@hoardodile/sdk-react 0.0.0

package/src/query.ts

@@ -0,0 +1,407 @@
+import type {
+	AnchorData,
+	Danmaku,
+	DanmakuListFilter,
+	DanmakuMode,
+	Message,
+	PluginSchema,
+} from "@hoardodile/sdk-types"
+import type {
+	Codec,
+	Host,
+	MutationState,
+	PluginFonts,
+	QueryState,
+	ReactivePluginAPI,
+	Theme,
+} from "@hoardodile/sdk-web"
+import {
+	extractFontsPayload,
+	extractPrefPayload,
+	extractThemePayload,
+	getPluginPrefStore,
+	invalidatePushKeys,
+	setPluginPref,
+	subscribeToPrefChanges,
+} from "@hoardodile/sdk-web"
+import { useEffect, useMemo, useState } from "react"
+
+// ── Query state helpers ──────────────────────────────────────────────────
+
+function buildQuerySuccessState<T>(data: T): QueryState<T> {
+	return { data, isLoading: false, isError: false, error: null }
+}
+
+function buildQueryErrorState(err: unknown): QueryState<never> {
+	return {
+		data: undefined,
+		isLoading: false,
+		isError: true,
+		error: err instanceof Error ? err : new Error(String(err)),
+	}
+}
+
+function buildQueryLoadingState(): QueryState<never> {
+	return { data: undefined, isLoading: true, isError: false, error: null }
+}
+
+// ── Base query hook ──────────────────────────────────────────────────────
+
+type PluginRequestKey = keyof import("@hoardodile/sdk-web").PluginRequests
+type HostPushKey = keyof import("@hoardodile/sdk-web").HostPushes
+
+type UseHostQueryOptions<K extends PluginRequestKey> = {
+	readonly method: K
+	readonly params: import("@hoardodile/sdk-web").RequestInput<K>
+	readonly invalidateKey: HostPushKey
+	readonly extraDeps?: readonly unknown[]
+}
+
+function useHostQuery<K extends PluginRequestKey, T>(
+	host: Host,
+	options: UseHostQueryOptions<K>,
+): QueryState<T> {
+	const { method, params, invalidateKey, extraDeps = [] } = options
+	const [state, setState] = useState<QueryState<T>>(buildQueryLoadingState)
+
+	useEffect(() => {
+		let cancelled = false
+		setState(buildQueryLoadingState())
+
+		function fetchData() {
+			const args = params === undefined ? [] : [params]
+			host
+				.request(method, ...(args as never))
+				.then((result) => {
+					if (!cancelled) {
+						setState(buildQuerySuccessState(result as T))
+					}
+				})
+				.catch((err: unknown) => {
+					if (!cancelled) {
+						setState(buildQueryErrorState(err))
+					}
+				})
+		}
+
+		fetchData()
+		const unsub = host.subscribe(invalidateKey, fetchData as never)
+		return function cleanup() {
+			cancelled = true
+			unsub()
+		}
+	}, [host, method, invalidateKey, ...extraDeps])
+
+	return state
+}
+
+// ── File queries ─────────────────────────────────────────────────────────
+
+function useFileList(host: Host, contextDeps: readonly unknown[]) {
+	return useHostQuery<"listFiles", readonly string[]>(host, {
+		method: "listFiles",
+		params: undefined,
+		invalidateKey: invalidatePushKeys.resource,
+		extraDeps: contextDeps,
+	})
+}
+// ── Message queries ──────────────────────────────────────────────────────
+
+function useMessageList(host: Host, contextDeps: readonly unknown[]) {
+	return useHostQuery<"listMessages", readonly Message[]>(host, {
+		method: "listMessages",
+		params: undefined,
+		invalidateKey: invalidatePushKeys.messages,
+		extraDeps: contextDeps,
+	})
+}
+
+// ── Danmaku queries ───────────────────────────────────────────────────────
+
+function useDanmakuList(
+	host: Host,
+	contextDeps: readonly unknown[],
+	filter?: DanmakuListFilter,
+) {
+	return useHostQuery<"listDanmaku", readonly Danmaku[]>(host, {
+		method: "listDanmaku",
+		params: { filter },
+		invalidateKey: invalidatePushKeys.danmaku,
+		// The filter object is a fresh literal on every render; a stable
+		// serialization keeps the effect from refetching in a loop while
+		// still refetching when any filter value actually changes.
+		extraDeps: [
+			...contextDeps,
+			filter === undefined ? undefined : JSON.stringify(filter),
+		],
+	})
+}
+
+// ── Mutations ────────────────────────────────────────────────────────────
+
+function useHostMutation<
+	K extends PluginRequestKey,
+	TArgs extends import("@hoardodile/sdk-web").RequestInput<K>,
+	TResult extends import("@hoardodile/sdk-web").RequestOutput<K>,
+>(host: Host, method: K): MutationState<TArgs, TResult> {
+	const [isPending, setIsPending] = useState(false)
+
+	async function mutate(args: TArgs): Promise<TResult> {
+		setIsPending(true)
+		try {
+			const requestArgs = args === undefined ? [] : [args]
+			return (await host.request(
+				method,
+				...(requestArgs as never),
+			)) as unknown as TResult
+		} finally {
+			setIsPending(false)
+		}
+	}
+
+	return { mutate, isPending }
+}
+
+function useCreateMessage(
+	host: Host,
+): MutationState<
+	{ readonly body: string; readonly anchor?: unknown },
+	Message
+> {
+	const base = useHostMutation<
+		"createMessage",
+		{ readonly body: string; readonly anchor?: AnchorData },
+		Message
+	>(host, "createMessage")
+	// The hook input is the raw plugin location data; the wire anchor is
+	// the `{ data }` envelope (see sdk-web runtime).
+	return {
+		isPending: base.isPending,
+		async mutate(input) {
+			return base.mutate({
+				body: input.body,
+				anchor: input.anchor === undefined ? undefined : { data: input.anchor },
+			})
+		},
+	}
+}
+
+function useCreateDanmaku(host: Host): MutationState<
+	{
+		readonly text: string
+		readonly anchor: unknown
+		readonly mode?: DanmakuMode
+	},
+	Danmaku
+> {
+	const base = useHostMutation<
+		"createDanmaku",
+		{
+			readonly text: string
+			readonly anchor: AnchorData
+			readonly mode?: DanmakuMode
+		},
+		Danmaku
+	>(host, "createDanmaku")
+	return {
+		isPending: base.isPending,
+		async mutate(input) {
+			return base.mutate({
+				text: input.text,
+				anchor: { data: input.anchor },
+				mode: input.mode,
+			})
+		},
+	}
+}
+
+// ── Preferences hook ─────────────────────────────────────────────────────
+
+/** Serialize a typed value to its stored string form (codec or String()). */
+function encodePrefValue<T>(codec: Codec<T> | undefined, value: T): string {
+	return codec !== undefined ? codec.encode(value) : String(value)
+}
+
+/** Parse a stored string back to its typed form, falling back on malformed input. */
+function decodePrefValue<T>(
+	codec: Codec<T> | undefined,
+	raw: string,
+	fallback: T,
+): T {
+	if (codec === undefined) return raw as unknown as T
+	const decoded = codec.decode(raw)
+	return decoded !== undefined ? decoded : fallback
+}
+
+function usePref<T>(
+	host: Host,
+	key: string,
+	defaultValue: T,
+	codec?: Codec<T>,
+): readonly [T, (value: T) => void] {
+	const store = getPluginPrefStore()
+	const encodedDefault = useMemo(
+		function computeEncodedDefault() {
+			return encodePrefValue(codec, defaultValue)
+		},
+		[codec, defaultValue],
+	)
+
+	const [raw, setRawState] = useState(function getInitial() {
+		return store.get(key) ?? encodedDefault
+	})
+
+	useEffect(
+		function subscribeToStoreChanges() {
+			return subscribeToPrefChanges(key, function onChange() {
+				setRawState(getPluginPrefStore().get(key) ?? encodedDefault)
+			})
+		},
+		[key, encodedDefault],
+	)
+
+	useEffect(
+		function subscribeToHostPush() {
+			return host.subscribe("prefsChanged", function handlePrefPush(data) {
+				const payload = extractPrefPayload(data)
+				if (payload === undefined || payload.key !== key) return
+				if (payload.value !== undefined) {
+					setPluginPref(key, payload.value)
+					setRawState(payload.value)
+				} else {
+					setRawState(encodedDefault)
+				}
+			})
+		},
+		[host, key, encodedDefault],
+	)
+
+	const value = useMemo(
+		function decodeValue() {
+			return decodePrefValue(codec, raw, defaultValue)
+		},
+		[raw, codec, defaultValue],
+	)
+
+	function setValue(next: T): void {
+		const encoded = encodePrefValue(codec, next)
+		setPluginPref(key, encoded)
+		setRawState(encoded)
+		host.request("setPref", { key, value: encoded }).catch(() => {})
+	}
+
+	return [value, setValue] as const
+}
+
+// ── Host push hooks ──────────────────────────────────────────────────────
+
+/**
+ * Subscribe to a host push and merge the extracted patch into state. The
+ * extractor returns `undefined` (or an empty patch) when the push carries
+ * no applicable change, so spurious pushes never re-render.
+ */
+function useHostPush<T>(
+	host: Host,
+	key: HostPushKey,
+	extract: (data: unknown) => Partial<T> | undefined,
+	initial: T,
+): T {
+	const [value, setValue] = useState(initial)
+
+	useEffect(() => {
+		const unsub = host.subscribe(key, function handlePush(data) {
+			const patch = extract(data)
+			if (patch !== undefined) {
+				setValue((prev) => ({ ...prev, ...patch }))
+			}
+		})
+		return function cleanup() {
+			unsub()
+		}
+	}, [host, key, extract])
+
+	return value
+}
+
+// ── Theme hook ───────────────────────────────────────────────────────────
+
+function extractThemePatch(data: unknown): Partial<Theme> | undefined {
+	const { resolvedTheme, palette, iconStyle } = extractThemePayload(data)
+	if (
+		resolvedTheme === undefined &&
+		palette === undefined &&
+		iconStyle === undefined
+	) {
+		return undefined
+	}
+	return {
+		...(resolvedTheme !== undefined ? { resolvedTheme } : {}),
+		...(palette !== undefined ? { palette } : {}),
+		...(iconStyle !== undefined ? { iconStyle } : {}),
+	}
+}
+
+function useTheme(
+	host: Host,
+	initialResolvedTheme: string,
+	initialPalette: string,
+	initialIconStyle: string,
+): Theme {
+	return useHostPush(host, "themeChanged", extractThemePatch, {
+		resolvedTheme: initialResolvedTheme,
+		palette: initialPalette,
+		iconStyle: initialIconStyle,
+	})
+}
+
+// ── Font hook ────────────────────────────────────────────────────────────
+
+function useFont(host: Host, initialFonts: PluginFonts): PluginFonts {
+	return useHostPush(host, "fontsChanged", extractFontsPayload, initialFonts)
+}
+
+// ── Public factory ───────────────────────────────────────────────────────
+
+/**
+ * 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()`.
+ */
+export 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> {
+	// Refetch when the iframe is rebound to another resource without a
+	// remount (createPluginRoot's `remountOnResourceChange: false`). With
+	// the default remount this dep is constant for the mount's lifetime.
+	const contextDeps = [ctx.resId]
+	return {
+		useFileList: () =>
+			useFileList(host, contextDeps) as QueryState<readonly TSchema["file"][]>,
+		useMessageList: () => useMessageList(host, contextDeps),
+		useCreateMessage: () => useCreateMessage(host),
+		useDanmakuList: (filter?: DanmakuListFilter) =>
+			useDanmakuList(host, contextDeps, filter),
+		useCreateDanmaku: () => useCreateDanmaku(host),
+		usePref: <T>(key: string, defaultValue: T, codec?: Codec<T>) =>
+			usePref(host, key, defaultValue, codec),
+		useTheme: () =>
+			useTheme(host, ctx.resolvedTheme, ctx.palette, ctx.iconStyle),
+		useFont: () => useFont(host, ctx.fonts),
+	}
+}

package/src/root.tsx

@@ -0,0 +1,144 @@
+import type { PluginSchema } from "@hoardodile/sdk-types"
+import {
+	applyFonts,
+	applyTheme,
+	createIframeHostAPI,
+	ensureHostBridge,
+	getVisibilitySnapshot,
+	mountPlugin,
+	subscribeToVisibility,
+} from "@hoardodile/sdk-web"
+import type { ComponentType, Provider, ReactNode } from "react"
+import { createElement, useEffect, useSyncExternalStore } from "react"
+import { flushSync } from "react-dom"
+import { createRoot } from "react-dom/client"
+import { usePluginAPI } from "./context.tsx"
+import type { FullPluginAPI } from "./define-api.ts"
+import { createPluginQueryAPI } from "./query.ts"
+
+export 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
+}
+
+function ThemeSync({ children }: { readonly children: ReactNode }) {
+	const api = usePluginAPI()
+	const { resolvedTheme, palette, iconStyle } = api.useTheme()
+
+	useEffect(
+		function applyOnChange() {
+			applyTheme(resolvedTheme, palette, iconStyle)
+		},
+		[resolvedTheme, palette, iconStyle],
+	)
+
+	return children
+}
+
+function FontSync({ children }: { readonly children: ReactNode }) {
+	const api = usePluginAPI()
+	const { family, cssPaths } = api.useFont()
+
+	useEffect(
+		function applyOnChange() {
+			applyFonts(family, cssPaths)
+		},
+		[family, cssPaths],
+	)
+
+	return children
+}
+
+/**
+ * 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.
+ */
+export function useVisibility(): boolean {
+	return useSyncExternalStore(subscribeToVisibility, getVisibilitySnapshot)
+}
+
+/**
+ * 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.
+ */
+export function createPluginRoot<TSchema extends PluginSchema = PluginSchema>(
+	config: PluginRootConfig<TSchema>,
+): void {
+	let root: ReturnType<typeof createRoot> | undefined
+
+	mountPlugin(function onContext(ctx) {
+		flushSync(() => {
+			if (root === undefined) {
+				const el = document.getElementById("root")
+				if (el === null) {
+					console.error("[plugin] #root element not found — cannot mount")
+					return
+				}
+				root = createRoot(el)
+			}
+			const host = ensureHostBridge()
+			const baseApi = createIframeHostAPI<TSchema>(ctx)
+			const api: FullPluginAPI<TSchema> = {
+				...baseApi,
+				...createPluginQueryAPI(host, {
+					resolvedTheme: ctx.resolvedTheme,
+					palette: ctx.palette,
+					iconStyle: ctx.iconStyle,
+					fonts: ctx.fonts,
+					resId: ctx.resId,
+				}),
+			}
+			applyTheme(ctx.resolvedTheme, ctx.palette, ctx.iconStyle)
+			applyFonts(ctx.fonts.family, ctx.fonts.cssPaths)
+			root.render(
+				createElement(
+					config.provider,
+					{ value: api },
+					createElement(
+						ThemeSync,
+						null,
+						createElement(
+							FontSync,
+							null,
+							createElement(
+								config.render,
+								config.remountOnResourceChange === false
+									? {}
+									: { key: ctx.resId },
+							),
+						),
+					),
+				),
+			)
+		})
+	})
+}

package/src/use-cache-writer.ts

@@ -0,0 +1,61 @@
+import { useEffect, useRef } from "react"
+import { usePluginAPI } from "./context.tsx"
+
+const DEFAULT_DEBOUNCE_MS = 500
+
+/**
+ * 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.
+ */
+export function useCacheWriter<T>(options: {
+	readonly key: string
+	readonly value: T | undefined
+	readonly encode: (value: T) => string
+	readonly disabled?: boolean
+	readonly debounceMs?: number
+}): void {
+	const api = usePluginAPI()
+	const {
+		key,
+		value,
+		encode,
+		disabled = false,
+		debounceMs = DEFAULT_DEBOUNCE_MS,
+	} = options
+	const latestRef = useRef(value)
+	latestRef.current = value
+	const encodeRef = useRef(encode)
+	encodeRef.current = encode
+
+	useEffect(() => {
+		if (disabled || value === undefined) return
+		const timer = setTimeout(() => {
+			const snap = latestRef.current
+			if (snap === undefined) return
+			api.setCache(key, encodeRef.current(snap))
+		}, debounceMs)
+		return () => clearTimeout(timer)
+	}, [api, key, value, disabled, debounceMs])
+
+	useEffect(() => {
+		if (disabled) return
+		function flush() {
+			const snap = latestRef.current
+			if (snap === undefined) return
+			api.setCache(key, encodeRef.current(snap))
+		}
+		window.addEventListener("pagehide", flush)
+		window.addEventListener("beforeunload", flush)
+		return () => {
+			window.removeEventListener("pagehide", flush)
+			window.removeEventListener("beforeunload", flush)
+			flush()
+		}
+		// api is structurally stable; flush reads the latest value via ref.
+	}, [api, key, disabled])
+}