diff --git a/.gitignore b/.gitignore
index 2a816f2..6d941af 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,6 @@ __pycache__/
.env
/.rust-release/
/dist/
+
+# Local showcase recordings, profiles and generated exchange files.
+/showcase-videos/
diff --git a/Cargo.lock b/Cargo.lock
index d554ca6..811efbd 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -548,7 +548,7 @@ dependencies = [
[[package]]
name = "canvas-pilot"
-version = "0.9.16"
+version = "0.9.17"
dependencies = [
"base64",
"craft-dwg",
diff --git a/Cargo.toml b/Cargo.toml
index d58b525..e2af0a5 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ default-members = ["crates/canvas-pilot"]
resolver = "3"
[workspace.package]
-version = "0.9.16"
+version = "0.9.17"
edition = "2024"
license = "MIT"
repository = "https://proxy.dandaedre.com/gitea/idle-org/canvas-pilot"
diff --git a/docs/canvas-pilot/changelog.md b/docs/canvas-pilot/changelog.md
index e0ae998..13ef5e2 100644
--- a/docs/canvas-pilot/changelog.md
+++ b/docs/canvas-pilot/changelog.md
@@ -4,6 +4,18 @@
## Unreleased
+### v0.9.17
+
+- Added isolated feature-recording recipes, a shot-by-shot capture guide and a
+ Git-ignored local video gallery with captions, contact sheets and fresh profiles.
+ Recorded 21 clips covering editing, crop/mask, exchange, language packs and
+ simulator transfers. Offline imagery and simulator footage are labelled.
+- The simulator Preview send passed device readback; baseline restoration verified
+ all captured S1 layer fields in both banks. Python tests and the pinned manual
+ build pass; this is not physical-output acceptance.
+- Added the requested backlog item to validate every Aquilon and Midra model,
+ starting with AQL C+; existing support claims and adapter checks are unchanged.
+
### v0.9.16
- Added language-pack management in Settings: installed revisions/languages,
diff --git a/docs/canvas-pilot/feature-demo-checklist.md b/docs/canvas-pilot/feature-demo-checklist.md
index 34ec41c..40f90a2 100644
--- a/docs/canvas-pilot/feature-demo-checklist.md
+++ b/docs/canvas-pilot/feature-demo-checklist.md
@@ -1,130 +1,139 @@
-# Canvas Pilot feature demonstration checklist
+# Recording the feature showcase
-Use one **Slides + Presenter** layout throughout: build it, refine it, exchange
-it with other applications, then send it to a device. This is an operation list,
-not a narration script. Tick off each item while recording.
+Record independent clips, with a fresh project and settings profile for each take.
+This avoids carrying a mistake into the next demonstration. The reproducible shot
+recipes live in [record-showcase.py](../../scripts/record-showcase.py); the
+[advanced guide](guide/overview.md) remains the reference for individual controls.
-## Before recording
+## Shot list
-- [ ] Prepare a reference image of a stage or screen layout.
-- [ ] Have simple rectangle layouts ready in Illustrator, Figma and draw.io.
-- [ ] Prepare a PPTX or DXF file for file import.
-- [ ] Have a Midra or the supported Aquilon emulator ready, with sources already routed.
-- [ ] Choose a folder for the demo project and exports.
+The two-layer fixture is a 1920 × 1080 output with Slides and Presenter. Special
+fixtures start with crop, mask, folder, reference or cached preview state already
+prepared. Captions explicitly identify that setup instead of implying it was
+created during the clip.
-## 1. Start a project
+| Clip | Actions and result to check |
+| --- | --- |
+| 01 Project | Save a named project, move a layer, reopen and confirm replacement; saved geometry returns. |
+| 02 Movement | Drag, corner-resize, undo/redo, enter an exact width and nudge; inspector values follow. |
+| 03 Alignment | Align to the screen, relocate a pivot, resize and change measurement reference. |
+| 04 Group resize | Select two layers, move together and compare same, mirrored and opposite handles with undo between examples. |
+| 05 Snapping/grid | Show target choices, snap a moving edge and distinguish overlay visibility from grid snapping. |
+| 06 Organization | Move a layer into a prepared folder, collapse, hide/lock, then add, name, reorder and remove a temporary layer. |
+| 07 Navigation/output | Pointer-centered zoom, pan, fit screen, zoom to selection and inspect output formats. |
+| 08 Crop | Start at 200%, reframe, inspect faded surroundings, recenter and reset without moving the container. |
+| 09 Mask | Enter crop, Tab to mask, resize/move the reveal window, inspect hatching, center and reset. |
+| 10 Source | Inspect the local source/input/layer distinction and explicit advanced-input opt-in; no input writes. |
+| 11 Fit modes | Use a square container to compare Centered, Fullscreen, Cropped and 1:1 against the same image. |
+| 12 Clipboard | Paste real SVG text, review destination mapping, apply geometry and undo. |
+| 13 File import | Pick a real SVG file, review, import and undo. |
+| 14 Export | Show formats, scope and metadata choices, then save a complete SVG layout. |
+| 15 Reference | Show a prepared reference, visibility, opacity/native placement controls and layer outlines. |
+| 16 Appearance/packs | Inspect installed pack revision and languages, removal confirmation, cancel, change theme and preview French with a return to English. |
+| 17 Simulator | Connect to the explicitly identified local Aquilon simulator and inspect device controls. |
+| 18 Cached preview | Inspect preview/guide controls using a labelled offline image; this is not live capture. |
+| 19 Mask snapping | With only mask targets enabled, snap against the visible picture edge and undo. |
+| 20 Pack lifecycle | Install the Ukrainian/Bhojpuri example ZIP, update to revision 2, cancel a downgrade warning and confirm removal. |
+| 21 Simulator transfer | With a separately authorized fixture, load a linked Preview layer, edit geometry, review, send and verify readback; restore the simulator afterward. |
-- [ ] Start a new project.
-- [ ] Show the default Slides and Presenter layers.
-- [ ] Open Output format: show presets and custom dimensions.
-- [ ] Use 1920 × 1080 for the demonstration.
-- [ ] Save the project with a recognizable name.
+These clips group related interactions rather than making a clip for every button.
+The SVG demonstrations exercise interchange without pretending to record Illustrator,
+Figma or draw.io. Actual captures from those applications, live input capture, other
+file codecs and physical device output require separate application/device sessions.
-## 2. Position the layers
+## Recording environment
-- [ ] Select a layer from the canvas, then from the layer list.
-- [ ] Drag it and resize it using the handles.
-- [ ] Toggle aspect-ratio locking and demonstrate the difference.
-- [ ] Enter an exact layer width and height.
-- [ ] Nudge with arrow keys, then Shift-arrow.
-- [ ] Open **Measure position from**: switch between a corner and the center.
-- [ ] Show that changing the measurement reference does not move the layer.
-- [ ] Enable a different layer measurement point and demonstrate one precise placement.
-- [ ] Undo and redo a change.
+Use a dedicated X11 display, not the working desktop. The script sends real mouse
+and keyboard events, changes its own clipboard and recreates its per-shot settings.
+The normal user profile is not used. Requirements:
-## 3. Align and resize together
+- A built `target/debug/canvas-pilot` (`cargo build -p canvas-pilot`).
+- Python 3, Xvfb, xdotool, xclip, FFmpeg/ffprobe and ImageMagick.
+- Tesseract with English recognition data; OCR locates labelled controls.
+- `dbus-daemon`, `xdg-desktop-portal` and the GTK portal backend for native file pickers.
-- [ ] Select both layers using Shift-click or a selection box.
-- [ ] Move them together.
-- [ ] Demonstrate snapping to guides or another layer.
-- [ ] Align one layer to the screen, then align against another layer.
-- [ ] Demonstrate **Same handles** resizing.
-- [ ] Demonstrate **Mirror horizontally**, then **Opposite handles**.
-- [ ] Undo between examples so the layout stays understandable.
+Start the virtual display in its own terminal:
-## 4. Organize the project
+```sh
+Xvfb :97 -screen 0 1440x940x24 -nolisten tcp -noreset
+```
-- [ ] Add a third layer and rename it.
-- [ ] Create a folder and drag layers into it.
-- [ ] Collapse and expand the folder.
-- [ ] Select the folder's layers together.
-- [ ] Toggle visibility and locking.
-- [ ] Reorder overlapping layers to show stacking.
-- [ ] Return to a clean Slides + Presenter arrangement.
+Then, from the repository root:
-## 5. Use a reference image
+```sh
+python3 scripts/record-showcase.py --list
+python3 scripts/record-showcase.py --display :97 --only 02-move-resize
+```
-- [ ] Drop the prepared image into the application.
-- [ ] Adjust its opacity and display placement.
-- [ ] Show outline-only layer display over the reference.
-- [ ] Position the layers against the reference.
-- [ ] Zoom around the pointer, pan, then use **Fit screen**.
-- [ ] Use **Zoom to selection**.
-- [ ] Hide the reference when finished.
+Omit `--only` to run clips 01–20. Clip 21 requires the separate simulator setup described below. To rehearse a fixture without recording:
-## 6. Show source formats and cropping
+```sh
+python3 scripts/record-showcase.py --display :97 --inspect 08-crop
+```
-- [ ] Open the Presenter layer's properties.
-- [ ] Show the distinction between source dimensions, usable input and final layer size.
-- [ ] Apply an asymmetric input crop.
-- [ ] Double-click the layer to adjust its crop visually.
-- [ ] Zoom and reposition the content while the visible layer box stays fixed.
-- [ ] Show the faded cropped-out area.
-- [ ] Align the content inside the box.
-- [ ] Demonstrate **Recenter**, then **Reset crop**.
-- [ ] Undo back to a useful presenter framing.
+Stop rehearsal with Ctrl-C. `--tools /path/to/prefix` optionally finds tools under
+`usr/bin`, shared libraries under `usr/lib` and English OCR data under
+`usr/share/tessdata`. Normal distribution packages need no such prefix. The script
+forces X11 for both egui and GTK, uses a private portal bus and sets fresh XDG
+configuration/data directories for each shot. Keep the 1440 × 940 resolution and
+English interface: icon coordinates are deliberately simple and fixed. Rehearse
+again after changing interface layout, font scaling or the desktop tool versions.
-## 7. Bring geometry in from other applications
+## Output and review
-- [ ] Copy a simple layout from Illustrator and paste into Canvas Pilot.
-- [ ] Show destination mapping and the before/after geometry.
-- [ ] Demonstrate position-only versus position-and-size import.
-- [ ] Show the outline-inclusion option using Illustrator's stroked rectangles.
-- [ ] Apply, then undo.
-- [ ] Briefly repeat copy/paste from Figma and draw.io.
-- [ ] Drop the prepared PPTX or DXF file into the window.
-- [ ] Show page/slide selection if applicable, map the rectangles and apply.
+The initial 2026-11-17 series records application v0.9.16 (`dc3e6ca`). Version
+0.9.17 adds the recording tooling and guide without changing application behavior.
+The local `manifest.json` records the binary fingerprint, clip durations and hashes.
-## 8. Export and reopen
+Everything generated stays in the Git-ignored `showcase-videos/` folder. Each shot
+has its own `video.mp4` (H.264, 30 fps, no audio), English `captions.vtt`, poster,
+contact sheet, start/end captures, starting/ending project JSON and recording log.
+The gallery is `showcase-videos/index.html`. For browser caption support, serve it:
-- [ ] Open the export format selector to show the available formats.
-- [ ] Export the whole layout as SVG.
-- [ ] Export only the selected layer.
-- [ ] Open one export in its destination application.
-- [ ] Save the Canvas Pilot project.
-- [ ] Reopen it to show that editable settings and reference images are retained.
+```sh
+python3 -m http.server 8765 --bind 127.0.0.1 --directory showcase-videos
+```
-## 9. Connect to a screen processor
+Open `http://127.0.0.1:8765/`. There is no autoplay. Videos and source fixtures stay
+local; committing the recipe does not publish or upload the recordings.
-- [ ] Open device connection settings and connect.
-- [ ] Show detected screens and layers.
-- [ ] Load a device layer into the editor.
-- [ ] Show its saved device destination mapping.
-- [ ] Make a visible position or size change locally.
-- [ ] Select Preview and review the exact changes.
-- [ ] Send and show the resulting device layout.
-- [ ] Show the bottom **Send** and **Load** controls.
-- [ ] Demonstrate Selected or Folder transfer scope.
-- [ ] Briefly show the two sizing strategies.
-- [ ] If both devices are available, repeat a short load/edit/send sequence on the other family.
+Every take must decode successfully, but that is only the first check. Watch the
+clip/contact sheet and inspect the saved result: a clicked disabled button is not
+a successful import. Confirm visible movement, readable menus, complete dialogs,
+actual saved exports and restoration after undo. Failed takes are named
+`FAILED-video.mp4` and excluded from the gallery. Fix the recipe and rerun just that
+shot. Keep captions factual about what is visible and what was preloaded.
-## 10. Use device input previews
+## Simulator and hardware boundaries
-- [ ] Enable an input preview on a layer.
-- [ ] Capture a still and use it to demonstrate cropping real content.
-- [ ] Adjust crop-guide opacity.
-- [ ] Enable timed refresh briefly, then pause it.
-- [ ] Show importing a snapshot as a fixed reference image.
+The device fixture uses `127.0.0.1:3000`, with startup connection disabled. Check
+identity before filming. Standalone AQL Cmax 6.2.x is the currently supported
+Aquilon profile; the session simulator identifies as 6.2.79. Broader Aquilon/Midra
+coverage is tracked in the [project backlog](plan.md#to-do-list).
-## 11. Finish
+Connection and mapping inspection are read-only. For a separate send demonstration,
+first capture the chosen Preview layer's baseline, use already routed sources,
+review the exact geometry/crop/mask changes, send, verify readback, then restore
+and verify the baseline. Never include TAKE, source routing or shared-input edits
+implicitly. Do not use a saved host as authorization for another device. Simulator
+readback does not establish physical-output accuracy.
-- [ ] Briefly show themes and snapping preferences.
-- [ ] Restore the clean finished layout.
-- [ ] Fit the screen and save the project.
+For the local transfer take, the user authorized temporarily routing **only S1
+Preview layer 1 to LIVE_1**. The completed transfer take confirmed application readback, followed by a successful
+comparison with the original baseline (`simulator-restoration.json`, no mismatches).
+The baseline records source, geometry, anchor, classic
+crop and mask for all seven S1 layers in both banks. The local
+`showcase-videos/simulator_session.py` captures/restores this fixture, and
+`showcase-videos/record-transfer.py` records the take with restoration in `finally`.
+Those session-specific helpers and their JSON evidence stay beside the recordings,
+not in the reusable recorder or CI. They require the temporary `websocket-client`
+package and this session's tool paths; inspect and adapt them before reuse.
-Leave the unfinished Midra fill/aspect modes, future adapters and multiple-screen
-projects out of the feature demonstration. This checklist covers implemented
-workflows as of 2026-11-16. Aquilon support is scoped to standalone AQL Cmax 6.2.x,
-validated on the 6.2.79 emulator; describe emulator footage accordingly.
-
-For detailed controls, see the [advanced guide](guide/overview.md).
+To take the transfer shot manually: identify the simulator, preserve the same
+baseline, route its Preview source explicitly, link Presenter to Aquilon S1/layer
+1 in Mapping, connect, and click **Load linked layers**. Set width 720, X 900 and
+Y 300, open **Device mapping & transfer**, expand the window, verify Preview and
+the linked destination, then **Send mapped layers**. Wait for the readback success
+message. Restore the original Preview source and all edited fields, apply the
+preset update and compare both banks with the captured baseline. Stop if bank
+mapping changes or any restoration check fails.
diff --git a/docs/canvas-pilot/plan.md b/docs/canvas-pilot/plan.md
index 41667d8..4604539 100644
--- a/docs/canvas-pilot/plan.md
+++ b/docs/canvas-pilot/plan.md
@@ -78,6 +78,13 @@ checks and stretch goals below remain open; the tag does not mark them complete.
## To-do list
+- [ ] **Broaden coverage to every Aquilon and Midra model.** Requested 2026-11-17:
+ inventory both product ranges and their firmware/link modes; validate identity,
+ bounded reads, geometry/crop/mask conversion, input previews and reviewed writes
+ per model. Start with the AQL C+ simulator encountered during showcase recording.
+ Preserve explicit unsupported-mode errors until each adapter path is validated;
+ emulator coverage and physical-output acceptance remain separate.
+
- [ ] **Resolve local input-ratio correction scope.** Shared-input Content ratio
and Transform to controls already exist and are [documented](guide/formats-and-crop.md#content-ratio-versus-transform-to).
Whether to add a local correction/preview model remains an unanswered question;
diff --git a/scripts/record-showcase.py b/scripts/record-showcase.py
new file mode 100644
index 0000000..1314097
--- /dev/null
+++ b/scripts/record-showcase.py
@@ -0,0 +1,1238 @@
+#!/usr/bin/env python3
+"""Record isolated Canvas Pilot feature clips. See docs/canvas-pilot/feature-demo-checklist.md.
+
+Requires a dedicated 1440x940 X11 display, ffmpeg/ffprobe, ImageMagick, tesseract,
+xdotool and xclip. Never point --display at your working desktop. Generated files
+and fresh per-shot profiles stay under the ignored showcase-videos directory.
+"""
+
+import argparse
+import base64
+import csv
+import html
+import io
+import json
+import math
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import time
+import zipfile
+
+ROOT = Path(__file__).resolve().parents[1]
+OUT = ROOT / "showcase-videos"
+
+
+def run(args, **kwargs):
+ kwargs.setdefault("timeout", 60)
+ return subprocess.run([str(a) for a in args], check=True, **kwargs)
+
+
+def baseline():
+ p = json.loads((ROOT / "docs/interfaces/canvas-pilot-v18.example.json").read_text())
+ p["folders"] = []
+ p["input_proposals"] = []
+ p["editor"].update(
+ backdrop_title="Canvas Pilot · feature showcase",
+ selected_layer_ids=[1],
+ position_point="top_left",
+ position_layer_point=None,
+ viewport_zoom=1,
+ viewport_pan=[0, 0],
+ outline_layers=False,
+ show_source_pattern=False,
+ )
+ for i, layer in enumerate(p["layers"]):
+ layer.update(
+ folder="",
+ name=["Slides", "Presenter"][i],
+ device_link=None,
+ layer_fit=None,
+ visible=True,
+ locked=False,
+ pivot=[0.5, 0.5],
+ )
+ layer["advanced_crop"] = dict.fromkeys(["left", "right", "top", "bottom"], 0.0)
+ layer["mask"] = dict(origin="layer", left=0.0, right=0.0, top=0.0, bottom=0.0)
+ return p
+
+
+def prepare_assets():
+ assets = OUT / "assets"
+ assets.mkdir(parents=True, exist_ok=True)
+ svg = """"""
+ (assets / "source.svg").write_text(svg)
+ run(
+ ["convert", "-background", "none", assets / "source.svg", assets / "source.png"]
+ )
+ (assets / "geometry.svg").write_text(
+ """"""
+ )
+ with zipfile.ZipFile(ROOT / "docs/language-packs/language-pack.zip") as source:
+ with zipfile.ZipFile(
+ assets / "language-pack-revision-2.zip", "w", zipfile.ZIP_DEFLATED
+ ) as output:
+ for name in source.namelist():
+ data = source.read(name)
+ if name == "manifest.json":
+ manifest = json.loads(data)
+ manifest["revision"] = 2
+ data = json.dumps(manifest, ensure_ascii=False).encode()
+ output.writestr(name, data)
+ return assets
+
+
+class Studio:
+ def __init__(self, args):
+ self.args = args
+ self.env = os.environ.copy()
+ self.env.pop("WAYLAND_DISPLAY", None)
+ self.env.update(
+ DISPLAY=args.display,
+ WINIT_UNIX_BACKEND="x11",
+ WINIT_X11_SCALE_FACTOR="1",
+ XDG_CURRENT_DESKTOP="GNOME",
+ XDG_SESSION_TYPE="x11",
+ GTK_USE_PORTAL="0",
+ GDK_BACKEND="x11",
+ )
+ if args.tools:
+ self.env["PATH"] = (
+ str(Path(args.tools) / "usr/bin") + ":" + self.env["PATH"]
+ )
+ self.env["LD_LIBRARY_PATH"] = str(Path(args.tools) / "usr/lib")
+ self.env["TESSDATA_PREFIX"] = str(Path(args.tools) / "usr/share/tessdata")
+ self.pos = (1000, 800)
+ self.app = None
+ self.recorder = None
+ self.events = []
+ self.started = 0
+ self.folder = OUT
+ self.assets = prepare_assets()
+ self.bus = None
+ self.portal_processes = []
+
+ def cmd(self, *args, **kw):
+ if kw.pop("capture_output", False):
+ kw.setdefault("stdout", subprocess.PIPE)
+ kw.setdefault("stderr", subprocess.PIPE)
+ else:
+ kw.setdefault("stdout", subprocess.DEVNULL)
+ kw.setdefault("stderr", subprocess.DEVNULL)
+ return run(args, env=self.env, **kw)
+
+ def portals(self):
+ result = self.cmd(
+ "dbus-daemon",
+ "--session",
+ "--fork",
+ "--print-address=1",
+ "--print-pid=1",
+ capture_output=True,
+ text=True,
+ ).stdout.splitlines()
+ self.env["DBUS_SESSION_BUS_ADDRESS"] = result[0]
+ self.bus = int(result[1])
+ config = OUT / "portal-config"
+ (config / "xdg-desktop-portal").mkdir(parents=True, exist_ok=True)
+ (config / "xdg-desktop-portal/portals.conf").write_text(
+ "[preferred]\ndefault=gtk\n"
+ )
+ penv = dict(
+ self.env,
+ XDG_CONFIG_HOME=str(config),
+ XDG_DATA_HOME=str(OUT / "portal-data"),
+ XDG_CACHE_HOME=str(OUT / "portal-cache"),
+ )
+ for executable in [
+ "/usr/lib/xdg-desktop-portal-gtk",
+ "/usr/lib/xdg-desktop-portal",
+ ]:
+ log = open(OUT / (Path(executable).name + ".log"), "w")
+ self.portal_processes.append(
+ subprocess.Popen(
+ [executable], env=penv, stdout=log, stderr=subprocess.STDOUT
+ )
+ )
+ time.sleep(2)
+
+ def stop_app(self):
+ if self.app and self.app.poll() is None:
+ self.app.terminate()
+ try:
+ self.app.wait(timeout=5)
+ except subprocess.TimeoutExpired:
+ self.app.kill()
+ self.app.wait()
+ self.app = None
+
+ def start(self, slug, variant="default"):
+ self.stop_app()
+ self.folder = OUT / slug
+ self.folder.mkdir(parents=True, exist_ok=True)
+ (self.folder / "shot.json").unlink(missing_ok=True)
+ profile = self.folder / "profile"
+ if profile.exists():
+ shutil.rmtree(profile)
+ config = profile / "config/midra-layout"
+ config.mkdir(parents=True)
+ settings = json.loads(
+ (
+ ROOT / "docs/interfaces/canvas-pilot-settings-v14.example.json"
+ ).read_text()
+ )
+ settings.update(
+ language="en",
+ autoconnect_at_startup=False,
+ midra_host="",
+ recent_midra_hosts=[],
+ )
+ p = baseline()
+ if variant in ["crop", "mask", "fits", "preview", "mask-snap"]:
+ image = base64.b64encode((self.assets / "source.png").read_bytes()).decode()
+ p["workspace"]["previews"] = [
+ dict(
+ layer_id=l["id"],
+ source_id=l["source_id"],
+ input=i + 1,
+ host="",
+ enabled=True,
+ automatic=False,
+ guide_opacity=0.5,
+ name="Offline demonstration image",
+ image_base64=image,
+ )
+ for i, l in enumerate(p["layers"])
+ ]
+ if variant in ["crop", "mask", "preview"]:
+ p["layers"][1]["advanced_crop"] = dict(
+ left=480.0, right=480.0, top=270.0, bottom=270.0
+ )
+ if variant == "mask":
+ p["layers"][1]["mask"].update(left=0.15, right=0.15, top=0.1, bottom=0.1)
+ if variant == "fits":
+ p["layers"][1]["bounds"].update(width=500.0, height=500.0)
+ p["layers"][1]["layer_fit"] = "centered"
+ if variant == "mask-snap":
+ p["layers"][0]["mask"].update(right=0.25)
+ p["workspace"]["snapping"].update(
+ enabled=True,
+ pixels=False,
+ screen_edges=False,
+ layer_edges=False,
+ mask_edges=True,
+ )
+ if variant == "reference":
+ p["references"] = [
+ dict(
+ name="Stage plan — offline reference",
+ image_base64=base64.b64encode(
+ (self.assets / "source.png").read_bytes()
+ ).decode(),
+ visible=True,
+ opacity=0.65,
+ preserve_ratio=True,
+ native_size=False,
+ offset=[0.0, 0.0],
+ )
+ ]
+ p["editor"]["outline_layers"] = True
+ if variant == "organize":
+ p["folders"] = ["Presentation"]
+ p["layers"][0]["folder"] = "Presentation"
+ if variant == "import":
+ p["editor"]["selected_layer_ids"] = [1, 2]
+ if variant == "language":
+ packs = config / "language-packs"
+ packs.mkdir()
+ shutil.copyfile(
+ ROOT / "docs/language-packs/language-pack.zip",
+ packs / "example-uk-bho.zip",
+ )
+ if variant == "device":
+ settings["midra_host"] = "127.0.0.1:3000"
+ (config / "settings.json").write_text(json.dumps(settings))
+ (config / "last_project.json").write_text(
+ json.dumps(
+ dict(version=1, project=p, project_path=None, manual_saved_at=None)
+ )
+ )
+ (self.folder / "starting-project.json").write_text(
+ json.dumps(p, indent=2) + "\n"
+ )
+ self.env.update(
+ XDG_CONFIG_HOME=str(profile / "config"), XDG_DATA_HOME=str(profile / "data")
+ )
+ self.app = subprocess.Popen(
+ [str(ROOT / "target/debug/canvas-pilot")],
+ env=self.env,
+ stdout=open(self.folder / "app.log", "w"),
+ stderr=subprocess.STDOUT,
+ )
+ time.sleep(3)
+ ids = self.cmd(
+ "xdotool",
+ "search",
+ "--name",
+ "^Canvas Pilot$",
+ capture_output=True,
+ text=True,
+ ).stdout.split()
+ self.window = ids[-1]
+ self.cmd("xdotool", "windowmove", self.window, "0", "0")
+ self.cmd("xdotool", "windowsize", self.window, "1440", "940")
+ self.cmd("xdotool", "windowfocus", self.window)
+ self.move(1000, 800, 0.1)
+ self.capture("start.png")
+
+ def move(self, x, y, duration=0.45):
+ start = self.pos
+ begun = time.monotonic()
+ while True:
+ f = min(1, (time.monotonic() - begun) / duration)
+ e = (1 - math.cos(math.pi * f)) / 2
+ self.cmd(
+ "xdotool",
+ "mousemove",
+ str(round(start[0] + (x - start[0]) * e)),
+ str(round(start[1] + (y - start[1]) * e)),
+ stdout=subprocess.DEVNULL,
+ )
+ if f == 1:
+ break
+ time.sleep(1 / 40)
+ self.pos = (x, y)
+
+ def click(self, x, y, button=1, pause=0.65):
+ self.move(x, y)
+ self.cmd("xdotool", "mousedown", str(button))
+ time.sleep(0.1)
+ self.cmd("xdotool", "mouseup", str(button))
+ time.sleep(pause)
+
+ def drag(self, x, y, tx, ty):
+ self.move(x, y)
+ self.cmd("xdotool", "mousedown", "1")
+ self.move(tx, ty, 1.4)
+ self.cmd("xdotool", "mouseup", "1")
+ time.sleep(0.8)
+
+ def key(self, key):
+ self.cmd("xdotool", "keydown", key)
+ time.sleep(0.12)
+ self.cmd("xdotool", "keyup", key)
+ time.sleep(0.45)
+
+ def type(self, text):
+ self.clipboard(text)
+ self.key("ctrl+v")
+
+ def field(self, x, y, value):
+ self.click(x, y)
+ self.key("ctrl+a")
+ self.type(str(value))
+ self.key("Return")
+
+ def capture(self, name):
+ path = self.folder / name
+ self.cmd("import", "-window", "root", path)
+ return path
+
+ def find(self, label, region=None, last=False):
+ image = self.capture("probe.png")
+ raw = self.cmd(
+ "tesseract",
+ image,
+ "stdout",
+ "--psm",
+ "11",
+ "-c",
+ "tessedit_create_tsv=1",
+ capture_output=True,
+ text=True,
+ stderr=subprocess.DEVNULL,
+ ).stdout
+ groups = {}
+ for row in csv.DictReader(io.StringIO(raw), delimiter="\t"):
+ if not row["text"].strip():
+ continue
+ x, y, w, h = [int(row[k]) for k in ["left", "top", "width", "height"]]
+ if region and not (
+ region[0] <= x < region[2] and region[1] <= y < region[3]
+ ):
+ continue
+ groups.setdefault(
+ tuple(row[k] for k in ["block_num", "par_num", "line_num"]), []
+ ).append((row["text"], x, y, w, h))
+ norm = lambda s: re.sub(r"[^a-z0-9]", "", s.lower())
+ query = norm(label)
+ matches = []
+ for words in groups.values():
+ for i in range(len(words)):
+ text = ""
+ for j in range(i, len(words)):
+ text += norm(words[j][0])
+ if text == query:
+ segment = words[i : j + 1]
+ x = min(w[1] for w in segment)
+ y = min(w[2] for w in segment)
+ right = max(w[1] + w[3] for w in segment)
+ bottom = max(w[2] + w[4] for w in segment)
+ matches.append(
+ (
+ i == 0 and j == len(words) - 1,
+ ((x + right) / 2, (y + bottom) / 2),
+ )
+ )
+ if len(text) > len(query):
+ break
+ if not matches:
+ raise RuntimeError(f"Cannot find {label!r}; inspect {image}")
+ exact = [point for whole, point in matches if whole]
+ points = exact or [point for _, point in matches]
+ return points[-1 if last else 0]
+
+ def label(self, text, region=None, last=False, pause=0.65):
+ self.click(*self.find(text, region, last), pause=pause)
+
+ def expect_absent(self, text):
+ try:
+ self.find(text)
+ except RuntimeError:
+ return
+ raise RuntimeError(f"{text!r} is still visible; action did not finish")
+
+ def hover(self, text):
+ self.move(*self.find(text))
+ time.sleep(1)
+
+ def note(self, text, pause=1):
+ self.events.append((time.monotonic() - self.started, text))
+ time.sleep(pause)
+
+ def clipboard(self, text):
+ self.cmd("xclip", "-selection", "clipboard", "-i", input=text.encode())
+
+ def dialog(self, path, save=False):
+ time.sleep(1)
+ windows = self.cmd(
+ "xdotool",
+ "search",
+ "--onlyvisible",
+ "--class",
+ ".",
+ capture_output=True,
+ text=True,
+ ).stdout.split()
+ picker = None
+ for window in windows:
+ if window == self.window:
+ continue
+ geometry = self.cmd(
+ "xdotool",
+ "getwindowgeometry",
+ "--shell",
+ window,
+ capture_output=True,
+ text=True,
+ ).stdout
+ dimensions = dict(re.findall(r"(WIDTH|HEIGHT)=(\d+)", geometry))
+ if (
+ int(dimensions.get("WIDTH", 0)) > 500
+ and int(dimensions.get("HEIGHT", 0)) > 300
+ ):
+ picker = window
+ break
+ if picker is None:
+ raise RuntimeError("Native file picker did not appear")
+ if picker:
+ self.cmd("xdotool", "windowmove", picker, "100", "100")
+ self.cmd("xdotool", "windowsize", picker, "1100", "740")
+ self.cmd("xdotool", "windowfocus", picker)
+ self.key("ctrl+l")
+ self.key("ctrl+a")
+ self.type(str(path))
+ self.key("Return")
+ time.sleep(1)
+ if save:
+ self.key("alt+s")
+ self.capture("file-dialog-result.png")
+ time.sleep(1)
+ self.cmd("xdotool", "windowfocus", self.window)
+
+ def properties(self, tab):
+ self.click(1240, 300)
+ self.click(
+ {
+ "Source": 48,
+ "Layer": 106,
+ "Crop": 156,
+ "Mask": 208,
+ "Mapping": 269,
+ "Preview": 343,
+ }[tab],
+ 71,
+ )
+ self.click(
+ {
+ "Source": 48,
+ "Layer": 106,
+ "Crop": 156,
+ "Mask": 208,
+ "Mapping": 269,
+ "Preview": 343,
+ }[tab],
+ 71,
+ )
+
+ def close_window(self):
+ self.click(537, 35)
+
+ def record(self, slug, title, variant, actions):
+ self.start(slug, variant)
+ (self.folder / "shot.json").unlink(missing_ok=True)
+ self.events = []
+ self.started = time.monotonic()
+ video = self.folder / "video.mp4"
+ for name in ["layout.svg", "showcase.pilot.json", "showcase.pilot.json.json"]:
+ (self.folder / name).unlink(missing_ok=True)
+ self.recorder = subprocess.Popen(
+ [
+ "ffmpeg",
+ "-hide_banner",
+ "-y",
+ "-f",
+ "x11grab",
+ "-draw_mouse",
+ "1",
+ "-framerate",
+ "30",
+ "-video_size",
+ "1440x940",
+ "-i",
+ self.args.display + ".0",
+ "-an",
+ "-c:v",
+ "libx264",
+ "-preset",
+ "veryfast",
+ "-crf",
+ "18",
+ "-pix_fmt",
+ "yuv420p",
+ "-movflags",
+ "+faststart",
+ str(video),
+ ],
+ env=self.env,
+ stdin=subprocess.PIPE,
+ stdout=open(self.folder / "record.log", "w"),
+ stderr=subprocess.STDOUT,
+ )
+ ok = False
+ try:
+ self.note(title, 2)
+ actions(self)
+ time.sleep(1.5)
+ self.capture("end.png")
+ ok = True
+ finally:
+ if not ok:
+ try:
+ self.capture("failure.png")
+ except subprocess.SubprocessError:
+ pass
+ try:
+ self.recorder.communicate(b"q\n", timeout=20)
+ except subprocess.TimeoutExpired:
+ self.recorder.kill()
+ self.recorder.wait()
+ self.recorder = None
+ self.stop_app()
+ recovery = self.folder / "profile/config/midra-layout/last_project.json"
+ if recovery.exists():
+ (self.folder / "ending-project.json").write_text(
+ json.dumps(json.loads(recovery.read_text())["project"], indent=2)
+ + "\n"
+ )
+ if not ok:
+ video.rename(self.folder / "FAILED-video.mp4")
+ try:
+ verify_result(slug, self.folder)
+ except (AssertionError, ValueError) as error:
+ video.rename(self.folder / "FAILED-video.mp4")
+ raise RuntimeError(f"Result verification failed: {error}") from error
+ run(["ffmpeg", "-v", "error", "-i", video, "-f", "null", "-"])
+ info = json.loads(
+ run(
+ [
+ "ffprobe",
+ "-v",
+ "error",
+ "-show_entries",
+ "format=duration,size",
+ "-of",
+ "json",
+ video,
+ ],
+ capture_output=True,
+ text=True,
+ ).stdout
+ )["format"]
+ duration = float(info["duration"])
+ stamp = (
+ lambda s: f"{int(s)//3600:02}:{int(s)//60%60:02}:{int(s)%60:02}.{int(s%1*1000):03}"
+ )
+ captions = "WEBVTT\n\n"
+ for i, (start, text) in enumerate(self.events):
+ end = self.events[i + 1][0] if i + 1 < len(self.events) else duration
+ captions += f"{stamp(start)} --> {stamp(end)}\n{text}\n\n"
+ (self.folder / "captions.vtt").write_text(captions)
+ (self.folder / "shot.json").write_text(
+ json.dumps(
+ dict(
+ id=slug,
+ title=title,
+ variant=variant,
+ duration=duration,
+ bytes=int(info["size"]),
+ events=self.events,
+ status="recorded; awaiting visual review",
+ ),
+ indent=2,
+ )
+ + "\n"
+ )
+ run(
+ [
+ "ffmpeg",
+ "-loglevel",
+ "error",
+ "-y",
+ "-ss",
+ str(duration / 2),
+ "-i",
+ video,
+ "-frames:v",
+ "1",
+ self.folder / "poster.jpg",
+ ]
+ )
+ run(
+ [
+ "ffmpeg",
+ "-loglevel",
+ "error",
+ "-y",
+ "-i",
+ video,
+ "-vf",
+ f"fps=4/{duration},scale=720:-1,tile=2x2",
+ "-frames:v",
+ "1",
+ self.folder / "contact.jpg",
+ ]
+ )
+ print(f"RECORDED {slug}: {duration:.1f}s", flush=True)
+
+ def close(self):
+ self.stop_app()
+ for process in self.portal_processes:
+ process.terminate()
+ if self.bus:
+ try:
+ os.kill(self.bus, 15)
+ except ProcessLookupError:
+ pass
+
+
+def verify_result(slug, folder):
+ """Check persistent outcomes as well as the screenshots reviewed by a person."""
+ start = json.loads((folder / "starting-project.json").read_text())
+ end = json.loads((folder / "ending-project.json").read_text())
+ before = {layer["id"]: layer for layer in start["layers"]}
+ after = {layer["id"]: layer for layer in end["layers"]}
+ if slug in {
+ "01-project-save-reopen",
+ "03-alignment-pivots-measurement",
+ "04-group-resizing",
+ "12-clipboard-import",
+ "13-file-import",
+ "19-mask-snapping",
+ }:
+ assert {key: value["bounds"] for key, value in before.items()} == {
+ key: value["bounds"] for key, value in after.items()
+ }, "Reopen/undo did not restore the original geometry"
+ if slug == "02-move-resize":
+ assert after[1]["bounds"]["width"] == 720, "Exact width did not apply"
+ if slug == "08-crop":
+ assert not any(after[1]["advanced_crop"].values()), "Crop reset did not apply"
+ if slug == "09-mask":
+ assert all(
+ after[1]["mask"][edge] == 0 for edge in ("left", "right", "top", "bottom")
+ ), "Mask reset did not apply"
+ if slug == "11-fit-modes":
+ assert after[1]["layer_fit"] == "one_to_one", "Final 1:1 fit did not apply"
+ if slug == "06-layers-folders":
+ assert len(after) == 2 and all(
+ layer["folder"] == "Presentation" for layer in after.values()
+ ), "Folder organization/removal did not finish"
+ if slug == "20-language-pack-lifecycle":
+ assert not list(
+ (folder / "profile/config/midra-layout/language-packs").glob("*.zip")
+ ), "Pack removal did not finish"
+
+
+# Each shot starts from its own documented seed; no shot depends on another clip.
+def movement(s):
+ s.note("Move the selected layer; the inspector follows its position.")
+ s.drag(795, 390, 705, 460)
+ s.note("Resize with a corner handle while preserving aspect ratio.")
+ s.drag(876, 553, 935, 588)
+ s.note("Undo and redo are single editing steps.")
+ s.key("ctrl+z")
+ s.key("ctrl+shift+z")
+ s.note("Enter an exact width, then nudge with arrow keys.")
+ s.field(1150, 650, "720")
+ s.click(735, 470)
+ s.key("Right")
+ s.key("shift+Down")
+
+
+def crop(s):
+ s.note("A prepared 200% crop starts this clip; the layer rectangle remains fixed.")
+ s.label("Adjust layer crop")
+ s.drag(795, 390, 865, 420)
+ s.note("Faded content outside the rectangle helps with reframing.")
+ s.key("Left")
+ s.key("shift+Up")
+ s.note("Crop properties offer precise zoom and offset controls.")
+ s.properties("Crop")
+ s.capture("crop-properties.png")
+ s.note("Recenter preserves zoom; Reset crop returns to the minimum framing.")
+ s.label("Recenter")
+ s.label("Reset crop")
+ s.close_window()
+
+
+def mask(s):
+ s.note("The prepared mask hides picture edges; double-click enters crop editing.")
+ s.click(795, 390)
+ s.key("Escape")
+ s.click(795, 390)
+ s.cmd("xdotool", "click", "--repeat", "2", "--delay", "120", "1")
+ time.sleep(0.8)
+ s.note(
+ "Tab switches from crop to mask editing. Hatching reveals the hidden picture."
+ )
+ s.key("Tab")
+ s.drag(680, 390, 725, 390)
+ s.note("Move the reveal window without changing the layer rectangle.")
+ s.drag(795, 390, 825, 410)
+ s.note("Numeric Mask controls include origin, centering and reset.")
+ s.properties("Mask")
+ s.label("Center mask")
+ s.label("Reset mask")
+ s.close_window()
+
+
+def language(s):
+ s.click(50, 81)
+ s.label("Open all settings")
+ s.note(
+ "Language packs have one management section: installed languages and revision."
+ )
+ s.label("Language packs")
+ s.label("Remove pack")
+ s.note("Removal names every bundled language. Cancel leaves the pack installed.", 2)
+ s.label("Cancel")
+ s.label("Appearance")
+ s.note("Appearance controls resize the interface and choose a theme.")
+ s.label("Browse all themes")
+ s.label("Corporate Light")
+ s.capture("light-theme.png")
+ s.note("Preview another language; the confirmation lets you return to English.")
+ s.click(220, 71)
+ s.label("French")
+ s.capture("language-preview.png")
+ time.sleep(3)
+ s.click(630, 531)
+
+
+def navigation(s):
+ s.note("Zoom around the pointer; middle-drag pans without moving geometry.")
+ s.move(790, 390)
+ s.cmd("xdotool", "click", "--repeat", "3", "--delay", "150", "4")
+ time.sleep(1)
+ s.move(650, 500)
+ s.cmd("xdotool", "mousedown", "2")
+ s.move(760, 560, 1)
+ s.cmd("xdotool", "mouseup", "2")
+ time.sleep(1)
+ s.note(
+ "Fit screen restores the complete output. Zoom to selection frames the selected layer."
+ )
+ s.click(496, 81)
+ s.click(532, 81)
+ s.click(496, 81)
+ s.note("Output format exposes standard and custom resolutions.")
+ s.click(776, 81)
+ s.capture("output-dialog.png")
+
+
+def clipboard(s):
+ s.note("Paste SVG geometry from an external application; review before applying.")
+ s.key("ctrl+a")
+ s.clipboard((s.assets / "geometry.svg").read_text())
+ s.key("ctrl+v")
+ time.sleep(1)
+ s.label("Selected layers")
+ s.label("All layers")
+ s.click(650, 723)
+ s.click(560, 779)
+ s.capture("import-review.png")
+ s.note("Choose mapped geometry and import it as a single undoable edit.", 2)
+ s.label("Import mapped values")
+ s.expect_absent("Import layer values")
+ s.capture("imported.png")
+ time.sleep(2)
+ s.note("Undo restores the previous geometry.")
+ s.key("ctrl+z")
+
+
+def export(s):
+ s.click(50, 81)
+ s.label("Export")
+ s.label("Export layers")
+ s.note(
+ "One export window selects format, layer scope and optional editor metadata.", 2
+ )
+ s.capture("export-window.png")
+ s.label("SVG vector editors")
+ s.capture("formats.png")
+ time.sleep(2)
+ s.key("Escape")
+ s.label("Selected layers")
+ s.label("All layers")
+ s.label("Canvas Pilot settings not included")
+ s.capture("metadata-options.png")
+ s.note("Export the complete layout as an SVG file.")
+ s.label("Export", region=(15, 100, 360, 850), last=True)
+ s.dialog(s.folder / "layout.svg", save=True)
+ if not (s.folder / "layout.svg").exists():
+ raise RuntimeError("SVG export was not saved")
+
+
+def device(s):
+ s.note("Aquilon simulator at 127.0.0.1:3000 — not physical-output acceptance.")
+ s.click(50, 81)
+ s.label("Device connection")
+ s.capture("connection.png")
+ s.label("Connect", last=True)
+ time.sleep(4)
+ try:
+ s.find("Online")
+ except RuntimeError:
+ s.label("Connect", last=True)
+ time.sleep(4)
+ s.find("Online")
+ s.capture("identity.png")
+ s.click(417, 35)
+ s.note(
+ "Inspect the detected screen, Preview bank and explicit destination mapping."
+ )
+ s.click(170, 923)
+ s.capture("device-mapping.png")
+ time.sleep(3)
+
+
+def fits(s):
+ s.note("A square layer makes the source-to-container fit differences visible.")
+ s.properties("Crop")
+ s.capture("advanced-fit.png")
+ for old, new in [
+ ("Centered (fit)", "Fullscreen (stretch)"),
+ ("Fullscreen (stretch)", "Cropped (fill)"),
+ ("Cropped (fill)", "1:1 pixels"),
+ ]:
+ s.note(new + ": inspect the picture preview and unchanged container.")
+ s.click(95, 180)
+ s.click(
+ 85,
+ {"Fullscreen (stretch)": 267, "Cropped (fill)": 297, "1:1 pixels": 207}[
+ new
+ ],
+ )
+ time.sleep(1)
+ s.capture("fit-modes.png")
+ s.close_window()
+
+
+def snap(s):
+ s.note("Enable proximity snapping and choose its targets.")
+ s.click(646, 81)
+ s.label("Snap movement & resizing")
+ s.label("Mask edges")
+ s.click(1000, 800)
+ s.note(
+ "Move the layer close to another edge; the guide marks the snapped position."
+ )
+ s.drag(795, 390, 588, 390)
+ s.note("Overlay-grid visibility and snapping are independent.")
+ s.click(682, 81)
+ s.label("Show overlay grid")
+ s.label("Snap to overlay grid")
+ s.capture("grid-options.png")
+ s.click(1000, 800)
+ s.click(580, 390)
+ s.key("shift+Right")
+ s.key("ctrl+z")
+
+
+def mask_snap(s):
+ s.note(
+ "Only mask-edge targets are enabled in this prepared scene. The left picture ends before its layer box."
+ )
+ s.click(646, 81)
+ s.capture("mask-targets.png")
+ s.click(1000, 800)
+ s.note("Drag near the visible picture edge, rather than the original layer edge.")
+ s.drag(795, 390, 503, 400)
+ s.note("Undo restores the original placement.")
+ s.key("ctrl+z")
+
+
+def groups(s):
+ s.note("Shift-click selects both layers; they move together.")
+ s.cmd("xdotool", "keydown", "Shift_L")
+ s.click(250, 390)
+ s.cmd("xdotool", "keyup", "Shift_L")
+ s.drag(795, 390, 755, 430)
+ s.key("ctrl+z")
+ for mode in ["Same handles", "Mirror horizontally", "Opposite handles"]:
+ s.note(mode + ": resize the pair, then undo before the next example.")
+ s.click(795, 390, 3)
+ s.label("Resize together")
+ s.click(
+ 1080,
+ {"Same handles": 606, "Mirror horizontally": 634, "Opposite handles": 662}[
+ mode
+ ],
+ )
+ s.drag(965, 483, 1000, 510)
+ s.key("ctrl+z")
+
+
+def alignment(s):
+ s.note("Alignment targets the output when one layer is selected.")
+ s.click(585, 81)
+ s.capture("alignment-menu.png")
+ # The icon grid follows the target selector in this fixed-size menu.
+ x, y = s.find("Screen (one selected layer)")
+ s.click(x, y + 74)
+ time.sleep(1)
+ s.note("Undo alignment, then reposition the resize pivot.")
+ s.key("ctrl+z")
+ s.click(722, 81)
+ s.drag(795, 389, 629, 294)
+ s.note("A corner resize now keeps the relocated pivot fixed.")
+ s.drag(965, 483, 1000, 510)
+ s.key("ctrl+z")
+ s.click(722, 81)
+ s.note(
+ "Measurement references change the displayed coordinates without moving geometry."
+ )
+ s.label("Top left to Top left")
+ s.capture("measurement-points.png")
+ s.click(1130, 569)
+ time.sleep(2)
+ s.key("Escape")
+
+
+def organize(s):
+ s.note(
+ "A prepared folder contains Slides. Move Presenter into it from the layer menu."
+ )
+ s.click(1185, 116, 3)
+ s.label("Move to folder")
+ s.label("Presentation")
+ s.note(
+ "Collapse and expand the folder; visibility and lock controls apply to its members."
+ )
+ s.click(1083, 114)
+ s.click(1083, 114)
+ s.click(1395, 114)
+ s.click(1395, 114)
+ s.click(1357, 114)
+ s.click(1357, 114)
+ s.note(
+ "The layer manager provides bulk names, folders, ordering and add/remove actions."
+ )
+ s.click(1403, 76)
+ s.capture("layer-manager.png")
+ s.note("Add a layer, give it a name and folder, then change its stacking order.")
+ s.label("Add layer")
+ s.field(250, 163, "Logo")
+ s.field(420, 163, "Branding")
+ s.click(70, 166)
+ s.capture("reordered.png")
+ s.note("Remove the temporary layer; existing layers keep their IDs.")
+ s.label("Remove selected")
+ s.capture("removed.png")
+
+
+def reference(s):
+ s.note(
+ "A prepared offline reference image guides placement; outlines keep it visible."
+ )
+ s.click(50, 81)
+ s.label("View")
+ s.label("Reference image settings")
+ s.note(
+ "Reference opacity and native-pixel placement are independent of layer geometry."
+ )
+ s.label("Show reference")
+ s.label("Show reference")
+ s.label("Native pixels (1 image pixel = 1 screen pixel)")
+ s.capture("reference-settings.png")
+ time.sleep(2)
+
+
+def preview(s):
+ s.note(
+ "This is a cached, labelled offline demonstration image, not a live capture."
+ )
+ s.properties("Preview")
+ s.capture("preview-settings.png")
+ s.note("Preview controls show capture setup, refresh and crop-guide opacity.", 2)
+ s.close_window()
+ s.label("Adjust layer crop")
+ s.drag(795, 390, 830, 405)
+
+
+def source(s):
+ s.note(
+ "Source dimensions, usable input and final layer size are different concepts."
+ )
+ s.properties("Source")
+ s.capture("source-settings.png")
+ s.note(
+ "Advanced shared-input controls are opt-in; opening this tab sends nothing.", 2
+ )
+ s.label("Edit advanced input settings and include my edits when sending")
+ s.capture("advanced-source.png")
+ time.sleep(2)
+ s.close_window()
+
+
+def file_import(s):
+ s.note("Import a real SVG file from disk; geometry is reviewed before application.")
+ s.click(184, 81)
+ s.label("Geometry file")
+ s.dialog(s.assets / "geometry.svg")
+ time.sleep(1)
+ s.click(700, 125)
+ s.capture("file-review.png")
+ s.note("Both selected layers are mapped; apply position and size together.", 2)
+ s.label("Import mapped values")
+ s.expect_absent("Import layer values")
+ s.capture("imported.png")
+ time.sleep(2)
+ s.note("The imported edit can be undone.")
+ s.key("ctrl+z")
+
+
+def project(s):
+ destination = s.folder / "showcase.pilot.json"
+ s.note(
+ "Save a named project including editable settings and local workspace state."
+ )
+ s.click(123, 81)
+ s.label("Save project")
+ s.dialog(destination, save=True)
+ if not destination.exists():
+ raise RuntimeError("Project file was not saved")
+ s.label("OK")
+ s.note(
+ "Make a change, then reopen the saved project with an explicit replacement review."
+ )
+ s.drag(795, 390, 745, 430)
+ s.click(123, 81)
+ s.label("Open project")
+ s.dialog(destination)
+ s.label("Open project", last=True)
+ time.sleep(2)
+ s.capture("reopened.png")
+
+
+def pack_lifecycle(s):
+ s.click(50, 81)
+ s.label("Open all settings")
+ s.label("Language packs")
+ s.note(
+ "Install the example ZIP: Ukrainian and Bhojpuri become available immediately."
+ )
+ s.click(270, 228)
+ s.dialog(ROOT / "docs/language-packs/language-pack.zip")
+ s.capture("installed.png")
+ time.sleep(2)
+ s.note("A higher revision updates the existing pack without an overwrite warning.")
+ s.click(270, 228)
+ s.dialog(s.assets / "language-pack-revision-2.zip")
+ s.capture("updated.png")
+ time.sleep(2)
+ s.note(
+ "An older revision requires an explicit overwrite decision. Cancel keeps revision 2."
+ )
+ s.click(270, 228)
+ s.dialog(ROOT / "docs/language-packs/language-pack.zip")
+ s.find("Overwrite pack")
+ s.capture("downgrade-warning.png")
+ time.sleep(2)
+ s.label("Cancel")
+ s.note("Remove the pack after reviewing the two languages affected.")
+ s.label("Remove pack")
+ s.capture("remove-warning.png")
+ time.sleep(2)
+ s.click(550, 524)
+ s.capture("removed-pack.png")
+
+
+SHOTS = {
+ "20-language-pack-lifecycle": (
+ "Install, update and remove a language pack",
+ "default",
+ pack_lifecycle,
+ ),
+ "01-project-save-reopen": ("Project save and reopen", "default", project),
+ "03-alignment-pivots-measurement": (
+ "Alignment, pivots and measurement references",
+ "default",
+ alignment,
+ ),
+ "04-group-resizing": ("Group movement and coordinated resizing", "default", groups),
+ "05-snapping-grid": ("Snapping targets and overlay grid", "default", snap),
+ "06-layers-folders": (
+ "Layers, folders, visibility and locking",
+ "organize",
+ organize,
+ ),
+ "10-source-and-fit": ("Source model and advanced input opt-in", "default", source),
+ "11-fit-modes": ("Centered, stretched, filled and 1:1 fitting", "fits", fits),
+ "13-file-import": ("Geometry file import and review", "import", file_import),
+ "15-reference-images": (
+ "Reference images and outline placement",
+ "reference",
+ reference,
+ ),
+ "18-cached-preview": (
+ "Cached input preview and crop guides — offline",
+ "preview",
+ preview,
+ ),
+ "19-mask-snapping": ("Snap to the visible masked picture", "mask-snap", mask_snap),
+ "02-move-resize": ("Move, resize, precise values and undo", "default", movement),
+ "07-navigation-output": (
+ "Camera navigation and output resolution",
+ "default",
+ navigation,
+ ),
+ "08-crop": ("Crop and reframe inside a fixed layer", "crop", crop),
+ "09-mask": ("Mask edges, reveal guides and reset", "mask", mask),
+ "12-clipboard-import": (
+ "Clipboard geometry import and review",
+ "default",
+ clipboard,
+ ),
+ "14-export": ("Export formats, scope and metadata", "default", export),
+ "16-appearance-language-packs": (
+ "Appearance and language-pack management",
+ "language",
+ language,
+ ),
+ "17-aquilon-simulator": (
+ "Aquilon simulator connection and review",
+ "device",
+ device,
+ ),
+}
+
+
+def gallery():
+ cards = []
+ duration = 0.0
+ for shot in sorted(OUT.glob("*/shot.json")):
+ info = json.loads(shot.read_text())
+ slug = shot.parent.name
+ if not (shot.parent / "video.mp4").is_file():
+ continue
+ duration += info["duration"]
+ cards.append(
+ f' {slug} · {info["duration"]:.1f} seconds · {html.escape(info["status"])}{html.escape(info["title"])}
Independent clips · actual application capture · silent with optional captions. Simulator footage is labelled explicitly.
' + + f"{len(cards)} clips · {duration / 60:.1f} minutes total
" + + "".join(cards) + + "" + ) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--display", default=":97") + parser.add_argument("--tools", type=Path) + parser.add_argument("--only", nargs="+", choices=SHOTS) + parser.add_argument("--list", action="store_true") + parser.add_argument( + "--inspect", + choices=SHOTS, + help="Start one seed without recording; leave it open for manual rehearsal", + ) + args = parser.parse_args() + if args.list: + for slug, (title, variant, _) in sorted(SHOTS.items()): + print(slug, ":", title, "[seed:", variant + "]") + return + OUT.mkdir(exist_ok=True) + studio = Studio(args) + studio.portals() + if args.inspect: + studio.start(args.inspect, SHOTS[args.inspect][1]) + print("Ready for rehearsal", flush=True) + try: + while True: + time.sleep(1) + except KeyboardInterrupt: + studio.close() + return + errors = [] + try: + for slug in args.only or sorted(SHOTS): + title, variant, actions = SHOTS[slug] + try: + studio.record(slug, title, variant, actions) + except Exception as error: + errors.append(f"{slug}: {error}") + print("FAILED", errors[-1], flush=True) + finally: + studio.close() + gallery() + if errors: + raise SystemExit("\n".join(errors)) + + +if __name__ == "__main__": + main()