@shenora/react 0.11.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

@@ -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

package/dist/useDropZone.js

@@ -7,21 +7,14 @@ 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
@@ -31,17 +24,12 @@ const newZoneId = () => randomId('drop-zone-');
 export function useDropZone(options) {
     const { targetRef, enabled = true } = options;
     // ⚠ LAZY, because `useRef(newZoneId())` evaluates its argument on EVERY render and keeps only the
-    // first — so the generator ran a `crypto.randomUUID()` per render of every drop zone, for a value
-    // used once. The empty string is a safe sentinel: a generated id is never empty, and a caller who
-    // passes `zoneId: ''` short-circuits the `??` and so still never reaches the generator.
+    // 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, like the id, and unlike `onDrop`/`bridge` below which track the latest value. That is
-    // deliberate rather than an oversight: the hover effect captures this class for its cleanup, while
-    // the FILE_DROP effect reads it live, so a value that could change mid-hover would let one path add
-    // class A and another remove class B — leaving A stuck on the element with no drag in progress. The
-    // default is a constant, so unlike the id there is nothing here worth making lazy.
+    // 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;
@@ -49,22 +37,19 @@ export function useDropZone(options) {
     bridgeRef.current = options.bridge;
     const bus = options.bus ?? defaultEventBus;
     // Tracks the latest handler (like `onDrop`), so a cleanup that runs long after mount still reports
-    // through the sink the app has NOW. Only when the app supplied none does this log — a caller that
-    // took `onError` owns its reporting and must not be double-logged, the rule the package's other
-    // three sinks follow.
+    // 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 (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.
+    // 🔴 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);
@@ -76,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(() => { });
@@ -165,11 +149,10 @@ 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 } })

package/dist/windowCommands.d.ts

@@ -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 {};

package/dist/windowCommands.js

@@ -40,33 +40,29 @@ export class WindowCommands extends BaseModuleService {
         return this.send('SET_THEME', { payload: { dark } });
     }
     /**
-     * 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) {
         return this.send('SET_CAPTION_BUTTONS', { payload: { buttons } });
     }
 }
 /**
- * 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 function useWindowMaximized(commands) {
     const [maximized, setMaximized] = useState(false);
@@ -80,11 +76,8 @@ export function useWindowMaximized(commands) {
                     setMaximized(value);
             }, () => { });
         };
-        // DEBOUNCED (P5.5 H2). `resize` fires continuously while a window is dragged — roughly 180 events
-        // over a 3-second drag — and each one used to start a full IPC round-trip, every one of them
-        // arming a 30-second timeout timer. The state that matters only changes at the END of a resize
-        // (maximize/restore is a single step), so the trailing edge is not just cheaper, it is the correct
-        // semantics. 100 ms matches the drop-zone bounds sync.
+        // `resize` fires continuously while a window is dragged, and each event undebounced is a full IPC
+        // round-trip arming its own 30-second timeout timer. 100 ms matches the drop-zone bounds sync.
         const refresh = debounce(query, 100);
         query(); // the initial read is immediate — nothing to coalesce yet
         window.addEventListener('resize', refresh);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shenora/react",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "React client for Shenora hosts on Windows, Android and iOS: correlated invoke/send/subscribe over the desktop postMessage bridge or the MAUI HybridWebView transport, typed module services, host-backed stores, and hooks for request tracking and media playback. Drop zones and window commands are desktop-only, because the capabilities are. Ships a browser fallback for pure-UI development.",
   "license": "MIT",
   "author": "Jiarong Gu",