Skip to content

feat(scene): each layer has an identity the studio keeps while it runs - #213

Merged
kixelated merged 10 commits into
mainfrom
quest/m1/item-identity
Nov 20, 2026
Merged

kixelated merged 10 commits into
mainfrom
quest/m1/item-identity

Conversation

@kixelated

@kixelated kixelated commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Implements and finishes quest/m1/item-identity.md, replacing the identity rules of moq-dev/studio#194's decisions 10 and 11.

Problem

Keep out of the way keeps a placer per layer, and nothing on an item said which layer it was. compositor::follow matched placers to items after each edit by source, then saved rect, then nearest index, and the engine's moved matched undo and redo by scene, index, and source. Two layers of one source at one rect, as Duplicate makes them, traded placers when a layer was added under both: the new place of the first is nearest the old place of the second. An undo of Keep always on top started a fresh placer. Auto-layout's slot glide paired items by source, so duplicates in slots could glide from each other's places.

Approach

  • Item.id (moq_scene::Id): a counter-made identity, #[serde(skip)], so the scene file never saves it and loading makes each fresh. A clone keeps it, so every edit made to an item, and every undo that puts one back, keeps it. Item's PartialEq leaves it out, by an exhaustive destructure so a new field cannot slip past. Autosave, reload, and every change check behave as before.
  • New items take a fresh one: Item::new, loading, Duplicate, Duplicate scene, paste (Draft::paste), drop, Add, and a guest joining. Validation refuses two items under one identity, so a copy made without a fresh one fails loud rather than sharing a placer.
  • The compositor keys by it: keepers, parked placers, and the grab are HashMap<Id, _>. follow, renamed, Parked, and the source and rect a keeper kept to be found are gone. placement, grab, hold, redone, and undone take an Id. The read pass finds each item keeping clear by identity, even while its scene's slots glide.
  • Parking: a placer whose item stops keeping clear or leaves its scene (removed, Keep always on top) is parked, held, under its identity. Compositor::remember forgets those no undo or redo can bring back; the engine calls it after each edit with the collection's and the history's items (History::items). The watch window, with no history, calls it with each new composition's items, so a picture a composition drops loses its placer at the next. An undo that brings the layer back, from a removal or from the top layer, puts it back where it was.
  • The engine's moved is by identity: a layer keeping clear that an undo, redo, or reload saved at another x or y, switched back on, or brought back. The rename and reorder bookkeeping (was_named, reordered) is gone.
  • The history file saves identities: show.history.toml gains ids, one list of numbers per entry naming each item it holds, so a load knows which mentions are one item through moves, swaps, and changes of source. History::from_toml gives each number one fresh identity, then History::align renames each to the identity the collection holds where an entry replaces or removes that item. The scene file saves none.
  • Reload: Collection::recognize gives a reloaded scene file's items the identities of the items before, per layer: in order (a longest common run) by source and rect, then by source, then out of order, as a reorder by hand leaves them; a renamed scene is matched with the gone scene it shares most with. History::recognize gives the reloaded history's items no layer shows, such as a removed one, the identities the running history had, so its parked placer survives.
  • Glide (glide.rs) pairs items by identity, and the compositor's reflow starts one when a slot's item changes, so duplicates swapping order glide. The watch window recognizes each new composition's collection against the last, so its slots still glide.

Impact

  • No change to what the window shows, the scene file, the wire, or moq/.
  • History file: show.history.toml gains a top-level ids array. A file without it loads, each item new. A build from before this PR refuses a file with it, naming the file; the studio is unreleased, and deleting the file starts a new history.
  • Behavior: duplicates of one camera keep their own places across an insert under both, a reorder, and an undo of a removal or of Keep always on top, which now puts the layer back where it was rather than starting it over. A layer moved into another scene keeps its placer.
  • Public API, moq-scene (unreleased, no !):
    • added Id, Item.id, Collection::recognize, History::align, History::recognize, History::items, Compositor::remember;
    • Compositor::placement(id), grab(Option<Id>, now), hold(id), redone(id, saved), undone(id, saved, now) take an Id in place of a scene, index, and source.
  • Cost: an Id is 8 bytes per item. remember walks the history's items after each edit only while a placer is parked (at most 100 entries).

Alternatives

  • More matching heuristics (rejected by the maintainer on feat: a layer that keeps out of the way #194): every rule on content trades duplicates in some edit.
  • Keeping identity by position on a replace (Change::Item applying keeps the old item's id): simpler history loading, but a swap into a slot, two set_items, would trade identities.
  • Aligning a loaded history by content (rounds 1 to 3 of this PR): each rule, alike then by source, the same change first, left a case (a swap of two layers of one source, a change of source) where a layer took another's identity. Saving the identities is exact; see the Design change.
  • A fallback to pairing by source in glide for items whose ids differ: only the watch window needed it, and recognizing its layouts keeps duplicates apart there too.

Caused by

  • moq-dev/studio#194 - matched placers to items by source, saved rect, then nearest index, so duplicates at one rect trade placers when a layer is added under both, and an undo of Keep always on top starts over (found by reviewer; accepted there as decision 10, with this quest as the follow-up)

Follow-ups

None. The quest file is deleted; nothing linked to it.

Validation

  • just ci passes at 72583e8: fmt, clippy, and 489 tests.
  • just render-sw passes on lavapipe at 72583e8 (75 + 20 + 14 + 1), with all 75 moq-scene GPU tests, including the new compositor::tests::duplicates_keep_their_own_placers: two cameras of one source at one rect, one in its slot (TopLeft) and one held by hand, keep their own placers as a hidden layer is added under both, as they swap order, and after a removal or Keep always on top that an undone puts back (back in its slot); once remember leaves it out, a parked placer starts over. With feat: a layer that keeps out of the way #194's rule, the insert hands the held one's keeper to the one in its slot (the new place of each is nearest the other's old one).
  • On lavapipe, engine::tests::an_undo_puts_back_a_layer_keeping_clear passes: through the real engine, an undo of a move by hand puts back the place, a redo holds, and an undo of a swap into a slot takes back the held placer.
  • just shots build_keep_clear build_keep_clear_compact build_drop pass; the facecam still glides off the HUD to the bottom right and BUILD draws it there, found by identity.
  • A property check, second and independent: edit::tests::every_point_of_a_history_keeps_its_identities makes 60 random edits of one layer (copies alike but new, removals, moves, swaps by two changed replacements, changes of source, rect edits), then seeks to 40 random points: each has the identities it had. After a save and reload of the scene file and history, 80 more seeks check that each point holds the same items, each under one consistent new identity. It fails with the saved ids ignored on load, and with History::align taken out.
  • edit::tests::a_loaded_history_aligns_past_a_swap (fails without its fix) and a_reloaded_history_keeps_what_it_removed.
  • collection::tests::a_reload_recognizes_each_item: an unchanged file's reload gets every identity back, duplicates included; a layer added under the duplicates, a moved one, a renamed scene, and a reorder by hand keep the rest themselves.
  • glide::tests::duplicates_glide_from_their_own_places: two of one source swapping places each glide from their own.
  • compositor::tests::duplicate_tiles_swapping_places_glide (lavapipe): two tiles of one source that swap order each glide from their own place, through the compositor's reflow, whose key now names each slot's item by identity. It fails with that key's identity held constant (each tile jumps). All 77 moq-scene GPU tests pass on lavapipe.
  • engine::tests::an_undo_or_a_reload_moves_by_hand: moved by identity, across a swap of order in a renamed scene, and for a layer brought back from a removal or from the top layer.
  • watch::tests::a_dropped_picture_forgets_its_placer (lavapipe, in just render-sw): a keep-clear picture a composition drops has its placer parked, then forgotten at the next composition. Ported onto feat(scene)!: the studio publishes a composition #146's composition after the merge of main; it fails with the remember call taken out.
  • After merging main (feat(scene)!: the studio publishes a composition #146, feat: browser sources on macOS #206, feat(studio): markers on REVIEW, with a clip around each #209, refactor(scene): one readback for the compositor's small GPU reads #211, feat(studio): time both formats' encodes together #214): just ci passes (511 tests), and the moq-studio half of just render-sw passes on lavapipe (22 tests, including a_dropped_picture_forgets_its_placer and plays_a_guest_where_the_studio_did).
  • Not exercised by hand in the running window: the change shows nothing new, and the engine test drives the real engine and compositor.

Decisions

Taken under /quest-afk as my recommendation; each is open to overturn in review.

  1. Reload matching is order-preserving first, not feat: a layer that keeps out of the way #194's nearest-index rule. The Plan said a reload of the scene file matches "by the same rule follow uses", but that rule trades duplicates when a layer is added under them, the bug this quest removes. recognize matches each layer's items in order (longest common run), then the rest out of order as feat: a layer that keeps out of the way #194 did. Rejected: the nearest-index rule alone, as planned.
  2. The history file saves identities (ids), so an undo after a restart or reload keeps each layer's own through moves, swaps, and changes of source. The quest said only that the scene file never saves them. Rejected: aligning by content (rounds 1 to 3 kept finding cases), and leaving a loaded history's items new (every undo after a restart would start a layer's placer over). Design change; also the round-3 review checkpoint, taken as continue.
  3. Two items under one identity are refused by validation, so a copy that forgot a fresh one fails at once. Rejected: a debug assertion, which release builds skip.
  4. Parked placers live while the collection or the history holds the item (Compositor::remember), bounded by the history's 100 entries. Rejected: forgetting a placer once its item leaves the collection, which loses it before an undo of a removal.
  5. A layer moved into another scene keeps its placer, and one whose source changes is the same layer. Rejected: starting over on a scene change.
  6. Glides pair by identity alone; the watch window recognizes each composition against the last. Rejected: a source fallback in glide.rs.
  7. Each picture the watch window reads from a composition takes a fresh identity (carried from the layout code onto feat(scene)!: the studio publishes a composition #146's collection(composition, size, &paths)), then recognize gives back those the last composition showed. ✅ fresh per picture (rejected: keeping the picture's own id, which a stored composition reuses across renders and duplicates when one item is placed twice, as the test fixture does, so validation would refuse it). The studio's Composition::new keeps its items' ids on the pictures it publishes; they are never serialized, so that is harmless.
  8. The justfile nextest filter keeps this PR's test(/^watch::tests::/), which covers main's plays_a_guest_where_the_studio_did too. ✅ the prefix (rejected: listing each watch test, which a new one would slip past).

Models

Size: M
Implementer: Claude Code, claude-opus-5-5, medium effort (arm A)
Implementer: Claude Code, claude-opus-5-5, medium effort (iterate, S, arm A)
Implementer: Claude Code, claude-opus-5-5 (iterate, S, arm A)

🤖 Generated with Claude Code

(Written by Claude Opus 5.5)

Review

Rewritten by quest review after each round.

  • Head: e5b1905

  • Base: origin/main at 6c7da41

  • Risk: medium, the base has no RISK.md to name what is always high or customer-facing, so every change is medium

  • Classified: medium by default

  • Reviewer: Codex, gpt-6.1-sol, high effort

  • Session: 01a1f72b-a5b9-7940-b3ac-318fb5966bd0, round 2

  • Score: 10/10, The production reflow key now includes item identity, resolving the prior finding, and the incremental changes introduce no new issues on code inspection; tests were not run.

  • Rounds: 7; first round 3 (medium 3); findings 7 (medium 7): fixed 7, refuted 0, open 0

  • Findings: none

  • The last round's findings, at 195fa80:

    • Fixed: medium, rs/moq-scene/src/glide.rs:70: Include item identity in the production reflow key; In rs/moq-scene/src/compositor.rs, reflow now keys each slotted item by (id, source, visible, rect), and duplicate_tiles_swapping_places_glide checks that same-source tiles retain their own starting positions when reordered.
  • Reviewer: Codex, gpt-6.1-sol, medium effort, shadow

  • Session: 01a1f411-c81a-76a0-81cb-ea841ff86287

  • Rounds: 4; first round 1 (medium 1); findings 2 (medium 2): fixed 2, refuted 0, open 0

kixelated and others added 2 commits November 19, 2026 04:16
Quest-Claim: 72483bc6b5d392a8
Items carry a runtime Id, never saved and ignored by equality. The
compositor keys keep-clear placers, parks, and grabs by it; glides pair
by it; undo, redo, and a reload keep it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Each layer has an identity the studio keeps while it runs feat(scene): each layer has an identity the studio keeps while it runs Nov 19, 2026
kixelated and others added 4 commits November 19, 2026 06:00
…d reorder

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Aligning a loaded history by content could not tell swapped or re-sourced
layers apart; numbering each item in the file makes the link exact.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Contributor Author

Design change: a loaded history's item identities come from the history file, not from matching content.

Rounds 1 and 2 of the local review each found a case where aligning a reloaded history's items to the collection by content gave a layer the wrong identity: a move (a removal plus an insertion), a swap of two layers of one source by two replacements, and a change of source. Each content rule left another case. The history file now saves each item's identity as a number (ids, one list per entry), so a load knows which mentions are one item, and History::align only renames each number's identity to the one the collection holds there. The scene file still saves none.

At the round-3 checkpoint I compared this with the alternatives: keeping content matching (the class of findings above stays open), or giving up identity across a restart (every undo after a restart would start a layer's placer over, a regression from #194). Saved numbers are the simplest exact answer; the round-3 finding was a one-line bug in it, fixed. Taken under /quest-afk as my recommendation: continue. Open to overturn in review.

(Written by Claude Opus 5.5 with medium effort)

@kixelated
kixelated marked this pull request as ready for review November 19, 2026 14:16
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 20 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 2940e41d-b1fc-4cac-b07b-8088a4f74350
Commits

Reviewing files that changed from the base of the PR and between 6c7da41 and e5b1905.

Files selected for processing: 17

  • justfile
  • quest/m1/item-identity.md
  • rs/moq-scene/src/clip.rs
  • rs/moq-scene/src/collection.rs
  • rs/moq-scene/src/compositor.rs
  • rs/moq-scene/src/edit.rs
  • rs/moq-scene/src/format.rs
  • rs/moq-scene/src/glide.rs
  • rs/moq-scene/src/lib.rs
  • rs/moq-scene/src/place.rs
  • rs/moq-studio/src/engine.rs
  • rs/moq-studio/src/shots.rs
  • rs/moq-studio/src/ui/build.rs
  • rs/moq-studio/src/ui/inspector.rs
  • rs/moq-studio/src/ui/keep.rs
  • rs/moq-studio/src/ui/slots.rs
  • rs/moq-studio/src/watch.rs
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ No critical issues. One minor leak is noted inline.

Approach: Sound. Keying placers by a runtime Id, kept by clones and minted fresh by copies, fixes #194's duplicate-swap at its cause instead of adding another matching heuristic. Saving ids in the history file is an exact answer to the alignment cases that matching by content kept missing.

Reviewed changes

I reviewed all 16 files at 72583e8. I followed every studio path that inserts or replaces items, the Move transition, portrait turning, and apply_outside.

  • Item.id / Id: a counter-made identity that serde skips and Item's PartialEq leaves out. Collection::validate refuses two items with the same identity.
  • Fresh identities on copies: Duplicate, scene_copy, clip paste, and the watch window's layouts take a fresh Id. Add, drop, and guests go through Item::new. I found no insert path that clones an item without one. The slot swap's two set_items share an id only until finish validates.
  • Compositor keyed by Id: keepers, parked, and grabbed are keyed by Id. follow and renamed are deleted. remember prunes parked placers that no undo or redo can bring back.
  • Engine moved: matches by identity across layers, so items brought back from a removal or from the top layer are noted.
  • History ids and align / recognize: the history file saves the numbers. On load, each number gets one fresh Id, and replaying undo and redo renames them to the collection's ids. On reload, Collection::recognize and History::recognize restore the running identities.
  • Glide: pairs by id. The scene-to-scene Move transition (Compositor::moving) still pairs by resolved source and is unaffected.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

Comment thread rs/moq-studio/src/watch.rs Resolved
Its compositor parked the placer of a picture keeping clear that a layout
dropped and never freed it, since only the engine called remember. Each
new layout now remembers only the items it shows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
pullfrog[bot]
pullfrog Bot previously approved these changes Nov 19, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found. The watch window leak from the last review is fixed.

Reviewed changes

This run covers 2f1ba12, the one commit since the prior Pullfrog review at 72583e8.

  • Watch window forgets dropped placers: after recognize, Watch::render calls Compositor::remember with the ids of every item in the new layout. A keep-clear picture that a layout drops is parked at that render, then freed when the next layout arrives.
  • Regression test: added watch::tests::a_dropped_picture_forgets_its_placer. It checks that undone cannot bring back a placer once it has been forgotten. The just render-sw filter now runs watch::tests:: on lavapipe.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated
kixelated enabled auto-merge (squash) November 20, 2026 01:07
@kixelated
kixelated disabled auto-merge November 20, 2026 04:08
kixelated and others added 2 commits November 19, 2026 20:09
# Conflicts:
#	justfile
#	rs/moq-studio/src/watch.rs
…ng places glide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found. The merge of main and the reflow key fix both look correct.

Reviewed changes

This run covers 195fa80 and e5b1905, the commits since the prior Pullfrog review at 5c771e4.

  • Ported the watch window onto compositions: collection(composition, size, &paths) gives each picture a fresh Id. Watch::render still calls recognize and then remember on the composition it applies, so a_dropped_picture_forgets_its_placer keeps its meaning after the move to Composition. The just render-sw filter keeps a single test(/^watch::tests::/), which also covers main's plays_a_guest_where_the_studio_did.
  • Added identity to the reflow glide key: reflow now keys slots by (id, source, visible, rect), so two tiles of one source that swap places start a glide. Nothing mints a fresh Id per frame for scene items that feed reflow, so the new key cannot restart glides on every frame. duplicate_tiles_swapping_places_glide checks each tile halfway between its two places.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated
kixelated merged commit 879ede7 into main Nov 20, 2026
4 checks passed
@kixelated
kixelated deleted the quest/m1/item-identity branch November 20, 2026 04:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant