@shenora/react 0.10.0 → 0.12.0

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

@@ -1,5 +1,5 @@
 /**
- * The Shenora IPC wire contract — the TS mirror of the `Shenora.Ipc` C# envelopes (names are
+ * The Shenora IPC wire contract — the TS mirror of the `Shenora.Core.Ipc` C# envelopes (names are
  * pinned on both sides; the host serializes camelCase). Transport-neutral: the same envelopes
  * travel over WebView2 postMessage, a WebSocket, or a mobile shell's channel.
  */
@@ -21,33 +21,34 @@ export declare const HANDSHAKE_TYPE = "READY";
  */
 export declare const IpcErrorCodes: {
     readonly unknownError: "UNKNOWN_ERROR";
-    readonly noHandler: "NO_HANDLER";
     /**
-     * A scope-routed module was called without a `scope`. Parameters: `module`.
+     * **No MODULE claimed the request** — nothing host-side answers that name, i.e. the module was never
+     * registered. Parameters: `module`, `type`.
      *
-     * 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.
+     * ⚠ 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** — 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`. */
     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).
+     * 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.
      *
-     * 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.
-     *
-     * ⚠ 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. */
@@ -57,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. */
@@ -85,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. */
@@ -119,16 +107,20 @@ export declare const ShellCapabilities: {
     readonly secondaryWindows: "secondaryWindows";
     readonly tray: "tray";
     /**
-     * The host can serve LOCAL FILES to this page — media, images, documents, exports — through its resource
-     * interceptor. Pair it with {@link mediaUrl}.
+     * 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, so it is the one part of the clipboard worth branching on.
      *
-     * 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.
+     * ⚠ It says nothing about the rest: text and bytes work everywhere, and the gesture-driven half is
+     * `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 `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";
 };
@@ -159,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

@@ -1,5 +1,5 @@
 /**
- * The Shenora IPC wire contract — the TS mirror of the `Shenora.Ipc` C# envelopes (names are
+ * The Shenora IPC wire contract — the TS mirror of the `Shenora.Core.Ipc` C# envelopes (names are
  * pinned on both sides; the host serializes camelCase). Transport-neutral: the same envelopes
  * travel over WebView2 postMessage, a WebSocket, or a mobile shell's channel.
  */
@@ -21,33 +21,34 @@ export const HANDSHAKE_TYPE = 'READY';
  */
 export const IpcErrorCodes = {
     unknownError: 'UNKNOWN_ERROR',
-    noHandler: 'NO_HANDLER',
     /**
-     * A scope-routed module was called without a `scope`. Parameters: `module`.
+     * **No MODULE claimed the request** — nothing host-side answers that name, i.e. the module was never
+     * registered. Parameters: `module`, `type`.
      *
-     * 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.
+     * ⚠ 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** — 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`. */
     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).
+     * 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.
      *
-     * 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.
-     *
-     * ⚠ 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. */
@@ -57,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,
@@ -77,16 +77,20 @@ export const ShellCapabilities = {
     secondaryWindows: 'secondaryWindows',
     tray: 'tray',
     /**
-     * The host can serve LOCAL FILES to this page — media, images, documents, exports — through its resource
-     * interceptor. Pair it with {@link mediaUrl}.
+     * 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, so it is the one part of the clipboard worth branching on.
      *
-     * 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.
+     * ⚠ It says nothing about the rest: text and bytes work everywhere, and the gesture-driven half is
+     * `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 `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

@@ -1,8 +1,8 @@
 import { type RefObject } from 'react';
 import { type ShenoraBridge } from './bridge.js';
 import { type ShenoraEventBus } from './eventBus.js';
-/** The reserved module the drop-zone stack speaks (host: `DropZoneManager`/`DropZoneFacade`). */
-export declare const DROP_ZONE_MODULE = "DROP_ZONE";
+/** The reserved module the drop-zone stack speaks (host: `DropZoneManager`/`DropZoneModule`). */
+export declare const DROP_ZONE_MODULE = "SHENORA.DROPZONE";
 /** A native file drop delivered to a zone. */
 export interface DropZoneFileDrop {
     zoneId: string;
@@ -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. */
@@ -29,35 +27,38 @@ export interface UseDropZoneOptions {
     onDrop: (files: string[], drop: DropZoneFileDrop) => void;
     /** False = zone torn down (same as unmount). Default true. */
     enabled?: boolean;
-    /** Stable zone id; default: generated per mount. */
+    /** Stable zone id; default: generated per mount. ⚠ Read on the FIRST render only — changing it later
+     * 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"`.
+     * 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. */
     bridge?: ShenoraBridge;
     /** The event bus host notifications arrive on. Default: the shared bus. */
     bus?: ShenoraEventBus;
+    /**
+     * 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.
+     */
+    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.**
- *
- * 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.
+ * 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.
  *
- * 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

package/dist/useDropZone.js

@@ -2,26 +2,19 @@ import { useEffect, useRef, useState } from 'react';
 import { getBridge } from './bridge.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
 import { debounce, randomId } from './internal.js';
-/** The reserved module the drop-zone stack speaks (host: `DropZoneManager`/`DropZoneFacade`). */
-export const DROP_ZONE_MODULE = 'DROP_ZONE';
+/** The reserved module the drop-zone stack speaks (host: `DropZoneManager`/`DropZoneModule`). */
+export const DROP_ZONE_MODULE = 'SHENORA.DROPZONE';
 const newZoneId = () => randomId('drop-zone-');
 /**
  * **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
@@ -30,20 +23,33 @@ const newZoneId = () => randomId('drop-zone-');
  */
 export function useDropZone(options) {
     const { targetRef, enabled = true } = options;
-    const zoneIdRef = useRef(options.zoneId ?? newZoneId());
+    // ⚠ LAZY, because `useRef(newZoneId())` evaluates its argument on EVERY render and keeps only the
+    // first. The empty string is a safe sentinel: a generated id is never empty, and a caller passing
+    // `zoneId: ''` short-circuits the `??` and so still never reaches the generator.
+    const zoneIdRef = useRef('');
+    if (zoneIdRef.current === '')
+        zoneIdRef.current = options.zoneId ?? newZoneId();
+    // Read ONCE, unlike `onDrop`/`bridge` below which track the latest value — see the option's docs.
     const dropClassRef = useRef(options.dropClassName ?? 'shenora-drop-hover');
     const onDropRef = useRef(options.onDrop);
     onDropRef.current = options.onDrop;
     const bridgeRef = useRef(options.bridge);
     bridgeRef.current = options.bridge;
     const bus = options.bus ?? defaultEventBus;
-    // Make the ref's CONTENT reactive (P5.5 H2). `targetRef` is a stable object, so effects keyed on it
-    // run exactly once — and if `targetRef.current` was null on that run (a conditionally-rendered
-    // target, or any order where the ref is attached after the first commit) the effect bailed out and
-    // NEVER re-ran: the zone was silently dead for the component's whole life, with no error anywhere.
-    // A ref mutation triggers no render, so this effect deliberately has NO dependency array — it
-    // observes `current` after every commit. `setElement` with an unchanged value is a no-op in React,
-    // so this cannot loop.
+    // Tracks the latest handler (like `onDrop`), so a cleanup that runs long after mount still reports
+    // through the sink the app has NOW. Logs only when the app supplied none.
+    const onErrorRef = useRef(options.onError);
+    onErrorRef.current = options.onError;
+    const reportRef = useRef(() => { });
+    reportRef.current = (error, route) => onErrorRef.current
+        ? onErrorRef.current(error, route)
+        : console.error(`[shenora] drop-zone ${route} failed:`, error);
+    // 🔴 Make the ref's CONTENT reactive. `targetRef` is a stable object, so an effect keyed on it runs
+    // exactly once — and if `targetRef.current` is null on that run (a conditionally-rendered target, or
+    // any order where the ref is attached after the first commit) the effect bails out and NEVER re-runs:
+    // the zone is silently dead for the component's whole life, with no error anywhere. A ref mutation
+    // triggers no render, so this effect has NO dependency array; `setElement` with an unchanged value is
+    // a React no-op, so it cannot loop.
     const [element, setElement] = useState(null);
     useEffect(() => {
         setElement(targetRef.current ?? null);
@@ -55,10 +61,9 @@ export function useDropZone(options) {
     const attemptedRef = useRef(false);
     // A REGISTER is in flight — guards against sending a duplicate before the first resolves.
     const registeringRef = useRef(false);
-    // Teardown epoch: the REGISTER ack must not apply after its zone was torn down — under
-    // StrictMode's mount-unmount-remount, a stale ack marked the DESTROYED zone "registered" and
-    // the overlay silently never existed again (found in review). Cleanup bumps the epoch; acks
-    // from an older epoch are ignored.
+    // Teardown epoch: a REGISTER ack must not apply after its zone was torn down. Under StrictMode's
+    // mount-unmount-remount a stale ack marks the DESTROYED zone "registered" and the overlay silently
+    // never exists again. Cleanup bumps the epoch; acks from an older epoch are ignored.
     const epochRef = useRef(0);
     const lastBoundsRef = useRef({ x: 0, y: 0, width: 0, height: 0 });
     const syncBoundsRef = useRef(() => { });
@@ -91,7 +96,7 @@ export function useDropZone(options) {
                 .then(() => {
                 if (epochRef.current === epoch)
                     isRegisteredRef.current = true;
-            }, (error) => console.error('[shenora] drop-zone REGISTER failed:', error))
+            }, (error) => reportRef.current(error, 'REGISTER'))
                 .finally(() => {
                 if (epochRef.current === epoch)
                     registeringRef.current = false;
@@ -101,7 +106,7 @@ export function useDropZone(options) {
             lastBoundsRef.current = bounds;
             bridge
                 .invoke(DROP_ZONE_MODULE, 'UPDATE', { payload: { zoneId: zoneIdRef.current, ...bounds } })
-                .catch((error) => console.error('[shenora] drop-zone UPDATE failed:', error));
+                .catch((error) => reportRef.current(error, 'UPDATE'));
         }
     };
     // Track the element and keep the native overlay in sync.
@@ -115,7 +120,7 @@ export function useDropZone(options) {
         const sendShow = debounce(() => {
             (bridgeRef.current ?? getBridge())
                 .invoke(DROP_ZONE_MODULE, 'SHOW', { payload: { zoneId: zoneIdRef.current } })
-                .catch((error) => console.error('[shenora] drop-zone SHOW failed:', error));
+                .catch((error) => reportRef.current(error, 'SHOW'));
         }, 100);
         // The element's mouseleave (and the window losing focus) re-arm the overlay — native
         // MouseLeave alone is unreliable through the WebView.
@@ -144,15 +149,14 @@ export function useDropZone(options) {
             window.removeEventListener('blur', onWindowBlur);
             element.removeEventListener('mouseleave', onMouseLeave);
             element.removeAttribute('data-drop-zone-id');
-            // Unregister whenever this effect tears down — on unmount OR when `enabled` flips false —
-            // unconditionally (not gated on the REGISTER ack) so an in-flight REGISTER is also torn
-            // down. The host's UnregisterZone no-ops if the overlay isn't there yet, and the ordered
-            // IPC channel processes the earlier REGISTER before this UNREGISTER (create-then-destroy,
-            // no orphan).
+            // Unregister whenever this effect tears down — on unmount OR when `enabled` flips false — and
+            // never gated on the REGISTER ack, so an in-flight REGISTER is torn down too. The host's
+            // UnregisterZone no-ops if the overlay isn't there yet, and the ordered IPC channel processes
+            // the earlier REGISTER first, so there is no orphan.
             if (attemptedRef.current) {
                 (bridgeRef.current ?? getBridge())
                     .invoke(DROP_ZONE_MODULE, 'UNREGISTER', { payload: { zoneId: zoneIdRef.current } })
-                    .catch((error) => console.error('[shenora] drop-zone UNREGISTER failed:', error));
+                    .catch((error) => reportRef.current(error, 'UNREGISTER'));
                 epochRef.current++; // invalidate any in-flight REGISTER's ack (see epochRef)
                 isRegisteredRef.current = false;
                 registeringRef.current = false; // a remount must re-send immediately

package/dist/windowCommands.d.ts

@@ -33,7 +33,7 @@ interface WindowRequests {
     };
 }
 /**
- * Typed client for the host's `WINDOW` module (`WindowCommandFacade` in Shenora.Windows) —
+ * Typed client for the host's `SHENORA.WINDOW` module (`WindowCommandModule` in Shenora.Windows) —
  * drive the frameless window's chrome from the page: chrome buttons call
  * `minimize`/`toggleMaximize`/`close`, the header's `onMouseDown` calls `startDrag` (the window
  * then drags natively — snap and multi-monitor included), and a thin strip at the very top
@@ -54,31 +54,27 @@ export declare class WindowCommands extends BaseModuleService<WindowRequests> {
     /** Resync the native chrome to the app theme (host `WindowCommandOptions.ApplyTheme`). */
     setTheme(dark: boolean): Promise<void>;
     /**
-     * Tell the host where the page drew its caption buttons, so the OS can treat them as the real
-     * thing — chiefly so Windows 11 offers **Snap Layouts** on the maximize button, which a page-drawn
-     * button never gets otherwise.
+     * Tell the host where the page drew its caption buttons, so the OS treats them as the real thing —
+     * chiefly so Windows 11 offers **Snap Layouts** on the maximize button.
      *
-     * Two consequences worth knowing before calling this. The host takes over CLICKS in those rects
-     * (the OS stops delivering them to the page), so your `onClick` handlers stop firing there — the
-     * host performs minimize/maximize/close itself, through the same commands. And CSS `:hover` stops
-     * firing too, so subscribe to the host's caption-button state to render hot/pressed; it is also the
-     * only way to stay hot while the pointer is over the snap flyout, which is a different window.
+     * ⚠ The host then takes over CLICKS in those rects and performs minimize/maximize/close itself, so
+     * your `onClick` handlers stop firing there. CSS `:hover` stops firing too — subscribe to the host's
+     * caption-button state to render hot/pressed, which is also the only way to stay hot while the
+     * pointer is over the snap flyout, a different window.
      *
-     * Re-send on every layout change (a resize, a theme that changes button size): the rectangles are a
-     * snapshot, and a stale one moves the hit-test off the button the user can see. Pass an empty array
-     * to hand every pixel back to the page.
+     * ⚠ Re-send on every layout change: the rectangles are a snapshot, and a stale one moves the
+     * hit-test off the button the user can see. Pass an empty array to hand the pixels back to the page.
      */
     setCaptionButtons(buttons: CaptionButtonRect[]): Promise<void>;
 }
 /**
- * The max/restore-glyph resync pattern from the source app: the authoritative maximize state,
- * re-queried when a resize SETTLES (a maximize/restore always resizes the window, and the DOM has no
- * other signal for the manual work-area maximize). Failures (plain browser, no host) leave it false.
+ * The authoritative maximize state, re-queried when a resize SETTLES — a maximize/restore always
+ * resizes the window, and the DOM has no other signal for the manual work-area maximize. Failures
+ * (plain browser, no host) leave it false.
  *
- * Read once immediately, then on the TRAILING edge of a 100 ms debounce — not once per `resize`
- * event, which a window drag fires ~180 times in three seconds. Coalescing is the correct semantics
- * here, not just the cheap one: maximize/restore is a single step, so only the end state matters. Do
- * not build on intermediate values during a drag; there are none.
+ * ⚠ Read once immediately, then only on the TRAILING edge of a 100 ms debounce, so there are no
+ * intermediate values during a drag to build on. Maximize/restore is a single step; only the end
+ * state exists.
  */
 export declare function useWindowMaximized(commands?: WindowCommands): boolean;
 export {};