@viji-dev/core 0.19.0 → 0.21.0

package/dist/index.d.ts

@@ -1136,6 +1136,9 @@ declare interface ImageParameter {
     category: ParameterCategory;
 }
 
+/** Value type of one `initialParameters` entry: a parameter value, or a {@link ModelSeed} for model parameters. */
+export declare type InitialParameterValue = ParameterValue | ModelSeed;
+
 /**
  * Runtime-enumerable identifiers for the **input / interaction** capabilities
  * tracked live per rendered frame. This is the live capability vocabulary — the
@@ -1144,7 +1147,10 @@ declare interface ImageParameter {
  *
  * Note: `parameters` is intentionally absent. It is a *declared-only* tag on
  * {@link SceneCapabilities} (the scene defines tunable parameters), not a live
- * consumed signal, so it is not part of the per-frame capability set.
+ * consumed signal, so it is not part of the per-frame capability set. The
+ * nested `cv` and `sources` members of {@link SceneCapabilities} are likewise
+ * outside this vocabulary (`cv` has its own, {@link CV_FEATURE_KEYS}; `sources`
+ * is declared-only).
  */
 export declare const INPUT_CAPABILITY_KEYS: readonly ["audio", "video", "mouse", "keyboard", "pointer", "touch", "sensors", "devices"];
 
@@ -1225,6 +1231,158 @@ export declare interface MinAvgMax {
     max: number;
 }
 
+/**
+ * The 3D model formats a `viji.model()` parameter accepts, with the file
+ * extension (dot included) and the canonical MIME type the Viji backend
+ * stores and serves for each. Cross-repo contract: the client builds its
+ * picker `accept` list and MIME canonicalization from this table, the
+ * backend keeps an equal literal and asserts equality in its tests.
+ *
+ * Multi-file formats (`.gltf` with external buffers and textures) are
+ * deliberately absent: one asset is one file.
+ */
+export declare const MODEL_FORMATS: ReadonlyArray<ModelFormatInfo>;
+
+/**
+ * Configuration object passed to `viji.model()`. The host renders a file
+ * picker for 3D model files; the user-supplied file becomes available as a
+ * {@link ModelValue} (bytes plus a blob URL) that your own loader parses.
+ */
+declare interface ModelConfig {
+    /**
+     * Advanced: explicit parameter identity. Normally you do NOT set this —
+     * the parameter's name is inferred from the variable or object key you
+     * assign it to (`const statue = viji.model(...)` → `statue`). Set `name`
+     * only for parameters not assigned to a variable or key (created in an
+     * array, loop, or factory). Must be a valid identifier and scene-globally
+     * unique. When set, it overrides the inferred name.
+     */
+    name?: string;
+    /** Display name shown next to the file picker in the parameter UI. Optional — defaults to the parameter's name. */
+    label?: string;
+    /** Optional tooltip / help text shown next to the control. */
+    description?: string;
+    /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
+    group?: string;
+    /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
+    category?: ParameterCategory;
+    /**
+     * Required: the formats your scene can parse, for example `['glb']` for a
+     * three.js `GLTFLoader` scene or `['obj', 'stl']` for p5 `loadModel()`.
+     * The host filters its picker by this list and core rejects files of other
+     * formats before the scene sees them. Must not be empty; list only what
+     * your loader handles.
+     */
+    formats: ModelFormat[];
+}
+
+/**
+ * Host-side value of a 3D model parameter: what parameter listeners,
+ * `getParameter()` and `getParameterValues()` deliver once a model is set.
+ * A frozen plain object carrying the format tag only; core keeps no copy of
+ * the bytes on the host (they are transferred to the scene). Hosts that need
+ * to tell it apart from other object values check the parameter's declared
+ * type (`'model'`) or the presence of a string `format`.
+ */
+export declare interface ModelDescriptor {
+    /** Format tag of the model the scene currently holds. */
+    readonly format: ModelFormat;
+}
+
+/**
+ * `VijiCoreError.code` values a model parameter can raise:
+ * `MODEL_FORMAT_UNKNOWN` (the file is not a supported model),
+ * `MODEL_FORMAT_NOT_ALLOWED` (the parameter's `formats` exclude it),
+ * `MODEL_LOAD_ERROR` (reading or fetching the input failed).
+ */
+export declare type ModelErrorCode = 'MODEL_FORMAT_UNKNOWN' | 'MODEL_FORMAT_NOT_ALLOWED' | 'MODEL_LOAD_ERROR';
+
+/**
+ * Format tag of a 3D model file. One tag per supported file type; the
+ * extension and canonical MIME type of each live in `MODEL_FORMATS`.
+ */
+export declare type ModelFormat = 'glb' | 'obj' | 'stl' | 'ply' | 'las' | 'laz' | 'splat';
+
+/** One row of `MODEL_FORMATS`: a format tag with its file extension and canonical MIME type. */
+export declare interface ModelFormatInfo {
+    /** Format tag used by `viji.model()` and the `format` field of a model value. */
+    readonly format: ModelFormat;
+    /** File extension including the dot, lower case (for picker `accept` lists). */
+    readonly extension: string;
+    /** Canonical MIME type the Viji backend stores and serves for this format. */
+    readonly mime: string;
+}
+
+/**
+ * What `setParameter` accepts for a model parameter: a `File` or `Blob`
+ * (read on the host), a bare `ArrayBuffer` or a {@link ModelSeed} (the
+ * buffer is TRANSFERRED to the scene and becomes unusable on the host), a
+ * URL string (fetched without credentials), or `null` to clear.
+ */
+export declare type ModelInput = File | Blob | ArrayBuffer | ModelSeed | string | null;
+
+/**
+ * Reactive object returned by `viji.model()`. `value` is `null` until the user
+ * provides a 3D model file.
+ */
+declare interface ModelParameter {
+    /** The current model as a {@link ModelValue}, or `null` until the user provides one. */
+    value: ModelValue | null;
+    /** Formats this parameter accepts (the `formats` you passed). */
+    readonly formats: ReadonlyArray<ModelFormat>;
+    /** Display name shown next to the upload field in the parameter UI. */
+    label?: string;
+    /** Tooltip / help text for the control (empty string when not configured). */
+    description?: string;
+    /** Group name under which the control appears in the UI. */
+    group: string;
+    /** Visibility category that controls when the parameter is shown. */
+    category: ParameterCategory;
+}
+
+/**
+ * What `initialParameters` accepts for a model parameter. Structured-cloned
+ * to the scene (your buffer stays usable). `format` is preferred (a host
+ * that stores assets knows it from the MIME type); when omitted, the format
+ * is sniffed from the bytes with `name` as the extension hint.
+ */
+export declare interface ModelSeed {
+    /** The whole model file. Must be an `ArrayBuffer` (not a view, not shared) with at least one byte. */
+    bytes: ArrayBuffer;
+    /** Format tag. Sniffed from `bytes` when omitted. */
+    format?: ModelFormat | undefined;
+    /** File name or URL, used only as an extension hint for the sniff; never stored. */
+    name?: string | undefined;
+}
+
+/**
+ * The model a `viji.model()` parameter currently holds: the file as bytes plus
+ * a lazily created blob URL, tagged with its format. Core never parses the
+ * file; pass `bytes` to a loader's `parse()` or `url` to its `load()`.
+ *
+ * Read `value` where you parse it. When the host replaces or clears the
+ * model, core drops the bytes and revokes `url`; geometry you already built
+ * from them stays valid, but a URL taken from the replaced value rejects
+ * when loaded afterwards.
+ */
+declare interface ModelValue {
+    /** Format tag of the file, resolved by the host before transfer. */
+    readonly format: ModelFormat;
+    /**
+     * The whole file, transferred from the host without a copy. `byteLength`
+     * is the file size. Some loaders transfer the buffer to their own worker
+     * and detach it; pass `bytes.slice(0)` to those, or disable their worker.
+     */
+    readonly bytes: ArrayBuffer;
+    /**
+     * Blob URL for loaders that take a URL (three.js `.load()`, p5 `loadModel()`).
+     * Created on first read (a Blob copies the bytes, so it is never built
+     * eagerly), cached, and revoked when the host replaces or clears the model.
+     * Reading it on a value the host already replaced throws.
+     */
+    readonly url: string;
+}
+
 /**
  * Mouse input state for the current frame: position, individual button states,
  * per-frame movement, scroll wheel, and frame-based press / release events.
@@ -1392,6 +1550,12 @@ export declare interface ParameterConfig {
      */
     step?: number;
     options?: string[] | number[];
+    /**
+     * For model type: the formats the scene can parse (required by
+     * `viji.model()`, so always present on model definitions). Hosts filter
+     * their pickers by it; core rejects files of other formats at set time.
+     */
+    formats?: ModelFormat[] | undefined;
     maxLength?: number;
     /**
      * For color and gradient types: the value carries a transparency channel
@@ -1444,9 +1608,9 @@ export declare interface ParameterGroup {
  * The kind of UI control a parameter renders as. Used for the per-type
  * breakdown in {@link SceneData.parameterCounts}.
  */
-export declare type ParameterType = 'slider' | 'color' | 'toggle' | 'select' | 'text' | 'number' | 'image' | 'button' | 'coordinate' | 'gradient';
+export declare type ParameterType = 'slider' | 'color' | 'toggle' | 'select' | 'text' | 'number' | 'image' | 'button' | 'coordinate' | 'gradient' | 'model';
 
-export declare type ParameterValue = string | number | boolean | ImageBitmap | CoordinateValue | GradientValue | null;
+export declare type ParameterValue = string | number | boolean | ImageBitmap | CoordinateValue | GradientValue | ModelDescriptor | null;
 
 export declare interface PerformanceStats {
     resolution: Resolution;
@@ -1629,7 +1793,8 @@ export declare interface SceneAnalysisData {
  *
  * The input keys here are pinned to {@link INPUT_CAPABILITY_KEYS} and the `cv`
  * keys to {@link CV_FEATURE_KEYS} by a compile-time guard (below), so this shape
- * cannot drift from the runtime vocabulary.
+ * cannot drift from the runtime vocabulary. `parameters`, `cv`, and `sources`
+ * are the declared-only members outside the per-frame input vocabulary.
  */
 export declare interface SceneCapabilities {
     /** Scene reads audio analysis (volume, bands, beat, FFT/waveform, or audio streams). */
@@ -1665,6 +1830,67 @@ export declare interface SceneCapabilities {
         /** Scene uses body segmentation. */
         segmentation: boolean;
     };
+    /**
+     * Which input **source** each capability reads, for host routing UIs (e.g. a
+     * controller deciding whether a phone camera belongs in the main slot or a
+     * device slot). Declared-only (static analysis, like the flags above) and
+     * inclusive-biased; not part of the per-frame {@link INPUT_CAPABILITY_KEYS}
+     * vocabulary (same standing as `parameters` and `cv`).
+     *
+     * - `main`: the host's primary stream, index 0 (`viji.video` / `viji.audio`,
+     *   `u_video*` / `u_audio*`).
+     * - `streams`: host-side additional compositor inputs, indices 1-99
+     *   (`viji.videoStreams` / `viji.audioStreams`, `u_videoStream*` /
+     *   `u_audioStream*`). Not routable from a controller; they set neither
+     *   `main` nor `device`.
+     * - `device`: an external device slot, indices 100+ (`viji.devices[i].video`
+     *   / `.audio` / `.motion` / `.orientation`, `u_device{i}*`, `u_deviceCount`,
+     *   `u_externalDeviceCount`).
+     *
+     * Native/p5 scenes reach device members through a `.video` / `.audio` /
+     * `.motion` / `.orientation` token after `viji.devices`. When a scene
+     * references `viji.devices` but no such token is visible (destructuring,
+     * `viji.devices.length`), all three `device` booleans report `true`: the
+     * analyzer never hides a source a scene may use.
+     */
+    sources: {
+        /** Video image source. */
+        video: {
+            /**
+             * Main camera. Shader scenes also report `true` when any `cv.*` flag is
+             * set (CV runs on the main stream only; no device-CV uniforms exist).
+             * Native/p5 CV `enable*` calls do NOT imply this: device cameras expose
+             * the same CV surface (`viji.devices[i].video.cv`).
+             */
+            main: boolean;
+            /** Additional compositor video streams (`viji.videoStreams`, `u_videoStream*`). */
+            streams: boolean;
+            /** External device cameras (`viji.devices[i].video`, `u_device{i}`, `u_deviceCount`). */
+            device: boolean;
+        };
+        /** Audio analysis source. */
+        audio: {
+            /** Main microphone / audio input (`viji.audio`, `u_audio*`). */
+            main: boolean;
+            /** Additional compositor audio streams (`viji.audioStreams`, `u_audioStream*`). */
+            streams: boolean;
+            /**
+             * External device audio (`viji.devices[i].audio`). Always `false` for
+             * shader scenes: no device-audio uniform family exists.
+             */
+            device: boolean;
+        };
+        /** Motion / orientation sensor source. */
+        sensors: {
+            /** The host machine's own sensors (`viji.device`, `u_deviceAcceleration` and family). */
+            internal: boolean;
+            /**
+             * External device sensors (`viji.devices[i].motion` / `.orientation`,
+             * `u_device{i}Acceleration` and family, `u_externalDeviceCount`).
+             */
+            device: boolean;
+        };
+    };
 }
 
 /**
@@ -2458,7 +2684,7 @@ declare interface TouchPoint {
 /** Returned by `on*` listener registration calls; invoke to unsubscribe. */
 export declare type Unsubscribe = () => void;
 
-export declare const VERSION = "0.19.0";
+export declare const VERSION = "0.21.0";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2759,6 +2985,20 @@ export declare interface VijiAPI {
      * if (tex.value) ctx.drawImage(tex.value, 0, 0, viji.width, viji.height);
      */
     image: (defaultValue: null, config: ImageConfig) => ImageParameter;
+    /**
+     * Declares a 3D model parameter. `formats` is required: list only the formats
+     * your loader parses, so the host picker offers nothing the scene cannot show.
+     * The user-supplied file becomes available as `value` (a `ModelValue` with
+     * `bytes`, `url` and `format`); parse it with your own loader (three.js loaders,
+     * p5 `loadModel()`, loaders.gl). Core never parses the file. Must be called at
+     * the top level of the scene, never inside `render()`.
+     *
+     * @example
+     * const statue = viji.model(null, { label: 'Statue', formats: ['glb'] });
+     * // later, when statue.value changes:
+     * loader.parse(statue.value.bytes, '', (gltf) => scene.add(gltf.scene));
+     */
+    model: (defaultValue: null, config: ModelConfig) => ModelParameter;
     /**
      * Declares a momentary button parameter. `value` is `true` for one frame after
      * the user clicks, then auto-resets. Perfect for triggering discrete events.
@@ -2874,9 +3114,12 @@ export declare class VijiCore {
     private config;
     /**
      * `config.initialParameters` after `sanitizeInitialParameters` (set in
-     * `initialize()`, cleared in `destroy()`). Overlaid onto `parameterValues`
+     * `initialize()`, released at the end of `handleParametersDefined`, its
+     * only consumer, and in `destroy()`). Overlaid onto `parameterValues`
      * when the worker reports its definitions, so the host table matches what
      * the worker seeded before frame 1. `null` when no seed was supplied.
+     * Released after define so model seed buffers (up to tens of MB) do not
+     * stay reachable from the host for the core's lifetime.
      */
     private initialSeed;
     private isHeadless;
@@ -3086,10 +3329,20 @@ export declare class VijiCore {
      */
     private normalizeParameterInput;
     /**
-     * Set a single parameter value
-     * Handles all parameter types including images intelligently
-     */
-    setParameter(name: string, value: ParameterValue | ColorInput | GradientInput | File | Blob): Promise<void>;
+     * Set a single parameter value.
+     * Handles all parameter types including images and 3D models.
+     *
+     * Model parameters accept a {@link ModelInput}: a `File` or `Blob` (read
+     * here), a URL string (fetched without credentials), a bare `ArrayBuffer`
+     * or a `ModelSeed`, or `null` to clear. A buffer you pass is TRANSFERRED to
+     * the scene and is unusable afterwards; when one model feeds several cores
+     * (VJ decks), pass a `File` / `Blob` or re-read the bytes per core. Core
+     * keeps no copy of the bytes: listeners and `getParameter()` receive a
+     * `ModelDescriptor` (`{ format }`). Rejects with `MODEL_FORMAT_UNKNOWN` when the file
+     * is not a supported model, `MODEL_FORMAT_NOT_ALLOWED` when the parameter's
+     * `formats` exclude it, and `MODEL_LOAD_ERROR` when reading or fetching fails.
+     */
+    setParameter(name: string, value: ParameterValue | ColorInput | GradientInput | File | Blob | ModelInput): Promise<void>;
     /**
      * Internal method to handle image parameter loading and transfer
      * Loads the image on the host side and creates TWO ImageBitmaps:
@@ -3097,13 +3350,26 @@ export declare class VijiCore {
      * - One to transfer to the worker
      */
     private handleImageParameter;
+    /**
+     * Internal: resolve, validate and transfer a 3D model parameter value.
+     *
+     * Order (security review S12): resolve the bytes, validate format and
+     * allowlist, then post inside try/catch, and only after a successful post
+     * commit the host table and notify listeners. Format errors are thrown
+     * BEFORE the I/O try so they keep their own codes; only read / fetch
+     * failures become `MODEL_LOAD_ERROR`. The host keeps the descriptor only.
+     */
+    private handleModelParameter;
     /**
      * Set multiple parameter values efficiently.
      *
      * For color parameters, accepts the same rich input forms as `setParameter`
      * (hex, RGB/HSB objects, CSS / GLSL strings); they are normalized to canonical hex.
+     * Model parameters accept the same {@link ModelInput} forms as `setParameter`;
+     * each model entry is resolved and transferred individually (in order) before
+     * the remaining values are sent as one batch.
      */
-    setParameters(values: Record<string, ParameterValue | ColorInput | GradientInput>): Promise<void>;
+    setParameters(values: Record<string, ParameterValue | ColorInput | GradientInput | ModelInput>): Promise<void>;
     /**
      * Get current parameter value
      */
@@ -4066,8 +4332,18 @@ export declare interface VijiCoreConfig {
      * closed is dropped from the seed with a console warning. URL strings are
      * not resolved and `File` / `Blob` values are not seedable; use
      * {@link VijiCore.setParameter} after `onParametersDefined` for those.
-     */
-    initialParameters?: Record<string, ParameterValue>;
+     *
+     * Model parameters accept a {@link ModelSeed} (`{ bytes, format? }`). The
+     * buffer is structured-cloned to the scene (one copy; your buffer stays
+     * usable and may be shared between keys), core keeps none of it after the
+     * scene reports its parameters, and the host table shows a
+     * {@link ModelDescriptor}. Seeds whose bytes are empty, detached, or
+     * not an `ArrayBuffer`, or whose format cannot be resolved, are dropped
+     * with a warning. The whole seed rides one message with a 5 second budget:
+     * keep model seeds small (total under 64 MB) and set large models with
+     * `setParameter` after `onParametersDefined` instead.
+     */
+    initialParameters?: Record<string, InitialParameterValue>;
     /** Frame rate mode - render every frame (`'full'`), every 2nd (`'half'`), every 4th (`'quarter'`), or every 8th (`'eighth'`). */
     frameRateMode?: FrameRateMode;
     /** Resolution: scale (number) or explicit dimensions (object). Required for headless, must be object form */

package/dist/index.js

@@ -1,8 +1,9 @@
-import { C as E, I as o, V as s, a as C, b as I } from "./index-PgPvRJ2p.js";
-export {
-  E as CV_FEATURE_KEYS,
-  o as INPUT_CAPABILITY_KEYS,
-  s as VERSION,
-  C as VijiCore,
-  I as VijiCoreError
-};
+import { C as E, I as s, M as o, V as C, a as I, b as V } from "./index-C9OHLFGB.js";
+export {
+  E as CV_FEATURE_KEYS,
+  s as INPUT_CAPABILITY_KEYS,
+  o as MODEL_FORMATS,
+  C as VERSION,
+  I as VijiCore,
+  V as VijiCoreError
+};

package/dist/param-inference.js

@@ -3100,6 +3100,7 @@ const ai = /* @__PURE__ */ new Set([
   "number",
   "text",
   "image",
+  "model",
   "button",
   "coordinate",
   "gradient"

package/dist/{scene-analysis-2Ov0HS52.js → scene-analysis-C7cAsqhv.js}

@@ -1,4 +1,4 @@
-class a {
+class u {
   /**
    * Detects the renderer type from scene code comments
    * 
@@ -39,6 +39,15 @@ class a {
    * - Shader scenes: matched against built-in `u_*` uniform usage (exact).
    * - Native / p5 scenes: matched against `viji.*` usage tokens.
    *
+   * The top-level flags are the per-frame cohort vocabulary
+   * (`INPUT_CAPABILITY_KEYS`) and are persisted downstream; their rules do
+   * not change. `sources` (0.20.0) is a declared-only refinement on top:
+   * per input kind, whether the scene reads the main stream, the additional
+   * compositor streams, or an external device slot. Same inclusive bias; a
+   * native/p5 scene that references `viji.devices` without a visible member
+   * token reports every `device` source as used. Shader scenes never report
+   * `audio.device` (no device-audio uniform family exists).
+   *
    * @param sceneCode - The artist's scene code to analyze
    * @param renderer - The renderer type (from {@link detectRendererType})
    * @returns The set of capabilities the scene declares it uses
@@ -61,9 +70,14 @@ class a {
         handTracking: !1,
         poseDetection: !1,
         segmentation: !1
+      },
+      sources: {
+        video: { main: !1, streams: !1, device: !1 },
+        audio: { main: !1, streams: !1, device: !1 },
+        sensors: { internal: !1, device: !1 }
       }
     };
-    return t === "shader" ? this.detectShaderCapabilities(i, s) : this.detectScriptCapabilities(i, s), s;
+    return t === "shader" ? (this.detectShaderCapabilities(i, s), this.detectShaderSources(i, s)) : (this.detectScriptCapabilities(i, s), this.detectScriptSources(i, s)), s;
   }
   /**
    * Replaces comment spans and string/template literals with whitespace via a
@@ -77,25 +91,25 @@ class a {
     const i = e.length;
     let s = 0;
     for (; s < i; ) {
-      const r = e[s], o = s + 1 < i ? e[s + 1] : "";
-      if (r === "/" && o === "/") {
+      const r = e[s], a = s + 1 < i ? e[s + 1] : "";
+      if (r === "/" && a === "/") {
         for (s += 2; s < i && e[s] !== `
 `; ) s++;
         continue;
       }
-      if (r === "/" && o === "*") {
+      if (r === "/" && a === "*") {
         for (s += 2; s < i && !(e[s] === "*" && e[s + 1] === "/"); ) s++;
         s += 2, t += " ";
         continue;
       }
       if (r === '"' || r === "'" || r === "`") {
-        const u = r;
+        const o = r;
         for (s++; s < i; ) {
           if (e[s] === "\\") {
             s += 2;
             continue;
           }
-          if (e[s] === u) {
+          if (e[s] === o) {
             s++;
             break;
           }
@@ -115,6 +129,9 @@ class a {
    * (`u_device0`, `u_device0Resolution/Connected`) map to video+devices,
    * sensor uniforms (`u_device0Acceleration`, …) map to sensors+devices, and
    * the internal-device sensors (`u_deviceAcceleration`, …) map to sensors.
+   *
+   * These flag rules are the persisted cohort vocabulary and must not change;
+   * per-source refinement lives in {@link detectShaderSources}, run afterwards.
    */
   static detectShaderCapabilities(e, t) {
     /\bu_audio\w*/.test(e) && (t.audio = !0), /\bu_video\w*/.test(e) && (t.video = !0), /\bu_mouse\w*/.test(e) && (t.mouse = !0), /\bu_key\w*/.test(e) && (t.keyboard = !0), /\bu_touch\w*/.test(e) && (t.touch = !0), /\bu_pointer\w*/.test(e) && (t.pointer = !0), /\bu_device(Acceleration|AccelerationGravity|RotationRate|OrientationAbsolute|Orientation)\b/.test(e) && (t.sensors = !0), /\bu_device[0-7](AccelerationGravity|Acceleration|RotationRate|Orientation)\b/.test(e) && (t.sensors = !0, t.devices = !0), /\bu_externalDeviceCount\b/.test(e) && (t.devices = !0, t.sensors = !0), (/\bu_deviceCount\b/.test(e) || /\bu_device[0-7](Resolution|Connected)?\b/.test(e)) && (t.video = !0, t.devices = !0), /\bu_face\w*/.test(e) && (t.cv.faceDetection = !0), /\bu_face0(Neutral|Happy|Sad|Angry|Surprised|Disgusted|Fearful)\b/.test(e) && (t.cv.emotion = !0), (/\bu_face0HeadPose\b/.test(e) || /\bu_videoAnalysed\w*/.test(e) || /\bu_face0(Brow|Cheek|Eye|Jaw|Mouth|Nose|Tongue)\w*/.test(e)) && (t.cv.faceMesh = !0), (/\bu_handCount\b/.test(e) || /\bu_(left|right)Hand\w*/.test(e)) && (t.cv.handTracking = !0), (/\bu_pose\w*/.test(e) || /\bu_(nose|leftShoulder|rightShoulder|leftElbow|rightElbow|leftWrist|rightWrist|leftHip|rightHip|leftKnee|rightKnee|leftAnkle|rightAnkle)Position\b/.test(e)) && (t.cv.poseDetection = !0), /\bu_segmentation\w*/.test(e) && (t.cv.segmentation = !0);
@@ -123,21 +140,54 @@ class a {
    * Native / p5 capability detection from `viji.*` usage tokens. CV features
    * are keyed on their canonical `enable*` method names (the canonical
    * signal — a scene must enable a feature to receive its data).
+   *
+   * These flag rules are the persisted cohort vocabulary and must not change;
+   * per-source refinement lives in {@link detectScriptSources}, run afterwards.
    */
   static detectScriptCapabilities(e, t) {
-    /\bviji\.audio/.test(e) && (t.audio = !0), /\bviji\.video/.test(e) && (t.video = !0), /\bviji\.mouse/.test(e) && (t.mouse = !0), /\bviji\.keyboard/.test(e) && (t.keyboard = !0), /\bviji\.touches/.test(e) && (t.touch = !0), /\bviji\.pointer/.test(e) && (t.pointer = !0), /\bviji\.device\b/.test(e) && (t.sensors = !0), /\bviji\.devices/.test(e) && (t.devices = !0), /\bviji\.(slider|color|toggle|select|text|number|image|button|coordinate|gradient)\s*\(/.test(e) && (t.parameters = !0), /\benableFaceDetection\b/.test(e) && (t.cv.faceDetection = !0), /\benableFaceMesh\b/.test(e) && (t.cv.faceMesh = !0), /\benableEmotionDetection\b/.test(e) && (t.cv.emotion = !0), /\benableHandTracking\b/.test(e) && (t.cv.handTracking = !0), /\benablePoseDetection\b/.test(e) && (t.cv.poseDetection = !0), /\benableBodySegmentation\b/.test(e) && (t.cv.segmentation = !0);
+    /\bviji\.audio/.test(e) && (t.audio = !0), /\bviji\.video/.test(e) && (t.video = !0), /\bviji\.mouse/.test(e) && (t.mouse = !0), /\bviji\.keyboard/.test(e) && (t.keyboard = !0), /\bviji\.touches/.test(e) && (t.touch = !0), /\bviji\.pointer/.test(e) && (t.pointer = !0), /\bviji\.device\b/.test(e) && (t.sensors = !0), /\bviji\.devices/.test(e) && (t.devices = !0), /\bviji\.(slider|color|toggle|select|text|number|image|model|button|coordinate|gradient)\s*\(/.test(e) && (t.parameters = !0), /\benableFaceDetection\b/.test(e) && (t.cv.faceDetection = !0), /\benableFaceMesh\b/.test(e) && (t.cv.faceMesh = !0), /\benableEmotionDetection\b/.test(e) && (t.cv.emotion = !0), /\benableHandTracking\b/.test(e) && (t.cv.handTracking = !0), /\benablePoseDetection\b/.test(e) && (t.cv.poseDetection = !0), /\benableBodySegmentation\b/.test(e) && (t.cv.segmentation = !0);
   }
   /**
-   * Detects which specific interaction inputs a scene reads (positions and
-   * mouse buttons), for the worker's consumed-meaningfully evaluation. Renderer-
-   * aware: shader scenes are read from built-in uniform usage, native/p5 from
-   * `mouse.*` / `pointer.*` / `touches.*` member access. Comments/strings are
-   * stripped first. Inclusive-biased like {@link detectCapabilities}.
-   *
-   * @param sceneCode - The artist's scene code to analyze
-   * @param renderer - The renderer type (from {@link detectRendererType})
-   * @returns The interaction-input usage mask
+   * Shader per-source refinement (`caps.sources`) from built-in uniform usage.
+   * Runs after {@link detectShaderCapabilities} because `video.main` also
+   * follows from any `cv.*` flag: CV runs on the main stream only and no
+   * device-CV uniforms exist. The `u_*Stream*` families are host compositor
+   * inputs and report `streams`, never `main` or `device`. No device-audio
+   * uniform family exists, so `audio.device` stays `false`. The device-sensor
+   * regexes repeat the flag rules above on purpose: the two surfaces must not
+   * disagree.
+   */
+  static detectShaderSources(e, t) {
+    const i = t.sources, s = Object.values(t.cv).some(Boolean);
+    i.video.main = s || /\bu_video(?!Stream)\w*/.test(e), i.video.streams = /\bu_videoStream\w*/.test(e), i.video.device = /\bu_deviceCount\b/.test(e) || /\bu_device[0-7](Resolution|Connected)?\b/.test(e), i.audio.main = /\bu_audio(?!Stream)\w*/.test(e), i.audio.streams = /\bu_audioStream\w*/.test(e), i.sensors.internal = /\bu_device(Acceleration|AccelerationGravity|RotationRate|OrientationAbsolute|Orientation)\b/.test(e), i.sensors.device = /\bu_device[0-7](AccelerationGravity|Acceleration|RotationRate|Orientation)\b/.test(e) || /\bu_externalDeviceCount\b/.test(e);
+  }
+  /**
+   * Native / p5 per-source refinement (`caps.sources`) from `viji.*` tokens.
+   * `main` / `streams` / `internal` are exact-token matches (`\b` after the
+   * name keeps `viji.videoStreams` out of `video.main`). CV `enable*` calls do
+   * not imply `video.main`: device cameras expose the same CV surface, so the
+   * receiver decides. Device sources come from {@link detectScriptDeviceSources}.
    */
+  static detectScriptSources(e, t) {
+    const i = t.sources;
+    i.video.main = /\bviji\.video\b/.test(e), i.video.streams = /\bviji\.videoStreams\b/.test(e), i.audio.main = /\bviji\.audio\b/.test(e), i.audio.streams = /\bviji\.audioStreams\b/.test(e), i.sensors.internal = /\bviji\.device\b/.test(e), /\bviji\.devices\b/.test(e) && this.detectScriptDeviceSources(e, t);
+  }
+  /**
+   * Which members a native / p5 scene reads off `viji.devices[i]`. Device
+   * elements are reached through aliases (`for (const d of viji.devices)`,
+   * `devices.filter(d => d.video)`), so the signal is the member token itself:
+   * `.video`, `.audio`, `.motion` / `.orientation`. The main-stream and
+   * internal-sensor member chains (`viji.video.cv…`, `viji.device.motion…`)
+   * are removed first, whole chain not just the head token, so their own
+   * members cannot leak into the device result. If `viji.devices` is
+   * referenced and no member token survives (destructuring,
+   * `viji.devices.length`), every device source reports `true`: inclusive
+   * bias, the scene may read any of them.
+   */
+  static detectScriptDeviceSources(e, t) {
+    const i = e.replace(/\bviji\.(video|audio|device)\b(\s*\??\.\s*[A-Za-z_$][\w$]*)*/g, " "), s = /\.video\b/.test(i), r = /\.audio\b/.test(i), a = /\.(motion|orientation)\b/.test(i), o = !s && !r && !a, b = t.sources;
+    b.video.device = s || o, b.audio.device = r || o, b.sensors.device = a || o;
+  }
   /**
    * Whether the scene statically consumes the CV analysed frame. Gates
    * per-sink `analysedFrame` bitmap delivery from the shared CV engine to
@@ -162,6 +212,17 @@ class a {
     const t = this.stripCommentsAndStrings(e);
     return /\b(analysedFrame|getAnalysedFrameData)\b/.test(t) || /\bu_videoAnalysed\w*/.test(t);
   }
+  /**
+   * Detects which specific interaction inputs a scene reads (positions and
+   * mouse buttons), for the worker's consumed-meaningfully evaluation. Renderer-
+   * aware: shader scenes are read from built-in uniform usage, native/p5 from
+   * `mouse.*` / `pointer.*` / `touches.*` member access. Comments/strings are
+   * stripped first. Inclusive-biased like {@link detectCapabilities}.
+   *
+   * @param sceneCode - The artist's scene code to analyze
+   * @param renderer - The renderer type (from {@link detectRendererType})
+   * @returns The interaction-input usage mask
+   */
   static detectUsage(e, t) {
     const i = this.stripCommentsAndStrings(e), s = {
       mouse: { position: !1, left: !1, right: !1, middle: !1 },
@@ -171,16 +232,16 @@ class a {
     return t === "shader" ? (s.mouse.position = /\bu_mouse(\b|InCanvas|Delta|Wheel)/.test(i), s.mouse.left = /\bu_mouse(Left|Pressed|WasPressed|WasReleased)\b/.test(i), s.mouse.right = /\bu_mouseRight\b/.test(i), s.mouse.middle = /\bu_mouseMiddle\b/.test(i), s.pointer.position = /\bu_pointer(\b|Delta|InCanvas)/.test(i), s.pointer.down = /\bu_pointer(Down|WasPressed|WasReleased)\b/.test(i), s.touch = /\bu_touch/.test(i)) : (s.mouse.position = /\bmouse\.(x|y|deltaX|deltaY|wheelDelta|wheelX|wheelY|wasMoved)\b/.test(i), s.mouse.left = /\bmouse\.(leftButton|isPressed|wasPressed|wasReleased)\b/.test(i), s.mouse.right = /\bmouse\.rightButton\b/.test(i), s.mouse.middle = /\bmouse\.middleButton\b/.test(i), s.pointer.position = /\bpointer\.(x|y|deltaX|deltaY)\b/.test(i), s.pointer.down = /\bpointer\.(isDown|wasPressed|wasReleased)\b/.test(i), s.touch = /\btouches\./.test(i)), s;
   }
 }
-function b(n) {
-  const e = a.detectRendererType(n), t = e === "p5" ? a.detectP5CanvasMode(n) : void 0;
+function l(n) {
+  const e = u.detectRendererType(n), t = e === "p5" ? u.detectP5CanvasMode(n) : void 0;
   return {
     renderer: e,
     ...t !== void 0 && { p5CanvasMode: t },
-    capabilities: a.detectCapabilities(n, e),
-    consumesAnalysedFrame: a.detectAnalysedFrameUse(n)
+    capabilities: u.detectCapabilities(n, e),
+    consumesAnalysedFrame: u.detectAnalysedFrameUse(n)
   };
 }
 export {
-  a as S,
-  b as a
+  u as S,
+  l as a
 };