@opsydyn/effect-three-foldkit 0.3.0 → 0.6.4

package/src/dom/webgpu.ts

@@ -177,6 +177,21 @@ export const webgpuRendererFactory = (
         scissored = true;
         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) => {

package/src/element.ts

@@ -59,9 +59,11 @@ export const sceneElement = CustomElement.define({
     'scene-drag': SceneSchema.DragDetail,
     'scene-drag-end': SceneSchema.DragDetail,
     'scene-gesture': SceneSchema.GestureDetail,
+    'scene-gesture-end': SceneSchema.GestureEndDetail,
     'scene-auto-rotated': SceneSchema.AutoRotatedDetail,
     'scene-collision': SceneSchema.CollisionDetail,
     'scene-contact-force': SceneSchema.ContactForceDetail,
+    'scene-physics-reached': SceneSchema.PhysicsReachedDetail,
     'scene-measured': SceneSchema.MeasuredDetail,
     'scene-label-measured': SceneSchema.LabelMeasuredDetail,
     'scene-xr': XrSessionDetail,
@@ -73,6 +75,8 @@ export const sceneElement = CustomElement.define({
     'scene-xr-meshes': SceneSchema.XrMeshesDetail,
     'scene-performance': SceneSchema.PerformanceDetail,
     'scene-error': Schema.Struct({ error: SceneError }),
+    'scene-asset-loaded': SceneSchema.AssetLoadedDetail,
+    'scene-asset-failed': SceneSchema.AssetFailedDetail,
     'scene-reconciled': ReconciledDetail,
   },
 });
@@ -92,9 +96,11 @@ export const domEventName = {
   Drag: 'scene-drag',
   DragEnd: 'scene-drag-end',
   Gesture: 'scene-gesture',
+  GestureEnd: 'scene-gesture-end',
   AutoRotated: 'scene-auto-rotated',
   Collision: 'scene-collision',
   ContactForce: 'scene-contact-force',
+  PhysicsReached: 'scene-physics-reached',
   Measured: 'scene-measured',
   LabelMeasured: 'scene-label-measured',
   XrStick: 'scene-xr-stick',

package/src/environment.ts

@@ -13,7 +13,8 @@ import {
   type ResourceStore,
 } from '@opsydyn/effect-three';
 
-import { makeAssets } from './assets.ts';
+import { makeAssetRegistry } from './assetRegistry.ts';
+import { assetLoader, 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';
@@ -49,6 +50,7 @@ export type EnvironmentOptions = {
 export const makeEnvironment = (host: EnvironmentHost, options: EnvironmentOptions = {}) => {
   const store: ResourceStore = createResourceStore();
   const assets = makeAssets(store);
+  const assetRegistry = makeAssetRegistry(assetLoader(store));
   const xrHub = createXrHub(() => host.navigator?.xr);
   return {
     host,
@@ -63,12 +65,15 @@ export const makeEnvironment = (host: EnvironmentHost, options: EnvironmentOptio
     labels: options.labels,
     /** Loads textures and glTF models by URL and lends them to the store. */
     assets,
+    /** The assets scenes ask for in their descriptions: loaded, shared, cancelled, freed. */
+    assetRegistry,
     /** 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: () => {
+      assetRegistry.dispose();
       assets.dispose();
       store.dispose();
     },

package/src/index.ts

@@ -44,21 +44,31 @@ export {
   type EnvironmentOptions,
   makeEnvironment,
 } from './environment.ts';
+export { inspectorView, type OnEdit } from './inspector.ts';
 export { makeSceneMount, type SceneMount } from './mount.ts';
+export * as BoxSelect from './boxSelect.ts';
+export * as MeasuringTape from './measuringTape.ts';
+export * as PivotControls from './pivotControls.ts';
+export * as TransformGizmo from './transformGizmo.ts';
+export * as ViewportGizmo from './viewportGizmo.ts';
 export { type OverlayView } from './overlayView.ts';
 export {
+  type AssetFailedDetail,
+  type AssetLoadedDetail,
   type AutoRotatedDetail,
   type ButtonDetail,
   type CollisionDetail,
   type ContactForceDetail,
   type DragDetail,
   type Gesture,
+  type GestureEndDetail,
   type HitDetail,
   type KeyDetail,
   type LabelMeasuredDetail,
   type MeasuredDetail,
   type MissDetail,
   type PerformanceDetail,
+  type PhysicsReachedDetail,
   view,
   type ViewConfig,
   type WheelDetail,

package/src/inspector.ts

@@ -0,0 +1,112 @@
+/**
+ * An inspector panel for Foldkit views (roadmap, "Beyond parity" 4): the fields the
+ * core's `Inspector.fields` reads from a schema, drawn as a form. Each control reports
+ * an edit as the app's own Message, with the field's path and the new value; the app
+ * applies it with `Inspector.edit`, which the schema checks, and keeps the result (or
+ * shows why it was refused).
+ *
+ * Numbers, text and choices report when they change (on Enter or leaving the field),
+ * colours as they are picked, switches when clicked, and each of a vector's three
+ * numbers on its own. Kinds, absent parts and lists are shown, not edited.
+ *
+ * @module
+ */
+import type { FieldPath, FieldValue, InspectedField } from '@opsydyn/effect-three';
+import type { Html, HtmlBuilder } from 'foldkit/html';
+
+/** Turns an edit (where, and the new value) into the app's Message. */
+export type OnEdit<Message> = (path: FieldPath, value: FieldValue) => Message;
+
+const axisNames = ['x', 'y', 'z'] as const;
+
+/** The field's name for people: its property names, without list indices. */
+const nameOf = (field: InspectedField): string =>
+  field.path.filter((part) => typeof part === 'string').join(' ') || field.label;
+
+const hex = (colour: number): string => `#${colour.toString(16).padStart(6, '0')}`;
+
+const numberInput = <Message>(
+  h: HtmlBuilder<Message>,
+  label: string,
+  value: number,
+  report: (raw: string) => Message,
+): Html =>
+  h.input([
+    h.Type('number'),
+    h.Step('any'),
+    h.Value(String(value)),
+    h.AriaLabel(label),
+    h.OnChange(report),
+  ]);
+
+const controlOf = <Message>(
+  h: HtmlBuilder<Message>,
+  field: InspectedField,
+  onEdit: OnEdit<Message>,
+): Html => {
+  const name = nameOf(field);
+  switch (field._tag) {
+    case 'Number':
+      return numberInput(h, name, field.value, (raw) => onEdit(field.path, Number(raw)));
+    case 'Text':
+      return h.input([
+        h.Type('text'),
+        h.Value(field.value),
+        h.AriaLabel(name),
+        h.OnChange((raw) => onEdit(field.path, raw)),
+      ]);
+    case 'Toggle':
+      return h.input([
+        h.Type('checkbox'),
+        h.Checked(field.value),
+        h.AriaLabel(name),
+        h.OnClick(onEdit(field.path, !field.value)),
+      ]);
+    case 'Choice':
+      return h.select(
+        [h.AriaLabel(name), h.OnChange((raw) => onEdit(field.path, raw))],
+        field.options.map((option) =>
+          h.option([h.Value(option), h.Selected(option === field.value)], [option]),
+        ),
+      );
+    case 'Colour':
+      return h.input([
+        h.Type('color'),
+        h.Value(hex(field.value)),
+        h.AriaLabel(name),
+        h.OnInput((raw) => onEdit(field.path, Number.parseInt(raw.slice(1), 16))),
+      ]);
+    case 'Vector':
+      return h.span(
+        [h.Class('e3-inspector-vector')],
+        field.value.map((component, index) =>
+          numberInput(h, `${name} ${axisNames[index] ?? index}`, component, (raw) =>
+            onEdit([...field.path, index], Number(raw)),
+          ),
+        ),
+      );
+    case 'Fixed':
+      return h.span([h.Class('e3-inspector-fixed')], [field.text]);
+  }
+};
+
+/**
+ * The fields as a form: a row each, its name and its control, keyed by path. Style it
+ * with the classes `e3-inspector`, `e3-inspector-row`, `e3-inspector-name`,
+ * `e3-inspector-vector` and `e3-inspector-fixed`.
+ */
+export const inspectorView = <Message>(
+  h: HtmlBuilder<Message>,
+  fields: ReadonlyArray<InspectedField>,
+  onEdit: OnEdit<Message>,
+): Html =>
+  h.div(
+    [h.Class('e3-inspector')],
+    fields.map((field) =>
+      h.keyed('label')(
+        field.path.join('.'),
+        [h.Class('e3-inspector-row')],
+        [h.span([h.Class('e3-inspector-name')], [nameOf(field)]), controlOf(h, field, onEdit)],
+      ),
+    ),
+  );

package/src/measuringTape.ts

@@ -0,0 +1,124 @@
+/**
+ * A measuring tape as a Foldkit submodel (roadmap, "Beyond parity" 5): the core's pure
+ * `tape` with Messages for clicks and pointer moves on the scene, an OutMessage when a
+ * length is measured, and its length as HTML at the tape's middle. The parent decides
+ * when the tape is in use and which clicks are on the scene:
+ *
+ * - `Placed` (a click on the scene, with the point it hit) places an end, or starts a
+ *   new tape; placing the second reports `Measured { from, to, length }`;
+ * - `Pointed` (the pointer moving over the scene, or `null` off it) runs the tape to
+ *   the pointer while the second end is placed;
+ * - `Cleared` empties it; `ChoseSnap` rounds new ends to a step, or not.
+ *
+ * `nodes(model)` draws it for the scene and `label(model, h)` is the length for the
+ * view's `overlays`.
+ *
+ * @module
+ */
+import {
+  clearTape,
+  overlay,
+  placeTapeEnd,
+  pointTape,
+  SceneSchema,
+  type SceneNode,
+  tape,
+  tapeLength,
+  type TapeLook,
+  tapeMiddle,
+  tapeNodes,
+} from '@opsydyn/effect-three';
+import { Option, Schema } from 'effect';
+import type { HtmlBuilder } from 'foldkit/html';
+import { defineMessageUnion } from 'foldkit/message';
+import type { ReturnWithOutMessage } from 'foldkit/update';
+
+import type { OverlayView } from './overlayView.ts';
+
+export const Model = Schema.Struct({
+  /** The key its nodes and label are drawn under. */
+  key: Schema.String,
+  tape: SceneSchema.Tape,
+});
+export type Model = typeof Model.Type;
+
+export const Message = defineMessageUnion({
+  Placed: { point: SceneSchema.Vec3 },
+  Pointed: { point: Schema.NullOr(SceneSchema.Vec3) },
+  Cleared: {},
+  ChoseSnap: { snap: SceneSchema.Tape.fields.snap },
+});
+export type Message = typeof Message.Type;
+
+export const OutMessage = defineMessageUnion({
+  /** Both ends are placed: where, and how far apart. */
+  Measured: { from: SceneSchema.Vec3, to: SceneSchema.Vec3, length: Schema.Finite },
+});
+export type OutMessage = typeof OutMessage.Type;
+
+/** An empty tape drawn under `key`, snapping to `snap` when given. */
+export const init = (key: string, options: { readonly snap?: number | null } = {}): Model => ({
+  key,
+  tape: tape(options),
+});
+
+type Return = ReturnWithOutMessage<Model, Message, OutMessage>;
+
+/** The OutMessage for a tape that has just been measured, if it has. */
+const measured = (next: Model): Return =>
+  Option.match(
+    Option.all([Option.fromNullishOr(next.tape.from), Option.fromNullishOr(next.tape.to)]),
+    {
+      onNone: () => ({ model: next }),
+      onSome: ([from, to]) => ({
+        model: next,
+        outMessage: OutMessage.Measured({ from, to, length: tapeLength(next.tape) ?? 0 }),
+      }),
+    },
+  );
+
+export const update = (model: Model, message: Message): Return =>
+  Message.match<Return>(message, {
+    Placed: ({ point }) => measured({ ...model, tape: placeTapeEnd(model.tape, point) }),
+    Pointed: ({ point }) => ({ model: { ...model, tape: pointTape(model.tape, point) } }),
+    Cleared: () => ({ model: { ...model, tape: clearTape(model.tape) } }),
+    ChoseSnap: ({ snap }) => ({ model: { ...model, tape: { ...model.tape, snap } } }),
+  });
+
+/** The tape's length, while it has one (to the pointer while the second end is placed). */
+export const length = (model: Model): Option.Option<number> =>
+  Option.fromNullishOr(tapeLength(model.tape));
+
+/** The tape, for the parent's scene. */
+export const nodes = (model: Model, look: Partial<TapeLook> = {}): SceneNode =>
+  tapeNodes(model.key, model.tape, look);
+
+/** The label's class, when one is given. */
+const classOf = <Message>(h: HtmlBuilder<Message>, className: string | undefined) =>
+  Option.match(Option.fromNullishOr(className), {
+    onNone: () => [],
+    onSome: (name) => [h.Class(name)],
+  });
+
+/**
+ * The length at the tape's middle, for the view's `overlays`: two decimals and `unit`
+ * (`m` unless given), in an element with the class `className` (unstyled unless given).
+ * Pointer events pass through it to the scene.
+ */
+export const label = <Message>(
+  model: Model,
+  h: HtmlBuilder<Message>,
+  options: { readonly unit?: string; readonly className?: string } = {},
+): ReadonlyArray<OverlayView> =>
+  Option.match(Option.all([length(model), Option.fromNullishOr(tapeMiddle(model.tape))]), {
+    onNone: () => [],
+    onSome: ([measuredLength, middle]) => [
+      {
+        overlay: overlay({ key: `${model.key}:label`, position: middle, center: true }),
+        content: h.span(classOf(h, options.className), [
+          `${measuredLength.toFixed(2)} ${options.unit ?? 'm'}`,
+        ]),
+        pointerEvents: 'none',
+      },
+    ],
+  });

package/src/mount.ts

@@ -27,6 +27,7 @@ import {
   removal,
   sceneErrorDispatch,
   sceneEventDispatch,
+  dispatchAssetNotice,
 } from './dom/canvas.ts';
 import { applying, createLatch, type Latch, routedWhileOpen } from './dom/latch.ts';
 import { containOverlays, createOverlayWriter, type OverlayWriter } from './dom/overlays.ts';
@@ -140,6 +141,27 @@ const connectObserver =
 const observed = <A>(observe: (emit: (value: A) => void) => () => void) =>
   Stream.callback<A>(connectObserver(observe));
 
+/** What the scene asks for now, given to the environment's asset registry. */
+const asking = (mounted: Mounted, scene: SceneDescription) => () =>
+  mounted.environment.assetRegistry.want(mounted.element, scene.assets, (notice) =>
+    dispatchAssetNotice(mounted.element, notice),
+  );
+
+const lettingGo = (mounted: Mounted) => () =>
+  mounted.environment.assetRegistry.release(mounted.element);
+
+/** The scene's assets, asked for while it is mounted: going, it asks for none. */
+const acquireAssets = (mounted: Mounted, initial: SceneDescription) => {
+  const ask = Effect.sync(asking(mounted, initial));
+  return Effect.acquireRelease(ask, () => Effect.sync(lettingGo(mounted)));
+};
+
+/** An update applied, then what it asks for given to the registry (a refused one asks nothing). */
+const updated = (mounted: Mounted) => (scene: SceneDescription) => {
+  const ask = Effect.sync(asking(mounted, scene));
+  return Effect.tap(mounted.handle.update(scene), () => ask);
+};
+
 const applyUpdate = (mounted: Mounted) => (value: unknown) => {
   const reportError = sceneErrorDispatch(mounted.element);
   const reportReconciled = afterUpdate(
@@ -148,7 +170,7 @@ const applyUpdate = (mounted: Mounted) => (value: unknown) => {
   );
   const decoded = decodeScene(value);
   const applied = decoded.pipe(
-    Effect.flatMap(mounted.handle.update),
+    Effect.flatMap(updated(mounted)),
     Effect.flatMap((ops) => Effect.sync(reportReconciled(ops))),
   );
   return applied.pipe(
@@ -258,6 +280,7 @@ function* runScene(
     gate: createFrameGate(frames),
     live: createLatch(true),
   };
+  yield* acquireAssets(mounted, initial);
   yield* acquirePointer(canvas, mounted);
   yield* acquireXrTarget(mounted);
   yield* Effect.sync(touchActionSync(canvas, handle.graph));

package/src/pivotControls.ts

@@ -0,0 +1,118 @@
+/**
+ * Pivot controls as a Foldkit submodel (roadmap, "Beyond parity" 5): the core's pure
+ * `pivotNodes`, `pressPivot` and `dragPivot` (after Drei's `PivotControls`) with
+ * Messages for the scene's pointer events and OutMessages for what the parent does with
+ * them, as `TransformGizmo` is for three's controls. The parent owns where its objects
+ * are; the submodel owns only the handles:
+ *
+ * - `Pressed` (a pointer down on one of its handles, with the point it hit and the
+ *   object's placement) takes hold;
+ * - `Dragged` reports `Moved { placement }` for the parent to apply (`snap` rounds turns
+ *   to ten degrees and scales to tenths, as Drei's shift does);
+ * - `Released` lets go and reports `Finished { placement }`, a step for history;
+ * - `Hovered` highlights a handle.
+ *
+ * `handleOf(model, key)` says whether a hit is on a handle, and `nodes(model, placement)`
+ * draws them.
+ *
+ * @module
+ */
+import {
+  dragPivot,
+  hoverPivot,
+  type Pivot,
+  pivot,
+  type PivotHandle,
+  pivotHandleOf,
+  pivotNodes,
+  type Placement,
+  pressPivot,
+  releasePivot,
+  SceneSchema,
+  type SceneNode,
+  type Vec3,
+} from '@opsydyn/effect-three';
+import { Option, Schema } from 'effect';
+import { defineMessageUnion } from 'foldkit/message';
+import type { ReturnWithOutMessage } from 'foldkit/update';
+
+export const Model = Schema.Struct({
+  /** The key its handles are drawn under: `${key}:arrow-x`, `${key}:slider-z` and so on. */
+  key: Schema.String,
+  pivot: SceneSchema.Pivot,
+  /** The placement the drag last reported, so `Released` can report where it ended. */
+  last: Schema.Option(SceneSchema.Placement),
+});
+export type Model = typeof Model.Type;
+
+const Handle = SceneSchema.PivotHandle;
+
+export const Message = defineMessageUnion({
+  Pressed: { handle: Handle, point: SceneSchema.Vec3, placement: SceneSchema.Placement },
+  Dragged: { origin: SceneSchema.Vec3, direction: SceneSchema.Vec3, snap: Schema.Boolean },
+  Released: {},
+  Hovered: { handle: Schema.NullOr(Handle) },
+});
+export type Message = typeof Message.Type;
+
+export const OutMessage = defineMessageUnion({
+  /** The object's placement now, during a drag. */
+  Moved: { placement: SceneSchema.Placement },
+  /** The drag is over, the object here: a step for history. */
+  Finished: { placement: SceneSchema.Placement },
+});
+export type OutMessage = typeof OutMessage.Type;
+
+/** Pivot controls drawn under `key`, with Drei's defaults or the options given. */
+export const init = (key: string, options: Parameters<typeof pivot>[0] = {}): Model => ({
+  key,
+  pivot: pivot(options),
+  last: Option.none(),
+});
+
+type Return = ReturnWithOutMessage<Model, Message, OutMessage>;
+
+const withPivot = (model: Model, next: Pivot): Model => ({ ...model, pivot: next });
+
+const finished = (model: Model): Return => ({
+  model: { ...withPivot(model, releasePivot(model.pivot)), last: Option.none() },
+  ...Option.match(model.last, {
+    onNone: () => ({}),
+    onSome: (placement) => ({ outMessage: OutMessage.Finished({ placement }) }),
+  }),
+});
+
+const dragged = (model: Model, origin: Vec3, direction: Vec3, snap: boolean): Return => {
+  const placement = Option.fromNullishOr(dragPivot(model.pivot, { origin, direction }, { snap }));
+  return Option.match(placement, {
+    onNone: () => ({ model }),
+    onSome: (placement) => ({
+      model: { ...model, last: Option.some(placement) },
+      outMessage: OutMessage.Moved({ placement }),
+    }),
+  });
+};
+
+export const update = (model: Model, message: Message): Return =>
+  Message.match<Return>(message, {
+    Pressed: ({ handle, point, placement }) => ({
+      model: {
+        ...withPivot(model, pressPivot(model.pivot, placement, handle, point)),
+        last: Option.none(),
+      },
+    }),
+    Dragged: ({ origin, direction, snap }) => dragged(model, origin, direction, snap),
+    Released: () => finished(model),
+    Hovered: ({ handle }) => ({ model: withPivot(model, hoverPivot(model.pivot, handle)) }),
+  });
+
+/** Whether a hit `key` is one of these controls' handles, and which. */
+export const handleOf = (model: Model, key: string): Option.Option<PivotHandle> =>
+  Option.fromNullishOr(pivotHandleOf(model.key, key));
+
+/** Whether a handle is held: the parent leaves the camera alone while it is. */
+export const held = (model: Model): boolean => model.pivot.grab !== null;
+
+/** The handles for `placement`, for the parent's scene. */
+export const nodes = (model: Model, placement: Placement): SceneNode =>
+  pivotNodes(model.key, model.pivot, placement);

package/src/transformGizmo.ts

@@ -0,0 +1,131 @@
+/**
+ * A transform gizmo as a Foldkit submodel (roadmap, "Beyond parity" 5): the core's pure
+ * gizmo (`gizmoNodes`, `pressGizmo`, `dragGizmo`, after three's `TransformControls`)
+ * with Messages for the scene's pointer events and OutMessages for what the parent does
+ * with them. The parent owns where its objects are; the submodel owns only the gizmo:
+ *
+ * - `Pressed` (a press on one of its handles, with the object's placement and the
+ *   camera) takes hold;
+ * - `Dragged` reports `Moved { placement }` for the parent to apply;
+ * - `Released` lets go and reports `Finished { placement }`, the moment to record a step
+ *   of history;
+ * - `Hovered` highlights a handle; `ChoseMode` and `ChoseSpace` switch them.
+ *
+ * `handleOf(model, key)` says whether a hit is on a handle, and `nodes(model, placement,
+ * camera)` draws them, for the parent's scene and view.
+ *
+ * @module
+ */
+import {
+  type Camera,
+  dragGizmo,
+  type Gizmo,
+  gizmo,
+  type GizmoHandle,
+  gizmoHandleOf,
+  gizmoNodes,
+  hoverGizmo,
+  type Placement,
+  pressGizmo,
+  releaseGizmo,
+  SceneSchema,
+  type SceneNode,
+  type Vec3,
+} from '@opsydyn/effect-three';
+import { Option, Schema } from 'effect';
+import { defineMessageUnion } from 'foldkit/message';
+import type { ReturnWithOutMessage } from 'foldkit/update';
+
+export const Model = Schema.Struct({
+  /** The key its handles are drawn under: `${key}:x`, `${key}:xy` and so on. */
+  key: Schema.String,
+  gizmo: SceneSchema.Gizmo,
+  /** The placement the drag last reported, so `Released` can report where it ended. */
+  last: Schema.Option(SceneSchema.Placement),
+});
+export type Model = typeof Model.Type;
+
+const Handle = Schema.Literals(['x', 'y', 'z', 'xy', 'yz', 'xz', 'xyz']);
+
+export const Message = defineMessageUnion({
+  Pressed: {
+    handle: Handle,
+    origin: SceneSchema.Vec3,
+    direction: SceneSchema.Vec3,
+    placement: SceneSchema.Placement,
+    camera: SceneSchema.Camera,
+  },
+  Dragged: { origin: SceneSchema.Vec3, direction: SceneSchema.Vec3 },
+  Released: {},
+  Hovered: { handle: Schema.NullOr(Handle) },
+  ChoseMode: { mode: Schema.Literals(['translate', 'rotate', 'scale']) },
+  ChoseSpace: { space: Schema.Literals(['world', 'local']) },
+});
+export type Message = typeof Message.Type;
+
+export const OutMessage = defineMessageUnion({
+  /** The object's placement now, during a drag. */
+  Moved: { placement: SceneSchema.Placement },
+  /** The drag is over, the object here: a step for history. */
+  Finished: { placement: SceneSchema.Placement },
+});
+export type OutMessage = typeof OutMessage.Type;
+
+/** A gizmo drawn under `key`, with the core's defaults or the options given. */
+export const init = (key: string, options: Parameters<typeof gizmo>[0] = {}): Model => ({
+  key,
+  gizmo: gizmo(options),
+  last: Option.none(),
+});
+
+type Return = ReturnWithOutMessage<Model, Message, OutMessage>;
+
+const withGizmo = (model: Model, next: Gizmo): Model => ({ ...model, gizmo: next });
+
+const finished = (model: Model): Return => ({
+  model: { ...withGizmo(model, releaseGizmo(model.gizmo)), last: Option.none() },
+  ...Option.match(model.last, {
+    onNone: () => ({}),
+    onSome: (placement) => ({ outMessage: OutMessage.Finished({ placement }) }),
+  }),
+});
+
+const dragged = (model: Model, origin: Vec3, direction: Vec3): Return => {
+  const placement = Option.fromNullishOr(dragGizmo(model.gizmo, { origin, direction }));
+  return Option.match(placement, {
+    onNone: () => ({ model }),
+    onSome: (placement) => ({
+      model: { ...model, last: Option.some(placement) },
+      outMessage: OutMessage.Moved({ placement }),
+    }),
+  });
+};
+
+export const update = (model: Model, message: Message): Return =>
+  Message.match<Return>(message, {
+    Pressed: ({ handle, origin, direction, placement, camera }) => ({
+      model: {
+        ...withGizmo(
+          model,
+          pressGizmo(model.gizmo, placement, handle, { origin, direction }, camera),
+        ),
+        last: Option.none(),
+      },
+    }),
+    Dragged: ({ origin, direction }) => dragged(model, origin, direction),
+    Released: () => finished(model),
+    Hovered: ({ handle }) => ({ model: withGizmo(model, hoverGizmo(model.gizmo, handle)) }),
+    ChoseMode: ({ mode }) => ({ model: withGizmo(model, { ...model.gizmo, mode }) }),
+    ChoseSpace: ({ space }) => ({ model: withGizmo(model, { ...model.gizmo, space }) }),
+  });
+
+/** Whether a hit `key` is one of this gizmo's handles, and which. */
+export const handleOf = (model: Model, key: string): Option.Option<GizmoHandle> =>
+  Option.fromNullishOr(gizmoHandleOf(model.key, key));
+
+/** Whether the gizmo is held: the parent leaves the camera alone while it is. */
+export const held = (model: Model): boolean => model.gizmo.grab !== null;
+
+/** The handles for `placement`, seen from `camera`, for the parent's scene. */
+export const nodes = (model: Model, placement: Placement, camera: Camera): SceneNode =>
+  gizmoNodes(model.key, model.gizmo, placement, camera);