blume 2.1.0 → 2.1.2

package/skills/blume-migrate/references/starlight.md

@@ -21,17 +21,17 @@ Keep content where it is — set `content.root: "src/content/docs"`.
 | `logo` (`{ src }` or `{ light, dark, alt }`) | `logo` — move the referenced file into `public/` |
 | `logo.replacesTitle` | `logo: { text: "" }` (renders the mark alone) |
 | `favicon` | copy the file into `public/` (drop the config field — Blume auto-detects) |
-| `social` (array of `{ label, icon, href }`; pre-0.33 legacy: `{ github: url }` object) | derive **`github: { owner, repo }`** from the GitHub entry; other socials drop (report) |
+| `social` (array of `{ label, icon, href }`; pre-0.33 legacy: `{ github: url }` object) | derive **`github: { owner, repo }`** from the GitHub entry; every other entry whose platform Blume knows → **`footer.socials`** (`{ discord: href, bluesky: href, … }`; the `x.com`/`twitter` icon → `x`; the platform list is under `footer` in `docs/configuration/index.mdx`); the rest (`mastodon`, `gitlab`, `rss`, …) drop (report) |
 | `editLink.baseUrl` (`…/edit/<branch>/<subdir?>`) | `github: { owner, repo, branch }` — **and any repo sub-path after the branch → `github.dir`** (a docs-in-subfolder repo breaks every edit link without it); **an origin other than `https://github.com` → `github.host`** (a GitHub Enterprise repo otherwise links to the public site) |
 | `sidebar` (array) | filesystem nav / `navigation.sidebar` (see below) |
 | `tableOfContents` (`false` or `{ minHeadingLevel, maxHeadingLevel }`) | `toc` — identical shape, 1:1 |
 | `markdown.headingLinks: false` | `markdown.headingAnchors: false` |
 | `expressiveCode.themes` | `markdown.code.theme: { light, dark }` — EC assigns by theme _type_, so match each theme by its darkness, not by array position |
 | `expressiveCode.styleOverrides` | drop → restyle via a root `theme.css` file |
-| `head` | **drop and report** (there is no `seo.metatags`); analytics `<script>` entries → one `script()` adapter each in the `analytics` list (from `blume/analytics`): `attrs.src` → `src`, an `async`/`defer` attr → `strategy`, every other `attrs` key → `attributes`, and an inline body (`content`) → `content` |
+| `head` | per entry: a `meta` tag → **`seo.metatags`** (`{ [attrs.name ?? attrs.property]: attrs.content }` — verification tokens, `theme-color`, and the like), minus the tags Blume writes itself (`description`, `robots`, `og:title`/`og:description`/`og:image`/`og:url`/`og:type`/`og:site_name`, `twitter:*` card tags, `article:*` dates — the build refuses them and names the setting that owns each, e.g. `og:image` → `seo.og`, `twitter:site` → `seo.x.handle`); an analytics `<script>` → one `script()` adapter each in the `analytics` list (from `blume/analytics`): `attrs.src` → `src`, an `async`/`defer` attr → `strategy`, every other `attrs` key → `attributes`, and an inline body (`content`) → `content`; anything else (`link`, `style`, other scripts) → drop and report |
 | `lastUpdated: true` | `lastModified: "git"` |
 | `customCss` | drop → move into a root **`theme.css`** file (auto-picked-up; not a config field) |
-| `components` (overrides) | Blume's layout slots via `defineComponents({ layout: { Header, Search, Sidebar, TableOfContents, Footer, … } })` — a near-1:1 map; reach for `blume eject` only beyond those |
+| `components` (overrides) | Blume's layout slots via `defineComponents({ layout: { … } })` in a root `components.ts`: `Header`, `Search`, `Sidebar`, `TableOfContents`, `Pagination` keep their names; `SiteTitle` → `Logo`; **`Footer` → `PageFooter`**, not Blume's `Footer` (that slot is the site footer; Starlight's `Footer` is the page-end last-updated date, pagination, and edit link, which Blume renders itself, so keep only what the override added). Other overrides (`Banner`, `PageTitle`, `Hero`, `EditLink`, `SocialIcons`, …) have no slot — fold their additions into `PageHeader`/`PageFooter`, or `blume eject`; a Starlight name left under `layout` matches no slot and does nothing. Rewrite reads of `Astro.locals.starlightRoute` against the slot's props |
 | `plugins` | **map, don't blanket-drop** — see Plugins below |
 | `pagination: false`, `pagefind`/Pagefind options, `titleDelimiter`, `credits`, `disable404Route`, `routeMiddleware` | drop (report) |
 | `locales` / `defaultLocale` | `i18n` (see below) |
@@ -40,7 +40,7 @@ Keep content where it is — set `content.root: "src/content/docs"`.
 
 Starlight's `sidebar` array → prefer letting Blume generate from the filesystem; use `navigation.sidebar` only for shapes files can't express:
 
-- `{ label, autogenerate: { directory: "d" } }` → **structure the folder and rely on filesystem nav** (label → the folder's `meta.ts` `title`). Do **not** map it to a sidebar item with `root:` — in an explicit Blume sidebar that renders a single page link, not the directory's children.
+- `{ label, items: [{ autogenerate: { directory: "d" } }] }` (0.39 and later; before 0.39 the group held it directly, `{ label, autogenerate: { directory: "d" } }`) → **structure the folder and rely on filesystem nav** (label → the folder's `meta.ts` `title`; `autogenerate.collapsed` → `collapsed: true` in each subfolder's `meta.ts`). Do **not** map it to a sidebar item with `root:` — in an explicit Blume sidebar that renders a single page link, not the directory's children. Since 0.39 a group's `items` can mix manual entries with an `autogenerate` entry; move those manual pages into the folder (route change → `redirects`) so the folder holds the whole group.
 - string `"guides/intro"` → `"/guides/intro"`; `{ label?, slug }` → `/<slug>`.
 - `{ label, items: [...] }` → `{ label, items: [...] }` (recursive) — or better, a real folder.
 - `{ label?, link }` → `{ label, href: link }`.
@@ -59,7 +59,8 @@ Starlight's `sidebar` array → prefer letting Blume generate from the filesyste
 | `lastUpdated: false` (boolean) | **remove** (Blume's `lastModified` takes a date; a boolean is a build error) |
 | `prev: false` **and** `next: false` | `pagination: false` (hides both links) |
 | `prev` / `next` otherwise (one side, or a label/link) | **drop** (report — the links can only be hidden together, and their labels come from the linked pages) |
-| `template: splash` / `hero` | **no equivalent** — rebuild as a custom `.astro` page under `content.pages`; a `hero` on a normal page drops (report) |
+| `template: splash` | `mode: center` (no sidebar, a wider centered column — the closest layout; report) |
+| `hero` | **no key** — its tagline → a paragraph, its actions → `<Card>`s or links, its image → a Markdown image (report); for a designed landing page, rebuild it as a custom `.astro` page under `content.pages` (`pages/index.astro` on `PageLayout` wins over the content page) |
 | `banner`, `tableOfContents`, `editUrl`, `head` | drop (report) |
 
 ## Asides → directives (and the `.md` trap)
@@ -83,7 +84,8 @@ Starlight content is full of Expressive Code fence meta; Blume understands some
 - `title="file.js"` → works as-is (or use the space-title shorthand). Line ranges `{2-3}` → work as-is.
 - `ins=`/`del=` line marks → `// [!code ++]` / `// [!code --]` comments; `mark=` → `{ranges}` or `// [!code highlight]`.
 - `showLineNumbers` → `lineNumbers`.
-- **Drop:** `frame="terminal"`, `collapse=`, `wrap`, `"string"` and `/regex/` text markers (report if they carried meaning).
+- `wrap` / `wrap=true` → a bare `wrap` (that block's long lines wrap); a site-wide `expressiveCode.defaultProps.wrap: true` → `markdown.code.wrap: true`.
+- **Drop:** `frame="terminal"`, `collapse=`, `wrap=false`, `preserveIndent`/`hangingIndent`, `"string"` and `/regex/` text markers (report if they carried meaning).
 - ` ```diff lang="js" ` → a normal ` ```js ` fence with `[!code ++]`/`[!code --]` markers.
 
 ## Plugins — map, don't drop
@@ -114,4 +116,4 @@ Remove `@astrojs/starlight` (and plugin deps) from deps, delete the Starlight bi
 
 ## Dropped — report these
 
-Non-GitHub socials, badge variants, sidebar/item `attrs` + `translations`, `customCss` beyond `theme.css`, `head` entries, `routeMiddleware`, splash/hero pages (rebuild as custom pages), starlight-blog's tag and author pages, aside custom icons, EC frames/collapse/text markers, prev/next toggles, unmapped plugins, any `<Icon>` name with no Lucide equivalent.
+Socials on a platform `footer.socials` lacks, badge variants, sidebar/item `attrs` + `translations`, `customCss` beyond `theme.css`, `head` entries other than meta tags and analytics scripts, a page's frontmatter `head`, `routeMiddleware`, splash layouts approximated with `mode: center` and hero blocks rebuilt as content, override components with no Blume slot, starlight-blog's tag and author pages, aside custom icons, EC frames/collapse/text markers, prev/next toggles, unmapped plugins, any `<Icon>` name with no Lucide equivalent.

package/src/ai/ask-context.ts

@@ -622,10 +622,37 @@ export interface ReaderScope {
   filters: { locale: string | undefined; version: string | undefined };
 }
 
+// The snapshot's locale codes, keyed lowercase, built once per snapshot.
+const localeCodes = new WeakMap<AskData, Map<string, string>>();
+
+/**
+ * The locale a path's first segment names (`/ja` or `/ja/pricing` → `ja`),
+ * when it's one the snapshot's documents carry: a page outside the docs,
+ * like a localized landing page, still says which language it's in.
+ */
+const pathLocale = (data: AskData, path: string): string | undefined => {
+  let codes = localeCodes.get(data);
+  if (!codes) {
+    codes = new Map<string, string>();
+    for (const { locale } of data.documents) {
+      if (locale) {
+        codes.set(locale.toLowerCase(), locale);
+      }
+    }
+    localeCodes.set(data, codes);
+  }
+  const [, first = ""] = normalizeRoute(path).split("/");
+  return first ? codes.get(first.toLowerCase()) : undefined;
+};
+
 /**
  * Where the reader is: their page, when it's in the snapshot, and the locale
- * and docs version retrieval keeps to. Without a page, a versioned site
- * grounds in the current docs rather than every archived copy of each page.
+ * and docs version retrieval keeps to. A page the snapshot doesn't have (the
+ * homepage, a custom page, or none at all from a cross-origin caller) keeps
+ * to the locale its path's first segment names, or the default locale, so
+ * translations of every page don't crowd each other out. Without a page, a
+ * versioned site grounds in the current docs rather than every archived copy
+ * of each page.
  */
 export const readerScope = (
   data: AskData,
@@ -635,10 +662,13 @@ export const readerScope = (
   const current = page?.path
     ? byRoute.get(normalizeRoute(page.path))
     : undefined;
+  const locale = current
+    ? current.locale
+    : (page?.path && pathLocale(data, page.path)) || data.defaultLocale;
   return {
     current,
     filters: {
-      locale: current?.locale || undefined,
+      locale: locale || undefined,
       version: data.versioned ? (current?.version ?? "") : undefined,
     },
   };

package/src/ai/ask-limits.ts

@@ -0,0 +1,13 @@
+/**
+ * What one request to the assistant's generated route (`/api/ask`) may carry.
+ * The route answers a longer conversation with a `400` (see
+ * `askEndpointTemplate`), so the panel's client (`useAssistant`) sends only
+ * the latest turns that fit. The endpoint is unauthenticated, so the limits
+ * bound what one request can spend against the model.
+ */
+
+/** The most messages, questions and answers together, one request sends. */
+export const ASK_MAX_MESSAGES = 40;
+
+/** The most characters the messages take as JSON (`JSON.stringify`). */
+export const ASK_MAX_MESSAGES_CHARS = 24_000;

package/src/ai/ask.ts

@@ -110,7 +110,8 @@ export interface AssistantGatewayOptions extends AssistantAdapterOptions {
    * How much the model reasons before answering. Sent as the AI SDK's
    * top-level `reasoning` option, which the gateway maps to the model's own
    * control (OpenAI's `reasoning_effort`, for example); the model has to
-   * offer the level you pick. Omitted keeps the model's default.
+   * offer the level you pick. Omitted keeps the model's default. Assistant
+   * only.
    */
   reasoning?: AssistantReasoning;
   /** Narration only: the speech model's voice. Defaults to `alloy`. */
@@ -153,32 +154,47 @@ export const gateway = (
 // openai()
 // ---------------------------------------------------------------------------
 
-const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
+export const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
 
 /** Options for {@link openai}. */
 export interface AssistantOpenAIOptions extends AssistantAdapterOptions {
+  /**
+   * Name of the env var holding the key. Defaults to `OPENAI_API_KEY`, except
+   * for narration with a `baseUrl`, which sends only a key named here.
+   */
+  apiKeyEnv?: string;
   /**
    * An OpenAI-compatible endpoint to call instead of OpenAI
    * (`https://llm.internal.example.com/v1`): a self-hosted model or an
    * internal gateway. The route then talks Chat Completions through
    * `@ai-sdk/openai-compatible`, and the docs tools are off unless
    * `ai.assistant.tools` turns them on, since the model may not call tools.
+   * For narration, a server with OpenAI's speech API (`/audio/speech`),
+   * called through `@ai-sdk/openai` and sent only the key `apiKeyEnv` names,
+   * if any.
    */
   baseUrl?: string;
-  /** The model id (`gpt-5.5`). */
+  /**
+   * Narration only: how the voice should sound, for speech models that take
+   * instructions ("Read calmly, like a teacher").
+   */
+  instructions?: string;
+  /** The model id (`gpt-5.5`, or a speech model like `gpt-4o-mini-tts`). */
   model: string;
   /**
    * The provider name the AI SDK reports, which a custom endpoint also reads
    * its `providerOptions` under. Defaults to `openai`, or `openai-compatible`
-   * with a `baseUrl`.
+   * with a `baseUrl`. Assistant only.
    */
   name?: string;
   /**
    * How much the model reasons before answering, sent as `reasoning_effort`;
    * with a `baseUrl`, the endpoint has to accept that parameter. Omitted
-   * keeps the model's default.
+   * keeps the model's default. Assistant only.
    */
   reasoning?: AssistantReasoning;
+  /** Narration only: the speech model's voice. Defaults to `alloy`. */
+  voice?: string;
 }
 
 const openaiOptionsSchema = z.strictObject({
@@ -203,7 +219,9 @@ export const openaiAdapterSchema = adapterDescriptorSchema(
  * Route the assistant to OpenAI, or to any OpenAI-compatible endpoint with
  * `baseUrl`. Reads `OPENAI_API_KEY` and needs `@ai-sdk/openai` installed; a
  * custom endpoint needs `@ai-sdk/openai-compatible` instead, since most
- * don't serve OpenAI's Responses API.
+ * don't serve OpenAI's Responses API. Narration generates audio with it
+ * through `@ai-sdk/openai` either way, and with a `baseUrl` sends only the key
+ * `apiKeyEnv` names.
  */
 export const openai = (
   options: AssistantOpenAIOptions

package/src/ai/changelog-markdown.ts

@@ -1,4 +1,5 @@
 import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
+import { withChangelogIndexText } from "../core/changelog-index.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { absoluteUrl } from "../core/site-url.ts";
@@ -45,12 +46,16 @@ const rowLine = (project: BlumeProject, { date, page }: IndexRow): string => {
 
 export const buildChangelogIndexMarkdown = (project: BlumeProject): string => {
   const { i18n } = project.config;
-  const ui = i18n
-    ? resolveUIStrings(i18n.defaultLocale, {
-        defaultLocale: i18n.defaultLocale,
-        overrides: i18n.ui,
-      })
-    : EN_UI;
+  const ui = withChangelogIndexText(
+    project.config,
+    i18n
+      ? resolveUIStrings(i18n.defaultLocale, {
+          defaultLocale: i18n.defaultLocale,
+          overrides: i18n.ui,
+        })
+      : EN_UI,
+    i18n?.defaultLocale
+  );
   const rows: IndexRow[] = project.graph.pages
     .filter(
       (page) =>

package/src/ai/component-markdown.ts

@@ -584,7 +584,7 @@ export const inlineCode = (text: string): string => {
 };
 
 /** Fence `code` so its opening/closing run outlengths any backticks inside. */
-const fencedBlock = (lang: string, code: string): string => {
+export const fencedBlock = (lang: string, code: string): string => {
   const trimmed = code.replace(/(?<!\n)\n+$/u, "");
   const runs = trimmed.match(/`+/gu);
   const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;

package/src/ai/cors.ts

@@ -66,6 +66,13 @@ interface RequestContext {
   request: Request;
 }
 
+/**
+ * The response headers a cross-origin caller may read beyond the safelisted
+ * ones: the rate limit's `Retry-After`, so a caller can tell a reader how
+ * long to wait after a `429`.
+ */
+const EXPOSED_HEADERS = "retry-after";
+
 /** Stamp the CORS headers on every response `handler` returns. */
 export const withCors =
   (
@@ -74,9 +81,8 @@ export const withCors =
   ): ((context: RequestContext) => Promise<Response>) =>
   async (context) => {
     const response = await handler(context);
-    for (const [key, value] of Object.entries(
-      corsHeaders(context.request, allowed)
-    )) {
+    const headers = corsHeaders(context.request, allowed);
+    for (const [key, value] of Object.entries(headers)) {
       // `Vary` accumulates (the handler may already vary on something), the
       // rest replace.
       if (key === "vary") {
@@ -85,5 +91,8 @@ export const withCors =
         response.headers.set(key, value);
       }
     }
+    if (headers["access-control-allow-origin"]) {
+      response.headers.set("access-control-expose-headers", EXPOSED_HEADERS);
+    }
     return response;
   };

package/src/ai/mcp/query.ts

@@ -53,20 +53,28 @@ const contentTypesField = z.preprocess((value) => {
 }, z.array(z.string()).optional().describe('Only include pages of these content types (frontmatter `type`, e.g. `["doc", "rfc"]`). `list_pages` shows each page\'s type. Omit to include every type.'));
 
 /**
- * The optional facet filter `search_docs` and `list_pages` share. Only
- * string-valued entries survive; an empty `{}` means "no filter".
+ * The optional facet filter `search_docs` and `list_pages` share. A value
+ * is read the way `pageFacets` stores one: a string as-is, a number or
+ * boolean stringified (`{"priority": 1}` matches the facet `"1"`). Entries of
+ * any other shape are dropped; an empty `{}` means "no filter".
  */
-/** Accepts any plain object, so the string-valued entries can be sifted out. */
+/** Accepts any plain object, so the usable entries can be sifted out. */
 const looseFacetObject = z.record(z.string(), z.unknown());
 
+/** A filter value a facet can hold, stringified like `pageFacets` does. */
+const facetFilterValue = z
+  .union([z.string(), z.number(), z.boolean()])
+  .transform(String);
+
 const filtersField = z.preprocess((value) => {
   const candidate = looseFacetObject.safeParse(value);
   if (!candidate.success) {
     return;
   }
-  const entries = Object.entries(candidate.data).filter(
-    (entry): entry is [string, string] => typeof entry[1] === "string"
-  );
+  const entries = Object.entries(candidate.data).flatMap(([key, entry]) => {
+    const parsed = facetFilterValue.safeParse(entry);
+    return parsed.success ? [[key, parsed.data] as const] : [];
+  });
   return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 }, z.record(z.string(), z.string()).optional().describe('Only include pages matching every facet, key → required value (e.g. `{"status": "enforced"}`). Facets are metadata the site declares per content type; `list_pages` shows each page\'s facet values. Omit for no facet filtering.'));
 

package/src/ai/openapi-components.ts

@@ -1,13 +1,24 @@
+import { customCodeSamples } from "../components/openapi/code-samples.ts";
 import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import type { ApiOperationRef, OpenApiData } from "../openapi/model.ts";
-import { operationOf, specAddresses, specOf } from "../openapi/model.ts";
+import {
+  operationObject,
+  operationOf,
+  specAddresses,
+  specOf,
+} from "../openapi/model.ts";
 import { asSentence } from "../openapi/sentence.ts";
 import { operationSignature } from "../openapi/signature.ts";
 import type {
   ComponentMarkdown,
   EvaluatedValue,
 } from "./component-markdown.ts";
-import { inlineCode, isString, linkDestination } from "./component-markdown.ts";
+import {
+  fencedBlock,
+  inlineCode,
+  isString,
+  linkDestination,
+} from "./component-markdown.ts";
 
 /**
  * Spec-authored prose as one line of inline Markdown. Unlike the props the
@@ -62,7 +73,10 @@ const listItem = (
  * section shows. Parameters, schemas and responses are deliberately left out:
  * those are `operation-model.ts` plus each component's own preparation, and a
  * second implementation here would be free to disagree with the page. The
- * endpoint and what it does is the part that was missing altogether.
+ * endpoint and what it does is the part that was missing altogether. The
+ * spec's own `x-codeSamples` do come along, as fenced code: they're text the
+ * spec wrote out (often an SDK call no agent could derive from the
+ * endpoint), read through the same `customCodeSamples` the page renders.
  *
  * `specs` is the parsed `blume:openapi` data — empty when the project has no
  * API reference, in which case every serializer declines. `deployBase` is the
@@ -142,7 +156,17 @@ export const openapiComponentSerializers = (
           : "",
         operation.deprecated ? "**Deprecated.**" : "",
       ].filter(Boolean);
-      return [signature, ...notes].join("\n\n");
+      // The spec's own `x-codeSamples`, labeled as their tabs are.
+      const object =
+        data.kind === "openapi" ? operationObject(data, operation) : undefined;
+      const samples = customCodeSamples({
+        "x-code-samples": object?.["x-code-samples"],
+        "x-codeSamples": object?.["x-codeSamples"],
+      }).map(
+        (sample) =>
+          `**${inlineText(sample.label)}**\n\n${fencedBlock(sample.lang, sample.source)}`
+      );
+      return [signature, ...notes, ...samples].join("\n\n");
     },
   } satisfies Record<string, ComponentMarkdown>;
 };

package/src/ai/relative-links.ts

@@ -7,8 +7,6 @@ import {
   withAuthoredBasePath,
   withBasePath,
 } from "../core/base-path.ts";
-import { nextFenceState } from "../core/code-fences.ts";
-import type { FenceState } from "../core/code-fences.ts";
 import { localePrefix } from "../core/i18n.ts";
 import {
   buildFileRouteIndex,
@@ -49,10 +47,6 @@ export interface LinkedPage {
 /** Rewrite a page's relative page links to the routes they mean. */
 export type RelativeLinkRewriter = (text: string, page: LinkedPage) => string;
 
-/** A reference definition's target: `[label]: ./install` or `<./install>`. */
-const DEFINITION =
-  /^(?<lead> {0,3}\[(?:[^\]\\]|\\.)+\]:[\t ]*)(?:<(?<angled>[^>]*)>|(?<bare>\S+))/u;
-
 /**
  * Whether a text could hold a relative page link at all: an inline link, a
  * reference definition, or a component `href` whose target isn't a URL with
@@ -88,31 +82,13 @@ const spliceLine = (line: string, splices: readonly Splice[]): string => {
   return out;
 };
 
-/** One line's reference-definition splice, when it defines a routed target. */
-const definitionSplice = (
-  line: string,
-  routed: (target: string) => string | undefined
-): Splice | undefined => {
-  const groups = DEFINITION.exec(line)?.groups;
-  const lead = groups?.lead;
-  const target = groups?.angled ?? groups?.bare;
-  const route = target === undefined ? undefined : routed(target);
-  if (lead === undefined || target === undefined || route === undefined) {
-    return undefined;
-  }
-  // An angle-bracketed target starts one past its `<`.
-  const angled = groups?.angled === undefined ? 0 : 1;
-  return { column: lead.length + angled, length: target.length, text: route };
-};
-
 /**
- * Every routed splice in `text`, by 0-based line: links and images, then
- * definitions. An image target goes through `imaged`, everything else through
- * `routed`.
+ * Every routed splice in `text`, by 0-based line: links, images, and
+ * reference definitions, as `extractLinks` finds them. An image target goes
+ * through `imaged`, everything else through `routed`.
  */
 const collectSplices = (
   text: string,
-  lines: readonly string[],
   routed: (target: string) => string | undefined,
   imaged: (target: string) => string | undefined
 ): Map<number, Splice[]> => {
@@ -130,16 +106,6 @@ const collectSplices = (
       });
     }
   }
-  let fence: FenceState = null;
-  for (const [index, line] of lines.entries()) {
-    const next = nextFenceState(line, fence);
-    const inFence = fence !== null || next !== null;
-    fence = next;
-    const splice = inFence ? undefined : definitionSplice(line, routed);
-    if (splice !== undefined) {
-      add(index, splice);
-    }
-  }
   return splices;
 };
 
@@ -242,7 +208,7 @@ export const relativeLinkRewriter = (
     };
 
     const lines = text.split("\n");
-    const splices = collectSplices(text, lines, routed, imaged);
+    const splices = collectSplices(text, routed, imaged);
 
     return lines
       .map((line, index) => {

package/src/analytics/clics.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+
+/** The browser tracker in Clics' installation guide. */
+export const CLICS_SCRIPT_SRC = "https://clics.dev/tracker.js";
+
+/** Public project ID and optional tracker flags. */
+export interface ClicsOptions {
+  /** Project ID from Configure → Tracking in the Clics dashboard. */
+  projectId: string;
+  /** Include localhost and 127.0.0.1 in a production build's reports. */
+  allowLocalhost?: boolean;
+  /** Turn off automatic outbound-link events. */
+  disableOutboundLinks?: boolean;
+}
+
+export const clicsOptionsSchema = z.strictObject({
+  allowLocalhost: z.boolean().optional(),
+  disableOutboundLinks: z.boolean().optional(),
+  projectId: z.string().min(1),
+});
+
+export type ClicsAdapter = AdapterDescriptor<"clics", ClicsOptions>;
+
+export const clicsAdapterSchema = adapterDescriptorSchema(
+  "clics",
+  clicsOptionsSchema
+);
+
+/** Clics website analytics. The project ID is public in the tracker tag. */
+export const clics = (options: ClicsOptions): ClicsAdapter => ({
+  kind: "clics",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * The documented deferred tracker tag. Clics reads these attributes from
+ * `document.currentScript` and tracks history changes without a Blume hook.
+ */
+export const clicsHead = (options: ClicsOptions): HeadScript[] => {
+  const attributes: HeadScript["attributes"] = {
+    "data-project-id": options.projectId,
+    defer: true,
+    src: CLICS_SCRIPT_SRC,
+  };
+  if (options.allowLocalhost) {
+    attributes["data-allow-localhost"] = true;
+  }
+  if (options.disableOutboundLinks) {
+    attributes["data-disable-outbound-links"] = true;
+  }
+  return [{ attributes, content: null }];
+};

package/src/analytics/head.ts

@@ -2,6 +2,7 @@ import { adobeHead } from "./adobe.ts";
 import { amplitudeHead } from "./amplitude.ts";
 import { clarityHead } from "./clarity.ts";
 import { clearbitHead } from "./clearbit.ts";
+import { clicsHead } from "./clics.ts";
 import { cloudflareHead } from "./cloudflare.ts";
 import { databuddyHead } from "./databuddy.ts";
 import { fathomHead } from "./fathom.ts";
@@ -47,6 +48,7 @@ export type HeadNode =
  * the one place that branches on `kind`. A provider whose install snippet is
  * two tags (an SDK plus its init call) emits two.
  */
+// oxlint-disable-next-line complexity -- each adapter has one exhaustive, type-narrowed dispatch case
 const adapterScripts = (
   adapter: Exclude<AnalyticsAdapter, { kind: "vercel" }>
 ): HeadScript[] => {
@@ -63,6 +65,9 @@ const adapterScripts = (
     case "clearbit": {
       return clearbitHead(adapter.options);
     }
+    case "clics": {
+      return clicsHead(adapter.options);
+    }
     case "cloudflare": {
       return cloudflareHead(adapter.options);
     }

package/src/analytics/index.ts

@@ -28,6 +28,8 @@ export { clarity } from "./clarity.ts";
 export type { ClarityAdapter, ClarityOptions } from "./clarity.ts";
 export { clearbit } from "./clearbit.ts";
 export type { ClearbitAdapter, ClearbitOptions } from "./clearbit.ts";
+export { clics } from "./clics.ts";
+export type { ClicsAdapter, ClicsOptions } from "./clics.ts";
 export { cloudflare } from "./cloudflare.ts";
 export type { CloudflareAdapter, CloudflareOptions } from "./cloudflare.ts";
 export { databuddy } from "./databuddy.ts";

package/src/analytics/schema.ts

@@ -4,6 +4,7 @@ import { adobeAdapterSchema } from "./adobe.ts";
 import { amplitudeAdapterSchema } from "./amplitude.ts";
 import { clarityAdapterSchema } from "./clarity.ts";
 import { clearbitAdapterSchema } from "./clearbit.ts";
+import { clicsAdapterSchema } from "./clics.ts";
 import { cloudflareAdapterSchema } from "./cloudflare.ts";
 import { databuddyAdapterSchema } from "./databuddy.ts";
 import { fathomAdapterSchema } from "./fathom.ts";
@@ -28,6 +29,7 @@ export const analyticsAdapterSchema = z.discriminatedUnion("kind", [
   amplitudeAdapterSchema,
   clarityAdapterSchema,
   clearbitAdapterSchema,
+  clicsAdapterSchema,
   cloudflareAdapterSchema,
   databuddyAdapterSchema,
   fathomAdapterSchema,