Make Markover UI development live and share element callouts

[lastobelus]

Problem

The current development watcher performs a complete build, quits Electron, and launches a replacement application after every successful edit. That destroys the working window geometry and turns UI tuning into a stop-start QA loop. Developers and agents also have no shared, low-friction way to point at the same rendered element without exchanging annotated screenshots.

Accepted interaction

• UI-facing changes reload inside the existing Electron process and existing BrowserWindow. The window does not close, reopen, resize, move, activate, or lose its configured geometry.
• Main-process or backend changes report that a restart is required; the watcher never silently tears down the application.
• A failed build leaves the last working renderer and window untouched.
• A user holds one development-only modifier gesture and clicks an element. Markover outlines and pins that element and copies one stable element reference.
• An agent can use the same reference with a development CLI command to show the elements bounding box in the running Markover window.
• The workflow requires no screenshots, drawing, DevTools inspection, or remote arbitrary JavaScript execution.

Delivery stack

1. Stable renderer live reload, based on main: classify watcher inputs, build UI assets separately, publish them atomically, and reload the existing web contents without replacing the BrowserWindow. Main-process changes stop at an explicit restart-required diagnostic.
2. Shared element callouts, based on slice 1: add the development-only picker, stable element-reference contract, authenticated CLI highlight command, renderer overlay, and focused tests.

The second PR depends on the first because it reuses the persistent development control path. The active UI-tuning PR #195 remains separate; this issue does not take ownership of its visual changes.

Complete when

• repeated CSS, HTML, and renderer edits become visible without changing the Electron PID or BrowserWindow bounds;
• UI-facing preload changes use the same stable-window path when Electron can safely reload them;
• failed UI builds leave the displayed renderer unchanged and the next valid edit recovers;
• main-process and backend inputs produce one clear restart-required state without automatic shutdown;
• user selection is one modifier-click gesture that visibly pins the chosen box and copies a stable reference;
• the development CLI can highlight or clear that exact reference in the addressed running instance;
• ambiguous or stale references fail clearly without highlighting the wrong element;
• production and non-watch runtimes expose no picker or highlight route;
• focused deterministic tests and the full local gate pass for each slice;
• native QA confirms stable bounds and the two-way callout flow in one running development instance.

Excludes

• hot-swapping Electron main-process or backend modules;
• preserving arbitrary unsaved in-memory renderer state beyond existing workspace and autosave contracts;
• a general browser automation server, arbitrary renderer script execution, remote-debugging port, or production inspector;
• visual changes owned by PR Improve Markover review UI #195;
• compatibility behavior for the current pre-MVP restart watcher.

[lastobelus]

Work intent

phase: completed
summary: "Slice 1: keep one Electron process and BrowserWindow while UI-facing source changes rebuild and reload"
touch-points:
  - "scripts/development-watch.ts and its bootstrap/input classification"
  - "a focused atomic development renderer build path"
  - "src/development-control.ts and src/main.ts reload coordination"
  - "development watcher, internal protocol, and native smoke tests"
  - "docs/developer/development.md"
done-when:
  - "CSS, HTML, renderer, and safely reloadable preload edits become visible without changing the Electron PID or BrowserWindow bounds"
  - "failed UI builds leave the displayed renderer untouched and a later valid edit recovers"
  - "main-process and backend changes print restart required and never automatically close the app"
  - "watcher shutdown still performs one managed durable quit"
  - "focused deterministic tests and npm run ci:local pass"
  - "native QA confirms repeated live reload preserves size, position, visibility, and focus"
excludes:
  - "Slice 2 element picker, locator contract, CLI highlight command, and overlay"
  - "hot-swapping Electron main-process or backend modules"
  - "arbitrary unsaved renderer memory beyond existing persistence contracts"
  - "visual changes owned by PR #195"
  - "compatibility behavior for the pre-MVP restart watcher"
blocked-by: []
may-block:
  - "Slice 2 shared element callouts"
branch: "t3code/stable-ui-dev-workflow"

[lastobelus]

Slice 1 checkpoint is now draft PR #197 at head ff7ca404 and remains in the implementing/native-QA phase. Automated validation is complete except for one unrelated order-sensitive full-suite flake documented in the PR; focused coverage and smoke pass. Slice 2 will branch from #197 after the native same-window QA gate.

[lastobelus]

Slice 1 native QA passed on PR #197 at head 3706aa78. A successful CSS reload, deliberate renderer compile failure, recovery reload, and cleanup all retained PID 33981, native window 14598, bounds 1180x760 @ (145,34), and the foreground app. QA also exposed and fixed initial-build recovery: after a cold build failure, the next valid edit now retries full startup instead of trying to reload a missing process.

[lastobelus]

Work intent

phase: completed
summary: "Slice 2: one-gesture user element picker and authenticated agent highlight command"
touch-points:
  - "development-only element reference and selector contract"
  - "renderer picker gesture, pinned bounding-box overlay, and clipboard handoff"
  - "authenticated local-service development highlight and clear routes"
  - "Markover CLI highlight and clear commands"
  - "focused IPC, service, renderer, and CLI tests"
done-when:
  - "one modifier-click pins an element and copies one stable reference"
  - "the addressed development CLI highlights or clears that reference"
  - "ambiguous and stale references fail without highlighting another element"
  - "production and non-watch runtimes expose neither picker nor highlight route"
  - "focused deterministic tests and the full local gate pass"
  - "native QA proves the two-way callout flow in one running development instance"
excludes:
  - "general browser automation or arbitrary renderer JavaScript execution"
  - "production inspection surfaces"
  - "visual changes owned by PR #195"
  - "compatibility behavior for unreleased prototype references"
blocked-by:
  - "PR #197"
may-block: []
branch: "t3code/ui-element-callouts"

[lastobelus]

Slice 2 is now draft PR #198, stacked on #197, at head 36e30940. Automated validation is green: full local gate 837/837 plus smoke, focused element/service/IPC/CLI/layout coverage 90/90. Native Option-click and CLI highlight/clear QA is next.

[lastobelus]

Slice 2 native QA passed on the running PR 198 development instance.

• One Option-click on Open Markdown copied the mko-ui-v1: reference anchored to empty-open-button.
• The CLI resolved it to {x:527, y:475, width:126, height:36}; the visible pink button#empty-open-button box enclosed that exact button.
• element clear removed the box.
• A valid reference with a missing anchor failed as stale and left no box.

Automated validation remains green: npm run ci:local passed 837/837 tests plus smoke, and the focused callout suite passed 90/90. PR #198 remains draft and stacked on #197.