@gyral/core 0.1.0 → 0.3.0

package/dist/internal/interpreter.js.map

@@ -1 +1 @@
-{"version":3,"file":"interpreter.js","sourceRoot":"","sources":["../../src/internal/interpreter.ts"],"names":[],"mappings":"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","sourcesContent":["import { Data, Duration, Effect, Fiber, Schedule } from 'effect';\nimport { DEVTOOLS_ENABLED } from '#devtools';\nimport type { AnyDriver, Command, Concurrency, RetryPolicy } from '../command.js';\nimport type { CommandPhase, CommandTrace } from '../devtools-events.js';\nimport { fork } from './runtime.js';\n\nclass DriverFailure extends Data.TaggedError('DriverFailure')<{ readonly cause: unknown }> {}\n\ntype Running = Fiber.RuntimeFiber<void>;\n\n/** Runs commands for one connected element. Disposed on disconnect. */\nexport interface Interpreter<M> {\n  readonly run: (cmd: Command<M>) => void;\n  readonly dispose: () => void;\n}\n\nconst isRunning = (fiber: Running | undefined): fiber is Running =>\n  fiber !== undefined && fiber.unsafePoll() === null;\n\nconst withRetry = <A>(\n  attempt: Effect.Effect<A, DriverFailure>,\n  policy: RetryPolicy | undefined,\n): Effect.Effect<A, DriverFailure> => {\n  if (policy === undefined || policy.times <= 0) return attempt;\n  const base = Duration.millis(policy.delayMs ?? 0);\n  const delays: Schedule.Schedule<unknown> =\n    policy.backoff === 'exponential' ? Schedule.exponential(base) : Schedule.spaced(base);\n  return Effect.retry(attempt, delays.pipe(Schedule.intersect(Schedule.recurs(policy.times))));\n};\n\n/** Reports one command's lifecycle to devtools (ADR 0017); undefined in production. */\ntype Report = ((phase: CommandPhase, result?: unknown) => void) | undefined;\n\nconst execute = <M>(\n  driver: AnyDriver,\n  cmd: Command<M>,\n  dispatch: (msg: M) => void,\n  report: Report,\n): Effect.Effect<void> => {\n  const deliver = (output: unknown): void => {\n    try {\n      const msg = cmd.onSuccess(output);\n      if (msg !== undefined) dispatch(msg);\n    } catch (defect) {\n      console.error('gyral: command mapper threw', defect);\n    }\n  };\n  const attempt = Effect.tryPromise({\n    try: (signal) => {\n      let settled = false;\n      const emit = (output: unknown): void => {\n        if (!settled && !signal.aborted) deliver(output);\n      };\n      // The input type was erased by command(); it was built for this driver's name.\n      const result = Promise.resolve(driver.run(cmd.input as never, { signal, emit }));\n      return result.finally(() => {\n        settled = true;\n      });\n    },\n    catch: (cause) => new DriverFailure({ cause }),\n  });\n  const traced =\n    DEVTOOLS_ENABLED && report !== undefined\n      ? withRetry(attempt, driver.retry).pipe(\n          Effect.onInterrupt(() =>\n            Effect.sync(() => {\n              report('interrupted');\n            }),\n          ),\n        )\n      : withRetry(attempt, driver.retry);\n  return traced.pipe(\n    Effect.matchEffect({\n      onSuccess: (output) => {\n        if (DEVTOOLS_ENABLED) report?.('settled', output);\n        return Effect.succeed(cmd.onSuccess(output));\n      },\n      onFailure: (failure) => {\n        const error = driver.toError === undefined ? failure.cause : driver.toError(failure.cause);\n        if (DEVTOOLS_ENABLED) report?.('failed', error);\n        return cmd.onFailure === undefined\n          ? Effect.logWarning(`gyral: unhandled failure from driver \"${driver.name}\"`, error).pipe(\n              Effect.as(undefined),\n            )\n          : Effect.succeed(cmd.onFailure(error));\n      },\n    }),\n    Effect.flatMap((msg) =>\n      Effect.sync(() => {\n        if (msg !== undefined) dispatch(msg);\n      }),\n    ),\n    Effect.catchAllDefect((defect) => Effect.logError('gyral: command mapper threw', defect)),\n  );\n};\n\nexport function makeInterpreter<M>(\n  resolve: (driver: AnyDriver) => AnyDriver,\n  dispatch: (msg: M) => void,\n  trace?: CommandTrace,\n): Interpreter<M> {\n  const reporter = (driver: string, lane: string, policy: Concurrency, input: unknown): Report =>\n    trace === undefined\n      ? undefined\n      : (phase, result) => {\n          trace({\n            phase,\n            driver,\n            lane,\n            policy,\n            input,\n            ...(result === undefined ? {} : { result }),\n          });\n        };\n  const lanes = new Map<string, Running>();\n  const all = new Set<Running>();\n  let active = true;\n  const guardedDispatch = (msg: M): void => {\n    if (active) dispatch(msg);\n  };\n\n  const track = (lane: string, fiber: Running): void => {\n    if (!isRunning(fiber)) return;\n    lanes.set(lane, fiber);\n    all.add(fiber);\n    fiber.addObserver(() => {\n      all.delete(fiber);\n      if (lanes.get(lane) === fiber) lanes.delete(lane);\n    });\n  };\n\n  const run = (cmd: Command<M>): void => {\n    if (!active) return;\n    const driver = resolve(cmd.driver);\n    const lane = cmd.key ?? driver.name;\n    const policy = cmd.concurrency ?? driver.concurrency ?? 'merge';\n    const previous = lanes.get(lane);\n    const inFlight = isRunning(previous) ? previous : undefined;\n    const report = DEVTOOLS_ENABLED ? reporter(driver.name, lane, policy, cmd.input) : undefined;\n    let program = execute(driver, cmd, guardedDispatch, report);\n    if (inFlight !== undefined && policy === 'exhaust') {\n      if (DEVTOOLS_ENABLED) report?.('dropped');\n      return;\n    }\n    if (DEVTOOLS_ENABLED) report?.('issued');\n    if (inFlight !== undefined) {\n      if (policy === 'switch') program = Effect.zipRight(Fiber.interrupt(inFlight), program);\n      if (policy === 'queue') program = Effect.zipRight(Fiber.await(inFlight), program);\n    }\n    track(lane, fork(program));\n  };\n\n  const dispose = (): void => {\n    active = false;\n    fork(Fiber.interruptAll([...all]));\n    all.clear();\n    lanes.clear();\n  };\n\n  return { run, dispose };\n}\n"]}
+{"version":3,"file":"interpreter.js","sourceRoot":"","sources":["../../src/internal/interpreter.ts"],"names":[],"mappings":"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","sourcesContent":["import { DEVTOOLS_ENABLED } from '#devtools';\nimport type { AnyDriver, Command, Concurrency, DriverOverrides, RetryPolicy } from '../command.js';\nimport type { CommandPhase, CommandTrace } from '../devtools-events.js';\nimport { providedDriver } from '../drivers-scope.js';\nimport type { FeatureHost } from '../features.js';\n\n// The command interpreter (ADR 0015: hand-written, no runtime dependencies). Each running command is a task with its own AbortController; lanes hold the\n// latest task per key. Interruption is `controller.abort()`, retry schedules are timers\n// that cancel on abort, and `queue` chains on the previous task's promise.\n\n/** Runs commands for one connected element. Disposed on disconnect. */\nexport interface Interpreter<M> {\n  readonly run: (cmd: Command<M>) => void;\n  readonly dispose: () => void;\n}\n\ninterface Task {\n  readonly controller: AbortController;\n  done: Promise<void>;\n  running: boolean;\n}\n\n/** Reports one command's lifecycle to devtools (ADR 0017); undefined in production. */\ntype Report = ((phase: CommandPhase, result?: unknown) => void) | undefined;\n\n/** Rejects when `signal` aborts. Marked handled so a losing race never reports it. */\nconst aborted = (signal: AbortSignal): Promise<never> => {\n  const promise = new Promise<never>((_resolve, reject) => {\n    // Callers check `signal.aborted`, never the reason.\n    const interrupt = (): void => {\n      reject(signal.reason as Error);\n    };\n    if (signal.aborted) interrupt();\n    else signal.addEventListener('abort', interrupt, { once: true });\n  });\n  promise.catch(() => undefined);\n  return promise;\n};\n\n/** Waits `ms`, or rejects as soon as `signal` aborts. */\nconst sleep = (ms: number, signal: AbortSignal): Promise<void> =>\n  Promise.race([\n    new Promise<void>((resolve) => {\n      const timer = setTimeout(resolve, ms);\n      signal.addEventListener(\n        'abort',\n        () => {\n          clearTimeout(timer);\n        },\n        { once: true },\n      );\n    }),\n    aborted(signal),\n  ]);\n\n/** Delay before retry number `retry` (0-based): fixed, or doubling from `delayMs`. */\nconst delayFor = (policy: RetryPolicy, retry: number): number => {\n  const base = policy.delayMs ?? 0;\n  return policy.backoff === 'exponential' ? base * 2 ** retry : base;\n};\n\nasync function attemptWithRetry(\n  driver: AnyDriver,\n  cmd: Command<unknown>,\n  signal: AbortSignal,\n  emit: (output: unknown) => void,\n): Promise<unknown> {\n  const policy = driver.retry;\n  for (let retry = 0; ; retry += 1) {\n    try {\n      // The input type was erased by command(); it was built for this driver's name.\n      const result = Promise.resolve(driver.run(cmd.input as never, { signal, emit }));\n      return await Promise.race([result, aborted(signal)]);\n    } catch (cause) {\n      if (signal.aborted || policy === undefined || retry >= policy.times) throw cause;\n      await sleep(delayFor(policy, retry), signal);\n    }\n  }\n}\n\n/** Maps a result to a message and dispatches it; a throwing mapper is logged, not fatal. */\nconst deliver = <M>(map: () => M | undefined, dispatch: (msg: M) => void): void => {\n  try {\n    const msg = map();\n    if (msg !== undefined) dispatch(msg);\n  } catch (defect) {\n    console.error('gyral: command mapper threw', defect);\n  }\n};\n\nasync function execute<M>(\n  driver: AnyDriver,\n  cmd: Command<M>,\n  signal: AbortSignal,\n  dispatch: (msg: M) => void,\n  report: Report,\n): Promise<void> {\n  let settled = false;\n  const emit = (output: unknown): void => {\n    if (!settled && !signal.aborted) deliver(() => cmd.onSuccess(output), dispatch);\n  };\n  if (DEVTOOLS_ENABLED && report !== undefined) {\n    signal.addEventListener(\n      'abort',\n      () => {\n        if (!settled) report('interrupted');\n      },\n      { once: true },\n    );\n  }\n  let output: unknown;\n  try {\n    output = await attemptWithRetry(driver, cmd, signal, emit);\n  } catch (cause) {\n    if (signal.aborted) return; // interrupted: reported by the abort listener\n    settled = true;\n    const error = driver.toError === undefined ? cause : driver.toError(cause);\n    if (DEVTOOLS_ENABLED) report?.('failed', error);\n    if (cmd.onFailure === undefined) {\n      console.warn(`gyral: unhandled failure from driver \"${driver.name}\"`, error);\n      return;\n    }\n    const onFailure = cmd.onFailure;\n    deliver(() => onFailure(error), dispatch);\n    return;\n  }\n  if (signal.aborted) return;\n  settled = true;\n  if (DEVTOOLS_ENABLED) report?.('settled', output);\n  deliver(() => cmd.onSuccess(output), dispatch);\n}\n\nexport function makeInterpreter<M>(\n  resolve: (driver: AnyDriver) => AnyDriver,\n  dispatch: (msg: M) => void,\n  trace?: CommandTrace,\n): Interpreter<M> {\n  const reporter = (driver: string, lane: string, policy: Concurrency, input: unknown): Report =>\n    trace === undefined\n      ? undefined\n      : (phase, result) => {\n          trace({\n            phase,\n            driver,\n            lane,\n            policy,\n            input,\n            ...(result === undefined ? {} : { result }),\n          });\n        };\n  const lanes = new Map<string, Task>();\n  const all = new Set<Task>();\n  let active = true;\n  const guardedDispatch = (msg: M): void => {\n    if (active) dispatch(msg);\n  };\n\n  const start = (\n    lane: string,\n    driver: AnyDriver,\n    cmd: Command<M>,\n    report: Report,\n    after?: Task,\n  ): void => {\n    const controller = new AbortController();\n    const task: Task = { controller, running: true, done: Promise.resolve() };\n    const body = async (): Promise<void> => {\n      if (after !== undefined) await after.done;\n      if (!controller.signal.aborted) {\n        await execute(driver, cmd, controller.signal, guardedDispatch, report);\n      }\n    };\n    task.done = body().finally(() => {\n      task.running = false;\n      all.delete(task);\n      if (lanes.get(lane) === task) lanes.delete(lane);\n    });\n    lanes.set(lane, task);\n    all.add(task);\n  };\n\n  const run = (cmd: Command<M>): void => {\n    if (!active) return;\n    const driver = resolve(cmd.driver);\n    const lane = cmd.key ?? driver.name;\n    const policy = cmd.concurrency ?? driver.concurrency ?? 'merge';\n    const previous = lanes.get(lane);\n    const inFlight = previous?.running === true ? previous : undefined;\n    const report = DEVTOOLS_ENABLED ? reporter(driver.name, lane, policy, cmd.input) : undefined;\n    if (inFlight !== undefined && policy === 'exhaust') {\n      if (DEVTOOLS_ENABLED) report?.('dropped');\n      return;\n    }\n    if (DEVTOOLS_ENABLED) report?.('issued');\n    if (inFlight !== undefined && policy === 'switch') inFlight.controller.abort();\n    start(\n      lane,\n      driver,\n      cmd,\n      report,\n      inFlight !== undefined && policy === 'queue' ? inFlight : undefined,\n    );\n  };\n\n  const dispose = (): void => {\n    active = false;\n    for (const task of all) task.controller.abort();\n    all.clear();\n    lanes.clear();\n  };\n\n  return { run, dispose };\n}\n\n/**\n * A component's interpreter (registered by `command()`, features.ts). Drivers resolve by name:\n * el.drivers → nearest provider → spec.drivers → the command's own (gyral-czi.35).\n */\nexport const hostInterpreter = <M>(\n  el: FeatureHost,\n  drivers: DriverOverrides | undefined,\n  dispatch: (msg: M) => void,\n  trace: CommandTrace | undefined,\n): Interpreter<M> =>\n  makeInterpreter(\n    (driver) =>\n      el.drivers[driver.name] ??\n      providedDriver(el, driver.name) ??\n      drivers?.[driver.name] ??\n      driver,\n    dispatch,\n    trace,\n  );\n"]}

package/dist/invokers-shim.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fallback for browsers without invoker commands: a click on a `command="--…"` invoker inside
+ * `root` dispatches a `command` event on its `commandfor` target (same tree scope), with the
+ * `command` and `source` properties a native `CommandEvent` has.
+ */
+export declare function shimInvokers(root: Node): void;

package/dist/invokers-shim.js

@@ -0,0 +1,32 @@
+/** 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` event on its `commandfor` target (same tree scope), with the
+ * `command` and `source` properties a native `CommandEvent` has.
+ */
+export function shimInvokers(root) {
+    root.addEventListener('click', (event) => {
+        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;
+        const info = { command, source: invoker };
+        target.dispatchEvent(Object.assign(new Event('command', { cancelable: true }), info));
+    });
+}
+//# sourceMappingURL=invokers-shim.js.map

package/dist/invokers-shim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invokers-shim.js","sourceRoot":"","sources":["../src/invokers-shim.ts"],"names":[],"mappings":"AAKA,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;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QACvC,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,IAAI,GAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QACvD,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACxF,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["// The invoker-command fallback (gyral-czi.6, ADR 0003 tier 3): loaded with import() by a\n// component that listens for `command` intents in a browser without `CommandEvent`\n// (intent.ts). Remove it when invoker commands are widely available (2028-06-12).\nimport type { CommandInfo } from './invokers.js';\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` event on its `commandfor` target (same tree scope), with the\n * `command` and `source` properties a native `CommandEvent` has.\n */\nexport function shimInvokers(root: Node): void {\n  root.addEventListener('click', (event) => {\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    const info: CommandInfo = { command, source: invoker };\n    target.dispatchEvent(Object.assign(new Event('command', { cancelable: true }), info));\n  });\n}\n"]}

package/dist/invokers.d.ts

@@ -6,10 +6,8 @@ export interface CommandInfo {
 }
 /** Native invoker commands available? */
 export declare const invokersSupported: () => boolean;
-/** The command carried by a native `CommandEvent` or by Gyral's fallback event. */
-export declare function commandOf(event: Event): CommandInfo | 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 declare function shimInvokers(root: Node): void;
+export declare function commandOf(event: Event): CommandInfo | undefined;

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;
 }
 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?: boolean;\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,66 @@
+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. */
+    readonly schema: StandardSchemaV1 | 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;
+    /** 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>;
+type Out<S extends StandardSchemaV1> = StandardSchemaV1.InferOutput<S>;
+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>;
+}
+interface WithSchema {
+    <S extends StandardSchemaV1>(schema: S, opts: Common & (Required | Defaulted<NoInfer<Out<S>>>)): Prop<Out<S>>;
+    <S extends StandardSchemaV1>(schema: S, opts?: Common & 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. */
+    readonly json: WithSchema;
+    /** Property only: no attribute. Validated in development. */
+    readonly value: WithSchema;
+};
+export {};

package/dist/prop.js

@@ -0,0 +1,22 @@
+import { features } from './features.js';
+import { propFeature } from './props.js';
+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,
+    };
+    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":"AAYA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqEzC,SAAS,IAAI,CAAC,IAAc,EAAE,OAAgB,EAAE,EAAE,MAAyB;IACzE,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;KACjC,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,GAab;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,MAAwB,EAAE,IAAc,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC;IAC9E,KAAK,EAAE,CAAC,MAAwB,EAAE,IAAc,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC;CACjF,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`.\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { features } from './features.js';\nimport { propFeature } from './props.js';\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  /** Refines (string/number/boolean) or defines (json/value) the accepted values. */\n  readonly schema: StandardSchemaV1 | 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  /** 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>;\ntype Out<S extends StandardSchemaV1> = StandardSchemaV1.InferOutput<S>;\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\ninterface WithSchema {\n  <S extends StandardSchemaV1>(\n    schema: S,\n    opts: Common & (Required | Defaulted<NoInfer<Out<S>>>),\n  ): Prop<Out<S>>;\n  <S extends StandardSchemaV1>(schema: S, opts?: Common & Optional): 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}\n\nfunction make(kind: PropKind, opts: Options = {}, schema?: StandardSchemaV1): 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  };\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  /** Attribute parsed with `JSON.parse`, then the schema. */\n  readonly json: WithSchema;\n  /** Property only: no attribute. Validated in development. */\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: StandardSchemaV1, opts?: Options) => make('json', opts, schema),\n  value: (schema: StandardSchemaV1, opts?: Options) => make('value', opts, schema),\n};\n"]}