@agent-native/core 0.88.0 → 0.90.2

package/corpus/templates/design/app/components/design/bridge/motion-preview.bridge.ts

@@ -9,21 +9,35 @@
  *   { type: 'motion-load-tracks', tracks: Array<{
  *       targetNodeId: string,
  *       property: string,
- *       keyframes: Array<{ t: number, value: string, ease?: string }>
- *     }>, defaultEase?: string }
- *     Load (or replace) the track list. t ∈ [0, 1]. defaultEase is the
- *     timeline-level fallback easing applied to any keyframe that omits its
- *     own `ease` (mirrors the compiled stylesheet); defaults to "ease".
+ *       keyframes: Array<{ t: number, value: string, ease?: string }>,
+ *       delayMs?: number,      // track start offset within the timeline
+ *       durationMs?: number    // per-track span; omitted = whole timeline
+ *     }>, defaultEase?: string, durationMs?: number }
+ *     Load (or replace) the track list. Keyframe t ∈ [0, 1] is normalised to
+ *     the TRACK's own span. defaultEase is the timeline-level fallback easing
+ *     applied to any keyframe that omits its own `ease` (mirrors the compiled
+ *     stylesheet); defaults to "ease". durationMs is the timeline duration,
+ *     needed to map offset tracks; also refreshed by each motion-preview tick.
  *
  *   { type: 'motion-preview', t, durationMs }
- *     Seek all loaded tracks to normalised position t ∈ [0, 1] and apply
- *     interpolated CSS property values as inline styles on the matching
- *     [data-agent-native-node-id="…"] elements. Never writes to storage.
+ *     Seek all loaded tracks to normalised TIMELINE position t ∈ [0, 1] and
+ *     apply interpolated CSS property values as inline styles on the matching
+ *     [data-agent-native-node-id="…"] elements. Tracks with delayMs /
+ *     durationMs map the timeline time into their own span, clamping outside
+ *     it (animation-fill-mode: both semantics). Never writes to storage.
  *
  *   { type: 'motion-preview-clear' }
  *     Remove all motion-preview inline-style overrides and the in-memory
  *     track list. Called when the dock is closed or the timeline is discarded.
  *
+ * Easing parity: per-segment easing reads the ease of the keyframe LEAVING
+ * each interval (CSS keyframe semantics — equivalently, Figma's easing INTO
+ * the next keyframe). Supported forms: CSS keywords, cubic-bezier(...),
+ * steps(...), CSS linear(...) stop lists, and real spring physics via
+ * spring(bounce[, settle]) tokens — keep the samplers in sync with
+ * shared/motion-easing.ts. Playback modes (loop/once/ping-pong) live in the
+ * MotionDock's rAF driver, which shapes the `t` values it sends here.
+ *
  * Rules:
  *   • No import/require of any module (DOM globals only).
  *   • No references to outer/module scope (the code runs inside an iframe).
@@ -35,12 +49,19 @@
     targetNodeId: string;
     property: string;
     keyframes: Array<{ t: number; value: string; ease?: string }>;
+    delayMs?: number;
+    durationMs?: number;
   }> = [];
   // Timeline-level default easing sent alongside the tracks. Applied to any
   // keyframe that omits its own `ease`, matching the compiled stylesheet's
   // defaultEase fallback so scrub/playback preview equals the persisted CSS.
   // Falls back to "ease" when the loader doesn't provide one.
   var loadedDefaultEase = "ease";
+  // Timeline duration in ms, needed to map timeline time into the local span
+  // of tracks that carry delayMs / durationMs offsets. Provided by
+  // 'motion-load-tracks' and refreshed by every 'motion-preview' tick; when
+  // unknown, offset-free tracks still preview correctly (local t = t).
+  var loadedTimelineDurationMs: number | null = null;
   // Map of nodeId -> [property, ...] we have touched, for cleanup.
   var touchedProps: Record<string, string[]> = {};
   // Map of nodeId -> property -> original inline style value.
@@ -348,13 +369,131 @@
         );
       }
     }
-    // Spring approximation: gentle overshoot bezier.
+    // Real spring physics: spring(bounce[, settle]) tokens sampled from a
+    // damped oscillator. Keep in sync with shared/motion-easing.ts.
     if (raw.indexOf("spring") === 0) {
-      return cubicBezierY(0.34, 1.56, 0.64, 1, clamped);
+      var spr = parseSpringEase(raw);
+      if (spr) return sampleSpringAt(spr[0], spr[1], clamped);
+      return clamped;
+    }
+    // CSS linear(...) stop lists (compiled springs / recovered timelines).
+    if (raw.indexOf("linear(") === 0) {
+      var lin = evalCssLinear(raw, clamped);
+      if (lin !== null) return lin;
     }
     return clamped;
   }
 
+  // Parse spring(bounce[, settle]) or the bare `spring` keyword into
+  // [bounce, settle], or null. Mirror of shared/motion-easing.ts.
+  function parseSpringEase(raw: string): [number, number] | null {
+    if (/^spring$/.test(raw)) return [0.25, 1];
+    var m = /^spring\(\s*([+-]?[\d.]+)\s*(?:,\s*([+-]?[\d.]+)\s*)?\)$/.exec(
+      raw,
+    );
+    if (!m) return null;
+    var bounce = parseFloat(m[1]);
+    if (!Number.isFinite(bounce)) return null;
+    var settle = m[2] === undefined ? 1 : parseFloat(m[2]);
+    if (!Number.isFinite(settle)) return null;
+    if (settle < 0.05) settle = 0.05;
+    if (settle > 1) settle = 1;
+    return [clamp01(bounce), settle];
+  }
+
+  // Damped-oscillator sampler. Mirror of sampleSpring in
+  // shared/motion-easing.ts — keep the two in sync.
+  function sampleSpringAt(bounce: number, settle: number, x: number): number {
+    if (x <= 0) return 0;
+    var u = x / settle;
+    if (u >= 1) return 1;
+    var zeta = 1 - clamp01(bounce);
+    if (zeta < 0.02) zeta = 0.02;
+    if (zeta > 1) zeta = 1;
+    var omega = Math.log(1 / 0.001) / zeta;
+    if (zeta >= 1) {
+      return 1 - Math.exp(-omega * u) * (1 + omega * u);
+    }
+    var omegaD = omega * Math.sqrt(1 - zeta * zeta);
+    var decay = Math.exp(-zeta * omega * u);
+    return (
+      1 -
+      decay *
+        (Math.cos(omegaD * u) +
+          ((zeta * omega) / omegaD) * Math.sin(omegaD * u))
+    );
+  }
+
+  // Evaluate a CSS linear(value <percent>{0,2}, ...) timing function at
+  // progress x. Mirror of evaluateCssLinear in shared/motion-easing.ts.
+  function evalCssLinear(raw: string, x: number): number | null {
+    var m = /^linear\(([^)]*)\)$/.exec(raw);
+    if (!m) return null;
+    var entries = m[1].split(",");
+    var values: number[] = [];
+    var positions: Array<number | null> = [];
+    for (var i = 0; i < entries.length; i++) {
+      var entry = entries[i].trim();
+      if (!entry) continue;
+      var parts = entry.split(/\s+/);
+      var value = parseFloat(parts[0]);
+      if (!Number.isFinite(value)) return null;
+      var found = 0;
+      for (var j = 1; j < parts.length && j <= 2; j++) {
+        if (!/%$/.test(parts[j])) return null;
+        var pct = parseFloat(parts[j]);
+        if (!Number.isFinite(pct)) return null;
+        values.push(value);
+        positions.push(pct / 100);
+        found++;
+      }
+      if (found === 0) {
+        values.push(value);
+        positions.push(null);
+      }
+    }
+    if (values.length < 2) return null;
+    if (positions[0] === null) positions[0] = 0;
+    if (positions[positions.length - 1] === null) {
+      positions[positions.length - 1] = 1;
+    }
+    var runningMax = positions[0] as number;
+    for (var k = 0; k < positions.length; k++) {
+      var pos = positions[k];
+      if (pos !== null) {
+        var clampedPos = pos < runningMax ? runningMax : pos;
+        positions[k] = clampedPos;
+        runningMax = clampedPos;
+        continue;
+      }
+      var nextIdx = k + 1;
+      while (nextIdx < positions.length && positions[nextIdx] === null) {
+        nextIdx++;
+      }
+      var prevPos = runningMax;
+      var nextPosRaw = positions[nextIdx] as number;
+      var nextPos = nextPosRaw < prevPos ? prevPos : nextPosRaw;
+      var span = nextIdx - (k - 1);
+      for (var q = k; q < nextIdx; q++) {
+        positions[q] = prevPos + ((q - (k - 1)) / span) * (nextPos - prevPos);
+      }
+      k = nextIdx - 1;
+      runningMax = nextPos;
+    }
+    var cx = clamp01(x);
+    if (cx <= (positions[0] as number)) return values[0];
+    for (var p = 0; p < values.length - 1; p++) {
+      var aPos = positions[p] as number;
+      var bPos = positions[p + 1] as number;
+      if (cx > bPos) continue;
+      if (bPos === aPos) return values[p + 1];
+      return (
+        values[p] + ((values[p + 1] - values[p]) * (cx - aPos)) / (bPos - aPos)
+      );
+    }
+    return values[values.length - 1];
+  }
+
   // Build the identity counterpart of a transform/filter list so a
   // `none` endpoint interpolates smoothly instead of midpoint-snapping
   // (e.g. none -> translateY(16px) lerps from translateY(0px)).
@@ -505,6 +644,32 @@
     return lerp(prev.value, next.value, eased);
   }
 
+  // Map a normalised TIMELINE time to a track-local normalised time,
+  // honouring the track's delayMs / durationMs span. Clamped outside the
+  // span (animation-fill-mode: both semantics). Without a known timeline
+  // duration, offset-free tracks behave as before (local t = t).
+  function trackLocalT(
+    track: { delayMs?: number; durationMs?: number },
+    t: number,
+  ): number {
+    var delay =
+      typeof track.delayMs === "number" && track.delayMs > 0
+        ? track.delayMs
+        : 0;
+    var dur =
+      typeof track.durationMs === "number" && track.durationMs > 0
+        ? track.durationMs
+        : null;
+    if (loadedTimelineDurationMs === null || (delay === 0 && dur === null)) {
+      return t;
+    }
+    var timeMs = t * loadedTimelineDurationMs;
+    var span = dur === null ? loadedTimelineDurationMs : dur;
+    if (span <= 0) return 0;
+    var local = (timeMs - delay) / span;
+    return local < 0 ? 0 : local > 1 ? 1 : local;
+  }
+
   function applyPreview(t: number): void {
     for (var i = 0; i < loadedTracks.length; i++) {
       var track = loadedTracks[i];
@@ -512,7 +677,7 @@
         '[data-agent-native-node-id="' + track.targetNodeId + '"]',
       ) as HTMLElement | null;
       if (!el) continue;
-      var value = interpolate(track.keyframes, t);
+      var value = interpolate(track.keyframes, trackLocalT(track, t));
       if (value === "") continue;
       // Normalize kebab properties (e.g. background-color) to the camelCase
       // CSSOM accessor; el.style['background-color'] = … is unreliable.
@@ -552,6 +717,7 @@
     originalInlineValues = {};
     loadedTracks = [];
     loadedDefaultEase = "ease";
+    loadedTimelineDurationMs = null;
   }
 
   // Last previewed playhead position, so reloading the track list (which
@@ -573,6 +739,12 @@
         typeof e.data.defaultEase === "string" && e.data.defaultEase
           ? e.data.defaultEase
           : "ease";
+      // Timeline duration (read AFTER clearPreview, which resets it): needed
+      // to map offset tracks before the first motion-preview tick arrives.
+      var loadDur = Number(e.data.durationMs);
+      if (Number.isFinite(loadDur) && loadDur > 0) {
+        loadedTimelineDurationMs = loadDur;
+      }
       // Defensive: interpolate() scans keyframe pairs in array order, so an
       // unsorted track (e.g. mid-drag ordering) would fail the window test.
       for (var i = 0; i < loadedTracks.length; i++) {
@@ -592,6 +764,10 @@
       var t = Number(e.data.t);
       if (!Number.isFinite(t)) return;
       t = Math.max(0, Math.min(1, t));
+      var tickDur = Number(e.data.durationMs);
+      if (Number.isFinite(tickDur) && tickDur > 0) {
+        loadedTimelineDurationMs = tickDur;
+      }
       lastPreviewT = t;
       applyPreview(t);
       return;

package/corpus/templates/design/app/components/design/bridge/shader-fill-preview.bridge.ts

@@ -10,13 +10,49 @@
  *     Apply `css` as the `background` inline style on the first element that
  *     matches `selector` (preferred) or `[data-agent-native-node-id="nodeId"]`.
  *     When both are absent, targets `document.body`. Stores the previous
- *     background value so it can be restored on clear.
+ *     background value so it can be restored on clear. `css` is run through
+ *     isSafeBackgroundStyleValue() below (a minimal duplicate of
+ *     isSafeStyleValue() in shared/code-layer.ts) before it ever touches
+ *     el.style.background — unsafe values are dropped silently (no style
+ *     write) and a `shader-fill-preview-rejected` message is posted back.
  *     Preview-only — never writes to DB, Yjs, or source files.
  *
  *   { type: 'shader-fill-preview-clear' }
  *     Remove the applied background override and restore the previous value.
  *     Called when the user discards the preview or switches selections.
  *
+ * GLSL protocol (delegates to the code-backed shader runtime injected right
+ * before this bridge — see shader-runtime.bridge.ts / window.__anShaders; all
+ * of these no-op harmlessly when the runtime is unavailable):
+ *
+ *   { type: 'glsl-shader-preview', target: { selector?, nodeId? },
+ *     shader: { id?, name?, glsl, uniforms? }, values?, mode: 'fill'|'effect' }
+ *     Mount a live WebGL preview of the shader on the target element without
+ *     persisting anything. Only the iframe that actually contains the target
+ *     mounts it (no body fallback), so the parent can safely broadcast to
+ *     every screen iframe. `shader.glsl`/`shader.uniforms` are run through
+ *     validatePreviewShaderDef() below — a minimal duplicate of the
+ *     structural checks validateShaderDef()/validateGlslSource()/
+ *     validateUniformManifest() apply on the persist path in
+ *     shared/shader-fills.ts — before ever reaching the WebGL compiler; a
+ *     rejected shader posts `glsl-shader-preview-rejected` with the reasons
+ *     instead of compiling. Also enforces a local MAX_PREVIEW_MOUNTS (8) cap
+ *     — every accepted preview request increments a counter that only resets
+ *     on `glsl-shader-preview-clear` — matching the runtime's own MAX_MOUNTS,
+ *     independent of the runtime's internal bookkeeping.
+ *
+ *   { type: 'glsl-shader-set-uniform', filter: { shaderId?, nodeId?, preview? },
+ *     name, value }
+ *     Live-update one uniform on matching mounts (knob scrubbing).
+ *
+ *   { type: 'glsl-shader-update', id, glsl?, uniforms? }
+ *     Hot-swap a registered shader's source/manifest (Edit-code live preview).
+ *     Same structural validation as glsl-shader-preview runs before the
+ *     hot-swap is forwarded to the runtime.
+ *
+ *   { type: 'glsl-shader-preview-clear' }   — unmount preview mounts.
+ *   { type: 'glsl-shader-rescan' }          — re-scan persisted annotations.
+ *
  * Rules:
  *   • No import/require of any module (DOM globals only).
  *   • No references to outer/module scope (the code runs inside an iframe).
@@ -43,9 +79,45 @@
     return document.body;
   }
 
+  /**
+   * Minimal inline equivalent of isSafeStyleValue() in shared/code-layer.ts
+   * (the sanitizer the persist path runs style edits through), scoped to the
+   * one property this bridge ever writes: the `background` shorthand. Bridge
+   * files cannot import shared modules (see bridge.guard.spec.ts's no-import
+   * guard), so this duplicates the source-of-truth's rules instead of
+   * reusing them — keep in sync with isSafeStyleValue() in
+   * shared/code-layer.ts:
+   *   - reject empty values
+   *   - reject expression(...) and javascript: breakouts
+   *   - reject url(...) (only the background-image longhand is ever allowed
+   *     a url() reference on the persist path; the background shorthand
+   *     this bridge writes stays on the strict no-url path)
+   *   - reject raw <>{}; breakout characters
+   */
+  function isSafeBackgroundStyleValue(value: string): boolean {
+    if (typeof value !== "string") return false;
+    var trimmed = value.trim();
+    if (!trimmed) return false;
+    if (/expression\s*\(/i.test(trimmed)) return false;
+    if (/javascript\s*:/i.test(trimmed)) return false;
+    if (/url\s*\(/i.test(trimmed)) return false;
+    if (/[<>{};]/.test(trimmed)) return false;
+    return true;
+  }
+
   function applyPreview(selector: string, nodeId: string, css: string): void {
     // Clear any prior patch first so we don't stack patches.
     clearPreview();
+    if (css && !isSafeBackgroundStyleValue(css)) {
+      // Reject silently (no style write) + tell the parent why.
+      try {
+        window.parent.postMessage(
+          { type: "shader-fill-preview-rejected", reason: "unsafe-css-value" },
+          "*",
+        );
+      } catch (_err) {}
+      return;
+    }
     var el = resolveTarget(selector, nodeId);
     if (!el) return;
     originalBackground = el.style.background || "";
@@ -60,6 +132,214 @@
     originalBackground = "";
   }
 
+  /**
+   * Minimal inline duplicate of the STRUCTURAL (string-level) checks
+   * validateGlslSource() / validateUniformManifest() / validateShaderDef()
+   * apply on the persist path in shared/shader-fills.ts, run here before any
+   * preview/live-edit GLSL reaches the WebGL compiler. Bridge files cannot
+   * import shared modules (see bridge.guard.spec.ts's no-import guard), so
+   * this duplicates the source-of-truth's rules instead of reusing them —
+   * keep in sync with shared/shader-fills.ts. Deliberately a SUBSET: it skips
+   * the cross-check that every manifest uniform is declared in the GLSL with
+   * the matching type (a knob-completeness nicety, not a GPU-hang/injection
+   * risk), since previews render even with unused/partial knobs.
+   *
+   * Script-tag handling also intentionally differs from a naive "reject both
+   * tags" rule, to stay in sync with shader script breakout hardening in
+   * shared/shader-fills.ts: an opening `<script` tag is a real injection
+   * vector (starts a brand new, arbitrary script), so it stays a hard
+   * rejection here too. A bare closing `</script` — e.g. inside a GLSL line
+   * comment — is NOT rejected here or on the persist path: escaping
+   * (escapeShaderScriptBreakout) happens only at persist-time serialization
+   * (serializeShaderScriptBlock), not here on the preview path, since preview
+   * GLSL never gets embedded in a `<script>` block in the first place.
+   */
+  var MAX_GLSL_LENGTH = 20000;
+  var UNIFORM_NAME_RE = /^u_[A-Za-z0-9_]{1,48}$/;
+  var SHADER_BUILTIN_UNIFORMS = ["u_time", "u_resolution"];
+
+  function validatePreviewGlslSource(glsl: unknown): string[] {
+    var errors: string[] = [];
+    if (typeof glsl !== "string" || glsl.trim().length === 0) {
+      return ["GLSL source is empty"];
+    }
+    if (glsl.length > MAX_GLSL_LENGTH) {
+      errors.push(
+        "GLSL source is " + glsl.length + " chars — max is " + MAX_GLSL_LENGTH,
+      );
+    }
+    if (!/void\s+main\s*\(/.test(glsl)) {
+      errors.push("GLSL source must define void main()");
+    }
+    if (!/gl_FragColor/.test(glsl)) {
+      errors.push("GLSL source must write gl_FragColor");
+    }
+    if (/<script/i.test(glsl)) {
+      errors.push("GLSL source must not contain an opening script tag");
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/.test(glsl)) {
+      errors.push("GLSL source contains control characters");
+    }
+    return errors;
+  }
+
+  function validatePreviewUniformManifest(uniforms: unknown): string[] {
+    var errors: string[] = [];
+    if (uniforms === undefined || uniforms === null) return errors;
+    if (typeof uniforms !== "object") {
+      return ["uniforms manifest must be an object"];
+    }
+    var manifest = uniforms as Record<string, unknown>;
+    var names = Object.keys(manifest);
+    if (names.length > 16) {
+      errors.push("too many uniforms (" + names.length + ") — max is 16");
+    }
+    for (var i = 0; i < names.length; i++) {
+      var name = names[i];
+      var def = manifest[name] as
+        | { type?: unknown; value?: unknown; min?: unknown; max?: unknown }
+        | undefined;
+      if (!UNIFORM_NAME_RE.test(name)) {
+        errors.push(
+          'uniform "' + name + '" must match u_[A-Za-z0-9_]+ (max 50 chars)',
+        );
+        continue;
+      }
+      if (SHADER_BUILTIN_UNIFORMS.indexOf(name) !== -1) {
+        errors.push(
+          'uniform "' + name + '" is a built-in provided by the runtime',
+        );
+        continue;
+      }
+      if (!def || typeof def !== "object") {
+        errors.push('uniform "' + name + '" definition must be an object');
+        continue;
+      }
+      if (def.type === "float") {
+        if (typeof def.value !== "number" || !isFinite(def.value as number)) {
+          errors.push('uniform "' + name + '" value must be a finite number');
+        }
+      } else if (def.type === "vec2") {
+        var v = def.value;
+        if (
+          !Array.isArray(v) ||
+          v.length !== 2 ||
+          typeof v[0] !== "number" ||
+          typeof v[1] !== "number" ||
+          !isFinite(v[0]) ||
+          !isFinite(v[1])
+        ) {
+          errors.push(
+            'uniform "' + name + '" value must be [x, y] finite numbers',
+          );
+        }
+      } else if (def.type === "color") {
+        if (
+          typeof def.value !== "string" ||
+          !/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(def.value)
+        ) {
+          errors.push(
+            'uniform "' + name + '" value must be a hex color like "#1a2b3c"',
+          );
+        }
+      } else {
+        errors.push(
+          'uniform "' + name + '" has unknown type — use float, vec2, or color',
+        );
+      }
+    }
+    return errors;
+  }
+
+  /**
+   * Full structural validation for a preview/live-edit shader def. Returns an
+   * empty array when valid. Mirrors validateShaderDef()'s string-level checks
+   * (see the comment above) without the GLSL↔manifest type cross-check.
+   */
+  function validatePreviewShaderDef(shader: {
+    id?: unknown;
+    name?: unknown;
+    glsl?: unknown;
+    uniforms?: unknown;
+  }): string[] {
+    var errors = validatePreviewGlslSource(shader.glsl);
+    errors = errors.concat(validatePreviewUniformManifest(shader.uniforms));
+    if (shader.name !== undefined) {
+      if (typeof shader.name !== "string" || shader.name.length > 80) {
+        errors.push("shader name must be a string ≤ 80 chars");
+      } else if (
+        shader.name.indexOf("*/") !== -1 ||
+        /<\/?script/i.test(shader.name)
+      ) {
+        errors.push("shader name contains forbidden sequences");
+      }
+    }
+    return errors;
+  }
+
+  function postShaderRejected(errors: string[]): void {
+    try {
+      window.parent.postMessage(
+        { type: "glsl-shader-preview-rejected", errors: errors },
+        "*",
+      );
+    } catch (_err) {}
+  }
+
+  // Local preview-mount bookkeeping — enforces the same cap the runtime uses
+  // (MAX_MOUNTS = 8 in shader-runtime.bridge.ts) independent of the
+  // runtime's own internal `mounts` array, which this bridge has no access
+  // to (no imports). Today's single-target glsl-shader-preview protocol only
+  // ever needs ONE live preview mount at a time (the runtime's own
+  // applyPreview() tears down any prior preview mount before creating a new
+  // one), so this counter is deliberately conservative: it counts every
+  // ACCEPTED preview request since the last explicit clear rather than
+  // trusting that every caller pairs each preview with one, so a
+  // hostile/misbehaving parent that fires many previews without ever
+  // clearing still gets capped at MAX_PREVIEW_MOUNTS instead of unbounded
+  // WebGL context churn.
+  var MAX_PREVIEW_MOUNTS = 8;
+  var acceptedPreviewCountSinceClear = 0;
+
+  /**
+   * The code-backed GLSL runtime (shader-runtime.bridge.ts) registers itself
+   * as window.__anShaders. It is injected immediately before this bridge in
+   * the editor, and embedded directly in persisted screen HTML. Everything
+   * here degrades to a no-op when it is missing.
+   */
+  interface AnShadersGlobal {
+    version: number;
+    scan: () => void;
+    applyPreview: (
+      target: { nodeId?: string; selector?: string },
+      def: {
+        id?: string;
+        name?: string;
+        glsl: string;
+        uniforms?: Record<string, unknown>;
+        values?: Record<string, unknown>;
+      },
+      mode?: string,
+    ) => boolean;
+    clearPreview: () => void;
+    setUniform: (
+      filter: { shaderId?: string; nodeId?: string; preview?: boolean },
+      name: string,
+      value: unknown,
+    ) => void;
+    updateShader: (
+      id: string,
+      patch: { glsl?: string; uniforms?: Record<string, unknown> },
+    ) => void;
+  }
+
+  function runtime(): AnShadersGlobal | null {
+    var api = (window as unknown as { __anShaders?: AnShadersGlobal })
+      .__anShaders;
+    return api && api.version >= 1 ? api : null;
+  }
+
   window.addEventListener("message", function (e: MessageEvent) {
     if (e.source !== window.parent) return;
     if (!e.data || typeof e.data.type !== "string") return;
@@ -74,5 +354,100 @@
       clearPreview();
       return;
     }
+    if (e.data.type === "glsl-shader-preview") {
+      var api = runtime();
+      if (!api) return;
+      var target =
+        e.data.target && typeof e.data.target === "object" ? e.data.target : {};
+      var shader =
+        e.data.shader && typeof e.data.shader === "object"
+          ? e.data.shader
+          : null;
+      if (!shader || typeof shader.glsl !== "string") return;
+      // Reject a hostile/broken shader BEFORE it ever reaches the WebGL
+      // compiler (GPU-hang risk from arbitrary postMessage GLSL) — same
+      // structural checks the persist path runs via validateShaderDef().
+      var validationErrors = validatePreviewShaderDef(shader);
+      if (validationErrors.length > 0) {
+        postShaderRejected(validationErrors);
+        return;
+      }
+      // Enforce the same mount cap the runtime uses (8), independent of the
+      // runtime's own bookkeeping — see acceptedPreviewCountSinceClear above.
+      if (acceptedPreviewCountSinceClear >= MAX_PREVIEW_MOUNTS) {
+        postShaderRejected([
+          "too many active shader previews — max is " + MAX_PREVIEW_MOUNTS,
+        ]);
+        return;
+      }
+      acceptedPreviewCountSinceClear += 1;
+      api.applyPreview(
+        { nodeId: target.nodeId, selector: target.selector },
+        {
+          id: shader.id,
+          name: shader.name,
+          glsl: shader.glsl,
+          uniforms: shader.uniforms,
+          values:
+            e.data.values && typeof e.data.values === "object"
+              ? e.data.values
+              : undefined,
+        },
+        e.data.mode === "effect" ? "effect" : "fill",
+      );
+      return;
+    }
+    if (e.data.type === "glsl-shader-set-uniform") {
+      var api2 = runtime();
+      if (!api2) return;
+      if (typeof e.data.name !== "string") return;
+      api2.setUniform(
+        e.data.filter && typeof e.data.filter === "object" ? e.data.filter : {},
+        e.data.name,
+        e.data.value,
+      );
+      return;
+    }
+    if (e.data.type === "glsl-shader-update") {
+      var api3 = runtime();
+      if (!api3) return;
+      if (typeof e.data.id !== "string") return;
+      // Same structural validation as glsl-shader-preview before hot-swapping
+      // a registered shader's live GLSL/manifest — glsl-shader-update allows
+      // a partial patch (e.g. uniforms-only), so only validate whichever
+      // parts are actually present in this message.
+      var updateErrors: string[] = [];
+      if (typeof e.data.glsl === "string") {
+        updateErrors = updateErrors.concat(
+          validatePreviewGlslSource(e.data.glsl),
+        );
+      }
+      updateErrors = updateErrors.concat(
+        validatePreviewUniformManifest(e.data.uniforms),
+      );
+      if (updateErrors.length > 0) {
+        postShaderRejected(updateErrors);
+        return;
+      }
+      api3.updateShader(e.data.id, {
+        glsl: typeof e.data.glsl === "string" ? e.data.glsl : undefined,
+        uniforms:
+          e.data.uniforms && typeof e.data.uniforms === "object"
+            ? e.data.uniforms
+            : undefined,
+      });
+      return;
+    }
+    if (e.data.type === "glsl-shader-preview-clear") {
+      var api4 = runtime();
+      if (api4) api4.clearPreview();
+      acceptedPreviewCountSinceClear = 0;
+      return;
+    }
+    if (e.data.type === "glsl-shader-rescan") {
+      var api5 = runtime();
+      if (api5) api5.scan();
+      return;
+    }
   });
 })();