@gyral/core 0.2.0 → 0.3.1

package/dist/invokers.js

@@ -5,60 +5,20 @@
 //
 // 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.
+// a custom-command (`--…`) invoker inside a component is clicked, so the same markup works:
+// invokers-shim.ts, an ADR 0003 tier-3 fallback loaded with import() only there, and only by
+// components listening for `command`. Built-in commands (`show-modal`, …) 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).
+ * The command carried by a `CommandEvent`, or by Gyral's fallback event, which has the same
+ * `command` and `source` properties.
  */
-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,
-        }));
-    });
+export function commandOf(event) {
+    const { type, command, source } = event;
+    return type === 'command' && typeof command === 'string'
+        ? { command, source: source instanceof Element ? source : undefined }
+        : undefined;
 }
 //# sourceMappingURL=invokers.js.map

package/dist/invokers.js.map

@@ -1 +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"]}
+{"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,6FAA6F;AAC7F,0FAA0F;AAC1F,WAAW;AASX,yCAAyC;AACzC,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAY,EAAE,CAAC,cAAc,IAAI,UAAU,CAAC;AAE7E;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAY;IACpC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,KAAwD,CAAC;IAC3F,OAAO,IAAI,KAAK,SAAS,IAAI,OAAO,OAAO,KAAK,QAAQ;QACtD,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAAE;QACrE,CAAC,CAAC,SAAS,CAAC;AAChB,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// invokers-shim.ts, an ADR 0003 tier-3 fallback loaded with import() only there, and only by\n// components listening for `command`. Built-in commands (`show-modal`, …) are left to the\n// 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/**\n * The command carried by a `CommandEvent`, or by Gyral's fallback event, which has the same\n * `command` and `source` properties.\n */\nexport function commandOf(event: Event): CommandInfo | undefined {\n  const { type, command, source } = event as Event & { command?: unknown; source?: unknown };\n  return type === 'command' && typeof command === 'string'\n    ? { command, source: source instanceof Element ? source : undefined }\n    : undefined;\n}\n"]}

package/dist/islands.d.ts

@@ -2,8 +2,6 @@
 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.

package/dist/islands.js

@@ -1,20 +1,13 @@
 // 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).
+// the user first reaches for it. The server marks it with `defer-hydration` plus the strategy
+// (view/06-server.md); the client removes `defer-hydration` when the strategy fires, and
+// define() finishes connecting from attributeChangedCallback (view/07-hydration.md "Islands").
 /** 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) {
@@ -35,7 +28,7 @@ export function scheduleIsland(host) {
     scheduled.add(host);
     const release = () => {
         host.removeAttribute(ISLAND_ATTRIBUTE);
-        host.removeAttribute(DEFER); // Lit's hydrate support hydrates it now
+        host.removeAttribute(DEFER); // attributeChangedCallback connects it now
     };
     if (strategy === 'idle') {
         whenIdle(release);

package/dist/islands.js.map

@@ -1 +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"]}
+{"version":3,"file":"islands.js","sourceRoot":"","sources":["../src/islands.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,6FAA6F;AAC7F,8FAA8F;AAC9F,yFAAyF;AACzF,+FAA+F;AAK/F,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,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,2CAA2C;IAC1E,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 `defer-hydration` plus the strategy\n// (view/06-server.md); the client removes `defer-hydration` when the strategy fires, and\n// define() finishes connecting from attributeChangedCallback (view/07-hydration.md \"Islands\").\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\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); // attributeChangedCallback connects 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/light-dom.d.ts

@@ -1,61 +1,12 @@
-import { type CSSResultGroup, type CSSResultOrNative } from 'lit';
-import { type Styles } from './styles.js';
 interface SpecLike {
-    readonly shadow?: boolean;
-    readonly styles?: Styles;
+    readonly shadow?: unknown;
 }
 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.
- */
+/** Is this class a light-DOM Gyral component (`shadow: false`)? */
 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.
+ * Server-rendered light hosts carry this attribute (ADR 0014 addendum, view/06-server.md
+ * "Components"), so a parent's hydration walk leaves a light child's content alone (view/07).
  */
 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

@@ -1,109 +1,14 @@
-// Light-DOM render mode (docs/design-docs/0014-light-dom.md).
-import { adoptStyles } from 'lit';
-import { toCssResultGroup } from './styles.js';
+// Light-DOM render mode (docs/design-docs/0014-light-dom.md): `shadow: false` renders the view
+// as the host's own children, styled by document CSS.
 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.
- */
+/** Is this class a light-DOM Gyral component (`shadow: false`)? */
 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.
+ * Server-rendered light hosts carry this attribute (ADR 0014 addendum, view/06-server.md
+ * "Components"), so a parent's hydration walk leaves a light child's content alone (view/07).
  */
 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

@@ -1 +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"]}
+{"version":3,"file":"light-dom.js","sourceRoot":"","sources":["../src/light-dom.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,sDAAsD;AAMtD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAc,EAAW,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC;AAE1E,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,MAAM,IAAI,GAAI,IAA4C,EAAE,IAAI,CAAC;IACjE,OAAO,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,kBAAkB,CAAC","sourcesContent":["// Light-DOM render mode (docs/design-docs/0014-light-dom.md): `shadow: false` renders the view\n// as the host's own children, styled by document CSS.\n\ninterface SpecLike {\n  readonly shadow?: unknown;\n}\n\nexport const isLight = (spec: SpecLike): boolean => spec.shadow === false;\n\n/** Is this class a light-DOM Gyral component (`shadow: false`)? */\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, view/06-server.md\n * \"Components\"), so a parent's hydration walk leaves a light child's content alone (view/07).\n */\nexport const LIGHT_ATTRIBUTE = 'data-gyral-light';\n"]}

package/dist/prop.d.ts

@@ -0,0 +1,89 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+declare const OUTPUT: unique symbol;
+export type PropKind = 'string' | 'number' | 'boolean' | 'json' | 'value';
+/** One declared prop: what a builder returns. */
+export interface Prop<T> {
+    readonly kind: PropKind;
+    /** The attribute name, `false` for property only, `undefined` for the kebab-case default. */
+    readonly attribute: string | false | undefined;
+    /**
+     * Refines (string/number/boolean) or defines (json/value) the accepted values: a Standard
+     * Schema, or for json/value a type guard (props.ts `checkValue` tells them apart).
+     */
+    readonly schema: StandardSchemaV1 | PropGuard<unknown> | undefined;
+    /** A missing value is a bug: warned once per instance at first render. */
+    readonly required: boolean;
+    /** Used whenever the element's value is missing (`boolean` props default to `false`). */
+    readonly default?: unknown;
+    /**
+     * When a new value counts as unchanged (no re-render, no `PropsChanged`): `Object.is`, the
+     * same JSON for `prop.json`, or the `equals` option of `prop.json`/`prop.value`.
+     */
+    readonly equals: (a: unknown, b: unknown) => boolean;
+    /** Type-only: the value components see. Never set. */
+    readonly [OUTPUT]?: () => T;
+}
+/** The props type of a table of builders: `PropsOf<typeof props>`. */
+export type PropsOf<T extends Readonly<Record<string, Prop<unknown>>>> = {
+    readonly [K in keyof T]: T[K] extends Prop<infer V> ? V : never;
+};
+interface Common {
+    /** Attribute name, or `false` for property only. Default: kebab-case of the prop name. */
+    readonly attribute?: string | false;
+}
+type Schema<O> = StandardSchemaV1<unknown, O>;
+/** A plain type guard, accepted by `prop.value` and `prop.json` in place of a schema. */
+export type PropGuard<T> = (value: unknown) => value is T;
+/** What `prop.value` and `prop.json` accept: a Standard Schema or a type guard. */
+type Check = StandardSchemaV1 | PropGuard<unknown>;
+type Out<S extends Check> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : S extends (value: unknown) => value is infer T ? T : never;
+interface Required {
+    readonly required: true;
+    readonly default?: undefined;
+}
+interface Defaulted<T> {
+    readonly required?: false;
+    readonly default: T;
+}
+interface Optional {
+    readonly required?: false;
+    readonly default?: undefined;
+}
+type Refined<O> = Common & {
+    readonly schema?: Schema<O>;
+};
+interface Scalar<B> {
+    <O extends B = B>(opts: Refined<O> & (Required | Defaulted<NoInfer<O>>)): Prop<O>;
+    <O extends B = B>(opts?: Refined<O> & Optional): Prop<O | undefined>;
+}
+/** `equals` for `prop.json`/`prop.value`: the old and new value (`undefined` when unset). */
+interface Equals<T> {
+    readonly equals?: (a: T | undefined, b: T | undefined) => boolean;
+}
+interface WithSchema {
+    <S extends Check>(schema: S, opts: Common & Equals<NoInfer<Out<S>>> & (Required | Defaulted<NoInfer<Out<S>>>)): Prop<Out<S>>;
+    <S extends Check>(schema: S, opts?: Common & Equals<NoInfer<Out<S>>> & Optional): Prop<Out<S> | undefined>;
+}
+/** The prop builders. */
+export declare const prop: {
+    /** Attribute parsed as is. */
+    readonly string: Scalar<string>;
+    /** Attribute parsed with `Number(v)`; empty or `NaN` is invalid. */
+    readonly number: Scalar<number>;
+    /** Attribute present → `true`, absent → `false` (the default). */
+    readonly boolean: <O extends boolean = boolean>(opts?: Refined<O> & {
+        readonly default?: NoInfer<O>;
+    }) => Prop<O>;
+    /**
+     * Attribute parsed with `JSON.parse`, then the schema (or type guard). Compared by value: a
+     * new but equal object (a fresh `.prop=${{…}}` each render) changes nothing.
+     */
+    readonly json: WithSchema;
+    /**
+     * Property only: no attribute. Validated in development by the schema (or type guard), and
+     * the object set is kept as is (production skips the check). Compared with `Object.is`
+     * unless `equals` is given.
+     */
+    readonly value: WithSchema;
+};
+export {};

package/dist/prop.js

@@ -0,0 +1,41 @@
+import { features } from './features.js';
+import { propFeature } from './props.js';
+import { DEV } from '#view-dev';
+/** `prop.json` values are JSON: the same JSON text is the same value. */
+// `prop.json`'s default `equals`: the same JSON text. A value JSON can't encode (a cycle, a
+// BigInt) is never equal, so the write always lands instead of throwing from the setter.
+let warned = false;
+function sameJson(a, b) {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch (error) {
+        if (DEV && !warned) {
+            warned = true;
+            console.warn(`prop.json got a value JSON can't encode (${String(error)}); every write of it counts ` +
+                'as a change. Use prop.value for non-JSON values, or pass equals.');
+        }
+        return false;
+    }
+}
+function make(kind, opts = {}, schema) {
+    features.props = propFeature; // components can declare props now (features.ts)
+    const value = opts.default !== undefined ? opts.default : kind === 'boolean' ? false : undefined;
+    const base = {
+        kind,
+        attribute: kind === 'value' ? false : opts.attribute,
+        schema: schema ?? opts.schema,
+        required: opts.required === true,
+        equals: opts.equals ?? (kind === 'json' ? sameJson : Object.is),
+    };
+    return value === undefined ? base : { ...base, default: value };
+}
+/** The prop builders. */
+export const prop = {
+    string: (opts) => make('string', opts),
+    number: (opts) => make('number', opts),
+    boolean: ((opts) => make('boolean', opts)),
+    json: (schema, opts) => make('json', opts, schema),
+    value: (schema, opts) => make('value', opts, schema),
+};
+//# sourceMappingURL=prop.js.map

package/dist/prop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop.js","sourceRoot":"","sources":["../src/prop.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAgGhC,yEAAyE;AACzE,4FAA4F;AAC5F,yFAAyF;AACzF,IAAI,MAAM,GAAG,KAAK,CAAC;AACnB,SAAS,QAAQ,CAAC,CAAU,EAAE,CAAU;IACtC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,GAAG,IAAI,CAAC;YACd,OAAO,CAAC,IAAI,CACV,4CAA4C,MAAM,CAAC,KAAK,CAAC,8BAA8B;gBACrF,kEAAkE,CACrE,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,IAAI,CAAC,IAAc,EAAE,OAAgB,EAAE,EAAE,MAAc;IAC9D,QAAQ,CAAC,KAAK,GAAG,WAAW,CAAC,CAAC,iDAAiD;IAC/E,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACjG,MAAM,IAAI,GAAG;QACX,IAAI;QACJ,SAAS,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS;QACpD,MAAM,EAAE,MAAM,IAAI,IAAI,CAAC,MAAM;QAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ,KAAK,IAAI;QAChC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;KAChE,CAAC;IACF,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAClE,CAAC;AAED,yBAAyB;AACzB,MAAM,CAAC,MAAM,IAAI,GAoBb;IACF,MAAM,EAAE,CAAC,IAAc,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC;IAChD,MAAM,EAAE,CAAC,IAAc,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC;IAChD,OAAO,EAAE,CAAC,CAAC,IAAc,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAqC;IACxF,IAAI,EAAE,CAAC,MAAa,EAAE,IAAc,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC;IACnE,KAAK,EAAE,CAAC,MAAa,EAAE,IAAc,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC;CACtE,CAAC","sourcesContent":["// Prop builders (docs/design-docs/view/05-element.md \"Props\"): every component input is\n// declared with a builder over Standard Schema, so \"parse at boundaries\" covers attributes.\n//\n//   props: {\n//     label: prop.string({ required: true }),        // attribute \"label\"\n//     minPrice: prop.number({ default: 0 }),         // attribute \"min-price\"\n//     items: prop.value(v.array(Item), { default: [] }), // property only\n//   }\n//\n// A prop's type is inferred from its schema's output. The honesty rule (ADR 0007) holds by\n// construction: a prop without `required` or `default` includes `undefined`. `prop.value` and\n// `prop.json` also take a plain type guard (`(u: unknown) => u is T`) instead of a schema.\n// Schemas and guards check; they don't decode: a property set keeps the object it was given.\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { features } from './features.js';\nimport { propFeature } from './props.js';\nimport { DEV } from '#view-dev';\n\ndeclare const OUTPUT: unique symbol;\n\nexport type PropKind = 'string' | 'number' | 'boolean' | 'json' | 'value';\n\n/** One declared prop: what a builder returns. */\nexport interface Prop<T> {\n  readonly kind: PropKind;\n  /** The attribute name, `false` for property only, `undefined` for the kebab-case default. */\n  readonly attribute: string | false | undefined;\n  /**\n   * Refines (string/number/boolean) or defines (json/value) the accepted values: a Standard\n   * Schema, or for json/value a type guard (props.ts `checkValue` tells them apart).\n   */\n  readonly schema: StandardSchemaV1 | PropGuard<unknown> | undefined;\n  /** A missing value is a bug: warned once per instance at first render. */\n  readonly required: boolean;\n  /** Used whenever the element's value is missing (`boolean` props default to `false`). */\n  readonly default?: unknown;\n  /**\n   * When a new value counts as unchanged (no re-render, no `PropsChanged`): `Object.is`, the\n   * same JSON for `prop.json`, or the `equals` option of `prop.json`/`prop.value`.\n   */\n  readonly equals: (a: unknown, b: unknown) => boolean;\n  /** Type-only: the value components see. Never set. */\n  readonly [OUTPUT]?: () => T;\n}\n\n/** The props type of a table of builders: `PropsOf<typeof props>`. */\nexport type PropsOf<T extends Readonly<Record<string, Prop<unknown>>>> = {\n  readonly [K in keyof T]: T[K] extends Prop<infer V> ? V : never;\n};\n\ninterface Common {\n  /** Attribute name, or `false` for property only. Default: kebab-case of the prop name. */\n  readonly attribute?: string | false;\n}\n\ntype Schema<O> = StandardSchemaV1<unknown, O>;\n\n/** A plain type guard, accepted by `prop.value` and `prop.json` in place of a schema. */\nexport type PropGuard<T> = (value: unknown) => value is T;\n\n/** What `prop.value` and `prop.json` accept: a Standard Schema or a type guard. */\ntype Check = StandardSchemaV1 | PropGuard<unknown>;\ntype Out<S extends Check> = S extends StandardSchemaV1\n  ? StandardSchemaV1.InferOutput<S>\n  : S extends (value: unknown) => value is infer T\n    ? T\n    : never;\n\ninterface Required {\n  readonly required: true;\n  readonly default?: undefined;\n}\ninterface Defaulted<T> {\n  readonly required?: false;\n  readonly default: T;\n}\ninterface Optional {\n  readonly required?: false;\n  readonly default?: undefined;\n}\n\ntype Refined<O> = Common & { readonly schema?: Schema<O> };\n\ninterface Scalar<B> {\n  <O extends B = B>(opts: Refined<O> & (Required | Defaulted<NoInfer<O>>)): Prop<O>;\n  <O extends B = B>(opts?: Refined<O> & Optional): Prop<O | undefined>;\n}\n\n/** `equals` for `prop.json`/`prop.value`: the old and new value (`undefined` when unset). */\ninterface Equals<T> {\n  readonly equals?: (a: T | undefined, b: T | undefined) => boolean;\n}\n\ninterface WithSchema {\n  <S extends Check>(\n    schema: S,\n    opts: Common & Equals<NoInfer<Out<S>>> & (Required | Defaulted<NoInfer<Out<S>>>),\n  ): Prop<Out<S>>;\n  <S extends Check>(\n    schema: S,\n    opts?: Common & Equals<NoInfer<Out<S>>> & Optional,\n  ): Prop<Out<S> | undefined>;\n}\n\ninterface Options {\n  readonly attribute?: string | false;\n  readonly schema?: StandardSchemaV1;\n  readonly required?: boolean;\n  readonly default?: unknown;\n  readonly equals?: (a: unknown, b: unknown) => boolean;\n}\n\n/** `prop.json` values are JSON: the same JSON text is the same value. */\n// `prop.json`'s default `equals`: the same JSON text. A value JSON can't encode (a cycle, a\n// BigInt) is never equal, so the write always lands instead of throwing from the setter.\nlet warned = false;\nfunction sameJson(a: unknown, b: unknown): boolean {\n  try {\n    return JSON.stringify(a) === JSON.stringify(b);\n  } catch (error) {\n    if (DEV && !warned) {\n      warned = true;\n      console.warn(\n        `prop.json got a value JSON can't encode (${String(error)}); every write of it counts ` +\n          'as a change. Use prop.value for non-JSON values, or pass equals.',\n      );\n    }\n    return false;\n  }\n}\n\nfunction make(kind: PropKind, opts: Options = {}, schema?: Check): Prop<unknown> {\n  features.props = propFeature; // components can declare props now (features.ts)\n  const value = opts.default !== undefined ? opts.default : kind === 'boolean' ? false : undefined;\n  const base = {\n    kind,\n    attribute: kind === 'value' ? false : opts.attribute,\n    schema: schema ?? opts.schema,\n    required: opts.required === true,\n    equals: opts.equals ?? (kind === 'json' ? sameJson : Object.is),\n  };\n  return value === undefined ? base : { ...base, default: value };\n}\n\n/** The prop builders. */\nexport const prop: {\n  /** Attribute parsed as is. */\n  readonly string: Scalar<string>;\n  /** Attribute parsed with `Number(v)`; empty or `NaN` is invalid. */\n  readonly number: Scalar<number>;\n  /** Attribute present → `true`, absent → `false` (the default). */\n  readonly boolean: <O extends boolean = boolean>(\n    opts?: Refined<O> & { readonly default?: NoInfer<O> },\n  ) => Prop<O>;\n  /**\n   * Attribute parsed with `JSON.parse`, then the schema (or type guard). Compared by value: a\n   * new but equal object (a fresh `.prop=${{…}}` each render) changes nothing.\n   */\n  readonly json: WithSchema;\n  /**\n   * Property only: no attribute. Validated in development by the schema (or type guard), and\n   * the object set is kept as is (production skips the check). Compared with `Object.is`\n   * unless `equals` is given.\n   */\n  readonly value: WithSchema;\n} = {\n  string: (opts?: Options) => make('string', opts),\n  number: (opts?: Options) => make('number', opts),\n  boolean: ((opts?: Options) => make('boolean', opts)) as <O extends boolean>() => Prop<O>,\n  json: (schema: Check, opts?: Options) => make('json', opts, schema),\n  value: (schema: Check, opts?: Options) => make('value', opts, schema),\n};\n"]}

package/dist/props.d.ts

@@ -1,26 +1,62 @@
-import type { PropertyDeclaration } from 'lit';
+import type { Prop } from './prop.js';
 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;
+export type PropTable = Readonly<Record<string, Prop<unknown>>>;
+/** `minPrice` → `min-price`. */
+export declare const kebab: (name: string) => string;
+/** The prop's attribute, or undefined for a property-only prop. */
+export declare function attributeOf(name: string, def: Prop<unknown>): string | undefined;
+export type Checked = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly issues: readonly string[];
+};
+/** Runs the built-in type check and the prop's schema. Schemas must be synchronous. */
+export declare function checkValue(tag: string, name: string, def: Prop<unknown>, value: unknown): Checked;
+/** Parses an attribute value (`null`: absent) per the builder table; undefined means missing. */
+export declare function parseAttribute(def: Prop<unknown>, raw: string | null): Checked | undefined;
+/** Logs an invalid value; the caller then treats the prop as missing. */
+export declare function reportInvalid(tag: string, name: string, from: string, issues: readonly string[]): 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.
+ * An attribute's value for prop `name` (view/05-element.md "When props are validated"):
+ * parsed per the builder and always validated; invalid or absent values are missing.
+ */
+export declare function attributeValue(tag: string, name: string, def: Prop<unknown> | undefined, attr: string, raw: string | null): unknown;
+/**
+ * A property set's (or seed's) value for prop `name`: validated in development only, where an
+ * invalid value is missing and a schema that transforms warns. Production keeps the input
+ * without calling this (propFeature, element.ts: gyral-c5d.14).
+ */
+export declare function propertyValue(tag: string, name: string, def: Prop<unknown> | undefined, value: unknown, from?: string): unknown;
+/** Structural equality for plain data (arrays, plain objects), `Object.is` for the rest. */
+export declare function sameData(a: unknown, b: unknown): boolean;
+/** The declared props as components see them: `default` fills missing values. */
+export declare function readProps(values: Bag, table: PropTable): Bag;
+/** Required props that are still missing (ADR 0007 addendum). */
+export declare function missingRequired(values: Bag, table: PropTable): string[];
+/** Warns about required props that are still missing, at first render. */
+export declare function warnMissing(tag: string, values: Bag, table: PropTable): void;
+/**
+ * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …):
+ * the accessor replaces the built-in, so setting the prop silently changes what the platform
+ * does with it (gyral-czi.33).
  */
 export declare function shadowedBuiltins(names: readonly string[]): string[];
+/** define(): a prop named like a built-in property is an error in development, else a warning. */
+export declare function checkShadowed(tag: string, names: readonly string[]): void;
+/**
+ * What the element uses, registered by the prop builders (features.ts). Property sets and seeds
+ * go through `propertyValue` in development only: production keeps the value as given, so the
+ * property path's schema and guard handling stay out of production bundles (gyral-c5d.14).
+ */
+export declare const propFeature: {
+    attributeOf: typeof attributeOf;
+    attributeValue: typeof attributeValue;
+    propertyValue: typeof propertyValue | undefined;
+    warnMissing: typeof warnMissing;
+    readProps: typeof readProps;
+    checkShadowed: typeof checkShadowed;
+};
+export type PropFeature = typeof propFeature;
 export {};