secondbrain-py 0.2.1__py3-none-any.whl

brain/quartz_overrides/quartz/processors/parse.ts

@@ -0,0 +1,371 @@
+// Brain wiki — parse pipeline with per-file parser result cache.
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/processors/parse.ts` by
+// `brain vault render --overlay`, overwriting the stock upstream module.
+//
+// Changes from upstream:
+//   1. `createFileParser` loop: reads raw bytes with `readFile` (replaces
+//      `read` from to-vfile — equivalent but gives us the Buffer for hashing).
+//      On each file, computes a cache key and checks the MDAST cache before
+//      running `processor.parse` + `processor.run`. Hit → push reconstituted
+//      MarkdownContent and continue. Miss → run existing path, then store.
+//      Only the MDAST phase is cached: the cache key is deterministic on
+//      (file_bytes, slug) and the dominant build cost is `processor.parse` +
+//      `processor.run` (remark), not the remark-rehype step that follows.
+//      The HTML phase (`createMarkdownParser`) is left identical to upstream.
+//   2. `parseMarkdown`: computes `cacheDir` (defaults to
+//      `<argv.directory>/.quartz/.cache/parser` unless ctx.cacheDir is already
+//      set or `argv.noCache` is true). Propagates `cacheDir` to workers via
+//      the `serializableCtx` literal.
+//
+// Cache module: `./parser_cache.ts` — pure Node.js, no Quartz-internal
+// imports, tested independently in `tests/test_quartz_parser_cache.ts`.
+//
+// Safety: every MDAST transformer in quartz_overrides/quartz/plugins/
+// transformers/ is a pure function of (file bytes, slug) — no cross-file
+// reads at the parse stage. Cross-file work (backlinks, contentIndex,
+// related-docs) happens in the emitter phase on the in-memory
+// ProcessedContent[] collection AFTER this function returns. The
+// transformers/index.ts file documents this contract.
+//
+// Tested against Quartz v4.5.x (April 2026). If a future Quartz version
+// changes the parse pipeline shape (e.g. adds a third processor phase or
+// changes how VFile is constructed), diff upstream against this file and
+// re-apply the brain-cache hooks.
+
+import esbuild from "esbuild"
+import remarkParse from "remark-parse"
+import remarkRehype from "remark-rehype"
+import { Processor, unified } from "unified"
+import { Root as MDRoot } from "remark-parse/lib"
+import { Root as HTMLRoot } from "hast"
+import { MarkdownContent, ProcessedContent } from "../plugins/vfile"
+import { PerfTimer } from "../util/perf"
+import { readFile } from "node:fs/promises"
+import { VFile } from "vfile"
+import { FilePath, QUARTZ, slugifyFilePath } from "../util/path"
+import path from "path"
+import workerpool, { Promise as WorkerPromise } from "workerpool"
+import { QuartzLogger } from "../util/log"
+import { trace } from "../util/trace"
+import { BuildCtx, WorkerSerializableBuildCtx } from "../util/ctx"
+import { styleText } from "util"
+import { cacheKey, getCached, putCached, CACHE_VERSION } from "./parser_cache"
+
+export type QuartzMdProcessor = Processor<MDRoot, MDRoot, MDRoot>
+export type QuartzHtmlProcessor = Processor<undefined, MDRoot, HTMLRoot>
+
+export function createMdProcessor(ctx: BuildCtx): QuartzMdProcessor {
+  const transformers = ctx.cfg.plugins.transformers
+
+  return (
+    unified()
+      // base Markdown -> MD AST
+      .use(remarkParse)
+      // MD AST -> MD AST transforms
+      .use(
+        transformers.flatMap((plugin) => plugin.markdownPlugins?.(ctx) ?? []),
+      ) as unknown as QuartzMdProcessor
+    //  ^ sadly the typing of `use` is not smart enough to infer the correct type from our plugin list
+  )
+}
+
+export function createHtmlProcessor(ctx: BuildCtx): QuartzHtmlProcessor {
+  const transformers = ctx.cfg.plugins.transformers
+  return (
+    unified()
+      // MD AST -> HTML AST
+      .use(remarkRehype, { allowDangerousHtml: true })
+      // HTML AST -> HTML AST transforms
+      .use(transformers.flatMap((plugin) => plugin.htmlPlugins?.(ctx) ?? []))
+  )
+}
+
+function* chunks<T>(arr: T[], n: number) {
+  for (let i = 0; i < arr.length; i += n) {
+    yield arr.slice(i, i + n)
+  }
+}
+
+// brain-cache: rehydrate Date instances inside cached file.data.
+// JSON.stringify turns Date objects into ISO strings; on read they come
+// back as strings, and components that call `.toISOString()` on them
+// crash (`date.toISOString is not a function`). The upstream `lastmod`
+// transformer populates `data.dates = { created, modified, published }`
+// with Dates; this helper restores them in place. Keep this list in sync
+// with `quartz/plugins/vfile.ts` `DataMap.dates` if upstream adds fields.
+function rehydrateDates(data: Record<string, unknown>): void {
+  const dates = data.dates as Record<string, unknown> | undefined
+  if (!dates || typeof dates !== "object") return
+  for (const key of ["created", "modified", "published"] as const) {
+    const value = dates[key]
+    if (typeof value === "string") {
+      dates[key] = new Date(value)
+    }
+  }
+}
+
+async function transpileWorkerScript() {
+  // transpile worker script
+  const cacheFile = "./.quartz-cache/transpiled-worker.mjs"
+  const fp = "./quartz/worker.ts"
+  return esbuild.build({
+    entryPoints: [fp],
+    outfile: path.join(QUARTZ, cacheFile),
+    bundle: true,
+    keepNames: true,
+    platform: "node",
+    format: "esm",
+    packages: "external",
+    sourcemap: true,
+    sourcesContent: false,
+    plugins: [
+      {
+        name: "css-and-scripts-as-text",
+        setup(build) {
+          build.onLoad({ filter: /\.scss$/ }, (_) => ({
+            contents: "",
+            loader: "text",
+          }))
+          build.onLoad({ filter: /\.inline\.(ts|js)$/ }, (_) => ({
+            contents: "",
+            loader: "text",
+          }))
+        },
+      },
+    ],
+  })
+}
+
+// brain-cache: shape of a stored MDAST cache entry.
+type MdCacheEntry = {
+  version: number
+  slug: string
+  ast: MDRoot
+  data: Record<string, unknown>
+}
+
+export function createFileParser(ctx: BuildCtx, fps: FilePath[]) {
+  const { argv, cfg } = ctx
+  return async (processor: QuartzMdProcessor) => {
+    const res: MarkdownContent[] = []
+    for (const fp of fps) {
+      try {
+        const perf = new PerfTimer()
+
+        // brain-cache: read raw bytes once; re-use as VFile value and as
+        // hash input. Equivalent to `await read(fp)` from to-vfile but
+        // gives us a Buffer for the cache key without a second fs.readFile.
+        const rawBytes = await readFile(fp)
+        const file = new VFile({ path: fp as string, value: rawBytes })
+
+        // strip leading and trailing whitespace
+        file.value = file.value.toString().trim()
+
+        // Text -> Text transforms
+        for (const plugin of cfg.plugins.transformers.filter((p) => p.textTransform)) {
+          file.value = plugin.textTransform!(ctx, file.value.toString())
+        }
+
+        // base data properties that plugins may use
+        file.data.filePath = file.path as FilePath
+        file.data.relativePath = path.posix.relative(argv.directory, file.path!) as FilePath
+        file.data.slug = slugifyFilePath(file.data.relativePath as FilePath)
+
+        // brain-fastpath: snapshot raw source BEFORE OFM transformer mutates vfile.value.
+        // computeFingerprint (fastpath_manifest.ts) reads vfile.data.rawSource to get the
+        // unmodified markdown text for canonical-blob building.  The OFM transformer runs
+        // later in processor.run — e.g. it appends |^blockId display aliases to transclusion
+        // links (![[target#^block]] → ![[target#^block|^block]]).  We store the raw disk
+        // bytes (rawBytes is the original Buffer from fs.readFile) so the snapshot is
+        // byte-identical to what parse.ts originally loaded, regardless of any later
+        // textTransform / trim / OFM mutations.
+        ;(file.data as Record<string, unknown>)["rawSource"] = rawBytes.toString("utf8")
+
+        // brain-cache: check MDAST cache before running the expensive parse.
+        const mdKey = ctx.cacheDir ? cacheKey(rawBytes, file.data.slug as string) : null
+        if (mdKey !== null) {
+          const cached = getCached<MdCacheEntry>(ctx.cacheDir!, mdKey)
+          // belt-and-suspenders: version is already baked into the cache key (the
+          // key hash includes CACHE_VERSION), so a stale entry at a different key
+          // path is simply a miss. The explicit version check here guards the
+          // unlikely edge case where two builds with different CACHE_VERSION values
+          // happen to collide on a key (sha256 collision) — effectively impossible,
+          // but cheap to double-check.
+          if (cached !== null && cached.version === CACHE_VERSION) {
+            // Reconstitute MarkdownContent from cached entry.
+            // value is set to the trimmed string so cache-hit and cache-miss
+            // paths produce the same file.value shape for downstream emitters.
+            const cachedFile = new VFile({ path: fp as string, value: rawBytes })
+            cachedFile.value = rawBytes.toString().trim()
+            // Rehydrate Date instances that JSON serialization stringified.
+            // Mutates cached.data in place — fine, the cache file on disk is
+            // not re-read and the entry won't be written back.
+            rehydrateDates(cached.data as Record<string, unknown>)
+            cachedFile.data = cached.data as typeof file.data
+            // brain-fastpath: always inject rawSource from current rawBytes even on cache hit.
+            // Old cache entries written before this snapshot was introduced may lack rawSource;
+            // setting it here ensures computeFingerprint never encounters a missing field
+            // without requiring a CACHE_VERSION bump.
+            ;(cachedFile.data as Record<string, unknown>)["rawSource"] = rawBytes.toString("utf8")
+            res.push([cached.ast, cachedFile])
+            if (argv.verbose) {
+              console.log(`[markdown hit] ${fp} -> ${cachedFile.data.slug} (${perf.timeSince()})`)
+            }
+            continue
+          }
+        }
+
+        const ast = processor.parse(file)
+        const newAst = await processor.run(ast, file)
+
+        // brain-cache: push BEFORE putCached so the file is always emitted
+        // even if putCached throws (ENOSPC / EACCES / readonly FS). A write
+        // failure must never silently drop a file from the build output.
+        res.push([newAst, file])
+
+        // brain-cache: store result for next build.
+        if (mdKey !== null) {
+          putCached<MdCacheEntry>(ctx.cacheDir!, mdKey, {
+            version: CACHE_VERSION,
+            slug: file.data.slug as string,
+            ast: newAst,
+            data: file.data as Record<string, unknown>,
+          })
+        }
+
+        if (argv.verbose) {
+          console.log(`[markdown] ${fp} -> ${file.data.slug} (${perf.timeSince()})`)
+        }
+      } catch (err) {
+        trace(`\nFailed to process markdown \`${fp}\``, err as Error)
+      }
+    }
+
+    return res
+  }
+}
+
+export function createMarkdownParser(ctx: BuildCtx, mdContent: MarkdownContent[]) {
+  return async (processor: QuartzHtmlProcessor) => {
+    const res: ProcessedContent[] = []
+    for (const [ast, file] of mdContent) {
+      try {
+        const perf = new PerfTimer()
+
+        const newAst = await processor.run(ast as MDRoot, file)
+        res.push([newAst, file])
+
+        if (ctx.argv.verbose) {
+          console.log(`[html] ${file.data.slug} (${perf.timeSince()})`)
+        }
+      } catch (err) {
+        trace(`\nFailed to process html \`${file.data.filePath}\``, err as Error)
+      }
+    }
+
+    return res
+  }
+}
+
+const clamp = (num: number, min: number, max: number) =>
+  Math.min(Math.max(Math.round(num), min), max)
+
+export async function parseMarkdown(ctx: BuildCtx, fps: FilePath[]): Promise<ProcessedContent[]> {
+  const { argv } = ctx
+  const perf = new PerfTimer()
+  const log = new QuartzLogger(argv.verbose)
+
+  // brain-cache: resolve cacheDir. Precedence:
+  //   1. ctx.cacheDir already set by caller (string | null | undefined)
+  //   2. argv.noCache === true  → null  (disable for this run)
+  //   3. default               → <argv.directory>/.quartz/.cache/parser
+  // `cacheDir: undefined` from an upstream BuildCtx constructor means
+  // "not set yet" and falls through to the default.
+  // NOTE: this path must match brain.maintenance._PARSER_CACHE_RELPATH
+  // (.quartz/.cache/parser), wiped by `brain-rebuild --clean-cache`.
+  const cacheDir: string | null =
+    ctx.cacheDir !== undefined
+      ? ctx.cacheDir
+      : argv.noCache
+        ? null
+        : path.join(argv.directory, ".quartz", ".cache", "parser")
+
+  const patchedCtx: BuildCtx = { ...ctx, cacheDir }
+
+  // rough heuristics: 128 gives enough time for v8 to JIT and optimize parsing code paths
+  const CHUNK_SIZE = 128
+  const concurrency = argv.concurrency ?? clamp(fps.length / CHUNK_SIZE, 1, 4)
+
+  let res: ProcessedContent[] = []
+  log.start(`Parsing input files using ${concurrency} threads`)
+  if (concurrency === 1) {
+    try {
+      const mdRes = await createFileParser(patchedCtx, fps)(createMdProcessor(patchedCtx))
+      res = await createMarkdownParser(patchedCtx, mdRes)(createHtmlProcessor(patchedCtx))
+    } catch (error) {
+      log.end()
+      throw error
+    }
+  } else {
+    await transpileWorkerScript()
+    const pool = workerpool.pool("./quartz/bootstrap-worker.mjs", {
+      minWorkers: "max",
+      maxWorkers: concurrency,
+      workerType: "thread",
+    })
+    const errorHandler = (err: any) => {
+      console.error(err)
+      process.exit(1)
+    }
+
+    // brain-cache: include cacheDir so workers can read/write the same
+    // on-disk cache. WorkerSerializableBuildCtx = Omit<BuildCtx, "cfg" | "trie">
+    // so cacheDir is automatically part of the type; this literal is explicit
+    // per the upstream pattern (workers deserialise by spreading partialCtx).
+    const serializableCtx: WorkerSerializableBuildCtx = {
+      buildId: patchedCtx.buildId,
+      argv: patchedCtx.argv,
+      allSlugs: patchedCtx.allSlugs,
+      allFiles: patchedCtx.allFiles,
+      incremental: patchedCtx.incremental,
+      cacheDir: patchedCtx.cacheDir,
+    }
+
+    const textToMarkdownPromises: WorkerPromise<MarkdownContent[]>[] = []
+    let processedFiles = 0
+    for (const chunk of chunks(fps, CHUNK_SIZE)) {
+      textToMarkdownPromises.push(pool.exec("parseMarkdown", [serializableCtx, chunk]))
+    }
+
+    const mdResults: Array<MarkdownContent[]> = await Promise.all(
+      textToMarkdownPromises.map(async (promise) => {
+        const result = await promise
+        processedFiles += result.length
+        log.updateText(`text->markdown ${styleText("gray", `${processedFiles}/${fps.length}`)}`)
+        return result
+      }),
+    ).catch(errorHandler)
+
+    const markdownToHtmlPromises: WorkerPromise<ProcessedContent[]>[] = []
+    processedFiles = 0
+    for (const mdChunk of mdResults) {
+      markdownToHtmlPromises.push(pool.exec("processHtml", [serializableCtx, mdChunk]))
+    }
+    const results: ProcessedContent[][] = await Promise.all(
+      markdownToHtmlPromises.map(async (promise) => {
+        const result = await promise
+        processedFiles += result.length
+        log.updateText(`markdown->html ${styleText("gray", `${processedFiles}/${fps.length}`)}`)
+        return result
+      }),
+    ).catch(errorHandler)
+
+    res = results.flat()
+    await pool.terminate()
+  }
+
+  log.end(`Parsed ${res.length} Markdown files in ${perf.timeSince()}`)
+  return res
+}

brain/quartz_overrides/quartz/processors/parser_cache.ts

@@ -0,0 +1,78 @@
+// Pure file-IO parser result cache for the Quartz incremental-build pipeline.
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/processors/parser_cache.ts` by
+// `brain vault render --overlay`. It does NOT compile or run from the
+// brain repo itself; it is pure Node.js with no Quartz-internal imports
+// so it can also be unit-tested directly from the brain repo with
+// `tsx --test tests/test_quartz_parser_cache.ts`.
+//
+// Cache key: sha256(CACHE_VERSION as 4-byte big-endian || slug as UTF-8 || fileBytes).
+// Version baked into key — bumping CACHE_VERSION changes every key and
+// therefore makes every existing entry unreachable without deleting them.
+// Disk: <cacheDir>/<key[0:2]>/<key[2:4]>/<key>.json (two-level sharding
+// keeps any single directory under a few thousand entries at vault scale).
+// Atomicity: write to <path>.<pid>.<uuid>.tmp, then fs.renameSync (POSIX-atomic).
+// pid + randomUUID() guarantees a unique tmp path per write even across
+// worker_threads sharing the same pid, so concurrent writes to the same key
+// are independent: they race to rename identical content and the last rename
+// wins without corruption.
+// Eviction: none. Disk grows O(vault size). The entire cache directory
+// can be deleted at any time — the next build regenerates it.
+
+import { createHash, randomUUID } from "node:crypto"
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+export const CACHE_VERSION = 1
+
+// cacheKey computes sha256(version-bytes || slug-utf8 || fileBytes) as lowercase hex.
+// CACHE_VERSION is mixed in first so a global version bump changes every key.
+export function cacheKey(fileBytes: Buffer, slug: string): string {
+  const hash = createHash("sha256")
+  const versionBuf = Buffer.allocUnsafe(4)
+  versionBuf.writeUInt32BE(CACHE_VERSION, 0)
+  hash.update(versionBuf)
+  hash.update(slug, "utf8")
+  hash.update(fileBytes)
+  return hash.digest("hex")
+}
+
+// cachePath returns the on-disk JSON path for a given key under cacheDir.
+// Two-level shard: <aa>/<bb>/<full-key>.json where aa=key[0:2], bb=key[2:4].
+export function cachePath(cacheDir: string, key: string): string {
+  return join(cacheDir, key.slice(0, 2), key.slice(2, 4), `${key}.json`)
+}
+
+// getCached reads and JSON-parses the cache entry for key.
+// Returns null on ENOENT (clean miss) or SyntaxError (corrupt/truncated file —
+// logged as a warning so the next build silently regenerates the entry without
+// crashing the whole build). Any other unexpected error (permissions, I/O, etc.)
+// is rethrown.
+export function getCached<T>(cacheDir: string, key: string): T | null {
+  const p = cachePath(cacheDir, key)
+  try {
+    const raw = readFileSync(p, "utf8")
+    return JSON.parse(raw) as T
+  } catch (err: unknown) {
+    if (err instanceof Error && "code" in err && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      return null
+    }
+    if (err instanceof SyntaxError) {
+      console.warn(`[parser_cache] discarding corrupt entry ${p}: ${err.message}`)
+      return null
+    }
+    throw err
+  }
+}
+
+// putCached serialises value to JSON and writes it atomically via a tmp file.
+// mkdir -p is called on the shard directory so the first write to a shard
+// creates the directory tree.
+export function putCached<T>(cacheDir: string, key: string, value: T): void {
+  const p = cachePath(cacheDir, key)
+  mkdirSync(dirname(p), { recursive: true })
+  const tmp = `${p}.${process.pid}.${randomUUID()}.tmp`
+  writeFileSync(tmp, JSON.stringify(value))
+  renameSync(tmp, p)
+}

brain/quartz_overrides/quartz/static/codeCopy.js

@@ -0,0 +1,196 @@
+// Brain wiki redesign — code-block copy-button injector (Lane C).
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/static/codeCopy.js` by `brain vault render
+// --overlay`, and is copied verbatim into every build's `static/` dir
+// by Quartz's stock `Plugin.Static()` emitter (no extra wiring needed
+// — Quartz already mirrors `quartz/static/` 1:1 into the build
+// output). The script is referenced from page `<head>` by the brain
+// `Plugin.CodeCopy` transformer's `externalResources()` hook (see
+// `codeCopy.ts` for the inject side).
+//
+// Tested against Quartz v4.5.x (April 2026). Plain vanilla JS — no
+// transpile, no bundler — so it survives any future Quartz refactor
+// of its plugin pipeline.
+//
+// What this script does, and why: Quartz's stock `Body.tsx` wires a
+// `.clipboard-button` into every `<pre>`, but its visual treatment
+// (gray border, white background, top-right floating chip) reads as
+// 2018-Hugo. The 2026 redesign wants a small-caps "Copy" pill with
+// the redesign palette, an "↗ Copied" success state, ARIA labelling,
+// and graceful keyboard focus. Rather than rewrite `Body.tsx` (which
+// would require also vendoring its clipboard.inline.ts), we hide
+// the stock button via CSS in `_code.scss` and inject our own
+// `.brain-code-copy` button here.
+//
+// Idempotency contract: every `<pre>` gets at most one
+// `.brain-code-copy` button. We mark each processed `<pre>` with
+// `data-brain-copy-injected="true"` so SPA navigation re-runs of
+// the tagger don't double-inject. First writer wins.
+//
+// Also handles the `data-language` attribute fallback. Quartz's
+// `Plugin.SyntaxHighlighting` stamps `<pre data-language="bash">`
+// directly, but for fenced code blocks that the highlighter doesn't
+// match (e.g. unrecognised languages), the attribute lands only on
+// the inner `<code class="language-X">`. The CSS-only language label
+// in `_code.scss` reads the attribute via `attr()`, which only works
+// on `pre[data-language]`. This script copies the attribute from the
+// inner `<code>` to the outer `<pre>` whenever the outer is missing
+// it, so the label reliably renders.
+//
+// Browser support: targets evergreen Chrome / Firefox / Safari. Uses
+// `navigator.clipboard.writeText`, `document.querySelectorAll`, and
+// `addEventListener` — all baseline since 2017.
+;(function () {
+  // brain: the data-attribute we stamp on processed `<pre>` blocks.
+  // Used as the idempotency check.
+  var INJECTED_ATTR = "data-brain-copy-injected"
+
+  // brain: regex matching `language-X` classes Quartz writes onto
+  // `<code>` for fenced blocks. Captures the language token.
+  var LANGUAGE_CLASS_RE = /(?:^|\s)language-([\w+-]+)/
+
+  // brain: copy the inner `<code class="language-X">`'s language token
+  // up to the outer `<pre data-language="X">` whenever the outer is
+  // missing it. CSS reads from the outer; the highlighter sometimes
+  // only stamps the inner. Idempotent — skips when outer already has
+  // the attribute.
+  function liftLanguageAttr(pre) {
+    if (pre.hasAttribute("data-language")) return
+    var code = pre.querySelector("code")
+    if (code === null) return
+    var match = LANGUAGE_CLASS_RE.exec(code.className)
+    if (match === null) return
+    pre.setAttribute("data-language", match[1])
+  }
+
+  // brain: extract the code text the user wants to copy. Stock
+  // Quartz's clipboard handler reads `dataset.clipboard` (a JSON
+  // override) when present, otherwise falls back to `innerText`.
+  // Mirror that contract so syntax-highlighted blocks with line
+  // numbers don't leak the gutter into the copy buffer.
+  function codeTextFor(pre) {
+    var inner = pre.querySelector("code")
+    if (inner === null) return pre.innerText
+    if (inner.dataset.clipboard) {
+      try {
+        return JSON.parse(inner.dataset.clipboard)
+      } catch (_e) {
+        // Fall through to innerText if the JSON is malformed.
+      }
+    }
+    return inner.innerText
+  }
+
+  // brain: the action accessible name when the button is at rest.
+  // Mirrored into `aria-label` after every flash so SR users hear
+  // the right verb when the chip returns to its idle state.
+  var BASE_LABEL = "Copy code to clipboard"
+
+  // brain: the actual copy handler. Modern browsers gate
+  // `navigator.clipboard` behind secure contexts (https / localhost).
+  // Falls back to a no-op (visible "Copy failed" pulse) when the
+  // browser blocks it — better UX than a silent click.
+  function copyHandler(pre, button) {
+    return function (event) {
+      event.preventDefault()
+      var text = codeTextFor(pre)
+      if (typeof navigator.clipboard === "undefined") {
+        // Non-secure context — no clipboard API available.
+        flashLabel(button, "Unavailable")
+        return
+      }
+      navigator.clipboard.writeText(text).then(
+        function () {
+          flashLabel(button, "Copied")
+        },
+        function () {
+          flashLabel(button, "Failed")
+        },
+      )
+    }
+  }
+
+  // brain: swap the button label to a status string for 1.4s, then
+  // restore. Toggles `.is-copied` so `_code.scss` can paint the
+  // success state.
+  //
+  // brain (Lane C audit fix 2026-05-02): also mirror the status into
+  // `aria-label`. Per ARIA spec, `aria-label` OVERRIDES the
+  // element's text content for the accessible name — so updating
+  // only `textContent` left SR users hearing "Copy code to clipboard"
+  // on every press, regardless of whether the copy succeeded.
+  // Mapping: "Copied" → "Code copied to clipboard" (action-confirming
+  // affirmative), "Failed" / "Unavailable" → "<base label> — <status>"
+  // (annotated state) so the user hears why the action didn't take.
+  function flashLabel(button, status) {
+    var prior = button.dataset.brainOriginalLabel || "Copy"
+    button.textContent = status
+    var statusLabel
+    if (status === "Copied") {
+      statusLabel = "Code copied to clipboard"
+    } else {
+      statusLabel = BASE_LABEL + " — " + status.toLowerCase()
+    }
+    button.setAttribute("aria-label", statusLabel)
+    button.classList.add("is-copied")
+    window.setTimeout(function () {
+      button.textContent = prior
+      button.setAttribute("aria-label", BASE_LABEL)
+      button.classList.remove("is-copied")
+    }, 1400)
+  }
+
+  // brain: build the copy button as a DOM node. Class `.brain-code-copy`
+  // matches the SCSS selector in `_code.scss`. ARIA label spells out
+  // the action for screen readers (the visible "Copy" text is also
+  // the accessible name; `aria-label` refines it for non-visual
+  // users — and is updated on each flashLabel() call so it tracks
+  // the visible status).
+  function buildButton() {
+    var button = document.createElement("button")
+    button.type = "button"
+    button.className = "brain-code-copy"
+    button.textContent = "Copy"
+    button.setAttribute("aria-label", BASE_LABEL)
+    button.dataset.brainOriginalLabel = "Copy"
+    return button
+  }
+
+  // brain: walk every `<pre>` in the article body and inject the
+  // copy button if not already done. We scope to `article` so popover
+  // hints and chrome blocks (no code) aren't touched.
+  function injectAll() {
+    var pres = document.querySelectorAll("article pre")
+    pres.forEach(function (pre) {
+      // brain: idempotency — skip already-processed blocks.
+      if (pre.getAttribute(INJECTED_ATTR) === "true") return
+      pre.setAttribute(INJECTED_ATTR, "true")
+
+      // brain: ensure the language label has an attribute to read.
+      liftLanguageAttr(pre)
+
+      // brain: build + wire the button.
+      var button = buildButton()
+      button.addEventListener("click", copyHandler(pre, button))
+      pre.appendChild(button)
+    })
+  }
+
+  // brain: run on first DOM ready. `DOMContentLoaded` fires before
+  // first paint of below-fold content; above-fold pre blocks may
+  // briefly miss the button, but the hover-only opacity means it's
+  // invisible until cursor enters the pre — no flash.
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", injectAll)
+  } else {
+    injectAll()
+  }
+
+  // brain: re-run on Quartz SPA navigation. `enableSPA: true` in
+  // `quartz.config.ts` makes Quartz dispatch a `nav` event on
+  // `document` after each in-page route change. The injected button
+  // doesn't survive the morph (micromorph swaps the article DOM),
+  // so we re-walk on every nav.
+  document.addEventListener("nav", injectAll)
+})()