@aftertext/player 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 z0rimo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,32 @@
1
- # Temporary Holding Version
1
+ # `@aftertext/player`
2
2
 
3
- 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.
3
+ A small headless player layer that threads an active AfterText runtime session
4
+ one observable step at a time.
5
+
6
+ > v0.1 foundation: the public API is early and may change.
7
+
8
+ ## Install
9
+
10
+ ```sh
11
+ npm install @aftertext/player @aftertext/compiler
12
+ ```
13
+
14
+ ## Usage
15
+
16
+ ```ts
17
+ import { compile } from "@aftertext/compiler";
18
+ import { advancePlayer, createPlayer } from "@aftertext/player";
19
+
20
+ const { document } = compile("@scene start\n\nHello.\n");
21
+ let player = createPlayer(document);
22
+ player = advancePlayer(document, player);
23
+
24
+ console.log(player.current);
25
+ ```
26
+
27
+ The player delegates narrative semantics to `@aftertext/runtime`; it does not
28
+ skip content, navigation, choices, or presentation results.
29
+
30
+ ## License
31
+
32
+ MIT
@@ -0,0 +1,15 @@
1
+ import type { StoryDocument } from "@aftertext/compiler";
2
+ import { type AdvanceOptions } from "@aftertext/runtime";
3
+ import type { PlayerState } from "./player-state.js";
4
+ /**
5
+ * Advances one step (docs/PROJECT_SPEC.md Section 18.5). A pure,
6
+ * non-mutating pass-through to runtime `advance()`: calls it with the
7
+ * Player's current `runtimeState`/`cursor`, and returns a new
8
+ * `PlayerState` built from exactly what it returns. Never reinterprets,
9
+ * skips, or auto-consumes any result — content, presentation, choice,
10
+ * navigation, completed, and error are all returned unchanged as
11
+ * `current` (Sections 18.6/18.7/18.10). One `advancePlayer()` call is
12
+ * exactly one runtime `advance()` call.
13
+ */
14
+ export declare function advancePlayer(document: StoryDocument, player: PlayerState, options?: AdvanceOptions): PlayerState;
15
+ //# sourceMappingURL=advance-player.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"advance-player.d.ts","sourceRoot":"","sources":["../src/advance-player.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW,CAGb"}
@@ -0,0 +1,16 @@
1
+ import { advance } from "@aftertext/runtime";
2
+ /**
3
+ * Advances one step (docs/PROJECT_SPEC.md Section 18.5). A pure,
4
+ * non-mutating pass-through to runtime `advance()`: calls it with the
5
+ * Player's current `runtimeState`/`cursor`, and returns a new
6
+ * `PlayerState` built from exactly what it returns. Never reinterprets,
7
+ * skips, or auto-consumes any result — content, presentation, choice,
8
+ * navigation, completed, and error are all returned unchanged as
9
+ * `current` (Sections 18.6/18.7/18.10). One `advancePlayer()` call is
10
+ * exactly one runtime `advance()` call.
11
+ */
12
+ export function advancePlayer(document, player, options) {
13
+ const step = advance(document, player.runtimeState, player.cursor, options);
14
+ return { runtimeState: step.runtimeState, cursor: step.cursor, current: step.result };
15
+ }
16
+ //# sourceMappingURL=advance-player.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"advance-player.js","sourceRoot":"","sources":["../src/advance-player.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAuB,MAAM,oBAAoB,CAAC;AAGlE;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAuB,EACvB,MAAmB,EACnB,OAAwB;IAExB,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5E,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;AACxF,CAAC"}
@@ -0,0 +1,12 @@
1
+ import type { StoryDocument } from "@aftertext/compiler";
2
+ import type { PlayerState } from "./player-state.js";
3
+ /**
4
+ * Creates the initial `PlayerState` for `document` (docs/PROJECT_SPEC.md
5
+ * Section 18.4). Seeds `runtimeState` via the runtime's own
6
+ * `createRuntimeState`, starts `cursor` at the runtime's initial cursor,
7
+ * and sets `current` to `null`. Performs no narrative execution —
8
+ * `advance()` is never called here; the first execution step remains an
9
+ * explicit `advancePlayer()` call.
10
+ */
11
+ export declare function createPlayer(document: StoryDocument): PlayerState;
12
+ //# sourceMappingURL=create-player.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"create-player.d.ts","sourceRoot":"","sources":["../src/create-player.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW,CAMjE"}
@@ -0,0 +1,17 @@
1
+ import { createRuntimeState, INITIAL_CURSOR } from "@aftertext/runtime";
2
+ /**
3
+ * Creates the initial `PlayerState` for `document` (docs/PROJECT_SPEC.md
4
+ * Section 18.4). Seeds `runtimeState` via the runtime's own
5
+ * `createRuntimeState`, starts `cursor` at the runtime's initial cursor,
6
+ * and sets `current` to `null`. Performs no narrative execution —
7
+ * `advance()` is never called here; the first execution step remains an
8
+ * explicit `advancePlayer()` call.
9
+ */
10
+ export function createPlayer(document) {
11
+ return {
12
+ runtimeState: createRuntimeState(document),
13
+ cursor: INITIAL_CURSOR,
14
+ current: null
15
+ };
16
+ }
17
+ //# sourceMappingURL=create-player.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"create-player.js","sourceRoot":"","sources":["../src/create-player.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGxE;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,QAAuB;IAClD,OAAO;QACL,YAAY,EAAE,kBAAkB,CAAC,QAAQ,CAAC;QAC1C,MAAM,EAAE,cAAc;QACtB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}
@@ -0,0 +1,6 @@
1
+ export type { PlayerState } from "./player-state.js";
2
+ export { createPlayer } from "./create-player.js";
3
+ export { advancePlayer } from "./advance-player.js";
4
+ export { selectPlayerChoice } from "./select-player-choice.js";
5
+ export type { AdvanceOptions, AvailableChoiceItem, ContentResult, PresentationResult, ChoiceResult, NavigationResult, CompletedResult, ErrorResult, ExecutionResult, RuntimeExecutionErrorKind, RuntimeExecutionError } from "@aftertext/runtime";
6
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,eAAe,EACf,yBAAyB,EACzB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,15 @@
1
+ // Public API surface for the headless Player Core (docs/PROJECT_SPEC.md
2
+ // Section 18). A thin application layer over @aftertext/runtime: it owns
3
+ // only `PlayerState` and the three pure transitions over it. All narrative
4
+ // semantics — StoryState, ReaderState, NavigationState, the execution
5
+ // cursor, expression evaluation, Reader Memory, Choice validation, Variant
6
+ // resolution, navigation, and execution errors — remain the runtime's.
7
+ //
8
+ // Only the runtime result types a consumer needs to narrow
9
+ // `PlayerState.current` (or to construct `advancePlayer`'s options) are
10
+ // re-exported, by reference to the existing runtime types — never
11
+ // redefined — and no unrelated runtime internals are re-exported.
12
+ export { createPlayer } from "./create-player.js";
13
+ export { advancePlayer } from "./advance-player.js";
14
+ export { selectPlayerChoice } from "./select-player-choice.js";
15
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,yEAAyE;AACzE,2EAA2E;AAC3E,sEAAsE;AACtE,2EAA2E;AAC3E,uEAAuE;AACvE,EAAE;AACF,2DAA2D;AAC3D,wEAAwE;AACxE,kEAAkE;AAClE,kEAAkE;AAGlE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}
@@ -0,0 +1,24 @@
1
+ import type { ExecutionCursor, ExecutionResult, RuntimeState } from "@aftertext/runtime";
2
+ /**
3
+ * The minimum state a headless Player Core session needs to thread between
4
+ * calls (docs/PROJECT_SPEC.md Section 18.2). A thin, three-field wrapper:
5
+ *
6
+ * - `runtimeState` is the authoritative runtime state, stored once and
7
+ * never reinterpreted — `StoryState`/`ReaderState`/`NavigationState`
8
+ * remain exactly where the runtime already keeps them, never duplicated
9
+ * into separate `PlayerState` fields.
10
+ * - `cursor` is the authoritative, opaque runtime execution cursor,
11
+ * threaded exactly as `advance()`/`selectChoice()` return it.
12
+ * - `current` is the most recently exposed runtime `ExecutionResult`.
13
+ * `current === null` means the player was created but no narrative
14
+ * execution has occurred yet.
15
+ *
16
+ * Immutable/caller-owned, matching every other value in this stack — no
17
+ * function in this package ever mutates a `PlayerState` it is given.
18
+ */
19
+ export interface PlayerState {
20
+ readonly runtimeState: RuntimeState;
21
+ readonly cursor: ExecutionCursor;
22
+ readonly current: ExecutionResult | null;
23
+ }
24
+ //# sourceMappingURL=player-state.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"player-state.d.ts","sourceRoot":"","sources":["../src/player-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEzF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=player-state.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"player-state.js","sourceRoot":"","sources":["../src/player-state.ts"],"names":[],"mappings":""}
@@ -0,0 +1,25 @@
1
+ import type { StoryDocument } from "@aftertext/compiler";
2
+ import type { PlayerState } from "./player-state.js";
3
+ /**
4
+ * Resolves a Choice selection (docs/PROJECT_SPEC.md Section 18.7). When
5
+ * `player.current` is a Choice result, reconstructs the exact
6
+ * `ExecutionStep` runtime `selectChoice()` requires from Player's own
7
+ * three fields and delegates entirely to it — never re-evaluating
8
+ * conditions, never reconstructing items from the source AST, never
9
+ * adding a `ChoiceRecord` or a freshness check. `selectChoice` remains
10
+ * the sole authority for validating `index`, and its existing replay/fork
11
+ * semantics apply unchanged: an older, still-valid `PlayerState` may be
12
+ * selected from independently and repeatedly.
13
+ *
14
+ * If `player.current` is not a Choice result, this is defensive
15
+ * application-API behavior (Section 18.8), never a thrown exception and
16
+ * never a new Player-specific error type. When an `ExecutionStep` already
17
+ * exists (`current` is `content`/`presentation`/`navigation`/`completed`/
18
+ * `error`), delegating to `selectChoice` itself is the source of this
19
+ * rejection — it already refuses a suspension that isn't a choice. Only
20
+ * for `current === null`, where no `ExecutionStep` exists yet to delegate
21
+ * to, is the identical runtime error outcome constructed directly here,
22
+ * via the existing `RuntimeErrors` factory.
23
+ */
24
+ export declare function selectPlayerChoice(document: StoryDocument, player: PlayerState, index: number): PlayerState;
25
+ //# sourceMappingURL=select-player-choice.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"select-player-choice.d.ts","sourceRoot":"","sources":["../src/select-player-choice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAmB3G"}
@@ -0,0 +1,42 @@
1
+ import { RuntimeErrors, selectChoice } from "@aftertext/runtime";
2
+ /**
3
+ * Resolves a Choice selection (docs/PROJECT_SPEC.md Section 18.7). When
4
+ * `player.current` is a Choice result, reconstructs the exact
5
+ * `ExecutionStep` runtime `selectChoice()` requires from Player's own
6
+ * three fields and delegates entirely to it — never re-evaluating
7
+ * conditions, never reconstructing items from the source AST, never
8
+ * adding a `ChoiceRecord` or a freshness check. `selectChoice` remains
9
+ * the sole authority for validating `index`, and its existing replay/fork
10
+ * semantics apply unchanged: an older, still-valid `PlayerState` may be
11
+ * selected from independently and repeatedly.
12
+ *
13
+ * If `player.current` is not a Choice result, this is defensive
14
+ * application-API behavior (Section 18.8), never a thrown exception and
15
+ * never a new Player-specific error type. When an `ExecutionStep` already
16
+ * exists (`current` is `content`/`presentation`/`navigation`/`completed`/
17
+ * `error`), delegating to `selectChoice` itself is the source of this
18
+ * rejection — it already refuses a suspension that isn't a choice. Only
19
+ * for `current === null`, where no `ExecutionStep` exists yet to delegate
20
+ * to, is the identical runtime error outcome constructed directly here,
21
+ * via the existing `RuntimeErrors` factory.
22
+ */
23
+ export function selectPlayerChoice(document, player, index) {
24
+ if (player.current === null) {
25
+ return {
26
+ runtimeState: player.runtimeState,
27
+ cursor: player.cursor,
28
+ current: {
29
+ type: "error",
30
+ error: RuntimeErrors.invalidChoiceSelection("Not currently suspended on a choice.")
31
+ }
32
+ };
33
+ }
34
+ const suspension = {
35
+ runtimeState: player.runtimeState,
36
+ cursor: player.cursor,
37
+ result: player.current
38
+ };
39
+ const step = selectChoice(document, suspension, index);
40
+ return { runtimeState: step.runtimeState, cursor: step.cursor, current: step.result };
41
+ }
42
+ //# sourceMappingURL=select-player-choice.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"select-player-choice.js","sourceRoot":"","sources":["../src/select-player-choice.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAsB,MAAM,oBAAoB,CAAC;AAGrF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAuB,EAAE,MAAmB,EAAE,KAAa;IAC5F,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO;YACL,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE;gBACP,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,aAAa,CAAC,sBAAsB,CAAC,sCAAsC,CAAC;aACpF;SACF,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAkB;QAChC,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,MAAM,CAAC,OAAO;KACvB,CAAC;IACF,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IACvD,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;AACxF,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "@aftertext/player",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "AfterText headless Player Core: a thin, pure application layer over @aftertext/runtime for threading an active play session.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/z0rimo/AfterText.git",
9
+ "directory": "packages/player"
10
+ },
11
+ "type": "module",
12
+ "main": "./dist/index.js",
13
+ "types": "./dist/index.d.ts",
14
+ "exports": {
15
+ ".": {
16
+ "types": "./dist/index.d.ts",
17
+ "default": "./dist/index.js"
18
+ }
19
+ },
20
+ "files": [
21
+ "dist"
22
+ ],
23
+ "publishConfig": {
24
+ "access": "public"
25
+ },
26
+ "scripts": {
27
+ "build": "tsc -p tsconfig.json",
28
+ "prepack": "tsc -b --force",
29
+ "typecheck": "tsc -p tsconfig.typecheck.json",
30
+ "test": "vitest run"
31
+ },
32
+ "dependencies": {
33
+ "@aftertext/compiler": "^0.1.0",
34
+ "@aftertext/runtime": "^0.1.0"
35
+ },
36
+ "devDependencies": {
37
+ "@types/node": "^22.7.5",
38
+ "typescript": "^5.6.3",
39
+ "vitest": "^2.1.2"
40
+ }
41
+ }