blume 1.5.2 → 1.6.0

package/src/core/ui-packs/pt.ts

@@ -20,6 +20,8 @@ export const pt: UIStringsOverride = {
     generating: "A gerar…",
     openIn: "Abrir em {name}",
     openInChat: "Abrir no chat",
+    openInChatPrompt:
+      "Leia {url} para que eu possa fazer perguntas sobre esta página.",
     scrollToTop: "Voltar ao topo",
   },
   ask: {

package/src/core/ui-packs/ro.ts

@@ -20,6 +20,8 @@ export const ro: UIStringsOverride = {
     generating: "Se generează…",
     openIn: "Deschide în {name}",
     openInChat: "Deschide în chat",
+    openInChatPrompt:
+      "Citește {url} ca să îți pot pune întrebări despre această pagină.",
     scrollToTop: "Sus de tot",
   },
   ask: {

package/src/core/ui-packs/ru.ts

@@ -20,6 +20,8 @@ export const ru: UIStringsOverride = {
     generating: "Генерация…",
     openIn: "Открыть в {name}",
     openInChat: "Открыть в чате",
+    openInChatPrompt:
+      "Прочитайте {url} — я буду задавать вопросы об этой странице.",
     scrollToTop: "Наверх",
   },
   ask: {

package/src/core/ui-packs/sk.ts

@@ -20,6 +20,7 @@ export const sk: UIStringsOverride = {
     generating: "Generovanie…",
     openIn: "Otvoriť v {name}",
     openInChat: "Otvoriť v chate",
+    openInChatPrompt: "Prečítajte si {url} — budem sa pýtať na túto stránku.",
     scrollToTop: "Späť nahor",
   },
   ask: {

package/src/core/ui-packs/sr.ts

@@ -20,6 +20,7 @@ export const sr: UIStringsOverride = {
     generating: "Генерисање…",
     openIn: "Отвори у {name}",
     openInChat: "Отвори у ћаскању",
+    openInChatPrompt: "Прочитајте {url} — постављаћу питања о овој страници.",
     scrollToTop: "Назад на врх",
   },
   ask: {

package/src/core/ui-packs/sv.ts

@@ -20,6 +20,8 @@ export const sv: UIStringsOverride = {
     generating: "Genererar…",
     openIn: "Öppna i {name}",
     openInChat: "Öppna i chatt",
+    openInChatPrompt:
+      "Läs {url} så att jag kan ställa frågor om den här sidan.",
     scrollToTop: "Till toppen",
   },
   ask: {

package/src/core/ui-packs/th.ts

@@ -20,6 +20,7 @@ export const th: UIStringsOverride = {
     generating: "กำลังสร้าง…",
     openIn: "เปิดใน {name}",
     openInChat: "เปิดในแชท",
+    openInChatPrompt: "อ่าน {url} เพื่อให้ฉันถามคำถามเกี่ยวกับหน้านี้ได้",
     scrollToTop: "กลับไปด้านบน",
   },
   ask: {

package/src/core/ui-packs/tr.ts

@@ -20,6 +20,8 @@ export const tr: UIStringsOverride = {
     generating: "Oluşturuluyor…",
     openIn: "{name} içinde aç",
     openInChat: "Sohbette aç",
+    openInChatPrompt:
+      "Bu sayfa hakkında sorular sorabilmem için {url} adresini okuyun.",
     scrollToTop: "Başa dön",
   },
   ask: {

package/src/core/ui-packs/uk.ts

@@ -20,6 +20,8 @@ export const uk: UIStringsOverride = {
     generating: "Генерація…",
     openIn: "Відкрити в {name}",
     openInChat: "Відкрити в чаті",
+    openInChatPrompt:
+      "Прочитайте {url} — я ставитиму запитання щодо цієї сторінки.",
     scrollToTop: "Нагору",
   },
   ask: {

package/src/core/ui-packs/vi.ts

@@ -20,6 +20,7 @@ export const vi: UIStringsOverride = {
     generating: "Đang tạo…",
     openIn: "Mở trong {name}",
     openInChat: "Mở trong trò chuyện",
+    openInChatPrompt: "Hãy đọc {url} để tôi có thể đặt câu hỏi về trang này.",
     scrollToTop: "Lên đầu trang",
   },
   ask: {

package/src/core/ui-packs/zh-tw.ts

@@ -20,6 +20,7 @@ export const zhTW: UIStringsOverride = {
     generating: "產生中…",
     openIn: "在 {name} 中開啟",
     openInChat: "在聊天中開啟",
+    openInChatPrompt: "請閱讀 {url} 以便我針對此頁面提問。",
     scrollToTop: "回到頂部",
   },
   ask: {

package/src/core/ui-packs/zh.ts

@@ -20,6 +20,7 @@ export const zh: UIStringsOverride = {
     generating: "生成中…",
     openIn: "在 {name} 中打开",
     openInChat: "在聊天中打开",
+    openInChatPrompt: "请阅读 {url} 以便我就此页面提问。",
     scrollToTop: "回到顶部",
   },
   ask: {

package/src/core/version-cut.ts

@@ -7,7 +7,7 @@ import { stripBasePath } from "./base-path.ts";
 import { writeTextAtomic } from "./fs-atomic.ts";
 import { localizeRoute } from "./i18n.ts";
 import type { BlumeProject } from "./project-graph.ts";
-import { scanProject } from "./project-graph.ts";
+import { isWithin, scanProject } from "./project-graph.ts";
 import { VERSION_ID } from "./schema.ts";
 import { nextFenceState } from "./sources/normalize.ts";
 import type { FenceState } from "./sources/normalize.ts";
@@ -60,11 +60,16 @@ const buildRouteRewrites = (
   const { contentRoot } = project.context;
   const rewrites = new Map<string, string>();
   for (const page of project.graph.pages) {
-    // `sourcePath` is set by the filesystem adapter only, so its absence
-    // already excludes generated and remote pages.
+    // `sourcePath` marks a page backed by a local file, which excludes
+    // generated and remote pages; the content-root check below excludes local
+    // files that live outside the tree a version snapshot copies. A staged
+    // page (an Obsidian note) is served from its source, not from the copied
+    // tree, so it keeps publishing as current even when its file sits under
+    // the content root.
     const { sourcePath } = page;
     if (
       page.version !== "" ||
+      page.collection === "staged" ||
       !sourcePath ||
       relative(contentRoot, sourcePath).startsWith("..")
     ) {
@@ -240,6 +245,18 @@ export const cutVersion = async (
     "node_modules",
     ...(project.config.versions?.archived.map((version) => version.id) ?? []),
   ]);
+  // Another local source's tree under the content root — an Obsidian vault the
+  // filesystem source excludes — is that source's to publish. Copying it would
+  // republish its raw notes (wikilinks and `%%comments%%` intact) as
+  // filesystem pages of the snapshot, while the source itself keeps serving
+  // them as current.
+  const foreignRoots = project.sources
+    .flatMap((source) =>
+      source.staged && source.contentRoot ? [source.contentRoot] : []
+    )
+    .filter((tree) => isWithin(contentRoot, tree));
+  const isForeign = (path: string): boolean =>
+    foreignRoots.some((tree) => isWithin(tree, path));
   const entries = await readdir(contentRoot, { withFileTypes: true });
   let copied = 0;
   await Promise.all(
@@ -252,6 +269,7 @@ export const cutVersion = async (
         return;
       }
       await cp(join(contentRoot, entry.name), join(dir, entry.name), {
+        filter: (source) => !isForeign(source),
         recursive: true,
       });
     })

package/src/core/yaml.ts

@@ -0,0 +1,26 @@
+import {
+  binaryTag,
+  CORE_SCHEMA,
+  mergeTag,
+  omapTag,
+  pairsTag,
+  setTag,
+  timestampTag,
+} from "js-yaml";
+
+/**
+ * The schema js-yaml 4 loaded with by default: YAML 1.2 core scalars plus the
+ * `!!timestamp`, `!!merge`, `!!binary`, `!!omap`, `!!pairs`, and `!!set` tags.
+ * js-yaml 5 loads with the bare core schema instead, which turns
+ * `date: 2024-01-01` into a string and leaves `<<:` merge keys unresolved — a
+ * silent change to every page's front matter. Every Blume `load` call passes
+ * this schema so parsing stays identical across the upgrade.
+ */
+export const YAML_SCHEMA = CORE_SCHEMA.withTags(
+  timestampTag,
+  mergeTag,
+  binaryTag,
+  omapTag,
+  pairsTag,
+  setTag
+);

package/src/deploy/function-bundle.ts

@@ -0,0 +1,251 @@
+import { existsSync, readFileSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { builtinModules } from "node:module";
+
+import { dirname, join, relative } from "pathe";
+import { z } from "zod";
+
+import { packageRoot } from "../core/package-root.ts";
+
+/**
+ * Post-build audit of a Vercel serverless function bundle.
+ *
+ * The Vercel adapter traces the server entry with `@vercel/nft` and copies
+ * every file it reaches into `.vercel/output/functions/_render.func`. A bare
+ * import the trace cannot resolve — a package that isn't reachable by walking
+ * `node_modules` up from the chunk that imports it — is dropped *silently*,
+ * and the deployed function dies on its first request with
+ * `ERR_MODULE_NOT_FOUND` (Vercel reports it as `FUNCTION_INVOCATION_FAILED`).
+ * Under an isolated linker (pnpm, Bun's `isolated` mode) that is exactly the
+ * shape of Blume's own runtime dependencies: the SSR build leaves them
+ * external, and they live under `blume`'s store directory, not the project
+ * root. Nothing before deploy surfaces it — the build is green, a warm-cache
+ * preview is green — so the bundle is re-checked here with Node's own
+ * resolution rule: a package is present when some `node_modules/<name>` on
+ * the walk from the importing chunk up to the function root exists.
+ */
+
+/** A bare package import the function bundle cannot satisfy. */
+export interface MissingPackage {
+  /** Function-relative paths of the chunks that import the package. */
+  importers: string[];
+  name: string;
+}
+
+/** One function directory's audit result. */
+export interface FunctionBundleAudit {
+  /** Absolute path of the `*.func` directory. */
+  dir: string;
+  missing: MissingPackage[];
+}
+
+const BUILTINS = new Set(builtinModules);
+
+/** Specifier prefixes that never name an installed package. */
+const NON_PACKAGE_PREFIXES = ["node:", "astro:", "virtual:", "data:", "\0"];
+
+/**
+ * The package a bare specifier resolves through (`@scope/name` or `name`), or
+ * null for relative/absolute paths, Node builtins, and virtual ids.
+ */
+export const packageName = (specifier: string): string | null => {
+  if (
+    specifier.startsWith(".") ||
+    specifier.startsWith("/") ||
+    NON_PACKAGE_PREFIXES.some((prefix) => specifier.startsWith(prefix)) ||
+    BUILTINS.has(specifier)
+  ) {
+    return null;
+  }
+  const segments = specifier.split("/");
+  if (specifier.startsWith("@")) {
+    return segments.length >= 2 ? `${segments[0]}/${segments[1]}` : null;
+  }
+  return segments[0] || null;
+};
+
+/**
+ * Static specifiers: a side-effect `import "x"` or an `import`/`export … from
+ * "x"` clause. Only `import` takes the bare-string form — `export "x"` is not
+ * syntax, so a runtime message quoting `export 'ALL'` must not match. The
+ * specifier quote must not be escaped either: a backslash-quoted `from \"zod\"`
+ * is a code sample serialized into a string (the MCP snapshot carries page
+ * Markdown), not module syntax.
+ */
+const STATIC_IMPORT =
+  /(?:^|[;\s}])(?:import\s*(?<!\\)["'](?<bare>[^"'\n]+)["']|(?:import|export)\s*[\w$*{},\s]*?\s*from\s*(?<!\\)["'](?<from>[^"'\n]+)["'])/gu;
+
+/** Dynamic `import("…")` specifiers, same escaped-quote rule. */
+const DYNAMIC_IMPORT =
+  /\bimport\(\s*(?<!\\)["'](?<dynamic>[^"'\n]+)["']\s*\)/gu;
+
+/** Every bare package name a module's source imports. */
+export const importedPackages = (source: string): string[] => {
+  const names = new Set<string>();
+  for (const pattern of [STATIC_IMPORT, DYNAMIC_IMPORT]) {
+    for (const match of source.matchAll(pattern)) {
+      const groups = match.groups ?? {};
+      const name = packageName(
+        groups.bare ?? groups.from ?? groups.dynamic ?? ""
+      );
+      if (name) {
+        names.add(name);
+      }
+    }
+  }
+  return [...names];
+};
+
+/** Whether `node_modules/<name>` exists on the walk from `from` up to `root`. */
+const resolvable = (name: string, from: string, root: string): boolean => {
+  let dir = from;
+  for (;;) {
+    if (existsSync(join(dir, "node_modules", name, "package.json"))) {
+      return true;
+    }
+    if (dir === root) {
+      return false;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return false;
+    }
+    dir = parent;
+  }
+};
+
+const MODULE_FILE = /\.(?:m?js|cjs)$/u;
+
+/** The one `.vc-config.json` field the audit reads; the rest passes through. */
+const vcConfigSchema = z.looseObject({ handler: z.string().optional() });
+
+/** Every JavaScript module under `dir`, skipping any `node_modules`. */
+const listModules = async (dir: string): Promise<string[]> => {
+  const files: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== "node_modules") {
+        // oxlint-disable-next-line no-await-in-loop -- sequential walk keeps ordering deterministic
+        files.push(...(await listModules(path)));
+      }
+    } else if (entry.isFile() && MODULE_FILE.test(entry.name)) {
+      files.push(path);
+    }
+  }
+  return files;
+};
+
+/**
+ * Audit one function directory: read its `.vc-config.json` handler, scan
+ * every module beside the handler (the adapter's `dist/server` tree) for bare
+ * imports, and report the packages no `node_modules` on the walk up to the
+ * function root provides. A function without a handler has nothing to check.
+ */
+export const auditFunctionBundle = async (
+  funcDir: string
+): Promise<MissingPackage[]> => {
+  const configPath = join(funcDir, ".vc-config.json");
+  if (!existsSync(configPath)) {
+    return [];
+  }
+  const config = vcConfigSchema.safeParse(
+    JSON.parse(await readFile(configPath, "utf-8"))
+  );
+  if (!config.success || !config.data.handler) {
+    return [];
+  }
+  const serverDir = dirname(join(funcDir, config.data.handler));
+  if (!existsSync(serverDir)) {
+    return [];
+  }
+  const missing = new Map<string, string[]>();
+  for (const file of await listModules(serverDir)) {
+    // oxlint-disable-next-line no-await-in-loop -- sequential read keeps the importer lists ordered
+    const source = await readFile(file, "utf-8");
+    for (const name of importedPackages(source)) {
+      if (resolvable(name, dirname(file), funcDir)) {
+        continue;
+      }
+      const importers = missing.get(name) ?? [];
+      importers.push(relative(funcDir, file));
+      missing.set(name, importers);
+    }
+  }
+  return [...missing]
+    .map(([name, importers]) => ({ importers, name }))
+    .toSorted((a, b) => a.name.localeCompare(b.name));
+};
+
+/**
+ * Audit every function in a Vercel Build Output tree (`.vercel/output`).
+ * Functions with nothing missing are omitted; an output tree without a
+ * `functions/` directory (a static build) yields nothing.
+ */
+export const auditVercelFunctions = async (
+  outputDir: string
+): Promise<FunctionBundleAudit[]> => {
+  const functionsDir = join(outputDir, "functions");
+  if (!existsSync(functionsDir)) {
+    return [];
+  }
+  const audits: FunctionBundleAudit[] = [];
+  const entries = await readdir(functionsDir, { withFileTypes: true });
+  for (const entry of entries.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (!(entry.isDirectory() && entry.name.endsWith(".func"))) {
+      continue;
+    }
+    const dir = join(functionsDir, entry.name);
+    // oxlint-disable-next-line no-await-in-loop -- sequential audit keeps the report ordered
+    const missing = await auditFunctionBundle(dir);
+    if (missing.length > 0) {
+      audits.push({ dir, missing });
+    }
+  }
+  return audits;
+};
+
+/** Blume's own runtime dependency names, from its published `package.json`. */
+export const blumeDependencyNames = (): Set<string> => {
+  const manifest: { dependencies?: Record<string, string> } = JSON.parse(
+    readFileSync(join(packageRoot(), "package.json"), "utf-8")
+  );
+  return new Set(Object.keys(manifest.dependencies ?? {}));
+};
+
+/** What a build should do about an audit: nothing, warn, or fail. */
+export interface FunctionBundleVerdict {
+  /**
+   * A missing package is one of Blume's own dependencies — the runtime Blume
+   * generated imports it, so the function is certain to crash. Anything else
+   * (a project's own external import) is reported but left to the author.
+   */
+  fatal: boolean;
+  message: string;
+}
+
+/**
+ * Describe a function's missing packages and how to fix them. Vercel's trace
+ * only reaches packages resolvable from the project root, so the remedy is a
+ * root-level dependency entry for each — the same mirror rule Blume's native
+ * dependencies (`sharp`, `takumi-js`) already follow.
+ */
+export const functionBundleVerdict = (
+  audit: FunctionBundleAudit,
+  root: string,
+  ownDependencies: ReadonlySet<string>
+): FunctionBundleVerdict => {
+  const names = audit.missing.map((entry) => entry.name);
+  const lines = audit.missing.map(
+    (entry) => `  - ${entry.name} (imported by ${entry.importers.join(", ")})`
+  );
+  const fatal = names.some((name) => ownDependencies.has(name));
+  const message = [
+    `The Vercel function bundle at ${relative(root, audit.dir) || audit.dir} is missing packages its server code imports, so the deployed function would fail on every request with ERR_MODULE_NOT_FOUND:`,
+    ...lines,
+    "Vercel's dependency trace only includes packages resolvable from the project root; under an isolated linker (pnpm, Bun's isolated mode) Blume's own dependencies are not. Add them to the project's package.json so the trace can find them:",
+    `  npm install -D ${names.join(" ")}`,
+  ].join("\n");
+  return { fatal, message };
+};

package/src/eval/schema.ts

@@ -3,6 +3,8 @@ import { readFile } from "node:fs/promises";
 import { load } from "js-yaml";
 import { z } from "zod";
 
+import { YAML_SCHEMA } from "../core/yaml.ts";
+
 /** Question ids are kebab-case slugs so they read well in reports and CI logs. */
 const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
 
@@ -90,7 +92,7 @@ export const loadEvalsFile = async (
 
   let parsed: unknown;
   try {
-    parsed = load(raw);
+    parsed = load(raw, { schema: YAML_SCHEMA });
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     throw new EvalsFileError(path, `Invalid YAML in ${path}: ${detail}`);

package/src/markdown/code-title.ts

@@ -9,6 +9,13 @@
  *   `data-line-numbers`; the theme renders a counter-driven line-number gutter.
  */
 
+import {
+  isLineRange,
+  metaTokens,
+  QUOTED_ATTR,
+  RESERVED_META_KEYWORDS,
+} from "./fence-meta.ts";
+
 /** The slice of Shiki's transformer `this` context Blume reads. */
 interface CodeMetaContext {
   options: { meta?: { __raw?: string } };
@@ -25,29 +32,25 @@ export interface CodeTitleTransformer {
   pre: (this: CodeMetaContext, node: PreNode) => void;
 }
 
-// The body excludes only the delimiting quote, so `title="foo's file.ts"`
-// (an apostrophe inside double quotes) still matches. The left boundary stops
-// `subtitle="..."` (or any `*title=` attr) from reading as a title.
 const TITLE_ATTR = /(?:^|\s)title=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/u;
 const LINE_NUMBERS = /(?:^|\s)lineNumbers(?=\s|$)/u;
-// Any quoted `key="..."` attr — blanked before keyword/bare-token scans so a
-// quoted value can't leak tokens (`title="enable lineNumbers later"`).
-const QUOTED_ATTR = /[\w-]+=(?:"[^"]*"|'[^']*')/gu;
 
+// Quoted attrs are blanked before keyword/bare-token scans so a quoted value
+// can't leak tokens (`title="enable lineNumbers later"`).
 const withoutQuotedAttrs = (raw: string): string =>
   raw.replace(QUOTED_ATTR, " ");
 
 // The first bare token is the title (```ts blume.config.ts): a non-empty token
 // that isn't a Shiki line range (`{1,3-5}`), a `key=value` attr, or a reserved
-// `lineNumbers`/`twoslash` keyword.
-const isTitleToken = (token: string): boolean => {
-  if (token.length === 0 || token.startsWith("{") || token.includes("=")) {
-    return false;
-  }
-  return token !== "lineNumbers" && token !== "twoslash";
-};
+// keyword.
+const isTitleToken = (token: string): boolean =>
+  token.length > 0 &&
+  !isLineRange(token) &&
+  !token.includes("=") &&
+  !RESERVED_META_KEYWORDS.has(token);
 
-const parseTitle = (raw: string | undefined): string | undefined => {
+/** The title a fence's meta string promotes to `data-title`, if any. */
+export const parseCodeTitle = (raw: string | undefined): string | undefined => {
   if (!raw) {
     return undefined;
   }
@@ -62,7 +65,10 @@ const parseTitle = (raw: string | undefined): string | undefined => {
   if (attrTitle) {
     return attrTitle;
   }
-  return withoutQuotedAttrs(raw).trim().split(/\s+/u).find(isTitleToken);
+  // The shared tokenizer keeps a quoted attr (rejected below by its `=`) and
+  // a spaced line range (`{1, 3-5}`) whole, so neither can shed a fragment
+  // that reads as a bare title.
+  return metaTokens(raw).find(isTitleToken);
 };
 
 const hasLineNumbers = (raw: string | undefined): boolean =>
@@ -73,7 +79,7 @@ export const codeTitleTransformer = (): CodeTitleTransformer => ({
   name: "blume:code-meta",
   pre(node) {
     const raw = this.options.meta?.__raw;
-    const title = parseTitle(raw);
+    const title = parseCodeTitle(raw);
     if (title) {
       node.properties.dataTitle = title;
     }

package/src/markdown/features.ts

@@ -0,0 +1,21 @@
+import type { Features } from "satteri";
+
+/**
+ * Sätteri's feature set for plain `.md` pages. Shared by the renderer and the
+ * search extractor so the index reads the same grammar the page renders.
+ */
+export const MARKDOWN_FEATURES = {
+  subscript: true,
+  superscript: true,
+} satisfies Features;
+
+/**
+ * The `.mdx` feature set: Markdown's plus `:::` directives (→ `<Callout>`) and
+ * block-only math — `singleDollarTextMath: false` keeps a bare `$` (currency,
+ * shell, code) as literal text and only parses `$$…$$`.
+ */
+export const MDX_FEATURES = {
+  ...MARKDOWN_FEATURES,
+  directive: true,
+  math: { singleDollarTextMath: false },
+} satisfies Features;

package/src/markdown/fence-meta.ts

@@ -0,0 +1,50 @@
+/**
+ * The shared fence-meta grammar: how the tokens after a code fence's language
+ * (```ts title="..." {1,3-5} lineNumbers) split, and which of them carry
+ * reserved meaning. Both the Shiki-side meta reader (`code-title.ts`) and the
+ * MDAST plugins that rewrite marked fences (`ts2js.ts`) consume this, so the
+ * two layers can't drift on token boundaries or keyword lists.
+ */
+
+/**
+ * Any quoted `key="..."` attr (spaces allowed inside the quotes). The body
+ * excludes only the delimiting quote, so `title="foo's file.ts"` (an
+ * apostrophe inside double quotes) still matches. The left boundary stops
+ * `subtitle="..."` (or any `*title=` attr) from reading as a title.
+ */
+export const QUOTED_ATTR = /[\w-]+=(?:"[^"]*"|'[^']*')/gu;
+
+/**
+ * A Shiki `{1,3-5}` line-range token, braces included. Shiki tolerates
+ * whitespace inside the braces (`{1, 3-5}`), so the range is one token even
+ * when it contains spaces — split on whitespace alone, `3-5}` would surface
+ * as a bare word and be promoted to the block title.
+ */
+const LINE_RANGE = /\{[^}]*\}/u;
+
+/**
+ * One fence-meta token: a quoted attribute, a line range, or a bare word, so
+ * a keyword inside a quoted value (`title="enable ts2js later"`) never reads
+ * as a bare token and a spaced line range never splits.
+ */
+const META_TOKEN = new RegExp(
+  `${QUOTED_ATTR.source}|${LINE_RANGE.source}|\\S+`,
+  "gu"
+);
+
+/** Split a raw fence meta string into its tokens. */
+export const metaTokens = (meta: string | null | undefined): string[] =>
+  meta?.match(META_TOKEN) ?? [];
+
+/**
+ * Bare keywords with reserved meaning after the language; never promoted to
+ * a block title.
+ */
+export const RESERVED_META_KEYWORDS: ReadonlySet<string> = new Set([
+  "lineNumbers",
+  "ts2js",
+  "twoslash",
+]);
+
+/** A Shiki `{1,3-5}` line-range token. */
+export const isLineRange = (token: string): boolean => token.startsWith("{");