@volter/editor-sdk 0.5.57

package/src/tools/registry.ts

@@ -0,0 +1,341 @@
+import type { z } from 'zod';
+import {
+  CORE_ERROR_CODES,
+  isOperationError,
+  type StructuredOperationError,
+  toStructuredIssues,
+} from './errors.js';
+import {
+  type ExecutionHost,
+  type ExecutionRequirements,
+  type PermissionMetadata,
+  TOOL_NAMESPACES,
+  type ToolContext,
+  type ToolNamespace,
+} from './types.js';
+
+/** One declared, machine-readable failure mode of an operation (§8 B1: "structured error codes and data schemas"). */
+export interface ToolErrorDefinition<TCode extends string = string> {
+  code: TCode;
+  /** One-line human summary of when this code fires — for docs/help text, never parsed by callers. */
+  summary: string;
+  /** Optional schema for this code's `data` payload. When present, `dispatch()` validates a thrown ToolError's data against it. */
+  data?: z.ZodType;
+}
+
+/**
+ * One operation, fully self-describing: identity, both schemas, every
+ * declared failure mode, where/how it runs, and its own implementation.
+ * Built via `defineTool` (below), which validates the name shape and
+ * error-code uniqueness at definition time.
+ */
+export interface ToolDefinition<
+  TInput extends z.ZodType = z.ZodType,
+  TResult extends z.ZodType = z.ZodType,
+  TErrorCode extends string = string,
+> {
+  /** Fully qualified dotted name, e.g. "project.scene.read" (§5.7 namespaces). */
+  name: string;
+  /** Short, one-line summary (for CLI help / listOperations tables). */
+  summary: string;
+  /** Longer prose description of behavior, side effects, and caveats. */
+  description: string;
+  /** Zod schema every `dispatch()` input is validated against before `impl` runs. */
+  input: TInput;
+  /** Zod schema every `impl` return value is validated against before `dispatch()` succeeds. */
+  result: TResult;
+  /** Every structured failure mode this operation may raise via `ToolError`. */
+  errors: ReadonlyArray<ToolErrorDefinition<TErrorCode>>;
+  /** Which live contexts this operation needs (project/editor/play/render). */
+  requires: ExecutionRequirements;
+  /** Which of the three hosts this operation executes on (node / editor-browser / runtime-page). */
+  host: ExecutionHost;
+  /** True if this operation writes/changes state (files, editor, runtime). */
+  mutates: boolean;
+  /** True if this operation supports a dry-run mode (mutations only, meaningful subset). */
+  supportsDryRun: boolean;
+  /** True for jobs that must not ride a short request/response timeout (e.g. `cinematic.render` on the editor relay). */
+  longRunning?: boolean;
+  /** Coarse permission/risk metadata for gated callers (agents, HTTP/MCP auth). */
+  permission: PermissionMetadata;
+  /** The actual implementation. Receives already-schema-validated input. */
+  impl: (input: z.infer<TInput>, ctx: ToolContext) => Promise<z.infer<TResult>>;
+}
+
+/** `listOperations()`'s element shape — every field of `ToolDefinition` except `impl`, so enumerating never risks invoking anything. */
+export type ToolSummary<
+  TInput extends z.ZodType = z.ZodType,
+  TResult extends z.ZodType = z.ZodType,
+  TErrorCode extends string = string,
+> = Omit<ToolDefinition<TInput, TResult, TErrorCode>, 'impl'>;
+
+const NAME_PATTERN = /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$/;
+
+function namespaceOf(name: string): string {
+  const dot = name.indexOf('.');
+  return dot === -1 ? name : name.slice(0, dot);
+}
+
+/**
+ * Typed helper that builds an `ToolDefinition`. Pure and synchronous —
+ * it does not touch a registry (so it can never itself throw "duplicate
+ * name"; that check happens at `ToolRegistry.register`, which has the
+ * cross-operation state to detect it) — but it DOES validate the two things
+ * that are decidable from the definition alone: the name is a valid dotted
+ * `namespace.rest` string under one of the four operation namespaces
+ * (§5.7), and no two declared error codes on the same operation collide.
+ *
+ * Exists mainly for type inference: it pins `impl`'s parameter/return types
+ * to `z.infer<TInput>` / `z.infer<TResult>` so a mismatched implementation
+ * fails to compile rather than failing at runtime.
+ */
+export function defineTool<
+  TInput extends z.ZodType,
+  TResult extends z.ZodType,
+  TErrorCode extends string = string,
+>(def: ToolDefinition<TInput, TResult, TErrorCode>): ToolDefinition<TInput, TResult, TErrorCode> {
+  if (!NAME_PATTERN.test(def.name)) {
+    throw new Error(
+      `defineTool: "${def.name}" is not a valid dotted operation name ` +
+        '(expected e.g. "project.scene.read" — lowercase-leading segments joined by dots).',
+    );
+  }
+  const ns = namespaceOf(def.name);
+  if (!(TOOL_NAMESPACES as readonly string[]).includes(ns)) {
+    throw new Error(
+      `defineTool: "${def.name}" has unknown namespace "${ns}" — expected one of ` +
+        `${TOOL_NAMESPACES.join(', ')} (§5.7).`,
+    );
+  }
+  const seen = new Set<string>();
+  for (const err of def.errors) {
+    if (seen.has(err.code)) {
+      throw new Error(`defineTool: "${def.name}" declares duplicate error code "${err.code}".`);
+    }
+    seen.add(err.code);
+  }
+  return def;
+}
+
+/** `dispatch()`'s result — a discriminated union, never a thrown exception, so every projection (CLI/HTTP/MCP) gets one uniform JSON-able shape for both success and failure. */
+export type ToolOutcome<TResult = unknown> =
+  | { ok: true; data: TResult }
+  | { ok: false; error: StructuredOperationError };
+
+/**
+ * Normalize whatever an `impl` threw into a `StructuredOperationError`.
+ * Three cases:
+ *  1. A declared `ToolError` whose code IS in `def.errors` and whose
+ *     `data` (if the code declares a schema) validates — forwarded as-is,
+ *     `data` replaced by its *parsed* form.
+ *  2. A declared code whose `data` fails its own schema — that is itself an
+ *     implementation bug, surfaced as INVALID_OUTPUT (never silently
+ *     forwarding unvalidated data).
+ *  3. Anything else — an `ToolError` with an undeclared code, a plain
+ *     `Error`, or a non-Error throw — normalized into INTERNAL_ERROR. The
+ *     raw exception/message is never used as the identifying `code`, but it
+ *     IS carried in `message` as well as `data.message`: every projection
+ *     (the CLI's `vgai tool`, the oclif commands, `vgai screenshot`'s module
+ *     lane) shows `error.message` and only some of them dump `data`, so a
+ *     `message` that said nothing but "threw an unstructured exception"
+ *     hid the one sentence the caller needed ("No editor connected — open
+ *     the editor in a browser tab, then retry.") behind whichever surface
+ *     happened to print the whole outcome.
+ */
+function normalizeThrown(def: ToolDefinition, err: unknown): StructuredOperationError {
+  if (isOperationError(err)) {
+    const declared = def.errors.find((e) => e.code === err.code);
+    if (!declared) {
+      return {
+        code: CORE_ERROR_CODES.INTERNAL_ERROR,
+        message: `"${def.name}" threw undeclared error code "${err.code}".`,
+        data: { undeclaredCode: err.code, message: err.message },
+      };
+    }
+    if (declared.data) {
+      const parsed = declared.data.safeParse(err.data);
+      if (!parsed.success) {
+        return {
+          code: CORE_ERROR_CODES.INVALID_OUTPUT,
+          message:
+            `"${def.name}" threw declared code "${err.code}" but its data failed that ` +
+            "code's own schema.",
+          issues: toStructuredIssues(parsed.error.issues),
+        };
+      }
+      return { code: err.code, message: err.message, data: parsed.data };
+    }
+    return {
+      code: err.code,
+      message: err.message,
+      ...(err.data !== undefined ? { data: err.data } : {}),
+    };
+  }
+
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    code: CORE_ERROR_CODES.INTERNAL_ERROR,
+    message: `"${def.name}" failed: ${message}`,
+    data: { message },
+  };
+}
+
+function toSummary(def: ToolDefinition): ToolSummary {
+  const { impl: _impl, ...summary } = def;
+  return summary;
+}
+
+/**
+ * Zod object schemas strip unknown keys by default. That is unsafe at an
+ * operation boundary: a misspelled `dryRun` could disappear and let the
+ * operation use its write-default. Detect anything parsing removed, at any
+ * nested object level, and reject it before the implementation can run.
+ */
+function firstStrippedInputPath(
+  raw: unknown,
+  parsed: unknown,
+  path: Array<string | number> = [],
+): Array<string | number> | null {
+  if (Array.isArray(raw) && Array.isArray(parsed)) {
+    for (let index = 0; index < raw.length; index++) {
+      const stripped = firstStrippedInputPath(raw[index], parsed[index], [...path, index]);
+      if (stripped) return stripped;
+    }
+    return null;
+  }
+  if (
+    raw === null ||
+    parsed === null ||
+    typeof raw !== 'object' ||
+    typeof parsed !== 'object' ||
+    Array.isArray(raw) ||
+    Array.isArray(parsed)
+  ) {
+    return null;
+  }
+  const parsedRecord = parsed as Record<string, unknown>;
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!Object.hasOwn(parsedRecord, key)) return [...path, key];
+    const stripped = firstStrippedInputPath(value, parsedRecord[key], [...path, key]);
+    if (stripped) return stripped;
+  }
+  return null;
+}
+
+/**
+ * The one registry of operation definitions (§8 B1). Holds definitions
+ * keyed by their fully-qualified name; `register` rejects a duplicate name
+ * outright (names are unique and stable per the AC), `listOperations`
+ * enumerates metadata without ever touching `impl`, and `dispatch` is the
+ * single validated call path: input schema -> impl -> result schema, with
+ * every failure normalized into `StructuredOperationError`.
+ */
+export class ToolRegistry {
+  private readonly definitions = new Map<string, ToolDefinition>();
+
+  /** Register a definition. Throws synchronously on a duplicate name — names are unique and stable by construction, not by convention. */
+  register<TInput extends z.ZodType, TResult extends z.ZodType, TErrorCode extends string>(
+    def: ToolDefinition<TInput, TResult, TErrorCode>,
+  ): void {
+    if (this.definitions.has(def.name)) {
+      throw new Error(
+        `ToolRegistry.register: "${def.name}" is already registered — operation names ` +
+          'must be unique and stable.',
+      );
+    }
+    this.definitions.set(def.name, def as unknown as ToolDefinition);
+  }
+
+  /** Enumerate every registered operation's metadata. Never invokes `impl`. */
+  listOperations(): ToolSummary[] {
+    return [...this.definitions.values()].map(toSummary);
+  }
+
+  /** Look up one operation's full definition (including `impl`) by name, or `undefined`. */
+  getOperation(name: string): ToolDefinition | undefined {
+    return this.definitions.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.definitions.has(name);
+  }
+
+  /**
+   * Validate `input` against the named operation's input schema, run its
+   * `impl`, validate the return value against its result schema, and return
+   * a uniform `ToolOutcome` — success or a `StructuredOperationError`.
+   * Never throws for an expected failure (unknown name, bad input, impl
+   * throw, bad output); those are exactly what this method exists to turn
+   * into a machine-readable result instead of an exception a caller has to
+   * parse prose out of.
+   */
+  async dispatch<TResult = unknown>(
+    name: string,
+    input: unknown,
+    ctx: ToolContext = {},
+  ): Promise<ToolOutcome<TResult>> {
+    const def = this.definitions.get(name);
+    if (!def) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.OPERATION_NOT_FOUND,
+          message: `No operation is registered as "${name}".`,
+          data: { name },
+        },
+      };
+    }
+
+    const parsedInput = def.input.safeParse(input);
+    if (!parsedInput.success) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.INVALID_INPUT,
+          message: `Input for "${name}" failed schema validation.`,
+          issues: toStructuredIssues(parsedInput.error.issues),
+        },
+      };
+    }
+    const strippedPath = firstStrippedInputPath(input, parsedInput.data);
+    if (strippedPath) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.INVALID_INPUT,
+          message: `Input for "${name}" contains an unknown field.`,
+          issues: [
+            {
+              path: strippedPath,
+              message: 'Unknown input field. Check spelling; unknown fields are never ignored.',
+              code: 'unrecognized_key',
+            },
+          ],
+        },
+      };
+    }
+
+    let rawResult: unknown;
+    try {
+      rawResult = await def.impl(parsedInput.data, ctx);
+    } catch (err) {
+      return { ok: false, error: normalizeThrown(def, err) };
+    }
+
+    const parsedResult = def.result.safeParse(rawResult);
+    if (!parsedResult.success) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.INVALID_OUTPUT,
+          message: `Result of "${name}" failed schema validation (implementation bug).`,
+          issues: toStructuredIssues(parsedResult.error.issues),
+        },
+      };
+    }
+
+    return { ok: true, data: parsedResult.data as TResult };
+  }
+}
+
+export type { ExecutionHost, ExecutionRequirements, ToolContext, ToolNamespace };

package/src/tools/types.ts

@@ -0,0 +1,159 @@
+/**
+ * Shared vocabulary for the operation registry (B1).
+ */
+
+/** The four namespaces every operation name must live under (§5.7). */
+export const TOOL_NAMESPACES = ['project', 'editor', 'play', 'cinematic'] as const;
+export type ToolNamespace = (typeof TOOL_NAMESPACES)[number];
+
+/**
+ * Which of the three hosts an operation executes on (§8 B1, the
+ * review-hardened addition):
+ *  - `node` — runs in the SDK's own Node process against files (or, for
+ *    long-running jobs like `cinematic.render`, launches its own browser).
+ *  - `editor-browser` — invoked through the existing
+ *    `POST /__editor/command` SSE relay in
+ *    `packages/editor/server/editor-server.ts`, which broadcasts to the
+ *    connected browser editor and awaits its callback under a short timeout
+ *    (~5s; 120s for `play`). The projection generates the relay stub.
+ *  - `runtime-page` — invoked through the play/render harness in a launched
+ *    runtime page.
+ *
+ * `cinematic.render` is pinned `node` and MUST NOT ride the editor relay's
+ * short timeout — it is a long-running job (see `longRunning` on
+ * `ToolDefinition`).
+ */
+export type ExecutionHost = 'node' | 'editor-browser' | 'runtime-page';
+
+/** Which live contexts an operation needs before it can run. */
+export interface ExecutionRequirements {
+  /** Needs a project directory on disk (no editor process required). */
+  project?: boolean;
+  /** Needs an existing, connected editor session. */
+  editor?: boolean;
+  /** Needs a playable runtime (starts or targets one). */
+  play?: boolean;
+  /** Needs a controlled render runtime. */
+  render?: boolean;
+}
+
+/** Coarse risk classification surfaced to permission-gated callers (agents, HTTP/MCP auth). */
+export type PermissionRisk = 'read' | 'write' | 'destructive';
+
+export interface PermissionMetadata {
+  risk: PermissionRisk;
+  /** Human summary of what this operation is permitted to touch or do. */
+  summary: string;
+}
+
+/** One completed file handed to the host-managed generated-output boundary. */
+export interface ProjectOutputFile {
+  /** Project-relative destination. Slice 1 deliberately permits only public/**. */
+  path: string;
+  content: string | Uint8Array;
+  mediaType?: string;
+  role?: 'asset' | 'provenance' | 'other';
+}
+
+/** JSON-safe summary returned after an atomic generated-output transaction. */
+export interface ProjectGeneratedOutputFile {
+  path: string;
+  bytes: number;
+  mediaType?: string;
+  role?: ProjectOutputFile['role'];
+}
+
+export interface ProjectGeneratedOutput {
+  files: ProjectGeneratedOutputFile[];
+  totalBytes: number;
+  dryRun: boolean;
+  /** Host-created logical record in .vgai/provenance.json; absent for dry runs. */
+  provenanceOperationId?: string;
+}
+
+export interface ProjectProviderExecution {
+  mode: 'mock' | 'direct' | 'managed';
+  provider: string;
+  operation?: string;
+  model?: string;
+  requestId?: string;
+  taskId?: string;
+  managedJobId?: string;
+  /** Route-aware charge snapshot when this execution produced accepted output. */
+  billing?: import('../generations.js').GenerationBilling;
+}
+
+/** Facts the operation host already owns and stamps onto every committed batch. */
+export interface ProjectOutputProvenanceContext {
+  operationName: string;
+  operationSource?: string;
+  /** Sanitized facts for a single provider execution. */
+  execution?: ProjectProviderExecution;
+  /** Ordered facts for a native multi-task pipeline that produced one output batch. */
+  executions?: readonly ProjectProviderExecution[];
+  /** WHICH editor session produced the bytes, for a `project.session.write`
+   *  batch — the kind whose producer is a script an agent ran inside a live
+   *  session rather than an operation that ran here. Shape and meaning:
+   *  `project/provenance.ts`'s `ProjectProvenanceSessionSchema`, which is the
+   *  validated form; this mirror exists because `types.ts` carries no zod. */
+  session?: {
+    id: string;
+    port: number;
+    revision: number;
+    callId?: string;
+  };
+  /** Schema-validated, JSON-safe operation input. */
+  input?: unknown;
+  /** Project-relative paths of the project FILES these bytes were produced
+   *  from — a session-written GLB names the `src/models/<name>.blend` it was
+   *  exported from. Shape and meaning: `project/provenance.ts`'s `inputs`,
+   *  which is the validated form; this mirror exists because `types.ts`
+   *  carries no zod. It is what lets a reader drill DOWN by kind from a
+   *  prefab's glTF to the model it came from. */
+  inputs?: readonly string[];
+}
+
+/**
+ * Host capability supplied only to Node-hosted project operations. Generator
+ * implementations may stay ordinary native JS; their thin operation wrapper
+ * calls this once it has a complete batch ready to commit.
+ */
+export interface ProjectOutputWriter {
+  write(
+    files: readonly ProjectOutputFile[],
+    options?: { dryRun?: boolean },
+  ): Promise<ProjectGeneratedOutput>;
+}
+
+/**
+ * Runtime context passed to every operation's `impl`. Intentionally an open
+ * record (`[key: string]: unknown`) — later units (B2-B8) will grow this with
+ * concrete fields (editor session ids, play session handles, render job
+ * state); B1 only needs the two seams its sample operations touch.
+ */
+export interface ToolContext {
+  /** Absolute path to the target project's root, for `project`-context ops. */
+  projectRoot?: string;
+  /** Base URL of a connected editor session, for `editor`-context ops. */
+  editorUrl?: string;
+  /** Cooperative cancellation for long-running (`node`, `longRunning`) ops. */
+  signal?: AbortSignal;
+  /** Atomic writer for generated project assets (Node project operations). */
+  projectOutputs?: ProjectOutputWriter;
+  /** WHICH mounted instance a game-driving tool should address, when the
+   *  editor has several live (multiplayer authoring). A tool that drives the
+   *  game binds `game.instance(ctx.instance)` from it; omitted means the sole
+   *  live instance. */
+  instance?: string;
+  /** The HOST's project-module loader (the editor server's Vite SSR loader,
+   *  wrapped with dependency-change invalidation). A tool that imports the
+   *  project's own source at run time — `project.bake.preview` importing
+   *  `src/models/barrel.ts` — MUST load through this rather than a raw
+   *  `import()`: Node's ESM cache never invalidates, so a raw import returned
+   *  the FIRST version of a model for the life of the server and every later
+   *  edit re-rendered byte-identical until `vgai restart` (measured on the
+   *  blind modeling bench, 2026-09-05: three restarts in one barrel). Absent
+   *  only when the tool runs outside an editor server. */
+  loadProjectModule?: (absolutePath: string) => Promise<unknown>;
+  [key: string]: unknown;
+}

package/src/transport.ts

@@ -0,0 +1,97 @@
+/**
+ * THE STAGE TRANSPORT'S PUBLISHED TYPES — the vocabulary a contribution needs
+ * to attach something to a stage's transport and to draw a look over it.
+ *
+ * Declared HERE rather than beside the implementation
+ * (`@editor/animation/stage-transport`) so `@vgai/blender` — and any other
+ * skew package — reaches them through `@volter/editor-sdk/host` with no
+ * dependency on the editor's own source and no engine value import. The
+ * implementation imports these; nothing imports the implementation.
+ *
+ * TIME IS A POSITION ON FACTS A WORLD OWNS, AND A POSITION HAS A DRIVER
+ * (WORK.md §The stage transport and the animation door). In Edit, time is
+ * WRITTEN: nothing is running, and "show me frame 24" originates in the
+ * transport and is seeked down into the world. In Play, time is READ: the
+ * game's loop advances its own time and the editor may not write it — the
+ * transport's `driver` says which of the two is true, and the write verbs
+ * refuse by name while it answers `'world'`.
+ *
+ * SECONDS ARE THE SEAM. `fps` is a subject's DISPLAY rate, carried so a look
+ * that thinks in frames (Blender's Timeline) can convert at its own edge and
+ * nowhere else. Keys are deliberately NOT here: Blender's authored keys are
+ * the door's key COLUMNS rather than a per-frame bake, and its bone names
+ * break three's `PropertyBinding` grammar, so no honest common drawing
+ * projection exists — each look draws its own from its own door.
+ */
+
+/**
+ * What a world attaches to a stage so the transport can show it at a time.
+ *
+ * A subject is the world's own object: `seek` calls the world's own code
+ * (Blender's `mixer.setTime` through the wire, three's `AnimationMixer`).
+ * The transport owns the position; the subject owns what that position MEANS.
+ */
+export interface TransportSubject {
+  /** Stable for the lifetime of the attachment. Blender: the action name;
+   *  three: the clip name (or the object's uuid when it carries several). */
+  readonly id: string;
+  readonly label: string;
+  /** The subject's own valid time domain and its display rate. */
+  range(): { start: number; end: number; fps: number };
+  /** THE ONE WRITE. Must be idempotent and synchronous: the transport calls
+   *  it for every crossing, including a re-seek to the time already shown. */
+  seek(seconds: number): void;
+  /** Optional — which of several clips this subject is showing (three).
+   *  Blender omits it: an action IS the subject there. */
+  clips?(): readonly { id: string; label: string }[];
+  setClip?(id: string): void;
+}
+
+export type TransportPlaybackState = 'stopped' | 'paused' | 'playing';
+
+/** Everything a look needs to draw the transport, in one immutable read. */
+export interface StageTransportSnapshot {
+  readonly time: number;
+  readonly range: { start: number; end: number; fps: number; loop: boolean };
+  readonly playbackState: TransportPlaybackState;
+  readonly timeScale: number;
+  readonly activeSubject: string | null;
+  readonly subjects: readonly { id: string; label: string }[];
+  /**
+   * `'world'` ⇔ this stage's store is in Play, so the game's own loop is
+   * advancing time and the editor did not cause it. Every write verb below
+   * refuses while this answers `'world'`; a look draws itself read-only and
+   * says why rather than disabling a button with no reason.
+   */
+  readonly driver: 'editor' | 'world';
+}
+
+/**
+ * The transport as a CONTRIBUTION sees it — the editor's own class minus its
+ * construction and disposal, which belong to the stage that owns it.
+ */
+export interface StageTransportHandle {
+  snapshot(): StageTransportSnapshot;
+  subscribe(listener: () => void): () => void;
+  /** Attach a subject; the first attach becomes active. Returns detach. */
+  attach(subject: TransportSubject): () => void;
+  setActiveSubject(id: string): void;
+  /** `'reverse'` plays backwards — Blender's Timeline has a play-reverse
+   *  button beside play, and the engine's clock has carried the direction all
+   *  along (`AnimationClock.play(direction)`). */
+  play(direction?: 'forward' | 'reverse'): void;
+  pause(): void;
+  stop(): void;
+  seek(seconds: number): void;
+  seekFrame(frame: number): void;
+  setLoop(loop: boolean): void;
+  setTimeScale(scale: number): void;
+  /**
+   * Fires when the playhead SETTLES — on `pause()`, and at scrub-end (the
+   * first 150 ms with no further `seek` while not playing). A world with a
+   * persisted playhead (Blender's `scene.frame_current`) writes its bookmark
+   * here, so a slider drag writes once instead of once per frame. A `seek`
+   * while playing never settles.
+   */
+  onSettled(listener: (seconds: number) => void): () => void;
+}