@triflare/fx 0.0.0-stage → 1.0.1

package/src/index.js

@@ -0,0 +1,35 @@
+/**
+ * Triflare Fx public API.
+ *
+ * @example
+ * import {build} from 'fx';
+ * const {sb3} = build({file: 'src/player.tfx'});
+ * fs.writeFileSync('player.pmp', sb3);
+ */
+export { tokenize } from "./lexer.js";
+export { parse } from "./parser.js";
+export { Compiler, compile } from "./compiler.js";
+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,
+  extensionDataUri,
+  readExtensionDataUri,
+} from "./extensions.js";
+export { readSprite, spriteArchive, spriteSource } from "./sprite.js";
+export { packageProject, loadPackager, packagerDistPath } from "./packager.js";
+export {
+  applyCustomHtml,
+  extractArchive,
+  packageExtension,
+  packageOutputPath,
+  packageSignature,
+  resolvePackageConfig,
+  slugify,
+} from "./package.js";
+export { formatDevUrls, injectDevClient, startDevServer } from "./dev.js";
+export * from "./catalog.js";
+export * from "./config.js";
+export { FxError, LexError, ParseError, CompileError } from "./errors.js";

package/src/language.js

@@ -0,0 +1,12 @@
+/**
+ * Triflare Fx language modules, browser-safe.
+ *
+ * Unlike the root `@triflare/fx` entry point, this subpath only
+ * re-exports the lexer, parser, error types and block catalog: pure ESM with
+ * no Node built-ins, so it can be bundled for browsers, web workers and
+ * editor tooling (e.g. the VS Code extension under `editors/vscode/`).
+ */
+export { tokenize } from "./lexer.js";
+export { parse } from "./parser.js";
+export { FxError, LexError, ParseError } from "./errors.js";
+export * from "./catalog.js";

package/src/lexer.js

@@ -0,0 +1,202 @@
+/**
+ * Triflare Fx lexer.
+ *
+ * Produces a flat list of tokens with 1-based line/column information so that
+ * downstream errors can point at the exact source location.
+ */
+import { LexError } from "./errors.js";
+
+const PUNCTUATION = [
+  // longest first so that greedy matching works
+  "+=",
+  "-=",
+  "*=",
+  "/=",
+  "==",
+  "!=",
+  "<=",
+  ">=",
+  "&&",
+  "||",
+  "{",
+  "}",
+  "(",
+  ")",
+  "[",
+  "]",
+  ",",
+  ";",
+  ":",
+  ".",
+  "=",
+  "<",
+  ">",
+  "+",
+  "-",
+  "*",
+  "/",
+  "%",
+  "!",
+];
+
+const isIdentStart = (ch) => /[A-Za-z_$]/.test(ch);
+const isIdentPart = (ch) => /[A-Za-z0-9_$]/.test(ch);
+const isDigit = (ch) => ch >= "0" && ch <= "9";
+
+/**
+ * @typedef {object} Token
+ * @property {'ident'|'number'|'string'|'punct'|'eof'} type
+ * @property {string} value
+ * @property {number} line
+ * @property {number} column
+ */
+
+/**
+ * Tokenize a Triflare Fx source string.
+ * @param {string} source
+ * @param {string} [file]
+ * @returns {Token[]}
+ */
+export function tokenize(source, file = "<input>") {
+  const tokens = [];
+  let i = 0;
+  let line = 1;
+  let column = 1;
+
+  const push = (type, value, startLine, startColumn) => {
+    tokens.push({ type, value, line: startLine, column: startColumn, file });
+  };
+
+  const fail = (message, startLine = line, startColumn = column) => {
+    throw new LexError(message, {
+      file,
+      line: startLine,
+      column: startColumn,
+      source,
+    });
+  };
+
+  const advance = (n = 1) => {
+    for (let k = 0; k < n; k++) {
+      if (source[i] === "\n") {
+        line++;
+        column = 1;
+      } else {
+        column++;
+      }
+      i++;
+    }
+  };
+
+  while (i < source.length) {
+    const ch = source[i];
+
+    // --- whitespace -----------------------------------------------------
+    if (ch === " " || ch === "\t" || ch === "\r" || ch === "\n") {
+      advance();
+      continue;
+    }
+
+    // --- comments -------------------------------------------------------
+    if (ch === "/" && source[i + 1] === "/") {
+      while (i < source.length && source[i] !== "\n") advance();
+      continue;
+    }
+    if (ch === "/" && source[i + 1] === "*") {
+      const startLine = line;
+      const startColumn = column;
+      advance(2);
+      while (i < source.length && !(source[i] === "*" && source[i + 1] === "/"))
+        advance();
+      if (i >= source.length)
+        fail("Unterminated block comment", startLine, startColumn);
+      advance(2);
+      continue;
+    }
+
+    const startLine = line;
+    const startColumn = column;
+
+    // --- strings --------------------------------------------------------
+    if (ch === '"' || ch === "'") {
+      const quote = ch;
+      advance();
+      let out = "";
+      while (i < source.length && source[i] !== quote) {
+        if (source[i] === "\\") {
+          const next = source[i + 1];
+          const escapes = {
+            n: "\n",
+            t: "\t",
+            r: "\r",
+            '"': '"',
+            "'": "'",
+            "\\": "\\",
+          };
+          if (next in escapes) {
+            out += escapes[next];
+            advance(2);
+          } else {
+            out += next ?? "";
+            advance(2);
+          }
+        } else {
+          out += source[i];
+          advance();
+        }
+      }
+      if (i >= source.length)
+        fail("Unterminated string literal", startLine, startColumn);
+      advance(); // closing quote
+      push("string", out, startLine, startColumn);
+      continue;
+    }
+
+    // --- numbers --------------------------------------------------------
+    if (isDigit(ch) || (ch === "." && isDigit(source[i + 1]))) {
+      let out = "";
+      while (i < source.length && (isDigit(source[i]) || source[i] === ".")) {
+        out += source[i];
+        advance();
+      }
+      if (i < source.length && /[eE]/.test(source[i])) {
+        out += source[i];
+        advance();
+        if (source[i] === "+" || source[i] === "-") {
+          out += source[i];
+          advance();
+        }
+        while (i < source.length && isDigit(source[i])) {
+          out += source[i];
+          advance();
+        }
+      }
+      push("number", out, startLine, startColumn);
+      continue;
+    }
+
+    // --- identifiers ----------------------------------------------------
+    if (isIdentStart(ch)) {
+      let out = "";
+      while (i < source.length && isIdentPart(source[i])) {
+        out += source[i];
+        advance();
+      }
+      push("ident", out, startLine, startColumn);
+      continue;
+    }
+
+    // --- punctuation ----------------------------------------------------
+    const punct = PUNCTUATION.find((p) => source.startsWith(p, i));
+    if (punct) {
+      advance(punct.length);
+      push("punct", punct, startLine, startColumn);
+      continue;
+    }
+
+    fail(`Unexpected character ${JSON.stringify(ch)}`, startLine, startColumn);
+  }
+
+  push("eof", "", line, column);
+  return tokens;
+}

package/src/log.js

@@ -0,0 +1,70 @@
+import { formatWithOptions, styleText } from "node:util";
+import { brand } from "./brand.js";
+
+// The CLI has no logging dependency, so this is the reporter. Glyphs and colors
+// still come from product.yml, which keeps the terminal voice in one place.
+const TYPES = {
+  success: { symbol: "success", color: "green" },
+  error: { symbol: "error", color: "red" },
+  warn: { symbol: "progress", color: "yellow" },
+};
+
+function stringify(message) {
+  if (typeof message === "string") return message;
+  if (message instanceof Error) return message.stack ?? message.message;
+  return formatWithOptions({ colors: false }, message);
+}
+
+// styleText's own escape for a color, so a line can be re-colored after a
+// nested brand-colored word resets the foreground.
+function colorOpen(color, stream) {
+  const marker = "\u0000";
+  const sample = styleText(color, marker, { stream });
+  const index = sample.indexOf(marker);
+  return index > 0 ? sample.slice(0, index) : "";
+}
+
+function paint(text, color, stream) {
+  if (!color) return text;
+  const open = colorOpen(color, stream);
+  let painted = styleText(color, text, { stream });
+  if (open) {
+    painted = painted.replaceAll("\x1b[39m", `\x1b[39m${open}`);
+    if (painted.endsWith(open)) painted = painted.slice(0, -open.length);
+  }
+  return painted;
+}
+
+export function createLogger(product = brand(), streams = {}) {
+  const stdout = streams.stdout ?? process.stdout;
+  const stderr = streams.stderr ?? process.stderr;
+  const symbol = (name) => product.symbols?.[name] ?? "";
+
+  function report(type, message) {
+    const { symbol: glyph, color } = TYPES[type];
+    const mark = symbol(glyph);
+    const stream = type === "success" ? stdout : stderr;
+    const output = stringify(message)
+      .split("\n")
+      .map((line) => paint(mark ? `${mark} ${line}` : line, color, stream))
+      .join("\n");
+    stream.write(`${output}\n`);
+  }
+
+  function mark(name, message) {
+    const glyph = symbol(name);
+    stdout.write(`${glyph ? `${glyph} ` : ""}${stringify(message)}\n`);
+  }
+
+  return {
+    success: (message) => report("success", message),
+    error: (message) => report("error", message),
+    warn: (message) => report("warn", message),
+    progress: (message) => mark("progress", message),
+    bullet: (message) => {
+      const glyph = symbol("bullet");
+      stdout.write(`  ${glyph ? `${glyph} ` : ""}${stringify(message)}\n`);
+    },
+    info: (message) => stdout.write(`${stringify(message)}\n`),
+  };
+}

package/src/package.js

@@ -0,0 +1,202 @@
+/**
+ * Packaging helpers shared by `fx package`, `fx dev`, and the public API.
+ *
+ * `fx.yml` values can be inline text or a `{ file: "..." }` reference. File
+ * references are resolved here, relative to the directory that contains
+ * `fx.yml`, before the packager sees them.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { outputDirectory } from "./brand.js";
+import { DEFAULT_PACKAGE, normalizePackageTarget } from "./config.js";
+
+/** Turn a project name into a filesystem-friendly slug. */
+export function slugify(name) {
+  return (
+    String(name || "project")
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "project"
+  );
+}
+
+/** @param {unknown} value @param {string} label @param {string} baseDir */
+function readTextSource(value, label, baseDir) {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && typeof value.file === "string") {
+    const file = path.resolve(baseDir, value.file);
+    try {
+      return fs.readFileSync(file, "utf8");
+    } catch (err) {
+      throw new Error(`Could not read ${label} from ${file}: ${err.message}`, {
+        cause: err,
+      });
+    }
+  }
+  throw new Error(`${label} must be text or { file: "<path>" }`);
+}
+
+/**
+ * Resolve file-backed values and paths in a normalized `package:` block.
+ *
+ * @param {typeof DEFAULT_PACKAGE} [pkg]
+ * @param {{baseDir?: string, projectName?: string}} [options]
+ * @returns {{
+ *   target: string,
+ *   output: string|null,
+ *   extract: boolean,
+ *   name: string|null,
+ *   version: string|null,
+ *   icon: string|null,
+ *   custom: {js: string, css: string, html: string},
+ *   options: object,
+ *   baseDir: string,
+ * }}
+ */
+export function resolvePackageConfig(pkg = DEFAULT_PACKAGE, options = {}) {
+  const baseDir = path.resolve(options.baseDir || process.cwd());
+  const projectName = options.projectName || null;
+  return {
+    target: normalizePackageTarget(pkg.target),
+    output: pkg.output ? path.resolve(baseDir, pkg.output) : null,
+    extract: Boolean(pkg.extract),
+    name: pkg.name || projectName || null,
+    version: pkg.version || null,
+    icon: pkg.icon ? path.resolve(baseDir, pkg.icon) : null,
+    custom: {
+      js: readTextSource(pkg.custom?.js, "package.custom.js", baseDir),
+      css: readTextSource(pkg.custom?.css, "package.custom.css", baseDir),
+      html: readTextSource(pkg.custom?.html, "package.custom.html", baseDir),
+    },
+    options: pkg.options || {},
+    baseDir,
+  };
+}
+
+/** Whether a target produces an HTML file rather than a ZIP archive. */
+export function isHtmlTarget(target) {
+  return normalizePackageTarget(target) === "html";
+}
+
+/** File extension for a packager target. */
+export function packageExtension(target) {
+  return isHtmlTarget(target) ? ".html" : ".zip";
+}
+
+/**
+ * Pick an output path. A directory (existing, or ending in a slash) gets the
+ * default filename appended; an extensionless path gets the target extension.
+ *
+ * @param {{target: string, output?: string|null, name?: string|null, dir?: string}} options
+ * @returns {string}
+ */
+export function packageOutputPath(options) {
+  const dir = path.resolve(options.dir || process.cwd());
+  const extension = packageExtension(options.target);
+  const filename = `${slugify(options.name)}${extension}`;
+  if (!options.output) return path.join(dir, outputDirectory(), filename);
+
+  const requested = path.resolve(dir, String(options.output));
+  let isDirectory;
+  try {
+    isDirectory = fs.statSync(requested).isDirectory();
+  } catch {
+    isDirectory = /[\\/]$/.test(String(options.output));
+  }
+  if (isDirectory) return path.join(requested, filename);
+  if (!path.extname(requested)) return `${requested}${extension}`;
+  return requested;
+}
+
+/** A stable signature of resolved package settings, for dev rebuilds. */
+export function packageSignature(pkg) {
+  let signature = JSON.stringify(pkg);
+  if (pkg.icon) {
+    try {
+      const stat = fs.statSync(pkg.icon);
+      signature += `:icon:${stat.size}:${stat.mtimeMs}`;
+    } catch {
+      // The packager will report the missing icon with a better message.
+    }
+  }
+  return signature;
+}
+
+/**
+ * Insert custom HTML just before the closing body tag. If a document has no
+ * body tag (for example a fragment), append it instead.
+ *
+ * @param {string} html
+ * @param {string} customHtml
+ * @returns {string}
+ */
+export function applyCustomHtml(html, customHtml) {
+  if (!customHtml) return html;
+  const block = `<!-- fx: custom html -->\n${customHtml}\n`;
+  if (/<\/body\s*>/i.test(html)) {
+    return html.replace(/<\/body\s*>/i, `${block}</body>`);
+  }
+  return `${html}${html.endsWith("\n") ? "" : "\n"}${block}`;
+}
+
+/**
+ * Apply custom HTML inside a packaged ZIP archive by replacing its index.html.
+ * The packager has no native HTML hook, so this is how desktop and zip targets
+ * get the same custom HTML as the plain HTML target.
+ *
+ * @param {Buffer|Uint8Array} data
+ * @param {string} customHtml
+ * @returns {Promise<Buffer>}
+ */
+export async function applyCustomHtmlToArchive(data, customHtml) {
+  if (!customHtml) return Buffer.from(data);
+  const { default: JSZip } = await import("jszip");
+  const zip = await JSZip.loadAsync(data);
+  const index = zip.file("index.html");
+  if (!index) throw new Error("Packaged archive is missing index.html");
+  const html = await index.async("string");
+  zip.file("index.html", applyCustomHtml(html, customHtml), {
+    date: index.date,
+    unixPermissions: index.unixPermissions,
+  });
+  return zip.generateAsync({
+    type: "nodebuffer",
+    compression: "DEFLATE",
+    platform: "UNIX",
+  });
+}
+
+/**
+ * Extract a packaged ZIP to a directory, preserving unix execute bits (which
+ * desktop builds need for their launchers).
+ *
+ * @param {Buffer|Uint8Array} data
+ * @param {string} destination
+ * @returns {Promise<string[]>} written file names
+ */
+export async function extractArchive(data, destination) {
+  const { default: JSZip } = await import("jszip");
+  const zip = await JSZip.loadAsync(data);
+  const root = path.resolve(destination);
+  const written = [];
+
+  for (const [name, entry] of Object.entries(zip.files)) {
+    const target = path.resolve(root, name);
+    const relative = path.relative(root, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+      throw new Error(`Refusing to extract unsafe path: ${name}`);
+    if (entry.dir) {
+      fs.mkdirSync(target, { recursive: true });
+      continue;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, await entry.async("nodebuffer"));
+    if (entry.unixPermissions)
+      fs.chmodSync(target, entry.unixPermissions & 0o777);
+    written.push(name);
+  }
+
+  return written;
+}

package/src/packager.js

@@ -0,0 +1,177 @@
+/**
+ * Thin wrapper around the vendored PenguinMod Packager Node API.
+ *
+ * The packager is copied into `vendor/pm-packager-dist` by
+ * `scripts/build-packager.js`. It is a CommonJS UMD bundle, so it is loaded
+ * with a dynamic import and validated before use.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { DEFAULT_PACKAGE, normalizePackageTarget } from "./config.js";
+import {
+  applyCustomHtml,
+  applyCustomHtmlToArchive,
+  slugify,
+} from "./package.js";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const DIST = path.join(ROOT, "vendor", "pm-packager-dist", "dist");
+const ENTRY = path.join(DIST, "packager.js");
+
+let cached = null;
+
+/** Absolute path of the generated packager distribution. */
+export function packagerDistPath() {
+  return DIST;
+}
+
+/**
+ * Import the vendored packager, with a useful error when it has not been built.
+ * @returns {Promise<{Packager: Function, Image: Function, loadProject: Function}>}
+ */
+export async function loadPackager() {
+  if (cached) return cached;
+  if (!fs.existsSync(ENTRY)) {
+    throw new Error(
+      "The PenguinMod Packager is not built. Run `npm run build:packager` " +
+        "from the Triflare Fx checkout (or reinstall the package).",
+    );
+  }
+  const mod = await import(pathToFileURL(ENTRY).href);
+  const api = mod.default ?? mod;
+  if (
+    !api ||
+    typeof api.Packager !== "function" ||
+    typeof api.loadProject !== "function"
+  ) {
+    throw new Error(
+      `The PenguinMod Packager at ${ENTRY} did not export the expected API.`,
+    );
+  }
+  cached = api;
+  return cached;
+}
+
+function isPlainObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Merge partial packager options without dropping nested defaults. */
+function mergeOptions(target, source) {
+  for (const [key, value] of Object.entries(source || {})) {
+    if (isPlainObject(value) && isPlainObject(target[key]))
+      mergeOptions(target[key], value);
+    else target[key] = value;
+  }
+  return target;
+}
+
+/** @param {string} html @param {string} customHtml */
+function htmlWithCustomization(html, customHtml) {
+  return applyCustomHtml(html, customHtml);
+}
+
+/**
+ * Package `.pmp` bytes into an HTML file or ZIP archive.
+ *
+ * @param {object} options
+ * @param {Buffer|Uint8Array} options.sb3 Project archive bytes.
+ * @param {string} [options.projectName] Used for the window title and package name.
+ * @param {ReturnType<import("./package.js").resolvePackageConfig>} [options.packageConfig]
+ * @returns {Promise<{
+ *   data: Buffer,
+ *   type: "text/html"|"application/zip",
+ *   filename: string,
+ *   target: string,
+ *   html: string|null,
+ * }>}
+ */
+export async function packageProject(options = {}) {
+  const Packager = await loadPackager();
+  const config = options.packageConfig || {
+    ...DEFAULT_PACKAGE,
+    target: "html",
+    custom: { ...DEFAULT_PACKAGE.custom },
+    options: {},
+  };
+  const target = normalizePackageTarget(config.target);
+  const displayName = config.name || options.projectName || "Packaged Project";
+  const packageName = slugify(displayName);
+
+  const loaded = await Packager.loadProject(
+    Buffer.from(options.sb3 ?? []),
+    options.onProgress,
+  );
+  const packager = new Packager.Packager();
+  packager.project = loaded;
+
+  mergeOptions(packager.options, config.options || {});
+  packager.options.target = target;
+
+  // The packager's defaults already fill in app metadata ("Packaged Project"),
+  // so only leave those defaults in place when the user set them explicitly.
+  const appOptions = config.options?.app || {};
+  packager.options.app ||= {};
+  if (appOptions.windowTitle === undefined)
+    packager.options.app.windowTitle = displayName;
+  if (appOptions.packageName === undefined)
+    packager.options.app.packageName = packageName;
+  if (appOptions.version === undefined)
+    packager.options.app.version = config.version || "1.0.0";
+
+  packager.options.custom ||= {};
+  packager.options.custom.js = config.custom?.js || "";
+  packager.options.custom.css = config.custom?.css || "";
+
+  if (config.icon) {
+    if (path.extname(config.icon).toLowerCase() !== ".png")
+      throw new Error(
+        `Packager icons must be PNG files; received ${path.basename(config.icon)}`,
+      );
+    let icon;
+    try {
+      icon = fs.readFileSync(config.icon);
+    } catch (err) {
+      throw new Error(
+        `Could not read package icon ${config.icon}: ${err.message}`,
+        { cause: err },
+      );
+    }
+    packager.options.app.icon = new Packager.Image("image/png", icon);
+  }
+
+  if (options.onEvent && typeof packager.addEventListener === "function") {
+    for (const [event, listener] of Object.entries(options.onEvent))
+      packager.addEventListener(event, listener);
+  }
+
+  const result = await packager.package();
+  const customHtml = config.custom?.html || "";
+  const isHtml = result.type === "text/html";
+  let data;
+  let html = null;
+  let type;
+
+  if (isHtml) {
+    html =
+      typeof result.data === "string"
+        ? result.data
+        : Buffer.from(result.data).toString("utf8");
+    html = htmlWithCustomization(html, customHtml);
+    data = Buffer.from(html);
+    type = "text/html";
+  } else {
+    data = Buffer.from(result.data);
+    if (customHtml) data = await applyCustomHtmlToArchive(data, customHtml);
+    type = "application/zip";
+  }
+
+  return {
+    data,
+    type,
+    filename: result.filename,
+    target,
+    html,
+  };
+}