@triflare/fx 1.0.0 → 1.0.1

package/bin/fx.js

@@ -3,7 +3,8 @@
  * Triflare Fx command line interface.
  *
  *   fx build [input.tfx | dir] [-o out.pmp] [--no-config]   (alias: b)
- *   fx decompile <input.pmp> [-o out.tfx] [--assets <dir>]  (alias: d)
+ *   fx decompile <input.pmp> [-o out.tfx] [--assets <dir>] [--fetch-extensions]
+ *                                                          (alias: d)
  *   fx check [input.tfx | dir]                              (alias: c)
  *   fx catalog [dir] [--json]                              (alias: l)
  *   fx init [dir]                                          (alias: i)
@@ -15,7 +16,7 @@ import process from "node:process";
 import { build } from "../src/build.js";
 import { parse } from "../src/parser.js";
 import { discoverSources, mergePrograms } from "../src/project.js";
-import { decompile } from "../src/decompiler.js";
+import { decompileProject } from "../src/decompiler.js";
 import { unzipSync } from "../src/sb3.js";
 import { CATALOG, blockNames } from "../src/catalog.js";
 import {
@@ -26,7 +27,7 @@ import {
   readProjectExtensions,
   removeProjectExtension,
 } from "../src/config.js";
-import { loadExtensions } from "../src/extensions.js";
+import { loadExtensions, readExtensionDataUri } from "../src/extensions.js";
 import { readSprite, spriteArchive, spriteSource } from "../src/sprite.js";
 import { packageProject } from "../src/packager.js";
 import {
@@ -40,6 +41,7 @@ import { startDevServer } from "../src/dev.js";
 import {
   brandText,
   configFilename,
+  configFilenames,
   outputDirectory,
   sourceDirectory,
   sourceExtension,
@@ -64,6 +66,7 @@ function parseArgs(argv) {
     "extract",
     "lan",
     "strict-port",
+    "fetch-extensions",
   ]);
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i];
@@ -96,7 +99,7 @@ Usage:
   ${command} build [<input${EXTENSION}>|<dir>] [-o <output.pmp>] [--no-config]
   ${command} package [<input${EXTENSION}>|<input.pmp>|<dir>] [-o <output>] [--target <target>] [--extract]
   ${command} dev [<input${EXTENSION}>|<dir>] [--host [host]] [--lan] [--port <port>] [--strict-port]
-  ${command} decompile <input.pmp> [-o <output${EXTENSION}>] [--assets <dir>]
+  ${command} decompile <input.pmp> [-o <output${EXTENSION}>] [--assets <dir>] [--fetch-extensions]
   ${command} check [<input${EXTENSION}>|<dir>]
   ${command} catalog [<dir>] [--json]
   ${command} init [dir]
@@ -107,7 +110,8 @@ Commands:
   package   (p)  Package a source, project archive or directory into HTML or a ZIP
                  (Windows/macOS/Linux desktop builds use Electron).
   dev            Serve the packaged HTML and reload when the output changes.
-  decompile (d)  Convert a .pmp back into ${product.name} source.
+  decompile (d)  Convert a .pmp back into ${product.name} source, restoring
+                 extensions into ${configFilename(product)}.
   check     (c)  Parse a file (or every ${EXTENSION} file in a directory) for errors.
   catalog   (l)  List ${product.name} blocks, including those from ${configFilename(product)}
                  extensions (paths or URLs).
@@ -133,6 +137,7 @@ Options:
   -o, --output    Output file path
   --no-config     Ignore ${configFilename(product)}
   --assets <dir>  Extract project assets into <dir> when decompiling
+  --fetch-extensions  Load remote (http/https) extensions when decompiling
   --target <t>    Packaging target (html, zip, windows, macos, linux, …)
   --extract       Unzip a packaged desktop/zip archive
   --host [host]   Dev server host; with no value listen on all interfaces
@@ -159,7 +164,7 @@ function fail(message) {
   process.exit(1);
 }
 
-async function loadProjectExtensions(dir, config, { localFileWarning } = {}) {
+async function loadProjectExtensions(dir, config) {
   const catalog = {};
   const extensionUrls = {};
   const unsandboxed = [];
@@ -168,7 +173,6 @@ async function loadProjectExtensions(dir, config, { localFileWarning } = {}) {
   const loaded = await loadExtensions(config.extensions, {
     baseDir: dir,
     expectUnsandboxed: config.unsandboxed,
-    localFileWarning,
   });
   Object.assign(catalog, loaded.catalog);
   Object.assign(extensionUrls, loaded.extensionUrls);
@@ -471,9 +475,7 @@ async function cmdCatalog(args) {
     : loadConfigFrom(args._[0] || process.cwd());
   const config = loaded.project;
   const extBase = loaded.path ? path.dirname(loaded.path) : process.cwd();
-  const { catalog } = await loadProjectExtensions(extBase, config || {}, {
-    localFileWarning: false,
-  });
+  const { catalog } = await loadProjectExtensions(extBase, config || {});
 
   const merged = { ...CATALOG, ...catalog };
   const names = Object.keys(merged).sort();
@@ -499,12 +501,228 @@ async function cmdCatalog(args) {
   }
 }
 
-function cmdDecompile(args) {
+function truncate(text, max) {
+  const value = String(text);
+  return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+
+/** Sanitize an extension id into a portable file name stem. */
+function extensionFileStem(id) {
+  return (
+    String(id)
+      .replace(/[^A-Za-z0-9._-]+/g, "-")
+      .replace(/^[.-]+|[.-]+$/g, "") || "extension"
+  );
+}
+
+/**
+ * Recover the extensions a decompiled project references.
+ *
+ * An archive only remembers extension sources through `project.extensionURLs`:
+ * Triflare Fx stores local extension files there as data URIs, and PenguinMod
+ * projects keep plain URLs. Data URIs are written next to the output and
+ * referenced from the config file; URLs stay URLs.
+ *
+ * A decompiled archive is untrusted and the output directory is often the
+ * user's workspace, so embedded sources are never written over an existing
+ * path and never through a symlink. An extension that cannot be written is
+ * still loaded from the archive in memory, so its blocks decompile normally,
+ * and its own data URI is recorded in the config so later builds keep it.
+ *
+ * @param {object} project parsed project.json
+ * @param {string|null} outDir directory that receives the config and extension files
+ * @param {{fetchRemote?: boolean}} [options] `fetchRemote` loads plain URLs
+ *   instead of skipping them, which costs a network request per extension.
+ * @returns {{entries: string[], loadEntries: string[], files: string[], warnings: string[]}}
+ */
+function restoreExtensions(project, outDir, { fetchRemote = false } = {}) {
+  const result = { entries: [], loadEntries: [], files: [], warnings: [] };
+  const urls = project && project.extensionURLs;
+  if (!urls || typeof urls !== "object") return result;
+
+  // Resolve the directory that receives embedded sources once, refusing a
+  // symlinked `extensions/` (which would redirect every write) and verifying
+  // that it really is a plain child of the output directory.
+  let extensionDir = null;
+  let extensionDirProblem = null;
+  const resolveExtensionDir = () => {
+    if (extensionDir || extensionDirProblem) return;
+    const dir = path.join(outDir, "extensions");
+    const existing = fs.lstatSync(dir, { throwIfNoEntry: false });
+    if (existing && !existing.isDirectory()) {
+      extensionDirProblem = existing.isSymbolicLink()
+        ? `"${dir}" is a symlink, so the extension would land outside the output directory`
+        : `"${dir}" is not a directory`;
+      return;
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    const expected = path.join(fs.realpathSync(outDir), "extensions");
+    const actual = fs.realpathSync(dir);
+    if (actual !== expected) {
+      extensionDirProblem = `"${dir}" resolves to ${actual}, outside the output directory`;
+      return;
+    }
+    extensionDir = dir;
+  };
+
+  const used = new Set();
+  for (const [id, value] of Object.entries(urls)) {
+    const uri = typeof value === "string" ? value.trim() : "";
+    if (!uri) continue;
+    if (/^https?:\/\//i.test(uri)) {
+      result.entries.push(uri);
+      if (fetchRemote) result.loadEntries.push(uri);
+      else
+        result.warnings.push(
+          `extension ${id} points at a remote URL (${truncate(uri, 48)}); ` +
+            "not fetching it, so its blocks stay unsupported — pass " +
+            "--fetch-extensions to load it",
+        );
+      continue;
+    }
+    if (!/^data:/i.test(uri)) {
+      result.warnings.push(
+        `extension ${id} uses an unsupported URL (${truncate(uri, 48)}); ` +
+          `add it to ${configFilename(product)} by hand`,
+      );
+      continue;
+    }
+    const source = readExtensionDataUri(uri);
+    if (source == null) {
+      result.warnings.push(
+        `extension ${id} has an unreadable data URI; ` +
+          `add it to ${configFilename(product)} by hand`,
+      );
+      continue;
+    }
+    // When no file can be written, the archive's own copy is the only faithful
+    // reference left, so the config keeps its data URI: a later build still has
+    // the extension without overwriting, or depending on, a workspace file.
+    const keepEmbedded = (warning) => {
+      result.loadEntries.push(uri);
+      if (outDir) result.entries.push(uri);
+      result.warnings.push(warning);
+    };
+    if (!outDir) {
+      keepEmbedded(
+        `extension ${id} is embedded in the archive; pass -o to write it out ` +
+          `and reference it from ${configFilename(product)}`,
+      );
+      continue;
+    }
+    resolveExtensionDir();
+    if (extensionDirProblem) {
+      keepEmbedded(
+        `extension ${id} was not written: ${extensionDirProblem}; its blocks ` +
+          "still decompile and the config keeps its source, but the extension " +
+          "file is missing from the output",
+      );
+      continue;
+    }
+    const base = extensionFileStem(id);
+    let stem = base;
+    for (let suffix = 2; used.has(stem); suffix += 1)
+      stem = `${base}-${suffix}`;
+    used.add(stem);
+    const file = path.join(extensionDir, `${stem}.js`);
+    const relative = `extensions/${stem}.js`;
+    const existing = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (existing) {
+      // Never replace a workspace file. An identical regular file is already
+      // the copy we would have written, so reference it and leave it alone.
+      if (existing.isFile() && fs.readFileSync(file, "utf8") === source) {
+        result.files.push(relative);
+        result.entries.push(relative);
+        result.loadEntries.push(file);
+      } else {
+        keepEmbedded(
+          `extension ${id} not written to ${relative}: ` +
+            (existing.isSymbolicLink()
+              ? "the path is a symlink"
+              : "a different file already exists") +
+            "; the config keeps the archive's copy, so delete or rename it to " +
+            "write the extension file",
+        );
+      }
+      continue;
+    }
+    try {
+      // `wx` fails instead of following a path that appeared in the meantime.
+      fs.writeFileSync(file, source, { flag: "wx" });
+    } catch (err) {
+      keepEmbedded(
+        `extension ${id} not written to ${relative}: ` +
+          (err.code === "EEXIST"
+            ? "the path appeared while decompiling"
+            : `${err.code || err.message}`) +
+          "; the config keeps the archive's copy, so delete or rename it to " +
+          "write the extension file",
+      );
+      continue;
+    }
+    result.files.push(relative);
+    result.entries.push(relative);
+    result.loadEntries.push(file);
+  }
+  return result;
+}
+
+/**
+ * Record restored extensions in `fx.yml`, creating one next to the decompiled
+ * source when the directory has none yet.
+ *
+ * @param {string} outDir
+ * @param {string[]} entries
+ * @returns {{file: string, added: number}|null}
+ */
+function writeRestoredConfig(outDir, entries) {
+  if (entries.length === 0) return null;
+  const existing = configFilenames()
+    .map((name) => path.join(outDir, name))
+    .find((file) => fs.existsSync(file));
+  if (existing) {
+    let added = 0;
+    for (const entry of entries)
+      if (addProjectExtension(existing, entry).added) added += 1;
+    return { file: existing, added };
+  }
+  const file = path.join(outDir, configFilenames()[0]);
+  const lines = ["project:", "  extensions:"];
+  for (const entry of entries) lines.push(`    - ${JSON.stringify(entry)}`);
+  lines.push("");
+  fs.writeFileSync(file, lines.join("\n"));
+  return { file, added: entries.length };
+}
+
+async function cmdDecompile(args) {
   const input = args._[0];
   if (!input)
     fail(`decompile requires an input .pmp file\n\n${usage(process.stderr)}`);
   const data = fs.readFileSync(input);
   const files = unzipSync(data);
+  const projectJson = files.get("project.json");
+  if (!projectJson) fail("Not a Scratch project: missing project.json");
+  const project = JSON.parse(projectJson.toString("utf8"));
+
+  const output = args.flags.o || args.flags.output;
+  const outDir = output ? path.dirname(path.resolve(output)) : null;
+  const restored = restoreExtensions(project, outDir, {
+    fetchRemote: Boolean(args.flags["fetch-extensions"]),
+  });
+  for (const warning of restored.warnings)
+    process.stderr.write(`warning: ${warning}\n`);
+
+  // Extension sources also feed the catalog, so extension blocks decompile as
+  // real calls instead of "unsupported block".
+  let catalog = {};
+  if (restored.loadEntries.length > 0) {
+    const loaded = await loadExtensions(restored.loadEntries, {
+      baseDir: outDir || process.cwd(),
+    });
+    catalog = loaded.catalog;
+    for (const warning of loaded.warnings)
+      process.stderr.write(`warning: ${warning}\n`);
+  }
 
   const assetDir = args.flags.assets;
   let assetPrefix = "";
@@ -523,24 +741,23 @@ function cmdDecompile(args) {
       fs.writeFileSync(destination, buffer);
     }
     // Reference assets relative to the directory the source file will live in.
-    const outDir = path.dirname(
-      path.resolve(
-        args.flags.o ||
-          args.flags.output ||
-          path.join(process.cwd(), `out${EXTENSION}`),
-      ),
-    );
     const rel = path
-      .relative(outDir, path.resolve(assetDir))
+      .relative(outDir || process.cwd(), path.resolve(assetDir))
       .replace(/\\/g, "/");
     assetPrefix = rel ? `${rel}/` : "";
   }
 
-  const source = decompile(data, { assetPrefix });
-  const output = args.flags.o || args.flags.output;
+  const source = decompileProject(project, { assetPrefix, catalog });
   if (output) {
     fs.writeFileSync(output, source);
+    const config = writeRestoredConfig(outDir, restored.entries);
     log.success(`Decompiled ${input} -> ${output}`);
+    if (config)
+      log.success(
+        `Restored ${config.added} extension(s) -> ${
+          path.relative(process.cwd(), config.file) || config.file
+        }`,
+      );
   } else {
     process.stdout.write(source);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@triflare/fx",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Code PenguinMod projects with text.",
   "type": "module",
   "license": "Apache-2.0",

package/product.yml

@@ -1,7 +1,7 @@
 # Identity
 name: "Triflare Fx"
 command: "fx"
-version: "1.0.0"
+version: "1.0.1"
 tagline: "Code PenguinMod projects with text."
 author: "Triflare"
 homepage: "https://github.com/triflare/fx"

package/src/decompiler.js

@@ -62,10 +62,25 @@ function numberText(value) {
   return String(value);
 }
 
+/** Reverse lookup for a merged catalog: opcode -> canonical catalog name. */
+function buildByOpcode(catalog) {
+  const map = new Map();
+  for (const [name, entry] of Object.entries(catalog)) {
+    if (!map.has(entry.opcode)) map.set(entry.opcode, name);
+  }
+  return map;
+}
+
 class Decompiler {
   constructor(project, options = {}) {
     this.project = project;
     this.assetPrefix = options.assetPrefix || "";
+    // Extension entries come from `loadExtensions`, so projects that use
+    // extensions decompile into real calls instead of "unsupported block".
+    this.catalog = options.catalog
+      ? { ...CATALOG, ...options.catalog }
+      : CATALOG;
+    this.byOpcode = options.catalog ? buildByOpcode(this.catalog) : BY_OPCODE;
     this.returningProccodes = new Set();
     for (const target of project.targets) {
       for (const block of Object.values(target.blocks)) {
@@ -149,6 +164,12 @@ class Decompiler {
       const field = Object.values(block.fields || {})[0];
       return field ? `"${escapeString(field[0])}"` : '""';
     }
+    // Extension menus are shadow blocks the catalog never describes; their
+    // chosen option is the only thing worth emitting.
+    if (block.shadow) {
+      const field = Object.values(block.fields || {})[0];
+      if (field) return `"${escapeString(field[0])}"`;
+    }
     if (block.opcode === "data_variable") return block.fields.VARIABLE[0];
     if (block.opcode === "data_listcontents") return block.fields.LIST[0];
     if (
@@ -191,13 +212,13 @@ class Decompiler {
       return `(not ${this.renderExpression(block.inputs.OPERAND)})`;
     }
 
-    const name = BY_OPCODE.get(block.opcode);
+    const name = this.byOpcode.get(block.opcode);
     if (name) return this.renderCatalogCall(name, block);
     return `/* unknown ${block.opcode} */`;
   }
 
   renderCatalogCall(name, block) {
-    const entry = CATALOG[name];
+    const entry = this.catalog[name];
     const args = [];
     for (const key of Object.keys(entry.fields || {})) {
       const field = block.fields[key];
@@ -279,12 +300,22 @@ class Decompiler {
           );
           return `${pad}${listName}.${method}(${args.join(", ")});`;
         }
-        const name = BY_OPCODE.get(block.opcode);
-        if (name && CATALOG[name].kind === "command") {
+        const name = this.byOpcode.get(block.opcode);
+        if (!name) return `${pad}// unsupported block ${block.opcode}`;
+        const entry = this.catalog[name];
+        const substacks = Object.entries(entry.inputs || {})
+          .filter(([, spec]) => spec.type === "substack")
+          .map(([input]) => input);
+        if (substacks.length === 0)
           return `${pad}${this.renderCatalogCall(name, block)};`;
-        }
-        if (name) return `${pad}${this.renderCatalogCall(name, block)};`;
-        return `${pad}// unsupported block ${block.opcode}`;
+        const primary = firstOf(block.inputs[substacks[0]]);
+        const alternate = substacks[1]
+          ? firstOf(block.inputs[substacks[1]])
+          : null;
+        const otherwise = alternate
+          ? ` else {${sub(firstOf(block.inputs[substacks[1]]))}\n${pad}}`
+          : "";
+        return `${pad}${this.renderCatalogCall(name, block)} {${sub(primary)}${otherwise}\n${pad}}`;
       }
     }
   }
@@ -321,10 +352,25 @@ class Decompiler {
         return `${pad}when ${kind}(${this.renderExpression(block.inputs.VALUE)}) {\n${body(block.next)}\n}`;
       }
       default:
-        return null;
+        return this.renderExtensionHat(block, pad, body);
     }
   }
 
+  /** Render hats contributed by extensions, e.g. `when signals.onBang("x") {`. */
+  renderExtensionHat(block, pad, body) {
+    const name = this.byOpcode.get(block.opcode);
+    const entry = name ? this.catalog[name] : null;
+    if (!entry || entry.kind !== "hat") return null;
+    const args = (entry.args || []).map((spec) => {
+      if (spec.field) {
+        const field = (block.fields || {})[spec.field];
+        return `"${escapeString(field ? field[0] : "")}"`;
+      }
+      return this.renderExpression((block.inputs || {})[spec.input]);
+    });
+    return `${pad}when ${name}(${args.join(", ")}) {\n${body(block.next)}\n}`;
+  }
+
   renderFunction(defBlock) {
     const protoId = firstOf(defBlock.inputs.custom_block);
     const proto = this.target.blocks[protoId];
@@ -474,7 +520,8 @@ function indentText(text, prefix) {
 /**
  * Decompile project JSON into Triflare Fx source.
  * @param {object} project
- * @param {{assetPrefix?: string}} [options]
+ * @param {{assetPrefix?: string, catalog?: Record<string, object>}} [options]
+ *   `catalog` adds extension entries from `loadExtensions`.
  * @returns {string}
  */
 export function decompileProject(project, options) {
@@ -484,7 +531,7 @@ export function decompileProject(project, options) {
 /**
  * Decompile a `.pmp`/`.sb3` buffer (or project JSON) into Triflare Fx source.
  * @param {Buffer|Uint8Array|object} input
- * @param {{assetPrefix?: string}} [options]
+ * @param {{assetPrefix?: string, catalog?: Record<string, object>}} [options]
  * @returns {string}
  */
 export function decompile(input, options) {

package/src/extensions.js

@@ -534,9 +534,55 @@ async function evaluateExtension(
 
 // ------------------------------------------------------------------- loading
 
+const DATA_URI = /^data:([^,]*),([\s\S]*)$/i;
+const BASE64_PAYLOAD = /^[A-Za-z0-9+/=\s]*$/;
+
+/**
+ * Encode extension source as a `data:` URI.
+ *
+ * Archives only remember extension sources through `project.extensionURLs`, so
+ * local extension files are baked in as data URIs (the same trick the
+ * PenguinMod packager uses when it bakes extensions). Base64 survives quotes,
+ * comments and non-ASCII text without escaping.
+ * @param {string} source
+ * @returns {string}
+ */
+export function extensionDataUri(source) {
+  const base64 = Buffer.from(String(source), "utf8").toString("base64");
+  return `data:text/javascript;base64,${base64}`;
+}
+
+/**
+ * Decode a `data:` URI back into extension source text.
+ * @param {string} uri
+ * @returns {string|null} source text, or null when the URI is unsupported
+ */
+export function readExtensionDataUri(uri) {
+  const match = DATA_URI.exec(String(uri).trim());
+  if (!match) return null;
+  const [, meta, payload] = match;
+  try {
+    if (/;base64\s*$/i.test(meta)) {
+      if (!BASE64_PAYLOAD.test(payload)) return null;
+      return Buffer.from(payload, "base64").toString("utf8");
+    }
+    return decodeURIComponent(payload);
+  } catch {
+    return null;
+  }
+}
+
 /** Resolve a config entry to source text. */
 async function resolveSource(entry, baseDir, fetchImpl) {
   const value = String(entry);
+  if (/^data:/i.test(value)) {
+    const source = readExtensionDataUri(value);
+    if (source == null)
+      throw new Error(
+        "unsupported data URI; expected base64 or percent-encoded JavaScript",
+      );
+    return { source, remote: false, dataUri: true, url: value };
+  }
   if (/^https?:\/\//i.test(value)) {
     const fetchFn = fetchImpl || globalThis.fetch;
     if (typeof fetchFn !== "function")
@@ -597,23 +643,16 @@ async function evaluateExtensionAny(source, filename) {
 /**
  * Load a list of extension references.
  *
- * @param {Array<string>} list Paths or `http(s)://` URLs.
- * @param {{baseDir?: string, fetchImpl?: typeof fetch, expectUnsandboxed?: string|string[], localFileWarning?: boolean}} [options]
+ * @param {Array<string>} list Paths, `http(s)://` URLs or `data:` URIs.
+ * @param {{baseDir?: string, fetchImpl?: typeof fetch, expectUnsandboxed?: string|string[]}} [options]
  *   `expectUnsandboxed` acknowledges extensions that are known to require
- *   unsandboxed mode, silencing the warning for them. `localFileWarning`
- *   (default true) emits the build-specific notice that local files are not
- *   recorded in `extensionURLs`; listing commands turn it off.
+ *   unsandboxed mode, silencing the warning for them.
  * @returns {Promise<{catalog: Record<string, object>, extensionUrls: Record<string, string>, warnings: string[], ids: string[], unsandboxed: string[]}>}
  *   `unsandboxed` holds the ids of extensions that only load unsandboxed.
  */
 export async function loadExtensions(
   list,
-  {
-    baseDir = process.cwd(),
-    fetchImpl,
-    expectUnsandboxed = [],
-    localFileWarning = true,
-  } = {},
+  { baseDir = process.cwd(), fetchImpl, expectUnsandboxed = [] } = {},
 ) {
   const catalog = {};
   const extensionUrls = {};
@@ -631,62 +670,63 @@ export async function loadExtensions(
 
   for (const entry of list || []) {
     const label = String(entry);
+    // Data URIs are enormous; keep warning lines readable without breaking the
+    // path/URL matching that `expectUnsandboxed` relies on.
+    const name = label.length > 64 ? `${label.slice(0, 60)}…` : label;
     try {
-      const { source, remote, url, file } = await resolveSource(
+      const { source, remote, url, file, dataUri } = await resolveSource(
         entry,
         baseDir,
         fetchImpl,
       );
       const { infos, unsandboxed: needsUnsandboxed } =
-        await evaluateExtensionAny(source, remote ? url : file);
+        await evaluateExtensionAny(
+          source,
+          remote ? url : (file ?? "extension"),
+        );
       if (infos.length === 0) {
         warnings.push(
-          `extension ${label} did not call Scratch.extensions.register()`,
+          `extension ${name} did not call Scratch.extensions.register()`,
         );
         continue;
       }
       for (const info of infos) {
-        const count = registerInfo(catalog, info, label);
+        const count = registerInfo(catalog, info, name);
         if (!ids.includes(info.id)) ids.push(info.id);
 
-        for (const name of [info.id, label]) {
-          if (!declared.has(name)) continue;
-          declaredSeen.add(name);
-          if (!needsUnsandboxed) declaredNotNeeded.add(name);
+        for (const candidate of [info.id, label]) {
+          if (!declared.has(candidate)) continue;
+          declaredSeen.add(candidate);
+          if (!needsUnsandboxed) declaredNotNeeded.add(candidate);
         }
 
         if (needsUnsandboxed) {
           if (!unsandboxed.includes(info.id)) unsandboxed.push(info.id);
-          needsDeclaration.push({ id: info.id, label });
+          needsDeclaration.push({ id: info.id, label, name });
         }
 
-        if (remote) {
-          extensionUrls[info.id] = url;
-        } else if (localFileWarning) {
-          warnings.push(
-            `extension ${label} (id "${info.id}") is a local file; it will be referenced in ` +
-              "project.extensions but not in extensionURLs. Bundle it with the PenguinMod packager " +
-              "or host it before loading in the editor.",
-          );
-        }
+        // Remote URLs travel as-is; local (and already embedded) sources are
+        // recorded as data URIs so the archive carries the extension with it.
+        extensionUrls[info.id] =
+          remote || dataUri ? url : extensionDataUri(source);
         if (count === 0)
           warnings.push(
-            `extension ${label} (id "${info.id}") exposes no usable blocks`,
+            `extension ${name} (id "${info.id}") exposes no usable blocks`,
           );
       }
     } catch (err) {
       warnings.push(
-        `failed to load extension ${label}: ${err && err.message ? err.message : err}`,
+        `failed to load extension ${name}: ${err && err.message ? err.message : err}`,
       );
     }
   }
 
   // Extensions that only load unsandboxed error out unless the editor is allowed
   // to run them unsandboxed (or the project is packaged), so say so up front.
-  for (const { id, label } of needsDeclaration) {
+  for (const { id, label, name } of needsDeclaration) {
     if (declared.has(id) || declared.has(label)) continue;
     warnings.push(
-      `extension ${label} (id "${id}") requires unsandboxed mode; allow it to run ` +
+      `extension ${name} (id "${id}") requires unsandboxed mode; allow it to run ` +
         `unsandboxed when opening the project in PenguinMod (or add "${id}" to ` +
         "project.unsandboxed in fx.yml once you trust it)",
     );

package/src/index.js

@@ -13,7 +13,11 @@ export { build, writeSb3 } from "./build.js";
 export { discoverSources, mergePrograms } from "./project.js";
 export { decompile, decompileProject } from "./decompiler.js";
 export { zipSync, unzipSync, md5hex, imageSize, wavInfo } from "./sb3.js";
-export { loadExtensions } from "./extensions.js";
+export {
+  loadExtensions,
+  extensionDataUri,
+  readExtensionDataUri,
+} from "./extensions.js";
 export { readSprite, spriteArchive, spriteSource } from "./sprite.js";
 export { packageProject, loadPackager, packagerDistPath } from "./packager.js";
 export {