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

package/dist/capabilities.js

@@ -0,0 +1,288 @@
+const emptyPreferences = () => ({ extension: {}, commands: {} });
+export function createBrowserPreferenceStore(extension, storage) {
+    const key = `blast:${extension}:preferences`;
+    let memory = null;
+    const readRaw = () => {
+        try {
+            return storage?.getItem(key) ?? memory;
+        }
+        catch {
+            return memory;
+        }
+    };
+    const read = () => {
+        const raw = readRaw();
+        if (!raw)
+            return emptyPreferences();
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== "object" || !parsed.extension || !parsed.commands)
+                return emptyPreferences();
+            return { extension: parsed.extension, commands: parsed.commands };
+        }
+        catch {
+            return emptyPreferences();
+        }
+    };
+    const save = (next) => {
+        const value = JSON.stringify(next);
+        memory = value;
+        try {
+            storage?.setItem(key, value);
+        }
+        catch {
+            // The memory copy keeps the demo usable in private browsing.
+        }
+    };
+    return {
+        read,
+        save,
+        values(command) {
+            const current = read();
+            return { ...current.extension, ...current.commands[command] };
+        },
+        update(extensionValues, command, commandValues) {
+            const current = read();
+            save({
+                extension: { ...current.extension, ...extensionValues },
+                commands: {
+                    ...current.commands,
+                    [command]: { ...current.commands[command], ...commandValues },
+                },
+            });
+        },
+    };
+}
+const denial = (message) => ({
+    ok: false,
+    error: { code: "DENIED", message },
+});
+function paramsOf(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function extensionEntry(catalog, name) {
+    return catalog.extensions.find((extension) => extension.name === name);
+}
+const keyFor = (extension, key, internal) => 
+// User keys get their own namespace so a LocalStorage key such as
+// "internal:x" can never collide with Blast's internal or OAuth entries.
+`blast:${extension}:${internal ? "internal" : "user"}:${key}`;
+const decode = (value) => {
+    if (value === null)
+        return null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+};
+const tokenKey = (extension, provider) => keyFor(extension, `oauth:${provider}`, true);
+/** Browser-backed capability handlers. All browser effects are injected for unit tests. */
+export function createBrowserCapabilities(options) {
+    const memory = new Map();
+    let copied = "";
+    const browserStorage = options.storage;
+    const read = (key) => {
+        try {
+            return browserStorage?.getItem(key) ?? memory.get(key) ?? null;
+        }
+        catch {
+            return memory.get(key) ?? null;
+        }
+    };
+    const write = (key, value) => {
+        memory.set(key, value);
+        try {
+            browserStorage?.setItem(key, value);
+        }
+        catch {
+            // Private browsing and disabled storage are expected; memory is the fallback.
+        }
+    };
+    const remove = (key) => {
+        memory.delete(key);
+        try {
+            browserStorage?.removeItem(key);
+        }
+        catch {
+            // The memory value has already been removed.
+        }
+    };
+    const all = (extension) => {
+        const prefix = `blast:${extension}:user:`;
+        const values = new Map();
+        try {
+            for (let index = 0; index < (browserStorage?.length ?? 0); index++) {
+                const storedKey = browserStorage?.key(index);
+                if (storedKey?.startsWith(prefix)) {
+                    const name = storedKey.slice(prefix.length);
+                    const value = browserStorage?.getItem(storedKey);
+                    if (typeof value === "string")
+                        values.set(name, value);
+                }
+            }
+        }
+        catch {
+            // Merge the memory fallback below.
+        }
+        for (const [storedKey, value] of memory) {
+            if (storedKey.startsWith(prefix))
+                values.set(storedKey.slice(prefix.length), value);
+        }
+        const result = {};
+        for (const [name, value] of values) {
+            try {
+                result[name] = JSON.parse(value);
+            }
+            catch {
+                // Ignore values written by another application under our prefix.
+            }
+        }
+        return result;
+    };
+    const clear = (extension) => {
+        const prefix = `blast:${extension}:user:`;
+        const keys = new Set();
+        for (const key of memory.keys())
+            if (key.startsWith(prefix))
+                keys.add(key);
+        try {
+            for (let index = 0; index < (browserStorage?.length ?? 0); index++) {
+                const key = browserStorage?.key(index);
+                if (key?.startsWith(prefix))
+                    keys.add(key);
+            }
+        }
+        catch {
+            // Clear the known memory keys even when browser storage is inaccessible.
+        }
+        for (const key of keys)
+            remove(key);
+    };
+    return async function handle(request, context) {
+        const params = paramsOf(request.params);
+        if (request.name === "storage.get" ||
+            request.name === "storage.set" ||
+            request.name === "storage.remove") {
+            const key = typeof params.key === "string" ? params.key : "";
+            if (!key)
+                return denial(`${request.name} requires a non-empty key`);
+            const storedKey = keyFor(context.extensionName, key, params.scope === "blast:internal");
+            if (request.name === "storage.get")
+                return { ok: true, value: decode(read(storedKey)) };
+            if (request.name === "storage.remove") {
+                remove(storedKey);
+                return { ok: true, value: null };
+            }
+            write(storedKey, JSON.stringify(params.value));
+            return { ok: true, value: null };
+        }
+        if (request.name === "storage.all") {
+            return { ok: true, value: all(context.extensionName) };
+        }
+        if (request.name === "storage.clear") {
+            clear(context.extensionName);
+            return { ok: true, value: null };
+        }
+        if (request.name === "oauth.tokens.get") {
+            return {
+                ok: true,
+                value: decode(read(tokenKey(context.extensionName, String(params.providerId ?? "")))),
+            };
+        }
+        if (request.name === "oauth.tokens.set") {
+            write(tokenKey(context.extensionName, String(params.providerId ?? "")), JSON.stringify(params.tokens));
+            return { ok: true, value: null };
+        }
+        if (request.name === "oauth.tokens.remove") {
+            remove(tokenKey(context.extensionName, String(params.providerId ?? "")));
+            return { ok: true, value: null };
+        }
+        if (request.name === "clipboard.copy" || request.name === "clipboard.paste") {
+            const text = typeof params.text === "string" ? params.text : "";
+            copied = text;
+            try {
+                await options.clipboard?.writeText?.(text);
+            }
+            catch {
+                // The session fallback still makes read useful when permission is denied.
+            }
+            if (request.name === "clipboard.paste")
+                options.status?.("Copied — paste with ⌘V");
+            else
+                options.status?.("Copied");
+            return { ok: true, value: null };
+        }
+        if (request.name === "clipboard.read") {
+            try {
+                const text = await options.clipboard?.readText?.();
+                if (typeof text === "string")
+                    return { ok: true, value: { text } };
+            }
+            catch {
+                // Fall back to the last value Blast copied in this session.
+            }
+            return { ok: true, value: { text: copied } };
+        }
+        if (request.name === "clipboard.clear") {
+            copied = "";
+            return { ok: true, value: null };
+        }
+        if (request.name === "open.url") {
+            const url = typeof params.url === "string" ? params.url : "";
+            options.openUrl?.(url);
+            return { ok: true, value: null };
+        }
+        if (request.name === "command.metadata") {
+            const command = extensionEntry(options.catalog, context.extensionName)?.commands.find((item) => item.name === context.commandName);
+            return command
+                ? { ok: true, value: null }
+                : denial("This command is not in the browser catalog");
+        }
+        if (request.name === "command.launch") {
+            const targetExtension = String(params.extensionName ?? context.extensionName);
+            if (targetExtension !== context.extensionName)
+                return denial("The browser demo can launch commands only from the current extension");
+            const command = typeof params.name === "string" ? params.name : "";
+            if (!extensionEntry(options.catalog, targetExtension)?.commands.some((item) => item.name === command))
+                return denial("That command is not in the browser catalog");
+            // A background launch is a host request, not a second foreground session.
+            // Running it through `launchCommand` would replace the port the caller is
+            // waiting on (one-thing/remove-one-thing then never finishes), and a
+            // browser tab has no background process or menu bar to update anyway.
+            if (params.type === "background") {
+                options.status?.(`Background command accepted: ${command}`);
+                return { ok: true, value: null };
+            }
+            if (!options.launchCommand)
+                return denial("Command launching is unavailable in this browser session");
+            await options.launchCommand(context.source, command);
+            return { ok: true, value: null };
+        }
+        if (request.name === "oauth.authorize")
+            return denial("OAuth authorization needs a host redirect and is unavailable in a browser tab");
+        if (request.name === "preferences.open") {
+            const scope = params.scope;
+            if (scope !== "extension" && scope !== "command")
+                return denial("preferences.open requires an extension or command scope");
+            options.openPreferences?.(scope, context);
+            return { ok: true, value: null };
+        }
+        if (request.name === "applications.list")
+            return { ok: true, value: [] };
+        if (request.name === "applications.default" || request.name === "applications.frontmost")
+            return denial("Applications are unavailable in a browser tab");
+        if (request.name.startsWith("applications."))
+            return denial("Applications are unavailable in a browser tab");
+        if (request.name.startsWith("selection."))
+            return denial("Selection is unavailable in a browser tab");
+        if (request.name.startsWith("window."))
+            return denial("Window management is unavailable in a browser tab");
+        if (request.name.startsWith("ai."))
+            return denial("AI access is unavailable in a browser tab");
+        return denial(`${request.name} is not supported by the browser demo`);
+    };
+}

package/dist/custom-element.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Defines `<blast-extension extension="raycast/extensions/name" sandbox-url="…">`
+ * for pages that prefer declarative embedding. Optional attributes: `source`,
+ * `command`, `assets-url`, `theme`, and the booleans `root` and `fixtures`.
+ */
+export declare function defineBlastExtension(tag?: string): void;

package/dist/custom-element.js

@@ -0,0 +1,36 @@
+import { startSession } from "./session.js";
+/**
+ * Defines `<blast-extension extension="raycast/extensions/name" sandbox-url="…">`
+ * for pages that prefer declarative embedding. Optional attributes: `source`,
+ * `command`, `assets-url`, `theme`, and the booleans `root` and `fixtures`.
+ */
+export function defineBlastExtension(tag = "blast-extension") {
+    if (customElements.get(tag))
+        return;
+    customElements.define(tag, class extends HTMLElement {
+        #session;
+        connectedCallback() {
+            const options = {
+                sandboxUrl: this.getAttribute("sandbox-url") ?? "/sandbox/",
+                root: this.hasAttribute("root"),
+                fixtures: this.hasAttribute("fixtures"),
+            };
+            for (const [attribute, key] of [
+                ["extension", "extension"],
+                ["source", "source"],
+                ["command", "command"],
+                ["assets-url", "assetsUrl"],
+                ["theme", "theme"],
+            ]) {
+                const value = this.getAttribute(attribute);
+                if (value)
+                    options[key] = value;
+            }
+            this.#session = startSession(this, options);
+        }
+        disconnectedCallback() {
+            this.#session?.close();
+            this.#session = undefined;
+        }
+    });
+}

package/dist/default-renderer.d.ts

@@ -0,0 +1,27 @@
+import type { ControllerInput, ControllerView } from "@blastlauncher/client-core";
+export type WebStatus = {
+    text: string;
+    error?: boolean;
+    progress?: boolean;
+};
+export type WebView = ControllerView | {
+    type: "loading";
+    extension?: string;
+    command?: string;
+} | {
+    type: "error";
+    message: string;
+};
+export type ViewInput = (input: ControllerInput) => void;
+export type Theme = string | Record<string, string>;
+/**
+ * Draws views with the shared HTML renderer and turns clicks, typing and keys
+ * into controller input. Everything is scoped to `element`.
+ */
+export declare function createDefaultRenderer(element: HTMLElement, send: ViewInput, options?: {
+    theme?: Theme;
+    actionsKey?: string;
+}): {
+    draw(next: WebView, status: WebStatus): void;
+    destroy(): void;
+};

package/dist/default-renderer.js

@@ -0,0 +1,145 @@
+import { defaultStyles } from "./default-styles.js";
+import { render } from "./render.js";
+const STYLE_ID = "blast-web-styles";
+function installStyles(root) {
+    if (root.getElementById(STYLE_ID))
+        return;
+    const style = root.createElement("style");
+    style.id = STYLE_ID;
+    style.textContent = defaultStyles;
+    root.head.prepend(style);
+}
+const field = (target) => target instanceof HTMLElement ? target.closest("[data-field]") : null;
+/**
+ * Draws views with the shared HTML renderer and turns clicks, typing and keys
+ * into controller input. Everything is scoped to `element`.
+ */
+export function createDefaultRenderer(element, send, options = {}) {
+    installStyles(element.ownerDocument);
+    element.classList.add("blast-web");
+    if (typeof options.theme === "string")
+        element.dataset.theme = options.theme;
+    else if (options.theme)
+        for (const [key, value] of Object.entries(options.theme))
+            element.style.setProperty(key, value);
+    if (!element.hasAttribute("tabindex"))
+        element.tabIndex = 0;
+    let view;
+    const onKeydown = (event) => {
+        if (!view)
+            return;
+        const target = event.target;
+        const typing = target instanceof HTMLTextAreaElement;
+        if (event.key === "ArrowDown")
+            send({ type: "move", direction: "down" });
+        else if (event.key === "ArrowUp")
+            send({ type: "move", direction: "up" });
+        else if (event.key === "Enter" && (event.metaKey || event.ctrlKey))
+            send(view.kind === "form" ? { type: "submit" } : { type: "primary" });
+        else if (event.key === "Enter" && !typing && !(target instanceof HTMLButtonElement))
+            send(view.kind === "form" ? { type: "submit" } : { type: "primary" });
+        else if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k")
+            send({ type: view.actions.open ? "closeActions" : "openActions" });
+        else if (event.key === "Escape") {
+            if (!view.actions.open && !view.dropdown?.open && view.search.text)
+                send({ type: "search", text: "" });
+            else
+                send({ type: "back" });
+        }
+        else
+            return;
+        event.preventDefault();
+    };
+    const onInput = (event) => {
+        const target = event.target;
+        const formField = field(target);
+        if (target.id === "search")
+            send({ type: "search", text: target.value });
+        else if (target.id === "action-search")
+            send({ type: "actionsQuery", text: target.value });
+        else if (target.hasAttribute("data-dropdown-search"))
+            send({ type: "dropdownQuery", text: target.value });
+        else if (formField?.dataset.field)
+            send(target.type === "checkbox"
+                ? { type: "toggle", id: formField.dataset.field }
+                : { type: "setValue", id: formField.dataset.field, value: target.value });
+    };
+    const onClick = (event) => {
+        const target = event.target;
+        const footer = target.closest("[data-footer]")?.dataset.footer;
+        if (footer === "primary")
+            return send({ type: "primary" });
+        if (footer === "actions")
+            return send({ type: "openActions" });
+        if (footer === "back")
+            return send({ type: "back" });
+        if (target.closest("[data-dropdown-open]"))
+            return send({ type: "openDropdown" });
+        const action = target.closest("[data-action-index]");
+        if (action && view?.actions.open) {
+            const delta = Number(action.dataset.actionIndex) - view.actions.selectedIndex;
+            for (let step = 0; step < Math.abs(delta); step++)
+                send({ type: "move", direction: delta > 0 ? "down" : "up" });
+            return send({ type: "primary" });
+        }
+        const item = target.closest("[data-id], [data-menu-id]");
+        if (item)
+            send({ type: "select", id: item.dataset.id ?? item.dataset.menuId ?? "" });
+    };
+    const onSubmit = (event) => {
+        event.preventDefault();
+        send({ type: "submit" });
+    };
+    element.addEventListener("keydown", onKeydown);
+    element.addEventListener("input", onInput);
+    element.addEventListener("click", onClick);
+    element.addEventListener("submit", onSubmit);
+    /** Redrawing replaces the DOM, so put the caret back where the visitor left it. */
+    const withFocus = (draw) => {
+        const active = element.contains(document.activeElement)
+            ? document.activeElement
+            : undefined;
+        const key = active?.id || active?.dataset.field;
+        const selection = active ? [active.selectionStart, active.selectionEnd] : undefined;
+        draw();
+        const next = (key
+            ? element.querySelector(`#${CSS.escape(key)}, [data-field="${key}"]`)
+            : null) ?? (active ? null : element.querySelector("#search"));
+        if (!next)
+            return;
+        next.focus({ preventScroll: true });
+        if (selection?.[0] != null && selection[1] != null)
+            next.setSelectionRange?.(selection[0], selection[1]);
+    };
+    return {
+        draw(next, status) {
+            if ("type" in next && next.type === "loading") {
+                view = undefined;
+                element.innerHTML = `<p role="status" aria-busy="true"></p>`;
+                element.firstElementChild.textContent = status.text || "Loading extension…";
+                return;
+            }
+            if ("type" in next && next.type === "error") {
+                view = undefined;
+                element.innerHTML = `<p role="alert" data-blast-error></p>`;
+                element.firstElementChild.textContent = next.message;
+                return;
+            }
+            view = next;
+            withFocus(() => {
+                element.innerHTML = render(view, {
+                    status,
+                    ...(options.actionsKey ? { actionsKey: options.actionsKey } : {}),
+                });
+            });
+        },
+        destroy() {
+            element.removeEventListener("keydown", onKeydown);
+            element.removeEventListener("input", onInput);
+            element.removeEventListener("click", onClick);
+            element.removeEventListener("submit", onSubmit);
+            element.classList.remove("blast-web");
+            element.replaceChildren();
+        },
+    };
+}

package/dist/default-styles.d.ts

@@ -0,0 +1,2 @@
+/** Default look of the built-in renderer; every colour is a `--blast-*` custom property. */
+export declare const defaultStyles = "\n.blast-web{--blast-bg:#fcfcfc;--blast-fg:#171717;--blast-muted:#646464;--blast-line:#e2e2e2;--blast-selection:#ededed;--blast-accent:#ff6338;--blast-error:#d93036;--blast-radius:12px;font:14px/1.4 system-ui,sans-serif;background:var(--blast-bg);color:var(--blast-fg);border:1px solid var(--blast-line);border-radius:var(--blast-radius);overflow:hidden}\n.blast-web[data-theme=dark]{--blast-bg:#161616;--blast-fg:#f2f2f2;--blast-muted:#a0a0a0;--blast-line:#343434;--blast-selection:#282828}\n@media(prefers-color-scheme:dark){.blast-web:not([data-theme=light]){--blast-bg:#161616;--blast-fg:#f2f2f2;--blast-muted:#a0a0a0;--blast-line:#343434;--blast-selection:#282828}}\n.blast-web main{display:flex;flex-direction:column;min-height:16rem}\n.blast-web header{padding:.5rem .75rem;border-bottom:1px solid var(--blast-line)}\n.blast-web h1{margin:0 0 .25rem;font-size:12px;font-weight:600;color:var(--blast-muted)}\n.blast-web .search-line{display:flex;gap:.5rem;align-items:center}\n.blast-web input,.blast-web textarea,.blast-web select{font:inherit;color:inherit;background:transparent;border:0;outline:0}\n.blast-web #search,.blast-web .search-line input{flex:1;padding:.25rem 0}\n.blast-web ul{margin:0;padding:.25rem;list-style:none;flex:1;overflow:auto}\n.blast-web li{display:flex;gap:.5rem;align-items:center;padding:.4rem .5rem;border-radius:8px}\n.blast-web li.selected,.blast-web .selected{background:var(--blast-selection)}\n.blast-web .section-header{color:var(--blast-muted);font-size:12px}\n.blast-web small,.blast-web .root-accessory{color:var(--blast-muted)}\n.blast-web .root-copy{flex:1;display:flex;gap:.5rem;align-items:baseline}\n.blast-web footer{display:flex;gap:.75rem;align-items:center;padding:.4rem .75rem;border-top:1px solid var(--blast-line);color:var(--blast-muted)}\n.blast-web footer #status{flex:1}\n.blast-web #status[data-error=true],.blast-web [data-blast-error]{color:var(--blast-error)}\n.blast-web button{font:inherit;color:inherit;background:transparent;border:0;border-radius:6px;cursor:pointer}\n.blast-web kbd{font:inherit;font-size:11px;padding:0 .3rem;margin-left:.25rem;border:1px solid var(--blast-line);border-radius:4px}\n.blast-web .actions,.blast-web .dropdown-panel{margin:.5rem;padding:.5rem;border:1px solid var(--blast-line);border-radius:8px;background:var(--blast-bg)}\n.blast-web .empty,.blast-web [role=status]:not(#status){padding:1rem;color:var(--blast-muted)}\n.blast-web .detail,.blast-web .extension-form{padding:.75rem}\n.blast-web .form-field{display:flex;flex-direction:column;gap:.25rem;margin-bottom:.5rem}\n.blast-web .visually-hidden{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)}\n";

package/dist/default-styles.js

@@ -0,0 +1,28 @@
+/** Default look of the built-in renderer; every colour is a `--blast-*` custom property. */
+export const defaultStyles = `
+.blast-web{--blast-bg:#fcfcfc;--blast-fg:#171717;--blast-muted:#646464;--blast-line:#e2e2e2;--blast-selection:#ededed;--blast-accent:#ff6338;--blast-error:#d93036;--blast-radius:12px;font:14px/1.4 system-ui,sans-serif;background:var(--blast-bg);color:var(--blast-fg);border:1px solid var(--blast-line);border-radius:var(--blast-radius);overflow:hidden}
+.blast-web[data-theme=dark]{--blast-bg:#161616;--blast-fg:#f2f2f2;--blast-muted:#a0a0a0;--blast-line:#343434;--blast-selection:#282828}
+@media(prefers-color-scheme:dark){.blast-web:not([data-theme=light]){--blast-bg:#161616;--blast-fg:#f2f2f2;--blast-muted:#a0a0a0;--blast-line:#343434;--blast-selection:#282828}}
+.blast-web main{display:flex;flex-direction:column;min-height:16rem}
+.blast-web header{padding:.5rem .75rem;border-bottom:1px solid var(--blast-line)}
+.blast-web h1{margin:0 0 .25rem;font-size:12px;font-weight:600;color:var(--blast-muted)}
+.blast-web .search-line{display:flex;gap:.5rem;align-items:center}
+.blast-web input,.blast-web textarea,.blast-web select{font:inherit;color:inherit;background:transparent;border:0;outline:0}
+.blast-web #search,.blast-web .search-line input{flex:1;padding:.25rem 0}
+.blast-web ul{margin:0;padding:.25rem;list-style:none;flex:1;overflow:auto}
+.blast-web li{display:flex;gap:.5rem;align-items:center;padding:.4rem .5rem;border-radius:8px}
+.blast-web li.selected,.blast-web .selected{background:var(--blast-selection)}
+.blast-web .section-header{color:var(--blast-muted);font-size:12px}
+.blast-web small,.blast-web .root-accessory{color:var(--blast-muted)}
+.blast-web .root-copy{flex:1;display:flex;gap:.5rem;align-items:baseline}
+.blast-web footer{display:flex;gap:.75rem;align-items:center;padding:.4rem .75rem;border-top:1px solid var(--blast-line);color:var(--blast-muted)}
+.blast-web footer #status{flex:1}
+.blast-web #status[data-error=true],.blast-web [data-blast-error]{color:var(--blast-error)}
+.blast-web button{font:inherit;color:inherit;background:transparent;border:0;border-radius:6px;cursor:pointer}
+.blast-web kbd{font:inherit;font-size:11px;padding:0 .3rem;margin-left:.25rem;border:1px solid var(--blast-line);border-radius:4px}
+.blast-web .actions,.blast-web .dropdown-panel{margin:.5rem;padding:.5rem;border:1px solid var(--blast-line);border-radius:8px;background:var(--blast-bg)}
+.blast-web .empty,.blast-web [role=status]:not(#status){padding:1rem;color:var(--blast-muted)}
+.blast-web .detail,.blast-web .extension-form{padding:.75rem}
+.blast-web .form-field{display:flex;flex-direction:column;gap:.25rem;margin-bottom:.5rem}
+.blast-web .visually-hidden{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)}
+`;

package/dist/extension-files.d.ts

@@ -0,0 +1,21 @@
+import type { BrowserFetch } from "./browser-install.js";
+export type BrowserFile = string | Uint8Array;
+export type FetchedExtension = {
+    files: Map<string, BrowserFile>;
+    manifest: Record<string, unknown>;
+    lockfile?: string;
+    root: string;
+};
+export type FetchExtensionOptions = {
+    fetch?: BrowserFetch;
+    /** Base URL of `<name>/__files` fixture listings; omit to always use GitHub. */
+    fixturesUrl?: string | undefined;
+};
+/** `raycast/extensions/<name>` is the embedding shorthand for a Store extension. */
+export declare function resolveExtensionSource(value: string): string;
+/** Fetches an extension's files from a local fixture server or GitHub. */
+export declare function fetchExtensionFiles(source: string, options?: FetchExtensionOptions): Promise<FetchedExtension>;
+/** The source file a command's bundle starts from. */
+export declare function commandEntry(files: Map<string, BrowserFile>, name: string): string;
+/** Command names a manifest declares, in order. */
+export declare function manifestCommands(manifest: Record<string, unknown>): string[];

package/dist/extension-files.js

@@ -0,0 +1,86 @@
+import { canUseLocalFixture, isTextExtension, parseExtensionSource } from "./source.js";
+const githubApiPath = (path) => path
+    .split("/")
+    .map((part) => encodeURIComponent(part))
+    .join("/");
+const rateLimited = (response) => response.status === 403 && response.headers.get("x-ratelimit-remaining") === "0";
+/** `raycast/extensions/<name>` is the embedding shorthand for a Store extension. */
+export function resolveExtensionSource(value) {
+    const match = /^raycast\/extensions\/([^/]+)$/.exec(value.trim());
+    return match?.[1] ?? value;
+}
+/** Fetches an extension's files from a local fixture server or GitHub. */
+export async function fetchExtensionFiles(source, options = {}) {
+    const request = options.fetch ?? ((input, init) => fetch(input, init));
+    const parsed = parseExtensionSource(resolveExtensionSource(source));
+    const files = new Map();
+    const read = async (path, url) => {
+        const response = await request(url);
+        if (!response.ok) {
+            if (rateLimited(response))
+                throw new Error("GitHub API rate limit reached; try again later or use a local fixture");
+            throw new Error(`Unable to fetch ${path} (${response.status})`);
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        files.set(`/${path}`, isTextExtension(path) ? new TextDecoder().decode(bytes) : bytes);
+    };
+    let root = parsed.path;
+    let paths = [];
+    if (canUseLocalFixture(parsed, options.fixturesUrl !== undefined)) {
+        const localBase = `${options.fixturesUrl}${encodeURIComponent(parsed.path.replace(/^extensions\//, ""))}`;
+        const listing = await request(`${localBase}/__files`).catch(() => undefined);
+        if (listing?.ok) {
+            paths = (await listing.json());
+            root = parsed.path.replace(/^extensions\//, "");
+            for (const path of paths)
+                await read(path, `${localBase}/${path}`);
+        }
+    }
+    if (paths.length === 0) {
+        const list = async (path) => {
+            const response = await request(`https://api.github.com/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/contents/${githubApiPath(path)}?ref=${encodeURIComponent(parsed.ref)}`, { headers: { Accept: "application/vnd.github+json" } });
+            if (!response.ok) {
+                if (rateLimited(response))
+                    throw new Error("GitHub API rate limit reached; try again later or use a local fixture");
+                throw new Error(`Unable to list GitHub extension files (${response.status})`);
+            }
+            const entries = (await response.json());
+            const result = [];
+            for (const entry of entries) {
+                if (!entry.path || entry.path.split("/").includes("node_modules"))
+                    continue;
+                if (entry.type === "dir")
+                    result.push(...(await list(entry.path)));
+                else if (entry.type === "file")
+                    result.push(entry.path.slice(parsed.path.length + 1));
+            }
+            return result;
+        };
+        paths = await list(parsed.path);
+        if (!paths.includes("package.json"))
+            throw new Error("Extension package.json was not found");
+        for (const path of paths)
+            await read(path, `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/${encodeURIComponent(parsed.ref)}/${parsed.path}/${path}`);
+    }
+    const manifest = JSON.parse(String(files.get("/package.json")));
+    const lockfile = files.get("/package-lock.json");
+    return { files, manifest, root, ...(typeof lockfile === "string" ? { lockfile } : {}) };
+}
+/** The source file a command's bundle starts from. */
+export function commandEntry(files, name) {
+    for (const extension of ["tsx", "ts", "jsx", "js"]) {
+        const path = `/src/${name}.${extension}`;
+        if (files.has(path))
+            return path;
+    }
+    if (files.has("/src/index.tsx"))
+        return "/src/index.tsx";
+    throw new Error(`Command source not found for ${name}`);
+}
+/** Command names a manifest declares, in order. */
+export function manifestCommands(manifest) {
+    const commands = manifest.commands;
+    return Array.isArray(commands)
+        ? commands.flatMap((command) => typeof command?.name === "string" ? [command.name] : [])
+        : [];
+}

package/dist/handlers.d.ts

@@ -0,0 +1,18 @@
+import type { BrowserStorage, CapabilityContext, CapabilityRequest, CapabilityResult, ClipboardBridge } from "./capabilities.js";
+/**
+ * How the embedding page answers the capabilities an extension asks for.
+ * Anything left out falls back to the package default (decision 0015).
+ */
+export type WebHandlers = {
+    storage?: BrowserStorage;
+    clipboard?: ClipboardBridge;
+    openUrl?: (url: string) => void;
+    /**
+     * Answers any capability before the defaults see it: return a result to
+     * grant it, or `{ ok: false, error: { code: "DENIED", ... } }` to deny it.
+     * Return undefined to let the default handler answer.
+     */
+    capability?: (request: CapabilityRequest, context: CapabilityContext) => CapabilityResult | undefined | Promise<CapabilityResult | undefined>;
+};
+/** localStorage, the Clipboard API (the browser asks the user) and a new tab for URLs. */
+export declare function createDefaultHandlers(): WebHandlers;