@viji-dev/core 0.6.1 → 0.7.0

package/dist/index.d.ts

@@ -1699,6 +1699,107 @@ export declare type Resolution = {
     height: number;
 };
 
+/**
+ * Structured scene console envelope surfaced via `VijiCore.onSceneConsole`.
+ *
+ * Only artist `console.*` calls reach this listener (the wrapper is injected
+ * as a function argument on the scene IIFE; engine code uses `globalThis.console`
+ * and is not surfaced). The wrapper calls the real `console[level](...args)`
+ * first before forwarding, so DevTools output is preserved.
+ *
+ * Arguments are pre-stringified in the worker with cycle-safe depth-bounded
+ * inspection, a per-argument byte cap (`consoleArgMaxBytes`), and an argument
+ * count cap (`consoleMaxArgsPerCall`). High-cardinality logs are rate-limited
+ * by `consoleMaxUniqueSignaturesPerSecond`.
+ */
+export declare interface SceneConsoleMessage {
+    /** Console method invoked. */
+    level: 'log' | 'info' | 'warn' | 'error';
+    /** Stringified arguments. Each entry is bounded by `consoleArgMaxBytes`. */
+    args: string[];
+    /** Stable hash of `level` and the stringified arguments, used for coalescing. */
+    signatureHash: string;
+    /** Number of occurrences of this signature accumulated in the current window. */
+    count: number;
+    /** Millisecond timestamp of the first occurrence of this signature in the current window. */
+    firstSeenAt: number;
+    /** Millisecond timestamp of the most recent occurrence. */
+    lastSeenAt: number;
+    /**
+     * Source location of the `console.*` call site in artist-source coordinates.
+     * Captured via `new Error().stack` inside the wrapper. Absent when stack
+     * frame parsing fails.
+     */
+    sourceLocation?: SceneSourceLocation;
+}
+
+/**
+ * Discriminator for scene runtime errors surfaced via `onSceneRuntimeError`.
+ *
+ * - `SCENE_CODE_ERROR`: thrown during `setSceneCode` parse/eval (native, P5).
+ * - `RENDER_ERROR`: synchronous throw inside the artist's `render()` function.
+ * - `UNCAUGHT_ERROR`: caught by the worker's `self.onerror` (async / RAF / setTimeout).
+ * - `UNHANDLED_REJECTION`: caught by the worker's `unhandledrejection` handler.
+ * - `SHADER_COMPILE_ERROR`: GLSL compile failure (shader mode).
+ * - `P5_INIT_ERROR`: failure during P5 mode initialization (e.g. missing `render`).
+ * - `ENGINE_INTERNAL`: engine path with no artist attribution.
+ */
+export declare type SceneErrorCode = 'SCENE_CODE_ERROR' | 'RENDER_ERROR' | 'UNCAUGHT_ERROR' | 'UNHANDLED_REJECTION' | 'SHADER_COMPILE_ERROR' | 'P5_INIT_ERROR' | 'ENGINE_INTERNAL';
+
+/**
+ * Structured scene runtime error envelope surfaced via `VijiCore.onSceneRuntimeError`.
+ *
+ * Identical signatures are coalesced inside the worker: the first occurrence in
+ * a window fires with `count: 1`, subsequent occurrences increment `count`, and
+ * a trailing rollup fires at window close if more than one occurrence was seen.
+ *
+ * The host-side `console.error('Scene error:', data)` tee continues to fire
+ * alongside the listener (never silenced based on listener presence).
+ */
+export declare interface SceneRuntimeError {
+    /** Error message, equivalent to `Error.message`. */
+    message: string;
+    /** Raw V8 stack trace, when available. Not resolved to artist-source coordinates. */
+    stack?: string;
+    /**
+     * Attribution: `'scene'` when at least one stack frame originates in the
+     * artist's compiled scene IIFE; `'engine'` otherwise.
+     */
+    source: 'scene' | 'engine';
+    /**
+     * Lifecycle phase: `'init'` before the first successful render frame
+     * completes; `'render'` afterwards.
+     */
+    phase: 'init' | 'render';
+    /** Error code; see `SceneErrorCode`. */
+    code: SceneErrorCode;
+    /** Stable hash of `message` and the first artist stack frame, used for coalescing. */
+    signatureHash: string;
+    /** Number of occurrences of this signature accumulated in the current window. */
+    count: number;
+    /** Millisecond timestamp of the first occurrence of this signature in the current window. */
+    firstSeenAt: number;
+    /** Millisecond timestamp of the most recent occurrence. */
+    lastSeenAt: number;
+    /**
+     * Source location resolved to artist-source coordinates when available.
+     * Absent when no artist stack frame is found (engine errors), when shader
+     * compile logs lack column info, or when sourcemap resolution fails.
+     */
+    sourceLocation?: SceneSourceLocation;
+}
+
+/**
+ * Resolved source location in artist-source coordinates. `line` is 1-based and
+ * matches the artist's authored TypeScript / GLSL line numbers. `column` is
+ * 1-based when present; absent when sourcemap resolution failed or the source
+ * is GLSL (which doesn't reliably emit column information in compile logs).
+ */
+export declare interface SceneSourceLocation {
+    line: number;
+    column?: number;
+}
+
 /**
  * Per-pixel person/background segmentation mask. Mask dimensions reflect the
  * ML model's output and may differ from the source video frame.
@@ -2267,7 +2368,7 @@ declare type TrackingState = 'TRACKING' | 'LOCKED' | 'BREAKDOWN' | 'LOST';
 /** Returned by `on*` listener registration calls; invoke to unsubscribe. */
 export declare type Unsubscribe = () => void;
 
-export declare const VERSION = "0.5.7";
+export declare const VERSION = "0.7.0";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2633,6 +2734,8 @@ export declare class VijiCore {
     private parameterErrorListeners;
     private capabilitiesChangeListeners;
     private stateImportErrorListeners;
+    private sceneRuntimeErrorListeners;
+    private sceneConsoleListeners;
     private stats;
     constructor(config: VijiCoreConfig);
     /**
@@ -2928,6 +3031,42 @@ export declare class VijiCore {
      */
     onStateImportError(listener: (error: StateImportError) => void): Unsubscribe;
     private fireStateImportError;
+    /**
+     * Listen for scene runtime errors surfaced by the worker. Errors caused by
+     * the artist's scene code (`SCENE_CODE_ERROR`, `RENDER_ERROR`,
+     * `SHADER_COMPILE_ERROR`, `P5_INIT_ERROR`, plus async / unhandled-rejection
+     * paths originating in the scene) are coalesced on the worker side: identical
+     * signatures within `VijiCoreConfig.errorCoalescingWindowMs` (default 1s)
+     * collapse to a single leading-edge listener call plus an optional trailing
+     * rollup with the final `count`.
+     *
+     * The legacy `console.error('Worker error:', data)` host log continues to
+     * fire alongside this listener (tee semantics, never silenced).
+     *
+     * @returns Unsubscribe function. Call to remove the listener.
+     */
+    onSceneRuntimeError(listener: (error: SceneRuntimeError) => void): Unsubscribe;
+    private fireSceneRuntimeError;
+    /**
+     * Listen for `console.*` calls made from the artist's scene code. The
+     * worker injects a wrapped `console` as an additional function-argument
+     * binding to the artist's IIFE; the wrapper calls the real `console[level]`
+     * first (preserving DevTools output) and then forwards a coalesced, bounded
+     * envelope through this listener.
+     *
+     * Coalescing window: `VijiCoreConfig.consoleCoalescingWindowMs` (default 1s).
+     * Argument bounds: `consoleArgMaxBytes` (default 512B per arg),
+     * `consoleMaxArgsPerCall` (default 8 args). Rate cap on distinct signatures:
+     * `consoleMaxUniqueSignaturesPerSecond` (default 32).
+     *
+     * Only the four forwarded levels (`log`, `info`, `warn`, `error`) reach
+     * this listener. Other console methods (`debug`, `trace`, `dir`, `group`,
+     * etc.) pass through to the real console unchanged but are not surfaced.
+     *
+     * @returns Unsubscribe function. Call to remove the listener.
+     */
+    onSceneConsole(listener: (message: SceneConsoleMessage) => void): Unsubscribe;
+    private fireSceneConsole;
     /**
      * Notify parameter change listeners
      */
@@ -3406,6 +3545,34 @@ export declare interface VijiCoreConfig {
     _rh?: number;
     /** Called when the scene is visually live (render loop running, branding applied) but before audio/video/WASM setup completes. */
     onRenderStart?: () => void;
+    /**
+     * Coalescing window in milliseconds for `onSceneRuntimeError` listener. Identical signatures
+     * within the window collapse into a single host-side message with an incremented `count`.
+     * Default: `1000`.
+     */
+    errorCoalescingWindowMs?: number;
+    /**
+     * Coalescing window in milliseconds for `onSceneConsole` listener. Identical signatures
+     * within the window collapse into a single host-side message with an incremented `count`.
+     * Default: `1000`.
+     */
+    consoleCoalescingWindowMs?: number;
+    /**
+     * Per-argument byte cap for `onSceneConsole` payloads. Arguments longer than this are
+     * truncated with a `…[truncated]` marker. Default: `512`.
+     */
+    consoleArgMaxBytes?: number;
+    /**
+     * Maximum arguments per `console.*` call forwarded through `onSceneConsole`. Excess arguments
+     * are dropped. Default: `8`.
+     */
+    consoleMaxArgsPerCall?: number;
+    /**
+     * Rate cap on distinct console signatures forwarded per second. Excess unique signatures
+     * are dropped with a single synthetic "console suppressed: high frequency" envelope per
+     * overflow window. Default: `32`.
+     */
+    consoleMaxUniqueSignaturesPerSecond?: number;
 }
 
 export declare class VijiCoreError extends Error {

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as a, V as i, a as s, b as e } from "./index-DfAcgMbB.js";
+import { A as a, V as i, a as s, b as e } from "./index-BCIUaaLW.js";
 export {
   a as AudioSystem,
   i as VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "main": "./dist/index.js",
@@ -51,6 +51,7 @@
     "prebuild": "node scripts/prebuild-clean.mjs",
     "build": "vite build && node scripts/copy-tasks-assets.mjs && node scripts/build-artist-types.mjs && node scripts/build-docs-api.mjs",
     "build:docs": "node scripts/build-docs-api.mjs",
+    "lint:ai-prompts-drift": "node scripts/lint-ai-prompts-drift.mjs",
     "dev": "vite build --watch",
     "integration": "vite --config integration-example/vite.config.ts",
     "test": "vitest",