sketchmark 2.0.0 → 2.1.0

package/ANIMATABLE_MATRIX.md

@@ -0,0 +1,177 @@
+# Animatable Property Matrix
+
+This matrix defines the kernel animation surface. Unknown timeline tracks are invalid.
+
+Interpolation kinds:
+
+- `number`: numeric interpolation
+- `point2`: `[x,y]` interpolation
+- `numberArray`: same-length numeric array interpolation
+- `color`: hex color interpolation for color strings, otherwise discrete
+- `paint`: whole paint value; color strings can interpolate, structured paint switches discretely unless animating supported internals
+- `discrete`: previous value until the target keyframe
+
+## Shared Position Tracks
+
+| Property | path | text | image | point | group | Value | Interpolation | Default |
+|---|---:|---:|---:|---:|---:|---|---|---|
+| `position` | yes | yes | yes | yes | yes | `[x,y]` | `point2` | current `x/y` |
+| `x` | yes | yes | yes | yes | yes | number | `number` | `0` |
+| `y` | yes | yes | yes | yes | yes | number | `number` | `0` |
+
+## Transform And Visibility
+
+| Property | path | text | image | point | group | Value | Interpolation | Default |
+|---|---:|---:|---:|---:|---:|---|---|---|
+| `opacity` | yes | yes | yes | yes | yes | number | `number` | `1` |
+| `rotation` | yes | yes | yes | no | yes | number | `number` | `0` |
+| `scale` | yes | yes | yes | no | yes | number | `number` | `1` |
+| `scaleX` | yes | yes | yes | no | yes | number | `number` | `1` |
+| `scaleY` | yes | yes | yes | no | yes | number | `number` | `1` |
+| `origin` | yes | yes | yes | no | yes | `[x,y]` | `point2` | renderer-derived |
+| `blendMode` | yes | yes | yes | no | yes | string | `discrete` | none |
+
+## Path Drawing And Stroke
+
+| Property | path | text | image | point | group | Value | Interpolation | Default |
+|---|---:|---:|---:|---:|---:|---|---|---|
+| `d` | yes | no | no | no | no | string | `discrete` | required path `d` |
+| `stroke` | yes | no | no | no | no | paint | `paint` | none |
+| `strokeWidth` | yes | no | no | no | no | number | `number` | `1` |
+| `strokeCap` | yes | no | no | no | no | string | `discrete` | renderer default |
+| `strokeJoin` | yes | no | no | no | no | string | `discrete` | renderer default |
+| `miterLimit` | yes | no | no | no | no | number | `number` | renderer default |
+| `dashArray` | yes | no | no | no | no | number array | `numberArray` | none |
+| `dashOffset` | yes | no | no | no | no | number | `number` | `0` |
+| `drawStart` | yes | no | no | no | no | number | `number` | `0` |
+| `drawEnd` | yes | no | no | no | no | number | `number` | `1` |
+
+## Fill Paint
+
+| Property | path | text | image | point | group | Value | Interpolation | Default |
+|---|---:|---:|---:|---:|---:|---|---|---|
+| `fill` | yes | yes | no | no | no | paint | `paint` | renderer default |
+
+Whole `fill` and `stroke` tracks can switch structured paint values. For smooth gradient or pattern changes, animate the supported nested paint properties below.
+
+## Text
+
+| Property | path | text | image | point | group | Value | Interpolation | Default |
+|---|---:|---:|---:|---:|---:|---|---|---|
+| `text` | no | yes | no | no | no | string | `discrete` | none |
+| `lines` | no | yes | no | no | no | string array | `discrete` | none |
+| `align` | no | yes | no | no | no | string | `discrete` | renderer default |
+| `valign` | no | yes | no | no | no | string | `discrete` | renderer default |
+| `fontFamily` | no | yes | no | no | no | string | `discrete` | renderer default |
+| `fontStyle` | no | yes | no | no | no | string | `discrete` | none |
+| `fontSize` | no | yes | no | no | no | number | `number` | `16` |
+| `lineHeight` | no | yes | no | no | no | number | `number` | `1.2` |
+| `letterSpacing` | no | yes | no | no | no | number | `number` | `0` |
+| `maxWidth` | no | yes | no | no | no | number | `number` | none |
+| `weight` | no | yes | no | no | no | number or string | `discrete` | `400` |
+
+`wrap` is a kernel field but is not currently an animatable property.
+
+## Image
+
+| Property | path | text | image | point | group | Value | Interpolation | Default |
+|---|---:|---:|---:|---:|---:|---|---|---|
+| `width` | no | no | yes | no | yes | number | `number` | `0` |
+| `height` | no | no | yes | no | yes | number | `number` | `0` |
+| `src` | no | no | yes | no | no | string | `discrete` | required image `src` |
+| `fit` | no | no | yes | no | no | string | `discrete` | renderer default |
+| `source.x` | no | no | yes | no | no | number | `number` | `0` |
+| `source.y` | no | no | yes | no | no | number | `number` | `0` |
+| `source.width` | no | no | yes | no | no | number | `number` | image width |
+| `source.height` | no | no | yes | no | no | number | `number` | image height |
+
+Image radius is not a kernel field. Use `clip.d`.
+
+## Clip And Mask
+
+| Property | path | text | image | point | group | Value | Interpolation | Default |
+|---|---:|---:|---:|---:|---:|---|---|---|
+| `clip.d` | yes | yes | yes | no | yes | string | `discrete` | full-plane clip if authored through edit helper |
+| `mask.d` | yes | yes | yes | no | yes | string | `discrete` | full-plane mask if authored through edit helper |
+| `mask.opacity` | yes | yes | yes | no | yes | number | `number` | `1` |
+
+`clip.d` and `mask.d` are discrete. Smooth-looking path/radius changes must be sampled above the kernel.
+
+## Effects
+
+| Property | path | text | image | point | group | Value | Interpolation | Default |
+|---|---:|---:|---:|---:|---:|---|---|---|
+| `effects.blur` | yes | yes | yes | no | yes | number | `number` | `0` |
+| `effects.brightness` | yes | yes | yes | no | yes | number | `number` | `1` |
+| `effects.contrast` | yes | yes | yes | no | yes | number | `number` | `1` |
+| `effects.saturate` | yes | yes | yes | no | yes | number | `number` | `1` |
+| `effects.hueRotate` | yes | yes | yes | no | yes | number | `number` | `0` |
+| `effects.shadow.dx` | yes | yes | yes | no | yes | number | `number` | `0` |
+| `effects.shadow.dy` | yes | yes | yes | no | yes | number | `number` | `0` |
+| `effects.shadow.blur` | yes | yes | yes | no | yes | number | `number` | `0` |
+| `effects.shadow.color` | yes | yes | yes | no | yes | string | `color` | `#000000` |
+| `effects.shadow.opacity` | yes | yes | yes | no | yes | number | `number` | `1` |
+
+## Structured Paint Internals
+
+These tracks are valid only when the element currently has the matching structured paint type on the matching root (`fill` or `stroke`).
+
+### Linear Gradient
+
+| Property | path fill | text fill | path stroke | Value | Interpolation |
+|---|---:|---:|---:|---|---|
+| `fill.from` | yes | yes | no | `[x,y]` | `point2` |
+| `fill.to` | yes | yes | no | `[x,y]` | `point2` |
+| `stroke.from` | no | no | yes | `[x,y]` | `point2` |
+| `stroke.to` | no | no | yes | `[x,y]` | `point2` |
+
+### Radial Gradient
+
+| Property | path fill | text fill | path stroke | Value | Interpolation |
+|---|---:|---:|---:|---|---|
+| `fill.center` | yes | yes | no | `[x,y]` | `point2` |
+| `fill.focus` | yes | yes | no | `[x,y]` | `point2` |
+| `fill.radius` | yes | yes | no | number | `number` |
+| `stroke.center` | no | no | yes | `[x,y]` | `point2` |
+| `stroke.focus` | no | no | yes | `[x,y]` | `point2` |
+| `stroke.radius` | no | no | yes | number | `number` |
+
+### Gradient Stops
+
+| Property pattern | path fill | text fill | path stroke | Value | Interpolation |
+|---|---:|---:|---:|---|---|
+| `fill.stops.N.offset` | yes | yes | no | number | `number` |
+| `fill.stops.N.color` | yes | yes | no | string | `color` |
+| `stroke.stops.N.offset` | no | no | yes | number | `number` |
+| `stroke.stops.N.color` | no | no | yes | string | `color` |
+
+`N` must point to an existing stop. The kernel does not create missing paint stops.
+
+### Pattern
+
+| Property | path fill | text fill | path stroke | Value | Interpolation |
+|---|---:|---:|---:|---|---|
+| `fill.x` | yes | yes | no | number | `number` |
+| `fill.y` | yes | yes | no | number | `number` |
+| `fill.width` | yes | yes | no | number | `number` |
+| `fill.height` | yes | yes | no | number | `number` |
+| `fill.opacity` | yes | yes | no | number | `number` |
+| `stroke.x` | no | no | yes | number | `number` |
+| `stroke.y` | no | no | yes | number | `number` |
+| `stroke.width` | no | no | yes | number | `number` |
+| `stroke.height` | no | no | yes | number | `number` |
+| `stroke.opacity` | no | no | yes | number | `number` |
+
+## Conflict Warnings
+
+The validator allows but warns for overlapping timeline representations:
+
+- `position` with `x` or `y`
+- `scale` with `scaleX` or `scaleY`
+- whole paint tracks such as `fill` with nested paint tracks such as `fill.to`
+
+Prefer one representation per property family.
+
+## Authoring Rule
+
+If a desired animation is not in this matrix, do not add a new kernel field casually. Prefer a preset/editor helper that compiles into existing tracks.

package/KERNEL_SPEC.md

@@ -0,0 +1,412 @@
+# Sketchmark Kernel Spec
+
+Version: `1`
+
+Sketchmark kernel documents are a strict 2D render and animation interchange format. The kernel is not an authoring language, editor project file, AI prompt format, or preset scene graph.
+
+The kernel's job is to be:
+
+- renderable
+- deterministic
+- validatable
+- easy for editors and compilers to target
+- small enough to keep stable
+
+## Document Shape
+
+Allowed top-level fields:
+
+- `version`: must be `1`
+- `canvas`: required
+- `elements`: optional array
+
+No other top-level fields are allowed.
+
+```json
+{
+  "version": 1,
+  "canvas": {
+    "width": 960,
+    "height": 540,
+    "background": "#ffffff",
+    "duration": 2,
+    "fps": 30
+  },
+  "elements": []
+}
+```
+
+## Canvas
+
+Required fields:
+
+- `width`: number
+- `height`: number
+
+Optional fields:
+
+- `background`: string
+- `duration`: non-negative number
+- `fps`: positive number
+
+Canvas has no camera, 3D space, scene list, assets map, imports, exports, or global timeline.
+
+## Elements
+
+Allowed element types:
+
+- `path`
+- `text`
+- `image`
+- `point`
+- `group`
+
+Common optional fields:
+
+- `id`
+- `opacity`
+- `fill`
+- `stroke`
+- `strokeWidth`
+- `strokeCap`
+- `strokeJoin`
+- `miterLimit`
+- `dashArray`
+- `dashOffset`
+- `drawStart`
+- `drawEnd`
+- `effects`
+- `blendMode`
+- `rotation`
+- `scale`
+- `scaleX`
+- `scaleY`
+- `origin`
+- `clip`
+- `mask`
+- `timeline`
+
+Element IDs must start with a letter or `_` and may contain letters, numbers, `_`, `-`, or `.`. Dot-separated IDs are allowed so authoring layers can generate readable names such as `hero.head`.
+
+Explicitly not allowed:
+
+- editor metadata
+- selections
+- locks
+- guides
+- snapping
+- scene IDs
+- semantic objects
+- rectangles/circles/arrows as separate types
+- `cornerRadius`
+
+Those belong in editor/project/preset layers and must compile down to kernel fields.
+
+## Path
+
+Required:
+
+- `type: "path"`
+- `d`: SVG path data string
+
+Optional:
+
+- `x`
+- `y`
+- common fields
+
+Path `x/y` are rendered as a translation.
+
+## Text
+
+Required:
+
+- `type: "text"`
+- `x`
+- `y`
+
+Optional:
+
+- `text`
+- `lines`
+- `align`: `left`, `center`, `right`
+- `valign`: `top`, `middle`, `bottom`
+- `fontSize`
+- `fontFamily`
+- `weight`
+- `fontStyle`
+- `lineHeight`
+- `letterSpacing`
+- `maxWidth`
+- `wrap`
+- common fields
+
+If both `text` and `lines` exist, renderers may prefer explicit `lines`.
+
+## Image
+
+Required:
+
+- `type: "image"`
+- `src`
+- `x`
+- `y`
+- `width`
+- `height`
+
+Optional:
+
+- `fit`: `fill`, `contain`, `cover`
+- `source`: crop rectangle
+- common fields
+
+Rounded images are represented with `clip.d`, not `cornerRadius`.
+
+## Point
+
+Required:
+
+- `type: "point"`
+- `x`
+- `y`
+
+Points are render-neutral anchors. They can be referenced by authoring tools and timelines, but renderers do not draw visible geometry for points.
+
+## Group
+
+Required:
+
+- `type: "group"`
+- `x`
+- `y`
+- `children`
+
+Optional:
+
+- `width`
+- `height`
+- common fields
+
+Group `x/y` are rendered as group translation. Child coordinates are local to the group.
+
+## Paint
+
+Paint can be:
+
+- color string
+- linear gradient
+- radial gradient
+- pattern
+
+Linear gradient:
+
+```json
+{
+  "type": "linearGradient",
+  "from": [0, 0],
+  "to": [100, 0],
+  "stops": [[0, "#000000"], [1, "#ffffff"]]
+}
+```
+
+Radial gradient:
+
+```json
+{
+  "type": "radialGradient",
+  "center": [50, 50],
+  "radius": 40,
+  "focus": [50, 50],
+  "stops": [[0, "#ffffff"], [1, "#000000"]]
+}
+```
+
+Pattern:
+
+```json
+{
+  "type": "pattern",
+  "src": "image.png",
+  "x": 0,
+  "y": 0,
+  "width": 32,
+  "height": 32,
+  "fit": "cover",
+  "opacity": 1
+}
+```
+
+## Clip And Mask
+
+Clip:
+
+```json
+{
+  "type": "path",
+  "d": "M 0 0 H 100 V 100 H 0 Z"
+}
+```
+
+Mask:
+
+```json
+{
+  "type": "path",
+  "d": "M 0 0 H 100 V 100 H 0 Z",
+  "opacity": 0.8
+}
+```
+
+Clip and mask paths use user-space coordinates for the rendered element context. If an editor wants rounded rectangles, arbitrary reveals, or soft masks, it should compile them into these fields.
+
+## Timeline
+
+Animation is element-local.
+
+```json
+{
+  "timeline": {
+    "start": 0,
+    "end": 2,
+    "tracks": {
+      "position": {
+        "keyframes": [
+          { "time": 0, "value": [10, 20] },
+          { "time": 1, "value": [100, 20] }
+        ]
+      }
+    }
+  }
+}
+```
+
+Timeline fields:
+
+- `start`: optional non-negative number
+- `end`: optional non-negative number
+- `tracks`: map of known animatable property names to track objects
+
+Unknown tracks are invalid.
+
+## Keyframes
+
+Legacy tuple form remains valid:
+
+```json
+[0, 100]
+```
+
+Preferred object form:
+
+```json
+{
+  "time": 0,
+  "value": 100,
+  "out": {
+    "type": "cubicBezier",
+    "x1": 0,
+    "y1": 0,
+    "x2": 0.58,
+    "y2": 1
+  }
+}
+```
+
+Object keyframe fields:
+
+- `time`: finite seconds
+- `value`: JSON-safe timeline value
+- `in`: optional curve
+- `out`: optional curve
+- `interpolation`: optional curve
+
+Keyframes must be sorted by time.
+
+## Curves
+
+Supported curves:
+
+- `graph`
+- `cubicBezier`
+- `hold`
+
+Graph curve:
+
+```json
+{
+  "type": "graph",
+  "points": [[0, 0], [0.5, 0.2], [1, 1]]
+}
+```
+
+Graph `x` is normalized time progress. Graph `y` is normalized value progress.
+
+Cubic Bezier:
+
+```json
+{
+  "type": "cubicBezier",
+  "x1": 0.42,
+  "y1": 0,
+  "x2": 0.58,
+  "y2": 1
+}
+```
+
+Hold:
+
+```json
+{
+  "type": "hold"
+}
+```
+
+Segment curve resolution order:
+
+1. previous keyframe `out`
+2. previous keyframe `interpolation`
+3. next keyframe `in`
+4. track `curve`
+5. legacy `ease`
+6. linear
+
+Named `ease` is legacy compatibility. New authoring tools should emit explicit curves.
+
+## Interpolation Rules
+
+- number to number: numeric interpolation
+- `[x,y]` to `[x,y]`: point interpolation
+- same-length number arrays: numeric array interpolation
+- hex color string to hex color string: color interpolation
+- all other string/object values: discrete switch at the target keyframe
+
+Path data such as `d` and `clip.d` is discrete in the kernel. Smooth-looking path/radius changes should be sampled by an authoring compiler into multiple keyframes.
+
+## Determinism Rules
+
+For the same document and time:
+
+- validation result must be stable
+- resolved frame must be stable
+- SVG output should be stable
+- generated schema must match `schema/visual.schema.json`
+
+Renderers should not read editor/project state, ambient AI context, hidden assets maps, or non-kernel fields.
+
+## Versioning
+
+`version: 1` is the frozen kernel line.
+
+Breaking changes require a new document version. Additive features must still preserve deterministic validation and rendering.
+
+## Kernel Boundary
+
+Do not add these to the kernel:
+
+- motion presets such as `rise`, `fadeIn`, `stagger`, `dogWalk`
+- project source objects such as rectangles, circles, charts, diagrams
+- editor state such as selected, locked, hidden, guides, snapping
+- AI prompts or semantic descriptions
+- benchmark task metadata
+
+Those belong above the kernel and compile down to this spec.

package/PACKS.md

@@ -0,0 +1,81 @@
+# Sketchmark Packs
+
+Packs are shareable collections of presets.
+
+This milestone documents the pack contract only. Sketchmark does not load third-party packs yet.
+
+## Folder Shape
+
+```txt
+my-pack/
+  sketchmark-pack.json
+  index.cjs
+  presets/
+```
+
+## Manifest
+
+```json
+{
+  "name": "my-pack",
+  "version": "1.0.0",
+  "sketchmark": ">=2.0.0",
+  "presets": [
+    {
+      "id": "motions.float",
+      "kind": "motion",
+      "title": "Float"
+    }
+  ]
+}
+```
+
+Fields:
+
+- `name`: package name
+- `version`: pack version
+- `sketchmark`: compatible Sketchmark range
+- `presets`: list of exported preset IDs
+
+Preset `kind` should be one of:
+
+- `shape`
+- `character`
+- `motion`
+- `effect`
+- `transition`
+- `scene`
+
+## Runtime Contract
+
+`index.cjs` should export preset functions:
+
+```js
+module.exports = {
+  presets: {
+    "motions.float": function float({ id, start = 0, duration = 1 }) {
+      return {
+        timelines: {
+          [id]: {
+            position: {
+              keyframes: [
+                { time: start, value: [0, 0], out: { type: "cubicBezier", x1: 0.42, y1: 0, x2: 0.58, y2: 1 } },
+                { time: start + duration / 2, value: [0, -16], out: { type: "cubicBezier", x1: 0.42, y1: 0, x2: 0.58, y2: 1 } },
+                { time: start + duration, value: [0, 0] }
+              ]
+            }
+          }
+        }
+      };
+    }
+  }
+};
+```
+
+## Rules
+
+- Packs are authoring code, not kernel schema.
+- Pack presets must compile to pure `PresetFragment` objects.
+- Pack output must validate as a normal Sketchmark kernel document after application.
+- Trusted `.cjs` packs may execute local code. A safer declarative pack format can come later.
+- Pack manifests should describe what exists; they should not be copied into `.visual.json`.