From 392253ff0826aa0a55bd4da32b47f4ce24de272a Mon Sep 17 00:00:00 2001
From: Corey Petty <corey@status.im>
Date: Tue, 14 Jul 2026 09:47:42 -0400
Subject: [PATCH 1/6] trying out a way to implement inline commenting system
 into quartz

---
 docs-internal/inline-comments-design.md       | 200 +++++
 quartz.layout.ts                              |  14 +
 quartz/components/InlineComments.tsx          |  58 ++
 quartz/components/index.ts                    |   2 +
 .../scripts/inlineComments.inline.ts          | 806 ++++++++++++++++++
 quartz/components/styles/inlineComments.scss  | 227 +++++
 .../inline-comments-worker/.dev.vars.example  |   4 +
 serverless/inline-comments-worker/README.md   |  89 ++
 .../inline-comments-worker/package.json       |  16 +
 .../inline-comments-worker/src/index.ts       | 282 ++++++
 .../inline-comments-worker/tsconfig.json      |  16 +
 .../inline-comments-worker/wrangler.toml      |  13 +
 12 files changed, 1727 insertions(+)
 create mode 100644 docs-internal/inline-comments-design.md
 create mode 100644 quartz/components/InlineComments.tsx
 create mode 100644 quartz/components/scripts/inlineComments.inline.ts
 create mode 100644 quartz/components/styles/inlineComments.scss
 create mode 100644 serverless/inline-comments-worker/.dev.vars.example
 create mode 100644 serverless/inline-comments-worker/README.md
 create mode 100644 serverless/inline-comments-worker/package.json
 create mode 100644 serverless/inline-comments-worker/src/index.ts
 create mode 100644 serverless/inline-comments-worker/tsconfig.json
 create mode 100644 serverless/inline-comments-worker/wrangler.toml

diff --git a/docs-internal/inline-comments-design.md b/docs-internal/inline-comments-design.md
new file mode 100644
index 0000000..1ebd30e
--- /dev/null
+++ b/docs-internal/inline-comments-design.md
@@ -0,0 +1,200 @@
+# Inline Comments for Quartz — Design
+
+> Status: **draft / in progress**
+> Owner: Corey Petty
+> Companion code: `quartz/components/InlineComments.tsx`, `quartz/components/scripts/inlineComments.inline.ts`, `serverless/inline-comments-worker/`
+
+## Goal
+
+Add **inline, anchored comments** to this Quartz site — comments attached to a
+specific text selection or paragraph (Medium margin-notes / Hypothes.is style),
+not just one thread at the bottom of the page. It must be:
+
+- **Portable** — a single drop-in Quartz component + one small serverless function.
+- **Backed by GitHub Discussions** — same store as the existing page-bottom
+  comments, so nothing is fragmented.
+- **Authenticated with GitHub** — same identity model the site already uses.
+
+## Starting point (what already exists)
+
+`quartz.layout.ts` wires Quartz's built-in `Comments` component with
+`provider: "giscus"`, pointed at GitHub Discussions on `logos-co/assembly`
+(category _Announcements_). Giscus gives us **page-level** comments only:
+
+- Auth + posting happen entirely inside Giscus's hosted `<iframe>`.
+- One GitHub Discussion per page, mapped by URL.
+
+**Constraint that drives everything below:** Giscus is a closed widget. It will
+not hand our code the user's GitHub token, and it will not let us attach custom
+anchor metadata to a comment. So we can _read_ a page's discussion and render any
+comment that carries an anchor, but we cannot make Giscus _write_ an anchored
+comment. Inline **writing** therefore requires our own GitHub auth.
+
+We keep the existing Giscus widget. This system coexists with it on the **same
+per-page Discussion** (see "Coexistence").
+
+## Architecture overview
+
+```
+ ┌─────────────────────────── browser (static Quartz page) ───────────────────────────┐
+ │  InlineComments.inline.ts                                                            │
+ │   • anchoring engine (text-quote + text-position selectors)                          │
+ │   • selection UI → floating "Comment" button → composer                              │
+ │   • renders <mark> highlights + margin badges + thread popovers                      │
+ │                                                                                      │
+ │   reads (anon + authed) ───────────►  Worker /api/comments  ──► GitHub GraphQL       │
+ │   login  ───────────────────────────► Worker /api/auth/login (302 → github.com)      │
+ │   token exchange ◄──────────────────  Worker /api/auth/callback (postMessage token)  │
+ │   writes (authed) ─────────────────────────────────────────►  GitHub GraphQL (user)  │
+ └──────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+The only non-static piece is the **Worker** (Cloudflare Workers / Vercel /
+Netlify function). It does three things and holds the two secrets that can't live
+in the browser:
+
+1. `GET /api/auth/login` → redirect to GitHub's OAuth authorize URL.
+2. `GET /api/auth/callback` → exchange `code` (+ `client_secret`) for a user
+   access token; return a tiny HTML page that `postMessage`s the token to the
+   opener and closes.
+3. `GET /api/comments` → **anonymous read proxy**. Uses a _server-side_ token so
+   visitors who are not logged in can still see inline highlights. (Giscus solves
+   the same problem behind its own backend; here we own it.)
+
+**Writes** go from the browser straight to GitHub's GraphQL API using the
+**user's own token** (`addDiscussionComment` / `addDiscussionCommentReply`). The
+Worker never sees write traffic and never stores a user token. This keeps the
+Worker tiny and minimizes the secret/trust surface.
+
+## Anchoring
+
+We use the **W3C Web Annotation** selector model (the same approach Hypothes.is
+uses), which is robust to reflow and minor content edits:
+
+- `TextQuoteSelector` — `{ exact, prefix, suffix }`. The selected text plus a
+  short window of surrounding context. Primary anchor; survives DOM structure
+  changes because it matches on text, not element paths.
+- `TextPositionSelector` — `{ start, end }` character offsets into the article's
+  normalized text. Fast path + disambiguation when the same `exact` string
+  appears multiple times.
+- `slug` — nearest heading id, coarse fallback / margin grouping.
+
+**Anchoring root:** the article body, rendered by Quartz as
+`<article class="popover-hint">` inside `.center`. We compute offsets over the
+concatenated text nodes of that element only (sidebars/nav excluded).
+
+**Re-anchoring on load:** find `exact` in the article text; if it occurs once,
+done. If multiple, disambiguate with `prefix`/`suffix`, then `start/end`. Map the
+resolved character range back to a DOM `Range` and wrap it in
+`<mark class="inline-comment-highlight" data-comment-id="…">`.
+
+**Orphans:** if `exact` can't be found (content changed too much), the comment is
+_not_ lost — it is flagged `orphaned` and shown in a page-level fallback list
+under the article. v1 uses exact + context matching; a later pass can swap in
+`dom-anchor-text-quote` + `diff-match-patch` for fuzzy tolerance without changing
+the stored format.
+
+## Storage format
+
+One GitHub Discussion per page (same URL→discussion mapping as Giscus, so the two
+systems share a discussion). Each inline comment is a **top-level discussion
+comment**; replies use `addDiscussionCommentReply`. The anchor rides along in the
+comment body as an HTML comment — invisible in GitHub's rendered Discussion,
+parseable by us:
+
+```markdown
+> the exact text the reader highlighted
+
+The reader's actual comment prose.
+
+<!-- quartz-anchor: {"v":1,"exact":"…","prefix":"…","suffix":"…","start":1234,"end":1290,"slug":"a-heading"} -->
+```
+
+- The `> quote` blockquote makes the comment self-explanatory on GitHub itself.
+- The trailing `<!-- quartz-anchor: … -->` is the machine-readable anchor. We
+  parse it out and strip it before rendering the body in the UI.
+- Versioned (`"v":1`) so the format can evolve.
+
+## Coexistence with Giscus
+
+Because both systems use the same per-page Discussion:
+
+- A comment **without** a `quartz-anchor` marker → a normal page-level comment,
+  rendered by the existing Giscus widget at the bottom (unchanged).
+- A comment **with** a marker → rendered inline by this plugin in the margin.
+
+No migration, no data split. You can run both indefinitely, or later retire the
+Giscus widget once the inline UI also renders unanchored comments as a bottom
+list (the read proxy already returns them).
+
+## Auth flow (detail)
+
+1. User selects text, clicks "Comment", writes, hits submit while logged out.
+2. Plugin opens a popup to `GET {apiBase}/api/auth/login?redirect=<worker>` with
+   a random `state` (stored in `sessionStorage`).
+3. Worker 302s to `https://github.com/login/oauth/authorize` with `client_id`,
+   `scope=public_repo`, `state`.
+4. GitHub redirects back to `GET {apiBase}/api/auth/callback?code&state`.
+5. Worker exchanges `code` + `client_secret` for a user token, returns HTML that
+   `window.opener.postMessage({ type: "inline-comments-token", token }, origin)`
+   and closes the popup.
+6. Plugin stores the token (`localStorage`, keyed per-origin) and retries the
+   pending submit.
+
+Trust model is identical to Giscus/utterances: the user posts **as themselves**
+with their own token; the site never posts on their behalf. `public_repo` is
+sufficient to comment on Discussions of a public repo. (A GitHub **App** with
+fine-grained Discussion write is a stricter alternative — noted as a follow-up.)
+
+## Component / config surface
+
+`quartz.layout.ts`:
+
+```ts
+Component.InlineComments({
+  provider: "github",
+  options: {
+    repo: "logos-co/assembly",
+    repoId: "R_kgDOQUhKqA",
+    category: "Announcements",
+    categoryId: "DIC_kwDOQUhKqM4Cxur2",
+    apiBase: "https://inline-comments.<you>.workers.dev", // the Worker
+    mapping: "pathname", // how a page maps to a discussion term
+  },
+})
+```
+
+If `apiBase` is unset the client **no-ops gracefully** (site still builds and
+renders; no inline UI). This keeps the component safe to land before the Worker
+is deployed.
+
+## Rate limits
+
+- Authenticated GraphQL: 5000 points/hour/user — ample for writing.
+- Anonymous reads go through the Worker's server token (also 5000/hr, shared).
+  Mitigations if needed: short edge cache on `/api/comments`, and the client
+  only fetches on pages where the component is present.
+
+## Rollout phases
+
+- **Phase 1 — anchoring + read-only render.** Ship the component, SCSS, and the
+  anchoring/render engine. Reads come through the Worker's `/api/comments`.
+  Proves the risky part (anchoring robustness) against real Discussion data.
+- **Phase 2 — auth + write.** Login popup + composer + `addDiscussionComment`.
+- **Phase 3 — threads + polish.** Replies, margin/gutter UX, orphan list,
+  reactions, optional fuzzy re-anchoring.
+
+## Alternatives considered
+
+- **Hypothes.is embed** — inline annotations for free, no backend, but stores in
+  Hypothes.is with its own identity. Fails "push to Discussions."
+- **Read-only inline over Giscus** — no backend, but cannot write anchored
+  comments. Incomplete alone.
+- **Self-host giscus's backend** — full control, far more than needed.
+
+## Open questions / follow-ups
+
+- GitHub **App** (fine-grained) vs **OAuth App** (`public_repo`) for writes.
+- Whether to also render unanchored comments in-plugin and retire Giscus.
+- Fuzzy re-anchoring library choice (`dom-anchor-text-quote` + `diff-match-patch`).
+- Abuse/moderation: rely on GitHub Discussion moderation + repo permissions.
diff --git a/quartz.layout.ts b/quartz.layout.ts
index 083ed02..af179f3 100644
--- a/quartz.layout.ts
+++ b/quartz.layout.ts
@@ -21,6 +21,20 @@ export const sharedPageComponents: SharedLayout = {
         lang: "en",
       },
     }),
+    // Inline (anchored) comments — shares the same GitHub Discussion as giscus
+    // above. No-ops until `apiBase` points at a deployed inline-comments worker
+    // (see serverless/inline-comments-worker + docs-internal/inline-comments-design.md).
+    Component.InlineComments({
+      provider: "github",
+      options: {
+        repo: "logos-co/assembly",
+        repoId: "R_kgDOQUhKqA",
+        category: "Announcements",
+        categoryId: "DIC_kwDOQUhKqM4Cxur2",
+        apiBase: "", // e.g. "https://inline-comments.<you>.workers.dev"
+        mapping: "url", // match giscus's mapping to share the same discussion
+      },
+    }),
   ],
   footer: Component.Footer({
     links: {
diff --git a/quartz/components/InlineComments.tsx b/quartz/components/InlineComments.tsx
new file mode 100644
index 0000000..72c02b3
--- /dev/null
+++ b/quartz/components/InlineComments.tsx
@@ -0,0 +1,58 @@
+import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import { classNames } from "../util/lang"
+// @ts-ignore
+import script from "./scripts/inlineComments.inline"
+import style from "./styles/inlineComments.scss"
+
+type Options = {
+  provider: "github"
+  options: {
+    // owner/name of the repo holding the Discussions, e.g. "logos-co/assembly"
+    repo: `${string}/${string}`
+    // GraphQL node id of the repo (data-repo-id in giscus config)
+    repoId: string
+    // Discussion category name, e.g. "Announcements"
+    category: string
+    // GraphQL node id of the category (data-category-id in giscus config)
+    categoryId: string
+    // Base URL of the serverless worker (OAuth exchange + anonymous read proxy).
+    // If empty, the client no-ops gracefully and nothing is rendered.
+    apiBase?: string
+    // how a page maps to a discussion "term". Matches the existing giscus mapping.
+    mapping?: "url" | "title" | "pathname"
+  }
+}
+
+export default ((opts: Options) => {
+  const InlineComments: QuartzComponent = ({
+    displayClass,
+    fileData,
+    cfg,
+  }: QuartzComponentProps) => {
+    // respect the same frontmatter opt-out as the built-in Comments component
+    const disableComment: boolean =
+      typeof fileData.frontmatter?.comments !== "undefined" &&
+      (!fileData.frontmatter?.comments || fileData.frontmatter?.comments === "false")
+    if (disableComment) {
+      return <></>
+    }
+
+    return (
+      <div
+        class={classNames(displayClass, "inline-comments")}
+        data-repo={opts.options.repo}
+        data-repo-id={opts.options.repoId}
+        data-category={opts.options.category}
+        data-category-id={opts.options.categoryId}
+        data-api-base={opts.options.apiBase ?? ""}
+        data-mapping={opts.options.mapping ?? "pathname"}
+        data-base-url={cfg.baseUrl ?? ""}
+      ></div>
+    )
+  }
+
+  InlineComments.afterDOMLoaded = script
+  InlineComments.css = style
+
+  return InlineComments
+}) satisfies QuartzComponentConstructor<Options>
diff --git a/quartz/components/index.ts b/quartz/components/index.ts
index cece8e6..33f8122 100644
--- a/quartz/components/index.ts
+++ b/quartz/components/index.ts
@@ -21,6 +21,7 @@ import MobileOnly from "./MobileOnly"
 import RecentNotes from "./RecentNotes"
 import Breadcrumbs from "./Breadcrumbs"
 import Comments from "./Comments"
+import InlineComments from "./InlineComments"
 import Flex from "./Flex"
 import ConditionalRender from "./ConditionalRender"
 
@@ -48,6 +49,7 @@ export {
   NotFound,
   Breadcrumbs,
   Comments,
+  InlineComments,
   Flex,
   ConditionalRender,
 }
diff --git a/quartz/components/scripts/inlineComments.inline.ts b/quartz/components/scripts/inlineComments.inline.ts
new file mode 100644
index 0000000..ecdaa23
--- /dev/null
+++ b/quartz/components/scripts/inlineComments.inline.ts
@@ -0,0 +1,806 @@
+import { computePosition, offset, flip, shift, autoUpdate } from "@floating-ui/dom"
+
+// ────────────────────────────────────────────────────────────────────────
+// Inline, anchored comments for Quartz, backed by GitHub Discussions.
+//
+//  • Anchoring uses a W3C-style text-quote + text-position selector so a
+//    comment survives reflow and minor content edits.
+//  • Reads go through the serverless worker (`apiBase`) so anonymous visitors
+//    can see highlights without logging in.
+//  • Writes go straight to GitHub's GraphQL API with the user's own token.
+//
+// See docs-internal/inline-comments-design.md for the full design.
+// ────────────────────────────────────────────────────────────────────────
+
+type TextQuoteAnchor = {
+  v: number
+  exact: string
+  prefix: string
+  suffix: string
+  start: number
+  end: number
+  slug: string
+}
+
+type CommentAuthor = { login: string; avatarUrl: string }
+
+type RawComment = {
+  id: string
+  author: CommentAuthor
+  body: string
+  bodyHTML: string
+  createdAt: string
+  url: string
+  replies?: RawComment[]
+}
+
+type CommentsResponse = {
+  discussionId: string | null
+  discussionNumber: number | null
+  comments: RawComment[]
+}
+
+type Config = {
+  repo: string
+  repoId: string
+  category: string
+  categoryId: string
+  apiBase: string
+  mapping: string
+  baseUrl: string
+}
+
+type TextSegment = { node: Text; start: number; end: number }
+
+const TOKEN_KEY = "inline-comments-gh-token"
+const STATE_KEY = "inline-comments-oauth-state"
+const ANCHOR_RE = /<!--\s*quartz-anchor:\s*(\{[\s\S]*?\})\s*-->/
+const CONTEXT_LEN = 32
+const GITHUB_GRAPHQL = "https://api.github.com/graphql"
+
+// ─── config ─────────────────────────────────────────────────────────────
+
+function readConfig(container: HTMLElement): Config {
+  const d = container.dataset
+  return {
+    repo: d.repo ?? "",
+    repoId: d.repoId ?? "",
+    category: d.category ?? "",
+    categoryId: d.categoryId ?? "",
+    apiBase: (d.apiBase ?? "").replace(/\/$/, ""),
+    mapping: d.mapping ?? "pathname",
+    baseUrl: d.baseUrl ?? "",
+  }
+}
+
+function getRoot(): HTMLElement | null {
+  return document.querySelector("article.popover-hint")
+}
+
+function getTerm(cfg: Config): string {
+  switch (cfg.mapping) {
+    case "title":
+      return document.title
+    case "url":
+      return location.origin + location.pathname
+    case "pathname":
+    default:
+      return location.pathname.replace(/\/+$/, "") || "/"
+  }
+}
+
+// ─── anchoring engine ───────────────────────────────────────────────────
+
+// Collect the article's text nodes with their cumulative character offsets,
+// skipping our own injected UI (badges) so offsets stay stable across renders.
+function collectSegments(root: Node): { text: string; segments: TextSegment[] } {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+    acceptNode(node: Node): number {
+      const parent = (node as Text).parentElement
+      if (parent?.closest("[data-inline-comment-ignore]")) {
+        return NodeFilter.FILTER_REJECT
+      }
+      return NodeFilter.FILTER_ACCEPT
+    },
+  })
+  let text = ""
+  const segments: TextSegment[] = []
+  let n: Node | null
+  while ((n = walker.nextNode())) {
+    const t = n as Text
+    const start = text.length
+    text += t.data
+    segments.push({ node: t, start, end: text.length })
+  }
+  return { text, segments }
+}
+
+// Character offset within the concatenated article text for a DOM boundary
+// point. Works for both text-node and element containers.
+function pointOffset(
+  segments: TextSegment[],
+  container: Node,
+  offsetInNode: number,
+): number | null {
+  const probe = document.createRange()
+  try {
+    probe.setStart(container, offsetInNode)
+    probe.collapse(true)
+  } catch {
+    return null
+  }
+  let total = 0
+  for (const seg of segments) {
+    let endCmp: number
+    let startCmp: number
+    try {
+      endCmp = probe.comparePoint(seg.node, seg.node.data.length)
+      startCmp = probe.comparePoint(seg.node, 0)
+    } catch {
+      continue
+    }
+    if (endCmp <= 0) {
+      // whole segment lies before the boundary
+      total += seg.node.data.length
+    } else if (startCmp >= 0) {
+      // whole segment lies after the boundary — nothing to add
+    } else {
+      // boundary falls inside this segment
+      if (container === seg.node) {
+        total += offsetInNode
+      } else {
+        total += seg.node.data.length
+      }
+    }
+  }
+  return total
+}
+
+function nearestHeadingSlug(node: Node): string {
+  let el: Element | null =
+    node.nodeType === Node.ELEMENT_NODE ? (node as Element) : node.parentElement
+  while (el) {
+    const heading = el.matches?.("h1,h2,h3,h4,h5,h6")
+      ? el
+      : el.previousElementSibling?.closest?.("h1,h2,h3,h4,h5,h6")
+    if (heading?.id) return heading.id
+    el = el.parentElement
+  }
+  const firstHeadingWithId = document.querySelector(
+    "article.popover-hint :is(h1,h2,h3,h4,h5,h6)[id]",
+  )
+  return firstHeadingWithId?.id ?? ""
+}
+
+function anchorFromRange(root: HTMLElement, range: Range): TextQuoteAnchor | null {
+  const { text, segments } = collectSegments(root)
+  const start = pointOffset(segments, range.startContainer, range.startOffset)
+  const end = pointOffset(segments, range.endContainer, range.endOffset)
+  if (start === null || end === null || end <= start) return null
+  const exact = text.slice(start, end)
+  if (!exact.trim()) return null
+  return {
+    v: 1,
+    exact,
+    prefix: text.slice(Math.max(0, start - CONTEXT_LEN), start),
+    suffix: text.slice(end, Math.min(text.length, end + CONTEXT_LEN)),
+    start,
+    end,
+    slug: nearestHeadingSlug(range.startContainer),
+  }
+}
+
+// Locate the anchor's text in the current article, disambiguating repeated
+// matches by surrounding context and stored position. Returns null (→ orphan)
+// if the exact text is no longer present.
+function resolveAnchor(
+  text: string,
+  anchor: TextQuoteAnchor,
+): { start: number; end: number } | null {
+  const { exact, prefix, suffix } = anchor
+  if (!exact) return null
+
+  const occurrences: number[] = []
+  let i = text.indexOf(exact)
+  while (i !== -1) {
+    occurrences.push(i)
+    i = text.indexOf(exact, i + 1)
+  }
+  if (occurrences.length === 0) return null
+  if (occurrences.length === 1) {
+    return { start: occurrences[0], end: occurrences[0] + exact.length }
+  }
+
+  let best = occurrences[0]
+  let bestScore = -Infinity
+  for (const o of occurrences) {
+    let score = 0
+    if (prefix) {
+      const pfx = text.slice(Math.max(0, o - prefix.length), o)
+      if (pfx.endsWith(prefix)) score += 2
+      else if (prefix.length >= 4 && pfx.endsWith(prefix.slice(-4))) score += 1
+    }
+    if (suffix) {
+      const sfx = text.slice(o + exact.length, o + exact.length + suffix.length)
+      if (sfx.startsWith(suffix)) score += 2
+      else if (suffix.length >= 4 && sfx.startsWith(suffix.slice(0, 4))) score += 1
+    }
+    const closer = Math.abs(o - anchor.start) < Math.abs(best - anchor.start)
+    if (score > bestScore || (score === bestScore && closer)) {
+      best = o
+      bestScore = score
+    }
+  }
+  return { start: best, end: best + exact.length }
+}
+
+// Wrap [start, end) of the article text in <mark> elements (one per crossed
+// text node), tagging them with the group id and a comment count.
+function highlightRange(
+  root: HTMLElement,
+  start: number,
+  end: number,
+  groupId: string,
+  count: number,
+): HTMLElement[] {
+  const { segments } = collectSegments(root)
+  const marks: HTMLElement[] = []
+  for (const seg of segments) {
+    const s = Math.max(start, seg.start)
+    const e = Math.min(end, seg.end)
+    if (s >= e) continue
+    const range = document.createRange()
+    try {
+      range.setStart(seg.node, s - seg.start)
+      range.setEnd(seg.node, e - seg.start)
+      const mark = document.createElement("mark")
+      mark.className = "inline-comment-highlight"
+      mark.dataset.groupId = groupId
+      range.surroundContents(mark)
+      marks.push(mark)
+    } catch {
+      // range crosses an element boundary within this segment; skip it
+    }
+  }
+  if (count > 1 && marks.length > 0) {
+    const badge = document.createElement("span")
+    badge.className = "inline-comment-count"
+    badge.setAttribute("data-inline-comment-ignore", "")
+    badge.textContent = String(count)
+    marks[marks.length - 1].appendChild(badge)
+  }
+  return marks
+}
+
+// ─── comment body <-> anchor marker ─────────────────────────────────────
+
+function parseAnchor(body: string): TextQuoteAnchor | null {
+  const m = body.match(ANCHOR_RE)
+  if (!m) return null
+  try {
+    const parsed = JSON.parse(m[1]) as TextQuoteAnchor
+    return typeof parsed.exact === "string" ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+function formatBody(anchor: TextQuoteAnchor, prose: string): string {
+  const quote = anchor.exact
+    .split("\n")
+    .map((l) => "> " + l)
+    .join("\n")
+  const marker = `<!-- quartz-anchor: ${JSON.stringify(anchor)} -->`
+  return `${quote}\n\n${prose.trim()}\n\n${marker}`
+}
+
+// Strip the leading quote blockquote we injected so the thread UI doesn't
+// duplicate the highlighted text. GitHub already drops the HTML comment.
+function displayHTML(bodyHTML: string): string {
+  const tpl = document.createElement("template")
+  tpl.innerHTML = bodyHTML.trim()
+  const first = tpl.content.firstElementChild
+  if (first && first.tagName === "BLOCKQUOTE") first.remove()
+  return tpl.innerHTML
+}
+
+// ─── auth ───────────────────────────────────────────────────────────────
+
+function getToken(): string | null {
+  return localStorage.getItem(TOKEN_KEY)
+}
+
+function clearToken(): void {
+  localStorage.removeItem(TOKEN_KEY)
+}
+
+function randomState(): string {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID()
+  return Math.random().toString(36).slice(2) + Date.now().toString(36)
+}
+
+function login(cfg: Config): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const state = randomState()
+    sessionStorage.setItem(STATE_KEY, state)
+    const apiOrigin = new URL(cfg.apiBase).origin
+    const loginUrl =
+      `${cfg.apiBase}/api/auth/login?state=${encodeURIComponent(state)}` +
+      `&origin=${encodeURIComponent(location.origin)}`
+    const popup = window.open(loginUrl, "inline-comments-login", "width=600,height=720")
+    if (!popup) {
+      reject(new Error("popup blocked"))
+      return
+    }
+    const onMessage = (e: MessageEvent) => {
+      if (e.origin !== apiOrigin) return
+      const data = e.data as { type?: string; token?: string; state?: string }
+      if (data?.type !== "inline-comments-token") return
+      window.removeEventListener("message", onMessage)
+      if (data.state && data.state !== state) {
+        reject(new Error("oauth state mismatch"))
+        return
+      }
+      if (!data.token) {
+        reject(new Error("no token returned"))
+        return
+      }
+      localStorage.setItem(TOKEN_KEY, data.token)
+      resolve(data.token)
+    }
+    window.addEventListener("message", onMessage)
+  })
+}
+
+// ─── github i/o ─────────────────────────────────────────────────────────
+
+async function fetchComments(cfg: Config, term: string): Promise<CommentsResponse> {
+  const empty: CommentsResponse = { discussionId: null, discussionNumber: null, comments: [] }
+  if (!cfg.apiBase) return empty
+  const token = getToken()
+  const url =
+    `${cfg.apiBase}/api/comments?repo=${encodeURIComponent(cfg.repo)}` +
+    `&category=${encodeURIComponent(cfg.category)}&term=${encodeURIComponent(term)}`
+  try {
+    const res = await fetch(url, {
+      headers: token ? { Authorization: `Bearer ${token}` } : {},
+    })
+    if (!res.ok) return empty
+    return (await res.json()) as CommentsResponse
+  } catch {
+    return empty
+  }
+}
+
+async function graphql<T>(token: string, query: string, variables: object): Promise<T> {
+  const res = await fetch(GITHUB_GRAPHQL, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ query, variables }),
+  })
+  if (res.status === 401) {
+    clearToken()
+    throw new Error("GitHub session expired — please sign in again.")
+  }
+  const json = (await res.json()) as { data?: T; errors?: { message: string }[] }
+  if (json.errors?.length) throw new Error(json.errors[0].message)
+  if (!json.data) throw new Error("empty GraphQL response")
+  return json.data
+}
+
+const CREATE_DISCUSSION = `
+mutation ($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
+  createDiscussion(input: { repositoryId: $repoId, categoryId: $categoryId, title: $title, body: $body }) {
+    discussion { id }
+  }
+}`
+
+const ADD_COMMENT = `
+mutation ($discussionId: ID!, $body: String!, $replyToId: ID) {
+  addDiscussionComment(input: { discussionId: $discussionId, body: $body, replyToId: $replyToId }) {
+    comment { id url createdAt bodyHTML body author { login avatarUrl } }
+  }
+}`
+
+async function ensureDiscussion(
+  token: string,
+  cfg: Config,
+  term: string,
+  current: CommentsResponse,
+): Promise<string> {
+  if (current.discussionId) return current.discussionId
+  const data = await graphql<{ createDiscussion: { discussion: { id: string } } }>(
+    token,
+    CREATE_DISCUSSION,
+    {
+      repoId: cfg.repoId,
+      categoryId: cfg.categoryId,
+      title: term,
+      body: `Comments for \`${term}\``,
+    },
+  )
+  return data.createDiscussion.discussion.id
+}
+
+async function addComment(
+  token: string,
+  discussionId: string,
+  body: string,
+  replyToId?: string,
+): Promise<RawComment> {
+  const data = await graphql<{ addDiscussionComment: { comment: RawComment } }>(
+    token,
+    ADD_COMMENT,
+    {
+      discussionId,
+      body,
+      replyToId: replyToId ?? null,
+    },
+  )
+  return data.addDiscussionComment.comment
+}
+
+// ─── floating UI helpers ────────────────────────────────────────────────
+
+type Cleanup = () => void
+
+function anchorFloating(
+  reference: HTMLElement | { getBoundingClientRect: () => DOMRect },
+  floating: HTMLElement,
+): Cleanup {
+  return autoUpdate(reference as HTMLElement, floating, () => {
+    computePosition(reference as HTMLElement, floating, {
+      strategy: "fixed",
+      placement: "top",
+      middleware: [offset(8), flip(), shift({ padding: 8 })],
+    }).then(({ x, y }) => {
+      Object.assign(floating.style, { left: `${x}px`, top: `${y}px` })
+    })
+  })
+}
+
+function virtualRef(range: Range) {
+  return { getBoundingClientRect: () => range.getBoundingClientRect() }
+}
+
+// ─── main ───────────────────────────────────────────────────────────────
+
+function relTime(iso: string): string {
+  const then = new Date(iso).getTime()
+  const secs = Math.round((Date.now() - then) / 1000)
+  const units: [number, Intl.RelativeTimeFormatUnit][] = [
+    [60, "second"],
+    [60, "minute"],
+    [24, "hour"],
+    [30, "day"],
+    [12, "month"],
+    [Number.POSITIVE_INFINITY, "year"],
+  ]
+  let value = secs
+  let unit: Intl.RelativeTimeFormatUnit = "second"
+  for (const [size, u] of units) {
+    if (Math.abs(value) < size) {
+      unit = u
+      break
+    }
+    value = Math.round(value / size)
+    unit = u
+  }
+  return new Intl.RelativeTimeFormat(undefined, { numeric: "auto" }).format(-value, unit)
+}
+
+function commentItemEl(c: RawComment, isReply: boolean): HTMLElement {
+  const item = document.createElement("div")
+  item.className = isReply ? "inline-comment-item reply" : "inline-comment-item"
+
+  const meta = document.createElement("div")
+  meta.className = "inline-comment-meta"
+  const avatar = document.createElement("img")
+  avatar.src = c.author?.avatarUrl ?? ""
+  avatar.alt = c.author?.login ?? ""
+  const author = document.createElement("a")
+  author.className = "inline-comment-author"
+  author.textContent = c.author?.login ?? "unknown"
+  author.href = c.url
+  author.target = "_blank"
+  author.rel = "noopener noreferrer"
+  const date = document.createElement("span")
+  date.className = "inline-comment-date"
+  date.textContent = relTime(c.createdAt)
+  meta.append(avatar, author, date)
+
+  const body = document.createElement("div")
+  body.className = "inline-comment-body"
+  body.innerHTML = displayHTML(c.bodyHTML)
+
+  item.append(meta, body)
+  return item
+}
+
+class InlineComments {
+  private cfg: Config
+  private root: HTMLElement
+  private term: string
+  private state: CommentsResponse = { discussionId: null, discussionNumber: null, comments: [] }
+  private popover: HTMLElement | null = null
+  private popoverCleanups: Cleanup[] = []
+  // groupId -> comments sharing an identical resolved range
+  private groups = new Map<string, RawComment[]>()
+
+  constructor(cfg: Config, root: HTMLElement) {
+    this.cfg = cfg
+    this.root = root
+    this.term = getTerm(cfg)
+  }
+
+  // torn down by quartz's SPA router on the next navigation
+  registerCleanup(fn: Cleanup) {
+    window.addCleanup(fn)
+  }
+
+  async start() {
+    this.setupSelectionUI()
+    await this.render()
+  }
+
+  // ── rendering existing comments ──
+  async render() {
+    this.state = await fetchComments(this.cfg, this.term)
+    this.groups.clear()
+
+    const { text } = collectSegments(this.root)
+    type Placed = { key: string; start: number; end: number; comments: RawComment[] }
+    const placedByRange = new Map<string, Placed>()
+    const orphans: RawComment[] = []
+
+    for (const c of this.state.comments) {
+      const anchor = parseAnchor(c.body)
+      if (!anchor) continue // page-level comment → left to the giscus widget
+      const resolved = resolveAnchor(text, anchor)
+      if (!resolved) {
+        orphans.push(c)
+        continue
+      }
+      const key = `${resolved.start}:${resolved.end}`
+      const existing = placedByRange.get(key)
+      if (existing) existing.comments.push(c)
+      else placedByRange.set(key, { key, start: resolved.start, end: resolved.end, comments: [c] })
+    }
+
+    // wrap ranges last-first so earlier offsets are not invalidated
+    const placed = [...placedByRange.values()].sort((a, b) => b.start - a.start)
+    for (const p of placed) {
+      this.groups.set(p.key, p.comments)
+      const marks = highlightRange(this.root, p.start, p.end, p.key, p.comments.length)
+      for (const mark of marks) {
+        mark.addEventListener("click", (e) => {
+          e.preventDefault()
+          this.openThread(p.key, mark)
+        })
+      }
+    }
+
+    this.renderOrphans(orphans)
+  }
+
+  renderOrphans(orphans: RawComment[]) {
+    document.querySelector(".inline-comments-orphans")?.remove()
+    if (orphans.length === 0) return
+    const wrap = document.createElement("section")
+    wrap.className = "inline-comments-orphans"
+    const h = document.createElement("h3")
+    h.textContent = `Comments on earlier revisions (${orphans.length})`
+    wrap.appendChild(h)
+    for (const c of orphans) wrap.appendChild(commentItemEl(c, false))
+    this.root.after(wrap)
+    this.registerCleanup(() => wrap.remove())
+  }
+
+  // ── selection → add button ──
+  setupSelectionUI() {
+    const btn = document.createElement("button")
+    btn.className = "inline-comment-add"
+    btn.setAttribute("data-inline-comment-ignore", "")
+    btn.innerHTML =
+      `<svg viewBox="0 0 24 24" stroke-width="2"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>` +
+      `<span>Comment</span>`
+    btn.style.left = "0"
+    btn.style.top = "0"
+    document.body.appendChild(btn)
+    this.registerCleanup(() => btn.remove())
+
+    let pendingRange: Range | null = null
+    let btnCleanup: Cleanup | null = null
+
+    const hide = () => {
+      btn.classList.remove("visible")
+      btnCleanup?.()
+      btnCleanup = null
+    }
+
+    const onSelect = () => {
+      const sel = window.getSelection()
+      if (!sel || sel.isCollapsed || sel.rangeCount === 0) return hide()
+      const range = sel.getRangeAt(0)
+      if (!this.root.contains(range.commonAncestorContainer) || !range.toString().trim()) {
+        return hide()
+      }
+      pendingRange = range.cloneRange()
+      btnCleanup?.()
+      btnCleanup = anchorFloating(virtualRef(range), btn)
+      btn.classList.add("visible")
+    }
+
+    const onDocMouseDown = (e: MouseEvent) => {
+      if (e.target instanceof Node && (btn.contains(e.target) || this.popover?.contains(e.target)))
+        return
+      // let the browser update the selection first
+      setTimeout(() => {
+        const sel = window.getSelection()
+        if (!sel || sel.isCollapsed) hide()
+      }, 0)
+    }
+
+    btn.addEventListener("mousedown", (e) => e.preventDefault())
+    btn.addEventListener("click", () => {
+      if (pendingRange) this.openComposer(pendingRange)
+      hide()
+    })
+    document.addEventListener("mouseup", onSelect)
+    document.addEventListener("mousedown", onDocMouseDown)
+    this.registerCleanup(() => {
+      document.removeEventListener("mouseup", onSelect)
+      document.removeEventListener("mousedown", onDocMouseDown)
+      btnCleanup?.()
+    })
+  }
+
+  // ── popover plumbing ──
+  private closePopover() {
+    this.popoverCleanups.forEach((fn) => fn())
+    this.popoverCleanups = []
+    this.popover?.remove()
+    this.popover = null
+  }
+
+  private openPopover(
+    reference: HTMLElement | { getBoundingClientRect: () => DOMRect },
+    build: (el: HTMLElement) => void,
+  ) {
+    this.closePopover()
+    const el = document.createElement("div")
+    el.className = "inline-comment-popover"
+    el.setAttribute("data-inline-comment-ignore", "")
+    build(el)
+    document.body.appendChild(el)
+    this.popover = el
+    this.popoverCleanups.push(anchorFloating(reference, el))
+
+    const onOutside = (e: MouseEvent) => {
+      if (e.target instanceof Node && !el.contains(e.target)) this.closePopover()
+    }
+    setTimeout(() => document.addEventListener("mousedown", onOutside), 0)
+    this.popoverCleanups.push(() => document.removeEventListener("mousedown", onOutside))
+
+    // ensure the popover is also cleaned up if the user navigates away
+    this.registerCleanup(() => this.closePopover())
+  }
+
+  private quoteEl(exact: string): HTMLElement {
+    const q = document.createElement("blockquote")
+    q.className = "inline-comment-quote"
+    q.textContent = exact
+    return q
+  }
+
+  private composerEl(
+    submitLabel: string,
+    onSubmit: (text: string, setBusy: (b: boolean) => void) => void,
+  ): HTMLElement {
+    const composer = document.createElement("div")
+    composer.className = "inline-comment-composer"
+    const textarea = document.createElement("textarea")
+    textarea.placeholder = getToken()
+      ? "Add a comment…"
+      : "Add a comment… (you'll sign in with GitHub to post)"
+    const actions = document.createElement("div")
+    actions.className = "inline-comment-actions"
+    const hint = document.createElement("span")
+    hint.className = "inline-comment-hint"
+    const submit = document.createElement("button")
+    submit.className = "inline-comment-submit"
+    submit.textContent = submitLabel
+    submit.disabled = true
+
+    const setBusy = (b: boolean) => {
+      submit.disabled = b || textarea.value.trim().length === 0
+      submit.textContent = b ? "Posting…" : submitLabel
+    }
+    textarea.addEventListener("input", () => {
+      submit.disabled = textarea.value.trim().length === 0
+    })
+    submit.addEventListener("click", () => {
+      const text = textarea.value.trim()
+      if (text) onSubmit(text, setBusy)
+    })
+    const showHint = (msg: string) => (hint.textContent = msg)
+    ;(composer as HTMLElement & { showHint?: (m: string) => void }).showHint = showHint
+
+    actions.append(hint, submit)
+    composer.append(textarea, actions)
+    return composer
+  }
+
+  // ── new comment on a fresh selection ──
+  private openComposer(range: Range) {
+    const anchor = anchorFromRange(this.root, range)
+    if (!anchor) return
+    this.openPopover(virtualRef(range), (el) => {
+      el.appendChild(this.quoteEl(anchor.exact))
+      const composer = this.composerEl("Comment", async (text, setBusy) => {
+        setBusy(true)
+        try {
+          const token = getToken() ?? (await login(this.cfg))
+          const discussionId = await ensureDiscussion(token, this.cfg, this.term, this.state)
+          this.state.discussionId = discussionId
+          await addComment(token, discussionId, formatBody(anchor, text))
+          this.closePopover()
+          await this.render()
+        } catch (err) {
+          setBusy(false)
+          const showHint = (composer as HTMLElement & { showHint?: (m: string) => void }).showHint
+          showHint?.(err instanceof Error ? err.message : "Failed to post comment.")
+        }
+      })
+      el.appendChild(composer)
+    })
+  }
+
+  // ── existing thread on a highlight ──
+  private openThread(groupId: string, mark: HTMLElement) {
+    const comments = this.groups.get(groupId) ?? []
+    if (comments.length === 0) return
+    const anchor = parseAnchor(comments[0].body)
+
+    this.openPopover(mark, (el) => {
+      if (anchor) el.appendChild(this.quoteEl(anchor.exact))
+      const thread = document.createElement("div")
+      thread.className = "inline-comment-thread"
+      for (const c of comments) {
+        thread.appendChild(commentItemEl(c, false))
+        for (const r of c.replies ?? []) thread.appendChild(commentItemEl(r, true))
+      }
+      el.appendChild(thread)
+
+      const replyTo = comments[0]
+      const composer = this.composerEl("Reply", async (text, setBusy) => {
+        setBusy(true)
+        try {
+          const token = getToken() ?? (await login(this.cfg))
+          const discussionId = this.state.discussionId
+          if (!discussionId) throw new Error("missing discussion")
+          await addComment(token, discussionId, text, replyTo.id)
+          this.closePopover()
+          await this.render()
+        } catch (err) {
+          setBusy(false)
+          const showHint = (composer as HTMLElement & { showHint?: (m: string) => void }).showHint
+          showHint?.(err instanceof Error ? err.message : "Failed to post reply.")
+        }
+      })
+      el.appendChild(composer)
+    })
+  }
+}
+
+// ─── lifecycle ──────────────────────────────────────────────────────────
+
+document.addEventListener("nav", () => {
+  const container = document.querySelector(".inline-comments") as HTMLElement | null
+  const root = getRoot()
+  if (!container || !root) return
+  const cfg = readConfig(container)
+  if (!cfg.apiBase) return // graceful no-op until the worker is deployed
+  const app = new InlineComments(cfg, root)
+  void app.start()
+})
diff --git a/quartz/components/styles/inlineComments.scss b/quartz/components/styles/inlineComments.scss
new file mode 100644
index 0000000..3705ad8
--- /dev/null
+++ b/quartz/components/styles/inlineComments.scss
@@ -0,0 +1,227 @@
+@use "../../styles/variables.scss" as *;
+
+// ─── anchored highlight in the article body ─────────────────────────────
+.inline-comment-highlight {
+  background-color: color-mix(in srgb, var(--tertiary) 25%, rgba(255, 255, 255, 0));
+  border-bottom: 2px solid var(--tertiary);
+  cursor: pointer;
+  border-radius: 2px;
+  transition:
+    background-color 0.2s ease,
+    border-color 0.2s ease;
+
+  &:hover,
+  &.active {
+    background-color: color-mix(in srgb, var(--tertiary) 45%, rgba(255, 255, 255, 0));
+  }
+
+  // a small superscript count of comments on this range
+  & > .inline-comment-count {
+    font-size: 0.6rem;
+    vertical-align: super;
+    line-height: 0;
+    margin-left: 1px;
+    padding: 0 3px;
+    border-radius: 6px;
+    background-color: var(--tertiary);
+    color: var(--light);
+    user-select: none;
+  }
+}
+
+// ─── floating "add comment" button that follows a selection ─────────────
+.inline-comment-add {
+  position: absolute;
+  z-index: 998;
+  display: flex;
+  align-items: center;
+  gap: 0.3rem;
+  padding: 0.35rem 0.6rem;
+  font-family: var(--bodyFont);
+  font-size: 0.8rem;
+  color: var(--light);
+  background-color: var(--secondary);
+  border: none;
+  border-radius: 5px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+  cursor: pointer;
+  opacity: 0;
+  transform: translateY(4px);
+  transition:
+    opacity 0.12s ease,
+    transform 0.12s ease;
+
+  &.visible {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
+  & > svg {
+    width: 0.9rem;
+    height: 0.9rem;
+    stroke: currentColor;
+    fill: none;
+  }
+}
+
+// ─── shared popover shell (composer + thread) ───────────────────────────
+.inline-comment-popover {
+  position: fixed;
+  z-index: 999;
+  left: 0;
+  top: 0;
+  width: 22rem;
+  max-width: calc(100vw - 2rem);
+  max-height: 24rem;
+  display: flex;
+  flex-direction: column;
+  font-family: var(--bodyFont);
+  font-size: 0.85rem;
+  color: var(--darkgray);
+  background-color: var(--light);
+  border: 1px solid var(--lightgray);
+  border-radius: 6px;
+  box-shadow: 6px 6px 36px 0 rgba(0, 0, 0, 0.25);
+  overflow: hidden;
+
+  & .inline-comment-quote {
+    margin: 0.75rem 0.75rem 0;
+    padding: 0.35rem 0.5rem;
+    border-left: 3px solid var(--tertiary);
+    background-color: color-mix(in srgb, var(--tertiary) 12%, rgba(255, 255, 255, 0));
+    font-style: italic;
+    color: var(--gray);
+    font-size: 0.8rem;
+    max-height: 4rem;
+    overflow: auto;
+  }
+
+  & .inline-comment-thread {
+    padding: 0.5rem 0.75rem;
+    overflow-y: auto;
+    overscroll-behavior: contain;
+  }
+
+  & .inline-comment-item {
+    padding: 0.5rem 0;
+    border-bottom: 1px solid var(--lightgray);
+
+    &:last-child {
+      border-bottom: none;
+    }
+
+    & .inline-comment-meta {
+      display: flex;
+      align-items: center;
+      gap: 0.4rem;
+      margin-bottom: 0.25rem;
+
+      & img {
+        width: 1.1rem;
+        height: 1.1rem;
+        border-radius: 50%;
+      }
+
+      & .inline-comment-author {
+        font-weight: 600;
+        color: var(--dark);
+      }
+
+      & .inline-comment-date {
+        color: var(--gray);
+        font-size: 0.75rem;
+      }
+    }
+
+    & .inline-comment-body {
+      margin: 0;
+      line-height: 1.4;
+
+      & p {
+        margin: 0 0 0.4rem;
+      }
+      & p:last-child {
+        margin-bottom: 0;
+      }
+    }
+
+    // nested replies are indented
+    &.reply {
+      margin-left: 1rem;
+      border-left: 2px solid var(--lightgray);
+      padding-left: 0.5rem;
+      border-bottom: none;
+    }
+  }
+
+  // composer / reply box
+  & .inline-comment-composer {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    padding: 0.75rem;
+    border-top: 1px solid var(--lightgray);
+
+    & textarea {
+      resize: vertical;
+      min-height: 3.5rem;
+      padding: 0.4rem 0.5rem;
+      font-family: var(--bodyFont);
+      font-size: 0.85rem;
+      color: var(--darkgray);
+      background-color: var(--light);
+      border: 1px solid var(--lightgray);
+      border-radius: 4px;
+
+      &:focus {
+        outline: none;
+        border-color: var(--secondary);
+      }
+    }
+
+    & .inline-comment-actions {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 0.5rem;
+    }
+  }
+
+  & button.inline-comment-submit {
+    padding: 0.35rem 0.75rem;
+    font-family: var(--bodyFont);
+    font-size: 0.8rem;
+    color: var(--light);
+    background-color: var(--secondary);
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+
+    &:disabled {
+      opacity: 0.5;
+      cursor: default;
+    }
+  }
+
+  & .inline-comment-hint {
+    font-size: 0.75rem;
+    color: var(--gray);
+  }
+}
+
+// ─── orphaned-comment fallback list under the article ───────────────────
+.inline-comments-orphans {
+  margin-top: 1.5rem;
+
+  & > h3 {
+    font-size: 1rem;
+    margin: 0 0 0.5rem;
+  }
+
+  & .inline-comment-item {
+    border: 1px solid var(--lightgray);
+    border-radius: 5px;
+    padding: 0.5rem 0.75rem;
+    margin-bottom: 0.5rem;
+  }
+}
diff --git a/serverless/inline-comments-worker/.dev.vars.example b/serverless/inline-comments-worker/.dev.vars.example
new file mode 100644
index 0000000..3a0f9ea
--- /dev/null
+++ b/serverless/inline-comments-worker/.dev.vars.example
@@ -0,0 +1,4 @@
+# Copy to `.dev.vars` for local `wrangler dev` (git-ignored).
+GITHUB_CLIENT_ID=your_oauth_app_client_id
+GITHUB_CLIENT_SECRET=your_oauth_app_client_secret
+GITHUB_TOKEN=your_fine_grained_pat_with_discussions_read
diff --git a/serverless/inline-comments-worker/README.md b/serverless/inline-comments-worker/README.md
new file mode 100644
index 0000000..fe69635
--- /dev/null
+++ b/serverless/inline-comments-worker/README.md
@@ -0,0 +1,89 @@
+# Inline Comments Worker
+
+The one serverless piece behind Quartz [inline comments](../../docs-internal/inline-comments-design.md).
+It does three things and holds the two secrets that can't live in the browser:
+
+| Route | Purpose |
+|-------|---------|
+| `GET /api/auth/login` | Redirect to GitHub's OAuth authorize URL |
+| `GET /api/auth/callback` | Exchange `code` → user token, `postMessage` it back to the opener |
+| `GET /api/comments` | Anonymous read proxy (server token) so logged-out visitors see highlights |
+
+**Writes never touch this worker** — the browser posts comments straight to
+GitHub's GraphQL API with the signed-in user's own token.
+
+## 1. Create a GitHub OAuth App
+
+<https://github.com/settings/developers> → **New OAuth App**
+
+- **Homepage URL:** your site, e.g. `https://assembly.logos.co`
+- **Authorization callback URL:** `https://<your-worker-domain>/api/auth/callback`
+
+Copy the **Client ID** and generate a **Client secret**.
+
+> Scope requested is `public_repo` — enough to comment on Discussions of a
+> public repo. For a stricter setup use a GitHub **App** with fine-grained
+> Discussion write (a follow-up in the design doc).
+
+## 2. Create the server read token
+
+A **fine-grained PAT** (<https://github.com/settings/tokens?type=beta>) with
+**read** access to the repo's Discussions. This lets anonymous visitors load
+existing comments. Store it as `GITHUB_TOKEN`.
+
+## 3. Configure & deploy (Cloudflare Workers)
+
+```sh
+cd serverless/inline-comments-worker
+npm install
+
+# set the allowed site origin(s)
+#   edit wrangler.toml → [vars] ALLOWED_ORIGINS = "https://assembly.logos.co"
+
+# secrets
+wrangler secret put GITHUB_CLIENT_ID
+wrangler secret put GITHUB_CLIENT_SECRET
+wrangler secret put GITHUB_TOKEN
+
+wrangler deploy
+```
+
+Deploy prints the worker URL (e.g. `https://inline-comments.<you>.workers.dev`).
+
+### Local dev
+
+```sh
+cp .dev.vars.example .dev.vars   # fill in the three secrets
+npm run dev                      # serves on http://localhost:8787
+```
+
+Keep `ALLOWED_ORIGINS = "http://localhost:8080"` (Quartz's dev server) while testing.
+
+## 4. Point Quartz at the worker
+
+In `quartz.layout.ts`:
+
+```ts
+Component.InlineComments({
+  provider: "github",
+  options: {
+    repo: "logos-co/assembly",
+    repoId: "R_kgDOQUhKqA",
+    category: "Announcements",
+    categoryId: "DIC_kwDOQUhKqM4Cxur2",
+    apiBase: "https://inline-comments.<you>.workers.dev",
+    mapping: "pathname",
+  },
+})
+```
+
+If `apiBase` is empty the component no-ops, so it's safe to land before the
+worker exists.
+
+## Notes / limits
+
+- Comments + replies are fetched 100-at-a-time (no pagination yet).
+- `mapping` must match on read and write. To share the *same* discussion as the
+  existing giscus widget, use the mapping giscus is configured with.
+- Ports to Vercel/Netlify functions are straightforward — the handler is a
+  single `fetch(request, env)`; only the deploy wrapper changes.
diff --git a/serverless/inline-comments-worker/package.json b/serverless/inline-comments-worker/package.json
new file mode 100644
index 0000000..9b19055
--- /dev/null
+++ b/serverless/inline-comments-worker/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "inline-comments-worker",
+  "version": "0.1.0",
+  "private": true,
+  "description": "OAuth exchange + anonymous read proxy for Quartz inline comments",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241106.0",
+    "typescript": "^5.6.0",
+    "wrangler": "^3.86.0"
+  }
+}
diff --git a/serverless/inline-comments-worker/src/index.ts b/serverless/inline-comments-worker/src/index.ts
new file mode 100644
index 0000000..96f7e38
--- /dev/null
+++ b/serverless/inline-comments-worker/src/index.ts
@@ -0,0 +1,282 @@
+// Inline Comments worker — the only non-static piece of the system.
+//
+// Endpoints:
+//   GET /api/auth/login?state=&origin=   → 302 to GitHub's OAuth authorize URL
+//   GET /api/auth/callback?code=&state=  → exchange code → postMessage token to opener
+//   GET /api/comments?repo=&category=&term=
+//                                        → anonymous read proxy (server token) so
+//                                          logged-out visitors can see highlights
+//
+// Secrets (wrangler secret put ...):
+//   GITHUB_CLIENT_ID       OAuth App client id
+//   GITHUB_CLIENT_SECRET   OAuth App client secret
+//   GITHUB_TOKEN           server read token (fine-grained PAT: Discussions read)
+// Vars (wrangler.toml [vars]):
+//   ALLOWED_ORIGINS        comma-separated site origins, e.g. "https://assembly.logos.co"
+
+export interface Env {
+  GITHUB_CLIENT_ID: string
+  GITHUB_CLIENT_SECRET: string
+  GITHUB_TOKEN: string
+  ALLOWED_ORIGINS: string
+}
+
+const GITHUB_GRAPHQL = "https://api.github.com/graphql"
+const USER_AGENT = "quartz-inline-comments"
+
+// ─── helpers ──────────────────────────────────────────────────────────────
+
+function allowedOrigins(env: Env): string[] {
+  return (env.ALLOWED_ORIGINS ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+function isAllowed(origin: string, env: Env): boolean {
+  const list = allowedOrigins(env)
+  return list.includes("*") || list.includes(origin)
+}
+
+function corsHeaders(origin: string, env: Env): Record<string, string> {
+  const allow = isAllowed(origin, env) ? origin : (allowedOrigins(env)[0] ?? "")
+  return {
+    "Access-Control-Allow-Origin": allow,
+    "Access-Control-Allow-Headers": "Authorization, Content-Type",
+    "Access-Control-Allow-Methods": "GET, OPTIONS",
+    Vary: "Origin",
+  }
+}
+
+function json(data: unknown, status: number, extra: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json", ...extra },
+  })
+}
+
+function b64urlEncode(s: string): string {
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+function b64urlDecode(s: string): string {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4))
+  return atob(s.replace(/-/g, "+").replace(/_/g, "/") + pad)
+}
+
+async function githubGraphQL<T>(token: string, query: string, variables: object): Promise<T> {
+  const res = await fetch(GITHUB_GRAPHQL, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT,
+    },
+    body: JSON.stringify({ query, variables }),
+  })
+  const body = (await res.json()) as { data?: T; errors?: { message: string }[] }
+  if (body.errors?.length) throw new Error(body.errors[0].message)
+  if (!body.data) throw new Error("empty GraphQL response")
+  return body.data
+}
+
+// ─── auth: login ────────────────────────────────────────────────────────
+
+function handleLogin(url: URL, env: Env): Response {
+  const clientState = url.searchParams.get("state") ?? ""
+  const origin = url.searchParams.get("origin") ?? ""
+  if (!isAllowed(origin, env)) return new Response("origin not allowed", { status: 403 })
+
+  const ghState = b64urlEncode(JSON.stringify({ cs: clientState, o: origin }))
+  const redirectUri = `${url.origin}/api/auth/callback`
+  const authorize = new URL("https://github.com/login/oauth/authorize")
+  authorize.searchParams.set("client_id", env.GITHUB_CLIENT_ID)
+  authorize.searchParams.set("redirect_uri", redirectUri)
+  authorize.searchParams.set("scope", "public_repo")
+  authorize.searchParams.set("state", ghState)
+  authorize.searchParams.set("allow_signup", "true")
+  return Response.redirect(authorize.toString(), 302)
+}
+
+// ─── auth: callback ───────────────────────────────────────────────────────
+
+function callbackPage(token: string, clientState: string, origin: string): Response {
+  // JSON-encode + neutralize "</script>" so nothing can break out of the tag.
+  const payload = JSON.stringify({
+    type: "inline-comments-token",
+    token,
+    state: clientState,
+  }).replace(/</g, "\\u003c")
+  const targetOrigin = JSON.stringify(origin).replace(/</g, "\\u003c")
+  const html = `<!doctype html><meta charset="utf-8"><title>Signing in…</title>
+<body style="font-family:sans-serif;padding:2rem">Signing you in…
+<script>
+(function () {
+  var msg = ${payload};
+  if (window.opener) { window.opener.postMessage(msg, ${targetOrigin}); }
+  window.close();
+})();
+</script></body>`
+  return new Response(html, { headers: { "Content-Type": "text/html; charset=utf-8" } })
+}
+
+async function handleCallback(url: URL, env: Env): Promise<Response> {
+  const code = url.searchParams.get("code")
+  const ghState = url.searchParams.get("state") ?? ""
+  let clientState = ""
+  let origin = ""
+  try {
+    const parsed = JSON.parse(b64urlDecode(ghState)) as { cs: string; o: string }
+    clientState = parsed.cs
+    origin = parsed.o
+  } catch {
+    return new Response("invalid state", { status: 400 })
+  }
+  if (!code || !isAllowed(origin, env)) return new Response("bad request", { status: 400 })
+
+  const res = await fetch("https://github.com/login/oauth/access_token", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+    },
+    body: JSON.stringify({
+      client_id: env.GITHUB_CLIENT_ID,
+      client_secret: env.GITHUB_CLIENT_SECRET,
+      code,
+      redirect_uri: `${url.origin}/api/auth/callback`,
+    }),
+  })
+  const tokenJson = (await res.json()) as { access_token?: string; error?: string }
+  if (!tokenJson.access_token) {
+    return new Response(`oauth error: ${tokenJson.error ?? "unknown"}`, { status: 400 })
+  }
+  return callbackPage(tokenJson.access_token, clientState, origin)
+}
+
+// ─── read proxy: comments ──────────────────────────────────────────────────
+
+type GHComment = {
+  id: string
+  url: string
+  createdAt: string
+  bodyHTML: string
+  body: string
+  author: { login: string; avatarUrl: string } | null
+  replies?: { nodes: GHComment[] }
+}
+
+type GHDiscussion = {
+  id: string
+  number: number
+  title: string
+  category: { name: string }
+  comments: { nodes: GHComment[] }
+}
+
+const SEARCH_DISCUSSION = `
+query ($q: String!) {
+  search(query: $q, type: DISCUSSION, first: 10) {
+    nodes {
+      ... on Discussion {
+        id
+        number
+        title
+        category { name }
+        comments(first: 100) {
+          nodes {
+            id url createdAt bodyHTML body
+            author { login avatarUrl }
+            replies(first: 100) {
+              nodes { id url createdAt bodyHTML body author { login avatarUrl } }
+            }
+          }
+        }
+      }
+    }
+  }
+}`
+
+function mapComment(c: GHComment): unknown {
+  return {
+    id: c.id,
+    url: c.url,
+    createdAt: c.createdAt,
+    bodyHTML: c.bodyHTML,
+    body: c.body,
+    author: c.author ?? { login: "ghost", avatarUrl: "" },
+    replies: (c.replies?.nodes ?? []).map(mapComment),
+  }
+}
+
+async function handleComments(request: Request, url: URL, env: Env): Promise<Response> {
+  const origin = request.headers.get("Origin") ?? ""
+  const cors = corsHeaders(origin, env)
+
+  const repo = url.searchParams.get("repo") ?? ""
+  const category = url.searchParams.get("category") ?? ""
+  const term = url.searchParams.get("term") ?? ""
+  const [owner, name] = repo.split("/")
+  if (!owner || !name || !term) return json({ error: "missing repo/term" }, 400, cors)
+
+  // A logged-in reader may pass their own token; else use the server token.
+  const authHeader = request.headers.get("Authorization")
+  const token =
+    authHeader && authHeader.startsWith("Bearer ") ? authHeader.slice(7) : env.GITHUB_TOKEN
+  if (!token) return json({ error: "no token configured" }, 500, cors)
+
+  const q = `repo:${owner}/${name} in:title "${term.replace(/"/g, "")}"`
+  try {
+    const data = await githubGraphQL<{ search: { nodes: GHDiscussion[] } }>(
+      token,
+      SEARCH_DISCUSSION,
+      {
+        q,
+      },
+    )
+    const match = data.search.nodes.find(
+      (d) => d && d.title === term && (!category || d.category?.name === category),
+    )
+    if (!match) {
+      return json({ discussionId: null, discussionNumber: null, comments: [] }, 200, cors)
+    }
+    return json(
+      {
+        discussionId: match.id,
+        discussionNumber: match.number,
+        comments: match.comments.nodes.map(mapComment),
+      },
+      200,
+      cors,
+    )
+  } catch (err) {
+    return json({ error: err instanceof Error ? err.message : "read failed" }, 502, cors)
+  }
+}
+
+// ─── router ─────────────────────────────────────────────────────────────
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url)
+
+    if (request.method === "OPTIONS") {
+      return new Response(null, {
+        status: 204,
+        headers: corsHeaders(request.headers.get("Origin") ?? "", env),
+      })
+    }
+
+    switch (url.pathname) {
+      case "/api/auth/login":
+        return handleLogin(url, env)
+      case "/api/auth/callback":
+        return handleCallback(url, env)
+      case "/api/comments":
+        return handleComments(request, url, env)
+      default:
+        return new Response("not found", { status: 404 })
+    }
+  },
+}
diff --git a/serverless/inline-comments-worker/tsconfig.json b/serverless/inline-comments-worker/tsconfig.json
new file mode 100644
index 0000000..b105b2f
--- /dev/null
+++ b/serverless/inline-comments-worker/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "lib": ["esnext"],
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}
diff --git a/serverless/inline-comments-worker/wrangler.toml b/serverless/inline-comments-worker/wrangler.toml
new file mode 100644
index 0000000..d2cacac
--- /dev/null
+++ b/serverless/inline-comments-worker/wrangler.toml
@@ -0,0 +1,13 @@
+name = "inline-comments"
+main = "src/index.ts"
+compatibility_date = "2024-11-01"
+
+# Public site origin(s) allowed to use this worker (comma-separated).
+# Used for CORS on /api/comments and as the postMessage target on auth callback.
+[vars]
+ALLOWED_ORIGINS = "http://localhost:8080"
+
+# Secrets are NOT set here. Set them with:
+#   wrangler secret put GITHUB_CLIENT_ID
+#   wrangler secret put GITHUB_CLIENT_SECRET
+#   wrangler secret put GITHUB_TOKEN

From b10fe49b609f30f354dbb9826319c529d313eb61 Mon Sep 17 00:00:00 2001
From: Corey Petty <corey@status.im>
Date: Mon, 20 Jul 2026 10:16:38 -0400
Subject: [PATCH 2/6] Wire inline comments to deployed worker; harden secret
 handling

Connects the InlineComments component to the live Cloudflare worker and
fixes a gap that left OAuth secrets uncovered by gitignore.

- quartz.layout.ts: point apiBase at the deployed worker so the client
  engine activates (it no-ops on an empty apiBase)
- wrangler.toml: allow the production origin (logos-co.github.io) alongside
  the local dev server. [vars] need a redeploy to take effect; secrets do not
- .gitignore: protect .dev.vars and .wrangler/ from the repo root. The root
  ignore file excludes all nested .gitignore files, so the worker's own
  ignore rules were never tracked and did not survive a fresh clone
- worker README: reorder to deploy-first, since the OAuth callback URL
  contains the worker URL, which does not exist until after deploy

Verified against the deployed worker: routing, token/client-id bindings,
origin allowlist (allow + deny), and callback state validation.
Untested: GITHUB_CLIENT_SECRET, which needs a real browser OAuth round-trip.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .gitignore                                    |    5 +
 quartz.layout.ts                              |    2 +-
 serverless/inline-comments-worker/README.md   |  103 +-
 .../inline-comments-worker/package-lock.json  | 1606 +++++++++++++++++
 .../inline-comments-worker/wrangler.toml      |    5 +-
 5 files changed, 1681 insertions(+), 40 deletions(-)
 create mode 100644 serverless/inline-comments-worker/package-lock.json

diff --git a/.gitignore b/.gitignore
index 5d57c9a..564ab1e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,8 @@ private/
 .replit
 replit.nix
 .gitnexus
+
+# serverless worker secrets (nested .gitignore files are ignored by line 2,
+# so these rules must live here to travel with the repo)
+.dev.vars
+.wrangler/
diff --git a/quartz.layout.ts b/quartz.layout.ts
index af179f3..2919f9c 100644
--- a/quartz.layout.ts
+++ b/quartz.layout.ts
@@ -31,7 +31,7 @@ export const sharedPageComponents: SharedLayout = {
         repoId: "R_kgDOQUhKqA",
         category: "Announcements",
         categoryId: "DIC_kwDOQUhKqM4Cxur2",
-        apiBase: "", // e.g. "https://inline-comments.<you>.workers.dev"
+        apiBase: "https://inline-comments.inline-assembly.workers.dev",
         mapping: "url", // match giscus's mapping to share the same discussion
       },
     }),
diff --git a/serverless/inline-comments-worker/README.md b/serverless/inline-comments-worker/README.md
index fe69635..8003d80 100644
--- a/serverless/inline-comments-worker/README.md
+++ b/serverless/inline-comments-worker/README.md
@@ -3,61 +3,88 @@
 The one serverless piece behind Quartz [inline comments](../../docs-internal/inline-comments-design.md).
 It does three things and holds the two secrets that can't live in the browser:
 
-| Route | Purpose |
-|-------|---------|
-| `GET /api/auth/login` | Redirect to GitHub's OAuth authorize URL |
-| `GET /api/auth/callback` | Exchange `code` → user token, `postMessage` it back to the opener |
-| `GET /api/comments` | Anonymous read proxy (server token) so logged-out visitors see highlights |
+| Route                    | Purpose                                                                   |
+| ------------------------ | ------------------------------------------------------------------------- |
+| `GET /api/auth/login`    | Redirect to GitHub's OAuth authorize URL                                  |
+| `GET /api/auth/callback` | Exchange `code` → user token, `postMessage` it back to the opener         |
+| `GET /api/comments`      | Anonymous read proxy (server token) so logged-out visitors see highlights |
 
 **Writes never touch this worker** — the browser posts comments straight to
 GitHub's GraphQL API with the signed-in user's own token.
 
-## 1. Create a GitHub OAuth App
+> **Order matters.** The OAuth App's callback URL must contain the worker's
+> URL, and the worker's URL doesn't exist until it's deployed — so deploy
+> first. Deploying without secrets is fine; those endpoints simply error until
+> you add them.
 
-<https://github.com/settings/developers> → **New OAuth App**
-
-- **Homepage URL:** your site, e.g. `https://assembly.logos.co`
-- **Authorization callback URL:** `https://<your-worker-domain>/api/auth/callback`
-
-Copy the **Client ID** and generate a **Client secret**.
-
-> Scope requested is `public_repo` — enough to comment on Discussions of a
-> public repo. For a stricter setup use a GitHub **App** with fine-grained
-> Discussion write (a follow-up in the design doc).
-
-## 2. Create the server read token
-
-A **fine-grained PAT** (<https://github.com/settings/tokens?type=beta>) with
-**read** access to the repo's Discussions. This lets anonymous visitors load
-existing comments. Store it as `GITHUB_TOKEN`.
-
-## 3. Configure & deploy (Cloudflare Workers)
+## 1. Deploy the worker (Cloudflare Workers)
 
 ```sh
 cd serverless/inline-comments-worker
 npm install
-
-# set the allowed site origin(s)
-#   edit wrangler.toml → [vars] ALLOWED_ORIGINS = "https://assembly.logos.co"
-
-# secrets
-wrangler secret put GITHUB_CLIENT_ID
-wrangler secret put GITHUB_CLIENT_SECRET
-wrangler secret put GITHUB_TOKEN
-
-wrangler deploy
+npx wrangler login     # first run also prompts you to pick your workers.dev subdomain
+npx wrangler deploy    # prints the URL
 ```
 
-Deploy prints the worker URL (e.g. `https://inline-comments.<you>.workers.dev`).
+The printed URL is `https://<name>.<your-subdomain>.workers.dev`, where `<name>`
+is `name` in `wrangler.toml`. For this repo it is:
+
+```
+https://inline-comments.inline-assembly.workers.dev
+```
+
+## 2. Create a GitHub OAuth App
+
+<https://github.com/settings/developers> → **New OAuth App**
+
+- **Homepage URL:** the site, `https://logos-co.github.io/assembly/`
+- **Authorization callback URL:** the worker URL + `/api/auth/callback`, i.e.
+  `https://inline-comments.inline-assembly.workers.dev/api/auth/callback`
+
+Register, copy the **Client ID**, then **Generate a new client secret** and copy
+it immediately (shown once).
+
+An OAuth App allows only **one** callback URL, so register a **second app** for
+local dev with callback `http://localhost:8787/api/auth/callback`.
+
+> Scope requested is `public_repo` — enough to comment on Discussions of a
+> public repo. For a stricter setup use a GitHub **App** with fine-grained
+> Discussion write (a follow-up in the design doc).
+>
+> `logos-co` is an org: if it enforces third-party application restrictions, an
+> owner must approve the app or posting will fail for members. Registering the
+> app **under the org** (Org Settings → Developer settings → OAuth Apps) avoids
+> tying ownership to one person's account.
+
+## 3. Create the server read token
+
+A **fine-grained PAT** (<https://github.com/settings/tokens?type=beta>) scoped to
+`logos-co/assembly` with **Discussions: read**. This lets anonymous visitors load
+existing comments. Store it as `GITHUB_TOKEN`.
+
+## 4. Set secrets and origins
+
+```sh
+npx wrangler secret put GITHUB_CLIENT_ID
+npx wrangler secret put GITHUB_CLIENT_SECRET
+npx wrangler secret put GITHUB_TOKEN
+```
+
+Secrets apply immediately. `ALLOWED_ORIGINS` lives in `wrangler.toml` `[vars]`
+and **requires a redeploy** to take effect:
+
+```sh
+npx wrangler deploy
+```
 
 ### Local dev
 
 ```sh
-cp .dev.vars.example .dev.vars   # fill in the three secrets
+cp .dev.vars.example .dev.vars   # fill in the three secrets (git-ignored)
 npm run dev                      # serves on http://localhost:8787
 ```
 
-Keep `ALLOWED_ORIGINS = "http://localhost:8080"` (Quartz's dev server) while testing.
+`ALLOWED_ORIGINS` already includes `http://localhost:8080` (Quartz's dev server).
 
 ## 4. Point Quartz at the worker
 
@@ -83,7 +110,7 @@ worker exists.
 ## Notes / limits
 
 - Comments + replies are fetched 100-at-a-time (no pagination yet).
-- `mapping` must match on read and write. To share the *same* discussion as the
+- `mapping` must match on read and write. To share the _same_ discussion as the
   existing giscus widget, use the mapping giscus is configured with.
 - Ports to Vercel/Netlify functions are straightforward — the handler is a
   single `fetch(request, env)`; only the deploy wrapper changes.
diff --git a/serverless/inline-comments-worker/package-lock.json b/serverless/inline-comments-worker/package-lock.json
new file mode 100644
index 0000000..35be3d3
--- /dev/null
+++ b/serverless/inline-comments-worker/package-lock.json
@@ -0,0 +1,1606 @@
+{
+  "name": "inline-comments-worker",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "inline-comments-worker",
+      "version": "0.1.0",
+      "devDependencies": {
+        "@cloudflare/workers-types": "^4.20241106.0",
+        "typescript": "^5.6.0",
+        "wrangler": "^3.86.0"
+      }
+    },
+    "node_modules/@cloudflare/kv-asset-handler": {
+      "version": "0.3.4",
+      "resolved": "https://registry.npmjs.org/@cloudflare/kv-asset-handler/-/kv-asset-handler-0.3.4.tgz",
+      "integrity": "sha512-YLPHc8yASwjNkmcDMQMY35yiWjoKAKnhUbPRszBRS0YgH+IXtsMp61j+yTcnCE3oO2DgP0U3iejLC8FTtKDC8Q==",
+      "dev": true,
+      "license": "MIT OR Apache-2.0",
+      "dependencies": {
+        "mime": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=16.13"
+      }
+    },
+    "node_modules/@cloudflare/unenv-preset": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/@cloudflare/unenv-preset/-/unenv-preset-2.0.2.tgz",
+      "integrity": "sha512-nyzYnlZjjV5xT3LizahG1Iu6mnrCaxglJ04rZLpDwlDVDZ7v46lNsfxhV3A/xtfgQuSHmLnc6SVI+KwBpc3Lwg==",
+      "dev": true,
+      "license": "MIT OR Apache-2.0",
+      "peerDependencies": {
+        "unenv": "2.0.0-rc.14",
+        "workerd": "^1.20250124.0"
+      },
+      "peerDependenciesMeta": {
+        "workerd": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@cloudflare/workerd-darwin-64": {
+      "version": "1.20250718.0",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20250718.0.tgz",
+      "integrity": "sha512-FHf4t7zbVN8yyXgQ/r/GqLPaYZSGUVzeR7RnL28Mwj2djyw2ZergvytVc7fdGcczl6PQh+VKGfZCfUqpJlbi9g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@cloudflare/workerd-darwin-arm64": {
+      "version": "1.20250718.0",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20250718.0.tgz",
+      "integrity": "sha512-fUiyUJYyqqp4NqJ0YgGtp4WJh/II/YZsUnEb6vVy5Oeas8lUOxnN+ZOJ8N/6/5LQCVAtYCChRiIrBbfhTn5Z8Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@cloudflare/workerd-linux-64": {
+      "version": "1.20250718.0",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20250718.0.tgz",
+      "integrity": "sha512-5+eb3rtJMiEwp08Kryqzzu8d1rUcK+gdE442auo5eniMpT170Dz0QxBrqkg2Z48SFUPYbj+6uknuA5tzdRSUSg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@cloudflare/workerd-linux-arm64": {
+      "version": "1.20250718.0",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20250718.0.tgz",
+      "integrity": "sha512-Aa2M/DVBEBQDdATMbn217zCSFKE+ud/teS+fFS+OQqKABLn0azO2qq6ANAHYOIE6Q3Sq4CxDIQr8lGdaJHwUog==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@cloudflare/workerd-windows-64": {
+      "version": "1.20250718.0",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20250718.0.tgz",
+      "integrity": "sha512-dY16RXKffmugnc67LTbyjdDHZn5NoTF1yHEf2fN4+OaOnoGSp3N1x77QubTDwqZ9zECWxgQfDLjddcH8dWeFhg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@cloudflare/workers-types": {
+      "version": "4.20260702.1",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workers-types/-/workers-types-4.20260702.1.tgz",
+      "integrity": "sha512-mOhf5TUEB1m2vPrxtqoIGfz0fUC9xyxRDx5gWHy5s+OCo6dcV+g7wI1R7gYCMFohhqF/2y2xeKVwMwCJjfn/WA==",
+      "dev": true,
+      "license": "MIT OR Apache-2.0"
+    },
+    "node_modules/@cspotcode/source-map-support": {
+      "version": "0.8.1",
+      "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
+      "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "0.3.9"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.11.2",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.2.tgz",
+      "integrity": "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@esbuild-plugins/node-globals-polyfill": {
+      "version": "0.2.3",
+      "resolved": "https://registry.npmjs.org/@esbuild-plugins/node-globals-polyfill/-/node-globals-polyfill-0.2.3.tgz",
+      "integrity": "sha512-r3MIryXDeXDOZh7ih1l/yE9ZLORCd5e8vWg02azWRGj5SPTuoh69A2AIyn0Z31V/kHBfZ4HgWJ+OK3GTTwLmnw==",
+      "dev": true,
+      "license": "ISC",
+      "peerDependencies": {
+        "esbuild": "*"
+      }
+    },
+    "node_modules/@esbuild-plugins/node-modules-polyfill": {
+      "version": "0.2.2",
+      "resolved": "https://registry.npmjs.org/@esbuild-plugins/node-modules-polyfill/-/node-modules-polyfill-0.2.2.tgz",
+      "integrity": "sha512-LXV7QsWJxRuMYvKbiznh+U1ilIop3g2TeKRzUxOG5X3YITc8JyyTa90BmLwqqv0YnX4v32CSlG+vsziZp9dMvA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "escape-string-regexp": "^4.0.0",
+        "rollup-plugin-node-polyfills": "^0.2.1"
+      },
+      "peerDependencies": {
+        "esbuild": "*"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.17.19.tgz",
+      "integrity": "sha512-rIKddzqhmav7MSmoFCmDIb6e2W57geRsM94gV2l38fzhXMwq7hZoClug9USI2pFRGL06f4IOPHHpFNOkWieR8A==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.17.19.tgz",
+      "integrity": "sha512-KBMWvEZooR7+kzY0BtbTQn0OAYY7CsiydT63pVEaPtVYF0hXbUaOyZog37DKxK7NF3XacBJOpYT4adIJh+avxA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.17.19.tgz",
+      "integrity": "sha512-uUTTc4xGNDT7YSArp/zbtmbhO0uEEK9/ETW29Wk1thYUJBz3IVnvgEiEwEa9IeLyvnpKrWK64Utw2bgUmDveww==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.17.19.tgz",
+      "integrity": "sha512-80wEoCfF/hFKM6WE1FyBHc9SfUblloAWx6FJkFWTWiCoht9Mc0ARGEM47e67W9rI09YoUxJL68WHfDRYEAvOhg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.17.19.tgz",
+      "integrity": "sha512-IJM4JJsLhRYr9xdtLytPLSH9k/oxR3boaUIYiHkAawtwNOXKE8KoU8tMvryogdcT8AU+Bflmh81Xn6Q0vTZbQw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.17.19.tgz",
+      "integrity": "sha512-pBwbc7DufluUeGdjSU5Si+P3SoMF5DQ/F/UmTSb8HXO80ZEAJmrykPyzo1IfNbAoaqw48YRpv8shwd1NoI0jcQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.17.19.tgz",
+      "integrity": "sha512-4lu+n8Wk0XlajEhbEffdy2xy53dpR06SlzvhGByyg36qJw6Kpfk7cp45DR/62aPH9mtJRmIyrXAS5UWBrJT6TQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.17.19.tgz",
+      "integrity": "sha512-cdmT3KxjlOQ/gZ2cjfrQOtmhG4HJs6hhvm3mWSRDPtZ/lP5oe8FWceS10JaSJC13GBd4eH/haHnqf7hhGNLerA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.17.19.tgz",
+      "integrity": "sha512-ct1Tg3WGwd3P+oZYqic+YZF4snNl2bsnMKRkb3ozHmnM0dGWuxcPTTntAF6bOP0Sp4x0PjSF+4uHQ1xvxfRKqg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.17.19.tgz",
+      "integrity": "sha512-w4IRhSy1VbsNxHRQpeGCHEmibqdTUx61Vc38APcsRbuVgK0OPEnQ0YD39Brymn96mOx48Y2laBQGqgZ0j9w6SQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.17.19.tgz",
+      "integrity": "sha512-2iAngUbBPMq439a+z//gE+9WBldoMp1s5GWsUSgqHLzLJ9WoZLZhpwWuym0u0u/4XmZ3gpHmzV84PonE+9IIdQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.17.19.tgz",
+      "integrity": "sha512-LKJltc4LVdMKHsrFe4MGNPp0hqDFA1Wpt3jE1gEyM3nKUvOiO//9PheZZHfYRfYl6AwdTH4aTcXSqBerX0ml4A==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.17.19.tgz",
+      "integrity": "sha512-/c/DGybs95WXNS8y3Ti/ytqETiW7EU44MEKuCAcpPto3YjQbyK3IQVKfF6nbghD7EcLUGl0NbiL5Rt5DMhn5tg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.17.19.tgz",
+      "integrity": "sha512-FC3nUAWhvFoutlhAkgHf8f5HwFWUL6bYdvLc/TTuxKlvLi3+pPzdZiFKSWz/PF30TB1K19SuCxDTI5KcqASJqA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.17.19.tgz",
+      "integrity": "sha512-IbFsFbxMWLuKEbH+7sTkKzL6NJmG2vRyy6K7JJo55w+8xDk7RElYn6xvXtDW8HCfoKBFK69f3pgBJSUSQPr+4Q==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.17.19.tgz",
+      "integrity": "sha512-68ngA9lg2H6zkZcyp22tsVt38mlhWde8l3eJLWkyLrp4HwMUr3c1s/M2t7+kHIhvMjglIBrFpncX1SzMckomGw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.17.19.tgz",
+      "integrity": "sha512-CwFq42rXCR8TYIjIfpXCbRX0rp1jo6cPIUPSaWwzbVI4aOfX96OXY8M6KNmtPcg7QjYeDmN+DD0Wp3LaBOLf4Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.17.19.tgz",
+      "integrity": "sha512-cnq5brJYrSZ2CF6c35eCmviIN3k3RczmHz8eYaVlNasVqsNY+JKohZU5MKmaOI+KkllCdzOKKdPs762VCPC20g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.17.19.tgz",
+      "integrity": "sha512-vCRT7yP3zX+bKWFeP/zdS6SqdWB8OIpaRq/mbXQxTGHnIxspRtigpkUcDMlSCOejlHowLqII7K2JKevwyRP2rg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.17.19.tgz",
+      "integrity": "sha512-yYx+8jwowUstVdorcMdNlzklLYhPxjniHWFKgRqH7IFlUEa0Umu3KuYplf1HUZZ422e3NU9F4LGb+4O0Kdcaag==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.17.19.tgz",
+      "integrity": "sha512-eggDKanJszUtCdlVs0RB+h35wNlb5v4TWEkq4vZcmVt5u/HiDZrTXe2bWFQUez3RgNHwx/x4sk5++4NSSicKkw==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.17.19.tgz",
+      "integrity": "sha512-lAhycmKnVOuRYNtRtatQR1LPQf2oYCkRGkSFnseDAKPl8lu5SOsK/e1sXe5a0Pc5kHIHe6P2I/ilntNv2xf3cA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@fastify/busboy": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-2.1.1.tgz",
+      "integrity": "sha512-vBZP4NlzfOlerQTnba4aqZoMhE/a9HY7HRqoOPaETQcSQuWEIyZMHGfVu6w9wGtGK5fED5qRs2DteVCjOH60sA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/@img/sharp-darwin-arm64": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.33.5.tgz",
+      "integrity": "sha512-UT4p+iz/2H4twwAoLCqfA9UH5pI6DggwKEGuaPy7nCVQ8ZsiY5PIcrRvD1DzuY3qYL07NtIQcWnBSY/heikIFQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-arm64": "1.0.4"
+      }
+    },
+    "node_modules/@img/sharp-darwin-x64": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.33.5.tgz",
+      "integrity": "sha512-fyHac4jIc1ANYGRDxtiqelIbdWkIuQaI84Mv45KvGRRxSAa7o7d1ZKAOBaYbnepLC1WqxfpimdeWfvqqSGwR2Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-x64": "1.0.4"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-arm64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.0.4.tgz",
+      "integrity": "sha512-XblONe153h0O2zuFfTAbQYAX2JhYmDHeWikp1LM9Hul9gVPjFY427k6dFEcOL72O01QxQsWi761svJ/ev9xEDg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-x64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.0.4.tgz",
+      "integrity": "sha512-xnGR8YuZYfJGmWPvmlunFaWJsb9T/AO2ykoP3Fz/0X5XV2aoYBPkX6xqCQvUTKKiLddarLaxpzNe+b1hjeWHAQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.0.5.tgz",
+      "integrity": "sha512-gvcC4ACAOPRNATg/ov8/MnbxFDJqf/pDePbBnuBDcjsI8PssmjoKMAz4LtLaVi+OnSb5FK/yIOamqDwGmXW32g==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.0.4.tgz",
+      "integrity": "sha512-9B+taZ8DlyyqzZQnoeIvDVR/2F4EbMepXMc/NdVbkzsJbzkUjhXv/70GQJ7tdLA4YJgNP25zukcxpX2/SueNrA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-s390x": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.0.4.tgz",
+      "integrity": "sha512-u7Wz6ntiSSgGSGcjZ55im6uvTrOxSIS8/dgoVMoiGE9I6JAfU50yH5BoDlYA1tcuGS7g/QNtetJnxA6QEsCVTA==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-x64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.0.4.tgz",
+      "integrity": "sha512-MmWmQ3iPFZr0Iev+BAgVMb3ZyC4KeFc3jFxnNbEPas60e1cIfevbtuyf9nDGIzOaW9PdnDciJm+wFFaTlj5xYw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.0.4.tgz",
+      "integrity": "sha512-9Ti+BbTYDcsbp4wfYib8Ctm1ilkugkA/uscUn6UXK1ldpC1JjiXbLfFZtRlBhjPZ5o1NCLiDbg8fhUPKStHoTA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-x64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.0.4.tgz",
+      "integrity": "sha512-viYN1KX9m+/hGkJtvYYp+CCLgnJXwiQB39damAO7WMdKWlIhmYTfHjwSbQeUK/20vY154mwezd9HflVFM1wVSw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.33.5.tgz",
+      "integrity": "sha512-JTS1eldqZbJxjvKaAkxhZmBqPRGmxgu+qFKSInv8moZ2AmT5Yib3EQ1c6gp493HvrvV8QgdOXdyaIBrhvFhBMQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm": "1.0.5"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm64": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.33.5.tgz",
+      "integrity": "sha512-JMVv+AMRyGOHtO1RFBiJy/MBsgz0x4AWrT6QoEVVTyh1E39TrCUpTRI7mx9VksGX4awWASxqCYLCV4wBZHAYxA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm64": "1.0.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-s390x": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.33.5.tgz",
+      "integrity": "sha512-y/5PCd+mP4CA/sPDKl2961b+C9d+vPAveS33s6Z3zfASk2j5upL6fXVPZi7ztePZ5CuH+1kW8JtvxgbuXHRa4Q==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-s390x": "1.0.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-x64": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.33.5.tgz",
+      "integrity": "sha512-opC+Ok5pRNAzuvq1AG0ar+1owsu842/Ab+4qvU879ippJBHvyY5n2mxF1izXqkPYlGuP/M556uh53jRLJmzTWA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-x64": "1.0.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-arm64": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.33.5.tgz",
+      "integrity": "sha512-XrHMZwGQGvJg2V/oRSUfSAfjfPxO+4DkiRh6p2AFjLQztWUuY/o8Mq0eMQVIY7HJ1CDQUJlxGGZRw1a5bqmd1g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-arm64": "1.0.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-x64": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.33.5.tgz",
+      "integrity": "sha512-WT+d/cgqKkkKySYmqoZ8y3pxx7lx9vVejxW/W4DOFMYVSkErR+w7mf2u8m/y4+xHe7yY9DAXQMWQhpnMuFfScw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-x64": "1.0.4"
+      }
+    },
+    "node_modules/@img/sharp-wasm32": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.33.5.tgz",
+      "integrity": "sha512-ykUW4LVGaMcU9lu9thv85CbRMAwfeadCJHRsg2GmeRa/cJxsVY9Rbd57JcMxBkKHag5U/x7TSBpScF4U8ElVzg==",
+      "cpu": [
+        "wasm32"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/runtime": "^1.2.0"
+      },
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-ia32": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.33.5.tgz",
+      "integrity": "sha512-T36PblLaTwuVJ/zw/LaH0PdZkRz5rd3SmMHX8GSmR7vtNSP5Z6bQkExdSK7xGWyxLw4sUknBuugTelgw2faBbQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-x64": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.33.5.tgz",
+      "integrity": "sha512-MpY/o8/8kj+EcnxwvrP4aTJSWw/aZ7JIGR4aBeZkZw5B7/Jn+tY9/VNwtcoGmdT7GfggGIU4kygOMSbYnOrAbg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.9",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz",
+      "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.0.3",
+        "@jridgewell/sourcemap-codec": "^1.4.10"
+      }
+    },
+    "node_modules/acorn": {
+      "version": "8.14.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.0.tgz",
+      "integrity": "sha512-cl669nCJTZBsL97OF4kUQm5g5hC2uihk0NxY3WENAC0TYdILVkAyHymAntgxGkl7K+t0cXIrH5siy5S4XkFycA==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/acorn-walk": {
+      "version": "8.3.2",
+      "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.2.tgz",
+      "integrity": "sha512-cjkyv4OtNCIeqhHrfS81QWXoCBPExR/J62oyEqepVw8WaQeSqpW2uhuLPh1m9eWhDuOo/jUXVTlifvesOWp/4A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/as-table": {
+      "version": "1.0.55",
+      "resolved": "https://registry.npmjs.org/as-table/-/as-table-1.0.55.tgz",
+      "integrity": "sha512-xvsWESUJn0JN421Xb9MQw6AsMHRCUknCe0Wjlxvjud80mU4E6hQf1A6NzQKcYNmYw62MfzEtXc+badstZP3JpQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "printable-characters": "^1.0.42"
+      }
+    },
+    "node_modules/blake3-wasm": {
+      "version": "2.1.5",
+      "resolved": "https://registry.npmjs.org/blake3-wasm/-/blake3-wasm-2.1.5.tgz",
+      "integrity": "sha512-F1+K8EbfOZE49dtoPtmxUQrpXaBIl3ICvasLh+nJta0xkz+9kF/7uet9fLnwKqhDrmj6g+6K3Tw9yQPUg2ka5g==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/color": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/color/-/color-4.2.3.tgz",
+      "integrity": "sha512-1rXeuUUiGGrykh+CeBdu5Ie7OJwinCgQY0bc7GCRxy5xVHy+moaqkpL/jqQq0MtQOeYcrqEz4abc5f0KtU7W4A==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "color-convert": "^2.0.1",
+        "color-string": "^1.9.0"
+      },
+      "engines": {
+        "node": ">=12.5.0"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "color-name": "~1.1.4"
+      },
+      "engines": {
+        "node": ">=7.0.0"
+      }
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/color-string": {
+      "version": "1.9.1",
+      "resolved": "https://registry.npmjs.org/color-string/-/color-string-1.9.1.tgz",
+      "integrity": "sha512-shrVawQFojnZv6xM40anx4CkoDP+fZsw/ZerEMsW/pyzsRbElpsL/DBVW7q3ExxwusdNXI3lXpuhEZkzs8p5Eg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "color-name": "^1.0.0",
+        "simple-swizzle": "^0.2.2"
+      }
+    },
+    "node_modules/cookie": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
+      "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/data-uri-to-buffer": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-2.0.2.tgz",
+      "integrity": "sha512-ND9qDTLc6diwj+Xe5cdAgVTbLVdXbtxTJRXRhli8Mowuaan+0EJOtdqJ0QCHNSSPyoXGx9HX2/VMnKeC34AChA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/defu": {
+      "version": "6.1.7",
+      "resolved": "https://registry.npmjs.org/defu/-/defu-6.1.7.tgz",
+      "integrity": "sha512-7z22QmUWiQ/2d0KkdYmANbRUVABpZ9SNYyH5vx6PZ+nE5bcC0l7uFvEfHlyld/HcGBFTL536ClDt3DEcSlEJAQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.17.19",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.17.19.tgz",
+      "integrity": "sha512-XQ0jAPFkK/u3LcVRcvVHQcTIqD6E2H1fvZMA5dQPSOWb3suUbWbfbRf94pjc0bNzRYLfIrDRQXr7X+LHIm5oHw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "optionalDependencies": {
+        "@esbuild/android-arm": "0.17.19",
+        "@esbuild/android-arm64": "0.17.19",
+        "@esbuild/android-x64": "0.17.19",
+        "@esbuild/darwin-arm64": "0.17.19",
+        "@esbuild/darwin-x64": "0.17.19",
+        "@esbuild/freebsd-arm64": "0.17.19",
+        "@esbuild/freebsd-x64": "0.17.19",
+        "@esbuild/linux-arm": "0.17.19",
+        "@esbuild/linux-arm64": "0.17.19",
+        "@esbuild/linux-ia32": "0.17.19",
+        "@esbuild/linux-loong64": "0.17.19",
+        "@esbuild/linux-mips64el": "0.17.19",
+        "@esbuild/linux-ppc64": "0.17.19",
+        "@esbuild/linux-riscv64": "0.17.19",
+        "@esbuild/linux-s390x": "0.17.19",
+        "@esbuild/linux-x64": "0.17.19",
+        "@esbuild/netbsd-x64": "0.17.19",
+        "@esbuild/openbsd-x64": "0.17.19",
+        "@esbuild/sunos-x64": "0.17.19",
+        "@esbuild/win32-arm64": "0.17.19",
+        "@esbuild/win32-ia32": "0.17.19",
+        "@esbuild/win32-x64": "0.17.19"
+      }
+    },
+    "node_modules/escape-string-regexp": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
+      "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/estree-walker": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-0.6.1.tgz",
+      "integrity": "sha512-SqmZANLWS0mnatqbSfRP5g8OXZC12Fgg1IwNtLsyHDzJizORW4khDfjPqJZsemPWBB2uqykUah5YpQ6epsqC/w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/exit-hook": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/exit-hook/-/exit-hook-2.2.1.tgz",
+      "integrity": "sha512-eNTPlAD67BmP31LDINZ3U7HSF8l57TxOY2PmBJ1shpCvpnxBF93mWCE8YHBnXs8qiUZJc9WDcWIeC3a2HIAMfw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/exsolve": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/exsolve/-/exsolve-1.1.0.tgz",
+      "integrity": "sha512-D+42+T12DdIlJM3uepa55qGiL3sYdLBOxIl2ifQCzCHz4c7eiolaHsi3BIqEr7JxBzxv2pYZQX9kw16ziMcEmw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/get-source": {
+      "version": "2.0.12",
+      "resolved": "https://registry.npmjs.org/get-source/-/get-source-2.0.12.tgz",
+      "integrity": "sha512-X5+4+iD+HoSeEED+uwrQ07BOQr0kEDFMVqqpBuI+RaZBpBpHCuXxo70bjar6f0b0u/DQJsJ7ssurpP0V60Az+w==",
+      "dev": true,
+      "license": "Unlicense",
+      "dependencies": {
+        "data-uri-to-buffer": "^2.0.0",
+        "source-map": "^0.6.1"
+      }
+    },
+    "node_modules/glob-to-regexp": {
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/glob-to-regexp/-/glob-to-regexp-0.4.1.tgz",
+      "integrity": "sha512-lkX1HJXwyMcprw/5YUZc2s7DrpAiHB21/V+E1rHUrVNokkvB6bqMzT0VfV6/86ZNabt1k14YOIaT7nDvOX3Iiw==",
+      "dev": true,
+      "license": "BSD-2-Clause"
+    },
+    "node_modules/is-arrayish": {
+      "version": "0.3.4",
+      "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.3.4.tgz",
+      "integrity": "sha512-m6UrgzFVUYawGBh1dUsWR5M2Clqic9RVXC/9f8ceNlv2IcO9j9J/z8UoCLPqtsPBFNzEpfR3xftohbfqDx8EQA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/magic-string": {
+      "version": "0.25.9",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.25.9.tgz",
+      "integrity": "sha512-RmF0AsMzgt25qzqqLc1+MbHmhdx0ojF2Fvs4XnOqz2ZOBXzzkEwc/dJQZCYHAn7v1jbVOjAZfK8msRn4BxO4VQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "sourcemap-codec": "^1.4.8"
+      }
+    },
+    "node_modules/mime": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-3.0.0.tgz",
+      "integrity": "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "mime": "cli.js"
+      },
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
+    "node_modules/miniflare": {
+      "version": "3.20250718.3",
+      "resolved": "https://registry.npmjs.org/miniflare/-/miniflare-3.20250718.3.tgz",
+      "integrity": "sha512-JuPrDJhwLrNLEJiNLWO7ZzJrv/Vv9kZuwMYCfv0LskQDM6Eonw4OvywO3CH/wCGjgHzha/qyjUh8JQ068TjDgQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@cspotcode/source-map-support": "0.8.1",
+        "acorn": "8.14.0",
+        "acorn-walk": "8.3.2",
+        "exit-hook": "2.2.1",
+        "glob-to-regexp": "0.4.1",
+        "stoppable": "1.1.0",
+        "undici": "^5.28.5",
+        "workerd": "1.20250718.0",
+        "ws": "8.18.0",
+        "youch": "3.3.4",
+        "zod": "3.22.3"
+      },
+      "bin": {
+        "miniflare": "bootstrap.js"
+      },
+      "engines": {
+        "node": ">=16.13"
+      }
+    },
+    "node_modules/mustache": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/mustache/-/mustache-4.2.0.tgz",
+      "integrity": "sha512-71ippSywq5Yb7/tVYyGbkBggbU8H3u5Rz56fH60jGFgr8uHwxs+aSKeqmluIVzM0m0kB7xQjKS6qPfd0b2ZoqQ==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "mustache": "bin/mustache"
+      }
+    },
+    "node_modules/ohash": {
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/ohash/-/ohash-2.0.11.tgz",
+      "integrity": "sha512-RdR9FQrFwNBNXAr4GixM8YaRZRJ5PUWbKYbE5eOsrwAjJW0q2REGcf79oYPsLyskQCZG1PLN+S/K1V00joZAoQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/path-to-regexp": {
+      "version": "6.3.0",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-6.3.0.tgz",
+      "integrity": "sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/printable-characters": {
+      "version": "1.0.42",
+      "resolved": "https://registry.npmjs.org/printable-characters/-/printable-characters-1.0.42.tgz",
+      "integrity": "sha512-dKp+C4iXWK4vVYZmYSd0KBH5F/h1HoZRsbJ82AVKRO3PEo8L4lBS/vLwhVtpwwuYcoIsVY+1JYKR268yn480uQ==",
+      "dev": true,
+      "license": "Unlicense"
+    },
+    "node_modules/rollup-plugin-inject": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/rollup-plugin-inject/-/rollup-plugin-inject-3.0.2.tgz",
+      "integrity": "sha512-ptg9PQwzs3orn4jkgXJ74bfs5vYz1NCZlSQMBUA0wKcGp5i5pA1AO3fOUEte8enhGUC+iapTCzEWw2jEFFUO/w==",
+      "deprecated": "This package has been deprecated and is no longer maintained. Please use @rollup/plugin-inject.",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "estree-walker": "^0.6.1",
+        "magic-string": "^0.25.3",
+        "rollup-pluginutils": "^2.8.1"
+      }
+    },
+    "node_modules/rollup-plugin-node-polyfills": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/rollup-plugin-node-polyfills/-/rollup-plugin-node-polyfills-0.2.1.tgz",
+      "integrity": "sha512-4kCrKPTJ6sK4/gLL/U5QzVT8cxJcofO0OU74tnB19F40cmuAKSzH5/siithxlofFEjwvw1YAhPmbvGNA6jEroA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "rollup-plugin-inject": "^3.0.0"
+      }
+    },
+    "node_modules/rollup-pluginutils": {
+      "version": "2.8.2",
+      "resolved": "https://registry.npmjs.org/rollup-pluginutils/-/rollup-pluginutils-2.8.2.tgz",
+      "integrity": "sha512-EEp9NhnUkwY8aif6bxgovPHMoMoNr2FulJziTndpt5H9RdwC47GSGuII9XxpSdzVGM0GWrNPHV6ie1LTNJPaLQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "estree-walker": "^0.6.1"
+      }
+    },
+    "node_modules/semver": {
+      "version": "7.8.5",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
+      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
+      "dev": true,
+      "license": "ISC",
+      "optional": true,
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/sharp": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.33.5.tgz",
+      "integrity": "sha512-haPVm1EkS9pgvHrQ/F3Xy+hgcuMV0Wm9vfIBSiwZ05k+xgb0PkBQpGsAA/oWdDobNaZTH5ppvHtzCFbnSEwHVw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "color": "^4.2.3",
+        "detect-libc": "^2.0.3",
+        "semver": "^7.6.3"
+      },
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-darwin-arm64": "0.33.5",
+        "@img/sharp-darwin-x64": "0.33.5",
+        "@img/sharp-libvips-darwin-arm64": "1.0.4",
+        "@img/sharp-libvips-darwin-x64": "1.0.4",
+        "@img/sharp-libvips-linux-arm": "1.0.5",
+        "@img/sharp-libvips-linux-arm64": "1.0.4",
+        "@img/sharp-libvips-linux-s390x": "1.0.4",
+        "@img/sharp-libvips-linux-x64": "1.0.4",
+        "@img/sharp-libvips-linuxmusl-arm64": "1.0.4",
+        "@img/sharp-libvips-linuxmusl-x64": "1.0.4",
+        "@img/sharp-linux-arm": "0.33.5",
+        "@img/sharp-linux-arm64": "0.33.5",
+        "@img/sharp-linux-s390x": "0.33.5",
+        "@img/sharp-linux-x64": "0.33.5",
+        "@img/sharp-linuxmusl-arm64": "0.33.5",
+        "@img/sharp-linuxmusl-x64": "0.33.5",
+        "@img/sharp-wasm32": "0.33.5",
+        "@img/sharp-win32-ia32": "0.33.5",
+        "@img/sharp-win32-x64": "0.33.5"
+      }
+    },
+    "node_modules/simple-swizzle": {
+      "version": "0.2.4",
+      "resolved": "https://registry.npmjs.org/simple-swizzle/-/simple-swizzle-0.2.4.tgz",
+      "integrity": "sha512-nAu1WFPQSMNr2Zn9PGSZK9AGn4t/y97lEm+MXTtUDwfP0ksAIX4nO+6ruD9Jwut4C49SB1Ws+fbXsm/yScWOHw==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "is-arrayish": "^0.3.1"
+      }
+    },
+    "node_modules/source-map": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
+      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/sourcemap-codec": {
+      "version": "1.4.8",
+      "resolved": "https://registry.npmjs.org/sourcemap-codec/-/sourcemap-codec-1.4.8.tgz",
+      "integrity": "sha512-9NykojV5Uih4lgo5So5dtw+f0JgJX30KCNI8gwhz2J9A15wD0Ml6tjHKwf6fTSa6fAdVBdZeNOs9eJ71qCk8vA==",
+      "deprecated": "Please use @jridgewell/sourcemap-codec instead",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/stacktracey": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/stacktracey/-/stacktracey-2.2.0.tgz",
+      "integrity": "sha512-ETyQEz+CzXiLjEbyJqpbp+/T79RQD/6wqFucRBIlVNZfYq2Ay7wbretD4cxpbymZlaPWx58aIhPEY1Cr8DlVvg==",
+      "dev": true,
+      "license": "Unlicense",
+      "dependencies": {
+        "as-table": "^1.0.36",
+        "get-source": "^2.0.12"
+      }
+    },
+    "node_modules/stoppable": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/stoppable/-/stoppable-1.1.0.tgz",
+      "integrity": "sha512-KXDYZ9dszj6bzvnEMRYvxgeTHU74QBFL54XKtP3nyMuJ81CFYtABZ3bAzL2EdFUaEwJOBOgENyFj3R7oTzDyyw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4",
+        "npm": ">=6"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "dev": true,
+      "license": "0BSD",
+      "optional": true
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/ufo": {
+      "version": "1.6.4",
+      "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.6.4.tgz",
+      "integrity": "sha512-JFNbkD1Svwe0KvGi8GOeLcP4kAWQ609twvCdcHxq1oSL8svv39ZuSvajcD8B+5D0eL4+s1Is2D/O6KN3qcTeRA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/undici": {
+      "version": "5.29.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-5.29.0.tgz",
+      "integrity": "sha512-raqeBD6NQK4SkWhQzeYKd1KmIG6dllBOTt55Rmkt4HtI9mwdWtJljnrXjAFUBLTSN67HWrOIZ3EPF4kjUw80Bg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@fastify/busboy": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=14.0"
+      }
+    },
+    "node_modules/unenv": {
+      "version": "2.0.0-rc.14",
+      "resolved": "https://registry.npmjs.org/unenv/-/unenv-2.0.0-rc.14.tgz",
+      "integrity": "sha512-od496pShMen7nOy5VmVJCnq8rptd45vh6Nx/r2iPbrba6pa6p+tS2ywuIHRZ/OBvSbQZB0kWvpO9XBNVFXHD3Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "defu": "^6.1.4",
+        "exsolve": "^1.0.1",
+        "ohash": "^2.0.10",
+        "pathe": "^2.0.3",
+        "ufo": "^1.5.4"
+      }
+    },
+    "node_modules/workerd": {
+      "version": "1.20250718.0",
+      "resolved": "https://registry.npmjs.org/workerd/-/workerd-1.20250718.0.tgz",
+      "integrity": "sha512-kqkIJP/eOfDlUyBzU7joBg+tl8aB25gEAGqDap+nFWb+WHhnooxjGHgxPBy3ipw2hnShPFNOQt5lFRxbwALirg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "workerd": "bin/workerd"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "optionalDependencies": {
+        "@cloudflare/workerd-darwin-64": "1.20250718.0",
+        "@cloudflare/workerd-darwin-arm64": "1.20250718.0",
+        "@cloudflare/workerd-linux-64": "1.20250718.0",
+        "@cloudflare/workerd-linux-arm64": "1.20250718.0",
+        "@cloudflare/workerd-windows-64": "1.20250718.0"
+      }
+    },
+    "node_modules/wrangler": {
+      "version": "3.114.17",
+      "resolved": "https://registry.npmjs.org/wrangler/-/wrangler-3.114.17.tgz",
+      "integrity": "sha512-tAvf7ly+tB+zwwrmjsCyJ2pJnnc7SZhbnNwXbH+OIdVas3zTSmjcZOjmLKcGGptssAA3RyTKhcF9BvKZzMUycA==",
+      "dev": true,
+      "license": "MIT OR Apache-2.0",
+      "dependencies": {
+        "@cloudflare/kv-asset-handler": "0.3.4",
+        "@cloudflare/unenv-preset": "2.0.2",
+        "@esbuild-plugins/node-globals-polyfill": "0.2.3",
+        "@esbuild-plugins/node-modules-polyfill": "0.2.2",
+        "blake3-wasm": "2.1.5",
+        "esbuild": "0.17.19",
+        "miniflare": "3.20250718.3",
+        "path-to-regexp": "6.3.0",
+        "unenv": "2.0.0-rc.14",
+        "workerd": "1.20250718.0"
+      },
+      "bin": {
+        "wrangler": "bin/wrangler.js",
+        "wrangler2": "bin/wrangler.js"
+      },
+      "engines": {
+        "node": ">=16.17.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.2",
+        "sharp": "^0.33.5"
+      },
+      "peerDependencies": {
+        "@cloudflare/workers-types": "^4.20250408.0"
+      },
+      "peerDependenciesMeta": {
+        "@cloudflare/workers-types": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.18.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.18.0.tgz",
+      "integrity": "sha512-8VbfWfHLbbwu3+N6OKsOMpBdT4kXPDDB9cJk2bJ6mh9ucxdlnNvH1e+roYkKmN9Nxw2yjz7VzeO9oOz2zJ04Pw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/youch": {
+      "version": "3.3.4",
+      "resolved": "https://registry.npmjs.org/youch/-/youch-3.3.4.tgz",
+      "integrity": "sha512-UeVBXie8cA35DS6+nBkls68xaBBXCye0CNznrhszZjTbRVnJKQuNsyLKBTTL4ln1o1rh2PKtv35twV7irj5SEg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cookie": "^0.7.1",
+        "mustache": "^4.2.0",
+        "stacktracey": "^2.1.8"
+      }
+    },
+    "node_modules/zod": {
+      "version": "3.22.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-3.22.3.tgz",
+      "integrity": "sha512-EjIevzuJRiRPbVH4mGc8nApb/lVLKVpmUhAaR5R5doKGfAnGJ6Gr3CViAVjP+4FWSxCsybeWQdcgCtbX+7oZug==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}
diff --git a/serverless/inline-comments-worker/wrangler.toml b/serverless/inline-comments-worker/wrangler.toml
index d2cacac..5452f38 100644
--- a/serverless/inline-comments-worker/wrangler.toml
+++ b/serverless/inline-comments-worker/wrangler.toml
@@ -4,8 +4,11 @@ compatibility_date = "2024-11-01"
 
 # Public site origin(s) allowed to use this worker (comma-separated).
 # Used for CORS on /api/comments and as the postMessage target on auth callback.
+# NOTE: origins only — scheme + host, no path. The site lives at
+# https://logos-co.github.io/assembly/ but the origin is the bare host.
+# Changing these requires a redeploy (`wrangler deploy`); secrets do not.
 [vars]
-ALLOWED_ORIGINS = "http://localhost:8080"
+ALLOWED_ORIGINS = "https://logos-co.github.io,http://localhost:8080"
 
 # Secrets are NOT set here. Set them with:
 #   wrangler secret put GITHUB_CLIENT_ID

From 0d9af3749991398c5f265b2bf54daee632112e8e Mon Sep 17 00:00:00 2001
From: Corey Petty <corey@status.im>
Date: Mon, 20 Jul 2026 10:35:59 -0400
Subject: [PATCH 3/6] Fix comment button positioning; offer sign-in in the
 composer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The floating "Comment" button was positioned with `absolute` while
computePosition ran with `strategy: "fixed"`. Fixed-strategy coordinates
are viewport-relative, so an absolutely-positioned element read them as
document-relative and the button was offset by scrollY — visible only at
the very top of the page. Switch it to `fixed`, matching the popover.

Also surface authentication in the composer itself, so signing in no
longer means scrolling to the giscus widget at the bottom of the page:

- signed out: a "Sign in with GitHub" button under the textarea; typed
  text survives the popup round-trip
- signed in: avatar + @login, plus a sign-out link
- cache the viewer in localStorage so it costs one round-trip rather
  than one per popover open
- route implicit login-on-submit through a shared ensureToken(), keeping
  login() reachable synchronously from the click so the popup is not
  blocked by the browser

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../scripts/inlineComments.inline.ts          | 120 +++++++++++++++++-
 quartz/components/styles/inlineComments.scss  |  62 ++++++++-
 2 files changed, 174 insertions(+), 8 deletions(-)

diff --git a/quartz/components/scripts/inlineComments.inline.ts b/quartz/components/scripts/inlineComments.inline.ts
index ecdaa23..91010cb 100644
--- a/quartz/components/scripts/inlineComments.inline.ts
+++ b/quartz/components/scripts/inlineComments.inline.ts
@@ -53,6 +53,7 @@ type Config = {
 type TextSegment = { node: Text; start: number; end: number }
 
 const TOKEN_KEY = "inline-comments-gh-token"
+const VIEWER_KEY = "inline-comments-gh-viewer"
 const STATE_KEY = "inline-comments-oauth-state"
 const ANCHOR_RE = /<!--\s*quartz-anchor:\s*(\{[\s\S]*?\})\s*-->/
 const CONTEXT_LEN = 32
@@ -312,6 +313,42 @@ function getToken(): string | null {
 
 function clearToken(): void {
   localStorage.removeItem(TOKEN_KEY)
+  localStorage.removeItem(VIEWER_KEY)
+}
+
+// The signed-in user, cached so the composer can show "signed in as @x"
+// without a round-trip on every popover open.
+function getCachedViewer(): CommentAuthor | null {
+  const raw = localStorage.getItem(VIEWER_KEY)
+  if (!raw) return null
+  try {
+    return JSON.parse(raw) as CommentAuthor
+  } catch {
+    return null
+  }
+}
+
+async function fetchViewer(token: string): Promise<CommentAuthor | null> {
+  const cached = getCachedViewer()
+  if (cached) return cached
+  try {
+    const data = await graphql<{ viewer: CommentAuthor }>(
+      token,
+      `
+        query {
+          viewer {
+            login
+            avatarUrl
+          }
+        }
+      `,
+      {},
+    )
+    localStorage.setItem(VIEWER_KEY, JSON.stringify(data.viewer))
+    return data.viewer
+  } catch {
+    return null
+  }
 }
 
 function randomState(): string {
@@ -538,6 +575,17 @@ class InlineComments {
     window.addCleanup(fn)
   }
 
+  // Returns a usable token, opening the sign-in popup if needed. `login()`
+  // must be reached synchronously from the originating click or the browser
+  // blocks the popup — hence no awaits before it.
+  private async ensureToken(): Promise<string> {
+    const existing = getToken()
+    if (existing) return existing
+    const token = await login(this.cfg)
+    await fetchViewer(token)
+    return token
+  }
+
   async start() {
     this.setupSelectionUI()
     await this.render()
@@ -700,9 +748,7 @@ class InlineComments {
     const composer = document.createElement("div")
     composer.className = "inline-comment-composer"
     const textarea = document.createElement("textarea")
-    textarea.placeholder = getToken()
-      ? "Add a comment…"
-      : "Add a comment… (you'll sign in with GitHub to post)"
+    textarea.placeholder = "Add a comment…"
     const actions = document.createElement("div")
     actions.className = "inline-comment-actions"
     const hint = document.createElement("span")
@@ -712,10 +758,69 @@ class InlineComments {
     submit.textContent = submitLabel
     submit.disabled = true
 
+    // auth row — sign-in is offered here rather than only at the page bottom
+    const auth = document.createElement("div")
+    auth.className = "inline-comment-auth"
+
     const setBusy = (b: boolean) => {
       submit.disabled = b || textarea.value.trim().length === 0
       submit.textContent = b ? "Posting…" : submitLabel
     }
+    const showHint = (msg: string) => (hint.textContent = msg)
+
+    const renderAuth = () => {
+      auth.replaceChildren()
+      const token = getToken()
+      if (!token) {
+        const signIn = document.createElement("button")
+        signIn.className = "inline-comment-signin"
+        signIn.type = "button"
+        signIn.innerHTML =
+          `<svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z"/></svg>` +
+          `<span>Sign in with GitHub</span>`
+        signIn.addEventListener("click", async () => {
+          // must call login() synchronously in the click handler or the
+          // popup gets blocked
+          try {
+            signIn.disabled = true
+            const t = await login(this.cfg)
+            await fetchViewer(t)
+            showHint("")
+            renderAuth()
+            textarea.focus()
+          } catch (err) {
+            signIn.disabled = false
+            showHint(err instanceof Error ? err.message : "Sign-in failed.")
+          }
+        })
+        auth.append(signIn)
+        return
+      }
+
+      const who = document.createElement("span")
+      who.className = "inline-comment-whoami"
+      const viewer = getCachedViewer()
+      if (viewer) {
+        const avatar = document.createElement("img")
+        avatar.src = viewer.avatarUrl
+        avatar.alt = viewer.login
+        who.append(avatar, document.createTextNode(`@${viewer.login}`))
+      } else {
+        who.textContent = "Signed in"
+        // resolve the login lazily, then re-render
+        void fetchViewer(token).then((v) => v && renderAuth())
+      }
+      const signOut = document.createElement("button")
+      signOut.className = "inline-comment-signout"
+      signOut.type = "button"
+      signOut.textContent = "Sign out"
+      signOut.addEventListener("click", () => {
+        clearToken()
+        renderAuth()
+      })
+      auth.append(who, signOut)
+    }
+
     textarea.addEventListener("input", () => {
       submit.disabled = textarea.value.trim().length === 0
     })
@@ -723,11 +828,12 @@ class InlineComments {
       const text = textarea.value.trim()
       if (text) onSubmit(text, setBusy)
     })
-    const showHint = (msg: string) => (hint.textContent = msg)
     ;(composer as HTMLElement & { showHint?: (m: string) => void }).showHint = showHint
+    ;(composer as HTMLElement & { refreshAuth?: () => void }).refreshAuth = renderAuth
 
+    renderAuth()
     actions.append(hint, submit)
-    composer.append(textarea, actions)
+    composer.append(textarea, auth, actions)
     return composer
   }
 
@@ -740,7 +846,7 @@ class InlineComments {
       const composer = this.composerEl("Comment", async (text, setBusy) => {
         setBusy(true)
         try {
-          const token = getToken() ?? (await login(this.cfg))
+          const token = await this.ensureToken()
           const discussionId = await ensureDiscussion(token, this.cfg, this.term, this.state)
           this.state.discussionId = discussionId
           await addComment(token, discussionId, formatBody(anchor, text))
@@ -776,7 +882,7 @@ class InlineComments {
       const composer = this.composerEl("Reply", async (text, setBusy) => {
         setBusy(true)
         try {
-          const token = getToken() ?? (await login(this.cfg))
+          const token = await this.ensureToken()
           const discussionId = this.state.discussionId
           if (!discussionId) throw new Error("missing discussion")
           await addComment(token, discussionId, text, replyTo.id)
diff --git a/quartz/components/styles/inlineComments.scss b/quartz/components/styles/inlineComments.scss
index 3705ad8..cb60a38 100644
--- a/quartz/components/styles/inlineComments.scss
+++ b/quartz/components/styles/inlineComments.scss
@@ -31,7 +31,10 @@
 
 // ─── floating "add comment" button that follows a selection ─────────────
 .inline-comment-add {
-  position: absolute;
+  // must match the `strategy: "fixed"` used by computePosition — with
+  // `absolute` the viewport-relative coords are read as document-relative,
+  // so the button flies off-screen as soon as the page is scrolled.
+  position: fixed;
   z-index: 998;
   display: flex;
   align-items: center;
@@ -185,6 +188,63 @@
       justify-content: space-between;
       gap: 0.5rem;
     }
+
+    // auth row: sign in / who you are, offered inline with the composer
+    & .inline-comment-auth {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 0.5rem;
+      min-height: 1.5rem;
+
+      & .inline-comment-signin {
+        display: flex;
+        align-items: center;
+        gap: 0.4rem;
+        padding: 0.35rem 0.6rem;
+        font-family: var(--bodyFont);
+        font-size: 0.8rem;
+        color: var(--light);
+        background-color: var(--dark);
+        border: none;
+        border-radius: 4px;
+        cursor: pointer;
+
+        &:disabled {
+          opacity: 0.5;
+          cursor: default;
+        }
+      }
+
+      & .inline-comment-whoami {
+        display: flex;
+        align-items: center;
+        gap: 0.35rem;
+        font-size: 0.75rem;
+        color: var(--gray);
+
+        & img {
+          width: 1rem;
+          height: 1rem;
+          border-radius: 50%;
+        }
+      }
+
+      & .inline-comment-signout {
+        font-family: var(--bodyFont);
+        font-size: 0.75rem;
+        color: var(--gray);
+        background: none;
+        border: none;
+        padding: 0;
+        cursor: pointer;
+        text-decoration: underline;
+
+        &:hover {
+          color: var(--secondary);
+        }
+      }
+    }
   }
 
   & button.inline-comment-submit {

From 9bd5ceba1bebebe375cb1a7bfdeb597ef5c7e9e9 Mon Sep 17 00:00:00 2001
From: Corey Petty <corey@status.im>
Date: Mon, 20 Jul 2026 10:49:39 -0400
Subject: [PATCH 4/6] Use a GitHub App so commenters aren't asked for
 public_repo

An OAuth App can only request coarse scopes; the narrowest one permitting
comments on a public repo's Discussions is `public_repo`, which grants
write access to every public repository the commenter owns. That is an
unreasonable ask for a reader who wants to leave one inline note.

A GitHub App's permissions are fixed by the App definition, so a commenter
grants exactly `Discussions: write` on logos-co/assembly and nothing else.

Worker:
- drop `scope` from the authorize URL; App permissions replace it
- pass expires_in / refresh_token through the callback postMessage
- add POST /api/auth/refresh to trade a refresh token for a fresh user
  token, and allow POST in the CORS methods

Client:
- store a session object (token, expiresAt, refreshToken, refreshExpiresAt)
  rather than a bare string, parsing a legacy bare token defensively so
  existing sign-ins are not broken
- refresh silently in ensureToken() with a 60s skew before expiry, falling
  back to the sign-in popup; keep login() free of any preceding await so
  the popup is not blocked
- treat an expired-but-refreshable session as signed in, so the composer
  does not flash signed-out every 8 hours

GitHub Apps are governed by installation rather than the org's OAuth App
access restrictions, so the previous org-approval step is replaced by an
owner installing the App on the repo.

Both configurations work: if the App has token expiration disabled, GitHub
omits the expiry fields and the client treats the token as non-expiring.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs-internal/inline-comments-design.md       |  64 +++++----
 .../scripts/inlineComments.inline.ts          | 122 ++++++++++++++++--
 serverless/inline-comments-worker/README.md   |  75 +++++++----
 .../inline-comments-worker/src/index.ts       | 116 +++++++++++++++--
 4 files changed, 306 insertions(+), 71 deletions(-)

diff --git a/docs-internal/inline-comments-design.md b/docs-internal/inline-comments-design.md
index 1ebd30e..894339e 100644
--- a/docs-internal/inline-comments-design.md
+++ b/docs-internal/inline-comments-design.md
@@ -50,14 +50,17 @@ per-page Discussion** (see "Coexistence").
 ```
 
 The only non-static piece is the **Worker** (Cloudflare Workers / Vercel /
-Netlify function). It does three things and holds the two secrets that can't live
-in the browser:
+Netlify function). It holds the two secrets that can't live in the browser and
+does four things:
 
-1. `GET /api/auth/login` → redirect to GitHub's OAuth authorize URL.
+1. `GET /api/auth/login` → redirect to GitHub's authorize URL (no `scope`; a
+   GitHub App's permissions come from the App definition).
 2. `GET /api/auth/callback` → exchange `code` (+ `client_secret`) for a user
-   access token; return a tiny HTML page that `postMessage`s the token to the
-   opener and closes.
-3. `GET /api/comments` → **anonymous read proxy**. Uses a _server-side_ token so
+   session; return a tiny HTML page that `postMessage`s it to the opener at the
+   state-embedded origin, then closes.
+3. `POST /api/auth/refresh` → exchange a refresh token for a fresh user token,
+   so an expiring GitHub App token renews without a visible re-login.
+4. `GET /api/comments` → **anonymous read proxy**. Uses a _server-side_ token so
    visitors who are not logged in can still see inline highlights. (Giscus solves
    the same problem behind its own backend; here we own it.)
 
@@ -129,22 +132,37 @@ list (the read proxy already returns them).
 
 ## Auth flow (detail)
 
-1. User selects text, clicks "Comment", writes, hits submit while logged out.
-2. Plugin opens a popup to `GET {apiBase}/api/auth/login?redirect=<worker>` with
-   a random `state` (stored in `sessionStorage`).
-3. Worker 302s to `https://github.com/login/oauth/authorize` with `client_id`,
-   `scope=public_repo`, `state`.
-4. GitHub redirects back to `GET {apiBase}/api/auth/callback?code&state`.
-5. Worker exchanges `code` + `client_secret` for a user token, returns HTML that
-   `window.opener.postMessage({ type: "inline-comments-token", token }, origin)`
-   and closes the popup.
-6. Plugin stores the token (`localStorage`, keyed per-origin) and retries the
-   pending submit.
+Identity is a **GitHub App**, not an OAuth App. An OAuth App can only ask for
+coarse scopes — the narrowest that permits commenting on a public repo's
+Discussions is `public_repo`, which grants write access to _every_ public repo
+the commenter owns. That's an unreasonable ask for a drive-by reader. A GitHub
+App's permissions are fixed by the App definition, so a commenter grants exactly
+**`Discussions: write` on `logos-co/assembly`** and nothing else.
 
-Trust model is identical to Giscus/utterances: the user posts **as themselves**
-with their own token; the site never posts on their behalf. `public_repo` is
-sufficient to comment on Discussions of a public repo. (A GitHub **App** with
-fine-grained Discussion write is a stricter alternative — noted as a follow-up.)
+1. User selects text, clicks "Comment", writes, hits submit while logged out.
+2. Plugin opens a popup to `GET {apiBase}/api/auth/login?state=&origin=` with a
+   random `state`.
+3. Worker 302s to `https://github.com/login/oauth/authorize` with `client_id`
+   and `state` — **no `scope`**, since the App defines its own permissions.
+4. GitHub redirects back to `GET {apiBase}/api/auth/callback?code&state`.
+5. Worker exchanges `code` + `client_secret`, returns HTML that
+   `postMessage`s the session to the opener at the state-embedded origin.
+6. Plugin stores the session in `localStorage` and retries the pending submit.
+
+**Token lifetime.** GitHub Apps issue user-to-server tokens that expire (8h by
+default) alongside a refresh token (~6 months). The client stores
+`{ token, expiresAt, refreshToken, refreshExpiresAt }` and refreshes silently
+through `POST {apiBase}/api/auth/refresh` (the worker holds the client secret)
+with a 60s skew so a request can't expire mid-flight. If the App has expiration
+disabled, GitHub omits those fields, `expiresAt` is `null`, and the token is
+treated as non-expiring — both configurations work unchanged.
+
+Trust model is the same as Giscus/utterances: the user posts **as themselves**
+with their own token; the site never posts on their behalf.
+
+The App must be **installed** on the repo by an org owner. This replaces the
+OAuth App access-restriction approval that `logos-co` would otherwise enforce —
+GitHub Apps are governed by installation, not by that policy.
 
 ## Component / config surface
 
@@ -194,7 +212,9 @@ is deployed.
 
 ## Open questions / follow-ups
 
-- GitHub **App** (fine-grained) vs **OAuth App** (`public_repo`) for writes.
+- Server read token is still a fine-grained PAT (tied to a person). Deriving an
+  installation access token from the App's private key would decouple it — needs
+  JWT signing in the worker via Web Crypto.
 - Whether to also render unanchored comments in-plugin and retire Giscus.
 - Fuzzy re-anchoring library choice (`dom-anchor-text-quote` + `diff-match-patch`).
 - Abuse/moderation: rely on GitHub Discussion moderation + repo permissions.
diff --git a/quartz/components/scripts/inlineComments.inline.ts b/quartz/components/scripts/inlineComments.inline.ts
index 91010cb..e5e3802 100644
--- a/quartz/components/scripts/inlineComments.inline.ts
+++ b/quartz/components/scripts/inlineComments.inline.ts
@@ -307,8 +307,88 @@ function displayHTML(bodyHTML: string): string {
 
 // ─── auth ───────────────────────────────────────────────────────────────
 
+// A GitHub App issues user-to-server tokens that expire (8h by default) plus a
+// refresh token (~6 months). If the App has expiration disabled, GitHub omits
+// those fields and `expiresAt` stays null, meaning "never expires".
+type Session = {
+  token: string
+  expiresAt: number | null
+  refreshToken: string | null
+  refreshExpiresAt: number | null
+}
+
+// Refresh this far before actual expiry so a request can't die mid-flight.
+const EXPIRY_SKEW_MS = 60_000
+
+function readSession(): Session | null {
+  const raw = localStorage.getItem(TOKEN_KEY)
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw) as Partial<Session>
+    if (typeof parsed.token !== "string") return null
+    return {
+      token: parsed.token,
+      expiresAt: typeof parsed.expiresAt === "number" ? parsed.expiresAt : null,
+      refreshToken: typeof parsed.refreshToken === "string" ? parsed.refreshToken : null,
+      refreshExpiresAt:
+        typeof parsed.refreshExpiresAt === "number" ? parsed.refreshExpiresAt : null,
+    }
+  } catch {
+    // legacy format: a bare token string from the pre-GitHub-App version
+    return { token: raw, expiresAt: null, refreshToken: null, refreshExpiresAt: null }
+  }
+}
+
+function writeSession(s: Session): void {
+  localStorage.setItem(TOKEN_KEY, JSON.stringify(s))
+}
+
+function isExpired(at: number | null): boolean {
+  return at !== null && Date.now() >= at - EXPIRY_SKEW_MS
+}
+
+// The currently usable token, or null if absent/expired. Callers that can
+// perform a refresh should use InlineComments#ensureToken instead.
 function getToken(): string | null {
-  return localStorage.getItem(TOKEN_KEY)
+  const s = readSession()
+  if (!s || isExpired(s.expiresAt)) return null
+  return s.token
+}
+
+// True when we hold a token that's merely expired but still refreshable —
+// used to keep the composer showing "signed in" rather than flashing signed-out.
+function canRefresh(): boolean {
+  const s = readSession()
+  return !!s?.refreshToken && !isExpired(s.refreshExpiresAt)
+}
+
+function isSignedIn(): boolean {
+  return getToken() !== null || canRefresh()
+}
+
+async function refreshSession(cfg: Config): Promise<string | null> {
+  const s = readSession()
+  if (!s?.refreshToken || isExpired(s.refreshExpiresAt)) return null
+  try {
+    const res = await fetch(`${cfg.apiBase}/api/auth/refresh`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refresh_token: s.refreshToken }),
+    })
+    if (!res.ok) {
+      clearToken()
+      return null
+    }
+    const next = (await res.json()) as Session
+    if (!next?.token) {
+      clearToken()
+      return null
+    }
+    writeSession(next)
+    return next.token
+  } catch {
+    return null
+  }
 }
 
 function clearToken(): void {
@@ -371,7 +451,7 @@ function login(cfg: Config): Promise<string> {
     }
     const onMessage = (e: MessageEvent) => {
       if (e.origin !== apiOrigin) return
-      const data = e.data as { type?: string; token?: string; state?: string }
+      const data = e.data as Partial<Session> & { type?: string; state?: string }
       if (data?.type !== "inline-comments-token") return
       window.removeEventListener("message", onMessage)
       if (data.state && data.state !== state) {
@@ -382,7 +462,12 @@ function login(cfg: Config): Promise<string> {
         reject(new Error("no token returned"))
         return
       }
-      localStorage.setItem(TOKEN_KEY, data.token)
+      writeSession({
+        token: data.token,
+        expiresAt: data.expiresAt ?? null,
+        refreshToken: data.refreshToken ?? null,
+        refreshExpiresAt: data.refreshExpiresAt ?? null,
+      })
       resolve(data.token)
     }
     window.addEventListener("message", onMessage)
@@ -575,12 +660,25 @@ class InlineComments {
     window.addCleanup(fn)
   }
 
-  // Returns a usable token, opening the sign-in popup if needed. `login()`
-  // must be reached synchronously from the originating click or the browser
-  // blocks the popup — hence no awaits before it.
+  // Returns a usable token: the current one, else a silent refresh, else the
+  // sign-in popup.
+  //
+  // `login()` must be reached synchronously from the originating click or the
+  // browser blocks the popup. A refresh is an await, so it is only attempted
+  // when we actually hold a refresh token — otherwise we go straight to
+  // login() with no await in front of it.
   private async ensureToken(): Promise<string> {
     const existing = getToken()
     if (existing) return existing
+
+    if (canRefresh()) {
+      const refreshed = await refreshSession(this.cfg)
+      if (refreshed) return refreshed
+      // refresh failed — fall through to sign-in. The popup may be blocked
+      // here since we've now awaited; the error surfaces in the composer and
+      // a second click (with no refresh token left) opens it cleanly.
+    }
+
     const token = await login(this.cfg)
     await fetchViewer(token)
     return token
@@ -770,8 +868,9 @@ class InlineComments {
 
     const renderAuth = () => {
       auth.replaceChildren()
-      const token = getToken()
-      if (!token) {
+      // an expired-but-refreshable session still counts as signed in, so the
+      // row doesn't flash "signed out" every 8 hours
+      if (!isSignedIn()) {
         const signIn = document.createElement("button")
         signIn.className = "inline-comment-signin"
         signIn.type = "button"
@@ -807,8 +906,11 @@ class InlineComments {
         who.append(avatar, document.createTextNode(`@${viewer.login}`))
       } else {
         who.textContent = "Signed in"
-        // resolve the login lazily, then re-render
-        void fetchViewer(token).then((v) => v && renderAuth())
+        // resolve the login lazily, then re-render. Only possible with a live
+        // token; if it's merely refreshable we'll fill this in after the next
+        // refresh rather than burning a round-trip here.
+        const live = getToken()
+        if (live) void fetchViewer(live).then((v) => v && renderAuth())
       }
       const signOut = document.createElement("button")
       signOut.className = "inline-comment-signout"
diff --git a/serverless/inline-comments-worker/README.md b/serverless/inline-comments-worker/README.md
index 8003d80..72dbc5c 100644
--- a/serverless/inline-comments-worker/README.md
+++ b/serverless/inline-comments-worker/README.md
@@ -5,17 +5,24 @@ It does three things and holds the two secrets that can't live in the browser:
 
 | Route                    | Purpose                                                                   |
 | ------------------------ | ------------------------------------------------------------------------- |
-| `GET /api/auth/login`    | Redirect to GitHub's OAuth authorize URL                                  |
-| `GET /api/auth/callback` | Exchange `code` → user token, `postMessage` it back to the opener         |
+| `GET /api/auth/login`    | Redirect to GitHub's authorize URL                                        |
+| `GET /api/auth/callback` | Exchange `code` → user session, `postMessage` it back to the opener       |
+| `POST /api/auth/refresh` | Exchange a refresh token for a fresh user token                           |
 | `GET /api/comments`      | Anonymous read proxy (server token) so logged-out visitors see highlights |
 
 **Writes never touch this worker** — the browser posts comments straight to
 GitHub's GraphQL API with the signed-in user's own token.
 
-> **Order matters.** The OAuth App's callback URL must contain the worker's
-> URL, and the worker's URL doesn't exist until it's deployed — so deploy
-> first. Deploying without secrets is fine; those endpoints simply error until
-> you add them.
+Auth is a **GitHub App**, not an OAuth App. That matters: an OAuth App would
+have to request the `public_repo` scope, which grants write access to _every_
+public repo the commenter owns. A GitHub App's permissions are fixed by the App
+definition, so commenters grant only **`Discussions: write` on this one repo**.
+No `scope` is sent on the authorize URL as a result.
+
+> **Order matters.** The App's callback URL must contain the worker's URL, and
+> the worker's URL doesn't exist until it's deployed — so deploy first.
+> Deploying without secrets is fine; those endpoints simply error until you
+> add them.
 
 ## 1. Deploy the worker (Cloudflare Workers)
 
@@ -33,28 +40,46 @@ is `name` in `wrangler.toml`. For this repo it is:
 https://inline-comments.inline-assembly.workers.dev
 ```
 
-## 2. Create a GitHub OAuth App
+## 2. Create a GitHub App
 
-<https://github.com/settings/developers> → **New OAuth App**
+Create it **under the `logos-co` org** so ownership isn't tied to one person:
 
-- **Homepage URL:** the site, `https://logos-co.github.io/assembly/`
-- **Authorization callback URL:** the worker URL + `/api/auth/callback`, i.e.
-  `https://inline-comments.inline-assembly.workers.dev/api/auth/callback`
+<https://github.com/organizations/logos-co/settings/apps> → **New GitHub App**
 
-Register, copy the **Client ID**, then **Generate a new client secret** and copy
-it immediately (shown once).
+| Setting                                                    | Value                                                                   |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------- |
+| **GitHub App name**                                        | `Assembly Inline Comments`                                              |
+| **Homepage URL**                                           | `https://logos-co.github.io/assembly/`                                  |
+| **Callback URL**                                           | `https://inline-comments.inline-assembly.workers.dev/api/auth/callback` |
+| **Request user authorization (OAuth) during installation** | ✅ **check this**                                                       |
+| **Expire user authorization tokens**                       | ✅ leave checked (see below)                                            |
+| **Webhook → Active**                                       | ❌ uncheck — we don't use webhooks                                      |
+| **Repository permissions → Discussions**                   | **Read and write**                                                      |
+| **Where can this GitHub App be installed?**                | Only on this account                                                    |
 
-An OAuth App allows only **one** callback URL, so register a **second app** for
-local dev with callback `http://localhost:8787/api/auth/callback`.
+Everything else can stay at its default. Then:
 
-> Scope requested is `public_repo` — enough to comment on Discussions of a
-> public repo. For a stricter setup use a GitHub **App** with fine-grained
-> Discussion write (a follow-up in the design doc).
+1. **Create GitHub App.**
+2. Copy the **Client ID** (`Iv23li…`) and **Generate a new client secret** —
+   copy it immediately, it's shown once.
+3. **Install App** → install it on **`logos-co/assembly`** (choosing "Only
+   select repositories" and picking just that repo). Without this install step
+   the App can't touch the repo's Discussions.
+
+Add a **second callback URL** on the same App for local dev —
+`http://localhost:8787/api/auth/callback`. Unlike OAuth Apps, a GitHub App
+accepts multiple callback URLs, so one App covers both prod and dev.
+
+> **On token expiration.** With "Expire user authorization tokens" enabled,
+> user tokens last 8 hours and come with a ~6-month refresh token; the client
+> refreshes silently via `POST /api/auth/refresh`. If you disable expiration,
+> GitHub omits those fields and the client treats the token as non-expiring —
+> both paths work, so keep the secure default.
 >
-> `logos-co` is an org: if it enforces third-party application restrictions, an
-> owner must approve the app or posting will fail for members. Registering the
-> app **under the org** (Org Settings → Developer settings → OAuth Apps) avoids
-> tying ownership to one person's account.
+> A GitHub App is **not** subject to the org's OAuth App access restrictions;
+> it's governed by installation instead. That's why the previous "org must
+> approve the OAuth App" step is gone — installing it (step 3) is the
+> equivalent, and an org owner does it once.
 
 ## 3. Create the server read token
 
@@ -86,7 +111,7 @@ npm run dev                      # serves on http://localhost:8787
 
 `ALLOWED_ORIGINS` already includes `http://localhost:8080` (Quartz's dev server).
 
-## 4. Point Quartz at the worker
+## 5. Point Quartz at the worker
 
 In `quartz.layout.ts`:
 
@@ -98,8 +123,8 @@ Component.InlineComments({
     repoId: "R_kgDOQUhKqA",
     category: "Announcements",
     categoryId: "DIC_kwDOQUhKqM4Cxur2",
-    apiBase: "https://inline-comments.<you>.workers.dev",
-    mapping: "pathname",
+    apiBase: "https://inline-comments.inline-assembly.workers.dev",
+    mapping: "url", // must match giscus's mapping to share a discussion
   },
 })
 ```
diff --git a/serverless/inline-comments-worker/src/index.ts b/serverless/inline-comments-worker/src/index.ts
index 96f7e38..f1fb311 100644
--- a/serverless/inline-comments-worker/src/index.ts
+++ b/serverless/inline-comments-worker/src/index.ts
@@ -1,18 +1,29 @@
 // Inline Comments worker — the only non-static piece of the system.
 //
+// Auth is a **GitHub App** (not an OAuth App): permissions come from the App
+// definition, so users are asked for fine-grained `Discussions: write` on the
+// one repo the App is installed on — never `public_repo` across every public
+// repo they own. Consequently no `scope` is sent on the authorize URL.
+//
+// GitHub Apps issue user-to-server tokens that expire (8h by default) with a
+// refresh token (~6 months), hence /api/auth/refresh. If the App has token
+// expiration disabled, GitHub simply omits those fields and everything still
+// works — the client treats a missing expiry as "never expires".
+//
 // Endpoints:
-//   GET /api/auth/login?state=&origin=   → 302 to GitHub's OAuth authorize URL
-//   GET /api/auth/callback?code=&state=  → exchange code → postMessage token to opener
-//   GET /api/comments?repo=&category=&term=
+//   GET  /api/auth/login?state=&origin=  → 302 to GitHub's authorize URL
+//   GET  /api/auth/callback?code=&state= → exchange code → postMessage session to opener
+//   POST /api/auth/refresh               → refresh_token → new session (CORS)
+//   GET  /api/comments?repo=&category=&term=
 //                                        → anonymous read proxy (server token) so
 //                                          logged-out visitors can see highlights
 //
-// Secrets (wrangler secret put ...):
-//   GITHUB_CLIENT_ID       OAuth App client id
-//   GITHUB_CLIENT_SECRET   OAuth App client secret
+// Secrets (wrangler secret put ..., or the Cloudflare dashboard as encrypted):
+//   GITHUB_CLIENT_ID       GitHub App client id (Iv23li…)
+//   GITHUB_CLIENT_SECRET   GitHub App client secret
 //   GITHUB_TOKEN           server read token (fine-grained PAT: Discussions read)
 // Vars (wrangler.toml [vars]):
-//   ALLOWED_ORIGINS        comma-separated site origins, e.g. "https://assembly.logos.co"
+//   ALLOWED_ORIGINS        comma-separated site origins, e.g. "https://logos-co.github.io"
 
 export interface Env {
   GITHUB_CLIENT_ID: string
@@ -43,7 +54,7 @@ function corsHeaders(origin: string, env: Env): Record<string, string> {
   return {
     "Access-Control-Allow-Origin": allow,
     "Access-Control-Allow-Headers": "Authorization, Content-Type",
-    "Access-Control-Allow-Methods": "GET, OPTIONS",
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
     Vary: "Origin",
   }
 }
@@ -92,7 +103,9 @@ function handleLogin(url: URL, env: Env): Response {
   const authorize = new URL("https://github.com/login/oauth/authorize")
   authorize.searchParams.set("client_id", env.GITHUB_CLIENT_ID)
   authorize.searchParams.set("redirect_uri", redirectUri)
-  authorize.searchParams.set("scope", "public_repo")
+  // NOTE: deliberately no `scope` — a GitHub App's permissions are fixed by
+  // the App definition. Sending a scope here is what made the OAuth App ask
+  // for `public_repo` across all of the user's public repositories.
   authorize.searchParams.set("state", ghState)
   authorize.searchParams.set("allow_signup", "true")
   return Response.redirect(authorize.toString(), 302)
@@ -100,12 +113,42 @@ function handleLogin(url: URL, env: Env): Response {
 
 // ─── auth: callback ───────────────────────────────────────────────────────
 
-function callbackPage(token: string, clientState: string, origin: string): Response {
+// GitHub's token response. `expires_in` / `refresh_token` are present only
+// when the App has expiring user tokens enabled (the default for new Apps).
+type TokenResponse = {
+  access_token?: string
+  expires_in?: number
+  refresh_token?: string
+  refresh_token_expires_in?: number
+  error?: string
+  error_description?: string
+}
+
+// Absolute epoch-ms expiry, or null when the token never expires.
+function absoluteExpiry(seconds: number | undefined, now: number): number | null {
+  return typeof seconds === "number" ? now + seconds * 1000 : null
+}
+
+function sessionFrom(t: TokenResponse, now: number) {
+  return {
+    token: t.access_token,
+    expiresAt: absoluteExpiry(t.expires_in, now),
+    refreshToken: t.refresh_token ?? null,
+    refreshExpiresAt: absoluteExpiry(t.refresh_token_expires_in, now),
+  }
+}
+
+function callbackPage(
+  t: TokenResponse,
+  clientState: string,
+  origin: string,
+  now: number,
+): Response {
   // JSON-encode + neutralize "</script>" so nothing can break out of the tag.
   const payload = JSON.stringify({
     type: "inline-comments-token",
-    token,
     state: clientState,
+    ...sessionFrom(t, now),
   }).replace(/</g, "\\u003c")
   const targetOrigin = JSON.stringify(origin).replace(/</g, "\\u003c")
   const html = `<!doctype html><meta charset="utf-8"><title>Signing in…</title>
@@ -148,11 +191,53 @@ async function handleCallback(url: URL, env: Env): Promise<Response> {
       redirect_uri: `${url.origin}/api/auth/callback`,
     }),
   })
-  const tokenJson = (await res.json()) as { access_token?: string; error?: string }
+  const tokenJson = (await res.json()) as TokenResponse
   if (!tokenJson.access_token) {
-    return new Response(`oauth error: ${tokenJson.error ?? "unknown"}`, { status: 400 })
+    const detail = tokenJson.error_description ?? tokenJson.error ?? "unknown"
+    return new Response(`oauth error: ${detail}`, { status: 400 })
   }
-  return callbackPage(tokenJson.access_token, clientState, origin)
+  return callbackPage(tokenJson, clientState, origin, Date.now())
+}
+
+// ─── auth: refresh ────────────────────────────────────────────────────────
+
+// Exchanges a refresh token for a fresh user-to-server token. Needs the client
+// secret, which is why it lives here rather than in the browser.
+async function handleRefresh(request: Request, env: Env): Promise<Response> {
+  const origin = request.headers.get("Origin") ?? ""
+  const cors = corsHeaders(origin, env)
+  if (!isAllowed(origin, env)) return json({ error: "origin not allowed" }, 403, cors)
+
+  let refreshToken = ""
+  try {
+    const body = (await request.json()) as { refresh_token?: string }
+    refreshToken = body.refresh_token ?? ""
+  } catch {
+    return json({ error: "invalid body" }, 400, cors)
+  }
+  if (!refreshToken) return json({ error: "missing refresh_token" }, 400, cors)
+
+  const res = await fetch("https://github.com/login/oauth/access_token", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+    },
+    body: JSON.stringify({
+      client_id: env.GITHUB_CLIENT_ID,
+      client_secret: env.GITHUB_CLIENT_SECRET,
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+    }),
+  })
+  const tokenJson = (await res.json()) as TokenResponse
+  if (!tokenJson.access_token) {
+    // refresh token expired or revoked — the client should re-run sign-in
+    const detail = tokenJson.error_description ?? tokenJson.error ?? "unknown"
+    return json({ error: detail }, 401, cors)
+  }
+  return json(sessionFrom(tokenJson, Date.now()), 200, cors)
 }
 
 // ─── read proxy: comments ──────────────────────────────────────────────────
@@ -273,6 +358,9 @@ export default {
         return handleLogin(url, env)
       case "/api/auth/callback":
         return handleCallback(url, env)
+      case "/api/auth/refresh":
+        if (request.method !== "POST") return new Response("method not allowed", { status: 405 })
+        return handleRefresh(request, env)
       case "/api/comments":
         return handleComments(request, url, env)
       default:

From 86468798b2a2807cdcfb4864e49a2151e04014ce Mon Sep 17 00:00:00 2001
From: Corey Petty <corey@status.im>
Date: Mon, 20 Jul 2026 11:16:37 -0400
Subject: [PATCH 5/6] Pick the populated discussion when titles collide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Giscus can race and create two discussions with the same title for one
page — #11 and #12 in this repo are exactly that, created 35 seconds
apart, one holding both comments and the other empty.

handleComments took the first title match from the search results. Search
ordering is not guaranteed, so landing on the empty twin would render a
page with no comments and no error to explain it. Today the ordering
happens to favour the populated one, which is luck rather than a
guarantee.

Select by comment count instead, tie-breaking on the lower discussion
number so repeated reads are stable. Requires totalCount in the query.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 serverless/inline-comments-worker/src/index.ts | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/serverless/inline-comments-worker/src/index.ts b/serverless/inline-comments-worker/src/index.ts
index f1fb311..74acc1e 100644
--- a/serverless/inline-comments-worker/src/index.ts
+++ b/serverless/inline-comments-worker/src/index.ts
@@ -257,7 +257,7 @@ type GHDiscussion = {
   number: number
   title: string
   category: { name: string }
-  comments: { nodes: GHComment[] }
+  comments: { totalCount: number; nodes: GHComment[] }
 }
 
 const SEARCH_DISCUSSION = `
@@ -270,6 +270,7 @@ query ($q: String!) {
         title
         category { name }
         comments(first: 100) {
+          totalCount
           nodes {
             id url createdAt bodyHTML body
             author { login avatarUrl }
@@ -320,12 +321,22 @@ async function handleComments(request: Request, url: URL, env: Env): Promise<Res
         q,
       },
     )
-    const match = data.search.nodes.find(
+    const matches = data.search.nodes.filter(
       (d) => d && d.title === term && (!category || d.category?.name === category),
     )
-    if (!match) {
+    if (matches.length === 0) {
       return json({ discussionId: null, discussionNumber: null, comments: [] }, 200, cors)
     }
+    // Two discussions can share a title — giscus races and creates a duplicate
+    // if a page is opened twice at once (see #11/#12 in this repo). Search
+    // order is not guaranteed, so picking the first match could silently land
+    // on the empty twin and show no comments at all. Prefer the one actually
+    // holding the conversation, tie-breaking on the lower number for stability.
+    const match = matches.reduce((best, d) => {
+      const better = d.comments.totalCount > best.comments.totalCount
+      const tie = d.comments.totalCount === best.comments.totalCount && d.number < best.number
+      return better || tie ? d : best
+    })
     return json(
       {
         discussionId: match.id,

From c0b258528e624fc76eb15922515f7b1111e2d37e Mon Sep 17 00:00:00 2001
From: Corey Petty <corey@status.im>
Date: Mon, 20 Jul 2026 12:08:11 -0400
Subject: [PATCH 6/6] Document the inline comments -> Quartz 5 plugin migration

Records what was verified against quartz-community/explorer: the anchoring
engine, both SPA globals, the component resource API and SCSS handling all
survive v5 unchanged, and the worker needs no changes at all. The changes
are mechanical - import paths, and layout position moving from
quartz.layout.ts into the package.json quartz manifest.

Also captures the open questions to resolve during the port, notably
whether the anchoring root is still article.popover-hint, and a carry-over
checklist so the v5 migration does not drop the worker or docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../inline-comments-v5-plugin-migration.md    | 174 ++++++++++++++++++
 1 file changed, 174 insertions(+)
 create mode 100644 docs-internal/inline-comments-v5-plugin-migration.md

diff --git a/docs-internal/inline-comments-v5-plugin-migration.md b/docs-internal/inline-comments-v5-plugin-migration.md
new file mode 100644
index 0000000..f6037fc
--- /dev/null
+++ b/docs-internal/inline-comments-v5-plugin-migration.md
@@ -0,0 +1,174 @@
+# Migrating Inline Comments to a Standalone Quartz 5 Plugin
+
+> Status: **planned**
+> Prerequisite: the site is migrated to Quartz 5 (see [migrating](https://quartz.jzhao.xyz/getting-started/migrating))
+> Companion: [inline-comments-design.md](./inline-comments-design.md)
+
+## Why
+
+In v4 this feature lives *inside* the site repo as a custom component
+(`quartz/components/InlineComments.tsx` + inline script + SCSS), wired up by
+hand in `quartz.layout.ts`. Porting it to another site means copying files,
+which drifts.
+
+Quartz 5 replaces that model: components are **standalone Git repositories**
+installed with `npx quartz plugin add`. That is exactly the right shape for
+this feature, and it turns "port it to another site" into one command.
+
+## Findings: what actually changes
+
+Verified against a real v5 community plugin
+([`quartz-community/explorer`](https://github.com/quartz-community/explorer)),
+not just the docs.
+
+### Survives unchanged
+
+- **The whole anchoring engine.** `inlineComments.inline.ts` is plain DOM/TS
+  whose only external import is `@floating-ui/dom`.
+- **Both SPA globals we depend on.** Confirmed present in v5 —
+  `window.addCleanup(...)` and `document.addEventListener("nav", ...)` are both
+  used by explorer's own inline script.
+- **The component resource API.** `Component.css = style` and
+  `Component.afterDOMLoaded = script` are identical in v5, as is
+  `satisfies QuartzComponentConstructor`.
+- **SCSS.** `tsup.config.ts` compiles `.scss` through `sass` and `.inline.ts`
+  through a nested esbuild pass, both loaded as text — same mental model as v4.
+- **The worker.** `serverless/inline-comments-worker/` needs **zero changes**;
+  it is independent infrastructure that only speaks HTTP.
+
+### Mechanical changes
+
+| v4 | v5 |
+| --- | --- |
+| `import ... from "./types"` | `from "@quartz-community/types"` |
+| `classNames` from `../util/lang` | `@quartz-community/utils/lang`, or vendor a local copy (explorer vendors its own) |
+| `import script from "./scripts/x.inline"` | `"./scripts/x.inline.ts"` with `// @ts-expect-error` |
+| Wiring in `quartz.layout.ts` | `quartz` manifest block in `package.json` |
+| Options as a TS object | YAML `options:` validated by `optionSchema` |
+
+> Do **not** import from `@jackyzha0/quartz` or `vfile` directly — the v5 plugin
+> docs call this out explicitly. Use the `@quartz-community/*` packages.
+
+## Target repo layout
+
+Mirrors `quartz-community/explorer`:
+
+```
+quartz-inline-comments/
+├── src/
+│   ├── index.ts                       # export { default as InlineComments }
+│   └── components/
+│       ├── InlineComments.tsx
+│       ├── scripts/inlineComments.inline.ts
+│       └── styles/inlineComments.scss
+├── types/globals.d.ts                 # addCleanup, CustomEventMap, *.scss module
+├── package.json                       # deps + the `quartz` manifest block
+├── tsup.config.ts                     # scss + .inline.ts esbuild loaders
+├── tsconfig.json / tsconfig.build.json
+└── README.md
+```
+
+### The manifest
+
+Layout position lives in `package.json`, not in any layout file:
+
+```jsonc
+"quartz": {
+  "name": "inline-comments",
+  "displayName": "Inline Comments",
+  "category": "component",
+  "quartzVersion": ">=5.0.0",
+  "defaultEnabled": true,
+  "defaultOrder": 50,
+  "components": {
+    "InlineComments": {
+      "displayName": "Inline Comments",
+      "defaultPosition": "afterBody",
+      "defaultPriority": 50
+    }
+  },
+  "optionSchema": {
+    "repo":       { "type": "string" },
+    "repoId":     { "type": "string" },
+    "category":   { "type": "string" },
+    "categoryId": { "type": "string" },
+    "apiBase":    { "type": "string" },
+    "mapping":    { "type": "enum", "values": ["url", "pathname", "title"] }
+  }
+}
+```
+
+All existing options are plain strings, so they survive the move to YAML
+unchanged — no option needs restructuring.
+
+### Dependencies
+
+```jsonc
+"dependencies": {
+  "@quartz-community/types": "github:quartz-community/types",
+  "@quartz-community/utils": "github:quartz-community/utils"
+},
+"peerDependencies": { "preact": "^10.0.0" }
+```
+
+`@floating-ui/dom` becomes a real dependency of the plugin (in v4 we relied on
+it being a stock Quartz dep — a plugin cannot assume that).
+
+## Consumer experience
+
+```sh
+npx quartz plugin add github:logos-co/quartz-inline-comments
+```
+
+```yaml
+plugins:
+  - source: github:logos-co/quartz-inline-comments
+    enabled: true
+    options:
+      repo: logos-co/assembly
+      repoId: R_kgDOQUhKqA
+      category: Announcements
+      categoryId: DIC_kwDOQUhKqM4Cxur2
+      apiBase: https://inline-comments.inline-assembly.workers.dev
+      mapping: url
+```
+
+Any Quartz 5 site can then adopt this in one command. The worker can be shared
+across sites (add the new origin to `ALLOWED_ORIGINS`, install the GitHub App on
+the new repo, widen the read PAT) or deployed per-site.
+
+## Open questions to resolve during the port
+
+1. **Is the anchoring root still `<article class="popover-hint">`?**
+   `getRoot()` depends on it. Explorer is a sidebar component so it tells us
+   nothing here. This is the single highest-risk unknown; if the markup changed
+   it is a one-line fix, but it must be checked on a running v5 site.
+2. **Does `dist/` need to be committed?** Explorer commits its `dist/`, and
+   `quartz plugin add` installs over git rather than npm, which implies built
+   output must be present in the repo. Confirm on first install; if so, add a
+   CI workflow that builds and commits `dist/` on release.
+3. **Does `optionSchema` support required fields / defaults?** `repo`, `repoId`
+   and `apiBase` have no sensible default; ideally the schema can mark them
+   required rather than failing at runtime.
+4. **Where should the repo live?** Under `logos-co`, or published to
+   `quartz-community` so other Quartz sites can use it.
+
+## Sequencing
+
+1. Migrate the site to Quartz 5 on a branch (production stays on v4).
+2. Build the plugin repo and validate against that branch.
+3. `quartz plugin add` it, configure in `quartz.config.yaml`, verify end to end.
+4. Cut production over.
+
+The feature is offline between the moment `quartz.layout.ts` disappears and the
+moment the plugin is installed — which is why the v5 work belongs on a branch.
+
+## Carry-over checklist
+
+Beyond the component itself, these must survive the v5 migration:
+
+- [ ] `serverless/inline-comments-worker/` (unchanged, but must not be lost)
+- [ ] `docs-internal/` (this file and the design doc)
+- [ ] `.gitignore` rules protecting `.dev.vars` and `.wrangler/`
+- [ ] Worker `ALLOWED_ORIGINS` still matches the production origin
+- [ ] CI deploy workflow retargeted from `v4` to the new default branch