@nilvn/core 0.14.0

package/dist/serialize.js

@@ -0,0 +1,365 @@
+import { BUILTIN_COMMAND_MAP } from './commands.js';
+export function serializeChunk(project, opts = {}) {
+    const lang = opts.lang ?? project.meta.defaultLang;
+    const catalog = project.catalogs[lang] ?? {};
+    const commands = opts.commands ?? BUILTIN_COMMAND_MAP;
+    // keepKeys: ship the catalog key (`@t.hello`) so text is resolved at play time;
+    // otherwise inline the resolved literal from the chosen language's catalog.
+    const text = opts.keepKeys
+        ? (key) => (key ? '@' + key : '')
+        : (key) => catalog[key] ?? '';
+    const anchorLabel = opts.anchorLabel ?? '__nilvn_here__';
+    const scenes = opts.scenes ? project.scenes.filter((s) => opts.scenes.includes(s.id)) : project.scenes;
+    // When scoped, any jump/choice target that lands OUTSIDE the scope would be an
+    // unknown label at play time (engine.jump throws). Precompute the in-scope sets
+    // so dest() can redirect such a target to the graceful unset landing — a scoped
+    // preview then ends cleanly at its boundary instead of crashing, and the editor
+    // offers to continue into the real target scene. Unscoped = no redirect.
+    // Scene ids are kept SEPARATE from the merged label namespace: a cross-scene
+    // jump must be judged against the scene set alone, so an out-of-scope scene id
+    // that happens to match an in-scope label node's name is still redirected.
+    const scope = opts.scenes ? { labels: new Set(), scenes: new Set() } : null;
+    if (scope) {
+        // Validate targets against just the in-scope scenes (preview: an out-of-scope
+        // jump can't play, so redirect it to the unset landing) OR against the whole
+        // project (chunked export: a jump to another scene is a valid cross-chunk jump
+        // the runtime resolves via labelIndex, so keep it — only a target that names no
+        // scene/label anywhere degrades to unset).
+        const validation = opts.crossChunk ? project.scenes : scenes;
+        for (const scene of validation) {
+            scope.scenes.add(scene.id);
+            scope.labels.add(scene.id);
+            for (const node of scene.nodes)
+                if (node.kind === 'label')
+                    scope.labels.add(node.name);
+        }
+    }
+    const out = [];
+    const labels = [];
+    const assetRefs = new Set();
+    // A–B replay segments (Project.replays, schema v7): only segments whose BOTH
+    // anchors resolve to live nodes are emitted — a dangling anchor (its node was
+    // deleted) degrades to "segment not in this build" rather than a broken label.
+    // Start anchors become a `[label __replay_<id>]` right before their node; end
+    // anchors a `[replayend <id>]` right after theirs (segment inclusive of the end
+    // node). The `[replaydef]` preamble — the gallery list the runtime shows — is
+    // emitted only into the scope holding the project's FIRST scene, so a chunked
+    // export declares each segment once (in the entry chunk).
+    const replayStarts = new Map();
+    const replayEnds = new Map();
+    const validReplays = (project.replays ?? []).filter((r) => hasNode(project, r.start) && hasNode(project, r.end));
+    for (const r of validReplays) {
+        push(replayStarts, r.start.nodeId, r.id);
+        push(replayEnds, r.end.nodeId, r.id);
+    }
+    const holdsEntry = !opts.scenes || (project.scenes[0] !== undefined && opts.scenes.includes(project.scenes[0].id));
+    if (holdsEntry) {
+        for (const r of validReplays) {
+            out.push(`[replaydef id=${token(r.id)} title=${token(text(r.titleKey))} label=${REPLAY_LABEL_PREFIX}${r.id}]`);
+            // The start label is DEFINED in whatever chunk holds the start scene; the
+            // preamble only references it (labelIndex maps it to its defining chunk).
+        }
+        if (validReplays.length)
+            out.push('');
+    }
+    for (const scene of scenes) {
+        // Scene boundary doubles as a jump label so the engine can start(sceneId).
+        out.push(`[label ${scene.id}]`);
+        labels.push(scene.id);
+        for (const node of scene.nodes) {
+            if (opts.anchorNodeId && node.id === opts.anchorNodeId)
+                out.push(`[label ${anchorLabel}]`);
+            for (const segId of replayStarts.get(node.id) ?? []) {
+                out.push(`[label ${REPLAY_LABEL_PREFIX}${segId}]`);
+                labels.push(`${REPLAY_LABEL_PREFIX}${segId}`); // a cross-chunk start target → into labelIndex
+            }
+            if (node.kind === 'label')
+                labels.push(node.name);
+            collectNodeAssets(node, assetRefs);
+            out.push(serializeNode(node, text, commands, scope));
+            for (const segId of replayEnds.get(node.id) ?? [])
+                out.push(`[replayend ${token(segId)}]`);
+        }
+        out.push('');
+    }
+    // A landing spot for not-yet-connected branches/jumps. Reaching it just ends
+    // the script (nothing follows), so an unset target can't break parsing/preview.
+    out.push(`[label ${UNSET_LABEL}]`);
+    return { body: out.join('\n').trimEnd() + '\n', labels, assetRefs: [...assetRefs] };
+}
+/** Serialize to the `.nvn` DSL string (the common case: preview / interchange
+ *  export). Thin wrapper over serializeChunk, so the scoped and full paths are
+ *  identical and a caller that only wants the script stays unchanged. */
+export function serializeProject(project, opts = {}) {
+    return serializeChunk(project, opts).body;
+}
+/** Matches the asset extensions the pipeline ships. Kept beside isAssetRef so the
+ *  predicate is one place (the editor imports it too — no second copy to drift). */
+const ASSET_EXT = /\.(svg|png|jpe?g|gif|webp|avif|mp3|ogg|opus|wav|m4a|aac|flac|mp4|webm)$/i;
+/** True when a value looks like an asset reference — used to pick asset paths out
+ *  of arbitrary command params. Zero-dep, so it's the single shared predicate. */
+export function isAssetRef(v) {
+    return (typeof v === 'string' &&
+        v !== '' &&
+        (v.startsWith('/') || v.startsWith('./') || v.startsWith('asset:') || ASSET_EXT.test(v)));
+}
+/** Scene-scoped asset refs: command params that look like assets + a line's voice
+ *  clip. (Project-level resources / actor faces are collected elsewhere.) */
+function collectNodeAssets(node, into) {
+    if (node.kind === 'command') {
+        for (const v of Object.values(node.params ?? {}))
+            if (isAssetRef(v))
+                into.add(v);
+    }
+    else if (node.kind === 'say' && node.voice) {
+        into.add(node.voice);
+    }
+}
+// Where a jump/choice with no chosen target points until the author connects it.
+const UNSET_LABEL = '__nilvn_unset__';
+/** Label prefix for A–B replay segment start anchors (`__replay_<segId>`). Shared
+ *  with the engine's `playReplay` (which starts at this label) via the wire form
+ *  the `[replaydef]` preamble carries — the engine never re-derives it. */
+export const REPLAY_LABEL_PREFIX = '__replay_';
+/** Whether an anchor's node still exists (in its scene, or anywhere if the scene
+ *  itself was renamed — node ids are globally unique, so an id match suffices). */
+function hasNode(project, anchor) {
+    const scene = project.scenes.find((s) => s.id === anchor.sceneId);
+    if (scene?.nodes.some((n) => n.id === anchor.nodeId))
+        return true;
+    return project.scenes.some((s) => s.nodes.some((n) => n.id === anchor.nodeId));
+}
+function push(map, key, value) {
+    const arr = map.get(key);
+    if (arr)
+        arr.push(value);
+    else
+        map.set(key, [value]);
+}
+// Cross-scene jumps target the scene id (each scene emits `[label sceneId]`),
+// otherwise the in-scene label. The conditional jump path also routes through here.
+// An empty target routes to the unset-landing label so the DSL still parses. When
+// `scope` is given (scoped serialization), a target outside the scope is likewise
+// routed to the unset landing — see the scope comment in serializeChunk.
+function dest(target, scope) {
+    const d = target.scene || target.label || UNSET_LABEL;
+    if (!scope)
+        return d;
+    // A cross-scene jump is in-scope only if its SCENE is in scope (independent of
+    // any label-name collision); a label-only target is judged by the label set.
+    if (target.scene)
+        return scope.scenes.has(target.scene) ? target.scene : UNSET_LABEL;
+    return scope.labels.has(d) ? d : UNSET_LABEL;
+}
+function serializeNode(node, text, commands, scope = null) {
+    switch (node.kind) {
+        case 'label':
+            return `[label ${node.name}]`;
+        case 'say': {
+            const face = node.face ? `(${node.face})` : '';
+            const line = `${node.actor}${face}: ${text(node.textKey)}`;
+            // A per-line voice clip is queued by [voice ...] right before the dialogue;
+            // the engine plays it alongside the line and mutes the synth typing blip.
+            // The start-offset (correction) skips leading silence; emitted only if set.
+            if (!node.voice)
+                return line;
+            const off = node.voiceOffset;
+            const offPart = off && off > 0 ? ` offset=${off}` : '';
+            return `[voice ${token(node.voice)}${offPart}]\n${line}`;
+        }
+        case 'narrate':
+            return `|${text(node.textKey)}`;
+        case 'choice':
+            return node.options
+                .map((o) => {
+                const cond = o.condition ? ` if=${token(o.condition)}` : '';
+                return `[choice ${token(text(o.labelKey))} -> ${dest(o.target, scope)}${cond}]`;
+            })
+                .join('\n');
+        case 'jump':
+            // v1 DSL expresses a conditional jump as [if cond -> label].
+            return node.condition
+                ? `[if ${node.condition} -> ${dest(node.target, scope)}]`
+                : `[jump ${dest(node.target, scope)}]`;
+        case 'set':
+            return `[set ${node.var} = ${node.expr}]`;
+        case 'recall':
+            // v1 DSL has no recall command; emit a comment the engine ignores. The recall
+            // gallery is built from the IR directly, not from the runtime script.
+            return `; recall ${node.recallId}`;
+        case 'command':
+            return serializeCommand(node, commands[node.cmd]);
+        case 'anim':
+            return serializeAnim(node);
+        case 'eventframe':
+            return serializeEventFrame(node);
+        case 'loopstart':
+            return serializeLoopStart(node);
+        case 'loopstop':
+            return serializeLoopStop(node);
+        default: {
+            const _exhaustive = node;
+            return _exhaustive;
+        }
+    }
+}
+function serializeCommand(node, schema) {
+    const parts = [node.cmd];
+    const params = node.params;
+    const used = new Set();
+    if (schema) {
+        const positionals = schema.params
+            .filter((p) => p.positional !== undefined)
+            .sort((a, b) => a.positional - b.positional);
+        // Emit positionals contiguously up to the last one actually provided,
+        // filling any gaps with their defaults so the argument order stays intact.
+        let last = -1;
+        positionals.forEach((p, i) => {
+            if (params[p.key] !== undefined)
+                last = i;
+        });
+        for (let i = 0; i <= last; i++) {
+            const p = positionals[i];
+            used.add(p.key);
+            parts.push(token(params[p.key] ?? p.default ?? ''));
+        }
+        for (const p of schema.params) {
+            if (p.positional !== undefined)
+                continue;
+            used.add(p.key);
+            const val = params[p.key];
+            if (val === undefined)
+                continue;
+            if (p.default !== undefined && val === p.default)
+                continue;
+            parts.push(`${p.key}=${token(val)}`);
+        }
+    }
+    // Params not described by the schema (e.g. unknown plugin command) -> key=value.
+    for (const [k, v] of Object.entries(params)) {
+        if (used.has(k))
+            continue;
+        parts.push(`${k}=${token(v)}`);
+    }
+    return `[${parts.join(' ')}]`;
+}
+// A recorded keyframe animation (AnimNode) serializes to an `[anim …]` command the
+// engine's built-in `anim` handler plays. The whole track rides one compact `kf`
+// token (no whitespace / quotes / brackets, so the tokenizer carries it whole):
+// frames joined by `;`, each `<t>:<code><n>,…[,e<easeCode>]` (bare `<t>` = empty),
+// channel codes x / y / s(scale) / r(rotation) / o(opacity); `t` is seconds.
+// The format mirrors the engine's parseAnimFrames (packages/engine/src/builtins.ts).
+function serializeAnim(node) {
+    const parts = ['anim', `obj=${node.target}`, `dur=${compactNum(node.duration)}`];
+    if (node.hold)
+        parts.push('hold=1');
+    const kf = encodeAnimFrames(node.keyframes);
+    if (kf)
+        parts.push(`kf=${kf}`);
+    return `[${parts.join(' ')}]`;
+}
+const ANIM_CODE = {
+    x: 'x',
+    y: 'y',
+    scale: 's',
+    rotation: 'r',
+    opacity: 'o',
+};
+function encodeAnimFrames(kfs) {
+    return kfs
+        .map((k) => {
+        const ch = [];
+        for (const key of ['x', 'y', 'scale', 'rotation', 'opacity']) {
+            const v = k[key];
+            if (typeof v === 'number')
+                ch.push(`${ANIM_CODE[key]}${compactNum(v)}`);
+        }
+        if (k.ease)
+            ch.push(`e${k.ease}`);
+        return ch.length ? `${compactNum(k.t)}:${ch.join(',')}` : compactNum(k.t);
+    })
+        .join(';');
+}
+// A recording event-frame (EventFrameNode) serializes to an `[eventframe …]`
+// command played by the engine's pure-JS rAF clock. The whole choreography rides
+// one compact `kf` token (no whitespace / quotes / brackets, so the tokenizer
+// carries it whole). The grammar — decoded by the engine's `decodeTracks`
+// (packages/engine/src/keyframes.ts), keep the two in sync:
+//   kf    = TRACK ("|" TRACK)*
+//   TRACK = <objId> "#" FRAME (";" FRAME)*
+//   FRAME = <t> ["~" <easeCode>] [":" CH ("," CH)*]
+//   CH    = <chId> "=" <value>      (number | string | "1"/"0" for booleans)
+// Unlike `[anim]`, channels are addressed by their full recordable id (`scale`,
+// `face`) rather than a single-letter code — the id is data, so a plugin channel
+// round-trips with no shared code table (the "dynamic extraction" model).
+function serializeEventFrame(node) {
+    const parts = ['eventframe', `dur=${compactNum(node.duration)}`];
+    const kf = encodeTracks(node.tracks);
+    if (kf)
+        parts.push(`kf=${kf}`);
+    return `[${parts.join(' ')}]`;
+}
+function encodeTracks(tracks) {
+    return tracks
+        .filter((tr) => tr.keys.length > 0)
+        .map((tr) => `${tr.objId}#${tr.keys.map(encodeKeyframe).join(';')}`)
+        .join('|');
+}
+function encodeKeyframe(k) {
+    const head = k.ease ? `${compactNum(k.t)}~${k.ease}` : compactNum(k.t);
+    const chs = Object.entries(k.ch).map(([id, v]) => `${id}=${encodeChannelValue(v)}`);
+    return chs.length ? `${head}:${chs.join(',')}` : head;
+}
+function encodeChannelValue(v) {
+    if (typeof v === 'number')
+        return compactNum(v);
+    if (typeof v === 'boolean')
+        return v ? '1' : '0';
+    return v;
+}
+// A single-element loop (LoopStart/LoopStop) serializes to `[loopstart …]` /
+// `[loopstop …]` commands played by the engine's loop runtime. The cycle `body`
+// reuses the same compact frame encoding as one event-frame track (the objId rides
+// `obj=` instead of an inline prefix); the anchor `entry` / settle `exit` poses are
+// a bare channel set (`chId=val,…`). Each compound value is a single whitespace-
+// and quote-free token, so the DSL tokenizer carries it whole (decoded by the
+// engine's decodeFrames / decodeChannelSet — keep the two in sync).
+function serializeLoopStart(node) {
+    const parts = ['loopstart', `obj=${node.objId}`, `dur=${compactNum(node.duration)}`];
+    if (node.intoEase)
+        parts.push(`into=${node.intoEase}`);
+    const entry = encodeChannelSet(node.entry);
+    if (entry)
+        parts.push(`entry=${entry}`);
+    const body = node.body.map(encodeKeyframe).join(';');
+    if (body)
+        parts.push(`body=${body}`);
+    return `[${parts.join(' ')}]`;
+}
+function serializeLoopStop(node) {
+    const parts = ['loopstop', `obj=${node.objId}`];
+    if (node.outEase)
+        parts.push(`out=${node.outEase}`);
+    const exit = encodeChannelSet(node.exit);
+    if (exit)
+        parts.push(`exit=${exit}`);
+    return `[${parts.join(' ')}]`;
+}
+/** Encode a bare channel set (`entry` / `exit`) as `chId=val,chId=val`. */
+function encodeChannelSet(ch) {
+    return Object.entries(ch)
+        .map(([id, v]) => `${id}=${encodeChannelValue(v)}`)
+        .join(',');
+}
+/** A number as a compact token: round to 3 decimals, no trailing zeros. */
+function compactNum(n) {
+    return String(Math.round(n * 1000) / 1000);
+}
+// Quote a token when it would otherwise break tokenization (whitespace, `]`, quotes, empty).
+// The tokenizer has no escape syntax, so embedded double quotes are dropped.
+function token(v) {
+    const s = String(v);
+    if (s === '' || /[\s"\]]/.test(s))
+        return `"${s.replace(/"/g, '')}"`;
+    return s;
+}

package/dist/versions.d.ts

@@ -0,0 +1,17 @@
+export declare const FORMAT_VERSIONS: Readonly<{
+    /** Project / IR document (`ProjectMeta.schemaVersion`) — `migrateProject` brings
+     *  older projects forward, one table step per bump. */
+    irSchema: 11;
+    /** Chunked-streaming manifest (`ChunkManifest.format`) — the loaders gate on it. */
+    chunkManifest: 1;
+    /** Script package (`nilvn.json` `format`) — `checkPackageManifest` gates on it. */
+    package: 1;
+    /** Engine `SaveState.v` — `restoreState` returns false for any other value. */
+    saveState: 2;
+    /** The menu plugin's save-slot wrapper (`SlotPayload.v`). */
+    saveSlot: 1;
+    /** The plugin manifest / runtime contract (`PluginManifest.apiVersion`) —
+     *  `validatePluginManifest` rejects a newer one. */
+    pluginApi: 2;
+}>;
+export type FormatVersions = typeof FORMAT_VERSIONS;

package/dist/versions.js

@@ -0,0 +1,25 @@
+// The compatibility table:
+// every independently-versioned on-disk / on-wire shape in one place, so a
+// reader can see at a glance which numbers exist and which code gates them.
+// Each is bumped ONLY when its own shape changes incompatibly; none is tied to
+// a package's SemVer.
+import { CURRENT_SCHEMA_VERSION } from './ir.js';
+import { CHUNK_MANIFEST_FORMAT } from './chunk.js';
+import { PACKAGE_FORMAT } from './package.js';
+import { PLUGIN_API_VERSION } from './plugin-manifest.js';
+export const FORMAT_VERSIONS = Object.freeze({
+    /** Project / IR document (`ProjectMeta.schemaVersion`) — `migrateProject` brings
+     *  older projects forward, one table step per bump. */
+    irSchema: CURRENT_SCHEMA_VERSION,
+    /** Chunked-streaming manifest (`ChunkManifest.format`) — the loaders gate on it. */
+    chunkManifest: CHUNK_MANIFEST_FORMAT,
+    /** Script package (`nilvn.json` `format`) — `checkPackageManifest` gates on it. */
+    package: PACKAGE_FORMAT,
+    /** Engine `SaveState.v` — `restoreState` returns false for any other value. */
+    saveState: 2,
+    /** The menu plugin's save-slot wrapper (`SlotPayload.v`). */
+    saveSlot: 1,
+    /** The plugin manifest / runtime contract (`PluginManifest.apiVersion`) —
+     *  `validatePluginManifest` rejects a newer one. */
+    pluginApi: PLUGIN_API_VERSION,
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@nilvn/core",
+  "version": "0.14.0",
+  "type": "module",
+  "description": "NilVN shared core — the project document model (IR), command / plugin-manifest schemas, script-package format and serializers",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nilzx/nilvn-engine.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "nilvn",
+    "visual-novel",
+    "adv",
+    "galgame"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.lib.json"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}