@blastlauncher/runtime 1.0.5 → 3.0.0-alpha.1

package/dist/api/environment.d.ts

@@ -0,0 +1,44 @@
+import type { CommandMode, InitEnvironment } from "@blastlauncher/protocol";
+import { type LaunchContext, type LaunchTypeValue } from "./launch.js";
+/** Raycast's `raycastVersion`; Blast is not Raycast, so this is our own value. */
+export declare const RAYCAST_VERSION = "0.0.0-blast";
+/** The theme the host reports; a headless host has no UI and defaults to `"dark"`. */
+export type Appearance = "light" | "dark";
+export type TextSize = "medium" | "large";
+/** Raycast's `EntryPointTypes`: Blast launches commands only. */
+export type EntryPointType = "command" | "tool";
+export type EntryPointMode = CommandMode;
+export type Environment = {
+    raycastVersion: string;
+    ownerOrAuthorName: string;
+    extensionName: string;
+    entryPointType: EntryPointType;
+    entryPointName: string;
+    entryPointMode: EntryPointMode;
+    assetsPath: string;
+    supportPath: string;
+    isDevelopment: boolean;
+    appearance: Appearance;
+    textSize: TextSize;
+    launchType: LaunchTypeValue;
+    /** Deprecated alias of {@link Environment.entryPointName}; extensions still read it. */
+    commandName: string;
+    /** @deprecated Use `appearance` instead. */
+    theme: Appearance;
+    /** @deprecated Use the top-level `launchContext` prop instead. */
+    launchContext?: LaunchContext;
+    /** @deprecated Use `entryPointMode` instead. */
+    commandMode: EntryPointMode;
+    canAccess(api: unknown): boolean;
+};
+/** Mutable in place: extension modules bind this object when they import it. */
+export declare const environment: Environment;
+/**
+ * Installs the values from `init`; the runtime calls it before importing the
+ * command. The entry point mirrors the launched command, as Raycast defines it.
+ */
+export declare function setEnvironment(values: InitEnvironment, command: {
+    name: string;
+    mode: CommandMode;
+    launchContext?: LaunchContext;
+}): void;

package/dist/api/environment.js

@@ -0,0 +1,61 @@
+import { LaunchType } from "./launch.js";
+import { OPTIONAL_API } from "./ai-browser.js";
+import { unsupportedPath } from "./unsupported.js";
+/** Raycast's `raycastVersion`; Blast is not Raycast, so this is our own value. */
+export const RAYCAST_VERSION = "0.0.0-blast";
+let availableAPIs = [];
+function canAccess(api) {
+    const optional = (typeof api === "object" && api !== null) || typeof api === "function"
+        ? Reflect.get(api, OPTIONAL_API)
+        : undefined;
+    return optional === undefined
+        ? unsupportedPath(api) === undefined
+        : availableAPIs.includes(optional);
+}
+/** Mutable in place: extension modules bind this object when they import it. */
+export const environment = {
+    raycastVersion: RAYCAST_VERSION,
+    ownerOrAuthorName: "",
+    extensionName: "",
+    // Blast launches commands, never tools.
+    entryPointType: "command",
+    entryPointName: "",
+    entryPointMode: "view",
+    assetsPath: "",
+    supportPath: "",
+    isDevelopment: false,
+    appearance: "dark",
+    textSize: "medium",
+    // Blast only launches commands the user initiated; a background launch is
+    // out of scope (task 0028).
+    launchType: LaunchType.UserInitiated,
+    commandName: "",
+    // The deprecated aliases mirror their replacements from the start.
+    theme: "dark",
+    commandMode: "view",
+    canAccess,
+};
+/**
+ * Installs the values from `init`; the runtime calls it before importing the
+ * command. The entry point mirrors the launched command, as Raycast defines it.
+ */
+export function setEnvironment(values, command) {
+    availableAPIs = values.availableAPIs ?? [];
+    environment.extensionName = values.extensionName;
+    environment.ownerOrAuthorName = values.ownerOrAuthorName;
+    environment.entryPointType = "command";
+    environment.entryPointName = command.name;
+    environment.entryPointMode = command.mode;
+    environment.assetsPath = values.assetsPath;
+    environment.supportPath = values.supportPath;
+    environment.isDevelopment = values.isDevelopment;
+    environment.appearance = values.appearance;
+    environment.textSize = values.textSize;
+    environment.commandName = values.commandName;
+    environment.theme = values.appearance;
+    environment.commandMode = command.mode;
+    if (command.launchContext === undefined)
+        delete environment.launchContext;
+    else
+        environment.launchContext = command.launchContext;
+}

package/dist/api/feedback.d.ts

@@ -0,0 +1,94 @@
+import type { ImageLike, Shortcut } from "./types.js";
+import type { PopToRootTypeValue } from "./window.js";
+export interface ToastActionOptions {
+    title: string;
+    shortcut?: Shortcut;
+    onAction(toast: Toast): void;
+}
+export interface ToastOptions {
+    title: string;
+    message?: string | undefined;
+    style?: string;
+    primaryAction?: ToastActionOptions | undefined;
+    secondaryAction?: ToastActionOptions | undefined;
+}
+export interface AlertActionOptions {
+    title: string;
+    style?: string;
+    onAction?(): void;
+}
+export interface AlertOptions {
+    title: string;
+    message?: string | undefined;
+    icon?: ImageLike;
+    primaryAction?: AlertActionOptions;
+    dismissAction?: AlertActionOptions;
+    rememberUserChoice?: boolean;
+}
+export interface HUDOptions {
+    clearRootSearch?: boolean;
+    popToRootType?: PopToRootTypeValue;
+}
+export declare const Alert: {
+    readonly ActionStyle: {
+        readonly Default: "default";
+        readonly Cancel: "cancel";
+        readonly Destructive: "destructive";
+    };
+};
+export declare const AlertActionStyle: {
+    readonly Default: "default";
+    readonly Cancel: "cancel";
+    readonly Destructive: "destructive";
+};
+export declare function setFeedbackMount(callback: () => void): void;
+/**
+ * Mounts that lazily created scene, if the command has one. Feedback state and
+ * the window's `closeMainWindow` request both publish through it.
+ */
+export declare function mountScene(): void;
+export declare class Toast {
+    static Style: {
+        readonly Success: "SUCCESS";
+        readonly Failure: "FAILURE";
+        readonly Animated: "ANIMATED";
+    };
+    private options;
+    constructor(props: ToastOptions);
+    get title(): string;
+    set title(value: string);
+    get message(): string | undefined;
+    set message(value: string | undefined);
+    get style(): string;
+    set style(value: string);
+    get primaryAction(): ToastActionOptions | undefined;
+    set primaryAction(value: ToastActionOptions | undefined);
+    get secondaryAction(): ToastActionOptions | undefined;
+    set secondaryAction(value: ToastActionOptions | undefined);
+    show(): Promise<void>;
+    hide(): Promise<void>;
+    private update;
+}
+export declare const ToastStyle: {
+    readonly Success: "SUCCESS";
+    readonly Failure: "FAILURE";
+    readonly Animated: "ANIMATED";
+};
+export declare function showToast(options: ToastOptions): Promise<Toast>;
+export declare function showToast(style: string, title: string, message?: string): Promise<Toast>;
+export declare function showHUD(title: string, options?: HUDOptions): Promise<void>;
+export declare function confirmAlert(options: AlertOptions): Promise<boolean>;
+export declare function FeedbackScene(): (import("react").DOMElement<import("react").DOMAttributes<Element>, Element> | import("react").ReactElement<{
+    key: string;
+    title: string;
+    message: string | undefined;
+    style: string;
+}, string | import("react").JSXElementConstructor<any>> | import("react").ReactElement<{
+    key: number;
+    title: string;
+    message: string | undefined;
+    icon: ImageLike | undefined;
+    rememberUserChoice: boolean | undefined;
+    rememberChoice?: boolean;
+    onRememberUserChoiceChange?: (checked: boolean) => void;
+}, string | import("react").JSXElementConstructor<any>> | undefined)[];

package/dist/api/feedback.js

@@ -0,0 +1,228 @@
+import { createElement as h, useLayoutEffect, useSyncExternalStore } from "react";
+// `AlertActionStyle_2` and `ToastStyle_2` are the declarations' names behind the
+// public `Alert.ActionStyle` and `Toast.Style` paths (api-extractor dedupes
+// alias collisions with a numeric suffix).
+import { AlertActionStyle_2, ToastStyle_2 } from "./enums.generated.js";
+import { requestCapability } from "./capability.js";
+import { environment } from "./environment.js";
+export const Alert = { ActionStyle: AlertActionStyle_2 };
+export const AlertActionStyle = Alert.ActionStyle;
+const activeToast = { current: undefined };
+let hud;
+let revision = 0;
+const listeners = new Set();
+const committed = new Map();
+let nextAlert = 0;
+const alerts = [];
+let mount;
+// No-view commands mount a scene lazily, retaining their scene-free fast path.
+export function setFeedbackMount(callback) {
+    mount = callback;
+}
+/**
+ * Mounts that lazily created scene, if the command has one. Feedback state and
+ * the window's `closeMainWindow` request both publish through it.
+ */
+export function mountScene() {
+    mount?.();
+}
+function changed(wait = false) {
+    const pendingRevision = ++revision;
+    const result = wait
+        ? new Promise((resolve) => committed.set(pendingRevision, resolve))
+        : Promise.resolve();
+    for (const listener of listeners)
+        listener();
+    mountScene();
+    // Without a subscriber no React commit can acknowledge this revision.
+    queueMicrotask(() => {
+        if (listeners.size === 0) {
+            committed.get(pendingRevision)?.();
+            committed.delete(pendingRevision);
+        }
+    });
+    return result;
+}
+const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+            activeToast.current = undefined;
+            hud = undefined;
+            for (const alert of alerts.splice(0)) {
+                alert.remember = false;
+                alert.resolve(false);
+            }
+            for (const resolve of committed.values())
+                resolve();
+            committed.clear();
+            revision++;
+        }
+    };
+};
+const snapshot = () => revision;
+export class Toast {
+    static Style = ToastStyle_2;
+    options;
+    constructor(props) {
+        this.options = { ...props, style: props.style ?? Toast.Style.Success };
+    }
+    get title() {
+        return this.options.title;
+    }
+    set title(value) {
+        this.options.title = value;
+        this.update();
+    }
+    get message() {
+        return this.options.message;
+    }
+    set message(value) {
+        this.options.message = value;
+        this.update();
+    }
+    get style() {
+        return this.options.style;
+    }
+    set style(value) {
+        this.options.style = value;
+        this.update();
+    }
+    get primaryAction() {
+        return this.options.primaryAction;
+    }
+    set primaryAction(value) {
+        this.options.primaryAction = value;
+        this.update();
+    }
+    get secondaryAction() {
+        return this.options.secondaryAction;
+    }
+    set secondaryAction(value) {
+        this.options.secondaryAction = value;
+        this.update();
+    }
+    show() {
+        activeToast.current = this;
+        return changed(true);
+    }
+    hide() {
+        if (activeToast.current !== this)
+            return Promise.resolve();
+        activeToast.current = undefined;
+        return changed(true);
+    }
+    update() {
+        if (activeToast.current === this)
+            void changed();
+    }
+}
+export const ToastStyle = Toast.Style;
+export async function showToast(options, title, message) {
+    const next = new Toast(typeof options === "string" ? { style: options, title: title, message } : options);
+    await next.show();
+    return next;
+}
+export function showHUD(title, options = {}) {
+    hud = { title, ...options };
+    return changed(true);
+}
+export async function confirmAlert(options) {
+    // Host storage supplies extension isolation; the key separates commands and
+    // alert text/actions without depending on function identity or queue order.
+    const key = `blast:alert:${JSON.stringify([
+        environment.commandName,
+        options.title,
+        options.message ?? null,
+        options.primaryAction?.title ?? "OK",
+        options.primaryAction?.style ?? Alert.ActionStyle.Default,
+        options.dismissAction?.title ?? "Cancel",
+        options.dismissAction?.style ?? Alert.ActionStyle.Cancel,
+    ])}`;
+    if (options.rememberUserChoice) {
+        const answer = await requestCapability("storage.get", { scope: "blast:internal", key });
+        if (typeof answer === "boolean") {
+            (answer ? options.primaryAction : options.dismissAction)?.onAction?.();
+            return answer;
+        }
+    }
+    const alert = { id: ++nextAlert, options, remember: false, resolve: (_value) => { } };
+    const answer = await new Promise((resolve) => {
+        alert.resolve = resolve;
+        alerts.push(alert);
+        void changed();
+    });
+    if (options.rememberUserChoice && alert.remember)
+        await requestCapability("storage.set", { scope: "blast:internal", key, value: answer });
+    return answer;
+}
+export function FeedbackScene() {
+    const version = useSyncExternalStore(subscribe, snapshot, snapshot);
+    useLayoutEffect(() => {
+        for (const [pending, resolve] of committed) {
+            if (pending <= version) {
+                committed.delete(pending);
+                resolve();
+            }
+        }
+    }, [version]);
+    const currentToast = activeToast.current;
+    const alert = alerts[0];
+    const respond = (answer) => {
+        // Stale or repeated events must not answer the next queued alert.
+        if (alerts[0] !== alert || !alert)
+            return;
+        alerts.shift();
+        void changed();
+        alert.resolve(answer);
+        return (answer ? alert.options.primaryAction : alert.options.dismissAction)?.onAction?.();
+    };
+    const toastAction = (action, name) => action &&
+        h("Toast.Action", {
+            key: name,
+            name,
+            title: action.title,
+            shortcut: action.shortcut,
+            onAction: () => action.onAction(currentToast),
+        });
+    return [
+        currentToast &&
+            h("Toast", {
+                key: "toast",
+                title: currentToast.title,
+                message: currentToast.message,
+                style: currentToast.style,
+            }, toastAction(currentToast.primaryAction, "primaryAction"), toastAction(currentToast.secondaryAction, "secondaryAction")),
+        hud && h("HUD", { key: "hud", ...hud }),
+        alert &&
+            h("Alert", {
+                key: alert.id,
+                title: alert.options.title,
+                message: alert.options.message,
+                icon: alert.options.icon,
+                rememberUserChoice: alert.options.rememberUserChoice,
+                ...(alert.options.rememberUserChoice
+                    ? {
+                        rememberChoice: alert.remember,
+                        onRememberUserChoiceChange: (checked) => {
+                            if (alerts[0] !== alert)
+                                return;
+                            alert.remember = checked === true;
+                            void changed();
+                        },
+                    }
+                    : {}),
+            }, h("Alert.Action", {
+                name: "primaryAction",
+                title: alert.options.primaryAction?.title ?? "OK",
+                style: alert.options.primaryAction?.style ?? Alert.ActionStyle.Default,
+                onAction: () => respond(true),
+            }), h("Alert.Action", {
+                name: "dismissAction",
+                title: alert.options.dismissAction?.title ?? "Cancel",
+                style: alert.options.dismissAction?.style ?? Alert.ActionStyle.Cancel,
+                onAction: () => respond(false),
+            })),
+    ];
+}

package/dist/api/form.d.ts

@@ -0,0 +1,162 @@
+import { type ReactNode } from "react";
+import { DatePickerType } from "./enums.generated.js";
+import type { ImageLike, Shortcut } from "./types.js";
+export type FormValue = string | number | boolean | string[] | number[] | Date | null;
+export type FormValues = Record<string, FormValue>;
+export interface FormEvent<T extends FormValue> {
+    target: {
+        id: string;
+        value?: T;
+    };
+    type: "focus" | "blur";
+}
+/** `Form.ItemReference`: the shared imperative handle every field ref exposes. */
+export interface FormItemRef {
+    focus: () => void;
+    reset: () => void;
+}
+export interface FormItemProps<T extends FormValue> {
+    id: string;
+    title?: string;
+    info?: string;
+    error?: string;
+    storeValue?: boolean;
+    autoFocus?: boolean;
+    value?: T;
+    defaultValue?: T;
+    onChange?: (value: T) => void;
+    onBlur?: (event: FormEvent<T>) => void;
+    onFocus?: (event: FormEvent<T>) => void;
+}
+export interface FormProps {
+    children?: ReactNode;
+    actions?: ReactNode;
+    searchBarAccessory?: ReactNode;
+    navigationTitle?: string;
+    isLoading?: boolean;
+    enableDrafts?: boolean;
+}
+export interface FormTextFieldProps extends FormItemProps<string> {
+    placeholder?: string;
+}
+export interface FormTextAreaProps extends FormTextFieldProps {
+    enableMarkdown?: boolean;
+}
+export interface FormCheckboxProps extends FormItemProps<boolean> {
+    label: string;
+}
+/** `Form.DatePicker.Type`: what a date picker lets the user pick. */
+export { DatePickerType };
+export interface FormFilePickerProps extends FormItemProps<string[]> {
+    allowMultipleSelection?: boolean;
+    canChooseDirectories?: boolean;
+    canChooseFiles?: boolean;
+    showHiddenFiles?: boolean;
+}
+export interface FormPasswordFieldProps extends FormItemProps<string> {
+    placeholder?: string;
+}
+export interface FormTagPickerProps extends FormItemProps<string[]> {
+    children?: ReactNode;
+    placeholder?: string;
+}
+export interface FormTagPickerItemProps {
+    value: string;
+    title: string;
+    icon?: ImageLike;
+}
+export interface FormLinkAccessoryProps {
+    target: string;
+    text: string;
+}
+export interface FormDatePickerProps extends FormItemProps<Date | null> {
+    type?: (typeof DatePickerType)[keyof typeof DatePickerType];
+    min?: Date;
+    max?: Date;
+}
+export interface FormDropdownProps extends FormItemProps<string> {
+    children?: ReactNode;
+    placeholder?: string;
+    filtering?: boolean | {
+        keepSectionOrder: boolean;
+    };
+    isLoading?: boolean;
+    throttle?: boolean;
+    onSearchTextChange?: (text: string) => void;
+}
+export interface FormDropdownItemProps {
+    value: string;
+    title: string;
+    icon?: ImageLike;
+    keywords?: string[];
+}
+export interface FormDropdownSectionProps {
+    children?: ReactNode;
+    title?: string;
+}
+export interface FormDescriptionProps {
+    title?: string;
+    text: string;
+}
+type Fields = Map<string, {
+    read: () => FormValue;
+    secret: boolean;
+    event: (type: "focus" | "blur") => void;
+}>;
+/** Installed before importing the command, alongside its launch props. */
+export declare function setFormDraftValues(values: FormValues | undefined): void;
+export interface FormContextValue {
+    fields: Fields;
+    enableDrafts: boolean;
+    focusedId: string | null;
+    focus: (id: string | null) => void;
+    blur: (id: string) => void;
+    draft: FormValues | undefined;
+}
+/** Decodes a stored or wire-carried values object back into typed `FormValue`s. */
+export declare function decodeFormValues(values: Record<string, unknown>): FormValues;
+/** Graceful shutdown must receive the host's write acknowledgements before exiting. */
+export declare function flushFormPersistence(): Promise<void>;
+export declare const Form: (({ children, actions, searchBarAccessory, ...props }: FormProps) => import("react").FunctionComponentElement<import("react").ProviderProps<FormContextValue | null>>) & {
+    FilePicker: import("react").ForwardRefExoticComponent<FormFilePickerProps & import("react").RefAttributes<FormItemRef>>;
+    TagPicker: import("react").ForwardRefExoticComponent<FormTagPickerProps & import("react").RefAttributes<FormItemRef>> & {
+        Item: (props: FormTagPickerItemProps) => import("react").ReactElement<FormTagPickerItemProps, string | import("react").JSXElementConstructor<any>>;
+    };
+    PasswordField: import("react").ForwardRefExoticComponent<FormPasswordFieldProps & import("react").RefAttributes<FormItemRef>>;
+    TextField: import("react").ForwardRefExoticComponent<FormTextFieldProps & import("react").RefAttributes<FormItemRef>>;
+    TextArea: import("react").ForwardRefExoticComponent<FormTextAreaProps & import("react").RefAttributes<FormItemRef>>;
+    Checkbox: import("react").ForwardRefExoticComponent<FormCheckboxProps & import("react").RefAttributes<FormItemRef>>;
+    DatePicker: import("react").ForwardRefExoticComponent<FormDatePickerProps & import("react").RefAttributes<FormItemRef>> & {
+        Type: {
+            readonly Date: "date";
+            readonly DateTime: "date_time";
+        };
+        /** Whether the date is a full day: non-null with local time exactly midnight. */
+        isFullDay(date?: Date | null): boolean;
+    };
+    Dropdown: import("react").ForwardRefExoticComponent<FormDropdownProps & import("react").RefAttributes<FormItemRef>> & {
+        Item: (props: FormDropdownItemProps) => import("react").ReactElement<FormDropdownItemProps, string | import("react").JSXElementConstructor<any>>;
+        Section: (props: FormDropdownSectionProps) => import("react").DOMElement<FormDropdownSectionProps, Element>;
+    };
+    LinkAccessory: (props: FormLinkAccessoryProps) => import("react").ReactElement<FormLinkAccessoryProps, string | import("react").JSXElementConstructor<any>>;
+    Description: (props: FormDescriptionProps) => import("react").ReactElement<FormDescriptionProps, string | import("react").JSXElementConstructor<any>>;
+    Separator: (props: Record<string, never>) => import("react").DOMElement<Record<string, never>, Element>;
+};
+export interface SubmitFormProps<T extends FormValues = FormValues> {
+    title?: string;
+    icon?: ImageLike;
+    shortcut?: Shortcut;
+    style?: "regular" | "destructive";
+    onSubmit?: (input: T) => void | boolean | Promise<void | boolean>;
+}
+export declare function SubmitForm<T extends FormValues>({ onSubmit, title, ...props }: SubmitFormProps<T>): import("react").ReactElement<{
+    icon?: ImageLike;
+    shortcut?: Shortcut;
+    style?: "regular" | "destructive";
+    submissionFailureCount: number;
+    title: string;
+    onAction: () => void | boolean | Promise<void | boolean>;
+}, string | import("react").JSXElementConstructor<any>>;
+export declare namespace SubmitForm {
+    var displayName: string;
+}