From a7b51cb24fe04460c80d3e4a5a727b0535743801 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 15 Nov 2026 13:04:10 +0100 Subject: [PATCH] Add staged Aquilon adapter implementation handoff --- docs/midra-layout/aquilon-compatibility.md | 2 +- docs/midra-layout/aquilon_support.task.md | 215 +++++++++++++++++++++ docs/midra-layout/changelog.md | 4 + docs/midra-layout/plan.md | 2 +- 4 files changed, 221 insertions(+), 2 deletions(-) create mode 100644 docs/midra-layout/aquilon_support.task.md diff --git a/docs/midra-layout/aquilon-compatibility.md b/docs/midra-layout/aquilon-compatibility.md index 040d7bb..f19b606 100644 --- a/docs/midra-layout/aquilon-compatibility.md +++ b/docs/midra-layout/aquilon-compatibility.md @@ -1,6 +1,6 @@ # Aquilon compatibility investigation -[Midra Layout plan](plan.md) · [Device workflows](guide/device.md) +[Midra Layout plan](plan.md) · [Device workflows](guide/device.md) · [Agent implementation task](aquilon_support.task.md) Investigated 2026-11-15. **Aquilon is not yet enabled in the application.** This review compared the current Rust adapter with upstream protocol references; diff --git a/docs/midra-layout/aquilon_support.task.md b/docs/midra-layout/aquilon_support.task.md new file mode 100644 index 0000000..9b09f1e --- /dev/null +++ b/docs/midra-layout/aquilon_support.task.md @@ -0,0 +1,215 @@ +# Aquilon / LivePremier support — agent handoff + +Status: **not implemented**. Prepared 2026-11-15. Work in +`crates/midra-layout/`; read the repository `AGENTS.md` before editing. + +## Objective + +Add a separate Aquilon adapter to the existing layout editor, initially targeting +**AQL Cmax firmware 6.2.79**. Deliver useful geometry import first, then mapped +position/size transfers, crop conversion and input previews. Preserve existing +Midra behavior and reuse the editor, transfer scopes, mapping review and transport +where their semantics actually match. Do not claim support for every Aquilon +firmware/model based on this one emulator. + +This file is an implementation brief, not a request to start a second agent. +The current task only prepares the handoff; the implementing agent should execute +the stages below when assigned the implementation. + +## Known target and evidence + +- User-supplied emulator: `192.168.10.146:3000` (HTTP and expected WebSocket + authority; verify that it is still this emulator before diagnostic writes). +- Read-only `GET /api/tpp/v1/system` returned: + `{"type":"AQL Cmax","label":"AQUILON","isLinked":false,"linkName":"","version":{"major":6,"minor":2,"patch":79,"beta":false}}`. +- `GET /api/stores/device` returned **124,076,981 bytes**, approximately 118 MiB. + The existing 32 MiB Midra response cap cannot accommodate it. +- The probe wrote `/tmp/aquilon-system.json` and `/tmp/aquilon-device-state.json`. + These are temporary, private local artifacts and may no longer exist. Re-read + if necessary; do not commit the raw state or assume it is current. +- Commit `0c37ad6` added identity validation before downloading state. Aquilon + currently reports that its adapter is unimplemented. Replace this refusal only + when a supported profile can actually parse it; merely accepting the model name + or raising the cap does not enable compatibility. +- [Protocol investigation](aquilon-compatibility.md) records the upstream evidence, + exact Companion revision and source links. Review those before implementing. + AWJ TCP and WebRCS WebSocket transport are distinct; do not mix their framing. + +The user previously authorized device testing, including Program changes, and +rejected extra confirmation rituals in the product. Preserve the actual product +contract: Program destinations require the **Allow sending to program** preference; +opening mapping options does not send; the explicit Send action sends. Use Preview +for initial diagnostics. No implicit TAKE or input routing changes. Keep hardware +writes out of automated CI. Do not turn old agent-facing cautions into new dialogs. + +## Code map and contracts to preserve + +| Area | Current implementation | +| --- | --- | +| Identity, HTTP reads, screen/layer parsing | `src/device.rs` (`Snapshot`, `Screen`, `Layer`, `fetch`) | +| Send planning, WebSocket writes, apply/readback | `src/device_send.rs` (`Target`, `Sizing`, `Plan`) | +| Connection/history, scope, mapping, direct send/load | `src/device_ui.rs` | +| Snapshot endpoints and input discovery | `src/device_capture.rs` | +| Pooled low-rate captures and preview state | `src/capture_ui.rs` | +| Geometry, layer identities and saved links | `src/lib.rs` (`MidraLink` currently has decimal-only screen/layer strings) | +| Source/crop math and property windows | `src/formats.rs`, `src/format_ui.rs` | +| Project persistence and recovery | `src/project.rs`, `src/project_ui.rs`, `src/recovery_ui.rs` | +| Connection/application preferences | `src/settings.rs` | +| Existing regression fixtures | `tests/device.rs`, `tests/project.rs`, in-module send/capture/UI tests | + +Read [device import](../interfaces/midra-device-import.md), +[send/crop conversion](../interfaces/midra-device-send.md), +[project schema](../interfaces/midra-layout.md), +[application settings](../interfaces/midra-layout-settings.md) and +[input previews](../interfaces/midra-input-preview.md). + +## Staged implementation checklist + +### 1. Establish a bounded, usable Aquilon state reader + +- [ ] Confirm identity/firmware, authentication requirements and root structure. + Inspect `/auth/status` if supported; avoid logging credentials or session tokens. +- [ ] Inventory actual screens, auxiliary screens, layer allocations, source IDs, + transition/bank state and any linked-unit identifiers in the captured data. +- [ ] Investigate documented subtree reads or subscriptions. Prefer small reads + sufficient for a coherent operation over repeatedly fetching the full store. + Do not invent subtree URLs without testing them. +- [ ] If a full-store fallback is necessary, give it an explicit, measured size + budget and timeout, and bound decoded data as well as wire bytes. Account for + JSON allocation and cloning costs; retain only the state needed by the adapter. +- [ ] Keep network/parse work off the UI thread. Support cancellation, progress, + timeouts, malformed responses and authentication errors without stale-online state. +- [ ] Derive small sanitized fixtures. Record field meanings and uncertainty; + do not check in the 118 MiB dump. + +Acceptance: the target can be identified and read without the misleading size +error, UI blocking or unbounded allocations. Unsupported profiles fail clearly. + +### 2. Separate transport from device-family semantics + +- [ ] Introduce explicit device family/profile and capability information. Keep + existing Midra profiles working; avoid scattered `if Aquilon` path substitutions. +- [ ] Normalize screen/layer geometry into the current editor model while keeping + native destination identity. Profiles own paths, bank resolution and apply pulses. +- [ ] Model Preview and Program banks explicitly. The current “not UP means DOWN” + logic is Midra-specific and cannot resolve Aquilon A/B banks. +- [ ] Resolve banks per screen/group and handle active transitions explicitly. + +Candidate differences from upstream, **to verify against 6.2.79**: + +| Concern | Aquilon candidate behavior | +| --- | --- | +| Screen identity | `S1`, `A1`; firmware 4+ separates screen/auxiliary lists | +| Allocated layer count | Screen `status/pp/layerCount` | +| Position and size | Both under layer `position/pp`; positions are centers | +| Crop/mask | `cropping/classic/pp` and `cropping/mask/pp` | +| Apply | Firmware 4+ `device/screenAuxGroupList/control/pp/xUpdate`, false then true | +| Older profiles | Different roots/apply path; explicitly out of initial scope | + +### 3. Import geometry and expose accurate capabilities + +- [ ] Import actual allocated layers, independently of whether they have a source. + Inputs and layer slots are different resources; never infer layer count from inputs. +- [ ] Convert center position and size into editor top-left boxes; retain fractional + values internally. Preserve disabled-screen handling and error reporting. +- [ ] Support screen/frame selection and explicit destination mapping using the + existing dedicated device-import workflow, not the generic geometry-import dialog. +- [ ] Preserve default All / Selected / Folder scopes and linked-load behavior. +- [ ] Detect crop/mask/fit combinations not yet understood; report their limitation + rather than silently importing incorrect visible bounds. + +Acceptance: multiple differently sized screens, unassigned layers, A/B swaps, +empty/disabled slots and malformed state have regression coverage. Imported boxes +match the emulator's displayed positions and sizes for the verified simple case. + +### 4. Persist family-aware destination links + +- [ ] Design destination identity including family, screen/auxiliary identity and + layer; include unit identity where the verified linked topology requires it. + Never collapse `S1` and `A1` into one numeric destination. +- [ ] Update validation, mapping selectors, conflict detection and linked send/load. + Multiple editor layers may share a destination, but a single send scope with + duplicate destinations must be rejected with the conflicting layer names. +- [ ] Preserve remapping/unmapping, saved screen selection and folder-based memories. + Do not revive the removed multi-link-per-layer or nested-folder proposals. +- [ ] Version any breaking project schema change (current baseline is v12), migrate + existing numeric Midra links explicitly, and test save/load/recovery and undo. +- [ ] Update interface docs, examples and embedded-export snapshot behavior in the + same change. Keep temporary device state out of saved projects. + +### 5. Send position/size and apply changes + +- [ ] Implement profile-specific write planning for the chosen Preview/Program bank. + Validate destinations against actual capabilities, not hard-coded Midra limits. +- [ ] Preserve both `OutputBox` and `SourceAspect` sizing strategies; enable only + combinations whose interpretation has been verified. +- [ ] Use the verified Aquilon apply pulse. Resolve bank state afresh when needed + so a stale snapshot does not select the wrong preset. +- [ ] Read back affected fields and verify the emulator rendering, not just WebRCS + values. Previously Midra accepted writes without visibly applying them until + the missing apply pulse was sent. +- [ ] Preserve direct Send linked layers and Load linked layers, mapping review, + selection/folder scope, error reporting and Program preference behavior. + +Acceptance: change a known layer, apply, read back and observe the intended box; +record the tested destination/bank and restore diagnostic geometry afterward. +Partial writes and disconnects must be reported without claiming success. + +### 6. Verify crop, zoom and advanced source behavior + +- [ ] Determine crop units, rounding, fit modes, masks and source correction from + the actual firmware. Do not reuse Midra's normalized crop units without evidence. +- [ ] Test both send sizing strategies against asymmetric and extreme crops, + non-16:9 sources, custom input dimensions, content offsets and zoom >= 100%. +- [ ] Verify inverse import conversion and export/import round trips. The final + visible layer box must remain consistent with the editor's geometry contract. +- [ ] Leave shared input settings untouched unless explicitly enabled and edited + in the Advanced Source section. Do not change source routing as a side effect. +- [ ] Keep unsupported fit/mask modes explicit until verified. + +### 7. Add low-resource input previews + +- [ ] Verify capture endpoints, IDs, availability/no-signal reporting and sizes. + Remove Midra-only input limits through discovered capabilities plus resource caps. +- [ ] Reuse serialized/throttled requests, pooling when layers share an input, + opt-in refresh, immediate-but-throttled capture on selection and cancellation. +- [ ] Preserve input preselection on device load without auto-capturing until enabled, + source assignment/stills in projects, and paused refresh after project restore. +- [ ] Keep reference captures still-only and preserve preview/crop-guide controls. + +### 8. Acceptance, documentation and delivery + +- [ ] Add sanitized parser/plan fixtures and mock HTTP/WebSocket tests, including + correct apply pulse, no implicit TAKE, no routing writes and opt-in source edits. +- [ ] Exercise existing Midra fixtures to prove this adapter has not changed them. +- [ ] Test mapping persistence, duplicate destinations, folder sends, reconnect, + custom port, history/autoconnect, stale bank state and failure recovery. +- [ ] Record emulator acceptance separately from physical-output acceptance. + Linked units, older firmware and untested models remain explicitly unverified. +- [ ] Update the investigation, main plan, user manual, affected interface contracts + and Unreleased changelog with what actually works and remaining limitations. +- [ ] Commit each completed task with only its relevant changes; do not push. + +Required repository checks: + +```sh +cargo fmt --all --check +cargo clippy --locked --workspace --all-targets --all-features -- -D warnings +cargo test --locked --workspace --all-features +RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps +python3 scripts/ci.py coverage +``` + +Run relevant default-feature tests too when touching native exchange or embedded +project snapshots: all-features includes `no_proprietary` and disables those codecs. +Local mock-server tests need permission to bind loopback sockets in a restricted +sandbox. Actual-device write diagnostics are separate manual checks, never CI. + +## Reporting checkpoints + +After each stage, report the implemented capability, exact emulator/model/firmware +checked, test results and remaining gaps. Distinguish “state read”, “geometry +import”, “position/size transfer”, “crop conversion” and “preview capture”; do not +summarize a partial implementation as complete Aquilon support. If the target is +unavailable, continue fixture/refactoring/documentation work and state which +acceptance checks require the emulator rather than inventing protocol behavior. diff --git a/docs/midra-layout/changelog.md b/docs/midra-layout/changelog.md index 07dc5a2..706aa90 100644 --- a/docs/midra-layout/changelog.md +++ b/docs/midra-layout/changelog.md @@ -4,6 +4,10 @@ ## Unreleased +- Add an Aquilon implementation handoff covering the observed emulator, bounded + state loading, family-specific geometry/transfers, saved links, crop, capture + and staged acceptance checks. No device support is enabled by this task. + - Recommend SVG for Illustrator exchange in the README, manual and template catalog. Keep AI as an optional compatibility target requiring external VectorCraft CLI, with executable discovery and setup documented. diff --git a/docs/midra-layout/plan.md b/docs/midra-layout/plan.md index c03900c..3f8f1ce 100644 --- a/docs/midra-layout/plan.md +++ b/docs/midra-layout/plan.md @@ -67,7 +67,7 @@ device readback and physical-screen acceptance. ## Remaining feature work -- [ ] **Aquilon / LivePremier adapter.** [Protocol investigation and implementation sequence](aquilon-compatibility.md) completed. A read-only AQL Cmax 6.2.79 emulator probe confirmed identity and a 118 MiB state store; unsupported identities now fail before state download. Next: sanitized emulator fixtures, firmware-aware geometry import, family-aware saved links, send/apply/readback, then verified crop and capture support. Aquilon is not enabled yet. +- [ ] **Aquilon / LivePremier adapter.** [Agent implementation task](aquilon_support.task.md). [Protocol investigation and implementation sequence](aquilon-compatibility.md) completed. A read-only AQL Cmax 6.2.79 emulator probe confirmed identity and a 118 MiB state store; unsupported identities now fail before state download. Next: sanitized emulator fixtures, firmware-aware geometry import, family-aware saved links, send/apply/readback, then verified crop and capture support. Aquilon is not enabled yet. - [ ] **Further export/workflow cleanup.** Shared transfer scopes, mapping review and direct linked send/load are implemented; further changes await specifications.