@shenora/react 0.11.0 → 0.13.0

package/dist/store.js

@@ -1,55 +1,74 @@
 import { useCallback, useDebugValue, useRef, useSyncExternalStore } from 'react';
 import { getBridge } from './bridge.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
-/** Inputs for {@link createShenoraStore}. */
 /**
  * Is the fresh selector result the same VALUE as the previous one, for re-render purposes?
  *
  * `Object.is` plus ONE level of own-key comparison. The shallow step is what lets an inline selector
  * that derives a new object work — `s => ({ count: s.lines.length })` builds a different object every
- * call, and without this every call would look like a change and loop.
- *
- * ⚠ Deliberately one level. Deep equality would make an unchanged NESTED value hide a changed outer
- * one only by cost, and a store whose selectors need deep comparison is selecting too much.
+ * call, and without it every call would look like a change and loop.
  */
 function equivalent(a, b) {
     if (Object.is(a, b))
         return true;
     if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
         return false;
-    // Arrays and plain objects only — anything exotic (Map, Date, a class) falls back to identity above.
-    if (Array.isArray(a) !== Array.isArray(b))
+    // Two different classes are never the same value, and this also separates an array from a bag.
+    const proto = Object.getPrototypeOf(a);
+    if (proto !== Object.getPrototypeOf(b))
         return false;
+    // 🔴 A Date, a Set and a Map keep their contents in INTERNAL SLOTS, so `Object.keys` is `[]` for every
+    // one of them — the key compare below then reports two of different contents EQUAL, which pinned such
+    // a selector to its first value for the component's life. Silent: the early return also skips the cache
+    // refresh, so it never self-corrects. These three answer for themselves.
+    if (a instanceof Date)
+        return Object.is(a.getTime(), b.getTime());
+    if (a instanceof Set) {
+        const setB = b;
+        if (a.size !== setB.size)
+            return false;
+        for (const value of a)
+            if (!setB.has(value))
+                return false;
+        return true;
+    }
+    if (a instanceof Map) {
+        const mapB = b;
+        if (a.size !== mapB.size)
+            return false;
+        for (const [key, value] of a) {
+            if (!mapB.has(key) || !Object.is(mapB.get(key), value))
+                return false;
+        }
+        return true;
+    }
     const aKeys = Object.keys(a);
-    const bKeys = Object.keys(b);
-    if (aKeys.length !== bKeys.length)
+    if (aKeys.length !== Object.keys(b).length)
+        return false;
+    // ⚠ ZERO own keys on anything else exotic — a RegExp, a Promise, a class whose state is all private —
+    // means this compare learned NOTHING, so it must not answer "equal". A plain bag or an array genuinely
+    // IS empty. Class instances carrying own fields still compare shallowly, which is why the gate is on
+    // emptiness rather than on being a plain object: rejecting those would trade a stale render for
+    // React's "getSnapshot should be cached" loop.
+    if (aKeys.length === 0 && !Array.isArray(a) && proto !== Object.prototype && proto !== null)
         return false;
     return aKeys.every((k) => Object.prototype.hasOwnProperty.call(b, k)
         && Object.is(a[k], b[k]));
 }
 /**
- * A store fed by one module's host event stream, shared by every component that reads it.
- *
- * This is the shape a desktop app needs and the one three sibling apps each hand-built before it
- * existed here — see `.claude/knowledge/generic-library.md`'s worked example for that survey. It exists
- * because status- and progress-driven UI is inherently MANY-WATCHERS: a full panel and a compact
- * progress strip want the same live state, and without a shared store each re-implements the wiring,
- * each opens its own subscription, and each starts empty.
+ * A store fed by one module's host event stream, shared by every component that reads it — for the
+ * status- and progress-driven UI that is inherently many-watchers, where a full panel and a compact
+ * progress strip want the same live state.
  *
  * What it guarantees:
  * - **One subscription per event type, however many components read it.** Mounting N components does
  *   not open N subscriptions; unmounting the last one tears them down.
  * - **A late mounter sees current state**, via {@link ShenoraStoreOptions.snapshot} on the first
- *   subscription. This is the part that cannot be retrofitted by subscribing harder.
- * - **No state library.** Built on React's `useSyncExternalStore`, which exists for exactly this and
- *   is tearing-free under concurrent rendering. The kit imposes no store dependency (D13's spirit —
- *   apps bring their own); every sibling reached for the same one, and baking that in would have been
- *   solving their stack rather than their problem.
- * - **Reducers are PURE and isolated**: they take state + payload and return state, so a store is
- *   testable with no bridge, and a throwing reducer is reported rather than corrupting shared state.
- *
- * Headless (D13/D21): the kit ships the MECHANISM. What an operation is — its phases, its progress
- * shape, whether it queues — stays in the app; there is deliberately no job/queue/progress type here.
+ *   subscription.
+ * - **No state library.** Built on React's `useSyncExternalStore`, so it is tearing-free under
+ *   concurrent rendering and imposes no store dependency on the app.
+ * - **Reducers are PURE and isolated**: state + payload in, state out, so a store is testable with no
+ *   bridge and a throwing reducer is reported rather than corrupting shared state.
  *
  * @example
  * const useDeploy = createShenoraStore('DEPLOY', {
@@ -73,8 +92,8 @@ export function createShenoraStore(module, options) {
     let state = initial;
     let snapshotLoaded = false;
     // Bumped on detach. A snapshot response from an earlier subscriber epoch resolving late must be
-    // DROPPED: the current epoch has (or will have) its own, fresher request, and applying the old
-    // body after the new one is a lost update wearing a success path.
+    // DROPPED — the current epoch has its own fresher request, and applying the old body over the new
+    // one is a lost update wearing a success path.
     let snapshotEpoch = 0;
     const listeners = new Set();
     let unsubscribes = [];
@@ -95,16 +114,15 @@ export function createShenoraStore(module, options) {
             setState(reduce(state, event.payload, event));
         }
         catch (error) {
-            // A throwing reducer must not corrupt shared state or break the other subscribers — the same
-            // guarded-callback rule the host applies to app code (Shenora.AppCallback).
+            // A throwing reducer must not corrupt shared state or break the other subscribers.
             report(error, { module, type });
         }
     };
     const loadSnapshot = () => {
         if (!snapshot || snapshotLoaded)
             return;
-        snapshotLoaded = true; // set BEFORE awaiting: two components mounting in the same tick must not
-        // both fire the request (React StrictMode double-invokes effects, which is precisely this case).
+        snapshotLoaded = true; // set BEFORE awaiting: two components mounting in the same tick (React
+        // StrictMode double-invokes effects) must not both fire the request.
         const epoch = snapshotEpoch;
         bridge()
             .invoke(module, snapshot.type, { payload: snapshot.payload, scope })
@@ -120,8 +138,8 @@ export function createShenoraStore(module, options) {
         }, (error) => {
             if (epoch !== snapshotEpoch)
                 return;
-            // Allow a later retry: a snapshot that failed because the host was not ready yet should not
-            // leave the store permanently empty for the rest of the session.
+            // Allow a later retry: a snapshot that failed because the host was not ready yet must not
+            // leave the store permanently empty.
             snapshotLoaded = false;
             report(error, { module, type: snapshot.type });
         });
@@ -134,17 +152,15 @@ export function createShenoraStore(module, options) {
         for (const off of unsubscribes)
             off();
         unsubscribes = [];
-        // The next mount must RE-LOAD: with no bus subscription live, everything the host emits from
-        // here on is missed, so the snapshot the flag was guarding is stale the moment this returns.
-        // The flag exists to dedupe same-tick double-mounts (StrictMode), not to span subscriber epochs —
-        // and the epoch bump orphans any request still in flight, so its late answer cannot clobber the
-        // next epoch's fresher one.
+        // The next mount must RE-LOAD: with no bus subscription live, everything the host emits from here
+        // on is missed, so the snapshot the flag was guarding is stale the moment this returns. The epoch
+        // bump orphans any request still in flight, so its late answer cannot clobber the next one.
         snapshotLoaded = false;
         snapshotEpoch++;
     };
     const subscribe = (listener) => {
-        // ONE subscription per event type for the whole store — the property that makes this worth
-        // existing. The first listener attaches; the last one to leave detaches.
+        // ONE subscription per event type for the whole store: the first listener attaches, the last one
+        // to leave detaches.
         if (listeners.size === 0)
             attach();
         listeners.add(listener);
@@ -164,26 +180,14 @@ export function createShenoraStore(module, options) {
     /**
      * Subscribe to the store, optionally through a selector.
      *
-     * 🔴 **The selector is RE-RUN every time and the previous RESULT is reused when equivalent.** It used
-     * to be memoized against STATE identity alone, which looked like the careful thing and was wrong: a
-     * selector whose closure changed while the state did not returned the PREVIOUS selector's value. A
-     * list row doing `useShenoraRequests(s => s.byId[id])` whose `id` prop changes — virtualised reuse, a
-     * route change — rendered the previous row's data until some unrelated event replaced the state.
-     *
-     * ⚠ <b>Two requirements pull against each other and both are met by comparing RESULTS rather than
-     * inputs.</b> `useSyncExternalStore` re-renders whenever `getSnapshot` returns something new by
-     * `Object.is`, so:
-     * <list type="bullet">
-     * <item>keying the cache on STATE alone gives stale values when the selector changes — the bug above;</item>
-     * <item>keying it on the SELECTOR too loops forever for an inline selector that derives a new object
-     * (`s => ({ count: s.lines.length })`) — a fresh identity each render, a fresh object each call.
-     * zustand v5 has exactly that behaviour and answers it with an opt-in `useShallow`.</item>
-     * </list>
-     * Comparing the RESULT shallowly gives both: a derived object that is field-for-field the same reuses
-     * the previous reference and does not re-render, while a genuinely different row does.
+     * 🔴 **The selector is RE-RUN every time and the previous RESULT is reused when equivalent** — never
+     * cached against the state or the selector, both of which fail silently. Keying on STATE alone
+     * returns the PREVIOUS selector's value when the closure changes (a list row doing
+     * `s => s.byId[id]` whose `id` prop changes renders the previous row's data); keying on the SELECTOR
+     * too loops forever for an inline selector that derives a new object (`s => ({ n: s.lines.length })`).
      */
     function useStore(selector) {
-        // The last result handed to React. Reused whenever the fresh one is equivalent, which is what keeps
+        // The last result handed to React, reused whenever the fresh one is equivalent — what keeps
         // getSnapshot stable without pinning it to an input that can go stale.
         const previous = useRef(null);
         const getSelected = useCallback(() => {

package/dist/transport.d.ts

@@ -10,14 +10,9 @@ export interface ShenoraTransport {
     subscribe(listener: (message: string) => void): () => void;
 }
 /**
- * True when running inside ANY Shenora host — a WebView2 desktop shell or a MAUI
- * `HybridWebView` — i.e. when a transport to the host exists. In a plain browser this is false and
- * callers should fall back to browser-only behavior.
- *
- * It used to test WebView2 alone, which answered FALSE on the MAUI shell: an app would have
- * concluded it was in a plain browser tab while a perfectly good host sat on the other side of the
- * channel. Widened when the second shell arrived — the question this function is asked is "is there
- * a host", never "is it WebView2".
+ * True when running inside ANY Shenora host — a WebView2 desktop shell or a MAUI `HybridWebView` — i.e.
+ * when a transport to the host exists. In a plain browser this is false and callers should fall back to
+ * browser-only behavior. The question is "is there a host", never "is it WebView2".
  */
 export declare function isShenoraAvailable(): boolean;
 /** The WebView2 postMessage transport, or null outside a WebView2 host. */
@@ -25,20 +20,16 @@ export declare function createWebView2Transport(): ShenoraTransport | null;
 /**
  * The MAUI `HybridWebView` transport, or null outside a MAUI host.
  *
- * Asymmetric by the platform's design, which is the only thing interesting here: sending goes
- * through `window.HybridWebView.SendRawMessage`, while receiving is a `HybridWebViewMessageReceived`
- * CustomEvent dispatched on `window`. Both directions carry the same JSON envelopes the desktop
- * shell speaks — the host side is `Shenora.Maui.MauiIpcBridge`, and the envelope itself never
- * changed, which is the whole point of the transport seam (D16).
+ * Asymmetric by the platform's design: sending goes through `window.HybridWebView.SendRawMessage`,
+ * while receiving is a `HybridWebViewMessageReceived` CustomEvent dispatched on `window`. Both
+ * directions carry the same JSON envelopes the desktop shell speaks; the host side is
+ * `Shenora.Maui.MauiIpcBridge`.
  */
 export declare function createHybridWebViewTransport(): ShenoraTransport | null;
 /**
  * The transport for whichever Shenora host this page is running in, or null in a plain browser.
  * This is what the bridge uses by default, so an app that simply calls `invoke`/`post` works on the
- * desktop shell and the MAUI shell without knowing which one it is.
- *
- * WebView2 is probed FIRST for no deeper reason than that it is the older shell and a page can only
- * ever be in one of them; if both objects were somehow present, preferring the one the desktop host
- * injects keeps existing behaviour byte-identical.
+ * desktop shell and the MAUI shell without knowing which one it is. A page is only ever in one of
+ * them; WebView2 wins if both objects are somehow present.
  */
 export declare function createHostTransport(): ShenoraTransport | null;

package/dist/transport.js

@@ -1,13 +1,8 @@
 const webViewWindow = () => typeof window === 'undefined' ? undefined : window;
 /**
- * True when running inside ANY Shenora host — a WebView2 desktop shell or a MAUI
- * `HybridWebView` — i.e. when a transport to the host exists. In a plain browser this is false and
- * callers should fall back to browser-only behavior.
- *
- * It used to test WebView2 alone, which answered FALSE on the MAUI shell: an app would have
- * concluded it was in a plain browser tab while a perfectly good host sat on the other side of the
- * channel. Widened when the second shell arrived — the question this function is asked is "is there
- * a host", never "is it WebView2".
+ * True when running inside ANY Shenora host — a WebView2 desktop shell or a MAUI `HybridWebView` — i.e.
+ * when a transport to the host exists. In a plain browser this is false and callers should fall back to
+ * browser-only behavior. The question is "is there a host", never "is it WebView2".
  */
 export function isShenoraAvailable() {
     const host = webViewWindow();
@@ -34,11 +29,10 @@ export function createWebView2Transport() {
 /**
  * The MAUI `HybridWebView` transport, or null outside a MAUI host.
  *
- * Asymmetric by the platform's design, which is the only thing interesting here: sending goes
- * through `window.HybridWebView.SendRawMessage`, while receiving is a `HybridWebViewMessageReceived`
- * CustomEvent dispatched on `window`. Both directions carry the same JSON envelopes the desktop
- * shell speaks — the host side is `Shenora.Maui.MauiIpcBridge`, and the envelope itself never
- * changed, which is the whole point of the transport seam (D16).
+ * Asymmetric by the platform's design: sending goes through `window.HybridWebView.SendRawMessage`,
+ * while receiving is a `HybridWebViewMessageReceived` CustomEvent dispatched on `window`. Both
+ * directions carry the same JSON envelopes the desktop shell speaks; the host side is
+ * `Shenora.Maui.MauiIpcBridge`.
  */
 export function createHybridWebViewTransport() {
     const host = webViewWindow();
@@ -64,11 +58,8 @@ export function createHybridWebViewTransport() {
 /**
  * The transport for whichever Shenora host this page is running in, or null in a plain browser.
  * This is what the bridge uses by default, so an app that simply calls `invoke`/`post` works on the
- * desktop shell and the MAUI shell without knowing which one it is.
- *
- * WebView2 is probed FIRST for no deeper reason than that it is the older shell and a page can only
- * ever be in one of them; if both objects were somehow present, preferring the one the desktop host
- * injects keeps existing behaviour byte-identical.
+ * desktop shell and the MAUI shell without knowing which one it is. A page is only ever in one of
+ * them; WebView2 wins if both objects are somehow present.
  */
 export function createHostTransport() {
     return createWebView2Transport() ?? createHybridWebViewTransport();

package/dist/types.d.ts

@@ -22,48 +22,33 @@ export declare const HANDSHAKE_TYPE = "READY";
 export declare const IpcErrorCodes: {
     readonly unknownError: "UNKNOWN_ERROR";
     /**
-     * **No MODULE claimed the request** — nothing on the host answers that name. Parameters:
-     * `module`, `type`.
+     * **No MODULE claimed the request** — nothing host-side answers that name, i.e. the module was never
+     * registered. Parameters: `module`, `type`.
      *
-     * ⚠ Distinct from {@link noRoute}, and the split is what makes it actionable: this means the module
-     * was never registered host-side, while `noRoute` means it WAS and does not know that type. Opposite
-     * fixes — wire the module up, versus correct a route name — so collapsing both into `NO_HANDLER` with
-     * identical parameters leaves a dead page undiagnosable from the wire.
+     * ⚠ Distinct from {@link noRoute}, and opposite fixes: wire the module up, versus correct a route name.
      */
     readonly noHandler: "NO_HANDLER";
     /**
-     * **The module answered but has no route of that type.** Parameters: `module`, `type`.
-     *
-     * Seeing this is proof the module IS registered and mapped, which is exactly what {@link noHandler}
-     * cannot tell you — so this is a route-name problem, not a composition problem.
+     * **The module answered but has no route of that type** — so it IS registered, and this is a
+     * route-name problem. Parameters: `module`, `type`.
      */
     readonly noRoute: "NO_ROUTE";
-    /**
-     * A scope-routed module was called without a `scope`. Parameters: `module`.
-     *
-     * This was MISSING here while the host emitted it (P5.5 H6), so a scoped app could not match it by
-     * constant and had to hard-code the string — against documentation claiming the two sides mirror
-     * name-for-name. The mirror is now enforced by a test rather than by care.
-     */
+    /** A scope-routed module was called without a `scope`. Parameters: `module`. */
     readonly scopeRequired: "SCOPE_REQUIRED";
     readonly missingPayloadValue: "MISSING_PAYLOAD_VALUE";
     readonly invalidPayloadValue: "INVALID_PAYLOAD_VALUE";
     /**
      * The operation was cancelled — a NORMAL outcome, not a fault. Treat it as "show nothing": it is the
-     * one failure a UI should stay silent about. Previously indistinguishable from `UNKNOWN_ERROR`.
+     * one failure a UI should stay silent about.
      */
     readonly operationCancelled: "OPERATION_CANCELLED";
     /**
      * The shell has NO EXPRESSION of what was asked for — not a fault, and not something a retry fixes.
-     * Parameters: `capability` (a {@link ShellCapabilities} value).
-     *
-     * Treat it like `operationCancelled`: do not show a fault. The right response is to hide the control,
-     * because the capability is absent by design on that platform (a folder picker on a phone, for
-     * instance) rather than broken.
+     * Parameters: `capability` (a {@link ShellCapabilities} value). Hide the control rather than showing
+     * an error: the capability is absent by design on that platform, not broken.
      *
-     * ⚠ A page should not normally NEED this. The ready handshake advertises `ShellInfo.capabilities`
-     * precisely so one bundle can decide BEFORE it asks — `useFileDialogs().canPickFolder` is the
-     * intended path. This is the honest answer when a page asks anyway.
+     * ⚠ A page should not normally NEED this. The ready handshake advertises `ShellInfo.capabilities` so
+     * one bundle can decide BEFORE it asks — `useFileDialogs().canPickFolder` is the intended path.
      */
     readonly capabilityNotSupported: "CAPABILITY_NOT_SUPPORTED";
     /** Client-only: the request timed out waiting for a response. */
@@ -73,8 +58,7 @@ export declare const IpcErrorCodes: {
 };
 /**
  * The codes that exist ONLY on the client — they never arrive from the host, but reject through the same
- * structured shape so app error handling stays uniform. Named here so the cross-language mirror check can
- * exclude them by intent rather than by a hard-coded list on the other side.
+ * structured shape. Named here so the cross-language mirror check excludes them by intent.
  */
 export declare const ClientOnlyIpcErrorCodes: readonly string[];
 /** The request envelope a client sends to the host. */
@@ -101,20 +85,8 @@ export interface IpcError {
 }
 /**
  * What the host is and what it can do — the handshake's response data (mirror of the host's
- * `ShellInfo`).
- *
- * This is what lets ONE page ship to every shell. Render on the data rather than sniffing the
- * platform:
- *
- * ```tsx
- * const shell = useShellInfo();
- * return <>{shell?.capabilities.includes(ShellCapabilities.windowChrome) && <TitleBar />}</>;
- * ```
- *
- * A desktop shell that draws its own chrome advertises `windowChrome` and `dropZones`; a mobile one
- * has neither, and the same bundle renders correctly on both. Undefined means no host said
- * anything — a plain browser tab, or a host predating this — so treat absent as "assume nothing",
- * never as "assume desktop".
+ * `ShellInfo`), and what lets ONE page ship to every shell. Read it with `useShellInfo`, whose docs
+ * carry the rule for an absent one.
  */
 export interface ShellInfo {
     /** Short host identifier, for diagnostics (`"winforms"`, `"maui"`). Never branch on this — branch on the capabilities. */
@@ -136,24 +108,19 @@ export declare const ShellCapabilities: {
     readonly tray: "tray";
     /**
      * The host can put a FILE LIST on the clipboard, so the user can paste into Explorer, Finder or a
-     * file manager. No web API expresses this, and a phone's pasteboard has none — so it is the one part
-     * of the clipboard worth branching on.
+     * file manager. No web API expresses this, so it is the one part of the clipboard worth branching on.
      *
      * ⚠ It says nothing about the rest: text and bytes work everywhere, and the gesture-driven half is
-     * `navigator.clipboard`'s job, not the host's.
+     * `navigator.clipboard`'s job.
      */
     readonly clipboardFiles: "clipboardFiles";
     /**
-     * The host can serve LOCAL FILES to this page — media, images, documents, exports — through its resource
-     * interceptor. Pair it with {@link mediaUrl}.
-     *
-     * A page cannot reach a local file itself on any shell (`file://` is blocked from a virtual-host origin,
-     * and would be the wrong answer anyway), so branch on this and fall back rather than rendering a player
-     * that can never load.
+     * The host can serve LOCAL FILES to this page — media, images, documents, exports — through its
+     * resource interceptor. Pair it with `mediaUrl`.
      *
-     * ⚠ It says the host CAN serve, not what: routes, payload shape and allowed roots are the app's. And it
-     * deliberately tells you nothing about the URL SCHEME — {@link mediaUrl} is relative precisely so each
-     * shell supplies its own, and knowing it would put you back to branching on platform.
+     * ⚠ A page cannot reach a local file itself on any shell, so branch on this and fall back rather than
+     * rendering a player that can never load. It says the host CAN serve, not what: routes, payload shape
+     * and allowed roots are the app's, and it says nothing about the URL SCHEME.
      */
     readonly localFiles: "localFiles";
 };
@@ -184,9 +151,8 @@ export interface IpcNotificationBatch {
     timestamp: string;
 }
 /**
- * A client-side event on the event bus — an unbundled {@link IpcNotification} (or a locally
- * emitted event; the host-side `EventMessage` additionally carries id/timestamp, which don't
- * cross the wire).
+ * A client-side event on the event bus — an unbundled {@link IpcNotification}, or a locally emitted
+ * event. The host-side `EventMessage` additionally carries id/timestamp, which don't cross the wire.
  */
 export interface EventMessage<TPayload = unknown> {
     module: string;

package/dist/types.js

@@ -22,48 +22,33 @@ export const HANDSHAKE_TYPE = 'READY';
 export const IpcErrorCodes = {
     unknownError: 'UNKNOWN_ERROR',
     /**
-     * **No MODULE claimed the request** — nothing on the host answers that name. Parameters:
-     * `module`, `type`.
+     * **No MODULE claimed the request** — nothing host-side answers that name, i.e. the module was never
+     * registered. Parameters: `module`, `type`.
      *
-     * ⚠ Distinct from {@link noRoute}, and the split is what makes it actionable: this means the module
-     * was never registered host-side, while `noRoute` means it WAS and does not know that type. Opposite
-     * fixes — wire the module up, versus correct a route name — so collapsing both into `NO_HANDLER` with
-     * identical parameters leaves a dead page undiagnosable from the wire.
+     * ⚠ Distinct from {@link noRoute}, and opposite fixes: wire the module up, versus correct a route name.
      */
     noHandler: 'NO_HANDLER',
     /**
-     * **The module answered but has no route of that type.** Parameters: `module`, `type`.
-     *
-     * Seeing this is proof the module IS registered and mapped, which is exactly what {@link noHandler}
-     * cannot tell you — so this is a route-name problem, not a composition problem.
+     * **The module answered but has no route of that type** — so it IS registered, and this is a
+     * route-name problem. Parameters: `module`, `type`.
      */
     noRoute: 'NO_ROUTE',
-    /**
-     * A scope-routed module was called without a `scope`. Parameters: `module`.
-     *
-     * This was MISSING here while the host emitted it (P5.5 H6), so a scoped app could not match it by
-     * constant and had to hard-code the string — against documentation claiming the two sides mirror
-     * name-for-name. The mirror is now enforced by a test rather than by care.
-     */
+    /** A scope-routed module was called without a `scope`. Parameters: `module`. */
     scopeRequired: 'SCOPE_REQUIRED',
     missingPayloadValue: 'MISSING_PAYLOAD_VALUE',
     invalidPayloadValue: 'INVALID_PAYLOAD_VALUE',
     /**
      * The operation was cancelled — a NORMAL outcome, not a fault. Treat it as "show nothing": it is the
-     * one failure a UI should stay silent about. Previously indistinguishable from `UNKNOWN_ERROR`.
+     * one failure a UI should stay silent about.
      */
     operationCancelled: 'OPERATION_CANCELLED',
     /**
      * The shell has NO EXPRESSION of what was asked for — not a fault, and not something a retry fixes.
-     * Parameters: `capability` (a {@link ShellCapabilities} value).
-     *
-     * Treat it like `operationCancelled`: do not show a fault. The right response is to hide the control,
-     * because the capability is absent by design on that platform (a folder picker on a phone, for
-     * instance) rather than broken.
+     * Parameters: `capability` (a {@link ShellCapabilities} value). Hide the control rather than showing
+     * an error: the capability is absent by design on that platform, not broken.
      *
-     * ⚠ A page should not normally NEED this. The ready handshake advertises `ShellInfo.capabilities`
-     * precisely so one bundle can decide BEFORE it asks — `useFileDialogs().canPickFolder` is the
-     * intended path. This is the honest answer when a page asks anyway.
+     * ⚠ A page should not normally NEED this. The ready handshake advertises `ShellInfo.capabilities` so
+     * one bundle can decide BEFORE it asks — `useFileDialogs().canPickFolder` is the intended path.
      */
     capabilityNotSupported: 'CAPABILITY_NOT_SUPPORTED',
     /** Client-only: the request timed out waiting for a response. */
@@ -73,8 +58,7 @@ export const IpcErrorCodes = {
 };
 /**
  * The codes that exist ONLY on the client — they never arrive from the host, but reject through the same
- * structured shape so app error handling stays uniform. Named here so the cross-language mirror check can
- * exclude them by intent rather than by a hard-coded list on the other side.
+ * structured shape. Named here so the cross-language mirror check excludes them by intent.
  */
 export const ClientOnlyIpcErrorCodes = [
     IpcErrorCodes.timeout,
@@ -94,24 +78,19 @@ export const ShellCapabilities = {
     tray: 'tray',
     /**
      * The host can put a FILE LIST on the clipboard, so the user can paste into Explorer, Finder or a
-     * file manager. No web API expresses this, and a phone's pasteboard has none — so it is the one part
-     * of the clipboard worth branching on.
+     * file manager. No web API expresses this, so it is the one part of the clipboard worth branching on.
      *
      * ⚠ It says nothing about the rest: text and bytes work everywhere, and the gesture-driven half is
-     * `navigator.clipboard`'s job, not the host's.
+     * `navigator.clipboard`'s job.
      */
     clipboardFiles: 'clipboardFiles',
     /**
-     * The host can serve LOCAL FILES to this page — media, images, documents, exports — through its resource
-     * interceptor. Pair it with {@link mediaUrl}.
-     *
-     * A page cannot reach a local file itself on any shell (`file://` is blocked from a virtual-host origin,
-     * and would be the wrong answer anyway), so branch on this and fall back rather than rendering a player
-     * that can never load.
+     * The host can serve LOCAL FILES to this page — media, images, documents, exports — through its
+     * resource interceptor. Pair it with `mediaUrl`.
      *
-     * ⚠ It says the host CAN serve, not what: routes, payload shape and allowed roots are the app's. And it
-     * deliberately tells you nothing about the URL SCHEME — {@link mediaUrl} is relative precisely so each
-     * shell supplies its own, and knowing it would put you back to branching on platform.
+     * ⚠ A page cannot reach a local file itself on any shell, so branch on this and fall back rather than
+     * rendering a player that can never load. It says the host CAN serve, not what: routes, payload shape
+     * and allowed roots are the app's, and it says nothing about the URL SCHEME.
      */
     localFiles: 'localFiles',
 };

package/dist/useDropZone.d.ts

@@ -18,9 +18,7 @@ export interface DropZoneFileDrop {
  * Inputs for {@link useDropZone}.
  *
  * No ordering constraint against `notifyReady()`: the host clears zones when a new DOCUMENT starts
- * loading, not on the handshake, so this hook's `REGISTER` cannot be wiped by a reset that arrives
- * after it. (It could, until the reset moved off the handshake — React runs CHILD effects before
- * PARENT effects, which made losing the registration the default outcome rather than bad luck.)
+ * loading, not on the handshake, so this hook's `REGISTER` cannot be wiped by a later reset.
  */
 export interface UseDropZoneOptions {
     /** The element the native overlay tracks. */
@@ -33,11 +31,10 @@ export interface UseDropZoneOptions {
      * does not re-register the zone, which is what "stable" means here. */
     zoneId?: string;
     /**
-     * Class toggled on the element while a file drag hovers the zone. UNSTYLED — headless (D13):
-     * the library ships no CSS; style it in the app. Default `"shenora-drop-hover"`.
-     * ⚠ Read on the FIRST render only, like {@link UseDropZoneOptions.zoneId}: the hover effect
-     * captures it for its cleanup while the drop path reads it live, so a mid-hover change would add one
-     * class and remove another, leaving the first stuck on the element. Switch it by remounting.
+     * Class toggled on the element while a file drag hovers the zone. UNSTYLED — the library ships no
+     * CSS; style it in the app. Default `"shenora-drop-hover"`.
+     * ⚠ Read on the FIRST render only, like {@link UseDropZoneOptions.zoneId}: a mid-hover change would
+     * add one class and remove another, leaving the first stuck on the element. Switch it by remounting.
      */
     dropClassName?: string;
     /** The bridge to speak over. Default: the shared default bridge. */
@@ -48,29 +45,20 @@ export interface UseDropZoneOptions {
      * Where a failed REGISTER / UPDATE / SHOW / UNREGISTER is reported. Default: `console.error`.
      *
      * ⚠ Worth routing somewhere real, because a failure here is INVISIBLE in the UI: the page renders
-     * exactly as it should and files simply do not drop. This hook was the last error path in the package
-     * that could only ever reach the console — `bridge.ts`'s `onPostError`, `store.ts`'s `onError` and
-     * `segmentBinder.ts`'s `onDiagnostic` all take an app sink.
+     * exactly as it should and files simply do not drop.
      */
     onError?: (error: unknown, route: string) => void;
 }
 /**
  * **The file-drop API for a Shenora page. Do not use the DOM's own drop event for files —
- * it is not an alternative here, it is the thing this exists to replace.**
+ * it is not an alternative here, it is the thing this exists to replace.** A page-side `onDrop` gets a
+ * `File` whose only accessor is its CONTENT, so every dropped file is copied into the renderer and
+ * across the IPC boundary before the app knows whether it wants any of them. This gives you `string[]`
+ * OS paths instead — open lazily, stream, hash incrementally, move or link without copying.
  *
- * A page-side `onDrop` gets a `File` handle whose only accessor is its CONTENT. In a shell
- * architecture the page is UI and the host does the file work, so those bytes have to be read into
- * the renderer and then pushed across the IPC boundary: a full copy of every dropped file, EAGERLY,
- * at drop time, before the app knows whether it wants any of them. Drop 200 files to filter by
- * extension and you pay for all 200; drop a multi-GB asset and you pay that, to reach a file the
- * host could have opened off the same disk. This hook gives you `string[]` paths instead — open
- * lazily, stream, hash incrementally, move or link without copying, watch for changes.
- *
- * Sync a native drop-zone overlay to a page element, ported from the primary desktop sibling
- * (its fix-history comments kept below): the host positions a transparent WinForms overlay
- * over the element to capture REAL OS file paths — including drags started while the app is in
- * the background. Bounds re-sync (debounced) on resize/scroll/intersection changes; the host
- * converts the CSS rect to physical pixels per-monitor.
+ * The host positions a transparent native overlay over the element to capture those paths, including
+ * for drags started while the app is in the background. Bounds re-sync (debounced) on
+ * resize/scroll/intersection changes; the host converts the CSS rect to physical pixels per-monitor.
  *
  * How the visibility dance works: mouse leaves the element → SHOW (overlay up, ready to catch a
  * drag); mouse enters → the host hides the overlay (hover effects keep working); an inactive