@volter/editor-threejs 0.5.211 → 0.5.212

package/src/kit/components/standard-viewport-dressing.ts

@@ -1,51 +1,26 @@
 /**
- * The STANDARD VIEWPORT dressing — the ONE chrome-and-dressing definition every
- * 3D document viewport inherits (owner-ratified contract). A document surface
- * (`Object3DDocumentViewport` and everything mounted on it: the 3D board,
- * story turntables, model/entity asset documents) gets the editor's standard
- * look from this module instead of instantiating its own background/lighting:
- *
- *  - `scene.environment` baked from three's own `RoomEnvironment` through
- *    `PMREMGenerator`, so PBR materials actually read;
- *  - a subtle dark vertical-gradient backdrop (never a flat hex);
- *  - one NEUTRAL directional key light for definition (it was warm; see the
- *    measurement where it is constructed);
- *  - an optional ground grid following the Scene viewport's grid conventions
- *    (1 m cells, `0x999999`, `EDITOR_LAYER` — see `editor-viewport.ts`),
- *    centred on the content and fading out with distance so it never
- *    degenerates into convergence-line artifacts at the horizon.
- *
- * Everything created here is EDITOR CHROME: marked per `editor-layers.ts`'s
- * conventions (`userData.editorHelper`, and `EDITOR_LAYER` for the grid) so no
- * hierarchy walk, pick, or export ever mistakes it for content — and it is
- * never serialized, never touching project data (the anti-shim rule). It
- * exists only inside the document viewport's scene at view time.
- *
- * Ownership: {@link applyStandardViewportDressing} owns every object and
- * texture it creates, INCLUDING the {@link StandardEnvironment} handed to it
- * (PMREM render targets leak if not disposed). Its returned `dispose` is the
- * one teardown path; it is idempotent.
- *
- * The environment bake lives in `@volter/editor-threejs/viewport/environment`
- * because it is the one GL-bound step — it needs a live `WebGLRenderer`,
- * where the rest of the dressing is plain scene-graph work.
+ * Standard dressing for 3D document viewports: a supplied environment for PBR materials, gradient
+ * backdrop and optional ground grid centered on content. Mark all objects as
+ * editor furniture and keep them out of authored data. applyStandardViewportDressing owns its
+ * objects, textures and supplied StandardEnvironment, and returns an idempotent disposer. The
+ * renderer-dependent bake belongs to viewport/environment.
  */
 
-import { invalidateStages } from '@volter/sdk/kit/stage-invalidation';
+import { invalidateStages } from '@volter/sdk/stage-invalidation';
 import { contentWorldBounds } from '@volter/editor-threejs/viewport/content-bounds';
 import { EDITOR_LAYER } from '@volter/editor-threejs/viewport/editor-layers';
 import { loadEnvironmentImage, type StandardEnvironment } from '@volter/editor-threejs/viewport/environment';
 import { setUserData } from '@volter/editor-threejs/ecs/user-data';
 import * as THREE from 'three';
-import { environmentImage } from '@volter/sdk/kit/environment-images';
-import { editorConsole } from '@volter/sdk/kit/editor-console';
+import { environmentImage } from '@volter/sdk/environment-images';
+import { editorConsole } from '@volter/sdk/editor-console';
 import {
   studioPreset,
   type StudioLight,
   type SceneTakeover,
   type StudioPreset,
   type ViewportPresentation,
-} from '@volter/sdk/kit/viewport-presentation';
+} from '@volter/sdk/viewport-presentation';
 
 /**
  * Front-right three-quarter view for project-owned R3F components. Their
@@ -62,21 +37,13 @@ export const STANDARD_COMPONENT_CAMERA_DIRECTION = [0.8, 0.5, -1] as const;
 const GRADIENT_BOTTOM = new THREE.Color(0x1e2530);
 const GRADIENT_TOP = new THREE.Color(0x4c5b70);
 
-export interface BackdropStops {
+interface BackdropStops {
   readonly bottom: THREE.Color;
   readonly top: THREE.Color;
 }
 
-/**
- * The backdrop's stops for the ACTIVE PALETTE: the ground line is the
- * palette's panel surface and the top is its raised surface, each blended
- * with the studio tint and lifted for ACES. Measured under the Blender
- * palette (panel #303030, raised #3d3d3d) the stage reads as Blender's grey
- * ground instead of a black void; under Classic Graphite it stays within a
- * few steps of the studio constants. Falls back to the studio constants
- * where no palette is installed (a bounded host, headless).
- */
-export function paletteBackdropStops(): BackdropStops {
+/** Blend palette panel and raised surfaces with studio tint for the backdrop. Use studio constants when no palette is installed. */
+function paletteBackdropStops(): BackdropStops {
   const root =
     typeof document === 'undefined' ? null : document.querySelector('[data-volter-palette]');
   if (!root) return { bottom: GRADIENT_BOTTOM.clone(), top: GRADIENT_TOP.clone() };
@@ -100,11 +67,7 @@ export function paletteBackdropStops(): BackdropStops {
   };
   const panel = read('--volter-surface-panel', GRADIENT_BOTTOM);
   const raised = read('--volter-surface-raised', GRADIENT_TOP);
-  // A background texture is not tone-mapped, so what is authored here is
-  // what the screen shows. The small lift keeps the ground a step above the
-  // panel it sits beside (Blender's viewport is lighter than its editors).
-  // Measured on screen under the Blender palette: ground #40, top #50, beside
-  // Blender's own #3f–#4e.
+  // Background textures bypass tone mapping; lift the authored gradient slightly above the neighbouring panel.
   const bottom = panel.lerp(GRADIENT_BOTTOM, 0.25).lerp(new THREE.Color(0xffffff), 0.03);
   const top = raised.lerp(GRADIENT_TOP, 0.25).lerp(new THREE.Color(0xffffff), 0.04);
   return { bottom, top };
@@ -114,8 +77,7 @@ export function paletteBackdropStops(): BackdropStops {
  * Fires when the palette the backdrop follows changes. The theme installer
  * stamps its root with `data-volter-palette` / `data-volter-material` on every
  * switch, so the DOM is the contract here — a document stage never imports
- * the shell's preference store (its closure is pinned,
- * `scripts/validate-editor-closure.mjs`). Returns the unsubscribe.
+ * the shell's preference store. Returns the unsubscribe.
  */
 export function watchPaletteBackdrop(onChange: () => void): () => void {
   if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') return () => {};
@@ -133,18 +95,13 @@ export function watchPaletteBackdrop(onChange: () => void): () => void {
 }
 
 /** One 1×N vertical-gradient strip; the renderer stretches it full-frame. */
-export function createGradientBackgroundTexture(
-  stops: BackdropStops = paletteBackdropStops(),
-): THREE.DataTexture {
+export function createGradientBackgroundTexture(): THREE.DataTexture {
+  const stops = paletteBackdropStops();
   const height = 128;
   const data = new Uint8Array(height * 4);
   const color = new THREE.Color();
   for (let row = 0; row < height; row++) {
-    // Row 0 is the BOTTOM of the texture, so the gradient runs ground → sky.
-    // `Color` holds LINEAR components under colour management while the
-    // texture below is declared sRGB, so the bytes are encoded on the way
-    // out — written raw, every stop rendered several steps darker than
-    // authored (measured: the stage read #050506 for a #1e2530 stop).
+    // Row zero is the texture bottom. Encode Color’s linear components to sRGB bytes for the declared texture colour space.
     color
       .copy(stops.bottom)
       .lerp(stops.top, row / (height - 1))
@@ -203,28 +160,9 @@ function gridDivisions(size: number): number {
  * reference; the band scales with `gridFrameForScene`, which already tracks
  * the content. Injection at `color_fragment` is where `LineBasicMaterial` has
  * `diffuseColor` in scope.
- *
- * Exported because the dressing OWNS the grid treatment: `editor-viewport.ts`
- * applies the same fade to its own editing grid, so no viewport anywhere ends
- * a grid on a hard aliasing rim.
  */
-export function applyGridDistanceFade(material: THREE.Material, gridSize: number): void {
-  // The band ends at the grid's own extent: it exists so the floor never ends
-  // on a hard rim, not to shrink the floor. The old 0.18/0.42 band was tuned
-  // for a camera standing close — a document that opens further back (the
-  // Model document's `openingFit`) photographed a floor with NO visible grid
-  // at all, measured against Blender's uniform lattice.
-  //
-  // `gridSize` is `GridHelper`'s size, which is the grid's DIAMETER — it spans
-  // ±size/2 — while the shader below compares against a RADIUS
-  // (`length(vGridPlanePosition)`). Comparing the two directly put the whole
-  // band outside the geometry: on a 400 m grid the fade started at 220 m when
-  // the farthest point along either axis is 200 m, so alpha never left 1.0 and
-  // the floor ended on exactly the hard rim this function exists to prevent
-  // (measured against Blender: our horizon stepped from #3f3f3f to #4f4f4f in
-  // four scanlines across the full stage width, Blender's held #3f3f3f-#41
-  // throughout). The band is a fraction of the RADIUS, so it reaches zero at
-  // the grid's edge, where the fade belongs.
+function applyGridDistanceFade(material: THREE.Material, gridSize: number): void {
+  // Fade to zero at the grid’s radius (half GridHelper’s size), retaining a band proportional to that radius.
   const gridRadius = gridSize / 2;
   const fadeStart = gridRadius * 0.55;
   const fadeEnd = gridRadius;
@@ -251,30 +189,23 @@ export function applyGridDistanceFade(material: THREE.Material, gridSize: number
   material.customProgramCacheKey = () => `volter-grid-fade:${fadeStart}:${fadeEnd}`;
 }
 
-export interface StandardViewportDressingOptions {
+interface StandardViewportDressingOptions {
   /**
    * The baked IBL from `@volter/editor-threejs/viewport/environment`; `null` opts the
    * scene out of an environment entirely. Ownership transfers here.
    */
   readonly environment: StandardEnvironment | null;
-  /** Apply the vertical-gradient backdrop. Default `true`; a host whose
-   *  backdrop lives elsewhere (the Asset Lab's alpha-canvas studio stage, an
-   *  explicit SDK-contributed background) opts out. */
-  readonly background?: boolean;
-  /** Add the warm directional key light. Default `true`; a source that
-   *  authors its own lights opts out — authored lighting always wins. */
-  readonly keyLight?: boolean;
-  /** Add the ground grid (content standing on y=0 by design). Default `false`. */
-  readonly grid?: boolean;
-  readonly content?: THREE.Object3D;
+  /** Apply the vertical-gradient backdrop unless the stage paints its background elsewhere. */
+  readonly background: boolean;
+  /** Add the ground grid, centered on the content's footprint. */
+  readonly grid: boolean;
+  readonly content: THREE.Object3D;
 }
 
 export interface StandardViewportDressing {
   /** The gradient applied to `scene.background`, or `null` when opted out —
    *  hosts hand it on (e.g. as a document session's neutral background). */
   readonly backgroundTexture: THREE.Texture | null;
-  /** The dressing's lights, for hosts whose lighting presets retune them. */
-  readonly lights: readonly THREE.Light[];
   frameContent(content: THREE.Object3D): void;
   /** The ONE teardown path for everything this dressing created. Idempotent. */
   dispose(): void;
@@ -285,9 +216,7 @@ export function applyStandardViewportDressing(
   scene: THREE.Scene,
   options: StandardViewportDressingOptions,
 ): StandardViewportDressing {
-  const { environment, background = true, keyLight = true, grid = false } = options;
-  const chrome: THREE.Object3D[] = [];
-  const lights: THREE.Light[] = [];
+  const { environment, background, grid } = options;
   let backgroundTexture: THREE.DataTexture | null = null;
 
   if (environment) scene.environment = environment.texture;
@@ -297,22 +226,6 @@ export function applyStandardViewportDressing(
     scene.background = backgroundTexture;
   }
 
-  if (keyLight) {
-    // The kit's own key, warm, as the kit studio preset states it (`KIT_STUDIO_PRESET`). A
-    // document stage is lit by its view's presentation instead (`StagePresentationRig`, and
-    // `StageHost` turns this key off); a stage without a presentation still gets this one.
-    const key = new THREE.DirectionalLight(0xfff3dd, 1.9);
-    key.name = 'volter:standard-dressing-key';
-    key.position.set(6, 10, -4);
-    key.castShadow = true;
-    // `userData.editorHelper` keeps it out of hierarchy walks and picks;
-    // layers stay default so it lights layer-0 content under any camera.
-    setUserData(key, 'editorHelper', true);
-    scene.add(key);
-    chrome.push(key);
-    lights.push(key);
-  }
-
   let gridHelper: THREE.GridHelper | null = null;
   let gridFrame = '';
   const frameContent = (content: THREE.Object3D) => {
@@ -324,7 +237,6 @@ export function applyStandardViewportDressing(
     if (gridHelper) {
       gridHelper.removeFromParent();
       gridHelper.dispose();
-      chrome.splice(chrome.indexOf(gridHelper), 1);
     }
     // The Scene viewport's grid color (`editor-viewport.ts`), softened with
     // transparency so it reads as a ground reference under the gradient
@@ -343,23 +255,18 @@ export function applyStandardViewportDressing(
     helper.layers.set(EDITOR_LAYER);
     setUserData(helper, 'editorHelper', true);
     scene.add(helper);
-    chrome.push(helper);
   };
-  frameContent(options.content ?? scene);
+  frameContent(options.content);
 
   let disposed = false;
   return {
     backgroundTexture,
-    lights,
     frameContent,
     dispose(): void {
       if (disposed) return;
       disposed = true;
-      for (const object of chrome) {
-        object.removeFromParent();
-        // GridHelper frees its geometry+material; Light frees its shadow map.
-        (object as { dispose?: () => void }).dispose?.();
-      }
+      gridHelper?.removeFromParent();
+      gridHelper?.dispose();
       if (environment) {
         if (scene.environment === environment.texture) scene.environment = null;
         environment.dispose();
@@ -373,34 +280,15 @@ export function applyStandardViewportDressing(
 }
 
 /**
- * THE STAGE'S LIGHTING, FROM ITS PRESENTATION — the Three half of
- * `@volter/sdk/kit/viewport-presentation`. A 3D document stage owns one rig; it draws
- * the view's `studio` lighting (a preset's lights, world-fixed or camera-locked, and its
- * ambient), sets the renderer's tone mapper and exposure, and answers the image-based light's
- * strength. It replaces the lights that were fixed in code: the dressing's key and the
- * viewport's own ambient and directional (`docs/VIEWPORT-STAGE.md` §The ruling). It moves to
- * `@volter/editor-threejs` with the rest of the assembled viewport (ARCHITECTURE.md, the plan,
- * unit 3).
- *
- * A `studio` draw lights by its preset alone: the stage darkens the content's own lights for
- * that draw and restores them after it (`Object3DDocumentHost.darkenContentLights`). The
- * `document` preset is the document's own view-locked studio (Blender's Solid lights), which the
- * document manages together with its scene's lights.
- *
- * Not yet: the `preview` source (a sun and a sky) draws nothing, and a Blender document's
- * `scene` source draws unlit, because Blender's render lighting lives in the Blender engine
- * (`BlenderRuntimeView.setRendered`) rather than as lights in the document's content.
+ * Stage lighting from viewport-presentation: own the studio preset’s lights and ambient term, apply
+ * tone mapping and exposure, and report environment intensity. Studio drawing temporarily darkens
+ * authored lights. The document preset leaves its view-locked lighting and scene-light management
+ * to the document; Blender render lighting belongs to BlenderRuntimeView.setRendered.
  */
 const LIGHT_DISTANCE = 12;
 
-/**
- * GODOT'S FILMIC CURVE as three's one custom tone mapper: John Hable's curve with Godot's
- * exposure bias of 2, divided by the curve at the white point so white stays white
- * (`servers/rendering/renderer_rd/shaders/effects/tonemap.glsl`, `tonemap_filmic`, at
- * Godot's default `tonemap_white` of 1.0). three's own curves map white to about 0.8, which
- * drew Godot's sun grey. Installed once, into three's `CustomToneMapping` slot, which nothing
- * else on the page fills.
- */
+/** Godot's Hable filmic curve, with exposure bias 2 and normalization at its default white point 1.
+ * Installed in three's CustomToneMapping slot. */
 const GODOT_FILMIC = /* glsl */ `
 vec3 volterHable( vec3 x ) {
 	const float A = 0.22 * 4.0;
@@ -572,8 +460,8 @@ export class StagePresentationRig {
     new THREE.PlaneGeometry(FLOOR_EXTENT, FLOOR_EXTENT).rotateX(-Math.PI / 2),
     fadingFloorMaterial(),
   );
-  /** The preview sky, built from its three colours: the background drawn behind the scene and
-   *  the environment that lights it, rebuilt only when the colours change. */
+  /** The preview's background and environment, keyed by image identity or procedural
+   * colours, curves, clouds and sun. */
   private sky: {
     key: string;
     /** The environment image drawn, or `null` for the procedural strip. */
@@ -612,7 +500,7 @@ export class StagePresentationRig {
     this.floor.name = 'volter:preview-floor';
     this.floor.userData['editorHelper'] = true;
     this.floor.receiveShadow = true;
-    // Transparent now (its fade), so it is sorted with the grid: drawn first, under it.
+    // The fading floor is transparent and sorts with the grid; draw it first, beneath the grid.
     this.floor.renderOrder = -1;
     this.floor.visible = false;
     scene.add(this.floor);
@@ -649,8 +537,7 @@ export class StagePresentationRig {
     const altitude = THREE.MathUtils.degToRad(sun.altitude);
     const azimuth = THREE.MathUtils.degToRad(sun.azimuth);
     this.sun.color.set(sun.color);
-    // Godot's energy as three's intensity, unscaled: the unit mapping is measured against
-    // Godot's own frames, not assumed.
+    // Map Godot light energy directly to three intensity.
     this.sun.intensity = sun.enabled ? sun.energy : 0;
     this.sun.position
       .set(Math.sin(azimuth) * Math.cos(altitude), Math.sin(altitude), -Math.cos(azimuth) * Math.cos(altitude))
@@ -734,7 +621,7 @@ export class StagePresentationRig {
         this.pendingImage = { id: image.id, state: 'failed' };
         editorConsole.error(`Environment image "${image.id}" (${image.url}) did not load: ${String(error)}`, 'viewport');
         // The view still names it, so what stands is the procedural sky, never the last image.
-        this.latestSky?.();
+        this.latestSky!();
         this.onReady?.();
       });
   }
@@ -773,20 +660,13 @@ export class StagePresentationRig {
   }
 
   /**
-   * THE PREVIEW SKY, Godot's `ProceduralSkyMaterial`: above the horizon the horizon colour runs
-   * to the top colour on the sky's top curve (Godot's 0.15), below it to the ground colour on its
-   * ground curve (Godot's 0.02), mixed in linear light (`scene/resources/3d/sky_material.cpp`). THE SUN in
-   * it follows the same material: inside the light's disc the sky is the sun's colour at its
-   * energy, and out to `sun_angle_max` (30°) it returns to the sky on a curve of `sun_curve`
-   * (0.15). A light with no angular size draws a half-degree disc.
-   *
-   * Drawn into a HALF-FLOAT equirectangular strip, because the sun is brighter than white: an 8-bit
-   * strip clipped it to 1.0, which the tone curve draws as grey 202 (measured) where Godot's
-   * sun blows out. Half, not full, float: a full-float strip cannot be linearly filtered where
-   * `OES_texture_float_linear` is missing (common on phones) and would draw black. The strip is
-   * both the backdrop and, prefiltered, the light; 1024 across,
-   * because the sun's bright core is about 3° wide and drew as two pixels at 256. Placed by
-   * three's equirectangular mapping (`atan(z, x)`, `asin(y)`); row 0 is straight down.
+   * Build the preview sky from Godot’s ProceduralSkyMaterial curves in linear light: horizon to top
+   * above the horizon, horizon to ground below it, and the light’s disc to sky across
+   * sun_angle_max, with a fixed half-degree disc. The half-float
+   * equirectangular strip preserves sun energy above white while supporting linear filtering
+   * without OES_texture_float_linear. Its 1024-pixel width resolves the bright core. Three’s
+   * mapping uses atan(z, x) and asin(y), with row zero pointing down. The strip supplies both the
+   * backdrop and the prefiltered lighting.
    */
   private buildSky(
     colours: ViewportPresentation['lighting']['preview']['environment']['sky'],

package/src/kit/components/world-root-binding.ts

@@ -10,12 +10,11 @@
  * which a modeling host never carries — so the package hands the host this
  * binding and the host loads it only for a stage that shows a world.
  */
-import type { ComponentType, RefObject } from 'react';
+import type { ComponentType } from 'react';
 import type * as THREE from 'three';
 import type { EditorShellStore } from '../editor-shell-store';
-import type { EditorStats } from '@volter/sdk/kit/editor-runtime';
+import type { EditorStats } from '@volter/sdk/editor-runtime';
 import type { EditorViewport } from '../editor-viewport';
-import type { ViewportPresentation, ViewportRoot } from '../../viewport-api';
 
 export interface WorldRootStageOptions {
   /** The session's store: the world is the session's own subject. */
@@ -25,8 +24,6 @@ export interface WorldRootStageOptions {
   readonly canvas: HTMLCanvasElement;
   readonly renderer: THREE.WebGLRenderer;
   readonly stats: EditorStats;
-  /** The camera-authoring preview pane, read per frame (a React ref). */
-  readonly cameraPreview: () => HTMLDivElement | null;
   readonly onMountStatus: (status: 'mounting' | 'ready') => void;
   readonly onRootIds: (rootIds: readonly string[]) => void;
   /** This stage's frame hook on the per-stage viewport door. */
@@ -37,7 +34,6 @@ export interface WorldRootStage {
   readonly scene: THREE.Scene;
   readonly viewport: EditorViewport;
   frame(timeMs: number, resumed: boolean): void;
-  present(roots: readonly ViewportRoot[]): ViewportPresentation | null;
   setHelper(kind: string, object: THREE.Object3D | null): void;
   dispose(): void;
 }
@@ -46,7 +42,6 @@ export interface WorldRootOverlayProps {
   readonly store: EditorShellStore;
   /** The stage's own document — its stage context is read by this id. */
   readonly documentId: string;
-  readonly cameraPreviewRef: RefObject<HTMLDivElement | null>;
   readonly mountStatus: 'mounting' | 'ready';
   readonly rootIds: readonly string[];
 }

package/src/kit/constraint-helper.ts

@@ -115,7 +115,7 @@ export class ConstraintHelper extends THREE.Group {
   }
 
   /** True when this helper is already the native viewport presentation for
-   * the object. Such nodes must not also receive the legacy corner-bracket
+   * the object. Such nodes must not also receive the corner-bracket
    * fallback: the constraint lines/handle are their visible representation. */
   presents(object: THREE.Object3D): boolean {
     if (object === this.source) return true;

package/src/kit/document-renderer-session.ts

@@ -0,0 +1,114 @@
+import {
+  isEditorPresentationActive,
+  subscribeEditorPresentationActivity,
+} from './editor-presentation-activity';
+
+/** Keep the renderer when a document deactivates: stop its loop and shrink the buffer while retaining geometry and program state. Dispose the context only when the document closes. */
+
+export class DocumentRendererSession {
+  private rafId = 0;
+  private running = false;
+  private disposed = false;
+  private active = false;
+  private readonly unsubscribeActivity: () => void;
+
+  constructor(
+    private readonly frame: (time: number, resumed: boolean) => void,
+    private readonly releaseRenderer: () => void,
+  ) {
+    this.unsubscribeActivity = subscribeEditorPresentationActivity(() => this.syncActivity());
+  }
+
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Tab flip. `false` pauses the loop and keeps the GPU surface. `true`
+   * resumes it. Neither constructs nor disposes a renderer.
+   */
+  setActive(active: boolean): void {
+    if (this.disposed) return;
+    this.active = active;
+    this.syncActivity();
+  }
+
+  private syncActivity(): void {
+    if (this.active && isEditorPresentationActive()) this.start();
+    else this.stop();
+  }
+
+  /** Resizing clears the drawing buffer. Repaint immediately while visible;
+   * a suspended document redraws as soon as its presentation resumes. */
+  redraw(): void {
+    if (this.running && !this.disposed && isEditorPresentationActive()) {
+      this.guardedFrame(performance.now());
+    }
+  }
+
+  /** The one teardown path — document CLOSE / host unmount. */
+  dispose(): void {
+    this.stop();
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unsubscribeActivity();
+    this.releaseRenderer();
+  }
+
+  private start(): void {
+    if (this.disposed || this.running) return;
+    this.running = true;
+    // A tab activation is a direct request to present this document. Draw one
+    // frame in the activation turn, then join the browser's animation clock.
+    // Waiting for the first rAF would make a visible tab inherit Chromium's
+    // background cadence (the 1 Hz signature) even when the page itself is
+    // visible, showing the stale canvas for that whole interval. Subsequent
+    // presentation remains ordinary rAF-driven work.
+    // Let content reset its delta baseline without advancing by the hidden interval.
+    this.guardedFrame(performance.now(), true);
+    if (!this.running || this.disposed) return;
+    this.rafId = requestAnimationFrame(this.tick);
+  }
+
+  /** The last frame's failure text, so a persistent fault narrates ONCE
+   *  rather than sixty times a second, and a recovered loop resets. */
+  private lastFrameFailure: string | null = null;
+
+  /** Catch frame failures, report them through the document channel and schedule the next frame so presentation can recover. */
+  private guardedFrame(time: number, resumed = false): void {
+    try {
+      this.frame(time, resumed);
+      this.lastFrameFailure = null;
+    } catch (caught) {
+      const text = caught instanceof Error ? caught.message : String(caught);
+      if (text !== this.lastFrameFailure) {
+        this.lastFrameFailure = text;
+        // biome-ignore lint/suspicious/noConsole: a document frame that threw must narrate itself
+        console.error('[document renderer] a frame threw; the loop continues:', caught);
+      }
+    }
+  }
+
+  private stop(): void {
+    this.running = false;
+    if (this.rafId !== 0) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = 0;
+    }
+  }
+
+  private readonly tick = (time: number): void => {
+    if (!this.running || this.disposed) return;
+    if (!isEditorPresentationActive()) {
+      this.stop();
+      return;
+    }
+    this.guardedFrame(time);
+    if (!this.running || this.disposed) return;
+    this.rafId = requestAnimationFrame(this.tick);
+  };
+}

package/src/kit/editor-presentation-activity.ts

@@ -0,0 +1,58 @@
+/** Host visibility controls presentation work, never document ownership. */
+interface PresentationActivity {
+  hostActive: boolean;
+  readonly listeners: Set<() => void>;
+}
+
+// Existing renderer sessions can survive a replacement of this module. Keep
+// their subscriptions and the host's last answer on the same shared object.
+/** Vite's HMR context when a dev server serves this module, typed here so the SDK carries no
+ *  bundler types. */
+const hot = (import.meta as ImportMeta & {
+  hot?: {
+    data?: { presentationActivity?: PresentationActivity };
+    dispose(callback: () => void): void;
+  };
+}).hot;
+const hotData = hot?.data;
+const activity: PresentationActivity = hotData?.presentationActivity ?? {
+  hostActive: true,
+  listeners: new Set<() => void>(),
+};
+if (hotData) hotData.presentationActivity = activity;
+
+export function isEditorPresentationActive(): boolean {
+  return activity.hostActive && (typeof document === 'undefined' || !document.hidden);
+}
+function changed(): void {
+  for (const listener of activity.listeners) listener();
+}
+
+const parentOrigin =
+  typeof document !== 'undefined' && document.referrer ? new URL(document.referrer).origin : null;
+
+function receive(event: MessageEvent): void {
+  if (window.parent === window || event.source !== window.parent) return;
+  if (!parentOrigin || event.origin !== parentOrigin) return;
+  if (event.data?.type !== 'volter:embed-activity' || typeof event.data.active !== 'boolean') return;
+  if (activity.hostActive === event.data.active) return;
+  activity.hostActive = event.data.active;
+  changed();
+}
+export function subscribeEditorPresentationActivity(listener: () => void): () => void {
+  activity.listeners.add(listener);
+  return () => {
+    activity.listeners.delete(listener);
+  };
+}
+if (typeof window !== 'undefined') {
+  window.addEventListener('message', receive);
+  document.addEventListener('visibilitychange', changed);
+  if (window.parent !== window && parentOrigin) {
+    window.parent.postMessage({ type: 'volter:request-embed-activity' }, parentOrigin);
+  }
+  hot?.dispose(() => {
+    window.removeEventListener('message', receive);
+    document.removeEventListener('visibilitychange', changed);
+  });
+}