@blastlauncher/client-core 3.0.0-alpha.1 → 3.0.0-alpha.3

package/dist/controller.d.ts

@@ -1,7 +1,8 @@
 import type { SceneMessage } from "@blastlauncher/protocol";
 import { type OutboundEvent } from "./nodes.js";
-import { type FormInput, type FormFieldView } from "./form-view.js";
-export type { FormFieldView } from "./form-view.js";
+import { type IconAppearance, type IconMask, type IconSource } from "./icons.js";
+import { type FormInput, type FormFieldView, type FormItemView } from "./form-view.js";
+export type { FormFieldView, FormItemView } from "./form-view.js";
 import { type KeyInput, type Platform } from "./shortcut.js";
 export type ControllerInput = FormInput | {
     type: "search";
@@ -70,6 +71,8 @@ export type RowView = {
     selected: boolean;
     iconLabel: string;
     iconTint?: string;
+    iconSource?: IconSource;
+    iconMask?: IconMask;
     /** The row as one line, for clients that do not lay columns out. */
     text: string;
 };
@@ -79,6 +82,9 @@ export type GridCellView = {
     subtitle: string;
     /** The cell content as short text: image source name or color. */
     content: string;
+    /** Set when the content is an image: what to draw for it. */
+    iconSource?: IconSource;
+    iconMask?: IconMask;
     selected: boolean;
 };
 export type GridRowView = {
@@ -105,6 +111,10 @@ export type MenuRowView = {
     kind: "item" | "submenu" | "section";
     title: string;
     subtitle: string;
+    iconLabel: string;
+    iconTint?: string;
+    iconSource?: IconSource;
+    iconMask?: IconMask;
     shortcut: string;
     disabled: boolean;
     selected: boolean;
@@ -129,6 +139,8 @@ export type ControllerView = {
         description: string;
         iconLabel: string;
         iconTint?: string;
+        iconSource?: IconSource;
+        iconMask?: IconMask;
     } | null;
     detail: string;
     primary: {
@@ -192,6 +204,7 @@ export type ControllerView = {
         selectedId: string | null;
     } | null;
     form: {
+        items: FormItemView[];
         fields: FormFieldView[];
         focusId: string | null;
     } | null;
@@ -215,5 +228,11 @@ export type ControllerOptions = {
     hudDurationMs?: number;
     /** Overrides how long success and failure toasts stay visible. */
     toastDurationMs?: number;
+    /** Shown when the scene has no navigation title, typically the command title. */
+    fallbackTitle?: string;
+    /** Which light/dark variant of icon sources and tints the view carries. Default: "light". */
+    appearance?: IconAppearance;
+    /** Absolute directory that relative icon image names resolve under (the extension's `assets/`). */
+    assetsDir?: string;
 };
 export declare function createController(options: ControllerOptions): Controller;

package/dist/controller.js

@@ -1,14 +1,14 @@
-import { event, handler, selectionId, text } from "./nodes.js";
+import { event, handler, handlerEvent, selectionId, text } from "./nodes.js";
 import { activeNode, actionRows, defaultActionShortcut, panelRows, sceneToView } from "./view.js";
-import { contentGlyph, gridMove } from "./grid.js";
-import { iconView } from "./icons.js";
+import { contentGlyph, contentIcon, gridMove } from "./grid.js";
+import { iconFields, iconView, } from "./icons.js";
 import { dropdownLabel, dropdownOptions, visibleOptions } from "./dropdown.js";
-import { createFormController } from "./form-view.js";
+import { createFormController, } from "./form-view.js";
 import { loadMoreRequest } from "./pagination.js";
 import { searchDispatch } from "./search.js";
 import { feedbackState, TOAST_DURATION_MS } from "./feedback.js";
 import { HUD_DURATION_MS } from "./hud.js";
-import { menuBarStep, menuBarView } from "./menu-bar.js";
+import { menuBarStep, menuBarView, menuShortcut } from "./menu-bar.js";
 import { matchesShortcut, shortcutLabel } from "./shortcut.js";
 const fresh = () => ({ events: [], effects: [] });
 const send = (out, value) => {
@@ -20,6 +20,10 @@ const clamp = (value, length) => Math.max(0, Math.min(length - 1, value));
 const runName = (node) => handler(node?.props.onAction) ? "onAction" : "onSubmit";
 export function createController(options) {
     const { platform } = options;
+    const icons = {
+        appearance: options.appearance ?? "light",
+        ...(options.assetsDir === undefined ? {} : { assetsDir: options.assetsDir }),
+    };
     let current;
     const form = createFormController();
     let searchText = "";
@@ -72,7 +76,12 @@ export function createController(options) {
         deferred.set(key, { token, event: value.event });
         out.effects.push({ type: "schedule", ms: value.delayMs, token });
     };
-    const base = () => sceneToView(current, { searchText, selectedId });
+    const base = () => sceneToView(current, {
+        searchText,
+        selectedId,
+        ...(options.fallbackTitle ? { fallbackTitle: options.fallbackTitle } : {}),
+        icons,
+    });
     const isMenu = (view) => view.list?.type === "MenuBarExtra";
     const panelNodeOf = (view) => {
         let node = view.actions;
@@ -327,9 +336,25 @@ export function createController(options) {
     }
     function shortcutKey(out, view, press) {
         const feedback = feedbackState(current);
-        if (mode(view, !!feedback.alert) !== "base")
+        const level = mode(view, !!feedback.alert);
+        if (level === "menu") {
+            // A menu item's key equivalent works while its menu is open, as in a
+            // native menu, from any submenu level.
+            const item = menuShortcut(view.list, press, platform);
+            if (!item)
+                return;
+            out.handled = true;
+            const value = handlerEvent(item, item.props.onAction, [{ type: "left-click" }]);
+            if (value)
+                send(out, value);
+            return;
+        }
+        // Raycast runs an action's shortcut with its action panel open too, and
+        // closes the panel; alerts and dropdowns keep every key to themselves.
+        if (level !== "base" && level !== "panel")
             return;
-        const toast = toastVisible &&
+        const toast = level === "base" &&
+            toastVisible &&
             feedback.toast?.actions.find((action) => matchesShortcut(action.shortcut, press, platform));
         if (toast) {
             out.handled = true;
@@ -347,6 +372,9 @@ export function createController(options) {
         if (!shortcut)
             return;
         out.handled = true;
+        panel = null;
+        panelQuery = "";
+        panelIndex = 0;
         if (shortcut.node.type === "ActionPanel.Submenu") {
             send(out, event(shortcut.node, "onOpen"));
             openPanel([shortcut.node.id]);
@@ -482,7 +510,7 @@ export function createController(options) {
                 accessories: row.accessories ?? "",
                 icon: row.icon === true,
                 iconLabel: row.iconView?.label ?? "",
-                ...(row.iconView?.tint ? { iconTint: row.iconView.tint } : {}),
+                ...iconFields(row.iconView),
                 count: row.count ?? null,
                 selected: item && row.node.id === list.selected?.id,
                 text: row.text,
@@ -490,7 +518,7 @@ export function createController(options) {
         };
         const actions = panelState(list);
         const dropdown = dropdownState(list);
-        const bar = menuBarView(current, { path: menuPath, selectedId }, platform);
+        const bar = menuBarView(current, { path: menuPath, selectedId }, platform, icons);
         const primaryNode = list.primary;
         let breadcrumb = [];
         if (panel?.length) {
@@ -504,7 +532,7 @@ export function createController(options) {
         const alert = feedback.alert;
         const dismiss = alert?.dismiss;
         const confirm = alert?.primary;
-        const emptyIcon = list.empty?.props.icon ? iconView(list.empty.props.icon) : undefined;
+        const emptyIcon = list.empty?.props.icon ? iconView(list.empty.props.icon, icons) : undefined;
         return {
             kind,
             title: list.title,
@@ -519,13 +547,18 @@ export function createController(options) {
                 ? list.grid.rows.map((row) => ({
                     id: row.node ? row.node.id : null,
                     header: row.header,
-                    cells: row.cells.map((cell) => ({
-                        id: selectionId(cell) ?? cell.id,
-                        title: text(cell.props.title),
-                        subtitle: text(cell.props.subtitle),
-                        content: contentGlyph(cell),
-                        selected: cell.id === list.selected?.id,
-                    })),
+                    cells: row.cells.map((cell) => {
+                        const image = contentIcon(cell, icons);
+                        return {
+                            id: selectionId(cell) ?? cell.id,
+                            title: text(cell.props.title),
+                            subtitle: text(cell.props.subtitle),
+                            content: contentGlyph(cell),
+                            ...(image?.source ? { iconSource: image.source } : {}),
+                            ...(image?.mask ? { iconMask: image.mask } : {}),
+                            selected: cell.id === list.selected?.id,
+                        };
+                    }),
                 }))
                 : null,
             selectedId: selected,
@@ -535,7 +568,7 @@ export function createController(options) {
                     title: text(list.empty.props.title),
                     description: text(list.empty.props.description),
                     iconLabel: emptyIcon?.label ?? "",
-                    ...(emptyIcon?.tint ? { iconTint: emptyIcon.tint } : {}),
+                    ...iconFields(emptyIcon),
                 }
                 : null,
             detail: list.detail,
@@ -611,6 +644,10 @@ export function createController(options) {
                         kind: !row.item ? "section" : row.isSubmenu ? "submenu" : "item",
                         title: row.title ?? "",
                         subtitle: row.subtitle ?? "",
+                        iconLabel: row.iconLabel ?? "",
+                        ...(row.iconTint ? { iconTint: row.iconTint } : {}),
+                        ...(row.iconSource ? { iconSource: row.iconSource } : {}),
+                        ...(row.iconMask ? { iconMask: row.iconMask } : {}),
                         shortcut: row.shortcut ?? "",
                         disabled: row.disabled,
                         selected: row.item && row.node.id === bar.selected?.node.id,

package/dist/form-view.d.ts

@@ -38,6 +38,7 @@ export type FormFieldView = {
     id: string;
     type: string;
     title: string;
+    required: boolean;
     info: string;
     label: string;
     placeholder: string;
@@ -58,6 +59,18 @@ export type FormFieldView = {
     query: string;
     focused: boolean;
 };
+export type FormItemView = {
+    kind: "field";
+    id: string;
+} | {
+    kind: "separator";
+    id: string;
+} | {
+    kind: "description";
+    id: string;
+    title: string;
+    text: string;
+};
 /** Form-only client state. Password contents never enter this state or its view. */
 export declare function createFormController(): {
     active: (next: boolean, events: OutboundEvent[]) => void;
@@ -67,6 +80,7 @@ export declare function createFormController(): {
     }>, events: OutboundEvent[]): void;
     view(): {
         focusId: string | null;
+        items: FormItemView[];
         fields: FormFieldView[];
     };
 };

package/dist/form-view.js

@@ -200,6 +200,22 @@ export function createFormController() {
         view() {
             return {
                 focusId,
+                items: (form?.children ?? []).flatMap((node) => {
+                    if (editable.has(node.type))
+                        return [{ kind: "field", id: node.id }];
+                    if (node.type === "Form.Separator")
+                        return [{ kind: "separator", id: node.id }];
+                    if (node.type === "Form.Description")
+                        return [
+                            {
+                                kind: "description",
+                                id: node.id,
+                                title: text(node.props.title),
+                                text: text(node.props.text),
+                            },
+                        ];
+                    return [];
+                }),
                 fields: fields.map((field) => {
                     const password = field.type === "Form.PasswordField";
                     const value = password ? null : valueOf(field);
@@ -209,7 +225,8 @@ export function createFormController() {
                         id: field.id,
                         type: field.type,
                         title: text(field.props.title ?? field.props.id),
-                        info: text(field.props.info),
+                        required: field.props.required === true,
+                        info: focusId === field.id ? text(field.props.info) : "",
                         label: text(field.props.label),
                         placeholder: text(field.props.placeholder),
                         error: draft?.error || text(field.props.error),

package/dist/grid.d.ts

@@ -1,4 +1,5 @@
 import type { SceneNode } from "@blastlauncher/protocol";
+import { type IconOptions, type IconView } from "./icons.js";
 import { type FilteringOptions } from "./rank.js";
 export type GridRow = {
     node: SceneNode | undefined;
@@ -12,6 +13,8 @@ export type GridLayout = {
 export type GridDirection = "up" | "down" | "left" | "right";
 /** The content of a cell as short text: the image source name or a color. */
 export declare function contentGlyph(node: SceneNode): string;
+/** The drawable image of a cell, when its content is an image rather than a color. */
+export declare function contentIcon(node: SceneNode, icons: IconOptions): IconView | undefined;
 /**
  * Lay a Grid scene node out into selectable cells, one row per `columns`.
  * Items are filtered and ranked for `query` per the grid's `filtering`.

package/dist/grid.js

@@ -1,4 +1,5 @@
 import { selectionId, text } from "./nodes.js";
+import { iconView } from "./icons.js";
 import { filteringOf, groupsOf, rankGroups, score, searchable, } from "./rank.js";
 function columnsOf(node, fallback) {
     const value = node.props.columns;
@@ -18,6 +19,18 @@ export function contentGlyph(node) {
     }
     return "◇";
 }
+/** The drawable image of a cell, when its content is an image rather than a color. */
+export function contentIcon(node, icons) {
+    const content = node.props.content;
+    const value = content && typeof content === "object" && !Array.isArray(content) && "value" in content
+        ? content.value
+        : content;
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "object" && !Array.isArray(value) && "color" in value)
+        return undefined;
+    return iconView(value, icons);
+}
 /**
  * Lay a Grid scene node out into selectable cells, one row per `columns`.
  * Items are filtered and ranked for `query` per the grid's `filtering`.

package/dist/icons.d.ts

@@ -1,13 +1,45 @@
 import type { JsonValue } from "@blastlauncher/protocol";
+/** What a graphical client draws for an icon; `label` stays the text fallback. */
+export type IconSource = {
+    kind: "builtin";
+    name: string;
+} | {
+    kind: "url";
+    url: string;
+} | {
+    kind: "file";
+    path: string;
+} | {
+    kind: "fileIcon";
+    path: string;
+};
+export type IconMask = "circle" | "roundedRectangle";
+export type IconAppearance = "light" | "dark";
+export type IconOptions = {
+    /** Picks the light or dark variant of sources and tints. Default: "light". */
+    appearance?: IconAppearance;
+    /** Absolute directory that relative image names (`icon.png`) resolve under. */
+    assetsDir?: string;
+};
 /**
- * A compact terminal stand-in for a Raycast icon. `tint` is a Raycast colour
- * name (`red`, `raycast-blue`, `secondary-text`) or a raw CSS colour; turning
- * it into a palette entry is the client's job, so this module stays free of
- * framework and palette imports.
+ * An icon as a client draws it. `label` is a compact terminal stand-in; `tint`
+ * is a Raycast colour name (`red`, `raycast-blue`, `secondary-text`) or a raw
+ * CSS colour, and turning it into a palette entry is the client's job, so this
+ * module stays free of framework and palette imports. `source` and `mask` tell
+ * a graphical client what to draw: the variant for the requested appearance,
+ * with relative asset names already absolute.
  */
 export type IconView = {
     label: string;
     tint?: string;
+    source?: IconSource;
+    mask?: IconMask;
+};
+/** The optional icon fields every view row carries, flattened under `icon*` names. */
+export declare function iconFields(icon: IconView | undefined): {
+    iconTint?: string;
+    iconSource?: IconSource;
+    iconMask?: IconMask;
 };
-/** Convert a Raycast image/icon value to a compact terminal representation. */
-export declare function iconView(value: JsonValue | undefined): IconView;
+/** Convert a Raycast image/icon value to a terminal label plus a drawable source. */
+export declare function iconView(value: JsonValue | undefined, options?: IconOptions): IconView;

package/dist/icons.js

@@ -1,3 +1,11 @@
+/** The optional icon fields every view row carries, flattened under `icon*` names. */
+export function iconFields(icon) {
+    return {
+        ...(icon?.tint ? { iconTint: icon.tint } : {}),
+        ...(icon?.source ? { iconSource: icon.source } : {}),
+        ...(icon?.mask ? { iconMask: icon.mask } : {}),
+    };
+}
 // Keyed by the icon name without Raycast's `-16` size suffix, lowercase and
 // with separators removed (`Icon.ArrowDown` -> "arrowdown"). Aliases share a
 // glyph where Raycast has several names for the same picture.
@@ -332,48 +340,67 @@ const tintRoles = {
     red: "red",
     yellow: "yellow",
 };
-function tintOf(value) {
+function tintOf(value, appearance) {
     if (typeof value === "string")
         return tintRoles[value.toLowerCase()] ?? value;
     if (value && typeof value === "object" && !Array.isArray(value)) {
-        // A DynamicColor picks the dark variant: the reference client is dark.
         const dynamic = value;
-        return tintOf(dynamic.dark ?? dynamic.light);
+        return tintOf(appearance === "dark" ? (dynamic.dark ?? dynamic.light) : (dynamic.light ?? dynamic.dark), appearance);
     }
     return undefined;
 }
-function sourceOf(value) {
+function parse(value, appearance) {
     if (typeof value === "string")
         return { source: value, ...(looksLikeImage(value) ? { image: true } : {}) };
     if (!value || typeof value !== "object" || Array.isArray(value))
         return {};
     const icon = value;
     if (typeof icon.fileIcon === "string")
-        return { source: icon.fileIcon, image: true };
-    const tint = tintOf(icon.tintColor);
-    const source = icon.source;
-    if (typeof source === "string")
-        return {
-            source,
-            ...(tint ? { tint } : {}),
-            ...(looksLikeImage(source) ? { image: true } : {}),
-        };
+        return { fileIcon: icon.fileIcon, image: true };
+    const tint = tintOf(icon.tintColor, appearance);
+    const mask = icon.mask === "circle" || icon.mask === "roundedRectangle" ? icon.mask : undefined;
+    let source = icon.source;
     if (source && typeof source === "object" && !Array.isArray(source)) {
         const dynamic = source;
-        const selected = dynamic.dark ?? dynamic.light;
-        if (typeof selected === "string")
-            return {
-                source: selected,
-                ...(tint ? { tint } : {}),
-                ...(looksLikeImage(selected) ? { image: true } : {}),
-            };
+        source =
+            appearance === "dark" ? (dynamic.dark ?? dynamic.light) : (dynamic.light ?? dynamic.dark);
     }
-    return tint ? { tint } : {};
+    return {
+        ...(typeof source === "string"
+            ? { source, ...(looksLikeImage(source) ? { image: true } : {}) }
+            : {}),
+        ...(tint ? { tint } : {}),
+        ...(mask ? { mask } : {}),
+    };
 }
 function looksLikeImage(source) {
     return (/^(https?:|data:|file:|\/)/i.test(source) ||
         /\.(png|jpe?g|gif|svg|webp|bmp|heic)$/i.test(source));
 }
+/** Where a string icon points; undefined when a relative asset has no directory to resolve under. */
+function sourceOf(source, assetsDir) {
+    if (/^(https?:|data:)/i.test(source))
+        return { kind: "url", url: source };
+    if (/^file:/i.test(source)) {
+        try {
+            return { kind: "file", path: decodeURIComponent(new URL(source).pathname) };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (source.startsWith("/") || /^[a-z]:[\\/]/i.test(source))
+        return { kind: "file", path: source };
+    if (!looksLikeImage(source))
+        return { kind: "builtin", name: source };
+    // An extension must not reach outside its own assets directory.
+    if (!assetsDir || source.split(/[\\/]/).includes(".."))
+        return undefined;
+    return {
+        kind: "file",
+        path: `${assetsDir.replace(/[\\/]+$/, "")}/${source.replace(/^\.?[\\/]/, "")}`,
+    };
+}
 /** `globe-01-16` -> "globe": drop the file extension, `16` size and `01` index suffixes. */
 function iconName(source) {
     const base = (source.split(/[\\/]/).at(-1) ?? source).replace(/\.[a-z0-9]{1,5}$/i, "");
@@ -397,13 +424,23 @@ function fallbackLabel(source) {
     const label = titleCase(words);
     return label.length <= 12 ? label : `${titleCase(words.slice(0, 9))}…`;
 }
-/** Convert a Raycast image/icon value to a compact terminal representation. */
-export function iconView(value) {
-    const { source, tint, image } = sourceOf(value);
+/** Convert a Raycast image/icon value to a terminal label plus a drawable source. */
+export function iconView(value, options = {}) {
+    const { source, fileIcon, tint, mask, image } = parse(value, options.appearance ?? "light");
+    const drawable = fileIcon !== undefined
+        ? { kind: "fileIcon", path: fileIcon }
+        : source === undefined
+            ? undefined
+            : sourceOf(source, options.assetsDir);
+    const extras = {
+        ...(tint ? { tint } : {}),
+        ...(drawable ? { source: drawable } : {}),
+        ...(mask ? { mask } : {}),
+    };
     if (!source)
-        return { label: "◇", ...(tint ? { tint } : {}) };
+        return { label: fileIcon === undefined ? "◇" : "▣", ...extras };
     const name = iconName(source);
     const glyph = glyphs[name] ?? glyphs[name.replace(/(?:filled|disabled|small|large)$/, "")] ?? undefined;
     const label = glyph ?? (image ? "▣" : fallbackLabel(source));
-    return { label, ...(tint ? { tint } : {}) };
+    return { label, ...extras };
 }

package/dist/index.d.ts

@@ -12,3 +12,5 @@ export * from "./feedback.js";
 export * from "./menu-bar.js";
 export * from "./icons.js";
 export * from "./controller.js";
+export * from "./root.js";
+export * from "./prompt.js";

package/dist/index.js

@@ -15,3 +15,5 @@ export * from "./feedback.js";
 export * from "./menu-bar.js";
 export * from "./icons.js";
 export * from "./controller.js";
+export * from "./root.js";
+export * from "./prompt.js";

package/dist/menu-bar.d.ts

@@ -1,6 +1,7 @@
 import type { SceneMessage, SceneNode } from "@blastlauncher/protocol";
 import { type OutboundEvent } from "./nodes.js";
-import { type Platform } from "./shortcut.js";
+import { type KeyInput, type Platform } from "./shortcut.js";
+import { type IconMask, type IconOptions, type IconSource } from "./icons.js";
 export type MenuRow = {
     node: SceneNode;
     text: string;
@@ -8,6 +9,10 @@ export type MenuRow = {
     disabled: boolean;
     title?: string;
     subtitle?: string;
+    iconLabel?: string;
+    iconTint?: string;
+    iconSource?: IconSource;
+    iconMask?: IconMask;
     shortcut?: string;
     isSubmenu?: boolean;
 };
@@ -32,9 +37,9 @@ export type MenuBarView = {
     tooltip: string;
 };
 /** The rows of the menu level addressed by `path` (ids of open Submenus). */
-export declare function menuRows(menu: SceneNode | undefined, path: string[], platform?: Platform): MenuRow[];
+export declare function menuRows(menu: SceneNode | undefined, path: string[], platform?: Platform, icons?: IconOptions): MenuRow[];
 /** The menu of the active view as rows, selection and loading state. */
-export declare function menuBarView(scene: SceneMessage | undefined, state?: MenuBarState, platform?: Platform): MenuBarView;
+export declare function menuBarView(scene: SceneMessage | undefined, state?: MenuBarState, platform?: Platform, icons?: IconOptions): MenuBarView;
 export type MenuBarAction = {
     type: "move";
     delta: 1 | -1;
@@ -57,3 +62,5 @@ export type MenuBarStep = {
 };
 /** The menu-bar navigation reducer. Pure: the client sends `events` itself. */
 export declare function menuBarStep(scene: SceneMessage | undefined, state: MenuBarState, action: MenuBarAction, platform?: Platform): MenuBarStep;
+/** The enabled item anywhere in `menu` whose shortcut is `press`, if any. */
+export declare function menuShortcut(menu: SceneNode | undefined, press: KeyInput, platform?: Platform): SceneNode | undefined;

package/dist/menu-bar.js

@@ -1,9 +1,10 @@
 import { handler, handlerEvent, event, selectionId, text } from "./nodes.js";
-import { shortcutLabel } from "./shortcut.js";
+import { matchesShortcut, shortcutLabel } from "./shortcut.js";
 import { activeNode } from "./view.js";
+import { iconFields, iconView } from "./icons.js";
 export const MENU_BAR_START = { path: [], selectedId: null };
 /** The rows of the menu level addressed by `path` (ids of open Submenus). */
-export function menuRows(menu, path, platform = "Linux") {
+export function menuRows(menu, path, platform = "Linux", icons = {}) {
     if (menu?.type !== "MenuBarExtra")
         return [];
     let level = menu;
@@ -30,12 +31,14 @@ export function menuRows(menu, path, platform = "Linux") {
             const title = text(node.props.title);
             const subtitle = text(node.props.subtitle);
             const shortcut = shortcutLabel(node.props.shortcut, platform);
+            const icon = node.props.icon === undefined ? undefined : iconView(node.props.icon, icons);
             rows.push({
                 node,
                 item: true,
                 disabled: !handler(node.props.onAction),
                 title,
                 subtitle,
+                ...(icon ? { iconLabel: icon.label, ...iconFields(icon) } : {}),
                 shortcut,
                 text: [title, subtitle, shortcut].filter(Boolean).join("  "),
             });
@@ -66,10 +69,10 @@ export function menuRows(menu, path, platform = "Linux") {
     return rows;
 }
 /** The menu of the active view as rows, selection and loading state. */
-export function menuBarView(scene, state = MENU_BAR_START, platform = "Linux") {
+export function menuBarView(scene, state = MENU_BAR_START, platform = "Linux", icons = {}) {
     const active = activeNode(scene?.root);
     const menu = active?.type === "MenuBarExtra" ? active : undefined;
-    const rows = menuRows(menu, state.path, platform);
+    const rows = menuRows(menu, state.path, platform, icons);
     const items = rows.filter((row) => row.item);
     return {
         menu,
@@ -115,3 +118,17 @@ export function menuBarStep(scene, state, action, platform = "Linux") {
         };
     return same;
 }
+/** The enabled item anywhere in `menu` whose shortcut is `press`, if any. */
+export function menuShortcut(menu, press, platform = "Linux") {
+    if (menu?.type !== "MenuBarExtra")
+        return;
+    const queue = [...menu.children];
+    for (let node = queue.shift(); node; node = queue.shift()) {
+        if (node.type === "MenuBarExtra.Item" &&
+            handler(node.props.onAction) &&
+            matchesShortcut(node.props.shortcut, press, platform))
+            return node;
+        queue.push(...node.children);
+    }
+    return;
+}

package/dist/prompt.d.ts

@@ -0,0 +1,64 @@
+import { type ControllerInput, type ControllerOptions } from "./controller.js";
+import type { ControllerView } from "./controller.js";
+export type PromptValue = string | number | boolean;
+export type PromptValues = Record<string, PromptValue>;
+/** One input of the form. `key` identifies it in `values`, view field ids and effects. */
+export type PromptField = {
+    key: string;
+    /** A preference or argument type: `textfield`, `password`, `checkbox`, `dropdown`, `file`, `directory`, `appPicker`. */
+    type: string;
+    title: string;
+    description?: string;
+    placeholder?: string;
+    /** A checkbox's label next to the box. */
+    label?: string;
+    required: boolean;
+    data?: {
+        title: string;
+        value: string;
+    }[];
+};
+export type PromptForm = {
+    title: string;
+    /** Primary action title, e.g. "Save & Launch". */
+    submit: string;
+    description?: string;
+    sections: {
+        title: string;
+        fields: PromptField[];
+    }[];
+    /** Starting values by field key; missing ones start empty (checkbox off, dropdown on its first option). */
+    values: PromptValues;
+};
+export type PromptStatus = {
+    title: string;
+    toast: {
+        style: "animated" | "success" | "failure";
+        title: string;
+        message: string;
+        /** Adds a Retry action to the toast and the primary action. */
+        retry?: boolean;
+    };
+};
+export type PromptEffect = {
+    type: "submit";
+    values: PromptValues;
+} | {
+    type: "retry";
+} | {
+    type: "cancel";
+};
+export type PromptResult = {
+    effects: PromptEffect[];
+};
+export type PromptController = {
+    /** Replace the view with a form; the next `submit` effect carries its values. */
+    form(form: PromptForm): void;
+    /** Replace the view with a status screen: a toast over an empty detail. */
+    status(status: PromptStatus): void;
+    /** Any controller input; anything outside the prompt's own inputs is ignored. */
+    input(input: ControllerInput): PromptResult;
+    view(): ControllerView;
+    subscribe(listener: (view: ControllerView) => void): () => void;
+};
+export declare function createPromptController(options: ControllerOptions): PromptController;

package/dist/prompt.js

@@ -0,0 +1,184 @@
+import { createController } from "./controller.js";
+const node = (type, id, props = {}, children = []) => ({ type, id, props, children });
+const handler = (name) => ({ $handler: name });
+const actions = (...children) => node("Slot", "slot-actions", { name: "actions" }, [node("ActionPanel", "panel", {}, children)]);
+const SET = "set:";
+const empty = (value) => value === undefined || value === "";
+/** The value a field starts with, so a form never shows a dropdown with nothing chosen. */
+function initial(field, values) {
+    const value = values[field.key];
+    if (value !== undefined)
+        return value;
+    if (field.type === "checkbox")
+        return false;
+    if (field.type === "dropdown")
+        return field.data?.[0]?.value ?? "";
+    return "";
+}
+function fieldNode(field, value, error) {
+    const common = {
+        id: field.key,
+        title: field.title,
+        required: field.required,
+        ...(field.description ? { info: field.description } : {}),
+        ...(error ? { error } : {}),
+        onChange: handler(`${SET}${field.key}`),
+    };
+    switch (field.type) {
+        case "checkbox":
+            return node("Form.Checkbox", field.key, {
+                ...common,
+                label: field.label ?? field.title,
+                value: value === true,
+            });
+        case "dropdown":
+            return node("Form.Dropdown", field.key, { ...common, value: String(value) }, (field.data ?? []).map((option) => node("Form.Dropdown.Item", `${field.key}:${option.value}`, option)));
+        case "password":
+            return node("Form.PasswordField", field.key, {
+                ...common,
+                value: String(value),
+                hasValue: value !== "",
+                ...(field.placeholder ? { placeholder: field.placeholder } : {}),
+            });
+        case "file":
+        case "directory":
+            return node("Form.FilePicker", field.key, {
+                ...common,
+                value: value === "" ? [] : [String(value)],
+                allowMultipleSelection: false,
+                canChooseFiles: field.type === "file",
+                canChooseDirectories: field.type === "directory",
+            });
+        default:
+            return node("Form.TextField", field.key, {
+                ...common,
+                value: String(value),
+                ...(field.placeholder ? { placeholder: field.placeholder } : {}),
+            });
+    }
+}
+export function createPromptController(options) {
+    const controller = createController(options);
+    let revision = 0;
+    let current;
+    let values = {};
+    let errors = new Map();
+    let status;
+    const show = (list, ...feedback) => {
+        const message = {
+            type: "scene",
+            revision: ++revision,
+            root: node("Navigation", "prompt", { pop: handler("cancel") }, [
+                node("Navigation.Entry", "entry", { active: true }, [list]),
+                ...feedback,
+            ]),
+        };
+        controller.scene(message);
+    };
+    const render = () => {
+        if (current) {
+            const form = current;
+            const children = [];
+            if (form.description)
+                children.push(node("Form.Description", "description", { text: form.description }));
+            form.sections.forEach((section, index) => {
+                if (index > 0 || form.description)
+                    children.push(node("Form.Separator", `rule:${index}`));
+                if (section.title)
+                    children.push(node("Form.Description", `section:${index}`, { text: section.title }));
+                for (const field of section.fields)
+                    children.push(fieldNode(field, initial(field, values), errors.get(field.key) ?? ""));
+            });
+            children.push(actions(node("Action.SubmitForm", "submit", { title: form.submit, onSubmit: handler("submit") })));
+            show(node("Form", "prompt-form", { navigationTitle: form.title }, children));
+        }
+        else if (status) {
+            const toast = status.toast;
+            show(node("Detail", "prompt-status", {
+                navigationTitle: status.title,
+                markdown: "",
+                isLoading: toast.style === "animated",
+            }, toast.retry
+                ? [actions(node("Action", "retry", { title: "Retry", onAction: handler("retry") }))]
+                : []), node("Toast", "toast", { style: toast.style.toUpperCase(), title: toast.title, message: toast.message }, toast.retry
+                ? [
+                    node("Toast.Action", "toast-retry", {
+                        name: "primaryAction",
+                        title: "Retry",
+                        shortcut: { modifiers: [], key: "r" },
+                        onAction: handler("retry"),
+                    }),
+                ]
+                : []));
+        }
+    };
+    const submit = () => {
+        if (!current)
+            return [];
+        errors = new Map();
+        const all = current.sections.flatMap((section) => section.fields);
+        for (const field of all)
+            if (field.required && empty(initial(field, values)))
+                errors.set(field.key, "Required");
+        if (errors.size)
+            return [];
+        return [
+            {
+                type: "submit",
+                values: Object.fromEntries(all.map((field) => [field.key, initial(field, values)])),
+            },
+        ];
+    };
+    return {
+        form(form) {
+            current = form;
+            status = undefined;
+            values = { ...form.values };
+            errors = new Map();
+            render();
+        },
+        status(next) {
+            current = undefined;
+            status = next;
+            render();
+        },
+        input(input) {
+            const effects = [];
+            const result = controller.input(input);
+            // The controller asks to close on `back`; the prompt cancels instead.
+            if (result.effects.some((effect) => effect.type === "quit"))
+                effects.push({ type: "cancel" });
+            let changed = false;
+            for (const { handler: name, args } of result.events) {
+                if (name === "cancel")
+                    effects.push({ type: "cancel" });
+                else if (name === "retry")
+                    effects.push({ type: "retry" });
+                else if (name === "submit") {
+                    effects.push(...submit());
+                    changed = true;
+                }
+                else if (name.startsWith(SET)) {
+                    const key = name.slice(SET.length);
+                    const field = current?.sections.flatMap((s) => s.fields).find((f) => f.key === key);
+                    const value = args[0];
+                    if (!field)
+                        continue;
+                    if (Array.isArray(value))
+                        values[key] = typeof value[0] === "string" ? value[0] : "";
+                    else if (typeof value === "string" ||
+                        typeof value === "boolean" ||
+                        typeof value === "number")
+                        values[key] = value;
+                    errors.delete(key);
+                    changed = true;
+                }
+            }
+            if (changed)
+                render();
+            return { effects };
+        },
+        view: () => controller.view(),
+        subscribe: (listener) => controller.subscribe(listener),
+    };
+}

package/dist/root.d.ts

@@ -0,0 +1,40 @@
+import { type IconView } from "./icons.js";
+import type { ControllerInput, ControllerView } from "./controller.js";
+import { type Platform } from "./shortcut.js";
+/** A command exposed by an opened extension. `extension` is the grouping and launch key. */
+export type RootCommand = {
+    extension: string;
+    extensionTitle?: string;
+    command: string;
+    title: string;
+    subtitle?: string;
+    description?: string;
+    mode?: "view" | "no-view" | "menu-bar";
+    icon?: IconView;
+};
+/** `launch` runs the command; `configure` opens its preferences form without running it. */
+export type RootEffect = {
+    type: "launch" | "configure";
+    extension: string;
+    command: string;
+    scope?: "extension" | "command";
+};
+export type RootResult = {
+    effects: RootEffect[];
+};
+/** Any controller input is accepted; those with no meaning in the root list are ignored. */
+export type RootInput = ControllerInput;
+export type RootController = {
+    input(input: RootInput): RootResult;
+    /** Replace the catalog (an extension opened, closed or edited). Selection follows the command. */
+    setCatalog(commands: RootCommand[]): void;
+    /** Show a failure toast until the next input. */
+    fail(title: string, message: string): void;
+    /** Come back from a command: clears the search, selection and any toast. */
+    reset(): void;
+    view(): ControllerView;
+    subscribe(listener: (view: ControllerView) => void): () => void;
+};
+export declare function createRootController(initial?: RootCommand[], options?: {
+    platform?: Platform;
+}): RootController;

package/dist/root.js

@@ -0,0 +1,219 @@
+import { rankGroups, score } from "./rank.js";
+import { iconFields } from "./icons.js";
+import { matchesShortcut, shortcutLabel } from "./shortcut.js";
+const PLACEHOLDER = "Search commands…";
+const OPEN = "Open Command";
+const CONFIGURE = "Configure Command";
+const CONFIGURE_KEYS = { modifiers: ["cmd", "shift"], key: "," };
+const ACTIONS = [{ id: "open" }, { id: "configure" }];
+const MODE_LABELS = { view: "Command", "no-view": "No View", "menu-bar": "Menu Bar" };
+const commandId = (command) => `${command.extension}:${command.command}`;
+export function createRootController(initial = [], options = {}) {
+    const platform = options.platform ?? "Linux";
+    let catalog = initial;
+    let query = "";
+    let selectedId = null;
+    let actionsOpen = false;
+    let actionIndex = 0;
+    let failure = null;
+    const listeners = new Set();
+    // Sections are extensions in catalog order; a query orders items by score inside each.
+    const visible = () => {
+        const byExtension = new Map();
+        for (const command of catalog) {
+            const items = byExtension.get(command.extension);
+            if (items)
+                items.push(command);
+            else
+                byExtension.set(command.extension, [command]);
+        }
+        const groups = [...byExtension].map(([section, items]) => ({
+            section,
+            items,
+        }));
+        return rankGroups(groups, query, (c) => score({
+            title: c.title,
+            subtitle: c.subtitle || c.description || "",
+            keywords: [c.command, c.extension, c.extensionTitle ?? ""],
+        }, query), { enabled: true, keepSectionOrder: true }).flatMap((group) => group.items);
+    };
+    // The chosen command, falling back to the first when it disappeared (live catalog).
+    const chosen = (items) => items.find((c) => commandId(c) === selectedId) ?? items[0];
+    const view = () => {
+        const items = visible();
+        const current = chosen(items);
+        const rows = [];
+        let section;
+        for (const command of items) {
+            if (command.extension !== section) {
+                section = command.extension;
+                const title = command.extensionTitle ?? section;
+                rows.push({
+                    id: `section:${section}`,
+                    kind: "section",
+                    title,
+                    subtitle: "",
+                    accessories: "",
+                    icon: false,
+                    count: items.filter((c) => c.extension === section).length,
+                    selected: false,
+                    iconLabel: "",
+                    text: title,
+                });
+            }
+            const subtitle = command.subtitle || command.description || "";
+            rows.push({
+                id: commandId(command),
+                kind: "item",
+                title: command.title,
+                subtitle,
+                accessories: command.mode ? MODE_LABELS[command.mode] : "",
+                icon: !!command.icon,
+                count: null,
+                selected: command === current,
+                iconLabel: command.icon?.label ?? "",
+                ...iconFields(command.icon),
+                text: subtitle ? `${command.title}  ${subtitle}` : command.title,
+            });
+        }
+        return {
+            kind: "list",
+            title: "Commands",
+            navigation: { canGoBack: false },
+            loading: false,
+            search: { text: query, placeholder: PLACEHOLDER },
+            rows,
+            grid: null,
+            selectedId: current ? commandId(current) : null,
+            emptyText: query ? "No matching commands" : "No commands",
+            empty: null,
+            detail: "",
+            primary: { title: OPEN, shortcut: "", enabled: !!current },
+            actions: {
+                open: actionsOpen && !!current,
+                title: current?.title ?? "Actions",
+                query: "",
+                breadcrumb: [],
+                rows: actionsOpen && current
+                    ? [
+                        {
+                            id: "open",
+                            kind: "action",
+                            title: OPEN,
+                            shortcut: "",
+                            selected: actionIndex === 0,
+                        },
+                        {
+                            id: "configure",
+                            kind: "action",
+                            title: CONFIGURE,
+                            shortcut: shortcutLabel(CONFIGURE_KEYS, platform),
+                            selected: actionIndex === 1,
+                        },
+                    ]
+                    : [],
+                selectedIndex: actionsOpen && current ? actionIndex : -1,
+            },
+            dropdown: null,
+            feedback: {
+                toast: failure && { style: "failure", ...failure, actions: [] },
+                hud: null,
+                alert: null,
+            },
+            menuBar: null,
+            form: null,
+            requests: { quit: false, clearSearch: false },
+        };
+    };
+    const notify = () => {
+        const next = view();
+        for (const listener of listeners)
+            listener(next);
+    };
+    const run = (type) => {
+        const current = chosen(visible());
+        actionsOpen = false;
+        return {
+            effects: current
+                ? [
+                    {
+                        type,
+                        extension: current.extension,
+                        command: current.command,
+                    },
+                ]
+                : [],
+        };
+    };
+    return {
+        input(input) {
+            failure = null;
+            let result = { effects: [] };
+            switch (input.type) {
+                case "search":
+                    query = input.text;
+                    selectedId = null;
+                    actionsOpen = false;
+                    break;
+                case "move": {
+                    const items = visible();
+                    const step = input.direction === "down" ? 1 : input.direction === "up" ? -1 : 0;
+                    const current = chosen(items);
+                    if (actionsOpen) {
+                        actionIndex = Math.max(0, Math.min(ACTIONS.length - 1, actionIndex + step));
+                        break;
+                    }
+                    const next = items[(current ? items.indexOf(current) : 0) + step];
+                    if (next)
+                        selectedId = commandId(next);
+                    break;
+                }
+                case "select": {
+                    const picked = visible().find((c) => commandId(c) === input.id);
+                    if (picked)
+                        selectedId = commandId(picked);
+                    break;
+                }
+                case "primary":
+                    result = run(actionsOpen && ACTIONS[actionIndex]?.id === "configure" ? "configure" : "launch");
+                    break;
+                case "key":
+                    if (matchesShortcut(CONFIGURE_KEYS, input.key, platform))
+                        result = run("configure");
+                    break;
+                case "openActions":
+                    actionsOpen = true;
+                    actionIndex = 0;
+                    break;
+                case "closeActions":
+                case "back":
+                    actionsOpen = false;
+                    break;
+                default:
+                    break;
+            }
+            notify();
+            return result;
+        },
+        setCatalog(commands) {
+            catalog = commands;
+            notify();
+        },
+        fail(title, message) {
+            failure = { title, message };
+            notify();
+        },
+        reset() {
+            query = "";
+            actionsOpen = false;
+            failure = null;
+            notify();
+        },
+        view,
+        subscribe(listener) {
+            listeners.add(listener);
+            listener(view());
+            return () => listeners.delete(listener);
+        },
+    };
+}

package/dist/view.d.ts

@@ -1,13 +1,16 @@
 import type { SceneMessage, SceneNode } from "@blastlauncher/protocol";
 import { type FilteringOptions } from "./rank.js";
 import { type Platform } from "./shortcut.js";
-import { type IconView } from "./icons.js";
+import { type IconOptions, type IconView } from "./icons.js";
 /** Raycast's built-in shortcuts for actions without an explicit shortcut. */
 export declare function defaultActionShortcut(node: SceneNode, index: number): unknown;
 export { event, handler, handlerEvent, isFiltering, paginationOf, selectionId, slot, text, } from "./nodes.js";
 export type UIState = {
     searchText: string;
     selectedId: string | null;
+    /** Shown when the scene has no navigation title, typically the command title. */
+    fallbackTitle?: string;
+    icons?: IconOptions;
 };
 export type Row = {
     node: SceneNode;

package/dist/view.js

@@ -36,32 +36,40 @@ export function activeNode(node) {
         return activeNode(node.children[0]);
     return node ?? undefined;
 }
-function itemAccessories(node) {
+function itemAccessories(node, icons) {
     const accessories = node.props.accessories;
     const labels = Array.isArray(accessories)
         ? accessories.map((value) => {
             if (!value || typeof value !== "object" || Array.isArray(value))
                 return "";
-            return [text(value.text), text(value.tag), value.icon ? iconView(value.icon).label : ""]
+            return [
+                text(value.text),
+                text(value.tag),
+                value.icon ? iconView(value.icon, icons).label : "",
+            ]
                 .filter(Boolean)
                 .join(" ");
         })
         : [];
     return labels.filter(Boolean).join("  ");
 }
-function itemText(node) {
+function itemText(node, icons) {
     const accessories = node.props.accessories;
     const labels = Array.isArray(accessories)
         ? accessories.map((value) => {
             if (!value || typeof value !== "object" || Array.isArray(value))
                 return "";
-            return [text(value.text), text(value.tag), value.icon ? iconView(value.icon).label : ""]
+            return [
+                text(value.text),
+                text(value.tag),
+                value.icon ? iconView(value.icon, icons).label : "",
+            ]
                 .filter(Boolean)
                 .join(" ");
         })
         : [];
     return [
-        node.props.icon ? iconView(node.props.icon).label : "",
+        node.props.icon ? iconView(node.props.icon, icons).label : "",
         text(node.props.title),
         text(node.props.subtitle),
         ...labels,
@@ -69,16 +77,16 @@ function itemText(node) {
         .filter(Boolean)
         .join("  ");
 }
-function itemRow(node) {
+function itemRow(node, icons) {
     return {
         node,
-        text: itemText(node),
+        text: itemText(node, icons),
         item: true,
         title: text(node.props.title),
         subtitle: text(node.props.subtitle),
-        accessories: itemAccessories(node),
+        accessories: itemAccessories(node, icons),
         icon: Boolean(node.props.icon),
-        ...(node.props.icon ? { iconView: iconView(node.props.icon) } : {}),
+        ...(node.props.icon ? { iconView: iconView(node.props.icon, icons) } : {}),
     };
 }
 function sectionRow(node) {
@@ -103,6 +111,7 @@ export function sceneToView(scene, state) {
     const list = activeNode(scene?.root);
     const rows = [];
     const query = state.searchText;
+    const icons = state.icons ?? {};
     const filtering = filteringOf(list);
     const grid = list?.type === "Grid" ? gridLayout(list, query, filtering) : undefined;
     if (list?.type === "List") {
@@ -112,7 +121,7 @@ export function sceneToView(scene, state) {
             if (header)
                 rows.push(header);
             for (const node of group.items)
-                rows.push(itemRow(node));
+                rows.push(itemRow(node, icons));
             if (header)
                 header.count = group.items.length;
         }
@@ -132,7 +141,9 @@ export function sceneToView(scene, state) {
         grid,
         accessory: searchBarDropdown(list),
         navigation: scene?.root?.type === "Navigation" ? scene.root : undefined,
+        // An empty list shows its EmptyView, whose actions replace the list's, as in Raycast.
         actions: (selected ? slot(selected, "actions") : undefined) ??
+            (!selected && empty ? slot(empty, "actions") : undefined) ??
             (list ? slot(list, "actions") : undefined),
         detail: list?.type === "Detail"
             ? detailText(list)
@@ -147,11 +158,12 @@ export function sceneToView(scene, state) {
             (list?.type === "MenuBarExtra"
                 ? [text(list.props.title), text(list.props.tooltip)].filter(Boolean).join(" — ")
                 : "") ||
+            state.fallbackTitle ||
             "Blast",
         loading: list?.props.isLoading === true || !scene,
         emptyText: empty
             ? [
-                empty.props.icon ? iconView(empty.props.icon).label : "",
+                empty.props.icon ? iconView(empty.props.icon, icons).label : "",
                 text(empty.props.title),
                 text(empty.props.description),
             ]
@@ -159,6 +171,7 @@ export function sceneToView(scene, state) {
                 .join("  ")
             : "No results",
         primary: firstAction(selected ? slot(selected, "actions") : undefined) ??
+            firstAction(!selected && empty ? slot(empty, "actions") : undefined) ??
             firstAction(list ? slot(list, "actions") : undefined),
     };
 }

package/package.json

@@ -9,9 +9,9 @@
     }
   },
   "dependencies": {
-    "@blastlauncher/protocol": "3.0.0-alpha.1"
+    "@blastlauncher/protocol": "3.0.0-alpha.3"
   },
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.3",
   "license": "MIT",
   "repository": {
     "type": "git",