@world-engines/create-project 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,46 @@
+WorldEngine 官方作者工具许可证
+
+版权所有 (c) 2026 Nixdorfer。保留所有权利。
+
+本仓库的源代码、构建材料及附带资源（统称“本作品”）不是开源软件，
+不适用任何 OSI 认证的开源许可证。
+
+一、官方作者工具分发许可
+
+版权所有者可以通过其官方网站、npm registry、签名安装包或其他官方渠道，
+复制并分发由本作品构建的 WorldEngine 作者工具及其必要运行资源
+（统称“官方作者工具”）。仅版权所有者或其书面指定的发布者享有此分发权。
+
+二、作者用户许可
+
+从官方渠道取得官方作者工具的作者用户，可以：
+
+1. 安装和运行官方作者工具；
+2. 使用官方作者工具创作、编辑、预览、导入、导出和提交其有权处理的内容；
+3. 为上述使用目的制作合理必要的本地备份副本。
+
+三、未授予的权利
+
+除第二条明确允许的行为外，本许可证不授予作者用户或其他第三方以下权利：
+
+1. 修改、改编、反编译、反汇编或制作官方作者工具的派生作品；
+2. 复制、镜像、转发、再上传、出售、出租、再分发或再许可官方作者工具；
+3. 使用本作品的源代码、构建材料或任何部分开发、提供或训练其他产品或服务；
+4. 删除或规避版权、许可、签名、访问控制或其他权利管理信息。
+
+法律强制允许且合同不得排除的权利不受上述限制影响。
+
+四、源代码查看
+
+第三方可以在已获合法访问权限的范围内查看本作品，用于审查、安全研究或学习参考；
+查看不授予运行、复制、修改、分发、再许可或用于其他产品与服务的权利。
+
+五、无担保与责任限制
+
+本作品与官方作者工具均按“现状”提供，不附带任何明示或暗示的担保。
+在适用法律允许的最大范围内，版权所有者不对因访问或使用本作品或官方作者工具
+造成的任何损失承担责任。
+
+六、终止
+
+违反本许可证将立即终止相应的访问与使用权；终止不影响版权所有者已经产生的权利和救济。

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+export interface CreateProjectCliIo {
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+}
+export declare function runCreateProjectCli(argv: readonly string[], io?: CreateProjectCliIo): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { initializeLocalAuthorProject } from "./index.js";
+function argumentError(message) {
+    return Object.assign(new Error(message), { code: "E_ARGUMENT_INVALID" });
+}
+function parseArguments(argv) {
+    let target;
+    let bootstrapFile;
+    let installDependencies = true;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--no-install") {
+            installDependencies = false;
+            continue;
+        }
+        if (argument === "--target" || argument === "--bootstrap-file") {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith("--"))
+                throw argumentError(`${argument} 需要一个路径`);
+            if (argument === "--target") {
+                if (target !== undefined)
+                    throw argumentError("target 只能指定一次");
+                target = value;
+            }
+            else {
+                if (bootstrapFile !== undefined)
+                    throw argumentError("--bootstrap-file 只能指定一次");
+                bootstrapFile = value;
+            }
+            index += 1;
+            continue;
+        }
+        if (!argument.startsWith("--") && target === undefined) {
+            target = argument;
+            continue;
+        }
+        throw argumentError(`未知参数：${argument}`);
+    }
+    return {
+        ...(target === undefined ? {} : { target }),
+        ...(bootstrapFile === undefined ? {} : { bootstrapFile }),
+        installDependencies,
+    };
+}
+export async function runCreateProjectCli(argv, io = {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+}) {
+    try {
+        const options = parseArguments(argv);
+        if (options.target === undefined) {
+            io.stderr("用法：create-worldengine-project <empty-directory> [--bootstrap-file <cmd>] [--no-install]\n");
+            return 2;
+        }
+        const receipt = await initializeLocalAuthorProject({
+            target: resolve(options.target),
+            install_dependencies: options.installDependencies,
+            ...(options.bootstrapFile === undefined ? {} : { bootstrap_file: resolve(options.bootstrapFile) }),
+        });
+        io.stdout(`${JSON.stringify(receipt)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error ? String(error.code) : "E_INITIALIZATION_FAILED";
+        const message = error instanceof Error ? error.message : String(error);
+        io.stderr(`${code}: ${message}\n`);
+        return 1;
+    }
+}
+const invokedPath = process.argv[1];
+if (invokedPath !== undefined && resolve(invokedPath).toLocaleLowerCase("en-US") === resolve(fileURLToPath(import.meta.url)).toLocaleLowerCase("en-US")) {
+    void runCreateProjectCli(process.argv.slice(2)).then((exitCode) => {
+        process.exitCode = exitCode;
+    });
+}

package/dist/default-view/app-v3.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_CHAT_APP_V3: string;

package/dist/default-view/app-v3.js

@@ -0,0 +1,83 @@
+export const DEFAULT_CHAT_APP_V3 = String.raw `import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import type { KeyboardEvent as ReactKeyboardEvent } from "react";
+import { applyMessageDeleted, applyMessagePage, isPreviewModelUnavailable, loadMessages, mergeMessages, messageIdFromEvent, publicError, readTheme, requireChatPlay, resolvedThemeFromEvent, type ChatMessage, type ChatPlayConversationBridge } from "./chatplay";
+import { PlayerPanel, type PlayerPanelKind } from "./player-panel";
+
+type IconName = "add" | "send" | "model" | "worldline" | "progress" | "assets" | "resources" | "state" | "actions" | "search";
+type PendingTurn = { readonly turnId: string; readonly epoch: number; readonly streamId?: string };
+type EarlyTurnSignal = { readonly streamId?: string; readonly terminal?: "assistant" | "done" | "error"; readonly error?: unknown };
+const actions: readonly { kind: PlayerPanelKind; label: string; icon: IconName }[] = [
+  { kind: "model", label: "切换模型", icon: "model" }, { kind: "worldline", label: "世界线", icon: "worldline" },
+  { kind: "progress", label: "剧情进度", icon: "progress" }, { kind: "assets", label: "资源", icon: "assets" },
+  { kind: "resources", label: "已解锁", icon: "resources" }, { kind: "state", label: "角色状态", icon: "state" },
+  { kind: "actions", label: "互动选择", icon: "actions" }, { kind: "search", label: "历史搜索", icon: "search" },
+];
+function Icon({ name }: { name: IconName }) {
+  const paths: Record<IconName, React.ReactNode> = {
+    add: <path d="M12 5v14M5 12h14" />, send: <path d="m4 5 16 7-16 7 3-7-3-7Zm3 7h13" />,
+    model: <><rect x="4" y="5" width="16" height="14" rx="3" /><path d="M8 10h.01M12 10h.01M16 10h.01M8 14h8" /></>,
+    worldline: <><circle cx="6" cy="6" r="2" /><circle cx="18" cy="18" r="2" /><circle cx="18" cy="6" r="2" /><path d="M8 6h5a5 5 0 0 1 5 5v5M8 6c5 0 3 12 8 12" /></>,
+    progress: <><path d="M5 19V9m7 10V5m7 14v-7M3 19h18" /></>, assets: <><rect x="4" y="5" width="16" height="14" rx="2" /><circle cx="9" cy="10" r="1.5" /><path d="m5 17 5-5 3 3 2-2 4 4" /></>,
+    resources: <><path d="M12 3 19 7v10l-7 4-7-4V7l7-4Z" /><path d="m5 7 7 4 7-4M12 11v10" /></>, state: <><circle cx="12" cy="12" r="8" /><path d="M12 8v4l3 2M5 5l2 2m10-2-2 2" /></>,
+    actions: <><path d="M5 7h14M5 12h14M5 17h9" /><path d="m15 15 3 2-3 2" /></>, search: <><circle cx="10.5" cy="10.5" r="5.5" /><path d="m15 15 4 4" /></>,
+  };
+  return <svg viewBox="0 0 24 24" aria-hidden="true">{paths[name]}</svg>;
+}
+function nearBottom(node: HTMLElement | null) { return !node || node.scrollHeight - node.scrollTop - node.clientHeight < 72; }
+function stringField(payload: unknown, field: string): string | null { return payload && typeof payload === "object" && typeof (payload as Record<string, unknown>)[field] === "string" ? (payload as Record<string, string>)[field] : null; }
+function turnIdFrom(payload: unknown): string | null { return stringField(payload, "turnId") ?? (payload && typeof payload === "object" ? stringField((payload as { meta?: unknown }).meta, "turnId") : null); }
+function isAssistantTurn(message: ChatMessage, turnId: string): boolean { return message.role === "assistant" && turnIdFrom(message.meta) === turnId; }
+function assistantTurnIdFrom(payload: unknown): string | null { return stringField(payload, "role") === "assistant" ? turnIdFrom(payload) : null; }
+
+export function App() {
+  const [bridge, setBridge] = useState<ChatPlayConversationBridge | null>(null); const [messages, setMessages] = useState<readonly ChatMessage[]>([]); const [hasEarlier, setHasEarlier] = useState(false);
+  const [draft, setDraft] = useState(""); const [sending, setSending] = useState(false); const [pendingTurn, setPendingTurn] = useState<PendingTurn | null>(null); const [composing, setComposing] = useState(false); const [title, setTitle] = useState("故事对话"); const [theme, setTheme] = useState<"light" | "dark">("dark"); const [error, setError] = useState<string | null>(null); const [menuOpen, setMenuOpen] = useState(false); const [panel, setPanel] = useState<PlayerPanelKind | null>(null);
+  const transcript = useRef<HTMLElement>(null); const input = useRef<HTMLTextAreaElement>(null); const menu = useRef<HTMLDivElement>(null); const bridgeRef = useRef<ChatPlayConversationBridge | null>(null); const pendingTurnRef = useRef<PendingTurn | null>(null); const earlySignals = useRef(new Map<string, EarlyTurnSignal>()); const acceptingEpoch = useRef<number | null>(null); const generation = useRef(0); const worldlineEpoch = useRef(0); const requestSerial = useRef(0); const errorVersion = useRef(0); const errorKind = useRef<"read" | "other">("other"); const deletedIds = useRef(new Set<string>()); const inFlight = useRef(false); const themeVersion = useRef(0);
+  const showError = useCallback((message: string, kind: "read" | "other" = "other") => { errorVersion.current += 1; errorKind.current = kind; setError(message); }, []);
+  const clearErrorIfUnchanged = useCallback((version: number) => { if (errorVersion.current === version) setError(null); }, []);
+  const clearReadErrorIfUnchanged = useCallback((version: number) => { if (errorVersion.current === version && errorKind.current === "read") setError(null); }, []);
+  const clearPendingTurn = useCallback((turnId?: string | null, streamId?: string | null) => { const pending = pendingTurnRef.current; const matchesLocalTurnStream = pending !== null && pending.streamId === undefined && streamId === pending.turnId; if (!pending || pending.epoch !== worldlineEpoch.current || turnId !== pending.turnId && (streamId === null || streamId === undefined || streamId !== pending.streamId && !matchesLocalTurnStream)) return; pendingTurnRef.current = null; setPendingTurn(null); }, []);
+  const rememberEarlySignal = useCallback((turnId: string | null, signal: EarlyTurnSignal) => { if (!turnId || !inFlight.current || acceptingEpoch.current !== worldlineEpoch.current) return; const earlier = earlySignals.current.get(turnId); earlySignals.current.set(turnId, { ...earlier, ...signal }); }, []);
+  const resizeInput = useCallback(() => { const node = input.current; if (!node) return; node.style.height = "auto"; const computed = window.getComputedStyle(node); const border = (Number.parseFloat(computed.borderTopWidth) || 0) + (Number.parseFloat(computed.borderBottomWidth) || 0); const maxContent = 160 - border; node.style.height = Math.min(node.scrollHeight + border, 160) + "px"; node.style.overflowY = node.scrollHeight > maxContent ? "auto" : "hidden"; }, []);
+  useLayoutEffect(() => { resizeInput(); }, [draft, resizeInput]);
+  const refreshMessages = useCallback(async (api: ChatPlayConversationBridge, preservePosition = true, stamp = generation.current) => {
+    const shouldStick = !preservePosition || nearBottom(transcript.current); const request = ++requestSerial.current; const errorsBeforeRequest = errorVersion.current;
+    try { const next = await loadMessages(api); if (stamp !== generation.current || request !== requestSerial.current) return; const pending = pendingTurnRef.current; if (pending && pending.epoch === worldlineEpoch.current && next.some((message) => isAssistantTurn(message, pending.turnId))) clearPendingTurn(pending.turnId); setMessages((current) => applyMessagePage({ request: request - 1, deletedIds: deletedIds.current, messages: current }, request, next).messages); setHasEarlier(next.length >= 80); clearReadErrorIfUnchanged(errorsBeforeRequest); if (shouldStick) requestAnimationFrame(() => transcript.current?.scrollTo({ top: transcript.current.scrollHeight })); }
+    catch (reason) { if (stamp !== generation.current || request !== requestSerial.current) return; showError(isPreviewModelUnavailable(reason) ? "当前预览未连接模型" : publicError(reason, "读取消息失败") ?? "读取消息失败", "read"); }
+  }, [clearPendingTurn, clearReadErrorIfUnchanged, showError]);
+  const refreshTheme = useCallback(async (api: ChatPlayConversationBridge, payload?: unknown, stamp = generation.current) => {
+    const eventTheme = resolvedThemeFromEvent(payload); if (eventTheme) { themeVersion.current += 1; if (stamp === generation.current) setTheme(eventTheme); return; }
+    const version = themeVersion.current; try { const snapshot = await readTheme(api); if (stamp === generation.current && version === themeVersion.current) setTheme(snapshot.resolved); } catch { /* 主题读取不能阻断消息。 */ }
+  }, []);
+  const resetWorldline = useCallback(() => { const api = bridgeRef.current; if (!api) return; worldlineEpoch.current += 1; earlySignals.current.clear(); acceptingEpoch.current = null; pendingTurnRef.current = null; setPendingTurn(null); errorVersion.current += 1; setError(null); deletedIds.current.clear(); requestSerial.current += 1; setMessages([]); setHasEarlier(false); void refreshMessages(api, false, generation.current); }, [refreshMessages]);
+  useEffect(() => {
+    const stamp = ++generation.current; let active = true; let stop = () => {};
+    try {
+      const api = requireChatPlay(); const refresh = () => { void refreshMessages(api, true, stamp); };
+      void api.ready.then(() => {
+        if (!active || stamp !== generation.current) return; bridgeRef.current = api; setBridge(api);
+        const remove = (payload: unknown) => { const id = messageIdFromEvent(payload); if (id) { deletedIds.current.add(id); setMessages((current) => applyMessageDeleted({ request: requestSerial.current, deletedIds: deletedIds.current, messages: current }, id).messages); } refresh(); };
+        const noteStreamStart = (payload: unknown) => { const pending = pendingTurnRef.current; const turnId = turnIdFrom(payload); const streamId = stringField(payload, "streamId"); rememberEarlySignal(turnId, { streamId: streamId ?? undefined }); if (!pending || pending.epoch !== worldlineEpoch.current || turnId !== pending.turnId || !streamId) return; const next = { ...pending, streamId }; pendingTurnRef.current = next; setPendingTurn(next); };
+        const noteAssistant = (payload: unknown) => { const turnId = assistantTurnIdFrom(payload); rememberEarlySignal(turnId, { terminal: "assistant" }); if (turnId) clearPendingTurn(turnId); refresh(); };
+        const endStream = (payload: unknown) => { const turnId = turnIdFrom(payload); const streamId = stringField(payload, "streamId"); rememberEarlySignal(turnId, { streamId: streamId ?? undefined, terminal: "done" }); clearPendingTurn(turnId, streamId); refresh(); };
+        const streamError = (payload: unknown) => { const epoch = worldlineEpoch.current; const turnId = turnIdFrom(payload); const streamId = stringField(payload, "streamId"); rememberEarlySignal(turnId, { streamId: streamId ?? undefined, terminal: "error", error: payload }); const pending = pendingTurnRef.current; const belongsToPending = Boolean(pending && pending.epoch === epoch && (turnId === pending.turnId || streamId !== null && (streamId === pending.streamId || pending.streamId === undefined && streamId === pending.turnId))); queueMicrotask(() => { if (!active || stamp !== generation.current || epoch !== worldlineEpoch.current) return; if (belongsToPending) clearPendingTurn(turnId, streamId); if (!turnId && !streamId || belongsToPending) showError(isPreviewModelUnavailable(payload) ? "当前预览未连接模型" : publicError(payload, "生成出错") ?? "生成出错"); }); };
+        const stops = [api.on("themeChanged", (payload) => { void refreshTheme(api, payload, stamp); }), api.on("messageAdded", noteAssistant), api.on("messageUpdated", noteAssistant), api.on("messageDeleted", remove), api.on("streamStart", noteStreamStart), api.on("streamDelta", refresh), api.on("streamDone", endStream), api.on("streamError", streamError), api.on("worldlineActivated", resetWorldline), api.on("worldlineForked", resetWorldline), api.on("localeChanged", () => { void api.getLocale().then((locale) => { if (active && stamp === generation.current) document.documentElement.lang = locale; }).catch(() => {}); })];
+        stop = () => stops.forEach((unsubscribe) => unsubscribe()); void refreshMessages(api, false, stamp); void refreshTheme(api, undefined, stamp);
+        void api.getScenarioMeta().then((meta) => { if (active && stamp === generation.current) setTitle(meta.title && meta.title !== meta.scriptId ? meta.title : "故事对话"); }).catch(() => {});
+        void api.getLocale().then((locale) => { if (active && stamp === generation.current) document.documentElement.lang = locale; }).catch(() => {});
+      }).catch((reason) => { if (active) showError(publicError(reason, "视图未连接") ?? "视图未连接"); });
+    } catch (reason) { showError(publicError(reason, "视图未连接") ?? "视图未连接"); }
+    return () => { active = false; bridgeRef.current = null; earlySignals.current.clear(); acceptingEpoch.current = null; pendingTurnRef.current = null; setPendingTurn(null); generation.current += 1; stop(); };
+  }, [clearPendingTurn, refreshMessages, refreshTheme, rememberEarlySignal, resetWorldline, showError]);
+  useEffect(() => { const onKey = (event: KeyboardEvent) => { if (event.key === "Escape") { setMenuOpen(false); setPanel(null); } }; window.addEventListener("keydown", onKey); return () => window.removeEventListener("keydown", onKey); }, []);
+  const loadEarlier = useCallback(async () => { if (!bridge || !messages.length) return; const stamp = generation.current; const epoch = worldlineEpoch.current; const request = ++requestSerial.current; const errorsBeforeRequest = errorVersion.current; const node = transcript.current; const top = node?.scrollTop ?? 0; const height = node?.scrollHeight ?? 0; try { const older = await loadMessages(bridge, messages[0].id); if (stamp !== generation.current || epoch !== worldlineEpoch.current || request !== requestSerial.current) return; setMessages((current) => mergeMessages(current, older.filter((message) => !deletedIds.current.has(message.id)))); setHasEarlier(older.length >= 80); clearReadErrorIfUnchanged(errorsBeforeRequest); requestAnimationFrame(() => { if (node && epoch === worldlineEpoch.current) node.scrollTop = top + node.scrollHeight - height; }); } catch (reason) { if (stamp === generation.current && epoch === worldlineEpoch.current && request === requestSerial.current) showError(publicError(reason, "读取更早消息失败") ?? "读取更早消息失败", "read"); } }, [bridge, clearReadErrorIfUnchanged, messages, showError]);
+  const submit = useCallback(async () => { if (!bridge || inFlight.current || !draft.trim()) return; const stamp = generation.current; const epoch = worldlineEpoch.current; const errorsBeforeSend = errorVersion.current; inFlight.current = true; acceptingEpoch.current = epoch; earlySignals.current.clear(); setSending(true); try { const accepted = await bridge.sendUserMessage(draft.trim()); if (stamp !== generation.current || epoch !== worldlineEpoch.current) return; const early = earlySignals.current.get(accepted.turnId); const nextPending = { turnId: accepted.turnId, epoch, ...(early?.streamId ? { streamId: early.streamId } : {}) }; pendingTurnRef.current = nextPending; setPendingTurn(nextPending); setDraft(""); clearErrorIfUnchanged(errorsBeforeSend); if (early?.terminal === "assistant" || early?.terminal === "done") clearPendingTurn(accepted.turnId, early.streamId); if (early?.terminal === "error") { clearPendingTurn(accepted.turnId, early.streamId); showError(isPreviewModelUnavailable(early.error) ? "当前预览未连接模型" : publicError(early.error, "生成出错") ?? "生成出错"); } await refreshMessages(bridge, false, stamp); } catch (reason) { if (stamp === generation.current && epoch === worldlineEpoch.current) showError(isPreviewModelUnavailable(reason) ? "当前预览未连接模型" : publicError(reason, "发送失败，草稿已保留") ?? "发送失败，草稿已保留"); } finally { earlySignals.current.clear(); acceptingEpoch.current = null; inFlight.current = false; setSending(false); } }, [bridge, clearErrorIfUnchanged, clearPendingTurn, draft, refreshMessages, showError]);
+  const onKeyDown = (event: ReactKeyboardEvent<HTMLTextAreaElement>) => { const native = event.nativeEvent; if (event.key !== "Enter" || event.shiftKey || composing || native.isComposing || native.keyCode === 229 || window.matchMedia("(max-width: 720px)").matches) return; event.preventDefault(); void submit(); };
+  return <main className="chat-app" data-theme={theme}>
+    <header className="chat-header"><p className="chat-scene-title">{title}</p></header>{error && <p className="chat-error" role="alert">{error}</p>}{pendingTurn && <p className="chat-status" role="status">故事正在回应…</p>}
+    <section className="chat-transcript" ref={transcript} aria-label="对话记录">{hasEarlier && <button className="chat-retry" type="button" onClick={() => void loadEarlier()}>读取更早消息</button>}{messages.length ? messages.map((message) => <article className="chat-message" data-role={message.role} key={message.id}><p className="chat-message-body">{message.text}</p></article>) : <div className="chat-empty"><h2>对话从这里开始</h2><p>写下你的第一句话，故事会按当前剧本继续。</p></div>}</section>
+    <div className="chat-composer"><div className="chat-fab-row" ref={menu}><button className="chat-fab chat-fab-add" type="button" aria-expanded={menuOpen} aria-label="更多玩家功能" onClick={() => setMenuOpen((open) => !open)}><Icon name="add" /></button>{menuOpen && <div className="chat-fab-menu" aria-expanded="true">{actions.map((action) => <button className="chat-fab-option" type="button" key={action.kind} onClick={() => { setPanel(action.kind); setMenuOpen(false); }}><span className="chat-fab-option-icon"><Icon name={action.icon} /></span><span className="chat-fab-option-label">{action.label}</span></button>)}</div>}</div><textarea ref={input} className="chat-input" rows={1} value={draft} placeholder="写下你的回复…" aria-label="发送消息" onChange={(event) => setDraft(event.target.value)} onCompositionStart={() => setComposing(true)} onCompositionEnd={() => setComposing(false)} onKeyDown={onKeyDown} disabled={!bridge || sending} /><button className="chat-fab chat-fab-send" type="button" aria-label="发送消息" onClick={() => { void submit(); }} disabled={!bridge || sending || !draft.trim()}><Icon name="send" /></button></div>
+    {panel && bridge && <div className="chat-panel-overlay" role="presentation" onMouseDown={(event) => { if (event.target === event.currentTarget) setPanel(null); }}><PlayerPanel kind={panel} bridge={bridge} messages={messages} onWorldlineChange={resetWorldline} onClose={() => setPanel(null)} /></div>}
+  </main>;
+}
+`;

package/dist/default-view/app.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_CHAT_APP: string;

package/dist/default-view/app.js

@@ -0,0 +1,122 @@
+export const DEFAULT_CHAT_APP = String.raw `import { useCallback, useEffect, useRef, useState } from "react";
+import type { FormEvent, KeyboardEvent as ReactKeyboardEvent } from "react";
+import { applyMessageDeleted, applyMessagePage, emitConfiguredAction, isPreviewModelUnavailable, loadMessages, mergeMessages, messageIdFromEvent, optionalRead, publicError, readableError, readTheme, requireChatPlay, resolvedThemeFromEvent, sendMessage, type ChatMessage, type ChatPlayConversationBridge } from "./chatplay";
+import { viewConfig } from "./view-config";
+
+type Asset = Awaited<ReturnType<ChatPlayConversationBridge["listAssets"]>>[number];
+type ResourceGroup = Awaited<ReturnType<ChatPlayConversationBridge["getOwnedResources"]>>[number];
+type MobilePanel = "chat" | "story" | "details";
+
+const icon = (name: "menu" | "info" | "send" | "back") => ({ menu: <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 7h16M4 12h16M4 17h16" /></svg>, info: <svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="8" /><path d="M12 11v5m0-8h.01" /></svg>, send: <svg viewBox="0 0 24 24" aria-hidden="true"><path d="m4 5 16 7-16 7 3-7-3-7Zm3 7h13" /></svg>, back: <svg viewBox="0 0 24 24" aria-hidden="true"><path d="m14 6-6 6 6 6" /></svg> }[name]);
+
+function formatDate(ts: number, locale: string) { return new Intl.DateTimeFormat(locale, { hour: "2-digit", minute: "2-digit" }).format(new Date(ts)); }
+function isPreviewable(asset: Asset) { return asset.mime.startsWith("image/") || asset.mime.startsWith("audio/") || asset.mime.startsWith("video/"); }
+function stateValue(value: unknown): unknown { if (value && typeof value === "object" && "unlocked" in value) return (value as { unlocked: boolean }).unlocked ? "已解锁" : "未解锁"; if (value && typeof value === "object" && "value" in value) return (value as { value: unknown }).value; return value; }
+function optionalError(result: unknown): string | undefined { return result && typeof result === "object" && "error" in result && typeof (result as { error?: unknown }).error === "string" ? (result as { error: string }).error : undefined; }
+
+export function App() {
+  const [bridge, setBridge] = useState<ChatPlayConversationBridge | null>(null);
+  const [messages, setMessages] = useState<readonly ChatMessage[]>([]);
+  const [hasEarlier, setHasEarlier] = useState(false);
+  const [draft, setDraft] = useState("");
+  const [sending, setSending] = useState(false);
+  const [composing, setComposing] = useState(false);
+  const [error, setError] = useState<string | null>(null); const [actionNotice, setActionNotice] = useState<string | null>(null);
+  const [theme, setTheme] = useState<"light" | "dark">("dark");
+  const [locale, setLocale] = useState("zh-CN");
+  const [title, setTitle] = useState("故事对话");
+  const [progress, setProgress] = useState<number | null>(null);
+  const [assets, setAssets] = useState<readonly Asset[] | null>(null);
+  const [assetsEnabled, setAssetsEnabled] = useState(false);
+  const [resources, setResources] = useState<readonly ResourceGroup[] | null>(null);
+  const [stateKeys, setStateKeys] = useState<readonly string[]>([]);
+  const [stateEntries, setStateEntries] = useState<readonly { key: string; value: unknown }[]>([]);
+  const [unavailable, setUnavailable] = useState<readonly string[]>([]);
+  const [stateError, setStateError] = useState<string | null>(null); const themeVersion = useRef(0);
+  const [stateEnabled, setStateEnabled] = useState(viewConfig.variables.length > 0 || viewConfig.unlocks.length > 0);
+  const [mobilePanel, setMobilePanel] = useState<MobilePanel>("chat");
+  const [assetUrls, setAssetUrls] = useState<Record<string, string>>({});
+  const transcript = useRef<HTMLElement>(null); const mainRef = useRef<HTMLElement>(null); const storyRef = useRef<HTMLElement>(null); const detailsRef = useRef<HTMLElement>(null); const generation = useRef(0); const messageRequest = useRef(0); const sendInFlight = useRef(false); const deletedIds = useRef(new Set<string>());
+
+  const refreshMessages = useCallback(async (current: ChatPlayConversationBridge, preservePosition = true, stamp = generation.current) => {
+    try {
+      const request = ++messageRequest.current; const nextMessages = await loadMessages(current);
+      if (stamp !== generation.current || request !== messageRequest.current) return;
+      setMessages((existing) => applyMessagePage({ request: request - 1, deletedIds: deletedIds.current, messages: existing }, request, nextMessages).messages); setHasEarlier(nextMessages.length >= 80);
+      if (!preservePosition) requestAnimationFrame(() => transcript.current?.scrollTo({ top: transcript.current.scrollHeight }));
+    } catch (reason) { if (stamp === generation.current) { if (isPreviewModelUnavailable(reason)) { setError(null); setActionNotice("视图桥已连接；当前为界面预览，未连接模型。"); } else { setActionNotice(null); setError(publicError(reason, "读取消息失败") ?? "读取消息失败"); } } }
+  }, []);
+
+  const refreshDetails = useCallback(async (current: ChatPlayConversationBridge, stamp = generation.current) => {
+    try {
+      const capabilities = current.context()?.capabilities; const supportsAssets = capabilities?.supportsAssets === true; const supportsCustomState = (capabilities?.customStateMaxBytes ?? 0) > 0;
+      const [scenario, nextProgress, nextAssets, nextResources, nextKeys, nextLocale] = await Promise.all([
+        optionalRead(() => current.getScenarioMeta()), optionalRead(() => current.getProgress()), supportsAssets ? optionalRead(() => current.listAssets()) : optionalRead(async () => [] as Asset[]), optionalRead(() => current.getOwnedResources()), supportsCustomState ? optionalRead(() => current.customState.keys()) : optionalRead(async () => [] as string[]), optionalRead(() => current.getLocale()),
+      ]);
+      const keys = nextKeys.value ?? [];
+      const entryResults = await Promise.all(keys.slice(0, 12).map(async (key) => ({ key, result: await optionalRead(() => current.customState.get(key)) })));
+      const configuredEntries = await Promise.all([...viewConfig.variables.map(async (item) => ({ key: item.label, result: await optionalRead(() => current.getVariable(item.name)) })), ...viewConfig.unlocks.map(async (item) => ({ key: item.label, result: await optionalRead(() => current.getUnlock(item.target, item.id)) }))]);
+      if (stamp !== generation.current) return;
+      if (scenario.value?.title) setTitle(scenario.value.title);
+      const stateResults = [...entryResults, ...configuredEntries]; const assetsError = optionalError(nextAssets); const resourcesError = optionalError(nextResources); const keysError = optionalError(nextKeys); setProgress(typeof nextProgress.value === "number" && Number.isFinite(nextProgress.value) ? Math.max(0, Math.min(1, nextProgress.value)) : null); setAssets(assetsError ? null : nextAssets.value ?? []); setResources(resourcesError ? null : nextResources.value ?? []); setStateKeys(keys); setStateEntries(stateResults.filter((entry) => optionalError(entry.result) === undefined).map((entry) => ({ key: entry.key, value: stateValue(entry.result.value) }))); setStateError(stateResults.some((entry) => optionalError(entry.result) !== undefined) || keysError ? publicError(keysError ?? new Error("state"), "状态暂不可用") ?? null : null); setStateEnabled(supportsCustomState || configuredEntries.length > 0); if (nextLocale.value) setLocale(nextLocale.value); setUnavailable([...new Set([scenario, nextProgress, nextAssets, nextResources, nextKeys, nextLocale].flatMap((item) => { const error = optionalError(item); return error ? [publicError(error, "读取故事信息失败")].filter((value): value is string => value !== null) : []; }))]);
+    } catch (reason) { setError(readableError(reason, "读取故事信息失败")); }
+  }, []);
+
+  const refreshTheme = useCallback(async (current: ChatPlayConversationBridge, payload?: unknown, stamp = generation.current) => {
+    const eventTheme = resolvedThemeFromEvent(payload); if (eventTheme) { themeVersion.current += 1; if (stamp === generation.current) setTheme(eventTheme); return; }
+    const requestVersion = themeVersion.current; try { const next = await readTheme(current); if (stamp === generation.current && requestVersion === themeVersion.current) setTheme(next.resolved); } catch (reason) { if (stamp === generation.current) setError(readableError(reason, "读取主题失败")); }
+  }, []);
+
+  useEffect(() => {
+    const stamp = ++generation.current; let active = true; let stop = () => {};
+    try {
+      const current = requireChatPlay();
+      void current.ready.then(async () => {
+        if (!active) return;
+        setBridge(current); const capabilities = current.context()?.capabilities; setAssetsEnabled(capabilities?.supportsAssets === true);
+        const refreshMessage = () => { void refreshMessages(current, true, stamp); }; const refreshDetail = () => { void refreshDetails(current, stamp); };
+        const messageStops = [current.on("messageAdded", refreshMessage), current.on("messageUpdated", refreshMessage), current.on("streamStart", refreshMessage), current.on("streamDelta", refreshMessage), current.on("streamDone", refreshMessage)]; const streamErrorStop = current.on("streamError", (payload) => { if (isPreviewModelUnavailable(payload)) { setError(null); setActionNotice("视图桥已连接；当前为界面预览，未连接模型。"); } else { const notice = publicError(payload, "生成暂不可用"); if (notice) { setActionNotice(null); setError(notice); } else { setError(null); setActionNotice("当前宿主未开放生成能力。"); } } });
+        const deletedStop = current.on("messageDeleted", (payload) => { const id = messageIdFromEvent(payload); if (id) { deletedIds.current.add(id); setMessages((existing) => applyMessageDeleted({ request: messageRequest.current, deletedIds: deletedIds.current, messages: existing }, id).messages); } void refreshMessages(current, true, stamp); });
+        const detailStops = [current.on("resourceUnlocked", refreshDetail), current.on("stateChanged", refreshDetail), current.on("localeChanged", refreshDetail), current.on("tmwDelivery", refreshDetail)];
+        const themeStop = current.on("themeChanged", (payload) => { void refreshTheme(current, payload, stamp); });
+        await Promise.all([refreshMessages(current, false, stamp), refreshDetails(current, stamp), refreshTheme(current, undefined, stamp)]);
+        const unsubscribe = () => [...messageStops, streamErrorStop, deletedStop, ...detailStops, themeStop].forEach((end) => end());
+        if (active && stamp === generation.current) stop = unsubscribe; else unsubscribe();
+      }).catch((reason) => active && setError(readableError(reason, "ChatPlay SDK 未就绪")));
+    } catch (reason) { setError(readableError(reason, "ChatPlay SDK 不可用")); }
+    return () => { active = false; generation.current += 1; stop(); };
+  }, [refreshDetails, refreshMessages, refreshTheme]);
+  useEffect(() => { const storyDrawer = window.matchMedia("(max-width: 880px)"); const detailsDrawer = window.matchMedia("(max-width: 1080px)"); const activeOverlay = () => mobilePanel === "story" && storyDrawer.matches ? storyRef.current : mobilePanel === "details" && detailsDrawer.matches ? detailsRef.current : null; const main = mainRef.current; const syncDrawer = () => { const overlay = activeOverlay(); if (main) { if (overlay) main.setAttribute("inert", ""); else main.removeAttribute("inert"); } if (overlay) overlay.querySelector<HTMLElement>(".chat-overlay-close")?.focus(); }; const onKeyDown = (event: KeyboardEvent) => { if (event.key === "Escape" && activeOverlay()) setMobilePanel("chat"); }; syncDrawer(); storyDrawer.addEventListener("change", syncDrawer); detailsDrawer.addEventListener("change", syncDrawer); window.addEventListener("keydown", onKeyDown); return () => { storyDrawer.removeEventListener("change", syncDrawer); detailsDrawer.removeEventListener("change", syncDrawer); window.removeEventListener("keydown", onKeyDown); main?.removeAttribute("inert"); }; }, [mobilePanel]);
+
+  const loadEarlier = useCallback(async () => {
+    if (!bridge || messages.length === 0) return;
+    try { const earlier = await loadMessages(bridge, messages[0].id); setMessages((current) => mergeMessages(current, earlier.filter((message) => !deletedIds.current.has(message.id)))); setHasEarlier(earlier.length >= 80); } catch (reason) { setError(readableError(reason, "读取更早消息失败")); }
+  }, [bridge, messages]);
+
+  const submit = useCallback(async () => {
+    if (!bridge || sending || sendInFlight.current || !draft.trim()) return;
+    sendInFlight.current = true; setSending(true);
+    try { await sendMessage(bridge, draft); setDraft(""); await refreshMessages(bridge, false); } catch (reason) { if (isPreviewModelUnavailable(reason)) { setError(null); setActionNotice("视图桥已连接；当前为界面预览，未连接模型。"); } else { setActionNotice(null); setError(publicError(reason, "发送失败，草稿已保留") ?? "发送失败，草稿已保留"); } } finally { sendInFlight.current = false; setSending(false); }
+  }, [bridge, draft, refreshMessages, sending]);
+
+  const resolveAsset = useCallback(async (asset: Asset) => {
+    if (!bridge || assetUrls[asset.id]) return;
+    try { const url = await bridge.getAssetUrl(asset.id); if (!/^(blob:|https?:)/.test(url)) throw new Error("宿主返回了不受信任的资源地址"); setAssetUrls((current) => ({ ...current, [asset.id]: url })); } catch (reason) { setError(readableError(reason, "资源预览不可用")); }
+  }, [assetUrls, bridge]);
+
+  const onSubmit = (event: FormEvent) => { event.preventDefault(); void submit(); };
+  const onKeyDown = (event: ReactKeyboardEvent<HTMLTextAreaElement>) => { if (event.key === "Enter" && !event.shiftKey && !composing) { event.preventDefault(); void submit(); } };
+  const runAction = (action: (typeof viewConfig.actions)[number]) => { if (!bridge) return; try { emitConfiguredAction(bridge, action.eventType, action.payload, crypto.randomUUID()); setError(null); setActionNotice("互动请求已提交，等待故事结果。"); } catch (reason) { setActionNotice(null); setError(readableError(reason, "互动暂不可用")); } };
+  const canRetry = error !== null && !error.startsWith("请先在作者工具登录");
+  return <div className="chat-app" data-theme={theme}>
+    <aside ref={storyRef} role="dialog" aria-modal="true" aria-label="故事信息" className={"chat-sidebar" + (mobilePanel === "story" ? " is-open" : "")}><button className="chat-icon-button chat-overlay-close" type="button" aria-label="关闭故事" onClick={() => setMobilePanel("chat")}>{icon("back")}</button><div className="chat-brand">WorldEngine</div><div className="chat-scene-title">{title}</div>{progress !== null && <div className="chat-progress"><span style={{ width: (progress * 100) + "%" }} />{Math.round(progress * 100)}%</div>}<section className="chat-panel chat-status"><h2>故事状态</h2><p>{bridge ? "视图已连接" : "正在连接…"}</p>{unavailable.map((notice) => <p key={notice}>{notice}</p>)}</section>{resources !== null && resources.length > 0 && <section className="chat-panel chat-resources"><h2>已解锁</h2><ul className="chat-list">{resources.flatMap((group) => group.resources).map((resource) => <li className="chat-list-item" key={resource.uri}>{resource.type}</li>)}</ul></section>}{stateEnabled && <section className="chat-panel"><h2>状态</h2>{stateError ? <p>{stateError}</p> : stateEntries.map((entry) => <p key={entry.key}>{entry.key}：{String(entry.value)}</p>)}</section>}{viewConfig.actions.map((action) => <button key={action.eventType} className="chat-button" type="button" onClick={() => runAction(action)}>{action.label}</button>)}</aside>
+    <main ref={mainRef} className="chat-main"><header className="chat-header"><button className="chat-icon-button" type="button" aria-label="故事信息" onClick={() => setMobilePanel("story")}>{icon("menu")}</button><div className="chat-header-copy"><h1>{title}</h1><p>{bridge ? "当前存档" : "连接中"}</p></div><button className="chat-icon-button" type="button" aria-label="详情" onClick={() => setMobilePanel("details")}>{icon("info")}</button></header>
+      {error && <div className="chat-error" role="alert">{error}{canRetry && <button className="chat-retry" type="button" onClick={() => bridge && void refreshMessages(bridge)}>刷新消息</button>}</div>}{actionNotice && <p className="chat-status" role="status">{actionNotice}</p>}
+      <section className="chat-transcript" ref={transcript} aria-label="对话记录">{hasEarlier && <button className="chat-button chat-retry" type="button" onClick={() => void loadEarlier()}>读取更早消息</button>}{messages.length === 0 ? <div className="chat-empty"><svg className="chat-empty-illustration" viewBox="0 0 24 24" aria-hidden="true"><path d="M5 5h14v10H9l-4 4V5Z" /></svg><h2>对话从这里开始</h2><p>写下你的第一句话，故事会按当前剧本继续。</p></div> : messages.map((message) => <article key={message.id} className="chat-message" data-role={message.role}><p className="chat-message-body">{message.text}</p></article>)}</section>
+      <form className="chat-composer" onSubmit={onSubmit}><textarea className="chat-input" value={draft} onChange={(event) => setDraft(event.target.value)} onCompositionStart={() => setComposing(true)} onCompositionEnd={() => setComposing(false)} onKeyDown={onKeyDown} placeholder="写下你的回复…" aria-label="发送消息" rows={1} disabled={!bridge || sending} /><button className="chat-button" type="button" aria-label="发送消息" onClick={() => { void submit(); }} disabled={!bridge || sending || !draft.trim()}>{sending ? "发送中" : icon("send")}</button></form>
+    </main>
+    <aside ref={detailsRef} role="dialog" aria-modal="true" aria-label="详情" className={"chat-details" + (mobilePanel === "details" ? " is-open" : "")}><button className="chat-icon-button chat-overlay-close" type="button" aria-label="关闭详情" onClick={() => setMobilePanel("chat")}>{icon("back")}</button>{assetsEnabled && <section className="chat-panel"><h2>资源</h2>{assets === null ? <p>资源暂不可用</p> : assets.length ? <ul>{assets.map((asset) => <li className="chat-resource-item" key={asset.id}>{isPreviewable(asset) && <button className="chat-icon-button" type="button" aria-label={"预览 " + asset.filename} onClick={() => void resolveAsset(asset)}>预览</button>}<span>{asset.filename}</span>{assetUrls[asset.id] && (asset.mime.startsWith("image/") ? <img className="chat-asset-preview" src={assetUrls[asset.id]} alt={asset.filename} /> : asset.mime.startsWith("audio/") ? <audio className="chat-asset-preview" controls src={assetUrls[asset.id]} /> : <video className="chat-asset-preview" controls src={assetUrls[asset.id]} />)}</li>)}</ul> : <p className="chat-empty">当前没有可展示资源</p>}</section>}{stateEnabled && <section className="chat-panel"><h2>状态</h2>{stateError ? <p>{stateError}</p> : stateEntries.length ? <ul>{stateEntries.map((entry) => <li key={entry.key}><strong>{entry.key}</strong><span>{typeof entry.value === "string" || typeof entry.value === "number" || typeof entry.value === "boolean" ? String(entry.value) : entry.value === null ? "null" : "已读取"}</span></li>)}</ul> : <p className="chat-empty">没有可读状态</p>}</section>}<details className="chat-panel"><summary>运行信息</summary><p>{bridge ? "Runtime " + bridge.runtimeVersion().major + "." + bridge.runtimeVersion().patch : "不可用"}</p></details></aside>
+    <nav className="chat-mobile-nav" aria-label="视图导航">{(["story", "chat", "details"] as const).map((panel) => <button key={panel} className={"chat-mobile-nav-item" + (mobilePanel === panel ? " is-active" : "")} type="button" onClick={() => setMobilePanel(panel)}>{panel === "story" ? "故事" : panel === "chat" ? "对话" : "详情"}</button>)}</nav>
+  </div>;
+}
+`;

package/dist/default-view/bridge.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_CHAT_BRIDGE: string;

package/dist/default-view/bridge.js

@@ -0,0 +1,112 @@
+export const DEFAULT_CHAT_BRIDGE = String.raw `import type { ChatPlayApi } from "@world-engines/view-sdk";
+
+export type ChatMessage = Awaited<ReturnType<ChatPlayApi["listMessages"]>>[number];
+export type ThemeSnapshot = Awaited<ReturnType<ChatPlayApi["getTheme"]>>;
+export type ChatPlayConversationBridge = Pick<ChatPlayApi, "ready" | "context" | "listMessages" | "sendUserMessage" | "listAssets" | "getAssetUrl" | "loadCustomState" | "listCustomStateKeys" | "customState" | "events" | "getScenarioMeta" | "getProgress" | "getVariable" | "getUnlock" | "getOwnedResources" | "getLocale" | "getTheme" | "runtimeVersion" | "worldline" | "openModelSettings" | "on">;
+
+export function readableError(reason: unknown, fallback: string): string {
+  return typeof reason === "string" ? reason : reason instanceof Error && reason.message ? reason.message : fallback;
+}
+
+function errorCode(reason: unknown): string {
+  const direct = reason && typeof reason === "object" && "code" in reason ? (reason as { code?: unknown }).code : undefined;
+  if (typeof direct === "string" && direct) return direct.toUpperCase();
+  const match = readableError(reason, "").match(/\b(?:E_[A-Z0-9_]+|E[A-Z][A-Z0-9_]*|UNAUTHENTICATED|UNAUTHORIZED)\b/iu);
+  return match ? match[0].toUpperCase() : "";
+}
+
+export function publicError(reason: unknown, fallback: string): string | null {
+  const code = errorCode(reason);
+  if (/^(E_CAPABILITY_UNAVAILABLE|ENOTSUP)$/u.test(code)) return null;
+  if (code === "E_PREVIEW_MODEL_UNAVAILABLE") return "当前预览暂未接入模型，暂时无法继续对话。";
+  if (/^(E_AUTH_REQUIRED|EAUTH|ELOGIN|UNAUTHENTICATED|UNAUTHORIZED)$/u.test(code)) return "请先登录后重试。";
+  if (code === "EPERM") return "当前游戏未开放此功能。";
+  if (code === "EINVAL") return "请求内容无效，请重新操作。";
+  if (/^(MODEL_DOWN|MODEL_UNAVAILABLE|PROVIDER_UNAVAILABLE|E_MODEL_DOWN|E_MODEL_UNAVAILABLE|E_PROVIDER_UNAVAILABLE)$/u.test(code)) return "模型服务暂不可用，请稍后再试。";
+  if (/^(ETIMEDOUT|ETIMEOUT|E_TIMEOUT|ECONNRESET|ECONNREFUSED|ENETUNREACH|E_NETWORK)$/u.test(code)) return "连接暂时不可用，请稍后再试。";
+  return fallback;
+}
+
+export function isPreviewModelUnavailable(reason: unknown): boolean {
+  return Boolean(reason && typeof reason === "object" && "code" in reason && (reason as { code?: unknown }).code === "E_PREVIEW_MODEL_UNAVAILABLE") || /\bE_PREVIEW_MODEL_UNAVAILABLE\b/u.test(readableError(reason, ""));
+}
+
+export function requireChatPlay(): ChatPlayConversationBridge {
+  if (window.ChatPlay === undefined) throw new Error("ChatPlay SDK 未由宿主注入");
+  return window.ChatPlay;
+}
+
+export async function initializeBridge(bridge: ChatPlayConversationBridge): Promise<void> {
+  await bridge.ready;
+}
+
+export async function loadMessages(bridge: ChatPlayConversationBridge, before?: string): Promise<readonly ChatMessage[]> {
+  await initializeBridge(bridge);
+  const messages = await bridge.listMessages(before === undefined ? { limit: 80 } : { before, limit: 80 });
+  return [...messages].sort((left, right) => left.ts - right.ts || left.id.localeCompare(right.id));
+}
+
+export function mergeMessages(current: readonly ChatMessage[], incoming: readonly ChatMessage[]): readonly ChatMessage[] {
+  return [...new Map([...current, ...incoming].map((message) => [message.id, message])).values()]
+    .sort((left, right) => left.ts - right.ts || left.id.localeCompare(right.id));
+}
+
+export interface MessageSnapshot {
+  readonly request: number;
+  readonly deletedIds: ReadonlySet<string>;
+  readonly messages: readonly ChatMessage[];
+}
+
+export function applyMessagePage(previous: MessageSnapshot, request: number, incoming: readonly ChatMessage[]): MessageSnapshot {
+  if (request < previous.request) return previous;
+  const messages = mergeMessages(previous.messages, incoming.filter((message) => !previous.deletedIds.has(message.id)));
+  return { ...previous, request, messages };
+}
+
+export function applyMessageDeleted(previous: MessageSnapshot, id: string): MessageSnapshot {
+  const deletedIds = new Set(previous.deletedIds); deletedIds.add(id);
+  return { ...previous, deletedIds, messages: previous.messages.filter((message) => message.id !== id) };
+}
+
+export function messageIdFromEvent(payload: unknown): string | null {
+  if (!payload || typeof payload !== "object") return null;
+  const id = (payload as { id?: unknown; messageId?: unknown }).id ?? (payload as { messageId?: unknown }).messageId;
+  return typeof id === "string" && id.length > 0 ? id : null;
+}
+
+export function resolvedThemeFromEvent(payload: unknown): "light" | "dark" | null {
+  if (!payload || typeof payload !== "object") return null;
+  const resolved = (payload as { resolved?: unknown }).resolved;
+  return resolved === "light" || resolved === "dark" ? resolved : null;
+}
+
+export function emitConfiguredAction(bridge: ChatPlayConversationBridge, eventType: string, payload: Readonly<Record<string, null | boolean | number | string>>, interactionId: string) {
+  return bridge.events.emit(eventType, payload, interactionId);
+}
+
+export async function sendMessage(bridge: ChatPlayConversationBridge, text: string): Promise<void> {
+  const trimmed = text.trim();
+  if (!trimmed) return;
+  await initializeBridge(bridge);
+  await bridge.sendUserMessage(trimmed);
+}
+
+export async function readTheme(bridge: ChatPlayConversationBridge): Promise<ThemeSnapshot> {
+  await initializeBridge(bridge);
+  return bridge.getTheme();
+}
+
+export async function optionalRead<T>(work: () => Promise<T>): Promise<{ value?: T; error?: string }> {
+  try { return { value: await work() }; }
+  catch (reason) { return { error: readableError(reason, "此信息暂不可用") }; }
+}
+
+export async function subscribeToChanges(bridge: ChatPlayConversationBridge, refresh: () => void, refreshTheme: () => void): Promise<() => void> {
+  await initializeBridge(bridge);
+  const subscribe = bridge.on as unknown as (event: string, listener: () => void) => () => void;
+  const stops = ["messageAdded", "messageUpdated", "messageDeleted", "streamStart", "streamDelta", "streamDone", "streamError", "resourceUnlocked", "stateChanged", "tmwDelivery"]
+    .map((event) => subscribe(event, refresh));
+  stops.push(bridge.on("themeChanged", refreshTheme), bridge.on("localeChanged", refresh));
+  return () => stops.forEach((stop) => stop());
+}
+`;

package/dist/default-view/config.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_CHAT_VIEW_CONFIG: string;

package/dist/default-view/config.js

@@ -0,0 +1,8 @@
+export const DEFAULT_CHAT_VIEW_CONFIG = String.raw `/** 只有明确列出的数据才会读取；actions 必须在当前作者 manifest 声明。
+ * 可选、可执行的互动/状态示范在 examples/interaction-demo/，默认空白项目不自动启用。 */
+export const viewConfig = {
+  variables: [] as readonly { name: string; label: string }[],
+  unlocks: [] as readonly { target: "node" | "edge"; id: string; label: string }[],
+  actions: [] as readonly { eventType: string; label: string; payload: Readonly<Record<string, null | boolean | number | string>> }[],
+};
+`;

package/dist/default-view/interaction-demo.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 这是独立 opt-in 示例，不进入空白项目的运行路径。它只操作显式指定、仍为空白的项目。
+ */
+export declare const INTERACTION_DEMO_CONFIG: string;
+export declare const INTERACTION_DEMO_INSTALLER: string;
+export declare const INTERACTION_DEMO_README: string;