113 lines
6.9 KiB
Markdown
113 lines
6.9 KiB
Markdown
# Canvas Pilot
|
|
|
|
Independent Rust/egui layout editor for presentation switchers; not affiliated with
|
|
Analog Way. This repository owns the application, device probe, exchange templates,
|
|
manual and build tooling. It must build without a sibling beffroi-tools checkout.
|
|
Keep the single-member workspace and adapter design simple; avoid speculative layers
|
|
of abstraction. User instructions take precedence over this guidance.
|
|
|
|
When resuming the migrated conversation, read `docs/development/handoff.md` for
|
|
pending decisions, video plans, prior test authorization and publication state.
|
|
Treat dated observations as a snapshot and verify current state before acting.
|
|
|
|
## Project map
|
|
|
|
- `crates/canvas-pilot/src/`: editor and application. `lib.rs`, `project.rs`,
|
|
`formats.rs` and `snapping.rs` own geometry, persistence and editing rules;
|
|
`gui.rs` and the `*_ui.rs` modules own interaction and presentation.
|
|
- `device.rs`, `device/`, `device_send.rs` and `device_capture.rs`: shared device
|
|
representation and Midra/Aquilon implementations. Keep protocol paths, conversion
|
|
and apply behavior inside the appropriate adapter; do not leak them into generic
|
|
geometry or editor controls. Preserve bounded reads, partial writes, preflight,
|
|
cancellation, explicit unsupported-mode errors and verified readback.
|
|
- `exchange.rs`, `interchange.rs`, `geometry_formats.rs`, `vendor_formats.rs` and
|
|
`exchange_metadata.rs`: exchange formats and embedded metadata. Preserve the shared
|
|
geometry model, precision, import review and optional vendor-format build.
|
|
- `crates/canvas-pilot/tests/` and `tests/fixtures/` within that crate: Rust regression
|
|
tests and sanitized device/clipboard fixtures. `examples/` contains explicitly
|
|
invoked device diagnostics; these are not automated hardware tests.
|
|
- `tools/midra_probe.py`: standalone, read-only Python diagnostic tool.
|
|
`tests/` at the repository root covers the probe, templates and build/publication
|
|
helpers. `docs/templates/canvas-pilot/` owns all eleven-format starter files and ZIP.
|
|
- `scripts/`, root Cargo/Cross/release configuration and `Jenkinsfile`: independent
|
|
build, checks, packaging, artwork, launchers and documentation publication.
|
|
|
|
## Authoritative documentation
|
|
|
|
Use `AGENT_DOCUMENTATION.md` as the index for contracts, research, handoffs,
|
|
acceptance evidence and technical notes. Use `docs/development/README.md` for the
|
|
project plan, tasks, stretch goals and contribution workflow. Read the linked
|
|
records before changing behavior; do not duplicate their status in new checklists.
|
|
|
|
The user manual is built from the Markdown files listed in
|
|
`docs/manuals/canvas-pilot/SUMMARY.md`. Edit those chapters as the single source of
|
|
user-facing instructions. Keep READMEs short navigation pages. Do not put task lists,
|
|
handoffs or agent contracts on the main README or in the user book's chapter list.
|
|
Keep completed work, remaining acceptance and future ideas distinct. Preserve the
|
|
documented support boundaries; emulator evidence is not physical-output acceptance.
|
|
|
|
## Compatibility and device behavior
|
|
|
|
Document every persistent save/export representation under `docs/interfaces/`,
|
|
including fields, units, precision, versions, validation, omissions and round trips.
|
|
The project, settings, recovery and exchange contracts and versioned examples are
|
|
there, alongside device adapters and reviewed Midra transfers. Update documentation,
|
|
fixtures and meaningful regression tests in the same change as a schema modification.
|
|
Provide tested migrations or clear unsupported-version errors for breaking changes.
|
|
Preserve settings locations and legacy Midra identifiers; renaming the repository
|
|
must not reset user preferences or change serialized formats.
|
|
|
|
Preserve source documents. Imports and failed operations must not silently replace
|
|
working projects or existing exports. Keep device writes explicit and within the
|
|
user's authorized scope; never infer authorization from a saved address. Geometry
|
|
operations must not implicitly route sources, TAKE, or alter shared input settings.
|
|
Advanced input writes remain opt-in. Device writes and physical-output acceptance
|
|
are never CI tests. Do not commit credentials or unsanitized captures.
|
|
|
|
## Validation and documentation
|
|
|
|
For Rust changes, follow `docs/development/ci.md`: formatting, Clippy and rustdoc
|
|
with warnings denied, workspace tests, default vendor-format tests and the
|
|
`--no-default-features --features no_proprietary` tests. `--all-features` activates
|
|
`no_proprietary`, so it does not cover the normal vendor codecs by itself.
|
|
Run `python3 scripts/ci.py coverage` for whole-application coverage (75% floor);
|
|
never exclude production GUI or format code to inflate it.
|
|
|
|
Run `python3 -m unittest discover -s tests -v` for Python/build-helper changes.
|
|
For documentation changes, run `python3 scripts/manuals.py build` with the mdBook
|
|
version pinned in `docs/manuals/mdbook-version`; it validates links, downloads and
|
|
print-view anchors. Use `docs/manuals/canvas-pilot/SUMMARY.md` to maintain chapters.
|
|
Keep screenshots and template bytes intact unless intentionally updating them;
|
|
the template ZIP and individual files must agree. Test actual rendering with the
|
|
relevant external tools when available; report checks that could not be completed.
|
|
|
|
Keep root README concise and put details in `docs/`. Add a succinct Unreleased
|
|
entry to `docs/canvas-pilot/changelog.md` for each change, including useful validation
|
|
or limitations; it is linked from `docs/changelogs.md`.
|
|
|
|
## Version bookkeeping
|
|
|
|
Bump the workspace patch version once per completed subject (feature, fix or
|
|
substantive documentation task), not once per commit. Follow-up corrections and
|
|
validation for that same subject share its version. Read-only work needs no bump.
|
|
Use a requested minor/major bump instead of an additional patch bump. Keep
|
|
`Cargo.toml`, the Canvas Pilot entry in `Cargo.lock` and the changelog in sync;
|
|
group entries by version under Unreleased until published. Keep this lightweight:
|
|
version bookkeeping alone does not call for a tag, binary build, push or release.
|
|
|
|
## Publication and working conventions
|
|
|
|
Manual publication owns only `/mnt/books/manuals/canvas-pilot/`; never replace the
|
|
shared manuals index or another book. Badge publication owns only
|
|
`/mnt/assets/coverage/idle-org/canvas-pilot/main/`. Main/non-PR restrictions apply.
|
|
Jenkins archives exactly the version, test and coverage SVGs; it does not create
|
|
releases or publish binaries. See `docs/development/ci.md` for job setup and
|
|
`docs/development/releases.md` for manually invoked packaging.
|
|
|
|
Inspect the working tree first. Preserve unrelated changes, use existing dependencies
|
|
and Python's standard library where practical, and keep temporary files temporary.
|
|
Never commit credentials, caches, generated manuals, release archives or executables.
|
|
Every completed task changing repository files must end with a descriptive Git commit.
|
|
Stage only task-owned changes, report the commit and validation, and do not push unless
|
|
requested. Read-only audits need no empty commit.
|