embedded-react 0.1.0

package/build.mjs

@@ -0,0 +1,136 @@
+/*
+ * 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.
+ */
+
+// Bundles a demo (React app + reconciler + host config) into a single classic (IIFE) script that
+// QuickJS can run with a plain JS_Eval, and bakes the images/fonts the demo imports into a generated
+// C translation unit (dist/assets.generated.c) exposing er_register_assets(). Globals the bundle
+// expects at runtime (NativeUI, screen, console, timer shims) are provided by the C host (e.g.,
+// examples/linux/main_js.c); the example firmware compiles the generated assets and calls
+// er_register_assets() at boot.
+//
+// Demos live in the top-level demos/ folder, one folder per demo. Pick one with:
+//   npm run build                 # default demo (thermostat)
+//   npm run build -- marine-dash  # a specific demo by folder name
+// Outputs are always dist/app.bundle.js + dist/assets.generated.{c,h} — the single "active" app the
+// example hosts pick up.
+import { build } from 'esbuild';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve, basename } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { bakeAssets } from './assets/index.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url)); // bridges/quickjs/js
+const repoRoot = resolve(here, '../../..');
+const demosDir = resolve(repoRoot, 'demos');
+const libEntry = resolve(here, 'src/embedded-react/index.js');
+const nodeModules = resolve(here, 'node_modules');
+const distDir = resolve(here, 'dist');
+
+const DEFAULT_DEMO = 'thermostat';
+const demo = process.argv[2] || process.env.DEMO || DEFAULT_DEMO;
+const demoDir = resolve(demosDir, demo);
+const entry = resolve(demoDir, 'index.jsx');
+
+if (!existsSync(entry)) {
+  const available = existsSync(demosDir)
+    ? readdirSync(demosDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+    : [];
+  console.error(`Demo "${demo}" not found (expected ${entry}).`);
+  console.error(`Available demos: ${available.join(', ') || '(none)'}`);
+  process.exit(1);
+}
+
+// Asset discovery is import-driven: an `import x from './x.png'` (image) or `import F from './F.ttf'`
+// (font) is intercepted here. The import resolves to the asset's NAME (its file basename) — the
+// string an <Image source>/imageName looks up, or the family a fontFamily uses — and the path is
+// recorded, so it gets baked below. Only what the app imports is baked.
+const images = new Map(); // name -> path
+const fonts = new Map(); // family -> path
+const assetPlugin = {
+  name: 'embedded-react-assets',
+  setup(build) {
+    build.onLoad({ filter: /\.(png|jpe?g|webp|gif|bmp)$/i }, (args) => {
+      const name = basename(args.path).replace(/\.[^.]+$/, '');
+      images.set(name, args.path);
+      return { contents: `module.exports = ${JSON.stringify(name)};`, loader: 'js' };
+    });
+    build.onLoad({ filter: /\.(ttf|otf)$/i }, (args) => {
+      const family = basename(args.path).replace(/\.[^.]+$/, '');
+      fonts.set(family, args.path);
+      return { contents: `module.exports = ${JSON.stringify(family)};`, loader: 'js' };
+    });
+  },
+};
+
+const bundlePath = resolve(distDir, 'app.bundle.js');
+await build({
+  entryPoints: [entry],
+  bundle: true,
+  format: 'iife',
+  outfile: bundlePath,
+  platform: 'neutral',
+  target: 'es2020',
+  jsx: 'automatic',
+  // Demos live outside the embedded-react package, so the package self-reference doesn't resolve for
+  // them: map the bare `embedded-react` import to the library source and let the demo's bare deps
+  // (react, react-reconciler) resolve from this package's node_modules. (The library's own internal
+  // imports still resolve relatively / from node_modules as before.)
+  alias: { 'embedded-react': libEntry },
+  nodePaths: [nodeModules],
+  plugins: [assetPlugin],
+  // Production React: smaller and avoids dev-only warning machinery that needs more shims.
+  define: { 'process.env.NODE_ENV': '"production"' },
+  legalComments: 'none',
+  logLevel: 'info',
+});
+
+console.log(`Bundled demo "${demo}" -> dist/app.bundle.js`);
+
+// --- Bake imported assets ---------------------------------------------------------------------
+// Fonts are pre-rasterized at fixed sizes (the engine has no runtime rasterizer), so bake exactly
+// the literal fontSize values the bundle uses. Computed/dynamic sizes can't be discovered statically
+// and will snap to the nearest baked size at runtime; pin them via assets.config.js if needed.
+const bundleSrc = readFileSync(bundlePath, 'utf8');
+const discoveredSizes = [
+  ...new Set([...bundleSrc.matchAll(/\bfontSize\s*:\s*(\d+(?:\.\d+)?)/g)].map((m) => Math.round(Number(m[1])))),
+].sort((a, b) => a - b);
+
+// Optional per-demo overrides: demos/<demo>/assets.config.js
+//   export default { fonts: { 'Family': { sizes: [..], bpp: 4, glyphs: 'ascii'|'common'|[cps] } } }
+let config = {};
+const configPath = resolve(demoDir, 'assets.config.js');
+if (existsSync(configPath)) {
+  config = (await import(pathToFileURL(configPath).href)).default || {};
+}
+const fontConfig = config.fonts || {};
+
+const fontJobs = [...fonts.entries()].map(([family, path]) => {
+  const fc = fontConfig[family] || {};
+  const sizes = fc.sizes && fc.sizes.length ? fc.sizes : discoveredSizes.length ? discoveredSizes : [16];
+  return { path, family, sizes, bpp: fc.bpp ?? 4, glyphs: fc.glyphs ?? 'ascii' };
+});
+const imageJobs = [...images.entries()].map(([name, path]) => ({ path, name }));
+
+const summary = bakeAssets({ images: imageJobs, fonts: fontJobs, outDir: distDir });
+const fontDesc = fontJobs.length
+  ? fontJobs.map((f) => `${f.family}@[${f.sizes.join(',')}]x${f.bpp}bpp`).join(', ')
+  : 'none';
+console.log(
+  `Baked ${summary.images} image(s), ${summary.fonts} font size(s) -> dist/assets.generated.c\n` +
+    `  fonts: ${fontDesc}`,
+);

package/pack-container.mjs

@@ -0,0 +1,161 @@
+/*
+ * 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 pack [demo]` — builds a deployable ERCF config container (dist/app.erpkg).
+//
+// The full release path for Flow A: bundle the app (esbuild → IIFE), precompile it to QuickJS
+// bytecode (so the device never ships the parser or source text), bake the imported images/fonts into
+// an ERPK pack, and wrap both — with a QuickJS version stamp and an integrity CRC — into a single
+// .erpkg. That one file is "the config": load it with er_runtime_load_container() on the desktop, or
+// upload it to a device's config region. See bridges/quickjs/js/assets/emit-container.mjs for the
+// format, and er_runtime.h for the loader.
+//
+//   npm run pack                 # default demo (thermostat)
+//   npm run pack -- marine-dash  # a specific demo by folder name
+//
+// Prereq: the bytecode precompiler (er-bridge-quickjs-compile) must be built. This script searches the
+// usual build dirs and tells you how to build it if it's missing (override with ER_COMPILE_BIN).
+import { build } from 'esbuild';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve, basename } from 'node:path';
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { bakeImage } from './assets/bake-image.mjs';
+import { bakeFont } from './assets/bake-font.mjs';
+import { emitAssetPack } from './assets/emit-pack.mjs';
+import { emitContainer } from './assets/emit-container.mjs';
+
+// QuickJS release the bytecode targets — MUST match the FetchContent pin in
+// bridges/quickjs/CMakeLists.txt and ER_QUICKJS_TAG in er_runtime.c. The loader rejects a mismatch.
+const QJS_TAG = 'v0.15.0';
+
+const here = dirname(fileURLToPath(import.meta.url)); // bridges/quickjs/js
+const repoRoot = resolve(here, '../../..');
+const demosDir = resolve(repoRoot, 'demos');
+const libEntry = resolve(here, 'src/embedded-react/index.js');
+const nodeModules = resolve(here, 'node_modules');
+const distDir = resolve(here, 'dist');
+
+const demo = process.argv[2] || process.env.DEMO || 'thermostat';
+const demoDir = resolve(demosDir, demo);
+const entry = resolve(demoDir, 'index.jsx');
+if (!existsSync(entry)) {
+  const available = existsSync(demosDir)
+    ? readdirSync(demosDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
+    : [];
+  console.error(`Demo "${demo}" not found (expected ${entry}).`);
+  console.error(`Available demos: ${available.join(', ') || '(none)'}`);
+  process.exit(1);
+}
+
+// --- Locate the bytecode precompiler -----------------------------------------------------------
+const exe = process.platform === 'win32' ? '.exe' : '';
+const compileBin =
+  process.env.ER_COMPILE_BIN ||
+  [
+    resolve(repoRoot, 'bridges/quickjs/build', `er-bridge-quickjs-compile${exe}`),
+    resolve(repoRoot, 'examples/linux/build/bridges/quickjs', `er-bridge-quickjs-compile${exe}`),
+    resolve(repoRoot, 'tools/simulator/build/bridges/quickjs', `er-bridge-quickjs-compile${exe}`),
+  ].find(existsSync);
+if (!compileBin) {
+  console.error('Bytecode precompiler (er-bridge-quickjs-compile) not found. Build it once:');
+  console.error('  cmake -S bridges/quickjs -B bridges/quickjs/build -G "MinGW Makefiles"');
+  console.error('  cmake --build bridges/quickjs/build --target er-bridge-quickjs-compile');
+  console.error('(or set ER_COMPILE_BIN to the binary path)');
+  process.exit(1);
+}
+
+// --- Bundle the app (same import-driven asset discovery as build.mjs) ---------------------------
+const images = new Map(); // name -> path
+const fonts = new Map(); // family -> path
+const assetPlugin = {
+  name: 'embedded-react-assets',
+  setup(b) {
+    b.onLoad({ filter: /\.(png|jpe?g|webp|gif|bmp)$/i }, (args) => {
+      const name = basename(args.path).replace(/\.[^.]+$/, '');
+      images.set(name, args.path);
+      return { contents: `module.exports = ${JSON.stringify(name)};`, loader: 'js' };
+    });
+    b.onLoad({ filter: /\.(ttf|otf)$/i }, (args) => {
+      const family = basename(args.path).replace(/\.[^.]+$/, '');
+      fonts.set(family, args.path);
+      return { contents: `module.exports = ${JSON.stringify(family)};`, loader: 'js' };
+    });
+  },
+};
+
+mkdirSync(distDir, { recursive: true });
+const bundlePath = resolve(distDir, 'app.bundle.js');
+await build({
+  entryPoints: [entry],
+  bundle: true,
+  format: 'iife',
+  outfile: bundlePath,
+  platform: 'neutral',
+  target: 'es2020',
+  jsx: 'automatic',
+  alias: { 'embedded-react': libEntry },
+  nodePaths: [nodeModules],
+  plugins: [assetPlugin],
+  define: { 'process.env.NODE_ENV': '"production"' },
+  legalComments: 'none',
+  logLevel: 'info',
+});
+console.log(`Bundled demo "${demo}" -> dist/app.bundle.js`);
+
+// --- Precompile to QuickJS bytecode -------------------------------------------------------------
+const qbcPath = resolve(distDir, 'app.bundle.qbc');
+const cc = spawnSync(compileBin, [bundlePath, qbcPath], { stdio: 'inherit' });
+if (cc.status !== 0) {
+  console.error('Bytecode compile failed.');
+  process.exit(1);
+}
+const bytecode = readFileSync(qbcPath);
+
+// --- Bake imported assets into an ERPK pack (same sizing rules as build.mjs / sim.mjs) ----------
+const bundleSrc = readFileSync(bundlePath, 'utf8');
+const discoveredSizes = [
+  ...new Set([...bundleSrc.matchAll(/\bfontSize\s*:\s*(\d+(?:\.\d+)?)/g)].map((m) => Math.round(Number(m[1])))),
+].sort((a, b) => a - b);
+
+let config = {};
+const configPath = resolve(demoDir, 'assets.config.js');
+if (existsSync(configPath)) config = (await import(pathToFileURL(configPath).href)).default || {};
+const fontConfig = config.fonts || {};
+
+const fontJobs = [...fonts.entries()].map(([family, path]) => {
+  const fc = fontConfig[family] || {};
+  const sizes = fc.sizes && fc.sizes.length ? fc.sizes : discoveredSizes.length ? discoveredSizes : [16];
+  return { path, family, sizes, bpp: fc.bpp ?? 4, glyphs: fc.glyphs ?? 'ascii' };
+});
+const imageJobs = [...images.entries()].map(([name, path]) => ({ path, name }));
+
+const bakedImages = imageJobs.map((i) => bakeImage(i));
+const bakedFonts = fontJobs.map((f) => bakeFont(f));
+const assetPack = bakedImages.length || bakedFonts.length ? emitAssetPack({ images: bakedImages, fonts: bakedFonts }) : null;
+const fontSizeCount = bakedFonts.reduce((n, f) => n + f.sizes.length, 0);
+
+// --- Wrap into the ERCF container ---------------------------------------------------------------
+const container = emitContainer({ bytecode, assetPack, qjsTag: QJS_TAG });
+const outPath = resolve(distDir, 'app.erpkg');
+writeFileSync(outPath, container);
+
+const kb = (n) => `${(n / 1024).toFixed(1)} KB`;
+console.log(
+  `Packed config -> dist/app.erpkg (${kb(container.length)})\n` +
+    `  qjs ${QJS_TAG} · bytecode ${kb(bytecode.length)}` +
+    (assetPack ? ` · assets ${kb(assetPack.length)} (${bakedImages.length} image(s), ${fontSizeCount} font size(s))` : ' · no assets'),
+);

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "embedded-react",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "React Native-style component package + reconciler that drives the embedded-react C engine through the QuickJS NativeUI bridge (Flow A).",
+  "license": "Apache-2.0",
+  "author": "Cory Lamming",
+  "homepage": "https://github.com/TheMasterCoder007/embedded-react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheMasterCoder007/embedded-react.git",
+    "directory": "bridges/quickjs/js"
+  },
+  "bugs": {
+    "url": "https://github.com/TheMasterCoder007/embedded-react/issues"
+  },
+  "keywords": [
+    "react",
+    "react-native",
+    "embedded",
+    "microcontroller",
+    "esp32",
+    "stm32",
+    "mcu",
+    "jsx",
+    "gui",
+    "ui",
+    "quickjs",
+    "aot"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": "./src/embedded-react/index.js"
+  },
+  "files": [
+    "src/",
+    "aot/",
+    "assets/",
+    "build.mjs",
+    "pack-container.mjs",
+    "persist-transform.mjs",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "!**/__tests__/**",
+    "!**/*.test.js"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "pack": "node pack-container.mjs",
+    "aot": "node aot/compile.mjs",
+    "aot:smoke": "node aot/screenshot-smoke.mjs",
+    "parity": "node parity.mjs",
+    "version:sync": "node ../../../tools/sync-version.mjs",
+    "version:check": "node ../../../tools/sync-version.mjs --check",
+    "release": "node ../../../tools/release.mjs",
+    "build:builtin-font": "node assets/build-builtin-font.mjs",
+    "sim": "node sim.mjs",
+    "create": "node create-embedded-react.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:runtime": "node test/runtime/run.mjs",
+    "test:bytecode": "node test/runtime/run.mjs --bytecode"
+  },
+  "dependencies": {
+    "react": "18.3.1",
+    "react-reconciler": "0.29.2"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.7",
+    "@babel/plugin-syntax-jsx": "^7.29.7",
+    "esbuild": "^0.24.0",
+    "opentype.js": "^2.0.0",
+    "pngjs": "^7.0.0",
+    "vitest": "^2.1.0"
+  }
+}

package/persist-transform.mjs

@@ -0,0 +1,106 @@
+/*
+ * 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.
+ */
+
+// Simulator-only Babel transform: rewrites `useState(init)` in app code to a persisting helper so
+// state transparently survives a hot reload (see /SIMULATOR.md, Phase 3 — transparent variant). Plain
+// `useState` from 'react' just persists in the simulator; on a device (no transform, no __erPersist)
+// it's exactly useState. Only the app's own files are transformed — never the library or React (so
+// the helper itself isn't rewritten).
+//
+// Each call is keyed by `module::component#index` (component name + its useState order), which is
+// stable across the edits you make most often (JSX/logic). Adding/removing a useState in a component,
+// or renaming it, shifts that component's keys and resets its state — press R in the sim for a clean
+// reset any time.
+import { transformSync } from '@babel/core';
+import syntaxJsx from '@babel/plugin-syntax-jsx';
+
+/** Best-effort name of the function/component enclosing a path (for a stable, readable key). */
+function enclosingName(path) {
+  const fn = path.getFunctionParent();
+  if (!fn) return '_';
+  if (fn.node.id && fn.node.id.name) return fn.node.id.name; // function Foo() {}
+  const parent = fn.parentPath && fn.parentPath.node;
+  if (parent) {
+    if (parent.type === 'VariableDeclarator' && parent.id && parent.id.name) return parent.id.name; // const Foo = () =>
+    if (parent.key && parent.key.name) return parent.key.name; // method / property
+    if (parent.type === 'AssignmentExpression' && parent.left && parent.left.name) return parent.left.name;
+  }
+  return '_';
+}
+
+/** Babel plugin: useState(init) → __erPersistState("key", init), importing the helper when used. */
+function persistPlugin({ types: t }) {
+  return {
+    name: 'er-persist-usestate',
+    visitor: {
+      Program: {
+        enter(_path, state) {
+          state.erCounters = new Map();
+          state.erUsed = false;
+        },
+        exit(path, state) {
+          if (!state.erUsed) return;
+          path.unshiftContainer(
+            'body',
+            t.importDeclaration(
+              [t.importSpecifier(t.identifier('__erPersistState'), t.identifier('usePersistentState'))],
+              t.stringLiteral('embedded-react'),
+            ),
+          );
+        },
+      },
+      CallExpression(path, state) {
+        if (!t.isIdentifier(path.node.callee, { name: 'useState' })) return;
+        // Only rewrite the real useState (an imported binding from react / embedded-react).
+        const binding = path.scope.getBinding('useState');
+        if (!binding || binding.kind !== 'module') return;
+        const decl = binding.path.parentPath && binding.path.parentPath.node;
+        const src = decl && decl.source && decl.source.value;
+        if (src !== 'react' && src !== 'embedded-react') return;
+
+        const fnName = enclosingName(path);
+        const idx = state.erCounters.get(fnName) || 0;
+        state.erCounters.set(fnName, idx + 1);
+        const key = `${state.opts.moduleId}::${fnName}#${idx}`;
+
+        path.replaceWith(
+          t.callExpression(t.identifier('__erPersistState'), [t.stringLiteral(key), ...path.node.arguments]),
+        );
+        state.erUsed = true;
+        path.skip();
+      },
+    },
+  };
+}
+
+/**
+ * Applies the persist transform to a module's source.
+ *
+ * @param {string} code      Module source (JSX allowed).
+ * @param {string} moduleId  Stable module identifier (used in keys; e.g. a path relative to the app).
+ * @returns {string} Transformed source (JSX preserved for esbuild to handle).
+ */
+export function transformPersist(code, moduleId) {
+  const out = transformSync(code, {
+    filename: moduleId,
+    babelrc: false,
+    configFile: false,
+    sourceType: 'module',
+    parserOpts: { plugins: ['jsx'] },
+    plugins: [syntaxJsx, [persistPlugin, { moduleId }]],
+  });
+  return out.code;
+}