@gyral/core 0.3.0 → 0.3.1

package/dist/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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","sourcesContent":["// Shared state: stores as \"props from the side\" (docs/design-docs/0013-shared-state.md).\n// A store is MVI without a view: init + pure update, commands run by its own interpreter.\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { DEVTOOLS_ENABLED, devCommands, devStore } from '#devtools';\nimport {\n  splitNext,\n  type AnyDriver,\n  type Command,\n  type DriverOverrides,\n  type Next,\n} from './command.js';\nimport { features, type LocalHost } from './features.js';\nimport { makeInterpreter, type Interpreter } from './internal/interpreter.js';\nimport { bindStores } from './store-binding.js';\nimport type { IntentRejected, Tagged } from './types.js';\n\n/** No DOM means a server render: store commands never run there (ADR 0012). */\nconst onServer = typeof document === 'undefined';\n\ntype Variant<M extends Tagged, K extends M['_tag']> = Extract<M, { readonly _tag: K }>;\n\n/** One pure reducer per message tag, like a component's `update` but without context. */\nexport type StoreUpdate<S, M extends Tagged> = {\n  readonly [K in M['_tag']]: (state: S, msg: Variant<M, K>) => Next<S, M>;\n};\n\nexport interface StoreSpec<S, M extends Tagged> {\n  /** Initial state (and optional commands, e.g. load a saved cart). */\n  readonly init: () => Next<S, M>;\n  readonly update: StoreUpdate<S, M>;\n  /** Driver substitutions by name for this store's commands. */\n  readonly drivers?: DriverOverrides;\n  /**\n   * Validates the server's page seed before the client uses it (any synchronous Standard\n   * Schema). An invalid seed is reported with console.error and the store starts from `init`.\n   */\n  readonly schema?: StandardSchemaV1<unknown, S>;\n}\n\n/** The result of checking a seed against a store's schema. */\nexport type SeedCheck<S> =\n  | { readonly ok: true; readonly state: S }\n  | { readonly ok: false; readonly issues: readonly string[] };\n\n/** What `ctx.read()` accepts: anything that names a store and carries its state type. */\nexport interface StoreRef<S> {\n  readonly name: string;\n  /** Type-only marker for the state type. Never set at runtime. */\n  readonly stateType?: (state: S) => S;\n}\n\n/** A live store: one per page on the client, one per request on the server, one per test. */\nexport interface StoreInstance<S, M extends Tagged> {\n  readonly store: Store<S, M>;\n  readonly state: S;\n  /** Feeds a message through the store's `update` and notifies subscribers on change. */\n  send(msg: M): void;\n  /** Called after every state change. Returns an unsubscribe function. */\n  subscribe(listener: (state: S, prev: S) => void): () => void;\n  /** Per-instance driver substitutions (test fakes). Checked before the spec's. */\n  drivers: DriverOverrides;\n  /** Stops running commands and drops subscribers. */\n  dispose(): void;\n  /** Set by the registry that holds the instance (store-to-store `send`). */\n  bindScope(resolve: StoreResolver): void;\n}\n\nexport interface Store<S, M extends Tagged> extends StoreRef<S> {\n  readonly spec: StoreSpec<S, M>;\n  /**\n   * A fresh, independent instance. `initial` skips `init`'s state (a server seed, a test\n   * fixture); `init`'s commands still run on the client.\n   */\n  instance(initial?: S): StoreInstance<S, M>;\n  /** Checks a seed with `spec.schema` (ok as-is without one). */\n  checkSeed(seed: unknown): SeedCheck<S>;\n  /** Type-only marker for the message type. Never set at runtime. */\n  readonly messageType?: (msg: M) => M;\n}\n\n/** Any store, with its types erased (for declarations and registries). */\nexport interface AnyStore {\n  readonly name: string;\n  instance(initial?: never): AnyStoreInstance;\n  checkSeed(seed: unknown): SeedCheck<unknown>;\n}\n\n/** Any store instance, with its types erased. */\nexport interface AnyStoreInstance {\n  readonly store: AnyStore;\n  readonly state: unknown;\n  send(msg: never): void;\n  subscribe(listener: (state: unknown, prev: unknown) => void): () => void;\n  dispose(): void;\n  /**\n   * Called by the registry that holds this instance, so the store's `send(other, msg)`\n   * commands reach `other`'s instance in the same scope (gyral-czi.20).\n   */\n  bindScope?(resolve: StoreResolver): void;\n}\n\n/** Finds a store's instance in a scope (a registry). */\nexport type StoreResolver = (store: AnyStore) => AnyStoreInstance;\n\n/** Store instances substituted by store name (tests, islands). */\nexport type StoreOverrides = Readonly<Record<string, AnyStoreInstance>>;\n\n/** Defines a store. `name` keys it in registries, seeds and overrides, so keep it unique. */\nexport function defineStore<S, M extends Tagged>(name: string, spec: StoreSpec<S, M>): Store<S, M> {\n  features.stores = bindStores; // components can use stores now (features.ts)\n  const store: Store<S, M> = {\n    name,\n    spec,\n    instance: (initial?: S) => createInstance(store, initial),\n    checkSeed: (seed) => checkSeed(spec.schema, seed),\n  };\n  return store;\n}\n\nconst issuePath = (issue: StandardSchemaV1.Issue): string =>\n  (issue.path ?? []).map((s) => String(typeof s === 'object' ? s.key : s)).join('.');\n\nfunction checkSeed<S>(\n  schema: StandardSchemaV1<unknown, S> | undefined,\n  seed: unknown,\n): SeedCheck<S> {\n  // Sound without a schema: the seed is this store's state, serialized by the server.\n  if (schema === undefined) return { ok: true, state: seed as S };\n  const result = schema['~standard'].validate(seed);\n  if (result instanceof Promise) {\n    return { ok: false, issues: ['the store schema is async; seeds need a synchronous schema'] };\n  }\n  if (result.issues === undefined) return { ok: true, state: result.value };\n  return {\n    ok: false,\n    issues: result.issues.map((i) => `${issuePath(i) || '(root)'}: ${i.message}`),\n  };\n}\n\nfunction createInstance<S, M extends Tagged>(\n  store: Store<S, M>,\n  initial: S | undefined,\n): StoreInstance<S, M> {\n  // Sound: send() only calls the reducer whose key equals msg._tag.\n  const reducers = store.spec.update as unknown as Readonly<\n    Record<string, ((state: S, msg: M) => Next<S, M>) | undefined>\n  >;\n  const listeners = new Set<(state: S, prev: S) => void>();\n  let interpreter: Interpreter<M | IntentRejected> | undefined;\n  let disposed = false;\n\n  const [initState, initCommands] = splitNext(store.spec.init());\n  let state = initial === undefined ? initState : initial;\n\n  const resolve = (driver: AnyDriver): AnyDriver =>\n    instance.drivers[driver.name] ?? store.spec.drivers?.[driver.name] ?? driver;\n\n  let scope: StoreResolver | undefined;\n\n  // Store-to-store writes: delivered synchronously to the other store's instance in scope.\n  const deliver = ({ store: target, msg }: StoreSendInput): void => {\n    if (scope === undefined) {\n      console.warn(\n        `store \"${store.name}\" sends to \"${target.name}\" but is not held by a store scope ` +\n          '(a registry, <gyral-stores> or the page default), so the message is dropped.',\n      );\n      return;\n    }\n    (scope(target) as { send(msg: unknown): void }).send(msg);\n  };\n\n  const run = (commands: ReadonlyArray<Command<M | IntentRejected>>): void => {\n    if (onServer || disposed || commands.length === 0) return; // never on the server (ADR 0012)\n    for (const cmd of commands) {\n      if (cmd.driver === STORE_SEND) {\n        deliver(cmd.input as StoreSendInput);\n        continue;\n      }\n      interpreter ??= makeInterpreter<M | IntentRejected>(\n        resolve,\n        (msg) => {\n          // Stores have no IntentRejected reducer; only their own messages apply.\n          if (msg._tag !== 'IntentRejected') instance.send(msg as M);\n        },\n        DEVTOOLS_ENABLED ? devCommands(() => `store:${store.name}`) : undefined,\n      );\n      interpreter.run(cmd);\n    }\n  };\n\n  const instance: StoreInstance<S, M> = {\n    store,\n    get state() {\n      return state;\n    },\n    drivers: {},\n    send(msg) {\n      const reducer = reducers[msg._tag];\n      if (reducer === undefined) {\n        console.warn(`store \"${store.name}\" has no update for message \"${msg._tag}\".`);\n        return;\n      }\n      const prev = state;\n      const [next, commands] = splitNext(reducer(prev, msg));\n      state = next;\n      if (DEVTOOLS_ENABLED) devStore(store.name, msg, prev, next);\n      if (!Object.is(next, prev)) for (const listener of [...listeners]) listener(next, prev);\n      run(commands);\n    },\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    dispose() {\n      disposed = true;\n      interpreter?.dispose();\n      listeners.clear();\n    },\n    bindScope(resolver) {\n      scope = resolver;\n    },\n  };\n\n  // A seeded instance (hydration) starts init's commands after the hydrating renders flushed,\n  // so a fast driver can't change state under them (same reason as ADR 0012 for components).\n  if (initial === undefined) run(initCommands);\n  else if (initCommands.length > 0)\n    setTimeout(() => {\n      run(initCommands);\n    }, 0);\n  return instance;\n}\n\n/** Marker driver for `send()`: `define()` delivers these to the resolved store instance. */\nexport const STORE_SEND = {\n  name: '@gyral/store-send',\n  run: () => undefined,\n  /** A component's send: delivered to its instance of the store (features.ts). */\n  local: (host: LocalHost, input: unknown) => {\n    host.stores().send(input as StoreSendInput);\n  },\n} as const;\n\n/** The input of a `send()` command. */\nexport interface StoreSendInput {\n  readonly store: AnyStore;\n  readonly msg: Tagged;\n}\n\n/** A command that sends `msg` to the component's instance of `store`. Writes are commands. */\n// NoInfer: the store decides the message type, so a literal (`{ _tag: 'Track', … }`) is checked\n// against it instead of widening `_tag` to string (store-to-store sends have no other context).\nexport function send<S, M extends Tagged>(store: Store<S, M>, msg: NoInfer<M>): Command<never> {\n  const input: StoreSendInput = { store, msg };\n  return { driver: STORE_SEND, input, onSuccess: () => undefined };\n}\n\n/** Framework message: a store this component reads changed (ADR 0013). Optional reducer. */\nexport interface StoreChanged {\n  readonly _tag: 'StoreChanged';\n  /** The store's name. Narrow with `changed(store, msg)`. */\n  readonly store: string;\n  readonly state: unknown;\n  readonly prev: unknown;\n}\n\n/** Narrows a `StoreChanged` message to one store's typed state, or `undefined`. */\nexport function changed<S>(\n  store: StoreRef<S>,\n  msg: StoreChanged,\n): { readonly state: S; readonly prev: S } | undefined {\n  // Sound: the message was built from this store's instance (matched by unique name).\n  return msg.store === store.name ? { state: msg.state as S, prev: msg.prev as S } : undefined;\n}\n"]}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EACL,SAAS,GAKV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAkB,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,eAAe,EAAoB,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,+EAA+E;AAC/E,MAAM,QAAQ,GAAG,OAAO,QAAQ,KAAK,WAAW,CAAC;AA0FjD,6FAA6F;AAC7F,MAAM,UAAU,WAAW,CAAsB,IAAY,EAAE,IAAqB;IAClF,QAAQ,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC,8CAA8C;IAC5E,MAAM,KAAK,GAAgB;QACzB,IAAI;QACJ,IAAI;QACJ,QAAQ,EAAE,CAAC,OAAW,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC;QACzD,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;KAClD,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,SAAS,GAAG,CAAC,KAA6B,EAAU,EAAE,CAC1D,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAErF,SAAS,SAAS,CAChB,MAAgD,EAChD,IAAa;IAEb,oFAAoF;IACpF,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAS,EAAE,CAAC;IAChE,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAClD,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;QAC9B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,4DAA4D,CAAC,EAAE,CAAC;IAC/F,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;IAC1E,OAAO;QACL,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;KAC9E,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CACrB,KAAkB,EAClB,OAAsB;IAEtB,kEAAkE;IAClE,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,MAE3B,CAAC;IACF,MAAM,SAAS,GAAG,IAAI,GAAG,EAA+B,CAAC;IACzD,IAAI,WAAwD,CAAC;IAC7D,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/D,IAAI,KAAK,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;IAExD,MAAM,OAAO,GAAG,CAAC,MAAiB,EAAa,EAAE,CAC/C,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC;IAE/E,IAAI,KAAgC,CAAC;IAErC,yFAAyF;IACzF,MAAM,OAAO,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAkB,EAAQ,EAAE;QAC/D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YACnD,OAAO;QACT,CAAC;QACA,KAAK,CAAC,MAAM,CAAkC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5D,CAAC,CAAC;IAEF,MAAM,GAAG,GAAG,CAAC,QAAoD,EAAQ,EAAE;QACzE,IAAI,QAAQ,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,iCAAiC;QAC5F,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC9B,OAAO,CAAC,GAAG,CAAC,KAAuB,CAAC,CAAC;gBACrC,SAAS;YACX,CAAC;YACD,WAAW,KAAK,eAAe,CAC7B,OAAO,EACP,CAAC,GAAG,EAAE,EAAE;gBACN,wEAAwE;gBACxE,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB;oBAAE,QAAQ,CAAC,IAAI,CAAC,GAAQ,CAAC,CAAC;YAC7D,CAAC,EACD,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,SAAS,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,EACvE,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;gBACtB,MAAM,KAAK,GAAG,UAAU,KAAK,CAAC,IAAI,GAAG,CAAC;gBACtC,MAAM,IAAI,GACR,IAAI,KAAK,EAAE;oBACT,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC;oBAC5B,CAAC,CAAC,IAAI,KAAK,EAAE;wBACX,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC;wBAC5B,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;gBACnC,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;YAChD,CAAC,CACF,CAAC;YACF,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAwB;QACpC,KAAK;QACL,IAAI,KAAK;YACP,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,EAAE,EAAE;QACX,IAAI,CAAC,GAAG;YACN,YAAY,EAAE,CAAC,CAAC,qDAAqD;YACrE,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;gBAChD,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,KAAK,CAAC;YACnB,IAAI,MAAkB,CAAC;YACvB,IAAI,CAAC;gBACH,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC9B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,0DAA0D;gBAC1D,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC3E,OAAO;YACT,CAAC;YACD,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YAC3C,KAAK,GAAG,IAAI,CAAC;YACb,IAAI,gBAAgB;gBAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAC5D,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;gBAC3B,wFAAwF;gBACxF,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;oBACtC,IAAI,CAAC;wBACH,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;oBACvB,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;oBACnE,CAAC;gBACH,CAAC;YACH,CAAC;YACD,GAAG,CAAC,QAAQ,CAAC,CAAC;QAChB,CAAC;QACD,SAAS,CAAC,QAAQ;YAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO;YACL,QAAQ,GAAG,IAAI,CAAC;YAChB,WAAW,EAAE,OAAO,EAAE,CAAC;YACvB,SAAS,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;QACD,SAAS,CAAC,QAAQ;YAChB,KAAK,GAAG,QAAQ,CAAC;QACnB,CAAC;KACF,CAAC;IAEF,4FAA4F;IAC5F,2FAA2F;IAC3F,IAAI,OAAO,KAAK,SAAS;QAAE,GAAG,CAAC,YAAY,CAAC,CAAC;SACxC,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;QAC9B,UAAU,CAAC,GAAG,EAAE;YACd,GAAG,CAAC,YAAY,CAAC,CAAC;QACpB,CAAC,EAAE,CAAC,CAAC,CAAC;IACR,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,4FAA4F;AAC5F,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,mBAAmB;IACzB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;IACpB,gFAAgF;IAChF,KAAK,EAAE,CAAC,IAAe,EAAE,KAAc,EAAE,EAAE;QACzC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,KAAuB,CAAC,CAAC;IAC9C,CAAC;CACO,CAAC;AAQX,8FAA8F;AAC9F,gGAAgG;AAChG,gGAAgG;AAChG,MAAM,UAAU,IAAI,CAAsB,KAAkB,EAAE,GAAe;IAC3E,MAAM,KAAK,GAAmB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAC7C,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AACnE,CAAC;AAWD,mFAAmF;AACnF,MAAM,UAAU,OAAO,CACrB,KAAkB,EAClB,GAAiB;IAEjB,oFAAoF;IACpF,OAAO,GAAG,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAU,EAAE,IAAI,EAAE,GAAG,CAAC,IAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/F,CAAC","sourcesContent":["// Shared state: stores as \"props from the side\" (docs/design-docs/0013-shared-state.md).\n// A store is MVI without a view: init + pure update, commands run by its own interpreter.\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { DEVTOOLS_ENABLED, devCommands, devStore } from '#devtools';\nimport {\n  splitNext,\n  type AnyDriver,\n  type Command,\n  type DriverOverrides,\n  type Next,\n} from './command.js';\nimport { fail } from './errors.js';\nimport { features, type LocalHost } from './features.js';\nimport { makeInterpreter, type Interpreter } from './internal/interpreter.js';\nimport { noteActivity } from './scheduler.js';\nimport { bindStores } from './store-binding.js';\nimport type { IntentRejected, Tagged } from './types.js';\nimport { message } from './view/index.js';\n\n/** No DOM means a server render: store commands never run there (ADR 0012). */\nconst onServer = typeof document === 'undefined';\n\ntype Variant<M extends Tagged, K extends M['_tag']> = Extract<M, { readonly _tag: K }>;\n\n/** One pure reducer per message tag, like a component's `update` but without context. */\nexport type StoreUpdate<S, M extends Tagged> = {\n  readonly [K in M['_tag']]: (state: S, msg: Variant<M, K>) => Next<S, M>;\n};\n\nexport interface StoreSpec<S, M extends Tagged> {\n  /** Initial state (and optional commands, e.g. load a saved cart). */\n  readonly init: () => Next<S, M>;\n  readonly update: StoreUpdate<S, M>;\n  /** Driver substitutions by name for this store's commands. */\n  readonly drivers?: DriverOverrides;\n  /**\n   * Validates the server's page seed before the client uses it (any synchronous Standard\n   * Schema). An invalid seed is reported with console.error and the store starts from `init`.\n   */\n  readonly schema?: StandardSchemaV1<unknown, S>;\n}\n\n/** The result of checking a seed against a store's schema. */\nexport type SeedCheck<S> =\n  | { readonly ok: true; readonly state: S }\n  | { readonly ok: false; readonly issues: readonly string[] };\n\n/** What `ctx.read()` accepts: anything that names a store and carries its state type. */\nexport interface StoreRef<S> {\n  readonly name: string;\n  /** Type-only marker for the state type. Never set at runtime. */\n  readonly stateType?: (state: S) => S;\n}\n\n/** A live store: one per page on the client, one per request on the server, one per test. */\nexport interface StoreInstance<S, M extends Tagged> {\n  readonly store: Store<S, M>;\n  readonly state: S;\n  /** Feeds a message through the store's `update` and notifies subscribers on change. */\n  send(msg: M): void;\n  /** Called after every state change. Returns an unsubscribe function. */\n  subscribe(listener: (state: S, prev: S) => void): () => void;\n  /** Per-instance driver substitutions (test fakes). Checked before the spec's. */\n  drivers: DriverOverrides;\n  /** Stops running commands and drops subscribers. */\n  dispose(): void;\n  /** Set by the registry that holds the instance (store-to-store `send`). */\n  bindScope(resolve: StoreResolver): void;\n}\n\nexport interface Store<S, M extends Tagged> extends StoreRef<S> {\n  readonly spec: StoreSpec<S, M>;\n  /**\n   * A fresh, independent instance. `initial` skips `init`'s state (a server seed, a test\n   * fixture); `init`'s commands still run on the client.\n   */\n  instance(initial?: S): StoreInstance<S, M>;\n  /** Checks a seed with `spec.schema` (ok as-is without one). */\n  checkSeed(seed: unknown): SeedCheck<S>;\n  /** Type-only marker for the message type. Never set at runtime. */\n  readonly messageType?: (msg: M) => M;\n}\n\n/** Any store, with its types erased (for declarations and registries). */\nexport interface AnyStore {\n  readonly name: string;\n  instance(initial?: never): AnyStoreInstance;\n  checkSeed(seed: unknown): SeedCheck<unknown>;\n}\n\n/** Any store instance, with its types erased. */\nexport interface AnyStoreInstance {\n  readonly store: AnyStore;\n  readonly state: unknown;\n  send(msg: never): void;\n  subscribe(listener: (state: unknown, prev: unknown) => void): () => void;\n  dispose(): void;\n  /**\n   * Called by the registry that holds this instance, so the store's `send(other, msg)`\n   * commands reach `other`'s instance in the same scope (gyral-czi.20).\n   */\n  bindScope?(resolve: StoreResolver): void;\n}\n\n/** Finds a store's instance in a scope (a registry). */\nexport type StoreResolver = (store: AnyStore) => AnyStoreInstance;\n\n/** Store instances substituted by store name (tests, islands). */\nexport type StoreOverrides = Readonly<Record<string, AnyStoreInstance>>;\n\n/** Defines a store. `name` keys it in registries, seeds and overrides, so keep it unique. */\nexport function defineStore<S, M extends Tagged>(name: string, spec: StoreSpec<S, M>): Store<S, M> {\n  features.stores = bindStores; // components can use stores now (features.ts)\n  const store: Store<S, M> = {\n    name,\n    spec,\n    instance: (initial?: S) => createInstance(store, initial),\n    checkSeed: (seed) => checkSeed(spec.schema, seed),\n  };\n  return store;\n}\n\nconst issuePath = (issue: StandardSchemaV1.Issue): string =>\n  (issue.path ?? []).map((s) => String(typeof s === 'object' ? s.key : s)).join('.');\n\nfunction checkSeed<S>(\n  schema: StandardSchemaV1<unknown, S> | undefined,\n  seed: unknown,\n): SeedCheck<S> {\n  // Sound without a schema: the seed is this store's state, serialized by the server.\n  if (schema === undefined) return { ok: true, state: seed as S };\n  const result = schema['~standard'].validate(seed);\n  if (result instanceof Promise) {\n    return { ok: false, issues: ['the store schema is async; seeds need a synchronous schema'] };\n  }\n  if (result.issues === undefined) return { ok: true, state: result.value };\n  return {\n    ok: false,\n    issues: result.issues.map((i) => `${issuePath(i) || '(root)'}: ${i.message}`),\n  };\n}\n\nfunction createInstance<S, M extends Tagged>(\n  store: Store<S, M>,\n  initial: S | undefined,\n): StoreInstance<S, M> {\n  // Sound: send() only calls the reducer whose key equals msg._tag.\n  const reducers = store.spec.update as unknown as Readonly<\n    Record<string, ((state: S, msg: M) => Next<S, M>) | undefined>\n  >;\n  const listeners = new Set<(state: S, prev: S) => void>();\n  let interpreter: Interpreter<M | IntentRejected> | undefined;\n  let disposed = false;\n\n  const [initState, initCommands] = splitNext(store.spec.init());\n  let state = initial === undefined ? initState : initial;\n\n  const resolve = (driver: AnyDriver): AnyDriver =>\n    instance.drivers[driver.name] ?? store.spec.drivers?.[driver.name] ?? driver;\n\n  let scope: StoreResolver | undefined;\n\n  // Store-to-store writes: delivered synchronously to the other store's instance in scope.\n  const deliver = ({ store: target, msg }: StoreSendInput): void => {\n    if (scope === undefined) {\n      console.warn(message(54, store.name, target.name));\n      return;\n    }\n    (scope(target) as { send(msg: unknown): void }).send(msg);\n  };\n\n  const run = (commands: ReadonlyArray<Command<M | IntentRejected>>): void => {\n    if (onServer || disposed || commands.length === 0) return; // never on the server (ADR 0012)\n    for (const cmd of commands) {\n      if (cmd.driver === STORE_SEND) {\n        deliver(cmd.input as StoreSendInput);\n        continue;\n      }\n      interpreter ??= makeInterpreter<M | IntentRejected>(\n        resolve,\n        (msg) => {\n          // Stores have no IntentRejected reducer; only their own messages apply.\n          if (msg._tag !== 'IntentRejected') instance.send(msg as M);\n        },\n        DEVTOOLS_ENABLED ? devCommands(() => `store:${store.name}`) : undefined,\n        (cause, code, driver) => {\n          const owner = `store \"${store.name}\"`;\n          const text =\n            code === 40\n              ? message(40, owner, driver)\n              : code === 41\n                ? message(41, owner, driver)\n                : message(43, owner, driver);\n          fail(cause, 'command', text, { msg: driver });\n        },\n      );\n      interpreter.run(cmd);\n    }\n  };\n\n  const instance: StoreInstance<S, M> = {\n    store,\n    get state() {\n      return state;\n    },\n    drivers: {},\n    send(msg) {\n      noteActivity(); // settled() keeps waiting while messages arrive (04)\n      const reducer = reducers[msg._tag];\n      if (reducer === undefined) {\n        console.warn(message(55, store.name, msg._tag));\n        return;\n      }\n      const prev = state;\n      let result: Next<S, M>;\n      try {\n        result = reducer(prev, msg);\n      } catch (cause) {\n        // A store reducer that throws changes nothing (ADR 0024).\n        fail(cause, 'store', message(76, store.name, msg._tag), { msg: msg._tag });\n        return;\n      }\n      const [next, commands] = splitNext(result);\n      state = next;\n      if (DEVTOOLS_ENABLED) devStore(store.name, msg, prev, next);\n      if (!Object.is(next, prev)) {\n        // Each subscriber on its own: one that throws doesn't keep the others stale (ADR 0024).\n        for (const listener of [...listeners]) {\n          try {\n            listener(next, prev);\n          } catch (cause) {\n            fail(cause, 'store', message(77, store.name), { msg: msg._tag });\n          }\n        }\n      }\n      run(commands);\n    },\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    dispose() {\n      disposed = true;\n      interpreter?.dispose();\n      listeners.clear();\n    },\n    bindScope(resolver) {\n      scope = resolver;\n    },\n  };\n\n  // A seeded instance (hydration) starts init's commands after the hydrating renders flushed,\n  // so a fast driver can't change state under them (same reason as ADR 0012 for components).\n  if (initial === undefined) run(initCommands);\n  else if (initCommands.length > 0)\n    setTimeout(() => {\n      run(initCommands);\n    }, 0);\n  return instance;\n}\n\n/** Marker driver for `send()`: `define()` delivers these to the resolved store instance. */\nexport const STORE_SEND = {\n  name: '@gyral/store-send',\n  run: () => undefined,\n  /** A component's send: delivered to its instance of the store (features.ts). */\n  local: (host: LocalHost, input: unknown) => {\n    host.stores().send(input as StoreSendInput);\n  },\n} as const;\n\n/** The input of a `send()` command. */\nexport interface StoreSendInput {\n  readonly store: AnyStore;\n  readonly msg: Tagged;\n}\n\n/** A command that sends `msg` to the component's instance of `store`. Writes are commands. */\n// NoInfer: the store decides the message type, so a literal (`{ _tag: 'Track', … }`) is checked\n// against it instead of widening `_tag` to string (store-to-store sends have no other context).\nexport function send<S, M extends Tagged>(store: Store<S, M>, msg: NoInfer<M>): Command<never> {\n  const input: StoreSendInput = { store, msg };\n  return { driver: STORE_SEND, input, onSuccess: () => undefined };\n}\n\n/** Framework message: a store this component reads changed (ADR 0013). Optional reducer. */\nexport interface StoreChanged {\n  readonly _tag: 'StoreChanged';\n  /** The store's name. Narrow with `changed(store, msg)`. */\n  readonly store: string;\n  readonly state: unknown;\n  readonly prev: unknown;\n}\n\n/** Narrows a `StoreChanged` message to one store's typed state, or `undefined`. */\nexport function changed<S>(\n  store: StoreRef<S>,\n  msg: StoreChanged,\n): { readonly state: S; readonly prev: S } | undefined {\n  // Sound: the message was built from this store's instance (matched by unique name).\n  return msg.store === store.name ? { state: msg.state as S, prev: msg.prev as S } : undefined;\n}\n"]}

package/dist/subscription.d.ts

@@ -0,0 +1,35 @@
+import type { Concurrency, Driver } from './command.js';
+/** How to stop listening: a function, or an object with `unsubscribe()` (RxJS, XState). */
+export type Unsubscribe = (() => void) | {
+    readonly unsubscribe: () => void;
+};
+export interface SubscriptionContext<I> {
+    /** The command's input (a room code, a URL, a store key). */
+    readonly input: I;
+    /** Aborts when the command is switched away or its component disconnects. */
+    readonly signal: AbortSignal;
+    /**
+     * Ends the subscription with an error: the source is released and the command's
+     * `onFailure` gets it. Wrap the driver in `retry()` to subscribe again instead.
+     */
+    readonly fail: (error: unknown) => void;
+}
+/** Driver options a subscription may set. `concurrency` defaults to `'switch'`. */
+export interface SubscriptionOptions<E> {
+    readonly concurrency?: Concurrency;
+    readonly toError?: (cause: unknown) => E;
+}
+/**
+ * A streaming driver over a source Gyral doesn't own. `subscribe` starts listening, calls
+ * `emit` with each value (it may emit the current value at once) and returns how to stop
+ * (a function, or an object with `unsubscribe()`).
+ * The subscription lasts while the command runs; aborting it (lane `switch`, disconnect)
+ * releases the source, and emits after that are ignored. Substitute it by `name` in tests.
+ *
+ *   const cart = subscription<CartState>('cart', (emit) => {
+ *     emit(reduxStore.getState());
+ *     return reduxStore.subscribe(() => emit(reduxStore.getState()));
+ *   });
+ *   // init: [state, [command(cart, undefined, { onSuccess: (c) => ({ _tag: 'Cart', c }) })]]
+ */
+export declare function subscription<O, I = undefined, E = unknown>(name: string, subscribe: (emit: (value: O) => void, ctx: SubscriptionContext<I>) => Unsubscribe, options?: SubscriptionOptions<E>): Driver<I, O, E>;

package/dist/subscription.js

@@ -0,0 +1,74 @@
+import { fail } from './errors.js';
+import { message } from './view/index.js';
+const release = (name, stop) => {
+    if (stop === undefined)
+        return;
+    try {
+        if (typeof stop === 'function')
+            stop();
+        else
+            stop.unsubscribe();
+    }
+    catch (error) {
+        fail(error, 'subscribe', message(42, name), { msg: name });
+    }
+};
+const asError = (reason) => reason instanceof Error ? reason : new DOMException('Aborted', 'AbortError');
+/**
+ * A streaming driver over a source Gyral doesn't own. `subscribe` starts listening, calls
+ * `emit` with each value (it may emit the current value at once) and returns how to stop
+ * (a function, or an object with `unsubscribe()`).
+ * The subscription lasts while the command runs; aborting it (lane `switch`, disconnect)
+ * releases the source, and emits after that are ignored. Substitute it by `name` in tests.
+ *
+ *   const cart = subscription<CartState>('cart', (emit) => {
+ *     emit(reduxStore.getState());
+ *     return reduxStore.subscribe(() => emit(reduxStore.getState()));
+ *   });
+ *   // init: [state, [command(cart, undefined, { onSuccess: (c) => ({ _tag: 'Cart', c }) })]]
+ */
+export function subscription(name, subscribe, options = {}) {
+    return {
+        name,
+        concurrency: 'switch',
+        ...options,
+        run: (input, { signal, emit }) => new Promise((_resolve, reject) => {
+            // `ended` may flip inside subscribe (fail() or an abort), so it lives in an object.
+            const sub = { ended: false };
+            // Deliberately not wrapped in an Error: the driver's toError (or onFailure) sees the
+            // source's own error (a WebSocket's error event, a store's rejection).
+            const end = (error) => {
+                if (sub.ended)
+                    return;
+                sub.ended = true;
+                signal.removeEventListener('abort', onAbort);
+                release(name, sub.stop);
+                // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+                reject(error);
+            };
+            const onAbort = () => {
+                end(asError(signal.reason));
+            };
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener('abort', onAbort, { once: true });
+            try {
+                const stop = subscribe((value) => {
+                    if (!sub.ended)
+                        emit(value);
+                }, { input, signal, fail: end });
+                // fail() or an abort while subscribing ended it before `stop` was known.
+                if (sub.ended)
+                    release(name, stop);
+                else
+                    sub.stop = stop;
+            }
+            catch (error) {
+                end(error);
+            }
+        }),
+    };
+}
+//# sourceMappingURL=subscription.js.map

package/dist/subscription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.js","sourceRoot":"","sources":["../src/subscription.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAuB1C,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,IAA6B,EAAQ,EAAE;IACpE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO;IAC/B,IAAI,CAAC;QACH,IAAI,OAAO,IAAI,KAAK,UAAU;YAAE,IAAI,EAAE,CAAC;;YAClC,IAAI,CAAC,WAAW,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,OAAO,GAAG,CAAC,MAAe,EAAS,EAAE,CACzC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAE/E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,SAAiF,EACjF,UAAkC,EAAE;IAEpC,OAAO;QACL,IAAI;QACJ,WAAW,EAAE,QAAQ;QACrB,GAAG,OAAO;QACV,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAC/B,IAAI,OAAO,CAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;YACtC,oFAAoF;YACpF,MAAM,GAAG,GAA2C,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YACrE,qFAAqF;YACrF,uEAAuE;YACvE,MAAM,GAAG,GAAG,CAAC,KAAc,EAAQ,EAAE;gBACnC,IAAI,GAAG,CAAC,KAAK;oBAAE,OAAO;gBACtB,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC;gBACjB,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC7C,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;gBACxB,2EAA2E;gBAC3E,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC,CAAC;YACF,MAAM,OAAO,GAAG,GAAS,EAAE;gBACzB,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9B,CAAC,CAAC;YACF,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,OAAO,EAAE,CAAC;gBACV,OAAO;YACT,CAAC;YACD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,SAAS,CACpB,CAAC,KAAK,EAAE,EAAE;oBACR,IAAI,CAAC,GAAG,CAAC,KAAK;wBAAE,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC,EACD,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAC7B,CAAC;gBACF,yEAAyE;gBACzE,IAAI,GAAG,CAAC,KAAK;oBAAE,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;;oBAC9B,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;YACvB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,GAAG,CAAC,KAAK,CAAC,CAAC;YACb,CAAC;QACH,CAAC,CAAC;KACL,CAAC;AACJ,CAAC","sourcesContent":["// Streaming drivers over sources Gyral doesn't own (ADR 0006 \"Outside sources\"): TC39 signals,\n// Redux-style stores, XState actors, WebSocket feeds. `subscription()` turns \"subscribe and\n// return how to stop\" into a driver: values become messages through the command's\n// `onSuccess`, and the source is released when the command is switched away or its component\n// disconnects. A standalone module: apps that don't import it don't bundle it.\nimport type { Concurrency, Driver } from './command.js';\nimport { fail } from './errors.js';\nimport { message } from './view/index.js';\n\n/** How to stop listening: a function, or an object with `unsubscribe()` (RxJS, XState). */\nexport type Unsubscribe = (() => void) | { readonly unsubscribe: () => void };\n\nexport interface SubscriptionContext<I> {\n  /** The command's input (a room code, a URL, a store key). */\n  readonly input: I;\n  /** Aborts when the command is switched away or its component disconnects. */\n  readonly signal: AbortSignal;\n  /**\n   * Ends the subscription with an error: the source is released and the command's\n   * `onFailure` gets it. Wrap the driver in `retry()` to subscribe again instead.\n   */\n  readonly fail: (error: unknown) => void;\n}\n\n/** Driver options a subscription may set. `concurrency` defaults to `'switch'`. */\nexport interface SubscriptionOptions<E> {\n  readonly concurrency?: Concurrency;\n  readonly toError?: (cause: unknown) => E;\n}\n\nconst release = (name: string, stop: Unsubscribe | undefined): void => {\n  if (stop === undefined) return;\n  try {\n    if (typeof stop === 'function') stop();\n    else stop.unsubscribe();\n  } catch (error) {\n    fail(error, 'subscribe', message(42, name), { msg: name });\n  }\n};\n\nconst asError = (reason: unknown): Error =>\n  reason instanceof Error ? reason : new DOMException('Aborted', 'AbortError');\n\n/**\n * A streaming driver over a source Gyral doesn't own. `subscribe` starts listening, calls\n * `emit` with each value (it may emit the current value at once) and returns how to stop\n * (a function, or an object with `unsubscribe()`).\n * The subscription lasts while the command runs; aborting it (lane `switch`, disconnect)\n * releases the source, and emits after that are ignored. Substitute it by `name` in tests.\n *\n *   const cart = subscription<CartState>('cart', (emit) => {\n *     emit(reduxStore.getState());\n *     return reduxStore.subscribe(() => emit(reduxStore.getState()));\n *   });\n *   // init: [state, [command(cart, undefined, { onSuccess: (c) => ({ _tag: 'Cart', c }) })]]\n */\nexport function subscription<O, I = undefined, E = unknown>(\n  name: string,\n  subscribe: (emit: (value: O) => void, ctx: SubscriptionContext<I>) => Unsubscribe,\n  options: SubscriptionOptions<E> = {},\n): Driver<I, O, E> {\n  return {\n    name,\n    concurrency: 'switch',\n    ...options,\n    run: (input, { signal, emit }) =>\n      new Promise<never>((_resolve, reject) => {\n        // `ended` may flip inside subscribe (fail() or an abort), so it lives in an object.\n        const sub: { ended: boolean; stop?: Unsubscribe } = { ended: false };\n        // Deliberately not wrapped in an Error: the driver's toError (or onFailure) sees the\n        // source's own error (a WebSocket's error event, a store's rejection).\n        const end = (error: unknown): void => {\n          if (sub.ended) return;\n          sub.ended = true;\n          signal.removeEventListener('abort', onAbort);\n          release(name, sub.stop);\n          // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors\n          reject(error);\n        };\n        const onAbort = (): void => {\n          end(asError(signal.reason));\n        };\n        if (signal.aborted) {\n          onAbort();\n          return;\n        }\n        signal.addEventListener('abort', onAbort, { once: true });\n        try {\n          const stop = subscribe(\n            (value) => {\n              if (!sub.ended) emit(value);\n            },\n            { input, signal, fail: end },\n          );\n          // fail() or an abort while subscribing ended it before `stop` was known.\n          if (sub.ended) release(name, stop);\n          else sub.stop = stop;\n        } catch (error) {\n          end(error);\n        }\n      }),\n  };\n}\n"]}

package/dist/subscriptions.d.ts

@@ -0,0 +1,26 @@
+import type { Command } from './command.js';
+/** What syncing needs from the host's model (host-model.ts). */
+export interface SubscriptionHost<M> {
+    readonly tag: string;
+    state(): unknown;
+    ctx(): {
+        readonly props: unknown;
+    };
+    /** Runs commands as a reducer's would. */
+    run(commands: readonly Command<M>[]): void;
+    /** Aborts the running task of `lane`. */
+    cancel(lane: string): void;
+    fail(cause: unknown, phase: 'update', text: string, msg: string): unknown;
+}
+/** One host's subscriptions. */
+export interface Subscriptions {
+    /** Evaluates `subscriptions` and makes the running set equal to its result. */
+    readonly update: () => void;
+    /** Forgets the running set (the host's commands were stopped). */
+    readonly reset: () => void;
+}
+/**
+ * `derive` is the spec field. A throw is reported as an update failure (ADR 0024) and leaves
+ * the running set as it was.
+ */
+export declare function subscriptionSet<M>(host: SubscriptionHost<M>, derive: (state: never, props: never) => readonly Command<M>[]): Subscriptions;

package/dist/subscriptions.js

@@ -0,0 +1,98 @@
+import { DEV, message } from './view/index.js';
+/**
+ * An input's identity for the diff: its data as JSON text. Functions inside it count as equal
+ * (an inline selector, `watch(store, (s) => s.x)`, is a new function after every message, and
+ * comparing it would restart the lane each time), repeated objects and cycles are cut, and
+ * BigInts are written out. So a changed key or changed data restarts a lane; a changed function
+ * alone doesn't: to restart on a new selector, change the key (gyral-1zd.29).
+ */
+const fingerprint = (input) => {
+    const seen = new WeakSet();
+    // Wrapped in an array, so even `undefined` has a text (`[null]`).
+    return JSON.stringify([input], (_key, value) => {
+        if (typeof value === 'function')
+            return '[function]';
+        if (typeof value === 'bigint')
+            return `${value.toString()}n`;
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value))
+                return '[seen]';
+            seen.add(value);
+        }
+        return value;
+    });
+};
+/**
+ * `derive` is the spec field. A throw is reported as an update failure (ADR 0024) and leaves
+ * the running set as it was.
+ */
+export function subscriptionSet(host, derive) {
+    const tag = host.tag;
+    const running = new Map();
+    // A command can emit while it starts (a timer that fires at once), so its message's update
+    // asks to sync again in the middle of a sync: it runs once this one is done.
+    let syncing = false;
+    let again = false;
+    const askedAgain = () => again; // read through a call: sync() may set it
+    const sync = () => {
+        let commands;
+        try {
+            // Sound: the host passes its own state and props to its own spec's field.
+            commands = derive(host.state(), host.ctx().props);
+        }
+        catch (cause) {
+            host.fail(cause, 'update', message(73, tag, 'subscriptions'), 'subscriptions');
+            return;
+        }
+        const seen = new Set();
+        for (const cmd of commands) {
+            const lane = cmd.key ?? cmd.driver.name;
+            if (seen.has(lane)) {
+                if (DEV)
+                    console.warn(message(79, tag, lane));
+                continue;
+            }
+            seen.add(lane);
+            const print = fingerprint(cmd.input);
+            if (running.has(lane)) {
+                if (Object.is(running.get(lane), print))
+                    continue;
+                host.cancel(lane);
+            }
+            running.set(lane, print);
+            host.run([cmd]);
+        }
+        for (const lane of running.keys()) {
+            if (seen.has(lane))
+                continue;
+            host.cancel(lane);
+            running.delete(lane);
+        }
+    };
+    return {
+        update() {
+            if (syncing) {
+                again = true;
+                return;
+            }
+            syncing = true;
+            try {
+                // A subscription whose input depends on what it emits would restart forever.
+                for (let rounds = 0; rounds < 100; rounds++) {
+                    again = false;
+                    sync();
+                    if (!askedAgain())
+                        return;
+                }
+                host.fail(new Error(message(80, tag)), 'update', message(80, tag), 'subscriptions');
+            }
+            finally {
+                syncing = false;
+            }
+        },
+        reset() {
+            running.clear();
+        },
+    };
+}
+//# sourceMappingURL=subscriptions.js.map

package/dist/subscriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../src/subscriptions.ts"],"names":[],"mappings":"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","sourcesContent":["// Declarative subscriptions (ADR 0025, view/05-element.md \"Subscriptions\"): `spec.subscriptions`\n// says which long-lived commands should be running for the current state and props, and this\n// module keeps the running set equal to it. Reached through `#spec-features` (registered by\n// the build when a module names the field), so apps that don't use it don't bundle it.\n//\n// The rules: once the host has rendered, and after every update and props change while it is\n// connected, `subscriptions(state, props)` is evaluated and synced. Commands are matched by\n// lane (`key`, else the driver's name). A lane that is new starts; a lane that is gone is\n// aborted; a lane whose input changed (compared as JSON text, functions ignored) is aborted\n// and started again; a lane with the same input keeps running. A subscription that ends by\n// itself stays ended until its lane or input changes. When the host's commands stop (removal,\n// ADR 0006) the set is forgotten, and the next connect starts it again from the current state.\nimport type { Command } from './command.js';\nimport { DEV, message } from './view/index.js';\n\n/** What syncing needs from the host's model (host-model.ts). */\nexport interface SubscriptionHost<M> {\n  readonly tag: string;\n  state(): unknown;\n  ctx(): { readonly props: unknown };\n  /** Runs commands as a reducer's would. */\n  run(commands: readonly Command<M>[]): void;\n  /** Aborts the running task of `lane`. */\n  cancel(lane: string): void;\n  fail(cause: unknown, phase: 'update', text: string, msg: string): unknown;\n}\n\n/** One host's subscriptions. */\nexport interface Subscriptions {\n  /** Evaluates `subscriptions` and makes the running set equal to its result. */\n  readonly update: () => void;\n  /** Forgets the running set (the host's commands were stopped). */\n  readonly reset: () => void;\n}\n\n/**\n * An input's identity for the diff: its data as JSON text. Functions inside it count as equal\n * (an inline selector, `watch(store, (s) => s.x)`, is a new function after every message, and\n * comparing it would restart the lane each time), repeated objects and cycles are cut, and\n * BigInts are written out. So a changed key or changed data restarts a lane; a changed function\n * alone doesn't: to restart on a new selector, change the key (gyral-1zd.29).\n */\nconst fingerprint = (input: unknown): string => {\n  const seen = new WeakSet<object>();\n  // Wrapped in an array, so even `undefined` has a text (`[null]`).\n  return JSON.stringify([input], (_key, value: unknown) => {\n    if (typeof value === 'function') return '[function]';\n    if (typeof value === 'bigint') return `${value.toString()}n`;\n    if (typeof value === 'object' && value !== null) {\n      if (seen.has(value)) return '[seen]';\n      seen.add(value);\n    }\n    return value;\n  });\n};\n\n/**\n * `derive` is the spec field. A throw is reported as an update failure (ADR 0024) and leaves\n * the running set as it was.\n */\nexport function subscriptionSet<M>(\n  host: SubscriptionHost<M>,\n  derive: (state: never, props: never) => readonly Command<M>[],\n): Subscriptions {\n  const tag = host.tag;\n  const running = new Map<string, unknown>();\n  // A command can emit while it starts (a timer that fires at once), so its message's update\n  // asks to sync again in the middle of a sync: it runs once this one is done.\n  let syncing = false;\n  let again = false;\n  const askedAgain = (): boolean => again; // read through a call: sync() may set it\n  const sync = (): void => {\n    let commands: readonly Command<M>[];\n    try {\n      // Sound: the host passes its own state and props to its own spec's field.\n      commands = derive(host.state() as never, host.ctx().props as never);\n    } catch (cause) {\n      host.fail(cause, 'update', message(73, tag, 'subscriptions'), 'subscriptions');\n      return;\n    }\n    const seen = new Set<string>();\n    for (const cmd of commands) {\n      const lane = cmd.key ?? cmd.driver.name;\n      if (seen.has(lane)) {\n        if (DEV) console.warn(message(79, tag, lane));\n        continue;\n      }\n      seen.add(lane);\n      const print = fingerprint(cmd.input);\n      if (running.has(lane)) {\n        if (Object.is(running.get(lane), print)) continue;\n        host.cancel(lane);\n      }\n      running.set(lane, print);\n      host.run([cmd]);\n    }\n    for (const lane of running.keys()) {\n      if (seen.has(lane)) continue;\n      host.cancel(lane);\n      running.delete(lane);\n    }\n  };\n  return {\n    update() {\n      if (syncing) {\n        again = true;\n        return;\n      }\n      syncing = true;\n      try {\n        // A subscription whose input depends on what it emits would restart forever.\n        for (let rounds = 0; rounds < 100; rounds++) {\n          again = false;\n          sync();\n          if (!askedAgain()) return;\n        }\n        host.fail(new Error(message(80, tag)), 'update', message(80, tag), 'subscriptions');\n      } finally {\n        syncing = false;\n      }\n    },\n    reset() {\n      running.clear();\n    },\n  };\n}\n"]}

package/dist/transitions.d.ts

@@ -1,8 +1,7 @@
-/** True when a view transition may run now (API present, motion not reduced). */
-export declare const canTransition: () => boolean;
 /**
- * Runs `update` (a whole flush) as a view transition's update callback. A transition skipped
+ * Runs `update` (a whole flush) as a view transition's update callback and returns true, or
+ * returns false when no transition may run now (the caller then runs it). A transition skipped
  * by a newer one still runs its update (per spec); its rejected promises are expected and
- * swallowed. Call only after `canTransition()`.
+ * swallowed.
  */
-export declare function startTransition(update: () => void): void;
+export declare function startTransition(update: () => void): boolean;

package/dist/transitions.js

@@ -1,17 +1,23 @@
 // View Transitions for the scheduler (view/04-scheduler.md "View transitions", ADR 0001
 // addendum). An ADR 0003 enhancement: without the API, or with reduced motion requested, the
-// flush runs as normal.
+// flush runs as normal. Reached through core's `#spec-features` (spec-features.ts): compiled
+// builds bundle it only when a module names `viewTransition` (compiler/features.ts,
+// gyral-c5d.12).
 const ignore = () => undefined;
 /** True when a view transition may run now (API present, motion not reduced). */
-export const canTransition = () => 'startViewTransition' in document && !matchMedia('(prefers-reduced-motion: reduce)').matches;
+const canTransition = () => 'startViewTransition' in document && !matchMedia('(prefers-reduced-motion: reduce)').matches;
 /**
- * Runs `update` (a whole flush) as a view transition's update callback. A transition skipped
+ * Runs `update` (a whole flush) as a view transition's update callback and returns true, or
+ * returns false when no transition may run now (the caller then runs it). A transition skipped
  * by a newer one still runs its update (per spec); its rejected promises are expected and
- * swallowed. Call only after `canTransition()`.
+ * swallowed.
  */
 export function startTransition(update) {
+    if (!canTransition())
+        return false;
     const transition = document.startViewTransition(update);
     transition.ready.catch(ignore);
     transition.finished.catch(ignore);
+    return true;
 }
 //# sourceMappingURL=transitions.js.map

package/dist/transitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../src/transitions.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,6FAA6F;AAC7F,wBAAwB;AAWxB,MAAM,MAAM,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAErC,iFAAiF;AACjF,MAAM,CAAC,MAAM,aAAa,GAAG,GAAY,EAAE,CACzC,qBAAqB,IAAI,QAAQ,IAAI,CAAC,UAAU,CAAC,kCAAkC,CAAC,CAAC,OAAO,CAAC;AAE/F;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAkB;IAChD,MAAM,UAAU,GAAI,QAA8C,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC/F,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC","sourcesContent":["// View Transitions for the scheduler (view/04-scheduler.md \"View transitions\", ADR 0001\n// addendum). An ADR 0003 enhancement: without the API, or with reduced motion requested, the\n// flush runs as normal.\n\ninterface ViewTransitionLike {\n  readonly ready: Promise<unknown>;\n  readonly finished: Promise<unknown>;\n}\n\ninterface ViewTransitionDocument {\n  startViewTransition(update: () => void): ViewTransitionLike;\n}\n\nconst ignore = (): void => undefined;\n\n/** True when a view transition may run now (API present, motion not reduced). */\nexport const canTransition = (): boolean =>\n  'startViewTransition' in document && !matchMedia('(prefers-reduced-motion: reduce)').matches;\n\n/**\n * Runs `update` (a whole flush) as a view transition's update callback. A transition skipped\n * by a newer one still runs its update (per spec); its rejected promises are expected and\n * swallowed. Call only after `canTransition()`.\n */\nexport function startTransition(update: () => void): void {\n  const transition = (document as Document & ViewTransitionDocument).startViewTransition(update);\n  transition.ready.catch(ignore);\n  transition.finished.catch(ignore);\n}\n"]}
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../src/transitions.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,6FAA6F;AAC7F,6FAA6F;AAC7F,oFAAoF;AACpF,iBAAiB;AAWjB,MAAM,MAAM,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAErC,iFAAiF;AACjF,MAAM,aAAa,GAAG,GAAY,EAAE,CAClC,qBAAqB,IAAI,QAAQ,IAAI,CAAC,UAAU,CAAC,kCAAkC,CAAC,CAAC,OAAO,CAAC;AAE/F;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAAkB;IAChD,IAAI,CAAC,aAAa,EAAE;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,UAAU,GAAI,QAA8C,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC/F,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["// View Transitions for the scheduler (view/04-scheduler.md \"View transitions\", ADR 0001\n// addendum). An ADR 0003 enhancement: without the API, or with reduced motion requested, the\n// flush runs as normal. Reached through core's `#spec-features` (spec-features.ts): compiled\n// builds bundle it only when a module names `viewTransition` (compiler/features.ts,\n// gyral-c5d.12).\n\ninterface ViewTransitionLike {\n  readonly ready: Promise<unknown>;\n  readonly finished: Promise<unknown>;\n}\n\ninterface ViewTransitionDocument {\n  startViewTransition(update: () => void): ViewTransitionLike;\n}\n\nconst ignore = (): void => undefined;\n\n/** True when a view transition may run now (API present, motion not reduced). */\nconst canTransition = (): boolean =>\n  'startViewTransition' in document && !matchMedia('(prefers-reduced-motion: reduce)').matches;\n\n/**\n * Runs `update` (a whole flush) as a view transition's update callback and returns true, or\n * returns false when no transition may run now (the caller then runs it). A transition skipped\n * by a newer one still runs its update (per spec); its rejected promises are expected and\n * swallowed.\n */\nexport function startTransition(update: () => void): boolean {\n  if (!canTransition()) return false;\n  const transition = (document as Document & ViewTransitionDocument).startViewTransition(update);\n  transition.ready.catch(ignore);\n  transition.finished.catch(ignore);\n  return true;\n}\n"]}