sketchmark 2.0.0 → 2.1.0

package/dist/src/animatable.d.ts

@@ -0,0 +1,21 @@
+import type { MotionValue, VisualElement } from "./types";
+export type AnimatableValueKind = "number" | "string" | "numberOrString" | "paint" | "point2" | "numberArray" | "stringArray" | "object";
+export type AnimatableInterpolation = "number" | "color" | "point2" | "numberArray" | "discrete";
+export interface AnimatablePropertySpec {
+    property: string;
+    valueKind: AnimatableValueKind;
+    interpolation: AnimatableInterpolation;
+    elementTypes: readonly string[];
+    defaultValue?: MotionValue | ((element: VisualElement, property: string) => MotionValue | undefined);
+    ensure?: (element: VisualElement, property: string) => void;
+}
+export declare function animatablePropertySpec(element: VisualElement, property: string): AnimatablePropertySpec | undefined;
+export declare function knownAnimatableProperty(property: string): boolean;
+export declare function animatablePropertiesForElement(element: VisualElement): AnimatablePropertySpec[];
+export declare function validateMotionValueForProperty(spec: AnimatablePropertySpec, value: unknown): boolean;
+export declare function isTimelineValue(value: unknown): value is MotionValue;
+export declare function getPropertyValue(element: VisualElement, property: string): MotionValue | undefined;
+export declare function baseValueForProperty(element: VisualElement, property: string): MotionValue | undefined;
+export declare function applyPropertyValue(element: VisualElement, property: string, value: MotionValue): void;
+export declare function parsePropertyPath(property: string): Array<string | number>;
+export declare function conflictWarningsForTracks(trackNames: string[]): string[];

package/dist/src/animatable.js

@@ -0,0 +1,439 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.animatablePropertySpec = animatablePropertySpec;
+exports.knownAnimatableProperty = knownAnimatableProperty;
+exports.animatablePropertiesForElement = animatablePropertiesForElement;
+exports.validateMotionValueForProperty = validateMotionValueForProperty;
+exports.isTimelineValue = isTimelineValue;
+exports.getPropertyValue = getPropertyValue;
+exports.baseValueForProperty = baseValueForProperty;
+exports.applyPropertyValue = applyPropertyValue;
+exports.parsePropertyPath = parsePropertyPath;
+exports.conflictWarningsForTracks = conflictWarningsForTracks;
+const utils_1 = require("./utils");
+const POSITION_TYPES = ["path", "point", "text", "image", "group"];
+const VISIBLE_TYPES = ["path", "text", "image", "group"];
+const COMMON_TYPES = ["path", "point", "text", "image", "group"];
+const PAINT_FILL_TYPES = ["path", "text"];
+const PATH_TYPES = ["path"];
+const TEXT_TYPES = ["text"];
+const IMAGE_TYPES = ["image"];
+const BASE_SPECS = [
+    { property: "position", valueKind: "point2", interpolation: "point2", elementTypes: POSITION_TYPES, defaultValue: (element) => canUsePosition(element) ? [Number(element.x ?? 0), Number(element.y ?? 0)] : undefined },
+    { property: "x", valueKind: "number", interpolation: "number", elementTypes: POSITION_TYPES, defaultValue: 0 },
+    { property: "y", valueKind: "number", interpolation: "number", elementTypes: POSITION_TYPES, defaultValue: 0 },
+    { property: "rotation", valueKind: "number", interpolation: "number", elementTypes: VISIBLE_TYPES, defaultValue: 0 },
+    { property: "scale", valueKind: "number", interpolation: "number", elementTypes: VISIBLE_TYPES, defaultValue: 1 },
+    { property: "scaleX", valueKind: "number", interpolation: "number", elementTypes: VISIBLE_TYPES, defaultValue: 1 },
+    { property: "scaleY", valueKind: "number", interpolation: "number", elementTypes: VISIBLE_TYPES, defaultValue: 1 },
+    { property: "origin", valueKind: "point2", interpolation: "point2", elementTypes: VISIBLE_TYPES },
+    { property: "opacity", valueKind: "number", interpolation: "number", elementTypes: COMMON_TYPES, defaultValue: 1 },
+    { property: "d", valueKind: "string", interpolation: "discrete", elementTypes: PATH_TYPES },
+    { property: "fill", valueKind: "paint", interpolation: "color", elementTypes: PAINT_FILL_TYPES },
+    { property: "stroke", valueKind: "paint", interpolation: "color", elementTypes: PATH_TYPES },
+    { property: "strokeWidth", valueKind: "number", interpolation: "number", elementTypes: PATH_TYPES, defaultValue: 1 },
+    { property: "strokeCap", valueKind: "string", interpolation: "discrete", elementTypes: PATH_TYPES },
+    { property: "strokeJoin", valueKind: "string", interpolation: "discrete", elementTypes: PATH_TYPES },
+    { property: "miterLimit", valueKind: "number", interpolation: "number", elementTypes: PATH_TYPES },
+    { property: "dashArray", valueKind: "numberArray", interpolation: "numberArray", elementTypes: PATH_TYPES },
+    { property: "dashOffset", valueKind: "number", interpolation: "number", elementTypes: PATH_TYPES, defaultValue: 0 },
+    { property: "drawStart", valueKind: "number", interpolation: "number", elementTypes: PATH_TYPES, defaultValue: 0 },
+    { property: "drawEnd", valueKind: "number", interpolation: "number", elementTypes: PATH_TYPES, defaultValue: 1 },
+    { property: "text", valueKind: "string", interpolation: "discrete", elementTypes: TEXT_TYPES },
+    { property: "lines", valueKind: "stringArray", interpolation: "discrete", elementTypes: TEXT_TYPES },
+    { property: "align", valueKind: "string", interpolation: "discrete", elementTypes: TEXT_TYPES },
+    { property: "valign", valueKind: "string", interpolation: "discrete", elementTypes: TEXT_TYPES },
+    { property: "fontFamily", valueKind: "string", interpolation: "discrete", elementTypes: TEXT_TYPES },
+    { property: "fontStyle", valueKind: "string", interpolation: "discrete", elementTypes: TEXT_TYPES },
+    { property: "fontSize", valueKind: "number", interpolation: "number", elementTypes: TEXT_TYPES, defaultValue: 16 },
+    { property: "lineHeight", valueKind: "number", interpolation: "number", elementTypes: TEXT_TYPES, defaultValue: 1.2 },
+    { property: "letterSpacing", valueKind: "number", interpolation: "number", elementTypes: TEXT_TYPES, defaultValue: 0 },
+    { property: "maxWidth", valueKind: "number", interpolation: "number", elementTypes: TEXT_TYPES },
+    { property: "weight", valueKind: "numberOrString", interpolation: "discrete", elementTypes: TEXT_TYPES, defaultValue: 400 },
+    { property: "width", valueKind: "number", interpolation: "number", elementTypes: ["image", "group"], defaultValue: 0 },
+    { property: "height", valueKind: "number", interpolation: "number", elementTypes: ["image", "group"], defaultValue: 0 },
+    { property: "src", valueKind: "string", interpolation: "discrete", elementTypes: IMAGE_TYPES },
+    { property: "fit", valueKind: "string", interpolation: "discrete", elementTypes: IMAGE_TYPES },
+    { property: "blendMode", valueKind: "string", interpolation: "discrete", elementTypes: VISIBLE_TYPES },
+    { property: "clip.d", valueKind: "string", interpolation: "discrete", elementTypes: VISIBLE_TYPES, ensure: ensureClip },
+    { property: "mask.d", valueKind: "string", interpolation: "discrete", elementTypes: VISIBLE_TYPES, ensure: ensureMask },
+    { property: "mask.opacity", valueKind: "number", interpolation: "number", elementTypes: VISIBLE_TYPES, defaultValue: 1, ensure: ensureMask }
+];
+const BASE_BY_PROPERTY = new Map(BASE_SPECS.map((spec) => [spec.property, spec]));
+function animatablePropertySpec(element, property) {
+    const base = BASE_BY_PROPERTY.get(property);
+    if (base)
+        return supportsType(base, element.type) ? base : undefined;
+    const dynamic = dynamicPropertySpec(property, element);
+    return dynamic && supportsType(dynamic, element.type) ? dynamic : undefined;
+}
+function knownAnimatableProperty(property) {
+    return BASE_BY_PROPERTY.has(property) || dynamicPropertySpec(property) !== undefined;
+}
+function animatablePropertiesForElement(element) {
+    const out = BASE_SPECS.filter((spec) => supportsType(spec, element.type));
+    for (const property of dynamicPropertiesForElement(element)) {
+        const spec = animatablePropertySpec(element, property);
+        if (spec)
+            out.push(spec);
+    }
+    return out;
+}
+function validateMotionValueForProperty(spec, value) {
+    switch (spec.valueKind) {
+        case "number":
+            return (0, utils_1.isFiniteNumber)(value);
+        case "string":
+            return typeof value === "string";
+        case "numberOrString":
+            return (0, utils_1.isFiniteNumber)(value) || typeof value === "string";
+        case "paint":
+            return isPaintValue(value);
+        case "point2":
+            return (0, utils_1.isPoint2)(value);
+        case "numberArray":
+            return isNumberArray(value);
+        case "stringArray":
+            return isStringArray(value);
+        case "object":
+            return isJsonObject(value);
+    }
+}
+function isTimelineValue(value) {
+    return (0, utils_1.isFiniteNumber)(value) || typeof value === "string" || (0, utils_1.isPoint2)(value) || isNumberArray(value) || isStringArray(value) || isJsonObject(value);
+}
+function getPropertyValue(element, property) {
+    if (property === "position" && canUsePosition(element))
+        return [Number(element.x ?? 0), Number(element.y ?? 0)];
+    const stop = parseGradientStopProperty(property);
+    if (stop)
+        return getGradientStopValue(element, stop);
+    const value = getPathValue(element, parsePropertyPath(property));
+    return isTimelineValue(value) ? (0, utils_1.clone)(value) : undefined;
+}
+function baseValueForProperty(element, property) {
+    const value = getPropertyValue(element, property);
+    if (value !== undefined)
+        return value;
+    const spec = animatablePropertySpec(element, property);
+    if (!spec || spec.defaultValue === undefined)
+        return undefined;
+    return typeof spec.defaultValue === "function" ? spec.defaultValue(element, property) : (0, utils_1.clone)(spec.defaultValue);
+}
+function applyPropertyValue(element, property, value) {
+    if (property === "position") {
+        if (!(0, utils_1.isPoint2)(value))
+            return;
+        if (canUsePosition(element)) {
+            const record = element;
+            record.x = value[0];
+            record.y = value[1];
+        }
+        return;
+    }
+    const spec = animatablePropertySpec(element, property);
+    if (spec?.ensure)
+        spec.ensure(element, property);
+    const stop = parseGradientStopProperty(property);
+    if (stop) {
+        setGradientStopValue(element, stop, value);
+        return;
+    }
+    const path = parsePropertyPath(property);
+    if (path.length > 1) {
+        setPathValue(element, path, (0, utils_1.clone)(value), !!spec?.ensure);
+        return;
+    }
+    element[property] = (0, utils_1.clone)(value);
+}
+function parsePropertyPath(property) {
+    return property.split(".").filter(Boolean).map((segment) => /^\d+$/.test(segment) ? Number(segment) : segment);
+}
+function conflictWarningsForTracks(trackNames) {
+    const tracks = new Set(trackNames);
+    const warnings = [];
+    if (tracks.has("position") && (tracks.has("x") || tracks.has("y")))
+        warnings.push("position overlaps with x/y tracks; prefer one representation.");
+    if (tracks.has("scale") && (tracks.has("scaleX") || tracks.has("scaleY")))
+        warnings.push("scale overlaps with scaleX/scaleY tracks; prefer one representation.");
+    for (const root of ["fill", "stroke"]) {
+        if (tracks.has(root) && trackNames.some((name) => name.startsWith(`${root}.`)))
+            warnings.push(`${root} overlaps with nested ${root}.* tracks; prefer whole-paint switching or nested paint animation, not both.`);
+    }
+    return warnings;
+}
+function dynamicPropertySpec(property, element) {
+    const gradient = parsePaintProperty(property, element);
+    if (gradient)
+        return gradient;
+    if (/^effects\.(blur|brightness|contrast|saturate|hueRotate)$/.test(property)) {
+        return { property, valueKind: "number", interpolation: "number", elementTypes: VISIBLE_TYPES, defaultValue: effectDefault(property), ensure: ensureEffects };
+    }
+    if (/^effects\.shadow\.(dx|dy|blur|opacity)$/.test(property)) {
+        return { property, valueKind: "number", interpolation: "number", elementTypes: VISIBLE_TYPES, defaultValue: shadowDefault(property), ensure: ensureShadow };
+    }
+    if (property === "effects.shadow.color") {
+        return { property, valueKind: "string", interpolation: "color", elementTypes: VISIBLE_TYPES, defaultValue: "#000000", ensure: ensureShadow };
+    }
+    if (/^source\.(x|y|width|height)$/.test(property)) {
+        return { property, valueKind: "number", interpolation: "number", elementTypes: IMAGE_TYPES, defaultValue: sourceDefault(property), ensure: ensureImageSource };
+    }
+    return undefined;
+}
+function parsePaintProperty(property, element) {
+    const pattern = /^(fill|stroke)\.(x|y|width|height|opacity)$/.exec(property);
+    if (pattern) {
+        if (element && !isPaintType(element, pattern[1], "pattern"))
+            return undefined;
+        return { property, valueKind: "number", interpolation: "number", elementTypes: paintElementTypes(pattern[1]) };
+    }
+    const rootMatch = /^(fill|stroke)\.(from|to)$/.exec(property);
+    if (rootMatch) {
+        if (element && !isPaintType(element, rootMatch[1], "linearGradient"))
+            return undefined;
+        return { property, valueKind: "point2", interpolation: "point2", elementTypes: paintElementTypes(rootMatch[1]) };
+    }
+    const radialPoint = /^(fill|stroke)\.(center|focus)$/.exec(property);
+    if (radialPoint) {
+        if (element && !isPaintType(element, radialPoint[1], "radialGradient"))
+            return undefined;
+        return { property, valueKind: "point2", interpolation: "point2", elementTypes: paintElementTypes(radialPoint[1]) };
+    }
+    const radialRadius = /^(fill|stroke)\.radius$/.exec(property);
+    if (radialRadius) {
+        if (element && !isPaintType(element, radialRadius[1], "radialGradient"))
+            return undefined;
+        return { property, valueKind: "number", interpolation: "number", elementTypes: paintElementTypes(radialRadius[1]), defaultValue: 40 };
+    }
+    const stop = parseGradientStopProperty(property);
+    if (!stop)
+        return undefined;
+    if (element && !hasGradientStop(element, stop))
+        return undefined;
+    return {
+        property,
+        valueKind: stop.channel === "offset" ? "number" : "string",
+        interpolation: stop.channel === "offset" ? "number" : "color",
+        elementTypes: paintElementTypes(stop.root)
+    };
+}
+function dynamicPropertiesForElement(element) {
+    const out = [
+        "effects.blur",
+        "effects.brightness",
+        "effects.contrast",
+        "effects.saturate",
+        "effects.hueRotate",
+        "effects.shadow.dx",
+        "effects.shadow.dy",
+        "effects.shadow.blur",
+        "effects.shadow.color",
+        "effects.shadow.opacity"
+    ];
+    if (element.type === "image")
+        out.push("source.x", "source.y", "source.width", "source.height");
+    for (const root of ["fill", "stroke"]) {
+        if (!supportsType({ elementTypes: paintElementTypes(root) }, element.type))
+            continue;
+        const paint = element[root];
+        if (isPatternPaint(paint))
+            out.push(`${root}.x`, `${root}.y`, `${root}.width`, `${root}.height`, `${root}.opacity`);
+        if (isStructuredPaint(paint)) {
+            if (paint.type === "linearGradient")
+                out.push(`${root}.from`, `${root}.to`);
+            if (paint.type === "radialGradient")
+                out.push(`${root}.center`, `${root}.focus`, `${root}.radius`);
+            for (let index = 0; index < paint.stops.length; index += 1) {
+                out.push(`${root}.stops.${index}.offset`, `${root}.stops.${index}.color`);
+            }
+        }
+    }
+    return out;
+}
+function supportsType(spec, type) {
+    return spec.elementTypes.includes(type);
+}
+function canUsePosition(element) {
+    return element.type === "path" || element.type === "point" || element.type === "text" || element.type === "image" || element.type === "group";
+}
+function paintElementTypes(root) {
+    return root === "fill" ? PAINT_FILL_TYPES : PATH_TYPES;
+}
+function getPathValue(target, path) {
+    let cursor = target;
+    for (const segment of path) {
+        if (cursor === undefined || cursor === null)
+            return undefined;
+        cursor = readSegment(cursor, segment);
+    }
+    return cursor;
+}
+function setPathValue(target, path, value, create) {
+    let cursor = target;
+    for (let index = 0; index < path.length - 1; index += 1) {
+        const segment = path[index];
+        const next = path[index + 1];
+        const current = readSegment(cursor, segment);
+        if (current === undefined || current === null) {
+            if (!create)
+                return;
+            writeSegment(cursor, segment, typeof next === "number" ? [] : {});
+        }
+        cursor = readSegment(cursor, segment);
+    }
+    writeSegment(cursor, path[path.length - 1], value);
+}
+function readSegment(target, segment) {
+    if (Array.isArray(target) && typeof segment === "number")
+        return target[segment];
+    if (isRecord(target))
+        return target[String(segment)];
+    return undefined;
+}
+function writeSegment(target, segment, value) {
+    if (Array.isArray(target) && typeof segment === "number") {
+        target[segment] = value;
+        return;
+    }
+    if (isRecord(target))
+        target[String(segment)] = value;
+}
+function parseGradientStopProperty(property) {
+    const match = /^(fill|stroke)\.stops\.(\d+)\.(offset|color)$/.exec(property);
+    if (!match)
+        return undefined;
+    return { root: match[1], index: Number(match[2]), channel: match[3] };
+}
+function getGradientStopValue(element, stopPath) {
+    const paint = element[stopPath.root];
+    if (!isStructuredPaint(paint))
+        return undefined;
+    const stop = paint.stops[stopPath.index];
+    if (!stop)
+        return undefined;
+    const value = Array.isArray(stop) ? (stopPath.channel === "offset" ? stop[0] : stop[1]) : stop[stopPath.channel];
+    return isTimelineValue(value) ? (0, utils_1.clone)(value) : undefined;
+}
+function setGradientStopValue(element, stopPath, value) {
+    const paint = element[stopPath.root];
+    if (!isStructuredPaint(paint))
+        return;
+    const stop = paint.stops[stopPath.index];
+    if (!stop)
+        return;
+    if (Array.isArray(stop)) {
+        if (stopPath.channel === "offset" && (0, utils_1.isFiniteNumber)(value))
+            stop[0] = value;
+        if (stopPath.channel === "color" && typeof value === "string")
+            stop[1] = value;
+    }
+    else {
+        stop[stopPath.channel] = (0, utils_1.clone)(value);
+    }
+}
+function ensureEffects(element) {
+    const record = element;
+    if (!isRecord(record.effects))
+        record.effects = {};
+}
+function ensureShadow(element) {
+    ensureEffects(element);
+    const effects = element.effects;
+    if (!isRecord(effects.shadow))
+        effects.shadow = { dx: 0, dy: 0, blur: 0, color: "#000000", opacity: 1 };
+}
+function ensureImageSource(element) {
+    if (element.type !== "image")
+        return;
+    if (!element.source) {
+        element.source = {
+            x: 0,
+            y: 0,
+            width: element.width,
+            height: element.height,
+            imageWidth: element.width,
+            imageHeight: element.height
+        };
+    }
+}
+function ensureClip(element) {
+    if (!element.clip)
+        element.clip = { type: "path", d: fullPlanePath() };
+}
+function ensureMask(element) {
+    if (!element.mask)
+        element.mask = { type: "path", d: fullPlanePath(), opacity: 1 };
+}
+function effectDefault(property) {
+    if (property === "effects.brightness" || property === "effects.contrast" || property === "effects.saturate")
+        return 1;
+    return 0;
+}
+function shadowDefault(property) {
+    return property === "effects.shadow.opacity" ? 1 : 0;
+}
+function sourceDefault(property) {
+    return (element) => {
+        if (element.type !== "image")
+            return undefined;
+        if (property === "source.width")
+            return element.width;
+        if (property === "source.height")
+            return element.height;
+        return 0;
+    };
+}
+function fullPlanePath() {
+    return "M -100000 -100000 H 100000 V 100000 H -100000 Z";
+}
+function isStructuredPaint(value) {
+    return isRecord(value) && typeof value.type === "string" && Array.isArray(value.stops);
+}
+function isPatternPaint(value) {
+    return isRecord(value) && value.type === "pattern";
+}
+function isPaintType(element, root, type) {
+    const paint = element[root];
+    return isRecord(paint) && paint.type === type;
+}
+function hasGradientStop(element, stopPath) {
+    const paint = element[stopPath.root];
+    return isStructuredPaint(paint) && !!paint.stops[stopPath.index];
+}
+function isPaintValue(value) {
+    if (typeof value === "string")
+        return true;
+    if (!isRecord(value) || typeof value.type !== "string")
+        return false;
+    if (value.type === "linearGradient")
+        return (0, utils_1.isPoint2)(value.from) && (0, utils_1.isPoint2)(value.to) && isGradientStops(value.stops);
+    if (value.type === "radialGradient")
+        return (0, utils_1.isPoint2)(value.center) && (0, utils_1.isFiniteNumber)(value.radius) && (value.focus === undefined || (0, utils_1.isPoint2)(value.focus)) && isGradientStops(value.stops);
+    if (value.type === "pattern")
+        return typeof value.src === "string" && (0, utils_1.isFiniteNumber)(value.width) && (0, utils_1.isFiniteNumber)(value.height);
+    return false;
+}
+function isGradientStops(value) {
+    return Array.isArray(value) && value.length >= 2 && value.every((stop) => {
+        if (Array.isArray(stop))
+            return (0, utils_1.isFiniteNumber)(stop[0]) && typeof stop[1] === "string";
+        return isRecord(stop) && (0, utils_1.isFiniteNumber)(stop.offset) && typeof stop.color === "string";
+    });
+}
+function isNumberArray(value) {
+    return Array.isArray(value) && value.every((item) => (0, utils_1.isFiniteNumber)(item));
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isJsonObject(value) {
+    if (!isRecord(value))
+        return false;
+    return Object.values(value).every(isJsonValue);
+}
+function isJsonValue(value) {
+    return value === null || typeof value === "string" || typeof value === "boolean" || (0, utils_1.isFiniteNumber)(value) || (Array.isArray(value) && value.every(isJsonValue)) || isJsonObject(value);
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}

package/dist/src/builders/index.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationValue, ArcElement, CircleElement, CurveElement, EllipseElement, Endpoint, GroupElement, LineElement, PointElement, PolygonElement, PolylineElement, RectElement, TextElement, VisualDocument, VisualElement } from "../types";
+import type { ArcElement, CircleElement, CurveElement, EllipseElement, Endpoint, GroupElement, LineElement, PointElement, PolygonElement, PolylineElement, RectElement, TextElement, VisualDocument, VisualElement } from "../types";
 export type ElementInput = VisualElement | VisualElement[];
 export declare function scene(input: Omit<VisualDocument, "version"> & {
     version?: 1;
@@ -15,8 +15,6 @@ export declare function arrow(input: Omit<LineElement, "type">): LineElement;
 export declare function arc(input: Omit<ArcElement, "type">): ArcElement;
 export declare function curve(input: Omit<CurveElement, "type">): CurveElement;
 export declare function group(input: Omit<GroupElement, "type">): GroupElement;
-export declare function animate(from: number | string, to: number | string, options?: Omit<AnimationValue, "from" | "to">): AnimationValue;
-export declare function keyframes(values: Array<[number, number | string]>): AnimationValue;
 export interface NodeOptions {
     id: string;
     label: string;
@@ -43,14 +41,6 @@ export interface FlowOptions {
     labelY?: number;
 }
 export declare function flow(options: FlowOptions): VisualElement[];
-export interface PacketOptions {
-    id: string;
-    on: string;
-    radius?: number;
-    fill?: string;
-    progress: number | AnimationValue;
-}
-export declare function packet(options: PacketOptions): CircleElement;
 export interface CalloutOptions {
     id: string;
     text: string;

package/dist/src/builders/index.js

@@ -13,11 +13,8 @@ exports.arrow = arrow;
 exports.arc = arc;
 exports.curve = curve;
 exports.group = group;
-exports.animate = animate;
-exports.keyframes = keyframes;
 exports.node = node;
 exports.flow = flow;
-exports.packet = packet;
 exports.callout = callout;
 exports.row = row;
 exports.column = column;
@@ -61,12 +58,6 @@ function curve(input) {
 function group(input) {
     return { type: "group", ...input };
 }
-function animate(from, to, options = {}) {
-    return { from, to, ...options };
-}
-function keyframes(values) {
-    return { keyframes: values };
-}
 function node(options) {
     return [
         rect({
@@ -119,15 +110,6 @@ function flow(options) {
     }
     return out;
 }
-function packet(options) {
-    return circle({
-        id: options.id,
-        radius: options.radius ?? 7,
-        fill: options.fill ?? "#ef4444",
-        follow: options.on,
-        progress: options.progress
-    });
-}
 function callout(options) {
     const boxId = `${options.id}_box`;
     return [
@@ -153,7 +135,7 @@ function callout(options) {
         }),
         arrow({
             id: `${options.id}_arrow`,
-            from: `${boxId}.bottom`,
+            from: { target: boxId, anchor: (0, utils_1.anchorSpec)("bottom") },
             to: options.target,
             stroke: options.stroke ?? "#ef4444",
             strokeWidth: 2

package/dist/src/diagnostics.js

@@ -15,7 +15,7 @@ function lintVisualDocument(document) {
                 path,
                 code: "element_outside_canvas",
                 message: `Element '${element.id ?? element.type}' extends outside the canvas.`,
-                suggestion: "Move it inside the canvas or intentionally clip it with a group/mask later."
+                suggestion: "Move it inside the canvas or intentionally clip it."
             });
         }
         if (element.type === "text" && Number(element.fontSize ?? 16) < 10) {
@@ -26,27 +26,6 @@ function lintVisualDocument(document) {
                 suggestion: "Use fontSize 12 or larger for explainer visuals."
             });
         }
-        if (element.type === "text") {
-            const containingBox = boxes.find((item) => item.element.type === "rect" && item.element.id !== element.id && pointInside(element.x, element.y, item.box));
-            if (containingBox && !boxInside(box, containingBox.box)) {
-                warnings.push({
-                    path,
-                    code: "text_likely_outside_box",
-                    message: `Text '${element.id ?? ""}' is anchored inside '${containingBox.element.id ?? "rect"}' but its estimated bounds extend outside.`,
-                    suggestion: "Move the text explicitly, reduce fontSize, or set maxWidth/wrap intentionally."
-                });
-            }
-            const contrastAgainst = containingBox?.element.fill ?? document.canvas.background ?? "#ffffff";
-            const ratio = contrastRatio(String(element.fill ?? "#111827"), String(contrastAgainst));
-            if (ratio !== undefined && ratio < 3) {
-                warnings.push({
-                    path,
-                    code: "low_text_contrast",
-                    message: `Text '${element.id ?? ""}' may not have enough contrast.`,
-                    suggestion: "Choose a darker or lighter explicit fill color; diagnostics do not recolor text."
-                });
-            }
-        }
     }
     for (let left = 0; left < boxes.length; left += 1) {
         for (let right = left + 1; right < boxes.length; right += 1) {
@@ -69,45 +48,3 @@ function lintVisualDocument(document) {
 function overlaps(a, b) {
     return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
 }
-function pointInside(x, y, box) {
-    return x >= box.x && x <= box.x + box.width && y >= box.y && y <= box.y + box.height;
-}
-function boxInside(inner, outer) {
-    return inner.x >= outer.x && inner.y >= outer.y && inner.x + inner.width <= outer.x + outer.width && inner.y + inner.height <= outer.y + outer.height;
-}
-function contrastRatio(foreground, background) {
-    const fg = parseHexColor(foreground);
-    const bg = parseHexColor(background);
-    if (!fg || !bg)
-        return undefined;
-    const a = relativeLuminance(fg);
-    const b = relativeLuminance(bg);
-    const light = Math.max(a, b);
-    const dark = Math.min(a, b);
-    return (light + 0.05) / (dark + 0.05);
-}
-function parseHexColor(value) {
-    const text = value.trim();
-    if (/^#[0-9a-fA-F]{3}$/.test(text)) {
-        return [
-            parseInt(text[1] + text[1], 16),
-            parseInt(text[2] + text[2], 16),
-            parseInt(text[3] + text[3], 16)
-        ];
-    }
-    if (/^#[0-9a-fA-F]{6}$/.test(text)) {
-        return [
-            parseInt(text.slice(1, 3), 16),
-            parseInt(text.slice(3, 5), 16),
-            parseInt(text.slice(5, 7), 16)
-        ];
-    }
-    return undefined;
-}
-function relativeLuminance([r, g, b]) {
-    const values = [r, g, b].map((channel) => {
-        const value = channel / 255;
-        return value <= 0.03928 ? value / 12.92 : Math.pow((value + 0.055) / 1.055, 2.4);
-    });
-    return 0.2126 * values[0] + 0.7152 * values[1] + 0.0722 * values[2];
-}

package/dist/src/edit.d.ts

@@ -0,0 +1,27 @@
+import type { ClipShape, ImageElement, MotionValue, TimelineCurve, TimelineKeyframe, VisualDocument, VisualElement } from "./types";
+export interface ElementReference {
+    id: string;
+    type: string;
+    depth: number;
+    path: number[];
+}
+export interface SetKeyframeOptions {
+    in?: TimelineCurve;
+    out?: TimelineCurve;
+    interpolation?: TimelineCurve;
+    curve?: TimelineCurve;
+    ease?: string;
+}
+export declare function listElementReferences(document: VisualDocument): ElementReference[];
+export declare function findElementById(document: VisualDocument, id: string): VisualElement | undefined;
+export declare function setElementProperty(document: VisualDocument, id: string, property: string, value: MotionValue): VisualDocument;
+export declare function setTimelineKeyframe(document: VisualDocument, id: string, property: string, time: number, value: MotionValue, options?: SetKeyframeOptions): VisualDocument;
+export declare function removeTimelineKeyframe(document: VisualDocument, id: string, property: string, time: number): VisualDocument;
+export declare function listTimelineTracks(document: VisualDocument, id: string): Array<{
+    property: string;
+    keyframes: TimelineKeyframe[];
+    curve?: TimelineCurve;
+    ease?: string;
+}>;
+export declare function roundedRectClipPath(x: number, y: number, width: number, height: number, radius?: number): string;
+export declare function imageRoundedClip(element: Pick<ImageElement, "x" | "y" | "width" | "height">, radius?: number): ClipShape;