@vosjs/cli 0.53.0 → 0.53.2

package/dist/cli.js

@@ -709,7 +709,7 @@ async function cmdCheck(argv) {
   return result.ok ? EXIT_OK : EXIT_ERROR;
 }
 async function delegate(argv, viaAlias = false) {
-  const { run } = await import("./run-RFFLVLVQ.js");
+  const { run } = await import("./run-W5UTMIFU.js");
   if (viaAlias && argv[0]) {
     process.stderr.write(
       `note: "vos voila ${argv[0]}" is now "vos ${argv[0]}".
@@ -749,7 +749,7 @@ async function main() {
     const engine = HELP_ENGINE.split("\n").filter(
       (l) => l.startsWith(`  vos ${cmd} `)
     );
-    const { verbHelp } = await import("./run-RFFLVLVQ.js");
+    const { verbHelp } = await import("./run-W5UTMIFU.js");
     const take = verbHelp(cmd);
     process.stdout.write(
       `${engine.join("\n")}
@@ -781,7 +781,7 @@ ${take.includes("no such verb") ? "" : take}`
 main().then(async (code) => {
   if (code === EXIT_OK) {
     const verb = process.argv[2] ?? "";
-    const { HELP } = await import("./run-RFFLVLVQ.js");
+    const { HELP } = await import("./run-W5UTMIFU.js");
     const documented = [
       ...helpFlagsFor(HELP_ENGINE, verb),
       ...helpFlagsFor(HELP, verb)

package/dist/index.js

@@ -23,7 +23,7 @@ import {
   takePaths,
   validateActions,
   waitForPageDone
-} from "./chunk-WGBRKQPB.js";
+} from "./chunk-ZARSNMVY.js";
 import {
   BrowserUnavailableError,
   apiError,

package/dist/{run-RFFLVLVQ.js → run-W5UTMIFU.js}

@@ -6,7 +6,7 @@ import {
   takeBackdrop,
   takeBrowserArgs,
   verbHelp
-} from "./chunk-WGBRKQPB.js";
+} from "./chunk-ZARSNMVY.js";
 import "./chunk-PJX3XE7G.js";
 import "./chunk-6XPFWQKP.js";
 export {
@@ -17,4 +17,4 @@ export {
   takeBrowserArgs,
   verbHelp
 };
-//# sourceMappingURL=run-RFFLVLVQ.js.map
+//# sourceMappingURL=run-W5UTMIFU.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vosjs/cli",
-  "version": "0.53.0",
+  "version": "0.53.2",
   "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,14 +49,14 @@
   "dependencies": {
     "mediabunny": "^1.55.7",
     "playwright": "^1.49.0",
+    "@vosjs/core": "^0.25.2",
     "@vosjs/editor": "^1.4.0",
-    "@vosjs/core": "^0.25.0",
-    "@vosjs/elements": "^0.8.2",
-    "@vosjs/render-core": "^0.3.7",
-    "@vosjs/shared": "^0.4.1",
-    "@vosjs/studio-core": "^0.33.0",
-    "@vosjs/tween": "^0.8.2",
-    "@vosjs/timeline": "^0.4.1"
+    "@vosjs/elements": "^0.8.3",
+    "@vosjs/render-core": "^0.3.8",
+    "@vosjs/shared": "^0.5.0",
+    "@vosjs/studio-core": "^0.33.1",
+    "@vosjs/timeline": "^0.4.1",
+    "@vosjs/tween": "^0.8.2"
   },
   "devDependencies": {
     "@types/node": "^22",

package/skills/VERSION

@@ -1 +1 @@
-0.7.1
+0.9.0

package/skills/vos-port/SKILL.md

@@ -23,7 +23,11 @@ Two ways to get this wrong, both seen in real ports:
 Read `references/intro-port.mjs` first: the Remotion showreel's intro scene,
 ported by these rules and checked against Remotion's own render. It is the
 shape every port takes: real functions, stringified into a `config.json`
-(`node intro-port.mjs` writes one beside it).
+(`node intro-port.mjs` writes one beside it). Every field a config, an
+element, `ctx` and an ease accept is in `references/elements-and-context.md`,
+copied from the published declarations with the facts they leave out
+(which props re-raster, what `vos check` says about eases): read it there,
+not in `node_modules`.
 
 ## The rules (the port grammar)
 
@@ -72,18 +76,64 @@ shape every port takes: real functions, stringified into a `config.json`
   translateY }` in design pixels, never a `tl.set` on `props.x/y`, for any
   text whose content or colour changes live: every re-raster lays the
   element out again from its config and drops a tweened position.
-- **Bind a live text to its full words.** Text that `onFrame` writes each
-  frame (a scramble, a counter) starts as `{ "$data": "subtitle" }`, never
-  `' '`: a still capture (and so the vos.so thumbnail) misses what `onFrame`
-  writes, and then shows the bound words instead of nothing.
+- **Text that `onFrame` writes is missing from a still.** A scramble or a
+  counter written into `props.content` each frame shows in `vos render`
+  output (a frame late) and is BLANK in `vos still` and in the vos.so
+  thumbnail. Check it in a rendered frame, and set the program's cover
+  (`vos push --still <t>`, cli 0.53+) at a moment where that text is not the
+  point.
 - **Transform origin is the centre.** Remotion's `transformOrigin: 'right
   center'` with `scaleX` becomes a centre scale plus an `x` tween that keeps
   the right edge still: `{ scaleX: 0, x: x0 + (width / 2) * k }`.
 
+## Layering: where a painter goes (measured)
+
+A frame draws in this order, and a painter joins it at the place it names:
+
+1. **The 3D scene** (`ctx.scene`, `ctx.camera`) first, `scene.background`
+   under all of it. A ground or a 3D object lives here, under every element.
+2. **Then the elements**, one overlay scene per distinct element `zIndex`
+   (default 100), lowest first, depth cleared between them, all drawn with
+   `ctx.overlayCamera`: orthographic, in RENDER pixels, centred on the frame
+   (x right, y up in three.js terms).
+3. **Inside an overlay scene, later wins**: element *i* of `config.elements`
+   has `renderOrder = zIndex + i × 0.01` (a split unit adds `0.001` per
+   unit). Order elements in the array the way the source stacks them.
+
+A painter that must sit BETWEEN elements is a plane in `ctx.overlayScene`
+(the lowest-zIndex overlay scene, so keep every element at the default
+`zIndex`) with a `renderOrder` between its neighbours:
+
+```js
+// createContent: a painter over element 1 and under element 2
+const T = ctx.THREE
+const canvas = document.createElement('canvas')
+const tex = new T.CanvasTexture(canvas)
+tex.colorSpace = T.SRGBColorSpace // or every colour renders lighter
+const mesh = new T.Mesh(
+  new T.PlaneGeometry(1, 1),
+  new T.MeshBasicMaterial({ map: tex, transparent: true, depthTest: false, depthWrite: false }),
+)
+mesh.scale.set(ctx.resolution.width, ctx.resolution.height, 1) // full frame, render px
+mesh.renderOrder = 100 + 1 * 0.01 + 0.005
+mesh.frustumCulled = false
+ctx.overlayScene.add(mesh)
+// onFrame: paint `canvas` from ctx.time and ctx.data, then tex.needsUpdate = true
+```
+
+Keep the slot numbers in `data` beside the scene table (`layers: { card:
+100.015, grain: 100.995 }`), computed from element indices in the build
+script, so adding an element never silently reorders a painter. A painter
+over everything (grain, a vignette) takes the highest slot; a CSS blend mode
+is a custom `blending` on its material, stated in the push note as an
+approximation.
+
 ## The mapping
 
 - Remotion: `references/remotion.md`.
 - HyperFrames: `references/hyperframes.md`.
+- The target's types (elements, `ctx`, the timeline, eases):
+  `references/elements-and-context.md`.
 - A hand-rolled page (a single HTML file, its own canvas engine): read it as
   source with the same tables. What the page draws with DOM becomes
   elements; what it paints in a canvas is a painter, kept to the procedural