@blastlauncher/runtime 1.0.5 → 3.0.0-alpha.0

package/dist/api/list.d.ts

@@ -0,0 +1,291 @@
+import { type ReactNode } from "react";
+import type { ColorLike, ImageLike } from "./types.js";
+/** `List.Item.Accessory`: a text, date or tag label with optional icon/tooltip. */
+export interface ListAccessory {
+    /** An optional text label, optionally colored. */
+    text?: string | null | {
+        value: string | null | undefined;
+        color?: string;
+    };
+    /** An optional date label (rendered relative to now), optionally colored. */
+    date?: Date | null | {
+        value: Date | null | undefined;
+        color?: string;
+    };
+    /** A string or date tag; the color also tints the background. */
+    tag?: string | Date | null | {
+        value: string | Date | null | undefined;
+        color?: ColorLike;
+    };
+    /** An optional image shown in front of the label. */
+    icon?: ImageLike | null;
+    /** An optional tooltip shown when the accessory is hovered. */
+    tooltip?: string | null;
+}
+export interface ListProps {
+    /** List sections or items. */
+    children?: ReactNode;
+    /** The main title for that view displayed in the host. */
+    navigationTitle?: string;
+    /** Indicates whether a loading bar should be shown below the search bar. */
+    isLoading?: boolean;
+    /** The text that will be displayed in the search bar. */
+    searchText?: string;
+    /** Placeholder text of the search bar. */
+    searchBarPlaceholder?: string;
+    /** Whether the list should show details for the selected item. */
+    isShowingDetail?: boolean;
+    /** Selects the item with the specified id. */
+    selectedItemId?: string;
+    /** Deprecated alias of filtering. */
+    enableFiltering?: boolean;
+    /** Clients request subsequent pages through onLoadMore. */
+    pagination?: {
+        pageSize: number;
+        hasMore: boolean;
+        onLoadMore: () => void;
+    };
+    /**
+     * Toggles client-side filtering of the items through the search bar; the
+     * client decides how to honor it (see task 0020, "Out of scope").
+     */
+    filtering?: boolean | {
+        keepSectionOrder: boolean;
+    };
+    /**
+     * Defines whether the `onSearchTextChange` handler fires on every keystroke
+     * or with a throttling delay.
+     */
+    throttle?: boolean;
+    /** Callback triggered when the search bar text changes. */
+    onSearchTextChange?: (text: string) => void;
+    /** Callback triggered when the item selection in the list changes. */
+    onSelectionChange?: (id: string | null) => void;
+    /** An ActionPanel; rendered as a `Slot` child named `actions`. */
+    actions?: ReactNode;
+    /** A search bar accessory; rendered as a `Slot` child named `searchBarAccessory`. */
+    searchBarAccessory?: ReactNode;
+}
+export interface ListItemProps {
+    /** Passed to the `onSelectionChange` handler of the List when selected. */
+    id?: string;
+    /** The main title displayed for the item, optionally with a tooltip. */
+    title: string | {
+        value: string;
+        tooltip?: string | null;
+    };
+    /** An optional subtitle, optionally with a tooltip. */
+    subtitle?: string | {
+        value?: string | null;
+        tooltip?: string | null;
+    };
+    /** Additional indexable strings for search. */
+    keywords?: string[];
+    /** An optional icon displayed for the item. */
+    icon?: ImageLike | {
+        value: ImageLike | null | undefined;
+        tooltip: string;
+    };
+    /** Accessory items displayed on the right side of the item. */
+    accessories?: ListAccessory[] | null;
+    /** Deprecated single-accessory props, retained for clients. */
+    accessoryIcon?: ImageLike;
+    accessoryTitle?: string;
+    /** File metadata for client Quick Look previews. */
+    quickLook?: {
+        name?: string | null;
+        path: string;
+    };
+    /** An ActionPanel; rendered as a `Slot` child named `actions`. */
+    actions?: ReactNode;
+    /** A `List.Item.Detail`; rendered as a `Slot` child named `detail`. */
+    detail?: ReactNode;
+}
+export interface ListSectionProps {
+    /** Deprecated internal section identifier. */
+    id?: string;
+    /** The `List.Item` elements of the section. */
+    children?: ReactNode;
+    /** Title displayed above the section. */
+    title?: string;
+    /** An optional subtitle displayed next to the title of the section. */
+    subtitle?: string;
+}
+export interface ListEmptyViewProps {
+    /** The main title displayed for the empty view. */
+    title?: string;
+    /** An optional description for why the empty view is shown. */
+    description?: string;
+    /** An optional icon displayed in the center of the empty view. */
+    icon?: ImageLike | null;
+    /** An ActionPanel; rendered as a `Slot` child named `actions`. */
+    actions?: ReactNode;
+}
+export interface ListDropdownItemProps {
+    /** Value of the dropdown item; passed to `onChange` when selected. */
+    value: string;
+    /** The title displayed for the item. */
+    title: string;
+    /** An optional icon displayed for the item. */
+    icon?: ImageLike | null;
+    /** Additional indexable strings for search. */
+    keywords?: string[];
+}
+export interface ListDropdownSectionProps {
+    /** The `List.Dropdown.Item` elements of the section. */
+    children?: ReactNode;
+    /** Title displayed above the section. */
+    title?: string;
+}
+export interface ListDropdownProps {
+    /** The dropdown sections or items. */
+    children?: ReactNode;
+    /** ID of the dropdown. */
+    id?: string;
+    /** Tooltip displayed when hovering the dropdown. */
+    tooltip: string;
+    /** Placeholder text shown in the dropdown search field. */
+    placeholder?: string;
+    /**
+     * Persist the selected value per command and dropdown id across runs.
+     */
+    storeValue?: boolean;
+    /** The current value of the dropdown. */
+    value?: string;
+    /** The default value of the dropdown, configured once per component lifecycle. */
+    defaultValue?: string;
+    /** Toggles client-side filtering of the dropdown items. */
+    filtering?: boolean | {
+        keepSectionOrder: boolean;
+    };
+    /** Indicates whether a loading indicator should be shown next to the dropdown. */
+    isLoading?: boolean;
+    /** Defines whether `onSearchTextChange` fires on every keystroke or throttled. */
+    throttle?: boolean;
+    /** Callback triggered when the dropdown search field text changes. */
+    onSearchTextChange?: (text: string) => void;
+    /** Callback triggered when the dropdown selection changes. */
+    onChange?: (newValue: string) => void;
+}
+declare const ListDropdownItem: (props: ListDropdownItemProps) => import("react").ReactElement<ListDropdownItemProps, string | import("react").JSXElementConstructor<any>>;
+declare const ListDropdownSection: (props: ListDropdownSectionProps) => import("react").DOMElement<ListDropdownSectionProps, Element>;
+declare function ListSection(props: ListSectionProps): import("react").DOMElement<ListSectionProps, Element>;
+declare function ListEmptyView(props: ListEmptyViewProps): import("react").ReactElement<{
+    /** The main title displayed for the empty view. */
+    title?: string;
+    /** An optional description for why the empty view is shown. */
+    description?: string;
+    /** An optional icon displayed in the center of the empty view. */
+    icon?: ImageLike | null;
+}, string | import("react").JSXElementConstructor<any>>;
+export declare const List: ((props: ListProps) => import("react").ReactElement<{
+    /** The main title for that view displayed in the host. */
+    navigationTitle?: string;
+    /** Indicates whether a loading bar should be shown below the search bar. */
+    isLoading?: boolean;
+    /** The text that will be displayed in the search bar. */
+    searchText?: string;
+    /** Placeholder text of the search bar. */
+    searchBarPlaceholder?: string;
+    /** Whether the list should show details for the selected item. */
+    isShowingDetail?: boolean;
+    /** Selects the item with the specified id. */
+    selectedItemId?: string;
+    /** Deprecated alias of filtering. */
+    enableFiltering?: boolean;
+    /** Clients request subsequent pages through onLoadMore. */
+    pagination?: {
+        pageSize: number;
+        hasMore: boolean;
+        onLoadMore: () => void;
+    };
+    /**
+     * Toggles client-side filtering of the items through the search bar; the
+     * client decides how to honor it (see task 0020, "Out of scope").
+     */
+    filtering?: boolean | {
+        keepSectionOrder: boolean;
+    };
+    /**
+     * Defines whether the `onSearchTextChange` handler fires on every keystroke
+     * or with a throttling delay.
+     */
+    throttle?: boolean;
+    /** Callback triggered when the search bar text changes. */
+    onSearchTextChange?: (text: string) => void;
+    /** Callback triggered when the item selection in the list changes. */
+    onSelectionChange?: (id: string | null) => void;
+}, string | import("react").JSXElementConstructor<any>>) & {
+    Item: ((props: ListItemProps) => import("react").ReactElement<{
+        /** Passed to the `onSelectionChange` handler of the List when selected. */
+        id?: string;
+        /** The main title displayed for the item, optionally with a tooltip. */
+        title: string | {
+            value: string;
+            tooltip?: string | null;
+        };
+        /** An optional subtitle, optionally with a tooltip. */
+        subtitle?: string | {
+            value?: string | null;
+            tooltip?: string | null;
+        };
+        /** Additional indexable strings for search. */
+        keywords?: string[];
+        /** An optional icon displayed for the item. */
+        icon?: ImageLike | {
+            value: ImageLike | null | undefined;
+            tooltip: string;
+        };
+        /** Accessory items displayed on the right side of the item. */
+        accessories?: ListAccessory[] | null;
+        /** Deprecated single-accessory props, retained for clients. */
+        accessoryIcon?: ImageLike;
+        accessoryTitle?: string;
+        /** File metadata for client Quick Look previews. */
+        quickLook?: {
+            name?: string | null;
+            path: string;
+        };
+    }, string | import("react").JSXElementConstructor<any>>) & {
+        Detail: ((props: import("./detail.js").ListItemDetailProps) => import("react").ReactElement<{
+            isLoading?: boolean;
+            markdown?: string | null;
+        }, string | import("react").JSXElementConstructor<any>>) & {
+            Metadata: import("./metadata.js").MetadataComponents;
+        };
+    };
+    Section: typeof ListSection;
+    EmptyView: typeof ListEmptyView;
+    Dropdown: ((props: ListDropdownProps) => import("react").ReactElement<{
+        /** The dropdown sections or items. */
+        children?: ReactNode;
+        /** ID of the dropdown. */
+        id?: string;
+        /** Tooltip displayed when hovering the dropdown. */
+        tooltip: string;
+        /** Placeholder text shown in the dropdown search field. */
+        placeholder?: string;
+        /**
+         * Persist the selected value per command and dropdown id across runs.
+         */
+        storeValue?: boolean;
+        /** The default value of the dropdown, configured once per component lifecycle. */
+        defaultValue?: string;
+        /** Toggles client-side filtering of the dropdown items. */
+        filtering?: boolean | {
+            keepSectionOrder: boolean;
+        };
+        /** Indicates whether a loading indicator should be shown next to the dropdown. */
+        isLoading?: boolean;
+        /** Defines whether `onSearchTextChange` fires on every keystroke or throttled. */
+        throttle?: boolean;
+        /** Callback triggered when the dropdown search field text changes. */
+        onSearchTextChange?: (text: string) => void;
+        value: string | undefined;
+        onChange: ((value: string) => void | undefined) | undefined;
+    }, string | import("react").JSXElementConstructor<any>>) & {
+        Item: typeof ListDropdownItem;
+        Section: typeof ListDropdownSection;
+    };
+};
+export {};

package/dist/api/list.js

@@ -0,0 +1,28 @@
+import { createElement } from "react";
+import { useDropdown } from "./dropdown.js";
+import { ListItemDetail } from "./detail.js";
+import { slot } from "./slot.js";
+const ListDropdownItem = function ListDropdownItem(props) {
+    return createElement("List.Dropdown.Item", props);
+};
+const ListDropdownSection = function ListDropdownSection(props) {
+    return createElement("List.Dropdown.Section", props);
+};
+const ListDropdown = Object.assign(function ListDropdown(props) {
+    return useDropdown("List.Dropdown", props);
+}, { Item: ListDropdownItem, Section: ListDropdownSection });
+const ListItem = Object.assign(function ListItem(props) {
+    const { actions, detail, ...rest } = props;
+    return createElement("List.Item", rest, slot("actions", actions), slot("detail", detail));
+}, { Detail: ListItemDetail });
+function ListSection(props) {
+    return createElement("List.Section", props);
+}
+function ListEmptyView(props) {
+    const { actions, ...rest } = props;
+    return createElement("List.EmptyView", rest, slot("actions", actions));
+}
+export const List = Object.assign(function List(props) {
+    const { actions, searchBarAccessory, children, ...rest } = props;
+    return createElement("List", rest, children, slot("actions", actions), slot("searchBarAccessory", searchBarAccessory));
+}, { Item: ListItem, Section: ListSection, EmptyView: ListEmptyView, Dropdown: ListDropdown });

package/dist/api/menu-bar.d.ts

@@ -0,0 +1,54 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { ImageLike, Shortcut } from "./types.js";
+export interface MenuBarActionEvent {
+    type: "left-click" | "right-click";
+}
+export interface MenuBarExtraProps {
+    isLoading?: boolean;
+    title?: string;
+    tooltip?: string;
+    icon?: ImageLike;
+    children?: ReactNode;
+}
+export interface MenuBarItemProps {
+    title: string;
+    subtitle?: string;
+    icon?: ImageLike;
+    tooltip?: string;
+    onAction?: (event: MenuBarActionEvent) => void;
+    shortcut?: Shortcut | undefined;
+    alternate?: ReactElement<MenuBarItemProps>;
+}
+export interface MenuBarSectionProps {
+    children?: ReactNode;
+    title?: string;
+}
+export interface MenuBarSubmenuProps {
+    title: string;
+    icon?: ImageLike;
+    children?: ReactNode;
+}
+declare function Item({ alternate, shortcut, ...props }: MenuBarItemProps): ReactElement<{
+    title: string;
+    subtitle?: string;
+    icon?: ImageLike;
+    tooltip?: string;
+    onAction?: (event: MenuBarActionEvent) => void;
+    shortcut: Shortcut | undefined;
+}, string | import("react").JSXElementConstructor<any>>;
+declare function Section(props: MenuBarSectionProps): import("react").DOMElement<MenuBarSectionProps, Element>;
+declare function Submenu(props: MenuBarSubmenuProps): import("react").DOMElement<MenuBarSubmenuProps, Element>;
+declare function Separator(): import("react").DOMElement<import("react").DOMAttributes<Element>, Element>;
+export declare const MenuBarExtra: ((props: MenuBarExtraProps) => import("react").DOMElement<{
+    title?: string;
+    tooltip?: string;
+    icon?: ImageLike;
+    children?: ReactNode;
+    isLoading: boolean;
+}, Element>) & {
+    Item: typeof Item;
+    Section: typeof Section;
+    Submenu: typeof Submenu;
+    Separator: typeof Separator;
+};
+export {};

package/dist/api/menu-bar.js

@@ -0,0 +1,30 @@
+import { cloneElement, createElement } from "react";
+import { slot } from "./slot.js";
+function modifiers(shortcut, alternate) {
+    if (!shortcut)
+        return undefined;
+    const adjust = (value) => ({
+        ...value,
+        modifiers: [...value.modifiers.filter((key) => key !== "opt"), ...(alternate ? ["opt"] : [])],
+    });
+    if ("modifiers" in shortcut)
+        return adjust(shortcut);
+    return { ...shortcut, macOS: adjust(shortcut.macOS) };
+}
+function Item({ alternate, shortcut, ...props }) {
+    // Alternates inherit the parent's shortcut plus Option, never their own.
+    const primaryShortcut = alternate ? modifiers(shortcut, false) : shortcut;
+    return createElement("MenuBarExtra.Item", { ...props, shortcut: primaryShortcut }, slot("alternate", alternate ? cloneElement(alternate, { shortcut: modifiers(shortcut, true) }) : null));
+}
+function Section(props) {
+    return createElement("MenuBarExtra.Section", props);
+}
+function Submenu(props) {
+    return createElement("MenuBarExtra.Submenu", props);
+}
+function Separator() {
+    return createElement("MenuBarExtra.Separator");
+}
+export const MenuBarExtra = Object.assign(function MenuBarExtra(props) {
+    return createElement("MenuBarExtra", { ...props, isLoading: props.isLoading ?? false });
+}, { Item, Section, Submenu, Separator });

package/dist/api/metadata.d.ts

@@ -0,0 +1,62 @@
+import { type ReactNode } from "react";
+import type { ColorLike, ImageLike } from "./types.js";
+export interface MetadataLabelProps {
+    /** The title of the item. */
+    title: string;
+    /** An icon to illustrate the value of the item. */
+    icon?: ImageLike | null;
+    /**
+     * The text value of the item. Specifying `color` displays the text in the
+     * provided color, defaulting to `Color.PrimaryText`.
+     */
+    text?: string | {
+        value: string;
+        color?: ColorLike | null;
+    };
+}
+export interface MetadataLinkProps {
+    /** The title shown above the item. */
+    title: string;
+    /** The target of the link. */
+    target: string;
+    /** The text value of the item. */
+    text: string;
+}
+export interface MetadataProps {
+    /** The elements of the Metadata view. */
+    children?: ReactNode;
+}
+export interface MetadataSeparatorProps {
+}
+export interface MetadataTagListProps {
+    /** The title shown above the item. */
+    title: string;
+    /** The tags contained in the TagList. */
+    children?: ReactNode;
+}
+export interface MetadataTagListItemProps {
+    /** The optional tag icon. Required if the tag has no text. */
+    icon?: ImageLike | null;
+    /** The optional tag text. Required if the tag has no icon. */
+    text?: string;
+    /** Changes the text color to the provided color and sets a transparent background with the same color. */
+    color?: ColorLike | null;
+    /** Callback that is triggered when the item is clicked. */
+    onAction?: () => void;
+}
+export interface MetadataComponents {
+    (props: MetadataProps): ReactNode;
+    Label: (props: MetadataLabelProps) => ReactNode;
+    Link: (props: MetadataLinkProps) => ReactNode;
+    Separator: (props: MetadataSeparatorProps) => ReactNode;
+    TagList: {
+        (props: MetadataTagListProps): ReactNode;
+        Item: (props: MetadataTagListItemProps) => ReactNode;
+    };
+}
+/**
+ * `Detail.Metadata` and `List.Item.Detail.Metadata` render the same props, but
+ * scene element types are the public Raycast paths, so the namespace is built
+ * from the path of the view that owns it.
+ */
+export declare function createMetadata(prefix: "Detail" | "List.Item.Detail"): MetadataComponents;

package/dist/api/metadata.js

@@ -0,0 +1,33 @@
+import { createElement } from "react";
+/**
+ * `Detail.Metadata` and `List.Item.Detail.Metadata` render the same props, but
+ * scene element types are the public Raycast paths, so the namespace is built
+ * from the path of the view that owns it.
+ */
+export function createMetadata(prefix) {
+    const path = `${prefix}.Metadata`;
+    function Metadata(props) {
+        return createElement(path, props);
+    }
+    function Label(props) {
+        return createElement(`${path}.Label`, props);
+    }
+    function Link(props) {
+        return createElement(`${path}.Link`, props);
+    }
+    function Separator(props) {
+        return createElement(`${path}.Separator`, props);
+    }
+    function TagList(props) {
+        return createElement(`${path}.TagList`, props);
+    }
+    function TagListItem(props) {
+        return createElement(`${path}.TagList.Item`, props);
+    }
+    return Object.assign(Metadata, {
+        Label,
+        Link,
+        Separator,
+        TagList: Object.assign(TagList, { Item: TagListItem }),
+    });
+}

package/dist/api/navigation.d.ts

@@ -0,0 +1,36 @@
+import { type ReactNode } from "react";
+export interface Navigation {
+    push(component: ReactNode, onPop?: () => void): void;
+    pop(): void;
+}
+/** `popToRoot` options from the declarations. */
+export interface PopToRootOptions {
+    /**
+     * Raycast also clears the root search bar. Blast's headless clients own any
+     * search-bar state, so the request is recorded on the `Navigation` scene
+     * element (`props.popToRoot`) for clients to act on.
+     */
+    clearSearchBar?: boolean;
+}
+/** `clearSearchBar` options from the declarations. */
+export interface ClearSearchBarOptions {
+    /** Forces scrolling to the top of the list; the default is the client's. */
+    forceScrollToTop?: boolean;
+}
+export declare const RootNavigationEntryContext: import("react").Context<boolean>;
+export declare function subscribeClearSearchBar(listener: () => void): () => void;
+/** The recorded request, or `undefined` while no clear was asked for. */
+export declare function clearSearchBarRequest(): ClearSearchBarOptions | undefined;
+export declare function NavigationProvider({ children }: {
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<Navigation | null>>;
+export declare function useNavigation(): Navigation;
+/** `popToRoot` from the declarations: pop the current command's stack to root. */
+export declare function popToRoot(options?: PopToRootOptions): Promise<void>;
+/**
+ * `clearSearchBar` from the declarations. Blast has no search-bar state, so
+ * the request is recorded on the `Navigation` scene element
+ * (`props.clearSearchBar`) for clients to act on, exactly like `closeMainWindow`
+ * records its own request.
+ */
+export declare function clearSearchBar(options?: ClearSearchBarOptions): Promise<void>;

package/dist/api/navigation.js

@@ -0,0 +1,99 @@
+import { createContext, createElement, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { FeedbackScene } from "./feedback.js";
+import { closeRequest, subscribeCloseRequest } from "./window.js";
+export const RootNavigationEntryContext = createContext(true);
+const NavigationContext = createContext(null);
+// `popToRoot()` is a module-level API without React context, so mounted
+// providers register their stack; the most recent one answers. One command per
+// runtime process in production; tests may hold several.
+const stacks = new Set();
+// Like `closeMainWindow`, a `clearSearchBar()` request is module state: it is
+// rendered by whichever `Navigation` is mounted and dropped with that scene, so
+// a later command starts with a clean search bar.
+let searchBarRequest;
+const searchBarListeners = new Set();
+export function subscribeClearSearchBar(listener) {
+    searchBarListeners.add(listener);
+    return () => {
+        searchBarListeners.delete(listener);
+        if (searchBarListeners.size === 0)
+            searchBarRequest = undefined;
+    };
+}
+/** The recorded request, or `undefined` while no clear was asked for. */
+export function clearSearchBarRequest() {
+    return searchBarRequest;
+}
+export function NavigationProvider({ children }) {
+    const entries = useRef([]);
+    const nextId = useRef(1);
+    const [stack, setStack] = useState([]);
+    const [popToRootOptions, setPopToRootOptions] = useState();
+    // A fresh object per `closeMainWindow()` call, so the snapshot identity
+    // changes and `closeMainWindow` props follow the recorded request.
+    const closeMainWindow = useSyncExternalStore(subscribeCloseRequest, closeRequest, closeRequest);
+    const searchBarClear = useSyncExternalStore(subscribeClearSearchBar, clearSearchBarRequest, clearSearchBarRequest);
+    const navigation = useMemo(() => ({
+        push(component, onPop) {
+            entries.current = [...entries.current, { id: nextId.current++, component, onPop }];
+            setStack(entries.current);
+        },
+        pop() {
+            const entry = entries.current.at(-1);
+            if (!entry)
+                return;
+            entries.current = entries.current.slice(0, -1);
+            setStack(entries.current);
+            entry.onPop?.();
+        },
+    }), []);
+    const popToRootStack = useMemo(() => (options) => {
+        setPopToRootOptions(options);
+        // The root view is the provider's own children, not an entry (decision
+        // 0003), so nothing above it is kept; onPops run topmost first, like
+        // successive `pop()` calls.
+        if (entries.current.length === 0)
+            return;
+        const popped = entries.current.toReversed();
+        entries.current = [];
+        setStack(entries.current);
+        for (const entry of popped)
+            entry.onPop?.();
+    }, []);
+    stacks.add(popToRootStack);
+    useEffect(() => {
+        return () => {
+            stacks.delete(popToRootStack);
+        };
+    }, [popToRootStack]);
+    return createElement(NavigationContext.Provider, { value: navigation }, createElement("Navigation", {
+        depth: stack.length + 1,
+        pop: stack.length ? navigation.pop : undefined,
+        popToRoot: popToRootOptions,
+        clearSearchBar: searchBarClear,
+        closeMainWindow,
+    }, createElement("Navigation.Entry", { key: 0, active: stack.length === 0 }, children), ...stack.map((entry, index) => createElement("Navigation.Entry", { key: entry.id, active: index === stack.length - 1 }, createElement(RootNavigationEntryContext.Provider, { value: false }, entry.component))), createElement(FeedbackScene, { key: "feedback" })));
+}
+export function useNavigation() {
+    const navigation = useContext(NavigationContext);
+    if (!navigation)
+        throw new Error("useNavigation requires a running view command");
+    return navigation;
+}
+/** `popToRoot` from the declarations: pop the current command's stack to root. */
+export async function popToRoot(options) {
+    [...stacks].at(-1)?.(options);
+}
+/**
+ * `clearSearchBar` from the declarations. Blast has no search-bar state, so
+ * the request is recorded on the `Navigation` scene element
+ * (`props.clearSearchBar`) for clients to act on, exactly like `closeMainWindow`
+ * records its own request.
+ */
+export async function clearSearchBar(options = {}) {
+    if (searchBarListeners.size === 0)
+        return;
+    searchBarRequest = { ...options };
+    for (const listener of searchBarListeners)
+        listener();
+}