embedded-react 0.1.0

package/assets/emit-c.mjs

@@ -0,0 +1,187 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Emits the generated C for baked assets: one .c with the image pixel arrays + font BitmapFont data,
+// and one .h declaring er_register_assets(). The .c depends only on the public engine header
+// (er_scene.h, which exposes both er_image_load/er_font_register and the BitmapFont format), so it
+// drops into any target's build the same way the bundle does.
+
+/** Sanitizes an asset/family name into a C identifier fragment. */
+function cIdent(name) {
+  let id = String(name).replace(/[^0-9a-zA-Z_]/g, '_');
+  if (id && /[0-9]/.test(id[0])) id = '_' + id;
+  return id || '_asset';
+}
+
+/** Formats an array of byte/word strings into wrapped C initializer lines. */
+function rows(values, perLine, indent = '    ') {
+  const out = [];
+  for (let i = 0; i < values.length; i += perLine) {
+    out.push(indent + values.slice(i, i + perLine).join(', ') + ',');
+  }
+  return out.join('\n');
+}
+
+/** Emits the GlyphInfo designated-initializer for one glyph. */
+function glyphInit(g) {
+  return (
+    `{ .bitmap_offset = ${g.bitmapOffset}, .width = ${g.width}, .height = ${g.height}, ` +
+    `.x_offset = ${g.xOffset}, .y_offset = ${g.yOffset}, .advance = ${g.advance} }`
+  );
+}
+
+/**
+ * Builds the .c and .h text for a set of baked images and fonts.
+ *
+ * @param {object} opts
+ * @param {string} opts.headerName       Basename of the .h (for the .c's #include).
+ * @param {Array<object>} [opts.images]  Results from bakeImage().
+ * @param {Array<object>} [opts.fonts]   Results from bakeFont().
+ * @returns {{c:string, h:string}}
+ */
+export function emitAssetsC({ headerName, images = [], fonts = [] }) {
+  const guard = 'ER_' + cIdent(headerName).toUpperCase();
+  const h =
+    `/* Generated by bridges/quickjs/js/assets — DO NOT EDIT. */\n` +
+    `#ifndef ${guard}\n#define ${guard}\n\n` +
+    `#ifdef __cplusplus\nextern "C"\n{\n#endif\n\n` +
+    `    /** @brief Registers every baked image and font with the engine (call once at boot, after\n` +
+    `     *         embedded_renderer_set_backend()). */\n` +
+    `    void er_register_assets(void);\n\n` +
+    `#ifdef __cplusplus\n}\n#endif\n\n` +
+    `#endif\n`;
+
+  const lines = [];
+  lines.push(`/* Generated by bridges/quickjs/js/assets — DO NOT EDIT. */`);
+  lines.push(`/* Images: premultiplied ARGB8888, referenced by pointer. Fonts: baked BitmapFont per size. */`);
+  lines.push(``);
+  lines.push(`#include "${headerName}"`);
+  lines.push(`#include "er_scene.h" /* er_image_load, er_font_register, BitmapFont */`);
+  lines.push(`#include <stddef.h>`);
+  lines.push(`#include <stdint.h>`);
+  lines.push(``);
+
+  // --- Images ---------------------------------------------------------------------------------
+  for (const img of images) {
+    const id = cIdent(img.name);
+    const hex = Array.from(img.pixels, (p) => '0x' + p.toString(16).toUpperCase().padStart(8, '0') + 'u');
+    lines.push(`/* image "${img.name}" — ${img.width}x${img.height} */`);
+    lines.push(`static const uint32_t ${id}_px[] = {`);
+    lines.push(rows(hex, 8));
+    lines.push(`};`);
+    lines.push(``);
+  }
+
+  // --- Fonts ----------------------------------------------------------------------------------
+  const fontRegistrations = [];
+  for (const font of fonts) {
+    const famId = cIdent(font.family);
+    lines.push(`/* font "${font.family}" — ${font.sizes.map((s) => `${s.pixelSize}px`).join(', ')} */`);
+    emitFontSizes(lines, font, famId, 'static const '); // file-local: only er_register_assets refers to these
+    for (const sz of font.sizes) {
+      fontRegistrations.push(`    er_font_register(${JSON.stringify(font.family)}, &g_font_${famId}_${sz.pixelSize});`);
+    }
+  }
+
+  // --- Registration entry point ---------------------------------------------------------------
+  lines.push(`void er_register_assets(void)`);
+  lines.push(`{`);
+  for (const img of images) {
+    lines.push(`    er_image_load(${JSON.stringify(img.name)}, ${cIdent(img.name)}_px, ${img.width}, ${img.height});`);
+  }
+  for (const reg of fontRegistrations) lines.push(reg);
+  if (images.length === 0 && fontRegistrations.length === 0) {
+    lines.push(`    /* no baked assets */`);
+  }
+  lines.push(`}`);
+  lines.push(``);
+
+  return { c: lines.join('\n'), h };
+}
+
+/** Emits the per-size BitmapFont blocks (bitmap + glyphs + extras + struct) for one font. */
+function emitFontSizes(lines, font, symbol, fontStorage) {
+  for (const sz of font.sizes) {
+    const prefix = `s_${symbol}_${sz.pixelSize}`;
+    const hex = sz.bitmap.map((b) => '0x' + b.toString(16).toUpperCase().padStart(2, '0'));
+    lines.push(`static const uint8_t ${prefix}_bitmap[${sz.bitmap.length || 1}] = {`);
+    lines.push(sz.bitmap.length ? rows(hex, 16) : '    0x00,');
+    lines.push(`};`);
+    lines.push(``);
+
+    lines.push(`static const GlyphInfo ${prefix}_glyphs[${sz.dense.length}] = {`);
+    for (const g of sz.dense) lines.push(`    ${glyphInit(g)},`);
+    lines.push(`};`);
+    lines.push(``);
+
+    if (sz.extras.length) {
+      lines.push(`static const ExtraGlyph ${prefix}_extras[${sz.extras.length}] = {`);
+      for (const e of sz.extras) {
+        lines.push(`    { .codepoint = 0x${e.codepoint.toString(16).toUpperCase()}, .info = ${glyphInit(e.info)} },`);
+      }
+      lines.push(`};`);
+      lines.push(``);
+    }
+
+    lines.push(`${fontStorage}BitmapFont g_font_${symbol}_${sz.pixelSize} = {`);
+    lines.push(`    .bitmap       = ${prefix}_bitmap,`);
+    lines.push(`    .glyphs       = ${prefix}_glyphs,`);
+    lines.push(`    .extras       = ${sz.extras.length ? `${prefix}_extras` : 'NULL'},`);
+    lines.push(`    .extras_count = ${sz.extras.length},`);
+    lines.push(`    .first        = 0x${sz.first.toString(16).toUpperCase()},`);
+    lines.push(`    .last         = 0x${sz.last.toString(16).toUpperCase()},`);
+    lines.push(`    .pixel_size   = ${sz.pixelSize},`);
+    lines.push(`    .line_height  = ${sz.lineHeight},`);
+    lines.push(`    .baseline     = ${sz.baseline},`);
+    lines.push(`    .format       = ${sz.bpp},`);
+    lines.push(`};`);
+    lines.push(``);
+  }
+}
+
+/**
+ * Emits the engine's built-in font translation unit (font_data.c format): the per-size BitmapFont
+ * structs plus the `g_<symbol>_sizes[]` array + `_count` that font_registry.c falls back to. Depends
+ * only on font_bitmap.h. Symbol must be 'inter' to satisfy the extern decls in font_bitmap.h.
+ *
+ * @param {object} opts
+ * @param {object} opts.font        Result of bakeFont().
+ * @param {string} [opts.symbol]    C symbol prefix (default 'inter').
+ * @param {string} [opts.sourceName] Source font filename, for the header comment.
+ * @returns {string} The .c source text.
+ */
+export function emitBuiltinFont({ font, symbol = 'inter', sourceName = '' }) {
+  const sizesStr = font.sizes.map((s) => s.pixelSize).join(',');
+  const bpp = font.sizes[0] ? font.sizes[0].bpp : 4;
+  const lines = [];
+  lines.push(`/* AUTO-GENERATED by bridges/quickjs/js/assets/build-builtin-font.mjs — do not edit by hand.`);
+  lines.push(` * Source : ${sourceName}`);
+  lines.push(` * Sizes  : ${sizesStr}  (bpp ${bpp}, family "${font.family}")`);
+  lines.push(` * Regenerate: cd bridges/quickjs/js && npm run build:builtin-font`);
+  lines.push(` */`);
+  lines.push(`#include "font_bitmap.h"`);
+  lines.push(`#include <stddef.h>`);
+  lines.push(``);
+
+  emitFontSizes(lines, font, symbol, 'const '); // file-scope const: referenced by g_<symbol>_sizes
+
+  lines.push(`const BitmapFont *const g_${symbol}_sizes[] = {`);
+  for (const sz of font.sizes) lines.push(`    &g_font_${symbol}_${sz.pixelSize},`);
+  lines.push(`};`);
+  lines.push(`const size_t g_${symbol}_sizes_count = sizeof(g_${symbol}_sizes) / sizeof(g_${symbol}_sizes[0]);`);
+  lines.push(``);
+  return lines.join('\n');
+}

package/assets/emit-container.mjs

@@ -0,0 +1,121 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// ERCF — the embedded-react config container: one self-describing blob holding an app's compiled
+// QuickJS bytecode plus its asset pack, with a version stamp and an integrity CRC. This is the
+// universal "a config" unit the device-agnostic loader (er_runtime_load_container, in the bridge)
+// verifies and runs — on the desktop demo, an ESP32-S3 partition, or an STM32H7 config region.
+//
+// Two CRCs are NOT the same thing: this internal CRC32 is embedded-react's own integrity check
+// (catches a corrupt/partially-written config). A bootloader's transfer/flash CRC (e.g. SREC_CAT on
+// the STM32H7) is a separate, project-specific step layered on top of this .erpkg by the firmware's
+// upload toolchain.
+//
+// Little-endian (matches the LE hosts: x86 desktop, ESP32-S3, STM32H7). Format:
+//
+//   magic "ERCF" (4 bytes)
+//   format_version u32 = 1
+//   crc32          u32   — CRC-32/IEEE over every byte AFTER this field (offset 12 to end)
+//   qjs_tag        u16 len + bytes   — QuickJS release the bytecode targets (loader rejects mismatch)
+//   section_count  u32
+//   sections[section_count]: type u32, len u32, bytes
+//     type 1 = QuickJS bytecode (run last)
+//     type 2 = ERPK asset pack (registered before the app mounts)
+
+const FORMAT_VERSION = 1;
+
+export const SECTION_BYTECODE = 1;
+export const SECTION_ASSET_PACK = 2;
+
+/**
+ * CRC-32/IEEE (zlib polynomial 0xEDB88320), computed without a lookup table to match the C loader's
+ * crc32_bytes() byte-for-byte.
+ *
+ * @param {Buffer|Uint8Array} buf  Bytes to checksum.
+ * @returns {number} The CRC as an unsigned 32-bit integer.
+ */
+export function crc32(buf) {
+  let crc = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) {
+    crc ^= buf[i];
+    for (let b = 0; b < 8; b++) {
+      crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** Accumulates little-endian binary chunks (mirrors emit-pack.mjs's Writer). */
+class Writer {
+  constructor() {
+    this.chunks = [];
+  }
+  u16(v) {
+    const b = Buffer.alloc(2);
+    b.writeUInt16LE(v & 0xffff, 0);
+    this.chunks.push(b);
+  }
+  u32(v) {
+    const b = Buffer.alloc(4);
+    b.writeUInt32LE(v >>> 0, 0);
+    this.chunks.push(b);
+  }
+  str(s) {
+    const b = Buffer.from(s, 'utf8');
+    this.u16(b.length);
+    this.chunks.push(b);
+  }
+  bytes(buf) {
+    this.chunks.push(Buffer.from(buf));
+  }
+  done() {
+    return Buffer.concat(this.chunks);
+  }
+}
+
+/**
+ * Serializes a compiled app + assets into an ERCF container.
+ *
+ * @param {object} opts
+ * @param {Buffer|Uint8Array} opts.bytecode    QuickJS bytecode blob (.qbc) — required.
+ * @param {Buffer|Uint8Array} [opts.assetPack] ERPK asset pack bytes; omitted/empty → no asset section.
+ * @param {string} opts.qjsTag                 QuickJS release tag the bytecode targets (e.g. "v0.15.0").
+ * @returns {Buffer} The container bytes.
+ */
+export function emitContainer({ bytecode, assetPack, qjsTag }) {
+  if (!bytecode || !bytecode.length) throw new Error('emitContainer: bytecode is required');
+  if (!qjsTag) throw new Error('emitContainer: qjsTag is required');
+
+  // Build the body (everything after the crc32 field) first, then prepend magic+version+crc.
+  const body = new Writer();
+  body.str(qjsTag);
+  const sections = [];
+  if (assetPack && assetPack.length) sections.push([SECTION_ASSET_PACK, assetPack]);
+  sections.push([SECTION_BYTECODE, bytecode]);
+  body.u32(sections.length);
+  for (const [type, data] of sections) {
+    body.u32(type);
+    body.u32(data.length);
+    body.bytes(data);
+  }
+  const bodyBytes = body.done();
+
+  const head = new Writer();
+  head.bytes(Buffer.from('ERCF', 'ascii'));
+  head.u32(FORMAT_VERSION);
+  head.u32(crc32(bodyBytes));
+  return Buffer.concat([head.done(), bodyBytes]);
+}

package/assets/emit-pack.mjs

@@ -0,0 +1,128 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// ERPK — a binary asset pack for the simulator's runtime loader (see /SIMULATOR.md, Phase 2b).
+//
+// Produced from the SAME JS bakers (bake-image.mjs / bake-font.mjs) as the device's baked C, so the
+// simulator renders pixel-identical images and fonts. The sim host (tools/simulator/asset_pack.c)
+// loads this at runtime and calls er_image_load / er_font_register, so assets hot-reload without a
+// sim rebuild. Little-endian (the simulator is x86). Format:
+//
+//   magic "ERPK" (4 bytes), version u32=1, n_images u32, n_font_sizes u32
+//   images[n_images]:    name(u16 len + bytes), width u32, height u32, pixels (w*h * u32 ARGB)
+//   fonts[n_font_sizes]: family(u16 len + bytes), pixel_size/line_height/baseline/format (4*u8),
+//                        first u16, last u16, glyph_count u16, extras_count u16, bitmap_len u32,
+//                        glyphs[glyph_count] (9B: off u32, w/h u8, xo/yo i8, adv u8),
+//                        extras[extras_count] (13B: codepoint u32 + the 9B glyph),
+//                        bitmap (bitmap_len bytes)
+
+const VERSION = 1;
+
+/** Accumulates little-endian binary chunks. */
+class Writer {
+  constructor() {
+    this.chunks = [];
+  }
+  u8(v) {
+    const b = Buffer.alloc(1);
+    b.writeUInt8(v & 0xff, 0);
+    this.chunks.push(b);
+  }
+  i8(v) {
+    const b = Buffer.alloc(1);
+    b.writeInt8(Math.max(-128, Math.min(127, v | 0)), 0);
+    this.chunks.push(b);
+  }
+  u16(v) {
+    const b = Buffer.alloc(2);
+    b.writeUInt16LE(v & 0xffff, 0);
+    this.chunks.push(b);
+  }
+  u32(v) {
+    const b = Buffer.alloc(4);
+    b.writeUInt32LE(v >>> 0, 0);
+    this.chunks.push(b);
+  }
+  str(s) {
+    const b = Buffer.from(s, 'utf8');
+    this.u16(b.length);
+    this.chunks.push(b);
+  }
+  bytes(buf) {
+    this.chunks.push(Buffer.from(buf));
+  }
+  done() {
+    return Buffer.concat(this.chunks);
+  }
+}
+
+/** Writes one glyph record (9 bytes). */
+function writeGlyph(w, g) {
+  w.u32(g.bitmapOffset);
+  w.u8(g.width);
+  w.u8(g.height);
+  w.i8(g.xOffset);
+  w.i8(g.yOffset);
+  w.u8(g.advance);
+}
+
+/**
+ * Serializes baked images + fonts into an ERPK pack.
+ *
+ * @param {object} opts
+ * @param {Array<object>} [opts.images]  Results of bakeImage().
+ * @param {Array<object>} [opts.fonts]   Results of bakeFont().
+ * @returns {Buffer} The pack bytes.
+ */
+export function emitAssetPack({ images = [], fonts = [] }) {
+  const w = new Writer();
+  w.bytes(Buffer.from('ERPK', 'ascii'));
+  w.u32(VERSION);
+  w.u32(images.length);
+  const fontSizes = fonts.reduce((n, f) => n + f.sizes.length, 0);
+  w.u32(fontSizes);
+
+  for (const img of images) {
+    w.str(img.name);
+    w.u32(img.width);
+    w.u32(img.height);
+    // pixels is a Uint32Array (premultiplied ARGB words); copy its LE bytes verbatim.
+    w.bytes(Buffer.from(img.pixels.buffer, img.pixels.byteOffset, img.pixels.byteLength));
+  }
+
+  for (const font of fonts) {
+    for (const sz of font.sizes) {
+      w.str(font.family);
+      w.u8(sz.pixelSize);
+      w.u8(sz.lineHeight);
+      w.u8(sz.baseline);
+      w.u8(sz.bpp);
+      w.u16(sz.first);
+      w.u16(sz.last);
+      w.u16(sz.dense.length);
+      w.u16(sz.extras.length);
+      w.u32(sz.bitmap.length);
+      for (const g of sz.dense) writeGlyph(w, g);
+      for (const e of sz.extras) {
+        w.u32(e.codepoint);
+        writeGlyph(w, e.info);
+      }
+      w.bytes(Buffer.from(sz.bitmap));
+    }
+  }
+
+  return w.done();
+}

package/assets/index.mjs

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Asset baking orchestrator: turns the images and fonts an app imports into a single generated C
+// translation unit (assets.generated.c + .h) exposing er_register_assets(). Invoked by build.mjs
+// after bundling; the example firmware compiles the .c and calls er_register_assets() at boot.
+import fs from 'node:fs';
+import path from 'node:path';
+import { bakeImage } from './bake-image.mjs';
+import { bakeFont } from './bake-font.mjs';
+import { emitAssetsC } from './emit-c.mjs';
+import { emitAssetPack } from './emit-pack.mjs';
+
+/**
+ * Bakes the given assets and writes assets.generated.{c,h} into outDir.
+ *
+ * @param {object} opts
+ * @param {Array<{path:string,name:string}>} [opts.images]  Discovered image imports.
+ * @param {Array<{path:string,family:string,sizes:number[],bpp:number,glyphs:any}>} [opts.fonts]
+ *        Discovered font imports with their resolved size/bpp/glyph config.
+ * @param {string} opts.outDir   Directory to write the generated files into.
+ * @returns {{cPath:string, hPath:string, images:number, fonts:number}}
+ */
+export function bakeAssets({ images = [], fonts = [], outDir }) {
+  const bakedImages = images.map((i) => bakeImage(i));
+  const bakedFonts = fonts.map((f) => bakeFont(f));
+
+  const headerName = 'assets.generated.h';
+  const { c, h } = emitAssetsC({ headerName, images: bakedImages, fonts: bakedFonts });
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const cPath = path.join(outDir, 'assets.generated.c');
+  const hPath = path.join(outDir, headerName);
+  fs.writeFileSync(cPath, c);
+  fs.writeFileSync(hPath, h);
+
+  const fontSizes = bakedFonts.reduce((n, f) => n + f.sizes.length, 0);
+  return { cPath, hPath, images: bakedImages.length, fonts: fontSizes };
+}
+
+/**
+ * Bakes the given assets into a binary ERPK pack the simulator loads at runtime (hot-reloadable),
+ * using the same bakers as bakeAssets so the result is pixel-identical.
+ *
+ * @param {object} opts
+ * @param {Array<{path:string,name:string}>} [opts.images]
+ * @param {Array<{path:string,family:string,sizes:number[],bpp:number,glyphs:any}>} [opts.fonts]
+ * @param {string} opts.outPath  Path to write the .pack file.
+ * @returns {{path:string, bytes:number, images:number, fonts:number}}
+ */
+export function bakeAssetPack({ images = [], fonts = [], outPath }) {
+  const bakedImages = images.map((i) => bakeImage(i));
+  const bakedFonts = fonts.map((f) => bakeFont(f));
+  const pack = emitAssetPack({ images: bakedImages, fonts: bakedFonts });
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, pack);
+  const fontSizes = bakedFonts.reduce((n, f) => n + f.sizes.length, 0);
+  return { path: outPath, bytes: pack.length, images: bakedImages.length, fonts: fontSizes };
+}

package/assets/rasterize.mjs

@@ -0,0 +1,169 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Pure-JS glyph rasterizer — fills an opentype.js Path into a grayscale coverage bitmap with no
+// native dependencies. Curves are flattened to polylines, then each pixel's coverage is computed by
+// scanline-filling at SS× supersampling using the nonzero winding rule (TrueType's convention).
+//
+// The output convention matches what the engine's text renderer expects (see draw_glyph /
+// draw_glyph_aa in engine/text/text_renderer.c): coordinates come from glyph.getPath(0, baseline,
+// pixelSize), so xOffset is the glyph's left bearing from the pen and yOffset is the distance from
+// the line box top (y = 0) down to the top of the glyph ink.
+
+/**
+ * Flattens opentype path commands into closed contours of {x, y} points.
+ *
+ * @param {Array} commands  opentype.js Path commands (M/L/Q/C/Z).
+ * @param {number} steps    Subdivision steps per Bézier curve.
+ * @returns {Array<Array<{x:number,y:number}>>} One point array per contour.
+ */
+function flattenCommands(commands, steps) {
+  const contours = [];
+  let cur = null;
+  let cx = 0;
+  let cy = 0; // current point
+  let sx = 0;
+  let sy = 0; // contour start
+  for (const c of commands) {
+    if (c.type === 'M') {
+      if (cur && cur.length > 1) contours.push(cur);
+      cur = [{ x: c.x, y: c.y }];
+      cx = sx = c.x;
+      cy = sy = c.y;
+    } else if (c.type === 'L') {
+      cur.push({ x: c.x, y: c.y });
+      cx = c.x;
+      cy = c.y;
+    } else if (c.type === 'Q') {
+      for (let i = 1; i <= steps; i++) {
+        const t = i / steps;
+        const mt = 1 - t;
+        cur.push({
+          x: mt * mt * cx + 2 * mt * t * c.x1 + t * t * c.x,
+          y: mt * mt * cy + 2 * mt * t * c.y1 + t * t * c.y,
+        });
+      }
+      cx = c.x;
+      cy = c.y;
+    } else if (c.type === 'C') {
+      for (let i = 1; i <= steps; i++) {
+        const t = i / steps;
+        const mt = 1 - t;
+        cur.push({
+          x: mt * mt * mt * cx + 3 * mt * mt * t * c.x1 + 3 * mt * t * t * c.x2 + t * t * t * c.x,
+          y: mt * mt * mt * cy + 3 * mt * mt * t * c.y1 + 3 * mt * t * t * c.y2 + t * t * t * c.y,
+        });
+      }
+      cx = c.x;
+      cy = c.y;
+    } else if (c.type === 'Z') {
+      if (cur) {
+        cur.push({ x: sx, y: sy }); // close the contour
+        if (cur.length > 1) contours.push(cur);
+        cur = null;
+      }
+    }
+  }
+  if (cur && cur.length > 1) contours.push(cur);
+  return contours;
+}
+
+/**
+ * Rasterizes a glyph path to an 8-bit coverage bitmap (0-255 per pixel).
+ *
+ * @param {object} path        opentype.js Path (from glyph.getPath(0, baseline, pixelSize)).
+ * @param {object} [opts]
+ * @param {number} [opts.ss]    Supersample factor per axis (coverage levels = ss*ss). Default 4.
+ * @param {number} [opts.steps] Bézier subdivision steps. Default 12.
+ * @returns {{width:number,height:number,xOffset:number,yOffset:number,coverage:Uint8Array}}
+ *          An empty (width 0, height 0) result for whitespace / glyphs with no ink.
+ */
+export function rasterize(path, opts = {}) {
+  const ss = opts.ss || 4;
+  const steps = opts.steps || 12;
+  const contours = flattenCommands(path.commands, steps);
+
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const ct of contours) {
+    for (const p of ct) {
+      if (p.x < minX) minX = p.x;
+      if (p.x > maxX) maxX = p.x;
+      if (p.y < minY) minY = p.y;
+      if (p.y > maxY) maxY = p.y;
+    }
+  }
+  if (!Number.isFinite(minX)) {
+    return { width: 0, height: 0, xOffset: 0, yOffset: 0, coverage: new Uint8Array(0) };
+  }
+
+  const x0 = Math.floor(minX);
+  const y0 = Math.floor(minY);
+  const width = Math.ceil(maxX) - x0;
+  const height = Math.ceil(maxY) - y0;
+  if (width <= 0 || height <= 0) {
+    return { width: 0, height: 0, xOffset: 0, yOffset: 0, coverage: new Uint8Array(0) };
+  }
+
+  // Non-horizontal edges, normalized so ylo < yhi; dir is the winding contribution.
+  const edges = [];
+  for (const ct of contours) {
+    for (let i = 0; i + 1 < ct.length; i++) {
+      const a = ct[i];
+      const b = ct[i + 1];
+      if (a.y === b.y) continue;
+      if (a.y < b.y) edges.push({ ylo: a.y, yhi: b.y, x: a.x, dxdy: (b.x - a.x) / (b.y - a.y), dir: 1 });
+      else edges.push({ ylo: b.y, yhi: a.y, x: b.x, dxdy: (a.x - b.x) / (a.y - b.y), dir: -1 });
+    }
+  }
+
+  const counts = new Uint16Array(width * height); // covered subsamples per output pixel
+  const subW = width * ss;
+  for (let sy = 0; sy < height * ss; sy++) {
+    const sampleY = y0 + (sy + 0.5) / ss;
+    const xs = [];
+    for (const e of edges) {
+      if (sampleY >= e.ylo && sampleY < e.yhi) {
+        xs.push({ x: e.x + (sampleY - e.ylo) * e.dxdy, dir: e.dir });
+      }
+    }
+    if (xs.length < 2) continue;
+    xs.sort((p, q) => p.x - q.x);
+    const outRow = (sy / ss) | 0;
+    let wind = 0;
+    for (let i = 0; i + 1 < xs.length; i++) {
+      wind += xs[i].dir;
+      if (wind === 0) continue;
+      // Interior span [xs[i].x, xs[i+1].x): tally the subsample columns whose centre falls inside.
+      let sxa = Math.ceil((xs[i].x - x0) * ss - 0.5);
+      let sxb = Math.ceil((xs[i + 1].x - x0) * ss - 0.5);
+      if (sxa < 0) sxa = 0;
+      if (sxb > subW) sxb = subW;
+      for (let sx = sxa; sx < sxb; sx++) {
+        counts[outRow * width + ((sx / ss) | 0)]++;
+      }
+    }
+  }
+
+  const maxCov = ss * ss;
+  const coverage = new Uint8Array(width * height);
+  for (let i = 0; i < coverage.length; i++) {
+    coverage[i] = Math.round((counts[i] * 255) / maxCov);
+  }
+  return { width, height, xOffset: x0, yOffset: y0, coverage };
+}