A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
docs(comments): drop transient rearch design-doc references from comments
esengine0f43f0c2d5bf
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsxindex 32ad07d4e..2370e1608 100644--- a/desktop/src/App.tsx+++ b/desktop/src/App.tsx@@ -59,7 +59,7 @@ export function App() {// Play runs in an ISOLATED realm (the Game panel's iframe = the shipping// runtime), NOT by flipping the main edit World — so gameplay can never dirty- // the scene and the Viewport stays a live Scene view (REARCH_EDITOR_REALM R2).+ // the scene and the Viewport stays a live Scene view.// (The headless/automation path still drives the main World via// EditorControlSurface.setRunMode + step for deterministic capture.)const isPlaying = useEditorStore((s) => s.isPlaying);diff --git a/desktop/src/components/BuildDialog.tsx b/desktop/src/components/BuildDialog.tsxindex fdb2951e7..a5b9c0a62 100644--- a/desktop/src/components/BuildDialog.tsx+++ b/desktop/src/components/BuildDialog.tsx@@ -1,8 +1,8 @@// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file BuildDialog.tsx — the UE5-style "Package Project" modal (REARCH_EDITOR_REALM- * Phase S). Pick a platform + configuration + output, hit Build, watch the+ * @file BuildDialog.tsx — the UE5-style "Package Project" modal.+ * Pick a platform + configuration + output, hit Build, watch the* cook → bundle → copy run, then reveal the output. Web is the live target;* WeChat/Playable/Native are shown disabled (the engine has those wasm* targets, but the project export only wires Web today).diff --git a/desktop/src/document/AssetDocument.ts b/desktop/src/document/AssetDocument.tsindex d084714aa..dc6ec8ff8 100644--- a/desktop/src/document/AssetDocument.ts+++ b/desktop/src/document/AssetDocument.ts@@ -3,7 +3,7 @@/*** @file AssetDocument.ts* @brief Reactive, undoable in-memory asset document — the shared base for- * single-file asset editors (docs/REARCH_ANIMATION.md L4 / P5).+ * single-file asset editors.** Mirrors the scene's model-authoritative reactivity for ONE asset file: the* typed in-memory asset is the source of truth, panels subscribe viadiff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.tsindex 5fcf6875b..ba79df558 100644--- a/desktop/src/engine/EditorControlSurface.ts+++ b/desktop/src/engine/EditorControlSurface.ts@@ -8,8 +8,7 @@* headless verification host, and (later) the editor MCP server, which* is a transport adapter over this object rather than a parallel API.*- * Design and phasing: docs/REARCH_EDITOR_AUTOMATION.md + REARCH_EDITOR_MODEL.md- * (P2: the session boundary). This adds no new truth — commands route through+ * This adds no new truth — commands route through* the session's SceneCommands (the model write boundary), reads through its* SceneQuery / SceneModel (the model is the source of truth; the World is a* derived projection), and observation reads the live canvas/World (process-diff --git a/desktop/src/engine/EditorSession.ts b/desktop/src/engine/EditorSession.tsindex 35f09afab..498eedbd0 100644--- a/desktop/src/engine/EditorSession.ts+++ b/desktop/src/engine/EditorSession.ts@@ -10,7 +10,7 @@ import { useSelection, createSelectionStore, type SelectionStore } from '@/storeimport { EditorControlSurfaceImpl } from './EditorControlSurface';/**- * The single editor boundary (REARCH_EDITOR_MODEL.md §3.5, P2). One instance owns+ * The single editor boundary. One instance owns* the whole editor-state graph — {model, history, store (reactivity), reconciler* (model→World), selection, commands, query} — and exposes one façade* ({@link EditorControlSurface}) for the UI, the headless host, and the MCP server.@@ -94,6 +94,6 @@ export class EditorSession {export const defaultSession = EditorSession.default;/** The app's default-session control surface — the ONE programmatic boundary for- * the UI, the headless host, and the MCP server (REARCH_EDITOR_MODEL.md P2). */+ * the UI, the headless host, and the MCP server. */export const EditorControlSurface = defaultSession.surface;export type { EditorControlSurfaceT } from './EditorControlSurface';diff --git a/desktop/src/engine/EngineGuard.ts b/desktop/src/engine/EngineGuard.tsindex cd0d9f531..19b04d7a7 100644--- a/desktop/src/engine/EngineGuard.ts+++ b/desktop/src/engine/EngineGuard.ts@@ -20,8 +20,6 @@ import { ABI_LAYOUT_HASH } from 'esengine';* without re-running the sync, and we must never block a genuinely-fine boot on* stale metadata. The authoritative fatal check stays in the runtime handshake,* which reads the real binary.- *- * @see REARCH frontier doc RC12 §E1.*/const MANIFEST_URL = '/wasm/wasm.manifest.json';diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.tsindex 2c940a785..951e12210 100644--- a/desktop/src/engine/EngineHost.ts+++ b/desktop/src/engine/EngineHost.ts@@ -239,7 +239,7 @@ class EngineHostImpl {return { x: t.position.x, y: t.position.y, orthoSize: c.orthoSize ?? 360 };}- // — Headless / automation drive (see docs/REARCH_EDITOR_AUTOMATION.md) —+ // — Headless / automation drive —// The live editor lets the engine drive its own rAF loop (app.run()); a// headless render host or a verification/automation driver instead advances// frames itself, so it can capture a deterministic, reproducible frame. These@@ -302,7 +302,7 @@ class EngineHostImpl {/*** Boot the engine without a DOM viewport or a self-driving loop, for the- * headless render host (see docs/REARCH_EDITOR_AUTOMATION.md): a fixed-size+ * headless render host: a fixed-size* offscreen canvas, no initial scene (the driver loads one), and frames* advanced manually via tick() so captures are deterministic. Resolves once* the engine is ready; the driver then does loadScene → step → captureViewport.@@ -410,8 +410,8 @@ class EngineHostImpl {// Model-authoritative wiring (Reconciler model→World projection + SceneStore// reactivity) is owned by the EditorSession (constructed at app/headless- // entry), not here — EngineHost is a pure engine host (REARCH_EDITOR_MODEL.md- // P2). The session's wiring only subscribes the model, so it is in place+ // entry), not here — EngineHost is a pure engine host.+ // The session's wiring only subscribes the model, so it is in place// before this boot loads the initial scene.if (opts.loadInitialScene) {diff --git a/desktop/src/engine/PlayRealm.ts b/desktop/src/engine/PlayRealm.tsindex 7400b8453..2748f789a 100644--- a/desktop/src/engine/PlayRealm.ts+++ b/desktop/src/engine/PlayRealm.ts@@ -1,8 +1,8 @@// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file PlayRealm.ts — controller for the isolated play realm (REARCH_EDITOR_REALM- * Phase R2). Owns a detached <iframe> (play.html) re-parented into the Game+ * @file PlayRealm.ts — controller for the isolated play realm.+ * Owns a detached <iframe> (play.html) re-parented into the Game* panel (mirrors EngineHost's detached-canvas pattern), and the typed* postMessage protocol with it:* out → init {sceneData, assetManifest} · setPaused {paused}diff --git a/desktop/src/engine/PrefabInstance.ts b/desktop/src/engine/PrefabInstance.tsindex 94ecbe65a..8e4b2c89f 100644--- a/desktop/src/engine/PrefabInstance.ts+++ b/desktop/src/engine/PrefabInstance.ts@@ -16,7 +16,7 @@ import type {* `expandEntry` / `collapseEntry` and the `PrefabInstanceDelta` /* `PrefabInstanceEntry` / `AddedEntity` types — now lives in the ENGINE* (`esengine`, sdk/src/prefab/sceneInstance.ts) so the editor and the runtime- * scene loader (`loadSceneWithAssets`, REARCH_PREFABS PF1 — play == ship) share+ * scene loader (`loadSceneWithAssets` — play == ship) share* ONE implementation and can never diverge. This module re-exports that core* and adds the editor-only layer on top: the SceneModel's per-entity instance* TAGS and the tag-producing whole-scene expand/collapse the ProjectStore runsdiff --git a/desktop/src/engine/Reconciler.ts b/desktop/src/engine/Reconciler.tsindex 8b8645574..38586d9d4 100644--- a/desktop/src/engine/Reconciler.ts+++ b/desktop/src/engine/Reconciler.ts@@ -8,9 +8,9 @@ import { SceneModel, SceneModelImpl, type ModelEvent } from './SceneModel';import { componentByName, componentDefaults, type AnyComp, type WorldT } from './schema';/**- * Projects the model into the World (REARCH_EDITOR_MODEL.md §3.3).+ * Projects the model into the World.*- * The invariant the whole rearchitecture rests on: **the World is a pure+ * The invariant the whole model rests on: **the World is a pure* function of the Model.** Commands mutate the model only; the model emits a* change event; this reconciler is the SINGLE place that writes the World in* response. There is no other path from a command to the World, so the twodiff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.tsindex 04c50734b..155b160be 100644--- a/desktop/src/engine/SceneCommands.ts+++ b/desktop/src/engine/SceneCommands.ts@@ -25,7 +25,7 @@ export interface TilePaint {tileId: number;}-// — Model-authoritative commands (REARCH_EDITOR_MODEL.md) —+// — Model-authoritative commands —//// Every mutation edits the SceneModel ONLY (the session's source of truth). The// model emits a change event; the Reconciler projects it to the World. Nothing@@ -114,7 +114,7 @@ export class SceneCommandsImpl {private gesture: { label: string; touched: Map<string, FieldEdit> } | null = null;// Optional observer/interceptor on the field-edit door — the Sequencer's record- // mode registers it to auto-key edits (REARCH_ANIMATION). Returning true+ // mode registers it to auto-key edits. Returning true// SUPPRESSES the scene write (reserved for future non-destructive record);// the recorder returns false (observe-only) so the edit still lands normally.// Kept generic: SceneCommands knows nothing about timelines.@@ -302,7 +302,7 @@ export class SceneCommandsImpl {}/**- * Instantiate a prefab into the scene under `parent` (REARCH_PREFABS.md PF2):+ * Instantiate a prefab into the scene under `parent`:* expand the asset into the model as ordinary entities (the Reconciler spawns* them), tagged with their prefab origin so save can collapse the subtree back* to a delta. The caller (ProjectStore / UI) loads the PrefabData asset; this@@ -445,7 +445,7 @@ export class SceneCommandsImpl {}/**- * Paint tiles into a TilemapLayer entity — model-authoritative (REARCH_TILEMAP T3).+ * Paint tiles into a TilemapLayer entity — model-authoritative.** Tile data is a C++-side chunk store the scene carries as the TilemapLayer's* out-of-band `chunks` blob. We apply the edits live to the C++ tilemap (so thediff --git a/desktop/src/engine/SceneLoader.ts b/desktop/src/engine/SceneLoader.tsindex fb3185d8c..1a64dfb05 100644--- a/desktop/src/engine/SceneLoader.ts+++ b/desktop/src/engine/SceneLoader.ts@@ -14,7 +14,7 @@ const UUID_PREFIX = '@uuid:';export const SceneLoader = {/*** Fetch an `.esscene` (SceneData JSON) and load it through the engine's own- * asset system — the ONE asset-resolution path (REARCH_ASSETS.md). A uuid→url+ * asset system — the ONE asset-resolution path. A uuid→url* manifest feeds the ref resolver; `Assets.preloadSceneAssets` loads every* referenced type (not just textures), and a resolved copy builds the World.* The raw scene (with `@uuid:` refs + components/fields the World drops) is@@ -24,7 +24,7 @@ export const SceneLoader = {* URLs); the editor's project transport (estella:// + .meta) lives in* ProjectStore. Both now go through the same engine `Assets` loader.*- * Model-authoritative (REARCH_EDITOR_MODEL.md): SceneModel.adopt emits `reset`;+ * Model-authoritative: SceneModel.adopt emits `reset`;* the Reconciler ignores it (the World is already built here) while SceneStore* bumps and panels re-read from the model.*/diff --git a/desktop/src/engine/SceneModel.ts b/desktop/src/engine/SceneModel.tsindex 96fd57cd7..935f591f8 100644--- a/desktop/src/engine/SceneModel.ts+++ b/desktop/src/engine/SceneModel.ts@@ -25,7 +25,7 @@ export type ModelEvent =type Listener = (ev: ModelEvent) => void;/**- * Marks a model entity as part of a prefab instance (REARCH_PREFABS.md). The+ * Marks a model entity as part of a prefab instance. The* editor expands a prefab instance into ordinary entities; these tags record* each entity's prefab origin so save can collapse the subtree back to a delta.* Editor-transient (never a World component); the Reconciler ignores them.@@ -40,8 +40,8 @@ export interface PrefabInstanceTag {}/**- * The editor's single source of truth — the JSON-first scene document- * (REARCH_EDITOR_MODEL.md). Holds the COMPLETE SceneData: components/fields the+ * The editor's single source of truth — the JSON-first scene document.+ * Holds the COMPLETE SceneData: components/fields the* live World drops on projection (unknown component types, schema-extra fields,* `visible:false` entities) and portable `@uuid:` asset refs, all verbatim.*@@ -302,7 +302,7 @@ export class SceneModelImpl {return out;}- // ── Prefab instances (REARCH_PREFABS.md) ──────────────────────────────────+ // ── Prefab instances ──────────────────────────────────────────────────────/** Tag an entity as part of a prefab instance (or pass undefined to clear). */setPrefabTag(sourceId: number, tag: PrefabInstanceTag | undefined): void {diff --git a/desktop/src/engine/SceneQuery.ts b/desktop/src/engine/SceneQuery.tsindex 4d258df72..4602b99a5 100644--- a/desktop/src/engine/SceneQuery.ts+++ b/desktop/src/engine/SceneQuery.ts@@ -65,8 +65,8 @@ export function buildInspector(data: SceneData | null, id: EntityId): InspectorC}/**- * Read-only projection of the editor's source-of-truth model into view-models- * (REARCH_EDITOR_MODEL.md §3.4). The outliner tree, inspector, and field reads+ * Read-only projection of the editor's source-of-truth model into view-models.+ * The outliner tree, inspector, and field reads* all come from the MODEL — the single truth — never the World. The Viewport* still reads the World for camera-derived screen geometry (pick / gizmo /* selection outline) via ViewportController; that is rendering, the engine'sdiff --git a/desktop/src/engine/SceneStore.ts b/desktop/src/engine/SceneStore.tsindex 6759381f2..bf20ca033 100644--- a/desktop/src/engine/SceneStore.ts+++ b/desktop/src/engine/SceneStore.ts@@ -6,7 +6,7 @@ import { SceneModel, SceneModelImpl, type ModelEvent } from './SceneModel';/*** Reactive mirror of the editor scene — the model-change bus.*- * Model-authoritative data flow (REARCH_EDITOR_MODEL.md): the editor reacts to+ * Model-authoritative data flow: the editor reacts to* **model** events, not engine-pushed World mutations. This subscribes to the* SceneModel and turns each change into a revision bump; panels subscribe via* `useSyncExternalStore` and re-read through SceneQuery (which reads the model).diff --git a/desktop/src/engine/TimelinePreview.ts b/desktop/src/engine/TimelinePreview.tsindex e46b15c32..c387c79b9 100644--- a/desktop/src/engine/TimelinePreview.ts+++ b/desktop/src/engine/TimelinePreview.ts@@ -4,7 +4,7 @@* @file TimelinePreview.ts* @brief Edit-mode live preview of the open timeline document — the document→* World projection that mirrors the scene's Reconciler (model→World),- * for animation (docs/REARCH_ANIMATION.md L4, the P1 payoff).+ * for animation.** Subscribes to {@link TimelineDocument} (asset + preview-root binding) and the* sequencer playhead, and on every change samples the timeline at the playhead anddiff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.tsindex ca95a3d9a..222ab012f 100644--- a/desktop/src/engine/schema.ts+++ b/desktop/src/engine/schema.ts@@ -150,7 +150,7 @@ export function inferField(key: string, v: unknown, isColor: boolean): Inspectorreturn null; // unknown shape — not editable here}-// — User-component schemas (the `schemas.json` consumer; REARCH_EDITOR_MODEL.md) —+// — User-component schemas (the `schemas.json` consumer) —//// Project/script components never run in the editor realm, so they're absent// from the engine registry. Their field shapes come from `.esengine/cache/diff --git a/desktop/src/engine/spineLoad.ts b/desktop/src/engine/spineLoad.tsindex 83f8db96c..139df25c3 100644--- a/desktop/src/engine/spineLoad.ts+++ b/desktop/src/engine/spineLoad.ts@@ -53,7 +53,7 @@ class EditorSpineProvider implements RuntimeAssetProvider {* SpineManager so spine renders in the editor viewport. The World already holds* the SpineAnimation components (loadSceneData ran); this loads the runtime* assets + spawns the per-entity spine instances through the SAME shared loader- * the builder runtime uses (REARCH_SPINE single-impl). No-op when the app has no+ * the builder runtime uses. No-op when the app has no* spine provider/manager or the scene has no spine entities.*/export async function loadEditorSpine(diff --git a/desktop/src/gameHost.ts b/desktop/src/gameHost.tsindex c9dac9a95..05cac30cd 100644--- a/desktop/src/gameHost.ts+++ b/desktop/src/gameHost.ts@@ -1,8 +1,8 @@// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file gameHost.ts — the exported game's runtime host (REARCH_EDITOR_REALM- * Phase S). Bundled by exportGame (esbuild, esengine inlined) into a+ * @file gameHost.ts — the exported game's runtime host.+ * Bundled by exportGame (esbuild, esengine inlined) into a* self-contained game.js. Boots the SAME shipping runtime the editor's* play realm uses (createWebApp → initPlayRealmRuntime), but loads the* scene + asset manifest from the COOKED files next to index.html — so thediff --git a/desktop/src/headless.ts b/desktop/src/headless.tsindex a15fb1a2a..9ce5fec59 100644--- a/desktop/src/headless.ts+++ b/desktop/src/headless.ts@@ -2,8 +2,8 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file headless.ts- * @brief Headless boot entry for the editor's render host- * (docs/REARCH_EDITOR_AUTOMATION.md P1). Loaded by a show:false+ * @brief Headless boot entry for the editor's render host.+ * Loaded by a show:false* Electron window; boots the engine with no React UI and publishes* EditorControlSurface on `window` so a driver — the main process via* executeJavaScript today, the editor MCP server later — can open adiff --git a/desktop/src/panels/Sequencer.tsx b/desktop/src/panels/Sequencer.tsxindex d9333abdf..19425ffd2 100644--- a/desktop/src/panels/Sequencer.tsx+++ b/desktop/src/panels/Sequencer.tsx@@ -2,8 +2,8 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file Sequencer.tsx- * @brief The UE-Sequencer-style animation editor panel (docs/REARCH_ANIMATION.md- * L4) — bottom-dock tab. P1 skeleton: open a clip, render the+ * @brief The UE-Sequencer-style animation editor panel — bottom-dock tab.+ * Open a clip, render the* entity→component→channel track tree + a scrubbable frame timeline.** Data flow mirrors the scene panels: subscribe to the TimelineDocument revisiondiff --git a/desktop/src/panels/SequencerCurve.tsx b/desktop/src/panels/SequencerCurve.tsxindex 2f09a5eb1..b6e38f116 100644--- a/desktop/src/panels/SequencerCurve.tsx+++ b/desktop/src/panels/SequencerCurve.tsx@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file SequencerCurve.tsx- * @brief Curve editor view for the Sequencer (docs/REARCH_ANIMATION.md P3).+ * @brief Curve editor view for the Sequencer.** Best-architecture point: the curves are drawn by sampling the SAME runtime* evaluator (`evaluateChannel`) the playback/preview uses — so the displayed curvediff --git a/desktop/src/panels/TilemapPainter.tsx b/desktop/src/panels/TilemapPainter.tsxindex 54099c471..319b2d31a 100644--- a/desktop/src/panels/TilemapPainter.tsx+++ b/desktop/src/panels/TilemapPainter.tsx@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file TilemapPainter.tsx- * @brief The Tilemap painter panel (REARCH_TILEMAP T3b) — the brush palette + tools+ * @brief The Tilemap painter panel — the brush palette + tools* for painting a selected scene `TilemapLayer` entity. Painting itself happens* in the Viewport (this panel drives the active tool + brush via the paint* store); the palette is the entity's referenced `.estileset` atlas.diff --git a/desktop/src/panels/TilesetEditor.tsx b/desktop/src/panels/TilesetEditor.tsxindex b37aec2ea..360e6ef0b 100644--- a/desktop/src/panels/TilesetEditor.tsx+++ b/desktop/src/panels/TilesetEditor.tsx@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file TilesetEditor.tsx- * @brief The .estileset editor panel (docs/REARCH_TILEMAP.md T2) — the tileset's+ * @brief The .estileset editor panel — the tileset's* atlas with a grid overlay; click/drag tiles to toggle box collision (the* collision authority every tilemap derives from). Subscribes to the reactive* TilesetDocument; mutations go through TilesetCommands (one undo step each).diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.tsindex 4f2a6bda4..d1f53923a 100644--- a/desktop/src/playHost.ts+++ b/desktop/src/playHost.ts@@ -1,8 +1,8 @@// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file playHost.ts — the isolated play realm's host module (REARCH_EDITOR_REALM- * import-map phase). Unlike the R1 Vite `play.ts` (which bundles its own+ * @file playHost.ts — the isolated play realm's host module.+ * Unlike the Vite `play.ts` (which bundles its own* esengine), this is esbuilt with **esengine EXTERNAL** and runs from the* project's `estella://` origin under `.esengine/play/host.js`. A* `<script type=importmap>` in play.html maps `esengine` → `./sdk/index.js`,diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.tsindex 8880d4d35..f274699c7 100644--- a/desktop/src/project/ProjectStore.ts+++ b/desktop/src/project/ProjectStore.ts@@ -21,7 +21,7 @@ import { resolveLayout, WORKSPACE_DIR, PROJECT_MANIFEST_FILE, type OpenedProject* directory, loads its scene into the live engine World via `resetWorldTo`, and* saves back. The bridge sandboxes every fs path to the open project root.*- * Assets resolve through the engine's own asset system (REARCH_ASSETS.md A1):+ * Assets resolve through the engine's own asset system:* the editor builds a uuid→path registry from `.meta` sidecars, points the* engine `Assets` loader at the `estella://` transport (electron/main serves* project files), and preloads EVERY referenced asset type — not just textures.@@ -201,7 +201,7 @@ class ProjectStoreImpl {await this.buildAssetRegistry();// Expand prefab-instance entries into ordinary tagged entities (the model is- // always expanded; the file stores deltas) — REARCH_PREFABS.md. Internal+ // always expanded; the file stores deltas). Internal// entities get fresh ids above the file's max so they don't collide.let nextId = raw.entities.reduce((m, e) => Math.max(m, (e as { id?: number }).id ?? 0), 0) + 1;const { scene: expandedRaw, tags } = await expandScenePrefabs(@@ -223,7 +223,7 @@ class ProjectStoreImpl {// A scene is a session document: replacing it clears the editor history +// selection so undo closures can't reference the previous scene's entities- // (REARCH_EDITOR_MODEL.md §6). The Reconciler bulk path then builds the World+ // selection. The Reconciler bulk path then builds the World// from the resolved scene and adopts the raw scene (with @uuid: refs + any// components/fields/invisible entities the World drops) as the source of// truth. The World is a lossy projection; the model is what save() serializes.@@ -238,7 +238,7 @@ class ProjectStoreImpl {// Bind spine entities' skeletons/atlas/textures into the SpineManager so spine// renders in the viewport (the World holds the SpineAnimation components, but- // spine assets load separately from Assets — REARCH_SPINE side modules). The+ // spine assets load separately from Assets via side modules). The// entityMap is the Reconciler's source→runtime binding; refs resolve through// the project's estella:// transport.const spineMap = new Map<number, number>();@@ -299,8 +299,8 @@ class ProjectStoreImpl {}/**- * Load the project's asset index (the main-process AssetDatabase scan,- * REARCH_ASSETS.md A2) into a uuid→path registry, then point the engine+ * Load the project's asset index (the main-process AssetDatabase scan)+ * into a uuid→path registry, then point the engine* `Assets` loader at it + the `estella://` transport. This is the ONE* asset-resolution path: `Assets.resolveRef` turns `@uuid:` → path, the backend* fetches `estella://project/<path>`.@@ -449,7 +449,7 @@ class ProjectStoreImpl {}/**- * Assemble the isolated play-realm payload (REARCH_EDITOR_REALM Phase R): the+ * Assemble the isolated play-realm payload: the* current scene as RAW (`@uuid:`) SceneData straight from the expanded model —* the runtime needs no prefab expansion and handles are realm-local, so we send* the lossless refs, not resolved handles — plus a uuid→url manifest the realm@@ -535,9 +535,9 @@ class ProjectStoreImpl {}/**- * Serialize the editor's source-of-truth model — lossless (JSON-first L4) ++ * Serialize the editor's source-of-truth model — lossless (JSON-first) +* prefab-aware: collapse each expanded prefab-instance subtree back to a single- * `{prefab, overrides, added, removed}` delta entry (REARCH_PREFABS.md). The+ * `{prefab, overrides, added, removed}` delta entry. The* model retains everything the World drops (unknown components/fields, invisible* entities, `@uuid:` asset refs), so this reads only the model.*/diff --git a/desktop/src/project/format.ts b/desktop/src/project/format.tsindex dcf9becf7..767ae5502 100644--- a/desktop/src/project/format.ts+++ b/desktop/src/project/format.ts@@ -43,7 +43,7 @@ export interface DesignResolution {}/**- * Script entry points (REARCH_EDITOR_REALM §E8 / P3). Splitting declaration from+ * Script entry points. Splitting declaration from* startup is what lets the editor extract a component schema WITHOUT executing* project startup: schema extraction imports ONLY `register`, the play-realm* bundle is built from `main`. Both default (see {@link DEFAULT_SCRIPTS}) so mostdiff --git a/desktop/src/project/fsWatch.ts b/desktop/src/project/fsWatch.tsindex a3f4312fa..60e128bcf 100644--- a/desktop/src/project/fsWatch.ts+++ b/desktop/src/project/fsWatch.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file Live filesystem ↔ editor-asset sync (REARCH_ASSETS A2, renderer side).+ * @file Live filesystem ↔ editor-asset sync (renderer side).** `fsRefresh` is a bump signal every `useDir` subscribes to (re-read directories).* `initFsWatch` subscribes ONCE to the main-process watcher so changes on disk —diff --git a/desktop/src/store/selectionStore.ts b/desktop/src/store/selectionStore.tsindex 2f131a08f..6364d2018 100644--- a/desktop/src/store/selectionStore.ts+++ b/desktop/src/store/selectionStore.ts@@ -5,7 +5,7 @@ import { SceneModel, SceneModelImpl } from '@/engine/SceneModel';import type { EntityId } from '@/types';/**- * Entity selection — model-anchored (REARCH_EDITOR_MODEL.md).+ * Entity selection — model-anchored.** Selection holds stable **source ids** (they survive undo/redo recreates, where* the runtime World id changes). A selected entity can still be removed out fromdiff --git a/desktop/src/store/sequencerStore.ts b/desktop/src/store/sequencerStore.tsindex c32d17b47..40a9f9a88 100644--- a/desktop/src/store/sequencerStore.ts+++ b/desktop/src/store/sequencerStore.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { create } from 'zustand';-// Sequencer UI + playback state (docs/REARCH_ANIMATION.md L4). Kept separate from+// Sequencer UI + playback state. Kept separate from// editorStore (scene-level UI) and the TimelineDocument (the asset data) — this is// the transient view state: playhead, transport flags, track-tree collapse,// keyframe selection. The playhead `time` is in SECONDS (the asset's unit); thediff --git a/desktop/src/store/tilemapPaintStore.ts b/desktop/src/store/tilemapPaintStore.tsindex 92b25c76c..5ad58a197 100644--- a/desktop/src/store/tilemapPaintStore.ts+++ b/desktop/src/store/tilemapPaintStore.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file tilemapPaintStore.ts- * @brief Transient tilemap-painting state (REARCH_TILEMAP T3b): the active tileset+ * @brief Transient tilemap-painting state: the active tileset* palette, the selected brush tile, and the active paint tool. When a tool is* set AND a TilemapLayer entity is selected, the Viewport paints instead of* selecting. Editor-session state — never serialized.diff --git a/desktop/src/tilemap/createTilemap.ts b/desktop/src/tilemap/createTilemap.tsindex 948067db6..7ca6bf013 100644--- a/desktop/src/tilemap/createTilemap.ts+++ b/desktop/src/tilemap/createTilemap.ts@@ -2,8 +2,8 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file createTilemap.ts- * @brief Spawn a scene-embedded TilemapLayer entity from an .estileset- * (REARCH_TILEMAP T3b) — the Unity/Godot model: the tilemap is a real,+ * @brief Spawn a scene-embedded TilemapLayer entity from an .estileset —+ * the Unity/Godot model: the tilemap is a real,* paintable entity, the tileset is the reusable asset it references.*/diff --git a/desktop/src/tileset/TilesetCommands.ts b/desktop/src/tileset/TilesetCommands.tsindex 7f113b1cb..955e535c8 100644--- a/desktop/src/tileset/TilesetCommands.ts+++ b/desktop/src/tileset/TilesetCommands.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file TilesetCommands.ts- * @brief Undoable mutations on the open .estileset (docs/REARCH_TILEMAP.md T2).+ * @brief Undoable mutations on the open .estileset.* Each routes through TilesetDocument.edit → one EditorHistory snapshot step;* the panel never mutates the asset directly.*/diff --git a/desktop/src/tileset/TilesetDocument.ts b/desktop/src/tileset/TilesetDocument.tsindex 0a8e8d0ba..6008b92af 100644--- a/desktop/src/tileset/TilesetDocument.ts+++ b/desktop/src/tileset/TilesetDocument.ts@@ -4,7 +4,7 @@* @file TilesetDocument.ts* @brief The open .estileset as a reactive editor document — the second* {@link AssetDocument} (after the Sequencer's TimelineDocument), and the- * rule-of-three that confirmed the base is generic (docs/REARCH_TILEMAP.md T2).+ * rule-of-three that confirmed the base is generic.** A tileset is a pure asset (unlike a timeline it binds to no scene entity), so this* subclass adds almost nothing over the generic reactive + snapshot-undo core — justdiff --git a/desktop/src/tileset/openTileset.ts b/desktop/src/tileset/openTileset.tsindex fceb4e734..74ad8611c 100644--- a/desktop/src/tileset/openTileset.ts+++ b/desktop/src/tileset/openTileset.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file openTileset.ts- * @brief Open / create a .estileset from the Content Browser (docs/REARCH_TILEMAP.md T2).+ * @brief Open / create a .estileset from the Content Browser.* Mirrors openClip.ts (open) and ProjectStore.createPrefabFromEntity (create + .meta* + registry re-scan).*/diff --git a/desktop/src/timeline/TimelineCommands.ts b/desktop/src/timeline/TimelineCommands.tsindex cc4fa0914..080d56284 100644--- a/desktop/src/timeline/TimelineCommands.ts+++ b/desktop/src/timeline/TimelineCommands.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file TimelineCommands.ts- * @brief Undoable edits to the open timeline document (docs/REARCH_ANIMATION.md P2).+ * @brief Undoable edits to the open timeline document.** Mirrors the scene's SceneCommands: a command mutates the document's asset and* registers one undo step on the shared {@link EditorHistory} (so timeline editsdiff --git a/desktop/src/timeline/TimelineDocument.ts b/desktop/src/timeline/TimelineDocument.tsindex f034ad908..ec76c74ec 100644--- a/desktop/src/timeline/TimelineDocument.ts+++ b/desktop/src/timeline/TimelineDocument.ts@@ -3,7 +3,7 @@/*** @file TimelineDocument.ts* @brief The open .estimeline as a reactive editor document — the first- * {@link AssetDocument} (docs/REARCH_ANIMATION.md L4 / P5).+ * {@link AssetDocument}.** The generic reactive + snapshot-undo core lives in AssetDocument; this adds the* timeline-specific state: `fps` (editor display metadata — the asset stores timediff --git a/desktop/src/timeline/TimelineRecorder.ts b/desktop/src/timeline/TimelineRecorder.tsindex 62ff8b4fb..cd17454d6 100644--- a/desktop/src/timeline/TimelineRecorder.ts+++ b/desktop/src/timeline/TimelineRecorder.ts@@ -2,8 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file TimelineRecorder.ts- * @brief Record mode — auto-key inspector/gizmo edits into the open clip- * (docs/REARCH_ANIMATION.md P2).+ * @brief Record mode — auto-key inspector/gizmo edits into the open clip.** Registers a generic edit hook on SceneCommands (the single field-edit door): when* recording is on and the edited entity is the clip's bound preview root, it dropsdiff --git a/desktop/src/timeline/openClip.ts b/desktop/src/timeline/openClip.tsindex 6bd4674de..31e15ed50 100644--- a/desktop/src/timeline/openClip.ts+++ b/desktop/src/timeline/openClip.ts@@ -3,7 +3,7 @@/*** @file openClip.ts* @brief Open an animation clip (.esanim / legacy .estimeline) from disk into- * the Sequencer (docs/REARCH_ANIMATION.md P2).+ * the Sequencer.** Reads the project file, parses it through the unified clip loader (rich* multi-track or legacy flipbook), opens it as the editor TimelineDocument bounddiff --git a/desktop/src/timeline/timelineView.ts b/desktop/src/timeline/timelineView.tsindex 873789c49..d29e5809e 100644--- a/desktop/src/timeline/timelineView.ts+++ b/desktop/src/timeline/timelineView.ts@@ -4,7 +4,7 @@* @file timelineView.ts* @brief Read projection for the Sequencer panel — derive a renderable* entity→component→channel row tree (and keyframe times) from the flat- * TimelineAsset. The seed of TimelineQuery (docs/REARCH_ANIMATION.md L4).+ * TimelineAsset. The seed of TimelineQuery.** The asset stores tracks flat (each carries childPath + component + channels);* the UI shows them as the design's nested tree (Player → Transform → 位置/…),diff --git a/sdk/src/app.ts b/sdk/src/app.tsindex 5527d9ce2..1c1d52606 100644--- a/sdk/src/app.ts+++ b/sdk/src/app.ts@@ -585,8 +585,8 @@ export class App {this.pipeline_ = null;this.runner_ = null;- // Tear down the C++ engine context too (REARCH_ENGINE_INSTANCING N3/N4,- // closes I3): previously quit() only cleared JS state and dropped the+ // Tear down the C++ engine context too: previously quit() only cleared+ // JS state and dropped the// module reference, so the EstellaContext was never shut down — it// leaked its GPU subsystems + WebGL context, and a later init silently// reused the stale (still-"initialized") singleton. shutdownRenderer isdiff --git a/sdk/src/camera/CameraDirector.ts b/sdk/src/camera/CameraDirector.tsindex 0420be7e6..0a249db0f 100644--- a/sdk/src/camera/CameraDirector.ts+++ b/sdk/src/camera/CameraDirector.ts@@ -27,8 +27,7 @@ export type BlendCurve = (typeof BlendCurve)[keyof typeof BlendCurve];export function applyCurve(curve: number, t: number): number {const x = t < 0 ? 0 : t > 1 ? 1 : t;// BlendCurve 0..3 aligns with Easing's Linear/EaseInQuad/EaseOutQuad/EaseInOutQuad- // (identical formulas) — delegate so the easing math lives in one place- // (docs/REARCH_ANIMATION.md easing consolidation).+ // (identical formulas) — delegate so the easing math lives in one place.return applyEasing(curve as EasingType, x);}diff --git a/sdk/src/component.ts b/sdk/src/component.tsindex 77aff9754..94630e0b2 100644--- a/sdk/src/component.ts+++ b/sdk/src/component.ts@@ -30,7 +30,7 @@ export interface ComponentMetadata {/*** Runtime-only state that must never persist: a transient component is* skipped by {@link serializeScene} (e.g. per-frame pointer/drag/hover state- * that its driving system rebuilds each frame, REARCH_GUI F2). Systems still+ * that its driving system rebuilds each frame). Systems still* read/write it normally; only scene save omits it.*/transient?: boolean;@@ -295,7 +295,7 @@ export function defineBuiltin<T>(name: string, defaults: T, metadata?: ComponentdiscoverAssets: metadata?.discoverAssets,// Builtins declare transience via the defineBuiltin metadata arg for now;// a C++-side ES_COMPONENT(transient) annotation can flow through- // COMPONENT_META later (REARCH_GUI F6) without touching call sites.+ // COMPONENT_META later without touching call sites.transient: metadata?.transient ?? false,};builtinRegistry.set(name, def);diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.tsindex 5265d6c3f..fafbd7ec6 100644--- a/sdk/src/core-ui.ts+++ b/sdk/src/core-ui.ts@@ -87,7 +87,7 @@ export {colorWithAlpha,/** @internal per-entity state map used by interaction behaviour */EntityStateMap,- // Theme design tokens (REARCH_GUI F7)+ // Theme design tokensDARK_TOKENS,getTheme,setTheme,diff --git a/sdk/src/runtimeAssets.ts b/sdk/src/runtimeAssets.tsindex 6fa4ae877..92ce3a6ca 100644--- a/sdk/src/runtimeAssets.ts+++ b/sdk/src/runtimeAssets.ts@@ -51,7 +51,7 @@ export function createTextureFromPixels(/*** Upload pixels into a sub-rectangle of an existing texture. Lets the dynamic- * glyph atlas (REARCH_GUI P1) pack glyphs individually instead of re-uploading+ * glyph atlas pack glyphs individually instead of re-uploading* the whole atlas. `pixels` must match the texture's format (RGBA8) and the* rect must lie inside the texture (the engine bounds-checks and no-ops if not).*/diff --git a/sdk/src/scene.ts b/sdk/src/scene.tsindex 83a1ab7e5..e325f6e74 100644--- a/sdk/src/scene.ts+++ b/sdk/src/scene.ts@@ -192,7 +192,7 @@ export function registerSceneComponentCodec(type: string, codec: SceneComponentC}// =============================================================================-// Prefab instance entries (REARCH_PREFABS PF1 — runtime play == ship)+// Prefab instance entries (runtime play == ship)// =============================================================================// A scene-file entity is either an ordinary entity record or a prefab-instancediff --git a/sdk/src/tilemap/chunkCodec.ts b/sdk/src/tilemap/chunkCodec.tsindex 2731bd88c..255d368ea 100644--- a/sdk/src/tilemap/chunkCodec.ts+++ b/sdk/src/tilemap/chunkCodec.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file chunkCodec.ts- * @brief Decode the `tilemap_exportChunks` blob (REARCH_TILEMAP T4) so the SDK can+ * @brief Decode the `tilemap_exportChunks` blob so the SDK can* read painted tiles back — used to derive runtime collision from a tilemap's* collidable tiles. Format (little-endian, base64url):* u32 magic 'ESTM' · u32 chunkCount · per chunk: i32 x, i32 y, u16 tiles[256]diff --git a/sdk/src/tilemap/tiledLoader.ts b/sdk/src/tilemap/tiledLoader.tsindex e74ba29dd..a244d7894 100644--- a/sdk/src/tilemap/tiledLoader.ts+++ b/sdk/src/tilemap/tiledLoader.ts@@ -608,7 +608,7 @@ export function generateTileCollision(/*** @brief Build static box colliders for an INFINITE (chunked) tilemap layer from its- * collidable tiles — the native scene-`TilemapLayer` path (REARCH_TILEMAP T4).+ * collidable tiles — the native scene-`TilemapLayer` path.** Each chunk's collidable tiles are greedy-merged independently (no cross-chunk merge); a* merged rect (x0,y0)-(x1,y1) maps to a world AABB by the SAME orthogonal conventiondiff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.tsindex 7fea14102..8de1d5960 100644--- a/sdk/src/tilemap/tilemapPlugin.ts+++ b/sdk/src/tilemap/tilemapPlugin.ts@@ -283,8 +283,8 @@ export class TilemapPlugin implements Plugin {const oy = tf?.position.y ?? 0;const spawned: Entity[] = [];for (const layer of cached.layers) {- // T1 covers finite layers (flat tile arrays); infinite/chunk- // collision is deferred (see docs/REARCH_TILEMAP.md).+ // Collision covers finite layers (flat tile arrays);+ // infinite/chunk collision is deferred.if (layer.infinite || layer.tiles.length === 0) continue;spawned.push(...generateLayerCollision(world, layer.tiles, layer.width, layer.height,diff --git a/sdk/src/tilemap/tilesetAsset.ts b/sdk/src/tilemap/tilesetAsset.tsindex 0ecb20aa1..2510a3649 100644--- a/sdk/src/tilemap/tilesetAsset.ts+++ b/sdk/src/tilemap/tilesetAsset.ts@@ -2,8 +2,8 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file tilesetAsset.ts- * @brief The `.estileset` tileset-palette asset — atlas slicing + per-tile behaviour- * (docs/REARCH_TILEMAP.md). The reusable asset the Tileset editor authors and the+ * @brief The `.estileset` tileset-palette asset — atlas slicing + per-tile behaviour.+ * The reusable asset the Tileset editor authors and the* single source of truth for how a tile looks (atlas grid) AND behaves (collision* shape / animation / properties). Tilemaps reference it; collision is derived from* it at runtime, so editing the tileset updates every map.diff --git a/sdk/src/timeline/AnimationClip.ts b/sdk/src/timeline/AnimationClip.tsindex bebb5ae88..b167d0f05 100644--- a/sdk/src/timeline/AnimationClip.ts+++ b/sdk/src/timeline/AnimationClip.ts@@ -3,7 +3,7 @@/*** @file AnimationClip.ts* @brief The unified animation-clip loader — one .esanim document the Sequencer- * authors and the Animator state-machine references (docs/REARCH_ANIMATION.md).+ * authors and the Animator state-machine references.** The editor unified two formats into `.esanim`: the rich multi-track model* (property curves + sprite frames + events + …) and the legacy sprite-flipbookdiff --git a/sdk/src/timeline/TimelineControl.ts b/sdk/src/timeline/TimelineControl.tsindex b2b4b6d7c..33f0542c0 100644--- a/sdk/src/timeline/TimelineControl.ts+++ b/sdk/src/timeline/TimelineControl.ts@@ -10,7 +10,7 @@ import { WrapMode } from './TimelineTypes';* and is published as the {@link Timeline} resource; game code drives playback via* `app.getResource(Timeline)`.*- * The timeline runtime is pure TS now (docs/REARCH_ANIMATION.md P4c) — there is no+ * The timeline runtime is pure TS now — there is no* C++ handle or wasm module here. `TimelinePlugin` advances each entity's* {@link TimelineState} every frame; these methods just flip/seek that state.*/diff --git a/sdk/src/timeline/TimelineDrive.ts b/sdk/src/timeline/TimelineDrive.tsindex b32bf1538..a2644fee4 100644--- a/sdk/src/timeline/TimelineDrive.ts+++ b/sdk/src/timeline/TimelineDrive.ts@@ -3,7 +3,7 @@/*** @file TimelineDrive.ts* @brief Pure-TS per-frame timeline runtime — the replacement for the C++- * TimelineSystem::advance (docs/REARCH_ANIMATION.md P4c).+ * TimelineSystem::advance.** Holds a per-entity playback clock and, each frame: advances time (speed + wrap),* samples property tracks (via the shared evaluator), and edge-detects event-trackdiff --git a/sdk/src/timeline/TimelineEvaluator.ts b/sdk/src/timeline/TimelineEvaluator.tsindex 4bcea48dc..66b125fee 100644--- a/sdk/src/timeline/TimelineEvaluator.ts+++ b/sdk/src/timeline/TimelineEvaluator.ts@@ -5,8 +5,8 @@* @brief Pure-TS timeline sampler — evaluate a TimelineAsset at an absolute* time and apply its property tracks to the world.*- * The engine's C++ TimelineSystem is a temporary implementation (see- * docs/REARCH_ANIMATION.md). This is the modern replacement's kernel: ONE+ * The engine's C++ TimelineSystem is a temporary implementation. This is the+ * modern replacement's kernel: ONE* sample(time) call drives both forward playback (advance the clock, then sample)* and editor scrubbing (sample at any T) — so the editor gets "scrub ==* evaluate-at-T" for free, with no separate evaluate/apply paths.@@ -110,7 +110,7 @@ export function applyWrapMode(}// ----------------------------------------------------------------------------// Field application — seed of the REARCH_ANIMATION L1 reflection writer table+// Field application — the reflection writer table// ---------------------------------------------------------------------------type FieldWriter = (data: any, value: number) => void;diff --git a/sdk/src/timeline/TimelinePlugin.ts b/sdk/src/timeline/TimelinePlugin.tsindex 19bb52b5f..dc112d703 100644--- a/sdk/src/timeline/TimelinePlugin.ts+++ b/sdk/src/timeline/TimelinePlugin.ts@@ -94,7 +94,7 @@ export class TimelinePlugin implements Plugin {this.animFramesStates_.delete(entity);});- // The timeline runs entirely in TS (REARCH_ANIMATION P4c): a per-entity+ // The timeline runs entirely in TS: a per-entity// clock + the shared evaluator (property tracks) + edge-detected event// dispatch — no wasm timeline, no upload, no per-frame poll. Property writes// land via world.set (the same path the editor preview uses).diff --git a/sdk/src/timeline/TimelineRuntime.ts b/sdk/src/timeline/TimelineRuntime.tsindex 77b20cbf6..8c68c7529 100644--- a/sdk/src/timeline/TimelineRuntime.ts+++ b/sdk/src/timeline/TimelineRuntime.ts@@ -6,7 +6,7 @@ import type { AudioAPI } from '../audio/Audio';import type { Entity } from '../types';/**- * Shared timeline runtime helpers (docs/REARCH_ANIMATION.md). The timeline is a+ * Shared timeline runtime helpers. The timeline is a* pure-TS runtime now (see TimelineDrive); this module holds the pieces shared by* the drive and the editor: child-entity resolution, nested-path writes, and the* event dispatcher.diff --git a/sdk/src/timeline/TimelineSerializer.ts b/sdk/src/timeline/TimelineSerializer.tsindex 5d4961a81..0d185889b 100644--- a/sdk/src/timeline/TimelineSerializer.ts+++ b/sdk/src/timeline/TimelineSerializer.ts@@ -5,8 +5,8 @@* @brief Serialize an in-memory TimelineAsset back to .estimeline JSON — the* inverse of TimelineLoader.parseTimelineAsset.*- * The runtime previously only LOADED timelines; authoring (the Sequencer editor,- * docs/REARCH_ANIMATION.md) needs to write them back. Field names and the wrapMode+ * The runtime previously only LOADED timelines; authoring (the Sequencer editor)+ * needs to write them back. Field names and the wrapMode* string encoding mirror the loader exactly so parse(serialize(x)) round-trips —* notably AnimFrames tracks persist under the on-disk key `animFrames` (the loader* reads `raw.animFrames` into the in-memory `frames`).diff --git a/sdk/src/ui/SafeArea.ts b/sdk/src/ui/SafeArea.tsindex b5ab82bd0..07a9f3403 100644--- a/sdk/src/ui/SafeArea.ts+++ b/sdk/src/ui/SafeArea.ts@@ -3,7 +3,7 @@/*** @file ui/SafeArea.ts* @brief Back-compat shim — the SafeArea component moved into the layout- * concept module (REARCH_GUI P0). Re-exported here to keep the- * public symbol + existing imports stable until REARCH_GUI P4.+ * concept module. Re-exported here to keep the public symbol ++ * existing imports stable.*/export { SafeArea, type SafeAreaData } from './layout/safe-area';diff --git a/sdk/src/ui/TextInputPlugin.ts b/sdk/src/ui/TextInputPlugin.tsindex 888c9ecbd..81796be3c 100644--- a/sdk/src/ui/TextInputPlugin.ts+++ b/sdk/src/ui/TextInputPlugin.ts@@ -54,7 +54,7 @@ export class TextInputPlugin implements Plugin {const world = app.world;- // REARCH_GUI F8: the editable text renders through the shared SDF glyph+ // The editable text renders through the shared SDF glyph// atlas — a child Text entity (drawn by textPlugin) + a child UIVisual// caret quad, composited over the entity's background UIVisual. No more// per-entity Canvas2D rasterization / texture upload. `measureRenderer`@@ -256,7 +256,7 @@ export class TextInputPlugin implements Plugin {// Render system — composite the input from SDF child entities (a child// Text drawn by textPlugin + a child caret quad) over the entity's// background UIVisual. Tree-DFS render order layers bg < text < caret. No- // Canvas2D, no per-entity texture (REARCH_GUI F8).+ // Canvas2D, no per-entity texture.app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([],() => {diff --git a/sdk/src/ui/behavior/draggable.ts b/sdk/src/ui/behavior/draggable.tsindex 2accb369c..4d940c62e 100644--- a/sdk/src/ui/behavior/draggable.ts+++ b/sdk/src/ui/behavior/draggable.ts@@ -3,8 +3,7 @@/*** @file ui/behavior/draggable.ts* @brief Back-compat shim — Draggable/DragState moved to the input concept- * module (REARCH_GUI P0). Re-exported here to keep existing imports- * stable until REARCH_GUI P4.+ * module. Re-exported here to keep existing imports stable.*/export {Draggable,diff --git a/sdk/src/ui/behavior/focusable.ts b/sdk/src/ui/behavior/focusable.tsindex f5794ff63..f55239484 100644--- a/sdk/src/ui/behavior/focusable.ts+++ b/sdk/src/ui/behavior/focusable.ts@@ -3,8 +3,7 @@/*** @file ui/behavior/focusable.ts* @brief Back-compat shim — Focusable/FocusManager moved to the input concept- * module (REARCH_GUI P0). Re-exported here to keep existing imports- * stable until REARCH_GUI P4.+ * module. Re-exported here to keep existing imports stable.*/export {Focusable,diff --git a/sdk/src/ui/behavior/interactable.ts b/sdk/src/ui/behavior/interactable.tsindex a95db2094..c53ff88e9 100644--- a/sdk/src/ui/behavior/interactable.ts+++ b/sdk/src/ui/behavior/interactable.ts@@ -3,8 +3,7 @@/*** @file ui/behavior/interactable.ts* @brief Back-compat shim — Interactable/UIInteraction moved to the input- * concept module (REARCH_GUI P0). Re-exported here to keep existing- * imports stable until REARCH_GUI P4.+ * concept module. Re-exported here to keep existing imports stable.*/export {Interactable,diff --git a/sdk/src/ui/behavior/state-visuals.ts b/sdk/src/ui/behavior/state-visuals.tsindex 7e4330ae4..cd6204bc5 100644--- a/sdk/src/ui/behavior/state-visuals.ts+++ b/sdk/src/ui/behavior/state-visuals.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/behavior/state-visuals.ts- * @brief StateVisuals — named state → visual overrides (REARCH_GUI F5).+ * @brief StateVisuals — named state → visual overrides.** A variable-length `states` list replaced the old 8 hardcoded `slotN*` field* quartets + stringly-keyed reflection. The apply system reads the entity'sdiff --git a/sdk/src/ui/core/dimension.ts b/sdk/src/ui/core/dimension.tsindex 601485ccf..b44c6c265 100644--- a/sdk/src/ui/core/dimension.ts+++ b/sdk/src/ui/core/dimension.ts@@ -3,7 +3,7 @@/*** @file ui/core/dimension.ts* @brief Dimension — a CSS-style length (value + unit) for the runtime UI box- * model (REARCH_GUI F2, see docs/REARCH_GUI.md).+ * model.** One field can be pixels, a percentage of the parent, or content-driven (auto),* replacing the old size/offset/`-1`-sentinel scheme. The on-wire shape matchesdiff --git a/sdk/src/ui/core/ui-node.ts b/sdk/src/ui/core/ui-node.tsindex b3155c1b3..ac0a7fca0 100644--- a/sdk/src/ui/core/ui-node.ts+++ b/sdk/src/ui/core/ui-node.ts@@ -2,13 +2,13 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/core/ui-node.ts- * @brief UINode — the CSS box-model layout primitive (REARCH_GUI F3).+ * @brief UINode — the CSS box-model layout primitive.** The primary way to author UI geometry: every size is a {@link Dimension}* (px / percent / auto) fed straight into the single-pass Yoga solver, replacing* the RectTransform anchor/offset/pivot model. The per-item flex properties* (grow/shrink/basis/alignSelf/margin/min-max) live here — the standalone- * FlexItem component was subsumed by UINode and removed (REARCH_GUI F4).+ * FlexItem component was subsumed by UINode and removed.* Container properties stay on {@link FlexContainer}. Mirrors the C++ `UINode`* builtin; `computed_size_` is C++-internal (not serialized). Construct lengths* with `px()/percent()/auto()`.diff --git a/sdk/src/ui/core/ui-visual.ts b/sdk/src/ui/core/ui-visual.tsindex 724f3d85b..c0130cb78 100644--- a/sdk/src/ui/core/ui-visual.ts+++ b/sdk/src/ui/core/ui-visual.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/core/ui-visual.ts- * @brief UIVisual — the single UI visual component (REARCH_GUI F4).+ * @brief UIVisual — the single UI visual component.** Merges the former low-level `UIRenderer` (what the renderer drew) and the* high-level `Image` (Simple/Sliced/Tiled/Filled intent that used to be copieddiff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex f769ec78c..ff2e1cbd1 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -232,7 +232,7 @@ export {// ─── Rendering / text helpers ───────────────────────────────────────────────// All text — display (Text) and editable (TextInput) — now renders through the-// SDF glyph atlas; the Canvas2D TextRenderer was retired in REARCH_GUI F8.+// SDF glyph atlas; the Canvas2D TextRenderer was retired.export { TextPlugin, textPlugin } from './text/plugin';// UI Math Utilities@@ -250,7 +250,7 @@ export {// ─── Plugins (composed UI pipeline + the concept plugins it builds) ─────────-// REARCH_GUI F6: `uiPlugin` is the single declarative UI pipeline. The concept+// `uiPlugin` is the single declarative UI pipeline. The concept// plugins below remain exported for granular/advanced wiring.export { UIPlugin, uiPlugin } from './ui-plugin';@@ -340,7 +340,7 @@ export {type ResolvedImage,} from './ImageResolver';-// ─── SDF glyph-atlas text (REARCH_GUI P1) ───────────────────────────────────+// ─── SDF glyph-atlas text ───────────────────────────────────────────────────export {UI_TEXT_BOLD,diff --git a/sdk/src/ui/layout/flex.ts b/sdk/src/ui/layout/flex.tsindex 7dea49ec0..5f7d99ce1 100644--- a/sdk/src/ui/layout/flex.ts+++ b/sdk/src/ui/layout/flex.ts@@ -42,5 +42,5 @@ export const FlexContainer = defineBuiltin<FlexContainerData>('FlexContainer', {});// Per-item flex properties (grow/shrink/basis/alignSelf/margin/min-max) live on-// UINode now; the standalone FlexItem component was removed in REARCH_GUI F4.+// UINode now; the standalone FlexItem component was removed.// `AlignSelf` moved to ui/core/ui-node.ts alongside the other item properties.diff --git a/sdk/src/ui/layout/layout.ts b/sdk/src/ui/layout/layout.tsindex ebc90306f..0e1f36252 100644--- a/sdk/src/ui/layout/layout.ts+++ b/sdk/src/ui/layout/layout.ts@@ -7,11 +7,11 @@* Owns the PreUpdate `UILayoutSystem` (drives the C++ Yoga pass via* `uiLayout_update` + `transform_update`) plus the PostUpdate late/final* passes that re-solve after scroll/list mutations. Co-located with the- * `flex`/`grid`/`safe-area` schemas in this module (REARCH_GUI P0).+ * `flex`/`grid`/`safe-area` schemas in this module.** Behaviour is byte-identical to the former flat `UILayoutPlugin.ts`, which* now re-exports from here (strangler-fig; legacy public symbols kept as- * shims until REARCH_GUI P4).+ * shims).*/import type { App, Plugin } from '../../app';import { registerComponent } from '../../component';diff --git a/sdk/src/ui/layout/safe-area.ts b/sdk/src/ui/layout/safe-area.tsindex ecf7408e7..e2fe8a439 100644--- a/sdk/src/ui/layout/safe-area.ts+++ b/sdk/src/ui/layout/safe-area.ts@@ -5,11 +5,11 @@* @brief Safe-area concept — component + the PreUpdate system that pushes* platform safe-area insets into UINode insets, co-located.*- * Part of REARCH_GUI P0: the layout concept (Yoga driver + safe-area) is the- * first concept relocated out of the flat legacy plugins into a cohesive- * module. Behaviour is byte-identical to the former `SafeArea.ts` +- * `SafeAreaPlugin.ts`; those files now re-export from here (strangler-fig —- * legacy public symbols are kept as shims until REARCH_GUI P4).+ * The layout concept (Yoga driver + safe-area) is the first concept relocated+ * out of the flat legacy plugins into a cohesive module. Behaviour is+ * byte-identical to the former `SafeArea.ts` + `SafeAreaPlugin.ts`; those files+ * now re-export from here (strangler-fig — legacy public symbols are kept as+ * shims).*/import type { App, Plugin } from '../../app';import { isWeChat, platformDevicePixelRatio } from '../../platform';diff --git a/sdk/src/ui/text/atlas-packer.ts b/sdk/src/ui/text/atlas-packer.tsindex 951d5b110..e8a0e972d 100644--- a/sdk/src/ui/text/atlas-packer.ts+++ b/sdk/src/ui/text/atlas-packer.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/text/atlas-packer.ts- * @brief Rectangle packer for the runtime dynamic glyph atlas (REARCH_GUI P1).+ * @brief Rectangle packer for the runtime dynamic glyph atlas.** Glyphs are packed into a fixed-size atlas page incrementally as they are first* seen. The packer is an interface so the heuristic is swappable; the defaultdiff --git a/sdk/src/ui/text/atlas-page-store.ts b/sdk/src/ui/text/atlas-page-store.tsindex f5af1727a..8c2844877 100644--- a/sdk/src/ui/text/atlas-page-store.ts+++ b/sdk/src/ui/text/atlas-page-store.ts@@ -2,9 +2,9 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/text/atlas-page-store.ts- * @brief Engine-backed AtlasPageStore for the dynamic glyph atlas (REARCH_GUI- * P1.3): a page is an RGBA8 GPU texture, glyphs land via the P1.0- * sub-region upload. The page id IS the texture handle, so the text+ * @brief Engine-backed AtlasPageStore for the dynamic glyph atlas: a page is+ * an RGBA8 GPU texture, glyphs land via the sub-region upload. The+ * page id IS the texture handle, so the text* renderer can pass it straight to submitTextBatch as the atlas texture.*/import type { ESEngineModule } from '../../wasm';diff --git a/sdk/src/ui/text/glyph-atlas.ts b/sdk/src/ui/text/glyph-atlas.tsindex da9150f2f..d613bbb80 100644--- a/sdk/src/ui/text/glyph-atlas.ts+++ b/sdk/src/ui/text/glyph-atlas.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/text/glyph-atlas.ts- * @brief Runtime dynamic glyph atlas (REARCH_GUI P1) — the cache + multi-page+ * @brief Runtime dynamic glyph atlas — the cache + multi-page* packer that turns "I need glyph X" into "here is its atlas rectangle".** Design: the atlas is SDF-agnostic. It deals only in upload-ready bitmaps; the@@ -10,7 +10,7 @@* the injected {@link AtlasPageStore} owns the GPU texture pages. Both are* interfaces so the orchestration is unit-testable (mock both) and the real* Canvas2D + engine implementations stay thin and swappable (e.g. a plain-alpha- * rasterizer fallback per REARCH_GUI §7.6).+ * rasterizer fallback).** Because SDF is resolution-independent, each glyph is rasterized ONCE at a fixed* `sdfRenderSize`; the display size scales the quad at draw time. The cache keydiff --git a/sdk/src/ui/text/glyph-rasterizer.ts b/sdk/src/ui/text/glyph-rasterizer.tsindex 4988e6c5b..aad894965 100644--- a/sdk/src/ui/text/glyph-rasterizer.ts+++ b/sdk/src/ui/text/glyph-rasterizer.ts@@ -3,7 +3,7 @@/*** @file ui/text/glyph-rasterizer.ts* @brief Canvas2D glyph rasterizer → SDF, the real GlyphRasterizer for the- * dynamic atlas (REARCH_GUI P1.3). Works on web AND WeChat (both expose+ * dynamic atlas. Works on web AND WeChat (both expose* a 2D canvas + getImageData; the legacy text path already relied on* this). Any font / CJK / emoji, since glyphs are drawn on demand.*diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.tsindex 63801112b..e6c3bf468 100644--- a/sdk/src/ui/text/layout.ts+++ b/sdk/src/ui/text/layout.ts@@ -3,7 +3,7 @@/*** @file ui/text/layout.ts* @brief Pure text layout + glyph-quad vertex building for the SDF text path- * (REARCH_GUI P1.3, TS-centric). Given the glyph atlas (which supplies+ * (TS-centric). Given the glyph atlas (which supplies* per-glyph atlas UVs + metrics), turn a string into positioned quads* and then into the interleaved vertex/index buffers `submitTextBatch`* expects. No Canvas/GL here, so it is fully unit-testable.@@ -209,7 +209,7 @@ export function wrapLine(}/**- * Lay out multi-line text (REARCH_GUI P1.4): splits on `\n`, lays each line out+ * Lay out multi-line text: splits on `\n`, lays each line out* (rich or plain), stacks lines downward (y-up: line 0 on top) by `lineHeight`,* and horizontally aligns each line within the widest line's block. Pure →* unit-testable. (Word-wrap to a max width is a later addition.)@@ -254,7 +254,7 @@ export function layoutText(}/**- * Lay out a single line of rich text (REARCH_GUI P1.4): `<b>`, `<i>`,+ * Lay out a single line of rich text: `<b>`, `<i>`,* `<color=#rrggbb[aa]>`, `<font size=N>` runs (parsed by parseRichText) become* glyphs carrying per-run color + size + bold/italic style. Image runs (`<img>`)* are skipped for now. Each run scales by its own fontSize / atlas.renderSize;diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.tsindex 86464826e..9a83150d3 100644--- a/sdk/src/ui/text/plugin.ts+++ b/sdk/src/ui/text/plugin.ts@@ -3,7 +3,7 @@/*** @file ui/text/plugin.ts* @brief TextPlugin — renders the `Text` component via the dynamic SDF glyph- * atlas (REARCH_GUI P1.4d), replacing the legacy Canvas2D-per-entity+ * atlas, replacing the legacy Canvas2D-per-entity* path. A pre-flush callback scans Text entities, composes the world* transform, places the text inside its UINode box (no auto-size — the* UINode is the box; rendering never mutates layout) and draws batcheddiff --git a/sdk/src/ui/text/sdf.ts b/sdk/src/ui/text/sdf.tsindex fdfb6216f..94f4756b0 100644--- a/sdk/src/ui/text/sdf.ts+++ b/sdk/src/ui/text/sdf.ts@@ -3,7 +3,7 @@/*** @file ui/text/sdf.ts* @brief TS wrapper over the engine's C++ 8SSEDT signed-distance-field- * generator (REARCH_GUI P1). The dynamic glyph atlas rasterizes a+ * generator. The dynamic glyph atlas rasterizes a* glyph to alpha via Canvas2D, then calls this to get an SDF that* stays crisp at any scale and supports cheap outline/shadow.*/@@ -15,7 +15,7 @@ import { withScratch } from '../../wasmScratch';* 128 encodes the edge; >128 inside, <128 outside, with `spread` pixels mapped* to half the byte range. Returns a fresh `width*height` Uint8Array, or `null`* when the engine build lacks the binding (caller falls back to a plain-alpha- * atlas — see REARCH_GUI §7.6).+ * atlas).*/export function sdfFromAlpha(module: ESEngineModule,diff --git a/sdk/src/ui/text/submit.ts b/sdk/src/ui/text/submit.tsindex 9d419fcb7..1747b1621 100644--- a/sdk/src/ui/text/submit.ts+++ b/sdk/src/ui/text/submit.ts@@ -2,8 +2,8 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/text/submit.ts- * @brief TS → engine submission for pre-laid-out SDF glyph quads (REARCH_GUI- * P1.3). The text system lays glyphs out against the dynamic atlas in+ * @brief TS → engine submission for pre-laid-out SDF glyph quads.+ * The text system lays glyphs out against the dynamic atlas in* TS, then hands the batch here; the engine routes it through the SDF* batch-shader variant. Mirrors the proven spine mesh-submit path.*/diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.tsindex fa6093fc8..b07c8e8a5 100644--- a/sdk/src/ui/text/text-renderer.ts+++ b/sdk/src/ui/text/text-renderer.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/text/text-renderer.ts- * @brief High-level SDF text drawing (REARCH_GUI P1.3): owns the dynamic glyph+ * @brief High-level SDF text drawing: owns the dynamic glyph* atlas and turns a string into batched glyph quads via the engine.** `drawTextWith` is the pure orchestration (inject atlas + a submit sink → unit-@@ -28,7 +28,7 @@ export interface DrawTextParams {originX?: number;originY?: number;style?: number;- /** Parse `<b>/<i>/<color>/<font size>` markup (REARCH_GUI P1.4). */+ /** Parse `<b>/<i>/<color>/<font size>` markup. */richText?: boolean;/** Horizontal alignment: 0 left | 1 center | 2 right. */align?: number;diff --git a/sdk/src/ui/text/text-transform.ts b/sdk/src/ui/text/text-transform.tsindex 355466250..000915562 100644--- a/sdk/src/ui/text/text-transform.ts+++ b/sdk/src/ui/text/text-transform.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/text/text-transform.ts- * @brief Pure placement helpers for SDF text (REARCH_GUI P1.4d): the entity+ * @brief Pure placement helpers for SDF text: the entity* world matrix and the rect→text-box mapping. No component here — the* canonical text component is core/text.ts `Text`, rendered by the SDF* text plugin.diff --git a/sdk/src/ui/theme/tokens.ts b/sdk/src/ui/theme/tokens.tsindex 88d15d7c1..4429c539d 100644--- a/sdk/src/ui/theme/tokens.ts+++ b/sdk/src/ui/theme/tokens.ts@@ -2,8 +2,8 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/theme/tokens.ts- * @brief ThemeTokens — semantic design tokens for the widget layer (REARCH_GUI- * F7), replacing the deleted per-widget UITheme god-object.+ * @brief ThemeTokens — semantic design tokens for the widget layer,+ * replacing the deleted per-widget UITheme god-object.** Widgets read their default colors from the active theme via {@link getTheme}* instead of hard-coding RGBA ("去裸色"): one place defines the palette, and andiff --git a/sdk/src/ui/ui-plugin.ts b/sdk/src/ui/ui-plugin.tsindex f457b1c3b..7c3c0db0b 100644--- a/sdk/src/ui/ui-plugin.ts+++ b/sdk/src/ui/ui-plugin.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file ui/ui-plugin.ts- * @brief UIPlugin — the single declarative UI pipeline (REARCH_GUI F6).+ * @brief UIPlugin — the single declarative UI pipeline.** Composes the formerly separate concept plugins (layout, mask, safe-area,* text, interaction, behavior, drag, focus, text-input, render-order) into onediff --git a/sdk/src/ui/uiHelpers.ts b/sdk/src/ui/uiHelpers.tsindex e55bac39f..060632227 100644--- a/sdk/src/ui/uiHelpers.ts+++ b/sdk/src/ui/uiHelpers.ts@@ -144,7 +144,7 @@ export function getEntityDepth(world: World, entity: Entity): number {return depth;}-/** Resolved px width of a UINode (its Yoga-computed size; REARCH_GUI F3). 0 if unresolved. */+/** Resolved px width of a UINode (its Yoga-computed size). 0 if unresolved. */export function getUINodeWidth(entity: Entity): number {if (module_ && nativeRegistry_ && module_.getUINodeComputedWidth) {return module_.getUINodeComputedWidth(nativeRegistry_, entity);diff --git a/sdk/src/ui/widgets/helpers.ts b/sdk/src/ui/widgets/helpers.tsindex 4bfd1acc5..6de66b367 100644--- a/sdk/src/ui/widgets/helpers.ts+++ b/sdk/src/ui/widgets/helpers.ts@@ -44,7 +44,7 @@ export interface UINodeInit {}/**- * Build a UINode (CSS box, REARCH_GUI). `fill: true` is the common widget case+ * Build a UINode (CSS box). `fill: true` is the common widget case* (stretch to the parent); otherwise set width/height and/or inset. Anchoring* (e.g. top-right) = position Absolute + the relevant insets.*/diff --git a/sdk/src/uiPlugins.ts b/sdk/src/uiPlugins.tsindex b7c8da495..50b3f22c0 100644--- a/sdk/src/uiPlugins.ts+++ b/sdk/src/uiPlugins.ts@@ -3,7 +3,7 @@import { uiPlugin } from './ui/ui-plugin';import type { Plugin } from './app';-// REARCH_GUI F6: the ten hand-ordered UI concept plugins are now composed into+// The ten hand-ordered UI concept plugins are now composed into// one declarative `uiPlugin`. The concept plugins remain individually exported// (from their modules) for granular wiring.export const uiPlugins: Plugin[] = [uiPlugin];diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 5cd1ff7a6..7a9ef04e3 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -13,7 +13,7 @@ import type { Registry as GeneratedRegistry } from './wasm.generated';// =============================================================================/**- * A JS-owned C++ EstellaContext instance (REARCH_ENGINE_INSTANCING N1). Created+ * A JS-owned C++ EstellaContext instance. Created* via `new module.EstellaContext()`, destroyed via `.delete()` — like Registry.* Owns one engine's GPU + logic subsystems; `setActiveContext` selects which one* the bindings route through.@@ -83,7 +83,7 @@ export interface SpineBounds {export interface ESEngineModule {Registry: new () => CppRegistry;- /** JS-newable engine context (REARCH_ENGINE_INSTANCING N1). */+ /** JS-newable engine context. */EstellaContext: new () => CppEngineContext;HEAPU8: Uint8Array;HEAPU32: Uint32Array;@@ -98,9 +98,9 @@ export interface ESEngineModule {initRendererWithContext(contextHandle: number): boolean;shutdownRenderer(): void;/**- * Select which EstellaContext the bindings route through (REARCH_ENGINE_INSTANCING- * N1). Pass null to clear. Existing initRenderer paths still set it implicitly- * until N3; this lets the editor own contexts explicitly.+ * Select which EstellaContext the bindings route through. Pass null to clear.+ * Existing initRenderer paths still set it implicitly; this lets the editor+ * own contexts explicitly.*/setActiveContext(ctx: CppEngineContext | null): void;@@ -122,14 +122,14 @@ export interface ESEngineModule {getResourceManager(): CppResourceManager;/*** Convert a Canvas2D-rasterized alpha bitmap to a signed distance field for- * the runtime glyph atlas (REARCH_GUI P1). `alphaPtr`/`outPtr` are HEAPU8+ * the runtime glyph atlas. `alphaPtr`/`outPtr` are HEAPU8* pointers to width*height byte buffers; the SDF is written into `outPtr`.*/sdfFromAlpha?(alphaPtr: number, outPtr: number, width: number, height: number, spread: number): void;/*** UI draw order of an entity (its UIVisual.uiOrder, assigned by the UI* render-order pass), so SDF text quads interleave with UI quads. -1 if the- * entity is not a UI render node (REARCH_GUI P1.4d #1).+ * entity is not a UI render node.*/ui_getRenderOrder?(registry: CppRegistry, entity: number): number;getSpineBounds?(registry: CppRegistry, entity: number): SpineBounds;@@ -150,8 +150,8 @@ export interface ESEngineModule {layer: number, depth: number): void;/**- * Submit pre-laid-out glyph quads against the dynamic SDF atlas (REARCH_GUI- * P1.3). Vertex format x,y,u,v,r,g,b,a; routed through the SDF batch variant.+ * Submit pre-laid-out glyph quads against the dynamic SDF atlas.+ * Vertex format x,y,u,v,r,g,b,a; routed through the SDF batch variant.*/renderer_submitTextBatch?(verticesPtr: number, vertexCount: number,diff --git a/sdk/src/webAppFactory.ts b/sdk/src/webAppFactory.tsindex ed40f1a2a..feb776eb6 100644--- a/sdk/src/webAppFactory.ts+++ b/sdk/src/webAppFactory.ts@@ -16,7 +16,7 @@ import { SpinePlugin, WebSpineWasmProvider } from './spine';import type { SpineWasmProvider } from './spine';export { uiPlugins };-// REARCH_GUI F6: the single composed UI pipeline; the concept plugins below are+// The single composed UI pipeline; the concept plugins below are// re-exported for granular/advanced wiring.export { uiPlugin, UIPlugin } from './ui/ui-plugin';export { textPlugin, TextPlugin } from './ui/text/plugin';@@ -36,7 +36,7 @@ export { AudioPlugin, audioPlugin } from './audio';export { ParticlePlugin, particlePlugin } from './particle';export { PostProcessPlugin, postProcessPlugin } from './postprocess';export { TimelinePlugin, timelinePlugin, registerTimelineAsset, parseTimelineAsset, Timeline, TimelineApi, TimelinePlayer, type TimelinePlayerData } from './timeline';-// Authoring + pure-TS evaluation surface for the editor Sequencer (REARCH_ANIMATION).+// Authoring + pure-TS evaluation surface for the editor Sequencer.export {sampleTimeline, sampleTimelineInWorld, evaluateChannel, applyWrapMode,serializeTimelineAsset, serializeTimelineToJson, resolveChildEntity, parseAnimationClip,diff --git a/src/esengine/animation/TweenSystem.cpp b/src/esengine/animation/TweenSystem.cppindex efe0df220..d920803ac 100644--- a/src/esengine/animation/TweenSystem.cpp+++ b/src/esengine/animation/TweenSystem.cpp@@ -128,8 +128,8 @@ void TweenSystem::resumeTween(ecs::Registry& registry, Entity tweenEntity) {}// Tween owns the writes for its fixed 13 targets (was routed through the generic-// animTargets `applyAnimatedValue`; REARCH_ANIMATION P4b decouples it so the-// generic enum+switch can be deleted with the C++ timeline in P4c). Mirrors the+// animTargets `applyAnimatedValue`; decoupled so the generic enum+switch could be+// deleted with the C++ timeline). Mirrors the// per-field semantics exactly: rotation.z → half-angle quaternion, and the UINode// `anim_override_` flags so UI layout doesn't clobber animated Transform fields.// Flag the entity's UINode so the layout pass leaves the tween-driven Transformdiff --git a/src/esengine/bindings/ActiveContext.hpp b/src/esengine/bindings/ActiveContext.hppindex 5c6e88a1e..3c3b187fa 100644--- a/src/esengine/bindings/ActiveContext.hpp+++ b/src/esengine/bindings/ActiveContext.hpp@@ -10,7 +10,7 @@ namespace esengine {/*** @brief The explicitly-installed active engine context (or null if none).- * @details Set by setActiveContext (REARCH_ENGINE_INSTANCING) or, until N3, by+ * @details Set by setActiveContext or, until N3, by* the legacy initRenderer path. Read through {@link activeCtx}.*/inline EstellaContext* g_activeContext = nullptr;diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 29452f729..cd90eb4d7 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -107,7 +107,7 @@ void renderer_submitSpineBatchByEntity(#endif-// REARCH_GUI P1.3: TS lays out glyph quads against the dynamic SDF atlas and+// TS lays out glyph quads against the dynamic SDF atlas and// submits them here (ungated — text is core, unlike spine).void renderer_submitTextBatch(uintptr_t verticesPtr, i32 vertexCount,diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 1bb64daee..628a77d5f 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -245,7 +245,7 @@ resource::ResourceManager* getResourceManager() {return g_resourceManager;}-// Runtime glyph atlas (REARCH_GUI P1): convert a Canvas2D-rasterized alpha+// Runtime glyph atlas: convert a Canvas2D-rasterized alpha// bitmap to a signed distance field. Both buffers are caller-allocated in WASM// linear memory (TS passes HEAPU8 pointers); `alpha` and `out` are width*height.void web_sdfFromAlpha(uintptr_t alphaPtr, uintptr_t outPtr, u32 width, u32 height, f32 spread) {@@ -262,7 +262,7 @@ void web_sdfFromAlpha(uintptr_t alphaPtr, uintptr_t outPtr, u32 width, u32 heigh// WebBindings.generated.cpp (generated by EHT's PtrLayoutGenerator), which is// the single source of truth for the pointer ABI. Do not hand-maintain// static_assert(offsetof(...)) here — they drifted and only covered 8 of N-// components. See docs/REARCHITECTURE.md (root cause 1).+// components.int getTransformPtr(ecs::Registry& r, u32 e) {auto* t = r.tryGet<ecs::Transform>(Entity::fromRaw(e));@@ -319,7 +319,7 @@ EMSCRIPTEN_BINDINGS(esengine_ptr_access) {emscripten::function("getCircleColliderPtr", &esengine::getCircleColliderPtr);}-// Engine instancing (REARCH_ENGINE_INSTANCING.md, N1): expose EstellaContext as+// Engine instancing: expose EstellaContext as// a JS-newable instance + an explicit active-context setter, so the editor can// own / create / destroy isolated engine contexts rather than every App being// hard-bound to the process singleton (EngineContext::instance()). PURE ADDITION@@ -545,7 +545,7 @@ void uiRenderOrder_update(ecs::Registry& registry) {ecs::uiRenderOrderUpdate(registry);}-// REARCH_GUI P1.4d (#1 z-order): the SDF text path (TS) reads an entity's UI+// The SDF text path (TS) reads an entity's UI// draw order so glyph quads interleave with UI quads. uiRenderOrderUpdate// assigns uiOrder to every UIVisual in the UI tree (text nodes carry a// visualType=None UIVisual purely to be ordered). -1 = not a UI node.diff --git a/src/esengine/core/UITypes.hpp b/src/esengine/core/UITypes.hppindex 6efd7671a..9518d6050 100644--- a/src/esengine/core/UITypes.hpp+++ b/src/esengine/core/UITypes.hpp@@ -18,7 +18,7 @@ struct Padding {/*** @brief A CSS-style length: `value` interpreted per `unit`.*- * The runtime UI box model (REARCH_GUI F2/F3, see docs/REARCH_GUI.md) uses+ * The runtime UI box model uses* Dimension for width/height/min/max/inset so one field can be pixels, a* percentage of the parent, or content-driven — retiring the old* size/offset/`-1`-sentinel scheme. Kept a flat POD (f32 + u8) so it serializes@@ -31,7 +31,7 @@ struct Dimension {};/**- * @brief One named visual state for StateVisuals (REARCH_GUI F5).+ * @brief One named visual state for StateVisuals.** The element type of `StateVisuals.states` — a variable-length list that* replaced the old 8 hardcoded `slotN*` field quartets + stringly-keyeddiff --git a/src/esengine/data/shaders/batch.esshader b/src/esengine/data/shaders/batch.esshaderindex 3055d8121..3a879d7fe 100644--- a/src/esengine/data/shaders/batch.esshader+++ b/src/esengine/data/shaders/batch.esshader@@ -2,7 +2,7 @@#pragma version 300 es// Compile-time variant: when enabled the fragment stage treats the sampled-// alpha as a signed distance field (runtime glyph atlas, REARCH_GUI P1) and+// alpha as a signed distance field (runtime glyph atlas) and// derives crisp, resolution-independent coverage instead of sampling RGBA.#pragma feature SDFdiff --git a/src/esengine/ecs/UILayoutSystem.cpp b/src/esengine/ecs/UILayoutSystem.cppindex 67d762255..46e2f4255 100644--- a/src/esengine/ecs/UILayoutSystem.cpp+++ b/src/esengine/ecs/UILayoutSystem.cpp@@ -84,7 +84,7 @@ YGAlign toYGAlignSelf(AlignSelf as) {}// =============================================================================-// UINode (CSS box) → single-pass Yoga (REARCH_GUI: the single layout model)+// UINode (CSS box) → single-pass Yoga (the single layout model)// =============================================================================//// A UINode subtree is laid out by ONE Yoga solve: each entity becomes a YGNode,diff --git a/src/esengine/ecs/components/StateVisuals.hpp b/src/esengine/ecs/components/StateVisuals.hppindex 7ba68cb47..37fd6da91 100644--- a/src/esengine/ecs/components/StateVisuals.hpp+++ b/src/esengine/ecs/components/StateVisuals.hpp@@ -27,7 +27,7 @@ namespace StateVisualsTransition {/*** @brief Maps state names to visual overrides on a target entity.*- * @details A variable-length `states` list (REARCH_GUI F5 — replaced the old 8+ * @details A variable-length `states` list (replaced the old 8* hardcoded `slotN*` field quartets + stringly-keyed reflection). The* visual system reads the owning entity's StateMachine.current, finds* the matching VisualState by name, and applies its color / sprite /diff --git a/src/esengine/ecs/components/UINode.hpp b/src/esengine/ecs/components/UINode.hppindex 9c3dc8227..6dd8b2e13 100644--- a/src/esengine/ecs/components/UINode.hpp+++ b/src/esengine/ecs/components/UINode.hpp@@ -11,8 +11,8 @@ namespace esengine::ecs {/*** @brief Per-item cross-axis alignment override (CSS align-self). Lives on- * UINode since UINode carries the flex-item properties (REARCH_GUI F4:- * the standalone FlexItem component was subsumed by UINode and removed).+ * UINode since UINode carries the flex-item properties (the standalone+ * FlexItem component was subsumed by UINode and removed).*/ES_ENUM()enum class AlignSelf : u8 {@@ -27,7 +27,7 @@ enum class AlignSelf : u8 {* @brief Box positioning scheme. Absolute takes the node out of flex flow and* places it by `inset` against the parent's box — this is how anchor /* stretch (the old RectTransform use cases) are expressed in the CSS- * model (REARCH_GUI F3 unification): e.g. inset 0 on all edges = stretch+ * model: e.g. inset 0 on all edges = stretch* to fill; top+right set = anchor to the top-right corner.*/ES_ENUM()@@ -37,8 +37,8 @@ enum class UIPositionType : u8 {};/**- * @brief UINode — the CSS box-model layout input (REARCH_GUI F3, the CSS/Flex- * primary layout model; see docs/REARCH_GUI.md).+ * @brief UINode — the CSS box-model layout input (the CSS/Flex+ * primary layout model).** Replaces the RectTransform anchor/offset/pivot model (UIRect) as the primary* way to author UI geometry: every size is a Dimension (px / percent / auto), feddiff --git a/src/esengine/ecs/components/UIVisual.hpp b/src/esengine/ecs/components/UIVisual.hppindex 779c4cec2..8a419f1c0 100644--- a/src/esengine/ecs/components/UIVisual.hpp+++ b/src/esengine/ecs/components/UIVisual.hpp@@ -11,7 +11,7 @@ namespace esengine::ecs {/*** @brief How a UIVisual fills its UINode box. Replaces the old UIRenderer- * visualType + Image imageType pair (REARCH_GUI F4): a single draw mode,+ * visualType + Image imageType pair: a single draw mode,* so the renderer derives the sampled UV at draw time and no frame-late* Image->UIRenderer copy system is needed.*@@ -45,7 +45,7 @@ enum class UIFillOrigin : u8 {};/**- * @brief UIVisual — the single UI visual component (REARCH_GUI F4), merging the+ * @brief UIVisual — the single UI visual component, merging the* former low-level UIRenderer (what the renderer drew) and high-level* Image (Simple/Sliced/Tiled/Filled intent that used to be copied into a* UIRenderer each frame). One component authored directly; UIElementPlugindiff --git a/src/esengine/particle/ParticleEasing.hpp b/src/esengine/particle/ParticleEasing.hppindex 0592cc1d2..40edfe585 100644--- a/src/esengine/particle/ParticleEasing.hpp+++ b/src/esengine/particle/ParticleEasing.hpp@@ -15,7 +15,7 @@ enum class EasingType : i32 {};// Delegates to the shared easing library so the math lives in ONE place-// (docs/REARCH_ANIMATION.md easing consolidation). Particle keeps its own 4-value+// (easing consolidation). Particle keeps its own 4-value// enum (its serialized data format); the formulas are byte-identical to the quad// easings, so this is behavior-preserving.inline f32 applyEasing(EasingType type, f32 t) {diff --git a/src/esengine/renderer/BatchBuilder.hpp b/src/esengine/renderer/BatchBuilder.hppindex 062237de1..d475f42af 100644--- a/src/esengine/renderer/BatchBuilder.hpp+++ b/src/esengine/renderer/BatchBuilder.hpp@@ -7,8 +7,8 @@* DrawCommand -> apply clip state -> push" sequence that each batch emitter* (sprite/UI/text/particle/tilemap plugins + RenderFrame's spine/tile direct* submits) used to copy verbatim. Giving the renderer one submission face here- * is the de-risking prerequisite for the GfxDevice keystone (docs/REARCH_RENDER.md- * P0): the keystone rewrites DrawList::execute against a single producer, not six.+ * is the de-risking prerequisite for the GfxDevice keystone: the keystone rewrites+ * DrawList::execute against a single producer, not six.** @author ESEngine Team* @date 2026diff --git a/src/esengine/renderer/FrameConstants.hpp b/src/esengine/renderer/FrameConstants.hppindex 8750c2328..6798aaa84 100644--- a/src/esengine/renderer/FrameConstants.hpp+++ b/src/esengine/renderer/FrameConstants.hpp@@ -8,7 +8,7 @@* declares `layout(std140) uniform FrameConstants { mat4 u_projection; };`* and Shader::compile auto-links that block to the binding point — there is* no loose per-shader u_projection upload. This is the first non-texture- * resource of the eventual P2 BindGroup model (docs/REARCH_RENDER.md).+ * resource of the eventual BindGroup model.** @author ESEngine Team* @date 2026diff --git a/src/esengine/renderer/PipelineState.hpp b/src/esengine/renderer/PipelineState.hppindex 2d3e79b4e..3a1b4fde4 100644--- a/src/esengine/renderer/PipelineState.hpp+++ b/src/esengine/renderer/PipelineState.hpp@@ -10,7 +10,7 @@* it with GfxDevice::setPipeline. Per-draw dynamic state — scissor rectangle and* stencil reference — stays out of the pipeline (see setScissor/setStencilReference),* mirroring WebGPU's split. This is the keystone abstraction that lets a WebGPU- * backend slot in beside the WebGL2 one (docs/REARCH_RENDER.md P2).+ * backend slot in beside the WebGL2 one.** @author ESEngine Team* @date 2026diff --git a/src/esengine/renderer/RenderFrame.hpp b/src/esengine/renderer/RenderFrame.hppindex e30fec2ae..39a9e4441 100644--- a/src/esengine/renderer/RenderFrame.hpp+++ b/src/esengine/renderer/RenderFrame.hpp@@ -88,8 +88,8 @@ public:);/**- * Submit a batch of pre-laid-out glyph quads from TS (REARCH_GUI P1.3, the- * dynamic SDF glyph atlas). Same vertex format as submitSpineBatch+ * Submit a batch of pre-laid-out glyph quads from TS (the dynamic SDF glyph+ * atlas). Same vertex format as submitSpineBatch* (x,y,u,v,r,g,b,a per vertex) but routed through the SDF batch variant* (batchProgram({"SDF"})) with RenderType::Text. The atlas page is `textureId`.*/@@ -132,7 +132,7 @@ public:/*** Compiled program id for a batch-shader feature variant, compiled+cached on- * first use (REARCH_GUI P1.2). `{}` is the default batch program; `{"SDF"}`+ * first use. `{}` is the default batch program; `{"SDF"}`* is the glyph-atlas SDF text variant. Same vertex layout + sampler/UBO setup* as the default, so quads of any variant share the batch vertex format.*/@@ -173,8 +173,8 @@ private:std::unordered_map<u32, EntityStencilInfo> stencil_masks_;u32 batch_shader_id_ = 0;- // Compiled batch-shader variants keyed by ShaderParser::variantKey(features)- // (REARCH_GUI P1.2). {} → default, {"SDF"} → glyph-atlas text.+ // Compiled batch-shader variants keyed by ShaderParser::variantKey(features).+ // {} → default, {"SDF"} → glyph-atlas text.std::unordered_map<std::string, u32> batch_variants_;TransientBufferPool pool_;DrawList draw_list_;diff --git a/src/esengine/renderer/ShaderEmbeds.generated.hpp b/src/esengine/renderer/ShaderEmbeds.generated.hppindex a5cc343a9..dce606d2f 100644--- a/src/esengine/renderer/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/ShaderEmbeds.generated.hpp@@ -6,7 +6,7 @@ inline constexpr const char* BATCH = R"esshader(#pragma shader "Batch"#pragma version 300 es// Compile-time variant: when enabled the fragment stage treats the sampled-// alpha as a signed distance field (runtime glyph atlas, REARCH_GUI P1) and+// alpha as a signed distance field (runtime glyph atlas) and// derives crisp, resolution-independent coverage instead of sampling RGBA.#pragma feature SDFdiff --git a/src/esengine/renderer/Texture.hpp b/src/esengine/renderer/Texture.hppindex 5ba34fd3a..9ac0f8212 100644--- a/src/esengine/renderer/Texture.hpp+++ b/src/esengine/renderer/Texture.hpp@@ -201,7 +201,7 @@ public:/*** @brief Uploads pixel data to a sub-rectangle of the texture.*- * Lets the dynamic glyph atlas (REARCH_GUI P1) pack glyphs one-by-one+ * Lets the dynamic glyph atlas pack glyphs one-by-one* without re-uploading the whole atlas. The sub-rect must lie fully inside* the texture and `data` must be tightly packed in this texture's format.*diff --git a/src/esengine/renderer/plugins/BatchPlugin.hpp b/src/esengine/renderer/plugins/BatchPlugin.hppindex 0eb1caf9f..e9b064f1d 100644--- a/src/esengine/renderer/plugins/BatchPlugin.hpp+++ b/src/esengine/renderer/plugins/BatchPlugin.hpp@@ -8,7 +8,7 @@* differ. This base owns the shared geometry construction (parameterized over those* differences) and the batch shader id, leaving each plugin only its ECS query and* per-entity attribute resolution. Submission goes through BatchBuilder, so there is- * one quad-emitting path for the renderer keystone to target (docs/REARCH_RENDER.md P0).+ * one quad-emitting path for the renderer keystone to target.** @author ESEngine Team* @date 2026diff --git a/src/esengine/renderer/plugins/UIElementPlugin.cpp b/src/esengine/renderer/plugins/UIElementPlugin.cppindex 0f60c0948..76f814196 100644--- a/src/esengine/renderer/plugins/UIElementPlugin.cpp+++ b/src/esengine/renderer/plugins/UIElementPlugin.cpp@@ -97,7 +97,7 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {// Derive the sampled UV from the base sub-region + the fill mode. This// replaces the old per-frame Image->UIRenderer copy: Tiled repeats by- // box/tileSize, Filled crops to fillAmount. (REARCH_GUI F4.)+ // box/tileSize, Filled crops to fillAmount.glm::vec2 uvOffset = renderer.uvOffset;glm::vec2 uvScale = renderer.uvScale;if (renderer.visualType == ecs::UIVisualType::Tiled) {diff --git a/src/esengine/text/SdfGenerator.hpp b/src/esengine/text/SdfGenerator.hppindex cd7bc2e5c..edcb6e8dd 100644--- a/src/esengine/text/SdfGenerator.hpp+++ b/src/esengine/text/SdfGenerator.hpp@@ -4,7 +4,7 @@* @file text/SdfGenerator.hpp* @brief Signed distance field generation from an 8-bit alpha coverage bitmap.*- * Used by the runtime dynamic glyph atlas (REARCH_GUI P1): glyphs are rasterized+ * Used by the runtime dynamic glyph atlas: glyphs are rasterized* to alpha via Canvas2D on the TS side, then converted to an SDF here so they* stay crisp at any scale and support cheap outline/shadow in the shader. Pure* (no GL / no emscripten) so it is unit-testable and portable.