@viji-dev/core 0.12.0 → 0.14.0

package/dist/scene-analysis-CEQRlNUL.js

@@ -0,0 +1,186 @@
+class a {
+  /**
+   * Detects the renderer type from scene code comments
+   * 
+   * Looks for:
+   * - // @renderer shader
+   * - /* @renderer shader *\/
+   * - // @renderer p5
+   * - /* @renderer p5 *\/
+   * 
+   * @param sceneCode - The artist's scene code to analyze
+   * @returns The detected renderer type ('shader', 'p5', or 'native')
+   */
+  static detectRendererType(e) {
+    return /\/\/\s*@renderer\s+shader|\/\*\s*@renderer\s+shader\s*\*\//.test(e) ? "shader" : /\/\/\s*@renderer\s+p5|\/\*\s*@renderer\s+p5\s*\*\//.test(e) ? "p5" : "native";
+  }
+  /**
+   * P5 main-canvas mode from the renderer directive (only meaningful when
+   * {@link detectRendererType} is `'p5'`).
+   *
+   * - `// @renderer p5` → 2D (default)
+   * - `// @renderer p5 webgl` → WEBGL
+   */
+  static detectP5CanvasMode(e) {
+    return /\/\/\s*@renderer\s+p5\s+webgl\b|\/\*\s*@renderer\s+p5\s+webgl\s*\*\//i.test(
+      e
+    ) ? "webgl" : "2d";
+  }
+  /**
+   * Detects which engine capabilities the scene's code declares it uses.
+   *
+   * Static analysis only — the scene is never executed. Comments and string
+   * literals are stripped first (so capabilities cannot be spoofed via
+   * commented-out code), then capability tokens are matched. Detection is
+   * **inclusive-biased**: a capability the scene actually uses is never
+   * hidden, but a rarely-ambiguous case may report an extra one (a false
+   * "show" is harmless; a false "hide" would break a working scene).
+   *
+   * - Shader scenes: matched against built-in `u_*` uniform usage (exact).
+   * - Native / p5 scenes: matched against `viji.*` usage tokens.
+   *
+   * @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
+   */
+  static detectCapabilities(e, t) {
+    const i = this.stripCommentsAndStrings(e), s = {
+      audio: !1,
+      video: !1,
+      mouse: !1,
+      keyboard: !1,
+      pointer: !1,
+      touch: !1,
+      parameters: !1,
+      sensors: !1,
+      devices: !1,
+      cv: {
+        faceDetection: !1,
+        faceMesh: !1,
+        emotion: !1,
+        handTracking: !1,
+        poseDetection: !1,
+        segmentation: !1
+      }
+    };
+    return t === "shader" ? this.detectShaderCapabilities(i, s) : this.detectScriptCapabilities(i, s), s;
+  }
+  /**
+   * Replaces comment spans and string/template literals with whitespace via a
+   * single forward scan. Robust against the regex-ordering pitfalls of
+   * stripping comments and strings independently (a `//` inside a string, or a
+   * quote inside a comment). Over-stripping is acceptable for capability
+   * detection; under-detection is not.
+   */
+  static stripCommentsAndStrings(e) {
+    let t = "";
+    const i = e.length;
+    let s = 0;
+    for (; s < i; ) {
+      const r = e[s], o = s + 1 < i ? e[s + 1] : "";
+      if (r === "/" && o === "/") {
+        for (s += 2; s < i && e[s] !== `
+`; ) s++;
+        continue;
+      }
+      if (r === "/" && o === "*") {
+        for (s += 2; s < i && !(e[s] === "*" && e[s + 1] === "/"); ) s++;
+        s += 2, t += " ";
+        continue;
+      }
+      if (r === '"' || r === "'" || r === "`") {
+        const u = r;
+        for (s++; s < i; ) {
+          if (e[s] === "\\") {
+            s += 2;
+            continue;
+          }
+          if (e[s] === u) {
+            s++;
+            break;
+          }
+          s++;
+        }
+        t += " ";
+        continue;
+      }
+      t += r, s++;
+    }
+    return t;
+  }
+  /**
+   * Shader (GLSL) capability detection from built-in `u_*` uniform usage.
+   * The uniform-name SOT is `ShaderWorkerAdapter.getBuiltInUniforms()`.
+   * The `u_device*` family is suffix-aware: camera uniforms
+   * (`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.
+   */
+  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);
+  }
+  /**
+   * 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).
+   */
+  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)\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
+   */
+  /**
+   * Whether the scene statically consumes the CV analysed frame. Gates
+   * per-sink `analysedFrame` bitmap delivery from the shared CV engine to
+   * zero for non-consumers.
+   *
+   * Three arms, inclusive-biased (over-detection is safe — the sink merely
+   * receives bitmaps it ignores; under-detection breaks consumers SILENTLY):
+   *   - `analysedFrame` / `getAnalysedFrameData` — the JS surface
+   *     (native / p5 scenes, any stream).
+   *   - `u_videoAnalysed*` — the SHADER arm: GLSL scenes consume the
+   *     analysed frame as a texture bound by ShaderWorkerAdapter and never
+   *     contain the JS names; without this arm they would be classified as
+   *     non-consumers and permanently sample the 1×1 black fallback.
+   *     (Same source pattern as the capability mapping above, which routes
+   *     `u_videoAnalysed*` to `cv.faceMesh` — this is a separate consumer
+   *     flag, NOT a capability: it must not move cohort keys.)
+   *
+   * @param sceneCode - The artist's scene code to analyze
+   * @returns true when the scene reads the analysed frame
+   */
+  static detectAnalysedFrameUse(e) {
+    const t = this.stripCommentsAndStrings(e);
+    return /\b(analysedFrame|getAnalysedFrameData)\b/.test(t) || /\bu_videoAnalysed\w*/.test(t);
+  }
+  static detectUsage(e, t) {
+    const i = this.stripCommentsAndStrings(e), s = {
+      mouse: { position: !1, left: !1, right: !1, middle: !1 },
+      pointer: { position: !1, down: !1 },
+      touch: !1
+    };
+    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;
+  return {
+    renderer: e,
+    ...t !== void 0 && { p5CanvasMode: t },
+    capabilities: a.detectCapabilities(n, e),
+    consumesAnalysedFrame: a.detectAnalysedFrameUse(n)
+  };
+}
+export {
+  a as S,
+  b as a
+};

package/dist/scene-analysis.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Full static scene analysis — everything the worker's `scene-analysis` ack
+ * carries, computed without constructing a core. Composes the same four
+ * statics the worker runs in phase 1 of scene load ({@link
+ * SceneAnalyzer.detectRendererType} → {@link SceneAnalyzer.detectP5CanvasMode}
+ * → {@link SceneAnalyzer.detectCapabilities} → {@link
+ * SceneAnalyzer.detectAnalysedFrameUse}), and the worker itself consumes this
+ * function to build the ack — so for a given core version the result is the
+ * exact payload a booted core's `initialize()` resolves its scene analysis
+ * with. Parity holds through shared code, not parallel composition.
+ *
+ * Intended for out-of-engine consumers (e.g. server-side persistence of
+ * per-scene capabilities; migration tooling that needs the renderer without
+ * booting a core). The following properties are an intentional, kept
+ * contract, covering all four fields:
+ * - **Pure and Node-safe** — static analysis only; the scene is never
+ *   executed and no DOM, canvas, or worker API is touched. Callable in a
+ *   bare Node process.
+ * - **Deterministic** — same code string, same result, within a core version.
+ * - **Raw-code input** — `renderer` and `p5CanvasMode` are comment-directive
+ *   scans over the artist's original source, before any transpilation (the
+ *   worker applies sucrase only after this analysis, and only to script
+ *   scenes). Pass stored scene code as-is.
+ * - **Inclusive-biased** (`capabilities`) — a capability the scene uses is
+ *   never hidden; a rare ambiguous case may report an extra one.
+ * - **Safe on untrusted input** — linear-time scans and regexes with no
+ *   throw paths on any string input.
+ *
+ * `p5CanvasMode` is present only when `renderer` is `'p5'`, mirroring the
+ * ack shape exactly.
+ *
+ * Note for consumers filtering on `capabilities.video`: the flag means the
+ * scene reads the video *image* (pixels/texture). Shader scenes that consume
+ * only CV result uniforms report `cv.*` without `video`, so a "reacts to the
+ * camera" filter should test `video || any cv key`.
+ *
+ * @param sceneCode - The artist's scene code (native, p5, or shader), raw
+ * @returns The complete static analysis — the worker's ack payload
+ * @example
+ * ```ts
+ * const analysis = analyzeScene(scene.code);
+ * if (analysis.renderer === 'shader') return skip(scene);
+ * if (analysis.capabilities.audio) tags.push('audio');
+ * ```
+ */
+export declare function analyzeScene(sceneCode: string): SceneAnalysisData;
+
+/**
+ * P5 main-canvas mode. Only meaningful when {@link SceneData.renderer} is
+ * `'p5'`: `'2d'` for the default 2D canvas, `'webgl'` for a WEBGL canvas.
+ */
+declare type P5CanvasMode = '2d' | 'webgl';
+
+declare type RendererType = 'native' | 'p5' | 'shader';
+
+/**
+ * Payload of the worker's `scene-analysis` ack — the correlated response to
+ * `set-scene-code`. The worker runs static analysis (renderer, capabilities,
+ * p5 canvas mode, analysedFrame consumption) after receiving the scene code
+ * and **before** compiling it, and the host's `initialize()` awaits this ack
+ * to assign the four `SceneData` fields exactly once. Carries booleans/enums
+ * only — never scene source.
+ *
+ * Public since 0.14.0: this is also the return type of `analyzeScene`
+ * (`@viji-dev/core/scene-analysis`), which the worker itself calls to build
+ * the ack — one shape, one producer, two transports.
+ */
+declare interface SceneAnalysisData {
+    /** Detected renderer the scene targets. */
+    renderer: RendererType;
+    /** P5 canvas mode; present only when `renderer` is `'p5'`. */
+    p5CanvasMode?: P5CanvasMode;
+    /** Capabilities the scene's code declares it uses (inclusive-biased). */
+    capabilities: SceneCapabilities;
+    /** Whether the scene consumes per-frame analysed-frame bitmaps (CV). */
+    consumesAnalysedFrame: boolean;
+}
+
+/**
+ * The set of engine capabilities a scene's code declares it uses, derived by
+ * static analysis of the scene source (no execution). Detection is
+ * **inclusive-biased**: a capability the scene actually uses is never hidden,
+ * but a rarely-ambiguous case may show an extra one. Shader scenes are
+ * detected from built-in uniform usage (exact); native/p5 scenes from
+ * `viji.*` usage tokens.
+ *
+ * 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.
+ */
+declare interface SceneCapabilities {
+    /** Scene reads audio analysis (volume, bands, beat, FFT/waveform, or audio streams). */
+    audio: boolean;
+    /** Scene reads video input (camera frame, video streams, or device cameras). */
+    video: boolean;
+    /** Scene reads mouse state. */
+    mouse: boolean;
+    /** Scene reads keyboard state. */
+    keyboard: boolean;
+    /** Scene reads the unified pointer (mouse/touch) state. */
+    pointer: boolean;
+    /** Scene reads multi-touch state. */
+    touch: boolean;
+    /** Scene declares tunable parameters. */
+    parameters: boolean;
+    /** Scene reads internal device motion/orientation sensors (`viji.device`). */
+    sensors: boolean;
+    /** Scene reads external connected devices (`viji.devices`). */
+    devices: boolean;
+    /** Per-feature computer-vision usage. */
+    cv: {
+        /** Scene uses face detection (bounding boxes). */
+        faceDetection: boolean;
+        /** Scene uses face mesh / landmarks / blendshapes. */
+        faceMesh: boolean;
+        /** Scene uses emotion / expression detection. */
+        emotion: boolean;
+        /** Scene uses hand tracking. */
+        handTracking: boolean;
+        /** Scene uses body pose detection. */
+        poseDetection: boolean;
+        /** Scene uses body segmentation. */
+        segmentation: boolean;
+    };
+}
+
+export { }

package/dist/scene-analysis.js

@@ -0,0 +1,4 @@
+import { a as n } from "./scene-analysis-CEQRlNUL.js";
+export {
+  n as analyzeScene
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "sideEffects": false,
@@ -12,6 +12,15 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
+    "./scene-analysis": {
+      "import": "./dist/scene-analysis.js",
+      "types": "./dist/scene-analysis.d.ts"
+    },
+    "./param-inference": {
+      "import": "./dist/param-inference.js",
+      "types": "./dist/param-inference.d.ts"
+    },
+    "./package.json": "./package.json",
     "./artist-global": {
       "types": "./dist/artist-global.d.ts"
     },
@@ -49,6 +58,7 @@
     "README.md"
   ],
   "scripts": {
+    "audio-lab": "vite --config audio-lab/vite.config.mjs",
     "prebuild": "node scripts/prebuild-clean.mjs && node scripts/sync-version.mjs",
     "version": "npm run build && git add -A",
     "build": "vite build && node scripts/copy-tasks-assets.mjs && node scripts/minify-dist.mjs && node scripts/build-artist-types.mjs && node scripts/lint-artist-types-drift.mjs && node scripts/build-docs-api.mjs",