@actalk/inkos-studio 1.5.0 → 1.6.1-canary.49.1

package/dist/api/server.js

@@ -2,9 +2,10 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { streamSSE } from "hono/streaming";
 import { serve } from "@hono/node-server";
-import { StateManager, PipelineRunner, createLLMClient, createLogger, createInteractionToolsFromDeps, computeAnalytics, loadProjectConfig, loadProjectSession, processProjectInteractionRequest, resolveSessionActiveBook, listBookSessions, loadBookSession, appendManualSessionMessages, createAndPersistBookSession, renameBookSession, deleteBookSession, migrateBookSession, SessionAlreadyMigratedError, runAgentSession, resolveServicePreset, resolveServiceProviderFamily, resolveServiceModelsBaseUrl, guessServiceFromBaseUrl, resolveServiceModel, loadSecrets, saveSecrets, listModelsForService, isApiKeyOptionalForEndpoint, getAllEndpoints, probeModelsFromUpstream, fetchWithProxy, chatCompletion, buildExportArtifact, evaluateBookQuality, ConsolidatorAgent, DetectionConfigSchema, InputGovernanceModeSchema, GLOBAL_ENV_PATH, COVER_PROVIDER_PRESETS, createPlayDB, PlayStore, buildPlayEntityImagePrompt, buildPlaySceneImagePrompt, generatePlayImage, readPlayImageManifest, readPlayImageSettings, writePlayImageSettings, Scheduler, coverSecretKey, resolveCoverProviderPreset, SessionKindSchema, isExplicitWriteChapterCommand, isUsablePlayInitialScene, isWriteNextInstruction, normalizeActionSource as normalizeCoreActionSource, normalizeActionPayload as normalizeCoreActionPayload, normalizePlayMode as normalizeCorePlayMode, normalizeRequestedIntent as normalizeCoreRequestedIntent, inferLanguage, createGenerateCoverTool, createPlayStartTool, createShortFictionRunTool, createSubAgentTool, } from "@actalk/inkos-core";
-import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { gzipSync } from "node:zlib";
+import { StateManager, PipelineRunner, createLLMClient, createLogger, createInteractionToolsFromDeps, computeAnalytics, loadProjectConfig, loadProjectSession, processProjectInteractionRequest, resolveSessionActiveBook, listBookSessions, loadBookSession, appendManualSessionMessages, createAndPersistBookSession, renameBookSession, deleteBookSession, migrateBookSession, SessionAlreadyMigratedError, runAgentSession, resolveServicePreset, resolveServiceProviderFamily, resolveServiceModelsBaseUrl, guessServiceFromBaseUrl, resolveServiceModel, loadSecrets, saveSecrets, listModelsForService, isApiKeyOptionalForEndpoint, getAllEndpoints, probeModelsFromUpstream, fetchWithProxy, chatCompletion, buildExportArtifact, evaluateBookQuality, ConsolidatorAgent, DetectionConfigSchema, ResearchSearchConfigSchema, InputGovernanceModeSchema, GLOBAL_ENV_PATH, COVER_PROVIDER_PRESETS, createPlayDB, PlayStore, buildPlayEntityImagePrompt, buildPlaySceneImagePrompt, generatePlayImage, readPlayImageManifest, readPlayImageSettings, writePlayImageSettings, Scheduler, coverSecretKey, resolveCoverProviderPreset, SessionKindSchema, isExplicitWriteChapterCommand, isUsablePlayInitialScene, isWriteNextInstruction, normalizeActionSource as normalizeCoreActionSource, normalizeActionPayload as normalizeCoreActionPayload, normalizePlayMode as normalizeCorePlayMode, normalizeRequestedIntent as normalizeCoreRequestedIntent, normalizeSkillIdList as normalizeCoreSkillIdList, inferLanguage, createSkillRegistry, loadConfiguredCapabilitySkills, CapabilitySkillManifestSchema, createGenerateCoverTool, createInteractiveFilmCreationTool, createPlayStartTool, createScriptCreationTool, createShortFictionRunTool, createStoryboardCreationTool, createSubAgentTool, createDraftStructureTool, createConnectChoiceTool, createRemoveNodeTool, filmLLMDepsFromClient, applyGraphDelta, loadStoryGraph, reviewStoryGraph, exportInk, buildPlayableHtml, analyzeEmotionalArcs, analyzePathDistribution, generateNodeImage, defaultNodeImageDeps, } from "@actalk/inkos-core";
+import { access, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { isSafeBookId } from "./safety.js";
 import { ApiError } from "./errors.js";
 import { buildStudioBookConfig } from "./book-create.js";
@@ -25,6 +26,10 @@ const PIPELINE_STAGES = {
     ],
     auditor: ["审计章节"],
 };
+function attachmentDisposition(fileName) {
+    const safeAscii = fileName.replace(/[^A-Za-z0-9._-]+/g, "_") || "download";
+    return `attachment; filename="${safeAscii}"; filename*=UTF-8''${encodeURIComponent(fileName)}`;
+}
 const AGENT_LABELS = {
     architect: "建书", writer: "写作", auditor: "审计",
     reviser: "修订", exporter: "导出",
@@ -33,6 +38,9 @@ const TOOL_LABELS = {
     read: "读取文件", edit: "编辑文件", grep: "搜索", ls: "列目录",
     propose_action: "确认动作",
     short_fiction_run: "短篇生产",
+    script_create: "剧本创作",
+    storyboard_create: "分镜创作",
+    interactive_film_create: "互动影游",
     generate_cover: "生成封面",
     play_edit: "编辑互动世界",
     play_start: "启动互动世界",
@@ -46,15 +54,15 @@ function resolveToolLabel(tool, agent) {
 }
 function summarizeResult(result) {
     if (typeof result === "string")
-        return result.slice(0, 200);
+        return result.slice(0, 2000);
     if (result && typeof result === "object") {
         const r = result;
         if (typeof r.content === "string")
-            return r.content.slice(0, 200);
+            return r.content.slice(0, 2000);
         if (typeof r.text === "string")
-            return r.text.slice(0, 200);
+            return r.text.slice(0, 2000);
     }
-    return String(result).slice(0, 200);
+    return String(result).slice(0, 2000);
 }
 function compareServiceListItems(left, right) {
     const priority = ["kkaiapi", "openrouter", "newapi", "siliconcloud"];
@@ -65,6 +73,76 @@ function compareServiceListItems(left, right) {
     }
     return 0;
 }
+async function buildTarArchive(sourceDir, packageRootName) {
+    const files = await listArchiveFiles(sourceDir);
+    const chunks = [];
+    for (const file of files) {
+        const payload = await readFile(join(sourceDir, file));
+        const archiveName = normalizeArchivePath(join(packageRootName, file));
+        chunks.push(createTarHeader(archiveName, payload.byteLength));
+        chunks.push(payload);
+        const padding = (512 - (payload.byteLength % 512)) % 512;
+        if (padding > 0)
+            chunks.push(Buffer.alloc(padding));
+    }
+    chunks.push(Buffer.alloc(1024));
+    return Buffer.concat(chunks);
+}
+async function listArchiveFiles(dir, prefix = "") {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (entry.name === ".DS_Store")
+            continue;
+        const relativePath = prefix ? join(prefix, entry.name) : entry.name;
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await listArchiveFiles(fullPath, relativePath));
+        }
+        else if (entry.isFile()) {
+            files.push(normalizeArchivePath(relativePath));
+        }
+        else {
+            const info = await stat(fullPath).catch(() => null);
+            if (info?.isFile())
+                files.push(normalizeArchivePath(relativePath));
+        }
+    }
+    return files.sort((a, b) => a.localeCompare(b));
+}
+function normalizeArchivePath(path) {
+    return path.replace(/\\/g, "/").replace(/^\/+/g, "");
+}
+function createTarHeader(name, size) {
+    const header = Buffer.alloc(512, 0);
+    writeTarString(header, 0, 100, name);
+    writeTarOctal(header, 100, 8, 0o644);
+    writeTarOctal(header, 108, 8, 0);
+    writeTarOctal(header, 116, 8, 0);
+    writeTarOctal(header, 124, 12, size);
+    writeTarOctal(header, 136, 12, Math.floor(Date.now() / 1000));
+    header.fill(0x20, 148, 156);
+    header[156] = "0".charCodeAt(0);
+    writeTarString(header, 257, 6, "ustar");
+    writeTarString(header, 263, 2, "00");
+    let checksum = 0;
+    for (const byte of header)
+        checksum += byte;
+    writeTarOctal(header, 148, 8, checksum);
+    return header;
+}
+function writeTarString(header, offset, length, value) {
+    const encoded = Buffer.from(value);
+    if (encoded.byteLength > length) {
+        throw new Error(`Archive path is too long for tar header: ${value}`);
+    }
+    encoded.copy(header, offset);
+}
+function writeTarOctal(header, offset, length, value) {
+    const text = value.toString(8).padStart(length - 1, "0").slice(-(length - 1));
+    header.write(text, offset, length - 1, "ascii");
+    header[offset + length - 1] = 0;
+}
 function isHeaderSafeApiKey(value) {
     if (!value)
         return true;
@@ -143,8 +221,8 @@ function resolveProjectImageFile(root, rawPath) {
         || relPath.split(/[\\/]+/u).includes("..")) {
         throw new ApiError(400, "INVALID_PROJECT_FILE_PATH", "Invalid project file path");
     }
-    if (!relPath.startsWith("shorts/") && !relPath.startsWith("covers/")) {
-        throw new ApiError(400, "INVALID_PROJECT_FILE_PATH", "Only generated shorts/ and covers/ images can be previewed");
+    if (!relPath.startsWith("shorts/") && !relPath.startsWith("covers/") && !relPath.startsWith("interactive-films/")) {
+        throw new ApiError(400, "INVALID_PROJECT_FILE_PATH", "Only generated shorts/, covers/, interactive-films/ images can be previewed");
     }
     const ext = relPath.split(".").pop()?.toLowerCase() ?? "";
     const contentTypes = {
@@ -164,6 +242,46 @@ function resolveProjectImageFile(root, rawPath) {
     }
     return { resolved, contentType };
 }
+function normalizeProjectGeneratedPath(root, rawPath, code) {
+    let relPath;
+    try {
+        relPath = decodeURIComponent(rawPath).replace(/^\/+/u, "");
+    }
+    catch {
+        throw new ApiError(400, code, "Invalid project artifact path");
+    }
+    if (!relPath
+        || relPath.includes("\0")
+        || isAbsolute(relPath)
+        || relPath.split(/[\\/]+/u).includes("..")) {
+        throw new ApiError(400, code, "Invalid project artifact path");
+    }
+    const allowedRoots = ["dramas/", "storyboards/", "interactive-films/", "shorts/", "covers/"];
+    if (!allowedRoots.some((prefix) => relPath.startsWith(prefix))) {
+        throw new ApiError(400, code, "Only generated writing artifacts can be opened");
+    }
+    const resolved = resolve(root, relPath);
+    const rel = relative(root, resolved);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new ApiError(400, code, "Invalid project artifact path");
+    }
+    return { relPath, resolved };
+}
+function resolveProjectTextArtifactFile(root, rawPath) {
+    const file = normalizeProjectGeneratedPath(root, rawPath, "INVALID_PROJECT_ARTIFACT_PATH");
+    const ext = file.relPath.split(".").pop()?.toLowerCase() ?? "";
+    const contentTypes = {
+        md: "text/markdown; charset=utf-8",
+        markdown: "text/markdown; charset=utf-8",
+        txt: "text/plain; charset=utf-8",
+        json: "application/json; charset=utf-8",
+    };
+    const contentType = contentTypes[ext];
+    if (!contentType) {
+        throw new ApiError(415, "UNSUPPORTED_PROJECT_ARTIFACT_TYPE", "Unsupported project artifact type");
+    }
+    return { ...file, contentType };
+}
 function isLikelyFailedToolResult(exec) {
     if (exec.status === "error")
         return true;
@@ -218,6 +336,138 @@ function normalizeStudioActionPayload(value) {
         throw new ApiError(400, "INVALID_ACTION_PAYLOAD", `Invalid actionPayload: ${message}`);
     }
 }
+function normalizeStudioSkillIdList(value, field) {
+    try {
+        return normalizeCoreSkillIdList(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ApiError(400, "INVALID_SKILL_ID", `Invalid ${field}: ${message}`);
+    }
+}
+function normalizeStudioSkillId(value, field = "skillId") {
+    const [id] = normalizeStudioSkillIdList([value], field);
+    if (!id)
+        throw new ApiError(400, "INVALID_SKILL_ID", `Invalid ${field}: empty`);
+    return id;
+}
+function projectSkillsDir(root) {
+    return join(root, ".inkos", "skills");
+}
+function projectSkillDir(root, id) {
+    return join(projectSkillsDir(root), id);
+}
+function projectSkillPath(root, id) {
+    return join(projectSkillDir(root, id), "SKILL.md");
+}
+function toStudioSkill(skill, root, projectSkillIds) {
+    const projectPath = projectSkillPath(root, skill.id);
+    const isProjectFile = projectSkillIds.has(skill.id);
+    return {
+        id: skill.id,
+        name: skill.name,
+        description: skill.description,
+        whenToUse: skill.whenToUse,
+        triggers: skill.triggers,
+        sessionKinds: skill.sessionKinds,
+        promptPacks: skill.promptPacks,
+        toolHints: skill.toolHints,
+        contextNeeds: skill.contextNeeds,
+        body: skill.body,
+        source: isProjectFile ? "project" : skill.source,
+        editable: isProjectFile,
+        path: isProjectFile ? relative(root, projectPath) : undefined,
+    };
+}
+function normalizeSkillPayload(value, idOverride) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ApiError(400, "INVALID_SKILL_PAYLOAD", "Skill payload must be an object");
+    }
+    const data = value;
+    const id = normalizeStudioSkillId(idOverride ?? data.id, "id");
+    const textOr = (field, fallback) => {
+        const raw = data[field];
+        return typeof raw === "string" && raw.trim() ? raw.trim() : fallback;
+    };
+    const stringList = (field) => (Array.isArray(data[field])
+        ? data[field]
+            .filter((item) => typeof item === "string" && item.trim().length > 0)
+            .map((item) => item.trim())
+        : []);
+    try {
+        return CapabilitySkillManifestSchema.parse({
+            id,
+            name: textOr("name", id),
+            description: textOr("description", "Project runtime skill."),
+            whenToUse: textOr("whenToUse", "Use when explicitly selected by the user."),
+            triggers: stringList("triggers"),
+            sessionKinds: stringList("sessionKinds"),
+            promptPacks: stringList("promptPacks"),
+            toolHints: stringList("toolHints"),
+            contextNeeds: Array.isArray(data.contextNeeds) ? data.contextNeeds : [],
+            body: typeof data.body === "string" ? data.body : "",
+            source: "project",
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ApiError(400, "INVALID_SKILL_PAYLOAD", message);
+    }
+}
+function serializeProjectSkill(skill) {
+    const frontmatter = {
+        id: skill.id,
+        name: skill.name,
+        description: skill.description,
+        whenToUse: skill.whenToUse,
+        triggers: skill.triggers,
+        sessionKinds: skill.sessionKinds,
+        promptPacks: skill.promptPacks,
+        toolHints: skill.toolHints,
+        contextNeeds: skill.contextNeeds,
+    };
+    return [
+        "---",
+        ...Object.entries(frontmatter).map(([key, value]) => `${key}: ${JSON.stringify(value)}`),
+        "---",
+        skill.body.trim(),
+        "",
+    ].join("\n");
+}
+async function loadStudioSkills(root) {
+    const configured = await loadConfiguredCapabilitySkills({ projectRoot: root });
+    const projectSkillIds = await listProjectSkillIds(root);
+    const registry = createSkillRegistry({ skills: configured.skills });
+    return {
+        skills: registry.listSkills().map((skill) => toStudioSkill(skill, root, projectSkillIds)),
+        diagnostics: configured.diagnostics,
+    };
+}
+async function listProjectSkillIds(root) {
+    try {
+        const entries = await readdir(projectSkillsDir(root), { withFileTypes: true });
+        const ids = new Set();
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const id = normalizeStudioSkillId(entry.name, "skillId");
+            try {
+                const info = await stat(projectSkillPath(root, id));
+                if (info.isFile())
+                    ids.add(id);
+            }
+            catch {
+                // Ignore incomplete project skill directories.
+            }
+        }
+        return ids;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return new Set();
+        throw error;
+    }
+}
 function normalizeStudioPlayMode(value) {
     try {
         return normalizeCorePlayMode(value);
@@ -478,7 +728,12 @@ class ConfirmedActionExecutionError extends Error {
     }
 }
 function suppressManualTextForTool(exec) {
-    return exec.tool === "play_start" || exec.tool === "play_step" || exec.tool === "play_revise";
+    return exec.tool === "play_start"
+        || exec.tool === "play_step"
+        || exec.tool === "play_revise"
+        || exec.tool === "script_create"
+        || exec.tool === "storyboard_create"
+        || exec.tool === "interactive_film_create";
 }
 function manualToolAssistantMessage(responseText, exec, provider, model) {
     return {
@@ -509,8 +764,14 @@ function isConfirmedProductionAction(args) {
     return (args.actionSource === "button" || args.actionSource === "slash")
         && (args.requestedIntent === "create_book"
             || args.requestedIntent === "short_run"
+            || args.requestedIntent === "script_create"
+            || args.requestedIntent === "storyboard_create"
+            || args.requestedIntent === "interactive_film_create"
             || args.requestedIntent === "play_start"
-            || args.requestedIntent === "generate_cover");
+            || args.requestedIntent === "generate_cover"
+            || args.requestedIntent === "draft_structure"
+            || args.requestedIntent === "connect_choice"
+            || args.requestedIntent === "remove_node");
 }
 function requirePayloadText(value, message) {
     const text = value?.trim();
@@ -572,6 +833,63 @@ async function executeConfirmedProductionAction(args) {
             ...(payload?.outputDir ? { outputDir: payload.outputDir } : {}),
         };
     }
+    else if (args.requestedIntent === "script_create") {
+        const payload = actionPayload?.scriptCreate;
+        const title = requirePayloadText(payload?.title, "确认创建剧本缺少标题，请重新生成确认卡。");
+        tool = createScriptCreationTool(args.pipeline, args.root, { actionPayload });
+        params = {
+            title,
+            instruction: args.instruction,
+            ...(payload?.sourceKind ? { sourceKind: payload.sourceKind } : {}),
+            ...(payload?.targetFormat ? { targetFormat: payload.targetFormat } : {}),
+            ...(payload?.sourceText ? { sourceText: payload.sourceText } : {}),
+            ...(payload?.sourcePath ? { sourcePath: payload.sourcePath } : {}),
+            ...(payload?.requirements ? { requirements: payload.requirements } : {}),
+            ...(payload?.episodeCount ? { episodeCount: payload.episodeCount } : {}),
+            ...(payload?.episodeDuration ? { episodeDuration: payload.episodeDuration } : {}),
+            ...(payload?.projectId ? { projectId: payload.projectId } : {}),
+            ...(payload?.outDir ? { outDir: payload.outDir } : {}),
+        };
+    }
+    else if (args.requestedIntent === "storyboard_create") {
+        const payload = actionPayload?.storyboardCreate;
+        const title = requirePayloadText(payload?.title, "确认创建分镜缺少标题，请重新生成确认卡。");
+        tool = createStoryboardCreationTool(args.pipeline, args.root, { actionPayload });
+        params = {
+            title,
+            instruction: args.instruction,
+            ...(payload?.sourceKind ? { sourceKind: payload.sourceKind } : {}),
+            ...(payload?.sourceText ? { sourceText: payload.sourceText } : {}),
+            ...(payload?.sourcePath ? { sourcePath: payload.sourcePath } : {}),
+            ...(payload?.requirements ? { requirements: payload.requirements } : {}),
+            ...(payload?.visualStyle ? { visualStyle: payload.visualStyle } : {}),
+            ...(payload?.aspectRatio ? { aspectRatio: payload.aspectRatio } : {}),
+            ...(payload?.granularity ? { granularity: payload.granularity } : {}),
+            ...(payload?.maxShots ? { maxShots: payload.maxShots } : {}),
+            ...(payload?.projectId ? { projectId: payload.projectId } : {}),
+            ...(payload?.outDir ? { outDir: payload.outDir } : {}),
+        };
+    }
+    else if (args.requestedIntent === "interactive_film_create") {
+        const payload = actionPayload?.interactiveFilmCreate;
+        const title = requirePayloadText(payload?.title, "确认创建互动影游缺少标题，请重新生成确认卡。");
+        tool = createInteractiveFilmCreationTool(args.pipeline, args.root, { actionPayload });
+        params = {
+            title,
+            instruction: args.instruction,
+            ...(payload?.sourceKind ? { sourceKind: payload.sourceKind } : {}),
+            ...(payload?.sourceText ? { sourceText: payload.sourceText } : {}),
+            ...(payload?.sourcePath ? { sourcePath: payload.sourcePath } : {}),
+            ...(payload?.requirements ? { requirements: payload.requirements } : {}),
+            ...(payload?.targetAudience ? { targetAudience: payload.targetAudience } : {}),
+            ...(payload?.episodeCount ? { episodeCount: payload.episodeCount } : {}),
+            ...(payload?.episodeDuration ? { episodeDuration: payload.episodeDuration } : {}),
+            ...(payload?.budget ? { budget: payload.budget } : {}),
+            ...(payload?.referenceMode ? { referenceMode: payload.referenceMode } : {}),
+            ...(payload?.projectId ? { projectId: payload.projectId } : {}),
+            ...(payload?.outDir ? { outDir: payload.outDir } : {}),
+        };
+    }
     else if (args.requestedIntent === "play_start") {
         const payload = actionPayload?.playStart;
         const title = requirePayloadText(payload?.title, "确认启动互动世界缺少标题，请重新生成确认卡。");
@@ -600,6 +918,44 @@ async function executeConfirmedProductionAction(args) {
             ...(payload?.suggestedActions ? { suggestedActions: payload.suggestedActions } : {}),
         };
     }
+    else if (args.requestedIntent === "draft_structure") {
+        const payload = actionPayload?.draftStructure;
+        const projectId = payload?.projectId ?? args.bookId;
+        if (!projectId)
+            throw new ApiError(400, "INVALID_ID", "interactive-film action requires a project id (bookId)");
+        const agentCtx = args.pipeline.createAgentContext("film-authoring", projectId);
+        const deps = filmLLMDepsFromClient(agentCtx.client, agentCtx.model);
+        tool = createDraftStructureTool(args.root, projectId, deps);
+        params = {
+            instruction: payload?.instruction?.trim() || args.instruction,
+        };
+    }
+    else if (args.requestedIntent === "connect_choice") {
+        const payload = actionPayload?.connectChoice;
+        if (!payload?.node) {
+            throw new ApiError(400, "CONFIRMED_ACTION_PAYLOAD_INCOMPLETE", "确认连接选择缺少节点数据，请重新生成确认卡。");
+        }
+        const projectId = payload?.projectId ?? args.bookId;
+        if (!projectId)
+            throw new ApiError(400, "INVALID_ID", "interactive-film action requires a project id (bookId)");
+        tool = createConnectChoiceTool(args.root, projectId);
+        params = {
+            node: payload.node,
+        };
+    }
+    else if (args.requestedIntent === "remove_node") {
+        const payload = actionPayload?.removeNode;
+        if (!payload?.nodeId) {
+            throw new ApiError(400, "CONFIRMED_ACTION_PAYLOAD_INCOMPLETE", "确认删除节点缺少 nodeId，请重新生成确认卡。");
+        }
+        const projectId = payload?.projectId ?? args.bookId;
+        if (!projectId)
+            throw new ApiError(400, "INVALID_ID", "interactive-film action requires a project id (bookId)");
+        tool = createRemoveNodeTool(args.root, projectId);
+        params = {
+            nodeId: payload.nodeId,
+        };
+    }
     else {
         throw new ApiError(400, "UNSUPPORTED_CONFIRMED_ACTION", `Unsupported confirmed action: ${args.requestedIntent}`);
     }
@@ -828,6 +1184,38 @@ async function loadRawConfig(root) {
 async function saveRawConfig(root, config) {
     await writeFile(join(root, "inkos.json"), JSON.stringify(config, null, 2), "utf-8");
 }
+function normalizeChapterReviewMode(mode) {
+    return mode === "manual" ? "manual" : "auto";
+}
+function readProjectChapterReviewMode(config) {
+    const writing = config.writing && typeof config.writing === "object" && !Array.isArray(config.writing)
+        ? config.writing
+        : {};
+    return normalizeChapterReviewMode(writing.reviewMode);
+}
+function readBookChapterReviewMode(rawBook) {
+    const writing = rawBook.writing && typeof rawBook.writing === "object" && !Array.isArray(rawBook.writing)
+        ? rawBook.writing
+        : undefined;
+    if (!writing || writing.reviewMode !== "manual" && writing.reviewMode !== "auto")
+        return undefined;
+    return writing.reviewMode;
+}
+async function loadRawBookConfig(root, bookId) {
+    const raw = await readFile(join(root, "books", bookId, "book.json"), "utf-8");
+    return JSON.parse(raw);
+}
+async function resolveBookChapterReviewMode(root, bookId, projectMode) {
+    if (!bookId || !isSafeBookId(bookId))
+        return projectMode;
+    try {
+        const rawBook = await loadRawBookConfig(root, bookId);
+        return readBookChapterReviewMode(rawBook) ?? projectMode;
+    }
+    catch {
+        return projectMode;
+    }
+}
 function unquoteEnvValue(value) {
     const trimmed = value.trim();
     if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
@@ -1295,7 +1683,7 @@ async function probeServiceCapabilities(args) {
     };
 }
 // --- Server factory ---
-export function createStudioServer(initialConfig, root) {
+export function createStudioServer(initialConfig, root, overrides = {}) {
     const app = new Hono();
     const state = new StateManager(root);
     let cachedConfig = initialConfig;
@@ -1352,6 +1740,8 @@ export function createStudioServer(initialConfig, root) {
     }
     async function buildPipelineConfig(overrides) {
         const currentConfig = overrides?.currentConfig ?? await loadCurrentProjectConfig();
+        const projectReviewMode = readProjectChapterReviewMode(currentConfig);
+        const chapterReviewMode = await resolveBookChapterReviewMode(root, overrides?.bookIdForSettings, projectReviewMode);
         const scopedSseSink = overrides?.sessionIdForSSE
             ? {
                 write(entry) {
@@ -1372,7 +1762,7 @@ export function createStudioServer(initialConfig, root) {
             defaultLLMConfig: currentConfig.llm,
             foundationReviewRetries: currentConfig.foundation?.reviewRetries ?? 2,
             writingReviewRetries: currentConfig.writing?.reviewRetries ?? 1,
-            chapterReviewMode: currentConfig.writing?.reviewMode === "manual" ? "manual" : "auto",
+            chapterReviewMode,
             modelOverrides: currentConfig.modelOverrides,
             notifyChannels: currentConfig.notify,
             logger,
@@ -1671,7 +2061,7 @@ export function createStudioServer(initialConfig, root) {
         const body = await c.req.json().catch(() => ({ wordCount: undefined }));
         broadcast("write:start", { bookId: id });
         // Fire and forget — progress/completion/errors pushed via SSE
-        const pipeline = new PipelineRunner(await buildPipelineConfig());
+        const pipeline = new PipelineRunner(await buildPipelineConfig({ bookIdForSettings: id }));
         pipeline.writeNextChapter(id, body.wordCount).then((result) => {
             broadcast("write:complete", { bookId: id, chapterNumber: result.chapterNumber, status: result.status, title: result.title, wordCount: result.wordCount });
         }, (e) => {
@@ -2197,9 +2587,16 @@ export function createStudioServer(initialConfig, root) {
     });
     // --- Project info ---
     app.get("/api/v1/project", async (c) => {
-        const currentConfig = await loadCurrentProjectConfig({ requireApiKey: false });
-        // Check if language was explicitly set in inkos.json (not just the schema default)
-        const raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
+        let currentConfig;
+        let raw;
+        try {
+            currentConfig = await loadCurrentProjectConfig({ requireApiKey: false });
+            // Check if language was explicitly set in inkos.json (not just the schema default)
+            raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
+        }
+        catch (error) {
+            throw new ApiError(500, "PROJECT_CONFIG_INVALID", `Failed to load inkos.json: ${error instanceof Error ? error.message : String(error)}`);
+        }
         const languageExplicit = "language" in raw && raw.language !== "";
         return c.json({
             name: currentConfig.name,
@@ -2212,6 +2609,40 @@ export function createStudioServer(initialConfig, root) {
             temperature: currentConfig.llm.temperature,
         });
     });
+    app.get("/api/v1/skills", async (c) => {
+        const result = await loadStudioSkills(root);
+        return c.json(result);
+    });
+    app.post("/api/v1/skills", async (c) => {
+        const payload = await c.req.json().catch(() => {
+            throw new ApiError(400, "INVALID_SKILL_PAYLOAD", "Skill payload must be JSON");
+        });
+        const skill = normalizeSkillPayload(payload);
+        await mkdir(projectSkillDir(root, skill.id), { recursive: true });
+        await writeFile(projectSkillPath(root, skill.id), serializeProjectSkill(skill), "utf-8");
+        return c.json({ skill: toStudioSkill(skill, root, new Set([skill.id])) });
+    });
+    app.put("/api/v1/skills/:skillId", async (c) => {
+        const id = normalizeStudioSkillId(c.req.param("skillId"), "skillId");
+        const payload = await c.req.json().catch(() => {
+            throw new ApiError(400, "INVALID_SKILL_PAYLOAD", "Skill payload must be JSON");
+        });
+        const skill = normalizeSkillPayload(payload, id);
+        await mkdir(projectSkillDir(root, skill.id), { recursive: true });
+        await writeFile(projectSkillPath(root, skill.id), serializeProjectSkill(skill), "utf-8");
+        return c.json({ skill: toStudioSkill(skill, root, new Set([skill.id])) });
+    });
+    app.delete("/api/v1/skills/:skillId", async (c) => {
+        const id = normalizeStudioSkillId(c.req.param("skillId"), "skillId");
+        try {
+            await access(projectSkillPath(root, id));
+        }
+        catch {
+            throw new ApiError(404, "SKILL_NOT_FOUND", `Project skill not found: ${id}`);
+        }
+        await rm(projectSkillDir(root, id), { recursive: true, force: true });
+        return c.json({ ok: true });
+    });
     app.get("/api/v1/project/files/:file{.+}", async (c) => {
         const file = resolveProjectImageFile(root, c.req.param("file"));
         try {
@@ -2227,6 +2658,39 @@ export function createStudioServer(initialConfig, root) {
             return c.notFound();
         }
     });
+    app.get("/api/v1/project/artifacts/:file{.+}", async (c) => {
+        const file = resolveProjectTextArtifactFile(root, c.req.param("file"));
+        try {
+            const content = await readFile(file.resolved, "utf-8");
+            return c.json({
+                path: file.relPath,
+                content,
+                contentType: file.contentType,
+                size: Buffer.byteLength(content, "utf-8"),
+            });
+        }
+        catch {
+            return c.notFound();
+        }
+    });
+    app.put("/api/v1/project/artifacts/:file{.+}", async (c) => {
+        const file = resolveProjectTextArtifactFile(root, c.req.param("file"));
+        const body = await c.req.json().catch(() => null);
+        const content = body && typeof body === "object" && "content" in body
+            ? body.content
+            : undefined;
+        if (typeof content !== "string") {
+            throw new ApiError(400, "INVALID_PROJECT_ARTIFACT_BODY", "content must be a string");
+        }
+        await mkdir(dirname(file.resolved), { recursive: true });
+        await writeFile(file.resolved, content, "utf-8");
+        return c.json({
+            ok: true,
+            path: file.relPath,
+            contentType: file.contentType,
+            size: Buffer.byteLength(content, "utf-8"),
+        });
+    });
     // --- Config editing ---
     app.put("/api/v1/project", async (c) => {
         const updates = await c.req.json();
@@ -2630,7 +3094,7 @@ export function createStudioServer(initialConfig, root) {
         return c.json({ ok: true });
     });
     app.post("/api/v1/agent", async (c) => {
-        const { instruction, activeBookId, sessionId: reqSessionId, sessionKind: reqSessionKind, actionSource: reqActionSource, requestedIntent: reqRequestedIntent, actionPayload: reqActionPayload, playMode: reqPlayMode, model: reqModel, service: reqService, } = await c.req.json();
+        const { instruction, activeBookId, sessionId: reqSessionId, sessionKind: reqSessionKind, actionSource: reqActionSource, requestedIntent: reqRequestedIntent, actionPayload: reqActionPayload, requestedSkills: reqRequestedSkills, disabledSkills: reqDisabledSkills, playMode: reqPlayMode, model: reqModel, service: reqService, } = await c.req.json();
         const sessionId = reqSessionId;
         if (!instruction?.trim()) {
             return c.json({ error: "No instruction provided" }, 400);
@@ -2645,8 +3109,10 @@ export function createStudioServer(initialConfig, root) {
         const actionSource = normalizeStudioActionSource(reqActionSource);
         const requestedIntent = normalizeStudioRequestedIntent(reqRequestedIntent);
         const actionPayload = normalizeStudioActionPayload(reqActionPayload);
+        const requestedSkills = normalizeStudioSkillIdList(reqRequestedSkills, "requestedSkills");
+        const disabledSkills = normalizeStudioSkillIdList(reqDisabledSkills, "disabledSkills");
         const playMode = normalizeStudioPlayMode(reqPlayMode);
-        broadcast("agent:start", { instruction, activeBookId, sessionId, actionSource, requestedIntent });
+        broadcast("agent:start", { instruction, activeBookId, sessionId, actionSource, requestedIntent, requestedSkills });
         try {
             // Load config + create LLM client (pipeline created after model resolution)
             const config = await loadCurrentProjectConfig({ requireApiKey: false });
@@ -2670,7 +3136,7 @@ export function createStudioServer(initialConfig, root) {
                 bookSession = updatedSession;
             }
             let activeBookConfig = null;
-            if (agentBookId) {
+            if (agentBookId && sessionKind !== "interactive-film-authoring") {
                 try {
                     activeBookConfig = await state.loadBookConfig(agentBookId);
                 }
@@ -2814,6 +3280,7 @@ export function createStudioServer(initialConfig, root) {
                 model: reqModel ?? config.llm.model,
                 currentConfig: config,
                 sessionIdForSSE: bookSession.sessionId,
+                bookIdForSettings: activeBookId ?? undefined,
             }));
             if (requestedIntent && isConfirmedProductionAction({ actionSource, requestedIntent })) {
                 const pendingBookId = requestedIntent === "create_book" && actionPayload?.createBook?.title
@@ -2832,6 +3299,7 @@ export function createStudioServer(initialConfig, root) {
                         pipeline,
                         root,
                         sessionId: bookSession.sessionId,
+                        bookId: agentBookId,
                         streamSessionId,
                         instruction,
                         requestedIntent,
@@ -2863,13 +3331,15 @@ export function createStudioServer(initialConfig, root) {
                         }
                     }
                     const responseText = exec.result ?? "已完成。";
+                    const responseForUser = suppressManualTextForTool(exec) ? "" : responseText;
                     await appendManualSessionMessages(root, bookSession.sessionId, [
                         manualToolAssistantMessage(responseText, exec, configuredEntry?.service ?? reqService ?? config.llm.provider, reqModel ?? config.llm.model),
                     ], instruction, manualToolAppendOptions(sessionKind, exec));
                     await refreshBookSessionFromTranscript();
                     broadcast("agent:complete", { instruction, activeBookId: createdBookId ?? agentBookId, sessionId: bookSession.sessionId, sessionKind });
                     return c.json({
-                        response: responseText,
+                        response: responseForUser,
+                        details: { toolExecutions: [exec] },
                         session: {
                             sessionId: bookSession.sessionId,
                             sessionKind,
@@ -3022,6 +3492,8 @@ export function createStudioServer(initialConfig, root) {
                 actionSource,
                 requestedIntent,
                 actionPayload,
+                requestedSkills,
+                disabledSkills,
                 sessionId: bookSession.sessionId,
                 language: surfaceLanguage,
                 onContextCompression: (event) => {
@@ -3182,6 +3654,7 @@ export function createStudioServer(initialConfig, root) {
                             sessionKind,
                             ...(bookSession.bookId ? { activeBookId: bookSession.bookId } : {}),
                         },
+                        details: { toolExecutions: collectedToolExecs },
                     });
                 }
                 if (result.errorMessage) {
@@ -3442,21 +3915,126 @@ export function createStudioServer(initialConfig, root) {
         await writeFileFs(configPath, JSON.stringify(raw, null, 2), "utf-8");
         return c.json({ ok: true });
     });
+    // --- Global default model ---
+    app.get("/api/v1/project/default-model", async (c) => {
+        const raw = await loadRawConfig(root);
+        const llm = raw.llm && typeof raw.llm === "object" && !Array.isArray(raw.llm)
+            ? raw.llm
+            : {};
+        return c.json({
+            service: typeof llm.service === "string" ? llm.service : null,
+            defaultModel: typeof llm.defaultModel === "string" && llm.defaultModel.trim()
+                ? llm.defaultModel
+                : typeof llm.model === "string" && llm.model.trim()
+                    ? llm.model
+                    : null,
+        });
+    });
+    app.put("/api/v1/project/default-model", async (c) => {
+        const body = await c.req.json();
+        const defaultModel = typeof body.defaultModel === "string" ? body.defaultModel.trim() : "";
+        if (!defaultModel)
+            return c.json({ error: "defaultModel is required" }, 400);
+        const raw = await loadRawConfig(root);
+        raw.llm = raw.llm && typeof raw.llm === "object" && !Array.isArray(raw.llm) ? raw.llm : {};
+        const llm = raw.llm;
+        llm.defaultModel = defaultModel;
+        if (typeof body.service === "string" && body.service.trim()) {
+            llm.service = body.service.trim();
+        }
+        syncTopLevelLlmMirror(llm);
+        await saveRawConfig(root, raw);
+        return c.json({
+            ok: true,
+            service: typeof llm.service === "string" ? llm.service : null,
+            defaultModel,
+        });
+    });
+    // --- Research search provider ---
+    app.get("/api/v1/project/research-search", async (c) => {
+        const raw = await loadRawConfig(root);
+        return c.json({ researchSearch: ResearchSearchConfigSchema.parse(raw.researchSearch ?? {}) });
+    });
+    app.put("/api/v1/project/research-search", async (c) => {
+        const body = await c.req.json();
+        const researchSearch = ResearchSearchConfigSchema.parse(body.researchSearch ?? {});
+        const raw = await loadRawConfig(root);
+        raw.researchSearch = researchSearch;
+        await saveRawConfig(root, raw);
+        return c.json({ ok: true, researchSearch });
+    });
     // --- Chapter review mode (C4a: auto pipeline vs manual checkpoint) ---
     app.get("/api/v1/project/chapter-review-mode", async (c) => {
-        const raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
-        return c.json({ mode: raw.writing?.reviewMode === "manual" ? "manual" : "auto" });
+        const raw = await loadRawConfig(root);
+        return c.json({ mode: readProjectChapterReviewMode(raw) });
     });
     app.put("/api/v1/project/chapter-review-mode", async (c) => {
         const { mode } = await c.req.json();
-        const next = mode === "manual" ? "manual" : "auto";
-        const configPath = join(root, "inkos.json");
-        const raw = JSON.parse(await readFile(configPath, "utf-8"));
+        const next = normalizeChapterReviewMode(mode);
+        const raw = await loadRawConfig(root);
         raw.writing = { ...(raw.writing ?? {}), reviewMode: next };
-        const { writeFile: writeFileFs } = await import("node:fs/promises");
-        await writeFileFs(configPath, JSON.stringify(raw, null, 2), "utf-8");
+        await saveRawConfig(root, raw);
         return c.json({ ok: true, mode: next });
     });
+    app.get("/api/v1/books/:id/chapter-review-mode", async (c) => {
+        const bookId = c.req.param("id");
+        if (!isSafeBookId(bookId))
+            return c.json({ error: "Invalid book id" }, 400);
+        try {
+            const [projectConfig, rawBook] = await Promise.all([
+                loadRawConfig(root),
+                loadRawBookConfig(root, bookId),
+            ]);
+            const projectMode = readProjectChapterReviewMode(projectConfig);
+            const bookMode = readBookChapterReviewMode(rawBook);
+            return c.json({
+                mode: bookMode ?? projectMode,
+                bookMode: bookMode ?? null,
+                projectMode,
+            });
+        }
+        catch {
+            return c.json({ error: `Book "${bookId}" not found` }, 404);
+        }
+    });
+    app.put("/api/v1/books/:id/chapter-review-mode", async (c) => {
+        const bookId = c.req.param("id");
+        if (!isSafeBookId(bookId))
+            return c.json({ error: "Invalid book id" }, 400);
+        const { mode } = await c.req.json();
+        const rawBookPath = join(root, "books", bookId, "book.json");
+        try {
+            const [projectConfig, rawBook] = await Promise.all([
+                loadRawConfig(root),
+                loadRawBookConfig(root, bookId),
+            ]);
+            const projectMode = readProjectChapterReviewMode(projectConfig);
+            if (mode === "inherit") {
+                const writing = rawBook.writing && typeof rawBook.writing === "object" && !Array.isArray(rawBook.writing)
+                    ? { ...rawBook.writing }
+                    : {};
+                delete writing.reviewMode;
+                rawBook.writing = Object.keys(writing).length > 0 ? writing : undefined;
+            }
+            else {
+                rawBook.writing = {
+                    ...(rawBook.writing && typeof rawBook.writing === "object" && !Array.isArray(rawBook.writing) ? rawBook.writing : {}),
+                    reviewMode: normalizeChapterReviewMode(mode),
+                };
+            }
+            await writeFile(rawBookPath, JSON.stringify(rawBook, null, 2), "utf-8");
+            const bookMode = readBookChapterReviewMode(rawBook);
+            return c.json({
+                ok: true,
+                mode: bookMode ?? projectMode,
+                bookMode: bookMode ?? null,
+                projectMode,
+            });
+        }
+        catch {
+            return c.json({ error: `Book "${bookId}" not found` }, 404);
+        }
+    });
     // --- Notify channels ---
     app.get("/api/v1/project/notify", async (c) => {
         const raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
@@ -3999,6 +4577,172 @@ export function createStudioServer(initialConfig, root) {
         catch { /* slow/unreachable upstream — leave llmConnected false */ }
         return c.json(checks);
     });
+    app.get("/api/v1/interactive-films", async (c) => {
+        const filmsDir = join(root, "interactive-films");
+        let entries = [];
+        try {
+            const dirents = await readdir(filmsDir, { withFileTypes: true });
+            entries = dirents.filter((d) => d.isDirectory()).map((d) => d.name);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        const films = [];
+        for (const projectId of entries) {
+            if (!isSafeBookId(projectId))
+                continue;
+            try {
+                const graph = await loadStoryGraph(root, projectId);
+                if (graph)
+                    films.push({ projectId, title: graph.title || projectId });
+            }
+            catch { /* skip dirs without valid story-graph */ }
+        }
+        films.sort((a, b) => a.title.localeCompare(b.title, "zh"));
+        return c.json({ films });
+    });
+    app.post("/api/v1/projects/:id/story-graph/delta", async (c) => {
+        const id = c.req.param("id");
+        if (!isSafeBookId(id)) {
+            return c.json({ error: { code: "INVALID_ID", message: `invalid project id: ${id}` } }, 400);
+        }
+        const { delta } = await c.req.json();
+        const { graph, rev } = await applyGraphDelta({ projectRoot: root, projectId: id, delta: delta });
+        return c.json({ rev, graph });
+    });
+    app.get("/api/v1/projects/:id/story-graph", async (c) => {
+        const id = c.req.param("id");
+        if (!isSafeBookId(id)) {
+            return c.json({ error: { code: "INVALID_ID", message: `invalid project id: ${id}` } }, 400);
+        }
+        const graphPath = join(root, "interactive-films", id, "story-graph.json");
+        try {
+            const raw = await readFile(graphPath, "utf-8");
+            return c.json(JSON.parse(raw));
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return c.json({ error: { code: "NOT_FOUND", message: `story graph not found for ${id}` } }, 404);
+            }
+            throw error;
+        }
+    });
+    app.get("/api/v1/projects/:id/export", async (c) => {
+        const id = c.req.param("id");
+        if (!isSafeBookId(id)) {
+            return c.json({ error: { code: "INVALID_ID", message: `invalid project id: ${id}` } }, 400);
+        }
+        const projectDir = join(root, "interactive-films", id);
+        try {
+            await access(projectDir);
+            const archive = gzipSync(await buildTarArchive(projectDir, id));
+            return new Response(new Uint8Array(archive), {
+                headers: {
+                    "Content-Type": "application/gzip",
+                    "Content-Disposition": `attachment; filename="${encodeURIComponent(id)}.tar.gz"`,
+                },
+            });
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return c.json({ error: { code: "NOT_FOUND", message: `interactive film project not found for ${id}` } }, 404);
+            }
+            throw error;
+        }
+    });
+    app.get("/api/v1/projects/:id/story-graph/validation", async (c) => {
+        const id = c.req.param("id");
+        if (!isSafeBookId(id)) {
+            return c.json({ error: { code: "INVALID_ID", message: `invalid project id: ${id}` } }, 400);
+        }
+        const graph = await loadStoryGraph(root, id);
+        if (!graph) {
+            return c.json({ error: { code: "NOT_FOUND", message: `story graph not found for ${id}` } }, 404);
+        }
+        return c.json(reviewStoryGraph(graph));
+    });
+    app.get("/api/v1/projects/:id/story-graph/analysis", async (c) => {
+        const id = c.req.param("id");
+        if (!isSafeBookId(id))
+            return c.json({ error: { code: "INVALID_ID", message: `invalid project id: ${id}` } }, 400);
+        const graph = await loadStoryGraph(root, id);
+        if (!graph)
+            return c.json({ error: { code: "NOT_FOUND", message: `story graph not found for ${id}` } }, 404);
+        return c.json({ report: reviewStoryGraph(graph), arcs: analyzeEmotionalArcs(graph), distribution: analyzePathDistribution(graph) });
+    });
+    app.get("/api/v1/projects/:id/export/json", async (c) => {
+        const id = c.req.param("id");
+        if (!isSafeBookId(id))
+            return c.json({ error: { code: "INVALID_ID", message: `invalid project id: ${id}` } }, 400);
+        const graph = await loadStoryGraph(root, id);
+        if (!graph)
+            return c.json({ error: { code: "NOT_FOUND", message: `story graph not found for ${id}` } }, 404);
+        return new Response(JSON.stringify(graph, null, 2), {
+            headers: {
+                "Content-Type": "application/json; charset=utf-8",
+                "Content-Disposition": attachmentDisposition(`${id}.story-graph.json`),
+            },
+        });
+    });
+    app.get("/api/v1/projects/:id/export/ink", async (c) => {
+        const id = c.req.param("id");
+        if (!isSafeBookId(id))
+            return c.json({ error: { code: "INVALID_ID", message: `invalid project id: ${id}` } }, 400);
+        const graph = await loadStoryGraph(root, id);
+        if (!graph)
+            return c.json({ error: { code: "NOT_FOUND", message: `story graph not found for ${id}` } }, 404);
+        return new Response(exportInk(graph), {
+            headers: {
+                "Content-Type": "text/plain; charset=utf-8",
+                "Content-Disposition": attachmentDisposition(`${id}.ink`),
+            },
+        });
+    });
+    app.get("/api/v1/projects/:id/export/html", async (c) => {
+        const id = c.req.param("id");
+        if (!isSafeBookId(id))
+            return c.json({ error: { code: "INVALID_ID", message: `invalid project id: ${id}` } }, 400);
+        const graph = await loadStoryGraph(root, id);
+        if (!graph)
+            return c.json({ error: { code: "NOT_FOUND", message: `story graph not found for ${id}` } }, 404);
+        const assetDataUris = {};
+        for (const node of graph.nodes) {
+            const ref = node.imageSlot?.assetRef;
+            if (!ref || assetDataUris[ref])
+                continue;
+            try {
+                const file = resolveProjectImageFile(root, ref);
+                const buf = await readFile(file.resolved);
+                assetDataUris[ref] = `data:${file.contentType};base64,${buf.toString("base64")}`;
+            }
+            catch (err) {
+                console.warn(`[studio] export/html: skipping assetRef "${ref}" —`, err);
+            }
+        }
+        return new Response(buildPlayableHtml(graph, { assetDataUris }), {
+            headers: {
+                "Content-Type": "text/html; charset=utf-8",
+                "Content-Disposition": attachmentDisposition(`${id}.html`),
+            },
+        });
+    });
+    app.post("/api/v1/projects/:id/nodes/:nodeId/image", async (c) => {
+        const id = c.req.param("id");
+        const nodeId = c.req.param("nodeId");
+        if (!isSafeBookId(id)) {
+            return c.json({ error: { code: "INVALID_ID", message: `invalid project id: ${id}` } }, 400);
+        }
+        const graph = await loadStoryGraph(root, id);
+        const node = graph?.nodes.find((n) => n.id === nodeId);
+        if (!node) {
+            return c.json({ error: { code: "NODE_NOT_FOUND", message: `node ${nodeId} not found` } }, 404);
+        }
+        const deps = overrides.nodeImageGenerator ?? (await defaultNodeImageDeps(root));
+        const { assetRef, delta } = await generateNodeImage({ projectRoot: root, projectId: id, node, deps });
+        const { rev } = await applyGraphDelta({ projectRoot: root, projectId: id, delta });
+        return c.json({ assetRef, rev });
+    });
     return app;
 }
 // --- Standalone runner ---