embedded-react 0.1.0

package/aot/screenshot-smoke.mjs

@@ -0,0 +1,110 @@
+/*
+ * 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.
+ */
+
+// `npm run aot:smoke` — automated compile-and-screenshot smoke test for the Flow B (AOT) demos.
+//
+// For each demo it: (1) compiles App.jsx → dist/app.gen.{c,h} (`node aot/compile.mjs`), (2) rebuilds the
+// linux-aot SDL host (which links the generated C), (3) runs it headless via ER_AOT_SHOT to render ONE
+// frame to a BMP, and (4) checks the image actually has content (distinct colours above a floor) — i.e. it
+// compiled, linked, and rendered something rather than crashing or drawing a blank screen. Exits non-zero
+// if any demo fails, so it can gate CI.
+//
+// Prereq: the linux-aot CMake build must be configurable (SDL2 found). It reuses examples/linux-aot/build;
+// if that isn't configured yet, set CMAKE_TOOLCHAIN_FILE (e.g. a vcpkg toolchain) and it will configure it.
+// Needs a display (SDL video); on a headless box run under a virtual framebuffer.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url)); // bridges/quickjs/js/aot
+const jsDir = resolve(here, '..'); // bridges/quickjs/js
+const repoRoot = resolve(here, '../../../..');
+const exampleDir = resolve(repoRoot, 'examples/linux-aot');
+const buildDir = resolve(exampleDir, 'build');
+const exe = resolve(buildDir, process.platform === 'win32' ? 'embedded-react-desktop-aot.exe' : 'embedded-react-desktop-aot');
+const tmpDir = resolve(jsDir, 'dist', '.smoke');
+
+// Demos to smoke-test. `screen` (optional) sets ER_AOT_SCREEN_W/H so the responsive thermostat folds to its
+// compact (AOT-compilable) branch. `minColors` is the floor of distinct sampled colours for "rendered".
+const DEMOS = [
+  { name: 'music-player', minColors: 40 },
+  { name: 'thermostat', screen: { w: 240, h: 320 }, minColors: 40 },
+];
+
+/** Counts distinct colours in an uncompressed 24/32-bpp BMP (sampled) — a quick "is anything drawn?" signal. */
+function bmpDistinctColors(path, step = 4) {
+  const b = readFileSync(path);
+  if (b[0] !== 0x42 || b[1] !== 0x4d) throw new Error(`not a BMP: ${path}`);
+  const off = b.readUInt32LE(10);
+  const w = b.readInt32LE(18);
+  const h = Math.abs(b.readInt32LE(22));
+  const bpp = b.readUInt16LE(28);
+  if (bpp !== 24 && bpp !== 32) throw new Error(`unexpected BMP bpp ${bpp}`);
+  const bytesPP = bpp / 8;
+  const rowSize = Math.floor((bpp * w + 31) / 32) * 4; // rows padded to 4 bytes
+  const colors = new Set();
+  for (let y = 0; y < h; y += step) {
+    for (let x = 0; x < w; x += step) {
+      const p = off + y * rowSize + x * bytesPP;
+      colors.add((b[p] << 16) | (b[p + 1] << 8) | b[p + 2]); // BGR triplet
+    }
+  }
+  return colors.size;
+}
+
+function run(cmd, args, opts = {}) {
+  execFileSync(cmd, args, { stdio: 'pipe', ...opts });
+}
+
+function ensureConfigured() {
+  if (existsSync(resolve(buildDir, 'CMakeCache.txt'))) return;
+  console.log('• configuring linux-aot build (first run)…');
+  const args = ['-S', exampleDir, '-B', buildDir];
+  if (process.env.CMAKE_TOOLCHAIN_FILE) args.push(`-DCMAKE_TOOLCHAIN_FILE=${process.env.CMAKE_TOOLCHAIN_FILE}`);
+  if (process.platform === 'win32') args.push('-G', 'MinGW Makefiles');
+  run('cmake', args);
+}
+
+let failures = 0;
+mkdirSync(tmpDir, { recursive: true });
+ensureConfigured();
+
+for (const demo of DEMOS) {
+  const shot = resolve(tmpDir, `${demo.name}.bmp`);
+  try {
+    rmSync(shot, { force: true });
+    const genEnv = { ...process.env };
+    if (demo.screen) {
+      genEnv.ER_AOT_SCREEN_W = String(demo.screen.w);
+      genEnv.ER_AOT_SCREEN_H = String(demo.screen.h);
+    }
+    run('node', [resolve(here, 'compile.mjs'), demo.name], { cwd: jsDir, env: genEnv }); // → dist/app.gen.{c,h}
+    run('cmake', ['--build', buildDir]); // relink the generated C
+    run(exe, [], { cwd: buildDir, env: { ...process.env, ER_AOT_SHOT: shot } }); // render one frame → BMP
+
+    if (!existsSync(shot)) throw new Error('no screenshot written (host crashed before present?)');
+    const colors = bmpDistinctColors(shot);
+    if (colors < demo.minColors) throw new Error(`screenshot looks blank (${colors} distinct colours < ${demo.minColors})`);
+    console.log(`✓ ${demo.name}: rendered (${colors} distinct colours)`);
+  } catch (e) {
+    failures++;
+    console.error(`✗ ${demo.name}: ${e.message?.split('\n')[0] || e}`);
+  }
+}
+
+console.log(failures ? `\n${failures} demo(s) failed the smoke test.` : `\nAll ${DEMOS.length} demos compiled, built, and rendered.`);
+process.exit(failures ? 1 : 0);

package/aot/style-map.mjs

@@ -0,0 +1,248 @@
+/*
+ * 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.
+ */
+
+// style-map — lowers RN style keys to ERProps C-struct field assignments for the Flow B AOT compiler.
+//
+// This is the build-time mirror of what native_ui_bridge.c does at runtime in Flow A: it turns a
+// flattened style object into ERProps field writes. The AOT compiler emits those writes as C source
+// (e.g. `p.background_color = 0xFF0F172Au;`) so the generated program builds byte-identical prop bags
+// to Flow A — same defaults (er_props_default), same field values → pixel-identical rendering.
+//
+// Scope: the minimal subset for the first vertical slice (the scaffold counter). Unsupported keys
+// throw with a clear message so the compiler fails loudly instead of silently dropping a style — the
+// supported set grows demo by demo.
+
+/** A few CSS/RN named colors (extend as demos need them); everything else must be hex. */
+const NAMED_COLORS = {
+  transparent: 0x00000000,
+  white: 0xffffffff,
+  black: 0xff000000,
+  red: 0xffff0000,
+  green: 0xff00ff00,
+  blue: 0xff0000ff,
+};
+
+/**
+ * Parses a color string to a packed ARGB8888 unsigned int (matching ERProps color fields).
+ *
+ * @param {string} s  '#rgb' | '#rrggbb' | '#rrggbbaa' (RN order) | a named color.
+ * @returns {number} ARGB8888 as an unsigned 32-bit integer.
+ */
+export function parseColorValue(s) {
+  if (typeof s !== 'string') throw new Error(`color must be a string, got ${typeof s}`);
+  const key = s.trim().toLowerCase();
+  if (key in NAMED_COLORS) return NAMED_COLORS[key] >>> 0;
+  const m = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(key);
+  if (!m) throw new Error(`unsupported color "${s}" (use #rgb / #rrggbb / #rrggbbaa or a named color)`);
+  let hex = m[1];
+  if (hex.length === 3) hex = hex.split('').map((c) => c + c).join(''); // #rgb → #rrggbb
+  let r, g, b, a;
+  if (hex.length === 6) {
+    a = 0xff;
+    r = parseInt(hex.slice(0, 2), 16);
+    g = parseInt(hex.slice(2, 4), 16);
+    b = parseInt(hex.slice(4, 6), 16);
+  } else {
+    // RN 8-digit is #rrggbbaa (alpha last).
+    r = parseInt(hex.slice(0, 2), 16);
+    g = parseInt(hex.slice(2, 4), 16);
+    b = parseInt(hex.slice(4, 6), 16);
+    a = parseInt(hex.slice(6, 8), 16);
+  }
+  return (((a << 24) | (r << 16) | (g << 8) | b) >>> 0);
+}
+
+/** Formats an ARGB int as a C unsigned hex literal, e.g. 0xFF0F172Au. */
+export function colorLiteral(s) {
+  return `0x${parseColorValue(s).toString(16).toUpperCase().padStart(8, '0')}u`;
+}
+
+const ALIGN = {
+  auto: 'ER_ALIGN_AUTO',
+  'flex-start': 'ER_ALIGN_FLEX_START',
+  center: 'ER_ALIGN_CENTER',
+  'flex-end': 'ER_ALIGN_FLEX_END',
+  stretch: 'ER_ALIGN_STRETCH',
+};
+const JUSTIFY = {
+  'flex-start': 'ER_JUSTIFY_FLEX_START',
+  center: 'ER_JUSTIFY_CENTER',
+  'flex-end': 'ER_JUSTIFY_FLEX_END',
+  'space-between': 'ER_JUSTIFY_SPACE_BETWEEN',
+  'space-around': 'ER_JUSTIFY_SPACE_AROUND',
+  'space-evenly': 'ER_JUSTIFY_SPACE_EVENLY',
+};
+const FLEX_DIRECTION = {
+  column: 'ER_FLEX_COL',
+  row: 'ER_FLEX_ROW',
+  'row-reverse': 'ER_FLEX_ROW_REVERSE',
+  'column-reverse': 'ER_FLEX_COL_REVERSE',
+};
+const POSITION = { relative: 'ER_POS_RELATIVE', absolute: 'ER_POS_ABSOLUTE' };
+
+const enumKey = (table, name) => (v) => {
+  const c = table[v];
+  if (!c) throw new Error(`${name}: unsupported value "${v}" (one of ${Object.keys(table).join(', ')})`);
+  return c;
+};
+const dim = (v) => {
+  if (typeof v !== 'number' || !Number.isFinite(v)) throw new Error(`expected a numeric dimension, got ${JSON.stringify(v)}`);
+  return String(Math.round(v));
+};
+
+/**
+ * A dimension that may be a percentage. `'50%'` → the engine's float `*_pct` field (% of the parent);
+ * a number → the pixel field. Used for width / height / flexBasis, which the engine resolves at layout.
+ *
+ * @param {string} pxField   ERProps pixel field (e.g. 'width').
+ * @param {string} pctField  ERProps percentage field (e.g. 'width_pct').
+ */
+const pctOrPx = (pxField, pctField) => (v) => {
+  if (typeof v === 'string' && v.trim().endsWith('%')) {
+    const n = parseFloat(v);
+    if (!Number.isFinite(n)) throw new Error(`expected a percentage like '50%', got ${JSON.stringify(v)}`);
+    // A valid C float literal needs a decimal point — `50f` is a syntax error, `50.0f` is not.
+    const lit = Number.isInteger(n) ? `${n}.0f` : `${n}f`;
+    return [{ field: pctField, expr: lit }];
+  }
+  return [{ field: pxField, expr: dim(v) }];
+};
+
+/**
+ * Per-style-key lowering. Each entry maps a style value to one or more { field, expr } ERProps writes
+ * (field = ERProps C member, expr = C source for the value). `flex` expands to several fields.
+ */
+const KEYS = {
+  // Layout
+  width: pctOrPx('width', 'width_pct'),
+  height: pctOrPx('height', 'height_pct'),
+  flexBasis: pctOrPx('flex_basis', 'flex_basis_pct'),
+  minWidth: (v) => [{ field: 'min_width', expr: dim(v) }],
+  maxWidth: (v) => [{ field: 'max_width', expr: dim(v) }],
+  minHeight: (v) => [{ field: 'min_height', expr: dim(v) }],
+  maxHeight: (v) => [{ field: 'max_height', expr: dim(v) }],
+  padding: (v) => [{ field: 'padding', expr: dim(v) }],
+  paddingHorizontal: (v) => [{ field: 'padding_horizontal', expr: dim(v) }],
+  paddingVertical: (v) => [{ field: 'padding_vertical', expr: dim(v) }],
+  paddingLeft: (v) => [{ field: 'padding_left', expr: dim(v) }],
+  paddingTop: (v) => [{ field: 'padding_top', expr: dim(v) }],
+  paddingRight: (v) => [{ field: 'padding_right', expr: dim(v) }],
+  paddingBottom: (v) => [{ field: 'padding_bottom', expr: dim(v) }],
+  margin: (v) => [{ field: 'margin', expr: dim(v) }],
+  marginHorizontal: (v) => [{ field: 'margin_horizontal', expr: dim(v) }],
+  marginVertical: (v) => [{ field: 'margin_vertical', expr: dim(v) }],
+  marginLeft: (v) => [{ field: 'margin_left', expr: dim(v) }],
+  marginTop: (v) => [{ field: 'margin_top', expr: dim(v) }],
+  marginRight: (v) => [{ field: 'margin_right', expr: dim(v) }],
+  marginBottom: (v) => [{ field: 'margin_bottom', expr: dim(v) }],
+  gap: (v) => [{ field: 'gap', expr: dim(v) }],
+  rowGap: (v) => [{ field: 'row_gap', expr: dim(v) }],
+  columnGap: (v) => [{ field: 'column_gap', expr: dim(v) }],
+  flexGrow: (v) => [{ field: 'flex_grow', expr: dim(v) }],
+  flexShrink: (v) => [{ field: 'flex_shrink', expr: dim(v) }],
+  flexDirection: (v) => [{ field: 'flex_direction', expr: enumKey(FLEX_DIRECTION, 'flexDirection')(v) }],
+  alignItems: (v) => [{ field: 'align_items', expr: enumKey(ALIGN, 'alignItems')(v) }],
+  alignSelf: (v) => [{ field: 'align_self', expr: enumKey(ALIGN, 'alignSelf')(v) }],
+  justifyContent: (v) => [{ field: 'justify_content', expr: enumKey(JUSTIFY, 'justifyContent')(v) }],
+  // Positioning: `position: 'absolute'` takes a node out of flow; left/top/right/bottom are its anchors.
+  position: (v) => [{ field: 'position', expr: enumKey(POSITION, 'position')(v) }],
+  left: (v) => [{ field: 'left', expr: dim(v) }],
+  top: (v) => [{ field: 'top', expr: dim(v) }],
+  right: (v) => [{ field: 'right', expr: dim(v) }],
+  bottom: (v) => [{ field: 'bottom', expr: dim(v) }],
+  // `flex: n` → grow=n, shrink=1, basis=0 (RN semantics; matches native_ui_bridge apply_flex).
+  flex: (v) => {
+    const n = Number(v);
+    if (n > 0) return [{ field: 'flex_grow', expr: dim(n) }, { field: 'flex_shrink', expr: '1' }, { field: 'flex_basis', expr: '0' }];
+    if (n === 0) return [{ field: 'flex_grow', expr: '0' }, { field: 'flex_shrink', expr: '0' }];
+    return [{ field: 'flex_grow', expr: '0' }, { field: 'flex_shrink', expr: '1' }];
+  },
+
+  // View visual
+  backgroundColor: (v) => [{ field: 'background_color', expr: colorLiteral(v) }],
+  borderRadius: (v) => [{ field: 'border_radius', expr: dim(v) }],
+  borderWidth: (v) => [{ field: 'border_width', expr: dim(v) }],
+  borderColor: (v) => [{ field: 'border_color', expr: colorLiteral(v) }],
+  opacity: (v) => [{ field: 'opacity', expr: String(Math.round(Math.max(0, Math.min(1, Number(v))) * 255)) }],
+  zIndex: (v) => [{ field: 'z_index', expr: dim(v) }],
+
+  // Text
+  color: (v) => [{ field: 'color', expr: colorLiteral(v) }],
+  fontSize: (v) => [{ field: 'font_size', expr: dim(v) }],
+  fontWeight: (v) => [{ field: 'font_weight', expr: v === 'bold' || Number(v) >= 600 ? '1' : '0' }],
+  lineHeight: (v) => [{ field: 'line_height', expr: dim(v) }],
+  letterSpacing: (v) => [{ field: 'letter_spacing', expr: dim(v) }],
+};
+
+/**
+ * Lowers one flattened style object to a list of ERProps field assignments.
+ *
+ * @param {object} style  Flattened style (plain key→value; values already statically resolved).
+ * @returns {Array<{field:string, expr:string}>} ERProps writes in declaration order.
+ */
+export function lowerStyle(style) {
+  const out = [];
+  for (const [key, value] of Object.entries(style)) {
+    if (value === undefined || value === null) continue;
+    const fn = KEYS[key];
+    if (!fn) throw new Error(`AOT: unsupported style key "${key}" (not yet lowered to ERProps)`);
+    out.push(...fn(value));
+  }
+  return out;
+}
+
+/** Maps a JSX component tag to its ERNodeType enum (the subset the slice supports). */
+export const NODE_TYPES = {
+  View: 'ER_NODE_VIEW',
+  Text: 'ER_NODE_TEXT',
+  Pressable: 'ER_NODE_PRESSABLE',
+  Image: 'ER_NODE_IMAGE',
+  ScrollView: 'ER_NODE_SCROLL_VIEW',
+};
+
+// Style keys whose value can be DYNAMIC (driven by state). Each maps to its ERProps field + a kind the
+// AOT compiler uses to lower a runtime expression: 'num' → assign a C numeric expression directly;
+// 'opacity' → scale a 0–1 expression to 0–255; 'color' → a (ternary of) color literal(s). Keys absent
+// here (enums like flexDirection, the `flex` shorthand) can only be static for now.
+const NUM_FIELDS = {
+  width: 'width', height: 'height', minWidth: 'min_width', maxWidth: 'max_width', minHeight: 'min_height', maxHeight: 'max_height',
+  padding: 'padding', paddingHorizontal: 'padding_horizontal', paddingVertical: 'padding_vertical',
+  paddingLeft: 'padding_left', paddingTop: 'padding_top', paddingRight: 'padding_right', paddingBottom: 'padding_bottom',
+  margin: 'margin', marginHorizontal: 'margin_horizontal', marginVertical: 'margin_vertical',
+  marginLeft: 'margin_left', marginTop: 'margin_top', marginRight: 'margin_right', marginBottom: 'margin_bottom',
+  gap: 'gap', rowGap: 'row_gap', columnGap: 'column_gap', flexGrow: 'flex_grow', flexShrink: 'flex_shrink',
+  borderRadius: 'border_radius', borderWidth: 'border_width', zIndex: 'z_index',
+  fontSize: 'font_size', lineHeight: 'line_height', letterSpacing: 'letter_spacing',
+};
+
+// Enum style keys that can be state-driven: the value (a string literal or a ternary of them) lowers to the
+// matching ER_* enum constant via its table. Changing one in app_update re-runs layout (props_hash covers it).
+const ENUM_FIELDS = {
+  flexDirection: { field: 'flex_direction', table: FLEX_DIRECTION },
+  alignItems: { field: 'align_items', table: ALIGN },
+  alignSelf: { field: 'align_self', table: ALIGN },
+  justifyContent: { field: 'justify_content', table: JUSTIFY },
+  position: { field: 'position', table: POSITION },
+};
+
+export const DYN_FIELDS = {
+  ...Object.fromEntries(Object.entries(NUM_FIELDS).map(([k, f]) => [k, { field: f, kind: 'num' }])),
+  ...Object.fromEntries(Object.entries(ENUM_FIELDS).map(([k, m]) => [k, { field: m.field, kind: 'enum', table: m.table }])),
+  backgroundColor: { field: 'background_color', kind: 'color' },
+  color: { field: 'color', kind: 'color' },
+  borderColor: { field: 'border_color', kind: 'color' },
+  opacity: { field: 'opacity', kind: 'opacity' },
+};

package/assets/bake-font.mjs

@@ -0,0 +1,190 @@
+/*
+ * 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.
+ */
+
+// Build-time font baker: TrueType/OpenType → the engine's BitmapFont glyph data, at the exact pixel
+// sizes the app uses. Pure JS (opentype.js + the local rasterizer) — no native deps, no Python.
+//
+// The output is consumed zero-copy by er_font_register() (the BitmapFont is a flash-resident const),
+// so there is no runtime rasterizer and no font pool. Per-pixel coverage is packed to the requested
+// bits-per-pixel exactly as engine/text/text_renderer.c decodes it:
+//   bpp 1 → 1 bit/px, MSB = leftmost, set when coverage >= 128
+//   bpp 2 → 4 px/byte, value = round(cov*3/255)   (decoded as value*85)
+//   bpp 4 → 2 px/byte, high nibble = left, value = round(cov*15/255)   (decoded as value*17)
+//   bpp 8 → 1 byte/px, raw coverage
+import fs from 'node:fs';
+import opentype from 'opentype.js';
+import { rasterize } from './rasterize.mjs';
+
+/** Default dense glyph range: printable ASCII (0x20..0x7E). */
+export const ASCII_FIRST = 0x20;
+export const ASCII_LAST = 0x7e;
+
+// Named extra-symbol sets selectable from assets.config.js (glyphs: 'common' | 'minimal' | ...).
+const SYMBOLS_MINIMAL = [
+  0x00b0, 0x00b1, 0x00b5, 0x00d7, 0x00f7, 0x2013, 0x2014, 0x2022, 0x2026, 0x2190, 0x2191, 0x2192,
+  0x2193, 0x2713, 0x2717,
+];
+const SYMBOLS_COMMON = [
+  0x00a2, 0x00a3, 0x00a5, 0x00a7, 0x00a9, 0x00ae, 0x00b0, 0x00b1, 0x00b5, 0x00d7, 0x00f7, 0x2013,
+  0x2014, 0x2018, 0x2019, 0x201c, 0x201d, 0x2020, 0x2021, 0x2022, 0x2026, 0x2030, 0x20ac, 0x2122,
+  0x2190, 0x2191, 0x2192, 0x2193, 0x2194, 0x21b5, 0x2202, 0x2206, 0x221a, 0x221e, 0x2211, 0x2212,
+  0x2248, 0x2260, 0x2264, 0x2265, 0x25a0, 0x25cf, 0x25c6, 0x2605, 0x2606, 0x2713, 0x2717,
+];
+const SYMBOLS_GREEK = [];
+for (let c = 0x0391; c <= 0x03a9; c++) if (c !== 0x03a2) SYMBOLS_GREEK.push(c); // uppercase (skip gap)
+for (let c = 0x03b1; c <= 0x03c9; c++) SYMBOLS_GREEK.push(c); // lowercase
+const SYMBOL_SETS = {
+  none: [],
+  minimal: SYMBOLS_MINIMAL,
+  common: SYMBOLS_COMMON,
+  greek: SYMBOLS_GREEK,
+  'common-greek': [...new Set([...SYMBOLS_COMMON, ...SYMBOLS_GREEK])].sort((a, b) => a - b),
+};
+
+/**
+ * Resolves a glyph-coverage spec into a sorted list of extra (sparse) codepoints.
+ *
+ * @param {string|Array<number>|undefined} glyphs  'ascii' (none), a named set, or explicit codepoints.
+ * @returns {number[]} Sorted extra codepoints outside the dense ASCII range.
+ */
+export function resolveExtras(glyphs) {
+  if (!glyphs || glyphs === 'ascii') return [];
+  let cps;
+  if (Array.isArray(glyphs)) cps = glyphs.slice();
+  else if (SYMBOL_SETS[glyphs]) cps = SYMBOL_SETS[glyphs].slice();
+  else throw new Error(`unknown glyph set "${glyphs}" (use 'ascii', a named set, or a codepoint array)`);
+  return [...new Set(cps)].filter((c) => c < ASCII_FIRST || c > ASCII_LAST).sort((a, b) => a - b);
+}
+
+/**
+ * Packs an 8-bit coverage bitmap (one byte per pixel) into the engine's per-row bpp layout.
+ *
+ * @param {Uint8Array} cov  Row-major coverage, width*height bytes.
+ * @param {number} w        Glyph width in pixels.
+ * @param {number} h        Glyph height in pixels.
+ * @param {number} bpp      Bits per pixel (1, 2, 4, or 8).
+ * @returns {number[]} Packed bytes (row-major, each row padded to a whole byte).
+ */
+function packCoverage(cov, w, h, bpp) {
+  const out = [];
+  if (bpp === 8) {
+    for (let i = 0; i < w * h; i++) out.push(cov[i]);
+    return out;
+  }
+  const maxVal = (1 << bpp) - 1;
+  const perByte = 8 / bpp;
+  const rowBytes = Math.ceil(w / perByte);
+  for (let row = 0; row < h; row++) {
+    for (let b = 0; b < rowBytes; b++) {
+      let byte = 0;
+      for (let s = 0; s < perByte; s++) {
+        const col = b * perByte + s;
+        if (col >= w) continue;
+        const c = cov[row * w + col];
+        const v = bpp === 1 ? (c >= 128 ? 1 : 0) : Math.round((c * maxVal) / 255);
+        byte |= v << (8 - bpp - s * bpp); // first pixel in the high bits
+      }
+      out.push(byte);
+    }
+  }
+  return out;
+}
+
+/**
+ * Rasterizes a single codepoint into a glyph record + appended bitmap bytes.
+ *
+ * @returns {{glyph:object, bytes:number[]}|null} null when the font has no glyph for the codepoint.
+ */
+function bakeGlyph(font, cp, pixelSize, baseline, scale, bpp) {
+  if (font.charToGlyphIndex(String.fromCodePoint(cp)) === 0 && cp !== 0x20) return null;
+  const glyph = font.charToGlyph(String.fromCodePoint(cp));
+  const advance = Math.round(glyph.advanceWidth * scale);
+  const ss = bpp === 8 ? 8 : 4;
+  const steps = Math.max(6, Math.ceil(pixelSize / 3));
+  const r = rasterize(glyph.getPath(0, baseline, pixelSize), { ss, steps });
+
+  if (r.width > 255 || r.height > 255) {
+    throw new Error(`glyph U+${cp.toString(16)} is ${r.width}x${r.height}px — exceeds the uint8 glyph limit`);
+  }
+  const glyphRec = {
+    bitmapOffset: 0, // filled in by the caller once the running offset is known
+    width: r.width,
+    height: r.height,
+    xOffset: r.xOffset,
+    yOffset: r.yOffset,
+    advance: Math.min(advance, 255),
+  };
+  const bytes = r.width > 0 && r.height > 0 ? packCoverage(r.coverage, r.width, r.height, bpp) : [];
+  return { glyph: glyphRec, bytes };
+}
+
+/**
+ * Bakes one font into per-size BitmapFont data.
+ *
+ * @param {object} opts
+ * @param {string} opts.path    Path to the .ttf/.otf file.
+ * @param {string} opts.family  Family name to register under (used by fontFamily lookups).
+ * @param {number[]} opts.sizes Pixel sizes to bake.
+ * @param {number} [opts.bpp]   Bits per pixel (default 4).
+ * @param {string|Array<number>} [opts.glyphs] Extra glyph coverage beyond ASCII (default 'ascii').
+ * @returns {{family:string, sizes:Array<object>}} Baked data ready for the C emitter.
+ */
+export function bakeFont({ path, family, sizes, bpp = 4, glyphs = 'ascii' }) {
+  if (![1, 2, 4, 8].includes(bpp)) throw new Error(`bpp must be 1, 2, 4, or 8 (got ${bpp})`);
+  const font = opentype.parse(fs.readFileSync(path).buffer);
+  const extraCps = resolveExtras(glyphs);
+
+  const baked = [];
+  for (const pixelSize of sizes) {
+    const scale = pixelSize / font.unitsPerEm;
+    const baseline = Math.round(font.ascender * scale);
+    const lineHeight = baseline + Math.round(-font.descender * scale);
+
+    const bitmap = [];
+    const dense = [];
+    for (let cp = ASCII_FIRST; cp <= ASCII_LAST; cp++) {
+      const baked1 = bakeGlyph(font, cp, pixelSize, baseline, scale, bpp) || {
+        glyph: { bitmapOffset: 0, width: 0, height: 0, xOffset: 0, yOffset: 0, advance: Math.round(pixelSize / 2) },
+        bytes: [],
+      };
+      baked1.glyph.bitmapOffset = baked1.bytes.length > 0 ? bitmap.length : 0;
+      bitmap.push(...baked1.bytes);
+      dense.push(baked1.glyph);
+    }
+
+    const extras = [];
+    for (const cp of extraCps) {
+      const b = bakeGlyph(font, cp, pixelSize, baseline, scale, bpp);
+      if (!b) continue; // font has no such glyph
+      b.glyph.bitmapOffset = b.bytes.length > 0 ? bitmap.length : 0;
+      bitmap.push(...b.bytes);
+      extras.push({ codepoint: cp, info: b.glyph });
+    }
+
+    baked.push({
+      pixelSize,
+      lineHeight: Math.min(lineHeight, 255),
+      baseline: Math.min(baseline, 255),
+      first: ASCII_FIRST,
+      last: ASCII_LAST,
+      bpp,
+      dense,
+      extras,
+      bitmap,
+    });
+  }
+  return { family, sizes: baked };
+}

package/assets/bake-image.mjs

@@ -0,0 +1,50 @@
+/*
+ * 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.
+ */
+
+// Build-time image baker: PNG → premultiplied ARGB8888, the format the engine's image registry
+// references by pointer (er_image_load). Pure JS (pngjs) — no native deps, no Python. The engine
+// scales at render time, so bake at whatever source resolution you want to ship.
+import fs from 'node:fs';
+import { PNG } from 'pngjs';
+
+/**
+ * Decodes an image and returns its premultiplied ARGB8888 pixels (row-major, 0xAARRGGBB).
+ *
+ * @param {object} opts
+ * @param {string} opts.path  Path to the source image.
+ * @param {string} opts.name  Asset name an <Image source>/imageName looks up.
+ * @returns {{name:string, width:number, height:number, pixels:Uint32Array}}
+ */
+export function bakeImage({ path, name }) {
+  if (!/\.png$/i.test(path)) {
+    throw new Error(`image "${path}": only PNG is supported by the baker (convert to PNG, or extend bake-image.mjs)`);
+  }
+  const png = PNG.sync.read(fs.readFileSync(path));
+  const { width, height, data } = png; // data = RGBA, 8-bit, row-major
+  const pixels = new Uint32Array(width * height);
+  for (let i = 0; i < width * height; i++) {
+    const r = data[i * 4];
+    const g = data[i * 4 + 1];
+    const b = data[i * 4 + 2];
+    const a = data[i * 4 + 3];
+    // Premultiply the color channels by alpha (round-to-nearest) — the engine's image format.
+    const rp = Math.floor((r * a + 127) / 255);
+    const gp = Math.floor((g * a + 127) / 255);
+    const bp = Math.floor((b * a + 127) / 255);
+    pixels[i] = ((a << 24) | (rp << 16) | (gp << 8) | bp) >>> 0;
+  }
+  return { name, width, height, pixels };
+}

package/assets/build-builtin-font.mjs

@@ -0,0 +1,51 @@
+/*
+ * 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.
+ */
+
+// Regenerates the engine's built-in font (engine/font/font_data.c) from assets/fonts/Inter-Regular.ttf
+// using the same JS bakers as app assets — this is the single source of truth for the built-in font
+// (there is no Python step). font_registry.c falls back to g_inter_sizes[] for any text without a
+// matching custom family.
+//
+//   cd bridges/quickjs/js && npm run build:builtin-font
+//
+// Regenerating changes glyph metrics slightly vs a prior rasterizer, so re-run the engine text tests
+// (test_text, yoga_parity) and re-flash to eyeball on-device after changing it.
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeFileSync } from 'node:fs';
+import { bakeFont } from './bake-font.mjs';
+import { emitBuiltinFont } from './emit-c.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url)); // bridges/quickjs/js/assets
+const repoRoot = resolve(here, '../../../..');
+const FONT = resolve(repoRoot, 'assets/fonts/Inter-Regular.ttf');
+const OUT = resolve(repoRoot, 'engine/font/font_data.c');
+
+// The built-in covers printable ASCII plus a fixed set of common symbols (degrees, arrows, math,
+// punctuation, etc.) the UI components rely on — kept stable across regenerations.
+const SIZES = [10, 12, 16, 20, 24, 32, 48];
+const EXTRAS = [
+  0x00a2, 0x00a3, 0x00a5, 0x00a7, 0x00a9, 0x00ae, 0x00b0, 0x00b1, 0x00b5, 0x00d7, 0x00f7, 0x2013,
+  0x2014, 0x2018, 0x2019, 0x201c, 0x201d, 0x2020, 0x2021, 0x2022, 0x2026, 0x2030, 0x20ac, 0x2122,
+  0x2190, 0x2191, 0x2192, 0x2193, 0x2194, 0x21b5, 0x2202, 0x2206, 0x2211, 0x2212, 0x221a, 0x221e,
+  0x2248, 0x2260, 0x2264, 0x2265, 0x25a0, 0x25c6, 0x25cf, 0x2605, 0x2606, 0x2713, 0x2717,
+];
+
+const font = bakeFont({ path: FONT, family: 'Inter', sizes: SIZES, bpp: 4, glyphs: EXTRAS });
+writeFileSync(OUT, emitBuiltinFont({ font, symbol: 'inter', sourceName: 'Inter-Regular.ttf' }));
+
+const bytes = font.sizes.reduce((n, s) => n + s.bitmap.length, 0);
+console.log(`Regenerated ${OUT}\n  ${SIZES.length} sizes [${SIZES.join(',')}], bpp 4, ${font.sizes[0].extras.length} extra glyphs, ${bytes} bitmap bytes`);