@hoardodile/host-web 0.0.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Wooloo <ayan0312000@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @hoardodile/host-web
+
+The browser-side plugin host runtime: the shared host-core protocol
+router (used by the hoardodile web app in production and by the offline
+mock) plus the mock host for component tests and the workbench. The wire
+protocol itself stays in `@hoardodile/sdk-web` — this package consumes
+it, never redefines it.
+
+## Install
+
+```bash
+pnpm add @hoardodile/host-web
+```
+
+## What's in it
+
+- **`createHostRouter`** / **`defineHandler`** — the host-core protocol
+  router: message demux, method routing, per-method param validation,
+  stale-request scoping, response envelope. The real app and the mock
+  assemble on this module so routing and validation never drift
+- **`createMockHost`** — an in-memory host for jsdom component tests and
+  the workbench; register a window and drive the iframe bridge with no
+  server
+- **`createInMemoryFileBackend`** — file backend for the mock
+
+## Subpaths
+
+| Entry | Contents |
+| ----- | -------- |
+| `@hoardodile/host-web` | Browser-safe router + mock (no node imports) |
+| `@hoardodile/host-web/node` | Node file backends (directory-backed mock storage) |

package/dist/file-backends-Dyy2BxUM.d.ts

@@ -0,0 +1,27 @@
+import { ReadFileRange } from '@hoardodile/sdk-types';
+
+/**
+ * File backends for the offline mock host: the plugin's `listFiles` and
+ * `readFile` requests resolve against this interface, so a mock can be
+ * pointed at an in-memory map, a real directory (Node), or a read-only
+ * HTTP mount (workbench) without changing the host.
+ */
+type MockFileBackend = {
+    readonly listFiles: (resId: string) => Promise<readonly string[]>;
+    readonly readFile: (resId: string, path: string, range?: ReadFileRange) => Promise<ArrayBuffer>;
+    readonly statFile: (resId: string, path: string) => Promise<{
+        readonly sizeBytes: number;
+    } | undefined>;
+    /**
+     * The rows the plugin's own `listFiles` hook produced, when the
+     * backend can obtain them (the workbench reads them from a sandboxed
+     * hook snapshot). In production the host answers `listFiles` with
+     * exactly these plugin-shaped entries; returning `undefined` falls
+     * back to generic `{filename, ext, sizeBytes}` rows.
+     */
+    readonly listFileEntries?: (resId: string) => Promise<readonly unknown[] | undefined>;
+};
+/** In-memory file map backend for unit tests. `resId` is ignored. */
+declare function createInMemoryFileBackend(files?: Readonly<Record<string, string | Uint8Array>>): MockFileBackend;
+
+export { type MockFileBackend as M, createInMemoryFileBackend as c };

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+import { z } from 'zod';
+import { HostResponse, PluginIframeContext } from '@hoardodile/sdk-web';
+import { M as MockFileBackend } from './file-backends-Dyy2BxUM.js';
+export { c as createInMemoryFileBackend } from './file-backends-Dyy2BxUM.js';
+import { Danmaku, Message, PluginDownloadRequest, PluginDownloadResult, PluginAssetDeleteResult } from '@hoardodile/sdk-types';
+export { ReadFileRange } from '@hoardodile/sdk-types';
+
+/**
+ * The consent-dialog queue for plugin asset downloads — the shared
+ * implementation both host apps mount:
+ *
+ * - the **app** feeds it from SSE (`pluginDownloadRequested` /
+ *   `pluginDownloadResolved`) and drives decisions through the server
+ *   (`pluginAsset.decide`); the resolved broadcast closes entries here;
+ * - the **workbench** has no server: its asset engine enqueues via
+ *   {@link request} and the dialog answers via {@link decide} — the same
+ *   dialog component, one queue per page, FIFO, one dialog at a time.
+ *
+ * State-only by design: decisions never mutate the queue directly
+ * except through `close`/`decide`, which the two hosts wire to their
+ * own decision path.
+ */
+/**
+ * A queued consent question: the ticket shape. Structurally identical to
+ * the server's `pluginDownloadRequested` SSE event minus its `type`
+ * discriminator (and to `pluginAsset.listPending` rows) — declared here
+ * instead of importing `@hoardodile/schemas` so the host-core package
+ * stays dependency-lean.
+ */
+type DownloadConsentEntry = {
+    readonly ticketId: string;
+    readonly pluginId: string;
+    readonly pluginName: string;
+    readonly url: string;
+    readonly dest: string;
+    readonly sizeBytes?: number;
+    readonly reason?: string;
+};
+type State = {
+    readonly queue: readonly DownloadConsentEntry[];
+};
+declare function subscribeDownloadConsent(listener: () => void): () => void;
+declare function getDownloadConsentSnapshot(): State;
+/** A new ticket arrived (SSE) or was requested locally: append if absent. */
+declare function enqueueDownloadConsent(entry: DownloadConsentEntry): void;
+/** A ticket resolved (decide/timeout/dispose): drop it in every consumer. */
+declare function closeDownloadConsent(ticketId: string): void;
+/**
+ * Replace the queue from a pending list (app: `listPending` after an SSE
+ * reconnect; workbench: same API on restart).
+ */
+declare function rehydrateDownloadConsent(entries: readonly DownloadConsentEntry[]): void;
+/**
+ * Enqueue a ticket and wait for its decision (workbench engine path).
+ * The dialog's answer arrives through {@link decideDownloadConsent}.
+ */
+declare function requestDownloadConsent(entry: DownloadConsentEntry): Promise<boolean>;
+/**
+ * Answer a ticket from the dialog. Closes the entry and resolves any
+ * awaiting engine call. Idempotent; unknown tickets are a no-op.
+ */
+declare function decideDownloadConsent(ticketId: string, approved: boolean): void;
+/** Test-only: reset the singleton between tests. */
+declare function resetDownloadConsent(): void;
+
+/**
+ * Wire-level param schemas for every request method, shared by the real
+ * host (apps/web) and the offline mock host. Both hosts validate
+ * identical shapes, so a plugin that passes validation in the mock is
+ * guaranteed to pass in production.
+ */
+/**
+ * Wire shape of a message/danmaku anchor: the plugin location payload
+ * only. The resource id is host state — the host stamps its own binding
+ * into the anchor before it reaches the server.
+ */
+declare const anchorData: z.ZodObject<{
+    data: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+declare const requestSchemas: {
+    readFile: z.ZodObject<{
+        path: z.ZodString;
+        range: z.ZodOptional<z.ZodObject<{
+            start: z.ZodOptional<z.ZodNumber>;
+            end: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    listFiles: undefined;
+    listMessages: undefined;
+    createMessage: z.ZodObject<{
+        body: z.ZodString;
+        anchor: z.ZodOptional<z.ZodObject<{
+            data: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strict>>;
+    }, z.core.$strip>;
+    listDanmaku: z.ZodObject<{
+        filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    }, z.core.$strip>;
+    createDanmaku: z.ZodObject<{
+        text: z.ZodString;
+        anchor: z.ZodObject<{
+            data: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strict>;
+        mode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    setPref: z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>;
+    setCache: z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>;
+    invalidate: z.ZodObject<{
+        target: z.ZodEnum<{
+            resource: "resource";
+            resources: "resources";
+            messages: "messages";
+            danmaku: "danmaku";
+        }>;
+    }, z.core.$strip>;
+    download: z.ZodObject<{
+        url: z.ZodString;
+        dest: z.ZodString;
+        sha256: z.ZodOptional<z.ZodString>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    deleteAsset: z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strip>;
+    logInfo: z.ZodObject<{
+        message: z.ZodString;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    logWarn: z.ZodObject<{
+        message: z.ZodString;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    logError: z.ZodObject<{
+        message: z.ZodString;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+};
+
+/**
+ * The shared host-side protocol core: message demux, method routing,
+ * per-method param validation, stale-request scoping and the response
+ * envelope. Both the real host (apps/web) and the offline mock host
+ * assemble on this module, so routing and validation never drift.
+ */
+/** What a registered iframe (or mock window) is bound to. */
+type HostBinding = {
+    readonly pluginId: string;
+    readonly resId: string;
+};
+type HostRouterDeps = {
+    /**
+     * Authenticate an inbound message event: narrow it to a trusted source
+     * + binding, or return `undefined` to drop the message. The real host
+     * validates origin/source against its iframe registry; the mock
+     * validates against its own registered windows.
+     */
+    readonly resolveSource: (event: MessageEvent) => {
+        readonly source: unknown;
+        readonly record: HostBinding;
+    } | undefined;
+    /** Send a response back to the source (the layer's postMessage exit). */
+    readonly respond: (source: unknown, response: HostResponse) => void;
+    /** Record a subscription key for the source. */
+    readonly subscribe: (source: unknown, key: string) => void;
+};
+type HostHandlerContext = {
+    readonly source: unknown;
+    /**
+     * The resource this request is scoped to: the source's current
+     * binding ("" only for never-bound sources). Requests stamped by the
+     * SDK with a different resource are dropped as stale before they
+     * reach a handler.
+     */
+    readonly resId: string;
+    readonly pluginId: string;
+};
+type HostHandlerEntry = {
+    readonly method: string;
+    /** Param schema; validated in the router before the handler runs. */
+    readonly schema: z.ZodTypeAny | undefined;
+    readonly handler: (ctx: HostHandlerContext, params: unknown) => Promise<unknown>;
+};
+declare function defineHandler<TReturn>(method: string, handler: (ctx: HostHandlerContext) => Promise<TReturn> | TReturn): HostHandlerEntry;
+declare function defineHandler<TSchema extends z.ZodTypeAny, TReturn>(method: string, schema: TSchema, handler: (ctx: HostHandlerContext, params: z.infer<TSchema>) => Promise<TReturn> | TReturn): HostHandlerEntry;
+/**
+ * Create the per-window message handler: authenticates the event,
+ * routes requests by method, validates params, drops stale scopes and
+ * wraps every outcome in the response envelope.
+ */
+declare function createHostRouter(handlers: readonly HostHandlerEntry[], deps: HostRouterDeps): (event: MessageEvent) => void;
+
+type MockMessageStore = {
+    readonly list: (resId: string) => readonly Message[];
+    readonly create: (resId: string, input: {
+        body: string;
+        anchor?: unknown;
+    }) => Message;
+};
+/**
+ * `seed` pre-fills the store with rows the plugin should already see —
+ * the workbench passes the resource's real comments so the iframe opens
+ * with the same content the app would show.
+ */
+declare function createMockMessageStore(seed?: readonly Message[]): MockMessageStore;
+type MockDanmakuStore = {
+    readonly list: (resId: string) => readonly Danmaku[];
+    readonly create: (resId: string, input: {
+        text: string;
+        anchor: unknown;
+        mode?: string;
+    }) => Danmaku;
+};
+/** See {@link createMockMessageStore} for `seed`. */
+declare function createMockDanmakuStore(seed?: readonly Danmaku[]): MockDanmakuStore;
+
+/**
+ * The offline host side of the plugin postMessage bridge. Implements the
+ * same routing, validation and scoping as the production host (via
+ * host-core) with in-memory data — so plugin iframes run with no server
+ * at all. Shared by automated component tests (jsdom: register the test
+ * window) and the manual workbench page (register the real iframe
+ * window).
+ */
+type MockHostLogger = {
+    readonly info: (message: string, data?: unknown) => void;
+    readonly warn: (message: string, data?: unknown) => void;
+    readonly error: (message: string, data?: unknown) => void;
+};
+type MockHostOptions = {
+    /**
+     * Window that receives plugin postMessage traffic: the page window in
+     * a workbench, the test window in jsdom. The host listens on it and
+     * posts responses to it.
+     */
+    readonly targetWindow: Window;
+    readonly files: MockFileBackend;
+    readonly messages?: MockMessageStore;
+    readonly danmaku?: MockDanmakuStore;
+    /** Initial plugin-scoped prefs. */
+    readonly prefs?: Readonly<Record<string, string>>;
+    /** Initial plugin+resId cache entries. */
+    readonly cache?: Readonly<Record<string, string>>;
+    readonly logger?: MockHostLogger;
+    /** Called after a plugin writes a pref. */
+    readonly onPrefChanged?: (key: string, value: string) => void;
+    /** Called after a plugin writes a cache entry. */
+    readonly onCacheChanged?: (resId: string, key: string, value: string) => void;
+    /**
+     * Plugin asset vault implementation (workbench only). Absent → the
+     * asset methods answer `UNAVAILABLE` (tests, jsdom hosts). The real
+     * app routes these through its server pipeline via tRPC — the mock
+     * never talks to it.
+     */
+    readonly assetVault?: PluginAssetVaultMock;
+};
+/**
+ * The workbench-side plugin asset vault: the mock hands `download` and
+ * `deleteAsset` to the host app's implementation (consent dialog + dev
+ * server fetch + local vault), mirroring the server pipeline's
+ * request/result vocabulary.
+ */
+type PluginAssetVaultMock = {
+    readonly download: (request: PluginDownloadRequest) => Promise<PluginDownloadResult>;
+    readonly deleteAsset: (path: string) => Promise<PluginAssetDeleteResult>;
+};
+type MockHost = {
+    /**
+     * Bind a message source to a plugin/resource. The real host binds
+     * iframe contentWindows; jsdom tests register the test window itself
+     * (plugin code posts to `window.parent`, which is itself).
+     */
+    readonly register: (source: unknown, binding: HostBinding) => void;
+    readonly unregister: (source: unknown) => void;
+    /** Push a host event to one source. */
+    readonly push: (source: unknown, key: string, data?: unknown) => void;
+    /** Push the plugin context (the iframe mounts on this). */
+    readonly pushContext: (source: unknown, ctx: PluginIframeContext) => void;
+    readonly setVisibility: (source: unknown, visible: boolean) => void;
+    readonly messages: MockMessageStore;
+    readonly danmaku: MockDanmakuStore;
+    readonly prefs: ReadonlyMap<string, string>;
+    readonly cache: ReadonlyMap<string, string>;
+    readonly dispose: () => void;
+};
+declare function createMockHost(opts: MockHostOptions): MockHost;
+
+export { type DownloadConsentEntry, type HostBinding, type HostHandlerContext, type HostHandlerEntry, type HostRouterDeps, type MockDanmakuStore, MockFileBackend, type MockHost, type MockHostLogger, type MockHostOptions, type MockMessageStore, type PluginAssetVaultMock, anchorData, closeDownloadConsent, createHostRouter, createMockDanmakuStore, createMockHost, createMockMessageStore, decideDownloadConsent, defineHandler, enqueueDownloadConsent, getDownloadConsentSnapshot, rehydrateDownloadConsent, requestDownloadConsent, requestSchemas, resetDownloadConsent, subscribeDownloadConsent };