@triflare/fx 1.0.3 → 2.1.0-beta.1

package/src/cli/templates/index.js

@@ -0,0 +1,112 @@
+/**
+ * Scaffolding templates used by `fx init`.
+ */
+
+import {
+  configFilename,
+  sourceDirectory,
+  sourceExtension,
+} from "../../brand.js";
+
+const CAT_ASSET = `<svg xmlns="http://www.w3.org/2000/svg" width="95" height="101" viewBox="0 0 95 101">
+  <ellipse cx="47" cy="60" rx="35" ry="35" fill="#ffab19" stroke="#cf8b17" stroke-width="4"/>
+  <circle cx="35" cy="50" r="6" fill="#000"/>
+  <circle cx="60" cy="50" r="6" fill="#000"/>
+</svg>
+`;
+
+function configText({ name, width, height, target }) {
+  const lines = [
+    "project:",
+    `  name: ${JSON.stringify(name)}`,
+    "  fps: 60",
+    `  width: ${width}`,
+    `  height: ${height}`,
+    "  turbo: false",
+    "  interpolation: true",
+    "fx:",
+    "  partialSprites: false",
+  ];
+  if (target !== "none") {
+    lines.push("package:", `  target: ${target}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+const CAT_SOURCE = `sprite "Cat" {
+    costumes: {
+        cat: "../assets/cat.svg"
+    };
+
+    let score = 0;
+
+    when greenFlag {
+        motion.goToXY(0, 0);
+        control.forever {
+            motion.turnRight(1);
+        }
+    }
+
+    when keyPressed("space") {
+        score += 1;
+        looks.sayForSecs(operators.join("Score: ", score), 1);
+    }
+}
+`;
+
+const EMPTY_SOURCE = `// Your project starts here.
+when greenFlag {
+    looks.say("Hello, world!");
+}
+`;
+
+const BLANK_SOURCE = `// Your project starts here.
+`;
+
+/**
+ * Build the file map for an init run.
+ *
+ * @param {{
+ *   product: object,
+ *   name: string,
+ *   template: "cat"|"empty"|"blank",
+ *   width: number,
+ *   height: number,
+ *   target: string,
+ * }} options
+ */
+export function initFiles({ product, name, template, width, height, target }) {
+  const files = {
+    [configFilename(product)]: configText({ name, width, height, target }),
+    [`${sourceDirectory(product)}/main${sourceExtension(product)}`]:
+      template === "cat"
+        ? CAT_SOURCE
+        : template === "empty"
+          ? EMPTY_SOURCE
+          : BLANK_SOURCE,
+  };
+  if (template === "cat") files["assets/cat.svg"] = CAT_ASSET;
+  return files;
+}
+
+export const TEMPLATES = [
+  {
+    value: "cat",
+    label: "Cat demo",
+    hint: "sprite, costumes, events, variables",
+  },
+  { value: "empty", label: "Empty project", hint: "one green-flag script" },
+  { value: "blank", label: "Blank", hint: "just the config and a source file" },
+];
+
+export const TARGETS = [
+  { value: "none", label: "None", hint: "source only" },
+  { value: "html", label: "HTML", hint: "single-file web build" },
+  { value: "zip", label: "ZIP", hint: "packaged archive" },
+];
+
+export const STAGE_SIZES = [
+  { value: "480x360", label: "480 × 360", hint: "Scratch default" },
+  { value: "640x360", label: "640 × 360", hint: "wide" },
+  { value: "1920x1080", label: "1920 × 1080", hint: "full HD" },
+];

package/src/cli/theme.js

@@ -0,0 +1,84 @@
+/**
+ * Terminal theme shared by help output and the reporter.
+ *
+ * Colors are derived from the product palette so a rebrand reaches the CLI
+ * too. Everything falls back to plain text when the stream cannot show color.
+ */
+
+import { styleText } from "node:util";
+import { brandingColors } from "../brand.js";
+
+const STATUS_COLORS = {
+  success: "#34D399",
+  warning: "#FBBF24",
+  danger: "#F87171",
+};
+
+function rgb(hex) {
+  const digits =
+    hex.length === 4 ? hex.slice(1).replace(/./g, "$&$&") : hex.slice(1);
+  return digits.match(/../g).map((part) => parseInt(part, 16));
+}
+
+function mix(from, to, amount) {
+  const [r1, g1, b1] = rgb(from);
+  const [r2, g2, b2] = rgb(to);
+  const channel = (a, b) => Math.round(a + (b - a) * amount);
+  return [channel(r1, r2), channel(g1, g2), channel(b1, b2)];
+}
+
+function supportsColor(stream) {
+  if (!stream?.isTTY) return false;
+  if (process.env.NO_COLOR) return false;
+  if (process.env.TERM === "dumb") return false;
+  return styleText("red", "x", { stream }).includes("\x1b");
+}
+
+/**
+ * @param {{ product?: object, color?: "auto"|"always"|"never", stream?: NodeJS.WriteStream }} [options]
+ */
+export function createTheme({
+  product,
+  color = "auto",
+  stream = process.stdout,
+} = {}) {
+  const palette = brandingColors(product);
+  const enabled =
+    color === "always" || (color !== "never" && supportsColor(stream));
+
+  const paint = (text, codes) => {
+    if (!enabled || codes.length === 0) return String(text);
+    return `\x1b[${codes.join(";")}m${text}\x1b[0m`;
+  };
+
+  const foreground = (colorValue) => {
+    const [r, g, b] = Array.isArray(colorValue) ? colorValue : rgb(colorValue);
+    return `38;2;${r};${g};${b}`;
+  };
+
+  const command = mix(palette.primary, "#FFFFFF", 0.35);
+  const heading = mix(palette.primary, "#FFFFFF", 0.2);
+  const option = mix(palette.primary, "#FFFFFF", 0.58);
+  const argument = mix(palette.primary, "#FFFFFF", 0.74);
+
+  return {
+    enabled,
+    stream,
+
+    accent: (text) => paint(text, [foreground(palette.primary)]),
+    command: (text) => paint(text, ["1", foreground(command)]),
+    heading: (text) => paint(text, ["1", foreground(heading)]),
+    option: (text) => paint(text, [foreground(option)]),
+    argument: (text) => paint(text, [foreground(argument)]),
+    muted: (text) => paint(text, ["2"]),
+    bold: (text) => paint(text, ["1"]),
+    success: (text) => paint(text, [foreground(STATUS_COLORS.success)]),
+    warning: (text) => paint(text, [foreground(STATUS_COLORS.warning)]),
+    danger: (text) => paint(text, [foreground(STATUS_COLORS.danger)]),
+
+    tone(name, text) {
+      const value = STATUS_COLORS[name] ?? palette.primary;
+      return paint(text, [foreground(value)]);
+    },
+  };
+}

package/src/compiler.js

@@ -137,6 +137,7 @@ export class Compiler {
     this.loadAsset = loadAsset || null;
     this.catalog = catalog ? { ...CATALOG, ...catalog } : CATALOG;
     this.extensionUrls = extensionUrls;
+    this.requiredExtensions = new Map();
     this.file = file;
     /** @type {string[]} Non-fatal problems worth surfacing to the user. */
     this.warnings = [];
@@ -252,6 +253,8 @@ export class Compiler {
     // can only be given their mutation once every stack is complete.
     for (const ctx of contexts) this.applyDynamicNextMutations(ctx);
 
+    this.validateRequiredExtensions();
+
     return { project: this.assembleProject(contexts), assets: this.assets };
   }
 
@@ -335,6 +338,11 @@ export class Compiler {
   }
 
   declareTargetVar(ctx, decl) {
+    if (decl.name.startsWith("$"))
+      this.fail(
+        `Names starting with "$" are reserved for temporary variables; rename ${JSON.stringify(decl.name)}.`,
+        decl.loc,
+      );
     const global = ctx.isStage;
     if (global && this.globals.has(decl.name)) {
       const first = this.globals.get(decl.name);
@@ -380,6 +388,11 @@ export class Compiler {
   }
 
   declareTargetList(ctx, decl) {
+    if (decl.name.startsWith("$"))
+      this.fail(
+        `Names starting with "$" are reserved for temporary variables; rename ${JSON.stringify(decl.name)}.`,
+        decl.loc,
+      );
     if (ctx.isStage && this.globals.has(decl.name)) {
       const first = this.globals.get(decl.name);
       const where = this.where(first.loc);
@@ -421,6 +434,13 @@ export class Compiler {
         decl.loc,
       );
     }
+    for (const param of decl.params) {
+      if (param.name.startsWith("$"))
+        this.fail(
+          `Names starting with "$" are reserved for temporary variables; rename parameter ${JSON.stringify(param.name)}.`,
+          decl.loc,
+        );
+    }
     const argIds = decl.params.map((_, i) => `arg${i}`);
     const proccode = decl.params.length
       ? `${decl.name} ${decl.params.map((param) => (param.boolean ? "%b" : "%s")).join(" ")}`
@@ -785,6 +805,8 @@ export class Compiler {
         return this.compileForever(ctx, node);
       case "Return":
         return this.compileReturn(ctx, node);
+      case "TempVarDecl":
+        return this.compileTempVarDecl(ctx, node);
       default:
         this.fail(`Unsupported statement ${node.type}`, node.loc);
     }
@@ -824,6 +846,13 @@ export class Compiler {
   }
 
   compileAssign(ctx, node) {
+    const sigil = /^(\$\$?)([A-Za-z_][A-Za-z0-9_]*)$/.exec(node.name);
+    if (sigil) return this.compileSigilAssign(ctx, node, sigil);
+    if (node.name.startsWith("$"))
+      this.fail(
+        `Invalid temporary variable reference ${JSON.stringify(node.name)}`,
+        node.loc,
+      );
     const resolved = ctx.resolveValue(node.name);
     if (!resolved || resolved.kind !== "var") {
       this.fail(`Unknown variable ${JSON.stringify(node.name)}`, node.loc);
@@ -880,6 +909,64 @@ export class Compiler {
     return id;
   }
 
+  compileTempVarDecl(ctx, node) {
+    if (node.name.startsWith("$"))
+      this.fail(
+        'Temporary variable names cannot start with "$"; use a plain name.',
+        node.loc,
+      );
+    const name =
+      node.kind === "runtime" ? "tempvars.setRuntime" : "tempvars.setThread";
+    const entry = this.catalog[name];
+    if (!entry)
+      this.fail(
+        "Temporary variables are not available in this Fx build",
+        node.loc,
+      );
+    return this.emitCatalogCall(
+      ctx,
+      {
+        name,
+        segments: name.split("."),
+        args: [
+          { type: "String", value: node.name, loc: node.loc },
+          node.init ?? { type: "String", value: "0", loc: node.loc },
+        ],
+        loc: node.loc,
+      },
+      entry,
+      null,
+    ).id;
+  }
+
+  compileSigilAssign(ctx, node, sigil) {
+    if (node.op !== "=" && node.op !== "+=")
+      this.fail(
+        `Temporary variables only support "=" and "+="; ${JSON.stringify(node.op)} is not available.`,
+        node.loc,
+      );
+    const kind = sigil[1] === "$$" ? "Runtime" : "Thread";
+    const action = node.op === "=" ? "set" : "change";
+    const name = `tempvars.${action}${kind}`;
+    const entry = this.catalog[name];
+    if (!entry)
+      this.fail(
+        "Temporary variables are not available in this Fx build",
+        node.loc,
+      );
+    return this.emitCatalogCall(
+      ctx,
+      {
+        name,
+        segments: name.split("."),
+        args: [{ type: "String", value: sigil[2], loc: node.loc }, node.value],
+        loc: node.loc,
+      },
+      entry,
+      null,
+    ).id;
+  }
+
   compileIf(ctx, node) {
     const id = this.addBlock(ctx, {
       opcode: node.else ? "control_if_else" : "control_if",
@@ -976,6 +1063,11 @@ export class Compiler {
   emitCatalogCall(ctx, node, entry, parentId) {
     if (entry.kind === "hat")
       this.fail(`${node.name} is an event and cannot be called`, node.loc);
+    if (entry.requiresExtension) {
+      const id = entry.extension || extensionForOpcode(entry.opcode);
+      if (id && !this.requiredExtensions.has(id))
+        this.requiredExtensions.set(id, node.loc);
+    }
     const id = this.addBlock(ctx, { opcode: entry.opcode, parent: parentId });
     const fieldNames = Object.keys(entry.fields || {});
     const inputNames = Object.keys(entry.inputs || {});
@@ -1282,6 +1374,33 @@ export class Compiler {
   }
 
   emitIdentifier(ctx, node) {
+    const sigil = /^(\$\$?)([A-Za-z_][A-Za-z0-9_]*)$/.exec(node.name);
+    if (sigil) {
+      const name = sigil[1] === "$$" ? "tempvars.runtime" : "tempvars.thread";
+      const entry = this.catalog[name];
+      if (!entry)
+        this.fail(
+          "Temporary variables are not available in this Fx build",
+          node.loc,
+        );
+      const result = this.emitCatalogCall(
+        ctx,
+        {
+          name,
+          segments: name.split("."),
+          args: [{ type: "String", value: sigil[2], loc: node.loc }],
+          loc: node.loc,
+        },
+        entry,
+        null,
+      );
+      return { k: "block", id: result.id, kind: "reporter" };
+    }
+    if (node.name.startsWith("$"))
+      this.fail(
+        `Invalid temporary variable reference ${JSON.stringify(node.name)}`,
+        node.loc,
+      );
     if (node.segments.length > 1)
       this.fail(
         `Unexpected dotted name ${JSON.stringify(node.name)}`,
@@ -1537,6 +1656,20 @@ export class Compiler {
 
   // ------------------------------------------------------------ assembly
 
+  validateRequiredExtensions() {
+    for (const [id, loc] of this.requiredExtensions) {
+      if (this.extensionUrls[id]) continue;
+      const feature = id === "fxTempVars" ? "temporaryvariables" : null;
+      const hint = feature
+        ? ` Run "fx feature ${feature} enable" to install it.`
+        : "";
+      this.fail(
+        `This project uses blocks from extension ${JSON.stringify(id)}, which is not loaded.${hint}`,
+        loc,
+      );
+    }
+  }
+
   assembleProject(contexts) {
     const targets = [];
     const extensions = new Set();