iris/ai-app
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite the Iris extraction handoff for a fresh session

Browse Source 
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.
This commit is contained in:
iris committed 2026-09-13 15:50:09 -04:00
1 parent bc555f9ded
commit 26f86bc6f7
1 file changed
+155 -258
Download Patch File Download Diff File Expand all files Collapse all files
docs/IRIS_EXTRACTION_HANDOFF.md
+155 -258
View File
@@ -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/<id>/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::<P>`
takes the primitive's WGSL and what it samples, and returns a
`PrimitiveKind<P>`. 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:<branch>` 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<T> variants for distinct texture uses
WidgetRef<W> 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 -- <focused paths>
```
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 <iris-worktree>
@@ -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 `<ms> down|move|up <x> <y>` 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.