@shenora/react 0.1.0

package/dist/useDropZone.js

@@ -0,0 +1,183 @@
+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';
+const newZoneId = () => randomId('drop-zone-');
+/**
+ * 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.
+ *
+ * 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
+ * window always shows overlays (background drag-drop); while the overlay is visible the host
+ * emits DRAG_ENTER/DRAG_LEAVE for CSS feedback.
+ */
+export function useDropZone(options) {
+    const { targetRef, enabled = true } = options;
+    const zoneIdRef = useRef(options.zoneId ?? newZoneId());
+    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.
+    const [element, setElement] = useState(null);
+    useEffect(() => {
+        setElement(targetRef.current ?? null);
+    });
+    const isRegisteredRef = useRef(false);
+    // Whether a REGISTER has ever been SENT for this zone (even if not yet acked). The cleanup
+    // unregisters on THIS (not on the ack) so a fast unmount before REGISTER resolves still tears
+    // the overlay down.
+    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.
+    const epochRef = useRef(0);
+    const lastBoundsRef = useRef({ x: 0, y: 0, width: 0, height: 0 });
+    const syncBoundsRef = useRef(() => { });
+    syncBoundsRef.current = () => {
+        const element = targetRef.current;
+        if (!element)
+            return;
+        const bridge = bridgeRef.current ?? getBridge();
+        const rect = element.getBoundingClientRect();
+        const bounds = {
+            x: Math.round(rect.left),
+            y: Math.round(rect.top),
+            width: Math.round(rect.width),
+            height: Math.round(rect.height),
+        };
+        const changed = !isRegisteredRef.current ||
+            bounds.x !== lastBoundsRef.current.x ||
+            bounds.y !== lastBoundsRef.current.y ||
+            bounds.width !== lastBoundsRef.current.width ||
+            bounds.height !== lastBoundsRef.current.height;
+        if (!isRegisteredRef.current) {
+            if (registeringRef.current)
+                return;
+            registeringRef.current = true;
+            attemptedRef.current = true;
+            lastBoundsRef.current = bounds;
+            const epoch = epochRef.current;
+            bridge
+                .invoke(DROP_ZONE_MODULE, 'REGISTER', { payload: { zoneId: zoneIdRef.current, ...bounds } })
+                .then(() => {
+                if (epochRef.current === epoch)
+                    isRegisteredRef.current = true;
+            }, (error) => console.error('[shenora] drop-zone REGISTER failed:', error))
+                .finally(() => {
+                if (epochRef.current === epoch)
+                    registeringRef.current = false;
+            });
+        }
+        else if (changed) {
+            lastBoundsRef.current = bounds;
+            bridge
+                .invoke(DROP_ZONE_MODULE, 'UPDATE', { payload: { zoneId: zoneIdRef.current, ...bounds } })
+                .catch((error) => console.error('[shenora] drop-zone UPDATE failed:', error));
+        }
+    };
+    // Track the element and keep the native overlay in sync.
+    useEffect(() => {
+        if (!enabled || !element)
+            return;
+        // The host's occlusion check finds the element through this attribute.
+        element.setAttribute('data-drop-zone-id', zoneIdRef.current);
+        const syncBounds = debounce(() => syncBoundsRef.current(), 100);
+        syncBoundsRef.current();
+        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));
+        }, 100);
+        // The element's mouseleave (and the window losing focus) re-arm the overlay — native
+        // MouseLeave alone is unreliable through the WebView.
+        const onMouseLeave = () => sendShow();
+        const onWindowBlur = () => sendShow();
+        element.addEventListener('mouseleave', onMouseLeave);
+        window.addEventListener('blur', onWindowBlur);
+        // Guarded construction: test DOMs (jsdom) lack the observers; real WebView2 always has them.
+        const resizeObserver = typeof ResizeObserver !== 'undefined'
+            ? new ResizeObserver(() => syncBounds())
+            : undefined;
+        const intersectionObserver = typeof IntersectionObserver !== 'undefined'
+            ? new IntersectionObserver(() => syncBounds(), { threshold: [0, 0.1, 0.5, 0.9, 1.0] })
+            : undefined;
+        resizeObserver?.observe(element);
+        intersectionObserver?.observe(element);
+        window.addEventListener('scroll', syncBounds, true);
+        window.addEventListener('resize', syncBounds);
+        return () => {
+            sendShow.cancel();
+            syncBounds.cancel();
+            resizeObserver?.disconnect();
+            intersectionObserver?.disconnect();
+            window.removeEventListener('scroll', syncBounds, true);
+            window.removeEventListener('resize', syncBounds);
+            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).
+            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));
+                epochRef.current++; // invalidate any in-flight REGISTER's ack (see epochRef)
+                isRegisteredRef.current = false;
+                registeringRef.current = false; // a remount must re-send immediately
+                attemptedRef.current = false;
+            }
+        };
+    }, [enabled, element]);
+    // Drag-hover CSS feedback.
+    useEffect(() => {
+        if (!enabled || !element)
+            return;
+        const dropClass = dropClassRef.current;
+        const offEnter = bus.subscribe(DROP_ZONE_MODULE, 'DRAG_ENTER', (event) => {
+            if (event.payload?.zoneId === zoneIdRef.current)
+                element.classList.add(dropClass);
+        });
+        const offLeave = bus.subscribe(DROP_ZONE_MODULE, 'DRAG_LEAVE', (event) => {
+            if (event.payload?.zoneId === zoneIdRef.current)
+                element.classList.remove(dropClass);
+        });
+        return () => {
+            offEnter();
+            offLeave();
+            element.classList.remove(dropClass);
+        };
+    }, [enabled, element, bus]);
+    // File drops.
+    useEffect(() => {
+        if (!enabled)
+            return;
+        return bus.subscribe(DROP_ZONE_MODULE, 'FILE_DROP', (event) => {
+            const drop = event.payload;
+            if (!drop || drop.zoneId !== zoneIdRef.current)
+                return;
+            targetRef.current?.classList.remove(dropClassRef.current);
+            onDropRef.current(drop.files, drop);
+        });
+    }, [enabled, targetRef, bus]);
+}

package/dist/windowCommands.d.ts

@@ -0,0 +1,80 @@
+import type { ShenoraBridge } from './bridge.js';
+import { BaseModuleService } from './moduleService.js';
+/** The top resize edges — the only ones that exist: the frameless technique keeps the native
+ * side/bottom resize borders, so only the top (covered by the WebView) needs page-side help. */
+export type WindowResizeEdge = 'top' | 'topLeft' | 'topRight';
+/** Which system caption button a page-drawn region stands in for (mirrors the host's enum). */
+export type CaptionButtonKind = 'minimize' | 'maximize' | 'close';
+/**
+ * Where the page drew one caption button, in CSS px relative to the WebView2 — i.e. straight out of
+ * `getBoundingClientRect()`. The host converts to physical px using the control's DeviceDpi.
+ */
+export interface CaptionButtonRect {
+    kind: CaptionButtonKind;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface WindowRequests {
+    MINIMIZE: void;
+    TOGGLE_MAXIMIZE: void;
+    CLOSE: void;
+    IS_MAXIMIZED: void;
+    START_DRAG: void;
+    START_RESIZE: {
+        edge: WindowResizeEdge;
+    };
+    SET_THEME: {
+        dark: boolean;
+    };
+    SET_CAPTION_BUTTONS: {
+        buttons: CaptionButtonRect[];
+    };
+}
+/**
+ * Typed client for the host's `WINDOW` module (`WindowCommandFacade` in Shenora.WebView2) —
+ * 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
+ * calls `startResize` on mousedown. `setTheme` resyncs the native chrome on a runtime
+ * light↔dark switch (without it the frame keeps the old theme's border; measured host-side).
+ */
+export declare class WindowCommands extends BaseModuleService<WindowRequests> {
+    constructor(bridge?: ShenoraBridge);
+    minimize(): Promise<void>;
+    toggleMaximize(): Promise<void>;
+    close(): Promise<void>;
+    /** Authoritative maximize state (a frameless manual maximize never shows in the DOM). */
+    isMaximized(): Promise<boolean>;
+    /** Call from the header's `onMouseDown` — hands off to the OS move loop. */
+    startDrag(): Promise<void>;
+    /** Call from the top strip's `onMouseDown` — hands off to the OS size loop. */
+    startResize(edge?: WindowResizeEdge): Promise<void>;
+    /** 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.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    setCaptionButtons(buttons: CaptionButtonRect[]): Promise<void>;
+}
+/**
+ * The max/restore-glyph resync pattern from the source app: the authoritative maximize state,
+ * re-queried on every window resize (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.
+ */
+export declare function useWindowMaximized(commands?: WindowCommands): boolean;
+export {};

package/dist/windowCommands.js

@@ -0,0 +1,94 @@
+import { useEffect, useRef, useState } from 'react';
+import { debounce } from './internal.js';
+import { BaseModuleService } from './moduleService.js';
+/**
+ * Typed client for the host's `WINDOW` module (`WindowCommandFacade` in Shenora.WebView2) —
+ * 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
+ * calls `startResize` on mousedown. `setTheme` resyncs the native chrome on a runtime
+ * light↔dark switch (without it the frame keeps the old theme's border; measured host-side).
+ */
+export class WindowCommands extends BaseModuleService {
+    constructor(bridge) {
+        super('WINDOW', bridge);
+    }
+    minimize() {
+        return this.send('MINIMIZE');
+    }
+    toggleMaximize() {
+        return this.send('TOGGLE_MAXIMIZE');
+    }
+    close() {
+        return this.send('CLOSE');
+    }
+    /** Authoritative maximize state (a frameless manual maximize never shows in the DOM). */
+    async isMaximized() {
+        const result = await this.send('IS_MAXIMIZED');
+        return result.maximized;
+    }
+    /** Call from the header's `onMouseDown` — hands off to the OS move loop. */
+    startDrag() {
+        return this.send('START_DRAG');
+    }
+    /** Call from the top strip's `onMouseDown` — hands off to the OS size loop. */
+    startResize(edge = 'top') {
+        return this.send('START_RESIZE', { payload: { edge } });
+    }
+    /** Resync the native chrome to the app theme (host `WindowCommandOptions.ApplyTheme`). */
+    setTheme(dark) {
+        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.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    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 on every window resize (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.
+ */
+export function useWindowMaximized(commands) {
+    const [maximized, setMaximized] = useState(false);
+    const defaultCommands = useRef(undefined);
+    useEffect(() => {
+        const target = commands ?? (defaultCommands.current ?? (defaultCommands.current = new WindowCommands()));
+        let stale = false;
+        const query = () => {
+            target.isMaximized().then((value) => {
+                if (!stale)
+                    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.
+        const refresh = debounce(query, 100);
+        query(); // the initial read is immediate — nothing to coalesce yet
+        window.addEventListener('resize', refresh);
+        return () => {
+            stale = true;
+            refresh.cancel(); // a pending timer must not fire against an unmounted component
+            window.removeEventListener('resize', refresh);
+        };
+    }, [commands]);
+    return maximized;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@shenora/react",
+  "version": "0.1.0",
+  "description": "React client for Shenora desktop hosts: correlated invoke/send/subscribe over the WebView2 bridge, typed module services, hooks, and a browser fallback for pure-UI development.",
+  "license": "MIT",
+  "author": "Jiarong Gu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JiarongGu/Shenora.git",
+    "directory": "src/Shenora.React"
+  },
+  "homepage": "https://github.com/JiarongGu/Shenora#readme",
+  "keywords": [
+    "shenora",
+    "webview2",
+    "desktop",
+    "ipc",
+    "react",
+    "winforms",
+    "dotnet"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "//typecheck": "The ONLY thing that type-checks the tests — `build` excludes them and vitest transpiles without checking, so `@ts-expect-error` assertions (which pin the typed-service generic) are inert without this. Run by dev.mjs verify.",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.17",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  }
+}