@vosjs/cli 0.46.1 → 0.48.0

package/skills/product-video/references/taste.md

@@ -0,0 +1,115 @@
+# Taste — the product-video quality bar
+
+The rubric for judging a take before its render ships. Judge stills
+**multimodally**: look at the images, don't just check numbers.
+
+## The quality loop (run it, don't skip it)
+
+1. `vos record --actions actions.json --out take --strict --json` —
+   exit 2 means the flow is broken; fix selectors, never ship around a skip.
+2. `vos validate take` — doc lints must pass (warnings are judgment calls).
+3. `vos frames take --at-zooms --times 0,25%,50%,75%,100%` — look at every
+   still against the rubric below. The zoom apexes are where quality lives;
+   judge those hardest.
+4. Iterate doc.json → spot-check with `vos render take x.webm --range a..b --draft`
+   (seconds, not a full re-render) → re-frame the changed region.
+5. Full render only when the stills pass. Verify the final with one more
+   `frames --at-zooms` against the SAME rubric before declaring done.
+
+## Story shape
+
+1. **One idea per clip.** A take demonstrates one flow or one feature —
+   navigation to it is overhead, not story. Open as close to the money shot
+   as possible; a cold viewer should see the point inside 3 seconds.
+2. **≤ 30s for marketing clips**; 8–15s is the sweet spot for a page hero.
+   Launch videos may run longer but every scene must still earn its seconds.
+3. **End settled.** Close on a resolved state (result visible, motion parked),
+   never mid-action — the loop point should read as intentional.
+
+## Flow authoring (actions.json)
+
+4. **Route the cursor away from hover-traps.** Nav links that live next to
+   hover-triggered menus (mega-panels, frosted backdrop-blur scrims) will
+   open them as the cursor passes — the rest of the take then plays behind a
+   blur. Unless the menu IS the subject, path the cursor below the nav
+   (`move` to page content first), or target an equivalent link outside the
+   nav.
+5. **Pacing is the zoom plan.** Hovers of 700–900ms on the things that matter
+   become the zooms; open with `wait ≥700ms`, give navigations 1200–2000ms,
+   end with a settle wait. A rushed flow reads as a rushed video AND plans
+   no zooms.
+6. **Real interactions only.** Click things that respond, type real strings
+   (no "asdf"), scroll to content — the witnessed-capture claim dies the
+   moment footage looks staged.
+
+## Zoom & camera
+
+7. **Levels 1.4–2.8 read well**; above 3× is for genuine detail (a number, a
+   toggle), and must be brief. Below 1.3× reads as drift, not intent.
+8. **One zoom per beat.** Zooms that chain across unrelated UI read as a lost
+   camera. If the planner over-suggested, delete spans — an un-zoomed second
+   is better than an unmotivated one.
+9. **Focus on the subject, not the cursor resting spot.** `cx/cy` are
+   normalized [0..1]; check the apex still shows the thing the beat is about,
+   with breathing room (the subject inside the middle ~60% of the crop).
+10. **Camera style is a sentence, not a spice rack.** Default `glide` for
+    marketing calm; `snappy` only for dense click-through demos; never mix
+    intents within one short clip.
+
+## Frame & destination
+
+11. **Footage honesty.** Never export above the recording's capture width —
+    `validate` warns; fix the viewport at record time instead of upscaling.
+12. **Background is ambience, not a subject.** A `frame.backgroundMedia`
+    loop should sit _behind_ the work, never compete with it: prefer a calm
+    ambient loop, and set `dim` (≈0.2–0.4) whenever the card carries dense
+    UI or the take runs long enough to loop visibly. A high-contrast or fast
+    background behind a text-heavy screen is a rejection.
+13. **Tilt is punctuation, not texture.** `doc.tilt` spans lean the card for
+    a beat and return to rest — at most one pose change per ~5s, in the
+    ±5..18° band, paired with the zoom moments (same `in`/`out` chains the
+    two camera moves; `tiltStyle` does this for you). Lean TOWARD the focus
+    (right-side focus = negative `ry`). Never oscillate — a wobbling card is
+    a rejection — and never leave the card leaning across a whole take: a
+    permanent lean reads as a rendering bug, not a style. Spans are the only
+    way to pose the card (there is no static tilt), so rest is always flat
+    and every lean has to earn its moment.
+
+## Smoothness — the north star
+
+A product video's baseline quality is SMOOTHNESS: the frame should always be
+alive, and nothing should change all-at-once unless it's a deliberate cut.
+The two enemies, both measurable:
+
+14. **Dead time.** A still frame is not the defect: a page the viewer is
+    reading is content, and a workspace tour is mostly still. What is dead
+    is a still frame under a PARKED cursor past the beat it takes to read
+    what changed: about 1 s after a page changed, 0.6 s after a control
+    did. The record done event reports it per step as `dead` (`ms`, `pct`,
+    `steps[]` with how long each hold ran after its page settled and how
+    much of that was past the beat; `freezePct` stays as the plain fact of
+    stillness, `@vosjs/cli` 0.46 and later). Budget: **≤20% dead**, no
+    single dead hold >1.5s. The fix is the step's `ms`: a hold is what it
+    takes to read what changed, so cut the named steps to their beat. Then,
+    where a flow allows it, keep something alive in frame (a playing
+    preview, a live canvas, a scroll), and hover things that respond with
+    motion. Never choose a flow to make a stillness number smaller.
+15. **Full-frame bangs.** Instant UI re-layouts (filter clicks, page
+    navigations) read as jump cuts — violent when zoomed. Budget: **≤1 bang
+    per ~5s**, and let them happen WIDE (place zoom spans so the camera has
+    released before a click that re-layouts; zoom into the RESULT, not the
+    trigger). Census: `ffmpeg -vf "select='gt(scene,0.12)'"` on the final
+    render — each detection should be a transition you _chose_.
+
+## Judge each still set against
+
+- **Blur check** — nothing unintentionally blurred (hover scrims, mid-seek
+  frames). If a still looks soft, find out why before shipping.
+- **Chrome check** — browser bar style matches the destination (mac for
+  marketing, minimal/none inside app-like framings); no double chrome.
+- **Cursor check** — the dot rests on or beside the subject at every apex,
+  never floating in dead space; click effects land under it.
+- **Text legibility** — body text in the footage readable at the render size;
+  if not, the zoom level or viewport was wrong.
+- **First/last frame** — both must stand alone as posters (the first frame IS
+  the poster; the last frame is what loops into the first).

package/skills/product-video/references/troubleshooting.md

@@ -0,0 +1,116 @@
+# Troubleshooting
+
+## Exit codes
+
+| Code | Meaning | Fix |
+|---|---|---|
+| 0 | ok | |
+| 1 | error | read stderr; `--json` puts the message in the done event |
+| 2 | usage error, or `--strict` failure | see below |
+| 3 | no browser | `npx playwright install chromium`, or set `VOS_BROWSER_PATH` to a Chrome/Chromium binary |
+| 4 | the recorder met a sign-in instead of the page (`@vosjs/cli` 0.41 and later) | it needs a SESSION, not a new script: walk `sessions.md`, then pass `--storage-state <file>`. Nothing was recorded and nothing was cleared. `--allow-wall` only when the sign-in page IS the take |
+
+## The wall (exit 4)
+
+`vos record`, `create` and `--dry-run` check where the first navigation
+landed before a frame is captured. Refused always: a 401 or 403, a redirect
+to an identity provider or a sign-in path, a sign-in form rendered in place.
+Refused under `--strict` and in a rehearsal, warned otherwise: a redirect
+somewhere else with no sign-in in sight, which is what a site that shows
+strangers its marketing page looks like.
+
+- Do not touch `actions.json`. The script is fine; the browser is a
+  stranger. One `curl -sI <url>` before you script tells you the same thing
+  sooner: a 30x away from the page you asked for is a wall.
+- A re-record that worked last week and exits 4 today is an EXPIRED session.
+  Mint it again; the old footage is still there, the refusal clears nothing.
+- A digest that prints `WALL` is footage recorded past a wall
+  (`--allow-wall`, or a redirect without `--strict`): it may be the wrong
+  page. Re-record with a session before cutting it.
+
+## `setup #N … the selector never appeared` (exit 2)
+
+The off-camera sign-in did not finish, so the take did not start. A
+selector in `setup` is checked the same way a step's is: rehearse with
+`--dry-run`. `the environment variable NAME is not set` means the shell
+that ran `vos record` did not export it; the value is never read from a
+file. A setup that ran and then met the wall (exit 4) signed in with the
+wrong credentials or into the wrong place.
+
+## `EXPOSED in the frame`
+
+Not an error: the take recorded. The recorder read the visible text after
+each step and saw something shaped like an email address, a key or a card.
+It reports the kind and the place, never the string. Fix it in the script
+(`mask`, or a demo account) and re-record; a blur added afterwards in
+`doc.json` still leaves the real value in `recording.webm`, which is what
+`vos push` uploads. `MASK hid nothing: <selector>` (exit 2) means the
+selector matched no element, so whatever it was for may be showing.
+
+## Strict-mode failures (exit 2)
+
+`vos record --strict` exits 2 when a selector was skipped or a navigation
+never reached networkidle, with `skipped[]` in the `--json` done event.
+
+- A skipped selector means the flow is broken: the element wasn't there, the
+  selector is unstable (nth-child chains), or the page needed more settle
+  time. Fix the actions.json — never ship a take that silently skipped steps.
+- Networkidle timeouts on pages with long-polling/websockets: add explicit
+  `wait` steps after navigation instead of relying on networkidle.
+- Always pass `--strict`. The lenient default exits 0 over broken flows,
+  which is how bad takes ship.
+
+## Dead time
+
+The record done event reports `dead` (`@vosjs/cli` 0.46 and later): a
+still frame under a parked cursor past the beat it takes to read what
+changed, per step, with how long the hold ran after the page settled.
+`freezePct` beside it is the plain fact of stillness and is not a defect
+on its own (a page being read is content). Budget: ≤20% dead, no single
+dead hold >1.5s. The take-ready line names the steps.
+
+1. Cut the named steps' `ms` to their beat: about 1 s after a page
+   changed, 0.6 s after a control did.
+2. Where the flow allows, keep something alive in frame, and hover things
+   that respond with motion — those dwells become zooms too.
+3. Trim dead heads/tails with `segments`; compress slow stretches with
+   `speed` spans.
+
+Never choose a flow to make `freezePct` smaller.
+
+## Browser and environment
+
+- **MP4 output needs system Chrome** (`--format mp4`); Playwright's bundled
+  Chromium lacks the H.264 encoder. WebM works everywhere.
+- **Headless WebGL**: if a render hangs at scene init on a CI box, the
+  browser may lack GPU/SwiftShader flags. Prefer system Chrome; file an
+  issue with the `--json` output if it persists.
+- **Network**: the render page imports three/mediabunny from esm.sh —
+  rendering needs outbound network. A fully offline sandbox can record
+  nothing and render nothing; surface that limitation rather than shipping a
+  broken artifact.
+- Recordings served to a render page must come from a server that supports
+  HTTP Range/206 (the CLI's own take server does) — video seeking hangs
+  forever without it.
+
+## Performance expectations
+
+- Recording is always real-time (it drives a real browser).
+- Render ≈ 1.5× real-time at 1080p with ~5s fixed startup; 2K is ~2× the
+  per-frame cost; `--parallel N` pays off past ~30s of footage (ignored when
+  audio is muxed).
+
+## Take directory anatomy
+
+| Path | What | Keep? |
+|---|---|---|
+| `recording.webm` | the re-render source footage | KEEP |
+| `doc.json` | every editable decision | KEEP — this is the document |
+| `actions.json` | the recipe that recorded it | keep for re-records |
+| `frames/` | encode intermediate (~1GB at 2K) | deletable |
+| `meta.json` | capture geometry | keep |
+
+## Determinism
+
+Renders are deterministic: same take + same doc.json = same frames, on any
+machine. If two renders differ, the doc changed (diff it) — not the weather.

package/skills/vos-authoring/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: vos-authoring
+description: Author a vos animation program (VosConfigJson) from scratch or debug one — declarative configs compiling into deterministic Three.js + GSAP-dialect animations on the MIT vos engine (@vosjs/core), validated locally with compileVosConfig. Covers the schema, dialect rules, 2D overlay elements, shaders, and params/presets knobs. Use when asked to write a vos animation program, create a VosConfigJson, make a programmatic motion graphic or logo animation, or fix a config that fails to compile or lint.
+license: MIT
+---
+
+# Vos program authoring
+
+You generate VosConfigJson files — declarative animation configs that compile
+into Three.js + GSAP-dialect animations on the vos engine
+([github.com/vosjs/vos](https://github.com/vosjs/vos), MIT). The preview is
+the render: a config produces the same frames on every machine.
+
+## Workflow
+
+1. **Parse the prompt**: identify the animation concept, mood, colors, and
+   any referenced images.
+2. **Design the approach**: choose camera preset, materials, effects, and
+   animation strategy (see the category guide below).
+3. **Generate the config**: write a complete, valid VosConfigJson to
+   `<kebab-case-name>.json` wherever the project keeps configs.
+4. **Validate locally** (see below), then render or preview it.
+
+If the user provides an image, analyze its visual style (colors, mood,
+composition, lighting) and translate those qualities into the scene.
+
+## Validate and render locally
+
+```bash
+npm i @vosjs/core        # compiler + lints
+node -e "import('@vosjs/core/compiler').then(async m => { \
+  const cfg = JSON.parse(require('fs').readFileSync('my-config.json','utf8')); \
+  m.compileVosConfig(cfg); console.error('compiles clean') })"
+```
+
+`compileVosConfig(config)` must not throw — it is the same compiler every
+player and render server runs. For visual checks, the CLI
+(`npm i -D @vosjs/cli`):
+
+```bash
+vos render my-config.json out.webm     # deterministic video render
+vos still  my-config.json out.webp --time 2.5
+vos preview my-config.json             # local playback page
+vos info   my-config.json
+```
+
+## Share for preview (no account needed)
+
+Local render is the default — nothing leaves the machine unless the user
+asks for sharing or hosting. When they do want to see it hosted (playable
+link, fine-tuning in the vos.so studio) and no API key is configured, use
+the claimable push:
+
+```bash
+vos push my-config.json --claimable --title "…"
+# → claim: https://vos.so/claim/…   expires: <72h from now>
+
+# No CLI, or an older one? The same thing over plain HTTP:
+curl -s -X POST https://vos.so/api/claim \
+  -H 'content-type: application/json' \
+  -d '{"title": "…", "config": <the VosConfigJson>}'
+# → { "claimUrl": "https://vos.so/claim/…", "expiresAt": "…" }
+```
+
+Hand `claimUrl` to the user and nowhere else — it is the only reference and
+the only credential. It lasts 72 hours; unclaimed work is deleted after
+that (re-push if it lapses). Claiming moves the vos into the user's
+library. With a key configured (`VOS_API_KEY` or `vos login`), prefer
+`vos push` — keyed pushes have no expiry. Programs only, config ≤200KB,
+5 pushes per day per network.
+
+## VosConfigJson structure
+
+```json
+{
+  "version": 2,
+  "duration": 8,
+  "scene": { "background": "#0a0a1a", "fog": { "type": "exp2", "color": 0, "density": 0.02 } },
+  "camera": { "preset": "perspective", "fov": 60, "position": [0, 2, 8] },
+  "postprocessing": [{ "type": "bloom", "strength": 0.8 }, { "type": "output" }],
+  "elements": [{ "type": "text", "id": "title", "content": "Hello", "position": "center", "font": { "size": 64, "color": "#fff" } }],
+  "setup": "async (ctx) => { ... return data }",
+  "createContent": "(ctx, setupData?) => { ... return { objects, refs, dispose } }",
+  "createTimeline": "(ctx, content, duration) => { ... return tl }"
+}
+```
+
+Complete field reference: `references/schema-reference.md`. Working
+examples of every major type: `references/examples.md`.
+
+## Critical rules
+
+### DO
+1. Functions must be valid **JavaScript strings** — NO TypeScript (no `as`,
+   no type annotations)
+2. Access Three.js via `ctx.THREE`, GSAP-dialect via `ctx.gsap`, scene via
+   `ctx.scene`
+3. `createContent` MUST return `{ objects: [...], refs: {...}, dispose: () => {...} }`
+4. `createTimeline` MUST return `ctx.gsap.timeline({ paused: true })`
+5. Always include `dispose()` that cleans up geometries, materials, textures
+6. Use `ctx.resolution.drawingBufferWidth/drawingBufferHeight` for shader
+   `iResolution`
+7. Set `mesh.frustumCulled = false` for fullscreen shader quads
+8. Set `depthWrite: false, depthTest: false` on fullscreen ShaderMaterial
+9. Always include `{ "type": "output" }` as the last entry when using
+   postprocessing
+10. Add all scene objects to both `scene` and the returned `objects` array
+11. Tween shader uniforms directly:
+    `tl.to(uniforms.iTime, { value: duration, duration, ease: 'none' })`
+12. For per-frame logic (InstancedMesh updates, camera math), use `onUpdate`
+    callbacks on tweens
+
+### DON'T
+1. **NO `${}` template literals** in function strings — they evaluate at
+   compile time. Use string concatenation.
+2. **NO escaped backticks** — write shaders as inline strings, or use
+   single-line concatenation
+3. **NEVER `repeat: -1`** on individual tweens — looping is handled by the
+   player; this breaks duration tracking
+4. **NO CSS-style** `style` objects or `textContent` on elements — elements
+   are WebGL planes
+5. **NO external imports** — everything is on `ctx` (THREE, gsap, loaders,
+   utils)
+6. **NO `requestAnimationFrame`** or `setTimeout` — use `onUpdate` callbacks
+7. **NO `Date.now()` / `Math.random()`** in frame paths — determinism is the
+   contract; derive everything from the timeline's time and `ctx.data`
+8. **NO `onFrame`** for new configs — put all per-frame logic in `onUpdate`
+
+## Params and Looks (make it remixable)
+
+Declare 2–4 knobs via `config.params` — editors render them as live controls,
+and other agents can retune the program without touching code. Each param
+documents a `ctx.data` key the program reads:
+
+```json
+"params": [{ "key": "hue", "label": "Hue", "kind": "number",
+             "min": 0, "max": 1, "default": 0.6,
+             "hint": "Shifts every color around the wheel",
+             "unit": "°", "group": "Color", "order": 1 }]
+```
+
+- kinds: `number` (min/max/step) | `color` | `select` (options) | `toggle`
+- `hint`: ONE sentence on what visibly changes — write it
+- the program reads it where it animates:
+  `const d = ctx.data || {}; if (typeof d.hue === 'number') u.uHue.value = d.hue`
+- Name knobs by INTENT (`mood`, `drama`, `pace`), never by implementation
+  (`blurRadius`). Every knob must visibly change the output — a dead knob is
+  worse than no knob.
+
+Ship Looks via `config.presets` — named param-value sets (2–3 when the
+program has 4+ params):
+
+```json
+"presets": [{ "name": "Vivid", "values": { "hue": 0.9, "speed": 2 } },
+            { "name": "Calm",  "values": { "hue": 0.3, "speed": 0.6 } }]
+```
+
+Values must reference declared param keys with matching types.
+
+## Server-render caution
+
+Configs pushed to vos.so get preview-rendered on a software-GL fleet: no
+`THREE.DoubleSide` on transmission materials (hard hang), no `dispersion`
+(too slow), and any fetched asset must be reachable and CORS-open. These are
+fine for purely local renders on a real GPU.
+
+## Design principles
+
+- **Visual impact**: bloom for glow (even 0.3–0.5 elevates); emissive
+  materials + bloom = light emitters; exp2 fog (0.01–0.05) for depth; dark
+  backgrounds make colors pop; glass (transmission + HDR env) reads premium;
+  subtle camera drift adds life.
+- **Animation quality**: 4–10s loops, 10–30s narratives; `ease: 'none'` for
+  constant motion; `power2.inOut`/`sine.inOut` for transitions; stagger for
+  sequential reveals; layer tweens at different start times.
+- **Color**: 2–3 complementary colors max; warm key + cool rim; dark tones
+  (`0x0a0a1a`, `0x1a1a2e`) for backgrounds.
+- **Performance**: `InstancedMesh` for 10+ identical objects; 5k–20k Points,
+  100–500 InstancedMesh; dispose everything.
+
+## Category selection guide
+
+| Concept | Camera | Technique |
+|---------|--------|-----------|
+| Shader art / fractals | `fullscreen` | ShaderMaterial + uniform tweens |
+| 3D objects | `perspective` | Mesh + Material + lights |
+| Isometric/flat | `orthographic` | InstancedMesh + computed positions |
+| Text showcase | `perspective` or `fullscreen` | TextGeometry (3D) or elements (2D) |
+| Glass/refraction | `perspective` | MeshPhysicalMaterial + HDR env map |
+| Particles | `perspective` | Points + shader or InstancedMesh |
+| Mixed media | `perspective` | 3D scene + elements array |