@nilvn/core 0.14.0

package/dist/package.js

@@ -0,0 +1,80 @@
+// Script package (.nvs) — the contract core of "a work the engine can load and
+// run on its own". One `nilvn.json`
+// carries everything a shell used to split across index.html / boot.json /
+// manifest.json: work metadata, the actor table, the enabled plugin set, the
+// initial + switchable languages, playback defaults, and the chunk manifest
+// (embedded verbatim, so every ContentLoader keeps reading a ChunkManifest).
+//
+// 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 { isChunkManifest } from './chunk.js';
+import { buildChunkedExport } from './chunk-build.js';
+/** Script-package format version. Bumped only when nilvn.json's shape changes
+ *  incompatibly; the embedded chunk manifest keeps its own `format`. */
+export const PACKAGE_FORMAT = 1;
+/** The package's single entry file, at the package root. */
+export const PACKAGE_MANIFEST_FILE = 'nilvn.json';
+/** Structural check for a parsed nilvn.json — a foreign or truncated file fails
+ *  cleanly here instead of deep inside playback. Does NOT check `format`
+ *  numbers (callers gate those so they can word the mismatch message). */
+export function isPackageManifest(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const m = x;
+    return (typeof m.format === 'number' &&
+        typeof m.title === 'string' &&
+        typeof m.engine === 'string' &&
+        typeof m.lang === 'string' &&
+        Array.isArray(m.languages) &&
+        !!m.actors &&
+        typeof m.actors === 'object' &&
+        Array.isArray(m.plugins) &&
+        typeof m.textSpeed === 'number' &&
+        typeof m.saveKey === 'string' &&
+        isChunkManifest(m.chunks));
+}
+/** Languages the finished work can switch between: the default plus every
+ *  declared language that ships a non-empty catalog. The default comes first. */
+export function packageLanguages(project) {
+    const def = project.meta.defaultLang;
+    const declared = project.meta.languages?.length ? project.meta.languages : [def];
+    const extra = declared.filter((l) => l !== def && Object.keys(project.catalogs[l] ?? {}).length > 0);
+    return [def, ...extra];
+}
+/** The runtime actor table straight from the IR (`name` = the default-language
+ *  display name, falling back to the id). */
+export function packageActors(project) {
+    const cat = project.catalogs[project.meta.defaultLang] ?? {};
+    const out = {};
+    for (const [id, a] of Object.entries(project.actors)) {
+        out[id] = { name: cat[a.nameKey] ?? id, nameKey: a.nameKey, color: a.color, sprites: a.sprites, defaultFace: a.defaultFace, voice: a.voice };
+    }
+    return out;
+}
+/** Build a script package from a project: the chunked script side (one chunk per
+ *  scene by default; `groups` merges scenes — a single group = one chunk, the
+ *  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) {
+    const plan = buildChunkedExport(project, { engine: opts.engine, groups: opts.groups });
+    const title = opts.title ?? (project.meta.title || 'NilVN');
+    const lang = (opts.lang ?? project.meta.defaultLang);
+    const manifest = {
+        format: PACKAGE_FORMAT,
+        title,
+        engine: opts.engine,
+        lang,
+        languages: opts.languages ?? packageLanguages(project),
+        actors: opts.actors ?? packageActors(project),
+        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'),
+        chunks: plan.manifest,
+    };
+    return { manifest, files: plan.files, assetRefs: plan.assetRefs };
+}
+/** 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/plugin-manifest.d.ts

@@ -0,0 +1,146 @@
+import type { CommandSchema, EffectSchema, ObjectKindSchema, 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. */
+export declare const PLUGIN_API_VERSION = 2;
+/** The file a plugin package is rooted at. */
+export declare const PLUGIN_MANIFEST_FILE = "plugin.json";
+/** The `entries.*` sentinel host-registry plugins use: the host's own registry
+ *  supplies the module (the first-party set, or a module the host registered
+ *  itself), nothing is fetched. */
+export declare const BUNDLED_ENTRY = "bundled";
+export type PermissionSide = 'engine' | 'editor' | 'host';
+export type CatalogStatus = 'active' | 'reserved';
+export interface PermissionDef {
+    /** The id a manifest writes; `pattern` ids end in `:` and take a suffix. */
+    id: string;
+    group: string;
+    side: PermissionSide;
+    status: CatalogStatus;
+    pattern?: boolean;
+    /** What the capability object exposes (active) or is reserved for. */
+    description: string;
+}
+/** 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';
+/** 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;
+export interface ExtensionPointDef {
+    key: string;
+    side: 'engine' | 'editor';
+    status: CatalogStatus;
+    /** Schema version of this point's contribution shape. */
+    version: number;
+    description: string;
+}
+/** The keys `contributes` may carry. */
+export declare const EXTENSION_POINTS: readonly ExtensionPointDef[];
+/** A manager panel the editor hosts for the plugin (was `PluginUI`). */
+export interface PanelDef {
+    id: string;
+    /** Tab label — an i18n id resolved through the plugin's `messages`. */
+    label: string;
+    /** Free-form descriptor; the plugin renders its own panel body. */
+    kind?: 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 {
+    commands?: CommandSchema[];
+    textEffects?: TextEffectDef[];
+    /** Object kinds this plugin contributes (declarative mirror of the engine's
+     *  `objectKinds`). Built-in kinds live in BUILTIN_OBJECT_KINDS, not here. */
+    objectKinds?: ObjectKindSchema[];
+    effects?: EffectSchema[];
+    hooks?: string[];
+    saveSlice?: boolean;
+    panels?: PanelDef[];
+    nodeKinds?: string[];
+    stageTools?: string[];
+    lineActions?: string[];
+    objectMenu?: string[];
+    /** Reserved points (see EXTENSION_POINTS) — typed loosely on purpose. */
+    [reserved: string]: unknown;
+}
+export interface PluginActivation {
+    /** `eager` (default): activate when enabled; `onCommand`: at the first
+     *  execution of one of its `contributes.commands`; `manual`: only via
+     *  `engine.enablePlugin`. */
+    engine?: 'eager' | 'onCommand' | 'manual';
+    editor?: 'eager' | 'onPanelOpen';
+}
+/** `plugin.json` — what a plugin tells the hosts so users can enable and use it
+ *  by clicking, and so the hosts can run it with exactly the capabilities it
+ *  declared. Superset of the v1 manifest; `id` is the stable key everywhere
+ *  (`name` is display only). */
+export interface PluginManifest {
+    /** Stable reverse-DNS id (`app.nilvn.textfx`). The enabled-set / `[use]` /
+     *  i18n-namespace key. */
+    id: string;
+    /** Display name: an i18n id resolved through `messages` (`plugin.textfx.name`). */
+    name: string;
+    /** An i18n id (`plugin.textfx.desc`). */
+    description?: string;
+    /** The plugin's own SemVer. */
+    version: string;
+    /** Engine compatibility range (semver.ts subset); absent = any. */
+    engine?: string;
+    /** Editor compatibility range; absent = any. */
+    editor?: string;
+    /** Other plugins this one needs: id → range. Activated first; a missing or
+     *  incompatible dependency keeps this plugin inactive with a diagnostic. */
+    dependencies?: Record<string, string>;
+    contributes?: PluginContributions;
+    /** Capabilities requested from the PERMISSIONS catalog. */
+    permissions?: Permission[];
+    activation?: PluginActivation;
+    /** Hot-plug policy: `hot` (default) = deactivate / dispose / reactivate in
+     *  place; `restart` = the host must reload (IR node shapes, renderer layers…). */
+    reload?: 'hot' | 'restart';
+    /** Module entries relative to plugin.json (`'bundled'` for host-registry
+     *  plugins). No `engine` = a pure editor plugin (the former `editorOnly`); no
+     *  `editor` = a pure runtime plugin. */
+    entries?: {
+        engine?: string;
+        editor?: string;
+    };
+    /** Stylesheets relative to plugin.json, scoped by the host per plugin id. */
+    styles?: string[];
+    /** The plugin's own UI-chrome i18n catalog: `{ lang: { id: text } }`. The hosts
+     *  register it under the `plugin:<id>` namespace. */
+    messages?: Partial<Record<string, Record<string, string>>>;
+    /** Author-facing usage block (one display line per entry): how to trigger
+     *  this plugin in an AuthoringDoc. Tools prefer it over deriving usage from
+     *  `contributes`, which under-reports hook-only / auto plugins. */
+    authorUsage?: string[];
+    /** Plugin contract version this manifest targets (defaults to current). */
+    apiVersion?: number;
+}
+/** `id` grammar: reverse-DNS, ≥ 2 dot-separated labels of `[a-z0-9-]`, each
+ *  starting with a letter. */
+export declare const PLUGIN_ID_RE: RegExp;
+export declare function isPluginId(s: string): boolean;
+export interface ManifestReport {
+    /** Problems that reject the manifest. */
+    errors: string[];
+    /** Tolerated oddities (unknown extension points, reserved permissions…). */
+    warnings: string[];
+}
+export interface ValidateManifestOptions {
+    /** Host versions to check the manifest's ranges against (absent = skip). */
+    engineVersion?: string;
+    editorVersion?: string;
+}
+/** Load-time check of a manifest against the host's catalogs, contract version
+ *  and (optionally) versions. Bundled manifests always pass with no warnings;
+ *  this is the seam that guards third-party plugins. */
+export declare function validatePluginManifest(m: PluginManifest, opts?: ValidateManifestOptions): ManifestReport;
+/** Convenience: only the errors (the shape most call sites need). */
+export declare function manifestErrors(m: PluginManifest, opts?: ValidateManifestOptions): string[];
+/** Whether the manifest ships a runtime (engine) half. */
+export declare function hasEngineHalf(m: PluginManifest): boolean;
+/** Whether the manifest ships an editor half. */
+export declare function hasEditorHalf(m: PluginManifest): boolean;

package/dist/plugin-manifest.js

@@ -0,0 +1,165 @@
+// Plugin manifest v2 (`plugin.json`) — the declarative half of the plugin
+// platform.
+// A manifest says WHAT a plugin contributes (extension points), WHAT it needs
+// (permissions) and HOW the host should run it (activation / reload / entries);
+// the executable halves live in the engine (`entries.engine`) and the editor
+// (`entries.editor`). Host-registry plugins (the first-party set in
+// @nilvn/plugins, or any module a host registers itself) use the `'bundled'`
+// entry sentinel — the hosts resolve those from their own registries.
+//
+// Two catalogs are the host-owned vocabulary a plugin may NOT extend:
+//   EXTENSION_POINTS — the keys `contributes` may carry (unknown keys are
+//                      ignored with a warning: forward-compatible);
+//   PERMISSIONS      — the capability ids `permissions` may request; a plugin
+//                      only ever receives the capability objects it declared AND
+//                      the host granted (the rest are simply `undefined`).
+import { isValidRange, satisfiesRange } from './semver.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. */
+export const PLUGIN_API_VERSION = 2;
+/** The file a plugin package is rooted at. */
+export const PLUGIN_MANIFEST_FILE = 'plugin.json';
+/** The `entries.*` sentinel host-registry plugins use: the host's own registry
+ *  supplies the module (the first-party set, or a module the host registered
+ *  itself), nothing is fetched. */
+export const BUNDLED_ENTRY = 'bundled';
+/** The closed capability catalog. */
+export const PERMISSIONS = [
+    { id: 'stage.read', group: 'stage', side: 'engine', status: 'active', description: 'Read stage objects: hasObject / getProp / getBand / getFace / hasChar / charFace / snapshot.' },
+    { id: 'stage.write', group: 'stage', side: 'engine', status: 'active', description: 'Stage read + every Renderer write verb, applyEffect, and keyframe choreography (playFrames / startLoop / stopLoop).' },
+    { id: 'stage.layer:', group: 'stage', side: 'engine', status: 'reserved', pattern: true, description: 'A named renderer layer (weather / masks).' },
+    { id: 'audio.play', group: 'audio', side: 'engine', status: 'active', description: 'playTrack / stopTrack / stopAllTracks / playSe, channel volumes and voicePlaying.' },
+    { id: 'audio.bus:', group: 'audio', side: 'engine', status: 'reserved', pattern: true, description: 'A specific audio bus.' },
+    { id: 'audio.capture', group: 'audio', side: 'host', status: 'reserved', description: 'Microphone capture (host-mediated).' },
+    { id: 'vars.read', group: 'data', side: 'engine', status: 'active', description: 'Read script variables.' },
+    { id: 'vars.write', group: 'data', side: 'engine', status: 'active', description: 'Read + write script variables.' },
+    { id: 'save.slice', group: 'data', side: 'engine', status: 'active', description: 'Own a SaveState.ext slice (saveState / restoreState are called).' },
+    { id: 'session.save', group: 'session', side: 'engine', status: 'active', description: 'saveState / restoreState / restart, the work save key and build info.' },
+    { id: 'session.settings', group: 'session', side: 'engine', status: 'active', description: 'Text speed, channel volumes, language switching, resolveText.' },
+    { 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.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.' },
+    { id: 'ui.inspector', group: 'ui', side: 'editor', status: 'reserved', description: 'The selected-object inspector panel.' },
+    { id: 'project.read', group: 'project', side: 'editor', status: 'active', description: 'Read the open project (IR) and editor state.' },
+    { id: 'project.commit', group: 'project', side: 'editor', status: 'active', description: 'Mutate the project through the editor (undoable).' },
+    { id: 'assets.read', group: 'project', side: 'editor', status: 'active', description: 'Resolve project assets.' },
+    { id: 'assets.write', group: 'project', side: 'editor', status: 'active', description: 'Import / replace project assets.' },
+    { id: 'fs.pick', group: 'system', side: 'host', status: 'reserved', description: 'Native file picker (host-mediated).' },
+    { id: 'fs.project', group: 'system', side: 'host', status: 'reserved', description: 'Files under the project directory (host-mediated).' },
+    { 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: '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.' },
+    { id: 'ai.code', group: 'ai', side: 'host', status: 'reserved', description: 'Code generation (plugins from natural language).' },
+    { id: 'ai.context', group: 'ai', side: 'host', status: 'reserved', description: 'Read the authoring context handed to AI slots.' },
+];
+/** Resolve a permission id (exact, or a pattern id with its suffix) to its
+ *  catalog entry; undefined for anything outside the catalog. */
+export function matchPermission(id) {
+    for (const p of PERMISSIONS) {
+        if (p.pattern ? id.startsWith(p.id) && id.length > p.id.length : id === p.id)
+            return p;
+    }
+    return undefined;
+}
+/** The keys `contributes` may carry. */
+export const EXTENSION_POINTS = [
+    { key: 'commands', side: 'engine', status: 'active', version: 1, description: 'Script commands `[name …]` (CommandSchema drives the insert form).' },
+    { key: 'textEffects', side: 'engine', status: 'active', version: 1, description: 'Inline text effects `{name:text}`.' },
+    { key: 'objectKinds', side: 'engine', status: 'active', version: 1, description: 'Addressable stage-object kinds.' },
+    { 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: '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).' },
+    { key: 'stageTools', side: 'editor', status: 'active', version: 1, description: 'Stage overlay tools (modal takeovers of the stage).' },
+    { key: 'lineActions', side: 'editor', status: 'active', version: 1, description: 'Buttons on a dialogue line’s action bar.' },
+    { key: 'objectMenu', side: 'editor', status: 'active', version: 1, description: 'Sections in an on-stage object’s context menu.' },
+    { key: 'windows', side: 'editor', status: 'reserved', version: 1, description: 'Draggable editor windows.' },
+    { key: 'insertPalette', side: 'editor', status: 'reserved', version: 1, description: 'Insert-palette categories and entries.' },
+    { key: 'timelineLanes', side: 'editor', status: 'reserved', version: 1, description: 'Extra timeline lanes.' },
+    { key: 'exportSteps', side: 'editor', status: 'reserved', version: 1, description: 'Steps in the export pipeline.' },
+    { key: 'projectMenuItems', side: 'editor', status: 'reserved', version: 1, description: 'Project menu entries.' },
+    { key: 'inspectors', side: 'editor', status: 'reserved', version: 1, description: 'Selected-object inspector sections.' },
+    { key: 'aiSlots', side: 'editor', status: 'reserved', version: 1, description: 'AI slots (roadmap §6).' },
+    { key: 'aiProviders', side: 'editor', status: 'reserved', version: 1, description: 'AI providers (roadmap §6).' },
+];
+const POINT_KEYS = new Set(EXTENSION_POINTS.map((p) => p.key));
+/** `id` grammar: reverse-DNS, ≥ 2 dot-separated labels of `[a-z0-9-]`, each
+ *  starting with a letter. */
+export const PLUGIN_ID_RE = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/;
+export function isPluginId(s) {
+    return PLUGIN_ID_RE.test(s);
+}
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/** Load-time check of a manifest against the host's catalogs, contract version
+ *  and (optionally) versions. Bundled manifests always pass with no warnings;
+ *  this is the seam that guards third-party plugins. */
+export function validatePluginManifest(m, opts = {}) {
+    const errors = [];
+    const warnings = [];
+    if (typeof m.id !== 'string' || !isPluginId(m.id))
+        errors.push(`invalid plugin id "${String(m.id)}" (expected reverse-DNS, e.g. com.example.myfx)`);
+    if (typeof m.name !== 'string' || !m.name)
+        errors.push('missing "name"');
+    if (typeof m.version !== 'string' || !SEMVER_RE.test(m.version))
+        errors.push(`invalid "version" "${String(m.version)}" (expected x.y.z)`);
+    if (m.apiVersion !== undefined && m.apiVersion > PLUGIN_API_VERSION) {
+        errors.push(`requires plugin API v${m.apiVersion}, host is v${PLUGIN_API_VERSION}`);
+    }
+    for (const [field, range] of [['engine', m.engine], ['editor', m.editor]]) {
+        if (range !== undefined && !isValidRange(range))
+            errors.push(`invalid "${field}" range "${range}"`);
+    }
+    if (m.engine && opts.engineVersion && isValidRange(m.engine) && !satisfiesRange(opts.engineVersion, m.engine)) {
+        errors.push(`requires engine ${m.engine}, host is ${opts.engineVersion}`);
+    }
+    if (m.editor && opts.editorVersion && isValidRange(m.editor) && !satisfiesRange(opts.editorVersion, m.editor)) {
+        errors.push(`requires editor ${m.editor}, host is ${opts.editorVersion}`);
+    }
+    for (const [dep, range] of Object.entries(m.dependencies ?? {})) {
+        if (!isPluginId(dep))
+            errors.push(`invalid dependency id "${dep}"`);
+        if (!isValidRange(range))
+            errors.push(`invalid range "${range}" for dependency "${dep}"`);
+    }
+    for (const p of m.permissions ?? []) {
+        const def = matchPermission(p);
+        if (!def)
+            errors.push(`unknown permission "${p}"`);
+        else if (def.status === 'reserved')
+            warnings.push(`permission "${p}" is reserved — no host grants it yet`);
+    }
+    for (const key of Object.keys(m.contributes ?? {})) {
+        if (!POINT_KEYS.has(key))
+            warnings.push(`unknown extension point "${key}" — ignored`);
+        else if (EXTENSION_POINTS.find((p) => p.key === key).status === 'reserved')
+            warnings.push(`extension point "${key}" is reserved — ignored`);
+    }
+    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')
+        errors.push(`unknown reload policy "${m.reload}"`);
+    if (m.entries && !m.entries.engine && !m.entries.editor)
+        warnings.push('"entries" names neither an engine nor an editor module');
+    return { errors, warnings };
+}
+/** Convenience: only the errors (the shape most call sites need). */
+export function manifestErrors(m, opts) {
+    return validatePluginManifest(m, opts).errors;
+}
+/** Whether the manifest ships a runtime (engine) half. */
+export function hasEngineHalf(m) {
+    return !!m.entries?.engine;
+}
+/** Whether the manifest ships an editor half. */
+export function hasEditorHalf(m) {
+    return !!m.entries?.editor;
+}

package/dist/plugins.d.ts

@@ -0,0 +1,26 @@
+import type { CommandSchema } from './schema.js';
+import type { PluginManifest } from './plugin-manifest.js';
+/** The reserved id namespace of the first-party plugins (`app.nilvn.textfx`).
+ *  A plugin under it also answers to its short name everywhere a plugin is named
+ *  (`[use textfx]`, authoring docs, old projects / packages) — see
+ *  {@link resolvePluginId}. Third-party ids must be reverse-DNS under their own
+ *  domain, so a dotless name can only ever mean a first-party short name. */
+export declare const FIRST_PARTY_ID_PREFIX = "app.nilvn.";
+/** A short first-party name → its id (`textfx` → `app.nilvn.textfx`); anything
+ *  with a dot (already an id) is returned as-is. Pure convention, no table: the
+ *  engine aliases the same way when it registers a first-party module. */
+export declare function resolvePluginId(nameOrId: string): string;
+/** Whether `id` lives in the first-party namespace (short name or id). */
+export declare function isFirstPartyId(nameOrId: string): boolean;
+/** The last dotted segment of a plugin id (`app.nilvn.textfx` → `textfx`): the
+ *  first-party plugins' i18n-id prefix (`plugin.textfx.*`) and style-element suffix. */
+export declare function pluginSlug(id: string): string;
+/** The commands a set of manifests contributes, keyed by name. */
+export declare function manifestCommandMap(manifests: readonly PluginManifest[]): Record<string, CommandSchema>;
+/** A serializer / editor command registry: the built-in commands plus every
+ *  command these manifests contribute. Hosts build it once from the manifests
+ *  they know (the first-party set and any third-party ones) and pass it to
+ *  `serializeChunk` / `buildScriptPackage` so plugin commands round-trip with the
+ *  correct positional / named args. Enabled-agnostic on
+ *  purpose: round-trip is a document concern, independent of the toggled set. */
+export declare function commandRegistry(manifests: readonly PluginManifest[]): Record<string, CommandSchema>;

package/dist/plugins.js

@@ -0,0 +1,42 @@
+// Plugin id conventions and manifest-derived registries — the parts of the plugin
+// platform that are CONTRACT, not inventory. Which plugins exist is not core's
+// business: the first-party set (manifests + runtime modules + messages) lives in
+// @nilvn/plugins, third-party ones in their own packages. Core only knows the id
+// grammar, the reserved first-party namespace, and how to derive lookup tables
+// from whatever manifests a host hands it.
+import { BUILTIN_COMMAND_MAP } from './commands.js';
+/** The reserved id namespace of the first-party plugins (`app.nilvn.textfx`).
+ *  A plugin under it also answers to its short name everywhere a plugin is named
+ *  (`[use textfx]`, authoring docs, old projects / packages) — see
+ *  {@link resolvePluginId}. Third-party ids must be reverse-DNS under their own
+ *  domain, so a dotless name can only ever mean a first-party short name. */
+export const FIRST_PARTY_ID_PREFIX = 'app.nilvn.';
+/** A short first-party name → its id (`textfx` → `app.nilvn.textfx`); anything
+ *  with a dot (already an id) is returned as-is. Pure convention, no table: the
+ *  engine aliases the same way when it registers a first-party module. */
+export function resolvePluginId(nameOrId) {
+    return nameOrId.includes('.') ? nameOrId : FIRST_PARTY_ID_PREFIX + nameOrId;
+}
+/** Whether `id` lives in the first-party namespace (short name or id). */
+export function isFirstPartyId(nameOrId) {
+    return resolvePluginId(nameOrId).startsWith(FIRST_PARTY_ID_PREFIX);
+}
+/** The last dotted segment of a plugin id (`app.nilvn.textfx` → `textfx`): the
+ *  first-party plugins' i18n-id prefix (`plugin.textfx.*`) and style-element suffix. */
+export function pluginSlug(id) {
+    const i = id.lastIndexOf('.');
+    return i < 0 ? id : id.slice(i + 1);
+}
+/** The commands a set of manifests contributes, keyed by name. */
+export function manifestCommandMap(manifests) {
+    return Object.fromEntries(manifests.flatMap((m) => (m.contributes?.commands ?? []).map((c) => [c.name, c])));
+}
+/** A serializer / editor command registry: the built-in commands plus every
+ *  command these manifests contribute. Hosts build it once from the manifests
+ *  they know (the first-party set and any third-party ones) and pass it to
+ *  `serializeChunk` / `buildScriptPackage` so plugin commands round-trip with the
+ *  correct positional / named args. Enabled-agnostic on
+ *  purpose: round-trip is a document concern, independent of the toggled set. */
+export function commandRegistry(manifests) {
+    return { ...BUILTIN_COMMAND_MAP, ...manifestCommandMap(manifests) };
+}

package/dist/schema.d.ts

@@ -0,0 +1,73 @@
+export type ParamType = 'string' | 'number' | 'boolean' | 'enum' | 'asset:bg' | 'asset:bgm' | 'asset:se' | 'asset:sprite' | 'actor' | 'face' | 'color' | 'expr';
+export interface ParamOption {
+    value: string;
+    label: string;
+}
+export interface ParamSchema {
+    key: string;
+    label: string;
+    type: ParamType;
+    required?: boolean;
+    default?: string | number | boolean;
+    /** Choices when type === 'enum'. */
+    options?: ParamOption[];
+    /**
+     * When set, this param serializes to a positional DSL argument at the given index
+     * (e.g. [char yuki happy] => id at 0, face at 1). Otherwise it serializes as key=value.
+     */
+    positional?: number;
+    /** Tuck behind an "advanced" disclosure in the editor. */
+    advanced?: boolean;
+}
+export type CommandCategory = 'stage' | 'audio' | 'fx' | 'flow' | 'text';
+export interface CommandSchema {
+    name: string;
+    label: string;
+    category: CommandCategory;
+    /** One-line help shown in the editor. */
+    hint?: string;
+    icon?: string;
+    params: ParamSchema[];
+}
+export interface TextEffectDef {
+    name: string;
+    label?: string;
+    preview?: string;
+}
+/** Renderable object kind — what the editor needs to label/group stage objects.
+ *  The transform schema (x/y/scale/rotation/opacity/zIndex/visible) is engine-owned
+ *  and not mirrored here; the editor only addresses objects, never their transform. */
+export interface ObjectKindSchema {
+    id: string;
+    /** Display label, a t() key. */
+    label: string;
+    /** Whether the kind exposes the transform schema (animatable). */
+    transformable: boolean;
+    /** Emoji shown beside on-stage instances of this kind in the palette. */
+    icon?: string;
+}
+/** Built-in kinds, mirroring the engine's BUILTIN_KINDS. `character` is per-actor
+ *  (the palette shows actor names), `camera`/`screen` are singletons. */
+export declare const BUILTIN_OBJECT_KINDS: ObjectKindSchema[];
+/** A retargetable effect a plugin contributes, bound to kinds via `appliesToKinds`
+ *  (matching the engine's static binding). Authors never insert an effect directly —
+ *  they insert the `command` that applies it; this schema tells the editor
+ *  how to offer the effect for an on-stage object and which CommandNode to produce. */
+export interface EffectSchema {
+    name: string;
+    /** Display label, a t() key. Used as the menu entry unless `fanout` is set. */
+    label: string;
+    hint?: string;
+    icon?: string;
+    /** Kinds this effect can target. */
+    appliesToKinds: string[];
+    /** The command name that applies this effect (its CommandSchema drives the form). */
+    command: string;
+    /** Per-kind params written onto the inserted command to point it at the chosen
+     *  object. The sentinel '$id' is replaced with the object's instance id; a kind
+     *  absent here (e.g. a singleton with an implicit default) targets implicitly. */
+    targetParams?: Record<string, Record<string, string>>;
+    /** Name of an enum param to expand into one object-section entry per option
+     *  (e.g. pose → hop/nod/shake/swing). The chosen value is written to that param. */
+    fanout?: string;
+}

package/dist/schema.js

@@ -0,0 +1,15 @@
+// Declarative command & plugin schema — drives the editor UI so built-in commands and
+// third-party plugin commands are edited the same way. Built-in schemas: commands.ts.
+/** Built-in kinds, mirroring the engine's BUILTIN_KINDS. `character` is per-actor
+ *  (the palette shows actor names), `camera`/`screen` are singletons. */
+export const BUILTIN_OBJECT_KINDS = [
+    { id: 'character', label: 'objectKind.character', transformable: true, icon: '🧍' },
+    { id: 'camera', label: 'objectKind.camera', transformable: true, icon: '🎥' },
+    { id: 'screen', label: 'objectKind.screen', transformable: false, icon: '🖥' },
+    // UI windows — today the built-in `window:dialog` singleton (the dialogue box);
+    // the future ui-kit plugin contributes more instances through the same kind path.
+    { id: 'window', label: 'objectKind.window', transformable: true, icon: '🪟' },
+];
+// The plugin manifest (v2) and its capability / extension-point catalogs live in
+// plugin-manifest.ts; the command / effect / kind schemas above are what
+// a manifest's `contributes` carries.

package/dist/screenplay-format.d.ts

@@ -0,0 +1,8 @@
+export interface ScreenplayFormatOptions {
+    /** Target quote style for body text. Default `"` (owner call 2026-07-21);
+     *  `“”` / `「」` cater to Simplified-Chinese / Japanese typesetting habits. */
+    quoteStyle?: '"' | '“”' | '「」';
+    /** Target ellipsis form for body text. Default `……` (CJK convention). */
+    ellipsis?: '……' | '...';
+}
+export declare function formatScreenplay(text: string, opts?: ScreenplayFormatOptions): string;