@gyral/core 0.3.0 → 0.3.2

package/dist/internal/indexeddb-transaction.js

@@ -0,0 +1,134 @@
+import { databaseError } from './indexeddb-open.js';
+const rangeOf = (range) => {
+    if (range === undefined)
+        return undefined;
+    switch (range._tag) {
+        case 'Only':
+            return IDBKeyRange.only(range.key);
+        case 'Lower':
+            return IDBKeyRange.lowerBound(range.key, range.open);
+        case 'Upper':
+            return IDBKeyRange.upperBound(range.key, range.open);
+        case 'Bound':
+            return IDBKeyRange.bound(range.lower, range.upper, range.lowerOpen, range.upperOpen);
+    }
+};
+/** Queue requests synchronously and resolve only from transaction complete. */
+export function transact(db, operations, signal) {
+    return new Promise((resolve, reject) => {
+        signal.throwIfAborted();
+        const mode = operations.some((op) => op._tag === 'Put' || op._tag === 'Delete')
+            ? 'readwrite'
+            : 'readonly';
+        const tx = db.transaction([...new Set(operations.map((op) => op.store))], mode);
+        const state = { ended: false };
+        const results = [];
+        const releaseRequests = [];
+        let failure;
+        const cleanup = () => {
+            signal.removeEventListener('abort', abort);
+            tx.oncomplete = null;
+            tx.onabort = null;
+            tx.onerror = null;
+            for (const release of releaseRequests)
+                release();
+        };
+        const end = (cause) => {
+            if (state.ended)
+                return;
+            state.ended = true;
+            cleanup();
+            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- preserve AbortSignal reasons
+            reject(cause);
+        };
+        const stop = () => {
+            try {
+                tx.abort();
+            }
+            catch {
+                /* A completed transaction cannot be undone. */
+            }
+        };
+        const abort = () => {
+            stop();
+            end(signal.reason);
+        };
+        signal.addEventListener('abort', abort, { once: true });
+        tx.onerror = (event) => {
+            if (event.target instanceof IDBRequest)
+                failure = event.target.error;
+        };
+        tx.onabort = () => {
+            end(databaseError(db.name, 'transaction', failure ?? tx.error ?? new Error('Transaction aborted.')));
+        };
+        tx.oncomplete = () => {
+            if (state.ended)
+                return;
+            state.ended = true;
+            cleanup();
+            resolve(results);
+        };
+        try {
+            operations.forEach((op, position) => {
+                const store = tx.objectStore(op.store);
+                if (op._tag === 'Read') {
+                    const request = store.openCursor(IDBKeyRange.only(op.key));
+                    releaseRequests.push(() => {
+                        request.onsuccess = null;
+                    });
+                    request.onsuccess = () => {
+                        const cursor = request.result;
+                        const value = cursor?.value;
+                        results[position] = {
+                            _tag: 'Record',
+                            store: op.store,
+                            key: op.key,
+                            entry: cursor === null ? { found: false } : { found: true, value },
+                        };
+                    };
+                }
+                else if (op._tag === 'Query') {
+                    const rows = [];
+                    results[position] = { _tag: 'Records', store: op.store, records: rows };
+                    const source = op.index === undefined ? store : store.index(op.index);
+                    const request = source.openCursor(rangeOf(op.range), op.direction);
+                    releaseRequests.push(() => {
+                        request.onsuccess = null;
+                    });
+                    request.onsuccess = () => {
+                        const cursor = request.result;
+                        if (cursor === null)
+                            return;
+                        const value = cursor.value;
+                        rows.push({ key: cursor.primaryKey, value });
+                        if (rows.length < op.limit)
+                            cursor.continue();
+                    };
+                }
+                else if (op._tag === 'Put') {
+                    const request = op.key === undefined ? store.put(op.value) : store.put(op.value, op.key);
+                    releaseRequests.push(() => {
+                        request.onsuccess = null;
+                    });
+                    request.onsuccess = () => {
+                        results[position] = { _tag: 'Put', store: op.store, key: request.result };
+                    };
+                }
+                else {
+                    const request = store.delete(op.key);
+                    releaseRequests.push(() => {
+                        request.onsuccess = null;
+                    });
+                    request.onsuccess = () => {
+                        results[position] = { _tag: 'Deleted', store: op.store, key: op.key };
+                    };
+                }
+            });
+        }
+        catch (cause) {
+            stop();
+            end(databaseError(db.name, 'transaction', cause));
+        }
+    });
+}
+//# sourceMappingURL=indexeddb-transaction.js.map

package/dist/internal/indexeddb-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb-transaction.js","sourceRoot":"","sources":["../../src/internal/indexeddb-transaction.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  IndexedDBOperation,\n  IndexedDBRange,\n  IndexedDBResult,\n  IndexedDBStores,\n} from '../indexeddb-types.js';\nimport { databaseError } from './indexeddb-open.js';\n\nexport type RawResult = IndexedDBResult<IndexedDBStores>;\nconst rangeOf = (range: IndexedDBRange | undefined): IDBKeyRange | undefined => {\n  if (range === undefined) return undefined;\n  switch (range._tag) {\n    case 'Only':\n      return IDBKeyRange.only(range.key);\n    case 'Lower':\n      return IDBKeyRange.lowerBound(range.key, range.open);\n    case 'Upper':\n      return IDBKeyRange.upperBound(range.key, range.open);\n    case 'Bound':\n      return IDBKeyRange.bound(range.lower, range.upper, range.lowerOpen, range.upperOpen);\n  }\n};\n\n/** Queue requests synchronously and resolve only from transaction complete. */\nexport function transact(\n  db: IDBDatabase,\n  operations: readonly IndexedDBOperation<IndexedDBStores>[],\n  signal: AbortSignal,\n): Promise<readonly RawResult[]> {\n  return new Promise((resolve, reject) => {\n    signal.throwIfAborted();\n    const mode = operations.some((op) => op._tag === 'Put' || op._tag === 'Delete')\n      ? 'readwrite'\n      : 'readonly';\n    const tx = db.transaction([...new Set(operations.map((op) => op.store))], mode);\n    const state = { ended: false };\n    const results: RawResult[] = [];\n    const releaseRequests: (() => void)[] = [];\n    let failure: unknown;\n    const cleanup = (): void => {\n      signal.removeEventListener('abort', abort);\n      tx.oncomplete = null;\n      tx.onabort = null;\n      tx.onerror = null;\n      for (const release of releaseRequests) release();\n    };\n    const end = (cause: unknown): void => {\n      if (state.ended) return;\n      state.ended = true;\n      cleanup();\n      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- preserve AbortSignal reasons\n      reject(cause);\n    };\n    const stop = (): void => {\n      try {\n        tx.abort();\n      } catch {\n        /* A completed transaction cannot be undone. */\n      }\n    };\n    const abort = (): void => {\n      stop();\n      end(signal.reason);\n    };\n    signal.addEventListener('abort', abort, { once: true });\n    tx.onerror = (event) => {\n      if (event.target instanceof IDBRequest) failure = event.target.error;\n    };\n    tx.onabort = () => {\n      end(\n        databaseError(\n          db.name,\n          'transaction',\n          failure ?? tx.error ?? new Error('Transaction aborted.'),\n        ),\n      );\n    };\n    tx.oncomplete = () => {\n      if (state.ended) return;\n      state.ended = true;\n      cleanup();\n      resolve(results);\n    };\n    try {\n      operations.forEach((op, position) => {\n        const store = tx.objectStore(op.store);\n        if (op._tag === 'Read') {\n          const request = store.openCursor(IDBKeyRange.only(op.key));\n          releaseRequests.push(() => {\n            request.onsuccess = null;\n          });\n          request.onsuccess = () => {\n            const cursor = request.result;\n            const value: unknown = cursor?.value;\n            results[position] = {\n              _tag: 'Record',\n              store: op.store,\n              key: op.key,\n              entry: cursor === null ? { found: false } : { found: true, value },\n            };\n          };\n        } else if (op._tag === 'Query') {\n          const rows: { key: IDBValidKey; value: unknown }[] = [];\n          results[position] = { _tag: 'Records', store: op.store, records: rows };\n          const source = op.index === undefined ? store : store.index(op.index);\n          const request = source.openCursor(rangeOf(op.range), op.direction);\n          releaseRequests.push(() => {\n            request.onsuccess = null;\n          });\n          request.onsuccess = () => {\n            const cursor = request.result;\n            if (cursor === null) return;\n            const value: unknown = cursor.value;\n            rows.push({ key: cursor.primaryKey, value });\n            if (rows.length < op.limit) cursor.continue();\n          };\n        } else if (op._tag === 'Put') {\n          const request = op.key === undefined ? store.put(op.value) : store.put(op.value, op.key);\n          releaseRequests.push(() => {\n            request.onsuccess = null;\n          });\n          request.onsuccess = () => {\n            results[position] = { _tag: 'Put', store: op.store, key: request.result };\n          };\n        } else {\n          const request = store.delete(op.key);\n          releaseRequests.push(() => {\n            request.onsuccess = null;\n          });\n          request.onsuccess = () => {\n            results[position] = { _tag: 'Deleted', store: op.store, key: op.key };\n          };\n        }\n      });\n    } catch (cause) {\n      stop();\n      end(databaseError(db.name, 'transaction', cause));\n    }\n  });\n}\n"]}

package/dist/internal/interpreter.d.ts

@@ -1,14 +1,22 @@
-import type { AnyDriver, Command, DriverOverrides } from '../command.js';
+import type { AnyDriver, Command } from '../command.js';
 import type { CommandTrace } from '../devtools-events.js';
 import type { FeatureHost } from '../features.js';
 /** Runs commands for one connected element. Disposed on disconnect. */
 export interface Interpreter<M> {
     readonly run: (cmd: Command<M>) => void;
+    /** Aborts the running task of `lane`, if any (subscriptions.ts: a subscription that left). */
+    readonly cancel: (lane: string) => void;
     readonly dispose: () => void;
 }
-export declare function makeInterpreter<M>(resolve: (driver: AnyDriver) => AnyDriver, dispatch: (msg: M) => void, trace?: CommandTrace): Interpreter<M>;
+/**
+ * Reports a failure to the owner (ADR 0024): `40` a mapper threw, `41` a driver failed and the
+ * command has no `onFailure`, `43` nothing provides a driver token. The owner builds the message
+ * and reports it.
+ */
+export type CommandFailure = (cause: unknown, code: 40 | 41 | 43, driver: string) => void;
+export declare function makeInterpreter<M>(resolve: (driver: AnyDriver) => AnyDriver, dispatch: (msg: M) => void, trace: CommandTrace | undefined, failed: CommandFailure): Interpreter<M>;
 /**
  * A component's interpreter (registered by `command()`, features.ts). Drivers resolve by name:
- * el.drivers → nearest provider → spec.drivers → the command's own (gyral-czi.35).
+ * el.drivers → nearest provider → the command's own (gyral-czi.35; ADR 0006 "Driver tokens").
  */
-export declare const hostInterpreter: <M>(el: FeatureHost, drivers: DriverOverrides | undefined, dispatch: (msg: M) => void, trace: CommandTrace | undefined) => Interpreter<M>;
+export declare const hostInterpreter: <M>(el: FeatureHost, dispatch: (msg: M) => void, trace: CommandTrace | undefined, failed: CommandFailure) => Interpreter<M>;

package/dist/internal/interpreter.js

@@ -1,5 +1,6 @@
 import { DEVTOOLS_ENABLED } from '#devtools';
 import { providedDriver } from '../drivers-scope.js';
+import { unprovided } from './token.js';
 /** Rejects when `signal` aborts. Marked handled so a losing race never reports it. */
 const aborted = (signal) => {
     const promise = new Promise((_resolve, reject) => {
@@ -15,52 +16,35 @@ const aborted = (signal) => {
     promise.catch(() => undefined);
     return promise;
 };
-/** Waits `ms`, or rejects as soon as `signal` aborts. */
-const sleep = (ms, signal) => Promise.race([
-    new Promise((resolve) => {
-        const timer = setTimeout(resolve, ms);
-        signal.addEventListener('abort', () => {
-            clearTimeout(timer);
-        }, { once: true });
-    }),
+/** Runs the driver once; an abort settles it at once, even if the driver ignores the signal. */
+const attempt = (driver, cmd, signal, emit) => 
+// The input type was erased by command(); it was built for this driver's name.
+Promise.race([
+    Promise.resolve(driver.run(cmd.input, { signal, emit })),
     aborted(signal),
 ]);
-/** Delay before retry number `retry` (0-based): fixed, or doubling from `delayMs`. */
-const delayFor = (policy, retry) => {
-    const base = policy.delayMs ?? 0;
-    return policy.backoff === 'exponential' ? base * 2 ** retry : base;
-};
-async function attemptWithRetry(driver, cmd, signal, emit) {
-    const policy = driver.retry;
-    for (let retry = 0;; retry += 1) {
-        try {
-            // The input type was erased by command(); it was built for this driver's name.
-            const result = Promise.resolve(driver.run(cmd.input, { signal, emit }));
-            return await Promise.race([result, aborted(signal)]);
-        }
-        catch (cause) {
-            if (signal.aborted || policy === undefined || retry >= policy.times)
-                throw cause;
-            await sleep(delayFor(policy, retry), signal);
-        }
-    }
-}
-/** Maps a result to a message and dispatches it; a throwing mapper is logged, not fatal. */
-const deliver = (map, dispatch) => {
+/**
+ * Maps a result to a message and dispatches it. A throwing mapper is reported (ADR 0024) and
+ * sends nothing; the reducer's own failures are the owner's (dispatch reports them).
+ */
+const deliver = (map, dispatch, failed, driver) => {
+    let msg;
     try {
-        const msg = map();
-        if (msg !== undefined)
-            dispatch(msg);
+        msg = map();
     }
     catch (defect) {
-        console.error('gyral: command mapper threw', defect);
+        failed(defect, 40, driver);
+        return;
     }
+    if (msg !== undefined)
+        dispatch(msg);
 };
-async function execute(driver, cmd, signal, dispatch, report) {
+async function execute(driver, cmd, signal, dispatch, report, failed) {
     let settled = false;
+    const name = driver.name;
     const emit = (output) => {
         if (!settled && !signal.aborted)
-            deliver(() => cmd.onSuccess(output), dispatch);
+            deliver(() => cmd.onSuccess(output), dispatch, failed, name);
     };
     if (DEVTOOLS_ENABLED && report !== undefined) {
         signal.addEventListener('abort', () => {
@@ -70,7 +54,7 @@ async function execute(driver, cmd, signal, dispatch, report) {
     }
     let output;
     try {
-        output = await attemptWithRetry(driver, cmd, signal, emit);
+        output = await attempt(driver, cmd, signal, emit);
     }
     catch (cause) {
         if (signal.aborted)
@@ -80,11 +64,11 @@ async function execute(driver, cmd, signal, dispatch, report) {
         if (DEVTOOLS_ENABLED)
             report?.('failed', error);
         if (cmd.onFailure === undefined) {
-            console.warn(`gyral: unhandled failure from driver "${driver.name}"`, error);
+            failed(error, 41, name);
             return;
         }
         const onFailure = cmd.onFailure;
-        deliver(() => onFailure(error), dispatch);
+        deliver(() => onFailure(error), dispatch, failed, name);
         return;
     }
     if (signal.aborted)
@@ -92,9 +76,9 @@ async function execute(driver, cmd, signal, dispatch, report) {
     settled = true;
     if (DEVTOOLS_ENABLED)
         report?.('settled', output);
-    deliver(() => cmd.onSuccess(output), dispatch);
+    deliver(() => cmd.onSuccess(output), dispatch, failed, name);
 }
-export function makeInterpreter(resolve, dispatch, trace) {
+export function makeInterpreter(resolve, dispatch, trace, failed) {
     const reporter = (driver, lane, policy, input) => trace === undefined
         ? undefined
         : (phase, result) => {
@@ -121,7 +105,7 @@ export function makeInterpreter(resolve, dispatch, trace) {
             if (after !== undefined)
                 await after.done;
             if (!controller.signal.aborted) {
-                await execute(driver, cmd, controller.signal, guardedDispatch, report);
+                await execute(driver, cmd, controller.signal, guardedDispatch, report, failed);
             }
         };
         task.done = body().finally(() => {
@@ -137,6 +121,10 @@ export function makeInterpreter(resolve, dispatch, trace) {
         if (!active)
             return;
         const driver = resolve(cmd.driver);
+        if (driver.run === unprovided) {
+            failed(undefined, 43, driver.name);
+            return;
+        }
         const lane = cmd.key ?? driver.name;
         const policy = cmd.concurrency ?? driver.concurrency ?? 'merge';
         const previous = lanes.get(lane);
@@ -153,6 +141,9 @@ export function makeInterpreter(resolve, dispatch, trace) {
             inFlight.controller.abort();
         start(lane, driver, cmd, report, inFlight !== undefined && policy === 'queue' ? inFlight : undefined);
     };
+    const cancel = (lane) => {
+        lanes.get(lane)?.controller.abort();
+    };
     const dispose = () => {
         active = false;
         for (const task of all)
@@ -160,14 +151,11 @@ export function makeInterpreter(resolve, dispatch, trace) {
         all.clear();
         lanes.clear();
     };
-    return { run, dispose };
+    return { run, cancel, dispose };
 }
 /**
  * A component's interpreter (registered by `command()`, features.ts). Drivers resolve by name:
- * el.drivers → nearest provider → spec.drivers → the command's own (gyral-czi.35).
+ * el.drivers → nearest provider → the command's own (gyral-czi.35; ADR 0006 "Driver tokens").
  */
-export const hostInterpreter = (el, drivers, dispatch, trace) => makeInterpreter((driver) => el.drivers[driver.name] ??
-    providedDriver(el, driver.name) ??
-    drivers?.[driver.name] ??
-    driver, dispatch, trace);
+export const hostInterpreter = (el, dispatch, trace, failed) => makeInterpreter((driver) => el.drivers[driver.name] ?? providedDriver(el, driver.name) ?? driver, dispatch, trace, failed);
 //# sourceMappingURL=interpreter.js.map

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 { 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"]}
+{"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 } from '../command.js';\nimport type { CommandPhase, CommandTrace } from '../devtools-events.js';\nimport { providedDriver } from '../drivers-scope.js';\nimport type { FeatureHost } from '../features.js';\nimport { unprovided } from './token.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()`,\n// and `queue` chains on the previous task's promise. A driver runs once: retries are a driver\n// wrapper (retry.ts, ADR 0022).\n\n/** Runs commands for one connected element. Disposed on disconnect. */\nexport interface Interpreter<M> {\n  readonly run: (cmd: Command<M>) => void;\n  /** Aborts the running task of `lane`, if any (subscriptions.ts: a subscription that left). */\n  readonly cancel: (lane: string) => 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/**\n * Reports a failure to the owner (ADR 0024): `40` a mapper threw, `41` a driver failed and the\n * command has no `onFailure`, `43` nothing provides a driver token. The owner builds the message\n * and reports it.\n */\nexport type CommandFailure = (cause: unknown, code: 40 | 41 | 43, driver: string) => void;\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/** Runs the driver once; an abort settles it at once, even if the driver ignores the signal. */\nconst attempt = (\n  driver: AnyDriver,\n  cmd: Command<unknown>,\n  signal: AbortSignal,\n  emit: (output: unknown) => void,\n): Promise<unknown> =>\n  // The input type was erased by command(); it was built for this driver's name.\n  Promise.race([\n    Promise.resolve(driver.run(cmd.input as never, { signal, emit })),\n    aborted(signal),\n  ]);\n\n/**\n * Maps a result to a message and dispatches it. A throwing mapper is reported (ADR 0024) and\n * sends nothing; the reducer's own failures are the owner's (dispatch reports them).\n */\nconst deliver = <M>(\n  map: () => M | undefined,\n  dispatch: (msg: M) => void,\n  failed: CommandFailure,\n  driver: string,\n): void => {\n  let msg: M | undefined;\n  try {\n    msg = map();\n  } catch (defect) {\n    failed(defect, 40, driver);\n    return;\n  }\n  if (msg !== undefined) dispatch(msg);\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  failed: CommandFailure,\n): Promise<void> {\n  let settled = false;\n  const name = driver.name;\n  const emit = (output: unknown): void => {\n    if (!settled && !signal.aborted) deliver(() => cmd.onSuccess(output), dispatch, failed, name);\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 attempt(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      failed(error, 41, name);\n      return;\n    }\n    const onFailure = cmd.onFailure;\n    deliver(() => onFailure(error), dispatch, failed, name);\n    return;\n  }\n  if (signal.aborted) return;\n  settled = true;\n  if (DEVTOOLS_ENABLED) report?.('settled', output);\n  deliver(() => cmd.onSuccess(output), dispatch, failed, name);\n}\n\nexport function makeInterpreter<M>(\n  resolve: (driver: AnyDriver) => AnyDriver,\n  dispatch: (msg: M) => void,\n  trace: CommandTrace | undefined,\n  failed: CommandFailure,\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, failed);\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    if (driver.run === unprovided) {\n      failed(undefined, 43, driver.name);\n      return;\n    }\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 cancel = (lane: string): void => {\n    lanes.get(lane)?.controller.abort();\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, cancel, dispose };\n}\n\n/**\n * A component's interpreter (registered by `command()`, features.ts). Drivers resolve by name:\n * el.drivers → nearest provider → the command's own (gyral-czi.35; ADR 0006 \"Driver tokens\").\n */\nexport const hostInterpreter = <M>(\n  el: FeatureHost,\n  dispatch: (msg: M) => void,\n  trace: CommandTrace | undefined,\n  failed: CommandFailure,\n): Interpreter<M> =>\n  makeInterpreter(\n    (driver) => el.drivers[driver.name] ?? providedDriver(el, driver.name) ?? driver,\n    dispatch,\n    trace,\n    failed,\n  );\n"]}

package/dist/internal/token.d.ts

@@ -0,0 +1 @@
+export declare function unprovided(): never;

package/dist/internal/token.js

@@ -0,0 +1,7 @@
+// The `run` of a driver token (defineDriver('name'), ADR 0006 "Driver tokens"). The interpreter
+// recognises it and reports G0043 instead of running it; called directly, it throws.
+import { DEV } from '#view-dev';
+export function unprovided() {
+    throw new Error(DEV ? 'gyral: this driver is a token; provide an implementation by name' : '');
+}
+//# sourceMappingURL=token.js.map

package/dist/internal/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/internal/token.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,qFAAqF;AACrF,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,kEAAkE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACjG,CAAC","sourcesContent":["// The `run` of a driver token (defineDriver('name'), ADR 0006 \"Driver tokens\"). The interpreter\n// recognises it and reports G0043 instead of running it; called directly, it throws.\nimport { DEV } from '#view-dev';\n\nexport function unprovided(): never {\n  throw new Error(DEV ? 'gyral: this driver is a token; provide an implementation by name' : '');\n}\n"]}

package/dist/internal.d.ts

@@ -0,0 +1,20 @@
+export { STORE_SEND } from './store.js';
+export type { StoreSendInput } from './store.js';
+export { scriptSafeJson } from './script-json.js';
+export { STORE_SEED_ATTRIBUTE } from './store-scope.js';
+export { warnJsonHazard } from './json-safety.js';
+export { intentRejectedSchema, isSecretField } from './forms.js';
+export { runInit } from './init.js';
+export { ISLAND_ATTRIBUTE } from './islands.js';
+export { DEVTOOLS_ENABLED as devtoolsEnabled, devLiveComponents as devtoolsLiveComponents, } from '#devtools';
+export { HEAD_ATTRIBUTE, headEntries } from './head.js';
+export type { HeadEntry } from './head.js';
+export { emit } from './children.js';
+export { invokersSupported } from './invokers.js';
+export { resetDocumentStores, STORES_ELEMENT } from './store-scope.js';
+export { DRIVERS_ELEMENT } from './drivers-scope.js';
+export { jsonHazard } from './json-safety.js';
+export { LIGHT_ATTRIBUTE } from './light-dom.js';
+export { HydrationMismatch } from './view/index.js';
+export { DEVTOOLS_GLOBAL } from './devtools-events.js';
+export type { CommandPhase, CommandTraceEvent, DevComponentRef, DevEvent, DevtoolsHook, } from './devtools-events.js';

package/dist/internal.js

@@ -0,0 +1,22 @@
+// `@gyral/core/internal`: what Gyral's own packages (@gyral/router, @gyral/ssr, @gyral/testing,
+// @gyral/http, @gyral/devtools) share with core. INTERNAL: not part of Gyral's public API and
+// not covered by semver; any release may change or remove these. Apps import from `@gyral/core`
+// (docs/references/public-api-0.3.1.md).
+export { STORE_SEND } from './store.js';
+export { scriptSafeJson } from './script-json.js';
+export { STORE_SEED_ATTRIBUTE } from './store-scope.js';
+export { warnJsonHazard } from './json-safety.js';
+export { intentRejectedSchema, isSecretField } from './forms.js';
+export { runInit } from './init.js';
+export { ISLAND_ATTRIBUTE } from './islands.js';
+export { DEVTOOLS_ENABLED as devtoolsEnabled, devLiveComponents as devtoolsLiveComponents, } from '#devtools';
+export { HEAD_ATTRIBUTE, headEntries } from './head.js';
+export { emit } from './children.js';
+export { invokersSupported } from './invokers.js';
+export { resetDocumentStores, STORES_ELEMENT } from './store-scope.js';
+export { DRIVERS_ELEMENT } from './drivers-scope.js';
+export { jsonHazard } from './json-safety.js';
+export { LIGHT_ATTRIBUTE } from './light-dom.js';
+export { HydrationMismatch } from './view/index.js';
+export { DEVTOOLS_GLOBAL } from './devtools-events.js';
+//# sourceMappingURL=internal.js.map

package/dist/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,8FAA8F;AAC9F,gGAAgG;AAChG,yCAAyC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,gBAAgB,IAAI,eAAe,EACnC,iBAAiB,IAAI,sBAAsB,GAC5C,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC","sourcesContent":["// `@gyral/core/internal`: what Gyral's own packages (@gyral/router, @gyral/ssr, @gyral/testing,\n// @gyral/http, @gyral/devtools) share with core. INTERNAL: not part of Gyral's public API and\n// not covered by semver; any release may change or remove these. Apps import from `@gyral/core`\n// (docs/references/public-api-0.3.1.md).\nexport { STORE_SEND } from './store.js';\nexport type { StoreSendInput } from './store.js';\nexport { scriptSafeJson } from './script-json.js';\nexport { STORE_SEED_ATTRIBUTE } from './store-scope.js';\nexport { warnJsonHazard } from './json-safety.js';\nexport { intentRejectedSchema, isSecretField } from './forms.js';\nexport { runInit } from './init.js';\nexport { ISLAND_ATTRIBUTE } from './islands.js';\nexport {\n  DEVTOOLS_ENABLED as devtoolsEnabled,\n  devLiveComponents as devtoolsLiveComponents,\n} from '#devtools';\nexport { HEAD_ATTRIBUTE, headEntries } from './head.js';\nexport type { HeadEntry } from './head.js';\nexport { emit } from './children.js';\nexport { invokersSupported } from './invokers.js';\nexport { resetDocumentStores, STORES_ELEMENT } from './store-scope.js';\nexport { DRIVERS_ELEMENT } from './drivers-scope.js';\nexport { jsonHazard } from './json-safety.js';\nexport { LIGHT_ATTRIBUTE } from './light-dom.js';\nexport { HydrationMismatch } from './view/index.js';\nexport { DEVTOOLS_GLOBAL } from './devtools-events.js';\nexport type {\n  CommandPhase,\n  CommandTraceEvent,\n  DevComponentRef,\n  DevEvent,\n  DevtoolsHook,\n} from './devtools-events.js';\n"]}

package/dist/invoker-fallback-used.d.ts

@@ -0,0 +1,4 @@
+/** Loads the fallback for `root`, when the build registered it. */
+export declare const loadInvokerShim: (root: Node) => void;
+/** Turns the fallback on (use-invokers.ts). */
+export declare const useInvokerShim: (load: (root: Node) => void) => void;

package/dist/invoker-fallback-used.js

@@ -0,0 +1,10 @@
+let loader;
+/** Loads the fallback for `root`, when the build registered it. */
+export const loadInvokerShim = ((root) => {
+    loader?.(root);
+});
+/** Turns the fallback on (use-invokers.ts). */
+export const useInvokerShim = ((load) => {
+    loader = load;
+});
+//# sourceMappingURL=invoker-fallback-used.js.map

package/dist/invoker-fallback-used.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoker-fallback-used.js","sourceRoot":"","sources":["../src/invoker-fallback-used.ts"],"names":[],"mappings":"AAQA,IAAI,MAA0C,CAAC;AAE/C,mEAAmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAU,EAAQ,EAAE;IACnD,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;AACjB,CAAC,CAA2C,CAAC;AAE7C,+CAA+C;AAC/C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,IAA0B,EAAQ,EAAE;IAClE,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC,CAA0C,CAAC","sourcesContent":["// `#invoker-fallback` in production client-only builds (gyral-c5d.11, view/05-element.md\n// \"Intent events\"): the fallback's loader (invoker-fallback.ts and its import()) arrives only\n// through `useInvokerShim`, called by use-invokers.ts, which the preset's client-only plugin\n// adds to the build when a module may make a root listen for `command` (compiler/features.ts).\n// Without it the module isn't in the build's graph at all, so neither is the shim's chunk or,\n// with no other import(), Vite's preload helper. Development resolves invoker-fallback.ts.\nimport type * as Fallback from './invoker-fallback.js';\n\nlet loader: ((root: Node) => void) | undefined;\n\n/** Loads the fallback for `root`, when the build registered it. */\nexport const loadInvokerShim = ((root: Node): void => {\n  loader?.(root);\n}) satisfies typeof Fallback.loadInvokerShim;\n\n/** Turns the fallback on (use-invokers.ts). */\nexport const useInvokerShim = ((load: (root: Node) => void): void => {\n  loader = load;\n}) satisfies typeof Fallback.useInvokerShim;\n"]}

package/dist/invoker-fallback.d.ts

@@ -0,0 +1,4 @@
+/** Loads the fallback for `root` (once per root; the shim module loads once). */
+export declare function loadInvokerShim(root: Node): void;
+/** Registration (use-invokers.ts) is for client-only builds; here the fallback is always on. */
+export declare const useInvokerShim: (load: (root: Node) => void) => void;

package/dist/invoker-fallback.js

@@ -0,0 +1,15 @@
+// Loading the invoker-command fallback (invokers-shim.ts, ADR 0003 tier 3), core's
+// `#invoker-fallback`: a root that listens for `command` intents in a browser without
+// `CommandEvent` loads it with import() (intent.ts); settled() waits. Production client-only
+// builds resolve `#invoker-fallback` to invoker-fallback-used.ts, which reaches this module only
+// when the build saw command intents (use-invokers.ts, gyral-c5d.11).
+import { hold } from './scheduler.js';
+/** Loads the fallback for `root` (once per root; the shim module loads once). */
+export function loadInvokerShim(root) {
+    hold(import('./invokers-shim.js').then((shim) => {
+        shim.shimInvokers(root);
+    }, reportError));
+}
+/** Registration (use-invokers.ts) is for client-only builds; here the fallback is always on. */
+export const useInvokerShim = () => undefined;
+//# sourceMappingURL=invoker-fallback.js.map

package/dist/invoker-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoker-fallback.js","sourceRoot":"","sources":["../src/invoker-fallback.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,sFAAsF;AACtF,6FAA6F;AAC7F,iGAAiG;AACjG,sEAAsE;AACtE,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,IAAU;IACxC,IAAI,CACF,MAAM,CAAC,oBAAoB,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QACzC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC,EAAE,WAAW,CAAC,CAChB,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,CAAC,MAAM,cAAc,GAAyC,GAAG,EAAE,CAAC,SAAS,CAAC","sourcesContent":["// Loading the invoker-command fallback (invokers-shim.ts, ADR 0003 tier 3), core's\n// `#invoker-fallback`: a root that listens for `command` intents in a browser without\n// `CommandEvent` loads it with import() (intent.ts); settled() waits. Production client-only\n// builds resolve `#invoker-fallback` to invoker-fallback-used.ts, which reaches this module only\n// when the build saw command intents (use-invokers.ts, gyral-c5d.11).\nimport { hold } from './scheduler.js';\n\n/** Loads the fallback for `root` (once per root; the shim module loads once). */\nexport function loadInvokerShim(root: Node): void {\n  hold(\n    import('./invokers-shim.js').then((shim) => {\n      shim.shimInvokers(root);\n    }, reportError),\n  );\n}\n\n/** Registration (use-invokers.ts) is for client-only builds; here the fallback is always on. */\nexport const useInvokerShim: (load: (root: Node) => void) => void = () => undefined;\n"]}

package/dist/light-dom.d.ts

@@ -1,5 +1,5 @@
 interface SpecLike {
-    readonly shadow?: boolean;
+    readonly shadow?: unknown;
 }
 export declare const isLight: (spec: SpecLike) => boolean;
 /** Is this class a light-DOM Gyral component (`shadow: false`)? */

package/dist/light-dom.js.map

@@ -1 +1 @@
-{"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"]}
+{"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

@@ -6,12 +6,20 @@ 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;
+    /**
+     * 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;
 }
@@ -24,7 +32,11 @@ interface Common {
     readonly attribute?: string | false;
 }
 type Schema<O> = StandardSchemaV1<unknown, O>;
-type Out<S extends StandardSchemaV1> = StandardSchemaV1.InferOutput<S>;
+/** 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;
@@ -44,9 +56,13 @@ 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 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>;
+    <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: {
@@ -58,9 +74,16 @@ export declare const prop: {
     readonly boolean: <O extends boolean = boolean>(opts?: Refined<O> & {
         readonly default?: NoInfer<O>;
     }) => Prop<O>;
-    /** Attribute parsed with `JSON.parse`, then the schema. */
+    /**
+     * 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. */
+    /**
+     * 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 {};