@geastack/core 0.1.39 → 0.1.40

package/scripts/bitmap-font-source.mjs

@@ -0,0 +1,155 @@
+import fs from "node:fs";
+
+function integer(value, name, minimum = 0, maximum = 65535) {
+  if (!Number.isInteger(value) || value < minimum || value > maximum) {
+    throw new Error(`Invalid bitmap font ${name}`);
+  }
+
+  return value;
+}
+
+export function loadBitmapFontSource(filename) {
+  const source = JSON.parse(fs.readFileSync(filename, "utf8"));
+
+  if (
+    source.schemaVersion !== 1 ||
+    source.format !== "gea-bitmap-font" ||
+    !Array.isArray(source.fonts)
+  ) {
+    throw new Error(`Invalid bitmap font source: ${filename}`);
+  }
+
+  return source;
+}
+
+export function buildBitmapFont(source, tuple, packGlyphAtlas) {
+  const face = source.fonts.find((font) => font.sizePx === tuple.sizePx);
+
+  if (!face)
+    throw new Error(
+      `Bitmap font ${tuple.family} has no exact ${tuple.sizePx}px face`,
+    );
+  const lineHeight = integer(face.lineHeight, "lineHeight", 1, 1024);
+  const ascender = integer(face.ascender, "ascender", 0, lineHeight);
+  const descender = integer(face.descender, "descender", 0, lineHeight);
+  if (ascender + descender !== lineHeight)
+    throw new Error("Invalid bitmap font line metrics");
+  const glyphs = [];
+  const bitmaps = [];
+  const available = new Set();
+  const requested = tuple.charset;
+  const fallbackCodepoint =
+    face.fallbackCodepoint === undefined
+      ? -1
+      : integer(face.fallbackCodepoint, "fallbackCodepoint", 0, 0x10ffff);
+
+  if (!Array.isArray(face.glyphs) || face.glyphs.length === 0)
+    throw new Error("Bitmap font has no glyphs");
+  for (const item of face.glyphs) {
+    const cp = integer(item.codepoint, "codepoint", 0, 0x10ffff);
+
+    if (available.has(cp)) throw new Error("Duplicate bitmap font glyph");
+    available.add(cp);
+    const width = integer(item.width, "glyph width", 0, 512);
+    const height = integer(item.height, "glyph height", 0, 512);
+    const advance16 = integer(item.advance16, "advance16", 0, 32767);
+    const bearingX = integer(item.bearingX, "bearingX", -1024, 1024);
+    const bearingY = integer(item.bearingY, "bearingY", -1024, 1024);
+    if (
+      typeof item.coverage !== "string" ||
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+        item.coverage,
+      )
+    ) {
+      throw new Error("Invalid bitmap glyph coverage encoding");
+    }
+
+    const coverage = Buffer.from(item.coverage, "base64");
+
+    if (coverage.length !== width * height)
+      throw new Error("Invalid bitmap glyph coverage length");
+    if (
+      requested &&
+      !requested.has(cp) &&
+      cp !== 63 &&
+      cp !== fallbackCodepoint
+    )
+      continue;
+    glyphs.push({
+      codepoint: cp,
+      sourceX: 0,
+      sourceY: 0,
+      width,
+      height,
+      advance: (advance16 + 8) >> 4,
+      bearingX,
+      bearingY,
+      advance16,
+    });
+    bitmaps.push(coverage);
+  }
+
+  if (fallbackCodepoint >= 0 && !available.has(fallbackCodepoint))
+    throw new Error("Bitmap fallback glyph is absent");
+  if (glyphs.length === 0)
+    throw new Error("Bitmap font charset selects no available glyphs");
+  const records = glyphs
+    .map((glyph, index) => ({ glyph, bitmap: bitmaps[index] }))
+    .sort((a, b) => a.glyph.codepoint - b.glyph.codepoint);
+  const sortedGlyphs = records.map((record) => record.glyph);
+  const { atlasWidth, atlasHeight } = packGlyphAtlas(sortedGlyphs);
+  const width = Math.max(1, atlasWidth);
+  const height = Math.max(1, atlasHeight);
+  const atlasData = new Uint8Array(width * height);
+
+  for (const { glyph, bitmap } of records) {
+    for (let row = 0; row < glyph.height; row++) {
+      atlasData.set(
+        bitmap.subarray(row * glyph.width, (row + 1) * glyph.width),
+        (glyph.sourceY + row) * width + glyph.sourceX,
+      );
+    }
+  }
+
+  const selected = new Set(sortedGlyphs.map((glyph) => glyph.codepoint));
+  const kerning = [];
+  const pairs = new Set();
+  for (const pair of face.kerning || []) {
+    const left = integer(pair.left, "kerning left", 0, 0x10ffff);
+    const right = integer(pair.right, "kerning right", 0, 0x10ffff);
+    const adjustment16 = integer(
+      pair.adjustment16,
+      "kerning adjustment",
+      -32768,
+      32767,
+    );
+    const key = `${left}:${right}`;
+
+    if (pairs.has(key)) throw new Error("Duplicate bitmap font kerning pair");
+    pairs.add(key);
+    if (!available.has(left) || !available.has(right))
+      throw new Error("Kerning references absent glyph");
+    if (selected.has(left) && selected.has(right) && adjustment16 !== 0)
+      kerning.push({ left, right, adjustment16 });
+  }
+
+  kerning.sort((a, b) => a.left - b.left || a.right - b.right);
+
+  return {
+    id: tuple.id,
+    family: tuple.family,
+    familyId: tuple.familyId,
+    sizePx: tuple.sizePx,
+    lineHeight,
+    ascender,
+    descender,
+    glyphs: sortedGlyphs,
+    atlasWidth: width,
+    atlasHeight: height,
+    atlasBits: 8,
+    atlasData,
+    kerning,
+    importedBitmap: true,
+    fallbackCodepoint,
+  };
+}

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

@@ -253,7 +253,18 @@ function copyCompatSourceTree(srcDir, dstDir, envDefines = {}) {
         for (const module of native.modules) {
           nativeModules.set(`${module.kind}:${module.url}`, { ...module, stagedEntry: path.resolve(path.dirname(dst), path.relative(path.dirname(src), module.entry)) })
         }
-        fs.writeFileSync(dst, inlineProcessEnv(transformGeaEmbeddedCompatSource(inlineJsonImports(native.code, src), src), envDefines))
+        let debugMap
+        const preparedSource = inlineJsonImports(native.code, src)
+        const transformed = transformGeaEmbeddedCompatSource(preparedSource, src,
+          process.env.GEA_NATIVE_DEBUGGER === '1' ? map => { debugMap = map } : undefined)
+        fs.writeFileSync(dst, inlineProcessEnv(transformed, envDefines))
+        if (process.env.GEA_NATIVE_DEBUGGER === '1') {
+          fs.writeFileSync(dst + '.gea-source.json', JSON.stringify({
+            source: src, original: code, staged: fs.readFileSync(dst, 'utf8'),
+            map: debugMap || null, prepared: preparedSource,
+            unmappedTransforms: preparedSource !== code || transformed !== inlineProcessEnv(transformed, envDefines)
+          }))
+        }
       } else {
         fs.copyFileSync(src, dst)
         if (path.extname(entry.name) === '.css') copyCssUrlAssets(src, dst)
@@ -451,7 +462,72 @@ function resolveAppleNativeAliasModules(appDir) {
   return { threeSrcDir, threeUtilsModule, threeWebGLAnimationModule, threeWebXRManagerModule, troikaThreeTextModule }
 }
 
-function writeCompatViteConfig({ configPath, compatSrcDir, appDir, entry, viteOutDir, geaIrPath, appleNative, moduleGraphOutDir, envDefines }) {
+// `gea.moduleAliases` in the application's package.json: exact import
+// specifiers redirected to files inside the application, for a module whose
+// host exists on one target only (an app's macOS audio host, say) and that
+// 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).
+function resolveAppModuleAliases(appDir, stagedAppDir = appDir) {
+  let manifest = {}
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(appDir, 'package.json'), 'utf8')).gea ?? {}
+  } catch {
+    return []
+  }
+  const raw = manifest.moduleAliases
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return []
+  const aliases = []
+  for (const [specifier, target] of Object.entries(raw)) {
+    if (typeof target !== 'string' || !target) fail(`gea.moduleAliases["${specifier}"] must name a file inside the application`)
+    if (!fs.existsSync(path.resolve(appDir, target))) fail(`gea.moduleAliases["${specifier}"] does not exist: ${target}`)
+    aliases.push({ specifier, replacement: path.resolve(stagedAppDir, target) })
+  }
+  return aliases
+}
+
+// The gea-threejs port, when the application depends on it: its src/ directory,
+// and the native troika text module when the application uses troika.
+// Opt-in: an application that sets `"gea": { "geaThreejs": true }` in its
+// package.json. Depending on the port is not enough on its own, so an app that
+// installs it for some other reason keeps compiling three.js itself.
+function resolveGeaThreeAliasModules(appDir) {
+  const appRequire = createRequire(path.join(appDir, 'package.json'))
+  let geaThreeSrcDir = ''
+  let troikaThreeTextModule = ''
+  let optedIn = false
+  try {
+    optedIn = JSON.parse(fs.readFileSync(path.join(appDir, 'package.json'), 'utf8')).gea?.geaThreejs === true
+  } catch {
+    // An unreadable manifest opts into nothing; the build reports it elsewhere.
+  }
+  if (!optedIn) return { geaThreeSrcDir, troikaThreeTextModule }
+  try {
+    geaThreeSrcDir = path.join(path.dirname(fs.realpathSync(appRequire.resolve('@geastack/gea-threejs/package.json'))), 'src')
+  } catch {
+    return { geaThreeSrcDir, troikaThreeTextModule }
+  }
+  try {
+    appRequire.resolve('troika-three-text')
+  } catch {
+    return { geaThreeSrcDir, troikaThreeTextModule }
+  }
+  try {
+    troikaThreeTextModule = fs.realpathSync(appRequire.resolve('@geastack/native-webgl-angle/troika-three-text'))
+  } catch {
+    fail(
+      `This build resolved "troika-three-text" and "@geastack/gea-threejs" from ${appDir}, but could not resolve ` +
+      '"@geastack/native-webgl-angle/troika-three-text", the native text module that replaces it. ' +
+      'Install @geastack/native-webgl-angle in the application.'
+    )
+  }
+  return { geaThreeSrcDir, troikaThreeTextModule }
+}
+
+function writeCompatViteConfig({ configPath, compatSrcDir, appDir, stagedAppDir, entry, viteOutDir, geaIrPath, appleNative, moduleGraphOutDir, envDefines }) {
   const engineComponentsPath = path.join(engineRoot, 'components/index.ts')
   const engineComponentSubpath = path.join(engineRoot, 'components/$1')
   const elementsPath = path.join(elementsRoot, 'components/index.ts')
@@ -467,7 +543,13 @@ function writeCompatViteConfig({ configPath, compatSrcDir, appDir, entry, viteOu
   const { threeSrcDir, threeUtilsModule, threeWebGLAnimationModule, threeWebXRManagerModule, troikaThreeTextModule } = appleNative
     ? resolveAppleNativeAliasModules(appDir)
     : { threeSrcDir: '', threeUtilsModule: '', threeWebGLAnimationModule: '', threeWebXRManagerModule: '', troikaThreeTextModule: '' }
+  // Apple-native keeps three.js itself (it renders through ANGLE).
+  const geaThree = appleNative ? { geaThreeSrcDir: '', troikaThreeTextModule: '' } : resolveGeaThreeAliasModules(appDir)
   const q = (value) => JSON.stringify(value)
+  const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
+  const appModuleAliases = resolveAppModuleAliases(appDir, stagedAppDir)
+    .map(({ specifier, replacement }) => `      { find: new RegExp(${q('^' + escapeRegExp(specifier) + '$')}), replacement: ${q(replacement)} },\n`)
+    .join('')
   // Compile the @geajs/core reactive runtime (Component/Store/compiler-runtime)
   // from its TYPED SOURCE, not the minified dist. The minified build reuses short
   // identifiers across nested scopes, which the C++ symbol collector cannot
@@ -496,7 +578,7 @@ function writeCompatViteConfig({ configPath, compatSrcDir, appDir, entry, viteOu
   const config = `import { resolve } from 'node:path'
 import { geaPlugin } from ${q(geaPluginResolved)}
 import { geaNativeStylePlugin } from ${q(path.join(coreRoot, 'scripts/gea-native-style-plugin.mjs'))}
-import { geaAppleNativeModuleAliases, geaModuleGraphPlugins } from ${q(moduleGraphPluginPath)}
+import { geaAppleNativeModuleAliases, geaModuleGraphPlugins, geaThreeModuleAliases } from ${q(moduleGraphPluginPath)}
 
 const root = ${q(compatSrcDir)}
 const geaModuleGraph = geaModuleGraphPlugins({ outDir: ${q(moduleGraphOutDir || '')}, entryReachableOnly: true })
@@ -507,6 +589,10 @@ const geaAppleNativeAliases = geaAppleNativeModuleAliases({
   threeWebXRManagerModule: ${q(threeWebXRManagerModule)},
   troikaThreeTextModule: ${q(troikaThreeTextModule)},
 })
+const geaThreeAliases = geaThreeModuleAliases({
+  geaThreeSrcDir: ${q(geaThree.geaThreeSrcDir)},
+  troikaThreeTextModule: ${q(geaThree.troikaThreeTextModule)},
+})
 
 export default {
   root,
@@ -516,6 +602,7 @@ ${defineEntries}
   plugins: [geaNativeStylePlugin({ runtimeEntry: ${q(compilerRuntimeEntry)} }), geaPlugin({ ir: { enabled: true, outFile: ${q(geaIrPath)} } }), ...geaModuleGraph],
   resolve: {
     alias: [
+${appModuleAliases}      ...geaThreeAliases,
 ${compilerRuntimeAlias}
       { find: new RegExp('^@geastack/core$'), replacement: ${q(runtimePath)} },
       { find: new RegExp('^@geastack/engine$'), replacement: ${q(engineComponentsPath)} },
@@ -2011,7 +2098,6 @@ function cssIgnoredProperty(property) {
     'scroll-snap-type',
     'scrollbar-width',
     'text-shadow',
-    'transition',
     'cursor',
     '-webkit-tap-highlight-color',
   ]).has(property)
@@ -4428,7 +4514,7 @@ if (geaEmbeddedCompat) {
   }
   stagedEntryFile = path.join(compatSrcDir, compatEntry)
   fontSourceDir = compatSrcDir
-  writeCompatViteConfig({ configPath: viteConfig, compatSrcDir, appDir, entry: compatEntry, viteOutDir, geaIrPath, appleNative, moduleGraphOutDir, envDefines })
+  writeCompatViteConfig({ configPath: viteConfig, compatSrcDir, appDir, stagedAppDir: path.join(compatSrcDir, path.relative(stagingRoot, appDir)), entry: compatEntry, viteOutDir, geaIrPath, appleNative, moduleGraphOutDir, envDefines })
 } else if (appleNative) {
   const baseViteConfig = viteConfig
   viteConfig = path.join(outDir, 'gea-apple-native.vite.config.mjs')
@@ -4559,6 +4645,10 @@ const geatscArgs = [
   `gea.ir=${geaIrPath}`,
   '--plugin-option',
   `gea.microtasks-namespace=${microtasksNamespaceForEntry(entrySymbol)}`,
+  '--plugin-option',
+  `gea.native-signature-core-root=${coreRoot}`,
+  '--plugin-option',
+  `gea.native-signature-host-root=${process.env.GEA_HOST_DIR || path.resolve(coreRoot, '..', 'host')}`,
 ]
 if (!moduleGraphCompile) geatscArgs.push('--target', 'cpp')
 if (moduleGraphCompile) {
@@ -4578,6 +4668,7 @@ if (cxxStandard) geatscArgs.push('--cxx-standard', cxxStandard)
 if (hasFlag('--allow-any') || compilerSettings.allowAny) geatscArgs.push('--allow-any')
 if (entrySymbol) geatscArgs.push('--entry-symbol', entrySymbol)
 if (hasFlag('--isolate-symbols')) geatscArgs.push('--isolate-symbols')
+if (process.env.GEA_NATIVE_DEBUGGER === '1') geatscArgs.push('--debug-source')
 // One C++ unit per source module plus a shared header, instead of one unit for
 // the whole program. Every target already reads `geatsc-sources.txt` as a LIST,
 // so nothing downstream changes; see the compiler's docs/TRANSLATION-UNITS.md
@@ -4606,7 +4697,7 @@ if (nativeModules.size) {
     if (!fs.existsSync(module.stagedEntry)) fail(`missing ${module.kind} module: ${module.entry}`)
     if (module.kind === 'worklet') {
       const implementation = path.join(coreRoot, 'runtime/audio-worklet.ts')
-      const bindings = `import { AudioWorkletProcessor, registerProcessor } from ${JSON.stringify(implementation)}\n`
+      const bindings = `import { AudioWorkletProcessor, registerProcessor } from ${JSON.stringify(implementation.slice(0, -3))}\n`
       const source = fs.readFileSync(module.stagedEntry, 'utf8')
       fs.writeFileSync(module.stagedEntry, bindings + source)
       const compilerRequire = createRequire(pathToFileURL(geatscBin))

package/scripts/gea-embedded-asset-policy.mjs

@@ -0,0 +1,38 @@
+import path from "node:path";
+
+export function compileTimeOnlyAssetPaths(manifest) {
+  const configured = manifest?.gea?.embeddedAssets?.compileTimeOnly;
+
+  if (configured === undefined) {
+    return new Set();
+  }
+
+  if (!Array.isArray(configured)) {
+    throw new Error(
+      "gea.embeddedAssets.compileTimeOnly must be an array of app-relative file paths",
+    );
+  }
+
+  const result = new Set();
+
+  for (const entry of configured) {
+    if (
+      typeof entry !== "string" ||
+      entry.length === 0 ||
+      entry.includes("\\") ||
+      path.posix.isAbsolute(entry) ||
+      path.posix.normalize(entry) !== entry ||
+      entry === "." ||
+      entry === ".." ||
+      entry.startsWith("../")
+    ) {
+      throw new Error(
+        "Compile-time asset paths must be normalized relative paths inside the app",
+      );
+    }
+
+    result.add(entry);
+  }
+
+  return result;
+}

package/scripts/gea-embedded-compat-transform.mjs

@@ -212,7 +212,7 @@ function transformTopLevelStatement(stmt) {
   return { changed: false, nodes: [stmt] }
 }
 
-export function transformGeaEmbeddedCompatSource(code, filename) {
+export function transformGeaEmbeddedCompatSource(code, filename, onSourceMap) {
   if ((!code.includes('<') || !code.includes('>')) && !code.includes('@geastack/core') && !code.includes('@geajs/core')) return code
 
   const ast = parser.parse(code, {
@@ -246,7 +246,9 @@ export function transformGeaEmbeddedCompatSource(code, filename) {
     ensureComponentImport(ast, statesProps)
   }
 
-  return generate(ast, { retainLines: true }, code).code
+  const result = generate(ast, { retainLines: true, sourceMaps: !!onSourceMap, sourceFileName: filename }, code)
+  if (onSourceMap) onSourceMap(result.map)
+  return result.code
 }
 
 // ─── JSON-import constant folding ────────────────────────────────────────────

package/scripts/gea-vite-module-graph-plugin.mjs

@@ -6,6 +6,7 @@ import path from 'node:path'
 const JS_LIKE_RE = /\.(?:mjs|cjs|js|jsx|ts|tsx)$/i
 const STATIC_ASSET_RE = /\.(?:apng|bmp|png|jpe?g|jfif|pjpeg|pjp|gif|svg|ico|webp|avif|cur|jxl|mp4|webm|ogg|mp3|wav|flac|aac|opus|mov|m4a|vtt|woff2?|eot|ttf|otf|webmanifest|pdf|txt|glb|gltf|hdr)$/i
 const STATIC_ASSET_MODULE_SUFFIX = '.geaassetmodule.js'
+const RAW_MODULE_SUFFIX = '.gearawmodule.js'
 const STATIC_IMPORT_RE = /\bimport\s+(?:[^'"()]*?\s+from\s*)?["']([^"']+)["']/g
 const EXPORT_FROM_RE = /\bexport\s+(?:[^'"]*?\s+from\s*)["']([^"']+)["']/g
 const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g
@@ -65,6 +66,30 @@ export function geaAppleNativeModuleAliases(options = {}) {
   return aliases
 }
 
+// An app that opts into @geastack/gea-threejs (three.js ported to strictly
+// typed TypeScript, with a native software renderer) by setting
+// `"gea": { "geaThreejs": true }` gets three's import surface redirected to
+// the port on non-apple native targets: bare `three`,
+// every `three/src/*.js` path (to its `.ts` source), and `troika-three-text`
+// (to the native atlas text, whose own `three/src` imports land on the port
+// through the same aliases).
+export function geaThreeModuleAliases(options = {}) {
+  const aliases = []
+  if (!options.geaThreeSrcDir) return aliases
+  if (!path.isAbsolute(options.geaThreeSrcDir)) {
+    throw new TypeError('geaThreeSrcDir must be an absolute directory resolved from the application package boundary')
+  }
+  aliases.push({ find: /^three$/, replacement: path.join(options.geaThreeSrcDir, 'Three.ts') })
+  aliases.push({ find: /^three\/src\/(.+)\.js$/, replacement: path.join(options.geaThreeSrcDir, '$1.ts') })
+  if (options.troikaThreeTextModule) {
+    if (!path.isAbsolute(options.troikaThreeTextModule)) {
+      throw new TypeError('troikaThreeTextModule must be an absolute module resolved from the application package boundary')
+    }
+    aliases.push({ find: /^troika-three-text$/, replacement: options.troikaThreeTextModule })
+  }
+  return aliases
+}
+
 export function geaModuleGraphPlugins(options = {}) {
   const outDir = options.outDir || process.env.GEA_VITE_MODULE_GRAPH_OUT || ''
   if (!outDir) return []
@@ -76,6 +101,7 @@ export function geaModuleGraphPlugins(options = {}) {
     transformed: new Map(),
     imports: new Map(),
     assets: new Map(),
+    rawModules: new Map(),
     // GEA_MODULE_GRAPH_ENTRY_REACHABLE_ONLY=0 keeps the unpruned graph, so a
     // build can be A/B'd against the reachability filter without editing the
     // generated vite config.
@@ -95,32 +121,44 @@ export function geaModuleGraphPlugins(options = {}) {
         // Vite normally turns a plain static-asset import into a JS module that
         // exports the emitted browser URL. The native compiler consumes source
         // snapshots instead of the browser bundle, so expose the same binding
-        // through a compiler-visible synthetic JS module. Query imports retain
-        // Vite's distinct ?raw/?inline/etc. semantics.
+        // through a compiler-visible synthetic JS module. Raw imports export
+        // file contents instead; other query imports retain Vite semantics.
         const normalizedImporter = normalizeModuleId(importer)
+        const raw = source.endsWith('?raw')
+        const assetSpecifier = raw ? source.slice(0, -4) : source
         if (
           !importer ||
           !shouldTrackModule(normalizedImporter) ||
-          source.includes('?') ||
-          source.includes('#') ||
-          !STATIC_ASSET_RE.test(source)
+          assetSpecifier.includes('?') ||
+          assetSpecifier.includes('#') ||
+          (!raw && !STATIC_ASSET_RE.test(assetSpecifier))
         ) return null
 
         let resolvedId = ''
-        const resolved = await this.resolve(source, importer, { skipSelf: true })
+        const resolved = await this.resolve(assetSpecifier, importer, { skipSelf: true })
         if (resolved && !resolved.external) resolvedId = normalizeModuleId(resolved.id)
-        if (!resolvedId && source.startsWith('.')) {
-          resolvedId = path.resolve(path.dirname(normalizedImporter), source)
+        if (!resolvedId && assetSpecifier.startsWith('.')) {
+          resolvedId = path.resolve(path.dirname(normalizedImporter), assetSpecifier)
         }
         if (!path.isAbsolute(resolvedId) || !fs.existsSync(resolvedId) || !fs.statSync(resolvedId).isFile()) return null
 
         const assetSource = fs.realpathSync(resolvedId)
+        if (raw) {
+          const moduleId = `${assetSource}${RAW_MODULE_SUFFIX}`
+          state.rawModules.set(moduleId, fs.readFileSync(assetSource, 'utf8'))
+          return moduleId
+        }
+
         const moduleId = `${assetSource}${STATIC_ASSET_MODULE_SUFFIX}`
         if (!state.assets.has(moduleId)) state.assets.set(moduleId, describeStaticAsset(assetSource))
         return moduleId
       },
       load(id) {
-        const asset = state.assets.get(normalizeModuleId(id))
+        const normalizedId = normalizeModuleId(id)
+        if (state.rawModules.has(normalizedId)) {
+          return `export default ${JSON.stringify(state.rawModules.get(normalizedId))}\n`
+        }
+        const asset = state.assets.get(normalizedId)
         if (!asset) return null
         return `export default ${JSON.stringify(asset.url)}\n`
       },
@@ -183,10 +221,16 @@ function writeModuleGraph(pluginContext, state) {
     const id = normalizeModuleId(rawId)
     if (shouldTrackModule(id) && !rawIdsByNormalizedId.has(id)) rawIdsByNormalizedId.set(id, rawId)
   }
+  // A framework transform can consume an imported asset while leaving the
+  // original TS snapshot's binding intact. Rollup then never loads its module;
+  // the native graph still needs the resolved literal module for that binding.
+  for (const id of [...state.assets.keys(), ...state.rawModules.keys()]) {
+    if (!rawIdsByNormalizedId.has(id)) rawIdsByNormalizedId.set(id, id)
+  }
   const modules = []
   const allIds = Array.from(rawIdsByNormalizedId.keys()).sort()
   const reachableIds = state.entryReachableOnly
-    ? entryReachableModuleIds(pluginContext, rawIdsByNormalizedId, allIds)
+    ? entryReachableModuleIds(pluginContext, state, rawIdsByNormalizedId, allIds)
     : allIds
   const live = liveModuleIds(state, reachableIds)
   const ids = reachableIds.filter((id) => live.keep.has(id))
@@ -194,11 +238,13 @@ function writeModuleGraph(pluginContext, state) {
   for (const id of ids) {
     const info = pluginContext.getModuleInfo(rawIdsByNormalizedId.get(id))
     const prune = (code) => pruneDeadReExports(code, id, state, live)
-    const originalCode = prune(normalizeSnapshotSourceForGeatsc(state.original.get(id) ?? readFileSource(id)))
-    const transformedCode = prune(normalizeSnapshotSourceForGeatsc(state.transformed.get(id)))
+    const asset = state.assets.get(id)
+    const literal = asset?.url ?? state.rawModules.get(id)
+    const syntheticSource = literal === undefined ? undefined : `export default ${JSON.stringify(literal)}\n`
+    const originalCode = prune(normalizeSnapshotSourceForGeatsc(state.original.get(id) ?? syntheticSource ?? readFileSource(id)))
+    const transformedCode = prune(normalizeSnapshotSourceForGeatsc(state.transformed.get(id) ?? syntheticSource))
     const originalPath = writeSnapshot(state, id, 'original', originalCode)
     const transformedPath = writeSnapshot(state, id, 'transformed', transformedCode)
-    const asset = state.assets.get(id)
     modules.push({
       id,
       file: path.isAbsolute(id) ? id : null,
@@ -397,7 +443,7 @@ function pruneDeadReExports(code, id, state, live) {
   })
 }
 
-function entryReachableModuleIds(pluginContext, rawIdsByNormalizedId, allIds) {
+function entryReachableModuleIds(pluginContext, state, rawIdsByNormalizedId, allIds) {
   const tracked = new Set(allIds)
   const reachable = new Set()
   const pending = []
@@ -416,7 +462,10 @@ function entryReachableModuleIds(pluginContext, rawIdsByNormalizedId, allIds) {
     if (!id || reachable.has(id)) continue
     reachable.add(id)
     const info = pluginContext.getModuleInfo(rawIdsByNormalizedId.get(id))
-    for (const dependency of [...(info?.importedIds ?? []), ...(info?.dynamicallyImportedIds ?? [])]) {
+    const snapshotAssets = (state.imports.get(id) ?? [])
+      .map((item) => item.resolvedId)
+      .filter((target) => state.assets.has(target) || state.rawModules.has(target))
+    for (const dependency of [...(info?.importedIds ?? []), ...(info?.dynamicallyImportedIds ?? []), ...snapshotAssets]) {
       const normalized = normalizeModuleId(dependency)
       if (tracked.has(normalized) && !reachable.has(normalized)) pending.push(normalized)
     }

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Scans an app directory for binary assets (images/fonts) and emits a C++ translation
+// Scans an app directory for binary assets (images/fonts/audio) and emits a C++ translation
 // unit that embeds each one as a named, externally-visible `.rodata` symbol.
 //
 // This is the build half of "store images as files, read them as files": the
@@ -23,6 +23,7 @@
 // an asset filename; the linker keeps one copy.
 
 import { describeStaticAsset } from './gea-static-asset.mjs'
+import { compileTimeOnlyAssetPaths } from './gea-embedded-asset-policy.mjs'
 import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
@@ -44,8 +45,19 @@ function fail(message) {
 
 const appDir = path.resolve(readOption('--app-dir') ?? fail('missing --app-dir <dir>'))
 const outCpp = path.resolve(readOption('--out-cpp') ?? fail('missing --out-cpp <file>'))
+const manifestPath = path.join(appDir, 'package.json')
+const compileTimeOnly = compileTimeOnlyAssetPaths(
+  fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : {},
+)
 
-const ASSET_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.ttf', '.otf'])
+for (const relative of compileTimeOnly) {
+  const file = path.join(appDir, relative)
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+    fail(`compile-time-only asset is not a file: ${relative}`)
+  }
+}
+
+const ASSET_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.ttf', '.otf', '.wav'])
 // Launcher/package icons are metadata, not runtime `<Image>` assets. If an app
 // wants to render one, keep a copy under `public/` so the reference is explicit.
 const PRUNE_DIRS = new Set(['node_modules', 'dist', 'build'])
@@ -83,7 +95,9 @@ function collectAssets(dir) {
         const rel = path.relative(appDir, full).split(path.sep).join('/')
         if (!PRUNE_DIRS.has(entry.name) && !entry.name.startsWith('.') && rel !== 'icons') walk(full)
       } else if (entry.isFile() && ASSET_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
-        found.push(full)
+        if (!compileTimeOnly.has(relPath(full))) {
+          found.push(full)
+        }
       }
     }
   }