@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/svg.js

@@ -0,0 +1,539 @@
+/** Portable SVG construction and animation. No DOM, Node, clock, network or runtime dependencies. */
+import { checkStructure } from "./svg/schema.js";
+export const SVG_ASSET_LIMITS = Object.freeze({
+    sourceValues: 100000,
+    sourceCharacters: 2000000,
+    nodesPerFrame: 10000,
+    frames: 240,
+    outputCharacters: 8000000,
+    depth: 32,
+});
+export class SvgAssetError extends Error {
+    diagnostics;
+    constructor(code, path, message) {
+        super(`${code} at ${path}: ${message}`);
+        this.name = "SvgAssetError";
+        this.diagnostics = [{ code, path, message }];
+    }
+}
+function fail(code, path, message) {
+    throw new SvgAssetError(code, path, message);
+}
+const own = (record, key) => record && Object.hasOwn(record, key) ? (record[key] ?? null) : null;
+const bounded = (v, min, max, path) => {
+    if (!Number.isFinite(v) || v < min || v > max)
+        fail("SVG_RANGE", path, `Expected a finite value in [${min}, ${max}].`);
+    return v;
+};
+function budgetInput(input) {
+    let count = 0, characters = 0;
+    const active = new Set();
+    function visit(v, depth) {
+        if (++count > SVG_ASSET_LIMITS.sourceValues || depth > 64)
+            fail("SVG_BUDGET", "$", "Source exceeds value or depth budget.");
+        if (typeof v === "string") {
+            characters += v.length;
+            for (const ch of v) {
+                const code = ch.codePointAt(0) ?? 0;
+                if ((code < 32 && ![9, 10, 13].includes(code)) ||
+                    (code >= 0xd800 && code <= 0xdfff) ||
+                    code === 0xfffe ||
+                    code === 0xffff)
+                    fail("SVG_STRUCTURE", "$", "Strings must be valid XML text.");
+            }
+        }
+        if (characters > SVG_ASSET_LIMITS.sourceCharacters)
+            fail("SVG_BUDGET", "$", "Source exceeds character budget.");
+        if (v && typeof v === "object") {
+            if (active.has(v))
+                fail("SVG_CYCLE", "$", "Source must be acyclic JSON data.");
+            if (!Array.isArray(v) &&
+                Object.getPrototypeOf(v) !== Object.prototype &&
+                Object.getPrototypeOf(v) !== null)
+                fail("SVG_STRUCTURE", "$", "Source must contain plain JSON objects.");
+            active.add(v);
+            for (const [k, child] of Object.entries(v)) {
+                characters += k.length;
+                visit(child, depth + 1);
+            }
+            active.delete(v);
+        }
+        else if (v !== null && !["number", "string", "boolean"].includes(typeof v))
+            fail("SVG_STRUCTURE", "$", "Source must contain JSON values.");
+    }
+    visit(input, 0);
+}
+const reserved = new Set(["time", "phase", "i", "n", "age", "life"]);
+function parameters(params, path) {
+    for (const [name, p] of Object.entries(params ?? {})) {
+        if (reserved.has(name))
+            fail("SVG_PARAMETER", `${path}.${name}`, "Reserved variable name.");
+        bounded(p.default, p.min, p.max, `${path}.${name}.default`);
+    }
+}
+function semantics(spec) {
+    parameters(spec.params, "$.params");
+    const globals = new Set(["time", "phase", ...Object.keys(spec.params ?? {})]);
+    function expressions(value, scope, path) {
+        if (typeof value === "string" && value.startsWith("$") && !scope.has(value.slice(1)))
+            fail("SVG_REFERENCE", path, `Unknown or out-of-scope variable ${value}.`);
+        if (Array.isArray(value))
+            value.forEach((v, i) => expressions(v, scope, `${path}[${i}]`));
+        else if (value && typeof value === "object")
+            for (const [k, v] of Object.entries(value))
+                expressions(v, scope, `${path}.${k}`);
+    }
+    function paint(value, path) {
+        if (typeof value === "object" && !own(spec.gradients, value.gradient))
+            fail("SVG_REFERENCE", path, `Unknown gradient ${value.gradient}.`);
+        if (typeof value === "string" && value.startsWith("@") && !own(spec.palette, value.slice(1)))
+            fail("SVG_REFERENCE", path, `Unknown palette token ${value}.`);
+    }
+    const dependencies = new Map();
+    function nodes(list, scope, path, owner, definition = false) {
+        const ids = new Set();
+        for (let i = 0; i < list.length; i++) {
+            const node = list[i];
+            if (!node)
+                continue;
+            const at = `${path}[${i}]`;
+            if (ids.has(node.id))
+                fail("SVG_DUPLICATE", `${at}.id`, "Sibling IDs must be unique.");
+            ids.add(node.id);
+            if (definition && (node.clip || node.mask || node.blur !== undefined))
+                fail("SVG_DEFINITION", at, "Clip/mask shapes cannot themselves reference clips, masks or filters.");
+            for (const [field, map] of [
+                ["clip", spec.clips],
+                ["mask", spec.masks],
+            ])
+                if (node[field] && !own(map, node[field]))
+                    fail("SVG_REFERENCE", `${at}.${field}`, "Unknown definition.");
+            paint(node.style?.fill, `${at}.style.fill`);
+            paint(node.style?.stroke, `${at}.style.stroke`);
+            for (const [k, v] of Object.entries(node))
+                if (!["id", "children", "symbol", "velocity", "acceleration", "style", "clip", "mask"].includes(k))
+                    expressions(v, scope, `${at}.${k}`);
+            expressions(node.style?.strokeWidth, scope, `${at}.style.strokeWidth`);
+            if (node.kind === "path" && node.d[0]?.[0] !== "M")
+                fail("SVG_PATH", `${at}.d`, "A path must start with M.");
+            if (node.kind === "use") {
+                const symbol = own(spec.symbols, node.symbol);
+                if (!symbol)
+                    fail("SVG_REFERENCE", `${at}.symbol`, `Unknown symbol ${node.symbol}.`);
+                for (const arg of Object.keys(node.args ?? {}))
+                    if (!own(symbol.params, arg))
+                        fail("SVG_PARAMETER", `${at}.args.${arg}`, "Argument is not declared by this symbol.");
+                if (owner)
+                    dependencies.get(owner)?.add(node.symbol);
+            }
+            if ("children" in node) {
+                const inner = new Set(scope);
+                if (node.kind === "repeat" || node.kind === "emitter") {
+                    inner.add("i");
+                    inner.add("n");
+                }
+                if (node.kind === "emitter") {
+                    inner.add("age");
+                    inner.add("life");
+                    expressions(node.velocity, inner, `${at}.velocity`);
+                    expressions(node.acceleration, inner, `${at}.acceleration`);
+                }
+                nodes(node.children, inner, `${at}.children`, owner);
+            }
+        }
+    }
+    for (const name of Object.keys(spec.symbols ?? {}))
+        dependencies.set(name, new Set());
+    for (const [name, symbol] of Object.entries(spec.symbols ?? {})) {
+        parameters(symbol.params, `$.symbols.${name}.params`);
+        nodes(symbol.children, new Set([...globals, ...Object.keys(symbol.params ?? {})]), `$.symbols.${name}.children`, name);
+    }
+    const visited = new Set(), visiting = new Set();
+    function visit(name, depth) {
+        if (visiting.has(name))
+            fail("SVG_CYCLE", `$.symbols.${name}`, "Recursive symbol expansion is not supported.");
+        if (depth > SVG_ASSET_LIMITS.depth)
+            fail("SVG_BUDGET", `$.symbols.${name}`, "Symbol graph exceeds depth budget.");
+        if (visited.has(name))
+            return;
+        visiting.add(name);
+        for (const dep of dependencies.get(name) ?? [])
+            visit(dep, depth + 1);
+        visiting.delete(name);
+        visited.add(name);
+    }
+    for (const name of dependencies.keys())
+        visit(name, 0);
+    nodes(spec.nodes, globals, "$.nodes", null);
+    for (const field of ["clips", "masks"])
+        for (const [name, shapes] of Object.entries(spec[field] ?? {}))
+            nodes(shapes, globals, `$.${field}.${name}`, null, true);
+    for (const [name, gradient] of Object.entries(spec.gradients ?? {})) {
+        expressions(gradient, globals, `$.gradients.${name}`);
+        let prev = -1;
+        for (const stop of gradient.stops) {
+            if (stop.offset < prev)
+                fail("SVG_GRADIENT", `$.gradients.${name}`, "Stops must be ordered by offset.");
+            prev = stop.offset;
+        }
+    }
+    if (spec.defaultAnimation && !own(spec.animations, spec.defaultAnimation))
+        fail("SVG_REFERENCE", "$.defaultAnimation", "Unknown animation.");
+    for (const [name, clip] of Object.entries(spec.animations ?? {})) {
+        for (const [param, keys] of Object.entries(clip.tracks)) {
+            const declaration = own(spec.params, param), at = `$.animations.${name}.tracks.${param}`;
+            if (!declaration)
+                fail("SVG_REFERENCE", at, "Tracks must target declared global parameters.");
+            if (keys[0]?.time !== 0 || keys.at(-1)?.time !== clip.duration)
+                fail("SVG_TIMELINE", at, "Keys must cover 0 through duration exactly.");
+            let prev = -1;
+            for (const key of keys) {
+                if (key.time <= prev || key.time > clip.duration)
+                    fail("SVG_TIMELINE", at, "Key times must increase strictly within duration.");
+                bounded(key.value, declaration.min, declaration.max, at);
+                prev = key.time;
+            }
+        }
+    }
+}
+function freeze(value) {
+    if (value && typeof value === "object") {
+        Object.values(value).forEach(freeze);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** Validates structure, references and the default/rest frame; never mutates caller input. */
+export function compileSvgAsset(input) {
+    try {
+        budgetInput(input);
+        const structure = checkStructure(input);
+        if (structure)
+            fail("SVG_STRUCTURE", structure.split(":")[0] ?? "$", structure);
+        const spec = JSON.parse(JSON.stringify(input));
+        semantics(spec);
+        const asset = freeze({ spec });
+        renderSvgFrame(asset, { animation: null });
+        if (spec.defaultAnimation)
+            renderSvgFrame(asset);
+        return { ok: true, asset, diagnostics: [] };
+    }
+    catch (error) {
+        if (error instanceof SvgAssetError)
+            return { ok: false, asset: null, diagnostics: error.diagnostics };
+        throw error;
+    }
+}
+export const validateSvgAsset = (input) => compileSvgAsset(input).diagnostics;
+function random(seed, key, salt) {
+    let h = (2166136261 ^ seed) >>> 0;
+    for (const ch of `${key}:${salt}`)
+        h = Math.imul(h ^ ch.charCodeAt(0), 16777619) >>> 0;
+    h = Math.imul(h ^ (h >>> 16), 0x7feb352d);
+    h = Math.imul(h ^ (h >>> 15), 0x846ca68b);
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+function evaluate(expr, ctx, path) {
+    let value;
+    if (typeof expr === "number")
+        value = expr;
+    else if (typeof expr === "string") {
+        const v = own(ctx.vars, expr.slice(1));
+        if (v === null)
+            fail("SVG_REFERENCE", path, `Unknown variable ${expr}.`);
+        value = v;
+    }
+    else {
+        const [op, ...args] = expr, values = args.map((a) => evaluate(a, ctx, path));
+        const a = values[0] ?? 0, b = values[1] ?? 0, c = values[2] ?? 0;
+        switch (op) {
+            case "add":
+                value = a + b;
+                break;
+            case "sub":
+                value = a - b;
+                break;
+            case "mul":
+                value = a * b;
+                break;
+            case "div":
+                if (b === 0)
+                    fail("SVG_ARITHMETIC", path, "Division by zero.");
+                value = a / b;
+                break;
+            case "min":
+                value = Math.min(a, b);
+                break;
+            case "max":
+                value = Math.max(a, b);
+                break;
+            case "sin":
+                value = Math.sin(a);
+                break;
+            case "cos":
+                value = Math.cos(a);
+                break;
+            case "abs":
+                value = Math.abs(a);
+                break;
+            case "clamp":
+                if (b > c)
+                    fail("SVG_RANGE", path, "Clamp bounds are reversed.");
+                value = Math.min(c, Math.max(b, a));
+                break;
+            case "mix":
+                value = a + (b - a) * c;
+                break;
+            case "rand":
+                if (b > c)
+                    fail("SVG_RANGE", path, "Random bounds are reversed.");
+                value = b + random(ctx.seed, ctx.key, a) * (c - b);
+                break;
+        }
+    }
+    return bounded(value, -1e9, 1e9, path);
+}
+const number = (v) => String(Number(v.toFixed(6)));
+const escape = (v) => v
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll("'", "&apos;");
+const attrs = (record) => Object.entries(record)
+    .map(([k, v]) => ` ${k}="${escape(typeof v === "number" ? number(v) : v)}"`)
+    .join("");
+/** A seek is independent of every previous sample. Loop endpoints wrap; one-shots hold. */
+export function sampleSvgParameters(asset, options = {}) {
+    const spec = asset.spec, time = bounded(options.time ?? 0, 0, 1e6, "options.time");
+    const name = options.animation === undefined ? spec.defaultAnimation : options.animation;
+    const clip = name ? own(spec.animations, name) : null;
+    if (name && !clip)
+        fail("SVG_REFERENCE", "options.animation", `Unknown animation ${name}.`);
+    const t = clip ? (clip.loop ? time % clip.duration : Math.min(time, clip.duration)) : time;
+    const params = Object.fromEntries(Object.entries(spec.params ?? {}).map(([k, v]) => [k, v.default]));
+    if (clip)
+        for (const [param, keys] of Object.entries(clip.tracks)) {
+            let value = keys.at(-1)?.value ?? 0;
+            for (let i = 1; i < keys.length; i++) {
+                const a = keys[i - 1], b = keys[i];
+                if (!a || !b || t >= b.time)
+                    continue;
+                let u = (t - a.time) / (b.time - a.time);
+                if (a.ease === "hold")
+                    u = 0;
+                if (a.ease === "smooth")
+                    u = u * u * (3 - 2 * u);
+                value = a.value + (b.value - a.value) * u;
+                break;
+            }
+            params[param] = value;
+        }
+    for (const [key, value] of Object.entries(options.params ?? {})) {
+        const declaration = own(spec.params, key);
+        if (!declaration)
+            fail("SVG_PARAMETER", `options.params.${key}`, "Unknown parameter.");
+        params[key] = bounded(value, declaration.min, declaration.max, `options.params.${key}`);
+    }
+    return { time: t, phase: clip ? t / clip.duration : 0, params };
+}
+function frame(asset, options) {
+    const spec = asset.spec, sampled = sampleSvgParameters(asset, options), prefix = options.prefix ?? "asset";
+    if (!/^[A-Za-z][A-Za-z0-9_-]{0,79}$/.test(prefix))
+        fail("SVG_ID", "options.prefix", "Use a letter followed by up to 79 letters, digits, hyphens or underscores.");
+    const context = {
+        vars: { ...sampled.params, time: sampled.time, phase: sampled.phase },
+        seed: spec.seed ?? 0,
+        key: "root",
+    };
+    let count = 0, characters = 0;
+    const defs = [];
+    const id = (kind, name) => `${prefix}-${kind}-${name}`;
+    function emit(text) {
+        characters += text.length;
+        if (characters > SVG_ASSET_LIMITS.outputCharacters)
+            fail("SVG_BUDGET", "$", "Frame output exceeds character budget.");
+        return text;
+    }
+    const scalar = (expr, fallback, ctx, path) => evaluate(expr ?? fallback, ctx, path);
+    const point = (p, fallback, ctx, path) => [scalar(p?.[0], fallback[0], ctx, path), scalar(p?.[1], fallback[1], ctx, path)];
+    const paint = (p) => typeof p === "object"
+        ? `url(#${id("gradient", p.gradient)})`
+        : p.startsWith("@")
+            ? (own(spec.palette, p.slice(1)) ?? "none")
+            : p;
+    function common(node, ctx, path) {
+        const a = { "data-part": path };
+        if (node.transform) {
+            const tr = node.transform, [tx, ty] = point(tr.translate, [0, 0], ctx, path), [px, py] = point(tr.pivot, [0, 0], ctx, path), [sx, sy] = point(tr.scale, [1, 1], ctx, path);
+            a.transform = `translate(${number(tx)} ${number(ty)}) translate(${number(px)} ${number(py)}) rotate(${number(scalar(tr.rotate, 0, ctx, path))}) scale(${number(sx)} ${number(sy)}) translate(${number(-px)} ${number(-py)})`;
+        }
+        if (node.opacity !== undefined)
+            a.opacity = bounded(evaluate(node.opacity, ctx, path), 0, 1, path);
+        const s = node.style;
+        if (s?.fill)
+            a.fill = paint(s.fill);
+        if (s?.stroke)
+            a.stroke = paint(s.stroke);
+        if (s?.strokeWidth !== undefined)
+            a["stroke-width"] = bounded(evaluate(s.strokeWidth, ctx, path), 0, 1e6, path);
+        if (s?.linecap)
+            a["stroke-linecap"] = s.linecap;
+        if (s?.linejoin)
+            a["stroke-linejoin"] = s.linejoin;
+        if (s?.fillRule) {
+            a["fill-rule"] = s.fillRule;
+            a["clip-rule"] = s.fillRule;
+        }
+        if (node.clip)
+            a["clip-path"] = `url(#${id("clip", node.clip)})`;
+        if (node.mask)
+            a.mask = `url(#${id("mask", node.mask)})`;
+        if (node.blur !== undefined) {
+            const blur = bounded(evaluate(node.blur, ctx, path), 0, 100, path), filterId = id("blur", String(count));
+            defs.push(emit(`<filter${attrs({ id: filterId, x: "-100%", y: "-100%", width: "300%", height: "300%", "color-interpolation-filters": "sRGB" })}><feGaussianBlur stdDeviation="${number(blur)}"/></filter>`));
+            a.filter = `url(#${filterId})`;
+        }
+        return attrs(a);
+    }
+    function shape(node, ctx, path, attributes) {
+        const e = (v) => evaluate(v, ctx, path), positive = (v) => bounded(e(v), 0, 1e6, path);
+        if (node.kind === "rect")
+            return emit(`<rect${attributes}${attrs({ x: e(node.x), y: e(node.y), width: positive(node.width), height: positive(node.height), rx: positive(node.radius ?? 0) })}/>`);
+        if (node.kind === "ellipse")
+            return emit(`<ellipse${attributes}${attrs({ cx: e(node.cx), cy: e(node.cy), rx: positive(node.rx), ry: positive(node.ry) })}/>`);
+        const d = node.d
+            .map(([command, ...args]) => {
+            const values = args.map((value) => e(value));
+            if (command === "A" && ((values[0] ?? 0) < 0 || (values[1] ?? 0) < 0))
+                fail("SVG_RANGE", path, "Arc radii must be nonnegative.");
+            return `${command}${values.map(number).join(" ")}`;
+        })
+            .join(" ");
+        return emit(`<path${attributes} d="${d}"/>`);
+    }
+    function nodes(list, ctx, path, depth) {
+        if (depth > SVG_ASSET_LIMITS.depth)
+            fail("SVG_BUDGET", path, "Expansion exceeds depth budget.");
+        return list
+            .map((node) => {
+            if (++count > SVG_ASSET_LIMITS.nodesPerFrame)
+                fail("SVG_BUDGET", path, "Expanded frame exceeds node budget.");
+            const at = `${path}/${node.id}`, local = { ...ctx, key: at }, a = common(node, local, at);
+            if (node.kind === "rect" || node.kind === "ellipse" || node.kind === "path")
+                return shape(node, local, at, a);
+            let body;
+            if (node.kind === "use") {
+                const symbol = own(spec.symbols, node.symbol);
+                if (!symbol)
+                    fail("SVG_REFERENCE", at, "Unknown symbol.");
+                // Symbols have lexical scope: globals plus declared arguments, never caller loop locals.
+                const vars = { ...context.vars };
+                for (const [name, p] of Object.entries(symbol.params ?? {}))
+                    vars[name] = bounded(scalar(own(node.args, name), p.default, local, at), p.min, p.max, at);
+                body = nodes(symbol.children, { ...local, vars }, `${at}/${node.symbol}`, depth + 1);
+            }
+            else if (node.kind === "group")
+                body = nodes(node.children, local, at, depth + 1);
+            else {
+                const instances = [];
+                for (let i = 0; i < node.count; i++) {
+                    const key = `${at}/${i}`, vars = { ...ctx.vars, i, n: node.count }, child = { ...ctx, key, vars };
+                    if (node.kind === "emitter") {
+                        const elapsed = sampled.time - (node.start ?? 0);
+                        if (elapsed < 0)
+                            continue;
+                        const life = node.mode === "loop" ? (elapsed + (i * node.lifetime) / node.count) % node.lifetime : elapsed;
+                        if (life >= node.lifetime)
+                            continue;
+                        Object.assign(vars, { life, age: life / node.lifetime });
+                        const [vx, vy] = point(node.velocity, [0, 0], child, key), [ax, ay] = point(node.acceleration, [0, 0], child, key);
+                        const x = bounded(vx * life + (ax * life * life) / 2, -1e9, 1e9, key), y = bounded(vy * life + (ay * life * life) / 2, -1e9, 1e9, key);
+                        const contents = nodes(node.children, child, key, depth + 1);
+                        instances.push(emit(`<g transform="translate(${number(x)} ${number(y)})">`) + contents + emit("</g>"));
+                    }
+                    else
+                        instances.push(nodes(node.children, child, key, depth + 1));
+                }
+                body = instances.join("");
+            }
+            return emit(`<g${a}>`) + body + emit("</g>");
+        })
+            .join("");
+    }
+    for (const [name, gradient] of Object.entries(spec.gradients ?? {})) {
+        const a = { id: id("gradient", name), gradientUnits: "userSpaceOnUse" };
+        if (gradient.kind === "linear") {
+            const [x1, y1] = point(gradient.from, [0, 0], context, name), [x2, y2] = point(gradient.to, [1, 1], context, name);
+            Object.assign(a, { x1, y1, x2, y2 });
+        }
+        else {
+            const [cx, cy] = point(gradient.center, [0, 0], context, name);
+            Object.assign(a, { cx, cy, r: bounded(evaluate(gradient.radius, context, name), 0.000001, 1e6, name) });
+        }
+        const tag = gradient.kind === "linear" ? "linearGradient" : "radialGradient";
+        defs.push(emit(`<${tag}${attrs(a)}>${gradient.stops.map((s) => `<stop${attrs({ offset: s.offset, "stop-color": s.color, "stop-opacity": s.opacity ?? 1 })}/>`).join("")}</${tag}>`));
+    }
+    for (const field of ["clips", "masks"])
+        for (const [name, shapes] of Object.entries(spec[field] ?? {})) {
+            const tag = field === "clips" ? "clipPath" : "mask", kind = field === "clips" ? "clip" : "mask";
+            const a = field === "clips"
+                ? { id: id(kind, name), clipPathUnits: "userSpaceOnUse" }
+                : {
+                    id: id(kind, name),
+                    maskUnits: "userSpaceOnUse",
+                    maskContentUnits: "userSpaceOnUse",
+                    x: spec.viewBox[0],
+                    y: spec.viewBox[1],
+                    width: spec.viewBox[2],
+                    height: spec.viewBox[3],
+                };
+            defs.push(emit(`<${tag}${attrs(a)}>`), nodes(shapes, context, `${field}/${name}`, 0), emit(`</${tag}>`));
+        }
+    const body = nodes(spec.nodes, context, "root", 0);
+    return { defs: defs.join(""), body };
+}
+function document(asset, defs, body) {
+    const spec = asset.spec;
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${spec.viewBox.join(" ")}" width="${spec.viewBox[2]}" height="${spec.viewBox[3]}" role="img" aria-label="${escape(spec.name)}"><title>${escape(spec.name)}</title><defs>${defs}</defs>${body}</svg>`;
+}
+export function renderSvgFrame(asset, options = {}) {
+    const { defs, body } = frame(asset, options);
+    return document(asset, defs, body);
+}
+/** Script-free sampled SVG playback. Frame sampling is deliberate, bounded and portable. */
+export function exportSvgAnimation(asset, options = {}) {
+    const name = options.animation ?? asset.spec.defaultAnimation, clip = name ? own(asset.spec.animations, name) : null;
+    if (!clip || !name)
+        fail("SVG_REFERENCE", "options.animation", "Select an existing animation.");
+    const fps = bounded(options.fps ?? 24, 1, 60, "options.fps"), steps = Math.ceil(clip.duration * fps), count = steps + (clip.loop ? 0 : 1);
+    if (count > SVG_ASSET_LIMITS.frames)
+        fail("SVG_BUDGET", "options.fps", `Animation exceeds ${SVG_ASSET_LIMITS.frames} frames; lower fps or shorten the clip.`);
+    const defs = [], bodies = [];
+    let size = 0;
+    for (let i = 0; i < count; i++) {
+        const { defs: definition, body } = frame(asset, {
+            ...options,
+            animation: name,
+            time: (i * clip.duration) / steps,
+            prefix: `${options.prefix ?? "asset"}-f${i}`,
+        });
+        const times = [0], values = [i === 0 ? "inline" : "none"];
+        if (i > 0) {
+            times.push(i / steps);
+            values.push("inline");
+        }
+        if (i < steps) {
+            times.push((i + 1) / steps);
+            values.push("none");
+        }
+        const animation = `<animate${attrs({ attributeName: "display", calcMode: "discrete", values: values.join(";"), keyTimes: times.map(String).join(";"), dur: `${clip.duration}s`, repeatCount: clip.loop ? "indefinite" : "1", fill: "freeze" })}/>`;
+        const group = `<g data-frame="${i}" display="${i === 0 ? "inline" : "none"}">${animation}${body}</g>`;
+        size += definition.length + group.length;
+        if (size > SVG_ASSET_LIMITS.outputCharacters)
+            fail("SVG_BUDGET", "$", "Animation exceeds output character budget; lower fps or simplify the asset.");
+        defs.push(definition);
+        bodies.push(group);
+    }
+    return document(asset, defs.join(""), bodies.join(""));
+}

package/dist/text.d.ts

@@ -0,0 +1,12 @@
+/** A representation-neutral syntax repair. Never changes a JSON field, value or relationship. */
+export interface TextEdit {
+    start: number;
+    end: number;
+    replacement: string;
+}
+export interface TextRepair {
+    text: string;
+    edits: TextEdit[];
+    code: "JSON_TRAILING_DELIMITER" | "JSON_MISSING_DELIMITER";
+}
+export declare function repairJSONDelimiters(input: string): TextRepair | null;

package/dist/text.js

@@ -0,0 +1,75 @@
+import { requireValue } from "./required.js";
+export function repairJSONDelimiters(input) {
+    if (input.length > 1_000_000)
+        return null;
+    try {
+        JSON.parse(input);
+        return null;
+    }
+    catch {
+        /* A repair must be needed. */
+    }
+    const stack = [];
+    let quoted = false, escaped = false, rootEnd = -1;
+    for (let i = 0; i < input.length; i++) {
+        const c = requireValue(input[i]);
+        if (quoted) {
+            if (escaped)
+                escaped = false;
+            else if (c === "\\")
+                escaped = true;
+            else if (c === '"')
+                quoted = false;
+            continue;
+        }
+        if (c === '"') {
+            quoted = true;
+            continue;
+        }
+        if (c === "{" || c === "[")
+            stack.push(c);
+        else if (c === "}" || c === "]") {
+            const expected = c === "}" ? "{" : "[";
+            if (stack.pop() !== expected)
+                return null;
+            if (!stack.length) {
+                rootEnd = i + 1;
+                break;
+            }
+        }
+    }
+    if (rootEnd >= 0) {
+        const tail = input.slice(rootEnd).trim();
+        if (!/^[}\]]{1,3}$/.test(tail))
+            return null;
+        const text = input.slice(0, rootEnd);
+        try {
+            JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        return {
+            text,
+            edits: [{ start: rootEnd, end: input.length, replacement: "" }],
+            code: "JSON_TRAILING_DELIMITER",
+        };
+    }
+    if (quoted || !stack.length || stack.length > 3)
+        return null;
+    const suffix = stack
+        .reverse()
+        .map((c) => (c === "{" ? "}" : "]"))
+        .join(""), text = input + suffix;
+    try {
+        JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    return {
+        text,
+        edits: [{ start: input.length, end: input.length, replacement: suffix }],
+        code: "JSON_MISSING_DELIMITER",
+    };
+}