narraleaf-studio 0.4.0 → 0.5.0

package/dist/_api.d.ts

@@ -59,6 +59,7 @@ type FileDetails = {
 	encoding: BufferEncoding | null;
 };
 type TextEncodingId = "utf8" | "utf8bom" | "utf16le" | "utf16be" | "gbk" | "gb18030" | "big5" | "shiftjis" | "euckr" | "windows1252" | "iso88591";
+type PersistedTextEol = "lf" | "crlf";
 type FsTextEncoding = BufferEncoding | TextEncodingId;
 type PluginPermissionPersistence = "temporary" | "permanent";
 type PluginFileSystemPermissionMode = "read" | "write" | "readwrite";
@@ -679,10 +680,32 @@ type StoryActionPayload = {
 	operation: "setBgm" | "playSound" | "stopSound" | "pauseSound" | "resumeSound" | "setVolume" | "setRate" | "muteSound" | "seekSound";
 	objectName?: string;
 	assetId?: string;
+	/**
+	 * The project audio track this row plays on (`ProjectAudioTrack.id`) — the bus it lands on,
+	 * the multiplier applied to {@link volume}, and the fade/loop defaults it inherits.
+	 *
+	 * Only the rows that CREATE a sound (`setBgm`, `playSound`) carry one: a later `/vol piano`
+	 * addresses a handle that already has a track, and letting it name a second would be two
+	 * answers to one question (the compiler reports that as a conflict rather than picking).
+	 *
+	 * Spelled `audioTrackId`, not `trackId`: the latter is Story Motion's key for a timeline row,
+	 * and sharing it would make reference counting across documents ambiguous.
+	 *
+	 * Additive: no document written before this carries it, so no schema bump. Absent — and a
+	 * dangling id, since a track can be deleted — resolves to the built-in for the operation's
+	 * natural bus, which is exactly what the compiler hard-coded before tracks existed.
+	 */
+	audioTrackId?: string;
+	/**
+	 * Fade for this row, in milliseconds, applied in whichever direction the operation goes.
+	 * Absent = the track's own `fadeInMs` / `fadeOutMs`.
+	 */
 	fadeMs?: number;
+	/** 0-1 as authored. Multiplied by the track's gain at compile time. */
 	volume?: number;
 	rate?: number;
 	muted?: boolean;
+	/** Absent = the track's own loop default. */
 	loop?: boolean;
 	/** `seekSound` — where to move the play head, in milliseconds (seconds on the line). */
 	timeMs?: number;
@@ -1096,10 +1119,22 @@ type AutoSaveEntry = {
 	metadata: unknown;
 };
 type AudioClipRegion = {
-	/** Offset from the start of the clip, in milliseconds. Where playback starts, and where a loop returns to. */
+	/** Offset from the start of the clip, in milliseconds. Where playback starts. */
 	inMs?: number;
 	/** Offset from the start of the clip, in milliseconds. Where playback stops, or where a loop turns around. */
 	outMs?: number;
+	/**
+	 * Offset from the start of the clip, in milliseconds. Where each repeat returns to.
+	 *
+	 * Absent means "return to {@link inMs}" - a plain loop, and exactly what every record written
+	 * before this field existed means. Set past the in point it describes the standard VN
+	 * **intro→loop**: `inMs..loopStartMs` plays once, then `loopStartMs..outMs` repeats forever.
+	 *
+	 * Constrained to `inMs <= loopStartMs < outMs`. A value outside that window is dropped rather
+	 * than clamped: clamping would invent a loop point the author never marked, while dropping
+	 * degrades to the plain loop the two other markers already describe.
+	 */
+	loopStartMs?: number;
 };
 declare const UI_PAGE_ANIMATION_PRESETS: readonly [
 	"none",
@@ -1419,6 +1454,12 @@ type PluginContributes = {
 export type PluginManifestV2 = Omit<PluginIdentity, "id" | "name" | "version"> & Required<Pick<PluginIdentity, "id" | "name" | "version">> & {
 	manifestVersion: typeof PluginManifestVersion;
 	description?: string;
+	/**
+	 * Package-relative path to the thumbnail shown beside the plugin's name in
+	 * the Launcher list. Square, at most 512x512, and one of the extensions in
+	 * `PLUGIN_ICON_EXTENSIONS`. Plugins without one keep the name monogram.
+	 */
+	icon?: string;
 	entries: PluginManifestEntries;
 	contributes?: PluginContributes;
 	permissions?: PluginInstallPermission[];
@@ -1460,6 +1501,12 @@ type PluginStatus = "enabled" | "disabled" | "needsAuthorization" | "error";
 export type PluginListItem = {
 	pluginId: string;
 	manifest: NormalizedPluginManifestV2;
+	/**
+	 * `app://` address of the declared icon, absent when the plugin ships none.
+	 * Resolved here rather than in the renderer because only the main process
+	 * knows where the package landed on disk.
+	 */
+	iconUrl?: string;
 	installPath: string;
 	enabled: boolean;
 	builtIn: boolean;
@@ -1729,10 +1776,18 @@ declare const en: {
 				readonly label: "Automatic checkpoint interval";
 				readonly description: "How long to wait before recording a checkpoint in a project's version history. Only ever records when something has changed. Set to 0 to turn automatic checkpoints off.";
 			};
+			readonly checkpointOnClose: {
+				readonly label: "Record a checkpoint when a workspace closes";
+				readonly description: "Record a checkpoint in the project's version history when you close its workspace window, so an unrecorded session is not lost. Independent of the interval above.";
+			};
 			readonly versionControlAuthor: {
 				readonly label: "Author name";
 				readonly description: "Recorded as the author of commits and checkpoints. Leave empty to record NarraLeaf Studio instead.";
 			};
+			readonly versionControlAuthorEmail: {
+				readonly label: "Author email";
+				readonly description: "Recorded next to the author name on commits and checkpoints, as \"Name <email>\". Leave empty to record no address.";
+			};
 			readonly confirmBeforeClose: {
 				readonly label: "Confirm before closing a workspace";
 				readonly description: "Ask for confirmation when you close a workspace window.";
@@ -1785,6 +1840,18 @@ declare const en: {
 			readonly recentTitle: "Recent Projects";
 			readonly openFolder: "Open Folder";
 			readonly importProject: "Import Project";
+			readonly clone: {
+				readonly title: "Get a project from a server";
+				readonly addressLabel: "Project address";
+				readonly addressHint: "Ask whoever set up the project for this address.";
+				readonly folderLabel: "Where to put it";
+				readonly folderPlaceholder: "Choose an empty folder";
+				readonly folderHint: "Must be a new or empty folder.";
+				readonly confirm: "Get project";
+				readonly cancel: "Cancel";
+				readonly working: "Copying the project from the server. This can take a while.";
+				readonly error: "Could not get the project from the server.";
+			};
 			readonly openNamed: "Open {name}";
 			readonly search: {
 				readonly placeholder: "Search projects";
@@ -2169,6 +2236,10 @@ declare const en: {
 					readonly theme: "Theme switcher";
 					readonly zoom: "Zoom level";
 					readonly version: "Version";
+					readonly textFileName: "Text file name";
+					readonly textEncoding: "Text encoding";
+					readonly textLineEnding: "Line ending";
+					readonly textSelection: "Cursor position";
 				};
 			};
 			readonly save: {
@@ -2195,6 +2266,7 @@ declare const en: {
 					readonly localization: "localization";
 					readonly voice: "voice library";
 					readonly variables: "variable registry";
+					readonly audioTracks: "audio tracks";
 					readonly characters: "characters";
 					readonly project: "project settings";
 					readonly assets: "asset library";
@@ -2277,6 +2349,33 @@ declare const en: {
 					readonly platform: "Version control is not available on this machine.";
 					readonly installation: "Version control is not available in this installation of Studio.";
 				};
+				readonly server: {
+					readonly title: "Server";
+					readonly none: "Not connected to a server";
+					readonly connect: "Connect to a server";
+					readonly addressLabel: "Server address";
+					readonly addressPlaceholder: "lore://studio.example.lan:41337";
+					readonly save: "Connect";
+					readonly cancel: "Cancel";
+					readonly disconnect: "Disconnect";
+					readonly check: "Check the server";
+					readonly checking: "Checking the server\u2026";
+					readonly notChecked: "Not checked";
+					readonly upToDate: "Up to date";
+					readonly localAhead: "You have versions the server does not";
+					readonly remoteAhead: "The server has versions you do not";
+					readonly diverged: "You and the server have both moved on";
+					readonly unreachable: "Cannot reach this server";
+					readonly unauthorized: "This server did not accept you";
+					readonly push: "Send to server";
+					readonly pushing: "Sending to the server\u2026";
+					readonly pushedAlready: "The server already has these versions";
+					readonly sync: "Get from server";
+					readonly syncing: "Getting versions from the server\u2026";
+					readonly syncedNothing: "Already up to date";
+				};
+				readonly syncConflictTitle: "Some files could not be merged";
+				readonly syncConflictDetail: string;
 			};
 			readonly keybindings: {
 				readonly searchPlaceholder: "Search shortcuts\u2026";
@@ -2331,6 +2430,12 @@ declare const en: {
 						readonly undo: "Undo";
 						readonly redo: "Redo";
 						readonly delete: "Delete Keyframe";
+						readonly prevFrame: "Step Playhead Back One Frame";
+						readonly nextFrame: "Step Playhead Forward One Frame";
+						readonly prevFrames: "Step Playhead Back Ten Frames";
+						readonly nextFrames: "Step Playhead Forward Ten Frames";
+						readonly playheadStart: "Move Playhead to Start";
+						readonly playheadEnd: "Move Playhead to End";
 					};
 				};
 			};
@@ -2610,6 +2715,7 @@ declare const en: {
 			readonly lineText: "Text";
 			readonly labelName: "Label";
 			readonly scene: "Scene";
+			readonly track: "Audio Track";
 			readonly displayName: "Display Name";
 			readonly seekTime: "Seconds";
 			readonly cameraOperation: "Pan / Zoom / Rotate / Darken / Motion / Reset";
@@ -2691,6 +2797,7 @@ declare const en: {
 					readonly param: "A numeric parameter of its model, by id";
 				};
 				readonly scene: "Scene";
+				readonly audioTrack: "Audio track";
 				readonly label: "Label in this scene";
 				readonly variable: "Variable";
 				readonly content: "New content, typed by the target";
@@ -2766,6 +2873,7 @@ declare const en: {
 			readonly sceneMusicLoop: "Loop";
 			readonly sceneMusicFade: "Fade in (s)";
 			readonly sceneMusicLoopRegion: "Loops {from}s \u2013 {to}s";
+			readonly sceneMusicIntroLoop: "Plays {from}s, loops {loop}s \u2013 {to}s";
 			readonly sceneMusicFromIn: "Starts at {from}s";
 			readonly sceneMusicWholeClip: "Whole clip";
 			readonly backgroundResolveError: "Image asset could not be resolved: {error}";
@@ -3265,6 +3373,7 @@ declare const en: {
 			unknownAsset: string;
 			unknownCharacter: string;
 			unknownScene: string;
+			unknownAudioTrack: string;
 			unknownLabel: string;
 			unknownVariable: string;
 			unknownForm: string;
@@ -3599,6 +3708,8 @@ declare const en: {
 			readonly storyActionTitle: "Story Action";
 		};
 		readonly audio: {
+			readonly track: "Track";
+			readonly trackDefault: "Default ({name})";
 			readonly soundName: "Sound name";
 			readonly bgmAsset: "BGM asset";
 			readonly soundAsset: "Sound asset";
@@ -3929,6 +4040,7 @@ declare const en: {
 				readonly zoomFit: "Fit whole clip";
 				readonly zoomSelection: "Zoom to selection";
 				readonly markIn: "Set in point at playhead";
+				readonly markLoop: "Set loop point at playhead";
 				readonly markOut: "Set out point at playhead";
 				readonly channels: "{count} ch";
 			};
@@ -3942,13 +4054,16 @@ declare const en: {
 				readonly nudgeForwardCoarse: "Nudge playhead forward one second";
 				readonly loop: "Toggle loop";
 				readonly markIn: "Set in point";
+				readonly markLoop: "Set loop point";
 				readonly markOut: "Set out point";
 				readonly goToIn: "Go to in point";
+				readonly goToLoop: "Go to loop point";
 				readonly goToOut: "Go to out point";
 				readonly clearIn: "Clear in point";
+				readonly clearLoop: "Clear loop point";
 				readonly clearOut: "Clear out point";
-				readonly undo: "Undo in/out change";
-				readonly redo: "Redo in/out change";
+				readonly undo: "Undo marker change";
+				readonly redo: "Redo marker change";
 				readonly selectAll: "Select whole clip";
 				readonly clearSelection: "Clear selection";
 				readonly zoomIn: "Zoom in";
@@ -3989,8 +4104,14 @@ declare const en: {
 			readonly loadFailed: "Failed to read this file.";
 			readonly saveFailed: "Failed to save this file.";
 			readonly caret: "Ln {line}, Col {column}";
+			readonly selected: "({count} selected)";
+			readonly selectedInRanges: "({count} selected in {ranges} ranges)";
+			readonly selectionLabel: "Cursor position and selection";
 			readonly reopenWithEncoding: "Reopen with Encoding";
 			readonly saveWithEncoding: "Save with Encoding";
+			readonly selectEncoding: "Select the file's encoding";
+			readonly selectLineEnding: "Select the file's line ending";
+			readonly lineEndingLabel: "Line ending: {ending}";
 			readonly encodingLabel: "Encoding: {encoding}";
 			readonly actionFailed: "This action failed.";
 		};
@@ -4343,6 +4464,8 @@ declare const en: {
 			readonly untitledSurface: "Untitled surface";
 			readonly untitledStory: "Untitled story";
 			readonly untitledScene: "Untitled scene";
+			readonly unnamedCharacter: "Unnamed character";
+			readonly missingCharacter: "Missing character ({id})";
 		};
 		readonly tsPane: {
 			readonly importHint: "Allowed import: \"narraleaf-studio\"";
@@ -4385,6 +4508,7 @@ declare const en: {
 			readonly array: "Array";
 			readonly asset: "Asset";
 			readonly autoForward: "Auto Forward";
+			readonly avatar: "Avatar";
 			readonly bgmVolume: "BGM Volume";
 			readonly body: "Body";
 			readonly boolean: "Boolean";
@@ -4395,6 +4519,7 @@ declare const en: {
 			readonly case: "Case";
 			readonly case0: "Case 0";
 			readonly case1: "Case 1";
+			readonly character: "Character";
 			readonly circIn: "Circ In";
 			readonly circInOut: "Circ In Out";
 			readonly circOut: "Circ Out";
@@ -4431,6 +4556,7 @@ declare const en: {
 			readonly field: "Field";
 			readonly float: "Float";
 			readonly fnName: "Fn Name";
+			readonly found: "Found";
 			readonly frame: "Frame";
 			readonly from: "From";
 			readonly function: "Function";
@@ -4465,6 +4591,8 @@ declare const en: {
 			readonly loop: "Loop";
 			readonly playing: "Playing";
 			readonly fadeS: "Fade (s)";
+			readonly fadeInS: "Fade In (s)";
+			readonly audioTrack: "Track";
 			readonly timeS: "Time (s)";
 			readonly max: "Max";
 			readonly maxOffset: "Max Offset";
@@ -4617,6 +4745,7 @@ declare const en: {
 			readonly getAvailableLanguages: "Get Available Languages";
 			readonly getBacklog: "Get Backlog";
 			readonly getBounds: "Get Bounds";
+			readonly getCharacter: "Get Character";
 			readonly getChoiceCount: "Get Choice Count";
 			readonly getCurrentLanguage: "Get Current Language";
 			readonly getDisplay: "Get Display";
@@ -4666,6 +4795,7 @@ declare const en: {
 			readonly getSliderRange: "Get Slider Range";
 			readonly getSliderValue: "Get Slider Value";
 			readonly getSpeakerAvatar: "Get Speaker Avatar";
+			readonly getSpeakerColor: "Get Speaker Color";
 			readonly getText: "Get Text";
 			readonly getTextAlign: "Get Text Align";
 			readonly getTextColor: "Get Text Color";
@@ -4974,18 +5104,27 @@ declare const en: {
 				readonly customNameHint: "Also the folder it lives in, under runtimes/puppet/.";
 			};
 			readonly poses: "Poses";
-			readonly newPose: "New pose";
 			readonly removePose: "Remove pose";
+			readonly defaultPoseName: "Pose {n}";
+			readonly defaultAxisName: "Axis {n}";
+			readonly defaultTagName: "Tag {n}";
+			readonly defaultLayerName: "Layer {n}";
+			readonly renameHint: "Double-click or F2 to rename";
 			readonly avatar: "Dialog avatar";
 			readonly avatarAxis: "Avatar varies with this axis";
+			readonly avatarClearOverride: "Remove override";
+			readonly rebake: "Re-bake avatars";
+			readonly bakeReceipt: "{written} written \u00B7 {unresolved} without art \u00B7 {removed} removed";
+			readonly selectImage: "Choose an image";
+			readonly selectAvatarImage: "Choose an avatar image";
 			readonly axes: "Axes";
-			readonly newAxis: "New axis";
 			readonly removeAxis: "Remove axis";
 			readonly newTag: "New tag";
 			readonly removeTag: "Remove tag";
 			readonly makeDefault: "Make default";
+			readonly isDefault: "Default";
+			readonly changeImage: "Change image";
 			readonly layers: "Layers";
-			readonly newLayer: "New layer";
 			readonly removeLayer: "Remove layer";
 			readonly constantLayer: "Always drawn";
 			readonly hasImage: "image set";
@@ -5038,54 +5177,28 @@ declare const en: {
 				readonly axisNoTags: "{name} has no tags";
 				readonly axisUnused: "{name} drives no layer";
 				readonly duplicateTag: "{axis} has two tags named {name}";
+				readonly duplicateAxis: "Two axes are named {name}";
+				readonly axisDefaultMissing: "{axis} has no default tag; {name} is used instead";
 				readonly occluded: "{name} is completely covered by the layers above it";
 				readonly avatarCombinations: "{count} dialog avatars will be baked; narrow the axes to reduce it";
+				readonly combinationNoArt: "{name} draws nothing at all";
+				readonly snapshotStale: "{name} was saved with tags that no longer exist";
+				readonly poseNoImage: "{name} has no image";
+				readonly noPoses: "This character has no poses, so nothing draws";
+				readonly defaultPoseMissing: "The default pose was deleted; {name} is used instead";
+				readonly duplicatePose: "Two poses are named {name}";
 			};
 			readonly header: {
 				readonly fallbackName: "Character";
 				readonly subtitle: "Character Editor";
 			};
-			readonly selectVariantImage: "Select Variant Image";
-			readonly dialog: {
-				readonly newFormTitle: "New Form";
-				readonly formNamePlaceholder: "Enter form name";
-				readonly renameFormTitle: "Rename Form";
-				readonly newVariantTitle: "New Variant";
-				readonly variantNamePlaceholder: "Enter variant name";
-				readonly newGroupTitle: "New Variant Group";
-				readonly groupNamePlaceholder: "Enter group name";
-				readonly renameGroupTitle: "Rename Group";
-				readonly renameVariantTitle: "Rename Variant";
-			};
-			readonly validation: {
-				readonly nameRequired: "Name is required";
-				readonly formExists: "Form already exists";
-				readonly formNotFound: "Form not found";
-				readonly variantExists: "Variant already exists in this form";
-				readonly groupExists: "Group already exists";
-			};
-			readonly notify: {
-				readonly renameFormFailed: "Unable to rename form";
-				readonly variantNameUnique: "Variant name must be unique within the form";
-				readonly deleteUngroupedBucket: "Cannot delete ungrouped bucket";
-				readonly renameUngroupedBucket: "Cannot rename ungrouped bucket";
-				readonly renameGroupFailed: "Unable to rename group";
-				readonly renameVariantFailed: "Unable to rename variant";
-			};
 			readonly confirm: {
-				readonly deleteFormTitle: "Delete form \"{name}\"?";
-				readonly deleteFormDetail: "Groups and variants inside will be removed.";
-				readonly deleteGroupTitle: "Delete group \"{name}\"?";
-				readonly deleteGroupDetail: "Variants inside will be removed.";
-				readonly deleteVariantTitle: "Delete variant \"{name}\"?";
-				readonly deleteVariantDetail: "Asset binding will be removed.";
-			};
-			readonly menu: {
-				readonly renameVariant: "Rename Variant";
-				readonly setAsDefault: "Set as Default";
-				readonly deleteVariant: "Delete Variant";
-				readonly renameForm: "Rename Form";
-				readonly deleteForm: "Delete Form";
+				readonly deleteTitle: "Delete \"{name}\"?";
+				readonly deletePoseDetail: "Story rows that name this pose will no longer resolve one.";
+				readonly deleteAxisDetail: "Layers bound to it become constant and lose their per-tag images.";
+				readonly deleteTagDetail: "Images assigned to this tag are released.";
+				readonly deleteLayerDetail: "Its images are released.";
+				readonly deleteSnapshotDetail: "The combination itself is unaffected \u2014 only the name is removed.";
 			};
 		};
 		readonly properties: {
@@ -5093,6 +5206,9 @@ declare const en: {
 			readonly thumbnail: "Thumbnail";
 			readonly preview: "Preview";
 			readonly defaultAvatar: "Dialog avatar";
+			readonly voiceTrack: "Voice bus";
+			readonly voiceTrackMissing: "Missing bus";
+			readonly voiceTrackEmpty: "Add a bus under Voice in Project \u2192 Audio to give this character its own volume.";
 			readonly select: "Select";
 			readonly thumbnailAlt: "thumbnail";
 			readonly color: "Color";
@@ -5116,18 +5232,6 @@ declare const en: {
 				readonly unknown: "Unknown error";
 			};
 		};
-		readonly formsPanel: {
-			readonly title: "Forms";
-			readonly addForm: "Add form";
-			readonly expand: "Expand forms";
-			readonly collapse: "Collapse forms";
-			readonly default: "Default";
-			readonly formActions: "Form actions";
-			readonly groupCount: {
-				readonly one: "{count} group";
-				readonly other: "{count} groups";
-			};
-		};
 		readonly preview: {
 			readonly title: "Preview";
 			readonly currentForm: "Current form: {name}";
@@ -5142,30 +5246,9 @@ declare const en: {
 			readonly resetView: "Reset View";
 			readonly alt: "Variant preview";
 			readonly setPortrait: "Portrait framing";
-			readonly resetPortrait: "Reset portrait framing";
+			readonly resetPortrait: "Frame automatically";
 			readonly portraitTitle: "Portrait framing";
-			readonly portraitFormScopedOff: "Frame this form only";
-			readonly portraitFormScopedOn: "Framing this form only \u2014 click to inherit the default";
-		};
-		readonly variantsPanel: {
-			readonly title: "Variants";
-			readonly expand: "Expand variants";
-			readonly collapse: "Collapse variants";
-			readonly addGroup: "Add group";
-			readonly addVariant: "Add variant";
-			readonly addVariantToGroup: "Add variant to group";
-			readonly ungrouped: "Ungrouped";
-			readonly default: "Default";
-			readonly changeImage: "Change image";
-			readonly variantActions: "Variant actions";
-			readonly renameGroup: "Rename group";
-			readonly deleteGroup: "Delete group";
-			readonly groupPrefix: "Group: {name}";
-			readonly selectForm: "Select a form from the left.";
-			readonly variantCount: {
-				readonly one: "{count} variant";
-				readonly other: "{count} variants";
-			};
+			readonly portraitScoped: "Frame this look only";
 		};
 	};
 	readonly properties: {
@@ -5976,6 +6059,8 @@ declare const en: {
 			readonly autoplayHint: "Applies in the game. The editor canvas stays paused; use the docker bar to preview.";
 			readonly volume: "Volume";
 			readonly volumeHint: "0 to 1. A blueprint volume pin overrides this at runtime.";
+			readonly audioTrack: "Audio Track";
+			readonly audioTrackDefault: "SFX";
 			readonly playbackRate: "Speed";
 			readonly controls: "Native controls";
 			readonly controlsHint: "Shows the browser's own play bar over the clip.";
@@ -6512,6 +6597,10 @@ declare const en: {
 				readonly title: "Game";
 				readonly description: "How the finished game behaves for players";
 			};
+			readonly audio: {
+				readonly title: "Audio";
+				readonly description: "The mixer: which bus feeds which, and how loud each one is";
+			};
 			readonly assets: {
 				readonly title: "Assets";
 				readonly description: "Application icons for each platform";
@@ -6580,6 +6669,37 @@ declare const en: {
 			readonly autoSaveSlotsTitle: "Autosaves kept";
 			readonly autoSaveSlotsDescription: "Autosaves rotate through this many slots, oldest overwritten first. They stay out of the player's own save slots and are read with the List Auto Saves node.";
 		};
+		readonly audio: {
+			readonly add: "Add track";
+			readonly newTrackName: "New Track";
+			readonly nameTitle: "Name";
+			readonly nameDescription: "What this bus is called across Studio. References are stored by id, so renaming one is safe.";
+			readonly parentTitle: "Routes into";
+			readonly parentDescription: "The bus this one feeds. Every bus between here and the master output multiplies its volume in.";
+			readonly parentMaster: "Master output";
+			readonly volumeTitle: "Volume";
+			readonly volumeDescription: "This bus's own level, applied live to everything playing on it or below it. A bus can quieten, never amplify.";
+			readonly volumeUnit: "%";
+			readonly loopTitle: "Loop by default";
+			readonly loopDescription: "Clips played on this track repeat unless the action that plays them says otherwise.";
+			readonly duplicate: "Duplicate";
+			readonly delete: "Delete";
+			readonly deleteConfirm: "Delete \"{name}\"?";
+			readonly deleteDetail: {
+				readonly one: "{count} reference falls back to its default bus.";
+				readonly other: "{count} references fall back to their default bus.";
+			};
+			readonly deleteChildren: {
+				readonly one: "{count} track under it moves to {parent}.";
+				readonly other: "{count} tracks under it move to {parent}.";
+			};
+			readonly slider: {
+				readonly bgm: "BGM Volume";
+				readonly sound: "Sound Volume";
+				readonly voice: "Voice Volume";
+				readonly global: "Global Volume";
+			};
+		};
 		readonly settings: {
 			readonly allowHttpTitle: "Allow HTTP";
 			readonly allowHttpDescription: "When off, the game is confined to the app protocol and all HTTP/HTTPS requests are blocked.";
@@ -6859,6 +6979,9 @@ declare const en: {
 			};
 			readonly versionControl: {
 				readonly description: "Set up version control for your project.";
+				readonly loreHint: "A version history is created inside the project folder, recording it as the first version.";
+				readonly unavailablePlatform: "Version control is not available on this machine, so the project is created without it.";
+				readonly unavailableInstallation: "Version control is not available in this installation of Studio, so the project is created without it.";
 			};
 			readonly projectLocation: "Project Location";
 			readonly projectLocationPlaceholder: "Enter project location\u2026";
@@ -7279,10 +7402,17 @@ declare const en: {
 			readonly aliasLocked: "Enter the keystore password";
 			readonly aliasEmpty: "No signing key in this keystore";
 			readonly keyPasswordSame: "Same as the keystore password";
+			readonly macIdentityLoading: "Reading the keychain\u2026";
+			readonly macIdentityEmpty: "This Mac holds no code-signing certificate. Install your Developer ID certificate in Keychain Access, or import it as a certificate file instead.";
+			readonly macIdentityNotDeveloperId: "not for distribution";
+			readonly notarized: "Notarized with Apple";
+			readonly notNotarized: "Not notarized - Gatekeeper warns players on first launch";
 			readonly kind: {
 				readonly "windows-pfx": "Certificate file";
 				readonly "windows-store": "Windows certificate store";
 				readonly "windows-azure": "Azure Trusted Signing";
+				readonly "macos-keychain": "Certificate in the keychain";
+				readonly "macos-apple": "Certificate file";
 				readonly "android-keystore": "Release keystore";
 				readonly "ios-apple": "Apple identity";
 				readonly "linux-gpg": "GPG key";
@@ -7306,6 +7436,10 @@ declare const en: {
 				readonly publisher: "Publisher";
 				readonly keyId: "Key ID";
 				readonly gpgPath: "gpg path";
+				readonly macIdentity: "Certificate";
+				readonly notaryKey: "Notary key (.p8)";
+				readonly notaryKeyId: "Notary key ID";
+				readonly notaryIssuerId: "Notary issuer ID";
 			};
 		};
 		readonly output: {
@@ -7350,8 +7484,11 @@ declare const en: {
 			readonly "signing-credential-expiring": "The {platform} signing certificate expires on {notAfter}, in {days} day(s). Builds signed and timestamped before then stay valid afterwards, but new ones need a renewed certificate.";
 			readonly "signing-secret-unavailable": "The password for the {platform} signing credential cannot be read on this machine: it is sealed with the system keyring, which is unavailable here or belonged to a different user account. Import the credential again to store the password afresh.";
 			readonly "signing-tool-missing": "Signing the {platform} build needs {tool}, which this machine does not have. Install it and make sure it is on your PATH, then reopen this dialog.";
-			readonly "signing-host-unsupported": "This machine runs {host}, which cannot sign the {platform} build with the selected credential: a certificate held in the Windows certificate store is only reachable from Windows. Use a certificate file instead, or build this target on a Windows machine.";
-			readonly "signing-needs-network": "Signing the {platform} build reaches the network - the signature is timestamped by a certificate authority, cloud signing runs remotely, and a machine without the Windows SDK downloads the signing tool first. Everything else about this build works offline.";
+			readonly "signing-host-unsupported": "This machine runs {host}, which cannot sign the {platform} build with the selected credential: its private key is held by an operating-system service that only exists on that platform - the Windows certificate store, or the macOS keychain that Apple's codesign reads. Build this target on a machine of that platform.";
+			readonly "signing-needs-network": "Signing the {platform} build reaches the network: signatures are timestamped by a certificate authority, cloud signing and Apple notarization run remotely, and a host missing a signing tool downloads it first. Everything else about this build works offline.";
+			readonly "signing-macos-identity-missing": "No certificate named {identity} is in this Mac's keychain, so codesign has nothing to sign with. Install it in Keychain Access, or choose another certificate here.";
+			readonly "signing-macos-identity-unusable": "The certificate {identity} is in this Mac's keychain, but it cannot sign: it has expired, its private key is not there, or its issuing chain is incomplete. Open it in Keychain Access to see which - a certificate imported without Apple's intermediate certificate is the usual cause.";
+			readonly "signing-macos-not-developer-id": "{identity} is not a \"Developer ID Application\" certificate. The build will be signed and will run on this Mac, but Gatekeeper refuses it on anyone else's and Apple will not notarize it. Only a Developer ID certificate works for software distributed outside the App Store.";
 			readonly "signing-android-not-play": "The signed APK is for sideloading and for stores that accept APKs, such as itch.io. Google Play is not one of them: it accepts only AAB packages, which this pipeline does not produce.";
 			readonly "signing-ios-profile-mismatch": "The app id {bundleId} is not covered by the provisioning profile, which is issued for {profileAppId}. iOS refuses to install an app the profile does not name - change the project identifier, or import the profile that covers it.";
 			readonly "cross-build-download": "Cross-building for {platforms} downloads Electron on first use (cached afterwards).";
@@ -7390,10 +7527,6 @@ declare const en: {
 				readonly one: "{count} word";
 				readonly other: "{count} words";
 			};
-			readonly nodes: {
-				readonly one: "{count} node";
-				readonly other: "{count} nodes";
-			};
 			readonly days: {
 				readonly one: "{count} day";
 				readonly other: "{count} days";
@@ -7418,7 +7551,7 @@ declare const en: {
 			readonly totalWords: "Words";
 			readonly characters: "Characters";
 			readonly assets: "Assets";
-			readonly blueprints: "Blueprints";
+			readonly blueprintNodes: "Blueprint nodes";
 			readonly uiSurfaces: "Interface surfaces";
 			readonly variables: "Variables";
 		};
@@ -7499,7 +7632,7 @@ declare const en: {
 				readonly message: "{asset} collides with {other} on case-insensitive filesystems";
 			};
 			readonly portabilityMediaFormat: {
-				readonly title: "Unsupported media format";
+				readonly title: "Unplayable format";
 				readonly description: "A codec some selected build targets cannot play";
 				readonly message: "{asset} does not play on {platform}";
 			};
@@ -7960,6 +8093,29 @@ interface AssetExtras {
 	 * extra state at all, and re-detection keeps working if a later Studio learns a new format.
 	 */
 	modelEntry?: string;
+	/**
+	 * Text assets only: the encoding the author said this file is in.
+	 *
+	 * A property of the *file*, not of the window, which is why it rides the record into version
+	 * control rather than sitting in session state: the point of a shared plan file is that the
+	 * colleague who opens the GBK spreadsheet next gets it right without having to know. Outranks
+	 * the byte-order-mark sniff on open, because an author who said so has said more than a
+	 * heuristic can.
+	 *
+	 * Written only when the author explicitly reopens or saves under an encoding. Absent - the
+	 * normal state - means "sniff the BOM, then UTF-8", so merely reading a file never produces a
+	 * change to commit.
+	 */
+	textEncoding?: TextEncodingId;
+	/**
+	 * Text assets only: the line ending this file uses.
+	 *
+	 * Recorded for the same reason as {@link textEncoding}, and needed at all because a *new* text
+	 * file is zero bytes: there is nothing in the content to detect, so the platform that created it
+	 * is the only thing that can answer. For a file that has content, the content wins - see
+	 * `resolveLineEnding` - and this is only the fallback.
+	 */
+	textEol?: PersistedTextEol;
 	/**
 	 * Superseded by {@link audioLoop}, which replaced a free list of markers with the one in/out
 	 * pair a clip actually has. Read only so records written by the short-lived cue-point model
@@ -8027,8 +8183,14 @@ type UIListItemScope = {
 	count: number;
 	key: string;
 };
-declare const BLUEPRINT_HOST_API_CONTRACT_VERSION: 29;
+declare const BLUEPRINT_HOST_API_CONTRACT_VERSION: 30;
 type BlueprintHostApiContractVersion = typeof BLUEPRINT_HOST_API_CONTRACT_VERSION;
+type BlueprintRGBAColor = {
+	r: number;
+	g: number;
+	b: number;
+	a: number;
+};
 type BlueprintImageAsset = {
 	kind: "imageAsset";
 	assetId: string;
@@ -8037,6 +8199,19 @@ type BlueprintSoundHandle = {
 	kind: "soundHandle";
 	id: string;
 };
+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;
@@ -8400,6 +8575,18 @@ type BlueprintHostApiRuntime = {
 		 * 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;
+		/**
+		 * 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;
@@ -8428,6 +8615,37 @@ type BlueprintHostApiRuntime = {
 		/** 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>;
 	};
 	devtools: {
 		log: (level: string, message: string) => void;
@@ -8441,9 +8659,25 @@ declare const BLUEPRINT_SOUND_CHANNELS: readonly [
 type BlueprintSoundChannel = (typeof BLUEPRINT_SOUND_CHANNELS)[number];
 type BlueprintSoundPlayInput = {
 	assetId: string;
-	channel: BlueprintSoundChannel;
-	loop: boolean;
-	volume: number;
+	/**
+	 * 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;
+	/**
+	 * The pre-track channel select, kept only so a graph or a host call written before tracks
+	 * existed still plays on the bus it named. Read only when `audioTrackId` is unset, and mapped
+	 * to that channel's built-in track by the transport. Nothing writes it any more.
+	 */
+	channel?: BlueprintSoundChannel;
 };
 type GameLocalizationConfigSnapshot = Pick<GameLocalizationBundle, "sourceLocale" | "locales"> & Partial<Pick<GameLocalizationBundle, "tables" | "keys">>;
 type BlueprintGameNotification = {
@@ -9884,6 +10118,8 @@ declare enum Services {
 	ProjectStats = "projectStats",
 	/** Project-level persistent variable registry (blueprint-declared persistent vars); M-VAR */
 	VariableRegistry = "variableRegistry",
+	/** Project-level audio tracks: the authoring-time mix presets every audio surface points at */
+	AudioTracks = "audioTracks",
 	/** Aggregate "is my work on disk?" state: auto-saver states + the table of files that failed */
 	SaveStatus = "saveStatus",
 	Localization = "localization",
@@ -10799,6 +11035,14 @@ export interface SelectProps {
 	menuDataAttributes?: Record<`data-${string}`, string | undefined>;
 	/** Optional z-index override for the dropdown menu panel. */
 	menuZIndex?: number;
+	/**
+	 * Accessible name for the trigger.
+	 *
+	 * The trigger's own text is the *selected value*, not what the value means, so a select whose
+	 * visible label lives in a row header beside it reaches assistive tech announcing "Voice" with
+	 * no clue that the question was "routes into". Pass the row's title.
+	 */
+	ariaLabel?: string;
 	/**
 	 * This select changes what is SHOWN and writes nothing.
 	 *
@@ -10808,8 +11052,22 @@ export interface SelectProps {
 	 * getting it wrong offers a write inside a frozen project.
 	 */
 	inspectOnly?: boolean;
+	/**
+	 * This select normally writes, but right now it may only be read.
+	 *
+	 * **Open, not shut.** `disabled` is the obvious treatment and it is the wrong one here: a
+	 * dropdown that cannot be opened hides its option list, and on a frozen project that list is
+	 * project data the author came to look at - which keys exist, which states this element has,
+	 * what the choices even were. So the trigger still opens (through {@link InspectOnlyButton}, so
+	 * an ancestor clamp cannot reach it either), the menu still renders with the current value
+	 * marked, and every row is inert.
+	 *
+	 * Different from {@link inspectOnly}, which is for a select whose `onChange` never writes at
+	 * all and whose rows therefore stay live.
+	 */
+	readOnly?: boolean;
 }
-declare function Select({ options, value, onChange, placeholder, disabled, size, variant, fullWidth, className, multiple, portalMenu, menuPlacement, menuClassName, menuDataAttributes, menuZIndex, inspectOnly, }: SelectProps): import("react/jsx-runtime").JSX.Element;
+declare function Select({ options, value, onChange, placeholder, disabled, size, variant, fullWidth, className, multiple, portalMenu, menuPlacement, menuClassName, menuDataAttributes, menuZIndex, inspectOnly, readOnly, ariaLabel, }: SelectProps): import("react/jsx-runtime").JSX.Element;
 declare function Combobox({ options, value, onChange, placeholder, disabled, size, variant, fullWidth, className, filterOptions, }: SelectProps & {
 	filterOptions?: boolean;
 }): import("react/jsx-runtime").JSX.Element;
@@ -10829,6 +11087,90 @@ export interface SwitchProps extends Omit<React$1.ButtonHTMLAttributes<HTMLButto
 	loading?: boolean;
 }
 declare function Switch({ checked, onCheckedChange, size, variant, disabled, loading, className, onClick, ...props }: SwitchProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * What a control inside an editor renders as while the workspace is frozen.
+ *
+ * The correctness half of freeze is not here and never will be: `@/lib/app/writeFreeze` refuses every
+ * write of project data at the boundary, so nothing a panel does while frozen reaches the author's
+ * files. This module is the other half - **do not offer an action that cannot happen.** Measured
+ * before it existed: a frozen workspace let the author walk the whole New Scene flow, name the scene,
+ * press OK, and get a tab for a scene that was never written. The app said yes and then discarded it.
+ *
+ * It follows `components/ui/freezeActionPolicy` (the same decision, for the top bar) on all four
+ * counts, because a workspace where the top bar and the panels disagree about what a freeze looks like
+ * teaches the author nothing:
+ *
+ *  - **Disabled, not hidden.** A control that vanishes cannot explain itself; the author reads the gap
+ *    as a broken editor rather than as a frozen project. So {@link FreezeGuard.writes} greys a button
+ *    and puts the reason on it, and never removes it.
+ *  - **One reason, one string.** `workspace.shell.freeze.unavailable` is the same text the top bar
+ *    uses. The author learns "this is what frozen looks like" once instead of reading a different
+ *    excuse per panel.
+ *  - **Navigation, selection and inspection are never touched.** Opening a tab, selecting an element,
+ *    reading its properties, expanding a tree, scrolling a timeline: all of that is the entire point of
+ *    a frozen workspace, so nothing here has any business disabling it. Only the write is blocked.
+ *  - **Computed at render, never written back.** Documents, registries and registered menu items
+ *    outlive a freeze; a freeze that marked them disabled would leave them disabled after the thaw.
+ *
+ * Two shapes, because the surfaces genuinely differ. A button has somewhere to put a reason;
+ * a drag gesture does not, and {@link FreezeGuard.gesture} makes it inert instead - a half-inert
+ * gesture (drag starts, drop does nothing) is worse than either, because it reads as a bug.
+ */
+export type FrozenControlProps = {
+	disabled: boolean;
+	/** Hover text: the freeze reason when the freeze is why, the caller's own otherwise. */
+	title: string | undefined;
+};
+export type FreezeGuard = {
+	/** Whether this window's project data is frozen right now. */
+	readonly frozen: boolean;
+	/**
+	 * The single hover string for everything the freeze switches off.
+	 *
+	 * Exposed for the call sites that build their own `title` (a control that already composes one,
+	 * a tooltip component); prefer {@link writes}, which picks between this and the caller's own.
+	 */
+	readonly reason: string;
+	/**
+	 * Render props for a control whose action writes project data.
+	 *
+	 * `ownDisabled` / `ownTitle` are the control's existing state, kept intact: a button that was
+	 * already disabled for its own reason must not start claiming the freeze is why, because that
+	 * lie outlives the thaw.
+	 */
+	writes(ownDisabled?: boolean, ownTitle?: string): FrozenControlProps;
+	/**
+	 * The render fields for a menu row that writes project data.
+	 *
+	 * The row still renders, so the author can see the action exists - the same bargain the top bar's
+	 * menus make - and `tooltip` says why it is off. That field only exists because this pass added it
+	 * to `ContextMenuItemDef`; before it, a greyed row carried no reason at all, and the explanation
+	 * could not go in the label without turning a disabled menu into a paragraph.
+	 */
+	menuRow(ownDisabled?: boolean): {
+		disabled: boolean;
+		tooltip: string | undefined;
+	};
+	/**
+	 * A drag/pointer handler, or `undefined` while frozen - so the gesture is never half-attached.
+	 *
+	 * Returning `undefined` rather than a no-op is deliberate: `draggable`, `onDragOver` and React
+	 * Flow's `nodesDraggable` all key off whether a handler is there, and a present-but-inert
+	 * `onDragStart` produces a drag that picks up and refuses to drop. Pass the whole set through
+	 * this, or none of it.
+	 */
+	gesture<F>(handler: F): F | undefined;
+	/**
+	 * A handler that has no control to grey out - a keybinding, a dialog's confirm, a drop target -
+	 * wrapped so it does nothing while frozen.
+	 *
+	 * The author is not told here. They will be: the write boundary announces the refusal through
+	 * `SaveStatusService` the moment anything tries to save, and a toast per blocked keystroke would
+	 * bury that one useful message under a dozen.
+	 */
+	run<A extends unknown[], R>(handler: (...args: A) => R): (...args: A) => R | undefined;
+};
+declare function useFreezeGuard(): FreezeGuard;
 type DivProps = React$1.HTMLAttributes<HTMLDivElement>;
 declare function PluginAssetSelector(props: AssetSelectorProps): import("react/jsx-runtime").JSX.Element | null;
 export type PluginPanelRootProps = DivProps & {
@@ -10862,6 +11204,20 @@ export type PluginPanelEmptyStateProps = DivProps & {
 };
 declare function PluginPanelEmptyState({ icon, title, description, actions, className, ...props }: PluginPanelEmptyStateProps): import("react/jsx-runtime").JSX.Element;
 declare const pluginUi: Readonly<{
+	/**
+	 * What a plugin's writing controls render as while the project is read-only.
+	 *
+	 * Studio's own panels call this, and a plugin surface calling it renders the identical
+	 * treatment: greyed rather than hidden, one shared reason on hover, and navigation, selection and
+	 * inspection left completely alone - a frozen project is one the author came to *read*. Route
+	 * every control that writes through `writes()`, every drag through `gesture()`, and every
+	 * keybinding or dialog confirm through `run()`.
+	 *
+	 * Affordance only. The refusal itself happens at the write boundary whether a plugin opts in or
+	 * not; what opting in buys is not lying to the author about what will happen. See
+	 * `services.workspace` for the non-React half.
+	 */
+	useFreezeGuard: typeof useFreezeGuard;
 	Button: typeof Button;
 	IconButton: typeof IconButton;
 	Input: typeof Input;
@@ -10934,6 +11290,7 @@ export type PluginBlueprintNodeDef = Omit<BlueprintNodeDef, "execute"> & {
  */
 export type PluginBlueprintNodeContext = RuntimeBlueprintNodeContext;
 export declare const ui: Readonly<{
+	useFreezeGuard: typeof useFreezeGuard;
 	Button: typeof Button;
 	IconButton: typeof IconButton;
 	Input: typeof Input;
@@ -11038,10 +11395,59 @@ export type PluginTextEditorService = {
 	registerPreview(def: PluginTextEditorPreviewDef): PluginCleanup;
 	registerAction(def: PluginTextEditorActionDef): PluginCleanup;
 };
+/**
+ * Anything a plugin writes through {@link PluginStorageService} is **project content**: it lands in
+ * `editor/services/`, inside the versioned working tree, alongside the story and the assets. Two
+ * consequences follow, and this service is how a plugin answers both of them.
+ */
 export type PluginStorageService = {
 	readJson<T extends Record<string, any>>(namespace: string): Promise<T | null>;
+	/**
+	 * Writes are **silently discarded while the project is frozen** ({@link PluginWorkspaceService}).
+	 * That is deliberate at the boundary - it is what keeps a version the author is only *looking* at
+	 * from being written over - but it means a plugin that mutates its own memory first and writes
+	 * second ends up with memory the disk does not have. Check `workspace.frozen` before you mutate,
+	 * not after.
+	 */
 	writeJson<T extends Record<string, any>>(namespace: string, data: T): Promise<void>;
 };
+/** Why project data is currently read-only: an older version is on screen, or the author froze it. */
+export type PluginFreezeReason = "revision" | "manual";
+/**
+ * The state of the project a plugin's data lives in.
+ *
+ * Studio's version control moves the whole working tree under the editors' feet - restoring a past
+ * version, or displaying one read-only while the author browses history - and a plugin store is part
+ * of that tree. So there are exactly two things a plugin has to do to be version-controlled, and both
+ * are here:
+ *
+ *  - **Do not offer a write that cannot happen.** While `frozen`, project writes are refused at the
+ *    boundary; a plugin that keeps its buttons live lets the author edit and then throws the edit
+ *    away. Grey them out (`ui.useFreezeGuard()` renders exactly what Studio's own panels render) and
+ *    make every mutation bail before it touches memory.
+ *  - **Re-read when Studio does.** {@link registerReloader} enrols your store in the pass Studio runs
+ *    after a restore, a thaw, or entering a version view. Skipping it is not a cosmetic staleness
+ *    bug: your pre-restore memory is still in RAM, and the author's next edit writes it back over the
+ *    version they just restored.
+ */
+export type PluginWorkspaceService = {
+	/** Whether project data may be written right now. Read at call time; never cached. */
+	readonly frozen: boolean;
+	/** Why, or `null` when the project is writable. */
+	readonly freezeReason: PluginFreezeReason | null;
+	/** Fires on every change, with the new state. */
+	onFreezeChange(listener: (frozen: boolean, reason: PluginFreezeReason | null) => void): PluginCleanup;
+	/**
+	 * Re-read everything this plugin holds in memory, because the project's documents have been
+	 * replaced.
+	 *
+	 * Called with project writes held off and the new version already installed at the read
+	 * boundary, so a plain `storage.readJson` inside it returns the right bytes. Read before you drop
+	 * what you have: throwing must leave the plugin with its old data rather than with half of a
+	 * document. Register once per store, at `setup`.
+	 */
+	registerReloader(reload: () => Promise<void> | void): PluginCleanup;
+};
 export type PluginAssetsService = {
 	getMap(): AssetsMap;
 	list<T extends AssetType>(type: T): Asset<T, AssetSource>[];
@@ -11125,6 +11531,8 @@ export type PluginServices = {
 	storage: PluginStorageService;
 	assets: PluginAssetsService;
 	i18n: PluginI18n;
+	/** The state of the project your data lives in; see {@link PluginWorkspaceService}. */
+	workspace: PluginWorkspaceService;
 	/** Extend Studio's built-in text editor; see {@link PluginTextEditorService}. */
 	textEditor: PluginTextEditorService;
 	ui: {

package/dist/plugin.d.ts

@@ -35,6 +35,8 @@ export {
 	ContextMenuProps,
 	ContextMenuSeparatorDef,
 	definePlugin,
+	FreezeGuard,
+	FrozenControlProps,
 	InputSize,
 	InputVariant,
 	isPluginDefinition,
@@ -48,6 +50,7 @@ export {
 	PluginBlueprintNodeDef,
 	PluginCleanup,
 	PluginDefinition,
+	PluginFreezeReason,
 	PluginI18n,
 	PluginIdentity,
 	PluginInstallPermission,
@@ -82,6 +85,7 @@ export {
 	PluginTranslator,
 	PluginUiKit,
 	PluginVoiceUnitEntry,
+	PluginWorkspaceService,
 	ProgressProps,
 	ProgressSize,
 	ProgressVariant,

package/package.json

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