From 890386c7f752f0bf04a7c9ed1dc361646b5b2a29 Mon Sep 17 00:00:00 2001 From: Lightning Pixel Date: Wed, 18 Nov 2026 13:29:18 +0100 Subject: [PATCH 1/8] docs: design and plan for the Image Studio tool icons and crop --- .../plans/2026-11-18-image-studio-tools.md | 120 ++++++++++++++++++ .../2026-11-18-image-studio-tools-design.md | 61 +++++++++ 2 files changed, 181 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-18-image-studio-tools.md create mode 100644 docs/superpowers/specs/2026-11-18-image-studio-tools-design.md diff --git a/docs/superpowers/plans/2026-11-18-image-studio-tools.md b/docs/superpowers/plans/2026-11-18-image-studio-tools.md new file mode 100644 index 00000000..5d734f6e --- /dev/null +++ b/docs/superpowers/plans/2026-11-18-image-studio-tools.md @@ -0,0 +1,120 @@ +# Image Studio Tools Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the Image Studio header sliders with tool icons, a contextual options bar, and an interactive crop frame. + +**Architecture:** The page owns `activeTool` and two DOM slots (an options bar under the header, an overlay layer in the canvas). Each op control keeps its own state as today, renders its icon in the header, and portals its options (and, for crop, its overlay) into the slots. Crop geometry is a pure, unit-tested module; the backend crop op accepts float percentages. + +**Tech Stack:** React 18 + TypeScript + Tailwind (renderer), `node:test` (JS tests), FastAPI + Pillow + `unittest` (backend). + +**Spec:** `docs/superpowers/specs/2026-11-18-image-studio-tools-design.md` + +## Global Constraints + +- English only in code, comments, commit messages. No attribution trailer in commits. +- Do not commit: the coordinator commits. Do not touch files outside your task's list. +- Keep the generic path: an unknown op id gets the fallback wand icon and `ParamFields` options. +- Style with the page's existing zinc/accent Tailwind classes. +- JS tests: `npm run test:node`. Python tests: from `api/`, `.venv/Scripts/python.exe -m unittest tests.test_image_ops_framing tests.test_image_ops_registry`. Lint: `npm run lint` must stay at 0 problems. + +## Review Focus + +1. The window or canvas resizes during a crop: the frame must stay on the same image pixels (overlay mapping recomputed via `ResizeObserver`). — Task 4, manual check. +2. The selected image changes while crop is active: the frame resets to the new input's full image. — Task 4 (`key` on the input id). +3. Images smaller than 16 px: the minimum size becomes the image size, no NaN or inverted rect. — Task 2 test `min size never exceeds a tiny image`. +4. Pointer released outside the canvas: the drag ends (pointer capture). — Task 4. +5. Enter/Esc typed in a number field of the options bar: ignored by the shortcuts. — Tasks 3 and 4 use `isTextField(event.target)`. + +--- + +### Task 1: Backend crop takes float percentages + +**Files:** +- Modify: `api/services/image_ops/builtin.py` (`_edge_param`, `crop`) +- Test: `api/tests/test_image_ops_framing.py` + +**Interfaces:** +- Produces: op `crop` params `left|top|right|bottom`: `type "float"`, `default 0.0`, `min 0.0`, `max 99.0`, `step 0.1`. + +- [ ] **Step 1: Update/add tests** + - `test_crop_edges_are_clamped`: `resolve_params("crop", {"left": 150})["left"] == 99.0`. + - `test_crop_accepts_fractional_percentages`: on a 1000×500 image, `{"left": 12.5, "top": 10.2}` → output size `(875, 449)` (`crop_box` rounds: x0=125, y0=51). + - `test_crop_refuses_an_empty_box`: `{"left": 60, "right": 40}` raises `ImageOpInputError`; same for `top+bottom >= 100`. +- [ ] **Step 2: Run, expect the new tests to FAIL.** +- [ ] **Step 3: Implement** the schema change and, in `crop`, raise `ImageOpInputError("Nothing left to crop: the frame is empty.")` when `left + right >= 100` or `top + bottom >= 100`. Update the tooltip to "Percentage of the image cut off the {edge} edge." +- [ ] **Step 4: Run both test modules, expect PASS.** + +### Task 2: Crop geometry module + +**Files:** +- Create: `src/areas/image-studio/cropGeometry.ts` +- Test: `src/areas/image-studio/cropGeometry.test.ts` + +**Interfaces (Produces):** +```ts +export interface ImageSize { width: number; height: number } +export interface Rect { x: number; y: number; w: number; h: number } // integer image pixels +export type Handle = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw' | 'move' +export type AspectMode = 'free' | 'square' | 'original' +export const MIN_CROP_PX = 16 +export function fullRect(size: ImageSize): Rect +export function minCropSize(size: ImageSize): { w: number; h: number } // min(16, side) per axis +export function aspectRatio(mode: AspectMode, size: ImageSize): number | null // w / h; free → null +export function fitToRatio(rect: Rect, ratio: number | null, size: ImageSize): Rect +export function dragRect(start: Rect, handle: Handle, dx: number, dy: number, size: ImageSize, ratio: number | null): Rect +export function cropEdges(rect: Rect, size: ImageSize): { left: number; top: number; right: number; bottom: number } // percent +export function isFullRect(rect: Rect, size: ImageSize): boolean +``` +Semantics: `dx/dy` are image-pixel deltas from the drag start (the caller always passes the `start` rect captured at pointerdown). Results are rounded to integers, inside the image, at least `minCropSize`. `move` translates, clamped. Edge/corner handles move the dragged edges; the opposite edges stay put. With a ratio: corner handles keep the opposite corner as anchor and size from the larger of the two proposed dimensions, shrunk to fit the image; edge handles change the dragged dimension and the other one follows, centered on the rect's perpendicular center, shrunk to fit. `fitToRatio` returns the largest rect of that ratio inside `rect`, centered on it (`null` returns `rect`). + +- [ ] **Step 1: Write failing tests** (size 200×100 unless stated): + - `fullRect` → `{x:0,y:0,w:200,h:100}`; `isFullRect(fullRect(s), s) === true`. + - `move` by (50, 50) from `{x:10,y:10,w:100,h:50}` → `{x:60,y:50,w:100,h:50}`; by (500, 0) → `x: 100`. + - `e` by +30 from `{x:0,y:0,w:100,h:100}` → `w:130`; `w` by +95 from `{x:0,y:0,w:100,h:100}` → `{x:84, w:16}` (min size). + - `se` by (+500,+500) from `{x:0,y:0,w:50,h:50}` → `{w:200,h:100}`. + - `nw` by (-20,-20) from `{x:10,y:10,w:50,h:50}` → `{x:0,y:0,w:60,h:60}`. + - ratio 1: `se` by (+40, +10) from `{x:0,y:0,w:50,h:50}` → `{w:90,h:90}`; by (+300,+300) → `{w:100,h:100}` (fits height). + - ratio 1: `e` by +20 from `{x:50,y:25,w:50,h:50}` → `{w:70,h:70}`, vertically centered then clamped into the image (`y` in `[0, 30]`). + - `fitToRatio({x:0,y:0,w:200,h:100}, 1, s)` → `{x:50,y:0,w:100,h:100}`; `aspectRatio('original', s) === 2`; `aspectRatio('free', s) === null`. + - `cropEdges({x:20,y:10,w:100,h:50}, s)` → `{left:10, top:10, right:40, bottom:40}`. + - `min size never exceeds a tiny image`: size 8×4 → `minCropSize = {w:8,h:4}`; `dragRect(fullRect, 'w', 100, 0, …)` → `{x:0,w:8}`. +- [ ] **Step 2: Run `npm run test:node`, expect FAIL (module missing).** +- [ ] **Step 3: Implement.** +- [ ] **Step 4: Run, expect PASS.** + +### Task 3: Tool icons, options bar slot, active tool + +**Files:** +- Create: `src/areas/image-studio/imageOpIcons.tsx` +- Modify: `src/areas/image-studio/ImageOpsToolbar.tsx`, `src/areas/image-studio/ImageStudioPage.tsx` +- Modify: `src/areas/image-studio/imageOps.ts` (add `isTextField`), test in `imageOps.test.ts` + +**Interfaces:** +- Produces: + - `export function ImageOpIcon({ opId, size }: { opId: string; size?: number }): JSX.Element` — crop, remove_background, auto_frame icons; wand fallback. + - `export function isTextField(target: EventTarget | null): boolean` in `imageOps.ts` — true for `input` (non-button/checkbox/range types), `textarea`, `select`, `contentEditable`. + - `ImageOpsToolbar` props: `entries`, `selected`, `onResult`, `onActivity` (unchanged) plus `activeTool: string | null`, `onActiveToolChange: (id: string | null) => void`, `optionsSlot: HTMLElement | null`, `overlaySlot: HTMLElement | null`. + - Inside `ImageOpsToolbar.tsx`, `ImageOpControl` exposes to the crop UI (Task 4) a `start(params?: Record): Promise` (true when a result was added) and `running`, `busy`. Leave a single branch `op.id === 'crop'` that Task 4 fills; in this task crop uses the generic options. + - `Canvas` gets `hideToggles: boolean` and renders `
` above the image. + +- [ ] **Step 1: Failing test** in `imageOps.test.ts`: `isTextField` true for a stub `{ tagName: 'INPUT', type: 'number' }` and `{ tagName: 'TEXTAREA' }`, false for `{ tagName: 'INPUT', type: 'checkbox' }`, `{ tagName: 'BUTTON' }`, `null`. (Duck-typed: read `tagName`, `type`, `isContentEditable`.) +- [ ] **Step 2: Implement `isTextField`, run tests, PASS.** +- [ ] **Step 3: Page:** `activeTool` state (reset to null when `selected` is undefined); slots via `useState` callback refs; under `
` a `
`. "Add image" and "Show in folder" become icon-only buttons with `title` and `aria-label`; "Send to Generate" unchanged. Pass `hideToggles={activeTool === 'crop'}`. +- [ ] **Step 4: Toolbar:** each control renders an icon button in the header (`title={op.label}`, `aria-pressed`, accent styling when active, spinner while running, disabled when another op runs) toggling `onActiveToolChange`. When active, `createPortal` into `optionsSlot`: op label, `ParamFields` in a row (`flex items-center gap-3`), Apply button, and the `SetupCardView` (anchored to the bar). Esc on `window` (not in a text field) closes the active tool. +- [ ] **Step 5: Verify:** `npm run lint` 0, `npm run build` OK, `npm run test:node` PASS. + +### Task 4: Crop tool (overlay + options) + +**Files:** +- Create: `src/areas/image-studio/CropTool.tsx` +- Modify: `src/areas/image-studio/ImageOpsToolbar.tsx` (the `op.id === 'crop'` branch only) + +**Interfaces:** +- Consumes: Task 2 module; Task 3's `start`, `running`, `busy`, `optionsSlot`, `overlaySlot`, `isTextField`, `onActiveToolChange`; `runInputFor(entries, selected, 'crop')`. +- Produces: `export default function CropTool(props: { input: StudioImage; optionsSlot: HTMLElement | null; overlaySlot: HTMLElement | null; running: boolean; busy: boolean; onApply: (edges: { left: number; top: number; right: number; bottom: number }) => Promise; onCancel: () => void }): JSX.Element`. Rendered with `key={input.id}` so the frame resets when the input changes. + +- [ ] **Step 1: Overlay** (portal into `overlaySlot`): an opaque zinc-950 layer with the input's `` (object-contain); natural size from `onLoad`; displayed box computed from the container size via `ResizeObserver`; the frame drawn in screen px from the image rect; outside dimmed with four `bg-black/60` divs; 8 handles (8×8 px, white, with `cursor` per handle) plus the frame interior as `move`; pointerdown captures the pointer and records start rect; pointermove converts screen delta to image px (`/ scale`) and calls `dragRect`; thirds grid lines only while dragging. +- [ ] **Step 2: Options** (portal into `optionsSlot`): "Crop", a 3-way segmented control Free / 1:1 / Original (changing it applies `fitToRatio`), `{w} × {h} px`, Reset (`fullRect`), Cancel (`onCancel`), Apply (accent; disabled when `isFullRect` or `busy`; spinner while `running`). Enter applies, Esc cancels — ignoring text fields. +- [ ] **Step 3: Wire** in `ImageOpControl`: `onApply = (edges) => start(edges)`; on true, `onActiveToolChange(null)`. `onCancel = () => onActiveToolChange(null)`. +- [ ] **Step 4: Verify:** lint 0, build OK, all tests PASS; then run the app (`npm run dev`) and check crop end to end: drag edges/corners/move, ratios, resize the window mid-crop, apply → new history entry with the expected size, Esc cancels. diff --git a/docs/superpowers/specs/2026-11-18-image-studio-tools-design.md b/docs/superpowers/specs/2026-11-18-image-studio-tools-design.md new file mode 100644 index 00000000..fa2a12e9 --- /dev/null +++ b/docs/superpowers/specs/2026-11-18-image-studio-tools-design.md @@ -0,0 +1,61 @@ +# Image Studio: tool icons and interactive crop + +## Intent + +The Image Studio header is a wall of sliders: four crop percentages, edge +hardness, margin, resolution, each next to its own button. The maintainer wants +it to work like the Windows Photos editor: a row of tool icons, the options of +the active tool only, and a crop you do by dragging a frame on the image, then +confirming. + +## Goals + +- Header: title, one icon per image op, then Add image / Show in folder / Send to Generate. +- Clicking an icon makes it the active tool (highlighted). Clicking it again, or Esc, closes it. +- A thin options bar under the header shows the active tool's params and its action buttons. Nothing shows when no tool is active. +- Crop mode: a frame over the image with 8 handles (4 corners, 4 edges); dragging inside moves it; the image outside the frame is dimmed; a rule-of-thirds grid shows while dragging. The options bar holds the aspect ratio (Free, 1:1, Original), the result size in pixels, Reset, Cancel and Apply. Enter applies, Esc cancels. +- Applying writes a new file through the existing `crop` op and adds it to the history, as today. + +## Non-goals + +- No rotate, flip, zoom or pan of the canvas. +- No new image ops. +- No change to how results, history or "Send to Generate" work. + +## Anti-goals + +- A tool whose options cover the image being edited. +- Losing the generic toolbar: an op added to the backend registry must still appear (with a fallback icon and its params rendered by `ParamFields`) with no front-end change. + +## Approaches + +- **A. Popover under each icon.** Cleanest header, but the popover covers the image, and the crop's Apply/Cancel would float over the area being cropped. +- **B. Contextual options bar under the header (picked).** Matches Windows Photos, the reference the maintainer gave; one place for every tool's options and for the crop's Apply/Cancel; the image keeps the full width. +- **C. Side panel.** Familiar from pro tools, but takes width from the image permanently for three tools. + +The maintainer picked B. + +## Design + +### Backend (`api/services/image_ops`) + +- `crop` params stay `left`, `top`, `right`, `bottom` (percent of the side cut off each edge), but become `float`, `min 0`, `max 99`, `step 0.1`. The 45 % limit goes. +- `crop` raises `ImageOpInputError` when `left + right >= 100` or `top + bottom >= 100` (nothing left to keep). `framing.crop_box` already rounds to pixels and keeps at least 1 px. +- Tests in `api/tests/test_image_ops_framing.py` follow (the clamp test moves from 45 to 99, plus the new error). + +### Front end (`src/areas/image-studio`) + +- **Active tool state** lives in `ImageStudioPage` (`activeTool: string | null`), so the header icons, the options bar and the canvas agree. It resets to null when no image is selected. +- **Icons**: a map from op id to icon (`crop`, `remove_background`, `auto_frame`), with the current wand as the fallback for unknown ops. Each icon button has the op label as tooltip and `aria-pressed`. While an op runs, its icon shows a spinner and the other icons are disabled (the existing `RunLock`). +- **Options bar**: for a generic op, its `ParamFields` laid out in a row plus an Apply button; the one-time-download card (`SetupCardView`) anchors under this bar. The per-op state (params, setup card, readiness) keeps working as `ImageOpControl` does today; it is split so the icon and the options render in two places of the layout. +- **Crop** is the one op with its own UI, keyed by op id `crop`: + - `cropGeometry.ts`, pure and unit-tested: a rect in image pixels; drag of a handle or of the whole frame given a pointer delta in image pixels; clamping to the image; a minimum size (16 px or the image size if smaller); aspect-ratio lock (free, 1:1, original) applied from the handle being dragged; conversion to the op's four edge percentages. + - `CropOverlay.tsx`: drawn over the canvas image, maps screen to image pixels from the displayed `` box (object-contain), pointer events with capture, the dimmed outside, the thirds grid while dragging, handle cursors. + - The image cropped is `runInputFor(entries, selected, 'crop')`, as today: cropping a crop starts again from its source, so the overlay shows that source. The frame starts as the whole image, and resets when the selected image changes. + - While crop is active, the "What the model sees" and "Mask" toggles are hidden. +- **Keyboard**: Esc closes the active tool (cancels a crop); Enter applies the crop. Neither fires while the focus is in a text field. + +## Left to the builder + +- Exact SVG paths of the three icons, spacing and colours (follow the page's zinc/accent classes). +- How `ImageOpControl` is split (a hook per op, or a component rendered twice with a slot); the constraint is one source of state per op. From 0f697a17878ca04c3f80e58f3d0f0b3a01afd54e Mon Sep 17 00:00:00 2001 From: Lightning Pixel Date: Wed, 18 Nov 2026 13:32:25 +0100 Subject: [PATCH 2/8] feat(image-ops): let crop take fractional edge percentages --- api/services/image_ops/builtin.py | 19 ++++++++++--------- api/tests/test_image_ops_framing.py | 14 +++++++++++++- 2 files changed, 23 insertions(+), 10 deletions(-) diff --git a/api/services/image_ops/builtin.py b/api/services/image_ops/builtin.py index 83f5b71e..8ea8d704 100644 --- a/api/services/image_ops/builtin.py +++ b/api/services/image_ops/builtin.py @@ -102,11 +102,11 @@ def _edge_param(param_id: str, label: str) -> dict[str, Any]: return { "id": param_id, "label": label, - "type": "int", - "default": 0, - "min": 0, - "max": 45, - "step": 1, + "type": "float", + "default": 0.0, + "min": 0.0, + "max": 99.0, + "step": 0.1, "tooltip": f"Percentage of the image cut off the {param_id} edge.", } @@ -114,10 +114,11 @@ def _edge_param(param_id: str, label: str) -> dict[str, Any]: def crop(input_path: Path, params: Mapping[str, Any], context: ImageOpContext) -> ImageOpResult: image = load_image(input_path) image = image.convert("RGBA" if _has_alpha(image) else "RGB") - box = framing.crop_box( - image.width, image.height, - params.get("left", 0), params.get("top", 0), params.get("right", 0), params.get("bottom", 0), - ) + left, top = params.get("left", 0), params.get("top", 0) + right, bottom = params.get("right", 0), params.get("bottom", 0) + if left + right >= 100 or top + bottom >= 100: + raise ImageOpInputError("Nothing left to crop: the frame is empty.") + box = framing.crop_box(image.width, image.height, left, top, right, bottom) cropped = image.crop(box) (out_path,) = write_new_files(context.images_dir, sanitize_stem(input_path.name), [("crop", png_bytes(cropped))]) return ImageOpResult(path=out_path, details={"width": cropped.width, "height": cropped.height, "box": list(box)}) diff --git a/api/tests/test_image_ops_framing.py b/api/tests/test_image_ops_framing.py index 7d05fc3b..e4ea7996 100644 --- a/api/tests/test_image_ops_framing.py +++ b/api/tests/test_image_ops_framing.py @@ -127,7 +127,19 @@ def test_colour_key_transparency_is_honoured(self) -> None: self.assertEqual(_visible_box(framed), (0, 0, 512, 512)) def test_crop_edges_are_clamped(self) -> None: - self.assertEqual(image_ops_registry.resolve_params("crop", {"left": 90})["left"], 45) + self.assertEqual(image_ops_registry.resolve_params("crop", {"left": 150})["left"], 99.0) + + def test_crop_accepts_fractional_percentages(self) -> None: + path = self._save(Image.new("RGB", (1000, 500), (10, 20, 30)), "wide.png") + result = image_ops_registry.run("crop", path, {"left": 12.5, "top": 10.2}, self.context) + self.assertEqual(_open(result.path).size, (875, 449)) + + def test_crop_refuses_an_empty_box(self) -> None: + path = self._save(Image.new("RGB", (100, 100), (10, 20, 30)), "sq.png") + for params in ({"left": 60, "right": 40}, {"top": 60, "bottom": 40}): + with self.subTest(params=params): + with self.assertRaises(ImageOpInputError): + image_ops_registry.run("crop", path, params, self.context) def test_auto_frame_centers_an_off_center_cutout(self) -> None: cutout = Image.new("RGBA", (400, 300), (0, 0, 0, 0)) From 0046b78dbdd851806f616165581d4aa57968b21e Mon Sep 17 00:00:00 2001 From: Lightning Pixel Date: Wed, 18 Nov 2026 13:32:26 +0100 Subject: [PATCH 3/8] feat(image-studio): add the crop frame geometry --- package.json | 2 +- src/areas/image-studio/cropGeometry.test.ts | 65 ++++++++++ src/areas/image-studio/cropGeometry.ts | 132 ++++++++++++++++++++ 3 files changed, 198 insertions(+), 1 deletion(-) create mode 100644 src/areas/image-studio/cropGeometry.test.ts create mode 100644 src/areas/image-studio/cropGeometry.ts diff --git a/package.json b/package.json index c641af68..605c5726 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,7 @@ "prepare-resources": "node scripts/download-python-embed.js", "test": "npm run test:py && npm run test:node", "test:py": "node scripts/run-pytests.mjs", - "test:node": "node --test --experimental-strip-types --experimental-loader ./scripts/node-ts-extensionless-loader.mjs src/shared/types/assetLibrary.test.ts src/areas/generate/assetLibraryProjection.test.ts src/areas/generate/assetLibraryService.test.ts src/areas/generate/assetLibraryUi.test.ts src/areas/library/libraryView.test.ts src/areas/library/gridWindow.test.ts src/areas/generate/orcaSlicerLink.test.ts src/shared/utils/agentStream.test.ts src/shared/thumbnails/assetThumbnailQueue.test.ts src/shared/thumbnails/assetThumbnailStore.test.ts src/shared/components/agent/clientTools.test.ts src/shared/components/agent/agentContext.test.ts src/shared/utils/ollamaHealth.test.ts src/shared/utils/notification.test.ts src/shared/utils/agentConversations.test.ts electron/main/artifact-registry-service.test.ts electron/main/asset-thumbnail-cache.test.ts electron/main/extension-path-guard.test.ts electron/main/storage-directory-guard.test.ts electron/main/storage-ownership.test.ts electron/main/startup-error.test.ts electron/main/api-port.test.ts electron/main/api-guard.test.ts electron/main/agent-conversations.test.ts electron/main/gpu-memory.test.ts electron/preload/artifact-registry-preload.test.ts src/shared/stores/meshHistory.test.ts src/areas/generate/meshEditPanel.test.ts src/areas/generate/sculpt/SculptMesh.test.ts src/areas/generate/sculpt/SculptMesh.perf.test.ts src/areas/generate/sculpt/sculptLogic.test.ts src/shared/pages/pageRegistry.test.ts src/shared/pages/startPage.test.ts src/areas/home/recents.test.ts src/areas/workflows/workflowRunRecord.test.ts src/areas/queue/queueModel.test.ts electron/main/workspace-images.test.ts src/areas/image-studio/imageStudioStore.test.ts src/areas/image-studio/imageOps.test.ts src/shared/utils/imageInput.test.ts src/areas/print/printBed.test.ts src/shared/three/viewScale.test.ts src/areas/workflows/nodes/mesh-exporter/obj.test.ts && node --test electron/main/*.test.mjs src/**/*.test.mjs", + "test:node": "node --test --experimental-strip-types --experimental-loader ./scripts/node-ts-extensionless-loader.mjs src/shared/types/assetLibrary.test.ts src/areas/generate/assetLibraryProjection.test.ts src/areas/generate/assetLibraryService.test.ts src/areas/generate/assetLibraryUi.test.ts src/areas/library/libraryView.test.ts src/areas/library/gridWindow.test.ts src/areas/generate/orcaSlicerLink.test.ts src/shared/utils/agentStream.test.ts src/shared/thumbnails/assetThumbnailQueue.test.ts src/shared/thumbnails/assetThumbnailStore.test.ts src/shared/components/agent/clientTools.test.ts src/shared/components/agent/agentContext.test.ts src/shared/utils/ollamaHealth.test.ts src/shared/utils/notification.test.ts src/shared/utils/agentConversations.test.ts electron/main/artifact-registry-service.test.ts electron/main/asset-thumbnail-cache.test.ts electron/main/extension-path-guard.test.ts electron/main/storage-directory-guard.test.ts electron/main/storage-ownership.test.ts electron/main/startup-error.test.ts electron/main/api-port.test.ts electron/main/api-guard.test.ts electron/main/agent-conversations.test.ts electron/main/gpu-memory.test.ts electron/preload/artifact-registry-preload.test.ts src/shared/stores/meshHistory.test.ts src/areas/generate/meshEditPanel.test.ts src/areas/generate/sculpt/SculptMesh.test.ts src/areas/generate/sculpt/SculptMesh.perf.test.ts src/areas/generate/sculpt/sculptLogic.test.ts src/shared/pages/pageRegistry.test.ts src/shared/pages/startPage.test.ts src/areas/home/recents.test.ts src/areas/workflows/workflowRunRecord.test.ts src/areas/queue/queueModel.test.ts electron/main/workspace-images.test.ts src/areas/image-studio/imageStudioStore.test.ts src/areas/image-studio/imageOps.test.ts src/areas/image-studio/cropGeometry.test.ts src/shared/utils/imageInput.test.ts src/areas/print/printBed.test.ts src/shared/three/viewScale.test.ts src/areas/workflows/nodes/mesh-exporter/obj.test.ts && node --test electron/main/*.test.mjs src/**/*.test.mjs", "package": "cross-env CSC_IDENTITY_AUTO_DISCOVERY=false npm run build && npm run prepare-resources && electron-builder", "package:mac": "cross-env CSC_IDENTITY_AUTO_DISCOVERY=false npm run build && npm run prepare-resources && electron-builder --mac --arm64", "lint": "eslint ." diff --git a/src/areas/image-studio/cropGeometry.test.ts b/src/areas/image-studio/cropGeometry.test.ts new file mode 100644 index 00000000..5c351f02 --- /dev/null +++ b/src/areas/image-studio/cropGeometry.test.ts @@ -0,0 +1,65 @@ +import test from 'node:test' +import assert from 'node:assert/strict' +import { + aspectRatio, cropEdges, dragRect, fitToRatio, fullRect, isFullRect, minCropSize, type Rect, +} from './cropGeometry' + +const S = { width: 200, height: 100 } +const sub = (r: Rect, keys: (keyof Rect)[]) => Object.fromEntries(keys.map((k) => [k, r[k]])) + +test('fullRect covers the image and isFullRect recognizes it', () => { + assert.deepEqual(fullRect(S), { x: 0, y: 0, w: 200, h: 100 }) + assert.equal(isFullRect(fullRect(S), S), true) + assert.equal(isFullRect({ x: 1, y: 0, w: 199, h: 100 }, S), false) +}) + +test('move translates and clamps inside the image', () => { + const start = { x: 10, y: 10, w: 100, h: 50 } + assert.deepEqual(dragRect(start, 'move', 50, 50, S, null), { x: 60, y: 50, w: 100, h: 50 }) + assert.equal(dragRect(start, 'move', 500, 0, S, null).x, 100) + assert.equal(dragRect(start, 'move', -500, -500, S, null).x, 0) +}) + +test('free edge handles move only the dragged edge', () => { + const sq = { x: 0, y: 0, w: 100, h: 100 } + assert.equal(dragRect(sq, 'e', 30, 0, S, null).w, 130) + assert.deepEqual(sub(dragRect(sq, 'w', 95, 0, S, null), ['x', 'w']), { x: 84, w: 16 }) +}) + +test('free corners clamp to the image and respect the opposite corner', () => { + const r = dragRect({ x: 0, y: 0, w: 50, h: 50 }, 'se', 500, 500, S, null) + assert.deepEqual(sub(r, ['w', 'h']), { w: 200, h: 100 }) + assert.deepEqual(dragRect({ x: 10, y: 10, w: 50, h: 50 }, 'nw', -20, -20, S, null), { x: 0, y: 0, w: 60, h: 60 }) +}) + +test('ratio corner uses the larger proposed dimension and fits the image', () => { + const start = { x: 0, y: 0, w: 50, h: 50 } + assert.deepEqual(sub(dragRect(start, 'se', 40, 10, S, 1), ['w', 'h']), { w: 90, h: 90 }) + assert.deepEqual(sub(dragRect(start, 'se', 300, 300, S, 1), ['w', 'h']), { w: 100, h: 100 }) +}) + +test('ratio edge changes one dimension and centers the other', () => { + const r = dragRect({ x: 50, y: 25, w: 50, h: 50 }, 'e', 20, 0, S, 1) + assert.deepEqual(sub(r, ['x', 'w', 'h']), { x: 50, w: 70, h: 70 }) + assert.ok(r.y >= 0 && r.y <= 30) + assert.equal(r.y, 15) +}) + +test('fitToRatio and aspectRatio', () => { + assert.deepEqual(fitToRatio({ x: 0, y: 0, w: 200, h: 100 }, 1, S), { x: 50, y: 0, w: 100, h: 100 }) + const rect = { x: 5, y: 5, w: 30, h: 20 } + assert.equal(fitToRatio(rect, null, S), rect) + assert.equal(aspectRatio('original', S), 2) + assert.equal(aspectRatio('free', S), null) + assert.equal(aspectRatio('square', S), 1) +}) + +test('cropEdges returns percentages', () => { + assert.deepEqual(cropEdges({ x: 20, y: 10, w: 100, h: 50 }, S), { left: 10, top: 10, right: 40, bottom: 40 }) +}) + +test('min size never exceeds a tiny image', () => { + const tiny = { width: 8, height: 4 } + assert.deepEqual(minCropSize(tiny), { w: 8, h: 4 }) + assert.deepEqual(sub(dragRect(fullRect(tiny), 'w', 100, 0, tiny, null), ['x', 'w']), { x: 0, w: 8 }) +}) diff --git a/src/areas/image-studio/cropGeometry.ts b/src/areas/image-studio/cropGeometry.ts new file mode 100644 index 00000000..f943aef4 --- /dev/null +++ b/src/areas/image-studio/cropGeometry.ts @@ -0,0 +1,132 @@ +export interface ImageSize { width: number; height: number } +/** Integer image pixels. */ +export interface Rect { x: number; y: number; w: number; h: number } +export type Handle = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw' | 'move' +export type AspectMode = 'free' | 'square' | 'original' + +export const MIN_CROP_PX = 16 + +const clamp = (v: number, lo: number, hi: number): number => Math.min(Math.max(v, lo), Math.max(lo, hi)) + +export function fullRect(size: ImageSize): Rect { + return { x: 0, y: 0, w: size.width, h: size.height } +} + +export function minCropSize(size: ImageSize): { w: number; h: number } { + return { w: Math.min(MIN_CROP_PX, size.width), h: Math.min(MIN_CROP_PX, size.height) } +} + +/** w / h of the mode, or null when free. */ +export function aspectRatio(mode: AspectMode, size: ImageSize): number | null { + if (mode === 'square') return 1 + if (mode === 'original') return size.width / size.height + return null +} + +/** Largest rect of `ratio` inside `rect`, centered on it. */ +export function fitToRatio(rect: Rect, ratio: number | null, _size: ImageSize): Rect { + if (ratio === null) return rect + let w = rect.w + let h = Math.round(w / ratio) + if (h > rect.h) { + h = rect.h + w = Math.round(h * ratio) + } + w = Math.min(w, rect.w) + return { + x: rect.x + Math.round((rect.w - w) / 2), + y: rect.y + Math.round((rect.h - h) / 2), + w, + h, + } +} + +export function dragRect( + start: Rect, handle: Handle, dx: number, dy: number, size: ImageSize, ratio: number | null, +): Rect { + const W = size.width + const H = size.height + const min = minCropSize(size) + + if (handle === 'move') { + return { + x: clamp(Math.round(start.x + dx), 0, W - start.w), + y: clamp(Math.round(start.y + dy), 0, H - start.h), + w: start.w, + h: start.h, + } + } + + const hasE = handle.includes('e') + const hasW = handle.includes('w') + const hasN = handle.includes('n') + const hasS = handle.includes('s') + const isCorner = (hasE || hasW) && (hasN || hasS) + + if (ratio === null) { + let l = start.x + let r = start.x + start.w + let t = start.y + let b = start.y + start.h + if (hasE) r = clamp(Math.round(r + dx), l + min.w, W) + if (hasW) l = clamp(Math.round(l + dx), 0, r - min.w) + if (hasS) b = clamp(Math.round(b + dy), t + min.h, H) + if (hasN) t = clamp(Math.round(t + dy), 0, b - min.h) + return { x: l, y: t, w: r - l, h: b - t } + } + + const minW = Math.max(min.w, min.h * ratio) + + if (isCorner) { + const ax = hasE ? start.x : start.x + start.w + const ay = hasS ? start.y : start.y + start.h + const pw = hasE ? start.w + dx : start.w - dx + const ph = hasS ? start.h + dy : start.h - dy + const maxW = Math.min(hasE ? W - ax : ax, (hasS ? H - ay : ay) * ratio) + const w = Math.round(clamp(Math.max(pw, ph * ratio), minW, maxW)) + const h = Math.min(Math.round(w / ratio), hasS ? H - ay : ay) + return { x: hasE ? ax : ax - w, y: hasS ? ay : ay - h, w, h } + } + + if (hasE || hasW) { + const pw = hasE ? start.w + dx : start.w - dx + const maxW = Math.min(hasE ? W - start.x : start.x + start.w, H * ratio) + const w = Math.round(clamp(pw, minW, maxW)) + const h = Math.min(Math.round(w / ratio), H) + const cy = start.y + start.h / 2 + return { + x: hasE ? start.x : start.x + start.w - w, + y: clamp(Math.round(cy - h / 2), 0, H - h), + w, + h, + } + } + + // n / s + const minH = Math.max(min.h, min.w / ratio) + const ph = hasS ? start.h + dy : start.h - dy + const maxH = Math.min(hasS ? H - start.y : start.y + start.h, W / ratio) + const h = Math.round(clamp(ph, minH, maxH)) + const w = Math.min(Math.round(h * ratio), W) + const cx = start.x + start.w / 2 + return { + x: clamp(Math.round(cx - w / 2), 0, W - w), + y: hasS ? start.y : start.y + start.h - h, + w, + h, + } +} + +/** Crop margins as percentages of the image. */ +export function cropEdges(rect: Rect, size: ImageSize): { left: number; top: number; right: number; bottom: number } { + return { + left: (rect.x / size.width) * 100, + top: (rect.y / size.height) * 100, + right: ((size.width - rect.x - rect.w) / size.width) * 100, + bottom: ((size.height - rect.y - rect.h) / size.height) * 100, + } +} + +export function isFullRect(rect: Rect, size: ImageSize): boolean { + return rect.x === 0 && rect.y === 0 && rect.w === size.width && rect.h === size.height +} From fb399baad30416ffe9bd3c6db7ec08d5d3516946 Mon Sep 17 00:00:00 2001 From: Lightning Pixel Date: Wed, 18 Nov 2026 13:39:31 +0100 Subject: [PATCH 4/8] feat(image-studio): show the image ops as tool icons with an options bar --- src/areas/image-studio/ImageOpsToolbar.tsx | 151 ++++++++++++++++----- src/areas/image-studio/ImageStudioPage.tsx | 61 ++++++--- src/areas/image-studio/imageOpIcons.tsx | 21 +++ src/areas/image-studio/imageOps.test.ts | 15 ++ src/areas/image-studio/imageOps.ts | 17 +++ 5 files changed, 212 insertions(+), 53 deletions(-) create mode 100644 src/areas/image-studio/imageOpIcons.tsx diff --git a/src/areas/image-studio/ImageOpsToolbar.tsx b/src/areas/image-studio/ImageOpsToolbar.tsx index 1b2d7171..f90162d2 100644 --- a/src/areas/image-studio/ImageOpsToolbar.tsx +++ b/src/areas/image-studio/ImageOpsToolbar.tsx @@ -1,4 +1,5 @@ import { useEffect, useRef, useState } from 'react' +import { createPortal } from 'react-dom' import { useAppStore } from '@shared/stores/appStore' import { ParamFields } from '@shared/components/ui/ParamFields' import { SseProgressBar } from '@shared/components/ui/SseProgressBar' @@ -10,6 +11,7 @@ import { cardForStatus, createRunLock, failInstall, + isTextField, opCopy, runInputFor, setupMessage, @@ -19,6 +21,7 @@ import { type RunLock, type SetupCard, } from './imageOps' +import { ImageOpIcon } from './imageOpIcons' import { ImageOpNotReadyError, getImageOpStatus, listImageOps, prepareImageOp, runImageOpOnFile } from './imageOpsApi' // Image operations served by the backend (GET /image/ops: background removal, @@ -43,11 +46,21 @@ interface ToolbarProps { selected: StudioImage onResult: (result: ImageOpResult, source: StudioImage) => Promise onActivity: (activity: ImageOpActivity | null) => void + /** Id of the op whose options show, or null when no tool is open. */ + activeTool: string | null + onActiveToolChange: (id: string | null) => void + /** The options bar under the header: the active op renders its options there. */ + optionsSlot: HTMLElement | null + /** A layer over the canvas image, for a tool that draws on it (crop). */ + overlaySlot: HTMLElement | null } const BUTTON_CLASS = 'flex items-center gap-1.5 rounded-lg border border-zinc-800 bg-zinc-900/60 px-3 py-1.5 text-xs font-medium text-zinc-300 transition-colors hover:border-zinc-700 hover:text-zinc-100 disabled:opacity-50' +const ICON_BUTTON_CLASS = + 'flex h-8 w-8 items-center justify-center rounded-lg border transition-colors disabled:cursor-not-allowed disabled:opacity-40' + function Spinner({ size = 14 }: { size?: number }): JSX.Element { return (
+
{ops.map((op) => ( ))} +
) } -function ImageOpControl({ op, lock, blocked, entries, selected, onResult, onActivity }: ToolbarProps & { +/** What a run processes: the input file, the entry selected when it was asked, and its params when they override the options bar's. */ +interface RunTarget { + input: StudioImage + selectedId: string + params?: Record +} + +/** + * One op: its header icon and, while it is the active tool, its options in + * the options bar. All of the op's state (params, setup download, readiness) + * lives here, so closing and reopening the tool keeps it. + */ +function ImageOpControl(props: ToolbarProps & { op: ImageOpDescriptor /** Shared by all the ops: one runs at a time. */ lock: RunLock /** Another op is running. */ blocked: boolean }): JSX.Element { + const { op, lock, blocked, entries, selected, onResult, onActivity, activeTool, onActiveToolChange, optionsSlot } = props const showError = useAppStore((s) => s.showError) const showToast = useAppStore((s) => s.showToast) const [params, setParams] = useState>(() => defaultParamValues(op.params_schema)) @@ -107,28 +143,42 @@ function ImageOpControl({ op, lock, blocked, entries, selected, onResult, onActi const [running, setRunning] = useState(false) /** Set once the op answered ready, so later clicks skip the status check. */ const ready = useRef(false) - /** The image the user asked to process, kept across the setup download. */ - const pending = useRef<{ input: StudioImage, selectedId: string } | null>(null) + /** The run the user asked for, kept across the setup download. */ + const pending = useRef(null) const copy = opCopy(op) + const active = activeTool === op.id + + // Closing the tool drops a download offer not taken up; an install under way keeps going. + useEffect(() => { + if (active) return + if (card.phase === 'confirm' || card.phase === 'error') { + pending.current = null + setCard(HIDDEN_CARD) + } + }, [active, card.phase]) - async function run(input: StudioImage, selectedId: string) { + /** True when a result was added to the history. */ + async function run(target: RunTarget): Promise { + const { input, selectedId } = target if (!lock.claim(op.id)) { showToast('Wait for the current image operation to finish') - return + return false } setRunning(true) onActivity({ ids: [selectedId, input.id], label: copy.running }) try { - const result = await runImageOpOnFile(op.id, input.path, paramsRef.current) + const result = await runImageOpOnFile(op.id, input.path, target.params ?? paramsRef.current) await onResult({ op: op.id, path: result.path, maskPath: result.maskPath }, input) + return true } catch (err) { if (err instanceof ImageOpNotReadyError) { ready.current = false - pending.current = { input, selectedId } + pending.current = target await checkSetup() } else { showError(err instanceof Error ? err.message : String(err)) } + return false } finally { setRunning(false) onActivity(null) @@ -151,11 +201,18 @@ function ImageOpControl({ op, lock, blocked, entries, selected, onResult, onActi } } - async function start() { - if (running || card.phase === 'installing' || card.phase === 'checking') return - const target = { input: runInputFor(entries, selected, op.id), selectedId: selected.id } + /** + * Runs the op on the selected image, with `override` as its params when + * given (else the options bar's). True when a result was added; false when + * it did not run, failed, or now waits for the one-time download (the run + * then happens, with the same params, once the download is done). + */ + async function start(override?: Record): Promise { + if (running || card.phase === 'installing' || card.phase === 'checking') return false + const target: RunTarget = { input: runInputFor(entries, selected, op.id), selectedId: selected.id, params: override } pending.current = target - if (ready.current || await checkSetup()) await run(target.input, target.selectedId) + if (ready.current || await checkSetup()) return run(target) + return false } async function download() { @@ -187,34 +244,56 @@ function ImageOpControl({ op, lock, blocked, entries, selected, onResult, onActi setCard(HIDDEN_CARD) const target = pending.current pending.current = null - if (target) await run(target.input, target.selectedId) + if (target) await run(target) } const busy = running || blocked || card.phase === 'checking' || card.phase === 'installing' - return ( -
+ const genericOptions = ( + <> + {op.label} setParams((current) => ({ ...current, [id]: value }))} disabled={running} - // Crop's four edges sit in two columns to keep the header short. - className={op.params_schema.length > 2 ? 'grid w-80 grid-cols-2 gap-x-3 gap-y-1' : 'flex w-52 flex-col gap-1'} + className="flex flex-wrap items-center gap-3 [&>*]:w-52" /> - + + ) + + // CROP_UI: crop is the one op with its own UI. Task 4 replaces this branch with + // + // Until then crop falls through to the generic options. + const options = op.id === 'crop' ? genericOptions : genericOptions - {card.phase !== 'hidden' && card.phase !== 'checking' && ( - { void download() }} - onClose={() => { pending.current = null; setCard(HIDDEN_CARD) }} - /> + return ( + <> + + + {active && optionsSlot && createPortal( + <> + {options} + {card.phase !== 'hidden' && card.phase !== 'checking' && ( + { void download() }} + onClose={() => { pending.current = null; setCard(HIDDEN_CARD) }} + /> + )} + , + optionsSlot, )} -
+ ) } diff --git a/src/areas/image-studio/ImageStudioPage.tsx b/src/areas/image-studio/ImageStudioPage.tsx index dd669b5d..227b2212 100644 --- a/src/areas/image-studio/ImageStudioPage.tsx +++ b/src/areas/image-studio/ImageStudioPage.tsx @@ -24,6 +24,9 @@ const ICONS = { close: 'M6 6l12 12M18 6 6 18', } +const ICON_BUTTON_CLASS = + 'flex h-8 w-8 items-center justify-center rounded-lg border border-zinc-800 bg-zinc-900/60 text-zinc-300 transition-colors hover:border-zinc-700 hover:text-zinc-100 disabled:opacity-50' + const PASTE_HINT = typeof navigator !== 'undefined' && /mac/i.test(navigator.platform) ? '⌘V' : 'Ctrl+V' /** Transparent pixels show as a checkerboard, as in image editors. */ @@ -89,10 +92,19 @@ function ModelView({ image }: { image: StudioImage }): JSX.Element { ) } -function Canvas({ image, activity }: { image: StudioImage, activity: string | null }): JSX.Element { +function Canvas({ image, activity, hideToggles, onOverlaySlot }: { + image: StudioImage + activity: string | null + /** A tool draws over the image (crop): the view toggles would sit in its way. */ + hideToggles: boolean + /** Receives the layer over the image that the active tool can draw into. */ + onOverlaySlot: (element: HTMLDivElement | null) => void +}): JSX.Element { const [maskFor, setMaskFor] = useState(null) const [modelView, setModelView] = useState(false) - const showMask = Boolean(image.maskPath) && maskFor === image.id + // With the toggles hidden, so is what they switch: the tool works on the plain image. + const showMask = !hideToggles && Boolean(image.maskPath) && maskFor === image.id + const showModelView = !hideToggles && modelView const mask = useMaskPreview(showMask ? image.maskPath : undefined) let content: JSX.Element @@ -100,7 +112,7 @@ function Canvas({ image, activity }: { image: StudioImage, activity: string | nu content = mask.url ? {`Mask : {mask.failed ? 'Could not load the mask' : 'Loading mask…'} - } else if (modelView) { + } else if (showModelView) { content = } else { content = {image.name} @@ -109,12 +121,13 @@ function Canvas({ image, activity }: { image: StudioImage, activity: string | nu return (
{content} - - {image.maskPath && ( + } + {!hideToggles && image.maskPath && (
- {selected && } + {selected && ( + + )} - {selected && ( - )}
+ {/* The active tool's options; ImageOpsToolbar portals them in. Hidden while empty. */} +
+ {selected - ? -: } + ? + : } {entries.length > 0 && (
diff --git a/src/areas/image-studio/imageOpIcons.tsx b/src/areas/image-studio/imageOpIcons.tsx new file mode 100644 index 00000000..2ccf1f71 --- /dev/null +++ b/src/areas/image-studio/imageOpIcons.tsx @@ -0,0 +1,21 @@ +// Header icons of the image ops, keyed by op id. An op the front end does not +// know yet (added to the backend registry) gets the wand. + +const PATHS: Record = { + // Two crossing corner marks, as in photo editors. + crop: 'M6 2v14a2 2 0 0 0 2 2h14M2 6h14a2 2 0 0 1 2 2v14', + // A subject cut out of a dashed backdrop. + remove_background: 'M4 4h2M10 4h4M18 4h2v2M20 10v4M20 18v2h-2M14 20h-4M6 20H4v-2M4 14v-4M4 6V4M12 8a2.5 2.5 0 1 1 0 5 2.5 2.5 0 0 1 0-5zM7.5 17.5a4.5 4.5 0 0 1 9 0', + // Viewfinder corners around a centred square. + auto_frame: 'M3 8V5a2 2 0 0 1 2-2h3M16 3h3a2 2 0 0 1 2 2v3M21 16v3a2 2 0 0 1-2 2h-3M8 21H5a2 2 0 0 1-2-2v-3M9 9h6v6H9z', +} + +const WAND = 'M15 4V2M15 16v-2M8 9h2M20 9h2M17.8 11.8 19 13M17.8 6.2 19 5M3 21l9-9M12.2 6.2 11 5' + +export function ImageOpIcon({ opId, size = 16 }: { opId: string, size?: number }): JSX.Element { + return ( + + ) +} diff --git a/src/areas/image-studio/imageOps.test.ts b/src/areas/image-studio/imageOps.test.ts index 95edf096..da9e19fd 100644 --- a/src/areas/image-studio/imageOps.test.ts +++ b/src/areas/image-studio/imageOps.test.ts @@ -8,6 +8,7 @@ import { createRunLock, failInstall, isOutsideWorkspace, + isTextField, modelViewCaption, notReadyMissing, opCopy, @@ -181,3 +182,17 @@ test('isOutsideWorkspace recognises only the 403 outside_workspace', () => { assert.equal(isOutsideWorkspace({ response: { status: 400, data: { detail: { code: 'outside_workspace' } } } }), false) assert.equal(isOutsideWorkspace(new Error('boom')), false) }) + +// ─── Keyboard focus ─────────────────────────────────────────────────────────── + +test('isTextField is true only where typing goes', () => { + const target = (stub: object) => stub as unknown as EventTarget + assert.equal(isTextField(target({ tagName: 'INPUT', type: 'number' })), true) + assert.equal(isTextField(target({ tagName: 'TEXTAREA' })), true) + assert.equal(isTextField(target({ tagName: 'SELECT' })), true) + assert.equal(isTextField(target({ tagName: 'DIV', isContentEditable: true })), true) + assert.equal(isTextField(target({ tagName: 'INPUT', type: 'checkbox' })), false) + assert.equal(isTextField(target({ tagName: 'INPUT', type: 'range' })), false) + assert.equal(isTextField(target({ tagName: 'BUTTON' })), false) + assert.equal(isTextField(null), false) +}) diff --git a/src/areas/image-studio/imageOps.ts b/src/areas/image-studio/imageOps.ts index 7e402d49..9a972dcc 100644 --- a/src/areas/image-studio/imageOps.ts +++ b/src/areas/image-studio/imageOps.ts @@ -212,3 +212,20 @@ export function notReadyMissing(err: unknown): SetupStep[] | null { if (!detail || typeof detail !== 'object' || (detail as { code?: unknown }).code !== 'not_ready') return null return knownSteps((detail as { missing?: unknown }).missing) } + +// ─── Keyboard ───────────────────────────────────────────────────────────────── + +/** Input types that take no typing: a shortcut key pressed on one still belongs to the page. */ +const NON_TEXT_INPUTS = new Set(['button', 'checkbox', 'radio', 'range', 'reset', 'submit', 'image', 'color', 'file']) + +/** Whether a key event's target is a field the user types in (page shortcuts must not fire there). Duck-typed so it runs without a DOM. */ +export function isTextField(target: EventTarget | null): boolean { + if (!target || typeof target !== 'object') return false + const el = target as { tagName?: unknown, type?: unknown, isContentEditable?: unknown } + if (el.isContentEditable === true) return true + const tag = typeof el.tagName === 'string' ? el.tagName.toUpperCase() : '' + if (tag === 'TEXTAREA' || tag === 'SELECT') return true + if (tag !== 'INPUT') return false + const type = typeof el.type === 'string' ? el.type.toLowerCase() : 'text' + return !NON_TEXT_INPUTS.has(type) +} From 76d947674baf45d0083777d560fc7555ae337d05 Mon Sep 17 00:00:00 2001 From: Lightning Pixel Date: Wed, 18 Nov 2026 13:44:53 +0100 Subject: [PATCH 5/8] feat(image-studio): crop by dragging a frame on the image --- src/areas/image-studio/CropTool.tsx | 296 +++++++++++++++++++++ src/areas/image-studio/ImageOpsToolbar.tsx | 23 +- 2 files changed, 313 insertions(+), 6 deletions(-) create mode 100644 src/areas/image-studio/CropTool.tsx diff --git a/src/areas/image-studio/CropTool.tsx b/src/areas/image-studio/CropTool.tsx new file mode 100644 index 00000000..067aede0 --- /dev/null +++ b/src/areas/image-studio/CropTool.tsx @@ -0,0 +1,296 @@ +import { useCallback, useEffect, useRef, useState } from 'react' +import type { PointerEvent as ReactPointerEvent } from 'react' +import { createPortal } from 'react-dom' +import type { StudioImage } from './imageStudioStore' +import { isTextField } from './imageOps' +import { + aspectRatio, + cropEdges, + dragRect, + fitToRatio, + fullRect, + isFullRect, + type AspectMode, + type Handle, + type ImageSize, + type Rect, +} from './cropGeometry' + +// The crop tool: a frame drawn over the image (in the canvas overlay slot) and +// its options (in the options bar). The frame lives in integer image pixels; +// the overlay maps it to screen pixels from the displayed, object-contain box. + +export type CropEdges = { left: number; top: number; right: number; bottom: number } + +interface CropToolProps { + /** The image cropped: its source when the selection is itself a crop. */ + input: StudioImage + optionsSlot: HTMLElement | null + overlaySlot: HTMLElement | null + running: boolean + busy: boolean + /** Runs the crop; true when the result was added to the history. */ + onApply: (edges: CropEdges) => Promise + onCancel: () => void +} + +/** Where the image is drawn inside the overlay: object-contain, centered. */ +interface ImageBox { left: number; top: number; scale: number } + +const HANDLES: { handle: Exclude; x: 0 | 0.5 | 1; y: 0 | 0.5 | 1; cursor: string }[] = [ + { handle: 'nw', x: 0, y: 0, cursor: 'nwse-resize' }, + { handle: 'n', x: 0.5, y: 0, cursor: 'ns-resize' }, + { handle: 'ne', x: 1, y: 0, cursor: 'nesw-resize' }, + { handle: 'e', x: 1, y: 0.5, cursor: 'ew-resize' }, + { handle: 'se', x: 1, y: 1, cursor: 'nwse-resize' }, + { handle: 's', x: 0.5, y: 1, cursor: 'ns-resize' }, + { handle: 'sw', x: 0, y: 1, cursor: 'nesw-resize' }, + { handle: 'w', x: 0, y: 0.5, cursor: 'ew-resize' }, +] + +const MODES: { mode: AspectMode; label: string }[] = [ + { mode: 'free', label: 'Free' }, + { mode: 'square', label: '1:1' }, + { mode: 'original', label: 'Original' }, +] + +function imageBox(container: { width: number; height: number }, size: ImageSize): ImageBox | null { + if (container.width <= 0 || container.height <= 0) return null + const scale = Math.min(container.width / size.width, container.height / size.height) + return { + left: (container.width - size.width * scale) / 2, + top: (container.height - size.height * scale) / 2, + scale, + } +} + +/** Size of an element, kept up to date as it resizes. */ +function useElementSize(element: HTMLElement | null): { width: number; height: number } { + const [size, setSize] = useState({ width: 0, height: 0 }) + useEffect(() => { + if (!element) return + const measure = () => setSize({ width: element.clientWidth, height: element.clientHeight }) + measure() + const observer = new ResizeObserver(measure) + observer.observe(element) + return () => observer.disconnect() + }, [element]) + return size +} + +export default function CropTool({ input, optionsSlot, overlaySlot, running, busy, onApply, onCancel }: CropToolProps): JSX.Element { + const [size, setSize] = useState(null) + const [rect, setRect] = useState(null) + const [mode, setMode] = useState('free') + const sizeRef = useRef(null) + + // The frame starts as the whole image, and starts again if the image's size changes. + const onImageSize = useCallback((natural: ImageSize) => { + const current = sizeRef.current + if (natural.width <= 0 || natural.height <= 0) return + if (current && current.width === natural.width && current.height === natural.height) return + sizeRef.current = natural + setSize(natural) + setRect(fullRect(natural)) + setMode('free') + }, []) + + const canApply = size !== null && rect !== null && !isFullRect(rect, size) && !busy + + const apply = useCallback(() => { + if (!canApply || !size || !rect) return + void onApply(cropEdges(rect, size)) + }, [canApply, size, rect, onApply]) + + // Enter applies, Esc cancels. Capture phase, so this runs before the + // toolbar's Esc listener, which skips events already handled. + const keys = useRef({ apply, onCancel }) + keys.current = { apply, onCancel } + useEffect(() => { + const onKeyDown = (event: KeyboardEvent) => { + if (event.defaultPrevented || isTextField(event.target)) return + if (event.key === 'Escape') { + event.preventDefault() + keys.current.onCancel() + } else if (event.key === 'Enter' && !event.repeat) { + // Also keeps Enter from clicking the focused button (a ratio, Reset…). + event.preventDefault() + keys.current.apply() + } + } + window.addEventListener('keydown', onKeyDown, true) + return () => window.removeEventListener('keydown', onKeyDown, true) + }, []) + + function changeMode(next: AspectMode) { + setMode(next) + if (size) setRect((current) => current && fitToRatio(current, aspectRatio(next, size), size)) + } + + function reset() { + if (!size) return + setMode('free') + setRect(fullRect(size)) + } + + return ( + <> + {overlaySlot && createPortal( + , + overlaySlot, + )} + {optionsSlot && createPortal( + <> + Crop +
+ {MODES.map(({ mode: m, label }) => ( + + ))} +
+ + {rect ? `${rect.w} × ${rect.h} px` : '…'} + +
+ + + +
+ , + optionsSlot, + )} + + ) +} + +/** A drag in progress: what was grabbed, where, and the frame at that moment. */ +interface Drag { handle: Handle; pointerId: number; x: number; y: number; start: Rect } + +function CropOverlay({ input, size, rect, ratio, locked, onImageSize, onRectChange }: { + input: StudioImage + size: ImageSize | null + rect: Rect | null + ratio: number | null + /** No dragging (the crop is running). */ + locked: boolean + onImageSize: (size: ImageSize) => void + onRectChange: (rect: Rect) => void +}): JSX.Element { + const [container, setContainer] = useState(null) + const containerSize = useElementSize(container) + const imgRef = useRef(null) + const drag = useRef(null) + const [dragging, setDragging] = useState(false) + + // A cached image can be complete before onLoad is attached. + useEffect(() => { + const img = imgRef.current + if (img?.complete && img.naturalWidth > 0) onImageSize({ width: img.naturalWidth, height: img.naturalHeight }) + }, [onImageSize]) + + const box = size ? imageBox(containerSize, size) : null + + function onPointerDown(handle: Handle, event: ReactPointerEvent) { + if (locked || !rect || event.button !== 0) return + event.preventDefault() + event.stopPropagation() + event.currentTarget.setPointerCapture(event.pointerId) + drag.current = { handle, pointerId: event.pointerId, x: event.clientX, y: event.clientY, start: rect } + setDragging(true) + } + + function onPointerMove(event: ReactPointerEvent) { + const current = drag.current + if (!current || current.pointerId !== event.pointerId || !size || !box) return + // Screen pixels to image pixels, at the scale the image is drawn now. + const dx = (event.clientX - current.x) / box.scale + const dy = (event.clientY - current.y) / box.scale + onRectChange(dragRect(current.start, current.handle, dx, dy, size, ratio)) + } + + function endDrag(event: ReactPointerEvent) { + if (drag.current?.pointerId !== event.pointerId) return + drag.current = null + setDragging(false) + } + + const dragProps = (handle: Handle) => ({ + onPointerDown: (event: ReactPointerEvent) => onPointerDown(handle, event), + onPointerMove, + onPointerUp: endDrag, + onPointerCancel: endDrag, + onLostPointerCapture: endDrag, + }) + + // The frame in overlay pixels. + const frame = box && rect + ? { left: box.left + rect.x * box.scale, top: box.top + rect.y * box.scale, width: rect.w * box.scale, height: rect.h * box.scale } + : null + + return ( +
+ {input.name} onImageSize({ width: event.currentTarget.naturalWidth, height: event.currentTarget.naturalHeight })} + className="pointer-events-none absolute inset-0 h-full w-full object-contain" /> + {frame && ( + <> + + + + + +
+ {dragging && } +
+ + {!locked && HANDLES.map(({ handle, x, y, cursor }) => ( + // A 16 px hit area around an 8 px white square. + + ))} + + )} +
+ ) +} + +function Dim(props: { left: number; top: number; width: number; height: number }): JSX.Element | null { + if (props.width <= 0 || props.height <= 0) return null + return
+} + +function ThirdsGrid(): JSX.Element { + return ( +
+ + + + +
+ ) +} + +function Spinner(): JSX.Element { + return ( + + ) +} diff --git a/src/areas/image-studio/ImageOpsToolbar.tsx b/src/areas/image-studio/ImageOpsToolbar.tsx index f90162d2..59160c99 100644 --- a/src/areas/image-studio/ImageOpsToolbar.tsx +++ b/src/areas/image-studio/ImageOpsToolbar.tsx @@ -22,6 +22,7 @@ import { type SetupCard, } from './imageOps' import { ImageOpIcon } from './imageOpIcons' +import CropTool, { type CropEdges } from './CropTool' import { ImageOpNotReadyError, getImageOpStatus, listImageOps, prepareImageOp, runImageOpOnFile } from './imageOpsApi' // Image operations served by the backend (GET /image/ops: background removal, @@ -265,11 +266,16 @@ function ImageOpControl(props: ToolbarProps & { ) - // CROP_UI: crop is the one op with its own UI. Task 4 replaces this branch with - // - // Until then crop falls through to the generic options. - const options = op.id === 'crop' ? genericOptions : genericOptions + // Crop is the one op with its own UI: a frame on the image, and its own options. + const isCrop = op.id === 'crop' + /** What the crop frame is drawn on: the image the run will read. */ + const cropInput = active && isCrop ? runInputFor(entries, selected, op.id) : null + + async function applyCrop(edges: CropEdges): Promise { + const added = await start({ ...edges }) + if (added) onActiveToolChange(null) + return added + } return ( <> @@ -279,9 +285,14 @@ function ImageOpControl(props: ToolbarProps & { {running ? : } + {cropInput && ( + onActiveToolChange(null)} /> + )} + {active && optionsSlot && createPortal( <> - {options} + {!isCrop && genericOptions} {card.phase !== 'hidden' && card.phase !== 'checking' && ( Date: Wed, 18 Nov 2026 13:49:14 +0100 Subject: [PATCH 6/8] fix(image-studio): let a crop edge reach 100% so a thin far-side frame is not clamped --- api/services/image_ops/builtin.py | 2 +- api/tests/test_image_ops_framing.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/services/image_ops/builtin.py b/api/services/image_ops/builtin.py index 8ea8d704..962bd49a 100644 --- a/api/services/image_ops/builtin.py +++ b/api/services/image_ops/builtin.py @@ -105,7 +105,7 @@ def _edge_param(param_id: str, label: str) -> dict[str, Any]: "type": "float", "default": 0.0, "min": 0.0, - "max": 99.0, + "max": 100.0, "step": 0.1, "tooltip": f"Percentage of the image cut off the {param_id} edge.", } diff --git a/api/tests/test_image_ops_framing.py b/api/tests/test_image_ops_framing.py index e4ea7996..f4e91be7 100644 --- a/api/tests/test_image_ops_framing.py +++ b/api/tests/test_image_ops_framing.py @@ -127,7 +127,7 @@ def test_colour_key_transparency_is_honoured(self) -> None: self.assertEqual(_visible_box(framed), (0, 0, 512, 512)) def test_crop_edges_are_clamped(self) -> None: - self.assertEqual(image_ops_registry.resolve_params("crop", {"left": 150})["left"], 99.0) + self.assertEqual(image_ops_registry.resolve_params("crop", {"left": 150})["left"], 100.0) def test_crop_accepts_fractional_percentages(self) -> None: path = self._save(Image.new("RGB", (1000, 500), (10, 20, 30)), "wide.png") From 7e6b99a8be66eb076ba3943a0bed76f9e75425ea Mon Sep 17 00:00:00 2001 From: Lightning Pixel Date: Wed, 18 Nov 2026 13:49:15 +0100 Subject: [PATCH 7/8] fix(image-studio): leave Enter to the focused control and end a drag whose release was missed --- src/areas/image-studio/CropTool.tsx | 27 +++++++++++++++++-------- src/areas/image-studio/imageOps.test.ts | 17 ++++++++++++++++ src/areas/image-studio/imageOps.ts | 15 ++++++++++++++ 3 files changed, 51 insertions(+), 8 deletions(-) diff --git a/src/areas/image-studio/CropTool.tsx b/src/areas/image-studio/CropTool.tsx index 067aede0..71747cf7 100644 --- a/src/areas/image-studio/CropTool.tsx +++ b/src/areas/image-studio/CropTool.tsx @@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react' import type { PointerEvent as ReactPointerEvent } from 'react' import { createPortal } from 'react-dom' import type { StudioImage } from './imageStudioStore' -import { isTextField } from './imageOps' +import { isInteractive, isTextField } from './imageOps' import { aspectRatio, cropEdges, @@ -103,17 +103,17 @@ export default function CropTool({ input, optionsSlot, overlaySlot, running, bus }, [canApply, size, rect, onApply]) // Enter applies, Esc cancels. Capture phase, so this runs before the - // toolbar's Esc listener, which skips events already handled. + // toolbar's Esc listener, which skips events already handled. Enter on a + // control (a ratio, Reset, a header button, a link…) is left to that control. const keys = useRef({ apply, onCancel }) keys.current = { apply, onCancel } useEffect(() => { const onKeyDown = (event: KeyboardEvent) => { - if (event.defaultPrevented || isTextField(event.target)) return - if (event.key === 'Escape') { + if (event.defaultPrevented) return + if (event.key === 'Escape' && !isTextField(event.target)) { event.preventDefault() keys.current.onCancel() - } else if (event.key === 'Enter' && !event.repeat) { - // Also keeps Enter from clicking the focused button (a ratio, Reset…). + } else if (event.key === 'Enter' && !event.repeat && !isInteractive(event.target)) { event.preventDefault() keys.current.apply() } @@ -207,6 +207,9 @@ function CropOverlay({ input, size, rect, ratio, locked, onImageSize, onRectChan if (locked || !rect || event.button !== 0) return event.preventDefault() event.stopPropagation() + // preventDefault keeps focus where it was (often the Crop icon): move it + // here, so the Enter that follows applies the crop rather than clicking it. + container?.focus({ preventScroll: true }) event.currentTarget.setPointerCapture(event.pointerId) drag.current = { handle, pointerId: event.pointerId, x: event.clientX, y: event.clientY, start: rect } setDragging(true) @@ -214,7 +217,15 @@ function CropOverlay({ input, size, rect, ratio, locked, onImageSize, onRectChan function onPointerMove(event: ReactPointerEvent) { const current = drag.current - if (!current || current.pointerId !== event.pointerId || !size || !box) return + if (!current || current.pointerId !== event.pointerId) return + // The release was missed (the grabbed handle unmounted when the run + // locked the frame): end the drag rather than follow a hovering pointer. + if (locked || event.buttons === 0) { + drag.current = null + setDragging(false) + return + } + if (!size || !box) return // Screen pixels to image pixels, at the scale the image is drawn now. const dx = (event.clientX - current.x) / box.scale const dy = (event.clientY - current.y) / box.scale @@ -241,7 +252,7 @@ function CropOverlay({ input, size, rect, ratio, locked, onImageSize, onRectChan : null return ( -
+
{input.name} onImageSize({ width: event.currentTarget.naturalWidth, height: event.currentTarget.naturalHeight })} className="pointer-events-none absolute inset-0 h-full w-full object-contain" /> diff --git a/src/areas/image-studio/imageOps.test.ts b/src/areas/image-studio/imageOps.test.ts index da9e19fd..adac2b9b 100644 --- a/src/areas/image-studio/imageOps.test.ts +++ b/src/areas/image-studio/imageOps.test.ts @@ -8,6 +8,7 @@ import { createRunLock, failInstall, isOutsideWorkspace, + isInteractive, isTextField, modelViewCaption, notReadyMissing, @@ -196,3 +197,19 @@ test('isTextField is true only where typing goes', () => { assert.equal(isTextField(target({ tagName: 'BUTTON' })), false) assert.equal(isTextField(null), false) }) + +test('isInteractive is true on controls that handle Enter themselves', () => { + const target = (stub: object) => stub as unknown as EventTarget + const withRole = (role: string | null) => target({ tagName: 'DIV', getAttribute: (name: string) => (name === 'role' ? role : null) }) + assert.equal(isInteractive(target({ tagName: 'BUTTON' })), true) + assert.equal(isInteractive(target({ tagName: 'a' })), true) + assert.equal(isInteractive(target({ tagName: 'SELECT' })), true) + assert.equal(isInteractive(target({ tagName: 'INPUT', type: 'checkbox' })), true) + assert.equal(isInteractive(target({ tagName: 'INPUT', type: 'number' })), true) + assert.equal(isInteractive(target({ tagName: 'DIV', isContentEditable: true })), true) + assert.equal(isInteractive(withRole('button')), true) + assert.equal(isInteractive(withRole('Link')), true) + assert.equal(isInteractive(withRole(null)), false) + assert.equal(isInteractive(target({ tagName: 'BODY' })), false) + assert.equal(isInteractive(null), false) +}) diff --git a/src/areas/image-studio/imageOps.ts b/src/areas/image-studio/imageOps.ts index 9a972dcc..5ad49c7c 100644 --- a/src/areas/image-studio/imageOps.ts +++ b/src/areas/image-studio/imageOps.ts @@ -229,3 +229,18 @@ export function isTextField(target: EventTarget | null): boolean { const type = typeof el.type === 'string' ? el.type.toLowerCase() : 'text' return !NON_TEXT_INPUTS.has(type) } + +/** Tags whose Enter/Space key already does something (activates, follows, submits, toggles). */ +const INTERACTIVE_TAGS = new Set(['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY']) +const INTERACTIVE_ROLES = new Set(['button', 'link', 'checkbox', 'radio', 'switch', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'combobox', 'textbox', 'slider', 'spinbutton']) + +/** Whether a key event's target is a control that handles Enter itself, so a page-wide Enter shortcut must leave it alone. Duck-typed so it runs without a DOM. */ +export function isInteractive(target: EventTarget | null): boolean { + if (isTextField(target)) return true + if (!target || typeof target !== 'object') return false + const el = target as { tagName?: unknown, getAttribute?: unknown } + const tag = typeof el.tagName === 'string' ? el.tagName.toUpperCase() : '' + if (INTERACTIVE_TAGS.has(tag)) return true + const role = typeof el.getAttribute === 'function' ? (el.getAttribute as (name: string) => unknown).call(target, 'role') : null + return typeof role === 'string' && INTERACTIVE_ROLES.has(role.toLowerCase()) +} From eb3bab59a076f89e4930515b6dea297df3edac08 Mon Sep 17 00:00:00 2001 From: Lightning Pixel Date: Wed, 18 Nov 2026 13:49:51 +0100 Subject: [PATCH 8/8] docs: crop edges go up to 100% --- docs/superpowers/plans/2026-11-18-image-studio-tools.md | 4 ++-- .../superpowers/specs/2026-11-18-image-studio-tools-design.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/superpowers/plans/2026-11-18-image-studio-tools.md b/docs/superpowers/plans/2026-11-18-image-studio-tools.md index 5d734f6e..e4ae7ddb 100644 --- a/docs/superpowers/plans/2026-11-18-image-studio-tools.md +++ b/docs/superpowers/plans/2026-11-18-image-studio-tools.md @@ -35,10 +35,10 @@ - Test: `api/tests/test_image_ops_framing.py` **Interfaces:** -- Produces: op `crop` params `left|top|right|bottom`: `type "float"`, `default 0.0`, `min 0.0`, `max 99.0`, `step 0.1`. +- Produces: op `crop` params `left|top|right|bottom`: `type "float"`, `default 0.0`, `min 0.0`, `max 100.0`, `step 0.1`. - [ ] **Step 1: Update/add tests** - - `test_crop_edges_are_clamped`: `resolve_params("crop", {"left": 150})["left"] == 99.0`. + - `test_crop_edges_are_clamped`: `resolve_params("crop", {"left": 150})["left"] == 100.0`. - `test_crop_accepts_fractional_percentages`: on a 1000×500 image, `{"left": 12.5, "top": 10.2}` → output size `(875, 449)` (`crop_box` rounds: x0=125, y0=51). - `test_crop_refuses_an_empty_box`: `{"left": 60, "right": 40}` raises `ImageOpInputError`; same for `top+bottom >= 100`. - [ ] **Step 2: Run, expect the new tests to FAIL.** diff --git a/docs/superpowers/specs/2026-11-18-image-studio-tools-design.md b/docs/superpowers/specs/2026-11-18-image-studio-tools-design.md index fa2a12e9..772e22f6 100644 --- a/docs/superpowers/specs/2026-11-18-image-studio-tools-design.md +++ b/docs/superpowers/specs/2026-11-18-image-studio-tools-design.md @@ -39,9 +39,9 @@ The maintainer picked B. ### Backend (`api/services/image_ops`) -- `crop` params stay `left`, `top`, `right`, `bottom` (percent of the side cut off each edge), but become `float`, `min 0`, `max 99`, `step 0.1`. The 45 % limit goes. +- `crop` params stay `left`, `top`, `right`, `bottom` (percent of the side cut off each edge), but become `float`, `min 0`, `max 100`, `step 0.1`. The 45 % limit goes. - `crop` raises `ImageOpInputError` when `left + right >= 100` or `top + bottom >= 100` (nothing left to keep). `framing.crop_box` already rounds to pixels and keeps at least 1 px. -- Tests in `api/tests/test_image_ops_framing.py` follow (the clamp test moves from 45 to 99, plus the new error). +- Tests in `api/tests/test_image_ops_framing.py` follow (the clamp test moves from 45 to 100, plus the new error). ### Front end (`src/areas/image-studio`)