@shenora/react 0.1.0

package/dist/devInterceptor.js

@@ -0,0 +1,92 @@
+/**
+ * Dev-only IPC + event-hub interceptor, ported from the primary desktop sibling (NEVER ship it
+ * in prod — gate the single call site with `import.meta.env.DEV`).
+ *
+ * Why: during desktop-app testing the agent drives the UI over CDP, but native dialogs and
+ * event-driven flows can't be exercised by clicking. This wraps the bridge's `invoke` (the IPC
+ * seam) and the event bus's `emit` (the event hub) to (1) record + console.debug every
+ * request/response/event into ring buffers, and (2) expose a window global so a CDP eval can
+ * invoke ANY IPC directly and await events:
+ *
+ *   window.__shenora.call('NOTES', 'ADD', { title: 'x' })   // drive an IPC, bypass the UI
+ *   window.__shenora.waitEvent('NOTES', 'ADDED')            // resolves on the next emit
+ *   window.__shenora.recentIpc(20) / .recentEvents(20)     // inspect traffic
+ */
+import { getBridge } from './bridge.js';
+import { eventBus as defaultEventBus } from './eventBus.js';
+/**
+ * Install the interceptor (idempotent across HMR / StrictMode double-invoke — keyed on the
+ * window global).
+ */
+export function installDevInterceptor(options = {}) {
+    if (typeof window === 'undefined')
+        return;
+    const globalName = options.globalName ?? '__shenora';
+    const w = window;
+    if (w[globalName])
+        return;
+    const ringSize = options.ringSize ?? 300;
+    const bridge = options.bridge ?? getBridge();
+    const bus = options.bus ?? defaultEventBus;
+    const ipc = [];
+    const events = [];
+    const push = (buffer, entry) => {
+        buffer.push(entry);
+        if (buffer.length > ringSize)
+            buffer.shift();
+    };
+    // --- wrap the IPC send seam ---
+    const originalInvoke = bridge.invoke.bind(bridge);
+    bridge.invoke = (module, type, invokeOptions = {}) => {
+        const start = performance.now();
+        const entry = { t: Date.now(), module, type, payload: invokeOptions.payload };
+        push(ipc, entry);
+        console.debug(`[IPC →] ${module}.${type}`, invokeOptions.payload);
+        return originalInvoke(module, type, invokeOptions).then((result) => {
+            entry.ms = Math.round(performance.now() - start);
+            entry.ok = true;
+            entry.result = result;
+            console.debug(`[IPC ✓] ${module}.${type} (${entry.ms}ms)`, result);
+            return result;
+        }, (error) => {
+            entry.ms = Math.round(performance.now() - start);
+            entry.ok = false;
+            entry.error = error?.message;
+            console.debug(`[IPC ✗] ${module}.${type} (${entry.ms}ms)`, error?.message);
+            throw error;
+        });
+    };
+    // --- wrap the event hub ---
+    const originalEmit = bus.emit.bind(bus);
+    bus.emit = (event) => {
+        push(events, { t: Date.now(), module: event.module, type: event.type, payload: event.payload });
+        console.debug(`[EVT] ${event.module}.${event.type}`, event.payload);
+        originalEmit(event);
+    };
+    w[globalName] = {
+        bridge,
+        eventBus: bus,
+        ipc,
+        events,
+        /** Drive ANY IPC directly (bypasses native dialogs / UI). Returns the response promise. */
+        call: (module, type, payload, scope) => bridge.invoke(module, type, { payload, scope }),
+        /** Resolve on the next matching event (or null on timeout) — for CDP awaitPromise verification. */
+        waitEvent: (module, type, timeoutMs = 8000) => new Promise((resolve) => {
+            const off = bus.subscribe(module, type, (event) => {
+                off();
+                resolve(event);
+            });
+            setTimeout(() => {
+                off();
+                resolve(null);
+            }, timeoutMs);
+        }),
+        recentIpc: (n = 20) => ipc.slice(-n),
+        recentEvents: (n = 20) => events.slice(-n),
+        clear: () => {
+            ipc.length = 0;
+            events.length = 0;
+        },
+    };
+    console.info(`[shenora] dev interceptor installed → window.${globalName} (call(), waitEvent(), recentIpc(), recentEvents())`);
+}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+import type { IpcError } from './types.js';
+/**
+ * The rejection type for every failed bridge call — the client mirror of the host's
+ * `OperationException` (the `Error` suffix is the TS idiom; the C# type keeps the platform's
+ * `Exception` suffix). Carries the structured code + parameters so callers translate
+ * `errors.{code}` instead of matching message strings. Client-side failures (timeout, missing
+ * transport) reject through this same shape with the client-reserved codes.
+ */
+export declare class OperationError extends Error {
+    /** Error code / i18n key (e.g. `"IMPORT_FAILED"`, `"TIMEOUT"`). */
+    readonly code: string;
+    /** Values the client interpolates into the translated message. */
+    readonly parameters?: Record<string, string>;
+    constructor(error: IpcError);
+}

package/dist/errors.js

@@ -0,0 +1,15 @@
+/**
+ * The rejection type for every failed bridge call — the client mirror of the host's
+ * `OperationException` (the `Error` suffix is the TS idiom; the C# type keeps the platform's
+ * `Exception` suffix). Carries the structured code + parameters so callers translate
+ * `errors.{code}` instead of matching message strings. Client-side failures (timeout, missing
+ * transport) reject through this same shape with the client-reserved codes.
+ */
+export class OperationError extends Error {
+    constructor(error) {
+        super(error.message ?? error.code);
+        this.name = 'OperationError';
+        this.code = error.code;
+        this.parameters = error.parameters;
+    }
+}

package/dist/eventBus.d.ts

@@ -0,0 +1,74 @@
+import type { EventMessage } from './types.js';
+/** Optional narrowing for the {@link ShenoraEventBus} subscribe methods. */
+export interface SubscribeOptions {
+    /**
+     * Only receive events carrying this app-defined scope. Omit to receive EVERY scope.
+     *
+     * The semantics mirror the host's `EventBus` exactly, and both halves matter: an unscoped
+     * subscription sees every scope, AND a scope-less (global) event still reaches scoped subscribers —
+     * so an app-wide announcement is not swallowed by a per-scope listener.
+     */
+    scope?: string;
+}
+/**
+ * The client-side event hub, ported from the primary desktop sibling: host notifications are
+ * unbundled into it by the bridge, and app code (or the dev interceptor) can emit locally.
+ * Event enums/maps are app schema, so apps layer their own typed wrappers on top (headless per D13).
+ * A throwing handler is isolated: it never breaks the other subscribers or the emitter.
+ *
+ * Three subscription breadths, mirroring the host's `Shenora.Core.IEventBus`: an exact
+ * `(module, type)` pair, a whole {@link subscribeToModule | module}, or
+ * {@link subscribeToAll | everything}. The broad two were added in P6.4 — the host had shipped them
+ * from the start (`WebViewIpcBridge` itself consumes `SubscribeToAll`), so the client was the
+ * asymmetric half of one concept and an observer that cannot enumerate the event vocabulary up front
+ * had no supported expression at all.
+ */
+export declare class ShenoraEventBus {
+    /** Exact `(module, type)` subscriptions, keyed by {@link eventKey}. */
+    private exact;
+    /** Whole-module subscriptions, keyed by module. */
+    private byModule;
+    /** Catch-all subscriptions. */
+    private all;
+    /**
+     * Subscribe to one (module, type), optionally narrowed to a scope; returns the cleanup function
+     * (React-effect friendly).
+     */
+    subscribe<TPayload = unknown>(module: string, type: string, handler: (event: EventMessage<TPayload>) => void, options?: SubscribeOptions): () => void;
+    /**
+     * Subscribe to EVERY event from one module, whatever its type; returns the cleanup function.
+     *
+     * For a feature whose event vocabulary is open — plug-in-contributed types, a module that grows
+     * types over time — where enumerating pairs would mean editing the subscriber every time the host
+     * gains an event.
+     */
+    subscribeToModule<TPayload = unknown>(module: string, handler: (event: EventMessage<TPayload>) => void, options?: SubscribeOptions): () => void;
+    /**
+     * Subscribe to EVERY event on the bus; returns the cleanup function.
+     *
+     * The breadth is the point, so use it for cross-cutting observers — a diagnostics overlay, a
+     * telemetry tap, a bridge that folds the whole stream into another state library, or an adoption
+     * shim keeping a legacy "every host message" handler alive while individual features migrate onto
+     * exact pairs. It is NOT the way to consume one feature's events: prefer {@link subscribe}, which
+     * says what it listens for and does not wake for unrelated traffic.
+     */
+    subscribeToAll<TPayload = unknown>(handler: (event: EventMessage<TPayload>) => void, options?: SubscribeOptions): () => void;
+    /**
+     * Emit to every matching subscriber (see {@link SubscribeOptions.scope} for the scope rule).
+     *
+     * Delivery order is stable: exact pair, then whole-module, then catch-all — narrowest first, so a
+     * broad observer never runs ahead of the feature code it is observing.
+     */
+    emit(event: EventMessage): void;
+    /** Remove every subscription (tests). */
+    clear(): void;
+    /**
+     * Subscription count (diagnostics). With no arguments: every subscription of any breadth. With a
+     * `(module, type)`: every subscription that WOULD receive that pair — exact, whole-module and
+     * catch-all — because "how many listeners does this event have?" is the question a diagnostic is
+     * actually asking. Scope is not applied; a count is not a delivery.
+     */
+    getSubscriptionCount(module?: string, type?: string): number;
+}
+/** The shared event bus the default bridge unbundles into. */
+export declare const eventBus: ShenoraEventBus;

package/dist/eventBus.js

@@ -0,0 +1,158 @@
+/**
+ * The client-side event hub, ported from the primary desktop sibling: host notifications are
+ * unbundled into it by the bridge, and app code (or the dev interceptor) can emit locally.
+ * Event enums/maps are app schema, so apps layer their own typed wrappers on top (headless per D13).
+ * A throwing handler is isolated: it never breaks the other subscribers or the emitter.
+ *
+ * Three subscription breadths, mirroring the host's `Shenora.Core.IEventBus`: an exact
+ * `(module, type)` pair, a whole {@link subscribeToModule | module}, or
+ * {@link subscribeToAll | everything}. The broad two were added in P6.4 — the host had shipped them
+ * from the start (`WebViewIpcBridge` itself consumes `SubscribeToAll`), so the client was the
+ * asymmetric half of one concept and an observer that cannot enumerate the event vocabulary up front
+ * had no supported expression at all.
+ */
+export class ShenoraEventBus {
+    constructor() {
+        /** Exact `(module, type)` subscriptions, keyed by {@link eventKey}. */
+        this.exact = new Map();
+        /** Whole-module subscriptions, keyed by module. */
+        this.byModule = new Map();
+        /** Catch-all subscriptions. */
+        this.all = new Set();
+    }
+    /**
+     * Subscribe to one (module, type), optionally narrowed to a scope; returns the cleanup function
+     * (React-effect friendly).
+     */
+    subscribe(module, type, handler, options = {}) {
+        return addTo(this.exact, eventKey(module, type), newSubscription(handler, options));
+    }
+    /**
+     * Subscribe to EVERY event from one module, whatever its type; returns the cleanup function.
+     *
+     * For a feature whose event vocabulary is open — plug-in-contributed types, a module that grows
+     * types over time — where enumerating pairs would mean editing the subscriber every time the host
+     * gains an event.
+     */
+    subscribeToModule(module, handler, options = {}) {
+        return addTo(this.byModule, module, newSubscription(handler, options));
+    }
+    /**
+     * Subscribe to EVERY event on the bus; returns the cleanup function.
+     *
+     * The breadth is the point, so use it for cross-cutting observers — a diagnostics overlay, a
+     * telemetry tap, a bridge that folds the whole stream into another state library, or an adoption
+     * shim keeping a legacy "every host message" handler alive while individual features migrate onto
+     * exact pairs. It is NOT the way to consume one feature's events: prefer {@link subscribe}, which
+     * says what it listens for and does not wake for unrelated traffic.
+     */
+    subscribeToAll(handler, options = {}) {
+        const subscription = newSubscription(handler, options);
+        this.all.add(subscription);
+        return () => { this.all.delete(subscription); };
+    }
+    /**
+     * Emit to every matching subscriber (see {@link SubscribeOptions.scope} for the scope rule).
+     *
+     * Delivery order is stable: exact pair, then whole-module, then catch-all — narrowest first, so a
+     * broad observer never runs ahead of the feature code it is observing.
+     */
+    emit(event) {
+        const exact = this.exact.get(eventKey(event.module, event.type));
+        const byModule = this.byModule.get(event.module);
+        if (!exact?.size && !byModule?.size && this.all.size === 0)
+            return;
+        // Snapshot ALL THREE breadths before invoking any handler, not one at a time. A handler may
+        // subscribe or unsubscribe during delivery, and one event must reach exactly the subscribers
+        // that existed when it was emitted. Reading the broad collections lazily — after the exact
+        // handlers had already run — would let a handler that subscribes broadly while handling receive
+        // the very event it is handling. Copying per-set was enough while there was only one set.
+        for (const subscription of [...(exact ?? []), ...(byModule ?? []), ...this.all]) {
+            if (!scopeMatches(subscription.scope, event.scope))
+                continue;
+            try {
+                subscription.handler(event);
+            }
+            catch (error) {
+                // One subscriber's failure must not break the others.
+                console.error(`[shenora] event handler failed for ${event.module}/${event.type}:`, error);
+            }
+        }
+    }
+    /** Remove every subscription (tests). */
+    clear() {
+        this.exact.clear();
+        this.byModule.clear();
+        this.all.clear();
+    }
+    /**
+     * Subscription count (diagnostics). With no arguments: every subscription of any breadth. With a
+     * `(module, type)`: every subscription that WOULD receive that pair — exact, whole-module and
+     * catch-all — because "how many listeners does this event have?" is the question a diagnostic is
+     * actually asking. Scope is not applied; a count is not a delivery.
+     */
+    getSubscriptionCount(module, type) {
+        if (module && type) {
+            return (this.exact.get(eventKey(module, type))?.size ?? 0)
+                + (this.byModule.get(module)?.size ?? 0)
+                + this.all.size;
+        }
+        let total = this.all.size;
+        for (const set of this.exact.values())
+            total += set.size;
+        for (const set of this.byModule.values())
+            total += set.size;
+        return total;
+    }
+}
+/** The one place a handler is widened to the stored shape, so the three breadths cannot drift. */
+function newSubscription(handler, options) {
+    return { handler: handler, scope: options.scope };
+}
+/** Shared add-and-prune for the two keyed collections (an empty key is removed, as it always was). */
+function addTo(collection, key, subscription) {
+    let set = collection.get(key);
+    if (!set) {
+        set = new Set();
+        collection.set(key, set);
+    }
+    set.add(subscription);
+    return () => {
+        const current = collection.get(key);
+        if (!current)
+            return;
+        current.delete(subscription);
+        if (current.size === 0)
+            collection.delete(key);
+    };
+}
+/**
+ * `'\0'`-joined, NOT `.`-joined (P5.5 H6).
+ *
+ * Module and type are both arbitrary app-defined strings, so a `.` separator makes
+ * `("APP", "TASK.DONE")` and `("APP.TASK", "DONE")` the same key — one app's events silently delivered
+ * to another's subscribers. The host's `EventBus` fixed exactly this and documented it; the client kept
+ * the colliding form, so the two halves of one contract disagreed. `'\0'` cannot appear in a JS string
+ * literal a developer types by accident, which is what makes it safe as a separator.
+ *
+ * The broad subscriptions deliberately do NOT reuse this with a `"*"` sentinel the way the host's
+ * pattern matcher does: a module or type legitimately named `*` would then silently become a
+ * catch-all. Separate collections cannot collide with an app string at all — same lesson as above,
+ * applied before it could be earned a second time.
+ */
+function eventKey(module, type) {
+    return `${module}\0${type}`;
+}
+/**
+ * The host's rule, restated: no subscriber scope = every scope; no event scope = a global event that
+ * reaches scoped subscribers too. Otherwise they must be equal.
+ */
+function scopeMatches(subscriptionScope, eventScope) {
+    if (!subscriptionScope)
+        return true;
+    if (!eventScope)
+        return true;
+    return subscriptionScope === eventScope;
+}
+/** The shared event bus the default bridge unbundles into. */
+export const eventBus = new ShenoraEventBus();

package/dist/hooks.d.ts

@@ -0,0 +1,45 @@
+import { type ShenoraBridge } from './bridge.js';
+import { type ShenoraEventBus } from './eventBus.js';
+import type { EventMessage } from './types.js';
+/** Host access for components: the (default) bridge and whether a host transport exists. */
+export declare function useShenora(): {
+    isAvailable: boolean;
+    bridge: ShenoraBridge;
+};
+/**
+ * Subscribe to one (module, type) event for the component's lifetime, ported from the primary
+ * desktop sibling. The handler receives the unwrapped payload (plus the full event). DEVIATION
+ * from the source: instead of a deps array re-subscribing on change, the latest handler is kept
+ * in a ref — no re-subscribe churn, no stale-closure trap.
+ *
+ * Pass `scope` for a scoped app: the wire carries a scope and the host keys on it, but this hook had
+ * no way to express one, so a component in profile A also woke for profile B's events with no filter
+ * available (P5.5 H6). Omitting it still means "every scope", and a global (scope-less) event still
+ * reaches a scoped subscriber — the host's rule, mirrored.
+ */
+export declare function useShenoraEvent<TPayload = unknown>(module: string, type: string, handler: (payload: TPayload, event: EventMessage<TPayload>) => void, options?: {
+    bus?: ShenoraEventBus;
+    scope?: string;
+}): void;
+/** Result of {@link useShenoraQuery}. */
+export interface ShenoraQueryResult<TData> {
+    data: TData | undefined;
+    error: Error | undefined;
+    /** True while a fetch is in flight. */
+    loading: boolean;
+    /** Re-run the query. */
+    refetch: () => void;
+}
+/**
+ * Fetch-on-mount over the bridge: `invoke` + `{data, error, loading, refetch}`. Deliberately
+ * minimal — no caching, no dedup, no background refresh (headless, D13): apps with data-layer
+ * needs bring their own query library and call `bridge.invoke` from it. The payload participates
+ * in the effect key BY VALUE (JSON), so inline object literals don't refetch every render.
+ */
+export declare function useShenoraQuery<TData = unknown, TPayload = unknown>(module: string, type: string, options?: {
+    payload?: TPayload;
+    scope?: string;
+    /** False = don't fetch (yet). Default true. */
+    enabled?: boolean;
+    bridge?: ShenoraBridge;
+}): ShenoraQueryResult<TData>;

package/dist/hooks.js

@@ -0,0 +1,69 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { getBridge } from './bridge.js';
+import { eventBus as defaultEventBus } from './eventBus.js';
+/** Host access for components: the (default) bridge and whether a host transport exists. */
+export function useShenora() {
+    const bridge = getBridge();
+    return { isAvailable: bridge.isAvailable, bridge };
+}
+/**
+ * Subscribe to one (module, type) event for the component's lifetime, ported from the primary
+ * desktop sibling. The handler receives the unwrapped payload (plus the full event). DEVIATION
+ * from the source: instead of a deps array re-subscribing on change, the latest handler is kept
+ * in a ref — no re-subscribe churn, no stale-closure trap.
+ *
+ * Pass `scope` for a scoped app: the wire carries a scope and the host keys on it, but this hook had
+ * no way to express one, so a component in profile A also woke for profile B's events with no filter
+ * available (P5.5 H6). Omitting it still means "every scope", and a global (scope-less) event still
+ * reaches a scoped subscriber — the host's rule, mirrored.
+ */
+export function useShenoraEvent(module, type, handler, options = {}) {
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const bus = options.bus ?? defaultEventBus;
+    const scope = options.scope;
+    useEffect(() => bus.subscribe(module, type, (event) => handlerRef.current(event.payload, event), { scope }), [module, type, bus, scope]);
+}
+/**
+ * Fetch-on-mount over the bridge: `invoke` + `{data, error, loading, refetch}`. Deliberately
+ * minimal — no caching, no dedup, no background refresh (headless, D13): apps with data-layer
+ * needs bring their own query library and call `bridge.invoke` from it. The payload participates
+ * in the effect key BY VALUE (JSON), so inline object literals don't refetch every render.
+ */
+export function useShenoraQuery(module, type, options = {}) {
+    const { payload, scope, enabled = true } = options;
+    const bridge = options.bridge ?? getBridge();
+    const [state, setState] = useState({
+        data: undefined,
+        error: undefined,
+        loading: enabled,
+    });
+    const [fetchToken, setFetchToken] = useState(0);
+    const payloadKey = payload === undefined ? '' : JSON.stringify(payload);
+    const payloadRef = useRef(payload);
+    payloadRef.current = payload;
+    useEffect(() => {
+        if (!enabled) {
+            // A fetch in flight when enabled flipped false was marked stale by the cleanup — without
+            // this, `loading` would stay true forever (a spinner that never stops).
+            setState((previous) => (previous.loading ? { ...previous, loading: false } : previous));
+            return;
+        }
+        let stale = false;
+        setState((previous) => ({ ...previous, loading: true }));
+        bridge
+            .invoke(module, type, { payload: payloadRef.current, scope })
+            .then((data) => { if (!stale)
+            setState({ data, error: undefined, loading: false }); }, 
+        // KEEP the previous data alongside the error (P5.5 H2). This used to set `data: undefined`, so
+        // a failed REFETCH — a transient host hiccup, one timed-out call — blanked data the UI was
+        // already showing correctly, turning a recoverable error into an empty screen. The caller has
+        // both fields and can decide: render stale data with an error banner, or hide it. Blanking it
+        // for them removes that choice. (A first fetch has no previous data, so it is unaffected.)
+        (error) => { if (!stale)
+            setState((previous) => ({ data: previous.data, error, loading: false })); });
+        return () => { stale = true; };
+    }, [module, type, scope, enabled, bridge, payloadKey, fetchToken]);
+    const refetch = useCallback(() => setFetchToken((token) => token + 1), []);
+    return { ...state, refetch };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { IpcCategories, IpcErrorCodes, HANDSHAKE_MODULE, HANDSHAKE_TYPE, type IpcRequest, type IpcResponse, type IpcError, type IpcNotification, type IpcNotificationBatch, type EventMessage, } from './types.js';
+export { OperationError } from './errors.js';
+export { isShenoraAvailable, createWebView2Transport, type ShenoraTransport } from './transport.js';
+export { ShenoraEventBus, eventBus } from './eventBus.js';
+export { ShenoraBridge, getBridge, configureBridge, type ShenoraBridgeOptions, type InvokeOptions, type PostOptions, type PostFailure, } from './bridge.js';
+export { createShenoraStore, type ShenoraStore, type ShenoraStoreOptions, type ShenoraStoreIo, type ShenoraStoreSnapshot, } from './store.js';
+export { BaseModuleService } from './moduleService.js';
+export { WindowCommands, useWindowMaximized, type WindowResizeEdge, type CaptionButtonKind, type CaptionButtonRect, } from './windowCommands.js';
+export { useDropZone, DROP_ZONE_MODULE, type DropZoneFileDrop, type UseDropZoneOptions, } from './useDropZone.js';
+export { useShenora, useShenoraEvent, useShenoraQuery, type ShenoraQueryResult } from './hooks.js';
+export { installDevInterceptor, type DevInterceptorOptions, type DevIpcEntry, type DevEventEntry, } from './devInterceptor.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+// @shenora/react — the client side of the Shenora desktop body: correlated invoke over a
+// pluggable transport, the event hub host notifications unbundle into, typed module services,
+// React hooks, and the dev interceptor for CDP-driven testing. Headless by design (D13): no UI
+// components, no design-system dependency — apps bring their own.
+export { IpcCategories, IpcErrorCodes, HANDSHAKE_MODULE, HANDSHAKE_TYPE, } from './types.js';
+export { OperationError } from './errors.js';
+export { isShenoraAvailable, createWebView2Transport } from './transport.js';
+export { ShenoraEventBus, eventBus } from './eventBus.js';
+export { ShenoraBridge, getBridge, configureBridge, } from './bridge.js';
+export { createShenoraStore, } from './store.js';
+export { BaseModuleService } from './moduleService.js';
+export { WindowCommands, useWindowMaximized, } from './windowCommands.js';
+export { useDropZone, DROP_ZONE_MODULE, } from './useDropZone.js';
+export { useShenora, useShenoraEvent, useShenoraQuery } from './hooks.js';
+export { installDevInterceptor, } from './devInterceptor.js';

package/dist/internal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared internals for `@shenora/react`. NOT exported from the barrel — nothing here is public
+ * surface, and it must not become so by accident.
+ *
+ * These lived as per-file copies until a second consumer appeared for each (P5.5 H2): the debounce
+ * helper was private to `useDropZone` and `useWindowMaximized` needed the same thing, and the
+ * `randomUUID`-with-fallback pair had drifted into two spellings. H4.5 deliberately left both alone
+ * at the time, on the grounds that the package had no shared-internals home and inventing one for a
+ * single consumer is speculation — this file exists now because the need is real.
+ */
+/** A debounced void callback with a `cancel` for effect teardown. */
+export interface Debounced {
+    (): void;
+    cancel(): void;
+}
+/**
+ * Trailing-edge debounce: the callback runs `ms` after the LAST call. `cancel` must be called from a
+ * React effect's cleanup, or a pending timer fires against an unmounted component.
+ */
+export declare function debounce(fn: () => void, ms: number): Debounced;
+/**
+ * A unique id, optionally prefixed. Correlation ids and zone ids only need uniqueness, not entropy,
+ * so the non-`crypto` fallback (ancient or non-secure-context environments) is fine.
+ */
+export declare function randomId(prefix?: string): string;

package/dist/internal.js

@@ -0,0 +1,33 @@
+/**
+ * Shared internals for `@shenora/react`. NOT exported from the barrel — nothing here is public
+ * surface, and it must not become so by accident.
+ *
+ * These lived as per-file copies until a second consumer appeared for each (P5.5 H2): the debounce
+ * helper was private to `useDropZone` and `useWindowMaximized` needed the same thing, and the
+ * `randomUUID`-with-fallback pair had drifted into two spellings. H4.5 deliberately left both alone
+ * at the time, on the grounds that the package had no shared-internals home and inventing one for a
+ * single consumer is speculation — this file exists now because the need is real.
+ */
+/**
+ * Trailing-edge debounce: the callback runs `ms` after the LAST call. `cancel` must be called from a
+ * React effect's cleanup, or a pending timer fires against an unmounted component.
+ */
+export function debounce(fn, ms) {
+    let timer;
+    const wrapped = (() => {
+        clearTimeout(timer);
+        timer = setTimeout(fn, ms);
+    });
+    wrapped.cancel = () => clearTimeout(timer);
+    return wrapped;
+}
+/**
+ * A unique id, optionally prefixed. Correlation ids and zone ids only need uniqueness, not entropy,
+ * so the non-`crypto` fallback (ancient or non-secure-context environments) is fine.
+ */
+export function randomId(prefix) {
+    const id = typeof crypto !== 'undefined' && 'randomUUID' in crypto
+        ? crypto.randomUUID()
+        : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    return prefix === undefined ? id : `${prefix}${id}`;
+}

package/dist/moduleService.d.ts

@@ -0,0 +1,61 @@
+import { type ShenoraBridge } 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 declare abstract class BaseModuleService<TRequests extends object = Record<string, unknown>> {
+    /** The backend module this service fronts (e.g. `"NOTES"`). */
+    protected readonly module: string;
+    /**
+     * The bridge to speak over. Omit to use the shared default bridge, resolved PER CALL — see
+     * {@link bridge}.
+     */
+    private readonly explicitBridge?;
+    protected constructor(
+    /** The backend module this service fronts (e.g. `"NOTES"`). */
+    module: string, 
+    /**
+     * The bridge to speak over. Omit to use the shared default bridge, resolved PER CALL — see
+     * {@link bridge}.
+     */
+    explicitBridge?: ShenoraBridge | undefined);
+    /**
+     * 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.
+     */
+    protected get bridge(): ShenoraBridge;
+    /** Send one typed request to this module and await the typed response data. */
+    protected send<TResponse = unknown, TType extends keyof TRequests & string = keyof TRequests & string>(type: TType, options?: {
+        payload?: TRequests[TType];
+        scope?: string;
+        timeoutMs?: number;
+    }): Promise<TResponse>;
+}