From be97e14f9e761630527ff1ba3067316e07f34148 Mon Sep 17 00:00:00 2001
From: Aleksandr Soloshenko <capcom2me@gmail.com>
Date: Fri, 31 Jul 2026 07:45:51 +0700
Subject: [PATCH] [attachments] inline images support

---
 frontend/src/app.css                          |   5 +
 .../src/lib/components/CommentForm.svelte     |  55 ++++++--
 .../src/lib/components/CommentList.svelte     | 102 ++++++++++++--
 .../lib/components/InlineImageButton.svelte   |  39 ++++++
 frontend/src/lib/components/TaskForm.svelte   |  59 ++++++++-
 .../src/lib/inline-image-editor.svelte.ts     | 124 ++++++++++++++++++
 frontend/src/lib/pages/task-detail.svelte     |  42 +++---
 frontend/src/lib/pages/task-edit.svelte       |   1 +
 frontend/src/lib/resolve-attachment-refs.ts   |  29 ++++
 frontend/src/lib/upload-image.ts              |  67 ++++++++++
 internal/attachments/service.go               |   6 +
 internal/storage/service.go                   |   1 +
 12 files changed, 483 insertions(+), 47 deletions(-)
 create mode 100644 frontend/src/lib/components/InlineImageButton.svelte
 create mode 100644 frontend/src/lib/inline-image-editor.svelte.ts
 create mode 100644 frontend/src/lib/resolve-attachment-refs.ts
 create mode 100644 frontend/src/lib/upload-image.ts

diff --git a/frontend/src/app.css b/frontend/src/app.css
index 054b4ce..118d0e6 100644
--- a/frontend/src/app.css
+++ b/frontend/src/app.css
@@ -94,4 +94,9 @@
   .prose a:hover {
     color: hsl(var(--muted-foreground));
   }
+  .prose img {
+    max-width: 100%;
+    height: auto;
+    border-radius: 0.375rem;
+  }
 }
\ No newline at end of file
diff --git a/frontend/src/lib/components/CommentForm.svelte b/frontend/src/lib/components/CommentForm.svelte
index 8d6f63b..d5fd8f5 100644
--- a/frontend/src/lib/components/CommentForm.svelte
+++ b/frontend/src/lib/components/CommentForm.svelte
@@ -1,25 +1,41 @@
 <script lang="ts">
   import { Textarea } from "$lib/components/ui/textarea";
   import { Button } from "$lib/components/ui/button";
+  import InlineImageButton from "$lib/components/InlineImageButton.svelte";
+  import { InlineImageEditor } from "$lib/inline-image-editor.svelte";
   import { toast } from "$lib/toast";
 
   let {
+    taskId = 0,
     onSubmit = async (_content: string) => {},
   }: {
+    taskId?: number;
     onSubmit: (content: string) => Promise<void>;
   } = $props();
 
   let text = $state("");
   let posting = $state(false);
+  let textareaEl: HTMLTextAreaElement | undefined = $state();
+  let fileInput: HTMLInputElement | undefined = $state();
+
+  const images = new InlineImageEditor({
+    getTaskId: () => taskId,
+    getValue: () => text,
+    setValue: (v) => {
+      text = v;
+    },
+    getTextarea: () => textareaEl,
+  });
 
   async function handleSubmit() {
     if (!text.trim()) return;
+    if (images.uploading) return;
     posting = true;
     try {
       await onSubmit(text.trim());
       text = "";
-    } catch (e: any) {
-      toast.error(e.message || "Failed to add comment");
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "Failed to add comment");
     } finally {
       posting = false;
     }
@@ -27,15 +43,34 @@
 </script>
 
 <div>
-  <Textarea
-    bind:value={text}
-    placeholder="Add a comment..."
-    class="mb-2 min-h-20"
-  />
-  <Button
-    onclick={handleSubmit}
-    disabled={posting || !text.trim()}
+  <!-- svelte-ignore a11y_no_static_element_interactions -->
+  <div
+    ondragover={(e) => images.handleDragOver(e)}
+    ondrop={(e) => images.handleImageDrop(e)}
   >
+    <Textarea
+      bind:value={text}
+      bind:this={textareaEl}
+      onpaste={(e) => images.handleImagePaste(e)}
+      placeholder="Add a comment..."
+      class="mb-2 min-h-20"
+    />
+  </div>
+  <div class="mb-2 flex items-center gap-2">
+    <InlineImageButton
+      uploading={images.uploading}
+      disabled={!taskId}
+      onclick={() => fileInput?.click()}
+    />
+    <input
+      type="file"
+      bind:this={fileInput}
+      accept="image/png,image/jpeg,image/gif,image/webp"
+      class="hidden"
+      onchange={(e) => images.handleImagePick(e)}
+    />
+  </div>
+  <Button onclick={handleSubmit} disabled={posting || images.uploading || !text.trim()}>
     {posting ? "Posting..." : "Comment"}
   </Button>
 </div>
diff --git a/frontend/src/lib/components/CommentList.svelte b/frontend/src/lib/components/CommentList.svelte
index 5ca1499..53cf56d 100644
--- a/frontend/src/lib/components/CommentList.svelte
+++ b/frontend/src/lib/components/CommentList.svelte
@@ -2,8 +2,11 @@
   import { Avatar, AvatarFallback } from "$lib/components/ui/avatar";
   import { Button } from "$lib/components/ui/button";
   import { Textarea } from "$lib/components/ui/textarea";
+  import InlineImageButton from "$lib/components/InlineImageButton.svelte";
   import { parse } from "marked";
   import { processAutoLinks } from "$lib/autolink";
+  import { resolveAttachmentRefs } from "$lib/resolve-attachment-refs";
+  import { InlineImageEditor } from "$lib/inline-image-editor.svelte";
   import DOMPurify from "dompurify";
   import type { AutoLinkContext } from "$lib/autolink";
   import type { Comment } from "$lib/types/api";
@@ -13,12 +16,16 @@
   let {
     comments = [] as Comment[],
     currentUserId = 0,
+    taskId = 0,
+    attachmentsMap = new Map<number, string>(),
     autoLinkCtx = {} as AutoLinkContext,
     onEdit = async (_commentId: number, _content: string) => {},
     onDelete = async (_commentId: number) => {},
   }: {
     comments: Comment[];
     currentUserId: number;
+    taskId?: number;
+    attachmentsMap: Map<number, string>;
     autoLinkCtx: AutoLinkContext;
     onEdit: (commentId: number, content: string) => Promise<void>;
     onDelete: (commentId: number) => Promise<void>;
@@ -27,6 +34,18 @@
   let editingId = $state<number | null>(null);
   let editText = $state("");
   let saving = $state(false);
+  let editTextarea: HTMLTextAreaElement | undefined = $state();
+  let fileInput: HTMLInputElement | undefined = $state();
+
+  const images = new InlineImageEditor({
+    getTaskId: () => taskId,
+    getValue: () => editText,
+    setValue: (v) => {
+      editText = v;
+    },
+    getTextarea: () => editTextarea,
+    getSessionId: () => editingId,
+  });
 
   function formatDateTime(d: string): string {
     return new Date(d).toLocaleString();
@@ -44,18 +63,24 @@
   function renderMarkdown(text: string): string {
     if (!text) return "";
     return DOMPurify.sanitize(
-      parse(processAutoLinks(text, autoLinkCtx), {
-        async: false,
-      }) as string,
+      parse(
+        processAutoLinks(
+          resolveAttachmentRefs(text, attachmentsMap),
+          autoLinkCtx,
+        ),
+        { async: false },
+      ) as string,
     );
   }
 
   function startEdit(comment: Comment) {
+    if (images.uploading) return;
     editingId = comment.id;
     editText = comment.content;
   }
 
   function cancelEdit() {
+    if (images.uploading) return;
     editingId = null;
     editText = "";
   }
@@ -71,8 +96,8 @@
       await onEdit(commentId, editText);
       editingId = null;
       editText = "";
-    } catch (e: any) {
-      toast.error(e.message || "Failed to update comment");
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "Failed to update comment");
     } finally {
       saving = false;
     }
@@ -97,18 +122,63 @@
         </div>
 
         {#if editingId === comment.id}
-          <Textarea bind:value={editText} class="mb-2 min-h-16" />
+          <!-- svelte-ignore a11y_no_static_element_interactions -->
+          <div
+            ondragover={(e) => {
+              if (saving) {
+                e.preventDefault();
+                return;
+              }
+              images.handleDragOver(e);
+            }}
+            ondrop={(e) => {
+              if (saving) {
+                e.preventDefault();
+                return;
+              }
+              images.handleImageDrop(e);
+            }}
+          >
+            <Textarea
+              bind:value={editText}
+              bind:this={editTextarea}
+              onpaste={(e) => {
+                if (!saving) images.handleImagePaste(e);
+              }}
+              class="mb-2 min-h-16"
+            />
+          </div>
+          <div class="mb-2 flex items-center gap-2">
+            <InlineImageButton
+              uploading={images.uploading}
+              disabled={!taskId || saving}
+              onclick={() => fileInput?.click()}
+            />
+            <input
+              type="file"
+              disabled={saving || images.uploading}
+              bind:this={fileInput}
+              accept="image/png,image/jpeg,image/gif,image/webp"
+              class="hidden"
+              onchange={(e) => images.handleImagePick(e)}
+            />
+          </div>
           <div class="flex gap-2">
             <Button
               size="sm"
               onclick={() => handleEdit(comment.id)}
-              disabled={saving}
+              disabled={saving || images.uploading}
             >
               {saving ? "Saving..." : "Save"}
             </Button>
-            <Button size="sm" variant="ghost" onclick={cancelEdit}
-              >Cancel</Button
+            <Button
+              size="sm"
+              variant="ghost"
+              onclick={cancelEdit}
+              disabled={images.uploading}
             >
+              Cancel
+            </Button>
           </div>
         {:else}
           <div class="prose prose-sm dark:prose-invert max-w-none text-sm">
@@ -117,17 +187,23 @@
           {#if canManageComment(comment)}
             <div class="mt-1 flex gap-2">
               <button
-                class="text-muted-foreground hover:text-foreground cursor-pointer text-xs underline underline-offset-2"
+                class="text-muted-foreground hover:text-foreground cursor-pointer text-xs underline underline-offset-2 disabled:opacity-50 disabled:no-underline"
+                disabled={images.uploading}
                 onclick={() => startEdit(comment)}>Edit</button
               >
               <button
-                class="text-muted-foreground hover:text-destructive cursor-pointer text-xs underline underline-offset-2"
+                class="text-muted-foreground hover:text-destructive cursor-pointer text-xs underline underline-offset-2 disabled:opacity-50 disabled:no-underline"
+                disabled={images.uploading}
                 onclick={async () => {
                   if (confirm("Delete this comment?")) {
                     try {
                       await onDelete(comment.id);
-                    } catch (e: any) {
-                      toast.error(e.message || "Failed to delete comment");
+                    } catch (e) {
+                      toast.error(
+                        e instanceof Error
+                          ? e.message
+                          : "Failed to delete comment",
+                      );
                     }
                   }
                 }}>Delete</button
diff --git a/frontend/src/lib/components/InlineImageButton.svelte b/frontend/src/lib/components/InlineImageButton.svelte
new file mode 100644
index 0000000..8b96992
--- /dev/null
+++ b/frontend/src/lib/components/InlineImageButton.svelte
@@ -0,0 +1,39 @@
+<script lang="ts">
+  let {
+    uploading = false,
+    disabled = false,
+    onclick,
+  }: {
+    uploading?: boolean;
+    disabled?: boolean;
+    onclick: () => void;
+  } = $props();
+</script>
+
+<button
+  type="button"
+  {onclick}
+  disabled={disabled || uploading}
+  class="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-xs font-medium text-muted-foreground hover:bg-muted hover:text-foreground disabled:opacity-50"
+  title="Insert image"
+>
+  {#if uploading}
+    <span
+      class="size-3 animate-spin rounded-full border-2 border-current border-t-transparent"
+    ></span>
+    Uploading...
+  {:else}
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 20 20"
+      fill="currentColor"
+      class="size-4"
+      ><path
+        fill-rule="evenodd"
+        d="M1 5.25A2.25 2.25 0 0 1 3.25 3h13.5A2.25 2.25 0 0 1 19 5.25v9.5A2.25 2.25 0 0 1 16.75 17H3.25A2.25 2.25 0 0 1 1 14.75v-9.5Zm1.5 5.81v3.69c0 .414.336.75.75.75h13.5a.75.75 0 0 0 .75-.75v-2.69l-2.22-2.219a.75.75 0 0 0-1.06 0l-1.91 1.909.47.47a.75.75 0 1 1-1.06 1.06L6.53 8.091a.75.75 0 0 0-1.06 0l-2.97 2.97ZM12 7a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"
+        clip-rule="evenodd"
+      /></svg
+    >
+    Image
+  {/if}
+</button>
diff --git a/frontend/src/lib/components/TaskForm.svelte b/frontend/src/lib/components/TaskForm.svelte
index 14a78bc..500980c 100644
--- a/frontend/src/lib/components/TaskForm.svelte
+++ b/frontend/src/lib/components/TaskForm.svelte
@@ -6,6 +6,8 @@
   import AssigneeCombobox from "$lib/components/AssigneeCombobox.svelte";
   import * as Card from "$lib/components/ui/card";
   import { PRIORITIES, KINDS, STATUSES, type Project } from "$lib/types/api";
+  import InlineImageButton from "$lib/components/InlineImageButton.svelte";
+  import { InlineImageEditor } from "$lib/inline-image-editor.svelte";
 
   interface TaskFormData {
     project_slug: string;
@@ -20,6 +22,7 @@
 
   interface Props {
     mode?: "create" | "edit";
+    taskId?: number;
     projects?: Project[];
     initialTitle?: string;
     initialDescription?: string;
@@ -37,6 +40,7 @@
 
   let {
     mode = "create",
+    taskId = 0,
     projects = [] as Project[],
     initialTitle = "",
     initialDescription = "",
@@ -74,6 +78,17 @@
 
   let saving = $state(false);
   let error = $state("");
+  let descriptionTextarea: HTMLTextAreaElement | undefined = $state();
+  let fileInput: HTMLInputElement | undefined = $state();
+
+  const images = new InlineImageEditor({
+    getTaskId: () => taskId,
+    getValue: () => description,
+    setValue: (v) => {
+      description = v;
+    },
+    getTextarea: () => descriptionTextarea,
+  });
 
   async function handleSubmit() {
     if (!title.trim()) {
@@ -84,6 +99,7 @@
       error = "Project is required";
       return;
     }
+    if (images.uploading) return;
     saving = true;
     error = "";
 
@@ -154,12 +170,41 @@
       </div>
 
       <div class="space-y-1.5">
-        <label for="description" class="text-sm font-medium">Description</label>
-        <Textarea
-          id="description"
-          bind:value={description}
-          placeholder="Optional description (supports Markdown)"
-          class="min-h-32"
+        <div class="flex items-center justify-between">
+          <label for="description" class="text-sm font-medium"
+            >Description</label
+          >
+          {#if taskId > 0}
+            <InlineImageButton
+              uploading={images.uploading}
+              onclick={() => fileInput?.click()}
+            />
+          {:else}
+            <span class="text-xs text-muted-foreground"
+              >Image upload available when editing</span
+            >
+          {/if}
+        </div>
+        <!-- svelte-ignore a11y_no_static_element_interactions -->
+        <div
+          ondragover={(e) => images.handleDragOver(e)}
+          ondrop={(e) => images.handleImageDrop(e)}
+        >
+          <Textarea
+            id="description"
+            bind:value={description}
+            bind:this={descriptionTextarea}
+            onpaste={(e) => images.handleImagePaste(e)}
+            placeholder="Optional description (supports Markdown)"
+            class="min-h-32"
+          />
+        </div>
+        <input
+          type="file"
+          bind:this={fileInput}
+          accept="image/png,image/jpeg,image/gif,image/webp"
+          class="hidden"
+          onchange={(e) => images.handleImagePick(e)}
         />
       </div>
 
@@ -244,7 +289,7 @@
       {/if}
 
       <div class="flex gap-2 pt-2">
-        <Button type="submit" disabled={saving}>
+        <Button type="submit" disabled={saving || images.uploading}>
           {saving
             ? mode === "edit"
               ? "Saving..."
diff --git a/frontend/src/lib/inline-image-editor.svelte.ts b/frontend/src/lib/inline-image-editor.svelte.ts
new file mode 100644
index 0000000..d319418
--- /dev/null
+++ b/frontend/src/lib/inline-image-editor.svelte.ts
@@ -0,0 +1,124 @@
+import { uploadInlineImage, type UploadResult } from "$lib/upload-image";
+import { toast } from "$lib/toast";
+
+export function attachmentMarkdown(result: UploadResult): string {
+  const name = result.fileName
+    .replace(/\.[^.]+$/, "")
+    .replace(/[[\]\\]/g, "");
+  return `![${name}](attachment:${result.attachmentId})`;
+}
+
+export function insertAtCursor(
+  el: HTMLTextAreaElement | undefined,
+  current: string,
+  insertion: string,
+  setValue: (next: string) => void,
+): void {
+  if (!el) {
+    setValue(current + insertion);
+    return;
+  }
+  const start = el.selectionStart ?? current.length;
+  const end = el.selectionEnd ?? start;
+  setValue(current.slice(0, start) + insertion + current.slice(end));
+  requestAnimationFrame(() => {
+    const pos = start + insertion.length;
+    el.selectionStart = pos;
+    el.selectionEnd = pos;
+    el.focus();
+  });
+}
+
+export type InlineImageEditorOptions = {
+  getTaskId: () => number;
+  getValue: () => string;
+  setValue: (value: string) => void;
+  getTextarea: () => HTMLTextAreaElement | undefined;
+  getSessionId?: () => unknown;
+};
+
+export class InlineImageEditor {
+  uploading = $state(false);
+
+  #opts: InlineImageEditorOptions;
+
+  constructor(opts: InlineImageEditorOptions) {
+    this.#opts = opts;
+  }
+
+  async uploadAndInsert(file: File): Promise<void> {
+    const taskId = this.#opts.getTaskId();
+    if (!taskId) return;
+    if (this.uploading) {
+      toast("Image upload already in progress");
+      return;
+    }
+
+    const sessionId = this.#opts.getSessionId?.();
+    this.uploading = true;
+    try {
+      const result = await uploadInlineImage(taskId, file);
+      if (
+        this.#opts.getSessionId &&
+        this.#opts.getSessionId() !== sessionId
+      ) {
+        toast("Image uploaded, but the comment is no longer being edited");
+        return;
+      }
+      insertAtCursor(
+        this.#opts.getTextarea(),
+        this.#opts.getValue(),
+        attachmentMarkdown(result),
+        this.#opts.setValue,
+      );
+      toast.success("Image uploaded");
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "Image upload failed");
+    } finally {
+      this.uploading = false;
+    }
+  }
+
+  handleImagePick(e: Event): void {
+    const input = e.target as HTMLInputElement;
+    const file = input.files?.[0];
+    if (file) void this.uploadAndInsert(file);
+    input.value = "";
+  }
+
+  handleImagePaste(e: ClipboardEvent): void {
+    if (!this.#opts.getTaskId()) return;
+    const items = e.clipboardData?.items;
+    if (!items) return;
+    for (const item of items) {
+      if (item.kind === "file" && item.type.startsWith("image/")) {
+        e.preventDefault();
+        const file = item.getAsFile();
+        if (file) void this.uploadAndInsert(file);
+        return;
+      }
+    }
+  }
+
+  async handleImageDrop(e: DragEvent): Promise<void> {
+    if (!this.#opts.getTaskId()) return;
+    e.preventDefault();
+    const files = e.dataTransfer?.files;
+    if (!files) return;
+    for (let i = 0; i < files.length; i++) {
+      const file = files[i];
+      if (file.type.startsWith("image/")) {
+        await this.uploadAndInsert(file);
+      } else {
+        toast.error(
+          `"${file.name}" is not an image. Only images can be dropped.`,
+        );
+      }
+    }
+  }
+
+  handleDragOver(e: DragEvent): void {
+    if (!this.#opts.getTaskId()) return;
+    e.preventDefault();
+  }
+}
diff --git a/frontend/src/lib/pages/task-detail.svelte b/frontend/src/lib/pages/task-detail.svelte
index 3afd87f..41ad8c5 100644
--- a/frontend/src/lib/pages/task-detail.svelte
+++ b/frontend/src/lib/pages/task-detail.svelte
@@ -20,9 +20,10 @@
   import * as Card from "$lib/components/ui/card";
   import { parse } from "marked";
   import DOMPurify from "dompurify";
-  import type { TaskDetails, Comment, Attachment } from "$lib/types/api";
+  import type { TaskDetails, Attachment } from "$lib/types/api";
   import { STATUSES } from "$lib/types/api";
   import { processAutoLinks } from "$lib/autolink";
+  import { resolveAttachmentRefs } from "$lib/resolve-attachment-refs";
   import type { AutoLinkContext } from "$lib/autolink";
   import { toast } from "$lib/toast";
 
@@ -51,12 +52,20 @@
     repoUrl: task?.project.repo_url || undefined,
   });
 
+  let attachmentUrls = $derived(
+    new Map(task?.attachments?.map((a) => [a.id, a.download_url]) ?? []),
+  );
+
   let renderedDescription = $derived(
     task?.description
       ? DOMPurify.sanitize(
-          parse(processAutoLinks(task.description, autoLinkCtx), {
-            async: false,
-          }) as string,
+          parse(
+            processAutoLinks(
+              resolveAttachmentRefs(task.description, attachmentUrls),
+              autoLinkCtx,
+            ),
+            { async: false },
+          ) as string,
         )
       : "",
   );
@@ -127,21 +136,18 @@
   }
 
   async function handleAddComment(content: string) {
-    const created = await createComment(taskId, { content });
-    task = {
-      ...task!,
-      comments: [...task!.comments, created as Comment],
-    };
+    await createComment(taskId, { content });
+    // Refetch the task so the freshly-confirmed inline attachment is present in
+    // task.attachments (attachmentUrls derives from it), letting the newly
+    // posted comment's inline image resolve without a manual page refresh.
+    const refreshed = await getTaskByProjectAndNumber(slug, number);
+    task = refreshed;
   }
 
   async function handleEditComment(commentId: number, content: string) {
-    const updated = await updateComment(taskId, commentId, { content });
-    task = {
-      ...task!,
-      comments: task!.comments.map((c) =>
-        c.id === commentId ? (updated as Comment) : c,
-      ),
-    };
+    await updateComment(taskId, commentId, { content });
+    const refreshed = await getTaskByProjectAndNumber(slug, number);
+    task = refreshed;
   }
 
   async function handleDeleteComment(commentId: number) {
@@ -251,12 +257,14 @@
             <CommentList
               comments={task.comments}
               {currentUserId}
+              taskId={task.id}
+              attachmentsMap={attachmentUrls}
               {autoLinkCtx}
               onEdit={handleEditComment}
               onDelete={handleDeleteComment}
             />
             <div class="mt-4">
-              <CommentForm onSubmit={handleAddComment} />
+              <CommentForm taskId={task.id} onSubmit={handleAddComment} />
             </div>
           </div>
         </div>
diff --git a/frontend/src/lib/pages/task-edit.svelte b/frontend/src/lib/pages/task-edit.svelte
index a9cf1af..fd23b12 100644
--- a/frontend/src/lib/pages/task-edit.svelte
+++ b/frontend/src/lib/pages/task-edit.svelte
@@ -75,6 +75,7 @@
   {:else if task}
     <TaskForm
       mode="edit"
+      {taskId}
       {projects}
       initialTitle={task.title}
       initialDescription={task.description || ""}
diff --git a/frontend/src/lib/resolve-attachment-refs.ts b/frontend/src/lib/resolve-attachment-refs.ts
new file mode 100644
index 0000000..d56c998
--- /dev/null
+++ b/frontend/src/lib/resolve-attachment-refs.ts
@@ -0,0 +1,29 @@
+/**
+ * Replaces Markdown image references using attachment IDs with actual presigned S3 URLs.
+ *
+ * Transforms: ![alt text](attachment:123)
+ * Into:       ![alt text](<presigned-s3-url>)
+ *
+ * URLs are resolved from the attachmentsMap (id -> presigned download URL).
+ * This avoids sending JWTs in <img> src attributes — the presigned S3 URL
+ * is a time-limited, resource-specific URL that requires no auth header.
+ *
+ * If the attachment ID is not found in the map, the reference is left
+ * unresolved (renders as broken image / alt text) rather than silently failing.
+ */
+export function resolveAttachmentRefs(
+  text: string,
+  attachmentsMap: Map<number, string>,
+): string {
+  if (!attachmentsMap.size) return text;
+  return text.replace(
+    /!\[([^\]]*)\]\(attachment:(\d+)\)/g,
+    (_match, alt, id) => {
+      const url = attachmentsMap.get(Number(id));
+      // angle-bracket destination so presigned URLs containing `)` or
+      // whitespace are not parsed as malformed Markdown image destinations
+      if (url) return `![${alt}](<${url}>)`;
+      return _match; // leave unresolved if attachment not found
+    },
+  );
+}
diff --git a/frontend/src/lib/upload-image.ts b/frontend/src/lib/upload-image.ts
new file mode 100644
index 0000000..421d12d
--- /dev/null
+++ b/frontend/src/lib/upload-image.ts
@@ -0,0 +1,67 @@
+import { initUpload, confirmUpload } from "$lib/api/attachments";
+
+const ALLOWED_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+]);
+const MAX_SIZE = 100 * 1024 * 1024;
+// Presigned URLs expire after 15 minutes (backend default), so the upload
+// timeout must stay below that. 10 minutes leaves room for init/confirm calls.
+const UPLOAD_TIMEOUT_MAX_MS = 10 * 60_000;
+const UPLOAD_TIMEOUT_MIN_MS = 60_000;
+const MIN_UPSTREAM_BYTES_PER_SEC = 256 * 1024;
+
+export interface UploadResult {
+  attachmentId: number;
+  fileName: string;
+}
+
+export async function uploadInlineImage(
+  taskId: number,
+  file: File,
+  options?: { onProgress?: (percent: number) => void },
+): Promise<UploadResult> {
+  if (!ALLOWED_TYPES.has(file.type)) {
+    throw new Error(
+      `Invalid file type "${file.type}". Allowed: PNG, JPEG, GIF, WebP.`,
+    );
+  }
+
+  if (file.size > MAX_SIZE) {
+    throw new Error("File exceeds 100 MB limit");
+  }
+
+  const init = await initUpload(taskId, {
+    file_name: file.name,
+    size_bytes: file.size,
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.timeout = Math.min(
+      UPLOAD_TIMEOUT_MAX_MS,
+      Math.max(UPLOAD_TIMEOUT_MIN_MS, (file.size / MIN_UPSTREAM_BYTES_PER_SEC) * 1000),
+    );
+    xhr.upload.onprogress = (e) => {
+      if (e.lengthComputable && options?.onProgress) {
+        options.onProgress(Math.round((e.loaded / e.total) * 100));
+      }
+    };
+    xhr.onload = () => {
+      if (xhr.status >= 200 && xhr.status < 300) resolve();
+      else reject(new Error(`Upload failed with status ${xhr.status}`));
+    };
+    xhr.onerror = () =>
+      reject(new Error("Upload failed: network error while uploading to storage"));
+    xhr.ontimeout = () => reject(new Error("Upload timed out"));
+    xhr.onabort = () => reject(new Error("Upload was canceled"));
+    xhr.open("PUT", init.upload_url);
+    xhr.send(file);
+  });
+
+  const confirmed = await confirmUpload(taskId, init.id);
+
+  return { attachmentId: confirmed.id, fileName: confirmed.file_name };
+}
diff --git a/internal/attachments/service.go b/internal/attachments/service.go
index 2ed16a8..8cea204 100644
--- a/internal/attachments/service.go
+++ b/internal/attachments/service.go
@@ -116,6 +116,11 @@ func (s *Service) Import(
 	return attachment, nil
 }
 
+// GetByID retrieves an attachment by its ID.
+func (s *Service) GetByID(ctx context.Context, id int64) (*Attachment, error) {
+	return s.attachments.GetByID(ctx, id)
+}
+
 func (s *Service) ListByTask(ctx context.Context, taskID int64) ([]AttachmentWithURL, error) {
 	items, err := s.attachments.ListByTask(ctx, taskID)
 	if err != nil {
@@ -135,6 +140,7 @@ func (s *Service) ListByTask(ctx context.Context, taskID int64) ([]AttachmentWit
 	return result, nil
 }
 
+// GetDownloadURL returns a presigned URL for downloading an uploaded attachment.
 func (s *Service) GetDownloadURL(ctx context.Context, id int64) (string, error) {
 	attachment, err := s.attachments.GetByID(ctx, id)
 	if err != nil {
diff --git a/internal/storage/service.go b/internal/storage/service.go
index d2cee8e..20379e3 100644
--- a/internal/storage/service.go
+++ b/internal/storage/service.go
@@ -61,6 +61,7 @@ func (s *Service) PutObject(ctx context.Context, key string, filePath string) er
 	return nil
 }
 
+// PresignedGetObject returns a presigned URL for downloading an object.
 func (s *Service) PresignedGetObject(ctx context.Context, key string) (string, error) {
 	u, err := s.client.PresignedGetObject(
 		ctx,