@shenora/react 0.11.0 → 0.12.0

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

@@ -2,12 +2,11 @@ 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 (the
- * containment/module boundary every media delivery path shares — `MediaAccessOptions`, D71), which
+ * 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), beside the handshake's bare
- * `SHENORA`. It exists so your app stays free to own a module called plainly `MEDIA`.
+ * ⚠ 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";
 /**
@@ -24,11 +23,38 @@ export declare const MediaPlayerCommands: {
 };
 /** 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, matching the host: 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.
+ * ⚠ `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. */
@@ -60,27 +86,18 @@ export interface UseMediaPlayerOptions {
  * ```
  *
  * **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 page keeps what
- * it is good at (rendering) and gives up what it was never good at (deciding whether a file can be played
- * at all, which needs a probe and a device capability query).
- *
- * ⚠ **The host half needs nothing from you.** The reports posted here are an ordinary IPC message
- * (`PLAYER_REPORT` on {@link MEDIA_PLAYER_MODULE}) and the kit's own `MediaPlayerModule` answers it,
- * registered by the media feature itself. If you wrote that route by hand against a build from before
- * 2026-08-07, **delete it** — two facades on one module is a duplicate the host rejects.
+ * 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 the element unconditionally and hide it with CSS, or key
- * the component so the hook remounts with it.
+ * 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`.** That event fires ~4×/second and forwarding it
- * would cost battery and IPC to tell the host something it can extrapolate from a position and a rate. If
- * you need a moving scrubber, read `element.currentTime` in your own render loop — locally, at the rate you
- * actually redraw.
+ * ⚠ **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 reports `Failed`. That is the platform's rule, not the kit's, and the host
- * hears about it rather than silently believing playback started.
+ * 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

@@ -2,12 +2,11 @@ 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 (the
- * containment/module boundary every media delivery path shares — `MediaAccessOptions`, D71), which
+ * 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), beside the handshake's bare
- * `SHENORA`. It exists so your app stays free to own a module called plainly `MEDIA`.
+ * ⚠ 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';
 /**
@@ -24,6 +23,33 @@ export const MediaPlayerCommands = {
 };
 /** 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).
@@ -35,28 +61,19 @@ export const MEDIA_PLAYER_REPORT = 'PLAYER_REPORT';
  * ```
  *
  * **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 page keeps what
- * it is good at (rendering) and gives up what it was never good at (deciding whether a file can be played
- * at all, which needs a probe and a device capability query).
- *
- * ⚠ **The host half needs nothing from you.** The reports posted here are an ordinary IPC message
- * (`PLAYER_REPORT` on {@link MEDIA_PLAYER_MODULE}) and the kit's own `MediaPlayerModule` answers it,
- * registered by the media feature itself. If you wrote that route by hand against a build from before
- * 2026-08-07, **delete it** — two facades on one module is a duplicate the host rejects.
+ * 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 the element unconditionally and hide it with CSS, or key
- * the component so the hook remounts with it.
+ * 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`.** That event fires ~4×/second and forwarding it
- * would cost battery and IPC to tell the host something it can extrapolate from a position and a rate. If
- * you need a moving scrubber, read `element.currentTime` in your own render loop — locally, at the rate you
- * actually redraw.
+ * ⚠ **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 reports `Failed`. That is the platform's rule, not the kit's, and the host
- * hears about it rather than silently believing playback started.
+ * 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;
@@ -65,8 +82,7 @@ export function useMediaPlayer(ref, options = {}) {
         if (!element)
             return;
         const link = bridge ?? getBridge();
-        // The element is the only clock: the host asks IT for position rather than tracking its own, so a
-        // report always carries what the element actually believes.
+        // 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 = {
@@ -77,11 +93,10 @@ export function useMediaPlayer(ref, options = {}) {
             };
             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 calls `element.load()`, which aborts the first load so
-        // its `loadedmetadata` never comes. The stale listener then survives and runs on the NEXT track's
-        // metadata — so loading A at 10:00 and then B at 0:00 starts B ten minutes in, because B sets no
-        // listener of its own and A's is still attached.
+        // 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)
@@ -107,10 +122,9 @@ export function useMediaPlayer(ref, options = {}) {
             }),
             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 rather than testing `instanceof Error`: the value browsers reject
-                // with is a DOMException, which is not an Error subclass everywhere (jsdom's is not), and a page
-                // can reject with anything at all. The name is the stable, app-safe part — `NotAllowedError` is
-                // what an autoplay block actually says, and it is the one an adopter will want to branch on.
+                // ⚠ 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');
@@ -133,7 +147,7 @@ export function useMediaPlayer(ref, options = {}) {
             }),
         ];
         // ── element → host ────────────────────────────────────────────────────────────────────────────
-        // Transitions only. `timeupdate` is deliberately absent — see the remarks.
+        // Transitions only — no `timeupdate`, see the remarks.
         const listeners = [
             ['loadedmetadata', () => report('Paused')],
             ['canplay', () => report(element.paused ? 'Paused' : 'Playing')],
@@ -148,17 +162,13 @@ export function useMediaPlayer(ref, options = {}) {
         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 — which for steady playback is the moment it started.
-        //
-        // Measured on an Android emulator 2026-08-15: with transition-only reporting the page sat at 19.79 s
-        // while the host believed 0.01 s, and `BackgroundPlaybackTransfer` handed the native player 0.01 s.
-        // The user backgrounds mid-film and resumes from the beginning. The platform's `pause` at background
-        // time does fire, but not in time to cross IPC before the process is frozen.
+        // 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`: this fires while the document is still alive and the
-        // bridge can still post, and it is the signal both mobile shells raise on the way to the background.
-        // It costs ONE report per background — nothing like `timeupdate`'s ~4/second, which is why that one
-        // is still deliberately absent.
+        // ⚠ `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;
@@ -178,8 +188,8 @@ export function useMediaPlayer(ref, options = {}) {
 /**
  * A short, stable reason from `MediaError`.
  *
- * ⚠ Deliberately NOT `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. The host applies the same rule to platform errors.
+ * ⚠ 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) {

package/dist/moduleService.d.ts

@@ -1,9 +1,8 @@
 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 } }
@@ -18,18 +17,11 @@ import { type ShenoraBridge } from './bridge.js';
  * 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 method's declared return
- * type instead, which every method here has anyway. `moduleService.test.ts` pins both halves.
+ * without the type argument is a TS2353. The response is inferred from the declared return type instead.
  *
- * 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.
+ * ⚠ `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"`). */
@@ -50,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,9 +1,8 @@
 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 } }
@@ -18,18 +17,11 @@ import { getBridge } from './bridge.js';
  * 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 method's declared return
- * type instead, which every method here has anyway. `moduleService.test.ts` pins both halves.
+ * without the type argument is a TS2353. The response is inferred from the declared return type instead.
  *
- * 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.
+ * ⚠ `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(
@@ -46,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();