@cyber-dash-tech/revela 0.15.0 → 0.15.2

package/lib/refine/server.ts

@@ -1,13 +1,16 @@
 import { randomBytes } from "crypto"
 import { existsSync, readFileSync, statSync } from "fs"
 import { fileURLToPath } from "url"
-import { dirname, extname, isAbsolute, resolve, sep } from "path"
+import { dirname, extname, isAbsolute, relative, resolve, sep } from "path"
 import type { EditableDeck } from "../edit/resolve-deck"
 import { buildEditPrompt, type EditCommentPayload } from "../edit/prompt"
 import type { InspectionElementSnapshot } from "../inspection-context/match"
 import { buildInspectionPrompt } from "../inspect/prompt"
 import { projectWorkspaceElement } from "../inspect/request"
 import { createInspectRequest, failInspectRequest, getInspectRequest } from "../inspect/requests"
+import { saveMediaAsset } from "../media/save"
+import { searchRemoteImages, type ImageCandidate } from "../media/search"
+import type { MediaAssetRecord, MediaPurpose } from "../media/types"
 
 const TOKEN_BYTES = 24
 const SESSION_TTL_MS = 2 * 60 * 60 * 1000
@@ -190,9 +193,148 @@ async function handleRequest(req: Request): Promise<Response> {
     return handleDeckVersion(session.value)
   }
 
+  if (url.pathname === "/api/assets/search" && req.method === "GET") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return handleAssetSearch(url, session.value)
+  }
+
+  if (url.pathname === "/api/assets/save" && req.method === "POST") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return handleAssetSave(req, session.value)
+  }
+
+  if (url.pathname === "/api/assets/list" && req.method === "GET") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return handleAssetList(session.value)
+  }
+
   return textResponse("Not found", 404)
 }
 
+async function handleAssetSearch(url: URL, session: EditSession): Promise<Response> {
+  const query = (url.searchParams.get("query") || "").trim()
+  if (!query) return jsonResponse({ ok: false, error: "query is required" }, 400)
+  const purpose = normalizeMediaPurpose(url.searchParams.get("purpose"))
+  const limit = Number(url.searchParams.get("limit") || 12)
+  const page = Number(url.searchParams.get("page") || 1)
+  try {
+    const candidates = await searchRemoteImages({ query, purpose, limit, page })
+    session.lastActiveAt = Date.now()
+    scheduleIdleStop()
+    return jsonResponse({ ok: true, candidates })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return jsonResponse({ ok: false, error: message }, 502)
+  }
+}
+
+async function handleAssetSave(req: Request, session: EditSession): Promise<Response> {
+  let body: any
+  try {
+    body = await req.json()
+  } catch {
+    return jsonResponse({ ok: false, error: "Invalid JSON body" }, 400)
+  }
+
+  const candidate = normalizeImageCandidate(body?.candidate ?? body)
+  if (!candidate) return jsonResponse({ ok: false, error: "Valid image candidate is required" }, 400)
+  const purpose = normalizeMediaPurpose(body?.purpose) || candidate.purpose || "illustration"
+  const result = await saveMediaAsset({
+    topic: session.deck,
+    id: body?.id || candidate.candidateId,
+    type: "image",
+    purpose,
+    brief: body?.brief || `Saved from ${candidate.provider} for Refine asset placement.`,
+    status: "success",
+    sourceUrl: candidate.imageUrl,
+    alt: body?.alt || candidate.alt || candidate.title,
+    notes: body?.notes,
+    provider: candidate.provider,
+    sourcePageUrl: candidate.sourcePageUrl,
+    license: candidate.license,
+    attribution: candidate.attribution,
+    width: candidate.width,
+    height: candidate.height,
+  }, session.workspaceRoot)
+
+  session.lastActiveAt = Date.now()
+  scheduleIdleStop()
+  if (!result.ok) return jsonResponse({ ok: false, error: result.error }, 400)
+  if (result.status !== "success" || !result.path) {
+    return jsonResponse({ ok: false, error: `Failed to save asset: ${result.status}` }, 400)
+  }
+  const asset = savedAssetForResult(session, result.assetId)
+  if (!asset) return jsonResponse({ ok: false, error: "Saved asset was not found in workspace assets." }, 500)
+  return jsonResponse({ ok: true, asset, result })
+}
+
+function handleAssetList(session: EditSession): Response {
+  session.lastActiveAt = Date.now()
+  scheduleIdleStop()
+  return jsonResponse({ ok: true, assets: listSavedAssets(session) })
+}
+
+function savedAssetForResult(session: EditSession, assetId: string): (MediaAssetRecord & { previewUrl?: string; deckPath?: string }) | null {
+  return listSavedAssets(session).find((asset) => asset.id === assetId) ?? null
+}
+
+function listSavedAssets(session: EditSession): Array<MediaAssetRecord & { previewUrl?: string; deckPath?: string }> {
+  const manifestPath = resolve(session.workspaceRoot, "assets", slugify(session.deck), "media-manifest.json")
+  if (!existsSync(manifestPath)) return []
+  try {
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf-8")) as { assets?: MediaAssetRecord[] }
+    return (Array.isArray(parsed.assets) ? parsed.assets : [])
+      .filter((asset) => asset.status === "success" && asset.path)
+      .map((asset) => ({
+        ...asset,
+        previewUrl: asset.path ? assetUrlForRef(asset.path, session, session.workspaceRoot) ?? undefined : undefined,
+        deckPath: asset.path ? relative(dirname(session.absoluteFile), resolve(session.workspaceRoot, asset.path)).replace(/\\/g, "/") : undefined,
+      }))
+  } catch {
+    return []
+  }
+}
+
+function normalizeImageCandidate(input: any): ImageCandidate | null {
+  if (!input || typeof input !== "object") return null
+  const candidateId = typeof input.candidateId === "string" ? input.candidateId.trim() : ""
+  const provider = typeof input.provider === "string" ? input.provider.trim() : ""
+  const title = typeof input.title === "string" ? input.title.trim() : ""
+  const imageUrl = typeof input.imageUrl === "string" ? input.imageUrl.trim() : ""
+  const thumbnailUrl = typeof input.thumbnailUrl === "string" ? input.thumbnailUrl.trim() : imageUrl
+  if (!candidateId || !provider || !title || !imageUrl) return null
+  return {
+    candidateId,
+    provider,
+    title,
+    thumbnailUrl,
+    imageUrl,
+    sourcePageUrl: typeof input.sourcePageUrl === "string" ? input.sourcePageUrl : undefined,
+    width: typeof input.width === "number" ? input.width : undefined,
+    height: typeof input.height === "number" ? input.height : undefined,
+    alt: typeof input.alt === "string" ? input.alt : undefined,
+    license: typeof input.license === "string" ? input.license : undefined,
+    attribution: typeof input.attribution === "string" ? input.attribution : undefined,
+    purpose: normalizeMediaPurpose(input.purpose),
+  }
+}
+
+function normalizeMediaPurpose(input: unknown): MediaPurpose | undefined {
+  return input === "hero" || input === "illustration" || input === "portrait" || input === "logo" || input === "screenshot"
+    ? input
+    : undefined
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
 function handleDeck(session: EditSession): Response {
   session.assets.clear()
   session.assetKeys.clear()
@@ -460,6 +602,7 @@ async function handleInspect(req: Request, session: EditSession): Promise<Respon
 
   const snapshot = normalizeSnapshot(body?.snapshot ?? body)
   const language = normalizeInspectLanguage(body?.language)
+  const comment = typeof body?.comment === "string" ? body.comment.trim().slice(0, 2000) : ""
   const requestId = typeof body?.requestId === "string" && body.requestId.trim() ? body.requestId.trim() : randomBytes(10).toString("base64url")
   const version = readDeckVersion(session).version
   const staleReason = typeof body?.deckVersion === "string" && body.deckVersion !== version
@@ -482,6 +625,7 @@ async function handleInspect(req: Request, session: EditSession): Promise<Respon
             requestId,
             file: session.file,
             language,
+            comment,
             projection: staleReason
               ? { ...projection, stale: { stale: true, reason: staleReason } } as any
               : projection,
@@ -624,95 +768,167 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
   <style>
     :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
     * { box-sizing: border-box; }
-    body { margin: 0; background: #f6f8fb; color: #172033; height: 100vh; overflow: hidden; }
+    body { margin: 0; background: #eee8dc; color: #1f2933; height: 100vh; overflow: hidden; }
     body.resizing { cursor: col-resize; user-select: none; }
     body.resizing iframe, body.resizing .hitbox { pointer-events: none; }
     .app { --editor-width: 376px; position: relative; display: grid; grid-template-columns: minmax(0, 1fr) var(--editor-width); height: 100vh; }
-    .preview { position: relative; min-width: 0; background: #eef3f8; }
+    .preview { position: relative; min-width: 0; background: #e7dfd1; }
     .resize-handle { position: absolute; top: 0; bottom: 0; right: calc(var(--editor-width) - 7px); width: 14px; z-index: 5; cursor: col-resize; background: transparent; }
     .resize-handle::before { content: ""; position: absolute; left: 50%; top: 50%; width: 4px; height: 44px; border-radius: 999px; transform: translate(-50%, -50%); background: rgba(148,163,184,.34); box-shadow: 0 1px 2px rgba(15,23,42,.06); transition: background .16s ease, height .16s ease, box-shadow .16s ease; }
     .resize-handle:hover::before, body.resizing .resize-handle::before { height: 52px; background: #94a3b8; box-shadow: 0 0 0 4px rgba(148,163,184,.16); }
     iframe { display: block; width: 100%; height: 100%; border: 0; background: #fff; }
     .hitbox { position: absolute; inset: 0; z-index: 2; cursor: crosshair; background: transparent; }
-    aside { display: flex; flex-direction: column; gap: 16px; padding: 20px; background: linear-gradient(180deg, #ffffff 0%, #f8fafc 100%); overflow: auto; }
+    .deck-nav { position: absolute; left: 50%; bottom: 18px; z-index: 4; display: inline-flex; align-items: center; gap: 8px; transform: translateX(-50%); padding: 7px; border: 1px solid rgba(148,163,184,.42); border-radius: 999px; background: rgba(15,23,42,.76); box-shadow: 0 16px 44px rgba(15,23,42,.24); backdrop-filter: blur(14px); -webkit-backdrop-filter: blur(14px); pointer-events: auto; }
+    .deck-nav button { width: auto; min-width: 84px; padding: 8px 12px; border-radius: 999px; background: rgba(255,255,255,.12); color: #fff; box-shadow: none; font-size: 12px; font-weight: 900; }
+    .deck-nav button:hover:not(:disabled) { background: rgba(255,255,255,.22); }
+    .deck-nav button:disabled { opacity: .38; }
+    .deck-nav-status { min-width: 76px; color: #e2e8f0; font-size: 12px; font-weight: 900; text-align: center; font-variant-numeric: tabular-nums; }
+    aside { position: relative; display: flex; flex-direction: column; gap: 16px; padding: 20px; background: linear-gradient(180deg, #fbfaf7 0%, #f2eee6 100%); overflow: auto; border-left: 1px solid #d8d2c6; }
     h1 { margin: 0; font-size: 18px; line-height: 1.2; letter-spacing: -.01em; color: #0f172a; }
     .wordmark { font-family: Garamond, "Iowan Old Style", Georgia, serif; font-size: 21px; letter-spacing: .08em; font-weight: 600; }
-    .hint { margin: 0; color: #64748b; font-size: 13px; line-height: 1.5; }
+    .hint { margin: 0; color: #756f66; font-size: 13px; line-height: 1.5; }
     .panel { display: flex; flex-direction: column; gap: 10px; }
-    .tabs { display: grid; grid-template-columns: 1fr 1fr; gap: 6px; padding: 4px; border: 1px solid #dbe4ee; border-radius: 14px; background: #f1f5f9; }
-    .tab { padding: 9px 10px; border: 0; border-radius: 10px; background: transparent; color: #475569; box-shadow: none; font-weight: 900; }
-    .tab.active { background: #ffffff; color: #0f172a; box-shadow: 0 6px 18px rgba(15,23,42,.08); }
+    .tabs { display: grid; grid-template-columns: 1fr 1fr; gap: 6px; padding: 4px; border: 1px solid #d8d2c6; border-radius: 14px; background: #ebe4d8; }
+    .tab { padding: 9px 10px; border: 0; border-radius: 10px; background: transparent; color: #5f594f; box-shadow: none; font-weight: 900; }
+    .tab.active { background: #fbfaf7; color: #111827; box-shadow: 0 6px 16px rgba(31,41,51,.1); }
     .tab-panel { display: none; flex-direction: column; gap: 12px; }
     .tab-panel.active { display: flex; }
-    .selection-summary { padding: 10px 12px; border: 1px solid #d7e0ea; border-radius: 14px; background: #fff; color: #334155; font-size: 13px; line-height: 1.45; box-shadow: 0 8px 24px rgba(15,23,42,.05); }
-    .selection-summary strong { display: block; margin-bottom: 7px; color: #64748b; font-size: 11px; letter-spacing: .09em; text-transform: uppercase; }
+    .sr-only { position: absolute !important; width: 1px !important; height: 1px !important; padding: 0 !important; margin: -1px !important; overflow: hidden !important; clip: rect(0,0,0,0) !important; white-space: nowrap !important; border: 0 !important; }
+    .selection-summary { padding: 10px 12px; border: 1px solid #d8d2c6; border-radius: 14px; background: #fbfaf7; color: #3f3a33; font-size: 13px; line-height: 1.45; box-shadow: 0 8px 22px rgba(31,41,51,.05); }
+    .selection-summary strong { display: block; margin-bottom: 7px; color: #756f66; font-size: 11px; letter-spacing: .09em; text-transform: uppercase; }
     .selection-chips { display: flex; flex-wrap: wrap; gap: 6px; }
-    .label { color: #64748b; font-size: 11px; font-weight: 800; letter-spacing: .09em; text-transform: uppercase; }
-    .comment-editor { width: 100%; min-height: 164px; max-height: 42vh; overflow: auto; padding: 13px 14px; border: 1px solid #d7e0ea; border-radius: 14px; background: #ffffff; color: #0f172a; font: inherit; line-height: 1.5; outline: none; white-space: pre-wrap; box-shadow: 0 10px 28px rgba(15,23,42,.06); }
-    .comment-editor:focus { border-color: #2563eb; box-shadow: 0 0 0 3px rgba(37,99,235,.12), 0 10px 28px rgba(15,23,42,.06); }
-    .comment-editor:empty::before { content: attr(data-placeholder); color: #94a3b8; pointer-events: none; }
+    .label { color: #756f66; font-size: 11px; font-weight: 800; letter-spacing: .09em; text-transform: uppercase; }
+    .comment-editor { width: 100%; min-height: 164px; max-height: 42vh; overflow: auto; padding: 13px 14px; border: 1px solid #d8d2c6; border-radius: 14px; background: #fffdf8; color: #111827; font: inherit; line-height: 1.5; outline: none; white-space: pre-wrap; box-shadow: 0 10px 24px rgba(31,41,51,.06); }
+    .comment-editor:focus { border-color: #a9793f; box-shadow: 0 0 0 3px rgba(169,121,63,.14), 0 10px 24px rgba(31,41,51,.07); }
+    .comment-editor:empty::before { content: attr(data-placeholder); color: #a79d8e; pointer-events: none; }
     .ref-chip { display: inline-flex; align-items: center; margin: 0 2px; padding: 1px 7px; border-radius: 999px; background: var(--ref-bg, #e0f2fe); color: var(--ref-text, #075985); border: 1px solid var(--ref-border, #7dd3fc); font-weight: 800; white-space: nowrap; }
-    .comment-thread { display: flex; flex-direction: column; gap: 10px; max-height: 30vh; overflow: auto; }
-    .comment-bubble { border: 1px solid #dbe4ee; border-radius: 14px; padding: 10px 12px; background: #ffffff; color: #334155; font-size: 13px; line-height: 1.45; box-shadow: 0 8px 24px rgba(15,23,42,.05); }
-    .comment-bubble.sending { border-color: #93c5fd; background: #eff6ff; }
-    .comment-bubble.updated { border-color: #86efac; background: #f0fdf4; }
-    .comment-bubble.stale { border-color: #facc15; background: #fefce8; }
-    .comment-bubble.failed { border-color: #fca5a5; background: #fef2f2; }
+    .activity-panel { display: flex; flex-direction: column; gap: 8px; padding-top: 2px; }
+    .comment-thread { display: flex; flex-direction: column; gap: 8px; max-height: 24vh; overflow: auto; }
+    .comment-thread:empty { display: none; }
+    .comment-bubble { border: 1px solid #d8d2c6; border-radius: 14px; padding: 10px 12px; background: #fffdf8; color: #3f3a33; font-size: 13px; line-height: 1.45; box-shadow: 0 8px 22px rgba(31,41,51,.05); }
+    .comment-bubble.sending { border-color: #c8b88f; background: #f7f0df; }
+    .comment-bubble.updated { border-color: #9dac8a; background: #f0f2e8; }
+    .comment-bubble.stale { border-color: #c6a96a; background: #f8efd7; }
+    .comment-bubble.failed { border-color: #c58f82; background: #f7eae5; }
     .comment-bubble-text { white-space: pre-wrap; overflow-wrap: anywhere; }
-    .comment-bubble-state { margin-top: 8px; color: #2563eb; font-size: 12px; font-weight: 800; }
-    .comment-bubble.updated .comment-bubble-state { color: #15803d; }
-    .comment-bubble.stale .comment-bubble-state { color: #a16207; }
-    .comment-bubble.failed .comment-bubble-state { color: #b91c1c; }
+    .comment-bubble-state { margin-top: 8px; color: #8a6231; font-size: 12px; font-weight: 800; }
+    .comment-bubble.updated .comment-bubble-state { color: #556b3f; }
+    .comment-bubble.stale .comment-bubble-state { color: #8a6231; }
+    .comment-bubble.failed .comment-bubble-state { color: #8f4638; }
     .inspect-actions { display: flex; flex-direction: column; gap: 8px; }
     .inspect-options { display: flex; flex-direction: column; gap: 5px; }
-    .inspect-options label { color: #64748b; font-size: 11px; font-weight: 800; text-transform: uppercase; letter-spacing: .05em; }
-    .inspect-select { width: 100%; padding: 10px 11px; border: 1px solid #d7e0ea; border-radius: 12px; background: #fff; color: #0f172a; font-weight: 700; }
+    .inspect-options label { color: #756f66; font-size: 11px; font-weight: 800; text-transform: uppercase; letter-spacing: .05em; }
+    .inspect-select { width: 100%; padding: 10px 11px; border: 1px solid #d8d2c6; border-radius: 12px; background: #fffdf8; color: #111827; font-weight: 700; }
     .inspect-cards { display: flex; flex-direction: column; gap: 12px; }
-    .inspect-card { border: 1px solid #d7e0ea; border-radius: 16px; background: #fff; padding: 13px; box-shadow: 0 10px 24px rgba(15,23,42,.05); }
+    .inspect-card { border: 1px solid #d8d2c6; border-radius: 16px; background: #fffdf8; padding: 13px; box-shadow: 0 10px 22px rgba(31,41,51,.05); }
     .inspect-card-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 8px; }
     .inspect-card h2 { margin: 0; font-size: 13px; color: #0f172a; }
-    .badge { border-radius: 999px; padding: 3px 8px; font-size: 11px; font-weight: 800; text-transform: uppercase; letter-spacing: .04em; background: #e2e8f0; color: #475569; }
-    .badge.supported, .badge.found, .badge.present, .badge.known, .badge.suggested { background: #dcfce7; color: #166534; }
-    .badge.weak, .badge.missing { background: #fef3c7; color: #92400e; }
-    .badge.unsupported { background: #fee2e2; color: #991b1b; }
-    .inspect-card p, .inspect-empty, .inspect-loading { margin: 0; color: #475569; font-size: 12px; line-height: 1.5; }
-    .inspect-item { margin-top: 7px; padding: 8px; border-radius: 10px; background: #f8fafc; color: #334155; font-size: 12px; line-height: 1.45; }
+    .badge { border-radius: 999px; padding: 3px 8px; font-size: 11px; font-weight: 800; text-transform: uppercase; letter-spacing: .04em; background: #e8e1d4; color: #5f594f; }
+    .badge.supported, .badge.found, .badge.present, .badge.known, .badge.suggested { background: #e7ecdc; color: #4d6138; }
+    .badge.weak, .badge.missing { background: #f1e5c8; color: #765326; }
+    .badge.unsupported { background: #f0d9d1; color: #7f3d31; }
+    .inspect-card p, .inspect-empty, .inspect-loading { margin: 0; color: #5f594f; font-size: 12px; line-height: 1.5; }
+    .inspect-item { margin-top: 7px; padding: 8px; border-radius: 10px; background: #f7f3ea; color: #3f3a33; font-size: 12px; line-height: 1.45; }
     .inspect-warning, .inspect-stale { margin-top: 8px; padding: 8px; border-radius: 10px; background: #fff7ed; color: #9a3412; font-size: 12px; line-height: 1.45; }
-    button { width: 100%; padding: 12px 14px; border: 0; border-radius: 12px; background: #2563eb; color: #ffffff; font-weight: 800; cursor: pointer; box-shadow: 0 10px 24px rgba(37,99,235,.22); }
+    .loading-row { display: inline-flex; align-items: center; gap: 8px; }
+    .spinner { width: 16px; height: 16px; border: 2px solid rgba(169,121,63,.22); border-top-color: currentColor; border-radius: 999px; animation: spin .8s linear infinite; }
+    button .spinner { width: 15px; height: 15px; border-color: rgba(255,255,255,.36); border-top-color: #fff; }
+    .skeleton-card { border: 1px solid #d8d2c6; border-radius: 16px; background: #fffdf8; padding: 13px; box-shadow: 0 10px 22px rgba(31,41,51,.05); }
+    .skeleton-line { height: 10px; margin: 8px 0; border-radius: 999px; background: linear-gradient(90deg, #ded5c6 0%, #fbfaf7 48%, #ded5c6 100%); background-size: 200% 100%; animation: shimmer 1.2s ease-in-out infinite; }
+    .skeleton-line.short { width: 42%; }
+    .skeleton-line.medium { width: 68%; }
+    .skeleton-line.long { width: 92%; }
+    .asset-card.is-saving::after { content: ""; position: absolute; inset: 0; background: rgba(15,23,42,.32); }
+    .asset-card.is-saving .asset-save { z-index: 1; }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    @keyframes shimmer { 0% { background-position: 200% 0; } 100% { background-position: -200% 0; } }
+    .asset-search { display: grid; grid-template-columns: minmax(0, 1fr) 118px; gap: 8px; }
+    .asset-search input, .asset-search select { min-width: 0; padding: 10px 11px; border: 1px solid #d8d2c6; border-radius: 12px; background: #fffdf8; color: #111827; font: inherit; font-size: 12px; font-weight: 700; outline: none; }
+    .asset-search input:focus, .asset-search select:focus { border-color: #a9793f; box-shadow: 0 0 0 3px rgba(169,121,63,.14); }
+    .asset-actions { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 8px; }
+    .asset-grid { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 8px; }
+    .asset-card { position: relative; min-width: 0; aspect-ratio: 1 / 1; overflow: hidden; border: 1px solid #d8d2c6; border-radius: 14px; background: #fffdf8; box-shadow: 0 8px 18px rgba(31,41,51,.05); }
+    .asset-card.saved { width: 64px; height: 64px; aspect-ratio: auto; border-radius: 12px; }
+    .asset-card[draggable="true"] { cursor: grab; }
+    .asset-card[draggable="true"]:active { cursor: grabbing; }
+    .asset-thumb { width: 100%; height: 100%; display: block; background: #eee8dc; object-fit: contain; }
+    .asset-tools { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+    .asset-search-toggle { width: auto; min-width: 32px; height: 28px; padding: 0 9px; border-radius: 999px; box-shadow: 0 6px 14px rgba(31,41,51,.08); font-size: 16px; line-height: 1; }
+    .asset-search-view { position: absolute; inset: 0; z-index: 12; display: flex; flex-direction: column; gap: 14px; padding: 20px; background: linear-gradient(180deg, #fbfaf7 0%, #f2eee6 100%); overflow: auto; transform: translateX(105%); transition: transform .2s ease; box-shadow: -18px 0 44px rgba(31,41,51,.16); }
+    .asset-search-view.open { transform: translateX(0); }
+    .asset-search-head { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
+    .asset-search-title { display: flex; flex-direction: column; gap: 2px; }
+    .asset-search-title h2 { margin: 0; color: #0f172a; font-size: 16px; letter-spacing: -.01em; }
+    .asset-search-title span { color: #756f66; font-size: 12px; line-height: 1.35; }
+    .asset-back { width: auto; padding: 9px 11px; border-radius: 999px; background: #ebe4d8; color: #111827; box-shadow: none; }
+    .asset-save { position: absolute; left: 7px; right: 7px; bottom: 7px; width: auto; padding: 7px 8px; border-radius: 10px; font-size: 11px; background: rgba(17,24,39,.9); color: #fbfaf7; box-shadow: 0 8px 16px rgba(31,41,51,.2); opacity: .96; }
+    .asset-empty { grid-column: 1 / -1; margin: 0; color: #756f66; font-size: 12px; line-height: 1.45; }
+    .edit-assets { padding: 10px; border: 1px solid #d8d2c6; border-radius: 16px; background: #f7f3ea; }
+    .edit-assets .panel { gap: 8px; }
+    .edit-assets .asset-grid { grid-template-columns: repeat(auto-fill, 64px); align-items: start; max-height: 176px; overflow: auto; }
+    .edit-assets .asset-thumb { width: 64px; height: 64px; }
+    .drop-active .hitbox { background: rgba(169,121,63,.1); outline: 2px dashed rgba(169,121,63,.48); outline-offset: -10px; }
+    button { width: 100%; padding: 12px 14px; border: 1px solid #d8d2c6; border-radius: 12px; background: #ebe4d8; color: #111827; font-weight: 800; cursor: pointer; box-shadow: 0 8px 16px rgba(31,41,51,.08); }
+    button:hover:not(:disabled) { background: #e3dacb; }
     button:disabled { cursor: not-allowed; opacity: .5; }
-    .status { min-height: 20px; color: #475569; font-size: 13px; line-height: 1.45; }
-    @media (max-width: 900px) { .app { grid-template-columns: 1fr; grid-template-rows: minmax(0, 1fr) auto; } .resize-handle { display: none; } aside { max-height: 48vh; } }
+    .primary-action { display: inline-flex; align-items: center; justify-content: center; gap: 8px; min-height: 46px; border-radius: 14px; border-color: #111827; background: linear-gradient(135deg, #111827 0%, #1f2937 100%); color: #fbfaf7; font-size: 14px; letter-spacing: .01em; box-shadow: 0 12px 24px rgba(31,41,51,.24); transition: transform .14s ease, box-shadow .14s ease, filter .14s ease; }
+    .primary-action:hover:not(:disabled) { background: linear-gradient(135deg, #0f1720 0%, #283241 100%); transform: translateY(-1px); box-shadow: 0 16px 30px rgba(31,41,51,.28); filter: saturate(1.02); }
+    .primary-action:active:not(:disabled) { transform: translateY(0); box-shadow: 0 9px 20px rgba(31,41,51,.22); }
+    .send-icon { width: 17px; height: 17px; stroke: currentColor; fill: none; stroke-width: 2.25; stroke-linecap: round; stroke-linejoin: round; }
+    .status { min-height: 20px; color: #5f594f; font-size: 13px; line-height: 1.45; }
+    @media (max-width: 900px) { .app { grid-template-columns: 1fr; grid-template-rows: minmax(0, 1fr) auto; } .resize-handle { display: none; } aside { max-height: 48vh; } .deck-nav { bottom: 10px; } }
   </style>
 </head>
 <body>
   <main class="app">
-    <section class="preview"><iframe id="deck" src="/deck?token=${encodeURIComponent(token)}"></iframe><div id="hitbox" class="hitbox" aria-label="Deck element selection layer"></div></section>
+    <section class="preview"><iframe id="deck" src="/deck?token=${encodeURIComponent(token)}"></iframe><div id="hitbox" class="hitbox" aria-label="Deck element selection layer"></div><nav class="deck-nav" aria-label="Deck navigation"><button id="deckPrev" type="button" title="Previous slide (ArrowLeft / ArrowUp / PageUp)">Previous</button><div id="deckCounter" class="deck-nav-status" aria-live="polite">-- / --</div><button id="deckNext" type="button" title="Next slide (ArrowRight / ArrowDown / Space / PageDown)">Next</button></nav></section>
     <div id="resizeHandle" class="resize-handle" role="separator" aria-label="Resize editor panel" aria-orientation="vertical" title="Drag to resize editor. Double-click to reset."></div>
     <aside>
       <div>
         <h1><span class="wordmark">REVELA</span> Refine</h1>
-        <p class="hint">Cmd/Ctrl-click slide elements once, then use Edit for fast changes or Inspect for Narrative Reading, Exploratory Reading, Source, and Purpose review.</p>
+        <p class="hint">Select refs, describe the change, then send. Use Inspect only when you need source or purpose context.</p>
       </div>
-      <div id="selectionSummary" class="selection-summary"><strong>Selection</strong><span>No references selected.</span><div id="selectionChips" class="selection-chips"></div></div>
+      <div id="selectionSummary" class="selection-summary sr-only" aria-live="polite"><strong>Selection</strong><span>No references selected.</span><div id="selectionChips" class="selection-chips"></div></div>
       <div class="tabs" role="tablist" aria-label="Refine mode">
         <button id="editTab" class="tab" type="button" role="tab">Edit</button>
         <button id="inspectTab" class="tab" type="button" role="tab">Inspect</button>
       </div>
       <div id="editPanel" class="tab-panel">
         <div class="panel">
-          <div class="label">Comment</div>
-          <div id="comment" class="comment-editor" contenteditable="true" role="textbox" aria-multiline="true" data-placeholder="Example: Cmd/Ctrl-click to ref the chart title, then ask to make it shorter and align it with the KPI row."></div>
+          <div class="label">Describe the change</div>
+          <div id="comment" class="comment-editor" contenteditable="true" role="textbox" aria-multiline="true" data-placeholder="Cmd/Ctrl-click slide elements to add @refs, then describe the exact edit."></div>
         </div>
-        <div id="commentThread" class="comment-thread" aria-live="polite"></div>
-        <button id="send" disabled>Send Edit</button>
+        <div class="edit-assets" aria-label="Edit assets">
+          <div class="panel">
+            <div class="asset-tools"><div class="label">Local Assets</div><button id="assetSearchToggle" class="asset-search-toggle" type="button" aria-expanded="false" aria-controls="assetSearchView" title="Search assets">+</button></div>
+            <div id="editSavedAssets" class="asset-grid"><p class="asset-empty">No local assets yet. Click + to search assets.</p></div>
+          </div>
+        </div>
+        <button id="send" class="primary-action" disabled><svg class="send-icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94L14.7 6.3z"/></svg><span>Apply Fix</span></button>
+        <div class="activity-panel"><div class="label">Activity</div><div id="commentThread" class="comment-thread" aria-live="polite"></div></div>
       </div>
       <div id="inspectPanel" class="tab-panel">
+        <div class="panel">
+          <label class="label" for="inspectComment">Inspect comment</label>
+          <div id="inspectComment" class="comment-editor" contenteditable="true" role="textbox" aria-multiline="true" data-placeholder="Cmd/Ctrl-click slide elements to add @refs, then ask about purpose or source."></div>
+        </div>
         <div class="inspect-actions">
           <div class="inspect-options"><label for="inspectLanguage">Display Language</label><select id="inspectLanguage" class="inspect-select"><option>Auto</option><option>English</option><option>简体中文</option><option>繁體中文</option><option>日本語</option><option>Deutsch</option><option>Français</option><option>Español</option><option>Português</option><option>Arabic</option></select></div>
-          <button id="inspectButton" disabled>Inspect Selection</button>
+          <button id="inspectButton" disabled>Inspect Reference</button>
           <div id="inspectStale"></div>
         </div>
-        <div id="inspectCards" class="inspect-cards"><div class="inspect-empty">Select one or more deck elements, then inspect them for Narrative Reading, Exploratory Reading, Source, and Purpose. This does not edit the deck.</div></div>
+        <div id="inspectCards" class="inspect-cards"><div class="inspect-empty">Select a deck element to create an @ref, optionally ask a question, then Inspect. This does not edit the deck.</div></div>
+      </div>
+      <div id="assetSearchView" class="asset-search-view" aria-hidden="true">
+        <div class="asset-search-head">
+          <button id="assetSearchBack" class="asset-back" type="button">← Back</button>
+          <div class="asset-search-title"><h2>Search Assets</h2><span>Save images to Local Assets, then use them from Edit.</span></div>
+        </div>
+        <div class="panel">
+          <div class="asset-search"><input id="assetQuery" type="search" placeholder="Company logo, product photo, portrait..." /><select id="assetPurpose"><option value="logo" selected>logo</option><option value="illustration">photo</option><option value="hero">hero</option><option value="portrait">portrait</option><option value="screenshot">screenshot</option></select></div>
+          <div class="asset-actions"><button id="assetSearchButton" type="button">Search Assets</button><button id="assetShuffleButton" type="button" disabled>Refresh</button></div>
+          <div id="assetResults" class="asset-grid"><p class="asset-empty">Search image candidates, then save one to the workspace.</p></div>
+        </div>
       </div>
       <div id="status" class="status"></div>
     </aside>
@@ -752,16 +968,34 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         bound: false,
         commentRange: null,
         resizeDrag: null,
+        deckSlideIndex: 0,
+        deckSlideCount: 0,
         mode: defaultMode === 'inspect' ? 'inspect' : 'edit',
         inspecting: false,
         activeInspectRequestId: '',
         inspectLanguage: 'Auto',
         inspectFallback: null,
+        sendingEdit: false,
+        assetCandidates: [],
+        savedAssets: [],
+        selectedAsset: null,
+        draggingAsset: null,
+        assetDropTarget: null,
+        assetDropOutline: null,
+        assetSearchBusy: false,
+        assetSavingIndex: -1,
+        assetSearchPage: 1,
+        assetSearchKey: '',
+        assetVisibleCount: 0,
+        assetPendingCount: 0,
       };
       const els = {
         frame: null,
         hitbox: null,
         resizeHandle: null,
+        deckPrev: null,
+        deckNext: null,
+        deckCounter: null,
         selectionSummary: null,
         selectionChips: null,
         editTab: null,
@@ -771,10 +1005,20 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         comment: null,
         commentThread: null,
         send: null,
+        inspectComment: null,
         inspectButton: null,
         inspectLanguage: null,
         inspectCards: null,
         inspectStale: null,
+        assetSearchToggle: null,
+        assetSearchBack: null,
+        assetSearchView: null,
+        assetQuery: null,
+        assetPurpose: null,
+        assetSearchButton: null,
+        assetShuffleButton: null,
+        assetResults: null,
+        editSavedAssets: null,
         status: null,
       };
 
@@ -792,6 +1036,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           els.frame = document.getElementById('deck');
           els.hitbox = document.getElementById('hitbox');
           els.resizeHandle = document.getElementById('resizeHandle');
+          els.deckPrev = document.getElementById('deckPrev');
+          els.deckNext = document.getElementById('deckNext');
+          els.deckCounter = document.getElementById('deckCounter');
           els.selectionSummary = document.getElementById('selectionSummary');
           els.selectionChips = document.getElementById('selectionChips');
           els.editTab = document.getElementById('editTab');
@@ -801,14 +1048,24 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           els.comment = document.getElementById('comment');
           els.commentThread = document.getElementById('commentThread');
           els.send = document.getElementById('send');
+          els.inspectComment = document.getElementById('inspectComment');
           els.inspectButton = document.getElementById('inspectButton');
           els.inspectCards = document.getElementById('inspectCards');
           els.inspectStale = document.getElementById('inspectStale');
+          els.assetSearchToggle = document.getElementById('assetSearchToggle');
+          els.assetSearchBack = document.getElementById('assetSearchBack');
+          els.assetSearchView = document.getElementById('assetSearchView');
+          els.assetQuery = document.getElementById('assetQuery');
+          els.assetPurpose = document.getElementById('assetPurpose');
+          els.assetSearchButton = document.getElementById('assetSearchButton');
+          els.assetShuffleButton = document.getElementById('assetShuffleButton');
+          els.assetResults = document.getElementById('assetResults');
+          els.editSavedAssets = document.getElementById('editSavedAssets');
           els.status = document.getElementById('status');
 
           els.inspectLanguage = document.getElementById('inspectLanguage');
 
-          if (!els.frame || !els.hitbox || !els.resizeHandle || !els.selectionSummary || !els.selectionChips || !els.editTab || !els.inspectTab || !els.editPanel || !els.inspectPanel || !els.comment || !els.commentThread || !els.send || !els.inspectButton || !els.inspectLanguage || !els.inspectCards || !els.inspectStale || !els.status) {
+          if (!els.frame || !els.hitbox || !els.resizeHandle || !els.deckPrev || !els.deckNext || !els.deckCounter || !els.selectionSummary || !els.selectionChips || !els.editTab || !els.inspectTab || !els.editPanel || !els.inspectPanel || !els.comment || !els.commentThread || !els.send || !els.inspectComment || !els.inspectButton || !els.inspectLanguage || !els.inspectCards || !els.inspectStale || !els.assetSearchToggle || !els.assetSearchBack || !els.assetSearchView || !els.assetQuery || !els.assetPurpose || !els.assetSearchButton || !els.assetShuffleButton || !els.assetResults || !els.editSavedAssets || !els.status) {
             throw new Error('Editor boot failed: required DOM nodes are missing.');
           }
 
@@ -817,6 +1074,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           setMode(state.mode);
           setStatus('Editor ready. Ctrl/Cmd + click deck elements to reference them.');
           initFrame();
+          loadSavedAssets();
           startDeckVersionPolling();
         } catch (error) {
           reportError(error);
@@ -828,15 +1086,34 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         state.bound = true;
         els.frame.addEventListener('load', initFrame);
         document.addEventListener('keydown', (event) => {
-          if (event.key === 'Escape') clearHover();
+          if (event.key === 'Escape') {
+            clearHover();
+            return;
+          }
+          if (isTextInputTarget(event.target) || event.metaKey || event.ctrlKey || event.altKey) return;
+          if (['ArrowDown', 'ArrowRight', ' ', 'PageDown'].includes(event.key)) {
+            event.preventDefault();
+            nextDeckSlide();
+          } else if (['ArrowUp', 'ArrowLeft', 'PageUp'].includes(event.key)) {
+            event.preventDefault();
+            prevDeckSlide();
+          }
         });
         els.comment.addEventListener('input', () => {
           saveCommentRange();
-          syncReferencesFromComment(false);
+          syncReferencesFromComment(false, els.comment);
+          syncSelectedAssetFromComment();
           updateSendState();
         });
         els.comment.addEventListener('keyup', saveCommentRange);
         els.comment.addEventListener('mouseup', saveCommentRange);
+        els.inspectComment.addEventListener('input', () => {
+          saveCommentRange();
+          syncReferencesFromComment(false, els.inspectComment);
+          updateSendState();
+        });
+        els.inspectComment.addEventListener('keyup', saveCommentRange);
+        els.inspectComment.addEventListener('mouseup', saveCommentRange);
         document.addEventListener('selectionchange', saveCommentRange);
         els.hitbox.addEventListener('pointermove', onHover);
         els.hitbox.addEventListener('pointerdown', onPointerDown);
@@ -854,13 +1131,29 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         }, { passive: false });
         els.resizeHandle.addEventListener('pointerdown', startEditorResize);
         els.resizeHandle.addEventListener('dblclick', resetEditorWidth);
+        els.deckPrev.addEventListener('click', prevDeckSlide);
+        els.deckNext.addEventListener('click', nextDeckSlide);
         els.send.addEventListener('click', sendComment);
         els.inspectButton.addEventListener('click', inspectCurrentSelection);
+        els.assetSearchToggle.addEventListener('click', toggleAssetSearchPanel);
+        els.assetSearchBack.addEventListener('click', closeAssetSearchPanel);
+        els.assetSearchButton.addEventListener('click', () => searchAssets(false));
+        els.assetShuffleButton.addEventListener('click', () => searchAssets(true));
+        els.assetQuery.addEventListener('keydown', (event) => {
+          if (event.key === 'Enter') {
+            event.preventDefault();
+            searchAssets(false);
+          }
+        });
+        els.assetPurpose.addEventListener('change', () => resetAssetSearchBatch());
         els.inspectLanguage.addEventListener('change', () => {
           state.inspectLanguage = els.inspectLanguage.value || 'Auto';
         });
         els.editTab.addEventListener('click', () => setMode('edit'));
         els.inspectTab.addEventListener('click', () => setMode('inspect'));
+        els.hitbox.addEventListener('dragover', onAssetDragOver);
+        els.hitbox.addEventListener('dragleave', onAssetDragLeave);
+        els.hitbox.addEventListener('drop', onAssetDrop);
       }
 
       function setMode(mode) {
@@ -869,9 +1162,31 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         els.inspectTab.classList.toggle('active', state.mode === 'inspect');
         els.editPanel.classList.toggle('active', state.mode === 'edit');
         els.inspectPanel.classList.toggle('active', state.mode === 'inspect');
+        saveCommentRange();
         updateSendState();
       }
 
+      function activeCommentEditor() {
+        return state.mode === 'inspect' ? els.inspectComment : els.comment;
+      }
+
+      function toggleAssetSearchPanel() {
+        const open = !els.assetSearchView.classList.contains('open');
+        setAssetSearchOpen(open);
+      }
+
+      function closeAssetSearchPanel() {
+        setAssetSearchOpen(false);
+      }
+
+      function setAssetSearchOpen(open) {
+        els.assetSearchView.classList.toggle('open', open);
+        els.assetSearchView.setAttribute('aria-hidden', open ? 'false' : 'true');
+        els.assetSearchToggle.setAttribute('aria-expanded', open ? 'true' : 'false');
+        els.assetSearchToggle.textContent = '+';
+        if (open) els.assetQuery.focus();
+      }
+
       function restoreEditorWidth() {
         try {
           const saved = Number(window.localStorage.getItem(EDITOR_WIDTH_KEY));
@@ -934,12 +1249,15 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           clearReferences(false);
           state.hoverEl = null;
           state.hoverOutline = createOutline(doc, '#38bdf8', 'rgba(56,189,248,.12)');
+          state.assetDropTarget = null;
+          state.assetDropOutline = createOutline(doc, '#a9793f', 'rgba(169,121,63,.16)');
           state.referenceOutlines = [];
           doc.addEventListener('scroll', () => {
             renderHoverOutline(state.hoverEl);
             renderReferenceOutlines();
           }, true);
           const slides = getSlides(doc);
+          syncDeckNavigation();
           updateSendState();
           if (state.pendingRefreshMessage) {
             state.pendingRefreshMessage = false;
@@ -952,6 +1270,102 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         }
       }
 
+      function isTextInputTarget(target) {
+        if (!target || !(target instanceof Element)) return false;
+        const tag = target.tagName.toLowerCase();
+        return tag === 'input' || tag === 'textarea' || tag === 'select' || target.isContentEditable || Boolean(target.closest('[contenteditable="true"]'));
+      }
+
+      function syncDeckNavigation() {
+        try {
+          const doc = els.frame.contentDocument;
+          const slides = doc ? getSlides(doc) : [];
+          state.deckSlideCount = slides.length;
+          state.deckSlideIndex = Math.max(0, Math.min(state.deckSlideIndex, Math.max(0, slides.length - 1)));
+          updateDeckNavControls();
+        } catch {
+          state.deckSlideCount = 0;
+          state.deckSlideIndex = 0;
+          updateDeckNavControls();
+        }
+      }
+
+      function updateDeckNavControls() {
+        const total = state.deckSlideCount;
+        const current = total > 0 ? state.deckSlideIndex + 1 : 0;
+        els.deckCounter.textContent = total > 0 ? current + ' / ' + total : '-- / --';
+        els.deckPrev.disabled = total <= 1 || state.deckSlideIndex <= 0;
+        els.deckNext.disabled = total <= 1 || state.deckSlideIndex >= total - 1;
+      }
+
+      function prevDeckSlide() {
+        goToDeckSlide(state.deckSlideIndex - 1);
+      }
+
+      function nextDeckSlide() {
+        goToDeckSlide(state.deckSlideIndex + 1);
+      }
+
+      function goToDeckSlide(index) {
+        try {
+          const doc = els.frame.contentDocument;
+          const win = els.frame.contentWindow;
+          if (!doc || !win) return;
+          const slides = getSlides(doc);
+          if (!slides.length) {
+            syncDeckNavigation();
+            return;
+          }
+          const clamped = Math.max(0, Math.min(slides.length - 1, index));
+          const nav = win.RevelaDeckNav;
+          let handled = false;
+          if (nav && typeof nav.goTo === 'function') {
+            try {
+              nav.goTo(clamped);
+              handled = true;
+            } catch {}
+          } else if (nav && clamped > state.deckSlideIndex && typeof nav.next === 'function') {
+            try {
+              nav.next();
+              handled = true;
+            } catch {}
+          } else if (nav && clamped < state.deckSlideIndex && typeof nav.prev === 'function') {
+            try {
+              nav.prev();
+              handled = true;
+            } catch {}
+          }
+          if (!handled) applyFallbackDeckNavigation(win, doc, slides, clamped);
+          state.deckSlideIndex = clamped;
+          updateDeckNavControls();
+          renderHoverOutline(state.hoverEl);
+          renderReferenceOutlines();
+        } catch (error) {
+          reportError(error);
+        }
+      }
+
+      function applyFallbackDeckNavigation(win, doc, slides, index) {
+        const target = slides[index];
+        const usesOverlaySlides = slides.some((slide) => {
+          const style = win.getComputedStyle(slide);
+          return style.position === 'absolute' || style.position === 'fixed' || style.opacity === '0' || slide.style.opacity !== '';
+        });
+        if (usesOverlaySlides) {
+          slides.forEach((slide, i) => {
+            slide.style.opacity = i === index ? '1' : '0';
+            slide.style.pointerEvents = i === index ? 'auto' : 'none';
+          });
+          win.scrollTo?.(0, 0);
+          return;
+        }
+        if (target && typeof target.scrollIntoView === 'function') {
+          target.scrollIntoView({ block: 'start', inline: 'nearest', behavior: 'auto' });
+          return;
+        }
+        doc.defaultView?.scrollTo?.(0, index * win.innerHeight);
+      }
+
       function startDeckVersionPolling() {
         pollDeckVersion();
         window.setInterval(pollDeckVersion, 2000);
@@ -987,6 +1401,8 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         clearReferences(true);
         state.hoverEl = null;
         if (state.hoverOutline) state.hoverOutline.style.display = 'none';
+        state.assetDropTarget = null;
+        if (state.assetDropOutline) state.assetDropOutline.style.display = 'none';
         state.referenceOutlines.forEach((outline) => outline.style.display = 'none');
         state.referenceOutlines = [];
         updateSendState();
@@ -1038,34 +1454,353 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       }
 
       async function sendComment() {
-        syncReferencesFromComment(false);
+        syncReferencesFromComment(false, els.comment);
+        syncSelectedAssetFromComment();
         const text = getCommentText().trim();
         if (!text) return;
         const elements = state.references.map((reference) => reference.payload);
+        const asset = state.selectedAsset || undefined;
         const commentId = addPendingComment(text, elements, 'sending');
         clearReferences(false);
+        state.selectedAsset = null;
         els.comment.textContent = '';
         renderReferenceOutlines();
-        els.send.disabled = true;
+        state.sendingEdit = true;
+        updateSendState();
         setStatus('Sending...');
         try {
           const res = await fetch('/api/comment?token=' + encodeURIComponent(token), {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ comment: text, elements }),
+            body: JSON.stringify({ comment: text, elements, asset }),
           });
           const body = await res.json().catch(() => ({}));
           if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to send comment');
           updatePendingCommentStatus(commentId, 'sent', { baseDeckVersion: body.deckVersion || state.deckVersion });
           if (pendingCommentStatus(commentId) !== 'updated') setStatus('Comment sent. Waiting for deck update...');
+          state.sendingEdit = false;
           updateSendState();
         } catch (error) {
           updatePendingCommentStatus(commentId, 'failed');
+          state.sendingEdit = false;
           reportError(error);
           updateSendState();
         }
       }
 
+      async function searchAssets(nextBatch) {
+        const query = (els.assetQuery.value || '').trim();
+        if (!query || state.assetSearchBusy) return;
+        const key = query + '\u0000' + (els.assetPurpose.value || 'illustration');
+        if (!nextBatch || state.assetSearchKey !== key) {
+          state.assetSearchPage = 1;
+          state.assetSearchKey = key;
+        } else {
+          state.assetSearchPage += 1;
+        }
+        state.assetSearchBusy = true;
+        els.assetSearchButton.disabled = true;
+        els.assetShuffleButton.disabled = true;
+        renderAssetSearchLoading(nextBatch ? 'Searching another batch...' : 'Searching remote image sources...');
+        setButtonLoading(els.assetSearchButton, true, 'Searching...');
+        setStatus(nextBatch ? 'Searching another asset batch...' : 'Searching assets...');
+        try {
+          const params = new URLSearchParams({ query, purpose: els.assetPurpose.value || 'illustration', limit: '24', page: String(state.assetSearchPage) });
+          const res = await fetch('/api/assets/search?token=' + encodeURIComponent(token) + '&' + params.toString(), { cache: 'no-store' });
+          const body = await res.json().catch(() => ({}));
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Asset search failed');
+          state.assetCandidates = Array.isArray(body.candidates) ? body.candidates : [];
+          renderAssetCandidates();
+          setStatus(state.assetCandidates.length ? 'Asset search complete. Click + to save an asset to the workspace.' : (nextBatch ? 'No more assets found. Try another query or purpose.' : 'No assets found. Try another query or purpose.'));
+        } catch (error) {
+          if (nextBatch) state.assetSearchPage = Math.max(1, state.assetSearchPage - 1);
+          els.assetResults.innerHTML = '<p class="asset-empty">' + escapeHtml(error && error.message ? error.message : String(error)) + '</p>';
+          reportError(error);
+        } finally {
+          state.assetSearchBusy = false;
+          setButtonLoading(els.assetSearchButton, false, 'Search Assets');
+          updateAssetShuffleState();
+        }
+      }
+
+      function renderAssetSearchLoading(message) {
+        els.assetResults.innerHTML = '<p class="asset-empty"><span class="loading-row"><span class="spinner" aria-hidden="true"></span>' + escapeHtml(message) + '</span></p>'
+          + Array.from({ length: 8 }, () => '<div class="skeleton-card asset-skeleton"><div class="skeleton-line long"></div><div class="skeleton-line medium"></div></div>').join('');
+      }
+
+      function resetAssetSearchBatch() {
+        state.assetSearchPage = 1;
+        state.assetSearchKey = '';
+        updateAssetShuffleState();
+      }
+
+      function updateAssetShuffleState() {
+        els.assetShuffleButton.disabled = state.assetSearchBusy || !state.assetCandidates.length;
+      }
+
+      function renderAssetCandidates() {
+        els.assetResults.textContent = '';
+        state.assetVisibleCount = 0;
+        state.assetPendingCount = state.assetCandidates.length;
+        if (!state.assetCandidates.length) {
+          els.assetResults.innerHTML = '<p class="asset-empty">No assets found. Try another query or purpose.</p>';
+          return;
+        }
+        state.assetCandidates.forEach((candidate, index) => {
+          const card = assetCard(candidate, false, index);
+          if (state.assetSavingIndex === index) {
+            card.classList.add('is-saving');
+            appendAssetSaveButton(card, 'Saving...', 'Saving to workspace', () => {}, true);
+          } else {
+            appendAssetSaveButton(card, 'Save', 'Save to workspace', () => saveCandidate(index));
+          }
+          els.assetResults.appendChild(card);
+        });
+        updateAssetShuffleState();
+      }
+
+      async function saveCandidate(index) {
+        const candidate = state.assetCandidates[index];
+        if (!candidate) return;
+        state.assetSavingIndex = index;
+        renderAssetCandidates();
+        setStatus('Saving asset to workspace...');
+        try {
+          const res = await fetch('/api/assets/save?token=' + encodeURIComponent(token), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ candidate, purpose: els.assetPurpose.value || candidate.purpose || 'illustration' }),
+          });
+          const body = await res.json().catch(() => ({}));
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to save asset');
+          await loadSavedAssets();
+          const path = body.asset && (body.asset.path || body.asset.deckPath);
+          setStatus(path ? 'Saved to ' + path + '. Use it from Local Assets.' : 'Asset saved. Use it from Local Assets.');
+        } catch (error) {
+          reportError(error);
+        } finally {
+          state.assetSavingIndex = -1;
+          renderAssetCandidates();
+        }
+      }
+
+      async function loadSavedAssets() {
+        try {
+          const res = await fetch('/api/assets/list?token=' + encodeURIComponent(token), { cache: 'no-store' });
+          const body = await res.json().catch(() => ({}));
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to list assets');
+          state.savedAssets = Array.isArray(body.assets) ? body.assets : [];
+          renderSavedAssets();
+        } catch (error) {
+          const message = '<p class="asset-empty">' + escapeHtml(error && error.message ? error.message : String(error)) + '</p>';
+          els.editSavedAssets.innerHTML = message;
+        }
+      }
+
+      function renderSavedAssets() {
+        renderSavedAssetGrid(els.editSavedAssets, 'No local assets yet. Click + to search assets.');
+      }
+
+      function renderSavedAssetGrid(container, emptyMessage) {
+        container.textContent = '';
+        if (!state.savedAssets.length) {
+          container.innerHTML = '<p class="asset-empty">' + escapeHtml(emptyMessage) + '</p>';
+          return;
+        }
+        state.savedAssets.forEach((asset) => {
+          const card = assetCard(asset, true, 0);
+          card.draggable = true;
+          card.addEventListener('click', () => addAssetToComment(asset));
+          card.addEventListener('dragstart', (event) => {
+            state.draggingAsset = asset;
+            event.dataTransfer?.setData('application/revela-asset-id', asset.id || '');
+            event.dataTransfer?.setData('text/plain', asset.path || asset.id || '');
+            if (event.dataTransfer) event.dataTransfer.effectAllowed = 'copy';
+          });
+          card.addEventListener('dragend', () => {
+            state.draggingAsset = null;
+            document.body.classList.remove('drop-active');
+          });
+          container.appendChild(card);
+        });
+      }
+
+      function assetCard(asset, saved, index) {
+        const card = document.createElement('div');
+        card.className = saved ? 'asset-card saved' : 'asset-card';
+        const image = document.createElement('img');
+        image.className = 'asset-thumb';
+        image.loading = !saved && index < 8 ? 'eager' : 'lazy';
+        image.decoding = 'async';
+        image.alt = asset.alt || asset.title || asset.id || 'Image asset';
+        if (!saved) {
+          image.addEventListener('load', () => markAssetImageLoaded());
+          image.addEventListener('error', () => hideBrokenAssetCard(card));
+        }
+        image.src = saved ? (asset.previewUrl || '') : (asset.thumbnailUrl || asset.imageUrl || '');
+        card.title = asset.title || asset.id || asset.alt || 'Image asset';
+        card.appendChild(image);
+        return card;
+      }
+
+      function markAssetImageLoaded() {
+        state.assetVisibleCount += 1;
+        state.assetPendingCount = Math.max(0, state.assetPendingCount - 1);
+      }
+
+      function hideBrokenAssetCard(card) {
+        card.remove();
+        state.assetPendingCount = Math.max(0, state.assetPendingCount - 1);
+        if (!state.assetVisibleCount && !state.assetPendingCount) {
+          els.assetResults.innerHTML = '<p class="asset-empty">No displayable images found. Try Refresh or another purpose.</p>';
+        }
+      }
+
+      function appendAssetSaveButton(card, text, label, onClick, loading) {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'asset-save';
+        button.innerHTML = loading ? '<span class="spinner" aria-hidden="true"></span><span>' + escapeHtml(text) + '</span>' : escapeHtml(text);
+        button.disabled = !!loading;
+        button.setAttribute('aria-label', label);
+        button.title = label;
+        button.addEventListener('click', onClick);
+        card.appendChild(button);
+      }
+
+      function addAssetToComment(asset) {
+        if (!asset) return;
+        state.selectedAsset = asset;
+        removeAssetChip();
+        const intro = els.comment.textContent && !/\s$/.test(els.comment.textContent) ? ' Use asset ' : 'Use asset ';
+        insertPlainText(intro);
+        insertAssetChip(asset);
+        insertPlainText(' ');
+        setMode('edit');
+        updateSendState();
+        setStatus('Asset added to the Edit comment. Describe where or how to use it, then Apply Fix.');
+      }
+
+      function onAssetDragOver(event) {
+        if (!state.draggingAsset) return;
+        event.preventDefault();
+        if (event.dataTransfer) event.dataTransfer.dropEffect = 'copy';
+        document.body.classList.add('drop-active');
+        const placement = collectAssetPlacement(event, state.draggingAsset);
+        renderAssetDropTarget(placement);
+      }
+
+      function onAssetDragLeave() {
+        document.body.classList.remove('drop-active');
+        renderAssetDropTarget(null);
+      }
+
+      async function onAssetDrop(event) {
+        const asset = state.draggingAsset || findSavedAsset(event.dataTransfer?.getData('application/revela-asset-id'));
+        if (!asset) return;
+        event.preventDefault();
+        document.body.classList.remove('drop-active');
+        renderAssetDropTarget(null);
+        const placement = collectAssetPlacement(event, asset);
+        if (!placement) {
+          setStatus('Drop the asset onto a deck slide.');
+          return;
+        }
+        await sendAssetPlacement(asset, placement);
+      }
+
+      function findSavedAsset(id) {
+        return state.savedAssets.find((asset) => asset.id === id) || null;
+      }
+
+      function collectAssetPlacement(event, asset) {
+        initFrame();
+        const doc = els.frame.contentDocument;
+        const win = els.frame.contentWindow;
+        if (!doc || !win) return null;
+        const frameRect = els.frame.getBoundingClientRect();
+        const frameX = event.clientX - frameRect.left;
+        const frameY = event.clientY - frameRect.top;
+        const rawTarget = doc.elementFromPoint(frameX, frameY);
+        const target = selectable(rawTarget);
+        const slide = findSlide(target) || findSlide(rawTarget);
+        if (!slide) return null;
+        const slides = getSlides(doc);
+        const explicitSlideIndex = Number(slide.getAttribute('data-slide-index'));
+        const slideIndex = Number.isFinite(explicitSlideIndex) && explicitSlideIndex > 0 ? explicitSlideIndex : slides.indexOf(slide) + 1;
+        const slideRect = slide.getBoundingClientRect();
+        const x = slideRect.width ? Math.max(0, Math.min(1, (frameX - slideRect.left) / slideRect.width)) : 0;
+        const y = slideRect.height ? Math.max(0, Math.min(1, (frameY - slideRect.top) / slideRect.height)) : 0;
+        const targetPayload = target && target !== slide ? collectPayload(target) : null;
+        const targetMode = targetPayload
+          ? (target && target.tagName && target.tagName.toLowerCase() === 'img' ? 'replace' : 'insert-into')
+          : 'add';
+        return {
+          slideIndex,
+          x,
+          y,
+          viewport: { width: win.innerWidth, height: win.innerHeight },
+          nearbyText: (slide.innerText || slide.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 1000),
+          targetMode,
+          target: targetPayload,
+          targetLabel: targetMode === 'replace' ? 'Replace image' : targetMode === 'insert-into' ? 'Insert into this element' : 'Add near here',
+          targetTagName: target?.tagName?.toLowerCase(),
+        };
+      }
+
+      function renderAssetDropTarget(placement) {
+        if (!state.assetDropOutline) return;
+        const target = placement?.target ? elementFromPayload(placement.target) : null;
+        state.assetDropTarget = target;
+        renderBox(state.assetDropOutline, target);
+        if (placement?.targetLabel) setStatus(placement.targetLabel + '. Drop to send an asset placement comment.');
+      }
+
+      function elementFromPayload(payload) {
+        const doc = els.frame.contentDocument;
+        if (!doc || !payload) return null;
+        const slides = getSlides(doc);
+        const slide = slides.find((item, index) => {
+          const explicit = Number(item.getAttribute('data-slide-index'));
+          const slideIndex = Number.isFinite(explicit) && explicit > 0 ? explicit : index + 1;
+          return slideIndex === payload.slideIndex;
+        });
+        if (!slide) return null;
+        if (payload.selector) {
+          try {
+            const selected = slide.querySelector(payload.selector);
+            if (selected) return selected;
+          } catch {}
+        }
+        return slide;
+      }
+
+      async function sendAssetPlacement(asset, placement) {
+        const modeText = placement.targetMode === 'replace'
+          ? 'replace the image at the drop target'
+          : placement.targetMode === 'insert-into'
+            ? 'insert it into the target element'
+            : 'add it near the drop point';
+        const comment = 'Place workspace asset ' + asset.path + ' on slide ' + placement.slideIndex + ' as a ' + (asset.purpose || 'visual asset') + '; ' + modeText + '. Preserve the current layout and do not cover existing text, charts, tables, or evidence.';
+        const elements = placement.target ? [placement.target] : [];
+        const commentId = addPendingComment(comment, elements, 'sending');
+        setStatus('Sending asset placement comment...');
+        try {
+          const res = await fetch('/api/comment?token=' + encodeURIComponent(token), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ comment, elements, asset, drop: placement }),
+          });
+          const body = await res.json().catch(() => ({}));
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to send asset placement');
+          updatePendingCommentStatus(commentId, 'sent', { baseDeckVersion: body.deckVersion || state.deckVersion });
+          if (pendingCommentStatus(commentId) !== 'updated') setStatus('Asset placement sent. Waiting for deck update...');
+        } catch (error) {
+          updatePendingCommentStatus(commentId, 'failed');
+          reportError(error);
+        }
+      }
+
       function selectable(node) {
         if (!node || node.nodeType !== 1) return null;
         if (node === state.hoverOutline || state.referenceOutlines.includes(node)) return null;
@@ -1094,7 +1829,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         renderReferenceOutlines();
         updateSendState();
         renderSelectionSummary();
-        resetInspectCards('References ready. Open Inspect and click Inspect Selection when you want Narrative Reading, Exploratory Reading, Source, and Purpose review.');
+        resetInspectCards('References ready. Open Inspect and click Inspect Reference for concise Purpose and Source context.');
         setStatus('Inserted @' + label + '. ' + state.references.length + ' reference' + (state.references.length === 1 ? '' : 's') + ' will be sent.');
       }
 
@@ -1116,8 +1851,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         updateSendState();
       }
 
-      function syncReferencesFromComment(showStatus) {
-        const activeIds = new Set(Array.from(els.comment.querySelectorAll('.ref-chip[data-ref-id]')).map((chip) => chip.getAttribute('data-ref-id')));
+      function syncReferencesFromComment(showStatus, editor) {
+        const source = editor || activeCommentEditor();
+        const activeIds = new Set(Array.from(source.querySelectorAll('.ref-chip[data-ref-id]')).map((chip) => chip.getAttribute('data-ref-id')));
         const before = state.references.length;
         state.references = state.references.filter((reference) => activeIds.has(reference.id));
         if (state.references.length !== before) {
@@ -1127,6 +1863,11 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         }
       }
 
+      function syncSelectedAssetFromComment() {
+        if (els.comment.querySelector('.asset-ref-chip[data-asset-id]')) return;
+        state.selectedAsset = null;
+      }
+
       function addPendingComment(text, elements, status) {
         const id = 'comment-' + state.nextCommentId++;
         state.pendingComments.push({
@@ -1271,10 +2012,20 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       }
 
       function updateSendState() {
-        els.send.disabled = !getCommentText().trim();
+        if (state.sendingEdit) setButtonLoading(els.send, true, 'Sending...');
+        else setButtonLoading(els.send, false, '<svg class="send-icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94L14.7 6.3z"/></svg><span>Apply Fix</span>', true);
+        els.send.disabled = state.sendingEdit || !getCommentText().trim();
+        if (state.inspecting) setButtonLoading(els.inspectButton, true, 'Inspecting...');
+        else setButtonLoading(els.inspectButton, false, 'Inspect Reference');
         els.inspectButton.disabled = state.inspecting || state.references.length === 0;
       }
 
+      function setButtonLoading(button, loading, label, html) {
+        if (!button) return;
+        button.innerHTML = loading ? '<span class="spinner" aria-hidden="true"></span><span>' + escapeHtml(label) + '</span>' : (html ? label : escapeHtml(label));
+        button.disabled = !!loading;
+      }
+
       function renderSelectionSummary() {
         const label = state.references.length
           ? state.references.length + ' referenced element' + (state.references.length === 1 ? '' : 's') + ' selected.'
@@ -1298,27 +2049,39 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         els.inspectCards.innerHTML = '<div class="inspect-empty">' + escapeHtml(message) + '</div>';
       }
 
+      function renderInspectLoading(message) {
+        els.inspectCards.innerHTML = '<div class="inspect-loading"><span class="loading-row"><span class="spinner" aria-hidden="true"></span><b>' + escapeHtml(message) + '</b></span><br>Preparing concise Purpose and Source context.</div>'
+          + '<div class="skeleton-card"><div class="skeleton-line short"></div><div class="skeleton-line long"></div><div class="skeleton-line medium"></div></div>'
+          + '<div class="skeleton-card"><div class="skeleton-line short"></div><div class="skeleton-line long"></div><div class="skeleton-line medium"></div></div>';
+      }
+
+      function getInspectComment() {
+        syncReferencesFromComment(false, els.inspectComment);
+        return getCommentText(els.inspectComment).trim().slice(0, 2000);
+      }
+
       async function inspectCurrentSelection() {
         if (!state.references.length || state.inspecting) return;
         const snapshot = collectReferenceSnapshot();
+        const comment = getInspectComment();
         state.inspecting = true;
         updateSendState();
         setMode('inspect');
         els.inspectStale.innerHTML = '';
         state.inspectFallback = null;
-        els.inspectCards.innerHTML = '<div class="inspect-loading"><b>Reading selection...</b><br>Sending grounded selection context to OpenCode. Deterministic context is kept as fallback if generation fails.</div>';
+        renderInspectLoading('Reading selection...');
         try {
           const res = await fetch('/api/inspect?token=' + encodeURIComponent(token), {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ snapshot, deckVersion: state.deckVersion, language: state.inspectLanguage }),
+            body: JSON.stringify({ snapshot, deckVersion: state.deckVersion, language: state.inspectLanguage, comment }),
           });
           const body = await res.json().catch(() => ({}));
           if (!res.ok || !body.ok) throw new Error(body.error || 'Inspection failed');
           state.deckVersion = body.deckVersion || state.deckVersion;
           state.activeInspectRequestId = body.requestId;
           state.inspectFallback = body.preprocess || null;
-          els.inspectCards.innerHTML = '<div class="inspect-loading"><b>Reading selection...</b><br>Waiting for localized structured reading cards.</div>';
+          renderInspectLoading('Waiting for Purpose and Source...');
           await pollInspectResult(body.requestId);
         } catch (error) {
           if (state.inspectFallback) {
@@ -1377,8 +2140,6 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         else els.inspectStale.innerHTML = '';
         els.inspectCards.innerHTML = [
           '<div class="status">' + escapeHtml(phase || 'Inspection') + '</div>',
-          result.cards.reading ? renderInspectCard('Narrative Reading', result.cards.reading.status, result.cards.reading.rationale, renderReading(result.cards.reading)) : '',
-          result.cards.exploratory ? renderInspectCard('Exploratory Reading', result.cards.exploratory.status, result.cards.exploratory.rationale, renderExploratory(result.cards.exploratory)) : '',
           renderInspectCard('Purpose', result.cards.purpose.status, result.cards.purpose.rationale, renderPurpose(result.cards.purpose)),
           renderInspectCard('Source', result.cards.source.status, result.cards.source.rationale, renderSource(result.cards.source)),
         ].join('');
@@ -1456,6 +2217,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       }
 
       function insertReferenceChip(reference) {
+        const editor = activeCommentEditor();
         const chip = document.createElement('span');
         chip.className = 'ref-chip';
         chip.contentEditable = 'false';
@@ -1473,16 +2235,60 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           range.collapse(true);
           applyCommentRange(range);
         } else {
-          if (els.comment.textContent && !/\\s$/.test(els.comment.textContent)) els.comment.appendChild(document.createTextNode(' '));
-          els.comment.appendChild(chip);
-          els.comment.appendChild(trailingSpace);
+          if (editor.textContent && !/\\s$/.test(editor.textContent)) editor.appendChild(document.createTextNode(' '));
+          editor.appendChild(chip);
+          editor.appendChild(trailingSpace);
           placeCaretAfter(trailingSpace);
         }
+        editor.focus();
+      }
+
+      function insertAssetChip(asset) {
+        const chip = document.createElement('span');
+        chip.className = 'ref-chip asset-ref-chip';
+        chip.contentEditable = 'false';
+        chip.dataset.assetId = asset.id || '';
+        chip.style.setProperty('--ref-bg', '#dcfce7');
+        chip.style.setProperty('--ref-border', '#86efac');
+        chip.style.setProperty('--ref-text', '#166534');
+        chip.textContent = '@Asset ' + (asset.id || asset.deckPath || asset.path || 'image');
+        const range = getCommentInsertRange();
+        if (range) {
+          range.insertNode(chip);
+          range.setStartAfter(chip);
+          range.collapse(true);
+          applyCommentRange(range);
+        } else {
+          els.comment.appendChild(chip);
+          placeCaretAfter(chip);
+        }
         els.comment.focus();
       }
 
+      function insertPlainText(text) {
+        const node = document.createTextNode(text);
+        const range = getCommentInsertRange();
+        if (range) {
+          range.insertNode(node);
+          range.setStartAfter(node);
+          range.collapse(true);
+          applyCommentRange(range);
+        } else {
+          els.comment.appendChild(node);
+          placeCaretAfter(node);
+        }
+      }
+
+      function removeAssetChip() {
+        els.comment.querySelectorAll('.asset-ref-chip').forEach((chip) => {
+          const next = chip.nextSibling;
+          chip.remove();
+          if (next && next.nodeType === Node.TEXT_NODE && next.textContent === ' ') next.remove();
+        });
+      }
+
       function removeReferenceChip(id) {
-        const chip = els.comment.querySelector('.ref-chip[data-ref-id="' + cssEscape(id) + '"]');
+        const chip = activeCommentEditor().querySelector('.ref-chip[data-ref-id="' + cssEscape(id) + '"]');
         if (!chip) return;
         const next = chip.nextSibling;
         chip.remove();
@@ -1491,13 +2297,18 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
 
       function clearReferences(removeChips) {
         state.references = [];
-        if (removeChips) els.comment.querySelectorAll('.ref-chip').forEach((chip) => chip.remove());
+        if (removeChips) {
+          activeCommentEditor().querySelectorAll('.ref-chip[data-ref-id]').forEach((chip) => chip.remove());
+          state.selectedAsset = null;
+          removeAssetChip();
+        }
         renderSelectionSummary();
-        resetInspectCards('Select one or more deck elements, then inspect them for Narrative Reading, Exploratory Reading, Source, and Purpose. This does not edit the deck.');
+        resetInspectCards('Select a deck element to create an @ref, optionally ask a question, then Inspect. This does not edit the deck.');
       }
 
-      function getCommentText() {
-        return (els.comment.innerText || els.comment.textContent || '').replace(/\\u00a0/g, ' ');
+      function getCommentText(editor) {
+        const source = editor || els.comment;
+        return (source.innerText || source.textContent || '').replace(/\\u00a0/g, ' ');
       }
 
       function placeCaretAfter(node) {
@@ -1510,18 +2321,20 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       function saveCommentRange() {
         const selection = window.getSelection();
         if (!selection || selection.rangeCount === 0) return;
-        if (!els.comment || !els.comment.contains(selection.anchorNode)) return;
+        const editor = activeCommentEditor();
+        if (!editor || !editor.contains(selection.anchorNode)) return;
         state.commentRange = selection.getRangeAt(0).cloneRange();
       }
 
       function getCommentInsertRange() {
+        const editor = activeCommentEditor();
         const selection = window.getSelection();
-        if (selection && selection.rangeCount > 0 && els.comment.contains(selection.anchorNode)) {
+        if (selection && selection.rangeCount > 0 && editor.contains(selection.anchorNode)) {
           const range = selection.getRangeAt(0).cloneRange();
           range.deleteContents();
           return range;
         }
-        if (state.commentRange && els.comment.contains(state.commentRange.commonAncestorContainer)) {
+        if (state.commentRange && editor.contains(state.commentRange.commonAncestorContainer)) {
           const range = state.commentRange.cloneRange();
           range.deleteContents();
           return range;