@geastack/core 0.1.42 → 0.1.44

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
   }
 }
 
@@ -468,9 +491,9 @@ function resolveAppleNativeAliasModules(appDir) {
 // another target replaces with its own implementation.
 // Each replacement names the app's STAGED copy when there is one: the compat
 // build compiles the staged tree, so an alias into the app directory itself
-// pulled a second copy of every module the replacement imports (skytail's
-// mosaico kit index brought its own kit-types.ts, and the two KitCategory
-// records refused to convert).
+// pulled a second copy of every module the replacement imports (a game's
+// board-specific index brought its own copy of a shared types module, and the
+// two copies of one record type refused to convert).
 function resolveAppModuleAliases(appDir, stagedAppDir = appDir) {
   let manifest = {}
   try {
@@ -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')
@@ -556,7 +580,7 @@ function writeCompatViteConfig({ configPath, compatSrcDir, appDir, stagedAppDir,
   // disambiguate, and — with all types erased — geatsc is forced to lower the
   // whole reactive runtime dynamically (gea_cpp_value, ill-formed auto-vectors,
   // proxy derefs). From source, everything is typed and lowers natively, exactly
-  // like three.js/hono/mongodb. The env var still wins when explicitly set;
+  // like the third-party libraries an app imports. The env var still wins when explicitly set;
   // otherwise follow ordinary package resolution, including hoisted installs.
   const compilerRuntimeEntry = process.env.GEA_COMPILER_RUNTIME_SOURCE || resolveCompilerRuntimeEntry([appDir, coreRoot])
   const compilerRuntimeAlias = compilerRuntimeEntry && fs.existsSync(compilerRuntimeEntry)

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)

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

@@ -11,6 +11,7 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
+import { fileAssetBundle, fileAssetLoader } from "./gea-file-asset-bundle.mjs";
 
 const args = process.argv.slice(2);
 
@@ -1060,6 +1061,7 @@ function generatedCpp(fonts, families) {
   // this TU too (a weak symbol can't be defined twice in one TU); `font_data`
   // points at the shared symbol either way.
   const atlasSymbols = new Map();
+  const atlasEntries = [];
   for (const font of fonts) {
     const hash = createHash("sha1")
       .update(Buffer.from(font.atlasData))
@@ -1069,14 +1071,23 @@ function generatedCpp(fonts, families) {
     font.atlasSymbol = symbol;
     if (atlasSymbols.has(hash)) continue;
     atlasSymbols.set(hash, symbol);
+    atlasEntries.push({ symbol, data: font.atlasData });
+  }
+  const bundle = fileAssetBundle(appDir, outCpp, 'fonts', atlasEntries);
+  if (bundle) lines.unshift('#include "platform/asset_bundle.h"');
+  for (const { symbol, data } of atlasEntries) {
+    if (bundle) {
+      lines.push(`__attribute__((weak)) GEA_FILE_ASSET_BUFFER std::uint8_t ${symbol}[${Math.max(1, data.length)}];`);
+      continue;
+    }
     // `extern` + initializer: a namespace-scope `const` is internal by default,
     // and `weak` requires external linkage ("weak declaration must be public").
     lines.push(
-      `extern __attribute__((weak)) const std::uint8_t ${symbol}[${font.atlasData.length}] = {`,
+      `extern __attribute__((weak)) const std::uint8_t ${symbol}[${data.length}] = {`,
     );
-    for (let i = 0; i < font.atlasData.length; i += 32) {
+    for (let i = 0; i < data.length; i += 32) {
       const chunk = Array.from(
-        font.atlasData.slice(i, Math.min(i + 32, font.atlasData.length)),
+        data.slice(i, Math.min(i + 32, data.length)),
       );
       lines.push(
         `    ${chunk.map((byte) => `0x${byte.toString(16).padStart(2, "0")}`).join(", ")},`,
@@ -1085,6 +1096,7 @@ function generatedCpp(fonts, families) {
     lines.push("};");
     lines.push("");
   }
+  if (bundle) lines.push(...fileAssetLoader(bundle, 'prepareFontAssets'));
 
   for (const font of fonts) {
     // `atlasBits` defaults to 8 in RasterizedFontData, so an 8-bit atlas leaves
@@ -1144,12 +1156,14 @@ function generatedCpp(fonts, families) {
   lines.push("");
   lines.push(`void ${names.ensureLinked}()`);
   lines.push("{");
+  if (bundle) lines.push('    (void)prepareFontAssets();');
   lines.push("}");
   lines.push("");
   lines.push(
     `const gea::framework::graphics::RasterizedFontData *${names.lookupFont}(int fontId)`,
   );
   lines.push("{");
+  if (bundle) lines.push('    if (!prepareFontAssets()) return nullptr;');
   lines.push("    for (const auto &entry : generated_fonts) {");
   lines.push(
     "        if (entry.font && entry.font->id == fontId) return entry.font;",
@@ -1162,6 +1176,7 @@ function generatedCpp(fonts, families) {
     `const gea::framework::graphics::RasterizedFontData *${names.lookupFontForFamily}(int familyId, int sizePx)`,
   );
   lines.push("{");
+  if (bundle) lines.push('    if (!prepareFontAssets()) return nullptr;');
   lines.push("    const RasterizedFontData *best = nullptr;");
   lines.push("    int bestDiff = 2147483647;");
   lines.push("    for (const auto &entry : generated_fonts) {");
@@ -1510,7 +1525,13 @@ function writeFileIfChanged(filePath, contents) {
 function writeGeneratedFonts() {
   const fontFaces = collectSourceFontFaces();
   const tuples = collectUsedFontTuples(fontFaces);
-  const familyNames = [...new Set(tuples.map((tuple) => tuple.family))].sort();
+  // Runtime fonts are selected at actual layout time, including CSS variables
+  // and programmatic styles with no statically discoverable family/size tuple.
+  // Keep every explicitly declared local face; raster-only builds retain their
+  // existing tuple-pruned size/charset policy.
+  const familyNames = runtimeTtfFonts
+    ? [...fontFaces.keys()].sort()
+    : [...new Set(tuples.map((tuple) => tuple.family))].sort();
   const families = familyNames.map((name, id) => ({ id, name }));
   const familyIds = new Map(families.map((family) => [family.name, family.id]));
 

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

@@ -0,0 +1,46 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { resolveAppGeaVitePlugin } from '../gea-vite-plugin-resolution.mjs'
+
+test('declared app plugin honors its real package/version and symlink; undeclared alone inherits Core', () => {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'gea-plugin-resolution-')))
+  try {
+    const app = path.join(root,'app'), core = path.join(root,'core')
+    for (const p of [app,core]) { fs.mkdirSync(p); fs.writeFileSync(path.join(p,'package.json'),'{}') }
+    const install = (parent, version) => {
+      const pkg=path.join(parent,'node_modules/@geajs/vite-plugin'); fs.mkdirSync(pkg,{recursive:true})
+      fs.writeFileSync(path.join(pkg,'package.json'),JSON.stringify({name:'@geajs/vite-plugin',version,type:'module',exports:{'.':{import:'./index.mjs'}}}))
+      fs.writeFileSync(path.join(pkg,'index.mjs'),`export const version=${JSON.stringify(version)}`)
+      return pkg
+    }
+    const legacy=install(core,'1.4.1')
+    assert.equal(resolveAppGeaVitePlugin(app,path.join(core,'package.json')),path.join(legacy,'index.mjs'))
+    fs.writeFileSync(path.join(app,'package.json'),JSON.stringify({devDependencies:{'@geajs/vite-plugin':'file:../source'}}))
+    assert.throws(()=>resolveAppGeaVitePlugin(app,path.join(core,'package.json')),/App declares/)
+    const source=install(root,'1.5.0')
+    fs.mkdirSync(path.join(app,'node_modules/@geajs'),{recursive:true})
+    fs.symlinkSync(source,path.join(app,'node_modules/@geajs/vite-plugin'))
+    assert.equal(resolveAppGeaVitePlugin(app,path.join(core,'package.json')),path.join(source,'index.mjs'))
+    fs.unlinkSync(path.join(source,'index.mjs'))
+    assert.throws(()=>resolveAppGeaVitePlugin(app,path.join(core,'package.json')),/App declares/)
+  } finally { fs.rmSync(root,{recursive:true,force:true}) }
+})
+
+test('declared app plugin hoisted to its npm workspace root resolves; an unlisted ancestor install does not', () => {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'gea-plugin-workspace-')))
+  try {
+    const app = path.join(root,'apps/clock'), stray = path.join(root,'tools/stray'), core = path.join(root,'core')
+    for (const p of [app,stray,core]) fs.mkdirSync(p,{recursive:true})
+    for (const p of [app,stray]) fs.writeFileSync(path.join(p,'package.json'),JSON.stringify({devDependencies:{'@geajs/vite-plugin':'^1.4.2'}}))
+    fs.writeFileSync(path.join(core,'package.json'),'{}')
+    fs.writeFileSync(path.join(root,'package.json'),JSON.stringify({private:true,workspaces:['apps/*']}))
+    const pkg=path.join(root,'node_modules/@geajs/vite-plugin'); fs.mkdirSync(pkg,{recursive:true})
+    fs.writeFileSync(path.join(pkg,'package.json'),JSON.stringify({name:'@geajs/vite-plugin',version:'1.4.2',type:'module',exports:{'.':{import:'./index.mjs'}}}))
+    fs.writeFileSync(path.join(pkg,'index.mjs'),'export const version="1.4.2"')
+    assert.equal(resolveAppGeaVitePlugin(app,path.join(core,'package.json')),path.join(pkg,'index.mjs'))
+    assert.throws(()=>resolveAppGeaVitePlugin(stray,path.join(core,'package.json')),/App declares/)
+  } finally { fs.rmSync(root,{recursive:true,force:true}) }
+})