@gyral/core 0.3.0 → 0.3.2

package/dist/compiler/tag-map.js

@@ -0,0 +1,126 @@
+// Component discovery and generated element typings (gyral-1zd.22, gyral-1zd.25). One scan of
+// an app's sources for two-call `define<…>()('tag', …)` calls, read from the source text (not a
+// type check), shared by automatic component loading (./components.ts) and the typings: every
+// exported component becomes an `HTMLElementTagNameMap` entry, so apps stop hand-writing
+// `declare global { interface HTMLElementTagNameMap { … } }` blocks. Node built-ins only, so
+// ../vite.ts loads it with Node's require, from TypeScript source too.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+/**
+ * A two-call `define<…>()('tag'`, optionally as `export const Name = …`: the generics (lazy,
+ * so nested `<…>` extend it), the empty call, then a string tag with a hyphen.
+ * `customElements.define(` doesn't match.
+ */
+const DEFINE_TAG = /(?:export\s+const\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]+)?=\s*)?(?<![.\w$])define\s*(?:<[\s\S]*?>)?\s*\(\s*\)\s*\(\s*(['"`])([a-z][a-z0-9._-]*-[a-z0-9._-]*)\2/g;
+const SOURCE_FILE = /\.[cm]?[jt]sx?$/;
+const SKIPPED = /\.(?:test|spec|d)\.[cm]?[jt]sx?$/;
+/** The components defined in one module's source text. */
+export function componentsIn(code, file) {
+    if (!code.includes('define'))
+        return [];
+    const out = [];
+    for (const m of code.matchAll(DEFINE_TAG)) {
+        out.push({ tag: m[3], file, name: m[1] });
+    }
+    return out;
+}
+/** Every component under `dirs` (relative to `root`), in file then source order. */
+export function discoverComponents(root, dirs) {
+    const found = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name !== 'node_modules' && !entry.name.startsWith('.'))
+                    walk(path);
+                continue;
+            }
+            if (!SOURCE_FILE.test(entry.name) || SKIPPED.test(entry.name))
+                continue;
+            found.push(...componentsIn(readFileSync(path, 'utf8'), path));
+        }
+    };
+    for (const dir of dirs)
+        walk(resolve(root, dir));
+    return found;
+}
+/** Every exported component under `dirs` (default `['src']`), sorted by tag. */
+export function scanTags(options) {
+    const entries = discoverComponents(options.root, options.dirs ?? ['src']).flatMap((c) => c.name === undefined ? [] : [{ tag: c.tag, file: c.file, name: c.name }]);
+    return entries.sort((x, y) => (x.tag < y.tag ? -1 : x.tag > y.tag ? 1 : 0));
+}
+/** The import specifier for `file` from `outFile`: relative, `.js` for TypeScript sources. */
+function specifier(outFile, file) {
+    const path = relative(dirname(outFile), file).split(sep).join('/');
+    const js = path.replace(/\.tsx?$/, '.js').replace(/\.mts$/, '.mjs');
+    return js.startsWith('.') ? js : `./${js}`;
+}
+/** The declaration file's text for `entries`, written to `outFile`. */
+export function tagMapSource(entries, outFile) {
+    const lines = entries.map((e) => `    ${JSON.stringify(e.tag)}: InstanceType<typeof import(${JSON.stringify(specifier(outFile, e.file))}).${e.name}>;`);
+    return ('/* eslint-disable */\n' +
+        '// Generated by @gyral/core (gyralVitePreset / gyral-types) from the define() calls in your\n' +
+        '// sources. Do not edit; gitignore .gyral/ and add ".gyral/elements.d.ts" to tsconfig "include".\n' +
+        'export {};\n\n' +
+        'declare global {\n' +
+        '  interface HTMLElementTagNameMap {\n' +
+        (lines.length === 0 ? '' : `${lines.join('\n')}\n`) +
+        '  }\n' +
+        '}\n');
+}
+/**
+ * Scans the sources and writes the declaration file when its content changed. Returns the
+ * entries and whether the file was written.
+ */
+export function writeTagMap(options) {
+    const outFile = join(options.root, options.out ?? '.gyral/elements.d.ts');
+    const entries = scanTags(options);
+    const text = tagMapSource(entries, outFile);
+    if (existsSync(outFile) && readFileSync(outFile, 'utf8') === text)
+        return { entries, written: false };
+    mkdirSync(dirname(outFile), { recursive: true });
+    writeFileSync(outFile, text);
+    return { entries, written: true };
+}
+/** The preset's `gyral:element-types` plugin (`gyralVitePreset({ types })`). */
+export function elementTypesPlugin(options) {
+    let root = process.cwd();
+    const regenerate = () => {
+        const settings = { root, ...options };
+        const out = join(root, options.out ?? '.gyral/elements.d.ts');
+        // A project without components gets no file.
+        if (scanTags(settings).length === 0 && !existsSync(out))
+            return;
+        writeTagMap(settings);
+    };
+    const isSource = (file) => /\.(?:ts|tsx|mts)$/.test(file) &&
+        (options.dirs ?? ['src']).some((dir) => file.startsWith(join(root, dir)));
+    return {
+        name: 'gyral:element-types',
+        configResolved(config) {
+            root = config.root;
+        },
+        buildStart() {
+            regenerate();
+        },
+        watchChange(id) {
+            if (isSource(id))
+                regenerate();
+        },
+        configureServer(server) {
+            const changed = (file) => {
+                if (isSource(file))
+                    regenerate();
+            };
+            server.watcher.on('add', changed).on('change', changed).on('unlink', changed);
+        },
+    };
+}
+//# sourceMappingURL=tag-map.js.map

package/dist/compiler/tag-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-map.js","sourceRoot":"","sources":["../../src/compiler/tag-map.ts"],"names":[],"mappings":"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","sourcesContent":["// Component discovery and generated element typings (gyral-1zd.22, gyral-1zd.25). One scan of\n// an app's sources for two-call `define<…>()('tag', …)` calls, read from the source text (not a\n// type check), shared by automatic component loading (./components.ts) and the typings: every\n// exported component becomes an `HTMLElementTagNameMap` entry, so apps stop hand-writing\n// `declare global { interface HTMLElementTagNameMap { … } }` blocks. Node built-ins only, so\n// ../vite.ts loads it with Node's require, from TypeScript source too.\nimport { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';\nimport { dirname, join, relative, resolve, sep } from 'node:path';\nimport type { Plugin } from 'vite';\nimport type { ElementTypesOptions } from '../vite.js';\n\nexport interface TagMapOptions {\n  /** Project root; `dirs` and `out` are relative to it. */\n  readonly root: string;\n  /** Source directories to scan, recursively. Default `['src']`. */\n  readonly dirs?: readonly string[];\n  /** The declaration file to write. Default `.gyral/elements.d.ts`. */\n  readonly out?: string;\n}\n\nexport interface TagEntry {\n  readonly tag: string;\n  readonly file: string;\n  readonly name: string;\n}\n\n/** One `define()`d component: its tag, the file defining it and, if exported, its binding. */\nexport interface Discovered {\n  readonly tag: string;\n  /** Absolute path of the defining module. */\n  readonly file: string;\n  /** `X` in `export const X = define…`; undefined for a component that isn't exported. */\n  readonly name: string | undefined;\n}\n\n/**\n * A two-call `define<…>()('tag'`, optionally as `export const Name = …`: the generics (lazy,\n * so nested `<…>` extend it), the empty call, then a string tag with a hyphen.\n * `customElements.define(` doesn't match.\n */\nconst DEFINE_TAG =\n  /(?:export\\s+const\\s+([A-Za-z_$][\\w$]*)\\s*(?::[^=;]+)?=\\s*)?(?<![.\\w$])define\\s*(?:<[\\s\\S]*?>)?\\s*\\(\\s*\\)\\s*\\(\\s*(['\"`])([a-z][a-z0-9._-]*-[a-z0-9._-]*)\\2/g;\nconst SOURCE_FILE = /\\.[cm]?[jt]sx?$/;\nconst SKIPPED = /\\.(?:test|spec|d)\\.[cm]?[jt]sx?$/;\n\n/** The components defined in one module's source text. */\nexport function componentsIn(code: string, file: string): Discovered[] {\n  if (!code.includes('define')) return [];\n  const out: Discovered[] = [];\n  for (const m of code.matchAll(DEFINE_TAG)) {\n    out.push({ tag: m[3] as string, file, name: m[1] });\n  }\n  return out;\n}\n\n/** Every component under `dirs` (relative to `root`), in file then source order. */\nexport function discoverComponents(root: string, dirs: readonly string[]): Discovered[] {\n  const found: Discovered[] = [];\n  const walk = (dir: string): void => {\n    let entries;\n    try {\n      entries = readdirSync(dir, { withFileTypes: true });\n    } catch {\n      return;\n    }\n    for (const entry of entries) {\n      const path = join(dir, entry.name);\n      if (entry.isDirectory()) {\n        if (entry.name !== 'node_modules' && !entry.name.startsWith('.')) walk(path);\n        continue;\n      }\n      if (!SOURCE_FILE.test(entry.name) || SKIPPED.test(entry.name)) continue;\n      found.push(...componentsIn(readFileSync(path, 'utf8'), path));\n    }\n  };\n  for (const dir of dirs) walk(resolve(root, dir));\n  return found;\n}\n\n/** Every exported component under `dirs` (default `['src']`), sorted by tag. */\nexport function scanTags(options: TagMapOptions): TagEntry[] {\n  const entries = discoverComponents(options.root, options.dirs ?? ['src']).flatMap((c) =>\n    c.name === undefined ? [] : [{ tag: c.tag, file: c.file, name: c.name }],\n  );\n  return entries.sort((x, y) => (x.tag < y.tag ? -1 : x.tag > y.tag ? 1 : 0));\n}\n\n/** The import specifier for `file` from `outFile`: relative, `.js` for TypeScript sources. */\nfunction specifier(outFile: string, file: string): string {\n  const path = relative(dirname(outFile), file).split(sep).join('/');\n  const js = path.replace(/\\.tsx?$/, '.js').replace(/\\.mts$/, '.mjs');\n  return js.startsWith('.') ? js : `./${js}`;\n}\n\n/** The declaration file's text for `entries`, written to `outFile`. */\nexport function tagMapSource(entries: readonly TagEntry[], outFile: string): string {\n  const lines = entries.map(\n    (e) =>\n      `    ${JSON.stringify(e.tag)}: InstanceType<typeof import(${JSON.stringify(specifier(outFile, e.file))}).${e.name}>;`,\n  );\n  return (\n    '/* eslint-disable */\\n' +\n    '// Generated by @gyral/core (gyralVitePreset / gyral-types) from the define() calls in your\\n' +\n    '// sources. Do not edit; gitignore .gyral/ and add \".gyral/elements.d.ts\" to tsconfig \"include\".\\n' +\n    'export {};\\n\\n' +\n    'declare global {\\n' +\n    '  interface HTMLElementTagNameMap {\\n' +\n    (lines.length === 0 ? '' : `${lines.join('\\n')}\\n`) +\n    '  }\\n' +\n    '}\\n'\n  );\n}\n\n/**\n * Scans the sources and writes the declaration file when its content changed. Returns the\n * entries and whether the file was written.\n */\nexport function writeTagMap(options: TagMapOptions): { entries: TagEntry[]; written: boolean } {\n  const outFile = join(options.root, options.out ?? '.gyral/elements.d.ts');\n  const entries = scanTags(options);\n  const text = tagMapSource(entries, outFile);\n  if (existsSync(outFile) && readFileSync(outFile, 'utf8') === text)\n    return { entries, written: false };\n  mkdirSync(dirname(outFile), { recursive: true });\n  writeFileSync(outFile, text);\n  return { entries, written: true };\n}\n\n/** The preset's `gyral:element-types` plugin (`gyralVitePreset({ types })`). */\nexport function elementTypesPlugin(options: ElementTypesOptions): Plugin {\n  let root = process.cwd();\n  const regenerate = (): void => {\n    const settings = { root, ...options };\n    const out = join(root, options.out ?? '.gyral/elements.d.ts');\n    // A project without components gets no file.\n    if (scanTags(settings).length === 0 && !existsSync(out)) return;\n    writeTagMap(settings);\n  };\n  const isSource = (file: string): boolean =>\n    /\\.(?:ts|tsx|mts)$/.test(file) &&\n    (options.dirs ?? ['src']).some((dir) => file.startsWith(join(root, dir)));\n  return {\n    name: 'gyral:element-types',\n    configResolved(config) {\n      root = config.root;\n    },\n    buildStart() {\n      regenerate();\n    },\n    watchChange(id) {\n      if (isSource(id)) regenerate();\n    },\n    configureServer(server) {\n      const changed = (file: string): void => {\n        if (isSource(file)) regenerate();\n      };\n      server.watcher.on('add', changed).on('change', changed).on('unlink', changed);\n    },\n  };\n}\n"]}

package/dist/components-ready.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolves once every rendered tag the component loader knows (in the document and in the
+ * shadow roots of components it defined) is defined, and the page has settled. Await it in
+ * browser tests and page scripts after the loader has run (page scripts placed after it; in
+ * tests, import `virtual:gyral/components` first).
+ */
+export declare function componentsReady(): Promise<void>;

package/dist/components-ready.js

@@ -0,0 +1,19 @@
+// `componentsReady()` (ADR 0016 "Automatic components"): wait until the components the page
+// renders are defined and have rendered. The loader that gyralVitePreset({ components: true })
+// generates registers itself under a well-known symbol; without it (no automatic components,
+// or a server render) this is just `settled()`.
+import { settled } from './settled.js';
+const KEY = Symbol.for('gyral.components');
+/**
+ * Resolves once every rendered tag the component loader knows (in the document and in the
+ * shadow roots of components it defined) is defined, and the page has settled. Await it in
+ * browser tests and page scripts after the loader has run (page scripts placed after it; in
+ * tests, import `virtual:gyral/components` first).
+ */
+export async function componentsReady() {
+    const loader = globalThis[KEY];
+    if (loader !== undefined)
+        await loader.ready();
+    await settled();
+}
+//# sourceMappingURL=components-ready.js.map

package/dist/components-ready.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"components-ready.js","sourceRoot":"","sources":["../src/components-ready.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,+FAA+F;AAC/F,6FAA6F;AAC7F,gDAAgD;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAMvC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,MAAM,MAAM,GAAI,UAA0C,CAAC,GAAG,CAAC,CAAC;IAChE,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAC/C,MAAM,OAAO,EAAE,CAAC;AAClB,CAAC","sourcesContent":["// `componentsReady()` (ADR 0016 \"Automatic components\"): wait until the components the page\n// renders are defined and have rendered. The loader that gyralVitePreset({ components: true })\n// generates registers itself under a well-known symbol; without it (no automatic components,\n// or a server render) this is just `settled()`.\nimport { settled } from './settled.js';\n\ninterface ComponentLoader {\n  readonly ready: () => Promise<void>;\n}\n\nconst KEY = Symbol.for('gyral.components');\n\n/**\n * Resolves once every rendered tag the component loader knows (in the document and in the\n * shadow roots of components it defined) is defined, and the page has settled. Await it in\n * browser tests and page scripts after the loader has run (page scripts placed after it; in\n * tests, import `virtual:gyral/components` first).\n */\nexport async function componentsReady(): Promise<void> {\n  const loader = (globalThis as { [KEY]?: ComponentLoader })[KEY];\n  if (loader !== undefined) await loader.ready();\n  await settled();\n}\n"]}

package/dist/define.d.ts

@@ -1,9 +1,17 @@
 import type { GyralElementClass } from './element-types.js';
 import type { ComponentSpec, Tagged } from './types.js';
 export type { GyralElement, GyralElementClass } from './element-types.js';
+/** The second call of `define()`: takes the tag and the spec, infers the intent names. */
+export type Definer<S, M extends Tagged, P extends object, O extends Tagged> = <N extends string = never>(tag: string, spec: ComponentSpec<S, M, P, N>) => GyralElementClass<S, M, P, O, N>;
 /**
- * Compiles a Model-View-Intent spec into a custom element and registers it under `tag`.
- * See docs/design-docs/0001-mvi-parsed-intent.md, 0006-effects-and-drivers.md, 0007-props.md,
- * 0008-forms.md and view/05-element.md.
+ * Compiles a Model-View-Intent spec into a custom element and registers it under `tag`. Two
+ * calls (ADR 0023): the first takes the types, the second the tag and spec, from whose
+ * `intent` keys it infers the component's intent names.
+ *
+ *   define<State, Msg>()('x-counter', { init, intent: { Increment: … }, update, view })
+ *
+ * With no type arguments, `define()('x-badge', spec)` infers the state, messages, props and
+ * intent names from the spec. Guide: https://gyral.dev/docs/components/
  */
-export declare function define<S, M extends Tagged, P extends object = object, O extends Tagged = never>(tag: string, spec: ComponentSpec<S, M, P>): GyralElementClass<S, M, P, O>;
+export declare function define(): <S, M extends Tagged = never, P extends object = object, N extends string = never>(tag: string, spec: ComponentSpec<S, M, P, N>) => GyralElementClass<S, M, P, never, N>;
+export declare function define<S, M extends Tagged = never, P extends object = object, O extends Tagged = never>(): Definer<S, M, P, O>;

package/dist/define.js

@@ -3,7 +3,7 @@ import { markGyralHost } from './intent.js';
 import { isLight } from './light-dom.js';
 import { features } from './features.js';
 import { recordSpec } from './server-specs.js';
-import { DEV } from './view/index.js';
+import { DEV, message } from './view/index.js';
 function checkSpec(tag, spec) {
     const names = Object.keys(spec.props ?? {});
     // The prop builders registered the prop feature (features.ts) if there are props.
@@ -13,22 +13,19 @@ function checkSpec(tag, spec) {
         console.warn(`<${tag}> has shadow: false, so its styles are ignored; use document CSS.`);
     }
 }
-/**
- * Compiles a Model-View-Intent spec into a custom element and registers it under `tag`.
- * See docs/design-docs/0001-mvi-parsed-intent.md, 0006-effects-and-drivers.md, 0007-props.md,
- * 0008-forms.md and view/05-element.md.
- */
-export function define(tag, spec) {
+// One function serves both call forms; the overloads type the result.
+export function define() {
+    return defineElement;
+}
+function defineElement(tag, spec) {
     checkSpec(tag, spec);
     if (typeof HTMLElement === 'undefined') {
         // No DOM (Node, Workers): the server renderer renders the spec itself (Phase 4). Only the
         // spec is recorded here, so the server registry code never reaches client bundles.
         recordSpec(tag, spec);
-        const Placeholder = Object.assign(function Placeholder() {
-            throw new Error(`<${tag}> is a browser element (render it with @gyral/core/server).`);
+        return Object.assign(function Placeholder() {
+            throw new Error(message(1, tag));
         }, { spec, tagName: tag });
-        // Sound enough: outside the browser the class only carries `spec` and `tagName`.
-        return Placeholder;
     }
     const existing = customElements.get(tag);
     if (existing !== undefined) {
@@ -40,7 +37,6 @@ export function define(tag, spec) {
     const Element = elementClass(tag, spec);
     markGyralHost(Element);
     customElements.define(tag, Element);
-    // Sound: every declared prop is an accessor on the prototype.
     return Element;
 }
 //# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAUtC,SAAS,SAAS,CAAC,GAAW,EAAE,IAAe;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC5C,kFAAkF;IAClF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAChE,IAAI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACtD,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,mEAAmE,CAAC,CAAC;IAC3F,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM,CACpB,GAAW,EACX,IAA4B;IAE5B,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACrB,IAAI,OAAO,WAAW,KAAK,WAAW,EAAE,CAAC;QACvC,0FAA0F;QAC1F,mFAAmF;QACnF,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACtB,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAC/B,SAAS,WAAW;YAClB,MAAM,IAAI,KAAK,CAAC,IAAI,GAAG,6DAA6D,CAAC,CAAC;QACxF,CAAC,EACD,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CACvB,CAAC;QACF,iFAAiF;QACjF,OAAO,WAAuD,CAAC;IACjE,CAAC;IACD,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,GAAG,IAAK,QAAwC,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACnE,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,gEAAgE,CAAC,CAAC;QACxF,CAAC;QACD,OAAO,QAAoD,CAAC;IAC9D,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxC,aAAa,CAAC,OAAO,CAAC,CAAC;IACvB,cAAc,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACpC,8DAA8D;IAC9D,OAAO,OAAmD,CAAC;AAC7D,CAAC","sourcesContent":["// `define(tag, spec)` (docs/design-docs/view/05-element.md): compiles a Model-View-Intent spec\n// into a custom element and registers it. Outside the browser it records the spec in the\n// server registry instead (view/06-server.md) and returns a placeholder class.\nimport type { GyralElementClass } from './element-types.js';\nimport { elementClass } from './element.js';\nimport { markGyralHost } from './intent.js';\nimport { isLight } from './light-dom.js';\nimport { features } from './features.js';\nimport { recordSpec } from './server-specs.js';\nimport type { ComponentSpec, Tagged } from './types.js';\nimport { DEV } from './view/index.js';\n\nexport type { GyralElement, GyralElementClass } from './element-types.js';\n\ninterface SpecShape {\n  readonly props?: object;\n  readonly shadow?: boolean;\n  readonly styles?: unknown;\n}\n\nfunction checkSpec(tag: string, spec: SpecShape): void {\n  const names = Object.keys(spec.props ?? {});\n  // The prop builders registered the prop feature (features.ts) if there are props.\n  if (names.length > 0) features.props?.checkShadowed(tag, names);\n  if (DEV && isLight(spec) && spec.styles !== undefined) {\n    console.warn(`<${tag}> has shadow: false, so its styles are ignored; use document CSS.`);\n  }\n}\n\n/**\n * Compiles a Model-View-Intent spec into a custom element and registers it under `tag`.\n * See docs/design-docs/0001-mvi-parsed-intent.md, 0006-effects-and-drivers.md, 0007-props.md,\n * 0008-forms.md and view/05-element.md.\n */\nexport function define<S, M extends Tagged, P extends object = object, O extends Tagged = never>(\n  tag: string,\n  spec: ComponentSpec<S, M, P>,\n): GyralElementClass<S, M, P, O> {\n  checkSpec(tag, spec);\n  if (typeof HTMLElement === 'undefined') {\n    // No DOM (Node, Workers): the server renderer renders the spec itself (Phase 4). Only the\n    // spec is recorded here, so the server registry code never reaches client bundles.\n    recordSpec(tag, spec);\n    const Placeholder = Object.assign(\n      function Placeholder(): never {\n        throw new Error(`<${tag}> is a browser element (render it with @gyral/core/server).`);\n      },\n      { spec, tagName: tag },\n    );\n    // Sound enough: outside the browser the class only carries `spec` and `tagName`.\n    return Placeholder as unknown as GyralElementClass<S, M, P, O>;\n  }\n  const existing = customElements.get(tag);\n  if (existing !== undefined) {\n    if (DEV && (existing as { readonly spec?: unknown }).spec !== spec) {\n      console.warn(`<${tag}> is already defined with a different spec; keeping the first.`);\n    }\n    return existing as unknown as GyralElementClass<S, M, P, O>;\n  }\n  const Element = elementClass(tag, spec);\n  markGyralHost(Element);\n  customElements.define(tag, Element);\n  // Sound: every declared prop is an accessor on the prototype.\n  return Element as unknown as GyralElementClass<S, M, P, O>;\n}\n"]}
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAU/C,SAAS,SAAS,CAAC,GAAW,EAAE,IAAe;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC5C,kFAAkF;IAClF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAChE,IAAI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACtD,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,mEAAmE,CAAC,CAAC;IAC3F,CAAC;AACH,CAAC;AAoCD,sEAAsE;AACtE,MAAM,UAAU,MAAM;IACpB,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,SAAS,aAAa,CAAC,GAAW,EAAE,IAA4C;IAC9E,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACrB,IAAI,OAAO,WAAW,KAAK,WAAW,EAAE,CAAC;QACvC,0FAA0F;QAC1F,mFAAmF;QACnF,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACtB,OAAO,MAAM,CAAC,MAAM,CAClB,SAAS,WAAW;YAClB,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC,EACD,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CACvB,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,GAAG,IAAK,QAAwC,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACnE,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,gEAAgE,CAAC,CAAC;QACxF,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxC,aAAa,CAAC,OAAO,CAAC,CAAC;IACvB,cAAc,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["// `define<S, M>()(tag, spec)` (docs/design-docs/view/05-element.md, ADR 0023): compiles a\n// Model-View-Intent spec into a custom element and registers it. Outside the browser it\n// records the spec in the server registry instead (view/06-server.md) and returns a\n// placeholder class.\nimport type { GyralElementClass } from './element-types.js';\nimport { elementClass } from './element.js';\nimport { markGyralHost } from './intent.js';\nimport { isLight } from './light-dom.js';\nimport { features } from './features.js';\nimport { recordSpec } from './server-specs.js';\nimport type { ComponentSpec, ShadowOption, Tagged } from './types.js';\nimport { DEV, message } from './view/index.js';\n\nexport type { GyralElement, GyralElementClass } from './element-types.js';\n\ninterface SpecShape {\n  readonly props?: object;\n  readonly shadow?: ShadowOption;\n  readonly styles?: unknown;\n}\n\nfunction checkSpec(tag: string, spec: SpecShape): void {\n  const names = Object.keys(spec.props ?? {});\n  // The prop builders registered the prop feature (features.ts) if there are props.\n  if (names.length > 0) features.props?.checkShadowed(tag, names);\n  if (DEV && isLight(spec) && spec.styles !== undefined) {\n    console.warn(`<${tag}> has shadow: false, so its styles are ignored; use document CSS.`);\n  }\n}\n\n/** The second call of `define()`: takes the tag and the spec, infers the intent names. */\nexport type Definer<S, M extends Tagged, P extends object, O extends Tagged> = <\n  N extends string = never,\n>(\n  tag: string,\n  spec: ComponentSpec<S, M, P, N>,\n) => GyralElementClass<S, M, P, O, N>;\n\n/**\n * Compiles a Model-View-Intent spec into a custom element and registers it under `tag`. Two\n * calls (ADR 0023): the first takes the types, the second the tag and spec, from whose\n * `intent` keys it infers the component's intent names.\n *\n *   define<State, Msg>()('x-counter', { init, intent: { Increment: … }, update, view })\n *\n * With no type arguments, `define()('x-badge', spec)` infers the state, messages, props and\n * intent names from the spec. Guide: https://gyral.dev/docs/components/\n */\nexport function define(): <\n  S,\n  M extends Tagged = never,\n  P extends object = object,\n  N extends string = never,\n>(\n  tag: string,\n  spec: ComponentSpec<S, M, P, N>,\n) => GyralElementClass<S, M, P, never, N>;\nexport function define<\n  S,\n  // No messages: `define<State>()` for a pure view (intent and update optional).\n  M extends Tagged = never,\n  P extends object = object,\n  O extends Tagged = never,\n>(): Definer<S, M, P, O>;\n// One function serves both call forms; the overloads type the result.\nexport function define(): (tag: string, spec: never) => unknown {\n  return defineElement;\n}\n\nfunction defineElement(tag: string, spec: ComponentSpec<unknown, Tagged, object>): unknown {\n  checkSpec(tag, spec);\n  if (typeof HTMLElement === 'undefined') {\n    // No DOM (Node, Workers): the server renderer renders the spec itself (Phase 4). Only the\n    // spec is recorded here, so the server registry code never reaches client bundles.\n    recordSpec(tag, spec);\n    return Object.assign(\n      function Placeholder(): never {\n        throw new Error(message(1, tag));\n      },\n      { spec, tagName: tag },\n    );\n  }\n  const existing = customElements.get(tag);\n  if (existing !== undefined) {\n    if (DEV && (existing as { readonly spec?: unknown }).spec !== spec) {\n      console.warn(`<${tag}> is already defined with a different spec; keeping the first.`);\n    }\n    return existing;\n  }\n  const Element = elementClass(tag, spec);\n  markGyralHost(Element);\n  customElements.define(tag, Element);\n  return Element;\n}\n"]}

package/dist/devtools-events.d.ts

@@ -44,6 +44,14 @@ export type DevEvent = {
     readonly kind: 'command';
     readonly owner: string;
 } & CommandTraceEvent) | {
+    /** A failure Gyral caught (ADR 0024): `component` is absent for stores and shared work. */
+    readonly kind: 'error';
+    readonly component?: DevComponentRef;
+    readonly phase: string;
+    readonly msg?: string;
+    readonly message: string;
+    readonly error: unknown;
+} | {
     readonly kind: 'store';
     readonly store: string;
     readonly msg: Tagged;

package/dist/devtools-events.js.map

@@ -1 +1 @@
-{"version":3,"file":"devtools-events.js","sourceRoot":"","sources":["../src/devtools-events.ts"],"names":[],"mappings":"AAKA,oFAAoF;AACpF,MAAM,CAAC,MAAM,eAAe,GAAG,oBAAoB,CAAC","sourcesContent":["// The devtools event stream (ADR 0017). Types and the global hook name only: the emitting code\n// lives in devtools.ts (development builds) and devtools-off.ts (production builds).\nimport type { Concurrency } from './command.js';\nimport type { Tagged } from './types.js';\n\n/** Where a listener installs itself: `globalThis.__GYRAL_DEVTOOLS__ = { emit }`. */\nexport const DEVTOOLS_GLOBAL = '__GYRAL_DEVTOOLS__';\n\n/** A live component, identified for the timeline. `element` gives the panel its state. */\nexport interface DevComponentRef {\n  readonly tag: string;\n  readonly id: number;\n  readonly element: Element;\n}\n\nexport type CommandPhase = 'issued' | 'dropped' | 'settled' | 'failed' | 'interrupted';\n\n/** What the interpreter reports about one command (ADR 0006 lanes and policies). */\nexport interface CommandTraceEvent {\n  readonly phase: CommandPhase;\n  readonly driver: string;\n  readonly lane: string;\n  readonly policy: Concurrency;\n  readonly input: unknown;\n  /** Driver output (`settled`) or error (`failed`). */\n  readonly result?: unknown;\n}\n\nexport type CommandTrace = (event: CommandTraceEvent) => void;\n\nexport type DevEvent = { readonly at: number } & (\n  | { readonly kind: 'connect' | 'disconnect'; readonly component: DevComponentRef }\n  | {\n      readonly kind: 'update';\n      readonly component: DevComponentRef;\n      readonly msg: Tagged;\n      readonly prev: unknown;\n      readonly next: unknown;\n    }\n  | {\n      readonly kind: 'hydrated';\n      readonly component: DevComponentRef;\n      readonly serverRendered: boolean;\n    }\n  | {\n      /** The server DOM didn't match the first render (view/07-hydration.md \"Mismatches\"). */\n      readonly kind: 'mismatch';\n      readonly component: DevComponentRef;\n      readonly message: string;\n    }\n  | ({ readonly kind: 'command'; readonly owner: string } & CommandTraceEvent)\n  | {\n      readonly kind: 'store';\n      readonly store: string;\n      readonly msg: Tagged;\n      readonly prev: unknown;\n      readonly next: unknown;\n    }\n);\n\n/** Installed by a devtools panel (or a test) on `globalThis[DEVTOOLS_GLOBAL]`. */\nexport interface DevtoolsHook {\n  emit(event: DevEvent): void;\n}\n"]}
+{"version":3,"file":"devtools-events.js","sourceRoot":"","sources":["../src/devtools-events.ts"],"names":[],"mappings":"AAKA,oFAAoF;AACpF,MAAM,CAAC,MAAM,eAAe,GAAG,oBAAoB,CAAC","sourcesContent":["// The devtools event stream (ADR 0017). Types and the global hook name only: the emitting code\n// lives in devtools.ts (development builds) and devtools-off.ts (production builds).\nimport type { Concurrency } from './command.js';\nimport type { Tagged } from './types.js';\n\n/** Where a listener installs itself: `globalThis.__GYRAL_DEVTOOLS__ = { emit }`. */\nexport const DEVTOOLS_GLOBAL = '__GYRAL_DEVTOOLS__';\n\n/** A live component, identified for the timeline. `element` gives the panel its state. */\nexport interface DevComponentRef {\n  readonly tag: string;\n  readonly id: number;\n  readonly element: Element;\n}\n\nexport type CommandPhase = 'issued' | 'dropped' | 'settled' | 'failed' | 'interrupted';\n\n/** What the interpreter reports about one command (ADR 0006 lanes and policies). */\nexport interface CommandTraceEvent {\n  readonly phase: CommandPhase;\n  readonly driver: string;\n  readonly lane: string;\n  readonly policy: Concurrency;\n  readonly input: unknown;\n  /** Driver output (`settled`) or error (`failed`). */\n  readonly result?: unknown;\n}\n\nexport type CommandTrace = (event: CommandTraceEvent) => void;\n\nexport type DevEvent = { readonly at: number } & (\n  | { readonly kind: 'connect' | 'disconnect'; readonly component: DevComponentRef }\n  | {\n      readonly kind: 'update';\n      readonly component: DevComponentRef;\n      readonly msg: Tagged;\n      readonly prev: unknown;\n      readonly next: unknown;\n    }\n  | {\n      readonly kind: 'hydrated';\n      readonly component: DevComponentRef;\n      readonly serverRendered: boolean;\n    }\n  | {\n      /** The server DOM didn't match the first render (view/07-hydration.md \"Mismatches\"). */\n      readonly kind: 'mismatch';\n      readonly component: DevComponentRef;\n      readonly message: string;\n    }\n  | ({ readonly kind: 'command'; readonly owner: string } & CommandTraceEvent)\n  | {\n      /** A failure Gyral caught (ADR 0024): `component` is absent for stores and shared work. */\n      readonly kind: 'error';\n      readonly component?: DevComponentRef;\n      readonly phase: string;\n      readonly msg?: string;\n      readonly message: string;\n      readonly error: unknown;\n    }\n  | {\n      readonly kind: 'store';\n      readonly store: string;\n      readonly msg: Tagged;\n      readonly prev: unknown;\n      readonly next: unknown;\n    }\n);\n\n/** Installed by a devtools panel (or a test) on `globalThis[DEVTOOLS_GLOBAL]`. */\nexport interface DevtoolsHook {\n  emit(event: DevEvent): void;\n}\n"]}

package/dist/devtools-off.d.ts

@@ -5,6 +5,7 @@ export declare const devUpdate: typeof Dev.devUpdate;
 export declare const devHydrated: typeof Dev.devHydrated;
 export declare const devMismatch: typeof Dev.devMismatch;
 export declare const devStore: typeof Dev.devStore;
+export declare const devError: typeof Dev.devError;
 export declare const devCommands: typeof Dev.devCommands;
 export declare const devOwner: typeof Dev.devOwner;
 export declare const devLiveComponents: typeof Dev.devLiveComponents;

package/dist/devtools-off.js

@@ -5,6 +5,7 @@ export const devUpdate = noop;
 export const devHydrated = noop;
 export const devMismatch = noop;
 export const devStore = noop;
+export const devError = noop;
 export const devCommands = () => noop;
 export const devOwner = () => '';
 export const devLiveComponents = () => [];

package/dist/devtools-off.js.map

@@ -1 +1 @@
-{"version":3,"file":"devtools-off.js","sourceRoot":"","sources":["../src/devtools-off.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,gBAAgB,GAAY,KAAK,CAAC;AAE/C,MAAM,IAAI,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAEnC,MAAM,CAAC,MAAM,UAAU,GAA0B,IAAI,CAAC;AACtD,MAAM,CAAC,MAAM,SAAS,GAAyB,IAAI,CAAC;AACpD,MAAM,CAAC,MAAM,WAAW,GAA2B,IAAI,CAAC;AACxD,MAAM,CAAC,MAAM,WAAW,GAA2B,IAAI,CAAC;AACxD,MAAM,CAAC,MAAM,QAAQ,GAAwB,IAAI,CAAC;AAClD,MAAM,CAAC,MAAM,WAAW,GAA2B,GAAG,EAAE,CAAC,IAAI,CAAC;AAC9D,MAAM,CAAC,MAAM,QAAQ,GAAwB,GAAG,EAAE,CAAC,EAAE,CAAC;AACtD,MAAM,CAAC,MAAM,iBAAiB,GAAiC,GAAG,EAAE,CAAC,EAAE,CAAC","sourcesContent":["// Production build of the devtools hook (ADR 0017): the same names as devtools.ts, doing\n// nothing. Call sites guard with DEVTOOLS_ENABLED, a literal `false` here, so bundlers drop\n// them entirely. The `typeof Dev.x` annotations keep both modules' signatures in sync.\nimport type * as Dev from './devtools.js';\n\nexport const DEVTOOLS_ENABLED: boolean = false;\n\nconst noop = (): void => undefined;\n\nexport const devConnect: typeof Dev.devConnect = noop;\nexport const devUpdate: typeof Dev.devUpdate = noop;\nexport const devHydrated: typeof Dev.devHydrated = noop;\nexport const devMismatch: typeof Dev.devMismatch = noop;\nexport const devStore: typeof Dev.devStore = noop;\nexport const devCommands: typeof Dev.devCommands = () => noop;\nexport const devOwner: typeof Dev.devOwner = () => '';\nexport const devLiveComponents: typeof Dev.devLiveComponents = () => [];\n"]}
+{"version":3,"file":"devtools-off.js","sourceRoot":"","sources":["../src/devtools-off.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,gBAAgB,GAAY,KAAK,CAAC;AAE/C,MAAM,IAAI,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAEnC,MAAM,CAAC,MAAM,UAAU,GAA0B,IAAI,CAAC;AACtD,MAAM,CAAC,MAAM,SAAS,GAAyB,IAAI,CAAC;AACpD,MAAM,CAAC,MAAM,WAAW,GAA2B,IAAI,CAAC;AACxD,MAAM,CAAC,MAAM,WAAW,GAA2B,IAAI,CAAC;AACxD,MAAM,CAAC,MAAM,QAAQ,GAAwB,IAAI,CAAC;AAClD,MAAM,CAAC,MAAM,QAAQ,GAAwB,IAAI,CAAC;AAClD,MAAM,CAAC,MAAM,WAAW,GAA2B,GAAG,EAAE,CAAC,IAAI,CAAC;AAC9D,MAAM,CAAC,MAAM,QAAQ,GAAwB,GAAG,EAAE,CAAC,EAAE,CAAC;AACtD,MAAM,CAAC,MAAM,iBAAiB,GAAiC,GAAG,EAAE,CAAC,EAAE,CAAC","sourcesContent":["// Production build of the devtools hook (ADR 0017): the same names as devtools.ts, doing\n// nothing. Call sites guard with DEVTOOLS_ENABLED, a literal `false` here, so bundlers drop\n// them entirely. The `typeof Dev.x` annotations keep both modules' signatures in sync.\nimport type * as Dev from './devtools.js';\n\nexport const DEVTOOLS_ENABLED: boolean = false;\n\nconst noop = (): void => undefined;\n\nexport const devConnect: typeof Dev.devConnect = noop;\nexport const devUpdate: typeof Dev.devUpdate = noop;\nexport const devHydrated: typeof Dev.devHydrated = noop;\nexport const devMismatch: typeof Dev.devMismatch = noop;\nexport const devStore: typeof Dev.devStore = noop;\nexport const devError: typeof Dev.devError = noop;\nexport const devCommands: typeof Dev.devCommands = () => noop;\nexport const devOwner: typeof Dev.devOwner = () => '';\nexport const devLiveComponents: typeof Dev.devLiveComponents = () => [];\n"]}

package/dist/devtools.d.ts

@@ -1,4 +1,5 @@
 import { type CommandTrace, type DevComponentRef } from './devtools-events.js';
+import type { GyralError } from './errors.js';
 import type { Tagged } from './types.js';
 export declare const DEVTOOLS_ENABLED: boolean;
 /** Components connected right now, for a panel that starts after they did. */
@@ -8,6 +9,8 @@ export declare function devUpdate(element: Element, tag: string, msg: Tagged, pr
 export declare function devHydrated(element: Element, tag: string, serverRendered: boolean): void;
 export declare function devMismatch(element: Element, tag: string, message: string): void;
 export declare function devStore(store: string, msg: Tagged, prev: unknown, next: unknown): void;
+/** A failure `fail()` reported (ADR 0024); `element` is the failing host, if any. */
+export declare function devError(element: Element | undefined, error: GyralError): void;
 /** A command tracer for one owner (`<tag>#id` or `store:name`). */
 export declare function devCommands(owner: () => string): CommandTrace;
 /** The label the panel shows for a component's commands. */

package/dist/devtools.js

@@ -56,6 +56,20 @@ export function devMismatch(element, tag, message) {
 export function devStore(store, msg, prev, next) {
     emit(() => ({ kind: 'store', store, msg, prev, next, at: now() }));
 }
+/** A failure `fail()` reported (ADR 0024); `element` is the failing host, if any. */
+export function devError(element, error) {
+    emit(() => ({
+        kind: 'error',
+        ...(element === undefined
+            ? {}
+            : { component: ref(element, error.component ?? element.localName) }),
+        phase: error.phase,
+        ...(error.msg === undefined ? {} : { msg: error.msg }),
+        message: error.message,
+        error: error.cause,
+        at: now(),
+    }));
+}
 /** A command tracer for one owner (`<tag>#id` or `store:name`). */
 export function devCommands(owner) {
     return (event) => {

package/dist/devtools.js.map

@@ -1 +1 @@
-{"version":3,"file":"devtools.js","sourceRoot":"","sources":["../src/devtools.ts"],"names":[],"mappings":"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","sourcesContent":["// Development build of the devtools hook (ADR 0017). Resolved through the `#devtools` import\n// with the `development` condition; production builds get devtools-off.ts instead, so the\n// guarded call sites (`if (DEVTOOLS_ENABLED) …`) disappear from the bundle.\nimport {\n  DEVTOOLS_GLOBAL,\n  type CommandTrace,\n  type DevComponentRef,\n  type DevEvent,\n  type DevtoolsHook,\n} from './devtools-events.js';\nimport type { Tagged } from './types.js';\n\nexport const DEVTOOLS_ENABLED: boolean = true;\n\nconst hook = (): DevtoolsHook | undefined =>\n  (globalThis as Record<string, unknown>)[DEVTOOLS_GLOBAL] as DevtoolsHook | undefined;\n\nconst ids = new WeakMap<Element, number>();\nlet nextId = 1;\n\nfunction ref(element: Element, tag: string): DevComponentRef {\n  let id = ids.get(element);\n  if (id === undefined) {\n    id = nextId++;\n    ids.set(element, id);\n  }\n  return { tag, id, element };\n}\n\n// Builds nothing unless a listener is installed: zero cost in dev without devtools.\nfunction emit(make: () => DevEvent): void {\n  const listener = hook();\n  if (listener === undefined) return;\n  try {\n    listener.emit(make());\n  } catch (error) {\n    console.error('gyral devtools listener threw', error);\n  }\n}\n\nconst now = (): number => performance.now();\n\n/** Connected components, so a panel loaded later still lists them (dev builds only). */\nconst live = new Map<Element, string>();\n\n/** Components connected right now, for a panel that starts after they did. */\nexport function devLiveComponents(): readonly DevComponentRef[] {\n  return [...live].map(([element, tag]) => ref(element, tag));\n}\n\nexport function devConnect(element: Element, tag: string, connected: boolean): void {\n  if (connected) live.set(element, tag);\n  else live.delete(element);\n  emit(() => ({\n    kind: connected ? 'connect' : 'disconnect',\n    component: ref(element, tag),\n    at: now(),\n  }));\n}\n\nexport function devUpdate(\n  element: Element,\n  tag: string,\n  msg: Tagged,\n  prev: unknown,\n  next: unknown,\n) {\n  emit(() => ({ kind: 'update', component: ref(element, tag), msg, prev, next, at: now() }));\n}\n\nexport function devHydrated(element: Element, tag: string, serverRendered: boolean): void {\n  emit(() => ({ kind: 'hydrated', component: ref(element, tag), serverRendered, at: now() }));\n}\n\nexport function devMismatch(element: Element, tag: string, message: string): void {\n  emit(() => ({ kind: 'mismatch', component: ref(element, tag), message, at: now() }));\n}\n\nexport function devStore(store: string, msg: Tagged, prev: unknown, next: unknown): void {\n  emit(() => ({ kind: 'store', store, msg, prev, next, at: now() }));\n}\n\n/** A command tracer for one owner (`<tag>#id` or `store:name`). */\nexport function devCommands(owner: () => string): CommandTrace {\n  return (event) => {\n    emit(() => ({ kind: 'command', owner: owner(), ...event, at: now() }));\n  };\n}\n\n/** The label the panel shows for a component's commands. */\nexport function devOwner(element: Element, tag: string): string {\n  return `<${tag}>#${String(ref(element, tag).id)}`;\n}\n"]}
+{"version":3,"file":"devtools.js","sourceRoot":"","sources":["../src/devtools.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,0FAA0F;AAC1F,4EAA4E;AAC5E,OAAO,EACL,eAAe,GAKhB,MAAM,sBAAsB,CAAC;AAI9B,MAAM,CAAC,MAAM,gBAAgB,GAAY,IAAI,CAAC;AAE9C,MAAM,IAAI,GAAG,GAA6B,EAAE,CACzC,UAAsC,CAAC,eAAe,CAA6B,CAAC;AAEvF,MAAM,GAAG,GAAG,IAAI,OAAO,EAAmB,CAAC;AAC3C,IAAI,MAAM,GAAG,CAAC,CAAC;AAEf,SAAS,GAAG,CAAC,OAAgB,EAAE,GAAW;IACxC,IAAI,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1B,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,EAAE,GAAG,MAAM,EAAE,CAAC;QACd,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC;AAED,oFAAoF;AACpF,SAAS,IAAI,CAAC,IAAoB;IAChC,MAAM,QAAQ,GAAG,IAAI,EAAE,CAAC;IACxB,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO;IACnC,IAAI,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED,MAAM,GAAG,GAAG,GAAW,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;AAE5C,wFAAwF;AACxF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAC;AAExC,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAgB,EAAE,GAAW,EAAE,SAAkB;IAC1E,IAAI,SAAS;QAAE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;;QACjC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1B,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACV,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY;QAC1C,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC;QAC5B,EAAE,EAAE,GAAG,EAAE;KACV,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,OAAgB,EAChB,GAAW,EACX,GAAW,EACX,IAAa,EACb,IAAa;IAEb,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAgB,EAAE,GAAW,EAAE,cAAuB;IAChF,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,cAAc,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AAC9F,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAgB,EAAE,GAAW,EAAE,OAAe;IACxE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AACvF,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,GAAW,EAAE,IAAa,EAAE,IAAa;IAC/E,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,OAA4B,EAAE,KAAiB;IACtE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACV,IAAI,EAAE,OAAO;QACb,GAAG,CAAC,OAAO,KAAK,SAAS;YACvB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACtE,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;QACtD,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,EAAE,EAAE,GAAG,EAAE;KACV,CAAC,CAAC,CAAC;AACN,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC7C,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;IACzE,CAAC,CAAC;AACJ,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,QAAQ,CAAC,OAAgB,EAAE,GAAW;IACpD,OAAO,IAAI,GAAG,KAAK,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACpD,CAAC","sourcesContent":["// Development build of the devtools hook (ADR 0017). Resolved through the `#devtools` import\n// with the `development` condition; production builds get devtools-off.ts instead, so the\n// guarded call sites (`if (DEVTOOLS_ENABLED) …`) disappear from the bundle.\nimport {\n  DEVTOOLS_GLOBAL,\n  type CommandTrace,\n  type DevComponentRef,\n  type DevEvent,\n  type DevtoolsHook,\n} from './devtools-events.js';\nimport type { GyralError } from './errors.js';\nimport type { Tagged } from './types.js';\n\nexport const DEVTOOLS_ENABLED: boolean = true;\n\nconst hook = (): DevtoolsHook | undefined =>\n  (globalThis as Record<string, unknown>)[DEVTOOLS_GLOBAL] as DevtoolsHook | undefined;\n\nconst ids = new WeakMap<Element, number>();\nlet nextId = 1;\n\nfunction ref(element: Element, tag: string): DevComponentRef {\n  let id = ids.get(element);\n  if (id === undefined) {\n    id = nextId++;\n    ids.set(element, id);\n  }\n  return { tag, id, element };\n}\n\n// Builds nothing unless a listener is installed: zero cost in dev without devtools.\nfunction emit(make: () => DevEvent): void {\n  const listener = hook();\n  if (listener === undefined) return;\n  try {\n    listener.emit(make());\n  } catch (error) {\n    console.error('gyral devtools listener threw', error);\n  }\n}\n\nconst now = (): number => performance.now();\n\n/** Connected components, so a panel loaded later still lists them (dev builds only). */\nconst live = new Map<Element, string>();\n\n/** Components connected right now, for a panel that starts after they did. */\nexport function devLiveComponents(): readonly DevComponentRef[] {\n  return [...live].map(([element, tag]) => ref(element, tag));\n}\n\nexport function devConnect(element: Element, tag: string, connected: boolean): void {\n  if (connected) live.set(element, tag);\n  else live.delete(element);\n  emit(() => ({\n    kind: connected ? 'connect' : 'disconnect',\n    component: ref(element, tag),\n    at: now(),\n  }));\n}\n\nexport function devUpdate(\n  element: Element,\n  tag: string,\n  msg: Tagged,\n  prev: unknown,\n  next: unknown,\n) {\n  emit(() => ({ kind: 'update', component: ref(element, tag), msg, prev, next, at: now() }));\n}\n\nexport function devHydrated(element: Element, tag: string, serverRendered: boolean): void {\n  emit(() => ({ kind: 'hydrated', component: ref(element, tag), serverRendered, at: now() }));\n}\n\nexport function devMismatch(element: Element, tag: string, message: string): void {\n  emit(() => ({ kind: 'mismatch', component: ref(element, tag), message, at: now() }));\n}\n\nexport function devStore(store: string, msg: Tagged, prev: unknown, next: unknown): void {\n  emit(() => ({ kind: 'store', store, msg, prev, next, at: now() }));\n}\n\n/** A failure `fail()` reported (ADR 0024); `element` is the failing host, if any. */\nexport function devError(element: Element | undefined, error: GyralError): void {\n  emit(() => ({\n    kind: 'error',\n    ...(element === undefined\n      ? {}\n      : { component: ref(element, error.component ?? element.localName) }),\n    phase: error.phase,\n    ...(error.msg === undefined ? {} : { msg: error.msg }),\n    message: error.message,\n    error: error.cause,\n    at: now(),\n  }));\n}\n\n/** A command tracer for one owner (`<tag>#id` or `store:name`). */\nexport function devCommands(owner: () => string): CommandTrace {\n  return (event) => {\n    emit(() => ({ kind: 'command', owner: owner(), ...event, at: now() }));\n  };\n}\n\n/** The label the panel shows for a component's commands. */\nexport function devOwner(element: Element, tag: string): string {\n  return `<${tag}>#${String(ref(element, tag).id)}`;\n}\n"]}

package/dist/drivers-scope.js.map

@@ -1 +1 @@
-{"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) → spec.drivers →\n// the command's own driver. 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"]}
+{"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

@@ -2,8 +2,7 @@ import type { DriverOverrides } from './command.js';
 import type { StoreOverrides } from './store.js';
 import type { ComponentSpec, Tagged } from './types.js';
 /**
- * The custom element `define()` produces: a plain `HTMLElement` (view/05-element.md "Public
- * instance API"). Tests wait for rendering with `settled()`.
+ * The custom element `define()` produces: a plain `HTMLElement`. Tests wait for rendering with `settled()`.
  */
 export interface GyralElement<S, M extends Tagged> extends HTMLElement {
     /** Current model state. */
@@ -24,13 +23,17 @@ export interface GyralElement<S, M extends Tagged> extends HTMLElement {
      */
     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 { 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<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`. 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"]}