@forsvn/metaprev 0.5.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@forsvn/metaprev",
+  "version": "0.5.0",
+  "description": "Preview, inspect, and repair Open Graph cards locally with actionable validation and copy-ready fixes.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Le Vinh Hung <levinhhungg@gmail.com>",
+  "homepage": "https://github.com/forsvn-labs/metaprev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forsvn-labs/metaprev.git"
+  },
+  "bugs": {
+    "url": "https://github.com/forsvn-labs/metaprev/issues"
+  },
+  "keywords": [
+    "opengraph",
+    "og-image",
+    "og-preview",
+    "social-preview",
+    "twitter-card",
+    "meta-tags",
+    "seo",
+    "cli"
+  ],
+  "bin": {
+    "metaprev": "bin/metaprev.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "dev": "bun bin/metaprev.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "image-size": "^2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/skills/metaprev/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: metaprev
+description: Preview, validate, and debug OpenGraph cards and social link previews locally via the metaprev CLI. Use whenever the user asks about how their site looks when shared on Facebook, X, LinkedIn, Discord, or Slack — including og:image, og:title, og:description, twitter:card, "broken share preview", "link preview not loading", "test my OG card", "OpenGraph validator", "social meta tags", or whenever they reference seeing issues from OpenGraph.xyz, metatags.io, Facebook Sharing Debugger, or similar third-party validators. Also use proactively when a Vercel/Next/Astro deploy is being checked for share-readiness, when og:image meta tags are added or modified, or when social-share thumbnails appear broken in chats. Prefer this over pointing the user at a third-party validator.
+---
+
+# metaprev — local OpenGraph preview
+
+`metaprev` is a CLI that fetches a URL, parses Open Graph and X metadata, validates the selected image and fallbacks, then opens a local preview-and-repair workspace with representative Facebook, X, LinkedIn, and Discord cards. Slack classic unfurls use the same inspected Open Graph and X metadata, but metaprev does not present Discord UI as a Slack screenshot. It works against any `localhost` dev server and public URLs with no validator service.
+
+- Repo: https://github.com/forsvn-labs/metaprev
+- Package: `@forsvn/metaprev`
+- Author intent: replace the workflow of "paste URL into OpenGraph.xyz / metatags.io / Facebook Debugger" with a local CLI you can run before shipping.
+
+## When this skill applies
+
+Use `metaprev` instead of pointing the user at a third-party debugger when the task involves:
+
+- "How does this link look when shared?" "Why is my preview broken?"
+- Adding or fixing `og:image`, `og:title`, `og:description`, `og:url`, `twitter:card`
+- Validating image dimensions, file size, absolute-URL-ness
+- Debugging Slack/Discord/iMessage embeds that don't render
+- The user pasted a screenshot from OpenGraph.xyz, metatags.io, Twitter Card Validator, or Facebook Sharing Debugger
+- A deploy is being readied and someone wants to check share-card health
+- A new OG image was generated and needs validation
+
+Don't reach for it when the task is: favicon work, PWA manifests, OG image *generation* (different problem — this skill validates an existing image), pure SEO meta (search-result `description`/`keywords`), or schema.org / JSON-LD.
+
+## How to invoke
+
+The default invocation is `npx` so no install is needed. Bun is required on `PATH` because the package ships TypeScript and runs it via Bun.
+
+```bash
+# Any URL — deployed or local dev (any framework, any port)
+npx @forsvn/metaprev https://example.com
+npx @forsvn/metaprev http://localhost:3000   # Next, Vite, Bun.serve, Rails…
+npx @forsvn/metaprev http://localhost:4321   # Astro
+npx @forsvn/metaprev http://localhost:5173   # Vite default
+# (no URL → prints help)
+
+# Subcommands — scoped text/JSON output, no browser
+npx @forsvn/metaprev issues https://example.com          # just the issue list
+npx @forsvn/metaprev facts  https://example.com          # just the parsed meta facts
+npx @forsvn/metaprev facts  https://example.com --json   # pipe into another tool
+
+# CI / scripting — JSON to stdout, no browser
+npx @forsvn/metaprev https://example.com --json
+
+# Don't auto-open the browser
+npx @forsvn/metaprev https://example.com --no-open
+
+# Write the preview HTML to a specific file
+npx @forsvn/metaprev https://example.com -o ./og-preview.html
+
+# Local self-signed TLS (auto-on for *.localhost / *.test / 127.0.0.1; otherwise pass explicitly)
+npx @forsvn/metaprev https://staging.internal --insecure
+```
+
+Exit codes: `0` clean, `1` at least one error-level issue, `2` fetch failure. Use exit code `1` to fail a CI check.
+
+## Reading the output
+
+Three issue levels:
+
+- **error** — share is visibly broken. No `og:image`, image returns 404, `og:image` is a relative URL like `/og.png` (most validators fetch the URL standalone and fail), or the URL returns a non-image response that can't be decoded (points at an HTML/error page).
+- **warn** — real compatibility or presentation risk. Examples: missing `og:title`, off-ratio or low-resolution image, image above LinkedIn's documented 5 MB limit, SVG image, or declared dimensions that differ from the decoded asset.
+- **info** — standards, accessibility, or resilience improvement. Examples: missing `og:image:alt`, `og:type`, dimensions, canonical URL, or `twitter:card`.
+
+Address errors first. Use each finding's impact and evidence to judge warnings. Info findings do not fail CI, but accessibility and standards notes can still be worth fixing.
+
+Every issue includes a stable code, impact, observed evidence, and a concrete fix. The HTML workspace also shows Open Graph versus X inputs, source fallbacks, cover-versus-fit crop evidence, and copy-ready metadata, repair brief, and guarded coding-agent prompt.
+
+## Common fixes (in order of leverage)
+
+1. **`og:image` must be an absolute URL.** Many template engines emit `/og-default.png`, but Open Graph defines the property as a URL. Fix: produce `https://yourdomain.com/og-default.png`.
+   - Astro: `new URL(image, Astro.site).toString()` (requires `site` in `astro.config`)
+   - Next.js: build with `process.env.NEXT_PUBLIC_SITE_URL` or `metadata.metadataBase`
+   - SvelteKit: `${$page.url.origin}${image}`
+   - Plain HTML: hardcode the full URL
+2. **Use a deliberate 1.91:1 asset.** The workspace target is 1200×630. LinkedIn documents 1200×627 for its sharing module. Use the crop inspection instead of assuming every platform will frame it identically.
+3. **Add accurate `og:image:width`, `og:image:height`, and `og:image:alt`.** The dimensions must match the decoded file. Alt describes what is in the image, not a slogan.
+4. **Choose the X treatment explicitly.** Use `summary_large_image` for a wide card or `summary` for the compact card.
+5. **Set `og:url` or a `<link rel="canonical">`** so platforms dedupe shares from URLs with `?utm_*` query strings.
+
+## Copy rule
+
+metaprev intentionally emits no generic title-length or description-length warnings. Preserve concise, truthful copy. Do not add keywords, claims, calls to action, or padding just to resemble an SEO score. Treat the metadata snippet as a safe starting point: adapt it to the framework and review every value. A local or private-network URL remains a comment because it is not a valid public repair value.
+
+## Workflow patterns
+
+### Pattern A — User just changed OG meta and wants to verify
+
+1. Run `npx @forsvn/metaprev <url>` (local or deployed).
+2. Read the terminal output: title, description, image URL, image dims, issue list.
+3. Surface errors first with the recommended fix.
+4. Surface warnings with their evidence and concrete fix.
+5. Skip info-level unless it fits the user's current pass.
+
+### Pattern B — User says the link preview is broken on a specific platform
+
+1. Run `metaprev` against the page they're sharing.
+2. Diagnose from evidence in this order: (a) `og:image` missing or not absolute? (b) image request fails? (c) decoded bytes and response type disagree? (d) image too large or framed poorly?
+3. If everything looks fine in `metaprev`, the platform may be serving cached metadata. Use an official refresh tool where one exists:
+   - Facebook: scrape again via the Sharing Debugger (https://developers.facebook.com/tools/debug/)
+   - LinkedIn: use the Post Inspector (https://www.linkedin.com/post-inspector/)
+   - X, Slack, and Discord cache behavior can change; do not promise a refresh time.
+
+### Pattern C — Pre-deploy CI check
+
+Add a smoke test to a pre-deploy script:
+
+```bash
+npx @forsvn/metaprev https://staging.example.com --json > /dev/null || exit 1
+```
+
+Exit code `1` fails the deploy when any error-level issue exists. The `--json` output is machine-readable for further checks (e.g., assert image content-type is `image/png`).
+
+### Pattern D — User pastes a screenshot from OpenGraph.xyz or similar
+
+Third-party validators may overlap with metaprev and may also add generic heuristics such as "missing CTA in image" or "title 50–60 chars." Run metaprev against the same URL to confirm the source evidence, then review each claim:
+
+- "Image is 2400×1260" → the ratio is already correct; do not resize only to hit an exact pixel count.
+- "Image is broken in preview" → inspect the resolved URL, HTTP result, response type, and decoded bytes before choosing a fix.
+- "Missing CTA in image" → push back. Editorial OG cards (clean typography, brand name, tagline) don't need "Visit example.com →" buttons. The buttons make the card look like an ad. The tagline IS the CTA.
+- "Title is short, description is short" → user's call. Recommend keeping if intentional.
+
+## Output reading reference
+
+Terminal:
+
+```
+metaprev — https://example.com/
+HTTP 200 · fetched 2026-05-10T16:45:13Z
+
+  title        Example Inc. (12 chars)
+  description  We build... (58 chars)
+  og:image     https://example.com/og.png
+  image dims   1200×630px
+
+  WRN og:image     The image does not match the 1.91:1 share frame.
+      impact       Depending on the platform and viewport, the asset can be cropped or padded.
+      evidence     The decoded asset is 1200×1200px (1.00:1); the workspace frame is 1.91:1.
+      fix          Export a 1200×630px version and keep important content away from the edges.
+  ...
+  preview → /var/folders/.../preview.html
+```
+
+`--json` output has parsed metadata, the image probe, and a typed `issues[]` array. Existing `level`, `field`, and `message` keys remain; `code`, `impact`, `evidence`, and `fix` add repair context.
+
+The HTML report is a responsive local workspace with four representative card mocks, light/dark treatments, explicit source fallbacks, crop-versus-fit image inspection, prioritized validation, parsed facts, and reviewed repair outputs. Platform experiments, viewport differences, and cached unfurls can differ from the mocks.
+
+## Limitations to know
+
+- Bun must be on `PATH`; users without Bun get a clear error pointing to https://bun.sh/install.
+- Currently parses meta tags via regex on the `<head>` substring. Handles standard cases; pages that use `<base href>` or that emit meta tags outside `<head>` may parse imperfectly. If a page has weird structure, fall back to viewing raw HTML.
+- The platform cards are representative and can differ from live UI experiments, viewport treatments, and cached unfurls. The report makes that uncertainty explicit.
+- No JavaScript rendering. If the page sets meta tags via client-side JS (rare; bad practice for shared content), `metaprev` won't see them. Recommend the user emit meta tags server-side / at build.

package/src/fetch.ts

@@ -0,0 +1,215 @@
+import { imageSize } from 'image-size'
+import { classifyUrlHost } from './host.ts'
+import type { ImageProbe } from './types.ts'
+
+const UA = 'metaprev (+https://github.com/forsvn-labs/metaprev)'
+
+// Fetch policy: local dev targets stay fetchable — that is the product's job.
+export function isLocalUrl(url: string): boolean {
+  return classifyUrlHost(url).isLocalDevHost
+}
+
+type FetchOpts = { insecure?: boolean }
+type ProbeOpts = FetchOpts & { withDataUri?: boolean }
+
+// Cap how much HTML we pull into memory. The <head> sits at the top of the document,
+// so a few MB is plenty to find every meta tag while staying immune to multi-hundred-MB
+// or never-ending responses.
+const MAX_HTML_BYTES = 4 * 1024 * 1024
+
+// Cap image downloads too. This is a memory-safety ceiling, not a platform limit;
+// validation applies the current platform-specific threshold separately.
+const MAX_IMAGE_BYTES = 32 * 1024 * 1024
+
+function tlsOpt(url: string, opts: FetchOpts): { rejectUnauthorized: false } | undefined {
+  return opts.insecure || isLocalUrl(url) ? { rejectUnauthorized: false } : undefined
+}
+
+function timeoutError(err: unknown, ctrl: AbortController, timeoutMs: number): Error {
+  if (ctrl.signal.aborted || (err as Error)?.name === 'AbortError') {
+    return new Error(`timed out after ${Math.round(timeoutMs / 1000)}s`)
+  }
+  return err as Error
+}
+
+// Read a response body up to a byte cap, cancelling the stream once exceeded. Returns the
+// bytes (sliced to the cap) plus whether more data was left unread.
+export async function readCappedBytes(res: Response, maxBytes: number): Promise<{ bytes: Buffer; truncated: boolean }> {
+  const body = res.body
+  if (!body) {
+    // Null-body path: there is no stream to cap mid-flight, so the only safe bound
+    // is the declared length. A missing or oversized Content-Length is rejected
+    // rather than read into memory unbounded.
+    const declaredLen = Number(res.headers.get('content-length'))
+    if (res.headers.get('content-length') === null || !Number.isFinite(declaredLen) || declaredLen < 0 || declaredLen > maxBytes) {
+      throw new Error(`Response body has no readable stream and ${res.headers.get('content-length') !== null ? 'declares more than' : 'does not declare'} the readable size limit`)
+    }
+    const all = Buffer.from(await res.arrayBuffer())
+    return { bytes: all.subarray(0, maxBytes), truncated: all.byteLength > maxBytes }
+  }
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  let truncated = false
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (!value) continue
+      chunks.push(value)
+      total += value.byteLength
+      if (total > maxBytes) {
+        // Past the cap; we have more than enough. A cancel() rejection must not discard it.
+        truncated = true
+        await reader.cancel().catch(() => {})
+        break
+      }
+    }
+  } finally {
+    reader.releaseLock?.()
+  }
+  const buf = Buffer.concat(chunks)
+  return { bytes: truncated ? buf.subarray(0, maxBytes) : buf, truncated }
+}
+
+// Read a response body up to a byte cap. Returns decoded text.
+async function readCapped(res: Response, maxBytes: number): Promise<string> {
+  const { bytes } = await readCappedBytes(res, maxBytes)
+  return new TextDecoder('utf-8').decode(bytes)
+}
+
+function guessMime(url: string): string | undefined {
+  const ext = url.split('?')[0]?.split('#')[0]?.split('.').pop()?.toLowerCase()
+  switch (ext) {
+    case 'png': return 'image/png'
+    case 'jpg':
+    case 'jpeg': return 'image/jpeg'
+    case 'webp': return 'image/webp'
+    case 'gif': return 'image/gif'
+    case 'svg': return 'image/svg+xml'
+    case 'avif': return 'image/avif'
+    default: return undefined
+  }
+}
+
+type PageResult = {
+  finalUrl: string
+  status: number
+  html: string
+}
+
+export async function fetchPage(url: string, opts: FetchOpts = {}, timeoutMs = 10_000): Promise<PageResult> {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    throw new Error('Invalid page URL')
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error('Page URL must use HTTP or HTTPS')
+  }
+
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+  try {
+    const res = await fetch(url, {
+      headers: { 'user-agent': UA, accept: 'text/html,*/*', 'cache-control': 'no-cache', pragma: 'no-cache' },
+      redirect: 'follow',
+      cache: 'no-store',
+      signal: ctrl.signal,
+      tls: tlsOpt(url, opts),
+    })
+    if (!res.ok) {
+      await res.body?.cancel().catch(() => {})
+      throw new Error(`page returned HTTP ${res.status}`)
+    }
+    const contentType = (res.headers.get('content-type') ?? '').split(';')[0]!.trim().toLowerCase()
+    if (contentType && contentType !== 'text/html' && contentType !== 'application/xhtml+xml') {
+      await res.body?.cancel().catch(() => {})
+      throw new Error(`page returned ${contentType}, not HTML`)
+    }
+    const html = await readCapped(res, MAX_HTML_BYTES)
+    return { finalUrl: res.url || url, status: res.status, html }
+  } catch (err) {
+    throw timeoutError(err, ctrl, timeoutMs)
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export async function probeImage(url: string, base: string, opts: ProbeOpts = {}, timeoutMs = 10_000): Promise<ImageProbe> {
+  let resolved = url
+  try {
+    const parsed = new URL(url, base)
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return { url, resolved: parsed.toString(), status: 0, ok: false, error: 'Image URL must use HTTP or HTTPS' }
+    }
+    resolved = parsed.toString()
+  } catch {
+    return { url, resolved: url, status: 0, ok: false, error: 'Invalid image URL' }
+  }
+
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+  try {
+    const res = await fetch(resolved, {
+      headers: { 'user-agent': UA, accept: 'image/*,*/*', 'cache-control': 'no-cache', pragma: 'no-cache' },
+      redirect: 'follow',
+      cache: 'no-store',
+      signal: ctrl.signal,
+      tls: tlsOpt(resolved, opts),
+    })
+    const probe: ImageProbe = {
+      url,
+      resolved: res.url || resolved,
+      status: res.status,
+      ok: res.ok,
+      contentType: res.headers.get('content-type') ?? undefined,
+    }
+    if (!res.ok) {
+      probe.error = `HTTP ${res.status}`
+      return probe
+    }
+    const { bytes: buf, truncated } = await readCappedBytes(res, MAX_IMAGE_BYTES)
+    // Trust Content-Length for the true size when present; otherwise fall back to what we
+    // read (which equals the cap when truncated — still enough to trip the "too big" warn).
+    const declaredLen = Number(res.headers.get('content-length'))
+    probe.byteLength = Number.isFinite(declaredLen) && declaredLen > 0 ? declaredLen : buf.byteLength
+    try {
+      const dims = imageSize(buf)
+      probe.width = dims.width
+      probe.height = dims.height
+      const detectedMime: Record<string, string> = {
+        avif: 'image/avif', gif: 'image/gif', jpg: 'image/jpeg', png: 'image/png',
+        svg: 'image/svg+xml', webp: 'image/webp',
+      }
+      probe.detectedContentType = dims.type ? detectedMime[dims.type] : undefined
+    } catch (err) {
+      probe.error = `Could not read image dimensions: ${(err as Error).message}`
+    }
+    // Only build the (potentially multi-MB) base64 data URI when the caller actually
+    // renders the HTML preview. issues / facts / --json never embed the image, so
+    // skipping the encode saves CPU and peak memory. Skip it too when the body was
+    // truncated — a partial buffer would embed a broken image.
+    if (opts.withDataUri && !truncated) {
+      // Validate the MIME against a strict pattern before embedding into HTML/CSS — a
+      // misbehaving server could otherwise propagate junk into the data: URI which then
+      // sits inside `style="background-image: url('...')"`.
+      const embeddable = new Set(['image/avif', 'image/gif', 'image/jpeg', 'image/png', 'image/webp'])
+      const rawMime = (probe.contentType?.split(';')[0] ?? '').trim().toLowerCase()
+      const mime = probe.detectedContentType ?? (embeddable.has(rawMime) ? rawMime : undefined) ?? guessMime(resolved)
+      if (mime && embeddable.has(mime)) probe.dataUri = `data:${mime};base64,${buf.toString('base64')}`
+    }
+    return probe
+  } catch (err) {
+    return {
+      url,
+      resolved,
+      status: 0,
+      ok: false,
+      error: timeoutError(err, ctrl, timeoutMs).message,
+    }
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/src/format.ts

@@ -0,0 +1,5 @@
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+  return `${(n / 1024 / 1024).toFixed(2)} MB`
+}

package/src/host.ts

@@ -0,0 +1,93 @@
+// Single source of truth for host scope classification.
+//
+// Two policies read from one classifier so fetch behavior and repair-snippet
+// behavior can never drift apart by accident:
+//   - fetch keeps working for loopback/local dev targets (the product's job).
+//   - repair outputs require a genuinely public host before emitting copy-ready URLs.
+
+export type HostScope =
+  | 'loopback' // this machine (127.0.0.0/8, ::1, 0.0.0.0)
+  | 'local' // development names (*.localhost, *.test, *.local)
+  | 'private' // RFC1918, CGNAT, link-local, ULA, and other non-routable ranges
+  | 'reserved' // documentation, multicast, benchmark, and other special-purpose ranges
+  | 'unspecified' // "::" or an empty host
+  | 'public'
+
+const LOCAL_NAME_RE = /^(?:[^.]+\.)*(?:localhost|test|local)$/i
+
+function parseIpv4(host: string): [number, number, number, number] | undefined {
+  if (!/^\d{1,3}(?:\.\d{1,3}){3}$/.test(host)) return undefined
+  const parts = host.split('.').map(Number)
+  if (parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) return undefined
+  return parts as [number, number, number, number]
+}
+
+function ipv4Scope([a, b]: [number, number, number, number]): HostScope {
+  if (a === 127) return 'loopback'
+  if (a === 0) return 'unspecified' // "this network" 0.0.0.0/8 never routes publicly
+  if (a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168)) return 'private'
+  if (a === 100 && b >= 64 && b <= 127) return 'private' // CGNAT 100.64.0.0/10
+  if (a === 169 && b === 254) return 'private' // link-local
+  if ((a === 192 && (b === 0 || b === 88)) || (a === 198 && b === 51) || (a === 203 && b === 0)) return 'reserved'
+  if (a >= 224) return 'reserved' // multicast + reserved + broadcast
+  return 'public'
+}
+
+function ipv6Scope(host: string): HostScope {
+  const h = host.toLowerCase()
+  if (h === '::') return 'unspecified'
+  if (h === '::1') return 'loopback'
+  // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible addresses inherit the v4 scope.
+  const mapped = /^::ffff:(?:(\d{1,3}(?:\.\d{1,3}){3})|([0-9a-f]{1,4}):([0-9a-f]{1,4}))$/.exec(h)
+  if (mapped) {
+    if (mapped[1]) {
+      const v4 = parseIpv4(mapped[1])
+      if (v4) return ipv4Scope(v4)
+    } else {
+      const hi = parseInt(mapped[2]!, 16)
+      const lo = parseInt(mapped[3]!, 16)
+      return ipv4Scope([(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff])
+    }
+  }
+  if (/^f[cd][0-9a-f]{0,2}:/.test(h)) return 'private' // unique-local fc00::/7
+  if (/^fe[89ab][0-9a-f]:/.test(h)) return 'private' // link-local fe80::/10
+  if (/^ff[0-9a-f]{2}:/.test(h)) return 'reserved' // multicast ff00::/8
+  if (/^2001:db8:/.test(h)) return 'reserved' // documentation
+  if (/^100::/.test(h)) return 'reserved' // discard-only
+  if (/^64:ff9b:/.test(h)) return 'reserved' // NAT64 well-known prefix (translation infra)
+  return 'public'
+}
+
+/** Classify a URL hostname (brackets on IPv6 literals are tolerated). */
+export function classifyHost(hostname: string): HostScope {
+  let host = hostname.trim().replace(/^\[|\]$/g, '').toLowerCase()
+  if (!host) return 'unspecified'
+  if (host.endsWith('.') && !host.endsWith('..')) host = host.slice(0, -1) // trailing dot FQDN form
+  if (LOCAL_NAME_RE.test(host)) return 'local'
+  if (host.includes(':')) return ipv6Scope(host)
+  const v4 = parseIpv4(host)
+  if (v4) return ipv4Scope(v4)
+  return 'public'
+}
+
+export type HostPolicy = {
+  /** Loopback + dev names: the targets a developer runs against locally. */
+  isLocalDevHost: boolean
+  /** Safe to emit as a copy-ready share URL in repair output. */
+  isPublicHost: boolean
+}
+
+/** One shared classifier; callers pick the policy predicate they need. */
+export function classifyUrlHost(url: string): HostPolicy {
+  let hostname = ''
+  try {
+    hostname = new URL(url).hostname
+  } catch {
+    return { isLocalDevHost: false, isPublicHost: false }
+  }
+  const scope = classifyHost(hostname)
+  return {
+    isLocalDevHost: scope === 'loopback' || scope === 'local',
+    isPublicHost: scope === 'public',
+  }
+}

package/src/inputs.ts

@@ -0,0 +1,94 @@
+import type { MetaTags } from './types.ts'
+
+// ── twitter:card vocabulary ───────────────────────────────────────────────
+// Shared by the validator, the repair snippet, and the renderer so the set of
+// known card treatments lives in exactly one place.
+
+export const CARD_SUMMARY = 'summary'
+export const CARD_SUMMARY_LARGE_IMAGE = 'summary_large_image'
+/** Card types X documents for twitter:card. */
+export const KNOWN_TWITTER_CARDS = [CARD_SUMMARY, CARD_SUMMARY_LARGE_IMAGE, 'app', 'player'] as const
+/** Card treatments this workspace renders faithfully. */
+export const RENDERED_TWITTER_CARDS: ReadonlySet<string> = new Set([CARD_SUMMARY, CARD_SUMMARY_LARGE_IMAGE])
+
+export function isKnownTwitterCard(value: string): boolean {
+  return (KNOWN_TWITTER_CARDS as readonly string[]).includes(value)
+}
+
+// ── canonical input fallback policy ───────────────────────────────────────
+// One precedence ladder per surface; CLI output, HTML render, and repair text
+// all resolve through these helpers.
+
+export type PlatformName = 'Open Graph' | 'X'
+export type TextField = 'title' | 'description'
+export type InputSource =
+  | 'og:title' | 'twitter:title' | '<title>' | 'none'
+  | 'og:description' | 'twitter:description' | 'meta description'
+
+export type ResolvedInputValue = {
+  value?: string
+  source: InputSource
+  /** True when the winning source is a fallback rather than the platform's own tag. */
+  fallback: boolean
+}
+
+const TITLE_SOURCES: Record<PlatformName, Array<{ key: keyof MetaTags; source: InputSource }>> = {
+  // Open Graph consumers do not read twitter:* copy as a fallback.
+  'Open Graph': [{ key: 'ogTitle', source: 'og:title' }, { key: 'title', source: '<title>' }],
+  X: [
+    { key: 'twitterTitle', source: 'twitter:title' },
+    { key: 'ogTitle', source: 'og:title' },
+    { key: 'title', source: '<title>' },
+  ],
+}
+
+const DESCRIPTION_SOURCES: Record<PlatformName, Array<{ key: keyof MetaTags; source: InputSource }>> = {
+  'Open Graph': [{ key: 'ogDescription', source: 'og:description' }, { key: 'description', source: 'meta description' }],
+  X: [
+    { key: 'twitterDescription', source: 'twitter:description' },
+    { key: 'ogDescription', source: 'og:description' },
+    { key: 'description', source: 'meta description' },
+  ],
+}
+
+function resolveFrom(m: MetaTags, ladder: Array<{ key: keyof MetaTags; source: InputSource }>): ResolvedInputValue {
+  for (const step of ladder) {
+    const value = m[step.key]
+    if (value) return { value, source: step.source, fallback: step.source !== ladder[0]!.source }
+  }
+  return { value: undefined, source: 'none', fallback: true }
+}
+
+export function resolvePlatformInput(m: MetaTags, platform: PlatformName, field: TextField): ResolvedInputValue {
+  return field === 'title'
+    ? resolveFrom(m, TITLE_SOURCES[platform])
+    : resolveFrom(m, DESCRIPTION_SOURCES[platform])
+}
+
+/**
+ * Primary share copy shown at the top of terminal/facts/report output and used
+ * as the starting value in the repair snippet: the protocol's own og:* value
+ * first, then X-specific copy, then the page-level tag.
+ */
+const PRIMARY_TITLE_LADDER: Array<{ key: keyof MetaTags; source: InputSource }> = [
+  { key: 'ogTitle', source: 'og:title' },
+  { key: 'twitterTitle', source: 'twitter:title' },
+  { key: 'title', source: '<title>' },
+]
+
+const PRIMARY_DESCRIPTION_LADDER: Array<{ key: keyof MetaTags; source: InputSource }> = [
+  { key: 'ogDescription', source: 'og:description' },
+  { key: 'twitterDescription', source: 'twitter:description' },
+  { key: 'description', source: 'meta description' },
+]
+
+/**
+ * Primary share copy shown at the top of terminal/facts/report output and used
+ * as the starting value in the repair snippet: the protocol's own og:* value
+ * first, then X-specific copy, then the page-level tag.
+ */
+export function resolvePrimaryInput(m: MetaTags, field: TextField): ResolvedInputValue {
+  return field === 'title'
+    ? resolveFrom(m, PRIMARY_TITLE_LADDER)
+    : resolveFrom(m, PRIMARY_DESCRIPTION_LADDER)
+}