@cyber-dash-tech/revela 0.15.1 → 0.15.2

package/lib/edit/prompt.ts

@@ -24,6 +24,8 @@ export interface EditCommentPayload extends EditSelectedElementPayload {
   comment: string
   elements?: EditSelectedElementPayload[]
   comments?: EditCommentDraftPayload[]
+  asset?: Record<string, unknown>
+  drop?: Record<string, unknown>
 }
 
 export function buildEditPrompt(payload: EditCommentPayload): string {
@@ -54,6 +56,8 @@ export function buildEditPrompt(payload: EditCommentPayload): string {
     deck: payload.deck,
     file: payload.file,
     comments,
+    asset: payload.asset,
+    drop: payload.drop,
   }
 
   return `The user left a visual edit comment on a Revela slide deck.
@@ -75,6 +79,14 @@ Instructions:
 - Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, runtime JavaScript fixes, or deck HTML contract fixes may remain an artifact-level edit.
 - If the request mixes content meaning and visual polish, treat it as narrative-impacting unless the user clarifies otherwise.
 - Preserve the existing deck structure, active design language, typography, spacing system, animations, and slide count unless the comment explicitly asks otherwise.
+- If an asset/drop payload is present, this is an asset placement request. Use only the saved local asset path from the asset payload in deck HTML. Prefer asset.deckPath when present because it is relative to the target HTML file; otherwise use asset.path.
+- Do not write remote imageUrl, thumbnailUrl, source page URLs, or ${"`/__revela_asset`"} proxy URLs into deck HTML.
+- Logo assets should remain small, clear, and brand-like; do not use logos as decorative backgrounds.
+- Photography can be cropped or masked when appropriate, but must not cover text, charts, tables, evidence, or important claims.
+- Screenshots, diagrams, charts, tables, and evidence images must remain readable and should not be converted into decorative hero imagery.
+- For asset targetMode ${"`replace`"}, prefer replacing the targeted image or visual element. For ${"`insert-into`"}, place the asset inside the targeted card, media box, or semantic container while preserving that element's layout role. For ${"`add`"}, place the asset near the drop coordinates within the existing layout or semantic box. Do not invent a new visual system when the existing deck grammar can express the placement.
+- If an asset payload is present without drop coordinates, use the user's comment and selected element context to choose placement; if placement remains ambiguous, ask one concise clarification question instead of guessing.
+- Preserve source/license/attribution facts if you surface them in visible notes; do not invent missing licensing or attribution.
 - Do not rewrite unrelated slides or broad sections of the deck.
 - Locate each target primarily with slideIndex, slideTitle, selected text, nearbyText, and outerHTMLExcerpt. Use selector/domPath as hints; they may be approximate.
 - For targeted artifact-level edits, patch ${"`decks/*.html`"} directly. Do not call ${"`revela-decks`"} action ${"`review`"} as a precondition, and do not let ${"`writeReadiness`"}, ${"`planReview`"}, or ${"`slide_plan_unconfirmed`"} block the patch.

package/lib/inspect/prompt.ts

@@ -5,21 +5,25 @@ export function buildInspectionPrompt(input: {
   file: string
   projection: InspectionPromptProjection
   language?: string
+  comment?: string
 }): string {
   const language = normalizeInspectLanguage(input.language)
+  const comment = typeof input.comment === "string" && input.comment.trim() ? input.comment.trim() : ""
   return `A user selected slide content in Revela Evidence Inspector. The selection may contain one referenced element, a whole slide, or multiple referenced elements selected with Cmd/Ctrl-click.
 
 Target file: ${input.file}
 Inspection request id: ${input.requestId}
 Display language: ${language}
+User inspect comment: ${comment || "(none; explain purpose and source only)"}
 
-Use the structured projection below to produce the final inspector cards. This is LLM judgment with grounded boundaries: explain the selected object's narrative reading context, bounded exploratory reading context, purpose, and source credibility only. Do not edit files. Do not mutate DECKS.json. Do not invent claim ids, evidence binding ids, sources, quotes, URLs, page references, caveats, objections, risks, artifact coverage, or evidence not present in the projection.
+Use the structured projection below to produce the final inspector cards. This is LLM judgment with grounded boundaries. The user's inspect comment is the complete request about the selected reference; do not parse it into a separate question field. The user primarily wants to understand the selected component: what purpose it serves and what source support exists. Use narrative reading and exploratory reading only as internal grounding unless needed to answer the user's comment. Do not edit files. Do not mutate DECKS.json. Do not invent claim ids, evidence binding ids, sources, quotes, URLs, page references, caveats, objections, risks, artifact coverage, or evidence not present in the projection.
 
 Language boundary: the selected display language affects only human-readable card copy. Preserve all claim ids, canonical claim ids, evidence binding ids, source paths, findings files, URLs, numbers, quoted/source facts, caveats, artifact ids, and coverage statuses exactly as grounded in the projection. If the display language is Auto, use projection.deck.language when available; otherwise follow the user's/browser context or default to English.
 
 Return the result only by calling the \`revela-inspection-result\` tool with this request id. Do not answer in chat.
 
 Required card model:
+- User inspect comment: if present, answer it through the Purpose and Source cards first. If it asks about trust, provenance, evidence, factuality, or where a number came from, prioritize Source. If it asks why something is on the slide or what it is doing, prioritize Purpose.
 - Narrative Reading: when the projection includes a matched claim, preserve its claim id, canonical claim id, evidence binding ids, supported scope, unsupported scope, caveats, related objections, related risks, and artifact coverage. Artifact coverage must come only from projection.cards.artifacts; do not invent where a claim appears or whether an artifact is stale/current/partial/missing. If canonical narrative linkage is missing, say so and fall back to the matched slide claim; do not invent canonical ids.
 - Candidate boundary: when projection.match.claim is absent but projection.match.candidateClaims is present, explain the selected child element only within those candidate claim boundaries. You may describe that the child element functions as a detail, prerequisite, source note, risk cue, or evidence cue inside the slide, but you must not select one candidate claim id by semantic guess. If projection.match.confidence is none or candidateClaims is empty, explain the mapping gap instead of inventing a plausible claim.
 - Exploratory Reading: provide bounded, non-official reading cues for objection prep, audience reframing, appendix leads, and meeting prep only from the projection. Mark official as false. Keep missing evidence, caveats, unsupported scope, and stale artifacts visible. Do not make exploratory text sound like approved artifact content, and do not turn this into chat or a fix plan.
@@ -29,6 +33,7 @@ Required card model:
 Boundaries:
 - Do not hunt for problems. If it works, say it works.
 - Do not recommend edits or fixes; this inspector view only explains narrative context, bounded exploratory reading context, purpose, and source credibility.
+- Keep Purpose and Source concise and directly useful. Avoid long narrative-reading exposition unless the selected content cannot be explained without it.
 - Do not turn every caveat into a problem.
 - If confidence is low, use unclear or unknown instead of pretending certainty.
 

package/lib/media/download.ts

@@ -3,11 +3,15 @@ import { extname } from "path"
 const MIME_TO_EXT: Record<string, string> = {
   "image/png": ".png",
   "image/jpeg": ".jpg",
+  "image/svg+xml": ".svg",
   "image/webp": ".webp",
   "image/gif": ".gif",
+  "image/x-icon": ".ico",
+  "image/vnd.microsoft.icon": ".ico",
 }
 
-const ALLOWED_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"])
+const ALLOWED_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".svg", ".webp", ".gif", ".ico"])
+const DEFAULT_DOWNLOAD_TIMEOUT_MS = 10_000
 
 function normalizeExtension(ext: string): string {
   const value = ext.toLowerCase()
@@ -30,6 +34,7 @@ export function inferImageExtension(contentType: string | null, sourceName = "")
 
 export async function downloadImageFromUrl(
   url: string,
+  options: { timeoutMs?: number } = {},
 ): Promise<{ buffer: Buffer; contentType: string | null; extension: string }> {
   let parsed: URL
   try {
@@ -42,16 +47,36 @@ export async function downloadImageFromUrl(
     throw new Error("INVALID_URL")
   }
 
-  const response = await fetch(parsed, {
-    headers: {
-      "User-Agent":
-        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
-        "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
-    },
-  })
+  const controller = new AbortController()
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    controller.abort()
+  }, Math.max(1, options.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS))
 
-  if (!response.ok) {
-    throw new Error(`DOWNLOAD_FAILED:${response.status}`)
+  let response: Response
+  let buffer: Buffer
+  try {
+    response = await fetch(parsed, {
+      headers: {
+        Accept: "image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8",
+        "User-Agent":
+          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+          "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
+      },
+      signal: controller.signal,
+    })
+
+    if (!response.ok) {
+      throw new Error(`DOWNLOAD_FAILED:${response.status}`)
+    }
+
+    buffer = Buffer.from(await response.arrayBuffer())
+  } catch (error) {
+    if (timedOut) throw new Error("DOWNLOAD_TIMEOUT")
+    throw error
+  } finally {
+    clearTimeout(timer)
   }
 
   const contentType = response.headers.get("content-type")
@@ -61,7 +86,7 @@ export async function downloadImageFromUrl(
   }
 
   return {
-    buffer: Buffer.from(await response.arrayBuffer()),
+    buffer,
     contentType,
     extension,
   }

package/lib/media/save.ts

@@ -69,6 +69,12 @@ function buildFailureRecord(
     alt: input.alt,
     notes: input.notes,
     failureReason,
+    provider: input.provider,
+    sourcePageUrl: input.sourcePageUrl,
+    license: input.license,
+    attribution: input.attribution,
+    width: input.width,
+    height: input.height,
     savedAt: nowIso(),
   }
 }
@@ -112,6 +118,12 @@ function saveFailureResult(
       sourcePath: sourcePath ?? existing.sourcePath,
       alt: input.alt ?? existing.alt,
       notes: input.notes ?? existing.notes,
+      provider: input.provider ?? existing.provider,
+      sourcePageUrl: input.sourcePageUrl ?? existing.sourcePageUrl,
+      license: input.license ?? existing.license,
+      attribution: input.attribution ?? existing.attribution,
+      width: input.width ?? existing.width,
+      height: input.height ?? existing.height,
       failureReason,
     }
     : buildFailureRecord(input, topic, status, failureReason, sourcePath)
@@ -196,6 +208,12 @@ export async function saveMediaAsset(input: MediaSaveInput, workspaceDir: string
         intendedSection: input.intendedSection,
         alt: input.alt,
         notes: input.notes,
+        provider: input.provider,
+        sourcePageUrl: input.sourcePageUrl,
+        license: input.license,
+        attribution: input.attribution,
+        width: input.width,
+        height: input.height,
         savedAt: nowIso(),
       }
       const { manifest: nextManifest } = upsertAsset(manifest, record)
@@ -248,6 +266,12 @@ export async function saveMediaAsset(input: MediaSaveInput, workspaceDir: string
       intendedSection: input.intendedSection,
       alt: input.alt,
       notes: input.notes,
+      provider: input.provider,
+      sourcePageUrl: input.sourcePageUrl,
+      license: input.license,
+      attribution: input.attribution,
+      width: input.width,
+      height: input.height,
       savedAt: nowIso(),
     }
     const { manifest: nextManifest } = upsertAsset(manifest, record)

package/lib/media/search.ts

@@ -0,0 +1,385 @@
+import type { MediaPurpose } from "./types"
+
+export interface ImageCandidate {
+  candidateId: string
+  provider: string
+  title: string
+  thumbnailUrl: string
+  imageUrl: string
+  sourcePageUrl?: string
+  width?: number
+  height?: number
+  alt?: string
+  license?: string
+  attribution?: string
+  purpose?: MediaPurpose
+}
+
+export interface ImageSearchInput {
+  query: string
+  purpose?: MediaPurpose
+  limit?: number
+  page?: number
+  signal?: AbortSignal
+  providerTimeoutMs?: number
+}
+
+export interface ImageSearchProvider {
+  name: string
+  search(input: ImageSearchInput): Promise<ImageCandidate[]>
+}
+
+const PROVIDER_TIMEOUT_MS: Record<string, number> = {
+  "website-metadata": 3000,
+  unsplash: 6000,
+  "wikimedia-commons": 7000,
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+function normalizeLimit(limit: number | undefined): number {
+  if (!Number.isFinite(limit ?? Number.NaN)) return 12
+  return Math.max(1, Math.min(48, Math.floor(limit!)))
+}
+
+function normalizePage(page: number | undefined): number {
+  if (!Number.isFinite(page ?? Number.NaN)) return 1
+  return Math.max(1, Math.floor(page!))
+}
+
+function domainFromQuery(query: string): string | null {
+  const value = query.trim().toLowerCase()
+  if (!value) return null
+  const withoutProtocol = value.replace(/^https?:\/\//, "").replace(/^www\./, "")
+  const first = withoutProtocol.split(/[\s/]+/)[0]
+  if (/^[a-z0-9.-]+\.[a-z]{2,}$/.test(first)) return first
+  const compact = value.replace(/\b(logo|company|brand)\b/g, "").replace(/[^a-z0-9]+/g, "")
+  if (!compact) return null
+  return `${compact}.com`
+}
+
+function textFromMetadata(value: unknown): string | undefined {
+  if (!value || typeof value !== "object") return undefined
+  const raw = (value as { value?: unknown }).value
+  return typeof raw === "string" && raw.trim() ? raw.replace(/<[^>]+>/g, "").trim() : undefined
+}
+
+function compactBrandName(query: string): string | null {
+  const value = query
+    .toLowerCase()
+    .replace(/^https?:\/\//, "")
+    .replace(/^www\./, "")
+    .split(/[\s/]+/)[0]
+    .replace(/\.[a-z]{2,}$/, "")
+    .replace(/\b(logo|company|brand)\b/g, "")
+    .replace(/[^a-z0-9]+/g, "")
+  return value || null
+}
+
+function absoluteUrl(value: string, base: string): string | undefined {
+  try {
+    return new URL(value, base).toString()
+  } catch {
+    return undefined
+  }
+}
+
+function uniqueValues(values: Array<string | undefined>): string[] {
+  const seen = new Set<string>()
+  return values.flatMap((value) => {
+    if (!value || seen.has(value)) return []
+    seen.add(value)
+    return [value]
+  })
+}
+
+function htmlAttr(tag: string, attr: string): string | undefined {
+  const pattern = new RegExp(`${attr}=["']([^"']+)["']`, "i")
+  return tag.match(pattern)?.[1]
+}
+
+function htmlMetaContent(html: string, property: string): string | undefined {
+  const tags = html.match(/<meta\b[^>]*>/gi) ?? []
+  const needle = property.toLowerCase()
+  for (const tag of tags) {
+    const key = htmlAttr(tag, "property") || htmlAttr(tag, "name")
+    if (key?.toLowerCase() === needle) return htmlAttr(tag, "content")
+  }
+  return undefined
+}
+
+function htmlIconLinks(html: string): string[] {
+  const tags = html.match(/<link\b[^>]*>/gi) ?? []
+  return tags.flatMap((tag) => {
+    const rel = htmlAttr(tag, "rel")?.toLowerCase() ?? ""
+    if (!rel.includes("icon") && !rel.includes("apple-touch-icon")) return []
+    return htmlAttr(tag, "href") ?? []
+  })
+}
+
+function queryForPurpose(query: string, purpose: MediaPurpose | undefined): string {
+  const value = query.trim()
+  if (!value) return value
+  if (purpose === "hero") return `${value} hero background professional photography`
+  if (purpose === "portrait") return `${value} portrait headshot`
+  if (purpose === "screenshot") return `${value} screenshot interface product`
+  if (purpose === "illustration") return `${value} professional photo concept visual`
+  return value
+}
+
+function wikimediaQueryForPurpose(query: string, purpose: MediaPurpose | undefined): string {
+  const value = query.trim()
+  if (!value) return value
+  if (purpose === "portrait") return `${value} portrait`
+  if (purpose === "screenshot") return `${value} screenshot`
+  return value
+}
+
+export const clearbitLogoProvider: ImageSearchProvider = {
+  name: "clearbit-logo",
+  async search(input) {
+    if (normalizePage(input.page) > 1) return []
+    if (input.purpose && input.purpose !== "logo") return []
+    const domain = domainFromQuery(input.query)
+    if (!domain) return []
+    const title = `${domain} logo`
+    return [{
+      candidateId: `clearbit-${slugify(domain)}`,
+      provider: this.name,
+      title,
+      thumbnailUrl: `https://logo.clearbit.com/${encodeURIComponent(domain)}`,
+      imageUrl: `https://logo.clearbit.com/${encodeURIComponent(domain)}`,
+      sourcePageUrl: `https://${domain}`,
+      alt: title,
+      purpose: "logo",
+    }]
+  },
+}
+
+export const simpleIconsProvider: ImageSearchProvider = {
+  name: "simple-icons",
+  async search(input) {
+    if (normalizePage(input.page) > 1) return []
+    if (input.purpose && input.purpose !== "logo") return []
+    const brand = compactBrandName(input.query)
+    if (!brand) return []
+    const title = `${brand} logo`
+    const cdnUrl = `https://cdn.simpleicons.org/${encodeURIComponent(brand)}`
+    const imageUrl = `https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/${encodeURIComponent(brand)}.svg`
+    return [{
+      candidateId: `simple-icons-${slugify(brand)}`,
+      provider: this.name,
+      title,
+      thumbnailUrl: cdnUrl,
+      imageUrl,
+      sourcePageUrl: `https://simpleicons.org/?q=${encodeURIComponent(brand)}`,
+      alt: title,
+      license: "See Simple Icons source license",
+      attribution: "Simple Icons",
+      purpose: "logo",
+    }]
+  },
+}
+
+export const websiteMetadataProvider: ImageSearchProvider = {
+  name: "website-metadata",
+  async search(input) {
+    if (normalizePage(input.page) > 1) return []
+    const domain = domainFromQuery(input.query)
+    if (!domain) return []
+    const homepage = `https://${domain}`
+    const response = await fetch(homepage, {
+      headers: { "user-agent": "Revela/0.15 asset search" },
+      signal: input.signal,
+    })
+    if (!response.ok) throw new Error(`Website metadata fetch failed: ${response.status}`)
+    const html = await response.text()
+    const title = htmlMetaContent(html, "og:site_name") || html.match(/<title[^>]*>([^<]+)<\/title>/i)?.[1]?.trim() || domain
+    const socialImages = [htmlMetaContent(html, "og:image"), htmlMetaContent(html, "twitter:image")]
+    const icons = [...htmlIconLinks(html), "/favicon.ico"]
+    const sourceUrls = input.purpose === "logo"
+      ? icons
+      : input.purpose === "screenshot"
+        ? socialImages
+        : socialImages
+    const urls = uniqueValues(sourceUrls.map((value) => value ? absoluteUrl(value, homepage) : undefined))
+    return urls.slice(0, normalizeLimit(input.limit)).map((imageUrl, index) => ({
+      candidateId: `website-${slugify(domain)}-${index + 1}`,
+      provider: this.name,
+      title: index === 0 ? `${title} image` : `${title} icon ${index}`,
+      thumbnailUrl: imageUrl,
+      imageUrl,
+      sourcePageUrl: homepage,
+      alt: `${title} image`,
+      purpose: input.purpose,
+    }))
+  },
+}
+
+export const unsplashProvider: ImageSearchProvider = {
+  name: "unsplash",
+  async search(input) {
+    const accessKey = process.env.UNSPLASH_ACCESS_KEY?.trim()
+    if (!accessKey) return []
+    if (input.purpose === "logo" || input.purpose === "screenshot") return []
+    const limit = normalizeLimit(input.limit)
+    const page = normalizePage(input.page)
+    const url = new URL("https://api.unsplash.com/search/photos")
+    url.searchParams.set("query", input.query)
+    url.searchParams.set("per_page", String(Math.min(30, limit)))
+    url.searchParams.set("page", String(page))
+    url.searchParams.set("orientation", input.purpose === "portrait" ? "portrait" : "landscape")
+    const response = await fetch(url, {
+      headers: {
+        authorization: `Client-ID ${accessKey}`,
+        "accept-version": "v1",
+        "user-agent": "Revela/0.15 asset search",
+      },
+      signal: input.signal,
+    })
+    if (!response.ok) throw new Error(`Unsplash search failed: ${response.status}`)
+    const body = await response.json() as any
+    const results = Array.isArray(body?.results) ? body.results : []
+    return results.flatMap((item: any) => {
+      const imageUrl = typeof item?.urls?.regular === "string" ? item.urls.regular : ""
+      if (!imageUrl) return []
+      const title = item.description || item.alt_description || "Unsplash photo"
+      const author = item.user?.name ? String(item.user.name) : undefined
+      return [{
+        candidateId: `unsplash-${slugify(String(item.id || title))}`,
+        provider: this.name,
+        title,
+        thumbnailUrl: typeof item.urls?.small === "string" ? item.urls.small : imageUrl,
+        imageUrl,
+        sourcePageUrl: typeof item.links?.html === "string" ? item.links.html : undefined,
+        width: typeof item.width === "number" ? item.width : undefined,
+        height: typeof item.height === "number" ? item.height : undefined,
+        alt: item.alt_description || title,
+        license: "Unsplash License",
+        attribution: author ? `Photo by ${author} on Unsplash` : "Unsplash",
+        purpose: input.purpose,
+      }]
+    }).slice(0, limit)
+  },
+}
+
+export const wikimediaProvider: ImageSearchProvider = {
+  name: "wikimedia-commons",
+  async search(input) {
+    const limit = normalizeLimit(input.limit)
+    const page = normalizePage(input.page)
+    const url = new URL("https://commons.wikimedia.org/w/api.php")
+    url.searchParams.set("action", "query")
+    url.searchParams.set("format", "json")
+    url.searchParams.set("origin", "*")
+    url.searchParams.set("generator", "search")
+    url.searchParams.set("gsrnamespace", "6")
+    url.searchParams.set("gsrlimit", String(limit))
+    url.searchParams.set("gsroffset", String((page - 1) * limit))
+    url.searchParams.set("gsrsearch", input.query)
+    url.searchParams.set("prop", "imageinfo|info")
+    url.searchParams.set("iiprop", "url|thumburl|mime|size|extmetadata")
+    url.searchParams.set("iiurlwidth", "320")
+    url.searchParams.set("inprop", "url")
+
+    const response = await fetch(url, {
+      headers: { "user-agent": "Revela/0.15 asset search" },
+      signal: input.signal,
+    })
+    if (!response.ok) throw new Error(`Wikimedia search failed: ${response.status}`)
+    const body = await response.json() as any
+    const pages = Object.values(body?.query?.pages ?? {}) as any[]
+    return pages.flatMap((page) => {
+      const info = page?.imageinfo?.[0]
+      const mime = typeof info?.mime === "string" ? info.mime : ""
+      if (!mime.startsWith("image/")) return []
+      const imageUrl = typeof info?.url === "string" ? info.url : ""
+      if (!imageUrl) return []
+      const thumbnailUrl = typeof info?.thumburl === "string" ? info.thumburl : imageUrl
+      const metadata = info?.extmetadata ?? {}
+      const title = String(page.title || "Wikimedia image").replace(/^File:/, "")
+      return [{
+        candidateId: `wikimedia-${slugify(title).slice(0, 80)}`,
+        provider: this.name,
+        title,
+        thumbnailUrl,
+        imageUrl,
+        sourcePageUrl: typeof page.fullurl === "string" ? page.fullurl : undefined,
+        width: typeof info.width === "number" ? info.width : undefined,
+        height: typeof info.height === "number" ? info.height : undefined,
+        alt: title,
+        license: textFromMetadata(metadata.LicenseShortName) || textFromMetadata(metadata.UsageTerms),
+        attribution: textFromMetadata(metadata.Artist) || textFromMetadata(metadata.Credit),
+        purpose: input.purpose,
+      }]
+    }).slice(0, limit)
+  },
+}
+
+export async function searchRemoteImages(input: ImageSearchInput): Promise<ImageCandidate[]> {
+  const query = input.query.trim()
+  if (!query) return []
+  const limit = normalizeLimit(input.limit)
+  const page = normalizePage(input.page)
+  const mediaQuery = queryForPurpose(query, input.purpose)
+  const wikimediaQuery = wikimediaQueryForPurpose(query, input.purpose)
+  const searches: Array<Promise<ImageCandidate[]>> = input.purpose === "logo"
+    ? [
+      runProvider(clearbitLogoProvider, { ...input, query, limit, page }),
+      runProvider(simpleIconsProvider, { ...input, query, limit, page }),
+      runProvider(websiteMetadataProvider, { ...input, query, limit, page }),
+    ]
+    : input.purpose === "screenshot"
+      ? [
+        runProvider(websiteMetadataProvider, { ...input, query, limit, page }),
+        runProvider(wikimediaProvider, { ...input, query: wikimediaQuery, limit, page }),
+      ]
+      : [
+        runProvider(websiteMetadataProvider, { ...input, query, limit, page }),
+        runProvider(unsplashProvider, { ...input, query: mediaQuery, limit, page }),
+        runProvider(wikimediaProvider, { ...input, query: wikimediaQuery, limit, page }),
+      ]
+  const batches = await Promise.allSettled(searches)
+  const candidates = batches.flatMap((result) => result.status === "fulfilled" ? result.value : [])
+  const seen = new Set<string>()
+  return candidates.filter((candidate) => {
+    const key = candidate.imageUrl || candidate.thumbnailUrl || candidate.candidateId
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  }).slice(0, limit)
+}
+
+async function runProvider(provider: ImageSearchProvider, input: ImageSearchInput): Promise<ImageCandidate[]> {
+  const timeoutMs = input.providerTimeoutMs ?? PROVIDER_TIMEOUT_MS[provider.name]
+  if (!timeoutMs) return provider.search(input).catch(() => [])
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  const signal = input.signal ? anySignal([input.signal, controller.signal]) : controller.signal
+  try {
+    return await provider.search({ ...input, signal })
+  } catch {
+    return []
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function anySignal(signals: AbortSignal[]): AbortSignal {
+  const controller = new AbortController()
+  const abort = () => controller.abort()
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort()
+      break
+    }
+    signal.addEventListener("abort", abort, { once: true })
+  }
+  return controller.signal
+}

package/lib/media/types.ts

@@ -15,6 +15,12 @@ export interface MediaSaveInput {
   alt?: string
   notes?: string
   failureReason?: string
+  provider?: string
+  sourcePageUrl?: string
+  license?: string
+  attribution?: string
+  width?: number
+  height?: number
 }
 
 export interface MediaAssetRecord {
@@ -30,6 +36,12 @@ export interface MediaAssetRecord {
   alt?: string
   notes?: string
   failureReason?: string
+  provider?: string
+  sourcePageUrl?: string
+  license?: string
+  attribution?: string
+  width?: number
+  height?: number
   savedAt: string
 }
 

package/lib/qa/checks.ts

@@ -23,13 +23,14 @@ import { CANVAS_W, CANVAS_H } from "./measure"
 export type IssueSeverity = "error" | "warning" | "info"
 
 export interface LayoutIssue {
-  type: "canvas" | "scrollbar" | "overflow" | "text_overflow" | "density" | "balance" | "symmetry" | "rhythm" | "compliance"
+  type: "canvas" | "scrollbar" | "overflow" | "text_overflow" | "density" | "balance" | "symmetry" | "rhythm" | "compliance" | "asset"
   /** Sub-category within the dimension */
   sub?: "size_mismatch" | "page_scroll" | "text_clipped" | "thin_content"
       | "centroid_offset" | "bottom_gap" | "sparse"
       | "height_mismatch" | "density_mismatch"
       | "gap_variance"
       | "unknown_class" | "novel_css_rule"
+      | "remote_url" | "refine_proxy" | "missing_file"
   severity: IssueSeverity
   /** Human-readable description for the LLM to act on */
   detail: string