@gyral/core 0.2.0 → 0.3.1

package/dist/drivers-scope.js

@@ -1,8 +1,3 @@
-// Tree-scoped driver overrides (gyral-czi.35, ADR 0006 addendum): which driver a command uses.
-// Resolution: el.drivers → nearest driver provider (across shadow roots) → spec.drivers →
-// the command's own driver. Mirrors <gyral-stores> (ADR 0013) for stores.
-import { isServer } from 'lit';
-const onServer = isServer;
 /** Provider element name: `<gyral-drivers .drivers=${{ http: fake }}>…</gyral-drivers>`. */
 export const DRIVERS_ELEMENT = 'gyral-drivers';
 // Elements registered with provideDrivers() (any element can act as a provider).
@@ -30,11 +25,9 @@ function overridesOf(node) {
 /**
  * The override for `name` from the nearest provider that has one. Providers nest: an inner
  * provider without that driver lets an outer one supply it. Commands never run on the server,
- * so there is nothing to resolve there.
+ * so only the browser calls this.
  */
 export function providedDriver(host, name) {
-    if (onServer)
-        return undefined;
     for (let node = host.parentNode; node !== null;) {
         if (node instanceof Element) {
             const driver = overridesOf(node)?.[name];

package/dist/drivers-scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"drivers-scope.js","sourceRoot":"","sources":["../src/drivers-scope.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,0FAA0F;AAC1F,0EAA0E;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAG/B,MAAM,QAAQ,GAAY,QAAQ,CAAC;AAEnC,4FAA4F;AAC5F,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAE/C,iFAAiF;AACjF,MAAM,QAAQ,GAAG,IAAI,OAAO,EAA4B,CAAC;AAEzD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,OAAwB;IACvE,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,OAAO;YAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClE,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAa;IAChC,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAChD,IAAI,IAAI,CAAC,SAAS,KAAK,eAAe;QAAE,OAAO,SAAS,CAAC;IACzD,OAAQ,IAAgD,CAAC,OAAO,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAa,EAAE,IAAY;IACxD,IAAI,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC/B,KAAK,IAAI,IAAI,GAAgB,IAAI,CAAC,UAAU,EAAE,IAAI,KAAK,IAAI,GAAG,CAAC;QAC7D,IAAI,IAAI,YAAY,OAAO,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;QAC1C,CAAC;QACD,IAAI,GAAG,IAAI,YAAY,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;IAClE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["// Tree-scoped driver overrides (gyral-czi.35, ADR 0006 addendum): which driver a command uses.\n// Resolution: el.drivers → nearest driver provider (across shadow roots) → spec.drivers →\n// the command's own driver. Mirrors <gyral-stores> (ADR 0013) for stores.\nimport { isServer } from 'lit';\nimport type { AnyDriver, DriverOverrides } from './command.js';\n\nconst onServer: boolean = isServer;\n\n/** Provider element name: `<gyral-drivers .drivers=${{ http: fake }}>…</gyral-drivers>`. */\nexport const DRIVERS_ELEMENT = 'gyral-drivers';\n\n// Elements registered with provideDrivers() (any element can act as a provider).\nconst provided = new WeakMap<Element, DriverOverrides>();\n\n/**\n * Makes `element` a driver provider for every Gyral component below it (including inside\n * shadow roots). Returns a function that removes the overrides. Use it on a test container\n * or an app root; a `<gyral-drivers>` element with a `.drivers` property works the same way.\n */\nexport function provideDrivers(element: Element, drivers: DriverOverrides): () => void {\n  provided.set(element, drivers);\n  return () => {\n    if (provided.get(element) === drivers) provided.delete(element);\n  };\n}\n\nfunction overridesOf(node: Element): DriverOverrides | undefined {\n  const registered = provided.get(node);\n  if (registered !== undefined) return registered;\n  if (node.localName !== DRIVERS_ELEMENT) return undefined;\n  return (node as Element & { drivers?: DriverOverrides }).drivers;\n}\n\n/**\n * The override for `name` from the nearest provider that has one. Providers nest: an inner\n * provider without that driver lets an outer one supply it. Commands never run on the server,\n * so there is nothing to resolve there.\n */\nexport function providedDriver(host: Element, name: string): AnyDriver | undefined {\n  if (onServer) return undefined;\n  for (let node: Node | null = host.parentNode; node !== null;) {\n    if (node instanceof Element) {\n      const driver = overridesOf(node)?.[name];\n      if (driver !== undefined) return driver;\n    }\n    node = node instanceof ShadowRoot ? node.host : node.parentNode;\n  }\n  return undefined;\n}\n"]}
+{"version":3,"file":"drivers-scope.js","sourceRoot":"","sources":["../src/drivers-scope.ts"],"names":[],"mappings":"AAKA,4FAA4F;AAC5F,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAE/C,iFAAiF;AACjF,MAAM,QAAQ,GAAG,IAAI,OAAO,EAA4B,CAAC;AAEzD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,OAAwB;IACvE,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,OAAO;YAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClE,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAa;IAChC,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAChD,IAAI,IAAI,CAAC,SAAS,KAAK,eAAe;QAAE,OAAO,SAAS,CAAC;IACzD,OAAQ,IAAgD,CAAC,OAAO,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAa,EAAE,IAAY;IACxD,KAAK,IAAI,IAAI,GAAgB,IAAI,CAAC,UAAU,EAAE,IAAI,KAAK,IAAI,GAAG,CAAC;QAC7D,IAAI,IAAI,YAAY,OAAO,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;QAC1C,CAAC;QACD,IAAI,GAAG,IAAI,YAAY,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;IAClE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["// Tree-scoped driver overrides (gyral-czi.35, ADR 0006 addendum): which driver a command uses.\n// Resolution: el.drivers → nearest driver provider (across shadow roots) → the command's own\n// driver; a driver token (defineDriver('name')) has no own implementation. Mirrors <gyral-stores> (ADR 0013) for stores.\nimport type { AnyDriver, DriverOverrides } from './command.js';\n\n/** Provider element name: `<gyral-drivers .drivers=${{ http: fake }}>…</gyral-drivers>`. */\nexport const DRIVERS_ELEMENT = 'gyral-drivers';\n\n// Elements registered with provideDrivers() (any element can act as a provider).\nconst provided = new WeakMap<Element, DriverOverrides>();\n\n/**\n * Makes `element` a driver provider for every Gyral component below it (including inside\n * shadow roots). Returns a function that removes the overrides. Use it on a test container\n * or an app root; a `<gyral-drivers>` element with a `.drivers` property works the same way.\n */\nexport function provideDrivers(element: Element, drivers: DriverOverrides): () => void {\n  provided.set(element, drivers);\n  return () => {\n    if (provided.get(element) === drivers) provided.delete(element);\n  };\n}\n\nfunction overridesOf(node: Element): DriverOverrides | undefined {\n  const registered = provided.get(node);\n  if (registered !== undefined) return registered;\n  if (node.localName !== DRIVERS_ELEMENT) return undefined;\n  return (node as Element & { drivers?: DriverOverrides }).drivers;\n}\n\n/**\n * The override for `name` from the nearest provider that has one. Providers nest: an inner\n * provider without that driver lets an outer one supply it. Commands never run on the server,\n * so only the browser calls this.\n */\nexport function providedDriver(host: Element, name: string): AnyDriver | undefined {\n  for (let node: Node | null = host.parentNode; node !== null;) {\n    if (node instanceof Element) {\n      const driver = overridesOf(node)?.[name];\n      if (driver !== undefined) return driver;\n    }\n    node = node instanceof ShadowRoot ? node.host : node.parentNode;\n  }\n  return undefined;\n}\n"]}

package/dist/element-internals.d.ts

@@ -0,0 +1 @@
+export declare function internalsOf(host: HTMLElement): ElementInternals;

package/dist/element-internals.js

@@ -0,0 +1,11 @@
+// Native features share one attachment: attachInternals() may only be called once per host.
+const internals = new WeakMap();
+export function internalsOf(host) {
+    let value = internals.get(host);
+    if (value === undefined) {
+        value = host.attachInternals();
+        internals.set(host, value);
+    }
+    return value;
+}
+//# sourceMappingURL=element-internals.js.map

package/dist/element-internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-internals.js","sourceRoot":"","sources":["../src/element-internals.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,MAAM,SAAS,GAAG,IAAI,OAAO,EAAiC,CAAC;AAE/D,MAAM,UAAU,WAAW,CAAC,IAAiB;IAC3C,IAAI,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,KAAK,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;QAC/B,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["// Native features share one attachment: attachInternals() may only be called once per host.\nconst internals = new WeakMap<HTMLElement, ElementInternals>();\n\nexport function internalsOf(host: HTMLElement): ElementInternals {\n  let value = internals.get(host);\n  if (value === undefined) {\n    value = host.attachInternals();\n    internals.set(host, value);\n  }\n  return value;\n}\n"]}

package/dist/element-types.d.ts

@@ -1,9 +1,11 @@
-import type { LitElement } from 'lit';
 import type { DriverOverrides } from './command.js';
 import type { StoreOverrides } from './store.js';
 import type { ComponentSpec, Tagged } from './types.js';
-/** The custom element class produced by `define()`. */
-export interface GyralElement<S, M extends Tagged> extends LitElement {
+/**
+ * The custom element `define()` produces: a plain `HTMLElement` (view/05-element.md "Public
+ * instance API"). Tests wait for rendering with `settled()`.
+ */
+export interface GyralElement<S, M extends Tagged> extends HTMLElement {
     /** Current model state. */
     readonly state: S;
     /** Feeds a message through `update`, as if an intent had produced it. */
@@ -22,13 +24,17 @@ export interface GyralElement<S, M extends Tagged> extends LitElement {
      */
     initialMessages: readonly Tagged[];
 }
-export interface GyralElementClass<S, M extends Tagged, P, O extends Tagged = never> {
+export interface GyralElementClass<S, M extends Tagged, P, O extends Tagged = never, N extends string = string> {
     /** Instances expose their declared props as settable properties. */
     new (): GyralElement<S, M> & {
         -readonly [K in keyof P]: P[K];
     };
-    readonly spec: ComponentSpec<S, M, P>;
+    readonly spec: ComponentSpec<S, M, P, N>;
     readonly tagName: string;
+    /** Native custom-element registration flag, true when the spec opts into forms. */
+    readonly formAssociated?: boolean;
     /** Type-only: the outputs this component emits (read by `child()`). */
     readonly outputs?: O;
+    /** Type-only: the component's intent names, the keys of `intent` (read by `intentsOf()`). */
+    readonly intentNames?: N;
 }

package/dist/element-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"element-types.js","sourceRoot":"","sources":["../src/element-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { LitElement } from 'lit';\nimport type { DriverOverrides } from './command.js';\nimport type { StoreOverrides } from './store.js';\nimport type { ComponentSpec, Tagged } from './types.js';\n\n/** The custom element class produced by `define()`. */\nexport interface GyralElement<S, M extends Tagged> extends LitElement {\n  /** Current model state. */\n  readonly state: S;\n  /** Feeds a message through `update`, as if an intent had produced it. */\n  send(msg: M): void;\n  /** Per-instance driver substitutions by name (test fakes). Checked before the spec's. */\n  drivers: DriverOverrides;\n  /**\n   * Per-instance store instances by store name (tests, islands). Checked before the nearest\n   * `<gyral-stores>` provider and the document default (ADR 0013).\n   */\n  stores: StoreOverrides;\n  /**\n   * Messages applied through `update` right after `init`, before the first render. The server\n   * uses it to render a rejected form with the same reducer as the JS path (ADR 0008). Ignored\n   * when the element resumes from a hydration seed (the seed already contains their effect).\n   */\n  initialMessages: readonly Tagged[];\n}\n\nexport interface GyralElementClass<S, M extends Tagged, P, O extends Tagged = never> {\n  /** Instances expose their declared props as settable properties. */\n  new (): GyralElement<S, M> & { -readonly [K in keyof P]: P[K] };\n  readonly spec: ComponentSpec<S, M, P>;\n  readonly tagName: string;\n  /** Type-only: the outputs this component emits (read by `child()`). */\n  readonly outputs?: O;\n}\n"]}
+{"version":3,"file":"element-types.js","sourceRoot":"","sources":["../src/element-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { DriverOverrides } from './command.js';\nimport type { StoreOverrides } from './store.js';\nimport type { ComponentSpec, Tagged } from './types.js';\n\n/**\n * The custom element `define()` produces: a plain `HTMLElement` (view/05-element.md \"Public\n * instance API\"). Tests wait for rendering with `settled()`.\n */\nexport interface GyralElement<S, M extends Tagged> extends HTMLElement {\n  /** Current model state. */\n  readonly state: S;\n  /** Feeds a message through `update`, as if an intent had produced it. */\n  send(msg: M): void;\n  /** Per-instance driver substitutions by name (test fakes). Checked before the spec's. */\n  drivers: DriverOverrides;\n  /**\n   * Per-instance store instances by store name (tests, islands). Checked before the nearest\n   * `<gyral-stores>` provider and the document default (ADR 0013).\n   */\n  stores: StoreOverrides;\n  /**\n   * Messages applied through `update` right after `init`, before the first render. The server\n   * uses it to render a rejected form with the same reducer as the JS path (ADR 0008). Ignored\n   * when the element resumes from a hydration seed (the seed already contains their effect).\n   */\n  initialMessages: readonly Tagged[];\n}\n\nexport interface GyralElementClass<\n  S,\n  M extends Tagged,\n  P,\n  O extends Tagged = never,\n  N extends string = string,\n> {\n  /** Instances expose their declared props as settable properties. */\n  new (): GyralElement<S, M> & { -readonly [K in keyof P]: P[K] };\n  readonly spec: ComponentSpec<S, M, P, N>;\n  readonly tagName: string;\n  /** Native custom-element registration flag, true when the spec opts into forms. */\n  readonly formAssociated?: boolean;\n  /** Type-only: the outputs this component emits (read by `child()`). */\n  readonly outputs?: O;\n  /** Type-only: the component's intent names, the keys of `intent` (read by `intentsOf()`). */\n  readonly intentNames?: N;\n}\n"]}

package/dist/element.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentSpec, Tagged } from './types.js';
+/** The element class for `spec` (not yet registered); define() types it for the spec. */
+export declare function elementClass<S, M extends Tagged, P>(tag: string, spec: ComponentSpec<S, M, P>): CustomElementConstructor;

package/dist/element.js

@@ -0,0 +1,322 @@
+// The element define() creates (docs/design-docs/view/05-element.md): a plain HTMLElement
+// subclass. Declared props are prototype accessors over Standard Schema builders; renders go
+// through the global scheduler (view/04-scheduler.md); intents are delegated listeners on the
+// root (ADR 0001). The model side (state, commands, stores) is host-model.ts.
+import { DEVTOOLS_ENABLED, devConnect, devHydrated } from '#devtools';
+import { fail } from './errors.js';
+import { HostModel } from './host-model.js';
+import { hydrationCode, takeSeed, whenHydrationLoads } from '#hydration-loader';
+import { DEFAULT_EVENTS, eventsOf, handleIntent, hostDepth, intentNames, listenForIntents, } from './intent.js';
+import { isLight } from './light-dom.js';
+import { features } from './features.js';
+import { afterRender, markDirty, POST_HYDRATED, POST_INIT, POST_STATES, } from './scheduler.js';
+import { checkSpecFeatures, customStates, errorView, formAssociation } from '#spec-features';
+import { DEV, ERROR_ATTRIBUTE, message, onHookFailure, render, sheetsFor, suspendHooks, } from './view/index.js';
+const DEFER = 'defer-hydration';
+// A hook that throws is reported for the host owning the render root (ADR 0024).
+onHookFailure((error, root) => {
+    const host = root instanceof ShadowRoot ? root.host : root;
+    fail(error, 'hook', message(75, host.localName), { host, tag: host.localName });
+});
+/** The element class for `spec` (not yet registered); define() types it for the spec. */
+export function elementClass(tag, spec) {
+    const table = (spec.props ?? {});
+    const names = Object.keys(table);
+    // Registered by the prop builders (features.ts): set whenever a component declares props.
+    const props = features.props;
+    /** Property sets and seeds: checked in development, kept as given in production (05). */
+    const checked = (props) => props.propertyValue;
+    const attrs = new Map();
+    const light = isLight(spec);
+    let sheets;
+    const parsers = (spec.intent ?? {});
+    const model = spec;
+    if (DEV)
+        checkSpecFeatures(tag, spec);
+    class Element extends HTMLElement {
+        static { this.spec = spec; }
+        static { this.tagName = tag; }
+        static get observedAttributes() {
+            return [...attrs.keys(), DEFER];
+        }
+        static {
+            for (const name of names) {
+                const def = table[name];
+                const attr = def === undefined ? undefined : props.attributeOf(name, def);
+                if (attr !== undefined)
+                    attrs.set(attr, name);
+                Object.defineProperty(this.prototype, name, {
+                    configurable: true,
+                    enumerable: true,
+                    get() {
+                        return this.#values[name];
+                    },
+                    set(value) {
+                        this.#write(name, DEV ? checked(props)(tag, name, table[name], value) : value);
+                    },
+                });
+            }
+        }
+        #values = {};
+        #root;
+        #rendered = false;
+        /** Something changed while disconnected: render on reconnect. */
+        #stale = false;
+        #serverRendered = false;
+        /** The first render adopts the server's DOM (07): resumed from a seed, root not empty. */
+        #hydrating = false;
+        /** init's commands for a server-rendered host: started after its first render. */
+        #afterInit = [];
+        #task = {
+            tag,
+            depth: 0,
+            render: () => {
+                this.#render();
+            },
+        };
+        #model = new HostModel({
+            el: this,
+            tag,
+            props: () => (names.length > 0 ? props.readProps(this.#values, table) : {}),
+            root: () => this.#root,
+            invalidate: (onFrame) => {
+                this.#invalidate(onFrame);
+            },
+        }, model);
+        constructor() {
+            super();
+            const self = this;
+            self['drivers'] ??= {};
+            self['stores'] ??= {};
+            self['initialMessages'] ??= [];
+            // Upgrade capture: a property set before the class was defined hides the accessor.
+            for (const name of names) {
+                if (!Object.hasOwn(this, name))
+                    continue;
+                const value = self[name];
+                Reflect.deleteProperty(this, name);
+                self[name] = value;
+            }
+            formAssociation?.create(this, this.#model, spec.formAssociated);
+        }
+        get state() {
+            return this.#state();
+        }
+        #state() {
+            if (!this.#model.ready && names.length > 0)
+                props.warnMissing(tag, this.#values, table);
+            return this.#model.state(this.initialMessages);
+        }
+        send(msg) {
+            this.#model.dispatch(msg);
+        }
+        connectedCallback() {
+            if (this.#root !== undefined) {
+                this.#connect();
+                return;
+            }
+            this.#resume();
+            this.#begin();
+        }
+        /** `moveBefore()` keeps everything: no disconnect, no re-resolution (view/03-lists.md). */
+        connectedMoveCallback() {
+            // Intentionally empty.
+        }
+        disconnectedCallback() {
+            this.#model.disconnect();
+            // Element hooks' dispose; they run client again after the render on reconnect (02).
+            if (suspendHooks(this.#root))
+                this.#stale = true;
+            if (DEVTOOLS_ENABLED)
+                devConnect(this, tag, false);
+        }
+        attributeChangedCallback(name, _old, raw) {
+            if (name === DEFER) {
+                if (raw === null && this.isConnected && this.#root === undefined)
+                    this.#begin();
+                return;
+            }
+            const prop = attrs.get(name);
+            if (prop !== undefined)
+                this.#write(prop, props.attributeValue(tag, prop, table[prop], name, raw));
+        }
+        #write(name, value) {
+            // The prop's `equals` (prop.ts): `Object.is`, the same JSON for prop.json, or the option.
+            if (table[name]?.equals(this.#values[name], value))
+                return;
+            this.#values[name] = value;
+            if (this.#model.ready)
+                this.#invalidate();
+        }
+        /** Hydration seeds (ADR 0012): the server's state and the props no attribute carried. */
+        #resume() {
+            if (this.#model.ready)
+                return;
+            const seed = takeSeed(this);
+            if (seed === undefined)
+                return;
+            for (const [name, value] of Object.entries(seed.props)) {
+                const def = table[name];
+                if (def === undefined || this.#values[name] !== undefined)
+                    continue;
+                this.#values[name] = DEV ? checked(props)(tag, name, def, value, 'the seed') : value;
+            }
+            this.#afterInit = this.#model.resume(seed);
+            this.#serverRendered = true;
+        }
+        /**
+         * Starts the host, or waits: for the hydration code (a server-rendered host or an island,
+         * view/07-hydration.md "Loading"), then for an island's trigger (released by
+         * attributeChangedCallback).
+         */
+        #begin() {
+            const defer = this.hasAttribute(DEFER);
+            if (hydrationCode === undefined && (this.#serverRendered || defer)) {
+                whenHydrationLoads(() => {
+                    if (this.isConnected && this.#root === undefined)
+                        this.#begin();
+                });
+            }
+            else if (defer && hydrationCode !== null)
+                hydrationCode?.scheduleIsland(this);
+            else
+                this.#start();
+        }
+        #start() {
+            // `shadow: { delegatesFocus }` (05 "Focus"); `true` and `undefined` spread nothing.
+            const root = light
+                ? this
+                : (this.shadowRoot ??
+                    this.attachShadow({ ...spec.shadow, mode: 'open' }));
+            this.#root = root;
+            this.#hydrating = this.#serverRendered && hydrationCode != null && root.hasChildNodes();
+            sheets ??= light ? [] : sheetsFor(spec.styles);
+            // Rendering fresh: a shadow root without a seed (hand-written DSD) or a server-rendered
+            // host whose hydration code failed to load starts empty.
+            // A host that failed on the server (ADR 0024) starts fresh: its content is a fallback.
+            const failedOnServer = this.hasAttribute(ERROR_ATTRIBUTE);
+            if (failedOnServer)
+                this.removeAttribute(ERROR_ATTRIBUTE);
+            if (!this.#hydrating) {
+                if (!light || this.#serverRendered || failedOnServer)
+                    root.replaceChildren();
+                if (!light)
+                    root.adoptedStyleSheets = sheets;
+            }
+            this.#listen(DEFAULT_EVENTS);
+            this.#state(); // init, unless resumed from a seed
+            this.#connect();
+        }
+        #connect() {
+            this.#task.depth = hostDepth(this);
+            const rebound = this.#model.connect();
+            if (DEVTOOLS_ENABLED)
+                devConnect(this, tag, true);
+            if (!this.#rendered || this.#stale || rebound)
+                this.#invalidate();
+        }
+        #invalidate(onFrame = false) {
+            if (this.#root === undefined)
+                return;
+            if (this.isConnected)
+                markDirty(this.#task, onFrame);
+            else
+                this.#stale = true;
+        }
+        /** One render (the scheduler calls it): PropsChanged first, then the view and its commit. */
+        #render() {
+            const root = this.#root;
+            if (root === undefined || !this.isConnected) {
+                this.#stale = true;
+                return;
+            }
+            this.#stale = false;
+            this.#model.syncProps(names);
+            const failure = this.#model.failure;
+            if (failure !== undefined) {
+                // init threw (ADR 0024): the error view, once; nothing else runs for this host.
+                if (!this.#rendered)
+                    this.#fallback(root, failure, undefined);
+                this.#rendered = true;
+                return;
+            }
+            try {
+                const view = spec.view(this.state, intentNames, this.#model.ctx());
+                if (this.#hydrating) {
+                    hydrationCode?.hydrateRoot(this, tag, view, root, light ? undefined : sheets, this.#seen);
+                    this.#hydrating = false;
+                }
+                else
+                    render(view, root, this.#seen);
+                formAssociation?.sync(this, this.state, this.#model.ctx(), root);
+            }
+            catch (cause) {
+                const error = this.#model.fail(cause, 'view', message(31, tag));
+                this.#fallback(root, error, this.state);
+                return; // the first-render steps wait for a render that succeeds
+            }
+            const states = spec.states;
+            const sync = customStates;
+            if (states !== undefined && sync !== undefined) {
+                afterRender(POST_STATES, () => {
+                    sync(this, states(this.state));
+                });
+            }
+            if (this.#rendered)
+                return;
+            this.#rendered = true;
+            if (DEVTOOLS_ENABLED)
+                devHydrated(this, tag, this.#serverRendered);
+            if (this.#model.hasReducer('Hydrated')) {
+                const msg = { _tag: 'Hydrated', serverRendered: this.#serverRendered };
+                afterRender(POST_HYDRATED, () => {
+                    this.#model.dispatch(msg);
+                });
+            }
+            const commands = this.#afterInit;
+            this.#afterInit = [];
+            if (commands.length > 0) {
+                afterRender(POST_INIT, () => {
+                    this.#model.run(commands);
+                });
+            }
+            if (spec.subscriptions !== undefined) {
+                afterRender(POST_INIT, () => {
+                    this.#model.subscribe();
+                });
+            }
+        }
+        /**
+         * Renders `spec.error` (ADR 0024). Without one the root keeps what it shows; a fallback that
+         * throws too is reported and changes nothing.
+         */
+        #fallback(root, error, state) {
+            if (spec.error === undefined || errorView === undefined)
+                return;
+            const view = (failure, at) => spec.error?.(failure, at);
+            if (errorView(view, root, error, state, this.#hydrating, this.#seen, this, tag)) {
+                this.#hydrating = false;
+            }
+        }
+        /** Intent event types this host's root listens for (view/05-element.md "Intent events"). */
+        #listening = new Set();
+        #listen(types) {
+            listenForIntents(this.#root, this.#listening, types, this.#onEvent);
+        }
+        /** Told about each template a render instantiates: listen for what its markup names. */
+        #seen = (markup) => {
+            this.#listen(eventsOf(markup));
+        };
+        #onEvent = (event) => {
+            if (this.#root === undefined)
+                return;
+            handleIntent(event, this.#root, parsers, tag, this.#model, (msg) => {
+                if (msg !== undefined && this.isConnected)
+                    this.#model.dispatch(msg);
+            });
+        };
+    }
+    formAssociation?.install(Element, spec.formAssociated !== undefined);
+    return Element;
+}
+//# sourceMappingURL=element.js.map

package/dist/element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.js","sourceRoot":"","sources":["../src/element.ts"],"names":[],"mappings":"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","sourcesContent":["// The element define() creates (docs/design-docs/view/05-element.md): a plain HTMLElement\n// subclass. Declared props are prototype accessors over Standard Schema builders; renders go\n// through the global scheduler (view/04-scheduler.md); intents are delegated listeners on the\n// root (ADR 0001). The model side (state, commands, stores) is host-model.ts.\nimport { DEVTOOLS_ENABLED, devConnect, devHydrated } from '#devtools';\nimport type { DriverOverrides } from './command.js';\nimport type { GyralElement } from './element-types.js';\nimport { fail, type GyralError } from './errors.js';\nimport { HostModel, type ModelCommand } from './host-model.js';\nimport { hydrationCode, takeSeed, whenHydrationLoads } from '#hydration-loader';\nimport {\n  DEFAULT_EVENTS,\n  eventsOf,\n  handleIntent,\n  hostDepth,\n  intentNames,\n  listenForIntents,\n} from './intent.js';\nimport { isLight } from './light-dom.js';\nimport { features } from './features.js';\nimport type { PropFeature, PropTable, propertyValue } from './props.js';\nimport {\n  afterRender,\n  markDirty,\n  POST_HYDRATED,\n  POST_INIT,\n  POST_STATES,\n  type HostTask,\n} from './scheduler.js';\nimport { checkSpecFeatures, customStates, errorView, formAssociation } from '#spec-features';\nimport type { StoreOverrides } from './store.js';\nimport type { ComponentSpec, IntentNames, IntentParser, Tagged } from './types.js';\nimport {\n  DEV,\n  ERROR_ATTRIBUTE,\n  message,\n  onHookFailure,\n  render,\n  sheetsFor,\n  suspendHooks,\n  type Markup,\n} from './view/index.js';\n\nconst DEFER = 'defer-hydration';\n\n// A hook that throws is reported for the host owning the render root (ADR 0024).\nonHookFailure((error, root) => {\n  const host = root instanceof ShadowRoot ? root.host : (root as Element);\n  fail(error, 'hook', message(75, host.localName), { host, tag: host.localName });\n});\n\ntype Bag = Record<string, unknown>;\n/** The element class for `spec` (not yet registered); define() types it for the spec. */\nexport function elementClass<S, M extends Tagged, P>(\n  tag: string,\n  spec: ComponentSpec<S, M, P>,\n): CustomElementConstructor {\n  const table = (spec.props ?? {}) as PropTable;\n  const names = Object.keys(table);\n  // Registered by the prop builders (features.ts): set whenever a component declares props.\n  const props = features.props as PropFeature;\n  /** Property sets and seeds: checked in development, kept as given in production (05). */\n  const checked = (props: PropFeature): typeof propertyValue =>\n    props.propertyValue as typeof propertyValue;\n  const attrs = new Map<string, string>();\n  const light = isLight(spec);\n  let sheets: CSSStyleSheet[] | undefined;\n  const parsers = (spec.intent ?? {}) as Readonly<\n    Record<string, IntentParser<M> | true | undefined>\n  >;\n  const model = spec as unknown as ComponentSpec<S, Tagged, P>;\n  if (DEV) checkSpecFeatures(tag, spec);\n\n  class Element extends HTMLElement implements GyralElement<S, M> {\n    static readonly spec = spec;\n    static readonly tagName = tag;\n    static get observedAttributes(): string[] {\n      return [...attrs.keys(), DEFER];\n    }\n\n    static {\n      for (const name of names) {\n        const def = table[name];\n        const attr = def === undefined ? undefined : props.attributeOf(name, def);\n        if (attr !== undefined) attrs.set(attr, name);\n        Object.defineProperty(this.prototype, name, {\n          configurable: true,\n          enumerable: true,\n          get(this: Element): unknown {\n            return this.#values[name];\n          },\n          set(this: Element, value: unknown) {\n            this.#write(name, DEV ? checked(props)(tag, name, table[name], value) : value);\n          },\n        });\n      }\n    }\n\n    declare drivers: DriverOverrides;\n    declare stores: StoreOverrides;\n    declare initialMessages: readonly Tagged[];\n\n    #values: Bag = {};\n    #root: ShadowRoot | HTMLElement | undefined;\n    #rendered = false;\n    /** Something changed while disconnected: render on reconnect. */\n    #stale = false;\n    #serverRendered = false;\n    /** The first render adopts the server's DOM (07): resumed from a seed, root not empty. */\n    #hydrating = false;\n    /** init's commands for a server-rendered host: started after its first render. */\n    #afterInit: readonly ModelCommand[] = [];\n    #task: HostTask = {\n      tag,\n      depth: 0,\n      render: () => {\n        this.#render();\n      },\n    };\n    #model = new HostModel<S, P>(\n      {\n        el: this,\n        tag,\n        props: () => (names.length > 0 ? props.readProps(this.#values, table) : {}),\n        root: () => this.#root,\n        invalidate: (onFrame) => {\n          this.#invalidate(onFrame);\n        },\n      },\n      model,\n    );\n\n    constructor() {\n      super();\n      const self = this as unknown as Bag;\n      self['drivers'] ??= {};\n      self['stores'] ??= {};\n      self['initialMessages'] ??= [];\n      // Upgrade capture: a property set before the class was defined hides the accessor.\n      for (const name of names) {\n        if (!Object.hasOwn(this, name)) continue;\n        const value = self[name];\n        Reflect.deleteProperty(this, name);\n        self[name] = value;\n      }\n      formAssociation?.create(this, this.#model, spec.formAssociated);\n    }\n\n    get state(): S {\n      return this.#state();\n    }\n\n    #state(): S {\n      if (!this.#model.ready && names.length > 0) props.warnMissing(tag, this.#values, table);\n      return this.#model.state(this.initialMessages);\n    }\n\n    send(msg: M): void {\n      this.#model.dispatch(msg);\n    }\n\n    connectedCallback(): void {\n      if (this.#root !== undefined) {\n        this.#connect();\n        return;\n      }\n      this.#resume();\n      this.#begin();\n    }\n\n    /** `moveBefore()` keeps everything: no disconnect, no re-resolution (view/03-lists.md). */\n    connectedMoveCallback(): void {\n      // Intentionally empty.\n    }\n\n    disconnectedCallback(): void {\n      this.#model.disconnect();\n      // Element hooks' dispose; they run client again after the render on reconnect (02).\n      if (suspendHooks(this.#root)) this.#stale = true;\n      if (DEVTOOLS_ENABLED) devConnect(this, tag, false);\n    }\n\n    attributeChangedCallback(name: string, _old: string | null, raw: string | null): void {\n      if (name === DEFER) {\n        if (raw === null && this.isConnected && this.#root === undefined) this.#begin();\n        return;\n      }\n      const prop = attrs.get(name);\n      if (prop !== undefined)\n        this.#write(prop, props.attributeValue(tag, prop, table[prop], name, raw));\n    }\n\n    #write(name: string, value: unknown): void {\n      // The prop's `equals` (prop.ts): `Object.is`, the same JSON for prop.json, or the option.\n      if (table[name]?.equals(this.#values[name], value)) return;\n      this.#values[name] = value;\n      if (this.#model.ready) this.#invalidate();\n    }\n\n    /** Hydration seeds (ADR 0012): the server's state and the props no attribute carried. */\n    #resume(): void {\n      if (this.#model.ready) return;\n      const seed = takeSeed(this);\n      if (seed === undefined) return;\n      for (const [name, value] of Object.entries(seed.props)) {\n        const def = table[name];\n        if (def === undefined || this.#values[name] !== undefined) continue;\n        this.#values[name] = DEV ? checked(props)(tag, name, def, value, 'the seed') : value;\n      }\n      this.#afterInit = this.#model.resume(seed);\n      this.#serverRendered = true;\n    }\n\n    /**\n     * Starts the host, or waits: for the hydration code (a server-rendered host or an island,\n     * view/07-hydration.md \"Loading\"), then for an island's trigger (released by\n     * attributeChangedCallback).\n     */\n    #begin(): void {\n      const defer = this.hasAttribute(DEFER);\n      if (hydrationCode === undefined && (this.#serverRendered || defer)) {\n        whenHydrationLoads(() => {\n          if (this.isConnected && this.#root === undefined) this.#begin();\n        });\n      } else if (defer && hydrationCode !== null) hydrationCode?.scheduleIsland(this);\n      else this.#start();\n    }\n\n    #start(): void {\n      // `shadow: { delegatesFocus }` (05 \"Focus\"); `true` and `undefined` spread nothing.\n      const root = light\n        ? this\n        : (this.shadowRoot ??\n          this.attachShadow({ ...(spec.shadow as object | undefined), mode: 'open' }));\n      this.#root = root;\n      this.#hydrating = this.#serverRendered && hydrationCode != null && root.hasChildNodes();\n      sheets ??= light ? [] : sheetsFor(spec.styles);\n      // Rendering fresh: a shadow root without a seed (hand-written DSD) or a server-rendered\n      // host whose hydration code failed to load starts empty.\n      // A host that failed on the server (ADR 0024) starts fresh: its content is a fallback.\n      const failedOnServer = this.hasAttribute(ERROR_ATTRIBUTE);\n      if (failedOnServer) this.removeAttribute(ERROR_ATTRIBUTE);\n      if (!this.#hydrating) {\n        if (!light || this.#serverRendered || failedOnServer) root.replaceChildren();\n        if (!light) (root as ShadowRoot).adoptedStyleSheets = sheets;\n      }\n      this.#listen(DEFAULT_EVENTS);\n      this.#state(); // init, unless resumed from a seed\n      this.#connect();\n    }\n\n    #connect(): void {\n      this.#task.depth = hostDepth(this);\n      const rebound = this.#model.connect();\n      if (DEVTOOLS_ENABLED) devConnect(this, tag, true);\n      if (!this.#rendered || this.#stale || rebound) this.#invalidate();\n    }\n\n    #invalidate(onFrame = false): void {\n      if (this.#root === undefined) return;\n      if (this.isConnected) markDirty(this.#task, onFrame);\n      else this.#stale = true;\n    }\n\n    /** One render (the scheduler calls it): PropsChanged first, then the view and its commit. */\n    #render(): void {\n      const root = this.#root;\n      if (root === undefined || !this.isConnected) {\n        this.#stale = true;\n        return;\n      }\n      this.#stale = false;\n      this.#model.syncProps(names);\n      const failure = this.#model.failure;\n      if (failure !== undefined) {\n        // init threw (ADR 0024): the error view, once; nothing else runs for this host.\n        if (!this.#rendered) this.#fallback(root, failure, undefined);\n        this.#rendered = true;\n        return;\n      }\n      try {\n        const view = spec.view(this.state, intentNames as IntentNames<string>, this.#model.ctx());\n        if (this.#hydrating) {\n          hydrationCode?.hydrateRoot(this, tag, view, root, light ? undefined : sheets, this.#seen);\n          this.#hydrating = false;\n        } else render(view, root, this.#seen);\n        formAssociation?.sync(this, this.state, this.#model.ctx(), root);\n      } catch (cause) {\n        const error = this.#model.fail(cause, 'view', message(31, tag));\n        this.#fallback(root, error, this.state);\n        return; // the first-render steps wait for a render that succeeds\n      }\n      const states = spec.states;\n      const sync = customStates;\n      if (states !== undefined && sync !== undefined) {\n        afterRender(POST_STATES, () => {\n          sync(this, states(this.state));\n        });\n      }\n      if (this.#rendered) return;\n      this.#rendered = true;\n      if (DEVTOOLS_ENABLED) devHydrated(this, tag, this.#serverRendered);\n      if (this.#model.hasReducer('Hydrated')) {\n        const msg = { _tag: 'Hydrated', serverRendered: this.#serverRendered } as Tagged;\n        afterRender(POST_HYDRATED, () => {\n          this.#model.dispatch(msg);\n        });\n      }\n      const commands = this.#afterInit;\n      this.#afterInit = [];\n      if (commands.length > 0) {\n        afterRender(POST_INIT, () => {\n          this.#model.run(commands);\n        });\n      }\n      if (spec.subscriptions !== undefined) {\n        afterRender(POST_INIT, () => {\n          this.#model.subscribe();\n        });\n      }\n    }\n\n    /**\n     * Renders `spec.error` (ADR 0024). Without one the root keeps what it shows; a fallback that\n     * throws too is reported and changes nothing.\n     */\n    #fallback(root: ShadowRoot | HTMLElement, error: GyralError, state: S | undefined): void {\n      if (spec.error === undefined || errorView === undefined) return;\n      const view = (failure: GyralError, at: never): unknown => spec.error?.(failure, at);\n      if (errorView(view, root, error, state, this.#hydrating, this.#seen, this, tag)) {\n        this.#hydrating = false;\n      }\n    }\n\n    /** Intent event types this host's root listens for (view/05-element.md \"Intent events\"). */\n    #listening = new Set<string>();\n\n    #listen(types: readonly string[]): void {\n      listenForIntents(this.#root as Node, this.#listening, types, this.#onEvent);\n    }\n\n    /** Told about each template a render instantiates: listen for what its markup names. */\n    #seen = (markup: Markup): void => {\n      this.#listen(eventsOf(markup));\n    };\n\n    #onEvent = (event: Event): void => {\n      if (this.#root === undefined) return;\n      handleIntent(event, this.#root, parsers, tag, this.#model, (msg) => {\n        if (msg !== undefined && this.isConnected) this.#model.dispatch(msg);\n      });\n    };\n  }\n  formAssociation?.install(Element, spec.formAssociated !== undefined);\n  return Element;\n}\n"]}

package/dist/error-view.d.ts

@@ -0,0 +1,10 @@
+import { type ErrorPhase, type GyralError } from './errors.js';
+import type { Tagged } from './types.js';
+import { type SeenMarkup } from './view/index.js';
+/**
+ * Renders a component's `error` view into `root`; true when it rendered (a hydrating root is
+ * cleared first). A view that throws too is reported and changes nothing.
+ */
+export declare function renderErrorView(view: (error: GyralError, state: never) => unknown, root: ShadowRoot | HTMLElement, error: GyralError, state: unknown, hydrating: boolean, seen: SeenMarkup, host: HTMLElement, tag: string): boolean;
+/** Sends `Errored` to a component whose `update` handles it (a failed update, parse or command). */
+export declare function sendErrored(dispatch: (msg: Tagged) => unknown, phase: ErrorPhase, error: GyralError): void;

package/dist/error-view.js

@@ -0,0 +1,30 @@
+// Optional error handling a component asks for by name (ADR 0024, gyral-1zd.17): the `error`
+// fallback view and the `Errored` framework message. Reached through `#spec-features`, so a
+// compiled build bundles each only when some module names `error` or `Errored`
+// (compiler/features.ts); the reporting channel itself (errors.ts) is in every app.
+import { fail } from './errors.js';
+import { message, render } from './view/index.js';
+/**
+ * Renders a component's `error` view into `root`; true when it rendered (a hydrating root is
+ * cleared first). A view that throws too is reported and changes nothing.
+ */
+export function renderErrorView(view, root, error, state, hydrating, seen, host, tag) {
+    try {
+        const value = view(error, state);
+        if (hydrating)
+            root.replaceChildren();
+        render(value, root, seen);
+        return true;
+    }
+    catch (cause) {
+        fail(cause, 'view', message(31, tag), { host, tag });
+        return false;
+    }
+}
+/** Sends `Errored` to a component whose `update` handles it (a failed update, parse or command). */
+export function sendErrored(dispatch, phase, error) {
+    if (phase === 'update' || phase === 'parse' || phase === 'command') {
+        dispatch({ _tag: 'Errored', phase, error });
+    }
+}
+//# sourceMappingURL=error-view.js.map

package/dist/error-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-view.js","sourceRoot":"","sources":["../src/error-view.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,4FAA4F;AAC5F,+EAA+E;AAC/E,oFAAoF;AACpF,OAAO,EAAE,IAAI,EAAoC,MAAM,aAAa,CAAC;AAErE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAoC,MAAM,iBAAiB,CAAC;AAEpF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAkD,EAClD,IAA8B,EAC9B,KAAiB,EACjB,KAAc,EACd,SAAkB,EAClB,IAAgB,EAChB,IAAiB,EACjB,GAAW;IAEX,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,KAAc,CAAe,CAAC;QACxD,IAAI,SAAS;YAAE,IAAI,CAAC,eAAe,EAAE,CAAC;QACtC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;QACrD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,WAAW,CACzB,QAAkC,EAClC,KAAiB,EACjB,KAAiB;IAEjB,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACnE,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAY,CAAC,CAAC;IACxD,CAAC;AACH,CAAC","sourcesContent":["// Optional error handling a component asks for by name (ADR 0024, gyral-1zd.17): the `error`\n// fallback view and the `Errored` framework message. Reached through `#spec-features`, so a\n// compiled build bundles each only when some module names `error` or `Errored`\n// (compiler/features.ts); the reporting channel itself (errors.ts) is in every app.\nimport { fail, type ErrorPhase, type GyralError } from './errors.js';\nimport type { Tagged } from './types.js';\nimport { message, render, type ChildValue, type SeenMarkup } from './view/index.js';\n\n/**\n * Renders a component's `error` view into `root`; true when it rendered (a hydrating root is\n * cleared first). A view that throws too is reported and changes nothing.\n */\nexport function renderErrorView(\n  view: (error: GyralError, state: never) => unknown,\n  root: ShadowRoot | HTMLElement,\n  error: GyralError,\n  state: unknown,\n  hydrating: boolean,\n  seen: SeenMarkup,\n  host: HTMLElement,\n  tag: string,\n): boolean {\n  try {\n    const value = view(error, state as never) as ChildValue;\n    if (hydrating) root.replaceChildren();\n    render(value, root, seen);\n    return true;\n  } catch (cause) {\n    fail(cause, 'view', message(31, tag), { host, tag });\n    return false;\n  }\n}\n\n/** Sends `Errored` to a component whose `update` handles it (a failed update, parse or command). */\nexport function sendErrored(\n  dispatch: (msg: Tagged) => unknown,\n  phase: ErrorPhase,\n  error: GyralError,\n): void {\n  if (phase === 'update' || phase === 'parse' || phase === 'command') {\n    dispatch({ _tag: 'Errored', phase, error } as Tagged);\n  }\n}\n"]}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+/** Where a failure happened. */
+export type ErrorPhase = 'init' | 'update' | 'view' | 'parse' | 'command' | 'hook' | 'store' | 'subscribe';
+/** A failure Gyral caught, with its context; `cause` is what was thrown. */
+export declare class GyralError extends Error {
+    readonly name = "GyralError";
+    /** The failing host's tag; `undefined` for a store or work not tied to one component. */
+    readonly component: string | undefined;
+    readonly phase: ErrorPhase;
+    /** The message tag being reduced, the intent name, or the driver's name. */
+    readonly msg: string | undefined;
+    constructor(phase: ErrorPhase, text: string, cause: unknown, component?: string, msg?: string);
+}
+/** Where a failure happened, for `fail()`. */
+export interface FailureSite {
+    /** The failing host: it gets the boundary event. */
+    readonly host?: Element | undefined;
+    readonly tag?: string | undefined;
+    readonly msg?: string | undefined;
+}
+/** Reports `cause` (ADR 0024 "Recommendation"); returns the GyralError it reported. */
+export declare function fail(cause: unknown, phase: ErrorPhase, text: string, site?: FailureSite): GyralError;

package/dist/errors.js

@@ -0,0 +1,47 @@
+// Errors (ADR 0024): one reporting channel. Every failure Gyral catches becomes a `GyralError`
+// carrying the component, the phase and the message, and goes through `fail()`: the devtools
+// timeline, then a bubbling, composed, cancelable `ErrorEvent('error')` on the failing host
+// (a parent claims it with `preventDefault()`), then `reportError()` unless it was claimed, so
+// `window` `error` listeners and monitoring tools see it. The boundary event stops at the
+// document, so `window` gets each failure once, from `reportError`.
+import { DEVTOOLS_ENABLED, devError } from '#devtools';
+/** A failure Gyral caught, with its context; `cause` is what was thrown. */
+export class GyralError extends Error {
+    constructor(phase, text, cause, component, msg) {
+        super(text, { cause });
+        this.name = 'GyralError';
+        this.phase = phase;
+        this.component = component;
+        this.msg = msg;
+    }
+}
+let stopping = false;
+/** Reports `cause` (ADR 0024 "Recommendation"); returns the GyralError it reported. */
+export function fail(cause, phase, text, site = {}) {
+    const { host, tag, msg } = site;
+    const error = cause instanceof GyralError ? cause : new GyralError(phase, text, cause, tag, msg);
+    if (DEVTOOLS_ENABLED)
+        devError(host, error);
+    let claimed = false;
+    if (host?.isConnected === true) {
+        if (!stopping) {
+            // The boundary event ends at the document: `window` hears the failure from reportError.
+            stopping = true;
+            document.addEventListener('error', (event) => {
+                if (event.error instanceof GyralError)
+                    event.stopPropagation();
+            });
+        }
+        claimed = !host.dispatchEvent(new ErrorEvent('error', {
+            error,
+            message: error.message,
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+        }));
+    }
+    if (!claimed)
+        reportError(error); // Baseline widely available since 2024-09 (ADR 0024)
+    return error;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,6FAA6F;AAC7F,4FAA4F;AAC5F,+FAA+F;AAC/F,0FAA0F;AAC1F,oEAAoE;AACpE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAMvD,4EAA4E;AAC5E,MAAM,OAAO,UAAW,SAAQ,KAAK;IAQnC,YAAY,KAAiB,EAAE,IAAY,EAAE,KAAc,EAAE,SAAkB,EAAE,GAAY;QAC3F,KAAK,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QARP,SAAI,GAAG,YAAY,CAAC;QASpC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;CACF;AAUD,IAAI,QAAQ,GAAG,KAAK,CAAC;AAErB,uFAAuF;AACvF,MAAM,UAAU,IAAI,CAClB,KAAc,EACd,KAAiB,EACjB,IAAY,EACZ,OAAoB,EAAE;IAEtB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,YAAY,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACjG,IAAI,gBAAgB;QAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC5C,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,IAAI,EAAE,WAAW,KAAK,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,wFAAwF;YACxF,QAAQ,GAAG,IAAI,CAAC;YAChB,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC3C,IAAI,KAAK,CAAC,KAAK,YAAY,UAAU;oBAAE,KAAK,CAAC,eAAe,EAAE,CAAC;YACjE,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,CAAC,aAAa,CAC3B,IAAI,UAAU,CAAC,OAAO,EAAE;YACtB,KAAK;YACL,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;YACd,UAAU,EAAE,IAAI;SACjB,CAAC,CACH,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,OAAO;QAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,qDAAqD;IACvF,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["// Errors (ADR 0024): one reporting channel. Every failure Gyral catches becomes a `GyralError`\n// carrying the component, the phase and the message, and goes through `fail()`: the devtools\n// timeline, then a bubbling, composed, cancelable `ErrorEvent('error')` on the failing host\n// (a parent claims it with `preventDefault()`), then `reportError()` unless it was claimed, so\n// `window` `error` listeners and monitoring tools see it. The boundary event stops at the\n// document, so `window` gets each failure once, from `reportError`.\nimport { DEVTOOLS_ENABLED, devError } from '#devtools';\n\n/** Where a failure happened. */\nexport type ErrorPhase =\n  'init' | 'update' | 'view' | 'parse' | 'command' | 'hook' | 'store' | 'subscribe';\n\n/** A failure Gyral caught, with its context; `cause` is what was thrown. */\nexport class GyralError extends Error {\n  override readonly name = 'GyralError';\n  /** The failing host's tag; `undefined` for a store or work not tied to one component. */\n  readonly component: string | undefined;\n  readonly phase: ErrorPhase;\n  /** The message tag being reduced, the intent name, or the driver's name. */\n  readonly msg: string | undefined;\n\n  constructor(phase: ErrorPhase, text: string, cause: unknown, component?: string, msg?: string) {\n    super(text, { cause });\n    this.phase = phase;\n    this.component = component;\n    this.msg = msg;\n  }\n}\n\n/** Where a failure happened, for `fail()`. */\nexport interface FailureSite {\n  /** The failing host: it gets the boundary event. */\n  readonly host?: Element | undefined;\n  readonly tag?: string | undefined;\n  readonly msg?: string | undefined;\n}\n\nlet stopping = false;\n\n/** Reports `cause` (ADR 0024 \"Recommendation\"); returns the GyralError it reported. */\nexport function fail(\n  cause: unknown,\n  phase: ErrorPhase,\n  text: string,\n  site: FailureSite = {},\n): GyralError {\n  const { host, tag, msg } = site;\n  const error = cause instanceof GyralError ? cause : new GyralError(phase, text, cause, tag, msg);\n  if (DEVTOOLS_ENABLED) devError(host, error);\n  let claimed = false;\n  if (host?.isConnected === true) {\n    if (!stopping) {\n      // The boundary event ends at the document: `window` hears the failure from reportError.\n      stopping = true;\n      document.addEventListener('error', (event) => {\n        if (event.error instanceof GyralError) event.stopPropagation();\n      });\n    }\n    claimed = !host.dispatchEvent(\n      new ErrorEvent('error', {\n        error,\n        message: error.message,\n        bubbles: true,\n        composed: true,\n        cancelable: true,\n      }),\n    );\n  }\n  if (!claimed) reportError(error); // Baseline widely available since 2024-09 (ADR 0024)\n  return error;\n}\n"]}