.`, one row `world.` (`world.render.exposure`, `world.environment.fog.density`), a vector's fields `world.gravity.x`/`.y`/`.z`, an enum's items `world..` (`world.render.tonemap.neutral`), a colour's picker `world..pick`, and the reset arrow `world..reset`. `crates/editor/tests/d19_world.rs` drives it through the winit boundary: gravity, exposure and fog density each one step, shown and saved; a drag and a typed word each one step; a refused exposure; a dropdown; the reset arrow; the search; and the panel at 100-200% display scale. ## Project Settings The usual editor's **Project Settings**: a page over the editor (Edit ▸ Project Settings…, the toolbar's Settings, the Export panel's Edit in Project Settings) with a category list on the left and typed rows on the right. It edits `argus.project.json` through the workspace service (`crates/editor/src/settings.rs`, below under [The workspace service](#project-settings-1)): what is typed waits for **Apply**, Revert drops it, and closing the page keeps it. | Group | Category | Rows (manifest pointer) | |---|---|---| | Project | Identity | **Project type** (2D, 3D, 3D HD: `/kind` with `/render/profile`, below); Display name, Application id, Executable name, Version, Build number (`/application/*`) | | Project | Startup and window | Startup scene; Window width and height (whole pixels, 64..8192, checked as typed with the contract's `project-window-size`), Resizable (a checkbox) | | Project | Packaging | Icon, with Choose… and a preview (`/application/icon`) | | Project | Asset generation | **Concept images** and **3D model generator**, each an Enabled checkbox (off by default) and a Provider dropdown (the concept step's shows tripo until another is picked, and the file holds it only once one is); **Image model** and **Concept views** (Auto by asset type, 1 or 2; Auto leaves `views` out of the file, 1 and 2 write a number) for the concept step; **Style** (render, proportion, wear: dropdowns over the taxonomy's values, None leaves the facet out); **Spend** (project and session caps, Ask before paying, on by default), with the running spend from the library's ledger and each provider's key status, with where the key comes from in plain words, and a **Set key…** button that opens the person-only `keys set` in a terminal (a key is never typed in the editor and never stored in the project); **Budgets** as one table, a line per class and a column per profile, each cell triangles / texture side, muted at the gate's own ceiling until typed (`settings.assets.budget...`). A note says generation uses your own provider keys and costs money. Nothing is generated in a project until it opts in here. Authoring only: a change needs no restart or export | | Engine | Physics | Default gravity (`/physics/gravity`), Quality (`/physics/quality`); **Overrides** and **Sleep** (`/physics/overrides/*`) | | Engine | Graphics | Renderer, standard or HD (`/render/profile`), shown and not edited: "set by Project type"; **Default look**: style, shading, filter, tonemap, exposure, resolution scale, anti-aliasing (`/graphics/render/*`); **Quality (HD)**: preset, target frame rate, the knobs it overrides, the custom profile (`/render/quality/*`); **Windows** and **Linux**: each platform's preset, frame rate and knob overrides over it (`/render/quality/platforms//*`), and what that platform runs | | Engine | Input | The project's action map (`/input`) as [the Input table](#the-input-table) | | Engine | Audio | **Buses**: Master, Music and Effects volume (the buses named `master`, `music`, `sfx` in `/audio/buses`); Voices, Output device (`/audio/voices`, `/audio/device`) | **Project type is one row for two fields**. It is the first row of Identity (`settings./kind`), a choice of **2D** (`kind` `2d`, `render.profile` `standard`), **3D** (`3d`, `standard`) and **3D HD** (`3d`, `hd`), the same `argus_projects::template::ProjectType` New project offers. A choice waits for Apply like any row, and Apply sends **both** `/kind` and `/render/profile` in one change set, the pair an agent sends with `project.settings.set`; choosing what the project already is sends nothing. The Graphics ▸ Renderer row only shows the renderer, with "set by Project type", so two controls never write `render.profile`; the service's own `/kind` field ("Project kind") is this row, not a second one. A manifest from before `kind` reads as 3D or 3D HD by its renderer. A pair the row does not offer (a hand-edited `2d` on `hd`) reads **Custom (2d, hd)** with the `project-kind-2d-hd` warning on the row (`settings./kind.diagnostic.project-kind-2d-hd`); the project still loads and draws, and choosing any type replaces the pair. The row publishes what it reads as `settings./kind.shows.<2d|3d|3d-hd|custom>`. An applied change goes the renderer's restart path: the project reopens (`Exit::Reopen`), after the unsaved-work prompt when anything is unsaved, whose extra line says the project reopens and scenes are not changed (`prompt.then`). **Changing the type converts nothing.** No scene is rewritten; the kind sets the defaults new game cameras and physics take (orthographic and planar for 2D) and how the viewport behaves, and the Identity section says so (`settings.identity.project-type`). **The Engine categories are the defaults every scene starts from** (option A): a scene that leaves a field out of its `meta` takes the project's, and one that writes it overrides it ([World Settings](#world-settings) shows which). The rows are World Settings' own for the same field — label, editor, hover line — from `world_settings::describe`, and a row the manifest leaves out shows, greyed, the engine's default that then stands. A row the manifest writes has the usual editor's reset arrow, which takes the value out of the manifest. A typed row not yet applied has its label in the warning colour. **Graphics reuses the quality system; it adds none.** The presets are the contract's `RENDER_QUALITY_PRESETS`, the knobs and their types `RENDER_QUALITY_KNOBS` (a boolean is a checkbox, an integer a whole-number field, a choice a dropdown), and a platform's line under its rows ("Linux (this machine) runs: high at 60 fps, 1 knob overridden") is `effective_render_quality`, the layering the launch plan hands the renderer. The base quality and each platform are the same rows over another pointer. A knob is overridden with **Override a knob…**, which lists every knob not yet overridden; the arrow gives it back to the preset. Quality is the HD renderer's (`project-render-quality-without-hd`), so its rows are disabled, with a line saying so, until the Renderer is HD. **Input** is the input table over the project's map (`input_ui::InputTarget::Project`), read from the manifest with anything typed over it (`project_settings::ProjectMaps`). A project with no map shows the built-in one, and the first change copies it into `/input`. A change waits for Apply like every other row; **Remove the project's map** takes `/input` out. **One edit per settings field.** The service takes an edit only at one of its fields, so a row inside one — one override, one platform's preset, one bus's volume — is typed by its own pointer and Apply sends the whole field with the row applied (`project_settings::edits`): `/physics/overrides`, `/render/quality/platforms`, `/audio/buses`. An object left empty is taken out. **Diagnostics and refusals are on their rows.** Every diagnostic of the manifest is shown under the row whose pointer it names (a bus by its index is matched to its name), and the rest at the top of the section. An Apply the service refuses (422 `invalid-settings`) writes nothing, keeps what was typed, says why at the foot, and puts each diagnostic on its row until the next Apply or Revert: a substep count of 99 is `project-default-invalid: physics-quality-invalid: …; every scene that does not set its own takes this default`. What a change needs (`requires.restart`, `requires.reExport`, from the service) is said once per section, or with a `×` on the row where the section is mixed. **After an apply the editor follows.** The shell re-reads the manifest (`Editor::adopt_manifest`), takes the scene defaults into the document's context and shows the scene again with them, so the viewport and World Settings reflect the new defaults without the scene being reopened. Play reads the manifest when it starts (`Editor::preview_run_scene` merges the saved scene's meta over the defaults as they are then). A change made elsewhere — an agent's `project.settings.set`, another window — is found the same way (the service's change report, or the two-second disk check), and the page reads the settings again, keeping what was typed on it (`EditorUi::refresh_settings_view`). **Search.** One box filters every category at once, as the usual editor's does: a row by its label, pointer or group title, the Input section by an action's or a context's name (or "input", "key", "gamepad"). The tree counts each category's hits, and while a search is on the form shows every category with a hit under its own header. **Not here yet** (they are not manifest fields): export targets, development and release builds and installers, which belong to the launcher; default friction and bounciness, collision layers, and a fixed timestep, which the engine does not have as settings; `settings.ui` (default theme and locale), which `project.settings.set` edits and this page does not draw yet. **Hit names.** `settings.category.` (`identity`, `startup-window`, `packaging`, `physics`, `graphics`, `input`, `audio`), `settings.section.` (and `.note`, `.defaults`), one row `settings.` (`settings./physics/gravity`), a vector's fields `settings./physics/gravity.x`, a dropdown's items `settings..`, the reset arrow `settings..reset`, a row's first diagnostic `settings..diagnostic`, a group title `settings.group..`, Override a knob… `settings./overrides.add` and its items `.add..`, a platform's line `settings..effective`, and the Input section's `settings.input.source`; the table's own controls are `input.…`. `crates/editor/tests/d19_project.rs` drives it through the winit boundary: a gravity default shown "from project" in World Settings and run in Play; a scene's override and the reset arrow; a project input rebinding a scene without its own plays; a platform preset and knob stored under `render.quality.platforms` and a refused frame rate on its row; `project-default-invalid`; the search; and the page at 100-200% display scale. `crates/agent/tests/d19_project_settings.rs` holds the parity. ## Behaviours This was the one step of the product's exit gate — New project → Import model → **Add Behaviour** → Play → Revise → Export → Run — the editor could not do. An entity could carry a behaviour, and a person had no way to give it one; `script.module` was reachable only by editing the scene file by hand or by asking an agent. **Everything here lands as one undo step through `Editor::commit_scene`**, the seam the Content browser's Place already uses: authoring only, computed as a whole new scene that already passes the contract, shown in the authoring world before it is committed, and carrying the selection as it was. So a behaviour a person attaches and a behaviour an agent attaches (`crates/agent`'s `entity.add_behaviour`) are the same edit arrived at two ways, and Play, the build and undo cannot tell them apart. ### Add component At the **top** of the Details panel, above the transform, where the usual editor's own "+ Add" is. Not a matter of taste: the panel is 320 points wide at most and as little as 480 tall at 150 % display scaling, and an entity with three components already fills it — a catalogue under the property sections was drawn below the bottom of the window, where a control is not published at all and neither a person nor a gate can press it. **Add component** (`inspector.@add-component`) opens a list of the component kinds the contract will take, each added with the contract's own defaults, and the one under the pointer described on the single line below. A kind is `inspector.@add-component.`. The `@` is the same control namespace the typed property rows use, so a property can be called anything without taking a control's name. | Offered | Added as | One per entity | |---|---|---| | Behaviour (`script`) | nothing on its own — it opens the behaviour catalogue, because a `script` with no module is a scene the contract refuses | no | | Collider | a unit box | no | | Rigid body | `dynamic` where the entity has a non-trigger collider, `kinematic` where it has not (`dynamic-needs-collider`) | yes | | Trigger | `triggered`, not once | yes | | Goal | the next number in the 1..n sequence the contract requires, with a goal id no goal in the scene has | yes | | Controller, Camera, Light, Spawn point, Nav area, Nav agent, Label, HUD element, Particles | the contract's defaults; a new camera is `primary` only when no camera in the scene is (`primary-camera`) | yes | **`mesh`, `animator` and `audio` are not offered.** Each names an asset, and an asset reference is the import flow's to write — the same reason `script.module` and `mesh.asset` have no typed property row. They arrive through Import and through the Content browser's Place, where the file being named actually is. **A kind that cannot go here says so before it is pressed.** A second controller on one entity is a component nothing reads, because `crates/app`'s `wire_entity` seats one per entity; a trigger with no trigger collider is `trigger-needs-trigger-collider`. Both are drawn disabled with the reason on hover, rather than left to a refusal in the toolbar after the click. A collider and a behaviour are the two an entity may have several of — an entity may carry a solid shape and a sensing volume, and the starter course runs several behaviours on the player. The contract still has the last word: `Document::component_added` reads the component back as an `argus_contract::Component` and then checks the whole scene, so anything the catalogue's precondition misses changes nothing and the toolbar names the rule. ### Add behaviour **Add behaviour** (`inspector.@add-behaviour`), or Behaviour in the component list, opens the catalogue of modules `script.module` may name (`behaviour.catalogue`), narrowed by a search box (`behaviour.search`): - **This project's own**, from the `.ts` and `.js` files under the open scene's folder. A module name is the file's path under that folder without the extension — `behaviors/door` — which is what `crates/app/src/modules.rs` resolves and what the build writes. It is the same enumeration `crates/agent`'s `argus://behaviours` resource lists a project by, so what an agent will accept and what this catalogue offers cannot drift apart. - **The built-ins** that ship with the engine: `player`, `camera`, `animator`, `hud`, `audio`, `particles`, `label`. `packages/gameplay/src/behaviors/catalogue.ts` is the source of truth, and an installed editor has no checkout beside it to read, so the editor carries a copy that `tests/d9_behaviour.rs` holds to that file — the modules and the props each one reads. - **New behaviour…** (`behaviour.new`), below. A module is `behaviour.item.`. Choosing one writes a `script` component naming it, as one undo step, and **the typed property rows are there the moment it lands**. **What a behaviour is attached with is only what its own source states.** A built-in's props are the defaults its module spells out (`props.x ?? v`), so attaching one changes nothing and still gives the person rows to tune. `player.speed` is deliberately not written: its default is `props.speed ?? component?.speed ?? 4`, so a `speed` prop would silently override the entity's own `controller` component, and an attach that changes how the player moves is not a no-op whatever the number says. Nothing is known about a project behaviour's props, so none are asserted; the add-property row is how they are given. **A second copy of one module on one entity is refused**, in the same words `entity.add_behaviour` uses: two ticks of the same behaviour is never what was meant. The row is drawn and disabled rather than left out, so the person can see that it is already running. ### New behaviour from a template **New behaviour…** opens a dialog: a name (`behaviour.new.name`), a template (`behaviour.new.template.`), Create (`behaviour.new.create`) and Cancel (`behaviour.new.cancel`). Nothing is written before Create. | Template | `t` | Is | |---|---|---| | Empty | `empty` | `init` and `update`, and nothing else yet | | Rotate | `rotate` | spins the entity about one axis at a steady rate | | Collectable | `collectable` | the starter course's pickup, byte for byte | | Trigger door | `trigger-door` | the starter course's `door.ts`, byte for byte | | Interactable | `interactable` | the starter course's `interactor.ts`, byte for byte | | Timer | `timer` | a HUD countdown that emits once when it runs out | Three of the six are `fixtures/starter-course/scenes/behaviors/{collectable,door,interactor}.ts` **byte for byte**: a person starting a pickup should start from the pickup the documentation describes, not from a second almost-identical one, and `d9_behaviour.rs` is what keeps the two copies one thing — the same test `tests/template.rs` runs over the collection course's scene. The file written is the template's bytes exactly; nothing on the way to disk reformats a file somebody is about to open and read. **It is refused for the same names New scene is refused for**, and for the same reasons (see [Scenes](#scenes)): a name is a file name and not a path, `.` and `..` are not file names, a dot-leading name is in no revision so nothing would ever build it, a name longer than `Editor::SCENE_NAME_MAX` fails at the write with a raw `ENAMETOOLONG` instead of in the dialog, the characters are the contract's own project-path rule asked about a path built **as text**, and a name that differs from an existing file only in case coexists on Linux and collides on Windows. Two more are this file's own: a name is compared against `.js` as well as `.ts`, because two files that resolve to one module name are a module the loader picks one of; and an extension the person typed is stripped rather than doubled. The reason appears in the dialog as the name is typed, and Create is disabled until there is none. **The file is written first and then attached, and a refused attach keeps the file.** The two halves fail for different reasons — the write for the name or the disk, the attach for what the scene or the authoring view will not take — and deleting source code somebody has just asked for because the preview could not load it is destroying the wrong thing. The dialog then says what happened to each half. Once it is written the dialog says so and offers **Open in editor** (`behaviour.open`), which opens the file with whatever this system opens a `.ts` with: Explorer on Windows (which starts the associated program with no console window of its own, exactly as Reveal does), `open` on macOS, `xdg-open` elsewhere, with `code` and `notepad` behind them. It is spawned and let go — waiting on it would freeze the editor behind somebody else's window — and the error names every program it tried, because "nothing opened and I do not know what it looked for" is the unhelpful half of this failing. A gate opens no windows, so it is tested by dispatch alone. **The dialog is in `Shell::modal_open`**, and so is New scene. Neither used to be (wave-2 F10), on the reasoning that Escape in a name field has to leave the field rather than throw away the name typed into it. That is true, and it is not a reason to leave the authoring shortcuts live behind a dialog. `egui::Modal` already stops anything beneath the dialog being clicked; the keyboard gate is `modal_open`, and the only other gate is whether egui wants the keyboard — which goes false the moment a template chip takes the focus off the name field. So with the dialog still up and a chip pressed, Escape cleared the selection, Delete deleted the selected entity, Ctrl+S saved and F5 started Play. Escape is now answered in two stages, the way a running export already answers it: while the name field has the keyboard it leaves the field, and once the field is given up it cancels the dialog. Cancel still closes it. `d9_behaviour.rs` drives both dialogs through the chip and the shortcut table. ### The round trip to Play Saving the scene makes a revision the workspace service builds, and a behaviour file on disk is an input of that revision whether or not the editor wrote it. A build that refuses the TypeScript names the file and the line in the activity feed and on the toolbar already (see [Activity feed](#activity-feed) and `d2_feed.rs`). What neither could say is *which* of the behaviours on the selected entity it is about — so the newest build's first error also appears on that module's own script row, `inspector..diagnostic`, which is `inspector.script.diagnostic` for the first script on the entity. The diagnostic's project-relative path is compared against the module resolved under the open scene's folder, case-insensitively and against both extensions the loader takes, so another module's row stays quiet and a built-in never matches — it is not a file in this project and nothing here compiles it. Fixing the file and letting the next build through clears the row. ### From the Content browser A behaviour in the Content browser is a file a person opens and a behaviour a person attaches, so the tab offers both (see [The Content browser](#the-content-browser)): - **Double-clicking a behaviour opens it** in the system's editor, the way double-clicking a scene opens the scene and double-clicking a model places it. Before this a behaviour tile was the one tile that answered a double-click with silence. - **Open** (`content.open`) serves both roles a person opens: a scene, or a behaviour. - **Attach** (`content.attach`) runs the selected behaviour on the selected entity. It needs both ends and the disabled message says which one is missing. The module name is the file's path under the open scene's own folder, so a behaviour beside a *different* scene cannot be attached from here and says so, rather than writing a module name nothing would load. Both are in the row of verbs as well as in a tile's right-click menu, because a headless gate cannot press an item in a popup menu — the same reason every other Content action is a button. ### Names | Name | Is | |---|---| | `inspector.@add-component` | opens the component catalogue | | `inspector.@add-component.` | adds that kind with the contract's defaults | | `inspector.@add-behaviour` | opens the behaviour catalogue | | `behaviour.catalogue` | the catalogue's surface | | `behaviour.search` | narrows it | | `behaviour.item.` | attaches that module | | `behaviour.new` | opens the New behaviour dialog | | `behaviour.new.name`, `behaviour.new.template.`, `behaviour.new.create`, `behaviour.new.cancel` | the dialog | | `behaviour.open` | opens the file that was just written, in the system's editor | | `inspector.script.diagnostic` | the last build's error for that module | | `content.open`, `content.attach` | the Content browser's two | `crates/editor/tests/d9_behaviour.rs` drives all of it by hit name through the winit boundary, with the workspace service in the test process for the diagnostic. ## Importing models **Import model…** on the toolbar (`toolbar.import`) opens the operating system's file picker filtered to `.glb` and `.gltf`; where the editor links no picker — everything but Windows — the same flow is reached by handing the path to `UiAction::ImportFile`, which is also how the gates drive it. **The file is never rewritten.** glTF has no unit field and no up-axis field, so the import declares both in the scene's asset entry and the runtime composes them into one transform above the loaded mesh (`argus::import_transform`, and `docs/SPEC.md` amendment 15). Nothing is baked into the vertices, which is what keeps the import correct for a skinned mesh, whose vertices are in skin space and whose joints are not. ### What is measured `crate::import::measure` reads the **POSITION vertex data** of every triangle primitive reachable from the default scene — the GLB's BIN chunk, or a `data:` buffer URI in a self-contained `.gltf` — folds each accessor's vertices into one box, and puts that box through its node's world transform before unioning it. Reachability and the node transforms are what `argus::assets::merge_gltf` does when the runtime actually draws the file, so the editor measures what the runtime draws — not something near it. The accessor's declared `min`/`max` is read as well, but only to be **checked**. A declaration further from the vertices than 1e-4 of the box's own size is a warning that names the accessor — "POSITION accessor 0 declared bounds differ from the vertices; the vertices are used" — and the vertices win. A file that declares a 1 cm box over vertices spanning 20 m therefore imports as 20 m, with a box collider 20 m across and a line in the modal saying the declaration was wrong. An accessor whose vertices cannot be read at all — a sparse accessor, or a component type this reader does not decode — falls back to its declaration and says so in the same way. **It is still fast.** Each accessor is read once however many nodes instance it, streamed at its own byte stride and folded into a running min/max with nothing allocated per vertex. The four-megabyte, 243,602-triangle model in `d3_import.rs::probe_a_four_megabyte_model_stays_responsive` measures in **4.2–4.4 ms** and the modal opens in 8.1–8.7 ms; the gate refuses anything over 100 ms. `AssetRef.bounds` and `AssetRef.triangles` are therefore **the source file's own numbers, in the file's own units and axes, before the import transform**. That is what the runtime needs: `targetSizeM` and `baseCenter` are resolved against exactly those, and pre-applying the settings here would apply them twice. Everything a person sees, and everything a box collider is sized from, goes through `import::preview_bounds`, which calls the runtime's own `argus::import_transform` — one implementation, so the editor and the runtime cannot disagree. ### Vertex colours A primitive's `COLOR_0` is drawn. It may be float, or normalised unsigned byte or short, and RGB or RGBA (an RGB colour has alpha 1); `argus_assets` hands it on as linear RGBA in `LoadedMesh::colors`, `merge_gltf` carries it into `MeshData::colors`, and the opaque pass multiplies it into the base colour the way glTF specifies — `baseColorFactor × baseColorTexture × COLOR_0` — and by the entity's tint, for static and skinned meshes and for PBR, unlit and toon materials alike. That is what baked lighting or ambient occlusion, flat-shaded low-poly art and per-vertex tinting need, with no material setting to turn it on. A primitive without `COLOR_0` in a mesh or file where another has it is white — glTF's "no tint" — rather than the column being dropped. A file with no `COLOR_0` anywhere carries no column and draws exactly as it did before vertex colours were read: the GPU vertex gets white, and a tint times 1.0 is the tint bit for bit (`crates/render/tests/vertex_colors.rs` checks that directly, and the render goldens are byte-identical). Only `COLOR_0` is read; `COLOR_1` and above are ignored. On the GPU it is `Unorm8x4`: the vertex grew by 4 bytes (static 48 → 52, skinned 72 → 76), and white packs as 255, which decodes to exactly 1.0. Float and 16-bit `COLOR_0` are therefore quantised to 8 bits per channel; smooth baked lighting across large triangles can show 1/255 steps in the darks. ### What is refused, before anything is copied | Refused | Message names | |---|---| | An `extensionsRequired` this engine does not implement | the extension, what *is* implemented (`argus_assets::gltf_load::IMPLEMENTED_EXTENSIONS`, read from the loader so the two cannot drift), and a way out for Draco, `KHR_texture_basisu` and `KHR_mesh_quantization` | | Geometry in a sidecar (a `.gltf` with a separate `.bin`) | the sidecar, and that a self-contained `.glb` is what to export | | An image in a separate file, **missing** | the image, where it was looked for, and the material and slot that want it | | An image in a separate file, **present** | the same, and that a one-file copy would leave it behind | | Nothing with triangles in the default scene | that there is no size to import it at — this renderer draws triangles, so a points-only file would import as an invisible entity | Every one of these says "Nothing has been copied into the project", because nothing has: the measurement happens first. ### The Import modal `import.*`. It shows the file name, the measured size in the file's own units, the triangle, material and texture counts, and any warnings (non-triangle primitives, meshes outside the scene graph, a skinned mesh whose bounds are its bind pose, extensions used but not required). | Control | Hit name | Does | |---|---|---| | Unit scale | `import.unit-scale`, and `import.unit.{m,cm,mm,in}` | the file's units multiplied by this are metres. No range on the field itself: a zero, or anything outside `[1e-6, 1e6]`, is refused **in words**, with Import disabled, rather than silently clamped. That range is `asset-import-invalid`'s, read from the rule, and it is what a 32-bit transform can hold — a micrometre and a thousand kilometres per file unit | | Up axis | `import.up-axis`, options `import.up-axis.{Y,Z,-Y,-Z,X,-X}` | which axis of the FILE points up. Forward defaults to `Z`, except `Z` up → `-Y` and `-Z` up → `Y`, the convention every Z-up exporter uses | | Target size | `import.target-size.on`, `import.target-size` | scales the longest side to this many metres, after the unit scale | | Base centre | `import.base-center` | puts the origin at the base centre, measured *after* the scale and the rotation, so the floor is whichever axis ended up down | | Collider | `import.collider.{none,box,trimesh}` | **explicit, default none.** A line of text says what a box would be; nothing is ever chosen from it | | Target size | as above | the same range as the unit scale, refused the same way | | After import | `import.after`, `import.size-warning.*` | `X × Y × Z m, Y-up` from `preview_bounds`, live. Over 100 m across warns that the unit scale is probably wrong. Settings that make no usable transform at all — a scale the file's own measurement drives out of range — show the refusal at `import.problem` instead, with Import disabled: the line never reads `NaN × NaN × NaN` | | Import, Cancel | `import.ok`, `import.cancel` | | The modal is modal: while it is up, input reaches it alone (`Shell::modal_open`), Escape cancels it, and no shortcut, camera key or pick goes anywhere else. ### What Import does 1. Copies the file to `assets/` **beside the scene file, wherever that is** — `/scenes/assets/` for the usual `scenes/main.scene.json`, `/scenes/levels/act1/assets/` for a scene three folders down, `/assets/` for a scene at the project root. The path in the asset entry is scene-relative and needs no `..`, and the artifact's staleness check tracks it. A name already taken becomes `-2.glb`, `-3`, and so on, **even when the bytes are identical**: two asset entries sharing one file would mean a reimport of either silently rewriting the other's model. 2. Adds `assets[]` — `kind: "glb"`, the scene-relative `path`, `triangles`, `bounds` (the file's own) and `import` (the source file's name, its SHA-256, the settings and the collider choice). The id is the file stem slugged to ASCII (`Café Chair v2.glb` → `caf-chair-v2`), free as both an asset id and an entity id. 3. Adds an entity with that same id **at the origin**, with a `mesh` component and the chosen collider, and selects it. The origin, not in front of the camera: it is where the person can find it and the same place every time, which is what lets a gate assert the result. 4. Commits all of it as **one undo step**, labelled `import `. The scene must pass the contract, which refuses an absolute or `..` asset path (`asset-path-not-relative`), so the editor never writes one. The model file is written **at import time**; the scene is not written until Save, and the modal says so. Undo takes the entity and the asset entry back out and leaves the copy where it is: nothing references it, so nothing loads it, and a redo finds it already there. ### An import copy is immutable Once the editor has written a model file into `assets/`, it never writes to that file again. That one rule is what keeps undo out of the project's files, and it is why undo is a document operation and nothing more. A **reimport** therefore writes a *new* file beside the scene, named `-.glb`, and points the asset's `path` at it. The name is the content's, not a counter's, so reimporting the same bytes twice lands on the same file instead of piling up `-2`, `-3`, `-4`; and a hash already on the stem is replaced rather than appended to, so a file reimported ten times is still `chair-.glb`. The stem is the asset's current file name, not the source's, so an asset keeps its own name across reimports however the file it was read from is called — `import.source` is what records where the bytes came from. On the vanishingly unlikely eight-hex collision with *different* bytes, the copy takes the next free number instead of overwriting anything. **Undo then writes nothing at all.** It restores the document, the document names the file it named before, and that file is still on disk untouched. The undo stack holds no model bytes: `Document` carries whole-scene snapshots and nothing else, which is also what keeps eight reimports of a 24 MB model from costing 384 MB of undo history (`d3_review_probes.rs::memory::probe_eight_reimports_do_not_hold_the_model_in_the_undo_stack` measures 0 MB). ### Unreferenced model files The other side of that rule is that reimports and undone imports leave files behind. Nothing deletes them on its own. `Editor::orphaned_models` lists the `.glb` and `.gltf` files directly inside the scene's `assets/` folder that **neither the scene being edited nor the scene last saved** names. Both are asked deliberately: a file the working document has stopped naming may still be the one the saved scene loads, and a person who then discards their changes would find it gone. The inspector's asset section shows "N unreferenced model files in scenes/assets" (`inspector.orphans`) with **Delete unreferenced** (`inspector.delete-orphans`) beside it, which deletes exactly that list — recomputed at the moment it is pressed, so a file that became referenced in between is never deleted. It is not an undo step: these are files no scene the editor knows about names, so there is nothing in the document to take back. Disabled during Play, like every other authoring action. It is also **refused outright when the project could not be read in full** — a sibling scene that does not parse (half-written, a merge-conflict marker, a trailing comma) or a scenes folder that could not be listed — and the refusal names the file and says to fix or remove it first: a scene the editor cannot read still owns its models, and "that scene is broken" must never become "so the editor deleted its models". Importing is an authoring action. During Play it is refused ("stop Play first") and the toolbar button is disabled: Play runs a build prepared from saved files, and copying a model in underneath it would change what a restart loads. ### The inspector's asset section For a selected entity with a `mesh`, under the transform fields: the asset id, its path, the source file and hash it came from, the import settings as one line, the post-transform size and the triangle count. - **Reimport…** (`inspector.reimport`) reads a model file into the asset again. On Windows it picks a file; where there is no picker it reads the asset's own file again, which is what a re-export over it needs. The asset id, the entity's transform, every other reference to the asset and every per-entity `material` override survive, because none of them is touched: only `path`, `bounds`, `triangles` and `import` change, and the new `path` is the new copy's (see [An import copy is immutable](#an-import-copy-is-immutable)). `import.sourceSha256` is the field that makes a running world drop its cached mesh, since the hot-reload diff compares `AssetRef` values and not file contents. A file that does not measure leaves the asset **and every file** exactly as they were, and names the reason: the measurement happens before anything is written. One undo step, and undo restores the document alone. - **Collider…** (`inspector.collider.{none,box,trimesh}`) changes the entity's collider, one undo step, and records the choice in `import.collider` so a later reimport can offer the same one. A box is sized and centred from the **post-transform** bounds. A reimport does not resize a collider: geometry a person will stand on is not changed without being asked. - **Reveal** (`inspector.reveal`) copies the model file's absolute path. ### Limits - **No FBX, no OBJ, no retargeting, no PBR authoring.** glTF 2.0 only, as `.glb` or a self-contained `.gltf`. - **One file per import.** A `.gltf` with a sidecar `.bin`, or with images beside it, is refused rather than imported half-copied; export a `.glb` with everything embedded. - **A trimesh collider is previewed only in Play's F1 overlay.** The authoring view draws the mesh, not the collision shape. - **A reimport makes the artifact stale**, because the asset entry changed: Play refuses until the next Save prepares a new build. That is the same rule every behaviour and asset file is under. - **Reimporting the asset's own file cannot undo bytes the editor never saw.** Undo points the asset back at the file it named before; if an authoring tool re-exported over that file, its contents are the tool's and not the ones the restored measurements describe. - **A reimport leaves the previous copy on disk.** That is the point — see [Unreferenced model files](#unreferenced-model-files) — but a project reimported many times accumulates them until someone presses **Delete unreferenced**. - **A reimport costs no memory per round, and both things that used to make it cost are gone.** The undo stack held the model's bytes before and after every edit; it holds whole-scene snapshots and nothing else now. `Renderer::register_mesh` had no counterpart, so `World::reconcile` dropping an asset's `mesh_cache` entry freed the parsed glTF and the CPU geometry while the vertex and index buffers stayed; `Renderer::free_mesh` is that counterpart and `World::free_evicted_meshes` calls it on exactly the meshes the reload evicted, skipping any a draw binding still names. Measured on this machine with the software Vulkan adapter, warmed up with eight reimports and measured over the next eight: a **3.0 MB** model moves the resident set by **0 MB** and a **23.9 MB** model by **1 MB**. With the meshes left unfreed the same runs cost **6 MB** and **48 MB** *per reimport* — 2.1 and 2.0 times the file, every round, for as long as the editor stayed open. What is left is inside the noise of a process that parses a 24 MB glTF between the two readings, which is why the probe's bound is a whole file per round rather than zero. Two probes hold it there: `memory::probe_eight_reimports_do_not_hold_the_model_in_the_undo_stack` isolates the undo stack by reimporting the same bytes, and `memory::probe_repeated_reimports_grow_the_undo_stack_without_a_byte_budget` alternates the geometry so every round really does register a mesh. - **A freed `MeshId` is permanently dead.** Ids are positions in the renderer's list, so a freed slot is a tombstone and is never handed out again rather than coming back attached to different geometry. The tombstone costs a word; a session that reimports thousands of times accumulates thousands of words, which is not a budget anyone will notice. The four builtin meshes are never freed, because every scene shares them. - **`import.collider` is a record, not the collider that runs.** The entity's `collider` component is. ### Scans **Import model…** also takes an `.obj` (with its `.mtl` and textures beside it) or a `.ply`: a photogrammetry or scanner mesh of millions of triangles that cannot be drawn as delivered. The file is **cooked** first, on a thread, behind a small modal with Cancel (`import.scan.cooking`, `import.scan.cancel`); the cook writes nothing. `crates/scan` (`argus-scan`, also a CLI: `argus-scan cook in.obj out.glb`) reads it, welds it, decimates it to a triangle budget (500,000 by default) with meshoptimizer, makes two coarser levels, brings its textures to 4096 px, fits up to 32 convex hulls, and writes **one GLB**: the default scene draws full detail, the coarser levels are `MSFT_lod` nodes outside it, the hulls a mesh named by the root node's `extras.argusCollisionHulls`. The Import modal then opens on that GLB, exactly as for any model, with the cook's report above the settings (`import.scan.N`), **Convex hulls** among the collider choices (`import.collider.hulls`, selected when hulls were made) and **Keep the scan's source** (`import.scan.keep-source`, on). Import is the ordinary one: the GLB copied into `assets/`, the asset and entity added as one undo step. The asset's `import` record names the file picked (`source`, `sourceSha256`) and carries the cook's settings in `import.scan`; the source and its MTL and textures are kept under `assets/scan-src/-/` (never exported, since nothing at run time names them). A scan too large for the scene's asset budget raises `meta.budgets.textureMB` to fit, and says so. **Levels of detail.** The runtime draws one level per entity per frame, chosen by the share of the screen's height the asset's bounding sphere covers (the file's `MSFT_screencoverage`, 0.25 and 0.075 by default) with a 10% band so an object on a switch does not flicker. The same instance rows reach the standard and HD renderers, so both switch. `argus run --lod-freeze N` pins every level for captures; `World::set_lod_bias` moves every switch (a headset renders at 0.5). **The inspector's Scan section** (`inspector.scan.*`), for a scan asset: the triangle, hull and texture numbers and **Reprocess** (cooks the kept source again on a thread and lands as a reimport: a new content-named GLB, identity kept, one undo step); **Ruler** (click two points on the scan, type the real distance; sets `unitScale` and records `import.scan.ruler`); **Align part** (click a point on the part, then the same point on the scan, three pairs or more; moves the part, rigid or with a scale, and reports the RMS residual); **Cut region** (click the scan where a replacement part sits; its triangles inside a box there are removed at the next cook, split cleanly along the box); **Box collider** (click the corners of a bench; a static box collider fitted to the scan) and **Floor and walls** (for a room scan: static boxes fitted to the floor and up to four walls). While a tool is picking, viewport clicks land on surfaces instead of selecting. A Reimport… of a scan asset cooks the picked file (or the kept source) with the recorded settings. **Triangle budget.** An import never changes `meta.budgets.triangles`: the scene's full-detail total against it is in the import's answer (`triangleBudget`: `sceneTriangles`, `budget`, `over`, and a `suggestion` naming the budget that would hold it), for the author or the agent to act on. Agents reach all of it: `asset.import` with a `scan` object, `asset.reprocess`, `asset.ruler`, `entity.align` and `entity.fit_proxies`, and the control actions `import`, `reprocess`, `scan-ruler`, `align`, `proxies` and `surface`. **Collision.** `collider { shape: "hulls" }` is the cooked hulls as one compound body, so a concave scan can be grabbed or placed as a dynamic body and its notches stay open. **CUI.** The cook and the import never use the network. Every cooked GLB records its source's SHA-256 and the settings (`asset.extras.argusScan`), and every kept source folder a `provenance.json`. `argus-scan derived --project ` (also the control action `derived` and the agent tool `asset.derived`) lists every file in the project derived from a source (cooked GLBs, the kept source, byte-identical copies under `.argus/`, the project thumbnail) so they can be purged; a file another scan's provenance claims is never listed, even when two scans share a texture byte for byte. Keeping the source is a choice on purpose: data minimisation says keep no copy unless a re-cook will be needed. `scan-src/` never enters a revision, a build or an export: the workspace service does not read it and the exporter refuses it by name. Untick **Keep the scan's source** to keep no copy at all. ## The Content browser The **Content** tab of the bottom drawer (`content.tab`) is every file in the project, not the open scene's asset map: a folder tree on the left, tiles on the right, and the handful of things a person does to a file. `crate::content_browser`. **What is in the project, and what each file is, are the workspace service's answers.** The walk is `argus_workspace_service::inputs::walk`, the exclusions are its `is_excluded` (`.argus` and every other dot folder, `node_modules`, top-level `target` and `dist`), and the role is its `role_for`. The browser refines that one step further, because a browser has to colour a mesh differently from a texture and a revision does not: the service's single `Asset` role becomes **Models**, **Textures**, **Audio** and **Other**, beside its **Scenes**, **Scripts** and everything else as Other; the table under **Narrowing** has every extension. One more refinement, and the same kind: anything `inputs::ui_role` classifies is **UI** rather than the Behaviour a `.tsx` would otherwise be — see [The UI category and the viewport preview](#the-ui-category-and-the-viewport-preview). Nothing about exclusion or role is decided twice, so a file the browser shows and a file a revision captures can never disagree. **The tree always shows the folder that is selected.** Clicking a folder row selects **and expands** it, as the usual editor's does — somebody clicking a folder is asking to see what is in it — and clicking the folder that is already selected is the press that collapses it again. Whatever else sets the selected folder, a breadcrumb or a script, opens every ancestor of it, so the row a script asks for by name exists to be pressed. **Layout.** A left column of indented folder rows with a painted disclosure triangle where a folder has folders under it, and a tile grid on the right. Above them a compact row of actions, and under it the breadcrumb, the **Filters** button, the search box and a chip for each filter that is on. The actions are on top, which is the usual editor's order and which decides what survives a short drawer: at a small window and a high display scale the drawer can be shorter than its contents, and what a person has to keep is the row of verbs rather than the row that refines a list. The tree's root row is named after the project's own folder, because the breadcrumb beside it already says "Content". **Tiles.** A painted role mark, the name over up to two lines, the size, and along the bottom a role-coloured stripe in the usual editor's convention — levels yellow, static meshes cyan, scripts blue, textures red. A model whose file the open scene already has an asset entry for also carries its triangle count and the size the runtime gives it, which the inspector's asset section computes from the same numbers. The open scene is marked `◎` and the startup scene `★` in the tile's corner, both at once when they are the same file. A tile is `content.item.`, a folder row is `content.tree.`, and the project root's own row is `content.tree`. **A UI screen's tile carries a rendered thumbnail** — a real frame of the screen, drawn by the real runtime. Every other role still carries its painted mark; a model thumbnail is still deferred, since `crates/capture` rendering a one-entity world from four angles is a change of its own. **Narrowing.** The type filter is the usual editor's filter bar: a **Filters ▾** button (`content.filters`) left of the search opens a menu with a check box per type (`content.filters.`) and **Reset Filters** (`content.filters.reset`). Several can be on at once; the menu stays open while they are ticked, as the usual editor's does, and closes on a click outside it or Escape. Each type that is on gets a chip after the search box (`content.filter.`, "Models ×"), outlined in the type's colour; clicking the chip takes that type off. None on is every type, and the button says how many are on ("Filters (2)"). The search (`content.search`, case-insensitive over the names in the folder shown) narrows whatever the filters leave, and a breadcrumb goes back up the path (`content.crumb.`, 0 being the project root). The old Prefabs chip is now the Prefabs row of this menu, one system with the rest. | Filter (key) | Files | Decided by | |---|---|---| | Models (`model`) | `.glb`, `.gltf`, `.obj`, `.fbx` | the service's `Asset` role, by extension | | Textures (`image`) | `.png`, `.jpg`, `.jpeg`, `.webp`, `.ktx2`, `.hdr`, `.exr` | the service's `Asset` role, by extension | | Materials (`material`) | `*.material.json` | `argus_contract::is_material_file_path` | | Audio (`audio`) | `.wav`, `.ogg`, `.mp3`, `.flac` | the service's `Asset` role, by extension | | Prefabs (`prefab`) | `*.prefab.json` | `prefab_ui::is_prefab` (the contract's `source_problem`) | | Scripts (`behaviour`) | `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs` outside `ui/` | the service's `Behavior` role | | Screens (UI) (`ui`) | screens, components, styles, themes, scenarios and locales under `ui/` | `inputs::ui_role`, checked first | | Scenes (`scene`) | `*.scene.json` | the service's `Scene` role | | Other (`other`) | everything else: `argus.project.json`, data `.json`, a glTF's `.bin`, fonts, text | — | The checks run in the table's "decided by" order where two could claim a file: UI first, then prefab, then material, then the service's role. **The choice is the person's**, kept in `layout.json` as `contentFilter` (the keys, in the menu's order; see the layout below), so it survives a restart and follows the person to every project. Agents read it as `editor.state`'s `view.layout.contentFilter` and set it with `editor.set {layout: {contentFilter: [...]}}` (`/v1/do set-view`), in the keys or the menu's words, singular or plural, any case (`["Scripts", "materials"]`); `[]` is every type, and a word that is no type refuses the whole call. `project.files` keeps its own `role` and `prefix` filters, the service's: the browser's types are the editor's reading of those, and a second classifier in the agent crate was not worth the duplicate. **Actions.** Double-clicking a scene opens it, and double-clicking a model places it. Both are also buttons, and so are the rest, because a headless gate cannot press an item in a popup menu: `content.place`, `content.open`, `content.ui.preview`, `content.ui.thumbnails`, `content.reveal`, `content.import`, `content.delete-unreferenced` and `content.refresh` are always drawn and act on the selected tile — the names are the old ones and the labels are short, so that the row fits the narrowest window the editor promises without wrapping onto a line a short drawer would cut off. Right-clicking a tile gives the same items. A model tile is also a drag source carrying a `content_browser::DragModel`; the click path never depends on the drop, and `d6_shell.rs` drives a whole drag through the winit boundary. | Action | What it does | |---|---| | Open | `UiAction::Scene(SceneAction::Open(…))` — the same path the File menu takes, unsaved-work prompt and all (see [Scenes](#scenes)) | | Place | Puts the model in the open scene at the origin, as one undo step. Refused while Play runs, while an unsaved-work prompt is waiting, and when the file has gone since the walk | | Reveal | Shows the file in the platform's file manager (`export::reveal`) | | Import… | Opens the Import modal. The copy still lands in the open scene's `assets/`, because an asset path is relative to its scene and may not climb out of it (`asset-path-not-relative`) — so the folder the person asked from cannot be where it goes. Refused, at the button and at the action, while Play runs or an unsaved-work prompt is waiting: it opens the operating system's file picker, and a second picker over a prompt is worse than a button that says why it cannot | | Generate | Opens the Generate panel (`content.generate`). Disabled, with the reason and what to turn on as its hover text, while the project's `assets.generation.enabled` is not true (`asset_generation::refusal`) | | Generate panel | An in-app window (`generate.window`, closable with `generate.close`) over the asset library CLI, one step at a time: **prompt** (`generate.prompt`), **class** (prop, scenery, vehicle, structure; no character; `generate.class`), **Hero asset** (vehicles always; `generate.hero`) and the project style read-only -> **reuse first** (`generate.search`; matches with thumbnail, score, provenance, licence, visibility, `generate.match..use` imports free, `generate.new`) -> with concept images on, **drafts** (`generate.draft.`), **Change only…** (`generate.change`; no cap on rounds: "Round N" and the concept's running cost sit beside it, `generate.round`), **Approve** (`generate.approve`, records the OS user name; required for hero) -> **3D** and the gate verdict per profile (`generate.verdict.`; each reject with the gate's own `Next:` fix text under it, `generate.verdict..reject.[.next]`; the answer's warnings, `generate.warnings`) -> **Import** (`generate.import`, offered only on a clean pass), then the Content Browser refreshes. The window opens at about 60% by 70% of the editor window, resizable and never larger than it. The verdict step shows a **3D preview** (`generate.preview.image`, `.prev`, `.next`): the generated GLB drawn on the CPU from four turns (`glb_preview`, no window or GPU; the editor has no model-thumbnail path yet), else the gate's own thumbnail or views picture (`generate.preview.source` says which). Each step shows its own cost (`generate.cost.step`, `generate.cost.concept`) and the asset total, `Asset total: US$1.30 (concept 0.20 + 3D 1.10)` (`generate.cost.total`; the CLI's `costUsd` is the two together). Drafts: the highlighted draft is the approved one or none until the person picks (Approve and Apply change wait for a pick). After a gate refusal there is no Import: **Re-check (free)** (`generate.recheck`; `regate {id}`, shows the new verdict; "Re-check is not available in this build" on an unknown-command refusal, `generate.recheck.unavailable`), **Use anyway (warnings)** (`generate.anyway`, only for warnings without rejects, or a pass with warnings; one-line confirmation `generate.anyway.confirm` naming the warnings; `import {id, project, acceptWarnings: true, by: }`), **Change only... on the concept** (`generate.change-concept`: back to the drafts with the approved draft selected, a concept image edit priced by `estimate`) and **Retry with feedback** (`generate.retry`, priced by `estimate`), each with its cost beside it. Every call runs off the UI thread with the step name, elapsed seconds, a spinner and **Cancel** (kills the child; `generate.progress`, `generate.cancel`). Where the project does not ask first, `estimate` is called before a paid step and "This step costs about US$X (summary)" shows while it runs (`generate.estimate`), with no dialog. Before a paid step the CLI's `library-needs-approval` (its `estimateUsd`, `key`, `summary` fields) shows "about US$X" with **Confirm** (`approve`, then the same call once; `generate.confirm`) or Cancel (nothing sent); `library-spend-cap` shows the cap, what is spent and this step's estimate (its fields) and no retry until the spend settings change. A failed step shows the CLI's message and **Retry with feedback** (`generate.retry`). **Pending approvals** (agents' paid steps) list with Approve / Decline (the request whose cost dialog is on screen is not listed a second time) (`generate.approval..approve\|.decline`). With generation off the panel never calls the CLI | | Library tab | Window > Library (`library.tab`) opens the **Library** tab of the bottom drawer: what the asset library already holds, browsable in every project with generation on or off (search, import and rate are free and never generate). A search field (`library.search`, `library.search.go`), a class filter (all, prop, scenery, vehicle, structure; `library.class`) and **Project style only** (`library.style-only`, on by default: the manifest's `assets.style` goes to `search`'s `style` filter; off shows everything, with "not the project's style" on each off-style row). Rows (`library.item.`) show thumbnail, name, class, mean score and count, triangles, provider and model, cost, licence, visibility and style. Selecting one opens its details (`library.details`): every human score with who, when and note, prompt, provider, model, task, date, cost, concept trail (chosen draft, approved by, edits), gate verdict per profile (`library.verdict.`), licence, visibility and content hash, read from the cache's `records/.json` (the CLI has no verb for one full record). **Import into project** (`library.import`, free, offered on a clean pass; an asset the gate rejected shows its rejects with their `Next:` text and no Import, `library.reject.[.next]`; one with warnings only offers **Import anyway (accept warnings)**, `library.import-anyway`, behind a one-line confirmation naming them, `library.import-anyway.confirm`, which sends `import {id, project, acceptWarnings: true, by}`; **Re-check (free)**, `library.regate`, runs `regate {id}` and reads the record again; a shared asset is fetched first; the Content Browser refreshes), **Rate** (`library.rate`: 0 to 10 `library.rate.score`, optional note `library.rate.note`, **Send** `library.rate.send` as the OS user name, the same name as the Generate panel's approval) and **Generate something new** (`library.generate`: opens the Generate panel with the search text as its prompt; disabled with the reason while generation is off). Every call runs off the UI thread; an empty library says so in one line (`library.empty`); a missing CLI shows its error (`library.error`) | | Delete unused | `Editor::delete_orphaned_models`, the same rule as the inspector's: model files under the open scene's `assets/` that no scene in the project names. It walks the project itself before it decides, because a destructive action never reads a cache | | Refresh | Walks the project again | **Place, in three cases and a half.** A model already in the project is not imported again. If the open scene has an asset entry for that file, a new entity simply names it and no second entry is written. If it has one imported from *these exact bytes* under another name, that entry is named too — an asset entry's `path` points at the copy and never at the source, so without this a second Place of the same library model wrote a byte-identical `chair-2.glb` and a second asset entry for one model (`AssetImport.source_sha256` is the comparison, which is what the importer records and what a reimport already compares). If the file is under the scene's own folder, a new asset entry names it by its scene-relative path, with the bounds and triangle count measured from the file and no `import` block — nothing here declared its units, and the inspector says so rather than inventing them. Only a model elsewhere in the project is imported, which copies it in, because an asset path may not climb out of its scene's folder. All three are one undo step through `Editor::commit_scene`, and the entity is the import path's: at the origin, with a `mesh` component and the file's stem for a name. **The manifest is read again when its answer is about to be used.** `Editor::adopt_manifest_if_changed` compares the manifest's length and modified time against what the editor last read and re-resolves the project when they differ; the Export panel calls it as it opens, and so does every frame the File menu is open. Before this the editor adopted the manifest only from its own Set as startup scene, so a manifest changed by the workspace service, by another window or by a `git pull` was never taken while the project stayed open — and the Export panel, which is the last thing a person reads before they ship, then named a scene the export would not pack. A manifest that has changed into one the project resolver refuses leaves the editor holding the last good one and says so on standard error: a bad edit elsewhere must not close the project out from under someone with unsaved work. **One walk, and only when something asks for it.** The browser and File ▸ Open scene read the *same* walk: `Editor::project_tree` and `Editor::scenes` both come from one `content_browser::scan`, so a project with both open is walked once, not twice. Nothing polls. The walk happens again when the workspace service reports a file change, when the person presses Refresh, when the editor itself writes a file (an import, a new scene, Delete unreferenced), and when the File menu is opened or the Content tab comes into view with the walk older than two seconds. Before this, `Editor::pump_service` re-walked the whole project every two seconds on the frame thread for as long as the editor was open — a `stat` per file and a JSON parse of every scene but the open one, about 10 ms at 1,500 files and roughly 100 ms at 15,000, whether or not anything was looking. **A frame's work is what it draws.** The walk builds two indices once: a folder → files map, so a folder's tiles are not a pass over the project, and a folder → subfolders map, so the tree is not quadratic in the number of folders. Each file's name is lowercased at scan time, so a search compares rather than allocating a string per file per frame, and `tiles` makes one pass, stopping one item past `TILES_CAP`. `content_browser::State::scans` counts the walks the browser has adopted and `Editor::project_walks` the walks themselves; `tests/d6_content.rs` asserts neither moves between frames that nothing changed, over a folder of 5,000 files. ### Folders, and moving files `crate::content_folders` for the controls, `crate::relocate` for the move. | Verb | How | Hit names | |---|---|---| | New Folder | right-click a folder in the tree ▸ New Folder (inside it), the project's own row (at the root), or the space under the tiles (in the folder shown). Made on disk at once as `NewFolder` (`NewFolder1`, … beside one), its name open for typing: Enter or clicking away renames it, Escape keeps the name | `menu.content.new-folder`, `content.folder-rename`, `content.empty` | | Rename | right-click a folder ▸ Rename. A folder with files in it is a move of every file in it (below), and its subfolders, empty ones too, go with it | `menu.content.rename` | | Delete | right-click a folder ▸ Delete. Only an empty folder is deleted; one with anything in it stays, and the status line says what is inside ("scenes/models is not empty: it holds crate.glb, … and 3 more") | `menu.content.delete` | | Move | drag tiles onto a folder in the tree. Ctrl+click picks several (drawn selected), and dragging one of them moves them all; any tile can be dragged, and a model's, a prefab's and a screen's still onto the viewport too | `content.tree.` | The tree lists empty folders too (a walk only sees files, so `scan` adds the directories that hold none). A folder is a directory, not revision content: it is made and removed on disk, and the workspace service sees the files that go in it. **A move rewrites every reference to the files moved, or refuses and moves nothing.** What names a file is what the contract and the loaders resolve, each against its own base: a scene's `assets.*.path` (relative to the scene's folder, never climbing out, `asset-path-not-relative`), its `script.module`s (the same folder's `.ts|.js`) and each instance's `prefab.source` (project-relative); a prefab file's asset paths and modules (read from the open scene's folder, where its assets merge); a material's `*Texture` paths (relative to it, never climbing); a `.gltf`'s buffer and image `uri`s; quoted `./` and `../` specifiers and `url(…)` in behaviours, UI files and stylesheets (with or without the extension, `.js` naming a `.ts`); and anywhere in a JSON or text file (the manifest's `startupScene`, a data file), a string that is exactly a moved file's project path. A moved file's own references are rebased the same way. A reference that cannot be written from where the files end up (a model dragged out of the folder of a scene that uses it) refuses the whole move with the file and the field in the status line. The open scene itself cannot be moved. **The open scene is rebased, not edited.** Its references are rewritten in the document, its saved baseline and every step of its history alike (`Document::rebase`): a move adds no undo step, is not an unsaved change, and no undo can bring back a path whose file is gone. Its file on disk is rewritten with the other referrers, and when the document was saved, that file is its saved baseline again, so the move raises no "changed on disk". As in the usual editor, a move is not on the undo stack. **One change set.** With a workspace service (a human's editor, `EditorOpts::human`), the moves (`put-file` at the new path, `delete-file` at the old) and every rewritten file land as one change set under the editor's owner (`Editor::land_files`), which a revert of that change (the service's `POST /v1/changes//undo`, an agent's `revert`) takes back whole. Without one, the new files and rewritten referrers are written first and the old files removed last, so no reference is ever dangling. An agent moves files the same way with `project.files` and `move`, through a running editor's `do: move-files` when there is one. ## The UI category and the viewport preview A project's game UI lives under `ui/` at the project root — `ui/screens/**.tsx`, `ui/components/**.tsx`, `ui/styles/**.css`, `ui/theme/**.css`, `ui/scenarios/**.json` — and the editor gives it a Content browser category, a preview in the viewport, and hot reload. `crate::ui_screen`, `crate::ui_preview`, `crate::ui_reload`. **What it previews is the real game UI runtime.** The screen is described by esbuild, registered through `argus::UiState::screen_from_json` — which is `ctx.ui.screen`'s own path — laid out by Taffy against the project's own cascade, and drawn by `crates/render`'s UI pass into the same offscreen target the authoring view uses. The editor's own interface stays egui; nothing here reimplements a node, a style or a focus rule. §5 says that distinction is the whole point and must not erode, so the two overlays are the only things this preview computes for itself, and both are read straight off the laid-out tree the frame drew. ### The UI category Anything `argus_workspace_service::inputs::ui_role` classifies is one category, the Filters menu's **Screens (UI)** (`content.filters.ui`, its chip `content.filter.ui`). One rather than five, because a person looking for "the UI" is looking for all of it — and a screen must not be filed with the game's behaviours, which is where the service's own `role_for` would put a `.tsx`. A file under `ui/` that is not one of the five roles, a `ui/README.md` say, is not a UI input: it is Other, and it fires no reload. **A screen's tile is a picture of the screen, in the theme the preview shows.** It is described at its default scenario, the project's stylesheets are applied **in the engine's own order** and the theme `settings.ui.defaultTheme` names is applied by name — the same two calls `UiPreview::load_styles` makes, so a tile is never a picture of a theme the preview will not show. The world renders one frame at 1080p — §2.5's reference height, so the tile shows the layout the budgets are measured at rather than one that exists only at tile size — and the frame is read back and box-filtered to a fixed 256 px side into `.argus/editor/ui-thumbnails/`. The authoring world is left exactly as it was found: the screen is popped, the target put back **and the theme the world was on restored**, so pressing Thumbnails while a preview is up does not change the screen under the operator's eyes. **Nothing is rendered while a frame draws.** Rendering a screen is esbuild, an evaluation and a GPU frame, which a `draw` call may not do. A tile with no thumbnail on disk asks for one through `content_browser::Action::RenderThumbnail`, **at most one screen per frame and at most once per screen**, so a folder of screens fills in over a few frames rather than costing an esbuild each in one. A failure is remembered with its reason, so a screen that will not compile is not rebuilt on every frame the drawer is open. **Thumbnails** (`content.ui.thumbnails`) forgets them all, which is what a person presses after editing a stylesheet that changed how they all look. | Action | What it does | |---|---| | Preview | `content.ui.preview`, double-click, or the tile's context menu: shows the screen in the viewport | | Set as the scene's start screen | The context menu, and dropping a screen tile on the viewport: writes `meta.ui.startScreen` — see below | | Render thumbnail | The context menu, for one screen | | Thumbnails | `content.ui.thumbnails`: every screen again | **Dropping a screen on the viewport sets the scene's start screen.** §5 asks for the gesture and the scene contract now has the field: `meta.ui.startScreen`, which `argus::World::load` reads and pushes once the project's screens are registered. **The name written is the screen's own** — `defineScreen({ name })` — and not the file's stem, because only the first is what the screen is registered under; writing the stem would produce a scene that validates, loads and then reports `ui.screen.unknown` for a screen sitting right there. So the file is described first, which is the same describe the preview and the tile already pay for and usually already cached. A second drop of the screen that is already the start screen says so rather than writing an undo step that changes nothing. **The browser says which screen it is.** `content.ui.start-screen` names the open scene's start screen beside Preview and Thumbnails — "Start screen: main-menu", or "none" — and the screen's own tile carries `▶`. The line is right the moment a project opens; the mark needs the file's declared name, which is knowable only by describing it, so it arrives with the tile's thumbnail and a file that has not been described carries no mark rather than a guessed one. ### Describing a screen esbuild, with `packages/ui`'s own JSX flags — the list `argus_host::esbuild_args()` carries and `crates/host/tests/tsx.rs` holds it to — plus `--bundle`, because a project's screen imports `@argus/ui` and its own components and the engine's per-file transpile has nothing to resolve those against. The bundle is then evaluated, and `describeScenario` writes the frozen JSON of `docs/UI.md` §7. **The bundle carries no scenario.** The request — which scenario, and any props from `ui/scenarios/` — arrives as one JSON argument at evaluation time, so one bundle answers every scenario of one screen. That is what makes a `ui/scenarios/**` change cost an evaluation rather than a compile, which is the difference the three reload tiers are named for. A bundle is cached against the screen file's length and modification time and dropped whenever a screen or a component changes. **`ui/scenarios/.json`** is an object of scenario name to props, matched to a screen by file stem — `ui/screens/main-menu.tsx` takes `ui/scenarios/main-menu.json`. A screen's own `defineScreen({ scenarios })` is the default; a file here adds to it and overrides by name, which lets a project keep a screen's shipped scenarios and still preview it against the one awkward case without editing the screen. **Two tools, found the way the engine finds its own.** esbuild through `argus_host::find_esbuild` (`ARGUS_ESBUILD`), and `@argus/ui` through `ARGUS_UI_PACKAGE`, then the project's `tsconfig.json` `compilerOptions.paths`, then `node_modules/@argus/ui`, `packages/ui` or `sdk/packages/ui` walking up from three roots in turn: the project, the editor's own executable, and the directory the editor was started in. The third root is what makes a checkout answer for a project made anywhere — `argus run ~/projects/Course` typed in the repository, and every test that creates a project under the target directory — where before the project had no `@argus/ui`, nothing described, and every screen became `ui.screen.unknown` at run time. **The packed SDK carries `packages/ui`** (`scripts/sdk/pack.mjs` stages the checker, Node, esbuild and the package at `sdk/packages/ui`, every file named in the SDK manifest and covered by its id), so an installed editor finds `@argus/ui` under its own `sdk/` without `ARGUS_UI_PACKAGE`; a pack made before the package was added is refused as incomplete rather than used. **Node is not one of the tools any more**: the bundle is evaluated in process through `argus_host::Host::eval_json`, so opening a screen in an installed editor needs no Node installation. `crates/host/tests/describe_screen.rs` still compares the in-process description against Node's where a Node is present, which is the test that let the subprocess go away — and it spells every path for esbuild the way the describer does, so it runs on a Windows runner rather than tripping over `\\?\C:\…`. A missing tool is a reason shown on the tile and in the preview, not a silent blank. **The package's `exports` map becomes the aliases**, one per entry. esbuild's `--alias` is a path substitution rather than a package resolution, so aliasing the package *directory* rewrites `@argus/ui/components` to `/components`, which is not where the file is — and a screen that imports the component library then fails to bundle. `ui_screen::ui_package_aliases` reads what the package declares (`"."` becomes `@argus/ui`, `"./components"` becomes `@argus/ui/components`) and emits an alias apiece, so the editor honours the package rather than guessing at its layout. ### The preview in the viewport `ui-preview.*`. A bar of pickers above the image, the overlays over it. | Control | What it does | |---|---| | `ui-preview.close` | Back to the authoring view; the screen comes off the stack | | `ui-preview.screen` | What is being previewed, by the name `defineScreen` gave it | | `ui-preview.scenario.` | Describes the screen against that scenario's props | | `ui-preview.theme.` | Re-resolves the cascade against that theme's tokens. No reparse: `Parsed` holds every theme's table. The chip marks the theme the preview is *showing*, which is never inherited — see below | | `ui-preview.scale.` | The player's UI-scale setting (§2.12), 0.75 to 2 | | `ui-preview.locale.none` / `.` | See below | | `ui-preview.resolution.1080p` / `.1440p` / `.2160p` / `.custom` | The size the offscreen target is made at | | `ui-preview.overlay.bounds` | Every visible node's computed border box | | `ui-preview.overlay.focus` | The focusable nodes numbered in Tab order | | `ui-preview.node.` | Every control of the previewed screen, at the rectangle it is drawn at | **The resolution picker owns the target while a preview is up.** The offscreen target follows the viewport panel (`crate::preview::follow_panel`); a preview at 2160p in a 900-point panel must not, or "2160p" would mean "whatever this window happens to be". So `follow_panel` stands down while previewing and the panel scales the image to fit. **A theme, scale, resolution or overlay change is a re-resolve.** `docs/UI.md` §9 says switching theme "is a re-resolve, not a reparse, so it is instant and touches no disk", and §2.8 says a frame that only restyles does not rebuild. `UiPreview::sync` compares what the pickers say against what it last applied: when nothing but those moved, it calls `argus::UiState::set_theme` — which resolves against the token tables the parser already built — and the project's stylesheets are not read, no bundle is built and the tree the runtime holds is the one it already had. Moving the screen or its scenario is what costs a describe. The locale is on the cheap side too, now that it goes through `argus::UiState::set_locale` rather than being resolved into the description. **The preview loads the theme layer in the engine's order, and always applies a theme explicitly.** The default theme is the first `@theme` block the parser meets, so which file is read first decides it. The engine reads `ui/theme/tokens.css`, then the file `settings.ui.defaultTheme` names in `argus.project.json`, then the rest of `ui/theme/**` sorted — `argus::theme_layer_order` — and `ui_screen::theme_layer_order` is a call to that and nothing else. `UiPreview::load_styles` then calls `set_theme` by name rather than inheriting whatever the parser decided, so the chip always has an answer. Only the **theme** layer is reordered, in the engine as in the preview: `@tokens` and `@theme` blocks are token tables, where order decides which table a name resolves against, and ordinary rules are a cascade, where moving one would change what a screen looks like. **There is one order, so there is nothing to warn about.** The preview used to reorder the theme layer for itself and report the divergence in the feed as `ui.theme.load-order`, because the engine sorted `ui/theme/**` by path and `game.css` sorts before `sim.css`. That was a preview deliberately showing a different theme from the game and saying so. The engine orders now, the preview reads the same function, and what you see is what the game draws. A project whose default is not the one it wanted names the file: the design system's gallery names `ui/theme/sim.css`, which is what puts its layer in `docs/UI.md` §10's order. `crates/editor/src/ui_screen.rs`'s `THEME_LAYER` still mirrors `packages/ui/src/tokens.ts` as the documentation of that layer, and `tests/ui_editor.rs` reads the TypeScript and holds the Rust to it, the way `crates/host/tests/tsx.rs` does for the esbuild flags. **The overlays cannot disagree with the picture.** The boxes are `LayoutBox::painted` — where a node is drawn, clicked and navigated to, transforms already resolved — and the order is `argus_ui::tab_order`, the function the runtime's own Tab key calls. Both are read off the same laid-out tree the frame drew. A disabled button keeps its place in the tree and loses it in the order, because the runtime refuses to focus one. **A scripted human can press a real game control.** `ui-preview.node.` is published for every focusable node whether or not the numbers are switched on, and `Shell::on_mouse_button` turns a press there into a `UiEvent` for the runtime's own hit-test rather than into an entity pick. The event is handed to `UiState::handle` rather than queued: `World::queue_ui_event` parks it for `drive_ui_input`, which runs inside `World::step`, and the authoring world is never stepped. **The locale picker moves the runtime's own locale.** A project keeps its translations in `ui/locales/.json`, a flat map of key to string, which the scene's `meta.strings` knows nothing about. `ui_screen::read_locales` folds every file into the shape `argus::UiState::set_locale_overlay` takes — `"." -> text` per translation, plus `"" -> key` per key so the base locale draws the key itself — and `UiPreview::load_locales` installs it. The overlay is merged over the scene's table and survives the per-frame `sync_hud`, so `UiState::locales` lists the project's languages and `UiState::set_locale` accepts them. Picking one is then the same call `POST /ui/locale` makes and the same one a game makes. **So a language switch is a re-resolve, like a theme switch.** The description is registered with its `textKey`s intact, the runtime holds the keys, and moving the picker re-resolves them in place: no describe, no re-register, no tree rebuild. `tests/ui_editor.rs` asserts all three counters hold across the switch. This used to be the one picker where §5's "what it previews is **the real game UI runtime**" was untrue — the preview rewrote every key into a literal before registering, which left the runtime nothing to re-resolve and made a language change cost a full re-register. With `keys` chosen the preview shows the keys, which is what the game draws with no table loaded; that is the base locale plus the key-to-key entries, not a second code path. **A key no locale file mentions renders as `[[key]]`**, §2.11's convention for a key with no string, so an untranslated label is visible rather than indistinguishable from a translated one. A locale file that will not read or parse is a `ui.locale.unreadable` diagnostic naming it, in the feed with the rest; the locales that did read stay in the picker. **`ui/locales/**` has no `UiRole`**, so a translation edit on its own fires no hot reload. The tables are re-read on any sync that describes, and on the cheapest reload tier (`UiReload::Scenarios`), which covers the two folders a person edits without touching a screen. ### Hot reload `crate::ui_reload`. The paths one change set carried go to `argus_workspace_service::inputs::ui_reload_for`, which answers with the strongest reload they require — `Screens` beats `Styles` beats `Scenarios` — and the editor does exactly that. The ranking is not decided twice. | Reload | What happens | What survives | |---|---|---| | `Styles` (`ui/theme/**`, `ui/styles/**`) | The stylesheets are reparsed and the sheet swapped | Focus, scroll position, an open dialog, every binding. §5 states this as a requirement, and it holds because swapping the sheet is all that happens: no screen is re-registered, so no tree is rebuilt | | `Screens` (`ui/screens/**`, `ui/components/**`) | The bundles are dropped, the screen is compiled again and re-registered | Hover, press and focus by id. State only while the props shape is unchanged | | `Scenarios` (`ui/scenarios/**`) | The mock data is re-read and the picker refreshed | Everything: nothing is recompiled and no sheet is reparsed | **It rides the polling path, not a watcher.** `crates/workspace-service/src/external.rs:4-7` records that Windows delivers no events for files on the WSL path and inotify inside WSL does not see writes made from Windows to `/mnt/c`, so the service polls and journals what it found. The editor reads those paths off the journal into its feed (`FeedStore::take_ui_changes`) and hands them here, once per change set. §5 is explicit that UI hot reload has to ride that same path "or it will silently fail to fire on the user's own machine". **A failed reload keeps the working screen.** A stylesheet with a refused declaration, or a screen that stops compiling, leaves what is on screen where it is and reports the reason — with the file, the line, the column and the nearest supported alternative that §2.2 requires (`ui_screen::UiDiagnostic`). A blank viewport is worse than a slightly stale one. **Every diagnostic and every reload reaches the activity feed.** §5 asks for the diagnostics to be there "with file and line and click-to-source, exactly as script errors do", and a script error is a row with a file link — so a UI diagnostic is the same row. `Editor::report_ui_diagnostics` runs once a frame and writes one per stylesheet refusal, screen that would not compile, described-screen warning, refused binding and runtime diagnostic; the file and line become the link a person presses. `Editor::reload_ui` writes what the reload did, in `Reloaded::label`'s words, with the files it touched as links. **The diagnostic list is the last set, not a log.** `UiPreview` holds what the last parse and the last describe raised and nothing older: a reload replaces the set, `report_ui_diagnostics` drains it into the feed and hands it back marked, and nothing is written to the feed twice. Six reloads of one broken stylesheet therefore leave six feed rows and one list, where the list used to gain a copy per reload for as long as the editor was open. **A changed props shape is announced.** §5 promises state is kept when the props shape is unchanged and says nothing about the other case, where a screen gains a required prop that no scenario supplies and JavaScript interpolates `undefined` into a sentence the player reads. The description is read before it is registered, the three spellings a missing value has — `undefined`, `NaN` and `[object Object]` — become `[[…]]` holes in the `docs/UI.md` §2.11 convention, and each raises a `ui.screen.props` diagnostic naming the node, the scenario and the text. A whole word only: a literal with "undefined" inside a longer word is left alone. ### Screens in Play **The engine registers a project's screens itself now.** `World::load_ui_screens` describes every `ui/screens/**` through `argus_host::screen::Describer` — the same describer the preview and the tile use, so what Play registers and what the editor draws are one description — and registers each through `UiState::screen_from_json`, which is `ctx.ui.screen`'s own path. A behaviour can then `ctx.ui.push("main-menu")` by name in a Play session, in `argus run`, and in an exported build; this used to be the editor standing in for a hook the engine did not have, and it is not any more. `meta.ui.startScreen` goes up straight after, before `wire_all`, so a behaviour reading `ctx.ui.stack()` in `init` sees what the scene asked for rather than racing an empty stack. **What a screen that cannot be described costs is a named error, not silence.** A machine with no esbuild or no `@argus/ui` records one `ui.screen.tools` error rather than one per screen, a screen that will not compile records `ui.screen.compile` naming the file, and a `meta.ui.startScreen` nothing answers to records `ui.screen.unknown` naming the screens that did register. All of them are `ScriptError`s, which `argus run` prints, a test asserts on and `GET /events` carries — and `fixtures/starter-course`'s `course.ts` catches `ui.screen.unknown` and carries on with the HUD either way. Finding `@argus/ui` is therefore the difference between a project's screens existing and not; see "Describing a screen" above for the three roots it is looked for under. ### The Collection course's screens `fixtures/starter-course/ui/` — and the same files in the bundled template, byte for byte, which `tests/template.rs` checks the way it checks the scene. `main-menu.tsx` (start, restart, exit) and `results.tsx` (pass or fail, the score and the time), a `sim` theme binding the eleven reserved semantic names, two stylesheets in the documented CSS subset, named mock data, and English and French locale tables. `course.ts` puts the menu up at the start of a run and pushes the results screen when the player leaves by the exit, through `ctx.ui` and by name; it never imports a screen and never walks one. `fixtures/walkthroughs/ui-preview.txt` drives the whole preview on the desktop, and `tests/ui_editor.rs` runs the same file headless through the same `Shell` calls. ## The Output Log The usual editor's Output Log. **Window ▸ Output Log** (`menu.window.log`) opens the **Output Log** tab of the bottom drawer (`drawer.tab.log`, also `log.tab`), and the status bar's **Log** button (`status.drawer.log`), as the usual editor's bar has one. `crate::output_log`. **What is in it.** One line per message, each with a time (UTC, `12:03:04.123`), a category, a severity (verbose, info, warning, error), the text, and an entity and a file when it names them: | category | what writes it | |---|---| | `editor` | every message the editor wrote to stderr (or `--log-file`) before saves, imports, opening and stopping Play, refusals, an action that failed. Written through `log_line!`, which is `eprintln!` plus the log, so stderr and the log file keep every word they had | | `engine` | Play starting (what it runs and from where), and the UI diagnostics the preview and a running game raise (`ui.css.*`, `ui.describe.*`, … with the file and line) | | `service` | starting, reaching and stopping the workspace service, and what it refused | | `build` | the service's journal: each build going Ready, Failed (with its reason) or Superseded, and each diagnostic a build recorded, with its `location` as the file and line and its entity | | `script` | a running game's behaviours, read from the Play world after each of its frames. Script errors (`World::errors`): the entity, the module, the phase, the thrown message, whether the behaviour was disabled; the entity and the behaviour's file as links, and for a `.js` behaviour the line the stack names. `ctx.log` lines (info, with the data argument) and script warnings (`null-handle`, with the module's file) from `World::script_output`, the newest 512 the engine keeps; ctx.log's severity maps onto the line's, so `console.warn`/`console.error` show as warning/error once the engine has them | | `critic` | check results (`check passed/failed: summary`) and the diagnostics a check recorded | Journal history from before the editor started is left out: the log is this session's, and the Activity feed is the project's history. **Controls.** A chip per severity (`log.severity.`, errors and warnings with their counts) and per category (`log.category.`), a search box (`log.search`, case-blind over the text, the entity and the file), **Clear** (`log.clear`) and **Follow** (`log.follow`). The view follows the newest line; scrolling up pauses it, and scrolling back to the end or pressing Follow resumes it. Rows are `log.row.`; a line's entity is `log.row..entity`, which selects it as the Outliner does, and its file is `log.row..file`, which switches the drawer to Content with the file's folder open and the file selected. **Bounded, and cheap with a full buffer.** The log keeps 10,000 lines (`output_log::CAP`) of at most 2,048 bytes each; the oldest go first. It is process-wide, as stderr is, so it outlives a project closed and another opened. The tab keeps the ids that pass its filter and adds only the lines that arrived since each frame, rebuilding them only when the filter changes or the log is cleared, and draws only the rows on screen (`ScrollArea::show_rows`). `tests/d18_log.rs` measures it with the buffer full. **Parity.** An agent reads the same lines through the same filter: `POST /v1/log` on the control endpoint, which an agent reads as `editor.state {log}` ([AGENT.md](AGENT.md)), with `after` as a cursor. `shown: true` reads through the filter the person has on. Clear clears the stream for both; ids never repeat, so an agent's cursor stays good across it. `GET /v1/state` carries `log: {last, lines, errors, warnings}`. **Not in it (yet).** Scripts have no `console` global: a behaviour calling `console.log` throws a `ReferenceError`, which does reach the log as a script error. A `.ts` behaviour's error has no line link, because it runs as esbuild's output with no source map and the stack's line is the compiled file's. The engine's own `argus:` stderr lines (a navmesh rebuilt, a reload) are not captured. ## The Undo History The usual editor's Edit ▸ Undo History. **Window ▸ Undo History** (`menu.window.history`) opens the **Undo History** tab of the bottom drawer (`drawer.tab.history`, also `history.tab`). It has no status-bar button: the bar is full at 150 %, and The usual editor's has none either. `crate::history_ui`. **What it lists.** Every step the shown document's undo and redo hold (up to `UNDO_CAP` each) and every change another writer landed that the editor folded in (`Document::apply_external`, up to `UNDO_CAP`), newest at the top, in the order they happened (`Document::history`). Each row is the time (UTC, as the Output Log's), what the step did in words, and who made it: **You** for the person at this editor, an agent by the display name presence has for it (else its own name, else its id; the id is in the tooltip), the workspace service, or a change from outside the editor. The **current position** is the newest step that is done, marked with `›` on a highlighted row; the steps after it, the redo side, are greyed. Below them all is **Start of history**, before every step. | Edit | Row | |---|---| | a move, a drag or typed transform, over one or many | Move Crate, Move 12 entities | | rename | Rename Goblin to Grunt | | duplicate, delete, cut, paste | Duplicate 2 entities, Delete Crate, Paste 3 entities | | Details property rows, over one or many | Edit speed on Goblin, Edit speed on 40 entities | | folders | Create folder Monsters, Move Goblin to folder Monsters, Rename folder A to B, Delete folder A | | prefabs | Create prefab Crate, Place prefab Crate, Apply prefab Crate, Revert prefab overrides on Crate | | import, place, discard, restore autosave | Import tree.glb, Place tree.glb, Discard changes, Restore autosave | | an agent's scene through the editor | its own label ("Move box-b") under its name | | another writer's change folded in | Rename Orc to Brute, Add Crate, Delete Crate, Edit Crate, Edit 3 entities, Edit scene settings | **External changes are not undone from here.** Undo belongs to the person (see [Editing the scene](#editing-the-scene)): an agent's change folded in from the journal never enters the undo stack, and nothing the person undoes or redoes takes it back. The panel still lists it where it happened, so a person reads an agent's work in order with their own, marked `· external` with the reason in its tooltip ("Undo and Redo leave it as it is; revert it from the Activity feed"). **Jump.** Clicking a row undoes or redoes, one step at a time, until the history stands just after that row (`Editor::history_jump`, `UiAction::HistoryJump`): one click, several steps, as the usual editor's does. A click on an external change lands just after it (the person's steps before it done, those after it undone); Start of history undoes everything listed. Each step is the plain Undo or Redo, refused on the same terms — another writer's later change to what it touched, or a prefab file changed since Apply — and the **first refusal stops the jump there**: what was already undone stays undone, and the panel's top line (`history.note`, whole on hover) and the toolbar say how far it got and why ("the jump back stopped after 2 of 3 steps: cannot undo "move #goblin": #entity/goblin was changed by agent Layout since …"), until the next jump. A new edit ends the redo line, as it always has. **Names drawn.** `history.rows` (what of the list can be pressed), `history.row.` for each row on screen (`history.row.0` for the start) and `history.note`. The rows are drawn with `ScrollArea::show_rows`, so only those on screen are published. Five drawer tabs do not fit the strip at 200 % of 1280x720 (the drawer under the viewport is about 370 points): there the strip uses the status bar's short names (`DrawerTab::bar_label`), and below the promised window size it scrolls sideways rather than running under Hide. **Parity.** `editor.state` answers `history: {current, total, steps}`, the newest 50 (`history_ui::DEFAULT_LIMIT`) first, each `{index, label, actor: {kind, id, name}, at, undoable}` plus `redo: true` on the greyed side and `why` on an external change; `editor.state {history: N}` reads N (`POST /v1/history {"limit": N}`), and `GET /v1/state` carries the same `history`. An agent jumps with `editor.set {history: N}`, which is `/v1/do {"do":"history-jump","index":N}` and answers `moved`; a stopped jump is the refusal, with the same words. `index` counts from 1 per document and is never reused, so the index an agent read still names that step after more are added; Reload and opening another scene start a new history. See [AGENT.md](AGENT.md). ## The Profiler Window > Profiler (`menu.window.profiler`, also `profiler.tab`) opens the **Profiler** tab of the bottom drawer (`drawer.tab.profiler`; "Prof" on the crowded status bar and the compact strip). It reads the flight recorder: the last few seconds of timed spans that the running game records into a fixed ring at a cost of a few microseconds a frame. Nothing is recorded, saved or sent by looking at the tab; while it is open and a game runs it copies the newest 240 frames five times a second. - **The headline** (`profiler.bound`): what the frames are bound by (CPU script, CPU physics, CPU render, GPU with the pass, or paced by vsync), the frame cost and its p95, and the top finding of the analyser (`GET /profile/explain`'s first). With nothing running it says to play. - **The frame-time strip** (`profiler.strip`): a column for each frame, height by cost on a linear scale that follows the 99th-percentile frame of the window (never less than 25 ms), with the 16.7 ms budget line drawn over the bars (and 33 ms when it fits), coloured by what dominated it (script, physics, render, GPU). An ordinary frame sits well under the budget line and a hitch towers over it; a bar taller than the scale is cut off at the top with a white cap. A frame far above its neighbours is a **spike**: a red mark under the cap, and its own `profiler.strip.spike.` control. Pressing the strip, or a spike, selects that frame and **freezes** the strip so the frame stays under the pointer; Follow (`profiler.follow`) puts the newest back. The rule is the same one that saves a capture on its own: over 2.5 times the median frame and over it by 2 ms, or over 33 ms. - **The timeline** (`profiler.timeline`, mode `profiler.mode.timeline`): the selected frame's spans on one clock, a row per depth on each track: Main (the frame and tick, the phases, each behaviour call), worker threads, GPU (one span per pass, when the run has GPU timestamps), present and load. Hover names a bar, its length and, for a behaviour, its entity; **pressing a behaviour bar selects its entity** in the viewport and Outliner. `profiler.bar.` is the widest bar of each name. - **The flame graph** (mode `profiler.mode.flame`): the same spans merged by path over the frames shown, the widest child first; `profiler.flame.`. - **Capture now** (`profiler.capture`, while playing): saves the ring as a capture under `.argus/profile/`. The editor also saves one **on its own** when a frame spikes, and the status bar shows `Spikes N` (`status.profiler`) while a game runs and has hitched; pressing it opens this tab. The newest 8 captures are kept. - **Source** (`profiler.source`) picks the live ring or a saved capture (`profiler.source.pick.`), so a spike can be read after the game stopped. **Compare with...** (`profiler.compare`, items `profiler.compare.pick.`) draws the shown window against a capture: a before strip and an after strip, the frame cost change with its noise band, and the spans that changed significantly (`profiler.diff.row.`), green for faster and red for slower. - **Heat** (`profiler.heat`, while playing) tints each entity's bounds in the viewport by what it costs, one metric at a time: Script (ms per tick), Triangles or Contacts (`profiler.heat.metric.`), cold blue to hot yellow, entities that cost nothing untinted. **Surfaces** (`profiler.heat.surfaces`) also paints the meshes themselves in the standard renderer's Cost view (every surface its heat colour, the rest dark grey); the HD renderer does not read the view-mode flag, so there the boxes are the whole map. The map turns the draw counters (`POST /profile/detail`) on while it shows and off when it closes. - **Play records its input.** Every Play that starts from the authored scene writes `session-.replay` beside the captures (the newest four are kept), so a capture has a **replay recipe**: `profile.diff` (or `POST /profile/rerun`) can replay that run against the project as it is now and check a fix like for like. A Play restored from a snapshot cannot be replayed from load; its captures say so. - **F3 in the game window** shows two more rows under the stats when the recorder is on: what the last frames are bound by with the top finding, and the last 48 frames as a strip of characters (`.` cheap to `@` costly, `!` a spike). The pictures are laid out by `argus_profile::layout`, and drawn a second time, with no window and no GPU, by `argus_profile::raster` for the query API's `GET /profile/image?kind=strip|timeline|flame|heat` and the `profile.view` tool; a test puts the editor's bar list beside the rasteriser's. Files: `crates/editor/src/profiler.rs`, `crates/profile/src/layout.rs`, `crates/profile/src/raster.rs`, `crates/app/src/profile_image.rs`; tests `crates/editor/tests/p7_profiler.rs`, `crates/app/tests/profile_image.rs`. ## The Input table **Window ▸ Input** edits the open scene's action map, `meta.input` ([`docs/INPUT.md`](INPUT.md)), as a table (`crates/editor/src/input_ui.rs`). - **Contexts** down the left. The radio marks the one live when the scene loads (`active`); Rename (or a double-click) renames one in place, and Enter keeps the name; × deletes one with its actions; the field below adds one. Click a context to show its actions. - **Actions** of that context on the right, one row each: name, kind (button, axis1, axis2), keys, gamepad, and the kind's options (toggle on a button; mouse, deadzone and sensitivity are shown and edited in JSON). The row below adds an action by name and kind; × removes one; Rename (or a double-click on the name) renames one in place with its bindings, Enter keeps the name, and a name the context already has is refused. - **Keys.** Click a key and press the new one, as Editor Preferences ▸ Keyboard Shortcuts does: while the slot waits, no shortcut runs and the game hears nothing, and Escape on its own gives up. Modifiers are keys here (a game binds LShift). An axis takes its keys a set at a time, shown with `|` between sets: four for `axis2` (up, left, down, right, the tooltip says which), two for `axis1` (negative, positive). "+ set of 4" waits for four presses and adds them as one change; × beside a set removes it. A slot waiting for a key also takes a typed name (for Escape, which the press cancels on), in any spelling the key list answers to; it is stored in the engine's. - **Gamepad** is a dropdown of every source the contract takes (`GamepadBinding`), or none. - **Shared keys.** Two actions of one context on one key or one pad source are allowed, as the engine allows them, and each is named above the table ("Shared: LShift drives dash and sprint") with the key drawn in the warning colour. - **Refused.** A typed name that is not a key, or a pressed key the engine has no name for (Home, a numpad key), is refused in the contract's own words and nothing changes: `input-key-unknown: "Back" on gameplay.jump is not a key name, so it binds nothing; it is a pad button: write "gamepad": "select"`. A change the contract refuses for another reason is refused the same way, with its message. - **Undo and save.** Every change is one undo step through the scene edit path (it is in the Undo History, Ctrl+Z takes it back), and Save writes it. The table shows the map the scene plays: its own actions over the project's (Project Settings › Input), or the built-in map when the project has none. **Over a project map a change writes only what it changes** — the one action, keyed by context and action name, and `active` if that changed (`input_ui::scene_delta`) — so a later change to any other project action still reaches the scene. A scene cannot take away a context or an action the project has (the merge would add it back): removing or renaming one is refused and says so. Without a project map the first change copies the built-in map in, as before. The table is read-only during Play: Play runs the saved scene. **Two maps.** The table edits *an input map at a JSON pointer* (`input_ui::InputTarget`): the open scene's `/meta/input`, or the project's default map, `/input` in `argus.project.json`, which [Project Settings ▸ Input](#project-settings) draws. Where each is read and written is an `input_ui::Maps`: the editor for the scene's (one undo step each), the settings page for the project's (typed, sent with Apply). The edits, key checks, capture and drawing (`input_ui::table`) are shared. Window ▸ Input is not drawn over Project Settings, whose table has the same names. **Parity.** An agent edits the same map with `scene.patch` on `/meta/input`; no tool of its own. Each control is named `input.*` in `editor.controls` (`input.action.jump.key.0`, `input.action.jump.gamepad.north`, `input.context.menu.rename`), so `editor.click` and `editor.key` drive the table as a person does. ## Exporting a game **Export…** on the toolbar (`toolbar.export`) opens the Export panel: one branded executable a person with no Talos can double-click. The installed editor has no cargo, no Node and no checkout, so nothing here builds anything — the two binaries an export is composed from are installed beside the editor, and the composition itself is `crates/export` running in this process (`docs/EXPORT.md`). **What is exported is a revision, not what is on screen.** The workspace service turns each save into a revision and builds it; the panel exports the last build it found **Ready**, and says so by name. Two directories are read, both the service's: the revision's read-only snapshot (`.argus/snapshots//`) for the manifest, scene, icon and assets, and the build job's output (`.argus/jobs//out/modules/`) for the behaviours that build transpiled. Neither is the authored tree, so nothing typed since the build can reach the executable, and "this file is exactly revision X" holds by construction. Nothing is transpiled at export time: bytes no build ever checked do not go into a game. **With no Ready build, Export is refused in the build view's own words** — "Failed — scenes/jump.ts:5:19", "No workspace service: builds are not checked here" — rather than in a second vocabulary for the same fact (`BuildsView::export_blocked`). **What is left out is said, not implied** (`export.excluded.`). Unsaved changes to the scene get a line naming the file and the revision that *is* being exported; a build still running for a newer revision gets a line saying which build this is instead; an edit the service is still waiting to settle gets a line naming the files; and files changed outside the editor that are waiting for an explicit Apply get a line naming them and sending the person to the feed, where the Apply is ([Activity feed](#activity-feed)). **Branding is shown and never edited here** (`export.branding.*`): display name, executable name, version, build number and icon, read from Project Settings through the same `SettingsBackend` the settings section edits, with **Edit in Project Settings** (`export.settings`) closing the panel and bringing that section into view. Two places to change one name is one place too many. **The destination** is a folder (`export.destination`, with **Browse…** where the editor links a picker — Windows), defaulting to `dist/` beside the project. The executable is named from the manifest's `executableName`. A folder that is not there yet is created by the export; a path that is a file is refused. **The job runs on a thread** and reports through a channel, as the service link does: the panel drains it each frame, so nothing about an export that reads every asset and hashes a whole executable happens on the UI thread. Progress is by stage (`export.stage`, `export.progress`) — checking the inputs, verifying the launcher, reading the engine, collecting files, writing the icon and version, building the payload, composing, verifying, putting it in place — with a file count and the file being worked on inside the long one. **Cancel** (`export.cancel`) sets a flag the composer checks between stages and inside the asset loop; the panel goes on saying "Cancelling…" until the composer answers, because saying "cancelled" while a thread is still writing would be untrue. **On success** the panel names the file, its SHA-256 and its payload id (`export.done`, `export.sha256`, `export.payload-id`), and offers **Open Output** (`export.open-output`), which shows the executable in the file manager and never runs it. The payload id hashes the revision, artifact and build ids along with the content, so the executable reports which build it is out of its own bytes. **On failure** the panel shows the stable code and the message (`export.error`: `binary-mismatch`, `size-gate`, `verify-failed`, … — the codes `docs/EXPORT.md` lists), and states that a previous export at that path was not touched (`export.untouched`). That is a fact about the mechanism, not a hope: the executable is composed under a temporary name beside the destination, read back and verified, and renamed over the destination only then. **The two binaries.** The deploy engine (`argus-deploy-engine.exe`) and the launcher template (`argus-launcher.exe`) live beside `argus-editor.exe`, where `scripts\windows\install-editor.ps1 -Deploy … -Launcher …` puts them, each with its SHA-256 recorded beside it as `.sha256`. The editor reads the launcher and checks it against that recorded hash **by its bytes** before composing, so a swapped or corrupted launcher is caught rather than shipped. Neither missing binary is built on demand: the panel says which file is missing and which flag installs it. ## Restart state `/.argus/editor/state.json`, schema version 1, written atomically (write beside, rename over; on Windows a replace refused with `Access is denied` is retried up to 40 times 25 ms apart, about a second, before it fails) 250 ms after the last authoring change, on every Play snapshot save, and on close: | Field | Meaning | |---|---| | `schemaVersion` | `1` | | `projectId` | the manifest's `projectId` when written; a state file from another project is ignored, with a note | | `camera` | `target`, `yaw`, `pitch`, `distance`, `fovYDegrees`, `speed`, and `projection` and `orthoHeight`; a camera outside the editor's limits is ignored | | `selection` | stable entity ids; ids the scene no longer has are dropped, with a note | | `viewport` | the viewport's `mode` (lit, unlit, wireframe), `show` flags and `gameView` ([Viewport modes](#viewport-modes)); absent reads as the defaults. The camera's `projection`, `orthoHeight` and `speed` are in `camera` | | `gizmo` | the transform gizmo's `tool`, `space`, `pivot`, `gridSnap`, `grid`, `angleSnap`, `angle`, `scaleSnap`, `scale` ([Transform gizmos](#transform-gizmos)); absent reads as the defaults, and values outside the limits are ignored, with a note | | `views` | by scene path, the `hidden`, `isolated` and `locked` entity ids of that scene's authoring view; left out when nothing is hidden or locked. An editor from before this change refuses a file that has it (unknown field) and opens with defaults, with a note | | `lastArtifact` | the artifact the authoring view showed; reopened if it still matches the sources, otherwise a new one is prepared, with a note | | `lastSnapshot` | the last Play snapshot saved on purpose, project-relative | | `savedAtMs` | milliseconds since the Unix epoch | An unreadable or foreign state file never stops the editor opening: it opens with defaults and `Editor::reopened().notes` says what was ignored and why. Play state is never restored implicitly: Play always starts fresh, or from a snapshot the human chooses (F6). There is no player save system. Also under `.argus/editor/`: `artifacts//` (`artifact.json`, `inputs.json`, `scene.json`), `snapshots/`, `captures/`, `workers//`, and `sessions.json`, the session registry when no workspace service is the authority (see below). When the editor opens without a service, any session a previous editor process left non-terminal — a crash mid-Play, a killed editor — is marked `interrupted` ("the editor process that owned it ended") rather than left `running`. ## The workspace service ### Placement The editor runs on the operating system that owns the project's files, as the workspace service does. `OpenProject::open` asks the service crate's rule (`argus_workspace_service::placement::placement`, which decides by file-system identity, not by spelling) before it reads or writes anything, and refuses a project on the other OS's file system (`wrong-os-for-project`) or one whose file system it cannot identify (`placement-unverified`). `argus-editor ` opens the project before its window, so a refused project shows no window and writes nothing under `.argus/`. A project under WSL is edited by an editor running in WSL; a Windows-native editor refuses `\\wsl.localhost\…`, and a Linux editor refuses a project on `/mnt/c`. ### The service on the desktop A developer runs `argus-workspace-service serve --project ` in a terminal. Someone who opens the editor from a desktop shortcut has no terminal and no reason to know the service exists, so **the editor starts one itself** (`crate::supervise::Supervisor`). Without it there is no activity feed, no jobs panel, no build states and no session authority — the half of the editor that managed sessions are about. **When.** Opening a project, before `Editor::open`, so the editor's own open-time discovery finds it and takes its journal as the session authority for the run ([Session authority](#session-authority)). Closing the project stops it: returning to the launcher stops it and opening the next project starts one for that root. The order is deliberate — the editor closes first, because closing posts the run's last session records to the service. **What it starts.** `argus-workspace-service serve --project --no-selection`, as a child process, on an ephemeral port. The build pipeline runs (never `--no-build`): Ready is the service's Ready, which is what the toolbar shows. `--no-selection` keeps a service the editor spawned from changing the person's remembered project outside the project folder; the editor has its own recent-projects list. On Windows the child is started with `CREATE_NO_WINDOW` through `worker::no_console`, so it can open no console window and take no foreground. **Which binary.** `$ARGUS_WORKSPACE_SERVICE` when it is set, otherwise beside the editor's own executable: the multi-call `argus[.exe]`, run as `argus workspace-service serve …` (an install has one, and its `argus-workspace-service[.exe]` is only a small forwarding stand-in, `docs/INSTALL.md` "One executable for the tools"), or a real `argus-workspace-service[.exe]` when that is what is there (a checkout's `target` folder) — which is where `scripts\windows\install-editor.ps1 -Service ` puts it, with its SHA-256 recorded beside it as the editor's is. With neither, the editor says so, naming both places, and runs without a service. The installer warns when it has none to bundle. **The log.** The service's standard output and error are appended to `\.argus\editor\service.log`, moved aside to `.log.1` past 8 MB, as the editor's own log is. When that file cannot be opened — a read-only `.argus\editor`, for instance — the service still starts, its output is discarded, and the editor says which file and why. **It never touches a service it did not start.** If one already answers for the project — the CLI, CI, another editor — the editor uses it, starts nothing, and leaves it running at close. Two editors on one project are therefore the second adopting the first's service. The discovery file is removed on stop only while it still names the instance the editor started. **Stopping.** The service has no shutdown request: it stops on Ctrl-C or SIGTERM. So the editor sends SIGTERM and waits up to five seconds for the service to close its workspace, then terminates it. On Windows there is no SIGTERM, and a windowless child shares no console to be sent Ctrl-C on, so the process is terminated and the editor removes the discovery file the service had no chance to remove itself. The service takes no parent pipe, unlike a test worker: **an editor that is killed outright leaves its service running**, and the next editor adopts it. **A WSL project opened from Windows.** Refused, by the same placement rule as everything else ([Placement](#placement)): a Windows-native process cannot be the writer for a project on the WSL file system, so it does not start a service for one either. In practice `argus-editor.exe <\\wsl.localhost\…>` never gets this far — the project itself is refused before the window. Where a project opens but placement will not have this process serve it, the editor opens with no service and says which refusal it was (`wrong-os-for-project`, `placement-unverified`). Run the editor, and its service, on the operating system that owns the files. **Opting out.** `--no-service` on the command line, or `ARGUS_NO_SERVICE=1` in the environment. Either way the editor does exactly what it did before it follows a service that is already running and starts none. A refusal is never fatal — the editor opens, and the reason goes to its messages (stderr, or `--log-file`), not to the launcher's error line, which belongs to a project that did not open. ### Content roots Play and test workers load a revision's **read-only snapshot** (`/.argus/snapshots/rev_/`) and the build job's compiled output (`/.argus/jobs//out/modules/`), never the authored tree: the workspace service applies a multi-file change set as an intent entry followed by writes, so the authored files can be briefly mixed on disk, and a behaviour read from there is bytes no check ever saw. **Where those two directories come from is the service's answer, not a guess.** `GET /v1/builds/{revision}/content-root` re-materialises the revision's snapshot from the object store and hashes every file in it against the revision's own inputs before it answers; only then does it say `verified: true`, and only a selection carrying that is loaded. A path assembled from a revision id is a guess about what is on disk, and a read-only flag is not an integrity boundary. `GET /v1/builds`'s own `contentRoot` field is **not** that answer and the editor does not load from it. `crate::content::ContentRoots` remains the authoring preview's seam — "the content root for revision X" — with `AuthoredTree` as its implementation: the artifact's frozen scene copy, with behaviours and assets from the authored tree behind the artifact's stale check. Standalone `argus run ` keeps its file watcher and reload, and resolves `script.module` beside the scene as it always has. ### The link `crate::service::ServiceLink` is a background thread. It finds the project's service through `.argus/service.json` and `GET /v1/instance` (`argus_workspace_service::discovery::resolve`: the pid check on the service's own OS, then the instance handshake; never a guessed port) and follows it: - `GET /v1/log?after=&limit=500`, every 250 ms, up to eight pages a round; - `GET /v1/status`, every second; - `GET /v1/evidence/{sha256}` when a screenshot is opened (at most 32 MiB held). Everything it reads reaches the editor through a bounded channel (256 events), and each editor frame folds in at most 64 (`EVENTS_PER_FRAME`), so a busy service never stalls a frame. **The cursor survives reconnects**: it is the last sequence number read, and after a dropped connection or a restarted service reading resumes after it, so no entry is shown twice and none is skipped silently. The first connection starts at the newest 2,000 entries. While no service answers, the link retries every second and reports each distinct reason once. ### Session authority Whether a service answers **as the editor opens** decides who keeps the session registry for the whole run. **A service answered: its journal is the authority.** - Every record change is posted to `POST /v1/sessions?source=argus-editor`, one lifecycle step at a time, with the serving engine's instance from its ready line (`nonce`, `pid`, `endpoints`): the Play runtime's for a human-play session, the worker's for a test session. - Each live session is heartbeated every five seconds (`POST /v1/sessions/{id}/heartbeat`). - The editor writes no `sessions.json` and does no interrupted-recovery of its own: the service recovers sessions a dead editor left. - While the service is unreachable, records wait in bounded queues (1,024 in the registry, 256 in the link) and go in order once it answers; anything dropped from a full queue is counted (`ServiceState::dropped_records`). - A record the service refuses (`wrong-project`, `illegal-transition`, `terminal-session`, `engine-replaced`, `revision-not-runnable`) is reported (`ServiceState::refused`, the feed's `record-refused` row, and a stderr line) and never retried. - On close, the last records are posted (close waits at most two seconds for the service), then `sessions.json` gets its one write, as a record of how the run ended. **No service answered: `sessions.json` is the registry**, as before, for the whole run. A service that starts later is followed for the feed and jobs, but is not given the sessions. **Unverified content.** Sessions naming an artifact the service does not know are accepted and marked `artifactVerified: false`; that is every editor session until Play runs revision snapshots. The feed says so on the session's row ("unverified content: not a build the service checked"), and `ServiceState::artifact_verified(session)` gives the toolbar the same. `crates/editor/tests/service_link.rs` and `crates/editor/tests/e2_service.rs` gate the link and the authority against a real service. ### Activity feed `crate::feed::FeedStore` folds log pages into rows a person can act on: actor, action and result, with links to a diff, an entity, stored evidence (a screenshot, a trace), a job, or a source file. - **Bounded.** The newest 2,000 rows (`FEED_CAP`); every row's raw entry is cut at 2,048 bytes, its label at 512, each diff at 8,192, and its links at 12. Memory is bounded by the row cap however long the journal grows. - **Truncation is a row.** History the feed did not load (`feed-history-not-loaded`) and entries the service's retention removed before the feed read them (`journal-truncated-unread`, from the page's `truncatedBefore`) are marker rows with counts. Rows dropped to keep the cap are counted (`dropped()`). - **Filters** (All, Failures, Jobs, Changes) each keep an index of the rows they admit, updated as rows arrive and leave, so a frame reads only the rows it shows. - **Labels are for people.** A per-revision story follows a change through its build, checks and apply: "`jump` change compiled; `traversal` passed; applied to your session". **Applied comes only from the runtime's acknowledgement**: an `update-applied` entry whose outcome is `applied`, `ok`, `succeeded` or `success`. A completed change, a build or a passed check never sets it. The raw entry stays behind the row. - **Tolerant.** An entry kind the editor does not describe is still a row, with its raw JSON. **Changes made outside the editor are applied from the feed.** The workspace service reads files that change outside the workspace protocol once they have stopped changing; one file it applies itself, but several wait for an actor to say the edit is finished, because stable reads do not prove that it is (`docs/WORKSPACE-SERVICE.md`). Until someone does, those files are in no revision at all, so nothing builds, plays or exports from them. The row that found them names them and carries **Apply** (`feed.apply-external`, and `feed.apply-external.`, which is the name to press when more than one group is waiting), which posts `POST /v1/external//apply` as `human:local` through the service link. From the press until the service answers, the button is disabled and the row says it is applying (`feed.apply-external..applying`); on success the row names the revision the group became, and that revision builds as any other does; on failure the row shows the service's own message and offers the Apply again, because a refusal is not a reason to hide the changes. A group that a later one superseded says why and offers nothing. While a group is waiting, the Export panel says those files are in no revision and are not in the export, and sends the person to the feed to apply them. ### Agents `crate::presence` is what the human sees of the agents that work in the background. `PresenceModel` holds the roster, what each agent has in scope or has just changed, and the updates held behind Refresh. It is folded from `PresenceEvent`s that a `PresenceSource` hands over once a frame (`Presence::pump`, from `Shell::frame_with_dt`). `NoPresence` is the source until the service and the agent supply one, `FakePresence` is the gates' source, and `ARGUS_TEST_PRESENCE=` gives a scripted run a fake one. The buttons emit `UiAction::Presence(PresenceAction)`: the switch, Refresh and Apply are the model's own, and Pause, Revert and Diff are forwarded to the source. - **Roster.** The status bar's chip counts the agents and opens a list of them. Each row shows the agent's colour, hashed from its name into `theme::AGENT_PALETTE`, and its activity, with Pause/Resume, Revert all since… (the last 1, 5 or 15 minutes, or since this editor opened) and Show changes, which filters the feed to that agent. - **Marks.** An entity an agent has in scope, or changed in the last 10 s (`RECENT_MS`), gets a tinted Outliner row with a stripe and the agent's initial. It also gets a name tag in the agent's colour over it in the authoring view, and a ring flashes for 700 ms when a change lands. The tags are painted by the viewport overlay's painter, so they add no render pass and take no clicks. The human's selection is never touched, and it still wins the row's fill. - **Live updates.** Remembered per project in `.argus/editor/settings.json` (`liveUpdates`, default on), which is written when the switch is flipped. The editor core owns `state.json`, so the switch is not kept there. When the switch is on, a change is applied to the view as it lands. The exception is a staged set while Play runs, which queues until Refresh or Stop. When the switch is off, everything queues. The toolbar then shows "N updates ready (x scene, y code)" (`toolbar.updates`) with **Refresh** (`toolbar.refresh`). The button says "Refresh (restarts Play)" when something queued cannot reach a running game. Turning the switch back on with a queue offers "Apply N queued updates?" rather than applying them unasked. `PresenceModel::take_applied` hands what was applied, in order, to the editor core to fold into the document and Play. - **Feed.** A per-agent filter (`FeedStore::count_by`/`get_by`, an index like the others). Every change that landed carries **Revert** and **Diff**, and a change held behind Refresh carries **Apply**, which applies that one alone. ### Jobs panel model `crate::jobs::JobsView` is built from `job` and `check-result` entries and `GET /v1/status`'s live jobs: the newest 256 jobs, 16 results each, and 64 results that name no job, with counts of what was dropped. - Each job shows its state, the phase the service gives it (queued, running, session ready, checking, done), its kind as its resource class, and either the progress a runner reported or "progress not reported". Progress lives in the service's memory only, so it is absent for a job that never reported one and is lost when the service restarts. - **Stale:** a result for any artifact other than the running one stays inspectable and is marked stale; it cannot validate what the human is playing. - **Incomplete because:** the job's state and reason, whether the service is waiting for it to report again after a restart, and each result's outcome, failure kind and limitations, in words. - **Cancel** goes through `JobControl`. `ServiceJobControl` posts `POST /v1/jobs/{id}/cancel` with the human as the actor; the service answers `terminal-job` for a job that has already finished, and the refusal is shown rather than swallowed. A job can be cancelled while it is not terminal (`argus_workspace::is_terminal_job_state`, the service's own rule). Cancelling needs a runner polling: `GET /v1/jobs` lists only runners that polled within the service's `RUNNER_TTL_MS` (15 s), so an empty list is the whole signal, and the button then carries that reason instead of being dead. ### Project Settings `crate::settings::SettingsBackend` is shaped like the service's settings API (`GET /v1/settings`, `POST /v1/settings/check`, `POST /v1/settings/apply`, `GET /v1/settings/icon?path=`; an edit is `{field, expect, value}` by JSON pointer, and a stale `expect` is a field conflict with the expected, actual and proposed values). **`ServiceSettings` is what the editor uses.** `Shell::new` resolves `/.argus/service.json`, verifies the instance and talks to those routes, so a settings change is a change set on `argus.project.json` with a lease, an expected version and a journal entry — the same path an agent's edit of that file takes — and the write is a revision the build pipeline builds. The apply is made as the person at this editor (`Actor`), and its three refusals are shown rather than raised: a field someone changed underneath the edit (409 `field-conflict`, naming the field and what it holds now), another change holding the manifest (409 `lease-held`, naming the holder), and a merged manifest that would not validate (422 `invalid-settings`, with the diagnostics). The page holds the view it last read until something says the manifest moved underneath it: its own Apply says so, and so does anything else that edits a settings field (`EditorUi::forget_settings_view`), which today means Set as startup scene. Now a change made elsewhere does too: whenever the editor takes the manifest again (`Editor::manifest_generation`), the page reads the settings again and keeps what was typed (`EditorUi::refresh_settings_view`). **`ManifestView` is the fallback**, when no service answers or the discovery file names one that has gone. It reads `argus.project.json` through the project resolver, shows each violation on its field, previews the icon by reading the file, and edits nothing — only the service can record a settings change, and it says so where a person would otherwise type. `RecordingSettings` is the test seam the automated gate edits through. ### Authoring context `crate::state::EditorStateStore` is the whole interface for the restart state (`load`, `save`); `FileStateStore`, writing `state.json`, is its only implementation. ## The interface `crate::ui::EditorUi` is the editor's interface: egui 0.36, run once per editor frame over the editor core, after the editor's own frame. A frame of it reads the editor and records what the person asked for (`ui::UiAction`); the shell applies those after the frame through the same calls its keys make (`Shell::apply`), so a button and a key are one path. | Area | What it shows and does | |---|---| | Menu bar | File (New project…, Open project…, Save, Close project), Edit (Undo, Redo, Duplicate, Delete, Project Settings…), Window (Activity, Jobs, Content, Outliner, Details), Help (Viewport controls, About Talos Editor, Report a bug…, Request a feature…, Copy the documentation path), each item with its keyboard shortcut as text and each dispatching the same `UiAction` the toolbar and the keys do | | Toolbar | **one row** — left **Save** (a disk mark), Undo, Redo, **Import model…** (see [Importing models](#importing-models)), **Export…** (see [Exporting a game](#exporting-a-game)); centre **Edit** and the transport as marks, Play a green triangle, Pause two bars, Step a triangle against a bar, Stop a red square, each naming itself on hover; right the project's name in the quiet style every state item has (`toolbar.project`; it follows a settings apply, as the window title does), **Settings** (the Project Settings page) and **Close project**. What the editor is *holding* is the status bar below, not a second toolbar row | | Status bar | along the bottom of the window (the usual editor's bottom bar). Left: **Activity**, **Jobs**, **Content**, **Log** (`status.drawer.`; short labels, because at 150 % in a 1280-wide window the bar is full), which open the drawer on that tab and close it when pressed again; then, only while a Play session is live, "Play is up to date" or "N updates pending" (`toolbar.pending`) — at rest it says "Play runs the latest save", because the count is about restarting a run and there is nothing to restart — then the agent chip ("3 agents", `status.agents`), which opens the roster, and the **Live updates** switch (`status.live-updates`; see [Agents](#agents)). Right, reading left to right: the build state (`toolbar.build-state`), the workspace service's state (`toolbar.service`), "Unsaved changes" or "Saved" (`toolbar.save-status`), and `Content ` for the artifact Play loads (`toolbar.artifact`). Above the bar, and only when there is something to say, a wrapped row of notices: "Scene changed on disk" with **Reload**, the last Ready build and **Play last Ready**, "unverified content", the last refusal and the last error | | Viewport | the game image, drawn across the whole panel at the render target's size, which follows the panel's, composed with the panels in one pass; a click selects the entity drawn under the pointer (pointer, to the image rect, to a target pixel, to the authored id). A painted overlay at the top-left names the open scene and whether it is authoring or playing (`viewport.overlay`), with the selected entity's id under it in the usual editor's orange (`viewport.selection`); both are painted, not widgets, so a click there still reaches the viewport | | Outliner and Details | the right column, the tree over the inspector with a splitter between them, either one hidden from the Window menu, each under a header strip with its name as a tab (`outliner`, `details`); a search box over the tree (`outliner.search`) narrows it by name, id or tag and flattens it while it is typed in. The scene's entities as rows (`entity.`): a kind mark coloured by what the entity is for, its name, and its id dimmed after it, the selection filling the row in the accent. Then the selected entity's Duplicate and Delete, its transform as numeric fields (`inspector.transform.position.x`, …), its components' behaviour fields as typed rows (`inspector.prop.controller.speed`, …) over a collapsed raw JSON view, the asset section for an entity with a `mesh` (where it was imported from, its settings, Reimport, Collider, Reveal, and Delete unreferenced when the scene's `assets/` folder holds model files nothing names — see [Importing models](#importing-models)), components, a copy-path link to its behaviour source, and failures in the feed that name it | | Project Settings | a page over everything between the toolbar and the status bar (`settings.page`), opened from Edit → Project Settings…, the toolbar's Settings and the Export panel's Edit in Project Settings — **not while Play runs**, because the page would cover the viewport the run is drawing into, which is the rule every other File and Edit item already followed. A search that matches nothing says so (`settings.empty`), and edits typed and not applied are kept when the page is closed and counted at the top when it is reopened (`settings.unapplied`), so nobody pushes an edit they thought they had abandoned: a search box, the category tree from `Section::ALL` on the left with each section's count (`settings.category.`), the form under section headers on the right, capped at 720 pt with a fixed label column, each field's diagnostics (the categories are grouped Project and Engine, and the Engine ones are the scene defaults, see [Project Settings](#project-settings)), and "needs a restart or a new export" said **once per section** (`settings.section..note`) with a `×` beside the individual fields only where the section is mixed; the icon with **Choose…** and a preview served by the workspace service, then Apply, Revert and Close | | Activity feed | `build` entries as "Building scenes/main.scene.json", "Ready", "Failed: scenes/jump.ts:5:19 — message" with a source link, and `revision-runnable` entries; the newest rows the scroll area shows, and an explicit line for rows dropped, entries never read and housekeeping not shown. **Consecutive entries that say the same thing are one row and a count** ("… ×8"), and a garbage collection that freed no bytes is counted rather than kept — but a row that leads anywhere (a diff, an entity, a job, a file, a group of external changes) is never folded into another, because folding it would take away something a person can press; a row opens an "Activity entry" window with its links (diff, entity, screenshot or trace, job, source) and its raw entry, so the links are never cut off by the panel's height; "Applied" only on a runtime acknowledgement | | Build state | the toolbar shows, for the revision this scene's last save produced, the workspace service's own state in plain words (`toolbar.build-state`: Editing… / Building… / Checking… / Ready / Failed — file:line — message; a click opens the feed row), the last Ready build while the newest is Failed (`toolbar.last-ready`), and **Play last Ready** (`toolbar.play-last-ready`) to play the artifact this editor prepared before the failed one, without adopting it (Stop puts the current one back); `Content ` names the artifact Play loads. With no service: "No workspace service: builds are not checked here" | | Prompts | modal: **Unsaved changes** ("Save changes to ?", Yes / No / Cancel, `prompt.*`) when closing with unsaved work or opening another scene over it; **Restore unsaved work** (`recovery.*`) when a project opens with autosaves the last session left; **Unsaved changes** before Play (Save and Play / Discard and Play / Cancel, `play.*`); **The scene cannot be saved over as it is** (Overwrite / Reload / Cancel, `conflict.*`) when a save finds the file changed, missing or unreadable; **Import** (`import.*`), what a model file measured and what the declared settings will make of it; **Export** (`export.*`), the revision that would be exported, its branding read-only, the destination, progress, Cancel and what the last export wrote | | Drawer | over the viewport, above the status bar, tabs **Activity** / **Jobs** / **Content** / **Output Log** (`drawer.tab.`, also drawn as `feed.tab`, `jobs.tab`, `content.tab` and `log.tab`; the Output Log is [its own section](#the-output-log)), a grab handle that sizes it (`drawer.splitter`) and a Hide/Show button (`drawer.toggle`) leaving the tab strip; pressing the tab already showing closes it too, and so does the status bar's button for it. **Jobs** holds what used to be a column of its own, as a grid of cards that fills the width, newest first: each job's state and phase, resource class and reported progress ("progress not reported" only while it could still be reported); stale marking against the service's `currentArtifact`; why it is incomplete; Cancel through the service with its reason when it cannot, and no Cancel at all on a job that has finished; its screenshots | **Help ▸ Report a bug… and Request a feature…** (`menu.help.report-bug`, `menu.help.feature`; `crate::report`). Report a bug opens the Launcher's own report, not a second kind: the same `argus_usage::reports::Report`, the same form (category Bug / Feature request / Question, a title of up to 120 characters, a description, and **Attach logs**, off until ticked, with the warning "Logs can contain file names and paths from your project."), and the same **Review and send…** screen, which shows the report's JSON and the log text exactly as they will go (`report.review.fields`, `report.review.logs`). Always included: the engine version (this editor's), the launcher version (`0.0.0`: the editor cannot ask the Launcher) and the OS class and build. The editor's log bundle begins with its version, the open project's **name** and where the editor's log is, then the last 2,000 lines of the editor's log (`--log-file`), the workspace service's (`.argus/editor/service.log`) and the Launcher's (`argus-hub.log`), each only if it exists, with the profile folder replaced by `%USERPROFILE%`. Project files are never attached. **Only Send writes anything**: Cancel, Back, the window's × and Escape (once no field has the keyboard) save nothing. Send writes the reviewed report to the reports outbox (`%LOCALAPPDATA%\Argus\reports\outbox\\`, `argus_usage::reports::save`) and starts `argus-hub --send-reports` from the Launcher's install, which sends it; the editor makes no network call. With no Launcher to start, the dialog says the report waits in the outbox for the Launcher's next run; on a managed or offline install it is saved for email to feedback@cadarn.ai and nothing is started. The dialog is modal (`Shell::modal_open`) while it is open, so typing in it drives nothing else. There is no shortcut: a menu item is enough (Ctrl+Shift+F1 is the Launcher's). **Request a feature…** opens `https://cadarn.ai/talos/roadmap` (`report::ROADMAP_URL`), the testers' roadmap, in the system browser. Tests replace the outbox and the Launcher start (`Shell::set_outbox`) and the browser (`Shell::set_url_opener`), so no test writes the person's outbox, starts a program or opens a page (`tests/ed_help.rs`). **Painting.** The game keeps drawing into its `RenderTarget`, at the viewport panel's size. Each frame `crate::paint::Painter` copies the target's colour into a texture registered with egui-wgpu (remade, with the same id, whenever the target's size changes), and paints every egui primitive, the viewport's image included, into the swapchain image through `argus_render::surface::Surface::present_with`, on the renderer's device. Nothing is read back to the CPU. A headless shell runs and tessellates the interface each frame and paints nothing. **Input.** Every winit event goes to the interface's input (`crate::egui_input::EguiInput`, the editor's own translator, so tests and the window take one path) and to the shell's routing in the same call. A press on the game image gives input to the viewport and a press anywhere else to the interface (see [Focus](#focus)). While a text field has the keyboard, keys go to it and not to the game or the editor's shortcuts, and Esc leaves the field and does nothing else. The window's clipboard is egui-winit's; IME is allowed while a text field wants it. **Bounded.** The feed draws only the rows its scroll area shows (`ScrollArea::show_rows` over the store's per-filter index); failures for the selected entity are gathered once per selection and feed position. With 100,000 events folded into the feed, a frame draws at most 13 feed rows in the gate's layout (`tests/ui_bound.rs`). **Where things are.** Each control a person clicks is recorded by name with its rectangle (`EditorUi::hit`: `toolbar.play`, `menu.edit.undo`, `drawer.tab.jobs`, `feed.row.`, `feed.link.evidence.`, `entity.`, `settings./application/displayName`, `export.ok`, `viewport`, and so on), so the scripted-human gate presses exactly what a person would. The interface pass renamed nothing: every name the suites pressed before it is still drawn, and the new surfaces took new names — `menu.file`, `menu.file.`, `menu.edit.`, `menu.window.`, `menu.help.`, `toolbar.settings`, `outliner`, `details`, `drawer.tab.`, `drawer.toggle`, `drawer.splitter`, `feed.tab`, `jobs.tab`, `content.tab`, `settings.page`, `settings.search`, `settings.category.`, `settings.section.`, `settings.revert`, `settings.close`, `settings.error`, `settings.icon.browse`, `settings.icon.preview`, `settings.icon.error`, `settings.icon.none`, `about.window`, `about.version`, `about.build` and `about.docs`. The fix pass renamed nothing either. It **moved** the status items out of the toolbar into the status bar, where they keep the names they had (`toolbar.save-status`, `toolbar.artifact`, `toolbar.pending`, `toolbar.live`, `toolbar.freeze`, `toolbar.service`, `toolbar.build-state`, and in the notices row `toolbar.disk-changed`, `toolbar.reload`, `toolbar.last-ready`, `toolbar.play-last-ready`, `toolbar.unverified`, `toolbar.error`) — the name is where a gate presses, not where the control lives. The names it added are `status.drawer.content`, `status.drawer.activity`, `status.drawer.jobs`, `toolbar.project`, `outliner.search`, `viewport.overlay`, `viewport.selection`, `settings.section..note`, `settings.empty` and `settings.unapplied`. MaPresence renamed nothing. The Live and Freeze placeholders became the Live updates switch, which is drawn under `status.live-updates` and under both old names. It added `status.agents`, `roster`, `roster.`, `roster..name`, `roster..pause`, `roster..revert-since`, `roster..revert-since.{1m,5m,15m,all}`, `roster..changes`, `toolbar.updates`, `toolbar.refresh`, `entity..agent.` (the initial on a marked Outliner row), `viewport.tag.`, `feed.filter.agent`, `feed.filter.agent.all`, `feed.filter.agent.`, `feed.revert.`, `feed.diff.` and `feed.apply.`. `` is the agent's actor id. **Marks are painted, not typed.** The font egui bundles has no glyph for a good many symbols, and a character it lacks is drawn as *nothing at all* — no box, no warning, no failing test. Six marks the editor drew were invisible for that reason: `◧` and `▤` on Content tiles, `▾` and `▸` on the folder tree, `✓` in the File menu and `●` for the open scene, and the drawer's toggle was an empty button for the same reason. The toolbar's transport, the Content tiles' role marks and the folder tree's disclosure triangles are shapes now (`ui::Mark`, `content_browser::Role::mark`); `theme::TEXT_MARKS` is the list of characters the interface still draws as text, and `theme::tests::every_mark_has_a_glyph_in_the_bundled_font` asks the bundled font about each of them. ## The shell The window is laid out the way the usual editor's window is, in this order (`crate::ui::draw`): | Claim | Panel | Size | |---|---|---| | 1 | `menubar`, a top panel | the row's height, not resizable | | 2 | `toolbar`, a top panel | one row of controls, not resizable | | 3 | `status`, a bottom panel | one row, plus a wrapped notices row when there is something to say; claimed before the right column, so it runs the width of the window as the usual editor's bottom bar does | | 4 | `details`, a right panel | 320 pt, capped at 40 % of the width, holding `outliner` over the inspector; claimed before the drawer, so it runs the full height | | 5 | `drawer`, a bottom panel | `UiState::drawer_height`, capped at 45 % of what is left, spanning the viewport rather than the window | | 6 | the viewport, the central panel | the rest | The order matters. The right column is claimed before the drawer, so it runs from the toolbar to the bottom of the window and the drawer spans only the viewport beside it — which is both what the usual editor does and what the inspector needs, because **a control scrolled out of a panel is drawn, and named, and cannot be pressed**. A shorter Details panel is not a cosmetic change; it silently puts the property rows out of reach. **The left edge belongs to the viewport.** Before this change one 280-point left column held the scene tree, the inspector, the asset section and Project Settings in a single scroll, and the jobs held 300 points of their own on the right; Project Settings was below the fold in both screenshots the design review came from. The tree and the inspector are the right column now, Project Settings is a page, and the jobs are a tab. **The toolbar is laid out, not wrapped.** Its three groups sit at computed rectangles — the centre takes `TOOLBAR_CENTRE_WIDTH` and the two sides split what is left — so Play stays in the middle of the window whatever else changes. A wrapped row moved it every time a build state grew a word. The status bar is laid out the same way, its right-hand group capped at `STATUS_RIGHT_WIDTH` so the drawer buttons on the left always have room at 150 % display scaling; the notices above it *are* wrapped, so they can never reach past the window however much they have to say. **The viewport fills its panel** (ViewportD6). The view is no longer drawn at the size the project was opened at and letterboxed into the panel: the panel's size in physical pixels drives the offscreen target, so the frame is rendered at the size it is shown at and framed for the shape it is shown in. Each frame `Shell::frame_with_dt` measures the rect `ui::viewport` drew the image in and hands it to `preview::follow_panel`, which clamps it to 64..=4096 a side and asks the world the viewport shows — the authoring view's, or Play's while playing, because the editor runs Play inside the editor process, on the one renderer it moves between the two worlds. `World::request_target` allocates a new `RenderTarget` once that size has held for 150 ms, and `World::resize_target` is what replaces it: the four attachments, the two bind groups that sample them and the readback buffer, and nothing else — the scene, the entity store, the mesh and texture caches, the physics world and the renderer all stay as they were. The camera follows with no help, because `World::submit` reads its aspect from the target every frame. `paint::Painter` remakes the egui texture the image is sampled from when it sees a new target size, keeping its `TextureId`, so a resize costs one texture rather than a leaked one per resize — and while the panel and the target disagree, for the settle after a drag or the first frame of a Play, the last frame is stretched over the panel rather than the copy being skipped and the image freezing. **Why it is debounced:** a resize allocates roughly 24 bytes a pixel, and a window or a splitter being dragged reports a new size every frame; nothing is asked for at all while the pointer is holding something, so a drag of any length costs one reallocation, at the end. `crates/app/tests/d6_resize_target.rs` holds the engine half (the world survives, the aspect follows, the clamp, the debounce, fifty resizes and the memory); `crates/editor/tests/d6_viewport.rs` holds the editor's (the target follows the panel and not the window, picking is exact before and after a resize, the thumbnail and F9 are written at the target's size). **The drawer is sized from editor state, not from egui's panel memory** (`UiState::drawer_height`), so closing it and opening it again gives back the height it had. Its height settles on the frame after the toggle, because the panel's size is decided before the strip inside it is drawn. A drag on its grab handle (`drawer.splitter`, which shows the resize cursor) is kept per user in `layout.json` (`drawerHeight`, below), inside the same limits the drawer is drawn in; a double-click on the handle puts the default 240 points back. **The right column and the Outliner resize, and the person's sizes are kept** (`crate::layout`), as the usual editor's panels are. Two splitters, The usual editor's: `panel.splitter`, a strip just inside the column's left edge (so a press on it never picks in the viewport), sets the column's width, and `outliner.splitter`, over the edge between the Outliner and the Details, sets the Outliner's height. Hovered or dragged, a splitter shows the resize cursor and an accent line; a drag follows the pointer exactly from where it was pressed; a **double-click puts that size back to its default**. The limits keep both sides usable at every display scale: the column is at least 160 points and leaves the viewport at least 360; the Outliner is at least 48 points (its header, the search row and a row) and leaves the Details at least 120. A size the person has not set is the default, which follows the window (the column 320 points or 40 % of the window, whichever is less; the Outliner a third of the column, up to 200 points), so the default layout is exactly what it was. **Per user, not per project**, beside the keymap: `/argus/editor/layout.json` (`ARGUS_LAYOUT_FILE` overrides it for scripted runs), as `{ "panelWidth": 380, "outlinerHeight": 260, "drawerHeight": 300, "outlinerSort": "type" }`; a size left out or `null` is the default. It also holds `contentFilter`, the Content Browser's type filter (`["model", "prefab"]`; left out is every type, and a word the editor does not know is dropped when the file is read). It also holds `outlinerCollapsed`: the Outliner folders the person closed, per scene (keyed `#`, at most 64 scenes, the least recently changed dropped first); a folder not listed is open. It is written once when a drag ends, and when the sort or a folder's caret changes. Only the window's editor reads and writes it (`crate::app` calls `Shell::set_layout_store(LayoutStore::user())`); a `Shell` built directly — every test, a headless gate — keeps the defaults in memory unless handed a store. A file that does not read is the default layout with the reason on stderr; a size that is not a positive number keeps its default; a field it does not know is ignored. `/v1/state` has `view.layout`: `{panelWidth, outlinerHeight, drawerHeight}` as drawn last frame (points; `outlinerHeight` is `null` unless the Outliner and the Details share the column, both are `null` while it is closed, and `drawerHeight` is `null` while the drawer is closed) and `outlinerSort`; `/v1/do {"do":"set-view","layout":{…}}` (and `editor.set {layout}`) sets any of them, a size to `null` for its default. With no editor running, `editor.state` answers from the project's `state.json` and has no `view.layout`: the layout is the person's, not the project's. **A model dragged out of the Content drawer and let go on the viewport is placed in the open scene** (`content_browser::dropped_model` on the viewport's response, which answers only for the widget the pointer is over on the frame the button comes up), **where it was let go**, as the usual editor places a dragged asset: on the surface under the cursor (the authoring view's own pick, `Editor::surface_at`), else on the ground plane y = 0 along the cursor's ray, else at the origin. One function, `content_browser::drop_point`, places a dropped model and a dropped prefab alike. Place and a double-click still put it at the origin. The drop handlers ask for their payload's type before taking it: egui's `take_payload` takes whatever is carried, so a model check on a prefab's release used to drop it. Place is a button in the drawer as well, so nothing the browser does is reachable only by dragging. The two halves are asserted separately: that a model tile carries its path while it is dragged in `tests/d6_content.rs`, and that a release over the game image puts the model in the scene in `tests/d6_shell.rs`. **Project Settings blocks the viewport, not the shell.** The page is an `egui::Area` over the panels, so `EditorUi::over_viewport` stops giving the game the pointer while it is open, and the menu bar and the toolbar above it stay live — there is always a way back out. The prompts and the menus are `Modal`s and popups, which sit above it. **A hit name is a control a person can press.** Every name the interface publishes carries `Response::interact_rect` — the widget's rectangle clipped to what is actually on screen — and a widget whose clipped rectangle is empty is not published at all, because egui refuses to interact with a clipped widget. The panels under the Project Settings page publish nothing while it is up, for the same reason: they are still drawn, because leaving the page has to give back exactly what was there, but a click on one of them lands on the page. A modal prompt is the same rule: `egui::Modal` blocks input to everything beneath it, so while one is up the map holds the prompt's controls and nothing else — the suppression is applied where the prompts draw, not decided from a flag before them, so a prompt added later is covered without anything to keep in step. The design review measured what the old rule cost: 178 of 200 Outliner rows and the 300th content tile were published as controls, and pressing them did nothing at all; the re-review measured 51 more under the Play prompt. **A skipped test says so, and a gate can forbid skipping.** Some of `tests/d6_content.rs` and of the design review probes need `packages/gameplay/dist` and an esbuild binary to open a project whose scene carries behaviours. Without them those tests print `SKIPPED : ` and return — which cargo reports as `ok` and shows only under `--nocapture`, so a whole file can be green without having run, which is what the design review hit. `ARGUS_REQUIRE_TOOLING=1` makes a skip a failure instead, and every gate and CI run should set it. The other half of the answer is needing the toolchain in fewer places: a test whose project has no behaviours builds one and runs anywhere, so 8 of the 16 tests in `d6_content.rs` need it rather than 13 of 14. **Everything fits the window the editor promises, at the scales a person has.** `crates/editor/tests/d6_shell.rs` asserts that every rectangle the interface draws is inside a 1280x720 window at 100, 125 and 150 % — 150 % of that window is 853x480 points — with and without the settings page. `tests/d1_workflow.rs` and `tests/d3_review_probes.rs` hold the same line for the workflow's and the importer's controls at 150 %. ## The theme `crate::theme` is one `Visuals` and one `Style` for the whole product: the launcher and the editor each call `theme::apply` on their context, and neither carries a colour of its own. Before this change only the launcher was themed — the editor ran in stock egui dark — and the two halves disagreed about red (`#e15555` against `#eb6464`). The values approximate a familiar dark editor theme: window `#1A1A1A`, panels `#242424`, the header strip and the menu bar `#1C1C1C`, borders `#383838`, recessed fields `#1E1E1E`, buttons `#3C3C3C`, text `#DCDCDC` over `#9E9E9E` over `#6B6B6B`, accent blue `#0E6BB8`–`#2C7FE8`, 12.5 pt body text, 20 pt rows and 3 px radii. Epic publish no swatch list, so **every value is meant to be adjusted**: open the editor you are matching, eyedrop the surface, and change the one constant. Nothing else in the editor holds a colour. Separately from the chrome, eight constants carry meaning rather than surface — `ERROR`, `WARNING`, `OK`, `ACCENT`, `LINK`, `PLAY`, `STOP` and `SELECTION` (the selection orange familiar from other editors, which is also the colour the viewport marks the selected entity in). **Every colour the editor draws words in reads on every surface it draws them on**, which is the design review's finding: the theme's own test checked the panel alone, while the same words are drawn on a button, in a field and on the header strip — where `ERROR` was 3.21:1, `OK` 3.97:1, the hyperlink colour 2.79:1 and disabled text 2.07:1. So `ERROR` is a coral rather than a red (a red dark enough to look like the usual editor's `#ED1B34` cannot reach 4.5:1 on a `#3C3C3C` button at all), `OK` and `SELECTION` are one step lighter than the usual editor's, disabled text is lifted to clear 3:1 and still sits below muted, and the accent — right for a selection fill, a focus ring and an active tab's underline, and not readable as a word — keeps its value while the one place it would be a word, a link, has its own `LINK`. `STOP` and `PLAY` keep the usual editor's values because they are shapes, not words. The unit test now checks every colour against `PANEL`, `INPUT`, `HEADER` and `CONTROL`, and the surfaces to their order, so an eyedropper pass cannot quietly flatten the shell or make a failure unreadable. the person may choose the **accent** (blue, teal or violet) and the body **text size** in [Editor Preferences](#editor-preferences) ▸ Appearance. `theme::apply_appearance` puts them on the context, and whatever the painter draws in the accent reads it through `theme::accent()` and `theme::accent_deep()` rather than the `ACCENT` constants, which stay the usual editor's blue (the launcher's). The shell stays dark: a light theme would need every surface and text constant above to become a lookup. ## Windows build `argus-editor.exe` is a **GUI-subsystem** program (`windows_subsystem = "windows"`): opened from Explorer or a shortcut it opens no console, and so no console window takes the foreground. - Whenever it has no usable standard error, its messages go to `--log-file`, by default `%LOCALAPPDATA%\argus\logs\argus-editor.log` (moved aside to `.log.1` past 8 MB). On any OS, `--log-file PATH` sends them there explicitly. - `--console` attaches to the console it was started from, or opens one, and points the standard handles its launcher did not redirect at it. - The `worker` subcommand keeps the pipes its launcher gave it; the editor starts workers with `CREATE_NO_WINDOW`. - The project is opened before the window, so a refused project exits with its reason in the log and never shows a window. ## Simulating the human in tests The gates play the human **at the winit event boundary**, with no OS-level input synthesis and nothing taking focus. `argus_editor::test_inject` is clearly labelled test-only: it builds winit's own values (`KeyCode`, the logical `Key` and the text a key types, `ElementState`, `MouseButton`, `MouseScrollDelta`, `Ime`, `ModifiersState`) and calls `Shell::on_keyboard`, `on_mouse_button`, `on_cursor_moved`, `on_cursor_left`, `on_mouse_motion`, `on_wheel`, `on_focus`, `on_modifiers`, `on_ime` and `on_scale_factor` — exactly the calls the real event loop (`shell::App::window_event`) makes. Everything from there on is the production path, the interface's input included. `test_inject::click(shell, name)` moves the cursor to the centre of the control the interface drew under `name` and presses and releases it; `type_text` types characters. `crates/editor/tests/e2_human.rs` is the scripted-human gate: through those calls alone, a person watches a change arrive, inspects a failure, opens its screenshot, selects the affected entity, edits a Project Setting through the settings seam and resumes Play. For a real windowed run, `argus-editor --test-inject-script ` replays the same events inside a real window at rendered frame numbers. A scripted run needs no focus, so its window is created non-activating (`with_active(false)`; honoured on Windows and macOS, ignored by X11 and Wayland) and never grabs the cursor. Its events are: one event per line, ` key down|up`, `button left|right|middle down|up`, `cursor X Y`, `motion DX DY`, `wheel LINES`, `focus in|out`, `click `, `hover `, `type `, `modifiers none|ctrl|shift|alt[,…]`, `scale FACTOR`, `resize W H`, `import `, `close`. **A scripted step that cannot be applied is named and the run fails.** A `click` or a `hover` on a control that is not drawn is refused — the message names what *is* drawn under the same prefix, not every control on screen — and the runner logs `MISSED frame : was not applied: ` and ends the run non-zero with every miss listed. The script carries on after one, as a person does after a misclick, but a walkthrough can no longer pass having quietly done nothing: that is how a run clicked a Content tree folder row inside a collapsed parent, never selected the folder, and still reported success. A control that is still drawn but has *moved* between the aim and the press is the silent half of the same problem, so a press is re-aimed at the name the script took aim at, on the frame it is delivered. `hover ` rests the pointer on a control and leaves it there, which is how a script reaches anything inside a submenu: `scene.open.` is drawn only while File ▸ Open scene is open, so a click alone can never press it. Three lines, with frames between them, walk it: ```text 10 click menu.file 14 hover scene.open 20 click scene.open.scenes/arena.scene.json ``` What neither covers is winit and the OS themselves: key repeat, the order a platform delivers events in, focus the OS decides to move. ## Known limits - **Describing a screen needs `@argus/ui`.** The packed SDK carries it at `sdk/packages/ui` and a checkout answers for a project made anywhere, because the directory the editor was started in is one of the three roots discovery walks; `ARGUS_UI_PACKAGE` overrides both. A missing package is the reason on the tile, not a blank one. - **A project that names no default theme gets a path sort for everything after `ui/theme/tokens.css`**, which for the design system's layer is not the order `docs/UI.md` §10 fixes — `game.css` sorts before `sim.css`. Setting `settings.ui.defaultTheme` in `argus.project.json` is how a project chooses; the editor no longer second-guesses it, so a project that has not chosen previews exactly as it plays. - **A translation edit fires no hot reload.** `ui/locales/**` has no `UiRole`, so nothing classifies it as a UI input on its own. The tables are re-read on any sync that describes and on a `ui/scenarios/**` change, which covers editing a string and previewing again, but not editing one while a preview sits idle. - **A UI preview is an authoring activity.** It draws on the authoring world, so it shows nothing while Play is running, and the screen it puts up is popped when it closes. - **The target follows the panel, within a frame or two.** It is resized 150 ms after the panel settles, and clamped to 64..=4096 a side, so a panel dragged shut renders 64×64 and a panel on a wall of monitors renders 4096 wide and is scaled up to fill. - **Agents appear only when a presence source is attached.** Until the service and the agent wire `GET /v1/presence` and the journal into a `PresenceSource`, the chip says "0 agents". The switch and the queue work, but nothing lands in them. Viewport name tags are drawn in authoring only, because Play's camera is the game's. Refresh (restarts Play) reports that a restart is needed; the restart itself is the editor core's. **Cancel** works through the workspace service; it is disabled, with the reason, for a job that has already finished and when no runner is polling. - **Rotation is edited as degrees about X, Y, Z** and stored as the quaternion they make (rounded to 1e-6), so a rotation authored by hand as a quaternion shows as the nearest Euler angles, and typing the shown values back may change the stored quaternion by rounding. - **A save rewrites the file in the editor's form**: pretty-printed JSON, 2-space indent, every array element on its own line, floats as `2.0`. A scene file kept in another layout gets a large first diff. - **Undo is in memory** and does not survive a restart or a Reload; unsaved changes are lost when the editor crashes. - **Children are not duplicated with their parent**, and an entity's children go with it when it is deleted. - **A project whose `startupScene` names a file that is not there does not open.** The manifest is the project's definition and the contract refuses it, as it does for the builder, the exporter and the workspace service; the editor does not repair someone's manifest unasked. The refusal lists the scenes that *are* in the project and says which line to change. An offer in the launcher to set one of them and open is the real fix and is a change of its own. - **The interface keeps little layout across restarts.** The right column's width, the Outliner's height and sort, and the drawer's height are kept per user (`layout.json`, above); which drawer tab shows, the open feed row and the selected filter live for the run. The three splitters show the resize cursor. - **The interface in a real window has not been run by a gate.** The headless gates run and tessellate it; painting through `present_with` needs a window, which needs the coordinator's OK. - **Play worlds' renderer resources are not released.** `argus_render::Renderer` can give a mesh back — `free_mesh`, which `World::reconcile` calls on the meshes an asset swap evicts — but a texture has no unregister API at all, and nothing walks a finished Play world's caches on the way out. So each Play of an asset-heavy scene uploads its glTF meshes and textures onto the shared renderer again and they stay, and a long session of many Plays grows GPU memory until the editor restarts. Built-in primitives are shared and are never freed. A session of many **reimports** no longer grows it: see [Limits](#limits) under Import. - **A Play that fails to load after taking the renderer loses it.** The Play world is loaded from the same frozen document the authoring world already loaded, and the query server binds ephemeral ports, so this is not expected; if it happens the editor reports it and must be restarted. - **Scripts and assets are not bundled into artifacts.** The stale checks refuse a changed one instead. Built-in gameplay modules (`packages/gameplay/dist`) are not revision inputs. - **The engine identity is the running executable.** In the test suite that is the test binary, not `argus-editor`. - **`camera`, `reload` and `stop` have no API endpoints.** Their capabilities are declared and enforced by declaration; a worker stops when killed or when its editor goes. The editor's F5/F9 equivalents are the human's in-process controls. - **Behaviours that branch on the calendar or on sub-tick wall time are not reproducible** (`Date` starts at the run's wall-clock start; `performance.now()` is wall time within a tick and simulation time across ticks), and `Math.random` repeats across runs unless `--seed` changes: see [World seed](#world-seed). - **Content comes from the authored tree**, so the service marks every editor session unverified, until Play and test sessions run revision snapshots; see [Content roots](#content-roots). - **Session authority is decided when the editor opens.** A service that starts later does not take the sessions over for that run. - **A service that hangs, rather than exits,** holds the link for up to the service client's 120 s request timeout; frames are unaffected, but the feed and records wait. - **One editor per project** is assumed: `state.json` and `sessions.json` are not locked. - **A Windows-native editor cannot open a project under `\\wsl.localhost`**; run the editor in WSL for a WSL project. - **Windows TypeScript scenes**: a Windows engine against a project on NTFS needs a Windows esbuild on `PATH` or `ARGUS_ESBUILD`. The gate scenes use a plain `.js` behaviour and need no esbuild.