NeitzelFXDesigner/docs/target-runtime-sessions.md

# Target-runtime sessions, sizing and Component navigation

Stage 3 extends the shared workflow used by standalone and IntelliJ. The [implementation sequence](target-runtime-stage-plan.md) records the accepted scope. Qualification below distinguishes automated checks from the remaining human review of the new actions.

## Session and request ownership

A retained canvas session owns one target JVM, private draft overlay and lease on one successful build. Its key contains build identity, selected example, the exact captured document set (including content/revisions), and explicit retained-build selection. Allocated dimensions are request inputs, not a reason to construct another Model graph. A changed key replaces the worker. A crashed worker is replaced on retry.

`LatestSession` runs one operation at a time and keeps one replaceable pending operation. Superseded futures fail with cancellation; host generation and document checks reject obsolete results. Replacement and cancellation close transport independently of the FX thread. Client continuations run outside the session lock. Idle retained workers have no whole-session deadline; startup, readiness and individual requests remain bounded. A snapshot lease is released only after the process has actually exited, including delayed forced termination.

Configuration 1.0 accepts optional `preview.requestTimeoutSeconds` (default 30) and `preview.readinessTimeoutSeconds` (default 20), each from 1 to 300; readiness cannot exceed the request deadline. These values do not select a different JVM or weaken the owner-lifetime channel. Discovery still reads metadata without constructing application objects.

Interactive preview uses another workflow and another JVM/Model graph. **Interactive preview** captures current drafts and opens the target window; **Stop preview** terminates it. Its title identifies example, build and captured revisions. Closing the target window releases that session and stops automatic reopening. Unsaved document edits mark an interactive preview outdated while preserving its sample state. Explicit rerun or a resource save restarts it with fresh sample data. Canvas previews continue to refresh from drafts. No application class is loaded into either host.

## Identity, measurement and pixels

The optional negotiated `layout-v1` capability adds MEASURE and OCCURRENCES operations; `interactive-v1` adds INTERACTIVE. Existing operation ordinals and raw RGBA rendering remain compatible. Metadata operations carry session/build/document/size correlation without claiming a pixel payload. Required incompatible capabilities fail negotiation.

Private parent overlays attach target-only declaration keys to projected nodes; authoritative FXML and CSS IDs remain unchanged. The worker gives live nodes opaque session-local occurrence IDs and reports their parent scope, declared key, actual type and Component resource origin. Nested and repeated instances have separate identities. Detached nodes are pruned and an instance whose Model changes receives a new identity. Legacy callers may use a CSS ID only when it identifies exactly one node. Treat occurrence IDs together with their worker session, never as durable project IDs.

Measurements return min/pref/max dimensions, baseline and content bias. Width-dependent preferred height and height-dependent preferred width are queried at the requested allocation. Finite `Double.MAX_VALUE` means an unbounded maximum; invalid/non-finite measurements fail validation. SnapshotRegion uses these values only for computed layout, not saved attributes.

The Kit parent and explicit constraints allocate size. Target capture temporarily makes the selected resizable node unmanaged so a parent layout during snapshot cannot overwrite that allocation; it restores managed state afterward and does not resize the entire parent for each child. A bound managed property currently produces an explicit diagnostic instead of silently capturing at the wrong size. Retained images remain visible during asynchronous updates. Target layout passes and host measurement/allocation passes are bounded at eight; failure retains the previous image with a diagnostic. A parent load failure cannot publish a partially successful image batch.

Repeat containers are represented by opaque target-rendered proxies, like Components and Tables; their repeated children are selectable as a whole in the parent. Nested internals are edited in their own Component document. Instance scopes and runtime metadata do not yet supply stage 4's binding authoring UI.

## Draft refresh and navigation

Parent and open FXML drafts are captured together. Canonical path handling covers macOS aliases, and a reactor filter prevents another project's/context's documents from entering the overlay. Read-only dependency cache documents are excluded from overlays. Invalidation is currently conservative within a reactor: it may refresh more open previews than a future exact dependency graph would require.

**Open Component** opens a separate editor, reusing an existing standalone window or IntelliJ designer tab. Repeat-container navigation resolves its declared repeated Component. **Open Row Component** follows the Table's explicit Row declaration without changing its layout. **Open Java** navigates the selected Component's source through the host. The parent keeps its draft and undo history.

Example selection is filtered by the opened View resource. A standalone `fx:root` Component loads through a generated private wrapper, then receives its own example Model through its model property; it does not borrow the parent's default example. Fixtures supply independent Card, AddressForm, NoteForm and VisitRow examples.

Reactor sources are editable. IntelliJ can also find source/resource pairs in open source-owning projects and opens them in that project; each project uses its own launch configuration. Multiple candidates prompt for an origin. JAR-only FXML is copied into a content-addressed read-only source cache with an origin label. It is not a writable application resource or a snapshot lease-dependent temporary editor file. Arbitrary unattached source archives and remote projects are not inferred to be editable projects.

## Regression coverage

- Retained resource reuse/replacement, latest pending request, stale result rejection, bounded measurement metadata, capability negotiation, deadline configuration and read-only JAR navigation.
- Real worker PID reuse for sizing, fresh worker on draft changes, process-crash retry, captured child overlays, cancellation, and owner death.
- Classpath/module-path target fixtures: Person.home → AddressForm → NoteForm, repeated visits, Table row occurrences, shared Models, independent Component examples, empty/missing values, wrapping measurements, actual allocated capture dimensions, Controller actions, conversion failure/recovery, Table selection/sorting/filtering and interactive window creation.
- Existing readiness, cleanup, invalid attributes, module access, immutable builds and source-preservation scenarios remain in the suites.
- Shared live Kit scenarios render AddressForm, Repeat and Table proxies in standalone and the registered IntelliJ designer while asserting that runtime sizing does not alter source.

The qualification runs passed 64 Maven tests and 7 IntelliJ adapter tests; 32 target processes executed 402 fixture checks. Connected workflow checks cover both hosts with classpath and module-path applications (100 assertions), including native shared Kit rendering and interactive draft/save lifecycle. Registered IntelliJ checks additionally verify the actual designer extension and exclusive JavaFX 26 native libraries.

Run the bootstrap and registered IDE commands in [README](../README.md). A successful automated run does not close the human navigation/interactive review: verify parent → Component → nested Component, repeated open/reuse, independent examples, interactive editing, save-triggered restart, and closing/reopening preview in both hosts. The completed stage-2 mouse review remains valid for its artifact; input changes should receive focused retesting.

## Next human review (both hosts)

1. Open `Full.fxml`, Build and Refresh, and select its `full` example. Select AddressForm and use Open Component. Confirm a separate editor opens and repeated opening reuses it, with the parent draft intact.
2. Build and Refresh the child; verify its independent example, then open nested NoteForm. Return to the parent and check selection/editability and Undo/Redo.
3. Open the repeated visit Component, then explicitly Open Row Component on the Table. Confirm AddressForm for repeated visits and VisitRow for Table rows, with no parent layout changes.
4. Start Interactive preview. Edit the street and exercise the action button and Table. Make an unsaved designer edit: the running sample state should remain and show outdated status. Save: preview should restart with fresh sample data and the saved change.
5. Close the interactive window, rerun it, stop it, and close the owning editor. Check that windows close and can be opened again. Repeat with the module-path fixture and IntelliJ host.

These checks are pending; automated window/control checks do not count as human acceptance.

## Native-runtime lifecycle correction

The native JavaFX 21 target-worker crash observed during stage-3 qualification has been reproduced and corrected. See the [diagnosis, shutdown contract and lifecycle regression](native-worker-lifecycle.md). The runners now reject native crash reports even when UI assertions pass. Human navigation and interactive-preview review remains open.

## Boundaries

Qualification remains the recorded macOS arm64 / OpenJDK 25 / JavaFX and Kit 26 / IntelliJ 263.7307.200 host baseline and Java 21 / JavaFX 21.0.7 target fixtures. New protocol fields and preview behavior are development contracts, not a frozen public release. Structural authoring, binding/generation panels, production host handoff, broader platform coverage and packaging retain their later gates. VoiceOver remains outside scope.