@vosjs/cli 0.53.4 → 0.53.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vosjs/cli",
-  "version": "0.53.4",
+  "version": "0.53.5",
   "description": "The vos CLI: record the real product from a scripted browser flow, auto-zoom from the cursor track, cut as data in doc.json, render deterministic video and stills, deliver a release's media per destination spec, and sync with vos.so. One binary, every verb, MIT.",
   "type": "module",
   "license": "MIT",
@@ -49,10 +49,10 @@
   "dependencies": {
     "mediabunny": "^1.55.7",
     "playwright": "^1.49.0",
-    "@vosjs/core": "^0.25.3",
     "@vosjs/editor": "^1.4.0",
     "@vosjs/elements": "^0.9.0",
     "@vosjs/render-core": "^0.3.9",
+    "@vosjs/core": "^0.25.3",
     "@vosjs/shared": "^0.5.0",
     "@vosjs/studio-core": "^0.33.1",
     "@vosjs/timeline": "^0.4.1",

package/skills/VERSION

@@ -1 +1 @@
-0.9.1
+0.10.0

package/skills/vos-port/SKILL.md

@@ -43,10 +43,15 @@ not in `node_modules`.
    `font.family` and `font.color` take `{ "$data": "<key>" }` (they
    re-raster live on a data edit). Logos and shapes are `svg` or `image`
    elements, footage a `video` element. Elements are what the studio selects
-   and moves.
+   and moves. **Every visible word is a bound element**, whatever animates
+   it: a word whose letters rise one by one is ONE `split` element bound to
+   its key, never a pool of per-letter elements filled from `onFrame` (a
+   person can retype the first in the studio and not the second).
 4. **Motion is the timeline.** `createTimeline` holds the tweens, on
    `ctx.elements.get(id).props` (whole) or `.segments` (`split: { type:
-   'chars' | 'words' | 'lines' }` units), in the GSAP dialect. Keep curves
+   'chars' | 'words' | 'lines' }` units), in the GSAP dialect. Read
+   `el.segments` inside `createTimeline` and nowhere else: a data edit to a
+   bound split word rebuilds its units and the timeline over them. Keep curves
    exact: Remotion's `Easing.bezier(a, b, c, d)` is `ease: 'css-bezier(a, b,
    c, d)'`; GSAP eases keep their names.
 5. **Scenes are labels.** One `tl.addLabel('<scene>', t)` per scene or
@@ -185,7 +190,7 @@ stated approximation:
 
 | Source | In vos today |
 | --- | --- |
-| `overflow: hidden` masks, `clip-path` reveals | no element masks: approximate with opacity, or paint the item |
+| `overflow: hidden` masks, `clip-path` reveals | no element masks: approximate a masked WORD with opacity (it stays a bound element); paint only a shape |
 | a colour per split unit (`charStyle` making one letter red) | segments carry x/y/opacity/scale/rotation only: a separate element, or paint it |
 | `mixBlendMode` | no blend modes on elements: paint it |
 | a shape's colour as a knob | an svg's colours are compiled in (static `colors`): paint the shape if its colour must change live |

package/skills/vos-port/references/elements-and-context.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/build-element-reference.mjs from @vosjs/core 0.25.2, @vosjs/elements 0.8.3 and @vosjs/timeline 0.4.1. Do not edit by hand: re-run the script. -->
+<!-- Generated by scripts/build-element-reference.mjs from @vosjs/core 0.25.3, @vosjs/elements 0.9.0, @vosjs/timeline 0.4.1 and @vosjs/shared 0.5.0. Do not edit by hand: re-run the script. -->
 
 # Elements, the context and eases: the declarations
 
@@ -117,7 +117,16 @@ interface VosConfigJson {
 
 `content`, `font.family` and `font.color` of a text element are the three
 fields that take a `{ "$data": "<key>" }` binding, and the only ones that
-re-resolve on a data edit; every other field is read once at build.
+re-resolve on a data edit; every other field is read once at build. The key
+names a TOP-LEVEL key of `config.data` (no dotted path, no array index), so
+a list of words that each need binding is one key per word; `content`
+takes the value as a string. A bound `split` element follows a data edit
+too: its units are rebuilt from the new words and the timeline is rebuilt
+over them (`@vosjs/elements` 0.9.0 with core 0.25.3; before that the
+studio reloaded the program for such a knob and other hosts kept the old
+word). So a per-letter word that is a knob is ONE bound `split` element,
+never a pool of per-letter elements written from `onFrame`: a person can
+retype a bound element in the studio, and cannot retype a pool.
 `font.size`, `letterSpacing`, `transform.translateX/Y`, `stroke.width`
 and `shadow.blur` are design pixels (a 1080-high frame). There is no
 `mask`, `clip`, `blend` or group field on any element: SKILL.md's
@@ -318,9 +327,14 @@ The tween dialect animates numbers only: tween `fontSize` and
 
 Every such write queues a re-raster, even of an unchanged value, so guard
 a per-frame write: `if (el.props.content !== next) el.props.content = next`.
-A `split` text element does not re-raster at all: these writes are ignored
-on it, so text that changes and text that animates per letter are two
-elements.
+These writes do nothing on a `split` element (its units are structure):
+change a split element's words through its binding, never its props.
+
+A text raster never fails for being long: its density drops until the
+longest side fits the GPU's largest texture (4096 px when the GPU does
+not say), so a line past about 4096 design px at 1080p, or half that at
+2160p, renders softer. Only then is a long marquee worth cutting into
+elements, and each piece stays bound.
 
 ```ts
 /**
@@ -381,9 +395,14 @@ interface ElementInstance {
     props: ElementProps;
     /**
      * Split text segments (only available when split config is defined).
-     * Each segment has its own ElementProps for individual animation.
+     * Each segment has its own ElementProps for individual animation. A data
+     * edit to a BOUND split text rebuilds them from the new words: the array
+     * and its objects are replaced (and the host rebuilds the timeline), so
+     * read `el.segments` inside createTimeline, never cache it elsewhere.
      */
     segments?: ElementProps[];
+    /** Set when a data edit rebuilt this element's units; the host clears it. */
+    structural?: boolean;
     /** Update element content (text or image src) */
     setContent: (content: string) => void;
     /**
@@ -409,6 +428,83 @@ interface ElementInstance {
 }
 ```
 
+## Knobs (`config.params` and `config.presets`)
+
+A knob is a `ParamSpec` over one top-level `data` key, and a Look a named
+set of values. vos.so keeps at most 12 knobs and 8 Looks, the first valid
+ones, and `vos check` names every one it would drop before a push. Every
+bound word stays a `data` key whether or not it has a knob: the studio's
+element panel retypes a bound element directly, so the 12 knobs go to what
+a person reaches for first (the palette, the headline), not to every word.
+A `text` knob with `multiline: true` suits a list a painter draws line by
+line; a list of elements is one key per element.
+
+```ts
+/**
+ * Config params: `config.params`
+ * declares the `ctx.data` keys a program reads as its creative knobs — key,
+ * kind, range, default. THE one params module, shared by the web Remix
+ * panel, the API, and scripts (the knob honesty lint): edits commit by
+ * baking BOTH `params[i].default` and `data[key]` into the config, so
+ * saves/exports/server renders pick the values up through the existing
+ * `config.data` machinery with zero new plumbing.
+ *
+ * The engine schema does not know `params` yet (upstream addition pending) —
+ * `vosConfigJsonSchema` STRIPS unknown fields on parse, so the API re-attaches
+ * validated params at the storage boundary (the platform's server-side copy;
+ * change both together) and
+ * this module validates defensively.
+ */
+type ParamValue = number | string | boolean;
+
+interface ParamSpec {
+    /** The ctx.data key the program reads. */
+    key: string;
+    /** Human label; falls back to the key. */
+    label?: string;
+    /** One sentence on what the knob changes (U3b — knobs carry meaning). */
+    hint?: string;
+    /** Unit shown inside the number field: px, %, s, ×, °. */
+    unit?: string;
+    /** Optional card grouping; ungrouped knobs land on the Remix card. */
+    group?: string;
+    /** Sort order within a group (falls back to declaration order). */
+    order?: number;
+    kind: 'number' | 'color' | 'select' | 'toggle' | 'text' | 'font';
+    /** number kind */
+    min?: number;
+    max?: number;
+    step?: number;
+    /**
+     * select kind: the enumerated choices (REQUIRED, ≥2). font kind: an
+     * OPTIONAL curation — the families the knob offers; absent = the whole
+     * hosted catalog. Faces travel with the value: `applyParamValue` writes
+     * the chosen family's hosted faces into `data.fonts`, which the engine
+     * (core ≥0.17) registers at boot and on SET_DATA — no `config.fonts`
+     * declaration needed, no recompile.
+     */
+    options?: string[];
+    /** text kind: render a multiline editor (content knobs, e.g. a headline). */
+    multiline?: boolean;
+    default: ParamValue;
+}
+
+/**
+ * A Look (U3b): a named set of param values — the feel-the-range layer.
+ * Tap a look, then fine-tune; applying is ONE undoable multi-value commit.
+ */
+interface LookPreset {
+    name: string;
+    values: Record<string, ParamValue>;
+}
+
+/**
+ * Text params carry URLs (modelUrl knobs) and bound content
+ * (headline knobs) — longer than other string kinds.
+ */
+const TEXT_PARAM_MAX = 280;
+```
+
 ## The context (`ctx`)
 
 `setup(ctx)` gets a `SetupContext` and may return assets;

package/skills/vos-port/references/hyperframes.md

@@ -24,7 +24,7 @@ units (render pixels, y down, degrees counter-clockwise).
 | a CSS `cubic-bezier(a, b, c, d)` timing | `ease: 'css-bezier(a, b, c, d)'` (exact; spelled `cubic-bezier` it plays linear) |
 | CSS `--chrome` set by the timeline | a `data` value read in `onFrame`, or a tween on the element that shows it |
 | faces resolved by the runtime from CSS families | `fonts: [{ family, weight, url }]` from the catalog |
-| `mix-blend-mode`, `clip-path`, `overflow: hidden` reveals | GAPS: the painter, or an opacity approximation, said |
+| `mix-blend-mode`, `clip-path`, `overflow: hidden` reveals | GAPS: a revealed word keeps its bound element with an opacity approximation; the painter only for a shape; said in the push note |
 
 Two traps specific to HyperFrames sources: