@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/types.d.ts

@@ -0,0 +1,478 @@
+export type Vec3 = [number, number, number];
+export interface MeshData {
+    positions: number[];
+    normals: number[];
+    colors: number[];
+    indices: number[];
+    /**
+     * Per-vertex joint indices. Legacy compatibility meshes use adapter-defined IDs. Schema 0.2
+     * compilations index `CompiledAsset.skeleton.joints`; -1 marks a static vertex.
+     */
+    joints?: number[];
+    /** Optional joint pivot heights, owned by the consuming adapter. */
+    rigPivots?: readonly [number, number];
+}
+export type Scalar = number | {
+    parameter: string;
+};
+export interface Point {
+    x: Scalar;
+    y: Scalar;
+    z: Scalar;
+}
+export type Anchor = "center" | "top-center" | "bottom-center" | "left-center" | "right-center" | "front-center" | "back-center";
+export interface Size {
+    width: Scalar;
+    height: Scalar;
+    depth: Scalar;
+}
+/**
+ * `sides` (schema 0.3) is an integer from 3 to 32; round shapes default to 16 sides and spheres
+ * and ellipsoids to 12 meridians.
+ */
+export type Shape = {
+    type: "box";
+    size: Size;
+    bevel?: Scalar;
+} | {
+    type: "cylinder";
+    radius: Scalar;
+    height: Scalar;
+    sides?: number;
+} | {
+    type: "funnel";
+    bottomRadius: Scalar;
+    topRadius: Scalar;
+    height: Scalar;
+    sides?: number;
+} | {
+    type: "beam";
+    from: Point;
+    to: Point;
+    width: Scalar;
+} | {
+    type: "tube";
+    from: Point;
+    to: Point;
+    radius: Scalar;
+    sides?: number;
+} | {
+    type: "coil";
+    radius: Scalar;
+    thickness: Scalar;
+    sides?: number;
+}
+/** Schema 0.3. Bottom-centered: spans y = 0 to 2 × radius. */
+ | {
+    type: "sphere";
+    radius: Scalar;
+    sides?: number;
+}
+/** Schema 0.3. Bottom-centered, spanning the given size. */
+ | {
+    type: "ellipsoid";
+    size: Size;
+    sides?: number;
+}
+/** Schema 0.3. Base at y = 0, apex at y = height. */
+ | {
+    type: "cone";
+    radius: Scalar;
+    height: Scalar;
+    sides?: number;
+}
+/** Schema 0.3. Full-height back face (+Z); the slope descends to the front-bottom edge. */
+ | {
+    type: "wedge";
+    size: Size;
+}
+/** Schema 0.3. Surface of revolution about the local Y axis; y is non-decreasing. */
+ | {
+    type: "lathe";
+    profile: {
+        radius: Scalar;
+        y: Scalar;
+    }[];
+    sides?: number;
+}
+/** Schema 0.3. A simple X-Z outline extruded from y = 0 to height. */
+ | {
+    type: "extrude";
+    outline: {
+        x: Scalar;
+        z: Scalar;
+    }[];
+    height: Scalar;
+};
+/** Schema 0.3: degrees about the local origin, applied X, then Y, then Z (fixed axes). */
+export interface Rotation {
+    x?: Scalar;
+    y?: Scalar;
+    z?: Scalar;
+}
+/** Schema 0.3: copies of one part. Instance IDs are part/0 … part/n−1. */
+export type ArraySpec = {
+    type: "line";
+    count: number;
+    step: Point;
+    centered?: boolean;
+} | {
+    type: "grid";
+    count: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    spacing: {
+        x?: Scalar;
+        y?: Scalar;
+        z?: Scalar;
+    };
+    centered?: boolean;
+} | {
+    type: "radial";
+    count: number;
+    radius: Scalar;
+    axis?: "x" | "y" | "z";
+    start?: Scalar;
+    sweep?: Scalar;
+    orient?: boolean;
+};
+export type Placement = {
+    type: "absolute";
+    selfAnchor: string;
+    position: Point;
+} | {
+    type: "attach";
+    selfAnchor: string;
+    target: {
+        part: string;
+        anchor: string;
+    };
+    offset?: Point;
+} | {
+    type: "repeat";
+    pattern: "corners";
+    selfAnchor: string;
+    target: {
+        part: string;
+        face: "top" | "bottom";
+    };
+    edgeInset: {
+        x: Scalar;
+        z: Scalar;
+    };
+};
+export interface PartSpec {
+    shape: Shape;
+    material: string;
+    placement: Placement;
+    parent?: string;
+    anchors?: Record<string, Point>;
+    /** Schema 0.2: rigid binding to a joint. Attached parts inherit their target's joint. */
+    joint?: string;
+    /** Schema 0.2: author the character's left (−X) side; the right side is its mirror image. */
+    sides?: "both";
+    /** Schema 0.2: the part exists only when its slot selects this option. */
+    slot?: string;
+    option?: string;
+    /** Schema 0.2: visible only while every listed state channel is in one of its states. */
+    when?: Record<string, string[]>;
+    /** Schema 0.3: static orientation of the shape and its custom anchors before placement. */
+    rotation?: Rotation;
+    /** Schema 0.3: repeat the placed part along a line, on a grid or around a circle. */
+    array?: ArraySpec;
+}
+export type Axis = "+x" | "-x" | "+y" | "-y" | "+z" | "-z";
+export interface DofSpec {
+    name: string;
+    axis: Axis;
+    /** Degrees. The rest value 0 must lie within the limits. */
+    limits: [number, number];
+    /**
+     * Schema 0.3: a free-spinning DOF (wheels, rotors, clock hands). A looping clip may close after
+     * whole turns, e.g. keys 0° at 0 and 360° at 1, and keeps turning instead of rewinding.
+     */
+    continuous?: boolean;
+}
+export interface JointSpec {
+    parent?: string;
+    sides?: "both";
+    /** Face joints are animated by expressions; all other joints by poses. */
+    face?: boolean;
+    pivot: {
+        part: string;
+        anchor: string;
+    } | {
+        position: Point;
+    };
+    dofs: DofSpec[];
+}
+export interface IdentitySpec {
+    parameters?: Record<string, number>;
+    materials?: Record<string, {
+        color: string;
+    }>;
+    slots?: Record<string, string>;
+}
+export type SchemaVersion = "asset-assembly/0.1" | "asset-assembly/0.2" | "asset-assembly/0.3";
+export interface AssetSpec {
+    schema: SchemaVersion;
+    units: "meters" | "tiles";
+    parameters?: Record<string, number>;
+    materials: Record<string, {
+        color: string;
+        tintable?: boolean;
+    }>;
+    groups?: Record<string, {
+        parent?: string;
+        position: Point;
+    }>;
+    parts: Record<string, PartSpec>;
+    groundPivot?: Point;
+    /** Schema 0.2. */
+    joints?: Record<string, JointSpec>;
+    /** Schema 0.2: ordered options; the first is the default. */
+    slots?: Record<string, string[]>;
+    /** Schema 0.2: bounded overrides of declared parameters, colors and slots. */
+    identities?: Record<string, IdentitySpec>;
+    /** Schema 0.2: animated visibility channels; the first state is the rest state. */
+    states?: Record<string, string[]>;
+    /** Schema 0.2: chains a clip may solve to keep planted effectors in place. */
+    limbs?: Record<string, LimbSpec>;
+}
+export interface LimbSpec {
+    sides?: "both";
+    /** The point kept planted, e.g. the ankle anchor of a foot. */
+    effector: {
+        part: string;
+        anchor: string;
+    };
+    /** One to three DOFs solved to place the effector, from the root of the chain outward. */
+    reach: {
+        joint: string;
+        dof: string;
+    }[];
+    /** Optional DOF solved to keep the effector part level (its front horizontal). */
+    level?: {
+        joint: string;
+        dof: string;
+    };
+}
+export interface CompiledLimb {
+    id: string;
+    effector: string;
+    anchor: string;
+    reach: {
+        joint: string;
+        dof: string;
+    }[];
+    level?: {
+        joint: string;
+        dof: string;
+    };
+}
+export interface Diagnostic {
+    code: string;
+    path: string;
+    message: string;
+    part?: string;
+    targetPart?: string;
+    received?: unknown;
+    expected?: readonly string[];
+    /** Identity whose compilation produced the diagnostic (schema 0.2 validation). */
+    identity?: string;
+}
+export interface Bounds {
+    min: Vec3;
+    max: Vec3;
+}
+export interface ResolvedInstance {
+    id: string;
+    part: string;
+    material: string;
+    translation: Vec3;
+    bounds: Bounds;
+    anchors: Record<string, Vec3>;
+    mesh: MeshData;
+    /** Schema 0.2: compiled joint ID this instance follows, or null when static. */
+    joint?: string | null;
+    /** Schema 0.2: effective visibility conditions, including those inherited from attachment targets. */
+    when?: Record<string, string[]>;
+}
+export interface CompiledDof {
+    name: string;
+    /** Unit rotation axis in the asset frame (sign included; mirrored for right-side joints). */
+    axis: Vec3;
+    limits: [number, number];
+    /** Present and true for continuous DOFs (schema 0.3). */
+    continuous?: true;
+}
+export interface CompiledJoint {
+    id: string;
+    /** Declaring joint ID; equal to `id` unless the joint is sided. */
+    joint: string;
+    side?: "left" | "right";
+    /** Schema 0.3: index of this copy when the joint pivots on an arrayed part (IDs <joint>/<copy>). */
+    copy?: number;
+    /** Present and true for face joints. */
+    face?: true;
+    parent: string | null;
+    /** Rest-pose pivot in the asset frame. Rest frames are translation-only. */
+    pivot: Vec3;
+    dofs: CompiledDof[];
+}
+export interface Skeleton {
+    /** Parents precede children; ties are ordered by ID. */
+    joints: CompiledJoint[];
+}
+export interface CompiledAsset {
+    schema: SchemaVersion;
+    units: "meters" | "tiles";
+    sourceHash: string;
+    layers: Record<string, MeshData>;
+    materials: AssetSpec["materials"];
+    instances: ResolvedInstance[];
+    bounds: Bounds;
+    groundPivot: Vec3;
+    triangles: number;
+    /** Schema 0.2 only. */
+    skeleton?: Skeleton;
+    identity?: string | null;
+    slots?: Record<string, string>;
+    /** Declared state channels and their states (rest state first). */
+    states?: Record<string, string[]>;
+    /** Instances hidden in the rest states; poseAsset shows them when a pose selects their states. */
+    alternates?: ResolvedInstance[];
+    limbs?: CompiledLimb[];
+    /** Present on assets returned by poseAsset. */
+    pose?: {
+        clip: string;
+        phase: number;
+    };
+}
+export interface CompileOptions {
+    maxInstances?: number;
+    maxTriangles?: number;
+    /** Schema 0.2: compile one declared identity. Omit for the base description. */
+    identity?: string;
+}
+export type JointValues = Record<string, Record<string, number>>;
+export interface MotionKeySpec {
+    at: number;
+    pose?: string;
+    expression?: string;
+    joints?: JointValues;
+    states?: Record<string, string>;
+}
+export type Grounding = {
+    type: "none";
+} | {
+    type: "contacts";
+} | {
+    type: "anchor";
+    part: string;
+    anchor: string;
+};
+export interface ClipSpec {
+    duration: number;
+    loop: boolean;
+    interpolation?: "smooth" | "linear" | "step";
+    symmetry?: "none" | "alternate";
+    keys: MotionKeySpec[];
+    contacts?: Record<string, [number, number][]>;
+    grounding?: Grounding;
+    travel?: "contacts" | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Solve declared limbs so planted effectors stay where they touched down. */
+    solve?: "none" | "planted";
+}
+export interface MotionSpec {
+    schema: "motion-set/0.1";
+    poses?: Record<string, {
+        joints: JointValues;
+    }>;
+    expressions?: Record<string, {
+        joints?: JointValues;
+        states?: Record<string, string>;
+    }>;
+    clips: Record<string, ClipSpec>;
+}
+export interface MotionChannel {
+    joint: string;
+    dof: string;
+    /** Sorted key times (normalized 0–1) and degrees. */
+    times: number[];
+    values: number[];
+    /** Hermite tangents in degrees per normalized time unit. */
+    tangents: number[];
+    /** Continuous DOFs: degrees added per loop (a whole number of turns). */
+    cycle?: number;
+}
+export interface StateTrack {
+    channel: string;
+    /** Sorted key times; each state holds until the next key (step). */
+    times: number[];
+    values: string[];
+}
+export interface ContactTrack {
+    effector: string;
+    intervals: [number, number][];
+}
+export interface ClipMetrics {
+    /** Largest planted-effector horizontal drift from its touchdown point, in asset units. */
+    maxSlip: number;
+    /** Largest planted-effector height above the ground, in asset units. */
+    maxLift: number;
+    /** Lowest sampled vertex height (ground grounding only), in asset units. */
+    minHeight: number;
+    /** Root travel speed in asset units per second. */
+    speed: number;
+}
+export interface CompiledClip {
+    name: string;
+    duration: number;
+    loop: boolean;
+    interpolation: "smooth" | "linear" | "step";
+    symmetry: "none" | "alternate";
+    channels: MotionChannel[];
+    states: StateTrack[];
+    /** True when the clip keys only face joints and states, so it can overlay any body clip. */
+    face: boolean;
+    contacts: ContactTrack[];
+    grounding: Grounding;
+    solve: "none" | "planted";
+    /** Root displacement per clip cycle in asset units. */
+    travel: Vec3;
+    metrics: ClipMetrics;
+}
+export interface CompiledMotion {
+    schema: "motion-set/0.1";
+    sourceHash: string;
+    assetHash: string;
+    poses: Record<string, CompiledClip>;
+    expressions: Record<string, CompiledClip>;
+    clips: Record<string, CompiledClip>;
+}
+/** A rigid transform as a row-major 3×4 matrix: [r00 r01 r02 tx r10 r11 r12 ty r20 r21 r22 tz]. */
+export type Transform = number[];
+export interface SampledPose {
+    clip: string;
+    phase: number;
+    /** Face overlay clip name, when one was sampled. */
+    face?: string;
+    /** Degrees per compiled joint and DOF. */
+    values: JointValues;
+    /** Current state per declared channel. */
+    states: Record<string, string>;
+    /** Grounding offset applied to the whole asset. */
+    root: Vec3;
+    /** Cumulative travel for the host to apply to the entity; not applied by poseAsset. */
+    travel: Vec3;
+    transforms: Record<string, Transform>;
+    /** Effectors planted at this phase. */
+    contacts: string[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/svg/README.md

@@ -0,0 +1,150 @@
+# SVG Asset Notation 0.1
+
+**Proposal:** use `svg-asset/0.1`, a typed JSON construction language whose output is SVG. An asset consists of named parts in local coordinate systems, reusable symbols, bounded parameters, and named animation clips. The same parameters construct a still image and animate it. Characters, interiors and effects share one compiler; there are no built-in fox, room or portal node types.
+
+The 0.1 implementation is complete for the contract below. It is an initial version, not a claim of universal asset generation, visual approval, natural motion or a stable 1.0 API. It was first included in package version 0.4.0; **0.1 is the notation version**. This work adds the isolated `@ludic-labs/assembly/svg` entry point without changing the existing mesh compiler. The documentation includes [Ember’s Waygate](https://libraries.ludic-assembly.victorqueiroz.dev/svg/), a playable C++23/WebAssembly and WebGL 1.0 showcase, plus an [asset atelier](https://libraries.ludic-assembly.victorqueiroz.dev/svg/atelier/) for editing and exporting the examples.
+
+## What 0.1 delivers
+
+The effect collection includes the original waygate plus [aurora ribbon](../../examples/svg/aurora-ribbon.json), [ember fountain](../../examples/svg/ember-fountain.json) and [arcane shield](../../examples/svg/arcane-shield.json). Each has bounded editable parameters and a looping clip; the atelier exports the exact JSON, still SVG and self-playing SVG. Homepage previews start still and offer an explicit play/pause control. These are original examples, not a new notation version or a performance qualification.
+
+| Area         | Implemented                                                                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Construction | Ordered groups; local translate, rotate, scale and pivot; named symbol instances with local numeric arguments; bounded repetition                             |
+| Geometry     | Rounded rectangles, ellipses, absolute lines, quadratic/cubic Béziers and elliptical arcs, multiple path subpaths                                             |
+| Appearance   | Palette tokens, fill/stroke, line caps/joins, fill rules, opacity, linear/radial gradients, clips, luminance masks and Gaussian blur                          |
+| Animation    | Named clips, seconds-based keys, linear/smooth/hold interpolation, loops, one-shots, direct seeking, parameter-driven path deformation and articulated groups |
+| Effects      | Seeded, repeated particle instances; loop/burst lifetimes, velocity/acceleration and age-driven size/opacity/geometry                                         |
+| Delivery     | Static SVG, self-playing SVG without scripts, SVG frame sequences with timing manifests, a CLI and a browser authoring preview                                |
+| Validation   | TypeScript types, JSON Schema, structured diagnostics, reference/scope/cycle checks, numeric and expansion limits                                             |
+
+Arbitrary Bézier paths, composition and reusable definitions give broad **2D vector expressiveness**. They do not give infinite computational capacity, automatically infer good art, or cover every feature of SVG. A producer still authors or generates a valid definition. In particular, 0.1 has no raster import, font-dependent text, boolean geometry solver, automatic rigging, IK, skinning, physics, clip blending, topology-changing path interpolation, 3D reconstruction, or text-to-image model. Complex artwork can be represented with more authored paths within the declared budgets.
+
+## Research basis
+
+The language and implementation are our engineering synthesis. These original works inform specific decisions; none of their learned models or complete algorithms is reproduced.
+
+| Original source                                                                                                                                                                                                  | Evidence reviewed                                                                                                               | Decision in 0.1                                                                                                                            | Boundary                                                                                                                         |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Jones et al., [ShapeAssembly: Learning to Generate Programs for 3D Shape Structure Synthesis](https://arxiv.org/html/2009.08026v1), ACM TOG 39(6), 2020, DOI 10.1145/3414685.3417812                             | Abstract, introduction and language discussion: hierarchical part programs and continuous parameters describe editable families | Named local groups, explicit symbols and arguments, repeat operations, parameters retained in the source                                   | This is a 2D authoring language; no cuboid attachment solver, PartNet extraction, VAE or learned synthesis                       |
+| Lasseter, [Principles of Traditional Animation Applied to 3D Computer Animation](https://www.cs.cmu.edu/afs/cs/academic/class/15462-f13/www/lec_slides/Lesseter.pdf), SIGGRAPH 1987, pp. 35–44                   | Original scanned paper, pp. 36–38: squash/stretch, timing, anticipation, staging and their relation to key poses                | Independent pose parameters, explicit clip timing, local pivots, squash/stretch through scale, authored secondary motion                   | Smoothstep is our interpolation choice; exposing controls does not guarantee appealing movement or preserve volume automatically |
+| Reeves, [Particle Systems—A Technique for Modeling a Class of Fuzzy Objects](https://graphics.stanford.edu/courses/cs448-01-spring/papers/reeves.pdf), ACM TOG 2(2), 1983, pp. 91–108, DOI 10.1145/357318.357320 | Abstract and §2: particle birth, attributes, lifetime, transformation and stochastic control                                    | Bounded emitters, age/lifetime variables, seeded variation and analytic per-sample movement                                                | Our particles are SVG subtrees, with fixed populations and direct seeking; no volumetric rendering, fluid model or motion blur   |
+| Li et al., [Differentiable Vector Graphics Rasterization for Editing and Learning](https://people.csail.mit.edu/tzumao/diffvg/), ACM TOG 39(6), 2020                                                             | Author-hosted abstract and application descriptions                                                                             | Retain numeric curve controls and keep construction separate from raster evaluation, so a later optimizer could adjust declared parameters | No differentiable rasterizer, optimization loop or image-fitting result is implemented or claimed                                |
+
+The animation export uses SVG's discrete `animate` timing semantics, verified against [MDN keyTimes](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/keyTimes) and the browser engines. The transform, paint-order and definition model follows [SVG 2](https://www.w3.org/TR/SVG2/). These are implementation standards, not research evidence for visual quality.
+
+All three example designs are original vector constructions authored for this implementation. No itch.io artwork was copied, downloaded or traced. The earlier reviewed fox geometry, owner preferences, captured hashes and private SVG projector remain separate; this new fox is not the accepted fur-C asset.
+
+## A complete small definition
+
+`$lift` reads a parameter. `['add', a, b]` is data describing arithmetic, not executable JavaScript. This asset bobs and squashes using a one-second loop:
+
+```json
+{
+  "schema": "svg-asset/0.1",
+  "name": "Bouncing ember",
+  "viewBox": [0, 0, 100, 100],
+  "params": {
+    "lift": { "default": 0, "min": -25, "max": 0 },
+    "squash": { "default": 1, "min": 0.8, "max": 1.2 }
+  },
+  "nodes": [
+    {
+      "id": "ember",
+      "kind": "ellipse",
+      "cx": 50,
+      "cy": 65,
+      "rx": 16,
+      "ry": 20,
+      "style": { "fill": "#edb95f" },
+      "transform": {
+        "translate": [0, "$lift"],
+        "pivot": [50, 85],
+        "scale": [["div", 1, "$squash"], "$squash"]
+      }
+    }
+  ],
+  "animations": {
+    "bounce": {
+      "duration": 1,
+      "loop": true,
+      "tracks": {
+        "lift": [
+          { "time": 0, "value": 0, "ease": "smooth" },
+          { "time": 0.5, "value": -25, "ease": "smooth" },
+          { "time": 1, "value": 0 }
+        ],
+        "squash": [
+          { "time": 0, "value": 0.8, "ease": "smooth" },
+          { "time": 0.5, "value": 1.2, "ease": "smooth" },
+          { "time": 1, "value": 0.8 }
+        ]
+      }
+    }
+  },
+  "defaultAnimation": "bounce"
+}
+```
+
+Here reciprocal X/Y scale preserves the ellipse's area. More complicated shapes and overlapping groups still require artistic judgment. This sample is also available as [bouncing-ember.json](../../examples/svg/bouncing-ember.json).
+
+## Use the implementation
+
+```ts
+import {
+  compileSvgAsset,
+  renderSvgFrame,
+  exportSvgAnimation,
+  sampleSvgParameters,
+} from "@ludic-labs/assembly/svg";
+
+const result = compileSvgAsset(sourceJSON);
+if (!result.ok) {
+  console.error(result.diagnostics); // { code, path, message }[]
+} else {
+  const asset = result.asset;
+  const still = renderSvgFrame(asset, { time: 0.5, prefix: "keeper1" });
+  const motion = exportSvgAnimation(asset, { animation: "idle", fps: 24 });
+  const pose = sampleSvgParameters(asset, { animation: "idle", time: 0.5 });
+}
+```
+
+The compiler accepts `unknown`, clones it, validates it, and freezes its result. It has no DOM, Node, renderer or host imports. Runtime evaluation failures throw `SvgAssetError`, whose `diagnostics` use the same structure. Handle these at an editor or application boundary. A successful compile validates structure, references, scopes, key ordering and the rest/default-zero frames; it does **not** prove every possible parameter combination is renderable. Evaluated geometry is checked on every render, including intermediate animation samples.
+
+The root package remains the existing 3D assembly API. Import the new entry point explicitly. A JSON Schema consumer can use `@ludic-labs/assembly/schema/svg-asset-0.1`; semantic compilation is still required after schema validation. The [specification](specification.md) defines exact behavior and limits.
+
+The package includes these documents, the original JSON examples and the `ludic-svg` CLI. After installing this package revision, `ludic-svg source.json output.svg --animated --clip idle` uses the same implementation. The packed-package smoke check runs that CLI after extracting the tarball outside the checkout.
+
+From this checkout:
+
+```sh
+npm ci
+npm run build:svg-demo
+node tools/serve.mjs qualification/local/svg-demo
+# Open the localhost URL printed by the server.
+
+node tools/svg-asset.mjs examples/svg/lantern-keeper.json /tmp/keeper.svg --time 0.5
+node tools/svg-asset.mjs examples/svg/lantern-keeper.json /tmp/walk.svg --animated --clip walk
+node tools/svg-asset.mjs examples/svg/waygate.json /tmp/summon-frames --frames --clip summon --fps 24
+```
+
+The CLI accepts `--params overrides.json` to apply numeric overrides. Static output samples the selected/default clip at `--time` (zero by default). `--frames` emits a `svg-frames/0.1` manifest with viewBox, loop flag, duration, requested/effective sampling rate, ordered filenames and sample times. Consumers can rasterize those frames into their engine's atlas format. PNG/atlas packing is outside this notation's core.
+
+The gallery shows the complete JSON beside each preview and supports clip selection, playback, scrub, parameter overrides, source editing, structured errors, source download and both SVG exports. It honors reduced motion for automatic playback. Downloaded animated SVG has its own timeline: use static exports in reduced-motion contexts or hosts that strip SVG animation.
+
+## 0.1 completion gates
+
+| Gate                                                       | Evidence                                                                                                                                           |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A versioned grammar with documented semantics              | [Specification](specification.md), [schema](../../schemas/svg-asset-0.1.schema.json), [types](../../src/svg/types.ts)                              |
+| One portable implementation used by Node and the browser   | [Core](../../src/svg.ts), [CLI](../../tools/svg-asset.mjs), [viewer](../../demos/svg/viewer.mjs)                                                   |
+| All three requested asset classes and animation            | [Character](../../examples/svg/lantern-keeper.json), [interior](../../examples/svg/night-workshop.json), [effect](../../examples/svg/waygate.json) |
+| Determinism, invalid input and numerical boundary coverage | [Contract tests](../../tests/svg.test.mjs)                                                                                                         |
+| Real browser pixels and a complete authoring/export flow   | [Browser verifier](../../tools/verify-svg.mjs), [qualification record](../../qualification/svg/verification.json)                                  |
+| Compatibility with the existing project                    | `npm test`, `npm run build:docs`, `npm run test:browser`, typecheck and lint; recorded in qualification                                            |
+
+Run `npm run test:svg-browser` for the new browser checks. It builds the local gallery, uses one browser at a time, and writes screenshots/report to `qualification/local/svg-verification`. No cloud service, model download, GPU rental, or reference-image capture is needed.
+
+After editing `src/svg/schema.ts`, run `npm run build` and `node tools/build-svg-schema.mjs` to regenerate the published schema. A contract test detects drift between the two.
+
+The tests establish bounded technical behavior. The included images have been inspected for visible construction and clipping issues; owner aesthetic acceptance is still pending. File size is measured separately: sampled SVG duplicates geometry across frames and is intentionally limited to short clips. It is a working interchange format, not a demonstrated optimal delivery encoding. A later version can introduce compact native attribute tracks, rig/deformation adapters or image-guided optimization after separate compatibility and visual qualification.