symbiote-ui 0.3.0-alpha.52 → 0.3.0-alpha.53

package/CHANGELOG.md

@@ -2,10 +2,15 @@
 
 All notable changes to `symbiote-ui` will be documented in this file.
 
-## [0.3.0-alpha.52] - 2026-07-10
+## Unreleased
 
 ### Added
 
+- Added public `CanvasGraph.getViewport()` and `setViewport()` camera contracts
+  for clamped absolute live and deterministic viewport projection.
+- Added ordered v3 interaction-cue planning through
+  `createWebMcpTourTurnActionPlans`; presentation tools now consume cue bindings
+  directly and preserve strict tool input schemas.
 - Added bounded, cancellation-aware Media Studio frame-sequence playback,
   caption overlays, and external-clock timeline controls for synchronized
   audio, seek, pause, and resume workflows.
@@ -35,6 +40,9 @@ All notable changes to `symbiote-ui` will be documented in this file.
   `{ steps: [{ target, holdMs?, gesture?, label? }] }` scenarios with a host
   `resolveTarget`, per-step `onStep`, configurable `defaultHoldMs`, and
   `AbortSignal` support.
+- Added synchronous, seed-driven `presentAnnotationFrame` projection to the
+  presenter cursor so offline render workers can reproduce all marker and symbol
+  gestures without wall-clock or prior-frame state.
 - Added `actions` and `embed` custom-content message parts to `ChatMessageItem`
   and the message model: an `actions` part
   (`{ type: 'actions', actions: [{ id, label, icon, variant }] }`) renders inline
@@ -46,6 +54,8 @@ All notable changes to `symbiote-ui` will be documented in this file.
 
 ### Fixed
 
+- `registerWebMcpTool()` now forwards native registration options, including
+  `AbortSignal` and origin exposure, to `document.modelContext.registerTool()`.
 - Fixed cascade theme widget/editor slider rows staying stale or failing to
   apply range input after switching theme variants, and tuned the `classic`
   preset to sharp, no-outline chrome while keeping its lightness and chroma

package/canvas/CanvasGraph/CanvasGraph.js

@@ -69,9 +69,6 @@ const DEFAULT_MENU_ITEMS = Object.freeze([
 
 const INCREMENTAL_LAYOUT_INITIAL_ALPHA = 0.045;
 const SEEDED_LAYOUT_INITIAL_ALPHA = 0.22;
-const VISUAL_FOCUS_LAYOUT_INITIAL_ALPHA = 0.18;
-const CRYSTAL_FOCUS_LAYOUT_INITIAL_ALPHA = 0.07;
-const VISUAL_FOCUS_LAYOUT_PADDING = 8;
 const NODE_APPEARANCE_START_SCALE = 0.2;
 const ENTERING_LAYOUT_SIZE_SCALE = 0.18;
 const ENTERING_LAYOUT_SIZE_WARMUP_TICKS = 72;
@@ -674,7 +671,6 @@ export class CanvasGraph extends Symbiote {
   attributeChangedCallback(name, oldValue, newValue) {
     if (oldValue === newValue) return;
     if (name === 'active-node-scale' || name === 'info-panel-scale') {
-      this._restartWorkerForVisualFocus();
       this.needsDraw = true;
       this._wakeLoop?.();
       return;
@@ -1208,6 +1204,37 @@ export class CanvasGraph extends Symbiote {
     return true;
   }
 
+  getViewport() {
+    return {
+      zoom: this.zoom,
+      panX: this.panX,
+      panY: this.panY,
+    };
+  }
+
+  setViewport(viewport = {}) {
+    if (!Number.isFinite(viewport.zoom)
+      || !Number.isFinite(viewport.panX)
+      || !Number.isFinite(viewport.panY)) {
+      throw new TypeError('canvas-graph viewport requires finite zoom, panX, and panY');
+    }
+    let rect = this.canvas?.getBoundingClientRect?.();
+    let target = {
+      zoom: this._clampZoom(viewport.zoom, rect),
+      panX: viewport.panX,
+      panY: viewport.panY,
+      animate: viewport.animate === true,
+      viewportEase: viewport.viewportEase,
+    };
+    let applied = target.animate
+      ? this._applyViewportTarget(target)
+      : this._setViewportImmediate(target);
+    if (!applied) return false;
+    this.needsDraw = true;
+    this._wakeLoop();
+    return this.getViewport();
+  }
+
   _captureViewportState() {
     return {
       zoom: this.zoom,
@@ -1366,7 +1393,10 @@ export class CanvasGraph extends Symbiote {
       this._queueTransitionMarker(previousNode.id, node.id, options);
     }
     this.updateInteractionDepths();
-    if (isNewActivation) this._restartWorkerForVisualFocus();
+    if (isNewActivation) {
+      this.needsDraw = true;
+      this._wakeLoop();
+    }
     return true;
   }
 
@@ -2075,7 +2105,6 @@ export class CanvasGraph extends Symbiote {
         max: 4,
       });
     }
-    this._restartWorkerForVisualFocus();
     this.needsDraw = true;
     this._wakeLoop();
   }
@@ -2085,43 +2114,13 @@ export class CanvasGraph extends Symbiote {
     let height = node?.h;
     if (this.renderMode === 'dots') {
       const conns = this.adjMap.get(node.id)?.size || 0;
-      const isActiveLayoutNode = this.activeNode?.id === node.id;
-      const scale = isActiveLayoutNode ? this._resolveActiveNodeScale() : 1;
-      const radius = getNodeRadius(node, conns, { scale });
-      const layoutRadius = radius + (isActiveLayoutNode ? VISUAL_FOCUS_LAYOUT_PADDING : 0);
-      width = layoutRadius * 2;
-      height = layoutRadius * 2;
+      const radius = getNodeRadius(node, conns, { scale: 1 });
+      width = radius * 2;
+      height = radius * 2;
     }
     return { width, height };
   }
 
-  _getWorkerRestartOptions(options = {}) {
-    const baseOptions = this._lastWorkerOptions && typeof this._lastWorkerOptions === 'object'
-      ? { ...this._lastWorkerOptions }
-      : {};
-    return {
-      ...baseOptions,
-      activeGroupId: this.currentGroupId,
-      boundaryRadius: this.currentGroupId ? this.graphDB.nodes.get(this.currentGroupId)?.w / 2 : null,
-      attractors: baseOptions.attractors ?? null,
-      ...options,
-    };
-  }
-
-  _restartWorkerForVisualFocus() {
-    if (this._layoutSuspended || !this.worker || !this.nodes?.length || this.renderMode !== 'dots') return;
-    const baseAlpha = Number.isFinite(this._lastWorkerOptions?.initialAlpha)
-      ? this._lastWorkerOptions.initialAlpha
-      : 0;
-    const focusAlpha = this._usesCrystalForceLayout()
-      ? CRYSTAL_FOCUS_LAYOUT_INITIAL_ALPHA
-      : VISUAL_FOCUS_LAYOUT_INITIAL_ALPHA;
-    this.startWorker(this._getWorkerRestartOptions({
-      initialAlpha: Math.max(baseAlpha, focusAlpha),
-      crystalReseed: this._usesCrystalForceLayout(),
-    }));
-  }
-
   _queueNodeAppearances(nodeIds, options = {}) {
     if (!Array.isArray(nodeIds) || nodeIds.length === 0) return;
     let now = renderNow();
@@ -2451,7 +2450,7 @@ export class CanvasGraph extends Symbiote {
       nodeHeight: this.renderMode === 'dots' ? DOT_RADIUS * 2 : 40,
       mode: 'continuous',
       positionOrigin: this.renderMode === 'dots' ? 'center' : 'top-left',
-      activeVisualNodeId: this.renderMode === 'dots' ? this.activeNode?.id || null : null,
+      activeVisualNodeId: null,
       ...autoOptions,
       ...this._forceLayoutOverrides,
       ...(customOptions || {}),

package/canvas/graph-explorer.js

@@ -1,5 +1,16 @@
 export const GRAPH_PATH_STYLES = ['pcb', 'bezier', 'orthogonal', 'straight'];
 export const GRAPH_VIEW_MODES = ['structured', 'flat'];
+export const GRAPH_PATH_STYLE_MENU_GROUP = Object.freeze({
+  group: 'path',
+  groupLabel: 'Connections',
+  groupOrder: 20,
+});
+export const GRAPH_PATH_STYLE_MENU_ITEMS = Object.freeze({
+  pcb: Object.freeze({ label: 'Routed', icon: 'route' }),
+  orthogonal: Object.freeze({ label: 'Right angles', icon: 'account_tree' }),
+  bezier: Object.freeze({ label: 'Curved', icon: 'gesture' }),
+  straight: Object.freeze({ label: 'Straight', icon: 'trending_flat' }),
+});
 
 export const GRAPH_DIRECTORY_FRAME_COLORS = [
   'var(--sn-graph-cluster-0)',
@@ -22,6 +33,43 @@ export function normalizeGraphExplorerViewMode(mode) {
 
 export const normalizeGraphViewMode = normalizeGraphExplorerViewMode;
 
+function supportsGraphPathStyleMenuActions(mode) {
+  return mode === 'structured';
+}
+
+export function resolveGraphPathStyleAction(actionId) {
+  const id = String(actionId || '');
+  if (!id.startsWith('path:')) return '';
+  const style = id.slice('path:'.length);
+  return GRAPH_PATH_STYLES.includes(style) ? style : '';
+}
+
+export function createGraphPathStyleMenuActions({
+  mode = 'structured',
+  pathStyle = 'pcb',
+  labels = {},
+  titles = {},
+  group = GRAPH_PATH_STYLE_MENU_GROUP.group,
+  groupLabel = GRAPH_PATH_STYLE_MENU_GROUP.groupLabel,
+  groupOrder = GRAPH_PATH_STYLE_MENU_GROUP.groupOrder,
+} = {}) {
+  if (!supportsGraphPathStyleMenuActions(mode)) return [];
+  return GRAPH_PATH_STYLES.map((style) => {
+    const item = GRAPH_PATH_STYLE_MENU_ITEMS[style] || {};
+    const label = labels[style] || item.label || style;
+    return {
+      id: `path:${style}`,
+      label,
+      icon: item.icon || 'route',
+      title: titles[style] || `Use ${label} connection paths`,
+      group,
+      groupLabel,
+      groupOrder,
+      active: style === pathStyle,
+    };
+  });
+}
+
 function scheduleGraphExplorerFrame(callback) {
   if (typeof requestAnimationFrame === 'function') {
     requestAnimationFrame(callback);
@@ -346,6 +394,21 @@ export function createGraphExplorerViewController({
       return api;
     },
 
+    getPathStyleMenuActions(options = {}) {
+      return createGraphPathStyleMenuActions({
+        ...options,
+        mode: state.mode,
+        pathStyle: state.pathStyle,
+      });
+    },
+
+    runPathStyleMenuAction(actionId) {
+      const style = resolveGraphPathStyleAction(actionId);
+      if (!style || state.mode !== 'structured') return false;
+      api.setPathStyle(style);
+      return true;
+    },
+
     fitView({ structuredArgs = [], flatArgs = [] } = {}) {
       if (state.mode === 'flat') {
         state.flatGraph?.fitView?.(...flatArgs);

package/canvas/index.js

@@ -36,11 +36,14 @@ export {
 } from './CanvasGraph/CanvasGraphViewport.js';
 export {
   GRAPH_DIRECTORY_FRAME_COLORS,
+  GRAPH_PATH_STYLE_MENU_GROUP,
+  GRAPH_PATH_STYLE_MENU_ITEMS,
   GRAPH_PATH_STYLES,
   GRAPH_VIEW_MODES,
   addGraphDirectoryFrames,
   applyGraphExplorerViewMode,
   buildFlatPathHash,
+  createGraphPathStyleMenuActions,
   createGraphExplorerViewController,
   createGraphViewModeController,
   getFileSelectionNodeId,
@@ -52,6 +55,7 @@ export {
   normalizeGraphViewMode,
   renderGraphPathStyleButton,
   renderGraphViewModeButton,
+  resolveGraphPathStyleAction,
   resolveFlatHashChange,
   resolveInitialGraphViewMode,
   selectGraphLabelMode,

package/chat/presenter-cursor.js

@@ -17,6 +17,9 @@
  * same deterministic move counter as the travel arc, so runs differ yet stay
  * reproducible without `Math.random`. A faint, themed ink trail traces under the
  * cursor so the flourish reads, then fades.
+ * `presentAnnotationFrame` projects those same paths synchronously from explicit
+ * progress and seed values. It uses no animation frame, timer, or prior cursor
+ * position, so offline render workers can reproduce any frame independently.
  *
  * `clickElement(el)` is the native-control gesture: the cursor travels to a real
  * button/tab/control, pulses a click target ring, and then calls the element's
@@ -148,6 +151,7 @@ const TRAVEL_PX_PER_MS = 0.75; // longer hops take a little more time
 const GESTURE_MS = 720; // base duration of a single gesture pass
 const GESTURE_JITTER_PX = 2.4; // peak per-frame hand-tremor amplitude
 const INK_FADE_MS = 520; // how long the ink trail lingers before it clears
+const DETERMINISTIC_GESTURE_STEPS = 96;
 
 const DEFAULT_HOLD_MS = 1200;
 
@@ -887,6 +891,9 @@ function inertCursor() {
         } catch (_) {}
       }
     },
+    presentAnnotationFrame() {
+      return { presented: false, reason: 'unsupported' };
+    },
     clear() {},
     dispose() {},
     isSupported() {
@@ -903,7 +910,7 @@ function inertCursor() {
  * env this returns inert no-ops and `isSupported()` is false.
  *
  * @param {Document} [doc] - document to render into (defaults to the global one).
- * @returns {{ moveTo: (el: Element, opts?: object) => void, markElement: (el: Element, opts?: object) => void, annotateElement: (el: Element, opts?: object) => void, clickElement: (el: Element, opts?: object) => void, clear: () => void, dispose: () => void, isSupported: () => boolean }}
+ * @returns {{ moveTo: (el: Element, opts?: object) => void, markElement: (el: Element, opts?: object) => void, annotateElement: (el: Element, opts?: object) => void, presentAnnotationFrame: (el: Element, annotation: object, frame: object) => object, clickElement: (el: Element, opts?: object) => void, clear: () => void, dispose: () => void, isSupported: () => boolean }}
  */
 export function createPresenterCursor(doc = typeof document !== 'undefined' ? document : null) {
   if (!hasDocument(doc)) return inertCursor();
@@ -1456,6 +1463,93 @@ export function createPresenterCursor(doc = typeof document !== 'undefined' ? do
     }
   }
 
+  function presentAnnotationFrame(el, value, frame = {}) {
+    if (disposed) return { presented: false, reason: 'disposed' };
+    let annotation = normalizePresenterAnnotation(value);
+    if (!annotation) {
+      clear();
+      return { presented: false, reason: 'invalid-annotation' };
+    }
+    if (!el || typeof el.getBoundingClientRect !== 'function') {
+      clear();
+      return { presented: false, reason: 'invalid-target' };
+    }
+    let viewport = {
+      width: win?.innerWidth || doc.documentElement?.clientWidth || 0,
+      height: win?.innerHeight || doc.documentElement?.clientHeight || 0,
+    };
+    let rect = resolvePresenterVisibleRect(el, viewport);
+    if (!rect) {
+      clear();
+      return { presented: false, reason: 'hidden-target' };
+    }
+    let progress = Math.max(0, Math.min(1, Number(frame.progress) || 0));
+    let seed = Number(frame.seed);
+    if (!Number.isFinite(seed)) seed = 0;
+    let drawRect = annotationRectFor(rect, viewport, annotation);
+    let factory = annotation.kind === 'symbol'
+      ? SYMBOLS[annotation.symbol]
+      : GESTURES[annotation.marker];
+    let options = annotation.kind === 'symbol' ? { placement: annotation.placement } : {};
+    let plan = factory?.(drawRect, seed, options);
+    if (!plan || typeof plan.point !== 'function') {
+      clear();
+      return { presented: false, reason: 'unsupported-annotation' };
+    }
+
+    cancelTravel();
+    cancelDrag();
+    cancelGesture();
+    cancelClick();
+    overlay.classList.remove('is-paused');
+    overlay.classList.add('is-visible');
+    hideMarqueeFrame();
+
+    let pointCount = progress > 0
+      ? Math.max(2, Math.floor(progress * DETERMINISTIC_GESTURE_STEPS) + 1)
+      : 0;
+    let points = [];
+    let amp = GESTURE_JITTER_PX * (0.85 + (variation(seed, 31) * 0.5 + 0.5) * 0.4);
+    for (let index = 0; index < pointCount; index += 1) {
+      let t = Math.min(1, index / DETERMINISTIC_GESTURE_STEPS);
+      let eased = easeInOutCubic(t);
+      let ideal = plan.point(eased);
+      let fade = 1 - eased * eased;
+      points.push({
+        x: ideal.x + jitter(seed, eased, amp, 0) * fade,
+        y: ideal.y + jitter(seed, eased, amp, 1) * fade,
+      });
+    }
+    let path = points.length >= 2
+      ? points.reduce((d, point, index) => `${d}${index ? 'L' : 'M'}${point.x.toFixed(1)} ${point.y.toFixed(1)}`, '')
+      : '';
+    inkPath.setAttribute('d', path);
+    ink.classList.toggle('is-inking', Boolean(path));
+    let startIdeal = plan.point(0);
+    let startPoint = {
+      x: startIdeal.x + jitter(seed, 0, amp, 0),
+      y: startIdeal.y + jitter(seed, 0, amp, 1),
+    };
+    let cursorPoint = progress >= 1 ? (plan.rest || plan.point(1)) : (points.at(-1) || startPoint);
+    setCursor(cursorPoint.x, cursorPoint.y);
+    let pathDigest = 2166136261;
+    for (let index = 0; index < path.length; index += 1) {
+      pathDigest ^= path.charCodeAt(index);
+      pathDigest = Math.imul(pathDigest, 16777619);
+    }
+    return {
+      presented: true,
+      kind: annotation.kind,
+      name: annotation.marker || annotation.symbol,
+      progress,
+      seed,
+      rect: drawRect,
+      cursor: cursorPoint,
+      pathPoints: points.length,
+      pathDigest: (pathDigest >>> 0).toString(16).padStart(8, '0'),
+    };
+  }
+
   function clear() {
     if (disposed) return;
     cancelTravel();
@@ -1483,6 +1577,7 @@ export function createPresenterCursor(doc = typeof document !== 'undefined' ? do
     moveTo,
     markElement,
     annotateElement,
+    presentAnnotationFrame,
     clickElement,
     clear,
     dispose,

package/custom-elements.json

@@ -234,7 +234,7 @@
           "name": "CanvasGraph",
           "tagName": "canvas-graph",
           "description": "Generic hierarchical graph overview/read renderer with force layout, semantic navigation, selection events, and optional device-orientation parallax.",
-          "componentDescription": "Generic hierarchical graph overview/read renderer with force layout, semantic navigation, selection events, and optional device-orientation parallax. Use this interactive visual graph surface when composing canvas UI. Capabilities: hierarchical-graph, overview-read-renderer, force-layout, semantic-clusters, focus-selection, layout-snapshot, device-orientation-parallax. Data ownership: host-owned model; component renders and emits intent events. WebMCP tools: canvas_graph_set_model, canvas_graph_focus_node, canvas_graph_focus_nodes, canvas_graph_set_path.",
+          "componentDescription": "Generic hierarchical graph overview/read renderer with force layout, semantic navigation, selection events, and optional device-orientation parallax. Use this interactive visual graph surface when composing canvas UI. Capabilities: hierarchical-graph, overview-read-renderer, force-layout, semantic-clusters, focus-selection, layout-snapshot, viewport-control, device-orientation-parallax. Data ownership: host-owned model; component renders and emits intent events. WebMCP tools: canvas_graph_set_model, canvas_graph_focus_node, canvas_graph_focus_nodes, canvas_graph_set_path.",
           "attributes": [
             {
               "name": "active-node-scale",
@@ -376,6 +376,16 @@
               "name": "fitView",
               "description": "Fits the visible graph into the canvas viewport; accepts optional viewportEase for live replay tracking."
             },
+            {
+              "kind": "method",
+              "name": "getViewport",
+              "description": "Returns the current zoom and pan viewport as a portable snapshot."
+            },
+            {
+              "kind": "method",
+              "name": "setViewport",
+              "description": "Applies an absolute, clamped zoom and pan viewport immediately or through the graph camera easing loop."
+            },
             {
               "kind": "method",
               "name": "setVisualOptions",
@@ -1049,7 +1059,7 @@
             }
           },
           "agent": {
-            "componentDescription": "Generic hierarchical graph overview/read renderer with force layout, semantic navigation, selection events, and optional device-orientation parallax. Use this interactive visual graph surface when composing canvas UI. Capabilities: hierarchical-graph, overview-read-renderer, force-layout, semantic-clusters, focus-selection, layout-snapshot, device-orientation-parallax. Data ownership: host-owned model; component renders and emits intent events. WebMCP tools: canvas_graph_set_model, canvas_graph_focus_node, canvas_graph_focus_nodes, canvas_graph_set_path.",
+            "componentDescription": "Generic hierarchical graph overview/read renderer with force layout, semantic navigation, selection events, and optional device-orientation parallax. Use this interactive visual graph surface when composing canvas UI. Capabilities: hierarchical-graph, overview-read-renderer, force-layout, semantic-clusters, focus-selection, layout-snapshot, viewport-control, device-orientation-parallax. Data ownership: host-owned model; component renders and emits intent events. WebMCP tools: canvas_graph_set_model, canvas_graph_focus_node, canvas_graph_focus_nodes, canvas_graph_set_path.",
             "semanticRole": "interactive visual graph surface",
             "usage": "Render or compose <canvas-graph> when the host needs generic hierarchical graph overview/read renderer with force layout, semantic navigation, selection events, and optional device-orientation parallax.",
             "dataOwnership": "host-owned model; component renders and emits intent events",
@@ -29623,7 +29633,7 @@
           "name": "CellBg",
           "tagName": "cell-bg",
           "description": "Animated cellular automaton background effect.",
-          "componentDescription": "Animated cellular automaton background effect. Use this effects UI component when composing effects UI. Capabilities: animated-background, canvas-effect, activity-trigger, smooth-start, smooth-stop, pulse, resize-aware, reduced-motion-friendly, layout-lifecycle. Data ownership: host-owned props and attributes; component owns presentation state. WebMCP tools: cell_bg_trigger, cell_bg_start, cell_bg_stop.",
+          "componentDescription": "Animated cellular automaton background effect. Use this effects UI component when composing effects UI. Capabilities: animated-background, canvas-effect, activity-trigger, smooth-start, smooth-stop, pulse, resize-aware, reduced-motion-friendly, layout-lifecycle, deterministic-render. Data ownership: host-owned props and attributes; component owns presentation state. WebMCP tools: cell_bg_trigger, cell_bg_start, cell_bg_stop.",
           "attributes": [
             {
               "name": "active",
@@ -29645,6 +29655,13 @@
                 "text": "number"
               },
               "description": "Default timed pulse duration in milliseconds."
+            },
+            {
+              "name": "seed",
+              "type": {
+                "text": "string"
+              },
+              "description": "Stable seed used by deterministic external-frame rendering."
             }
           ],
           "members": [
@@ -29716,6 +29733,21 @@
               "kind": "method",
               "name": "resumeLayout",
               "description": "Restores persistent animation only when it was active before layout suspension."
+            },
+            {
+              "kind": "method",
+              "name": "setFrameDriver",
+              "description": "Selects self-driven live animation or externally driven deterministic rendering."
+            },
+            {
+              "kind": "method",
+              "name": "presentFrame",
+              "description": "Synchronously paints the current shared render-clock time."
+            },
+            {
+              "kind": "method",
+              "name": "getFramePresentation",
+              "description": "Returns deterministic frame metrics and the current grid hash."
             }
           ],
           "events": [
@@ -30084,7 +30116,7 @@
             }
           },
           "agent": {
-            "componentDescription": "Animated cellular automaton background effect. Use this effects UI component when composing effects UI. Capabilities: animated-background, canvas-effect, activity-trigger, smooth-start, smooth-stop, pulse, resize-aware, reduced-motion-friendly, layout-lifecycle. Data ownership: host-owned props and attributes; component owns presentation state. WebMCP tools: cell_bg_trigger, cell_bg_start, cell_bg_stop.",
+            "componentDescription": "Animated cellular automaton background effect. Use this effects UI component when composing effects UI. Capabilities: animated-background, canvas-effect, activity-trigger, smooth-start, smooth-stop, pulse, resize-aware, reduced-motion-friendly, layout-lifecycle, deterministic-render. Data ownership: host-owned props and attributes; component owns presentation state. WebMCP tools: cell_bg_trigger, cell_bg_start, cell_bg_stop.",
             "semanticRole": "effects UI component",
             "usage": "Render or compose <cell-bg> when the host needs animated cellular automaton background effect.",
             "dataOwnership": "host-owned props and attributes; component owns presentation state",

package/docs/runtime-ui-construction.md

@@ -136,6 +136,11 @@ changing the host-owned graph model.
 Use `fitNodes(ids, { viewportEase })` or `fitView({ viewportEase })` when a
 live replay should track a changing area of interest with a slower camera path
 than ordinary user-initiated focus.
+Use `getViewport()` to capture the current `{ zoom, panX, panY }` camera and
+`setViewport({ zoom, panX, panY, animate })` to restore or project an absolute
+camera state. `setViewport()` clamps zoom through the graph's normal viewport
+rules and cancels stale immediate-camera targets, so deterministic replay must
+prefer it over writing graph fields directly.
 During incremental model growth, `canvas-graph` seeds entering node positions
 near linked visible nodes, starts them with a small effective collision size,
 and restarts the force layout with low initial heat, so live process replay can

package/effects/CellBg/CellBg.js

@@ -2,6 +2,13 @@ import Symbiote from '@symbiotejs/symbiote';
 import template from './CellBg.tpl.js';
 import css from './CellBg.css.js';
 import { CELL_BG_DEFAULTS, readCellBgTheme } from './cell-bg-theme.js';
+import { renderNow } from '../../core/render-clock.js';
+import {
+  cellBgRenderFrame,
+  cellBgRenderHash,
+  createCellBgRenderState,
+  seekCellBgRenderState,
+} from './cell-bg-render-state.js';
 
 /**
  * Cellular Automaton Background Component
@@ -17,13 +24,21 @@ import { CELL_BG_DEFAULTS, readCellBgTheme } from './cell-bg-theme.js';
 const RULE_B = [3];
 const RULE_S = [2, 3];
 const PALETTE_SIZE = CELL_BG_DEFAULTS.paletteSize;
-const now = () => globalThis.performance?.now?.() ?? Date.now();
+const now = () => renderNow();
 const requestFrame = (callback) => {
   if (typeof globalThis.requestAnimationFrame === 'function') {
     return globalThis.requestAnimationFrame(callback);
   }
   return setTimeout(() => callback(now()), 16);
 };
+const cancelFrame = (handle) => {
+  if (handle === null || handle === undefined) return;
+  if (typeof globalThis.cancelAnimationFrame === 'function') {
+    globalThis.cancelAnimationFrame(handle);
+  } else {
+    clearTimeout(handle);
+  }
+};
 const getReducedMotionQuery = () => globalThis.matchMedia?.('(prefers-reduced-motion: reduce)') || null;
 
 function normalizeCssColor(source, value) {
@@ -89,7 +104,7 @@ function readCssNumber(source, token, fallback) {
 
 export class CellBg extends Symbiote {
   static get observedAttributes() {
-    return ['active', 'auto-trigger', 'pulse-duration'];
+    return ['active', 'auto-trigger', 'pulse-duration', 'seed'];
   }
 
   init$ = {
@@ -112,6 +127,10 @@ export class CellBg extends Symbiote {
     this._prefersReducedMotion = Boolean(this._motionQuery?.matches);
     this._motionChangeHandler = (event) => {
       this._prefersReducedMotion = Boolean(event.matches);
+      if (this._externalFrameDrive) {
+        this.presentFrame();
+        return;
+      }
       if (this._prefersReducedMotion) {
         if (this._pulseTimer) clearTimeout(this._pulseTimer);
         this._pulseTimer = null;
@@ -137,6 +156,11 @@ export class CellBg extends Symbiote {
     this.lastTime = now();
     this.isAnimating = false;
     this._stagnantCount = 0;
+    this._frameRequest = null;
+    this._externalFrameDrive = false;
+    this._externalRenderState = null;
+    this._externalRenderFrame = null;
+    this._externalRestoreState = null;
 
     // We only redraw on rAF if running, or if a single frame is needed after resize
     this.resize = this.resize.bind(this);
@@ -146,6 +170,7 @@ export class CellBg extends Symbiote {
     // Debounce: resize canvas immediately (prevents flash), pulse only after settle
     const onResize = () => {
       this.resize();
+      if (this._externalFrameDrive) return;
       if (this._resizeDebounce) clearTimeout(this._resizeDebounce);
       this._resizeDebounce = setTimeout(() => {
         this._resizeDebounce = null;
@@ -194,6 +219,9 @@ export class CellBg extends Symbiote {
       this.$.autoTrigger = this._readAutoTriggerAttribute();
     } else if (name === 'pulse-duration') {
       this.$.pulseDuration = this._readPulseDurationAttribute();
+    } else if (name === 'seed' && this._externalFrameDrive) {
+      this._externalRenderState = null;
+      this.presentFrame();
     }
   }
 
@@ -204,6 +232,10 @@ export class CellBg extends Symbiote {
    */
   toggle(state) {
     let next = !!state;
+    if (this._externalFrameDrive) {
+      this._recordExternalPersistent(next);
+      return;
+    }
     if (this.$.active !== next) {
       this.$.active = next;
       return;
@@ -211,7 +243,113 @@ export class CellBg extends Symbiote {
     this._setPersistent(next);
   }
 
+  setFrameDriver(mode = 'self') {
+    let nextMode = String(mode || 'self').trim().toLowerCase();
+    if (nextMode !== 'self' && nextMode !== 'external') {
+      throw new TypeError('CellBg frame driver must be self or external');
+    }
+    if (nextMode === 'external') {
+      if (!this._externalFrameDrive) {
+        this._externalRestoreState = {
+          toggled: Boolean(this._toggled),
+          active: Boolean(this.$?.active),
+          running: Boolean(this.running),
+        };
+      }
+      this._externalFrameDrive = true;
+      this.running = false;
+      this.isAnimating = false;
+      this.currentSpeed = 0;
+      if (this._frameRequest !== null) cancelFrame(this._frameRequest);
+      this._frameRequest = null;
+      if (this._pulseTimer) clearTimeout(this._pulseTimer);
+      if (this._resizeDebounce) clearTimeout(this._resizeDebounce);
+      this._pulseTimer = null;
+      this._resizeDebounce = null;
+      this._externalRenderState = null;
+      this.resize();
+      return 'external';
+    }
+
+    if (!this._externalFrameDrive) return 'self';
+    let restore = this._externalRestoreState || {};
+    if (this._externalRenderFrame) {
+      this.grid = new Uint8Array(this._externalRenderFrame.grid);
+      this.radii = new Float32Array(this._externalRenderFrame.radii);
+    }
+    this._externalFrameDrive = false;
+    this._externalRenderState = null;
+    this._externalRenderFrame = null;
+    this._externalRestoreState = null;
+    this._toggled = Boolean(restore.toggled);
+    this.$.active = Boolean(restore.active);
+    this.running = false;
+    this.isAnimating = false;
+    this.currentSpeed = 0;
+    this.lastTime = now();
+    if (restore.running || restore.toggled || restore.active) this._start('frame-driver-restore');
+    else this._draw();
+    return 'self';
+  }
+
+  presentFrame() {
+    if (!this._available) return false;
+    this.resize();
+    if (!this.canvas?._w || !this.canvas?._h) return false;
+    if (!this._externalFrameDrive) {
+      this._draw();
+      return true;
+    }
+    let options = this._externalRenderOptions();
+    this._externalRenderState = seekCellBgRenderState(this._externalRenderState, now(), options);
+    this._externalRenderFrame = cellBgRenderFrame(this._externalRenderState);
+    this._draw(this._externalRenderFrame);
+    return true;
+  }
+
+  getFramePresentation() {
+    if (!this._externalRenderState || !this._externalRenderFrame) return null;
+    return {
+      seed: this._externalRenderState.seed,
+      width: this.canvas?._w || 0,
+      height: this.canvas?._h || 0,
+      cols: this._externalRenderState.cols,
+      rows: this._externalRenderState.rows,
+      cellSize: this._cellSize,
+      stepMs: this._externalRenderState.stepMs,
+      stepIndex: this._externalRenderState.stepIndex,
+      timeMs: this._externalRenderState.timeMs,
+      gridHash: cellBgRenderHash(this._externalRenderState, this._externalRenderFrame),
+      activity: 'continuous',
+      reducedMotion: false,
+    };
+  }
+
+  _externalRenderOptions() {
+    return {
+      seed: this.getAttribute('seed') || 'symbiote-cell-bg',
+      cols: this.cols,
+      rows: this.rows,
+      stepMs: this._stepMs,
+      minRadius: this._minRadius,
+      maxRadius: this._maxRadius,
+      fadeRate: this._fadeRate,
+    };
+  }
+
+  _recordExternalPersistent(state) {
+    if (!this._externalRestoreState) return;
+    let active = Boolean(state);
+    this._externalRestoreState.toggled = active;
+    this._externalRestoreState.active = active;
+    this._externalRestoreState.running = active;
+  }
+
   _setPersistent(state) {
+    if (this._externalFrameDrive) {
+      this._recordExternalPersistent(state);
+      return;
+    }
     this._toggled = !!state;
     if (state && this._pulseTimer) {
       clearTimeout(this._pulseTimer);
@@ -240,6 +378,10 @@ export class CellBg extends Symbiote {
    * Stop persistent or timed animation with smooth deceleration.
    */
   stop() {
+    if (this._externalFrameDrive) {
+      this._recordExternalPersistent(false);
+      return;
+    }
     if (this._pulseTimer) clearTimeout(this._pulseTimer);
     this._pulseTimer = null;
     this._toggled = false;
@@ -252,6 +394,7 @@ export class CellBg extends Symbiote {
   }
 
   suspendLayout({ reason = 'layout-suspend' } = {}) {
+    if (this._externalFrameDrive) return;
     this._resumePersistentAfterSuspend = Boolean(this._toggled || this.$.active);
     if (this._pulseTimer) clearTimeout(this._pulseTimer);
     this._pulseTimer = null;
@@ -276,6 +419,7 @@ export class CellBg extends Symbiote {
   }
 
   resumeLayout() {
+    if (this._externalFrameDrive) return;
     if (this._resumePersistentAfterSuspend) this.start();
     this._resumePersistentAfterSuspend = false;
   }
@@ -287,6 +431,7 @@ export class CellBg extends Symbiote {
    * @param {number} [duration=10000]
    */
   pulse(duration = 10000) {
+    if (this._externalFrameDrive) return;
     if (this._toggled) return; // Already running persistently
     let safeDuration = this._normalizePulseDuration(duration);
     if (this._prefersReducedMotion) {
@@ -321,6 +466,8 @@ export class CellBg extends Symbiote {
     if (this._resizeDebounce) clearTimeout(this._resizeDebounce);
     this._pulseTimer = null;
     this._resizeDebounce = null;
+    if (this._frameRequest !== null) cancelFrame(this._frameRequest);
+    this._frameRequest = null;
     this._themeObserver?.disconnect();
     this.ownerDocument?.removeEventListener?.('cascade-theme-change', this._themeChangeHandler);
     if (typeof this._motionQuery?.removeEventListener === 'function') {
@@ -336,13 +483,18 @@ export class CellBg extends Symbiote {
     let previousCellSize = this._cellSize;
     let previousMinRadius = this._minRadius;
     let previousMaxRadius = this._maxRadius;
+    let previousStepMs = this._stepMs;
+    let previousFadeRate = this._fadeRate;
     this._buildPalette();
 
     let geometryChanged = previousCellSize !== this._cellSize
       || previousMinRadius !== this._minRadius
-      || previousMaxRadius !== this._maxRadius;
+      || previousMaxRadius !== this._maxRadius
+      || previousStepMs !== this._stepMs
+      || previousFadeRate !== this._fadeRate;
     if (geometryChanged) {
-      this.resize();
+      if (this._externalFrameDrive) this._externalRenderState = null;
+      this.resize({ force: true });
     } else {
       this._draw();
     }
@@ -350,6 +502,10 @@ export class CellBg extends Symbiote {
   }
 
   _scheduleThemeRefresh() {
+    if (this._externalFrameDrive) {
+      this.refreshTheme({ pulse: false });
+      return;
+    }
     if (this._themeRefreshQueued) return;
     this._themeRefreshQueued = true;
     requestFrame(() => {
@@ -381,6 +537,7 @@ export class CellBg extends Symbiote {
   }
 
   _triggerIfEnabled() {
+    if (this._externalFrameDrive) return;
     if (this.$.autoTrigger === false) return;
     this.trigger(this.$.pulseDuration);
   }
@@ -402,7 +559,7 @@ export class CellBg extends Symbiote {
     return theme;
   }
 
-  resize() {
+  resize({ force = false } = {}) {
     if (!this._available || !this.canvas.parentElement) return;
     let dpr = globalThis.devicePixelRatio || 1;
     let w = this.canvas.parentElement.clientWidth;
@@ -410,6 +567,9 @@ export class CellBg extends Symbiote {
 
     if (w === 0 || h === 0) return; // Hidden or not attached
 
+    let sameSize = this.canvas._w === w && this.canvas._h === h;
+    if (sameSize && !force && (!this._externalFrameDrive || this._externalRenderState)) return;
+
     this.canvas.width = w * dpr;
     this.canvas.height = h * dpr;
     this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
@@ -428,6 +588,16 @@ export class CellBg extends Symbiote {
     this.cols = Math.ceil(w / this._cellSize) + 1;
     this.rows = Math.ceil(h / this._cellSize) + 1;
 
+    if (this._externalFrameDrive) {
+      this.grid = new Uint8Array(this.cols * this.rows);
+      this.radii = new Float32Array(this.cols * this.rows);
+      this.radii.fill(this._minRadius);
+      this._externalRenderState = createCellBgRenderState(this._externalRenderOptions());
+      this._externalRenderFrame = cellBgRenderFrame(this._externalRenderState);
+      this._draw(this._externalRenderFrame);
+      return;
+    }
+
     this.grid = new Uint8Array(this.cols * this.rows);
     this.radii = new Float32Array(this.cols * this.rows);
     this.radii.fill(this._minRadius);
@@ -460,6 +630,7 @@ export class CellBg extends Symbiote {
   }
 
   _start(reason = 'manual') {
+    if (this._externalFrameDrive) return;
     if (!this._available) return;
     if (this.running) return;
     this.running = true;
@@ -471,11 +642,12 @@ export class CellBg extends Symbiote {
     if (!this.isAnimating) {
       this.lastTime = now();
       this.isAnimating = true;
-      requestFrame(this.renderLoop);
+      this._scheduleFrame();
     }
   }
 
   _stop(reason = 'manual') {
+    if (this._externalFrameDrive) return;
     if (!this.running) return;
     this.running = false;
     this.dispatchEvent(new CustomEvent('cell-bg-animation-stop', {
@@ -486,6 +658,11 @@ export class CellBg extends Symbiote {
     // Loop will smoothly decelerate and stop in renderLoop
   }
 
+  _scheduleFrame() {
+    if (this._externalFrameDrive || this._frameRequest !== null) return;
+    this._frameRequest = requestFrame(this.renderLoop);
+  }
+
   _step() {
     if (!this.cols || !this.rows) return;
     let len = this.cols * this.rows;
@@ -551,6 +728,8 @@ export class CellBg extends Symbiote {
   }
 
   renderLoop(ts) {
+    this._frameRequest = null;
+    if (this._externalFrameDrive) return;
     if (!this.isAnimating) return;
 
     let time = now();
@@ -559,7 +738,8 @@ export class CellBg extends Symbiote {
 
     // Smoothly accelerate/decelerate
     let targetSpeed = this.running ? 1.0 : 0.0;
-    this.currentSpeed += (targetSpeed - this.currentSpeed) * 0.03; // Smooth transition factor
+    let speedBlend = 1 - Math.pow(1 - 0.03, dt / (1000 / 60));
+    this.currentSpeed += (targetSpeed - this.currentSpeed) * speedBlend;
 
     // If we're fully stopped and radii have faded (we just wait for speed to drop near 0)
     if (!this.running && this.currentSpeed < 0.005) {
@@ -582,17 +762,29 @@ export class CellBg extends Symbiote {
       maxSteps--;
     }
 
+    this._advanceLiveRadii(dt);
     this._draw();
 
     if (this.isAnimating) {
-      requestFrame(this.renderLoop);
+      this._scheduleFrame();
+    }
+  }
+
+  _advanceLiveRadii(elapsedMs) {
+    let frames = Math.max(0, Number(elapsedMs) || 0) / (1000 / 60);
+    for (let index = 0; index < this.radii.length; index += 1) {
+      let alive = this.grid[index] === 1;
+      let target = alive ? this._maxRadius : this._minRadius;
+      let factor = alive ? 0.2 : this._fadeRate;
+      this.radii[index] = target + (this.radii[index] - target) * Math.pow(1 - factor, frames);
     }
   }
 
-  _draw() {
+  _draw(frame = null) {
     if (!this._available || !this.canvas._w) return;
     let w = this.canvas._w;
     let h = this.canvas._h;
+    let radii = frame?.radii || this.radii;
 
     this.ctx.clearRect(0, 0, w, h);
     this.ctx.fillStyle = this._bgFill;
@@ -603,18 +795,7 @@ export class CellBg extends Symbiote {
     for (let y = 0; y < this.rows; y++) {
       for (let x = 0; x < this.cols; x++) {
         let idx = y * this.cols + x;
-        let alive = this.grid[idx];
-
-        let targetR = alive ? this._maxRadius : this._minRadius;
-        let currentR = this.radii[idx];
-
-        if (alive) {
-          this.radii[idx] = currentR + (targetR - currentR) * 0.2;
-        } else {
-          this.radii[idx] = currentR + (targetR - currentR) * this._fadeRate;
-        }
-
-        let r = this.radii[idx];
+        let r = radii[idx];
         let cx = x * this._cellSize;
         let cy = y * this._cellSize;
 

package/effects/CellBg/cell-bg-render-state.js

@@ -0,0 +1,155 @@
+const RULE_B = new Set([3]);
+const RULE_S = new Set([2, 3]);
+const LIVE_FRAME_MS = 1000 / 60;
+const DEFAULT_SEED = 'symbiote-cell-bg';
+
+function finitePositive(value, fallback) {
+  let number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}
+
+function seedHash(value) {
+  let hash = 2166136261;
+  for (let char of String(value || DEFAULT_SEED)) {
+    hash ^= char.codePointAt(0);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0 || 1;
+}
+
+function nextRandom(state) {
+  state.randomState = (state.randomState + 0x6D2B79F5) >>> 0;
+  let value = state.randomState;
+  value = Math.imul(value ^ (value >>> 15), value | 1);
+  value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+  return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+}
+
+function approach(value, target, factor, elapsedMs) {
+  let safeFactor = Math.min(0.999999, Math.max(0, Number(factor) || 0));
+  let frames = Math.max(0, Number(elapsedMs) || 0) / LIVE_FRAME_MS;
+  return target + (value - target) * Math.pow(1 - safeFactor, frames);
+}
+
+function advanceRadii(state, elapsedMs) {
+  for (let index = 0; index < state.radii.length; index += 1) {
+    let alive = state.grid[index] === 1;
+    let target = alive ? state.maxRadius : state.minRadius;
+    let factor = alive ? 0.2 : state.fadeRate;
+    state.radii[index] = approach(state.radii[index], target, factor, elapsedMs);
+  }
+}
+
+function injectNoise(state) {
+  let regionW = Math.max(4, Math.floor(state.cols * 0.3));
+  let regionH = Math.max(4, Math.floor(state.rows * 0.3));
+  let startX = Math.floor(nextRandom(state) * Math.max(1, state.cols - regionW));
+  let startY = Math.floor(nextRandom(state) * Math.max(1, state.rows - regionH));
+  for (let y = startY; y < Math.min(state.rows, startY + regionH); y += 1) {
+    for (let x = startX; x < Math.min(state.cols, startX + regionW); x += 1) {
+      if (nextRandom(state) >= 0.15) continue;
+      let index = y * state.cols + x;
+      state.grid[index] = 1;
+      state.radii[index] = state.minRadius;
+    }
+  }
+}
+
+function stepGrid(state) {
+  let next = new Uint8Array(state.grid.length);
+  let changed = 0;
+  for (let y = 0; y < state.rows; y += 1) {
+    for (let x = 0; x < state.cols; x += 1) {
+      let neighbors = 0;
+      for (let dy = -1; dy <= 1; dy += 1) {
+        for (let dx = -1; dx <= 1; dx += 1) {
+          if (dx === 0 && dy === 0) continue;
+          let nx = (x + dx + state.cols) % state.cols;
+          let ny = (y + dy + state.rows) % state.rows;
+          neighbors += state.grid[ny * state.cols + nx];
+        }
+      }
+      let index = y * state.cols + x;
+      let alive = state.grid[index] === 1;
+      next[index] = alive
+        ? (RULE_S.has(neighbors) ? 1 : 0)
+        : (RULE_B.has(neighbors) ? 1 : 0);
+      if (next[index] !== state.grid[index]) changed += 1;
+    }
+  }
+  state.grid = next;
+  if (changed < state.grid.length * 0.02) {
+    state.stagnantCount += 1;
+    if (state.stagnantCount >= 5) {
+      injectNoise(state);
+      state.stagnantCount = 0;
+    }
+  } else {
+    state.stagnantCount = 0;
+  }
+}
+
+export function createCellBgRenderState(options = {}) {
+  let cols = Math.max(1, Math.floor(finitePositive(options.cols, 1)));
+  let rows = Math.max(1, Math.floor(finitePositive(options.rows, 1)));
+  let minRadius = finitePositive(options.minRadius, 2);
+  let state = {
+    seed: String(options.seed || DEFAULT_SEED),
+    cols,
+    rows,
+    stepMs: finitePositive(options.stepMs, 75),
+    minRadius,
+    maxRadius: Math.max(minRadius, finitePositive(options.maxRadius, 4)),
+    fadeRate: Math.min(1, Math.max(0, Number(options.fadeRate) || 0.04)),
+    grid: new Uint8Array(cols * rows),
+    radii: new Float32Array(cols * rows),
+    randomState: seedHash(`${options.seed || DEFAULT_SEED}:${cols}x${rows}`),
+    stagnantCount: 0,
+    stepIndex: 0,
+    timeMs: 0,
+  };
+  state.radii.fill(minRadius);
+  for (let index = 0; index < state.grid.length; index += 1) {
+    state.grid[index] = nextRandom(state) < 0.15 ? 1 : 0;
+  }
+  return state;
+}
+
+export function seekCellBgRenderState(state, timeMs, options = state || {}) {
+  let targetTimeMs = Math.max(0, Number(timeMs) || 0);
+  let next = state;
+  if (!next || targetTimeMs < next.timeMs) {
+    next = createCellBgRenderState(options);
+  }
+  let targetStep = Math.floor(targetTimeMs / next.stepMs);
+  while (next.stepIndex < targetStep) {
+    advanceRadii(next, next.stepMs);
+    stepGrid(next);
+    next.stepIndex += 1;
+  }
+  next.timeMs = targetTimeMs;
+  return next;
+}
+
+export function cellBgRenderFrame(state) {
+  let elapsedMs = Math.max(0, state.timeMs - state.stepIndex * state.stepMs);
+  let radii = new Float32Array(state.radii.length);
+  for (let index = 0; index < radii.length; index += 1) {
+    let alive = state.grid[index] === 1;
+    let target = alive ? state.maxRadius : state.minRadius;
+    let factor = alive ? 0.2 : state.fadeRate;
+    radii[index] = approach(state.radii[index], target, factor, elapsedMs);
+  }
+  return { grid: state.grid, radii };
+}
+
+export function cellBgRenderHash(state, frame = cellBgRenderFrame(state)) {
+  let hash = 2166136261;
+  for (let index = 0; index < frame.grid.length; index += 1) {
+    hash ^= frame.grid[index];
+    hash = Math.imul(hash, 16777619);
+    hash ^= Math.round(frame.radii[index] * 1000);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}

package/index.js

@@ -136,11 +136,14 @@ export {
 } from './canvas/CanvasGraph/CanvasGraphViewport.js';
 export {
   GRAPH_DIRECTORY_FRAME_COLORS,
+  GRAPH_PATH_STYLE_MENU_GROUP,
+  GRAPH_PATH_STYLE_MENU_ITEMS,
   GRAPH_PATH_STYLES,
   GRAPH_VIEW_MODES,
   addGraphDirectoryFrames,
   applyGraphExplorerViewMode,
   buildFlatPathHash,
+  createGraphPathStyleMenuActions,
   createGraphExplorerViewController,
   createGraphViewModeController,
   getFileSelectionNodeId,
@@ -150,6 +153,7 @@ export {
   getNextGraphPathStyle,
   normalizeGraphExplorerViewMode,
   normalizeGraphViewMode,
+  resolveGraphPathStyleAction,
   resolveFlatHashChange,
   resolveInitialGraphViewMode,
   shouldClearFocusOnSelection,

package/manifest/component-registry.js

@@ -3219,12 +3219,13 @@ export let COMPONENTS = [
       status: 'draft',
       schemaVersion: 'component-descriptor-v2',
       dataSchema: 'schemas/graph-model-v1.json',
-      capabilities: ['node-card', 'ports', 'controls', 'shape-variant', 'media-avatar', 'category-accent', 'type-accent', 'error-state'],
+      capabilities: ['node-card', 'ports', 'controls', 'shape-variant', 'media-avatar', 'media-fit', 'category-accent', 'type-accent', 'error-state'],
       attributes: [
         { name: 'node-label', type: 'string', description: 'Rendered node label.' },
         { name: 'node-category', type: 'string', description: 'Semantic node category used for icon and accent selection.' },
         { name: 'node-type', type: 'string', description: 'Semantic node type used for type-specific accent selection when a matching theme token exists.' },
         { name: 'node-shape', type: 'string', description: 'Supported node shape: rect, pill, circle, disc, diamond, comment, or registered SVG preset such as hexagon.' },
+        { name: 'data-media-fit', type: 'string', description: 'Resolved media object-fit strategy: contain for transparent/logo media, cover for cropped photo media.' },
       ],
       properties: [
         { name: 'mediaSrc', type: 'string', description: 'Media or avatar image URL derived from node params.' },
@@ -3453,7 +3454,7 @@ export let COMPONENTS = [
       status: 'draft',
       schemaVersion: 'component-descriptor-v2',
       dataSchema: 'schemas/graph-model-v1.json',
-      capabilities: ['hierarchical-graph', 'overview-read-renderer', 'force-layout', 'semantic-clusters', 'focus-selection', 'layout-snapshot', 'device-orientation-parallax'],
+      capabilities: ['hierarchical-graph', 'overview-read-renderer', 'force-layout', 'semantic-clusters', 'focus-selection', 'layout-snapshot', 'viewport-control', 'device-orientation-parallax'],
       attributes: [
         { name: 'active-node-scale', type: 'number', description: 'Visual scale target for the selected node; defaults to 1.5.' },
         { name: 'info-panel-scale', type: 'number', description: 'Visual scale for the active node information panel; defaults to 1.' },
@@ -3480,6 +3481,8 @@ export let COMPONENTS = [
         { name: 'focusNodes', type: 'function', description: 'Agent-facing alias for fitting one or more graph node ids into the viewport.' },
         { name: 'queueTransitionMarkers', type: 'function', description: 'Queues animated route markers from one graph node to multiple target node ids without changing the host-owned graph model.' },
         { name: 'fitView', type: 'function', description: 'Fits the visible graph into the canvas viewport; accepts optional viewportEase for live replay tracking.' },
+        { name: 'getViewport', type: 'function', description: 'Returns the current zoom and pan viewport as a portable snapshot.' },
+        { name: 'setViewport', type: 'function', description: 'Applies an absolute, clamped zoom and pan viewport immediately or through the graph camera easing loop.' },
         { name: 'setVisualOptions', type: 'function', description: 'Applies visual tuning options such as activeNodeScale and infoPanelScale without changing the host-owned graph model.' },
         { name: 'setForceLayoutOptions', type: 'function', description: 'Applies force-layout tuning options, including layoutAlgorithm: organic, oil-cloud, crystal, or spring, without changing the host-owned graph model.' },
         { name: 'pulseNode', type: 'function', description: 'Projects a timed pulse around one node, optionally from an explicit render-clock start time.' },
@@ -4440,6 +4443,7 @@ export let COMPONENTS = [
         'resize-aware',
         'reduced-motion-friendly',
         'layout-lifecycle',
+        'deterministic-render',
       ],
       properties: [
         { name: 'active', type: 'boolean', description: 'Persistent animation state.' },
@@ -4450,6 +4454,7 @@ export let COMPONENTS = [
         { name: 'active', type: 'boolean', description: 'Starts persistent animation when present.' },
         { name: 'auto-trigger', type: 'boolean', description: 'Set to false/off to disable mount and resize pulses.' },
         { name: 'pulse-duration', type: 'number', description: 'Default timed pulse duration in milliseconds.' },
+        { name: 'seed', type: 'string', description: 'Stable seed used by deterministic external-frame rendering.' },
       ],
       methods: [
         { name: 'start', type: 'function', description: 'Starts persistent animation with smooth acceleration.' },
@@ -4461,6 +4466,9 @@ export let COMPONENTS = [
         { name: 'resize', type: 'function', description: 'Resizes the canvas to its host bounds.' },
         { name: 'suspendLayout', type: 'function', description: 'Immediately stops animation work while the containing layout group is hidden.' },
         { name: 'resumeLayout', type: 'function', description: 'Restores persistent animation only when it was active before layout suspension.' },
+        { name: 'setFrameDriver', type: 'function', description: 'Selects self-driven live animation or externally driven deterministic rendering.' },
+        { name: 'presentFrame', type: 'function', description: 'Synchronously paints the current shared render-clock time.' },
+        { name: 'getFramePresentation', type: 'function', description: 'Returns deterministic frame metrics and the current grid hash.' },
       ],
       events: [
         { name: 'cell-bg-animation-trigger', description: 'Emits when a timed activity pulse is requested.', detail: [{ name: 'duration', type: 'number' }] },

package/node/GraphNode/GraphNode.css.js

@@ -229,6 +229,14 @@ export let styles = css`
       -webkit-user-drag: none;
     }
 
+    &[data-media-fit='contain'] .sn-node-media-img {
+      object-fit: contain;
+    }
+
+    &[data-media-fit='cover'] .sn-node-media-img {
+      object-fit: cover;
+    }
+
     & .sn-node-content {
       padding: var(--sn-node-content-padding, 8px 12px 10px);
       min-width: 0;

package/node/GraphNode/GraphNode.js

@@ -43,6 +43,14 @@ function normalizeNodeTone(value) {
   return tone;
 }
 
+function normalizeMediaFit(value) {
+  let fit = String(value || '').trim().toLowerCase();
+  if (fit === 'fit') return 'contain';
+  if (fit === 'crop') return 'cover';
+  if (fit === 'contain' || fit === 'cover') return fit;
+  return '';
+}
+
 export class GraphNode extends Symbiote {
   destructionDelay = 200;
 
@@ -108,6 +116,7 @@ export class GraphNode extends Symbiote {
     this.toggleAttribute('data-header-hidden', Boolean(params.hideHeader || params.headerHidden));
     this.toggleAttribute('data-content-hidden', contentHidden);
     setOptionalAttribute(this, 'data-node-tone', normalizeNodeTone(params.tone || params.nodeTone));
+    setOptionalAttribute(this, 'data-media-fit', normalizeMediaFit(params.mediaFit || params.imageFit || params.avatarFit));
     this.set$({
       nodeIcon: node.icon || CATEGORY_ICONS[node.category] || CATEGORY_ICONS.default,
       mediaSrc: params.media || params.image || params.avatar || '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "symbiote-ui",
-  "version": "0.3.0-alpha.52",
+  "version": "0.3.0-alpha.53",
   "type": "module",
   "description": "Agent-ready Web Components, layouts, themes, manifests, and UI contracts for Symbiote systems.",
   "main": "index.js",

package/ui/index.js

@@ -159,11 +159,14 @@ export {
 } from '../canvas/graph-layout.js';
 export {
   GRAPH_DIRECTORY_FRAME_COLORS,
+  GRAPH_PATH_STYLE_MENU_GROUP,
+  GRAPH_PATH_STYLE_MENU_ITEMS,
   GRAPH_PATH_STYLES,
   GRAPH_VIEW_MODES,
   addGraphDirectoryFrames,
   applyGraphExplorerViewMode,
   buildFlatPathHash,
+  createGraphPathStyleMenuActions,
   createGraphExplorerViewController,
   createGraphViewModeController,
   getFileSelectionNodeId,
@@ -175,6 +178,7 @@ export {
   normalizeGraphViewMode,
   renderGraphPathStyleButton,
   renderGraphViewModeButton,
+  resolveGraphPathStyleAction,
   resolveFlatHashChange,
   resolveInitialGraphViewMode,
   selectGraphLabelMode,

package/webmcp.js

@@ -23,7 +23,6 @@ export {
 export function getModelContext(target = globalThis.document) {
   return target?.modelContext
     || (typeof target?.registerTool === 'function' ? target : null)
-    || globalThis.navigator?.modelContext
     || null;
 }
 
@@ -65,7 +64,7 @@ export async function createNativeToolDescriptor(options) {
   return new ToolDescriptor(options);
 }
 
-export async function registerWebMcpTool(options, target = globalThis.document) {
+export async function registerWebMcpTool(options, target = globalThis.document, registrationOptions = {}) {
   let context = getModelContext(target);
   if (!context || typeof context.registerTool !== 'function') {
     return { nativeActive: false, descriptor: createToolDescriptor(options), unregister: () => {} };
@@ -82,7 +81,7 @@ export async function registerWebMcpTool(options, target = globalThis.document)
     nativeActive = false;
     descriptor = createToolDescriptor(options);
   }
-  let registration = context.registerTool(descriptor);
+  let registration = await context.registerTool(descriptor, registrationOptions);
   let unregister = registrationUnregister(registration);
 
   return { nativeActive, descriptor, unregister };
@@ -703,23 +702,42 @@ export function getWebMcpPresentationActionPhase(value, options = {}) {
   return WEBMCP_PRESENTATION_TOUR_PHASES.AFTER_FOCUS;
 }
 
-export function createWebMcpTourTurnActionPlan(turn = {}, options = {}) {
+export function createWebMcpTourTurnActionPlans(turn = {}, options = {}) {
   let actions = webMcpPresentationActionsFromOptions(options);
-  let source = isObject(turn?.webmcp) ? turn.webmcp : null;
-  let action = webMcpPresentationActionFromValue(source, actions);
-  let phase = source ? getWebMcpPresentationActionPhase(source, { ...options, actions }) : WEBMCP_PRESENTATION_TOUR_PHASES.NONE;
-  let command = action && phase !== WEBMCP_PRESENTATION_TOUR_PHASES.NONE ? {
-    tool: action.name || action.id,
-    input: isObject(source.input) ? { ...source.input } : {},
-  } : null;
-  return {
-    action,
-    command,
-    phase,
-    runBeforeFocus: phase === WEBMCP_PRESENTATION_TOUR_PHASES.BEFORE_FOCUS,
-    runAfterFocus: phase === WEBMCP_PRESENTATION_TOUR_PHASES.AFTER_FOCUS,
-    runAsAnnotation: phase === WEBMCP_PRESENTATION_TOUR_PHASES.AFTER_FOCUS_ANNOTATION,
-    runAsEffect: phase === WEBMCP_PRESENTATION_TOUR_PHASES.AFTER_FOCUS,
+  return (Array.isArray(turn?.cues) ? turn.cues : [])
+    .filter((cue) => cue?.kind === 'interaction' && isObject(cue.interaction?.binding))
+    .map((cue) => {
+      let binding = cue.interaction.binding;
+      let source = { tool: binding.tool, input: { ...(isObject(binding.input) ? binding.input : {}) } };
+      let action = webMcpPresentationActionFromValue(source, actions);
+      if (cue.targetId && action?.inputSchema?.properties?.targetId) source.input.targetId = cue.targetId;
+      let phase = getWebMcpPresentationActionPhase(source, { ...options, actions });
+      let command = action && phase !== WEBMCP_PRESENTATION_TOUR_PHASES.NONE ? {
+        tool: action.name || action.id,
+        input: source.input,
+      } : null;
+      return {
+        cue,
+        action,
+        command,
+        phase,
+        runBeforeFocus: phase === WEBMCP_PRESENTATION_TOUR_PHASES.BEFORE_FOCUS,
+        runAfterFocus: phase === WEBMCP_PRESENTATION_TOUR_PHASES.AFTER_FOCUS,
+        runAsAnnotation: phase === WEBMCP_PRESENTATION_TOUR_PHASES.AFTER_FOCUS_ANNOTATION,
+        runAsEffect: phase === WEBMCP_PRESENTATION_TOUR_PHASES.AFTER_FOCUS,
+      };
+    });
+}
+
+export function createWebMcpTourTurnActionPlan(turn = {}, options = {}) {
+  return createWebMcpTourTurnActionPlans(turn, options)[0] || {
+    action: null,
+    command: null,
+    phase: WEBMCP_PRESENTATION_TOUR_PHASES.NONE,
+    runBeforeFocus: false,
+    runAfterFocus: false,
+    runAsAnnotation: false,
+    runAsEffect: false,
   };
 }