@geastack/core 0.1.23

package/gea_app_entry.cpp

@@ -0,0 +1,317 @@
+// SPDX-License-Identifier: Apache-2.0
+// Adapter that runs a gea app compiled as:
+// TSX -> vite-plugin-gea JS -> geatsc C++.
+
+#include "app.h"
+#include "gea_perf_config.h"  // GEA_EMBEDDED_PERF master + per-subsystem perf flags
+#include "gea/embedded.h"
+#include "host/backends.h"
+#include "ui/style.h"
+#include "ui/tree_internal.h"  // Tree::mount for the post-mount clean repaint in init()
+
+#ifdef ESP_PLATFORM
+#include "esp_timer.h"
+#include "esp_log.h"
+#include "services/frame_scheduler.h"
+#else
+#include <chrono>
+#include <cstdio>
+#endif
+
+extern void __gea_top_level();
+#if !defined(GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT) || !GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT
+// Forward-declared inline runtime helper from packages/geatsc/src/targets/cpp/runtime/value.cpp.
+// Drops pending microtasks WITHOUT firing them — see comment in value.cpp.
+extern void gea_cpp_clear_microtasks();
+#endif
+namespace gea::framework::app::generated {
+void drainMicrotasks();
+}  // namespace gea::framework::app::generated
+
+extern "C" void gea_cycle_collection_defer_begin() __attribute__((weak));
+extern "C" void gea_cycle_collection_defer_end() __attribute__((weak));
+
+namespace gea::framework::app {
+
+namespace {
+
+// May be unused when all per-frame perf consumers are compiled out
+// (GEA_FRAME_PHASE_TIMING==0 and GEA_FRAME_PERF_LOG==0): phaseClockUs() returns
+// a constant 0 and the window-log blocks vanish, leaving no caller.
+[[maybe_unused]] std::int64_t nowUs()
+{
+#ifdef ESP_PLATFORM
+	return esp_timer_get_time();
+#else
+	using Clock = std::chrono::steady_clock;
+	return std::chrono::duration_cast<std::chrono::microseconds>(Clock::now().time_since_epoch()).count();
+#endif
+}
+
+bool applicationFrameOwnsMountedRefresh()
+{
+#ifdef ESP_PLATFORM
+	return !gea::framework::services::FrameScheduler::vsyncDriven();
+#else
+	return true;
+#endif
+}
+
+class FrameCycleCollectionDeferral {
+public:
+	FrameCycleCollectionDeferral()
+		: active_(gea_cycle_collection_defer_begin && gea_cycle_collection_defer_end)
+	{
+		if (active_) gea_cycle_collection_defer_begin();
+	}
+	~FrameCycleCollectionDeferral() { if (active_) gea_cycle_collection_defer_end(); }
+
+private:
+	bool active_;
+};
+
+}  // namespace
+
+void Application::init(int width, int height, double devicePixelRatio)
+{
+	// Top-level construction allocates the entire native object graph. Keep the
+	// generated collector at a host safepoint until initialization has unwound,
+	// just as Application::frame does for animation callbacks.
+	FrameCycleCollectionDeferral deferCycleCollection;
+#if defined(GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT) && GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT
+	(void)width;
+	(void)height;
+	(void)devicePixelRatio;
+	gea::host::resetAnimationFrameCallbacks();
+	gea::host::resetScheduledTimers();
+	__gea_top_level();
+#else
+	if (width > 0 && height > 0) {
+		gea::embedded::ui::Document::setPreferredMountSize(width, height);
+		// `vw`/`vh` resolve against the physical viewport. Explicit CSS `px`
+		// lengths resolve through the target's device pixel ratio.
+		gea::embedded::ui::setViewportMetrics(width, height, devicePixelRatio);
+	}
+	gea::host::resetAnimationFrameCallbacks();
+	gea::host::resetScheduledTimers();
+	// DROP (don't fire) any pending microtasks left over from the previous
+	// app. The runtime's gea_cpp_microtask_queue is a process-wide static-inline;
+	// reactive-binding callbacks scheduled by the previous app's last tick
+	// hold node-id references and would otherwise fire on the new app's
+	// first frame against reused indexes — leaking styles/transforms (analog-
+	// clock hand rotations into breakout, balls-jsx positions into launcher
+	// cards). DRAINING (firing them) is unsafe at this boundary because some
+	// callbacks reach back into the runtime and synchronously touch display
+	// state, which interleaves badly with the panel/SPI flush pipeline and
+	// has been observed to wedge the SPI driver in mid-tx. CLEARING is safe:
+	// the previous tree is being destroyed by Document::clear() on the next
+	// line, so the dropped callbacks couldn't have done anything useful.
+	gea_cpp_clear_microtasks();
+	gea::embedded::ui::Document::instance().clear();
+	// Defer per-node class-style recomputes for the duration of the initial
+	// mount: __gea_top_level registers the stylesheet and builds the whole tree,
+	// and recomputing each node's class styles per setTagName/setClassName/
+	// appendChild is O(nodes^2 x rules). endStyleMountBatch() does one full pass.
+	gea::embedded::ui::beginStyleMountBatch();
+	__gea_top_level();
+	gea::embedded::ui::endStyleMountBatch();
+	gea::embedded::ui::Document::instance().refreshMountedIfDirty();
+
+	// The initial mount inside __gea_top_level() ran while the style batch was
+	// still open, so Tree::mount SKIPPED its flush (that frame is unstyled). Now
+	// that endStyleMountBatch() has applied styles, do one clean full re-mount to
+	// present the first STYLED frame. This is the guaranteed first present (it
+	// can't be skipped — the batch is closed) and repaints the whole framebuffer
+	// from settled layout, so there's no flash of unstyled content and no stale
+	// pre-layout pixels. One cheap full paint at startup, before the frame loop.
+	{
+		auto &tree = gea::embedded::ui::Tree::instance();
+		const int root = tree.mountedRoot();
+		if (root >= 0) tree.mount(root, tree.mountedWidth(), tree.mountedHeight());
+	}
+#endif
+}
+
+namespace {
+
+// Rolling-window frame stats: every kFrameLogInterval frames, log the per-phase
+// µs aggregates and reset. Gives us a "where did the time go over the last ~1
+// sec" view without a UI overlay or external profiler. GEA_FRAME_PERF_LOG (this
+// file's "gea.perf:" line) and GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LOG (the esp32
+// scheduler harvest) — and the GEA_EMBEDDED_PERF master that governs both — are
+// defined in gea_perf_config.h (included via app.h-side headers / directly).
+//
+// The per-frame phase TIMING (the nowUs() reads bracketing each phase + the stat
+// accumulation in recordFramePhase) only has a consumer when one of those flags
+// is on, so gate it on their OR. With both off (master off) the timing is pure
+// dead work (~10 esp_timer_get_time() reads/frame feeding an accumulator nobody
+// reads). NOTE: applicationFramePhaseSet() stays UNGATED below — it is a single
+// relaxed atomic store feeding the frame watchdog's "app_phase=" stall report
+// (see frame_scheduler.cpp), not perf machinery.
+#define GEA_FRAME_PHASE_TIMING (GEA_FRAME_PERF_LOG || GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LOG)
+
+#if GEA_FRAME_PERF_LOG
+// 300-frame window (~5s). Each emission is an ESP_LOGI on the frame task; at 60 frames
+// it cost ~1 dropped VBlank per ~60 under TE-sync (the frame overran its ~16.7ms TE
+// window during the console write). A 5s cadence keeps the rolling fps/phase readout
+// while making that perturbation negligible, so vsync stays locked at the panel rate.
+constexpr int kFrameLogInterval = 300;
+int gFrameLogCounter = 0;
+int64_t gFrameLogWindowStartUs = 0;
+// The window keeps its OWN sums. The shared applicationFramePerfStats
+// accumulator is owned per-frame by the esp32 frame scheduler: runFrame()
+// resets it at frame start and harvests it after the app callback for the
+// perf-lite line. Reading/resetting it here used to (a) show ~one frame's
+// stats divided by kFrameLogInterval — near-zero busy/idle regardless of real
+// load — and (b) zero the 60th frame before the scheduler's harvest.
+ApplicationFramePerfStats gWindowPerfStats;
+// Sum of Application::frame() entry→exit wall over the window. Splits the
+// idle (= wall − busy) into in-callback non-phase overhead (appWall − busy) vs
+// out-of-callback scheduler dispatch (wall − appWall) — the 0.9ms-idle hunt.
+int64_t gAppFrameWallUs = 0;
+
+void logFramePerfWindow(int64_t windowEndUs)
+{
+	const ApplicationFramePerfStats stats = gWindowPerfStats;
+	const int64_t totalPhaseUs = stats.drainMicrotasksUs + stats.animationFrameUs +
+	                             stats.styleRecomputeUs + stats.documentFrameUs +
+	                             stats.refreshMountedUs;
+	const int64_t wallUs = windowEndUs - gFrameLogWindowStartUs;
+	const double frames = kFrameLogInterval;
+	const double fps = wallUs > 0 ? (frames * 1e6) / static_cast<double>(wallUs) : 0.0;
+	const double drainMs = stats.drainMicrotasksUs / 1000.0 / frames;
+	const double animMs = stats.animationFrameUs / 1000.0 / frames;
+	const double styleMs = stats.styleRecomputeUs / 1000.0 / frames;
+	const double docMs = stats.documentFrameUs / 1000.0 / frames;
+	const double refMs = stats.refreshMountedUs / 1000.0 / frames;
+	const double busyMs = totalPhaseUs / 1000.0 / frames;
+	const double wallMsPerFrame = wallUs / 1000.0 / frames;
+	const double idleMs = wallMsPerFrame - busyMs;
+	const double appWallMs = gAppFrameWallUs / 1000.0 / frames;
+	const double appOverheadMs = appWallMs - busyMs;       // non-phase work inside the callback
+	const double dispatchMs = wallMsPerFrame - appWallMs;  // scheduler dispatch outside the callback
+#ifdef ESP_PLATFORM
+	ESP_LOGI("gea.perf",
+	         "fps=%.1f wall=%.2fms busy=%.2fms idle=%.2fms(appovh=%.2f disp=%.2f) | drain=%.2f anim=%.2f style=%.2f doc=%.2f refresh=%.2f",
+	         fps, wallMsPerFrame, busyMs, idleMs, appOverheadMs, dispatchMs, drainMs, animMs, styleMs, docMs, refMs);
+#else
+	std::printf("[gea.perf] fps=%.1f wall=%.2fms busy=%.2fms idle=%.2fms(appovh=%.2f disp=%.2f) | drain=%.2f anim=%.2f style=%.2f doc=%.2f refresh=%.2f\n",
+	            fps, wallMsPerFrame, busyMs, idleMs, appOverheadMs, dispatchMs, drainMs, animMs, styleMs, docMs, refMs);
+#endif
+	gWindowPerfStats = {};
+	gAppFrameWallUs = 0;
+}
+#endif  // GEA_FRAME_PERF_LOG
+
+// Reads the frame timer ONLY when a per-frame perf consumer is compiled in (see
+// GEA_FRAME_PHASE_TIMING). Otherwise returns 0, so the bracketing reads + the
+// recordFramePhase() adds below constant-fold to nothing — a production build
+// pays zero for phase instrumentation.
+std::int64_t phaseClockUs()
+{
+#if GEA_FRAME_PHASE_TIMING
+	return nowUs();
+#else
+	return 0;
+#endif
+}
+
+// Feeds whichever per-frame perf consumers are compiled in: the shared
+// accumulator harvested by the esp32 scheduler (GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LOG)
+// and/or this file's rolling app-perf window (GEA_FRAME_PERF_LOG). A no-op when
+// neither is set.
+void recordFramePhase(ApplicationFramePhase phase, int64_t durationUs)
+{
+#if GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LOG
+	applicationFramePerfStatsAdd(phase, durationUs);
+#endif
+#if GEA_FRAME_PERF_LOG
+	applicationFramePerfStatsAdd(gWindowPerfStats, phase, durationUs);
+#endif
+#if !GEA_FRAME_PHASE_TIMING
+	(void)phase;
+	(void)durationUs;
+#endif
+}
+
+}  // namespace
+
+void Application::frame(int timestampMs)
+{
+	// Generated callbacks keep native references in ordinary C++ stack locals.
+	// An allocation-pressure collection inside one of those callbacks cannot see
+	// those roots, so defer it until every phase in this frame has unwound.
+	FrameCycleCollectionDeferral deferCycleCollection;
+#if defined(GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT) && GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT
+	applicationFramePhaseSet(ApplicationFramePhase::DrainMicrotasks);
+	generated::drainMicrotasks();
+	applicationFramePhaseSet(ApplicationFramePhase::AnimationFrameCallbacks);
+	gea::host::runAnimationFrameCallbacks(static_cast<gea::host::AnimationFrameTimestamp>(timestampMs));
+	generated::drainMicrotasks();
+	applicationFramePhaseSet(ApplicationFramePhase::Idle);
+#else
+#if GEA_FRAME_PERF_LOG
+	if (gFrameLogWindowStartUs == 0) gFrameLogWindowStartUs = nowUs();
+	const int64_t kAppFrameStartUs = nowUs();
+#endif
+
+	gea::framework::display::DisplayBackend::updateAutoRotationFromAccelerometer();
+
+	// Coalesce class-style recomputes triggered by this frame's reactive updates
+	// (microtask drains + rAF callbacks). Without this, one interaction that
+	// changes a near-root class — e.g. a weather city switch flipping the shell's
+	// theme class — triggers a full-tree style recompute per change on the frame
+	// task, freezing the UI for seconds. endStyleMountBatch() does one coalesced
+	// pass before layout/render; it is cheap when no class change was deferred.
+	gea::embedded::ui::beginStyleMountBatch();
+
+	int64_t startUs = phaseClockUs();
+	applicationFramePhaseSet(ApplicationFramePhase::DrainMicrotasks);
+	generated::drainMicrotasks();
+	recordFramePhase(ApplicationFramePhase::DrainMicrotasks, phaseClockUs() - startUs);
+
+	startUs = phaseClockUs();
+	applicationFramePhaseSet(ApplicationFramePhase::AnimationFrameCallbacks);
+	gea::host::runAnimationFrameCallbacks(static_cast<double>(timestampMs));
+	generated::drainMicrotasks();
+	gea::host::websocket::runCallbacks();
+	gea::host::rtc::runCallbacks();
+	gea::host::http::runRequests();
+	recordFramePhase(ApplicationFramePhase::AnimationFrameCallbacks, phaseClockUs() - startUs);
+
+	// Apply the coalesced style recompute for everything changed above, so layout
+	// and render below see final styles. Measured as its own phase: a city/theme
+	// class change near the root cascades a full-subtree recompute here, and it was
+	// previously invisible (folded into `app=` but in no phase counter).
+	startUs = phaseClockUs();
+	applicationFramePhaseSet(ApplicationFramePhase::StyleRecompute);
+	gea::embedded::ui::endStyleMountBatch();
+	recordFramePhase(ApplicationFramePhase::StyleRecompute, phaseClockUs() - startUs);
+
+	startUs = phaseClockUs();
+	applicationFramePhaseSet(ApplicationFramePhase::DocumentFrame);
+	gea::embedded::ui::Document::instance().frame(timestampMs);
+	recordFramePhase(ApplicationFramePhase::DocumentFrame, phaseClockUs() - startUs);
+
+	startUs = phaseClockUs();
+	applicationFramePhaseSet(ApplicationFramePhase::RefreshMounted);
+	if (applicationFrameOwnsMountedRefresh())
+		gea::embedded::ui::Document::instance().refreshMountedIfDirty();
+	recordFramePhase(ApplicationFramePhase::RefreshMounted, phaseClockUs() - startUs);
+	applicationFramePhaseSet(ApplicationFramePhase::Idle);
+
+#if GEA_FRAME_PERF_LOG
+	gAppFrameWallUs += nowUs() - kAppFrameStartUs;
+	if (++gFrameLogCounter >= kFrameLogInterval) {
+		const int64_t windowEndUs = nowUs();
+		logFramePerfWindow(windowEndUs);
+		gFrameLogCounter = 0;
+		gFrameLogWindowStartUs = windowEndUs;
+	}
+#endif
+#endif
+}
+
+void Application::toggleSettings() {}
+
+}  // namespace gea::framework::app

package/gea_sources.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// Shared geastack framework source manifest — the SINGLE SOURCE OF TRUTH for the
+// always-linked framework C/C++ source set and include roots. Target builds
+// (simulator build-web.sh, and the esp32/geaos CMake) read this instead of
+// hardcoding source lists. As files move between the new packages
+// (core/host/engine/elements/geaos) during the decomposition, ONLY this file
+// changes and every target follows. See docs/package-architecture-plan.md.
+//
+// This is Node rather than shell because CMake has to read it on Windows too,
+// where there is no bash: `execute_process(COMMAND bash -c ...)` failed
+// outright and no ESP32 target could configure. Node is already a hard
+// requirement of every path that reaches here (the CLI and geatsc are Node),
+// so it costs no new dependency. gea_sources.sh remains as a thin wrapper for
+// the shell callers that source it.
+//
+// Caller must export GEA_CORE = the @geastack/core package dir. In a normal npm
+// install the CLI resolves every package through Node's npm layout and exports
+// its exact directory before invoking a native build.
+// ALL package include roots are on every -I line (flat `ui/…`/`host/…` spellings
+// preserved) so a header resolves wherever its package put it.
+//
+// NOTE: app-specific sources (gea_app_entry and generated program/font/assets)
+// and target shims (web_*, esp_*) are NOT here — they stay in the target build.
+// This manifest is only the always-linked shared framework.
+
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Paths are joined with `/` rather than path.join: the output feeds CMake and
+// compiler command lines, which take forward slashes on every platform, and it
+// keeps the emitted strings byte-identical to what the shell manifest produced.
+const join = (...parts) => parts.join('/')
+
+function packageDirs(env) {
+  const read = (name) => {
+    const value = env[name]
+    if (!value) throw new Error(`${name} unset`)
+    return value
+  }
+  return {
+    core: read('GEA_CORE'),
+    host: read('GEA_HOST_DIR'),
+    engine: read('GEA_ENGINE_DIR'),
+    elements: read('GEA_ELEMENTS_DIR'),
+    geaos: read('GEA_GEAOS_PACKAGE_DIR')
+  }
+}
+
+export function includeFlags(env = process.env) {
+  const { core, host, engine, elements, geaos } = packageDirs(env)
+  return [
+    join(core, 'include'),
+    core,
+    join(host, 'include'),
+    host,
+    engine,
+    join(engine, 'ui'),
+    elements,
+    join(elements, 'ui'),
+    geaos,
+    join(engine, 'vendor/stb'),
+    join(engine, 'vendor/AnimatedGIF')
+  ].map((dir) => `-I${dir}`)
+}
+
+export function cSources(env = process.env) {
+  const { engine } = packageDirs(env)
+  return [join(engine, 'vendor/AnimatedGIF/AnimatedGIF.c')]
+}
+
+export function cxxSources(env = process.env) {
+  const { core, host, engine, elements, geaos } = packageDirs(env)
+  const cpp = (dir, names) => names.map((name) => join(dir, `${name}.cpp`))
+  return [
+    // @geastack/engine — machinery + intrinsics + text-input/keyboard runtime
+    ...cpp(join(engine, 'ui'), [
+      'tree_state', 'node_lifecycle', 'display_invalidation', 'layout_snapshot',
+      'absolute_leaf_refresh', 'viewport_region', 'dirty_regions', 'root_scroll_refresh',
+      'node', 'view_element', 'text_element', 'image_element', 'style', 'css_atom',
+      'document', 'core', 'tree_nodes', 'tree_style', 'tree_scroll_mirror', 'tree_render',
+      'view', 'text', 'image_node', 'layout', 'render', 'input', 'input_render',
+      'virtual_keyboard', 'canvas_element', 'canvas_store', 'tree_events'
+    ]),
+    ...cpp(engine, ['canvas', 'image_store', 'bitmap_font', 'rasterized_font', 'touch_runtime']),
+    // @geastack/elements — optional rich elements (engine still dispatches via NodeType until the behavior-table lands)
+    ...cpp(join(elements, 'ui'), ['camera_element', 'virtual_list']),
+    // @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',
+      'tile_loader'
+    ]),
+    // framework services (built on the platform abstraction — no target-specific deps)
+    ...cpp(join(host, 'services'), [
+      'app_state', 'battery_service', 'bluetooth_service', 'diagnostics',
+      'diagnostics_connection', 'diagnostics_server', 'mirror', 'network_services',
+      'runtime_log'
+    ]),
+    // @geastack/core — single-app shell: frame loop + perf + event dispatch
+    ...cpp(core, ['app_frame_perf', 'runtime', 'events']),
+    // geaos — installed-application platform integration
+    ...cpp(geaos, ['app_manager', 'installed_apps'])
+  ]
+}
+
+const queries = {
+  'include-flags': includeFlags,
+  'c-sources': cSources,
+  'cxx-sources': cxxSources
+}
+
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (invokedDirectly) {
+  const query = queries[process.argv[2]]
+  if (!query) {
+    process.stderr.write(`usage: gea_sources.mjs ${Object.keys(queries).join('|')}\n`)
+    process.exit(2)
+  }
+  try {
+    process.stdout.write(`${query().join('\n')}\n`)
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`)
+    process.exit(1)
+  }
+}

package/gea_sources.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Shell front end for the framework source manifest. The manifest itself now
+# lives in gea_sources.mjs — CMake has to read it on Windows too, where there is
+# no bash, so `execute_process(COMMAND bash -c ...)` failed and no ESP32 target
+# could configure. Node is already a hard requirement of every path that gets
+# here (the CLI and geatsc are Node), so reading it from Node costs no new
+# dependency, and keeping these three function names means shell callers that
+# `source` this file (simulator build-web.sh, core's own test) do not change.
+#
+# Caller must export GEA_CORE = the @geastack/core package dir, plus
+# GEA_HOST_DIR / GEA_ENGINE_DIR / GEA_ELEMENTS_DIR / GEA_GEAOS_PACKAGE_DIR.
+# gea_sources.mjs names any that are missing and exits non-zero.
+
+# The manifest sits next to this file, so locate it from BASH_SOURCE rather than
+# from GEA_CORE: sourcing still works when a caller points GEA_CORE at a
+# workspace symlink whose spelling differs from this checkout's.
+__GEA_SOURCES_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Run from that directory and name the manifest relatively: under Git Bash a
+# native node.exe would otherwise receive a POSIX path, which only works while
+# MSYS path conversion is enabled and turns into `C:\c\Users\...` when it is not.
+__gea_sources_run() {
+  ( cd "$__GEA_SOURCES_DIR" && node ./gea_sources.mjs "$1" )
+}
+
+gea_fw_include_flags() {
+  __gea_sources_run include-flags
+}
+
+gea_fw_c_sources() {
+  __gea_sources_run c-sources
+}
+
+gea_fw_cxx_sources() {
+  __gea_sources_run cxx-sources
+}

package/include/app.h

@@ -0,0 +1,60 @@
+#pragma once
+
+#include <cstdint>
+
+#ifndef GEA_EMBEDDED_CSS_DEVICE_PIXEL_RATIO
+#define GEA_EMBEDDED_CSS_DEVICE_PIXEL_RATIO 1.0
+#endif
+
+// The ratio the FRAME LOOP hands to Application::init, i.e. the one that makes
+// `width: 100px` mean 100 or 200 physical pixels. It is deliberately separate
+// from GEA_EMBEDDED_CSS_DEVICE_PIXEL_RATIO above: that one is what a BOARD
+// declares, and boards declare it for the font rasteriser (the CMakeLists hands
+// the same variable to geatsc as --font-device-pixel-ratio, which bakes glyph
+// atlases at cssPx * ratio). Runtime::run passed a hardcoded 1.0 for layout, so
+// on every board declaring 1.5 the two disagreed. Promoting the board's value to
+// the layout ratio would relayout every app already authored against the 1.0
+// behaviour, so the layout ratio stays 1.0 unless an APP asks for another one --
+// only the app's own CSS knows which pixels its lengths are written in. Declare
+// it with `gea.cssDevicePixelRatio` in the app manifest: the CLI sets this and
+// the font ratio together, so the atlas and the layout agree.
+#ifndef GEA_EMBEDDED_CSS_LAYOUT_DEVICE_PIXEL_RATIO
+#define GEA_EMBEDDED_CSS_LAYOUT_DEVICE_PIXEL_RATIO 1.0
+#endif
+
+namespace gea::framework::app {
+
+enum class ApplicationFramePhase : std::uint8_t {
+	Idle,
+	DrainMicrotasks,
+	AnimationFrameCallbacks,
+	StyleRecompute,
+	DocumentFrame,
+	RefreshMounted,
+};
+
+struct ApplicationFramePerfStats {
+	std::int64_t drainMicrotasksUs = 0;
+	std::int64_t animationFrameUs = 0;
+	std::int64_t styleRecomputeUs = 0;
+	std::int64_t documentFrameUs = 0;
+	std::int64_t refreshMountedUs = 0;
+};
+
+class Application {
+public:
+	static void init(int width, int height, double devicePixelRatio = GEA_EMBEDDED_CSS_DEVICE_PIXEL_RATIO);
+	static void frame(int timestampMs);
+	static void toggleSettings();
+};
+
+void applicationFramePerfStatsReset();
+void applicationFramePerfStatsAdd(ApplicationFramePhase phase, std::int64_t durationUs);
+void applicationFramePerfStatsAdd(ApplicationFramePerfStats &stats, ApplicationFramePhase phase,
+                                  std::int64_t durationUs);
+ApplicationFramePerfStats applicationFramePerfStatsRead();
+void applicationFramePhaseSet(ApplicationFramePhase phase);
+ApplicationFramePhase applicationFramePhaseRead();
+const char *applicationFramePhaseName(ApplicationFramePhase phase);
+
+}  // namespace gea::framework::app

package/include/apps.h

@@ -0,0 +1,46 @@
+#pragma once
+
+namespace gea::framework::apps {
+
+struct InstalledAppPlanEntry {
+	const char *appId = nullptr;
+	const char *slotLabel = nullptr;
+};
+
+class InstalledApps {
+public:
+	static int planCount();
+	static const InstalledAppPlanEntry *planAt(int index);
+};
+
+class AppLauncherPlatform {
+public:
+	virtual ~AppLauncherPlatform() = default;
+
+	virtual const char *currentInstalledAppId() = 0;
+	virtual bool runningAppIsLauncher(const char *launcherAppId) = 0;
+	virtual bool launchInstalledApp(const char *appId) = 0;
+	virtual void startLauncherButtonTask() {}
+};
+
+class AppManager {
+public:
+	static constexpr const char *launcherAppId() { return "app-launcher"; }
+	static void setPlatform(AppLauncherPlatform *platform);
+	static AppLauncherPlatform *platform();
+	static const char *currentId();
+	static bool launch(const char *appId);
+	static bool returnRunningAppToLauncher(const char *trigger);
+	static bool queueSettingsToggle();
+	static bool shouldEnableLauncherButton();
+	static void startLauncherButtonTask();
+};
+
+namespace generated {
+
+int installedAppPlanCount();
+const InstalledAppPlanEntry *installedAppPlanAt(int index);
+
+}
+
+}  // namespace gea::framework::apps

package/include/audio.h

@@ -0,0 +1,90 @@
+#pragma once
+
+#ifdef __cplusplus
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+namespace gea::platform::audio {
+
+enum class OscillatorType {
+	Sine = 0,
+	Square = 1,
+	Sawtooth = 2,
+	Triangle = 3,
+};
+
+using NativeAudioHandle = std::uintptr_t;
+
+class AudioParam {
+public:
+	explicit AudioParam(NativeAudioHandle oscillator = 0);
+	double value() const;
+	void setValue(double value);
+	void setValueAtTime(double value, double start_time);
+
+private:
+	NativeAudioHandle oscillator_;
+};
+
+class AudioNode {
+public:
+	NativeAudioHandle nativeId() const;
+
+protected:
+	explicit AudioNode(NativeAudioHandle native);
+
+private:
+	NativeAudioHandle native_;
+};
+
+class AudioDestinationNode : public AudioNode {
+public:
+	explicit AudioDestinationNode(NativeAudioHandle native = 0);
+};
+
+class OscillatorNode : public AudioNode {
+public:
+	explicit OscillatorNode(NativeAudioHandle native = 0);
+
+	OscillatorType type() const;
+	void setType(OscillatorType type);
+	void connect(const AudioDestinationNode &destination);
+	void start(double when = 0.0);
+	void stop(double when = 0.0);
+
+	AudioParam frequency;
+};
+
+class AudioContext {
+public:
+	double currentTime() const;
+	AudioDestinationNode destination() const;
+	OscillatorNode createOscillator() const;
+};
+
+class AudioSystem {
+public:
+	static AudioContext sharedContext();
+	static int volume();
+	static void setVolume(int volume_percent);
+	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();
+};
+
+#ifdef GEA_AUDIO_DRIVER_INTERNAL
+class OutputDriver {
+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 int volume();
+	static void setVolume(int volume_percent);
+};
+#endif
+
+}  // namespace gea::platform::audio
+
+#endif