odysseus/plans/photo-editor-interaction-audit.md

# Editor interaction audit

Date: 2026-09-16
Scope: make existing editing operations predictable and familiar. No additional tools.
Evidence: code inspection plus a focused browser regression for rasterization.
This is not a claim that every workflow has been manually verified.

## Implementation progress

The full audit remains open. Changes made on 2026-09-16:

- Removed destructive single-letter lasso shortcuts and made command dispatch
  return after handling undo, duplicate, save, transform and related actions.
- Native fields and contenteditable targets now own keyboard editing. Keyboard
  and paste bindings are replaced on editor rebuild rather than accumulating.
- M selects Marquee, S selects Clone, Ctrl/Cmd+D deselects, Ctrl/Cmd+A selects
  all, and Ctrl/Cmd+J copies the selection when one exists. Legacy deselect and
  select-all chords remain aliases. Tool keys now have a shared map.
- Shift+Alt chooses intersection consistently for marquee, lasso and wand.
- Cut no longer creates an extra visible layer. Lasso copy retains selection
  and returns immediately rather than also copying the whole layer.
- Pixel fill, selection erase, destructive blur and edge processing now await
  the rasterization confirmation. Edge cancellation no longer reports success.
- Quick Mask painting bypasses the parent-layer rasterization prompt.

Verified so far: 16 focused Python/JS tests passed; browser checks have verified
field focus, selection copy, shortcut mappings, intersection and editor reopening.
The browser suite stubs the unrelated notification-log endpoint because that
endpoint returns 401 without an account and triggers page navigation on the
isolated test server. Editor operations use the real application.

Still required: full dialog/shortcut ownership, active mask consistency across
fill/erase/filter, target visibility/lock feedback, gesture transitions, stable
controls, broader cross-browser/mobile tests, and the 4K/20-edit recovery gate.

Second implementation pass:

- Added a shared pixel-target resolver for selection erase, fill and destructive
  blur: selected layer/group masks are edited directly, including local offsets.
  Parent pixel/transparency locks no longer incorrectly block mask operations;
  owner/group locks still apply.
- Restored the existing Fill command in the Image menu; it had a handler but
  no menu entry. With no selection it fills the selected surface.
- Legacy lasso erase now uses the same document-space selection-delete path.
- Tool switching ends an active brush stroke before changing its tool identity.
  Desktop reselect keeps controls open; the mobile sheet toggle is preserved.
- Chromium verified offset-mask fill/delete preserve parent pixels. Firefox
  verified rasterize/cancel/undo, focus ownership, selection-copy pixels, cut,
  intersection, reopening and mask editing. The focused Python/JS suite now
  passes 20 tests. Firefox also passed the held-brush tool-switch test: one
  history entry, no lingering stroke, undo restores pixels, controls stay open.

Still open: copy/clipboard and edge-filter mask targeting, visibility feedback,
full dialog precedence, layer-switch/focus-loss gesture lifecycle, mobile panel
stability, and the 4K/20-edit recovery gate. These are not covered by the focused
passing tests above.

## 1. Command and keyboard ownership (highest priority)

Third implementation pass:

- Copy/cut and duplicate-selection share selected-surface extraction. Selected
  masks copy their own pixels, not their parent's image. Internal paste retains
  the source document offset and selects Move through the normal toolbar path.
- Canvas window handlers are replaced on editor rebuild. Focus loss releases
  drawing/pan gestures and temporary Space-pan state, preventing a returning
  pointer from extending a stale stroke.
- Verified seven interaction workflows in Chromium and eight in Firefox
  (including rasterize confirmation), plus 20 focused Python/JS tests. The
  offset-mask case verifies white mask pixels, the preserved paste offset and
  undo. The focus-loss case verifies one undo entry and no continued painting.
- Still open: full dialog precedence, layer-switch gesture lifecycle, edge-filter
  mask targeting, visibility feedback, stale asynchronous previews, mobile panel
  stability, and the 4K/20-edit persistence and export verification.

The findings below describe the initial audit; progress above records resolved
parts without removing the remaining acceptance criteria.

Fourth implementation pass:

- Filter dialogs own keyboard input ahead of the editor and surrounding app.
  Escape cancels, Enter applies (or activates focused Cancel), and Tab stays in
  the dialog. Destructive blur cancellation no longer pops unrelated history
  or clears redo: the history snapshot is taken only on acceptance.
- Filter prompts reject a changed document/target and cancel on editor close
  or reopen. Preview rollback on close is synchronous. Broader asynchronous
  preview/persistence interaction still requires verification.
- Layer thumbnails refresh after settled composites without rebuilding the
  panel. Changed layer rows briefly flash using the theme highlight; unchanged
  rows do not. Preview signatures reset between editor documents.
- Chromium: nine interaction workflows passed, including pixel-verified
  thumbnail refresh, the edited-row flash, and filter Escape/redo preservation.
- Clarified toolbar feedback: the top bar must stay on one row. Removed the
  forced second row; narrow windows scroll horizontally. Dropdown popovers
  escape that scroll clip without moving their DOM/event ownership. Chromium
  verifies one-row alignment and menu actions at 1280, 900, 600 and 390px.

`static/js/editor/keyboard-shortcuts.js` handles Space, arrow keys, transforms,
undo and clipboard before its general typing-target guard. Several commands can
therefore reach editor state while a field or text editor owns focus. Lasso
shortcuts run after tool switching: C can select Crop and copy a selection;
D can select Burn and delete selected pixels. These need one dispatch decision.
`galleryEditor.js` additionally handles Escape at window capture, document
capture and through a gallery callback. The rasterize browser test exposed
Escape escaping the new confirmation and discarding the editor state.

Work: define precedence as dialog, text/field editing, active gesture, canvas
command, surrounding application. Consume each command once. Keep native text
undo/cut/copy while typing. Centralize command labels and shortcut hints.

Shortcut mismatches in `editor/build/toolbar.js`: M selects Inpaint, R selects
Marquee, S selects AI Sharpen, K selects Clone, and D selects Burn. The existing
Deselect chord is Ctrl/Cmd+Shift+D. Adobe documents M for Marquee, S for Clone
and Ctrl/Cmd+D for Deselect. Browser-reserved chords such as Ctrl+T require an
explicit browser-compatible alternative, with matching UI hints.

Reference: https://helpx.adobe.com/photoshop/web/get-set-up/preferences-and-settings/keyboard-shortcuts.html

Acceptance: keyboard-only text editing, dialog cancellation, selection editing
and tool changes never invoke two commands or change an unrelated layer.

## 2. Layer target and rasterization

Before this patch, `_beginDraw` and paint handlers displayed rasterize toasts;
the actual conversion controls lived elsewhere. Text, shape and placed layers
had different paths. The new confirmation supports selecting/reselecting a
pixel tool or trying it on canvas, Enter, Cancel, and undo. Mask targets bypass
conversion. Do not replay a pointer stroke after a modal closes.

Remaining work: use the same permission/target decision for fill, selection
erase and destructive filters (`_canMutateLayerPixels` still only toasts).
Distinguish locked pixels, locked transparency, hidden layers and adjustment
layers with a concrete reason and relevant action. Make the active pixel/mask/
group target unmistakable in the layer panel and controls.

Acceptance: brush, erase, fill and filters agree on the active target; cancellation
changes nothing; undo restores retained text/shape/placed content.

## 3. Selection behavior

Selection state still crosses `wandMask`, lasso points and selection-space
conversion. Marquee already supports add/subtract and moving a boundary, so
preserve that implementation and reconcile other entry points with it.

Work: one consistent replace/add/subtract/intersect contract, clear distinction
between moving a boundary and moving selected pixels, consistent copy/cut/fill/
delete on offset layers and masks. Remove legacy single-letter destructive
lasso commands that collide with tools. Audit Ctrl/Cmd+J with an active selection:
the current dispatch always calls duplicateActiveLayer before selection handling.

Acceptance: the same selected region produces the same edited pixels across
marquee, lasso and wand, including zoomed and offset layers; undo restores both.

## 4. Gesture completion and tool switching

`onSelectTool` cancels crop, marquee and gradient work but commits transform
and text work. Reselecting a tool toggles its controls sheet. These policies are
distributed rather than expressed as one transition contract.

Work: specify commit/cancel for each pending operation, Enter/Escape, switching
tools, switching layers, losing focus and pointer cancellation. Keep temporary
pan distinct from changing tools. Preserve the existing direct-manipulation
and transform geometry modules; consolidate their lifecycle callers.

Acceptance: one drag produces one undo step; Escape restores the pre-drag
result; a released pointer outside the canvas cannot leave an operation active.

## 5. Contextual controls and visual feedback

`onSelectTool` individually shows/hides many control sections. Layer-type
controls, effects popups and mobile sheets need a consistent target and focus
contract. Keep the canvas position stable when these surfaces open.

Work: align control placement, selected states, disabled reasons, cursor/brush
preview and focus restoration. Preserve settings for each existing tool where
appropriate. Review repeated-tool clicks on desktop versus mobile, where they
currently also dismiss the controls sheet.

Acceptance: selecting a tool exposes its relevant controls without moving the
artwork; opening and dismissing a popup returns to the same target and viewport.

## 6. Responsiveness, undo and recovery

There are already worker rendering, history budget, persistence and cancellation
modules. Assess their observable behavior before proposing a replacement.

Work: measure stroke latency, preview latency and history cost on a 4K document
with multiple layers. Exercise 20 mixed operations, repeated undo/redo, save,
reopen and export. Check stale asynchronous previews after switching layers or
closing the document. Saved status must correspond to completed persistence.

Acceptance: no lost edits, stale previews or export/reopen differences in the
tested workflow. Record timings and browser/device rather than an arbitrary
percentage of Photoshop parity.

## Delivery order

1. Rasterization confirmation and focused regression (this change).
2. Command ownership and conflicting shortcuts.
3. Selection and active-target consistency.
4. Gesture commit/cancel and history consistency.
5. Controls, cursor feedback and stable panels.
6. Cross-browser desktop/mobile workflow and performance verification.

Existing browser tests under `tests/e2e/photo-editor/` cover useful building
blocks. Extend them with real sequences across tools; avoid testing each tool
only in isolation. Full Photoshop parity, new filters and new file formats are
outside this audit's scope.