@triflare/fx 2.1.0-beta.2 → 2.1.0-beta.4

package/src/cli/commands/catalog.js

@@ -1,15 +1,104 @@
-import { CATALOG, blockNames } from "../../catalog.js";
+import { CATALOG } from "../../catalog.js";
 import { loadProjectState } from "../context.js";
+import { plural, terminalColumns } from "../format.js";
+
+// Language order for the built-in categories; extension groups follow
+// alphabetically so their blocks stay together at the end of the listing.
+const CATEGORY_ORDER = [
+  "motion",
+  "looks",
+  "sound",
+  "sensing",
+  "operators",
+  "control",
+  "events",
+  "data",
+];
+
+// One-character kind marker, so a name alone still says how the block is used.
+const KIND_MARKS = {
+  command: " ",
+  reporter: "→",
+  boolean: "?",
+  hat: "▸",
+};
+
+/** `SCREAMING_SNAKE_CASE` name for a catalog argument. */
+function argumentName(name) {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .toUpperCase();
+}
+
+/** Positional arguments a block takes, in the order the compiler fills them. */
+function argumentNames(entry) {
+  // `pm.*` are argument reporters whose VALUE field is the reporter's own
+  // label ("is compiled?"), not a parameter the caller supplies.
+  if (entry.opcode?.startsWith("argument_reporter")) return [];
+  if (entry.kind === "hat")
+    return (entry.args || []).map((arg) => arg.field || arg.input);
+  return [
+    ...Object.keys(entry.fields || {}),
+    ...Object.entries(entry.inputs || {})
+      .filter(([, spec]) => spec.type !== "substack")
+      .map(([name]) => name),
+  ];
+}
+
+/** `category.block(ARG, ...)` call shape shown in the listing. */
+function signature(name, entry) {
+  const args = argumentNames(entry).map(argumentName);
+  return `${name}(${args.join(", ")})`;
+}
+
+function mark(entry) {
+  return KIND_MARKS[entry.kind] ?? " ";
+}
+
+/** Group block names by category, in reading order. */
+function groupNames(names) {
+  const groups = new Map();
+  for (const name of names) {
+    const group = name.split(".")[0];
+    if (!groups.has(group)) groups.set(group, []);
+    groups.get(group).push(name);
+  }
+  const rank = (group) => {
+    const index = CATEGORY_ORDER.indexOf(group);
+    return index < 0 ? CATEGORY_ORDER.length : index;
+  };
+  return new Map(
+    [...groups.entries()].sort(
+      ([left], [right]) =>
+        rank(left) - rank(right) || left.localeCompare(right),
+    ),
+  );
+}
 
 export const catalogCommand = {
   name: "catalog",
   aliases: ["l", "blocks"],
   group: "Core Commands:",
   summary: "List available blocks",
-  description: `List block names, including blocks from extensions configured in the
-project.`,
+  description: `List block names grouped by category, including blocks from extensions
+configured in the project.`,
   arguments: ["[dir]"],
-  examples: ["fx catalog", "fx catalog --json"],
+  options: [
+    {
+      flags: "--category <name>",
+      description: "Only list one category, such as motion or pen",
+    },
+    {
+      flags: "--search <text>",
+      description: "Only list blocks whose name contains the text",
+    },
+  ],
+  examples: [
+    "fx catalog",
+    "fx catalog --category motion",
+    "fx catalog --search glide",
+  ],
   async run({ args, cwd, options, reporter, product, prompts }) {
     const state = await loadProjectState({
       input: args[0],
@@ -19,24 +108,69 @@ project.`,
       prompts,
     });
     const merged = { ...CATALOG, ...state.catalog };
-    const names = Object.keys(merged).sort();
-    const builtIn = blockNames().length;
-
-    reporter.heading(
-      `${product.name} catalog (${names.length} blocks` +
-        (names.length > builtIn
-          ? `, ${names.length - builtIn} from extensions`
-          : "") +
-        "):",
+    const category =
+      typeof options.category === "string"
+        ? options.category.toLowerCase()
+        : null;
+    const search =
+      typeof options.search === "string" ? options.search.toLowerCase() : null;
+    const names = Object.keys(merged)
+      .filter(
+        (name) => !category || name.split(".")[0].toLowerCase() === category,
+      )
+      .filter((name) => !search || name.toLowerCase().includes(search))
+      .sort();
+    const selected = Object.fromEntries(
+      names.map((name) => [name, merged[name]]),
     );
-    for (const name of names) {
-      const entry = merged[name];
-      reporter.item(name, `-> ${entry.opcode} [${entry.kind}]`, {
-        width: 32,
-        suffix: entry.extension ? `(ext ${entry.extension})` : "",
-      });
+
+    if (names.length === 0) {
+      const filters = [
+        category && `--category "${options.category}"`,
+        search && `--search "${options.search}"`,
+      ]
+        .filter(Boolean)
+        .join(" and ");
+      reporter.info(`No blocks match ${filters}.`);
+      reporter.hint(`run "${product.command} catalog" to see every block`);
+      return selected;
+    }
+
+    const groups = groupNames(names);
+    let title = `${product.name} catalog — ${plural(names.length, "block")}`;
+    if (category) title += ` · ${category}`;
+    else if (search) title += ` matching "${options.search}"`;
+    else title += ` in ${plural(groups.size, "group")}`;
+    reporter.heading(title);
+    if (!category && !search)
+      reporter.hint("narrow with --category <name> or --search <text>");
+
+    const width = terminalColumns();
+    for (const [group, entries] of groups) {
+      reporter.text("");
+      reporter.item(group, "", { width: 0, suffix: `· ${entries.length}` });
+      if (reporter.verbose) {
+        for (const name of entries) {
+          const entry = merged[name];
+          reporter.item(
+            `${mark(entry)} ${signature(name, entry)}`,
+            `-> ${entry.opcode} [${entry.kind}]`,
+            {
+              width: 44,
+              suffix: entry.extension ? `(ext ${entry.extension})` : "",
+            },
+          );
+        }
+      } else {
+        reporter.columns(
+          entries.map(
+            (name) => `${mark(merged[name])} ${signature(name, merged[name])}`,
+          ),
+          { width },
+        );
+      }
     }
 
-    return merged;
+    return selected;
   },
 };

package/src/cli/format.js

@@ -29,3 +29,55 @@ export function truncate(text, max) {
   const value = String(text);
   return value.length > max ? `${value.slice(0, max)}…` : value;
 }
+
+/** Usable terminal width, clamped so narrow and huge terminals stay readable. */
+export function terminalColumns(
+  stream = process.stdout,
+  { fallback = 80, min = 40, max = 120 } = {},
+) {
+  const width = stream?.columns;
+  if (!Number.isFinite(width) || width <= 0) return fallback;
+  return Math.min(max, Math.max(min, width));
+}
+
+/**
+ * Lay items out in aligned columns that fit `width`. Entries wider than one
+ * cell get a line of their own, so a single long name does not collapse the
+ * whole listing into one column. Trailing whitespace is removed.
+ */
+export function formatColumns(
+  items,
+  { width = 80, indent = 2, gap = 2, cellWidth = 38 } = {},
+) {
+  if (items.length === 0) return [];
+  const available = Math.max(width - indent, 1);
+  const columns = Math.max(
+    1,
+    Math.min(4, Math.floor((available + gap) / (cellWidth + gap))),
+  );
+  const cell = Math.floor((available - gap * (columns - 1)) / columns);
+  const lines = [];
+  let row = [];
+
+  const flush = () => {
+    if (row.length === 0) return;
+    const cells = row.map((text, index) =>
+      index === row.length - 1 ? text : text.padEnd(cell),
+    );
+    lines.push(`${" ".repeat(indent)}${cells.join(" ".repeat(gap))}`.trimEnd());
+    row = [];
+  };
+
+  for (const item of items) {
+    const text = String(item);
+    if (text.length > cell) {
+      flush();
+      lines.push(`${" ".repeat(indent)}${text}`);
+      continue;
+    }
+    row.push(text);
+    if (row.length === columns) flush();
+  }
+  flush();
+  return lines;
+}

package/src/cli/reporter.js

@@ -8,6 +8,7 @@
 
 import { styleText } from "node:util";
 import { brandText } from "../brand.js";
+import { formatColumns } from "./format.js";
 import { createTheme } from "./theme.js";
 
 const STATUS = {
@@ -145,6 +146,13 @@ export function createReporter({
       stdout.write(`  ${theme.accent(padded)}${detail}${note}\n`);
     },
 
+    /** Compact multi-column rows for long block and file listings. */
+    columns(items, { width = 80, indent = 2, gap = 2 } = {}) {
+      if (!human) return;
+      for (const line of formatColumns(items, { width, indent, gap }))
+        stdout.write(`${line}\n`);
+    },
+
     /** Plain block of text with no decoration. */
     text(message) {
       if (!human) return;

package/src/compiler.js

@@ -45,6 +45,8 @@ const NUMBER_TYPES = {
 const TERMINAL_OPCODES = new Set([
   "procedures_return",
   "control_delete_this_clone",
+  "control_exitLoop",
+  "control_continueLoop",
 ]);
 
 let seed = 0n;
@@ -778,6 +780,9 @@ export class Compiler {
     if (block.opcode === "procedures_return") return "`return`";
     if (block.opcode === "control_delete_this_clone")
       return "`control.deleteThisClone()`";
+    if (block.opcode === "control_exitLoop") return "`control.escapeLoop()`";
+    if (block.opcode === "control_continueLoop")
+      return "`control.continueLoop()`";
     if (block.opcode === "control_stop") {
       const option = block.fields.STOP_OPTION
         ? block.fields.STOP_OPTION[0]
@@ -1034,14 +1039,17 @@ export class Compiler {
    */
   emitCall(ctx, node, parentId) {
     const segments = node.segments;
+    const entry = this.catalog[node.name];
 
     // List method: `items.push(x)`, `items.at(i)`, ...
     if (segments.length === 2) {
       const listInfo = ctx.resolveList(segments[0]);
-      if (listInfo) return this.emitListCall(ctx, node, listInfo, parentId);
+      // Canonical list methods take precedence; aliases resolve in emitListCall
+      // only when the name does not identify a catalog block.
+      if (listInfo && (Object.hasOwn(LIST_OPS, segments[1]) || !entry))
+        return this.emitListCall(ctx, node, listInfo, parentId);
     }
 
-    const entry = this.catalog[node.name];
     if (entry) return this.emitCatalogCall(ctx, node, entry, parentId);
 
     if (segments.length === 1 && ctx.funcs.has(node.name)) {
@@ -1098,6 +1106,33 @@ export class Compiler {
     for (const name of inputNames) {
       const spec = entry.inputs[name];
       if (spec.type === "substack") continue;
+      // Variable and list references are stored as fields in Scratch JSON
+      // even though they read as positional arguments in Fx source.
+      if (spec.type === "variable" || spec.type === "list") {
+        if (node.args[argIndex] === undefined)
+          this.fail(
+            `${node.name} requires a ${spec.type} name for ${name}`,
+            node.loc,
+          );
+        const refName = String(this.literalValue(node.args[argIndex]));
+        const resolved =
+          spec.type === "list"
+            ? ctx.resolveList(refName)
+            : ctx.resolveValue(refName);
+        if (
+          !resolved ||
+          (spec.type === "list"
+            ? resolved.kind !== "list"
+            : resolved.kind !== "var")
+        )
+          this.fail(
+            `Unknown ${spec.type} ${JSON.stringify(refName)} for ${node.name}`,
+            node.loc,
+          );
+        fields[name] = [resolved.name, resolved.id];
+        argIndex += 1;
+        continue;
+      }
       if (node.args[argIndex] !== undefined) {
         inputs[name] = this.buildInputForSpec(spec, node.args[argIndex], id);
         argIndex += 1;

package/src/decompiler.js

@@ -18,7 +18,15 @@ const MENU_OPCODES = new Set([
   "looks_backdrops",
   "sound_sounds_menu",
   "control_create_clone_of_menu",
+  "control_stop_sprite_menu",
   "sensing_of_object_menu",
+  "sensing_fulltouchingobjectmenu",
+  "sensing_touchingobjectmenusprites",
+  "sensing_scrolldirections",
+  "sensing_fingeroptions",
+  "looks_changeVisibilityOfSprite_menu",
+  "looks_getOtherSpriteVisible_menu",
+  "looks_getinput_menu",
   "pen_menu_colorParam",
 ]);
 
@@ -50,6 +58,7 @@ const LIST_OPCODE_METHOD = {
 };
 
 const SAFE_TEMP_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SAFE_VAR_REF = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 
 function escapeString(value) {
   return String(value)
@@ -236,6 +245,12 @@ class Decompiler {
     }
     for (const [inputName, spec] of Object.entries(entry.inputs || {})) {
       if (spec.type === "substack") continue;
+      if (spec.type === "variable" || spec.type === "list") {
+        const field = (block.fields || {})[inputName];
+        const ref = field ? field[0] : "0";
+        args.push(SAFE_VAR_REF.test(ref) ? ref : `"${escapeString(ref)}"`);
+        continue;
+      }
       args.push(this.renderExpression(block.inputs[inputName]));
     }
     return `${name}(${args.join(", ")})`;
@@ -396,6 +411,18 @@ class Decompiler {
           option === "timer" ? "timerGreaterThan" : "loudnessGreaterThan";
         return `${pad}when ${kind}(${this.renderExpression(block.inputs.VALUE)}) {\n${body(block.next)}\n}`;
       }
+      case "event_always":
+        return `${pad}when always {\n${body(block.next)}\n}`;
+      case "event_whenanything":
+        return `${pad}when whenAnything(${this.renderExpression(block.inputs.ANYTHING)}) {\n${body(block.next)}\n}`;
+      case "event_whenjavascript":
+        return `${pad}when whenJavaScript(${this.renderExpression(block.inputs.JS)}) {\n${body(block.next)}\n}`;
+      case "event_whenkeyhit":
+        return `${pad}when whenKeyHit("${escapeString((block.fields.KEY_OPTION || ["space"])[0])}") {\n${body(block.next)}\n}`;
+      case "event_whenmousescrolled":
+        return `${pad}when whenMouseScrolled("${escapeString((block.fields.KEY_OPTION || ["up"])[0])}") {\n${body(block.next)}\n}`;
+      case "event_whenstopclicked":
+        return `${pad}when whenStopClicked {\n${body(block.next)}\n}`;
       default:
         return this.renderExtensionHat(block, pad, body);
     }

package/src/vm.js

@@ -7,13 +7,26 @@
  * requires the VM lazily. Loading a project never draws anything, so the
  * no-op renderer is enough to deserialize targets, costumes, and blocks.
  *
- * The VM is shipped as a runtime dependency: `fx test` reports a clear
- * error when it is not installed instead of failing at import time.
+ * The VM is vendored as a git submodule and built into `vendor/pm-vm-dist` by
+ * `scripts/build-vm.js`, much like the PenguinMod Packager. `fx test` reports
+ * a clear error when that build is missing instead of failing at import time.
  */
 import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import { runInThisContext } from "node:vm";
 
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VM_BUNDLE = path.join(
+  ROOT,
+  "vendor",
+  "pm-vm-dist",
+  "dist",
+  "scratch-vm.js",
+);
+
 let modules = null;
 
 /** Blob URLs the VM created for project extension sources, keyed by URL. */
@@ -108,26 +121,41 @@ function installGlobals() {
 }
 
 /**
- * Load `scratch-vm` on first use.
- * @returns {{VirtualMachine: any, centralDispatch: any}}
+ * Load the vendored PenguinMod VM on first use.
+ * @returns {{
+ *   VirtualMachine: any,
+ *   centralDispatch: any,
+ *   extensionApi: any,
+ *   Cast: any,
+ *   Color: any,
+ * }}
  */
 export function loadVmModules() {
   if (modules) return modules;
   installGlobals();
   const require = createRequire(import.meta.url);
-  let VirtualMachine;
-  let centralDispatch;
+  let api;
   try {
-    VirtualMachine = require("scratch-vm");
-    centralDispatch = require("scratch-vm/src/dispatch/central-dispatch");
+    api = require(VM_BUNDLE);
   } catch (error) {
+    if (fs.existsSync(VM_BUNDLE)) throw error;
     throw new Error(
-      "Running tests needs the PenguinMod VM, which could not be loaded. " +
-        "Reinstall @triflare/fx with its runtime dependencies and try again.",
+      "Running tests needs the PenguinMod VM build, which is missing. " +
+        "Run `npm run build:vm` from the Triflare Fx checkout (or reinstall " +
+        "the package).",
       { cause: error },
     );
   }
-  modules = { VirtualMachine, centralDispatch };
+  if (
+    typeof api?.VirtualMachine !== "function" ||
+    !api.centralDispatch ||
+    !api.extensionApi
+  ) {
+    throw new Error(
+      `The PenguinMod VM at ${VM_BUNDLE} did not export the expected API.`,
+    );
+  }
+  modules = api;
   return modules;
 }
 

package/vendor/pm-vm-dist/.fx-build.json

@@ -0,0 +1,7 @@
+{
+  "name": "scratch-vm",
+  "version": "0.2.0",
+  "commit": "75ef6994e55270b9c2a2f3cb2edf6a5bf31cdf2a",
+  "inputHash": "9557b90be391ad2f1deaccfd034fddf0a9591c354da50b13e4cf142a8e2654fc",
+  "builtAt": "2026-11-07T18:15:07.603Z"
+}