@opsydyn/effect-three 0.0.0-stage → 0.1.0

package/src/kernel/xrInput.ts

@@ -0,0 +1,230 @@
+/**
+ * XR input as the scene's events: controllers and hands pointing, selecting, dragging,
+ * pushing sticks and pressing buttons, and (in AR) selecting a real surface.
+ *
+ * Behavioural reference: pmndrs/xr at `0e1acd8`. Its pointers ray-cast along each input
+ * source's target ray every frame (`packages/xr/src/pointer`), entering and leaving what
+ * they point at, capturing the object a select starts on so moving drags it, and turning
+ * select start and end into pointer down, up and click. Its controller locomotion
+ * (`controller-locomotion.ts`) reads the thumbstick each frame; here a stick reports when
+ * it is pushed past halfway in a direction and when it comes back, so a Model can snap
+ * turn and teleport by changing `xr({ origin, heading })`.
+ *
+ * @module
+ */
+import type { Vec3 } from './description.ts';
+import type { Hit, Picker, Ray, SceneEvent } from './pointer.ts';
+
+/** Which hand an input source is held in or is, as WebXR's `handedness`. */
+export type XrHand = 'left' | 'right' | 'none';
+
+/** Where a thumbstick is pushed: `forward` is away from the player. */
+export type XrStickDirection = 'center' | 'left' | 'right' | 'forward' | 'back';
+
+/**
+ * A controller's buttons, by the `xr-standard` gamepad mapping: the trigger, the grip
+ * (`squeeze`), a touchpad, the thumbstick pressed, and the face buttons (A and B on the
+ * right controller, X and Y on the left: `primary` and `secondary`).
+ */
+export type XrButtonName =
+  | 'trigger'
+  | 'squeeze'
+  | 'touchpad'
+  | 'thumbstick'
+  | 'primary'
+  | 'secondary';
+
+/**
+ * A plane the session detected (`xr({ planes: true })`): a floor, wall or table, in the
+ * scene's space. `polygon` is its outline in its own space (on its x–z plane); `label` is
+ * what the device took it for (`floor`, `wall`, `table`…), or `''` when it did not say.
+ * Follow one with `group({ follow: planeSpace(id) })`.
+ */
+export type XrPlane = {
+  readonly id: string;
+  readonly orientation: 'horizontal' | 'vertical';
+  readonly label: string;
+  readonly position: Vec3;
+  readonly rotation: Vec3;
+  readonly polygon: ReadonlyArray<Vec3>;
+};
+
+/**
+ * A mesh the session detected (`xr({ meshes: true })`): furniture, a wall, the room. Its
+ * pose is in the scene's space; its geometry is lent for `xrMesh(id)` rather than sent.
+ */
+export type XrMesh = {
+  readonly id: string;
+  readonly label: string;
+  readonly position: Vec3;
+  readonly rotation: Vec3;
+};
+
+/** Input from an immersive session, each from an input source (`source` tells them apart). */
+export type XrInput =
+  /** A select (the trigger, or a pinch) beginning or ending, along the source's ray. */
+  | { readonly _tag: 'SelectStart' | 'SelectEnd'; readonly source: number; readonly ray: Ray }
+  /** Where the source points this frame. */
+  | { readonly _tag: 'Aim'; readonly source: number; readonly ray: Ray }
+  /** The source went away (put down, or the session ended). */
+  | { readonly _tag: 'Lost'; readonly source: number }
+  | {
+      readonly _tag: 'Stick';
+      readonly source: number;
+      readonly hand: XrHand;
+      readonly direction: XrStickDirection;
+    }
+  | {
+      readonly _tag: 'Button';
+      readonly source: number;
+      readonly hand: XrHand;
+      readonly button: XrButtonName;
+      readonly pressed: boolean;
+    }
+  /** Gliding (`xr({ glide })`) stopped: where the player stands now, for the Model. */
+  | { readonly _tag: 'Moved'; readonly origin: Vec3; readonly heading: number }
+  /** The detected planes changed: all of them, as they are now. */
+  | { readonly _tag: 'Planes'; readonly planes: ReadonlyArray<XrPlane> }
+  /** The detected meshes changed: all of them, as they are now. */
+  | { readonly _tag: 'Meshes'; readonly meshes: ReadonlyArray<XrMesh> }
+  /** In AR, a select whose ray met a real surface: where, and the surface's normal. */
+  | {
+      readonly _tag: 'Surface';
+      readonly source: number;
+      readonly hand: XrHand;
+      readonly point: Vec3;
+      readonly normal: Vec3;
+    };
+
+/** One source's state: what it points at, the select it holds, and its last ray. */
+type Source = {
+  hovered: string | undefined;
+  /** The key a held select started on (`undefined` for nothing) and its ray, while held. */
+  pressed: { readonly key: string | undefined; readonly ray: Ray } | undefined;
+  dragged: boolean;
+  ray: Ray | undefined;
+};
+
+const none: ReadonlyArray<SceneEvent> = [];
+
+/**
+ * How far a held source must move before it drags, as the mouse must travel a few pixels:
+ * its ray turned by a degree, or moved a centimetre. Hands and controllers never hold
+ * perfectly still, and a select that does not move is a click.
+ */
+const dragStart = { turn: Math.cos((1 * Math.PI) / 180), shift: 0.01 } as const;
+
+const moved = (from: Ray, to: Ray): boolean => {
+  const [a, b, c] = from.direction;
+  const [x, y, z] = to.direction;
+  const [p, q, r] = from.origin;
+  const [u, v, w] = to.origin;
+  return (
+    a * x + b * y + c * z < dragStart.turn || Math.hypot(u - p, v - q, w - r) > dragStart.shift
+  );
+};
+
+/** Creates the tracker turning one session's XR input into scene events. */
+export const createXrTracker = (picker: Picker) => {
+  const sources = new Map<number, Source>();
+
+  const sourceOf = (id: number): Source => {
+    const known = sources.get(id);
+    if (known !== undefined) return known;
+    const created: Source = {
+      hovered: undefined,
+      pressed: undefined,
+      dragged: false,
+      ray: undefined,
+    };
+    sources.set(id, created);
+    return created;
+  };
+
+  /** Leaves and enters as what the source points at changes. */
+  const hover = (source: Source, hit: Hit | undefined, events: Array<SceneEvent>): void => {
+    const next = hit?.key;
+    if (next === source.hovered) return;
+    if (source.hovered !== undefined) events.push({ _tag: 'PointerLeave', key: source.hovered });
+    if (hit !== undefined) events.push({ _tag: 'PointerEnter', ...hit });
+    source.hovered = next;
+  };
+
+  const aim = (source: Source, ray: Ray): ReadonlyArray<SceneEvent> => {
+    source.ray = ray;
+    const events: Array<SceneEvent> = [];
+    const pressed = source.pressed;
+    // A select held on a mesh captures it: moving drags it, wherever the ray now points.
+    if (pressed?.key !== undefined && (source.dragged || moved(pressed.ray, ray))) {
+      source.dragged = true;
+      events.push({ _tag: 'Drag', key: pressed.key, button: 0, ray });
+    }
+    hover(source, picker.pickRay(ray), events);
+    return events;
+  };
+
+  const selectStart = (source: Source, ray: Ray): ReadonlyArray<SceneEvent> => {
+    const hit = picker.pickRay(ray);
+    source.pressed = { key: hit?.key, ray };
+    source.dragged = false;
+    return hit === undefined ? none : [{ _tag: 'PointerDown', button: 0, ...hit }];
+  };
+
+  const selectEnd = (source: Source, ray: Ray): ReadonlyArray<SceneEvent> => {
+    const from = source.pressed?.key;
+    const dragged = source.dragged;
+    source.pressed = undefined;
+    source.dragged = false;
+    const events: Array<SceneEvent> = [];
+    if (from !== undefined && dragged) events.push({ _tag: 'DragEnd', key: from, button: 0, ray });
+    const hit = picker.pickRay(ray);
+    if (hit === undefined) {
+      if (from === undefined) events.push({ _tag: 'PointerMissed', button: 0 });
+      return events;
+    }
+    events.push({ _tag: 'PointerUp', button: 0, ...hit });
+    if (from === hit.key) events.push({ _tag: 'Click', button: 0, ...hit });
+    return events;
+  };
+
+  /** A source gone: it leaves what it pointed at, and a drag ends where it last aimed. */
+  const lost = (id: number): ReadonlyArray<SceneEvent> => {
+    const source = sources.get(id);
+    sources.delete(id);
+    if (source === undefined) return none;
+    const events: Array<SceneEvent> = [];
+    const held = source.pressed?.key;
+    if (held !== undefined && source.dragged && source.ray !== undefined) {
+      events.push({ _tag: 'DragEnd', key: held, button: 0, ray: source.ray });
+    }
+    if (source.hovered !== undefined) events.push({ _tag: 'PointerLeave', key: source.hovered });
+    return events;
+  };
+
+  return (input: XrInput): ReadonlyArray<SceneEvent> => {
+    switch (input._tag) {
+      case 'Aim':
+        return aim(sourceOf(input.source), input.ray);
+      case 'SelectStart':
+        return selectStart(sourceOf(input.source), input.ray);
+      case 'SelectEnd':
+        return selectEnd(sourceOf(input.source), input.ray);
+      case 'Lost':
+        return lost(input.source);
+      case 'Stick':
+        return [{ _tag: 'XrStick', hand: input.hand, direction: input.direction }];
+      case 'Button':
+        return [
+          { _tag: 'XrButton', hand: input.hand, button: input.button, pressed: input.pressed },
+        ];
+      case 'Moved':
+        return [{ _tag: 'XrMoved', origin: input.origin, heading: input.heading }];
+      case 'Planes':
+        return [{ _tag: 'XrPlanes', planes: input.planes }];
+      case 'Meshes':
+        return [{ _tag: 'XrMeshes', meshes: input.meshes }];
+      case 'Surface':
+        return [{ _tag: 'XrSurface', hand: input.hand, point: input.point, normal: input.normal }];
+    }
+  };
+};

package/src/kernel/xrLocomotion.ts

@@ -0,0 +1,72 @@
+/**
+ * Moving the player in an immersive session, as functions from the scene's `xr` settings
+ * to new ones: the Model keeps where the player stands, and the session follows it.
+ *
+ * Behavioural reference: pmndrs/xr at `0e1acd8`, `controller-locomotion.ts`: the right
+ * thumbstick snap-turns 45° once pushed past halfway (and must come back before turning
+ * again), and the left one moves the player along where they face. Here moving is a step
+ * per push, not a glide: sticks arrive as `XrStick` events when pushed and let back.
+ * `teleport` is `@react-three/xr`'s `TeleportTarget`: the player stands where they point.
+ *
+ * @module
+ */
+import type { Vec3, Xr } from './description.ts';
+import type { XrHand, XrStickDirection } from './xrInput.ts';
+
+export type LocomotionOptions = {
+  /** Degrees a snap turn turns by. Default 45, as pmndrs/xr's. */
+  readonly snapDegrees?: number;
+  /** Metres a step moves. Default 1. */
+  readonly step?: number;
+  /** The hand whose stick turns; the other moves. Default `right`, as pmndrs/xr's. */
+  readonly turnHand?: Exclude<XrHand, 'none'>;
+};
+
+/** A step `forward` (`-1` back) and `right` (`-1` left) of the player facing `heading`. */
+const stepped = (settings: Xr, forward: number, right: number): Vec3 => {
+  const [x, y, z] = settings.origin;
+  const sin = Math.sin(settings.heading);
+  const cos = Math.cos(settings.heading);
+  // Facing `heading` about +y from −z: forward is (−sin, −cos), right is (cos, −sin).
+  return [x - forward * sin + right * cos, y, z - forward * cos - right * sin];
+};
+
+/**
+ * The settings after a stick is pushed: the turning hand's left and right snap-turn, the
+ * other hand's stick steps forward, back, left or right. Centring changes nothing.
+ */
+export const locomote = (
+  settings: Xr,
+  stick: { readonly hand: XrHand; readonly direction: XrStickDirection },
+  options: LocomotionOptions = {},
+): Xr => {
+  const turnHand = options.turnHand ?? 'right';
+  const step = options.step ?? 1;
+  const snap = ((options.snapDegrees ?? 45) * Math.PI) / 180;
+  if (stick.hand === turnHand) {
+    if (stick.direction === 'left') return { ...settings, heading: settings.heading + snap };
+    if (stick.direction === 'right') return { ...settings, heading: settings.heading - snap };
+    return settings;
+  }
+  const moves: Readonly<Record<XrStickDirection, readonly [number, number] | undefined>> = {
+    center: undefined,
+    forward: [step, 0],
+    back: [-step, 0],
+    left: [0, -step],
+    right: [0, step],
+  };
+  const move = moves[stick.direction];
+  return move === undefined ? settings : { ...settings, origin: stepped(settings, ...move) };
+};
+
+/** The settings with the player standing at `point` (on the floor there), facing as before. */
+export const teleport = (settings: Xr, point: Vec3): Xr => ({
+  ...settings,
+  origin: [point[0], settings.origin[1], point[2]],
+});
+
+/** The settings where gliding left the player (an `XrMoved` event): its origin and heading. */
+export const glided = (
+  settings: Xr,
+  moved: { readonly origin: Vec3; readonly heading: number },
+): Xr => ({ ...settings, origin: moved.origin, heading: moved.heading });

package/src/runtime/FrameSource.ts

@@ -0,0 +1,41 @@
+/**
+ * Where frames come from. Wraps a kernel `FrameScheduler` so a scene's per-frame callback
+ * is registered for exactly the lifetime of its scope.
+ *
+ * @module
+ */
+import { Context, Effect, Layer } from 'effect';
+
+import { createGatedFrames, type FrameControl, type FrameScheduler } from '../kernel/index.ts';
+
+const registration = (scheduler: FrameScheduler, onFrame: () => void) => () => {
+  const gate = createGatedFrames(scheduler);
+  const unsubscribe = gate.subscribe(onFrame);
+  const control: FrameControl = {
+    wake: () => gate.setOpen(true),
+    sleep: () => gate.setOpen(false),
+  };
+  return { control, unsubscribe };
+};
+
+/** The frame source service for `scheduler`, for providing directly with `provideService`. */
+export const fromScheduler = (scheduler: FrameScheduler) => ({
+  /**
+   * Calls `onFrame` once per frame until the current scope closes, while awake. Returns
+   * the control that puts the subscription to sleep and wakes it.
+   */
+  subscribe: (onFrame: () => void) => {
+    const register = Effect.sync(registration(scheduler, onFrame));
+    return Effect.acquireRelease(register, (registered) =>
+      Effect.sync(registered.unsubscribe),
+    ).pipe(Effect.map((registered) => registered.control));
+  },
+});
+
+export class FrameSource extends Context.Service<FrameSource, ReturnType<typeof fromScheduler>>()(
+  'effect-three/FrameSource',
+) {}
+
+/** Provides a frame source backed by `scheduler`. */
+export const layer = (scheduler: FrameScheduler) =>
+  Layer.succeed(FrameSource, fromScheduler(scheduler));

package/src/runtime/ResourceRegistry.ts

@@ -0,0 +1,24 @@
+/**
+ * App-level owner of shared GPU resources (ADR-005). Every scene runtime built with the
+ * same Layer shares one kernel resource store; the store is disposed when the Layer's
+ * scope closes.
+ *
+ * @module
+ */
+import { Context, Effect, Layer } from 'effect';
+
+import { createResourceStore, type ResourceStore } from '../kernel/index.ts';
+
+export class ResourceRegistry extends Context.Service<
+  ResourceRegistry,
+  { readonly store: ResourceStore }
+>()('effect-three/ResourceRegistry') {}
+
+const acquireStore = Effect.sync(createResourceStore);
+
+const toService = (store: ResourceStore) => ({ store });
+
+const scopedStore = Effect.acquireRelease(acquireStore, (store) => Effect.sync(store.dispose));
+
+/** Provides one shared resource store for the lifetime of the Layer. */
+export const layer = Layer.effect(ResourceRegistry, scopedStore.pipe(Effect.map(toService)));

package/src/runtime/SceneRuntime.ts

@@ -0,0 +1,229 @@
+/**
+ * A running scene: a kernel scene graph, a renderer and a frame subscription, all owned
+ * by the caller's `Scope`. Closing the scope stops the frame loop, then releases the
+ * event queue, the renderer and every resource the scene acquired, in that order.
+ *
+ * @module
+ */
+import { Clock, Effect, Exit, Match, Option, Queue, Result, Scope, Stream } from 'effect';
+
+import {
+  createSceneClock,
+  createSceneGraph,
+  type Behaviour,
+  createFramePacer,
+  createSceneLoop,
+  type Op,
+  type OverlayPlacement,
+  type LabelEngine,
+  type PhysicsEngine,
+  type ReconcileResult,
+  type RendererFactory,
+  type SceneDescription,
+  type SceneEvent,
+  type SceneClock,
+  type SceneGraph,
+  type SceneRenderer,
+  type Viewport,
+} from '../kernel/index.ts';
+import { InvalidScene, RendererUnavailable } from './errors.ts';
+import { FrameSource } from './FrameSource.ts';
+import { ResourceRegistry } from './ResourceRegistry.ts';
+
+export type SceneRuntimeOptions = {
+  readonly scene: SceneDescription;
+  readonly renderer: RendererFactory;
+  readonly viewport: Viewport;
+  /** Events kept when the consumer falls behind; older events are dropped. Default 64. */
+  readonly eventCapacity?: number;
+  /** Behaviours nodes may name, beside the built-in ones. */
+  readonly behaviours?: Readonly<Record<string, Behaviour>>;
+  /** The physics engine for meshes with a `body`; without one, bodies stay put. */
+  readonly physics?: PhysicsEngine | undefined;
+  /** Draws `label` nodes (distance-field text); without one, labels are empty. */
+  readonly labels?: LabelEngine | undefined;
+  /** Receives where the overlays are after each drawn frame, to move their HTML there. */
+  readonly placeOverlays?: (placements: ReadonlyArray<OverlayPlacement>) => void;
+};
+
+const defaultEventCapacity = 64;
+const noBehaviours: Readonly<Record<string, Behaviour>> = {};
+const ignorePlacements = (_placements: ReadonlyArray<OverlayPlacement>): void => undefined;
+const nanosPerMillisecond = 1_000_000;
+const nanosPerSecond = 1_000_000_000;
+
+const toResult = (result: ReconcileResult): Result.Result<ReadonlyArray<Op>, InvalidScene> =>
+  Match.valueTags(result, {
+    Applied: (applied) => Result.succeed(applied.ops),
+    Invalid: ({ error }) => Result.fail(new InvalidScene({ error })),
+  });
+
+const applyViewport = (graph: SceneGraph, renderer: SceneRenderer, viewport: Viewport): void => {
+  graph.resize(viewport.width, viewport.height);
+  renderer.setViewport(viewport);
+};
+
+/** The engines a scene graph hands work to, and the renderer whose kit shades it. */
+type Engines = Pick<SceneRuntimeOptions, 'physics' | 'labels' | 'renderer'>;
+
+const sceneGraph =
+  (
+    registry: ResourceRegistry['Service'],
+    behaviours: Readonly<Record<string, Behaviour>>,
+    engines: Engines,
+  ) =>
+  () =>
+    createSceneGraph({
+      store: registry.store,
+      behaviours,
+      physics: engines.physics,
+      labels: engines.labels,
+      kit: engines.renderer.kit,
+    });
+
+/**
+ * Reconciles at the current scene time. An idle scene draws no frames, so its last tick
+ * can be long past; catching up first makes new transitions start now, not back then.
+ */
+const reconcileNow = (graph: SceneGraph, sceneClock: SceneClock, scene: SceneDescription) => {
+  graph.tick(sceneClock.elapsedSeconds());
+  return graph.reconcile(scene);
+};
+
+const viewportChange = (graph: SceneGraph, renderer: SceneRenderer, viewport: Viewport) => () =>
+  applyViewport(graph, renderer, viewport);
+
+const animationChange = (sceneClock: SceneClock, graph: SceneGraph, animating: boolean) => () => {
+  sceneClock.setAnimating(animating);
+  graph.setAnimating(animating);
+};
+
+const acquireGraph = (
+  registry: ResourceRegistry['Service'],
+  behaviours: Readonly<Record<string, Behaviour>>,
+  engines: Engines,
+) => {
+  const create = Effect.sync(sceneGraph(registry, behaviours, engines));
+  return Effect.acquireRelease(create, (graph) => Effect.sync(graph.dispose));
+};
+
+const acquireRenderer = (factory: RendererFactory) => {
+  const create = Effect.try({
+    try: factory.create,
+    catch: (cause) => new RendererUnavailable({ cause }),
+  });
+  return Effect.acquireRelease(create, (renderer) => Effect.sync(renderer.dispose));
+};
+
+/** Waits for a renderer that starts asynchronously (WebGPU); a failed start is unavailable. */
+const awaitReady = (renderer: SceneRenderer) =>
+  Option.match(Option.fromNullishOr(renderer.ready), {
+    onNone: () => Effect.void,
+    onSome: (ready) =>
+      Effect.tryPromise({ try: ready, catch: (cause) => new RendererUnavailable({ cause }) }),
+  });
+
+const invalidationListening = (graph: SceneGraph, onInvalidated: () => void) => () =>
+  graph.onInvalidated(onInvalidated);
+
+const acquireInvalidation = (graph: SceneGraph, onInvalidated: () => void) => {
+  const listen = Effect.sync(invalidationListening(graph, onInvalidated));
+  return Effect.acquireRelease(listen, Effect.sync);
+};
+
+const acquireEvents = (capacity: number) => {
+  const create = Queue.sliding<SceneEvent>(capacity);
+  return Effect.acquireRelease(create, Queue.shutdown);
+};
+
+function* startScene(options: SceneRuntimeOptions) {
+  const registry = yield* ResourceRegistry;
+  const frames = yield* FrameSource;
+  const clock = yield* Clock.Clock;
+
+  const graph = yield* acquireGraph(registry, options.behaviours ?? noBehaviours, options);
+  const startupOps = yield* Effect.fromResult(toResult(graph.reconcile(options.scene)));
+  const renderer = yield* acquireRenderer(options.renderer);
+  yield* awaitReady(renderer);
+  applyViewport(graph, renderer, options.viewport);
+  const events = yield* acquireEvents(options.eventCapacity ?? defaultEventCapacity);
+
+  const sceneClock = createSceneClock(
+    () => Number(clock.monotonicTimeNanosUnsafe()) / nanosPerSecond,
+  );
+  const loop = createSceneLoop({
+    graph,
+    renderer,
+    elapsedSeconds: sceneClock.elapsedSeconds,
+    emit: (event) => {
+      Queue.offerUnsafe(events, event);
+    },
+    now: () => Number(clock.monotonicTimeNanosUnsafe()) / nanosPerMillisecond,
+    placeOverlays: options.placeOverlays ?? ignorePlacements,
+  });
+  yield* Effect.addFinalizer(() => Effect.sync(loop.dispose));
+  const pacer = createFramePacer(loop);
+  pacer.attach(yield* frames.subscribe(pacer.frame));
+  yield* acquireInvalidation(graph, pacer.wake);
+
+  return {
+    /** The hosted scene graph, for inspection. */
+    graph,
+    /** The operations that built the initial scene. */
+    startupOps,
+    /**
+     * Applies a new description and returns the operations it took. Structurally equal
+     * descriptions return no operations and cost no host changes.
+     */
+    update: (scene: SceneDescription) =>
+      Effect.suspend(() => Effect.fromResult(toResult(reconcileNow(graph, sceneClock, scene)))),
+    /** Resizes the camera aspect and the renderer's drawing surface. */
+    resize: (viewport: Viewport) => Effect.sync(viewportChange(graph, renderer, viewport)),
+    /** Freezes (`false`) or resumes (`true`) behaviours; frozen, transitions land at once. */
+    setAnimating: (animating: boolean) =>
+      Effect.sync(animationChange(sceneClock, graph, animating)),
+    /**
+     * Draws one frame now, whatever the frame mode: React Three Fiber's `advance`, for
+     * `frames: 'never'` scenes and frame-exact capture.
+     */
+    advance: Effect.sync(pacer.advance),
+    /**
+     * Draws one frame now, synchronously, for a host's own frame source to call directly:
+     * an immersive (WebXR) session's animation loop.
+     */
+    drawNow: pacer.advance,
+    /** Routes pointer input. Synchronous, so DOM listeners can call it directly. */
+    pointer: loop.pointer,
+    /** Routes XR input: aims, selects, sticks, buttons and surfaces. Synchronous, as `pointer`. */
+    xrInput: loop.xrInput,
+    /** Scene events, newest kept when the consumer falls behind. */
+    events: Stream.fromQueue(events),
+    /** Removes and returns every pending event without waiting. */
+    drainEvents: Queue.clear(events),
+  };
+}
+
+// Startup is atomic: everything is acquired into a child of the caller's scope, which is
+// closed immediately if startup fails or is interrupted. Otherwise a partial scene would
+// stay allocated until the caller's scope closed (under Foldkit: until unmount).
+function* startAtomically(options: SceneRuntimeOptions) {
+  const parent = yield* Effect.scope;
+  const child = yield* Scope.fork(parent);
+  return yield* Effect.gen(() => startScene(options)).pipe(
+    Scope.provide(child),
+    Effect.onError((cause) => Scope.close(child, Exit.failCause(cause))),
+  );
+}
+
+/**
+ * Starts a scene in the current scope. Fails with `InvalidScene` if the initial
+ * description is rejected and `RendererUnavailable` if the renderer can't be created.
+ * A failed or interrupted start releases everything it acquired before returning.
+ */
+export const make = (options: SceneRuntimeOptions) => {
+  const program = Effect.gen(() => startAtomically(options));
+  return program.pipe(Effect.withSpan('effect-three/SceneRuntime.make'));
+};
+
+/** The handle `make` returns. */
+export type SceneHandle = Effect.Success<ReturnType<typeof make>>;