@gyral/core 0.0.0 → 0.1.0

package/dist/invokers.js

@@ -0,0 +1,64 @@
+// Invoker commands as an intent source (gyral-czi.6, ADR 0001 addendum, ADR 0003).
+//
+//   <button type="button" commandfor="cart" command="--clear">Clear</button>
+//   <section id="cart" data-intent=${i.Clear} data-intent-on="command">…</section>
+//
+// Browsers with invoker commands dispatch a `CommandEvent` on the target. Elsewhere (invokers
+// are Baseline newly available, not widely) Gyral dispatches an equivalent `command` event when
+// a custom-command (`--…`) invoker inside a component is clicked, so the same markup works.
+// Built-in commands (`show-modal`, `toggle-popover`, …) are left to the browser.
+/** Native invoker commands available? */
+export const invokersSupported = () => 'CommandEvent' in globalThis;
+/** The command carried by a native `CommandEvent` or by Gyral's fallback event. */
+export function commandOf(event) {
+    if (event.type !== 'command')
+        return undefined;
+    if (event instanceof CustomEvent) {
+        const detail = event.detail;
+        return typeof detail?.command === 'string'
+            ? { command: detail.command, source: detail.source }
+            : undefined;
+    }
+    const native = event;
+    return typeof native.command === 'string'
+        ? {
+            command: native.command,
+            source: native.source instanceof Element ? native.source : undefined,
+        }
+        : undefined;
+}
+/** The custom-command invoker an event passed through, if any. */
+function invokerIn(event) {
+    for (const node of event.composedPath()) {
+        if (node instanceof Element &&
+            node.getAttribute('command')?.startsWith('--') === true &&
+            node.hasAttribute('commandfor')) {
+            return node;
+        }
+    }
+    return undefined;
+}
+/**
+ * Fallback for browsers without invoker commands: a click on a `command="--…"` invoker inside
+ * `root` dispatches a `command` CustomEvent on its `commandfor` target (same tree scope).
+ */
+export function shimInvokers(root) {
+    root.addEventListener('click', (event) => {
+        if (invokersSupported())
+            return;
+        const invoker = invokerIn(event);
+        const id = invoker?.getAttribute('commandfor');
+        const command = invoker?.getAttribute('command');
+        if (invoker === undefined || id == null || command == null)
+            return;
+        const scope = invoker.getRootNode();
+        const target = scope.getElementById(id);
+        if (target === null)
+            return;
+        target.dispatchEvent(new CustomEvent('command', {
+            detail: { command, source: invoker },
+            cancelable: true,
+        }));
+    });
+}
+//# sourceMappingURL=invokers.js.map

package/dist/invokers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invokers.js","sourceRoot":"","sources":["../src/invokers.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,EAAE;AACF,6EAA6E;AAC7E,mFAAmF;AACnF,EAAE;AACF,8FAA8F;AAC9F,gGAAgG;AAChG,4FAA4F;AAC5F,iFAAiF;AASjF,yCAAyC;AACzC,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAY,EAAE,CAAC,cAAc,IAAI,UAAU,CAAC;AAE7E,mFAAmF;AACnF,MAAM,UAAU,SAAS,CAAC,KAAY;IACpC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC/C,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAqC,CAAC;QAC3D,OAAO,OAAO,MAAM,EAAE,OAAO,KAAK,QAAQ;YACxC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;YACpD,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IACD,MAAM,MAAM,GAAG,KAAwD,CAAC;IACxE,OAAO,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;QACvC,CAAC,CAAC;YACE,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,MAAM,CAAC,MAAM,YAAY,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;SACrE;QACH,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,kEAAkE;AAClE,SAAS,SAAS,CAAC,KAAY;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,YAAY,EAAE,EAAE,CAAC;QACxC,IACE,IAAI,YAAY,OAAO;YACvB,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,KAAK,IAAI;YACvD,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,EAC/B,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QACvC,IAAI,iBAAiB,EAAE;YAAE,OAAO;QAChC,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,EAAE,GAAG,OAAO,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;QAC/C,MAAM,OAAO,GAAG,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,OAAO,KAAK,SAAS,IAAI,EAAE,IAAI,IAAI,IAAI,OAAO,IAAI,IAAI;YAAE,OAAO;QACnE,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAA2B,CAAC;QAC7D,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;QACxC,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO;QAC5B,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CAAc,SAAS,EAAE;YACtC,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;YACpC,UAAU,EAAE,IAAI;SACjB,CAAC,CACH,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["// Invoker commands as an intent source (gyral-czi.6, ADR 0001 addendum, ADR 0003).\n//\n//   <button type=\"button\" commandfor=\"cart\" command=\"--clear\">Clear</button>\n//   <section id=\"cart\" data-intent=${i.Clear} data-intent-on=\"command\">…</section>\n//\n// Browsers with invoker commands dispatch a `CommandEvent` on the target. Elsewhere (invokers\n// are Baseline newly available, not widely) Gyral dispatches an equivalent `command` event when\n// a custom-command (`--…`) invoker inside a component is clicked, so the same markup works.\n// Built-in commands (`show-modal`, `toggle-popover`, …) are left to the browser.\n\nexport interface CommandInfo {\n  /** The command, e.g. `--clear`. */\n  readonly command: string;\n  /** The invoker (the button) that sent it. */\n  readonly source: Element | undefined;\n}\n\n/** Native invoker commands available? */\nexport const invokersSupported = (): boolean => 'CommandEvent' in globalThis;\n\n/** The command carried by a native `CommandEvent` or by Gyral's fallback event. */\nexport function commandOf(event: Event): CommandInfo | undefined {\n  if (event.type !== 'command') return undefined;\n  if (event instanceof CustomEvent) {\n    const detail = event.detail as Partial<CommandInfo> | null;\n    return typeof detail?.command === 'string'\n      ? { command: detail.command, source: detail.source }\n      : undefined;\n  }\n  const native = event as Event & { command?: unknown; source?: unknown };\n  return typeof native.command === 'string'\n    ? {\n        command: native.command,\n        source: native.source instanceof Element ? native.source : undefined,\n      }\n    : undefined;\n}\n\n/** The custom-command invoker an event passed through, if any. */\nfunction invokerIn(event: Event): Element | undefined {\n  for (const node of event.composedPath()) {\n    if (\n      node instanceof Element &&\n      node.getAttribute('command')?.startsWith('--') === true &&\n      node.hasAttribute('commandfor')\n    ) {\n      return node;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Fallback for browsers without invoker commands: a click on a `command=\"--…\"` invoker inside\n * `root` dispatches a `command` CustomEvent on its `commandfor` target (same tree scope).\n */\nexport function shimInvokers(root: Node): void {\n  root.addEventListener('click', (event) => {\n    if (invokersSupported()) return;\n    const invoker = invokerIn(event);\n    const id = invoker?.getAttribute('commandfor');\n    const command = invoker?.getAttribute('command');\n    if (invoker === undefined || id == null || command == null) return;\n    const scope = invoker.getRootNode() as Document | ShadowRoot;\n    const target = scope.getElementById(id);\n    if (target === null) return;\n    target.dispatchEvent(\n      new CustomEvent<CommandInfo>('command', {\n        detail: { command, source: invoker },\n        cancelable: true,\n      }),\n    );\n  });\n}\n"]}

package/dist/islands.d.ts

@@ -0,0 +1,11 @@
+/** When a server-rendered component hydrates. `load` (the default) means right away. */
+export type HydrateStrategy = 'load' | 'idle' | 'visible' | 'interaction';
+/** Server-written strategy for a deferred island; removed when the island is released. */
+export declare const ISLAND_ATTRIBUTE = "data-gyral-hydrate";
+/** Server side: marks the host as an island unless it hydrates on load. */
+export declare function markIsland(host: Element, strategy: HydrateStrategy | undefined): void;
+/**
+ * Client side: if `host` is a deferred island, releases it when its strategy fires. Called on
+ * connect; scheduling happens once per element.
+ */
+export declare function scheduleIsland(host: HTMLElement): void;

package/dist/islands.js

@@ -0,0 +1,63 @@
+// Lazy hydration islands (gyral-4k7.4, ADR 0012 addendum). A server-rendered component may
+// hydrate later than page load: when the browser is idle, when it scrolls into view, or when
+// the user first reaches for it. The server marks it with Lit's `defer-hydration` plus the
+// strategy; the client removes `defer-hydration` when the strategy fires, and Lit's hydrate
+// support hydrates it in place (define() finishes connecting from attributeChangedCallback).
+/** Server-written strategy for a deferred island; removed when the island is released. */
+export const ISLAND_ATTRIBUTE = 'data-gyral-hydrate';
+const DEFER = 'defer-hydration';
+/** Events that mean the user is about to interact: they arrive before the click itself. */
+const INTERACTION_EVENTS = ['pointerover', 'pointerdown', 'focusin', 'touchstart'];
+/** Server side: marks the host as an island unless it hydrates on load. */
+export function markIsland(host, strategy) {
+    if (strategy === undefined || strategy === 'load')
+        return;
+    host.setAttribute(DEFER, '');
+    host.setAttribute(ISLAND_ATTRIBUTE, strategy);
+}
+const scheduled = new WeakSet();
+/** requestIdleCallback is not Baseline widely available; fall back to a short timeout. */
+function whenIdle(run) {
+    const idle = globalThis.requestIdleCallback;
+    if (idle === undefined)
+        setTimeout(run, 200);
+    else
+        idle(run, { timeout: 2000 });
+}
+/**
+ * Client side: if `host` is a deferred island, releases it when its strategy fires. Called on
+ * connect; scheduling happens once per element.
+ */
+export function scheduleIsland(host) {
+    const strategy = host.getAttribute(ISLAND_ATTRIBUTE);
+    if (strategy === null || !host.hasAttribute(DEFER) || scheduled.has(host))
+        return;
+    scheduled.add(host);
+    const release = () => {
+        host.removeAttribute(ISLAND_ATTRIBUTE);
+        host.removeAttribute(DEFER); // Lit's hydrate support hydrates it now
+    };
+    if (strategy === 'idle') {
+        whenIdle(release);
+    }
+    else if (strategy === 'visible') {
+        const observer = new IntersectionObserver((entries) => {
+            if (entries.some((entry) => entry.isIntersecting)) {
+                observer.disconnect();
+                release();
+            }
+        });
+        observer.observe(host);
+    }
+    else {
+        const controller = new AbortController();
+        const once = () => {
+            controller.abort();
+            release();
+        };
+        for (const type of INTERACTION_EVENTS) {
+            host.addEventListener(type, once, { capture: true, signal: controller.signal });
+        }
+    }
+}
+//# sourceMappingURL=islands.js.map

package/dist/islands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"islands.js","sourceRoot":"","sources":["../src/islands.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,6FAA6F;AAC7F,2FAA2F;AAC3F,4FAA4F;AAC5F,6FAA6F;AAK7F,0FAA0F;AAC1F,MAAM,CAAC,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AACrD,MAAM,KAAK,GAAG,iBAAiB,CAAC;AAEhC,2FAA2F;AAC3F,MAAM,kBAAkB,GAAG,CAAC,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,CAAU,CAAC;AAE5F,2EAA2E;AAC3E,MAAM,UAAU,UAAU,CAAC,IAAa,EAAE,QAAqC;IAC7E,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO;IAC1D,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7B,IAAI,CAAC,YAAY,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,SAAS,GAAG,IAAI,OAAO,EAAW,CAAC;AAIzC,0FAA0F;AAC1F,SAAS,QAAQ,CAAC,GAAe;IAC/B,MAAM,IAAI,GAAI,UAAqD,CAAC,mBAAmB,CAAC;IACxF,IAAI,IAAI,KAAK,SAAS;QAAE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;;QACxC,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC;IACrD,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO;IAClF,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpB,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,IAAI,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC;QACvC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,wCAAwC;IACvE,CAAC,CAAC;IACF,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,QAAQ,CAAC,OAAO,CAAC,CAAC;IACpB,CAAC;SAAM,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CAAC,CAAC,OAAO,EAAE,EAAE;YACpD,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC;gBAClD,QAAQ,CAAC,UAAU,EAAE,CAAC;gBACtB,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;SAAM,CAAC;QACN,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,GAAS,EAAE;YACtB,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,kBAAkB,EAAE,CAAC;YACtC,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["// Lazy hydration islands (gyral-4k7.4, ADR 0012 addendum). A server-rendered component may\n// hydrate later than page load: when the browser is idle, when it scrolls into view, or when\n// the user first reaches for it. The server marks it with Lit's `defer-hydration` plus the\n// strategy; the client removes `defer-hydration` when the strategy fires, and Lit's hydrate\n// support hydrates it in place (define() finishes connecting from attributeChangedCallback).\n\n/** When a server-rendered component hydrates. `load` (the default) means right away. */\nexport type HydrateStrategy = 'load' | 'idle' | 'visible' | 'interaction';\n\n/** Server-written strategy for a deferred island; removed when the island is released. */\nexport const ISLAND_ATTRIBUTE = 'data-gyral-hydrate';\nconst DEFER = 'defer-hydration';\n\n/** Events that mean the user is about to interact: they arrive before the click itself. */\nconst INTERACTION_EVENTS = ['pointerover', 'pointerdown', 'focusin', 'touchstart'] as const;\n\n/** Server side: marks the host as an island unless it hydrates on load. */\nexport function markIsland(host: Element, strategy: HydrateStrategy | undefined): void {\n  if (strategy === undefined || strategy === 'load') return;\n  host.setAttribute(DEFER, '');\n  host.setAttribute(ISLAND_ATTRIBUTE, strategy);\n}\n\nconst scheduled = new WeakSet<Element>();\n\ntype IdleCallback = (callback: () => void, options?: { timeout: number }) => number;\n\n/** requestIdleCallback is not Baseline widely available; fall back to a short timeout. */\nfunction whenIdle(run: () => void): void {\n  const idle = (globalThis as { requestIdleCallback?: IdleCallback }).requestIdleCallback;\n  if (idle === undefined) setTimeout(run, 200);\n  else idle(run, { timeout: 2000 });\n}\n\n/**\n * Client side: if `host` is a deferred island, releases it when its strategy fires. Called on\n * connect; scheduling happens once per element.\n */\nexport function scheduleIsland(host: HTMLElement): void {\n  const strategy = host.getAttribute(ISLAND_ATTRIBUTE);\n  if (strategy === null || !host.hasAttribute(DEFER) || scheduled.has(host)) return;\n  scheduled.add(host);\n  const release = (): void => {\n    host.removeAttribute(ISLAND_ATTRIBUTE);\n    host.removeAttribute(DEFER); // Lit's hydrate support hydrates it now\n  };\n  if (strategy === 'idle') {\n    whenIdle(release);\n  } else if (strategy === 'visible') {\n    const observer = new IntersectionObserver((entries) => {\n      if (entries.some((entry) => entry.isIntersecting)) {\n        observer.disconnect();\n        release();\n      }\n    });\n    observer.observe(host);\n  } else {\n    const controller = new AbortController();\n    const once = (): void => {\n      controller.abort();\n      release();\n    };\n    for (const type of INTERACTION_EVENTS) {\n      host.addEventListener(type, once, { capture: true, signal: controller.signal });\n    }\n  }\n}\n"]}

package/dist/json-safety.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The first place where `value` would change across a JSON round trip, as `path: reason`, or
+ * `undefined` when it is JSON-safe. `undefined` object properties are allowed (they vanish, and
+ * reading them still gives `undefined`).
+ */
+export declare function jsonHazard(value: unknown, path: string, seen?: Set<object>): string | undefined;
+/** Warns (server side) when a seed would hydrate differently from what was rendered. */
+export declare function warnJsonHazard(owner: string, value: unknown, path: string): void;

package/dist/json-safety.js

@@ -0,0 +1,68 @@
+// Seeds are JSON (ADR 0012). A value that doesn't survive JSON.stringify → JSON.parse unchanged
+// makes the client hydrate from different state than the server rendered (gyral-4k7.5).
+const plain = (value) => {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+/**
+ * The first place where `value` would change across a JSON round trip, as `path: reason`, or
+ * `undefined` when it is JSON-safe. `undefined` object properties are allowed (they vanish, and
+ * reading them still gives `undefined`).
+ */
+export function jsonHazard(value, path, seen = new Set()) {
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return undefined;
+        case 'number':
+            return Number.isFinite(value) ? undefined : `${path} is ${String(value)} (becomes null)`;
+        case 'undefined':
+            return `${path} is undefined (dropped, or null in an array)`;
+        case 'function':
+        case 'symbol':
+            return `${path} is a ${typeof value} (dropped)`;
+        case 'bigint':
+            return `${path} is a bigint (JSON can't encode it)`;
+        case 'object':
+            break;
+    }
+    if (value === null)
+        return undefined;
+    if (seen.has(value))
+        return `${path} is a circular reference`;
+    if (value instanceof Date)
+        return `${path} is a Date (becomes a string)`;
+    if (Array.isArray(value)) {
+        seen.add(value);
+        for (const [index, item] of value.entries()) {
+            const found = jsonHazard(item, `${path}[${String(index)}]`, seen);
+            if (found !== undefined)
+                return found;
+        }
+        seen.delete(value);
+        return undefined;
+    }
+    if (!plain(value)) {
+        const name = value.constructor?.name ?? 'object';
+        return `${path} is a ${name} (becomes a plain object)`;
+    }
+    seen.add(value);
+    for (const [key, item] of Object.entries(value)) {
+        if (item === undefined)
+            continue;
+        const found = jsonHazard(item, `${path}.${key}`, seen);
+        if (found !== undefined)
+            return found;
+    }
+    seen.delete(value);
+    return undefined;
+}
+/** Warns (server side) when a seed would hydrate differently from what was rendered. */
+export function warnJsonHazard(owner, value, path) {
+    const found = jsonHazard(value, path);
+    if (found !== undefined) {
+        console.warn(`${owner}: ${found}, so the client would hydrate from different data than the ` +
+            'server rendered. Keep seeded state and props JSON-safe (ADR 0012).');
+    }
+}
+//# sourceMappingURL=json-safety.js.map

package/dist/json-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-safety.js","sourceRoot":"","sources":["../src/json-safety.ts"],"names":[],"mappings":"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","sourcesContent":["// Seeds are JSON (ADR 0012). A value that doesn't survive JSON.stringify → JSON.parse unchanged\n// makes the client hydrate from different state than the server rendered (gyral-4k7.5).\n\nconst plain = (value: object): boolean => {\n  const proto: unknown = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n};\n\n/**\n * The first place where `value` would change across a JSON round trip, as `path: reason`, or\n * `undefined` when it is JSON-safe. `undefined` object properties are allowed (they vanish, and\n * reading them still gives `undefined`).\n */\nexport function jsonHazard(\n  value: unknown,\n  path: string,\n  seen = new Set<object>(),\n): string | undefined {\n  switch (typeof value) {\n    case 'string':\n    case 'boolean':\n      return undefined;\n    case 'number':\n      return Number.isFinite(value) ? undefined : `${path} is ${String(value)} (becomes null)`;\n    case 'undefined':\n      return `${path} is undefined (dropped, or null in an array)`;\n    case 'function':\n    case 'symbol':\n      return `${path} is a ${typeof value} (dropped)`;\n    case 'bigint':\n      return `${path} is a bigint (JSON can't encode it)`;\n    case 'object':\n      break;\n  }\n  if (value === null) return undefined;\n  if (seen.has(value)) return `${path} is a circular reference`;\n  if (value instanceof Date) return `${path} is a Date (becomes a string)`;\n  if (Array.isArray(value)) {\n    seen.add(value);\n    for (const [index, item] of value.entries()) {\n      const found = jsonHazard(item, `${path}[${String(index)}]`, seen);\n      if (found !== undefined) return found;\n    }\n    seen.delete(value);\n    return undefined;\n  }\n  if (!plain(value)) {\n    const name = (value.constructor as { name?: string } | undefined)?.name ?? 'object';\n    return `${path} is a ${name} (becomes a plain object)`;\n  }\n  seen.add(value);\n  for (const [key, item] of Object.entries(value)) {\n    if (item === undefined) continue;\n    const found = jsonHazard(item, `${path}.${key}`, seen);\n    if (found !== undefined) return found;\n  }\n  seen.delete(value);\n  return undefined;\n}\n\n/** Warns (server side) when a seed would hydrate differently from what was rendered. */\nexport function warnJsonHazard(owner: string, value: unknown, path: string): void {\n  const found = jsonHazard(value, path);\n  if (found !== undefined) {\n    console.warn(\n      `${owner}: ${found}, so the client would hydrate from different data than the ` +\n        'server rendered. Keep seeded state and props JSON-safe (ADR 0012).',\n    );\n  }\n}\n"]}

package/dist/light-dom.d.ts

@@ -0,0 +1,61 @@
+import { type CSSResultGroup, type CSSResultOrNative } from 'lit';
+import { type Styles } from './styles.js';
+interface SpecLike {
+    readonly shadow?: boolean;
+    readonly styles?: Styles;
+}
+export declare const isLight: (spec: SpecLike) => boolean;
+/** Shadow components keep their styles; light ones use the document's (and warn if given). */
+export declare function componentStyles(spec: SpecLike, tag: string): CSSResultGroup;
+/**
+ * Is this class a light-DOM Gyral component? Used by @gyral/ssr to render its view as plain
+ * children instead of Declarative Shadow DOM.
+ */
+export declare function isLightComponent(ctor: unknown): boolean;
+/**
+ * Server-rendered light hosts carry this attribute (ADR 0014 addendum). Hydration uses it to
+ * tell a host's own markers from those of light hosts nested inside it.
+ */
+export declare const LIGHT_ATTRIBUTE = "data-gyral-light";
+/** Prefix @gyral/ssr puts on Lit's markers inside light views so no hydrate() walk sees them. */
+export declare const HIDDEN_MARKER = "gyral:";
+/** Server side: marks a light host so the client can scope its markers. */
+export declare function markLightHost(host: Element): void;
+/**
+ * Client side, on a server-rendered light host's first update: turns the host's own hidden
+ * markers back into Lit's, leaving nested light hosts' markers hidden until they hydrate.
+ * Returns whether the host's root part marker was found (so Lit can hydrate in place).
+ */
+export declare function revealLightMarkers(host: Element): boolean;
+/** Lit's public `hydrate()` from `@lit-labs/ssr-client`. */
+export type Hydrate = (value: unknown, container: HTMLElement | DocumentFragment, options?: object) => void;
+/**
+ * Where `@gyral/ssr/hydrate` registers Lit's public `hydrate()` (gyral-czi.38). A global
+ * symbol, not an import, so core doesn't depend on `@lit-labs/ssr-client` and apps without
+ * SSR don't ship it.
+ */
+export declare const HYDRATE_KEY: unique symbol;
+/**
+ * Lit's `hydrate()`, if a server-rendered app loaded `@gyral/ssr/hydrate`. Used for light hosts
+ * and, since gyral-czi.41, for server-rendered shadow roots too: Gyral hydrates both itself, so
+ * it never depends on Lit's hydrate support having patched LitElement before Lit evaluated.
+ */
+export declare const hydrator: () => Hydrate | undefined;
+/**
+ * First update of a server-rendered (declarative) shadow root: hydrate the server's view in
+ * place with Lit's public hydrate(), which leaves the root part on the shadow root so the
+ * render() inside LitElement's update() updates it instead of appending a second copy
+ * (gyral-czi.41). Without `@gyral/ssr/hydrate` loaded, clear the server's view and let Lit
+ * render fresh, adopting the styles Lit's own createRenderRoot would have.
+ */
+export declare function hydrateShadow(root: ShadowRoot, view: unknown, options: object, styles: CSSResultOrNative[]): void;
+/**
+ * First update of a server-rendered light host: reveal this host's own hidden markers now (not
+ * on connect: a deferred child connects mid-way through its parent's hydrate walk), then call
+ * Lit's public hydrate(). It leaves the root part on the host, so the render() inside
+ * LitElement's update() updates it in place instead of appending a second copy. No Lit private
+ * fields: their names are mangled in Lit's production build (ADR 0014, gyral-czi.38). Without
+ * `@gyral/ssr/hydrate` loaded, clear the server's view and let Lit render fresh.
+ */
+export declare function hydrateLight(host: HTMLElement, view: unknown, options: object): void;
+export {};

package/dist/light-dom.js

@@ -0,0 +1,109 @@
+// Light-DOM render mode (docs/design-docs/0014-light-dom.md).
+import { adoptStyles } from 'lit';
+import { toCssResultGroup } from './styles.js';
+export const isLight = (spec) => spec.shadow === false;
+/** Shadow components keep their styles; light ones use the document's (and warn if given). */
+export function componentStyles(spec, tag) {
+    if (!isLight(spec))
+        return spec.styles === undefined ? [] : toCssResultGroup(spec.styles);
+    if (spec.styles !== undefined) {
+        console.warn(`<${tag}> has shadow: false, so its styles are ignored; use document CSS.`);
+    }
+    return [];
+}
+/**
+ * Is this class a light-DOM Gyral component? Used by @gyral/ssr to render its view as plain
+ * children instead of Declarative Shadow DOM.
+ */
+export function isLightComponent(ctor) {
+    const spec = ctor?.spec;
+    return spec !== undefined && isLight(spec);
+}
+/**
+ * Server-rendered light hosts carry this attribute (ADR 0014 addendum). Hydration uses it to
+ * tell a host's own markers from those of light hosts nested inside it.
+ */
+export const LIGHT_ATTRIBUTE = 'data-gyral-light';
+/** Prefix @gyral/ssr puts on Lit's markers inside light views so no hydrate() walk sees them. */
+export const HIDDEN_MARKER = 'gyral:';
+const LIT_MARKER = /^(?:lit-part|\/lit-part|lit-node)\b/;
+/** Server side: marks a light host so the client can scope its markers. */
+export function markLightHost(host) {
+    host.setAttribute(LIGHT_ATTRIBUTE, '');
+}
+/** Is the comment inside `host`'s own light view, not a nested light host's? */
+function ownedBy(comment, host) {
+    for (let el = comment.parentElement; el !== null; el = el.parentElement) {
+        if (el === host)
+            return true;
+        if (el.hasAttribute(LIGHT_ATTRIBUTE))
+            return false;
+    }
+    return false;
+}
+/**
+ * Client side, on a server-rendered light host's first update: turns the host's own hidden
+ * markers back into Lit's, leaving nested light hosts' markers hidden until they hydrate.
+ * Returns whether the host's root part marker was found (so Lit can hydrate in place).
+ */
+export function revealLightMarkers(host) {
+    const walker = document.createTreeWalker(host, NodeFilter.SHOW_COMMENT);
+    const own = [];
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+        const comment = node;
+        const data = comment.data.slice(HIDDEN_MARKER.length);
+        if (comment.data.startsWith(HIDDEN_MARKER) && LIT_MARKER.test(data) && ownedBy(comment, host)) {
+            own.push(comment);
+        }
+    }
+    for (const comment of own)
+        comment.data = comment.data.slice(HIDDEN_MARKER.length);
+    return own[0]?.data.startsWith('lit-part') === true;
+}
+/**
+ * Where `@gyral/ssr/hydrate` registers Lit's public `hydrate()` (gyral-czi.38). A global
+ * symbol, not an import, so core doesn't depend on `@lit-labs/ssr-client` and apps without
+ * SSR don't ship it.
+ */
+export const HYDRATE_KEY = Symbol.for('gyral.hydrate');
+/**
+ * Lit's `hydrate()`, if a server-rendered app loaded `@gyral/ssr/hydrate`. Used for light hosts
+ * and, since gyral-czi.41, for server-rendered shadow roots too: Gyral hydrates both itself, so
+ * it never depends on Lit's hydrate support having patched LitElement before Lit evaluated.
+ */
+export const hydrator = () => {
+    const fn = globalThis[HYDRATE_KEY];
+    return typeof fn === 'function' ? fn : undefined;
+};
+/**
+ * First update of a server-rendered (declarative) shadow root: hydrate the server's view in
+ * place with Lit's public hydrate(), which leaves the root part on the shadow root so the
+ * render() inside LitElement's update() updates it instead of appending a second copy
+ * (gyral-czi.41). Without `@gyral/ssr/hydrate` loaded, clear the server's view and let Lit
+ * render fresh, adopting the styles Lit's own createRenderRoot would have.
+ */
+export function hydrateShadow(root, view, options, styles) {
+    const hydrate = hydrator();
+    if (hydrate !== undefined) {
+        hydrate(view, root, options);
+        return;
+    }
+    root.replaceChildren();
+    adoptStyles(root, styles);
+}
+/**
+ * First update of a server-rendered light host: reveal this host's own hidden markers now (not
+ * on connect: a deferred child connects mid-way through its parent's hydrate walk), then call
+ * Lit's public hydrate(). It leaves the root part on the host, so the render() inside
+ * LitElement's update() updates it in place instead of appending a second copy. No Lit private
+ * fields: their names are mangled in Lit's production build (ADR 0014, gyral-czi.38). Without
+ * `@gyral/ssr/hydrate` loaded, clear the server's view and let Lit render fresh.
+ */
+export function hydrateLight(host, view, options) {
+    const hydrate = hydrator();
+    if (hydrate !== undefined && revealLightMarkers(host))
+        hydrate(view, host, options);
+    else
+        host.replaceChildren();
+}
+//# sourceMappingURL=light-dom.js.map

package/dist/light-dom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"light-dom.js","sourceRoot":"","sources":["../src/light-dom.ts"],"names":[],"mappings":"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","sourcesContent":["// Light-DOM render mode (docs/design-docs/0014-light-dom.md).\nimport { adoptStyles, type CSSResultGroup, type CSSResultOrNative } from 'lit';\nimport { toCssResultGroup, type Styles } from './styles.js';\n\ninterface SpecLike {\n  readonly shadow?: boolean;\n  readonly styles?: Styles;\n}\n\nexport const isLight = (spec: SpecLike): boolean => spec.shadow === false;\n\n/** Shadow components keep their styles; light ones use the document's (and warn if given). */\nexport function componentStyles(spec: SpecLike, tag: string): CSSResultGroup {\n  if (!isLight(spec)) return spec.styles === undefined ? [] : toCssResultGroup(spec.styles);\n  if (spec.styles !== undefined) {\n    console.warn(`<${tag}> has shadow: false, so its styles are ignored; use document CSS.`);\n  }\n  return [];\n}\n\n/**\n * Is this class a light-DOM Gyral component? Used by @gyral/ssr to render its view as plain\n * children instead of Declarative Shadow DOM.\n */\nexport function isLightComponent(ctor: unknown): boolean {\n  const spec = (ctor as { readonly spec?: SpecLike } | null)?.spec;\n  return spec !== undefined && isLight(spec);\n}\n\n/**\n * Server-rendered light hosts carry this attribute (ADR 0014 addendum). Hydration uses it to\n * tell a host's own markers from those of light hosts nested inside it.\n */\nexport const LIGHT_ATTRIBUTE = 'data-gyral-light';\n\n/** Prefix @gyral/ssr puts on Lit's markers inside light views so no hydrate() walk sees them. */\nexport const HIDDEN_MARKER = 'gyral:';\n\nconst LIT_MARKER = /^(?:lit-part|\\/lit-part|lit-node)\\b/;\n\n/** Server side: marks a light host so the client can scope its markers. */\nexport function markLightHost(host: Element): void {\n  host.setAttribute(LIGHT_ATTRIBUTE, '');\n}\n\n/** Is the comment inside `host`'s own light view, not a nested light host's? */\nfunction ownedBy(comment: Comment, host: Element): boolean {\n  for (let el = comment.parentElement; el !== null; el = el.parentElement) {\n    if (el === host) return true;\n    if (el.hasAttribute(LIGHT_ATTRIBUTE)) return false;\n  }\n  return false;\n}\n\n/**\n * Client side, on a server-rendered light host's first update: turns the host's own hidden\n * markers back into Lit's, leaving nested light hosts' markers hidden until they hydrate.\n * Returns whether the host's root part marker was found (so Lit can hydrate in place).\n */\nexport function revealLightMarkers(host: Element): boolean {\n  const walker = document.createTreeWalker(host, NodeFilter.SHOW_COMMENT);\n  const own: Comment[] = [];\n  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {\n    const comment = node as Comment;\n    const data = comment.data.slice(HIDDEN_MARKER.length);\n    if (comment.data.startsWith(HIDDEN_MARKER) && LIT_MARKER.test(data) && ownedBy(comment, host)) {\n      own.push(comment);\n    }\n  }\n  for (const comment of own) comment.data = comment.data.slice(HIDDEN_MARKER.length);\n  return own[0]?.data.startsWith('lit-part') === true;\n}\n\n/** Lit's public `hydrate()` from `@lit-labs/ssr-client`. */\nexport type Hydrate = (\n  value: unknown,\n  container: HTMLElement | DocumentFragment,\n  options?: object,\n) => void;\n\n/**\n * Where `@gyral/ssr/hydrate` registers Lit's public `hydrate()` (gyral-czi.38). A global\n * symbol, not an import, so core doesn't depend on `@lit-labs/ssr-client` and apps without\n * SSR don't ship it.\n */\nexport const HYDRATE_KEY: unique symbol = Symbol.for('gyral.hydrate') as never;\n\n/**\n * Lit's `hydrate()`, if a server-rendered app loaded `@gyral/ssr/hydrate`. Used for light hosts\n * and, since gyral-czi.41, for server-rendered shadow roots too: Gyral hydrates both itself, so\n * it never depends on Lit's hydrate support having patched LitElement before Lit evaluated.\n */\nexport const hydrator = (): Hydrate | undefined => {\n  const fn = (globalThis as { [HYDRATE_KEY]?: unknown })[HYDRATE_KEY];\n  return typeof fn === 'function' ? (fn as Hydrate) : undefined;\n};\n\n/**\n * First update of a server-rendered (declarative) shadow root: hydrate the server's view in\n * place with Lit's public hydrate(), which leaves the root part on the shadow root so the\n * render() inside LitElement's update() updates it instead of appending a second copy\n * (gyral-czi.41). Without `@gyral/ssr/hydrate` loaded, clear the server's view and let Lit\n * render fresh, adopting the styles Lit's own createRenderRoot would have.\n */\nexport function hydrateShadow(\n  root: ShadowRoot,\n  view: unknown,\n  options: object,\n  styles: CSSResultOrNative[],\n): void {\n  const hydrate = hydrator();\n  if (hydrate !== undefined) {\n    hydrate(view, root, options);\n    return;\n  }\n  root.replaceChildren();\n  adoptStyles(root, styles);\n}\n\n/**\n * First update of a server-rendered light host: reveal this host's own hidden markers now (not\n * on connect: a deferred child connects mid-way through its parent's hydrate walk), then call\n * Lit's public hydrate(). It leaves the root part on the host, so the render() inside\n * LitElement's update() updates it in place instead of appending a second copy. No Lit private\n * fields: their names are mangled in Lit's production build (ADR 0014, gyral-czi.38). Without\n * `@gyral/ssr/hydrate` loaded, clear the server's view and let Lit render fresh.\n */\nexport function hydrateLight(host: HTMLElement, view: unknown, options: object): void {\n  const hydrate = hydrator();\n  if (hydrate !== undefined && revealLightMarkers(host)) hydrate(view, host, options);\n  else host.replaceChildren();\n}\n"]}

package/dist/live-boolean.d.ts

@@ -0,0 +1,22 @@
+import { Directive, type AttributePart, type PartInfo } from 'lit/directive.js';
+/**
+ * A boolean that is right both in server-rendered markup and in the live DOM (ADR 0012).
+ * Use it in a boolean attribute binding:
+ *
+ *   <input type="checkbox" ?checked=${liveBoolean(s.on)} />
+ *   <option ?selected=${liveBoolean(s.sort === 'price')}>Price</option>
+ *
+ * - On the server it renders the attribute when true and omits it when false.
+ *   (A property binding, `.checked=${false}`, is serialized by Lit SSR as `checked="false"`,
+ *   which *checks* the box. Never bind boolean form state as a property in SSR'd views.)
+ * - In the browser it also sets the element's property of the same name (`checked`,
+ *   `selected`, `open`, …), so the control follows model state even after the user has
+ *   changed it. The attribute alone stops controlling `checked` once a box has been clicked.
+ */
+declare class LiveBoolean extends Directive {
+    constructor(info: PartInfo);
+    render(value: boolean): boolean;
+    update(part: AttributePart, [value]: [boolean]): boolean;
+}
+export declare const liveBoolean: (value: boolean) => import("lit/directive.js").DirectiveResult<typeof LiveBoolean>;
+export {};

package/dist/live-boolean.js

@@ -0,0 +1,34 @@
+import { Directive, directive, PartType, } from 'lit/directive.js';
+/**
+ * A boolean that is right both in server-rendered markup and in the live DOM (ADR 0012).
+ * Use it in a boolean attribute binding:
+ *
+ *   <input type="checkbox" ?checked=${liveBoolean(s.on)} />
+ *   <option ?selected=${liveBoolean(s.sort === 'price')}>Price</option>
+ *
+ * - On the server it renders the attribute when true and omits it when false.
+ *   (A property binding, `.checked=${false}`, is serialized by Lit SSR as `checked="false"`,
+ *   which *checks* the box. Never bind boolean form state as a property in SSR'd views.)
+ * - In the browser it also sets the element's property of the same name (`checked`,
+ *   `selected`, `open`, …), so the control follows model state even after the user has
+ *   changed it. The attribute alone stops controlling `checked` once a box has been clicked.
+ */
+class LiveBoolean extends Directive {
+    constructor(info) {
+        super(info);
+        if (info.type !== PartType.BOOLEAN_ATTRIBUTE) {
+            throw new Error('liveBoolean() must be used in a boolean attribute: ?checked=${…}');
+        }
+    }
+    render(value) {
+        return value;
+    }
+    update(part, [value]) {
+        const element = part.element;
+        if (part.name in part.element && element[part.name] !== value)
+            element[part.name] = value;
+        return value;
+    }
+}
+export const liveBoolean = directive(LiveBoolean);
+//# sourceMappingURL=live-boolean.js.map

package/dist/live-boolean.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-boolean.js","sourceRoot":"","sources":["../src/live-boolean.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,SAAS,EACT,QAAQ,GAGT,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAY,SAAQ,SAAS;IACjC,YAAY,IAAc;QACxB,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,iBAAiB,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IAEQ,MAAM,CAAC,KAAc;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IAEQ,MAAM,CAAC,IAAmB,EAAE,CAAC,KAAK,CAAY;QACrD,MAAM,OAAO,GAAG,IAAI,CAAC,OAA6C,CAAC;QACnE,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAC1F,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC","sourcesContent":["import {\n  Directive,\n  directive,\n  PartType,\n  type AttributePart,\n  type PartInfo,\n} from 'lit/directive.js';\n\n/**\n * A boolean that is right both in server-rendered markup and in the live DOM (ADR 0012).\n * Use it in a boolean attribute binding:\n *\n *   <input type=\"checkbox\" ?checked=${liveBoolean(s.on)} />\n *   <option ?selected=${liveBoolean(s.sort === 'price')}>Price</option>\n *\n * - On the server it renders the attribute when true and omits it when false.\n *   (A property binding, `.checked=${false}`, is serialized by Lit SSR as `checked=\"false\"`,\n *   which *checks* the box. Never bind boolean form state as a property in SSR'd views.)\n * - In the browser it also sets the element's property of the same name (`checked`,\n *   `selected`, `open`, …), so the control follows model state even after the user has\n *   changed it. The attribute alone stops controlling `checked` once a box has been clicked.\n */\nclass LiveBoolean extends Directive {\n  constructor(info: PartInfo) {\n    super(info);\n    if (info.type !== PartType.BOOLEAN_ATTRIBUTE) {\n      throw new Error('liveBoolean() must be used in a boolean attribute: ?checked=${…}');\n    }\n  }\n\n  override render(value: boolean): boolean {\n    return value;\n  }\n\n  override update(part: AttributePart, [value]: [boolean]): boolean {\n    const element = part.element as unknown as Record<string, unknown>;\n    if (part.name in part.element && element[part.name] !== value) element[part.name] = value;\n    return value;\n  }\n}\n\nexport const liveBoolean = directive(LiveBoolean);\n"]}

package/dist/props.d.ts

@@ -0,0 +1,26 @@
+import type { PropertyDeclaration } from 'lit';
+type Bag = Readonly<Record<string, unknown>>;
+/** Gyral's view of a declaration: Lit's options plus `required` and `default`. */
+export interface PropInfo extends PropertyDeclaration {
+    readonly required?: boolean;
+    readonly default?: unknown;
+}
+export type PropTable = Readonly<Record<string, PropInfo>>;
+/** The element's declared props as set on it (no defaults): what a seed must carry. */
+export declare function readRawProps(el: object, table: PropTable): Bag;
+/** The element's declared props as components see them: `default` fills `undefined`. */
+export declare function readProps(el: object, table: PropTable): Bag;
+/** Required props that are still `undefined` (ADR 0007 addendum). */
+export declare function missingRequired(el: object, table: PropTable): string[];
+/** True when every declared prop is identical (`Object.is`) in both snapshots. */
+export declare function sameProps<P>(names: readonly string[], a: P, b: P): boolean;
+/** Hydration: sets props that only travelled in the seed, unless the page already set them. */
+export declare function restoreProps(el: object, names: readonly string[], seeded: Bag): void;
+/**
+ * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …).
+ * Lit's reactive accessor replaces the built-in, so setting the prop silently changes what the
+ * platform does with it: a prop named `hidden` hides the element (gyral-czi.33). Browser only:
+ * the server's DOM shim doesn't model the full prototype chain.
+ */
+export declare function shadowedBuiltins(names: readonly string[]): string[];
+export {};

package/dist/props.js

@@ -0,0 +1,44 @@
+/** The element's declared props as set on it (no defaults): what a seed must carry. */
+export function readRawProps(el, table) {
+    const self = el;
+    return Object.fromEntries(Object.keys(table).map((name) => [name, self[name]]));
+}
+/** The element's declared props as components see them: `default` fills `undefined`. */
+export function readProps(el, table) {
+    const self = el;
+    return Object.fromEntries(Object.entries(table).map(([name, info]) => {
+        const value = self[name];
+        return [name, value === undefined && 'default' in info ? info.default : value];
+    }));
+}
+/** Required props that are still `undefined` (ADR 0007 addendum). */
+export function missingRequired(el, table) {
+    const self = el;
+    return Object.entries(table)
+        .filter(([name, info]) => info.required === true && self[name] === undefined)
+        .map(([name]) => name);
+}
+/** True when every declared prop is identical (`Object.is`) in both snapshots. */
+export function sameProps(names, a, b) {
+    return names.every((name) => Object.is(a[name], b[name]));
+}
+/** Hydration: sets props that only travelled in the seed, unless the page already set them. */
+export function restoreProps(el, names, seeded) {
+    const self = el;
+    for (const [name, value] of Object.entries(seeded)) {
+        if (names.includes(name) && self[name] === undefined)
+            self[name] = value;
+    }
+}
+/**
+ * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …).
+ * Lit's reactive accessor replaces the built-in, so setting the prop silently changes what the
+ * platform does with it: a prop named `hidden` hides the element (gyral-czi.33). Browser only:
+ * the server's DOM shim doesn't model the full prototype chain.
+ */
+export function shadowedBuiltins(names) {
+    if (typeof HTMLElement === 'undefined')
+        return [];
+    return names.filter((name) => name in HTMLElement.prototype);
+}
+//# sourceMappingURL=props.js.map

package/dist/props.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.js","sourceRoot":"","sources":["../src/props.ts"],"names":[],"mappings":"AAaA,uFAAuF;AACvF,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,KAAgB;IACvD,MAAM,IAAI,GAAG,EAAS,CAAC;IACvB,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAClF,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,SAAS,CAAC,EAAU,EAAE,KAAgB;IACpD,MAAM,IAAI,GAAG,EAAS,CAAC;IACvB,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,IAAI,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACjF,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,EAAU,EAAE,KAAgB;IAC1D,MAAM,IAAI,GAAG,EAAS,CAAC;IACvB,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SACzB,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;SAC5E,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,SAAS,CAAI,KAAwB,EAAE,CAAI,EAAE,CAAI;IAC/D,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAE,CAAS,CAAC,IAAI,CAAC,EAAG,CAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,KAAwB,EAAE,MAAW;IAC5E,MAAM,IAAI,GAAG,EAA6B,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAC3E,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAwB;IACvD,IAAI,OAAO,WAAW,KAAK,WAAW;QAAE,OAAO,EAAE,CAAC;IAClD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC;AAC/D,CAAC","sourcesContent":["// Prop bookkeeping for define() (ADR 0007): snapshots, defaults, change detection, seed restore.\nimport type { PropertyDeclaration } from 'lit';\n\ntype Bag = Readonly<Record<string, unknown>>;\n\n/** Gyral's view of a declaration: Lit's options plus `required` and `default`. */\nexport interface PropInfo extends PropertyDeclaration {\n  readonly required?: boolean;\n  readonly default?: unknown;\n}\n\nexport type PropTable = Readonly<Record<string, PropInfo>>;\n\n/** The element's declared props as set on it (no defaults): what a seed must carry. */\nexport function readRawProps(el: object, table: PropTable): Bag {\n  const self = el as Bag;\n  return Object.fromEntries(Object.keys(table).map((name) => [name, self[name]]));\n}\n\n/** The element's declared props as components see them: `default` fills `undefined`. */\nexport function readProps(el: object, table: PropTable): Bag {\n  const self = el as Bag;\n  return Object.fromEntries(\n    Object.entries(table).map(([name, info]) => {\n      const value = self[name];\n      return [name, value === undefined && 'default' in info ? info.default : value];\n    }),\n  );\n}\n\n/** Required props that are still `undefined` (ADR 0007 addendum). */\nexport function missingRequired(el: object, table: PropTable): string[] {\n  const self = el as Bag;\n  return Object.entries(table)\n    .filter(([name, info]) => info.required === true && self[name] === undefined)\n    .map(([name]) => name);\n}\n\n/** True when every declared prop is identical (`Object.is`) in both snapshots. */\nexport function sameProps<P>(names: readonly string[], a: P, b: P): boolean {\n  return names.every((name) => Object.is((a as Bag)[name], (b as Bag)[name]));\n}\n\n/** Hydration: sets props that only travelled in the seed, unless the page already set them. */\nexport function restoreProps(el: object, names: readonly string[], seeded: Bag): void {\n  const self = el as Record<string, unknown>;\n  for (const [name, value] of Object.entries(seeded)) {\n    if (names.includes(name) && self[name] === undefined) self[name] = value;\n  }\n}\n\n/**\n * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …).\n * Lit's reactive accessor replaces the built-in, so setting the prop silently changes what the\n * platform does with it: a prop named `hidden` hides the element (gyral-czi.33). Browser only:\n * the server's DOM shim doesn't model the full prototype chain.\n */\nexport function shadowedBuiltins(names: readonly string[]): string[] {\n  if (typeof HTMLElement === 'undefined') return [];\n  return names.filter((name) => name in HTMLElement.prototype);\n}\n"]}

package/dist/random.d.ts

@@ -0,0 +1,13 @@
+import { type Command, type Driver } from './command.js';
+export interface RandomInput {
+    /** How many numbers to draw. */
+    readonly count: number;
+}
+/** Uniform numbers in [0, 1). Substitute it in tests: `el.drivers = { random: fake }`. */
+export declare const randomDriver: Driver<RandomInput, readonly number[]>;
+/** Draws `count` uniform numbers in [0, 1) and turns them into a message. */
+export declare function random<M>(count: number, toMsg: (values: readonly number[]) => M | undefined): Command<M>;
+/** Maps a uniform number in [0, 1) to an integer in `min..max` (inclusive). Pure. */
+export declare const toInt: (u: number, min: number, max: number) => number;
+/** Draws one integer in `min..max` (inclusive). */
+export declare function randomInt<M>(min: number, max: number, toMsg: (value: number) => M | undefined): Command<M>;

package/dist/random.js

@@ -0,0 +1,19 @@
+// Randomness as an effect (gyral-czi.10): reducers ask for random numbers with a command,
+// so models stay pure and tests substitute a deterministic driver by name.
+import { command, defineDriver } from './command.js';
+/** Uniform numbers in [0, 1). Substitute it in tests: `el.drivers = { random: fake }`. */
+export const randomDriver = defineDriver({
+    name: 'random',
+    run: ({ count }) => Array.from({ length: count }, () => Math.random()),
+});
+/** Draws `count` uniform numbers in [0, 1) and turns them into a message. */
+export function random(count, toMsg) {
+    return command(randomDriver, { count }, { onSuccess: toMsg });
+}
+/** Maps a uniform number in [0, 1) to an integer in `min..max` (inclusive). Pure. */
+export const toInt = (u, min, max) => min + Math.min(max - min, Math.floor(u * (max - min + 1)));
+/** Draws one integer in `min..max` (inclusive). */
+export function randomInt(min, max, toMsg) {
+    return random(1, ([u = 0]) => toMsg(toInt(u, min, max)));
+}
+//# sourceMappingURL=random.js.map