sketchmark 2.0.0 → 2.1.1

package/dist/tests/run.js

@@ -3,8 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs = require("node:fs");
 const path = require("node:path");
 const src_1 = require("../src");
-const shapes_1 = require("../src/shapes");
-const builders_1 = require("../src/builders");
+const presets_1 = require("../src/presets");
 function test(name, fn) {
     try {
         fn();
@@ -16,629 +15,696 @@ function test(name, fn) {
         throw error;
     }
 }
-test("validates primitive geometry", () => {
+test("validates minimal render-kernel documents", () => {
     const doc = {
         version: 1,
-        canvas: { width: 400, height: 240 },
-        elements: [{ id: "card", type: "rect", x: 20, y: 30, width: 100, height: 60 }]
+        canvas: { width: 320, height: 180, background: "#ffffff" },
+        elements: [
+            { id: "line", type: "path", d: "M 20 120 L 300 40", stroke: "#111827", strokeWidth: 4 },
+            { id: "label", type: "text", text: "Kernel", x: 160, y: 90, align: "center", valign: "middle" },
+            { id: "pin", type: "point", x: 20, y: 120 }
+        ]
     };
     const result = (0, src_1.validateVisualDocument)(doc);
-    assert(result.ok, "document should be valid");
+    assert(result.ok, `document should validate: ${result.issues.map((item) => item.message).join("; ")}`);
 });
-test("rejects compound types in canonical JSON", () => {
+test("rejects non-kernel fields and types", () => {
     const doc = {
         version: 1,
-        canvas: { width: 400, height: 240 },
-        elements: [{ id: "bad", type: "node", label: "Browser", x: 0, y: 0, width: 100, height: 50 }]
+        canvas: { width: 320, height: 180, space: "3d", renderer: "three" },
+        elements: [
+            { id: "box", type: "rect", x: 20, y: 20, width: 80, height: 40 },
+            { id: "cube", type: "cuboid", position: [0, 0, 0], size: [1, 1, 1] }
+        ],
+        motion: { drivers: [] },
+        scenes: {},
+        imports: {},
+        assets: {},
+        exports: {}
     };
     const result = (0, src_1.validateVisualDocument)(doc);
     assert(!result.ok, "document should be invalid");
-    assert(result.issues.some((item) => item.code === "compound_type_not_allowed"), "should report compound type");
-});
-test("builders expand compounds into primitives", () => {
-    const items = [
-        ...(0, builders_1.node)({ id: "browser", label: "Browser", x: 120, y: 160, width: 180, height: 80 }),
-        ...(0, builders_1.node)({ id: "resolver", label: "DNS Resolver", x: 380, y: 160, width: 180, height: 80 }),
-        ...(0, builders_1.flow)({ id: "query", from: "browser_box.right", to: "resolver_box.left", label: "Query", labelX: 340, labelY: 145 }),
-        (0, builders_1.packet)({ id: "query_packet", on: "query", progress: (0, builders_1.animate)(0, 1, { duration: 1, delay: 1 }) }),
-        ...(0, builders_1.callout)({ id: "note", text: "Cached result", x: 520, y: 80, width: 140, height: 48, target: "resolver_box.top" })
-    ];
-    const compoundTypes = new Set(["node", "flow", "packet", "callout"]);
-    assert(items.every((item) => !compoundTypes.has(item.type)), "builders must return primitives");
+    assert(result.issues.some((item) => item.code === "non_kernel_field" && item.path === "/motion"), "motion should be rejected");
+    assert(result.issues.some((item) => item.code === "non_kernel_canvas_field" && item.path === "/canvas/space"), "3D canvas fields should be rejected");
+    assert(result.issues.some((item) => item.code === "unsupported_type" && item.path.endsWith("/type")), "non-kernel element types should be rejected");
 });
-test("compileCompounds is explicit and outputs primitives", () => {
-    const doc = (0, src_1.compileCompounds)({
-        version: 1,
-        canvas: { width: 640, height: 360 },
-        elements: [
-            { id: "browser", type: "node", label: "Browser", x: 80, y: 120, width: 160, height: 70 },
-            { id: "resolver", type: "node", label: "Resolver", x: 320, y: 120, width: 160, height: 70 },
-            { id: "query", type: "flow", from: "browser_box.right", to: "resolver_box.left", label: "Query", labelX: 280, labelY: 110 }
-        ]
-    });
-    const forbidden = new Set(["node", "flow"]);
-    assert(doc.elements?.every((item) => !forbidden.has(item.type)), "compiled document should contain only primitives");
-    assert((0, src_1.validateVisualDocument)(doc).ok, "compiled document should validate");
-});
-test("resolves references to numeric endpoints", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 640, height: 360 },
-        elements: [
-            { id: "left", type: "rect", x: 100, y: 100, width: 100, height: 60 },
-            { id: "right", type: "rect", x: 300, y: 100, width: 100, height: 60 },
-            { id: "arrow", type: "arrow", from: "left.right", to: "right.left", stroke: "#111827" }
-        ]
-    });
-    const normalized = (0, src_1.normalizeVisualDocument)(doc);
-    const arrow = normalized.elements.find((item) => item.id === "arrow");
-    assert(JSON.stringify(arrow.from) === JSON.stringify([200, 130]), "from should resolve to right edge");
-    assert(JSON.stringify(arrow.to) === JSON.stringify([300, 130]), "to should resolve to left edge");
-});
-test("animated x requires a static x", () => {
+test("rejects non-kernel fields on supported elements", () => {
     const doc = {
         version: 1,
-        canvas: { width: 400, height: 240 },
-        elements: [{ id: "label", type: "text", text: "Move", y: 40, animate: { x: (0, builders_1.animate)(0, 100, { duration: 1 }) } }]
+        canvas: { width: 320, height: 180 },
+        elements: [{ id: "old_line", type: "path", d: "M 0 0 L 10 10", from: [0, 0], to: [10, 10] }]
     };
     const result = (0, src_1.validateVisualDocument)(doc);
-    assert(!result.ok, "document should be invalid");
-    assert(result.issues.some((item) => item.code === "missing_static_animation_property"), "should require static animated property");
+    assert(!result.ok, "extra authoring fields should be invalid");
+    assert(result.issues.some((item) => item.code === "non_kernel_element_field" && item.path.endsWith("/from")), "should reject old element fields");
+});
+test("rejects project/editor metadata and image cornerRadius", () => {
+    const metadataDoc = {
+        version: 1,
+        canvas: { width: 320, height: 180 },
+        elements: [{ id: "dot", type: "point", x: 10, y: 10, metadata: { selected: true } }]
+    };
+    const metadata = (0, src_1.validateVisualDocument)(metadataDoc);
+    assert(!metadata.ok, "metadata should not be a kernel element field");
+    assert(metadata.issues.some((item) => item.code === "non_kernel_element_field" && item.path.endsWith("/metadata")), "metadata should be rejected");
+    const src = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='10'%3E%3C/svg%3E";
+    const roundedDoc = {
+        version: 1,
+        canvas: { width: 320, height: 180 },
+        elements: [{ id: "photo", type: "image", src, x: 20, y: 20, width: 80, height: 50, cornerRadius: 8 }]
+    };
+    const rounded = (0, src_1.validateVisualDocument)(roundedDoc);
+    assert(!rounded.ok, "image cornerRadius should not be a kernel field");
+    assert(rounded.issues.some((item) => item.code === "non_kernel_element_field" && item.path.endsWith("/cornerRadius")), "cornerRadius should be rejected");
+    const clipDoc = {
+        version: 1,
+        canvas: { width: 320, height: 180 },
+        elements: [{ id: "photo", type: "image", src, x: 20, y: 20, width: 80, height: 50, clip: (0, src_1.imageRoundedClip)({ x: 20, y: 20, width: 80, height: 50 }, 8) }]
+    };
+    assert((0, src_1.validateVisualDocument)(clipDoc).ok, "rounded image clips should compile through clip.d");
 });
-test("rejects raw keyframe arrays in animate", () => {
+test("renders path, text, image, and group to SVG and HTML", () => {
+    const src = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='10'%3E%3Crect width='10' height='10' fill='%232563eb'/%3E%3C/svg%3E";
     const doc = {
         version: 1,
-        canvas: { width: 400, height: 240, duration: 2 },
+        canvas: { width: 240, height: 140, background: "#f8fafc" },
         elements: [
             {
-                id: "dot",
-                type: "circle",
-                cx: 20,
-                cy: 40,
-                radius: 6,
-                animate: { cx: [[0, 20], [1, 120], [2, 20]] }
+                id: "card",
+                type: "group",
+                x: 20,
+                y: 20,
+                width: 200,
+                height: 100,
+                children: [
+                    { id: "panel", type: "path", d: "M 0 0 H 200 V 100 H 0 Z", fill: "#ffffff", stroke: "#cbd5e1" },
+                    { id: "photo", type: "image", src, x: 16, y: 16, width: 40, height: 40 },
+                    { id: "copy", type: "text", text: "Render kernel", x: 116, y: 38, align: "center", valign: "middle" }
+                ]
             }
         ]
     };
-    const result = (0, src_1.validateVisualDocument)(doc);
-    assert(!result.ok, "document should be invalid");
-    assert(result.issues.some((item) => item.code === "invalid_animation"), "should reject raw keyframe arrays");
+    const svg = (0, src_1.renderToSvg)(doc);
+    assert(svg.includes("<svg"), "should render SVG root");
+    assert(svg.includes("<path") && svg.includes("<image") && svg.includes("Render&#160;kernel"), "should render kernel elements");
+    assert(svg.includes('stroke-width="1"'), "path stroke should default to width 1 when stroke is set");
+    assert((0, src_1.renderToHtml)(doc).includes("Sketchmark Kernel Visual"), "should render HTML shell");
 });
-test("rejects effects arrays", () => {
+test("resolves element-local timeline tracks", () => {
     const doc = {
         version: 1,
-        canvas: { width: 400, height: 240 },
+        canvas: { width: 320, height: 180, duration: 3 },
         elements: [
             {
-                id: "sun",
-                type: "circle",
-                cx: 200,
-                cy: 120,
-                radius: 30,
-                effects: [{ type: "shadow", blur: 20, color: "#facc15" }]
+                id: "dot",
+                type: "point",
+                x: 0,
+                y: 0,
+                timeline: {
+                    start: 1,
+                    end: 3,
+                    tracks: {
+                        position: { keyframes: [[0, [20, 30]], [2, [120, 90]]], ease: "linear" },
+                        opacity: { keyframes: [[0, 0], [1, 1]] }
+                    }
+                }
+            },
+            {
+                id: "mark",
+                type: "path",
+                d: "M 10 10 L 30 10",
+                stroke: "#000000",
+                timeline: {
+                    tracks: {
+                        stroke: { keyframes: [[0, "#000000"], [2, "#ffffff"]], ease: "linear" }
+                    }
+                }
             }
         ]
     };
-    const result = (0, src_1.validateVisualDocument)(doc);
-    assert(!result.ok, "document should be invalid");
-    assert(result.issues.some((item) => item.code === "invalid_effects"), "should reject effects arrays");
-});
-test("rejects structured canvas backgrounds", () => {
+    assert((0, src_1.resolveVisualFrame)(doc, 0.5).elements.every((item) => item.id !== "dot"), "timeline start should hide early elements");
+    const mid = (0, src_1.resolveVisualFrame)(doc, 2);
+    const dot = mid.elements.find((item) => item.id === "dot");
+    const mark = mid.elements.find((item) => item.id === "mark");
+    assert(near(dot.x, 70) && near(dot.y, 60), `position should interpolate, got ${dot.x},${dot.y}`);
+    assert(dot.opacity === 1, "opacity should clamp after the last keyframe");
+    assert(mark.stroke === "#ffffff", `color should interpolate/clamp, got ${mark.stroke}`);
+    assert(!("timeline" in dot), "resolved frame should not keep timeline instructions");
+});
+test("resolves timeline interpolation graphs", () => {
     const doc = {
         version: 1,
-        canvas: {
-            width: 400,
-            height: 240,
-            background: {
-                type: "linearGradient",
-                from: [0, 0],
-                to: [0, 240],
-                stops: [[0, "#87ceeb"], [1, "#e8f4f8"]]
+        canvas: { width: 320, height: 180, duration: 1 },
+        elements: [
+            {
+                id: "graph",
+                type: "point",
+                x: 0,
+                y: 0,
+                timeline: {
+                    tracks: {
+                        position: {
+                            keyframes: [[0, [0, 0]], [1, [100, 0]]],
+                            curve: { type: "graph", points: [[0, 0], [0.5, 0], [1, 1]] }
+                        }
+                    }
+                }
+            },
+            {
+                id: "hold",
+                type: "point",
+                x: 0,
+                y: 20,
+                timeline: {
+                    tracks: {
+                        position: {
+                            keyframes: [[0, [0, 20]], [1, [100, 20]]],
+                            curve: { type: "hold" }
+                        }
+                    }
+                }
             }
-        },
-        elements: []
+        ]
     };
-    const result = (0, src_1.validateVisualDocument)(doc);
-    assert(!result.ok, "document should be invalid");
-    assert(result.issues.some((item) => item.code === "invalid_canvas_background"), "should reject structured canvas backgrounds");
-});
-test("long text warns without changing layout", () => {
+    const mid = (0, src_1.resolveVisualFrame)(doc, 0.5);
+    const graph = mid.elements.find((item) => item.id === "graph");
+    const hold = mid.elements.find((item) => item.id === "hold");
+    assert(near(graph.x, 0), `graph curve should map halfway time to zero progress, got ${graph.x}`);
+    assert(near(hold.x, 0), `hold curve should stay at previous value, got ${hold.x}`);
+    const late = (0, src_1.resolveVisualFrame)(doc, 0.75).elements.find((item) => item.id === "graph");
+    assert(near(late.x, 50), `graph curve should interpolate along normalized graph, got ${late.x}`);
+});
+test("resolves object keyframes and per-segment curves", () => {
     const doc = {
         version: 1,
-        canvas: { width: 400, height: 240 },
-        elements: [{ id: "label", type: "text", text: "This is a long label that should warn instead of resizing anything automatically", x: 20, y: 20 }]
-    };
-    const result = (0, src_1.validateVisualDocument)(doc);
-    assert(result.ok, "warning should not invalidate document");
-    assert(result.warnings.some((item) => item.code === "long_text_no_wrap"), "should warn for long text");
-});
-test("row and column builders position explicit primitive children", () => {
-    const rowItems = (0, builders_1.row)({
-        x: 10,
-        y: 20,
-        gap: 10,
-        children: [
-            (0, builders_1.node)({ id: "a", label: "A", x: 0, y: 0, width: 100, height: 40 }),
-            (0, builders_1.node)({ id: "b", label: "B", x: 0, y: 0, width: 100, height: 40 })
-        ]
-    });
-    const bBox = rowItems.find((item) => item.id === "b_box");
-    assert(bBox.x === 120 && bBox.y === 20, "row should move second box deterministically");
-    const columnItems = (0, builders_1.column)({
-        x: 10,
-        y: 20,
-        gap: 10,
-        children: [
-            (0, builders_1.node)({ id: "c", label: "C", x: 0, y: 0, width: 100, height: 40 }),
-            (0, builders_1.node)({ id: "d", label: "D", x: 0, y: 0, width: 100, height: 40 })
-        ]
-    });
-    const dBox = columnItems.find((item) => item.id === "d_box");
-    assert(dBox.x === 10 && dBox.y === 70, "column should move second box deterministically");
-});
-test("renders primitive SVG", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 320, height: 180, background: "#ffffff" },
+        canvas: { width: 320, height: 180, duration: 2 },
         elements: [
-            { id: "box", type: "rect", x: 20, y: 20, width: 100, height: 60, fill: "#ffffff", stroke: "#111827" },
-            { id: "label", type: "text", text: "Hello", x: 70, y: 50, align: "center", valign: "middle" }
+            {
+                id: "dot",
+                type: "point",
+                x: 0,
+                y: 0,
+                timeline: {
+                    tracks: {
+                        position: {
+                            curve: { type: "graph", points: [[0, 0], [1, 1]] },
+                            keyframes: [
+                                { time: 0, value: [0, 0], out: { type: "hold" } },
+                                { time: 1, value: [100, 0] },
+                                { time: 2, value: [200, 0] }
+                            ]
+                        }
+                    }
+                }
+            }
         ]
-    });
-    const svg = (0, src_1.renderToSvg)(doc);
-    assert(svg.includes("<svg"), "should render svg");
-    assert(svg.includes("Hello"), "should include text");
-    assert(!(0, src_1.renderToSvg)(doc, { transparent: true }).includes('width="320" height="180" fill="#ffffff"'), "transparent SVG should omit background rect");
+    };
+    const held = (0, src_1.resolveVisualFrame)(doc, 0.5).elements[0];
+    const linear = (0, src_1.resolveVisualFrame)(doc, 1.5).elements[0];
+    assert(near(held.x, 0), `object keyframe out curve should override track curve, got ${held.x}`);
+    assert(near(linear.x, 150), `track curve should apply when segment has no keyframe curve, got ${linear.x}`);
 });
-test("renders abstract canvas primitive styling", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 520, height: 320, background: "#f8fafc" },
+test("resolves nested animatable property tracks", () => {
+    const imageSrc = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100'%3E%3Crect width='100' height='100' fill='%23fff'/%3E%3C/svg%3E";
+    const doc = {
+        version: 1,
+        canvas: { width: 320, height: 180, duration: 2 },
         elements: [
             {
-                id: "panel",
-                type: "rect",
-                x: 40,
-                y: 40,
-                width: 180,
-                height: 120,
-                radius: 14,
-                fill: { type: "linearGradient", from: [40, 40], to: [220, 160], stops: [[0, "#dbeafe"], [1, "#a7f3d0"]] },
-                stroke: "#2563eb",
-                strokeWidth: 3,
-                effects: { shadow: { dx: 0, dy: 8, blur: 16, color: "#64748b", opacity: 0.25 } },
-                rotation: -4
+                id: "shape",
+                type: "path",
+                d: "M 0 0 H 100 V 100 H 0 Z",
+                fill: { type: "linearGradient", from: [0, 0], to: [100, 0], stops: [[0, "#000000"], [1, "#ffffff"]] },
+                stroke: "#000000",
+                dashArray: [0, 10],
+                timeline: {
+                    tracks: {
+                        "fill.to": { keyframes: [[0, [100, 0]], [2, [100, 100]]], ease: "linear" },
+                        "fill.stops.0.color": { keyframes: [[0, "#000000"], [2, "#ffffff"]], ease: "linear" },
+                        "effects.blur": { keyframes: [[0, 0], [2, 10]], ease: "linear" },
+                        "effects.shadow.opacity": { keyframes: [[0, 1], [2, 0]], ease: "linear" },
+                        "mask.opacity": { keyframes: [[0, 1], [2, 0]], ease: "linear" },
+                        dashArray: { keyframes: [[0, [0, 10]], [2, [10, 20]]], ease: "linear" }
+                    }
+                }
             },
             {
-                id: "copy",
-                type: "text",
-                lines: ["Gradient panel", "with two lines"],
-                x: 130,
-                y: 100,
-                align: "center",
-                valign: "middle",
-                fontSize: 18,
-                lineHeight: 1.25,
-                letterSpacing: 0.2
-            },
-            { id: "anchor", type: "point", x: 260, y: 100 },
-            { id: "trend", type: "polyline", points: [[300, 170], [340, 130], [390, 150], [440, 90]], stroke: "#dc2626", strokeWidth: 4, strokeCap: "round", drawEnd: 0.6 },
-            { id: "triangle", type: "polygon", points: [[330, 230], [390, 190], [450, 230]], fill: "#fef3c7", stroke: "#f59e0b", strokeJoin: "round", blendMode: "multiply" },
-            { id: "link", type: "arrow", from: "panel.right", to: "anchor", stroke: "#16a34a", strokeWidth: 3, strokeCap: "round" }
+                id: "photo",
+                type: "image",
+                src: imageSrc,
+                x: 120,
+                y: 20,
+                width: 100,
+                height: 100,
+                timeline: {
+                    tracks: {
+                        "source.width": { keyframes: [[0, 100], [2, 50]], ease: "linear" }
+                    }
+                }
+            }
         ]
-    });
+    };
     const result = (0, src_1.validateVisualDocument)(doc);
-    assert(result.ok, `styled document should validate: ${result.issues.map((item) => item.message).join("; ")}`);
-    const svg = (0, src_1.renderToSvg)(doc);
-    assert(svg.includes("<linearGradient"), "should render gradients");
-    assert(svg.includes("feDropShadow"), "should render shadow filters");
-    assert(svg.includes("<tspan"), "should render multiline text");
-    assert(svg.includes("pathLength=\"1\""), "should render draw reveal");
-    assert(svg.includes("stroke-linecap=\"round\""), "should render stroke caps");
-    assert(svg.includes("mix-blend-mode:multiply"), "should render blend mode");
-});
-test("color animation resolves fill and stroke values", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 200, height: 120 },
+    assert(result.ok, `nested animatable tracks should validate: ${result.issues.map((item) => item.message).join("; ")}`);
+    const mid = (0, src_1.resolveVisualFrame)(doc, 1);
+    const shape = mid.elements.find((item) => item.id === "shape");
+    const photo = mid.elements.find((item) => item.id === "photo");
+    assert(shape.fill.to[1] === 50, `linear gradient endpoint should interpolate, got ${shape.fill.to}`);
+    assert(shape.fill.stops[0][1] === "#808080", `gradient color stop should interpolate, got ${shape.fill.stops[0][1]}`);
+    assert(shape.effects.blur === 5, `effects.blur should interpolate, got ${shape.effects.blur}`);
+    assert(shape.effects.shadow.opacity === 0.5, `shadow opacity should interpolate, got ${shape.effects.shadow.opacity}`);
+    assert(shape.mask.opacity === 0.5, `mask opacity should interpolate, got ${shape.mask.opacity}`);
+    assert(shape.dashArray[0] === 5 && shape.dashArray[1] === 15, `dash arrays should interpolate, got ${shape.dashArray}`);
+    assert(photo.source.width === 75, `image source crop should interpolate, got ${photo.source.width}`);
+});
+test("rejects unknown tracks and invalid known track values", () => {
+    const unknownDoc = {
+        version: 1,
+        canvas: { width: 320, height: 180 },
         elements: [
             {
-                id: "signal",
-                type: "circle",
-                cx: 60,
-                cy: 60,
-                radius: 20,
-                fill: "#ff0000",
-                stroke: "#0000ff",
-                animate: {
-                    fill: (0, builders_1.animate)("#ff0000", "#00ff00", { duration: 2 }),
-                    stroke: (0, builders_1.animate)("#0000ff", "#ff0000", { duration: 2 })
-                }
+                id: "dot",
+                type: "point",
+                x: 0,
+                y: 0,
+                timeline: { tracks: { "future.magic": { keyframes: [{ time: 0, value: { enabled: true, amount: 1 } }] } } }
             }
         ]
-    });
-    const frame = (0, src_1.resolveVisualFrame)(doc, 1);
-    const signal = frame.elements.find((item) => item.id === "signal");
-    assert(signal.fill === "#808000", `fill should interpolate, got ${signal.fill}`);
-    assert(signal.stroke === "#800080", `stroke should interpolate, got ${signal.stroke}`);
-});
-test("point references resolve after point animation", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 240, height: 120 },
+    };
+    const unknown = (0, src_1.validateVisualDocument)(unknownDoc);
+    assert(!unknown.ok, "unknown compatibility track should be invalid in the frozen kernel");
+    assert(unknown.issues.some((item) => item.code === "unknown_timeline_track"), "unknown compatibility track should be rejected");
+    const invalidKnown = {
+        version: 1,
+        canvas: { width: 320, height: 180 },
         elements: [
-            { id: "moving", type: "point", x: 20, y: 40, animate: { x: (0, builders_1.animate)(20, 120, { duration: 2 }) } },
-            { id: "wire", type: "line", from: "moving", to: [200, 40], stroke: "#111827" }
+            {
+                id: "shape",
+                type: "path",
+                d: "M 0 0 L 100 0",
+                timeline: { tracks: { "effects.blur": { keyframes: [[0, "#fff"]] } } }
+            }
         ]
-    });
-    const frame = (0, src_1.resolveVisualFrame)(doc, 1);
-    const wire = frame.elements.find((item) => item.id === "wire");
-    assert(JSON.stringify(wire.from) === JSON.stringify([70, 40]), `animated point reference should resolve, got ${JSON.stringify(wire.from)}`);
+    };
+    const invalid = (0, src_1.validateVisualDocument)(invalidKnown);
+    assert(!invalid.ok, "invalid value for a known supported property should fail");
+    assert(invalid.issues.some((item) => item.code === "invalid_timeline_value_for_property"), "known property value mismatch should be reported");
 });
-test("renders image fit, image crop, arc, curve, mask, and pattern paint", () => {
-    const texture = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32'%3E%3Crect width='32' height='32' fill='%23dbeafe'/%3E%3Cpath d='M0 32 L32 0' stroke='%232563eb' stroke-width='6'/%3E%3C/svg%3E";
-    const photo = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='240'%3E%3Crect width='400' height='240' fill='%23fef3c7'/%3E%3Ccircle cx='260' cy='120' r='90' fill='%23fb923c'/%3E%3C/svg%3E";
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 640, height: 360, background: "#ffffff" },
+test("resolves newly supported animatable kernel properties", () => {
+    const patternSrc = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='10'%3E%3Crect width='10' height='10' fill='%23fff'/%3E%3C/svg%3E";
+    const doc = {
+        version: 1,
+        canvas: { width: 320, height: 180, duration: 1 },
         elements: [
             {
-                id: "pattern_card",
-                type: "rect",
-                x: 40,
-                y: 40,
-                width: 150,
-                height: 110,
-                radius: 12,
-                fill: { type: "pattern", src: texture, width: 32, height: 32, fit: "cover" },
-                stroke: "#2563eb"
-            },
-            {
-                id: "cropped_photo",
-                type: "image",
-                src: photo,
-                x: 230,
-                y: 40,
-                width: 160,
-                height: 110,
-                fit: "cover",
-                source: { x: 100, y: 40, width: 180, height: 120, imageWidth: 400, imageHeight: 240 },
-                mask: { type: "circle", cx: 310, cy: 95, radius: 55 }
+                id: "path",
+                type: "path",
+                d: "M 0 0 L 20 0",
+                stroke: "#000000",
+                timeline: {
+                    tracks: {
+                        d: { keyframes: [[0, "M 0 0 L 20 0"], [1, "M 0 0 L 40 40"]] }
+                    }
+                }
             },
             {
-                id: "angle",
-                type: "arc",
-                cx: 120,
-                cy: 250,
-                radius: 70,
-                startAngle: -20,
-                endAngle: 230,
-                stroke: "#dc2626",
-                strokeWidth: 5,
-                strokeCap: "round",
-                drawEnd: 0.75
+                id: "text",
+                type: "text",
+                text: "A",
+                x: 10,
+                y: 20,
+                align: "left",
+                valign: "top",
+                timeline: {
+                    tracks: {
+                        align: { keyframes: [[0, "left"], [1, "right"]] },
+                        valign: { keyframes: [[0, "top"], [1, "bottom"]] },
+                        fontStyle: { keyframes: [[0, "normal"], [1, "italic"]] }
+                    }
+                }
             },
             {
-                id: "flow_curve",
-                type: "curve",
-                from: [250, 250],
-                control1: [340, 150],
-                control2: [440, 340],
-                to: [560, 230],
-                stroke: "#16a34a",
-                strokeWidth: 5,
-                strokeCap: "round",
-                fill: "none"
+                id: "pattern",
+                type: "path",
+                d: "M 0 0 H 100 V 100 H 0 Z",
+                fill: { type: "pattern", src: patternSrc, x: 0, y: 0, width: 10, height: 10, opacity: 1 },
+                timeline: {
+                    tracks: {
+                        "fill.x": { keyframes: [[0, 0], [1, 12]] },
+                        "fill.width": { keyframes: [[0, 10], [1, 20]] },
+                        "fill.opacity": { keyframes: [[0, 1], [1, 0.5]] }
+                    }
+                }
             },
             {
-                id: "curve_dot",
-                type: "circle",
-                radius: 7,
-                fill: "#111827",
-                follow: "flow_curve",
-                progress: 0.5
+                id: "paint",
+                type: "path",
+                d: "M 0 0 H 10 V 10 H 0 Z",
+                fill: "#000000",
+                timeline: {
+                    tracks: {
+                        fill: {
+                            keyframes: [
+                                [0, "#000000"],
+                                [1, { type: "linearGradient", from: [0, 0], to: [10, 0], stops: [[0, "#000000"], [1, "#ffffff"]] }]
+                            ]
+                        }
+                    }
+                }
             }
         ]
-    });
-    const result = (0, src_1.validateVisualDocument)(doc);
-    assert(result.ok, `canvas-like document should validate: ${result.issues.map((item) => item.message).join("; ")}`);
-    const frame = (0, src_1.resolveVisualFrame)(doc, 0);
-    const dot = frame.elements.find((item) => item.id === "curve_dot");
-    assert(dot.cx > 250 && dot.cx < 560, "circle should follow curve primitive");
-    const svg = (0, src_1.renderToSvg)(doc);
-    assert(svg.includes("<pattern"), "should render pattern paint");
-    assert(svg.includes("preserveAspectRatio=\"xMidYMid slice\""), "should render cover image fit");
-    assert(svg.includes("clip-path=\"url(#"), "should crop image with clip path");
-    assert(svg.includes("<mask"), "should render masks");
-    assert(svg.includes(" A "), "should render arc path");
-    assert(svg.includes(" C "), "should render cubic curve path");
-});
-test("lowers authoring primitives into the 2D kernel", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 640, height: 360 },
-        elements: [
-            { id: "box", type: "rect", x: 20, y: 20, width: 80, height: 50, radius: 8, fill: "#ffffff", clip: { type: "rect", x: 20, y: 20, width: 80, height: 50 } },
-            { id: "dot", type: "circle", cx: 140, cy: 45, radius: 20, fill: "#2563eb" },
-            { id: "oval", type: "ellipse", cx: 210, cy: 45, rx: 28, ry: 16 },
-            { id: "wire", type: "line", from: [260, 20], to: [320, 80] },
-            { id: "arrow", type: "arrow", from: [340, 20], to: [400, 80], stroke: "#dc2626" },
-            { id: "angle", type: "arc", cx: 100, cy: 160, radius: 40, startAngle: 0, endAngle: 180 },
-            { id: "curve", type: "curve", from: [170, 160], control1: [230, 80], to: [300, 160], stroke: "#16a34a" },
-            { id: "poly", type: "polyline", points: [[330, 150], [360, 110], [390, 150]] },
-            { id: "shape", type: "polygon", points: [[420, 150], [450, 110], [480, 150]] },
-            { id: "raw", type: "path", d: "M 20 260 L 100 260" },
-            { id: "label", type: "text", text: "Kernel", x: 160, y: 260 },
-            { id: "anchor", type: "point", x: 240, y: 260 },
-            { id: "photo", type: "image", src: "data:image/svg+xml,%3Csvg/%3E", x: 280, y: 230, width: 80, height: 50, mask: { type: "circle", cx: 320, cy: 255, radius: 24 } },
-            { id: "group", type: "group", x: 420, y: 220, children: [{ id: "child", type: "rect", x: 0, y: 0, width: 40, height: 30 }] }
-        ]
-    });
-    const lowered = (0, src_1.lowerVisualDocument)(doc);
-    const allowed = new Set(["group", "path", "text", "image", "point"]);
-    assert((0, src_1.validateKernelVisualDocument)(lowered).ok, "lowered 2D document should validate as kernel");
-    assert(lowered.elements.every((item) => allowed.has(item.type)), "top-level 2D kernel should contain only low primitives");
-    assert(lowered.elements.filter((item) => item.type === "path").length >= 10, "friendly shapes should lower to paths");
-    assert(lowered.elements.find((item) => item.id === "arrow").metadata.markerEnd === "arrow", "arrow marker metadata should survive lowering");
-    assert(lowered.elements.find((item) => item.id === "box").clip.type === "path", "clip shape should lower to path");
-    assert(lowered.elements.find((item) => item.id === "photo").mask.type === "path", "mask shape should lower to path");
-});
-test("uses an internal registry for authoring shape lowerers", () => {
-    const types = (0, shapes_1.registeredAuthoringShapeTypes)();
-    assert(types.includes("rect") && types.includes("circle") && types.includes("sphere"), "built-in shape registry should expose registered authoring shapes");
-});
-test("validates built-in shape geometry through the registry", () => {
-    const doc = {
-        version: 1,
-        canvas: { width: 200, height: 120 },
-        elements: [{ id: "bad_rect", type: "rect", x: 10, y: 10, height: 40 }]
     };
     const result = (0, src_1.validateVisualDocument)(doc);
-    assert(!result.ok, "document should be invalid");
-    assert(result.issues.some((item) => item.path === "/elements/0/width" && item.code === "missing_number"), "rect width should be validated by shape definition");
-});
-test("enforces shape-owned animation properties", () => {
+    assert(result.ok, `new animatable properties should validate: ${result.issues.map((item) => item.message).join("; ")}`);
+    const midPath = (0, src_1.resolveVisualFrame)(doc, 0.5).elements.find((item) => item.id === "path");
+    assert(midPath.d === "M 0 0 L 20 0", `path.d should be discrete before the target keyframe, got ${midPath.d}`);
+    const end = (0, src_1.resolveVisualFrame)(doc, 1);
+    const text = end.elements.find((item) => item.id === "text");
+    const pattern = end.elements.find((item) => item.id === "pattern");
+    const paint = end.elements.find((item) => item.id === "paint");
+    assert(text.align === "right" && text.valign === "bottom" && text.fontStyle === "italic", "text layout/style tracks should resolve discretely");
+    assert(pattern.fill.x === 12 && pattern.fill.width === 20 && pattern.fill.opacity === 0.5, "pattern internals should resolve");
+    assert(paint.fill.type === "linearGradient", "whole paint tracks should switch structured paints");
+});
+test("warns about overlapping timeline representations", () => {
     const doc = {
         version: 1,
-        canvas: { width: 200, height: 120 },
-        elements: [{ id: "label", type: "text", text: "Hello", x: 20, y: 20, animate: { radius: (0, builders_1.animate)(2, 10, { duration: 1 }) } }]
-    };
-    const result = (0, src_1.validateVisualDocument)(doc);
-    assert(!result.ok, "document should be invalid");
-    assert(result.issues.some((item) => item.code === "unsupported_animation_property"), "text should not accept circle-only animation properties");
-});
-test("generated schema matches the committed schema artifact", () => {
-    const schemaPath = path.resolve(__dirname, "..", "..", "schema", "visual.schema.json");
-    const committed = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
-    assert(stableStringify((0, src_1.generateVisualSchema)()) === stableStringify(committed), "committed visual.schema.json should match generated schema");
-});
-test("resolves animation before lowering kernel frames", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 320, height: 180, duration: 2 },
-        elements: [
-            { id: "moving_box", type: "rect", x: 20, y: 30, width: 40, height: 30, animate: { x: (0, builders_1.animate)(20, 120, { duration: 2 }) } }
-        ]
-    });
-    const frame = (0, src_1.resolveKernelFrame)(doc, 1);
-    const pathElement = frame.elements.find((item) => item.id === "moving_box");
-    assert(pathElement.type === "path", "animated rect should lower to a kernel path");
-    assert(pathElement.d.startsWith("M 70 "), `lowered frame should use resolved animated x, got ${pathElement.d}`);
-    assert(!("animate" in pathElement), "resolved kernel frame should not retain authoring animation instructions");
-});
-test("lowered kernel paths keep only kernel-compatible animations", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 320, height: 180, duration: 2 },
+        canvas: { width: 320, height: 180 },
         elements: [
             {
-                id: "moving_box",
-                type: "rect",
-                x: 20,
-                y: 30,
-                width: 40,
-                height: 30,
-                opacity: 0.4,
-                animate: {
-                    x: (0, builders_1.animate)(20, 120, { duration: 2 }),
-                    opacity: (0, builders_1.animate)(0.4, 1, { duration: 2 })
+                id: "shape",
+                type: "path",
+                d: "M 0 0 L 100 0",
+                timeline: {
+                    tracks: {
+                        position: { keyframes: [[0, [0, 0]]] },
+                        x: { keyframes: [[0, 10]] }
+                    }
                 }
             }
         ]
-    });
-    const lowered = (0, src_1.lowerVisualDocument)(doc);
-    const pathElement = lowered.elements.find((item) => item.id === "moving_box");
-    assert(pathElement.type === "path", "rect should lower to a kernel path");
-    assert(!("x" in (pathElement.animate ?? {})), "path lowering should remove authoring-only x animation");
-    assert(pathElement.animate?.opacity, "path lowering should keep compatible opacity animation");
+    };
+    const result = (0, src_1.validateVisualDocument)(doc);
+    assert(result.ok, "overlapping tracks should remain valid");
+    assert(result.warnings.some((item) => item.code === "conflicting_timeline_tracks"), "overlapping tracks should warn");
 });
-test("lowers structured 3D authoring primitives into mesh kernel", () => {
+test("compiles visual keyframe states to kernel timelines", () => {
     const doc = {
         version: 1,
-        canvas: { width: 320, height: 180, space: "3d", renderer: "three" },
+        canvas: { width: 320, height: 180, duration: 1 },
         elements: [
-            { id: "cube", type: "cuboid", position: [0, 0, 0], size: [1, 1, 1], fill: "#2563eb" },
-            { id: "ball", type: "sphere", position: [2, 0, 0], radius: 0.5, fill: "#ef4444" },
-            { id: "floor", type: "plane", position: [0, -1, 0], size: [4, 3], fill: "#dbeafe" },
-            { id: "axis", type: "line3d", from: [-1, 0, 0], to: [1, 0, 0], stroke: "#111827" },
-            { id: "caption", type: "text3d", text: "3D", position: [0, 1, 0] },
-            { id: "lamp", type: "light", kind: "directional", position: [2, 4, 3] }
+            {
+                id: "card",
+                type: "group",
+                x: 20,
+                y: 80,
+                width: 80,
+                height: 40,
+                children: [{ id: "card_bg", type: "path", d: "M 0 0 H 80 V 40 H 0 Z", fill: "#ffffff" }]
+            }
         ]
     };
-    const lowered = (0, src_1.lowerVisualDocument)(doc);
-    assert((0, src_1.validateKernelVisualDocument)(lowered).ok, "lowered 3D document should validate as kernel");
-    assert(lowered.elements.filter((item) => item.type === "mesh3d").length === 3, "cuboid, sphere, and plane should lower to mesh3d");
-    assert(lowered.elements.some((item) => item.type === "line3d"), "line3d should remain a kernel line");
-    assert(lowered.elements.find((item) => item.id === "cube").vertices.length === 8, "cuboid mesh should expose vertices");
-});
-test("circle followers can move along paths", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 320, height: 180, duration: 2 },
-        elements: [
-            { id: "route", type: "path", d: "M 20 120 C 90 20 180 160 300 60", fill: "none", stroke: "#2563eb" },
-            { id: "dot", type: "circle", radius: 6, fill: "#ef4444", follow: "route", progress: (0, builders_1.animate)(0, 1, { duration: 2 }) }
-        ]
-    });
-    const start = (0, src_1.resolveVisualFrame)(doc, 0).elements.find((item) => item.id === "dot");
-    const middle = (0, src_1.resolveVisualFrame)(doc, 1).elements.find((item) => item.id === "dot");
-    const end = (0, src_1.resolveVisualFrame)(doc, 2).elements.find((item) => item.id === "dot");
-    assert(near(start.cx, 20) && near(start.cy, 120), "path follower should start at path start");
-    assert(near(end.cx, 300) && near(end.cy, 60), "path follower should end at path end");
-    assert(middle.cx > 20 && middle.cx < 300, "path follower should move through sampled path");
-});
-test("circle followers sample lowered path-like authoring shapes", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 320, height: 220 },
-        elements: [
-            { id: "arc_route", type: "arc", cx: 90, cy: 100, radius: 50, startAngle: 0, endAngle: 180, stroke: "#2563eb" },
-            { id: "arc_dot", type: "circle", radius: 4, fill: "#ef4444", follow: "arc_route", progress: 0.5 },
-            { id: "poly_route", type: "polyline", points: [[180, 160], [220, 80], [280, 160]], stroke: "#16a34a" },
-            { id: "poly_dot", type: "circle", radius: 4, fill: "#111827", follow: "poly_route", progress: 1 }
-        ]
-    });
-    const frame = (0, src_1.resolveVisualFrame)(doc, 0);
-    const arcDot = frame.elements.find((item) => item.id === "arc_dot");
-    const polyDot = frame.elements.find((item) => item.id === "poly_dot");
-    assert(near(arcDot.cx, 90) && near(arcDot.cy, 150), `arc follower should sample the lowered arc path, got ${arcDot.cx},${arcDot.cy}`);
-    assert(near(polyDot.cx, 280) && near(polyDot.cy, 160), "polyline follower should sample lowered polyline path");
-});
-test("applies primitive id patches", () => {
-    const doc = (0, builders_1.scene)({
-        canvas: { width: 320, height: 180 },
-        elements: [{ id: "label", type: "text", text: "Old", x: 20, y: 20 }]
-    });
-    const patched = (0, src_1.applyVisualPatch)(doc, { op: "update", id: "label", set: { text: "New" } }).document;
-    const label = patched.elements?.find((item) => item.id === "label");
-    assert(label.text === "New", "patch should update by id");
-});
-test("resolves scenes and sequences", () => {
+    const animated = (0, src_1.compileKeyframeStates)(doc, [
+        { time: 1, set: { card: { position: [220, 80], scale: 1.2, opacity: 0.5 } }, ease: "linear" }
+    ]);
+    const result = (0, src_1.validateVisualDocument)(animated);
+    assert(result.ok, `compiled keyframes should validate: ${result.issues.map((item) => item.message).join("; ")}`);
+    const card = animated.elements?.[0];
+    assert(card.timeline.tracks.position.keyframes.length === 2, "compiler should include the base position keyframe");
+    assert(card.timeline.tracks.position.keyframes[0].value[0] === 20, "base position should come from the element");
+    assert(card.timeline.tracks.position.keyframes[0].out?.type === "graph", "named linear ease should compile to an explicit graph curve");
+    const mid = (0, src_1.resolveVisualFrame)(animated, 0.5).elements[0];
+    assert(near(mid.x, 120) && near(mid.scale, 1.1) && near(mid.opacity, 0.75), `compiled timeline should interpolate, got ${mid.x}, ${mid.scale}, ${mid.opacity}`);
+});
+test("compiles per-property curves and timing offsets", () => {
     const doc = {
         version: 1,
-        canvas: { width: 320, height: 180 },
-        scenes: {
-            intro: { elements: [{ id: "intro_title", type: "text", text: "Intro", x: 20, y: 20 }] },
-            outro: { elements: [{ id: "outro_title", type: "text", text: "Outro", x: 20, y: 20 }] }
-        },
-        sequences: {
-            main: { id: "main", clips: [{ scene: "intro", duration: 2 }, { scene: "outro", duration: 3 }] }
-        }
+        canvas: { width: 320, height: 180, duration: 2 },
+        elements: [{ id: "dot", type: "point", x: 0, y: 0 }]
     };
-    assert((0, src_1.documentForScene)(doc, "intro").elements?.[0]?.id === "intro_title", "scene should resolve");
-    assert((0, src_1.resolvedFrameForScene)(doc, "intro", 0).elements[0]?.id === "intro_title", "scene resolved frame should resolve");
-    assert((0, src_1.compileVisualSequence)(doc, "main").duration === 5, "sequence duration should compile");
-    const frame = (0, src_1.documentForSequenceTime)(doc, "main", 2.5);
-    assert(frame.scene === "outro" && frame.localTime === 0.5, "sequence frame should map global to local time");
-    assert((0, src_1.resolvedFrameForSequenceTime)(doc, "main", 2.5).document.elements[0]?.id === "outro_title", "sequence resolved frame should expose resolved authoring frame");
-});
-test("sequence fade transitions produce inspectable frames and timeline", () => {
+    const animated = (0, src_1.compileKeyframeStates)(doc, [
+        {
+            time: 1,
+            set: {
+                dot: {
+                    position: {
+                        value: [100, 0],
+                        curve: { type: "hold" },
+                        offset: 0.25
+                    }
+                }
+            }
+        }
+    ], { offsets: { dot: { position: 0.25 } } });
+    const dot = animated.elements?.[0];
+    const keyframes = dot.timeline.tracks.position.keyframes;
+    assert(keyframes[0].time === 0 && keyframes[0].out.type === "hold", "base keyframe should receive the property curve");
+    assert(keyframes[1].time === 1.5, `global and property offsets should shift the target keyframe, got ${keyframes[1].time}`);
+    assert(near((0, src_1.resolveVisualFrame)(animated, 1).elements[0].x, 0), "hold curve should keep the point at the base value before the target");
+});
+test("edits nested element properties and timeline keyframes", () => {
     const doc = {
         version: 1,
-        canvas: { width: 320, height: 180, duration: 2, fps: 10 },
-        scenes: {
-            a: { elements: [{ id: "a_title", type: "text", text: "A", x: 20, y: 20 }] },
-            b: { elements: [{ id: "b_title", type: "text", text: "B", x: 20, y: 20 }] }
-        },
-        sequences: {
-            main: { id: "main", clips: [{ scene: "a", duration: 1 }, { scene: "b", duration: 1, transition: { type: "fade", duration: 0.5 } }] }
-        }
+        canvas: { width: 320, height: 180, duration: 2 },
+        elements: [
+            {
+                id: "root",
+                type: "group",
+                x: 10,
+                y: 20,
+                children: [{ id: "nested", type: "point", x: 5, y: 6 }]
+            }
+        ]
     };
-    const frame = (0, src_1.documentForSequenceTime)(doc, "main", 1.25);
-    assert(frame.transition?.type === "fade", "frame should expose fade transition");
-    assert(frame.document.elements?.some((item) => item.id === "fade_from_a_title"), "fade should include previous primitive clone");
-    assert(frame.document.elements?.some((item) => item.id === "fade_to_b_title"), "fade should include next primitive clone");
-    assert((0, src_1.sequenceTimeline)(doc, "main", 10).some((item) => item.transition?.type === "fade"), "timeline should expose transition frames");
-});
-test("applies deck step visibility without mutating primitives", () => {
+    assert((0, src_1.listElementReferences)(doc).some((item) => item.id === "nested" && item.depth === 1), "nested element should be listed");
+    const moved = (0, src_1.setElementProperty)(doc, "nested", "position", [30, 40]);
+    assert((0, src_1.findElementById)(moved, "nested").x === 30, "nested position should update immutably");
+    assert((0, src_1.findElementById)(doc, "nested").x === 5, "original document should not mutate");
+    const animated = (0, src_1.setTimelineKeyframe)(moved, "nested", "position", 1, [90, 40], { out: { type: "hold" } });
+    const tracks = (0, src_1.listTimelineTracks)(animated, "nested");
+    assert(tracks.length === 1 && tracks[0].property === "position", "timeline track should be listed");
+    assert((0, src_1.resolveVisualFrame)(animated, 1).elements[0].children[0].x === 90, "timeline keyframe should resolve");
+    const cleaned = (0, src_1.removeTimelineKeyframe)(animated, "nested", "position", 1);
+    assert(!(0, src_1.listTimelineTracks)(cleaned, "nested").length, "timeline keyframe removal should prune empty tracks");
+});
+test("edits and renders path position offsets", () => {
     const doc = {
         version: 1,
-        canvas: { width: 320, height: 180 },
-        scenes: {
-            slide: {
-                elements: [
-                    { id: "title", type: "text", text: "Title", x: 20, y: 20 },
-                    { id: "detail", type: "text", text: "Detail", x: 20, y: 60, opacity: 0 }
-                ],
-                steps: [{ id: "show_detail", show: ["detail"] }]
-            }
-        }
+        canvas: { width: 120, height: 80 },
+        elements: [{ id: "mark", type: "path", d: "M 0 0 L 20 0", stroke: "#000000" }]
     };
-    const frame = (0, src_1.documentForDeckStep)(doc, "slide", 0);
-    const detail = frame.elements?.find((item) => item.id === "detail");
-    assert(detail?.opacity === 1, "deck step should show explicit ids");
-    assert((0, src_1.resolvedFrameForDeckStep)(doc, "slide", 0).elements.find((item) => item.id === "detail")?.opacity === 1, "deck resolved frame should expose step visibility");
-    assert((0, src_1.renderDeckToHtml)(doc, "slide").includes("Next"), "deck html should include controls");
+    const moved = (0, src_1.setElementProperty)(doc, "mark", "position", [30, 40]);
+    const mark = (0, src_1.findElementById)(moved, "mark");
+    assert(mark.x === 30 && mark.y === 40, "path position should edit x/y offsets");
+    assert((0, src_1.renderToSvg)(moved).includes("translate(30 40)"), "path position should render as translation");
 });
-test("reports visual diagnostics without moving elements", () => {
+test("validates timeline graph mistakes", () => {
     const doc = {
         version: 1,
-        canvas: { width: 100, height: 100 },
+        canvas: { width: 320, height: 180 },
         elements: [
-            { id: "outside", type: "rect", x: 80, y: 80, width: 40, height: 40 },
-            { id: "panel", type: "rect", x: 10, y: 10, width: 50, height: 20, fill: "#ffffff" },
-            { id: "low", type: "text", text: "Low contrast text", x: 35, y: 20, align: "center", valign: "middle", fill: "#eeeeee" }
+            {
+                id: "dot",
+                type: "point",
+                x: 0,
+                y: 0,
+                timeline: {
+                    tracks: {
+                        position: {
+                            keyframes: [[0, [0, 0]], [1, [100, 0]]],
+                            curve: { type: "graph", points: [[0, 0], [0.25, 1], [0.2, 0.5], [1, 1]] }
+                        }
+                    }
+                }
+            }
         ]
     };
-    const report = (0, src_1.lintVisualDocument)(doc);
-    assert(report.warnings.some((item) => item.code === "element_outside_canvas"), "should warn about off-canvas elements");
-    assert(report.warnings.some((item) => item.code === "low_text_contrast"), "should warn about contrast");
+    const result = (0, src_1.validateVisualDocument)(doc);
+    assert(!result.ok, "unsorted graph points should be invalid");
+    assert(result.issues.some((item) => item.code === "unsorted_curve_points"), "should report unsorted curve points");
 });
-test("builds project symbol index and validates project scopes", () => {
+test("validates timeline mistakes", () => {
     const doc = {
         version: 1,
         canvas: { width: 320, height: 180 },
-        scenes: {
-            intro: { elements: [{ id: "title", type: "text", text: "Intro", x: 20, y: 20 }] }
-        }
+        elements: [
+            { id: "dot", type: "point", x: 0, y: 0, timeline: { tracks: { x: { keyframes: [[1, 10], [0, 0]] } } } }
+        ]
     };
-    const project = { document: doc, files: { "project.visual.json": doc }, symbols: [] };
-    project.symbols = (0, src_1.buildSymbolIndex)(project);
-    assert(project.symbols.some((symbol) => symbol.id === "title" && symbol.scene === "intro"), "symbol index should include scene ids");
-    assert((0, src_1.validateVisualProject)(project).ok, "project should validate");
+    const result = (0, src_1.validateVisualDocument)(doc);
+    assert(!result.ok, "unsorted timeline should be invalid");
+    assert(result.issues.some((item) => item.code === "unsorted_timeline_keyframes"), "should report unsorted timeline keyframes");
 });
-test("renders structured three html", () => {
+test("diagnostics report off-canvas elements", () => {
     const doc = {
         version: 1,
-        canvas: { width: 320, height: 180, space: "3d", renderer: "three", background: "#ffffff" },
-        elements: [{ id: "cube", type: "cuboid", position: [0, 0, 0], size: [1, 1, 1], fill: "#2563eb" }]
+        canvas: { width: 100, height: 100 },
+        elements: [{ id: "outside", type: "text", text: "Outside", x: 120, y: 20 }]
     };
-    const html = (0, src_1.renderToThreeHtml)(doc);
-    assert(html.includes("THREE") && html.includes("mesh3d"), "should render three html from kernel mesh");
-    assert((0, src_1.renderToHtml)(doc).includes("THREE"), "html renderer should delegate to three");
-    assert((0, src_1.renderThreePreviewSvg)(doc).includes("<polygon"), "structured three should have deterministic svg preview");
+    assert((0, src_1.lintVisualDocument)(doc).warnings.some((item) => item.code === "element_outside_canvas"), "should warn about off-canvas text");
 });
-test("renders raw three module escape hatch html outside primitive docs", () => {
-    const html = (0, src_1.renderRawThreeModuleHtml)({ width: 320, height: 180, moduleUrl: "./scene.js" });
-    assert(html.includes("createSketchmarkThreeScene"), "raw module html should use explicit module entrypoint");
+test("generated schema matches the committed schema artifact", () => {
+    const schemaPath = path.resolve(__dirname, "..", "..", "schema", "visual.schema.json");
+    const committed = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+    assert(stableStringify((0, src_1.generateVisualSchema)()) === stableStringify(committed), "committed visual.schema.json should match generated schema");
 });
-test("all good examples validate and render", () => {
-    const examplesRoot = path.resolve(__dirname, "..", "..", "examples");
-    const files = collectVisualFiles(examplesRoot).filter((file) => !normalizePath(file).includes("/bad/"));
-    const featureFiles = files.filter((file) => normalizePath(file).includes("/features/"));
-    assert(featureFiles.length >= 20, "should include at least 20 feature examples");
+test("all example visual documents validate against the frozen kernel", () => {
+    const examplesDir = path.resolve(__dirname, "..", "..", "examples");
+    const files = fs.readdirSync(examplesDir).filter((file) => file.endsWith(".visual.json")).sort();
+    assert(files.length > 0, "expected at least one example visual document");
+    const failures = [];
     for (const file of files) {
-        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
-        const doc = raw.imports ? (0, src_1.loadVisualProject)(file).document : raw;
+        const fullPath = path.join(examplesDir, file);
+        const document = JSON.parse(fs.readFileSync(fullPath, "utf8"));
+        const result = (0, src_1.validateVisualDocument)(document);
+        if (!result.ok) {
+            const details = result.issues.map((item) => `${item.path} ${item.code}: ${item.message}`).join("; ");
+            failures.push(`${file}: ${details}`);
+        }
+    }
+    assert(!failures.length, failures.join("\n"));
+});
+test("root export stays kernel-focused and presets live under the presets entrypoint", () => {
+    const root = require("../src");
+    assert(root.shapes === undefined && root.characters === undefined && root.applyPresetFragments === undefined, "root package export should not expose preset namespaces");
+    assert(typeof presets_1.shapes.rect === "function" && typeof presets_1.motions.fadeIn === "function", "presets entrypoint should expose official presets");
+});
+test("built-in shape, character, and scene presets compile to valid kernel elements", () => {
+    const doc = (0, presets_1.applyPresetFragments)(emptyPresetDocument(), [
+        presets_1.shapes.rect({ id: "shape.rect", x: 20, y: 20, width: 90, height: 50, fill: "#ffffff", stroke: "#111827" }),
+        presets_1.shapes.roundedRect({ id: "shape.rounded", x: 130, y: 20, width: 110, height: 50, radius: 12, fill: "#eff6ff", stroke: "#2563eb" }),
+        presets_1.shapes.ellipse({ id: "shape.ellipse", cx: 310, cy: 45, rx: 48, ry: 25, fill: "#dcfce7", stroke: "#16a34a" }),
+        presets_1.shapes.circle({ id: "shape.circle", cx: 400, cy: 45, radius: 24, fill: "#fef3c7", stroke: "#ca8a04" }),
+        presets_1.shapes.line({ id: "shape.line", from: [20, 100], to: [140, 120], stroke: "#0f172a" }),
+        presets_1.shapes.polyline({ id: "shape.polyline", points: [[170, 115], [205, 90], [240, 125]], stroke: "#7c3aed" }),
+        presets_1.shapes.arrow({ id: "shape.arrow", from: [280, 110], to: [410, 95], stroke: "#dc2626" }),
+        presets_1.shapes.regularPolygon({ id: "shape.polygon", cx: 500, cy: 100, radius: 30, sides: 6, fill: "#e0f2fe", stroke: "#0284c7" }),
+        presets_1.shapes.star({ id: "shape.star", cx: 590, cy: 100, outerRadius: 32, fill: "#fde68a", stroke: "#92400e" }),
+        presets_1.shapes.speechBubble({ id: "shape.speech", x: 650, y: 65, width: 190, height: 70, text: "Hello" }),
+        presets_1.characters.stickPerson({ id: "hero", x: 40, y: 190 }),
+        presets_1.characters.talkingHead({ id: "speaker", x: 170, y: 190 }),
+        presets_1.characters.simpleDog({ id: "dog", x: 330, y: 220 }),
+        presets_1.characters.simpleSpider({ id: "spider", x: 510, y: 200 }),
+        presets_1.characters.cursorHand({ id: "cursor", x: 680, y: 210 }),
+        presets_1.characters.simpleMascot({ id: "mascot", x: 790, y: 190 }),
+        presets_1.scenes.titleCard({ id: "scene.title", x: 20, y: 380, width: 220, height: 110, title: "Title", subtitle: "Preset" }),
+        presets_1.scenes.lowerThird({ id: "scene.lower", x: 260, y: 400, width: 210, height: 72, title: "Lower", subtitle: "Third" }),
+        presets_1.scenes.captionBubble({ id: "scene.caption", x: 500, y: 405, width: 180, height: 58, text: "Caption" }),
+        presets_1.scenes.comparisonSplit({ id: "scene.compare", x: 705, y: 380, width: 220, height: 110 }),
+        presets_1.scenes.deviceFrame({ id: "scene.device", x: 20, y: 510, width: 120, height: 160, label: "App" }),
+        presets_1.scenes.gridBackground({ id: "scene.grid", x: 170, y: 520, width: 180, height: 120, step: 30 })
+    ]);
+    const result = (0, src_1.validateVisualDocument)(doc);
+    assert(result.ok, `preset element output should validate: ${result.issues.map((item) => item.message).join("; ")}`);
+    assert(JSON.stringify(doc).includes("hero.head"), "character presets should use dot-separated namespaced ids");
+});
+test("built-in motion presets compile to explicit kernel timelines", () => {
+    const cases = [
+        presets_1.motions.fadeIn({ id: "card", start: 0, duration: 0.3 }),
+        presets_1.motions.fadeOut({ id: "card", start: 0.4, duration: 0.3 }),
+        presets_1.motions.slideIn({ id: "card", from: [-80, 20], to: [20, 20] }),
+        presets_1.motions.riseIn({ id: "card", to: [20, 20] }),
+        presets_1.motions.scaleIn({ id: "card" }),
+        presets_1.motions.pulse({ id: "card" }),
+        presets_1.motions.bob({ id: "panel", to: [180, 20] }),
+        presets_1.motions.shake({ id: "card" }),
+        presets_1.motions.drawOn({ id: "line" }),
+        presets_1.motions.stagger({ ids: ["card", "panel"], each: 0.05 })
+    ];
+    for (const fragment of cases) {
+        assertNoLegacyEase(fragment);
+        assert((0, src_1.validateVisualDocument)((0, presets_1.applyPresetFragments)(presetTargetDocument(), fragment)).ok, "motion preset should validate on a target document");
+    }
+});
+test("built-in effect presets compile to kernel effects, paint, clip, and mask tracks", () => {
+    const cases = [
+        presets_1.effects.dropShadow({ id: "card" }),
+        presets_1.effects.softBlur({ id: "card", amount: 4 }),
+        presets_1.effects.glow({ id: "card", color: "#38bdf8" }),
+        presets_1.effects.dim({ id: "card", opacity: 0.45 }),
+        presets_1.effects.tintFill({ id: "card", color: "#fee2e2" }),
+        presets_1.effects.gradientSweep({ id: "card" }),
+        presets_1.effects.roundedImageClip({ id: "photo", x: 320, y: 20, width: 120, height: 90, radius: 18 }),
+        presets_1.effects.maskReveal({ id: "card", x: 20, y: 20, width: 120, height: 70 })
+    ];
+    for (const fragment of cases) {
+        assertNoLegacyEase(fragment);
+        const doc = (0, presets_1.applyPresetFragments)(presetTargetDocument(), fragment);
         const result = (0, src_1.validateVisualDocument)(doc);
-        const relative = normalizePath(path.relative(examplesRoot, file));
-        assert(result.ok, `${relative} should validate: ${result.issues.map((issue) => issue.message).join("; ")}`);
-        const frame = raw.sequences ? (0, src_1.documentForSequenceTime)(doc, Object.keys(raw.sequences)[0], 0).document : raw.scenes ? (0, src_1.documentForScene)(doc, Object.keys(raw.scenes)[0]) : doc;
-        const output = frame.canvas.renderer === "three" ? (0, src_1.renderThreePreviewSvg)(frame) : (0, src_1.renderToSvg)(frame);
-        assert(output.includes("<svg"), `${relative} should render an SVG preview`);
+        assert(result.ok, `effect preset should validate: ${result.issues.map((item) => item.message).join("; ")}`);
+        assert(!JSON.stringify(doc).includes("cornerRadius"), "rounded image clip preset must not write cornerRadius");
+    }
+});
+test("built-in transition presets compile to coordinated kernel timelines", () => {
+    const cases = [
+        presets_1.transitions.crossfade({ fromId: "outgoing", toId: "incoming" }),
+        presets_1.transitions.pushLeft({ fromId: "outgoing", toId: "incoming" }),
+        presets_1.transitions.pushRight({ fromId: "outgoing", toId: "incoming" }),
+        presets_1.transitions.slideUp({ fromId: "outgoing", toId: "incoming" }),
+        presets_1.transitions.wipeLeft({ fromId: "outgoing", toId: "incoming", x: 0, y: 0, width: 160, height: 90 }),
+        presets_1.transitions.wipeRight({ fromId: "outgoing", toId: "incoming", x: 0, y: 0, width: 160, height: 90 }),
+        presets_1.transitions.zoomCut({ fromId: "outgoing", toId: "incoming" }),
+        presets_1.transitions.fadeThroughBlack({ fromId: "outgoing", toId: "incoming", width: 640, height: 360 }),
+        presets_1.transitions.irisIn({ id: "incoming", x: 0, y: 0, width: 160, height: 90 }),
+        presets_1.transitions.irisOut({ id: "outgoing", x: 0, y: 0, width: 160, height: 90 })
+    ];
+    for (const fragment of cases) {
+        assertNoLegacyEase(fragment);
+        const result = (0, src_1.validateVisualDocument)((0, presets_1.applyPresetFragments)(presetTargetDocument(), fragment));
+        assert(result.ok, `transition preset should validate: ${result.issues.map((item) => item.message).join("; ")}`);
+    }
+});
+test("preset fragment composition validates targets and can prefix ids to avoid collisions", () => {
+    const duplicateA = (0, presets_1.prefixPresetFragment)(presets_1.shapes.rect({ id: "box", x: 0, y: 0, width: 40, height: 40 }), "a");
+    const duplicateB = (0, presets_1.prefixPresetFragment)(presets_1.shapes.rect({ id: "box", x: 50, y: 0, width: 40, height: 40 }), "b");
+    const doc = (0, presets_1.applyPresetFragments)(emptyPresetDocument(), [duplicateA, duplicateB]);
+    assert((0, src_1.validateVisualDocument)(doc).ok, "prefixed duplicate fragments should validate");
+    assert(JSON.stringify(doc).includes("a.box") && JSON.stringify(doc).includes("b.box"), "prefixing should rewrite element ids");
+    let threw = false;
+    try {
+        (0, presets_1.applyPresetFragments)(emptyPresetDocument(), presets_1.motions.fadeIn({ id: "missing" }));
+    }
+    catch {
+        threw = true;
     }
+    assert(threw, "applying a timeline fragment to an unknown target should throw");
 });
-console.log("All primitive visual language tests passed.");
+test("preset example visual documents validate as pure kernel output", () => {
+    for (const file of ["presets-demo.visual.json", "preset-character-motion.visual.json"]) {
+        const document = JSON.parse(fs.readFileSync(path.resolve(__dirname, "..", "..", "examples", file), "utf8"));
+        const result = (0, src_1.validateVisualDocument)(document);
+        assert(result.ok, `${file} should validate: ${result.issues.map((item) => item.message).join("; ")}`);
+    }
+});
+console.log("All render-kernel tests passed.");
 function assert(condition, message) {
     if (!condition)
         throw new Error(message);
 }
-function collectVisualFiles(directory) {
-    const out = [];
-    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-        const fullPath = path.join(directory, entry.name);
-        if (entry.isDirectory())
-            out.push(...collectVisualFiles(fullPath));
-        else if (entry.name.endsWith(".visual.json"))
-            out.push(fullPath);
-    }
-    return out;
-}
-function normalizePath(value) {
-    return value.replace(/\\/g, "/");
-}
 function near(left, right) {
     return Math.abs(left - right) < 0.0001;
 }
+function emptyPresetDocument() {
+    return { version: 1, canvas: { width: 960, height: 720, background: "#f8fafc", duration: 2, fps: 30 }, elements: [] };
+}
+function presetTargetDocument() {
+    const imageSrc = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='90'%3E%3Crect width='120' height='90' fill='%23bfdbfe'/%3E%3C/svg%3E";
+    return {
+        version: 1,
+        canvas: { width: 640, height: 360, background: "#f8fafc", duration: 2, fps: 30 },
+        elements: [
+            { id: "card", type: "path", d: "M 20 20 H 140 V 90 H 20 Z", fill: "#ffffff", stroke: "#111827", strokeWidth: 2 },
+            { id: "line", type: "path", d: "M 20 130 C 80 80 150 170 230 120", fill: "none", stroke: "#2563eb", strokeWidth: 5 },
+            { id: "panel", type: "group", x: 180, y: 20, width: 100, height: 70, children: [{ id: "panel.bg", type: "path", d: "M 0 0 H 100 V 70 H 0 Z", fill: "#dcfce7" }] },
+            { id: "photo", type: "image", src: imageSrc, x: 320, y: 20, width: 120, height: 90 },
+            { id: "outgoing", type: "group", x: 40, y: 200, width: 120, height: 80, children: [{ id: "outgoing.bg", type: "path", d: "M 0 0 H 120 V 80 H 0 Z", fill: "#fee2e2" }] },
+            { id: "incoming", type: "group", x: 220, y: 200, width: 120, height: 80, opacity: 0, children: [{ id: "incoming.bg", type: "path", d: "M 0 0 H 120 V 80 H 0 Z", fill: "#dbeafe" }] }
+        ]
+    };
+}
+function assertNoLegacyEase(fragment) {
+    assert(!JSON.stringify(fragment).includes("\"ease\""), "preset fragments should emit explicit curves instead of legacy ease strings");
+}
 function stableStringify(value) {
     return JSON.stringify(sortJson(value));
 }