@blastlauncher/web 3.0.0-alpha.0 → 3.0.0-alpha.3

package/dist/bundles.d.ts

@@ -3,6 +3,10 @@ import type { CommandMode } from "@blastlauncher/protocol";
 export type CatalogArgument = {
     name: string;
     required: boolean;
+    /** The manifest argument type (`text`, `password`, `dropdown`). */
+    type?: string;
+    /** A dropdown argument's option values, in order. */
+    values?: string[];
 };
 export type CatalogManifest = {
     name: string;

package/dist/bundles.js

@@ -92,7 +92,15 @@ export function parseBundleIndex(value) {
                     const entry = argument;
                     if (!entry || typeof entry.name !== "string" || typeof entry.required !== "boolean")
                         throw new Error(`Invalid bundle manifest argument: ${key}/${name}`);
-                    return { name: entry.name, required: entry.required };
+                    const values = Array.isArray(entry.values)
+                        ? entry.values.filter((option) => typeof option === "string")
+                        : [];
+                    return {
+                        name: entry.name,
+                        required: entry.required,
+                        ...(typeof entry.type === "string" ? { type: entry.type } : {}),
+                        ...(values.length ? { values } : {}),
+                    };
                 });
             }
             manifest = {

package/dist/capabilities.d.ts

@@ -42,7 +42,8 @@ export type BrowserCapabilityOptions = {
     storage?: BrowserStorage;
     clipboard?: ClipboardBridge;
     openUrl?: (url: string) => void;
-    launchCommand?: (source: string, command: string) => Promise<void>;
+    /** `args` are the launched command's manifest argument values. */
+    launchCommand?: (source: string, command: string, args: Record<string, string>) => Promise<void>;
     status?: (message: string, error?: boolean) => void;
     openPreferences?: (scope: "extension" | "command", context: CapabilityContext) => void;
 };

package/dist/capabilities.js

@@ -259,7 +259,12 @@ export function createBrowserCapabilities(options) {
             }
             if (!options.launchCommand)
                 return denial("Command launching is unavailable in this browser session");
-            await options.launchCommand(context.source, command);
+            const args = {};
+            if (params.arguments && typeof params.arguments === "object")
+                for (const [name, value] of Object.entries(params.arguments))
+                    if (typeof value === "string")
+                        args[name] = value;
+            await options.launchCommand(context.source, command, args);
             return { ok: true, value: null };
         }
         if (request.name === "oauth.authorize")

package/dist/extension-files.d.ts

@@ -15,6 +15,23 @@ export type FetchExtensionOptions = {
 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>;
+/**
+ * Where an extension file lives under the command's assets directory, or
+ * undefined when the bundle already holds it: `assets/*` sit at its top,
+ * `src/` data files (not code) keep their place below it, and other files
+ * (`package.json`) keep their path.
+ */
+export declare function assetRelativePath(path: string): string | undefined;
+/** An extension's files keyed by `assetRelativePath`, as prebuilt bundles list them. */
+export declare function extensionAssets(files: ReadonlyMap<string, BrowserFile>): Array<[string, BrowserFile]>;
+/**
+ * The files a command's sandbox needs before it runs: the extension's assets
+ * (keyed by `assetRelativePath`) under `assetsPath` (decision 0013), its
+ * `package.json` also one level up (bundled code reads
+ * `__dirname/../package.json`), and markers that create the assets and support
+ * directories.
+ */
+export declare function sandboxFiles(assets: Iterable<readonly [string, BrowserFile]>, assetsPath: string, supportPath: string): Array<[string, BrowserFile]>;
 /** 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. */

package/dist/extension-files.js

@@ -66,6 +66,49 @@ export async function fetchExtensionFiles(source, options = {}) {
     const lockfile = files.get("/package-lock.json");
     return { files, manifest, root, ...(typeof lockfile === "string" ? { lockfile } : {}) };
 }
+/**
+ * Where an extension file lives under the command's assets directory, or
+ * undefined when the bundle already holds it: `assets/*` sit at its top,
+ * `src/` data files (not code) keep their place below it, and other files
+ * (`package.json`) keep their path.
+ */
+export function assetRelativePath(path) {
+    if (path.includes("/node_modules/"))
+        return undefined;
+    if (path.startsWith("/assets/"))
+        return path.slice("/assets/".length) || undefined;
+    if (path.startsWith("/src/"))
+        return /\.(?:cjs|css|html?|js|jsx|mjs|ts|tsx)$/iu.test(path)
+            ? undefined
+            : path.slice("/src/".length);
+    return path.replace(/^\//u, "") || undefined;
+}
+/** An extension's files keyed by `assetRelativePath`, as prebuilt bundles list them. */
+export function extensionAssets(files) {
+    return [...files].flatMap(([path, value]) => {
+        const relative = assetRelativePath(path);
+        return relative ? [[relative, value]] : [];
+    });
+}
+/**
+ * The files a command's sandbox needs before it runs: the extension's assets
+ * (keyed by `assetRelativePath`) under `assetsPath` (decision 0013), its
+ * `package.json` also one level up (bundled code reads
+ * `__dirname/../package.json`), and markers that create the assets and support
+ * directories.
+ */
+export function sandboxFiles(assets, assetsPath, supportPath) {
+    const result = [
+        [`${supportPath}/.keep`, ""],
+        [`${assetsPath}/.keep`, ""],
+    ];
+    for (const [relative, value] of assets) {
+        result.push([`${assetsPath}/${relative}`, value]);
+        if (relative === "package.json")
+            result.push([`${assetsPath.slice(0, assetsPath.lastIndexOf("/"))}/package.json`, value]);
+    }
+    return result;
+}
 /** The source file a command's bundle starts from. */
 export function commandEntry(files, name) {
     for (const extension of ["tsx", "ts", "jsx", "js"]) {

package/dist/sandbox.d.ts

@@ -18,6 +18,15 @@ export type SandboxOptions = {
 };
 /** `path` under `assetsUrl`, which defaults to the package's own `assets/` directory. */
 export declare const assetUrl: (options: Pick<SandboxOptions, "assetsUrl">, path: string) => string;
+/**
+ * Writes files into the sandbox's own file system before a command runs.
+ * Writes to `getVFS()` never reach it (the sandbox page keeps its own
+ * VirtualFS, and almostnode's sync would decode binary files as text), and a
+ * message posted to the frame right after `createRuntime` can still land on
+ * its initial `about:blank`. `execute` is the channel every command already
+ * runs through, so the files go as one script, base64 for exact bytes.
+ */
+export declare function writeSandboxFiles(runtime: Pick<SandboxRuntime, "execute">, files: ReadonlyArray<readonly [string, string | Uint8Array]>): Promise<void>;
 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;

package/dist/sandbox.js

@@ -14,6 +14,30 @@ export const assetUrl = (options, path) => new URL(path, options.assetsUrl
     ? new URL(options.assetsUrl, globalThis.location?.href)
     : packagedAssets()).toString();
 const keyOf = (options) => [options.sandboxUrl, assetUrl(options, "./"), options.bundlesUrl, options.buildUrl].join("\n");
+const base64 = (value) => {
+    const bytes = typeof value === "string" ? new TextEncoder().encode(value) : value;
+    let binary = "";
+    for (let start = 0; start < bytes.length; start += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));
+    return btoa(binary);
+};
+/**
+ * Writes files into the sandbox's own file system before a command runs.
+ * Writes to `getVFS()` never reach it (the sandbox page keeps its own
+ * VirtualFS, and almostnode's sync would decode binary files as text), and a
+ * message posted to the frame right after `createRuntime` can still land on
+ * its initial `about:blank`. `execute` is the channel every command already
+ * runs through, so the files go as one script, base64 for exact bytes.
+ */
+export async function writeSandboxFiles(runtime, files) {
+    const encoded = JSON.stringify(files.map(([path, value]) => [path, base64(value)]));
+    await runtime.execute(`const fs = require("fs");
+for (const [path, data] of ${encoded}) {
+  fs.mkdirSync(path.slice(0, path.lastIndexOf("/")) || "/", { recursive: true });
+  fs.writeFileSync(path, Buffer.from(data, "base64"));
+}
+module.exports = null;`, "/blast/write-files.cjs");
+}
 export function disposeSandbox(runtime) {
     try {
         runtime?.terminate?.();

package/dist/session.d.ts

@@ -26,6 +26,8 @@ export type WebMountOptions = {
     fixtures?: boolean;
     /** Show the extension's commands as the engine root view instead of running one. */
     root?: boolean;
+    /** Manifest argument values for `command` (`LaunchProps.arguments`). */
+    arguments?: Record<string, string>;
     /** Preference values, applied over the manifest defaults and saved values. */
     preferences?: PreferenceValues;
     /** Prebuilt bundle index (usually `/bundles.json`) used before fetching GitHub sources. */

package/dist/session.js

@@ -12,13 +12,13 @@ import { installForBrowser } from "./browser-install.js";
 import { aliases } from "./bundle-config.js";
 import { createBrowserCapabilities, createBrowserPreferenceStore, } from "./capabilities.js";
 import { createDefaultRenderer, } from "./default-renderer.js";
-import { commandEntry, fetchExtensionFiles, manifestCommands } from "./extension-files.js";
+import { commandEntry, extensionAssets, fetchExtensionFiles, manifestCommands, sandboxFiles, } from "./extension-files.js";
 import { createDefaultHandlers } from "./handlers.js";
 import { createLaunchGeneration, withLaunchTimeout } from "./launch.js";
 import { missingPreferences, parsePreferences, preferenceDefaults, preferenceFields, } from "@blastlauncher/protocol/preference-fields";
 import { loadPrebuiltCommand } from "./prebuilt.js";
 import { acceptsRuntimePortRequest } from "./runtime-port.js";
-import { acquireSandbox, assetUrl, disposeSandbox } from "./sandbox.js";
+import { acquireSandbox, assetUrl, disposeSandbox, writeSandboxFiles, } from "./sandbox.js";
 const initialized = new WeakSet();
 const LAUNCH_TIMEOUT_MS = 30_000;
 const RUNTIME_ENTRY = "/packages/web/sandbox/runtime-entry.ts";
@@ -86,7 +86,7 @@ export function startSession(element, options) {
         const result = root.input(value);
         for (const effect of result.effects)
             if (effect.type === "launch")
-                void run(effect.command);
+                void run(effect.command, {});
         return { events: [], effects: [] };
     };
     const renderer = options.render
@@ -217,7 +217,7 @@ export function startSession(element, options) {
         store.update(extensionValues, command, commandValues);
         return supplied;
     }
-    async function run(commandName) {
+    async function run(commandName, args) {
         // A command launched from the running one (`launchCommand`) replaces it.
         stopCommand();
         const generation = launches.current();
@@ -230,12 +230,13 @@ export function startSession(element, options) {
                 : undefined;
             if (!current())
                 return;
-            let files;
+            /** The extension's files by `assetRelativePath`, for the sandbox. */
+            let assets;
             let declared;
             let entry;
             let code;
             if (built) {
-                files = built.files;
+                assets = [...built.files].map(([path, value]) => [path.replace(/^\//u, ""), value]);
                 declared = fromCatalog(built.manifest, commandName);
                 entry = `/src/${commandName}.tsx`;
                 code = built.code;
@@ -244,7 +245,7 @@ export function startSession(element, options) {
                 const extension = await fetchExtension();
                 if (!current())
                     return;
-                files = extension.files;
+                assets = extensionAssets(extension.files);
                 declared = fromManifest(extension.manifest, commandName, source);
                 entry = commandEntry(extension.files, commandName);
                 setStatus("Installing…", false, true);
@@ -306,30 +307,9 @@ export function startSession(element, options) {
             const pathSegment = extensionName.replace(/[^A-Za-z0-9._-]/gu, "_") || "extension";
             const supportPath = `/blast/support/${pathSegment}`;
             const assetsPath = `/blast/assets/${pathSegment}`;
-            const vfs = active.getVFS();
-            vfs.mkdirSync(supportPath, { recursive: true });
-            vfs.mkdirSync(assetsPath, { recursive: true });
-            // A marker syncs directories created after the sandbox was initialised.
-            vfs.writeFileSync(`${supportPath}/.keep`, "");
-            vfs.writeFileSync(`${assetsPath}/.keep`, "");
-            for (const [path, value] of files) {
-                if (path.includes("/node_modules/"))
-                    continue;
-                const relative = path.startsWith("/assets/")
-                    ? path.slice("/assets/".length)
-                    : path.startsWith("/src/")
-                        ? /\.(?:cjs|css|html?|js|jsx|mjs|ts|tsx)$/iu.test(path)
-                            ? undefined
-                            : path.slice("/src/".length)
-                        : path.replace(/^\//u, "");
-                if (!relative)
-                    continue;
-                const target = `${assetsPath}/${relative}`;
-                vfs.mkdirSync(target.slice(0, target.lastIndexOf("/")), { recursive: true });
-                vfs.writeFileSync(target, value);
-                if (path === "/package.json")
-                    vfs.writeFileSync("/blast/assets/package.json", value);
-            }
+            await writeSandboxFiles(active, sandboxFiles(assets, assetsPath, supportPath));
+            if (!current())
+                return;
             const context = { extensionName, commandName, source };
             const capabilities = createBrowserCapabilities({
                 catalog: {
@@ -341,8 +321,8 @@ export function startSession(element, options) {
                 ...(handlers.clipboard ? { clipboard: handlers.clipboard } : {}),
                 ...(handlers.openUrl ? { openUrl: handlers.openUrl } : {}),
                 status: (text, error) => setStatus(text, error === true),
-                launchCommand: async (_source, command) => {
-                    void run(command);
+                launchCommand: async (_source, command, launchArgs) => {
+                    void run(command, launchArgs);
                 },
                 openPreferences: (scope) => {
                     if (!options.preferenceForm) {
@@ -352,7 +332,7 @@ export function startSession(element, options) {
                     // Saved preferences reach a command when it launches, so it runs again.
                     void askPreferences(declared, commandName, scope, { ...values }).then((supplied) => {
                         if (supplied && current())
-                            void run(commandName);
+                            void run(commandName, args);
                     });
                 },
             });
@@ -442,7 +422,13 @@ export function startSession(element, options) {
             port.postMessage({
                 type: "init",
                 protocol: 1,
-                command: { extension: extensionName, name: commandName, entry, mode },
+                command: {
+                    extension: extensionName,
+                    name: commandName,
+                    entry,
+                    mode,
+                    ...(Object.keys(args).length ? { arguments: { ...args } } : {}),
+                },
                 preferences: { ...values },
                 environment: {
                     extensionName,
@@ -473,7 +459,7 @@ export function startSession(element, options) {
             if (!options.root) {
                 const command = options.command ?? manifestCommands((await fetchExtension()).manifest)[0];
                 if (!closed)
-                    await run(command ?? "index");
+                    await run(command ?? "index", { ...options.arguments });
                 return;
             }
             const manifest = (await fetchExtension()).manifest;

package/package.json

@@ -9,11 +9,11 @@
     }
   },
   "dependencies": {
-    "@blastlauncher/client-core": "3.0.0-alpha.0",
-    "@blastlauncher/protocol": "3.0.0-alpha.0",
+    "@blastlauncher/client-core": "3.0.0-alpha.3",
+    "@blastlauncher/protocol": "3.0.0-alpha.3",
     "semver": "7.8.5"
   },
-  "version": "3.0.0-alpha.0",
+  "version": "3.0.0-alpha.3",
   "license": "MIT",
   "repository": {
     "type": "git",