@hoardodile/sdk-react 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,61 @@
+# @hoardodile/sdk-react
+
+React bindings for hoardodile content plugin iframes. Framework-agnostic
+plugins use `@hoardodile/sdk-web` directly instead.
+
+## Install
+
+```bash
+pnpm add @hoardodile/sdk-react
+```
+
+## What's in it
+
+- **`createPluginRoot(config)`** — one-call bootstrap: mounts the iframe
+  bridge, wires the typed `PluginAPIProvider`, applies host theme/fonts,
+  and remounts on resource rebind
+- **`definePluginAPI<Schema>({ decodeAnchor })`** — declare your plugin
+  schema once and get a typed `PluginAPIProvider`, `usePluginAPI` and
+  `useAnchorJump`
+- **`useVisibility()`** — pause media/timers when the iframe is parked
+- **`useCacheWriter()`** — debounced per-resource cache writes with a
+  flush on `pagehide`/unmount
+- **`createPluginTranslation(bundles)`** — `useTranslation()` backed by
+  the shared `@hoardodile/i18n` catalogs and the host's language pushes;
+  `@hoardodile/ui` chrome is localized for free in every supported host
+  language. Want full control over the i18n stack (namespaces, plurals,
+  `Trans`, custom format, lazy backends)? Assemble your own
+  react-i18next instance instead — the only hoardodile piece is the
+  `languageChanged` notification from `@hoardodile/sdk-web` (see the
+  advanced pattern in `skills/hd-plugin/references/client.md`).
+- **`StubPluginAPIProvider`** — render-test fixture
+
+## Quick start
+
+```tsx
+// src/render.tsx
+import { createPluginRoot, definePluginAPI } from "@hoardodile/sdk-react"
+import type { PluginSchema } from "@hoardodile/sdk-types"
+
+interface MySchema extends PluginSchema {
+	file: { filename: string }
+	sourceMeta: { files: readonly { filename: string }[] }
+}
+
+const { PluginAPIProvider, usePluginAPI } = definePluginAPI<MySchema>()
+
+function Viewer() {
+	const api = usePluginAPI()
+	const { data: files } = api.useFileList()
+	return <div>{files?.length} files</div>
+}
+
+createPluginRoot({ render: Viewer, provider: PluginAPIProvider })
+```
+
+## Where does the code live?
+
+The imperative API surface (`WebPluginAPI`) and the wire protocol live in
+`@hoardodile/sdk-web`; this package composes them into the reactive API
+React components see. Shared message/danmaku/anchor types come from
+`@hoardodile/sdk-types`.

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+import * as react from 'react';
+import { Provider, ReactNode, ComponentType } from 'react';
+import { WebPluginAPI, ReactivePluginAPI, DeepPartial, Host, PluginFonts } from '@hoardodile/sdk-web';
+export { DeepPartial, createWebPluginAPI } from '@hoardodile/sdk-web';
+import { PluginSchema } from '@hoardodile/sdk-types';
+
+/**
+ * The full plugin API as delivered to React plugin components: the
+ * imperative {@link WebPluginAPI} plus the reactive hooks implemented by
+ * this package's adapter. Typed with default (unknown) schema slots; the
+ * typed provider from `definePluginAPI` narrows it per plugin.
+ */
+type BasePluginAPI = WebPluginAPI & ReactivePluginAPI;
+/**
+ * Provides the plugin API to the component tree. Usually created
+ * implicitly via {@link createPluginRoot}; the typed provider from
+ * {@link definePluginAPI} narrows `BasePluginAPI` to the plugin's
+ * schema.
+ */
+declare const PluginAPIProvider: react.Provider<BasePluginAPI | null>;
+declare function usePluginAPI(): BasePluginAPI;
+
+/** The full API seen by React plugin components: imperative + hooks. */
+type FullPluginAPI<TSchema extends PluginSchema> = WebPluginAPI<TSchema> & ReactivePluginAPI<TSchema>;
+type DefinePluginAPIOptions<TSchema extends PluginSchema> = {
+    /**
+     * Validate incoming anchor data (host → plugin) against the schema's
+     * `anchor` slot. Anchors that fail decoding are dropped silently and
+     * never reach the `useAnchorJump` callback. Declare this whenever the
+     * schema declares an `anchor` type.
+     */
+    readonly decodeAnchor?: (data: unknown) => TSchema["anchor"] | undefined;
+};
+/**
+ * Define a typed plugin API context. The schema is declared once at module
+ * level — every consumer below gets properly typed access without repeating
+ * generics.
+ *
+ * The returned provider and hook share the same React context as the default
+ * {@link PluginAPIProvider}, so plugin roots created by `createPluginRoot`
+ * automatically satisfy typed consumers when the same provider is passed in.
+ *
+ * ```typescript
+ * interface VideoSchema { file: VideoFile; sourceMeta: VideoSourceMeta; anchor: VideoTimeAnchor }
+ * const { PluginAPIProvider, usePluginAPI, useAnchorJump } = definePluginAPI<VideoSchema>({
+ *   decodeAnchor: decodeVideoTimeAnchor,
+ * })
+ *
+ * function Viewer() {
+ *   const api = usePluginAPI()
+ *   const { data: files } = api.useFileList()
+ *   // files → readonly VideoFile[] | undefined
+ * }
+ * ```
+ */
+declare function definePluginAPI<TSchema extends PluginSchema = PluginSchema>(options?: DefinePluginAPIOptions<TSchema>): {
+    readonly PluginAPIProvider: Provider<FullPluginAPI<TSchema> | null>;
+    readonly usePluginAPI: () => FullPluginAPI<TSchema>;
+    readonly useAnchorJump: (cb: (anchor: TSchema["anchor"]) => void) => void;
+};
+
+/**
+ * Wrap children with a stubbed API provider for tests. Builds the stub
+ * via `createWebPluginAPI` from `@hoardodile/sdk-web` (re-exported
+ * below) — the imperative surface plus no-op reactive hooks, overridable
+ * via `api`.
+ */
+declare function StubPluginAPIProvider({ api, children, }: {
+    readonly api?: DeepPartial<BasePluginAPI>;
+    readonly children: ReactNode;
+}): react.JSX.Element;
+
+type RawBundle = Record<string, unknown>;
+type InterpolationVars = Record<string, string | number>;
+type PluginTranslation = {
+    readonly t: (key: string, vars?: InterpolationVars) => string;
+    readonly language: string;
+};
+/**
+ * Creates a `useTranslation` hook backed by the given locale bundles plus
+ * the shared `ui` catalog namespace (so `@hoardodile/ui` components
+ * render localized chrome in every supported host language).
+ *
+ * Backed by i18next/react-i18next with the same options as the host
+ * surfaces: the language follows the plugin context, updates when the
+ * host sends a `languageChanged` push, interpolates `{{var}}`
+ * placeholders, and falls back to English (via `fallbackLng`) for
+ * languages the plugin's own bundle does not ship.
+ */
+declare function createPluginTranslation(bundles: Record<string, RawBundle>): {
+    readonly useTranslation: () => PluginTranslation;
+};
+
+/**
+ * Builds the reactive half of the plugin API (`useFileList`,
+ * `useMessageList`, `useCreateMessage`, `useDanmakuList`,
+ * `useCreateDanmaku`, `usePref`, `useTheme`, `useFont`) on top of the
+ * imperative `WebPluginAPI` and the host bridge. Queries refetch
+ * automatically on the matching host invalidation push and when the
+ * iframe is rebound to another resource.
+ *
+ * Consumed by {@link createPluginRoot}; call it directly only when
+ * composing your own runtime. The returned hooks are bound to the
+ * `host` passed in — the one from `ensureHostBridge()`.
+ */
+declare function createPluginQueryAPI<TSchema extends PluginSchema = PluginSchema>(host: Host, ctx: {
+    readonly resolvedTheme: string;
+    readonly palette: string;
+    readonly iconStyle: string;
+    readonly fonts: PluginFonts;
+    readonly resId: string;
+}): ReactivePluginAPI<TSchema>;
+
+type PluginRootConfig<TSchema extends PluginSchema = PluginSchema> = {
+    /** Root component rendered inside the plugin iframe. */
+    readonly render: ComponentType;
+    /**
+     * Typed provider returned by {@link definePluginAPI}. This is the single
+     * source of truth for the plugin schema type.
+     */
+    readonly provider: Provider<FullPluginAPI<TSchema> | null>;
+    /**
+     * When `true` (default), the whole plugin tree remounts whenever the
+     * iframe is rebound to another resource — the safe choice: all
+     * per-resource state resets automatically.
+     *
+     * Set to `false` for fine-grained updates (e.g. cheap same-plugin
+     * navigation): the mounted tree stays alive and only re-renders with
+     * the new `api`. Queries refetch automatically, but every piece of
+     * per-resource state becomes the plugin's own responsibility — key
+     * subtrees and memos by `api.resource.id` and reset any hydration
+     * flags yourself.
+     */
+    readonly remountOnResourceChange?: boolean;
+};
+/**
+ * Subscribe to the iframe visibility state from the host: `false` while
+ * the iframe is parked offscreen in the preview window. Do NOT gate
+ * rendering on it — parked slots are meant to pre-paint so a flip is a
+ * style swap, and an empty tree defeats that. Use visibility only to
+ * pause active behavior: media playback, autoplay, timers.
+ */
+declare function useVisibility(): boolean;
+/**
+ * One-call plugin bootstrap. Handles `mountPlugin`, `createRoot` caching,
+ * iframe host API, typed `PluginAPIProvider`, reactive theme application, and
+ * visibility subscription.
+ *
+ * The supplied component receives no props; it should call `usePluginAPI()`
+ * and `useVisibility()` internally as needed. By default the root remounts
+ * when the resource changes (see
+ * {@link PluginRootConfig.remountOnResourceChange}); even then, use
+ * `api.resource.id` as a key inside your component if you need finer
+ * control.
+ */
+declare function createPluginRoot<TSchema extends PluginSchema = PluginSchema>(config: PluginRootConfig<TSchema>): void;
+
+/**
+ * Persist a value to the per-resource plugin cache: debounced writes while
+ * the value changes, plus a flush on `pagehide` / `beforeunload` / unmount
+ * so no pending update is lost.
+ *
+ * Use this for reader positions, resume timestamps, and similar
+ * continuously-changing state. Pass `undefined` as the value (or
+ * `disabled: true`) to skip persistence while the real value is loading.
+ */
+declare function useCacheWriter<T>(options: {
+    readonly key: string;
+    readonly value: T | undefined;
+    readonly encode: (value: T) => string;
+    readonly disabled?: boolean;
+    readonly debounceMs?: number;
+}): void;
+
+/**
+ * Materialization progress of the plugin's `extractArchive` hook:
+ * `"extracting"` while the host reports in-flight work, `"done"` once
+ * progress was seen and the record went idle again, `"idle"` when no
+ * extraction has ever been observed (or a poll failed — the host may
+ * not be serving yet).
+ */
+type ExtractProgressState = {
+    readonly state: "idle";
+} | {
+    readonly state: "extracting";
+    readonly done: number;
+    readonly total: number;
+} | {
+    readonly state: "done";
+};
+/**
+ * Reactive materialization progress for the current resource. Polls
+ * `api.extractProgressUrl()` and tracks the seen-progress transition:
+ * a plugin that called `extractArchive` can show "extracting" while the
+ * host materializes, then switch to "done" when the record expires.
+ */
+declare function useExtractProgress(): ExtractProgressState;
+
+export { type DefinePluginAPIOptions, type ExtractProgressState, type FullPluginAPI, PluginAPIProvider, type PluginRootConfig, StubPluginAPIProvider, createPluginQueryAPI, createPluginRoot, createPluginTranslation, definePluginAPI, useCacheWriter, useExtractProgress, usePluginAPI, useVisibility };