@volter/editor-blender 0.1.151 → 0.1.153

package/src/model-play-extension.ts

@@ -1,173 +0,0 @@
-/**
- * THE MODEL DOCUMENT'S PLAY, which editor-blender owns and offers in its API (`registerModelPlay`,
- * `docs/adr/plugin-apis.md`). A Play tool owns its controls, state and runner; the model document
- * lends that runner its detached stage. play registers its tool from its own `activate`, through
- * the API; the host hears only whether a document plays (`@volter/sdk/document-play-extension`).
- */
-import { setDocumentPlaySignal } from '@volter/sdk/document-play-extension';
-import type { ComponentType } from 'react';
-
-export interface DocumentPlayControlProps {
-  readonly documentId: string | undefined;
-  readonly onClose: () => void;
-}
-/** Where the document's own area stands while its game runs (`DocumentPlayStage.edit`): a box is in fractions of the
- *  stage. */
-export type DocumentPlayEditArea = 'live' | 'hidden' | { readonly left: number; readonly top: number; readonly width: number; readonly height: number };
-export interface DocumentPlayStage {
-  readonly documentId: string;
-  readonly sourcePath: string;
-  readonly report: (title: string, detail: string) => void;
-  /** Where the tool draws its game, over the document's own area. */
-  readonly container: HTMLElement;
-  /** The game's first frame stands. */
-  readonly ready: () => void;
-  /** THE DOCUMENT'S OWN AREA WHILE THE GAME RUNS ON: `live` brings the editing area back in front, live for editing
-   *  (its keys the editor's); a box shows it drawing in that part of the stage, taking no press (a tile among the
-   *  game's views); `hidden` puts the game in front again. */
-  readonly edit?: (area: DocumentPlayEditArea) => void;
-  /** A layer over the editing area and the play area alike, for the tool's view controls, which stand whichever area
-   *  is in front; it takes no press itself. */
-  readonly overlay?: HTMLElement;
-}
-
-/**
- * A RUNNING GAME'S CLOCK, as the Play tool keeps it: the game's own seconds and frames, which stand still while paused
- * and run at `speed` times the page's own clock otherwise.
- */
-export interface DocumentPlayClock {
-  /** The game's seconds since this run began. */
-  readonly time: number;
-  /** The frames the game has run since this run began. */
-  readonly tick: number;
-  readonly paused: boolean;
-  /** Simulation seconds per real second; one of the transport's `speeds`. */
-  readonly speed: number;
-  /** While playing with no game running because the game failed to start or threw: why. The
-   *  run stays playing (a save of the game retries it); a running game clears it. */
-  readonly failure?: string | null;
-  /** A game has started in this run and is running (its first update ran). False while the run
-   *  is still preparing, and while it plays with a `failure`. A reader that must know whether Play
-   *  WORKED (the CLI's `play`) waits for this or for `failure`, never for "playing" alone. */
-  readonly running: boolean;
-}
-/**
- * THE GAME'S TRANSPORT — what a Play tool offers beyond Play and Stop, for a layout that draws a
- * game panel (Cyclotron's Game mode, `@volter/editor-blender`). Optional: a tool without
- * one still plays and stops, and a layout draws only the controls a tool answers.
- */
-export interface DocumentPlayTransport {
-  /** The speeds `setSpeed` accepts, slowest first. */
-  readonly speeds: readonly number[];
-  clock(documentId: string): DocumentPlayClock;
-  /** The clock moves every played frame, so it has a subscription of its own: `subscribe` would
-   *  re-render everything that only asks whether a document plays. */
-  subscribeClock(listener: () => void): () => void;
-  /** Hold or release the game; the answer settles once the game has. */
-  setPaused(documentId: string, paused: boolean): void | Promise<void>;
-  /** `frames` frames (one when absent), pausing the game first. */
-  step(documentId: string, frames?: number): void | Promise<void>;
-  setSpeed(documentId: string, speed: number): void | Promise<void>;
-  /** Begin the run again on a FRESH detached copy, the clock at zero. */
-  restart(documentId: string): void;
-  /** Changes on every restart. The document that lends the stage keys its detached copy on it,
-   *  so a new generation is a new copy; the change is announced through `subscribe`. */
-  generation(documentId: string): number;
-  /** Whether the running game's own bot drives the player in view, and the goals it offers; a change is announced
-   *  through `subscribeClock`. Absent, the tool has no autoplay. */
-  autoplay?(documentId: string): DocumentPlayAutoplay;
-  /** Switch the bot on (it must be offered, and the game playing) or off. On plays `goal` (the game's own when
-   *  absent); the answer settles once the goal has started. */
-  setAutoplay?(documentId: string, on: boolean, by: 'panel' | 'cli', goal?: string): void | Promise<void>;
-  /** While stopped, ask the next start to switch the bot on with `goal` as soon as its player joins. Absent, autoplay
-   *  can only be switched while running. */
-  armAutoplay?(documentId: string, armed: boolean, goal?: string): void;
-}
-/**
- * AUTOPLAY, AS THE EDITOR OWNS IT: a game offers a bot and its goals, the editor decides whether it drives the player
- * in view. A person's own press in the game takes it back (`takeover`).
- */
-export interface DocumentPlayAutoplay {
-  readonly on: boolean;
-  /** The bot can be switched on for the player in view. */
-  readonly available: boolean;
-  /** Why the bot cannot be switched on now, in the tool's words (no goals, a view with no player, a player not yet
-   *  joined): the Game panel and `play state` say it. */
-  readonly unavailable?: string | null;
-  /** Who made the last change. */
-  readonly by: 'panel' | 'cli' | 'takeover' | null;
-  /** Armed while stopped (`armAutoplay`): the next start turns it on once its player joins. */
-  readonly armed?: boolean;
-  /** The goals the game's bot offers, and the one driving, armed, or the game's own. */
-  readonly behaviors?: readonly string[];
-  readonly behavior?: string | null;
-  /** A goal played where the person is not looking (a std game's headless play), and how it stands: `<goal>:
-   *  playing`, `<goal>: achieved` or `<goal>: failed — why`; null before any. */
-  readonly state?: string | null;
-}
-export interface DocumentPlayExtension {
-  readonly Control: ComponentType<DocumentPlayControlProps>;
-  readonly Menu: ComponentType<DocumentPlayControlProps>;
-  /** The run's panel, which a document's layout shows in its bottom area while it plays, when the tool has one. */
-  readonly Panel?: ComponentType;
-  playing(documentId: string): boolean;
-  /** Intended live frame shape; absent/null lets the document fill its area. */
-  aspectRatio?(documentId: string): number | null;
-  setPlaying(documentId: string, value: boolean): void;
-  escape?(documentId: string): void;
-  subscribe(listener: () => void): () => void;
-  run(stage: DocumentPlayStage): () => void;
-  /** Pause, step, speed, restart and the clock, when the tool keeps them. */
-  readonly transport?: DocumentPlayTransport;
-  /** What this tool runs to play a document's source file (a game's dev server command). */
-  scriptPath?(sourcePath: string): string;
-  /** Whether the document's source has a game to play: `null` while the tool has not looked yet. A change is announced
-   *  through `subscribe`. A layout uses it to open a document as a game or as a model. */
-  hasScript?(sourcePath: string): boolean | null;
-}
-
-let registered: DocumentPlayExtension | null = null;
-const listeners = new Set<() => void>();
-function publish(): void { for (const listener of listeners) listener(); }
-
-/** The registered Play tool, or `null` while none is. */
-export function modelPlayExtension(): DocumentPlayExtension | null {
-  return registered;
-}
-/** A registration, and every change the registered tool announces. */
-export function subscribeModelPlayExtension(listener: () => void): () => void {
-  listeners.add(listener);
-  return () => { listeners.delete(listener); };
-}
-
-/** Whether a document's Play runs and is paused, for the host. A pause is a clock change, and the
- *  clock moves every played frame, so its subscribers are readers whose snapshot changes rarely. */
-function signal(extension: DocumentPlayExtension) {
-  return {
-    state(documentId: string): 'playing' | 'paused' | 'stopped' {
-      if (!extension.playing(documentId)) return 'stopped';
-      return extension.transport?.clock(documentId).paused ? 'paused' : 'playing';
-    },
-    subscribe(listener: () => void): () => void {
-      const stopPlay = extension.subscribe(listener);
-      const stopClock = extension.transport?.subscribeClock(listener);
-      return () => { stopPlay(); stopClock?.(); };
-    },
-  };
-}
-
-/** The API's `registerModelPlay`: one Play tool for model documents at a time. */
-export function registerModelPlay(extension: DocumentPlayExtension): () => void {
-  if (registered) throw new Error('A Play tool already plays model documents.');
-  registered = extension;
-  const stop = extension.subscribe(publish);
-  setDocumentPlaySignal('model', signal(extension));
-  publish();
-  return () => {
-    stop();
-    if (registered !== extension) return;
-    registered = null;
-    setDocumentPlaySignal('model', null);
-    publish();
-  };
-}