@shenora/react 0.11.0 → 0.13.0

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.13.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",