@triflare/fx 2.1.0-beta.3 → 2.1.0-beta.5

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/commands/vendor/outdated.js

@@ -34,7 +34,7 @@ export const vendorOutdatedCommand = {
           : result.status === "error"
             ? "danger"
             : "success";
-      reporter.item(result.name, reporter.tone(tone, label), { width: 24 });
+      reporter.item(result.name, label, { width: 24, tone });
       if (result.error) reporter.warn(result.error);
     }
     if (outdated > 0)

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,8 @@
 
 import { styleText } from "node:util";
 import { brandText } from "../brand.js";
+import { sanitizeTerminalText } from "../terminal.js";
+import { formatColumns } from "./format.js";
 import { createTheme } from "./theme.js";
 
 const STATUS = {
@@ -59,7 +61,7 @@ export function createReporter({
     const glyph = mark(symbol);
     const stream = type === "success" ? stdout : stderr;
     const theme = themeFor(stream);
-    const text = String(message);
+    const text = sanitizeTerminalText(message);
     const output = text
       .split("\n")
       .map((line, index) => {
@@ -101,48 +103,61 @@ export function createReporter({
 
     info(message) {
       if (!human) return;
-      stdout.write(`${message}\n`);
+      stdout.write(`${sanitizeTerminalText(message)}\n`);
     },
 
     bullet(message) {
       if (!human) return;
       const theme = themeFor(stdout);
       const glyph = mark("bullet");
-      stdout.write(`  ${glyph ? `${theme.accent(glyph)} ` : ""}${message}\n`);
+      const text = sanitizeTerminalText(message);
+      stdout.write(`  ${glyph ? `${theme.accent(glyph)} ` : ""}${text}\n`);
     },
 
     step(message) {
       if (!human) return;
       const theme = themeFor(stdout);
       const glyph = mark("progress");
-      stdout.write(`${glyph ? `${theme.accent(glyph)} ` : ""}${message}\n`);
+      const text = sanitizeTerminalText(message);
+      stdout.write(`${glyph ? `${theme.accent(glyph)} ` : ""}${text}\n`);
     },
 
     heading(message) {
       if (!human) return;
-      stdout.write(`${themeFor(stdout).heading(String(message))}\n`);
+      stdout.write(
+        `${themeFor(stdout).heading(sanitizeTerminalText(message))}\n`,
+      );
     },
 
     /** Aligned `label  value` row used by command summaries. */
     detail(label, value, { width = 13 } = {}) {
       if (!human) return;
       const theme = themeFor(stdout);
-      const text = String(value);
+      const text = sanitizeTerminalText(value);
       const rendered = text === "(none)" ? theme.muted(text) : theme.bold(text);
-      stdout.write(
-        `  ${theme.muted(String(label).padEnd(width))} ${rendered}\n`,
-      );
+      const name = sanitizeTerminalText(label);
+      stdout.write(`  ${theme.muted(name.padEnd(width))} ${rendered}\n`);
     },
 
     /** Aligned name + description row used by listings. */
-    item(label, value = "", { width = 24, suffix = "" } = {}) {
+    item(label, value = "", { width = 24, suffix = "", tone } = {}) {
       if (!human) return;
       const theme = themeFor(stdout);
-      const text = String(label);
+      const text = sanitizeTerminalText(label);
       const padded = text.padEnd(Math.max(width, text.length));
-      const detail = value ? ` ${value}` : "";
-      const note = suffix ? ` ${theme.muted(suffix)}` : "";
-      stdout.write(`  ${theme.accent(padded)}${detail}${note}\n`);
+      const detail = value ? ` ${sanitizeTerminalText(value)}` : "";
+      const note = suffix
+        ? ` ${theme.muted(sanitizeTerminalText(suffix))}`
+        : "";
+      const rendered = tone ? theme.tone(tone, detail) : detail;
+      stdout.write(`  ${theme.accent(padded)}${rendered}${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. */
@@ -163,7 +178,9 @@ export function createReporter({
     /** Quiet, de-emphasized line for incidental notes. */
     note(message) {
       if (!human) return;
-      stdout.write(`${themeFor(stdout).muted(message)}\n`);
+      stdout.write(
+        `${themeFor(stdout).muted(sanitizeTerminalText(message))}\n`,
+      );
     },
 
     warn(message) {
@@ -183,9 +200,8 @@ export function createReporter({
     hint(message) {
       if (!human) return;
       const theme = themeFor(stdout);
-      stdout.write(
-        `  ${theme.accent("↳")} ${theme.muted(`hint: ${message}`)}\n`,
-      );
+      const text = sanitizeTerminalText(message);
+      stdout.write(`  ${theme.accent("↳")} ${theme.muted(`hint: ${text}`)}\n`);
     },
 
     /** One JSON document, used for the command result envelope. */

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/terminal.js

@@ -0,0 +1,27 @@
+/**
+ * Terminal output safety.
+ *
+ * Names, paths and source text can come from a repository the user did not
+ * write, so untrusted text is rendered with visible `\xNN` escapes instead of
+ * letting the terminal interpret control characters and escape sequences.
+ */
+
+/**
+ * Replace terminal control characters with visible `\xNN` escapes.
+ *
+ * Tabs and newlines are kept because callers print multi-line blocks.
+ * @param {unknown} value
+ */
+export function sanitizeTerminalText(value) {
+  let clean = "";
+  for (const char of String(value)) {
+    const code = char.codePointAt(0);
+    const printable =
+      code === 0x09 ||
+      code === 0x0a ||
+      (code >= 0x20 && code <= 0x7e) ||
+      code >= 0xa0;
+    clean += printable ? char : `\\x${code.toString(16).padStart(2, "0")}`;
+  }
+  return clean;
+}

package/src/vendor.js

@@ -23,6 +23,7 @@ import {
   readExtensionDataUri,
   resolveSource,
 } from "./extensions.js";
+import { sanitizeTerminalText } from "./terminal.js";
 
 export const LOCK_FILENAME = "fx.lock";
 export const LOCK_VERSION = 1;
@@ -1146,13 +1147,14 @@ export async function loadVendorExtensions({
 
 /** A compact line diff, enough to review an extension or config change. */
 export function formatDiff(before, after, filename = "") {
+  const header = sanitizeTerminalText(filename);
   const a = String(before).split(/\r?\n/);
   const b = String(after).split(/\r?\n/);
   const rows = a.length;
   const columns = b.length;
   // Keep very large extensions from allocating an enormous matrix.
   if (rows * columns > 4_000_000) {
-    return `--- ${filename}\n+++ ${filename}\n@@ source changed @@\n`;
+    return `--- ${header}\n+++ ${header}\n@@ source changed @@\n`;
   }
   const table = Array.from(
     { length: rows + 1 },
@@ -1166,24 +1168,24 @@ export function formatDiff(before, after, filename = "") {
           : Math.max(table[i + 1][j], table[i][j + 1]);
     }
   }
-  const lines = [`--- ${filename}`, `+++ ${filename}`];
+  const lines = [`--- ${header}`, `+++ ${header}`];
   let i = 0;
   let j = 0;
   while (i < rows && j < columns) {
     if (a[i] === b[j]) {
-      lines.push(` ${a[i]}`);
+      lines.push(` ${sanitizeTerminalText(a[i])}`);
       i += 1;
       j += 1;
     } else if (table[i + 1][j] >= table[i][j + 1]) {
-      lines.push(`-${a[i]}`);
+      lines.push(`-${sanitizeTerminalText(a[i])}`);
       i += 1;
     } else {
-      lines.push(`+${b[j]}`);
+      lines.push(`+${sanitizeTerminalText(b[j])}`);
       j += 1;
     }
   }
-  while (i < rows) lines.push(`-${a[i++]}`);
-  while (j < columns) lines.push(`+${b[j++]}`);
+  while (i < rows) lines.push(`-${sanitizeTerminalText(a[i++])}`);
+  while (j < columns) lines.push(`+${sanitizeTerminalText(b[j++])}`);
   return `${lines.join("\n")}\n`;
 }