NeitzelFXDesigner/docs/target-runtime-stage-plan.md

Target-runtime sessions, sizing and Component navigation

Status: stage-3 implementation and automated qualification are described in the runtime implementation report. The human review records observed passes and the user’s decision to skip the remaining checks and proceed. This document retains the implementation sequence and acceptance criteria. Stage 2's manual input gate is closed on its recorded baseline. This work implements the accepted preview and host contracts; it does not reopen them as Wayfinder decisions.

Starting implementation and gaps (before this stage)

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

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. The first implementation step is retained rendering sessions and their lifecycle tests; measurement and navigation build on that ownership boundary.