@gyral/core 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @gyral/core
 
+## 0.3.2
+
+### Patch Changes
+
+- Export the helper types `Reducer`, `Variant`, `ParseResult` and `StandardSchemaV1` (type-only),
+  so reducers and parsers written outside a component spec can be typed without copying
+  Gyral's internal definitions.
+- The development template locator no longer adds branches to your coverage reports: call
+  sites now go through a virtual helper module instead of an inline `.at?.() ?? html` fallback.
+- The components build metadata (`.vite/gyral-components.json`) gains `chunkModules`, which maps
+  each emitted chunk to the root-relative source modules it contains, including workspace
+  modules Vite merged into a shared chunk. Offline caches and service workers can use it to
+  know which chunk serves which module.
+- Public doc comments no longer point at repository paths or tracker IDs.
+
+## 0.3.1
+
+### Patch Changes
+
+This release includes API removals and behavior changes. Read the
+[0.3.0 → 0.3.1 migration guide](https://github.com/gyraljs/gyral/blob/main/docs/references/migrating-0.3.0-to-0.3.1.md) before upgrading, and keep the nine
+Gyral packages on the same version.
+
+- Components use `define<State, Msg>()(tag, spec)` with typed intent names, tag-only intents,
+  parser state access and typed outputs. A declined intent bubbles to the next matching
+  intent; child outputs stop at their direct consuming parent.
+- Declarative `subscriptions` reconcile long-lived commands, with typed `subscription()`
+  builders, cancellation and stable command lanes. Drivers resolve through the host/root
+  override boundary; retry supports predicates, backoff and jitter.
+- Views gain `svg` templates, `keyed` replacement, disposable `defineHook` hooks, delegated
+  shadow focus, `focus(..., { wait: true })` and post-render `call` commands. Hooks run after
+  child renders and dispose when their owned elements are removed.
+- Native modal/popover bindings open after DOM insertion and child renders. Conditional
+  insertion, keyed replacement, initial opening and hydration follow the same ordering.
+  Intents dispatched by native focus complete their renders before focus commands and `settled`.
+- Opt-in `formAssociated` components project native values and validity and receive reset,
+  disabled and restoration messages. Native SSR fallback controls can preserve edits made
+  before hydration without duplicate form entries.
+- Optional `@gyral/core/storage` provides schema-decoded localStorage operations and change
+  subscriptions. Optional `@gyral/core/indexeddb` provides typed records, bounded queries,
+  synchronous migrations and atomic transaction batches. Neither adds code to unused apps.
+- Forms validate and refill through their definitions, retain user edits until model values
+  change, and redact password/passcode/CSRF fields plus explicitly named secrets. Shared head
+  data covers title, metadata, canonical URLs and JSON-LD across server rendering and routing.
+- The Vite preset supports client-only builds, automatic component modules, explicit wrapper
+  module mappings and generated element typings. Entry-imported components stay in their
+  entry; loader/preload work and spec features are reduced when unused.
+- Unified `GyralError` reporting, `Errored` reducers and error views handle failures in the
+  browser and server. Production diagnostics use stable codes linked to the public reference.
+  Strict CSP style bindings use CSSOM; seeded hydration and Trusted Types paths are verified.
+- Compiler/runtime/lint template rules agree, including boolean bindings written as `?name`.
+  Public exports have a checked inventory; duplicate/internal helper APIs are removed as
+  described in the migration guide.
+
+The lockstep release also adds optional/catch-all routes in `@gyral/router` and native
+EventSource/WebSocket entries in `@gyral/http`; see those packages' changelogs.
+
 ## 0.3.0
 
 ### Minor Changes

package/NOTICE

@@ -5,7 +5,26 @@ Gyral is inspired by Cycle.js (https://github.com/cyclejs/cyclejs), released
 under the MIT License:
 
   The MIT License (MIT)
+
   Copyright (c) 2015-2019 The Cycle.js Core Team
 
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.
+
 Gyral is a new implementation. Where ideas, APIs or example programs are adapted
 from Cycle.js, this notice applies.

package/README.md

@@ -1,6 +1,6 @@
 # @gyral/core
 
-Model-View-Intent web components on the web platform, with their own view layer. _Inspired by [Cycle.js](https://cycle.js.org)._ Intent parses platform events into typed messages, the model is a set of pure reducers, and the view is a pure template that names intents. Side effects are commands: data that drivers run at the edges.
+Model-View-Intent web components on the web platform, with their own view layer. Intent parses platform events into typed messages, the model is a set of pure reducers, and the view is a pure template that names intents. Side effects are commands: data that drivers run at the edges.
 
 ## Install
 
@@ -15,11 +15,11 @@ import { define, html } from '@gyral/core';
 
 type Msg = { _tag: 'Increment' } | { _tag: 'Decrement' };
 
-define<{ count: number }, Msg>('gy-counter', {
+define<{ count: number }, Msg>()('gy-counter', {
   init: () => ({ count: 0 }),
   intent: {
-    Increment: () => ({ _tag: 'Increment' }),
-    Decrement: () => ({ _tag: 'Decrement' }),
+    Increment: true,
+    Decrement: true,
   },
   update: {
     Increment: (s) => ({ count: s.count + 1 }),
@@ -35,16 +35,44 @@ define<{ count: number }, Msg>('gy-counter', {
 
 `@gyral/core/vite` exports `gyralVitePreset()`, the Vite/Vitest settings every Gyral app needs
 (the build-time template compiler). `@gyral/core/eslint` is an ESLint plugin with the same
-template rules for the editor: `export default [gyral.configs.recommended]`.
+template rules for the editor (`import gyral from '@gyral/core/eslint'`, then
+`gyral.configs.recommended` in your flat config). `@gyral/ssr` renders components and pages
+to HTML on the server. In tests, `await settled()` waits until
+every component has rendered and messages have stopped arriving.
 
 ## Documentation
 
+`@gyral/core/storage` (0.3.1) exports `makeLocalStorageDriver(schema, { prefix?, name?,
+storage?, encode? })`: JSON Read/Write/Remove/Clear commands and cancellable Watch streams.
+Reads validate persisted values with Standard Schema; watches report invalid data and keep
+listening. Driver writes and native other-tab events produce changes. Clear respects the
+prefix namespace. Start initial watches in `subscriptions` so SSR state hydrates first;
+imports and factories do not access browser globals. This optional entry is absent from
+apps that do not import it. See [the storage guide](https://github.com/gyraljs/gyral/blob/main/skills/gyral/references/browser-storage.md).
+
+`@gyral/core/indexeddb` (0.3.1) exports `makeIndexedDBDriver(stores, { database, version,
+upgrade?, name?, factory?, encode? })`: typed Read/Put/Delete, bounded Query and atomic
+Transaction batches. Applications own stores, indexes and synchronous migrations. Success
+means the native transaction committed; stored records decode afterward. Blocked upgrades,
+access and decoding failures are typed. Commands close connections and cancel native work;
+an already committed write cannot be undone. This entry is also optional and SSR-safe.
+
 Guides and API reference: **[gyral.dev](https://gyral.dev)**. Source, issues and the
 consumer setup guide (packages, Vite preset, template compiler):
-[github.com/gyraljs/gyral](https://github.com/gyraljs/gyral). Upgrading from 0.2:
-[docs/references/migrating-0.2-to-0.3.md](https://github.com/gyraljs/gyral/blob/main/docs/references/migrating-0.2-to-0.3.md).
+[github.com/gyraljs/gyral](https://github.com/gyraljs/gyral). Upgrading:
+[from 0.3.0 to 0.3.1](https://github.com/gyraljs/gyral/blob/main/docs/references/migrating-0.3.0-to-0.3.1.md),
+[from 0.2 to 0.3](https://github.com/gyraljs/gyral/blob/main/docs/references/migrating-0.2-to-0.3.md).
+
+> Status: 0.x, on npm. Breaking changes to the
+> [public API](https://github.com/gyraljs/gyral/blob/main/docs/references/public-api-0.3.1.md)
+> come only in a new minor version, with a migration guide.
+
+## Diagnostic codes
 
-> Status: pre-alpha. APIs change between 0.x releases.
+Production builds print codes such as `Gyral G0010 my-cart Increment`. The full table (code,
+group, message, arguments, link) ships with the package as `@gyral/core/errors.json`, for tools
+and docs sites: `import errors from '@gyral/core/errors.json' with { type: 'json' };`. The
+same table, rendered: <https://gyral.dev/errors/>.
 
 ## License
 

package/dist/call.d.ts

@@ -0,0 +1,32 @@
+import type { Command } from './command.js';
+import type { LocalHost } from './features.js';
+/** The input of a `call()` command. */
+export interface CallInput {
+    readonly selector: string;
+    readonly method: string;
+    readonly args: readonly unknown[];
+}
+/** Marker driver: the host runs call commands itself (`local`), after the render. */
+export declare const CALL: {
+    readonly name: "@gyral/call";
+    readonly run: () => undefined;
+    readonly local: (host: LocalHost, input: unknown) => void;
+};
+/**
+ * A command that calls `method` with `args` on the first element matching `selector` inside
+ * this component (its shadow root, or its own children in light-DOM mode) once the current
+ * update has rendered:
+ *
+ *   Start: (s) => [{ ...s, playing: true }, [call('video', 'play')]]
+ *   Join: (s, m) => [s, [call('room-stage', 'join', m.room)]]
+ *
+ * `args` must be plain data (structured-cloneable), so the command stays data a test can
+ * compare. A missing element or method, or a method that throws or rejects, is reported
+ * through the error channel (ADR 0024); the error's cause says which.
+ */
+export declare function call(selector: string, method: string, ...args: readonly unknown[]): Command<never>;
+/**
+ * Runs a call command against `root`. No element, no such method, or a method that throws or
+ * rejects: reported with `host` (the cause says which).
+ */
+export declare function runCall(root: ParentNode, host: Element, tag: string, input: CallInput): void;

package/dist/call.js

@@ -0,0 +1,63 @@
+import { fail } from './errors.js';
+import { afterRender, POST_FOCUS } from './scheduler.js';
+import { DEV, message } from './view/index.js';
+/** Marker driver: the host runs call commands itself (`local`), after the render. */
+export const CALL = {
+    name: '@gyral/call',
+    run: () => undefined,
+    local: (host, input) => {
+        afterRender(POST_FOCUS, () => {
+            const root = host.root();
+            if (host.el.isConnected && root !== undefined)
+                runCall(root, host.el, host.tag, input);
+        });
+    },
+};
+/**
+ * A command that calls `method` with `args` on the first element matching `selector` inside
+ * this component (its shadow root, or its own children in light-DOM mode) once the current
+ * update has rendered:
+ *
+ *   Start: (s) => [{ ...s, playing: true }, [call('video', 'play')]]
+ *   Join: (s, m) => [s, [call('room-stage', 'join', m.room)]]
+ *
+ * `args` must be plain data (structured-cloneable), so the command stays data a test can
+ * compare. A missing element or method, or a method that throws or rejects, is reported
+ * through the error channel (ADR 0024); the error's cause says which.
+ */
+export function call(selector, method, ...args) {
+    if (DEV) {
+        try {
+            structuredClone(args);
+        }
+        catch {
+            throw new TypeError(message(86, selector, method));
+        }
+    }
+    const input = { selector, method, args };
+    return { driver: CALL, input, onSuccess: () => undefined };
+}
+/**
+ * Runs a call command against `root`. No element, no such method, or a method that throws or
+ * rejects: reported with `host` (the cause says which).
+ */
+export function runCall(root, host, tag, input) {
+    const { selector, method, args } = input;
+    const failed = (cause) => {
+        fail(cause, 'command', message(85, tag, selector, method), { host, tag, msg: method });
+    };
+    try {
+        const target = root.querySelector(selector);
+        if (target === null)
+            throw new Error(`no element matches ${selector}`);
+        const result = target[method].apply(target, [
+            ...args,
+        ]);
+        if (result instanceof Promise)
+            result.catch(failed);
+    }
+    catch (cause) {
+        failed(cause);
+    }
+}
+//# sourceMappingURL=call.js.map

package/dist/call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call.js","sourceRoot":"","sources":["../src/call.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAS/C,qFAAqF;AACrF,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,IAAI,EAAE,aAAa;IACnB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;IACpB,KAAK,EAAE,CAAC,IAAe,EAAE,KAAc,EAAE,EAAE;QACzC,WAAW,CAAC,UAAU,EAAE,GAAG,EAAE;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,EAAE,CAAC,WAAW,IAAI,IAAI,KAAK,SAAS;gBAC3C,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,KAAkB,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;IACL,CAAC;CACO,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,IAAI,CAClB,QAAgB,EAChB,MAAc,EACd,GAAG,IAAwB;IAE3B,IAAI,GAAG,EAAE,CAAC;QACR,IAAI,CAAC;YACH,eAAe,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACpD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AAC7D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,IAAgB,EAAE,IAAa,EAAE,GAAW,EAAE,KAAgB;IACpF,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IACzC,MAAM,MAAM,GAAG,CAAC,KAAc,EAAQ,EAAE;QACtC,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;IACzF,CAAC,CAAC;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAmC,CAAC;QAC9E,IAAI,MAAM,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,QAAQ,EAAE,CAAC,CAAC;QACvE,MAAM,MAAM,GAAa,MAAM,CAAC,MAAM,CAAkC,CAAC,KAAK,CAAC,MAAM,EAAE;YACrF,GAAG,IAAI;SACR,CAAC,CAAC;QACH,IAAI,MAAM,YAAY,OAAO;YAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,CAAC;IAChB,CAAC;AACH,CAAC","sourcesContent":["// Calling a method on an element from the model (gyral-1zd.27, view/05-element.md \"Calling an\n// element's method\"). Telling a child component, a media element or a widget to do something\n// (play, reset, open a room) is a side effect, so the model asks for it with a command, as it\n// does for focus: `call(selector, method, ...args)`. It runs as post-render work against the\n// component's own tree, so the element already exists. Gyral's answer to refs and ports: the\n// request is plain data, so a model test reads it with `callsIn` (@gyral/testing).\nimport type { Command } from './command.js';\nimport { fail } from './errors.js';\nimport type { LocalHost } from './features.js';\nimport { afterRender, POST_FOCUS } from './scheduler.js';\nimport { DEV, message } from './view/index.js';\n\n/** The input of a `call()` command. */\nexport interface CallInput {\n  readonly selector: string;\n  readonly method: string;\n  readonly args: readonly unknown[];\n}\n\n/** Marker driver: the host runs call commands itself (`local`), after the render. */\nexport const CALL = {\n  name: '@gyral/call',\n  run: () => undefined,\n  local: (host: LocalHost, input: unknown) => {\n    afterRender(POST_FOCUS, () => {\n      const root = host.root();\n      if (host.el.isConnected && root !== undefined)\n        runCall(root, host.el, host.tag, input as CallInput);\n    });\n  },\n} as const;\n\n/**\n * A command that calls `method` with `args` on the first element matching `selector` inside\n * this component (its shadow root, or its own children in light-DOM mode) once the current\n * update has rendered:\n *\n *   Start: (s) => [{ ...s, playing: true }, [call('video', 'play')]]\n *   Join: (s, m) => [s, [call('room-stage', 'join', m.room)]]\n *\n * `args` must be plain data (structured-cloneable), so the command stays data a test can\n * compare. A missing element or method, or a method that throws or rejects, is reported\n * through the error channel (ADR 0024); the error's cause says which.\n */\nexport function call(\n  selector: string,\n  method: string,\n  ...args: readonly unknown[]\n): Command<never> {\n  if (DEV) {\n    try {\n      structuredClone(args);\n    } catch {\n      throw new TypeError(message(86, selector, method));\n    }\n  }\n  const input: CallInput = { selector, method, args };\n  return { driver: CALL, input, onSuccess: () => undefined };\n}\n\n/**\n * Runs a call command against `root`. No element, no such method, or a method that throws or\n * rejects: reported with `host` (the cause says which).\n */\nexport function runCall(root: ParentNode, host: Element, tag: string, input: CallInput): void {\n  const { selector, method, args } = input;\n  const failed = (cause: unknown): void => {\n    fail(cause, 'command', message(85, tag, selector, method), { host, tag, msg: method });\n  };\n  try {\n    const target = root.querySelector(selector) as Record<string, unknown> | null;\n    if (target === null) throw new Error(`no element matches ${selector}`);\n    const result: unknown = (target[method] as (...a: unknown[]) => unknown).apply(target, [\n      ...args,\n    ]);\n    if (result instanceof Promise) result.catch(failed);\n  } catch (cause) {\n    failed(cause);\n  }\n}\n"]}

package/dist/children.d.ts

@@ -1,6 +1,6 @@
 import type { Command } from './command.js';
 import type { LocalHost } from './features.js';
-import type { IntentParser, Tagged } from './types.js';
+import type { IntentInput, IntentParser, Tagged } from './types.js';
 /** Marker driver: the host runs emit commands itself (`local`), synchronously ordered. */
 export declare const EMIT: {
     readonly name: "@gyral/emit";
@@ -10,8 +10,30 @@ export declare const EMIT: {
 /**
  * A command that sends `output` to the parent component. The parent receives it as an
  * intent on the child element: `<my-child data-intent=${i.Picked}>` + `child(MyChild, …)`.
+ * `outputs<Out>()` gives the same function typed by the component's output union.
  */
 export declare function emit(output: Tagged & Readonly<Record<string, unknown>>): Command<never>;
+/**
+ * `emit`, typed by a component's output union (the 4th `define` type parameter), so an
+ * output of the wrong shape fails to compile. A module-level constant, like `intentsOf()`:
+ *
+ *   type Out = { readonly _tag: 'Picked'; readonly id: number };
+ *   const emit = outputs<Out>();
+ *   // in update: Pick: (s, m) => [s, [emit({ _tag: 'Picked', id: m.id })]]
+ *
+ * Costs nothing at run time: it returns `emit` itself.
+ */
+export declare function outputs<O extends Tagged>(): (output: O) => Command<never>;
+/**
+ * The `gyral-output` event a child dispatches on its host for each output (ADR 0010): `detail`
+ * is the output. Bubbles, not composed. A non-Gyral parent listens for `OUTPUT_EVENT`. Only the
+ * direct parent's intent on the child host takes it, and once it does the event stops there.
+ */
+export type OutputEvent<O extends Tagged = Tagged> = CustomEvent<O>;
+/** The output union of a `define()` class: `OutputsOf<typeof Item>`. */
+export type OutputsOf<C> = C extends {
+    readonly outputs?: infer O;
+} ? Exclude<O, undefined> : never;
 /**
  * Sends an output to the parent component. A microtask keeps outputs in order and out of the
  * parent's render pass (settled() waits for it); the event bubbles through the parent's shadow
@@ -33,8 +55,8 @@ export type ChildSource<O extends Tagged, E extends Element> = OutputSource<O, E
  * Pass `() => Child` when the class isn't defined yet, e.g. a component that contains
  * itself; annotate the constant's type so TypeScript accepts the self-reference:
  *
- *   const Folder: GyralElementClass<State, Msg, Props, Out> = define('x-folder', {
+ *   const Folder: GyralElementClass<State, Msg, Props, Out> = define()('x-folder', {
  *     intent: { Child: child(() => Folder, (out, el) => …) }, …
  *   });
  */
-export declare function child<O extends Tagged, E extends Element, M>(source: ChildSource<O, E>, toMsg: (output: O, el: E) => M | undefined): IntentParser<M>;
+export declare function child<O extends Tagged, E extends Element, M>(source: ChildSource<O, E>, toMsg: (output: O, el: E) => M | undefined): (input: IntentInput) => ReturnType<IntentParser<M>>;

package/dist/children.js

@@ -11,10 +11,27 @@ export const EMIT = {
 /**
  * A command that sends `output` to the parent component. The parent receives it as an
  * intent on the child element: `<my-child data-intent=${i.Picked}>` + `child(MyChild, …)`.
+ * `outputs<Out>()` gives the same function typed by the component's output union.
  */
 export function emit(output) {
     return { driver: EMIT, input: output, onSuccess: () => undefined };
 }
+/**
+ * `emit`, typed by a component's output union (the 4th `define` type parameter), so an
+ * output of the wrong shape fails to compile. A module-level constant, like `intentsOf()`:
+ *
+ *   type Out = { readonly _tag: 'Picked'; readonly id: number };
+ *   const emit = outputs<Out>();
+ *   // in update: Pick: (s, m) => [s, [emit({ _tag: 'Picked', id: m.id })]]
+ *
+ * Costs nothing at run time: it returns `emit` itself.
+ */
+// A type-only argument: the caller names the union the result accepts.
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+export function outputs() {
+    // Sound: emit only forwards the output; the stricter parameter type is the point.
+    return emit;
+}
 /**
  * Sends an output to the parent component. A microtask keeps outputs in order and out of the
  * parent's render pass (settled() waits for it); the event bubbles through the parent's shadow
@@ -38,7 +55,7 @@ const resolveSource = (source) => 'prototype' in source && source.prototype !==
  * Pass `() => Child` when the class isn't defined yet, e.g. a component that contains
  * itself; annotate the constant's type so TypeScript accepts the self-reference:
  *
- *   const Folder: GyralElementClass<State, Msg, Props, Out> = define('x-folder', {
+ *   const Folder: GyralElementClass<State, Msg, Props, Out> = define()('x-folder', {
  *     intent: { Child: child(() => Folder, (out, el) => …) }, …
  *   });
  */

package/dist/children.js.map

@@ -1 +1 @@
-{"version":3,"file":"children.js","sourceRoot":"","sources":["../src/children.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,0FAA0F;AAC1F,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,IAAI,EAAE,aAAa;IACnB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;IACpB,KAAK,EAAE,CAAC,IAAe,EAAE,MAAe,EAAE,EAAE;QAC1C,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;CACO,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,MAAkD;IACrE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAa,EAAE,MAAe;IAC3D,KAAK,CAAC,GAAG,EAAE;QACT,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO;QAC9B,IAAI,CAAC,aAAa,CAChB,IAAI,WAAW,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAClF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAaD,oEAAoE;AACpE,MAAM,aAAa,GAAG,CACpB,MAAyB,EACL,EAAE,CACtB,WAAW,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;IACrD,CAAC,CAAE,MAA6B;IAChC,CAAC,CAAE,MAAmC,EAAE,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,KAAK,CACnB,MAAyB,EACzB,KAA0C;IAE1C,OAAO,CAAC,KAAkB,EAAE,EAAE;QAC5B,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,sDAAsD;QAC1F,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,YAAY,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACpF,8EAA8E;QAC9E,OAAO,KAAK,CAAC,KAAK,CAAC,MAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC,CAAC;AACJ,CAAC","sourcesContent":["// Child components: props down, outputs up (docs/design-docs/0010-child-components.md).\nimport type { Command } from './command.js';\nimport type { LocalHost } from './features.js';\nimport { OUTPUT_EVENT } from './intent.js';\nimport { defer } from './scheduler.js';\nimport type { IntentInput, IntentParser, Tagged } from './types.js';\n\n/** Marker driver: the host runs emit commands itself (`local`), synchronously ordered. */\nexport const EMIT = {\n  name: '@gyral/emit',\n  run: () => undefined,\n  local: (host: LocalHost, output: unknown) => {\n    dispatchOutput(host.el, output);\n  },\n} as const;\n\n/**\n * A command that sends `output` to the parent component. The parent receives it as an\n * intent on the child element: `<my-child data-intent=${i.Picked}>` + `child(MyChild, …)`.\n */\nexport function emit(output: Tagged & Readonly<Record<string, unknown>>): Command<never> {\n  return { driver: EMIT, input: output, onSuccess: () => undefined };\n}\n\n/**\n * Sends an output to the parent component. A microtask keeps outputs in order and out of the\n * parent's render pass (settled() waits for it); the event bubbles through the parent's shadow\n * tree only (not composed).\n */\nexport function dispatchOutput(host: Element, output: unknown): void {\n  defer(() => {\n    if (!host.isConnected) return;\n    host.dispatchEvent(\n      new CustomEvent(OUTPUT_EVENT, { detail: output, bubbles: true, composed: false }),\n    );\n  });\n}\n\n/** Anything `child()` can read an output type from: a `define()` class. */\nexport interface OutputSource<O extends Tagged, E extends Element> {\n  new (): E;\n  /** Type-only marker for the component's output union. Never set at runtime. */\n  readonly outputs?: O;\n}\n\n/** A child class, or a function returning it (for recursive or later-defined components). */\nexport type ChildSource<O extends Tagged, E extends Element> =\n  OutputSource<O, E> | (() => OutputSource<O, E>);\n\n// Classes have a prototype; arrow functions (the lazy form) do not.\nconst resolveSource = <O extends Tagged, E extends Element>(\n  source: ChildSource<O, E>,\n): OutputSource<O, E> =>\n  'prototype' in source && source.prototype !== undefined\n    ? (source as OutputSource<O, E>)\n    : (source as () => OutputSource<O, E>)();\n\n/**\n * Intent parser for a child component's outputs, typed by the child's output union.\n * `el` is the child element, for reading its props (an item id, for example).\n *\n * Pass `() => Child` when the class isn't defined yet, e.g. a component that contains\n * itself; annotate the constant's type so TypeScript accepts the self-reference:\n *\n *   const Folder: GyralElementClass<State, Msg, Props, Out> = define('x-folder', {\n *     intent: { Child: child(() => Folder, (out, el) => …) }, …\n *   });\n */\nexport function child<O extends Tagged, E extends Element, M>(\n  source: ChildSource<O, E>,\n  toMsg: (output: O, el: E) => M | undefined,\n): IntentParser<M> {\n  return (input: IntentInput) => {\n    const type = resolveSource(source); // resolved per event, so the lazy form never hits TDZ\n    if (!(input.target instanceof type) || input.detail === undefined) return undefined;\n    // Sound: only `emit()` from a component of this class dispatches this detail.\n    return toMsg(input.detail as O, input.target);\n  };\n}\n"]}
+{"version":3,"file":"children.js","sourceRoot":"","sources":["../src/children.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,0FAA0F;AAC1F,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,IAAI,EAAE,aAAa;IACnB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;IACpB,KAAK,EAAE,CAAC,IAAe,EAAE,MAAe,EAAE,EAAE;QAC1C,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;CACO,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,MAAkD;IACrE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AACrE,CAAC;AAED;;;;;;;;;GASG;AACH,uEAAuE;AACvE,6EAA6E;AAC7E,MAAM,UAAU,OAAO;IACrB,kFAAkF;IAClF,OAAO,IAAgD,CAAC;AAC1D,CAAC;AAYD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAa,EAAE,MAAe;IAC3D,KAAK,CAAC,GAAG,EAAE;QACT,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO;QAC9B,IAAI,CAAC,aAAa,CAChB,IAAI,WAAW,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAClF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAaD,oEAAoE;AACpE,MAAM,aAAa,GAAG,CACpB,MAAyB,EACL,EAAE,CACtB,WAAW,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;IACrD,CAAC,CAAE,MAA6B;IAChC,CAAC,CAAE,MAAmC,EAAE,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,KAAK,CACnB,MAAyB,EACzB,KAA0C;IAE1C,OAAO,CAAC,KAAkB,EAAE,EAAE;QAC5B,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,sDAAsD;QAC1F,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,YAAY,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACpF,8EAA8E;QAC9E,OAAO,KAAK,CAAC,KAAK,CAAC,MAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC,CAAC;AACJ,CAAC","sourcesContent":["// Child components: props down, outputs up (docs/design-docs/0010-child-components.md).\nimport type { Command } from './command.js';\nimport type { LocalHost } from './features.js';\nimport { OUTPUT_EVENT } from './intent.js';\nimport { defer } from './scheduler.js';\nimport type { IntentInput, IntentParser, Tagged } from './types.js';\n\n/** Marker driver: the host runs emit commands itself (`local`), synchronously ordered. */\nexport const EMIT = {\n  name: '@gyral/emit',\n  run: () => undefined,\n  local: (host: LocalHost, output: unknown) => {\n    dispatchOutput(host.el, output);\n  },\n} as const;\n\n/**\n * A command that sends `output` to the parent component. The parent receives it as an\n * intent on the child element: `<my-child data-intent=${i.Picked}>` + `child(MyChild, …)`.\n * `outputs<Out>()` gives the same function typed by the component's output union.\n */\nexport function emit(output: Tagged & Readonly<Record<string, unknown>>): Command<never> {\n  return { driver: EMIT, input: output, onSuccess: () => undefined };\n}\n\n/**\n * `emit`, typed by a component's output union (the 4th `define` type parameter), so an\n * output of the wrong shape fails to compile. A module-level constant, like `intentsOf()`:\n *\n *   type Out = { readonly _tag: 'Picked'; readonly id: number };\n *   const emit = outputs<Out>();\n *   // in update: Pick: (s, m) => [s, [emit({ _tag: 'Picked', id: m.id })]]\n *\n * Costs nothing at run time: it returns `emit` itself.\n */\n// A type-only argument: the caller names the union the result accepts.\n// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters\nexport function outputs<O extends Tagged>(): (output: O) => Command<never> {\n  // Sound: emit only forwards the output; the stricter parameter type is the point.\n  return emit as unknown as (output: O) => Command<never>;\n}\n\n/**\n * The `gyral-output` event a child dispatches on its host for each output (ADR 0010): `detail`\n * is the output. Bubbles, not composed. A non-Gyral parent listens for `OUTPUT_EVENT`. Only the\n * direct parent's intent on the child host takes it, and once it does the event stops there.\n */\nexport type OutputEvent<O extends Tagged = Tagged> = CustomEvent<O>;\n\n/** The output union of a `define()` class: `OutputsOf<typeof Item>`. */\nexport type OutputsOf<C> = C extends { readonly outputs?: infer O } ? Exclude<O, undefined> : never;\n\n/**\n * Sends an output to the parent component. A microtask keeps outputs in order and out of the\n * parent's render pass (settled() waits for it); the event bubbles through the parent's shadow\n * tree only (not composed).\n */\nexport function dispatchOutput(host: Element, output: unknown): void {\n  defer(() => {\n    if (!host.isConnected) return;\n    host.dispatchEvent(\n      new CustomEvent(OUTPUT_EVENT, { detail: output, bubbles: true, composed: false }),\n    );\n  });\n}\n\n/** Anything `child()` can read an output type from: a `define()` class. */\nexport interface OutputSource<O extends Tagged, E extends Element> {\n  new (): E;\n  /** Type-only marker for the component's output union. Never set at runtime. */\n  readonly outputs?: O;\n}\n\n/** A child class, or a function returning it (for recursive or later-defined components). */\nexport type ChildSource<O extends Tagged, E extends Element> =\n  OutputSource<O, E> | (() => OutputSource<O, E>);\n\n// Classes have a prototype; arrow functions (the lazy form) do not.\nconst resolveSource = <O extends Tagged, E extends Element>(\n  source: ChildSource<O, E>,\n): OutputSource<O, E> =>\n  'prototype' in source && source.prototype !== undefined\n    ? (source as OutputSource<O, E>)\n    : (source as () => OutputSource<O, E>)();\n\n/**\n * Intent parser for a child component's outputs, typed by the child's output union.\n * `el` is the child element, for reading its props (an item id, for example).\n *\n * Pass `() => Child` when the class isn't defined yet, e.g. a component that contains\n * itself; annotate the constant's type so TypeScript accepts the self-reference:\n *\n *   const Folder: GyralElementClass<State, Msg, Props, Out> = define()('x-folder', {\n *     intent: { Child: child(() => Folder, (out, el) => …) }, …\n *   });\n */\nexport function child<O extends Tagged, E extends Element, M>(\n  source: ChildSource<O, E>,\n  toMsg: (output: O, el: E) => M | undefined,\n): (input: IntentInput) => ReturnType<IntentParser<M>> {\n  return (input: IntentInput) => {\n    const type = resolveSource(source); // resolved per event, so the lazy form never hits TDZ\n    if (!(input.target instanceof type) || input.detail === undefined) return undefined;\n    // Sound: only `emit()` from a component of this class dispatches this detail.\n    return toMsg(input.detail as O, input.target);\n  };\n}\n"]}

package/dist/cli/gyral-types.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/gyral-types.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// gyral-types: writes the element typings gyralVitePreset() writes (gyral-1zd.25), for type
+// checks that run without Vite (`gyral-types && tsc --noEmit`).
+//   gyral-types [--root <dir>] [--dir <src dir>]... [--out <file>]
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { writeTagMap } from '../compiler/tag-map.js';
+const { values } = parseArgs({
+    options: {
+        root: { type: 'string', default: '.' },
+        dir: { type: 'string', multiple: true },
+        out: { type: 'string' },
+    },
+});
+const { entries, written } = writeTagMap({
+    root: resolve(values.root),
+    ...(values.dir === undefined ? {} : { dirs: values.dir }),
+    ...(values.out === undefined ? {} : { out: values.out }),
+});
+const where = values.out ?? '.gyral/elements.d.ts';
+console.log(`gyral-types: ${String(entries.length)} element${entries.length === 1 ? '' : 's'} ` +
+    `${written ? 'written to' : 'unchanged in'} ${where}`);
+//# sourceMappingURL=gyral-types.js.map

package/dist/cli/gyral-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gyral-types.js","sourceRoot":"","sources":["../../src/cli/gyral-types.ts"],"names":[],"mappings":";AACA,4FAA4F;AAC5F,gEAAgE;AAChE,mEAAmE;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErD,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE;QACP,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE;QACtC,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;QACvC,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KACxB;CACF,CAAC,CAAC;AAEH,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC;IACvC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;IACzD,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;CACzD,CAAC,CAAC;AACH,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,IAAI,sBAAsB,CAAC;AACnD,OAAO,CAAC,GAAG,CACT,gBAAgB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG;IACjF,GAAG,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,cAAc,IAAI,KAAK,EAAE,CACxD,CAAC","sourcesContent":["#!/usr/bin/env node\n// gyral-types: writes the element typings gyralVitePreset() writes (gyral-1zd.25), for type\n// checks that run without Vite (`gyral-types && tsc --noEmit`).\n//   gyral-types [--root <dir>] [--dir <src dir>]... [--out <file>]\nimport { resolve } from 'node:path';\nimport { parseArgs } from 'node:util';\nimport { writeTagMap } from '../compiler/tag-map.js';\n\nconst { values } = parseArgs({\n  options: {\n    root: { type: 'string', default: '.' },\n    dir: { type: 'string', multiple: true },\n    out: { type: 'string' },\n  },\n});\n\nconst { entries, written } = writeTagMap({\n  root: resolve(values.root),\n  ...(values.dir === undefined ? {} : { dirs: values.dir }),\n  ...(values.out === undefined ? {} : { out: values.out }),\n});\nconst where = values.out ?? '.gyral/elements.d.ts';\nconsole.log(\n  `gyral-types: ${String(entries.length)} element${entries.length === 1 ? '' : 's'} ` +\n    `${written ? 'written to' : 'unchanged in'} ${where}`,\n);\n"]}

package/dist/command.d.ts

@@ -1,12 +1,20 @@
 import type { IntentRejected } from './types.js';
 /** How commands in the same lane interact. See ADR 0006 for the table. */
 export type Concurrency = 'merge' | 'switch' | 'exhaust' | 'queue';
-export interface RetryPolicy {
+/** How `retry(driver, policy)` retries a rejected run (retry.ts). `E`: the driver's error. */
+export interface RetryPolicy<E = unknown> {
     /** Retries after the first failure. */
     readonly times: number;
     /** Delay before each retry (the base delay for exponential backoff). Default 0. */
     readonly delayMs?: number;
     readonly backoff?: 'fixed' | 'exponential';
+    /** Full jitter: wait a random time between 0 and the computed delay, so clients spread out. */
+    readonly jitter?: boolean;
+    /**
+     * Which failures to retry, given the driver's typed error (its `toError`, else the thrown
+     * value). Default: every failure. For `@gyral/http`, `retryableHttpError`.
+     */
+    readonly retryIf?: (error: E) => boolean;
 }
 export interface DriverContext<O = unknown> {
     /** Aborts when the command is switched away or its component disconnects. */
@@ -24,15 +32,35 @@ export interface Driver<I, O, E = unknown> {
     readonly run: (input: I, ctx: DriverContext<O>) => O | Promise<O>;
     /** Default policy for this driver's commands. Default `'merge'`. */
     readonly concurrency?: Concurrency;
-    readonly retry?: RetryPolicy;
     /** Turns a thrown or rejected value into this driver's typed error. */
     readonly toError?: (cause: unknown) => E;
 }
-/** Any driver, with its input type erased. */
+/**
+ * Any driver, with its input type erased. Every `Driver<I, O, E>` (from `defineDriver`,
+ * `subscription`, a test fake) is assignable to it as is: no cast.
+ */
 export type AnyDriver = Driver<never, unknown>;
-/** Drivers substituted by name (test fakes, configured instances). */
+/**
+ * A driver with no implementation of its own (`defineDriver<I, O, E>('session')`): commands built
+ * from it are typed by `I`, `O` and `E`, and it runs only when `provideDrivers` or `el.drivers`
+ * supplies a driver of that name (ADR 0006 addendum "Driver tokens").
+ */
+export interface DriverToken<E = unknown> {
+    readonly name: string;
+    readonly concurrency?: Concurrency;
+    readonly toError?: (cause: unknown) => E;
+}
+/**
+ * Drivers substituted by name (test fakes, configured instances): `el.drivers`,
+ * `provideDrivers`. Annotate a driver map with this type (or `Record<string, AnyDriver>`), not
+ * `Record<string, Driver<unknown, unknown>>`, which rejects drivers with a typed input.
+ */
 export type DriverOverrides = Readonly<Record<string, AnyDriver>>;
-/** A side effect described as data, plus pure mappers from its outcome to messages. */
+/**
+ * A side effect described as data, plus pure mappers from its outcome to messages. Commands
+ * that answer with no message (`focus()`, `call()`, `navigate()`) are `Command<never>`,
+ * which fits wherever a `Command<Msg>` is expected: no type argument needed.
+ */
 export interface Command<M> {
     readonly driver: AnyDriver;
     readonly input: unknown;
@@ -40,24 +68,38 @@ export interface Command<M> {
     readonly key?: string;
     readonly concurrency?: Concurrency;
     readonly onSuccess: (output: unknown) => M | undefined;
-    /** If omitted, failures are logged and dropped. */
+    /** If omitted, a failure is reported to the error channel (ADR 0024, G0041). */
     readonly onFailure?: (error: unknown) => M | undefined;
 }
+/**
+ * How a command's outcome becomes a message. Every field is optional: without `onSuccess` the
+ * command answers with nothing (`Command<never>`); without `onFailure` a failure is reported to
+ * the error channel (ADR 0024).
+ */
 export interface CommandHandlers<O, E, MS, MF = MS> {
-    readonly onSuccess: (output: O) => MS | undefined;
+    readonly onSuccess?: (output: O) => MS | undefined;
     readonly onFailure?: (error: E) => MF | undefined;
     readonly key?: string;
     readonly concurrency?: Concurrency;
 }
 /**
  * What a reducer (or `init`) returns: new state, optionally with commands to run. Commands may
- * also answer with the framework message `IntentRejected` (e.g. `submitForm` in @gyral/http
+ * also answer with the framework message `IntentRejected` (e.g. `submitForm` in `@gyral/http`
  * when the server rejects a form), which goes to the optional `IntentRejected` reducer.
  */
 export type Next<S, M> = S | readonly [S, ReadonlyArray<Command<M | IntentRejected>>];
-/** Identity helper so driver literals infer `I`, `O` and `E`. */
-export declare function defineDriver<I, O, E = unknown>(driver: Driver<I, O, E>): Driver<I, O, E>;
-/** Builds a command whose mappers are typed by the driver's input, output and error. */
-export declare function command<I, O, E, MS, MF = MS>(driver: Driver<I, O, E>, input: I, handlers: CommandHandlers<O, E, MS, MF>): Command<MS | MF>;
+/**
+ * Defines a driver. Given an implementation (`run`), it returns it as is, so literals infer
+ * `I`, `O` and `E`. Given only a name, it returns a typed **token**: commands built from it are
+ * typed, and it runs only when a provider (`provideDrivers`) or `el.drivers` supplies a driver of
+ * that name. A command whose token nothing provides fails with G0043, naming the driver.
+ */
+export declare function defineDriver<I, O, E = unknown>(spec: Driver<I, O, E> | DriverToken<E> | string): Driver<I, O, E>;
+/**
+ * Builds a command whose mappers are typed by the driver's input, output and error. Without
+ * handlers (or without `onSuccess`) it answers with no message: `command(log, line)` is a
+ * `Command<never>`, which fits any `Command<Msg>`.
+ */
+export declare function command<I, O, E, const MS = never, const MF = MS>(driver: Driver<I, O, E>, input: I, handlers?: CommandHandlers<O, E, MS, MF>): Command<MS | MF>;
 /** Splits a reducer result into state and commands. State is never an array (ADR 0006). */
 export declare function splitNext<S, M>(next: Next<S, M>): readonly [S, ReadonlyArray<Command<M | IntentRejected>>];

package/dist/command.js

@@ -3,21 +3,35 @@
 // that build no commands don't bundle it.
 import { features } from './features.js';
 import { hostInterpreter } from './internal/interpreter.js';
-/** Identity helper so driver literals infer `I`, `O` and `E`. */
-export function defineDriver(driver) {
-    return driver;
+import { unprovided } from './internal/token.js';
+/**
+ * Defines a driver. Given an implementation (`run`), it returns it as is, so literals infer
+ * `I`, `O` and `E`. Given only a name, it returns a typed **token**: commands built from it are
+ * typed, and it runs only when a provider (`provideDrivers`) or `el.drivers` supplies a driver of
+ * that name. A command whose token nothing provides fails with G0043, naming the driver.
+ */
+export function defineDriver(spec) {
+    if (typeof spec === 'string')
+        return { name: spec, run: unprovided };
+    return 'run' in spec ? spec : { ...spec, run: unprovided };
 }
-/** Builds a command whose mappers are typed by the driver's input, output and error. */
-// Two message parameters so success and failure may produce different variants.
-export function command(driver, input, handlers) {
+const none = () => undefined;
+/**
+ * Builds a command whose mappers are typed by the driver's input, output and error. Without
+ * handlers (or without `onSuccess`) it answers with no message: `command(log, line)` is a
+ * `Command<never>`, which fits any `Command<Msg>`.
+ */
+// Two message parameters so success and failure may produce different variants; `const` keeps
+// a mapper's `{ _tag: 'Loaded' }` literal, so no type arguments are needed.
+export function command(driver, input, handlers = {}) {
     features.commands = hostInterpreter;
-    const { onFailure, key, concurrency } = handlers;
+    const { onSuccess = none, onFailure, key, concurrency } = handlers;
+    // Sound: the interpreter only passes this driver's output and toError() result.
     return {
-        driver: driver,
+        driver,
         input,
-        // Sound: the interpreter only passes this driver's output and toError() result.
-        onSuccess: (output) => handlers.onSuccess(output),
-        ...(onFailure === undefined ? {} : { onFailure: (error) => onFailure(error) }),
+        onSuccess,
+        ...(onFailure && { onFailure }),
         ...(key === undefined ? {} : { key }),
         ...(concurrency === undefined ? {} : { concurrency }),
     };

package/dist/command.js.map

@@ -1 +1 @@
-{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,+FAA+F;AAC/F,0CAA0C;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAoE5D,iEAAiE;AACjE,MAAM,UAAU,YAAY,CAAoB,MAAuB;IACrE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wFAAwF;AACxF,gFAAgF;AAChF,MAAM,UAAU,OAAO,CACrB,MAAuB,EACvB,KAAQ,EACR,QAAuC;IAEvC,QAAQ,CAAC,QAAQ,GAAG,eAAe,CAAC;IACpC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC;IACjD,OAAO;QACL,MAAM,EAAE,MAAM;QACd,KAAK;QACL,gFAAgF;QAChF,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAW,CAAC;QACtD,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,SAAS,CAAC,KAAU,CAAC,EAAE,CAAC;QAC5F,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;QACrC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;KACtD,CAAC;AACJ,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,SAAS,CACvB,IAAgB;IAEhB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,OAAO,IAAgE,CAAC;IAC1E,CAAC;IACD,OAAO,CAAC,IAAS,EAAE,EAAE,CAAC,CAAC;AACzB,CAAC","sourcesContent":["// Effects as data (docs/design-docs/0006-effects-and-drivers.md). Plain TypeScript only: the\n// interpreter lives in ./internal/ (ADR 0015); `command()` registers it (features.ts), so apps\n// that build no commands don't bundle it.\nimport { features } from './features.js';\nimport { hostInterpreter } from './internal/interpreter.js';\nimport type { IntentRejected } from './types.js';\n\n/** How commands in the same lane interact. See ADR 0006 for the table. */\nexport type Concurrency = 'merge' | 'switch' | 'exhaust' | 'queue';\n\nexport interface RetryPolicy {\n  /** Retries after the first failure. */\n  readonly times: number;\n  /** Delay before each retry (the base delay for exponential backoff). Default 0. */\n  readonly delayMs?: number;\n  readonly backoff?: 'fixed' | 'exponential';\n}\n\nexport interface DriverContext<O = unknown> {\n  /** Aborts when the command is switched away or its component disconnects. */\n  readonly signal: AbortSignal;\n  /**\n   * Delivers an extra result while the command runs (streaming drivers: routers, timers,\n   * sockets). Each value goes through the command's `onSuccess`. Ignored once the command\n   * has settled or been aborted. A streaming `run` usually never resolves; abort ends it.\n   */\n  readonly emit: (output: O) => void;\n}\n\n/** Performs one kind of side effect. A plain object: easy to fake in tests. */\nexport interface Driver<I, O, E = unknown> {\n  readonly name: string;\n  readonly run: (input: I, ctx: DriverContext<O>) => O | Promise<O>;\n  /** Default policy for this driver's commands. Default `'merge'`. */\n  readonly concurrency?: Concurrency;\n  readonly retry?: RetryPolicy;\n  /** Turns a thrown or rejected value into this driver's typed error. */\n  readonly toError?: (cause: unknown) => E;\n}\n\n/** Any driver, with its input type erased. */\nexport type AnyDriver = Driver<never, unknown>;\n\n/** Drivers substituted by name (test fakes, configured instances). */\nexport type DriverOverrides = Readonly<Record<string, AnyDriver>>;\n\n/** A side effect described as data, plus pure mappers from its outcome to messages. */\nexport interface Command<M> {\n  readonly driver: AnyDriver;\n  readonly input: unknown;\n  /** Concurrency lane. Default: the driver's name. */\n  readonly key?: string;\n  readonly concurrency?: Concurrency;\n  readonly onSuccess: (output: unknown) => M | undefined;\n  /** If omitted, failures are logged and dropped. */\n  readonly onFailure?: (error: unknown) => M | undefined;\n}\n\nexport interface CommandHandlers<O, E, MS, MF = MS> {\n  readonly onSuccess: (output: O) => MS | undefined;\n  readonly onFailure?: (error: E) => MF | undefined;\n  readonly key?: string;\n  readonly concurrency?: Concurrency;\n}\n\n/**\n * What a reducer (or `init`) returns: new state, optionally with commands to run. Commands may\n * also answer with the framework message `IntentRejected` (e.g. `submitForm` in @gyral/http\n * when the server rejects a form), which goes to the optional `IntentRejected` reducer.\n */\nexport type Next<S, M> = S | readonly [S, ReadonlyArray<Command<M | IntentRejected>>];\n\n/** Identity helper so driver literals infer `I`, `O` and `E`. */\nexport function defineDriver<I, O, E = unknown>(driver: Driver<I, O, E>): Driver<I, O, E> {\n  return driver;\n}\n\n/** Builds a command whose mappers are typed by the driver's input, output and error. */\n// Two message parameters so success and failure may produce different variants.\nexport function command<I, O, E, MS, MF = MS>(\n  driver: Driver<I, O, E>,\n  input: I,\n  handlers: CommandHandlers<O, E, MS, MF>,\n): Command<MS | MF> {\n  features.commands = hostInterpreter;\n  const { onFailure, key, concurrency } = handlers;\n  return {\n    driver: driver,\n    input,\n    // Sound: the interpreter only passes this driver's output and toError() result.\n    onSuccess: (output) => handlers.onSuccess(output as O),\n    ...(onFailure === undefined ? {} : { onFailure: (error: unknown) => onFailure(error as E) }),\n    ...(key === undefined ? {} : { key }),\n    ...(concurrency === undefined ? {} : { concurrency }),\n  };\n}\n\n/** Splits a reducer result into state and commands. State is never an array (ADR 0006). */\nexport function splitNext<S, M>(\n  next: Next<S, M>,\n): readonly [S, ReadonlyArray<Command<M | IntentRejected>>] {\n  if (Array.isArray(next) && next.length === 2 && Array.isArray(next[1])) {\n    return next as readonly [S, ReadonlyArray<Command<M | IntentRejected>>];\n  }\n  return [next as S, []];\n}\n"]}
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,+FAA+F;AAC/F,0CAA0C;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAsGjD;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,IAA+C;IAE/C,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC;IACrE,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,IAAI,GAAG,GAAc,EAAE,CAAC,SAAS,CAAC;AAExC;;;;GAIG;AACH,8FAA8F;AAC9F,4EAA4E;AAC5E,MAAM,UAAU,OAAO,CACrB,MAAuB,EACvB,KAAQ,EACR,WAA0C,EAAE;IAE5C,QAAQ,CAAC,QAAQ,GAAG,eAAe,CAAC;IACpC,MAAM,EAAE,SAAS,GAAG,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC;IACnE,gFAAgF;IAChF,OAAO;QACL,MAAM;QACN,KAAK;QACL,SAAS;QACT,GAAG,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC/B,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;QACrC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;KAClC,CAAC;AACxB,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,SAAS,CACvB,IAAgB;IAEhB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,OAAO,IAAgE,CAAC;IAC1E,CAAC;IACD,OAAO,CAAC,IAAS,EAAE,EAAE,CAAC,CAAC;AACzB,CAAC","sourcesContent":["// Effects as data (docs/design-docs/0006-effects-and-drivers.md). Plain TypeScript only: the\n// interpreter lives in ./internal/ (ADR 0015); `command()` registers it (features.ts), so apps\n// that build no commands don't bundle it.\nimport { features } from './features.js';\nimport { hostInterpreter } from './internal/interpreter.js';\nimport { unprovided } from './internal/token.js';\nimport type { IntentRejected } from './types.js';\n\n/** How commands in the same lane interact. See ADR 0006 for the table. */\nexport type Concurrency = 'merge' | 'switch' | 'exhaust' | 'queue';\n\n/** How `retry(driver, policy)` retries a rejected run (retry.ts). `E`: the driver's error. */\nexport interface RetryPolicy<E = unknown> {\n  /** Retries after the first failure. */\n  readonly times: number;\n  /** Delay before each retry (the base delay for exponential backoff). Default 0. */\n  readonly delayMs?: number;\n  readonly backoff?: 'fixed' | 'exponential';\n  /** Full jitter: wait a random time between 0 and the computed delay, so clients spread out. */\n  readonly jitter?: boolean;\n  /**\n   * Which failures to retry, given the driver's typed error (its `toError`, else the thrown\n   * value). Default: every failure. For `@gyral/http`, `retryableHttpError`.\n   */\n  readonly retryIf?: (error: E) => boolean;\n}\n\nexport interface DriverContext<O = unknown> {\n  /** Aborts when the command is switched away or its component disconnects. */\n  readonly signal: AbortSignal;\n  /**\n   * Delivers an extra result while the command runs (streaming drivers: routers, timers,\n   * sockets). Each value goes through the command's `onSuccess`. Ignored once the command\n   * has settled or been aborted. A streaming `run` usually never resolves; abort ends it.\n   */\n  readonly emit: (output: O) => void;\n}\n\n/** Performs one kind of side effect. A plain object: easy to fake in tests. */\nexport interface Driver<I, O, E = unknown> {\n  readonly name: string;\n  readonly run: (input: I, ctx: DriverContext<O>) => O | Promise<O>;\n  /** Default policy for this driver's commands. Default `'merge'`. */\n  readonly concurrency?: Concurrency;\n  /** Turns a thrown or rejected value into this driver's typed error. */\n  readonly toError?: (cause: unknown) => E;\n}\n\n/**\n * Any driver, with its input type erased. Every `Driver<I, O, E>` (from `defineDriver`,\n * `subscription`, a test fake) is assignable to it as is: no cast.\n */\nexport type AnyDriver = Driver<never, unknown>;\n\n/**\n * A driver with no implementation of its own (`defineDriver<I, O, E>('session')`): commands built\n * from it are typed by `I`, `O` and `E`, and it runs only when `provideDrivers` or `el.drivers`\n * supplies a driver of that name (ADR 0006 addendum \"Driver tokens\").\n */\nexport interface DriverToken<E = unknown> {\n  readonly name: string;\n  readonly concurrency?: Concurrency;\n  readonly toError?: (cause: unknown) => E;\n}\n\n/**\n * Drivers substituted by name (test fakes, configured instances): `el.drivers`,\n * `provideDrivers`. Annotate a driver map with this type (or `Record<string, AnyDriver>`), not\n * `Record<string, Driver<unknown, unknown>>`, which rejects drivers with a typed input.\n */\nexport type DriverOverrides = Readonly<Record<string, AnyDriver>>;\n\n/**\n * A side effect described as data, plus pure mappers from its outcome to messages. Commands\n * that answer with no message (`focus()`, `call()`, `navigate()`) are `Command<never>`,\n * which fits wherever a `Command<Msg>` is expected: no type argument needed.\n */\nexport interface Command<M> {\n  readonly driver: AnyDriver;\n  readonly input: unknown;\n  /** Concurrency lane. Default: the driver's name. */\n  readonly key?: string;\n  readonly concurrency?: Concurrency;\n  readonly onSuccess: (output: unknown) => M | undefined;\n  /** If omitted, a failure is reported to the error channel (ADR 0024, G0041). */\n  readonly onFailure?: (error: unknown) => M | undefined;\n}\n\n/**\n * How a command's outcome becomes a message. Every field is optional: without `onSuccess` the\n * command answers with nothing (`Command<never>`); without `onFailure` a failure is reported to\n * the error channel (ADR 0024).\n */\nexport interface CommandHandlers<O, E, MS, MF = MS> {\n  readonly onSuccess?: (output: O) => MS | undefined;\n  readonly onFailure?: (error: E) => MF | undefined;\n  readonly key?: string;\n  readonly concurrency?: Concurrency;\n}\n\n/**\n * What a reducer (or `init`) returns: new state, optionally with commands to run. Commands may\n * also answer with the framework message `IntentRejected` (e.g. `submitForm` in `@gyral/http`\n * when the server rejects a form), which goes to the optional `IntentRejected` reducer.\n */\nexport type Next<S, M> = S | readonly [S, ReadonlyArray<Command<M | IntentRejected>>];\n\n/**\n * Defines a driver. Given an implementation (`run`), it returns it as is, so literals infer\n * `I`, `O` and `E`. Given only a name, it returns a typed **token**: commands built from it are\n * typed, and it runs only when a provider (`provideDrivers`) or `el.drivers` supplies a driver of\n * that name. A command whose token nothing provides fails with G0043, naming the driver.\n */\nexport function defineDriver<I, O, E = unknown>(\n  spec: Driver<I, O, E> | DriverToken<E> | string,\n): Driver<I, O, E> {\n  if (typeof spec === 'string') return { name: spec, run: unprovided };\n  return 'run' in spec ? spec : { ...spec, run: unprovided };\n}\n\nconst none = (): undefined => undefined;\n\n/**\n * Builds a command whose mappers are typed by the driver's input, output and error. Without\n * handlers (or without `onSuccess`) it answers with no message: `command(log, line)` is a\n * `Command<never>`, which fits any `Command<Msg>`.\n */\n// Two message parameters so success and failure may produce different variants; `const` keeps\n// a mapper's `{ _tag: 'Loaded' }` literal, so no type arguments are needed.\nexport function command<I, O, E, const MS = never, const MF = MS>(\n  driver: Driver<I, O, E>,\n  input: I,\n  handlers: CommandHandlers<O, E, MS, MF> = {},\n): Command<MS | MF> {\n  features.commands = hostInterpreter;\n  const { onSuccess = none, onFailure, key, concurrency } = handlers;\n  // Sound: the interpreter only passes this driver's output and toError() result.\n  return {\n    driver,\n    input,\n    onSuccess,\n    ...(onFailure && { onFailure }),\n    ...(key === undefined ? {} : { key }),\n    ...(concurrency === undefined ? {} : { concurrency }),\n  } as Command<MS | MF>;\n}\n\n/** Splits a reducer result into state and commands. State is never an array (ADR 0006). */\nexport function splitNext<S, M>(\n  next: Next<S, M>,\n): readonly [S, ReadonlyArray<Command<M | IntentRejected>>] {\n  if (Array.isArray(next) && next.length === 2 && Array.isArray(next[1])) {\n    return next as readonly [S, ReadonlyArray<Command<M | IntentRejected>>];\n  }\n  return [next as S, []];\n}\n"]}