From 26f86bc6f7bd55ad59d1b191375655d02efabab6 Mon Sep 17 00:00:00 2001 From: iris <2+iris@noreply.localhost> Date: Sun, 13 Sep 2026 15:50:09 -0400 Subject: [PATCH] Rewrite the Iris extraction handoff for a fresh session Current as of PR #11's fourth review, which is deliberately unread: the first instruction is to fetch it. Records what #11 became over three rounds of review, since that shape is what the new review is about, and where the headless rig actually lives, since a rendering claim cannot be verified without it. Drops the finished detail -- PR #10's contents, the source-history archaeology that has been consumed -- and points at the machine-wide pre-submit-review gate rather than restating it. --- docs/IRIS_EXTRACTION_HANDOFF.md | 413 ++++++++++++-------------------- 1 file changed, 155 insertions(+), 258 deletions(-) diff --git a/docs/IRIS_EXTRACTION_HANDOFF.md b/docs/IRIS_EXTRACTION_HANDOFF.md index f8ab57d..dc4c0d6 100644 --- a/docs/IRIS_EXTRACTION_HANDOFF.md +++ b/docs/IRIS_EXTRACTION_HANDOFF.md @@ -1,288 +1,175 @@ # Iris extraction handoff -Status at 2026-09-13, immediately after pull request #10 was squash-merged. -This is an operational handoff requested by the repository owner. Do not treat -it as a permanent decisions log; remove it after the extraction is complete. +Operational handoff for pulling Iris out of ai-app into a standalone framework. +Not a decisions log; delete it when the extraction is done. + +## Read this first + +**Pull request #11 was reviewed on 2026-09-13 and the review has not been read.** +The session that got it was asked to write this document and stop rather than +spend context on it. So the first thing to do is read it: + +```sh +TOKEN=$(cat ~/.config/gitea/token) +curl -s -H "Authorization: token $TOKEN" \ + https://git.arirex.me/api/v1/repos/iris/iris/pulls/11/reviews +curl -s -H "Authorization: token $TOKEN" \ + https://git.arirex.me/api/v1/repos/iris/iris/pulls/11/reviews//comments +curl -s -H "Authorization: token $TOKEN" \ + https://git.arirex.me/api/v1/repos/iris/iris/issues/11/comments +``` + +Three rounds of review had already landed on #11 before this one, so check the +newest `submitted_at` rather than assuming the first result is current. My +replies to the earlier rounds are ordinary issue comments on the same PR and +say what each change was for. ## Stop point -- Canonical Iris is `git@git.arirex.me:iris/iris.git`. -- The agent-owned fork is `git@git.arirex.me:iris-ai/iris.git`. -- Canonical `main` is at `0f6a28b4dd20d1f6bd745271c5f0926028c8fdb6`, - the squash merge of PR #10. -- **Updated 2026-09-13:** two independent PRs are open against canonical - `main` -- #11 (`split/11-texture-bindings`) and #12 - (`split/12-pointer-routing`, a scroll falling through a hovered button, - not reviewed yet). Both branch from `0f6a28b` and touch disjoint paths, - so either can merge first. Their worktrees are `/home/bob/repos/iris-pr11` - and `/home/bob/repos/iris-pr12`. -- #11 was reviewed `REQUEST_CHANGES` and reworked in response (commit - `0106257`): atlas pages became their own type rather than a `TextureKind` - tag on `Textures`, images went back through the single primitive instance - list instead of a parallel one, group 2 became one array texture plus a - sampler bound per draw run, and masks moved to group 3. Awaiting - re-review. -- `/home/bob/repos/ai-app-2` is on `rustify` at `50d214e` before this handoff - commit. Its worktree was clean. -- `/home/bob/repos/iris-pr10-text` is clean at `983e15c`, the merged PR head. +- Canonical Iris: `git@git.arirex.me:iris/iris.git`, `main` at `0f6a28b` + (the squash merge of #10). +- Agent fork: `git@git.arirex.me:iris-ai/iris.git`. The bot cannot push + canonical; work in the fork and open PRs into `iris/iris:main`. +- **#11** `split/11-texture-bindings`, worktree `/home/bob/repos/iris-pr11`, + head `7b318e3`, eight commits on top of `0f6a28b`. Reviewed four times; + the fourth is unread. +- **#12** `split/12-pointer-routing`, worktree `/home/bob/repos/iris-pr12`, + head `028521b`. A scroll falling through a hovered button. Not reviewed as + of the last check. Independent of #11 and can merge in either order. +- `/home/bob/repos/ai-app-2` is on `rustify`, worktree clean. -## Objective and constraints from the owner +## What #11 became -Pull Iris out of ai-app into a useful standalone UI framework even if the Rust -application switchover is not accepted. App/session/transcript/server behavior -must not leak into Iris; product code belongs in `app/`, and the dependency is -one-way from the app to Iris. +It started as "draw the glyph atlas as an array texture" and the review turned +it into a rework of how primitives are drawn. Worth knowing before reading the +new review, because the earlier rounds are what produced this shape: -The original extraction PR was too large to review. Rebuild it as small, -coherent PRs. Exact commit archaeology is not important, and a slice may be -redone instead of mechanically transplanted. It is acceptable for a rewritten -slice not to remove every old feature. Independent, non-overlapping PRs may be -open concurrently so work can continue while the owner reviews another PR. +- **Atlas pages are their own thing.** `GlyphAtlas` owns its page images and + emits dirty rectangles; `GpuPages` owns the array texture they upload to. + `Textures` holds standalone images only. +- **Every primitive is a registration.** `PrimitiveRegistry::register::

` + takes the primitive's WGSL and what it samples, and returns a + `PrimitiveKind

`. Its list, free list, buffers, bind group layout and + pipeline all follow from that. Rect, glyph and texture are registered the + same way at startup, so a caller registering their own primitive with their + own shader takes the identical path. That is deliberate — the owner wants + custom user shaders later. +- **Nothing dispatches dynamically.** Push, free, renumber, upload and draw are + identical for every primitive; only the entry size and the pipeline differ, + and those are data. `InstanceList` carries a runtime stride and its data as + bytes. Measured: 0.2ns per write over a statically typed list, against 1.6ns + for a trait object. +- **`shader.wgsl` became `shader/prelude.wgsl` plus one file per primitive**, + because one module cannot declare two types at the same binding. The prelude + carries the window, masks, sampled texture, vertex shader and `masked()`. +- **Within a layer, types draw in registration order** — rect under glyph under + texture. Order within a layer was never meaningful (freeing an instance + swaps another into its place), and layers are the compositing mechanism. -The bot cannot push canonical Iris. Work in the `iris-ai/iris` fork and open -pull requests into `iris/iris:main`. Do not recreate an `ai` branch in the -canonical repository; the fork is the isolation boundary. +## Standing instructions from the owner + +- Pull Iris out even if the Rust application switchover is not accepted. No + app, session, transcript, setup or server concepts in Iris; the dependency + runs one way from `app/` to Iris. +- **Small, coherent PRs.** The original extraction PR was too large to review. + A slice may be redone rather than transplanted, and need not remove every old + feature. Independent PRs may be open at once so work continues during review. +- Do not recreate an `ai` branch in canonical Iris; the fork is the boundary. +- **Never rewrite a pushed branch.** Follow review with additive commits. +- Respond to each review finding with a fix or a concise explanation. Do not + add a ceremonial comment when the changed code already answers it. + +## The review gate + +`~/.claude/MACHINE.md` now carries a machine-wide rule, and the procedure is +the installed **`pre-submit-review`** skill. It is not optional and not +project-specific: build clean, review the code, review the comments separately +once the code has settled, then verify the claim by running it. The fixes a +review produces are themselves unreviewed code, so the passes repeat until a +round finds nothing. + +Running it on #11 found four defects that format, clippy, tests and five +headless renders had all passed — including one hidden *by* the tests passing, +where an image alone in a layer failed GPU validation because every other case +happened to have a rectangle in the same layer leaving a bind group set. That +is the shape to hunt for. + +`audit.sh` in the skill directory prints every comment line a branch adds +against a base ref, for an explicit verdict each. The owner's standing +complaint is verbose agent comments; the default verdict is delete. ## Repository topology ### ai-app checkout -- Path: `/home/bob/repos/ai-app-2` -- Remote: `origin = git@git.arirex.me:iris/ai-app.git` -- Branch: `rustify` -- Commit `50d214e` replaced the in-tree `iris/` directory with a submodule. -- The submodule is pinned at `32f6ad8c795ea2badf4ade7a51c2c959e8c96921`, - the complete extracted snapshot. -- `.gitmodules` currently points Iris at the bot fork, not canonical Iris: - `git@git.arirex.me:iris-ai/iris.git`, branch `main`. -- This URL and the submodule pin will eventually need reconciling with the - canonical repository as the split PRs land. Do not change them casually: - ai-app currently needs the complete snapshot, while canonical Iris is only - partially caught up. +- `/home/bob/repos/ai-app-2`, `origin = git@git.arirex.me:iris/ai-app.git`, + branch `rustify`. +- `iris/` is a submodule pinned at `32f6ad8`, the complete extracted snapshot, + and `.gitmodules` points at the **bot fork**, not canonical Iris. +- Do not change either casually: ai-app needs the complete snapshot while + canonical Iris is only partly caught up. Reconcile when canonical contains + what ai-app needs, or when the owner accepts a temporarily non-building pin. ### standalone Iris checkout -- Path: `/home/bob/repos/iris` -- `origin = git@git.arirex.me:iris-ai/iris.git` -- `upstream = git@git.arirex.me:iris/iris.git` -- Local `main` and `origin/main` are the complete target snapshot at `32f6ad8`. - They are deliberately not canonical `main`. -- `origin/archive/full-extraction` also names `32f6ad8` as an explicit safety - copy. -- `history/full` names the corresponding source-history result at `a615bcd`. -- `upstream/main` was fetched after PR #10 and names `0f6a28b`. - -Do not reset, overwrite, or force-push the fork's `main`: it is both the target -reference and the commit pinned by ai-app. Start each new PR branch from the -current `upstream/main` in a separate worktree, and consult -`archive/full-extraction` for the intended final state. - -Existing worktrees under `/home/bob/repos/iris-pr*` retain the already merged -branches. They are useful references but should not be based on for new work. -The old branches remain on the fork; no branch cleanup has been requested. - -## Gitea access and workflow - -- REST token: `/home/bob/.config/gitea/token` (never print or commit it). -- SSH bot key: `~/.ssh/id_ed25519_gitea`. -- The token and account can create/fork repositories and create/comment on PRs. -- The bot can see inline reviews and ordinary PR comments through the Gitea - API. -- Gitea branch protection can express branch-level restrictions, but the owner - chose a fork-and-PR workflow instead. -- PR #10 was merged using **Create squash commit**. That put one combined - commit on canonical `main`; the review/fix commits remain on the fork branch. - -A safe shape for the next branch is: +- `/home/bob/repos/iris`, `origin` = fork, `upstream` = canonical. +- Fork `main` and `origin/archive/full-extraction` both name `32f6ad8`, the + target snapshot. `history/full` names the source-history result `a615bcd`. +- **Do not reset, overwrite or force-push fork `main`**: it is both the target + reference and the commit ai-app pins. +- Start each new branch from current `upstream/main` in its own worktree: ```sh -cd /home/bob/repos/iris -git fetch upstream -git worktree add -b split/10-short-name /home/bob/repos/iris-pr11 upstream/main +cd /home/bob/repos/iris && git fetch upstream +git worktree add -b split/13-name /home/bob/repos/iris-pr13 upstream/main ``` -Push the branch to `origin`, then create the PR from `iris-ai:` into -`iris:main`. Never rewrite a pushed branch; follow review with additive commits. +The other `/home/bob/repos/iris-pr*` worktrees hold merged branches. They are +readable references; do not build new work on them. -There is no persistent review watcher configured. At the start of a new turn, -query open PRs and their reviews/comments before assuming the owner has not -responded. The useful endpoints are: +## Merged so far -```text -GET /api/v1/repos/iris/iris/pulls?state=open -GET /api/v1/repos/iris/iris/pulls/{number}/reviews -GET /api/v1/repos/iris/iris/issues/{number}/comments -``` - -## Merged extraction PRs - -| PR | Result on canonical `main` | +| PR | On canonical `main` | | --- | --- | -| #2 | Build Iris on the current nightly (`4275314`) | +| #2 | Build on the current nightly (`4275314`) | | #3 | Request a frame after resize (`936fbdd`) | | #4 | Decouple `iris-core` from winit (`465e430`) | | #5 | Use vsync by default (`ec2b5d4`) | -| #6 | Notify winit before presenting frames (`db9b0f2`) | +| #6 | Notify winit before presenting (`db9b0f2`) | | #7 | Keep unsafe reference helpers internal (`0191f20`) | | #8 | Initialize the window uniform from the surface (`6e271e8`) | | #9 | Preserve primitive-count recursion (`b90c855`) | -| #10 | Move text layout and rendering to Parley (`0f6a28b`) | +| #10 | Text layout and rendering on Parley (`0f6a28b`) | -`3f92894` and `bf49525` were the starting points for #11 and #12 -respectively. Neither applied cleanly: the base has moved under both, so -each was rebuilt rather than transplanted. Of the three commits named under -"How to choose the next slices", only `6671194` (widget draw size) is still -unclaimed. +URLs are `https://git.arirex.me/iris/iris/pulls/{number}`. -The URLs are `https://git.arirex.me/iris/iris/pulls/{number}`. - -## PR #10 details worth preserving - -PR #10 was the first large cohesive slice. Text buffers, shaping, editing, -rendered glyphs, and the glyph atlas share types, so splitting it further would -have produced artificial broken stages. - -The final PR includes: - -- Parley-based text layout and Swash rasterization. -- Public editing-behavior integration tests in `tests/text_edit.rs`. -- Four retained tests: empty-field input placement, selection replacement, - UTF-8-aware backspace, and IME preedit replacement. -- A `LayoutKey` rather than tuple-shaped cache state. -- Normal Rust string-range validation for deletion, including panics for invalid - ranges instead of silently sorting or clamping them. -- Glyph rasterization and cache lookup factored into focused helpers. -- Standard hashing instead of a handwritten FNV implementation. -- One-pass atlas allocation, checked row copies, `Vec2` UVs, clearer binding - update naming, and colour state owned by `GlyphEntry`. -- Zero-sized and atlas-oversized glyph warnings. Rejected glyphs are negatively - cached, so each glyph/font/size/subpixel/variation key warns once rather than - every frame. `log 0.4.29` was added directly to `iris-core`; the lockfile was - kept minimal rather than accepting unrelated dependency pruning. -- `RenderedText` is owned by the cache and borrowed by callers. It does not use - `Arc`: no external shared ownership was needed, and the old design cloned an - `Arc` both on cache hits and insertion merely to return an owned value. - -All of these passed: +## Choosing the next slice ```sh -cargo fmt --all --check -cargo clippy --workspace --all-targets --locked -- -D warnings -cargo test --workspace --locked -``` - -The final PR branch commits after the main implementation are intentionally -small review responses. Do not mistake them for unreviewed extra scope. The -most relevant review discussion was summarized in PR comments 85, 90, 92 and -94. - -## Current Iris TODO retained by the owner - -PR #10 deliberately leaves these old questions in the root `TODO` file: - -```text -images - settings (sampler) - consider typed TextureHandle variants for distinct texture uses - -WidgetRef or smth instead of Id - enum that's either an Id or an actual concrete instance of W - painter takes them in instead of (or in addition to) id - then type wrapper widgets to contain them - allows for compile time optimization if a widget wrapper's inner is known at compile time - and the id of inner is not needed anywhere - maybe introduce InnerWidget trait to allow for editors to expose & modify inner type - maybe could also store a parent widget and keep using InnerWidget trait? unsure if possible - -vecs for each widget type? - -POTENTIAL BUG: closures that store IDs will not decrement the id!!! need to not increment id if moved into closure somehow??? wait no, need to decrement ID every time an event fn is added...... only if the id is used in it..?? -``` - -Do not prune these merely because newer architecture looks adjacent to them. -The owner explicitly restored them after an over-aggressive TODO cleanup. - -## Review and code-quality expectations - -Run the installed `pre-submit-review` skill before creating or updating any -pull request; the owner asked for a forced mechanism after #11, and it is the -only copy of the procedure. Every slice should get a sanity review, not merely -a successful transplant. -Fix obvious smells, poor naming, needless allocation, awkward state shapes, and -accidental complexity while keeping the slice focused. It is not necessary to -fully understand or redesign every complicated subsystem. - -Comments require special scrutiny. Before submitting or updating a PR: - -1. Enumerate every source comment added by the branch. -2. Remove comments that paraphrase code, narrate history, explain obvious - control flow, or exist only because an agent habitually writes comments. -3. Keep only constraints, non-obvious reasons, invariants, and genuinely useful - API documentation. -4. Re-check comments after responding to review; PR #9 needed a follow-up solely - to remove a trivial comment. - -Tests follow the same restraint: - -- Remove redundant tests that restate implementation details. -- Put valuable public behavior tests in Rust-standard top-level `tests/`. -- Keep inline unit tests only when private internals genuinely require them. -- A small change does not automatically need a new harness. - -Respond to review findings with either a code fix or a concise explanation. -Do not leave unexplained resolutions, and do not add a ceremonial PR comment -when the changed code already answers the review. - -## How to choose the next slices - -Compare canonical main with the archived target: - -```sh -cd /home/bob/repos/iris -git fetch upstream +cd /home/bob/repos/iris && git fetch upstream git diff --stat upstream/main..archive/full-extraction -git diff upstream/main..archive/full-extraction -- ``` -The archived snapshot is a reference, not a patch to apply blindly. Recreate a -change on top of canonical `main`, exclude app-specific behavior, run the code -quality pass, and verify it independently. +The archive is a reference, not a patch to apply. Recreate a change on top of +canonical `main`, leave app-specific behaviour out, and verify it independently. +Pick disjoint path sets when two PRs are open, and branch each from the latest +`upstream/main` rather than stacking. -Broad remaining areas in the target include: +Still in the target and not yet claimed: -- Texture binding/atlas resource organization. -- Widget draw-size and measurement cleanup. -- Pointer routing and shared input behavior. -- Frame diagnostics, staging allocation, and arena delta uploads. -- Retained span, scrolling, and layout placement. -- Retained paints, selection, overlays, and shared UI runtime state. +- Widget draw size and measurement cleanup (source commit `6671194`). +- Retained span, scrolling and layout placement. +- Retained paints, selection, overlays and shared UI runtime state. - Generic desktop/Android framework hosts and reusable example/APK tooling. - Application-owned fonts and application-named font families. - Shared resource-handle bookkeeping and replaceable glyph-atlas buckets. - Positioned text overflow and cluster-safe ellipsis. -- Animation timing, dirty-widget processing, and retained-frame allocation - cleanup. +- **The headless rig** — `scripts/run-headless.sh`, `headless.conf` and + `rig-input` live in ai-app's iris submodule and not in canonical Iris. + Everything below depends on running them from there; extracting them is a + slice of its own. -Useful source-history commits immediately after the original Parley work include -`3f92894` (texture bindings), `6671194` (widget draw size), and `bf49525` -(pointer routing). They are possible starting points, not guaranteed PR -boundaries. Later clean target commits can be listed with: - -```sh -git log --reverse --oneline --first-parent 05c0ac8..archive/full-extraction -``` - -Choose independent path sets when opening concurrent PRs. Avoid stacking PRs -unless a real dependency forces it; otherwise each should branch from the -latest canonical `upstream/main` and be reviewable alone. - -## Project boundaries and verification - -Read `/home/bob/repos/ai-app-2/AGENTS.md` and the machine-wide rules before -working. In particular, read the installed Android and graphics machine skills -before Gradle, adb, emulator, screenshot, UI-trace, or renderer work. - -For a normal Iris framework slice: +## Verifying a framework slice ```sh cd @@ -291,23 +178,33 @@ cargo clippy --all-targets -- -D warnings cargo test ``` -Use `--workspace` when the slice touches workspace crates, as PR #10 did. Any -rendering claim needs the appropriate real run or focused rig in addition to -compilation. Never infer phone frame performance from the debug emulator. +`--workspace` when the slice crosses workspace crates. A rendering claim needs +a real run, which on this machine means the headless rig in ai-app's submodule: -Keep Iris generic. Session drivers, transcript presentation, setup/server -concepts, app icons, and product-owned font assets stay in ai-app. Android and -desktop code is valid Iris work only when it is a generic framework host or -framework-level platform integration. +```sh +cd /home/bob/repos/ai-app-2/iris +./scripts/run-headless.sh tabs --dir /home/bob/repos/iris-prNN \ + --shot /tmp/out.png --seconds 3 +./scripts/run-headless.sh tabs --dir ... --replay /tmp/taps.touch --shot ... +``` -## Final cautions +A `.touch` file is ` down|move|up ` in the output's own pixels; the +script replays it through a virtual pointer. The `tabs` example's five tabs sit +at x = 192, 576, 960, 1344 and 1728 on a 1920x1200 output. Read the +`this-machine-graphics` skill before trusting any of it — the Vulkan device +here comes and goes, and everything silently falls back to software when it +does. -- Preserve the dirty-worktree rule even though the recorded worktrees were - clean: changes found later may belong to the owner or another agent. -- Do not force-push or rewrite any published branch. -- Do not delete the archived full snapshot or the fork `main` that ai-app pins. -- Do not change the submodule remote to canonical until canonical contains the - commit ai-app needs, or until the owner explicitly accepts a temporary - non-building pin. -- Continue using small PRs; the existence of a complete target branch is not - permission to recreate the original giant PR. +## Cautions + +- Read `/home/bob/repos/ai-app-2/AGENTS.md` and the machine-wide rules first. +- Keep Iris generic: session drivers, transcripts, setup and server concepts, + app icons and product fonts stay in ai-app. Android and desktop code is Iris + work only when it is a generic host or platform integration. +- Preserve the dirty-worktree rule. All worktrees were clean at handoff; + anything found later may be the owner's or another agent's. +- Do not delete the archived snapshot or the fork `main` ai-app pins. +- A complete target branch is not permission to recreate the giant PR. +- Another agent was freeing disk on this VM and removed `target/` from the + `iris-pr*` worktrees once. Sources and git state were untouched. Tell peers + before changing shared machine tooling, and expect a cold rebuild sometimes.