narraleaf-studio 1.3.0 → 1.4.0

package/dist/_api.d.ts

@@ -1775,6 +1775,38 @@ type BlueprintOpenExternalResult = {
 };
 type BlueprintGraphKind = "event" | "function" | "macro";
 type GameBuildPlatform = "windows" | "macos" | "linux" | "web" | "android" | "ios";
+declare const UI_STRUCT_FIELD_TYPES: readonly [
+	"string",
+	"number",
+	"boolean",
+	"image",
+	"color",
+	"json"
+];
+type UIStructFieldType = (typeof UI_STRUCT_FIELD_TYPES)[number];
+type UIStructField = {
+	/**
+	 * Stable identity. Value bindings, node params and generated pins all address a field by this,
+	 * so renaming `key` costs nothing and reshuffling the list costs nothing.
+	 */
+	id: string;
+	/** The property name this field occupies inside an item object. */
+	key: string;
+	/**
+	 * What the author called it, shown in the item table header and in every field picker.
+	 *
+	 * Optional because `key` is usually already the readable name; a label is what lets a field
+	 * whose key has to stay ASCII (it travels in JSON to a plugin, a save file, a story variable)
+	 * still read as words in the editor.
+	 */
+	label?: string;
+	type: UIStructFieldType;
+};
+type UIStructId = string;
+type UIStructDef = {
+	id: UIStructId;
+	fields: UIStructField[];
+};
 type PluginPermissionPersistence = "temporary" | "permanent";
 type PluginFileSystemPermissionMode = "read" | "write" | "readwrite";
 /**
@@ -2245,6 +2277,33 @@ export type PluginContributes = {
 	 * declaration only one of them made would be the half that drifts.
 	 */
 	widgetText?: Record<string, PluginWidgetTextContribution[]>;
+	/**
+	 * The shapes of the rows this plugin's nodes hand out, so a list can be given one and a field
+	 * read from one by name.
+	 *
+	 * A node pin carrying them says `struct:<id>` or `array<struct:<id>>` - `Get Gallery` answers
+	 * `array<struct:narraleaf.gallery.entry>` - and from then on the plugin's rows are what the
+	 * engine's own are: a list picks the shape under Edit content and its fields are the plugin's
+	 * and locked, Get Field offers them, and a list handed rows that lack them is reported.
+	 *
+	 * Declared in the manifest rather than at registration because the editor, the running game and
+	 * the command-line checker all need the shape, and only the manifest is read by all three before
+	 * any plugin code runs. Ids must start with the plugin id.
+	 */
+	structs?: PluginStructContribution[];
+};
+type PluginStructContribution = {
+	/** Prefixed with the plugin id: `narraleaf.gallery.entry`. */
+	id: string;
+	/** What the editor calls the shape - "Gallery entry". */
+	name: string;
+	/** `name` per editor locale, matched exactly as `localized` names are. */
+	localized?: Record<string, string>;
+	/** In the order the rows are read: the list's content editor shows them in this order. */
+	fields: {
+		key: string;
+		type: UIStructFieldType;
+	}[];
 };
 /**
  * One prop of a contributed widget whose value is words a player reads.
@@ -2558,6 +2617,9 @@ type UIInputBinding = {
 } | {
 	kind: "key";
 	key: string;
+} | {
+	kind: "gamepad";
+	button: string;
 };
 type UIInputActionDef = {
 	id: string;
@@ -2610,38 +2672,6 @@ type UIPageAnimationSettings = {
 	/** Surfaces only: hold the incoming Page until this exit has finished. */
 	exitBlocking: boolean;
 };
-declare const UI_STRUCT_FIELD_TYPES: readonly [
-	"string",
-	"number",
-	"boolean",
-	"image",
-	"color",
-	"json"
-];
-type UIStructFieldType = (typeof UI_STRUCT_FIELD_TYPES)[number];
-type UIStructField = {
-	/**
-	 * Stable identity. Value bindings, node params and generated pins all address a field by this,
-	 * so renaming `key` costs nothing and reshuffling the list costs nothing.
-	 */
-	id: string;
-	/** The property name this field occupies inside an item object. */
-	key: string;
-	/**
-	 * What the author called it, shown in the item table header and in every field picker.
-	 *
-	 * Optional because `key` is usually already the readable name; a label is what lets a field
-	 * whose key has to stay ASCII (it travels in JSON to a plugin, a save file, a story variable)
-	 * still read as words in the editor.
-	 */
-	label?: string;
-	type: UIStructFieldType;
-};
-type UIStructId = string;
-type UIStructDef = {
-	id: UIStructId;
-	fields: UIStructField[];
-};
 type UISurfaceBackgroundFillMode = "cover" | "contain" | "stretch" | "tile";
 type UISurfaceBackgroundImage = {
 	/** Image library asset id. Absent background = absent field, so this is never empty. */
@@ -2725,7 +2755,27 @@ type UIAppSurface = {
 	 * whether what it just did leaves anything for the surface behind to do.
 	 */
 	actions?: UISurfaceActionEnablement[];
+	/** The values this page is opened with, in author order. See {@link UIPageParam}. */
+	params?: UIPageParam[];
+};
+type UIPageParam = {
+	id: string;
+	name: string;
+	type: UIPageParamType;
+	/**
+	 * For a `list`: the shape each row has, as a struct id (an engine shape such as `nl.confirmButton`,
+	 * a plugin's, or one of the project's). It types the value on both ends - the inputs that give it
+	 * and `Get Page Param` - and a list on the page bound to it is checked against it. Absent for
+	 * every other type, and for a list of rows of no declared shape.
+	 */
+	struct?: string;
+	/**
+	 * What the page reads when whoever opened it gave nothing for this name, in the declared type.
+	 * Absent reads as the type's empty value (`uiPageParamDefaultValue`).
+	 */
+	defaultValue?: unknown;
 };
+type UIPageParamType = "string" | "text" | "number" | "boolean" | "list" | "json";
 type UIStageSurface = {
 	id: UISurfaceId;
 	name: string;
@@ -2866,6 +2916,20 @@ type UIElementValueBinding = {
  | {
 	kind: "componentParam";
 	paramId: string;
+}
+/**
+ * Show the value the page this element is on was opened with for one of its text parameters.
+ *
+ * The page's counterpart of `componentParam`, read the same way: no graph - the value is taken from
+ * the props the page was opened with (`resolveUIPageTextParams`), words given at the opening shown
+ * as given, the declared default translated through the page's own unit. Only a text parameter
+ * answers one, only a widget's words take one, and only on a page: a component's insides and a
+ * Game UI have no page parameters to show. The editing canvas, where the page has not been opened,
+ * draws the default, or the element's own words as sample text while the default is empty.
+ */
+ | {
+	kind: "pageParam";
+	paramId: string;
 };
 type UILayout = {
 	x: number;
@@ -3402,6 +3466,10 @@ declare const en: {
 			readonly downloadRewrites: {
 				readonly label: "Download address rewrites";
 			};
+			readonly useSystemProxy: {
+				readonly label: "Use this computer's proxy";
+				readonly description: "Studio downloads follow the proxy this computer already uses.";
+			};
 			readonly pluginRegistryUrl: {
 				readonly label: "Plugin registry URL";
 				readonly description: "Where the plugin store looks for its index.";
@@ -4321,6 +4389,7 @@ declare const en: {
 			readonly panelRenderError: "This panel hit a rendering error";
 			readonly mainEditorRegion: "Main editor";
 			readonly resizeSplit: "Resize split";
+			readonly resizeSections: "Resize sections";
 			readonly noActiveEditor: "No active editor";
 			readonly closePanel: "Close panel";
 			readonly closeTab: "Close {name}";
@@ -4897,6 +4966,15 @@ declare const en: {
 						readonly alignBottom: "Align bottom";
 						readonly distributeHorizontal: "Distribute horizontally";
 						readonly distributeVertical: "Distribute vertically";
+						readonly nudgeLeft: "Move left 1 px";
+						readonly nudgeRight: "Move right 1 px";
+						readonly nudgeUp: "Move up 1 px";
+						readonly nudgeDown: "Move down 1 px";
+						readonly nudgeLeftLarge: "Move left 10 px";
+						readonly nudgeRightLarge: "Move right 10 px";
+						readonly nudgeUpLarge: "Move up 10 px";
+						readonly nudgeDownLarge: "Move down 10 px";
+						readonly snapToGrid: "Snap to grid";
 					};
 					readonly blueprint: {
 						readonly undo: "Undo";
@@ -5405,6 +5483,8 @@ declare const en: {
 				readonly forkCondition: "Condition";
 				readonly fallsThrough: "continues";
 				readonly fallsThroughTitle: "No jump of its own; the scene continues past the fork";
+				readonly ends: "ends";
+				readonly endsTitle: "The story ends in this branch: {names}";
 				readonly forkCount: {
 					readonly one: "{count} branch";
 					readonly other: "{count} branches";
@@ -5868,6 +5948,15 @@ declare const en: {
 			readonly appliesTo: "Also filed under";
 			readonly star: "Star";
 			readonly unstar: "Unstar";
+			readonly abbreviations: "Your abbreviations";
+			readonly addAbbreviation: "Add abbreviation";
+			readonly removeAbbreviation: "Remove {word}";
+			readonly abbreviationPlaceholder: "Abbreviation";
+			readonly abbreviationSpace: "An abbreviation cannot contain spaces.";
+			readonly abbreviationCharacter: "Quotes, =, /, @ and # cannot be used.";
+			readonly abbreviationBuiltIn: "Already a spelling of {command}.";
+			readonly abbreviationTaken: "Already your abbreviation for {command}.";
+			readonly abbreviationShadowed: "Now a spelling of {command}. This abbreviation has no effect.";
 			readonly type: {
 				readonly image: "Image asset";
 				readonly audio: "Audio asset";
@@ -5995,7 +6084,7 @@ declare const en: {
 			readonly openPreview: "Open live preview";
 			readonly closePreview: "Close live preview";
 			readonly title: "Live Preview";
-			readonly dock: "Dock to sidebar";
+			readonly dock: "Dock in the scene editor";
 			readonly pip: "Picture-in-picture";
 			readonly selectRow: "Select a story row to preview its stage state.";
 			readonly failed: "Preview failed";
@@ -7973,6 +8062,25 @@ declare const en: {
 			readonly targetTooltip: "Target: {label} ({type})";
 			readonly fromPin: "Create from pin";
 			readonly connectEmpty: "No nodes can connect to this pin.";
+			readonly fieldsCategory: "Fields";
+			readonly readField: "Get {field}";
+			readonly filterByField: "Filter by {field}";
+			readonly sortByField: "Sort by {field}";
+			readonly findByField: "Find by {field}";
+		};
+		readonly struct: {
+			readonly any: "Struct";
+			readonly listRow: "List row";
+			readonly arrayOf: "{name} list";
+			readonly choiceItem: "Choice";
+			readonly notificationItem: "Notification";
+			readonly nvlItem: "NVL line";
+			readonly historyEntry: "History entry";
+			readonly saveEntry: "Save entry";
+			readonly confirmButton: "Confirm button";
+			readonly ending: "Ending";
+			readonly language: "Language";
+			readonly voiceLanguage: "Voice language";
 		};
 		readonly diagnostics: {
 			readonly empty: "No diagnostics.";
@@ -7991,7 +8099,7 @@ declare const en: {
 			};
 			readonly interaction: {
 				readonly hiddenEvents: "Element \u201C{name}\u201D is not visible but still has interaction bindings";
-				readonly hiddenEventsHint: "Remove the events, or make the element visible. A hidden element receives no input.";
+				readonly hiddenEventsHint: "Remove the events, make the element visible, or show it from a blueprint. A hidden element receives no input.";
 				readonly opaqueEvents: "Element \u201C{name}\u201D is nearly invisible (opacity) but has interaction bindings";
 				readonly opaqueEventsHint: "Players may not see this control. Check it in Dev Mode.";
 				readonly smallHit: "Element \u201C{name}\u201D has a small hit area with interactions";
@@ -8052,6 +8160,11 @@ declare const en: {
 				readonly variableIdInvalid: "Node \"{node}\": pick a variable.";
 				readonly persistentVariableIdInvalid: "Node \"{node}\": pick a persistent variable.";
 				readonly savedVariableIdInvalid: "Node \"{node}\": pick a saved variable.";
+				readonly fieldMissing: "\"{node}\": {struct} has no field \"{field}\".";
+				readonly fieldUnpicked: "Node \"{node}\": pick a field.";
+				readonly keyNotAField: "\"{node}\": {struct} has no field \"{key}\". No item matches.";
+				readonly listShapeMismatch: "\"{node}\": {struct} does not match this list's fields. Fields that differ show empty.";
+				readonly pageParamMissing: "\"{node}\": the page does not declare this param.";
 			};
 			readonly fn: {
 				readonly nameMissing: "Fn \"{node}\": set a function name.";
@@ -8324,6 +8437,7 @@ declare const en: {
 			readonly editValue: "Edit value on card";
 			readonly removeOutput: "Remove output pin";
 			readonly jsonFieldName: "JSON object field name";
+			readonly readsRow: "Current row";
 		};
 		readonly comment: {
 			readonly color: {
@@ -8416,6 +8530,7 @@ declare const en: {
 			readonly missingCharacter: "Missing character";
 			readonly unnamedInputAction: "Unnamed action";
 			readonly missingInputAction: "Missing action";
+			readonly missingField: "Missing field \u201C{field}\u201D";
 		};
 		readonly script: {
 			readonly fileLabel: "Script file";
@@ -8646,6 +8761,8 @@ declare const en: {
 			readonly height: "Height";
 			readonly held: "Held";
 			readonly device: "Device";
+			readonly connected: "Connected";
+			readonly axis: "Axis";
 			readonly hide: "Hide";
 			readonly holdFinalValue: "Hold final value";
 			readonly id: "Id";
@@ -8717,6 +8834,7 @@ declare const en: {
 			readonly page: "Page";
 			readonly pageProps: "Page props";
 			readonly param: "Param";
+			readonly parameter: "Parameter";
 			readonly persistent: "Persistent";
 			readonly pointer: "Pointer";
 			readonly center: "Center";
@@ -9076,7 +9194,7 @@ declare const en: {
 			readonly getLineHeight: "Get Line Height";
 			readonly findItemByField: "Find Item By Field";
 			readonly getItemAt: "Get Item At";
-			readonly getItemField: "Get Item Field";
+			readonly getField: "Get Field";
 			readonly getListContent: "Get List Content";
 			readonly getListLength: "Get List Length";
 			readonly setItemFieldAt: "Set Item Field At";
@@ -9138,6 +9256,9 @@ declare const en: {
 			readonly isLayerMounted: "Is Layer Mounted";
 			readonly isActionHeld: "Is Action Held";
 			readonly getInputDevice: "Get Input Device";
+			readonly isGamepadConnected: "Is Gamepad Connected";
+			readonly isGamepadButtonHeld: "Is Gamepad Button Held";
+			readonly getGamepadAxis: "Get Gamepad Axis";
 			readonly showConfirm: "Show Confirm";
 			readonly memo: "Memo";
 			readonly clearPage: "Clear Page";
@@ -9236,6 +9357,10 @@ declare const en: {
 			readonly onAction: "On Action";
 			readonly onKeyDown: "On Key Down";
 			readonly onKeyUp: "On Key Up";
+			readonly onGamepadButtonDown: "On Gamepad Button Down";
+			readonly onGamepadButtonUp: "On Gamepad Button Up";
+			readonly anyGamepadButtonDown: "Any Gamepad Button Down";
+			readonly anyGamepadButtonUp: "Any Gamepad Button Up";
 			readonly onPreferenceChanged: "On Preference Changed";
 			readonly openLink: "Open Link";
 			readonly openScreenshotsFolder: "Open Screenshots Folder";
@@ -9386,6 +9511,7 @@ declare const en: {
 		};
 		readonly nodeDescription: {
 			readonly getComponentParam: "The value this placement sets for the chosen parameter, or the parameter's default when it sets none. A Text parameter that reads from a translation key gives the key's name; Translation Key Text gives its words.";
+			readonly getPageParam: "The value the page was opened with for the chosen param, or the param's default when it was given none. Params are declared in the page's properties.";
 			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.";
@@ -9405,6 +9531,7 @@ declare const en: {
 			readonly translationKeyText: "A translation key's text in the player's current language, or its source text when that language has no translation. A key that does not exist gives its name. The same text as Get Text, and also usable in Blueprint Value and functions. A Blueprint Value that shows it updates when the player changes language.";
 			readonly format: "Replaces the placeholders in Template with values: {0}, {1} and so on with the items of an array, {name} with the field of that name in an object. A placeholder with no value becomes empty. A translated template comes from Translation Key Text.";
 			readonly formatText: "Replaces {0}, {1} and so on in Text with the items of Values. Format does the same, also fills {name} from an object, and can be used in Blueprint Value and functions.";
+			readonly getField: "One field of the struct wired into Object, picked from that struct's fields. Inside a list row, leave Object unwired to read the row. Use Get JSON Field for an object whose fields are not declared.";
 		};
 		readonly live: {
 			readonly nodeClaimed: "{name} is editing this node";
@@ -9816,6 +9943,27 @@ declare const en: {
 			readonly bindNone: "No parameter";
 			readonly bindMissing: "Missing parameter";
 		};
+		readonly pageParams: {
+			readonly title: "Params";
+			readonly none: "No params";
+			readonly hint: "Given by whatever opens this page. A text param can be shown by a text directly; read the others with Get Page Param.";
+			readonly rowShape: "Row struct";
+			readonly anyShape: "Unspecified";
+			readonly bindLabel: "Page param";
+			readonly bindNone: "No param";
+			readonly bindMissing: "Missing param";
+			readonly add: "Add param";
+			readonly remove: "Remove {name}";
+			readonly namePlaceholder: "Name";
+			readonly default: "Default";
+			readonly type: "Type";
+			readonly typeString: "String";
+			readonly typeText: "Text";
+			readonly typeNumber: "Number";
+			readonly typeBoolean: "Boolean";
+			readonly typeList: "List";
+			readonly typeJson: "JSON";
+		};
 		readonly binding: {
 			readonly notReady: "Blueprint not ready for this control.";
 			readonly bindToField: "Bind to field\u2026";
@@ -9911,6 +10059,7 @@ declare const en: {
 				readonly character: "Character";
 				readonly voice: "Voice";
 				readonly design: "Design";
+				readonly projectSettings: "Settings";
 				readonly plugin: "Plugin";
 			};
 		};
@@ -10229,10 +10378,15 @@ declare const en: {
 			readonly newName: "Field";
 			readonly none: "No fields";
 			readonly engineOwned: "This list receives its fields from the engine.";
+			readonly pluginOwned: "This list receives its fields from a plugin.";
 			readonly picker: "Field";
 			readonly visiblePicker: "Visible from field";
 			readonly pickerEmpty: "No field";
 		};
+		readonly shape: {
+			readonly label: "Struct";
+			readonly custom: "Custom";
+		};
 		readonly row: {
 			readonly add: "Add row";
 			readonly remove: "Remove row";
@@ -10326,6 +10480,7 @@ declare const en: {
 			readonly nvl: "Full-screen novel-mode dialog history.";
 		};
 		readonly panel: {
+			readonly interfaces: "Interfaces";
 			readonly interfaceType: "Interface Type";
 			readonly createPage: "Create Page";
 			readonly createGameUi: "Create Game UI";
@@ -10361,6 +10516,15 @@ declare const en: {
 		readonly history: {
 			readonly moveSurface: "move interface {name}";
 			readonly setEntryPage: "set entry page {name}";
+			readonly createComponent: "create component {name}";
+			readonly duplicateComponent: "duplicate component {name}";
+			readonly duplicateComponents: "duplicate {count} components";
+			readonly deleteComponent: "delete component {name}";
+			readonly deleteComponents: "delete {count} components";
+			readonly importSurface: "add interface {name}";
+			readonly importSurfaces: "add {count} interfaces";
+			readonly importComponent: "add component {name}";
+			readonly importComponents: "add {count} components";
 		};
 		readonly inputActions: {
 			readonly title: "Input Actions";
@@ -10397,6 +10561,7 @@ declare const en: {
 				readonly trackpad: "Trackpad";
 				readonly touch: "Touch screen";
 				readonly key: "Keyboard";
+				readonly gamepad: "Gamepad";
 			};
 			readonly gesture: {
 				readonly click: "Click";
@@ -10463,6 +10628,7 @@ declare const en: {
 			readonly wordsFromRowField: "These words come from the list row field \u201C{field}\u201D.";
 			readonly wordsFromBlueprintValue: "These words come from the blueprint value \u201C{name}\u201D.";
 			readonly wordsFromComponentParam: "These words come from the component parameter \u201C{param}\u201D, set on each placement.";
+			readonly wordsFromPageParam: "These words come from the page param \u201C{param}\u201D, given when the page is opened.";
 		};
 		readonly editor: {
 			readonly componentNotFound: "Component not found";
@@ -10474,6 +10640,9 @@ declare const en: {
 			readonly selectTool: "Select tool";
 			readonly panTool: "Pan the canvas";
 			readonly openInDevMode: "Open this interface in Dev Mode";
+			readonly showInLivePreview: "Show this interface in the live preview";
+			readonly livePreviewShowsNoNotifications: "Notifications are not shown in the live preview";
+			readonly livePreviewNoRow: "No row in the story shows this interface";
 			readonly componentDefinitionHint: "Components are edited as definitions";
 			readonly bindElement: "Bind Element";
 			readonly bindSelectHint: "Select one element on this Surface";
@@ -10501,6 +10670,11 @@ declare const en: {
 			readonly canvasLayout: "Canvas layout (edges & center)";
 			readonly elementBorders: "Element borders (edge to edge)";
 			readonly elementLayout: "Element layout (centers)";
+			readonly grid: "Grid";
+			readonly gridStyle: "Grid style";
+			readonly gridLines: "Lines";
+			readonly gridDots: "Dots";
+			readonly gridSize: "Grid size";
 		};
 		readonly contextMenu: {
 			readonly pasteIntoContainer: "Paste into container";
@@ -10549,6 +10723,12 @@ declare const en: {
 				readonly left: "left";
 			};
 		};
+		readonly reference: {
+			readonly label: "Game UI reference";
+			readonly heading: "Other game UI";
+			readonly none: "This project has no other game UI.";
+			readonly sizeDiffers: "Different size: {name} {width}\u00D7{height}";
+		};
 		readonly crossProject: {
 			readonly pasted: {
 				readonly one: "{count} element pasted";
@@ -10695,6 +10875,7 @@ declare const en: {
 			readonly removeBinding: "Remove";
 			readonly hintBlueprintValue: "Shown in the editor only. The game shows the Blueprint Value's result.";
 			readonly hintComponentParam: "Shown while editing the component only. Each placement shows the value it sets for the parameter.";
+			readonly hintPageParam: "Shown while editing the page, when the param's default is empty. In the game the page shows the text it is opened with, or the default.";
 		};
 		readonly textWriters: {
 			readonly title: "Written in the game by";
@@ -10730,6 +10911,9 @@ declare const en: {
 			readonly stateKeyPlaceholder: "choices";
 			readonly propName: "Prop name";
 			readonly propNamePlaceholder: "choices";
+			readonly pageParam: "Param";
+			readonly pageParamUndeclared: "not declared on this page";
+			readonly noPageParams: "This page declares no params";
 			readonly placeholderCount: "Placeholder rows";
 			readonly contentTitle: "List content";
 			readonly fields: "Fields";
@@ -10829,6 +11013,7 @@ declare const en: {
 			readonly title: "Page";
 			readonly page: "Page";
 			readonly props: "Props";
+			readonly params: "Params";
 			readonly animation: "Animation";
 			readonly usePageAnimation: "Use Page animation";
 			readonly pageLogic: "Page component logic";
@@ -11495,7 +11680,7 @@ declare const en: {
 			};
 			readonly settings: {
 				readonly title: "Settings";
-				readonly description: "Security, signing, compression, loading, and mobile";
+				readonly description: "Security, signing, compression, loading, letterbox, and mobile";
 			};
 		};
 		readonly group: {
@@ -11525,6 +11710,7 @@ declare const en: {
 			readonly videoCompression: "Video compression";
 			readonly loading: "Loading";
 			readonly crash: "Crashes";
+			readonly letterbox: "Letterbox";
 			readonly mobile: "Mobile";
 		};
 		readonly compressionMode: {
@@ -11909,6 +12095,10 @@ declare const en: {
 				readonly portrait: "Portrait";
 				readonly auto: "Follow device";
 			};
+			readonly letterboxColorTitle: "Letterbox color";
+			readonly letterboxColorDescription: "Shown around the stage on screens of another aspect ratio.";
+			readonly letterboxImageTitle: "Letterbox image";
+			readonly letterboxImageDescription: "Drawn over the letterbox color. The stage covers its middle.";
 			readonly stageFitTitle: "Screen fit";
 			readonly stageFitDescription: "Mobile builds and Dev Mode. Desktop and web always letterbox.";
 			readonly stageFit: {
@@ -13917,6 +14107,32 @@ declare const en: {
 				readonly message: "This is bound to an item field the list does not declare, so every row shows the same value";
 				readonly help: string;
 			};
+			readonly uiPagePropUndeclared: {
+				readonly title: "Undeclared page param";
+				readonly description: "A list showing a page prop the page does not declare as a param";
+				readonly message: "This list shows the page prop \"{name}\", which the page does not declare as a param";
+				readonly help: string;
+			};
+			readonly uiPageParamUnknown: {
+				readonly title: "Unknown page param";
+				readonly description: "A Page widget giving a value the page it shows does not declare";
+				readonly message: "This Page widget gives \"{name}\", which the page it shows does not declare";
+				readonly help: string;
+			};
+			readonly uiPageTextParamMissing: {
+				readonly title: "Missing page text param";
+				readonly description: "A text on a page showing a param the page does not declare as text";
+				readonly message: "This shows a page param the page does not declare as text, so the game shows no words here";
+				readonly messageOutside: "This shows a page param but is not on a page, so the game shows no words here";
+				readonly help: string;
+			};
+			readonly uiPageParamListMismatch: {
+				readonly title: "List not matching its page param";
+				readonly description: "A list showing a page param that is not a list, or whose rows lack fields the list draws";
+				readonly messageNotList: "This list shows the page param \"{name}\", which is not a list";
+				readonly message: "This list shows the page param \"{name}\", whose rows lack fields the list draws: {fields}";
+				readonly help: string;
+			};
 			readonly uiComponentParamMissing: {
 				readonly title: "Missing text parameter";
 				readonly description: "A widget in a component showing a parameter the component does not declare as text";
@@ -13954,6 +14170,24 @@ declare const en: {
 				readonly message: "{node} has nothing connected to {pin}";
 				readonly help: string;
 			};
+			readonly blueprintFieldMissing: {
+				readonly title: "Field not in shape";
+				readonly description: "A node that names a field the value it reads does not have";
+				readonly message: "{node}: {struct} has no field {field}";
+				readonly help: string;
+			};
+			readonly blueprintPageParamMissing: {
+				readonly title: "Missing page param";
+				readonly description: "Get Page Param reading a param the page does not declare";
+				readonly message: "{node} reads a param the page does not declare";
+				readonly help: string;
+			};
+			readonly blueprintListShapeMismatch: {
+				readonly title: "List fields do not match";
+				readonly description: "Rows of another shape given to a list";
+				readonly message: "{node}: {struct} does not match the list's fields";
+				readonly help: string;
+			};
 			readonly blueprintStartSceneForeign: {
 				readonly title: "Scene from another story";
 				readonly description: "A Start Game node whose scene is not in the story it names";
@@ -15933,12 +16167,13 @@ export type SearchJumpTarget = {
 }
 /**
  * A page of Project settings - the panel's sub-pages - and, with `part`, the part of it to scroll
- * into view: `fonts` is the project's font stack on the Design page.
+ * into view: `fonts` is the project's font stack on the Design page, `letterbox` the letterbox
+ * settings on the Settings page.
  */
  | {
 	kind: "projectPage";
 	page: "app" | "game" | "design" | "project" | "runtimes" | "settings";
-	part?: "fonts";
+	part?: "fonts" | "letterbox";
 }
 /**
  * A story's own row in the Story panel's list, selected and scrolled into view - the place a story
@@ -17151,6 +17386,13 @@ type ImportTemplateBundleInput = {
 	 * take those translations.
 	 */
 	translations?: CarriedTranslations;
+	/**
+	 * Whether the import is one step on the project's undo stack, which takes back every page and
+	 * definition it added. On unless a caller's own flow goes on to change more than the import did
+	 * - the starter title page also moves the entry page and removes the blank one, and a step that
+	 * took back only its middle would leave the project with neither page.
+	 */
+	history?: boolean;
 };
 declare class UIDocumentService extends Service<UIDocumentService> implements IUIDocumentService {
 	private document;
@@ -17246,7 +17488,15 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	updateElementLayout(elementId: string, layoutPatch: Partial<UILayout>, options?: {
 		skipHistory?: boolean;
 	}): void;
-	updateElementLayouts(layoutPatches: Record<string, Partial<UILayout>>): void;
+	/**
+	 * Write several elements' layouts as one change: one `documentChanged` and one undo step.
+	 *
+	 * `mergeKey` folds this step into the previous one when that carried the same key and was
+	 * recorded within the merge window - how a run of arrow-key nudges stays a single undo.
+	 */
+	updateElementLayouts(layoutPatches: Record<string, Partial<UILayout>>, options?: {
+		mergeKey?: string;
+	}): void;
 	updateElementProps(elementId: string, propsPatch: Record<string, unknown>): void;
 	/**
 	 * Every widget that reads its words from `keyName`, turned into one that holds `words` itself.
@@ -17316,6 +17566,25 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	 * shape, and an instance that could redeclare it would be editing every other instance.
 	 */
 	setListItemStructFields(elementId: string, fields: readonly UIStructField[]): void;
+	/**
+	 * {@link setListItemStructFields} for a list inside a component definition, one step in the
+	 * definition's own history.
+	 *
+	 * The library's rules are the document's, not the page's: a shape another list names - on a page
+	 * or in any definition - is forked rather than reshaped (`applyUIStructFieldsForOwner` walks the
+	 * definitions too), and the pruning that follows counts what definitions name.
+	 */
+	setComponentListItemStructFields(componentId: string, elementId: string, fields: readonly UIStructField[]): void;
+	/**
+	 * Give one list one of the engine's shapes, or (`null`) a shape of its own again.
+	 *
+	 * One step: the pointer, the rows read into the new shape, the list's key field and its item
+	 * template's field bindings moved to the field of the same name, and the library pruned. Undo takes
+	 * all of it back, the library included (`UIEditorHistoryService` slices the shapes a page names).
+	 */
+	setListItemStructShape(elementId: string, shapeId: string | null): void;
+	/** {@link setListItemStructShape} for a list inside a component definition, in its own history. */
+	setComponentListItemStructShape(componentId: string, elementId: string, shapeId: string | null): void;
 	/** What the gestures of this project mean, keyed by id. */
 	getInputActions(): Record<string, UIInputActionDef>;
 	/**
@@ -17367,6 +17636,18 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	 * field id. Switching between them therefore goes through the clear, which is why it runs here.
 	 */
 	setElementListItemFieldBinding(elementId: string, propPath: string, fieldId: string | null): void;
+	/**
+	 * Show one of its page's text parameters in the words of an element on that page, or (`null`)
+	 * stop showing one. The page's counterpart of `setElementComponentParamBinding`: an element on a
+	 * Game UI, which declares no parameters, is left alone.
+	 */
+	setElementPageParamBinding(elementId: string, propPath: string, paramId: string | null): void;
+	/**
+	 * Bind one prop of one element on a surface to something that needs no blueprint - a field of its
+	 * list row, a text parameter of its page - or (`null`) unbind it. A Blueprint Value the prop was
+	 * bound to is torn down on the way (`clearElementBlueprintValueBinding`).
+	 */
+	private setElementPlainValueBinding;
 	ensureElementBlueprintValueBinding(elementId: string, propPath: string, input: {
 		valueType: UIElementValueBindingValueType;
 		displayName?: string;
@@ -17456,10 +17737,65 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	private scheduleAutoSave;
 	private setDirty;
 	private getHistoryService;
+	/**
+	 * Where an edit to a component definition is recorded: the definition's own undo stack, named by
+	 * the component editor's surface id (`UIEditorHistoryService` maps that to the definition's
+	 * scope). One stack per definition, so undoing in one component tab never touches another
+	 * definition or any page - and an instance on a page draws the definition from the library each
+	 * time, so putting the definition back puts every placement back with it.
+	 */
+	private componentHistory;
+	private getGraphService;
+	/**
+	 * One step on the project's undo stack, for an operation on the library as a whole - adding,
+	 * copying, deleting or importing pages and definitions.
+	 *
+	 * The project's stack rather than any editor's, for the reason {@link reorderSurfaces} gives:
+	 * these are made from the rail, and that is the stack Ctrl+Z and the Edit menu reach from there
+	 * (`resolveWorkspaceUndoScope`). A definition's own stack holds edits *inside* it, and a deleted
+	 * definition has no tab to press Ctrl+Z in.
+	 *
+	 * Each step is a command over whole records, not a snapshot of the library: whichever direction
+	 * runs reads the records as they stand at that moment and writes them back exactly, and nothing
+	 * else in the library is touched. Tagged, so a live session drops these steps with the interface
+	 * editors' stacks (`LiveSessionService`): taking back an addition after a session would remove
+	 * whatever the room built inside it.
+	 */
+	private pushLibraryStep;
+	/**
+	 * Take pages and definitions out of the project, and return them as they stood.
+	 *
+	 * Empty when nothing left this copy of the document - ids it does not hold, or an operation sink
+	 * that took the gesture: inside a live session the removal arrives as an effect later, the
+	 * lifecycle sweep collects the blueprints then, and undo is the session's.
+	 */
+	private takeLibraryRecords;
+	/**
+	 * Put records {@link takeLibraryRecords} returned back where they stood.
+	 *
+	 * Blueprints first: the sweep that follows the document write gives a widget with no blueprint a
+	 * fresh, empty one, and it must find each record's own already in place.
+	 */
+	private putLibraryRecords;
+	/**
+	 * Leave the step that takes back pages and definitions an operation just added.
+	 *
+	 * Nothing is recorded when none of them is in this copy of the document, which is what an
+	 * operation sink taking the gesture looks like (the reasoning {@link reorderSurfaces} gives).
+	 */
+	private recordLibraryAddition;
 	private getElementSurfaceId;
 	private getCommonSurfaceIdForElements;
 	private filterLinkedComponentLayoutPatch;
 	private migrateIfNeeded;
+	/**
+	 * Every page's declared parameters, in the shape this build reads (`normalizeUIPageParams`).
+	 *
+	 * A normalizer for the reason {@link normalizeInputModel} is one: an empty list and no list mean
+	 * the same thing, so a page that declares none keeps its record as short as it was. A Game UI's
+	 * are dropped - the player mounts it with nothing, so nothing could ever fill them.
+	 */
+	private normalizePageParams;
 	/**
 	 * The v13 step, for the project's own document as it is opened (`textSourceMigration.ts`).
 	 *
@@ -17653,7 +17989,14 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	getComponent(componentId: string): UIComponentDefinition | undefined;
 	getComponentUsageCount(componentId: string): number;
 	createEmptyComponent(name?: string): UIComponentDefinition;
+	/**
+	 * A new definition made of copies of elements on a page, with the logic they carry.
+	 *
+	 * The page is not changed, so the step that takes this back is the library's - the project's
+	 * stack, the one {@link createEmptyComponent} uses - rather than the page's.
+	 */
 	createComponentFromElements(surfaceId: string, elementIds: string[], name?: string): UIComponentDefinition | null;
+	/** Recorded in the definition's own undo stack, as a page's name is in the page's. */
 	renameComponent(componentId: string, name: string): void;
 	/**
 	 * Replace a component's declared params.
@@ -17661,9 +18004,25 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	 * Instances keep values for ids that survive: a param is identified by `id`, so renaming one in
 	 * the inspector does not unset it anywhere. Values for ids that were removed are left on their
 	 * instances rather than swept - re-adding a param by the same id is how an author undoes a
-	 * deletion, and sweeping would make that a data loss with no warning.
+	 * deletion, and sweeping would make that a data loss with no warning. That is also why undoing
+	 * this - one step in the definition's own stack - needs nothing from the instances: their values
+	 * were never touched, so the restored declaration finds them where it left them.
 	 */
 	setComponentParams(componentId: string, params: UIComponentParam[]): void;
+	/**
+	 * Replace the parameters a page declares.
+	 *
+	 * A parameter is identified by `id`, so the nodes that open the page and the `Get Page Param`
+	 * nodes that read it keep pointing at it through a rename. What reads it by name - the key its
+	 * value travels under - is followed in the same step where it lives on the page itself: a list on
+	 * the page bound to the old name is bound to the new one. Anything elsewhere that names it (a Page
+	 * widget on another page giving it a value, a script) is left alone, because this page's undo must
+	 * not reach into another page; the project check reports those.
+	 *
+	 * A removed parameter's values are not swept from anywhere, as a component's are not: re-adding it
+	 * is how an author takes a deletion back.
+	 */
+	setPageParams(surfaceId: string, params: UIPageParam[]): void;
 	/**
 	 * Set one param value on one instance. An empty string is a value, not a reset.
 	 *
@@ -17678,9 +18037,42 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	 * and naming none leaves the parameter with neither, which falls back to the definition's default.
 	 */
 	setComponentInstanceParamKey(elementId: string, paramId: string, keyName: string | null): void;
+	/**
+	 * Remove definitions from the library, as one step on the project's undo stack.
+	 *
+	 * Placements of them on pages are left as they are, and draw as missing until the definition is
+	 * back or they are replaced. Undo puts each definition back at its place in the library with its
+	 * widgets' blueprints and the item shapes its lists name, and every placement draws it again.
+	 */
 	deleteComponents(componentIds: string[]): void;
+	/** One copy of a definition; see {@link duplicateComponents}. */
 	duplicateComponent(componentId: string): UIComponentDefinition | null;
-	updateComponentElementLayout(componentId: string, elementId: string, layoutPatch: Partial<UILayout>): void;
+	/**
+	 * A copy of each definition, added to the end of the library, as one step on the project's undo
+	 * stack. The copies' translations are written in the background and are not part of the step:
+	 * undoing leaves them unused, and redoing finds them again (`carryCopiedTranslations`).
+	 */
+	duplicateComponents(componentIds: readonly string[]): UIComponentDefinition[];
+	private copyComponent;
+	/**
+	 * One element of a definition's layout, as `updateElementLayout` is one of a page's: an undo step
+	 * of its own, folded into the previous one when that wrote the same fields of the same element
+	 * within the merge window - so typing a number into the inspector is one step, not one a key.
+	 * `skipHistory` is for the write a gesture makes on its way to the one it records.
+	 */
+	updateComponentElementLayout(componentId: string, elementId: string, layoutPatch: Partial<UILayout>, options?: {
+		skipHistory?: boolean;
+	}): void;
+	/**
+	 * Several elements of one definition as one change: one `documentChanged` and one undo step, as
+	 * `updateElementLayouts` is on a page - a drag of three elements is undone by one Ctrl+Z.
+	 * `mergeKey` folds the step into the previous one when that carried the same key and was
+	 * recorded within the merge window, which is how a run of arrow-key nudges stays one undo.
+	 */
+	updateComponentElementLayouts(componentId: string, layoutPatches: Record<string, Partial<UILayout>>, options?: {
+		mergeKey?: string;
+	}): void;
+	private writeComponentElementLayout;
 	/**
 	 * Bind one prop of one element of a component definition to a field of its list row or to a text
 	 * parameter of the component - the two value bindings that need no blueprint - or (`null`) unbind
@@ -17697,7 +18089,9 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	 */
 	setElementComponentParamBinding(elementId: string, propPath: string, paramId: string | null): void;
 	updateComponentElementProps(componentId: string, elementId: string, propsPatch: Record<string, unknown>): void;
-	updateComponentElementAnimation(componentId: string, elementId: string, animation: UIPageAnimationSettings | null): void;
+	updateComponentElementAnimation(componentId: string, elementId: string, animation: UIPageAnimationSettings | null, options?: {
+		mergeKey?: string;
+	}): void;
 	updateComponentElementExtra(componentId: string, elementId: string, extraPatch: Record<string, unknown>): void;
 	renameComponentElement(componentId: string, elementId: string, name: string): void;
 	reorderComponentChildren(componentId: string, parentId: string, orderedChildIds: string[]): void;
@@ -18556,6 +18950,18 @@ type BlueprintNodeDeclaration = {
 	saveSchemaPins?: {
 		kind: "input" | "output";
 	};
+	/**
+	 * Grow one input per parameter the page this node opens declares (`UIPageParam`).
+	 *
+	 * The page is the one picked on the card, read from `params[surfaceParam]` - the key the node's
+	 * page picker writes. Like {@link saveSchemaPins} the list comes from a project document rather
+	 * than from the node, so every node that opens one page grows the same inputs, in the page's
+	 * order, and renaming a parameter relabels all of them. The inputs belong to the picked page: a
+	 * different page arriving on a wire is opened with the node's `props` input alone.
+	 */
+	pageParamPins?: {
+		surfaceParam: string;
+	};
 	inspectorParams?: BlueprintInspectorParamDef[];
 	role?: BlueprintNodeRole;
 	/**
@@ -19056,7 +19462,9 @@ interface IUIDocumentService extends IService {
 	updateElementLayout(elementId: string, layoutPatch: Partial<UILayout>, options?: {
 		skipHistory?: boolean;
 	}): void;
-	updateElementLayouts(layoutPatches: Record<string, Partial<UILayout>>): void;
+	updateElementLayouts(layoutPatches: Record<string, Partial<UILayout>>, options?: {
+		mergeKey?: string;
+	}): void;
 	updateElementProps(elementId: string, propsPatch: Record<string, unknown>): void;
 	ensureElementBlueprintValueBinding(elementId: string, propPath: string, input: {
 		valueType: UIElementValueBindingValueType;
@@ -19090,7 +19498,13 @@ interface IUIDocumentService extends IService {
 	renameComponent(componentId: string, name: string): void;
 	deleteComponents(componentIds: string[]): void;
 	duplicateComponent(componentId: string): UIComponentDefinition | null;
-	updateComponentElementLayout(componentId: string, elementId: string, layoutPatch: Partial<UILayout>): void;
+	duplicateComponents(componentIds: readonly string[]): UIComponentDefinition[];
+	updateComponentElementLayout(componentId: string, elementId: string, layoutPatch: Partial<UILayout>, options?: {
+		skipHistory?: boolean;
+	}): void;
+	updateComponentElementLayouts(componentId: string, layoutPatches: Record<string, Partial<UILayout>>, options?: {
+		mergeKey?: string;
+	}): void;
 	updateComponentElementProps(componentId: string, elementId: string, propsPatch: Record<string, unknown>): void;
 	updateComponentElementExtra(componentId: string, elementId: string, extraPatch: Record<string, unknown>): void;
 	renameComponentElement(componentId: string, elementId: string, name: string): void;

package/package.json

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