Close manual input gate and define target-runtime implementation sequence

README.md

@@ -50,7 +50,7 @@ These graphical checks require a macOS desktop session; other platforms are not
 ## Implementation references
 
 - [Initial project contract](docs/initial-project-contract.md): module responsibilities, configuration, snapshots, runtimes, preview sessions and communication.
-- [Repository bootstrap plan](docs/repository-bootstrap-plan.md): ordered work packages and acceptance gates. Bootstrap work packages 1–7 are implemented; source-preserving projection is implemented, with physical drag/drop still requiring manual qualification. Next implementation stage: target-runtime sessions, sizing and navigation.
+- [Repository bootstrap plan](docs/repository-bootstrap-plan.md): ordered work packages and acceptance gates. Bootstrap work packages 1–7 are implemented; source-preserving projection is implemented and its [manual drag/resize gate](docs/manual-input-validation.md) passed in both hosts on the recorded baseline. Next: [target-runtime sessions, sizing and navigation](docs/target-runtime-stage-plan.md).
 - [Decision provenance](docs/provenance.md): workspace planning and captured prototype evidence.
 - [Third-party notices](THIRD-PARTY-NOTICES.md): Maven wrapper and patched Kit source provenance.
 

docs/manual-input-validation.md

@@ -0,0 +1,35 @@
+# Manual input validation: standalone and IntelliJ
+
+Status: **passed; the stage-2 physical drag/resize validation gate is closed for the tested baseline**. Konrad performed the tests with physical mouse input and reported each result in the development conversation on 2026-11-12. This record complements the automated projection checks; it does not turn synthetic events into hardware evidence.
+
+## Artifact and environment
+
+- Source-preserving projection: `dfa2dd1`; corner-resize correction: `b9d59e162f0df20057d50b5d0ec4ef54cc92d73e`, on NeitzelFXDesigner main.
+- macOS arm64; host OpenJDK 25.0.5.0.3, JavaFX 26+27 and Scene Builder Kit 26; IntelliJ IU 263.7307.200 with bundled embedding disabled and JavaFX/FXML language support retained.
+- Classpath fixture application on Java 21 / JavaFX 21.0.7, using the recorded corrected NeitzelLib development artifact. Module-path applications additionally pass the automated shared-host checks; no separate human module-path pass is claimed.
+- Disposable Person.fxml with an AnchorPane and two independently editable Card instances. Standalone retest labels: **Corner resize retest** and **Second**. IntelliJ labels: **Drag me** and **Second**.
+
+## Human results
+
+| Check | Standalone | IntelliJ |
+| --- | --- | --- |
+| Drag first Component; release retains position and responsive canvas | Passed | Passed |
+| Undo/Redo drag with one action each; other Component unchanged | Passed | Passed |
+| Drag second Component independently; Undo/Redo preserves first | Passed | Passed |
+| Corner resize first Component; width and height persist together | Passed after correction | Passed |
+| Corner resize second Component; independent Undo/Redo | Passed after correction | Passed |
+| Right edge changes only width; bottom edge changes only height | Passed | Passed |
+| Edge resize persists on release; one-action Undo/Redo | Passed | Passed |
+| Save and Source/Design switch preserve both declarations and layout | Passed | Passed |
+| Saved prefWidth/prefHeight survive reopening; selection/resizing still works | Passed | Passed |
+| IntelliJ Edit menu and keyboard shortcuts undo/redo the drag | Not applicable | Passed |
+
+The original standalone corner gesture persisted only width. Kit emits separate synchronous jobs for each changed dimension; an asynchronous host transaction started after the first notification dropped the second. The correction collects the completed FX event turn into one source-preserving transaction. Both Components were explicitly retested, including save/reopen. See [projection implementation](source-preserving-projection.md#corner-resize-correction-and-manual-review).
+
+## Gate boundary and remaining evidence
+
+This closes the pending human OS drag/drop and resize gate for stage 2 on this fixture/platform. No additional repetition of the same checklist is required before stage 3. Keep the shared automated regression in both hosts and repeat the affected manual checks when input/projection/host changes warrant it.
+
+It does not qualify every control/container, trackpad/horizontal scrolling, IME, display scaling, other operating systems or IDE versions, packaged releases, or the forthcoming nested/repeated/Table runtime behavior. VoiceOver remains outside the agreed scope. One earlier automated IntelliJ run failed a later save-preservation assertion; the next complete run passed. The assertion now records expected/actual text if it recurs; these human save/reopen passes do not establish its cause.
+
+Next: [target-runtime sessions, sizing and Component navigation](target-runtime-stage-plan.md).

docs/repository-bootstrap-plan.md

@@ -94,4 +94,4 @@ Do not label these packages as additional unresolved Wayfinder decisions: the ar
 
 ## After bootstrap: source-preserving projection
 
-Roadmap stage 2 now has source-range transactions, broader Component projection and shared live checks in both hosts. See [implementation and qualification boundaries](source-preserving-projection.md). Physical drag/drop delivery remains an explicit manual gate; the automated suite exercises Kit relocation commands and resize-handle gestures. The next implementation stage is target-runtime sessions, sizing and navigation.
+Roadmap stage 2 now has source-range transactions, broader Component projection and shared live checks in both hosts. See [implementation and qualification boundaries](source-preserving-projection.md). The [human standalone and IntelliJ review](manual-input-validation.md) now closes the physical drag/drop and resize gate on the recorded macOS baseline, including the corner-resize correction at `b9d59e1`. Broader platform/input coverage remains separate. Continue with the [stage-3 implementation plan](target-runtime-stage-plan.md): retained target sessions, occurrence identity and sizing, shared canvas refresh, Component/Row navigation, and separate interactive previews.

docs/source-preserving-projection.md

@@ -49,7 +49,7 @@ The live scenarios cover exact source preservation, nested/fully qualified/anony
 
 Verified on 2026-11-12: **65 tests** (58 Maven, seven IntelliJ), zero failures/errors/skips, plus the retained 346 target assertions in 24 JVMs, 14 Build and Refresh checks and 64 connected workflow assertions. Both native standalone layouts and both real registered IntelliJ layouts passed the shared projection scenarios. The final unchanged-property/entity-spelling and missing constraint-import regressions passed in the subsequent Maven/IDE builds. Plugin packaging, dependency/bytecode boundaries, test-artifact exclusion and documentation checks pass. Both isolated IDEs loaded exactly one Glass library with the recorded JavaFX 26 artifact hash. Evidence remains under `target/connected-workflow/` and `target/ide-workflow/`. The intentional SDK until-build warning is unchanged.
 
-Physical OS drag-and-drop delivery is **not qualified by this automated result**. Synthetic mouse events cannot start JavaFX's native dragboard; a desktop Robot attempt did not result in a document move, including after bringing the test process to the foreground. The suite therefore tests the actual Kit relocation command separately from resize-handle events. A human drag/drop check in both hosts remains part of stage-2 platform qualification.
+Physical OS drag-and-drop delivery is **not qualified by this automated result**. Synthetic mouse events cannot start JavaFX's native dragboard; a desktop Robot attempt did not result in a document move, including after bringing the test process to the foreground. The suite therefore tests the actual Kit relocation command separately from resize-handle events. The subsequent [human review](manual-input-validation.md) passed physical drag/drop and resizing in both hosts, closing that gate on the recorded baseline.
 
 ## Corner-resize correction and manual review
 
@@ -63,10 +63,10 @@ python3 scripts/check-corner-resize.py --target-java-home "$TARGET_JAVA_HOME"
 
 The focused regression, Maven tests, IntelliJ adapter tests/plugin build, both connected standalone layouts and both registered IntelliJ layouts passed with the correction. One earlier IDE run failed the later save-preservation assertion after the corner checks passed; this did not reproduce on the next complete run. The save assertion now reports expected and actual source for investigation if it recurs.
 
-The corner fix still needs the user's physical mouse retest. IntelliJ physical drag/drop review remains pending. The automated resize gesture is evidence for the transaction fix, not a substitute for these manual checks.
+The user subsequently passed the physical corner retest for both Components in both hosts, including one-action Undo/Redo and save/reopen. The [manual input record](manual-input-validation.md) closes this bounded gate; automated gestures remain separate evidence.
 
 ## Remaining boundaries
 
 This stage preserves arbitrary source, but does not make arbitrary structure visually editable. Insert/delete/reparent, binding-aware renames and subtree copy/paste require later structural transactions. Application wildcard imports, `fx:include`, scripts and unrepresentable roots retain source fallback. Arbitrary target properties use declared FXML text editing until shared discovery supplies typed metadata. Anonymous identities are local to a projection revision, not the persistent occurrence identities needed for repeated/Table Components. Target node lookup still uses the initial CSS-ID route; separate CSS IDs and repeated/internal scopes need stage 3's occurrence identity work.
 
-Qualification remains scoped to the recorded macOS arm64 / IntelliJ 263.7307.200 / JavaFX and Kit 26 host baseline and Java 21 / JavaFX 21.0.7 application fixtures. Product packaging, a broader platform matrix, lossless structural editing and physical drag/drop qualification are not implied. Next implementation stage: target-runtime sessions, sizing and navigation, while retaining the explicit manual stage-2 input gate.
+Qualification remains scoped to the recorded macOS arm64 / IntelliJ 263.7307.200 / JavaFX and Kit 26 host baseline and Java 21 / JavaFX 21.0.7 application fixtures. Product packaging, a broader platform matrix, lossless structural editing and wider input qualification are not implied. The stage-2 physical input gate is closed on the tested baseline. Next: [target-runtime sessions, sizing and navigation](target-runtime-stage-plan.md).

docs/target-runtime-stage-plan.md

@@ -0,0 +1,79 @@
+# Target-runtime sessions, sizing and Component navigation
+
+Status: implementation plan for roadmap stage 3; **not implemented or qualified by this document**. Stage 2's [manual input gate](manual-input-validation.md) is closed on its recorded baseline. This work implements the accepted preview and host contracts; it does not reopen them as Wayfinder decisions.
+
+## Current implementation and gaps
+
+| Area | Existing code | Work required |
+| --- | --- | --- |
+| Session ownership | DesignerWorkflow starts a worker per render batch; its finally block closes it. A batch shares one parent Model graph. | Retain one worker per immutable parent snapshot for measurement/render requests; replace it when snapshot inputs change. |
+| Request scheduling | Generation checks reject obsolete UI results; each render cancels the preceding worker. | Serialize requests within a session, coalesce pending size requests, bound cancellation and shut down replaced workers. |
+| Target lookup | TargetPreview uses root.lookup with a CSS ID. Anonymous projection IDs are inserted only into draft overlays. | Scoped occurrence identities independent of CSS IDs, including nested/repeated/row instances. |
+| Sizing | TargetPreview resizes the root and requested node to each image size; SnapshotRegion defaults to 300 by 220. | Target min/pref/max, baseline and content-bias measurements; parent allocation; bounded convergence and reflow. |
+| Drafts | Captured parent and known/open FXML overlays, build leases and revision checks already exist. | Make their identity the session boundary; track affected resource dependencies and refresh/restart across open editors. |
+| Navigation | componentSource searches reactor source roots by class-name convention; hosts open a URI. | Resolved source/origin metadata, inherited context, editor reuse, JAR read-only resources and attached-source ownership. |
+| Interactive preview | TargetPreview exposes its loaded View to target-side tests. No product interactive-preview action exists. | Separate owned JVM/window, sample selection, fresh-state restart, controller actions and cleanup. |
+
+## Implementation order
+
+### 1. Retained rendering sessions and request lifecycle
+
+Introduce a shared session owner beneath DesignerWorkflow. A session captures context, successful build identity, selected example, preview mode, and the exact parent/dependency draft revisions and content used in its overlay. Do not use size as the snapshot identity: new allocated sizes are requests against the same loaded Model graph. A new build, example or affected draft creates a fresh worker/JVM and fresh Models/services. Discovery remains non-constructing and independent of the rendering session.
+
+Use explicit starting, ready, replacing, failed and closed states. One worker socket has one request stream. Keep at most the latest queued sizing/render request for an occurrence; reject obsolete running responses by session identity, host revision ordering and request generation. Cancellation must interrupt blocking transport without waiting for the FX thread. Retain snapshot leases until actual worker exit. Replace the current whole-operation watchdog with bounded startup/readiness/request/shutdown deadlines suitable for a retained idle session. Expose timeout settings through validated configuration rather than unbounded waits.
+
+**Acceptance:** same-snapshot measurement/render requests have one PID and one provider construction; new example/build/draft has a different PID and fresh state. Rapid requests cannot accumulate workers or apply stale pixels. Timeout, crash, cancel, owner death and close release workers/leases. Closing one editor/project cannot terminate another's session. Include a failed build and explicit last-successful-build selection.
+
+### 2. Occurrence identity and target measurement protocol
+
+Extend the independently versioned negotiated protocol with measurement/occurrence capabilities. Keep bytecode and API boundaries intact. Unknown required capabilities disable the affected feature with source editing available. Preserve existing payload/image limits and validate finite dimensions, unbounded maximum-size representation, content bias and baseline semantics.
+
+Return a snapshot-local opaque occurrence identity plus source declaration/origin and parent/repetition scope. Never overload fx:id or CSS id as global runtime identity. Register actual loaded Component occurrences after readiness, including nested and repeated instances; distinguish the shared Row source from each visible Table occurrence. This is runtime identity/navigation work, not stage 4's binding metadata editor. Parent canvas internals stay opaque and select their outer Component.
+
+Measurements include min/pref/max sizes, baseline, content bias and width-dependent preferred height (and the corresponding height-dependent case). Measure real target nodes after CSS/layout. Host Kit parents and explicit constraints determine allocated size; requests capture at that allocation without resizing the entire parent to each child image size or rebinding the child Model.
+
+**Acceptance:** separate CSS IDs, duplicate local fx:ids in different scopes, anonymous Components, nested/repeated occurrences and Table row reuse remain distinguishable. Wrapping text reacts to width; explicit constraints and baseline remain correct. Invalid measurements fail with diagnostics. No application class is loaded into either host.
+
+### 3. Shared canvas layout and refresh
+
+SnapshotRegion consumes target measurements as computed layout values; do not write derived measurements into authoritative FXML. Keep the last usable image/layout and an updating indicator while measurement/render work is pending. Bound the measure/allocate/render cycle with tolerances and an iteration budget; retain the last stable result and diagnose oscillation instead of repeatedly resizing. Accept only results for the current session, document set and allocation generation.
+
+Capture current parent and open Component drafts together. Track affected dependencies so Component saves refresh open parent canvases and restart affected interactive previews with fresh sample data. A failed parent load fails the entire runtime snapshot; retained images must be marked stale and cannot imply a partially successful load. Provide selectable diagnostics and Retry while the host document remains editable.
+
+**Acceptance:** latest size wins during rapid resize; no UI-thread blocking; no source changes from target measurements. Unsaved parent/child overlays render together. Shared Model identity survives measurement within a snapshot. Failed parent/child loads, missing values, asynchronous readiness and non-converging layouts produce bounded recoverable results.
+
+### 4. Component and Row navigation in both hosts
+
+Resolve the selected occurrence to its declared Component/Row source and origin, not to an arbitrary first class-name match. Preserve the parent draft and inherited application context. Reuse the authoritative open document and an existing child editor; otherwise open a separate designer tab/window. A Component opened independently selects from its compatible named examples. Do not render a child editor using the parent's unrelated default example.
+
+For JAR-only resources provide a read-only editor with origin information. Prefer attached project source only when its owning project/context is identified; do not make extracted cache files writable application sources. Ambiguity is visible and requires a selection, not a guessed resource. Open Row Component is explicit and does not rearrange a shared layout. Related Java types navigate through the host's source service.
+
+**Acceptance:** parent → AddressForm → NoteForm, repeat/row source navigation, repeated opens, unsaved edits, same document through aliases, read-only JARs, attached sources and two contexts/projects. Returning to the parent preserves its draft, selection and native undo history.
+
+### 5. Separate interactive preview and end-to-end qualification
+
+Use a separate JVM/session for interactive preview, with the same exact captured draft/build provenance and its own fresh example Model/services. Show the running revision and stale/update state. Controller actions, conversion failures and Table selection/sorting/filtering execute only there. Restart affected previews from fresh examples after saves; terminate them on owner close/crash with the reserved lifetime channel.
+
+Expand the real classpath and module-path fixtures to Person.home → AddressForm → NoteForm, repeated visits and Table rows. Include shared Model references, empty/null values, readiness success/failure/timeout, service actions and conversion failures. Run the same scenarios in standalone and the registered IntelliJ designer, preserving stage-2 source/input regressions. Add focused human checks for navigation and interactive behavior once those features are runnable.
+
+**Exit:** all stage-3 scenarios above pass with artifact identities and logs in both hosts. Existing simple Card rendering and the completed drag/resize review do not close this gate. Structural authoring, binding editing, generated ViewModels/Views, coordinated handoff and packaging remain their later stages.
+
+## Ownership flow
+
+```mermaid
+flowchart LR
+    D[Host documents and draft revisions] --> S[Immutable parent snapshot]
+    B[Leased successful build] --> S
+    E[Selected example and services] --> S
+    S --> W[Retained target worker: one Model graph]
+    W --> O[Scoped occurrences and measurements]
+    O --> K[Shared Kit parent layout]
+    K --> R[Coalesced allocated-size request]
+    R --> W
+    W --> P[Correlated pixels]
+    P --> K
+    O --> N[Host Component / Row navigation]
+    S --> I[Separate interactive worker]
+```
+
+The broader accepted roadmap remains linked from [provenance](provenance.md#broader-roadmap). The first implementation step is retained rendering sessions and their lifecycle tests; measurement and navigation build on that ownership boundary.