Introducing a new way to review your PRs.

Read the announcement

usememos / memos

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

View on GitHub

25 documents · Updated Nov 20, 2026

docs / drawing-attachments

Drawing attachments

Drawing attachments are editable canvas documents delivered as PNG files. They let a memo hold a drawing that can be viewed as a drawing, edited in place when the user has permission, and shown as a paper-like item in the attachment gallery.

This page builds on Memo lifecycle and collaboration. For related memo and attachment behavior, see Memo query filtering, Markdown content processing, Memo payload processing, Space management and membership, Memo archive import and export, and Attachment and object storage.

Drawing attachment format

The drawing format uses a PNG image as the attachment and stores the editable canvas scene inside that file. The .canvas.png suffix identifies the drawing in the user interface, but the embedded scene is the source of truth when the file opens. web/…/drawing.ts• L7-29

The format also supports older or incompatible files that have the drawing suffix but no readable scene. The editor treats such a file as a picture to draw on and keeps the original file unchanged. The new result then becomes a new drawing. web/…/drawing.ts• L14-29, web/…/useDrawing.ts• L63-75

References: web/…/drawing.ts• L7-29 web/…/useDrawing.ts• L63-75

Drawing creation and insertion

The drawing editor opens as a focused sheet over the memo editor. A new session creates a blank canvas, while a session opened from an existing drawing restores its scene. The editor exports the finished canvas as a PNG with an embedded scene and a drawing filename. web/…/DrawingSheet.tsx• L51-69, web/…/DrawingSheet.tsx• L241-261

The editor supports common drawing actions and image input without changing the memo until the user finishes the sheet. Users can choose drawing tools, set ink color and width, undo or redo, zoom to fit, insert images, or paste images. If an image has no scene, the editor first places it as a starting background and marks that setup as saved. The editor waits for this preparation to finish before it accepts the completed drawing. web/…/DrawingSheet.tsx• L145-175, web/…/DrawingSheet.tsx• L210-227

The sheet asks before discarding unsaved drawing changes. After the user selects Done, it keeps the sheet open when export or insertion into the host fails. It marks the canvas saved only after the host accepts the exported file. If an accepted upload already exists, discard can restore that accepted scene before the sheet closes. web/…/DrawingSheet.tsx• L235-262, web/…/DrawingSheet.tsx• L592-618

When the user completes a new drawing, the memo editor adds the exported file to its local attachment draft. The normal memo save then uploads it with the other new attachments and includes its attachment reference in the memo. web/…/useDrawing.ts• L90-115, web/…/memoService.ts• L130-136, web/…/memoService.ts• L163-180

References: web/…/DrawingSheet.tsx• L51-69 web/…/DrawingSheet.tsx• L145-175 web/…/DrawingSheet.tsx• L210-227 web/…/DrawingSheet.tsx• L235-262 web/…/DrawingSheet.tsx• L592-618 web/…/useDrawing.ts• L90-120 web/…/memoService.ts• L130-180

The attachment gallery recognizes a drawing by its image type and .canvas.png suffix. It presents the original PNG on a paper-colored surface instead of treating it as an ordinary framed image. The paper can extend beyond the image edges, so the drawing keeps a consistent sheet-like view at different sizes. web/…/AttachmentListView.tsx• L51-52, web/…/AttachmentListView.tsx• L88-109

The memo editor uses the same paper treatment for drawing tiles. A saved drawing with a pending edit is represented by the pending file and shows an edited state. The original stays bound to the memo but is hidden until the pending edit is removed. Inline insertion is disabled for that pending edit until the replacement is saved. web/…/AttachmentListEditor.tsx• L145-153, web/…/AttachmentListEditor.tsx• L412-428, web/…/AttachmentListEditor.tsx• L486-551

Selecting a drawing opens a read-only canvas viewer. The viewer loads the original attachment rather than its thumbnail because thumbnails do not contain the editable scene. If the scene cannot be read, the gallery falls back to the normal image viewer. web/…/drawing.ts• L17-29, web/…/AttachmentListView.tsx• L266-289

The viewer provides pan and zoom behavior through the read-only canvas. A user who can edit the memo can enter the drawing sheet from the viewer. The viewer uses a lazy-loaded drawing surface, so the canvas editor and viewer load on first drawing use rather than during normal memo editing. web/…/DrawingViewer.tsx• L120-146, web/…/DrawingViewer.tsx• L122-130, web/…/index.ts• L8-12

The drawing dialog uses one responsive surface for viewing and editing. On wide screens it sits inside a nearly full-window inset, while on narrow screens it fills the screen. The paper stays edge to edge and the controls float above it. web/…/DrawingFrame.tsx• L6-23, web/…/DrawingSheet.tsx• L433-590, web/…/DrawingViewer.tsx• L120-146

The main viewing and editing flow is:

flowchart LR
    A[Attachment gallery] --> B{Drawing suffix?}
    B -- No --> C[Normal media viewer]
    B -- Yes --> D[Read original PNG]
    D --> E{Readable scene?}
    E -- No --> C
    E -- Yes --> F[Read-only drawing viewer]
    F --> G{Edit allowed?}
    G -- No --> H[View and zoom]
    G -- Yes --> I[Drawing editor]
    I --> J[Export PNG with scene]
    J --> K[Replace or add attachment]

The viewer keeps the attachment state in sync after a successful edit. It replaces the displayed attachment with the upload result and restores the saved scene, so the user returns to the updated drawing instead of a stale canvas. web/…/DrawingViewer.tsx• L109-118

References: web/…/AttachmentListView.tsx• L266-289 web/…/AttachmentListEditor.tsx• L145-153 web/…/AttachmentListEditor.tsx• L412-428 web/…/AttachmentListEditor.tsx• L486-551 web/…/DrawingFrame.tsx• L6-23 web/…/DrawingViewer.tsx• L49-68 web/…/DrawingViewer.tsx• L109-146 web/…/index.ts• L8-12

Canvas theme handling

Drawings use a fixed light paper and ink palette so the same drawing remains readable in light and dark memo themes. The exported paper is part of the drawing, so an older drawing keeps the paper on which it was made. The surrounding dialog controls still follow the application theme. web/…/useCanvasTheme.ts• L4-8, web/…/useCanvasTheme.ts• L28-42

The editor follows the memo application's sans-serif font for text drawn on the canvas. The default ink can follow the fixed drawing palette, while the editor also offers a set of colors that are chosen for contrast on the paper. web/…/useCanvasTheme.ts• L11-25, web/…/DrawingSheet.tsx• L94-107, web/…/DrawingSheet.tsx• L286-349

The drawing dialog adapts its layout to the screen. On wide screens the controls float in a top bar. On narrow screens the drawing stays full-screen, the main actions stay at the top, and the tool controls move to the bottom for touch access. Safe-area spacing keeps the floating controls clear of device edges. web/…/DrawingFrame.tsx• L27-65, web/…/DrawingSheet.tsx• L487-590

References: web/…/useCanvasTheme.ts• L4-42 web/…/DrawingSheet.tsx• L94-107 web/…/DrawingSheet.tsx• L286-349 web/…/DrawingFrame.tsx• L6-23 web/…/DrawingFrame.tsx• L27-65 web/…/DrawingSheet.tsx• L487-590

Attachment replacement behavior

An edit of a drawing can replace the saved attachment only when the current user may manage that attachment. The replacement keeps the attachment identity and its memo link, so existing references continue to point to the updated drawing. An edit of another user's drawing becomes a separate attachment beside the original. web/…/DrawingViewer.tsx• L70-87, web/…/user.ts• L7-16, web/…/useDrawing.ts• L27-34, web/…/useDrawing.ts• L95-115

The viewer re-reads the memo and source attachment before it saves. For an allowed replacement, it compares the current scene with the scene that was opened. If another edit changed the source, it switches to a copy instead of overwriting that edit. A replacement uploads with the current attachment name and then updates only the memo time. A copy remains uploaded until the memo update links both the original and the new file. If that memo update fails, the viewer retains the uploaded copy as the next replacement target, so a retry does not create another copy. web/…/DrawingViewer.tsx• L70-108, web/…/drawing.ts• L37-43

After either kind of save succeeds, the viewer reads the exported file again and replaces its local attachment and scene state. This returns the viewer to the new drawing and prevents the old canvas from remaining visible after an edit. web/…/DrawingViewer.tsx• L109-118

The memo save keeps replacement uploads separate from new attachment uploads. It updates the memo first, then uploads the replacement and stamps the memo update time. This order avoids changing a saved drawing when the rest of the memo save is refused. New memo creation handles replacements before the memo becomes visible. web/…/memoService.ts• L130-167

The upload request carries the target attachment name as a replacement marker. The server checks the target again when the upload finishes, confirms permission and storage state, writes the new object, points the existing attachment row to it, and removes the old object afterward. Per-attachment locking prevents concurrent replacements from deleting the wrong prior object. web/…/uploadService.ts• L13-61, server/…/attachment_service_replace.go• L21-31, server/…/attachment_service_replace.go• L115-235

The replacement flow protects the attachment from partial storage changes. A failed upload leaves the current drawing available. A committed row update is retained even if cleanup or the response reload fails, and later retry logic can remove the old object without removing the new one. server/…/attachment_service_replace.go• L166-231, server/…/attachment_service_replace.go• L238-266

sequenceDiagram
    participant E as Drawing editor
    participant M as Memo save
    participant U as Attachment upload
    participant S as Attachment service
    participant R as Existing attachment

    E->>M: Return exported drawing
    M->>U: Upload with replacement target
    U->>S: Send spec and file data
    S->>R: Check permission and current state
    S->>S: Store new object
    S->>R: Update existing attachment row
    S->>S: Remove old object
    S-->>M: Return updated attachment
    M->>M: Stamp memo update time

References: web/…/DrawingViewer.tsx• L70-118 web/…/drawing.ts• L37-43 web/…/user.ts• L7-16 web/…/useDrawing.ts• L27-34 web/…/useDrawing.ts• L95-115 web/…/uploadService.ts• L13-61 web/…/memoService.ts• L130-167 server/…/attachment_service_replace.go• L21-31 server/…/attachment_service_replace.go• L115-235 server/…/attachment_service_replace.go• L238-266

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the .canvas.png detection rule aligned with the exported drawing filename and gallery routing.
  • Keep replacement markers aligned across the editor decision, upload request, server validation, and memo save order.
  • Preserve the distinction between the original drawing file and its thumbnail. Only the original can restore the editable scene.
  • Keep the permission result consistent between viewer replacement decisions and server replacement checks.
  • Keep the scene baseline comparison aligned with the scene fields that define a saved drawing.
  • Keep the displayed attachment and scene updated after a successful viewer edit.
  • Keep pending replacement files hidden from the original gallery item and unavailable for inline insertion until save completes.
  • Keep fixed paper and palette values compatible with gallery paper presentation and saved drawing readability.
  • Keep the responsive dialog surface stable so changing screen width does not reset the canvas session.
  • Keep background image preparation complete before Done can export a drawing.

Important failure modes

TriggerConsequenceGuard
A drawing file has no readable embedded sceneThe canvas editor cannot restore its objectsOpen it as a background picture and leave the original attachment unchanged
The original file is replaced by a thumbnail during openThe scene cannot be restoredFetch the original attachment file for drawing reads
A user edits an attachment they cannot manageThe original could be overwritten without permissionAdd the edit as a new attachment and re-check permission on the server
The source changes after the viewer opens itA newer drawing could be overwrittenCompare the current scene with the opened baseline and save as a copy
A memo update fails after a copy uploadThe copy could be uploaded again on retryKeep the uploaded copy as the retry replacement target
A user account changes while a save is in progressThe result could be applied under the wrong accountAbort the drawing action when the active account no longer matches
Replacement storage succeeds but old-object cleanup failsThe attachment works but an orphaned old object remainsKeep the row pointed at the new object and retry cleanup safely
A memo save fails after a replacement is made too earlyThe saved drawing could change despite a refused memo saveUpload replacements after the existing memo update
A pending replacement is inserted into memo text before saveThe old attachment could be overwritten or duplicatedHide the original gallery item and disable inline insertion for the pending edit
A background image is still loading when drawing input startsThe first marks can be lost or become part of the saved setupBlock the drawing surface and Done action until background setup finishes
Export or host insertion fails after Done startsThe sheet can close with changes that were not savedKeep the sheet open and mark the canvas saved only after success

Key files

FileWhy to read it
web/…/drawing.tsDefines the drawing filename rule, original-file read, and scene comparison contract.
web/…/DrawingSheet.tsxShows the creation, image setup, export, discard, and responsive editing experience.
web/…/DrawingFrame.tsxDefines the shared responsive dialog and floating control surfaces.
web/…/DrawingViewer.tsxShows read-only viewing, edit access, concurrent-change checks, attachment state refresh, and save-back behavior.
web/…/useCanvasTheme.tsDefines the stable paper, ink, color, and font choices.
web/…/useDrawing.tsConnects drawing sessions to new, local, and saved attachment targets.
web/…/memoService.tsDefines when new uploads and replacement uploads affect memo saving.
web/…/uploadService.tsCarries replacement intent through attachment upload.
server/…/attachment_service_replace.goDefines server-side replacement checks and safe object transition.
web/…/AttachmentListView.tsxDefines saved-gallery presentation and routing into the drawing viewer.
web/…/AttachmentListEditor.tsxDefines draft-gallery treatment for drawings and pending replacement visibility.