@nilvn/core 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nilzx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @nilvn/core
+
+The contract layer of [NilVN](https://github.com/nilzx/nilvn-engine), a small
+visual-novel engine. No DOM, no dependencies. Every other NilVN piece — the
+runtime, the studio that authors games, plugins and tooling — agrees on the
+shapes defined here, so they can be versioned and shipped separately.
+
+```bash
+pnpm add @nilvn/core
+```
+
+## What is in it
+
+| Module | Exports | Use it to |
+|---|---|---|
+| **IR** | `Project`, `Scene`, `SceneNode` (`SayNode`, `NarrateNode`, `CommandNode`, `ChoiceNode`, `SetNode`, `JumpNode`, `LabelNode`, …), `Actor`, `VariableDef`, `ResourceRegistry`, `PluginRef`, `CURRENT_SCHEMA_VERSION`, `migrateProject` | Read, generate or transform a NilVN project: the structured document the studio edits. Text lives in per-language catalogs and nodes hold keys. `migrateProject` brings an older project to the current schema. |
+| **Command schema** | `CommandSchema`, `ParamSchema`, `BUILTIN_COMMANDS`, `BUILTIN_COMMAND_MAP`, `getCommandSchema` | Know every built-in script command's parameters, types and defaults — the same data the studio builds its forms from and a linter checks against. |
+| **Plugin manifest** | `PluginManifest`, `PluginContributions`, `validatePluginManifest`, `manifestErrors`, `isPluginId`, `PLUGIN_API_VERSION`, `PLUGIN_MANIFEST_FILE`, `EXTENSION_POINTS`, `PERMISSIONS`, `matchPermission`, `hasEngineHalf`, `hasEditorHalf` | Validate a `plugin.json` and introspect the extension-point and permission catalogs. |
+| **Plugin ids** | `FIRST_PARTY_ID_PREFIX`, `resolvePluginId`, `isFirstPartyId`, `pluginSlug`, `manifestCommandMap`, `commandRegistry` | The id conventions (`textfx` → `app.nilvn.textfx`, the reserved first-party namespace) and manifest-derived command registries; `commandRegistry(manifests)` is built-ins plus the commands those manifests contribute, what the serializer needs. The first-party plugins themselves live in `@nilvn/plugins`. |
+| **Script package** | `PackageManifest`, `PackageActor`, `PackagePlugin`, `PACKAGE_FORMAT`, `PACKAGE_MANIFEST_FILE`, `isPackageManifest`, `buildScriptPackage`, `fillPackageAssets`, `packageLanguages`, `packageActors` | Produce a `nilvn.json` package from a project (pure: returns the manifest and file contents; you write the files). |
+| **Chunks** | `ChunkManifest`, `ScriptChunk`, `TextCatalogSlice`, `ContentLoader`, `CHUNK_MANIFEST_FORMAT`, `isChunkManifest`, `buildChunkedExport`, `sceneTextKeys` | The streaming wire format and the loader interface a custom host implements. |
+| **Serialization** | `serializeProject`, `serializeChunk`, `SerializeOptions`, `isAssetRef` | IR → the `.nvn` script the engine plays (`keepKeys` emits `@key` references for runtime language switching; `scenes` scopes the output to a chunk). |
+| **Catalogs** | `exportCatalog`, `importCatalog`, `catalogToText`, `catalogFromText`, `catalogCompleteness`, `authoredKeys`, `nativeLangName` | Round-trip a project's text through a plain-text translation file. |
+| **Screenplay** | `parseScreenplay`, `formatScreenplay`, `stripScreenplayMarkup` | A human-readable markdown screenplay grammar and its normalizer, for writing tools. |
+| **Chrome i18n** | `createI18n`, `applyCatalogs`, `registerEnabledPluginCatalogs` | Stable-id UI string lookup shared by hosts and plugins (a plugin's own `messages` register into it). |
+| **Versions** | `FORMAT_VERSIONS`, `parseSemVer`, `compareSemVer`, `isValidRange`, `satisfiesRange` | Every independently-versioned format in one table, and the semver subset plugin manifests use. |
+
+## Examples
+
+Validate a plugin manifest against an engine version:
+
+```ts
+import { validatePluginManifest } from '@nilvn/core'
+
+const { errors, warnings } = validatePluginManifest(manifest, { engineVersion: '0.14.0' })
+if (errors.length) throw new Error(errors.join('\n'))
+```
+
+Turn a project into a playable package:
+
+```ts
+import { buildScriptPackage, fillPackageAssets, serializeProject } from '@nilvn/core'
+
+const plan = buildScriptPackage(project, { engine: '0.14.0' })
+// plan.manifest  → nilvn.json (chunks.assets still empty)
+// plan.files     → chunk + locale JSON files to write
+// plan.assetRefs → asset references to resolve, then:
+const manifest = fillPackageAssets(plan.manifest, { 'assets/bg/street.svg': { url: 'assets/bg/street.svg', bytes: 12034, kind: 'bg' } })
+
+const script = serializeProject(project)   // or a single .nvn for the whole project
+```
+
+Walk a project:
+
+```ts
+for (const scene of project.scenes) {
+  for (const node of scene.nodes) {
+    if (node.kind === 'say') console.log(node.actor, project.catalogs[project.meta.defaultLang][node.textKey])
+  }
+}
+```
+
+## Versioning
+
+`FORMAT_VERSIONS` lists the on-disk and on-wire shapes that version independently
+of the package: the IR schema (`migrateProject` steps older projects forward),
+the chunk manifest, the script package, the engine save state and the plugin API.
+Each bumps only when its own shape changes incompatibly.
+
+The runtime that plays what this package describes is
+[`@nilvn/engine`](https://www.npmjs.com/package/@nilvn/engine); plugin authors
+start from [`@nilvn/plugin-sdk`](https://www.npmjs.com/package/@nilvn/plugin-sdk).
+
+MIT.

package/dist/catalog.d.ts

@@ -0,0 +1,54 @@
+import type { Lang, Project } from './ir.js';
+/** Native display names for the language switcher / translation UI. Unknown codes
+ *  fall back to the code itself. Shared by the editor (engine keeps its own copy
+ *  to stay dependency-free). */
+export declare const LANG_NATIVE_NAMES: Record<string, string>;
+export declare function nativeLangName(code: Lang): string;
+/** One translatable string: its key, the source-language text (reference), and
+ *  the target-language text ('' when not yet translated). */
+export interface CatalogEntry {
+    key: string;
+    source: string;
+    target: string;
+}
+export interface CatalogExport {
+    sourceLang: Lang;
+    targetLang: Lang;
+    entries: CatalogEntry[];
+}
+/** Per-language translation coverage against the authored (source) catalog. */
+export interface LangCompleteness {
+    lang: Lang;
+    total: number;
+    translated: number;
+    /** Authored keys with no (or empty) translation in this language. */
+    missing: string[];
+}
+export interface ImportResult {
+    /** Keys written with a non-empty translation. */
+    applied: number;
+    /** Entries left blank in the file (existing translations are kept untouched). */
+    skipped: number;
+    /** Keys in the file that aren't authored in the source catalog (ignored). */
+    unknown: string[];
+}
+/** Keys that carry authored text: non-empty entries in the source catalog. Actor
+ *  names (`actor.*`) and scene titles (`scene.*`) live here too, so they localize
+ *  alongside dialogue. Empty placeholders (seeded by the editor for new nodes) are
+ *  skipped — there's nothing to translate yet. */
+export declare function authoredKeys(project: Project, sourceLang: Lang): string[];
+/** Pair every authored key with its source text and current target text, ready to
+ *  serialize for a translator. `sourceLang` defaults to the work's default lang. */
+export declare function exportCatalog(project: Project, targetLang: Lang, sourceLang?: Lang): CatalogExport;
+/** Merge a translated export back into project.catalogs[targetLang] (in place).
+ *  Only authored keys are written; blank targets leave any existing translation
+ *  alone. Registers the target language in meta.languages so it ships. */
+export declare function importCatalog(project: Project, data: CatalogExport): ImportResult;
+/** How completely `lang` translates the authored source. The source language is
+ *  trivially 100%. */
+export declare function catalogCompleteness(project: Project, lang: Lang, sourceLang?: Lang): LangCompleteness;
+/** Serialize an export to the line-based translation file (see file header). */
+export declare function catalogToText(data: CatalogExport): string;
+/** Parse a translation file back into an export. Throws on a missing/garbled
+ *  header so the caller can surface a clear error rather than importing nothing. */
+export declare function catalogFromText(text: string): CatalogExport;

package/dist/catalog.js

@@ -0,0 +1,137 @@
+// Catalog localization round-trip: export the authored text as a plain-text
+// translation file, hand it to a human or an LLM, then import the translations
+// back into the project's per-language catalogs. Logic and text stay separate
+// (see ir.ts): only the TextCatalog values move, never the scene/node structure.
+//
+// The file format is line-based and language-neutral so any editor / LLM can fill
+// it in without special tooling:
+//
+//   # nilvn-i18n source=en target=ja
+//   # <human instructions, trilingual>
+//
+//   @scene.intro
+//   en: Prologue
+//   ja: プロローグ
+//
+//   @t_a1b2c3d4
+//   en: Hello, nice to meet you.
+//   ja:
+//
+// `@<key>` opens an entry; `<sourceLang>:` is the read-only reference; the line
+// prefixed with the target language code is what the translator fills in. Catalog
+// values are single-line by construction (the DSL puts each line of dialogue on
+// one line; breaks are `{br}` markers, not real newlines), so a line-based format
+// round-trips losslessly.
+/** Native display names for the language switcher / translation UI. Unknown codes
+ *  fall back to the code itself. Shared by the editor (engine keeps its own copy
+ *  to stay dependency-free). */
+export const LANG_NATIVE_NAMES = { zh: '中文', ja: '日本語', en: 'English' };
+export function nativeLangName(code) {
+    return LANG_NATIVE_NAMES[code] ?? code;
+}
+/** Keys that carry authored text: non-empty entries in the source catalog. Actor
+ *  names (`actor.*`) and scene titles (`scene.*`) live here too, so they localize
+ *  alongside dialogue. Empty placeholders (seeded by the editor for new nodes) are
+ *  skipped — there's nothing to translate yet. */
+export function authoredKeys(project, sourceLang) {
+    const src = project.catalogs[sourceLang] ?? {};
+    return Object.keys(src)
+        .filter((k) => src[k]?.trim())
+        .sort();
+}
+/** Pair every authored key with its source text and current target text, ready to
+ *  serialize for a translator. `sourceLang` defaults to the work's default lang. */
+export function exportCatalog(project, targetLang, sourceLang) {
+    const sLang = sourceLang ?? project.meta.defaultLang;
+    const src = project.catalogs[sLang] ?? {};
+    const tgt = project.catalogs[targetLang] ?? {};
+    const entries = authoredKeys(project, sLang).map((key) => ({
+        key,
+        source: src[key] ?? '',
+        target: tgt[key] ?? '',
+    }));
+    return { sourceLang: sLang, targetLang, entries };
+}
+/** Merge a translated export back into project.catalogs[targetLang] (in place).
+ *  Only authored keys are written; blank targets leave any existing translation
+ *  alone. Registers the target language in meta.languages so it ships. */
+export function importCatalog(project, data) {
+    const authored = new Set(authoredKeys(project, data.sourceLang));
+    const catalog = (project.catalogs[data.targetLang] ??= {});
+    const result = { applied: 0, skipped: 0, unknown: [] };
+    for (const { key, target } of data.entries) {
+        if (!authored.has(key)) {
+            result.unknown.push(key);
+            continue;
+        }
+        const value = target.trim();
+        if (!value) {
+            result.skipped++;
+            continue;
+        }
+        catalog[key] = value;
+        result.applied++;
+    }
+    if (result.applied > 0 && !project.meta.languages.includes(data.targetLang)) {
+        project.meta.languages.push(data.targetLang);
+    }
+    return result;
+}
+/** How completely `lang` translates the authored source. The source language is
+ *  trivially 100%. */
+export function catalogCompleteness(project, lang, sourceLang) {
+    const sLang = sourceLang ?? project.meta.defaultLang;
+    const keys = authoredKeys(project, sLang);
+    if (lang === sLang)
+        return { lang, total: keys.length, translated: keys.length, missing: [] };
+    const cat = project.catalogs[lang] ?? {};
+    const missing = keys.filter((k) => !cat[k]?.trim());
+    return { lang, total: keys.length, translated: keys.length - missing.length, missing };
+}
+// ---------- plain-text serialization ----------
+const HEADER = '# nilvn-i18n';
+/** Serialize an export to the line-based translation file (see file header). */
+export function catalogToText(data) {
+    const { sourceLang: s, targetLang: t } = data;
+    const out = [
+        `${HEADER} source=${s} target=${t}`,
+        `# Fill each「${t}:」line with the ${nativeLangName(t)} translation of the「${s}:」line above it.`,
+        `# 在每个「${t}:」行后填写上面「${s}:」行的译文；请勿改动「@」开头的 key 行与「${s}:」行。`,
+        `# 各「${t}:」行に、上の「${s}:」行の訳を記入してください（「@」の key 行と「${s}:」行は変更しない）。`,
+        '',
+    ];
+    for (const e of data.entries) {
+        out.push(`@${e.key}`, `${s}: ${e.source}`, `${t}: ${e.target}`, '');
+    }
+    return out.join('\n').trimEnd() + '\n';
+}
+/** Parse a translation file back into an export. Throws on a missing/garbled
+ *  header so the caller can surface a clear error rather than importing nothing. */
+export function catalogFromText(text) {
+    const lines = text.split(/\r?\n/);
+    const head = lines.find((l) => l.startsWith(HEADER));
+    const sourceLang = head?.match(/\bsource=(\S+)/)?.[1];
+    const targetLang = head?.match(/\btarget=(\S+)/)?.[1];
+    if (!sourceLang || !targetLang) {
+        throw new Error('Not a NilVN translation file (missing "# nilvn-i18n source=… target=…" header).');
+    }
+    const srcPrefix = sourceLang + ':';
+    const tgtPrefix = targetLang + ':';
+    const entries = [];
+    let cur = null;
+    for (const line of lines) {
+        if (line.startsWith('@')) {
+            cur = { key: line.slice(1).trim(), source: '', target: '' };
+            if (cur.key)
+                entries.push(cur);
+            continue;
+        }
+        if (!cur)
+            continue;
+        if (line.startsWith(srcPrefix))
+            cur.source = line.slice(srcPrefix.length).trim();
+        else if (line.startsWith(tgtPrefix))
+            cur.target = line.slice(tgtPrefix.length).trim();
+    }
+    return { sourceLang, targetLang, entries };
+}

package/dist/chunk-build.d.ts

@@ -0,0 +1,37 @@
+import type { Project, SceneNode } from './ir.js';
+import type { CommandSchema } from './schema.js';
+import { type ChunkManifest } from './chunk.js';
+/** A JSON file the producer must write into the export, with its byte size
+ *  already reflected in the manifest. `text` is the exact file content. */
+export interface ChunkFile {
+    path: string;
+    text: string;
+    bytes: number;
+}
+export interface ChunkedExportPlan {
+    /** The manifest, with `assets` left EMPTY — the editor fills ref→{url,bytes,kind}
+     *  from its AssetStore, then writes manifest.json. Everything else is final. */
+    manifest: ChunkManifest;
+    /** chunks/meta.json + chunks/scene/*.json + chunks/locale/<lang>/*.json, ready
+     *  to write verbatim (bytes already counted into the manifest). */
+    files: ChunkFile[];
+    /** Deduped union of every chunk's asset refs — the editor resolves these to
+     *  files under assets/ and fills manifest.assets. */
+    assetRefs: string[];
+}
+export interface BuildChunkedOptions {
+    /** Target engine version stamped into the manifest (mismatch → clean load error). */
+    engine: string;
+    /** Scene-id groups, in play order, one per chunk. Defaults to one scene per
+     *  chunk; pass story-map chapter groupings to merge (a chunk = many scenes). */
+    groups?: string[][];
+    /** Command schema registry for serialization (`commandRegistry(manifests)`);
+     *  built-ins only when omitted — see SerializeOptions.commands. */
+    commands?: Record<string, CommandSchema>;
+}
+/** Catalog keys a scene's runtime body references (say/narrate text + choice
+ *  option labels) — i.e. the text that belongs in this scene's locale slice.
+ *  Exported: the editor's shard partition (per-scene locale slices) claims keys
+ *  with the same walker, so export slicing and persistence slicing cannot drift. */
+export declare function sceneTextKeys(nodes: SceneNode[], into: Set<string>): void;
+export declare function buildChunkedExport(project: Project, opts: BuildChunkedOptions): ChunkedExportPlan;

package/dist/chunk-build.js

@@ -0,0 +1,187 @@
+// Chunked streaming export — the producer half.
+//
+// buildChunkedExport(project) turns a Project into the script side of a chunked
+// export: the manifest (minus per-file asset metadata, which the editor fills from
+// its AssetStore) + the chunk/locale file contents. Pure, zero-I/O, zero-dep —
+// the editor (export-html.ts) writes the files, fetches assets, and zips.
+//
+// Full single-file export does NOT use this — it stays one inlined script
+// (serializeProject). This builder is for the chunked ZIP/Tauri product only.
+import { serializeChunk } from './serialize.js';
+import { CHUNK_MANIFEST_FORMAT, } from './chunk.js';
+/** UTF-8 byte length of a string — pure, so @nilvn/core stays zero-dep and
+ *  environment-agnostic (no TextEncoder, which isn't in core's lib). Matches what
+ *  TextEncoder().encode(s).length would return; used for the manifest byte hints. */
+function utf8Len(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c < 0x80)
+            n += 1;
+        else if (c < 0x800)
+            n += 2;
+        else if (c >= 0xd800 && c <= 0xdbff) {
+            n += 4; // a surrogate pair encodes one 4-byte code point
+            i++;
+        }
+        else
+            n += 3;
+    }
+    return n;
+}
+/** Resolve a jump/choice target to the SCENE id it lands in, or undefined for an
+ *  in-scene label / dangling target (no cross-chunk edge). Scene ids double as
+ *  labels, so a `label` that names a scene is a cross-scene jump. */
+function targetSceneId(target, sceneIds) {
+    if (target.scene)
+        return sceneIds.has(target.scene) ? target.scene : undefined;
+    if (target.label && sceneIds.has(target.label))
+        return target.label;
+    return undefined;
+}
+/** Catalog keys a scene's runtime body references (say/narrate text + choice
+ *  option labels) — i.e. the text that belongs in this scene's locale slice.
+ *  Exported: the editor's shard partition (per-scene locale slices) claims keys
+ *  with the same walker, so export slicing and persistence slicing cannot drift. */
+export function sceneTextKeys(nodes, into) {
+    for (const n of nodes) {
+        if (n.kind === 'say' || n.kind === 'narrate') {
+            if (n.textKey)
+                into.add(n.textKey);
+        }
+        else if (n.kind === 'choice') {
+            for (const o of n.options)
+                if (o.labelKey)
+                    into.add(o.labelKey);
+        }
+    }
+}
+export function buildChunkedExport(project, opts) {
+    const sceneOrder = project.scenes.map((s) => s.id);
+    const sceneIds = new Set(sceneOrder);
+    const byId = new Map(project.scenes.map((s) => [s.id, s]));
+    const groups = opts.groups ?? sceneOrder.map((id) => [id]);
+    // Each group → one chunk. Chunk id = its first scene id (stable, unique).
+    const chunks = [];
+    const files = [];
+    const labelIndex = {};
+    const sceneToChunk = new Map();
+    const allAssetRefs = new Set();
+    // Per-language, per-chunk key sets (for slicing) + the union of all scene keys
+    // (so base = catalog − sceneKeys).
+    const sceneKeysByChunk = new Map();
+    const allSceneKeys = new Set();
+    for (const group of groups) {
+        const ids = group.filter((id) => sceneIds.has(id));
+        if (!ids.length)
+            continue;
+        const chunkId = ids[0];
+        const { body, labels, assetRefs } = serializeChunk(project, { scenes: ids, keepKeys: true, crossChunk: true, ...(opts.commands ? { commands: opts.commands } : {}) });
+        const scriptChunk = { id: chunkId, body, labels };
+        const text = JSON.stringify(scriptChunk);
+        const bytes = utf8Len(text);
+        files.push({ path: `chunks/scene/${chunkId}.json`, text, bytes });
+        for (const label of labels) {
+            if (label in labelIndex) {
+                throw new Error(`Duplicate jump label "${label}" across chunks (${labelIndex[label]} and ${chunkId}); ` +
+                    `labels must be globally unique to chunk a project. Rename one.`);
+            }
+            labelIndex[label] = chunkId;
+        }
+        for (const id of ids)
+            sceneToChunk.set(id, chunkId);
+        for (const r of assetRefs)
+            allAssetRefs.add(r);
+        const keys = new Set();
+        for (const id of ids)
+            sceneTextKeys(byId.get(id).nodes, keys);
+        sceneKeysByChunk.set(chunkId, keys);
+        for (const k of keys)
+            allSceneKeys.add(k);
+        chunks.push({
+            id: chunkId, scenes: ids, url: `chunks/scene/${chunkId}.json`, bytes,
+            labels, assets: assetRefs, next: [], branchTargets: [],
+        });
+    }
+    // Prefetch hints: linear fall-through (next scene after the chunk's LAST scene,
+    // unless that scene ends in an unconditional jump) + explicit branch targets.
+    for (const chunk of chunks) {
+        const next = new Set();
+        const branch = new Set();
+        for (const sceneId of chunk.scenes) {
+            const scene = byId.get(sceneId);
+            for (const n of scene.nodes) {
+                if (n.kind === 'jump')
+                    addEdge(targetSceneId(n.target, sceneIds));
+                else if (n.kind === 'choice')
+                    for (const o of n.options)
+                        addEdge(targetSceneId(o.target, sceneIds));
+            }
+        }
+        // Fall-through from the chunk's last scene to the next scene in project order.
+        const lastSceneId = chunk.scenes[chunk.scenes.length - 1];
+        const lastScene = byId.get(lastSceneId);
+        const last = lastScene.nodes[lastScene.nodes.length - 1];
+        const fallsThrough = !(last && last.kind === 'jump' && !last.condition);
+        if (fallsThrough) {
+            const after = sceneOrder[sceneOrder.indexOf(lastSceneId) + 1];
+            const c = after && sceneToChunk.get(after);
+            if (c && c !== chunk.id)
+                next.add(c);
+        }
+        chunk.next = [...next];
+        chunk.branchTargets = [...branch];
+        function addEdge(sid) {
+            const c = sid && sceneToChunk.get(sid);
+            if (c && c !== chunk.id)
+                branch.add(c);
+        }
+    }
+    // Locale slices: a `base` slice per language (project-level keys — actor names,
+    // scene titles, anything not in a scene body, loaded with meta and always warm)
+    // + one slice per chunk (its scenes' dialogue, loaded when the chunk loads).
+    const langs = project.meta.languages?.length ? project.meta.languages : [project.meta.defaultLang];
+    const locales = {};
+    for (const lang of langs) {
+        const catalog = project.catalogs[lang] ?? {};
+        const slices = [];
+        // base = catalog keys not referenced by any scene body.
+        const base = {};
+        for (const k of Object.keys(catalog))
+            if (!allSceneKeys.has(k))
+                base[k] = catalog[k];
+        pushSlice(lang, 'base', [], base, slices);
+        for (const chunk of chunks) {
+            const slice = {};
+            for (const k of sceneKeysByChunk.get(chunk.id))
+                if (k in catalog)
+                    slice[k] = catalog[k];
+            pushSlice(lang, chunk.id, chunk.scenes, slice, slices);
+        }
+        locales[lang] = slices;
+    }
+    function pushSlice(lang, id, scenes, slice, out) {
+        const text = JSON.stringify(slice);
+        const bytes = utf8Len(text);
+        files.push({ path: `chunks/locale/${lang}/${id}.json`, text, bytes });
+        out.push({ id, scenes, url: `chunks/locale/${lang}/${id}.json`, bytes });
+    }
+    // meta.json: the whole project MINUS scenes + catalogs (the always-warm base —
+    // actors / variables / resources / plugins / loopClips / meta).
+    const { scenes: _scenes, catalogs: _catalogs, ...metaJson } = project;
+    const metaText = JSON.stringify(metaJson);
+    files.push({ path: 'chunks/meta.json', text: metaText, bytes: utf8Len(metaText) });
+    const manifest = {
+        format: CHUNK_MANIFEST_FORMAT,
+        engine: opts.engine,
+        schemaVersion: project.meta.schemaVersion ?? 0,
+        entry: { label: sceneOrder[0] ?? '' },
+        defaultLang: project.meta.defaultLang,
+        sceneOrder,
+        chunks,
+        labelIndex,
+        locales,
+        assets: {}, // editor fills ref → {url, bytes, kind}
+    };
+    return { manifest, files, assetRefs: [...allAssetRefs] };
+}

package/dist/chunk.d.ts

@@ -0,0 +1,106 @@
+import type { Lang } from './ir.js';
+/** Streaming-export format version (independent of the IR `schemaVersion`).
+ *  Bumped only when the manifest/chunk wire shape changes incompatibly. */
+export declare const CHUNK_MANIFEST_FORMAT = 1;
+/** One playable script chunk's manifest entry — a group of scenes compiled
+ *  together (default: one scene per chunk; story-map chapters may merge several). */
+export interface ManifestChunk {
+    /** Stable chunk id (also the filename stem under `chunks/scene/`). */
+    id: string;
+    /** Scene ids this chunk contains, in project order. */
+    scenes: string[];
+    /** Where to fetch the chunk body, relative to the manifest. */
+    url: string;
+    /** Decoded-or-encoded byte size, for prefetch budgeting / progress. */
+    bytes: number;
+    /** Every jump-target label this chunk DEFINES (scene ids + in-scene labels).
+     *  Feeds the manifest `labelIndex`; globally unique across chunks. */
+    labels: string[];
+    /** Asset refs this chunk references (command params + per-line voice). */
+    assets: string[];
+    /** Prefetch hint: the chunk(s) reachable by linear fall-through. */
+    next: string[];
+    /** Prefetch hint: chunk(s) reachable by an explicit jump/choice target. */
+    branchTargets: string[];
+}
+/** One language's catalog slice — the text for a group of scenes, mirroring the
+ *  scene chunks so only the current language's resident-scene slices need loading. */
+export interface ManifestLocaleSlice {
+    id: string;
+    /** Scene ids whose text this slice carries (parallels a scene chunk). */
+    scenes: string[];
+    url: string;
+    bytes: number;
+}
+/** Discrete asset file entry. The ref→file map lets any asset be fetched BY REF
+ *  regardless of whether its owning chunk is resident (backlog voice replay,
+ *  eventual window eviction) — seam constraint 2. */
+export interface ManifestAsset {
+    url: string;
+    bytes: number;
+    /** bg / char / audio / voice / sprite — for warm/release policy. */
+    kind: string;
+}
+/** The chunked export's directory/index (manifest.json) — the contract core
+ *  and the engine share. */
+export interface ChunkManifest {
+    /** Streaming-export format version; see CHUNK_MANIFEST_FORMAT. */
+    format: number;
+    /** Target engine version the chunks were compiled for (mismatch → clean error). */
+    engine: string;
+    /** IR schema version (mirrors ProjectMeta.schemaVersion). */
+    schemaVersion: number;
+    /** Where playback opens. */
+    entry: {
+        label: string;
+    };
+    defaultLang: Lang;
+    /** Linear scene order (scene-to-scene fall-through). */
+    sceneOrder: string[];
+    chunks: ManifestChunk[];
+    /** Any label (jump target / save resume point) → the chunk that defines it.
+     *  Denormalized for O(1) resolution: jump/restore = labelIndex[label] →
+     *  ensure that chunk loaded → base+offset. Seam constraint 1. */
+    labelIndex: Record<string, string>;
+    /** Per-language catalog slice lists, parallel to the scene chunks. */
+    locales: Record<string, ManifestLocaleSlice[]>;
+    /** Asset ref → file. Seam constraint 2 (by-ref, residency-independent). */
+    assets: Record<string, ManifestAsset>;
+}
+/** A decoded script chunk — what `ContentLoader.loadChunk` yields: the playable
+ *  `.nvn` body for its scenes plus the labels it defines (for the residency merge). */
+export interface ScriptChunk {
+    id: string;
+    /** The `.nvn` DSL the engine parser consumes (serializeChunk's `body`). */
+    body: string;
+    /** Labels this chunk defines (serializeChunk's `labels`). */
+    labels: string[];
+}
+/** A decoded locale slice — catalog key → resolved text, for the slice's scenes
+ *  in one language. Merged into the engine's catalog for that language. */
+export type TextCatalogSlice = Record<string, string>;
+/** The runtime seam the engine resolves content through (docs/.../streaming §3).
+ *  Bytes are pluggable: Web loader fetches; a future Tauri loader reads natively
+ *  and decrypts in the closed host, handing the engine plaintext to decode — the
+ *  engine never touches ciphertext or keys. */
+export interface ContentLoader {
+    /** Fetch + decode one script chunk by id (internally: read bytes → optional
+     *  decrypt → decode). */
+    loadChunk(chunkId: string): Promise<ScriptChunk>;
+    /** Fetch + decode one locale slice (current language only). */
+    loadLocale(lang: string, sliceId: string): Promise<TextCatalogSlice>;
+    /** Resolve an asset's playable URL by canonical ref — independent of whether
+     *  the owning chunk is resident (seam constraint 2). */
+    assetUrl(ref: string): Promise<string>;
+    /** Release a chunk's heavy bytes WITHOUT losing the ability to re-resolve its
+     *  assets by ref (seam constraint 3). The engine calls this when it evicts a
+     *  chunk under its opt-in residency ceiling, and for every resident chunk on
+     *  destroy(). An implementation that hands out revocable URLs owns its own
+     *  in-use protection; the bundled loaders never revoke (Web: static URLs,
+     *  no-op — desktop player: stable nvpk:// URLs, drops native plaintext cache). */
+    releaseChunk(chunkId: string): void;
+}
+/** Cheap structural sanity check for a fetched manifest — guards against a
+ *  truncated/foreign/garbage manifest with a clean error rather than a silent
+ *  misparse deep in playback (the version-mismatch gate; producer/loader both use it). */
+export declare function isChunkManifest(x: unknown): x is ChunkManifest;

package/dist/chunk.js

@@ -0,0 +1,35 @@
+// Chunked streaming export — shared contract types.
+//
+// The on-the-wire shape of a chunked/streaming export
+// plus the runtime ContentLoader interface the engine resolves chunks/assets through.
+// Pure types + tiny guards, zero-dep (core stays dependency-free). Producer
+// (editor) and consumer (engine) both import from here so the format can't drift.
+//
+// A full single-file export is the degenerate one-chunk case: it never builds a
+// manifest at all (the engine just loadSource()s the whole script), so these
+// types describe ONLY the chunked product.
+/** Streaming-export format version (independent of the IR `schemaVersion`).
+ *  Bumped only when the manifest/chunk wire shape changes incompatibly. */
+export const CHUNK_MANIFEST_FORMAT = 1;
+/** Cheap structural sanity check for a fetched manifest — guards against a
+ *  truncated/foreign/garbage manifest with a clean error rather than a silent
+ *  misparse deep in playback (the version-mismatch gate; producer/loader both use it). */
+export function isChunkManifest(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const m = x;
+    return (typeof m.format === 'number' &&
+        typeof m.engine === 'string' &&
+        typeof m.schemaVersion === 'number' &&
+        !!m.entry &&
+        typeof m.entry.label === 'string' &&
+        typeof m.defaultLang === 'string' &&
+        Array.isArray(m.sceneOrder) &&
+        Array.isArray(m.chunks) &&
+        !!m.labelIndex &&
+        typeof m.labelIndex === 'object' &&
+        !!m.locales &&
+        typeof m.locales === 'object' &&
+        !!m.assets &&
+        typeof m.assets === 'object');
+}

package/dist/commands.d.ts

@@ -0,0 +1,4 @@
+import type { CommandSchema } from './schema.js';
+export declare const BUILTIN_COMMANDS: CommandSchema[];
+export declare const BUILTIN_COMMAND_MAP: Record<string, CommandSchema>;
+export declare function getCommandSchema(name: string): CommandSchema | undefined;