Skip to content

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.json
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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>>();
+ });
+});