@gyral/core 0.2.0 → 0.3.1

package/dist/frame-lane.js

@@ -0,0 +1,28 @@
+/** A frame-lane flush that no animation frame has run by then runs from a timer (hidden pages). */
+const FRAME_FALLBACK_MS = 100;
+/** Hosts marked only in the frame lane: they join the scheduler's dirty set when the frame comes. */
+const framed = new Set();
+let frameRaf = 0;
+/** Set while a frame-lane flush is requested. */
+let frameTimer;
+export const frameLane = {
+    add(task, mark) {
+        framed.add(task);
+        if (frameTimer !== undefined)
+            return;
+        const run = () => {
+            cancelAnimationFrame(frameRaf);
+            clearTimeout(frameTimer);
+            frameTimer = undefined;
+            for (const host of framed)
+                mark(host);
+        };
+        frameRaf = requestAnimationFrame(run);
+        frameTimer = setTimeout(run, FRAME_FALLBACK_MS);
+    },
+    drop(task) {
+        framed.delete(task);
+    },
+    pending: () => framed.size > 0,
+};
+//# sourceMappingURL=frame-lane.js.map

package/dist/frame-lane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-lane.js","sourceRoot":"","sources":["../src/frame-lane.ts"],"names":[],"mappings":"AAQA,mGAAmG;AACnG,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,qGAAqG;AACrG,MAAM,MAAM,GAAG,IAAI,GAAG,EAAY,CAAC;AACnC,IAAI,QAAQ,GAAG,CAAC,CAAC;AACjB,iDAAiD;AACjD,IAAI,UAAqD,CAAC;AAY1D,MAAM,CAAC,MAAM,SAAS,GAAc;IAClC,GAAG,CAAC,IAAI,EAAE,IAAI;QACZ,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjB,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO;QACrC,MAAM,GAAG,GAAG,GAAS,EAAE;YACrB,oBAAoB,CAAC,QAAQ,CAAC,CAAC;YAC/B,YAAY,CAAC,UAAU,CAAC,CAAC;YACzB,UAAU,GAAG,SAAS,CAAC;YACvB,KAAK,MAAM,IAAI,IAAI,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC,CAAC;QACF,QAAQ,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;QACtC,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,CAAC,IAAI;QACP,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC;CAC/B,CAAC","sourcesContent":["// The scheduler's frame lane (view/04-scheduler.md \"Frame lane\"): hosts marked by a message\n// their spec lists in `renderOnFrame` wait for the next animation frame, then join a microtask\n// flush, so many such messages in one frame cost one render. `requestAnimationFrame` doesn't\n// run in hidden pages, so a timer runs the frame's flush if no frame came first. Reached\n// through core's `#spec-features` (spec-features.ts): compiled builds bundle it only when a\n// module names `renderOnFrame` (compiler/features.ts, gyral-c5d.12).\nimport type { HostTask } from './scheduler.js';\n\n/** A frame-lane flush that no animation frame has run by then runs from a timer (hidden pages). */\nconst FRAME_FALLBACK_MS = 100;\n\n/** Hosts marked only in the frame lane: they join the scheduler's dirty set when the frame comes. */\nconst framed = new Set<HostTask>();\nlet frameRaf = 0;\n/** Set while a frame-lane flush is requested. */\nlet frameTimer: ReturnType<typeof setTimeout> | undefined;\n\n/** The frame lane as the scheduler uses it. */\nexport interface FrameLane {\n  /** Marks `task` for the next frame; then `mark` moves each waiting host to a microtask flush. */\n  add(task: HostTask, mark: (task: HostTask) => void): void;\n  /** A microtask mark took `task` out of the frame lane. */\n  drop(task: HostTask): void;\n  /** Hosts are waiting for a frame (settled() waits for them). */\n  pending(): boolean;\n}\n\nexport const frameLane: FrameLane = {\n  add(task, mark) {\n    framed.add(task);\n    if (frameTimer !== undefined) return;\n    const run = (): void => {\n      cancelAnimationFrame(frameRaf);\n      clearTimeout(frameTimer);\n      frameTimer = undefined;\n      for (const host of framed) mark(host);\n    };\n    frameRaf = requestAnimationFrame(run);\n    frameTimer = setTimeout(run, FRAME_FALLBACK_MS);\n  },\n  drop(task) {\n    framed.delete(task);\n  },\n  pending: () => framed.size > 0,\n};\n"]}

package/dist/head.d.ts

@@ -0,0 +1,61 @@
+/** A JSON value: what a JSON-LD block holds. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * `<meta name content>`, or `<meta property content>` (Open Graph uses `property`). `media`
+ * makes one entry per media query (`theme-color` for light and dark).
+ */
+export type HeadMeta = {
+    readonly name: string;
+    readonly content: string;
+    readonly media?: string;
+} | {
+    readonly property: string;
+    readonly content: string;
+    readonly media?: string;
+};
+/**
+ * A metadata `<link>`: `alternate` (with `hreflang`), `icon` (with `sizes`, `type`), `manifest`
+ * (with `crossorigin`), `prev`/`next`, … Any other attribute is written as given.
+ */
+export interface HeadLink {
+    readonly rel: string;
+    readonly href: string;
+    readonly [attribute: string]: string;
+}
+/** A page's head: what `renderPage()` writes on the server and `setHead()` applies on the client. */
+export interface Head {
+    readonly title: string;
+    readonly description?: string;
+    /** Absolute URL, usually `new URL(match.path, origin).href` (ADR 0009 "Canonical paths"). */
+    readonly canonical?: string;
+    /** `<meta name="robots">`, e.g. `'noindex, follow'`. */
+    readonly robots?: string;
+    /** Later entries win over earlier ones with the same name or property. */
+    readonly meta?: readonly HeadMeta[];
+    /** Later entries win over earlier ones with the same attributes other than `href`. */
+    readonly links?: readonly HeadLink[];
+    /** Structured data, each written as one `<script type="application/ld+json">`. */
+    readonly jsonLd?: readonly JsonValue[];
+    /** `<html lang>`. */
+    readonly lang?: string;
+    /** `<html dir>`. */
+    readonly dir?: 'ltr' | 'rtl' | 'auto';
+}
+/** The attribute that marks an element the head model manages; its value is the entry's key. */
+export declare const HEAD_ATTRIBUTE = "data-gyral-head";
+/** One managed element: its key, tag, attributes (in order) and, for JSON-LD, its text. */
+export interface HeadEntry {
+    readonly key: string;
+    readonly tag: 'meta' | 'link' | 'script';
+    readonly attributes: readonly (readonly [name: string, value: string])[];
+    readonly text?: string;
+}
+/**
+ * A head's managed elements, in document order and without duplicates: description, robots,
+ * canonical, `meta`, `links`, then JSON-LD. Later `meta`/`links` entries with the same key win
+ * (at the later position); the typed description and robots win over `meta` entries. The
+ * title, `lang` and `dir` are not elements here.
+ */
+export declare function headEntries(head: Head): readonly HeadEntry[];

package/dist/head.js

@@ -0,0 +1,85 @@
+// The head model (ADR 0019): one description of a page's managed <head> elements, shared by the
+// server's page shell (@gyral/ssr `renderPage()`) and the router's `setHead()`. Types and a pure
+// normalizer only, no DOM, so both halves agree on keys, order and duplicates.
+import { DEV } from '#view-dev';
+import { scriptSafeJson } from './script-json.js';
+/** The attribute that marks an element the head model manages; its value is the entry's key. */
+export const HEAD_ATTRIBUTE = 'data-gyral-head';
+// Belong to renderPage() itself: changing them per navigation would unstyle the page, refetch
+// modules, or apply policy too late. Checked in development only.
+const REFUSED_REL = /(^|\s)(stylesheet|preload|modulepreload|canonical)(\s|$)/i;
+function check(head) {
+    const refuse = (what) => {
+        throw new Error(`gyral head: ${what} is not a managed head entry (ADR 0019 "Keys, dedupe and order"). ` +
+            'Write it with renderPage() options or extraHead.');
+    };
+    for (const m of head.meta ?? []) {
+        if ('http-equiv' in m || 'charset' in m)
+            refuse('<meta http-equiv> or <meta charset>');
+        if ('name' in m && /^viewport$/i.test(m.name))
+            refuse('<meta name="viewport">');
+    }
+    for (const link of head.links ?? []) {
+        if (REFUSED_REL.test(link.rel))
+            refuse(`<link rel="${link.rel}">`);
+    }
+    if (head.canonical !== undefined && !/^[a-z][a-z\d+.-]*:/i.test(head.canonical)) {
+        console.warn(`gyral head: canonical "${head.canonical}" is not an absolute URL. Build it from a ` +
+            'configured origin: new URL(match.path, origin).href (ADR 0019).');
+    }
+}
+/**
+ * A head's managed elements, in document order and without duplicates: description, robots,
+ * canonical, `meta`, `links`, then JSON-LD. Later `meta`/`links` entries with the same key win
+ * (at the later position); the typed description and robots win over `meta` entries. The
+ * title, `lang` and `dir` are not elements here.
+ */
+export function headEntries(head) {
+    if (DEV)
+        check(head);
+    const out = new Map();
+    const add = (key, tag, attributes, text) => {
+        out.delete(key);
+        out.set(key, text === undefined ? { key, tag, attributes } : { key, tag, attributes, text });
+    };
+    const meta = (attr, name, content, media) => {
+        add(media === undefined ? `${attr}:${name}` : `${attr}:${name}|${media}`, 'meta', [
+            [attr, name],
+            ['content', content],
+            ...(media === undefined ? [] : [['media', media]]),
+        ]);
+    };
+    if (head.description !== undefined)
+        meta('name', 'description', head.description);
+    if (head.robots !== undefined)
+        meta('name', 'robots', head.robots);
+    if (head.canonical !== undefined) {
+        add('canonical', 'link', [
+            ['rel', 'canonical'],
+            ['href', head.canonical],
+        ]);
+    }
+    const typed = new Set(out.keys());
+    for (const m of head.meta ?? []) {
+        const [attr, name] = 'name' in m ? ['name', m.name] : ['property', m.property];
+        if (!typed.has(`${attr}:${name}`))
+            meta(attr, name, m.content, m.media);
+    }
+    for (const link of head.links ?? []) {
+        const attributes = Object.entries(link);
+        const key = attributes
+            .filter(([name]) => name !== 'href')
+            .map(([name, value]) => `${name}=${value}`)
+            .sort()
+            .join(';');
+        add(`link:${key}`, 'link', [
+            ['rel', link.rel],
+            ...attributes.filter(([name]) => name !== 'rel'),
+        ]);
+    }
+    head.jsonLd?.forEach((value, n) => {
+        add(`ld:${String(n)}`, 'script', [['type', 'application/ld+json']], scriptSafeJson(value));
+    });
+    return [...out.values()];
+}
+//# sourceMappingURL=head.js.map

package/dist/head.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"head.js","sourceRoot":"","sources":["../src/head.ts"],"names":[],"mappings":"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","sourcesContent":["// The head model (ADR 0019): one description of a page's managed <head> elements, shared by the\n// server's page shell (@gyral/ssr `renderPage()`) and the router's `setHead()`. Types and a pure\n// normalizer only, no DOM, so both halves agree on keys, order and duplicates.\nimport { DEV } from '#view-dev';\nimport { scriptSafeJson } from './script-json.js';\n\n/** A JSON value: what a JSON-LD block holds. */\nexport type JsonValue =\n  string | number | boolean | null | readonly JsonValue[] | { readonly [key: string]: JsonValue };\n\n/**\n * `<meta name content>`, or `<meta property content>` (Open Graph uses `property`). `media`\n * makes one entry per media query (`theme-color` for light and dark).\n */\nexport type HeadMeta =\n  | { readonly name: string; readonly content: string; readonly media?: string }\n  | { readonly property: string; readonly content: string; readonly media?: string };\n\n/**\n * A metadata `<link>`: `alternate` (with `hreflang`), `icon` (with `sizes`, `type`), `manifest`\n * (with `crossorigin`), `prev`/`next`, … Any other attribute is written as given.\n */\nexport interface HeadLink {\n  readonly rel: string;\n  readonly href: string;\n  readonly [attribute: string]: string;\n}\n\n/** A page's head: what `renderPage()` writes on the server and `setHead()` applies on the client. */\nexport interface Head {\n  readonly title: string;\n  readonly description?: string;\n  /** Absolute URL, usually `new URL(match.path, origin).href` (ADR 0009 \"Canonical paths\"). */\n  readonly canonical?: string;\n  /** `<meta name=\"robots\">`, e.g. `'noindex, follow'`. */\n  readonly robots?: string;\n  /** Later entries win over earlier ones with the same name or property. */\n  readonly meta?: readonly HeadMeta[];\n  /** Later entries win over earlier ones with the same attributes other than `href`. */\n  readonly links?: readonly HeadLink[];\n  /** Structured data, each written as one `<script type=\"application/ld+json\">`. */\n  readonly jsonLd?: readonly JsonValue[];\n  /** `<html lang>`. */\n  readonly lang?: string;\n  /** `<html dir>`. */\n  readonly dir?: 'ltr' | 'rtl' | 'auto';\n}\n\n/** The attribute that marks an element the head model manages; its value is the entry's key. */\nexport const HEAD_ATTRIBUTE = 'data-gyral-head';\n\n/** One managed element: its key, tag, attributes (in order) and, for JSON-LD, its text. */\nexport interface HeadEntry {\n  readonly key: string;\n  readonly tag: 'meta' | 'link' | 'script';\n  readonly attributes: readonly (readonly [name: string, value: string])[];\n  readonly text?: string;\n}\n\n// Belong to renderPage() itself: changing them per navigation would unstyle the page, refetch\n// modules, or apply policy too late. Checked in development only.\nconst REFUSED_REL = /(^|\\s)(stylesheet|preload|modulepreload|canonical)(\\s|$)/i;\n\nfunction check(head: Head): void {\n  const refuse = (what: string): never => {\n    throw new Error(\n      `gyral head: ${what} is not a managed head entry (ADR 0019 \"Keys, dedupe and order\"). ` +\n        'Write it with renderPage() options or extraHead.',\n    );\n  };\n  for (const m of head.meta ?? []) {\n    if ('http-equiv' in m || 'charset' in m) refuse('<meta http-equiv> or <meta charset>');\n    if ('name' in m && /^viewport$/i.test(m.name)) refuse('<meta name=\"viewport\">');\n  }\n  for (const link of head.links ?? []) {\n    if (REFUSED_REL.test(link.rel)) refuse(`<link rel=\"${link.rel}\">`);\n  }\n  if (head.canonical !== undefined && !/^[a-z][a-z\\d+.-]*:/i.test(head.canonical)) {\n    console.warn(\n      `gyral head: canonical \"${head.canonical}\" is not an absolute URL. Build it from a ` +\n        'configured origin: new URL(match.path, origin).href (ADR 0019).',\n    );\n  }\n}\n\n/**\n * A head's managed elements, in document order and without duplicates: description, robots,\n * canonical, `meta`, `links`, then JSON-LD. Later `meta`/`links` entries with the same key win\n * (at the later position); the typed description and robots win over `meta` entries. The\n * title, `lang` and `dir` are not elements here.\n */\nexport function headEntries(head: Head): readonly HeadEntry[] {\n  if (DEV) check(head);\n  const out = new Map<string, HeadEntry>();\n  const add = (\n    key: string,\n    tag: HeadEntry['tag'],\n    attributes: HeadEntry['attributes'],\n    text?: string,\n  ): void => {\n    out.delete(key);\n    out.set(key, text === undefined ? { key, tag, attributes } : { key, tag, attributes, text });\n  };\n  const meta = (attr: string, name: string, content: string, media?: string): void => {\n    add(media === undefined ? `${attr}:${name}` : `${attr}:${name}|${media}`, 'meta', [\n      [attr, name],\n      ['content', content],\n      ...(media === undefined ? [] : [['media', media] as const]),\n    ]);\n  };\n  if (head.description !== undefined) meta('name', 'description', head.description);\n  if (head.robots !== undefined) meta('name', 'robots', head.robots);\n  if (head.canonical !== undefined) {\n    add('canonical', 'link', [\n      ['rel', 'canonical'],\n      ['href', head.canonical],\n    ]);\n  }\n  const typed = new Set(out.keys());\n  for (const m of head.meta ?? []) {\n    const [attr, name] = 'name' in m ? ['name', m.name] : ['property', m.property];\n    if (!typed.has(`${attr}:${name}`)) meta(attr, name, m.content, m.media);\n  }\n  for (const link of head.links ?? []) {\n    const attributes = Object.entries(link);\n    const key = attributes\n      .filter(([name]) => name !== 'href')\n      .map(([name, value]) => `${name}=${value}`)\n      .sort()\n      .join(';');\n    add(`link:${key}`, 'link', [\n      ['rel', link.rel],\n      ...attributes.filter(([name]) => name !== 'rel'),\n    ]);\n  }\n  head.jsonLd?.forEach((value, n) => {\n    add(`ld:${String(n)}`, 'script', [['type', 'application/ld+json']], scriptSafeJson(value));\n  });\n  return [...out.values()];\n}\n"]}

package/dist/hooks/invalid.d.ts

@@ -0,0 +1,14 @@
+type Errors = readonly string[] | string | undefined;
+/**
+ * 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 declare const invalid: (errors?: Errors) => import("../index.js").HookResult<[errors?: Errors]>;
+export {};

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/host-model.d.ts

@@ -0,0 +1,77 @@
+import { type Command, type Next } from './command.js';
+import { type FeatureHost, type LocalHost, type StoreLink } from './features.js';
+import { type ErrorPhase, type GyralError } from './errors.js';
+import type { Seed } from './hydration.js';
+import type { ComponentSpec, IntentRejected, ParserCtx, 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;
+    /** Set when `init` threw; the host has no state then. */
+    get failure(): GyralError | undefined;
+    /** The current state, running `init` (and `initialMessages`) on first read. */
+    state(initialMessages?: readonly Tagged[]): S;
+    /**
+     * Reports a failure of this host (ADR 0024) and, for a failed update, parse or command, sends
+     * `Errored` to its optional reducer. A failure while handling `Errored` is only reported.
+     */
+    fail(cause: unknown, phase: ErrorPhase, text: string, msg?: string): GyralError;
+    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). A reducer
+     * that throws leaves them unseen, so the next render sends PropsChanged again (ADR 0024).
+     */
+    syncProps(names: readonly string[]): void;
+    /**
+     * Runs `msg`'s reducer. A reducer that throws changes nothing (no state, no commands): the
+     * failure is reported (ADR 0024) and dispatch returns false.
+     */
+    dispatch(msg: Tagged, schedule?: boolean): boolean;
+    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(): ParserCtx<P, S>;
+    /**
+     * Resolves stores and runs kept commands; after a real detach, starts the subscriptions again
+     * (05 "Lifecycle"). Returns true if store instances were bound.
+     */
+    connect(): boolean;
+    /**
+     * Starts `spec.subscriptions` (ADR 0025): after the first render, as init's commands of a
+     * server-rendered host are, so nothing they emit can change what hydration adopts.
+     */
+    subscribe(): void;
+    /** Aborts the running command of `lane` (a subscription that left, ADR 0025). */
+    cancel(lane: string): void;
+    /**
+     * Stops the commands one microtask later, unless the host is connected again first: a move
+     * (`appendChild`, `insertBefore`) disconnects and connects in one task and keeps them running.
+     */
+    disconnect(): void;
+}
+export {};