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

package/dist/view.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The scene view: one call from a Foldkit `view` renders a scene and maps its events to
+ * the app's typed Messages. The scene is plain data derived from the Model.
+ *
+ * @module
+ */
+import type { SceneDescription, SceneSchema } from '@opsydyn/effect-three';
+import type { Html, HtmlBuilder } from 'foldkit/html';
+import { type ReconciledDetail, type SceneError, type SceneLifecycle, type XrSessionDetail } from './element.ts';
+import type { SceneMount } from './mount.ts';
+import { type OverlayView } from './overlayView.ts';
+/**
+ * Where the pointer met an interactive mesh: key, world-space point, distance from the
+ * camera, world-space face normal and texture coordinates.
+ */
+export type HitDetail = typeof SceneSchema.HitDetail.Type;
+/** Detail of click, double-click, pointer-down and pointer-up events: the hit and button. */
+export type ButtonDetail = typeof SceneSchema.ButtonDetail.Type;
+/** Detail of wheel events: the hit and the wheel deltas. */
+export type WheelDetail = typeof SceneSchema.WheelDetail.Type;
+/** Detail of a click that hit no interactive mesh. */
+export type MissDetail = typeof SceneSchema.MissDetail.Type;
+/** Detail of drag events: the captured mesh, the button and the pointer's world-space ray. */
+export type DragDetail = typeof SceneSchema.DragDetail.Type;
+/**
+ * A drag, wheel or pinch on the canvas, when the scene claims gestures. Pass it to
+ * `orbit` to move a camera kept in the Model.
+ */
+export type Gesture = typeof SceneSchema.Gesture.Type;
+/** Detail of collision events: the two bodies' keys, and whether they began touching. */
+export type CollisionDetail = typeof SceneSchema.CollisionDetail.Type;
+/** Detail of contact force events: the two bodies, and how hard they pushed. */
+export type ContactForceDetail = typeof SceneSchema.ContactForceDetail.Type;
+/** Detail of measured events: a node's world bounding box. */
+export type MeasuredDetail = typeof SceneSchema.MeasuredDetail.Type;
+/** Detail of auto-rotated events: where a camera turning by itself got to. */
+export type AutoRotatedDetail = typeof SceneSchema.AutoRotatedDetail.Type;
+/** Detail of label measured events: a label's laid-out size in its own units. */
+export type LabelMeasuredDetail = typeof SceneSchema.LabelMeasuredDetail.Type;
+/** Detail of XR stick events: a thumbstick pushed past halfway in a direction, or let back. */
+export type XrStickDetail = typeof SceneSchema.XrStickDetail.Type;
+/** Detail of XR button events: a controller button pressed or released. */
+export type XrButtonDetail = typeof SceneSchema.XrButtonDetail.Type;
+/** Detail of XR moved events: where gliding left the player. */
+export type XrMovedDetail = typeof SceneSchema.XrMovedDetail.Type;
+/** Detail of XR planes events: every plane the session detected, as it is now. */
+export type XrPlanesDetail = typeof SceneSchema.XrPlanesDetail.Type;
+/** Detail of XR meshes events: every mesh the session detected, as it is now. */
+export type XrMeshesDetail = typeof SceneSchema.XrMeshesDetail.Type;
+/** Detail of XR surface events: in AR, where a select met a real surface, and its normal. */
+export type XrSurfaceDetail = typeof SceneSchema.XrSurfaceDetail.Type;
+/** Detail of performance changes: the measured fps and the new factor, 0 to 1. */
+export type PerformanceDetail = typeof SceneSchema.PerformanceDetail.Type;
+/** Detail of pointer-leave events: the key that is no longer under the pointer. */
+export type KeyDetail = typeof SceneSchema.KeyDetail.Type;
+export type ViewConfig<Message> = {
+    /** The scene to show. Derive it from the Model; unchanged scenes cost nothing. */
+    readonly scene: SceneDescription;
+    /** The Mount from `makeSceneMount`, created once at the entry point. */
+    readonly mount: SceneMount;
+    /** Maps the mount outcome (started or failed) into the app's Messages. */
+    readonly onLifecycle: (message: SceneLifecycle) => Message;
+    /** Pressed and released on the same mesh with the same button. */
+    readonly onClick?: (detail: ButtonDetail) => Message;
+    /** A double-click on the mesh that was last pressed. */
+    readonly onDoubleClick?: (detail: ButtonDetail) => Message;
+    /** A context menu on the mesh that was last pressed. The browser's menu stays shut. */
+    readonly onContextMenu?: (detail: HitDetail) => Message;
+    readonly onPointerDown?: (detail: ButtonDetail) => Message;
+    readonly onPointerUp?: (detail: ButtonDetail) => Message;
+    readonly onPointerEnter?: (detail: HitDetail) => Message;
+    /** Every pointer movement over an interactive mesh. Can fire at the pointer's rate. */
+    readonly onPointerMove?: (detail: HitDetail) => Message;
+    readonly onPointerLeave?: (detail: KeyDetail) => Message;
+    /** A click that hit no interactive mesh and moved at most two pixels: clear a selection. */
+    readonly onPointerMissed?: (detail: MissDetail) => Message;
+    /** The wheel over an interactive mesh. Page scrolling is not blocked. */
+    readonly onWheel?: (detail: WheelDetail) => Message;
+    /**
+     * The pointer moved while pressed on a mesh, anywhere (the press captures it). Turn the
+     * ray into a point with `pointOnPlane` to drag along a plane.
+     */
+    readonly onDrag?: (detail: DragDetail) => Message;
+    /** A drag ended: released anywhere, or the pointer was cancelled. */
+    readonly onDragEnd?: (detail: DragDetail) => Message;
+    /**
+     * A drag, wheel or pinch anywhere on the canvas, reported while the scene claims
+     * gestures (`scene({ gestures: 'scene' })`). Apply it with `orbit` in `update`:
+     * the camera stays in the Model.
+     */
+    readonly onGesture?: (gesture: Gesture) => Message;
+    /**
+     * A gesture is about to begin on a camera turning by itself (`autoRotate`): keep where
+     * it got to with `autoRotated(model.camera, detail)` (a view's camera when `view` names
+     * one), so the gesture goes on from where the camera was shown.
+     */
+    readonly onAutoRotated?: (detail: AutoRotatedDetail) => Message;
+    /**
+     * Two bodies began or stopped touching (react-three-rapier's `onCollisionEnter` and
+     * `onCollisionExit`, for the whole scene). Needs `physics` and an engine.
+     */
+    readonly onCollision?: (detail: CollisionDetail) => Message;
+    /**
+     * Two bodies pushed on each other harder than a body's `contactForces` threshold during
+     * a step (react-three-rapier's `onContactForce`). Rapier reports every such step, so
+     * set the threshold high.
+     */
+    readonly onContactForce?: (detail: ContactForceDetail) => Message;
+    /**
+     * A node listed in the scene's `measure` has a new world bounding box (Drei's `Bounds`
+     * measuring, as a Message): fit the camera to it with `fitCamera`.
+     */
+    readonly onMeasured?: (detail: MeasuredDetail) => Message;
+    /**
+     * A measured label (`scene({ measure })`) was laid out anew: its block and tight glyph
+     * bounds in its own units, before its scale, to size what goes behind it.
+     */
+    readonly onLabelMeasured?: (detail: LabelMeasuredDetail) => Message;
+    /**
+     * An immersive session began presenting this scene (`mode`), or ended (`mode: null`),
+     * whether the app or the user (through the headset) ended it.
+     */
+    readonly onXRSession?: (detail: XrSessionDetail) => Message;
+    /**
+     * In a session, a thumbstick pushed past halfway in a direction, or let back to the
+     * centre: snap turn and teleport by changing the scene's `xr({ heading, origin })`, as
+     * pmndrs/xr's controller locomotion does.
+     */
+    readonly onXRStick?: (detail: XrStickDetail) => Message;
+    /** In a session, a controller button pressed or released (`xr-standard` mapping). */
+    readonly onXRButton?: (detail: XrButtonDetail) => Message;
+    /**
+     * In AR with `xr({ hitTest: true })`, a select whose ray met a real surface: place
+     * things there.
+     */
+    readonly onXRSurface?: (detail: XrSurfaceDetail) => Message;
+    /**
+     * Gliding with the sticks (`xr({ glide })`) stopped: keep where the player now stands
+     * with `glided(model.xr, detail)`.
+     */
+    readonly onXRMoved?: (detail: XrMovedDetail) => Message;
+    /**
+     * With `xr({ planes: true })`, the detected planes changed (found, reshaped, lost, or
+     * seen from where the player moved to): every plane, as it is now. Follow one with
+     * `group({ follow: planeSpace(id) })`.
+     */
+    readonly onXRPlanes?: (detail: XrPlanesDetail) => Message;
+    /**
+     * With `xr({ meshes: true })`, the detected meshes changed: every mesh, as it is now.
+     * Draw one as `mesh({ geometry: xrMesh(id), material })` inside a group that follows
+     * `meshSpace(id)`: its geometry is lent to the scene, not sent.
+     */
+    readonly onXRMeshes?: (detail: XrMeshesDetail) => Message;
+    /**
+     * Frames ran persistently slow or fast, and the performance factor moved (0 to 1).
+     * Store it in the Model and lower `render.resolution` with it, as Drei's
+     * `PerformanceMonitor` and `AdaptiveDpr` do together.
+     */
+    readonly onPerformanceChange?: (detail: PerformanceDetail) => Message;
+    /** A scene update was rejected; the scene keeps its last good state. */
+    readonly onError?: (detail: {
+        readonly error: SceneError;
+    }) => Message;
+    /**
+     * What each scene update did (operations by kind) and the GPU resources held afterwards.
+     * Fires at startup and after every update that changed something, never for no-ops.
+     */
+    readonly onReconciled?: (detail: ReconciledDetail) => Message;
+    /**
+     * HTML at points in the scene, as Drei's `Html`: each `overlay` says where (a point,
+     * perhaps on a node), `content` what. The scene moves the HTML there every frame it
+     * draws; the content is ordinary view HTML, rendered from the Model.
+     */
+    readonly overlays?: ReadonlyArray<OverlayView>;
+    readonly className?: string;
+};
+/** Renders a scene element. Only the event handlers you pass are bound. */
+export declare const view: <Message>(config: ViewConfig<NoInfer<Message>>, h: HtmlBuilder<Message>) => Html;
+//# sourceMappingURL=view.d.ts.map

package/dist/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../src/view.ts"],"names":[],"mappings":"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"}

package/dist/xr.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Immersive sessions as Effects an application runs from Foldkit Commands: whether a mode
+ * is supported, entering it from a user gesture, and leaving it. The scene presented is
+ * the mounted one whose description has `xr`; while presenting, the session drives its
+ * frames and the view's `onXRSession` reports the session starting and ending.
+ *
+ * @module
+ */
+import { Effect } from 'effect';
+import type { XrHub, XrMode } from './dom/xrHub.ts';
+declare const XrUnavailable_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "XrUnavailable";
+} & Readonly<A>;
+/** A session could not start: no WebXR, no scene describing `xr`, or the request refused. */
+export declare class XrUnavailable extends XrUnavailable_base<{
+    readonly mode: XrMode;
+    readonly cause: unknown;
+}> {
+}
+/** The immersive session controls for an environment's hub. */
+export declare const makeXr: (hub: XrHub) => {
+    /** Whether the browser can present `mode` (false without WebXR). */
+    supported: (mode: XrMode) => Effect.Effect<boolean, never, never>;
+    /**
+     * Enters `mode`, presenting the mounted scene that describes `xr`. Run it from the
+     * Command a click (or other user gesture) produces: browsers require one.
+     */
+    enter: (mode: XrMode) => Effect.Effect<void, XrUnavailable, never>;
+    /** Ends the session, if there is one. */
+    exit: Effect.Effect<void, never, never>;
+};
+export type XrControls = ReturnType<typeof makeXr>;
+export {};
+//# sourceMappingURL=xr.d.ts.map

package/dist/xr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr.d.ts","sourceRoot":"","sources":["../src/xr.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAQ,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;;;;AAEpD,6FAA6F;AAC7F,qBAAa,aAAc,SAAQ,mBAAkC;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,CAAC;CAAG;AAEL,+DAA+D;AAC/D,eAAO,MAAM,MAAM,QAAS,KAAK;IAC/B,oEAAoE;IACpE,SAAS,SAAS,MAAM;IACxB;;;OAGG;IACH,KAAK,SAAS,MAAM;IAKpB,yCAAyC;IACzC,IAAI;CACJ,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@opsydyn/effect-three-foldkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Thin Foldkit adapter for @opsydyn/effect-three.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opsydyn/fold-kit-experiments.git",
+    "directory": "packages/effect-three-foldkit"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "!dist/.tsbuildinfo",
+    "!dist/api-extractor",
+    "!dist/pack"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -b . ../effect-three-troika && tsc -p tsconfig.test.json",
+    "lint": "bunx --bun oxlint --config oxlint.strict.ts",
+    "check": "bun run lint",
+    "test": "bun test --pass-with-no-tests ./src ./test",
+    "test:e2e": "bun test ./e2e",
+    "build": "tsc -b && bun build ./src/index.ts --root ./src --outdir ./dist --target browser --packages external --sourcemap=linked",
+    "api:report": "api-extractor run --local",
+    "api:check": "api-extractor run",
+    "pack:check": "bun run build && publint && rm -rf dist/pack && bun pm pack --destination dist/pack && attw dist/pack/*.tgz --profile esm-only"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@effect/platform-browser": "4.0.0",
+    "@fontsource/inter": "5.3.0",
+    "@microsoft/api-extractor": "7.59.4",
+    "@opsydyn/effect-three": "0.1.0",
+    "@opsydyn/effect-three-troika": "0.1.0",
+    "@opsydyn/oxlint-effect": "2.0.1",
+    "@types/bun": "1.4.3",
+    "@types/pngjs": "6.0.5",
+    "@types/three": "0.186.0",
+    "effect": "4.0.0",
+    "foldkit": "0.167.0",
+    "iwer": "2.5.0",
+    "oxlint": "1.88.0",
+    "oxlint-tsgolint": "7.0.2004",
+    "pixelmatch": "8.0.0",
+    "playwright": "1.64.1",
+    "pngjs": "7.0.0",
+    "publint": "0.3.25",
+    "three": "0.186.1",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "@opsydyn/effect-three": "0.2.0",
+    "effect": "^4.0.0",
+    "foldkit": "0.167.0",
+    "three": ">=0.186.0 <0.187.0"
+  }
+}

package/src/assets.ts

@@ -0,0 +1,151 @@
+/**
+ * Loading textures, glTF models and typeface fonts by URL, as Effects an application runs
+ * from a Foldkit Command and settles into `AsyncData`. Each asset is lent to the shared
+ * resource store under an id: materials use a texture with `map: id`, a `borrowed({ id })`
+ * node shows a model, and `text({ font: id })` geometry draws with a font. The environment owns what it loads: loading an id again replaces and disposes
+ * the earlier asset, and `unload` or the environment's `dispose` frees it.
+ *
+ * @module
+ */
+import type { ResourceStore } from '@opsydyn/effect-three';
+import { Data, Effect } from 'effect';
+import {
+  EquirectangularReflectionMapping,
+  type Object3D,
+  SRGBColorSpace,
+  type Texture,
+  TextureLoader,
+} from 'three';
+import { type Font, FontLoader } from 'three/addons/loaders/FontLoader.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
+
+import { disposeModel, namesIn } from './dom/models.ts';
+
+/** An asset could not be fetched or decoded. */
+export class AssetLoadError extends Data.TaggedError('AssetLoadError')<{
+  readonly url: string;
+  readonly cause: unknown;
+}> {}
+
+/** What a loaded model offers: named parts to match hits against, and animation clips. */
+export type ModelInfo = {
+  readonly id: string;
+  /** Names of the objects inside the model, as hits report them in `part`. */
+  readonly parts: ReadonlyArray<string>;
+  /** Names of the model's animation clips. */
+  readonly clips: ReadonlyArray<string>;
+};
+
+/** Creates the asset loader for a store. One per environment. */
+export const makeAssets = (store: ResourceStore) => {
+  const releases = new Map<string, () => void>();
+
+  /** Takes ownership of an asset under `id`, first releasing whatever was there. */
+  const own = (id: string, release: () => void): void => {
+    releases.get(id)?.();
+    releases.set(id, release);
+  };
+
+  const lendTexture = (id: string) => (texture: Texture) => {
+    texture.colorSpace = SRGBColorSpace;
+    const withdraw = store.lendTexture(id, texture);
+    own(id, () => {
+      withdraw();
+      texture.dispose();
+    });
+    return id;
+  };
+
+  const lendModel =
+    (id: string) =>
+    (gltf: { readonly scene: Object3D; readonly animations: Object3D['animations'] }) => {
+      // Keep the clips with the object, so a borrowed node can play them by name.
+      gltf.scene.animations = gltf.animations;
+      const withdraw = store.lend(id, gltf.scene);
+      own(id, () => {
+        withdraw();
+        disposeModel(gltf.scene);
+      });
+      const info: ModelInfo = {
+        id,
+        parts: namesIn(gltf.scene),
+        clips: gltf.animations.map((clip) => clip.name),
+      };
+      return info;
+    };
+
+  /** Lends an HDR panorama for `environment({ map })`: linear, mapped for reflection. */
+  const lendEnvironment = (id: string) => (texture: Texture) => {
+    texture.mapping = EquirectangularReflectionMapping;
+    const withdraw = store.lendTexture(id, texture);
+    own(id, () => {
+      withdraw();
+      texture.dispose();
+    });
+    return id;
+  };
+
+  const lendFont = (id: string) => (font: Font) => {
+    // Fonts hold no GPU resources: withdrawing the loan frees them.
+    own(id, store.lendFont(id, font));
+    return id;
+  };
+
+  const releaseAll = (): void => {
+    for (const release of releases.values()) release();
+    releases.clear();
+  };
+
+  return {
+    /** Loads a colour texture (sRGB) and lends it under `id`. Succeeds with the id. */
+    loadTexture: (id: string, url: string) => {
+      const load = Effect.tryPromise({
+        try: () => new TextureLoader().loadAsync(url),
+        catch: (cause) => new AssetLoadError({ url, cause }),
+      });
+      return Effect.map(load, lendTexture(id));
+    },
+    /** Loads a glTF or GLB model and lends its scene under `id`, with its clips. */
+    loadModel: (id: string, url: string) => {
+      const load = Effect.tryPromise({
+        try: () => new GLTFLoader().loadAsync(url),
+        catch: (cause) => new AssetLoadError({ url, cause }),
+      });
+      return Effect.map(load, lendModel(id));
+    },
+    /**
+     * Loads an equirectangular HDR panorama (`.hdr`, three.js's `HDRLoader`) and lends it
+     * under `id` for `environment({ map: id })`. Succeeds with the id. Image panoramas
+     * load with `loadTexture`; the scene maps them for reflection.
+     */
+    loadEnvironment: (id: string, url: string) => {
+      const load = Effect.tryPromise({
+        try: () => new HDRLoader().loadAsync(url),
+        catch: (cause) => new AssetLoadError({ url, cause }),
+      });
+      return Effect.map(load, lendEnvironment(id));
+    },
+    /**
+     * Loads a typeface JSON font (three.js's `FontLoader` format, as Drei's `Text3D` takes)
+     * and lends it under `id`. Succeeds with the id.
+     */
+    loadFont: (id: string, url: string) => {
+      const load = Effect.tryPromise({
+        try: () => new FontLoader().loadAsync(url),
+        catch: (cause) => new AssetLoadError({ url, cause }),
+      });
+      return Effect.map(load, lendFont(id));
+    },
+    /** Withdraws and disposes the asset loaded under `id`, if any. */
+    unload: (id: string) =>
+      Effect.sync(() => {
+        releases.get(id)?.();
+        releases.delete(id);
+      }),
+    /** Withdraws and disposes every loaded asset. */
+    dispose: releaseAll,
+  };
+};
+
+export type Assets = ReturnType<typeof makeAssets>;

package/src/dom/animationFrames.ts

@@ -0,0 +1,32 @@
+/**
+ * A `requestAnimationFrame` scheduler shared by every scene on the page: one browser
+ * callback per frame, running only while at least one scene is subscribed.
+ *
+ * @module
+ */
+import type { FrameScheduler } from '@opsydyn/effect-three';
+
+/** The part of `Window` the scheduler needs. */
+export type AnimationFrameHost = Pick<Window, 'requestAnimationFrame' | 'cancelAnimationFrame'>;
+
+/** Creates a shared animation-frame scheduler for `host` (normally `window`). */
+export const animationFrameScheduler = (host: AnimationFrameHost): FrameScheduler => {
+  const callbacks = new Set<() => void>();
+  let handle: number | undefined;
+  const tick = (): void => {
+    handle = host.requestAnimationFrame(tick);
+    for (const onFrame of Array.from(callbacks)) onFrame();
+  };
+  return {
+    subscribe: (onFrame) => {
+      callbacks.add(onFrame);
+      handle ??= host.requestAnimationFrame(tick);
+      return () => {
+        callbacks.delete(onFrame);
+        if (callbacks.size > 0 || handle === undefined) return;
+        host.cancelAnimationFrame(handle);
+        handle = undefined;
+      };
+    },
+  };
+};

package/src/dom/canvas.ts

@@ -0,0 +1,54 @@
+/**
+ * The canvas a scene draws into, and DOM event dispatch from scene events.
+ *
+ * @module
+ */
+import type { Op, ResourceStore, SceneEvent } from '@opsydyn/effect-three';
+
+import { domEventName, type SceneError } from '../element.ts';
+import type { Latch } from './latch.ts';
+import { summarise } from './reconciled.ts';
+
+/** Creates a canvas filling `host` and appends it. */
+export const appendCanvas = (host: Element): HTMLCanvasElement => {
+  const canvas = host.ownerDocument.createElement('canvas');
+  canvas.style.display = 'block';
+  canvas.style.width = '100%';
+  canvas.style.height = '100%';
+  // Pointer gestures go to the scene, not to page scrolling or zooming.
+  canvas.style.touchAction = 'none';
+  host.append(canvas);
+  return canvas;
+};
+
+/** Dispatches a scene event as the element's typed DOM event. */
+export const dispatchSceneEvent = (element: Element, event: SceneEvent): void => {
+  element.dispatchEvent(new CustomEvent(domEventName[event._tag], { detail: event }));
+};
+
+/** Dispatches a rejected scene update as a `scene-error` event. */
+export const dispatchSceneError = (element: Element, error: SceneError): void => {
+  element.dispatchEvent(new CustomEvent('scene-error', { detail: { error } }));
+};
+
+/** Thunk builders, so Effect code can run DOM work with `Effect.sync(thunk)`. */
+export const canvasIn = (host: Element) => () => appendCanvas(host);
+export const removal = (node: ChildNode) => () => node.remove();
+/** Dispatches only while `live` is open: events are dropped during time-travel pause. */
+export const sceneEventDispatch = (element: Element, live: Latch) => (event: SceneEvent) => () => {
+  if (live.isOpen()) dispatchSceneEvent(element, event);
+};
+export const sceneErrorDispatch = (element: Element) => (error: SceneError) => () =>
+  dispatchSceneError(element, error);
+
+/**
+ * Dispatches a `scene-reconciled` summary when an update changed something. Updates with
+ * no operations dispatch nothing, so an app storing the summary in its Model can't loop.
+ */
+export const reconciledDispatch =
+  (element: Element, store: ResourceStore) => (ops: ReadonlyArray<Op>) => () => {
+    if (ops.length === 0) return;
+    element.dispatchEvent(
+      new CustomEvent('scene-reconciled', { detail: summarise(ops, store.stats()) }),
+    );
+  };

package/src/dom/latch.ts

@@ -0,0 +1,36 @@
+/**
+ * A boolean read synchronously by DOM callbacks and written by Effect code.
+ *
+ * @module
+ */
+
+export type Latch = {
+  readonly isOpen: () => boolean;
+  readonly set: (open: boolean) => void;
+};
+
+export const createLatch = (open: boolean): Latch => {
+  let current = open;
+  return {
+    isOpen: () => current,
+    set: (next) => {
+      current = next;
+    },
+  };
+};
+
+const nothing: ReadonlyArray<never> = [];
+
+/** Calls `route` only while `latch` is open, returning what it routed (nothing when shut). */
+export const routedWhileOpen =
+  <A, B>(latch: Latch, route: (value: A) => ReadonlyArray<B>) =>
+  (value: A): ReadonlyArray<B> => {
+    if (!latch.isOpen()) return nothing;
+    return route(value);
+  };
+
+/** A thunk calling `f(value)`, so Effect code can write `Effect.sync(applying(f, value))`. */
+export const applying =
+  <A, B>(f: (value: A) => B, value: A) =>
+  (): B =>
+    f(value);

package/src/dom/models.ts

@@ -0,0 +1,37 @@
+/**
+ * Plain three.js helpers for loaded models.
+ *
+ * @module
+ */
+import { type Material, Mesh, type Object3D, Texture } from 'three';
+
+/** Disposes every texture a material holds (maps of any kind). */
+const disposeMaterial = (material: Material): void => {
+  for (const value of Object.values(material)) {
+    if (value instanceof Texture) value.dispose();
+  }
+  material.dispose();
+};
+
+/** Disposes a mesh's geometry and materials; other objects hold nothing to free. */
+function disposeMesh(object: Object3D): void {
+  if (!(object instanceof Mesh)) return;
+  object.geometry.dispose();
+  const materials: ReadonlyArray<Material> = Array.isArray(object.material)
+    ? object.material
+    : [object.material];
+  for (const material of materials) disposeMaterial(material);
+}
+
+/** Disposes a loaded model's GPU resources: it was ours, not the application's. */
+export const disposeModel = (root: Object3D): void => {
+  root.traverse(disposeMesh);
+};
+
+export const namesIn = (root: Object3D): ReadonlyArray<string> => {
+  const names: Array<string> = [];
+  root.traverse((object) => {
+    if (object !== root && object.name !== '') names.push(object.name);
+  });
+  return names;
+};