@opsydyn/effect-three-foldkit 0.3.0 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsydyn/effect-three-foldkit",
-  "version": "0.3.0",
+  "version": "0.6.4",
   "description": "Thin Foldkit adapter for @opsydyn/effect-three.",
   "license": "MIT",
   "repository": {
@@ -44,17 +44,17 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
-    "@effect/platform-browser": "4.0.0",
+    "@effect/platform-browser": "4.1.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/effect-three": "0.6.3",
+    "@opsydyn/effect-three-troika": "0.6.3",
     "@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",
+    "effect": "4.1.0",
+    "foldkit": "0.170.0",
     "iwer": "2.5.0",
     "oxlint": "1.88.0",
     "oxlint-tsgolint": "7.0.2004",
@@ -66,9 +66,9 @@
     "typescript": "7.0.2"
   },
   "peerDependencies": {
-    "@opsydyn/effect-three": "0.3.0",
+    "@opsydyn/effect-three": "0.6.4",
     "effect": "^4.0.0",
-    "foldkit": "0.167.0",
+    "foldkit": ">=0.167.0 <0.171.0",
     "three": ">=0.186.0 <0.187.0"
   }
 }

package/src/assetRegistry.ts

@@ -0,0 +1,218 @@
+/**
+ * The assets scenes ask for with `scene({ assets })` (ADR-015), held for the environment:
+ * each loaded once however many scenes ask, lent to the store under its id, its load
+ * cancelled when no scene asks for it any more, and withdrawn and disposed when the last
+ * scene stops asking. Each scene hears whether what it asked for loaded or failed.
+ *
+ * An asset with coarser `levels` streams in: every level loads at once, each is lent as it
+ * arrives if it is finer than what is shown (replacing it), and once the finest is shown
+ * the coarser loads still under way are cancelled. Only the finest failing fails it.
+ *
+ * An id names one asset at a time: a scene asking for an id another scene holds as
+ * something else (another kind or URL) is told it failed, and gets it once the other lets
+ * go.
+ *
+ * @module
+ */
+import { type Asset, assetsEqual } from '@opsydyn/effect-three';
+
+/** An asset as loaded and lent: what a model offers, and how to withdraw and free it. */
+export type Lent = {
+  readonly parts: ReadonlyArray<string>;
+  readonly clips: ReadonlyArray<string>;
+  readonly release: () => void;
+};
+
+/** Loads one asset and lends it under its id; gives up (rejecting) when `signal` aborts. */
+export type AssetLoader = (asset: Asset, signal: AbortSignal) => Promise<Lent>;
+
+/**
+ * What a scene hears about an asset it asked for: a level of detail shown (0 for the
+ * coarsest of its levels, `levels.length` for its URL, the finest), or its finest failed.
+ */
+export type AssetNotice =
+  | ({
+      readonly _tag: 'Loaded';
+      readonly level: number;
+      readonly final: boolean;
+    } & Asset &
+      Pick<Lent, 'parts' | 'clips'>)
+  | ({ readonly _tag: 'Failed'; readonly reason: string } & Asset);
+
+/** Who asks: a mounted scene, by any object that stands for it. */
+type Holder = object;
+
+type Notify = (notice: AssetNotice) => void;
+
+type Entry = {
+  readonly asset: Asset;
+  readonly holders: Set<Holder>;
+  /** One a level, coarsest first: aborted once a finer level is shown, or the entry ends. */
+  readonly controllers: ReadonlyArray<AbortController>;
+  /** The finest level lent so far. */
+  shown: { readonly level: number; readonly lent: Lent } | undefined;
+  /** Why the finest level could not be loaded, once it could not. */
+  failure: string | undefined;
+};
+
+const sameAsset = (a: Asset, b: Asset): boolean =>
+  a.kind === b.kind &&
+  a.url === b.url &&
+  a.levels.length === b.levels.length &&
+  a.levels.every((level, i) => level === b.levels[i]);
+
+/** Every level's URL, coarsest first: the asset's own URL is the last, and finest. */
+const urlsOf = (asset: Asset): ReadonlyArray<string> => [...asset.levels, asset.url];
+
+const reasonOf = (asset: Asset, cause: unknown): string =>
+  cause instanceof Error && cause.message !== ''
+    ? `Could not load ${asset.url}: ${cause.message}`
+    : `Could not load ${asset.url}`;
+
+const taken = (asset: Asset, holding: Asset): AssetNotice => ({
+  _tag: 'Failed',
+  ...asset,
+  reason: `"${asset.id}" is already ${holding.url} for another scene`,
+});
+
+/** Creates the registry for one environment, loading with `load`. */
+export const makeAssetRegistry = (load: AssetLoader) => {
+  const entries = new Map<string, Entry>();
+  /** What each scene asks for now, and how to tell it. */
+  const asking = new Map<
+    Holder,
+    { readonly assets: ReadonlyArray<Asset>; readonly notify: Notify }
+  >();
+
+  const tellAll = (entry: Entry, notice: AssetNotice): void => {
+    for (const holder of entry.holders) asking.get(holder)?.notify(notice);
+  };
+
+  const loadedNotice = (entry: Entry, level: number, lent: Lent): AssetNotice => ({
+    _tag: 'Loaded',
+    ...entry.asset,
+    level,
+    final: level === entry.asset.levels.length,
+    parts: lent.parts,
+    clips: lent.clips,
+  });
+
+  /** What a scene that starts holding an entry hears at once: what is shown, and a failure. */
+  const noticesOf = (entry: Entry): ReadonlyArray<AssetNotice> => [
+    ...(entry.shown === undefined
+      ? []
+      : [loadedNotice(entry, entry.shown.level, entry.shown.lent)]),
+    ...(entry.failure === undefined
+      ? []
+      : [{ _tag: 'Failed' as const, ...entry.asset, reason: entry.failure }]),
+  ];
+
+  /** Starts loading every level of `asset`; what comes back too late is freed unseen. */
+  const start = (asset: Asset): Entry => {
+    const urls = urlsOf(asset);
+    const finest = urls.length - 1;
+    const entry: Entry = {
+      asset,
+      holders: new Set(),
+      controllers: urls.map(() => new AbortController()),
+      shown: undefined,
+      failure: undefined,
+    };
+    entries.set(asset.id, entry);
+    function current(level: number): boolean {
+      return entries.get(asset.id) === entry && entry.controllers[level]?.signal.aborted === false;
+    }
+    function loaded(level: number) {
+      return (lent: Lent): void => {
+        if (!current(level) || (entry.shown !== undefined && entry.shown.level >= level)) {
+          lent.release();
+          return;
+        }
+        // Lent first, then the coarser one freed: its withdrawal leaves the new loan.
+        const before = entry.shown;
+        entry.shown = { level, lent };
+        before?.lent.release();
+        if (level === finest)
+          for (const coarser of entry.controllers.slice(0, level)) coarser.abort();
+        tellAll(entry, loadedNotice(entry, level, lent));
+      };
+    }
+    function failed(level: number) {
+      return (cause: unknown): void => {
+        // A coarser level that fails is skipped; only the finest failing fails the asset.
+        if (!current(level) || level !== finest) return;
+        const reason = reasonOf({ ...asset, url: urls[level] ?? asset.url }, cause);
+        entry.failure = reason;
+        tellAll(entry, { _tag: 'Failed', ...asset, reason });
+      };
+    }
+    urls.forEach((url, level) => {
+      const signal = entry.controllers[level]?.signal ?? AbortSignal.abort();
+      load({ ...asset, url }, signal).then(loaded(level), failed(level));
+    });
+    return entry;
+  };
+
+  /** Ends an entry: its loads cancelled, and what it lent withdrawn and freed. */
+  const end = (entry: Entry): void => {
+    entries.delete(entry.asset.id);
+    for (const controller of entry.controllers) controller.abort();
+    entry.shown?.lent.release();
+  };
+
+  /** `holder` lets go of `id`; the last to let go ends it, and whoever waited on it asks again. */
+  const letGo = (holder: Holder, id: string): void => {
+    const entry = entries.get(id);
+    if (entry === undefined || !entry.holders.delete(holder) || entry.holders.size > 0) return;
+    end(entry);
+    for (const [waiting, { assets }] of asking) {
+      if (assets.some((asset) => asset.id === id)) hold(waiting, assets);
+    }
+  };
+
+  /** `holder` takes each of `assets` it does not hold yet. */
+  const hold = (holder: Holder, assets: ReadonlyArray<Asset>): void => {
+    for (const asset of assets) {
+      const entry = entries.get(asset.id) ?? start(asset);
+      if (!sameAsset(entry.asset, asset)) {
+        asking.get(holder)?.notify(taken(asset, entry.asset));
+        continue;
+      }
+      if (entry.holders.has(holder)) continue;
+      entry.holders.add(holder);
+      for (const notice of noticesOf(entry)) asking.get(holder)?.notify(notice);
+    }
+  };
+
+  /**
+   * What `holder` asks for now: loads what is new, lets go of what it no longer asks for
+   * (or asks for as something else), and tells it, through `notify`, when each asset it
+   * holds has loaded or failed (at once, for one loaded already).
+   */
+  const want = (holder: Holder, assets: ReadonlyArray<Asset>, notify: Notify): void => {
+    const before = asking.get(holder);
+    asking.set(holder, { assets, notify });
+    if (before !== undefined && assetsEqual(before.assets, assets)) return;
+    for (const old of before?.assets ?? []) {
+      const still = assets.find((asset) => asset.id === old.id);
+      if (still === undefined || !sameAsset(still, old)) letGo(holder, old.id);
+    }
+    hold(holder, assets);
+  };
+
+  /** `holder` (a scene going away) asks for nothing any more. */
+  const release = (holder: Holder): void => {
+    want(holder, [], () => undefined);
+    asking.delete(holder);
+  };
+
+  /** Ends every load and frees every asset (the environment going away). */
+  const dispose = (): void => {
+    asking.clear();
+    for (const entry of [...entries.values()]) end(entry);
+  };
+
+  return { want, release, dispose };
+};
+
+export type AssetRegistry = ReturnType<typeof makeAssetRegistry>;

package/src/assets.ts

@@ -1,16 +1,23 @@
 /**
- * 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.
+ * Loading textures, glTF models, HDR panoramas and typeface fonts by URL. 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, `environment({ map: id })` a panorama, and
+ * `text({ font: id })` geometry draws with a font.
+ *
+ * Two ways in. A scene can ask for assets in its description (`scene({ assets })`), and
+ * the environment's registry loads, shares, cancels and frees them as scenes ask
+ * (`assetLoader` is what it loads with; ADR-015). Or an application loads one with an
+ * Effect from a Command and settles it into `AsyncData`; the environment owns what it
+ * loads that way, loading an id again replaces and disposes the earlier asset, and
+ * `unload` or the environment's `dispose` frees it. Use one way for any one id.
  *
  * @module
  */
-import type { ResourceStore } from '@opsydyn/effect-three';
+import type { Asset, AssetKind, ResourceStore } from '@opsydyn/effect-three';
 import { Data, Effect } from 'effect';
 import {
   EquirectangularReflectionMapping,
+  LoadingManager,
   type Object3D,
   SRGBColorSpace,
   type Texture,
@@ -20,6 +27,7 @@ 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 type { AssetLoader, Lent } from './assetRegistry.ts';
 import { disposeModel, namesIn } from './dom/models.ts';
 
 /** An asset could not be fetched or decoded. */
@@ -37,6 +45,78 @@ export type ModelInfo = {
   readonly clips: ReadonlyArray<string>;
 };
 
+type Gltf = { readonly scene: Object3D; readonly animations: Object3D['animations'] };
+
+const nothing: ReadonlyArray<string> = [];
+
+/** What lending an asset gives back: no parts or clips, and how to withdraw and free it. */
+const plain = (release: () => void): Lent => ({ parts: nothing, clips: nothing, release });
+
+/** Lends a colour texture (sRGB). */
+const lentTexture = (store: ResourceStore, id: string, texture: Texture): Lent => {
+  texture.colorSpace = SRGBColorSpace;
+  const withdraw = store.lendTexture(id, texture);
+  return plain(() => {
+    withdraw();
+    texture.dispose();
+  });
+};
+
+/** Lends a model's scene, keeping its clips with it so a borrowed node can play them. */
+const lentModel = (store: ResourceStore, id: string, gltf: Gltf): Lent => {
+  gltf.scene.animations = gltf.animations;
+  const withdraw = store.lend(id, gltf.scene);
+  return {
+    parts: namesIn(gltf.scene),
+    clips: gltf.animations.map((clip) => clip.name),
+    release: () => {
+      withdraw();
+      disposeModel(gltf.scene);
+    },
+  };
+};
+
+/** Lends an HDR panorama for `environment({ map })`: linear, mapped for reflection. */
+const lentEnvironment = (store: ResourceStore, id: string, texture: Texture): Lent => {
+  texture.mapping = EquirectangularReflectionMapping;
+  const withdraw = store.lendTexture(id, texture);
+  return plain(() => {
+    withdraw();
+    texture.dispose();
+  });
+};
+
+/** Lends a font; fonts hold no GPU resources, so withdrawing the loan frees them. */
+const lentFont = (store: ResourceStore, id: string, font: Font): Lent =>
+  plain(store.lendFont(id, font));
+
+type LoadAndLend = (store: ResourceStore, asset: Asset, manager: LoadingManager) => Promise<Lent>;
+
+/** How each kind of asset loads, with a loading manager of its own, and is lent. */
+const loadAndLend = {
+  model: async (store, { id, url }, manager) =>
+    lentModel(store, id, await new GLTFLoader(manager).loadAsync(url)),
+  texture: async (store, { id, url }, manager) =>
+    lentTexture(store, id, await new TextureLoader(manager).loadAsync(url)),
+  environment: async (store, { id, url }, manager) =>
+    lentEnvironment(store, id, await new HDRLoader(manager).loadAsync(url)),
+  font: async (store, { id, url }, manager) =>
+    lentFont(store, id, await new FontLoader(manager).loadAsync(url)),
+} satisfies Record<AssetKind, LoadAndLend>;
+
+/**
+ * What the environment's registry loads scenes' assets with: three's loaders, each load
+ * with a loading manager of its own, so aborting it cancels its requests (three's file
+ * and image-bitmap loaders honour the manager's abort).
+ */
+export const assetLoader =
+  (store: ResourceStore): AssetLoader =>
+  (asset, signal) => {
+    const manager = new LoadingManager();
+    signal.addEventListener('abort', () => manager.abort(), { once: true });
+    return loadAndLend[asset.kind](store, asset, manager);
+  };
+
 /** Creates the asset loader for a store. One per environment. */
 export const makeAssets = (store: ResourceStore) => {
   const releases = new Map<string, () => void>();
@@ -48,47 +128,24 @@ export const makeAssets = (store: ResourceStore) => {
   };
 
   const lendTexture = (id: string) => (texture: Texture) => {
-    texture.colorSpace = SRGBColorSpace;
-    const withdraw = store.lendTexture(id, texture);
-    own(id, () => {
-      withdraw();
-      texture.dispose();
-    });
+    own(id, lentTexture(store, id, texture).release);
     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 lendModel = (id: string) => (gltf: Gltf) => {
+    const lent = lentModel(store, id, gltf);
+    own(id, lent.release);
+    const info: ModelInfo = { id, parts: lent.parts, clips: lent.clips };
+    return info;
+  };
+
   const lendEnvironment = (id: string) => (texture: Texture) => {
-    texture.mapping = EquirectangularReflectionMapping;
-    const withdraw = store.lendTexture(id, texture);
-    own(id, () => {
-      withdraw();
-      texture.dispose();
-    });
+    own(id, lentEnvironment(store, id, texture).release);
     return id;
   };
 
   const lendFont = (id: string) => (font: Font) => {
-    // Fonts hold no GPU resources: withdrawing the loan frees them.
-    own(id, store.lendFont(id, font));
+    own(id, lentFont(store, id, font).release);
     return id;
   };
 

package/src/boxSelect.ts

@@ -0,0 +1,158 @@
+/**
+ * Box selection as a Foldkit submodel (roadmap, "Beyond parity" 5), after Drei's `Select`
+ * over three.js's `SelectionBox`: a shift-drag that begins on nothing draws a box, and
+ * its release selects what the box holds, through the core's pure `boxSelect`. The parent
+ * owns what is selected; the submodel owns only the box:
+ *
+ * - `Dragged` (each scene `Drag` gesture the box `claims`, made with `dragOf`) starts the box
+ *   where the press was and moves its far corner by the gesture's deltas;
+ * - `Ended` (the scene's `GestureEnd`, with the camera and what can be selected) reports
+ *   `Selected { keys }`, which replaces the selection as Drei's box does, and clears the
+ *   box;
+ * - `Cancelled` clears the box and selects nothing.
+ *
+ * `rectangle(model)` places the box on the canvas in CSS pixels, for an HTML outline, and
+ * `inside(model, camera, selectable)` says what the box holds so far, for highlighting
+ * while it is drawn (Drei selects as the box moves).
+ *
+ * @module
+ */
+import { boxSelect, type Camera, type Gesture, SceneSchema } from '@opsydyn/effect-three';
+import { Option, Schema } from 'effect';
+import { defineMessageUnion } from 'foldkit/message';
+import type { ReturnWithOutMessage } from 'foldkit/update';
+
+const Corner = Schema.Struct({ x: Schema.Finite, y: Schema.Finite });
+
+/** Something the box can select: its key, and the point that must fall inside. */
+const Selectable = Schema.Struct({ key: Schema.String, at: SceneSchema.Vec3 });
+
+/** A box being drawn: its corners in the canvas's normalised coordinates, −1 to 1, y up. */
+export const Box = Schema.Struct({
+  from: Corner,
+  to: Corner,
+  width: Schema.Finite,
+  height: Schema.Finite,
+});
+export type Box = typeof Box.Type;
+
+export const Model = Schema.Struct({ box: Schema.Option(Box) });
+export type Model = typeof Model.Type;
+
+export const Message = defineMessageUnion({
+  Dragged: {
+    x: Schema.Finite,
+    y: Schema.Finite,
+    deltaX: Schema.Finite,
+    deltaY: Schema.Finite,
+    width: Schema.Finite,
+    height: Schema.Finite,
+  },
+  Ended: { camera: SceneSchema.Camera, selectable: Schema.Array(Selectable) },
+  Cancelled: {},
+});
+export type Message = typeof Message.Type;
+
+export const OutMessage = defineMessageUnion({
+  /** The box was let go: the keys inside it, for the new selection. */
+  Selected: { keys: Schema.Array(Schema.String) },
+});
+export type OutMessage = typeof OutMessage.Type;
+
+/** No box drawn. */
+export const init = (): Model => ({ box: Option.none() });
+
+type Return = ReturnWithOutMessage<Model, Message, OutMessage>;
+
+/** The box with its far corner moved by a drag's CSS-pixel deltas (down positive). */
+const moved = (box: Box, deltaX: number, deltaY: number): Box => ({
+  ...box,
+  to: { x: box.to.x + (deltaX * 2) / box.width, y: box.to.y - (deltaY * 2) / box.height },
+});
+
+const dragged = (model: Model, message: Extract<Message, { _tag: 'Dragged' }>): Model => {
+  const { x, y, deltaX, deltaY, width, height } = message;
+  const start: Box = { from: { x, y }, to: { x, y }, width, height };
+  const box = Option.getOrElse(model.box, () => start);
+  return { box: Option.some(moved(box, deltaX, deltaY)) };
+};
+
+type Selectables = ReadonlyArray<typeof Selectable.Type>;
+
+const keysIn = (box: Box, camera: Camera, selectable: Selectables): ReadonlyArray<string> =>
+  boxSelect(camera, box, box.from, box.to, selectable);
+
+const ended = (model: Model, camera: Camera, selectable: Selectables): Return =>
+  Option.match(model.box, {
+    onNone: () => ({ model }),
+    onSome: (box) => ({
+      model: init(),
+      outMessage: OutMessage.Selected({ keys: keysIn(box, camera, selectable) }),
+    }),
+  });
+
+export const update = (model: Model, message: Message): Return =>
+  Message.match<Return>(message, {
+    Dragged: (drag) => ({ model: dragged(model, drag) }),
+    Ended: ({ camera, selectable }) => ended(model, camera, selectable),
+    Cancelled: () => ({ model: init() }),
+  });
+
+/** Whether a box is being drawn: the parent leaves the camera alone while it is. */
+export const drawing = (model: Model): boolean => Option.isSome(model.box);
+
+/** A scene `Drag` gesture: the only kind a box takes. */
+export type DragGesture = Extract<Gesture, { readonly _tag: 'Drag' }>;
+
+/** The primary button: a box starts only with it. */
+const primaryButton = 0;
+
+/** A primary-button shift-drag that began on nothing starts a box. */
+const startsBox = (drag: DragGesture): boolean =>
+  drag.button === primaryButton && drag.modifiers.shift && drag.key === undefined;
+
+/** Whether the box takes `drag`: every drag while one is drawn, and one that starts it. */
+export const claims = (model: Model, drag: DragGesture): boolean =>
+  drawing(model) || startsBox(drag);
+
+/** The `Dragged` Message for a drag the box claims. */
+export const dragOf = (gesture: DragGesture): Message =>
+  Message.Dragged({
+    x: gesture.x,
+    y: gesture.y,
+    deltaX: gesture.deltaX,
+    deltaY: gesture.deltaY,
+    width: gesture.width,
+    height: gesture.height,
+  });
+
+/** What the box holds so far, seen through `camera`: none while no box is drawn. */
+export const inside = (
+  model: Model,
+  camera: Camera,
+  selectable: Selectables,
+): ReadonlyArray<string> =>
+  Option.match(model.box, {
+    onNone: () => [],
+    onSome: (box) => keysIn(box, camera, selectable),
+  });
+
+/** A box on the canvas, in CSS pixels from its top left. */
+export type Rectangle = {
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+};
+
+const onCanvas = (box: Box): Rectangle => {
+  const left = ((Math.min(box.from.x, box.to.x) + 1) / 2) * box.width;
+  const right = ((Math.max(box.from.x, box.to.x) + 1) / 2) * box.width;
+  const top = ((1 - Math.max(box.from.y, box.to.y)) / 2) * box.height;
+  const bottom = ((1 - Math.min(box.from.y, box.to.y)) / 2) * box.height;
+  return { left, top, width: right - left, height: bottom - top };
+};
+
+/** Where the box sits on the canvas, while one is drawn. */
+export const rectangle = (model: Model): Option.Option<Rectangle> =>
+  Option.map(model.box, onCanvas);

package/src/dom/canvas.ts

@@ -5,6 +5,7 @@
  */
 import type { Op, ResourceStore, SceneEvent } from '@opsydyn/effect-three';
 
+import type { AssetNotice } from '../assetRegistry.ts';
 import { domEventName, type SceneError } from '../element.ts';
 import type { Latch } from './latch.ts';
 import { summarise } from './reconciled.ts';
@@ -31,6 +32,17 @@ export const dispatchSceneError = (element: Element, error: SceneError): void =>
   element.dispatchEvent(new CustomEvent('scene-error', { detail: { error } }));
 };
 
+/**
+ * Dispatches what the environment says about an asset the scene asked for, as a
+ * `scene-asset-loaded` or `scene-asset-failed` event. Not held back while time travel is
+ * paused: whether an asset loaded is a fact about the page, not a frame.
+ */
+export const dispatchAssetNotice = (element: Element, notice: AssetNotice): void => {
+  const { _tag, ...detail } = notice;
+  const name = _tag === 'Loaded' ? 'scene-asset-loaded' : 'scene-asset-failed';
+  element.dispatchEvent(new CustomEvent(name, { detail }));
+};
+
 /** 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();

package/src/dom/pointer.ts

@@ -3,7 +3,13 @@
  *
  * @module
  */
-import type { Gestures, Modifiers, PointerInput, SceneEvent } from '@opsydyn/effect-three';
+import type {
+  Gestures,
+  Modifiers,
+  PointerDevice,
+  PointerInput,
+  SceneEvent,
+} from '@opsydyn/effect-three';
 
 /** The part of `DOMRect` the conversion needs. */
 export type Rect = {
@@ -33,6 +39,12 @@ const modifiersOf = (event: MouseEvent): Modifiers => ({
   alt: event.altKey,
 });
 
+/** What pressed: a finger, a pen, or (for anything else, and plain mouse events) a mouse. */
+const deviceOf = (event: MouseEvent): PointerDevice =>
+  event instanceof PointerEvent && (event.pointerType === 'touch' || event.pointerType === 'pen')
+    ? event.pointerType
+    : 'mouse';
+
 /** The pointer's id, or 0 for mouse events that are not pointer events. */
 const pointerIdOf = (event: MouseEvent): number =>
   event instanceof PointerEvent ? event.pointerId : 0;
@@ -64,6 +76,7 @@ export const toPointerInput = (event: MouseEvent, rect: Rect): PointerInput | un
         button: event.button,
         pointer,
         modifiers: modifiersOf(event),
+        device: deviceOf(event),
       };
     case 'pointerup':
       return { _tag: 'PointerUp', x, y, button: event.button, pointer };

package/src/dom/webgl.ts

@@ -184,6 +184,21 @@ export const webglRendererFactory = (
         // Effects apply to the single full view only; views draw straight to the screen.
         renderer.render(scene, camera);
       },
+      renderOver: (scene, camera) => {
+        if (renderer.xr.isPresenting) return;
+        if (scissored) {
+          const { width, height } = renderer.getSize(drawingSize);
+          renderer.setScissorTest(false);
+          renderer.setViewport(0, 0, width, height);
+          scissored = false;
+        }
+        // As Drei's Hud: keep what is drawn, clear depth so the HUD is never hidden by it.
+        const autoClear = renderer.autoClear;
+        renderer.autoClear = false;
+        renderer.clearDepth();
+        renderer.render(scene, camera);
+        renderer.autoClear = autoClear;
+      },
       createTarget: (width, height) => createTarget(targets, width, height),
       createEnvironment: () => createRoom(renderer),
       configure: (settings) => {