@syengup/friday-channel-next 0.1.26 → 0.1.28

package/src/http/handlers/plugin-upgrade.ts

@@ -0,0 +1,112 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { extractBearerToken } from "../middleware/auth.js";
+import { createFridayNextLogger } from "../../logging.js";
+import { PLUGIN_PACKAGE_NAME, PLUGIN_VERSION } from "../../version.js";
+import { getInstallSource } from "../../plugin-install-info.js";
+import { getUpgradeRuntime } from "../../upgrade-runtime.js";
+
+const UPGRADE_TIMEOUT_MS = 120_000;
+/** Give the 202 response time to flush before the restart kills the process. */
+const RESTART_DELAY_MS = 500;
+
+/**
+ * POST /friday-next/plugin/upgrade
+ *
+ * Runs `openclaw plugins install @syengup/friday-channel-next@latest --force`
+ * (registry-aware, updates the install record), responds 202, then triggers a
+ * safe gateway restart so the new version loads. Only npm-installed plugins are
+ * eligible — dev (load.paths / source==="path") installs return 409 to protect
+ * the dev environment from duplicate npm installs.
+ */
+export async function handlePluginUpgrade(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (req.method !== "POST") {
+    res.statusCode = 405;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Method Not Allowed" }));
+    return true;
+  }
+  if (!extractBearerToken(req)) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Unauthorized: bearer token mismatch" }));
+    return true;
+  }
+
+  const log = createFridayNextLogger("upgrade");
+  const installSource = getInstallSource();
+  if (installSource !== "npm") {
+    res.statusCode = 409;
+    res.setHeader("Content-Type", "application/json");
+    res.end(
+      JSON.stringify({
+        error: "auto-upgrade not available",
+        detail: `install source is "${installSource}"; only npm installs can be auto-upgraded`,
+        installSource,
+      }),
+    );
+    return true;
+  }
+
+  const rt = getUpgradeRuntime();
+  if (!rt) {
+    res.statusCode = 500;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "upgrade runtime unavailable" }));
+    return true;
+  }
+
+  const spec = `${PLUGIN_PACKAGE_NAME}@latest`;
+  log.info(`Starting plugin upgrade: ${spec} (from ${PLUGIN_VERSION})`);
+
+  let result;
+  try {
+    result = await rt.runCommandWithTimeout(
+      ["openclaw", "plugins", "install", spec, "--force"],
+      UPGRADE_TIMEOUT_MS,
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error(`plugin upgrade command failed to spawn: ${msg}`);
+    res.statusCode = 500;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "upgrade command failed", detail: msg }));
+    return true;
+  }
+
+  if (result.code !== 0) {
+    const stderrTail = (result.stderr ?? "").slice(-2000);
+    log.error(`plugin upgrade exited code=${result.code}: ${stderrTail}`);
+    res.statusCode = 500;
+    res.setHeader("Content-Type", "application/json");
+    res.end(
+      JSON.stringify({
+        error: "upgrade command exited non-zero",
+        code: result.code,
+        detail: stderrTail,
+      }),
+    );
+    return true;
+  }
+
+  log.info("Plugin upgrade install succeeded; scheduling gateway restart");
+
+  // Respond first so the app receives confirmation before the restart drops the
+  // connection, then trigger the safe restart after a short flush delay.
+  res.statusCode = 202;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ status: "upgrading", from: PLUGIN_VERSION }));
+
+  setTimeout(() => {
+    void rt
+      .mutateConfigFile({
+        afterWrite: { mode: "restart", reason: "friday-next 插件自动升级后重启" },
+        mutate: () => {},
+      })
+      .catch((err: unknown) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`gateway restart trigger failed: ${msg}`);
+      });
+  }, RESTART_DELAY_MS).unref?.();
+
+  return true;
+}

package/src/http/handlers/sse.ts

@@ -4,6 +4,7 @@ import { getHostOpenClawConfigSnapshot } from "../../host-config.js";
 import { getFridayNextRuntime } from "../../runtime.js";
 import { sseEmitter } from "../../sse/emitter.js";
 import { extractBearerToken } from "../middleware/auth.js";
+import { PLUGIN_VERSION } from "../../version.js";
 
 function parseLastEventId(req: IncomingMessage, url: URL): number {
   const query = Number.parseInt(url.searchParams.get("lastEventId") ?? "", 10);
@@ -56,6 +57,7 @@ export async function handleSseStream(req: IncomingMessage, res: ServerResponse)
         deviceId: normalized,
         serverTime: Date.now(),
         lastSeq,
+        pluginVersion: PLUGIN_VERSION,
       },
     },
     deviceId,

package/src/http/handlers/status.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { getActiveRunIds } from "../../agent/active-runs.js";
 import { sseEmitter } from "../../sse/emitter.js";
 import { extractBearerToken } from "../middleware/auth.js";
+import { PLUGIN_VERSION } from "../../version.js";
 
 export async function handleStatus(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
   if (req.method !== "GET") {
@@ -24,6 +25,7 @@ export async function handleStatus(req: IncomingMessage, res: ServerResponse): P
       ok: true,
       channel: "friday-next",
       version: "v2",
+      pluginVersion: PLUGIN_VERSION,
       connections: sseEmitter.getConnectionCount(),
       activeRuns,
       activeRunCount: activeRuns.length,

package/src/http/server.ts

@@ -20,7 +20,10 @@ import { handleHistorySessions } from "./handlers/history-sessions.js";
 import { handleHistoryMessages } from "./handlers/history-messages.js";
 import { handleHistorySetTitle } from "./handlers/history-set-title.js";
 import { handleStatus } from "./handlers/status.js";
+import { handleLinkPreview } from "./handlers/link-preview.js";
 import { handleHealth } from "./handlers/health.js";
+import { handlePluginInfo } from "./handlers/plugin-info.js";
+import { handlePluginUpgrade } from "./handlers/plugin-upgrade.js";
 import { applyCorsHeaders } from "./middleware/cors.js";
 import { resolveFridayNextConfig } from "../config.js";
 import { getHostOpenClawConfigSnapshot } from "../host-config.js";
@@ -104,11 +107,26 @@ async function handleFridayNextRoute(
     return await handleHistorySetTitle(req, res);
   }
 
+  // Route: GET /friday-next/link-preview?url=... (Open Graph metadata for preview cards)
+  if (req.method === "GET" && pathname === "/friday-next/link-preview") {
+    return await handleLinkPreview(req, res);
+  }
+
   // Route: GET /friday-next/health?deviceId=...&nodeDeviceId=...&selfHeal=true
   if (req.method === "GET" && pathname === "/friday-next/health") {
     return await handleHealth(req, res);
   }
 
+  // Route: GET /friday-next/plugin/info (current/latest version + upgradability)
+  if (req.method === "GET" && pathname === "/friday-next/plugin/info") {
+    return await handlePluginInfo(req, res);
+  }
+
+  // Route: POST /friday-next/plugin/upgrade (npm install @latest + safe gateway restart)
+  if (req.method === "POST" && pathname === "/friday-next/plugin/upgrade") {
+    return await handlePluginUpgrade(req, res);
+  }
+
   // Not found
   return false;
 }

package/src/link-preview/og-parse.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import { decodeHtmlEntities, parseOpenGraph } from "./og-parse.js";
+
+const BASE = "https://example.com/article/42";
+
+describe("decodeHtmlEntities", () => {
+  it("decodes named, decimal, and hex entities", () => {
+    expect(decodeHtmlEntities("Tom & Jerry — "fun"")).toBe('Tom & Jerry — "fun"');
+    expect(decodeHtmlEntities("中文")).toBe("中文");
+    expect(decodeHtmlEntities("'quoted'")).toBe("'quoted'");
+  });
+
+  it("leaves unknown entities untouched", () => {
+    expect(decodeHtmlEntities("&unknownentity; stays")).toBe("&unknownentity; stays");
+  });
+});
+
+describe("parseOpenGraph", () => {
+  it("extracts the standard og tags", () => {
+    const html = `<html><head>
+      <meta property="og:title" content="Hello World" />
+      <meta property="og:description" content="A page about things" />
+      <meta property="og:image" content="https://cdn.example.com/cover.jpg" />
+      <meta property="og:site_name" content="Example" />
+    </head><body></body></html>`;
+    expect(parseOpenGraph(html, BASE)).toEqual({
+      title: "Hello World",
+      description: "A page about things",
+      imageUrl: "https://cdn.example.com/cover.jpg",
+      siteName: "Example",
+      iconUrl: null,
+    });
+  });
+
+  it("handles name= variant, swapped attribute order, and single quotes", () => {
+    const html = `
+      <meta content="Swapped" property="og:title">
+      <meta name='og:description' content='Single quoted'>
+    `;
+    const result = parseOpenGraph(html, BASE);
+    expect(result.title).toBe("Swapped");
+    expect(result.description).toBe("Single quoted");
+  });
+
+  it("first occurrence wins for duplicate og tags", () => {
+    const html = `
+      <meta property="og:title" content="First">
+      <meta property="og:title" content="Second">
+    `;
+    expect(parseOpenGraph(html, BASE).title).toBe("First");
+  });
+
+  it("falls back to <title> and meta description", () => {
+    const html = `<html><head>
+      <title>  Fallback   Title </title>
+      <meta name="description" content="Fallback description">
+    </head></html>`;
+    const result = parseOpenGraph(html, BASE);
+    expect(result.title).toBe("Fallback Title");
+    expect(result.description).toBe("Fallback description");
+  });
+
+  it("decodes entities and collapses whitespace in text fields", () => {
+    const html = `<meta property="og:title" content="Q&amp;A:&#x20;What&#39;s
+      new">`;
+    expect(parseOpenGraph(html, BASE).title).toBe("Q&A: What's new");
+  });
+
+  it("resolves a relative og:image against the page URL", () => {
+    const html = `<meta property="og:image" content="/img/cover.png">`;
+    expect(parseOpenGraph(html, BASE).imageUrl).toBe("https://example.com/img/cover.png");
+  });
+
+  it("drops non-http og:image values", () => {
+    const html = `<meta property="og:image" content="data:image/png;base64,AAAA">`;
+    expect(parseOpenGraph(html, BASE).imageUrl).toBeNull();
+  });
+
+  it("returns nulls for a page with no usable metadata", () => {
+    expect(parseOpenGraph("<html><body>plain</body></html>", BASE)).toEqual({
+      title: null,
+      description: null,
+      imageUrl: null,
+      siteName: null,
+      iconUrl: null,
+    });
+  });
+
+  it("extracts and resolves a favicon, preferring apple-touch-icon, skipping mask-icon", () => {
+    const html = `<head>
+      <link rel="mask-icon" href="/safari.svg" color="#000">
+      <link rel="icon" type="image/png" href="/favicon-32.png">
+      <link rel="apple-touch-icon" href="https://cdn.example.com/touch.png">
+    </head>`;
+    expect(parseOpenGraph(html, BASE).iconUrl).toBe("https://cdn.example.com/touch.png");
+  });
+
+  it("falls back to a regular icon link and resolves relative hrefs", () => {
+    const html = `<link rel="shortcut icon" href="/static/fav.ico">`;
+    expect(parseOpenGraph(html, BASE).iconUrl).toBe("https://example.com/static/fav.ico");
+  });
+
+  it("returns null icon when only a mask-icon is present", () => {
+    expect(parseOpenGraph(`<link rel="mask-icon" href="/m.svg">`, BASE).iconUrl).toBeNull();
+  });
+
+  it("falls back to twitter card tags when og is absent", () => {
+    const html = `
+      <meta name="twitter:title" content="TW Title">
+      <meta name="twitter:description" content="TW Desc">
+      <meta name="twitter:image" content="https://cdn.example.com/tw.jpg">
+    `;
+    const r = parseOpenGraph(html, BASE);
+    expect(r.title).toBe("TW Title");
+    expect(r.description).toBe("TW Desc");
+    expect(r.imageUrl).toBe("https://cdn.example.com/tw.jpg");
+  });
+
+  it("falls back to JSON-LD (headline/description/image, incl. @graph and ImageObject)", () => {
+    const html = `<script type="application/ld+json">
+      {"@context":"https://schema.org","@graph":[
+        {"@type":"NewsArticle","headline":"LD Headline","description":"LD Desc",
+         "image":{"@type":"ImageObject","url":"https://cdn.example.com/ld.jpg"}}
+      ]}
+    </script>`;
+    const r = parseOpenGraph(html, BASE);
+    expect(r.title).toBe("LD Headline");
+    expect(r.description).toBe("LD Desc");
+    expect(r.imageUrl).toBe("https://cdn.example.com/ld.jpg");
+  });
+
+  it("prefers a body article-title over a generic <title> (QQ-style SPA shell)", () => {
+    const html = `<head><title>搜索资讯页</title></head>
+      <body><div class="article-wrapper"><div class="article-title">钉钉"两篇大作文"事件——离职副总裁万字长文</div></div></body>`;
+    expect(parseOpenGraph(html, BASE).title).toBe('钉钉"两篇大作文"事件——离职副总裁万字长文');
+  });
+
+  it("prefers an <h1> over a generic <title>", () => {
+    const html = `<title>Home</title><h1>The Real Headline</h1>`;
+    expect(parseOpenGraph(html, BASE).title).toBe("The Real Headline");
+  });
+
+  it("extracts a cover image from inline JSON (extensionless, escaped slashes)", () => {
+    const html = `<title>搜索资讯页</title>
+      <script>window.__INFO__={"imgUrl":"http:\\/\\/qqpublic.qpic.cn\\/qq_public_cover\\/0\\/0-2342_op"}</script>`;
+    expect(parseOpenGraph(html, BASE).imageUrl).toBe("http://qqpublic.qpic.cn/qq_public_cover/0/0-2342_op");
+  });
+
+  it("standard og tags still win over body/json fallbacks", () => {
+    const html = `<meta property="og:title" content="OG Wins">
+      <h1>Body H1</h1>
+      <div class="article-title">Body Title</div>`;
+    expect(parseOpenGraph(html, BASE).title).toBe("OG Wins");
+  });
+
+  it("does not throw on malformed or truncated HTML", () => {
+    expect(() => parseOpenGraph(`<meta property="og:title" content="Trunc`, BASE)).not.toThrow();
+    expect(() => parseOpenGraph("<<<>>><meta<meta>", BASE)).not.toThrow();
+  });
+
+  it("ignores empty content values", () => {
+    const html = `<meta property="og:title" content="">
+      <title>Real Title</title>`;
+    // og:title 占位为空串 → cleanText 归 null,但 og map 已记录空串;回退逻辑应仍给出可用 title
+    const result = parseOpenGraph(html, BASE);
+    expect(result.title).toBe("Real Title");
+  });
+});

package/src/link-preview/og-parse.ts

@@ -0,0 +1,249 @@
+/**
+ * Open Graph metadata extraction via regex — no HTML parser dependency.
+ *
+ * Good enough for the link-preview card use case: og:* meta tags are flat, attribute-ordered
+ * variants are handled generically, and pages where this fails simply degrade to "no card".
+ */
+
+const MAX_PARSE_BYTES = 512 * 1024;
+
+export interface OpenGraphResult {
+  title: string | null;
+  description: string | null;
+  imageUrl: string | null;
+  siteName: string | null;
+  /** Favicon URL parsed from `<link rel="...icon...">`, resolved absolute. */
+  iconUrl: string | null;
+}
+
+const META_TAG_RE = /<meta\b[^>]*>/gi;
+const TITLE_TAG_RE = /<title[^>]*>([\s\S]*?)<\/title>/i;
+const LINK_TAG_RE = /<link\b[^>]*>/gi;
+
+/** Extract one attribute value from a tag, tolerating single/double/no quotes and any order. */
+function attributeValue(tag: string, name: string): string | null {
+  const re = new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'>]+))`, "i");
+  const m = tag.match(re);
+  if (!m) return null;
+  return m[1] ?? m[2] ?? m[3] ?? "";
+}
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  ndash: "–",
+  mdash: "—",
+  hellip: "…",
+  middot: "·",
+  copy: "©",
+  reg: "®",
+  trade: "™",
+  lsquo: "‘",
+  rsquo: "’",
+  ldquo: "“",
+  rdquo: "”",
+  laquo: "«",
+  raquo: "»",
+};
+
+export function decodeHtmlEntities(s: string): string {
+  return s.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (whole, body: string) => {
+    if (body.startsWith("#x") || body.startsWith("#X")) {
+      const code = Number.parseInt(body.slice(2), 16);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+    if (body.startsWith("#")) {
+      const code = Number.parseInt(body.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+    return NAMED_ENTITIES[body.toLowerCase()] ?? whole;
+  });
+}
+
+function cleanText(raw: string | null | undefined): string | null {
+  if (raw == null) return null;
+  const text = decodeHtmlEntities(raw).replace(/\s+/g, " ").trim();
+  return text || null;
+}
+
+/** Resolve og:image (possibly relative) against the final page URL; only http(s) survives. */
+function resolveImageUrl(raw: string | null | undefined, baseUrl: string): string | null {
+  if (!raw) return null;
+  try {
+    const url = new URL(raw.trim(), baseUrl);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+export function parseOpenGraph(html: string, baseUrl: string): OpenGraphResult {
+  const slice = html.length > MAX_PARSE_BYTES ? html.slice(0, MAX_PARSE_BYTES) : html;
+
+  // First occurrence wins per key (matches browser/crawler behavior).
+  const og: Record<string, string> = {};
+  const tw: Record<string, string> = {};
+  let metaDescription: string | null = null;
+  for (const match of slice.matchAll(META_TAG_RE)) {
+    const tag = match[0];
+    const key = (attributeValue(tag, "property") ?? attributeValue(tag, "name"))?.trim().toLowerCase();
+    if (!key) continue;
+    const content = attributeValue(tag, "content");
+    if (content == null || !content.trim()) continue;
+    if (key.startsWith("og:")) {
+      const ogKey = key.slice(3);
+      if (!(ogKey in og)) og[ogKey] = content;
+    } else if (key.startsWith("twitter:")) {
+      const twKey = key.slice(8);
+      if (!(twKey in tw)) tw[twKey] = content;
+    } else if (key === "description" && metaDescription == null) {
+      metaDescription = content;
+    }
+  }
+
+  const ld = parseJsonLd(slice);
+  const pageTitle = slice.match(TITLE_TAG_RE)?.[1] ?? null;
+
+  // Title chain: standard tags first, then server-rendered body title (h1 / article-title class)
+  // BEFORE the generic <title> — many SPA/news shells put a useless <title> ("搜索资讯页") in the
+  // head while the real headline lives in the body.
+  const title =
+    cleanText(og["title"]) ??
+    cleanText(tw["title"]) ??
+    cleanText(ld.title) ??
+    cleanText(parseBodyTitle(slice)) ??
+    cleanText(pageTitle);
+
+  const description =
+    cleanText(og["description"]) ??
+    cleanText(tw["description"]) ??
+    cleanText(ld.description) ??
+    cleanText(metaDescription);
+
+  const imageUrl =
+    resolveImageUrl(og["image"] ?? null, baseUrl) ??
+    resolveImageUrl(tw["image"] ?? null, baseUrl) ??
+    resolveImageUrl(ld.image, baseUrl) ??
+    resolveImageUrl(parseBodyCoverImage(slice), baseUrl);
+
+  return {
+    title,
+    description,
+    imageUrl,
+    siteName: cleanText(og["site_name"] ?? tw["site"] ?? null),
+    iconUrl: parseFaviconUrl(slice, baseUrl),
+  };
+}
+
+const JSON_LD_RE = /<script[^>]*type\s*=\s*["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+
+/** Extract title/description/image from JSON-LD blocks (schema.org Article/NewsArticle/etc.). */
+function parseJsonLd(html: string): { title: string | null; description: string | null; image: string | null } {
+  for (const match of html.matchAll(JSON_LD_RE)) {
+    let data: unknown;
+    try {
+      data = JSON.parse(match[1].trim());
+    } catch {
+      continue;
+    }
+    // JSON-LD may be a single object, an array, or a @graph container.
+    const nodes: unknown[] = Array.isArray(data)
+      ? data
+      : isRecord(data) && Array.isArray(data["@graph"])
+        ? (data["@graph"] as unknown[])
+        : [data];
+    for (const node of nodes) {
+      if (!isRecord(node)) continue;
+      const title = asString(node.headline) ?? asString(node.name);
+      const description = asString(node.description);
+      const image = firstImage(node.image) ?? asString(node.thumbnailUrl);
+      if (title || description || image) {
+        return { title: title ?? null, description: description ?? null, image: image ?? null };
+      }
+    }
+  }
+  return { title: null, description: null, image: null };
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function asString(v: unknown): string | null {
+  return typeof v === "string" && v.trim() ? v : null;
+}
+
+/** JSON-LD `image` is a string, an array, or an ImageObject `{ url }`. */
+function firstImage(v: unknown): string | null {
+  if (typeof v === "string") return v;
+  if (Array.isArray(v)) {
+    for (const item of v) {
+      const found = firstImage(item);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (isRecord(v)) return asString(v.url);
+  return null;
+}
+
+// Common server-rendered article-title class names (whitelist keeps false positives down vs. any
+// class containing "title", e.g. a sidebar "related-titles" block).
+const BODY_TITLE_CLASS_RE =
+  /class\s*=\s*["'][^"']*\b(?:article-title|post-title|entry-title|news-title|content-title|headline|title-text)\b[^"']*["'][^>]*>\s*([^<]{4,200}?)\s*</i;
+const H1_RE = /<h1\b[^>]*>\s*([\s\S]{4,200}?)\s*<\/h1>/i;
+
+/** Server-rendered headline fallback: first <h1>, else an element with a known article-title class. */
+function parseBodyTitle(html: string): string | null {
+  const h1 = html.match(H1_RE)?.[1];
+  if (h1) {
+    const text = stripTags(h1).trim();
+    if (text.length >= 4) return text;
+  }
+  return html.match(BODY_TITLE_CLASS_RE)?.[1] ?? null;
+}
+
+// Cover image embedded in inline JSON (e.g. QQ's `"imgUrl":"http:\/\/...cover..."`). The URL may be
+// extensionless; the re-host step's magic-byte sniff is the safety net against non-image matches.
+const JSON_COVER_RE =
+  /"(?:imgUrl|imageUrl|coverUrl|coverImage|cover|ogImage|thumbnail|picUrl)"\s*:\s*"(https?:(?:\\?\/){2}[^"]+?)"/i;
+
+/** Cover image from inline JSON when no og/twitter/json-ld image is present. */
+function parseBodyCoverImage(html: string): string | null {
+  const raw = html.match(JSON_COVER_RE)?.[1];
+  if (!raw) return null;
+  return raw.replace(/\\\//g, "/"); // unescape JSON `\/`
+}
+
+function stripTags(s: string): string {
+  return s.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ");
+}
+
+/**
+ * Pick the best `<link rel="...icon...">` href. Prefers a high-res `apple-touch-icon`, then a
+ * regular `icon` / `shortcut icon`. Skips `mask-icon` (monochrome SVG). Returns absolute http(s).
+ */
+export function parseFaviconUrl(html: string, baseUrl: string): string | null {
+  let appleTouch: string | null = null;
+  let regular: string | null = null;
+  for (const match of html.matchAll(LINK_TAG_RE)) {
+    const tag = match[0];
+    const rel = attributeValue(tag, "rel")?.trim().toLowerCase();
+    if (!rel || !rel.includes("icon") || rel.includes("mask-icon")) continue;
+    const href = attributeValue(tag, "href");
+    if (!href) continue;
+    const resolved = resolveImageUrl(href, baseUrl);
+    if (!resolved) continue;
+    if (rel.includes("apple-touch-icon")) {
+      appleTouch ??= resolved;
+    } else {
+      regular ??= resolved;
+    }
+  }
+  return appleTouch ?? regular;
+}