@wenathlan/cadria 2.0.88 → 2.0.93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/cadria",
-  "version": "2.0.88",
+  "version": "2.0.93",
   "repository": {
     "type": "git",
     "url": "https://github.com/wenathlan/devthink"

package/tests/blendmodes.test.ts

@@ -0,0 +1,93 @@
+// # blendmodes.test — the separable blend formulas of the compositing
+// standard over the 0-1 and 0-255 domains, the non-separable luminance
+// modes and the W3C alpha composite, runnable with the node built-in
+// runner (no dependencies, no install):
+//   node --test tests/blendmodes.test.ts
+// Every test watches the two invariants the module promises: the channel
+// formulas match the published equations exactly and clamped inputs
+// never throw — damaged input answers the clamped or source value.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  alphacomposite,
+  blendchannel,
+  blendchannel01,
+  blendpixel,
+  blendrgb,
+  blendrgb01,
+  isseparable,
+  lumaof,
+} from "../blendmodes.ts";
+
+describe("blendmodes", () => {
+  it("answers the exact separable formulas in the 0-1 domain", () => {
+    assert.equal(blendchannel01("multiply", 0.5, 0.5), 0.25);
+    assert.ok(Math.abs(blendchannel01("screen", 0.5, 0.5) - 0.75) < 1e-12);
+    assert.equal(blendchannel01("difference", 0.8, 0.3), 0.5);
+    assert.ok(Math.abs(blendchannel01("exclusion", 0.5, 0.4) - 0.5) < 1e-12);
+    assert.equal(blendchannel01("darken", 0.7, 0.2), 0.2);
+    assert.equal(blendchannel01("lighten", 0.7, 0.2), 0.7);
+    assert.equal(blendchannel01("normal", 0.3, 0.9), 0.9);
+  });
+
+  it("answers the dodge and burn edge cases of the published equations", () => {
+    assert.equal(blendchannel01("colordodge", 0.5, 0.5), 1);
+    assert.equal(blendchannel01("colordodge", 0, 0.5), 0);
+    assert.equal(blendchannel01("colordodge", 0.25, 1), 1);
+    assert.equal(blendchannel01("colorburn", 0.5, 0.5), 0);
+    assert.equal(blendchannel01("colorburn", 1, 0.5), 1);
+    assert.equal(blendchannel01("colorburn", 0.5, 0), 0);
+  });
+
+  it("clamps damaged inputs instead of throwing", () => {
+    assert.equal(blendchannel01("multiply", 2, -1), 0);
+    assert.equal(blendchannel01("multiply", 5, 5), 1);
+    assert.ok(Number.isNaN(blendchannel01("multiply", Number.NaN, 0.5)));
+    assert.equal(blendchannel("multiply", Number.NaN, 128), 0);
+  });
+
+  it("rounds the 0-255 channel form of the same formulas", () => {
+    assert.equal(blendchannel("multiply", 255, 255), 255);
+    assert.equal(blendchannel("multiply", 128, 0), 0);
+    assert.equal(blendchannel("normal", 10, 200), 200);
+    assert.equal(blendchannel("screen", 128, 128), 192);
+    assert.equal(blendchannel("multiply", 128, 128), 64);
+  });
+
+  it("blends rgb triples per channel in both domains", () => {
+    assert.deepEqual(blendrgb01("multiply", [0.2, 0.4, 0.6], [0.5, 0.5, 0.5]), [0.1, 0.2, 0.3]);
+    assert.deepEqual(blendrgb("screen", [0, 0, 0], [255, 255, 255]), [255, 255, 255]);
+    assert.deepEqual(blendrgb("multiply", [255, 128, 0], [255, 128, 0]), [255, 64, 0]);
+  });
+
+  it("separates the separable modes from the luminance modes", () => {
+    assert.equal(isseparable("multiply"), true);
+    assert.equal(isseparable("softlight"), true);
+    assert.equal(isseparable("hue"), false);
+    assert.equal(isseparable("luminosity"), false);
+  });
+
+  it("keeps the classic luma weights of the compositing standard", () => {
+    assert.ok(Math.abs(lumaof([1, 0, 0]) - 0.3) < 1e-12);
+    assert.ok(Math.abs(lumaof([0, 1, 0]) - 0.59) < 1e-12);
+    assert.ok(Math.abs(lumaof([0, 0, 1]) - 0.11) < 1e-12);
+    assert.ok(Math.abs(lumaof([1, 1, 1]) - 1) < 1e-12);
+  });
+
+  it("composites with the W3C alpha weighting", () => {
+    const opaque = alphacomposite([1, 0, 0], [0, 1, 0], [0, 0, 1], 1, 1);
+    assert.ok(Math.abs(opaque.alpha - 1) < 1e-12);
+    assert.deepEqual(opaque.color, [1, 0, 0]);
+    const transparent = alphacomposite([1, 0, 0], [0, 1, 0], [0, 0, 1], 0, 1);
+    assert.ok(Math.abs(transparent.alpha - 1) < 1e-12);
+    assert.deepEqual(transparent.color, [0, 0, 1]);
+    const empty = alphacomposite([1, 0, 0], [0, 1, 0], [0, 0, 1], 0, 0);
+    assert.equal(empty.alpha, 0);
+    assert.deepEqual(empty.color, [0, 0, 0]);
+  });
+
+  it("blends one pixel under per-layer alpha", () => {
+    assert.deepEqual(blendpixel("multiply", [200, 200, 200], [100, 100, 100]), [78, 78, 78]);
+    assert.deepEqual(blendpixel("normal", [200, 200, 200], [10, 20, 30]), [10, 20, 30]);
+  });
+});

package/tests/colorconvert.test.ts

@@ -0,0 +1,124 @@
+// # colorconvert.test — the color space conversions of the studio: the
+// sRGB transfer curve through the decode table, the HSL and HSV cylinders,
+// the OKLab and OKLCH spheres, the studio-swing YCbCr families and the
+// hex round trip, runnable with the node built-in runner (no dependencies,
+// no install):
+//   node --test tests/colorconvert.test.ts
+// Every test watches the two invariants the module promises: conversions
+// round trip inside one byte of drift and clamped or damaged input never
+// throws — the channel clamp answers the nearest legal byte.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  clamp01,
+  clamprgb,
+  hexfromrgb,
+  hsltorgb,
+  hsvtorgb,
+  lineartosrgb,
+  mixrgb,
+  oklabfromrgb,
+  relativeluma601,
+  relativeluma709,
+  rgbfromhex,
+  rgbfromoklab,
+  rgbfromycbcr,
+  rgbtohsl,
+  rgbtohsv,
+  srgbtolinear,
+  YCBCR_601,
+  YCBCR_709,
+  ycbcrfromrgb,
+} from "../colorconvert.ts";
+
+describe("colorconvert", () => {
+  it("clamps to the legal ranges without throwing", () => {
+    assert.equal(clamp01(2), 1);
+    assert.equal(clamp01(-1), 0);
+    assert.equal(clamp01(0.5), 0.5);
+    assert.deepEqual(clamprgb([300, -5, 128]), [255, 0, 128]);
+  });
+
+  it("rides the sRGB transfer curve through the decode table", () => {
+    assert.equal(srgbtolinear(0), 0);
+    assert.equal(srgbtolinear(255), 1);
+    assert.ok(Math.abs(srgbtolinear(128) - 0.2158) < 0.002);
+    assert.equal(lineartosrgb(0), 0);
+    assert.equal(lineartosrgb(1), 255);
+    assert.ok(Math.abs(lineartosrgb(0.5) - 188) < 2);
+    assert.ok(Math.abs(lineartosrgb(srgbtolinear(128)) - 128) <= 1);
+    assert.equal(srgbtolinear(Number.NaN), 0);
+  });
+
+  it("converts the red primary across the HSL cylinder", () => {
+    const red = rgbtohsl(255, 0, 0);
+    assert.equal(red.h, 0);
+    assert.equal(red.s, 1);
+    assert.equal(red.l, 0.5);
+    assert.deepEqual(hsltorgb(0, 1, 0.5), [255, 0, 0]);
+    assert.deepEqual(hsltorgb(120, 1, 0.5), [0, 255, 0]);
+    assert.deepEqual(hsltorgb(240, 1, 0.5), [0, 0, 255]);
+    const gray = rgbtohsl(128, 128, 128);
+    assert.equal(gray.s, 0);
+  });
+
+  it("converts the red primary across the HSV cylinder", () => {
+    assert.deepEqual(rgbtohsv(255, 0, 0), { h: 0, s: 1, v: 1 });
+    assert.deepEqual(hsvtorgb(120, 1, 1), [0, 255, 0]);
+    assert.deepEqual(hsvtorgb(0, 0, 1), [255, 255, 255]);
+    assert.deepEqual(hsvtorgb(0, 1, 0), [0, 0, 0]);
+  });
+
+  it("round trips OKLab inside a small drift", () => {
+    const lab = oklabfromrgb(255, 128, 0);
+    assert.ok(lab.l > 0.5 && lab.l < 0.9);
+    const back = rgbfromoklab(lab.l, lab.a, lab.b);
+    assert.ok(Math.abs(back[0] - 255) <= 2);
+    assert.ok(Math.abs(back[1] - 128) <= 2);
+    assert.ok(Math.abs(back[2] - 0) <= 2);
+  });
+
+  it("maps the studio-swing YCbCr of the 601 family", () => {
+    const red = ycbcrfromrgb(255, 0, 0, YCBCR_601);
+    assert.equal(red.y, 81);
+    assert.equal(red.cb, 90);
+    assert.equal(red.cr, 240);
+    const green = ycbcrfromrgb(0, 255, 0, YCBCR_601);
+    assert.equal(green.y, 145);
+    assert.equal(green.cr, 34);
+    const white = ycbcrfromrgb(255, 255, 255, YCBCR_601);
+    assert.equal(white.y, 235);
+    assert.equal(white.cb, 128);
+    assert.equal(white.cr, 128);
+  });
+
+  it("round trips YCbCr back into the byte cube", () => {
+    const forward = ycbcrfromrgb(60, 120, 200, YCBCR_601);
+    const back = rgbfromycbcr(forward.y, forward.cb, forward.cr, YCBCR_601);
+    assert.ok(Math.abs(back[0] - 60) <= 2);
+    assert.ok(Math.abs(back[1] - 120) <= 2);
+    assert.ok(Math.abs(back[2] - 200) <= 2);
+  });
+
+  it("declares the 709 coefficients beside the 601 family", () => {
+    assert.ok(Math.abs(YCBCR_709.kr - 0.2126) < 1e-12);
+    assert.ok(Math.abs(YCBCR_709.kb - 0.0722) < 1e-12);
+    assert.ok(Math.abs(relativeluma709(0, 255, 0) - 0.7152) < 0.001);
+    assert.equal(relativeluma601(0, 0, 0), 0);
+    assert.ok(Math.abs(relativeluma601(255, 255, 255) - 1) < 1e-9);
+  });
+
+  it("parses and renders the hex form", () => {
+    assert.equal(hexfromrgb([255, 0, 0]), "#ff0000");
+    assert.equal(hexfromrgb([16, 32, 64]), "#102040");
+    assert.deepEqual(rgbfromhex("#102040"), [16, 32, 64]);
+    assert.equal(rgbfromhex("not a color"), null);
+  });
+
+  it("mixes two colors along the gamma-aware path", () => {
+    const mid = mixrgb([0, 0, 0], [255, 255, 255], 0.5);
+    assert.deepEqual(mid, [99, 99, 99]);
+    const clamped = mixrgb([0, 0, 0], [255, 0, 0], 2);
+    assert.deepEqual(clamped, [255, 0, 0]);
+  });
+});

package/tests/easecurves.test.ts

@@ -0,0 +1,113 @@
+// # easecurves.test — the influence and speed easing model: the handle
+// algebra of the presets, the cubic bezier solver, the linear detection
+// and the key track evaluation with hold segments, runnable with the
+// node built-in runner (no dependencies, no install):
+//   node --test tests/easecurves.test.ts
+// Every test watches the two invariants the module promises: the linear
+// preset answers the identity of its parameter and damaged curves or
+// times answer null or the nearest key instead of throwing.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  bezierprogress,
+  curvefromhandles,
+  curvehandles,
+  curveprogress,
+  EASE_INOUT,
+  EASE_LINEAR,
+  type EaseKey,
+  evaluatekeys,
+  evaluatesegment,
+  islinearcurve,
+  samplecurve,
+  sanitizecurve,
+  timeatprogress,
+} from "../easecurves.ts";
+
+describe("easecurves", () => {
+  it("renders the linear preset as the identity handles", () => {
+    const handles = curvehandles(EASE_LINEAR);
+    assert.ok(Math.abs(handles[0] - 1 / 3) < 1e-9);
+    assert.ok(Math.abs(handles[1] - 1 / 3) < 1e-9);
+    assert.ok(Math.abs(handles[2] - 2 / 3) < 1e-9);
+    assert.ok(Math.abs(handles[3] - 2 / 3) < 1e-9);
+    assert.equal(islinearcurve(EASE_LINEAR), true);
+    assert.equal(islinearcurve(EASE_INOUT), false);
+  });
+
+  it("rebuilds the curve from the handles of the preset", () => {
+    const rebuilt = curvefromhandles(curvehandles(EASE_LINEAR));
+    assert.ok(rebuilt !== null);
+    assert.equal(islinearcurve(rebuilt as NonNullable<typeof rebuilt>), true);
+    assert.equal(curvefromhandles([Number.NaN, 0, 1, 1]), null);
+  });
+
+  it("solves the degenerate linear bezier as the identity", () => {
+    assert.ok(Math.abs(bezierprogress(0, 0, 1, 1, 0) - 0) < 1e-9);
+    assert.ok(Math.abs(bezierprogress(0, 0, 1, 1, 0.5) - 0.5) < 1e-9);
+    assert.ok(Math.abs(bezierprogress(0, 0, 1, 1, 1) - 1) < 1e-9);
+  });
+
+  it("answers the parameter of the linear preset along the progress", () => {
+    assert.ok(Math.abs((curveprogress(EASE_LINEAR, 0.25) as number) - 0.25) < 0.02);
+    assert.ok(Math.abs((curveprogress(EASE_LINEAR, 0.75) as number) - 0.75) < 0.02);
+    assert.ok(Math.abs((curveprogress(EASE_INOUT, 0.5) as number) - 0.5) < 0.01);
+    assert.equal(curveprogress(EASE_LINEAR, Number.NaN), 0);
+  });
+
+  it("inverts the progress of the linear preset back into time", () => {
+    assert.ok(Math.abs((timeatprogress(EASE_LINEAR, 0.5) as number) - 0.5) < 0.02);
+    assert.ok(Math.abs(timeatprogress(EASE_LINEAR, Number.NaN) as number) < 0.001);
+  });
+
+  it("samples the linear preset across the unit range", () => {
+    const samples = samplecurve(EASE_LINEAR, 4) as number[];
+    const expected = [0, 0.25, 0.5, 0.75, 1];
+    assert.equal(samples.length, 5);
+    for (let i = 0; i < expected.length; i += 1) assert.ok(Math.abs(samples[i] - expected[i]) < 0.02, `sample ${i}`);
+    assert.equal(samplecurve(EASE_LINEAR, 0), null);
+  });
+
+  it("evaluates the key track with linear segments and edge clamps", () => {
+    const keys: EaseKey[] = [
+      { time: 0, value: 0 },
+      { time: 10, value: 100 },
+    ];
+    assert.ok(Math.abs((evaluatekeys(keys, 5) as number) - 50) < 0.5);
+    assert.equal(evaluatekeys(keys, -1), 0);
+    assert.equal(evaluatekeys(keys, 11), 100);
+    assert.equal(evaluatekeys([], 5), null);
+    assert.equal(evaluatekeys(keys, Number.NaN), null);
+  });
+
+  it("holds the value of a hold segment until the next key", () => {
+    const keys: EaseKey[] = [
+      { time: 0, value: 1, holdOut: true },
+      { time: 10, value: 2 },
+    ];
+    assert.equal(evaluatekeys(keys, 5), 1);
+    assert.equal(evaluatekeys(keys, 10), 2);
+  });
+
+  it("evaluates one segment through the bezier of its curves", () => {
+    const value = evaluatesegment({ time: 0, value: 0 }, { time: 1, value: 10 }, 0.5);
+    assert.ok(Math.abs(value - 5) < 0.3);
+    const held = evaluatesegment({ time: 0, value: 3, holdOut: true }, { time: 1, value: 9 }, 0.5);
+    assert.equal(held, 3);
+  });
+
+  it("sanitizes curves into the legal ranges", () => {
+    const clean = sanitizecurve(EASE_LINEAR);
+    assert.ok(clean !== null);
+    assert.ok(Math.abs((clean as NonNullable<typeof clean>).outInfluence - 100 / 3) < 1e-9);
+    assert.equal(
+      sanitizecurve({
+        outInfluence: Number.NaN,
+        outSpeed: 1,
+        inInfluence: 100 / 3,
+        inSpeed: 1,
+      }),
+      null,
+    );
+  });
+});

package/tests/masks.test.ts

@@ -0,0 +1,127 @@
+// # masks.test — the mask plane algebra of the studio: the grid builders,
+// the add, subtract and intersect combination, the inversion, threshold
+// and boolean bridges, the bounds, the crop and the shape generators,
+// runnable with the node built-in runner (no dependencies, no install):
+//   node --test tests/masks.test.ts
+// Every test watches the two invariants the module promises: the ops
+// fold planes cell by cell with clamped values and mismatched or empty
+// input answers null or the empty plane instead of throwing.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  alphatoboolean,
+  booleantoalpha,
+  combinemasks,
+  cropmask,
+  ellipsemask,
+  invertmask,
+  makeboolean,
+  makeopacity,
+  maskbounds,
+  maskcoverage,
+  maskstack,
+  rectmask,
+  thresholdmask,
+} from "../masks.ts";
+
+describe("masks", () => {
+  it("builds opacity and boolean grids with clamped fills", () => {
+    const plane = makeopacity(2, 3, 1);
+    assert.equal(plane.width, 2);
+    assert.equal(plane.height, 3);
+    assert.equal(plane.data.length, 6);
+    for (const value of plane.data) assert.equal(value, 1);
+    const hot = makeopacity(2, 2, 5);
+    for (const value of hot.data) assert.equal(value, 1);
+    const bits = makeboolean(3, 2, 7);
+    assert.equal(bits.data.length, 6);
+    for (const value of bits.data) assert.equal(value, 1);
+    const off = makeboolean(2, 2, 0);
+    for (const value of off.data) assert.equal(value, 0);
+  });
+
+  it("combines planes with the add, subtract and intersect ops", () => {
+    const left = makeopacity(2, 1, 0);
+    left.data[0] = 1;
+    const right = makeopacity(2, 1, 0);
+    right.data[1] = 1;
+    const added = combinemasks(left, right, "add") as NonNullable<ReturnType<typeof combinemasks>>;
+    assert.equal(added.data[0], 1);
+    assert.equal(added.data[1], 1);
+    const full = makeopacity(2, 1, 1);
+    const cut = makeopacity(2, 1, 0);
+    cut.data[0] = 1;
+    const subtracted = combinemasks(full, cut, "subtract") as NonNullable<ReturnType<typeof combinemasks>>;
+    assert.equal(subtracted.data[0], 0);
+    assert.equal(subtracted.data[1], 1);
+    const half = makeopacity(2, 1, 0);
+    half.data[0] = 0.5;
+    const intersected = combinemasks(full, half, "intersect") as NonNullable<ReturnType<typeof combinemasks>>;
+    assert.ok(Math.abs(intersected.data[0] - 0.5) < 1e-6);
+    assert.equal(intersected.data[1], 0);
+    assert.equal(combinemasks(makeopacity(2, 1), makeopacity(3, 1), "add"), null);
+  });
+
+  it("inverts a plane cell by cell", () => {
+    const plane = makeopacity(2, 1, 0);
+    plane.data[0] = 0.2;
+    plane.data[1] = 0.8;
+    const flipped = invertmask(plane);
+    assert.ok(Math.abs(flipped.data[0] - 0.8) < 1e-6);
+    assert.ok(Math.abs(flipped.data[1] - 0.2) < 1e-6);
+  });
+
+  it("crops to the bounds of the painted rectangle", () => {
+    const rect = rectmask(4, 4, 1, 1, 2, 2);
+    assert.equal(maskcoverage(rect), 4 / 16);
+    const bounds = maskbounds(rect) as NonNullable<ReturnType<typeof maskbounds>>;
+    assert.equal(bounds.minX, 1);
+    assert.equal(bounds.minY, 1);
+    assert.equal(bounds.maxX, 2);
+    assert.equal(bounds.maxY, 2);
+    const cropped = cropmask(rect, bounds) as NonNullable<ReturnType<typeof cropmask>>;
+    assert.equal(cropped.width, 2);
+    assert.equal(cropped.height, 2);
+    for (const value of cropped.data) assert.equal(value, 1);
+    assert.equal(maskbounds(makeopacity(2, 2, 0)), null);
+    assert.equal(cropmask(rect, { minX: 3, minY: 3, maxX: 0, maxY: 0 }), null);
+  });
+
+  it("bridges the boolean and opacity domains through the threshold", () => {
+    const plane = makeopacity(2, 1, 0);
+    plane.data[0] = 0.9;
+    plane.data[1] = 0.1;
+    const bits = thresholdmask(plane);
+    assert.equal(bits.data[0], 1);
+    assert.equal(bits.data[1], 0);
+    const back = booleantoalpha(bits);
+    assert.equal(back.data[0], 1);
+    assert.equal(back.data[1], 0);
+    const again = alphatoboolean(back);
+    assert.equal(again.data[0], 1);
+    assert.equal(again.data[1], 0);
+  });
+
+  it("paints the rectangle and the ellipse shapes", () => {
+    const rect = rectmask(3, 3, 0, 0, 3, 3);
+    assert.equal(maskcoverage(rect), 1);
+    const partial = rectmask(3, 3, 1, 1, 1, 1);
+    assert.ok(Math.abs(maskcoverage(partial) - 1 / 9) < 1e-6);
+    const clipped = rectmask(3, 3, 2, 2, 8, 8);
+    assert.equal(maskcoverage(clipped), 1 / 9);
+    const disc = ellipsemask(5, 5, 2, 2, 2, 2);
+    assert.equal(disc.data[2 * 5 + 2], 1);
+    assert.equal(disc.data[0], 0);
+  });
+
+  it("folds the layer stack over the base plane", () => {
+    const base = makeopacity(2, 2, 0);
+    const layer = rectmask(2, 2, 0, 0, 1, 1);
+    const stacked = maskstack([{ grid: layer, op: "add" }], base) as NonNullable<ReturnType<typeof maskstack>>;
+    assert.equal(stacked.data[0], 1);
+    assert.equal(stacked.data[3], 0);
+    const alone = maskstack([{ grid: layer, op: "add" }]) as NonNullable<ReturnType<typeof maskstack>>;
+    assert.equal(alone.data[0], 1);
+    assert.equal(maskstack([]), null);
+  });
+});

package/tests/timelineedit.test.ts

@@ -0,0 +1,212 @@
+// # timelineedit.test — the editing algebra of the timeline: the
+// overwrite, insert, lift and extract spans, the split with the fresh
+// right id, the trims with handles and neighbours, the roll, slip,
+// slide and rate stretch, runnable with the node built-in runner (no
+// dependencies, no install):
+//   node --test tests/timelineedit.test.ts
+// Every test watches the two invariants the module promises: edits
+// never throw — every refusal rides the outcome type — and the media
+// window of a piece only moves through the source in point its speed
+// computes.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  type EditItem,
+  type EditTrack,
+  extract,
+  insert,
+  itemat,
+  itemend,
+  lift,
+  overwrite,
+  ratestretch,
+  roll,
+  shapeof,
+  slide,
+  slip,
+  sorttrack,
+  split,
+  syncconflict,
+  trackof,
+  trim,
+} from "../timelineedit.ts";
+
+function item(id: number, start: number, duration: number, sourceIn = 0, speed = 1): EditItem {
+  return { id, start, duration, sourceIn, speed };
+}
+
+function track(items: EditItem[]): EditTrack {
+  return { id: 1, locked: false, syncLock: false, items };
+}
+
+describe("timelineedit", () => {
+  it("answers the exclusive end and the item under a tick", () => {
+    const one = item(1, 10, 5);
+    assert.equal(itemend(one), 15);
+    const trk = track([one, item(2, 0, 5)]);
+    assert.equal(itemat(trk, 12)?.id, 1);
+    assert.equal(itemat(trk, 5), null);
+    assert.equal(itemat(trk, 4)?.id, 2);
+  });
+
+  it("sorts a track by start and then id", () => {
+    const trk = sorttrack(track([item(2, 10, 5), item(1, 0, 5), item(3, 10, 5)]));
+    assert.deepEqual(
+      trk.items.map((it) => it.id),
+      [1, 2, 3],
+    );
+  });
+
+  it("detects the sync-lock conflict of a range", () => {
+    const trk = track([item(1, 0, 10)]);
+    assert.equal(syncconflict(trk, { start: 5, duration: 2 }), true);
+    assert.equal(syncconflict(trk, { start: 10, duration: 2 }), false);
+  });
+
+  it("overwrites the covered span and trims the partials", () => {
+    const trk = track([item(1, 0, 10, 0), item(2, 10, 10, 0)]);
+    const done = overwrite(trk, item(3, 5, 10, 100));
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    const left = done.value.items.find((it) => it.id === 1) as EditItem;
+    const right = done.value.items.find((it) => it.id === 2) as EditItem;
+    assert.equal(left.duration, 5);
+    assert.equal(right.start, 15);
+    assert.equal(right.duration, 5);
+    assert.equal(right.sourceIn, 5);
+    assert.ok(done.value.items.some((it) => it.id === 3));
+  });
+
+  it("inserts at the in point and pushes the rest right", () => {
+    const trk = track([item(1, 0, 10, 0)]);
+    const done = insert(trk, item(2, 5, 4, 50));
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    assert.equal(done.value.items.length, 3);
+    const head = done.value.items.find((it) => it.start === 0) as EditItem;
+    assert.equal(head.duration, 5);
+    const tail = done.value.items.find((it) => it.start === 9) as EditItem;
+    assert.equal(tail.duration, 5);
+    assert.equal(tail.sourceIn, 5);
+    const fresh = done.value.items.find((it) => it.id === 2) as EditItem;
+    assert.equal(fresh.start, 5);
+  });
+
+  it("lifts the span and keeps the gap", () => {
+    const trk = track([item(1, 0, 10, 0), item(2, 10, 10, 0)]);
+    const done = lift(trk, { start: 8, duration: 4 });
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    assert.equal(done.value.items.length, 2);
+    assert.equal(done.value.items[0].duration, 8);
+    assert.equal(done.value.items[1].start, 12);
+    assert.equal(done.value.items[1].duration, 8);
+    assert.equal(done.value.items[1].sourceIn, 2);
+    assert.equal(lift(trk, { start: 50, duration: 4 }).ok, false);
+  });
+
+  it("extracts the span and closes the gap", () => {
+    const trk = track([item(1, 0, 10, 0), item(2, 10, 10, 0)]);
+    const done = extract(trk, { start: 8, duration: 4 });
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    assert.equal(done.value.items[1].start, 8);
+    assert.equal(done.value.items[1].duration, 8);
+  });
+
+  it("splits the containing item with a fresh right id", () => {
+    const trk = track([item(1, 0, 10, 0, 2)]);
+    const done = split(trk, 6);
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    assert.equal(done.value.track.items.length, 2);
+    assert.equal(done.value.track.items[0].duration, 6);
+    const right = done.value.track.items[1];
+    assert.equal(right.start, 6);
+    assert.equal(right.duration, 4);
+    assert.equal(right.sourceIn, 12);
+    assert.equal(right.speed, 2);
+    assert.equal(done.value.rightId, 2);
+    assert.equal(split(trk, 20).ok, false);
+  });
+
+  it("trims the in edge across the media handles", () => {
+    const trk = track([item(1, 0, 10, 20)]);
+    const done = trim(trk, 1, "in", 2, { mediaStart: 0 });
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    const moved = done.value.items[0];
+    assert.equal(moved.start, 2);
+    assert.equal(moved.duration, 8);
+    assert.equal(moved.sourceIn, 22);
+    assert.equal(trim(trk, 1, "in", 30, { mediaStart: 0 }).ok, false);
+    assert.equal(trim(trk, 1, "in", 0).ok, false);
+  });
+
+  it("trims the out edge against the media duration", () => {
+    const trk = track([item(1, 0, 10, 0, 1)]);
+    const done = trim(trk, 1, "out", 5, { mediaStart: 0, mediaDuration: 20 });
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    assert.equal(done.value.items[0].duration, 15);
+    assert.equal(trim(trk, 1, "out", 5, { mediaStart: 0, mediaDuration: 12 }).ok, false);
+  });
+
+  it("rolls the cut between two joined items", () => {
+    const trk = track([item(1, 0, 10, 0), item(2, 10, 10, 0)]);
+    const done = roll(trk, 1, 3);
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    const left = done.value.items.find((it) => it.id === 1) as EditItem;
+    const right = done.value.items.find((it) => it.id === 2) as EditItem;
+    assert.equal(left.duration, 13);
+    assert.equal(right.start, 13);
+    assert.equal(right.duration, 7);
+    assert.equal(right.sourceIn, 3);
+    assert.equal(roll(trk, 1, 0).ok, false);
+  });
+
+  it("slips the media window without moving the span", () => {
+    const trk = track([item(1, 0, 10, 20)]);
+    const done = slip(trk, 1, 5);
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    assert.equal(done.value.items[0].start, 0);
+    assert.equal(done.value.items[0].duration, 10);
+    assert.equal(done.value.items[0].sourceIn, 25);
+    assert.equal(slip(trk, 1, -30, { mediaStart: 0 }).ok, false);
+  });
+
+  it("slides the item between its neighbours", () => {
+    const trk = track([item(1, 0, 5, 0), item(2, 10, 5, 0), item(3, 20, 5, 0)]);
+    const done = slide(trk, 2, 3);
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    assert.equal(done.value.items[1].start, 13);
+    assert.equal(slide(trk, 2, 6).ok, false);
+    assert.equal(slide(trk, 2, -8).ok, false);
+  });
+
+  it("rate stretches the item over a new duration", () => {
+    const trk = track([item(1, 0, 10, 0, 1)]);
+    const done = ratestretch(trk, 1, 20);
+    assert.ok(done.ok);
+    if (!done.ok) return;
+    assert.equal(done.value.items[0].duration, 20);
+    assert.equal(done.value.items[0].speed, 0.5);
+    const back = ratestretch(done.value, 1, 5);
+    assert.ok(back.ok);
+    if (!back.ok) return;
+    assert.equal(back.value.items[0].speed, 2);
+    assert.equal(ratestretch(trk, 1, 0, { minDuration: 1 }).ok, false);
+  });
+
+  it("refuses every edit on a locked track", () => {
+    const trk = track([item(1, 0, 10)]);
+    trk.locked = true;
+    assert.equal(overwrite(trk, item(2, 0, 5)).ok, false);
+    assert.equal(insert(trk, item(2, 0, 5)).ok, false);
+    assert.equal(lift(trk, { start: 0, duration: 5 }).ok, false);
+    assert.equal(split(trk, 5).ok, false);
+  });
+});

package/tests/timeticks.test.ts

@@ -0,0 +1,127 @@
+// # timeticks.test — exact tick time: frame-rate math, sample clocks, the
+// rational container conversions and SMPTE drop-frame timecode, runnable with
+// the node built-in runner (no dependencies, no install):
+//   node --test tests/timeticks.test.ts
+// Every test watches the two invariants the module promises: conversions are
+// exact inside the safe-integer range (no float drift) and nothing ever
+// throws — damaged input answers the default or null.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  addticks,
+  clampticks,
+  formattimecode,
+  frameat,
+  frameduration,
+  framelabel,
+  framerate,
+  frameratefromf64,
+  framestofields,
+  makerange,
+  parsetimecode,
+  rangeintersect,
+  rangeoverlaps,
+  scaleticks,
+  snaptick,
+  subticks,
+  TICKS_PER_SECOND,
+  tickofframe,
+  ticksfromrational,
+  ticksfromseconds,
+  ticksfromunits,
+  tickstorationalround,
+  tickstoseconds,
+  tickstounitsfloor,
+  timecodeparams,
+} from "../timeticks.ts";
+
+const R24 = { num: 24, den: 1 };
+const R2997 = { num: 30000, den: 1001 };
+
+describe("timeticks rates", () => {
+  it("keeps the tick rate and exact frame durations", () => {
+    assert.equal(TICKS_PER_SECOND, 254016000000);
+    assert.equal(frameduration(R24), 10584000000);
+    assert.equal(frameduration({ num: 24000, den: 1001 }), 10594584000);
+  });
+  it("reduces rational rates and falls back to the default on damaged input", () => {
+    assert.deepEqual(framerate(24, 48), { num: 1, den: 2 });
+    assert.deepEqual(framerate(0, 10), { num: 24000, den: 1001 });
+    assert.equal(framelabel({ num: 24000, den: 1001 }), "23.976");
+    assert.equal(framelabel({ num: 25, den: 1 }), "25");
+  });
+  it("matches the closest standard rate for a container average", () => {
+    assert.deepEqual(frameratefromf64(29.97), R2997);
+    assert.deepEqual(frameratefromf64(23.976), { num: 24000, den: 1001 });
+    assert.deepEqual(frameratefromf64(23.5), { num: 47, den: 2 });
+  });
+});
+
+describe("timeticks frame math", () => {
+  it("floors frames and answers exact frame starts", () => {
+    assert.equal(frameat(R24, frameduration(R24) + 1), 1);
+    assert.equal(tickofframe(R24, 2), 2 * frameduration(R24));
+    assert.equal(frameat(R24, 0), 0);
+    assert.equal(tickofframe(R24, 0), 0);
+  });
+  it("snaps to floor, nearest and ceil boundaries", () => {
+    const t = frameduration(R24) + frameduration(R24) * 0.6;
+    assert.equal(snaptick(R24, t, "floor"), frameduration(R24));
+    assert.equal(snaptick(R24, t, "nearest"), 2 * frameduration(R24));
+    assert.equal(snaptick(R24, t, "ceil"), 2 * frameduration(R24));
+    assert.equal(snaptick(R24, frameduration(R24), "ceil"), frameduration(R24));
+  });
+});
+
+describe("timeticks conversions", () => {
+  it("converts seconds both ways", () => {
+    assert.equal(ticksfromseconds(1), TICKS_PER_SECOND);
+    assert.equal(tickstoseconds(TICKS_PER_SECOND), 1);
+    assert.equal(ticksfromseconds(1.5), 381024000000);
+  });
+  it("aligns audio samples without drift", () => {
+    assert.equal(ticksfromunits(48000, 48000), TICKS_PER_SECOND);
+    assert.equal(tickstounitsfloor(TICKS_PER_SECOND, 44100), 44100);
+    assert.equal(tickstounitsfloor(ticksfromunits(1000, 44100), 44100), 1000);
+  });
+  it("converts rational container timestamps exactly", () => {
+    assert.equal(ticksfromrational(1, 1, 1000), 254016000);
+    assert.equal(tickstorationalround(TICKS_PER_SECOND / 3, 1, 1000), 333);
+    assert.equal(tickstorationalround((TICKS_PER_SECOND * 2) / 3, 1, 1000), 667);
+    assert.equal(scaleticks(TICKS_PER_SECOND, 1, 2), TICKS_PER_SECOND / 2);
+  });
+  it("does the integer arithmetic with saturation and crossed-bound clamps", () => {
+    assert.equal(addticks(TICKS_PER_SECOND, 1), TICKS_PER_SECOND + 1);
+    assert.equal(subticks(10, 4), 6);
+    assert.equal(clampticks(5, 10, 20), 10);
+    assert.equal(clampticks(5, 20, 10), 20);
+  });
+});
+
+describe("timeticks timecode", () => {
+  it("applies the drop-frame skip on NTSC rates only", () => {
+    assert.equal(timecodeparams(R2997).dropCapable, true);
+    assert.equal(timecodeparams(R24).dropCapable, false);
+    assert.deepEqual(framestofields(1800, R2997, true), { neg: false, hours: 0, minutes: 1, seconds: 0, frames: 2 });
+    assert.deepEqual(framestofields(17982, R2997, true), { neg: false, hours: 0, minutes: 10, seconds: 0, frames: 0 });
+  });
+  it("formats and parses timecodes (round trip, drop separator, garbage)", () => {
+    const t = tickofframe(R24, 4320);
+    assert.equal(formattimecode(t, R24), "00:03:00:00");
+    assert.equal(formattimecode(tickofframe(R2997, 1800), R2997, true), "00:01:00;02");
+    assert.equal(parsetimecode("00:03:00:00", R24), t);
+    assert.equal(parsetimecode("nope", R24), null);
+    assert.equal(parsetimecode("00:00:00:30", R24), null);
+  });
+});
+
+describe("timeticks ranges", () => {
+  it("overlaps and intersects half-open ranges", () => {
+    const a = makerange(10, 5);
+    assert.equal(a.duration, 5);
+    assert.ok(rangeoverlaps(a, makerange(12, 10)));
+    assert.deepEqual(rangeintersect(a, makerange(12, 10)), { start: 12, duration: 3 });
+    assert.equal(rangeintersect(a, makerange(20, 5)), null);
+    assert.equal(makerange(0, -5).duration, 0);
+  });
+});