narraleaf-studio 1.1.0 → 1.2.0

package/dist/_api.d.ts

@@ -665,32 +665,60 @@ type StoryActionPayload = {
 } | {
 	/**
 	 * A `Video` — an Actionable, not a Displayable, which is why it has its own verb set rather
-	 * than sharing `displayable`'s. `play` waits for the clip to finish; `resume` does not.
+	 * than sharing `displayable`'s.
 	 *
-	 * `create` declares, like the `image` arm's: it compiles to `Video.preload()`, which puts a
-	 * hidden element on stage so the clip starts buffering, and `show` is what reveals it.
+	 * **`play` is the only row that puts a clip on the stage** (v27). It carries the file
+	 * ({@link assetId}) and defines the clip under {@link objectName}: it reveals the clip, runs
+	 * it, and - unless {@link hideOnEnd} says otherwise - takes it off the stage when it ends. A
+	 * second `play` of the same name and file runs that clip again.
 	 *
-	 * A `show` carrying {@link assetId} is the one-row form, on the same terms as the `image`
-	 * 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.
+	 * Every other operation names a clip a `play` defined: `pause`, `resume`, `seek`, `stop`
+	 * (end it now, as though it had reached its end - the defining play then hides it or holds
+	 * its frame, as it says) and `hide`. A video is a cutscene the story plays, not an object it
+	 * stages, so there is no row that declares or reveals a clip without running it; v27
+	 * folded the `create` and `show` rows that used to into the plays that followed them.
 	 */
 	action: "video";
-	operation: "create" | "show" | "hide" | "play" | "pause" | "resume" | "stop" | "seek";
+	operation: "hide" | "play" | "pause" | "resume" | "stop" | "seek";
 	objectName: string;
-	/** Which clip a non-`create` op addresses. Same rule as the `image` arm's `target`. */
+	/**
+	 * Which clip a control operation addresses, bound to the `play` that defines it. Same rule
+	 * as the `image` arm's `target`. A `play` carries none: it defines its clip itself.
+	 */
 	target?: StoryActionableTargetRef;
+	/** `play` — the clip it plays. Required: a play with no file plays nothing. */
 	assetId?: string;
+	/** `play` — whether the clip plays without sound. */
 	muted?: boolean;
 	/** `seek` — where to jump to, in milliseconds. The engine's `seek` takes seconds; the compiler converts. */
 	timeMs?: number;
+	/**
+	 * `play` — whether the story waits for the clip to end before it moves on.
+	 *
+	 * Absent means it waits, which is what every `play` written before this field did. `false`
+	 * lets the next row run at once while the clip plays on; the clip still leaves the stage
+	 * when it ends, as {@link hideOnEnd} says. `videoPlayWaits` is the one reading of this field.
+	 *
+	 * Added with v27; a v26 document cannot carry it.
+	 */
+	waitForEnd?: boolean;
+	/**
+	 * `play` — whether the clip leaves the stage once it has played to the end.
+	 *
+	 * Absent means it does: a clip that ends holds its last frame above every scene, across a
+	 * jump too, so clearing itself away is what a cutscene is expected to do. `false` holds that
+	 * last frame until a `hide` row takes it away. `videoPlayHidesOnEnd` is the one reading of
+	 * this field.
+	 */
+	hideOnEnd?: boolean;
+	/**
+	 * How long the clip takes to fade out, in milliseconds - on a `hide`, and on a `play` that
+	 * hides its clip when it ends. `0` is a cut.
+	 *
+	 * Unset, a `hide` cuts, as it always did, and a hiding `play` fades over the default every
+	 * other hide row is seeded with. `videoLeaveFadeMs` is the one reading of this field.
+	 */
+	durationMs?: number;
 } | {
 	/**
 	 * The story's stage camera (`story.camera`) — a Displayable like any other in the engine, but
@@ -3842,6 +3870,11 @@ declare const en: {
 				readonly removeKey: "Remove key";
 				readonly removeKeyConfirm: "Remove {name}?";
 				readonly removeKeyConfirmDetail: "Existing translations of this key stay in the language files.";
+				readonly removeKeyUsedBy: "Used by:";
+				readonly removeKeyUsedByElement: "{owner} \u25B8 {element}";
+				readonly removeKeyUsedByBlueprint: "Blueprint \u201C{name}\u201D";
+				readonly removeKeyUsedByMore: "and {count} more";
+				readonly removeKeyUsedByAfter: "Once the key is removed, the project check reports each of them.";
 				readonly sourceColumn: "Source";
 				readonly targetColumn: "Translation";
 				readonly targetPlaceholder: "Translate\u2026";
@@ -4357,7 +4390,7 @@ declare const en: {
 				readonly saveFailed: "Save failed";
 				readonly retrySave: "Retry saving now";
 				readonly resetZoom: "Reset zoom to 100%";
-				readonly shortcuts: "Keyboard shortcuts";
+				readonly shortcuts: "Shortcuts and mouse actions";
 				readonly words: {
 					readonly one: "{count} word";
 					readonly other: "{count} words";
@@ -4376,7 +4409,7 @@ declare const en: {
 					readonly studioTasks: "Background work";
 					readonly unsavedChanges: "Unsaved changes";
 					readonly wordCount: "Story stats";
-					readonly shortcuts: "Keyboard shortcuts";
+					readonly shortcuts: "Shortcuts and mouse actions";
 					readonly notifications: "Notifications";
 					readonly theme: "Theme switcher";
 					readonly zoom: "Zoom level";
@@ -4731,7 +4764,7 @@ declare const en: {
 				readonly conflict: "Also bound to {name}";
 				readonly empty: "No matching shortcuts";
 				readonly openSettings: "Customize Keyboard Shortcuts";
-				readonly cheatSheetTitle: "Keyboard Shortcuts";
+				readonly cheatSheetTitle: "Shortcuts and Mouse Actions";
 				readonly cheatSheetCustomize: "Customize\u2026";
 				readonly categories: {
 					readonly general: "General";
@@ -4750,7 +4783,7 @@ declare const en: {
 				readonly catalog: {
 					readonly commandPalette: "Show and Run Commands";
 					readonly quickOpen: "Quick Open";
-					readonly cheatSheet: "Show Keyboard Shortcuts";
+					readonly cheatSheet: "Show Shortcuts and Mouse Actions";
 					readonly contextHelp: "Help for What Is Focused";
 					readonly reopenClosedTab: "Reopen Closed Tab";
 					readonly localizationFind: "Find in Translations";
@@ -4805,6 +4838,104 @@ declare const en: {
 						readonly playheadEnd: "Move Playhead to End";
 					};
 				};
+				readonly gestures: {
+					readonly withModifiers: "{keys}+{gesture}";
+					readonly middleClickTab: "Middle-click a tab";
+					readonly doubleClickTab: "Double-click a tab";
+					readonly clickTab: "Click a tab";
+					readonly doubleClickDivider: "Double-click the divider";
+					readonly doubleClickRow: "Double-click a row";
+					readonly clickRow: "Click a row";
+					readonly dragAcrossRows: "Drag across rows";
+					readonly dragRowHandle: "Drag a row's handle";
+					readonly clickName: "Click a name";
+					readonly dragHandle: "Drag a handle";
+					readonly arrowKeys: "Arrow keys";
+					readonly middleDrag: "Middle-drag";
+					readonly scroll: "Scroll";
+					readonly drag: "Drag";
+					readonly clickElement: "Click an element";
+					readonly doubleClickContainer: "Double-click a container";
+					readonly doubleClickText: "Double-click text or a button";
+					readonly doubleClickImage: "Double-click an image";
+					readonly dragImageAsset: "Drag an image asset onto the canvas";
+					readonly doubleClickOutlineItem: "Double-click an outline item";
+					readonly dragOutlineItem: "Drag an outline item";
+					readonly clickNode: "Click a node";
+					readonly rightClickCanvas: "Right-click the canvas";
+					readonly dragPinToCanvas: "Drag from a pin onto empty canvas";
+					readonly doubleClickWire: "Double-click a wire";
+					readonly doubleClickGroupTitle: "Double-click a group's title";
+					readonly middleClickTitle: "Middle-click the title row";
+					readonly doubleClickTrack: "Double-click a track";
+					readonly clickAsset: "Click an asset";
+					readonly doubleClick: "Double-click";
+					readonly dragToEditorArea: "Drag into the editor area";
+					readonly dragOntoGroup: "Drag onto a group";
+					readonly dragWaveform: "Drag on the waveform";
+					readonly doubleClickWaveform: "Double-click the waveform";
+					readonly doubleClickMarker: "Double-click a marker";
+					readonly doubleClickPicture: "Double-click the picture";
+					readonly doubleClickTimeline: "Double-click the timeline";
+				};
+				readonly fixed: {
+					readonly toggleSelection: "Add to or Remove from Selection";
+					readonly addToSelection: "Add to Selection";
+					readonly panCanvas: "Pan the Canvas";
+					readonly zoomAtPointer: "Zoom at the Pointer";
+					readonly easingSnap: "Snap an Easing Handle to the Grid";
+					readonly easingNudge: "Nudge a Focused Easing Handle";
+					readonly general: {
+						readonly keepTabOpen: "Keep a Preview Tab Open";
+						readonly selectTabs: "Select Several Tabs";
+						readonly resetSplit: "Split the Editor Area Evenly";
+					};
+					readonly story: {
+						readonly selectRowRange: "Select a Range of Rows";
+						readonly moveRows: "Move Rows";
+						readonly followReference: "Go to What a Name Refers To";
+						readonly continueRow: "Commit and Continue With the Same Kind of Row";
+						readonly blankRow: "Commit and Start a Blank Row";
+						readonly finishEditing: "Finish Editing a Row";
+						readonly pastePlain: "Paste Without Paste as Rows";
+					};
+					readonly uiEditor: {
+						readonly selectInside: "Select Inside a Container";
+						readonly editText: "Edit Text in Place";
+						readonly discardText: "Discard the Text Being Edited";
+						readonly crop: "Crop an Image";
+						readonly suspendSnap: "Suspend Smart Snap";
+						readonly dropImage: "Add an Image Element";
+						readonly reorder: "Reorder or Move Into Another Element";
+					};
+					readonly blueprint: {
+						readonly addNode: "Add a Node";
+						readonly addConnectedNode: "Add a Connected Node";
+						readonly deleteWire: "Delete a Wire";
+						readonly deleteSelection: "Delete Selection";
+						readonly renameGroup: "Rename a Group";
+					};
+					readonly storyMotion: {
+						readonly noFrameSnap: "Drag Without Frame Snapping";
+						readonly addKeyframe: "Add a Keyframe";
+						readonly panPreview: "Pan the Preview";
+						readonly zoom: "Zoom the Preview or Timeline";
+						readonly scrollTimeline: "Scroll the Timeline Sideways";
+					};
+					readonly assets: {
+						readonly selectAssetRange: "Select a Range of Assets";
+						readonly open: "Open";
+						readonly moveToGroup: "Move to a Group";
+						readonly tileSize: "Resize Thumbnails";
+						readonly audioScroll: "Scroll the Waveform Sideways";
+						readonly audioZoomTime: "Zoom the Waveform in Time";
+						readonly audioZoomAmplitude: "Magnify the Waveform Vertically";
+						readonly selectAudioRange: "Select a Stretch of Audio";
+						readonly clearMarker: "Clear a Marker";
+						readonly videoZoom: "Zoom the Picture";
+						readonly videoActualSize: "Switch Between Fit and Actual Pixels";
+					};
+				};
 			};
 			readonly search: {
 				readonly placeholder: "Search project\u2026";
@@ -4908,7 +5039,7 @@ declare const en: {
 				readonly other: "Its {count} scenes are deleted with it.";
 			};
 			readonly deleteSceneConfirm: "Delete scene \"{name}\"?";
-			readonly deleteSceneDetail: "This removes the scene and its blocks. Jumps to it will stop resolving.";
+			readonly deleteSceneDetail: "This removes the scene and all its rows. Jumps to it will stop resolving.";
 		};
 		readonly readFailed: {
 			readonly missing: "This story is no longer in this project.";
@@ -5003,9 +5134,9 @@ declare const en: {
 			readonly undoSceneRestored: "That scene is in the story again.";
 			readonly undoChapterGone: "That chapter is gone.";
 			readonly undoChapterRestored: "That chapter is in the story again.";
-			readonly undoContainerGone: "The block that line was in is gone.";
+			readonly undoContainerGone: "The row that line was inside is gone.";
 			readonly undoAnchorGone: "Where that line moved from is gone.";
-			readonly undoContainerFilled: "That block has lines in it now.";
+			readonly undoContainerFilled: "That row has other lines inside it now.";
 			readonly undoSubtreeLost: "The lines that were inside it cannot be put back.";
 			readonly undoChaptersChanged: "The chapters are not the ones that step recorded.";
 			readonly undoCharacterGone: "That character is gone.";
@@ -5450,6 +5581,7 @@ declare const en: {
 			readonly mirrorState: "On / Off";
 			readonly waitFor: "Seconds or click";
 			readonly waitForEnd: "Wait for the clip";
+			readonly hideOnEnd: "Hide when finished";
 			readonly fade: "Fade Seconds";
 			readonly loop: "Loop";
 			readonly returnable: "Return";
@@ -5894,7 +6026,7 @@ declare const en: {
 				readonly image: "Image \u201C{name}\u201D is not on stage; an earlier row has to create it.";
 				readonly text: "Text \u201C{name}\u201D is not on stage; an earlier row has to create it.";
 				readonly layer: "Layer \u201C{name}\u201D is not on stage; an earlier row has to create it.";
-				readonly video: "Video \u201C{name}\u201D is not on stage; an earlier row has to create it.";
+				readonly video: "Video \u201C{name}\u201D is not on stage; an earlier row has to play it.";
 				readonly ambience: "Ambience effect \u201C{name}\u201D is not on stage; an earlier row has to create it.";
 				readonly character: "Character \u201C{name}\u201D is not on stage; an earlier row has to bring it on stage.";
 				readonly characterGone: "The character this row acts on is no longer in this project, so it is not on stage.";
@@ -6034,7 +6166,7 @@ declare const en: {
 			};
 			readonly show: {
 				readonly label: "Show";
-				readonly detail: "Show a character, a stage object, or an image or video from the asset library";
+				readonly detail: "Show a character, a stage object, or an image from the asset library";
 			};
 			readonly hide: {
 				readonly label: "Hide";
@@ -6072,10 +6204,6 @@ declare const en: {
 				readonly label: "Text";
 				readonly detail: "Declare text on stage; /show reveals it";
 			};
-			readonly video: {
-				readonly label: "Video";
-				readonly detail: "Declare a video on stage; /show reveals it";
-			};
 			readonly vfx: {
 				readonly label: "Ambience";
 				readonly detail: "Declare a looping full-screen overlay: petals, rain, dust, light";
@@ -6090,7 +6218,7 @@ declare const en: {
 			};
 			readonly play: {
 				readonly label: "Play";
-				readonly detail: "Play a video on stage, or a video from the asset library";
+				readonly detail: "Play a video from the asset library, or play a video again";
 			};
 			readonly front: {
 				readonly label: "Bring to Front";
@@ -6233,10 +6361,10 @@ declare const en: {
 			readonly condition: "Condition";
 			readonly if: "If";
 			readonly elseIf: "Else if";
-			readonly else: "Otherwise";
+			readonly else: "Else";
 			readonly repeat: "Repeat";
 			readonly repeatUntil: "Repeat until";
-			readonly parallel: "Run at the same time";
+			readonly parallel: "Parallel";
 			readonly race: "Race, first to finish";
 			readonly sequence: "In order";
 			readonly nvl: "NVL";
@@ -6247,7 +6375,7 @@ declare const en: {
 			readonly declare: {
 				readonly scene: "Local";
 				readonly saved: "Var";
-				readonly persistent: "Global";
+				readonly persistent: "Persistent";
 			};
 			readonly narration: "Narration";
 			readonly dialogue: "Dialogue";
@@ -6877,7 +7005,7 @@ declare const en: {
 			readonly setZIndex: "Set z-index";
 		};
 		readonly videoOperation: {
-			readonly play: "Play (wait for end)";
+			readonly play: "Play";
 			readonly pause: "Pause";
 			readonly resume: "Resume";
 			readonly stop: "Stop";
@@ -6957,6 +7085,10 @@ declare const en: {
 			readonly videoName: "Video name";
 			readonly videoAsset: "Video asset";
 			readonly seekTime: "Seek to";
+			readonly hideOnEnd: "Hide when finished";
+			readonly leave: "Exit";
+			readonly waitForEnd: "Wait for the video";
+			readonly skipHint: "The player can end the video early by clicking or pressing the skip key.";
 		};
 		readonly nvl: {
 			readonly hint: "Child rows run in NVL mode. The transform below animates the NVL layer as it enters.";
@@ -7022,8 +7154,8 @@ declare const en: {
 			readonly conditionContainer: "Condition container. Add condition branches as children.";
 			readonly control: "Control";
 			readonly sequence: "Sequence";
-			readonly parallel: "Parallel all";
-			readonly race: "Race any";
+			readonly parallel: "Parallel";
+			readonly race: "Race";
 			readonly repeat: "Repeat";
 			readonly mode: {
 				readonly do: "Do";
@@ -7187,6 +7319,7 @@ declare const en: {
 			readonly list: "List view";
 			readonly icons: "Icon view";
 			readonly overview: "Overview";
+			readonly details: "Details view";
 		};
 		readonly filter: {
 			readonly label: "Filters";
@@ -7205,6 +7338,17 @@ declare const en: {
 		readonly list: {
 			readonly emptyFiltered: "No assets matched the current filters.";
 		};
+		readonly browser: {
+			readonly results: {
+				readonly one: "{count} result";
+				readonly other: "{count} results";
+			};
+			readonly selected: {
+				readonly one: "{count} selected";
+				readonly other: "{count} selected";
+			};
+			readonly location: "Location";
+		};
 		readonly iconView: {
 			readonly updating: "Updating\u2026";
 			readonly assetCount: {
@@ -7354,13 +7498,13 @@ declare const en: {
 				readonly locale: "Language";
 				readonly release: "Variant";
 			};
-			readonly deletedVariant: "Deleted variant";
+			readonly deletedVariant: "Deleted value";
 			readonly variantCount: {
-				readonly one: "{count} variant";
-				readonly other: "{count} variants";
+				readonly one: "{count} value";
+				readonly other: "{count} values";
 			};
-			readonly variantsResolved: "{resolved} of {total} variants";
-			readonly unfinished: "No variants declared";
+			readonly variantsResolved: "{resolved} of {total} values";
+			readonly unfinished: "No values declared";
 			readonly inUseTitle: "{name} is still in use";
 			readonly inUseMessage: "The following places name it and will stop resolving:";
 			readonly deleteConfirmMessage: "The files inside this set are deleted too.";
@@ -7375,7 +7519,7 @@ declare const en: {
 			};
 			readonly create: {
 				readonly title: "New asset set";
-				readonly subTitle: "New set under this variant";
+				readonly subTitle: "New set under this value";
 				readonly no: {
 					readonly locale: "This project declares one language.";
 					readonly release: "This project has no variants.";
@@ -7388,8 +7532,8 @@ declare const en: {
 				readonly filter: "Members carry";
 				readonly residencyBlocked: "A set that varies by variant cannot sit under one that varies by language.";
 				readonly fallback: "Falls back to";
-				readonly fallbackMissing: "This variant has no file, so nothing in this set resolves.";
-				readonly variants: "Variants";
+				readonly fallbackMissing: "This value has no file, so nothing in this set resolves.";
+				readonly variants: "Values";
 				readonly variantInherited: "fallback";
 				readonly variantMissing: "No file";
 				readonly variantAmbiguous: "{count} files";
@@ -7679,7 +7823,7 @@ declare const en: {
 		readonly tab: {
 			readonly title: "Blueprint";
 			readonly invalid: "Blueprint tab is invalid.";
-			readonly notFound: "Blueprint not found: {id}";
+			readonly notFound: "Blueprint not found in this project";
 		};
 		readonly breakpoint: {
 			readonly add: "Add breakpoint";
@@ -7713,6 +7857,14 @@ declare const en: {
 				readonly other: "Deleted the unknown node and its {count} hidden connections. Undo to restore.";
 			};
 		};
+		readonly wire: {
+			readonly nodeDetail: "{node} ({detail})";
+			readonly end: "{node} \u00B7 {pin}";
+			readonly connectedTo: "Connected to {target}";
+			readonly goTo: "Go to {target}";
+			readonly goToNth: "Go to {target} ({n})";
+			readonly goToConnected: "Go to connected node";
+		};
 		readonly crossProject: {
 			readonly pasted: {
 				readonly one: "{count} node pasted";
@@ -7975,6 +8127,7 @@ declare const en: {
 				readonly keys: "Keys";
 				readonly window: "Window";
 				readonly display: "Display";
+				readonly conditions: "Conditions";
 			};
 		};
 		readonly owner: {
@@ -8894,6 +9047,7 @@ declare const en: {
 			readonly getVisible: "Get Visible";
 			readonly getWrapMode: "Get Wrap Mode";
 			readonly goPage: "Go Page";
+			readonly replacePage: "Replace Page";
 			readonly goBack: "Go back";
 			readonly showLayer: "Show Layer";
 			readonly hideLayer: "Hide Layer";
@@ -9161,6 +9315,8 @@ declare const en: {
 			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 replacePage: "Opens a page in place of the current page, and closes the current page. Go back and Go Page set to None do not return to it.";
+			readonly isGameOverlay: "True when this page, layer or Game UI is shown over a running game. In the global blueprint, true while a page or a modal layer covers the story.";
 		};
 		readonly live: {
 			readonly nodeClaimed: "{name} is editing this node";
@@ -9265,7 +9421,7 @@ declare const en: {
 				readonly describeOk: "Filled from the model";
 				readonly describeNoModel: "No model to read";
 				readonly describeNoBackend: "No runtime chosen";
-				readonly describeBackendMissing: "Runtime not installed here";
+				readonly describeBackendMissing: "Runtime not installed in this project";
 				readonly describeDistrusted: "Project not trusted";
 				readonly describeNotSupported: "This runtime lists nothing";
 				readonly describeFailed: "The model could not be read";
@@ -9423,10 +9579,10 @@ declare const en: {
 			readonly editorTitle: "Character Properties";
 			readonly thumbnail: "Thumbnail";
 			readonly preview: "Preview";
-			readonly defaultAvatar: "Dialog avatar";
-			readonly voiceTrack: "Voice bus";
-			readonly voiceTrackMissing: "Missing bus";
-			readonly voiceTrackEmpty: "Add a bus under Voice in Project \u25B8 Game to give this character its own volume control.";
+			readonly defaultAvatar: "Default dialog avatar";
+			readonly voiceTrack: "Voice track";
+			readonly voiceTrackMissing: "Missing track";
+			readonly voiceTrackEmpty: "Add a track under Voice in Project \u25B8 Game to give this character its own volume control.";
 			readonly entrance: "Entrance defaults";
 			readonly entranceEmpty: "Entrance rows use the stage's own values until this is set.";
 			readonly entranceDrag: "Drag to place";
@@ -10028,7 +10184,7 @@ declare const en: {
 			readonly hint: "Defined in the project; the value lives in the save file.";
 		};
 		readonly persistent: {
-			readonly title: "Global variables";
+			readonly title: "Persistent variables";
 			readonly hint: "Defined in the project; app-level, shared with blueprints.";
 		};
 	};
@@ -10057,8 +10213,8 @@ declare const en: {
 		readonly ownerLabel: {
 			readonly globalMain: "App logic";
 			readonly surfaceMain: "Page logic";
-			readonly widgetMain: "Component logic";
-			readonly widgetValue: "Component value";
+			readonly widgetMain: "Widget logic";
+			readonly widgetValue: "Widget value";
 			readonly storyAction: "Story action";
 		};
 		readonly stageSlot: {
@@ -10097,6 +10253,10 @@ declare const en: {
 			readonly pageValidationHint: "Check the page name and size before creating it.";
 			readonly gameUiSlotHint: "Select an available Game UI slot before creating it.";
 			readonly allSlotsUsed: "All Game UI slots already have a surface. Open an existing Game UI from the list.";
+			readonly starterTitlePage: {
+				readonly title: "Create Title Page";
+				readonly description: "Includes Start and Continue buttons with their blueprints. Replaces the empty entry page.";
+			};
 		};
 		readonly naming: {
 			readonly page: "Page {index}";
@@ -10206,6 +10366,8 @@ declare const en: {
 		readonly canvas: {
 			readonly unknownWidget: "Unknown widget";
 			readonly widgetRenderFailed: "Widget failed to draw";
+			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 editor: {
 			readonly componentNotFound: "Component not found";
@@ -10256,7 +10418,7 @@ declare const en: {
 			readonly showSelected: "Show selected";
 			readonly hideSelected: "Hide selected";
 			readonly addToComponentLibrary: "Add to Component Library";
-			readonly addToGroup: "Add to group";
+			readonly group: "Group";
 			readonly ungroup: "Ungroup";
 			readonly addState: "Add state";
 			readonly arrange: {
@@ -10373,7 +10535,7 @@ declare const en: {
 			readonly interaction: "Interaction";
 		};
 		readonly blueprint: {
-			readonly controlLabel: "Component logic";
+			readonly controlLabel: "Widget logic";
 		};
 		readonly appearance: {
 			readonly title: "Appearance";
@@ -10431,7 +10593,14 @@ declare const en: {
 			readonly enableItalic: "Enable italic";
 			readonly disableItalic: "Disable italic";
 		};
+		readonly sampleText: {
+			readonly label: "Sample text";
+			readonly hint: "Shown in the editor only. The game shows the story's current line.";
+			readonly bindingNoEffect: "This binding has no effect in the {slot} slot.";
+			readonly removeBinding: "Remove";
+		};
 		readonly localization: {
+			readonly direct: "Direct";
 			readonly translationKey: "Translation key";
 			readonly noSourceLanguage: "The project has no source language";
 			readonly none: "None";
@@ -10450,7 +10619,7 @@ declare const en: {
 			readonly title: "List";
 			readonly sectionContent: "Content";
 			readonly runtimeItems: "Runtime items";
-			readonly runtimePreviewOnly: "Preview only";
+			readonly runtimeListContent: "List content";
 			readonly runtimePageState: "Page state array";
 			readonly runtimeAppState: "App state array";
 			readonly runtimePageProps: "Page props array";
@@ -10528,8 +10697,6 @@ declare const en: {
 			readonly value: "Value";
 			readonly valueHint: "Starting text. What the player types is held by the running game, not by this document.";
 			readonly placeholder: "Placeholder";
-			readonly placeholderKey: "Placeholder key";
-			readonly placeholderKeyHint: "The placeholder is shown to the player: attach a key to translate it.";
 			readonly sectionBehavior: "Behavior";
 			readonly inputMode: "Input mode";
 			readonly inputModeText: "Text";
@@ -10588,7 +10755,6 @@ declare const en: {
 			readonly start: "Start";
 			readonly center: "Center";
 			readonly end: "End";
-			readonly stretch: "Stretch";
 			readonly spaceBetween: "Space between";
 			readonly spaceAround: "Space around";
 			readonly gapHint: "Gap between children";
@@ -10737,6 +10903,9 @@ declare const en: {
 			readonly container: {
 				readonly name: "Container";
 			};
+			readonly group: {
+				readonly name: "Group";
+			};
 			readonly dialog: {
 				readonly name: "Sentence";
 				readonly text: "The current line will appear here.";
@@ -11493,15 +11662,15 @@ declare const en: {
 			};
 			readonly bgmVolume: {
 				readonly title: "Music volume";
-				readonly description: "The Music bus.";
+				readonly description: "The Music track.";
 			};
 			readonly soundVolume: {
 				readonly title: "SFX volume";
-				readonly description: "The SFX bus.";
+				readonly description: "The SFX track.";
 			};
 			readonly voiceVolume: {
 				readonly title: "Voice volume";
-				readonly description: "The Voice bus.";
+				readonly description: "The Voice track.";
 			};
 			readonly voiceEndMode: {
 				readonly title: "When a voiced line ends";
@@ -11544,18 +11713,18 @@ declare const en: {
 			};
 			readonly deleteConfirm: "Delete \"{name}\"?";
 			readonly deleteDetail: {
-				readonly one: "{count} reference falls back to its default bus.";
-				readonly other: "{count} references fall back to their default bus.";
+				readonly one: "{count} reference falls back to its default track.";
+				readonly other: "{count} references fall back to their default track.";
 			};
 			readonly deleteChildren: {
 				readonly one: "{count} track under it moves to {parent}.";
 				readonly other: "{count} tracks under it move to {parent}.";
 			};
 			readonly slider: {
-				readonly bgm: "BGM Volume";
-				readonly sound: "Sound Volume";
-				readonly voice: "Voice Volume";
-				readonly global: "Global Volume";
+				readonly bgm: "Music volume";
+				readonly sound: "SFX volume";
+				readonly voice: "Voice volume";
+				readonly global: "Master volume";
 			};
 		};
 		readonly settings: {
@@ -11760,6 +11929,10 @@ declare const en: {
 				readonly label: "Help";
 				readonly description: "How the parts of Studio behave.";
 			};
+			readonly titlePage: {
+				readonly label: "New Title Page";
+				readonly description: "Start and Continue buttons included.";
+			};
 		};
 		readonly reopenHint: {
 			readonly menu: "Reopen this page from Help \u2192 Open Welcome.";
@@ -12287,6 +12460,7 @@ declare const en: {
 			readonly page: "Page";
 			readonly layer: "Layer";
 			readonly faded: "Faded out";
+			readonly dialogHidden: "Hidden";
 			readonly hiddenForGame: "Hidden while the game runs";
 			readonly returnsOnBack: "Shown again on Go back";
 			readonly onScreenCount: "{onScreen} of {total} on screen";
@@ -12631,6 +12805,7 @@ declare const en: {
 		readonly createGroup: {
 			readonly title: "Create Group";
 			readonly prompt: "Please enter a name for the {type} group";
+			readonly promptIn: "Please enter a name for the group in {parent}";
 			readonly placeholder: "Enter group name\u2026";
 			readonly empty: "Group name cannot be empty";
 		};
@@ -12790,12 +12965,20 @@ declare const en: {
 		};
 		readonly unavailable: {
 			readonly windows: "Cannot build Windows apps on this machine.";
-			readonly macos: "macOS apps can only be built on a Mac.";
+			readonly macos: "Cannot build macOS apps on this machine.";
 			readonly linux: "Cannot build Linux apps on this machine.";
 			readonly web: "Web builds are available on every machine.";
 			readonly android: "Android builds are available on every machine.";
 			readonly ios: "iOS builds are available on every machine.";
 		};
+		readonly formatUnavailable: {
+			readonly windows: "Not available on this machine.";
+			readonly macos: "Requires a Mac.";
+			readonly linux: "Not available on Windows.";
+			readonly web: "Not available on this machine.";
+			readonly android: "Not available on this machine.";
+			readonly ios: "Not available on this machine.";
+		};
 		readonly format: {
 			readonly zip: "Portable ZIP";
 			readonly nsis: "Installer";
@@ -12847,15 +13030,15 @@ declare const en: {
 			readonly appId: "App ID";
 			readonly copyright: "Copyright";
 			readonly icons: "Icons";
-			readonly iconsHint: "Click an icon to change it in project settings";
+			readonly iconsHint: "Click an icon to change it in Project \u25B8 App";
 			readonly iconUnset: "Not set";
 			readonly notSet: "Not set";
 			readonly editInProject: "Edit in Project \u25B8 App";
 		};
 		readonly content: {
 			readonly protection: "Asset protection";
-			readonly protectionOn: "Assets and saves are encrypted in the packaged game.";
-			readonly protectionOff: "Assets and saves ship unencrypted.";
+			readonly protectionOn: "Assets are encrypted in the packaged game.";
+			readonly protectionOff: "Assets ship unencrypted.";
 			readonly plugins: "Bundled plugins";
 			readonly pluginsNone: "No plugins are bundled with this game.";
 			readonly pluginsRescanUnavailable: "The plugin list cannot be rescanned in this window.";
@@ -12903,6 +13086,7 @@ declare const en: {
 			readonly artifactReadVersioned: "{product} {version}, built {date}";
 			readonly artifactVariantStated: "Read from the build folder.";
 			readonly artifactVariantUnknown: "This build does not state its variant. Select it below.";
+			readonly artifactNoKey: "This build was made without a distribution key. The game ignores any patch exported for it.";
 			readonly artifactVariantMismatch: "This build is {build}. The DLC attaches to {variant}.";
 			readonly artifactWholeGame: "The patch includes the whole game.";
 			readonly contentLabel: "Variant the content comes from";
@@ -13014,6 +13198,7 @@ declare const en: {
 		readonly preflight: {
 			readonly "no-targets": "Select at least one platform and format.";
 			readonly "unbuildable-platform": "This machine cannot build for {platform}.";
+			readonly "unbuildable-format": "This machine cannot build the {format} format for {platform}.";
 			readonly "version-invalid": "Version {version} is not a valid semantic version; the build will fail.";
 			readonly "version-missing": "No version set; the game builds as 0.0.0.";
 			readonly "identifier-missing": "No project identifier; using the app id {appId}.";
@@ -13033,6 +13218,7 @@ declare const en: {
 			readonly "sidecar-crossbuild-exec-bit": string;
 			readonly "web-unprotected": "Asset protection does not apply to the web export; its files ship unprotected.";
 			readonly "mobile-unprotected": "Asset protection does not apply to Android or iOS packages.";
+			readonly "distribution-key-missing": "No distribution key. The game this build produces will not accept patches.";
 			readonly "progress-carry-unsupported": string;
 			readonly "lossy-images": "Images are re-encoded at quality {setting} and lose detail permanently.";
 			readonly "lossy-audio": "Audio is re-encoded at {setting} kbit/s and loses detail permanently.";
@@ -13480,6 +13666,11 @@ declare const en: {
 				readonly description: "Two rows creating one stage name; the second reuses the first";
 				readonly message: "{object} is already created above, so this row acts on that one";
 			};
+			readonly storyVideoControlAfterEnd: {
+				readonly title: "Video already finished";
+				readonly description: "A row pausing, resuming, seeking or stopping a video after a play that waits for its end";
+				readonly message: "{object} has already finished playing at this line; to continue while it plays, turn off \u201CWait for the video\u201D on its play row";
+			};
 			readonly storyCharacterMissing: {
 				readonly title: "Missing character";
 				readonly description: "A row naming a character the project does not have";
@@ -13588,6 +13779,16 @@ declare const en: {
 				readonly description: "A widget bound to an item field the list drawing it does not declare";
 				readonly message: "This is bound to an item field the list does not declare, so every row shows the same value";
 			};
+			readonly uiListTextUntranslated: {
+				readonly title: "Untranslated list content";
+				readonly description: "Words written into a list's content in a project that has a second language";
+				readonly message: "{text} and the rest of this list's content show as written in every language";
+			};
+			readonly uiLocalizationKeyMissing: {
+				readonly title: "Missing localization key";
+				readonly description: "A widget reading its words from a key the project does not have";
+				readonly message: "Reads its words from {key}, which the project does not have";
+			};
 			readonly uiGestureAnsweredTwice: {
 				readonly title: "Gesture answered twice";
 				readonly description: "A widget with a pointer handler of its own, on a page whose action answers the same gesture";
@@ -14062,7 +14263,7 @@ declare const en: {
 			readonly added: "Track added";
 			readonly removed: "Track removed";
 			readonly renamed: "Renamed";
-			readonly rerouted: "Routes into a different bus";
+			readonly rerouted: "Routes into a different track";
 			readonly reroutedToMaster: "Routes into the master output";
 			readonly volume: "Volume changed";
 			readonly loopOn: "Loops by default";
@@ -14077,7 +14278,7 @@ declare const en: {
 			readonly defaultValue: "Default value changed";
 			readonly valueType: "Type changed";
 			readonly scopeSaved: "Now a saved variable";
-			readonly scopeGlobal: "Now a global variable";
+			readonly scopeGlobal: "Now a persistent variable";
 			readonly storageKey: "Values already saved are no longer found";
 			readonly description: "Note changed";
 			readonly changed: "Variable changed";
@@ -14675,7 +14876,7 @@ declare const en: {
 				readonly body: string;
 			};
 			readonly keyboard: {
-				readonly title: "Keyboard";
+				readonly title: "Keyboard and Mouse";
 				readonly body: string;
 			};
 			readonly search: {
@@ -14718,6 +14919,10 @@ declare const en: {
 				readonly title: "Editing outside Studio";
 				readonly body: string;
 			};
+			readonly storyPaste: {
+				readonly title: "Paste as Rows";
+				readonly body: string;
+			};
 			readonly sceneSnapshot: {
 				readonly title: "Playing from a row";
 				readonly body: string;
@@ -14731,7 +14936,7 @@ declare const en: {
 				readonly body: string;
 			};
 			readonly storyMotion: {
-				readonly title: "Motion";
+				readonly title: "Story Motion";
 				readonly body: string;
 			};
 			readonly assets: {
@@ -15086,6 +15291,8 @@ declare const en: {
 			readonly storyStarted: "Load Save: \"{id}\" was written in another of the project's stories, which was started to receive it.";
 			readonly relaunchedRow: "Load Save: \"{id}\" was written by another build. The story was started again on the line the save records.";
 			readonly relaunchedScene: "Load Save: \"{id}\" was written by another build and the line it records is no longer present. The story was started again at the start of that scene.";
+			readonly rowLaunchRelaunchedRow: "Load Save: \"{id}\" was written in a run started with Play from this row. The story was started again on the line the save records.";
+			readonly rowLaunchRelaunchedScene: "Load Save: \"{id}\" was written in a run started with Play from this row, and the line it records is no longer present. The story was started again at the start of that scene.";
 			readonly detail: {
 				readonly unreadable: "The save could not be read. {error}";
 				readonly missing: "No save is stored under that id.";
@@ -16812,6 +17019,17 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 		blueprintId: string;
 	};
 	clearElementBlueprintValueBinding(elementId: string, propPath: string): void;
+	/**
+	 * Close the editor tabs showing a value blueprint that clearing its binding has just removed.
+	 *
+	 * The blueprint is the binding's own - minted for this element's prop and named for it - but the
+	 * author writes their logic into it, so its removal is one step on the page's undo history above,
+	 * blueprint included. A tab left open on it said only that the blueprint could not be found, and
+	 * while it stayed the active editor the inspector's Ctrl+Z went to its stack instead of the page's,
+	 * so the step that would bring the logic back was out of reach from where the author was. Closed,
+	 * the page the binding belongs to is the editor the inspector edits again.
+	 */
+	private closeTabsShowingBlueprint;
 	/**
 	 * How this element arrives and leaves. `null` clears it.
 	 *
@@ -16834,6 +17052,22 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	 * reparents an inner one that may be in the same batch.
 	 */
 	ungroupContainers(surfaceId: string, containerIds: string[]): string[];
+	/**
+	 * Wrap elements in a new group - an invisible container that takes their place - and return the
+	 * group's id, or null when they cannot be wrapped (see `planGroupElements` for which can, and
+	 * for why nothing on screen moves).
+	 *
+	 * One mutation, so Undo puts the tree back as it was in one step.
+	 */
+	groupElements(surfaceId: string, elementIds: readonly string[]): string | null;
+	/**
+	 * Rename one layer.
+	 *
+	 * A linked component instance renames like any other layer: its name is copied from the
+	 * definition once, when the instance is placed, and is the instance's own from then on - it is
+	 * how the outline tells "save slot 1" from "save slot 2". Props and shape are what the definition
+	 * owns, and their own setters still refuse them on an instance.
+	 */
 	renameElement(elementId: string, name: string): void;
 	deleteElements(elementIds: string[]): void;
 	/**
@@ -17070,6 +17304,16 @@ declare class UIDocumentService extends Service<UIDocumentService> implements IU
 	reorderComponentChildren(componentId: string, parentId: string, orderedChildIds: string[]): void;
 	deleteComponentElements(componentId: string, elementIds: string[]): void;
 	moveComponentElements(componentId: string, elementIds: string[], targetParentId: string, beforeChildId: string | null): MoveUiElementsResult;
+	/**
+	 * `ungroupContainers` for a component definition's elements, over a document made of the
+	 * component alone. Returns the ids that were lifted out.
+	 */
+	ungroupComponentContainers(componentId: string, containerIds: readonly string[]): string[];
+	/**
+	 * `groupElements` for a component definition's elements: the same plan, read and applied over a
+	 * document made of the component alone, as `moveComponentElements` does.
+	 */
+	groupComponentElements(componentId: string, elementIds: readonly string[]): string | null;
 	createComponentElement(componentId: string, parentId: string, type: string, layoutPatch?: Partial<UILayout>): UIElement | null;
 	pasteComponentClipboardPayload(componentId: string, targetParentId: string, beforeChildId: string | null, payload: UIEditorClipboardPayload): {
 		ok: true;
@@ -17182,18 +17426,29 @@ type WidgetLogicWritablePropDef = {
 export type WidgetLogicApi = {
 	supportsPrivateBlueprint: boolean;
 	blueprintLabel?: string;
+	/**
+	 * The events a private blueprint on this widget can be started by. Every entry is load-bearing:
+	 * the node palette, graph validation, the dispatcher and `ui.js widget` all read this list, so an
+	 * event belongs here only once the runtime raises it and a head node for it is registered.
+	 */
 	events: readonly WidgetLogicEventDef[];
+	/**
+	 * `commands`, `readableState` and `writableProps` describe the widget to a reader - `ui.js
+	 * widget` prints them - and nothing executes them: no blueprint node looks a widget up in these
+	 * lists. What a graph can actually do to a widget is in the node catalogue.
+	 */
 	commands: readonly WidgetLogicCommandDef[];
 	readableState: readonly WidgetLogicReadableStateDef[];
 	writableProps: readonly WidgetLogicWritablePropDef[];
 	/**
 	 * Whether the player operates this widget directly - a Button, a Switch, a Slider, a Text Input,
 	 * a list they pick a row from. Scenery (Container, Text, Image, Video, Model, the page host)
-	 * leaves it unset.
+	 * leaves it unset. A Video with its native controls showing is operable too, but that is a prop
+	 * on the instance, so `isOperableHitElement` in `surfaceInputActions.ts` answers it there.
 	 *
-	 * Declared rather than derived, and the retreat is deliberate. A panel-wide gesture has to stand
-	 * down over a control (`overControls: "skip"` in `inputAction.ts`), so something has to answer
-	 * "is this a control", and the tempting derivation - "declares an interaction event beyond the
+	 * Declared rather than derived, and the retreat is deliberate. A panel-wide gesture stands down
+	 * over a control (`pointerInputClaimedByControl` in `surfaceInputActions.ts`), so something has
+	 * to answer "is this a control", and the tempting derivation - "declares an interaction event beyond the
 	 * shared displayable set" - is wrong at both ends: `nl.button` declares exactly the displayable
 	 * set, and `nl.frame` declares `pageEvent`. Nothing else in an entry separates a Button from a
 	 * Container, because what makes a Button a control is how the runtime draws and handles it, not
@@ -17216,6 +17471,12 @@ export interface ContextMenuItemDef {
 	 * than in the label keeps a disabled menu a menu instead of a paragraph.
 	 */
 	tooltip?: string;
+	/**
+	 * The chord that runs the same command, already formatted for this platform (callers resolve it
+	 * through `useShortcutLabels`, so a rebound key shows rebound). Printed at the right of the row:
+	 * a menu that names a command without its key is the reason the key stays undiscovered.
+	 */
+	shortcut?: string;
 	onClick?: () => void;
 	submenu?: ContextMenuItemDef[];
 	/**
@@ -18474,6 +18735,12 @@ export type StoryPluginActionRegistration = {
 	detail?: string;
 	group?: string;
 	createBlock: (input: StoryPluginActionCreateInput) => StoryBlock;
+	/**
+	 * The text a committed row of this action reads as, from the params the row carries; `label`
+	 * when absent, or when it returns nothing. A row's params are otherwise invisible in the scene
+	 * editor, so an action whose params change what the row does says what they are here.
+	 */
+	describe?: (params: Record<string, unknown>) => string | null | undefined;
 };
 declare const HELP_TOPIC_IDS: readonly [
 	"gettingHelp",
@@ -18490,6 +18757,7 @@ declare const HELP_TOPIC_IDS: readonly [
 	"storyExpressions",
 	"storyFlow",
 	"storyScript",
+	"storyPaste",
 	"sceneSnapshot",
 	"storyMotion",
 	"dictionary",
@@ -18927,6 +19195,31 @@ export interface StoryCompilePass {
 	/** Called once per scene, before that scene's rows are compiled. */
 	scene(ctx: SceneCompileContext): void;
 }
+/** What a plugin story action's `run` receives. */
+export type RuntimeStoryActionContext = {
+	/** The params the row carries: whatever the studio entry's `createBlock` wrote. */
+	params: Record<string, unknown>;
+	/**
+	 * Aborted when the row is cancelled: the player rolls back past it, or loads a save, while it is
+	 * still running. Tear down whatever `run` put on screen and stop; nothing it does after this
+	 * reaches the story.
+	 */
+	signal: AbortSignal;
+	/** The very same object `setup(app)` received as `app.game`. */
+	game: RuntimePluginGame;
+};
+/**
+ * The game-side half of a plugin story action.
+ *
+ * `run` may be async, and the story waits for it: the next row starts once the promise settles. A
+ * save taken while it runs replays the row on load, so `run` must be able to start again from
+ * nothing. A throw is logged and the story carries on.
+ */
+export type RuntimeStoryActionDef = {
+	/** The same id the studio entry registered the action under, prefixed with the plugin id. */
+	id: string;
+	run(ctx: RuntimeStoryActionContext): void | Promise<void>;
+};
 /**
  * The detail on `nl.launch`: where this page sits on the launch's own timeline.
  *
@@ -19521,7 +19814,7 @@ export type RuntimePluginStory = {
 /**
  * The game-side plugin surface.
  *
- * Everything below the always-present five is **capability-gated**: a domain the
+ * Everything below the always-present six is **capability-gated**: a domain the
  * manifest did not declare is *absent from this object*, not a method that
  * throws. That is the whole contract — the install prompt lists exactly the
  * domains present here, so what the user approved and what the plugin can do are
@@ -19536,6 +19829,18 @@ export type RuntimePluginGame = {
 		register(def: RuntimeWidgetRendererDef): void;
 		registerMany(defs: RuntimeWidgetRendererDef[]): void;
 	};
+	/**
+	 * What runs when the story reaches a row one of this plugin's story actions inserted. The id is
+	 * the one the studio entry registered the action under; the story waits on the row until `run`
+	 * settles. See {@link RuntimeStoryActionDef}.
+	 *
+	 * Always present, like `blueprintNodes`: a runner only ever runs on a row the author placed, and
+	 * only on this plugin's own rows, so it grants nothing an install prompt would have to name.
+	 */
+	storyActions: {
+		register(def: RuntimeStoryActionDef): void;
+		registerMany(defs: RuntimeStoryActionDef[]): void;
+	};
 	/**
 	 * Read-only access to plugin storage published with the game, for the
 	 * namespaces declared in `contributes.runtimeData`. Synchronous: the

package/dist/runtime.d.ts

@@ -56,6 +56,8 @@ export {
 	RuntimePluginTimelineName,
 	RuntimePluginTimelineSpanDetails,
 	RuntimePluginTimelineSpanName,
+	RuntimeStoryActionContext,
+	RuntimeStoryActionDef,
 	RuntimeWidgetRendererDef,
 	RuntimeWidgetRendererProps,
 	SceneCompileContext,

package/package.json

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