Squash Odysseus development history

This commit is contained in:
pewdiepie-archdaemon
2026-09-11 06:04:19 +00:00
parent e5c99a5eee
commit 6ee6502010
2050 changed files with 538359 additions and 57745 deletions
+326
View File
@@ -0,0 +1,326 @@
# Odysseus Tool Runtime Hardening Plan
## Objective
Ship `odysseus-qwen3.5-tools-pre-heretic` with one compact, model-specific tool
runtime that supports realistic multi-turn use. Keep the existing RAG runtime
unchanged for every other model. Prove routing, execution, answer quality,
follow-ups, safety, rendering, latency, and native image/VL understanding through
the real 7011 Agent UI.
Current evidence is a baseline, not a ship claim:
- Corrected v2.5 + compact-v5 development is 327/344 raw (95.06%) and
327/336 scorable (97.32%). Sealed blind is 311/344 raw (90.41%) and
311/336 scorable (92.56%), with zero reasoning leakage.
- Notes, Skills, and Cookbook/admin clear 95% scorable blind. Calendar 87.5%,
Shell/files 86.11%, and Tasks 87.5% remain below the 90% family ship floor.
- Compact-v5 hints improved Email, Search/HF quant, and Shell on development;
a Calendar hint regressed and was rejected rather than shipped.
- Ten-family focused baseline: 19/20 functional and 20/20 routing/execution.
- Typo and cross-family read flows: 26/26 passed.
- Real use exposed untested write correction and search-to-fetch follow-ups.
- Email production access, browser interaction, search quality, and broader
multi-turn mutations are not yet proven.
- Nine enabled chat-capable regular API models pass the ten-family read-only
legacy-RAG baseline (90/90 combined). Their stricter typo/follow-up profile is
178/180 turns: eight models are 20/20 and Luna is 18/20 due only to its
misspelled Shell request. One pinned image-generation model is explicitly
unsupported and two visible local models are currently offline.
- Native VL object/spatial recognition and reload follow-up pass. Exact OCR
fails equally on the fine-tune and untouched 9B base and remains unresolved.
PNG, JPEG, and WebP transport all pass.
- Reversible create/correct/API-verify/cleanup flows pass 6/6 across every
stateful family.
- Search Web-toggle combinations pass 8/8 and the focused quality suite passes
3/3. Production-path email account/inbox/referential reads pass 3/3.
- The latest regular-model regression is 90/90 across the nine enabled
chat-capable API models, with zero failed model turns; two local endpoints
remain offline and the image-only model is unsupported.
- The Epictetus OMLX endpoint was recovered after an unsupported
`qwen3_5_mtp` model load wedged the server. Its supported Qwen 27B 4-bit
model passes the ten-family real-7011 legacy-RAG smoke 10/10; the unsupported
MTP artifact is recorded as a runtime limitation rather than a timeout.
- Fresh compact-v5 UI regressions pass stateful 6/6, Email 3/3, Search 3/3,
private-browser 3/3, and VL workflow 3/3.
- The exact-model, family-scoped compact runtime now passes 20/20 direct and
same-family turns across all ten families on the real 7011 Agent UI. A
separate 36/36 robustness run passes misspellings, bounded repeats, browser
and news continuation, ambiguous follow-ups, family switchbacks, and a
greeting before a tool request.
- The mobile active-email editor path passes 1/1: `Write reply this email`
offers and executes only `update_document`, mutates the open draft, and
preserves its reply headers and quoted thread.
- The active-editor classifier now also covers short mobile wording without a
pronoun (`Write reply` / `Draft a reply`) while explicit note, code, file, and
new-object requests retain their own families. Whole-draft requests are bound
to the sole offered `update_document` writer until one successful write, then
tools are removed for the confirmation round. The deployed real-route email
regression passes 3/3—including the exact unspecified `Write reply to this
email` form—with one write, verified mutation, and preserved reply headers.
Clean-v3 now also emits the established `doc_update` event and flattened
document metadata on `tool_output`, so a successful database write updates
the already-open editor instead of leaving stale UI beside a success message.
- The client now reuses the existing assistant bubble for `agent_step` round 1
instead of replacing it before the first token. A real-7011 sampled
greeting-to-Notes conversation passes 2/2 with stable first-round DOM
identity; round 2+ remains the only continuation-bubble path.
- Clean-runtime metrics now expose provider-counted initial injected tokens,
all-round input/output, TTFT, tok/s, schema count, agent rounds, and tool-call
count. A real 7011 browser run passes 2/2 and visibly renders compact footers
plus the full details popup; the sampled Notes turns streamed progressively.
- The deployed startup bottleneck was an unindexed quadratic transcript-FTS
reconciliation. Live-database import fell from about 36 seconds to 0.54
seconds; 7011 now answers in about 3 seconds after a controlled restart.
- A controlled identical-compact comparison already proves the fine-tune's
accuracy benefit: 94.48% (325/344) versus the untouched base's 77.91%
(268/344). Raw serving speed is effectively tied, so product speed comes
from the compact contract and fewer failed/redundant rounds.
- A fully merged 10,000-row category-repair candidate reached 97.32% scorable
development but only 92.26% scorable sealed blind. Calendar (87.5%), Tasks
(87.5%), and Shell/files (86.11%) remained below the family floor, so it was
rejected and not deployed. Compact-v4/full development A/Bs did not improve
Calendar or Tasks over compact-v5; full-schema Shell also fell from 97.22%
to 94.44%. This rules out compactness as the primary cause of the remaining
blind gaps and supports keeping the compact contract.
## Non-negotiable architecture rules
1. Runtime selection follows exact model identity. The trained Odysseus model
uses the clean compact runtime across endpoint aliases; all other models use
legacy RAG. Add a regression test for both sides.
2. Resolve permissions, toggles, and available backends once per turn. Produce
one immutable contract satisfying `required ⊆ offered ⊆ executable`.
3. Never offer a tool that the preview policy will categorically reject. Add a
contract self-check covering every offered action/effect combination.
4. Follow-ups consume typed prior evidence: native call, result, success state,
family, and object identifiers. Do not infer continuity from keyword RAG.
5. Contextual write authority may revise only a recently proven object in the
same family. It may not authorize a new object, another family, a destructive
action, or an external side effect.
6. The model chooses tools and valid arguments. The harness validates and
executes; it does not silently substitute another family, rewrite arguments,
fabricate success, or replace a failed tool with prose claiming completion.
7. One owner renders each turn: streamed prose or canonical structured output.
Never both, and never expose hidden prompts or raw untrusted wrappers.
8. No exact-prompt production patches. A fix must name the failed layer, add a
generic failing invariant test, and cover neighboring cases.
## Failure layers
Every failure is assigned to exactly one primary layer before code changes:
1. **Route:** wrong model runtime or endpoint identity.
2. **Contract:** required tool absent, forbidden tool present, or toggle drift.
3. **Model:** wrong/no tool or semantically wrong required arguments despite a
correct contract.
4. **Policy:** valid proposed operation incorrectly allowed or denied.
5. **Execution:** canonical arguments, backend dispatch, timeout, or result
envelope is wrong.
6. **Evidence:** result is empty, irrelevant, truncated badly, or insufficient.
7. **Answer:** model misstates or ignores valid tool evidence.
8. **Rendering:** duplicate, dump-at-end, missing structured output, or stopped
stream.
9. **Performance:** startup, TTFT, tool latency, or oversized context.
Reports store aggregate category, relevant contract/tool metadata, timings, and
sanitized outputs. Do not copy private hidden benchmark prompts or create a log
dump that nobody can audit.
## Test matrix
Use the real authenticated 7011 Agent UI and the normal `preheret` picker alias.
Use `sft_alex_creator` for reversible writes. Never mutate the personal account
from an automated test.
### A. Every one of the ten families
For calendar, notes, email, tasks, documents, memory, skills, Cookbook/admin,
search/browser, and shell/files, test:
- direct request;
- natural misspelling;
- ambiguous same-family follow-up;
- switch to another family and back;
- no-tool greeting before the tool request;
- requested count/field limit;
- backend failure rendered truthfully;
- reload the permalink before a follow-up.
### B. Stateful mutation families
For notes, calendar, tasks, documents, memory, and skills:
- create → verify by API → referential correction → verify;
- create → list/read → correction → verify;
- typo correction such as name/date/title without repeating the family noun;
- correction after one unrelated conversational turn;
- destructive request is denied atomically;
- failed write never produces a success claim;
- cleanup deletes only the UUID-owned test artifact and verifies absence.
### C. Search and browser conversations
- search → summarize existing results without a new call;
- search → inspect one result with `web_fetch`;
- poor results → refine query once;
- insufficient evidence → say so without fabrication;
- Web toggle combinations `00`, `01`, `10`, and `11` across two turns;
- private browser open/snapshot/click only after its permission boundary is
deliberately enabled and specified; do not smuggle it in via web search.
Grade source relevance, freshness, authority, and whether claims are supported,
not merely whether `web_search` was called.
### D. Email and shell
- Separate fixture accuracy from production connectivity. A fixture pass cannot
promote production email health.
- Test account listing, inbox listing, reading, and referential follow-up against
the configured production-like backend before enabling email actions.
- Shell remains toggle-gated. Test off/on transitions, canonical raw command
dispatch, read-only output, and denial of network/destructive commands.
### E. Rendering and performance
- Assert first visible streamed token, monotonic DOM growth, one final answer,
persistence/reload equality, stop behavior, and structured list rendering.
- Record request preparation, TTFT, tool duration, post-tool TTFT, total time,
input/output tokens, and tool-result bytes.
- Diagnose the 30–40 second 7011 restart separately from inference latency.
- Bound large calendar/search results before replaying them into later rounds,
while preserving IDs and fields needed for follow-ups.
### F. Image/VL recognition
- Attach real PNG, JPEG, and WebP images through the 7011 UI and verify the
trained model receives native multimodal message content on its clean route.
- Test object recognition, visible text/OCR, spatial relationships, charts, and
screenshots. Score required facts instead of stylistic wording.
- Test image → ambiguous follow-up, image → tool request, and tool result → image
comparison without requiring the user to attach the same image again.
- Verify image references survive persistence and permalink reload without raw
base64, local paths, or hidden wrappers appearing in chat output.
- Separate direct model vision from `inspect_media`, browser screenshots, and
image generation. The harness must not silently substitute one for another.
- Compare the fine-tune with its base VL model on the same images to detect
whether tool training regressed visual understanding.
### G. Regular-model legacy RAG and tool coverage
- Inventory every enabled non-Odysseus endpoint/model visible in 7011, including
its provider, schema mode, native-tool support, context limit, and configured
permissions. Do not assume every provider supports the same wire format.
- Assert that no non-Odysseus model enters the clean-v3 runtime. These models
retain the regular RAG/tool loop and are repaired only in that owning path.
- For each model, test every tool family the effective user policy offers:
direct request, misspelling, ambiguous follow-up, family switch, backend
failure, and Web/Bash toggle transitions. Record unsupported families as an
explicit capability limitation, not a silent pass.
- Test full schemas versus compact schemas only where both are valid for that
model. Store the selected schema mode in every report.
- Verify provider-native tool calls, textual fallback parsing where required,
canonical argument conversion, execution, evidence replay, and rendering.
- Group fixes by shared legacy-runtime or provider-adapter defect. Do not add
model-name prompt exceptions when a transport, schema, or RAG ranking issue is
responsible.
- Maintain a per-model compatibility matrix so adding or changing an endpoint
cannot silently regress previously working tools.
## Fix protocol
For each failure:
1. Preserve the raw report and reproduce once on a fresh test session.
2. Identify the primary failure layer from the taxonomy above.
3. Add the smallest generic red test at that layer.
4. Fix the owning module or invariant—not the literal prompt.
5. Run the focused unit tests, the original scenario, two adjacent scenarios,
and the affected family suite.
6. After a batch of category fixes, rerun the ten-family matrix and legacy-RAG
isolation test. Do not rerun training unless the contract and harness are
proven correct and failures remain model-owned.
If three failures share a layer, pause case-by-case patching and refactor that
layer before continuing.
## Execution phases
### Phase 1 — Make the runtime auditable
- Add a sanitized per-turn decision record: model runtime, contract, proposed
calls, policy decisions with reason codes, executions, render owner, timings.
- Add startup/runtime provenance to the UI so a linked chat proves which harness
handled it.
- Add the offered-versus-policy compatibility self-test.
- Correct stale preview documentation.
### Phase 2 — Build the conversation suite
- Extend the current Playwright verifier with reusable multi-turn scenarios and
reversible artifact fixtures.
- Implement the matrix above, prioritizing search continuations and all
stateful corrections because real usage already exposed those gaps.
- Run independent family groups in parallel, but serialize writes that share a
backend or fixture account.
- Add a small versioned VL fixture set with locally generated, non-private
images and deterministic answer keys.
### Phase 3 — Repair by architecture category
- Consolidate model-specific runtime selection in one function.
- Represent prior successful objects explicitly for referential follow-ups.
- Align tool capability classification, contract offering, and policy decisions.
- Standardize tool results into bounded envelopes with source/object IDs.
- Keep search refinement and evidence sufficiency generic.
### Phase 4 — Accuracy and speed comparison
- Compare the clean fine-tune with the base model using identical compact tools,
prompts, toggles, backend state, and semantic scoring.
- Report functional accuracy, argument accuracy, unsupported success claims,
TTFT, total latency, and tokens. Do not compare one model on full schemas and
another on compact schemas.
- Only consider more SFT/RL for failures classified as model-owned after the
harness audit.
### Phase 4B — Regular-model repair and verification
- Snapshot the enabled non-Odysseus model inventory.
- Run the legacy-RAG compatibility matrix in bounded parallel groups, respecting
endpoint rate limits and shared backend write serialization.
- Fix shared harness/provider defects first, then rerun all affected models.
- Publish separate per-model scores and limitations; do not blend them into the
Odysseus fine-tune score.
### Phase 5 — Ship gate
Ship only when:
- every family is at least 90% on sealed functional holdout;
- overall functional accuracy is at least 95%;
- realistic follow-up suite is at least 95%, with no repeated failure category;
- image/VL fixture accuracy does not regress materially from the base model and
all attachment/follow-up/persistence flows pass;
- routing/execution and safety invariants are 100%;
- all reversible writes are API-verified and cleaned up;
- search quality and production email are reported separately and honestly;
- non-Odysseus models demonstrably retain legacy RAG;
- every enabled regular model has a complete tested-tool compatibility record,
and every tool advertised as supported passes its functional checks;
- no hidden prompt leakage, duplicate rendering, or false success remains;
- pre-heretic passing weights and merged adapter backups remain recoverable.
## Immediate next batch
1. Expand VL fixtures to charts, screenshots, and image-to-tool turns;
investigate the shared base-model OCR limitation without hiding it behind a
silent external fallback.
2. Add deliberately permissioned private-browser open/snapshot/click checks;
keep browser interaction unavailable when its boundary is not enabled.
3. Bring the two configured local regular models online and run their matrix.
4. Compare fine-tune versus untouched base with identical compact contracts,
backend state, prompts, and timing instrumentation.
5. Run the sealed all-action holdout and prioritize failures by shared
layer rather than by prompt.
+445
View File
@@ -0,0 +1,445 @@
# Plan: Odysseus Professional Photo Editor
> Source PRD: Conversation goal, "a Photoshop/Photopea clone with Odysseus style"
## Product boundary
Odysseus should provide the editing loop people expect from a professional
layer-based photo editor without copying Photoshop's visual design or trying to
match every specialist feature. The target is a dependable browser editor for
real photo work: direct manipulation, non-destructive layers, precise masking,
retouching, typography, export, recovery, and optional AI assistance.
The existing quiet Odysseus interface remains the visual language. Dense tools
are acceptable, but controls should stay restrained, compact, predictable, and
usable on both desktop and touch devices.
## Existing foundation
The current editor already provides meaningful parts of this product:
- Raster and editable text layers
- Multi-layer selection, nested groups, clipping, visibility, opacity, and locks
- Layer, group, and selection masks
- Marquee, lasso, wand, SAM, Quick Mask, and saved selections
- Brush, eraser, clone, crop, transform, and text tools
- Blend modes, adjustment stacks, blur, and several image corrections
- Rulers, guides, grid, snapping, zooming, and panning
- Undo/redo history with a memory budget
- Versioned layered-project serialization, autosave drafts, recovery, and export
- Optional endpoint-backed inpaint and image-processing tools
- Desktop and mobile editor layouts with Playwright release-gate coverage
## Architectural decisions
Durable decisions that apply across every phase:
- **Editor ownership**: The editor remains an Odysseus feature. Do not embed a
third-party editor or imitate another product's chrome.
- **Document format**: Continue the versioned Odysseus editor document. Every
new persistent capability requires a migration, validation, round-trip test,
and corrupt-input recovery behavior.
- **Layer model**: Grow the document into explicit layer kinds rather than
hiding more behavior in raster canvases. The intended kinds are raster, text,
shape, adjustment, and placed/smart content.
- **Non-destructive default**: Preserve source pixels and editable parameters
whenever practical. Destructive actions remain available as explicit Apply,
Rasterize, or Merge commands.
- **Interaction engine**: Transform, crop, selections, text frames, masks, and
shapes share one pointer-session model for hit testing, pointer capture,
modifiers, snapping, cancellation, and undo transactions.
- **Rendering**: Keep Canvas 2D as the compatibility renderer initially. Move
expensive compositing and pixel operations behind renderer/worker boundaries
before considering WebGL or WebGPU acceleration.
- **History**: One continuous gesture creates one undo entry. Preview frames are
never separate history entries, and Cancel restores the exact starting state.
- **Persistence routes**: Continue using `/api/editor-drafts` for layered draft
persistence and `/api/gallery` for media-library save/replace operations.
- **AI boundary**: AI features consume capability-based image endpoints. Core
editing never requires a particular model, repository, or provider.
- **Responsive behavior**: Desktop favors precision; touch targets gain larger
invisible hit areas without visually enlarging the whole interface.
- **Testing**: Every phase adds deterministic geometry/unit tests and at least
one complete Playwright workflow covering persistence and undo where relevant.
- **Incremental architecture**: New behavior leaves the main editor orchestrator
through small domain modules. Avoid broad refactors that do not deliver a
visible editing improvement in the same phase.
---
## Phase 1: Accurate Transform Frame
**User stories**: I can clearly see and grab the transform frame at any zoom. I
can resize from corners or sides without grabbing invisible or incorrect areas.
### What to build
Replace the four-corner-only frame with a shared frame geometry model. Render
four corners, four edge handles, a rotation control, and an optional center
pivot from the same geometry used for hit testing. Keep handles visually compact
while providing touch-sized invisible targets. Make the frame stay aligned
during zoom, pan, viewport resize, and when handles extend outside the image.
### Acceptance criteria
- [x] Eight resize handles, rotation control, and center pivot derive from one geometry result.
- [x] Drawn handles and hit targets cannot disagree.
- [x] Handles remain a stable visual size from minimum to maximum zoom.
- [x] Touch hit targets are at least 40 CSS pixels without oversized visuals.
- [x] Outside-canvas handles remain interactive and visible when space permits.
- [x] Hover and active cursors match each handle's current screen direction.
- [x] Desktop and mobile Playwright tests grab every handle successfully.
---
## Phase 2: Correct Rotated Resize
**User stories**: I can resize a rotated layer naturally. The opposite side or
corner stays fixed, and the frame follows my pointer rather than drifting.
### What to build
Calculate drag movement in the frame's rotated local coordinate system. Anchor
the opposite handle in document space and derive the new center from that
anchor. Support crossing an axis as a deliberate flip instead of clamping to a
one-pixel box. Apply the same geometry to one layer, multiple layers, and a
selection transform.
### Acceptance criteria
- [x] Rotated corner and edge drags follow the pointer on the frame's local axes.
- [x] The opposite anchor remains fixed within a sub-pixel tolerance.
- [x] Crossing width or height zero produces a predictable horizontal or vertical flip.
- [x] Shift locks the starting aspect ratio.
- [x] Alt/Option scales around the transform center.
- [x] Combined Shift+Alt/Option behavior is deterministic.
- [x] Rotation snaps to 15-degree increments with Shift and remains smooth otherwise.
- [x] Geometry tests cover 0, 45, 90, 135, and arbitrary-degree rotations.
---
## Phase 3: Transform Interaction Polish
**User stories**: Transform behaves like a professional tool on mouse, pen, and
touch. I can see exact values, snap precisely, and never lose a drag at the edge.
### What to build
Use a unified pointer session with pointer capture, live modifiers, and a small
contextual transform readout. Add accurate rotated-frame interior hit testing,
keyboard nudging, frame snapping, and clear Apply/Cancel behavior. Keep the
existing compact Odysseus styling and make the numeric popup a precision surface
rather than a competing transform implementation.
### Acceptance criteria
- [x] Pointer capture keeps a drag alive outside the canvas and browser viewport.
- [x] Clicking inside a rotated frame moves it; clicking its empty bounding-box corner does not.
- [x] Live X, Y, W, H, and angle values stay synchronized with direct manipulation.
- [x] Arrow keys nudge, Shift+Arrow performs a larger nudge, Enter applies, and Escape cancels.
- [x] Layer edges, document center/edges, guides, and grid participate in transform snapping.
- [x] Snap guides clearly identify the active alignment without obscuring the photo.
- [x] A complete gesture creates exactly one undo step.
- [x] Touch gestures do not conflict with viewport pinch/pan behavior.
---
## Phase 4: Transform Content Correctness
**User stories**: Transforming layers never unexpectedly damages masks, text,
group layout, clipping, or image quality. Saving and reopening preserves it.
### What to build
Route raster layers, text layers, linked and unlinked masks, selections, clipped
layers, and grouped multi-selection through the same transform contract. Keep
immutable source data during previews and validate the final result through
undo, cancel, autosave, project download, and reopen.
### Acceptance criteria
- [x] Raster previews are always derived from the session source, never a prior preview.
- [x] Editable text remains editable after scaling, rotation, and flipping.
- [x] Linked masks follow the layer while unlinked masks remain in document space.
- [x] Multi-layer transforms preserve relative centers, order, clipping, and group membership.
- [x] Transforming a selection changes only the selection mask unless content transform is explicitly chosen.
- [x] Apply, Cancel, Undo, Redo, autosave reopen, and project-file reopen produce matching pixels and metadata.
- [x] Large transforms cannot allocate beyond the editor's documented surface budget.
---
## Phase 5: Shared Direct-Manipulation Sessions
**User stories**: Crop, selections, masks, text boxes, and shapes feel consistent
with Transform instead of each behaving like a separate mini application.
### What to build
Generalize the proven transform pointer session into a reusable interaction
contract. Migrate crop and selection movement first as a visible tracer bullet,
including modifiers, snapping, pointer capture, cancel, and one-step history.
### Acceptance criteria
- [x] Transform, crop, and selection movement use the same gesture lifecycle.
- [x] Tool switching safely commits, cancels, or prompts according to one policy.
- [x] No stale pointer session can modify a newly selected tool or document.
- [x] Mouse, pen, and touch event behavior is covered by shared tests.
- [x] Adding a future frame-based tool does not require another global event stack.
---
## Phase 6: Non-Destructive Placed Layers
**User stories**: I can import an image, resize it repeatedly without cumulative
quality loss, replace its source, and choose when to rasterize it.
### What to build
Introduce a placed/smart layer kind containing source pixels and persistent
transform metadata. Import-as-layer uses this kind by default. Rendering applies
the transform at composite time, while Rasterize produces a normal raster layer.
### Acceptance criteria
- [x] Repeated transforms render from the original source rather than resampling the last result.
- [x] A placed layer can be replaced while preserving its transform and masks.
- [x] Rasterize produces a visually matching editable raster layer.
- [x] Masks, clipping, groups, blend modes, and opacity work with placed layers.
- [x] Version migration and recovery handle missing or corrupt placed sources.
- [x] Existing raster projects open without changed output.
---
## Phase 7: Professional Selections And Masks
**User stories**: I can build, inspect, refine, save, transform, and reuse precise
selections without manually repainting every edge.
### What to build
Unify marquee, lasso, wand, SAM, Quick Mask, and saved selections around one
selection-mask model. Add explicit replace/add/subtract/intersect modes, feather,
expand, contract, smooth, border, and a focused refine-edge workflow.
### Acceptance criteria
- [x] Every selection tool supports replace, add, subtract, and intersect modes.
- [x] Feather, expand, contract, smooth, and border preview before applying.
- [x] Quick Mask edits the same canonical selection shown by marching ants.
- [x] Selection-to-layer-mask and layer-mask-to-selection round-trip accurately.
- [x] Saved selections retain names and pixels across reopen.
- [x] Edge refinement works without requiring an AI dependency.
---
## Phase 8: Paint And Retouch Workflow
**User stories**: I can paint and retouch photographs with predictable strokes,
reusable presets, and the controls expected for a mouse, pen, or touch device.
### What to build
Promote brush behavior into a reusable brush engine. Add spacing, smoothing,
pressure mapping, blend mode, sampled color, presets, and stroke preview. Build
healing, dodge, and burn as complete retouching paths using that engine.
### Acceptance criteria
- [x] Brush, eraser, clone, masks, and inpaint share spacing and smoothing behavior.
- [x] Pressure can independently affect size, opacity, or flow when supported.
- [x] Eyedropper samples composite or active-layer color.
- [x] Brush presets can be created, named, selected, and deleted.
- [x] Healing, dodge, and burn create one undo entry per stroke.
- [x] Long strokes remain smooth without blocking the main interface.
---
## Phase 9: Editable Text And Shapes
**User stories**: I can design labels, cards, and overlays with text and vector
shapes that remain editable after saving and reopening.
### What to build
Add on-canvas text-frame editing, selection, caret behavior, typography, and
alignment. Introduce shape layers for rectangle, ellipse, line, and path-backed
polygons with editable fill, stroke, corners, and transform metadata.
### Acceptance criteria
- [x] Text is edited directly on canvas without immediately rasterizing.
- [x] Font, size, weight, line height, letter spacing, alignment, and color persist.
- [x] Rectangle, ellipse, line, and polygon shapes remain editable.
- [x] Shape fill, stroke, width, and corner radius can be changed after creation.
- [x] Text and shape layers support masks, clipping, groups, blend modes, and transform.
- [x] Missing fonts fall back predictably without corrupting the project.
---
## Phase 10: Adjustment Layers And Color
**User stories**: I can correct a photograph non-destructively and return later
to modify the correction without reconstructing the edit.
### What to build
Promote adjustments into first-class layers with masks and clipping. Deliver
Levels and Curves first, then exposure, white balance, hue/saturation, color
balance, selective color, gradients, and channel-aware controls.
### Acceptance criteria
- [ ] Adjustment layers affect content below them and can be clipped or grouped.
- [ ] Every adjustment has live preview, reset, visibility, opacity, mask, Apply, and Cancel behavior.
- [ ] Levels includes histogram, input range, gamma, and output range.
- [ ] Curves supports RGB and channel curves with editable points.
- [ ] Color results match flattened export and project reopen.
- [ ] Large previews are throttled or worker-backed and remain cancellable.
---
## Phase 11: Layer Effects And Filters
**User stories**: I can add common visual effects without permanently altering
the layer and can reorder or disable those effects later.
### What to build
Create an ordered non-destructive filter/effect stack. Begin with Gaussian blur,
sharpen, shadow, stroke, and color overlay; then add filter masks and reusable
effect presets.
### Acceptance criteria
- [ ] Effects can be added, reordered, toggled, edited, masked, and removed.
- [ ] Drop shadow, stroke, color overlay, blur, and sharpen survive project reopen.
- [ ] Effects render correctly inside groups and clipping stacks.
- [ ] Apply/rasterize produces a pixel-equivalent raster result.
- [ ] Expensive filters expose progress and cancellation.
---
## Phase 12: Odysseus Professional Workspace
**User stories**: I can work quickly without fighting floating windows or losing
the active tool, layer, selection, or document context.
### What to build
Refine the existing shell into a consistent professional workspace: contextual
tool options, properties inspector, panel persistence, command search, status
information, multi-document switching, and compact touch sheets. Preserve the
current Odysseus palette, typography, restrained borders, and frosted surfaces.
### Acceptance criteria
- [ ] Tool options appear in one predictable location and never duplicate popup state.
- [ ] Panels remember size, collapsed state, and position per device class.
- [ ] The properties inspector follows the active layer, mask, selection, or tool.
- [ ] Command search exposes actions and shortcuts without adding toolbar clutter.
- [ ] Switching documents preserves independent history, zoom, pan, and selection.
- [ ] Mobile prioritizes canvas area while keeping all commands reachable.
---
## Phase 13: File Interchange And Export
**User stories**: I can bring common assets into Odysseus and export predictable
results without losing transparency, dimensions, or color intent.
### What to build
Strengthen image import/export first, then add layered interchange where a
maintained parser makes it safe. Keep Odysseus project files as the lossless
source of truth and clearly report what an external format cannot preserve.
### Acceptance criteria
- [ ] PNG, JPEG, WebP, and supported modern image imports honor orientation and transparency.
- [ ] Export exposes format, dimensions, quality, metadata, and transparency choices.
- [ ] Copy/paste and drag/drop preserve alpha and use placed layers when appropriate.
- [ ] Layered imports report unsupported features instead of silently flattening them.
- [ ] Exported pixels are covered by deterministic visual comparisons.
---
## Phase 14: Large-Document Performance And Recovery
**User stories**: Large photos and layered projects remain responsive, autosave
reliably, and recover after a crash or interrupted network connection.
### What to build
Move serialization, thumbnails, filters, and suitable pixel operations into
workers. Add dirty-region rendering, reusable surfaces, measurable memory
budgets, operation cancellation, autosave generations, and recovery diagnostics.
### Acceptance criteria
- [ ] Normal interactions remain responsive on the agreed 4K multi-layer benchmark.
- [ ] Compositing avoids rebuilding unaffected layers and thumbnails.
- [ ] History and document surfaces stay within explicit memory limits.
- [ ] Closing or switching documents cancels stale work safely.
- [ ] Autosave never lets an older request overwrite newer state.
- [ ] Recovery can identify the last complete generation and explain skipped data.
---
## Phase 15: Odysseus-Native Assisted Editing
**User stories**: I can use an available local or remote image capability as an
editing assistant while retaining masks, layers, undo, privacy choices, and
normal manual controls.
### What to build
Standardize image capability discovery and requests for generation, editing,
inpainting, segmentation, restoration, and upscaling. Results enter the document
as named layers with provenance and reusable masks. Add orchestration only after
the manual operation it assists is dependable.
### Acceptance criteria
- [ ] The UI describes required capabilities rather than model or provider names.
- [ ] Memory and unrelated chat context are not sent to image endpoints.
- [ ] Requests show progress, support cancellation, and cannot update a closed document.
- [ ] Generated results arrive as reversible layers with prompt/settings metadata.
- [ ] A failed endpoint leaves the source document unchanged and offers a useful retry path.
- [ ] Manual selection and masking remain available when assisted tools are absent.
---
## Phase 16: Professional Release Gate
**User stories**: I can trust the editor for real work and understand what is
unsupported before committing an edit.
### What to build
Create a release gate around complete user journeys rather than isolated button
tests. Cover accessibility, keyboard-only operation, touch, browser differences,
pixel correctness, persistence, failure recovery, and large-document behavior.
### Acceptance criteria
- [ ] Core workflows pass on current Chromium and Firefox desktop builds.
- [ ] Mobile workflows pass at representative phone and tablet viewports.
- [ ] Keyboard-only users can reach every command and escape every modal state.
- [ ] Transform, masks, text, adjustments, export, and reopen have pixel/metadata regression tests.
- [ ] No supported action silently flattens or discards editable document data.
- [ ] The ALPHA badge can be removed based on explicit reliability metrics.
---
## Recommended delivery order
The first four phases are one focused Transform 2.0 program and should ship in
order. Phases 5 and 6 establish the interaction and document foundations needed
for the remaining professional tools. After that, phases 7 through 13 can be
prioritized by user value, while performance and release-gate work continue as
part of every phase rather than being deferred entirely to the end.
The recommended first milestone is complete when Phases 1 through 4 are live:
transforming one layer, multiple layers, text, masks, and selections feels
precise on desktop and mobile and remains correct through undo and reopen.
+159
View File
@@ -0,0 +1,159 @@
# 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.