sketchmark 2.0.0 → 2.1.1

package/README.md

@@ -1,188 +1,274 @@
-# Sketchmark
-
-Primitive-first JSON visual language for AI-generated explanations.
-
-The canonical document format is a predictable scene graph of primitives. Higher-level helpers such as `node()`, `flow()`, `packet()`, and `callout()` are builder-time conveniences only: they expand into primitives before validation and rendering.
-
-## Core Principles
-
-- JSON is the source of truth.
-- The canonical document contains primitives only.
-- Box primitives use top-left `x`, `y`, `width`, and `height`.
-- Circles use `cx`, `cy`, and `radius`.
-- Lines and arrows use `from` and `to`.
-- Missing geometry is an error, not an auto-layout hint.
-- No collision avoidance, auto-routing, auto-resize, or hidden object synthesis.
-- All computed values come from explicit builders, references, or `follow`.
-
-## Example
-
-```json
-{
-  "version": 1,
-  "canvas": {
-    "width": 1280,
-    "height": 720,
-    "background": "#f8fafc",
-    "duration": 8,
-    "fps": 30
-  },
-  "elements": [
-    {
-      "id": "browser_box",
-      "type": "rect",
-      "x": 120,
-      "y": 160,
-      "width": 180,
-      "height": 80,
-      "radius": 12,
-      "fill": "#ffffff",
-      "stroke": "#2563eb"
-    },
-    {
-      "id": "browser_label",
-      "type": "text",
-      "text": "Browser",
-      "x": 210,
-      "y": 200,
-      "align": "center",
-      "valign": "middle",
-      "fontSize": 18
-    }
-  ]
-}
-```
-
-## Builders
-
-```ts
-import { scene } from "sketchmark";
-import { node, arrow } from "sketchmark/builders";
-
-const browser = node({
-  id: "browser",
-  label: "Browser",
-  x: 120,
-  y: 160,
-  width: 180,
-  height: 80
-});
-
-const resolver = node({
-  id: "resolver",
-  label: "DNS Resolver",
-  x: 380,
-  y: 160,
-  width: 180,
-  height: 80
-});
-
-export default scene({
-  canvas: { width: 1280, height: 720, background: "#f8fafc", duration: 8 },
-  elements: [
-    ...browser,
-    ...resolver,
-    arrow({
-      id: "query_arrow",
-      from: "browser_box.right",
-      to: "resolver_box.left",
-      stroke: "#2563eb",
-      strokeWidth: 3
-    })
-  ]
-});
-```
-
-## Exports
-
-Build first:
-
-```bash
-npm run build
-```
-
-Open a browser preview:
-
-```bash
-node bin/sketchmark.cjs preview examples/dns.visual.json
-```
-
-The preview opens an inline editor with live render, play/scrub controls, scene/sequence selectors, and a save button for the source JSON.
-
-Render files:
-
-```bash
-node bin/sketchmark.cjs render examples/dns.visual.json out.svg
-node bin/sketchmark.cjs render examples/dns.visual.json out.html
-node bin/sketchmark.cjs render examples/dns.visual.json out.png --time 1.5
-node bin/sketchmark.cjs render examples/dns.visual.json transparent.png --transparent
-node bin/sketchmark.cjs render examples/dns.visual.json out.pdf
-node bin/sketchmark.cjs render examples/dns.visual.json out.mp4 --fps 30 --duration 4
-node bin/sketchmark.cjs render examples/dns.visual.json transparent.webm --transparent --fps 30 --duration 4
-node bin/sketchmark.cjs lint examples/dns.visual.json
-node bin/sketchmark.cjs screenshot-lint examples/dns.visual.json
-```
-
-SVG and HTML are built in. PNG/JPG/PDF/MP4/WebM use `sharp`; video also requires `ffmpeg`. Use WebM for transparent video; MP4 is intentionally opaque. Structured Three image/video export uses a deterministic isometric SVG preview adapter, while HTML uses the live Three renderer.
-
-## Browser Player
-
-```ts
-import { SketchmarkPlayer, createSketchmarkPlayer } from "sketchmark/player";
-
-const player = new SketchmarkPlayer(document.getElementById("preview")!, {
-  document: visualDocument,
-  autoplay: true,
-  loop: true
-});
-
-player.seek(2);
-player.pause();
-player.setDocument(nextVisualDocument);
-await player.download("svg", { title: "visual" });
-await player.download("png", { title: "visual" });
-await player.download("mp4", { title: "visual" });
-player.destroy();
-```
-
-The player is UI-free. It renders the primitive JSON document into the supplied element, and its browser export provider can download SVG, PNG, JPG, HTML, JSON, and MP4. MP4 uses WebCodecs/H.264 when available and falls back to WebM if the browser cannot encode MP4.
-
-Project and sequence examples:
-
-```bash
-node bin/sketchmark.cjs preview examples/project.visual.json --sequence main
-node bin/sketchmark.cjs render examples/project.visual.json out.mp4 --sequence main
-node bin/sketchmark.cjs timeline examples/project.visual.json --sequence main --fps 12
-node bin/sketchmark.cjs render examples/deck.visual.json deck.html --deck --scene slide
-node bin/sketchmark.cjs render examples/deck.visual.json deck.pptx --deck --scene slide
-```
-
-Feature catalog:
-
-The `examples/features/` folder contains 21 primitive-first examples covering the main language surface: primitives, references, groups, animation, keyframes, packet follow, path follow, patch-friendly ids, diagrams, charts, scenes, sequences, deck steps, images, structured 3D, and mixed 2D/3D sequences.
-
-Structured Three HTML example:
-
-```bash
-node bin/sketchmark.cjs render examples/three-cube.visual.json cube.html
-node bin/sketchmark.cjs render examples/three-cube.visual.json cube.png
-node bin/sketchmark.cjs render examples/three-cube.visual.json cube.mp4 --duration 2 --fps 24
-```
-
-Raw Three escape hatch:
-
-```ts
-import { renderRawThreeModuleHtml } from "sketchmark";
-
-const html = renderRawThreeModuleHtml({
-  width: 1280,
-  height: 720,
-  moduleUrl: "./scene.js"
-});
-```
-
-The module must export `createSketchmarkThreeScene({ canvas, width, height, background })`.
-
-## AI Reference
-
-Use [AI.md](./AI.md) as the compact model-facing reference. It teaches only the primitive JSON surface and points to advanced features without making them default.
+# Sketchmark
+
+Sketchmark is currently a **pure 2D render kernel**.
+
+The canonical JSON contains only renderable atoms:
+
+- `path`
+- `text`
+- `image`
+- `point`
+- `group`
+
+Everything else, including rectangles, circles, arrows, diagrams, charts, scenes, decks, 3D, and walking cycles, belongs above the kernel and compiles down to this format. Sketchmark ships an official `presets` layer for common reusable authoring helpers.
+
+Reference docs:
+
+- [Kernel Spec](./KERNEL_SPEC.md)
+- [Animatable Property Matrix](./ANIMATABLE_MATRIX.md)
+- [Presets](./PRESETS.md)
+- [Packs](./PACKS.md)
+- [What Needs Improvement](./WHAT_NEEDS_IMPROVEMENT.md)
+
+## Kernel Document
+
+```json
+{
+  "version": 1,
+  "canvas": {
+    "width": 640,
+    "height": 360,
+    "background": "#f8fafc",
+    "duration": 2,
+    "fps": 30
+  },
+  "elements": [
+    {
+      "id": "line",
+      "type": "path",
+      "d": "M 80 240 C 180 80 320 280 520 120",
+      "fill": "none",
+      "stroke": "#111827",
+      "strokeWidth": 5,
+      "strokeCap": "round"
+    },
+    {
+      "id": "title",
+      "type": "text",
+      "text": "Render kernel",
+      "x": 320,
+      "y": 70,
+      "align": "center",
+      "valign": "middle",
+      "fontSize": 28,
+      "weight": 800,
+      "fill": "#0f172a"
+    }
+  ]
+}
+```
+
+Only `version`, `canvas`, and `elements` are canonical top-level fields.
+
+## Timeline
+
+Animation is element-local. Tuple keyframes are still valid, but editor-facing tools should prefer object keyframes because curves live on the outgoing segment:
+
+```json
+{
+  "id": "label",
+  "type": "text",
+  "text": "Move",
+  "x": 40,
+  "y": 80,
+  "timeline": {
+    "start": 0.5,
+    "end": 2,
+    "tracks": {
+      "position": {
+        "keyframes": [
+          {
+            "time": 0,
+            "value": [40, 80],
+            "out": {
+              "type": "cubicBezier",
+              "x1": 0.42,
+              "y1": 0,
+              "x2": 0.58,
+              "y2": 1
+            }
+          },
+          { "time": 1.5, "value": [260, 80] }
+        ]
+      },
+      "opacity": {
+        "keyframes": [[0, 0], [0.4, 1]]
+      }
+    }
+  }
+}
+```
+
+Track values may be numbers, strings, `[x,y]` points, same-length number arrays, string arrays, or JSON objects. Known kernel properties are type-checked more strictly than the broad schema shape. `position` maps to `x/y` for `path`, `point`, `text`, `image`, and `group`. Tracks can also define a fallback interpolation graph:
+
+```json
+{
+  "keyframes": [[0, [0, 0]], [1, [100, 0]]],
+  "curve": {
+    "type": "graph",
+    "points": [[0, 0], [0.35, 0.08], [0.65, 0.92], [1, 1]]
+  }
+}
+```
+
+The graph maps normalized time progress `x` to normalized value progress `y`. Kernel curves can be `graph`, `cubicBezier`, or `hold`. Segment resolution is: previous keyframe `out`, previous keyframe `interpolation`, next keyframe `in`, track `curve`, legacy `ease`, then linear. Named easing strings are still accepted as compatibility shorthands, but helpers/presets should prefer emitting explicit curves. There are no expressions, path followers, pose drivers, scenes, or 3D in this kernel pass.
+
+Current known animatable properties include transform/layout (`position`, `x`, `y`, `rotation`, `scale`, `scaleX`, `scaleY`, `origin`, `width`, `height`, `opacity`), path data/drawing/style (`d`, `fill`, `stroke`, `strokeWidth`, caps/joins, `dashArray`, `dashOffset`, `drawStart`, `drawEnd`), text content/layout (`text`, `lines`, `align`, `valign`, `fontStyle`, typography sizing), image `src`/`fit`/`source.*`, clip/mask paths and opacity, filter effects (`effects.*`), whole paint switching, structured gradient internals such as `fill.to` or `fill.stops.0.color`, and pattern internals such as `fill.x`, `fill.width`, or `fill.opacity`.
+
+Unknown timeline tracks are invalid in the frozen kernel. Rounded images should be authored above the kernel and compiled to `clip.d`; `cornerRadius` and editor metadata are intentionally not kernel fields.
+
+## Keyframe Authoring
+
+For AI or editor-style authoring, use visual snapshots and compile them down to kernel timelines:
+
+```ts
+import { compileKeyframeStates, timelineCurvePreset } from "sketchmark";
+
+const animated = compileKeyframeStates(document, [
+  {
+    time: 0,
+    set: {
+      card: { position: [80, 160], scale: 0.85, opacity: 0 }
+    }
+  },
+  {
+    time: 1,
+    set: {
+      card: {
+        position: {
+          value: [220, 120],
+          curve: timelineCurvePreset("ease-out")
+        },
+        scale: 1,
+        opacity: 1
+      }
+    }
+  }
+]);
+```
+
+This is an authoring adapter, not a new JSON schema feature. The compiled output is still only kernel elements with local timelines.
+
+## Preset Layer
+
+Presets are reusable authoring helpers that compile to pure kernel output. They are exported separately so the root package can stay kernel-focused:
+
+```js
+const { applyPresetFragments, shapes, motions, effects } = require("sketchmark/presets");
+
+const visual = applyPresetFragments(
+  {
+    version: 1,
+    canvas: { width: 960, height: 540, duration: 2, fps: 30 },
+    elements: []
+  },
+  [
+    shapes.roundedRect({
+      id: "card",
+      x: 80,
+      y: 80,
+      width: 260,
+      height: 120,
+      radius: 16,
+      fill: "#ffffff",
+      stroke: "#cbd5e1"
+    }),
+    motions.riseIn({ id: "card", from: [80, 120], to: [80, 80] }),
+    effects.dropShadow({ id: "card", dy: 10, blur: 24, opacity: 0.2 })
+  ]
+);
+```
+
+The output `.visual.json` still contains only kernel elements and timelines. Official namespaces include `shapes`, `characters`, `motions`, `effects`, `transitions`, and `scenes`.
+
+## CLI
+
+Build first:
+
+```bash
+npm run build
+```
+
+Render:
+
+```bash
+node bin/sketchmark.cjs render examples/basic.visual.json out.svg
+node bin/sketchmark.cjs render examples/timeline.visual.json out.html --time 1
+node bin/sketchmark.cjs render examples/timeline.visual.json out.mp4
+node bin/sketchmark.cjs render examples/timeline.visual.json out.webm --fps 30
+```
+
+Generate the key-pose walking example:
+
+```bash
+node examples/make-keypose-walk.cjs
+node bin/sketchmark.cjs preview examples/keypose-walk.visual.json
+```
+
+Generate the key-pose cyclist example:
+
+```bash
+node examples/make-keypose-cycle.cjs
+node bin/sketchmark.cjs preview examples/keypose-cycle.visual.json
+```
+
+Generate preset-layer examples:
+
+```bash
+node examples/make-presets-demo.cjs
+node examples/make-preset-character-motion.cjs
+node bin/sketchmark.cjs preview examples/presets-demo.visual.json
+node bin/sketchmark.cjs preview examples/preset-character-motion.visual.json
+```
+
+Generate heavier real-world stress scenes:
+
+```bash
+node examples/make-stress-city-traffic.cjs
+node examples/make-stress-ops-dashboard.cjs
+node examples/make-stress-airport-radar.cjs
+
+node bin/sketchmark.cjs preview examples/stress-city-traffic.visual.json
+node bin/sketchmark.cjs preview examples/stress-ops-dashboard.visual.json
+node bin/sketchmark.cjs preview examples/stress-airport-radar.visual.json
+```
+
+These are intentionally dense (many elements/keyframes) to pressure test preview responsiveness.
+
+Preview animated timelines in the browser:
+
+```bash
+node bin/sketchmark.cjs preview examples/timeline.visual.json
+```
+
+Open the tiny editor:
+
+```bash
+node bin/sketchmark.cjs edit examples/keypose-walk.visual.json
+```
+
+Lint:
+
+```bash
+node bin/sketchmark.cjs lint examples/basic.visual.json
+```
+
+Video export is an adapter, not a kernel feature. It samples the document timeline into SVG frames, rasterizes those frames, and hands them to `ffmpeg`. It requires `sharp` and `ffmpeg` to be available in the local environment.
+
+## Public API
+
+```ts
+import {
+  validateVisualDocument,
+  compileKeyframeStates,
+  timelineCurvePreset,
+  resolveVisualFrame,
+  renderToSvg,
+  renderToHtml,
+  lintVisualDocument
+} from "sketchmark";
+```
+
+The root package intentionally exports no builders, player, project loader, deck/sequence helpers, 3D renderer, or preset compiler.
+
+The official preset authoring layer is available from `sketchmark/presets`, not the root kernel entrypoint.