@shenora/react 0.1.0

package/dist/moduleService.js

@@ -0,0 +1,57 @@
+import { getBridge } from './bridge.js';
+/**
+ * Base class for typed module services, ported from the primary desktop sibling: each backend
+ * module gets one service subclass that binds the module name once and exposes app-typed
+ * methods over {@link send}. Bind `TRequests` to the module's request map
+ * (`{ [type]: payloadType }`) for compile-time payload checking:
+ *
+ * ```ts
+ * interface NoteRequests { GET_ALL: void; ADD: { title: string } }
+ * class NoteService extends BaseModuleService<NoteRequests> {
+ *   constructor() { super('NOTES'); }
+ *   getAll() { return this.send<Note[]>('GET_ALL'); }
+ *   add(title: string) { return this.send<Note>('ADD', { payload: { title } }); }
+ * }
+ * ```
+ *
+ * DEVIATION from the source: its boolean/array/optional convenience wrappers were pure casts
+ * around the same call — the response generic already expresses them, so they're gone.
+ *
+ * `TRequests extends object`, NOT `extends Record<string, unknown>` (P5.5 H6). The stricter bound was
+ * unsatisfiable by a plain `interface` — interfaces get no implicit index signature — so the example
+ * above and the README's snippet both failed with TS2344, on the first line an adopter copies. And
+ * satisfying it the way the kit's own `windowCommands.ts` did (`interface X extends Record<string,
+ * unknown>`) widened `keyof TRequests & string` back to `string`, so a mistyped request type compiled
+ * and every payload collapsed to `unknown` — the flagship typed-service feature checking nothing at all.
+ */
+export class BaseModuleService {
+    constructor(
+    /** The backend module this service fronts (e.g. `"NOTES"`). */
+    module, 
+    /**
+     * The bridge to speak over. Omit to use the shared default bridge, resolved PER CALL — see
+     * {@link bridge}.
+     */
+    explicitBridge) {
+        this.module = module;
+        this.explicitBridge = explicitBridge;
+    }
+    /**
+     * The bridge this service speaks over — resolved on every access, never captured.
+     *
+     * This used to be a constructor default (`bridge: ShenoraBridge = getBridge()`), which is evaluated
+     * at CONSTRUCTION: a service built before `configureBridge()` captured the old default, and
+     * `configureBridge` DISPOSES the bridge it replaces — so every later call from that service
+     * rejected with "Bridge disposed" for the rest of the session, with nothing to suggest why (P5.5
+     * H2). Module services are commonly module-level singletons, so constructing one before the app's
+     * startup configuration ran is the normal case, not an edge case. `useDropZone` already resolved
+     * lazily for exactly this reason; this matches it.
+     */
+    get bridge() {
+        return this.explicitBridge ?? getBridge();
+    }
+    /** Send one typed request to this module and await the typed response data. */
+    send(type, options = {}) {
+        return this.bridge.invoke(this.module, type, options);
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,102 @@
+import { type ShenoraBridge, type PostOptions } from './bridge.js';
+import { type ShenoraEventBus } from './eventBus.js';
+import type { EventMessage } from './types.js';
+/** The IPC handles a store's `actions` are built over. */
+export interface ShenoraStoreIo {
+    /** Fire-and-forget send to this store's module. Returns the request id. */
+    post: <TPayload = unknown>(type: string, options?: PostOptions<TPayload>) => string;
+    /** Correlated request to this store's module — for calls that are quick AND UI-thread-safe. */
+    invoke: <TData = unknown, TPayload = unknown>(type: string, options?: {
+        payload?: TPayload;
+        timeoutMs?: number;
+    }) => Promise<TData>;
+}
+/** How a store loads the state that already exists before anyone was watching. */
+export interface ShenoraStoreSnapshot<TState> {
+    /** The request type to `invoke` on this store's module. */
+    type: string;
+    payload?: unknown;
+    /** Fold the response into state. */
+    apply: (state: TState, data: unknown) => TState;
+}
+/** Inputs for {@link createShenoraStore}. */
+export interface ShenoraStoreOptions<TState, TActions> {
+    /** State before anything has arrived. */
+    initial: TState;
+    /**
+     * Load the CURRENT state when the first component subscribes.
+     *
+     * Not optional in spirit, even though it is in the type: a component that mounts while work is
+     * already in flight has MISSED the events, and a stream cannot be replayed. Snapshot-then-deltas
+     * is the contract; deltas alone silently work only for whoever was watching from the start.
+     */
+    snapshot?: ShenoraStoreSnapshot<TState>;
+    /** Event type (within this module) → PURE reducer over state. */
+    on?: Record<string, (state: TState, payload: never, event: EventMessage) => TState>;
+    /** Fire-and-forget senders / requests, exposed on the returned hook. */
+    actions?: (io: ShenoraStoreIo) => TActions;
+    /** Optional app-defined routing scope, applied to both the subscriptions and the sends. */
+    scope?: string;
+    /** Test/multi-transport seams. Default: the shared bridge and event bus. */
+    bridge?: ShenoraBridge;
+    bus?: ShenoraEventBus;
+    /** Where a reducer or snapshot failure is reported. Default: `console.error`. */
+    onError?: (error: unknown, context: {
+        module: string;
+        type: string;
+    }) => void;
+}
+/** What {@link createShenoraStore} returns: a hook, plus the store handles for non-React callers. */
+export interface ShenoraStore<TState, TActions> {
+    /** Subscribe this component. With no selector you get the whole state. */
+    (): TState;
+    <TSelected>(selector: (state: TState) => TSelected): TSelected;
+    /** Current state without subscribing (event handlers, actions, tests). */
+    getState: () => TState;
+    /** Subscribe outside React; returns an unsubscribe. */
+    subscribe: (listener: () => void) => () => void;
+    /** The declared actions. */
+    actions: TActions;
+    /** Test seam: drop state back to `initial` and forget that the snapshot ran. */
+    reset: () => void;
+}
+/**
+ * A store fed by one module's host event stream, shared by every component that reads it.
+ *
+ * This is the shape a desktop app needs and the one three sibling apps each hand-built before it
+ * existed here — see `docs/2026-07-31-shenora-oneway-ipc-design.md` §5 for the survey. It exists
+ * because status- and progress-driven UI is inherently MANY-WATCHERS: a full panel and a compact
+ * progress strip want the same live state, and without a shared store each re-implements the wiring,
+ * each opens its own subscription, and each starts empty.
+ *
+ * What it guarantees:
+ * - **One subscription per event type, however many components read it.** Mounting N components does
+ *   not open N subscriptions; unmounting the last one tears them down.
+ * - **A late mounter sees current state**, via {@link ShenoraStoreOptions.snapshot} on the first
+ *   subscription. This is the part that cannot be retrofitted by subscribing harder.
+ * - **No state library.** Built on React's `useSyncExternalStore`, which exists for exactly this and
+ *   is tearing-free under concurrent rendering. The kit imposes no store dependency (D13's spirit —
+ *   apps bring their own); every sibling reached for the same one, and baking that in would have been
+ *   solving their stack rather than their problem.
+ * - **Reducers are PURE and isolated**: they take state + payload and return state, so a store is
+ *   testable with no bridge, and a throwing reducer is reported rather than corrupting shared state.
+ *
+ * Headless (D13/D21): the kit ships the MECHANISM. What an operation is — its phases, its progress
+ * shape, whether it queues — stays in the app; there is deliberately no job/queue/progress type here.
+ *
+ * @example
+ * const useDeploy = createShenoraStore('DEPLOY', {
+ *   initial: { status: 'idle' as const, lines: [] as string[] },
+ *   snapshot: { type: 'GET_STATE', apply: (s, d) => ({ ...s, ...(d as object) }) },
+ *   on: {
+ *     PROGRESS: (s, p: { line: string }) => ({ ...s, lines: [...s.lines, p.line] }),
+ *     ENDED: (s, p: { ok: boolean }) => ({ ...s, status: p.ok ? 'done' : 'failed' }),
+ *   },
+ *   actions: ({ post }) => ({ start: (cfg: unknown) => post('START', { payload: cfg }) }),
+ * });
+ *
+ * // in any number of components:
+ * const status = useDeploy((s) => s.status);
+ * useDeploy.actions.start({ env: 'prod' });
+ */
+export declare function createShenoraStore<TState, TActions = Record<string, never>>(module: string, options: ShenoraStoreOptions<TState, TActions>): ShenoraStore<TState, TActions>;

package/dist/store.js

@@ -0,0 +1,150 @@
+import { useCallback, useDebugValue, useRef, useSyncExternalStore } from 'react';
+import { getBridge } from './bridge.js';
+import { eventBus as defaultEventBus } from './eventBus.js';
+/**
+ * A store fed by one module's host event stream, shared by every component that reads it.
+ *
+ * This is the shape a desktop app needs and the one three sibling apps each hand-built before it
+ * existed here — see `docs/2026-07-31-shenora-oneway-ipc-design.md` §5 for the survey. It exists
+ * because status- and progress-driven UI is inherently MANY-WATCHERS: a full panel and a compact
+ * progress strip want the same live state, and without a shared store each re-implements the wiring,
+ * each opens its own subscription, and each starts empty.
+ *
+ * What it guarantees:
+ * - **One subscription per event type, however many components read it.** Mounting N components does
+ *   not open N subscriptions; unmounting the last one tears them down.
+ * - **A late mounter sees current state**, via {@link ShenoraStoreOptions.snapshot} on the first
+ *   subscription. This is the part that cannot be retrofitted by subscribing harder.
+ * - **No state library.** Built on React's `useSyncExternalStore`, which exists for exactly this and
+ *   is tearing-free under concurrent rendering. The kit imposes no store dependency (D13's spirit —
+ *   apps bring their own); every sibling reached for the same one, and baking that in would have been
+ *   solving their stack rather than their problem.
+ * - **Reducers are PURE and isolated**: they take state + payload and return state, so a store is
+ *   testable with no bridge, and a throwing reducer is reported rather than corrupting shared state.
+ *
+ * Headless (D13/D21): the kit ships the MECHANISM. What an operation is — its phases, its progress
+ * shape, whether it queues — stays in the app; there is deliberately no job/queue/progress type here.
+ *
+ * @example
+ * const useDeploy = createShenoraStore('DEPLOY', {
+ *   initial: { status: 'idle' as const, lines: [] as string[] },
+ *   snapshot: { type: 'GET_STATE', apply: (s, d) => ({ ...s, ...(d as object) }) },
+ *   on: {
+ *     PROGRESS: (s, p: { line: string }) => ({ ...s, lines: [...s.lines, p.line] }),
+ *     ENDED: (s, p: { ok: boolean }) => ({ ...s, status: p.ok ? 'done' : 'failed' }),
+ *   },
+ *   actions: ({ post }) => ({ start: (cfg: unknown) => post('START', { payload: cfg }) }),
+ * });
+ *
+ * // in any number of components:
+ * const status = useDeploy((s) => s.status);
+ * useDeploy.actions.start({ env: 'prod' });
+ */
+export function createShenoraStore(module, options) {
+    const { initial, snapshot, on = {}, scope } = options;
+    const report = options.onError
+        ?? ((error, context) => console.error(`[shenora] store ${context.module}.${context.type} failed:`, error));
+    let state = initial;
+    let snapshotLoaded = false;
+    const listeners = new Set();
+    let unsubscribes = [];
+    const bridge = () => options.bridge ?? getBridge();
+    const bus = () => options.bus ?? defaultEventBus;
+    const setState = (next) => {
+        if (Object.is(next, state))
+            return; // a reducer returning the same state is a no-op, not a render
+        state = next;
+        for (const listener of [...listeners])
+            listener();
+    };
+    const applyEvent = (type, event) => {
+        const reduce = on[type];
+        if (!reduce)
+            return;
+        try {
+            setState(reduce(state, event.payload, event));
+        }
+        catch (error) {
+            // A throwing reducer must not corrupt shared state or break the other subscribers — the same
+            // guarded-callback rule the host applies to app code (Shenora.Core.AppCallback).
+            report(error, { module, type });
+        }
+    };
+    const loadSnapshot = () => {
+        if (!snapshot || snapshotLoaded)
+            return;
+        snapshotLoaded = true; // set BEFORE awaiting: two components mounting in the same tick must not
+        // both fire the request (React StrictMode double-invokes effects, which is precisely this case).
+        bridge()
+            .invoke(module, snapshot.type, { payload: snapshot.payload, scope })
+            .then((data) => {
+            try {
+                setState(snapshot.apply(state, data));
+            }
+            catch (error) {
+                report(error, { module, type: snapshot.type });
+            }
+        }, (error) => {
+            // Allow a later retry: a snapshot that failed because the host was not ready yet should not
+            // leave the store permanently empty for the rest of the session.
+            snapshotLoaded = false;
+            report(error, { module, type: snapshot.type });
+        });
+    };
+    const attach = () => {
+        unsubscribes = Object.keys(on).map((type) => bus().subscribe(module, type, (event) => applyEvent(type, event), { scope }));
+        loadSnapshot();
+    };
+    const detach = () => {
+        for (const off of unsubscribes)
+            off();
+        unsubscribes = [];
+    };
+    const subscribe = (listener) => {
+        // ONE subscription per event type for the whole store — the property that makes this worth
+        // existing. The first listener attaches; the last one to leave detaches.
+        if (listeners.size === 0)
+            attach();
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0)
+                detach();
+        };
+    };
+    const getState = () => state;
+    const io = {
+        post: (type, postOptions) => bridge().post(module, type, { scope, ...postOptions }),
+        invoke: (type, invokeOptions) => bridge().invoke(module, type, { scope, ...invokeOptions }),
+    };
+    function useStore(selector) {
+        // getSnapshot must return a STABLE value for an unchanged store, or React throws
+        // "The result of getSnapshot should be cached" and can loop. So the selector result is memoized
+        // against the state identity: recomputed only when state actually changed.
+        const cache = useRef(null);
+        const selectorRef = useRef(selector);
+        selectorRef.current = selector;
+        const getSelected = useCallback(() => {
+            const current = getState();
+            const select = selectorRef.current;
+            if (!select)
+                return current;
+            if (cache.current === null || !Object.is(cache.current.state, current)) {
+                cache.current = { state: current, selected: select(current) };
+            }
+            return cache.current.selected;
+        }, []);
+        const value = useSyncExternalStore(subscribe, getSelected, getSelected);
+        useDebugValue(value);
+        return value;
+    }
+    const store = useStore;
+    store.getState = getState;
+    store.subscribe = subscribe;
+    store.actions = options.actions ? options.actions(io) : {};
+    store.reset = () => {
+        snapshotLoaded = false;
+        setState(initial);
+    };
+    return store;
+}

package/dist/transport.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A message channel the bridge speaks over — the transport-pluggable seam (design D16): WebView2
+ * postMessage on desktop today; a WebSocket or a mobile shell's native channel speaks the same
+ * envelopes tomorrow. Messages are JSON strings in both directions.
+ */
+export interface ShenoraTransport {
+    /** Send one serialized envelope to the host. */
+    post(message: string): void;
+    /** Register a host→client listener; returns the unsubscribe function. */
+    subscribe(listener: (message: string) => void): () => void;
+}
+/**
+ * True when running inside a WebView2 desktop host (the bridge transport exists).
+ * In a plain browser this is false — callers should fall back to browser-only behavior.
+ */
+export declare function isShenoraAvailable(): boolean;
+/** The WebView2 postMessage transport, or null outside a WebView2 host. */
+export declare function createWebView2Transport(): ShenoraTransport | null;

package/dist/transport.js

@@ -0,0 +1,26 @@
+const webViewWindow = () => typeof window === 'undefined' ? undefined : window;
+/**
+ * True when running inside a WebView2 desktop host (the bridge transport exists).
+ * In a plain browser this is false — callers should fall back to browser-only behavior.
+ */
+export function isShenoraAvailable() {
+    return !!webViewWindow()?.chrome?.webview;
+}
+/** The WebView2 postMessage transport, or null outside a WebView2 host. */
+export function createWebView2Transport() {
+    const webview = webViewWindow()?.chrome?.webview;
+    if (!webview)
+        return null;
+    return {
+        post: (message) => webview.postMessage(message),
+        subscribe: (listener) => {
+            // The host posts strings (PostWebMessageAsString); anything else on the channel isn't ours.
+            const handler = (event) => {
+                if (typeof event.data === 'string')
+                    listener(event.data);
+            };
+            webview.addEventListener('message', handler);
+            return () => webview.removeEventListener('message', handler);
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The Shenora IPC wire contract — the TS mirror of the `Shenora.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.
+ */
+/** Values of the `category` discriminator on host→client messages. */
+export declare const IpcCategories: {
+    /** A response to a client request. */
+    readonly ipc: "ipc";
+    /** A host-pushed notification batch. */
+    readonly notification: "notification";
+};
+/** Reserved wire route: the ready handshake the host bridge intercepts (mirror of the host consts). */
+export declare const HANDSHAKE_MODULE = "SHENORA";
+/** Reserved wire route: the ready handshake type. */
+export declare const HANDSHAKE_TYPE = "READY";
+/**
+ * Error codes with framework-reserved meaning (`errors.{code}` is the family i18n-key
+ * convention). `timeout` and `noTransport` are CLIENT-side failures — they never come from the
+ * host but reject through the same structured shape so error handling stays uniform.
+ */
+export declare const IpcErrorCodes: {
+    readonly unknownError: "UNKNOWN_ERROR";
+    readonly noHandler: "NO_HANDLER";
+    /**
+     * 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.
+     */
+    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`.
+     */
+    readonly operationCancelled: "OPERATION_CANCELLED";
+    /** Client-only: the request timed out waiting for a response. */
+    readonly timeout: "TIMEOUT";
+    /** Client-only: no transport is available and no fallback was configured. */
+    readonly noTransport: "NO_TRANSPORT";
+};
+/**
+ * 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.
+ */
+export declare const ClientOnlyIpcErrorCodes: readonly string[];
+/** The request envelope a client sends to the host. */
+export interface IpcRequest<TPayload = unknown> {
+    /** Correlation id, echoed back on the response. */
+    id: string;
+    /** Routing: the module the request targets (e.g. `"APP"`). */
+    module: string;
+    /** Routing: the action within the module (e.g. `"GET_ALL"`). */
+    type: string;
+    /** Optional app-defined routing scope. */
+    scope?: string;
+    payload?: TPayload;
+    /** ISO-8601 send time. */
+    timestamp: string;
+}
+/** The structured error carried by a failed response. `code` is the i18n key (`errors.{code}`). */
+export interface IpcError {
+    code: string;
+    /** Untranslated fallback message for logs/dev; not for end users. */
+    message?: string;
+    /** Values interpolated into the translated message. */
+    parameters?: Record<string, string>;
+}
+/** The response envelope the host returns for an {@link IpcRequest}. */
+export interface IpcResponse<TData = unknown> {
+    category: typeof IpcCategories.ipc;
+    /** The request id this responds to. */
+    id: string;
+    success: boolean;
+    data?: TData;
+    error?: IpcError;
+}
+/** One host→client event inside an {@link IpcNotificationBatch}. Fire-and-forget. */
+export interface IpcNotification<TPayload = unknown> {
+    module: string;
+    type: string;
+    payload?: TPayload;
+    scope?: string;
+}
+/**
+ * The host→client push envelope: notifications batched every ~50 ms host-side. Always a batch —
+ * a single notification ships as a batch of one; `category` alone discriminates.
+ */
+export interface IpcNotificationBatch {
+    category: typeof IpcCategories.notification;
+    id: string;
+    payload: IpcNotification[];
+    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).
+ */
+export interface EventMessage<TPayload = unknown> {
+    module: string;
+    type: string;
+    payload?: TPayload;
+    scope?: string;
+}

package/dist/types.js

@@ -0,0 +1,53 @@
+/**
+ * The Shenora IPC wire contract — the TS mirror of the `Shenora.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.
+ */
+/** Values of the `category` discriminator on host→client messages. */
+export const IpcCategories = {
+    /** A response to a client request. */
+    ipc: 'ipc',
+    /** A host-pushed notification batch. */
+    notification: 'notification',
+};
+/** Reserved wire route: the ready handshake the host bridge intercepts (mirror of the host consts). */
+export const HANDSHAKE_MODULE = 'SHENORA';
+/** Reserved wire route: the ready handshake type. */
+export const HANDSHAKE_TYPE = 'READY';
+/**
+ * Error codes with framework-reserved meaning (`errors.{code}` is the family i18n-key
+ * convention). `timeout` and `noTransport` are CLIENT-side failures — they never come from the
+ * host but reject through the same structured shape so error handling stays uniform.
+ */
+export const IpcErrorCodes = {
+    unknownError: 'UNKNOWN_ERROR',
+    noHandler: 'NO_HANDLER',
+    /**
+     * 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.
+     */
+    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`.
+     */
+    operationCancelled: 'OPERATION_CANCELLED',
+    /** Client-only: the request timed out waiting for a response. */
+    timeout: 'TIMEOUT',
+    /** Client-only: no transport is available and no fallback was configured. */
+    noTransport: 'NO_TRANSPORT',
+};
+/**
+ * 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.
+ */
+export const ClientOnlyIpcErrorCodes = [
+    IpcErrorCodes.timeout,
+    IpcErrorCodes.noTransport,
+];

package/dist/useDropZone.d.ts

@@ -0,0 +1,56 @@
+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";
+/** A native file drop delivered to a zone. */
+export interface DropZoneFileDrop {
+    zoneId: string;
+    /** REAL OS paths — the whole point: the DOM's drop events only ever see blob URLs. */
+    files: string[];
+    /** Drop position in the zone's physical pixels. */
+    position: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * 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.)
+ */
+export interface UseDropZoneOptions {
+    /** The element the native overlay tracks. */
+    targetRef: RefObject<HTMLElement | null>;
+    /** Called with the dropped OS file paths. */
+    onDrop: (files: string[], drop: DropZoneFileDrop) => void;
+    /** False = zone torn down (same as unmount). Default true. */
+    enabled?: boolean;
+    /** Stable zone id; default: generated per mount. */
+    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"`.
+     */
+    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;
+}
+/**
+ * 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 declare function useDropZone(options: UseDropZoneOptions): void;