narraleaf-studio 0.7.0 → 0.8.0

package/dist/_api.d.ts

@@ -11,7 +11,6 @@
 // Generated by dts-bundle-generator v9.5.1
 
 import { LucideIcon } from 'lucide-react';
-import { TextGlyphOrientation, TextWritingMode as NlrTextWritingMode } from 'narraleaf-react';
 import React$1 from 'react';
 import { ComponentType, InputHTMLAttributes, ReactElement, ReactNode, RefObject } from 'react';
 
@@ -1422,92 +1421,6 @@ type StoryAlignPositionValue = {
 	xoffset?: number;
 	yoffset?: number;
 };
-type BlueprintDebugEvent = {
-	type: "execution.started";
-	executionId: string;
-	blueprintId: string;
-} | {
-	type: "execution.finished";
-	executionId: string;
-	blueprintId: string;
-} | {
-	type: "execution.cancelled";
-	executionId: string;
-	blueprintId?: string;
-	eventId?: string;
-	graphId?: string;
-	nodeId?: string;
-	reason?: string;
-} | {
-	type: "node.enter";
-	executionId: string;
-	nodeId: string;
-} | {
-	type: "node.exit";
-	executionId: string;
-	nodeId: string;
-} | {
-	type: "state.read";
-	scope: string;
-	key: string;
-} | {
-	type: "state.write";
-	scope: string;
-	key: string;
-} | {
-	type: "binding.evaluated";
-	bindingId: string;
-} | {
-	type: "function.call";
-	functionId: string;
-} | {
-	type: "function.return";
-	functionId: string;
-} | {
-	type: "devtools.log";
-	level: string;
-	message: string;
-} | {
-	/**
-	 * A node ran with one of its required data inputs left unconnected and no value on the
-	 * card, so the pin resolved to nothing.
-	 *
-	 * Its own event rather than a `devtools.log`, because it has a place: an issue list can
-	 * put it on a surface, and a repeat of it on the same pin is the same problem rather than
-	 * a second line of output. Carries the node's and the pin's English names off the
-	 * catalogue, which is what a host that has no node-title map (the shipped game) can still
-	 * write into a player's log.
-	 */
-	type: "node.input_missing";
-	executionId: string;
-	nodeId: string;
-	/** The node's display name as its definition declares it. */
-	nodeName: string;
-	/** The unwired pin's label as its definition declares it. */
-	pinLabel: string;
-	blueprintId?: string;
-	eventId?: string;
-	graphId?: string;
-	/** See the note on `execution.error`: what lets a host say "the Quick Menu". */
-	surfaceId?: string;
-} | {
-	type: "execution.error";
-	executionId: string;
-	message: string;
-	blueprintId?: string;
-	eventId?: string;
-	graphId?: string;
-	nodeId?: string;
-	/**
-	 * The UI surface whose graph failed, when the failure happened on one.
-	 *
-	 * The rest of this event names OUR ids - a blueprint, a graph, a node - none of which an
-	 * author can find their way back from. A surface id resolves against the document they
-	 * drew, which is what lets a host say "the Quick Menu" rather than "bp:8f2c1a…". Absent on
-	 * the global blueprint, which belongs to no surface.
-	 */
-	surfaceId?: string;
-};
 type BlueprintOwnerRef = {
 	kind: "globalMain";
 } | {
@@ -1747,70 +1660,6 @@ type BlueprintDiagnostic = {
 	/** Source span or module location; M1 opaque */
 	location?: Record<string, unknown>;
 };
-type LocaleCode = string;
-type LocalizationLocaleEntry = {
-	code: LocaleCode;
-	/** Author-facing autonym shown to players (e.g. "日本語", never "Japanese"). */
-	displayName: string;
-	/** Optional intermediate fallback locale tried before the source locale. */
-	fallback?: LocaleCode;
-};
-type GameLocalizationBundle = {
-	sourceLocale: LocaleCode;
-	locales: LocalizationLocaleEntry[];
-	tables: Record<LocaleCode, Record<string, string>>;
-	/** Named-key source texts (key name → source-language text). */
-	keys?: Record<string, string>;
-	/**
-	 * Scene-name source texts (scene id → source-language name), for the scenes this build ships.
-	 *
-	 * The same job `keys` does for named keys: a translation table only holds the *target* side, so
-	 * without this a `scene:` reference read while the game is in the source language has nothing to
-	 * render but the id. Assembled from the story documents the bundle carries, so a scene a variant
-	 * dropped is absent here too.
-	 */
-	scenes?: Record<string, string>;
-};
-type SaveRecordTimes = {
-	/** When this slot was last written, epoch milliseconds; 0 when the record carries no stamp. */
-	savedAt: number;
-	/** When this slot was first written, epoch milliseconds; 0 when the record carries no stamp. */
-	createdAt: number;
-};
-type SaveRecordPlaytime = {
-	/** Seconds of play behind the slot; 0 when nothing was recorded. */
-	seconds: number;
-	/** False when the slot carries no reading at all. */
-	recorded: boolean;
-};
-type SaveRecordLine = {
-	/** The last sentence shown, or "" when the record carries none. */
-	line: string;
-	/** Who spoke it, or "" when the record carries no speaker (narration, or none yet). */
-	speaker: string;
-};
-type SaveRecordStory = {
-	/** The story the save was written in, as an opaque reference; "" when the record carries none. */
-	id: string;
-	/** That story's author-facing name; "" when this build ships no story under that reference. */
-	name: string;
-};
-type AutoSaveEntry = {
-	id: string;
-	/** Slot index within the ring. */
-	slot: number;
-	/** When this slot was last written, epoch milliseconds. */
-	timestamp: number;
-	/** When this slot was first written, epoch milliseconds. */
-	createdAt: number;
-	/** Whatever the writer attached as user metadata (null when none). */
-	metadata: unknown;
-};
-type VoiceLocaleEntry = {
-	code: LocaleCode;
-	/** Author-facing autonym shown for this voice language (e.g. "日本語"). */
-	displayName: string;
-};
 type AudioClipRegion = {
 	/** Offset from the start of the clip, in milliseconds. Where playback starts. */
 	inMs?: number;
@@ -1838,67 +1687,7 @@ type BlueprintOpenExternalResult = {
 	/** Human-readable reason, null when the page was handed over. */
 	error: string | null;
 };
-type BlueprintPointerMoveOutcome = 
-/** The cursor is now at the requested point. */
-"moved"
-/** This shell cannot move the cursor: a web export, or a host with no platform support. */
- | "unsupported"
-/** The move was attempted and failed. */
- | "failed";
-type BlueprintPointerMoveResult = {
-	outcome: BlueprintPointerMoveOutcome;
-	error?: string;
-};
-declare const BLUEPRINT_POINTER_MOVE_EASINGS: readonly [
-	"linear",
-	"easeIn",
-	"easeOut",
-	"easeInOut"
-];
-type BlueprintPointerMoveEasing = (typeof BLUEPRINT_POINTER_MOVE_EASINGS)[number];
-type BlueprintScreenshotOutcome = "saved" | "failed";
-type BlueprintScreenshotResult = {
-	outcome: BlueprintScreenshotOutcome;
-	/** The file that was written, absolute, or null when nothing was. */
-	path: string | null;
-	/** Why nothing was written. Null on success. */
-	error: string | null;
-};
-type BlueprintOpenScreenshotsResult = {
-	outcome: "opened" | "failed";
-	/** The folder that was opened, absolute, or null when none was. */
-	path: string | null;
-	error: string | null;
-};
 type BlueprintGraphKind = "event" | "function" | "macro";
-declare const BLUEPRINT_NETWORK_METHODS: readonly [
-	"GET",
-	"POST",
-	"PUT",
-	"PATCH",
-	"DELETE",
-	"HEAD"
-];
-type BlueprintNetworkMethod = typeof BLUEPRINT_NETWORK_METHODS[number];
-type BlueprintNetworkFetchRequest = {
-	url: string;
-	method: BlueprintNetworkMethod;
-	/** Header name -> value. Null and `{}` both mean "send none". */
-	headers: Record<string, string> | null;
-	/** Request body, for the methods that carry one. */
-	body: string | null;
-	timeoutMs: number;
-};
-type BlueprintNetworkFetchOutcome = "success" | "httpError" | "networkError" | "timeout";
-type BlueprintNetworkFetchResult = {
-	outcome: BlueprintNetworkFetchOutcome;
-	/** HTTP status, or 0 when no response was received. */
-	status: number;
-	/** Response body text, present whenever a response arrived. */
-	body: string | null;
-	/** Human-readable failure reason, null on success. */
-	error: string | null;
-};
 type GameBuildPlatform = "windows" | "macos" | "linux" | "web" | "android" | "ios";
 type PluginPermissionPersistence = "temporary" | "permanent";
 type PluginFileSystemPermissionMode = "read" | "write" | "readwrite";
@@ -2044,6 +1833,24 @@ declare const PluginRuntimeCapability: {
 	 * declared.
 	 */
 	readonly StoryCompile: "story.compile";
+	/**
+	 * `app.game.diagnostics` — read what the player's caches are holding.
+	 *
+	 * The lightest of the list to grant and the easiest to misread as heavier than it is. Nothing
+	 * here is authored data: it reports how many images the engine is holding, how many bytes those
+	 * cost, and what budgets they are being held against. It reads no story, no save and no
+	 * variable, and every member is a read - there is nothing to set.
+	 *
+	 * It is its own capability rather than free like `data` and `config` because a plugin that
+	 * watches memory is a plugin that runs continuously and reports numbers about the player's
+	 * machine, and an author should see that named at install. The performance inspector is the
+	 * plugin this exists for.
+	 *
+	 * Absent until a game session is live, which is the same rule every other engine-backed member
+	 * follows: a plugin's `setup()` runs during boot, and asking then answers null rather than
+	 * throwing.
+	 */
+	readonly Diagnostics: "diagnostics";
 };
 type PluginRuntimeCapability = typeof PluginRuntimeCapability[keyof typeof PluginRuntimeCapability];
 /**
@@ -2397,11 +2204,6 @@ export type RuntimePluginDescriptor = {
 	 */
 	buildConfig?: Record<string, string>;
 };
-type GameProgressImportOutcome = {
-	outcome: "found" | "missing" | "failed";
-	sceneId: string;
-	error: string;
-};
 type GameMenuLabel = {
 	readonly key?: string | null;
 	readonly text: string;
@@ -2511,13 +2313,6 @@ type GameMenuSpecMenu = {
 type GameMenuSpec = {
 	readonly menus: readonly GameMenuSpecMenu[];
 };
-type UIInputActionSource = "pointer" | "key" | "gamepad" | "touch";
-type UIInputActionEventPayload = {
-	actionId: string;
-	source: UIInputActionSource;
-	x?: number;
-	y?: number;
-};
 declare const UI_INPUT_POINTER_GESTURES: readonly [
 	"click",
 	"doubleClick",
@@ -2823,30 +2618,6 @@ type UILayout = {
 	lockAspectRatio?: boolean;
 };
 type UIStyle = Record<string, unknown>;
-type GameStorageDurability = "durable" | "evictable" | "unknown";
-type DevModeStartStoryRequest = {
-	storyId: StoryId;
-	sceneId: string;
-	/** Row-precise "play from here": enter the game pre-posed at this block and play forward. */
-	startBlockId?: string;
-	/** Scene Snapshot (变量快照) whose variable overrides seed the launch. */
-	snapshotId?: string;
-	/**
-	 * Variable values lifted off a running game, laid over the launch's own stage walk.
-	 *
-	 * Set only by a hot reload resuming where the player was: the walk reconstructs what the values
-	 * would be had the story been played from the top down one path, and these are what they
-	 * actually were. Applied after the walk and after any Scene Snapshot, because they are the later
-	 * state - re-seeding either over them would rewind the player.
-	 *
-	 * Storage keys, the way the compiler names namespace entries, not variable ids. Persistent
-	 * values are absent by design: they outlive the run, so a reload has nothing to restore.
-	 */
-	resume?: {
-		sceneVariables: Record<string, StoryLiteralValue>;
-		savedVariables: Record<string, StoryLiteralValue>;
-	};
-};
 type GameTestLogLevel = "verbose" | "info" | "success" | "warning" | "error";
 type GameTestExitReason = 
 /** Closed from inside the game - the window's own close, or the engine quitting itself. */
@@ -9680,6 +9451,10 @@ declare const en: {
 			};
 			readonly refs: "{count} refs";
 		};
+		readonly canvas: {
+			readonly unknownWidget: "Unknown widget";
+			readonly widgetRenderFailed: "Widget failed to draw";
+		};
 		readonly editor: {
 			readonly componentNotFound: "Component not found";
 			readonly interfaceNotFound: "Interface not found";
@@ -10524,6 +10299,7 @@ declare const en: {
 			readonly insert: "Insert {name}";
 			readonly drawing: "Drawing {name}: drag on canvas to create";
 			readonly moreInsertElements: "More insert elements";
+			readonly fromPlugin: "From {plugin}";
 			readonly components: "Components";
 			readonly openComponentLibrary: "Open Component Library";
 			readonly componentLibrary: "Component Library";
@@ -11825,6 +11601,7 @@ declare const en: {
 				readonly locale: "Read the game language and the project's localized text";
 				readonly menu: "Provide the game's menu bar";
 				readonly storyCompile: "Take part in compiling stories, and add actions to lines it did not write";
+				readonly diagnostics: "Read how much memory the game\u2019s caches are using";
 			};
 		};
 		readonly button: {
@@ -11936,6 +11713,25 @@ declare const en: {
 			readonly registry: "Failed to reach the plugin registry";
 			readonly download: "Failed to download plugin";
 		};
+		readonly dependencies: {
+			readonly title: "Project dependencies";
+			readonly unavailable: {
+				readonly one: "{count} plugin this project needs is not available.";
+				readonly other: "{count} plugins this project needs are not available.";
+			};
+			readonly allReady: "Every plugin this project needs is available.";
+			readonly open: "Open dependencies";
+			readonly installAll: "Install all";
+			readonly updated: "Updated";
+			readonly authorized: "Authorized";
+			readonly notInRegistry: "Not in the registry";
+			readonly noCompatibleVersion: "No compatible version";
+			readonly task: {
+				readonly running: "Installing dependencies\u2026";
+				readonly done: "Dependencies installed.";
+				readonly partial: "Some plugins were not installed.";
+			};
+		};
 		readonly workspace: {
 			readonly reload: "Reload in this workspace";
 			readonly activity: {
@@ -11947,7 +11743,6 @@ declare const en: {
 				readonly suppressedHint: "The installed version is incompatible with the one this project was authored against. Update it, or update the project's dependency table from Project \u25B8 App.";
 				readonly failed: "Failed to load";
 			};
-			readonly suppressedNotice: "Not loaded for this project: {names}. The installed version is incompatible with the one the project was authored against. See the Plugins panel.";
 			readonly pendingReopen: "Takes effect the next time this project opens.";
 			readonly restartHint: "Some plugin changes take effect only after the workspace is restarted.";
 			readonly restart: "Restart";
@@ -12886,6 +12681,11 @@ declare const en: {
 				readonly description: "A clickable widget nothing listens to";
 				readonly message: "Nothing runs when this is clicked";
 			};
+			readonly uiUnknownWidget: {
+				readonly title: "Unknown widget type";
+				readonly description: "A widget whose type the project cannot load";
+				readonly message: "{type} is not loaded, so this widget will not be drawn in the game";
+			};
 			readonly uiComponentMissing: {
 				readonly title: "Missing component";
 				readonly description: "An instance of a component the project does not have";
@@ -14818,26 +14618,6 @@ export declare const AssetExtensions: {
 	model: string[];
 	other: string[];
 };
-type BlueprintVector2D = {
-	x: number;
-	y: number;
-};
-type BlueprintRect = {
-	x: number;
-	y: number;
-	width: number;
-	height: number;
-};
-type BlueprintRGBAColor = {
-	r: number;
-	g: number;
-	b: number;
-	a: number;
-};
-type BlueprintImageAsset = {
-	kind: "imageAsset";
-	assetId: string;
-};
 type BlueprintAssetPinKind = "image" | "audio" | "font";
 type BlueprintAssetPinRef = {
 	kind: BlueprintAssetPinKind;
@@ -14856,10 +14636,6 @@ type BlueprintAssetPinRef = {
 	 */
 	origin?: "stored" | "published";
 };
-type BlueprintSoundHandle = {
-	kind: "soundHandle";
-	id: string;
-};
 interface ProjectProps {
 	projectPath: string;
 }
@@ -15895,33 +15671,6 @@ type UIElementSelection = {
 	elementIds: UIElementId[];
 	primaryId?: UIElementId;
 };
-type GradientKind = "linear" | "radial" | "conic";
-interface GradientStop {
-	/** 0..1 along the gradient line. */
-	offset: number;
-	/**
-	 * A stored colour string: a literal, or `nlbrand:<id>[/<alpha>]`. Deliberately unresolved - see
-	 * the file comment.
-	 */
-	color: string;
-}
-interface GradientFill {
-	kind: GradientKind;
-	/** Normalised to two or more, sorted by offset, offsets clamped to 0..1. */
-	stops: GradientStop[];
-	/** Linear and conic. Degrees, CSS convention: 0 points to the top, 90 to the right. */
-	angle?: number;
-	/** Radial and conic. 0..1 of the painted box. */
-	center?: {
-		x: number;
-		y: number;
-	};
-	/** Radial. 0..1 of the painted box, one radius per axis. */
-	radius?: {
-		x: number;
-		y: number;
-	};
-}
 type ImageFillMode = "cover" | "contain" | "stretch" | "crop" | "tile";
 interface ImageFillCropPlacement {
 	leftPct: number;
@@ -15956,1030 +15705,97 @@ type UIListItemScope = {
 	 */
 	struct?: UIStructDef | null;
 };
-type UIListScrollMetrics = {
-	offset: number;
-	maxOffset: number;
-	progress: number;
-};
-declare const BLUEPRINT_HOST_API_CONTRACT_VERSION: 39;
-type BlueprintHostApiContractVersion = typeof BLUEPRINT_HOST_API_CONTRACT_VERSION;
-type BlueprintCharacterInfo = {
-	id: string;
-	/** Author-facing display name. Empty when the character is unnamed - never falls back to `id`, which is a UUID. */
-	name: string;
-	/**
-	 * The author's accent colour, already in pin shape. Null when the character has no colour set,
-	 * which is a different thing from "white" - see {@link blueprintCharacterColorOrDefault} for
-	 * what a non-nullable colour pin does with it.
-	 */
-	color: BlueprintRGBAColor | null;
-	/** The character's default dialog avatar, or null when it has none. */
-	avatar: BlueprintImageAsset | null;
-};
-type AppearanceSystemCondition = Partial<{
-	hovered: boolean;
-	active: boolean;
-	disabled: boolean;
-	focused: boolean;
-	/** Inside the row a list has selected. */
-	selected: boolean;
-}>;
-type AppearanceRowValue = string | number | boolean | null | ImageFill | GradientFill | Record<string, unknown>;
-type AppearanceValueRow = {
-	conditions?: AppearanceSystemCondition | null;
-	value: AppearanceRowValue;
-};
-type AppearanceTransitionTweenEasing = "linear" | "easeIn" | "easeOut" | "easeInOut" | "circIn" | "circOut" | "circInOut";
-type AppearanceFieldTransition = {
-	type: "tween";
-	durationMs: number;
-	delayMs?: number;
-	easing: AppearanceTransitionTweenEasing;
-} | {
-	type: "spring";
-	delayMs?: number;
-	stiffness: number;
-	damping: number;
-	mass: number;
-};
-type ContainerAppearancePropertyKey = "backgroundColor" | "borderRadius" | "borderRadiusTL" | "borderRadiusTR" | "borderRadiusBL" | "borderRadiusBR" | "borderRadiusLinked" | "borderColor" | "borderWidth" | "borderStyle" | "backgroundImage" | "backgroundFit" | "imageFill" | "gradientFill" | "fillType" | "fillVisible" | "fillOpacity" | "strokeVisible" | "strokeOpacity" | "strokeAlign" | "strokeSide" | "borderJoin" | "cornerAdvanced" | "transformOffsetX" | "transformOffsetY" | "transformScale" | "transformRotation" | "transformOpacity" | "effectBlur" | "effectBackgroundBlur" | "effectShadow" | "effectInnerShadow" | "effectBlend" | "effectGlow" | "effectFilter";
-declare const BUTTON_CURSOR_VALUES: readonly [
-	"auto",
-	"default",
-	"pointer",
-	"text",
-	"move",
-	"grab",
-	"grabbing",
-	"crosshair",
-	"help",
-	"wait",
-	"progress",
-	"not-allowed"
-];
-type ButtonCursorValue = (typeof BUTTON_CURSOR_VALUES)[number];
-type ButtonAppearancePropertyKey = "fontAssetId" | "fontSize" | "fontWeight" | "color" | "lineHeight" | "backgroundColor" | "fillType" | "fillOpacity" | "fillVisible" | "imageFill" | "gradientFill" | "backgroundImage" | "backgroundFit" | "borderRadius" | "borderWidth" | "borderColor" | "borderStyle" | "strokeOpacity" | "strokeSide" | "borderJoin" | "strokeAlign" | "paddingX" | "paddingY" | "clipContent" | "cursor" | "transformOffsetX" | "transformOffsetY" | "transformScale" | "transformRotation" | "transformOpacity" | "effectBlur" | "effectBackgroundBlur" | "effectShadow" | "effectTextShadow" | "effectInnerShadow" | "effectBlend" | "effectGlow" | "effectFilter";
-type TextAppearancePropertyKey = "fontAssetId" | "fontSize" | "fontWeight" | "fontStyle" | "color" | "lineHeight" | "transformOffsetX" | "transformOffsetY" | "transformScale" | "transformRotation" | "transformOpacity" | "effectBlur" | "effectTextShadow" | "effectBlend" | "effectFilter";
-type AppearancePropertyGroup = {
-	key: ContainerAppearancePropertyKey;
-	rows: AppearanceValueRow[];
-	transition?: AppearanceFieldTransition | null;
-} | {
-	key: ButtonAppearancePropertyKey;
-	rows: AppearanceValueRow[];
-	transition?: AppearanceFieldTransition | null;
-} | {
-	key: TextAppearancePropertyKey;
-	rows: AppearanceValueRow[];
-	transition?: AppearanceFieldTransition | null;
-};
-type AppearanceVariant = {
-	id: string;
-	name: string;
-	propertyGroups: AppearancePropertyGroup[];
-};
-type AppearanceModel = {
-	defaultVariantId: string;
-	variants: AppearanceVariant[];
-};
-type UISliderOrientation = "horizontal" | "vertical";
-type UISliderWidgetProps = {
-	value: number;
-	min: number;
-	max: number;
-	step: number;
-	orientation: UISliderOrientation;
-	trackElementId?: string | null;
-	handleElementId?: string | null;
-};
-type UISliderRange = {
-	min: number;
-	max: number;
-	step: number;
-};
-type UISliderRuntimeValue = UISliderRange & {
-	value: number;
-	normalizedValue: number;
-};
-type UISwitchWidgetProps = {
-	/** The author's starting state. What the player toggles lives in WidgetRuntimeStateStore. */
-	checked: boolean;
-	/** Blocks pointer and keyboard toggling. Looks are the `disabled` appearance signal's job. */
-	interactionDisabled: boolean;
-	trackElementId?: string | null;
-	thumbElementId?: string | null;
-};
-type UISwitchRuntimeValue = {
-	checked: boolean;
-};
-type UITextInputMode = "text" | "password" | "number";
-type UITextInputWidgetProps = {
-	value: string;
-	placeholder: string;
-	/** i18n attach-layer key for `placeholder`; player-facing text is never a Studio catalog key. */
-	placeholderLocalizationKey?: string | null;
-	inputMode: UITextInputMode;
-	/** 0 = unlimited. */
-	maxLength: number;
-	readOnly: boolean;
-	disabled: boolean;
-	textAlign: "left" | "center" | "right";
-};
-type UITextInputRuntimeValue = {
-	value: string;
-	/** Length in code points, so an emoji counts once - this is what `maxLength` is measured in. */
-	length: number;
-};
-type UIDisplayableMotionFromCurrentValue = {
-	from: "current";
-	to: number;
-};
-type UIDisplayableMotionValue = number | number[] | UIDisplayableMotionFromCurrentValue;
-type UIDisplayableMotionTarget = {
-	x?: UIDisplayableMotionValue;
-	y?: UIDisplayableMotionValue;
-	scale?: UIDisplayableMotionValue;
-	rotate?: UIDisplayableMotionValue;
-	opacity?: UIDisplayableMotionValue;
-};
-type UIDisplayableMotionTransition = {
-	type: "tween";
-	durationMs: number;
-	delayMs?: number;
-	easing?: string;
-} | {
-	type: "spring";
-	delayMs?: number;
-	stiffness: number;
-	damping: number;
-	mass: number;
-};
-type UIDisplayableMotionOverride = {
-	id: string;
-	target: UIDisplayableMotionTarget;
-	transition: UIDisplayableMotionTransition;
-	/** One-shot effects such as shake/pulse should hand control back to authored layout when finished. */
-	resetOnComplete?: boolean;
-};
-type TextWritingMode = NlrTextWritingMode;
-type TextOrientation = TextGlyphOrientation;
-type UITextRunMarks = Pick<StoryTextMarks, "bold" | "italic" | "color" | "ruby" | "fontSizeStep" | "emphasis">;
-type UITextRun = {
-	text: string;
-	marks?: UITextRunMarks;
-};
-type EffectShadowLayerData = {
-	offsetX: number;
-	offsetY: number;
-	blur: number;
-	spread: number;
-	color: string;
-};
-type FilterPresetId = "brightness" | "contrast" | "saturate" | "grayscale";
-type EffectShadowLayer = EffectShadowLayerData;
-type EffectShadowStored = {
-	storage: "layer";
-	layer: EffectShadowLayer;
-} | {
-	storage: "css";
-	css: string;
-};
-type EffectFilterStored = {
-	storage: "preset";
-	preset: FilterPresetId;
-	amount: number;
-} | {
-	storage: "css";
-	css: string;
-};
-type ElementEffectValues = {
-	effectBlur: number;
-	effectBackgroundBlur: number;
-	effectShadow: EffectShadowStored | null;
-	/** Text widgets: CSS text-shadow (separate from box-shadow `effectShadow`). */
-	effectTextShadow: EffectShadowStored | null;
-	effectInnerShadow: EffectShadowStored | null;
-	effectBlend: string;
-	effectGlow: EffectShadowStored | null;
-	effectFilter: EffectFilterStored | null;
-};
-type TextAlign = "left" | "center" | "right";
-type TextVerticalAlign = "start" | "center" | "end";
-type TextWrapMode = "word" | "character" | "nowrap";
-type TextWidgetProps = {
-	text: string;
-	/**
-	 * The label's text as marked runs, when it carries any.
-	 *
-	 * `text` stays the plain string and stays what everything else reads - a value binding writes
-	 * it, a translation replaces it, a plain field edits it - and these runs are only drawn while
-	 * they still spell it (`resolveUITextRuns`). Absent on every label that has never been marked,
-	 * which is what keeps the drawing of a plain label exactly what it was.
-	 */
-	rich?: UITextRun[];
-	/** Game-localization opt-in: registers the implicit translation unit `ui:<elementId>.text`. */
-	localizable?: boolean;
-	/** Named localization key reference; takes precedence over the implicit unit. */
-	localizationKey?: string;
-	fontSize: number;
-	color: string;
-	fontWeight: "normal" | "bold" | "600";
-	fontStyle: "normal" | "italic";
-	textAlign: TextAlign;
-	textVerticalAlign: TextVerticalAlign;
-	lineHeight: number;
-	/** Project font asset id when using a custom typeface in the editor; null inherits canvas default */
-	fontAssetId: string | null;
-	textWrapMode: TextWrapMode;
-	/**
-	 * Shrink the rendered text until it fits the element's box.
-	 *
-	 * The authored `fontSize` becomes a ceiling rather than a fixed value: the text is never set
-	 * larger than it, and never smaller than {@link TextWidgetProps.textAutoFitMinFontSize}. A line
-	 * that still does not fit at the floor is clipped, which is what every line does today.
-	 */
-	textAutoFit: boolean;
-	/** Smallest size auto fit may set, in px. */
-	textAutoFitMinFontSize: number;
-	/** Block flow. `horizontal-tb` leaves every other vertical setting inert. */
-	writingMode: TextWritingMode;
-	textOrientation: TextOrientation;
-	/**
-	 * 縦中横: sets a short Latin or digit run upright across the column instead of on its side,
-	 * the way a Japanese novel sets a two-digit number. Only read while writing vertically.
-	 */
-	tateChuYoko: boolean;
-	/** Longest run tate-chu-yoko combines, in characters. Two is the typographic convention. */
-	tateChuYokoMaxLength: number;
-	transformOffsetX: number;
-	transformOffsetY: number;
-	transformScale: number;
-	transformRotation: number;
-	transformOpacity: number;
-	/** Static baseline effects; appearance overlays may override per variant / state. */
-	effects: ElementEffectValues;
-	/** Optional variant + conditional row visuals; when absent, flat props are the sole source. */
-	appearance?: AppearanceModel | null;
-};
-type BlueprintPointerMoveOptions = {
-	durationSeconds?: number;
-	easing?: BlueprintPointerMoveEasing;
-};
-type BlueprintTextProperties = Pick<TextWidgetProps, "text" | "fontAssetId" | "fontSize" | "fontWeight" | "color" | "textAlign" | "textVerticalAlign" | "lineHeight" | "textWrapMode" | "effects">;
-type BlueprintTextPropertiesPatch = Partial<BlueprintTextProperties>;
-type BlueprintSliderProperties = UISliderRuntimeValue;
-type BlueprintSliderPropertiesPatch = Partial<Pick<UISliderWidgetProps, "value" | "min" | "max" | "step">>;
-type BlueprintSwitchProperties = UISwitchRuntimeValue;
-type BlueprintSwitchPropertiesPatch = Partial<Pick<UISwitchWidgetProps, "checked">>;
-type BlueprintTextInputProperties = UITextInputRuntimeValue;
-type BlueprintTextInputPropertiesPatch = Partial<Pick<UITextInputWidgetProps, "value">>;
-type BlueprintListProperties = {
-	items: unknown[];
-	selectedIndex: number;
-	/**
-	 * The shape the list declares, or null when it declares none.
-	 *
-	 * Carried with the items rather than fetched separately, because every node that reads a field
-	 * needs both and reading them apart is how the two drift: a graph that sorted by a field the
-	 * list no longer declares would sort by nothing and report success.
-	 */
-	struct: UIStructDef | null;
-	/**
-	 * Where the list has got to along its axis, as it last measured itself.
-	 *
-	 * A list that has not been rendered - or has been rendered somewhere with no runtime store, like
-	 * a Surface thumbnail - reports at-rest rather than nothing, so a graph asking gets the answer
-	 * for a list that cannot scroll instead of an undefined it has no way to branch on.
-	 */
-	scroll: UIListScrollMetrics;
-};
-type BlueprintDisplayableProperties = {
-	position: {
-		x: number;
-		y: number;
-	};
-	offset: {
-		x: number;
-		y: number;
-	};
-	/**
-	 * The extent the widget covers, never negative. The authored layout may hold a negative width
-	 * or height - that is how a widget dragged past its own origin is stored - and `position`
-	 * already reports the true top-left, so reporting the raw sign here would have described a
-	 * rectangle whose right edge sits left of its left edge.
-	 */
-	size: {
-		width: number;
-		height: number;
-	};
-	bounds: BlueprintRect;
-	rotation: number;
-	opacity: number;
-	display: boolean;
-	visible: boolean;
-};
-type BlueprintDisplayablePropertiesPatch = Partial<{
-	x: number;
-	y: number;
-	offsetX: number;
-	offsetY: number;
-	width: number;
-	height: number;
-	rotation: number;
-	opacity: number;
-	display: boolean;
-	visible: boolean;
-}>;
-type BlueprintDisplayableMotionRequest = {
-	id?: string;
-	target: UIDisplayableMotionTarget;
-	transition: UIDisplayableMotionTransition;
-	resetOnComplete?: boolean;
-	commitLayoutOnComplete?: Partial<Pick<BlueprintDisplayablePropertiesPatch, "x" | "y">>;
-};
-type BlueprintWidgetCommonProperties = {
-	visible: boolean;
-	enabled: boolean;
-	variantId: string | null;
-};
-type BlueprintButtonProperties = {
-	label: string;
-	cursor: ButtonCursorValue;
-};
-type BlueprintContainerProperties = {
-	clipContent: boolean;
+type BehaviorNodeExecuteResult = {
+	nextPort?: string;
+	nextPorts?: string[];
+	outputValues?: Record<string, unknown>;
 };
-type BlueprintImageProperties = {
-	asset: BlueprintImageAsset | null;
-	/** Legacy patch/read alias kept so older saved graph nodes can still run. */
-	assetId: string | null;
-	fitMode: ImageFillMode;
-	cropRect: ImageFillCropPlacement;
-	flipX: boolean;
-	flipY: boolean;
+type StoryBlockSelection = {
+	editor: "story";
+	tabId: string;
+	storyId: StoryId;
+	sceneId: StorySceneId;
+	/** The focused row, or null when the scene itself is the subject. */
+	blockId: StoryBlockId | null;
 };
-type BlueprintFrameProperties = {
-	targetSurfaceId: string | null;
-	params: Record<string, unknown>;
+type StoryMotionKeyframeSelection = {
+	editor: "story-motion";
+	tabId: string;
+	animationId: string;
+	trackId: string;
+	keyframeId: string;
 };
-type BlueprintGamePreferenceKey = "autoForward" | "skip"
+type ComparisonHalf = "base" | "head";
+interface ComparisonElementSelection {
+	/** Repository-relative path of the document being compared. Identity, not a read address. */
+	readonly documentPath: string;
+	readonly half: ComparisonHalf;
+	/** What that half calls its version, already resolved to text by the tab that knows. */
+	readonly versionLabel: string;
+	/** What the OTHER half calls its version. The strip names it when the element is not in it. */
+	readonly counterpartLabel: string;
+	readonly surfaceId: string;
+	readonly elementId: string;
+	/** The element, out of that half's parsed document. */
+	readonly element: UIElement;
+	/** That half's whole document, so a field can resolve a parent, a component or a binding. */
+	readonly document: UIDocument;
+	/** The same element in the other half, or null when that half does not hold it. */
+	readonly counterpart: UIElement | null;
+	/** The other half's document, for the fields that read one. Null when there is no other half. */
+	readonly counterpartDocument: UIDocument | null;
+}
 /**
- * Studio's own, not the engine's: skipping stops at a line the player has not read.
+ * What a plugin may add to Studio's built-in text editor.
+ *
+ * Studio ships the editor and nothing on top of it: no Markdown preview, no lint, no formatter.
+ * Those are plugin work, and this module is the whole of what a plugin needs to do them - a
+ * grammar, a preview pane, a command. The host registry is
+ * `TextEditorContributionService`; the plugin-facing names are re-exported from
+ * `@/plugin` and published in the `narraleaf-studio` types package.
+ *
+ * Two rules the rest of the design follows from:
  *
- * It lives in the engine's preference store all the same (see `preferenceRuntime`), which is
- * what lets it reach this API, the `gamePreferenceChanged` event and the project's preference
- * defaults through exactly the same plumbing as the twelve the engine defines.
+ *  - **Imperative, not declarative.** There is no `contributes.textEditor` manifest key, for the
+ *    same reason `ui.panels` has none: nothing outside the editor session needs to know these
+ *    exist, so a static declaration would be bookkeeping with no reader.
+ *  - **Nothing is rendered for an empty registry.** A preview toggle with no preview behind it is
+ *    a dead control, and the editor's status bar is values-only by design. The consumer shows the
+ *    toggles for the previews that match *this* document's extension and nothing otherwise.
  */
- | "skipReadText"
+/** The character encoding a document is currently being read and written in. */
+export type PluginTextEditorEncodingId = TextEncodingId;
 /**
- * Studio's own: the game's whole output goes quiet while its window is not the one the player is
- * working in. What acts on it is the host's output gate (`focusMute`), not the engine.
+ * A Monarch grammar - monaco's `languages.IMonarchLanguage`.
+ *
+ * Typed structurally rather than by importing monaco's declarations: the published
+ * `narraleaf-studio` types package would otherwise have to carry monaco's entire `.d.ts` surface,
+ * and a plugin would need monaco installed to write a twenty-line grammar. The host casts on the
+ * way into `monaco.languages.setMonarchTokensProvider`.
  */
- | "muteOnWindowBlur"
+export type PluginTextEditorMonarchGrammar = {
+	tokenizer: Record<string, unknown>;
+	[key: string]: unknown;
+};
+/** A monaco `languages.LanguageConfiguration` (comments, brackets, auto-closing pairs, folding). */
+export type PluginTextEditorLanguageConfiguration = Record<string, unknown>;
 /**
- * Studio's own, and transient: the skip run is going. Writing it is the equivalent of holding
- * the skip key, and the host clears it whenever the run ends - a guard stopping it, the game
- * leaving the stage, the window losing focus. Never persisted (see `@shared/types/preference`).
+ * A language the built-in editor should colour.
+ *
+ * Registered into monaco **lazily** - the first time a document with one of these extensions is
+ * opened, not when the plugin's `setup` runs. Monaco is a large module that Studio loads on the
+ * first text tab and never before; a language registration at setup time would drag it into
+ * startup for every workspace, whether or not a text file is ever opened.
  */
- | "skipping"
-/**
- * Studio's own: the engine keeps this in `game.config`, not in its preference store, so the
- * host copies it across on every change (see `preferenceRuntime`).
- */
- | "autoForwardDelay" | "showDialog" | "gameSpeed" | "cps"
-/** Milliseconds a newly typed character takes to fade in; `0` types it at full strength. */
- | "textRevealDuration" | "voiceVolume" | "voiceFadeDuration" | "voiceEndMode" | "bgmVolume" | "soundVolume" | "globalVolume" | "skipDelay" | "skipInterval";
-type BlueprintGamePreferenceVoiceEndMode = "fade" | "stop" | "none";
-type BlueprintGamePreferenceValue = boolean | number | BlueprintGamePreferenceVoiceEndMode;
-type BlueprintLayerShowOptions = {
-	/** Everything below goes inert and the keys belong to this layer. */
-	modal?: boolean;
-	/** Whether Go back closes it. Default true. */
-	dismissible?: boolean;
-	/** Mutual-exclusion group; a second layer of an occupied group queues behind the first. */
-	group?: string | null;
-};
-type BlueprintHostApiRuntime = {
-	navigation: {
-		openSurface: (surfaceId: string, props?: unknown) => Promise<void>;
-		getPageProps: () => Record<string, unknown>;
-		pageBack: () => Promise<void>;
-		clearPages: () => Promise<void>;
-		clearGameOverlay: () => Promise<void>;
-		quitApplication: () => Promise<void>;
-		getFullscreen: () => Promise<boolean>;
-		setFullscreen: (fullscreen: boolean) => Promise<void>;
-		/** The sizes worth offering, ascending. Empty where the shell has no window to size. */
-		getWindowScaleOptions: () => Promise<number[]>;
-		getWindowScale: () => Promise<number>;
-		setWindowScale: (scale: number) => Promise<void>;
-		getWindowSize: () => Promise<{
-			width: number;
-			height: number;
-		}>;
-		setWindowSize: (width: number, height: number) => Promise<void>;
-		/**
-		 * Open one web address in the player's browser.
-		 *
-		 * The host does not decide: it hands the request to whatever the shell supplied, and the
-		 * shell's own process checks it against the addresses the build declared. Nothing here
-		 * consults the project's network setting, because no request is made - see
-		 * `@shared/types/blueprint/externalLink`.
-		 */
-		openExternal: (request: BlueprintOpenExternalRequest) => Promise<BlueprintOpenExternalResult>;
-		/**
-		 * Write a picture of the frame the player is looking at, and say where it went.
-		 *
-		 * The shell decides where: a path chosen in a graph would be a path a graph could write
-		 * anywhere the player's account can. See `@shared/types/blueprint/screenshot`.
-		 */
-		saveScreenshot: () => Promise<BlueprintScreenshotResult>;
-		/** Show the player the folder those pictures are in. */
-		openScreenshotsFolder: () => Promise<BlueprintOpenScreenshotsResult>;
-		/**
-		 * Whether this game's window is the one the player is working in right now.
-		 *
-		 * True wherever the shell cannot tell, which is the honest reading of "there is no window
-		 * to be behind": a story preview inside Studio is always the thing being looked at.
-		 */
-		isWindowFocused: () => Promise<boolean>;
-	};
-	/** Surfaces stacked over the page lane. See the `layers` family in `@shared/types/blueprint/hostApi`. */
-	layers: {
-		/** Put a page up as a layer and return the handle that names it. */
-		show: (surfaceId: string, props?: unknown, options?: BlueprintLayerShowOptions) => Promise<string>;
-		/** Take that layer down, settling once it has finished animating out. */
-		hide: (handle: string) => Promise<void>;
-		/** Take a whole group down - what is on screen and what is queued behind it. */
-		hideGroup: (group: string) => Promise<void>;
-		/** Wait for that layer to close and read what it closed with. Null for a handle already gone. */
-		wait: (handle: string) => Promise<unknown>;
-		/** Close the layer the calling graph runs in. A no-op with a warning anywhere else. */
-		closeSelf: (result?: unknown) => Promise<void>;
-		isMounted: (handle: string) => boolean;
-	};
-	widget: {
-		setVisible: (elementId: string, visible: boolean) => Promise<void>;
-		setEnabled: (elementId: string, enabled: boolean) => Promise<void>;
-		/** `null` clears runtime override and restores authored default variant resolution. */
-		setVariant: (elementId: string, variantId: string | null, options?: {
-			waitForTransition?: boolean;
-		}) => Promise<void>;
-		getCommonProperties: (elementId: string) => BlueprintWidgetCommonProperties;
-		getTextProperties: (elementId: string) => BlueprintTextProperties;
-		setTextProperties: (elementId: string, patch: BlueprintTextPropertiesPatch) => Promise<void>;
-		getButtonProperties: (elementId: string) => BlueprintButtonProperties;
-		setButtonProperties: (elementId: string, patch: Partial<BlueprintButtonProperties>) => Promise<void>;
-		getContainerProperties: (elementId: string) => BlueprintContainerProperties;
-		setContainerProperties: (elementId: string, patch: Partial<BlueprintContainerProperties>) => Promise<void>;
-		getImageProperties: (elementId: string) => BlueprintImageProperties;
-		setImageProperties: (elementId: string, patch: Partial<BlueprintImageProperties>) => Promise<void>;
-		getSliderProperties: (elementId: string) => BlueprintSliderProperties;
-		setSliderProperties: (elementId: string, patch: BlueprintSliderPropertiesPatch) => Promise<void>;
-		getSwitchProperties: (elementId: string) => BlueprintSwitchProperties;
-		setSwitchProperties: (elementId: string, patch: BlueprintSwitchPropertiesPatch) => Promise<void>;
-		getTextInputProperties: (elementId: string) => BlueprintTextInputProperties;
-		setTextInputProperties: (elementId: string, patch: BlueprintTextInputPropertiesPatch) => Promise<void>;
-		getListProperties: (elementId: string) => BlueprintListProperties;
-		setListItems: (elementId: string, items: readonly unknown[]) => Promise<void>;
-		setListSelectedIndex: (elementId: string, index: number) => Promise<void>;
-		scrollListToIndex: (elementId: string, index: number) => Promise<void>;
-		scrollListToTop: (elementId: string) => Promise<void>;
-		scrollListToBottom: (elementId: string) => Promise<void>;
-		getDisplayableProperties: (elementId: string) => BlueprintDisplayableProperties;
-		/**
-		 * What the widget currently covers on screen, in the coordinates of the surface it is on,
-		 * or `null` when nothing is painted for it.
-		 *
-		 * Separate from {@link getDisplayableProperties} because the two answer different
-		 * questions. That one reads the document - where the author put the widget - and is the
-		 * right answer for layout arithmetic. This one measures the DOM, so it accounts for a
-		 * motion in flight, an appearance variant that shifted the widget, a text box sized to its
-		 * own words, and which row of a list an instance ended up on.
-		 */
-		getMeasuredRect: (elementId: string) => BlueprintRect | null;
-		setDisplayableProperties: (elementId: string, patch: BlueprintDisplayablePropertiesPatch) => Promise<void>;
-		animateDisplayable: (elementId: string, request: BlueprintDisplayableMotionRequest) => Promise<UIDisplayableMotionOverride>;
-		stopDisplayableAnimation: (animationId: string) => Promise<void>;
-		getFrameProperties: (elementId: string) => BlueprintFrameProperties;
-		setFrameProperties: (elementId: string, patch: Partial<BlueprintFrameProperties>) => Promise<void>;
-	};
-	state: {
-		get: (scope: string, key: string) => unknown;
-		set: (scope: string, key: string, value: unknown) => void;
-	};
-	persistence: {
-		get: (key: string) => Promise<unknown>;
-		set: (key: string, value: unknown) => Promise<void>;
-	};
-	localization: {
-		/** Localization setup of the running game, or null when the project has none. */
-		getConfig: () => GameLocalizationConfigSnapshot | null;
-		/** Effective current locale (stored player choice, else the source locale). */
-		getLocale: () => Promise<string>;
-		/** Persist the player's language choice; callers validate against getConfig(). */
-		setLocale: (code: string) => Promise<void>;
-	};
-	/**
-	 * Voice-over: which dub the player hears, and replaying a take on demand.
-	 *
-	 * Separate from `localization` because dub language and subtitle language are separate player
-	 * choices - a game may be read in English and heard in Japanese.
-	 */
-	voice: {
-		/** The dub languages this build ships, in project order. Empty when the game has no voice. */
-		listLocales: () => VoiceLocaleEntry[];
-		/** Effective dub language: the stored player choice when the build ships it, else the first. */
-		getLocale: () => Promise<string>;
-		/** Persist the player's dub choice. Takes effect from the next spoken line - no restart. */
-		setLocale: (code: string) => Promise<void>;
-		/**
-		 * Play one line's take in the current dub language, on that speaker's bus.
-		 *
-		 * The id is a voice unit id - the same id a backlog entry reports as `voiceId` - which is why
-		 * a replay button is built from this rather than from the entry's resolved URL. Resolves to
-		 * false when the line has no take in the current language.
-		 */
-		play: (unitId: string) => Promise<boolean>;
-		/**
-		 * Play one choice option's take, at most one instance of that option at a time.
-		 *
-		 * Same clip and same bus as {@link play}; what differs is the bookkeeping a menu needs. A
-		 * hover fires as often as the pointer crosses a row, so a line already speaking is left
-		 * alone rather than restarted, and it answers false. `interruptOthers` stops the takes of
-		 * the *other* options - the author's call, because a menu that reads each option over the
-		 * last is as deliberate a design as one that speaks a single line at a time.
-		 */
-		playChoice: (unitId: string, options?: {
-			interruptOthers?: boolean;
-		}) => Promise<boolean>;
-	};
-	frame: {
-		getParam: (key: string) => unknown;
-		emit: (eventName: string, data: unknown) => Promise<void>;
-	};
-	game: {
-		/**
-		 * Begin a story. `options.inheritSavedGame` carries a save's saved-scope values and visited
-		 * scenes into the new game - see the `Inherit From` pin - and carries nothing else.
-		 */
-		startStory: (request: DevModeStartStoryRequest, options?: {
-			inheritSavedGame?: unknown;
-		}) => Promise<void>;
-		/** The running playthrough as a serialized game, or null when none is running. */
-		captureRun: () => unknown | null;
-		/** The serialized game stored in a slot, or null when there is no such slot. */
-		readSaveGame: (id: string) => Promise<unknown | null>;
-		isInGame: () => boolean;
-		isGameOverlay: () => boolean;
-		quit: (surfaceId: string) => Promise<void>;
-		writeSave: (id: string, metadata?: unknown, screenshot?: boolean) => Promise<void>;
-		/** False when the save was not applied - the player and the author have both been told. */
-		loadSave: (id: string) => Promise<boolean>;
-		deleteSave: (id: string) => Promise<void>;
-		listSaveIds: () => Promise<string[]>;
-		getSaveMetadata: (id: string) => Promise<unknown>;
-		/** When a slot was written, or null when there is no such slot. */
-		getSaveTimes: (id: string) => Promise<SaveRecordTimes | null>;
-		/** Where a slot stopped, or null when there is no such slot. */
-		getSaveLine: (id: string) => Promise<SaveRecordLine | null>;
-		/** Which story a slot was written in, or null when there is no such slot. */
-		getSaveStory: (id: string) => Promise<SaveRecordStory | null>;
-		/** How long a slot was played, or null when there is no such slot. */
-		getSavePlaytime: (id: string) => Promise<SaveRecordPlaytime | null>;
-		/** The running playthrough's playtime, in seconds. */
-		getPlaytime: () => number;
-		/** Seconds ever spent in this project, across every playthrough. */
-		getTotalPlaytime: () => number;
-		getSavePreview: (id: string) => Promise<BlueprintImageAsset | null>;
-		/** Write an autosave into the reserved ring now, regardless of the timer. */
-		writeAutoSave: () => Promise<void>;
-		/** The reserved autosave ring, newest first. Never overlaps `listSaveIds`. */
-		listAutoSaves: () => Promise<AutoSaveEntry[]>;
-		/**
-		 * The backlog behind the play head, oldest first.
-		 *
-		 * From engine 0.26.0 this stops at the head: after the player steps back, the lines they
-		 * stepped past are no longer in here, they are in {@link getFuture}. Before anyone steps
-		 * back - which is every ordinary playthrough - the two are the whole backlog and nothing.
-		 */
-		getHistory: () => Promise<BlueprintGameHistoryEntry[]>;
-		/** The lines ahead of the play head, nearest first. Empty until the player steps back. */
-		getFuture: () => Promise<BlueprintGameHistoryEntry[]>;
-		/** Jump back to a history entry by id; omit the id to undo the last entry. */
-		restoreHistory: (id?: string) => Promise<void>;
-		/** Step the play head forward one line, back over a line the player has already read. */
-		redoHistory: () => Promise<void>;
-		canUndoHistory: () => boolean;
-		canRedoHistory: () => boolean;
-		getNametag: () => string | null;
-		/**
-		 * The speaking character's dialog avatar, or null. Already keyed on the differential the
-		 * character is currently wearing - the engine resolves it off the live portrait element.
-		 */
-		getSpeakerAvatar: () => BlueprintImageAsset | null;
-		/**
-		 * The speaking character's authored accent colour, already in pin shape. Opaque white when
-		 * nobody is speaking, the narrator is, or the character has no colour - the pin it feeds is
-		 * a non-nullable RGBAColor, so "no colour" and "the default colour" are the same answer.
-		 */
-		getSpeakerColor: () => BlueprintRGBAColor;
-		/**
-		 * Has the line on screen finished revealing, with the dialog now waiting for the player.
-		 *
-		 * False while it is still typing, and false again the moment the next line mounts, so an
-		 * indicator bound to it needs no timer of its own. False with no dialog on screen at all.
-		 */
-		isDialogWaiting: () => boolean;
-		/**
-		 * The current line's text - the whole line, not the part revealed so far. Empty string when
-		 * no line is on screen.
-		 */
-		getDialogText: () => string;
-		/**
-		 * Does the current line have no speaker. Distinct from a null nametag, which a character
-		 * with a blank name also reports. False when no line is on screen.
-		 */
-		isNarrator: () => boolean;
-		/**
-		 * Any character by id, from the table mirrored into global state - the addressable read the
-		 * speaker-scoped getters above cannot do. Null when the id is empty, or names a character
-		 * that is not (or is no longer) in the project.
-		 */
-		getCharacter: (characterId: string) => BlueprintCharacterInfo | null;
-		getNotifications: () => BlueprintGameNotification[];
-		getChoiceCount: () => number;
-		isNvlMode: () => boolean;
-		/** True while a dialog line is on screen and its message is marked read. */
-		isCurrentTextRead: () => boolean;
-		isTextRead: (textId: string) => boolean;
-		/** Wipe the persisted text-read record (all stories). */
-		clearTextRead: () => Promise<void>;
-		/**
-		 * Has the player ever ENTERED this scene, by Studio scene id.
-		 *
-		 * Not the same question as `isTextRead`: that record is written when a line is displayed,
-		 * this one when a scene actually starts. Saved-domain, so loading an older save rewinds it.
-		 */
-		isSceneVisited: (sceneId: string) => boolean;
-		/**
-		 * One saved variable of the running playthrough, by the id a `savedVariableRef` names.
-		 *
-		 * `found` is false with no game running, and with an id this build's story does not
-		 * declare. The two are worth telling apart from a value: `null` and the declared default
-		 * are both real values a variable can hold, so neither can double as "there was nothing to
-		 * read". See the capability's own note for why this is read-only.
-		 */
-		getSavedVariable: (variableId: string) => {
-			value: unknown;
-			found: boolean;
-		};
-		/**
-		 * Write one saved variable of the running playthrough.
-		 *
-		 * Throws when there is no game, when the id names nothing this build declares, and when the
-		 * value cannot go into a save file. All three are authoring errors a button would otherwise
-		 * swallow; see the capability's own note for what a write from a screen does and does not do.
-		 */
-		setSavedVariable: (variableId: string, value: unknown) => void;
-		/**
-		 * Has the player ever PICKED this choice option, by the option row's Studio block id. The
-		 * one thing the text-read record structurally cannot answer - a menu that merely appeared
-		 * marks every option of it read.
-		 */
-		isOptionPicked: (optionId: string) => boolean;
-		/**
-		 * Wipe the visited record of the running game.
-		 *
-		 * Synchronous, unlike `clearTextRead`: the record lives in the live `Storable`, not in host
-		 * persistence, so there is nothing to await. It is also scoped to the running session - with
-		 * no game up there is no record, and the call is a no-op instead of an error.
-		 */
-		clearVisited: () => void;
-		/**
-		 * Has the player ever reached this ending, by the `ending` row's Studio block id.
-		 *
-		 * Project persistence rather than the save file, unlike the visited record above: an endings
-		 * screen reports what this player has ever seen, so loading an older save must not re-lock
-		 * anything. Needs no running story - a title screen asks it before the first game exists.
-		 */
-		isEndingReached: (endingId: string) => boolean;
-		/**
-		 * Is this DLC installed beside the running build, by the id the author gave it.
-		 *
-		 * The whole of what a game may ask about its DLC, and deliberately not "does the player own
-		 * it". Ownership is a storefront's fact and a plugin's to answer; what decides whether the
-		 * content is here is whether its file is, which is the question this asks. A build with no
-		 * DLC beside it answers false to everything, which is what a title screen wants before the
-		 * player has bought anything.
-		 */
-		isDlcInstalled: (dlcId: string) => boolean;
-		/**
-		 * Every ending one story declares, in document order, each row already carrying whether it
-		 * was reached. Empty for an unknown or unnamed story rather than an error.
-		 *
-		 * The list comes from the story document this build ships, so it can never offer an ending
-		 * the compiler does not emit, and it is available with no game running for the same reason
-		 * the reader above is.
-		 */
-		listEndings: (storyId: string) => BlueprintStoryEnding[];
-		/**
-		 * Forget one ending. Awaited, unlike `clearVisited`: this writes host persistence rather
-		 * than a live `Storable`, and a caller that navigates away on the next beat has to know the
-		 * write landed.
-		 */
-		clearEndingState: (endingId: string) => Promise<void>;
-		/** Wipe the whole endings record. The `Clear Text Read` of this family. */
-		clearEndings: () => Promise<void>;
-		choose: (index: number) => Promise<void>;
-		next: () => Promise<void>;
-		skip: () => Promise<void>;
-		showDialog: () => Promise<void>;
-		hideDialog: () => Promise<void>;
-		toggleDialogDisplay: () => Promise<void>;
-		setSentenceSpeed: (cps: number) => Promise<void>;
-		getPreference: (key: BlueprintGamePreferenceKey) => BlueprintGamePreferenceValue;
-		setPreference: (key: BlueprintGamePreferenceKey, value: BlueprintGamePreferenceValue) => Promise<void>;
-	};
-	sound: {
-		play: (input: BlueprintSoundPlayInput) => Promise<BlueprintSoundHandle | null>;
-		stop: (handle: BlueprintSoundHandle | null, fadeMs?: number) => Promise<void>;
-		pause: (handle: BlueprintSoundHandle) => Promise<void>;
-		resume: (handle: BlueprintSoundHandle) => Promise<void>;
-		/** Ramp rather than jump when `fadeMs` is set - this is also the fade-out/duck node. */
-		setVolume: (handle: BlueprintSoundHandle, volume: number, fadeMs?: number) => Promise<void>;
-		/** Milliseconds from the start of the file, not from the clip's in point. */
-		seek: (handle: BlueprintSoundHandle, timeMs: number) => Promise<void>;
-		isPlaying: (handle: BlueprintSoundHandle) => boolean;
-		/**
-		 * The volume a **host-owned** media element (the `nl.video` widget's `<video>`) must be set
-		 * to so it obeys the same mixer everything else does.
-		 *
-		 * A DOM element the host created sits on none of the engine's gain nodes, so the whole
-		 * product has to be computed and written to `element.volume`: the authored volume, times
-		 * every bus in the track's chain, times the player's slider for whichever seeded bus that
-		 * chain runs through, times master. Without this a muted game keeps playing video at full
-		 * volume. Pair it with {@link subscribeMixerChanges} - a value read once goes stale the
-		 * moment the player drags a slider, bus faders included.
-		 */
-		resolveElementVolume: (input: {
-			audioTrackId?: string | null;
-			volume?: number | null;
-		}) => number;
-		/** Fires when any preference feeding `resolveElementVolume` changes. Returns a disposer. */
-		subscribeMixerChanges: (listener: () => void) => () => void;
-		/**
-		 * An audio **track**'s own volume, 0..1 - one strip of the player's mixer.
-		 *
-		 * The player-facing counterpart of {@link setVolume}, which addresses one playing clip by
-		 * handle. A track is a bus every clip beneath it is routed through, so setting one applies
-		 * live to everything already playing and survives the clip that provoked it. This is what
-		 * makes "turn Alice down" expressible at all: the four fixed volume preferences can only
-		 * reach the three buses the engine seeds.
-		 *
-		 * An unknown or deleted track id reads as unity and writes nowhere, so a settings page
-		 * built against a track the author later removed degrades to an inert slider.
-		 */
-		getTrackVolume: (trackId: string) => number;
-		setTrackVolume: (trackId: string, volume: number) => Promise<void>;
-	};
-	/**
-	 * HTTP, for the Fetch node.
-	 *
-	 * The host does not issue the request itself: it hands it to whatever the shell supplied, which
-	 * on desktop and in Dev Mode is the main process (`onNetworkFetch`). Nothing here calls
-	 * `fetch()` - see `@shared/utils/blueprintNetworkFetch` for why the renderer must not.
-	 */
-	network: {
-		fetch: (request: BlueprintNetworkFetchRequest) => Promise<BlueprintNetworkFetchResult>;
-	};
-	/**
-	 * The read side of input routing, for `Is Action Held` and `Get Input Device`.
-	 *
-	 * The only part of the input model a graph can ask about rather than be told about. Everything
-	 * else in it is a dispatch - an action fires, a head runs - and none of that can answer "while
-	 * the gesture is down" or "with which hand", because a fired event leaves nothing behind that
-	 * says whether the hand is still there or what it was.
-	 *
-	 * Structural rather than a declared family in `@shared/types/blueprint/hostApi`, matching how
-	 * both nodes reach for it (see `BlueprintInputActionHostApi`): the contract there names
-	 * capabilities a host may or may not implement, and these are answered by the window every host
-	 * already has.
-	 */
-	input: {
-		isActionHeld: (actionId: string) => boolean;
-		/**
-		 * Which device the player is using at this moment.
-		 *
-		 * One of the four values the `On Action` head's `source` pin carries, typed as a plain
-		 * string so a graph compares both against the same literals.
-		 */
-		getDevice: () => string;
-	};
-	/**
-	 * Moving the player's real cursor, for the Move Mouse family.
-	 *
-	 * The author names a point in a surface's own coordinates, which is the only frame they have
-	 * reason to think in. Turning that into a point in the window happens here, off the same
-	 * surface shell every mouse event's payload is divided by, so "the centre of this button"
-	 * measured by `widget.getMeasuredRect` and the point the cursor lands on are the same place.
-	 *
-	 * `surfaceId` is the surface the point belongs to; `null` means the active one. A point on a
-	 * surface that is not currently laid out has nowhere to be, and reports `failed` rather than
-	 * being guessed at against a different surface's scale.
-	 */
-	pointer: {
-		moveTo: (surfaceId: string | null, point: BlueprintVector2D, options?: BlueprintPointerMoveOptions) => Promise<BlueprintPointerMoveResult>;
-		/**
-		 * The same act aimed at a widget's centre, measured rather than computed from the document.
-		 *
-		 * A method of its own rather than something a caller assembles out of `getMeasuredRect` and
-		 * `moveTo`, because the two halves have to agree about which surface the widget turned out
-		 * to be painted on. A component instance renders its contents wherever it was placed, so
-		 * the answer is not always the surface the element was authored under, and a caller
-		 * stitching the halves together would have to know that to get it right.
-		 */
-		moveToElementCenter: (elementId: string, options?: BlueprintPointerMoveOptions) => Promise<BlueprintPointerMoveResult>;
-	};
-	/**
-	 * Carrying a playthrough between two editions of one title, for the Export/Import Progress
-	 * nodes.
-	 *
-	 * The host does not decide where the document is: it hands the act to whatever the shell
-	 * supplied, and the shell's own process resolves the file from the build's progress key. What
-	 * this side states is what the playthrough holds, never where it goes.
-	 *
-	 * `import` answers with a scene id rather than going anywhere with it. The node deliberately
-	 * does not jump - `Start Game` is what starts a story, and an author's graph usually has
-	 * something to do first.
-	 */
-	progress: {
-		export: () => Promise<{
-			outcome: "written" | "failed";
-			error: string;
-		}>;
-		import: () => Promise<GameProgressImportOutcome>;
-	};
-	/**
-	 * What the shell can promise about the data it writes, for the `Check Storage Durability` node.
-	 *
-	 * A fact about where the game is running, not about the playthrough: a packaged desktop game
-	 * keeps files nothing reclaims, a web export holds whatever grant the browser gave it. Stated,
-	 * never acted on - what a player is told about it belongs to the title.
-	 */
-	storage: {
-		durability: () => Promise<GameStorageDurability>;
-	};
-	devtools: {
-		log: (level: string, message: string) => void;
-	};
-};
-type BlueprintSoundPlayInput = {
-	assetId: string;
-	/**
-	 * Project audio track (`ProjectAudioTrack.id`), which **is** the engine bus this clip is routed
-	 * into, and whose own gain is applied live by the gain graph rather than folded in here. It also
-	 * supplies the loop default below. Absent resolves to the seeded SFX bus, which is what an
-	 * unqualified "play this clip" has always meant.
-	 */
-	audioTrackId?: string | null;
-	/** Author override; absent means the track's own default. */
-	loop?: boolean | null;
-	/** Author override, 0..1 as authored; absent means unity. Never pre-multiplied by a bus gain. */
-	volume?: number | null;
-	/** Fade-in in milliseconds; absent means a hard start (a fade belongs to the moment). */
-	fadeInMs?: number | null;
-};
-type GameLocalizationConfigSnapshot = Pick<GameLocalizationBundle, "sourceLocale" | "locales"> & Partial<Pick<GameLocalizationBundle, "tables" | "keys" | "scenes">>;
-type BlueprintGameNotification = {
-	id: string;
-	message: string;
-};
-type BlueprintStoryEnding = {
-	endingId: string;
-	name: string;
-	sceneId: string;
-	/** The scene the ending row sits in, so a row can be grouped or captioned without a lookup. */
-	sceneName: string;
-	isReached: boolean;
-};
-type BlueprintGameHistoryEntry = {
-	/** History token; pass to Restore From History to jump the game back to this point. */
-	id: string;
-	/** "say" for spoken lines, "menu" for a resolved choice. */
-	type: "say" | "menu";
-	/** Sentence text (say) or the menu prompt (menu); empty string when the source had none. */
-	text: string;
-	/** Speaker nametag for a say entry; null for menu entries or narration. */
-	character: string | null;
-	/** Resolved voice clip URL for a say entry; null when absent. Not addressable - see `voiceId`. */
-	voice: string | null;
-	/**
-	 * The voice unit id this line's take is filed under; null when the line was not voiced through
-	 * the voice module. This is the replayable handle: feed it to the Play Voice node. `voice` is a
-	 * URL the player already heard and nothing in the runtime accepts a URL.
-	 */
-	voiceId: string | null;
-	/** Chosen option text for a menu entry; null for say entries or an unresolved menu. */
-	selected: string | null;
-	/** True while the entry is the line currently being shown (not yet committed). */
-	isPending: boolean;
-};
-type BehaviorNodeExecuteResult = {
-	nextPort?: string;
-	nextPorts?: string[];
-	outputValues?: Record<string, unknown>;
-};
-type BehaviorGraphEventControl = {
-	stopPropagation(): void;
-	isPropagationStopped(): boolean;
-};
-type StoryBlockSelection = {
-	editor: "story";
-	tabId: string;
-	storyId: StoryId;
-	sceneId: StorySceneId;
-	/** The focused row, or null when the scene itself is the subject. */
-	blockId: StoryBlockId | null;
-};
-type StoryMotionKeyframeSelection = {
-	editor: "story-motion";
-	tabId: string;
-	animationId: string;
-	trackId: string;
-	keyframeId: string;
-};
-type ComparisonHalf = "base" | "head";
-interface ComparisonElementSelection {
-	/** Repository-relative path of the document being compared. Identity, not a read address. */
-	readonly documentPath: string;
-	readonly half: ComparisonHalf;
-	/** What that half calls its version, already resolved to text by the tab that knows. */
-	readonly versionLabel: string;
-	/** What the OTHER half calls its version. The strip names it when the element is not in it. */
-	readonly counterpartLabel: string;
-	readonly surfaceId: string;
-	readonly elementId: string;
-	/** The element, out of that half's parsed document. */
-	readonly element: UIElement;
-	/** That half's whole document, so a field can resolve a parent, a component or a binding. */
-	readonly document: UIDocument;
-	/** The same element in the other half, or null when that half does not hold it. */
-	readonly counterpart: UIElement | null;
-	/** The other half's document, for the fields that read one. Null when there is no other half. */
-	readonly counterpartDocument: UIDocument | null;
-}
-/**
- * What a plugin may add to Studio's built-in text editor.
- *
- * Studio ships the editor and nothing on top of it: no Markdown preview, no lint, no formatter.
- * Those are plugin work, and this module is the whole of what a plugin needs to do them - a
- * grammar, a preview pane, a command. The host registry is
- * `TextEditorContributionService`; the plugin-facing names are re-exported from
- * `@/plugin` and published in the `narraleaf-studio` types package.
- *
- * Two rules the rest of the design follows from:
- *
- *  - **Imperative, not declarative.** There is no `contributes.textEditor` manifest key, for the
- *    same reason `ui.panels` has none: nothing outside the editor session needs to know these
- *    exist, so a static declaration would be bookkeeping with no reader.
- *  - **Nothing is rendered for an empty registry.** A preview toggle with no preview behind it is
- *    a dead control, and the editor's status bar is values-only by design. The consumer shows the
- *    toggles for the previews that match *this* document's extension and nothing otherwise.
- */
-/** The character encoding a document is currently being read and written in. */
-export type PluginTextEditorEncodingId = TextEncodingId;
-/**
- * A Monarch grammar - monaco's `languages.IMonarchLanguage`.
- *
- * Typed structurally rather than by importing monaco's declarations: the published
- * `narraleaf-studio` types package would otherwise have to carry monaco's entire `.d.ts` surface,
- * and a plugin would need monaco installed to write a twenty-line grammar. The host casts on the
- * way into `monaco.languages.setMonarchTokensProvider`.
- */
-export type PluginTextEditorMonarchGrammar = {
-	tokenizer: Record<string, unknown>;
-	[key: string]: unknown;
-};
-/** A monaco `languages.LanguageConfiguration` (comments, brackets, auto-closing pairs, folding). */
-export type PluginTextEditorLanguageConfiguration = Record<string, unknown>;
-/**
- * A language the built-in editor should colour.
- *
- * Registered into monaco **lazily** - the first time a document with one of these extensions is
- * opened, not when the plugin's `setup` runs. Monaco is a large module that Studio loads on the
- * first text tab and never before; a language registration at setup time would drag it into
- * startup for every workspace, whether or not a text file is ever opened.
- */
-export type PluginTextEditorLanguageDef = {
-	/** Monaco language id. Must be prefixed with the plugin id. */
-	id: string;
-	/** File extensions, with or without the leading dot; matched case-insensitively. */
-	extensions: string[];
-	aliases?: string[];
-	monarch?: PluginTextEditorMonarchGrammar;
-	configuration?: PluginTextEditorLanguageConfiguration;
-};
+export type PluginTextEditorLanguageDef = {
+	/** Monaco language id. Must be prefixed with the plugin id. */
+	id: string;
+	/** File extensions, with or without the leading dot; matched case-insensitively. */
+	extensions: string[];
+	aliases?: string[];
+	monarch?: PluginTextEditorMonarchGrammar;
+	configuration?: PluginTextEditorLanguageConfiguration;
+};
 /**
  * What a preview component is handed on every render.
  *
@@ -17078,176 +15894,6 @@ type SelectionState = {
 	type: "storyBlock";
 	data: StoryBlockSelection;
 };
-type ViewportTransform = {
-	scale: number;
-	offsetX: number;
-	offsetY: number;
-};
-type CanvasFitMode = "contain" | "cover" | "width" | "actual";
-type SurfaceViewportFit = {
-	mode: CanvasFitMode;
-	/**
-	 * True when the mode came from the zoom menu. It survives a resize the same way, and only this
-	 * one escapes {@link SURFACE_FIT_MAX_SCALE}.
-	 */
-	chosen: boolean;
-};
-type UITool = {
-	kind: "select";
-} | {
-	kind: "pan";
-} | {
-	kind: "insert";
-	nodeType: string;
-	componentId?: string;
-};
-type SnapGuideKind = "surface-edge" | "surface-center" | "element-edge" | "element-center";
-type ActiveSnapGuideSegment = {
-	value: number;
-	kind: SnapGuideKind;
-};
-type ActiveSnapGuides = {
-	surfaceId: string;
-	vertical: ActiveSnapGuideSegment[];
-	horizontal: ActiveSnapGuideSegment[];
-};
-type SmartSnapDetailSettings = {
-	/** Snap selection edges/centers to other elements' center lines. */
-	snapElementLayout: boolean;
-	/** Snap element edges to other elements' edges. */
-	snapElementBorder: boolean;
-	/** Snap to canvas (surface) edges and center lines. */
-	snapCanvasLayout: boolean;
-};
-declare class UIEditorStateService extends Service<UIEditorStateService> implements IUIEditorStateService {
-	private uiStore;
-	private documentService;
-	private settingsService;
-	private readonly events;
-	private selection;
-	private tool;
-	private viewport;
-	/** Which interface {@link viewport} currently describes - it is one transform shared by every tab. */
-	private viewportSurfaceId;
-	/**
-	 * Set while {@link viewport} is a computed zoom - a fit mode rather than somewhere the author
-	 * zoomed or panned to by hand. `null` means the transform is theirs and nothing may revise it.
-	 */
-	private viewportFit;
-	/** Hand-set transforms, so switching back to an interface returns to the view it was left at. */
-	private readonly viewportBySurfaceId;
-	/** Fit modes, so switching back to an interface resumes the mode it was left following. */
-	private readonly viewportFitBySurfaceId;
-	private interactionOverride;
-	private selectionUnsubscribe?;
-	private enteredState;
-	/** Only stores `true` keys; missing id => collapsed. */
-	private readonly appearanceBorderSidesExpandedByElementId;
-	private appearanceInspectorUiCachePersistTimer;
-	/** Presence means the outline branch is collapsed. */
-	private readonly outlineCollapsedBranchIds;
-	private outlinePanelCollapsed;
-	private outlineCollapsePersistTimer;
-	private smartSnapEnabled;
-	private smartSnapDetail;
-	private snapGuides;
-	/** Pure view state: screen-ratio preview frame preset id, `null` = off. Never touches the UIDocument. */
-	private previewAspectId;
-	/** Pure view state: safe-area preview frame device preset id, `null` = off. Never touches the UIDocument. */
-	private previewSafeAreaId;
-	protected init(ctx: WorkspaceContext, depend: (services: Service[]) => Promise<void>): Promise<void>;
-	dispose(_ctx: WorkspaceContext): void;
-	getTool(): UITool;
-	setTool(tool: UITool): void;
-	getViewportTransform(): ViewportTransform;
-	/**
-	 * A hand gesture: a wheel zoom, a pan, or a zoom the author typed. It ends whatever fit mode
-	 * was running, because from here on the author has said where they want to be looking and a
-	 * pane resize must not overrule that.
-	 */
-	updateViewport(transform: Partial<ViewportTransform>): ViewportTransform;
-	/** Which interface the current transform describes; `null` before any editor tab claimed it. */
-	getViewportSurfaceId(): string | null;
-	/**
-	 * The fit mode the viewport is currently following, or `null` once the author has zoomed or
-	 * panned by hand. Only while it is set may the editor recompute the transform on its own, when
-	 * the pane resizes or the design size changes.
-	 */
-	getViewportFit(): SurfaceViewportFit | null;
-	/**
-	 * Installs a computed zoom as the viewport for `surfaceId`.
-	 *
-	 * Separate from {@link updateViewport} because the two carry opposite intent: this one is a
-	 * mode being applied, and it stays live across resizes; that one is a place the author chose,
-	 * and nothing may move it.
-	 */
-	applyFittedViewport(surfaceId: string, transform: ViewportTransform, fit: SurfaceViewportFit): ViewportTransform;
-	/**
-	 * Hands the shared viewport to `surfaceId` when opening or re-showing its tab.
-	 *
-	 * One transform serves every surface editor tab, so switching tabs would otherwise show the
-	 * next interface through the last one's zoom.
-	 *
-	 * Returns `null` when this interface was left at a hand-set transform - it has been restored
-	 * and the caller has nothing to do. Otherwise returns the mode the caller must recompute for
-	 * the space it has now, which for an interface being opened for the first time is the plain
-	 * fit nobody asked for.
-	 */
-	adoptSurfaceViewport(surfaceId: string): SurfaceViewportFit | null;
-	getSelection(): SelectionState;
-	setSelection(selection: SelectionState): void;
-	setUIElementSelection(selection: UIElementSelection): void;
-	getInteractionOverride(): InteractionOverride | null;
-	setInteractionOverride(next: InteractionOverride | null): void;
-	getDocument(): UIDocument;
-	getSurface(surfaceId: string): UISurface | undefined;
-	getEnteredState(): UIEditorEnteredState | null;
-	setEnteredState(next: UIEditorEnteredState | null): void;
-	getAppearanceBorderSidesExpanded(elementId: string): boolean;
-	setAppearanceBorderSidesExpanded(elementId: string, expanded: boolean): void;
-	isOutlineBranchCollapsed(elementId: string): boolean;
-	setOutlineBranchCollapsed(elementId: string, collapsed: boolean): void;
-	getOutlinePanelCollapsed(): boolean;
-	setOutlinePanelCollapsed(collapsed: boolean): void;
-	getSmartSnapEnabled(): boolean;
-	setSmartSnapEnabled(enabled: boolean): void;
-	getSmartSnapDetailSettings(): SmartSnapDetailSettings;
-	patchSmartSnapDetailSettings(patch: Partial<SmartSnapDetailSettings>): void;
-	getPreviewAspectId(): string | null;
-	/**
-	 * Pure view state — persisted in global settings only. Deliberately does NOT go through
-	 * `UIDocumentService`, so toggling a preview frame never dirties the project, never emits
-	 * `documentChanged` and never enters the undo stack.
-	 */
-	setPreviewAspectId(aspectId: string | null): void;
-	getPreviewSafeAreaId(): string | null;
-	/** Pure view state — see `setPreviewAspectId`. */
-	setPreviewSafeAreaId(safeAreaId: string | null): void;
-	getSnapGuides(): ActiveSnapGuides | null;
-	setSnapGuides(guides: ActiveSnapGuides | null): void;
-	on<K extends keyof UIEditorStateEvents>(event: K, handler: (data: UIEditorStateEvents[K]) => void): () => void;
-	private ensureUIStore;
-	private normalizeViewport;
-	private persistViewport;
-	private scheduleAppearanceInspectorUiCachePersistence;
-	private persistAppearanceInspectorUiCachesNow;
-	private flushAppearanceInspectorUiCachePersistence;
-	private scheduleOutlineCollapsePersistence;
-	private persistOutlineCollapsedBranchesNow;
-	private flushOutlineCollapsePersistence;
-	private areSnapGuidesEqual;
-	/**
-	 * Drops the entered state when the author moves to another interface.
-	 *
-	 * Selection is left alone on purpose. A canvas click on a widget's part promotes the selection to
-	 * the parent it drills from, so exiting on "the selection left the subtree" exits on the very
-	 * click an author makes to grab what they are editing - the state flickered away under them, and
-	 * whatever they did next landed somewhere they were not looking.
-	 */
-	private ensureEnteredStateValid;
-	private ensureInteractionOverrideValid;
-	private areOverridesEqual;
-}
 type LiveUIComponentShell = Omit<UIComponentDefinition, "elements">;
 type LiveUIParts = {
 	/** Records of the shared element map. */
@@ -18258,53 +16904,6 @@ interface PropertyEditorSchema<TData = any> {
 	/** Whether to show saving indicator */
 	showSavingIndicator?: boolean;
 }
-type WidgetRendererProps = {
-	element: UIElement;
-	surface: UISurface;
-	document: UIDocument;
-	hostAdapter: UIHostAdapter;
-	children?: React$1.ReactNode;
-	/** Stable suffix for repeated structural renderers such as list item previews. */
-	instanceKey?: string;
-	/** Current list item scope when this element renders inside a list-like item template. */
-	listItemScope?: UIListItemScope | null;
-	/**
-	 * Structural widgets may render children lazily with an instance scope.
-	 * `nl.list` uses this to repeat one authored item template without cloning UIDocument elements.
-	 */
-	renderChildren?: (options?: {
-		childrenIds?: string[];
-		listItemScope?: UIListItemScope | null;
-		instanceKey?: string;
-		elementOverrides?: Record<string, UIElement>;
-	}) => React$1.ReactNode[];
-	/**
-	 * Render another Page surface inside the current element without using an iframe.
-	 * Runtime hosts may isolate state/lifecycle by frame instance.
-	 */
-	renderSurface?: (options: {
-		targetSurfaceId: string | null;
-		frameElement: UIElement;
-		params?: Record<string, unknown>;
-		instanceKey?: string;
-	}) => React$1.ReactNode;
-	/** Runtime state readers exposed to structural widgets that resolve their own data source. */
-	runtimeData?: {
-		surfaceState?: {
-			get(key: string): unknown;
-		};
-		globalState?: {
-			get(key: string): unknown;
-		};
-		/** Props the current page was opened with; fixed for the life of the page instance. */
-		pageProps?: Readonly<Record<string, unknown>>;
-	};
-	/**
-	 * When true, canvas appearance resolves the variant from the inspector cache (editing-area preview).
-	 * Dev Mode and other hosts omit this so runtime/blueprint variant overrides stay authoritative.
-	 */
-	useAppearanceInspectorPreview?: boolean;
-};
 type UIInspectorData = {
 	element: UIElement;
 	elements: UIElement[];
@@ -18313,10 +16912,6 @@ type UIInspectorData = {
 	/** Set when inspecting a canvas widget; required for Blueprint M2 binding UI. */
 	surfaceId?: string;
 };
-type InspectorContext = {
-	element: UIElement;
-	documentService: UIDocumentService;
-};
 type DockerBarItem = DockerBarButton | DockerBarSelect | DockerBarNumberInput | DockerBarSeparator;
 type DockerBarButton = {
 	kind: "button";
@@ -18361,17 +16956,6 @@ type DockerBarSeparator = {
 	kind: "separator";
 	id: string;
 };
-type DockerBarContext = {
-	element: UIElement;
-	documentService: UIDocumentService;
-	stateService?: UIEditorStateService;
-	surfaceId?: string;
-};
-type WidgetContextMenuContext = {
-	element: UIElement;
-	documentService: UIDocumentService;
-	surfaceId: string;
-};
 type FloatingToolbarButton = {
 	kind: "button";
 	id: string;
@@ -18382,18 +16966,6 @@ type FloatingToolbarButton = {
 	onClick: () => void;
 };
 type FloatingToolbarItem = FloatingToolbarButton;
-type FloatingToolbarContext = {
-	element: UIElement;
-	documentService: UIDocumentService;
-	surfaceId: string;
-	openSurfaceEditor?: (surfaceId: string) => void;
-};
-type LayoutSizeFieldContext = {
-	element: UIElement;
-	documentService: UIDocumentService;
-	surfaceId?: string;
-	primaryId: string;
-};
 type DefaultChildElementContext = {
 	element: UIElement;
 	generateId: () => string;
@@ -18402,203 +16974,6 @@ type DefaultChildElementResult = {
 	elementPatch?: Partial<UIElement>;
 	children: UIElement[];
 };
-interface UIWidgetModule {
-	/** Unique type identifier (e.g. "nl.container") */
-	readonly type: string;
-	/**
-	 * Widget type this module specialises, set by `extendWidgetModule`.
-	 *
-	 * Mirrors the entry in `WIDGET_TYPE_PARENTS`, which is the shared table the capability lookups
-	 * (effect kinds, logic API, appearance backfill) read - `shared` cannot see a renderer module.
-	 */
-	readonly extends?: string;
-	/** Shared logic capability schema for editor, runtime, and blueprint tooling. */
-	readonly logicApi?: WidgetLogicApi;
-	/** Human-readable display name */
-	readonly displayName: string;
-	/** Icon shown in the docker bar's element palette */
-	readonly icon: LucideIcon;
-	/**
-	 * Creates the default partial element when the user inserts this widget.
-	 * The returned object is merged with system defaults (id, parentId, etc.).
-	 */
-	createDefaultElement(): Partial<UIElement>;
-	/**
-	 * Creates structural child elements that must be present immediately after inserting the widget.
-	 * The service applies the returned parent patch and child list in the same UIDocument mutation.
-	 */
-	createDefaultChildElements?(context: DefaultChildElementContext): DefaultChildElementResult;
-	/**
-	 * The states this widget can be shown in, when they belong to the widget rather than to an
-	 * appearance model.
-	 *
-	 * A switch is on or off whatever its parts look like, and it carries no appearance of its own, so
-	 * there are no variants for the state bar to list. Declaring them here puts the bar on the widget
-	 * itself; entering one broadcasts that variant id to the subtree, which is where the parts that
-	 * do carry variants pick it up. `id: null` is the state the widget rests in.
-	 */
-	listEditorStates?(element: UIElement): {
-		id: string | null;
-		name: string;
-	}[];
-	/**
-	 * Renders the element on the editor canvas.
-	 */
-	render(props: WidgetRendererProps): React$1.ReactElement | null;
-	/**
-	 * Returns property inspector fields for the properties panel.
-	 * These fields are appended after the common layout fields.
-	 * Return `undefined` to show only layout fields.
-	 */
-	createInspector?(context: InspectorContext): PropertyEditorSchema<UIInspectorData> | undefined;
-	/**
-	 * Returns docker bar items shown when this element is selected.
-	 * Return `undefined` or empty array for no element-specific docker items.
-	 */
-	createDockerBarItems?(context: DockerBarContext): DockerBarItem[];
-	/**
-	 * Returns docker bar items used when multiple elements of this type are selected.
-	 * The final multi-select docker bar shows only the items whose `id` exists for every selected module.
-	 */
-	createMultiSelectDockerBarItems?(context: DockerBarContext): DockerBarItem[];
-	/**
-	 * Extra context menu items when this element is the sole selection (canvas or outline).
-	 */
-	createContextMenuItems?(context: WidgetContextMenuContext): ContextMenuItemDef[];
-	/**
-	 * Returns icon actions rendered as one floating toolbar above the selected element's transform box.
-	 * Keep actions concise; all modules share the same group renderer.
-	 */
-	createFloatingToolbarItems?(context: FloatingToolbarContext): FloatingToolbarItem[];
-	/**
-	 * Override the common Width / Height row in the layout inspector.
-	 * Return `undefined` to use the default row, or `null` to hide the row.
-	 */
-	createLayoutSizeField?(context: LayoutSizeFieldContext): FieldDefinition<UIInspectorData> | null | undefined;
-	/**
-	 * Optional hook to register additional blueprint nodes (via `defineBlueprintNode`) when the module loads.
-	 * Keep side effects idempotent - the host may call this once per session.
-	 */
-	registerBlueprintNodes?(): void;
-}
-type UIEditorReadOnly = {
-	/** Whether every write gesture on this surface is inert right now. */
-	readonly active: boolean;
-	/** Hover text for the controls this state disables. The workspace passes the freeze reason. */
-	readonly reason?: string;
-};
-type UIHost$1 = "app" | "player";
-type UIHostAdapterElementEventOptions = {
-	listItemScope?: UIListItemScope | null;
-	instanceKey?: string;
-	componentId?: UIComponentId;
-	/** Resolved values by param id: the instance's own, falling back to the declared default. */
-	componentParams?: Record<string, string>;
-	eventControl?: BehaviorGraphEventControl;
-	allowClosedScopeExecution?: boolean;
-};
-type UIHostAdapterBlueprintRuntime = {
-	surfaceId: string;
-	/** Instance-specific scope id. Defaults to `surfaceId` for top-level surfaces. */
-	runtimeScopeId?: string;
-	setSurfaceState: (key: string, value: unknown) => void;
-	getSurfaceState: (key: string) => unknown;
-	emitDebug: (event: BlueprintDebugEvent) => void;
-	getSurfaceTransitionState?: () => {
-		isEntering: boolean;
-		isExiting: boolean;
-	};
-	/** Dispatch a widget private event slot (for example `init` or `mouseClick`) on the owner-local blueprint. */
-	dispatchElementBlueprintEvent: (elementId: string, eventName: string, payload?: Record<string, unknown>, options?: UIHostAdapterElementEventOptions) => Promise<void>;
-	/** Continue the current widget event from this element to its structural parent. */
-	continueElementEventBubble?: (elementId: string, eventName: string, payload?: Record<string, unknown>, options?: UIHostAdapterElementEventOptions) => Promise<boolean>;
-	/** Dispatch a surface-level event on the current surfaceMain blueprint. */
-	dispatchSurfaceBlueprintEvent?: (eventName: string, payload?: Record<string, unknown>) => Promise<void>;
-	/**
-	 * Raise one of this surface's declared input actions on its surfaceMain blueprint.
-	 *
-	 * The seam between routing and authoring: routing decides that this click, wheel or key means
-	 * "advance" on this surface (see `runtime/input/surfaceInputActions`), and this hands that
-	 * decision to the graph. Named rather than positional because the payload is what the action's
-	 * head node reads its pins from.
-	 *
-	 * It resolves when the action's graphs have run, which is what lets a lane walk stay sequential.
-	 */
-	dispatchSurfaceInputAction?: (payload: UIInputActionEventPayload) => Promise<void>;
-	dispatchBroadcastEvent?: (eventName: string, data: unknown, sender?: string) => Promise<void>;
-	getBroadcastListenerCount?: (eventName: string) => number;
-	/** Invoke a declared blueprint fn (Call Fn node); awaits the fn body and returns its Fn Return values. */
-	invokeBlueprintFn?: (input: {
-		fnRef: string;
-		args: Record<string, unknown>;
-		depth: number;
-		/** Surface of the calling execution; global callers omit it and only see global fns. */
-		callerSurfaceId?: string;
-		/** Component definition of the calling execution, when it is running inside one. */
-		callerComponentId?: string;
-		/** That instance's resolved params, which the fn body runs with. */
-		callerComponentParams?: Record<string, string>;
-		/** Which drawing the call came from, so the body's widget writes land on it. */
-		callerInstanceKey?: string;
-		signal?: AbortSignal;
-		callerExecutionId?: string;
-	}) => Promise<{
-		returns: Record<string, unknown>;
-	}>;
-	frame?: {
-		getParam: (key: string) => unknown;
-		emit: (eventName: string, data: unknown) => Promise<void> | void;
-	};
-	/** M3-full: Dev Mode host API (graphs + TS ctx); absent in editor preview. */
-	hostApi?: BlueprintHostApiRuntime;
-};
-type UIHostAdapter = {
-	host: UIHost$1;
-	navigate?: (target: unknown) => Promise<void> | void;
-	resolveSlot?: (slotId: string) => {
-		mount: (node: React$1.ReactNode) => void;
-	} | null;
-	gameUiRuntime?: {
-		slotId: UIStageSlotId;
-	};
-	/**
-	 * M1 latch: which frozen BlueprintHostApiContract generation this adapter targets.
-	 * Does not imply all capabilities are implemented yet.
-	 */
-	blueprintHostApiVersion?: BlueprintHostApiContractVersion;
-	/** M3-min: optional Blueprint runtime surface (Dev Mode). */
-	blueprintRuntime?: UIHostAdapterBlueprintRuntime;
-	/**
-	 * Story Action Blueprint runtime surface. Present only while a story-action blueprint graph
-	 * runs inside a compiled NLR `Script`; resolves scene/saved variable ids to their NLR backing
-	 * (`Scene.local` / `Storable`). Absent for UI blueprints.
-	 */
-	storyRuntime?: UIHostAdapterStoryRuntime;
-	/** Editor preview: use the active workspace service instance for canvas-local interaction overrides. */
-	editorStateService?: UIEditorStateService;
-	/** Editor preview: use the active document service, including component-editor adapters. */
-	editorDocumentService?: UIDocumentService;
-	/**
-	 * Whether the surface this adapter renders is read-only right now (a frozen workspace).
-	 *
-	 * The two services above are the only thing a widget renderer needs in order to write the
-	 * document from inside its own markup, and the interaction layer's gesture table cannot reach
-	 * those handlers - a widget's `onDoubleClick` is attached by the widget, not by the canvas. So
-	 * the state travels on the adapter beside them, and {@link resolveInlineTextEditHost} is where
-	 * the two are read together.
-	 */
-	editorReadOnly?: UIEditorReadOnly;
-};
-type StoryVariableRuntimeAccess = {
-	/** Resolve `variableId` to its stored value, or the declared default when unset. */
-	get: (variableId: string) => unknown;
-	/** Resolve `variableId` and write `value` to the backing store. */
-	set: (variableId: string, value: unknown) => void;
-};
-type UIHostAdapterStoryRuntime = {
-	sceneVar: StoryVariableRuntimeAccess;
-	savedVar: StoryVariableRuntimeAccess;
-};
 type BlueprintPinSemantic = "exec" | "data";
 export type BlueprintNodePinDef = {
 	id: string;
@@ -18957,98 +17332,6 @@ interface IUIDocumentService extends IService {
 	};
 	renameElement(elementId: string, name: string): void;
 }
-type InteractionOverride = {
-	kind: "imageCrop";
-	surfaceId: string;
-	elementId: string;
-	source: string;
-} | {
-	kind: "textEdit";
-	surfaceId: string;
-	elementId: string;
-};
-type InteractionOverrideChange = {
-	previous: InteractionOverride | null;
-	next: InteractionOverride | null;
-};
-type UIEditorEnteredState = {
-	surfaceId: string;
-	elementId: string;
-	variantId: string | null;
-};
-interface UIEditorStateEvents {
-	toolChanged: UITool;
-	viewportChanged: ViewportTransform;
-	selectionChanged: SelectionState;
-	interactionOverrideChanged: InteractionOverrideChange;
-	/** Editor-only: which element is showing one of its states, and which; drives canvas preview. */
-	enteredStateChanged: UIEditorEnteredState | null;
-	/** Outline panel expand/collapse memory (persisted); payload unused. */
-	outlineExpansionChanged: null;
-	/** Outline panel chrome collapsed state (persisted). */
-	outlinePanelCollapsedChanged: boolean;
-	/** Smart snap / smart guides toggle (persisted in project settings). */
-	smartSnapEnabledChanged: boolean;
-	/** Per-category snap targets when smart snap is enabled (persisted). */
-	smartSnapDetailSettingsChanged: SmartSnapDetailSettings;
-	/** Ephemeral snap guide lines in surface space (viewport overlay). */
-	snapGuidesChanged: ActiveSnapGuides | null;
-	/** Screen-ratio preview frame preset id, `null` = off (pure view state, global settings). */
-	previewAspectChanged: string | null;
-	/** Safe-area preview frame device preset id, `null` = off (pure view state, global settings). */
-	previewSafeAreaChanged: string | null;
-}
-interface IUIEditorStateService extends IService {
-	getTool(): UITool;
-	setTool(tool: UITool): void;
-	getViewportTransform(): ViewportTransform;
-	/** A hand gesture (zoom, pan, or a typed zoom); ends the fit mode the interface was following. */
-	updateViewport(transform: Partial<ViewportTransform>): ViewportTransform;
-	/** Which interface the current transform describes; `null` before any editor tab claimed it. */
-	getViewportSurfaceId(): string | null;
-	/** The fit mode in force, or `null` once the author moved the view by hand. */
-	getViewportFit(): SurfaceViewportFit | null;
-	/** Installs a computed zoom for an interface (stays live across resizes, unlike a hand gesture). */
-	applyFittedViewport(surfaceId: string, transform: ViewportTransform, fit: SurfaceViewportFit): ViewportTransform;
-	/** Restores a hand-set view (`null`), or returns the mode the caller must recompute. */
-	adoptSurfaceViewport(surfaceId: string): SurfaceViewportFit | null;
-	getSelection(): SelectionState;
-	setSelection(selection: SelectionState): void;
-	setUIElementSelection(selection: UIElementSelection): void;
-	getDocument(): UIDocument;
-	getSurface(surfaceId: string): UISurface | undefined;
-	/** The state being shown on the canvas right now, or null while every element rests. */
-	getEnteredState(): UIEditorEnteredState | null;
-	setEnteredState(next: UIEditorEnteredState | null): void;
-	/** Whether compact Border panel "sides" row is expanded (per element, persisted with project settings). */
-	getAppearanceBorderSidesExpanded(elementId: string): boolean;
-	setAppearanceBorderSidesExpanded(elementId: string, expanded: boolean): void;
-	/** Outline: branch is collapsed when true (editor-only, project settings). */
-	isOutlineBranchCollapsed(elementId: string): boolean;
-	setOutlineBranchCollapsed(elementId: string, collapsed: boolean): void;
-	/** Outline panel chrome: collapsed when true (editor-only global settings). */
-	getOutlinePanelCollapsed(): boolean;
-	setOutlinePanelCollapsed(collapsed: boolean): void;
-	/** When true, dragging/resizing/inserting snaps to surface and sibling guides (project settings). */
-	getSmartSnapEnabled(): boolean;
-	setSmartSnapEnabled(enabled: boolean): void;
-	/** Which guide categories participate when smart snap is on (persisted). */
-	getSmartSnapDetailSettings(): SmartSnapDetailSettings;
-	patchSmartSnapDetailSettings(patch: Partial<SmartSnapDetailSettings>): void;
-	/**
-	 * Screen-ratio preview frame preset id (`null` = off). Pure view state: persisted in global
-	 * settings, never in the UIDocument, so toggling it cannot dirty the project.
-	 */
-	getPreviewAspectId(): string | null;
-	setPreviewAspectId(aspectId: string | null): void;
-	/** Safe-area preview frame device preset id (`null` = off). Pure view state, see above. */
-	getPreviewSafeAreaId(): string | null;
-	setPreviewSafeAreaId(safeAreaId: string | null): void;
-	/** Active snap guides for the current interaction (null clears overlay). */
-	getSnapGuides(): ActiveSnapGuides | null;
-	setSnapGuides(guides: ActiveSnapGuides | null): void;
-	on<K extends keyof UIEditorStateEvents>(event: K, handler: (data: UIEditorStateEvents[K]) => void): () => void;
-}
 export type StoryPluginActionCreateInput = {
 	generateId: () => string;
 	initialText?: string;
@@ -19856,6 +18139,49 @@ export type RuntimePluginLocale = {
 export type RuntimePluginMenu = {
 	set(spec: GameMenuSpec): Promise<void>;
 };
+/**
+ * What the engine's image cache is holding, against what it is allowed to hold. All sizes in bytes.
+ *
+ * Restated here rather than re-exported from the engine because a plugin cannot import
+ * `narraleaf-react` - the only module specifiers it can resolve are `narraleaf-studio/*` and React.
+ * The shape is the engine's `ImageCacheStats`; if that grows a field, this is the second place.
+ */
+export type RuntimePluginImageCacheStats = {
+	/** Sources the cache holds a url for. */
+	entries: number;
+	/**
+	 * Bytes of fetched image data the cache is keeping alive.
+	 *
+	 * **Zero is a real answer, not a missing one.** A host that serves its own assets hands the
+	 * player urls instead of bytes, and then the player holds none: what the images cost lives in
+	 * the browser's cache, outside anything this can count. A reader that shows this as "memory
+	 * used" will report an improvement that did not happen - see {@link entries}, which still
+	 * counts, and the decoded figures below, which are the ones with a budget behind them.
+	 */
+	blobBytes: number;
+	/** Sources whose decoded bitmap the cache is holding. */
+	decodedEntries: number;
+	/** Estimated size of those bitmaps, at width x height x 4 bytes each. */
+	decodedBytes: number;
+	/** Entries nothing may evict right now: shown by a mounted element, or pinned by the scene. */
+	pinned: number;
+	/** The budgets in force. `Infinity` where the game removed one. */
+	budget: {
+		blobBytes: number;
+		decodedBytes: number;
+	};
+};
+/**
+ * `diagnostics` — what the player's caches weigh.
+ *
+ * Every member answers null before a game session exists, which is the ordinary state during
+ * `setup()`. A plugin polls this; there is no change event, because a cache that announced every
+ * eviction would cost more to watch than to run.
+ */
+export type RuntimePluginDiagnostics = {
+	/** The engine's image cache, or null when no session is live. */
+	imageCache(): RuntimePluginImageCacheStats | null;
+};
 /** `assets` — turn an asset id from the pack into a URL this shell can load. */
 export type RuntimePluginAssets = {
 	url(assetId: string): string;
@@ -19986,6 +18312,8 @@ export type RuntimePluginGame = {
 	menu?: RuntimePluginMenu;
 	/** Present with `"story.compile"`. */
 	story?: RuntimePluginStory;
+	/** Present with `"diagnostics"`. */
+	diagnostics?: RuntimePluginDiagnostics;
 	/** Present when `contributes.sidecars` is non-empty. */
 	sidecar?: RuntimePluginSidecars;
 	/** Present when `contributes.externalLinks` is non-empty. */
@@ -20006,6 +18334,163 @@ export type RuntimePluginDefinition = {
 };
 export declare function defineRuntimePlugin(definition: RuntimePluginDefinition): RuntimePluginDefinition;
 export declare function isRuntimePluginDefinition(value: unknown): value is RuntimePluginDefinition;
+/**
+ * The interface-editor extension surface a plugin actually gets.
+ *
+ * Studio's own widgets are described by `UIWidgetModule`, whose callbacks are handed the live
+ * `UIDocumentService` and `UIEditorStateService`. Those are `Service` instances, and `getContext()`
+ * on a service is public - so `documentService.getContext().services.get(...)` returns the workspace
+ * service registry, and with it a `FileSystemService` that speaks to the main process under the
+ * window's default privileged facade: recursive read and write over the author's whole project,
+ * authorised as the window rather than as the plugin. That is the same escalation
+ * `pluginWorkspaceGuard` closed on `ActionDefinition.onClick`, reached through the widget door.
+ *
+ * A class instance cannot be made safe by wrapping one method, either: `service.constructor` is the
+ * real class, `Service` extends `Singleton`, and `Singleton.instances` is an ordinary static
+ * property holding every service that has ever been constructed. Anything with that prototype chain
+ * hands over the registry however many members are trapped on the way past.
+ *
+ * So the types below are what a widget is handed instead - plain objects with named methods,
+ * built by `pluginWidgetGuard` and enforced there rather than here. **These declarations state the
+ * contract; they do not impose it.** A plugin ships compiled JavaScript and can cast anything to
+ * anything; the guard is what makes the cast find nothing.
+ *
+ * The surface is derived from what the built-in widgets do, which is the only honest measure of what
+ * a widget needs: read the interface document, write the element's own props, layout, animation,
+ * extra and list-item wiring, group a burst of those into one undo step, and move the selection.
+ * Nothing here reaches outside `uidoc.json`.
+ */
+/**
+ * Interface-document access for a plugin widget.
+ *
+ * Whole-document reads are deliberate: a structural widget cannot resolve its own parts without
+ * looking them up, which is why the game side hands plugin renderers the document too. The document
+ * is authored content the editor is already drawing, not a host power - and it is one document, not
+ * an index that leads to unrelated resources.
+ *
+ * Writes are element-scoped by signature. They are not restricted to the element being inspected: a
+ * widget with parts edits its parts, exactly as the built-in switch and list do, and there is no
+ * honest way to tell "my part" from "someone else's element" from here.
+ */
+export type PluginWidgetDocumentApi = {
+	/** The whole interface document, as the editor currently holds it. */
+	getDocument(): UIDocument;
+	/** A fresh element id, for a widget that builds child elements of its own. */
+	generateId(): string;
+	/** One component definition by id, for a widget that draws a linked component instance. */
+	getComponent(componentId: string): UIComponentDefinition | undefined;
+	createElement(parentId: string, type: string, layoutPatch?: Partial<UILayout>): UIElement;
+	updateElementProps(elementId: string, propsPatch: Record<string, unknown>): void;
+	updateElementExtra(elementId: string, extraPatch: Record<string, unknown>): void;
+	updateElementLayout(elementId: string, layoutPatch: Partial<UILayout>, options?: {
+		skipHistory?: boolean;
+	}): void;
+	updateElementAnimation(elementId: string, animation: UIPageAnimationSettings | null, options?: {
+		mergeKey?: string;
+	}): void;
+	/** Collapse everything the callback writes into one undo entry on that surface. */
+	runSurfaceHistoryTransaction(surfaceId: string, action: () => void): void;
+	setListItemStructFields(elementId: string, fields: readonly UIStructField[]): void;
+	setElementListItemFieldBinding(elementId: string, propPath: string, fieldId: string | null): void;
+	ensureElementBlueprintValueBinding(elementId: string, propPath: string, input: {
+		valueType: UIElementValueBindingValueType;
+		displayName?: string;
+		literalValue?: unknown;
+	}): {
+		blueprintId: string;
+	};
+	clearElementBlueprintValueBinding(elementId: string, propPath: string): void;
+};
+/**
+ * Editor state a plugin widget's docker bar may read and move.
+ *
+ * Selection only. The interaction overrides (inline text edit, image crop) are not here because the
+ * host honours them in built-in renderers alone - offering a plugin a switch that turns nothing on
+ * would be worse than not having it.
+ */
+export type PluginWidgetEditorStateApi = {
+	getSelection(): SelectionState;
+	setUIElementSelection(selection: UIElementSelection): void;
+	getEnteredState(): {
+		surfaceId: string;
+		elementId: string;
+		variantId: string | null;
+	} | null;
+	setEnteredState(next: {
+		surfaceId: string;
+		elementId: string;
+		variantId: string | null;
+	} | null): void;
+};
+/** What a plugin widget's property fields read and write through. */
+export type PluginWidgetInspectorData = {
+	element: UIElement;
+	elements: UIElement[];
+	documentService: PluginWidgetDocumentApi;
+	surfaceId?: string;
+};
+export type PluginWidgetInspectorContext = {
+	element: UIElement;
+	documentService: PluginWidgetDocumentApi;
+};
+export type PluginWidgetDockerBarContext = {
+	element: UIElement;
+	documentService: PluginWidgetDocumentApi;
+	stateService?: PluginWidgetEditorStateApi;
+	surfaceId?: string;
+};
+export type PluginWidgetContextMenuContext = {
+	element: UIElement;
+	documentService: PluginWidgetDocumentApi;
+	surfaceId: string;
+};
+export type PluginWidgetFloatingToolbarContext = {
+	element: UIElement;
+	documentService: PluginWidgetDocumentApi;
+	surfaceId: string;
+	openSurfaceEditor?: (surfaceId: string) => void;
+};
+export type PluginWidgetLayoutSizeFieldContext = {
+	element: UIElement;
+	documentService: PluginWidgetDocumentApi;
+	surfaceId?: string;
+	primaryId: string;
+};
+/**
+ * A widget type contributed by a plugin.
+ *
+ * `render` takes the same {@link RuntimeWidgetRendererProps} the game hands a plugin renderer,
+ * rather than the editor's wider props: one render function, drawn the same way in both places, and
+ * no `hostAdapter` on either side. See `create-plugin.md` for the shared-module pattern that relies
+ * on it.
+ *
+ * `registerBlueprintNodes` is absent on purpose. It exists on the built-in module type and the host
+ * only ever calls it for built-ins; a plugin registers nodes through `app.services.blueprintNodes`,
+ * where the execute context is narrowed the same way this is.
+ */
+export type PluginWidgetModule = {
+	/** Unique type id; must start with the plugin id and be declared in `contributes.widgets`. */
+	readonly type: string;
+	/** Widget type this one specialises. */
+	readonly extends?: string;
+	/** Event and effect capabilities, shared with the blueprint tooling. */
+	readonly logicApi?: WidgetLogicApi;
+	readonly displayName: string;
+	readonly icon: LucideIcon;
+	createDefaultElement(): Partial<UIElement>;
+	createDefaultChildElements?(context: DefaultChildElementContext): DefaultChildElementResult;
+	listEditorStates?(element: UIElement): {
+		id: string | null;
+		name: string;
+	}[];
+	render(props: RuntimeWidgetRendererProps): React$1.ReactElement | null;
+	createInspector?(context: PluginWidgetInspectorContext): PropertyEditorSchema<PluginWidgetInspectorData> | undefined;
+	createDockerBarItems?(context: PluginWidgetDockerBarContext): DockerBarItem[];
+	createMultiSelectDockerBarItems?(context: PluginWidgetDockerBarContext): DockerBarItem[];
+	createContextMenuItems?(context: PluginWidgetContextMenuContext): ContextMenuItemDef[];
+	createFloatingToolbarItems?(context: PluginWidgetFloatingToolbarContext): FloatingToolbarItem[];
+	createLayoutSizeField?(context: PluginWidgetLayoutSizeFieldContext): FieldDefinition<PluginWidgetInspectorData> | null | undefined;
+};
 /**
  * Caller-defined section (e.g. built-in presets) shown as a collapsible group in the asset list.
  * Workspace filter chips do not apply; only the search box filters `assets` (same rules as project assets).
@@ -20561,6 +19046,20 @@ declare const pluginUi: Readonly<{
 	}>;
 }>;
 export type PluginUiKit = typeof pluginUi;
+/**
+ * What a plugin can learn about a widget type it did not register.
+ *
+ * The registry itself holds host objects, so what comes back is the answer to the question a plugin
+ * can act on - does this type exist, and what is it called - rather than the module behind it.
+ */
+export type PluginWidgetTypeInfo = {
+	type: string;
+	displayName: string;
+	/** The widget type this one specialises, when it specialises one. */
+	extends?: string;
+	/** The plugin that contributed it, absent for Studio's own widgets. */
+	ownerPluginId?: string;
+};
 /**
  * A blueprint node as a *plugin* writes it: everything a node declares about itself, with the
  * narrowed execute of `narraleaf-studio/runtime`.
@@ -20812,7 +19311,7 @@ export type PluginAssetsService = {
 	revokeObjectUrl(url: string): void;
 };
 /** An active editor locale code (built-in like "en"/"zh", or a plugin-provided locale). */
-type LocaleCode$1 = string;
+export type LocaleCode = string;
 /**
  * A plugin's own message tables: `locale code -> (message key -> string)`. This
  * is the plugin's private catalog, unrelated to Studio's own translations.
@@ -20832,7 +19331,7 @@ export type PluginMessageBundle = {
  * {@link PluginI18n.onLocaleChange} to re-render on a language switch.
  */
 export type PluginTranslator = {
-	readonly locale: LocaleCode$1;
+	readonly locale: LocaleCode;
 	t(key: string, params?: Record<string, string | number>): string;
 };
 /**
@@ -20842,14 +19341,14 @@ export type PluginTranslator = {
  */
 export type PluginI18n = {
 	/** The editor's active locale code. */
-	readonly locale: LocaleCode$1;
+	readonly locale: LocaleCode;
 	/**
 	 * Subscribe to editor-language changes. The listener fires with the new
 	 * locale code whenever the active editor language changes. Returns a
 	 * {@link PluginCleanup} (also tracked by the host, so it is reclaimed on
 	 * unload even if you forget to call it).
 	 */
-	onLocaleChange(listener: (locale: LocaleCode$1) => void): PluginCleanup;
+	onLocaleChange(listener: (locale: LocaleCode) => void): PluginCleanup;
 	/** Locale-aware number formatting bound to the editor's active locale. */
 	formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
 	/** Locale-aware date formatting bound to the editor's active locale. */
@@ -20983,11 +19482,18 @@ export type PluginServices = {
 			error(message: string): void;
 		};
 	};
+	/**
+	 * Contribute a widget type to the interface editor; see {@link PluginWidgetModule}.
+	 *
+	 * `get` and `list` answer with a type's name rather than with its module. A widget module is
+	 * the host's own object - Studio's built-ins carry the editor services in their callbacks - and
+	 * "which types exist" is the whole of what a plugin can act on.
+	 */
 	widgets: {
-		register(module: UIWidgetModule): PluginCleanup;
-		registerMany(modules: UIWidgetModule[]): PluginCleanup;
-		get(type: string): UIWidgetModule | undefined;
-		list(): UIWidgetModule[];
+		register(module: PluginWidgetModule): PluginCleanup;
+		registerMany(modules: PluginWidgetModule[]): PluginCleanup;
+		get(type: string): PluginWidgetTypeInfo | undefined;
+		list(): PluginWidgetTypeInfo[];
 		has(type: string): boolean;
 	};
 	story: {
@@ -21036,7 +19542,6 @@ export declare function isPluginDefinition(value: unknown): value is PluginDefin
 
 export {
 	BehaviorNodeExecuteResult as RuntimeBlueprintNodeResult,
-	LocaleCode$1 as LocaleCode,
 	SelectOption$1 as SelectOption,
 };