@nilvn/core 0.16.3 → 0.17.0

package/dist/chunk-build.d.ts

@@ -28,6 +28,16 @@ export interface BuildChunkedOptions {
     /** Command schema registry for serialization (`commandRegistry(manifests)`);
      *  built-ins only when omitted — see SerializeOptions.commands. */
     commands?: Record<string, CommandSchema>;
+    /** A scoped build (the studio's preview of one scene): only these scene ids, in
+     *  project order, go into the package — as ONE chunk, which is also the entry —
+     *  and a jump or choice that leaves the scope routes to the unset landing
+     *  (serialize's non-`crossChunk` mode) instead of naming a label the package
+     *  does not carry. `groups` is ignored when set. Omitted = the whole project. */
+    scenes?: string[];
+    /** Emit `[label anchorLabel]` right before this node (play-from-here). */
+    anchorNodeId?: string;
+    /** The label to inject at `anchorNodeId`; defaults to `__nilvn_here__`. */
+    anchorLabel?: string;
 }
 /** 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.

package/dist/chunk-build.js

@@ -57,10 +57,12 @@ export function sceneTextKeys(nodes, into) {
     }
 }
 export function buildChunkedExport(project, opts) {
-    const sceneOrder = project.scenes.map((s) => s.id);
+    const scoped = opts.scenes ? project.scenes.filter((s) => opts.scenes.includes(s.id)) : project.scenes;
+    const sceneOrder = scoped.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]);
+    const byId = new Map(scoped.map((s) => [s.id, s]));
+    const groups = opts.scenes ? [sceneOrder] : (opts.groups ?? sceneOrder.map((id) => [id]));
+    const anchor = opts.anchorNodeId ? { anchorNodeId: opts.anchorNodeId, ...(opts.anchorLabel ? { anchorLabel: opts.anchorLabel } : {}) } : {};
     // Each group → one chunk. Chunk id = its first scene id (stable, unique).
     const chunks = [];
     const files = [];
@@ -76,7 +78,7 @@ export function buildChunkedExport(project, opts) {
         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 { body, labels, assetRefs } = serializeChunk(project, { scenes: ids, keepKeys: true, crossChunk: !opts.scenes, ...anchor, ...(opts.commands ? { commands: opts.commands } : {}) });
         const scriptChunk = { id: chunkId, body, labels };
         const text = JSON.stringify(scriptChunk);
         const bytes = utf8Len(text);

package/dist/ir.d.ts

@@ -1,6 +1,18 @@
 export type Lang = string;
 /** textKey -> localized string. Values may carry inline markup ({wave:..}, {w:0.5}, {br}). */
 export type TextCatalog = Record<string, string>;
+/** The work's engine configuration — the JSON form of `nilvn.config.toml`,
+ *  section by section (`title`, `ending`, `theme`, `window`, `menu`, `settings`,
+ *  `keys`, `saves`, `choices`, `input`, `preload`, `ui`, `persist`, `strings`,
+ *  `plugins.<id>` …). Core keeps it opaque on purpose: the engine is the one
+ *  source of its meaning (its `CONFIG_SCHEMA` / `checkConfig` validate it and the
+ *  studio's settings forms are generated from that schema), so nothing here
+ *  duplicates the engine's types. Sections the package model carries elsewhere
+ *  (`game.entry` / `game.scripts` / `path` / `actors` / `plugins.use`) do not
+ *  belong in it — the engine drops them with a diagnostic. */
+export interface WorkConfig {
+    [section: string]: unknown;
+}
 export interface Project {
     meta: ProjectMeta;
     actors: Record<string, Actor>;
@@ -18,6 +30,10 @@ export interface Project {
      *  the engine unlocks a segment when normal play passes its end. Optional: older
      *  projects simply have none. */
     replays?: ReplaySegment[];
+    /** The work's engine configuration (see {@link WorkConfig}); travels into the
+     *  script package as `nilvn.json` `config`. Optional: a project without one
+     *  plays with the engine's defaults. Added at schema v12. */
+    config?: WorkConfig;
 }
 /** A node position id: which scene, which node — the timeline's stable locator
  *  (`NodeBase.id` is minted once and survives edits around it). */
@@ -73,8 +89,10 @@ export interface ReplaySegment {
  *  v11: plugin platform v2 — `PluginRef`
  *      is `{ id, version?, config? }` keyed by the plugin's reverse-DNS id; the
  *      migration maps bundled short names (`textfx` → `app.nilvn.textfx`) and keeps
- *      unknown names verbatim (the editor reports them, nothing is dropped). */
-export declare const CURRENT_SCHEMA_VERSION = 11;
+ *      unknown names verbatim (the editor reports them, nothing is dropped).
+ *  v12: `Project.config` — the work's engine configuration (the JSON form of
+ *      nilvn.config.toml), exported as the package's `config`. Pure addition. */
+export declare const CURRENT_SCHEMA_VERSION = 12;
 /** Bring a loaded project up to CURRENT_SCHEMA_VERSION in place (then return it).
  *  Call once on load, after reading from disk. Runs every table step the project
  *  predates, in order, then stamps the current version. */

package/dist/ir.js

@@ -40,8 +40,10 @@ import { resolvePluginId } from './plugins.js';
  *  v11: plugin platform v2 — `PluginRef`
  *      is `{ id, version?, config? }` keyed by the plugin's reverse-DNS id; the
  *      migration maps bundled short names (`textfx` → `app.nilvn.textfx`) and keeps
- *      unknown names verbatim (the editor reports them, nothing is dropped). */
-export const CURRENT_SCHEMA_VERSION = 11;
+ *      unknown names verbatim (the editor reports them, nothing is dropped).
+ *  v12: `Project.config` — the work's engine configuration (the JSON form of
+ *      nilvn.config.toml), exported as the package's `config`. Pure addition. */
+export const CURRENT_SCHEMA_VERSION = 12;
 /** The stable id a ref (of either shape) points at. */
 function refId(r) {
     const raw = r.id ?? r.name;
@@ -152,6 +154,8 @@ const MIGRATIONS = [
             p.plugins = next;
         },
     },
+    // v11 -> v12: `Project.config` (the work's engine configuration). Pure addition
+    // — a project without one plays with the engine's defaults.
 ];
 /** Bring a loaded project up to CURRENT_SCHEMA_VERSION in place (then return it).
  *  Call once on load, after reading from disk. Runs every table step the project

package/dist/package.d.ts

@@ -1,4 +1,4 @@
-import type { Project } from './ir.js';
+import type { Project, WorkConfig } from './ir.js';
 import { type ChunkManifest, type ManifestAsset } from './chunk.js';
 import { type BuildChunkedOptions, type ChunkFile } from './chunk-build.js';
 /** Script-package format version. Bumped only when nilvn.json's shape changes
@@ -49,6 +49,14 @@ export interface PackageManifest {
     textSpeed: number;
     /** Per-work id the runtime namespaces saves / settings by. */
     saveKey: string;
+    /** The work's engine configuration — the JSON form of `nilvn.config.toml`
+     *  (`Project.config`). The engine applies it once the package is open, after
+     *  the asset table is filled, so a skin, logo or background in it resolves by
+     *  ref like any other asset. Optional (a package without one plays with the
+     *  engine's defaults); the sections `nilvn.json` carries itself (`game.entry`
+     *  / `game.scripts` / `path` / `actors` / `plugins.use`) are dropped with a
+     *  diagnostic. Engines before 0.17 ignore the field. */
+    config?: WorkConfig;
     /** The chunk manifest (chunk.ts), embedded as-is: chunk / locale-slice / asset
      *  index + entry label. Wire files (`chunks/**`, `assets/**`) are unchanged. */
     chunks: ChunkManifest;
@@ -74,6 +82,8 @@ export interface BuildPackageOptions extends BuildChunkedOptions {
     textSpeed?: number;
     /** Defaults to the project id, else the title. */
     saveKey?: string;
+    /** Defaults to `project.config`; left out of the manifest when empty. */
+    config?: WorkConfig;
 }
 export interface ScriptPackagePlan {
     /** nilvn.json, with `chunks.assets` still EMPTY — the producer resolves the
@@ -96,5 +106,12 @@ export declare function packageActors(project: Project): Record<string, PackageA
  *  single-file / asset-ZIP shape) plus the manifest fields the shells used to bake
  *  into their bootstraps. Pure, zero-I/O. */
 export declare function buildScriptPackage(project: Project, opts: BuildPackageOptions): ScriptPackagePlan;
+/** Asset refs a work configuration names — a skin, logo, background, music,
+ *  HUD icon or preload entry — found by walking every string in it with the
+ *  same predicate the scene walk uses (`isAssetRef`), so a producer resolves
+ *  them into the package's by-ref table alongside the scenes' assets. Strings
+ *  holding a `{placeholder}` (a layered actor's `src` template) are templates,
+ *  not refs, and are left to the actor table. */
+export declare function configAssetRefs(config: WorkConfig | undefined): string[];
 /** Fill the by-ref asset table (`chunks.assets`). Returns a new manifest. */
 export declare function fillPackageAssets(manifest: PackageManifest, assets: Record<string, ManifestAsset>): PackageManifest;

package/dist/package.js

@@ -8,6 +8,7 @@
 // Pure types + a builder over buildChunkedExport, zero-dep. The editor's four
 // exports (single-file HTML / asset ZIP / chunked ZIP / .nvpk) are this package
 // plus a shell; the engine's `load()` is its one consumer.
+import { isAssetRef } from './serialize.js';
 import { isChunkManifest } from './chunk.js';
 import { buildChunkedExport } from './chunk-build.js';
 /** Script-package format version. Bumped only when nilvn.json's shape changes
@@ -57,12 +58,14 @@ export function packageActors(project) {
  *  single-file / asset-ZIP shape) plus the manifest fields the shells used to bake
  *  into their bootstraps. Pure, zero-I/O. */
 export function buildScriptPackage(project, opts) {
-    // Forward the command registry: without it the chunks serialize plugin commands
-    // against the built-ins alone, and a positional argument (`[move yuki …]`)
-    // degrades to `id=yuki`, which the plugin never reads.
-    const plan = buildChunkedExport(project, { engine: opts.engine, groups: opts.groups, ...(opts.commands ? { commands: opts.commands } : {}) });
+    // The chunk options ride through whole (registry, grouping, a preview's scene
+    // scope and anchor): without the command registry the chunks serialize plugin
+    // commands against the built-ins alone, and a positional argument
+    // (`[move yuki …]`) degrades to `id=yuki`, which the plugin never reads.
+    const plan = buildChunkedExport(project, opts);
     const title = opts.title ?? (project.meta.title || 'NilVN');
     const lang = (opts.lang ?? project.meta.defaultLang);
+    const config = opts.config ?? project.config;
     const manifest = {
         format: PACKAGE_FORMAT,
         title,
@@ -73,10 +76,36 @@ export function buildScriptPackage(project, opts) {
         plugins: opts.plugins ?? project.plugins.map((p) => ({ id: p.id })),
         textSpeed: opts.textSpeed ?? (Number(project.meta.textSpeed) || 40),
         saveKey: opts.saveKey ?? (project.meta.id || project.meta.title || 'nilvn'),
+        ...(config && Object.keys(config).length ? { config } : {}),
         chunks: plan.manifest,
     };
     return { manifest, files: plan.files, assetRefs: plan.assetRefs };
 }
+/** Asset refs a work configuration names — a skin, logo, background, music,
+ *  HUD icon or preload entry — found by walking every string in it with the
+ *  same predicate the scene walk uses (`isAssetRef`), so a producer resolves
+ *  them into the package's by-ref table alongside the scenes' assets. Strings
+ *  holding a `{placeholder}` (a layered actor's `src` template) are templates,
+ *  not refs, and are left to the actor table. */
+export function configAssetRefs(config) {
+    const out = new Set();
+    const walk = (v) => {
+        if (typeof v === 'string') {
+            if (isAssetRef(v) && !v.includes('{'))
+                out.add(v);
+        }
+        else if (Array.isArray(v)) {
+            for (const x of v)
+                walk(x);
+        }
+        else if (v && typeof v === 'object') {
+            for (const x of Object.values(v))
+                walk(x);
+        }
+    };
+    walk(config);
+    return [...out];
+}
 /** Fill the by-ref asset table (`chunks.assets`). Returns a new manifest. */
 export function fillPackageAssets(manifest, assets) {
     return { ...manifest, chunks: { ...manifest.chunks, assets } };

package/dist/versions.d.ts

@@ -1,7 +1,7 @@
 export declare const FORMAT_VERSIONS: Readonly<{
     /** Project / IR document (`ProjectMeta.schemaVersion`) — `migrateProject` brings
      *  older projects forward, one table step per bump. */
-    irSchema: 11;
+    irSchema: 12;
     /** Chunked-streaming manifest (`ChunkManifest.format`) — the loaders gate on it. */
     chunkManifest: 1;
     /** Script package (`nilvn.json` `format`) — `checkPackageManifest` gates on it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nilvn/core",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "type": "module",
   "description": "NilVN shared core — the project document model (IR), command / plugin-manifest schemas, script-package format and serializers",
   "license": "MIT",