sketchmark 2.1.9 → 2.2.0

package/skills/sketchmark/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: sketchmark
+description: Entry point for Sketchmark kernel, design, animation, and render/edit/preview guidance. Use when working with Sketchmark `.visual.json`, generators, validation, rendering, timelines, or previews.
+---
+
+# Sketchmark
+
+Use the smallest file needed:
+
+- `kernel.md`: valid document shape, element properties, paints, effects, timelines, curves, and animatable tracks.
+- `design.md`: broad composition and static visual construction guidance.
+- `animation.md`: broad timeline and motion guidance.
+- `render.md`: validate, render, edit, preview, export, and debug workflow.
+
+Keep `.visual.json` output pure kernel: `version`, `canvas`, and `elements`.
+When working inside this repository, prefer example generator scripts such as `examples/make-*.cjs` over hand-authoring only generated `.visual.json` files.

package/skills/sketchmark/animation.md

@@ -0,0 +1,67 @@
+# Animation
+
+Use this for timeline creation, motion timing, reveals, transitions, and animated visual states.
+
+## Boundary
+
+- Animation is stored in element-local `timeline.tracks`.
+- Track names must be valid animatable properties from `kernel.md`.
+- Curves are timeline curve objects.
+- Helper functions may exist in generator code, but their output is only kernel timelines.
+
+## Process
+
+1. Create a readable static frame first.
+2. Choose which element or group owns each motion.
+3. Animate parent groups for broad movement.
+4. Animate child elements for local changes.
+5. Add keyframes at clear beats.
+6. Use explicit curves when timing matters.
+7. Validate.
+8. Render checkpoint frames at key times.
+
+## Track Selection
+
+- Position: `position`, `x`, `y`.
+- Visibility: `opacity`.
+- Transform: `rotation`, `scale`, `scaleX`, `scaleY`, `origin`.
+- Path drawing: `drawStart`, `drawEnd`.
+- Text changes: `text`, `lines`.
+- Paint changes: `fill`, `stroke`, paint subproperties.
+- Reveal: `clip.d`, `mask.d`, `mask.opacity`.
+- Effects: `effects.*`.
+
+## Keyframes
+
+Preferred object form:
+
+```js
+{ time: 0, value: [0, 0], out: { type: "cubicBezier", x1: 0.16, y1: 1, x2: 0.3, y2: 1 } }
+```
+
+Tuple form:
+
+```js
+[0, [0, 0]]
+```
+
+## Curves
+
+- `cubicBezier`: smooth timing.
+- `graph`: custom normalized timing.
+- `hold`: discrete switch.
+
+## Timing
+
+- Use seconds.
+- Keep keyframes sorted by time.
+- Use short names for curve constants in generator code.
+- Use `hold` for instant changes.
+- Use multiple sampled keyframes for path or radius style changes because path data is discrete.
+
+## Final Check
+
+- Every animated track exists in `kernel.md`.
+- Keyframes are sorted.
+- Curve fields contain curve objects.
+- The animation still reads at checkpoint frames.

package/skills/sketchmark/design.md

@@ -0,0 +1,59 @@
+# Design
+
+Use this for composition, layout, typography, visual hierarchy, and static visual construction.
+
+## Boundary
+
+- Output kernel elements only: `path`, `text`, `image`, `point`, `group`.
+- Higher-level objects compile to kernel elements.
+- Keep authoring helper names out of `.visual.json`.
+
+## Process
+
+1. Set `canvas.width`, `canvas.height`, optional `background`, `duration`, and `fps`.
+2. Define reusable constants in generator code: colors, font family, spacing, stroke widths.
+3. Build from back to front: background, large groups, content, details.
+4. Use `group` for local coordinate systems.
+5. Use `path` for shape geometry.
+6. Use `text` for all labels and copy.
+7. Use `image` only with explicit size and fit.
+8. Validate the document.
+9. Render at least one preview frame.
+
+## Layout
+
+- Use explicit `x` and `y`.
+- Use groups to move related elements together.
+- Use consistent margins and spacing.
+- Keep important content inside the canvas.
+- Prefer stable dimensions over inferred layout.
+
+## Text
+
+- Set `align` and `valign`.
+- Set `fontSize`, `lineHeight`, `weight`, and `fill`.
+- Use `text` with newlines or `lines` for multiline text.
+- Use `maxWidth` and `wrap` only when supported by the renderer path being used.
+
+## Shapes
+
+- Rectangle: `path`.
+- Rounded rectangle: `path`.
+- Circle/ellipse: `path`.
+- Arrow: `path`.
+- Divider: `path` with `stroke`.
+- Clip/reveal shape: `clip.d` or `mask.d`.
+
+## Images
+
+- Set `src`, `x`, `y`, `width`, `height`.
+- Use `fit`.
+- Use `source.*` for cropping.
+- Use `clip.d` for rounded or custom image boundaries.
+
+## Final Check
+
+- No non-kernel element types.
+- No metadata or editor state.
+- All visual objects have explicit position and size.
+- Text is readable in the target canvas.

package/skills/sketchmark/kernel.md

@@ -0,0 +1,354 @@
+# Kernel
+
+## Package Entry Points
+
+- `sketchmark`
+- `sketchmark/presets`
+- `sketchmark/browser-export`
+- `sketchmark/render`
+- `sketchmark/edit`
+- `sketchmark/editor`
+- `sketchmark/preview`
+- `sketchmark/schema`
+- CLI: `sketchmark`
+
+## Root Kernel Exports
+
+- types
+- validate
+- normalize
+- diagnostics
+- schema
+- keyframes
+- edit namespace and direct edit helpers
+- animatable
+- render namespace and direct render helpers
+
+Preferred package API:
+
+```js
+const { render, edit, validateVisualDocument } = require("sketchmark");
+
+const svg = render.svg(doc, { time: 1 });
+const html = render.html(doc);
+const embed = render.embedHtml(doc, { title: "Preview" });
+const nextDoc = edit.setProperty(doc, "element-id", "fill", "#22c55e");
+```
+
+UI entry points stay separate:
+
+```js
+const { editorHtml } = require("sketchmark/editor");
+const { previewHtml } = require("sketchmark/preview");
+```
+
+## Document
+
+- `version`: `1`
+- `canvas`: `VisualCanvas`
+- `elements`: `VisualElement[]`
+
+## Canvas
+
+- `width`: number
+- `height`: number
+- `background`: string
+- `duration`: number
+- `fps`: number
+
+## Element Types
+
+- `path`
+- `text`
+- `image`
+- `point`
+- `group`
+
+## Common Element Properties
+
+- `id`: string
+- `type`: element type
+- `opacity`: number
+- `fill`: paint
+- `stroke`: paint
+- `strokeWidth`: number
+- `strokeCap`: `butt | round | square`
+- `strokeJoin`: `miter | round | bevel`
+- `miterLimit`: number
+- `dashArray`: number[]
+- `dashOffset`: number
+- `drawStart`: number
+- `drawEnd`: number
+- `effects`: effects
+- `blendMode`: string
+- `rotation`: number
+- `scale`: number
+- `scaleX`: number
+- `scaleY`: number
+- `origin`: `[number, number]`
+- `clip`: clip shape
+- `mask`: mask shape
+- `timeline`: element timeline
+
+## Path Element
+
+- `type`: `"path"`
+- `d`: SVG path data string
+- `x`: number
+- `y`: number
+- common properties
+
+## Text Element
+
+- `type`: `"text"`
+- `x`: number
+- `y`: number
+- `text`: string
+- `lines`: string[]
+- `align`: `left | center | right`
+- `valign`: `top | middle | bottom`
+- `fontSize`: number
+- `fontFamily`: string
+- `weight`: number | string
+- `fontStyle`: string
+- `lineHeight`: number
+- `letterSpacing`: number
+- `maxWidth`: number
+- `wrap`: boolean
+- common properties
+
+## Image Element
+
+- `type`: `"image"`
+- `src`: string
+- `x`: number
+- `y`: number
+- `width`: number
+- `height`: number
+- `fit`: `fill | contain | cover`
+- `source.x`: number
+- `source.y`: number
+- `source.width`: number
+- `source.height`: number
+- `source.imageWidth`: number
+- `source.imageHeight`: number
+- common properties
+
+## Point Element
+
+- `type`: `"point"`
+- `x`: number
+- `y`: number
+- common properties
+
+## Group Element
+
+- `type`: `"group"`
+- `x`: number
+- `y`: number
+- `width`: number
+- `height`: number
+- `children`: `VisualElement[]`
+- common properties
+
+## Paint
+
+- string color
+- linear gradient
+- radial gradient
+- pattern
+
+## Linear Gradient Paint
+
+- `type`: `"linearGradient"`
+- `from`: `[number, number]`
+- `to`: `[number, number]`
+- `stops`: gradient stops
+
+## Radial Gradient Paint
+
+- `type`: `"radialGradient"`
+- `center`: `[number, number]`
+- `radius`: number
+- `focus`: `[number, number]`
+- `stops`: gradient stops
+
+## Pattern Paint
+
+- `type`: `"pattern"`
+- `src`: string
+- `x`: number
+- `y`: number
+- `width`: number
+- `height`: number
+- `fit`: `fill | contain | cover`
+- `opacity`: number
+
+## Gradient Stop
+
+- `[offset, color]`
+- `{ offset, color }`
+
+## Clip Shape
+
+- `type`: `"path"`
+- `d`: SVG path data string
+
+## Mask Shape
+
+- `type`: `"path"`
+- `d`: SVG path data string
+- `opacity`: number
+
+## Effects
+
+- `blur`: number
+- `brightness`: number
+- `contrast`: number
+- `saturate`: number
+- `hueRotate`: number
+- `shadow.dx`: number
+- `shadow.dy`: number
+- `shadow.blur`: number
+- `shadow.color`: string
+- `shadow.opacity`: number
+
+## Timeline
+
+- `start`: number
+- `end`: number
+- `tracks`: record of animatable property names to timeline tracks
+
+## Timeline Track
+
+- `keyframes`: timeline keyframes
+- `curve`: timeline curve
+- `ease`: string
+
+## Keyframe Tuple
+
+- `[time, value]`
+
+## Keyframe Object
+
+- `time`: number
+- `value`: timeline value
+- `in`: timeline curve
+- `out`: timeline curve
+- `interpolation`: timeline curve
+
+## Timeline Curve
+
+- `{ type: "graph", points: [number, number][] }`
+- `{ type: "cubicBezier", x1: number, y1: number, x2: number, y2: number }`
+- `{ type: "hold" }`
+
+## Timeline Values
+
+- number
+- string
+- `[number, number]`
+- number[]
+- string[]
+- JSON object
+
+## Animatable Common Tracks
+
+- `position`: path, point, text, image, group
+- `x`: path, point, text, image, group
+- `y`: path, point, text, image, group
+- `opacity`: path, point, text, image, group
+- `rotation`: path, text, image, group
+- `scale`: path, text, image, group
+- `scaleX`: path, text, image, group
+- `scaleY`: path, text, image, group
+- `origin`: path, text, image, group
+- `blendMode`: path, text, image, group
+- `clip.d`: path, text, image, group
+- `mask.d`: path, text, image, group
+- `mask.opacity`: path, text, image, group
+
+## Animatable Path Tracks
+
+- `d`
+- `fill`
+- `stroke`
+- `strokeWidth`
+- `strokeCap`
+- `strokeJoin`
+- `miterLimit`
+- `dashArray`
+- `dashOffset`
+- `drawStart`
+- `drawEnd`
+
+## Animatable Text Tracks
+
+- `text`
+- `lines`
+- `align`
+- `valign`
+- `fontFamily`
+- `fontStyle`
+- `fontSize`
+- `lineHeight`
+- `letterSpacing`
+- `maxWidth`
+- `weight`
+- `fill`
+
+## Animatable Image Tracks
+
+- `width`
+- `height`
+- `src`
+- `fit`
+- `source.x`
+- `source.y`
+- `source.width`
+- `source.height`
+
+## Animatable Group Tracks
+
+- `width`
+- `height`
+
+## Animatable Effects Tracks
+
+- `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`
+
+## Animatable Paint Tracks
+
+- `fill.x`
+- `fill.y`
+- `fill.width`
+- `fill.height`
+- `fill.opacity`
+- `fill.from`
+- `fill.to`
+- `fill.center`
+- `fill.focus`
+- `fill.radius`
+- `fill.stops.N.offset`
+- `fill.stops.N.color`
+- `stroke.x`
+- `stroke.y`
+- `stroke.width`
+- `stroke.height`
+- `stroke.opacity`
+- `stroke.from`
+- `stroke.to`
+- `stroke.center`
+- `stroke.focus`
+- `stroke.radius`
+- `stroke.stops.N.offset`
+- `stroke.stops.N.color`

package/skills/sketchmark/render.md

@@ -0,0 +1,166 @@
+# Render, Edit, Preview
+
+Use this for validating, rendering, editing, previewing, exporting, and debugging Sketchmark files.
+If the goal is a reusable preview another UI or AI agent can mount directly, prefer a self-contained embed HTML over a one-off SVG frame.
+Package-facing docs may use generic placeholder paths, but inside this repository the default authoring workflow is generator-first: create or update `examples/make-*.cjs` or `.js`, then regenerate the derived `.visual.json` or `.embed.html` artifacts.
+Do not default to hand-writing only a generated `.visual.json` file for a new repo example unless the user explicitly asks for raw JSON only.
+
+## Files
+
+- Repo convention for examples: `examples/make-name.cjs` -> `examples/name.visual.json`
+- Repo convention for embed demos: `examples/make-name.cjs` -> `examples/name.embed.html` and optional `examples/name.host.html`
+- Kernel document: `path/to/document.visual.json`
+- Optional generator script: `path/to/generator.cjs`
+- Optional standalone embed output: `path/to/preview.embed.html`
+- Optional host iframe page: `path/to/preview.host.html`
+- Schema: `schema/visual.schema.json`
+- CLI: `bin/sketchmark.cjs`
+- Package API: `sketchmark`, `sketchmark/render`, `sketchmark/edit`
+- UI API: `sketchmark/editor`, `sketchmark/preview`
+- Browser export entrypoint: `sketchmark/browser-export`
+
+## Generate
+
+If the project uses a generator script, build first when needed and run that script:
+
+```bash
+npm run build
+node path/to/generator.cjs
+```
+
+Inside this repo, prefer this pattern for new examples:
+
+```bash
+npm run build
+node examples/make-name.cjs
+```
+
+That generator should usually be the source of truth, with `.visual.json`, `.embed.html`, or `.host.html` checked in as generated artifacts when the repo already follows that pattern.
+
+## Validate
+
+In code:
+
+```js
+const { validateVisualDocument } = require("sketchmark");
+const result = validateVisualDocument(doc);
+if (!result.ok) throw new Error(result.issues.map((i) => `${i.path}: ${i.message}`).join("\n"));
+```
+
+With CLI when available:
+
+```bash
+node bin/sketchmark.cjs validate path/to/document.visual.json
+```
+
+## Render
+
+Render a frame:
+
+```bash
+node bin/sketchmark.cjs render path/to/document.visual.json --time 1 --out .tmp/preview.svg
+```
+
+Preview/export commands may vary by package version. Check:
+
+```bash
+node bin/sketchmark.cjs --help
+```
+
+Create a reusable embed in code:
+
+```js
+const { render } = require("sketchmark");
+
+const html = render.embedHtml(doc, {
+  title: "Agent Preview",
+  maxFrames: 180
+});
+```
+
+Render or edit from a standalone Node project with the public package API:
+
+```js
+const { render, edit } = require("sketchmark");
+
+const svg = render.svg(doc, { time: 1 });
+const nextDoc = edit.setProperty(doc, "element-id", "x", 120);
+const keyedDoc = edit.setKeyframe(nextDoc, "element-id", "opacity", 0.5, 1);
+```
+
+For explicit subpath imports:
+
+```js
+const render = require("sketchmark/render");
+const edit = require("sketchmark/edit");
+const { editorHtml } = require("sketchmark/editor");
+const { previewHtml } = require("sketchmark/preview");
+```
+
+Create the same output from a browser host:
+
+```js
+import { exportVisualInBrowser } from "sketchmark/browser-export";
+
+await exportVisualInBrowser(doc, {
+  format: "embed",
+  title: "Agent Preview",
+  sourceDocument: doc
+});
+```
+
+## Edit
+
+For small edits:
+
+1. Find element by `id`.
+2. Patch only the needed properties.
+3. Preserve unrelated timelines.
+4. Validate.
+5. Render the changed frame.
+
+For large edits:
+
+1. Update the generator.
+2. Regenerate the `.visual.json`.
+3. Validate.
+4. Render preview frames.
+
+For new repo examples:
+
+1. Add `examples/make-name.cjs` or update an existing generator.
+2. Generate the derived `.visual.json` and any embed demo artifacts.
+3. Validate and spot-check the rendered result.
+
+## Preview
+
+- SVG frame preview checks geometry, text, and paint.
+- HTML preview checks animation playback when available.
+- Embed preview is the preferred agent-friendly output: one HTML string, no server route, play/pause UI, scrubber, and export buttons.
+- For host-agnostic embeds, keep the HTML self-contained: inline scripts, inline styles, and no CDN or runtime network dependency.
+- Avoid module-script or blob/object-URL imports inside the embed. Some hosts rewrite or block blob URLs.
+- Avoid relying on `URL.createObjectURL()` for runtime-loaded assets like SVG frame rasterization. Prefer `data:` URLs or other inline forms.
+- Assume the embed may run inside `iframe`, `srcdoc`, webview, sandboxed previews, or artifact hosts that intercept downloads and messaging.
+- Keep host integration generic: optional `postMessage` events are fine, but the embed should not require Claude-specific globals or a custom parent API to render.
+- Embed chrome defaults to a transparent outer background with light/dark-aware translucent controls, so it sits more naturally inside host UIs.
+- Current embed exports are `svg`, `png`, `jpg`, `html`, `json`, and `mp4`.
+- Mount embed HTML in an `iframe` with `srcdoc` or the equivalent host API.
+- Use a generated `.embed.html` file and a host page with an `iframe` as the reference pair when you need parent-child messaging.
+- Parent pages can send `sketchmark-play`, `sketchmark-pause`, `sketchmark-show`, and `sketchmark-export` with `postMessage`.
+- The embed posts back `sketchmark-rendered` with `title`, `duration`, and `time`.
+- Use `maxFrames` to trade file size for smoother motion.
+- MP4 export inside the embed requires WebCodecs. Chrome and Edge are the safest targets.
+- Editor preview checks property editing and timeline changes.
+- Browser export is preferred for web deployments that cannot rely on server `ffmpeg` or `sharp`.
+
+## Debug
+
+- Validate before rendering.
+- Lower `maxFrames` if the embed HTML gets too large.
+- Browser raster or MP4 export can fail on unsupported browsers or when external images block canvas export.
+- Unknown timeline tracks are invalid.
+- Timeline curve fields must be objects.
+- `cornerRadius` is not kernel; use `clip.d`.
+- Text alignment uses `align` and `valign`.
+- Image crop uses `source.*`.
+- Render the exact failing time.