diff --git a/docs/design/README.md b/docs/design/README.md index 98ec6f3cc..c39cdc70f 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -14,6 +14,10 @@ behavior; a design document does not have to. ## Index +Implemented, awaiting release: + +- [Markup: image annotation and saving](drawing-annotation-and-recovery.md) + Implemented and frozen: - [API abuse controls](api-abuse-controls.md) diff --git a/docs/design/drawing-annotation-and-recovery.md b/docs/design/drawing-annotation-and-recovery.md new file mode 100644 index 000000000..c131530bb --- /dev/null +++ b/docs/design/drawing-annotation-and-recovery.md @@ -0,0 +1,117 @@ +# Markup: first release + +Status: Implemented; awaiting a tagged release. + +Date: 2026-11-15 + +Related: [MemoEditor](../../web/src/components/MemoEditor/README.md), +[Canvas product definition](https://github.com/usememos/canvas/blob/main/docs/product-definition.md), +[Canvas checkpoint contract](https://github.com/usememos/canvas/blob/main/docs/recovery-checkpoints.md). + +## Decision and scope + +Markup lets someone sketch an idea or mark a detail in an image, then attach the result to a memo. The first release completes +these actions and keeps the interface small. Use **Markup** (Chinese: **标注**) with Lucide's **Palette** icon. Canvas remains the +library name; the editable PNG format and existing resource names do not change. + +Memos draft recovery is deferred. Do not add IndexedDB persistence, recovery notices, Continue markup, or a draft-management UI. +An unfinished markup must not disable the containing memo's save. Canvas 26.11.3 retains its checkpoint capability for a future +integration, but this release does not expose a Memos markup draft. + +Keep one primary action and let the current context carry its meaning. Do not add a permanent More, Download or Discard menu, +status rows, or routine success copy. + +## Critical user journeys + +### Sketch and add + +The editor's insert menu offers Palette + Markup. It opens a blank drawing. **Add** exports an editable `.canvas.png` into the +current memo's pending attachments. The memo's existing Save uploads it. Adding explanatory text is optional. + +### Annotate an image + +An ordinary local or instance-hosted image offers Palette + Markup. Saved image previews offer it when the current user can edit +the memo. External images, motion-photo/video groups, standalone attachment-library editing, and replacing inline image references +are outside this release. + +Load the original file, never the thumbnail. Prevent duplicate opens, abort a dismissed load, and ignore late responses. A failed import keeps the source available and must not produce an apparently editable blank sheet. Fetching an existing attachment in the viewer shows a centered spinner before its canvas mounts; preparing a background image uses the existing primary action's spinner. Viewer fetch failures close the loading surface and show an error toast. Background preparation failures disable drawing and submission, with an error toast and a labeled retry icon whose tooltip explains the failure. + +Insert the image as a locked background, then call `setScene(getScene())` to establish a clean baseline and clear its insertion +undo step. `markSaved()` alone would leave Undo able to remove the background. Fit the image and start with red ink from the +existing palette. Keep the library's 1440 px import cap and opaque-image JPEG policy; this is not full-resolution image editing. + +The first annotation is a new editable PNG immediately after its source. Keep the original's bytes, identity and position. The PNG +embeds its background, so subsequent edits do not require the source to remain available. + +Inside an editor, **Add** joins the pending files. From a saved image preview, **Save copy** uploads and binds the annotation to +that memo. Read current membership before binding or retrying, retain other attachments, and stop if the source has disappeared. +Do not open a separate composer or save unrelated edits. + +### Edit and save + +Existing editable PNGs offer **Edit markup**. In the editor, **Save** updates the pending drawing; an owned saved attachment queues a +replacement for the outer memo save. A file the user cannot replace remains intact and the result becomes a copy. In a saved +markup viewer, **Save** replaces the owned attachment and updates the memo; **Save copy** retains an attachment the user cannot +replace. Existing permission and upload APIs remain authoritative. + +## Actions and exceptions + +| Context | Primary action | +| --- | --- | +| New sketch or first annotation in the editor | Add | +| Edit a pending drawing or queue an owned attachment replacement | Save | +| Edit an owned drawing directly from its viewer | Save | +| Direct image annotation or a direct edit requiring a new attachment | Save copy | + +Use the same short translated labels on loading buttons. Do not repeat the destination in the visible text. Existing attachment +New/Edited treatment identifies pending work in the composer. Export, adding a file to the editor, and server acceptance remain +separate implementation states; normal states add no copy to the canvas. + +Freeze the engine with `setReadOnly(true)` before export/submission. Block repeated submissions, scene replacement and editing +until the result is known. Acknowledge with `markSaved()` only after the host accepts, while still frozen. On failure retain the +scene and resume editing; after an acknowledged upload with a failed bind/timestamp, keep that revision frozen and retry only the +remaining operation. Surface partial failure with an exception icon/tooltip and the existing error toast. No overall Saved claim +until every required request is acknowledged. + +Close unchanged work directly. Close changed work through a discard confirmation, with **Keep drawing** and **Discard**. This is +the only ordinary discard action; it appears when the user is about to lose unsaved changes. Do not close during a server write. +This release retains unsuccessful work in memory while the sheet is open; it does not claim recovery after reload or closure. + +## Shared viewing and editing surface + +Viewing and editing are modes of one Markup surface. Keep the same dialog, paper, canvas instance and control sizes when switching modes. Entering edit must preserve the visible content, pan and zoom; saving or closing unchanged edits returns to the same view. Discard restores the accepted scene and may fit it again. Do not mount a second dialog or measure a new canvas while the previous dialog is closing. + +The top row is the same in both modes: a quiet X at the left and the current action at the right. The viewing action is Palette + **Edit** when permitted; editing replaces it with **Add**, **Save** or **Save copy**. Use no bordered container around these actions and no visible mode heading. The accessible dialog name remains Markup; icon labels and tooltips explain secondary actions. Viewing exposes no editing controls or save status. + +Canvas navigation is separate from closing or saving. Display the current zoom as a rounded percentage (for example **100%**) on a ghost button that opens an upward action menu. Place it at the bottom left on desktop and above the bottom tools bar on phones, accounting for the safe area. Keep the same position in viewing and editing, including the space above the phone's tools bar when that bar is absent. Its idle state has no fill or bordered container. The percentage stays synchronized with menu actions, wheel/trackpad zoom, touch pinches, initial fitting and background-image preparation; changing zoom never makes the drawing dirty. + +The menu contains **Zoom in**, **Zoom out**, a separator, **Zoom to fit** and **Reset zoom** (100%). Use Plus, Minus, ScanSearch and RotateCcw icons, respectively. The percentage replaces the standalone Fit button; names appear only in the menu and accessible label. Keep the same menu and actions in viewing and editing. Use the package's md Menu, retain focus in the dialog and let Escape dismiss the menu before affecting the drawing. Suspend canvas input while the menu is open so clicking the paper dismisses it without drawing or panning. Do not add selection zoom or a minimap in this first release. This follows Excalidraw's [zoom-to-fit magnifier and area icon](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/components/icons.tsx) and tldraw's [separate canvas navigation region](https://tldraw.dev/sdk-features/ui-components). + +Editing adds the existing bordered tools bar at the top center on desktop and at the bottom on phones. Available phone Undo/Redo controls follow X as plain ghost icons; they have no separate container and unavailable history actions are omitted. Desktop history and image insertion stay in the editing tools bar. Do not add controls or permanent status text to make the two modes match. + +Keep focus inside the dialog across mode changes: entering edit focuses the canvas; returning to view focuses Edit, or the canvas when Edit is unavailable. After a phone history action, focus returns to the canvas rather than a removed control. Close follows the existing unchanged/discard behavior. + +## Retry and concurrency + +Keep acknowledged uploads in memory. A copy whose bind failed is bound again without another upload. A replacement whose timestamp +update failed retries the memo update. If memo text saved before a replacement failed, keep the replacement pending and say which +part needs retry. Re-read membership for list-changing retries so another tab's attachment is retained. API calls are not an atomic +cross-resource transaction and an unacknowledged response does not provide an exactly-once guarantee. + +## Ownership and verification + +Canvas owns drawing, text input, scene serialization, locked backgrounds and editable PNG export. Memos owns the shell, strings, +permissions, placement and save orchestration. Pin `@usememos/canvas@26.11.3`; no backend schema or release workflow changes. + +Extend neighboring drawing, viewer, image-preview, attachment-placement and memo-save tests. The browser suite exercises actual +Canvas image preparation, annotation/export, original preservation and 360px controls. Cover viewing an existing drawing, entering edit, retaining visible content and viewport, returning without changes, discarding changes, saving, repeated mode changes and keyboard focus on desktop and phones. Check the zoom percentage's identical lower-left position in both modes, clearance above the phone tools bar, live zoom updates and all four menu actions in both modes, including keyboard dismissal and zoom without scene changes. It uses an isolated Vite server and cache; +Playwright is a development dependency only. + +From `web/`, run `pnpm lint`, `pnpm test`, `pnpm build`, and `pnpm test:drawings` (`pnpm exec playwright install chromium` once). +Browser emulation does not establish real-device pen, keyboard or mobile suspension behavior. + +## Deferred recovery + +A later Memos integration can use Canvas `getCheckpoint()`, `restoreCheckpoint()` and `onCheckpoint`. It needs a separate product +decision for discovering unfinished work, retaining companion text/files and upload progress, account/session identity, conflicts, +storage failures and cleanup. Do not reintroduce that UI as part of this first release. diff --git a/web/package.json b/web/package.json index 770c7ec9d..471970619 100644 --- a/web/package.json +++ b/web/package.json @@ -13,6 +13,7 @@ "lint:fix": "biome check --write src tests", "format": "biome format --write src tests", "test": "vitest run", + "test:drawings": "playwright test --config tests/browser/playwright.config.ts", "test:watch": "vitest", "test:coverage": "vitest run --coverage" }, @@ -26,7 +27,7 @@ "@tailwindcss/vite": "^4.2.4", "@tanstack/react-query": "^5.100.9", "@tanstack/react-query-devtools": "^5.100.9", - "@usememos/canvas": "26.11.2", + "@usememos/canvas": "26.11.3", "@usememos/editor": "26.11.5", "@usememos/ui": "26.11.20", "class-variance-authority": "^0.7.1", @@ -58,6 +59,7 @@ "@babel/core": "7.29.0", "@biomejs/biome": "^2.4.14", "@bufbuild/protobuf": "^2.12.0", + "@playwright/test": "1.63.0", "@rolldown/plugin-babel": "0.2.3", "@testing-library/jest-dom": "^6.9.1", "@testing-library/react": "^16.3.2", diff --git a/web/pnpm-lock.yaml b/web/pnpm-lock.yaml index 99419982a..1bf6bd8ee 100644 --- a/web/pnpm-lock.yaml +++ b/web/pnpm-lock.yaml @@ -39,8 +39,8 @@ importers: specifier: ^5.100.9 version: 5.100.9(@tanstack/react-query@5.100.9(react@19.2.6))(react@19.2.6) '@usememos/canvas': - specifier: 26.11.2 - version: 26.11.2(react-dom@19.2.6(react@19.2.6))(react@19.2.6) + specifier: 26.11.3 + version: 26.11.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6) '@usememos/editor': specifier: 26.11.5 version: 26.11.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6) @@ -129,6 +129,9 @@ importers: '@bufbuild/protobuf': specifier: ^2.12.0 version: 2.12.0(patch_hash=9d60cec35402ba36bc21a72fefc68ccef8db0acb883504cc47c05a00a0029f8c) + '@playwright/test': + specifier: 1.63.0 + version: 1.63.0 '@rolldown/plugin-babel': specifier: 0.2.3 version: 0.2.3(@babel/core@7.29.0)(@babel/runtime@7.29.7)(rolldown@1.0.0-rc.18)(vite@8.0.11(@types/node@24.12.2)(jiti@2.6.1)) @@ -516,6 +519,11 @@ packages: '@pierre/highlights@0.3.0': resolution: {integrity: sha512-s6xZ/giPPrSeCO2w254GiysUXD4ditKMTOrl1vHynvPqP7VdlujYi01O9joxJ0T16XkoXGQMN6zkRi9+O8NCzg==} + '@playwright/test@1.63.0': + resolution: {integrity: sha512-oxMK4vllB9RK5NQ2l1pq1IfOf2AvnEuj/vYGDj0H2nMtmtZpKtCwt/l00GEO6xjGfpBNAvjovvYdCm50dRQkpQ==} + engines: {node: '>=20'} + hasBin: true + '@react-leaflet/core@3.0.0': resolution: {integrity: sha512-3EWmekh4Nz+pGcr+xjf0KNyYfC3U2JjnkWsh0zcqaexYqmmB5ZhH37kz41JXGmKzpaMZCnPofBBm64i+YrEvGQ==} peerDependencies: @@ -951,8 +959,8 @@ packages: cpu: [x64] os: [win32] - '@usememos/canvas@26.11.2': - resolution: {integrity: sha512-sgFrRUSUz5qq3JMiVqPVsLd8NPL+nmWfuEG45mpjbvBbPRxHdKSzNVYc6DwokG/Z670zJI3gDc5Lfsi75QYvGw==} + '@usememos/canvas@26.11.3': + resolution: {integrity: sha512-KMIGsm/1afZpSuV2uILNBmB9rTUNpplhcCI6A7IsP+2kQUVGNcVOsTFIfSyVyqcrUdTKgnbt+XlfG1NwRhi3SA==} peerDependencies: react: '>=18' react-dom: '>=18' @@ -1404,6 +1412,16 @@ packages: resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==} engines: {node: '>=12'} + playwright-core@1.63.0: + resolution: {integrity: sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==} + engines: {node: '>=20'} + hasBin: true + + playwright@1.63.0: + resolution: {integrity: sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==} + engines: {node: '>=20'} + hasBin: true + postcss@8.5.14: resolution: {integrity: sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==} engines: {node: ^10 || ^12 || >=14} @@ -2075,6 +2093,10 @@ snapshots: '@pierre/highlights@0.3.0': {} + '@playwright/test@1.63.0': + dependencies: + playwright: 1.63.0 + '@react-leaflet/core@3.0.0(leaflet@1.9.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)': dependencies: leaflet: 1.9.4 @@ -2382,7 +2404,7 @@ snapshots: '@typescript/typescript-win32-x64@7.0.2': optional: true - '@usememos/canvas@26.11.2(react-dom@19.2.6(react@19.2.6))(react@19.2.6)': + '@usememos/canvas@26.11.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)': optionalDependencies: react: 19.2.6 react-dom: 19.2.6(react@19.2.6) @@ -2753,6 +2775,12 @@ snapshots: picomatch@4.0.4: {} + playwright-core@1.63.0: {} + + playwright@1.63.0: + dependencies: + playwright-core: 1.63.0 + postcss@8.5.14: dependencies: nanoid: 3.3.11 diff --git a/web/src/components/DrawingSheet/DrawingSheet.tsx b/web/src/components/DrawingSheet/DrawingSheet.tsx index 691e4e430..5c15c1e4e 100644 --- a/web/src/components/DrawingSheet/DrawingSheet.tsx +++ b/web/src/components/DrawingSheet/DrawingSheet.tsx @@ -1,18 +1,24 @@ -import { type CanvasError, type CanvasHandle, drawingFileName, type Scene, type ToolName } from "@usememos/canvas"; +import { type CanvasError, type CanvasHandle, drawingFileName, MAX_ZOOM, MIN_ZOOM, type Scene, type ToolName } from "@usememos/canvas"; import { Canvas } from "@usememos/canvas/react"; -import { AlertDialog, Button, Dialog, Popover, Toggle, ToggleGroup, Tooltip } from "@usememos/ui"; +import { AlertDialog, Button, Dialog, Menu, Popover, Spinner, Toggle, ToggleGroup, Tooltip } from "@usememos/ui"; import { + CircleAlertIcon, CircleIcon, EraserIcon, ImagePlusIcon, + MinusIcon, MousePointer2Icon, MoveUpRightIcon, + PaletteIcon, PencilIcon, + PlusIcon, Redo2Icon, - ScanIcon, + RotateCcwIcon, + ScanSearchIcon, SquareIcon, TypeIcon, Undo2Icon, + XIcon, } from "lucide-react"; import { type ClipboardEvent, type ReactElement, useEffect, useRef, useState } from "react"; import useMediaQuery from "@/hooks/useMediaQuery"; @@ -21,6 +27,7 @@ import { cn } from "@/lib/utils"; import { type Translations, useTranslate } from "@/utils/i18n"; import { primaryModifierGlyph } from "@/utils/platform"; import { DrawingDialogPopup, FloatingAction, FloatingBar, FloatingRow } from "./DrawingFrame"; +import { DrawingActionError } from "./drawing"; import { DRAWING_HUES, useCanvasTheme } from "./useCanvasTheme"; const TOOLS: { name: ToolName; label: Translations; shortcut: string; icon: ReactElement }[] = [ @@ -42,15 +49,21 @@ const WIDTHS: { value: number; label: Translations }[] = [ ]; export interface DrawingSheetProps { - /** `edit` reopens a saved drawing; it changes the sheet's name and the discard prompt. */ - mode: "new" | "edit"; + mode: "new" | "edit" | "view"; + /** Present only when the viewer permits editing. */ + onEdit?: () => void; + loading?: boolean; /** The scene read from the drawing's original file. */ initialScene?: Scene; + commitLabel?: Translations; + /** Returns the accepted scene when an acknowledged upload has already replaced the source. */ + onDiscard?: () => Scene | void | Promise; + submissionPending?: boolean; /** A picture to draw on: a file named like a drawing whose scene could not be read. */ background?: Blob; /** * The finished drawing, a PNG with the scene embedded, named `drawing-YYYYMMDD-HHMMSS.canvas.png`. - * A promise keeps Done busy until it settles; a rejection keeps the sheet open to retry. + * A promise keeps the action busy until it settles; a rejection keeps the sheet open to retry. */ onDone: (file: File) => void | Promise; onClose: () => void; @@ -62,7 +75,18 @@ export interface DrawingSheetProps { * theme, discard prompt) is memos'. On a phone the tools float at the bottom, in thumb * reach, with each control 44 px apart. */ -const DrawingSheet = ({ mode, initialScene, background, onDone, onClose }: DrawingSheetProps) => { +const DrawingSheet = ({ + mode, + onEdit, + loading = false, + initialScene, + background, + commitLabel, + onDiscard, + submissionPending, + onDone, + onClose, +}: DrawingSheetProps) => { const t = useTranslate(); const isWide = useMediaQuery("sm"); // Small controls on a desktop; a phone keeps the 32px ones, 44px apart, for touch. @@ -71,39 +95,109 @@ const DrawingSheet = ({ mode, initialScene, background, onDone, onClose }: Drawi const canvasRef = useRef(null); const surfaceRef = useRef(null); const fileInputRef = useRef(null); + const editButtonRef = useRef(null); + const isViewing = mode === "view"; const [tool, setTool] = useState("pen"); const [history, setHistory] = useState({ undo: false, redo: false }); + const [zoom, setZoom] = useState(1); + const [zoomMenuOpen, setZoomMenuOpen] = useState(false); + const zoomFrame = useRef(undefined); // Null follows the theme's ink, so a drawing started in one theme keeps reading in the other. - const [color, setColor] = useState(null); + const [color, setColor] = useState(background ? "#e03131" : null); const [width, setWidth] = useState(2); const [isExporting, setIsExporting] = useState(false); const [discardOpen, setDiscardOpen] = useState(false); // Drawing waits for a background picture, so no stroke can land before it and be marked saved with it. const [isPreparing, setIsPreparing] = useState(Boolean(background)); - const title = t(mode === "edit" ? "editor.drawing.edit" : "editor.drawing.new-title"); + const [commitError, setCommitError] = useState(); + const [prepareFailed, setPrepareFailed] = useState(false); + const busy = useRef(false); + const locked = useRef(submissionPending); + locked.current = isViewing || submissionPending; + const preparing = useRef(Boolean(background)); + const alive = useRef(true); + const actionLabel = commitLabel ?? (mode === "edit" ? "common.save" : "common.add"); + const title = t("editor.insert-menu.drawing"); const currentColor = color ?? ink; // Runs once the canvas has mounted (see CanvasMounted): the pen is ready, and a // picture without a scene becomes the drawing's locked background. - const setUpCanvas = () => { + useEffect(() => { + alive.current = true; + return () => { + alive.current = false; + if (zoomFrame.current !== undefined) cancelAnimationFrame(zoomFrame.current); + }; + }, []); + + useEffect(() => { + if (isViewing) { + if (editButtonRef.current) editButtonRef.current.focus(); + else canvasRef.current?.focus(); + } else { + canvasRef.current?.setTool("pen"); + setTool("pen"); + setHistory({ undo: Boolean(canvasRef.current?.canUndo()), redo: Boolean(canvasRef.current?.canRedo()) }); + canvasRef.current?.focus(); + } + }, [isViewing]); + + const setUpCanvas = async () => { const canvas = canvasRef.current; if (!canvas) return; - canvas.setTool("pen"); + if (!isViewing) canvas.setTool("pen"); + syncZoom(); if (!background) return; - canvas - .insertImage(background, { background: true }) - .then(() => { - // The picture is where the drawing starts, not a change to discard. - canvas.markSaved(); - canvas.zoomToFit(); - }) - .catch(() => showErrorToast(t("editor.drawing.image-failed"))) - .finally(() => setIsPreparing(false)); + preparing.current = true; + setIsPreparing(true); + setPrepareFailed(false); + canvas.setReadOnly(false); + try { + // The inert surface blocks user input while the import establishes its baseline. + const id = await canvas.insertImage(background, { background: true }); + if (!alive.current) return; + if (!id) throw new Error("Image preparation failed"); + canvas.setScene(canvas.getScene()); + canvas.setStyle({ strokeColor: "#e03131" }); + setColor("#e03131"); + canvas.zoomToFit(); + syncZoom(); + preparing.current = false; + canvas.setReadOnly(false); + } catch { + if (alive.current) { + setPrepareFailed(true); + showErrorToast(t("editor.drawing.image-failed")); + } + } finally { + if (alive.current) setIsPreparing(false); + } }; const syncHistory = () => { const canvas = canvasRef.current; setHistory({ undo: Boolean(canvas?.canUndo()), redo: Boolean(canvas?.canRedo()) }); + syncZoom(); + }; + + const syncZoom = () => { + const canvas = canvasRef.current; + if (canvas) setZoom(canvas.getViewport().zoom); + }; + + const scheduleZoom = () => { + if (zoomFrame.current !== undefined) return; + zoomFrame.current = requestAnimationFrame(() => { + zoomFrame.current = undefined; + syncZoom(); + }); + }; + + const changeZoom = (factor: number) => { + const canvas = canvasRef.current; + if (!canvas) return; + canvas.zoomTo(canvas.getViewport().zoom * factor); + syncZoom(); }; const handleCanvasError = (error: CanvasError) => { @@ -114,16 +208,19 @@ const DrawingSheet = ({ mode, initialScene, background, onDone, onClose }: Drawi }; const chooseTool = (next: ToolName) => { + if (isViewing || busy.current || preparing.current || prepareFailed || submissionPending) return; setTool(next); canvasRef.current?.setTool(next); }; const applyWidth = (strokeWidth: number) => { + if (isViewing || busy.current || preparing.current || prepareFailed || submissionPending) return; canvasRef.current?.setStyle({ strokeWidth }); setWidth(strokeWidth); }; const insertImages = (files: File[]) => { + if (isViewing || busy.current || preparing.current || prepareFailed || submissionPending) return; for (const file of files.filter((candidate) => candidate.type.startsWith("image/"))) { canvasRef.current?.insertImage(file).catch(() => showErrorToast(t("editor.drawing.image-failed"))); } @@ -135,32 +232,32 @@ const DrawingSheet = ({ mode, initialScene, background, onDone, onClose }: Drawi insertImages(Array.from(event.clipboardData.files)); }; - // Cancel, Escape and the system back gesture all ask first when the drawing has changes. const requestClose = () => { - if (canvasRef.current?.isDirty()) { - setDiscardOpen(true); - return; - } - onClose(); + if (busy.current) return; + if (!isViewing && canvasRef.current?.isDirty()) setDiscardOpen(true); + else onClose(); }; const handleDone = async () => { const canvas = canvasRef.current; - if (!canvas || isExporting || isPreparing) return; - // Text still being typed is part of the drawing. - canvas.commitText(); + if (!canvas || isViewing || busy.current || preparing.current || prepareFailed) return; + busy.current = true; setIsExporting(true); + canvas.setReadOnly(true); + setCommitError(undefined); try { const blob = await canvas.exportPng(); await onDone(new File([blob], drawingFileName(), { type: "image/png" })); - // Only once Done went through: after a failed save, Cancel still asks before discarding. - // The host may have closed the sheet already. canvasRef.current?.markSaved(); } catch (error) { console.error(error); - showErrorToast(t("editor.drawing.export-failed")); + const label = error instanceof DrawingActionError ? error.label : "editor.drawing.export-failed"; + setCommitError(label); + showErrorToast(t(label)); } finally { - setIsExporting(false); + busy.current = false; + canvasRef.current?.setReadOnly(Boolean(locked.current)); + if (alive.current) setIsExporting(false); } }; @@ -174,6 +271,7 @@ const DrawingSheet = ({ mode, initialScene, background, onDone, onClose }: Drawi size={size} aria-label={t(item.label)} icon={item.icon} + disabled={isExporting || isPreparing || prepareFailed || submissionPending} pressed={tool === item.name} onPressedChange={() => chooseTool(item.name)} /> @@ -196,6 +294,7 @@ const DrawingSheet = ({ mode, initialScene, background, onDone, onClose }: Drawi +
+ + } + onClick={() => void requestClose()} + disabled={isExporting} + /> + } + /> + {t("common.close")} + +
); + const exception = prepareFailed || commitError; const doneButton = ( - +
+ {exception && ( + } + disabled={isExporting} + onClick={() => { + if (prepareFailed) void setUpCanvas(); + }} + /> + )} + +
); return ( @@ -316,8 +438,9 @@ const DrawingSheet = ({ mode, initialScene, background, onDone, onClose }: Drawi // The sheet closes only through requestClose, which asks first when there are changes. eventDetails.cancel(); // Escape on the drawing surface leaves the current tool or selection; it belongs to the canvas. - const escapeOnSurface = eventDetails.reason === "escape-key" && surfaceRef.current?.contains(eventDetails.event.target as Node); - if (!escapeOnSurface) requestClose(); + const escapeOnSurface = + !isViewing && eventDetails.reason === "escape-key" && surfaceRef.current?.contains(eventDetails.event.target as Node); + if (!escapeOnSurface) void requestClose(); }} > @@ -328,29 +451,47 @@ const DrawingSheet = ({ mode, initialScene, background, onDone, onClose }: Drawi
- - + {loading ? ( +
+ +
+ ) : ( + <> + + + + )}
- {isWide ? ( - - {cancelButton} + + +
+ {cancelButton} + {!isWide && !isViewing && historyControls} +
+
+ {isWide && !isViewing && ( {toolRow} @@ -358,20 +499,72 @@ const DrawingSheet = ({ mode, initialScene, background, onDone, onClose }: Drawi {historyControls} - {viewControls} + } + onClick={() => fileInputRef.current?.click()} + /> - {doneButton} -
- ) : ( + )} + + {isViewing + ? onEdit && ( + + ) + : doneButton} + +
+ + + + + } + > + {Math.round(zoom * 100)}% + + + } disabled={zoom >= MAX_ZOOM} onClick={() => changeZoom(1.2)}> + {t("map.zoom-in")} + + } disabled={zoom <= MIN_ZOOM} onClick={() => changeZoom(1 / 1.2)}> + {t("map.zoom-out")} + + + } + onClick={() => { + canvasRef.current?.zoomToFit(); + syncZoom(); + }} + > + {t("editor.drawing.zoom-to-fit")} + + } + onClick={() => { + canvasRef.current?.zoomTo(1); + syncZoom(); + }} + > + {t("attachment-preview.reset-zoom")} + + + + + + {!isWide && !isViewing && ( <> - - {cancelButton} - - {historyControls} - {viewControls} - - {doneButton} - {/* The tools in thumb reach. Under 380px the divider goes and the bar nears the edges, so a 360px screen keeps 44px between targets. */} @@ -402,15 +595,23 @@ const DrawingSheet = ({ mode, initialScene, background, onDone, onClose }: Drawi {t(mode === "edit" ? "editor.drawing.discard-edit-title" : "editor.drawing.discard-title")} - {t(mode === "edit" ? "editor.drawing.discard-edit-description" : "editor.drawing.discard-description")} + {t(commitError ?? (mode === "edit" ? "editor.drawing.discard-edit-description" : "editor.drawing.discard-description"))} {t("editor.drawing.keep-drawing")}} /> - )} - - - -
- + onClose={() => { + if (!isEditing || background) onClose(); + else setIsEditing(false); + }} + /> ); }; -/** An icon-only ghost Button named by its Tooltip. */ -const IconAction = ({ label, icon, size, onClick }: { label: string; icon: ReactElement; size?: "sm"; onClick: () => void }) => ( - - } /> - {label} - -); - export default DrawingViewer; diff --git a/web/src/components/DrawingSheet/drawing.ts b/web/src/components/DrawingSheet/drawing.ts index 569da7dd3..74e3022b9 100644 --- a/web/src/components/DrawingSheet/drawing.ts +++ b/web/src/components/DrawingSheet/drawing.ts @@ -1,6 +1,7 @@ import type { Scene } from "@usememos/canvas"; import type { Attachment } from "@/types/proto/api/attachment_service_pb"; import { fetchAttachmentFile } from "@/utils/attachment"; +import type { Translations } from "@/utils/i18n"; /** * A drawing is a PNG attachment with its editable scene embedded. The name is a hint @@ -26,3 +27,17 @@ export const readDrawing = async (file: Blob): Promise => { const { scene } = await readScenePng(file); return scene ? { scene } : { background: file }; }; + +export class DrawingActionError extends Error { + constructor(public readonly label: Translations) { + super(label); + } +} + +export const sceneContent = (scene: Scene) => + JSON.stringify({ + elements: scene.elements, + files: scene.files, + background: scene.appState.viewBackgroundColor, + handDrawn: scene.appState.handDrawn, + }); diff --git a/web/src/components/MemoEditor/README.md b/web/src/components/MemoEditor/README.md index 5a02b8ac6..3f435ff84 100644 --- a/web/src/components/MemoEditor/README.md +++ b/web/src/components/MemoEditor/README.md @@ -61,7 +61,28 @@ The draft's attachments take the saved memo's shape: images, videos and drawings ### Drawings -A drawing is a PNG attachment made with [`@usememos/canvas`](https://github.com/usememos/canvas) (pinned to an exact version: it uses CalVer, so a version number does not signal breaking changes). The editable scene sits inside the file in a `zTXt` chunk named `memos-canvas`, and the name ends in `.canvas.png`. Everywhere outside the editor it is a plain image. The + menu's "Drawing" and the attachment row's "Edit drawing" open `components/DrawingSheet`, loaded on first use. It is a dialog that sits 24px inside the window from `md` up and fills the screen below that, with its controls floating on the paper (`DrawingFrame`). The package draws and edits the scene; the controls, strings, paper (`DRAWING_PAPER`, the same in every theme) and discard prompt are memos'. In a memo, a drawing opens in `DrawingViewer`, the same dialog with the canvas read-only, whose Edit saves in place. `useDrawing` owns the session: Done joins the draft through the same `LocalFile` path as a picked image, so the memo's save uploads it. "Edit drawing" reads the original file, never the thumbnail. Done on a file still in the draft swaps it in place. Done on a saved drawing keeps the attachment in the draft and queues the edit as a `LocalFile` with `replaces` set: the row shows the edit, and the save uploads it with `UploadAttachmentSpec.replace_attachment`, so the attachment keeps its name and place (`mergeUploadedAttachments`) while the server swaps the file and drops its thumbnail. Removing the pending row drops the edit. A saved drawing someone else uploaded stays, since only they or an admin may replace or remove it; its edit joins the draft as a new attachment. A file with the suffix but no readable scene opens as the background of a new drawing. The server must store `image/png` uploads unchanged, which `server/fileserver/drawing_png_test.go` checks. +The contract and acceptance cases are in +[`docs/design/drawing-annotation-and-recovery.md`](../../../../docs/design/drawing-annotation-and-recovery.md). +Canvas is pinned to `26.11.3`; its editable PNG remains an ordinary image outside the drawing UI. + +The insert menu starts a drawing. Ordinary local and instance-hosted images offer **Markup**; editable PNGs offer +**Edit markup**. Annotation loads the original bytes, opens a locked background with a clean undo baseline, and starts with red +ink. Applying it keeps the original and inserts a new `.canvas.png` beside it. Saved image previews provide the same annotation +flow, with **Save copy** binding directly to that memo. External images and motion-photo groups are excluded. + +The sheet has one short commit action: **Add** for new work, **Save** for edits, and **Save copy** for direct annotation or a copy +required by ownership. The editor's own save uploads pending files. An owned saved drawing uses `LocalFile.replaces`, preserving +its attachment name and links. Input is frozen before export until the host accepts or rejects it. Retries retain acknowledged +uploads in memory and finish the remaining bind or timestamp update; partial failures show an exception icon and tooltip. + +This first release has no Memos markup-draft UI or persistence. **Close** confirms discarding unsaved changes; it does not retain a +recoverable markup. There is no Continue entry, no markup-dependent memo-save blocker, and no permanent More/Download/Discard menu. +Normal states add no copy or badges to the canvas. Viewing and editing share one dialog and Canvas instance, retaining the visible content, pan and zoom across mode changes. Both modes keep a ghost X at the top left and the current action at the top right, without bordered action containers or a visible mode heading. A live zoom percentage opens the same four-action zoom menu in both modes (zoom in, zoom out, fit, reset to 100%). The trigger stays at the bottom left, above the phone tools bar and clear of the safe area. Editing adds the tools bar at the top center on desktop and at the bottom on phones. Available phone Undo/Redo actions follow X as quiet ghost icons; unavailable history actions are omitted. Returning to view focuses Edit; discarding restores the accepted scene. + +Canvas `26.11.3` provides checkpoints for a future recovery integration. The current editor's text-only localStorage draft behavior +is unchanged and excludes local file bytes. The server preserves editable PNGs unchanged (`server/fileserver/drawing_png_test.go`). +Browser regressions live in `tests/browser/`: run `pnpm test:drawings` after `pnpm exec playwright install chromium`. They verify +image preparation, original bytes/order, active Chinese text at export, desktop/360px controls, and view/edit content, viewport, focus and discard behavior. ### Suggestions diff --git a/web/src/components/MemoEditor/edit/Toolbar/EditorToolbar.tsx b/web/src/components/MemoEditor/edit/Toolbar/EditorToolbar.tsx index ca501f633..b445ec005 100644 --- a/web/src/components/MemoEditor/edit/Toolbar/EditorToolbar.tsx +++ b/web/src/components/MemoEditor/edit/Toolbar/EditorToolbar.tsx @@ -1,5 +1,5 @@ import { Button, Tooltip } from "@usememos/ui"; -import { CheckIcon } from "lucide-react"; +import { CheckIcon, CircleAlertIcon } from "lucide-react"; import { type FC, useId } from "react"; import { type Location, Visibility } from "@/types/proto/api/memo_service_pb"; import { useTranslate } from "@/utils/i18n"; @@ -32,6 +32,7 @@ export const EditorToolbar: FC = ({ const blockedReason = useEditorSelector((s) => validationService.canSave(s).reason); const blockedReasonDetail = useEditorSelector((s) => validationService.canSave(s).detail); const isSaving = useEditorSelector((s) => s.ui.isLoading.saving); + const drawingSaveError = useEditorSelector((s) => s.drawingSaveError); const justSaved = useEditorSelector((s) => s.ui.justSaved); const isUploading = useEditorSelector((s) => s.ui.isLoading.uploading); const location = useEditorSelector((s) => s.metadata.location); @@ -87,6 +88,7 @@ export const EditorToolbar: FC = ({ render={ + )}