@forgeax/engine-state 0.0.0-dev.8d955ade1c79

package/src/errors.ts

@@ -0,0 +1,147 @@
+// @forgeax/engine-state -- error model SSOT (feat-20260616-engine-state-and-state-scoped-entities M1 / m1w4)
+//
+// Closed union StateErrorCode (4 members), discriminated detail union,
+// and structured StateError carrying .code / .expected / .hint / .detail.
+//
+// Decision anchors:
+// - plan-strategy D-4: 4-code order-locked closed union + discriminated detail
+// - requirements sec 2.7: error code union, defineState throws (programmer error),
+//   setNextState / getState return Result.err (runtime AI user calls)
+// - AGENTS.md Error model: structured errors with .expected / .hint / .detail,
+//   never throw for runtime paths; exhaustive switch without default
+
+/** {@link state-already-defined} payload: carries the conflicting name and optional first-definition site. */
+export interface StateAlreadyDefinedDetail {
+  readonly code: 'state-already-defined';
+  readonly name: string;
+  readonly firstDefinedAt: string | undefined;
+}
+
+/** {@link state-not-registered} payload: carries the token name that has no plugin registration. */
+export interface StateNotRegisteredDetail {
+  readonly code: 'state-not-registered';
+  readonly name: string;
+}
+
+/** {@link invalid-variant} payload: carries the token name, the invalid variant string, and the valid variants list. */
+export interface InvalidVariantDetail {
+  readonly code: 'invalid-variant';
+  readonly name: string;
+  readonly got: string;
+  readonly valid: readonly string[];
+}
+
+/** {@link state-default-required} payload: carries the token name whose variants array was empty. */
+export interface StateDefaultRequiredDetail {
+  readonly code: 'state-default-required';
+  readonly name: string;
+}
+
+interface StateErrorDetailByCode {
+  'state-already-defined': StateAlreadyDefinedDetail;
+  'state-not-registered': StateNotRegisteredDetail;
+  'invalid-variant': InvalidVariantDetail;
+  'state-default-required': StateDefaultRequiredDetail;
+}
+
+/**
+ * Closed {@link StateErrorCode} union -- 4 members, order-locked.
+ * Exhaustive `switch (err.code)` needs no default fallback.
+ *
+ * | code | trigger |
+ * |:--|:--|
+ * | `'state-already-defined'` | `defineState()` called with a name already registered |
+ * | `'state-not-registered'` | `setNextState()` / `getState()` called before `registerStatesPlugin()` |
+ * | `'invalid-variant'` | `setNextState()` called with a variant string not in the token's variants tuple |
+ * | `'state-default-required'` | `defineState()` called with empty variants array |
+ */
+export type StateErrorCode = keyof StateErrorDetailByCode;
+
+/**
+ * Discriminated detail union for {@link StateError}, narrowed per
+ * `StateError.code`. AI users obtain the concrete shape via
+ * `switch (err.code)` without a fallback `as` cast.
+ */
+export type StateErrorDetail = StateErrorDetailByCode[StateErrorCode];
+
+/**
+ * Structured state-machine error -- four-field surface
+ * (`.code` / `.expected` / `.hint` / `.detail`).
+ *
+ * AI users consume the structured triple by fields, not by parsing `.message`.
+ */
+type StateErrorVariant<C extends StateErrorCode> = {
+  readonly code: C;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: StateErrorDetailByCode[C];
+};
+
+export type StateError = {
+  [C in StateErrorCode]: StateErrorVariant<C>;
+}[StateErrorCode];
+
+function makeError<C extends StateErrorCode>(
+  code: C,
+  expected: string,
+  hint: string,
+  detail: StateErrorDetailByCode[C],
+): StateErrorVariant<C> {
+  const error = {
+    code,
+    expected,
+    hint,
+    detail,
+    get message(): string {
+      return `[${code}] ${hint}`;
+    },
+  };
+  return error;
+}
+
+/** Convenience throw wrapper for programmer errors (defineState constructor phase). */
+export function throwStateError<C extends StateErrorCode>(
+  code: C,
+  expected: string,
+  hint: string,
+  detail: StateErrorDetailByCode[C],
+): never {
+  throw makeError(code, expected, hint, detail);
+}
+
+export function stateAlreadyDefined(name: string, firstDefinedAt?: string): StateError {
+  return makeError(
+    'state-already-defined',
+    'Each StateToken name must be registered exactly once at module level',
+    `State "${name}" is already defined${firstDefinedAt ? ` (first defined at ${firstDefinedAt})` : ''}. Use the existing token.`,
+    { code: 'state-already-defined', name, firstDefinedAt },
+  );
+}
+
+export function stateNotRegistered(name: string): StateError {
+  return makeError(
+    'state-not-registered',
+    'registerStatesPlugin(world) must be called before using setNextState / getState',
+    `State "${name}" has not been registered via registerStatesPlugin. createApp auto-registers the plugin in both canvas and assemble forms.`,
+    { code: 'state-not-registered', name },
+  );
+}
+
+export function invalidVariant(name: string, got: string, valid: readonly string[]): StateError {
+  const validSnapshot = [...valid];
+  return makeError(
+    'invalid-variant',
+    `Variant must be one of: ${validSnapshot.join(', ')}`,
+    `"${got}" is not a valid variant for state "${name}". Did you mean one of: ${validSnapshot.join(', ')}? Check for typos.`,
+    { code: 'invalid-variant', name, got, valid: validSnapshot },
+  );
+}
+
+export function stateDefaultRequired(name: string): StateError {
+  return makeError(
+    '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 },
+  );
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+// @forgeax/engine-state -- public barrel
+//
+// Single-entry surface for typed state definitions, transitions, lifecycle, and inspection.
+
+export { inState } from './conditions';
+export type {
+  StateToken,
+  StateTokenName,
+  StateTokenVariant,
+} from './define-state';
+export { defineState } from './define-state';
+export type {
+  InvalidVariantDetail,
+  StateAlreadyDefinedDetail,
+  StateDefaultRequiredDetail,
+  StateError,
+  StateErrorCode,
+  StateErrorDetail,
+  StateNotRegisteredDetail,
+} from './errors';
+export type {
+  StateCallback,
+  UnsubscribeHandle,
+} from './on-enter-on-exit';
+export {
+  addOnEnter,
+  addOnExit,
+  OnEnter,
+  OnExit,
+} from './on-enter-on-exit';
+export { statePlugin } from './plugin-factory';
+export { registerStatesPlugin, StateSet } from './register-plugin';
+export {
+  despawnOnEnter,
+  despawnOnExit,
+} from './scoped-component';
+export {
+  getPreviousState,
+  getState,
+  setNextState,
+  setNextStateForce,
+} from './set-next-state';

package/src/on-enter-on-exit.ts

@@ -0,0 +1,156 @@
+// @forgeax/engine-state -- OnEnter / OnExit callback registry (M4 / m4w2)
+//
+// OnEnter(token, value) and OnExit(token, value) return branded schedule-label
+// strings (pattern: `${name}__OnEnter__${value}` / `${name}__OnExit__${value}`).
+//
+// addOnEnter(token, variant, fn) / addOnExit(token, variant, fn) push fn into a
+// per-label callback registry and return an unsubscribe handle. The registry is
+// consumed by transitionStatesSystem (m4w4) which dispatches callbacks during
+// state transitions.
+//
+// These labels are NOT ECS schedule labels — they are state-package-internal
+// dispatchers. There is no ECS sub-schedule (research F-5); all dispatch happens
+// inside transitionStatesSystem itself (plan-strategy D-5).
+//
+// Decision anchors:
+// - plan-strategy D-5: fn[] registry + transition body dispatch, zero ECS change
+// - research F-5: ECS has no schedule label / sub-schedule API
+// - requirements F-11: OnEnter/OnExit return schedule labels for user-facing API
+
+import type { World } from '@forgeax/engine-ecs';
+import type { StateToken, StateTokenVariant } from './define-state';
+
+const ON_ENTER_LABEL_PREFIX = '__OnEnter__';
+const ON_EXIT_LABEL_PREFIX = '__OnExit__';
+
+/**
+ * Callback type for OnEnter / OnExit hooks.
+ *
+ * Receives the {@link World} for ECS interaction (e.g. spawning entities,
+ * reading Resources). Callbacks fire synchronously inside transitionStatesSystem.
+ */
+export type StateCallback = (world: World) => void;
+
+/**
+ * Unsubscribe handle returned by {@link addOnEnter} / {@link addOnExit}.
+ * Call to remove the callback from future dispatch.
+ */
+export type UnsubscribeHandle = () => void;
+
+/**
+ * Internal callback entry: pairs a function with its identity for removal.
+ * The `id` is a unique symbol used as the remove key.
+ */
+interface CallbackEntry {
+  id: symbol;
+  fn: StateCallback;
+}
+
+/**
+ * Module-private callback registry.
+ *
+ * Key: `${tokenName}__OnEnter__${variant}` or `${tokenName}__OnExit__${variant}`
+ * Value: ordered array of callback entries (fired in registration order).
+ */
+const _registry = new Map<string, CallbackEntry[]>();
+
+function makeLabel(tokenName: string, prefix: string, variant: string): string {
+  return `${tokenName}${prefix}${variant}`;
+}
+
+/**
+ * Returns a branded schedule-label string for an OnEnter hook.
+ *
+ * The label is NOT an ECS schedule label. It is consumed internally by
+ * {@link addOnEnter} and dispatched by transitionStatesSystem during state
+ * transition (plan-strategy D-5).
+ *
+ * @param token - The StateToken defining the state machine.
+ * @param variant - The variant whose entry triggers the callback.
+ * @returns A unique label string usable with {@link addOnEnter}.
+ */
+export function OnEnter<T extends StateToken>(token: T, variant: StateTokenVariant<T>): string {
+  return makeLabel(token.name, ON_ENTER_LABEL_PREFIX, variant);
+}
+
+/**
+ * Returns a branded schedule-label string for an OnExit hook.
+ *
+ * @param token - The StateToken defining the state machine.
+ * @param variant - The variant whose exit triggers the callback.
+ * @returns A unique label string usable with {@link addOnExit}.
+ */
+export function OnExit<T extends StateToken>(token: T, variant: StateTokenVariant<T>): string {
+  return makeLabel(token.name, ON_EXIT_LABEL_PREFIX, variant);
+}
+
+/**
+ * Register a callback to fire when `token` transitions into `variant`.
+ *
+ * @param token - The state machine token.
+ * @param variant - The target variant that triggers this callback.
+ * @param fn - The callback to invoke (receives World parameter).
+ * @returns An unsubscribe handle. Call it to remove the callback from future dispatch.
+ */
+export function addOnEnter<T extends StateToken>(
+  token: T,
+  variant: StateTokenVariant<T>,
+  fn: StateCallback,
+): UnsubscribeHandle {
+  const label = OnEnter(token, variant);
+  return _add(label, fn);
+}
+
+/**
+ * Register a callback to fire when `token` transitions away from `variant`.
+ *
+ * @param token - The state machine token.
+ * @param variant - The variant whose exit triggers this callback.
+ * @param fn - The callback to invoke (receives World parameter).
+ * @returns An unsubscribe handle. Call it to remove the callback from future dispatch.
+ */
+export function addOnExit<T extends StateToken>(
+  token: T,
+  variant: StateTokenVariant<T>,
+  fn: StateCallback,
+): UnsubscribeHandle {
+  const label = OnExit(token, variant);
+  return _add(label, fn);
+}
+
+function _add(label: string, fn: StateCallback): UnsubscribeHandle {
+  let entries = _registry.get(label);
+  if (!entries) {
+    entries = [];
+    _registry.set(label, entries);
+  }
+
+  const id = Symbol();
+  entries.push({ id, fn });
+
+  return () => {
+    const list = _registry.get(label);
+    if (!list) return;
+    const idx = list.findIndex((e) => e.id === id);
+    if (idx !== -1) {
+      list.splice(idx, 1);
+    }
+  };
+}
+
+/**
+ * Get all registered callbacks for a given label, in registration order.
+ *
+ * Returns the callbacks as an array of functions. An empty array means no
+ * callbacks are registered for this label. Consumed by transitionStatesSystem
+ * during dispatch (m4w4).
+ *
+ * @param label - An OnEnter or OnExit label string.
+ * @returns Array of callback functions (may be empty).
+ * @internal
+ */
+export function getCallbacks(label: string): StateCallback[] {
+  const entries = _registry.get(label);
+  if (!entries) return [];
+  return entries.map((e) => e.fn);
+}

package/src/plugin-factory.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+
+import { registerStatesPlugin } from './register-plugin';
+
+/**
+ * statePlugin -- registers the state-machine systems + per-token Resources.
+ *
+ * Installs the transition system and projects both current and later
+ * module-defined StateTokens into the injected World.
+ */
+export function statePlugin(): Plugin {
+  return {
+    name: 'state',
+    inject: ['world'],
+    apply(ctx) {
+      ctx.effect(() => registerStatesPlugin(ctx.world), 'state/systems');
+    },
+  };
+}

package/src/register-plugin.ts

@@ -0,0 +1,114 @@
+import { Update } from '@forgeax/engine-ecs';
+// @forgeax/engine-state -- registerStatesPlugin (M2 / m2w2, M3 / m3w4)
+//
+// Idempotent plugin that inserts per-token Resources (State / NextState /
+// PreviousState), pre-registers ScopedTo components, and registers the
+// transitionStatesSystem in the ECS schedule. Called automatically by
+// createApp in both canvas and assemble forms.
+//
+// M3 / m3w4: stub replaced with transitionStatesSystem from transition-system.ts.
+//
+// Decision anchors:
+// - requirements F-9: idempotent, canvas + assemble dual-form auto-wire
+// - plan-strategy D-6: schedule anchors 'input-frame-start-scan' -> 'transitionStates' -> 'propagateTransforms'
+// - plan-strategy D-4: insertResource initial values from token.defaultValue
+
+import { defineSystem, defineSystemSet, type SystemHandle, type World } from '@forgeax/engine-ecs';
+import { getRegisteredTokens, onStateDefined, type StateToken } from './define-state';
+import { nextStateResourceKey, previousStateResourceKey, stateResourceKey } from './resources';
+import { getScopedComponent, registerScopedComponents } from './scoped-component';
+import { transitionStatesSystem } from './transition-system';
+
+/** Schedule anchor: system name for the input frame-start scan (registered by {@link @forgeax/engine-input}). */
+const FRAME_START_SCAN_SYSTEM_NAME = 'input-frame-start-scan' as const;
+
+/** Schedule anchor: system name for the transform-propagation system (registered by {@link @forgeax/engine-runtime}). */
+const PROPAGATE_TRANSFORMS_SYSTEM = 'propagateTransforms' as const;
+
+const TRANSITION_STATES_SYSTEM_NAME = 'transitionStates';
+export const StateSet = defineSystemSet({ name: 'state' });
+const ACTIVE_STATE_RUNTIMES = new WeakSet<World>();
+
+/**
+ * The `transitionStates` system token (M2 — full resource-ification, D-4).
+ *
+ * Module-level `defineSystem` with the real fn body — no closure, no
+ * placeholder. The fn reads `world` from its first parameter (the M1
+ * world-first signature) and delegates to {@link transitionStatesSystem}.
+ * Anchored `after: ['input-frame-start-scan']`, `before: ['propagateTransforms']`
+ * and labelled `'state'` (spec §6.2 label-anchor map).
+ */
+export const TransitionStates: SystemHandle<readonly []> = defineSystem({
+  name: TRANSITION_STATES_SYSTEM_NAME,
+  queries: [],
+  after: [FRAME_START_SCAN_SYSTEM_NAME],
+  before: [PROPAGATE_TRANSFORMS_SYSTEM],
+  fn: transitionStatesSystem,
+});
+
+/**
+ * Register the state-machine plugin on a {@link World}.
+ *
+ * Side effects:
+ * 1. Pre-registers `__scopedTo__<name>` components for all known tokens.
+ * 2. For each globally registered {@link StateToken}: inserts three Resources
+ *    ({@link State} = defaultValue index, {@link NextState} = undefined,
+ *    {@link PreviousState} = defaultValue index).
+ * 3. Registers the {@link TransitionStates} system in the schedule.
+ *
+ * Tokens defined after registration are projected immediately. Repeated calls
+ * on the same World are no-ops; the first owner receives the sole disposer.
+ */
+export function registerStatesPlugin(world: World): () => void {
+  if (ACTIVE_STATE_RUNTIMES.has(world)) return () => {};
+
+  const resourceKeys = new Set<string>();
+  const componentLeases = new Map<string, { dispose(): unknown }>();
+  const registerToken = (token: StateToken): void => {
+    registerScopedComponents();
+    const scopedComponent = getScopedComponent(token);
+    if (!componentLeases.has(token.name)) {
+      const lease = world.components.register(scopedComponent);
+      if (!lease.ok) throw lease.error;
+      componentLeases.set(token.name, lease.value);
+    }
+    const defaultValueIdx = token.nameToIdx.get(token.defaultValue);
+    if (defaultValueIdx === undefined) return;
+
+    const stateKey = stateResourceKey(token);
+    const nextKey = nextStateResourceKey(token);
+    const previousKey = previousStateResourceKey(token);
+    if (world.hasResource(stateKey)) return;
+    resourceKeys.add(stateKey);
+    resourceKeys.add(nextKey);
+    resourceKeys.add(previousKey);
+    world.insertResource(stateKey, defaultValueIdx);
+    world.insertResource(nextKey, undefined as { value: number; force: boolean } | undefined);
+    world.insertResource(previousKey, defaultValueIdx);
+  };
+
+  for (const token of getRegisteredTokens().values()) registerToken(token);
+  const installed = world.addSystems(Update, StateSet, [TransitionStates]);
+  if (!installed.ok) {
+    for (const key of resourceKeys) {
+      world.removeResource(key);
+    }
+    throw installed.error;
+  }
+  const unsubscribe = onStateDefined(registerToken);
+  ACTIVE_STATE_RUNTIMES.add(world);
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    unsubscribe();
+    ACTIVE_STATE_RUNTIMES.delete(world);
+    world.removeSystem(Update, TRANSITION_STATES_SYSTEM_NAME);
+    for (const key of resourceKeys) {
+      world.removeResource(key);
+    }
+    for (const lease of componentLeases.values()) {
+      lease.dispose();
+    }
+  };
+}

package/src/resources.ts

@@ -0,0 +1,45 @@
+// @forgeax/engine-state -- Resource key constructors (feat-20260616 M1 / m1w2)
+//
+// Three Resource keys per StateToken: State (current value), NextState (pending
+// transition request), PreviousState (cached last-frame value for OnExit / getPreviousState).
+//
+// Decision anchors:
+// - plan-strategy D-1: Resources are per-token, keyed by __state__ prefix
+// - plan-strategy D-4: keys are pure string constructors; Resource CRUD is in registerStatesPlugin M2
+// - requirements F-4/F-5/F-6: State / NextState / PreviousState as Resources
+
+import type { StateToken } from './define-state';
+
+const STATE_PREFIX = '__state__';
+const NEXT_STATE_PREFIX = '__nextState__';
+const PREVIOUS_STATE_PREFIX = '__previousState__';
+
+/**
+ * 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 function stateResourceKey(token: StateToken): string {
+  return `${STATE_PREFIX}${token.name}`;
+}
+
+/**
+ * Resource key for the pending next-state transition request.
+ *
+ * Written by `setNextState` / `setNextStateForce` (M2); consumed by
+ * `transitionStatesSystem` (M3).
+ */
+export function nextStateResourceKey(token: StateToken): string {
+  return `${NEXT_STATE_PREFIX}${token.name}`;
+}
+
+/**
+ * Resource key for the previous-frame state value.
+ *
+ * Written by `transitionStatesSystem` before flipping `State`; read by
+ * `getPreviousState(world, token)` (M2).
+ */
+export function previousStateResourceKey(token: StateToken): string {
+  return `${PREVIOUS_STATE_PREFIX}${token.name}`;
+}

package/src/scoped-component.ts

@@ -0,0 +1,159 @@
+// @forgeax/engine-state -- ScopedTo components + despawnOnExit/Enter (M3 / m3w2)
+//
+// Per-token __scopedTo__<name> components: defineComponent with two enum fields
+// (value = u32 variant index, mode = exit/enter enum). Components are lazily
+// created on first use via getOrCreateScopedComponent.
+//
+// despawnOnExit / despawnOnEnter are free functions that add the corresponding
+// ScopedTo component to an entity. On duplicate add the ECS returns
+// ComponentAlreadyPresentError, which we throw.
+//
+// Decision anchors:
+// - plan-strategy D-1: value field uses 'enum' (u32 index into token.variants)
+// - requirements F-7/F-8: despawnOnExit/despawnOnEnter free functions
+// - requirements AC-11: duplicate add fail-fast via ECS default exclusive=false
+// - research F-2: 'enum' is already a ScalarFieldType
+
+import { defineComponent, type EntityHandle, type World } from '@forgeax/engine-ecs';
+import type { StateToken, StateTokenVariant } from './define-state';
+import { getRegisteredTokens } from './define-state';
+
+const SCOPED_COMPONENTS = new Map<string, ReturnType<typeof defineComponent>>();
+
+/** Fixed label-to-value map for the ScopedTo `mode` enum field. */
+export const SCOPED_MODE_VALUE = { exit: 0, enter: 1 } as const;
+
+function getOrCreateScopedComponent(token: StateToken): ReturnType<typeof defineComponent> {
+  const existing = SCOPED_COMPONENTS.get(token.name);
+  if (existing) return existing;
+
+  // `value` is the token's variant index — derive its label→index map from
+  // `token.variants` so reflection (describeComponent) can name each variant;
+  // `mode` uses the fixed exit/enter map. Both attach labels to the enum field
+  // (Derive, don't Duplicate: the variant order IS the label source).
+  const valueLabels: Record<string, number> = {};
+  token.variants.forEach((v, i) => {
+    valueLabels[v] = i;
+  });
+
+  const comp = defineComponent(`__scopedTo__${token.name}`, {
+    value: { type: 'enum', default: 0, labels: valueLabels },
+    mode: { type: 'enum', default: SCOPED_MODE_VALUE.exit, labels: SCOPED_MODE_VALUE },
+  });
+  SCOPED_COMPONENTS.set(token.name, comp);
+  return comp;
+}
+
+/** Resolve the world-local ScopedTo token for a state. */
+export function getScopedComponent(token: StateToken): ReturnType<typeof defineComponent> {
+  return getOrCreateScopedComponent(token);
+}
+
+function resolveVariantIndex(token: StateToken, variant: string): number {
+  const idx = token.nameToIdx.get(variant as never);
+  if (idx === undefined) {
+    throw new Error(
+      `Invalid variant "${variant}" for state "${token.name}". Valid: ${token.variants.join(', ')}`,
+    );
+  }
+  return idx;
+}
+
+/**
+ * Mark `entity` to be despawned when `token` leaves `variant`.
+ *
+ * Adds a `__scopedTo__<token.name>` component with mode=exit
+ * and value=<variant index>. When transitionStatesSystem detects
+ * the token transitions away from `variant`, it despawns the entity.
+ *
+ * Throws if `entity` already carries this token's ScopedTo component
+ * (ECS default exclusive=false fail-fast).
+ */
+function addScopedComponent(
+  world: World,
+  entity: EntityHandle,
+  scoped: ReturnType<typeof defineComponent>,
+  value: number,
+  mode: number,
+): ReturnType<typeof world.addComponent> {
+  return world.addComponent(entity, {
+    component: scoped,
+    // generic ComponentSchema loses the concrete {value, mode} enum-field
+    // types; data is u32 at runtime.
+    data: { value, mode } as Record<string, unknown> as Parameters<
+      typeof world.addComponent
+    >[1]['data'],
+  });
+}
+
+export function despawnOnExit<T extends StateToken>(
+  world: World,
+  entity: EntityHandle,
+  token: T,
+  variant: StateTokenVariant<T>,
+): void {
+  const idx = resolveVariantIndex(token, variant);
+  const scoped = getOrCreateScopedComponent(token);
+  const result = addScopedComponent(world, entity, scoped, idx, SCOPED_MODE_VALUE.exit);
+  if (!result.ok) {
+    throw result.error;
+  }
+}
+
+/**
+ * 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 function despawnOnEnter<T extends StateToken>(
+  world: World,
+  entity: EntityHandle,
+  token: T,
+  variant: StateTokenVariant<T>,
+): void {
+  const idx = resolveVariantIndex(token, variant);
+  const scoped = getOrCreateScopedComponent(token);
+  const result = addScopedComponent(world, entity, scoped, idx, SCOPED_MODE_VALUE.enter);
+  if (!result.ok) {
+    throw result.error;
+  }
+}
+
+/**
+ * Pre-register scoped components for all state tokens in the global registry.
+ * Called by registerStatesPlugin during boot; idempotent.
+ *
+ * @internal
+ */
+export function registerScopedComponents(): void {
+  for (const token of getRegisteredTokens().values()) {
+    getOrCreateScopedComponent(token);
+  }
+}
+
+/**
+ * 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 function countScopedEntitiesByVariant(world: World, token: StateToken): number[] {
+  const counts = new Array<number>(token.variants.length).fill(0);
+  const scoped = getOrCreateScopedComponent(token);
+  const query = world.query({ read: [scoped] }).unwrap();
+  for (const row of query) {
+    const idx = row.get(scoped).value;
+    if (typeof idx !== 'number') continue;
+    if (idx >= 0 && idx < counts.length) counts[idx] = (counts[idx] ?? 0) + 1;
+  }
+  return counts;
+}
+
+// resolveScopedComponent removed — transitionStatesSystem uses the World-local catalog.