@vosjs/cli 0.65.0 → 0.65.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vosjs/cli",
-  "version": "0.65.0",
+  "version": "0.65.1",
   "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",
@@ -52,12 +52,12 @@
     "mediabunny": "^1.55.7",
     "playwright": "^1.49.0",
     "@vosjs/core": "^0.27.0",
-    "@vosjs/editor": "^1.4.0",
     "@vosjs/elements": "^0.10.2",
+    "@vosjs/studio-core": "^0.35.3",
     "@vosjs/render-core": "^0.3.17",
-    "@vosjs/shared": "^0.7.0",
+    "@vosjs/editor": "^1.4.0",
     "@vosjs/timeline": "^0.5.0",
-    "@vosjs/studio-core": "^0.35.3",
+    "@vosjs/shared": "^0.7.0",
     "@vosjs/tween": "^0.8.3"
   },
   "devDependencies": {

package/skills/VERSION

@@ -1 +1 @@
-0.20.1
+0.21.0

package/skills/vos-authoring/SKILL.md

@@ -159,6 +159,9 @@ documents a `ctx.data` key the program reads:
 ```
 
 - kinds: `number` (min/max/step) | `color` | `select` (options) | `toggle`
+  | `text` | `font` | `asset` (a FILE knob: its `key` is a name in
+  `config.assets`, it has no `default`, and the person swaps the declared
+  file from the editor; see the vos-remix skill's `params-knobs.md`)
 - `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`

package/skills/vos-authoring/references/schema-reference.md

@@ -268,7 +268,7 @@ A file the program uses (a picture, a video, a model, a font file) is named in `
 
 **Never type a file's URL or path inside a function string.** It renders on your machine and then fails where it matters: a server render of a private vos cannot fetch it, and a remix does not bring it along. `vos check` reports a `"$assets.<name>"` that names nothing, a declared path that is not a file, and a hosted file typed in code.
 
-A file a knob swaps (a `modelUrl` text param) is the one exception: it lives in `data` as a URL, because a person changes it.
+A file a person should be able to swap is still declared here, with a FILE KNOB over its name: `"params": [{ "key": "cover", "label": "Cover", "kind": "asset" }]` (`@vosjs/cli` 0.65 or later). The knob's value is the declared file's `ref`, so it has no `default` and nothing in `data`; `accept` lists the kinds it takes and defaults to the file's own `kind`. Older programs spell this as a text knob holding a URL in `data` (a `modelUrl` param); that still plays, but write new ones with a file knob.
 
 ---
 

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.5, @vosjs/elements 0.10.0, @vosjs/timeline 0.4.1 and @vosjs/shared 0.6.0. Do not edit by hand: re-run the script. -->
+<!-- Generated by scripts/build-element-reference.mjs from @vosjs/core 0.27.0, @vosjs/elements 0.10.2, @vosjs/timeline 0.5.0 and @vosjs/shared 0.7.0. Do not edit by hand: re-run the script. -->
 
 # Elements, the context and eases: the declarations
 
@@ -46,6 +46,16 @@ interface VosConfigJson {
      * Total duration of one animation cycle in seconds.
      */
     duration: number;
+    /**
+     * The canvas the program is designed for, in pixels. Its ratio is the
+     * program's aspect (any shape: 1080x1920, 1080x1080, 2560x1080); its pixels
+     * are the default output size of a render or still. Absent, a host picks
+     * (16:9 by convention). Design units stay 1080-high at every size.
+     */
+    size?: {
+        width: number;
+        height: number;
+    };
     /** Scene configuration (background, fog) */
     scene?: SceneConfig;
     /** Camera configuration */
@@ -77,6 +87,25 @@ interface VosConfigJson {
      * @example { cursor: [{ t: 0, x: 10, y: 20, type: 'down' }] }
      */
     data?: Record<string, unknown>;
+    /**
+     * The files this program uses, declared by name: its manifest.
+     *
+     * A program reads `ctx.assets.<name>` and gets a URL (or an array of
+     * them) that the HOST resolved for the surface it is running on. An
+     * element, object or font may name one as the string `"$assets.<name>"`
+     * (or `"$assets.<name>[2]"`), which is replaced the same way.
+     *
+     * Declaring a file here instead of typing its URL inside a function is
+     * what lets a host see it: it can serve a private file to a render page,
+     * bring it along when the program is copied, and refuse to collect it
+     * while the program still plays.
+     *
+     * A `ref` is whatever the host understands: a URL or path is used as it
+     * is; any other scheme is mapped by the compile option `resolveAssetRef`
+     * and, per surface, by `deps.assets`.
+     * @example { logo: { ref: './logo.png', kind: 'image' } }
+     */
+    assets?: Record<string, AssetDecl>;
     /**
      * Async setup hook as a string.
      * @example "(ctx) => { const loader = new ctx.loaders.FontLoader(); ... }"
@@ -434,8 +463,13 @@ interface ElementProps {
 interface ElementInstance {
     /** Original configuration */
     config: ElementConfig;
-    /** Three.js mesh (textured plane) */
+    /** Three.js mesh (textured plane); a split text's FIRST unit only */
     mesh: THREE.Mesh;
+    /**
+     * Every mesh the element draws (a split text's units), for picking and
+     * the editor's box. Absent on instances from @vosjs/elements < 0.10.1.
+     */
+    meshes?: () => THREE.Mesh[];
     /** DOM node for SplitText (text elements only) - typed as unknown for portability */
     node: unknown;
     /** GSAP-animatable properties */
@@ -477,7 +511,8 @@ interface ElementInstance {
 
 ## Knobs (`config.params` and `config.presets`)
 
-A knob is a `ParamSpec` over one top-level `data` key, and a Look a named
+A knob is a `ParamSpec` over one top-level `data` key (a file knob, kind
+`asset`, is over a name in `assets` instead), 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
@@ -501,9 +536,22 @@ line; a list of elements is one key per element.
  * validated params at the storage boundary (the platform's server-side copy;
  * change both together) and
  * this module validates defensively.
+ *
+ * ONE kind is not a `ctx.data` key. An `asset` knob swaps a FILE, and a
+ * program's files live in `config.assets`, declared by name and read as
+ * `ctx.assets.<name>` or `"$assets.<name>"`. So an asset knob's `key` is a
+ * manifest name, its value is that entry's `ref`, and a commit writes the
+ * manifest, never `data`. That is what lets a swapped file get everything
+ * a declared file gets (a local path served by the CLI, uploaded by a push,
+ * resolved for every surface) instead of being a URL typed into data that
+ * nothing downstream knows is a file.
  */
 type ParamValue = number | string | boolean;
 
+const ASSET_PARAM_KINDS: readonly ["image", "video", "audio", "model", "font", "hdr"];
+
+type AssetParamKind = (typeof ASSET_PARAM_KINDS)[number];
+
 interface ParamSpec {
     /** The ctx.data key the program reads. */
     key: string;
@@ -517,7 +565,13 @@ interface ParamSpec {
     group?: string;
     /** Sort order within a group (falls back to declaration order). */
     order?: number;
-    kind: 'number' | 'color' | 'select' | 'toggle' | 'text' | 'font';
+    kind: 'number' | 'color' | 'select' | 'toggle' | 'text' | 'font' | 'asset';
+    /**
+     * asset kind: the kinds of file the knob takes (a picker offers only
+     * these). Absent = the declared file's own `kind` hint, and when that is
+     * absent too, any file.
+     */
+    accept?: AssetParamKind[];
     /** number kind */
     min?: number;
     max?: number;

package/skills/vos-remix/references/3d-recipe.md

@@ -18,7 +18,9 @@ Reveal: https://vos.so/gallery?tag=3d) are built to take a model swap.
      POINT** in these programs — with the loaded `setupData.model`,
      bbox-normalized to ~1.7 units and grounded at `y = 0` (the templates
      ship the normalization snippet; keep it so `scale` knobs stay
-     model-independent).
+     model-independent). To let the person swap the model later from the
+     editor, add a file knob over it (`params-knobs.md`, File knobs):
+     `{ "key": "product", "label": "Model", "kind": "asset" }`.
    - Or keep the template's own product and only retune params.
 3. **Never type the model's URL or path inside a function string.**
    `vos render` and `vos preview` serve the declared file to the page;

package/skills/vos-remix/references/params-knobs.md

@@ -17,6 +17,7 @@ just an artifact.**
 ```
 
 - kinds: `number` (min/max/step) | `color` | `select` (options) | `toggle`
+  | `text` | `font` | `asset` (a file knob, below)
 - `hint`: ONE sentence on what visibly changes — always write it
 - `unit` shows inside the number field (`px` `%` `s` `×` `°`);
   `group`/`order` cluster related knobs into their own panel card
@@ -38,6 +39,41 @@ Values must reference declared param keys with matching types (anything
 else is dropped on save; max 8 Looks, names ≤24 chars). Ship 2–3 Looks
 whenever the program has 4+ params.
 
+## File knobs
+
+A file a person should be able to swap (the logo, the product shot, the
+model) is a knob of kind `asset` over a DECLARED file. Its `key` is the
+file's name in `config.assets`; it has no `default` and nothing in `data`,
+because its value is that file's `ref`. Needs `@vosjs/cli` 0.65 or later.
+
+```json
+"assets": { "logo": { "ref": "./logo.png", "kind": "image" } },
+"params": [{ "key": "logo", "label": "Logo", "kind": "asset",
+             "hint": "The mark in the corner" }]
+```
+
+- The program reads it like any declared file: `ctx.assets.logo`, or
+  `"src": "$assets.logo"` on an element. No `onFrame` read is needed: a
+  swap recompiles the program once, it is never a live data edit.
+- `accept` lists the kinds it takes (`image`, `video`, `audio`, `model`,
+  `font`, `hdr`), e.g. `"accept": ["image", "video"]`. Without it the knob
+  takes the declared file's own `kind`, so write `kind` on the file.
+- One knob, one file: a name declared as a list cannot be a file knob.
+- In the editor the person sees the file with a **Replace** control and
+  picks from their own files or their device. The swap rewrites the
+  manifest entry, so the new file is declared like the old one: `vos push`
+  uploads it, and a server render of a private vos can fetch it.
+- To swap it yourself, change the file's `ref` in `assets` and push. A
+  Look can swap it too: `"values": { "logo": "asset:<id>" }`.
+- `vos check` warns when a file knob would do nothing: the name is not
+  declared, it is a list, nothing reads `ctx.assets.<name>`, or no kind is
+  said anywhere.
+
+A `text` knob holding a URL in `data` (a `modelUrl` param) is the older
+spelling. It still plays, but the person gets a box to paste an address
+into, and `vos push` does not upload a local file named there. Write new
+programs with a file knob.
+
 ## The five rules
 
 1. **The knob budget is a negotiation, not an accumulation.** Curate 2–4