Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/design/docs/docs-image-editing.md`:
- Around line 83-90: The docs for insertImage are out of sync: update the
documented signature and behavior to match the actual implementation's API
(insertImage(src, width, height, opts?) in packages/docs/src/view/editor.ts) and
note that it inserts at the caret (does not replace non-collapsed selections)
rather than replacing selections; adjust parameter names (naturalWidth→width,
naturalHeight→height, alt→opts) and describe the opts structure if applicable so
tests and callers aren't misled.
- Around line 148-179: Update the docs to reflect the actual rollout phases:
change any language in the "Floating Context Bar" and "Image Options Side Panel"
sections (and the other occurrence around lines noted) that claims these
features "ship in Phase 1" to indicate they are planned for later milestones
(Milestones 5 and 6) or mark them as Phase 2+ work; ensure the doc explicitly
references that these features are out-of-scope for Phase 1, mention that they
are pending in Milestones 5/6, and keep the feature descriptions but add a short
"Planned in later milestones" note under each heading.

In `@docs/tasks/active/20260412-docs-image-editing-todo.md`:
- Around line 129-132: Update the By-URL path note for
insertImageFromUrl(editor, url) to reflect that the preflight no longer forces
crossOrigin="anonymous"; instead validate the http[s]:// prefix, perform a
lightweight preflight/load without setting crossOrigin so we don't force CORS,
and document that natural dimensions are used and that callers should handle any
CORS requirements if they need cross-origin tainting protection.

In `@packages/frontend/src/app/docs/docs-formatting-toolbar.tsx`:
- Around line 147-152: The current handleUrlSubmit closes and clears the URL
form (closeAndReset) before insertImageFromUrl completes, losing user input on
failure; change handleUrlSubmit to await insertImageFromUrl(editor, url) and
only call closeAndReset() if that call returns a success true (or does not
throw), otherwise leave the form open and surface the error; update the
insertImageFromUrl helper to return a boolean success flag (or throw on fatal
errors) instead of swallowing failures so handleUrlSubmit can decide whether to
close the form; ensure you reference handleUrlSubmit, insertImageFromUrl,
closeAndReset, urlInput and editor when making these changes.

In `@packages/frontend/src/app/docs/image-insert.ts`:
- Around line 78-111: insertImageFromUrl currently persists third‑party
hotlinked URLs; change it to fetch/proxy and store the image on our trusted
storage before calling editor.insertImage so viewers won't hotlink external
hosts. Keep the existing validation and loadImageDimensions call to get
width/height, then call a new or existing helper (e.g. uploadImageFromUrl or
proxyFetchImage) to download and upload the remote image to first‑party storage
or return a proxied URL, and pass that returned hosted URL (not the original
trimmed URL) into EditorAPI.insertImage while preserving
originalWidth/originalHeight metadata and error handling.

---

Nitpick comments:
In `@packages/docs/src/model/types.ts`:
- Around line 274-287: In clampImageToWidth, add a guard for non-positive
maxWidth (e.g., if maxWidth <= 0) to avoid dividing by zero or producing invalid
scales; return the original { width, height } (same behavior as the existing
width <= 0 case) or normalize maxWidth to a safe minimum (Math.max(1, maxWidth))
before computing scale so the function never computes an invalid scale.

In `@packages/docs/src/view/editor.ts`:
- Around line 2077-2093: In dispose() add explicit cleanup for image-related
state: clear/reset the imageResizeDrag object (or set imageResizeDrag = null) to
drop any DOM measurement refs and any drag state, and set imageFileDropCallback
= null (and any other image-related callback vars) to remove closure references;
keep the rest of the existing listener removals and resource disposals (ruler,
cursor, textEditor, resizeObserver, canvas) intact. Ensure you reference the
same symbols used in this file (dispose, imageResizeDrag, imageFileDropCallback)
so the garbage collector can reclaim DOM-related memory when the editor is torn
down.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/docs/src/view/editor.ts`:
- Around line 1414-1435: The drop/paste flow (handleImageDrop) currently moves
the global cursor with cursor.moveTo then calls imageFileDropCallback(file),
which lets async uploads later insert at the current cursor instead of the
original drop position; capture the resolved DocPosition (use the hit from
paginatedPixelToPosition or the current cursor position if no hit) immediately
and pass that position (or an insertion closure bound to it) into
imageFileDropCallback instead of only the File so downstream code (e.g.,
insertImage) can insert at the original drop/paste location; apply the same
pattern to the other paste handler around the 2049-2058 area.
- Around line 1263-1299: handleImageResizeMouseUp and the related image-editing
paths (imageResizeDrag, handleImageResizeMouseMove, selection logic at
findImageAtOffset, and the mutation call doc.applyInlineStyle) are allowed to
run even when readOnly is true; guard these paths and the public mutating APIs
(insertImage, updateSelectedImage) with a check for !readOnly. Specifically,
before wiring event handlers or starting a drag/selection (where imageResizeDrag
is set and handleImageResizeMouseMove/handleImageResizeMouseUp are attached) and
before committing mutations (the docStore.snapshot()/doc.applyInlineStyle
sequence in handleImageResizeMouseUp), return early if readOnly is true;
likewise add the same !readOnly guard to insertImage and updateSelectedImage so
they no-op or throw when readOnly is set. Ensure rendering/cleanup still happens
(remove listeners, reset cursor) but prevent any state changes or
document.applyInlineStyle calls when readOnly is true.
- Around line 1352-1360: When an image is selected via findImageAtPoint (the
code path that sets selectedImage, calls cursor.moveTo and render), clear any
active text selection by calling selection.setRange(null) so printable keys
don't first clear selectedImage and then apply normal replace-selection
behavior; add the same selection.setRange(null) in the other image-selection
branch (the block around the second occurrence of selectedImage/cursor.moveTo at
the 2004-2010 area) to ensure consistent image-selection mode.