@opsydyn/effect-three-foldkit 0.0.0-stage → 0.2.0

package/src/element.ts

@@ -0,0 +1,114 @@
+/**
+ * The `<effect-three-scene>` element: a typed `scene` property that Foldkit diffs on
+ * every render, and Schema-decoded events that become the app's typed Messages.
+ *
+ * The tag is never registered with `customElements`; the scene Mount intercepts the
+ * property instead (ADR-002), so there is nothing to re-register under HMR or SSR.
+ *
+ * @module
+ */
+import { SceneSchema, type SceneEvent } from '@opsydyn/effect-three';
+import { Schema } from 'effect';
+import { CustomElement } from 'foldkit';
+import { defineMessageUnion } from 'foldkit/message';
+
+/** A scene update that could not be applied. The scene keeps its last good state. */
+export const SceneError = Schema.Union([
+  ...SceneSchema.DescriptionError.members,
+  Schema.TaggedStruct('MalformedScene', { issue: Schema.String }),
+]);
+export type SceneError = typeof SceneError.Type;
+
+const Counts = Schema.Struct({ live: Schema.Int, created: Schema.Int, disposed: Schema.Int });
+
+/** What one scene update did, and the GPU resources held afterwards. */
+export const ReconciledDetail = Schema.Struct({
+  ops: Schema.Struct({
+    created: Schema.Int,
+    updated: Schema.Int,
+    moved: Schema.Int,
+    removed: Schema.Int,
+    replaced: Schema.Int,
+    reordered: Schema.Int,
+    configured: Schema.Int,
+  }),
+  resources: Schema.Struct({ geometries: Counts, materials: Counts }),
+});
+export type ReconciledDetail = typeof ReconciledDetail.Type;
+
+/** An immersive session began presenting the scene in `mode`, or ended (`null`). */
+export const XrSessionDetail = Schema.Struct({
+  mode: Schema.NullOr(Schema.Literals(['immersive-vr', 'immersive-ar'])),
+});
+export type XrSessionDetail = typeof XrSessionDetail.Type;
+
+export const sceneElement = CustomElement.define({
+  tag: 'effect-three-scene',
+  properties: { scene: SceneSchema.SceneDescription },
+  events: {
+    'scene-click': SceneSchema.ButtonDetail,
+    'scene-double-click': SceneSchema.ButtonDetail,
+    'scene-context-menu': SceneSchema.HitDetail,
+    'scene-pointer-down': SceneSchema.ButtonDetail,
+    'scene-pointer-up': SceneSchema.ButtonDetail,
+    'scene-pointer-enter': SceneSchema.HitDetail,
+    'scene-pointer-move': SceneSchema.HitDetail,
+    'scene-pointer-leave': SceneSchema.KeyDetail,
+    'scene-pointer-missed': SceneSchema.MissDetail,
+    'scene-wheel': SceneSchema.WheelDetail,
+    'scene-drag': SceneSchema.DragDetail,
+    'scene-drag-end': SceneSchema.DragDetail,
+    'scene-gesture': SceneSchema.GestureDetail,
+    'scene-auto-rotated': SceneSchema.AutoRotatedDetail,
+    'scene-collision': SceneSchema.CollisionDetail,
+    'scene-contact-force': SceneSchema.ContactForceDetail,
+    'scene-measured': SceneSchema.MeasuredDetail,
+    'scene-label-measured': SceneSchema.LabelMeasuredDetail,
+    'scene-xr': XrSessionDetail,
+    'scene-xr-stick': SceneSchema.XrStickDetail,
+    'scene-xr-button': SceneSchema.XrButtonDetail,
+    'scene-xr-surface': SceneSchema.XrSurfaceDetail,
+    'scene-xr-moved': SceneSchema.XrMovedDetail,
+    'scene-xr-planes': SceneSchema.XrPlanesDetail,
+    'scene-xr-meshes': SceneSchema.XrMeshesDetail,
+    'scene-performance': SceneSchema.PerformanceDetail,
+    'scene-error': Schema.Struct({ error: SceneError }),
+    'scene-reconciled': ReconciledDetail,
+  },
+});
+
+/** The DOM event name for each kernel scene event. */
+export const domEventName = {
+  Click: 'scene-click',
+  DoubleClick: 'scene-double-click',
+  ContextMenu: 'scene-context-menu',
+  PointerDown: 'scene-pointer-down',
+  PointerUp: 'scene-pointer-up',
+  PointerEnter: 'scene-pointer-enter',
+  PointerMove: 'scene-pointer-move',
+  PointerLeave: 'scene-pointer-leave',
+  PointerMissed: 'scene-pointer-missed',
+  Wheel: 'scene-wheel',
+  Drag: 'scene-drag',
+  DragEnd: 'scene-drag-end',
+  Gesture: 'scene-gesture',
+  AutoRotated: 'scene-auto-rotated',
+  Collision: 'scene-collision',
+  ContactForce: 'scene-contact-force',
+  Measured: 'scene-measured',
+  LabelMeasured: 'scene-label-measured',
+  XrStick: 'scene-xr-stick',
+  XrButton: 'scene-xr-button',
+  XrSurface: 'scene-xr-surface',
+  XrMoved: 'scene-xr-moved',
+  XrPlanes: 'scene-xr-planes',
+  XrMeshes: 'scene-xr-meshes',
+  PerformanceChanged: 'scene-performance',
+} as const satisfies Record<SceneEvent['_tag'], keyof typeof sceneElement.events>;
+
+/** Outcome of mounting a scene. Map these into the app's Messages with `onLifecycle`. */
+export const SceneLifecycle = defineMessageUnion({
+  StartedScene: {},
+  FailedScene: { reason: Schema.String },
+});
+export type SceneLifecycle = typeof SceneLifecycle.Type;

package/src/environment.ts

@@ -0,0 +1,78 @@
+/**
+ * App-wide state shared by every scene element: one GPU resource store and one
+ * animation-frame scheduler. Create it once at the application entry point.
+ *
+ * @module
+ */
+import {
+  type Behaviour,
+  createResourceStore,
+  type LabelEngine,
+  type PhysicsEngine,
+  type RendererFactory,
+  type ResourceStore,
+} from '@opsydyn/effect-three';
+
+import { makeAssets } from './assets.ts';
+import { animationFrameScheduler, type AnimationFrameHost } from './dom/animationFrames.ts';
+import { defaultPixelRatio, type PixelRatio } from './dom/viewport.ts';
+import { webglRendererFactory } from './dom/webgl.ts';
+import { createXrHub } from './dom/xrHub.ts';
+import { makeXr } from './xr.ts';
+
+/** The browser APIs the adapter uses; normally `window`. */
+export type EnvironmentHost = AnimationFrameHost &
+  Pick<Window, 'matchMedia' | 'devicePixelRatio'> &
+  Partial<Pick<Window, 'navigator'>>;
+
+export type EnvironmentOptions = {
+  /** Creates each scene's renderer from its canvas. Defaults to WebGL2. */
+  readonly renderer?: (canvas: HTMLCanvasElement) => RendererFactory;
+  /** Drawing-buffer pixel ratio: fixed, or `[min, max]` around the device's. Default `[1, 2]`. */
+  readonly pixelRatio?: PixelRatio;
+  /** Behaviours scenes may name with `behave(name)`, beside the built-in `float`. */
+  readonly behaviours?: Readonly<Record<string, Behaviour>>;
+  /**
+   * The physics engine for scenes with `physics`, or the promise of one: pass
+   * `loadRapier()` from `@opsydyn/effect-three-rapier` as it is, and scenes start once it
+   * has loaded. Without one, bodies stay where they are described.
+   */
+  readonly physics?: PhysicsEngine | Promise<PhysicsEngine>;
+  /**
+   * Draws `label` nodes: pass `troikaLabels()` from `@opsydyn/effect-three-troika`.
+   * Without one, labels are empty.
+   */
+  readonly labels?: LabelEngine;
+};
+
+/** Creates the shared environment for `host`. Call `dispose` when the app shuts down. */
+export const makeEnvironment = (host: EnvironmentHost, options: EnvironmentOptions = {}) => {
+  const store: ResourceStore = createResourceStore();
+  const assets = makeAssets(store);
+  const xrHub = createXrHub(() => host.navigator?.xr);
+  return {
+    host,
+    store,
+    frames: animationFrameScheduler(host),
+    renderer: options.renderer ?? ((canvas: HTMLCanvasElement) => webglRendererFactory(canvas)),
+    pixelRatio: options.pixelRatio ?? defaultPixelRatio,
+    behaviours: options.behaviours ?? {},
+    /** The physics engine, once loaded; `undefined` when there is none. */
+    physics: Promise.resolve(options.physics),
+    /** The label engine; `undefined` when there is none. */
+    labels: options.labels,
+    /** Loads textures and glTF models by URL and lends them to the store. */
+    assets,
+    /** Enters and leaves immersive (WebXR) sessions, from Commands. */
+    xr: makeXr(xrHub),
+    /** The page's presentable scenes and its session; scene mounts register here. */
+    xrHub,
+    /** Disposes every loaded asset and every GPU resource still held. */
+    dispose: () => {
+      assets.dispose();
+      store.dispose();
+    },
+  };
+};
+
+export type Environment = ReturnType<typeof makeEnvironment>;

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Foldkit adapter for `@opsydyn/effect-three`.
+ *
+ * ```ts
+ * // entry.ts: once per app
+ * const environment = EffectThreeFoldkit.makeEnvironment(window);
+ * export const sceneMount = EffectThreeFoldkit.makeSceneMount(environment);
+ *
+ * // view.ts
+ * EffectThreeFoldkit.view(
+ *   { scene: sceneFor(model), mount: sceneMount, onLifecycle: GotSceneLifecycle, onClick: ClickedNode },
+ *   h,
+ * );
+ * ```
+ *
+ * @module
+ */
+export { AssetLoadError, type Assets, makeAssets, type ModelInfo } from './assets.ts';
+export { animationFrameScheduler, type AnimationFrameHost } from './dom/animationFrames.ts';
+export {
+  capturesPointer,
+  claimsContextMenu,
+  type Rect,
+  toNdc,
+  toPointerInput,
+} from './dom/pointer.ts';
+export { defaultPixelRatio, type PixelRatio, resolvePixelRatio } from './dom/viewport.ts';
+export { webglRendererFactory, type WebGLOptions } from './dom/webgl.ts';
+export { type WebGPUOptions, webgpuRendererFactory } from './dom/webgpu.ts';
+export {
+  domEventName,
+  ReconciledDetail,
+  SceneError,
+  sceneElement,
+  SceneLifecycle,
+  XrSessionDetail,
+} from './element.ts';
+export { type XrMode } from './dom/xrHub.ts';
+export { type XrControls, XrUnavailable } from './xr.ts';
+export { summarise } from './dom/reconciled.ts';
+export {
+  type Environment,
+  type EnvironmentHost,
+  type EnvironmentOptions,
+  makeEnvironment,
+} from './environment.ts';
+export { makeSceneMount, type SceneMount } from './mount.ts';
+export { type OverlayView } from './overlayView.ts';
+export {
+  type AutoRotatedDetail,
+  type ButtonDetail,
+  type CollisionDetail,
+  type ContactForceDetail,
+  type DragDetail,
+  type Gesture,
+  type HitDetail,
+  type KeyDetail,
+  type LabelMeasuredDetail,
+  type MeasuredDetail,
+  type MissDetail,
+  type PerformanceDetail,
+  view,
+  type ViewConfig,
+  type WheelDetail,
+  type XrButtonDetail,
+  type XrMeshesDetail,
+  type XrMovedDetail,
+  type XrPlanesDetail,
+  type XrStickDetail,
+  type XrSurfaceDetail,
+} from './view.ts';

package/src/mount.ts

@@ -0,0 +1,305 @@
+/**
+ * The scene Mount (ADR-002): runs one scene for the lifetime of its element inside
+ * Foldkit's runtime. Everything acquired here is released, in reverse order, when the
+ * element unmounts.
+ *
+ * @module
+ */
+import {
+  createGatedFrames,
+  FrameSource,
+  type GatedFrames,
+  type PhysicsEngine,
+  type PointerInput,
+  ResourceRegistry,
+  type SceneEvent,
+  type SceneDescription,
+  SceneRuntime,
+  SceneSchema,
+} from '@opsydyn/effect-three';
+import { type Cause, Data, Effect, Option, Queue, Schema, Stream } from 'effect';
+import { Mount } from 'foldkit';
+import type { ViewState } from 'foldkit/mount';
+
+import {
+  canvasIn,
+  reconciledDispatch,
+  removal,
+  sceneErrorDispatch,
+  sceneEventDispatch,
+} from './dom/canvas.ts';
+import { applying, createLatch, type Latch, routedWhileOpen } from './dom/latch.ts';
+import { containOverlays, createOverlayWriter, type OverlayWriter } from './dom/overlays.ts';
+import { claimsGestures, listenForPointer, touchActionSync } from './dom/pointer.ts';
+import { interceptProperty } from './dom/property.ts';
+import { typedScene } from './dom/typedScenes.ts';
+import { afterUpdate } from './dom/updates.ts';
+import {
+  measureViewport,
+  observePixelRatio,
+  observeReducedMotion,
+  observeSize,
+  observeVisibility,
+} from './dom/viewport.ts';
+import { createFrameGate, type FrameGate, xrTarget } from './dom/xrTarget.ts';
+import { SceneLifecycle } from './element.ts';
+import type { Environment } from './environment.ts';
+
+type SceneHandle = SceneRuntime.SceneHandle;
+
+/** Everything one mounted scene needs, gathered so helpers take one argument. */
+type Mounted = {
+  readonly environment: Environment;
+  readonly element: Element;
+  readonly canvas: HTMLCanvasElement;
+  readonly overlays: OverlayWriter;
+  readonly handle: SceneHandle;
+  readonly live: Latch;
+  readonly frames: GatedFrames;
+  readonly gate: FrameGate;
+};
+
+const decodeUnknownScene = Schema.decodeUnknownEffect(SceneSchema.SceneDescription);
+
+/** Typed scenes from `view` skip validation; anything else is Schema-decoded. */
+const decodeScene = (value: unknown) =>
+  Option.fromNullishOr(typedScene(value)).pipe(
+    Option.match({ onNone: () => decodeUnknownScene(value), onSome: Effect.succeed }),
+  );
+
+const isLive = Schema.is(Schema.Literal('Live'));
+
+const acquireCanvas = (element: Element) => {
+  const create = Effect.sync(canvasIn(element));
+  return Effect.acquireRelease(create, (canvas) => Effect.sync(removal(canvas)));
+};
+
+const acquireSceneUpdates = () => {
+  const create = Queue.sliding<unknown>(1);
+  return Effect.acquireRelease(create, Queue.shutdown);
+};
+
+const interception = (element: Element, updates: Queue.Queue<unknown>) => () =>
+  interceptProperty(element, 'scene', (value) => Queue.offerUnsafe(updates, value));
+
+const acquireInterception = (element: Element, updates: Queue.Queue<unknown>) => {
+  const intercept = Effect.sync(interception(element, updates));
+  return Effect.acquireRelease(intercept, (intercepted) => Effect.sync(intercepted.restore));
+};
+
+const pointerListening =
+  (
+    canvas: HTMLElement,
+    onInput: (input: PointerInput) => ReadonlyArray<SceneEvent>,
+    claimsGestures: () => boolean,
+  ) =>
+  () =>
+    listenForPointer(canvas, onInput, claimsGestures);
+
+const acquirePointer = (canvas: HTMLElement, mounted: Mounted) => {
+  const listen = Effect.sync(
+    pointerListening(
+      canvas,
+      routedWhileOpen(mounted.live, mounted.handle.pointer),
+      claimsGestures(mounted.handle.graph),
+    ),
+  );
+  return Effect.acquireRelease(listen, Effect.sync);
+};
+
+/** Makes the scene presentable in the page's immersive sessions while it is mounted. */
+const xrRegistration = (mounted: Mounted) => () =>
+  mounted.environment.xrHub.register(
+    xrTarget({
+      element: mounted.element,
+      canvas: mounted.canvas,
+      live: mounted.live,
+      gate: mounted.gate,
+      settings: mounted.handle.graph.xr,
+      draw: mounted.handle.drawNow,
+      scene: mounted.handle.graph.scene,
+      follow: mounted.handle.graph.follow,
+      lend: mounted.handle.graph.store.lendGeometry,
+      input: mounted.handle.xrInput,
+    }),
+  );
+
+const acquireXrTarget = (mounted: Mounted) => {
+  const register = Effect.sync(xrRegistration(mounted));
+  return Effect.acquireRelease(register, Effect.sync);
+};
+
+/** A stream of values from a DOM observer that returns a disconnect function. */
+const connectObserver =
+  <A>(observe: (emit: (value: A) => void) => () => void) =>
+  (queue: Queue.Queue<A, Cause.Done>) => {
+    const connect = Effect.sync(applying(observe, (value: A) => Queue.offerUnsafe(queue, value)));
+    return Effect.acquireRelease(connect, Effect.sync);
+  };
+
+const observed = <A>(observe: (emit: (value: A) => void) => () => void) =>
+  Stream.callback<A>(connectObserver(observe));
+
+const applyUpdate = (mounted: Mounted) => (value: unknown) => {
+  const reportError = sceneErrorDispatch(mounted.element);
+  const reportReconciled = afterUpdate(
+    reconciledDispatch(mounted.element, mounted.environment.store),
+    [touchActionSync(mounted.canvas, mounted.handle.graph), mounted.overlays.rewrite],
+  );
+  const decoded = decodeScene(value);
+  const applied = decoded.pipe(
+    Effect.flatMap(mounted.handle.update),
+    Effect.flatMap((ops) => Effect.sync(reportReconciled(ops))),
+  );
+  return applied.pipe(
+    Effect.catchTags({
+      SchemaError: (error) =>
+        Effect.sync(reportError({ _tag: 'MalformedScene', issue: error.message })),
+      InvalidScene: ({ error }) => Effect.sync(reportError(error)),
+    }),
+  );
+};
+
+const resize = (mounted: Mounted) => () =>
+  mounted.handle.resize(
+    measureViewport(
+      mounted.element,
+      mounted.environment.host.devicePixelRatio,
+      mounted.environment.pixelRatio,
+    ),
+  );
+
+const watchers = (
+  mounted: Mounted,
+  updates: Queue.Queue<unknown>,
+  viewStateChanges: Stream.Stream<ViewState>,
+) => {
+  const dispatchEvent = sceneEventDispatch(mounted.element, mounted.live);
+  const sizes = observed<void>((emit) => observeSize(mounted.element, emit));
+  const ratios = observed<void>((emit) => observePixelRatio(mounted.environment.host, emit));
+  const visibility = observed<boolean>((emit) => observeVisibility(mounted.element, emit));
+  const reducedMotion = observed<boolean>((emit) =>
+    observeReducedMotion(mounted.environment.host, emit),
+  );
+  return [
+    Stream.runForEach(Stream.fromQueue(updates), applyUpdate(mounted)),
+    Stream.runForEach(mounted.handle.events, (event) => Effect.sync(dispatchEvent(event))),
+    Stream.runForEach(viewStateChanges, (state) =>
+      Effect.sync(applying(mounted.live.set, isLive(state))),
+    ),
+    Stream.runForEach(sizes, resize(mounted)),
+    Stream.runForEach(ratios, resize(mounted)),
+    Stream.runForEach(visibility, (visible) =>
+      Effect.sync(applying(mounted.gate.setVisible, visible)),
+    ),
+    Stream.runForEach(reducedMotion, (reduced) => mounted.handle.setAnimating(!reduced)),
+  ];
+};
+
+/** The physics engine could not be loaded (Rapier's WebAssembly, say). */
+class PhysicsUnavailable extends Data.TaggedError('PhysicsUnavailable')<{
+  readonly cause: unknown;
+}> {}
+
+const sceneRuntimeFor =
+  (
+    environment: Environment,
+    element: Element,
+    canvas: HTMLCanvasElement,
+    overlays: OverlayWriter,
+    physics: PhysicsEngine | undefined,
+  ) =>
+  (scene: SceneDescription) => {
+    const frames = createGatedFrames(environment.frames);
+    const started = SceneRuntime.make({
+      scene,
+      renderer: environment.renderer(canvas),
+      behaviours: environment.behaviours,
+      physics,
+      labels: environment.labels,
+      placeOverlays: overlays.place,
+      viewport: measureViewport(element, environment.host.devicePixelRatio, environment.pixelRatio),
+    }).pipe(
+      Effect.provideService(FrameSource.FrameSource, FrameSource.fromScheduler(frames)),
+      Effect.provideService(ResourceRegistry.ResourceRegistry, { store: environment.store }),
+    );
+    return Effect.map(started, (handle) => ({ handle, frames }));
+  };
+
+function* runScene(
+  environment: Environment,
+  element: Element,
+  viewStateChanges: Stream.Stream<ViewState>,
+) {
+  const canvas = yield* acquireCanvas(element);
+  const updates = yield* acquireSceneUpdates();
+  const intercepted = yield* acquireInterception(element, updates);
+  const initial = yield* decodeScene(intercepted.initial);
+  const overlays = createOverlayWriter(element);
+  yield* Effect.sync(containOverlays(element));
+  const physics = yield* Effect.tryPromise({
+    try: () => environment.physics,
+    catch: (cause) => new PhysicsUnavailable({ cause }),
+  });
+  const { handle, frames } = yield* sceneRuntimeFor(
+    environment,
+    element,
+    canvas,
+    overlays,
+    physics,
+  )(initial);
+  const mounted: Mounted = {
+    environment,
+    element,
+    canvas,
+    overlays,
+    handle,
+    frames,
+    gate: createFrameGate(frames),
+    live: createLatch(true),
+  };
+  yield* acquirePointer(canvas, mounted);
+  yield* acquireXrTarget(mounted);
+  yield* Effect.sync(touchActionSync(canvas, handle.graph));
+  yield* Effect.sync(reconciledDispatch(element, environment.store)(handle.startupOps));
+  const forks = watchers(mounted, updates, viewStateChanges).map((watcher) =>
+    Effect.forkScoped(watcher),
+  );
+  yield* Effect.all(forks, { concurrency: 'unbounded' });
+  return SceneLifecycle.StartedScene();
+}
+
+const failure = (reason: string) => SceneLifecycle.FailedScene({ reason });
+
+const recoverStart = {
+  SchemaError: (error: Schema.SchemaError) =>
+    Effect.succeed(failure(`malformed scene: ${error.message}`)),
+  InvalidScene: ({ error }: { readonly error: { readonly _tag: string } }) =>
+    Effect.succeed(failure(`invalid scene: ${error._tag}`)),
+  RendererUnavailable: () => Effect.succeed(failure('renderer unavailable')),
+  PhysicsUnavailable: () => Effect.succeed(failure('physics unavailable')),
+};
+
+type ExecuteInput = {
+  readonly element: Element;
+  readonly viewStateChanges: Stream.Stream<ViewState>;
+};
+
+const mountScene =
+  (environment: Environment) =>
+  ({ element, viewStateChanges }: ExecuteInput) => {
+    const scene = Effect.gen(() => runScene(environment, element, viewStateChanges));
+    return scene.pipe(Effect.catchTags(recoverStart));
+  };
+
+/**
+ * Defines the scene Mount for an environment. Call once at the application entry point
+ * and pass the result to `view` as `mount`.
+ */
+export const makeSceneMount = (environment: Environment) =>
+  Mount.define('EffectThreeScene', {
+    messages: [SceneLifecycle.StartedScene, SceneLifecycle.FailedScene],
+    execute: mountScene(environment),
+  });
+
+export type SceneMount = ReturnType<typeof makeSceneMount>;

package/src/overlayView.ts

@@ -0,0 +1,71 @@
+/**
+ * Overlay HTML in the scene view: the application's content for each overlay, in an
+ * element the scene moves to the overlay's point every frame it draws.
+ *
+ * @module
+ */
+import type { Overlay, SceneDescription } from '@opsydyn/effect-three';
+import type { Html, HtmlBuilder } from 'foldkit/html';
+
+import { overlayData } from './dom/overlays.ts';
+
+/** HTML shown at a point in the scene, as Drei's `Html`: where, and what. */
+export type OverlayView = {
+  readonly overlay: Overlay;
+  readonly content: Html;
+  /**
+   * `'auto'` (the default, as Drei): the HTML takes pointer events. `'none'`: they pass
+   * through to the canvas, so the scene under a label stays pickable.
+   */
+  readonly pointerEvents?: 'auto' | 'none';
+};
+
+/** The scene with the overlays' points added, so the scene places them. */
+export const withOverlays = (
+  scene: SceneDescription,
+  overlays: ReadonlyArray<OverlayView>,
+): SceneDescription =>
+  overlays.length === 0
+    ? scene
+    : { ...scene, overlays: [...scene.overlays, ...overlays.map((view) => view.overlay)] };
+
+// The layer covers the canvas, lets events through, and keeps Drei's large z-indexes
+// inside the scene element rather than competing with the page.
+const layerStyle = {
+  position: 'absolute',
+  inset: '0',
+  overflow: 'hidden',
+  pointerEvents: 'none',
+  isolation: 'isolate',
+};
+
+/** The overlay layer, or nothing when there are no overlays. */
+export const overlayLayer = <Message>(
+  h: HtmlBuilder<Message>,
+  overlays: ReadonlyArray<OverlayView>,
+): ReadonlyArray<Html> =>
+  overlays.length === 0
+    ? []
+    : [
+        h.div(
+          [h.Style(layerStyle)],
+          overlays.map(({ overlay, content, pointerEvents = 'auto' }) =>
+            h.keyed('div')(
+              overlay.key,
+              [
+                h.DataAttribute(overlayData.key, overlay.key),
+                // Hidden until the scene first places it.
+                h.Style({
+                  position: 'absolute',
+                  top: '0',
+                  left: '0',
+                  transformOrigin: '0 0',
+                  visibility: 'hidden',
+                  pointerEvents,
+                }),
+              ],
+              [content],
+            ),
+          ),
+        ),
+      ];