The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
Fix proof composer template restoration and rendering (#25)
OsintMeThate20a37f27a60
diff --git a/docs/SPEC.md b/docs/SPEC.mdindex f5f4e7f..b072e6f 100644--- a/docs/SPEC.md+++ b/docs/SPEC.md@@ -157,7 +157,9 @@ scale bar + north arrow + optional graticule burned into capturesread EXIF/GPS at media import → suggest place/time.Engineering toward v2: split Satellite and Proof Composer into focused modules;-add Playwright coverage for canvas interactions that unit tests cannot exercise.+add Playwright coverage for canvas interactions that unit tests cannot exercise;+follow the [case storage and performance migration](STORAGE_AND_PERFORMANCE.md)+so large cases stay responsive on modest hardware.### v3 — investigation layerdiff --git a/docs/STORAGE_AND_PERFORMANCE.md b/docs/STORAGE_AND_PERFORMANCE.mdnew file mode 100644index 0000000..67f9c1b--- /dev/null+++ b/docs/STORAGE_AND_PERFORMANCE.md@@ -0,0 +1,535 @@+# Case storage and performance migration++This document plans the move from a monolithic `case.json` to a per-case+SQLite database. The goal is to keep every existing workflow intact while+making large cases comfortable on modest computers.++The migration changes structured case data only. Images, videos, proof PNGs,+drafts and saved Inspect sessions remain ordinary files inside the case+folder.++## Goals++- Open a case without loading its full catalog into Python or the browser.+- Keep metadata edits fast as the number of entities and links grows.+- Bound CPU and memory use during thumbnail generation and media analysis.+- Preserve the current local-first, portable case folder.+- Migrate old cases automatically without moving or rewriting their media.+- Give future EXIF, OCR, transcript, timeline, map and evidence tools one+ durable storage and job model.+- Keep unknown entity and link types readable so the ontology remains+ extensible.++## Non-goals++- Media bytes do not move into SQLite.+- Migration does not change image or video codecs.+- SQLite is not a reason to load every row and render every card at once.+- This work does not add cloud storage, telemetry or background network calls.+- The first migration does not need to implement every future entity+ attribute. It must leave room for versioned additions.++## Target case layout++```text+case.json # small manifest: name, dates, format and compatibility+case.db # entities, links, folders, catalog, jobs and events+notes.md # current case notes; later indexed for Case Notebook+media/ # imported, downloaded and derived media+proofs/ # editable proof specs and rendered PNGs+exports/ # post drafts, reports and case bundles+inspect/ # saved Inspect session specs+.thumbs/ # disposable thumbnail cache+evidence.jsonl # future portable evidence journal+```++`case.json` remains the discovery manifest. It owns the case name, creation+date and storage compatibility fields. It no longer contains the entity graph.+Keeping this small file lets the case switcher identify a case without opening+its database.++`case.db` becomes the source of truth for mutable structured state. The files+under `media/`, `proofs/`, `exports/` and `inspect/` remain the source of truth+for their content.++Media sidecars keep immutable acquisition and technical metadata that belongs+with a file. Mutable catalog fields such as title, notes and folder move to+the database. The migration imports existing values and the storage layer+becomes the only code allowed to change them.++This is a deliberate change to the current SPEC rule that limits SQLite to+rebuildable caches. `docs/SPEC.md` and `docs/ONTOLOGY.md` must be updated in the+implementation change that activates the new format.++## Ownership rules++Each value has one owner. Cached copies may exist, but they must be disposable+and carry enough information to detect when they are stale.++| Data | Owner | Notes |+|---|---|---|+| Case name and storage version | `case.json` | Small manifest, atomically replaced |+| Entities, links and folders | `case.db` | Transactional and versioned |+| Mutable titles and notes | `case.db` | Never duplicated into a writable sidecar |+| Image, video and audio bytes | Filesystem | Never stored as database blobs |+| Proof and session content | Their JSON/PNG files | Registered as artifacts in the database |+| Acquisition provenance | Media sidecar | Immutable after registration |+| Search rows | SQLite index tables | Rebuildable from owned data |+| Thumbnails | `.thumbs/` | Cache; safe to remove at any time |+| Cross-case search | Workspace index | Rebuildable from each case |+| Evidence export | `evidence.jsonl` | Produced from committed event records |++## Database shape++The first schema should stay small. New roadmap tools add migrations when they+need new indexed concepts.++### Core tables++`meta`+: Database schema version, ontology version and creation information.++`schema_migrations`+: Every applied migration, its version and completion time.++`entities`+: `id`, `type`, `label`, `attrs_json`, provenance fields and status. Unknown+ types and attributes remain valid.++`links`+: `id`, source entity, target entity, type, provenance fields and status.+ Foreign keys prevent links to missing entities. Delete policy remains in the+ existing dependency-aware service rather than in a blind SQL cascade.++`folders`+: Normalized logical paths for the analyst's organisation. These are not+ filesystem directories and are not semantic links.++`artifacts`+: Entity, safe relative path, media kind, MIME type, size, SHA-256 and source+ metadata needed by catalog queries. Paths are unique within a case.++`jobs`+: Durable local work such as thumbnails, EXIF extraction, OCR, transcription+ and video analysis. Stores state, progress, retry count and a short error.++`events`+: Committed case changes that can feed the future Evidence Locker and its+ `evidence.jsonl` export. An event identifier makes export idempotent.++### Indexes++The initial schema needs indexes for:++- entity type, status and creation time;+- link source, target and type;+- artifact path, hash and media kind;+- folder path;+- job state and requested time.++Full-text search is added over labels, notes and selected metadata. Geographic+and temporal projections should be added when the first map and timeline+queries land. Generic attributes stay in JSON until a real workflow needs an+indexed, typed field.++Use the SQLite support shipped with Python. Any reliance on FTS5, JSON or RTree+must be tested on the Windows, Linux and macOS release matrix before it becomes+part of the storage contract.++### Connection policy++- Enable foreign keys on every connection.+- Set a bounded busy timeout instead of failing immediately on a short write.+- Keep transactions short. File hashing and ffmpeg work happen outside them.+- Start with SQLite's rollback journal and `synchronous=FULL`. The app is+ single-user and portability matters more than speculative write concurrency.+- Benchmark WAL before adopting it. If WAL is ever enabled, case close and+ export must checkpoint it so a copied case is complete.+- Create live backups through SQLite's backup API. A manual folder copy is only+ guaranteed when the case is closed.+- Apply restrictive file permissions through the existing workspace helpers.++## Storage boundary before migration++The first implementation step is not SQL. Introduce one repository boundary+for every case operation:++- read case summary;+- list, get, add, update and remove entities;+- list, add and remove links;+- manage folders;+- register and update artifacts;+- resolve paths to entities;+- plan and apply dependency-aware deletion;+- enqueue and update local jobs.++The API and tools call this boundary. They no longer read or rewrite+`case.json` directly. A JSON-backed repository keeps the current behavior while+the boundary is introduced. The SQLite implementation then replaces it without+requiring every tool to change at once.++Direct storage access should fail review after this phase. Tests may inspect+fixtures and migration output, but production tools use the repository.++## Automatic migration++The conversion is one-way for normal use. A backup makes it recoverable, and+the legacy importer remains available indefinitely.++### Format versioning++Storage format and ontology version become separate concepts. The new manifest+must still carry a higher compatibility schema so an older Azimut refuses to+open it instead of treating it as an empty case.++The new application supports:++- opening and migrating legacy JSON cases;+- opening current SQLite cases;+- refusing a database created by a newer unsupported schema;+- importing a retained legacy backup for recovery.++It does not dual-write JSON and SQLite in production. Dual writes create two+authoritative copies and make crash recovery ambiguous.++### Conversion sequence++1. Acquire the existing per-case lock.+2. Read and validate the legacy `case.json`.+3. Check free disk space for the small database and its temporary copy.+4. Create a uniquely named, versioned JSON backup without overwriting an older+ backup.+5. Build `case.db.tmp` with the target schema.+6. Import entities, links, folders and artifact references in one database+ transaction.+7. Import mutable media fields from existing sidecars.+8. Validate row counts, identifiers, relative paths and link endpoints.+9. Run `foreign_key_check` and `integrity_check`.+10. Commit and close the temporary database.+11. Atomically rename the temporary database to `case.db`.+12. Atomically replace `case.json` with the new manifest.+13. Reopen the case through the normal SQLite repository and compare its+ summary with the migration report.++The manifest changes last. A crash before that point leaves the legacy case as+the active format. A complete but unreferenced temporary database can be+validated and reused or safely replaced on the next attempt.++Do not rehash every large video during migration. Import the recorded hash,+verify file existence and offer a separate integrity scan. Forced rehashing+would make the first launch unexpectedly expensive on a slow disk.++### Migration validation++The migration report records:++- entity, link and folder counts;+- artifact and sidecar counts;+- missing files and unresolved paths;+- duplicate identifiers or paths;+- links whose endpoints are missing;+- database integrity results.++Missing media is reported but does not erase its entity or provenance. Existing+dependency and tombstone rules remain in force.++If validation fails, the manifest is not changed. The user sees a short error+with the recovery location, and the legacy case remains available.++## API and frontend migration++SQLite only helps the interface when queries and rendering are bounded.++### Compatibility pass++First, keep current API responses unchanged and run them against both storage+implementations. This isolates storage regressions from UI changes.++### Bounded catalog API++Add cursor-based endpoints for entities, media and links with:++- stable ordering;+- a default and maximum page size;+- type, folder, status and date filters;+- server-side search;+- summary counts returned separately;+- direct lookup by identifier.++Cursor pagination avoids shifting pages when an import adds a new item. Offset+pagination is acceptable only for small, static lists.++Once every consumer has moved, the case-open response stops embedding the full+entity and link arrays. It returns the manifest, counts and the first data+needed by the active view.++### Bounded rendering++- Fetch the first page only when a tool becomes visible.+- Keep a small in-memory cache keyed by entity identifier.+- Load more rows as the user approaches the end of the visible list.+- Limit mounted media cards. Add simple windowing if progressive pages still+ leave too many DOM nodes.+- Preserve selection by identifier, not by list position.+- Run filters and full-text search in the backend.+- Cancel stale requests when the user changes case or query.++This work must not introduce a frontend dependency unless it has compatible+prebuilt support requirements and earns its maintenance cost. A small local+list window is preferable if it covers the current layouts.++## Thumbnail and background-job model++Thumbnails are disposable. A broken thumbnail must never block access to the+original file.++### Cache identity++A thumbnail key includes:++- original artifact identifier and SHA-256;+- requested size or variant;+- thumbnail generator version.++Changing the original file or generator therefore schedules a new result+instead of serving stale pixels.++### Job states++Use at least `queued`, `running`, `ready`, `failed` and `cancelled`. A job also+stores attempts, timestamps, progress where available and a short diagnostic.+On startup, an interrupted `running` job returns to `queued` or `failed`+according to its retry policy.++### Generation rules++- Generate visible and newly imported items first. Do not rebuild the entire+ case during open.+- Default to one CPU-heavy worker on modest hardware. A preference may allow+ more, but foreground interaction keeps priority.+- Bound ffmpeg execution time and remove partial output after failure.+- Decode images through the existing pixel clamp.+- Write to a unique temporary file, validate the result, then rename it into+ `.thumbs/` atomically.+- Store a concise error and retry with a limit. Never loop forever.+- Provide a manual regenerate action for one item or the whole cache.+- Apply a configurable cache-size budget and evict least-recently-used results.+ Eviction never touches originals or database records.++### UI failure behavior++- Use lazy image loading and asynchronous browser decoding.+- Show a type-specific placeholder while queued or after failure.+- A failed `<img>` request switches to the placeholder and reports the stale+ cache entry once. It does not retry on every render.+- Keep title, provenance and actions usable without a thumbnail.+- Expose retry without turning a technical failure into a blocking dialog.++The same durable queue later runs EXIF parsing, OCR, transcripts, perceptual+hashes and other local analysis. Each job begins only after a user action that+requires it; opening a tab does not create network work.++## Filesystem and database consistency++SQLite cannot atomically commit a filesystem rename. File-backed operations+therefore follow a recoverable sequence.++For creation:++1. Produce the file under a unique temporary name.+2. Validate and hash it.+3. Rename it to its final path.+4. Register it in a short database transaction.+5. Reconciliation removes abandoned temporary files and registers or reports+ untracked final files according to the operation journal.++For deletion, first rename the file into a case-local trash/staging directory,+then commit the database deletion, then remove it. A crash leaves a recoverable+staged file. This also follows Windows rules for open files and directory+replacement.++An inexpensive reconciliation pass checks pending operations when a case+opens. Full hashing and media probing stay behind an explicit integrity scan.++## Performance budgets++Performance work needs a repeatable fixture and a reference machine. Use a+modest profile such as four logical CPU cores, 8 GB of RAM, integrated graphics+and a SATA-class drive. Keep the exact machine and software versions in the+benchmark report.++The initial large-case fixture should contain:++- 10,000 entities;+- 20,000 links;+- 5,000 registered media items and sidecars;+- nested folders, notes, suggestions and unknown entity types;+- ready, missing, corrupt and failed thumbnails;+- proof, post and Inspect artifacts;+- missing source files and dependency tombstones.++Large binaries can be sparse fixtures or small synthetic files. Separate+benchmarks cover real image decoding and video thumbnail extraction.++Initial interaction targets on the reference machine:++| Operation | Target |+|---|---:|+| Open case and render the first useful page, cold | 2 seconds or less |+| Open case, warm filesystem cache | 750 ms or less |+| Return a warm filtered/search page | 300 ms or less |+| Update one metadata record | 200 ms or less |+| Mounted catalog rows/cards | 300 or fewer |+| Default CPU-heavy background jobs | 1 at a time |++These are starting budgets, not release claims. Record the current JSON+baseline first, calibrate the reference device, then make regressions fail CI+using stable relative thresholds. Absolute timings remain a manual release+check because shared CI hardware varies.++Also track peak backend memory, browser memory, query count, long browser tasks+and thumbnail queue depth. Memory use for the first page must not grow linearly+with the total case catalog.++## Test plan++### Characterization++Pin current behavior before changing storage:++- case creation, rename, promotion and deletion;+- entity and link CRUD;+- unknown entity and link types;+- folders and unfiled items;+- suggested and confirmed status;+- media import, download, deduplication and sidecars;+- proof, post and Inspect save/reopen;+- dependency-aware delete and tombstones;+- concurrent media registration;+- notes and provenance updates.++### Migration fixtures++Keep small legacy cases in the test suite with Unicode, unusual paths, absent+optional fields, unknown types, missing files and valid derivation chains.+Compare their public API results before and after migration.++Test failure after every conversion stage. Reopening must either finish the+migration or leave the JSON case untouched. It must never expose a half-filled+database as current.++### Database behavior++- constraints and foreign keys;+- rollback on failed writes;+- concurrent readers and short writers;+- unsupported newer schema refusal;+- sequential schema upgrades;+- backup and restore;+- corruption detection;+- cross-platform path handling and permissions.++### Frontend and load tests++- first-page rendering without a full-case fetch;+- pagination stability while imports arrive;+- selection across page loads;+- fast case switching with stale-request cancellation;+- broken and missing thumbnail fallbacks;+- bounded DOM and memory use;+- no network request merely from opening a case or tab.++Run the backend suite on Python 3.11 and the three release operating systems.+Run frontend unit tests, checks, the production build and targeted Playwright+coverage for scrolling, selection and thumbnail failure.++## Roadmap compatibility++The storage work is successful only if later tools reuse it.++| Roadmap work | Storage support |+|---|---|+| EXIF and metadata | Local jobs emit suggested place/event entities |+| OCR and transcript | Durable jobs, text artifacts and full-text index |+| Case Notebook | File-backed content with indexed text and entity references |+| Case Board / Relations | Indexed entities, typed links and reversible `same-as` |+| Map Board | Place entities plus indexed geographic projections |+| Timeline Builder | Event entities plus indexed time projections |+| Evidence Locker | Committed events exported idempotently to `evidence.jsonl` |+| Report Builder | Stable artifact identifiers and derivation links |+| Cross-case search | Rebuildable workspace index over closed case summaries |+| Search Orchestrator | Durable jobs and analyst-confirmed suggestions |+| Déjà Vu | Perceptual hashes indexed without loading media bytes |+| Channel Monitor | Bounded persistent queue with explicit network actions |++Do not pre-build all of these tables now. Add typed projections when the first+real query needs them, with a schema migration and tests. The core identifiers,+provenance and link rules must remain stable.++## Delivery sequence++### 1. Baseline and contract++- Add the large synthetic fixture and benchmark commands.+- Capture current JSON timings and memory.+- Finalize ownership and compatibility fields.+- Add characterization tests where behavior is not already pinned.++### 2. Repository boundary++- Add the storage interface and JSON implementation.+- Move all case graph and catalog access behind it.+- Keep API responses and frontend behavior unchanged.++### 3. SQLite implementation++- Add schema creation, migrations, indexes and backup helpers.+- Run the same repository contract tests against JSON and SQLite.+- Add the converter and crash/failure tests.++### 4. Safe activation++- Enable migration on case open.+- Keep the legacy importer and JSON backup.+- Update SPEC, ONTOLOGY, UI documentation and case-tree examples.+- Verify Windows, Linux, macOS and Python 3.11.++### 5. Bounded loading++- Add paginated endpoints and server-side filters.+- Change frontend stores to summary plus page caches.+- Add progressive loading, request cancellation and DOM bounds.++### 6. Job and thumbnail hardening++- Add the durable queue and one-worker default.+- Make thumbnail generation lazy, atomic and recoverable.+- Add cache budgeting, repair and visible retry states.++### 7. Release gate++- Run functional, migration, load and packaging tests.+- Test copies, backups and case bundles.+- Migrate several disposable real-world case copies.+- Record the reference-machine results.+- Ship only when the new format matches all current workflows and meets the+ agreed performance budgets.++The legacy importer is permanent. The JSON writer can be removed after the+SQLite release is stable, but opening an untouched old case must continue to+work.++## Completion criteria++The migration is complete when:++- existing cases migrate automatically with a retained backup;+- no production tool reads or writes the old graph arrays directly;+- all current workflows pass unchanged;+- older applications refuse the new format safely;+- a failed migration leaves the original case usable;+- case opening and lists use bounded queries and bounded rendering;+- thumbnail failures never block media access;+- the large-case fixture meets the reference performance budgets;+- the documented v2, v3 and v4 workflows fit the storage, job and event model;+- the full frontend and backend validation paths pass on supported platforms.diff --git a/frontend/src/lib/composer.js b/frontend/src/lib/composer.jsindex 6210444..08489ee 100644--- a/frontend/src/lib/composer.js+++ b/frontend/src/lib/composer.js@@ -737,6 +737,9 @@ export function toSpec(proof) {return {azimut_proof: 1,title: proof.title,+ // A proof keeps the selected house-style identity as well as its copied+ // style values, so reopening it can restore the template picker.+ templateId: typeof proof.templateId === 'string' ? proof.templateId : null,coords: autoCoords(proof.panels), // auto geo (first geo panel), for referencecoordsText: proof.coordsText?.trim() ? proof.coordsText.trim() : null, // null → autosource: proof.source?.trim() ? proof.source.trim() : null, // null → auto (link only)diff --git a/frontend/src/lib/composer.test.js b/frontend/src/lib/composer.test.jsindex 666363c..c6f1647 100644--- a/frontend/src/lib/composer.test.js+++ b/frontend/src/lib/composer.test.js@@ -354,6 +354,13 @@ describe('legend columns', () => {});describe('toSpec — persistence of layout', () => {+ it('persists the selected house-style ID without putting it in the style payload', () => {+ const spec = toSpec({ title: 'T', templateId: 'dark-house', panels: [], shapes: [] });+ expect(spec.templateId).toBe('dark-house');+ expect(templateFromProof({ templateId: 'dark-house', panels: [], shapes: [] }))+ .not.toHaveProperty('templateId');+ });+it('serialises the row index and caption size', () => {const proof = {title: 'T', coords: null, captionSize: 24, legendSize: 22, footerSize: 18,diff --git a/frontend/src/tools/ProofComposer.svelte b/frontend/src/tools/ProofComposer.svelteindex 68f4a8d..1f500cb 100644--- a/frontend/src/tools/ProofComposer.svelte+++ b/frontend/src/tools/ProofComposer.svelte@@ -5,14 +5,74 @@* Firefox's drag state. A click/tap or dragend is already a settled gesture.*/export function bindPanelPointerLifecycle(group, { onPress, onSelect, onDragEnd }) {- group.on('pointerdown', onPress);- group.on('click tap', onSelect);+ const isPanelTarget = (event) =>+ event?.target === group || event?.target?.name?.() === 'panel-hit';+ group.on('pointerdown', (event) => {+ if (isPanelTarget(event)) onPress(event);+ });+ group.on('click tap', (event) => {+ if (isPanelTarget(event)) onSelect(event);+ });if (onDragEnd) {- group.on('dragend', () => {- onSelect();- onDragEnd();+ group.on('dragend', (event) => {+ // Konva drag events bubble. A shape dragged inside this panel must keep+ // the shape selected and must never commit the parent panel's position.+ if (event?.target !== group) return;+ onSelect(event);+ onDragEnd(event);+ });+ }+ }++ /**+ * Coalesce document rebuilds and keep them out of an active pointer gesture.+ * Replacing Konva nodes between pointerdown and pointerup can leave Firefox+ * dispatching the rest of the gesture to a node that no longer exists.+ */+ export function createCanvasRenderGate(schedule, cancel, { rebuild, refreshUi }) {+ let pointerActive = false;+ let rebuildPending = false;+ let uiPending = false;+ let frame = null;++ function arm() {+ if (pointerActive || (!rebuildPending && !uiPending) || frame !== null) return;+ frame = schedule(() => {+ frame = null;+ if (pointerActive || (!rebuildPending && !uiPending)) return;+ const needsRebuild = rebuildPending;+ const needsUi = uiPending;+ rebuildPending = false;+ uiPending = false;+ if (needsRebuild) rebuild();+ else if (needsUi) refreshUi();});}++ return {+ beginPointer() {+ pointerActive = true;+ },+ endPointer() {+ pointerActive = false;+ arm();+ },+ requestRebuild() {+ rebuildPending = true;+ arm();+ },+ requestUi() {+ uiPending = true;+ arm();+ },+ destroy() {+ if (frame !== null) cancel(frame);+ frame = null;+ rebuildPending = false;+ uiPending = false;+ pointerActive = false;+ },+ };}</script>@@ -66,6 +126,7 @@// not per element); `shapes` are the drawn geometry bound to a panel.const proof = $state({title: DEFAULT_PROOF_TITLE, panels: [], shapes: [], notes: {}, legendOrder: [],+ templateId: null, // selected saved house style; its values remain copied belowcoordsText: '', source: '', // '' → auto-derived from panels; non-empty → manual overridecaptionSize: CAPTION_SIZE, legendSize: LEGEND_SIZE, footerSize: FOOTER_SIZE, footer: '',footerEnabled: true, // false → no footer line at all@@ -215,6 +276,7 @@color = proof.palette[0];proof.notes = spec.notes ?? {};proof.legendOrder = spec.legendOrder ?? [];+ proof.templateId = typeof spec.templateId === 'string' ? spec.templateId : null;proof.panels = spec.panels.map((p) => ({ ...p, img: imgCache.get(p.src) ?? null }));proof.shapes = spec.shapes ?? [];// a panel image missing from the cache (shouldn't happen) reloads async@@ -229,7 +291,10 @@selectedId = null;selectedPanelId = null;selectedSig = null;- appliedTemplate = null;+ const template = templatesState.proof.find((t) => t.id === proof.templateId);+ appliedTemplate = template+ ? { id: template.id, name: template.name, prevStyle: templateFromProof(proof) }+ : null;dirty = true;requestAnimationFrame(fit);// outlast the capture debounce so the restore itself is not re-recorded@@ -251,6 +316,7 @@// ---- konva ------------------------------------------------------------------let containerEl;let stage, docLayer, uiLayer, transformer, endHandles, guideGroup, panelCtrls;+ let canvasRenderGate;let drawing = null; // {panel, node, start, box, kind}let pathDraft = null; // {panel, box, node, points:[]} — multi-click curve in progresslet spacePan = false; // hold-space panning (manual, so it wins over shape drags)@@ -260,6 +326,14 @@onMount(() => {loadSignature(); // async: the canvas redraws when it landsstage = new Konva.Stage({ container: containerEl, width: 100, height: 100 });+ canvasRenderGate = createCanvasRenderGate(+ requestAnimationFrame,+ cancelAnimationFrame,+ {+ rebuild: () => { if (stage) rebuild(); },+ refreshUi: () => { if (stage) refreshCanvasUi(); },+ },+ );docLayer = new Konva.Layer();uiLayer = new Konva.Layer();stage.add(docLayer, uiLayer);@@ -295,9 +369,27 @@stage.on('pointerup', onPointerUp);stage.on('dblclick dbltap', () => { if (pathDraft) finishPath(true); });+ // The release can happen outside the canvas. Capture it at window level so+ // a deferred rebuild is never left waiting after an interrupted drag.+ const beginPointer = () => canvasRenderGate?.beginPointer();+ const settlePointer = () => canvasRenderGate?.endPointer();+ // Capture before Konva dispatches the event: selected annotations stop+ // bubbling at their node, so a Stage listener alone cannot see every press.+ containerEl.addEventListener('pointerdown', beginPointer, true);+ window.addEventListener('pointerup', settlePointer, true);+ window.addEventListener('pointercancel', settlePointer, true);+ window.addEventListener('blur', settlePointer);+return () => {resize.disconnect();+ containerEl.removeEventListener('pointerdown', beginPointer, true);+ window.removeEventListener('pointerup', settlePointer, true);+ window.removeEventListener('pointercancel', settlePointer, true);+ window.removeEventListener('blur', settlePointer);+ canvasRenderGate?.destroy();stage.destroy();+ canvasRenderGate = null;+ stage = null;};});@@ -333,7 +425,8 @@if (tool !== 'curve' && pathDraft) finishPath(false);});- // rebuild canvas whenever the document changes+ // Rebuild only when published document content changes. Selection is UI-only+ // and gets a lightweight refresh below, without recreating every image node.$effect(() => {JSON.stringify([proof.panels.map((p) => [p.src, p.caption, p.row, p.scale, p.x, p.y]),@@ -348,14 +441,19 @@proof.panelDirection,proof.signature,proof.signatureText,- selectedId,- selectedPanelId,- selectedSig,- guide,]);sigImg; // the logo lands async — redraw once it doesprefs.signatureHandle; // Settings can change the rendered handle live- if (stage) rebuild();+ if (stage) canvasRenderGate?.requestRebuild();+ });++ $effect(() => {+ selectedId;+ selectedPanelId;+ selectedSig;+ guide;+ tool;+ if (stage) canvasRenderGate?.requestUi();});// Text-size options threaded into every layout/size computation.@@ -377,6 +475,7 @@proof.shapes = [];proof.notes = {};proof.legendOrder = [];+ proof.templateId = null;proof.coordsText = '';proof.source = '';proof.captionSize = CAPTION_SIZE;@@ -429,6 +528,7 @@handle: !!prefs.signatureHandle?.trim(),});color = proof.palette[0] ?? ANNO_COLORS[0];+ proof.templateId = t.id;appliedTemplate = { id: t.id, name: t.name, prevStyle };dirty = true;requestAnimationFrame(fit); // margins/layout may have changed the doc size@@ -449,6 +549,7 @@handle: !!prefs.signatureHandle?.trim(),});color = proof.palette[0] ?? ANNO_COLORS[0];+ proof.templateId = null;appliedTemplate = null;dirty = true;requestAnimationFrame(fit);@@ -1041,7 +1142,7 @@// on top for hit-testing.group.add(new Konva.Rect({x: 0, y: 0, width: panel.natural[0], height: panel.natural[1],- fill: 'transparent', listening: true,+ fill: 'transparent', listening: true, name: 'panel-hit',}));bindPanelPointerLifecycle(group, {// Only the select tool touches panels. Selection itself waits until the@@ -1210,7 +1311,18 @@docLayer.add(node);}- // selection — keyed on the shape's kind, not the Konva node's class name,+ docLayer.batchDraw();+ refreshCanvasUi(boxes, width, height);+ }++ function refreshCanvasUi(boxes = null, width = null, height = null) {+ boxes ??= boxesOf();+ if (width === null || height === null) {+ const measured = measureDoc();+ width = measured.width;+ height = measured.height;+ }+ // Selection is keyed on the shape's kind, not the Konva node's class name,// since a framed/backgrounded text renders as a Group rather than a Text.// A whole panel can be selected instead (both modes): corner anchors only// (aspect locked, elements scale along), never rotated. In grid mode the@@ -1250,7 +1362,6 @@drawEndHandles(boxes);drawPanelMoveControls(boxes);drawGuide(width, height);- docLayer.batchDraw();uiLayer.batchDraw();}@@ -1930,6 +2041,13 @@// legend text lives in `notes` (per color); migrate old per-shape commentsproof.notes = spec.notes ?? notesFromShapes(proof.shapes);proof.legendOrder = spec.legendOrder ?? [];+ proof.templateId = typeof spec.templateId === 'string' ? spec.templateId : null;+ const template = templatesState.proof.find((t) => t.id === proof.templateId);+ if (template) {+ // The style is already part of the saved proof. Restore only the picker+ // association, not the template's current values.+ appliedTemplate = { id: template.id, name: template.name, prevStyle: templateFromProof(proof) };+ }openList = null;dirty = false;anchorHistory();diff --git a/frontend/src/tools/ProofComposer.test.js b/frontend/src/tools/ProofComposer.test.jsindex 8526d6b..f178512 100644--- a/frontend/src/tools/ProofComposer.test.js+++ b/frontend/src/tools/ProofComposer.test.js@@ -3,7 +3,10 @@ import { render } from 'svelte/server';vi.mock('konva', () => ({ default: {} }));-import ProofComposer, { bindPanelPointerLifecycle } from './ProofComposer.svelte';+import ProofComposer, {+ bindPanelPointerLifecycle,+ createCanvasRenderGate,+} from './ProofComposer.svelte';describe('Proof Composer empty state', () => {it('hides proof-specific chrome until a proof is started', () => {@@ -22,24 +25,24 @@ describe('Proof Composer empty state', () => {describe('Proof Composer panel pointer lifecycle', () => {function fakeGroup() {const handlers = new Map();- return {- handlers,- group: { on: vi.fn((events, handler) => handlers.set(events, handler)) },- };+ const group = { on: vi.fn((events, handler) => handlers.set(events, handler)) };+ return { handlers, group };}+ const panelHit = () => ({ target: { name: () => 'panel-hit' } });+it('does not select and rebuild the panel during pointerdown', () => {const { group, handlers } = fakeGroup();const onPress = vi.fn();const onSelect = vi.fn();bindPanelPointerLifecycle(group, { onPress, onSelect, onDragEnd: null });- handlers.get('pointerdown')();+ handlers.get('pointerdown')(panelHit());expect(onPress).toHaveBeenCalledOnce();expect(onSelect).not.toHaveBeenCalled();- handlers.get('click tap')();+ handlers.get('click tap')(panelHit());expect(onSelect).toHaveBeenCalledOnce();});@@ -52,8 +55,120 @@ describe('Proof Composer panel pointer lifecycle', () => {onSelect: () => calls.push('select'),onDragEnd: () => calls.push('commit'),});- handlers.get('dragend')();+ handlers.get('dragend')({ target: group });expect(calls).toEqual(['select', 'commit']);});++ it('ignores click and drag events bubbled from an annotation', () => {+ const { group, handlers } = fakeGroup();+ const onPress = vi.fn();+ const onSelect = vi.fn();+ const onDragEnd = vi.fn();+ const annotation = { name: () => '' };++ bindPanelPointerLifecycle(group, { onPress, onSelect, onDragEnd });+ handlers.get('pointerdown')({ target: annotation });+ handlers.get('click tap')({ target: annotation });+ handlers.get('dragend')({ target: annotation });++ expect(onPress).not.toHaveBeenCalled();+ expect(onSelect).not.toHaveBeenCalled();+ expect(onDragEnd).not.toHaveBeenCalled();+ });+});++describe('Proof Composer canvas render gate', () => {+ function setup() {+ const callbacks = new Map();+ let nextId = 1;+ const schedule = vi.fn((callback) => {+ const id = nextId++;+ callbacks.set(id, callback);+ return id;+ });+ const cancel = vi.fn((id) => callbacks.delete(id));+ const rebuild = vi.fn();+ const refreshUi = vi.fn();+ const gate = createCanvasRenderGate(schedule, cancel, { rebuild, refreshUi });+ const runFrame = () => {+ const [id, callback] = callbacks.entries().next().value ?? [];+ if (!callback) return;+ callbacks.delete(id);+ callback();+ };+ return { gate, schedule, cancel, rebuild, refreshUi, callbacks, runFrame };+ }++ it('defers a reactive rebuild until the pointer gesture has ended', () => {+ const { gate, schedule, rebuild, runFrame } = setup();++ gate.beginPointer();+ gate.requestRebuild();++ expect(schedule).not.toHaveBeenCalled();+ expect(rebuild).not.toHaveBeenCalled();++ gate.endPointer();+ expect(schedule).toHaveBeenCalledOnce();+ runFrame();+ expect(rebuild).toHaveBeenCalledOnce();+ });++ it('coalesces repeated state changes into one rebuild', () => {+ const { gate, schedule, rebuild, runFrame } = setup();++ gate.requestRebuild();+ gate.requestRebuild();+ gate.requestRebuild();++ expect(schedule).toHaveBeenCalledOnce();+ runFrame();+ expect(rebuild).toHaveBeenCalledOnce();+ });++ it('does not rebuild when a new pointer starts before the frame runs', () => {+ const { gate, rebuild, runFrame } = setup();++ gate.requestRebuild();+ gate.beginPointer();+ runFrame();+ expect(rebuild).not.toHaveBeenCalled();++ gate.endPointer();+ runFrame();+ expect(rebuild).toHaveBeenCalledOnce();+ });++ it('refreshes selection UI without rebuilding the document', () => {+ const { gate, rebuild, refreshUi, runFrame } = setup();++ gate.requestUi();+ runFrame();++ expect(refreshUi).toHaveBeenCalledOnce();+ expect(rebuild).not.toHaveBeenCalled();+ });++ it('lets a document rebuild absorb a queued selection refresh', () => {+ const { gate, rebuild, refreshUi, runFrame } = setup();++ gate.requestUi();+ gate.requestRebuild();+ runFrame();++ expect(rebuild).toHaveBeenCalledOnce();+ expect(refreshUi).not.toHaveBeenCalled();+ });++ it('cancels a queued rebuild when the canvas is destroyed', () => {+ const { gate, cancel, rebuild, runFrame } = setup();++ gate.requestRebuild();+ gate.destroy();++ expect(cancel).toHaveBeenCalledOnce();+ runFrame();+ expect(rebuild).not.toHaveBeenCalled();+ });});diff --git a/tests/test_proofs_api.py b/tests/test_proofs_api.pyindex bb6e099..629ccb5 100644--- a/tests/test_proofs_api.py+++ b/tests/test_proofs_api.py@@ -13,6 +13,7 @@ def _png_b64() -> str:SPEC = {+ "templateId": "dark-house","captionSize": 24,"legendSize": 22,"footerSize": 18,@@ -56,6 +57,7 @@ def test_save_load_roundtrip(client):assert spec["legendSize"] == 22assert spec["footerSize"] == 18assert spec["footer"] == "Custom footer line"+ assert spec["templateId"] == "dark-house"# PNG servedassert client.get(f"/files/{cid}/{saved['png']}").status_code == 200