@volter/play 0.0.0-stage → 0.5.204

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Volter AI, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+Copyright 2026 Volter AI, Inc.
+
+This package is developed in the public volter-ai/editor repository and is
+Volter AI, Inc.'s own work. It was first published under AGPL-3.0-only and is
+licensed under Apache-2.0 from this notice on. The owner's words are "the
+runtime should be apache, the editor is agpl"; that this package is runtime
+(the play-script API a game's gameplay is written against) is the reading
+recorded as ruling D336 on board task t_b315eb39 and in COMMERCIAL.md at the
+repository root. LICENSE contains the Apache-2.0 text.
+
+A play script is written against `src/play-script.ts`. The package imports
+`@volter/sdk` (Apache-2.0), three and React, and nothing of Blender.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# Play
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Play scripts on detached model documents. Play (the Game panel's, in Cyclotron) runs
+`src/models/<name>.play.ts` beside `src/models/<name>.blend` on a detached copy
+of the model; the model, its selection and its history stand as they were, and
+Stop returns to them. The script's default export is called once with the play
+context (`ModelPlayContext`, `src/play-script.ts`) and answers the game:
+
+```ts
+import type { ModelPlayContext, ModelPlayGame } from '@volter/play/play-script';
+
+export default (play: ModelPlayContext): ModelPlayGame => {
+  const player = play.find('Player')!;
+  let checkpoint = false;
+  return {
+    update(dt) {
+      player.position.y += dt;
+      if (!checkpoint && player.position.y > 10) {
+        checkpoint = true;
+        play.tint('Checkpoint.Pad', '#2bff6b');
+        play.log('checkpoint', { stage: 2, at: player.position });
+      }
+    },
+  };
+};
+```
+
+## The play log
+
+`play.log(kind, facts?)` writes one entry, stamped with `simT` (seconds of
+simulation since Play started, the sum of the `dt`s given to `update`) and
+`tick` (the update in progress). Facts are snapshotted as JSON when logged. `simT` and `tick` are the Game panel's
+clock: they stand still while paused and run at the speed (see Time below). The
+runner adds `play-start`, `play-restart` (`{ speed }`, right after a Restart's
+`play-start`), `script-reload` (`{ reason: 'saved' | 'dependency-deleted', path }`),
+`script-error` (`{ phase, message }`), `tint-unsupported` (`{ object, material, why }`),
+`tint-unknown-object` (`{ object, call }`, once per name: `tint` or `setOpacity` was given a
+name the model has none of, and did nothing), `autoplay-on` / `autoplay-off`
+(`{ by: 'panel' | 'cli' | 'takeover' | 'script' }`, see Autoplay below),
+`autoplay-unavailable` (`{ why }`, when a script's first update has run and it registered no
+bot; once per run, and again only if a bot came and went),
+`pause`, `resume`, `step` (`{ dt }`, one per stepped update), `speed`
+(`{ speed, from }` on a change; `{ speed }` at a start that is not 1×) and
+`play-stop` (`{ reason }`). Log transitions rather than every frame. Logging
+never throws and never changes timing or state; a script's `log`, `tint` and
+`setOpacity` do nothing once it has been replaced or Play has stopped.
+
+Each model document keeps its own log; a read takes the active Play's unless it
+names a document. The newest 5000 entries are kept (older ones are counted as
+`dropped`), each entry's facts up to 2048 characters of JSON. Play from a fresh
+copy, and Restart, empty the document's log; a script reload does not, and the log stays readable after Stop until the
+next Play. `console.log` does not reach the session's console feed (only
+warnings and errors do); the play log does.
+
+```sh
+cyclotron play-log                     # every kept entry, one per line
+cyclotron play-log --kind death        # one kind
+cyclotron play-log --since 12.5 --json # entries at or after simT 12.5, as JSON
+cyclotron play-log --document <id>     # another model document's log
+cyclotron eval "(await editor.modelPlayLog({ kind: 'death' })).entries"
+```
+
+## Recolouring the copy
+
+`play.tint(object, color)` draws an object (a name, or what `find` answered)
+and every mesh under it in `color`; an emitting surface glows in it, and an
+image texture is multiplied by it. `play.setOpacity(object, opacity)` fades it.
+`null` returns the authored look. Other objects wearing the same Blender
+material are not affected.
+
+Use these instead of editing materials directly: a presented mesh's `material`
+is an array with one `MeshPhysicalMaterial` per Blender material slot, shared by
+every object with that material; the presenter re-assigns those slots whenever
+it re-applies shading; `clone()` drops its shader hooks; and a node graph that
+drives Base Color or Alpha ignores `color` and `opacity`. A tinted or faded
+object wears copies of its own slots that draw the material's constant inputs
+(so a node graph's other inputs are not drawn while it does), and keeps them
+across a script reload. An object with a material the document cannot copy
+(one the script made itself) is left as it is, and the log says so once with
+`tint-unsupported`.
+
+## Autoplay
+
+A game offers its bot; the editor decides whether it drives.
+
+```ts
+play.autoplay(({ dt, simT, tick, keys }) => {
+  // the game's own decision, from its own state
+  return car.speed < 20 ? ['ArrowUp'] : [];
+});
+```
+
+The controller is a plain function. While autoplay is on it is called before each `update`
+with that update's `dt`, `simT` and `tick` (the stamps that update's log entries carry) and
+`keys`, the keys the person holds; it returns the `KeyboardEvent.code` keys the bot holds for
+that update (any iterable, or nothing). The runner merges them into `play.keys`, so the bot
+drives through the script's own input code exactly as a person does. One bot per script:
+registering again replaces it, `play.autoplay(null)` withdraws it, and it goes with the script
+on a reload or Stop. The bot is called only inside the editor's Play runner; a game run
+anywhere else never drives itself.
+
+Whether it drives is the editor's:
+
+- Autoplay is **off** whenever Play starts or restarts.
+- Only the Game panel's **Autoplay** toggle, `cyclotron play autoplay on|off` or
+  `await editor.command('volter.model-play.autoplay', { on: true })` turn it on (or off).
+- **A bot exists only while the game runs**: `play.autoplay` is called by the play script, so
+  a stopped game (or one still starting) has none, and neither has a running script that never
+  registers one. The panel says which, in words beside the toggle — "Available once the game is
+  running" or "No autoplay — this game doesn't provide a bot" — and `on` is refused with the
+  same reason, which `play state` also gives as `autoplay.why`.
+- **Arming.** Pressed while stopped, the panel's Autoplay arms the next start: autoplay turns
+  on (`by: 'panel'`) as soon as that run's script has run its first update with a bot, and the
+  arm is dropped if it offers none. A person's key or click in the game before then drops it
+  too (`autoplay-off` with `{ by: 'takeover', armed: true }`): the person always wins. Only an
+  explicit arm carries over; Stop, and closing the model, drop it.
+- **The person always wins.** A new key press the game would hear, or a pointer pressed in the
+  game's area (the HUD included), turns autoplay off before that key reaches `play.keys`, and
+  the panel reads "You're driving" until someone switches the bot on again. Synthetic keys and
+  clicks (`editor.document.key`, `click`) count as a person's: they are how an agent plays by
+  hand. A key repeat is not a new press; keys typed in a text field, or while the game's surface
+  does not hold the keyboard, are not the game's and do not take over.
+- A bot that throws turns autoplay off (`by: 'script'`, with a `script-error` of phase
+  `autoplay`), as does a reload whose script offers no bot.
+
+Each change is a play-log entry, `autoplay-on` or `autoplay-off`, with `by`.
+
+## Time
+
+`update(dt)` is the only clock a play script is given, and the editor decides it:
+
+| Control | What the script sees |
+| --- | --- |
+| Playing at 1× | One `update` per drawn frame, `dt` = the frame's seconds (at most 0.1). |
+| Speed 0.25× – 4× | `dt` scaled by the speed. A scaled frame longer than 0.1 s is split into equal updates, so no single `dt` exceeds 0.1. |
+| Pause | No `update` at all. The copy, the camera and the HUD hold the last frame. |
+| Step (while paused) | One `update` with `dt` = 1/60. |
+| Restart | The run begins again on a fresh detached copy, the clock at zero, without the camera's fly-in. |
+
+A script that reads the page's own clock (`performance.now()`, `Date.now()`) instead of
+summing `dt` is outside the reach of pause and speed.
+
+The run's clock — simulation time (the sum of the `dt`s handed to the script) and tick (the
+number of updates) — is kept per document beside whether it plays (`src/model-play.ts`).
+Speed is kept for the page's life; pause and the clock reset on every Play.
+When the run plays but no game runs — the script failed to start, or threw — the clock's
+`failure` says why (the Game panel shows it in place of "Playing"); a save of the script
+retries, and the next running game clears it.
+
+## Controls
+
+The tool registers the `model` document Play extension
+(`@volter/sdk/kit/document-play-extension`). Beside Play and Stop it offers:
+
+- `transport` — `setPaused`, `step`, `setSpeed`, `restart`, the `clock` and its own
+  subscription, the offered `speeds`, and the restart `generation` the document keys its
+  detached copy on.
+- `transport.autoplay(documentId)` and `transport.setAutoplay(documentId, on, by)` — the bot's
+  switch: `{ on, available, by, armed }`, announced through `subscribeClock`;
+  `transport.armAutoplay(documentId, armed)` arms it, while stopped, for the next start.
+- `log` — `tail(documentId, last, kind?)` (the newest entries and every kind the run wrote) and
+  `subscribe`, which the Game panel draws live.
+- `scriptPath(sourcePath)` and `hasScript(sourcePath)` — where a model's play script goes and
+  whether it exists, so a layout can open a model with a script as a game.
+
+In Cyclotron these are drawn by the Game panel (`@volter/editor-blender`): the Game /
+Animation switch at the left of the bottom area's header puts it there in place of the Timeline. The panel's controls
+are also commands, `volter.model-play.<verb>`, so an agent drives the same run the person
+sees:
+
+| Command | Arguments |
+| --- | --- |
+| `volter.model-play.state` | — |
+| `volter.model-play.play` / `stop` | — (`play` also switches the document to Game mode) |
+| `volter.model-play.pause` / `resume` | — |
+| `volter.model-play.step` | `{ count?: 1–600 }`, while paused |
+| `volter.model-play.speed` | `{ speed: 0.25 \| 0.5 \| 1 \| 2 \| 4 }` |
+| `volter.model-play.restart` | — |
+| `volter.model-play.mode` | `{ mode?: 'game' \| 'animation' }` |
+| `volter.model-play.autoplay` | `{ on: boolean }` — the game's bot drives, or the person does |
+
+Each takes an optional `document` (the model document's id) and otherwise acts on the model
+document on screen; each answers with the panel's state. From the shell:
+`cyclotron play pause`; under `eval`:
+`await editor.command('volter.model-play.speed', { speed: 0.5 })`.

package/contributions/model-play.command.ts

@@ -0,0 +1,37 @@
+/**
+ * THE MODEL PLAY VERB of the session wire (`@volter/sdk/commands`, a
+ * `workspace.command` contribution): `model-play-log`, the read behind
+ * `cyclotron play-log` and `editor.modelPlayLog()` in `eval`.
+ *
+ * It answers one model document's play log (`../src/play-log.ts`) — `documentId`'s, or the
+ * active Play's when omitted; the current run's, or the last one's after Stop — filtered by
+ * `since` (simulation seconds, inclusive) and `kind`. A read
+ * only: no play gate, since an empty log is the honest answer when nothing has played.
+ */
+import type { CommandContribution } from '@volter/sdk/commands';
+import { readModelPlayLog } from '../src/play-log';
+
+export const point = 'workspace.command';
+
+export const commands: CommandContribution['commands'] = {
+  'model-play-log': {
+    derivedRefresh: 'none',
+    handle: (command) => {
+      const since = command['since'];
+      const kind = command['kind'];
+      const documentId = command['documentId'];
+      if (documentId !== undefined && typeof documentId !== 'string')
+        return { ok: false, error: `model-play-log's documentId is a model document id, a string; it was given ${JSON.stringify(documentId)}.` };
+      if (since !== undefined && (typeof since !== 'number' || !Number.isFinite(since)))
+        return { ok: false, error: `model-play-log's since is simulation seconds, a number; it was given ${JSON.stringify(since)}.` };
+      if (kind !== undefined && typeof kind !== 'string')
+        return { ok: false, error: `model-play-log's kind is an entry kind, a string; it was given ${JSON.stringify(kind)}.` };
+      const reading = readModelPlayLog({
+        ...(documentId === undefined ? {} : { documentId }),
+        ...(since === undefined ? {} : { since }),
+        ...(kind === undefined ? {} : { kind }),
+      });
+      return { ok: true, data: { ...reading } };
+    },
+  },
+};

package/contributions/model-play.service.tsx

@@ -0,0 +1,152 @@
+/** Model script tool, available to every product through project packages. */
+import { useSyncExternalStore } from 'react';
+import { Button, EditorIcon, editorIcons, MenuItem } from '@volter/sdk/widgets';
+import { editorHost } from '@volter/sdk/host';
+import { registerDocumentPlayExtension, type DocumentPlayControlProps } from '@volter/sdk/kit/document-play-extension';
+import {
+  armModelPlayAutoplay,
+  escapeModelPlay,
+  MODEL_PLAY_SPEEDS,
+  modelPlayAutoplay,
+  modelPlayClock,
+  modelPlayGeneration,
+  modelPlaying,
+  restartModelPlay,
+  setModelPlayAutoplay,
+  setModelPlayFailure,
+  setModelPlayPaused,
+  setModelPlaying,
+  setModelPlaySpeed,
+  stepModelPlay,
+  subscribeModelPlay,
+  subscribeModelPlayClock,
+} from '../src/model-play';
+import { playScriptPath, runPlayScript } from '../src/play-script';
+import { beginModelPlayLog, subscribeModelPlayLog, tailModelPlayLog } from '../src/play-log';
+import type * as THREE from 'three';
+import { getCurrentProject, onProjectChange } from '@volter/sdk/kit/active-project';
+
+export const point = 'workspace.service';
+function usePlaying(documentId: string | undefined): boolean {
+  return useSyncExternalStore(subscribeModelPlay, () => documentId ? modelPlaying(documentId) : false, () => false);
+}
+// Kept because `DocumentPlayExtension` requires `Control` and `Menu` for a layout that draws Play in its header; Cyclotron's layout no longer does (its Play is the Game panel's).
+function Control({ documentId, onClose }: DocumentPlayControlProps) {
+  const playing = usePlaying(documentId);
+  return <Button size="compact" data-testid="model-play-button" aria-pressed={playing}
+    disabled={!documentId} title={playing ? 'Stop playing (Escape)' : 'Play this model’s script'}
+    onClick={() => { onClose(); if (documentId) setModelPlaying(documentId, !playing); }}>
+    <EditorIcon icon={playing ? editorIcons.transport.stop : editorIcons.transport.play} />
+    {playing ? 'Stop' : 'Play'}
+  </Button>;
+}
+function Menu({ documentId, onClose }: DocumentPlayControlProps) {
+  const playing = usePlaying(documentId);
+  return <MenuItem data-testid="model-play" disabled={!documentId}
+    onSelect={() => { onClose(); if (documentId) setModelPlaying(documentId, !playing); }}>
+    {playing ? 'Stop' : 'Play'}
+  </MenuItem>;
+}
+
+/**
+ * WHETHER A MODEL HAS A PLAY SCRIPT — `src/models/canyon.blend` has one when
+ * `src/models/canyon.play.ts` exists (`playScriptPath`), the same file Play imports. Asked once
+ * per path through the project's files door and then kept, corrected by that door's change
+ * events, so a layout can open a model with a script as a game and one without as a model. A
+ * project switch forgets every answer.
+ */
+const scripts = new Map<string, boolean>();
+const looking = new Set<string>();
+const scriptListeners = new Set<() => void>();
+function publishScripts(): void {
+  for (const listener of [...scriptListeners]) listener();
+}
+function projectPath(path: string): string {
+  return path.replaceAll('\\', '/').replace(/^\.\//, '');
+}
+function hasScript(sourcePath: string): boolean | null {
+  const path = projectPath(playScriptPath(sourcePath));
+  const known = scripts.get(path);
+  if (known !== undefined) return known;
+  if (!looking.has(path)) {
+    looking.add(path);
+    const project = getCurrentProject()?.rootPath;
+    void editorHost().files.exists(path).then(exists => exists, () => false).then(exists => {
+      looking.delete(path);
+      // An answer about the previous project is no answer about this one.
+      if (getCurrentProject()?.rootPath !== project) return;
+      scripts.set(path, exists);
+      publishScripts();
+    });
+  }
+  return null;
+}
+
+export function start(): () => void {
+  const stopWatching = (() => {
+    try {
+      return editorHost().files.watch((event) => {
+        const path = projectPath(event.path);
+        if (!scripts.has(path) && !path.endsWith('.play.ts')) return;
+        const exists = event.type !== 'remove';
+        if (scripts.get(path) === exists) return;
+        scripts.set(path, exists);
+        publishScripts();
+      });
+    } catch {
+      // A host without a files door still plays; the answer is then read once per path.
+      return () => {};
+    }
+  })();
+  const stopProject = onProjectChange(() => { scripts.clear(); publishScripts(); });
+  const unregister = registerDocumentPlayExtension('model', {
+    Control, Menu, playing: modelPlaying, setPlaying: setModelPlaying, escape: escapeModelPlay,
+    subscribe(listener) {
+      const stopPlay = subscribeModelPlay(listener), stopProject = onProjectChange(listener);
+      scriptListeners.add(listener);
+      return () => { stopPlay(); stopProject(); scriptListeners.delete(listener); };
+    },
+    aspectRatio() {
+      const size = getCurrentProject()?.config.resolution;
+      const ratio = size ? size.width / size.height : null;
+      return ratio !== null && Number.isFinite(ratio) && ratio > 0 ? ratio : null;
+    },
+    run(stage) {
+      // The document kind lends native scene objects; this tool owns their Three types.
+      return runPlayScript({ ...stage, blend: stage.sourcePath, root: stage.root as THREE.Object3D,
+        camera: stage.camera as () => THREE.Camera, editingCamera: stage.editingCamera as () => THREE.Camera,
+        ownMaterial: stage.ownMaterial as ((material: THREE.Material) => THREE.Material | null) | undefined });
+    },
+    // THE RUN'S TRANSPORT (`model-play.ts`): the runner reads all of it each frame.
+    transport: {
+      speeds: MODEL_PLAY_SPEEDS,
+      clock: modelPlayClock,
+      subscribeClock: subscribeModelPlayClock,
+      setPaused: setModelPlayPaused,
+      step: stepModelPlay,
+      setSpeed: setModelPlaySpeed,
+      restart: restartModelPlay,
+      generation: modelPlayGeneration,
+      autoplay: modelPlayAutoplay,
+      setAutoplay: setModelPlayAutoplay,
+      armAutoplay: armModelPlayAutoplay,
+      // NO STAGE, SO NO RUNNER, and until 2026-10-06 the document turned Play off and wrote the
+      // reason to the console: Play flicked on and off with nothing said where anyone looks.
+      // Now the run stands with its failure — the Game panel draws it, the log records it.
+      fail(documentId, sourcePath, failure) {
+        const run = beginModelPlayLog(documentId, playScriptPath(sourcePath));
+        run.append('play', 'script-error', { phase: 'stage', message: failure });
+        run.end({ reason: 'stage-failed' });
+        setModelPlayFailure(documentId, failure);
+      },
+    },
+    log: { tail: tailModelPlayLog, subscribe: subscribeModelPlayLog },
+    scriptPath: playScriptPath,
+    hasScript,
+  });
+  return () => {
+    unregister();
+    stopProject();
+    stopWatching();
+  };
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@volter/play",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.204",
+  "author": "Volter AI, Inc.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "description": "Play scripts on detached model documents.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/editor.git",
+    "directory": "packages/play"
+  },
+  "files": [
+    "src",
+    "contributions",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "exports": {
+    "./contributions/*": "./contributions/*",
+    "./package.json": "./package.json",
+    "./play-script": "./src/play-script.ts"
+  },
+  "volter": {
+    "contributions": [
+      "./contributions/model-play.command.ts",
+      "./contributions/model-play.service.tsx"
+    ]
+  },
+  "dependencies": {
+    "@volter/sdk": "0.5.204"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "three": "^0.180.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}