@cyber-dash-tech/revela 0.15.1 → 0.15.3

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/prompt-builder.ts

@@ -7,8 +7,10 @@
  *
  * Deck-render mode:
  *   Layer 1: SKILL.md           — legacy deck render protocol (HTML rules, quality)
- *   Layer 2: DOMAIN.md          — domain structure/terminology
- *   Layer 3: DESIGN.md          — visual style (colors, fonts, animations, layout)
+ *   Layer 2: DESIGN.md          — visual style (colors, fonts, animations, layout)
+ *
+ * Domain guidance is intentionally narrative-only. Deck-render mode must render
+ * the approved canonical narrative instead of re-interpreting domain semantics.
  *
  * When the active DESIGN.md has @section markers, only the global section,
  * layouts section, and a generated component index are injected into the
@@ -87,19 +89,23 @@ export function buildPrompt(optionsOrDesignName?: BuildPromptOptions | string, l
     ? "<!--   - preview.html — canonical visual reference (read this before generating slides) -->"
     : "<!--   - (no preview.html for this design) -->"
 
-  // Layer 2 — DOMAIN.md skill text (may be empty for "general")
+  // Layer 2 — DOMAIN.md skill text (narrative mode only). Deck-render mode
+  // renders the approved canonical narrative and must not re-interpret domain
+  // semantics from the full domain prompt.
   let domainSkill = ""
-  try {
-    domainSkill = getDomainSkillMd(domain)
-  } catch (e) {
-    // Domain not installed or empty — proceed without domain layer
-    promptLog.warn("domain skill not found — building without domain layer", {
-      domain,
-      error: e instanceof Error ? e.message : String(e),
-    })
+  if (mode === "narrative") {
+    try {
+      domainSkill = getDomainSkillMd(domain)
+    } catch (e) {
+      // Domain not installed or empty — proceed without domain layer
+      promptLog.warn("domain skill not found — building without domain layer", {
+        domain,
+        error: e instanceof Error ? e.message : String(e),
+      })
+    }
   }
 
-  // Layer 3 — DESIGN.md: deck-render only. Narrative mode must not inject
+  // DESIGN.md: deck-render only. Narrative mode must not inject
   // visual CSS, layout catalogs, component indexes, or HTML skeleton rules.
   const designSkill = mode === "deck-render" ? buildDesignLayer(design) : ""
 
@@ -107,7 +113,7 @@ export function buildPrompt(optionsOrDesignName?: BuildPromptOptions | string, l
   const header = mode === "deck-render"
     ? `<!-- Revela prompt mode: deck-render -->\n` +
       `<!-- Active design: ${design} -->\n` +
-      `<!-- Active domain: ${domain} -->\n` +
+      `<!-- Active domain: ${domain} (not injected in deck-render mode) -->\n` +
       `<!-- Design files: ${designDir}/ -->\n` +
       `<!--   - DESIGN.md — metadata + style instructions (injected below) -->\n` +
       `${previewLine}\n\n`
@@ -115,7 +121,7 @@ export function buildPrompt(optionsOrDesignName?: BuildPromptOptions | string, l
       `<!-- Active domain: ${domain} -->\n` +
       `<!-- Design layer intentionally omitted in narrative mode. Use deck-render mode before writing deck artifacts. -->\n\n`
 
-  // Concatenation: Header → Skill → Domain → Design (deck-render only)
+  // Concatenation: Header → Skill → Domain (narrative only) → Design (deck-render only)
   const parts = [header, coreSkill]
   if (domainSkill) {
     parts.push(`\n\n---\n\n${domainSkill}`)

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

package/lib/qa/index.ts

@@ -8,8 +8,10 @@
 
 import { measureSlides } from "./measure"
 import { runChecks, formatReport } from "./checks"
-import type { QAReport } from "./checks"
+import type { LayoutIssue, QAReport } from "./checks"
 import type { DesignClassVocabulary } from "../design/designs"
+import { existsSync, readFileSync } from "fs"
+import { dirname, resolve } from "path"
 
 export type { QAReport, SlideReport, LayoutIssue, IssueSeverity } from "./checks"
 export type { RunChecksOptions } from "./checks"
@@ -34,7 +36,76 @@ export async function runQA(
   _vocabulary?: DesignClassVocabulary,
 ): Promise<QAReport> {
   const result = await measureSlides(htmlFilePath)
-  return runChecks(htmlFilePath, result.slides)
+  const report = runChecks(htmlFilePath, result.slides)
+  return withAssetChecks(report, htmlFilePath)
+}
+
+function withAssetChecks(report: QAReport, htmlFilePath: string): QAReport {
+  const issues = scanAssetRefs(htmlFilePath)
+  if (!issues.length) return report
+  const slides = [...report.slides]
+  const first = slides[0] ?? { index: 1, title: "Deck", issues: [] }
+  slides[0] = { ...first, issues: [...first.issues, ...issues] }
+  const errorCount = report.errorCount + issues.filter((issue) => issue.severity === "error").length
+  const warningCount = report.warningCount + issues.filter((issue) => issue.severity === "warning").length
+  return {
+    ...report,
+    slides,
+    totalIssues: report.totalIssues + issues.length,
+    errorCount,
+    warningCount,
+    summary: errorCount === 0
+      ? `QA passed with ${warningCount} warning${warningCount === 1 ? "" : "s"}.`
+      : `QA failed with ${errorCount} error${errorCount === 1 ? "" : "s"} and ${warningCount} warning${warningCount === 1 ? "" : "s"}.`,
+  }
+}
+
+function scanAssetRefs(htmlFilePath: string): LayoutIssue[] {
+  let html = ""
+  try {
+    html = readFileSync(htmlFilePath, "utf-8")
+  } catch {
+    return []
+  }
+  const refs = new Set<string>()
+  const attrPattern = /\b(?:src|href|poster)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi
+  let match: RegExpExecArray | null
+  while ((match = attrPattern.exec(html))) refs.add(match[1] ?? match[2] ?? match[3] ?? "")
+  const cssPattern = /url\(\s*(?:"([^"]*)"|'([^']*)'|([^\s)]+))\s*\)/gi
+  while ((match = cssPattern.exec(html))) refs.add(match[1] ?? match[2] ?? match[3] ?? "")
+
+  const issues: LayoutIssue[] = []
+  for (const raw of refs) {
+    const ref = raw.trim()
+    if (!ref || ref.startsWith("data:") || ref.startsWith("#") || ref.startsWith("mailto:") || ref.startsWith("tel:")) continue
+    if (/^https?:\/\//i.test(ref) || ref.startsWith("//")) {
+      issues.push({ type: "asset", sub: "remote_url", severity: "error", detail: `Deck HTML references remote asset URL \`${ref}\`. Save network images to workspace assets and reference the local file instead.` })
+      continue
+    }
+    if (ref.includes("/__revela_asset")) {
+      issues.push({ type: "asset", sub: "refine_proxy", severity: "error", detail: `Deck HTML references Refine proxy URL \`${ref}\`. Use the saved workspace asset path instead.` })
+      continue
+    }
+    if (!looksLikeImageRef(ref)) continue
+    const pathOnly = safeDecode(ref.split(/[?#]/)[0])
+    const resolved = resolve(dirname(htmlFilePath), pathOnly)
+    if (!existsSync(resolved)) {
+      issues.push({ type: "asset", sub: "missing_file", severity: "error", detail: `Deck HTML references missing image asset \`${ref}\`. Use a path relative to the deck HTML file or save the asset into workspace assets first.` })
+    }
+  }
+  return issues
+}
+
+function looksLikeImageRef(ref: string): boolean {
+  return /\.(?:png|jpe?g|webp|gif|svg)(?:[?#].*)?$/i.test(ref)
+}
+
+function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
 }
 
 /**