@gyral/core 0.2.0 → 0.3.0

package/dist/hooks/invalid.js

@@ -0,0 +1,72 @@
+// `invalid(errors)` as an element hook (view/02-bindings.md "Element hooks", ADR 0008): model
+// errors mirrored to native validity, so `:user-invalid` and native bubbles agree with the
+// model. The server half writes `aria-invalid` into the start tag, so it is no longer written
+// twice.
+import { defineHook } from '../view/index.js';
+const isValidatable = (el) => 'setCustomValidity' in el;
+const valueOf = (el) => ('value' in el ? el.value : undefined);
+const formOf = (el) => {
+    const form = 'form' in el ? el.form : undefined;
+    return form instanceof HTMLFormElement ? form : undefined;
+};
+const messageOf = (errors) => typeof errors === 'string' ? errors : (errors ?? []).join(' ');
+/** The listeners that clear the current error, per element (hooks keep no instance state). */
+const listening = new WeakMap();
+// Forms with a resubmit already queued: several stale fields in one validation pass resubmit once.
+const resubmitting = new WeakSet();
+function apply(el, errors) {
+    listening.get(el)?.abort();
+    listening.delete(el);
+    const message = messageOf(errors);
+    if (isValidatable(el))
+        el.setCustomValidity(message);
+    if (message === '') {
+        el.removeAttribute('aria-invalid');
+        return;
+    }
+    el.setAttribute('aria-invalid', 'true');
+    const controller = new AbortController();
+    listening.set(el, controller);
+    const { signal } = controller;
+    const rejectedValue = valueOf(el);
+    const clear = () => {
+        controller.abort();
+        if (isValidatable(el))
+            el.setCustomValidity('');
+        el.removeAttribute('aria-invalid');
+    };
+    el.addEventListener('input', clear, { signal });
+    el.addEventListener('change', clear, { signal });
+    el.addEventListener('invalid', (event) => {
+        if (Object.is(valueOf(el), rejectedValue))
+            return; // still the rejected value
+        event.preventDefault(); // no bubble for an error that no longer applies
+        clear();
+        const form = formOf(el);
+        if (form === undefined || resubmitting.has(form))
+            return;
+        resubmitting.add(form);
+        queueMicrotask(() => {
+            resubmitting.delete(form);
+            form.requestSubmit();
+        });
+    }, { signal });
+}
+/**
+ * Mirrors model errors to native validity: `setCustomValidity` and `aria-invalid`.
+ *
+ *   <input name="email" ${invalid(s.errors.email)} />
+ *
+ * The custom error clears when the control fires `input` or `change` (the user edited it), when
+ * the bound errors become `undefined` or empty (the model cleared them), or when a submit finds
+ * the error stale (the value changed without an event, e.g. set from code): then the error is
+ * dropped and the form is submitted again once. An error is applied again only when a new value
+ * arrives (keep `fieldErrors()` results in state): `client` runs only when the errors change.
+ */
+export const invalid = defineHook({
+    server: ([errors]) => (messageOf(errors) === '' ? {} : { 'aria-invalid': 'true' }),
+    client: (el, [errors]) => {
+        apply(el, errors);
+    },
+});
+//# sourceMappingURL=invalid.js.map

package/dist/hooks/invalid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid.js","sourceRoot":"","sources":["../../src/hooks/invalid.ts"],"names":[],"mappings":"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","sourcesContent":["// `invalid(errors)` as an element hook (view/02-bindings.md \"Element hooks\", ADR 0008): model\n// errors mirrored to native validity, so `:user-invalid` and native bubbles agree with the\n// model. The server half writes `aria-invalid` into the start tag, so it is no longer written\n// twice.\nimport { defineHook } from '../view/index.js';\n\ntype Errors = readonly string[] | string | undefined;\n\ninterface Validatable extends Element {\n  setCustomValidity(message: string): void;\n}\n\nconst isValidatable = (el: Element): el is Validatable => 'setCustomValidity' in el;\n\nconst valueOf = (el: Element): unknown => ('value' in el ? el.value : undefined);\n\nconst formOf = (el: Element): HTMLFormElement | undefined => {\n  const form = 'form' in el ? el.form : undefined;\n  return form instanceof HTMLFormElement ? form : undefined;\n};\n\nconst messageOf = (errors: Errors): string =>\n  typeof errors === 'string' ? errors : (errors ?? []).join(' ');\n\n/** The listeners that clear the current error, per element (hooks keep no instance state). */\nconst listening = new WeakMap<Element, AbortController>();\n\n// Forms with a resubmit already queued: several stale fields in one validation pass resubmit once.\nconst resubmitting = new WeakSet<HTMLFormElement>();\n\nfunction apply(el: Element, errors: Errors): void {\n  listening.get(el)?.abort();\n  listening.delete(el);\n  const message = messageOf(errors);\n  if (isValidatable(el)) el.setCustomValidity(message);\n  if (message === '') {\n    el.removeAttribute('aria-invalid');\n    return;\n  }\n  el.setAttribute('aria-invalid', 'true');\n\n  const controller = new AbortController();\n  listening.set(el, controller);\n  const { signal } = controller;\n  const rejectedValue = valueOf(el);\n  const clear = (): void => {\n    controller.abort();\n    if (isValidatable(el)) el.setCustomValidity('');\n    el.removeAttribute('aria-invalid');\n  };\n  el.addEventListener('input', clear, { signal });\n  el.addEventListener('change', clear, { signal });\n  el.addEventListener(\n    'invalid',\n    (event) => {\n      if (Object.is(valueOf(el), rejectedValue)) return; // still the rejected value\n      event.preventDefault(); // no bubble for an error that no longer applies\n      clear();\n      const form = formOf(el);\n      if (form === undefined || resubmitting.has(form)) return;\n      resubmitting.add(form);\n      queueMicrotask(() => {\n        resubmitting.delete(form);\n        form.requestSubmit();\n      });\n    },\n    { signal },\n  );\n}\n\n/**\n * Mirrors model errors to native validity: `setCustomValidity` and `aria-invalid`.\n *\n *   <input name=\"email\" ${invalid(s.errors.email)} />\n *\n * The custom error clears when the control fires `input` or `change` (the user edited it), when\n * the bound errors become `undefined` or empty (the model cleared them), or when a submit finds\n * the error stale (the value changed without an event, e.g. set from code): then the error is\n * dropped and the form is submitted again once. An error is applied again only when a new value\n * arrives (keep `fieldErrors()` results in state): `client` runs only when the errors change.\n */\nexport const invalid = defineHook<[errors?: Errors]>({\n  server: ([errors]) => (messageOf(errors) === '' ? {} : { 'aria-invalid': 'true' }),\n  client: (el, [errors]) => {\n    apply(el, errors);\n  },\n});\n"]}

package/dist/hooks/labelled-by.d.ts

@@ -0,0 +1,13 @@
+/** The element with `id`, searched from `from`'s own root outward to the document. */
+export declare function findInScope(from: Element, id: string): Element | null;
+/**
+ * Names the element after the element with `id`, even outside this component's shadow root:
+ *
+ *   <form ${labelledBy('page-title', 'Sign in')}>
+ *
+ * Uses `ariaLabelledByElements` (ARIA element reflection) where the browser has it, so the name
+ * stays in sync with the heading. Elsewhere it sets `aria-label` from `fallback`, or from the
+ * target's text. It has no server half (as before): render a plain `aria-label` too (from a
+ * `label` prop) for the page before scripts run; the reflected `aria-labelledby` wins over it.
+ */
+export declare const labelledBy: (id: string, fallback?: string | undefined) => import("../index.js").HookResult<[id: string, fallback?: string]>;

package/dist/hooks/labelled-by.js

@@ -0,0 +1,51 @@
+// `labelledBy(id, fallback?)` as an element hook (view/02-bindings.md "Element hooks",
+// gyral-czi.26): accessible names across shadow boundaries. `aria-labelledby="page-title"`
+// inside a shadow root can't see an id in the page, so the id is resolved outward through the
+// shadow-including ancestors.
+import { defineHook } from '../view/index.js';
+/** ARIA element reflection: newly available Baseline, so feature-detected (ADR 0003). */
+const reflects = (el) => 'ariaLabelledByElements' in el;
+/** The element with `id`, searched from `from`'s own root outward to the document. */
+export function findInScope(from, id) {
+    for (let root = from.getRootNode();;) {
+        const found = 'getElementById' in root ? root.getElementById(id) : null;
+        if (found !== null && found !== from)
+            return found;
+        if (!(root instanceof ShadowRoot))
+            return null;
+        root = root.host.getRootNode();
+    }
+}
+/** Names `el`; false when the target wasn't found (it may render later). */
+function name(el, id, fallback) {
+    const target = findInScope(el, id);
+    if (target !== null && reflects(el)) {
+        el.ariaLabelledByElements = [target];
+        return true;
+    }
+    const text = fallback ?? target?.textContent.trim() ?? '';
+    if (text !== '')
+        el.setAttribute('aria-label', text);
+    return target !== null;
+}
+/**
+ * Names the element after the element with `id`, even outside this component's shadow root:
+ *
+ *   <form ${labelledBy('page-title', 'Sign in')}>
+ *
+ * Uses `ariaLabelledByElements` (ARIA element reflection) where the browser has it, so the name
+ * stays in sync with the heading. Elsewhere it sets `aria-label` from `fallback`, or from the
+ * target's text. It has no server half (as before): render a plain `aria-label` too (from a
+ * `label` prop) for the page before scripts run; the reflected `aria-labelledby` wins over it.
+ */
+export const labelledBy = defineHook({
+    client: (el, [id, fallback]) => {
+        // The labelling element may render after this one (a later sibling): try again once.
+        if (!name(el, id, fallback)) {
+            queueMicrotask(() => {
+                name(el, id, fallback);
+            });
+        }
+    },
+});
+//# sourceMappingURL=labelled-by.js.map

package/dist/hooks/labelled-by.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"labelled-by.js","sourceRoot":"","sources":["../../src/hooks/labelled-by.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,2FAA2F;AAC3F,8FAA8F;AAC9F,8BAA8B;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAM9C,yFAAyF;AACzF,MAAM,QAAQ,GAAG,CAAC,EAAW,EAAoB,EAAE,CAAC,wBAAwB,IAAI,EAAE,CAAC;AAInF,sFAAsF;AACtF,MAAM,UAAU,WAAW,CAAC,IAAa,EAAE,EAAU;IACnD,KAAK,IAAI,IAAI,GAAS,IAAI,CAAC,WAAW,EAAE,IAAK,CAAC;QAC5C,MAAM,KAAK,GAAG,gBAAgB,IAAI,IAAI,CAAC,CAAC,CAAE,IAAyB,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9F,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACnD,IAAI,CAAC,CAAC,IAAI,YAAY,UAAU,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/C,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,SAAS,IAAI,CAAC,EAAW,EAAE,EAAU,EAAE,QAA4B;IACjE,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,MAAM,KAAK,IAAI,IAAI,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACpC,EAAE,CAAC,sBAAsB,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,IAAI,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IAC1D,IAAI,IAAI,KAAK,EAAE;QAAE,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACrD,OAAO,MAAM,KAAK,IAAI,CAAC;AACzB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAkC;IACpE,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE;QAC7B,qFAAqF;QACrF,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC5B,cAAc,CAAC,GAAG,EAAE;gBAClB,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;YACzB,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF,CAAC,CAAC","sourcesContent":["// `labelledBy(id, fallback?)` as an element hook (view/02-bindings.md \"Element hooks\",\n// gyral-czi.26): accessible names across shadow boundaries. `aria-labelledby=\"page-title\"`\n// inside a shadow root can't see an id in the page, so the id is resolved outward through the\n// shadow-including ancestors.\nimport { defineHook } from '../view/index.js';\n\ninterface Reflecting extends Element {\n  ariaLabelledByElements: readonly Element[] | null;\n}\n\n/** ARIA element reflection: newly available Baseline, so feature-detected (ADR 0003). */\nconst reflects = (el: Element): el is Reflecting => 'ariaLabelledByElements' in el;\n\ntype DocumentOrShadow = Document | ShadowRoot;\n\n/** The element with `id`, searched from `from`'s own root outward to the document. */\nexport function findInScope(from: Element, id: string): Element | null {\n  for (let root: Node = from.getRootNode(); ;) {\n    const found = 'getElementById' in root ? (root as DocumentOrShadow).getElementById(id) : null;\n    if (found !== null && found !== from) return found;\n    if (!(root instanceof ShadowRoot)) return null;\n    root = root.host.getRootNode();\n  }\n}\n\n/** Names `el`; false when the target wasn't found (it may render later). */\nfunction name(el: Element, id: string, fallback: string | undefined): boolean {\n  const target = findInScope(el, id);\n  if (target !== null && reflects(el)) {\n    el.ariaLabelledByElements = [target];\n    return true;\n  }\n  const text = fallback ?? target?.textContent.trim() ?? '';\n  if (text !== '') el.setAttribute('aria-label', text);\n  return target !== null;\n}\n\n/**\n * Names the element after the element with `id`, even outside this component's shadow root:\n *\n *   <form ${labelledBy('page-title', 'Sign in')}>\n *\n * Uses `ariaLabelledByElements` (ARIA element reflection) where the browser has it, so the name\n * stays in sync with the heading. Elsewhere it sets `aria-label` from `fallback`, or from the\n * target's text. It has no server half (as before): render a plain `aria-label` too (from a\n * `label` prop) for the page before scripts run; the reflected `aria-labelledby` wins over it.\n */\nexport const labelledBy = defineHook<[id: string, fallback?: string]>({\n  client: (el, [id, fallback]) => {\n    // The labelling element may render after this one (a later sibling): try again once.\n    if (!name(el, id, fallback)) {\n      queueMicrotask(() => {\n        name(el, id, fallback);\n      });\n    }\n  },\n});\n"]}

package/dist/host-model.d.ts

@@ -0,0 +1,48 @@
+import { type Command, type Next } from './command.js';
+import { type FeatureHost, type LocalHost, type StoreLink } from './features.js';
+import type { Seed } from './hydration.js';
+import type { ComponentSpec, Ctx, IntentRejected, Tagged } from './types.js';
+type Bag = Readonly<Record<string, unknown>>;
+/** A command as the model runs it. */
+export type ModelCommand = Command<Tagged | IntentRejected>;
+type Cmd = ModelCommand;
+/** What the model needs from its element. */
+export interface ModelHost {
+    readonly el: FeatureHost;
+    readonly tag: string;
+    /** The declared props as components see them (defaults applied). */
+    readonly props: () => Bag;
+    /** The host's root once it has one (focus commands run against it). */
+    readonly root: () => ParentNode | undefined;
+    /** Something changed that the next render must show; `onFrame`: in the frame lane (04). */
+    readonly invalidate: (onFrame: boolean) => void;
+}
+export declare class HostModel<S, P> implements LocalHost {
+    #private;
+    readonly el: FeatureHost;
+    readonly tag: string;
+    readonly root: () => ParentNode | undefined;
+    constructor(host: ModelHost, spec: ComponentSpec<S, Tagged, P>);
+    /** The store binding, created on first use. Only reached once `defineStore()` has run. */
+    readonly stores: () => StoreLink;
+    get ready(): boolean;
+    /** The current state, running `init` (and `initialMessages`) on first read. */
+    state(initialMessages?: readonly Tagged[]): S;
+    hasReducer(tag: string): boolean;
+    /**
+     * Resumes from a server seed (ADR 0012): the server's state, or `init(props)`'s when the
+     * seed left it out. Returns init's commands, to start after the first render.
+     */
+    resume(seed: Seed): readonly Cmd[];
+    /** PropsChanged when props differ from the last ones seen (`Object.is` per prop). */
+    syncProps(names: readonly string[]): void;
+    dispatch(msg: Tagged, schedule?: boolean): void;
+    apply(next: Next<S, Tagged> | Next<S, Tagged | IntentRejected>): void;
+    /** Starts commands kept for later (init's, after a server-rendered host's first render). */
+    run(commands: readonly Cmd[]): void;
+    ctx(): Ctx<P>;
+    /** Resolves stores and runs kept commands. Returns true if store instances were bound. */
+    connect(): boolean;
+    disconnect(): void;
+}
+export {};

package/dist/host-model.js

@@ -0,0 +1,155 @@
+// The model side of one Gyral host (docs/design-docs/view/05-element.md, ADR 0006, ADR 0013):
+// state, reducers and commands. element.ts owns the DOM side (props, root, lifecycle,
+// rendering) and asks this object for state and context. Reducers run at once, so `state` is
+// always current; only the render waits (04). The interpreter and the store binding come from
+// features.ts, registered by `command()` and `defineStore()`; marker drivers (focus, emit, store
+// sends) carry their own `local` handler.
+import { DEVTOOLS_ENABLED, devCommands, devOwner, devUpdate } from '#devtools';
+import { splitNext } from './command.js';
+import { features, } from './features.js';
+import { runInit } from './init.js';
+import { requestTransition } from './scheduler.js';
+export class HostModel {
+    #host;
+    #spec;
+    #reducers;
+    #binding;
+    #model;
+    /** Props as of init or the last PropsChanged: the `prev` of the next PropsChanged. */
+    #seen;
+    #interpreter;
+    /** Commands kept while disconnected (init's, before the first connect); undefined once connected. */
+    #pending;
+    constructor(host, spec) {
+        /** Commands kept while disconnected (init's, before the first connect); undefined once connected. */
+        this.#pending = [];
+        /** The store binding, created on first use. Only reached once `defineStore()` has run. */
+        this.stores = () => (this.#binding ??= features.stores(this.#host.el, this.#host.tag, this.#spec.stores ?? [], (store, state, prev) => {
+            this.#storeChanged(store, state, prev);
+        }));
+        this.#host = host;
+        this.el = host.el;
+        this.tag = host.tag;
+        this.root = host.root;
+        this.#spec = spec;
+        // Sound: dispatch() only calls the reducer whose key equals msg._tag.
+        this.#reducers = spec.update;
+    }
+    get ready() {
+        return this.#model !== undefined;
+    }
+    /** The current state, running `init` (and `initialMessages`) on first read. */
+    state(initialMessages = []) {
+        if (this.#model === undefined) {
+            this.#seen = this.#host.props();
+            this.apply(runInit(this.#spec, this.#seen));
+            for (const msg of initialMessages)
+                this.dispatch(msg, false);
+        }
+        return this.#model.value;
+    }
+    hasReducer(tag) {
+        return this.#reducers[tag] !== undefined;
+    }
+    /**
+     * Resumes from a server seed (ADR 0012): the server's state, or `init(props)`'s when the
+     * seed left it out. Returns init's commands, to start after the first render.
+     */
+    resume(seed) {
+        this.#seen = this.#host.props();
+        const [initial, commands] = splitNext(runInit(this.#spec, this.#seen));
+        // Sound: the seed is this component's own state, written by the server.
+        this.#model = { value: 'state' in seed ? seed.state : initial };
+        return commands;
+    }
+    /** PropsChanged when props differ from the last ones seen (`Object.is` per prop). */
+    syncProps(names) {
+        const prev = this.#seen;
+        if (prev === undefined)
+            return;
+        const props = this.#host.props();
+        if (names.every((name) => Object.is(props[name], prev[name])))
+            return;
+        this.#seen = props;
+        this.dispatch({ _tag: 'PropsChanged', props, prev }, false);
+    }
+    dispatch(msg, schedule = true) {
+        const reducer = this.#reducers[msg._tag];
+        if (reducer === undefined) {
+            // Framework messages have optional reducers; props and stores stay readable as context.
+            if (msg._tag !== 'PropsChanged' && msg._tag !== 'StoreChanged') {
+                console.warn(`<${this.#host.tag}> has no update for message "${msg._tag}".`);
+            }
+            return;
+        }
+        const prev = this.state();
+        this.apply(reducer(prev, msg, this.ctx()));
+        const next = this.state();
+        if (DEVTOOLS_ENABLED)
+            devUpdate(this.#host.el, this.#host.tag, msg, prev, next);
+        if (!schedule)
+            return;
+        if (this.#spec.viewTransition?.(prev, next, msg) === true)
+            requestTransition();
+        this.#host.invalidate(this.#onFrame(msg._tag));
+    }
+    apply(next) {
+        const [state, commands] = splitNext(next);
+        this.#model = { value: state };
+        for (const cmd of commands) {
+            const local = cmd.driver.local;
+            if (local !== undefined)
+                local(this, cmd.input);
+            else if (this.#pending !== undefined)
+                this.#pending.push(cmd);
+            else
+                this.#commands().run(cmd);
+        }
+    }
+    /** Starts commands kept for later (init's, after a server-rendered host's first render). */
+    run(commands) {
+        this.apply([this.state(), commands]);
+    }
+    ctx() {
+        return { props: this.#host.props(), read: (store) => this.stores().read(store) };
+    }
+    /** Resolves stores and runs kept commands. Returns true if store instances were bound. */
+    connect() {
+        // The nearest <gyral-stores> may differ after a move.
+        const rebound = (this.#spec.stores?.length ?? 0) > 0 && this.stores().connect();
+        const pending = this.#pending ?? [];
+        this.#pending = undefined;
+        for (const cmd of pending)
+            this.#commands().run(cmd);
+        return rebound;
+    }
+    disconnect() {
+        this.#binding?.disconnect();
+        this.#interpreter?.dispose();
+        this.#interpreter = undefined;
+        this.#pending ??= [];
+    }
+    /**
+     * The interpreter, started with the first command after connecting. Only reached for a
+     * command built by `command()`, which registered it (features.ts).
+     */
+    #commands() {
+        const el = this.el;
+        return (this.#interpreter ??= features.commands(el, this.#spec.drivers, (msg) => {
+            this.dispatch(msg);
+        }, DEVTOOLS_ENABLED ? devCommands(() => devOwner(el, this.tag)) : undefined));
+    }
+    /** Does `tag` render in the frame lane (`spec.renderOnFrame`)? */
+    #onFrame(tag) {
+        return this.#spec.renderOnFrame?.includes(tag) === true;
+    }
+    #storeChanged(store, state, prev) {
+        if (this.#reducers['StoreChanged'] !== undefined) {
+            this.dispatch({ _tag: 'StoreChanged', store: store.name, state, prev });
+        }
+        else {
+            this.#host.invalidate(this.#onFrame('StoreChanged'));
+        }
+    }
+}
+//# sourceMappingURL=host-model.js.map

package/dist/host-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-model.js","sourceRoot":"","sources":["../src/host-model.ts"],"names":[],"mappings":"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","sourcesContent":["// The model side of one Gyral host (docs/design-docs/view/05-element.md, ADR 0006, ADR 0013):\n// state, reducers and commands. element.ts owns the DOM side (props, root, lifecycle,\n// rendering) and asks this object for state and context. Reducers run at once, so `state` is\n// always current; only the render waits (04). The interpreter and the store binding come from\n// features.ts, registered by `command()` and `defineStore()`; marker drivers (focus, emit, store\n// sends) carry their own `local` handler.\nimport { DEVTOOLS_ENABLED, devCommands, devOwner, devUpdate } from '#devtools';\nimport { splitNext, type Command, type Next } from './command.js';\nimport {\n  features,\n  type FeatureHost,\n  type LocalDriver,\n  type LocalHost,\n  type StoreLink,\n} from './features.js';\nimport type { Seed } from './hydration.js';\nimport { runInit } from './init.js';\nimport type { Interpreter } from './internal/interpreter.js';\nimport { requestTransition } from './scheduler.js';\nimport type { AnyStore } from './store.js';\nimport type { ComponentSpec, Ctx, IntentRejected, Tagged } from './types.js';\n\ntype Bag = Readonly<Record<string, unknown>>;\ntype Reducer<S> = (state: S, msg: Tagged, ctx: Ctx<object>) => Next<S, Tagged>;\n/** A command as the model runs it. */\nexport type ModelCommand = Command<Tagged | IntentRejected>;\ntype Cmd = ModelCommand;\n\n/** What the model needs from its element. */\nexport interface ModelHost {\n  readonly el: FeatureHost;\n  readonly tag: string;\n  /** The declared props as components see them (defaults applied). */\n  readonly props: () => Bag;\n  /** The host's root once it has one (focus commands run against it). */\n  readonly root: () => ParentNode | undefined;\n  /** Something changed that the next render must show; `onFrame`: in the frame lane (04). */\n  readonly invalidate: (onFrame: boolean) => void;\n}\n\nexport class HostModel<S, P> implements LocalHost {\n  readonly el: FeatureHost;\n  readonly tag: string;\n  readonly root: () => ParentNode | undefined;\n  readonly #host: ModelHost;\n  readonly #spec: ComponentSpec<S, Tagged, P>;\n  readonly #reducers: Readonly<Record<string, Reducer<S> | undefined>>;\n  #binding: StoreLink | undefined;\n  #model: { value: S } | undefined;\n  /** Props as of init or the last PropsChanged: the `prev` of the next PropsChanged. */\n  #seen: Bag | undefined;\n  #interpreter: Interpreter<Tagged | IntentRejected> | undefined;\n  /** Commands kept while disconnected (init's, before the first connect); undefined once connected. */\n  #pending: Cmd[] | undefined = [];\n\n  constructor(host: ModelHost, spec: ComponentSpec<S, Tagged, P>) {\n    this.#host = host;\n    this.el = host.el;\n    this.tag = host.tag;\n    this.root = host.root;\n    this.#spec = spec;\n    // Sound: dispatch() only calls the reducer whose key equals msg._tag.\n    this.#reducers = spec.update as unknown as Readonly<Record<string, Reducer<S> | undefined>>;\n  }\n\n  /** The store binding, created on first use. Only reached once `defineStore()` has run. */\n  readonly stores = (): StoreLink =>\n    (this.#binding ??= (features.stores as NonNullable<typeof features.stores>)(\n      this.#host.el,\n      this.#host.tag,\n      this.#spec.stores ?? [],\n      (store, state, prev) => {\n        this.#storeChanged(store, state, prev);\n      },\n    ));\n\n  get ready(): boolean {\n    return this.#model !== undefined;\n  }\n\n  /** The current state, running `init` (and `initialMessages`) on first read. */\n  state(initialMessages: readonly Tagged[] = []): S {\n    if (this.#model === undefined) {\n      this.#seen = this.#host.props();\n      this.apply(runInit(this.#spec, this.#seen as P));\n      for (const msg of initialMessages) this.dispatch(msg, false);\n    }\n    return (this.#model as { value: S }).value;\n  }\n\n  hasReducer(tag: string): boolean {\n    return this.#reducers[tag] !== undefined;\n  }\n\n  /**\n   * Resumes from a server seed (ADR 0012): the server's state, or `init(props)`'s when the\n   * seed left it out. Returns init's commands, to start after the first render.\n   */\n  resume(seed: Seed): readonly Cmd[] {\n    this.#seen = this.#host.props();\n    const [initial, commands] = splitNext(runInit(this.#spec, this.#seen as P));\n    // Sound: the seed is this component's own state, written by the server.\n    this.#model = { value: 'state' in seed ? (seed.state as S) : initial };\n    return commands;\n  }\n\n  /** PropsChanged when props differ from the last ones seen (`Object.is` per prop). */\n  syncProps(names: readonly string[]): void {\n    const prev = this.#seen;\n    if (prev === undefined) return;\n    const props = this.#host.props();\n    if (names.every((name) => Object.is(props[name], prev[name]))) return;\n    this.#seen = props;\n    this.dispatch({ _tag: 'PropsChanged', props, prev } as Tagged, false);\n  }\n\n  dispatch(msg: Tagged, schedule = true): void {\n    const reducer = this.#reducers[msg._tag];\n    if (reducer === undefined) {\n      // Framework messages have optional reducers; props and stores stay readable as context.\n      if (msg._tag !== 'PropsChanged' && msg._tag !== 'StoreChanged') {\n        console.warn(`<${this.#host.tag}> has no update for message \"${msg._tag}\".`);\n      }\n      return;\n    }\n    const prev = this.state();\n    this.apply(reducer(prev, msg, this.ctx() as Ctx<object>));\n    const next = this.state();\n    if (DEVTOOLS_ENABLED) devUpdate(this.#host.el, this.#host.tag, msg, prev, next);\n    if (!schedule) return;\n    if (this.#spec.viewTransition?.(prev, next, msg) === true) requestTransition();\n    this.#host.invalidate(this.#onFrame(msg._tag));\n  }\n\n  apply(next: Next<S, Tagged> | Next<S, Tagged | IntentRejected>): void {\n    const [state, commands] = splitNext(next as Next<S, Tagged>);\n    this.#model = { value: state };\n    for (const cmd of commands as readonly Cmd[]) {\n      const local = (cmd.driver as Partial<LocalDriver>).local;\n      if (local !== undefined) local(this, cmd.input);\n      else if (this.#pending !== undefined) this.#pending.push(cmd);\n      else this.#commands().run(cmd);\n    }\n  }\n\n  /** Starts commands kept for later (init's, after a server-rendered host's first render). */\n  run(commands: readonly Cmd[]): void {\n    this.apply([this.state(), commands]);\n  }\n\n  ctx(): Ctx<P> {\n    return { props: this.#host.props() as P, read: (store) => this.stores().read(store) };\n  }\n\n  /** Resolves stores and runs kept commands. Returns true if store instances were bound. */\n  connect(): boolean {\n    // The nearest <gyral-stores> may differ after a move.\n    const rebound = (this.#spec.stores?.length ?? 0) > 0 && this.stores().connect();\n    const pending = this.#pending ?? [];\n    this.#pending = undefined;\n    for (const cmd of pending) this.#commands().run(cmd);\n    return rebound;\n  }\n\n  disconnect(): void {\n    this.#binding?.disconnect();\n    this.#interpreter?.dispose();\n    this.#interpreter = undefined;\n    this.#pending ??= [];\n  }\n\n  /**\n   * The interpreter, started with the first command after connecting. Only reached for a\n   * command built by `command()`, which registered it (features.ts).\n   */\n  #commands(): Interpreter<Tagged | IntentRejected> {\n    const el = this.el;\n    return (this.#interpreter ??= (features.commands as NonNullable<typeof features.commands>)(\n      el,\n      this.#spec.drivers,\n      (msg) => {\n        this.dispatch(msg);\n      },\n      DEVTOOLS_ENABLED ? devCommands(() => devOwner(el, this.tag)) : undefined,\n    ));\n  }\n\n  /** Does `tag` render in the frame lane (`spec.renderOnFrame`)? */\n  #onFrame(tag: string): boolean {\n    return this.#spec.renderOnFrame?.includes(tag) === true;\n  }\n\n  #storeChanged(store: AnyStore, state: unknown, prev: unknown): void {\n    if (this.#reducers['StoreChanged'] !== undefined) {\n      this.dispatch({ _tag: 'StoreChanged', store: store.name, state, prev } as Tagged);\n    } else {\n      this.#host.invalidate(this.#onFrame('StoreChanged'));\n    }\n  }\n}\n"]}

package/dist/hydration-client.d.ts

@@ -0,0 +1,9 @@
+import { type ChildValue, type SeenMarkup } from './view/index.js';
+export { scheduleIsland } from './islands.js';
+/**
+ * Hydrates a server-rendered host's root with its first view (view/07-hydration.md "Steps").
+ * A shadow root swaps styles in the same step (08 "Hydration"): the shared sheets are adopted
+ * and the server's `<style>` removed. On a mismatch development throws; production recovers
+ * this component only: it clears the root, renders fresh and warns.
+ */
+export declare function hydrateRoot(host: HTMLElement, tag: string, view: ChildValue, root: ShadowRoot | HTMLElement, sheets: CSSStyleSheet[] | undefined, seen: SeenMarkup): void;

package/dist/hydration-client.js

@@ -0,0 +1,35 @@
+// The lazily loaded half of hydration (view/07-hydration.md "Loading"): the parallel walk and
+// islands. element.ts imports this module with import() when the first host that needs it
+// connects (one with a seed or `defer-hydration`), so client-only pages never fetch it.
+import { DEVTOOLS_ENABLED, devMismatch } from '#devtools';
+import { DEV, hydrate, HydrationMismatch, render, } from './view/index.js';
+export { scheduleIsland } from './islands.js';
+/**
+ * Hydrates a server-rendered host's root with its first view (view/07-hydration.md "Steps").
+ * A shadow root swaps styles in the same step (08 "Hydration"): the shared sheets are adopted
+ * and the server's `<style>` removed. On a mismatch development throws; production recovers
+ * this component only: it clears the root, renders fresh and warns.
+ */
+export function hydrateRoot(host, tag, view, root, sheets, seen) {
+    if (sheets !== undefined) {
+        root.adoptedStyleSheets = sheets;
+        const first = root.firstChild;
+        if (sheets.length > 0 && first?.nodeName === 'STYLE')
+            first.remove();
+    }
+    try {
+        hydrate(view, root, `<${tag}>`, seen);
+    }
+    catch (error) {
+        if (!(error instanceof HydrationMismatch))
+            throw error;
+        if (DEVTOOLS_ENABLED)
+            devMismatch(host, tag, error.message);
+        if (DEV)
+            throw error;
+        console.warn(`${error.message} <${tag}> was rendered fresh.`);
+        root.replaceChildren();
+        render(view, root, seen);
+    }
+}
+//# sourceMappingURL=hydration-client.js.map

package/dist/hydration-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration-client.js","sourceRoot":"","sources":["../src/hydration-client.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,0FAA0F;AAC1F,wFAAwF;AACxF,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EACL,GAAG,EACH,OAAO,EACP,iBAAiB,EACjB,MAAM,GAGP,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,IAAiB,EACjB,GAAW,EACX,IAAgB,EAChB,IAA8B,EAC9B,MAAmC,EACnC,IAAgB;IAEhB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACxB,IAAmB,CAAC,kBAAkB,GAAG,MAAM,CAAC;QACjD,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC;QAC9B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,EAAE,QAAQ,KAAK,OAAO;YAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IACvE,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,GAAG,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,iBAAiB,CAAC;YAAE,MAAM,KAAK,CAAC;QACvD,IAAI,gBAAgB;YAAE,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5D,IAAI,GAAG;YAAE,MAAM,KAAK,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,uBAAuB,CAAC,CAAC;QAC9D,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC","sourcesContent":["// The lazily loaded half of hydration (view/07-hydration.md \"Loading\"): the parallel walk and\n// islands. element.ts imports this module with import() when the first host that needs it\n// connects (one with a seed or `defer-hydration`), so client-only pages never fetch it.\nimport { DEVTOOLS_ENABLED, devMismatch } from '#devtools';\nimport {\n  DEV,\n  hydrate,\n  HydrationMismatch,\n  render,\n  type ChildValue,\n  type SeenMarkup,\n} from './view/index.js';\n\nexport { scheduleIsland } from './islands.js';\n\n/**\n * Hydrates a server-rendered host's root with its first view (view/07-hydration.md \"Steps\").\n * A shadow root swaps styles in the same step (08 \"Hydration\"): the shared sheets are adopted\n * and the server's `<style>` removed. On a mismatch development throws; production recovers\n * this component only: it clears the root, renders fresh and warns.\n */\nexport function hydrateRoot(\n  host: HTMLElement,\n  tag: string,\n  view: ChildValue,\n  root: ShadowRoot | HTMLElement,\n  sheets: CSSStyleSheet[] | undefined,\n  seen: SeenMarkup,\n): void {\n  if (sheets !== undefined) {\n    (root as ShadowRoot).adoptedStyleSheets = sheets;\n    const first = root.firstChild;\n    if (sheets.length > 0 && first?.nodeName === 'STYLE') first.remove();\n  }\n  try {\n    hydrate(view, root, `<${tag}>`, seen);\n  } catch (error) {\n    if (!(error instanceof HydrationMismatch)) throw error;\n    if (DEVTOOLS_ENABLED) devMismatch(host, tag, error.message);\n    if (DEV) throw error;\n    console.warn(`${error.message} <${tag}> was rendered fresh.`);\n    root.replaceChildren();\n    render(view, root, seen);\n  }\n}\n"]}

package/dist/hydration.d.ts

@@ -1,4 +1,3 @@
-import type { PropertyDeclaration } from 'lit';
 /** Host attribute holding the JSON seed. Removed once the client has read it. */
 export declare const SEED_ATTRIBUTE = "data-gyral-seed";
 export interface Seed {
@@ -12,25 +11,20 @@ export interface Seed {
 }
 /** JSON equality: seeds are JSON, so two values that serialize alike hydrate alike. */
 export declare const sameJson: (a: unknown, b: unknown) => boolean;
-type Declarations = Readonly<Record<string, PropertyDeclaration>>;
 /**
- * Server side: records the element's state and its props that are not already present as
- * attributes (property bindings such as `.items=${data}` are not in the HTML otherwise).
- * The SSR renderer escapes attribute values, so the JSON is HTML-safe.
+ * Server side: the seed for a component whose props `carried` travel in no attribute
+ * (property holes) and whose state is `state`; `initial` is `init(props)`'s state.
  */
-export declare function writeSeed(host: Element, state: unknown, props: Readonly<Record<string, unknown>>, declarations: Declarations, initialState?: {
-    readonly value: unknown;
-}): void;
-/**
- * Client side, right after hydration (gyral-4k7.12, ADR 0012): Lit SSR writes nothing for
- * an empty primitive (`''`, `null`, `undefined`), so `<!--lit-part--><!--/lit-part-->`
- * has no Text node between the markers. Hydration still records the primitive as the
- * part's committed value, and the next text commit writes `.data` into the
- * `<!--/lit-part-->` comment instead. Restore the empty Text node a client render would
- * have created. Harmless for `nothing` and empty iterables, which clear or insert before
- * the end marker. Shadow roots below `root` are handled by their own hosts.
- */
-export declare function fillEmptyTextParts(root: Node): void;
+export declare function makeSeed(tag: string, state: unknown, initial: unknown, carried: Readonly<Record<string, unknown>>): Seed;
 /** Client side: reads and removes the seed, if this element was server-rendered by Gyral. */
 export declare function takeSeed(host: Element): Seed | undefined;
-export {};
+/**
+ * The walk and islands (hydration-client.ts) once loaded; `null` if loading failed (a stale
+ * deployment: server-rendered hosts then render fresh); undefined until then.
+ */
+export declare let hydrationCode: typeof import('./hydration-client.js') | null | undefined;
+/**
+ * Loads the hydration code (once) and runs `next` when it has loaded or failed, in call
+ * order. settled() waits meanwhile (view/07-hydration.md "Loading").
+ */
+export declare function whenHydrationLoads(next: () => void): void;

package/dist/hydration.js

@@ -1,55 +1,24 @@
+// Server-render seeds (docs/design-docs/0012-ssr.md, view/06-server.md "Components"). The
+// server writes each component's state, plus the props an attribute can't carry, into one
+// attribute; the client reads it on connect, before its first render, so both sides start from
+// the same state. The walk that then hydrates the server's DOM is hydration-client.ts, which
+// core loads lazily (view/07-hydration.md "Loading").
 import { warnJsonHazard } from './json-safety.js';
+import { hold } from './scheduler.js';
+import { DEV } from './view/index.js';
 /** Host attribute holding the JSON seed. Removed once the client has read it. */
 export const SEED_ATTRIBUTE = 'data-gyral-seed';
 /** JSON equality: seeds are JSON, so two values that serialize alike hydrate alike. */
 export const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
-function attributeName(name, decl) {
-    if (decl.attribute === false)
-        return undefined;
-    return typeof decl.attribute === 'string' ? decl.attribute : name.toLowerCase();
-}
 /**
- * Server side: records the element's state and its props that are not already present as
- * attributes (property bindings such as `.items=${data}` are not in the HTML otherwise).
- * The SSR renderer escapes attribute values, so the JSON is HTML-safe.
+ * Server side: the seed for a component whose props `carried` travel in no attribute
+ * (property holes) and whose state is `state`; `initial` is `init(props)`'s state.
  */
-export function writeSeed(host, state, props, declarations, initialState) {
-    const carried = {};
-    for (const [name, value] of Object.entries(props)) {
-        const decl = declarations[name] ?? {};
-        const attr = attributeName(name, decl);
-        if (value !== undefined && (attr === undefined || !host.hasAttribute(attr))) {
-            carried[name] = value;
-        }
-    }
-    const derivable = initialState !== undefined && sameJson(state, initialState.value);
-    const seed = derivable ? { props: carried } : { state, props: carried };
-    warnJsonHazard(`<${host.localName}>`, seed, 'seed');
-    host.setAttribute(SEED_ATTRIBUTE, JSON.stringify(seed));
-}
-/**
- * Client side, right after hydration (gyral-4k7.12, ADR 0012): Lit SSR writes nothing for
- * an empty primitive (`''`, `null`, `undefined`), so `<!--lit-part--><!--/lit-part-->`
- * has no Text node between the markers. Hydration still records the primitive as the
- * part's committed value, and the next text commit writes `.data` into the
- * `<!--/lit-part-->` comment instead. Restore the empty Text node a client render would
- * have created. Harmless for `nothing` and empty iterables, which clear or insert before
- * the end marker. Shadow roots below `root` are handled by their own hosts.
- */
-export function fillEmptyTextParts(root) {
-    const doc = root.ownerDocument ?? root;
-    const walker = doc.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
-    const empty = [];
-    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
-        const next = node.nextSibling;
-        if (node.data === 'lit-part' &&
-            next instanceof Comment &&
-            next.data === '/lit-part') {
-            empty.push(node);
-        }
-    }
-    for (const start of empty)
-        start.after(doc.createTextNode(''));
+export function makeSeed(tag, state, initial, carried) {
+    const seed = sameJson(state, initial) ? { props: carried } : { state, props: carried };
+    if (DEV)
+        warnJsonHazard(`<${tag}>`, seed, 'seed'); // view/06-server.md "Seed": development
+    return seed;
 }
 /** Client side: reads and removes the seed, if this element was server-rendered by Gyral. */
 export function takeSeed(host) {
@@ -69,4 +38,35 @@ export function takeSeed(host) {
         return undefined;
     }
 }
+/**
+ * The walk and islands (hydration-client.ts) once loaded; `null` if loading failed (a stale
+ * deployment: server-rendered hosts then render fresh); undefined until then.
+ */
+export let hydrationCode;
+/** Hosts waiting for the code, in connection order; undefined when no load is pending. */
+let waiting;
+/**
+ * Loads the hydration code (once) and runs `next` when it has loaded or failed, in call
+ * order. settled() waits meanwhile (view/07-hydration.md "Loading").
+ */
+export function whenHydrationLoads(next) {
+    if (waiting !== undefined) {
+        waiting.push(next);
+        return;
+    }
+    waiting = [next];
+    const done = (code) => {
+        hydrationCode = code;
+        const hosts = waiting ?? [];
+        waiting = undefined;
+        // Each in its own microtask, in order: one host throwing doesn't stop the others. They all
+        // run before `hold` counts the load as done.
+        for (const host of hosts)
+            queueMicrotask(host);
+    };
+    hold(import('./hydration-client.js').then(done, (error) => {
+        console.error('gyral: hydration code failed to load; rendering fresh', error);
+        done(null);
+    }));
+}
 //# sourceMappingURL=hydration.js.map