odysseus/plans/photo-editor-remaining-scope.md

# Photo Editor Remaining Scope

Date: 2026-08-29

## Current verdict

Odysseus is now a credible layered everyday editor, not an editor mockup. The
first nine roadmap phases are implemented: professional transform geometry,
shared direct-manipulation sessions, retained placed content, unified
selections and masks, a reusable brush/retouch engine, and retained text and
shape layers.

Phase 10 is functionally advanced but not closed. First-class adjustment layers
now support Levels, Curves, Exposure, White Balance, Brightness/Contrast,
Hue/Saturation/Lightness, Color Balance, Selective Color, and Gradient Map.
They participate in clipping, groups, masks, visibility, opacity, history, the
v14 document format, and flattening. Retained effects have since been added as
a separate ordered stack with Gaussian Blur, Color Overlay, Drop Shadow, and
Stroke, including editable colors, visibility, opacity, reorder, rasterize,
history, persistence, and migration.

Practical readiness estimate:

- Everyday layered photo editing: **about 88%**
- Dependable professional v1 described by the roadmap: **about 62%**
- Broad Photoshop/Photopea feature parity: **about 50%**

The remaining gap is dominated by large-document rendering outside the live
composite path, workspace consolidation, interchange/color policy, and release
proof rather than basic canvas tools.

## Verification snapshot

- The focused editor unit suite currently passes **31 tests** in Docker.
- The full photo-editor browser suite currently has **41 passing workflows**;
  the nested-group selection workflow initially exposed a row-hit regression,
  which now passes on isolated rerun after the slider-selection fix. The new
  group-effects workflow also passes.
- The new adjustment tests exercise deterministic pixel math, nested parameter
  normalization, retained metadata, undo/redo, clipping, masks, and draft
  reopen.
- The latest editor changes have not yet been rebuilt into the live `7011`
  container.

## Close Phase 10

This is the immediate release slice.

1. Finish the bounded preview path for large documents. Downsampled previews
   now keep control movement responsive and full resolution is restored for
   commit/export. Live worker composites now use generation checks, latest-only
   coalescing, and close/reopen invalidation; extend the same guarantees to
   remaining preview paths.
2. Add flattened-export versus reopened-project pixel comparisons for every
   adjustment family, including groups, clipping, masks, blend mode, and
   partial opacity.
3. Validate the color algorithms visually. White Balance and Selective Color
   are currently deterministic approximations, not color-managed photographic
   transforms.
4. Test every adjustment popup on phone and desktop viewports, including tall
   popups, color inputs, drag, Reset, Apply, Cancel, and Escape.
5. Decide the migration path for the older per-raster `adjLayers` stack. It can
   remain readable for compatibility, but new UI should converge on first-class
   adjustment layers instead of maintaining two competing concepts.
6. Bump static cache versions, rebuild the live container, and run a short
   visual smoke test on `7011`.

## Phase 11: Retained effects and filters

The retained-effects slice is implemented for raster/placed/text/shape-compatible
layer output: Gaussian Blur, Sharpen, Color Overlay, Drop Shadow, and Stroke
have editable colors/parameters, visibility, opacity, reorder, rasterize,
history, migration, and reopen support. Effect-specific masks, presets, and
group-level effects are also implemented and covered by focused browser tests.
Remaining work is:

1. Extend worker coverage to serialization and remaining preview paths.
   Thumbnail encoding, retained-effect rasterization, and live composite
   rendering now use a worker where OffscreenCanvas is available, with
   synchronous compatibility fallbacks. Generation invalidation, latest-only
   coalescing, and CPU loop cancellation protect live rendering.
2. Add explicit group-effect blend/ordering tests for nested groups and
   non-default blend modes, plus visual comparisons for effect stacks.

Introduce the renderer/worker cancellation boundary here rather than adding
more synchronous full-canvas filters that Phase 14 must immediately replace.

## Phase 12: Professional workspace

Consolidate fragmented popups into one contextual properties surface. Persist
panel layout by device class, add command search, expose stable document status,
and support multiple open documents with independent history, zoom, pan, and
selection. Mobile should use canvas-first sheets rather than compressed desktop
panels.

## Phase 13: Interchange and export

Harden orientation, transparency, metadata, and color behavior for PNG, JPEG,
and WebP first. Add copy/paste and drag/drop through placed layers. Treat
layered formats as explicit compatibility projects: unsupported PSD/TIFF/HEIC
features must be reported, never silently discarded. Odysseus project files
remain the lossless source of truth.

## Phase 14: Performance and recovery

Move remaining preview/pixel paths into workers. Thumbnail encoding,
autosave serialization, adjustment rendering, and retained-effect rendering
now have worker-backed paths with compatibility fallbacks. Add
dirty-region compositing, reusable render surfaces, cancellation tokens,
operation telemetry, a documented surface/history budget, autosave generations,
and a checked-in 4K multi-layer benchmark.

This phase is the main architectural risk. Canvas 2D remains a valid
compatibility renderer, but full-document synchronous passes will not scale to
professional documents.

## Phase 15: Assisted editing

Normalize generation, editing, inpainting, segmentation, restoration, and
upscaling behind capability-based endpoints. Keep model/provider names out of
editor logic. Requests must exclude chat memory, show progress, cancel safely,
and return named reversible layers with provenance. Manual tools remain fully
usable without an endpoint.

Much of the endpoint plumbing already exists; the remaining work is consistent
capability discovery, lifecycle safety, and editor-native result handling.

## Phase 16: Release gate

Run complete user journeys on Chromium and Firefox desktop plus representative
phone/tablet viewports. Add keyboard-only and accessibility coverage, mixed
20-edit persistence/export tests, failure recovery, and large-document stress
tests. No supported operation may silently flatten or discard retained state.

## Architecture debt to control

- `galleryEditor.js` is still a large orchestrator. Continue extracting domain
  modules as visible features move, without a broad rewrite.
- Legacy raster adjustment sublayers and first-class adjustment layers overlap.
  Converge on the first-class model.
- Pixel effects still rely heavily on synchronous full-canvas work.
- `static/style.css` carries substantial editor-specific surface area and needs
  clearer component boundaries before workspace customization expands.
- The repository worktree contains many unrelated changes. Editor release and
  merge decisions require a scoped diff or clean integration branch.

## Recommended execution order

1. Close and deploy Phase 10.
2. Build Phase 11 through a cancellable render boundary.
3. Consolidate the workspace in Phase 12.
4. Define color/metadata policy and complete Phase 13.
5. Finish worker rendering, stress, and recovery in Phase 14.
6. Normalize assisted editing in Phase 15.
7. Run the cross-browser professional release gate in Phase 16.

Do not expand into full PSD fidelity, CMYK production, RAW development, 3D, or
complete Photoshop parity before this critical path passes. Those are separate
product decisions, not prerequisites for a strong Odysseus editor.