@forgeax/engine-state 0.1.2

package/dist/resources.d.ts

@@ -0,0 +1,23 @@
+import type { StateToken } from './define-state';
+/**
+ * Resource key for the current state value of a token.
+ *
+ * The {@link StateTokenVariant} is stored; `getState(world, token)` reads
+ * this Resource and decodes the index to a variant string.
+ */
+export declare function stateResourceKey(token: StateToken): string;
+/**
+ * Resource key for the pending next-state transition request.
+ *
+ * Written by `setNextState` / `setNextStateForce` (M2); consumed by
+ * `transitionStatesSystem` (M3).
+ */
+export declare function nextStateResourceKey(token: StateToken): string;
+/**
+ * Resource key for the previous-frame state value.
+ *
+ * Written by `transitionStatesSystem` before flipping `State`; read by
+ * `getPreviousState(world, token)` (M2).
+ */
+export declare function previousStateResourceKey(token: StateToken): string;
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAMjD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAElE"}

package/dist/scoped-component.d.ts

@@ -0,0 +1,38 @@
+import { defineComponent, type EntityHandle, type World } from '@forgeax/engine-ecs';
+import type { StateToken, StateTokenVariant } from './define-state';
+/** Fixed label-to-value map for the ScopedTo `mode` enum field. */
+export declare const SCOPED_MODE_VALUE: {
+    readonly exit: 0;
+    readonly enter: 1;
+};
+/** Resolve the world-local ScopedTo token for a state. */
+export declare function getScopedComponent(token: StateToken): ReturnType<typeof defineComponent>;
+export declare function despawnOnExit<T extends StateToken>(world: World, entity: EntityHandle, token: T, variant: StateTokenVariant<T>): void;
+/**
+ * Mark `entity` to be despawned when `token` enters `variant`.
+ *
+ * Adds a `__scopedTo__<token.name>` component with mode=enter
+ * and value=<variant index>. When transitionStatesSystem detects
+ * the token transitions into `variant`, it despawns the entity.
+ *
+ * Throws if `entity` already carries this token's ScopedTo component
+ * (ECS default exclusive=false fail-fast).
+ */
+export declare function despawnOnEnter<T extends StateToken>(world: World, entity: EntityHandle, token: T, variant: StateTokenVariant<T>): void;
+/**
+ * Pre-register scoped components for all state tokens in the global registry.
+ * Called by registerStatesPlugin during boot; idempotent.
+ *
+ * @internal
+ */
+export declare function registerScopedComponents(): void;
+/**
+ * Count entities carrying `token`'s ScopedTo component, grouped by the variant
+ * index they are scoped to (irrespective of exit/enter mode). Returns an array
+ * aligned to `token.variants` (index i = count for `token.variants[i]`).
+ *
+ * Used by the `state get <name>` CLI inspector to report per-variant scoped
+ * entity counts (requirements AC-15). Reflection only — does not mutate World.
+ */
+export declare function countScopedEntitiesByVariant(world: World, token: StateToken): number[];
+//# sourceMappingURL=scoped-component.d.ts.map

package/dist/scoped-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-component.d.ts","sourceRoot":"","sources":["../src/scoped-component.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAKpE,mEAAmE;AACnE,eAAO,MAAM,iBAAiB;;;CAAiC,CAAC;AAuBhE,0DAA0D;AAC1D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAExF;AAuCD,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAChD,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,IAAI,CAON;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,UAAU,EACjD,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAI/C;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,CAUtF"}

package/dist/set-next-state.d.ts

@@ -0,0 +1,48 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { StateToken, StateTokenVariant } from './define-state';
+import type { StateError } from './errors';
+/**
+ * Request a state transition for `token` to `variant` at the next frame.
+ *
+ * `variant` is narrowed to the token's variant union: a misspelled variant is
+ * a compile-time error (`StateTokenVariant<T>`), not just a runtime
+ * `invalid-variant` Result.
+ */
+export declare function setNextState<T extends StateToken>(world: World, token: T, variant: StateTokenVariant<T>): {
+    ok: true;
+    value: undefined;
+} | {
+    ok: false;
+    error: StateError;
+};
+/**
+ * Like {@link setNextState} but with `force=true`.
+ */
+export declare function setNextStateForce<T extends StateToken>(world: World, token: T, variant: StateTokenVariant<T>): {
+    ok: true;
+    value: undefined;
+} | {
+    ok: false;
+    error: StateError;
+};
+/**
+ * Read the current state value for `token`.
+ */
+export declare function getState(world: World, token: StateToken): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    error: StateError;
+};
+/**
+ * Read the previous-frame state value for `token`.
+ */
+export declare function getPreviousState(world: World, token: StateToken): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    error: StateError;
+};
+//# sourceMappingURL=set-next-state.d.ts.map

package/dist/set-next-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-next-state.d.ts","sourceRoot":"","sources":["../src/set-next-state.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAa3C;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAC/C,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAEnE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,UAAU,EACpD,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAEnE;AAiBD;;GAEG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,UAAU,GAChB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAWhE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,UAAU,GAChB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAWhE"}

package/dist/transition-system.d.ts

@@ -0,0 +1,3 @@
+import type { World } from '@forgeax/engine-ecs';
+export declare function transitionStatesSystem(world: World): void;
+//# sourceMappingURL=transition-system.d.ts.map

package/dist/transition-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-system.d.ts","sourceRoot":"","sources":["../src/transition-system.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAA2B,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAwD1E,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CA0EzD"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@forgeax/engine-state",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Single-world typed-state machine with state-scoped entity lifecycle.",
+  "bin": {
+    "forgeax-engine-remote-state": "./dist/cli-state.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ecs": "0.1.2",
+    "@forgeax/engine-plugin": "0.1.2",
+    "@forgeax/engine-scene": "0.1.2",
+    "@forgeax/engine-types": "0.1.2"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "library package, no runtime canvas; fps reported by hello-level-switch app"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "bench focus stays on engine-math; state correctness verified by unit tests"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; smoke gate covered by hello-level-switch app"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/cli-state.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// @forgeax/engine-state/src/cli-state - forgeax-engine-remote-state plugin bin
+// (feat-20260616-engine-state-and-state-scoped-entities M6 / m6w2).
+//
+// Two subcommands:
+//   state list  — iterates getRegisteredTokens() and prints name + variants + current state
+//   state get <name> — calls getState and prints the variant string
+//
+// Discovery: kubectl 4th-path. The base bin `forgeax-engine-console` finds
+// this binary on PATH via the `forgeax-engine-remote-` prefix scan and
+// forwards stdio + exit code (see packages/console/src/discoverPlugins.ts).
+//
+// The `connect` field in DispatchOptions is optional — this CLI plugin reads
+// from a directly supplied World reference (not through JSON-RPC over WS)
+// because state introspection is a local ECS operation, not a remote inspector
+// call. When the bin is invoked via PATH discovery from the base console CLI,
+// stdin forwarding is the standard plugin channel; the World reference is
+// provided by `world` in the script context injected via `vm.runInContext`.
+//
+// Decision anchors:
+// - M6 spec: console state list iterates getRegisteredTokens()
+// - M6 spec: console state get <name> calls getState and prints variant string
+// - plan-strategy: cli-state reflects the state registry (M2) + current state (M2)
+// - Console plugin pattern: argv-based dispatch with stdoutWrite/stderrWrite
+
+import type { World } from '@forgeax/engine-ecs';
+import type { StateToken } from './define-state';
+import { getRegisteredTokens } from './define-state';
+import { countScopedEntitiesByVariant } from './scoped-component';
+import { getPreviousState, getState } from './set-next-state';
+
+// ─── Dispatch options (test-injectable) ─────────────────────────────────────
+
+export interface DispatchOptions {
+  readonly argv: readonly string[];
+  readonly stdoutWrite: (line: string) => void;
+  readonly stderrWrite: (line: string) => void;
+  readonly world: World;
+}
+
+// ─── Help renderer ──────────────────────────────────────────────────────────
+
+function helpBody(): string {
+  return [
+    'forgeax-engine-remote-state - inspect forgeax state machines',
+    '',
+    'Usage:',
+    '  forgeax-engine-remote-state <subcommand> [args]',
+    '',
+    'Subcommands:',
+    '  list           list all registered tokens: name, current, previous, default, variants',
+    '  get <name>     print one token: current, previous, default, variants + per-variant scoped entity counts',
+    '',
+    'Flags:',
+    '  --help, -h     show this help and exit 0',
+    '',
+    'Examples:',
+    '  forgeax-engine-remote-state list',
+    '  forgeax-engine-remote-state get LevelId',
+    '',
+  ].join('\n');
+}
+
+function subcommandHelp(subcommand: string): string {
+  if (subcommand === 'list') {
+    return [
+      'forgeax-engine-remote-state list - list all registered state tokens',
+      '',
+      'Usage:',
+      '  forgeax-engine-remote-state list',
+      '',
+      'Output format: one line per token:',
+      '  <tokenName>: <current> (previous: <previous>, default: <default>, variants: <v1>, <v2>, ...)',
+      '',
+      'Examples:',
+      '  forgeax-engine-remote-state list',
+      '',
+    ].join('\n');
+  }
+  if (subcommand === 'get') {
+    return [
+      'forgeax-engine-remote-state get - inspect one state token',
+      '',
+      'Usage:',
+      '  forgeax-engine-remote-state get <tokenName>',
+      '',
+      'Output: current / previous / default variant, the full variants list,',
+      'and the count of ScopedTo entities currently scoped to each variant.',
+      '',
+      'Examples:',
+      '  forgeax-engine-remote-state get LevelId',
+      '  #   current:  main-menu',
+      '  #   previous: main-menu',
+      '  #   default:  main-menu',
+      '  #   variants: main-menu (0), tutorial (0), street-a (0)',
+      '',
+    ].join('\n');
+  }
+  return helpBody();
+}
+
+// ─── Subcommand impl ────────────────────────────────────────────────────────
+
+function runList(world: World, stdout: (line: string) => void): void {
+  const tokens = getRegisteredTokens();
+  if (tokens.size === 0) {
+    stdout('(no state tokens registered)');
+    return;
+  }
+  for (const [, token] of tokens) {
+    const current = getCurrentStateString(world, token);
+    const previous = getPreviousStateString(world, token);
+    const variantsStr = (token.variants as readonly string[]).join(', ');
+    stdout(
+      `${token.name}: ${current} (previous: ${previous}, default: ${token.defaultValue}, variants: ${variantsStr})`,
+    );
+  }
+}
+
+function runGet(
+  world: World,
+  tokenName: string,
+  stdout: (line: string) => void,
+  stderr: (line: string) => void,
+): number {
+  const tokens = getRegisteredTokens();
+  const token = tokens.get(tokenName);
+  if (token === undefined) {
+    stderr(
+      [
+        `forgeax: unknown state token "${tokenName}"`,
+        `  expected: one of ${[...tokens.keys()].map((k) => `"${k}"`).join(', ') || '(none registered)'}`,
+        "  hint:     use 'forgeax-engine-remote-state list' to see registered tokens",
+      ].join('\n'),
+    );
+    return 1;
+  }
+
+  const result = getState(world, token);
+  if (!result.ok) {
+    stderr(
+      [
+        `forgeax: ${result.error.code}`,
+        `  expected: ${result.error.expected}`,
+        `  hint:     ${result.error.hint}`,
+      ].join('\n'),
+    );
+    return 1;
+  }
+
+  const previous = getPreviousStateString(world, token);
+  const counts = countScopedEntitiesByVariant(world, token);
+  const variantsLine = (token.variants as readonly string[])
+    .map((v, i) => `${v} (${counts[i] ?? 0})`)
+    .join(', ');
+
+  stdout(`current:  ${result.value}`);
+  stdout(`previous: ${previous}`);
+  stdout(`default:  ${token.defaultValue}`);
+  stdout(`variants: ${variantsLine}`);
+  return 0;
+}
+
+function getCurrentStateString(world: World, token: StateToken): string {
+  const result = getState(world, token);
+  if (result.ok) return result.value;
+  return '<error>';
+}
+
+function getPreviousStateString(world: World, token: StateToken): string {
+  const result = getPreviousState(world, token);
+  if (result.ok) return result.value;
+  return '<error>';
+}
+
+// ─── Dispatch (test-injectable) ─────────────────────────────────────────────
+
+export async function dispatch(opts: DispatchOptions): Promise<number> {
+  const { argv, stdoutWrite, stderrWrite, world } = opts;
+  // argv[0] = node, argv[1] = script path; subcommand starts at argv[2].
+  const args = argv.slice(2);
+  const subcommand = args[0];
+
+  if (subcommand === undefined) {
+    stderrWrite('forgeax: expected subcommand (list or get); use --help for usage');
+    return 1;
+  }
+
+  if (subcommand === '--help' || subcommand === '-h') {
+    stdoutWrite(helpBody());
+    return 0;
+  }
+
+  if (subcommand === 'list') {
+    const listArgs = args.slice(1);
+    if (listArgs[0] === '--help' || listArgs[0] === '-h') {
+      stdoutWrite(subcommandHelp('list'));
+      return 0;
+    }
+    runList(world, stdoutWrite);
+    return 0;
+  }
+
+  if (subcommand === 'get') {
+    const getArgs = args.slice(1);
+    if (getArgs[0] === '--help' || getArgs[0] === '-h') {
+      stdoutWrite(subcommandHelp('get'));
+      return 0;
+    }
+    const tokenName = getArgs[0];
+    if (tokenName === undefined) {
+      stderrWrite(
+        [
+          'forgeax: state get requires a <tokenName> positional argument',
+          '  expected: forgeax-engine-remote-state get <tokenName>',
+          "  hint:     use 'forgeax-engine-remote-state list' to see registered tokens",
+        ].join('\n'),
+      );
+      return 1;
+    }
+    return runGet(world, tokenName, stdoutWrite, stderrWrite);
+  }
+
+  stderrWrite(
+    [
+      `forgeax: unknown subcommand "${subcommand}"`,
+      '  expected: list or get',
+      "  hint:     run 'forgeax-engine-remote-state --help' for usage",
+    ].join('\n'),
+  );
+  return 1;
+}

package/src/conditions.ts

@@ -0,0 +1,60 @@
+// @forgeax/engine-state -- run conditions (feat-20260618 M3 / w25)
+//
+// inState(token, variant) returns a (world: World) => boolean predicate
+// suitable for SystemDescriptor.runIf. The predicate reads the state token's
+// current value from the World resource store.
+//
+// Decision anchors:
+// - requirements section "inState factory" -- single factory, no and/or/not
+//   combiners (OOS-7); returns (world) => boolean
+// - research Finding 3 -- reuse stateResourceKey + hasResource + getResource<number>
+// - plan-strategy D-8 -- runIf receives World, inState returns the predicate
+
+import type { World } from '@forgeax/engine-ecs';
+import type { StateToken } from './define-state';
+import { stateResourceKey } from './resources';
+
+/**
+ * Create a run-condition predicate that passes when the state machine
+ * identified by `token` is in the given `variant`.
+ *
+ * The predicate reads the current state index from the World resource store
+ * (keyed by {@link stateResourceKey}) and compares it against the variant's
+ * index in `token.nameToIdx`.
+ *
+ * If the state resource has not been inserted yet (state not activated), the
+ * predicate returns `false` -- the system is skipped silently.
+ *
+ * @example
+ * ```ts
+ * const GameState = defineState('GameState', ['Menu', 'Playing', 'Paused'] as const);
+ *
+ * const S = defineSystem({
+ *   name: 'gameplay',
+ *   queries: [{ with: [Transform] }],
+ *   runIf: inState(GameState, 'Playing'),
+ *   fn: (world, queryResults, commands) => { ... },
+ * });
+ * ```
+ *
+ * @param token - The state token returned by {@link defineState}.
+ * @param variant - The variant name to check against (must be a member of token.variants).
+ * @returns A predicate `(world: World) => boolean` suitable for `SystemDescriptor.runIf`.
+ */
+export function inState(token: StateToken, variant: string): (world: World) => boolean {
+  const key = stateResourceKey(token);
+  const expectedIdx = token.nameToIdx.get(variant);
+  // If the variant string is not in the token's vocabulary, the predicate
+  // always returns false -- the system will never run. This is a programmer
+  // error (typo in variant name) but we don't throw at definition time
+  // because the predicate is a closure evaluated each frame; a throw here
+  // would kill the entire schedule.
+  if (expectedIdx === undefined) {
+    return (_world: World) => false;
+  }
+  return (world: World) => {
+    if (!world.hasResource(key)) return false;
+    const currentIdx = world.getResource<number>(key);
+    return currentIdx === expectedIdx;
+  };
+}

package/src/define-state.ts

@@ -0,0 +1,158 @@
+// @forgeax/engine-state -- defineState + StateToken SSOT (feat-20260616 M1 / m1w2)
+//
+// Module-level state registration: defineState(name, variants as const) returns a
+// branded StateToken. The token holds the variants vocabulary (name <-> idx lookup)
+// and is used both as a compile-time type witness and as a runtime key for Resource
+// registration.
+//
+// Decision anchors:
+// - plan-strategy D-1: variants vocabulary lives in StateToken, not in ECS types
+// - plan-strategy D-4: defineState throws on programmer errors (duplicate name / empty variants)
+// - plan-strategy sec 8.1: as const + readonly tuple for compile-time variant narrowing
+// - defineState registers schemas at module level; active state plugins project them into Worlds
+
+import { throwStateError } from './errors';
+
+/**
+ * Opaque branded type for type-level state-machine tokens.
+ *
+ * Use {@link defineState} to create a token; never construct manually.
+ * The {@link __forgeaxState} brand prevents plain-object assignment and
+ * enables TypeScript narrowing of variant literal types.
+ *
+ * @typeParam Name - The string literal name of the state machine.
+ * @typeParam V - The union of variant string literals derived from the const tuple.
+ */
+export interface StateToken<Name extends string = string, V extends string = string> {
+  /** Brand -- prevents structural compatibility with plain objects. */
+  readonly __forgeaxState: typeof FORGEAX_STATE_BRAND;
+  /** The user-supplied state-machine name. */
+  readonly name: Name;
+  /** The ordered, read-only variants tuple. */
+  readonly variants: readonly V[];
+  /** Fast lookup: variant string -> its zero-based index in `variants`. */
+  readonly nameToIdx: ReadonlyMap<V, number>;
+  /** Convenience: `variants[0]`, the default / initial state value. */
+  readonly defaultValue: V;
+}
+
+/**
+ * Brand symbol for {@link StateToken}. Declared (not runtime-initialised) so
+ * the token interface carries nominal identity without a runtime allocation.
+ */
+declare const FORGEAX_STATE_BRAND: unique symbol;
+
+/**
+ * Extract the variant union from a {@link StateToken}.
+ *
+ * ```ts
+ * const L = defineState('LevelId', ['menu', 'game'] as const);
+ * type LevelVariant = StateTokenVariant<typeof L>;
+ * //   ^? 'menu' | 'game'
+ * ```
+ */
+export type StateTokenVariant<T extends StateToken> =
+  T extends StateToken<infer _Name, infer V> ? V : never;
+
+/**
+ * Extract the name literal from a {@link StateToken}.
+ */
+export type StateTokenName<T extends StateToken> =
+  T extends StateToken<infer Name, infer _V> ? Name : never;
+
+/**
+ * Global registry of all state tokens, keyed by token name.
+ *
+ * `defineState` writes here; active state plugins project it into Worlds;
+ * cli-state reflection also reads it.
+ */
+const STATE_REGISTRY = new Map<string, StateToken>();
+const STATE_DEFINED_LISTENERS = new Set<(token: StateToken) => void>();
+
+/**
+ * Internal: get the read-only snapshot of all registered tokens.
+ * Exported for M2 registerStatesPlugin and M6 cli-state.
+ */
+export function getRegisteredTokens(): ReadonlyMap<string, StateToken> {
+  return STATE_REGISTRY;
+}
+
+/** @internal Subscribe one active World adapter to future module-level tokens. */
+export function onStateDefined(listener: (token: StateToken) => void): () => void {
+  STATE_DEFINED_LISTENERS.add(listener);
+  return () => STATE_DEFINED_LISTENERS.delete(listener);
+}
+
+/**
+ * Define a typed state machine.
+ *
+ * Must be called at module level. The `as const` assertion on the variants
+ * array enables TypeScript to infer the exact literal tuple type, giving
+ * compile-time narrowing on variant parameters (e.g. `setNextState(world,
+ * token, 'misspell')` is a type error).
+ *
+ * @param name - Unique state-machine identifier (e.g. `'LevelId'`).
+ * @param variants - Readonly tuple of variant string literals. Must be non-empty.
+ * @returns A branded {@link StateToken} for use with `setNextState`, `getState`, etc.
+ * @throws StateError if `name` is already registered or `variants` is empty.
+ *
+ * ```ts
+ * export const LevelId = defineState('LevelId', ['main-menu', 'tutorial', 'street-a'] as const);
+ * // LevelId.variants           -> readonly ['main-menu', 'tutorial', 'street-a']
+ * // LevelId.nameToIdx.get('tutorial') -> 1
+ * // LevelId.defaultValue       -> 'main-menu'
+ * ```
+ */
+export function defineState<Name extends string, const Variants extends readonly string[]>(
+  name: Name,
+  variants: Variants,
+): StateToken<Name, Variants[number]> {
+  if (STATE_REGISTRY.has(name)) {
+    throwStateError(
+      'state-already-defined',
+      'Each StateToken name must be registered exactly once at module level',
+      `State "${name}" is already defined. Use the existing token.`,
+      { code: 'state-already-defined', name, firstDefinedAt: undefined },
+    );
+  }
+
+  if (variants.length === 0) {
+    throwStateError(
+      'state-default-required',
+      'defineState requires at least one variant (non-empty array)',
+      `State "${name}" was defined with an empty variants array. Provide at least one variant, e.g. defineState("${name}", ["default"] as const).`,
+      { code: 'state-default-required', name },
+    );
+  }
+
+  // Check for duplicate variants within the array
+  const seen = new Set<string>();
+  for (const v of variants) {
+    if (seen.has(v)) {
+      throwStateError(
+        'state-default-required',
+        'Variants must be unique within a state token',
+        `State "${name}" has duplicate variant "${v}". Each variant must appear exactly once.`,
+        { code: 'state-default-required', name },
+      );
+    }
+    seen.add(v);
+  }
+
+  const nameToIdx = new Map<Variants[number], number>();
+  for (let i = 0; i < variants.length; i++) {
+    nameToIdx.set(variants[i] as Variants[number], i);
+  }
+
+  const token = {
+    __forgeaxState: undefined as unknown as typeof FORGEAX_STATE_BRAND,
+    name,
+    variants,
+    nameToIdx,
+    defaultValue: variants[0] as Variants[number],
+  } as StateToken<Name, Variants[number]>;
+
+  STATE_REGISTRY.set(name, token as unknown as StateToken);
+  for (const listener of STATE_DEFINED_LISTENERS) listener(token as unknown as StateToken);
+  return token;
+}