narraleaf-studio 1.5.0 → 1.6.0

package/dist/_api.d.ts

@@ -1048,9 +1048,10 @@ type StoryActionPayload = {
 	/** The plugin's story-action id, itself namespaced by `pluginId`. */
 	actionId: string;
 	/**
-	 * What the author filled in on the row, for the owning pass to interpret. Studio never
-	 * reads inside it - the keys are the plugin's vocabulary - so it is only constrained to be
-	 * JSON, which is what makes the row survive a round trip through the project file.
+	 * What the author filled in on the row, for the owning plugin to interpret. Studio never
+	 * interprets it - the keys are the plugin's vocabulary - and writes a key only through a
+	 * field the plugin's action declares (`params` on its registration). It is only constrained
+	 * to be JSON, which is what makes the row survive a round trip through the project file.
 	 */
 	params: Record<string, StoryPluginActionParamValue>;
 }
@@ -2014,6 +2015,22 @@ declare const en: {
 			readonly right: "right";
 			readonly overview: "Overview";
 		};
+		readonly keys: {
+			readonly arrowUp: "Arrow Up";
+			readonly arrowDown: "Arrow Down";
+			readonly arrowLeft: "Arrow Left";
+			readonly arrowRight: "Arrow Right";
+			readonly space: "Space";
+			readonly plus: "Plus";
+			readonly dpadUp: "D-pad Up";
+			readonly dpadDown: "D-pad Down";
+			readonly dpadLeft: "D-pad Left";
+			readonly dpadRight: "D-pad Right";
+			readonly leftStickUp: "Left Stick Up";
+			readonly leftStickDown: "Left Stick Down";
+			readonly leftStickLeft: "Left Stick Left";
+			readonly leftStickRight: "Left Stick Right";
+		};
 	};
 	readonly menu: {
 		readonly app: {
@@ -2166,7 +2183,7 @@ declare const en: {
 			};
 			readonly developerMode: {
 				readonly label: "Developer options";
-				readonly description: "Right-click menus gain a section for copying the ID of the item clicked.";
+				readonly description: "Right-click menus gain a section for copying the ID of the item clicked, and the blueprint add-node menu shows each node's type ID.";
 			};
 			readonly screenEffectThreads: {
 				readonly label: "Threads for screen effects";
@@ -2598,11 +2615,13 @@ declare const en: {
 		readonly data: {
 			readonly projectTrust: {
 				readonly loading: "Reading\u2026";
-				readonly empty: "Every project opened so far was created by Studio.";
+				readonly empty: "No projects.";
 				readonly waiting: "Waiting for a decision";
 				readonly granted: "Trusted";
 				readonly trust: "Trust";
-				readonly remove: "Remove";
+				readonly revoke: "Revoke";
+				readonly delete: "Remove from list";
+				readonly deleteCovered: "Inside a trusted project and cannot be removed";
 				readonly reloadNote: "A project that is open reloads when its trust changes.";
 				readonly origin: {
 					readonly package: "From a package";
@@ -3587,10 +3606,6 @@ declare const en: {
 			readonly noActiveEditor: "No active editor";
 			readonly closePanel: "Close panel";
 			readonly closeTab: "Close {name}";
-			readonly newTab: "New tab";
-			readonly newTabPage: {
-				readonly title: "New Tab";
-			};
 			readonly tabMenu: {
 				readonly keepOpen: "Keep open";
 				readonly close: "Close";
@@ -6558,6 +6573,9 @@ declare const en: {
 			readonly storyActionTitle: "Story Action";
 			readonly name: "Blueprint name";
 		};
+		readonly plugin: {
+			readonly missingOption: "{value} (missing)";
+		};
 		readonly audio: {
 			readonly track: "Track";
 			readonly trackDefault: "Default ({name})";
@@ -7811,6 +7829,31 @@ declare const en: {
 			readonly unbound: "Unbound";
 			readonly clear: "Clear binding";
 		};
+		readonly family: {
+			readonly compare: "Compare";
+			readonly key: "On Key";
+			readonly gamepadButton: "On Gamepad Button";
+			readonly getPreference: "Get Preference";
+			readonly setPreference: "Set Preference";
+			readonly trim: "Trim Whitespace";
+			readonly changeCase: "Change Case";
+			readonly pad: "Pad Text";
+			readonly replace: "Replace Text";
+			readonly checkType: "Check Type";
+			readonly convert: "Convert Type";
+			readonly rounding: "Rounding";
+			readonly random: "Random Number";
+			readonly literal: "Literal";
+			readonly saveInfo: "Get Save Info";
+			readonly getTextStyle: "Get Text Style";
+			readonly setTextStyle: "Set Text Style";
+			readonly getImageFraming: "Get Image Framing";
+			readonly setImageFraming: "Set Image Framing";
+			readonly getVisibleEnabled: "Get Visible or Enabled";
+			readonly setVisibleEnabled: "Set Visible or Enabled";
+			readonly rowSubtitle: "{category} \u00B7 {count} nodes";
+			readonly switchLabel: "Switch to another node of this kind";
+		};
 		readonly element: {
 			readonly select: "Select element";
 			readonly selectNamed: "Select element {name}";
@@ -8922,8 +8965,8 @@ declare const en: {
 		readonly nodeDescription: {
 			readonly getComponentParam: "The value this placement sets for the chosen parameter, or the parameter's default when it sets none. A Text parameter that reads from a translation key gives the key's name; Translation Key Text gives its words.";
 			readonly getPageParam: "The value the page was opened with for the chosen param, or the param's default when it was given none. Params are declared in the page's properties.";
-			readonly compareEqual: "True when A and B are the same value of the same type. The number 1 and the text \"1\" are not equal.";
-			readonly compareNotEqual: "True when A and B differ in value or in type. The number 1 and the text \"1\" count as different.";
+			readonly compareEqual: "True when A and B are the same value of the same type. Lists and objects are compared by their contents, an element by which element it is. The number 1 and the text \"1\" are not equal; an input left unconnected counts as Null.";
+			readonly compareNotEqual: "True when A and B differ in value or in type, judged as Equal judges them. The number 1 and the text \"1\" count as different.";
 			readonly compareGreaterThan: "True when A is greater than B. Both sides are compared as numbers; a side that cannot be read as a number gives false.";
 			readonly compareGreaterThanOrEqual: "True when A is greater than or equal to B. Both sides are compared as numbers; a side that cannot be read as a number gives false.";
 			readonly compareLessThan: "True when A is less than B. Both sides are compared as numbers; a side that cannot be read as a number gives false.";
@@ -15013,6 +15056,14 @@ declare const en: {
 				readonly title: "Actions in blueprints";
 				readonly body: string;
 			};
+			readonly focusNavigation: {
+				readonly title: "Focus navigation";
+				readonly body: string;
+			};
+			readonly focusNavigationSettings: {
+				readonly title: "Navigation settings";
+				readonly body: string;
+			};
 			readonly uiSurfaces: {
 				readonly title: "Game screens";
 				readonly body: string;
@@ -19721,6 +19772,84 @@ type PropertyFieldBindingMeta = {
 	/** Current literal from the document when creating a binding (persisted as fallback). */
 	readLiteral: (data: UIInspectorData) => string | number | boolean | null;
 };
+declare const HELP_TOPIC_IDS: readonly [
+	"gettingHelp",
+	"workspaceLayout",
+	"newProject",
+	"runModes",
+	"keyboard",
+	"search",
+	"undo",
+	"studioSettings",
+	"storyScene",
+	"storyCommands",
+	"storyVariables",
+	"storyExpressions",
+	"storyFlow",
+	"storyScript",
+	"storyPaste",
+	"sceneSnapshot",
+	"storyMotion",
+	"dictionary",
+	"dictionaryMarks",
+	"assets",
+	"assetSources",
+	"assetSets",
+	"assetSetAxes",
+	"mediaConversion",
+	"characters",
+	"appearances",
+	"puppetRuntimes",
+	"audio",
+	"audioClips",
+	"videoClips",
+	"voice",
+	"localization",
+	"brand",
+	"uiSurfaces",
+	"inputActions",
+	"inputActionBindings",
+	"inputActionAnswering",
+	"inputActionsInBlueprints",
+	"focusNavigation",
+	"focusNavigationSettings",
+	"uiComponents",
+	"blueprints",
+	"scripts",
+	"uiBindings",
+	"networkNodes",
+	"spellcheck",
+	"lint",
+	"tests",
+	"dashboard",
+	"recovery",
+	"versionControl",
+	"versionChanges",
+	"versionViewing",
+	"versionRestore",
+	"versionConflicts",
+	"versionServer",
+	"freeze",
+	"build",
+	"saveLocation",
+	"olderSaves",
+	"saveSameStory",
+	"saveStoryChanged",
+	"patches",
+	"buildVariant",
+	"appTags",
+	"variantContent",
+	"icons",
+	"signing",
+	"assetProtection",
+	"networkAllowlist",
+	"assetCompression",
+	"screenEffects",
+	"plugins"
+];
+type StaticHelpTopicId = (typeof HELP_TOPIC_IDS)[number];
+type LintRuleHelpTopicId = `lintRule.${string}`;
+type HelpTopicId = StaticHelpTopicId | LintRuleHelpTopicId;
 type FieldType = "text" | "textarea" | "number" | "toggle" | "select" | "tags" | "custom" | "info" | "thumbnail" | "section" | "colorPicker" | "colorPickerGroup" | "iconButtonGroup" | "dropdownGroup" | "menuTrigger" | "inputGroup" | "inlineRow" | "imageFill" | "fontAsset";
 interface BaseFieldDefinition<TData = any> {
 	/** Unique identifier for the field */
@@ -19988,6 +20117,13 @@ interface SectionFieldDefinition<TData = any> extends BaseFieldDefinition<TData>
 	collapsible?: boolean;
 	/** Whether the section is collapsed by default */
 	defaultCollapsed?: boolean;
+	/**
+	 * The help topic about the whole section: `F1` anywhere inside it, and a `?` in its header.
+	 *
+	 * For a section whose effect cannot be read off its own fields, under the rule in
+	 * `docs/help-system.md` §5. A section that explains itself through its fields' tips passes none.
+	 */
+	helpTopic?: HelpTopicId;
 }
 interface CustomFieldProps<TData = any> {
 	data: TData;
@@ -20959,6 +21095,17 @@ export type StoryPluginActionCreateInput = {
 	generateId: () => string;
 	initialText?: string;
 };
+/**
+ * One field the scene inspector shows on a row of a plugin story action, editing `params[key]`.
+ *
+ * The descriptor a plugin node's `inspectorParams` already takes, narrowed to the kinds a row's params
+ * can hold: a pick (static `options`, or a `dynamicOptionsSource` registered through
+ * `app.services.blueprintNodes`), a string, or a number. A plugin that offers the same choice on a
+ * node and on a row passes both the same object, so both list the same options.
+ */
+export type StoryPluginActionParamDef = Pick<BlueprintInspectorParamDef, "key" | "label" | "options" | "dynamicOptionsSource" | "emptyOptionLabel"> & {
+	kind: "select" | "string" | "number";
+};
 export type StoryPluginActionRegistration = {
 	id: string;
 	label: string;
@@ -20971,83 +21118,23 @@ export type StoryPluginActionRegistration = {
 	 * editor, so an action whose params change what the row does says what they are here.
 	 */
 	describe?: (params: Record<string, unknown>) => string | null | undefined;
+	/**
+	 * Words a typed command finds this action by in every interface language, as a built-in command
+	 * answers to its own word: with `keywords: ["unlock"]`, `/unlock ACH_WIN` commits this action with
+	 * "ACH_WIN" as its initial text. Without them a typed command has to start the label or the id.
+	 * Single words; a built-in command's word stays the built-in's.
+	 */
+	keywords?: readonly string[];
+	/**
+	 * The fields the scene inspector shows when one of this action's `{action:"plugin"}` rows is
+	 * selected, each editing one key of the row's `params`. Without them a row keeps whatever
+	 * `createBlock` wrote, and changing it means inserting the row again.
+	 *
+	 * A field of a kind this Studio does not know is left out of the inspector, so a plugin written
+	 * for a later Studio still registers here.
+	 */
+	params?: readonly StoryPluginActionParamDef[];
 };
-declare const HELP_TOPIC_IDS: readonly [
-	"gettingHelp",
-	"workspaceLayout",
-	"newProject",
-	"runModes",
-	"keyboard",
-	"search",
-	"undo",
-	"studioSettings",
-	"storyScene",
-	"storyCommands",
-	"storyVariables",
-	"storyExpressions",
-	"storyFlow",
-	"storyScript",
-	"storyPaste",
-	"sceneSnapshot",
-	"storyMotion",
-	"dictionary",
-	"dictionaryMarks",
-	"assets",
-	"assetSources",
-	"assetSets",
-	"assetSetAxes",
-	"mediaConversion",
-	"characters",
-	"appearances",
-	"puppetRuntimes",
-	"audio",
-	"audioClips",
-	"videoClips",
-	"voice",
-	"localization",
-	"brand",
-	"uiSurfaces",
-	"inputActions",
-	"inputActionBindings",
-	"inputActionAnswering",
-	"inputActionsInBlueprints",
-	"uiComponents",
-	"blueprints",
-	"scripts",
-	"uiBindings",
-	"networkNodes",
-	"spellcheck",
-	"lint",
-	"tests",
-	"dashboard",
-	"recovery",
-	"versionControl",
-	"versionChanges",
-	"versionViewing",
-	"versionRestore",
-	"versionConflicts",
-	"versionServer",
-	"freeze",
-	"build",
-	"saveLocation",
-	"olderSaves",
-	"saveSameStory",
-	"saveStoryChanged",
-	"patches",
-	"buildVariant",
-	"appTags",
-	"variantContent",
-	"icons",
-	"signing",
-	"assetProtection",
-	"networkAllowlist",
-	"assetCompression",
-	"screenEffects",
-	"plugins"
-];
-type StaticHelpTopicId = (typeof HELP_TOPIC_IDS)[number];
-type LintRuleHelpTopicId = `lintRule.${string}`;
-type HelpTopicId = StaticHelpTopicId | LintRuleHelpTopicId;
 interface PanelComponentProps<TPayload = any> {
 	panelId: string;
 	payload?: TPayload;
@@ -23468,11 +23555,14 @@ export type PluginServices = {
 		listScenes(storyId: string): Promise<PluginSceneEntry[]>;
 		actions: {
 			/**
-			 * Register a scene-editor palette action (shown under the Plugin
-			 * category) that creates story blocks. The blocks it returns are
-			 * standard story blocks - the document does not depend on the
-			 * plugin after creation. Action ids must be prefixed with the
+			 * Register a scene-editor palette action (shown under Tools)
+			 * that creates story blocks. Action ids must be prefixed with the
 			 * plugin id.
+			 *
+			 * A standard story block owes the plugin nothing once inserted. A
+			 * `{action:"plugin"}` row is the plugin's own: the runtime entry's
+			 * `app.game.storyActions` runs it, and the fields in `params` are
+			 * what the scene inspector lets the author change on it.
 			 */
 			register(registration: StoryPluginActionRegistration): PluginCleanup;
 			registerMany(registrations: StoryPluginActionRegistration[]): PluginCleanup;

package/dist/plugin.d.ts

@@ -127,6 +127,7 @@ export {
 	StoryBlockId,
 	StoryBlockKind,
 	StoryPluginActionCreateInput,
+	StoryPluginActionParamDef,
 	StoryPluginActionRegistration,
 	SwitchProps,
 	SwitchSize,

package/package.json

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