@nilvn/core 0.14.0 → 0.15.0

package/dist/commands.js

@@ -123,6 +123,26 @@ export const BUILTIN_COMMANDS = [
             { key: 'target', label: 'cmd.window.target', type: 'string', default: 'dialog', advanced: true },
         ],
     },
+    {
+        name: 'theme',
+        label: 'cmd.theme.label',
+        category: 'stage',
+        icon: '🎨',
+        hint: 'cmd.theme.hint',
+        // The engine accepts ANY token the theme contract names (`--nilvn-<token>`);
+        // the form offers the everyday ones. `[theme reset]` clears the script layer.
+        params: [
+            { key: 'dialog-bg', label: 'cmd.theme.dialogBg', type: 'string' },
+            { key: 'dialog-opacity', label: 'cmd.theme.dialogOpacity', type: 'number' },
+            { key: 'text-color', label: 'cmd.theme.textColor', type: 'string' },
+            { key: 'text-size', label: 'cmd.theme.textSize', type: 'string', advanced: true },
+            { key: 'name-bg', label: 'cmd.theme.nameBg', type: 'string', advanced: true },
+            { key: 'name-color', label: 'cmd.theme.nameColor', type: 'string', advanced: true },
+            { key: 'font', label: 'cmd.theme.font', type: 'string', advanced: true },
+            { key: 'accent', label: 'cmd.theme.accent', type: 'string', advanced: true },
+            { key: 'ui-scale', label: 'cmd.theme.uiScale', type: 'number', advanced: true },
+        ],
+    },
     {
         name: 'textspeed',
         label: 'cmd.textspeed.label',
@@ -174,6 +194,25 @@ export const BUILTIN_COMMANDS = [
         hint: 'cmd.end.hint',
         params: [{ key: 'sec', label: 'cmd.end.sec', type: 'number', default: 1, positional: 0 }],
     },
+    {
+        name: 'ending',
+        label: 'cmd.ending.label',
+        category: 'flow',
+        icon: '🎬',
+        hint: 'cmd.ending.hint',
+        params: [
+            { key: 'id', label: 'cmd.ending.id', type: 'string', default: 'default', positional: 0 },
+            { key: 'sec', label: 'cmd.ending.sec', type: 'number', default: 1, advanced: true },
+        ],
+    },
+    {
+        name: 'title',
+        label: 'cmd.title.label',
+        category: 'flow',
+        icon: '🏠',
+        hint: 'cmd.title.hint',
+        params: [],
+    },
 ];
 export const BUILTIN_COMMAND_MAP = Object.fromEntries(BUILTIN_COMMANDS.map((c) => [c.name, c]));
 export function getCommandSchema(name) {

package/dist/plugin-manifest.d.ts

@@ -1,4 +1,4 @@
-import type { CommandSchema, EffectSchema, ObjectKindSchema, TextEffectDef } from './schema.js';
+import type { CommandSchema, EffectSchema, ObjectKindSchema, ParamSchema, ParamType, TextEffectDef } from './schema.js';
 /** The plugin↔host contract version. A manifest declaring a higher `apiVersion`
  *  than the host supports is rejected (forward-compat is not guaranteed). v1 was
  *  the pre-batch-B `{ name, entry, capabilities }` shape; v2 = this file. */
@@ -24,7 +24,7 @@ export interface PermissionDef {
 /** The closed capability catalog. */
 export declare const PERMISSIONS: readonly PermissionDef[];
 /** A permission id as a manifest writes it (pattern ids carry their suffix). */
-export type Permission = 'stage.read' | 'stage.write' | `stage.layer:${string}` | 'audio.play' | `audio.bus:${string}` | 'audio.capture' | 'vars.read' | 'vars.write' | 'save.slice' | 'session.save' | 'session.settings' | 'session.backlog' | 'session.replay' | 'ui.layer' | 'ui.panel' | 'ui.window' | 'ui.toast' | 'ui.inspector' | 'project.read' | 'project.commit' | 'assets.read' | 'assets.write' | 'fs.pick' | 'fs.project' | `net:${string}` | 'clipboard' | 'timer' | 'ai.text' | 'ai.image' | 'ai.audio' | 'ai.code' | 'ai.context';
+export type Permission = 'stage.read' | 'stage.write' | `stage.layer:${string}` | 'audio.play' | `audio.bus:${string}` | 'audio.capture' | 'vars.read' | 'vars.write' | 'save.slice' | 'session.save' | 'session.settings' | 'session.backlog' | 'session.replay' | 'ui.layer' | 'ui.screen' | 'ui.dialog' | 'storage.local' | 'ui.panel' | 'ui.window' | 'ui.toast' | 'ui.inspector' | 'project.read' | 'project.commit' | 'assets.read' | 'assets.write' | 'fs.pick' | 'fs.project' | `net:${string}` | 'clipboard' | 'timer' | 'ai.text' | 'ai.image' | 'ai.audio' | 'ai.code' | 'ai.context';
 /** Resolve a permission id (exact, or a pattern id with its suffix) to its
  *  catalog entry; undefined for anything outside the catalog. */
 export declare function matchPermission(id: string): PermissionDef | undefined;
@@ -46,6 +46,37 @@ export interface PanelDef {
     /** Free-form descriptor; the plugin renders its own panel body. */
     kind?: string;
 }
+/** One plugin setting (`contributes.config`): a `ParamSchema` minus the command
+ *  positional / required bits, plus a numeric range and who may change it. */
+export interface ConfigFieldSchema extends Omit<ParamSchema, 'positional' | 'required'> {
+    min?: number;
+    max?: number;
+    step?: number;
+    /** `author` (default): set in the config file / the studio, read-only in the
+     *  game. `player`: also a row in the in-game settings panel, persisted per work
+     *  (the author's value is the default). */
+    scope?: 'author' | 'player';
+}
+/** An entry a plugin adds to the in-game system menu or the title page. */
+export interface MenuItemDef {
+    id: string;
+    /** An i18n id resolved through the plugin's `messages`. */
+    label: string;
+    /** Menu entries: show only while `playing` (default) or on every session state. */
+    when?: 'playing' | 'always';
+}
+/** A HUD widget slot. */
+export interface HudDef {
+    id: string;
+    slot?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+/** A field an actor declaration may carry for this plugin. */
+export interface ActorFieldDef {
+    key: string;
+    type: ParamType;
+    /** An i18n id (the studio's actor form). */
+    label?: string;
+}
 /** Contributions per extension point. Every field optional; unknown keys are
  *  tolerated (ignored with a warning) so a newer plugin loads on an older host. */
 export interface PluginContributions {
@@ -57,6 +88,11 @@ export interface PluginContributions {
     effects?: EffectSchema[];
     hooks?: string[];
     saveSlice?: boolean;
+    config?: ConfigFieldSchema[];
+    menuItems?: MenuItemDef[];
+    titleItems?: MenuItemDef[];
+    hud?: HudDef[];
+    actorFields?: ActorFieldDef[];
     panels?: PanelDef[];
     nodeKinds?: string[];
     stageTools?: string[];

package/dist/plugin-manifest.js

@@ -40,6 +40,8 @@ export const PERMISSIONS = [
     { id: 'session.backlog', group: 'session', side: 'engine', status: 'active', description: 'The dialogue backlog and voice replay by ref.' },
     { id: 'session.replay', group: 'session', side: 'engine', status: 'active', description: 'A–B replay segments: list / play / end / seen signals.' },
     { id: 'ui.layer', group: 'ui', side: 'engine', status: 'active', description: 'A host container inside the stage root (removed on dispose).' },
+    { id: 'ui.screen', group: 'ui', side: 'engine', status: 'active', description: 'Full-stage screens over the story, entries in the system menu and on the title page, HUD widgets (the menuItems / titleItems / hud contributions).' },
+    { id: 'ui.dialog', group: 'ui', side: 'engine', status: 'active', description: 'In-engine confirm / alert boxes and toasts (never the browser’s).' },
     { id: 'ui.panel', group: 'ui', side: 'editor', status: 'active', description: 'A manager panel host in the editor.' },
     { id: 'ui.window', group: 'ui', side: 'editor', status: 'active', description: 'A draggable editor window.' },
     { id: 'ui.toast', group: 'ui', side: 'editor', status: 'active', description: 'Editor toasts.' },
@@ -53,6 +55,7 @@ export const PERMISSIONS = [
     { id: 'net:', group: 'system', side: 'host', status: 'reserved', pattern: true, description: 'Network access to one origin (host-mediated; third-party default-deny).' },
     { id: 'clipboard', group: 'system', side: 'host', status: 'reserved', description: 'Clipboard read / write.' },
     { id: 'timer', group: 'system', side: 'engine', status: 'active', description: 'setTimeout / setInterval / requestAnimationFrame, cleared on dispose.' },
+    { id: 'storage.local', group: 'data', side: 'engine', status: 'active', description: 'A key-value store namespaced per work and plugin (async, JSON values) — the engine’s SaveStore.' },
     { id: 'ai.text', group: 'ai', side: 'host', status: 'reserved', description: 'Text generation through the configured provider.' },
     { id: 'ai.image', group: 'ai', side: 'host', status: 'reserved', description: 'Image generation.' },
     { id: 'ai.audio', group: 'ai', side: 'host', status: 'reserved', description: 'Audio / voice generation.' },
@@ -76,6 +79,11 @@ export const EXTENSION_POINTS = [
     { key: 'effects', side: 'engine', status: 'active', version: 1, description: 'Retargetable effects bound to kinds via appliesToKinds.' },
     { key: 'hooks', side: 'engine', status: 'active', version: 1, description: 'Engine hook names the runtime half listens to (introspection; the module is authoritative).' },
     { key: 'saveSlice', side: 'engine', status: 'active', version: 1, description: 'Declares a SaveState.ext slice owned by this plugin.' },
+    { key: 'config', side: 'engine', status: 'active', version: 1, description: 'Plugin settings (ConfigFieldSchema[]): the config file’s [plugins.<id>] table and ctx.config at runtime; scope = player rows also appear in the in-game settings panel and persist per work.' },
+    { key: 'menuItems', side: 'engine', status: 'active', version: 1, description: 'Entries in the in-game system menu (wired with ctx.screen.menuItem; needs ui.screen).' },
+    { key: 'titleItems', side: 'engine', status: 'active', version: 1, description: 'Buttons on the title page (ctx.screen.titleItem; needs ui.screen).' },
+    { key: 'hud', side: 'engine', status: 'active', version: 1, description: 'Persistent widgets in a stage corner while playing (ctx.screen.hud; needs ui.screen).' },
+    { key: 'actorFields', side: 'engine', status: 'active', version: 1, description: 'Fields an actor declaration may carry for this plugin ([actors.<id>] / [actor …]), reached as ctx.actorField(actorId, key).' },
     { key: 'rendererLayers', side: 'engine', status: 'reserved', version: 1, description: 'Named renderer layers.' },
     { key: 'panels', side: 'editor', status: 'active', version: 1, description: 'Manager panels (the editor renders the host; the plugin fills it).' },
     { key: 'nodeKinds', side: 'editor', status: 'active', version: 1, description: 'IR node kinds this plugin owns (forms + inert flag while disabled).' },
@@ -143,6 +151,22 @@ export function validatePluginManifest(m, opts = {}) {
         else if (EXTENSION_POINTS.find((p) => p.key === key).status === 'reserved')
             warnings.push(`extension point "${key}" is reserved — ignored`);
     }
+    const CONFIG_KEY_RE = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+    const seen = new Set();
+    for (const f of m.contributes?.config ?? []) {
+        if (!f || typeof f.key !== 'string' || !CONFIG_KEY_RE.test(f.key))
+            errors.push(`contributes.config: invalid key "${String(f?.key)}"`);
+        else if (seen.has(f.key))
+            errors.push(`contributes.config: duplicate key "${f.key}"`);
+        else
+            seen.add(f.key);
+        if (f && f.scope !== undefined && f.scope !== 'author' && f.scope !== 'player')
+            errors.push(`contributes.config."${String(f.key)}": unknown scope "${String(f.scope)}"`);
+    }
+    for (const a of m.contributes?.actorFields ?? []) {
+        if (!a || typeof a.key !== 'string' || !CONFIG_KEY_RE.test(a.key))
+            errors.push(`contributes.actorFields: invalid key "${String(a?.key)}"`);
+    }
     if (m.activation?.engine && !['eager', 'onCommand', 'manual'].includes(m.activation.engine))
         errors.push(`unknown activation.engine "${m.activation.engine}"`);
     if (m.reload && m.reload !== 'hot' && m.reload !== 'restart')

package/dist/versions.d.ts

@@ -8,7 +8,7 @@ export declare const FORMAT_VERSIONS: Readonly<{
     package: 1;
     /** Engine `SaveState.v` — `restoreState` returns false for any other value. */
     saveState: 2;
-    /** The menu plugin's save-slot wrapper (`SlotPayload.v`). */
+    /** The engine's save-slot wrapper (`SlotPayload.v` — the menu and autosave). */
     saveSlot: 1;
     /** The plugin manifest / runtime contract (`PluginManifest.apiVersion`) —
      *  `validatePluginManifest` rejects a newer one. */

package/dist/versions.js

@@ -17,7 +17,7 @@ export const FORMAT_VERSIONS = Object.freeze({
     package: PACKAGE_FORMAT,
     /** Engine `SaveState.v` — `restoreState` returns false for any other value. */
     saveState: 2,
-    /** The menu plugin's save-slot wrapper (`SlotPayload.v`). */
+    /** The engine's save-slot wrapper (`SlotPayload.v` — the menu and autosave). */
     saveSlot: 1,
     /** The plugin manifest / runtime contract (`PluginManifest.apiVersion`) —
      *  `validatePluginManifest` rejects a newer one. */

package/package.json

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