@shenora/react 0.10.0 → 0.12.0

package/dist/internal.js

@@ -1,12 +1,6 @@
 /**
  * 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
@@ -22,8 +16,8 @@ export function debounce(fn, ms) {
     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.
+ * A unique id, optionally prefixed. Correlation ids and zone ids need uniqueness, not entropy, so the
+ * non-`crypto` fallback for a non-secure context is fine.
  */
 export function randomId(prefix) {
     const id = typeof crypto !== 'undefined' && 'randomUUID' in crypto

package/dist/media.d.ts

@@ -1,15 +1,12 @@
 /**
  * Building the URL that lets a page render LOCAL content — media, images, documents, exports — that it
- * cannot reach directly.
- *
- * The host answers these through its resource interceptor; this module only builds the address, which is
- * why it is a pure function and not a hook. A hook (`useMediaSource`) can follow if an adopter wants
- * load/error state, but nothing needs one to start.
+ * cannot reach directly. The host answers these through its resource interceptor; this module only
+ * builds the address, which is why it is a pure function and not a hook.
  */
 /**
  * Build a URL the host's resource interceptor will answer: `<route>?<base64url of JSON>`.
  *
- * ⚠ **The result is RELATIVE, and that is the whole point.** Written as a path rather than with a scheme, it
+ * ⚠ **The result is RELATIVE, and that is load-bearing.** Written as a path rather than with a scheme, it
  * resolves against whatever origin the page is already served from — which means the browser hands the host
  * a URL each platform can actually decode:
  *
@@ -19,19 +16,16 @@
  * | Android | `https://0.0.0.1/media?…` — Android's media pipeline REFUSES a non-standard scheme |
  * | desktop | the app's virtual host |
  *
- * Both fixed forms fail on exactly one platform, in opposite directions, and registering the scheme rescues
- * neither: iOS cannot register a handler for `https`, and Android cannot register a scheme at all. Measured
- * on devices — so if you are tempted to hardcode `app://`, that is why not.
- *
- * The PAYLOAD is opaque to this package: whatever you pass is JSON-encoded and handed to your own host-side
- * route, which decodes it. That keeps the kit out of your addressing scheme — a filename, an id, a container
- * preference, a cache key, several of them. The kit encodes; you decide what it means.
+ * 🔴 **So do not hardcode `app://`.** Either fixed form fails on exactly one platform, and registering the
+ * scheme rescues neither: iOS cannot register a handler for `https`, and Android cannot register a scheme
+ * at all.
  *
- * base64**url** specifically, so `+`, `/` and `=` cannot survive into a query string and be re-interpreted
- * by anything that parses URLs along the way.
+ * The payload is opaque to this package — JSON-encoded and handed to your own host-side route, which
+ * decodes it. base64**url** specifically, so `+`, `/` and `=` cannot be re-interpreted by anything that
+ * parses URLs along the way.
  *
- * ⚠ An encoded payload costs debuggability — you cannot read the URL in a log any more. Have the host log
- * what it DECODED to: the response body cannot say, because an error body would leak paths.
+ * ⚠ An encoded payload costs debuggability: have the HOST log what it decoded to, because an error
+ * response body cannot say without leaking paths.
  *
  * @param payload Anything JSON-serialisable. Your host route decides what the shape means.
  * @param route The reserved path the host answers on. **Must not collide with a real asset in your bundle** —
@@ -52,14 +46,12 @@ export declare function mediaUrl(payload: unknown, route?: string): string;
  * The payload encoding on its own, for a caller that builds its own URL but wants the same wire format —
  * and so a host-side decoder has one documented thing to mirror.
  *
- * `TextEncoder` before `btoa` because `btoa` throws on any character above U+00FF: a payload carrying a
- * non-ASCII title or path would fail at the call site, which is a poor way to discover an encoding choice.
+ * ⚠ `TextEncoder` before `btoa`, which throws on any character above U+00FF — a payload carrying a
+ * non-ASCII title or path would fail at the call site.
  */
 export declare function encodeMediaPayload(payload: unknown): string;
 /**
  * Decode what {@link encodeMediaPayload} produced. Here for tests and for a page that round-trips its own
- * URLs; the real decoder is host-side, in whatever language the shell is written in.
- *
- * Padding is restored before decoding — base64url drops `=`, and `atob` requires it.
+ * URLs; the real decoder is host-side. Padding is restored first — base64url drops `=`, `atob` needs it.
  */
 export declare function decodeMediaPayload<T = unknown>(encoded: string): T;

package/dist/media.js

@@ -1,15 +1,12 @@
 /**
  * Building the URL that lets a page render LOCAL content — media, images, documents, exports — that it
- * cannot reach directly.
- *
- * The host answers these through its resource interceptor; this module only builds the address, which is
- * why it is a pure function and not a hook. A hook (`useMediaSource`) can follow if an adopter wants
- * load/error state, but nothing needs one to start.
+ * cannot reach directly. The host answers these through its resource interceptor; this module only
+ * builds the address, which is why it is a pure function and not a hook.
  */
 /**
  * Build a URL the host's resource interceptor will answer: `<route>?<base64url of JSON>`.
  *
- * ⚠ **The result is RELATIVE, and that is the whole point.** Written as a path rather than with a scheme, it
+ * ⚠ **The result is RELATIVE, and that is load-bearing.** Written as a path rather than with a scheme, it
  * resolves against whatever origin the page is already served from — which means the browser hands the host
  * a URL each platform can actually decode:
  *
@@ -19,19 +16,16 @@
  * | Android | `https://0.0.0.1/media?…` — Android's media pipeline REFUSES a non-standard scheme |
  * | desktop | the app's virtual host |
  *
- * Both fixed forms fail on exactly one platform, in opposite directions, and registering the scheme rescues
- * neither: iOS cannot register a handler for `https`, and Android cannot register a scheme at all. Measured
- * on devices — so if you are tempted to hardcode `app://`, that is why not.
- *
- * The PAYLOAD is opaque to this package: whatever you pass is JSON-encoded and handed to your own host-side
- * route, which decodes it. That keeps the kit out of your addressing scheme — a filename, an id, a container
- * preference, a cache key, several of them. The kit encodes; you decide what it means.
+ * 🔴 **So do not hardcode `app://`.** Either fixed form fails on exactly one platform, and registering the
+ * scheme rescues neither: iOS cannot register a handler for `https`, and Android cannot register a scheme
+ * at all.
  *
- * base64**url** specifically, so `+`, `/` and `=` cannot survive into a query string and be re-interpreted
- * by anything that parses URLs along the way.
+ * The payload is opaque to this package — JSON-encoded and handed to your own host-side route, which
+ * decodes it. base64**url** specifically, so `+`, `/` and `=` cannot be re-interpreted by anything that
+ * parses URLs along the way.
  *
- * ⚠ An encoded payload costs debuggability — you cannot read the URL in a log any more. Have the host log
- * what it DECODED to: the response body cannot say, because an error body would leak paths.
+ * ⚠ An encoded payload costs debuggability: have the HOST log what it decoded to, because an error
+ * response body cannot say without leaking paths.
  *
  * @param payload Anything JSON-serialisable. Your host route decides what the shape means.
  * @param route The reserved path the host answers on. **Must not collide with a real asset in your bundle** —
@@ -58,8 +52,8 @@ export function mediaUrl(payload, route = 'media') {
  * The payload encoding on its own, for a caller that builds its own URL but wants the same wire format —
  * and so a host-side decoder has one documented thing to mirror.
  *
- * `TextEncoder` before `btoa` because `btoa` throws on any character above U+00FF: a payload carrying a
- * non-ASCII title or path would fail at the call site, which is a poor way to discover an encoding choice.
+ * ⚠ `TextEncoder` before `btoa`, which throws on any character above U+00FF — a payload carrying a
+ * non-ASCII title or path would fail at the call site.
  */
 export function encodeMediaPayload(payload) {
     const bytes = new TextEncoder().encode(JSON.stringify(payload));
@@ -70,9 +64,7 @@ export function encodeMediaPayload(payload) {
 }
 /**
  * Decode what {@link encodeMediaPayload} produced. Here for tests and for a page that round-trips its own
- * URLs; the real decoder is host-side, in whatever language the shell is written in.
- *
- * Padding is restored before decoding — base64url drops `=`, and `atob` requires it.
+ * URLs; the real decoder is host-side. Padding is restored first — base64url drops `=`, `atob` needs it.
  */
 export function decodeMediaPayload(encoded) {
     let padded = encoded.replace(/-/g, '+').replace(/_/g, '/');

package/dist/mediaPlayer.d.ts

@@ -0,0 +1,103 @@
+import { type RefObject } from 'react';
+import { type ShenoraBridge } from './bridge.js';
+import { type ShenoraEventBus } from './eventBus.js';
+/**
+ * The module the player speaks on. Matches `MediaPlayerOptions.Access.Module` on the host, which
+ * defaults to the same string — change one and you must change the other.
+ *
+ * ⚠ The `SHENORA.` prefix is RESERVED for the kit's own modules (D64), so your app stays free to own
+ * a module called plainly `MEDIA`.
+ */
+export declare const MEDIA_PLAYER_MODULE = "SHENORA.MEDIA";
+/**
+ * Commands the host sends. **A wire contract**: these strings are duplicated in C# as
+ * `MediaPlayerEvents`, and the two halves agree by string or not at all.
+ */
+export declare const MediaPlayerCommands: {
+    readonly load: "PLAYER_LOAD";
+    readonly play: "PLAYER_PLAY";
+    readonly pause: "PLAYER_PAUSE";
+    readonly seek: "PLAYER_SEEK";
+    readonly rate: "PLAYER_RATE";
+    readonly unload: "PLAYER_UNLOAD";
+};
+/** The one message the page sends back. The host turns it into `MediaPlayer.Report(...)`. */
+export declare const MEDIA_PLAYER_REPORT = "PLAYER_REPORT";
+/** What the page asks to read the host player's current status (`MediaPlayerModule.StatusType`). */
+export declare const MEDIA_PLAYER_STATUS = "PLAYER_STATUS";
+/**
+ * A CONVERSION's events, on the same module. **A wire contract** mirrored from C#
+ * `MediaConversionEvents` — a conversion outlives the request that started it, so the page learns from
+ * these rather than from a response.
+ */
+export declare const MediaConversionEvents: {
+    /** Fraction complete: `{ source, progress }`. Throttle in the app if the engine is chatty. */
+    readonly sourceProgress: "SOURCE_PROGRESS";
+    /** The converted file is servable: `{ source }`. Set the element's `src` now. */
+    readonly ready: "READY";
+    /** Failed: `{ source, reason }`, plus `dropped` when `reason` is {@link MediaConversionErrorCodes}. */
+    readonly failed: "FAILED";
+};
+/**
+ * Stable `reason` tokens on {@link MediaConversionEvents.failed}. Anything else is a TYPE name from an
+ * unexpected fault — never exception text.
+ */
+export declare const MediaConversionErrorCodes: {
+    /**
+     * The output would have lost a stream, so nothing was cached; the event carries `dropped`, the codecs.
+     * ⚠ It means "not playable HERE", not always "not supported" — a run configured with no conversion
+     * seam never asked the platform.
+     */
+    readonly unsupportedCodec: "UNSUPPORTED_CODEC";
+};
+/**
+ * What the element is doing, in the host's vocabulary (`MediaPlayerState`).
+ *
+ * ⚠ `Opening` and `Buffering` are distinct: opening is "no position yet", buffering is "had one and it
+ * stopped moving". Collapsing them makes a UI extrapolate a position that is not advancing.
+ */
+export type MediaPlayerReportState = 'Empty' | 'Opening' | 'Paused' | 'Playing' | 'Buffering' | 'Ended' | 'Failed';
+/** One state report, sent on TRANSITIONS only. */
+export interface MediaPlayerReport {
+    state: MediaPlayerReportState;
+    /** Seconds. */
+    position: number;
+    /** Seconds, or null for a live stream / not yet known. */
+    duration: number | null;
+    /** A short reason when `state` is `Failed`; never the platform's raw text. */
+    error?: string;
+}
+/** Inputs for {@link useMediaPlayer}. */
+export interface UseMediaPlayerOptions {
+    /** Override the module. Must match the host's `MediaPlayerOptions.Access.Module`. */
+    module?: string;
+    /** Test seams. */
+    bridge?: ShenoraBridge;
+    eventBus?: ShenoraEventBus;
+}
+/**
+ * Bind a `<video>`/`<audio>` element to the HOST's player: the element becomes the display and the sound,
+ * and .NET owns the lifecycle (D58).
+ *
+ * ```tsx
+ * const ref = useRef<HTMLVideoElement>(null);
+ * useMediaPlayer(ref);
+ * return <video ref={ref} playsInline />;
+ * ```
+ *
+ * **That is the whole page-side integration.** No `src`, no play button wiring, no state machine — the app
+ * calls `IMediaPlayer.OpenAsync/PlayAsync` in C#, and this drives the element to match. The host half
+ * needs nothing from you: the kit's own `MediaPlayerModule` answers the reports posted here.
+ *
+ * ⚠ **The element must exist when this effect first runs.** `ref.current` is read once, and a `useRef`
+ * object is stable, so an element rendered CONDITIONALLY (`{ready && <video ref={ref} />}`) mounts after
+ * the effect and never binds — silently. Render it unconditionally and hide it with CSS, or key the
+ * component so the hook remounts with it.
+ *
+ * ⚠ **It reports on TRANSITIONS, never on `timeupdate`**, which fires ~4×/second. For a moving scrubber,
+ * read `element.currentTime` in your own render loop.
+ *
+ * ⚠ **Autoplay policies still apply.** A `PLAYER_PLAY` arriving before any user gesture can be refused by
+ * the browser, and the element then reports `Failed` rather than the host believing playback started.
+ */
+export declare function useMediaPlayer(ref: RefObject<HTMLMediaElement | null>, options?: UseMediaPlayerOptions): void;

package/dist/mediaPlayer.js

@@ -0,0 +1,202 @@
+import { useEffect } from 'react';
+import { getBridge } from './bridge.js';
+import { eventBus as defaultEventBus } from './eventBus.js';
+/**
+ * The module the player speaks on. Matches `MediaPlayerOptions.Access.Module` on the host, which
+ * defaults to the same string — change one and you must change the other.
+ *
+ * ⚠ The `SHENORA.` prefix is RESERVED for the kit's own modules (D64), so your app stays free to own
+ * a module called plainly `MEDIA`.
+ */
+export const MEDIA_PLAYER_MODULE = 'SHENORA.MEDIA';
+/**
+ * Commands the host sends. **A wire contract**: these strings are duplicated in C# as
+ * `MediaPlayerEvents`, and the two halves agree by string or not at all.
+ */
+export const MediaPlayerCommands = {
+    load: 'PLAYER_LOAD',
+    play: 'PLAYER_PLAY',
+    pause: 'PLAYER_PAUSE',
+    seek: 'PLAYER_SEEK',
+    rate: 'PLAYER_RATE',
+    unload: 'PLAYER_UNLOAD',
+};
+/** The one message the page sends back. The host turns it into `MediaPlayer.Report(...)`. */
+export const MEDIA_PLAYER_REPORT = 'PLAYER_REPORT';
+/** What the page asks to read the host player's current status (`MediaPlayerModule.StatusType`). */
+export const MEDIA_PLAYER_STATUS = 'PLAYER_STATUS';
+/**
+ * A CONVERSION's events, on the same module. **A wire contract** mirrored from C#
+ * `MediaConversionEvents` — a conversion outlives the request that started it, so the page learns from
+ * these rather than from a response.
+ */
+export const MediaConversionEvents = {
+    /** Fraction complete: `{ source, progress }`. Throttle in the app if the engine is chatty. */
+    sourceProgress: 'SOURCE_PROGRESS',
+    /** The converted file is servable: `{ source }`. Set the element's `src` now. */
+    ready: 'READY',
+    /** Failed: `{ source, reason }`, plus `dropped` when `reason` is {@link MediaConversionErrorCodes}. */
+    failed: 'FAILED',
+};
+/**
+ * Stable `reason` tokens on {@link MediaConversionEvents.failed}. Anything else is a TYPE name from an
+ * unexpected fault — never exception text.
+ */
+export const MediaConversionErrorCodes = {
+    /**
+     * The output would have lost a stream, so nothing was cached; the event carries `dropped`, the codecs.
+     * ⚠ It means "not playable HERE", not always "not supported" — a run configured with no conversion
+     * seam never asked the platform.
+     */
+    unsupportedCodec: 'UNSUPPORTED_CODEC',
+};
+/**
+ * Bind a `<video>`/`<audio>` element to the HOST's player: the element becomes the display and the sound,
+ * and .NET owns the lifecycle (D58).
+ *
+ * ```tsx
+ * const ref = useRef<HTMLVideoElement>(null);
+ * useMediaPlayer(ref);
+ * return <video ref={ref} playsInline />;
+ * ```
+ *
+ * **That is the whole page-side integration.** No `src`, no play button wiring, no state machine — the app
+ * calls `IMediaPlayer.OpenAsync/PlayAsync` in C#, and this drives the element to match. The host half
+ * needs nothing from you: the kit's own `MediaPlayerModule` answers the reports posted here.
+ *
+ * ⚠ **The element must exist when this effect first runs.** `ref.current` is read once, and a `useRef`
+ * object is stable, so an element rendered CONDITIONALLY (`{ready && <video ref={ref} />}`) mounts after
+ * the effect and never binds — silently. Render it unconditionally and hide it with CSS, or key the
+ * component so the hook remounts with it.
+ *
+ * ⚠ **It reports on TRANSITIONS, never on `timeupdate`**, which fires ~4×/second. For a moving scrubber,
+ * read `element.currentTime` in your own render loop.
+ *
+ * ⚠ **Autoplay policies still apply.** A `PLAYER_PLAY` arriving before any user gesture can be refused by
+ * the browser, and the element then reports `Failed` rather than the host believing playback started.
+ */
+export function useMediaPlayer(ref, options = {}) {
+    const { module = MEDIA_PLAYER_MODULE, bridge, eventBus = defaultEventBus } = options;
+    useEffect(() => {
+        const element = ref.current;
+        if (!element)
+            return;
+        const link = bridge ?? getBridge();
+        // The element is the only clock: the host tracks no position of its own.
+        const report = (state, error) => {
+            const duration = Number.isFinite(element.duration) ? element.duration : null;
+            const payload = {
+                state,
+                position: Number.isFinite(element.currentTime) ? element.currentTime : 0,
+                duration,
+                ...(error ? { error } : {}),
+            };
+            link.post(module, MEDIA_PLAYER_REPORT, { payload });
+        };
+        // The PENDING start-at seek, if any. 🔴 It has to be cancellable: `{ once: true }` removes a
+        // listener only when it FIRES, and a second PLAYER_LOAD aborts the first load so its
+        // `loadedmetadata` never comes. The stale listener then runs on the NEXT track's metadata — load A
+        // at 10:00 then B at 0:00 and B starts ten minutes in.
+        let pendingSeek = null;
+        const cancelPendingSeek = () => {
+            if (pendingSeek)
+                element.removeEventListener('loadedmetadata', pendingSeek);
+            pendingSeek = null;
+        };
+        // ── host → element ────────────────────────────────────────────────────────────────────────────
+        const subscriptions = [
+            eventBus.subscribe(module, MediaPlayerCommands.load, (message) => {
+                const { uri, startAt } = message.payload ?? { uri: '', startAt: 0 };
+                element.src = uri;
+                // load() rather than trusting the src assignment: a second load on the same element keeps the
+                // previous buffer otherwise, and a seek then lands in the OLD media.
+                element.load();
+                cancelPendingSeek(); // this load supersedes any earlier one — see pendingSeek
+                if (startAt > 0) {
+                    const seek = () => { pendingSeek = null; element.currentTime = startAt; };
+                    // `loadedmetadata` is the earliest point currentTime is settable — before it, the assignment is
+                    // silently dropped and the item starts at zero.
+                    pendingSeek = seek;
+                    element.addEventListener('loadedmetadata', seek, { once: true });
+                }
+            }),
+            eventBus.subscribe(module, MediaPlayerCommands.play, () => {
+                // A rejected play() is an autoplay refusal, and the host must hear it rather than assume success.
+                // ⚠ Read `.name` STRUCTURALLY, never via `instanceof Error`: browsers reject with a
+                // DOMException, which is not an Error subclass everywhere (jsdom's is not). `NotAllowedError`
+                // is what an autoplay block says, and the name an adopter branches on.
+                void element.play().catch((cause) => {
+                    const name = cause?.name;
+                    report('Failed', typeof name === 'string' && name ? name : 'PlayRejected');
+                });
+            }),
+            eventBus.subscribe(module, MediaPlayerCommands.pause, () => element.pause()),
+            eventBus.subscribe(module, MediaPlayerCommands.seek, (message) => {
+                element.currentTime = message.payload?.position ?? 0;
+            }),
+            eventBus.subscribe(module, MediaPlayerCommands.rate, (message) => {
+                element.playbackRate = message.payload?.rate ?? 1;
+            }),
+            eventBus.subscribe(module, MediaPlayerCommands.unload, () => {
+                element.pause();
+                element.removeAttribute('src');
+                // ⚠ load() after clearing src is what actually FREES the buffer. Without it the element keeps the
+                // decoded data alive, which on a phone is the difference between releasing memory and not.
+                element.load();
+                report('Empty');
+            }),
+        ];
+        // ── element → host ────────────────────────────────────────────────────────────────────────────
+        // Transitions only — no `timeupdate`, see the remarks.
+        const listeners = [
+            ['loadedmetadata', () => report('Paused')],
+            ['canplay', () => report(element.paused ? 'Paused' : 'Playing')],
+            ['play', () => report('Playing')],
+            ['playing', () => report('Playing')],
+            ['pause', () => report(element.ended ? 'Ended' : 'Paused')],
+            ['waiting', () => report('Buffering')],
+            ['seeked', () => report(element.paused ? 'Paused' : 'Playing')],
+            ['ended', () => report('Ended')],
+            ['error', () => report('Failed', mediaErrorReason(element))],
+        ];
+        for (const [event, handler] of listeners)
+            element.addEventListener(event, handler);
+        // 🔴 REPORT WHEN THE PAGE IS ABOUT TO BE HIDDEN, or the host's position is whatever the last
+        // TRANSITION left — for steady playback, the moment it started. The user then backgrounds mid-film
+        // and `BackgroundPlaybackTransfer` resumes from the beginning. The platform's `pause` does fire,
+        // but not in time to cross IPC before the process is frozen.
+        //
+        // ⚠ `visibilitychange` rather than `pagehide`: it fires while the document is still alive and the
+        // bridge can still post, and both mobile shells raise it on the way to the background. ONE report
+        // per background, not `timeupdate`'s ~4/second.
+        const onHidden = () => {
+            if (document.visibilityState !== 'hidden')
+                return;
+            report(element.paused ? (element.ended ? 'Ended' : 'Paused') : 'Playing');
+        };
+        document.addEventListener('visibilitychange', onHidden);
+        return () => {
+            for (const subscription of subscriptions)
+                subscription();
+            for (const [event, handler] of listeners)
+                element.removeEventListener(event, handler);
+            cancelPendingSeek();
+            document.removeEventListener('visibilitychange', onHidden);
+        };
+    }, [ref, module, bridge, eventBus]);
+}
+/**
+ * A short, stable reason from `MediaError`.
+ *
+ * ⚠ Never `error.message`: browsers put decoder internals and sometimes the full URL in it, and this
+ * string crosses to the host and can reach a log.
+ */
+function mediaErrorReason(element) {
+    switch (element.error?.code) {
+        case 1: return 'Aborted';
+        case 2: return 'Network';
+        case 3: return 'Decode';
+        case 4: return 'SourceNotSupported';
+        default: return 'Unknown';
+    }
+}

package/dist/moduleService.d.ts

@@ -1,28 +1,27 @@
 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:
+ * Base class for typed module services: 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 } }); }
+ *   getAll(): Promise<Note[]> { return this.send('GET_ALL'); }
+ *   add(title: string): Promise<Note> { return this.send('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.
+ * 🔴 **DECLARE THE RETURN TYPE; NEVER WRITE `send<Note>(…)`.** TypeScript has no partial type-argument
+ * inference, so naming the response argument makes `TType` fall back to its DEFAULT — the union of every
+ * key — and `payload` collapses to the union of every route's payload. The check silently stops
+ * checking: `send<Note>('ADD', { payload: { notAField: 1 } })` compiles clean, while the same call
+ * without the type argument is a TS2353. The response is inferred from the declared return type instead.
  *
- * `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.
+ * ⚠ `TRequests extends object`, never `extends Record<string, unknown>`: the stricter bound is
+ * unsatisfiable by a plain `interface` (TS2344 on the example above), and satisfying it by widening the
+ * request map widens `keyof TRequests & string` back to `string` — turning the payload check off again.
  */
 export declare abstract class BaseModuleService<TRequests extends object = Record<string, unknown>> {
     /** The backend module this service fronts (e.g. `"NOTES"`). */
@@ -43,13 +42,10 @@ export declare abstract class BaseModuleService<TRequests extends object = Recor
     /**
      * 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.
+     * 🔴 Never default it at CONSTRUCTION. Module services are commonly module-level singletons, so one
+     * is routinely built before `configureBridge()` runs — and `configureBridge` DISPOSES the bridge it
+     * replaces, so a captured default makes every later call reject with "Bridge disposed" for the rest
+     * of the session, with nothing to suggest why.
      */
     protected get bridge(): ShenoraBridge;
     /** Send one typed request to this module and await the typed response data. */

package/dist/moduleService.js

@@ -1,28 +1,27 @@
 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:
+ * Base class for typed module services: 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 } }); }
+ *   getAll(): Promise<Note[]> { return this.send('GET_ALL'); }
+ *   add(title: string): Promise<Note> { return this.send('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.
+ * 🔴 **DECLARE THE RETURN TYPE; NEVER WRITE `send<Note>(…)`.** TypeScript has no partial type-argument
+ * inference, so naming the response argument makes `TType` fall back to its DEFAULT — the union of every
+ * key — and `payload` collapses to the union of every route's payload. The check silently stops
+ * checking: `send<Note>('ADD', { payload: { notAField: 1 } })` compiles clean, while the same call
+ * without the type argument is a TS2353. The response is inferred from the declared return type instead.
  *
- * `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.
+ * ⚠ `TRequests extends object`, never `extends Record<string, unknown>`: the stricter bound is
+ * unsatisfiable by a plain `interface` (TS2344 on the example above), and satisfying it by widening the
+ * request map widens `keyof TRequests & string` back to `string` — turning the payload check off again.
  */
 export class BaseModuleService {
     constructor(
@@ -39,13 +38,10 @@ export class BaseModuleService {
     /**
      * 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.
+     * 🔴 Never default it at CONSTRUCTION. Module services are commonly module-level singletons, so one
+     * is routinely built before `configureBridge()` runs — and `configureBridge` DISPOSES the bridge it
+     * replaces, so a captured default makes every later call reject with "Bridge disposed" for the rest
+     * of the session, with nothing to suggest why.
      */
     get bridge() {
         return this.explicitBridge ?? getBridge();