Connect minimal hosts to snapshots, target workers and shared Kit editing
This commit is contained in:
@@ -67,7 +67,7 @@ Starting a build marks previous results outdated. A failed, cancelled or invalid
|
||||
|
||||
A lease supplies ordered private runtime paths and one manifest/build identity for discovery and rendering. Each lease holds a filesystem lock in a unique ticket; eviction checks those locks across threads, store instances and processes. Published last-successful snapshots are retained even without a lease. Closing a lease permits eviction of superseded snapshots. Process death releases its OS lock; abandoned tickets and staging directories are recoverable. Normal run workspaces are removed when the run finishes; abandoned private workspaces after a host crash are ignored, not activated, and may be removed when no build process owns them. There is no automatic age/size quota yet.
|
||||
|
||||
Cancellation stops the owned Maven process and observed descendants through the shared process runner. Capture checks cancellation between files. Cancellation after the publication commit point can complete as READY; it does not retroactively delete a successfully published build. The caller must keep the lease alive for the full worker lifetime and release it after worker shutdown; worker integration is a later gate.
|
||||
Cancellation stops the owned Maven process and observed descendants through the shared process runner. Capture checks cancellation between files. Cancellation after the publication commit point can complete as READY; it does not retroactively delete a successfully published build. The caller must keep the lease alive for the full worker lifetime and release it after worker shutdown; the [connected workflow](first-connected-workflow.md) now enforces this lifetime.
|
||||
|
||||
## Validation
|
||||
|
||||
@@ -77,4 +77,4 @@ Unit/integration regressions additionally cover exact save approval, FXML draft
|
||||
|
||||
Acceptance on 2026-11-12: **45 tests passed** (41 Maven, four IntelliJ), with no failures/errors/skips, plus **14 real Maven/Java 21 smoke checks**. The full clean bootstrap command also passed artifact identity, bytecode/dependency isolation, target linkage, plugin packaging and documentation checks. The previously documented intentional IntelliJ until-build warning remains.
|
||||
|
||||
The next bootstrap step validates the typed preview API and target adapter against real NeitzelLib classpath/module-path fixtures. Setup UI, worker transport, discovery/render restart, draft overlays and the connected two-host workflow remain later gates.
|
||||
The [target adapter](preview-target-fixtures.md) and [connected two-host workflow](first-connected-workflow.md) are now implemented. Work package 7 adds captured source roots and allows changed saved FXML only when the exact resource is supplied by a private overlay; all other freshness checks remain in force. The historical test count above belongs to work package 5.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Executable configuration and compatibility
|
||||
|
||||
Implementation history: this page records its original bootstrap work package. The [first connected workflow](first-connected-workflow.md) now supplies worker transport, draft overlays and runnable minimal hosts; historical test counts below remain scoped to that earlier step.
|
||||
|
||||
Bootstrap work package 4 supplies the packaged schemas, shared configuration/context/runtime implementation, and a draft wire codec/session validator. Both host adapters use the same `HostServices` interface; the same configuration-failure/editing contract runs against standalone files and real IntelliJ Documents. No configuration check changes document writability or closes a draft.
|
||||
|
||||
## Configuration 1.0
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
# First connected workflow in both minimal hosts
|
||||
|
||||
Bootstrap work package 7 connects the existing build/snapshot services to real target workers and the same Kit UI in standalone and IntelliJ. This is a runnable development milestone, with bounded scalar/layout projection, not the complete designer product.
|
||||
|
||||
## Flow and ownership
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as Shared Kit UI
|
||||
participant Host as Standalone / IntelliJ documents
|
||||
participant Core as DesignerWorkflow
|
||||
participant Build as BuildRefresh / SnapshotStore
|
||||
participant Worker as Java 21 target JVM
|
||||
UI->>Core: Build and Refresh
|
||||
Core->>Host: Inventory build drafts / exact save approval
|
||||
Core->>Build: Scoped Maven build and immutable publication
|
||||
UI->>Core: Discover successful build
|
||||
Core->>Build: Acquire verified snapshot lease
|
||||
Core->>Worker: Authenticated loopback discovery
|
||||
Worker-->>UI: Resource-only example descriptors
|
||||
UI->>Host: Capture parent and known Component drafts
|
||||
UI->>Core: Render selected example and Component sizes
|
||||
Core->>Build: Lease same build identity
|
||||
Core->>Core: Private FXML overlay and tooling copies
|
||||
Core->>Worker: New process, one loaded parent / Model graph
|
||||
Worker-->>Core: Correlated RGBA images
|
||||
Core->>Host: Recheck document revisions
|
||||
Core-->>UI: Images if request generation remains current
|
||||
UI->>Host: Canvas edit as one native document command
|
||||
Core->>Worker: Close owner channel / bounded termination
|
||||
Core->>Build: Release lease after worker shutdown
|
||||
```
|
||||
|
||||
A render batch shares one target View, Model graph and configured services across all Component images. A later draft/size/example refresh uses a fresh process. No application Controller, Component or provider is loaded in the host. Kit receives host-owned `SnapshotRegion` objects.
|
||||
|
||||
Source remains authoritative. The projection preserves original Controllers, bindings, processing instructions, comments and unrepresented attributes outside Kit. Supported scalar/layout edits on the root or identified nodes become one host document transaction; structural edits and unsupported attributes are rejected. Metadata is preserved semantically, although XML whitespace/serialization may change. Native document undo/redo reloads the projection.
|
||||
|
||||
## Transport, overlays and lifetime
|
||||
|
||||
`PreviewWorker` launches the configured target JDK, using the captured runtime and private copies of the three target tooling JARs. The application runtime never points at original mutable Maven outputs. Both classpath and boot-module-layer launches are implemented. Module launches deduplicate repeated module artifacts, retain configured explicit reads/opens, require the selected entry module to exist, and do not invent broad access fixes.
|
||||
|
||||
Each launch gets a random token delivered through a reserved stdin pipe, not command-line arguments or logs. The worker replaces application stdin with an empty stream and watches the original owner pipe independently of FX responsiveness. HELLO validates token, session, launched PID, versions and required capabilities on a loopback socket. Stdout/stderr are bounded presentation logs, separate from binary framing. Each request/result includes context, build, revisions and size through the existing protocol validator.
|
||||
|
||||
The host applies handshake/read deadlines and an overall 45-second worker deadline. Closing/cancelling the owner closes the socket and lifetime pipe, then forces termination if needed. Worker-side owner loss attempts cleanup and halts after a bounded grace period, independently of blocked FX. Abrupt owner death is tested in a separate process. Cleanup callbacks remain cooperative; they cannot be guaranteed after forced death.
|
||||
|
||||
FXML overlays contain at most 128 drafts, each at most 1 MiB. Only affected class directories/JARs are privately copied; unchanged dependencies remain leased immutable snapshot files. An overlaid JAR with signature metadata is rejected. Resources must map unambiguously to captured source roots and exist in the runtime. The store verifies that overlays never alter the published snapshot.
|
||||
|
||||
Saved FXML can differ from captured inputs **only when that exact file is supplied by the overlay**. Java/POM/settings changes and uncovered resource changes still invalidate current-build selection. Dirty and clean known/open Component drafts are captured, so saving an open Component does not require Java recompilation. A failed build still requires explicit **Preview last successful**.
|
||||
|
||||
Images retain the existing 16 MiB per-frame limit; a batch additionally caps aggregate pixels at 64 MiB. Document-change notifications invalidate queued UI results immediately; revision checks and generation checks reject stale responses. The previous image stays visible during asynchronous updates. Snapshot viewports use parent coordinates, as required by [JavaFX SnapshotParameters](https://openjfx.io/javadoc/26/javafx.graphics/javafx/scene/SnapshotParameters.html#setViewport(javafx.geometry.Rectangle2D)).
|
||||
|
||||
## Minimal host UI
|
||||
|
||||
Both hosts show the shared source view, Kit hierarchy/canvas/inspector, build output, example selection and actions for build, cancellation, rendering, explicit retained-build preview, save, undo/redo and opening Component source.
|
||||
|
||||
- Standalone owns shared file drafts across its windows. Closing the last window offers save/discard/cancel for unsaved drafts. Invalid setup opens a source-only editor with save and undo/redo.
|
||||
- IntelliJ registers a separate **Neitzel Designer** editor after the normal editor. It uses native Documents and commands, including asynchronous edits from FX. Setup failures leave the regular source editor available.
|
||||
- The IntelliJ gate checks the qualified SDK, disabled `embed.scene.builder` setting, bundled-provider refusal and absence of preloaded Glass before initialization. It revokes the designer if the registry setting changes. JavaFX/FXML language support stays enabled.
|
||||
- The narrow Kit 26 I18nStringEditor selection patch is shared by both hosts. Its source/license provenance is in [third-party notices](../THIRD-PARTY-NOTICES.md).
|
||||
|
||||
The IDE adapter retains the actual VirtualFile/Document opened through a path alias while using canonical paths for snapshot identities. This avoids a second document for macOS `/var` versus `/private/var` aliases.
|
||||
|
||||
## Run and verify
|
||||
|
||||
First run the full build command in [README](../README.md). The development launchers use that installed build and the verified NeitzelLib snapshot:
|
||||
|
||||
```sh
|
||||
python3 scripts/run-fixture-host.py standalone --java-home "$JAVA_HOME" --target-java-home "$TARGET_JAVA_HOME"
|
||||
python3 scripts/run-fixture-host.py intellij --java-home "$JAVA_HOME" --target-java-home "$TARGET_JAVA_HOME" --idea-home "$IDEA_HOME"
|
||||
```
|
||||
|
||||
Add `--mode modulepath` for the named-module application. Each launch makes a fresh disposable fixture and prints its location/PID. The IntelliJ launcher uses a private config/system/plugins directory with bundled embedding disabled; it does not alter the user's normal IDE settings. Select **Neitzel Designer**, then **Build and Refresh**.
|
||||
|
||||
Machine-local `.neitzel-fx-designer/host.properties` explicitly selects configuration, context, runtime-settings file, fallback Maven executable and target tooling JAR paths. Relative paths resolve from that file. Multiple application contexts require an explicit context value; the minimal setup has no configuration wizard. These local files are not application configuration or published artifacts.
|
||||
|
||||
Automated gates:
|
||||
|
||||
```sh
|
||||
python3 scripts/check-connected-workflow.py --target-java-home "$TARGET_JAVA_HOME" --idea-home "$IDEA_HOME"
|
||||
python3 scripts/check-ide-host.py --java-home "$JAVA_HOME" --target-java-home "$TARGET_JAVA_HOME" --idea-home "$IDEA_HOME"
|
||||
```
|
||||
|
||||
The first is included in `check-bootstrap.py`: real Maven builds, socket discovery/rendering, parent/Component overlays, shared render batches, source navigation, stale responses, saved-FXML reuse, native document undo/redo, invalid FXML and cancellation run through standalone and actual IntelliJ document adapters. Native standalone Kit windows verify both application layouts, inspector text selection, canvas commits, binding preservation, undo/redo, save and source-only fallback. A separate owner process verifies worker death after an abrupt shutdown.
|
||||
|
||||
The second launches real isolated IntelliJ instances with a **test-only companion plugin**, excluded from the delivered plugin ZIP. It verifies editor registration, the shared UI, build/discovery/render, native document edits and undo/redo, then captures screenshots and hashes loaded OpenJFX natives. Evidence is written under `target/connected-workflow/` and `target/ide-workflow/`.
|
||||
|
||||
## Qualification result — 2026-11-12
|
||||
|
||||
The clean bootstrap command passed **56 tests** (50 Maven, six IntelliJ), zero failures/errors/skips; **346 assertions across 24 target JVMs**; **14 Build and Refresh smoke checks**; and **64 connected workflow assertions** across both host document adapters and both application layouts. Native standalone Kit windows passed the five real inspector mouse-selection cases, build/render, canvas edit, undo/redo, save and source-only fallback for each layout. Abrupt owner death terminated its worker.
|
||||
|
||||
The separate real-IDE command passed for **classpath and module-path** applications on IU 263.7307.200. Both registered editors completed Build and Refresh, rendered both Components, committed Kit edits to the native Document, performed undo/redo and rendered drafts. Screenshots were inspected. Both processes reported JavaFX **26+27**, exactly one Glass library, and loaded OpenJFX native hashes matching the JavaFX 26 artifacts. Glass SHA-256: `8fe9cc20e424b078ecaeb01ad6d72436439fb2b66d48dd094fa5d262a65d546a`. Disposable IDEs were terminated after verification.
|
||||
|
||||
This work also fixes two issues exposed by the real registered editor: native edits now use IntelliJ's non-modal write-safe scheduling, and canonical snapshot paths retain the original alias-opened VirtualFile/Document. Artifact identity, dependency/bytecode gates, plugin ZIP checks and documentation validation passed. The intentional IntelliJ until-build restriction still produces its previously documented configuration warning.
|
||||
|
||||
## Limits and next stage
|
||||
|
||||
The qualified platform is macOS arm64, IntelliJ IU 263.7307.200, JavaFX/Kit 26 in hosts and the recorded Java 21 / JavaFX 21.0.7 target. This is not a Plugin Verifier result or wider OS/SDK/runtime qualification.
|
||||
|
||||
Canvas support is intentionally bounded: explicit Component imports with fx:id, the tested Caption/alignment/layout attributes, and scalar/layout edits on identified standard nodes. fx:root/include/script, inline Component content, wildcard application imports, arbitrary structural edits and complete binding/generation editing retain source editing and later projection gates. Opening an fx:root Component currently gives source editing; its parent can preview those drafts. Separate interactive preview controls, general Component authoring, handoff, accessibility, remote IDEs, installers and product release packaging remain later roadmap work.
|
||||
|
||||
The first workflow is now connected; the next roadmap stage is **Establish authoritative documents and generalize the Kit projection**, followed by richer Component preview and binding authoring. This milestone does not establish a corrected public NeitzelLib release or freeze a public preview API.
|
||||
@@ -84,7 +84,7 @@ Local settings hold installed JDK mappings, absolute machine paths and remembere
|
||||
|
||||
## Build and snapshot contract
|
||||
|
||||
Work package 5 now implements the shared [Build and Refresh workflow](build-and-refresh.md), including its validation and explicitly bounded input closure. Worker activation and UI wiring remain work package 7.
|
||||
Work package 5 now implements the shared [Build and Refresh workflow](build-and-refresh.md), including its validation and explicitly bounded input closure. Worker activation and UI wiring are implemented in the [first connected workflow](first-connected-workflow.md).
|
||||
|
||||
1. Resolve the selected context and required reactor dependencies, including configured preview sources. Prefer the Maven wrapper; expose the plan, command/output and cancellation. Avoid unrelated applications unless dependency resolution requires them.
|
||||
2. Identify known unsaved Java, Maven and designer-configuration inputs affecting the build. Offer **Save affected files and build** or **Cancel**, listing the affected files. Do not implicitly build older disk versions. Account for IDE autosave; another process's unsaved buffers are not observable.
|
||||
@@ -133,4 +133,4 @@ Accept the first milestone only when both minimal hosts use the same core/UI/fix
|
||||
- Listing examples performs no Model/Controller construction; selecting an example produces fresh state and honors readiness/cleanup.
|
||||
- Console output cannot corrupt worker messages; owner death, cancellation and timeout terminate workers.
|
||||
|
||||
These are acceptance requirements, not newly passed tests. Broader product behavior remains governed by the existing roadmap.
|
||||
These acceptance requirements are covered by the combined work-package suites; the [connected-workflow report](first-connected-workflow.md) records the qualified platforms and bounded UI scope. Broader product behavior remains governed by the existing roadmap.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Buildable module and host-service boundaries
|
||||
|
||||
Implementation history: this page records its original bootstrap work package. The [first connected workflow](first-connected-workflow.md) now supplies worker transport, draft overlays and runnable minimal hosts; historical test counts below remain scoped to that earlier step.
|
||||
|
||||
Work package 3 implements a buildable service foundation. It does not register an IntelliJ editor, launch a standalone designer, initialize JavaFX inside IntelliJ, or implement target discovery/rendering. The earlier prototypes remain separate evidence.
|
||||
|
||||
## Artifacts
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Preview API and target adapter qualification
|
||||
|
||||
Implementation history: this page records its original bootstrap work package. The [first connected workflow](first-connected-workflow.md) now supplies worker transport, draft overlays and runnable minimal hosts; historical test counts below remain scoped to that earlier step.
|
||||
|
||||
Work package 6 is implemented against the [verified NeitzelLib development artifact](runtime/neitzellib-baseline.md), Java 21 and application JavaFX 21.0.7. This qualifies target-side execution; it does not connect the designer UI, snapshot activation or worker transport. Those remain work package 7.
|
||||
|
||||
## Discovery and construction
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# NeitzelFXDesigner repository bootstrap plan
|
||||
|
||||
Status: repository foundation implemented by the initial commit; work package 2 has a verified development artifact; work package 3 implements the module/service foundation; work package 4 implements configuration and protocol validation; work package 5 implements Build and Refresh with immutable snapshots; work package 6 validates the preview API and target adapter with real fixtures; work package 7 remains planned. Consolidated 2026-11-12. Scope is the ordered implementation start for the [accepted initial contract](initial-project-contract.md); the initial commit creates the foundation only and does not publish a library release.
|
||||
Status: repository foundation implemented by the initial commit; work package 2 has a verified development artifact; work package 3 implements the module/service foundation; work package 4 implements configuration and protocol validation; work package 5 implements Build and Refresh with immutable snapshots; work package 6 validates the preview API and target adapter with real fixtures; work package 7 connects the first workflow in both minimal hosts. Consolidated 2026-11-12. Scope is the ordered implementation start for the [accepted initial contract](initial-project-contract.md); the initial commit creates the foundation only and does not publish a library release.
|
||||
|
||||
## Starting-point evidence before bootstrap
|
||||
|
||||
@@ -58,7 +58,7 @@ Build shared libraries/fixtures using the Maven structure; verify and pin the ac
|
||||
|
||||
### 4. Make configuration and compatibility executable
|
||||
|
||||
Implemented: packaged schemas, profile-qualified effective-reactor context selection, local runtime mappings, shared compatibility gating, bounded wire codec and authentication/correlation state. See [implementation and validation](configuration-and-protocol.md). Effective Maven model acquisition, worker transport and setup UI retain their later implementation gates.
|
||||
Implemented: packaged schemas, profile-qualified effective-reactor context selection, local runtime mappings, shared compatibility gating, bounded wire codec and authentication/correlation state. See [implementation and validation](configuration-and-protocol.md). Effective Maven capture and worker/minimal UI wiring are implemented in work packages 5 and 7; a general setup wizard remains later work.
|
||||
|
||||
Implement JSON schema, context resolution and local runtime mappings. Turn the illustrative fields into a versioned v1 schema and fixtures. Check invalid paths/modules, missing runtimes, unknown schema versions/capabilities, multiple matching contexts and parent-to-Component context inheritance. Define protocol framing, bounded message/image payloads and negotiation/error fixtures before worker implementation depends on them.
|
||||
|
||||
@@ -66,7 +66,7 @@ Implement JSON schema, context resolution and local runtime mappings. Turn the i
|
||||
|
||||
### 5. Implement Build and Refresh with immutable snapshots
|
||||
|
||||
Implemented: shared coordinator, scoped effective Maven capture, explicit draft save approval, isolated builds, consistent private runtime copies, atomic publication, persistent outdated/last-successful state and cross-process snapshot leases. See [implementation and limits](build-and-refresh.md). The UI and worker restart consume these interfaces in work package 7.
|
||||
Implemented: shared coordinator, scoped effective Maven capture, explicit draft save approval, isolated builds, consistent private runtime copies, atomic publication, persistent outdated/last-successful state and cross-process snapshot leases. See [implementation and limits](build-and-refresh.md). The UI and worker restart now consume these interfaces in work package 7.
|
||||
|
||||
Resolve scoped Maven builds, preview source arrangements, explicit save/cancel and runtime choices. Capture successful outputs/resources/dependencies with an input/output manifest. Validate consistency and publish atomically; pin active snapshots against eviction. Provide explicit last-successful-build selection and stale diagnostics.
|
||||
|
||||
@@ -74,7 +74,7 @@ Resolve scoped Maven builds, preview source arrangements, explicit save/cancel a
|
||||
|
||||
### 6. Validate the preview API and target adapter against real fixtures
|
||||
|
||||
Implemented: resource-only discovery, typed sessions, real NeitzelLib loading/rendering and 24 classpath/module-path process checks. See [qualification and lifecycle limits](preview-target-fixtures.md). Library-held Model/ViewModel state requires a fresh JVM per session; external shutdown enforcement remains work package 7.
|
||||
Implemented: resource-only discovery, typed sessions, real NeitzelLib loading/rendering and 24 classpath/module-path process checks. See [qualification and lifecycle limits](preview-target-fixtures.md). Library-held Model/ViewModel state requires a fresh JVM per session; external shutdown enforcement is now implemented in work package 7.
|
||||
|
||||
Add classpath/module-path Maven fixture applications using NeitzelLib artifacts. Implement non-constructing descriptor discovery and typed provider/session lifecycle against the real library. Test fresh Models/services, readiness, cleanup, invalid attributes and write-back. Freeze public Java signatures only after these tests establish the adapter contract.
|
||||
|
||||
@@ -82,6 +82,8 @@ Add classpath/module-path Maven fixture applications using NeitzelLib artifacts.
|
||||
|
||||
### 7. Complete the first workflow in both minimal hosts
|
||||
|
||||
Implemented: both minimal hosts use the same Kit UI and workflow, immutable snapshots, authenticated worker transport, parent/Component overlays, native document edits and undo/redo. The narrow Kit selection fix is carried with provenance. See [implementation, qualification and limits](first-connected-workflow.md). Broader projection, interactive preview controls and product qualification remain subsequent work.
|
||||
|
||||
Connect shared core/UI to the worker protocol and fixtures. Exercise Build and Refresh, discovery, parent/Component draft overlays and target-runtime render in standalone and IntelliJ. Use the qualified exclusive JavaFX 26 host setup; keep application runtime execution outside each host. Carry only the verified narrow Kit patch where still needed, with provenance and regression coverage.
|
||||
|
||||
**Exit:** all initial-contract acceptance requirements pass in both hosts with logs/artifact identities and explicit limitations. Then proceed to roadmap stage 2 and later feature stages. Full handoff, binding/generation UI, broader projection/control support and product packaging are not silently included in this first milestone.
|
||||
|
||||
Reference in New Issue
Block a user