narraleaf-studio 1.7.0 → 1.9.0

package/dist/_api.d.ts

@@ -12,7 +12,7 @@
 
 import { LucideIcon } from 'lucide-react';
 import React$1 from 'react';
-import { ComponentType, InputHTMLAttributes, ReactElement, ReactNode, RefObject } from 'react';
+import { CSSProperties, ComponentType, InputHTMLAttributes, ReactElement, ReactNode, RefObject } from 'react';
 
 declare enum FsRejectErrorCode {
 	NOT_FOUND = "NOT_FOUND",
@@ -1320,6 +1320,13 @@ type StoryTextMarks = {
 	 */
 	fontSizeStep?: number;
 	emphasis?: StoryTextEmphasis;
+	/** An inline effect a plugin contributes, such as shaking text. */
+	effect?: StoryTextEffect;
+};
+type StoryTextEffectParamValue = number | string | boolean;
+type StoryTextEffect = {
+	id: string;
+	params?: Record<string, StoryTextEffectParamValue>;
 };
 type StoryInterpolationRef = {
 	kind: "variable";
@@ -2357,6 +2364,10 @@ declare const en: {
 					readonly all: "Show all characters";
 				};
 			};
+			readonly groupSubmenus: {
+				readonly label: "Show groups as submenus";
+				readonly description: "In candidate menus, each character group and asset folder is one entry whose contents open in a column beside it.";
+			};
 			readonly dictionaries: {
 				readonly label: "Spelling dictionaries";
 			};
@@ -3494,6 +3505,7 @@ declare const en: {
 				readonly character_layered_set: "Lay out a layered character";
 				readonly character_layers_import: "Build a layered character from files";
 				readonly character_preview: "Preview a character look";
+				readonly character_avatars_autoframe: "Auto-frame dialog avatars";
 				readonly variables_list: "List variables";
 				readonly variable_upsert: "Create or update a variable";
 				readonly variable_delete: "Delete a variable";
@@ -4539,6 +4551,9 @@ declare const en: {
 			};
 			readonly sceneActions: "Scene actions";
 			readonly chapterActions: "Chapter actions";
+			readonly outlineView: "Outline display";
+			readonly showCastAvatars: "Show Cast Avatars";
+			readonly castLabel: "Cast: {names}";
 			readonly setEntryScene: "Set as Entry Scene";
 			readonly documentUnavailable: "Story document unavailable.";
 			readonly newStoryPlaceholder: "Enter story name";
@@ -4719,6 +4734,7 @@ declare const en: {
 				readonly badTag: "This line carries a formatting tag that is unknown, or left open.";
 				readonly badExpression: "This expression does not resolve.";
 				readonly layerDeclaration: "A script cannot declare a layer. Add it to the scene's layers";
+				readonly retiredLead: "Options no longer read \"show if\" or \"enable if\". Write \"hide if\" or \"disable if\" followed by the condition under which the option is hidden or greyed out";
 			};
 			readonly view: {
 				readonly open: "Read as a script";
@@ -5028,6 +5044,11 @@ declare const en: {
 			readonly speedUnit: "cps";
 			readonly speedPlaceholder: "Line";
 		};
+		readonly textEffect: {
+			readonly effect: "Effect";
+			readonly none: "None";
+			readonly unavailable: "{id} (not installed)";
+		};
 		readonly ruby: {
 			readonly title: "Ruby text";
 			readonly placeholder: "Reading";
@@ -5065,6 +5086,8 @@ declare const en: {
 			readonly rubyHint: "Ruby text (select the words to annotate)";
 			readonly type: "Type";
 			readonly typeHint: "Type (select the words to set)";
+			readonly effects: "Effects";
+			readonly effectsHint: "Effects (select the words to set)";
 			readonly tools: "Rich text tools";
 			readonly pauseClick: "Pause (waits for a click)";
 			readonly pauseSeconds: "Pause {seconds}s";
@@ -9206,6 +9229,20 @@ declare const en: {
 			readonly createCharacter: "create character {name}";
 			readonly editCharacter: "edit character {name}";
 			readonly deleteGroup: "delete group {name}";
+			readonly autoFrameAvatars: "auto-frame dialog avatars of {name}";
+		};
+		readonly autoFrame: {
+			readonly all: "Auto-frame all dialog avatars";
+			readonly one: "Auto-frame avatar";
+			readonly running: "Auto-framing dialog avatars";
+			readonly consoleChannel: "Avatars";
+			readonly consoleChannelDescription: "Dialog avatars framed on a detected head";
+			readonly started: "Detecting heads to frame dialog avatars";
+			readonly summary: "Framed {framed} \u00B7 No head found {noHead} \u00B7 Kept existing framing {kept}";
+			readonly noHeadLine: "{name}: no head found in {looks}";
+			readonly nothingToDo: "No dialog avatars to frame";
+			readonly noHead: "No head found";
+			readonly failed: "Auto-framing failed: {message}";
 		};
 		readonly create: {
 			readonly nameRequired: "Give the character a name.";
@@ -9470,7 +9507,7 @@ declare const en: {
 			readonly resetView: "Reset View";
 			readonly alt: "Variant preview";
 			readonly setPortrait: "Portrait framing";
-			readonly resetPortrait: "Frame automatically";
+			readonly resetPortrait: "Clear framing";
 			readonly portraitTitle: "Portrait framing";
 			readonly portraitScoped: "Frame this look only";
 		};
@@ -11829,7 +11866,7 @@ declare const en: {
 			readonly imageWebpQualityTitle: "WebP quality";
 			readonly imageWebpQualityDescription: "Quality passed to the WebP encoder, from 1 to 100.";
 			readonly imageMaxDimensionTitle: "Maximum image size";
-			readonly imageMaxDimensionDescription: "Images longer than this on their longest edge are scaled down. 0 keeps every image at the size it was saved.";
+			readonly imageMaxDimensionDescription: "Backgrounds and interface images longer than this on their longest edge are scaled down. Character sprites and other images drawn at their own pixel size keep their size. 0 keeps every image at the size it was saved.";
 			readonly audioModeTitle: "Audio compression settings";
 			readonly audioBitrateKbpsTitle: "Audio bitrate";
 			readonly audioBitrateKbpsDescription: "AAC bitrate, in kbit/s.";
@@ -11962,6 +11999,10 @@ declare const en: {
 					readonly one: "{count} action";
 					readonly other: "{count} actions";
 				};
+				readonly inlineTextEffect: {
+					readonly one: "{count} text effect";
+					readonly other: "{count} text effects";
+				};
 			};
 		};
 		readonly live: {
@@ -12293,6 +12334,12 @@ declare const en: {
 				readonly name: "Empty";
 				readonly description: "Project structure only";
 			};
+			readonly parts: {
+				readonly label: "Sample content";
+				readonly helper: "Unticked parts are left out of the new project. The screens always come in.";
+				readonly all: "All";
+				readonly none: "No sample content";
+			};
 		};
 		readonly project: {
 			readonly name: "Project Name";
@@ -13361,6 +13408,8 @@ declare const en: {
 			readonly compressionImages: "Images compressed";
 			readonly compressionMedia: "Audio and video compressed";
 			readonly compressionMetadata: "Metadata removed";
+			readonly compressionKeptAtSize: "Kept at full size";
+			readonly compressionKeptAtSizeHint: "Drawn at their own pixels";
 			readonly includedTitle: "Assets carried";
 			readonly includedEmpty: "This run carried no assets.";
 			readonly excludedTitle: "Assets left out";
@@ -14076,6 +14125,12 @@ declare const en: {
 				readonly message: "This line has no text";
 				readonly help: string;
 			};
+			readonly textUnknownEffect: {
+				readonly title: "Text effect not installed";
+				readonly description: "A line uses a text effect that no installed plugin provides";
+				readonly message: "The text effect {effect} is not provided by any installed plugin";
+				readonly help: string;
+			};
 			readonly localizationMissing: {
 				readonly title: "Missing translation";
 				readonly description: "A line or interface text with no translation in a target language";
@@ -16198,6 +16253,15 @@ export type PluginContributes = {
 	blueprintNodes?: string[];
 	/** Widget element types this plugin provides (editor module + runtime renderer). */
 	widgets?: string[];
+	/**
+	 * Inline text effects this plugin provides (rich text toolbar entry + runtime word renderer).
+	 *
+	 * An effect is set on a run of dialogue the way bold is, and the run compiles to the engine word
+	 * renderer of the same id. The studio entry registers the toolbar entry through
+	 * `app.services.richText.registerInlineEffect`; the runtime entry registers the renderer through
+	 * `app.game.wordRenderers.register`. Both refuse an id this list does not name.
+	 */
+	inlineTextEffects?: string[];
 	/** Studio language packs: locales this plugin adds or fills. */
 	locales?: PluginLocaleContribution[];
 	/**
@@ -22055,6 +22119,47 @@ export type RuntimeWidgetRendererDef = {
 	 */
 	logicApi?: WidgetLogicApi;
 };
+/**
+ * What an inline text effect draws one word of dialogue with. The engine hands these over each time
+ * the word renders: once per character while the line is being typed, and again when it settles.
+ */
+export type RuntimeInlineTextEffectRenderProps = {
+	/**
+	 * The word as the engine lays it out, with its reading (ruby), vertical writing and upright short
+	 * runs applied, and the characters still being revealed fading in. Draw this to keep all of that;
+	 * draw `text` instead only to place each character yourself.
+	 */
+	children: React$1.ReactNode;
+	/** The characters revealed so far. Equal to `fullText` once the typewriter has passed the word. */
+	text: string;
+	/** The whole word, revealed or not. */
+	fullText: string;
+	/** Whether every character of the word has been revealed. */
+	revealed: boolean;
+	/** Whether the whole line has finished revealing. */
+	done: boolean;
+	/** The word's resolved style, already applied to the element around it. */
+	style: Readonly<React$1.CSSProperties>;
+	/** Whether the word carries a reading, which `children` draws and `text` does not. */
+	hasRuby: boolean;
+	/** The parameter values the author set on the run. A parameter left at its default is absent. */
+	params: Readonly<Record<string, number | string | boolean>>;
+};
+/**
+ * Runtime-side inline text effect: the component that draws a run of dialogue the author set the
+ * effect on. The studio entry registers the toolbar entry under the same id.
+ */
+export type RuntimeInlineTextEffectDef = {
+	/** The effect id; must start with the plugin id and be declared in `contributes.inlineTextEffects`. */
+	id: string;
+	render: (props: RuntimeInlineTextEffectRenderProps) => React$1.ReactElement | null;
+	/**
+	 * Whether the word takes the player's clicks once it is revealed, instead of letting them advance
+	 * the line. Off by default: an effect that only changes how the text looks must not make part of
+	 * the dialogue box stop responding.
+	 */
+	interactive?: boolean;
+};
 /** Removes a subscription. Also tracked by the host, so a failed plugin cannot leak listeners. */
 export type RuntimePluginCleanup = () => void;
 /**
@@ -22416,6 +22521,17 @@ export type RuntimePluginGame = {
 		register(def: RuntimeWidgetRendererDef): void;
 		registerMany(defs: RuntimeWidgetRendererDef[]): void;
 	};
+	/**
+	 * Draw the runs of dialogue the author set one of this plugin's inline text effects on. A run
+	 * whose effect has no renderer here is drawn as plain text.
+	 *
+	 * Always present, like `widgets`: a renderer only draws text the author marked with this
+	 * plugin's own effect, so it grants nothing an install prompt would have to name.
+	 */
+	inlineTextEffects: {
+		register(def: RuntimeInlineTextEffectDef): void;
+		registerMany(defs: RuntimeInlineTextEffectDef[]): void;
+	};
 	/**
 	 * What runs when the story reaches a row one of this plugin's story actions inserted. The id is
 	 * the one the studio entry registered the action under; the story waits on the row until `run`
@@ -22733,6 +22849,38 @@ export interface AssetSelectorProps {
 	onClose: () => void;
 	onConfirm: (assets: Asset[]) => void;
 }
+/**
+ * One number an inline text effect lets the author set, drawn as a slider in the effect panel.
+ *
+ * Numbers only: a run's parameters are written into the document and into scripts as `key=value`,
+ * and a slider with a range is the one control every effect so far has needed.
+ */
+export type PluginInlineTextEffectParamDef = {
+	/** Unique within the effect. Keys the stored value; never displayed. */
+	key: string;
+	/** Author-facing name of the parameter, in the interface language. Read like the effect's. */
+	label: string;
+	min: number;
+	max: number;
+	/** The slider's increment. Defaults to a hundredth of the range. */
+	step?: number;
+	/** The value a run takes when the author has not moved the slider. Not stored. */
+	default: number;
+};
+/**
+ * An inline text effect's entry in the dialogue toolbar. The id is the one the runtime entry
+ * registers the renderer under, and the one the run stores.
+ */
+export type PluginInlineTextEffectDef = {
+	/** Must start with the plugin id and be declared in `contributes.inlineTextEffects`. */
+	id: string;
+	/**
+	 * Author-facing name, in the interface language. Read each time the panel draws, so a getter
+	 * over the plugin's translator follows a language switch without registering again.
+	 */
+	label: string;
+	params?: readonly PluginInlineTextEffectParamDef[];
+};
 type ControlSize = "sm" | "md" | "lg";
 export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
 export type ButtonSize = ControlSize;
@@ -23808,6 +23956,17 @@ export type PluginServices = {
 		list(): PluginWidgetTypeInfo[];
 		has(type: string): boolean;
 	};
+	/**
+	 * Contribute an inline text effect to the dialogue toolbar; see {@link PluginInlineTextEffectDef}.
+	 *
+	 * The author selects text in a line of dialogue and picks the effect, the way they pick bold. The
+	 * runtime entry draws the result through `app.game.inlineTextEffects` under the same id. The
+	 * toolbar shows its effects control only while at least one effect is registered.
+	 */
+	inlineTextEffects: {
+		register(def: PluginInlineTextEffectDef): PluginCleanup;
+		registerMany(defs: PluginInlineTextEffectDef[]): PluginCleanup;
+	};
 	story: {
 		/**
 		 * Read-only project catalogue, for a plugin panel that has to let the

package/dist/plugin.d.ts

@@ -63,6 +63,8 @@ export {
 	PluginFreezeReason,
 	PluginI18n,
 	PluginIdentity,
+	PluginInlineTextEffectDef,
+	PluginInlineTextEffectParamDef,
 	PluginInstallPermission,
 	PluginInstallRecord,
 	PluginInterfaceService,

package/dist/runtime.d.ts

@@ -18,6 +18,8 @@ export {
 	RuntimeBlueprintNodeExecute,
 	RuntimeBlueprintNodeResult,
 	RuntimeFlag,
+	RuntimeInlineTextEffectDef,
+	RuntimeInlineTextEffectRenderProps,
 	RuntimePluginApp,
 	RuntimePluginAssets,
 	RuntimePluginCleanup,

package/package.json

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