narraleaf-studio 0.9.0 → 1.1.0

package/README.md

@@ -1,119 +1,119 @@
-# narraleaf-studio
-
-TypeScript declarations for the [NarraLeaf Studio](https://github.com/NarraLeaf/NarraLeaf-Studio)
-plugin API.
-
-This package contains **types only**. Studio itself supplies the implementation
-at load time through an import map — there is no runtime code here.
-
-```bash
-yarn add -D narraleaf-studio
-```
-
-## Usage
-
-```ts
-// Studio entry — runs in the editor
-import { definePlugin } from "narraleaf-studio/plugin";
-
-export default definePlugin({
-    setup(app) {
-        app.services.blueprintNodes.registerMany(myNodes());
-        app.services.ui.notifications.info(`${app.manifest.name} loaded`);
-    },
-});
-```
-
-```ts
-// Runtime entry — runs inside the game
-import { defineRuntimePlugin } from "narraleaf-studio/runtime";
-
-export default defineRuntimePlugin({
-    setup(app) {
-        app.game.blueprintNodes.registerMany(myNodes());
-    },
-});
-```
-
-| Subpath                    | Surface                                                          |
-| -------------------------- | ---------------------------------------------------------------- |
-| `narraleaf-studio/plugin`  | Editor: `definePlugin`, `PluginApp`, `PluginServices`, `ui`       |
-| `narraleaf-studio/runtime` | Game: `defineRuntimePlugin`, `RuntimePluginApp`                   |
-
-The two are physically isolated at runtime. Importing `narraleaf-studio/plugin`
-from a runtime entry throws — the runtime host has no Studio services.
-
-## Tests
-
-`narraleaf-studio/plugin` also carries the **test protocol** (`TestDefinition` and
-everything it references, plus `TEST_PROTOCOL_VERSION`): checks an author runs
-against their own game from Studio's Run ▸ Test, contributed through
-`app.services.tests`. Nothing to do with your plugin's own unit tests.
-
-```ts
-app.services.tests.register({
-    id: "acme.qa-pack.scene-names",   // declare it in contributes.tests
-    title: { text: "Scenes are named" },
-    presentation: "headless",
-    requires: ["project.read"],
-    async run(ctx) { /* … */ return { status: "passed" }; },
-});
-```
-
-The contract — declaration, capabilities, who may claim which verdict, the
-game-session lifecycle — is
-[`docs/plugin-test-protocol.md`](https://github.com/NarraLeaf/NarraLeaf-Studio/blob/master/docs/plugin-test-protocol.md).
-
-`TEST_PROTOCOL_VERSION` is a compile-time constant; import it with `import type`
-and read the host's own version from `app.services.tests.protocolVersion`.
-
-## You must mark these external
-
-Both specifiers have to be `external` in your bundler. Studio resolves them (and
-`react`, `react-dom`) through an import map, so bundling them produces a second,
-broken React instance and a plugin that fails to load.
-
-```js
-// esbuild
-external: [
-    "narraleaf-studio/plugin",
-    "narraleaf-studio/runtime",
-    "react",
-    "react-dom",
-    "react-dom/client",
-    "react/jsx-runtime",
-]
-```
-
-If you forget, this package's stub throws at import with a message saying so.
-
-## How these types are produced
-
-Generated directly from Studio's source by `packages/plugin-types/build.mjs`,
-not written by hand:
-
-| Output            | Generated from                                                   |
-| ----------------- | ---------------------------------------------------------------- |
-| `dist/plugin.d.ts`  | `src/renderer/plugin/index.ts`                                   |
-| `dist/runtime.d.ts` | `src/renderer/lib/ui-editor/runtime/plugins/runtimePluginApi.ts` |
-
-Only what those entry points explicitly export is public. The build fails if the
-generated declarations do not typecheck on their own, so a release cannot ship a
-bundle that does not compile.
-
-## Versioning
-
-This package versions independently of Studio: it changes when the plugin API
-changes, which is far less often than the app ships. Studio does not yet enforce
-a compatibility range at install time, so treat a major bump as "recompile your
-plugin and check it still typechecks".
-
-## Getting started
-
-See the plugin authoring guide in the
-[NarraLeaf/Plugins](https://github.com/NarraLeaf/Plugins) registry, which has a
-working starter template.
-
-## License
-
-MPL-2.0
+# narraleaf-studio
+
+TypeScript declarations for the [NarraLeaf Studio](https://github.com/NarraLeaf/NarraLeaf-Studio)
+plugin API.
+
+This package contains **types only**. Studio itself supplies the implementation
+at load time through an import map — there is no runtime code here.
+
+```bash
+yarn add -D narraleaf-studio
+```
+
+## Usage
+
+```ts
+// Studio entry — runs in the editor
+import { definePlugin } from "narraleaf-studio/plugin";
+
+export default definePlugin({
+    setup(app) {
+        app.services.blueprintNodes.registerMany(myNodes());
+        app.services.ui.notifications.info(`${app.manifest.name} loaded`);
+    },
+});
+```
+
+```ts
+// Runtime entry — runs inside the game
+import { defineRuntimePlugin } from "narraleaf-studio/runtime";
+
+export default defineRuntimePlugin({
+    setup(app) {
+        app.game.blueprintNodes.registerMany(myNodes());
+    },
+});
+```
+
+| Subpath                    | Surface                                                          |
+| -------------------------- | ---------------------------------------------------------------- |
+| `narraleaf-studio/plugin`  | Editor: `definePlugin`, `PluginApp`, `PluginServices`, `ui`       |
+| `narraleaf-studio/runtime` | Game: `defineRuntimePlugin`, `RuntimePluginApp`                   |
+
+The two are physically isolated at runtime. Importing `narraleaf-studio/plugin`
+from a runtime entry throws — the runtime host has no Studio services.
+
+## Tests
+
+`narraleaf-studio/plugin` also carries the **test protocol** (`TestDefinition` and
+everything it references, plus `TEST_PROTOCOL_VERSION`): checks an author runs
+against their own game from Studio's Run ▸ Test, contributed through
+`app.services.tests`. Nothing to do with your plugin's own unit tests.
+
+```ts
+app.services.tests.register({
+    id: "acme.qa-pack.scene-names",   // declare it in contributes.tests
+    title: { text: "Scenes are named" },
+    presentation: "headless",
+    requires: ["project.read"],
+    async run(ctx) { /* … */ return { status: "passed" }; },
+});
+```
+
+The contract — declaration, capabilities, who may claim which verdict, the
+game-session lifecycle — is
+[`docs/plugin-test-protocol.md`](https://github.com/NarraLeaf/NarraLeaf-Studio/blob/master/docs/plugin-test-protocol.md).
+
+`TEST_PROTOCOL_VERSION` is a compile-time constant; import it with `import type`
+and read the host's own version from `app.services.tests.protocolVersion`.
+
+## You must mark these external
+
+Both specifiers have to be `external` in your bundler. Studio resolves them (and
+`react`, `react-dom`) through an import map, so bundling them produces a second,
+broken React instance and a plugin that fails to load.
+
+```js
+// esbuild
+external: [
+    "narraleaf-studio/plugin",
+    "narraleaf-studio/runtime",
+    "react",
+    "react-dom",
+    "react-dom/client",
+    "react/jsx-runtime",
+]
+```
+
+If you forget, this package's stub throws at import with a message saying so.
+
+## How these types are produced
+
+Generated directly from Studio's source by `packages/plugin-types/build.mjs`,
+not written by hand:
+
+| Output            | Generated from                                                   |
+| ----------------- | ---------------------------------------------------------------- |
+| `dist/plugin.d.ts`  | `src/renderer/plugin/index.ts`                                   |
+| `dist/runtime.d.ts` | `src/renderer/lib/ui-editor/runtime/plugins/runtimePluginApi.ts` |
+
+Only what those entry points explicitly export is public. The build fails if the
+generated declarations do not typecheck on their own, so a release cannot ship a
+bundle that does not compile.
+
+## Versioning
+
+This package versions independently of Studio: it changes when the plugin API
+changes, which is far less often than the app ships. Studio does not yet enforce
+a compatibility range at install time, so treat a major bump as "recompile your
+plugin and check it still typechecks".
+
+## Getting started
+
+See the plugin authoring guide in the
+[NarraLeaf/Plugins](https://github.com/NarraLeaf/Plugins) registry, which has a
+working starter template.
+
+## License
+
+MPL-2.0

package/dist/_api.d.ts

@@ -674,6 +674,11 @@ type StoryActionPayload = {
 	 * arm's - it builds the clip, names it and reveals it. Revealing is still not playing: the
 	 * element is on screen holding its first frame, and `/play` is what runs it.
 	 *
+	 * A `play` carrying {@link assetId} is the one-row cutscene: it builds the clip, names it,
+	 * reveals it and runs it to the end. Without one, `play` runs a clip an earlier row put on
+	 * stage and leaves its visibility alone. No document needs migrating for this: a `play` row
+	 * could always hold an asset, and one that did now does what it says.
+	 *
 	 * Additive: the four transport operations and `timeMs` are new in A3, and no document
 	 * written before them carries either, so no schema bump.
 	 */
@@ -2109,6 +2114,21 @@ type PluginContributes = {
 	 * capability to consent to at install time.
 	 */
 	tests?: string[];
+	/**
+	 * Save ids the plugin keeps for its own bookkeeping - a quick-save slot, a checkpoint - rather
+	 * than slots a player chose.
+	 *
+	 * The game leaves them out of `List Saves`, and so out of every save screen built on it, the way
+	 * it leaves out its own autosave ring. Nothing else changes for them: the plugin still writes,
+	 * loads and finds them through `app.game.saves` (whose `listIds` is the raw store listing and
+	 * still includes them), and the explicit-id save nodes - `Load Save`, `Delete Save`, the
+	 * `Get Save` readers - take them like any other id.
+	 *
+	 * Prefixed with the plugin id like the type lists above, so a plugin can only reserve ids in its
+	 * own namespace and can never hide a slot the author's own `Save Game` wrote. That is also why it
+	 * derives no install permission: it reaches nothing the plugin did not already own.
+	 */
+	reservedSaveIds?: string[];
 	/**
 	 * Capability domains the `runtime` entry may use. Each maps 1:1 onto a
 	 * namespace on `app.game`, and an undeclared domain is absent from that
@@ -2172,9 +2192,29 @@ type PluginContributes = {
 	 */
 	network?: string[];
 };
+/**
+ * The plugin's name and description in one editor language. Either may be left out, and the plain
+ * manifest field is shown in its place.
+ */
+export type PluginManifestLocalizedText = {
+	name?: string;
+	description?: string;
+};
+/**
+ * `name` and `description` per editor locale, keyed by the exact code Studio's language setting
+ * stores (`zh`, `ja`, or a code a language pack adds). There is no region matching: an entry under
+ * `zh-CN` is never shown, because no Studio locale is called that.
+ */
+export type PluginManifestLocalized = Record<string, PluginManifestLocalizedText>;
 export type PluginManifestV2 = Omit<PluginIdentity, "id" | "name" | "version"> & Required<Pick<PluginIdentity, "id" | "name" | "version">> & {
 	manifestVersion: typeof PluginManifestVersion;
 	description?: string;
+	/**
+	 * Translations of `name` and `description`, shown wherever Studio names the plugin to an author
+	 * whose editor is set to that language. The plain fields stay the plugin's identity: command
+	 * lines, project files and built games name it by them.
+	 */
+	localized?: PluginManifestLocalized;
 	/**
 	 * Package-relative path to the thumbnail shown beside the plugin's name in
 	 * the Launcher list. Square, at most 512x512, and one of the extensions in
@@ -2565,6 +2605,21 @@ type UIDocument = {
 	 * `inputAction.ts`.
 	 */
 	actions?: Record<string, UIInputActionDef>;
+	/**
+	 * The page the game starts on, by id.
+	 *
+	 * Absent means the page carrying `MAIN_APP_SURFACE_ID` - the id a new document gives its first
+	 * page, and the only entry a document had before this field existed - so a document whose author
+	 * never moved the entry stays exactly as short as it was. Read only through `resolveEntrySurface`
+	 * (`entrySurface.ts`), which also says what a pointer that has lost its page falls back to.
+	 *
+	 * A pointer rather than an id swap: a page's id is what its blueprints are filed under and what
+	 * every `Go Page` names, so making another page the entry must not change which id it has.
+	 *
+	 * Carries no schema bump, for the reason `actions` and `structs` did not: absence already means a
+	 * defined answer, so a document written before this field reads correctly without one.
+	 */
+	entrySurfaceId?: UISurfaceId;
 	meta?: UIDocumentMeta;
 };
 type UIDocumentMeta = {
@@ -3006,6 +3061,7 @@ declare const en: {
 			readonly welcome: "Open Welcome";
 			readonly docs: "Documentation";
 			readonly feedback: "Send Feedback";
+			readonly exportLogs: "Export Logs\u2026";
 			readonly about: "About {name}";
 		};
 	};
@@ -4228,6 +4284,10 @@ declare const en: {
 					readonly one: "{count} more waiting";
 					readonly other: "{count} more waiting";
 				};
+				readonly repeated: {
+					readonly one: "{count} time";
+					readonly other: "{count} times";
+				};
 			};
 			readonly background: {
 				readonly command: "Set background image\u2026";
@@ -4696,6 +4756,7 @@ declare const en: {
 					readonly localizationFind: "Find in Translations";
 					readonly voiceFind: "Find in Voice-over";
 					readonly lintFind: "Find in Problems";
+					readonly blueprintOverviewFind: "Find in Blueprint Overview";
 					readonly run: {
 						readonly stop: "Stop the Run";
 					};
@@ -5335,6 +5396,7 @@ declare const en: {
 			readonly scopedTo: "Actions for {name}";
 			readonly addStarred: "Add to starred";
 			readonly removeStarred: "Remove from starred";
+			readonly starredEmpty: "Starred commands are listed first in the \u201C/\u201D menu.";
 		};
 		readonly music: {
 			readonly missingAudio: "Missing audio";
@@ -5899,8 +5961,8 @@ declare const en: {
 			readonly kindExpression: "Expression";
 			readonly expressionPlaceholder: "gold >= 100 && !met";
 			readonly expressionVariables: "In scope: {names}";
-			readonly opIsOn: "is on";
-			readonly opIsOff: "is off";
+			readonly opIsTrue: "is true";
+			readonly opIsFalse: "is false";
 			readonly opEquals: "equals";
 			readonly opNotEquals: "does not equal";
 			readonly opGreaterThan: "is greater than";
@@ -6028,7 +6090,7 @@ declare const en: {
 			};
 			readonly play: {
 				readonly label: "Play";
-				readonly detail: "Play a video";
+				readonly detail: "Play a video on stage, or a video from the asset library";
 			};
 			readonly front: {
 				readonly label: "Bring to Front";
@@ -7643,7 +7705,6 @@ declare const en: {
 			readonly collapse: "Collapse side panel";
 		};
 		readonly canvas: {
-			readonly addLayer: "Add layer";
 			readonly selectLayer: "Select a layer on the left.";
 			readonly previewUnavailable: "Preview unavailable";
 			readonly unknownNode: "Unknown node";
@@ -7877,6 +7938,45 @@ declare const en: {
 				readonly other: "Already run by {count} layers";
 			};
 		};
+		readonly layerTemplates: {
+			readonly heading: "New layer";
+			readonly description: "Start from a template or from a blank layer.";
+			readonly listLabel: "Layer templates";
+			readonly blank: {
+				readonly title: "Blank layer";
+				readonly description: "An empty canvas, or one of your own scripts.";
+			};
+			readonly library: {
+				readonly title: "More templates";
+				readonly description: "Browse every template for this blueprint by category.";
+			};
+		};
+		readonly templateLibrary: {
+			readonly title: "Template library";
+			readonly open: "Add from template library";
+			readonly all: "All";
+			readonly categoriesLabel: "Categories";
+			readonly search: "Search templates";
+			readonly emptyFiltered: "No templates match.";
+			readonly empty: "No templates suit this blueprint.";
+			readonly add: "Add";
+			readonly back: "Back";
+			readonly openDetail: "Show details";
+			readonly choicesHeading: "To choose after adding";
+			readonly choicesNone: "Runs as it is once added.";
+			readonly previewLabel: "Graph preview";
+			readonly category: {
+				readonly pageFlow: "Page flow";
+				readonly navigation: "Navigation";
+				readonly game: "Game";
+				readonly settings: "Settings";
+				readonly audio: "Audio";
+				readonly motion: "Motion";
+				readonly keys: "Keys";
+				readonly window: "Window";
+				readonly display: "Display";
+			};
+		};
 		readonly owner: {
 			readonly global: "Global";
 			readonly storyAction: "Story Action";
@@ -7980,6 +8080,7 @@ declare const en: {
 			readonly select: "Select element";
 			readonly selectNamed: "Select element {name}";
 			readonly unbound: "Unbound";
+			readonly missing: "Missing element";
 		};
 		readonly pin: {
 			readonly addInput: "Add input pin";
@@ -9046,9 +9147,43 @@ declare const en: {
 			readonly getPlaytime: "Get Playtime";
 			readonly getTotalPlaytime: "Get Total Playtime";
 		};
+		readonly nodeDescription: {
+			readonly compareEqual: "True when A and B are the same value of the same type. The number 1 and the text \"1\" are not equal.";
+			readonly compareNotEqual: "True when A and B differ in value or in type. The number 1 and the text \"1\" count as different.";
+			readonly compareGreaterThan: "True when A is greater than B. Both sides are compared as numbers; a side that cannot be read as a number gives false.";
+			readonly compareGreaterThanOrEqual: "True when A is greater than or equal to B. Both sides are compared as numbers; a side that cannot be read as a number gives false.";
+			readonly compareLessThan: "True when A is less than B. Both sides are compared as numbers; a side that cannot be read as a number gives false.";
+			readonly compareLessThanOrEqual: "True when A is less than or equal to B. Both sides are compared as numbers; a side that cannot be read as a number gives false.";
+			readonly mathEqual: "True when A and B are the same number. Both sides are read as numbers first, so the text \"1\" equals the number 1.";
+			readonly mathNotEqual: "True when A and B are different numbers. Both sides are read as numbers first, so the text \"1\" and the number 1 count as equal.";
+			readonly flowReturn: "Stops the current run here. Nothing after it runs, including the remaining outputs of a Sequence. Gives back no value; to give one back, use Return Value, or Fn Return inside a function.";
+			readonly returnValue: "Gives the value back as the result and ends the run. Used where a blueprint has to produce a value, such as a Blueprint Value.";
+			readonly appBoot: "Runs once each time the game starts, after the first screen is showing, and does not hold that screen back. On Game Ready has already run by then. In Dev Mode it runs again after every reload.";
+			readonly gameReady: "Runs when the game is ready, before any story starts and before the first screen shows; the screen waits for it to finish. Runs before App Boot, and can run again when a game is started or loaded.";
+			readonly goBack: "Closes the current page and returns to the page beneath it. On the bottom page it does nothing.";
+		};
 		readonly live: {
 			readonly nodeClaimed: "{name} is editing this node";
 		};
+		readonly overview: {
+			readonly title: "Blueprint Overview";
+			readonly count: {
+				readonly one: "{count} blueprint";
+				readonly other: "{count} blueprints";
+			};
+			readonly noBlueprints: "No blueprints";
+			readonly search: "Search blueprints";
+			readonly noMatches: "No blueprints match \u201C{query}\u201D.";
+			readonly nodes: {
+				readonly one: "{count} node";
+				readonly other: "{count} nodes";
+			};
+			readonly group: {
+				readonly project: "Project";
+				readonly componentCaption: "Component";
+				readonly storyCaption: "Story";
+			};
+		};
 	};
 	readonly characters: {
 		readonly errors: {
@@ -9376,6 +9511,7 @@ declare const en: {
 				readonly addCreate: "Create action";
 				readonly removeAction: "Stop answering {name}";
 				readonly answer: "Answer {name}";
+				readonly reveal: "Show {name} in Input Actions";
 				readonly bubble: "After it fires";
 				readonly bubbleStop: "Intercept";
 				readonly bubbleContinue: "Continue";
@@ -9402,9 +9538,25 @@ declare const en: {
 			readonly uiElement: "UI Element";
 			readonly linkedComponent: "Linked Component";
 		};
+		readonly interactionSound: {
+			readonly title: "Sound";
+			readonly hover: "Hover";
+			readonly hoverTip: "Plays when the pointer moves onto the element, on the SFX track unless its options name another. Of nested elements with a hover sound, only the innermost one plays.";
+			readonly click: "Click";
+			readonly clickTip: "Plays when the element is clicked, on the SFX track unless its options name another. Of nested elements with a click sound, only the innermost one plays.";
+			readonly none: "No sound";
+			readonly options: "Playback options";
+			readonly summary: "Volume {volume} \u00B7 {track}";
+			readonly volume: "Volume";
+			readonly track: "Track";
+			readonly chooseHover: "Choose hover sound";
+			readonly chooseClick: "Choose click sound";
+			readonly missing: "Missing sound";
+		};
 		readonly linkedComponent: {
 			readonly missing: "Missing component";
 			readonly info: "Linked instance. Only its params and its position, size and rotation can be changed before unlinking.";
+			readonly reveal: "Show in Component Library";
 		};
 		readonly componentParams: {
 			readonly title: "Params";
@@ -9853,6 +10005,10 @@ declare const en: {
 			readonly string: "String";
 			readonly json: "JSON";
 		};
+		readonly value: {
+			readonly true: "True";
+			readonly false: "False";
+		};
 		readonly row: {
 			readonly nameAria: "Variable name";
 			readonly defaultPlaceholder: "default";
@@ -9932,6 +10088,7 @@ declare const en: {
 			readonly duplicateSurface: "Duplicate {label}";
 			readonly copySurface: "Copy {label}";
 			readonly pasteSurface: "Paste interface";
+			readonly setEntryPage: "Set as Entry Page";
 			readonly deleteSurface: "Delete {label}";
 			readonly surfaceActions: "{label} actions";
 			readonly deleteConfirm: "Delete {label}?";
@@ -9949,6 +10106,7 @@ declare const en: {
 		};
 		readonly history: {
 			readonly moveSurface: "move interface {name}";
+			readonly setEntryPage: "set entry page {name}";
 		};
 		readonly inputActions: {
 			readonly title: "Input Actions";
@@ -10067,6 +10225,8 @@ declare const en: {
 			readonly layerFallback: "Layer";
 			readonly openComponent: "Open component";
 			readonly unlinkComponent: "Unlink component";
+			readonly openComponentNamed: "Open component {name}";
+			readonly openPageNamed: "Open page {name}";
 		};
 		readonly zoom: {
 			readonly label: "Zoom";
@@ -10272,8 +10432,8 @@ declare const en: {
 			readonly disableItalic: "Disable italic";
 		};
 		readonly localization: {
-			readonly title: "Localization";
-			readonly textKey: "Text key";
+			readonly translationKey: "Translation key";
+			readonly noSourceLanguage: "The project has no source language";
 			readonly none: "None";
 			readonly createKey: "Create new key\u2026";
 			readonly createKeyTitle: "New localization key";
@@ -11779,6 +11939,12 @@ declare const en: {
 				readonly label: "About";
 				readonly tooltip: "About NarraLeaf Studio";
 			};
+			readonly exportLogs: {
+				readonly label: "Export Logs\u2026";
+				readonly tooltip: "Save all Studio logs as a zip archive";
+				readonly done: "Logs saved to {path}";
+				readonly failed: "The logs could not be exported.";
+			};
 		};
 		readonly export: {
 			readonly chooseFolder: "Choose a folder for the exported project package.";
@@ -12116,7 +12282,13 @@ declare const en: {
 			readonly title: "Layers";
 			readonly empty: "Nothing is on screen";
 			readonly stack: "Stack, bottom to top";
+			readonly stage: "Stage";
+			readonly gameUi: "Game UI";
 			readonly page: "Page";
+			readonly layer: "Layer";
+			readonly faded: "Faded out";
+			readonly hiddenForGame: "Hidden while the game runs";
+			readonly returnsOnBack: "Shown again on Go back";
 			readonly onScreenCount: "{onScreen} of {total} on screen";
 			readonly offScreen: "Not on screen";
 			readonly offScreenNote: "A layer stays off screen while this project has no surface with its id.";
@@ -12124,6 +12296,7 @@ declare const en: {
 			readonly queued: "Waiting for a group";
 			readonly takesClicks: "Takes clicks";
 			readonly takesNoClicks: "Takes no clicks";
+			readonly takesNoInput: "Takes no clicks or keys";
 			readonly keyboard: "Keyboard";
 			readonly modal: "Modal";
 			readonly dismissible: "Go back closes it";
@@ -12495,6 +12668,7 @@ declare const en: {
 			readonly inputAction: "input action";
 			readonly asset: "asset";
 			readonly page: "Page";
+			readonly entryPage: "Entry Page";
 			readonly gameUi: "Game UI";
 			readonly image: "Image";
 			readonly audio: "Audio";
@@ -12543,6 +12717,7 @@ declare const en: {
 				readonly supported: "Supported files";
 				readonly images: "Images";
 				readonly log: "Log";
+				readonly zip: "Zip archive";
 				readonly text: "Text";
 				readonly json: "JSON";
 				readonly patch: "Patch";
@@ -13481,13 +13656,15 @@ declare const en: {
 			};
 			readonly localizationMissing: {
 				readonly title: "Missing translation";
-				readonly description: "A line with no translation in a target language";
+				readonly description: "A line or interface text with no translation in a target language";
 				readonly message: "No {locale} translation";
+				readonly messageInterface: "No {locale} translation of {text}";
 			};
 			readonly localizationStale: {
 				readonly title: "Stale translation";
 				readonly description: "The source line changed after it was translated";
 				readonly message: "{locale} translation is older than the line";
+				readonly messageInterface: "{locale} translation of {text} is older than the text";
 			};
 			readonly localizationMarkup: {
 				readonly title: "Translation drops styling";
@@ -13793,6 +13970,7 @@ declare const en: {
 		};
 		readonly uiDocument: {
 			readonly renamed: "Interface renamed";
+			readonly entryPage: "Entry page changed";
 			readonly surfaceAdded: "Surface added ({elementCount})";
 			readonly surfaceRemoved: "Surface removed ({elementCount})";
 			readonly surfaceChanged: "Surface changed";
@@ -13855,6 +14033,10 @@ declare const en: {
 			readonly content: "File contents replaced";
 			readonly field: "{field} changed";
 			readonly orphanContent: "File with no asset record";
+			readonly fields: {
+				readonly group: "Group";
+				readonly missingGroup: "Missing group";
+			};
 		};
 		readonly brand: {
 			readonly added: "Color added";
@@ -15047,7 +15229,7 @@ type Messages = typeof en;
 type Flatten<T, Prefix extends string = ""> = {
 	[K in keyof T & string]: T[K] extends string ? `${Prefix}${K}` : Flatten<T[K], `${Prefix}${K}.`>;
 }[keyof T & string];
-type TranslationKey = Flatten<Messages>;
+type TranslationKey = Flatten<Messages> | (string & {});
 type PrivilegedWriteBatchEntry = {
 	path: string;
 	encoding?: FsTextEncoding;
@@ -16357,6 +16539,11 @@ type LiveUIParts = {
 	actions?: Readonly<Record<string, UIInputActionDef | null>>;
 	/** The document's own name, when it changed. */
 	name?: string;
+	/**
+	 * Which page the game starts on, when that changed. `null` is the document naming none - which
+	 * is a value of its own (the main page is the entry), not "unchanged".
+	 */
+	entrySurfaceId?: UISurfaceId | null;
 };
 type LiveUIElementRef = {
 	componentId: UIComponentId | null;
@@ -16747,6 +16934,10 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	private normalizeSpecialChildSlots;
 	private createEmptyDocument;
 	createSurface(input: CreateSurfaceInput): UISurface;
+	/**
+	 * Remove a surface and its tree. The entry page is refused: a game has to start somewhere, and
+	 * the way to delete the page it starts on is to make another page the entry first.
+	 */
 	deleteSurface(surfaceId: string): void;
 	/**
 	 * Put the surfaces in the order given.
@@ -16769,6 +16960,21 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	 * the entry.
 	 */
 	reorderSurfaces(orderedSurfaceIds: readonly string[], movedSurfaceId?: string): void;
+	/**
+	 * Make this page the one the game starts on.
+	 *
+	 * Only a page can be the entry - a Game UI has nothing to show before a story runs - and asking
+	 * for the page that already is changes nothing and records nothing. The pages keep their ids:
+	 * the document stores which one is the entry (`UIDocument.entrySurfaceId`), so every blueprint
+	 * and every `Go Page` that names either page still names the same page afterwards.
+	 *
+	 * On the project stack, for the reason {@link reorderSurfaces} gives: it is an edit to no one
+	 * surface, made from the panel. The entry restores to what the file stored rather than to the
+	 * page that was resolved, so taking this back leaves a document that never named an entry as
+	 * short as it was.
+	 */
+	setEntrySurface(surfaceId: string): void;
+	private applyEntrySurface;
 	private applySurfaceOrder;
 	renameSurface(surfaceId: string, name: string): void;
 	/**
@@ -16921,7 +17127,25 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	private configureDefaultNotificationBlueprints;
 	private configureDefaultChoiceBlueprints;
 	private configureDefaultNvlBlueprints;
-	private ensureMainSurface;
+	/**
+	 * A page for the game to start on, whatever the file said. True when the document had to change.
+	 *
+	 * Three repairs, each for a document that arrived broken - by a merge, a hand edit, or an older
+	 * tool - and none of which a document Studio wrote ever needs:
+	 *
+	 *  - **no page at all**: one is made, under the main id when nothing holds it, so a project
+	 *    always has somewhere to start;
+	 *  - **an entry page whose root element is missing**: it gets an empty one, so it can be opened;
+	 *  - **a stored entry that names no page**: the pointer is dropped, and the entry is the page the
+	 *    document would name without it (`resolveEntrySurface` already reads it that way - this only
+	 *    stops the file from saying something it does not mean).
+	 *
+	 * ⚠ **It never changes a page's id.** This used to give the first page the main id when no page
+	 * had it, which was harmless only while the main page could not be deleted. Now that the entry is
+	 * a pointer and the old main page can be deleted like any other, doing that would quietly re-file
+	 * every blueprint and every `Go Page` that named the page by the id it had.
+	 */
+	private ensureEntrySurface;
 	private getDocumentPath;
 	private ensureDocumentDir;
 }
@@ -17186,6 +17410,8 @@ interface IconButtonGroupOption {
 	icon: React$1.ReactNode;
 	label?: string;
 	disabled?: boolean;
+	/** Hover text when it should say more than the label - why an option is unavailable, say. */
+	tip?: string;
 }
 type IconButtonSelection = string | string[] | null;
 type IconButtonSegGroupDensity = "default" | "compact";
@@ -17672,6 +17898,20 @@ type BlueprintNodeDeclaration = {
 	};
 	inspectorParams?: BlueprintInspectorParamDef[];
 	role?: BlueprintNodeRole;
+	/**
+	 * The node's own words in other languages, for a node the host did not define.
+	 *
+	 * Keyed by locale code, then by the English text exactly as this declaration writes it: the
+	 * title, the category, a pin label, an inspector label, an option label or an empty-option
+	 * label. That is how the host's own catalogue is keyed (see `blueprintNodeI18n`), because the
+	 * canvas, the palette and the issue list all hold a title or a label rather than the node that
+	 * declared it. A string the host already translates keeps the host's wording, so one English
+	 * word reads the same on every node; a string with no entry for the active locale is drawn in
+	 * English.
+	 *
+	 * Built-in nodes leave this unset: their words live in Studio's catalogue.
+	 */
+	translations?: Readonly<Record<string, Readonly<Record<string, string>>>>;
 };
 interface ProjectProps {
 	projectPath: string;
@@ -19101,6 +19341,12 @@ export type RuntimePluginSaveMetadata = {
  * heavier capability.
  */
 export type RuntimePluginSaves = {
+	/**
+	 * Every slot in the store, reserved ones included: the autosave ring, and any slot a plugin
+	 * keeps for itself (`contributes.reservedSaveIds`). This is direct store access, not the
+	 * player's view - `List Saves` is the one that leaves bookkeeping out - so a plugin can find its
+	 * own reserved slot here.
+	 */
 	listIds(): Promise<string[]>;
 	readMetadata(id: string): Promise<RuntimePluginSaveMetadata | null>;
 	/** Present only with `saves.write`. Overwrites the slot. */
@@ -19618,10 +19864,15 @@ type DropEdge = "before" | "after";
 interface DropIndicatorProps {
 	/** Which edge of the positioned parent the line sits on. */
 	edge: DropEdge;
+	/**
+	 * Which way the rows run. A list (the default) puts "before" on the top edge and draws the line
+	 * across; a grid that reads left to right puts it on the left edge and draws the line down.
+	 */
+	axis?: "vertical" | "horizontal";
 	/** Extra classes for the rare caller that has to nudge it; the line itself is not negotiable. */
 	className?: string;
 }
-declare function DropIndicator({ edge, className }: DropIndicatorProps): React$1.ReactElement;
+declare function DropIndicator({ edge, axis, className }: DropIndicatorProps): React$1.ReactElement;
 export interface AccordionProps {
 	children: React$1.ReactNode;
 	/** Default open item IDs */

package/dist/plugin.d.ts

@@ -60,6 +60,8 @@ export {
 	PluginLocalizationKeyEntry,
 	PluginLocalizationService,
 	PluginManifestEntries,
+	PluginManifestLocalized,
+	PluginManifestLocalizedText,
 	PluginManifestV2,
 	PluginMessageBundle,
 	PluginPanelEmptyStateProps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "narraleaf-studio",
-  "version": "0.9.0",
+  "version": "1.1.0",
   "description": "TypeScript declarations for the NarraLeaf Studio plugin API (narraleaf-studio/plugin and narraleaf-studio/runtime).",
   "license": "MPL-2.0",
   "type": "module",