@triflare/fx 0.0.0-stage → 1.0.0

package/src/project.js

@@ -0,0 +1,156 @@
+/**
+ * Multi-file project assembly.
+ *
+ * A Triflare Fx project can be spread across any number of `.tfx` files in a
+ * directory tree. This module discovers those files and merges their ASTs into
+ * a single `Program`, so the rest of the pipeline keeps working with one AST.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ParseError } from "./errors.js";
+import { configFilename, sourceExtension } from "./brand.js";
+
+/** Directories never scanned for `.tfx` sources. */
+const IGNORED_DIRS = new Set([
+  "node_modules",
+  "build",
+  "dist",
+  "coverage",
+  ".cache",
+]);
+
+/**
+ * Recursively find every `.tfx` file under `dir`, skipping hidden entries and
+ * well-known build/dependency directories. Results are deterministic (sorted by
+ * path) so builds are reproducible.
+ * @param {string} dir
+ * @returns {string[]} absolute file paths
+ */
+export function discoverSources(dir) {
+  const root = path.resolve(dir);
+  const found = [];
+  const extension = sourceExtension().toLowerCase();
+
+  const walk = (current) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRS.has(entry.name)) continue;
+        walk(full);
+      } else if (
+        entry.isFile() &&
+        entry.name.toLowerCase().endsWith(extension)
+      ) {
+        found.push(full);
+      }
+    }
+  };
+
+  walk(root);
+  return found.sort();
+}
+
+/** @param {object} loc */
+function errorInfo(loc) {
+  return {
+    file: loc && loc.file,
+    line: loc && loc.line,
+    column: loc && loc.column,
+  };
+}
+
+/**
+ * Merge parsed programs into a single project AST.
+ *
+ * - At most one `stage { }` declaration is allowed across all files.
+ * - Top-level statements from every file become stage content.
+ * - At most one plain `sprite "Name" { }` declaration is allowed per name.
+ *   Additional `partial sprite "Name" { }` fragments are appended to it.
+ * - Partial sprites only merge when `partialSprites` is enabled.
+ *
+ * Bodies are composed base-first, then fragments in build order, so costume
+ * order and local variable initializers stay predictable regardless of which
+ * file happens to sort first.
+ *
+ * @param {Array<{ast: object, file: string}>} entries
+ * @param {{partialSprites?: boolean}} [options]
+ * @returns {object} a `Program` node
+ */
+export function mergePrograms(entries, { partialSprites = false } = {}) {
+  let stage = null;
+  const topItems = [];
+  /** @type {Map<string, {name: string, loc: object, base: object|null, fragments: object[], files: string[]}>} */
+  const groups = new Map();
+
+  for (const { ast, file } of entries) {
+    if (ast.stage) {
+      if (stage) {
+        throw new ParseError(
+          "A project may only declare one stage",
+          errorInfo(ast.stage.loc),
+        );
+      }
+      stage = ast.stage;
+    }
+    topItems.push(...ast.topItems);
+    for (const sprite of ast.sprites) {
+      if (sprite.partial && !partialSprites) {
+        throw new ParseError(
+          `partial sprite ${JSON.stringify(sprite.name)} is disabled; ` +
+            `set "fx.partialSprites: true" in ${configFilename()} to enable it`,
+          errorInfo(sprite.loc),
+        );
+      }
+
+      let group = groups.get(sprite.name);
+      if (!group) {
+        group = {
+          name: sprite.name,
+          loc: sprite.loc,
+          base: null,
+          fragments: [],
+          files: [],
+        };
+        groups.set(sprite.name, group);
+      }
+      group.files.push(file);
+
+      if (sprite.partial) {
+        group.fragments.push({ decl: sprite, file });
+      } else if (group.base) {
+        throw new ParseError(
+          `Duplicate sprite ${JSON.stringify(sprite.name)} ` +
+            `(declared in ${group.base.file} and ${file}); ` +
+            `use \`partial sprite ${JSON.stringify(sprite.name)}\` to split it across files`,
+          errorInfo(sprite.loc),
+        );
+      } else {
+        group.base = { decl: sprite, file };
+      }
+    }
+  }
+
+  const sprites = [...groups.values()].map((group) => {
+    const base = group.base ? [group.base.decl] : [];
+    const fragments = group.fragments.map(({ decl }) => decl);
+    const [first] = base.length ? base : fragments;
+    return {
+      type: "SpriteDecl",
+      name: group.name,
+      body: [...base, ...fragments].flatMap((decl) => decl.body),
+      loc: first.loc,
+      partial: false,
+      files: group.files,
+    };
+  });
+
+  return { type: "Program", stage, sprites, topItems };
+}

package/src/sb3.js

@@ -0,0 +1,340 @@
+/**
+ * Minimal, dependency-free ZIP reader/writer for Scratch 3 project archives
+ * (both `.sb3` and PenguinMod's `.pmp`, which share the same format) plus
+ * asset helpers.
+ *
+ * The Scratch 3 project format is a ZIP archive containing `project.json`
+ * alongside content-addressed asset files named `<md5>.<ext>`.
+ */
+import zlib from "node:zlib";
+import crypto from "node:crypto";
+
+// --------------------------------------------------------------------- crc32
+
+let CRC_TABLE = null;
+function crcTable() {
+  if (CRC_TABLE) return CRC_TABLE;
+  CRC_TABLE = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    CRC_TABLE[n] = c >>> 0;
+  }
+  return CRC_TABLE;
+}
+
+/** @param {Buffer|Uint8Array} buf */
+export function crc32(buf) {
+  const table = crcTable();
+  let crc = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) {
+    crc = table[(crc ^ buf[i]) & 0xff] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** @param {Buffer|Uint8Array} buf */
+export function md5hex(buf) {
+  return crypto.createHash("md5").update(buf).digest("hex");
+}
+
+// ----------------------------------------------------------------------- zip
+
+const DOS_TIME = 0; // 00:00:00
+const DOS_DATE = ((2024 - 1980) << 9) | (1 << 5) | 1; // 2024-01-01
+
+// Upper bound on a single entry's uncompressed size, guarding against
+// decompression bombs. 512 MiB is far beyond any realistic Scratch asset.
+const MAX_UNCOMPRESSED_SIZE = 512 * 1024 * 1024;
+// Cap cumulative output retained while extracting an archive as well.
+const MAX_ARCHIVE_UNCOMPRESSED_SIZE = 512 * 1024 * 1024;
+
+/**
+ * Build a ZIP archive entirely in memory.
+ * @param {Array<{name: string, data: Buffer|Uint8Array, compress?: boolean}>} files
+ * @returns {Buffer}
+ */
+export function zipSync(files) {
+  const chunks = [];
+  const central = [];
+  let offset = 0;
+
+  for (const file of files) {
+    const nameBuf = Buffer.from(file.name, "utf8");
+    const raw = Buffer.isBuffer(file.data) ? file.data : Buffer.from(file.data);
+    const crc = crc32(raw);
+    let method = 0;
+    let stored = raw;
+    if (file.compress !== false && raw.length > 0) {
+      const deflated = zlib.deflateRawSync(raw, { level: 9 });
+      if (deflated.length < raw.length) {
+        method = 8;
+        stored = deflated;
+      }
+    }
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(0x0800, 6); // UTF-8 flag
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(DOS_TIME, 10);
+    local.writeUInt16LE(DOS_DATE, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(stored.length, 18);
+    local.writeUInt32LE(raw.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28);
+    chunks.push(local, nameBuf, stored);
+
+    const cd = Buffer.alloc(46);
+    cd.writeUInt32LE(0x02014b50, 0);
+    cd.writeUInt16LE(20, 4); // version made by
+    cd.writeUInt16LE(20, 6); // version needed
+    cd.writeUInt16LE(0x0800, 8);
+    cd.writeUInt16LE(method, 10);
+    cd.writeUInt16LE(DOS_TIME, 12);
+    cd.writeUInt16LE(DOS_DATE, 14);
+    cd.writeUInt32LE(crc, 16);
+    cd.writeUInt32LE(stored.length, 20);
+    cd.writeUInt32LE(raw.length, 24);
+    cd.writeUInt16LE(nameBuf.length, 28);
+    cd.writeUInt16LE(0, 30); // extra
+    cd.writeUInt16LE(0, 32); // comment
+    cd.writeUInt16LE(0, 34); // disk
+    cd.writeUInt16LE(0, 36); // internal attrs
+    cd.writeUInt32LE(0, 38); // external attrs
+    cd.writeUInt32LE(offset, 42);
+    central.push(cd, nameBuf);
+
+    offset += local.length + nameBuf.length + stored.length;
+  }
+
+  const centralBuf = Buffer.concat(central);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(files.length, 8);
+  eocd.writeUInt16LE(files.length, 10);
+  eocd.writeUInt32LE(centralBuf.length, 12);
+  eocd.writeUInt32LE(offset, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...chunks, centralBuf, eocd]);
+}
+
+/**
+ * Read a ZIP archive produced by {@link zipSync} (or any standard 32-bit zip).
+ * @param {Buffer|Uint8Array} buf
+ * @returns {Map<string, Buffer>}
+ */
+export function unzipSync(buf) {
+  const data = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+  // Find the End Of Central Directory record.
+  let eocd = -1;
+  for (let i = data.length - 22; i >= 0; i--) {
+    if (data.readUInt32LE(i) === 0x06054b50) {
+      eocd = i;
+      break;
+    }
+  }
+  if (eocd < 0)
+    throw new Error("Not a ZIP archive (no end-of-central-directory record)");
+
+  const count = data.readUInt16LE(eocd + 10);
+  let ptr = data.readUInt32LE(eocd + 16);
+  const out = new Map();
+  let totalUncompressedSize = 0;
+
+  for (let i = 0; i < count; i++) {
+    if (data.readUInt32LE(ptr) !== 0x02014b50)
+      throw new Error("Corrupt ZIP central directory");
+    const method = data.readUInt16LE(ptr + 10);
+    const compSize = data.readUInt32LE(ptr + 20);
+    const uncompSize = data.readUInt32LE(ptr + 24);
+    const nameLen = data.readUInt16LE(ptr + 28);
+    const extraLen = data.readUInt16LE(ptr + 30);
+    const commentLen = data.readUInt16LE(ptr + 32);
+    const localOffset = data.readUInt32LE(ptr + 42);
+    const name = data.slice(ptr + 46, ptr + 46 + nameLen).toString("utf8");
+
+    if (uncompSize > MAX_UNCOMPRESSED_SIZE)
+      throw new Error(
+        `ZIP entry "${name}" exceeds the ${MAX_UNCOMPRESSED_SIZE}-byte size limit`,
+      );
+    const remainingSize = MAX_ARCHIVE_UNCOMPRESSED_SIZE - totalUncompressedSize;
+    if (uncompSize > remainingSize)
+      throw new Error(
+        `ZIP archive exceeds the ${MAX_ARCHIVE_UNCOMPRESSED_SIZE}-byte size limit`,
+      );
+    if (method !== 0 && method !== 8)
+      throw new Error(`Unsupported ZIP compression method: ${method}`);
+
+    const localNameLen = data.readUInt16LE(localOffset + 26);
+    const localExtraLen = data.readUInt16LE(localOffset + 28);
+    const dataStart = localOffset + 30 + localNameLen + localExtraLen;
+    const raw = data.slice(dataStart, dataStart + compSize);
+    const uncompressed =
+      method === 8
+        ? zlib.inflateRawSync(raw, {
+            // zlib requires a positive limit, even for an empty entry.
+            maxOutputLength: Math.max(
+              1,
+              Math.min(MAX_UNCOMPRESSED_SIZE, remainingSize),
+            ),
+          })
+        : raw;
+    // Account for actual output too, in case a header understates its size.
+    totalUncompressedSize += Math.max(uncompSize, uncompressed.length);
+    if (totalUncompressedSize > MAX_ARCHIVE_UNCOMPRESSED_SIZE)
+      throw new Error(
+        `ZIP archive exceeds the ${MAX_ARCHIVE_UNCOMPRESSED_SIZE}-byte size limit`,
+      );
+    out.set(name, uncompressed);
+
+    ptr += 46 + nameLen + extraLen + commentLen;
+  }
+  return out;
+}
+
+// -------------------------------------------------------------------- assets
+
+const EXT_FORMAT = {
+  svg: "svg",
+  png: "png",
+  jpg: "jpg",
+  jpeg: "jpg",
+  gif: "gif",
+  bmp: "bmp",
+  wav: "wav",
+  mp3: "mp3",
+  ogg: "ogg",
+};
+
+/**
+ * @param {string} filePath
+ * @returns {string} the Scratch dataFormat for a path/URL.
+ */
+export function extensionOf(filePath) {
+  const clean = String(filePath).split(/[?#]/)[0];
+  const match = /\.([a-z0-9]+)$/i.exec(clean);
+  return match ? match[1].toLowerCase() : "";
+}
+
+/**
+ * Read the pixel dimensions of an image buffer (SVG, PNG, JPG or GIF).
+ * Falls back to 0x0 when unknown.
+ * @param {Buffer} buffer
+ * @param {string} format
+ * @returns {{width: number, height: number}}
+ */
+export function imageSize(buffer, format) {
+  try {
+    if (
+      format === "png" &&
+      buffer.length >= 24 &&
+      buffer.readUInt32BE(0) === 0x89504e47
+    ) {
+      return {
+        width: buffer.readUInt32BE(16),
+        height: buffer.readUInt32BE(20),
+      };
+    }
+    if (format === "gif" && buffer.length >= 10) {
+      return { width: buffer.readUInt16LE(6), height: buffer.readUInt16LE(8) };
+    }
+    if (format === "jpg") {
+      let i = 2;
+      while (i < buffer.length) {
+        if (buffer[i] !== 0xff) {
+          i++;
+          continue;
+        }
+        const marker = buffer[i + 1];
+        if (
+          marker >= 0xc0 &&
+          marker <= 0xcf &&
+          marker !== 0xc4 &&
+          marker !== 0xc8 &&
+          marker !== 0xcc
+        ) {
+          return {
+            height: buffer.readUInt16BE(i + 5),
+            width: buffer.readUInt16BE(i + 7),
+          };
+        }
+        i += 2 + buffer.readUInt16BE(i + 2);
+      }
+    }
+    if (format === "svg") {
+      const text = buffer.toString("utf8");
+      const w = /<svg[^>]*\bwidth\s*=\s*["']([\d.]+)([^"']*)["']/i.exec(text);
+      const h = /<svg[^>]*\bheight\s*=\s*["']([\d.]+)([^"']*)["']/i.exec(text);
+      if (w && h && !w[2].includes("%") && !h[2].includes("%"))
+        return { width: Number(w[1]), height: Number(h[1]) };
+      const vb = /viewBox\s*=\s*["']([^"']+)["']/i.exec(text);
+      if (vb) {
+        const nums = vb[1]
+          .trim()
+          .split(/[\s,]+/)
+          .map(Number);
+        if (nums.length === 4 && nums.every((n) => Number.isFinite(n))) {
+          return { width: nums[2], height: nums[3] };
+        }
+      }
+    }
+  } catch {
+    /* fall through to zero dimensions */
+  }
+  return { width: 0, height: 0 };
+}
+
+/**
+ * Parse a WAV file header to recover rate + sample count.
+ * @param {Buffer} buffer
+ * @returns {{rate: number, sampleCount: number}}
+ */
+export function wavInfo(buffer) {
+  try {
+    if (
+      buffer.length >= 44 &&
+      buffer.toString("ascii", 0, 4) === "RIFF" &&
+      buffer.toString("ascii", 8, 12) === "WAVE"
+    ) {
+      let fmt = null;
+      // Locate the format and data chunks, skipping unknown chunks and padding.
+      let i = 12;
+      while (i + 8 <= buffer.length) {
+        const id = buffer.toString("ascii", i, i + 4);
+        const size = buffer.readUInt32LE(i + 4);
+        if (id === "fmt " && size >= 16) {
+          fmt = {
+            rate: buffer.readUInt32LE(i + 12),
+            bits: buffer.readUInt16LE(i + 22),
+            channels: buffer.readUInt16LE(i + 10),
+          };
+        }
+        if (id === "data" && fmt) {
+          const bytesPerSample = Math.max(1, (fmt.bits / 8) * fmt.channels);
+          return {
+            rate: fmt.rate,
+            sampleCount: Math.floor(size / bytesPerSample),
+          };
+        }
+        i += 8 + size + (size % 2);
+      }
+      return { rate: fmt?.rate ?? 48000, sampleCount: 0 };
+    }
+  } catch {
+    /* ignore */
+  }
+  return { rate: 48000, sampleCount: 0 };
+}
+
+/** @returns {string} Normalise a costume dataFormat used in project.json. */
+export function detectFormat(filePath) {
+  return EXT_FORMAT[extensionOf(filePath)] || extensionOf(filePath) || "png";
+}

package/src/sprite.js

@@ -0,0 +1,81 @@
+/**
+ * Single-sprite archives (`.pms`) and imports (`.sprite3`/`.pms`).
+ *
+ * A sprite archive is the same ZIP Scratch uses for `.sprite3`: `sprite.json`
+ * plus content-addressed `<md5>.<ext>` assets at the archive root. PenguinMod
+ * documents the same `sprite.json` target layout for saved sprites.
+ */
+import { unzipSync, zipSync } from "./sb3.js";
+import { decompileProject } from "./decompiler.js";
+
+const ASSET_NAME = /^[0-9a-f]{32}\.[a-z0-9]+$/i;
+
+/** Asset filenames a sprite references through its costumes and sounds. */
+export function spriteAssets(sprite) {
+  const names = [];
+  for (const asset of [...(sprite.costumes ?? []), ...(sprite.sounds ?? [])]) {
+    if (asset && asset.md5ext) names.push(asset.md5ext);
+  }
+  return [...new Set(names)];
+}
+
+/** Decompile one sprite target into standalone `.tfx` source. */
+export function spriteSource(sprite, options) {
+  return decompileProject({ targets: [sprite] }, options);
+}
+
+/** Pack a sprite target and its assets into a `.pms` archive. */
+export function spriteArchive(sprite, assets) {
+  const files = [
+    { name: "sprite.json", data: Buffer.from(JSON.stringify(sprite)) },
+  ];
+  for (const name of spriteAssets(sprite)) {
+    if (!ASSET_NAME.test(name))
+      throw new Error(`Unsafe asset name ${JSON.stringify(name)}`);
+    const data = assets.get(name);
+    if (!data)
+      throw new Error(
+        `Missing asset ${name} for sprite ${JSON.stringify(sprite.name)}`,
+      );
+    files.push({ name, data });
+  }
+  return zipSync(files);
+}
+
+/**
+ * Read a `.sprite3`/`.pms` archive, or bare `sprite.json` with no assets.
+ * @param {Buffer|Uint8Array} input
+ * @returns {{sprite: object, assets: Map<string, Buffer>}}
+ */
+export function readSprite(input) {
+  const bytes = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  const text = bytes.toString("utf8").trimStart();
+  const assets = new Map();
+
+  let sprite;
+  if (text.startsWith("{")) {
+    sprite = JSON.parse(text);
+    if (spriteAssets(sprite).length > 0)
+      throw new Error(
+        "That JSON has costumes or sounds but no assets; use the .sprite3/.pms archive",
+      );
+  } else {
+    const files = unzipSync(bytes);
+    const json = files.get("sprite.json");
+    if (!json) throw new Error("Not a sprite archive: missing sprite.json");
+    sprite = JSON.parse(json.toString("utf8"));
+    for (const name of spriteAssets(sprite)) {
+      if (!ASSET_NAME.test(name))
+        throw new Error(`Unsafe asset name ${JSON.stringify(name)}`);
+      const data = files.get(name);
+      if (!data) throw new Error(`Sprite archive is missing asset ${name}`);
+      assets.set(name, data);
+    }
+  }
+
+  if (!sprite || typeof sprite !== "object" || Array.isArray(sprite))
+    throw new Error("sprite.json must contain a target object");
+  if (sprite.isStage) throw new Error("That archive is a stage, not a sprite");
+  if (!sprite.name) throw new Error("sprite.json has no name");
+  return { sprite, assets };
+}

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

@@ -0,0 +1,6 @@
+{
+  "name": "@penguinmod/packager",
+  "version": "1.9.2",
+  "commit": "53f868b85ec21d2edab9ce00fd2d709da93da6d6",
+  "builtAt": "2026-11-03T06:22:44.624Z"
+}