@blastlauncher/web 0.0.0-stage → 3.0.0-alpha.2

package/dist/handlers.js

@@ -0,0 +1,22 @@
+/** localStorage, the Clipboard API (the browser asks the user) and a new tab for URLs. */
+export function createDefaultHandlers() {
+    let storage;
+    try {
+        storage = globalThis.localStorage;
+    }
+    catch {
+        // Blocked storage (private windows, sandboxed frames): capabilities fall back to memory.
+    }
+    return {
+        ...(storage ? { storage } : {}),
+        clipboard: {
+            readText: () => navigator.clipboard.readText(),
+            writeText: (text) => navigator.clipboard.writeText(text),
+        },
+        openUrl: (url) => {
+            // Only web URLs: an extension must not open javascript: or file: links.
+            if (/^https?:\/\//i.test(url))
+                window.open(url, "_blank", "noopener,noreferrer");
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { type WebMount, type WebMountOptions } from "./session.js";
+export * from "./browser-install.js";
+export * from "./browser-bundle.js";
+export { bundleKey, bundleMatches, parseBundleIndex, sha256Hex } from "./bundles.js";
+export { createDefaultHandlers } from "./handlers.js";
+export { defineBlastExtension } from "./custom-element.js";
+export { prewarm } from "./sandbox.js";
+export type { WebExit, WebFrame, WebHandlers, WebMount, WebMountOptions, WebPreferenceRequest, WebStatus, WebView, } from "./session.js";
+/**
+ * Runs a Raycast extension inside `element` (or hands its views to
+ * `options.render`). The extension executes in the cross-origin sandbox at
+ * `options.sandboxUrl`; it never touches the embedding page.
+ */
+export declare function mount(element: HTMLElement, options: WebMountOptions): WebMount;

package/dist/index.js

@@ -0,0 +1,17 @@
+import { startSession } from "./session.js";
+export * from "./browser-install.js";
+export * from "./browser-bundle.js";
+export { bundleKey, bundleMatches, parseBundleIndex, sha256Hex } from "./bundles.js";
+export { createDefaultHandlers } from "./handlers.js";
+export { defineBlastExtension } from "./custom-element.js";
+export { prewarm } from "./sandbox.js";
+/**
+ * Runs a Raycast extension inside `element` (or hands its views to
+ * `options.render`). The extension executes in the cross-origin sandbox at
+ * `options.sandboxUrl`; it never touches the embedding page.
+ */
+export function mount(element, options) {
+    if (!element)
+        throw new TypeError("mount requires an element");
+    return startSession(element, options);
+}

package/dist/launch.d.ts

@@ -0,0 +1,11 @@
+export declare class BrowserLaunchTimeoutError extends Error {
+    readonly code = "BROWSER_LAUNCH_TIMEOUT";
+    readonly stage: string;
+    constructor(timeoutMs: number, stage: string);
+}
+export declare function withLaunchTimeout<T>(promise: Promise<T>, timeoutMs: number, stage?: string): Promise<T>;
+export declare function createLaunchGeneration(): {
+    next: () => number;
+    current: () => number;
+    isCurrent: (token: number) => boolean;
+};

package/dist/launch.js

@@ -0,0 +1,29 @@
+export class BrowserLaunchTimeoutError extends Error {
+    code = "BROWSER_LAUNCH_TIMEOUT";
+    stage;
+    constructor(timeoutMs, stage) {
+        super(`Command did not start (${stage}) after ${timeoutMs} ms`);
+        this.name = "BrowserLaunchTimeoutError";
+        this.stage = stage;
+    }
+}
+export function withLaunchTimeout(promise, timeoutMs, stage = "waiting for runtime port") {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new BrowserLaunchTimeoutError(timeoutMs, stage)), timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+export function createLaunchGeneration() {
+    let generation = 0;
+    return {
+        next: () => ++generation,
+        current: () => generation,
+        isCurrent: (token) => token === generation,
+    };
+}

package/dist/prebuilt.d.ts

@@ -0,0 +1,24 @@
+import type { BrowserBundleFile } from "./browser-bundle.js";
+import { type BundleIndex, type CatalogManifest } from "./bundles.js";
+/** Where a deployment serves its prebuilt bundles (see `WebMountOptions.bundlesUrl`). */
+export type BundleLocation = {
+    bundlesUrl: string;
+    buildUrl?: string | undefined;
+};
+export type PrebuiltCommand = {
+    code: string;
+    files: Map<string, BrowserBundleFile>;
+    manifest: CatalogManifest;
+};
+/**
+ * The validated index, fetched once per location. A `buildUrl` whose `sha`
+ * differs from the index's `buildSha` means the index came from another
+ * deploy (a stale cache), so it is ignored.
+ */
+export declare function loadBundleIndex(location: BundleLocation): Promise<BundleIndex | undefined>;
+/** The shared runtime the prebuilt bundles import from, when the index has one. */
+export declare function loadPrebuiltRuntime(location: BundleLocation): Promise<string | undefined>;
+/** Bundles are keyed by Store name, so only `raycast/extensions` sources have one. */
+export declare function storeExtensionName(source: string): string | undefined;
+/** A verified prebuilt command, or undefined to fall back to fetching and bundling sources. */
+export declare function loadPrebuiltCommand(location: BundleLocation, source: string, command: string): Promise<PrebuiltCommand | undefined>;

package/dist/prebuilt.js

@@ -0,0 +1,112 @@
+import { bundleKey, bundleMatches, parseBundleIndex, sha256Hex, } from "./bundles.js";
+import { resolveExtensionSource } from "./extension-files.js";
+import { isTextExtension, parseExtensionSource } from "./source.js";
+/** Relative URLs resolve against the page; tests pass absolute ones. */
+const page = () => globalThis.location?.href;
+const indexes = new Map();
+const runtimes = new Map();
+const locationKey = (location) => `${location.bundlesUrl}\n${location.buildUrl ?? ""}`;
+const urlFor = (path, location) => new URL(path, new URL(location.bundlesUrl, page()));
+/** Fetches a file the index lists; undefined unless its size and digest match. */
+async function verified(entry, location) {
+    const response = await fetch(urlFor(entry.path, location));
+    if (!response.ok)
+        return undefined;
+    const bytes = await response.arrayBuffer();
+    if (bytes.byteLength !== entry.bytes || (await sha256Hex(bytes)) !== entry.sha256)
+        return undefined;
+    return bytes;
+}
+/**
+ * The validated index, fetched once per location. A `buildUrl` whose `sha`
+ * differs from the index's `buildSha` means the index came from another
+ * deploy (a stale cache), so it is ignored.
+ */
+export function loadBundleIndex(location) {
+    const key = locationKey(location);
+    let pending = indexes.get(key);
+    if (!pending) {
+        pending = (async () => {
+            const [indexResponse, buildResponse] = await Promise.all([
+                fetch(new URL(location.bundlesUrl, page())),
+                location.buildUrl ? fetch(new URL(location.buildUrl, page())) : null,
+            ]);
+            if (!indexResponse.ok || (buildResponse && !buildResponse.ok))
+                return undefined;
+            const index = parseBundleIndex(await indexResponse.json());
+            if (buildResponse) {
+                const build = (await buildResponse.json());
+                if (build.sha !== index.buildSha)
+                    return undefined;
+            }
+            return index;
+        })().catch(() => undefined);
+        // Only a usable index is kept; a failed fetch is retried by the next launch.
+        void pending.then((index) => index ?? indexes.delete(key));
+        indexes.set(key, pending);
+    }
+    return pending;
+}
+/** The shared runtime the prebuilt bundles import from, when the index has one. */
+export function loadPrebuiltRuntime(location) {
+    const key = locationKey(location);
+    let pending = runtimes.get(key);
+    if (!pending) {
+        pending = (async () => {
+            const index = await loadBundleIndex(location);
+            const bytes = index?.runtime ? await verified(index.runtime, location) : undefined;
+            return bytes ? new TextDecoder().decode(bytes) : undefined;
+        })().catch(() => undefined);
+        void pending.then((code) => code ?? runtimes.delete(key));
+        runtimes.set(key, pending);
+    }
+    return pending;
+}
+/** Bundles are keyed by Store name, so only `raycast/extensions` sources have one. */
+export function storeExtensionName(source) {
+    try {
+        const parsed = parseExtensionSource(resolveExtensionSource(source));
+        const [folder, name, ...rest] = parsed.path.split("/");
+        return parsed.owner === "raycast" &&
+            parsed.repo === "extensions" &&
+            folder === "extensions" &&
+            name &&
+            rest.length === 0
+            ? name
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A verified prebuilt command, or undefined to fall back to fetching and bundling sources. */
+export async function loadPrebuiltCommand(location, source, command) {
+    try {
+        const extension = storeExtensionName(source);
+        const index = extension ? await loadBundleIndex(location) : undefined;
+        if (!extension || !index)
+            return undefined;
+        const key = bundleKey(extension, command);
+        const entry = index.bundles[key];
+        // An entry without manifest data predates 0133; the source path has the full package.json.
+        if (!entry?.manifest)
+            return undefined;
+        const response = await fetch(urlFor(entry.path, location));
+        if (!response.ok)
+            return undefined;
+        const bytes = await response.arrayBuffer();
+        if (!(await bundleMatches(index, index.buildSha, key, bytes)))
+            return undefined;
+        const files = new Map();
+        for (const [name, file] of Object.entries(entry.files ?? {})) {
+            const fileBytes = await verified(file, location);
+            if (!fileBytes)
+                return undefined;
+            files.set(`/${name}`, isTextExtension(name) ? new TextDecoder().decode(fileBytes) : new Uint8Array(fileBytes));
+        }
+        return { code: new TextDecoder().decode(bytes), files, manifest: entry.manifest };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/render.d.ts

@@ -0,0 +1,62 @@
+/** @param {unknown} value */
+export declare function escapeHtml(value: unknown): string;
+/**
+ * A shortcut keycap. A combo the browser keeps for itself is drawn muted with
+ * the hint as its tooltip, so it never looks live when it is not.
+ * @param {"small" | "kbd"} tag @param {string} label @param {(label: string) => string} [hint]
+ */
+export declare const keycap: (tag: "small" | "kbd", label: string, hint?: (label: string) => string) => string;
+/** Render the deliberately small, safe markdown subset used by Detail. @param {unknown} markdown */
+export declare function renderMarkdown(markdown: unknown): string;
+export type FooterStatus = {
+    text: string;
+    error?: boolean;
+    progress?: boolean;
+    stage?: string;
+};
+export type ExtensionContext = {
+    extensionTitle: string;
+    commandTitle: string;
+    icon?: string;
+    iconUrl?: string;
+};
+/**
+ * Toast, HUD and alert: the feedback a command shows over whatever it draws.
+ * @param {import("@blastlauncher/client-core").ControllerView} view
+ * @param {{reservedHint?: (label: string) => string}} [options]
+ */
+export declare function feedbackMarkup(view: import("@blastlauncher/client-core").ControllerView, options?: {
+    reservedHint?: (label: string) => string;
+}): string;
+/**
+ * `actionsKey` labels the Actions footer (`⌘K`, or `Ctrl+K` off macOS);
+ * `reservedHint` returns a tooltip for a shortcut label the browser reserves.
+ * @param {import("@blastlauncher/client-core").ControllerView} view
+ * @param {{status?: FooterStatus, context?: ExtensionContext, actionsKey?: string, reservedHint?: (label: string) => string}} [options]
+ */
+export declare function render(view: import("@blastlauncher/client-core").ControllerView, options?: {
+    status?: FooterStatus;
+    context?: ExtensionContext;
+    actionsKey?: string;
+    reservedHint?: (label: string) => string;
+}): string;
+/** @param {{title: string, subtitle: string, icon: string, iconUrl?: string, accessory: string}[]} rows @param {number} selected @param {string} query @param {{open?: boolean, query?: string, actions?: {title: string, shortcut?: string}[], selected?: number, toast?: string, status?: FooterStatus}} [panel] */
+export declare function renderRoot(rows: {
+    title: string;
+    subtitle: string;
+    icon: string;
+    iconUrl?: string;
+    accessory: string;
+}[], selected: number, query: string, panel?: {
+    open?: boolean;
+    query?: string;
+    actions?: {
+        title: string;
+        shortcut?: string;
+    }[];
+    selected?: number;
+    toast?: string;
+    status?: FooterStatus;
+}): string;
+/** @param {import("@blastlauncher/protocol/preference-fields").Preference[]} fields @param {Record<string, unknown>} values @param {string} title @param {string[]} unavailable */
+export declare function renderPreferences(fields: import("@blastlauncher/protocol/preference-fields").Preference[], values: Record<string, unknown>, title: string, unavailable?: string[]): string;

package/dist/render.js

@@ -0,0 +1,288 @@
+// @ts-check
+/** @param {unknown} value */
+export function escapeHtml(value) {
+    return String(value ?? "")
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+/**
+ * A footer hint is a real button: clicking it does what its key does. The
+ * label is visible text and the key renders as a keycap.
+ * @param {string} label
+ * @param {string} key
+ * @param {"primary" | "actions" | "back"} action
+ */
+const footerButton = (label, key, action) => `<button type="button" class="footer-key" data-footer="${action}"><span>${escapeHtml(label)}</span><kbd>${escapeHtml(key)}</kbd></button>`;
+/**
+ * A shortcut keycap. A combo the browser keeps for itself is drawn muted with
+ * the hint as its tooltip, so it never looks live when it is not.
+ * @param {"small" | "kbd"} tag @param {string} label @param {(label: string) => string} [hint]
+ */
+export const keycap = (tag, label, hint) => {
+    if (!label)
+        return "";
+    const reserved = hint?.(label);
+    return reserved
+        ? `<${tag} class="reserved" title="${escapeHtml(reserved)}" aria-label="${escapeHtml(`${label}, ${reserved}`)}">${escapeHtml(label)}</${tag}>`
+        : `<${tag}>${escapeHtml(label)}</${tag}>`;
+};
+/** @param {string} label @param {string} action @param {boolean} [selected] */
+const button = (label, action, selected = false) => `<button data-input="${escapeHtml(action)}"${selected ? ' class="selected"' : ""}>${escapeHtml(label)}</button>`;
+/**
+ * Links and images only carry https URLs; images may also inline `data:image`.
+ * Anything else (javascript:, http:, relative) keeps just its visible text.
+ * @param {string} raw @param {boolean} image
+ */
+const safeUrl = (raw, image) => {
+    if (image && /^data:image\/[a-z0-9.+-]+[;,]\S*$/iu.test(raw))
+        return raw;
+    try {
+        return new URL(raw).protocol === "https:" ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Emphasis only ever sees escaped text segments, never generated tags or URLs. @param {string} text */
+const emphasis = (text) => escapeHtml(text)
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    .replace(/(^|[^\w])__([^_]+)__(?!\w)/g, "$1<strong>$2</strong>")
+    .replace(/\*([^*]+)\*/g, "<em>$1</em>")
+    .replace(/(^|[^\w])_([^_]+)_(?!\w)/g, "$1<em>$2</em>");
+/** Tokenize code, links and images first so emphasis cannot rewrite inside them. @param {string} value */
+const renderMarkdownInline = (value) => {
+    let out = "";
+    let last = 0;
+    for (const match of value.matchAll(/`([^`]+)`|(!?)\[([^\]]*)\]\(([^\s)]+)\)/gu)) {
+        out += emphasis(value.slice(last, match.index));
+        last = match.index + match[0].length;
+        const [, code, bang, label = "", url = ""] = match;
+        if (code !== undefined)
+            out += `<code>${escapeHtml(code)}</code>`;
+        else if (bang) {
+            const src = safeUrl(url, true);
+            out += src ? `<img src="${escapeHtml(src)}" alt="${escapeHtml(label)}">` : escapeHtml(label);
+        }
+        else {
+            const href = safeUrl(url, false);
+            out += href
+                ? `<a href="${escapeHtml(href)}" target="_blank" rel="noreferrer noopener">${emphasis(label)}</a>`
+                : emphasis(label);
+        }
+    }
+    return out + emphasis(value.slice(last));
+};
+/** Render the deliberately small, safe markdown subset used by Detail. @param {unknown} markdown */
+export function renderMarkdown(markdown) {
+    const lines = String(markdown ?? "").split(/\r?\n/);
+    const result = [];
+    let list = false;
+    for (const line of lines) {
+        const item = line.match(/^\s*[-*]\s+(.+)$/);
+        if (item) {
+            if (!list) {
+                result.push("<ul>");
+                list = true;
+            }
+            result.push(`<li>${renderMarkdownInline(item[1] ?? "")}</li>`);
+            continue;
+        }
+        if (list) {
+            result.push("</ul>");
+            list = false;
+        }
+        const heading = line.match(/^\s*(#{1,3})\s+(.+)$/);
+        if (heading) {
+            const level = heading[1]?.length ?? 1;
+            result.push(`<h${level}>${renderMarkdownInline(heading[2] ?? "")}</h${level}>`);
+            continue;
+        }
+        if (!line.trim())
+            continue;
+        result.push(`<p>${renderMarkdownInline(line)}</p>`);
+    }
+    if (list)
+        result.push("</ul>");
+    return result.join("");
+}
+/**
+ * @typedef {{text: string, error?: boolean, progress?: boolean, stage?: string}} FooterStatus
+ * @typedef {{extensionTitle: string, commandTitle: string, icon?: string, iconUrl?: string}} ExtensionContext
+ */
+/** @param {FooterStatus} status */
+function statusMarkup(status) {
+    return `<span id="status" role="status" data-error="${status.error ? "true" : "false"}"${status.stage ? ` data-stage="${escapeHtml(status.stage)}"` : ""}>${status.progress ? '<span class="status-spinner" aria-hidden="true"></span>' : ""}${escapeHtml(status.text)}</span>`;
+}
+/** @param {ExtensionContext | undefined} context */
+function breadcrumbMarkup(context) {
+    if (!context)
+        return "";
+    const icon = context.iconUrl
+        ? `<img src="${escapeHtml(context.iconUrl)}" alt="" width="20" height="20" onerror="this.hidden=true">`
+        : escapeHtml(context.icon ?? "⌘");
+    return `<div class="breadcrumb"><span class="breadcrumb-icon" aria-hidden="true">${icon}</span><span>${escapeHtml(context.extensionTitle)}</span><span class="breadcrumb-separator">›</span><span>${escapeHtml(context.commandTitle)}</span></div>`;
+}
+/**
+ * The footer names where the user is, as Raycast does: the extension's icon and
+ * the view's navigation title. It repeats the h1 and breadcrumb, so it is hidden
+ * from assistive tech.
+ * @param {ExtensionContext | undefined} context @param {string} title
+ */
+function footerContextMarkup(context, title) {
+    if (!context)
+        return "";
+    const icon = context.iconUrl
+        ? `<img src="${escapeHtml(context.iconUrl)}" alt="" width="20" height="20" onerror="this.hidden=true">`
+        : escapeHtml(context.icon ?? "⌘");
+    return `<span class="footer-context" aria-hidden="true"><span class="footer-icon">${icon}</span><span class="footer-title">${escapeHtml(title || context.commandTitle)}</span></span>`;
+}
+/**
+ * Toast, HUD and alert: the feedback a command shows over whatever it draws.
+ * @param {import("@blastlauncher/client-core").ControllerView} view
+ * @param {{reservedHint?: (label: string) => string}} [options]
+ */
+export function feedbackMarkup(view, options = {}) {
+    const toast = view.feedback.toast
+        ? `<aside class="toast" data-style="${escapeHtml(view.feedback.toast.style)}"><strong>${escapeHtml(view.feedback.toast.title)}</strong> ${escapeHtml(view.feedback.toast.message)}${view.feedback.toast.actions.map((action, index) => `<button type="button" data-toast-action="${index}">${escapeHtml(action.title)} ${keycap("small", action.shortcut, options.reservedHint)}</button>`).join("")}</aside>`
+        : "";
+    const hud = view.feedback.hud
+        ? `<aside class="hud" role="status">${escapeHtml(view.feedback.hud.title)}</aside>`
+        : "";
+    const alert = view.feedback.alert
+        ? `<section class="alert-backdrop"><dialog open class="alert" role="alertdialog" aria-modal="true" aria-labelledby="alert-title"><h2 id="alert-title">${escapeHtml(view.feedback.alert.title)}</h2><p>${escapeHtml(view.feedback.alert.message)}</p>${view.feedback.alert.rememberUserChoice ? `<label><input id="alert-remember" type="checkbox"${view.feedback.alert.remember ? " checked" : ""}> Remember my choice</label>` : ""}<footer>${view.feedback.alert.dismiss ? `<button type="button" data-alert="dismiss">${escapeHtml(view.feedback.alert.dismiss.title)}</button>` : ""}${view.feedback.alert.primary ? `<button type="button" data-alert="confirm">${escapeHtml(view.feedback.alert.primary.title)}</button>` : ""}</footer></dialog></section>`
+        : "";
+    return `${toast}${hud}${alert}`;
+}
+/**
+ * `actionsKey` labels the Actions footer (`⌘K`, or `Ctrl+K` off macOS);
+ * `reservedHint` returns a tooltip for a shortcut label the browser reserves.
+ * @param {import("@blastlauncher/client-core").ControllerView} view
+ * @param {{status?: FooterStatus, context?: ExtensionContext, actionsKey?: string, reservedHint?: (label: string) => string}} [options]
+ */
+export function render(view, options = {}) {
+    const status = options.status ?? { text: "Ready" };
+    const search = `<input id="search" value="${escapeHtml(view.search.text)}" placeholder="${escapeHtml(view.search.placeholder)}" aria-label="Search">${view.dropdown ? `<button type="button" class="dropdown-trigger" data-dropdown-open aria-label="${escapeHtml(view.dropdown.tooltip || view.dropdown.label)}">${escapeHtml(view.dropdown.label || "Filter")}⌄</button>` : ""}`;
+    const rows = view.rows
+        .map((row) => row.kind === "section"
+        ? `<li class="section-header" data-id="${escapeHtml(row.id)}"><strong>${escapeHtml(row.title)}</strong>${row.count === null ? "" : `<small>${row.count}</small>`}</li>`
+        : `<li${row.selected ? ' class="selected"' : ""} data-id="${escapeHtml(row.id)}"><span class="root-icon"${row.iconTint ? ` style="color:${escapeHtml(row.iconTint)}"` : ""}>${escapeHtml(row.iconLabel)}</span><span class="root-copy"><strong>${escapeHtml(row.title)}</strong>${row.subtitle ? `<small>${escapeHtml(row.subtitle)}</small>` : ""}</span>${row.accessories ? `<span class="root-accessory">${escapeHtml(row.accessories)}</span>` : ""}</li>`)
+        .join("");
+    const grid = (view.grid ?? [])
+        .map((row) => `${row.header ? `<li class="grid-header">${escapeHtml(row.header)}</li>` : ""}<li class="grid-row">${row.cells.map((cell) => `<button type="button" class="grid-cell${cell.selected ? " selected" : ""}" data-id="${escapeHtml(cell.id)}"><span class="grid-content">${escapeHtml(cell.content)}</span><strong>${escapeHtml(cell.title)}</strong><small>${escapeHtml(cell.subtitle)}</small></button>`).join("")}</li>`)
+        .join("");
+    const dropdown = view.dropdown?.open
+        ? `<section class="dropdown-panel" role="dialog" aria-label="${escapeHtml(view.dropdown.label)}"><input id="dropdown-search" data-dropdown-search value="${escapeHtml(view.dropdown.query)}" aria-label="Filter options"><ul>${view.dropdown.options.map((option) => `<li><button type="button" data-dropdown-value="${escapeHtml(option.value)}"${option.selected ? ' class="selected"' : ""}>${escapeHtml(option.title)}${option.current ? " ✓" : ""}</button></li>`).join("")}</ul></section>`
+        : "";
+    const actions = view.actions.open
+        ? `<section class="actions"><strong>${escapeHtml(view.actions.title)}</strong><div class="breadcrumb">${view.actions.breadcrumb.map(escapeHtml).join(" / ")}</div><input id="action-search" value="${escapeHtml(view.actions.query)}" placeholder="Search actions…" aria-label="Action search"><ul>${view.actions.rows.map((row, index) => `<li${row.selected ? ' class="selected"' : ""} data-action-index="${index}">${escapeHtml(row.title)} ${keycap("small", row.shortcut, options.reservedHint)}</li>`).join("")}</ul></section>`
+        : "";
+    const formView = view.form;
+    const form = formView
+        ? `<form class="extension-form">${formView.items
+            .map((item) => {
+            if (item.kind === "separator")
+                return `<hr class="form-separator">`;
+            if (item.kind === "description")
+                return `<p class="form-description">${escapeHtml(item.title)}${item.text ? `: ${escapeHtml(item.text)}` : ""}</p>`;
+            const field = formView.fields.find((candidate) => candidate.id === item.id);
+            if (!field)
+                return "";
+            const label = escapeHtml(field.title || field.label || field.id);
+            const common = `id="field-${escapeHtml(field.id)}" data-field="${escapeHtml(field.id)}"`;
+            const error = field.error
+                ? `<small class="form-error" role="alert">${escapeHtml(field.error)}</small>`
+                : "";
+            if (field.type === "Form.Checkbox")
+                return `<label class="form-field checkbox"><span>${label}</span><input ${common} type="checkbox"${field.checked ? " checked" : ""}></label>`;
+            if (field.type === "Form.Dropdown" || field.type === "Form.TagPicker")
+                return `<label class="form-field"><span>${label}</span><select ${common} ${field.type === "Form.TagPicker" ? "multiple" : ""}>${field.options.map((option) => `<option value="${escapeHtml(option.value)}"${field.selected.some((selected) => selected.value === option.value) ? " selected" : ""}>${escapeHtml(option.title)}</option>`).join("")}</select>${error}</label>`;
+            if (field.type === "Form.DatePicker")
+                return `<label class="form-field"><span>${label}</span><input ${common} type="date" value="${escapeHtml(field.text.slice(0, 10))}">${error}</label>`;
+            if (field.type === "Form.FilePicker")
+                return `<p class="form-unavailable">${label}: not available in the browser</p>`;
+            const area = field.type === "Form.TextArea";
+            return `<label class="form-field"><span>${label}</span>${area ? `<textarea ${common} placeholder="${escapeHtml(field.placeholder)}">${escapeHtml(field.text)}</textarea>` : `<input ${common} type="${field.type === "Form.PasswordField" ? "password" : "text"}"${field.hasValue ? " data-has-value" : ""} value="${escapeHtml(field.text)}" placeholder="${escapeHtml(field.placeholder)}">`}${error}</label>`;
+        })
+            .join("")}${button("Submit", "primary")}</form>`
+        : "";
+    const detail = view.kind === "detail" || (view.kind === "list" && view.detail)
+        ? `<article class="detail">${renderMarkdown(view.detail)}</article>`
+        : "";
+    const noRows = view.kind === "grid"
+        ? (view.grid ?? []).every((row) => row.cells.length === 0)
+        : view.rows.length === 0;
+    const empty = view.empty
+        ? `<p class="empty"><strong>${escapeHtml(view.empty.title)}</strong> ${escapeHtml(view.empty.description)}</p>`
+        : noRows && (view.kind === "list" || view.kind === "grid")
+            ? `<p class="empty">${escapeHtml(view.emptyText || "No results")}</p>`
+            : "";
+    const menu = view.menuBar
+        ? `<nav class="menu-bar" aria-label="${escapeHtml(view.menuBar.tooltip || view.menuBar.title || "Menu")}"><h2>${escapeHtml(view.menuBar.title || "Menu")}</h2><ul>${view.menuBar.rows
+            .map((row) => row.kind === "section"
+            ? `<li class="menu-section"><strong>${escapeHtml(row.title)}</strong></li>`
+            : `<li><button type="button" data-menu-id="${escapeHtml(row.id)}"${row.selected ? ' class="selected"' : ""}${row.disabled ? " disabled" : ""}><span class="menu-icon"${row.iconTint ? ` style="color:${escapeHtml(row.iconTint)}"` : ""}>${escapeHtml(row.iconLabel || "")}</span><span>${escapeHtml(row.title)}</span>${row.subtitle ? `<small>${escapeHtml(row.subtitle)}</small>` : ""}${keycap("kbd", row.shortcut, options.reservedHint)}${row.kind === "submenu" ? " ›" : ""}</button></li>`)
+            .join("")}</ul></nav>`
+        : "";
+    const body = view.kind === "menu-bar"
+        ? menu
+        : view.kind === "form"
+            ? form
+            : view.kind === "detail"
+                ? detail
+                : view.kind === "grid"
+                    ? `<ul class="grid">${grid}</ul>${empty}`
+                    : detail
+                        ? // `isShowingDetail`: the selected item's detail sits beside the rows, as in Raycast.
+                            `<div class="list-split"><div class="list-pane"><ul class="rows">${rows}</ul>${empty}</div>${detail}</div>`
+                        : `<ul class="rows">${rows}</ul>${empty}`;
+    const footer = `<footer>${footerContextMarkup(options.context, view.title)}${statusMarkup(status)}<span class="footer-hints">${view.primary.enabled ? footerButton(view.primary.title, view.primary.shortcut || "↵", "primary") : ""}${footerButton("Actions", options.actionsKey ?? "⌘K", "actions")}</span></footer>`;
+    // Back sits left of the search field, where Raycast puts it in pushed views.
+    const back = `<button type="button" class="back-key" data-footer="back" title="Back (Esc)"><span aria-hidden="true">←</span><span class="visually-hidden">Back</span></button>`;
+    return `<main data-kind="${escapeHtml(view.kind)}" data-loading="${view.loading ? "true" : "false"}" aria-busy="${view.loading ? "true" : "false"}"><header><h1>${escapeHtml(view.title)}</h1><div class="search-line">${back}${breadcrumbMarkup(options.context)}${search}</div></header>${body}${actions}${dropdown}${footer}${feedbackMarkup(view, options)}</main>`;
+}
+/** @param {{title: string, subtitle: string, icon: string, iconUrl?: string, accessory: string}[]} rows @param {number} selected @param {string} query @param {{open?: boolean, query?: string, actions?: {title: string, shortcut?: string}[], selected?: number, toast?: string, status?: FooterStatus}} [panel] */
+export function renderRoot(rows, selected, query, panel = {}) {
+    const options = rows
+        .map((row, index) => `<li id="root-option-${index}" role="option" aria-selected="${index === selected}" data-root-index="${index}"${index === selected ? ' class="selected"' : ""}><span class="root-icon" aria-hidden="true">${row.iconUrl ? `<img src="${escapeHtml(row.iconUrl)}" alt="" width="24" height="24" onerror="this.hidden=true;this.nextElementSibling.hidden=false">` : ""}<span${row.iconUrl ? " hidden" : ""}>${escapeHtml(row.icon)}</span></span><span class="root-copy"><strong>${escapeHtml(row.title)}</strong><small>${escapeHtml(row.subtitle)}</small></span><span class="root-accessory">${escapeHtml(row.accessory)}</span></li>`)
+        .join("");
+    const actions = panel.open
+        ? (panel.actions ?? [])
+            .map((action, index) => `<li id="root-action-${index}" role="option" aria-selected="${index === panel.selected}" data-root-action-index="${index}"${index === panel.selected ? ' class="selected"' : ""}>${escapeHtml(action.title)}${action.shortcut ? ` <small>${escapeHtml(action.shortcut)}</small>` : ""}</li>`)
+            .join("")
+        : "";
+    const actionPanel = panel.open
+        ? `<section class="actions" role="dialog" aria-label="Actions"><strong>Actions</strong><input id="root-action-search" value="${escapeHtml(panel.query ?? "")}" placeholder="Search actions…" aria-label="Search actions" role="combobox" aria-controls="root-actions" aria-activedescendant="${panel.selected !== undefined && panel.selected >= 0 ? `root-action-${panel.selected}` : ""}" autocomplete="off" autofocus><ul id="root-actions" role="listbox" aria-label="Command actions">${actions}</ul></section>`
+        : "";
+    const toast = panel.toast
+        ? `<span role="status" class="root-toast">${escapeHtml(panel.toast)}</span>`
+        : "";
+    const status = panel.status ?? { text: "Ready" };
+    return `<main class="root" data-kind="root" data-loading="false"><header><h1>Blast</h1><input id="root-search" value="${escapeHtml(query)}" placeholder="Search extension commands…" aria-label="Search extension commands" role="combobox" aria-controls="root-options" aria-activedescendant="${selected >= 0 ? `root-option-${selected}` : ""}" autocomplete="off" autofocus></header><ul id="root-options" class="rows root-options" role="listbox" aria-label="Extension commands">${options}</ul>${rows.length === 0 ? '<p class="empty">No matching commands</p>' : ""}<footer>${statusMarkup(status)}<span class="footer-hints">${footerButton("Run Command", "↵", "primary")}${footerButton("Actions", "⌘K", "actions")}${status.error ? footerButton("Back", "Esc", "back") : ""}</span>${toast}</footer>${actionPanel}</main>`;
+}
+/** @param {import("@blastlauncher/protocol/preference-fields").Preference[]} fields @param {Record<string, unknown>} values @param {string} title @param {string[]} unavailable */
+export function renderPreferences(fields, values, title, unavailable = []) {
+    const rows = fields
+        .map((field) => {
+        const value = values[field.name] ?? field.default ?? (field.type === "checkbox" ? false : "");
+        const required = field.required ? " *" : "";
+        const description = field.description
+            ? `<small class="preference-description">${escapeHtml(field.description)}</small>`
+            : "";
+        if (field.type === "checkbox")
+            return `<label class="preference-row"><span>${escapeHtml(field.title)}${required}</span><input name="${escapeHtml(field.name)}" type="checkbox" data-preference="${escapeHtml(field.name)}"${value ? " checked" : ""}>${description}</label>`;
+        if (field.type === "dropdown")
+            return `<label class="preference-row"><span>${escapeHtml(field.title)}${required}</span><select name="${escapeHtml(field.name)}" data-preference="${escapeHtml(field.name)}">${field.data.map((option) => `<option value="${escapeHtml(option.value)}"${String(value) === option.value ? " selected" : ""}>${escapeHtml(option.title)}</option>`).join("")}</select>${description}</label>`;
+        if (field.type === "file" || field.type === "directory" || field.type === "appPicker")
+            return `<div class="preference-row unavailable"><strong>${escapeHtml(field.title)}${required}</strong><span>Needs a file on your computer; this is not available in the browser.</span>${description}</div>`;
+        return `<label class="preference-row"><span>${escapeHtml(field.title)}${required}</span><input name="${escapeHtml(field.name)}" type="${field.type === "password" ? "password" : "text"}" data-preference="${escapeHtml(field.name)}" value="${escapeHtml(String(value))}" placeholder="${escapeHtml(field.placeholder ?? "")}">${description}</label>`;
+    })
+        .join("");
+    const disabled = unavailable.length > 0 ||
+        fields.some((field) => field.required &&
+            field.default === undefined &&
+            (values[field.name] === undefined || values[field.name] === ""));
+    return `<main class="preferences" data-kind="preferences"><header><h1>${escapeHtml(title)}</h1><p class="preference-note">These values stay in this browser only.</p></header><form id="preferences-form"><div class="preference-fields">${rows}</div><footer><span id="preference-error" role="alert"></span><span class="footer-hints"><button type="submit" class="footer-key"${disabled ? " disabled" : ""}><span>Run</span><kbd>↵</kbd></button><button type="button" class="footer-key" data-preference-back><span>Back</span><kbd>Esc</kbd></button></span></footer></form></main>`;
+}

package/dist/runtime-port.d.ts

@@ -0,0 +1,5 @@
+export type RuntimePortRequest = {
+    type: "blast-port-request";
+};
+export declare function isRuntimePortRequest(value: unknown): value is RuntimePortRequest;
+export declare function acceptsRuntimePortRequest(source: unknown, expectedSource: unknown, transferred: boolean, data: unknown): boolean;

package/dist/runtime-port.js

@@ -0,0 +1,8 @@
+export function isRuntimePortRequest(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.type === "blast-port-request");
+}
+export function acceptsRuntimePortRequest(source, expectedSource, transferred, data) {
+    return !transferred && source === expectedSource && isRuntimePortRequest(data);
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,25 @@
+export type SandboxRuntime = {
+    execute(code: string, filename?: string): Promise<unknown>;
+    getVFS(): {
+        mkdirSync(path: string, options?: {
+            recursive?: boolean;
+        }): void;
+        writeFileSync(path: string, data: string | Uint8Array): void;
+    };
+    iframe?: HTMLIFrameElement;
+    terminate?: () => void;
+};
+/** What decides which sandbox a session can adopt: the same page, assets and bundles. */
+export type SandboxOptions = {
+    sandboxUrl: string;
+    assetsUrl?: string | undefined;
+    bundlesUrl?: string | undefined;
+    buildUrl?: string | undefined;
+};
+/** `path` under `assetsUrl`, which defaults to the package's own `assets/` directory. */
+export declare const assetUrl: (options: Pick<SandboxOptions, "assetsUrl">, path: string) => string;
+export declare function disposeSandbox(runtime: SandboxRuntime | undefined): void;
+/** Starts a sandbox now so the next `mount()` with the same options skips that wait. */
+export declare function prewarm(options: SandboxOptions): void;
+/** The warm sandbox for these options if there is one, otherwise a new one. */
+export declare function acquireSandbox(options: SandboxOptions): Promise<SandboxRuntime>;