Code-first video & image, rendered natively on WebGPU.
feat(types): phase 1 branded primitives and strict interface cleanup
okanasl6da1d8bf0365
diff --git a/packages/core/package.json b/packages/core/package.jsonindex 04c7bc8b..8a27f7fc 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -24,6 +24,7 @@"scripts": {"build": "tsdown","typecheck": "tsc --noEmit",+ "test": "vitest run","dev": "tsdown --watch","clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist"},diff --git a/packages/core/src/types/brands.test.ts b/packages/core/src/types/brands.test.tsnew file mode 100644index 00000000..8c3c3a43--- /dev/null+++ b/packages/core/src/types/brands.test.ts@@ -0,0 +1,68 @@+import { describe, expect, it } from "vitest";+import {+ degrees,+ fps,+ frame,+ handleId,+ handleLabel,+ isFrameIndex,+ isNormalized,+ ms,+ nodeId,+ normalized,+ pixels,+ radians,+ seconds,+} from "./brands.js";++describe("Nominal Branded Types", () => {+ it("validates and constructs FrameIndex correctly", () => {+ expect(frame(0)).toBe(0);+ expect(frame(120)).toBe(120);+ expect(() => frame(-1)).toThrow(RangeError);+ expect(() => frame(1.5)).toThrow(RangeError);+ expect(() => frame(Number.NaN)).toThrow(RangeError);+ expect(isFrameIndex(24)).toBe(true);+ expect(isFrameIndex(24.5)).toBe(false);+ expect(isFrameIndex(-5)).toBe(false);+ expect(isFrameIndex("24")).toBe(false);+ });++ it("validates and constructs time units", () => {+ expect(seconds(2.5)).toBe(2.5);+ expect(ms(1500)).toBe(1500);+ expect(fps(60)).toBe(60);+ expect(() => seconds(Number.NaN)).toThrow(TypeError);+ expect(() => ms(Number.POSITIVE_INFINITY)).toThrow(TypeError);+ expect(() => fps(0)).toThrow(RangeError);+ expect(() => fps(-30)).toThrow(RangeError);+ });++ it("validates and constructs normalized range", () => {+ expect(normalized(0.5)).toBe(0.5);+ expect(normalized(-0.2)).toBe(0);+ expect(normalized(1.5)).toBe(1);+ expect(isNormalized(0.75)).toBe(true);+ expect(isNormalized(-0.1)).toBe(false);+ expect(isNormalized(1.1)).toBe(false);+ expect(() => normalized(Number.NaN)).toThrow(TypeError);+ });++ it("validates angles and pixel dimensions", () => {+ expect(degrees(180)).toBe(180);+ expect(radians(Math.PI)).toBe(Math.PI);+ expect(pixels(1920)).toBe(1920);+ expect(() => degrees(Number.NaN)).toThrow(TypeError);+ expect(() => radians(Number.NaN)).toThrow(TypeError);+ expect(() => pixels(Number.NaN)).toThrow(TypeError);+ });++ it("validates identity and graph handle strings", () => {+ expect(handleId("input-video-1")).toBe("input-video-1");+ expect(handleLabel("Main Video")).toBe("Main Video");+ expect(nodeId("box-hero")).toBe("box-hero");+ expect(() => handleId("")).toThrow(TypeError);+ expect(() => handleLabel("")).toThrow(TypeError);+ expect(() => nodeId("")).toThrow(TypeError);+ });+});diff --git a/packages/core/src/types/brands.ts b/packages/core/src/types/brands.tsnew file mode 100644index 00000000..7de7b1db--- /dev/null+++ b/packages/core/src/types/brands.ts@@ -0,0 +1,144 @@+declare const BrandTag: unique symbol;++/**+ * Compile-time zero-cost nominal typing tag ("newtype" pattern).+ * Prevents accidental cross-assignment of semantically incompatible primitives+ * (e.g. milliseconds to seconds, handle labels to handle IDs, or fractional frames).+ */+export type Brand<T, B extends string> = T & { readonly [BrandTag]: B };++/** Timeline frame number (must be a non-negative integer). */+export type FrameIndex = Brand<number, "FrameIndex">;++/** Time in seconds. */+export type Seconds = Brand<number, "Seconds">;++/** Time in milliseconds. */+export type Milliseconds = Brand<number, "Milliseconds">;++/** Frame rate in frames per second. */+export type Fps = Brand<number, "Fps">;++/** Normalized scalar in the range [0.0, 1.0]. */+export type Normalized = Brand<number, "Normalized">;++/** Angle in degrees (0 to 360). */+export type Degrees = Brand<number, "Degrees">;++/** Angle in radians (0 to 2*PI). */+export type Radians = Brand<number, "Radians">;++/** Dimension in screen/canvas pixels. */+export type Pixels = Brand<number, "Pixels">;++/** Live compositor dynamic input/output handle identifier. */+export type HandleId = Brand<string, "HandleId">;++/** Human-readable handle label (distinct from HandleId to prevent runtime lookup failure). */+export type HandleLabel = Brand<string, "HandleLabel">;++/** Unique layout node identifier. */+export type NodeId = Brand<string, "NodeId">;++/** Asserts and casts a number to an integer FrameIndex. */+export function frame(n: number): FrameIndex {+ if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {+ throw new RangeError(+ `FrameIndex must be a non-negative finite integer, got ${n}`,+ );+ }+ return n as FrameIndex;+}++/** Asserts and casts a number to Seconds. */+export function seconds(s: number): Seconds {+ if (!Number.isFinite(s)) {+ throw new TypeError(`Seconds must be a finite number, got ${s}`);+ }+ return s as Seconds;+}++/** Asserts and casts a number to Milliseconds. */+export function ms(m: number): Milliseconds {+ if (!Number.isFinite(m)) {+ throw new TypeError(`Milliseconds must be a finite number, got ${m}`);+ }+ return m as Milliseconds;+}++/** Asserts and casts a number to Fps. */+export function fps(f: number): Fps {+ if (!Number.isFinite(f) || f <= 0) {+ throw new RangeError(`Fps must be a positive finite number, got ${f}`);+ }+ return f as Fps;+}++/** Clamps and casts a number to Normalized [0.0, 1.0]. */+export function normalized(n: number): Normalized {+ if (!Number.isFinite(n)) {+ throw new TypeError(`Normalized must be a finite number, got ${n}`);+ }+ const clamped = Math.max(0, Math.min(1, n));+ return clamped as Normalized;+}++/** Asserts and casts a number to Degrees. */+export function degrees(deg: number): Degrees {+ if (!Number.isFinite(deg)) {+ throw new TypeError(`Degrees must be a finite number, got ${deg}`);+ }+ return deg as Degrees;+}++/** Asserts and casts a number to Radians. */+export function radians(rad: number): Radians {+ if (!Number.isFinite(rad)) {+ throw new TypeError(`Radians must be a finite number, got ${rad}`);+ }+ return rad as Radians;+}++/** Asserts and casts a number to Pixels. */+export function pixels(px: number): Pixels {+ if (!Number.isFinite(px)) {+ throw new TypeError(`Pixels must be a finite number, got ${px}`);+ }+ return px as Pixels;+}++/** Casts a string to HandleId. */+export function handleId(id: string): HandleId {+ if (!id) {+ throw new TypeError("HandleId cannot be empty");+ }+ return id as HandleId;+}++/** Casts a string to HandleLabel. */+export function handleLabel(label: string): HandleLabel {+ if (!label) {+ throw new TypeError("HandleLabel cannot be empty");+ }+ return label as HandleLabel;+}++/** Casts a string to NodeId. */+export function nodeId(id: string): NodeId {+ if (!id) {+ throw new TypeError("NodeId cannot be empty");+ }+ return id as NodeId;+}++/** Type guard checking if a number is a valid FrameIndex. */+export function isFrameIndex(val: unknown): val is FrameIndex {+ return typeof val === "number" && Number.isInteger(val) && val >= 0;+}++/** Type guard checking if a number is in the Normalized [0, 1] range. */+export function isNormalized(val: unknown): val is Normalized {+ return (+ typeof val === "number" && Number.isFinite(val) && val >= 0 && val <= 1+ );+}diff --git a/packages/core/src/types/index.ts b/packages/core/src/types/index.tsindex 31769f81..1a3be901 100644--- a/packages/core/src/types/index.ts+++ b/packages/core/src/types/index.ts@@ -1,4 +1,5 @@export * from "./base.js";+export * from "./brands.js";export * from "./config/index.js";export * from "./constants.js";export * from "./node-processor.js";diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.tsindex 060ee7c0..2394c381 100644--- a/packages/framefields/src/index.ts+++ b/packages/framefields/src/index.ts@@ -218,6 +218,7 @@ import {type DeflickerProps,DepthOfField,type DepthOfFieldProps,+ type EffectProp,effectFactories,FilmGrain,type FilmGrainProps,@@ -282,22 +283,25 @@ export interface SectionOptions {readonly id?: string;readonly position?: "absolute" | "relative";readonly source?: string | MediaNode;- readonly effects?: unknown[];+ readonly effects?: Effect<object>[];readonly padding?: number;readonly borderRadius?: number;readonly borderColor?: string;readonly borderWidth?: number;- readonly opacity?: number | unknown;+ readonly opacity?: EffectProp<number>;readonly blendMode?: string;readonly fit?: "cover" | "contain";- readonly width?: number | unknown;- readonly height?: number | unknown;- readonly x?: number | unknown;- readonly y?: number | unknown;+ readonly width?: EffectProp<SizeSpec>;+ readonly height?: EffectProp<SizeSpec>;+ readonly compositionWidth?: number;+ readonly compositionHeight?: number;+ readonly compWidth?: number;+ readonly compHeight?: number;+ readonly x?: EffectProp<number>;+ readonly y?: EffectProp<number>;readonly hideWhenLost?: boolean;readonly smoothFrames?: number;readonly children?: LayoutNode[];- readonly [key: string]: unknown;}export type SectionNode = AnimatableNode<BoxNode> & {@@ -1166,12 +1170,12 @@ export class Composition {private readonly _clipVision = new Map<string, ClipVision>();private _visionConfig?: VisionProps;private _visionBundle?: VisionBundle;- private _effects: unknown[] = [];+ private _effects: Effect<object>[] = [];/*** Applies a whole-composition post-processing effect or vision pipeline.*/- public apply(effect: unknown): this {+ public apply(effect: Effect<object>): this {if (effect instanceof Vision) {this.withVision(effect);return this;@@ -2105,9 +2109,8 @@ export type AnimatableNode<T extends LayoutNode> = T & {vision?: Vision;relighting?: NormalRelightingOptions;deflicker?: DeflickerOptions;- effects?: unknown[];+ effects?: Effect<object>[];blurRegions?: unknown[];- [key: string]: unknown;animate(...anim: (| LayerAnimation@@ -2160,9 +2163,13 @@ export type AnimatableNode<T extends LayoutNode> = T & {withRelighting(options?: NormalRelightingOptions): AnimatableNode<T>;relight(options?: NormalRelightingOptions): AnimatableNode<T>;withDeflicker(options?: DeflickerOptions): AnimatableNode<T>;- apply(effect: unknown): AnimatableNode<T>;- withEffect(effect: unknown): AnimatableNode<T>;- withEffects(effects: unknown[]): AnimatableNode<T>;+ apply(effect: Effect<object>): AnimatableNode<T>;+ withEffect(effect: Effect<object>): AnimatableNode<T>;+ withEffects(effects: Effect<object>[]): AnimatableNode<T>;+ section(+ targetOrOptions?: ObjectTrackSignals | SectionOptions,+ options?: SectionOptions,+ ): SectionNode;blurRegion(trackTarget: ObjectTrackSignals,options?: Partial<BlurProps>,@@ -2357,7 +2364,7 @@ function withAnimation<T extends LayoutNode>(node: T): AnimatableNode<T> {});Object.defineProperty(target, "apply", {- value: (effect: unknown) => {+ value: (effect: Effect<object>) => {if (!target.effects) {target.effects = [];}@@ -2370,7 +2377,7 @@ function withAnimation<T extends LayoutNode>(node: T): AnimatableNode<T> {});Object.defineProperty(target, "withEffect", {- value: (effect: unknown) => {+ value: (effect: Effect<object>) => {if (!target.effects) {target.effects = [];}@@ -2383,7 +2390,7 @@ function withAnimation<T extends LayoutNode>(node: T): AnimatableNode<T> {});Object.defineProperty(target, "withEffects", {- value: (effects: unknown[]) => {+ value: (effects: Effect<object>[]) => {if (!target.effects) {target.effects = [];}diff --git a/packages/framefields/src/type-safety.test.ts b/packages/framefields/src/type-safety.test.tsnew file mode 100644index 00000000..6d587761--- /dev/null+++ b/packages/framefields/src/type-safety.test.ts@@ -0,0 +1,97 @@+import { describe, expect, expectTypeOf, it } from "vitest";+import {+ type AnimatableNode,+ type Fps,+ type FrameIndex,+ fps,+ frame,+ type HandleId,+ type HandleLabel,+ handleId,+ handleLabel,+ isFrameIndex,+ isNormalized,+ Layer,+ type MediaNode,+ type Milliseconds,+ ms,+ type NodeId,+ type Normalized,+ nodeId,+ normalized,+ type Seconds,+ type SectionOptions,+ seconds,+ Vignette,+} from "./index.js";++describe("Type Safety & Branded Types (Phase 1)", () => {+ it("re-exports all branded types and assertion helpers from core", () => {+ const f = frame(48);+ expect(f).toBe(48);+ expectTypeOf(f).toEqualTypeOf<FrameIndex>();++ const s = seconds(2.5);+ expect(s).toBe(2.5);+ expectTypeOf(s).toEqualTypeOf<Seconds>();++ const m = ms(100);+ expect(m).toBe(100);+ expectTypeOf(m).toEqualTypeOf<Milliseconds>();++ const rate = fps(30);+ expect(rate).toBe(30);+ expectTypeOf(rate).toEqualTypeOf<Fps>();++ const norm = normalized(0.8);+ expect(norm).toBe(0.8);+ expectTypeOf(norm).toEqualTypeOf<Normalized>();++ const hid = handleId("video-input-1");+ expect(hid).toBe("video-input-1");+ expectTypeOf(hid).toEqualTypeOf<HandleId>();++ const hlbl = handleLabel("Video Stream");+ expect(hlbl).toBe("Video Stream");+ expectTypeOf(hlbl).toEqualTypeOf<HandleLabel>();++ const nid = nodeId("hero-card");+ expect(nid).toBe("hero-card");+ expectTypeOf(nid).toEqualTypeOf<NodeId>();++ expect(isFrameIndex(10)).toBe(true);+ expect(isNormalized(0.5)).toBe(true);+ });++ it("enforces strict SectionOptions without unknown index signature", () => {+ const validOptions: SectionOptions = {+ id: "tracked-section",+ position: "absolute",+ padding: 10,+ opacity: 0.9,+ width: 1920,+ height: 1080,+ compositionWidth: 1920,+ compositionHeight: 1080,+ effects: [new Vignette({ strength: 20 })],+ };++ expect(validOptions.id).toBe("tracked-section");+ expect(validOptions.padding).toBe(10);++ type SectionOptionsKeys = keyof SectionOptions;+ expectTypeOf<"padding">().toMatchTypeOf<SectionOptionsKeys>();+ expectTypeOf<"opacity">().toMatchTypeOf<SectionOptionsKeys>();+ expectTypeOf<"effects">().toMatchTypeOf<SectionOptionsKeys>();+ expectTypeOf<"compositionWidth">().toMatchTypeOf<SectionOptionsKeys>();+ });++ it("preserves typed AnimatableNode without index signature", () => {+ const video = Layer.video("sample.mp4");+ expectTypeOf(video).toMatchTypeOf<AnimatableNode<MediaNode>>();++ // Verify apply method accepts typed Effect instances+ const withEff = video.apply(new Vignette({ strength: 10 }));+ expectTypeOf(withEff).toMatchTypeOf<AnimatableNode<MediaNode>>();+ });+});