narraeon 0.5.6 → 0.6.0

package/dist/node/runtime/world-revision/WorldRevisionAuthoringTransaction.js

@@ -1,5 +1,6 @@
 import { isPackageFollowupControlPath } from "../content/PackageFollowups.js";
 import { defaultAppLocale } from "../../protocol/appPreferences.js";
+import { assertSameGameplay, gameplayPath, readGameplay, } from "../../protocol/gameplay.js";
 import { inspectContentPackageCurrentTree } from "../content/FileNativeContentTree.js";
 import { SettingAuthoringTransaction, settingImprovementToolDefinitions, } from "../setting/SettingAuthoringTransaction.js";
 import { WorldDocumentStore } from "../world/WorldDocumentStore.js";
@@ -71,8 +72,8 @@ export class WorldRevisionAuthoringTransaction {
         });
     }
 }
-export function worldRevisionToolDefinitions(locale = defaultAppLocale) {
-    return settingImprovementToolDefinitions(locale).map((definition) => {
+export function worldRevisionToolDefinitions(locale, gameplay) {
+    return settingImprovementToolDefinitions(locale, gameplay).map((definition) => {
         const name = settingToRevisionTool.get(definition.name);
         if (name === undefined)
             throw new Error(`Unsupported setting authoring tool: ${definition.name}`);
@@ -84,7 +85,9 @@ export function worldRevisionToolDefinitions(locale = defaultAppLocale) {
         };
     });
 }
-export function worldRevisionRuntimeContract(locale) {
+export function worldRevisionRuntimeContract(locale, gameplay) {
+    // A world's mode and scheme are fixed, so only tabletop worlds mention the file.
+    const tabletop = gameplay.mode === "tabletop";
     return locale === "zh-CN"
         ? `# Runtime 世界修订对话契约
 
@@ -93,7 +96,7 @@ export function worldRevisionRuntimeContract(locale) {
 - 工具调用修改的是尚未应用的工作树。只有玩家点击“应用修订”才会把当前整棵树提交为新的世界状态和控制并解除锁；“放弃修订”会丢弃工作树并解除锁。你不得宣称自己已经应用或放弃修订。
 - 每个完整工具响应按调用顺序结算。成功调用留下逐文件 before-image，可以由玩家单独回滚；失败调用不会撤销同一响应内其他成功调用。
 - 修改既有文件前必须完整读取。list/search cursor 和 read 授权只属于产生它们的工作树 revision；工作树发生任何手动、AI 或回滚写入后，继续修改前必须重新读取。
-- state/* 只接受 .yaml 或 .md 世界文档；control/* 接受 frame.yaml、player-views.yaml、blocks/*.md，以及 followups.yaml 与后置请求引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。可以创建新状态文档；既有状态文档不能删除或移动，因为 Authority 保留其稳定身份。
+- state/* 只接受 .yaml 或 .md 世界文档；control/* 接受 frame.yaml、player-views.yaml、blocks/*.md，以及 followups.yaml 与后置请求引用的 prompts/*.md、renderers/*.html、scripts/*.js、regex/*.yaml、assets/* 文本资源。${tabletop ? "control/gameplay.json 记录世界的玩法模式与判定方案，修订中只能保持不变。" : ""}可以创建新状态文档；既有状态文档不能删除或移动，因为 Authority 保留其稳定身份。
 - 对话跨越“应用”或“放弃”继续时，Runtime 会明确宣布一个新修订 epoch。此前读取授权全部失效；先重新读取新世界，再继续修改。`
         : `# Runtime world-revision conversation contract
 
@@ -102,11 +105,12 @@ export function worldRevisionRuntimeContract(locale) {
 - Tools change the unapplied worktree. Only the player can Apply the complete tree to world state/control and unlock it, or Discard the tree and unlock it. Never claim that you applied or discarded the revision yourself.
 - Calls in each complete tool response settle in order. Every successful call retains per-file before-images for selective rollback; a failed sibling does not undo successful calls.
 - Completely read an existing file before changing it. List/search cursors and read authorization belong only to the worktree revision that produced them. Re-read after any manual, AI, or rollback write.
-- state/* accepts only YAML or Markdown world documents. control/* accepts frame.yaml, player-views.yaml, blocks/*.md, plus followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. New state documents are allowed; existing state documents cannot be deleted or moved because Authority retains their stable identity.
+- state/* accepts only YAML or Markdown world documents. control/* accepts frame.yaml, player-views.yaml, blocks/*.md, plus followups.yaml and its referenced prompts/*.md, renderers/*.html, scripts/*.js, regex/*.yaml and assets/* text resources. ${tabletop ? "control/gameplay.json records the world's gameplay mode and resolution scheme; a revision must leave both unchanged. " : ""}New state documents are allowed; existing state documents cannot be deleted or moved because Authority retains their stable identity.
 - When a conversation continues after Apply or Discard, Runtime announces a new revision epoch and invalidates every prior read authorization. Re-read the new world before editing.`;
 }
 export function inspectWorldRevisionFiles(files, immutableBaseFiles) {
     const diagnostics = [];
+    diagnostics.push(...gameplayDiagnostics(immutableBaseFiles, files));
     const paths = new Set();
     for (const file of files) {
         if (paths.has(file.path))
@@ -188,6 +192,30 @@ export function inspectWorldRevisionFiles(files, immutableBaseFiles) {
         diagnostics,
     };
 }
+/** A malformed gameplay file is reported by content inspection, not as a scheme change. */
+function gameplayDiagnostics(immutableBaseFiles, files) {
+    try {
+        readGameplay(files);
+    }
+    catch {
+        return [];
+    }
+    try {
+        assertSameGameplay(immutableBaseFiles, files);
+        return [];
+    }
+    catch (error) {
+        return [
+            {
+                code: "gameplay_change_forbidden",
+                path: gameplayPath,
+                message: error instanceof Error
+                    ? error.message
+                    : "World gameplay mode and resolution scheme are fixed",
+            },
+        ];
+    }
+}
 export function assertUsableWorldRevisionFiles(files, immutableBaseFiles) {
     const inspection = inspectWorldRevisionFiles(files, immutableBaseFiles);
     if (inspection.status !== "usable")
@@ -370,7 +398,8 @@ function mapSchema(schema) {
 function isWritableWorldRevisionPath(path) {
     if (/^state\/.+\.(?:ya?ml|md)$/u.test(path))
         return true;
-    return (isPackageFollowupControlPath(path) ||
+    return (path === gameplayPath ||
+        isPackageFollowupControlPath(path) ||
         path === "control/frame.yaml" ||
         path === "control/player-views.yaml" ||
         /^control\/blocks\/.+\.md$/u.test(path));

package/dist/node/runtime/world-revision/WorldRevisionSession.js

@@ -233,16 +233,18 @@ export class WorldRevisionSession {
         const worlds = await this.#worlds.listWorlds();
         const playPreset = await this.#bindPlayPreset();
         const locale = this.#locale();
+        const gameplay = await this.#worlds.gameplay(worldId);
         const bootstrap = this.#compiler.compileWorldRevision({
             ...(epoch === null
                 ? {}
                 : { epoch: { id: epoch.epochId, baseHead: epoch.baseHead } }),
             worldTitle: worlds.find((world) => world.worldId === worldId)?.title ?? worldId,
-            runtimeContract: worldRevisionRuntimeContract(locale),
+            gameplay,
+            runtimeContract: worldRevisionRuntimeContract(locale, gameplay),
             authorPrompt: settingImprovementPromptForBinding(playPreset, locale),
             playPreset,
             modelBinding: modelBinding,
-            tools: worldRevisionToolDefinitions(locale),
+            tools: worldRevisionToolDefinitions(locale, gameplay),
         });
         return { bootstrap, playPreset };
     }
@@ -253,19 +255,21 @@ export class WorldRevisionSession {
         return this.#mutate(async () => this.#view(await this.#recoverIfNeeded(await this.#store.readSession(sessionId))));
     }
     async #create(worldId, epoch, creationRequestId) {
-        const [host, playPreset, worlds] = await Promise.all([
+        const [host, playPreset, worlds, gameplay] = await Promise.all([
             this.#bindModelHost(),
             this.#bindPlayPreset(),
             this.#worlds.listWorlds(),
+            this.#worlds.gameplay(worldId),
         ]);
         const worldTitle = worlds.find((world) => world.worldId === worldId)?.title ?? worldId;
         const locale = this.#locale();
         const modelBinding = host.binding();
-        const tools = worldRevisionToolDefinitions(locale);
+        const tools = worldRevisionToolDefinitions(locale, gameplay);
         const bootstrap = this.#compiler.compileWorldRevision({
             epoch: { id: epoch.epochId, baseHead: epoch.baseHead },
             worldTitle,
-            runtimeContract: worldRevisionRuntimeContract(locale),
+            gameplay,
+            runtimeContract: worldRevisionRuntimeContract(locale, gameplay),
             authorPrompt: settingImprovementPromptForBinding(playPreset, locale),
             playPreset,
             modelBinding,

package/dist/node/server/ConversationStream.js

@@ -68,6 +68,8 @@ export function registerConversationStream(server, runtime) {
                 }
             }
             catch (error) {
+                request.log.error({ err: error, conversationTarget: target }, "conversation observation failed");
+                await runtime.recordConversationFailure?.(target, error);
                 write(`event: failure\ndata: ${JSON.stringify({ message: error instanceof Error ? error.message : "Conversation observation failed" })}\n\n`);
                 stream.end();
                 cleanup();

package/dist/node/server/createServer.js

@@ -6,6 +6,7 @@ import fastifyStatic from "@fastify/static";
 import Fastify, { LogController, } from "fastify";
 import { maxPortableContentArchiveBase64Characters } from "../protocol/contentTree.js";
 import { parseV1Envelope, V1ProtocolError, v1Protocol, } from "../protocol/v1.js";
+import { WorldArchiveError } from "../runtime/archive/WorldArchiveZip.js";
 const runtimeRequestBodyLimit = maxPortableContentArchiveBase64Characters + 64 * 1024;
 const playCallChainStreamContentType = "application/x-ndjson";
 class RuntimeLogController extends LogController {
@@ -81,6 +82,53 @@ export async function createServer(input) {
         done(null, payload);
     });
     registerConversationStream(server, input.runtime);
+    // Keep uploads as a backpressured stream with their own archive-size limit.
+    // Fastify's JSON parser and content-package body limit never buffer this route.
+    await server.register((archives, _options, done) => {
+        archives.addContentTypeParser("application/zip", (_request, payload, done) => done(null, payload));
+        archives.post("/api/runtime/v1/world-archives", async (request, reply) => {
+            try {
+                return await input.runtime.worldArchives.upload(request.body);
+            }
+            catch (error) {
+                if (error instanceof WorldArchiveError)
+                    return reply
+                        .status(error.code === "limit_exceeded" ? 413 : 400)
+                        .send({ error: { code: error.code, message: error.message } });
+                throw error;
+            }
+        });
+        archives.get("/api/runtime/v1/world-archives/:archiveId", async (request, reply) => {
+            try {
+                const archive = await input.runtime.worldArchives.download(request.params.archiveId);
+                reply.raw.once("finish", () => {
+                    void archive.cleanup().catch(() => undefined);
+                });
+                return reply
+                    .type("application/zip")
+                    .header("Content-Length", archive.metadata.bytes)
+                    .header("Content-Disposition", `attachment; filename="world.narraeon-world.zip"; filename*=UTF-8''${encodeURIComponent(archive.metadata.fileName)}`)
+                    .send(archive.stream);
+            }
+            catch (error) {
+                if (error instanceof WorldArchiveError)
+                    return reply
+                        .status(400)
+                        .send({ error: { code: error.code, message: error.message } });
+                if (error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT")
+                    return reply.status(404).send({
+                        error: {
+                            code: "invalid_archive",
+                            message: "The archive download is unavailable",
+                        },
+                    });
+                throw error;
+            }
+        });
+        done();
+    });
     server.get("/health", () => ({
         status: "ok",
         protocol: "narraeon.runtime/v1",

package/dist/node/shared/default-preset-host.js

@@ -234,7 +234,7 @@ NPC 可以按性格、认知、处境和目标继续做事、与别人交谈、
 
 summary 是目录简介，用于识别文档和判断是否需要读取。只写简短的身份、主题或稳定线索，不复述具体状态和事件经过；具体事实放在正文。仅在识别信息改变时更新标题与简介。
 
-## 保存时机与整理检查点
+## 保存时机、整理与检查点
 
 先按玩家授权与互动需要确定本轮叙事范围和停笔位置，再保存该范围内的事实。保存进行中活动的实际进展、必要原话和待回应事项即可整理截至此刻的状态，不把尚未发生的完成结果提前写入。
 
@@ -243,9 +243,11 @@ summary 是目录简介，用于识别文档和判断是否需要读取。只写
 3. 需要保存但玩家原文和最终叙事没有记录的信息，当轮保存，包括重要场外进展、未表露的认知和隐蔽后果。工具中间文本不能替代持久记录。
 4. 其余可从玩家原文和最终叙事恢复的持续结果，允许事件收尾或合适的中间整理点归并。
 
-按已确定的叙事范围完成本轮必须保存的写入。在本轮原定停笔位置判断整理时机：事件自然告一段落、实际转换场景，或持续活动经过多轮并积累了需要归并的进展时，主动集中整理，不等玩家要求，也不等整个活动完成。只有零散即时变化时，按上述保存时机继续互动；一次写入不等于一次检查点。
+按已确定的叙事范围完成本轮必须保存的写入。整理随时可以进行：持续活动跨多轮积累了需要归并的进展，或发现重复、过期的记录时，直接在当轮工具调用中归并，不需要等事件结束，也不需要登记检查点。整理不等于检查点。只有零散即时变化时，按上述保存时机继续互动。
 
-整理时核对上次检查点后的交互和本轮范围内的结果，补齐必要记录，更新认知、进程、约定和界面值，结束实际已失效的待办并清理重复。此前已写回的事实核对后沿用，无需重复写入。准备好该停笔位置的记录后，调用 world_checkpoint，再输出最终叙事；进行中的活动和待回应事项按原状保存，整理不改变停笔位置。检查点覆盖该叙事，若其中又增加重要结果，继续工具调用补齐。登记回执不是语义完整性认证。
+world_checkpoint 只用于事件之间的间隙：上一事件已在本轮停笔位置自然告一段落，或场景已实际转换，接下来从全新上下文开始也不会丢失仍然重要的细节。登记前核对上次检查点后的交互，把刚结束事件中后续仍需要的结果写入文档，包括当前状态、重要认知、承诺与待办和界面值，因为全新上下文只补入检查点之后的原文，上一事件的经过不会再出现。持续活动中途、对方刚给出需要玩家回应的反馈，或仍有待玩家决定的事项时，不登记检查点。此前已写回的事实核对后沿用，无需重复写入。登记后输出最终叙事；若叙事又增加重要结果，继续工具调用补齐。登记回执不是语义完整性认证。
+
+检查点只标记已经出现的间隙，不是本轮要达成的目标。不要为了到达间隙而加快节奏、压缩过程、替玩家完成尚未授权的步骤或提前结束事件；停笔位置仍按“哪些必须由玩家决定”与互动需要确定。一个事件持续很多轮、跨越多次回复都是正常的，期间不需要登记检查点。
 
 ## 整理与连续性
 
@@ -492,7 +494,7 @@ Prefer natural owners for durable information. Create a separate document for in
 
 summary is a catalog description for identifying a document and deciding whether to read it. Include only a brief identity, topic or stable clue, not detailed state or event accounts; put concrete facts in the body. Update titles and descriptions only when that identifying information changes.
 
-## Save timing and consolidation checkpoints
+## Save timing, consolidation and checkpoints
 
 First choose this turn's narrative scope and stopping point from player authorization and interaction needs, then save facts within that scope. Recording actual progress in an ongoing activity, necessary exact wording and matters awaiting a response can complete maintenance through this moment without writing unrealized completion outcomes in advance.
 
@@ -501,9 +503,11 @@ First choose this turn's narrative scope and stopping point from player authoriz
 3. Save needed information absent from player originals and final narrative during this turn, including important offstage progress, unexpressed knowledge and hidden consequences. Intermediate tool text is not a durable substitute.
 4. Other durable outcomes recoverable from player originals and final narrative may be consolidated at event closure or a suitable intermediate point.
 
-Complete required writes within the chosen narrative scope. At this turn's already chosen stopping point, assess whether consolidation is due: proactively consolidate when an event naturally settles, the scene actually changes, or an ongoing activity has accumulated progress across several turns that needs consolidation. Do not wait for the player to request maintenance or for the whole activity to finish. With only isolated immediate changes, continue the interaction under the saving rules above; one write does not mean one checkpoint.
+Complete required writes within the chosen narrative scope. Consolidation can happen at any time: when an ongoing activity has accumulated progress across several turns that needs consolidation, or records are duplicated or outdated, consolidate directly in this turn's tool calls without waiting for the event to end or registering a checkpoint. Consolidation is not a checkpoint. With only isolated immediate changes, continue the interaction under the saving rules above.
+
+Use world_checkpoint only for gaps between events: the previous event has naturally settled at this turn's stopping point, or the scene has actually changed, and starting a fresh context next would not lose still-important details. Before registration, reconcile interactions since the previous checkpoint and save outcomes of the finished event that remain necessary, including current state, important knowledge, commitments, pending work and interface values. A fresh context replays only originals after the checkpoint; the previous event's account will no longer appear. Do not register during an ongoing activity, immediately after feedback needing the player's response, or while matters await the player's decision. Reuse already saved facts after checking them, without duplicate writes. After registration, produce final narrative; if it adds another important outcome, continue tool calls to save it. Registration is not certification of semantic completeness.
 
-When consolidating, reconcile interactions since the previous checkpoint and outcomes within this turn's scope: fill necessary records, update knowledge, processes, commitments and interface values, close actually expired pending work and remove duplicates. Reuse already saved facts after checking them, without duplicate writes. Once records for that stopping point are ready, call world_checkpoint, then produce final narrative. Preserve ongoing activities and matters awaiting a response as they stand; maintenance does not move the stopping point. The checkpoint covers that narrative; if it adds another important outcome, continue tool calls to save it. Registration is not certification of semantic completeness.
+A checkpoint marks a gap that has already appeared, not a goal for this turn. Do not accelerate the pace, compress the process, complete unauthorized steps for the player or end an event early to reach a gap. Choose the stopping point from what the player must decide and the interaction's needs. One event may last many turns across multiple replies; no checkpoint is needed during it.
 
 ## Maintenance and continuity
 

package/dist/node/shared/ordered-author-prompts.js

@@ -1,4 +1,5 @@
 import { defaultSettingImprovementPromptForLocale } from "./default-setting-improvement-prompt.js";
+import { tabletopAuthorBody } from "./tabletop-guidance.js";
 /** Authoring uses the same permissions as play, with target-specific dynamic references. */
 export function builtinAuthorPrompts(locale) {
     const zh = locale === "zh-CN";
@@ -17,6 +18,13 @@ export function builtinAuthorPrompts(locale) {
             required: false,
             body: defaultSettingImprovementPromptForLocale(locale),
         },
+        {
+            id: "author.tabletop",
+            name: zh ? "跑团创作建议" : "Tabletop authoring guidance",
+            required: false,
+            body: tabletopAuthorBody(locale),
+            gameplay: "tabletop",
+        },
         {
             id: "author.target",
             name: zh

package/dist/node/shared/ordered-play-prompts.js

@@ -1,9 +1,25 @@
 import { historyUseGuidance } from "./history-use-guidance.js";
 import { defaultNarrationPromptForLocale } from "./default-play-prompts.js";
 import { defaultPresetHostFilesForLocale } from "./default-preset-host.js";
+import { tabletopPlayBody } from "./tabletop-guidance.js";
 export function isPromptMessageRole(value) {
     return value === "system" || value === "user" || value === "assistant";
 }
+/**
+ * Unscoped prompts always apply. A scoped prompt applies only when the compiled
+ * world or package is tabletop, so fiction requests never see it.
+ */
+export function promptScopeApplies(scope, gameplay) {
+    return scope === undefined || gameplay.mode === "tabletop";
+}
+/** The scope of an ordered entry: a user entry's own scope or its builtin's. */
+export function orderedPromptScope(entry, catalog) {
+    if (entry.kind === "user")
+        return entry.gameplay;
+    if (entry.kind === "builtin")
+        return catalog.find((item) => item.id === entry.builtin)?.gameplay;
+    return undefined;
+}
 /** Application-owned references. Persist references; freeze resolved text in requests. */
 export function builtinPlayPrompts(locale) {
     const zh = locale === "zh-CN";
@@ -22,7 +38,7 @@ export function builtinPlayPrompts(locale) {
 
 world_patch 的 YAML locator 可以包含 map key 和从零开始的数组下标；remove 删除一个精确位置。未提供的元数据保持原值。world_retire 从目录注入中退役文档，文档仍可读取、引用和恢复。工具响应的成功状态变化与后续最终叙事分别提交，后续失败不回滚已提交变化。成功写入回执表示当前值已改变；以真实回执的结算状态为准，模型文字不能提交世界。
 
-包含工具调用的响应属于中间步，其中的文字尚未展示或提交为最终叙事。收到全部工具结果后，根据回执在最终正文中呈现本轮尚未展示的内容，并与已提交状态一致；没有工具调用的非空正文结束本次循环并由 Runtime 提交。world_checkpoint 仅登记整理声明与历史重放边界，在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；登记后仍可继续工具调用。登记不结束世界内事件，也不自动切换上下文，玩家自行选择。全新上下文补入边界后的已提交玩家原文与最终叙事，排除开场白、工具和推理。
+包含工具调用的响应属于中间步，其中的文字尚未展示或提交为最终叙事。收到全部工具结果后，根据回执在最终正文中呈现本轮尚未展示的内容，并与已提交状态一致；没有工具调用的非空正文结束本次循环并由 Runtime 提交。world_checkpoint 只在事件间隙登记，表示建议从此开始全新上下文，并作为历史重放边界；整理本身不需要登记。在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；登记后仍可继续工具调用。登记不结束世界内事件，也不自动切换上下文，玩家自行选择。全新上下文补入边界后的已提交玩家原文与最终叙事，排除开场白、工具和推理。
 
 ${historyUseGuidance(locale)}`
                 : `# Tools and response settlement
@@ -31,7 +47,7 @@ Use only attached tools. Directories use @dir-* handles from the preload or tool
 
 YAML world_patch locators accept map keys and zero-based array indexes; remove deletes one exact location. Omitted metadata remains unchanged. world_retire removes a document from catalog injection while keeping it readable, referenceable and restorable. Successful tool-response state changes and later final narrative commit separately; later failure does not roll back committed changes. Successful write receipts change current values; the actual receipt determines settlement, not model prose.
 
-Responses containing tool calls are intermediate steps; their text has not yet been displayed or committed as final narrative. After all tool results, use the receipts to present this turn's still-unshown content in final prose consistent with committed state. A nonempty tool-free response ends this loop and Runtime commits it. world_checkpoint only registers a consolidation declaration and history-replay boundary; it takes effect after the subsequent nonempty tool-free final prose successfully commits, including that prose. Further tool calls may follow registration. Registration neither ends an in-world event nor switches context, which the player chooses. Fresh-context replay contains committed player originals and final narratives after the boundary, excluding the opening, tools and reasoning.
+Responses containing tool calls are intermediate steps; their text has not yet been displayed or committed as final narrative. After all tool results, use the receipts to present this turn's still-unshown content in final prose consistent with committed state. A nonempty tool-free response ends this loop and Runtime commits it. world_checkpoint registers only at gaps between events, suggesting a fresh context from that point and defining the history-replay boundary; consolidation itself does not require registration. It takes effect after the subsequent nonempty tool-free final prose successfully commits, including that prose. Further tool calls may follow registration. Registration neither ends an in-world event nor switches context, which the player chooses. Fresh-context replay contains committed player originals and final narratives after the boundary, excluding the opening, tools and reasoning.
 
 ${historyUseGuidance(locale)}`,
         },
@@ -67,6 +83,13 @@ ${historyUseGuidance(locale)}`,
             body,
             required: false,
         })),
+        {
+            id: "play.tabletop",
+            name: zh ? "跑团主持" : "Tabletop GM",
+            body: tabletopPlayBody(locale),
+            required: false,
+            gameplay: "tabletop",
+        },
     ];
 }
 export function defaultOrderedPlayPrompts() {

package/dist/node/shared/sample-packages/index.js

@@ -0,0 +1,10 @@
+import { rainyInnEnglish } from "./rainy-inn-en.js";
+import { rainyInnChinese } from "./rainy-inn-zh.js";
+/** Each caller receives an ordinary, independent content-tree seed. */
+export function sampleContentPackageForLocale(locale) {
+    const sample = locale === "zh-CN" ? rainyInnChinese : rainyInnEnglish;
+    return {
+        title: sample.title,
+        files: sample.files.map((file) => ({ ...file })),
+    };
+}

package/dist/node/shared/sample-packages/rainy-inn-en.js

@@ -0,0 +1,194 @@
+export const rainyInnEnglish = {
+    title: "A Letter at the Rain Lantern Inn",
+    files: [
+        {
+            path: "opening.md",
+            contents: `Rain patters from the inn's eaves. The little brass bell above you is still swaying, and the lobby smells of ginger tea. A lamp casts a warm circle across the wooden counter.
+
+Behind it, a woman in a green apron lifts an empty blue saucer, checks underneath, and sets it down again. “Well, it hasn't grown legs.”
+
+A guest in a grey cardigan looks up from the window table. “A pale blue envelope. It's for my sister, and I haven't sealed it yet.” Beside the counter, a young postal runner pauses with a damp ledger tucked against his chest.
+
+The woman offers you a dry towel. “Welcome in. We're having a small mystery with a letter. Would you mind lending us a fresh pair of eyes?” The counter, umbrella stand, and window table are all within the lamplight. She waits for your answer.
+`,
+        },
+        {
+            path: "world/current-situation.yaml",
+            contents: `$document:
+  id: situation.rainy-inn
+  ref: current-situation
+  title: An empty saucer in the lamplight
+  summary: A small search in the Rain Lantern Inn's lobby.
+  aliases: []
+背景:
+  Time: An autumn evening, nine o'clock, steady rain
+  Place: Rain Lantern Inn lobby, Brookbridge
+Present:
+  - $ref: character.nora
+  - $ref: character.evelyn
+  - $ref: character.kit
+In progress:
+  Letter search: Evelyn's pale blue envelope is no longer on the counter's blue saucer. Nobody has begun a methodical search of the lobby.
+Awaiting a response:
+  Speaker: { $ref: character.nora }
+  Invitation: Welcome in. We're having a small mystery with a letter. Would you mind lending us a fresh pair of eyes?
+Immediate circumstances:
+  - You have just arrived at the doorway. Nora's offered towel has not been taken.
+  - Kit holds the ledger and has paused wiping its damp corner.
+`,
+        },
+        {
+            path: "world/characters/nora.yaml",
+            contents: `$document:
+  id: character.nora
+  ref: nora
+  title: Nora
+  summary: The Rain Lantern's attentive innkeeper, quick to offer practical kindness.
+  aliases: []
+Appearance: Short hair, soft features, a dusting of flour on one cuff.
+Clothing: A cream shirt, forest-green apron, and soft indoor shoes.
+Temperament: Patient; looks for a remedy before laying blame.
+Relationships:
+  Evelyn:
+    Person: { $ref: character.evelyn }
+    View: A familiar guest whose plant stories brighten the lobby; hopes she can rest without worrying tonight.
+  Kit:
+    Person: { $ref: character.kit }
+    View: A neighbour's helpful son, sometimes distracted; willing to hear him out when something goes wrong.
+Knowledge:
+  Letter: Remembers putting Evelyn's envelope on the blue saucer, then leaving to make tea. Did not watch the counter after that.
+  Basis: { $ref: event.letter-entrusted }
+`,
+        },
+        {
+            path: "world/characters/evelyn.yaml",
+            contents: `$document:
+  id: character.evelyn
+  ref: evelyn
+  title: Evelyn
+  summary: A travelling botanical illustrator who shares discoveries in letters.
+  aliases: []
+Appearance: Round glasses and a faint smudge of graphite on her fingertips.
+Clothing: A grey cardigan and navy trousers; her brown rain cape hangs by the umbrellas.
+Temperament: Observant and deliberate; double-checks small details when worried.
+Relationships:
+  Nora:
+    Person: { $ref: character.nora }
+    View: A trusted innkeeper; the missing letter has not made her suspect deliberate concealment.
+  Kit:
+    Person: { $ref: character.kit }
+    View: Met him this evening; trusts his postal expertise but knows little about his habits.
+Important belongings:
+  Letter for her sister: An unsealed pale blue envelope containing a page of news and a hand-drawn leaf study, intended for tomorrow's post.
+Knowledge:
+  Letter: Knows she entrusted it to Nora and now sees an empty saucer; does not know where it went afterward.
+  Basis: { $ref: event.letter-entrusted }
+`,
+        },
+        {
+            path: "world/characters/kit.yaml",
+            contents: `$document:
+  id: character.kit
+  ref: kit
+  title: Kit
+  summary: Brookbridge's young postal runner, always willing to help a neighbour.
+  aliases: []
+Appearance: Rain-flattened hair and a small dimple when he smiles.
+Clothing: An unbuttoned blue raincoat, striped shirt, and canvas shoes with wet toes.
+Temperament: Eager and easily distracted; owns up to mistakes and tries to put them right.
+Relationships:
+  Nora:
+    Person: { $ref: character.nora }
+    View: A neighbour he has known since childhood; trusts her and wants to be useful.
+  Evelyn:
+    Person: { $ref: character.evelyn }
+    View: A new acquaintance with intriguing drawings; hopes to ask about the leaves she sketches.
+Knowledge:
+  Remembered action: Moved a pale blue envelope to make room for his wet ledger, slipping it inside the back cover. Assumed the envelope was empty.
+  Current understanding: Has not caught what Evelyn is looking for or connected her letter with the envelope he moved.
+Belongings:
+  Ledger: Held against his chest; a corner of the back cover is damp.
+`,
+        },
+        {
+            path: "world/locations/rain-lantern-inn.yaml",
+            contents: `$document:
+  id: location.rain-lantern-inn
+  ref: rain-lantern-inn
+  title: Rain Lantern Inn
+  summary: A small inn by Brookbridge's bridge, where neighbours shelter over tea.
+  aliases: []
+Lobby: A wooden counter faces the entrance, with a blue saucer and brass lamp on top. A small table stands by the window; the umbrellas rest beside the door.
+Daily life: Guests can rest over ginger tea; the innkeeper sometimes holds letters for familiar visitors until morning.
+`,
+        },
+        {
+            path: "world/events/letter-entrusted.yaml",
+            contents: `$document:
+  id: event.letter-entrusted
+  ref: letter-entrusted
+  title: A letter left for safekeeping
+  summary: Evelyn's earlier arrangement with Nora to keep a letter at the counter.
+  aliases: []
+When: About half an hour earlier this evening
+Account: Evelyn gave Nora an unsealed pale blue envelope, explaining that it held a letter and leaf drawing for her sister. Nora put it on the blue saucer while Evelyn watched.
+Words: Evelyn said, “I'll seal it in the morning. Could you keep it here until then?” Nora agreed.
+Source: Both Evelyn and Nora were at the counter.
+`,
+        },
+        {
+            path: "control/frame.yaml",
+            contents: `format: narraeon.world-frame/v1
+bindings:
+  currentSituation: "@current-situation"
+instructions:
+  - markdown: blocks/world.md
+context:
+  - slot: { kind: catalog, directory: characters, maxEntries: 3 }
+  - slot: { kind: catalog, directory: locations, maxEntries: 4 }
+  - slot: { kind: catalog, directory: events, maxEntries: 12 }
+  - slot: { kind: document, document: "@rain-lantern-inn" }
+  - slot:
+      kind: reference_targets
+      from:
+        document: "@current-situation"
+        locator: { yaml: [Present] }
+      maxEntries: 3
+  - slot: { kind: current_situation }
+  - slot: { kind: additional_materials }
+`,
+        },
+        {
+            path: "control/blocks/world.md",
+            contents: `<!-- opening.md is the visible opening; world/current-situation.yaml holds the background and pending response; characters/ holds each person's state, relationships, and knowledge; locations/ describes places; events/ records shared past events; frame.yaml selects play material; player-views.yaml selects status values. Adapt these files to write your own story. -->
+
+# Genre and boundaries
+
+Focus on small-town inn life, conversation, and gentle mysteries arising from objects, memories, and misunderstandings. Keep the tone warm and suitable for all ages, without violence, adult content, or life-threatening conspiracies. Sharing a letter's private contents is up to its writer and recipient.
+
+## Documents and where changes belong
+
+Keep relationships, opinions, and knowledge in each person's own world/characters/ document, without a shared truth or secret field. Record events that need shared reference in world/events/; link to the account rather than copying it into each character. Lasting changes to places belong in world/locations/. Keep the letter among its owner's important belongings until independent transfer tracking warrants a separate document.
+`,
+        },
+        {
+            path: "control/player-views.yaml",
+            contents: `format: narraeon.player-views/v1
+views:
+  - id: scene-status
+    title: Right now
+    items:
+      - id: time
+        label: Time
+        select:
+          document: "@current-situation"
+          locator: { yaml: [背景, Time] }
+      - id: place
+        label: Place
+        select:
+          document: "@current-situation"
+          locator: { yaml: [背景, Place] }
+`,
+        },
+    ],
+};