@geastack/core 0.1.41 → 0.1.43

package/runtime/host.ts

@@ -7,6 +7,8 @@
 // below. lib.dom's GeolocationPositionError also carries PERMISSION_DENIED /
 // POSITION_UNAVAILABLE / TIMEOUT, which our host object never sets.
 import type {
+  UartOptions,
+  MagnetometerReading,
   CanvasRenderingContext2D,
   GeolocationCoordinates,
   GeolocationPosition,
@@ -354,6 +356,32 @@ declare const __gea_Gpio: {
   write(pin: number, level: boolean): boolean
   read(pin: number): boolean
 }
+declare const __gea_Magnetometer: {
+  open(): boolean
+  close(): void
+  count(): number
+  read(index: number, values: Float64Array): boolean
+}
+declare const __gea_Uart: {
+  open(port: number, tx: number, rx: number, baud: number, rxBytes: number, txBytes: number): boolean
+  isOpen(port: number): boolean
+  close(port: number): void
+  read(port: number, buffer: Uint8Array): number
+  write(port: number, buffer: Uint8Array): number
+  available(port: number): number
+  writable(port: number): number
+}
+declare const __gea_EspNow: {
+  open(channel: number, rate: number): boolean
+  setMaxTxPower(quarterDbm: number): boolean
+  getMaxTxPower(): number
+  isOpen(): boolean
+  canSend(): boolean
+  close(): void
+  addPeer(address: Uint8Array, key: Uint8Array): boolean
+  send(address: Uint8Array, bytes: Uint8Array): number
+  receive(source: Uint8Array, bytes: Uint8Array): number
+}
 declare const __gea_Led: {
   // A WS2812/NeoPixel strand on one pin — what "the onboard LED" is on most
   // modern ESP32 modules. set() is the one-call default (attach if needed,
@@ -1031,6 +1059,73 @@ export const Gpio = {
     return __gea_Gpio.read(pin)
   },
 }
+export const Uart = {
+  open(port: number, options: UartOptions): boolean {
+    if (typeof __gea_Uart === 'undefined') return false
+    return __gea_Uart.open(port, options.tx, options.rx, options.baudRate,
+      options.rxBufferSize ?? 4096, options.txBufferSize ?? 4096)
+  },
+  isOpen(port: number): boolean {
+    return typeof __gea_Uart !== 'undefined' && __gea_Uart.isOpen(port)
+  },
+  close(port: number): void {
+    if (typeof __gea_Uart !== 'undefined') __gea_Uart.close(port)
+  },
+  read(port: number, buffer: Uint8Array): number {
+    return typeof __gea_Uart !== 'undefined' ? __gea_Uart.read(port, buffer) : -1
+  },
+  write(port: number, buffer: Uint8Array): number {
+    return typeof __gea_Uart !== 'undefined' ? __gea_Uart.write(port, buffer) : -1
+  },
+  available(port: number): number {
+    return typeof __gea_Uart !== 'undefined' ? __gea_Uart.available(port) : -1
+  },
+  writable(port: number): number {
+    return typeof __gea_Uart !== 'undefined' ? __gea_Uart.writable(port) : -1
+  },
+}
+export const Magnetometer = {
+  open(): boolean {
+    return typeof __gea_Magnetometer !== 'undefined' && __gea_Magnetometer.open()
+  },
+  close(): void {
+    if (typeof __gea_Magnetometer !== 'undefined') __gea_Magnetometer.close()
+  },
+  count(): number {
+    return typeof __gea_Magnetometer !== 'undefined' ? __gea_Magnetometer.count() : 0
+  },
+  read(index: number): MagnetometerReading {
+    const values = new Float64Array(5)
+    const valid = typeof __gea_Magnetometer !== 'undefined' && __gea_Magnetometer.read(index, values)
+    return { x: values[0], y: values[1], z: values[2], valid, saturatedAxes: values[3], timestampUs: values[4] }
+  },
+}
+
+export const EspNow = {
+  // 115 selects S31 HE20 MCS9 short GI (114.7 Mbps); target validation owns
+  // availability. Other rates and the default retain their existing meaning.
+  open(channel: number, rateMbps: number = 54): boolean {
+    return typeof __gea_EspNow !== 'undefined' && __gea_EspNow.open(channel, rateMbps)
+  },
+  setMaxTxPower(quarterDbm: number): boolean {
+    return typeof __gea_EspNow !== 'undefined' && __gea_EspNow.setMaxTxPower(quarterDbm)
+  },
+  getMaxTxPower(): number {
+    return typeof __gea_EspNow !== 'undefined' ? __gea_EspNow.getMaxTxPower() : -1
+  },
+  isOpen(): boolean { return typeof __gea_EspNow !== 'undefined' && __gea_EspNow.isOpen() },
+  canSend(): boolean { return typeof __gea_EspNow !== 'undefined' && __gea_EspNow.canSend() },
+  close(): void { if (typeof __gea_EspNow !== 'undefined') __gea_EspNow.close() },
+  addPeer(address: Uint8Array, key: Uint8Array = new Uint8Array(0)): boolean {
+    return typeof __gea_EspNow !== 'undefined' && __gea_EspNow.addPeer(address, key)
+  },
+  send(address: Uint8Array, bytes: Uint8Array): number {
+    return typeof __gea_EspNow !== 'undefined' ? __gea_EspNow.send(address, bytes) : -1
+  },
+  receive(source: Uint8Array, bytes: Uint8Array): number {
+    return typeof __gea_EspNow !== 'undefined' ? __gea_EspNow.receive(source, bytes) : -1
+  },
+}
 export const Led = {
   set(pin: number, r: number, g: number, b: number): boolean {
     return __gea_Led.set(pin, r, g, b)

package/runtime-surface.ts

@@ -57,8 +57,13 @@ export type {
  * gets today.
  */
 export type {
+  UartOptions,
+  UartController,
+  EspNowController,
   AccelerometerController,
   AccelerometerReading,
+  MagnetometerController,
+  MagnetometerReading,
   AppsController,
   AudioBuffer,
   AudioBufferSourceNode,
@@ -128,6 +133,8 @@ export type {
   InputElementProps,
   InputEvent,
   InputEventTarget,
+  InputElement,
+  ButtonElement,
   KeyEvent,
   MediaDevices,
   MediaRecorder,

package/runtime.cpp

@@ -7,6 +7,7 @@
 #include "input.h"
 #include "memory.h"
 #include "events.h"
+#include "touch.h"
 #include "power.h"
 #include "services/app_runner.h"
 #include "services/app_state.h"
@@ -48,10 +49,89 @@
 #include "ui/document.h"
 #include "ui/tree_internal.h"
 
+#include <atomic>
+#include <cstdint>
+
+extern "C" void gea_cycle_collection_defer_begin() __attribute__((weak));
+extern "C" void gea_cycle_collection_defer_end() __attribute__((weak));
+
 namespace gea::framework {
 
 namespace {
 
+// The low bit is the requested state; the remaining bits distinguish each
+// transition. An acknowledgement of an earlier pause cannot satisfy a new
+// pause after a quick resume. These survive a request made by native boot,
+// before either the UI task or its queue exists.
+std::atomic<std::uint32_t> uiPauseRequest{0};
+std::atomic<std::uint32_t> uiPauseAcknowledged{0};
+
+void discardPausedInput()
+{
+#if !defined(GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT) || !GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT
+	services::AppState::lock();
+	events::TouchRuntime::resetGestureState();
+	services::AppState::unlock();
+	gea::platform::touch::Touchscreen::consumeLatestMove(nullptr, nullptr);
+	(void)input::consumeRotaryDelta();
+	input::HardwareKeyEvent key{};
+	while (input::consumeKeyEvent(key)) {}
+#endif
+}
+
+void discardPausedEvent(const events::Event &event)
+{
+#if !defined(GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT) || !GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT
+	// A move marker must re-arm the controller even though its callback is
+	// dropped; otherwise the first drag after resume can stop producing moves.
+	if (event.type == events::EventType::Touch && event.touchPhase == events::TouchPhase::Move)
+		gea::platform::touch::Touchscreen::consumeLatestMove(nullptr, nullptr);
+#else
+	(void)event;
+#endif
+}
+
+bool acknowledgeUiPause(bool &paused)
+{
+	const auto request = uiPauseRequest.load(std::memory_order_acquire);
+	if ((request & 1U) == 0) return false;
+	if (!paused) {
+		discardPausedInput();
+		paused = true;
+	}
+	// Called only by the event-loop owner, outside dispatch_event/runFrame and
+	// after discardPausedInput has released AppState. No lock is held while the
+	// runtime waits on its queue in the paused state.
+	uiPauseAcknowledged.store(request, std::memory_order_release);
+	return true;
+}
+
+// Input can allocate just like a frame callback, but touch dispatch and the
+// frame's poll/rotary/key prelude run outside Application::frame's lifetime
+// scope. Do not collect while generated callbacks still hold transient native
+// references or the dispatcher is borrowing its current listener.
+class InputCycleCollectionDeferral {
+public:
+	InputCycleCollectionDeferral()
+		: active_(gea_cycle_collection_defer_begin && gea_cycle_collection_defer_end)
+	{
+		if (active_) gea_cycle_collection_defer_begin();
+	}
+	~InputCycleCollectionDeferral()
+	{
+		if (!active_) return;
+		const auto previous = app::applicationFramePhaseRead();
+		app::applicationFramePhaseSet(app::ApplicationFramePhase::CycleCollection);
+		gea_cycle_collection_defer_end();
+		app::applicationFramePhaseSet(previous);
+	}
+	InputCycleCollectionDeferral(const InputCycleCollectionDeferral &) = delete;
+	InputCycleCollectionDeferral &operator=(const InputCycleCollectionDeferral &) = delete;
+
+private:
+	bool active_;
+};
+
 #if defined(GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT) && GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT
 
 void run_app_frame(int timestampMs, void *context)
@@ -96,19 +176,8 @@ void dispatch_key_input()
 		event.bubbles = true;
 		event.cancelable = true;
 
-		const int inputId = tree.activeInputId();
-		bool stopped = false;
-		if (inputId >= 0) {
-			event.targetId = inputId;
-			event.currentTargetId = inputId;
-			tree.dispatchEvent(event);
-			stopped = event.propagationStopped;
-		}
-		if (!stopped) {
-			event.propagationStopped = false;
-			if (key.pressed) gea::embedded::ui::dispatchDocumentKeyDown(event);
-			else gea::embedded::ui::dispatchDocumentKeyUp(event);
-		}
+		event.targetId = tree.activeInputId();
+		gea::embedded::ui::dispatchRootKeyEvent(event);
 	}
 }
 
@@ -116,6 +185,7 @@ void run_app_frame(int timestampMs, void *context)
 {
 	(void)context;
 	const uint32_t nowMs = static_cast<uint32_t>(timestampMs);
+	InputCycleCollectionDeferral deferCycleCollection;
 	// Low-rate platform work shares the runtime event loop. This keeps input and
 	// battery observation deterministic without dedicating several mostly-idle
 	// FreeRTOS tasks (and their stacks) to polling.
@@ -153,7 +223,11 @@ void dispatch_event(const events::Event &event, const RuntimeOptions &options)
 			break;
 		}
 		services::AppState::lock();
-		const bool touchChangedScene = events::TouchRuntime::dispatchEvent(event);
+		bool touchChangedScene;
+		{
+			InputCycleCollectionDeferral deferCycleCollection;
+			touchChangedScene = events::TouchRuntime::dispatchEvent(event);
+		}
 		services::AppState::unlock();
 		// Input-triggered render: a touch that actually ran handlers (down / real
 		// move / up) likely changed the scene, so post a Frame now instead of
@@ -198,6 +272,7 @@ void dispatch_event(const events::Event &event, const RuntimeOptions &options)
 		// A finger held still posts no moves, so gestureActiveWithin() lapses to
 		// false after the window and the loop quiesces — no busy-render on a hold.
 		for (;;) {
+			if (Runtime::uiPauseRequested()) break;
 #if defined(ESP_PLATFORM) && defined(GEA_NATIVE_DEBUGGER) && GEA_NATIVE_DEBUGGER
 			if (services::FrameScheduler::debuggerFrameRate() > 0) break;
 #endif
@@ -213,11 +288,12 @@ void dispatch_event(const events::Event &event, const RuntimeOptions &options)
 			// keep going, instead of returning to the timer-paced outer loop.
 			// drainFramesAndCheckInput() leaves a non-Frame event at the queue
 			// front, so receiveEvent() returns it immediately without blocking.
-			while (services::FrameScheduler::drainFramesAndCheckInput()) {
+			while (!Runtime::uiPauseRequested() && services::FrameScheduler::drainFramesAndCheckInput()) {
 				events::Event pending{};
 				if (!services::FrameScheduler::receiveEvent(&pending)) break;
 				dispatch_event(pending, options);
 			}
+			if (Runtime::uiPauseRequested()) break;
 			services::FrameScheduler::runFrame(frameCallbacks);
 		}
 		// Persist any localStorage writes made this frame (or from a store's
@@ -242,6 +318,40 @@ void dispatch_event(const events::Event &event, const RuntimeOptions &options)
 
 }  // namespace
 
+void Runtime::requestUiPause(bool paused)
+{
+	auto observed = uiPauseRequest.load(std::memory_order_relaxed);
+	for (;;) {
+		if (((observed & 1U) != 0) == paused) return;
+		const auto next = ((observed + 2U) & ~1U) | (paused ? 1U : 0U);
+		if (uiPauseRequest.compare_exchange_weak(observed, next, std::memory_order_acq_rel,
+											  std::memory_order_relaxed)) break;
+	}
+#if !GEA_EMBEDDED_NO_DISPLAY
+	// Before queue creation this harmlessly fails. A full queue is already a
+	// wake-up; an idle runtime receives this event and observes the new request.
+	events::Event wake{};
+	wake.type = events::EventType::Timeout;
+	(void)services::FrameScheduler::sendEvent(wake, 0);
+#endif
+}
+
+bool Runtime::uiPauseRequested()
+{
+	return (uiPauseRequest.load(std::memory_order_acquire) & 1U) != 0;
+}
+
+bool Runtime::uiPaused()
+{
+#if GEA_EMBEDDED_NO_DISPLAY
+	return uiPauseRequested();
+#else
+	const auto request = uiPauseRequest.load(std::memory_order_acquire);
+	return (request & 1U) != 0 && uiPauseAcknowledged.load(std::memory_order_acquire) == request &&
+		   uiPauseRequest.load(std::memory_order_acquire) == request;
+#endif
+}
+
 void Runtime::runNativeBoot()
 {
 	// An app with native hardware of its own (audio, USB host, sensors) brings
@@ -464,10 +574,29 @@ void Runtime::run(const RuntimeOptions &options)
 	// which starves whatever else shares it. boot() was the work; return.
 	(void)options;
 #else
+	bool paused = false;
 	while (true) {
+		if (acknowledgeUiPause(paused)) {
+			events::Event discarded{};
+			if (services::FrameScheduler::receiveEvent(&discarded)) discardPausedEvent(discarded);
+			continue;
+		}
+		if (paused) {
+			discardPausedInput();
+			paused = false;
+			(void)services::FrameScheduler::takeCatchUpRequest();
+			// A paused Frame was consumed without runFrame clearing the target's
+			// coalesced-pending flag. Force one ordinary frame to re-arm its clock;
+			// relying on a timer or a best-effort queue post could leave it stuck.
+			events::Event refresh{};
+			refresh.type = events::EventType::Frame;
+			dispatch_event(refresh, options);
+			continue;
+		}
 		events::Event event{};
 		if (services::FrameScheduler::receiveEvent(&event)) {
-			dispatch_event(event, options);
+			if (uiPauseRequested()) discardPausedEvent(event);
+			else dispatch_event(event, options);
 		}
 	}
 #endif

package/scripts/build-gea-vite-geatsc.mjs

@@ -5,6 +5,7 @@ import process from 'node:process'
 import { spawnSync } from 'node:child_process'
 import { createRequire } from 'node:module'
 import { fileURLToPath, pathToFileURL } from 'node:url'
+import { resolveAppGeaVitePlugin } from './gea-vite-plugin-resolution.mjs'
 import { inlineJsonImports, transformGeaEmbeddedCompatSource } from './gea-embedded-compat-transform.mjs'
 import { normalizeEmbeddedJsxOptions, shouldIgnoreCompatStagingDirectory } from './gea-embedded-compat-staging.mjs'
 import { dotEnvDefines, inlineProcessEnv } from './dotenv-defines.mjs'
@@ -24,7 +25,8 @@ import {
 const nativeModules = new Map()
 let nativeModuleSources = new Map()
 const args = process.argv.slice(2)
-const requireFromLib = createRequire(new URL('../package.json', import.meta.url))
+const corePackageJson = new URL('../package.json', import.meta.url)
+const requireFromLib = createRequire(corePackageJson)
 const coreRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const elementsRoot = path.resolve(coreRoot, '..', 'elements')
 const engineRoot = path.resolve(coreRoot, '..', 'engine')
@@ -74,7 +76,6 @@ function readPackageName(dir) {
 // `paths` entry, so both consumers of the staged tree agree.
 const runtimePath = path.join(coreRoot, 'runtime.ts')
 const tryResolve = (m) => { try { return requireFromLib.resolve(m) } catch { return '' } }
-const geaPluginResolved = fileURLToPath(import.meta.resolve('@geajs/vite-plugin'))
 const { parse } = requireFromLib('@babel/parser')
 const traverseModule = requireFromLib('@babel/traverse')
 const t = requireFromLib('@babel/types')
@@ -211,7 +212,29 @@ function copyCssUrlAssets(srcCss, dstCss) {
     const dstAsset = path.resolve(dstDir, clean)
     if (dstAsset === srcAsset) continue
     fs.mkdirSync(path.dirname(dstAsset), { recursive: true })
-    fs.copyFileSync(srcAsset, dstAsset)
+    copyAssetAtomically(srcAsset, dstAsset)
+  }
+}
+
+// A url() that climbs out of the app lands outside this build's own directory
+// (`../../../assets/fonts/x.ttf` staged under `<build>/<app>/` is
+// `<build>/assets/fonts/x.ttf`), where other builds sharing the parent stage
+// the same file at the same time -- core's app pipelines all do. copyFileSync
+// truncates and rewrites in place, so a concurrent reader saw a partial font
+// ("Offset is outside the bounds of the DataView"). Identical bytes are left
+// alone, and new bytes appear in one rename, never half-written.
+function copyAssetAtomically(srcAsset, dstAsset) {
+  const bytes = fs.readFileSync(srcAsset)
+  if (fs.existsSync(dstAsset) && fs.readFileSync(dstAsset).equals(bytes)) return
+  const staged = `${dstAsset}.${process.pid}.tmp`
+  fs.writeFileSync(staged, bytes)
+  try {
+    fs.renameSync(staged, dstAsset)
+  } catch (error) {
+    // Windows refuses to replace a file another process has open; that
+    // process staged it first, so the bytes it holds are these bytes.
+    fs.rmSync(staged, { force: true })
+    if (!(fs.existsSync(dstAsset) && fs.readFileSync(dstAsset).equals(bytes))) throw error
   }
 }
 
@@ -528,6 +551,7 @@ function resolveGeaThreeAliasModules(appDir) {
 }
 
 function writeCompatViteConfig({ configPath, compatSrcDir, appDir, stagedAppDir, entry, viteOutDir, geaIrPath, appleNative, moduleGraphOutDir, envDefines }) {
+  const geaPluginResolved = resolveAppGeaVitePlugin(appDir, corePackageJson)
   const engineComponentsPath = path.join(engineRoot, 'components/index.ts')
   const engineComponentSubpath = path.join(engineRoot, 'components/$1')
   const elementsPath = path.join(elementsRoot, 'components/index.ts')

package/scripts/gea-file-asset-bundle.mjs

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+export function fileAssetDirectory(manifest) {
+  const storage = manifest?.gea?.embeddedAssets?.storage;
+  if (storage === undefined) return null;
+  if (
+    storage?.type !== "file" ||
+    typeof storage.directory !== "string" ||
+    !storage.directory.startsWith("/") ||
+    storage.directory === "/" ||
+    storage.directory !== path.posix.normalize(storage.directory) ||
+    /[\\\0\r\n]/.test(storage.directory)
+  ) {
+    throw new Error(
+      'gea.embeddedAssets.storage must specify type="file" and a normalized absolute directory',
+    );
+  }
+  return storage.directory;
+}
+
+export function fileAssetBundle(appDir, outCpp, kind, entries) {
+  const manifestFile = path.join(appDir, "package.json");
+  const manifest = fs.existsSync(manifestFile)
+    ? JSON.parse(fs.readFileSync(manifestFile, "utf8"))
+    : {};
+  const directory = fileAssetDirectory(manifest);
+  if (!directory || !entries.length) return null;
+  const bytes = Buffer.concat(entries.map((entry) => Buffer.from(entry.data)));
+  const hash = createHash("sha256").update(bytes).digest("hex");
+  const id = String(manifest.gea?.id || path.basename(appDir)).replace(
+    /[^a-zA-Z0-9_-]/g,
+    "_",
+  );
+  const filename = `${id}-${kind}-${hash}.bin`;
+  const local = path.join(path.dirname(outCpp), filename);
+  const remote = path.posix.join(directory, filename);
+  fs.mkdirSync(path.dirname(local), { recursive: true });
+  if (!fs.existsSync(local) || !fs.readFileSync(local).equals(bytes))
+    fs.writeFileSync(local, bytes);
+  const deployment = {
+    version: 1,
+    files: [{ local, remote, bytes: bytes.length, sha256: hash }],
+  };
+  const metadata = `${outCpp}.assets.json`;
+  const contents = JSON.stringify(deployment, null, 2) + "\n";
+  if (
+    !fs.existsSync(metadata) ||
+    fs.readFileSync(metadata, "utf8") !== contents
+  )
+    fs.writeFileSync(metadata, contents);
+  let crc = 0xffffffff;
+  for (const value of bytes) {
+    crc ^= value;
+    for (let bit = 0; bit < 8; bit++)
+      crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+  }
+  return {
+    entries,
+    remote,
+    bytes: bytes.length,
+    crc: (crc ^ 0xffffffff) >>> 0,
+  };
+}
+
+export function fileAssetLoader(bundle, name) {
+  return [
+    `static bool ${name}() {`,
+    "  static const bool ready = [] {",
+    "    const gea::platform::storage::AssetSegment segments[] = {",
+    ...bundle.entries.map(
+      (entry) => `      {${entry.symbol}, ${entry.data.length}},`,
+    ),
+    "    };",
+    `    return gea::platform::storage::loadAssetBundle(${JSON.stringify(bundle.remote)}, segments, ${bundle.entries.length}, ${bundle.bytes}, ${bundle.crc}U);`,
+    "  }();",
+    "  return ready;",
+    "}",
+    "",
+  ];
+}

package/scripts/gea-native-style-plugin.mjs

@@ -35,7 +35,9 @@ export function geaNativeStylePlugin({ runtimeEntry }) {
       return [path.join(sourceRoot, `${name}.ts`), path.join(sourceRoot, name, 'index.ts')].find(entry => fs.existsSync(entry)) || null
     },
     load(id) {
-      if (id.split('?')[0] !== serializer) return null
+      // Vite spells module ids with forward slashes on Windows too; normalize
+      // before comparing with the native path (a no-op on POSIX).
+      if (path.normalize(id.split('?')[0]) !== serializer) return null
       // This module is the browser serialization boundary, not the JSX IR.
       // Replacing it here preserves numeric values in the native IR and prevents
       // browser px defaults from reaching native runtime-backed components/h().

package/scripts/gea-vite-plugin-resolution.mjs

@@ -0,0 +1,49 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+/** Honor an app's declared compiler plugin; only legacy undeclared apps inherit Core's. */
+function resolveImport(directory) {
+  // Let Node apply real ESM export conditions (the plugin is import-only).
+  const url = execFileSync(process.execPath,
+    ['--input-type=module', '-e', "process.stdout.write(import.meta.resolve('@geajs/vite-plugin'))"],
+    { cwd: directory, encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'pipe'] })
+  return fs.realpathSync(fileURLToPath(url))
+}
+
+function workspaceOwner(appDir) {
+  const app = path.resolve(appDir)
+  if (fs.existsSync(path.join(app, 'node_modules', '@geajs', 'vite-plugin'))) return null
+  for (let dir = path.dirname(app); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+    let manifest
+    try { manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')) } catch { continue }
+    const patterns = Array.isArray(manifest.workspaces) ? manifest.workspaces : manifest.workspaces?.packages ?? []
+    const relative = path.relative(dir, app).split(path.sep).join('/')
+    if (patterns.some(pattern => path.posix.matchesGlob(relative, pattern.replace(/\/+$/, '')))) return dir
+  }
+  return null
+}
+
+export function resolveAppGeaVitePlugin(appDir, corePackageJson) {
+  const manifest = path.join(appDir, 'package.json')
+  // A bare fixture directory has no manifest and so declares no plugin of its own.
+  const app = fs.existsSync(manifest) ? JSON.parse(fs.readFileSync(manifest, 'utf8')) : {}
+  const declared = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']
+    .some(field => Object.hasOwn(app[field] || {}, '@geajs/vite-plugin'))
+  if (!declared) return resolveImport(path.dirname(corePackageJson instanceof URL ? fileURLToPath(corePackageJson) : corePackageJson))
+  // Resolving from the app may otherwise walk up to an unrelated ancestor install.
+  // Require an actual app-owned installation entry, or the hoisted one of an npm
+  // workspace root that lists this app among its workspaces.
+  const installed = path.join(workspaceOwner(appDir) ?? appDir, 'node_modules', '@geajs', 'vite-plugin')
+  try {
+    const packageRoot = fs.realpathSync(installed)
+    const actual = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'))
+    if (actual.name !== '@geajs/vite-plugin') throw new Error('installed package name mismatch')
+    const resolved = resolveImport(appDir)
+    if (!resolved.startsWith(packageRoot + path.sep)) throw new Error('resolved outside declared installation')
+    return resolved
+  } catch (error) {
+    throw new Error(`App declares @geajs/vite-plugin but its installation is unavailable: ${error.message}`)
+  }
+}

package/scripts/generate-gea-embedded-assets.mjs

@@ -24,6 +24,7 @@
 
 import { describeStaticAsset } from './gea-static-asset.mjs'
 import { compileTimeOnlyAssetPaths } from './gea-embedded-asset-policy.mjs'
+import { fileAssetBundle, fileAssetLoader } from './gea-file-asset-bundle.mjs'
 import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
@@ -230,12 +231,19 @@ function writeFileIfChanged(filePath, contents) {
 }
 
 const assets = collectAssets(appDir)
+const bundleEntries = new Map()
+for (const file of assets) {
+  const symbol = assetSymbol(relPath(file))
+  if (!bundleEntries.has(symbol)) bundleEntries.set(symbol, { symbol, data: fs.readFileSync(file) })
+}
+const bundle = fileAssetBundle(appDir, outCpp, 'images', [...bundleEntries.values()])
 
 const parts = []
 parts.push('// Generated by scripts/generate-gea-embedded-assets.mjs. Do not edit by hand.')
 parts.push(`// app: ${relPath(appDir) || path.basename(appDir)}`)
 parts.push('')
 parts.push('#include <cstring>')
+if (bundle) parts.push('#include "platform/asset_bundle.h"')
 parts.push('')
 
 if (assets.length === 0) {
@@ -280,14 +288,23 @@ if (assets.length === 0) {
     // rejects `weak` on an internal const. `extern "C"` + initializer = a weak
     // definition with external, unmangled (namespace-independent) linkage,
     // which both GCC and Clang accept.
-    parts.push(`extern "C" __attribute__((weak)) const unsigned char ${sym}[] = {`)
-    parts.push(byteArrayBody(buffer))
-    parts.push('};')
+    if (bundle) {
+      parts.push(`extern "C" { __attribute__((weak)) GEA_FILE_ASSET_BUFFER unsigned char ${sym}[${Math.max(1, buffer.length)}]; }`)
+    } else {
+      parts.push(`extern "C" __attribute__((weak)) const unsigned char ${sym}[] = {`)
+      parts.push(byteArrayBody(buffer))
+      parts.push('};')
+    }
     parts.push(`extern "C" __attribute__((weak)) const unsigned long ${sym}_len = ${buffer.length}UL;`)
     parts.push('')
   }
+  if (bundle) {
+    parts.push(...fileAssetLoader(bundle, 'prepareImageAssets'))
+    parts.push('extern "C" bool gea_embedded_assets_prepare() { return prepareImageAssets(); }')
+  }
   parts.push('extern "C" __attribute__((weak)) bool gea_embedded_asset_lookup(const char *path, const unsigned char **data, unsigned long *length) {')
   parts.push('  if (!path || !data || !length) return false;')
+  if (bundle) parts.push('  if (!prepareImageAssets()) return false;')
   for (const file of assets) {
     const rel = relPath(file)
     const sym = assetSymbol(rel)