@geastack/core 0.1.32 → 0.1.34

package/app_frame_perf.cpp

@@ -30,6 +30,12 @@ const char *applicationFramePhaseName(ApplicationFramePhase phase)
 		case ApplicationFramePhase::StyleRecompute: return "style_recompute";
 		case ApplicationFramePhase::DocumentFrame: return "document_frame";
 		case ApplicationFramePhase::RefreshMounted: return "refresh_mounted";
+		case ApplicationFramePhase::CycleCollection: return "cycle_collection";
+		case ApplicationFramePhase::CallbackMicrotasks: return "callback_microtasks";
+		case ApplicationFramePhase::WebSocketCallbacks: return "websocket_callbacks";
+		case ApplicationFramePhase::RtcCallbacks: return "rtc_callbacks";
+		case ApplicationFramePhase::VideoPresentation: return "video_presentation";
+		case ApplicationFramePhase::HttpRequests: return "http_requests";
 		case ApplicationFramePhase::Idle: return "idle";
 	}
 	return "idle";
@@ -59,6 +65,12 @@ void applicationFramePerfStatsAdd(ApplicationFramePerfStats &stats, ApplicationF
 		case ApplicationFramePhase::RefreshMounted:
 			stats.refreshMountedUs += durationUs;
 			break;
+		case ApplicationFramePhase::CycleCollection:
+		case ApplicationFramePhase::CallbackMicrotasks:
+		case ApplicationFramePhase::WebSocketCallbacks:
+		case ApplicationFramePhase::RtcCallbacks:
+		case ApplicationFramePhase::VideoPresentation:
+		case ApplicationFramePhase::HttpRequests:
 		case ApplicationFramePhase::Idle:
 			break;
 	}

package/audio-worklet.d.ts

@@ -0,0 +1,49 @@
+import type { AudioContext, AudioDestinationNode } from './index'
+import type { MessagePort } from './workers'
+
+export interface AudioContextOptions {
+  sampleRate?: number
+  latencyHint?: 'interactive' | 'balanced' | 'playback' | number
+}
+
+export interface AudioWorklet {
+  addModule(moduleURL: string | URL): Promise<void>
+}
+
+export interface AudioWorkletNodeOptions {
+  numberOfInputs?: number
+  numberOfOutputs?: number
+  channelCount?: number
+  outputChannelCount?: number[]
+}
+
+export interface AudioWorkletNode {
+  readonly port: MessagePort
+  onprocessorerror: ((event: { readonly message: string }) => void) | null
+  connect(destination: AudioDestinationNode): AudioDestinationNode
+  disconnect(): void
+}
+
+export interface AudioWorkletNodeConstructor {
+  new (context: AudioContext, name: string, options?: AudioWorkletNodeOptions): AudioWorkletNode
+}
+
+export interface MediaStreamAudioSourceNode {
+  connect(destination: AudioWorkletNode): AudioWorkletNode
+  disconnect(): void
+}
+
+declare global {
+  const AudioWorkletNode: AudioWorkletNodeConstructor
+  abstract class AudioWorkletProcessor {
+    readonly port: MessagePort
+    constructor()
+    abstract process(inputs: Float32Array[][], outputs: Float32Array[][],
+      parameters: Record<string, Float32Array>): boolean
+  }
+  function registerProcessor(name: string, processorCtor: new () => AudioWorkletProcessor): void
+  /** AudioWorkletGlobalScope clock, in the context's sample-rate domain. */
+  const sampleRate: number
+  const currentFrame: number
+  const currentTime: number
+}

package/gea_app_entry.cpp

@@ -6,6 +6,7 @@
 #include "gea_perf_config.h"  // GEA_EMBEDDED_PERF master + per-subsystem perf flags
 #include "gea/embedded.h"
 #include "host/backends.h"
+#include "host/worker.h"
 #include "ui/style.h"
 #include "ui/tree_internal.h"  // Tree::mount for the post-mount clean repaint in init()
 
@@ -64,7 +65,23 @@ public:
 	{
 		if (active_) gea_cycle_collection_defer_begin();
 	}
-	~FrameCycleCollectionDeferral() { if (active_) gea_cycle_collection_defer_end(); }
+	~FrameCycleCollectionDeferral() {
+#if defined(ESP_PLATFORM) && CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS
+		const auto started = nowUs();
+#endif
+		if (active_) {
+			// Scope-exit collection runs after frame phases finish. Keep it
+			// visible to the watchdog instead of reporting a stalled frame as idle.
+			const auto previous = applicationFramePhaseRead();
+			applicationFramePhaseSet(ApplicationFramePhase::CycleCollection);
+			gea_cycle_collection_defer_end();
+			applicationFramePhaseSet(previous);
+		}
+#if defined(ESP_PLATFORM) && CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS
+		const auto elapsed = nowUs() - started;
+		if (elapsed > 30000) ESP_LOGW("frame_phase", "cycle_collection duration_ms=%lld", (long long)(elapsed / 1000));
+#endif
+	}
 
 private:
 	bool active_;
@@ -209,7 +226,7 @@ void logFramePerfWindow(int64_t windowEndUs)
 // pays zero for phase instrumentation.
 std::int64_t phaseClockUs()
 {
-#if GEA_FRAME_PHASE_TIMING
+#if GEA_FRAME_PHASE_TIMING || CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS
 	return nowUs();
 #else
 	return 0;
@@ -222,6 +239,11 @@ std::int64_t phaseClockUs()
 // neither is set.
 void recordFramePhase(ApplicationFramePhase phase, int64_t durationUs)
 {
+#if defined(ESP_PLATFORM) && CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS
+	if (durationUs > 30000)
+		ESP_LOGW("frame_phase", "%s duration_ms=%lld", applicationFramePhaseName(phase),
+			static_cast<long long>(durationUs / 1000));
+#endif
 #if GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LOG
 	applicationFramePerfStatsAdd(phase, durationUs);
 #endif
@@ -273,11 +295,22 @@ void Application::frame(int timestampMs)
 	startUs = phaseClockUs();
 	applicationFramePhaseSet(ApplicationFramePhase::AnimationFrameCallbacks);
 	gea::host::runAnimationFrameCallbacks(static_cast<double>(timestampMs));
+	applicationFramePhaseSet(ApplicationFramePhase::CallbackMicrotasks);
 	generated::drainMicrotasks();
-	// Offline builds have no network events to drain. Avoid locking empty queues every frame.
+	// The build already proves whether network services are reachable. Keep their
+	// callback pumps out of offline frame loops, while still servicing local workers.
 #if !defined(GEA_EMBEDDED_NETWORK_SERVICES_DISABLED) || !GEA_EMBEDDED_NETWORK_SERVICES_DISABLED
+	applicationFramePhaseSet(ApplicationFramePhase::WebSocketCallbacks);
 	gea::host::websocket::runCallbacks();
+	applicationFramePhaseSet(ApplicationFramePhase::RtcCallbacks);
 	gea::host::rtc::runCallbacks();
+#else
+	gea::host::workers::Context::runMainPending();
+#endif
+	applicationFramePhaseSet(ApplicationFramePhase::VideoPresentation);
+	gea::host::video::presentFrames();
+#if !defined(GEA_EMBEDDED_NETWORK_SERVICES_DISABLED) || !GEA_EMBEDDED_NETWORK_SERVICES_DISABLED
+	applicationFramePhaseSet(ApplicationFramePhase::HttpRequests);
 	gea::host::http::runRequests();
 #endif
 	recordFramePhase(ApplicationFramePhase::AnimationFrameCallbacks, phaseClockUs() - startUs);

package/gea_sources.mjs

@@ -87,8 +87,8 @@ export function cxxSources(env = process.env) {
     // @geastack/host — platform layer + services
     ...cpp(host, ['input', 'wifi', 'bluetooth', 'geolocation']),
     ...cpp(join(host, 'host'), [
-      'timers', 'input', 'display', 'fetch', 'media', 'rtc', 'websocket', 'http', 'wifi',
-      'ble', 'apps', 'audio', 'image', 'touch', 'imu', 'memory', 'camera', 'geolocation',
+      'timers', 'worker', 'input', 'display', 'fetch', 'media', 'rtc', 'websocket', 'http', 'wifi',
+      'ble', 'apps', 'audio', 'audio_worklet', 'video', 'mjpeg', 'image', 'touch', 'imu', 'memory', 'camera', 'geolocation',
       'tile_loader'
     ]),
     // framework services (built on the platform abstraction — no target-specific deps)

package/include/app.h

@@ -31,6 +31,12 @@ enum class ApplicationFramePhase : std::uint8_t {
 	StyleRecompute,
 	DocumentFrame,
 	RefreshMounted,
+	CycleCollection,
+	CallbackMicrotasks,
+	WebSocketCallbacks,
+	RtcCallbacks,
+	VideoPresentation,
+	HttpRequests,
 };
 
 struct ApplicationFramePerfStats {

package/include/audio.h

@@ -5,6 +5,7 @@
 #include <cstddef>
 #include <cstdint>
 #include <string>
+#include <functional>
 
 namespace gea::platform::audio {
 
@@ -72,6 +73,14 @@ public:
 	static bool playFile(const std::string &path);
 	static bool playPcm(const std::int16_t *samples, std::size_t sample_count, int sample_rate, int channels);
 	static void stopPlayback();
+	static void flushPlayback();
+	// Continuous 16 kHz mono source; zero means the platform could not attach it.
+	static std::uint64_t playPcmStream(std::function<std::size_t(std::int16_t*, std::size_t)> pull);
+	static void stopPcmStream(std::uint64_t stream);
+	static bool pcmStreamSettled(std::uint64_t stream);
+	// Maximum mixer and device buffering delays, in seconds.
+	static double processingLatency();
+	static double outputLatency();
 };
 
 #ifdef GEA_AUDIO_DRIVER_INTERNAL
@@ -80,8 +89,10 @@ public:
 	static bool open(int sample_rate, int channels, int bits_per_sample);
 	static bool write(const std::int16_t *pcm, std::size_t sample_count, int timeout_ms);
 	static void close();
+	static bool flush();
 	static int volume();
 	static void setVolume(int volume_percent);
+	static double outputLatency(int sample_rate);
 };
 #endif
 

package/include/audio_stream.h

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <algorithm>
+#include <array>
+#include <cstdint>
+#include <functional>
+#include <map>
+#include <mutex>
+
+namespace gea::platform::audio {
+
+// The RTC decoder supplies 16 kHz mono PCM. Pulling from independent readers
+// avoids copying every incoming packet into another playback queue.
+class PcmStreamMixer {
+ public:
+  using Pull = std::function<std::size_t(std::int16_t*, std::size_t)>;
+  using Handle = std::uint64_t;
+  static constexpr std::size_t chunkFrames = 512;
+
+  Handle add(Pull pull) {
+    if (!pull) return 0;
+    std::lock_guard<std::mutex> lock(mutex_);
+    const auto id = ++next_;
+    sources_.emplace(id, Source{std::move(pull)});
+    return id;
+  }
+  void remove(Handle id) { std::lock_guard<std::mutex> lock(mutex_); sources_.erase(id); }
+  void clear() { std::lock_guard<std::mutex> lock(mutex_); sources_.clear(); }
+  bool active() const { std::lock_guard<std::mutex> lock(mutex_); return !sources_.empty(); }
+  bool settled(Handle id) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    const auto it = sources_.find(id);
+    return it == sources_.end() || (!it->second.inFlight && !it->second.failed);
+  }
+  // Called by the sole output consumer AFTER its driver write returns. A
+  // reader being empty only proves its last block was pulled, not submitted.
+  void didWrite(bool success) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    for (auto& [id, source] : sources_) {
+      if (source.inFlight && !success) source.failed = true;
+      source.inFlight = false;
+    }
+  }
+
+  // Mix into existing stereo samples (e.g. oscillator output). Return the
+  // frames actually read: a short network packet must not acquire silence
+  // padding that lengthens speech and accumulates latency.
+  std::size_t mix(std::int16_t* stereo, std::size_t frames) {
+    frames = std::min(frames, chunkFrames);
+    std::array<std::int16_t, chunkFrames> mono;
+    std::size_t available = 0;
+    std::lock_guard<std::mutex> lock(mutex_);
+    for (auto& [id, source] : sources_) {
+      const auto count = std::min(frames, source.pull(mono.data(), frames));
+      source.inFlight = source.inFlight || count > 0;
+      available = std::max(available, count);
+      for (std::size_t i = 0; i < count; ++i) {
+        for (std::size_t channel = 0; channel < 2; ++channel) {
+          const auto sum = static_cast<int>(stereo[i * 2 + channel]) + mono[i];
+          stereo[i * 2 + channel] = static_cast<std::int16_t>(std::clamp(sum, -32768, 32767));
+        }
+      }
+    }
+    return available;
+  }
+ private:
+  mutable std::mutex mutex_;
+  struct Source { Pull pull; bool inFlight = false; bool failed = false; };
+  std::map<Handle, Source> sources_;
+  Handle next_ = 0;
+};
+}

package/include/pixel.h

@@ -658,17 +658,51 @@ inline std::uint16_t fromNative(native_t pixel)
 #endif
 }
 
-// Row copies across the RGB565-scratch <-> native-framebuffer boundary. Both
-// compile to a plain std::memcpy on RGB565 targets (native_t == std::uint16_t),
-// byte-identical to the original framebuffer code; on RGBA8888 they convert
-// per pixel (inactive path).
+// Non-overlapping native pixel spans, including cropped rows whose source and
+// destination have different vector alignment. Keep every load within the span:
+// a scalar head precedes the first aligned-down load, and the scalar tail leaves
+// room for the unaligned vector load's second aligned block.
+inline void copyNative(native_t *dst, const native_t *src, int count)
+{
+	if (count <= 0) return;
+#if GEA_PIXEL_PIE_FILL16 && !GEA_PIXEL_FORMAT_IS_8888 && !GEA_PIXEL_FORMAT_IS_GRAY
+	if (count >= 32) {
+		for (int i = 0; i < 8; ++i) { *dst++ = *src++; --count; }
+		while ((reinterpret_cast<std::uintptr_t>(dst) & 15u) != 0) {
+			*dst++ = *src++;
+			--count;
+		}
+		const int vectors = (count - 8) >> 3;
+		if (vectors > 0) {
+			const native_t *cursor = src;
+			asm volatile(
+				"ee.ld.128.usar.ip q0, %[src], 16\n"
+				"loopnez %[vectors], 1f\n"
+				"ee.ld.128.usar.ip q1, %[src], 16\n"
+				"ee.src.q.qup q2, q0, q1\n"
+				"ee.vst.128.ip q2, %[dst], 16\n"
+				"ee.orq q0, q1, q1\n"
+				"1:\n"
+				: [src] "+&r"(cursor), [dst] "+&r"(dst)
+				: [vectors] "r"(vectors)
+				: "memory");
+			src += vectors * 8;
+			count -= vectors * 8;
+		}
+	}
+#endif
+	std::memcpy(dst, src, static_cast<std::size_t>(count) * sizeof(native_t));
+}
+
+// Row copies across the RGB565-scratch <-> native-framebuffer boundary. RGB565
+// uses the native span copy above; other framebuffer formats convert per pixel.
 inline void copyNativeToRgb565(std::uint16_t *dst, const native_t *src, int count)
 {
 	if (count <= 0) return;
 #if GEA_PIXEL_FORMAT_IS_8888 || GEA_PIXEL_FORMAT_IS_GRAY
 	for (int i = 0; i < count; i++) dst[i] = fromNative(src[i]);
 #else
-	std::memcpy(dst, src, static_cast<std::size_t>(count) * sizeof(std::uint16_t));
+	copyNative(dst, src, count);
 #endif
 }
 
@@ -678,7 +712,7 @@ inline void copyRgb565ToNative(native_t *dst, const std::uint16_t *src, int coun
 #if GEA_PIXEL_FORMAT_IS_8888 || GEA_PIXEL_FORMAT_IS_GRAY
 	for (int i = 0; i < count; i++) dst[i] = toNative(src[i]);
 #else
-	std::memcpy(dst, src, static_cast<std::size_t>(count) * sizeof(std::uint16_t));
+	copyNative(dst, src, count);
 #endif
 }
 

package/index.d.ts

@@ -1,5 +1,12 @@
 /// <reference path="./css.d.ts" />
 
+export type * from './workers'
+export type * from './audio-worklet'
+/** Gea-only hardware output cancellation; call from an AudioWorklet message handler. */
+export declare function flushAudioWorkletOutput(): void
+export type * from './typed-arrays'
+import type { AudioContextOptions, AudioWorklet, MediaStreamAudioSourceNode } from './audio-worklet'
+
 // Opt-in native 64-bit integer. Structurally a `number` (assign/read without
 // casts), but where a binding, parameter, field, or return is annotated `int`,
 // geatsc lowers it to a C++ `long long` and emits exact integer arithmetic
@@ -70,6 +77,7 @@ export interface GeaIntrinsicElements {
   h5: NativeViewProps
   h6: NativeViewProps
   audio: AudioProps
+  video: VideoProps
   button: NativeButtonProps
   img: ImageProps
   input: NativeInputElementProps
@@ -117,9 +125,13 @@ declare global {
   // (`double setTimeout(TimerCallback, double)`), so both the id and the delay
   // are `number`, and the callback takes no arguments (unlike the browser's,
   // which forwards extra `setTimeout` arguments to it).
+  /** @gea-host-no-property-writes */
   function setTimeout(callback: () => void, delayMs: number): number
+  /** @gea-host-no-property-writes */
   function clearTimeout(id: number): void
+  /** @gea-host-no-property-writes */
   function setInterval(callback: () => void, delayMs: number): number
+  /** @gea-host-no-property-writes */
   function clearInterval(id: number): void
 
   /**
@@ -364,6 +376,7 @@ export interface Document {
   querySelector(selector: string): Element | null
   querySelectorAll(selector: string): readonly Element[]
   createElement(tag: 'audio'): HTMLAudioElement
+  createElement(tag: 'video'): HTMLVideoElement
   createElement(tag: 'virtual-list'): VirtualListElement
   createElement(tag: string): Element
   createTextNode(text: string): Node
@@ -596,13 +609,28 @@ export interface AudioProps extends DataAttributes {
   autoplay?: boolean | string | number
   controls?: boolean | string | number
   loop?: boolean | string | number
-  ref?: HTMLAudioElement | null
+  ref?: HTMLAudioElement | (typeof globalThis extends { HTMLAudioElement: { prototype: infer E } } ? E : never) | null
+  autoPlay?: boolean
   children?: any
 }
 
+export interface VideoProps extends DataAttributes {
+  id?: string
+  class?: ClassValue
+  style?: Style
+  autoplay?: boolean
+  muted?: boolean
+  playsinline?: boolean
+  autoPlay?: boolean
+  playsInline?: boolean
+  ref?: HTMLVideoElement | (typeof globalThis extends { HTMLVideoElement: { prototype: infer E } } ? E : never) | null
+}
+
 export type ImageSource = string | ArrayBuffer | Uint8Array | GeaEmbeddedImage
 
 export interface ImageProps extends DataAttributes {
+  alt?: string
+  key?: string | number
   id?: string
   class?: ClassValue
   // Optional: a static template can leave this unset and apply the source
@@ -1300,15 +1328,26 @@ export interface OscillatorNode {
 }
 
 export interface AudioContext {
+  /** Conservative maximum software buffering delay, in seconds. */
+  readonly baseLatency: number
+  /** Device buffering estimate in seconds; zero when unavailable. */
+  readonly outputLatency: number
+  readonly sampleRate: number
+  readonly state: 'running' | 'suspended' | 'closed'
+  readonly audioWorklet: AudioWorklet
   readonly currentTime: number
   readonly destination: AudioDestinationNode
   createOscillator(): OscillatorNode
   createBufferSource(): AudioBufferSourceNode
   decodeAudioData(audioData: ArrayBuffer | Uint8Array | GeaAudioBlob): Promise<AudioBuffer>
+  createMediaStreamSource(stream: MediaStream): MediaStreamAudioSourceNode
+  resume(): Promise<void>
+  suspend(): Promise<void>
+  close(): Promise<void>
 }
 
 export interface AudioContextConstructor {
-  new (): AudioContext
+  new (options?: AudioContextOptions): AudioContext
 }
 
 export declare const audioContext: AudioContext
@@ -1531,6 +1570,7 @@ export interface ButtonProps {
 }
 
 export interface NativeButtonProps extends NativeEventAttributes {
+  disabled?: boolean
   key?: string | number
   class?: ClassValue
   style?: Style
@@ -1653,9 +1693,13 @@ export interface FetchResponse {
   bytes(): Uint8Array
 }
 
+/** @gea-host-no-property-writes */
 export declare function fetchAsync(url: string, init?: FetchRequestInit): number
+/** @gea-host-no-property-writes */
 export declare function fetchReady(id: number): boolean
+/** @gea-host-no-property-writes */
 export declare function fetchResult(id: number): FetchResponse
+/** @gea-host-no-property-writes */
 export declare function fetchRelease(id: number): void
 
 /**
@@ -1692,6 +1736,7 @@ export declare function fetchUploadTotal(id: number): number
 
 declare global {
   function fetch(url: string, init?: FetchRequestInit): FetchResponse
+  /** @gea-host-no-property-writes */
   function fetchAsync(url: string, init?: FetchRequestInit): number
   function fetchUploadFileAsync(
     url: string,
@@ -1705,8 +1750,11 @@ declare global {
   function fetchUploadProgress(id: number): number
   function fetchUploadSent(id: number): number
   function fetchUploadTotal(id: number): number
+  /** @gea-host-no-property-writes */
   function fetchReady(id: number): boolean
+  /** @gea-host-no-property-writes */
   function fetchResult(id: number): FetchResponse
+  /** @gea-host-no-property-writes */
   function fetchRelease(id: number): void
   function atob(data: string): string
   function btoa(data: string | ArrayBuffer | Uint8Array): string
@@ -1727,18 +1775,20 @@ export interface WebSocketErrorEvent {
 }
 
 export interface WebSocketInstance {
+  readonly bufferedAmount: number
   readonly url: string
   readonly readyState: number
   onopen: (() => void) | null
   onmessage: ((event: WebSocketMessageEvent) => void) | null
   onclose: ((event: WebSocketCloseEvent) => void) | null
   onerror: ((event: WebSocketErrorEvent) => void) | null
+  /** @gea-host-no-property-writes */
   send(data: string): void
   close(code?: number, reason?: string): void
 }
 
 export interface WebSocketConstructor {
-  new (url: string): WebSocketInstance
+  new (url: string, protocols?: string | string[]): WebSocketInstance
   readonly CONNECTING: 0
   readonly OPEN: 1
   readonly CLOSING: 2
@@ -1805,7 +1855,7 @@ export declare const http: HttpModule
 
 export interface MediaStreamTrack {
   readonly id: string
-  readonly kind: 'audio'
+  readonly kind: string
   enabled: boolean
   readonly readyState: 'live' | 'ended'
   stop(): void
@@ -1813,12 +1863,19 @@ export interface MediaStreamTrack {
 
 export interface MediaStream {
   readonly id: string
+  readonly active: boolean
   getAudioTracks(): MediaStreamTrack[]
+  getVideoTracks(): MediaStreamTrack[]
   getTracks(): MediaStreamTrack[]
+  getTrackById(id: string): MediaStreamTrack | null
+  addTrack(track: MediaStreamTrack): void
+  removeTrack(track: MediaStreamTrack): void
 }
 
 export interface MediaStreamConstructor {
   new (): MediaStream
+  new (stream: MediaStream): MediaStream
+  new (tracks: MediaStreamTrack[]): MediaStream
 }
 
 export interface MediaStreamConstraints {
@@ -1863,10 +1920,34 @@ export interface MediaRecorderConstructor {
 
 export interface HTMLAudioElement extends Element {
   src: string
+  srcObject: MediaStream | null
+  autoplay: boolean
+  readonly paused: boolean
   currentTime: number
   volume: number
   loop: boolean
-  play(): void
+  play(): Promise<void>
+  pause(): void
+  /** Freeze the current PCM queue endpoint; later RTP silence is excluded. */
+  beginDrain(): void
+  /** Discard queued speech while keeping the live output clock running. */
+  clearBufferedAudio(): void
+  /** Queued PCM has reached the output driver. Hardware DMA drains on capture handoff. */
+  readonly drained: boolean
+  /** RMS of PCM being pulled for playback, normalized to 0–1. */
+  readonly audioLevel: number
+}
+
+export interface HTMLVideoElement extends Element {
+  /** Native HTTP multipart JPEG streaming; decoded on native network/video workers. */
+  src: string
+  srcObject: MediaStream | null
+  autoplay: boolean
+  readonly paused: boolean
+  readonly videoWidth: number
+  readonly videoHeight: number
+  onplaying: (() => void) | null
+  play(): Promise<void>
   pause(): void
 }
 
@@ -1875,6 +1956,13 @@ export interface AudioConstructor {
 }
 
 declare global {
+  interface HTMLAudioElement {
+    beginDrain(): void
+    clearBufferedAudio(): void
+    readonly drained: boolean
+    /** RMS of PCM being pulled for playback, normalized to 0–1. */
+    readonly audioLevel: number
+  }
   interface Blob {
     readonly path: string
   }
@@ -1907,10 +1995,54 @@ export interface RTCSessionDescriptionInit {
   sdp?: string
 }
 
+export interface RTCSessionDescription {
+  readonly type: RTCSessionDescriptionInit['type']
+  readonly sdp: string
+  toJSON(): RTCSessionDescriptionInit
+}
+export interface RTCSessionDescriptionConstructor {
+  new (init: RTCSessionDescriptionInit): RTCSessionDescription
+}
+declare global {
+  const RTCSessionDescription: RTCSessionDescriptionConstructor
+}
+
 export interface RTCIceCandidateInit {
-  candidate: string
+  candidate?: string
   sdpMid?: string | null
   sdpMLineIndex?: number | null
+  usernameFragment?: string | null
+}
+
+export interface RTCLocalIceCandidateInit extends RTCIceCandidateInit {
+  relayProtocol?: 'udp' | 'tcp' | 'tls' | null
+  url?: string | null
+}
+
+export interface RTCIceCandidate {
+  readonly candidate: string
+  readonly sdpMid: string | null
+  readonly sdpMLineIndex: number | null
+  readonly foundation: string | null
+  readonly component: 'rtp' | 'rtcp' | null
+  readonly priority: number | null
+  readonly address: string | null
+  readonly protocol: 'udp' | 'tcp' | null
+  readonly port: number | null
+  readonly type: 'host' | 'srflx' | 'prflx' | 'relay' | null
+  readonly tcpType: 'active' | 'passive' | 'so' | null
+  readonly relatedAddress: string | null
+  readonly relatedPort: number | null
+  readonly usernameFragment: string | null
+  readonly relayProtocol: 'udp' | 'tcp' | 'tls' | null
+  readonly url: string | null
+  toJSON(): RTCIceCandidateInit
+}
+export interface RTCIceCandidateConstructor {
+  new (init?: RTCLocalIceCandidateInit): RTCIceCandidate
+}
+declare global {
+  const RTCIceCandidate: RTCIceCandidateConstructor
 }
 
 export interface RTCIceServer {
@@ -1921,15 +2053,61 @@ export interface RTCIceServer {
 
 export interface RTCConfiguration {
   iceServers?: RTCIceServer[]
+  iceTransportPolicy?: 'all' | 'relay'
 }
 
 export interface RTCPeerConnectionIceEvent {
-  readonly candidate: RTCIceCandidateInit | null
+  readonly candidate: RTCIceCandidate | null
 }
 
 export interface RTCTrackEvent {
   readonly track: MediaStreamTrack
   readonly streams: readonly MediaStream[]
+  readonly receiver: RTCRtpReceiver
+  readonly transceiver: RTCRtpTransceiver
+}
+
+export interface RTCDataChannelInit {
+  ordered?: boolean
+  maxPacketLifeTime?: number
+  maxRetransmits?: number
+  protocol?: string
+  negotiated?: boolean
+  id?: number
+}
+export interface RTCDataChannelMessageEvent { readonly data: string | ArrayBuffer }
+export interface RTCDataChannel {
+  readonly label: string
+  readonly protocol: string
+  readonly ordered: boolean
+  readonly id: number | null
+  readonly maxPacketLifeTime: number | null
+  readonly maxRetransmits: number | null
+  readonly readyState: 'connecting' | 'open' | 'closing' | 'closed'
+  binaryType: 'arraybuffer'
+  readonly bufferedAmount: number
+  bufferedAmountLowThreshold: number
+  onopen: (() => void) | null
+  onclose: (() => void) | null
+  onmessage: ((event: RTCDataChannelMessageEvent) => void) | null
+  onbufferedamountlow: (() => void) | null
+  send(data: string | ArrayBuffer | Uint8Array): void
+  close(): void
+}
+export interface RTCRtpSender {
+  readonly track: MediaStreamTrack | null
+  replaceTrack(track: MediaStreamTrack | null): Promise<void>
+}
+export interface RTCRtpReceiver { readonly track: MediaStreamTrack | null }
+export interface RTCRtpTransceiverInit { direction?: 'sendrecv' | 'sendonly' | 'recvonly' | 'inactive' }
+export interface RTCRtpTransceiver {
+  readonly sender: RTCRtpSender
+  readonly receiver: RTCRtpReceiver
+  readonly mid: string | null
+  direction: 'sendrecv' | 'sendonly' | 'recvonly' | 'inactive'
+  readonly currentDirection: 'sendrecv' | 'sendonly' | 'recvonly' | 'inactive' | null
+  readonly stopped: boolean
+  stop(): void
 }
 
 export interface RTCPeerConnectionInstance {
@@ -1941,7 +2119,19 @@ export interface RTCPeerConnectionInstance {
   onconnectionstatechange: (() => void) | null
   oniceconnectionstatechange: (() => void) | null
 
-  addTrack(track: MediaStreamTrack, stream: MediaStream): void
+  readonly signalingState: 'stable' | 'have-local-offer' | 'have-remote-offer' | 'closed'
+  readonly localDescription: RTCSessionDescription | null
+  readonly remoteDescription: RTCSessionDescription | null
+  onsignalingstatechange: (() => void) | null
+  onnegotiationneeded: (() => void) | null
+  ondatachannel: ((event: { channel: RTCDataChannel }) => void) | null
+  addTrack(track: MediaStreamTrack, stream?: MediaStream): RTCRtpSender
+  removeTrack(sender: RTCRtpSender): void
+  addTransceiver(trackOrKind: MediaStreamTrack | 'audio', init?: RTCRtpTransceiverInit): RTCRtpTransceiver
+  getTransceivers(): RTCRtpTransceiver[]
+  getSenders(): RTCRtpSender[]
+  getReceivers(): RTCRtpReceiver[]
+  createDataChannel(label: string, init?: RTCDataChannelInit): RTCDataChannel
   createOffer(): Promise<RTCSessionDescriptionInit>
   createAnswer(): Promise<RTCSessionDescriptionInit>
   setLocalDescription(desc: RTCSessionDescriptionInit): Promise<void>
@@ -1958,3 +2148,33 @@ declare global {
   const RTCPeerConnection: RTCPeerConnectionConstructor
   function Image(props: ImageProps): GeaJsxElement
 }
+
+
+/** Streaming mono signed PCM16, little endian, carried as base64 text. */
+export interface PcmAudioStream {
+  setInput(stream: MediaStream): void
+  /** Capture and upload on the native socket worker, independently of UI callbacks. */
+  pipeTo(socket: WebSocketInstance, prefix: string, suffix: string): void
+  /** Decode matching PCM packets on the native receive worker; control messages still reach JS. */
+  receiveFrom(socket: WebSocketInstance, prefix: string, suffix: string): void
+  /** Read the next 40ms capture block, or an empty string if not ready. */
+  readBase64(): string
+  writeBase64(data: string): void
+  resetPlayback(interrupted?: boolean): void
+  close(): void
+  readonly queuedMs: number
+  /** Conservative audible duration, excluding mixer and device DMA latency. */
+  readonly playedMs: number
+  readonly drained: boolean
+  readonly audioLevel: number
+  readonly capturePendingMs: number
+  readonly captureDroppedSamples: number
+  readonly capturePackets: number
+}
+export interface PcmAudioStreamConstructor {
+  new (sampleRate: number): PcmAudioStream
+}
+
+declare global {
+  const PcmAudioStream: PcmAudioStreamConstructor
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/core",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "GeaStack app API, reactivity headers, runtime sources, and type declarations.",
   "license": "Apache-2.0",
   "repository": {
@@ -34,6 +34,9 @@
   "files": [
     "app_frame_perf.cpp",
     "css.d.ts",
+    "workers.d.ts",
+    "audio-worklet.d.ts",
+    "typed-arrays.d.ts",
     "events.cpp",
     "gea_sources.sh",
     "gea_sources.mjs",
@@ -63,7 +66,7 @@
     "@geajs/core": "1.5.1",
     "@geajs/vite-plugin": "1.5.0",
     "@geastack/compiler": "^1.0.20",
-    "@geastack/geatsc-plugin-gea": "^0.1.13",
+    "@geastack/geatsc-plugin-gea": "^0.1.15",
     "opentype.js": "^2.0.0",
     "vite": "^8.0.0"
   }

package/runtime/audio-worklet.ts

@@ -0,0 +1,51 @@
+import type { MessagePort } from '../workers.js'
+
+/** Native implementations of the AudioWorkletGlobalScope's two class APIs.
+ * The module loader supplies these lexical bindings to compiled worklet modules;
+ * applications use the browser globals, without imports or platform branches.
+ */
+
+declare function __geaAudioWorkletProcessorPort(): MessagePort
+declare function __geaFlushAudioWorkletOutput(): void
+
+/** Gea hardware cancellation extension; capture remains active. */
+export function flushAudioWorkletOutput(): void {
+  __geaFlushAudioWorkletOutput()
+}
+
+declare function __geaRegisterAudioWorkletProcessor(
+  name: string,
+  create: () => AudioWorkletProcessor,
+  process: (
+    processor: AudioWorkletProcessor,
+    inputs: Float32Array[][],
+    outputs: Float32Array[][]
+  ) => boolean
+): void
+
+export abstract class AudioWorkletProcessor {
+  readonly port: MessagePort
+
+  constructor() {
+    this.port = __geaAudioWorkletProcessorPort()
+  }
+
+  abstract process(
+    inputs: Float32Array[][],
+    outputs: Float32Array[][],
+    parameters: Record<string, Float32Array>
+  ): boolean
+}
+
+// The native module builder validates the concrete registration constructor.
+// AudioParam descriptors are explicitly unsupported, before code generation.
+export function registerProcessor(
+  name: string,
+  constructor: new () => AudioWorkletProcessor
+): void {
+  __geaRegisterAudioWorkletProcessor(
+    name,
+    () => new constructor(),
+    (processor, inputs, outputs) => processor.process(inputs, outputs, {})
+  )
+}

package/runtime-surface.ts

@@ -1,4 +1,7 @@
 export * from './runtime/compiler'
+export type * from './workers'
+export type * from './audio-worklet'
+export { flushAudioWorkletOutput } from './runtime/audio-worklet'
 export * from './runtime/host'
 export * from './runtime/ble'
 export * from './runtime/images'
@@ -109,6 +112,10 @@ export type {
   GeolocationPosition,
   GeolocationPositionError,
   HTMLAudioElement,
+  PcmAudioStream,
+  PcmAudioStreamConstructor,
+  HTMLVideoElement,
+  VideoProps,
   HttpModule,
   HttpRequestHandler,
   HttpServer,

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

@@ -8,6 +8,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 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'
+import { collectWorkerModuleSources, writeWorkerRegistry, validateWorkletRegistrations } from './gea-worker-modules.mjs'
 import { resolveCompilerRuntimeEntry } from './gea-native-style-plugin.mjs'
 import {
   MODULE_HINT_SCOPE,
@@ -20,6 +21,8 @@ import {
   restoreModuleGraphElAnnotations,
 } from './gea-bundle-type-hints.mjs'
 
+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 coreRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
@@ -246,7 +249,11 @@ function copyCompatSourceTree(srcDir, dstDir, envDefines = {}) {
         // (the fully native store/record lowering path). Then bake in .env vars
         // (process.env.<KEY> -> literal) so the module-graph snapshots geatsc
         // compiles carry the value — Vite's `define` only rewrites the bundle.
-        fs.writeFileSync(dst, inlineProcessEnv(transformGeaEmbeddedCompatSource(inlineJsonImports(code, src), src), envDefines))
+        const native = nativeModuleSources.get(src) ?? { code, modules: [] }
+        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))
       } else {
         fs.copyFileSync(src, dst)
         if (path.extname(entry.name) === '.css') copyCssUrlAssets(src, dst)
@@ -304,7 +311,7 @@ function linkCompatNodeModules(appDir, stagedAppDir, compatSrcDir) {
 // staging its containing directory wholesale (which also brings the css/asset
 // files discoverLocalImport skips).
 function escapedCompatImportDirs(appDir, entry) {
-  const escaped = collectReachableSourceFiles(appDir, entry).filter((file) => path.relative(appDir, file).startsWith('..'))
+  const escaped = [...new Set([...collectReachableSourceFiles(appDir, entry), ...nativeModuleSources.keys()])].filter((file) => path.relative(appDir, file).startsWith('..'))
   const dirs = [...new Set(escaped.map((file) => path.dirname(file)))].sort()
   return dirs.filter((dir, index) => !dirs.slice(0, index).some((outer) => outer !== dir && !path.relative(outer, dir).startsWith('..')))
 }
@@ -4393,6 +4400,8 @@ let stagedEntryFile = null
 let fontSourceDir = appDir
 
 if (geaEmbeddedCompat) {
+  nativeModuleSources = collectWorkerModuleSources(path.resolve(appDir, entry),
+    (file) => collectReachableSourceFiles(path.dirname(file), path.basename(file)))
   const compatSrcDir = path.join(outDir, 'gea-embedded-compat-src')
   fs.rmSync(compatSrcDir, { recursive: true, force: true })
   // Relative imports may escape the app dir (examples/shared components).
@@ -4587,7 +4596,46 @@ if (hasFlag('--gea-ir-backend') || hasFlag('--gea-replace-renderers')) {
 // measurement scripts are always run with this
 // limit; the build has to state the same one, not depend on the caller's
 // NODE_OPTIONS.
-run('node', ['--max-old-space-size=32768', ...geatscArgs])
+// Native interface call graphs can exceed V8's default ~1 MiB stack during
+// closure analysis; keep the compiler stack below the host's 8 MiB limit.
+run('node', ['--stack_size=8192', '--max-old-space-size=32768', ...geatscArgs])
+
+if (nativeModules.size) {
+  const nativeSources = []
+  for (const module of nativeModules.values()) {
+    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 source = fs.readFileSync(module.stagedEntry, 'utf8')
+      fs.writeFileSync(module.stagedEntry, bindings + source)
+      const compilerRequire = createRequire(pathToFileURL(geatscBin))
+      validateWorkletRegistrations(compilerRequire('typescript'), module.stagedEntry, implementation)
+    }
+    const moduleOut = path.join(outDir, `${module.kind}-${module.id}`)
+    const moduleArgs = [
+      geatscBin, 'compile', module.stagedEntry, '--out-dir', moduleOut,
+      '--target', 'cpp', '--plugin', geaPluginSpecifier,
+      '--entry-symbol', module.symbol, '--isolate-symbols', '--realm-storage',
+      '--plugin-option', `gea.microtasks-namespace=gea::framework::app::generated::gea_${module.kind}_${module.id}`,
+    ]
+    if (cppBoard) moduleArgs.push('--cpp-board', cppBoard)
+    if (cxxStandard) moduleArgs.push('--cxx-standard', cxxStandard)
+    run('node', ['--stack_size=8192', '--max-old-space-size=32768', ...moduleArgs])
+    const list = fs.readFileSync(path.join(moduleOut, 'geatsc-sources.txt'), 'utf8').split(/\r?\n/).filter(Boolean)
+    nativeSources.push(...list.filter((source) => path.basename(source) !== 'gea_runtime_builtins.cpp'))
+  }
+  const listPath = path.join(outDir, 'geatsc-sources.txt')
+  const sources = fs.readFileSync(listPath, 'utf8').split(/\r?\n/).filter(Boolean)
+  const registry = path.join(outDir, 'gea_worker_modules.cpp')
+  writeWorkerRegistry([...nativeModules.values()], registry)
+  // The app entry and its native registrations must be in one archive member:
+  // constructor-only members are not extracted by ordinary static linking.
+  const nativeEntry = path.join(outDir, 'gea_native_entry.cpp')
+  fs.writeFileSync(nativeEntry, `#include ${JSON.stringify(sources[0])}\n#include ${JSON.stringify(registry)}\n`)
+  fs.writeFileSync(listPath, [nativeEntry, ...sources.slice(1), ...nativeSources].join('\n') + '\n')
+}
+
 
 process.stdout.write(`gea-vite-bundle=${bundlePath}\n`)
 if (moduleGraphOutDir) process.stdout.write(`module-graph=${path.join(moduleGraphOutDir, 'gea-module-graph.json')}\n`)

package/scripts/gea-bundle-type-hints.mjs

@@ -156,8 +156,16 @@ export function discoverLocalImport(source, srcId, localImports) {
   if (source.endsWith('.css')) return
   const base = resolveLocalImportBase(source, srcId)
   if (!base) return
+  // TypeScript's ESM imports name the emitted .js/.mjs/.cjs file while the
+  // source tree contains .ts/.mts/.cts. Follow those edges before staging.
+  const extension = path.extname(base)
+  const sourceExtensions = extension === '.js' ? ['.ts', '.tsx', '.d.ts']
+    : extension === '.mjs' ? ['.mts', '.d.mts']
+      : extension === '.cjs' ? ['.cts', '.d.cts'] : []
+  const stem = base.slice(0, base.length - extension.length)
   for (const candidate of [
     base,
+    ...sourceExtensions.map((extension) => stem + extension),
     base + '.tsx',
     base + '.ts',
     base + '.jsx',
@@ -177,7 +185,7 @@ export function discoverLocalImport(source, srcId, localImports) {
       // non-ASCII byte (`wOFF` header → "Unexpected character" at column 4).
       // Assets aren't parseable modules; skip them (the added-extension
       // candidates below are always JS/TS, so a genuine module still resolves).
-      if (!/\.(?:mjs|cjs|jsx?|tsx?)$/i.test(candidate)) break
+      if (!/\.(?:[cm]?[jt]s|jsx|tsx)$/i.test(candidate)) break
       localImports.push(candidate)
       break
     }

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

@@ -5,6 +5,8 @@ export const COMPAT_STAGING_IGNORED_DIRECTORIES = Object.freeze([
   '.build',
   '.build-test',
   '.vite',
+  '.gea',
+  '.git',
   '.scratch',
   '.test-tmp',
   'generated-output',

package/scripts/gea-static-asset.mjs

@@ -0,0 +1,15 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+
+// One identity for Vite's native module graph and the firmware lookup table.
+export function describeStaticAsset(source) {
+  const contents = fs.readFileSync(source)
+  const sha256 = createHash('sha256').update(contents).digest('hex')
+  return {
+    source,
+    bytes: contents.length,
+    sha256,
+    url: `gea-asset://sha256/${sha256}/${encodeURIComponent(path.basename(source))}`,
+  }
+}

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

@@ -1,3 +1,4 @@
+import { describeStaticAsset } from './gea-static-asset.mjs'
 import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -424,20 +425,6 @@ function entryReachableModuleIds(pluginContext, rawIdsByNormalizedId, allIds) {
   return allIds.filter((id) => reachable.has(id))
 }
 
-function describeStaticAsset(source) {
-  const contents = fs.readFileSync(source)
-  const sha256 = crypto.createHash('sha256').update(contents).digest('hex')
-  // The hash makes the logical URL collision-safe and stable for unchanged
-  // bytes. The basename remains available to native bundle adapters, while the
-  // manifest is the authoritative URL -> source mapping.
-  const basename = encodeURIComponent(path.basename(source))
-  return {
-    source,
-    bytes: contents.length,
-    sha256,
-    url: `gea-asset://sha256/${sha256}/${basename}`,
-  }
-}
 
 async function captureResolvedImports(pluginContext, state, id, code) {
   const normalized = normalizeModuleId(id)

package/scripts/gea-worker-modules.mjs

@@ -0,0 +1,192 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+const require = createRequire(new URL("../package.json", import.meta.url));
+const { parse } = require("@babel/parser");
+const traversal = require("@babel/traverse");
+const traverse = traversal.default ?? traversal;
+
+/** Follow ordinary imports and native module edges without inspecting unused tests. */
+export function collectWorkerModuleSources(
+  entry,
+  importedFiles,
+  readSource = (file) => fs.readFileSync(file, "utf8"),
+) {
+  const pending = [entry];
+  const visited = new Set();
+  const sources = new Map();
+  while (pending.length) {
+    const file = pending.pop();
+    if (visited.has(file)) continue;
+    visited.add(file);
+    pending.push(...importedFiles(file));
+    if (!/\.[cm]?[jt]sx?$/.test(file)) continue;
+    const resolved = resolveWorkerModules(readSource(file), file);
+    sources.set(file, resolved);
+    pending.push(...resolved.modules.map((module) => module.entry));
+  }
+  return sources;
+}
+
+/** Native equivalent of a bundler's static worker URL resolution. */
+export function resolveWorkerModules(
+  code,
+  fileName,
+  resolveModule = (specifier) =>
+    path.resolve(path.dirname(fileName), specifier),
+) {
+  const source = parse(code, {
+    sourceType: "module",
+    plugins: ["typescript", "jsx"],
+  });
+  const modules = [];
+  const edits = [];
+  const staticURL = (argument) => {
+    if (argument?.type === "StringLiteral") return argument.value;
+    if (
+      argument?.type !== "NewExpression" ||
+      argument.callee.type !== "Identifier" ||
+      argument.callee.name !== "URL"
+    )
+      return null;
+    const [url, base] = argument.arguments;
+    if (
+      url?.type !== "StringLiteral" ||
+      base?.type !== "MemberExpression" ||
+      base.computed ||
+      base.property.name !== "url"
+    )
+      return null;
+    if (
+      base.object.type !== "MetaProperty" ||
+      base.object.meta.name !== "import" ||
+      base.object.property.name !== "meta"
+    )
+      return null;
+    return url.value;
+  };
+  const visit = (astPath) => {
+    const node = astPath.node;
+    const binding = astPath.scope.getBinding("Worker");
+    const typeOnlyBinding =
+      binding &&
+      (binding.path.node.importKind === "type" ||
+        binding.path.parent.importKind === "type");
+    const worker =
+      node.type === "NewExpression" &&
+      node.callee.type === "Identifier" &&
+      node.callee.name === "Worker" &&
+      (!binding || typeOnlyBinding);
+    const call = node.callee;
+    const worklet =
+      node.type === "CallExpression" &&
+      call.type === "MemberExpression" &&
+      !call.computed &&
+      call.property.name === "addModule" &&
+      call.object.type === "MemberExpression" &&
+      !call.object.computed &&
+      call.object.property.name === "audioWorklet";
+    if (!worker && !worklet) return;
+    const argument = node.arguments[0];
+    const specifier = staticURL(argument);
+    if (specifier === null)
+      throw new Error(
+        `${fileName}: native worker/worklet module URL must be statically resolvable`,
+      );
+    if (!specifier.startsWith("."))
+      throw new Error(
+        `${fileName}: native worker/worklet modules must use a relative module URL`,
+      );
+    const entry = resolveModule(specifier);
+    const url = pathToFileURL(entry).href;
+    const kind = worker ? "worker" : "worklet";
+    const id = crypto
+      .createHash("sha256")
+      .update(`${kind}:${url}`)
+      .digest("hex")
+      .slice(0, 16);
+    modules.push({
+      kind,
+      entry,
+      url,
+      symbol: `gea_${kind}_${id}_top_level`,
+      id,
+    });
+    edits.push({
+      start: argument.start,
+      end: argument.end,
+      text: JSON.stringify(url),
+    });
+  };
+  traverse(source, { NewExpression: visit, CallExpression: visit });
+  let transformed = code;
+  for (const edit of edits.sort((a, b) => b.start - a.start))
+    transformed =
+      transformed.slice(0, edit.start) +
+      edit.text +
+      transformed.slice(edit.end);
+  return { code: transformed, modules };
+}
+
+export function writeWorkerRegistry(modules, output) {
+  const includes = ['#include "host/worker.h"'];
+  if (modules.some((module) => module.kind === "worklet"))
+    includes.push('#include "host/audio_worklet.h"');
+  const declarations = modules.map((module) => `void ${module.symbol}();`);
+  const registrations = modules.map((module) => {
+    const target = module.kind === "worker" ? "workers" : "audio_worklet";
+    return `  gea::host::${target}::registerModule(${JSON.stringify(module.url)}, ${module.symbol});`;
+  });
+  const content = `${includes.join("\n")}\n${declarations.join("\n")}\nnamespace {\nstruct RegisterWorkerModules {\nRegisterWorkerModules() {\n${registrations.join("\n")}\n}\n};\nRegisterWorkerModules registeredWorkerModules;\n}\n`;
+  if (!fs.existsSync(output) || fs.readFileSync(output, "utf8") !== content)
+    fs.writeFileSync(output, content);
+}
+
+/** Validate the supported native registration subset using symbol/type identity. */
+export function validateWorkletRegistrations(ts, entry, implementation) {
+  const program = ts.createProgram([entry], {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    allowJs: true,
+    skipLibCheck: true,
+    noEmit: true,
+  });
+  const checker = program.getTypeChecker();
+  const platformFile = fs.realpathSync(implementation);
+  const fail = (node, message) => {
+    const source = node.getSourceFile();
+    const location = source.getLineAndCharacterOfPosition(node.getStart());
+    throw new Error(`${source.fileName}:${location.line + 1}: ${message}`);
+  };
+  const visit = (node) => {
+    if (ts.isCallExpression(node)) {
+      const declaration = checker.getResolvedSignature(node)?.declaration;
+      if (
+        declaration &&
+        fs.realpathSync(declaration.getSourceFile().fileName) === platformFile &&
+        declaration.name?.getText() === "registerProcessor"
+      ) {
+        let constructor = node.arguments[1];
+        if (!constructor) fail(node, "registerProcessor requires a processor class");
+        while (ts.isParenthesizedExpression(constructor) || ts.isAsExpression(constructor) || ts.isTypeAssertionExpression(constructor))
+          constructor = constructor.expression;
+        let symbol = checker.getSymbolAtLocation(constructor);
+        if (symbol && symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+        const classDeclaration = ts.isClassExpression(constructor) ? constructor : symbol?.valueDeclaration;
+        if (!classDeclaration || (!ts.isClassDeclaration(classDeclaration) && !ts.isClassExpression(classDeclaration)))
+          fail(node, "Native registerProcessor requires a directly named class constructor; indirect constructor values are unsupported");
+        const type = checker.getTypeAtLocation(constructor);
+        if (type.getProperty("parameterDescriptors"))
+          fail(node, "AudioParam parameterDescriptors are not supported by this native AudioWorklet host");
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  for (const source of program.getSourceFiles()) {
+    if (!source.isDeclarationFile && fs.realpathSync(source.fileName) !== platformFile) visit(source);
+  }
+}

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

@@ -22,6 +22,7 @@
 // shared binary) without duplicate-definition errors when they share
 // an asset filename; the linker keeps one copy.
 
+import { describeStaticAsset } from './gea-static-asset.mjs'
 import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
@@ -276,7 +277,7 @@ if (assets.length === 0) {
   for (const file of assets) {
     const rel = relPath(file)
     const sym = assetSymbol(rel)
-    const aliases = [rel]
+    const aliases = [rel, describeStaticAsset(file).url]
     if (rel.startsWith('public/')) aliases.push(rel.slice('public/'.length))
     const condition = aliases
       .map((alias) => `(std::strcmp(path, ${JSON.stringify(alias)}) == 0 || (path[0] == '/' && std::strcmp(path + 1, ${JSON.stringify(alias)}) == 0))`)

package/typed-arrays.d.ts

@@ -0,0 +1,13 @@
+/** Standard binary base64 APIs, with the default base64 alphabet and padding. */
+declare global {
+  interface Uint8Array<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike> {
+    toBase64(): string
+  }
+
+  interface Uint8ArrayConstructor {
+    /** Decode using the standard default (loose) final-chunk handling. */
+    fromBase64(string: string): Uint8Array<ArrayBuffer>
+  }
+}
+
+export {}

package/workers.d.ts

@@ -0,0 +1,66 @@
+/** Web worker APIs implemented by the native host. */
+export type WorkerMessage = string | ArrayBuffer
+
+export interface MessageEvent<T = WorkerMessage> {
+  readonly data: T
+  readonly ports: MessagePort[]
+}
+
+export interface WorkerErrorEvent {
+  readonly message: string
+}
+
+export interface MessagePort {
+  onmessage: ((event: MessageEvent) => void) | null
+  postMessage(message: WorkerMessage, transfer?: (ArrayBuffer | MessagePort)[]): void
+  start(): void
+  close(): void
+}
+
+export interface MessageChannel {
+  readonly port1: MessagePort
+  readonly port2: MessagePort
+}
+
+export interface MessageChannelConstructor {
+  new (): MessageChannel
+}
+
+export interface WorkerOptions {
+  type?: 'classic' | 'module'
+  name?: string
+  credentials?: 'omit' | 'same-origin' | 'include'
+}
+
+export interface Worker {
+  onmessage: ((event: MessageEvent) => void) | null
+  onerror: ((event: WorkerErrorEvent) => void) | null
+  postMessage(message: WorkerMessage, transfer?: (ArrayBuffer | MessagePort)[]): void
+  terminate(): void
+}
+
+export interface WorkerConstructor {
+  new (scriptURL: string | URL, options?: WorkerOptions): Worker
+}
+
+export interface DedicatedWorkerGlobalScope {
+  onmessage: ((event: MessageEvent) => void) | null
+  postMessage(message: WorkerMessage, transfer?: (ArrayBuffer | MessagePort)[]): void
+  close(): void
+}
+
+declare global {
+  interface ImportMeta {
+    readonly url: string
+  }
+
+  interface URL {
+    readonly href: string
+    toString(): string
+  }
+
+  const URL: { new (url: string | URL, base?: string | URL): URL }
+  const Worker: WorkerConstructor
+  const MessageChannel: MessageChannelConstructor
+  const self: DedicatedWorkerGlobalScope
+}