@almadar/orb-shell-typescript-linux-x64 19.0.3 → 19.2.0

package/templates/almadar-renderers-typescript/src/lib/kernel-client.ts

@@ -37,6 +37,8 @@ import type { FrameScheduler } from './kernel-frames';
 import { getTraitPresence, presenceGroup } from '../core';
 import type { AppliedWire, AwaitingTrait, DispatchMode, DispatchWire, Entered, FoldedNextWire, FoldProgressWire, FrameDelta, Left, MountWire, PageCircuit, TraitSnapshot } from '@almadar/core/kernel-wire';
 import type { KernelInstance } from './kernel-wire';
+import type { KernelGpuHost } from '@almadar/shell-runtime/kernel/wire';
+import { decodeHeldCompletion } from '@almadar/shell-runtime/kernel/decode';
 
 const log = createLogger('almadar:ui:kernel-client');
 
@@ -98,6 +100,8 @@ export interface KernelClientOptions {
   topology: Promise<{ carriesCircuitState: boolean }>;
   /** Hears every executed hop of every response the kernel produces (the verification timeline). */
   observer?: TransitionObserver;
+  /** The GPU answerer installed into the kernel before its first dispatch; absent, a `gpu/` ask answers `unsupported`. */
+  gpu?: Promise<KernelGpuHost | undefined>;
 }
 
 const defaultFrameScheduler: FrameScheduler = (callback) => {
@@ -121,8 +125,9 @@ export function createKernelClient(opts: KernelClientOptions): KernelClient {
   const { store, traitIndex, transport } = opts;
   let loaded: KernelInstance | undefined;
   const configs = new Map<string, TraitConfig>();
-  const ready = opts.instance.then((k) => {
+  const ready = Promise.all([opts.instance, opts.gpu]).then(([k, gpu]) => {
     loaded = k;
+    if (gpu !== undefined) k.installGpu(gpu, (json) => deliverGpuCompletion(k, json));
     return k;
   });
   // The load failure reaches every call that awaits `ready`; a client nothing dispatches through stays quiet.
@@ -464,7 +469,9 @@ export function createKernelClient(opts: KernelClientOptions): KernelClient {
       store.notify();
       return { response, mode: parse<DispatchMode>(k.dispatchMode(request.runTick.trait)) };
     }
-    const wire = parse<DispatchWire>(k.dispatch(traitName, request.entityId, request.event, payloadJson(request.payload)));
+    const wire = parse<DispatchWire>(request.heldPayload !== undefined
+      ? k.dispatchHeld(traitName, request.entityId, request.event, request.heldPayload)
+      : k.dispatch(traitName, request.entityId, request.event, payloadJson(request.payload)));
     try {
       return await settleDispatch(k, wire, request, hooks, progress);
     } finally {
@@ -472,6 +479,27 @@ export function createKernelClient(opts: KernelClientOptions): KernelClient {
     }
   };
 
+  /** The painters of the running frame clocks (`startFrames`): a dispatch no view started is painted as a frame is. */
+  const framePainters = new Set<(outcomes: ClientKernelOutcome[]) => void>();
+
+  /** A held gpu ask finished in the kernel: its route event runs as a dispatch of its own, with the payload the kernel holds, painted as a frame. */
+  const deliverGpuCompletion = (k: KernelInstance, json: string): void => {
+    const completion = decodeHeldCompletion(json);
+    if (completion === null) return;
+    const request: EventRequest = {
+      event: completion.event,
+      targetTrait: completion.traitName,
+      heldPayload: completion.heldPayload,
+      ...(completion.entityId !== undefined ? { entityId: completion.entityId } : {}),
+    };
+    dispatchOne(request, [], false).then((outcome) => {
+      for (const paint of framePainters) paint([outcome]);
+    }).catch((error: Error) => {
+      k.dropHeldPayload(completion.heldPayload);
+      log.error('gpu-completion-failed', { trait: completion.traitName, event: completion.event, error: error.message });
+    });
+  };
+
   const settleDispatch = async (k: KernelInstance, wire: DispatchWire, request: EventRequest, hooks: ClientDispatchHooks[], progress: boolean): Promise<ClientKernelOutcome> => {
     log.debug('dispatch', { trait: wire.seed.trait, event: request.event, mode: wire.mode, legs: wire.serverLegs.length, success: wire.response.success, states: wire.response.states, effects: (wire.response.clientEffectsByTrait ?? []).map((e) => `${e.traitName}:${e.effect[0]}:${e.effect[1] ?? ''}`), emitted: wire.response.emittedEvents.map((e) => e.event) });
     trace(k, wire.response);
@@ -500,12 +528,14 @@ export function createKernelClient(opts: KernelClientOptions): KernelClient {
         const kept = mountedSeeds.get(wire.orbital) ?? [];
         if (!kept.some((s) => s.trait === wire.seed.trait)) mountedSeeds.set(wire.orbital, [...kept, { trait: wire.seed.trait, event: seeds.find((s) => s.trait === wire.seed.trait)?.event ?? 'INIT' }]);
       }
-      for (const wire of wires) {
+      const announced = mount.announced;
+      for (const wire of announced !== null ? [announced, ...wires] : wires) {
         log.debug('mount', { trait: wire.seed.trait, event: wire.seed.event, mode: wire.mode, legs: wire.serverLegs.length, success: wire.response.success });
         trace(k, wire.response);
         mirror(wire.response);
       }
       store.notify();
+      if (announced !== null) hooks?.onLocal?.(announced.seed.trait, announced.response);
       for (const wire of wires) hooks?.onLocal?.(wire.seed.trait, wire.response);
       const outcome: MountOutcome = {
         seeds: wires.map((w) => ({ trait: w.seed.trait, event: w.seed.event, mode: w.mode, local: w.response })),
@@ -516,6 +546,21 @@ export function createKernelClient(opts: KernelClientOptions): KernelClient {
         emittedEvents: [],
       };
       if (transport === undefined) return outcome;
+      // The browser's own $MOUNT ran before the seeds, so the server work its listeners reached leaves first (EXEC-SEED-7).
+      if (announced !== null && announced.serverLegs.length > 0) {
+        let posted: Posted;
+        try {
+          posted = await post(k, announced, baseRequest, { rollback: false, awaiting: false });
+        } finally {
+          endFlight(k, announced.flight);
+        }
+        outcome.posted = true;
+        outcome.success = outcome.success && posted.success;
+        if (posted.error !== undefined) outcome.error = posted.error;
+        outcome.rejections.push(...posted.rejections);
+        outcome.serverEffects.clientEffectsByTrait?.push(...(posted.serverEffects.clientEffectsByTrait ?? []));
+        outcome.emittedEvents.push(...posted.foldedEmits);
+      }
       const topology = await opts.topology;
       // A group folds under its oldest seed's flight, so the groups go in flight order and each ends its flights before the next.
       const groups = (topology.carriesCircuitState ? mount.legs : mount.statefulLegs)
@@ -546,6 +591,23 @@ export function createKernelClient(opts: KernelClientOptions): KernelClient {
         outcome.serverEffects.clientEffectsByTrait?.push(...(posted.serverEffects.clientEffectsByTrait ?? []));
         outcome.emittedEvents.push(...posted.foldedEmits);
       }
+      // The hops the host's replay of the mount cannot reach leave after it, each folded as a dispatch's leg (EXEC-DIST-10).
+      for (const hop of mount.hops) {
+        const flight = k.openFlight();
+        let posted: Posted;
+        try {
+          const planned: PlannedLeg = { orbital: hop.orbital, leg: hop.leg, keepsState: true, alreadyDelivered: [], foldSeeded: [], wires: [], flight };
+          posted = await sendLegs(k, [planned], baseRequest, { rollback: false, mount: false }, outcome.seeds[0]!.local);
+        } finally {
+          endFlight(k, flight);
+        }
+        outcome.posted = true;
+        outcome.success = outcome.success && posted.success;
+        if (posted.error !== undefined) outcome.error = posted.error;
+        outcome.rejections.push(...posted.rejections);
+        outcome.serverEffects.clientEffectsByTrait?.push(...(posted.serverEffects.clientEffectsByTrait ?? []));
+        outcome.emittedEvents.push(...posted.foldedEmits);
+      }
       return outcome;
   };
 
@@ -616,10 +678,11 @@ export function createKernelClient(opts: KernelClientOptions): KernelClient {
       await scopeTail;
       const baseRequest = base ?? {};
       k.mount(JSON.stringify(seeds.map((s) => s.trait)));
-      const mount = parse<MountWire>(k.dispatchMount(JSON.stringify(seeds), baseRequest.entityId, payloadJson(baseRequest.payload), baseRequest.route));
+      const mount = parse<MountWire>(k.dispatchMount(JSON.stringify(seeds), baseRequest.entityId, payloadJson(baseRequest.payload), baseRequest.route, baseRequest.crumb));
       try {
         return await settleMount(k, mount, seeds, hooks, baseRequest);
       } finally {
+        if (mount.announced !== null) endFlight(k, mount.announced.flight);
         for (const wire of mount.seeds) endFlight(k, wire.flight);
       }
     },
@@ -648,6 +711,7 @@ export function createKernelClient(opts: KernelClientOptions): KernelClient {
     framePause: () => loaded?.framePause(),
     frameResume: () => loaded?.frameResume(),
     startFrames: (onFrame, schedule = defaultFrameScheduler) => {
+      framePainters.add(onFrame);
       const presence = getTraitPresence();
       const releases = visibleGroups.map(([, group]) => presence.watch(group));
       let stopped = false;
@@ -693,6 +757,7 @@ export function createKernelClient(opts: KernelClientOptions): KernelClient {
       }).catch((error: Error) => log.error('kernel-frame-failed', { error: error.message }));
       return () => {
         stopped = true;
+        framePainters.delete(onFrame);
         driver?.stop();
         releases.forEach((release) => release());
       };

package/templates/almadar-renderers-typescript/src/lib/kernel-wire.ts

@@ -6,10 +6,17 @@
  */
 
 import type { KernelModule as RuntimeKernelModule } from '../index';
+import type { KernelGpuHost } from '@almadar/shell-runtime/kernel/wire';
 
 /** The `Kernel` class `@almadar/kernel` exports: JSON strings in, JSON strings out. */
 export interface KernelInstance {
   dispatch(traitName: string, entityId: string | undefined, event: string, payloadJson?: string): string;
+  /** Install the GPU answerer: every `gpu/` ask is held in the kernel and answered in ask order, and each outcome's route event reaches `completed` as `HeldGpuCompletion` JSON (`null` when it takes no route) for the host to dispatch with `dispatchHeld`. */
+  installGpu(gpu: KernelGpuHost, completed: (completionJson: string) => void): void;
+  /** `dispatch` with the payload the kernel holds under `heldPayload` (a gpu completion's), taken once. */
+  dispatchHeld(traitName: string, entityId: string | undefined, event: string, heldPayload: number): string;
+  /** Drop a held completion payload no dispatch will take. */
+  dropHeldPayload(heldPayload: number): boolean;
   /** A flight for work the kernel did not wire (a dispatch the host ran on its own, a frame's browser leg). */
   openFlight(): number;
   /** `applyServerResponse` in flight order (EXEC-CONC-8): a `FoldProgressWire` as JSON, folded now or queued behind an older flight. */
@@ -28,7 +35,7 @@ export interface KernelInstance {
   /** The mount a reconnecting client posts to rebuild its session: the seeds with the state and frame this client holds for each. */
   reseedLeg(seedsJson: string, entityId?: string): string;
   foldBase(carriedJson: string | undefined, seededJson: string, entityId?: string): string | undefined;
-  dispatchMount(seedsJson: string, entityId?: string, payloadJson?: string, route?: string): string;
+  dispatchMount(seedsJson: string, entityId?: string, payloadJson?: string, route?: string, crumb?: string): string;
   /** The frame delta a painter at version `since` of this kernel's frames needs (`FrameDelta` JSON): empty when current, else a snapshot. */
   framesSince(since: number): string;
   restore(traitName: string, entityId: string | undefined, snapshotJson: string): string;

package/templates/almadar-renderers-typescript/src/lib/mermaidTheme.ts

@@ -6,11 +6,22 @@
  * @packageDocumentation
  */
 
-import type { CanvasTheme } from '@almadar/core';
+import { DIAGRAM_TONE_COLOR_KEYS, type CanvasTheme, type DiagramTone } from '@almadar/core';
 import type { ResolvedMode } from '../core';
 
 const PIE_SLOTS = 12;
 
+const READ_TONES: readonly DiagramTone[] = ['ink', 'label', 'axis', 'grid', 'guide', 'fill', 'highlight'];
+const SERIES_TONE_IDS: readonly DiagramTone[] = ['series-1', 'series-2', 'series-3', 'series-4', 'series-5', 'series-6', 'series-7', 'series-8'];
+
+/** A tone mermaid draws with did not resolve on the theme's scope; mermaid's colour parser would throw on it. */
+export class UnresolvedThemeToneError extends Error {
+  constructor(readonly tones: readonly DiagramTone[]) {
+    super(`diagram tones unresolved on the scope: declare ${tones.map((t) => `--color-${DIAGRAM_TONE_COLOR_KEYS[t]}`).join(', ')}`);
+    this.name = 'UnresolvedThemeToneError';
+  }
+}
+
 export interface MermaidThemeVariables {
   darkMode: boolean;
   background: string;
@@ -56,6 +67,9 @@ export interface MermaidThemeVariables {
 
 export function mermaidThemeVariables(theme: CanvasTheme, mode: ResolvedMode): MermaidThemeVariables {
   const { tones, series } = theme;
+  const drawnSeries = SERIES_TONE_IDS.filter((_, i) => i < series.length && i < PIE_SLOTS);
+  const missing = [...READ_TONES, ...drawnSeries].filter((t) => theme.unresolvedTones.includes(t));
+  if (missing.length > 0) throw new UnresolvedThemeToneError(missing);
   const seriesAt = (i: number): string => series[i % series.length] ?? tones.highlight;
   const vars: MermaidThemeVariables = {
     darkMode: mode === 'dark',

package/templates/almadar-renderers-typescript/src/lib/reconcile-slot-content.ts

@@ -72,6 +72,12 @@ function isPlainSlotObject(value: SlotPropValue): value is PlainSlotObject {
   return true;
 }
 
+/** An element's ref: React 19 carries it in props, earlier versions on the element. */
+function elementRef(element: React.ReactElement): React.Ref<Element> | undefined {
+  const props = element.props as { ref?: React.Ref<Element> } | null;
+  return props?.ref ?? (element as React.ReactElement & { ref?: React.Ref<Element> }).ref;
+}
+
 function shareValue(prev: SlotPropValue, next: SlotPropValue): ReconcileResult<SlotPropValue> {
   if (Object.is(prev, next)) return { value: prev, equal: true };
 
@@ -93,9 +99,15 @@ function shareValue(prev: SlotPropValue, next: SlotPropValue): ReconcileResult<S
       : { value: next, equal: false };
   }
 
-  // Functions, React elements, class instances: identity only (Object.is
-  // above already covered equality) — never recurse into them.
+  // Functions and class instances: identity only (Object.is above already covered equality).
   if (typeof prev === 'function' || typeof next === 'function') return { value: next, equal: false };
+  // A React element rebuilt from the same descriptor (a host re-projecting a paint every render) is the same element:
+  // same type, key and ref, and props that reconcile equal, as React itself decides to keep a subtree.
+  if (React.isValidElement(prev) && React.isValidElement(next)) {
+    if (prev.type !== next.type || prev.key !== next.key || elementRef(prev) !== elementRef(next)) return { value: next, equal: false };
+    const props = shareValue(prev.props as SlotPropValue, next.props as SlotPropValue);
+    return props.equal ? { value: prev, equal: true } : { value: next, equal: false };
+  }
   if (React.isValidElement(prev) || React.isValidElement(next)) return { value: next, equal: false };
 
   if (Array.isArray(prev) && Array.isArray(next)) {

package/templates/almadar-renderers-typescript/src/lib/slot-definitions.ts

@@ -134,6 +134,14 @@ export function isNotificationSlot(slot: string): boolean {
   return SLOT_DEFINITIONS[slot as UISlot]?.notification === true;
 }
 
+/**
+ * Whether a paint goes to its trait's embed frame instead of the slot: an embedded trait's inline renders do, while a
+ * portal slot (toast, modal, drawer, …) renders in that slot like any trait's. Every painter routes through this.
+ */
+export function paintsInTraitFrame(traitEmbedded: boolean, slot: string): boolean {
+  return traitEmbedded && !isNotificationSlot(slot);
+}
+
 /**
  * Get all slots of a specific type.
  */

package/templates/almadar-renderers-typescript/src/preview/OrbPreview.tsx

@@ -51,6 +51,7 @@ import { programStamp, type ProgramStamp } from '../hooks/circuit/useCircuitKern
 import { KernelEngineProvider, useKernelEngine } from '../providers/KernelEngineContext';
 import { ClientTicksPausedContext } from '../hooks/circuit/useClientTicks';
 import type { KernelLoader } from '../lib/kernel-wire';
+import type { KernelCanvas3DFactory, KernelSceneCanvasFactory } from '@almadar/shell-runtime/kernel/wire';
 import { RowSetResolverProvider } from '../providers/RowSetResolverContext';
 import { createCircuitRowSetResolver } from '../lib/store-row-set-resolver';
 import { browserRowSets } from '../lib/browser-row-sets';
@@ -95,9 +96,13 @@ function NavStackRefBridge({ apiRef }: { apiRef: React.MutableRefObject<NavStack
  * its own `sendEvent`/mount-time dispatch resolves — this component only
  * decides WHICH transport (or none) the kernel dispatches through.
  */
-function TraitInitializer({ pageName, routeParams, mountKey, orbitals, metadata, stamp, onNavigate, onNavigateBack, onLocalFallback, localFallbackTimeoutMs, browserStore, hasBridge, children }: {
+function TraitInitializer({ pageName, routePath, crumb, routeParams, mountKey, orbitals, metadata, stamp, onNavigate, onNavigateBack, onLocalFallback, localFallbackTimeoutMs, browserStore, hasBridge, children }: {
   /** The page the kernel answers the circuit of; absent: the initial page. */
   pageName?: string;
+  /** The concrete path the page is opened at: `$MOUNT.route` and the declared ancestors derive from it. */
+  routePath?: string;
+  /** The crumb of the navigate that opened `routePath`, passed through to the kernel's `$MOUNT`. */
+  crumb?: string;
   /** Route params from a parameterized page path — merged into every INIT payload. */
   routeParams?: Record<string, string>;
   /** The mounted page's identity — keys the once-per-mount INIT guard. */
@@ -155,6 +160,8 @@ function TraitInitializer({ pageName, routeParams, mountKey, orbitals, metadata,
   const { entityBindingSource, awaitingSkeletonSource, circuit, sessionTheme } = useTraitStateMachine(uiSlots, {
     orbitals,
     ...(pageName !== undefined ? { page: pageName } : {}),
+    ...(routePath !== undefined ? { routePath } : {}),
+    ...(crumb !== undefined ? { crumb } : {}),
     ...(metadata !== undefined ? { metadata } : {}),
     ...(stamp !== undefined ? { stamp } : {}),
     ...(onNavigate !== undefined ? { navigate: onNavigate } : {}),
@@ -281,7 +288,7 @@ function FitToBox({ children, mode = 'box' }: { children: React.ReactNode; mode?
  * When `serverUrl` is provided, wraps with ServerBridgeProvider and
  * forwards events to the server after local processing.
  */
-function SchemaRunner({ schema, serverUrl, transport, getAccessToken, mockData, pageName, routeParams, onNavigate, onNavigateBack, onLocalFallback, localFallbackTimeoutMs, themeOverride, frame }: {
+function SchemaRunner({ schema, serverUrl, transport, getAccessToken, mockData, pageName, routePath, crumb, routeParams, onNavigate, onNavigateBack, onLocalFallback, localFallbackTimeoutMs, themeOverride, frame }: {
   schema: OrbitalSchema;
   /** See OrbPreviewProps.frame. */
   frame: 'contained' | 'page';
@@ -290,6 +297,10 @@ function SchemaRunner({ schema, serverUrl, transport, getAccessToken, mockData,
   getAccessToken?: AccessTokenProvider;
   mockData?: EntityData;
   pageName?: string;
+  /** The concrete path the page is opened at, forwarded to TraitInitializer. */
+  routePath?: string;
+  /** The crumb of the navigate that opened `routePath`, forwarded to TraitInitializer. */
+  crumb?: string;
   /** Route params extracted from a parameterized page path (`/x/:id`) — merged into INIT payloads. */
   routeParams?: Record<string, string>;
   onNavigate?: (path: string, params?: Record<string, string>, crumb?: string) => void;
@@ -318,16 +329,17 @@ function SchemaRunner({ schema, serverUrl, transport, getAccessToken, mockData,
 
   const activeOrbitalTheme = useMemo(() => resolvePreviewTheme(schema, pageName), [schema, pageName]);
   const { locale } = useTranslate();
-  // A host that runs the whole program keeps its browser-stored entities; this view opens none.
-  const browserStore = useBrowserStore(schema.name ?? 'app', transport?.hostsBrowserStore === true ? NO_ORBITALS : schema.orbitals, locale);
+  // A host that runs the whole program keeps its browser-stored entities; this view opens none and resolves none.
+  const hostKeepsBrowserRows = transport?.hostsBrowserStore === true;
+  const browserStore = useBrowserStore(schema.name ?? 'app', hostKeepsBrowserRows ? NO_ORBITALS : schema.orbitals, locale);
 
   const bridge = useServerBridge();
   const kernelEngine = useKernelEngine();
   const browserRows = useMemo(
-    () => (browserStore.status === 'ready' && kernelEngine !== null
+    () => (!hostKeepsBrowserRows && browserStore.status === 'ready' && kernelEngine !== null
       ? browserRowSets(kernelEngine, { name: schema.name ?? 'app', orbitals: schema.orbitals, ...programStamp(schema) }, browserStore.store)
       : undefined),
-    [browserStore, kernelEngine, schema.name, schema.orbitals],
+    [hostKeepsBrowserRows, browserStore, kernelEngine, schema.name, schema.orbitals],
   );
   useEffect(() => () => browserRows?.dispose(), [browserRows]);
   const rowSets = useMemo(() => {
@@ -345,6 +357,8 @@ function SchemaRunner({ schema, serverUrl, transport, getAccessToken, mockData,
     <VerificationProvider enabled>
               <TraitInitializer
           pageName={pageName}
+          {...(routePath !== undefined ? { routePath } : {})}
+          {...(crumb !== undefined ? { crumb } : {})}
           routeParams={routeParams}
           mountKey={pageName}
           orbitals={schema.orbitals}
@@ -438,6 +452,10 @@ export interface OrbPreviewProps {
    * preview runs under whatever engine the host's own `KernelEngineProvider` selects.
    */
   kernelLoader?: KernelLoader;
+  /** With `kernelLoader`: makes the 3D view a `canvas` mode:"3d" draws on (`(canvas) => Canvas3D.create(canvas)`). */
+  canvas3d?: KernelCanvas3DFactory;
+  /** With `kernelLoader`: makes the scene canvas the learning and 2D canvases draw on (`(canvas) => SceneCanvas.create(canvas)`). */
+  sceneCanvas?: KernelSceneCanvasFactory;
   /**
    * How long (ms) to wait for the server bridge to connect before assuming
    * it's unreachable and falling back to local-only execution. Default
@@ -598,6 +616,8 @@ export function OrbPreview({
   transport,
   getAccessToken,
   kernelLoader,
+  canvas3d,
+  sceneCanvas,
   initialPagePath,
   isolated = false,
   fit = false,
@@ -775,6 +795,8 @@ export function OrbPreview({
     return pattern.replace(/:([A-Za-z0-9_]+)/g, (whole, key: string) => routeParams[key] ?? whole);
   }, [currentPagePath, routeParams]);
   const navStackRef = useRef<NavStackApi | null>(null);
+  const [crumbedNavigate, setCrumbedNavigate] = useState<{ path: string; crumb: string } | null>(null);
+  const openedCrumb = crumbedNavigate !== null && crumbedNavigate.path === concreteCurrentPath ? crumbedNavigate.crumb : undefined;
 
   // Navigate handler: when a ['navigate', '/path'] effect fires OR a
   // sidebar `<Link>` click is intercepted, find the matching page and
@@ -893,6 +915,7 @@ export function OrbPreview({
   const handleNavigateEffect = useCallback(
     (path: string, params?: Record<string, string>, crumb?: string) => {
       navStackRef.current?.beginNavigate(path, crumb);
+      setCrumbedNavigate(crumb !== undefined && crumb !== '' ? { path, crumb } : null);
       handleNavigate(path, params);
     },
     [handleNavigate],
@@ -927,7 +950,7 @@ export function OrbPreview({
       </ServerBridgeProvider>
     ) : node;
     const engined = kernelLoader !== undefined ? (
-      <KernelEngineProvider loader={kernelLoader}>{bridged}</KernelEngineProvider>
+      <KernelEngineProvider loader={kernelLoader} canvas3d={canvas3d} sceneCanvas={sceneCanvas}>{bridged}</KernelEngineProvider>
     ) : bridged;
     return <ClientTicksPausedContext.Provider value={paused}>{engined}</ClientTicksPausedContext.Provider>;
   };
@@ -1011,6 +1034,8 @@ export function OrbPreview({
                     getAccessToken={getAccessToken}
                     mockData={effectiveMockData}
                     pageName={currentPage}
+                    routePath={concreteCurrentPath}
+                    {...(openedCrumb !== undefined ? { crumb: openedCrumb } : {})}
                     routeParams={routeParams}
                     onNavigate={handleNavigateEffect}
                     onNavigateBack={handleNavigateBack}
@@ -1028,6 +1053,8 @@ export function OrbPreview({
                   getAccessToken={getAccessToken}
                   mockData={effectiveMockData}
                   pageName={currentPage}
+                  routePath={concreteCurrentPath}
+                  {...(openedCrumb !== undefined ? { crumb: openedCrumb } : {})}
                   routeParams={routeParams}
                   onNavigate={handleNavigateEffect}
                   onNavigateBack={handleNavigateBack}

package/templates/almadar-renderers-typescript/src/preview/__tests__/OrbPreview.kernel-loader.test.tsx

@@ -140,21 +140,20 @@ orbital Site {
 const greeting = (name: string): OrbitalSchema => ({ ...clientProgram(greetingProgram, { 'locales/en/site.json': JSON.stringify({ 'hero.title': 'Hello' }) }), name });
 
 describeKernel('OrbPreview — the client kernel paints i18n/t', () => {
-  it('from the catalog of the viewer the host provides', async () => {
+  it('from the catalog the resolved program carries, which the kernel installs (EXEC-LOAD-1)', async () => {
+    render(<OrbPreview schema={greeting(`i18n-${Math.random()}`)} isolated kernelLoader={loadFreshClientKernel} />);
+    expect(await screen.findByText('Hello', undefined, { timeout: 15_000 })).toBeTruthy();
+  }, 20_000);
+
+  it('control: a catalog the host provides never replaces the program\'s own messages', async () => {
     const messages = { 'site:hero.title': 'Hello from the catalog' };
     render(
       <I18nProvider value={{ locale: 'en', direction: 'ltr', t: createTranslate(messages), messages }}>
         <OrbPreview schema={greeting(`i18n-${Math.random()}`)} isolated kernelLoader={loadFreshClientKernel} />
       </I18nProvider>,
     );
-    expect(await screen.findByText('Hello from the catalog', undefined, { timeout: 15_000 })).toBeTruthy();
-  }, 20_000);
-
-  it('control: with no catalog the message paints empty, never the declared key or another locale', async () => {
-    render(<OrbPreview schema={greeting(`i18n-${Math.random()}`)} isolated kernelLoader={loadFreshClientKernel} />);
     const main = await screen.findByTestId('ui-slot-main', undefined, { timeout: 15_000 });
-    await waitFor(() => expect(main.getAttribute('data-slot-mode')).toBe('content'));
-    expect(main.textContent).toBe('');
+    await waitFor(() => expect(main.textContent).toBe('Hello'));
     expect(screen.queryByText('Hello from the catalog')).toBeNull();
   }, 20_000);
 });

package/templates/almadar-renderers-typescript/src/preview/__tests__/OrbPreview.mount-error.test.tsx

@@ -8,6 +8,8 @@ import React from 'react';
 import { render, screen } from '@testing-library/react';
 import { TRAIT_MOUNT_ERROR_TESTID, type OrbitalSchema, type Trait } from '@almadar/core';
 import { OrbPreview } from '../OrbPreview';
+import type { ServerBridgeTransport } from '../../providers/ServerBridge';
+import { TransportStatusError } from '@almadar/shell-runtime/client/EventTransport';
 import { TEST_TYPE_CONTRACT_VERSION } from '../../test-support/kernel-engine';
 
 const footer: Trait = {
@@ -43,6 +45,54 @@ function schemaWith(items: string | string[]): OrbitalSchema {
   };
 }
 
+function schemaWithServerRows(): OrbitalSchema {
+  const trait = (name: string): Trait => ({
+    name, linkedEntity: 'Row',
+    stateMachine: {
+      states: [{ name: 'idle', isInitial: true }], events: [],
+      transitions: [{ from: 'idle', to: 'idle', event: 'INIT', effects: [['fetch', 'Row'], ['render-ui', 'main', { type: 'typography', content: name }]] }],
+    },
+  });
+  return {
+    typeContractVersion: TEST_TYPE_CONTRACT_VERSION,
+    name: 'refused-app',
+    version: '1.0.0',
+    orbitals: [{
+      name: 'Shell',
+      entity: { name: 'Row', persistence: 'persistent', collection: 'rows', fields: [{ name: 'id', type: 'string' }] },
+      traits: [trait('FirstTrait'), trait('SecondTrait')],
+      pages: [{ name: 'Home', path: '/', traits: [{ ref: 'FirstTrait' }, { ref: 'SecondTrait' }] }],
+    }],
+  };
+}
+
+function refusing(status: number, body: string): ServerBridgeTransport {
+  return {
+    register: async () => ({ success: true, carriesCircuitState: true }),
+    unregister: async () => undefined,
+    send: async () => { throw new TransportStatusError(status, body); },
+    subscribe: () => () => undefined,
+  };
+}
+
+describe('OrbPreview — a server that refuses the page', () => {
+  it('says the server refused it, in the server\'s own words, without listing the traits', async () => {
+    render(<OrbPreview schema={schemaWithServerRows()} transport={refusing(429, '{"error":"Too many requests"}')} />);
+    const error = await screen.findByTestId(TRAIT_MOUNT_ERROR_TESTID);
+    expect(error.textContent).toContain('The server refused this page');
+    expect(error.textContent).toContain('Too many requests');
+    expect(error.textContent).not.toContain('FirstTrait');
+    expect(error.textContent).not.toContain('{"error"');
+  });
+
+  it('a refusal with no body still names the status', async () => {
+    render(<OrbPreview schema={schemaWithServerRows()} transport={refusing(503, '')} />);
+    const error = await screen.findByTestId(TRAIT_MOUNT_ERROR_TESTID);
+    expect(error.textContent).toContain('The server refused this page');
+    expect(error.textContent).toContain('503');
+  });
+});
+
 describe('OrbPreview — a trait that fails to start', () => {
   it('shows the typed evaluation error on the card, naming only the trait that failed', async () => {
     render(<OrbPreview schema={schemaWith('not-a-list')} isolated />);

package/templates/almadar-renderers-typescript/src/providers/GameAudioProvider.tsx

@@ -4,7 +4,8 @@
  *
  * Context provider that owns the game audio. While it is mounted, the kernel's
  * `audio/play-sound`, `audio/stop-sound`, `audio/change-music` and `audio/stop-music`
- * asks drive it.
+ * asks drive it: each carries what std-audio-cue resolved (the sound or track to play, or the
+ * music fade-out length), so the provider plays it as given.
  *
  * The provider also exposes `muted`/`setMuted` and `masterVolume`/
  * `setMasterVolume` via the `GameAudioContext` for toggle buttons.
@@ -17,7 +18,7 @@
 
 import React, { createContext, useContext, useEffect } from 'react';
 import { registerHostAudio } from '../lib/host-actions';
-import { useGameAudio, type AudioManifest, type GameAudioControls } from '../hooks/useGameAudio';
+import { useGameAudio, type GameAudioControls } from '../hooks/useGameAudio';
 import type { UiError } from '../core';
 
 // =============================================================================
@@ -25,7 +26,7 @@ import type { UiError } from '../core';
 // =============================================================================
 
 export type GameAudioContextValue = Pick<GameAudioControls,
-    'muted' | 'setMuted' | 'masterVolume' | 'setMasterVolume' | 'play' | 'playMusic' | 'stopMusic'
+    'muted' | 'setMuted' | 'masterVolume' | 'setMasterVolume' | 'playPlan' | 'playMusicPlan' | 'stopMusic'
 >;
 
  
@@ -58,10 +59,6 @@ export function useGameAudioContextOptional(): GameAudioContextValue | null {
 // =============================================================================
 
 export interface GameAudioProviderProps {
-    /** Sound manifest — keys mapped to SoundEntry definitions */
-    manifest: AudioManifest;
-    /** Base URL prepended to all sound paths (default '') */
-    baseUrl?: string;
     /** Children to render */
     children: React.ReactNode;
     /** Initial muted state */
@@ -77,27 +74,23 @@ export interface GameAudioProviderProps {
 // =============================================================================
 
 export function GameAudioProvider({
-    manifest,
-    baseUrl = '',
     children,
     initialMuted = false,
 }: GameAudioProviderProps): React.JSX.Element {
-    const { play, stop, stopAll, playMusic, stopMusic, muted, setMuted, masterVolume, setMasterVolume } =
-        useGameAudio({ manifest, baseUrl, initialMuted });
+    const { playPlan, playMusicPlan, stop, stopAll, stopMusic, muted, setMuted, masterVolume, setMasterVolume } =
+        useGameAudio({ initialMuted });
 
     // The `audio/*` asks the kernel makes reach this provider's audio
     useEffect(() => registerHostAudio((ask) => {
-        if (ask.op === 'audio/play-sound') play(ask.key);
+        if (ask.op === 'audio/play-sound') playPlan(ask.play);
         else if (ask.op === 'audio/stop-sound') {
             if (ask.key !== undefined) stop(ask.key);
             else stopAll();
-        } else if (ask.op === 'audio/change-music') {
-            if (ask.key !== undefined) playMusic(ask.key);
-            else stopMusic();
-        } else stopMusic();
-    }), [play, stop, stopAll, playMusic, stopMusic]);
+        } else if (ask.op === 'audio/change-music') playMusicPlan(ask.play);
+        else stopMusic(ask.fadeMs);
+    }), [playPlan, playMusicPlan, stop, stopAll, stopMusic]);
 
-    const value: GameAudioContextValue = { muted, setMuted, masterVolume, setMasterVolume, play, playMusic, stopMusic };
+    const value: GameAudioContextValue = { muted, setMuted, masterVolume, setMasterVolume, playPlan, playMusicPlan, stopMusic };
 
     return (
         <GameAudioContext.Provider value={value}>

package/templates/almadar-renderers-typescript/src/providers/KernelEngineContext.tsx

@@ -15,6 +15,7 @@ import { installNativeLanguages } from '@almadar/syntax';
 import type { KernelLoader, KernelModule } from '../lib/kernel-wire';
 import type { FrameScheduler } from '../lib/kernel-frames';
 import type { OsHostPort } from '@almadar/shell-runtime/kernel/os-port';
+import type { KernelCanvas3DFactory, KernelGpuHost, KernelSceneCanvasFactory } from '@almadar/shell-runtime/kernel/wire';
 
 export interface KernelEngineValue {
   /** Resolves the initialised `@almadar/kernel` module, its language installed (`@almadar/shell-browser/kernel-loader`); shared by every circuit under the provider. */
@@ -23,6 +24,12 @@ export interface KernelEngineValue {
   scheduleFrame?: FrameScheduler;
   /** The host's `os` port (`createFetchOsHost(fetch)`) every local-store kernel under the provider is opened with; absent, a program's `os` asks are denied. */
   os?: OsHostPort;
+  /** The host's GPU answerer (the kernel module's `GpuHost`), made once after the module loads and installed into every circuit kernel under the provider; absent, a `gpu/` ask answers `unsupported`. */
+  gpu?: () => KernelGpuHost;
+  /** Makes an orbital-canvas 3D view on a page canvas once the module has loaded; absent, a 3D canvas has no renderer. */
+  canvas3d?: KernelCanvas3DFactory;
+  /** Makes an orbital-canvas scene canvas (2D instruments, diagrams) on a page canvas once the module has loaded. */
+  sceneCanvas?: KernelSceneCanvasFactory;
 }
 
 export const KernelEngineContext = createContext<KernelEngineValue | null>(null);
@@ -43,10 +50,16 @@ export interface KernelEngineProviderProps {
   loader: KernelLoader;
   scheduleFrame?: FrameScheduler;
   os?: OsHostPort;
+  /** Makes the host's GPU answerer once the module has loaded (`() => new GpuHost()`). */
+  gpu?: () => KernelGpuHost;
+  /** Makes a 3D view on a page canvas (`(canvas) => Canvas3D.create(canvas)`). */
+  canvas3d?: KernelCanvas3DFactory;
+  /** Makes a scene canvas on a page canvas (`(canvas) => SceneCanvas.create(canvas)`). */
+  sceneCanvas?: KernelSceneCanvasFactory;
   children?: ReactNode;
 }
 
-export function KernelEngineProvider({ loader, scheduleFrame, os, children }: KernelEngineProviderProps): React.ReactElement {
+export function KernelEngineProvider({ loader, scheduleFrame, os, gpu, canvas3d, sceneCanvas, children }: KernelEngineProviderProps): React.ReactElement {
   const value = useMemo<KernelEngineValue>(() => {
     let module: Promise<KernelModule> | undefined;
     const load = (): Promise<KernelModule> =>
@@ -55,11 +68,16 @@ export function KernelEngineProvider({ loader, scheduleFrame, os, children }: Ke
         installNativeLanguages();
         return loaded;
       });
+    let gpuHost: KernelGpuHost | undefined;
+    const loadModule = (): Promise<KernelModule> => (module ??= load());
     return {
-      loadModule: () => (module ??= load()),
+      loadModule,
       ...(scheduleFrame !== undefined ? { scheduleFrame } : {}),
       ...(os !== undefined ? { os } : {}),
+      ...(gpu !== undefined ? { gpu: () => (gpuHost ??= gpu()) } : {}),
+      ...(canvas3d !== undefined ? { canvas3d: (canvas: HTMLCanvasElement) => loadModule().then(() => canvas3d(canvas)) } : {}),
+      ...(sceneCanvas !== undefined ? { sceneCanvas: (canvas: HTMLCanvasElement) => loadModule().then(() => sceneCanvas(canvas)) } : {}),
     };
-  }, [loader, scheduleFrame, os]);
+  }, [loader, scheduleFrame, os, gpu, canvas3d, sceneCanvas]);
   return <KernelEngineContext.Provider value={value}>{children}</KernelEngineContext.Provider>;
 }