sketchmark 2.0.0 → 2.1.0

package/dist/src/validate.js

@@ -1,9 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateVisualDocument = validateVisualDocument;
-const shapes_1 = require("./shapes");
+const animatable_1 = require("./animatable");
 const utils_1 = require("./utils");
-const POSITION_ANIMATION_PROPERTIES = new Set(["positionX", "positionY", "positionZ"]);
+const ELEMENT_TYPES = new Set(["path", "text", "image", "point", "group"]);
+const TOP_LEVEL_FIELDS = new Set(["version", "canvas", "elements"]);
+const CANVAS_FIELDS = new Set(["width", "height", "background", "duration", "fps"]);
+const COMMON_ELEMENT_FIELDS = new Set([
+    "id",
+    "type",
+    "opacity",
+    "fill",
+    "stroke",
+    "strokeWidth",
+    "strokeCap",
+    "strokeJoin",
+    "miterLimit",
+    "dashArray",
+    "dashOffset",
+    "drawStart",
+    "drawEnd",
+    "effects",
+    "blendMode",
+    "rotation",
+    "scale",
+    "scaleX",
+    "scaleY",
+    "origin",
+    "clip",
+    "mask",
+    "timeline"
+]);
+const TYPE_FIELDS = {
+    path: new Set(["d", "x", "y"]),
+    text: new Set(["x", "y", "text", "lines", "align", "valign", "fontSize", "fontFamily", "weight", "fontStyle", "lineHeight", "letterSpacing", "maxWidth", "wrap"]),
+    image: new Set(["src", "x", "y", "width", "height", "fit", "source"]),
+    point: new Set(["x", "y"]),
+    group: new Set(["x", "y", "width", "height", "children"])
+};
+const TIMELINE_TRACK_FIELDS = new Set(["keyframes", "curve", "ease"]);
+const TIMELINE_KEYFRAME_FIELDS = new Set(["time", "value", "in", "out", "interpolation"]);
 function validateVisualDocument(document) {
     const issues = [];
     const warnings = [];
@@ -11,183 +47,174 @@ function validateVisualDocument(document) {
         issues.push(issue("/", "invalid_document", "Document must be an object."));
         return { ok: false, issues, warnings };
     }
+    for (const key of Object.keys(document)) {
+        if (!TOP_LEVEL_FIELDS.has(key))
+            issues.push(issue(`/${key}`, "non_kernel_field", `Field '${key}' is not part of the render kernel.`));
+    }
     if (document.version !== 1)
         issues.push(issue("/version", "invalid_version", "Document version must be 1."));
-    if (!document.canvas || typeof document.canvas !== "object") {
-        issues.push(issue("/canvas", "missing_canvas", "Document must define canvas."));
-    }
-    else {
-        if (!(0, utils_1.isFiniteNumber)(document.canvas.width))
-            issues.push(issue("/canvas/width", "missing_canvas_width", "Canvas width must be a number."));
-        if (!(0, utils_1.isFiniteNumber)(document.canvas.height))
-            issues.push(issue("/canvas/height", "missing_canvas_height", "Canvas height must be a number."));
-        if (document.canvas.background !== undefined && typeof document.canvas.background !== "string") {
-            issues.push(issue("/canvas/background", "invalid_canvas_background", "Canvas background must be a color string.", "For gradient, pattern, or image backgrounds, keep canvas.background as a fallback color string and add a full-canvas rect/image as the first element."));
-        }
-        if (document.canvas.space === "3d" && document.canvas.renderer !== "three") {
-            issues.push(issue("/canvas/renderer", "3d_requires_three", "3D documents must set canvas.renderer to 'three'."));
-        }
-        if (document.canvas.renderer === "three" && document.canvas.space !== "3d") {
-            issues.push(issue("/canvas/space", "three_requires_3d", "Three renderer requires canvas.space to be '3d'."));
-        }
-    }
+    validateCanvas(document.canvas, issues);
     const elements = document.elements ?? [];
     if (document.elements !== undefined && !Array.isArray(elements))
         issues.push(issue("/elements", "invalid_elements", "Document elements must be an array."));
     const allElements = Array.isArray(elements) ? (0, utils_1.flattenElements)(elements) : [];
-    const ids = new Map();
+    const ids = new Set();
     for (const [index, element] of allElements.entries()) {
         const path = `/elements/${index}`;
         if (typeof element.id === "string") {
-            if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(element.id)) {
-                issues.push(issue(`${path}/id`, "invalid_id", `Invalid id '${element.id}'. Use letters, numbers, '_' or '-'.`));
+            if (!/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(element.id)) {
+                issues.push(issue(`${path}/id`, "invalid_id", `Invalid id '${element.id}'. Use letters, numbers, '_', '-' or '.'.`));
             }
             else if (ids.has(element.id)) {
                 issues.push(issue(`${path}/id`, "duplicate_id", `Duplicate element id '${element.id}'.`));
             }
             else {
-                ids.set(element.id, element);
+                ids.add(element.id);
             }
         }
     }
-    for (const [index, element] of allElements.entries()) {
-        validateElement(element, `/elements/${index}`, document, ids, issues, warnings);
-    }
-    for (const [sceneId, scene] of Object.entries(document.scenes ?? {})) {
-        if (!Array.isArray(scene.elements))
-            issues.push(issue(`/scenes/${sceneId}/elements`, "invalid_scene_elements", `Scene '${sceneId}' elements must be an array.`));
-        const sceneDoc = { ...document, canvas: { ...document.canvas, ...(scene.canvas ?? {}) }, elements: scene.elements, scenes: undefined, sequences: undefined };
-        const sceneResult = validateVisualDocument(sceneDoc);
-        issues.push(...sceneResult.issues.map((item) => ({ ...item, path: `/scenes/${sceneId}${item.path}` })));
-        warnings.push(...sceneResult.warnings.map((item) => ({ ...item, path: `/scenes/${sceneId}${item.path}` })));
-    }
-    for (const [sequenceId, sequence] of Object.entries(document.sequences ?? {})) {
-        if (!Array.isArray(sequence.clips))
-            issues.push(issue(`/sequences/${sequenceId}/clips`, "invalid_sequence_clips", `Sequence '${sequenceId}' clips must be an array.`));
-        for (const [index, clip] of (sequence.clips ?? []).entries()) {
-            if (!document.scenes?.[clip.scene])
-                issues.push(issue(`/sequences/${sequenceId}/clips/${index}/scene`, "unknown_sequence_scene", `Unknown scene '${clip.scene}' in sequence '${sequenceId}'.`));
-            if (!(0, utils_1.isFiniteNumber)(clip.duration) || clip.duration <= 0)
-                issues.push(issue(`/sequences/${sequenceId}/clips/${index}/duration`, "invalid_clip_duration", "Clip duration must be a positive number."));
-            validateTransition(clip.transition, `/sequences/${sequenceId}/clips/${index}/transition`, issues);
-        }
-    }
+    if (Array.isArray(elements))
+        validateElementList(elements, "/elements", issues, warnings);
     return { ok: issues.length === 0, issues, warnings };
 }
-function validateTransition(value, path, issues) {
-    if (value === undefined)
-        return;
-    if (value === "cut" || value === "fade")
-        return;
-    if (!value || typeof value !== "object") {
-        issues.push(issue(path, "invalid_transition", "Transition must be 'cut', 'fade', or an object with type/duration."));
+function validateCanvas(canvas, issues) {
+    if (!canvas || typeof canvas !== "object") {
+        issues.push(issue("/canvas", "missing_canvas", "Document must define canvas."));
         return;
     }
-    const transition = value;
-    if (transition.type !== "cut" && transition.type !== "fade") {
-        issues.push(issue(`${path}/type`, "invalid_transition_type", "Transition type must be 'cut' or 'fade'."));
+    for (const key of Object.keys(canvas)) {
+        if (!CANVAS_FIELDS.has(key))
+            issues.push(issue(`/canvas/${key}`, "non_kernel_canvas_field", `Canvas field '${key}' is not part of the render kernel.`));
+    }
+    if (!(0, utils_1.isFiniteNumber)(canvas.width))
+        issues.push(issue("/canvas/width", "missing_canvas_width", "Canvas width must be a number."));
+    if (!(0, utils_1.isFiniteNumber)(canvas.height))
+        issues.push(issue("/canvas/height", "missing_canvas_height", "Canvas height must be a number."));
+    if (canvas.background !== undefined && typeof canvas.background !== "string") {
+        issues.push(issue("/canvas/background", "invalid_canvas_background", "Canvas background must be a color string."));
+    }
+    if (canvas.duration !== undefined && (!(0, utils_1.isFiniteNumber)(canvas.duration) || canvas.duration < 0)) {
+        issues.push(issue("/canvas/duration", "invalid_canvas_duration", "Canvas duration must be a non-negative number."));
     }
-    if (transition.duration !== undefined && (!(0, utils_1.isFiniteNumber)(transition.duration) || transition.duration < 0)) {
-        issues.push(issue(`${path}/duration`, "invalid_transition_duration", "Transition duration must be a non-negative number."));
+    if (canvas.fps !== undefined && (!(0, utils_1.isFiniteNumber)(canvas.fps) || canvas.fps <= 0)) {
+        issues.push(issue("/canvas/fps", "invalid_canvas_fps", "Canvas fps must be a positive number."));
     }
 }
-function validateElement(element, path, document, ids, issues, warnings) {
-    if (!element || typeof element !== "object") {
+function validateElementList(elements, path, issues, warnings) {
+    for (const [index, element] of elements.entries())
+        validateElement(element, `${path}/${index}`, issues, warnings);
+}
+function validateElement(element, path, issues, warnings) {
+    if (!element || typeof element !== "object" || Array.isArray(element)) {
         issues.push(issue(path, "invalid_element", "Element must be an object."));
         return;
     }
-    const type = String(element.type || "");
-    if (utils_1.COMPOUND_TYPES.has(type)) {
-        issues.push(issue(`${path}/type`, "compound_type_not_allowed", `Compound type '${type}' is not valid in canonical JSON. Use builders to expand it into primitives first.`));
+    const type = String(element.type ?? "");
+    if (!ELEMENT_TYPES.has(type)) {
+        issues.push(issue(`${path}/type`, "unsupported_type", `Unsupported kernel element type '${type}'.`));
         return;
     }
-    const definition = (0, shapes_1.getInternalShapeDefinition)(type);
-    if (!definition) {
-        issues.push(issue(`${path}/type`, "unsupported_type", `Unsupported primitive type '${type}'.`));
-        return;
+    validateElementFields(element, type, path, issues);
+    if (type === "path") {
+        if (typeof element.d !== "string" || !element.d?.trim()) {
+            issues.push(issue(`${path}/d`, "missing_path_d", "Path elements require a non-empty d string."));
+        }
+        if (element.x !== undefined)
+            requireNumber(element.x, `${path}/x`, issues);
+        if (element.y !== undefined)
+            requireNumber(element.y, `${path}/y`, issues);
+    }
+    if (type === "text") {
+        requireNumber(element.x, `${path}/x`, issues);
+        requireNumber(element.y, `${path}/y`, issues);
+        if (element.text !== undefined && typeof element.text !== "string") {
+            issues.push(issue(`${path}/text`, "invalid_text", "Text must be a string."));
+        }
+        const lines = element.lines;
+        if (lines !== undefined && (!Array.isArray(lines) || lines.some((line) => typeof line !== "string"))) {
+            issues.push(issue(`${path}/lines`, "invalid_lines", "Text lines must be an array of strings."));
+        }
+        if (typeof element.text === "string" && element.text.length > 80 && !element.wrap && !(0, utils_1.isFiniteNumber)(element.maxWidth)) {
+            warnings.push(warning(`${path}/text`, "long_text_no_wrap", "Long text should use maxWidth/wrap or explicit line breaks."));
+        }
     }
-    if (definition.kind === "3d" && (document.canvas.space !== "3d" || document.canvas.renderer !== "three")) {
-        issues.push(issue(path, "three_primitive_requires_three_canvas", `Primitive '${type}' requires canvas.space '3d' and canvas.renderer 'three'.`));
+    if (type === "image")
+        validateImage(element, path, issues);
+    if (type === "point") {
+        requireNumber(element.x, `${path}/x`, issues);
+        requireNumber(element.y, `${path}/y`, issues);
+    }
+    if (type === "group") {
+        requireNumber(element.x, `${path}/x`, issues);
+        requireNumber(element.y, `${path}/y`, issues);
+        if (element.width !== undefined)
+            requireNumber(element.width, `${path}/width`, issues);
+        if (element.height !== undefined)
+            requireNumber(element.height, `${path}/height`, issues);
+        const children = element.children;
+        if (!Array.isArray(children))
+            issues.push(issue(`${path}/children`, "invalid_group_children", "Group children must be an array."));
+        else
+            validateElementList(children, `${path}/children`, issues, warnings);
     }
-    const context = createShapeValidationContext(document, path, ids, issues, warnings);
-    definition.validateGeometry(element, context);
     validateStyle(element, path, issues);
-    validateAnimation(element, path, definition, issues);
-    definition.validateReferences?.(element, context);
-    definition.validateWarnings?.(element, context);
+    validateTimeline(element, element.timeline, `${path}/timeline`, issues, warnings);
 }
-function createShapeValidationContext(document, path, ids, issues, warnings) {
-    return {
-        document,
-        path,
-        ids,
-        issues,
-        warnings,
-        addIssue(issuePath, code, message, suggestion) {
-            issues.push(issue(issuePath, code, message, suggestion));
-        },
-        addWarning(warningPath, code, message, suggestion) {
-            warnings.push(warning(warningPath, code, message, suggestion));
-        },
-        requireNumber(value, numberPath) {
-            requireNumber(value, numberPath, issues);
-        },
-        requirePoint2(value, pointPath, code, message) {
-            if (!(0, utils_1.isPoint2)(value))
-                issues.push(issue(pointPath, code, message));
-        },
-        requirePoint2Array(value, minLength, pointPath, code, message) {
-            if (!(0, utils_1.isPoint2Array)(value, minLength))
-                issues.push(issue(pointPath, code, message));
-        },
-        requirePoint3(value, pointPath, code, message) {
-            if (!isPoint3(value))
-                issues.push(issue(pointPath, code, message));
-        },
-        validateEndpoint(value, endpointPath) {
-            validateEndpoint(value, endpointPath, ids, issues);
-        },
-        validateImageOptions(element) {
-            validateImageOptions(element, path, issues);
-        },
-        isFollowable(type) {
-            return (0, shapes_1.isFollowableAuthoringShape)(type);
+function validateElementFields(element, type, path, issues) {
+    const typeFields = TYPE_FIELDS[type] ?? new Set();
+    for (const key of Object.keys(element)) {
+        if (!COMMON_ELEMENT_FIELDS.has(key) && !typeFields.has(key)) {
+            issues.push(issue(`${path}/${key}`, "non_kernel_element_field", `Field '${key}' is not valid on kernel ${type} elements.`));
         }
-    };
+    }
+}
+function validateImage(element, path, issues) {
+    if (typeof element.src !== "string" || !element.src)
+        issues.push(issue(`${path}/src`, "missing_image_src", "Image src must be a string."));
+    requireNumber(element.x, `${path}/x`, issues);
+    requireNumber(element.y, `${path}/y`, issues);
+    requireNumber(element.width, `${path}/width`, issues);
+    requireNumber(element.height, `${path}/height`, issues);
+    if ((0, utils_1.isFiniteNumber)(element.width) && element.width <= 0)
+        issues.push(issue(`${path}/width`, "invalid_image_width", "Image width must be positive."));
+    if ((0, utils_1.isFiniteNumber)(element.height) && element.height <= 0)
+        issues.push(issue(`${path}/height`, "invalid_image_height", "Image height must be positive."));
+    validateImageFit(element.fit, `${path}/fit`, issues);
+    if (!element.source)
+        return;
+    requireNumber(element.source.x, `${path}/source/x`, issues);
+    requireNumber(element.source.y, `${path}/source/y`, issues);
+    requireNumber(element.source.width, `${path}/source/width`, issues);
+    requireNumber(element.source.height, `${path}/source/height`, issues);
+    requireNumber(element.source.imageWidth, `${path}/source/imageWidth`, issues);
+    requireNumber(element.source.imageHeight, `${path}/source/imageHeight`, issues);
 }
 function validateStyle(element, path, issues) {
     validatePaint(element.fill, `${path}/fill`, issues);
     validatePaint(element.stroke, `${path}/stroke`, issues);
-    if (element.strokeCap !== undefined && !["butt", "round", "square"].includes(String(element.strokeCap))) {
+    if (element.opacity !== undefined && (!(0, utils_1.isFiniteNumber)(element.opacity) || element.opacity < 0 || element.opacity > 1))
+        issues.push(issue(`${path}/opacity`, "invalid_opacity", "Opacity must be between 0 and 1."));
+    if (element.strokeWidth !== undefined && !(0, utils_1.isFiniteNumber)(element.strokeWidth))
+        issues.push(issue(`${path}/strokeWidth`, "invalid_stroke_width", "strokeWidth must be a number."));
+    if (element.strokeCap !== undefined && !["butt", "round", "square"].includes(String(element.strokeCap)))
         issues.push(issue(`${path}/strokeCap`, "invalid_stroke_cap", "strokeCap must be 'butt', 'round', or 'square'."));
-    }
-    if (element.strokeJoin !== undefined && !["miter", "round", "bevel"].includes(String(element.strokeJoin))) {
+    if (element.strokeJoin !== undefined && !["miter", "round", "bevel"].includes(String(element.strokeJoin)))
         issues.push(issue(`${path}/strokeJoin`, "invalid_stroke_join", "strokeJoin must be 'miter', 'round', or 'bevel'."));
-    }
-    if (element.miterLimit !== undefined && !(0, utils_1.isFiniteNumber)(element.miterLimit))
-        issues.push(issue(`${path}/miterLimit`, "invalid_miter_limit", "miterLimit must be a finite number."));
-    if (element.dashOffset !== undefined && !(0, utils_1.isFiniteNumber)(element.dashOffset))
-        issues.push(issue(`${path}/dashOffset`, "invalid_dash_offset", "dashOffset must be a finite number."));
-    if (element.drawStart !== undefined && (!(0, utils_1.isFiniteNumber)(element.drawStart) || element.drawStart < 0 || element.drawStart > 1)) {
-        issues.push(issue(`${path}/drawStart`, "invalid_draw_start", "drawStart must be a number between 0 and 1."));
-    }
-    if (element.drawEnd !== undefined && (!(0, utils_1.isFiniteNumber)(element.drawEnd) || element.drawEnd < 0 || element.drawEnd > 1)) {
-        issues.push(issue(`${path}/drawEnd`, "invalid_draw_end", "drawEnd must be a number between 0 and 1."));
-    }
-    if ((0, utils_1.isFiniteNumber)(element.drawStart) && (0, utils_1.isFiniteNumber)(element.drawEnd) && element.drawStart > element.drawEnd) {
+    for (const key of ["miterLimit", "dashOffset", "rotation", "scale", "scaleX", "scaleY", "fontSize", "lineHeight", "letterSpacing", "maxWidth"]) {
+        const value = element[key];
+        if (value !== undefined && !(0, utils_1.isFiniteNumber)(value))
+            issues.push(issue(`${path}/${key}`, "invalid_number", `${key} must be a finite number.`));
+    }
+    if (element.dashArray !== undefined && (!Array.isArray(element.dashArray) || element.dashArray.some((value) => !(0, utils_1.isFiniteNumber)(value))))
+        issues.push(issue(`${path}/dashArray`, "invalid_dash_array", "dashArray must be an array of numbers."));
+    if (element.drawStart !== undefined && (!(0, utils_1.isFiniteNumber)(element.drawStart) || element.drawStart < 0 || element.drawStart > 1))
+        issues.push(issue(`${path}/drawStart`, "invalid_draw_start", "drawStart must be between 0 and 1."));
+    if (element.drawEnd !== undefined && (!(0, utils_1.isFiniteNumber)(element.drawEnd) || element.drawEnd < 0 || element.drawEnd > 1))
+        issues.push(issue(`${path}/drawEnd`, "invalid_draw_end", "drawEnd must be between 0 and 1."));
+    if ((0, utils_1.isFiniteNumber)(element.drawStart) && (0, utils_1.isFiniteNumber)(element.drawEnd) && element.drawStart > element.drawEnd)
         issues.push(issue(`${path}/drawStart`, "invalid_draw_range", "drawStart must be less than or equal to drawEnd."));
-    }
-    if (element.rotation !== undefined && !(0, utils_1.isFiniteNumber)(element.rotation))
-        issues.push(issue(`${path}/rotation`, "invalid_rotation", "rotation must be a finite number in degrees."));
-    if (element.scale !== undefined && !(0, utils_1.isFiniteNumber)(element.scale))
-        issues.push(issue(`${path}/scale`, "invalid_scale", "scale must be a finite number."));
-    if (element.scaleX !== undefined && !(0, utils_1.isFiniteNumber)(element.scaleX))
-        issues.push(issue(`${path}/scaleX`, "invalid_scale_x", "scaleX must be a finite number."));
-    if (element.scaleY !== undefined && !(0, utils_1.isFiniteNumber)(element.scaleY))
-        issues.push(issue(`${path}/scaleY`, "invalid_scale_y", "scaleY must be a finite number."));
-    if (element.origin !== undefined && !(typeof element.origin === "string" && utils_1.ANCHORS.has(element.origin)) && !(0, utils_1.isPoint2)(element.origin)) {
-        issues.push(issue(`${path}/origin`, "invalid_origin", "origin must be an anchor name or [x,y]."));
-    }
+    if (element.origin !== undefined && !(0, utils_1.isPoint2)(element.origin))
+        issues.push(issue(`${path}/origin`, "invalid_origin", "origin must be [x,y]."));
     validateEffects(element.effects, `${path}/effects`, issues);
     validateClip(element.clip, `${path}/clip`, issues);
     validateMask(element.mask, `${path}/mask`, issues);
@@ -195,8 +222,8 @@ function validateStyle(element, path, issues) {
 function validatePaint(value, path, issues) {
     if (value === undefined || typeof value === "string")
         return;
-    if (!value || typeof value !== "object") {
-        issues.push(issue(path, "invalid_paint", "Paint must be a color string or a structured gradient object."));
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        issues.push(issue(path, "invalid_paint", "Paint must be a color string or structured paint object."));
         return;
     }
     if (value.type === "linearGradient") {
@@ -211,7 +238,7 @@ function validatePaint(value, path, issues) {
         if (!(0, utils_1.isPoint2)(value.center))
             issues.push(issue(`${path}/center`, "invalid_gradient_center", "Radial gradient center must be [x,y]."));
         if (!(0, utils_1.isFiniteNumber)(value.radius) || value.radius < 0)
-            issues.push(issue(`${path}/radius`, "invalid_gradient_radius", "Radial gradient radius must be a non-negative number."));
+            issues.push(issue(`${path}/radius`, "invalid_gradient_radius", "Radial gradient radius must be non-negative."));
         if (value.focus !== undefined && !(0, utils_1.isPoint2)(value.focus))
             issues.push(issue(`${path}/focus`, "invalid_gradient_focus", "Radial gradient focus must be [x,y]."));
         validateGradientStops(value.stops, `${path}/stops`, issues);
@@ -221,20 +248,13 @@ function validatePaint(value, path, issues) {
         if (typeof value.src !== "string" || !value.src)
             issues.push(issue(`${path}/src`, "invalid_pattern_src", "Pattern src must be a string."));
         if (!(0, utils_1.isFiniteNumber)(value.width) || value.width <= 0)
-            issues.push(issue(`${path}/width`, "invalid_pattern_width", "Pattern width must be a positive number."));
+            issues.push(issue(`${path}/width`, "invalid_pattern_width", "Pattern width must be positive."));
         if (!(0, utils_1.isFiniteNumber)(value.height) || value.height <= 0)
-            issues.push(issue(`${path}/height`, "invalid_pattern_height", "Pattern height must be a positive number."));
-        if (value.x !== undefined && !(0, utils_1.isFiniteNumber)(value.x))
-            issues.push(issue(`${path}/x`, "invalid_pattern_x", "Pattern x must be a finite number."));
-        if (value.y !== undefined && !(0, utils_1.isFiniteNumber)(value.y))
-            issues.push(issue(`${path}/y`, "invalid_pattern_y", "Pattern y must be a finite number."));
+            issues.push(issue(`${path}/height`, "invalid_pattern_height", "Pattern height must be positive."));
         validateImageFit(value.fit, `${path}/fit`, issues);
-        if (value.opacity !== undefined && (!(0, utils_1.isFiniteNumber)(value.opacity) || value.opacity < 0 || value.opacity > 1)) {
-            issues.push(issue(`${path}/opacity`, "invalid_pattern_opacity", "Pattern opacity must be between 0 and 1."));
-        }
         return;
     }
-    issues.push(issue(`${path}/type`, "invalid_paint_type", "Paint object type must be 'linearGradient', 'radialGradient', or 'pattern'."));
+    issues.push(issue(`${path}/type`, "invalid_paint_type", "Paint object type must be linearGradient, radialGradient, or pattern."));
 }
 function validateGradientStops(value, path, issues) {
     if (!Array.isArray(value) || value.length < 2) {
@@ -266,166 +286,192 @@ function validateEffects(value, path, issues) {
         const shadow = value.shadow;
         if (!shadow || typeof shadow !== "object" || Array.isArray(shadow)) {
             issues.push(issue(`${path}/shadow`, "invalid_shadow", "shadow must be an object."));
+            return;
         }
-        else {
-            requireNumber(shadow.dx, `${path}/shadow/dx`, issues);
-            requireNumber(shadow.dy, `${path}/shadow/dy`, issues);
-            requireNumber(shadow.blur, `${path}/shadow/blur`, issues);
-            if (typeof shadow.color !== "string")
-                issues.push(issue(`${path}/shadow/color`, "invalid_shadow_color", "shadow color must be a string."));
-            if (shadow.opacity !== undefined && (!(0, utils_1.isFiniteNumber)(shadow.opacity) || shadow.opacity < 0 || shadow.opacity > 1)) {
-                issues.push(issue(`${path}/shadow/opacity`, "invalid_shadow_opacity", "shadow opacity must be between 0 and 1."));
-            }
-        }
+        requireNumber(shadow.dx, `${path}/shadow/dx`, issues);
+        requireNumber(shadow.dy, `${path}/shadow/dy`, issues);
+        requireNumber(shadow.blur, `${path}/shadow/blur`, issues);
+        if (typeof shadow.color !== "string")
+            issues.push(issue(`${path}/shadow/color`, "invalid_shadow_color", "shadow color must be a string."));
+        if (shadow.opacity !== undefined && (!(0, utils_1.isFiniteNumber)(shadow.opacity) || shadow.opacity < 0 || shadow.opacity > 1))
+            issues.push(issue(`${path}/shadow/opacity`, "invalid_shadow_opacity", "shadow opacity must be between 0 and 1."));
     }
 }
 function validateClip(value, path, issues) {
-    validateShape(value, path, "clip", issues);
+    if (value === undefined)
+        return;
+    if (!value || typeof value !== "object" || value.type !== "path" || typeof value.d !== "string" || !value.d.trim())
+        issues.push(issue(path, "invalid_clip", "clip must be { type:'path', d:string }."));
 }
 function validateMask(value, path, issues) {
-    validateShape(value, path, "mask", issues);
-    if (value && typeof value === "object" && value.opacity !== undefined && (!(0, utils_1.isFiniteNumber)(value.opacity) || value.opacity < 0 || value.opacity > 1)) {
+    if (value === undefined)
+        return;
+    if (!value || typeof value !== "object" || value.type !== "path" || typeof value.d !== "string" || !value.d.trim())
+        issues.push(issue(path, "invalid_mask", "mask must be { type:'path', d:string, opacity?:number }."));
+    if (value && value.opacity !== undefined && (!(0, utils_1.isFiniteNumber)(value.opacity) || value.opacity < 0 || value.opacity > 1))
         issues.push(issue(`${path}/opacity`, "invalid_mask_opacity", "mask opacity must be between 0 and 1."));
-    }
 }
-function validateShape(value, path, label, issues) {
+function validateTimeline(element, value, path, issues, warnings) {
     if (value === undefined)
         return;
-    if (!value || typeof value !== "object") {
-        issues.push(issue(path, `invalid_${label}`, `${label} must be a rect, circle, or path object.`));
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        issues.push(issue(path, "invalid_timeline", "timeline must be an object."));
         return;
     }
-    if (value.type === "rect") {
-        requireNumber(value.x, `${path}/x`, issues);
-        requireNumber(value.y, `${path}/y`, issues);
-        requireNumber(value.width, `${path}/width`, issues);
-        requireNumber(value.height, `${path}/height`, issues);
+    if (value.start !== undefined && (!(0, utils_1.isFiniteNumber)(value.start) || value.start < 0))
+        issues.push(issue(`${path}/start`, "invalid_timeline_start", "timeline.start must be a non-negative number."));
+    if (value.end !== undefined && (!(0, utils_1.isFiniteNumber)(value.end) || value.end < 0))
+        issues.push(issue(`${path}/end`, "invalid_timeline_end", "timeline.end must be a non-negative number."));
+    if ((0, utils_1.isFiniteNumber)(value.start) && (0, utils_1.isFiniteNumber)(value.end) && value.end < value.start)
+        issues.push(issue(`${path}/end`, "invalid_timeline_range", "timeline.end must be greater than or equal to timeline.start."));
+    if (value.tracks === undefined)
         return;
-    }
-    if (value.type === "circle") {
-        requireNumber(value.cx, `${path}/cx`, issues);
-        requireNumber(value.cy, `${path}/cy`, issues);
-        requireNumber(value.radius, `${path}/radius`, issues);
+    if (!value.tracks || typeof value.tracks !== "object" || Array.isArray(value.tracks)) {
+        issues.push(issue(`${path}/tracks`, "invalid_timeline_tracks", "timeline.tracks must be an object."));
         return;
     }
-    if (value.type === "path") {
-        if (typeof value.d !== "string" || !value.d.trim())
-            issues.push(issue(`${path}/d`, `missing_${label}_path`, `Path ${label} requires d.`));
-        return;
+    for (const [property, track] of Object.entries(value.tracks))
+        validateTrack(element, property, track, `${path}/tracks/${property}`, issues, warnings);
+    for (const message of (0, animatable_1.conflictWarningsForTracks)(Object.keys(value.tracks))) {
+        warnings.push(warning(`${path}/tracks`, "conflicting_timeline_tracks", message));
     }
-    issues.push(issue(`${path}/type`, `invalid_${label}_type`, `${label} type must be 'rect', 'circle', or 'path'.`));
 }
-function validateImageOptions(element, path, issues) {
-    validateImageFit(element.fit, `${path}/fit`, issues);
-    if (!element.source)
+function validateTrack(element, property, track, path, issues, warnings) {
+    if (!track || typeof track !== "object" || Array.isArray(track)) {
+        issues.push(issue(path, "invalid_timeline_track", "Timeline track must be an object."));
         return;
-    requireNumber(element.source.x, `${path}/source/x`, issues);
-    requireNumber(element.source.y, `${path}/source/y`, issues);
-    requireNumber(element.source.width, `${path}/source/width`, issues);
-    requireNumber(element.source.height, `${path}/source/height`, issues);
-    requireNumber(element.source.imageWidth, `${path}/source/imageWidth`, issues);
-    requireNumber(element.source.imageHeight, `${path}/source/imageHeight`, issues);
-    if ((0, utils_1.isFiniteNumber)(element.source.width) && element.source.width <= 0)
-        issues.push(issue(`${path}/source/width`, "invalid_source_width", "Image source width must be positive."));
-    if ((0, utils_1.isFiniteNumber)(element.source.height) && element.source.height <= 0)
-        issues.push(issue(`${path}/source/height`, "invalid_source_height", "Image source height must be positive."));
-    if ((0, utils_1.isFiniteNumber)(element.source.imageWidth) && element.source.imageWidth <= 0)
-        issues.push(issue(`${path}/source/imageWidth`, "invalid_source_image_width", "Image source imageWidth must be positive."));
-    if ((0, utils_1.isFiniteNumber)(element.source.imageHeight) && element.source.imageHeight <= 0)
-        issues.push(issue(`${path}/source/imageHeight`, "invalid_source_image_height", "Image source imageHeight must be positive."));
-}
-function validateImageFit(value, path, issues) {
-    if (value !== undefined && value !== "fill" && value !== "contain" && value !== "cover") {
-        issues.push(issue(path, "invalid_image_fit", "fit must be 'fill', 'contain', or 'cover'."));
     }
-}
-function validateAnimation(element, path, definition, issues) {
-    if (!element.animate)
+    for (const key of Object.keys(track)) {
+        if (!TIMELINE_TRACK_FIELDS.has(key))
+            issues.push(issue(`${path}/${key}`, "non_kernel_timeline_track_field", `Timeline track field '${key}' is not part of the render kernel.`));
+    }
+    validateTimelineCurve(track.curve, `${path}/curve`, issues);
+    if (track.ease !== undefined && typeof track.ease !== "string")
+        issues.push(issue(`${path}/ease`, "invalid_timeline_ease", "Timeline ease must be a string."));
+    const propertySpec = (0, animatable_1.animatablePropertySpec)(element, property);
+    if (!propertySpec) {
+        const code = (0, animatable_1.knownAnimatableProperty)(property) ? "unsupported_timeline_track_for_element" : "unknown_timeline_track";
+        issues.push(issue(path, code, `Timeline track '${property}' is not a supported animatable property for ${element.type} elements.`));
+    }
+    if (!Array.isArray(track.keyframes) || !track.keyframes.length) {
+        issues.push(issue(`${path}/keyframes`, "invalid_timeline_keyframes", "Track keyframes must be a non-empty array."));
         return;
-    const animatable = new Set(definition.animatable);
-    for (const [property, animation] of Object.entries(element.animate)) {
-        if (!animatable.has(property)) {
-            issues.push(issue(`${path}/animate/${property}`, "unsupported_animation_property", `Property '${property}' is not animatable in the primitive JSON core.`));
-            continue;
-        }
-        const hasStaticValue = property in element || (POSITION_ANIMATION_PROPERTIES.has(property) && "position" in element);
-        if (!hasStaticValue && property !== "opacity") {
-            issues.push(issue(`${path}/animate/${property}`, "missing_static_animation_property", `Animated property '${property}' must also have a static value.`));
-        }
-        if (!animation || typeof animation !== "object") {
-            issues.push(issue(`${path}/animate/${property}`, "invalid_animation", "Animation must be an object with from/to or keyframes."));
-            continue;
-        }
-        if (Array.isArray(animation)) {
-            issues.push(issue(`${path}/animate/${property}`, "invalid_animation", "Animation must be an object. Use { keyframes: [...] }, not a raw keyframe array."));
-            continue;
-        }
-        const values = [animation.from, animation.to].filter((value) => value !== undefined);
-        let hasTimeline = animation.from !== undefined || animation.to !== undefined;
-        if (animation.duration !== undefined && !(0, utils_1.isFiniteNumber)(animation.duration)) {
-            issues.push(issue(`${path}/animate/${property}/duration`, "invalid_animation_duration", "Animation duration must be a finite number."));
-        }
-        if (animation.delay !== undefined && !(0, utils_1.isFiniteNumber)(animation.delay)) {
-            issues.push(issue(`${path}/animate/${property}/delay`, "invalid_animation_delay", "Animation delay must be a finite number."));
-        }
-        if (animation.keyframes !== undefined) {
-            if (!Array.isArray(animation.keyframes)) {
-                issues.push(issue(`${path}/animate/${property}/keyframes`, "invalid_animation_keyframes", "Animation keyframes must be an array of [time,value] pairs."));
-            }
-            else {
-                hasTimeline = hasTimeline || animation.keyframes.length > 0;
-                for (const [index, frame] of animation.keyframes.entries()) {
-                    if (!Array.isArray(frame) || frame.length !== 2) {
-                        issues.push(issue(`${path}/animate/${property}/keyframes/${index}`, "invalid_animation_keyframe", "Animation keyframe must be [time,value]."));
-                        continue;
-                    }
-                    if (!(0, utils_1.isFiniteNumber)(frame[0])) {
-                        issues.push(issue(`${path}/animate/${property}/keyframes/${index}/0`, "invalid_animation_keyframe_time", "Animation keyframe time must be a finite number of seconds."));
-                    }
-                    values.push(frame[1]);
-                }
-            }
-        }
-        if (!hasTimeline) {
-            issues.push(issue(`${path}/animate/${property}`, "invalid_animation", "Animation must define from/to or keyframes."));
+    }
+    let previous = Number.NEGATIVE_INFINITY;
+    for (const [index, frame] of track.keyframes.entries()) {
+        const time = validateKeyframe(frame, `${path}/keyframes/${index}`, issues, propertySpec);
+        if (time === undefined)
             continue;
+        if (time < previous)
+            issues.push(issue(`${path}/keyframes/${index}/time`, "unsorted_timeline_keyframes", "Keyframe times must be sorted."));
+        previous = time;
+    }
+}
+function validateKeyframe(frame, path, issues, propertySpec) {
+    if (Array.isArray(frame)) {
+        if (frame.length !== 2) {
+            issues.push(issue(path, "invalid_timeline_keyframe", "Keyframe tuple must be [time,value]."));
+            return undefined;
         }
-        for (const value of values) {
-            if ((property === "fill" || property === "stroke") && typeof value === "string")
-                continue;
-            if (!(0, utils_1.isFiniteNumber)(value)) {
-                issues.push(issue(`${path}/animate/${property}`, "invalid_animation_value", `Animation values for '${property}' must be finite numbers${property === "fill" || property === "stroke" ? " or color strings" : ""}.`));
-                break;
-            }
+        if (!(0, utils_1.isFiniteNumber)(frame[0])) {
+            issues.push(issue(`${path}/0`, "invalid_timeline_keyframe_time", "Keyframe time must be finite seconds."));
+            return undefined;
         }
+        validateTimelineValue(frame[1], `${path}/1`, issues, propertySpec);
+        return frame[0];
+    }
+    if (!frame || typeof frame !== "object") {
+        issues.push(issue(path, "invalid_timeline_keyframe", "Keyframe must be [time,value] or { time, value }."));
+        return undefined;
+    }
+    for (const key of Object.keys(frame)) {
+        if (!TIMELINE_KEYFRAME_FIELDS.has(key))
+            issues.push(issue(`${path}/${key}`, "non_kernel_timeline_keyframe_field", `Timeline keyframe field '${key}' is not part of the render kernel.`));
+    }
+    if (!(0, utils_1.isFiniteNumber)(frame.time)) {
+        issues.push(issue(`${path}/time`, "invalid_timeline_keyframe_time", "Keyframe time must be finite seconds."));
+        return undefined;
+    }
+    validateTimelineValue(frame.value, `${path}/value`, issues, propertySpec);
+    validateTimelineCurve(frame.in, `${path}/in`, issues);
+    validateTimelineCurve(frame.out, `${path}/out`, issues);
+    validateTimelineCurve(frame.interpolation, `${path}/interpolation`, issues);
+    return frame.time;
+}
+function validateTimelineValue(value, path, issues, propertySpec) {
+    if (!(0, animatable_1.isTimelineValue)(value)) {
+        issues.push(issue(path, "invalid_timeline_value", "Track value must be a JSON-safe timeline value."));
+        return;
+    }
+    if (propertySpec && !(0, animatable_1.validateMotionValueForProperty)(propertySpec, value)) {
+        issues.push(issue(path, "invalid_timeline_value_for_property", `Track value is not valid for '${propertySpec.property}'.`));
     }
 }
-function validateEndpoint(value, path, ids, issues) {
-    if ((0, utils_1.isPoint2)(value))
+function validateTimelineCurve(curve, path, issues) {
+    if (curve === undefined)
+        return;
+    if (!curve || typeof curve !== "object" || Array.isArray(curve)) {
+        issues.push(issue(path, "invalid_timeline_curve", "Timeline curve must be an object."));
         return;
-    if (typeof value !== "string") {
-        issues.push(issue(path, "invalid_endpoint", "Endpoint must be [x,y] or a reference like 'box.right'."));
+    }
+    if (curve.type === "hold") {
+        validateAllowedKeys(curve, path, new Set(["type"]), issues);
+        return;
+    }
+    if (curve.type === "cubicBezier") {
+        validateAllowedKeys(curve, path, new Set(["type", "x1", "y1", "x2", "y2"]), issues);
+        if (!(0, utils_1.isFiniteNumber)(curve.x1) || curve.x1 < 0 || curve.x1 > 1)
+            issues.push(issue(`${path}/x1`, "invalid_curve_x1", "cubicBezier.x1 must be between 0 and 1."));
+        if (!(0, utils_1.isFiniteNumber)(curve.x2) || curve.x2 < 0 || curve.x2 > 1)
+            issues.push(issue(`${path}/x2`, "invalid_curve_x2", "cubicBezier.x2 must be between 0 and 1."));
+        if (!(0, utils_1.isFiniteNumber)(curve.y1))
+            issues.push(issue(`${path}/y1`, "invalid_curve_y1", "cubicBezier.y1 must be a finite number."));
+        if (!(0, utils_1.isFiniteNumber)(curve.y2))
+            issues.push(issue(`${path}/y2`, "invalid_curve_y2", "cubicBezier.y2 must be a finite number."));
         return;
     }
-    const { id, anchor } = (0, utils_1.parseReference)(value);
-    const target = ids.get(id);
-    if (!target) {
-        issues.push(issue(path, "unknown_reference", `Unknown reference '${value}'.`));
+    if (curve.type === "graph") {
+        validateAllowedKeys(curve, path, new Set(["type", "points"]), issues);
+        if (!Array.isArray(curve.points) || curve.points.length < 2) {
+            issues.push(issue(`${path}/points`, "invalid_curve_points", "Graph curve points must contain at least two [x,y] points."));
+            return;
+        }
+        let previousX = Number.NEGATIVE_INFINITY;
+        for (const [index, point] of curve.points.entries()) {
+            if (!(0, utils_1.isPoint2)(point)) {
+                issues.push(issue(`${path}/points/${index}`, "invalid_curve_point", "Graph curve points must be [x,y]."));
+                continue;
+            }
+            if (point[0] < 0 || point[0] > 1)
+                issues.push(issue(`${path}/points/${index}/0`, "invalid_curve_point_x", "Graph curve x values must be between 0 and 1."));
+            if (point[0] <= previousX)
+                issues.push(issue(`${path}/points/${index}/0`, "unsorted_curve_points", "Graph curve x values must be strictly increasing."));
+            previousX = point[0];
+        }
+        const first = curve.points[0];
+        const last = curve.points[curve.points.length - 1];
+        if ((0, utils_1.isPoint2)(first) && first[0] !== 0)
+            issues.push(issue(`${path}/points/0/0`, "invalid_curve_start", "Graph curve must start at x=0."));
+        if ((0, utils_1.isPoint2)(last) && last[0] !== 1)
+            issues.push(issue(`${path}/points/${curve.points.length - 1}/0`, "invalid_curve_end", "Graph curve must end at x=1."));
         return;
     }
-    if (!utils_1.ANCHORS.has(anchor))
-        issues.push(issue(path, "invalid_anchor", `Unknown anchor '${anchor}'.`));
-    if (!(0, utils_1.elementBox)(target)) {
-        issues.push(issue(path, "unresolvable_reference", `Reference '${value}' points to an element without a resolvable 2D box.`));
+    issues.push(issue(`${path}/type`, "invalid_timeline_curve_type", "Timeline curve type must be graph, cubicBezier, or hold."));
+}
+function validateAllowedKeys(value, path, allowed, issues) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            issues.push(issue(`${path}/${key}`, "non_kernel_timeline_curve_field", `Timeline curve field '${key}' is not part of this curve type.`));
     }
 }
+function validateImageFit(value, path, issues) {
+    if (value !== undefined && value !== "fill" && value !== "contain" && value !== "cover")
+        issues.push(issue(path, "invalid_image_fit", "fit must be 'fill', 'contain', or 'cover'."));
+}
 function requireNumber(value, path, issues) {
     if (!(0, utils_1.isFiniteNumber)(value))
         issues.push(issue(path, "missing_number", "A finite number is required."));
 }
-function isPoint3(value) {
-    return Array.isArray(value) && value.length === 3 && (0, utils_1.isFiniteNumber)(value[0]) && (0, utils_1.isFiniteNumber)(value[1]) && (0, utils_1.isFiniteNumber)(value[2]);
-}
 function issue(path, code, message, suggestion) {
     return { path, code, message, ...(suggestion ? { suggestion } : {}) };
 }