secondbrain-py 0.2.1__py3-none-any.whl

brain/quartz_overrides/quartz/plugins/transformers/derivedFenceMark.ts

@@ -0,0 +1,302 @@
+// Sample Quartz v4 markdown transformer for brain vaults.
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/plugins/transformers/derivedFenceMark.ts`
+// by `brain vault render --overlay`. It does NOT compile or run from
+// the brain repo itself; the imports below resolve against the
+// dependencies Quartz pulls into the cloned workspace via
+// `npm install`, not against any package brain ships.
+//
+// Tested against Quartz v4.5.x (April 2026). If a future Quartz
+// version restructures the transformer plugin shape or the mdast
+// types it uses, pull the latest transformer reference from
+// https://github.com/jackyzha0/quartz/tree/v4/quartz/plugins/transformers
+// and re-apply the brain tweaks flagged below — `// brain:` for
+// value/structural choices on upstream-supported fields, and
+// `// brain-extension:` for keys/types that don't exist in stock
+// Quartz.
+//
+// What this transformer does, and why: Phase D
+// (`src/brain/vault/derived_links/fence.py`) writes a fenced section
+// at the bottom of every `_ingested/` mirror file:
+//
+//     <!-- BRAIN_DERIVED_START -->
+//     ## Related (auto-generated, do not edit)
+//     - [[partner-stem|Partner Title]] *(same_day_participant)*
+//     - [[partner-stem|Partner Title]] *(shared_thread)*
+//     <!-- BRAIN_DERIVED_END -->
+//
+// The brain graph renderer needs to distinguish these "evidence"
+// edges from authored wiki-links so it can apply dashed/translucent
+// styling and surface the rule in hover tooltips. This transformer
+// scans the mdast tree for the BRAIN_DERIVED_START / END html-comment
+// markers and stamps each `<a>` link inside the fenced range with
+// `data-brain-derived="true"` + `data-brain-rule="<rule>"` (and
+// `data-brain-weight` if a weight is encoded — see parser below).
+// The custom contentIndex emitter
+// (`quartz_overrides/plugins/emitters/contentIndex.ts`) reads these
+// HTML attributes back when emitting `static/contentIndex.json` so
+// each link record carries `kind: "derived"` + structured rule /
+// weight metadata.
+//
+// brain (Lane B 2026-05-02): also writes a `title` attribute on each
+// derived link so the `cursor: help` styling Lane B's `_links.scss`
+// applies to derived links surfaces a real tooltip on hover. Format:
+// `"Derived: <rule>"` when the bullet emphasis parsed cleanly,
+// `"Derived (related)"` as a fallback when no rule was extracted.
+// Cross-lane edit (Lane B's CSS depends on this transformer's data).
+//
+// Registration: this transformer must run AFTER
+// `Plugin.ObsidianFlavoredMarkdown()` so that `[[wiki-link]]` syntax
+// has already been converted into mdast `link` nodes before we walk
+// the tree. The brain `quartz.config.ts` template wires it up in the
+// correct slot — see the `transformers: [...]` list there.
+//
+// brain: marker constants are mirrored verbatim from
+// `src/brain/vault/derived_links/fence.py` (the canonical Phase D
+// source). TypeScript can't import from Python, so they live in two
+// places — keep them in sync. If Phase D ever changes the marker
+// shape, update both files together and re-run the overlay's
+// parse-smoke test against a freshly-rendered fixture vault.
+
+import type { Root, RootContent, Link, Paragraph, Emphasis } from "mdast"
+
+import { QuartzTransformerPlugin } from "../types"
+
+// brain: kept identical to ``FENCE_START_MARKER`` /
+// ``FENCE_END_MARKER`` in ``src/brain/vault/derived_links/fence.py``.
+// Detection uses ``includes`` (not equality) so leading/trailing
+// whitespace introduced by markdown parsers around the html-comment
+// node doesn't break the match.
+const FENCE_START_MARKER = "<!-- BRAIN_DERIVED_START -->"
+const FENCE_END_MARKER = "<!-- BRAIN_DERIVED_END -->"
+
+// brain-extension: the structured shape we extract from each bullet's
+// trailing emphasis. ``rule`` is what fence.py writes today
+// (``same_day_participant`` / ``shared_thread``). It defaults to
+// undefined so the emitter's classifier can omit the
+// ``data-brain-rule`` attribute when the parser couldn't pin a value
+// down. Note: a missing ``rule`` does NOT downgrade the link's
+// classification — see ``stampDerived`` for the fence-membership
+// truth-source rule.
+interface BulletMeta {
+  rule?: string
+}
+
+// brain-extension: parses the trailing-emphasis text of a Phase D
+// bullet. Strict — only the shape fence.py actually writes today
+// (``*(<rule>)*`` where ``<rule>`` is an identifier) is accepted;
+// anything else returns ``{}``. Identifier-shape guard prevents
+// matching whole sentences if a future fence accidentally mixes
+// prose with the metadata convention.
+//
+// brain: the fence membership — not this parser's success — is the
+// truth-source for ``kind: "derived"``. Links inside the fence whose
+// emphasis fails to parse (missing, malformed, mixed prose) still
+// get ``data-brain-derived="true"`` stamped on them by
+// ``stampDerived``; only ``data-brain-rule`` is omitted. If Phase E
+// ever adds a structured ``weight`` to the bullet shape, extend
+// this parser and ``BulletMeta`` together — don't pre-build the
+// hook.
+function parseBulletEmphasis(text: string): BulletMeta {
+  const match = text.trim().match(/^\(([A-Za-z_][A-Za-z0-9_-]*)\)$/)
+  if (!match) return {}
+  return { rule: match[1] }
+}
+
+// brain: recursive text collector. mdast emphasis/strong nodes can
+// contain mixed text + nested formatting; flattening to a plain
+// string is safer than reading ``.children[0].value`` blindly when
+// fence.py's output is hand-edited or rendered through alternate
+// markdown processors.
+function collectText(node: RootContent): string {
+  if (node.type === "text") return node.value
+  if ("children" in node && Array.isArray(node.children)) {
+    return (node.children as RootContent[]).map(collectText).join("")
+  }
+  return ""
+}
+
+// brain: in-place attribute stamper. mdast's standard extension
+// point for "attach HTML attributes that survive into hast" is the
+// ``data.hProperties`` object — remark-rehype copies its keys onto
+// the corresponding hast element's properties, which then become
+// real HTML attributes after stringification. The brain emitter
+// reads these attributes back via ``classifyLink`` to flag derived
+// links in ``contentIndex.json``.
+//
+// brain: ``data-brain-derived`` is stamped unconditionally for
+// every link inside the fence range — fence membership is the
+// truth-source for "this is a derived edge," NOT the bullet
+// emphasis parse. ``data-brain-rule`` is added only when the parser
+// pinned a rule down; bullets with missing/malformed metadata still
+// produce ``kind: "derived"`` records (just without a rule field).
+//
+// brain (Lane B 2026-05-02): also stamp ``title`` so the
+// ``cursor: help`` styling on derived links in
+// ``brain/styles/_links.scss`` actually surfaces a tooltip on hover.
+// Without the title write, the SCSS rule promised an affordance the
+// DOM didn't deliver. The fallback string for the rule-less case is
+// the literal word "Derived (related)" so screen readers and
+// browser tooltips both read sensibly even when the bullet emphasis
+// failed to parse.
+function stampDerived(link: Link, meta: BulletMeta): void {
+  const data = (link.data ??= {}) as Record<string, unknown>
+  const props = (data.hProperties ??= {}) as Record<string, string>
+  props["data-brain-derived"] = "true"
+  if (meta.rule !== undefined) {
+    props["data-brain-rule"] = meta.rule
+    props["title"] = `Derived: ${meta.rule}`
+  } else {
+    props["title"] = "Derived (related)"
+  }
+}
+
+// brain: walks a Phase D bullet's paragraph children to find the
+// (link, trailing-emphasis) pair fence.py writes. The bullet shape
+// after Obsidian-flavored-markdown processing is:
+//
+//   listItem
+//   └─ paragraph
+//      ├─ link        ← [[stem|title]]
+//      ├─ text " "
+//      └─ emphasis    ← *(<rule>)*
+//
+// We walk left-to-right so a paragraph that mistakenly contains
+// multiple links gets paired correctly: each link inherits the
+// emphasis that immediately follows it, falling back to "no rule"
+// if none does. Returns the map keyed by mdast link node identity.
+function pairLinksAndRules(paragraph: Paragraph): Map<Link, BulletMeta> {
+  const result = new Map<Link, BulletMeta>()
+  let pendingLink: Link | null = null
+  for (const child of paragraph.children) {
+    if (child.type === "link") {
+      if (pendingLink !== null && !result.has(pendingLink)) {
+        // Previous link had no trailing emphasis; commit it as
+        // "derived but rule unknown" so the emitter still flags it.
+        result.set(pendingLink, {})
+      }
+      pendingLink = child
+      continue
+    }
+    if (child.type === "emphasis" && pendingLink !== null) {
+      const text = collectText(child as Emphasis)
+      result.set(pendingLink, parseBulletEmphasis(text))
+      pendingLink = null
+    }
+  }
+  if (pendingLink !== null && !result.has(pendingLink)) {
+    result.set(pendingLink, {})
+  }
+  return result
+}
+
+// brain: top-level mdast walker. Tracks ``inFence`` state across the
+// root's direct children (where the BRAIN_DERIVED_START / END html
+// comments live as siblings of the bullet list). Within the fence
+// range, recurses into descendants and:
+//
+//   1. Records every link node so we know which links are derived
+//      (kind="derived") regardless of whether their bullet's
+//      emphasis was parseable.
+//   2. Detects paragraph nodes (the bullet's content node) and pairs
+//      each link with its trailing emphasis to extract rule/weight
+//      metadata.
+//
+// Two-pass shape (collect, then stamp) keeps the recursion side-
+// effect-free and lets us merge rule/weight metadata onto the
+// minimal ``derived=true`` baseline in one place.
+function annotateFence(tree: Root): void {
+  let inFence = false
+  const linksInFence = new Set<Link>()
+  const ruleByLink = new Map<Link, BulletMeta>()
+
+  const visit = (node: RootContent | Root): void => {
+    if (node.type === "html" && typeof node.value === "string") {
+      // brain: html-comment markers are root-level siblings of the
+      // bullet list, so toggling ``inFence`` here (rather than on
+      // descent) gives the correct enclosing-range semantics. The
+      // markers themselves don't carry links, so there's nothing to
+      // miss by skipping the recursion below.
+      //
+      // brain: literal ``<!-- BRAIN_DERIVED_START -->`` text in body
+      // prose would also trigger this — vault docs almost never
+      // self-document the fence format (the canonical doc lives in
+      // ``docs/specs/`` outside the vault), so we accept the
+      // false-positive risk rather than wrap the marker in a unique
+      // sentinel that fence.py would also need to emit.
+      if (!inFence && node.value.includes(FENCE_START_MARKER)) {
+        inFence = true
+        return
+      }
+      if (inFence && node.value.includes(FENCE_END_MARKER)) {
+        inFence = false
+        return
+      }
+    }
+
+    if (inFence) {
+      if (node.type === "link") {
+        linksInFence.add(node)
+      }
+      // brain: paragraph-only — fence.py emits bullets, which become
+      // ``listItem > paragraph`` after mdast parsing. If a future
+      // fence shape ever inserts a heading or blockquote inside the
+      // marker range, links there would still get
+      // ``kind: "derived"`` (via ``linksInFence`` above) but without
+      // a ``rule`` field. Revisit the pairing logic at that point.
+      if (node.type === "paragraph") {
+        for (const [link, meta] of pairLinksAndRules(node)) {
+          ruleByLink.set(link, meta)
+        }
+      }
+    }
+
+    if ("children" in node && Array.isArray(node.children)) {
+      for (const child of node.children as RootContent[]) {
+        visit(child)
+      }
+    }
+  }
+
+  visit(tree)
+
+  if (inFence) {
+    // brain: defensive — fence.py always emits matched START/END
+    // pairs (and ``extract_fence`` in fence.py guards against the
+    // same corruption from the other side), but a hand-edited file
+    // could leave a doc in-fence forever. Drop everything we
+    // collected and surface a console warning rather than silently
+    // mis-tag every link below the orphaned START marker.
+    console.warn(
+      "[derivedFenceMark] unmatched BRAIN_DERIVED_START — discarding fence annotations for this document",
+    )
+    return
+  }
+
+  for (const link of linksInFence) {
+    stampDerived(link, ruleByLink.get(link) ?? {})
+  }
+}
+
+// brain-extension: the transformer plugin itself. Empty options
+// object is intentional — the only knobs would be the marker strings
+// (which are sourced from fence.py) and the matched-rule allowlist
+// (which is enforced upstream by fence.py's ``FENCE_RULES``).
+// Keeping the signature ``(opts?: never)`` documents that no
+// configuration is expected; if a knob is genuinely needed later,
+// widen the type at that point rather than guessing now.
+export const DerivedFenceMark: QuartzTransformerPlugin = () => {
+  return {
+    name: "DerivedFenceMark",
+    markdownPlugins() {
+      return [
+        () => {
+          return (tree: Root) => {
+            annotateFence(tree)
+          }
+        },
+      ]
+    },
+  }
+}

brain/quartz_overrides/quartz/plugins/transformers/emailThread.ts

@@ -0,0 +1,148 @@
+// Brain wiki redesign — email-thread reading-mode transformer plugin
+// (P4.4 of the Wiki UX Overhaul).
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/plugins/transformers/emailThread.ts`
+// by `brain vault render --overlay`. It does NOT compile or run from
+// the brain repo itself; the imports below resolve against the
+// dependencies Quartz pulls into the cloned workspace via
+// `npm install`, not against any package brain ships.
+//
+// Tested against Quartz v4.5.x (April 2026). If a future Quartz
+// version restructures the transformer plugin shape or the
+// `externalResources()` hook contract, pull the latest transformer
+// reference from
+// https://github.com/jackyzha0/quartz/tree/v4/quartz/plugins/transformers
+// and re-apply the brain tweaks flagged below — `// brain:` for
+// value/structural choices on upstream-supported fields, and
+// `// brain-extension:` for keys/types that don't exist in stock
+// Quartz.
+//
+// What this transformer does, and why: P4.4 ships an "Email thread
+// reading mode" — every per-message section in an `email_thread`
+// body becomes a collapsible `<details>` block (older messages
+// closed, latest expanded), and a "Show only my replies" filter
+// button hides every section whose `From:` header doesn't equal the
+// owner's email. The runtime that wires these affordances lives in
+// `quartz/static/emailThread.js`; this transformer's job is to (a)
+// inject that script into every page and (b) bake the owner's email
+// (read from `process.env.BRAIN_USER_EMAIL` at build time) into a
+// tiny inline `<script>window.BRAIN_USER_EMAIL = "..."</script>`
+// snippet so the runtime knows whose `From:` to match against.
+//
+// brain: this transformer ALWAYS injects the runtime — same pattern
+// as `LinkSourceTag` and `CodeCopy`, both of which are part of the
+// production redesign and don't gate on env vars. The user-email
+// global is emitted only when `BRAIN_USER_EMAIL` is set; without it
+// the runtime renders the toggle button anyway but the filter
+// matches no message (correct "you forgot to set the env var" cue).
+//
+// brain: cross-references for the email-thread reading-mode contract:
+//   * `quartz_overrides/quartz/static/emailThread.js` — the runtime
+//     this transformer points page `<head>` at.
+//   * `quartz_overrides/quartz/styles/brain/_email_thread.scss` — the
+//     SCSS partial that paints `<details>` and the filter button,
+//     and reads the body class (`brain-replies-only`) plus per-
+//     section attributes (`data-brain-is-mine`) the runtime stamps.
+//   * `src/brain/ingest/gmail.py` — `to_extracted_thread()`, which
+//     emits the `## YYYY-MM-DD HH:MM — <from>` headings + per-message
+//     `<details>` markup the runtime parses.
+//   * `src/brain/config.py` — the `Config.user_email` field and
+//     `BRAIN_USER_EMAIL` env-var contract this transformer mirrors.
+//
+// Registration: this transformer has NO ordering requirement among
+// the other transformers — it doesn't touch the mdast tree, only
+// contributes resources via `externalResources()`. Place it anywhere
+// in the `transformers: [...]` list; the brain `quartz.config.ts`
+// template wires it next to `LinkSourceTag` / `CodeCopy` so the
+// brain script-only transformers stay grouped.
+
+import { QuartzTransformerPlugin } from "../types"
+
+// brain-extension: the path the page `<script src=...>` tag points
+// at. Leading slash is intentional — Quartz emits pages at arbitrary
+// slug depths (e.g. `/_ingested/gmail/<thread>/index.html`) and a
+// relative `static/emailThread.js` would break for any non-root
+// page. Server-rooted `/static/emailThread.js` resolves consistently
+// regardless of which page the user landed on. This works because
+// Caddy's `file_server` (and Quartz's stock `file_server` in dev)
+// serves the build dir as the site root
+// (`<vault>/.quartz/current/static/emailThread.js`).
+const SCRIPT_SRC = "/static/emailThread.js"
+
+// brain-extension: build-time env var carrying the owner's email.
+// Read inside `externalResources()` so each plugin instance evaluates
+// the value fresh per build (matters for tests + for `bin/brain-up`
+// re-invocations where the env may differ between runs).
+const USER_EMAIL_ENV_VAR = "BRAIN_USER_EMAIL"
+
+// brain: minimal escape pass for the user-email value before it gets
+// interpolated into the inline `<script>` body. The email comes from
+// the user's own `.env` so it's not adversarial input, but a stray
+// `</script>` (malformed entry) or `\` would break the script tag
+// boundary. Escaping `<`, `>`, `\`, and `"` keeps the inline-script
+// stream parseable. Symmetric with how stock Quartz escapes inline
+// JSON in its `description.ts` transformer.
+function escapeForJsString(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/\r/g, "\\r")
+    .replace(/\n/g, "\\n")
+}
+
+// brain-extension: the transformer plugin itself. Empty options
+// shape — the only knobs would be the script path and the env var
+// name, both of which are part of the contract documented above.
+// Keeping the signature `(opts?: never)` documents that no
+// configuration is expected; if a knob is genuinely needed later
+// (e.g. a per-vault user-allowlist override), widen the type at that
+// point rather than guessing now.
+export const EmailThreadReader: QuartzTransformerPlugin = (_opts?: never) => {
+  return {
+    name: "EmailThreadReader",
+    externalResources() {
+      // brain: read the env var fresh per build. `.trim()` so a
+      // trailing newline from a `.env` quirk doesn't bleed into the
+      // JS global.
+      const rawEmail = (process.env[USER_EMAIL_ENV_VAR] ?? "").trim()
+      const escapedEmail = escapeForJsString(rawEmail)
+
+      // brain: emit two JS resources:
+      //
+      //   1. inline — sets `window.BRAIN_USER_EMAIL` BEFORE the runtime
+      //      script reads it. `loadTime: "beforeDOMReady"` ensures the
+      //      global is in place before the runtime's
+      //      `DOMContentLoaded` listener fires. Always emitted (even
+      //      when the env var is unset) so the runtime always sees
+      //      `window.BRAIN_USER_EMAIL` defined as `""` rather than
+      //      `undefined` — simpler null handling on the runtime side.
+      //
+      //   2. external — the runtime itself, served from
+      //      `/static/emailThread.js`. `loadTime: "afterDOMReady"`
+      //      because the runtime walks the article DOM at boot, and
+      //      `afterDOMReady` guarantees the article is in place.
+      //
+      // `spaPreserve` left unset on both — Quartz's SPA reuses the
+      // existing `<script>` between navigations only when set; we want
+      // both scripts to re-run on each `nav` event so the runtime can
+      // re-detect the page and re-inject the toggle.
+      return {
+        js: [
+          {
+            loadTime: "beforeDOMReady",
+            contentType: "inline",
+            script: `;window.BRAIN_USER_EMAIL = "${escapedEmail}";`,
+          },
+          {
+            loadTime: "afterDOMReady",
+            contentType: "external",
+            src: SCRIPT_SRC,
+          },
+        ],
+      }
+    },
+  }
+}

brain/quartz_overrides/quartz/plugins/transformers/emptyDoorFilter.ts

@@ -0,0 +1,213 @@
+// Brain hide-if-empty door filter — Phase 4.1 of the Wiki UX Overhaul.
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/plugins/transformers/emptyDoorFilter.ts` by
+// `brain vault render --overlay`. It does NOT compile or run from the
+// brain repo itself; the imports below resolve against the
+// dependencies Quartz pulls into the cloned workspace via `npm
+// install`.
+//
+// What this transformer does, and why: the home note (`index.md`) ships
+// a hand-curated set of "doors" — folder-style links like
+// `[Daily notes](daily/)` that take the user into a top-level subdir
+// of the vault. When the destination subdir is empty, the door
+// resolves to a 404. The fix has two layers:
+//
+//   1. A brain CLI step that auto-generates `<subdir>/index.md` when
+//      the subdir has notes (see `src/brain/vault/daily_index.py` for
+//      the daily case). When the subdir is non-empty the door
+//      resolves cleanly.
+//
+//   2. This transformer. When the subdir is empty (no `*.md` files
+//      other than a stale `index.md` itself), strip the door's
+//      enclosing `<li>` from the rendered HTML so the user never
+//      sees a link to a 404. Generic — a single `folders` option
+//      controls which subdirs to check, so a future "Workbench"
+//      door (or any other future top-level subdir) gets the same
+//      treatment by appending its name to the option.
+//
+// Restricted to the home page by default (`pageSlugs: ["index"]`) —
+// stripping random `<li>`s on every page would be too aggressive.
+// The brief case is the home navigation; if a future PR needs the
+// behaviour elsewhere, extend the option.
+//
+// Tested against Quartz v4.5.x (April 2026). The rehype tree shape
+// (hast `Element` with `tagName` / `properties` / `children`) is
+// stable across versions; the `Plugin.CrawlLinks` integration this
+// depends on (resolving folder refs to relative URLs) has been
+// in place since v4.0.
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+import type { Element, Root, RootContent } from "hast"
+
+import { QuartzTransformerPlugin } from "../types"
+
+export interface EmptyDoorFilterOptions {
+  // brain: list of folder names (relative to the vault root) to check
+  // for emptiness. The transformer compares each link's resolved href
+  // against this list and strips the enclosing `<li>` if the folder
+  // has zero matchable `.md` files. `daily` is the only case that
+  // motivated this transformer; future top-level subdirs (e.g. a
+  // hypothetical `workbench/`) get the same treatment by appending
+  // their name here.
+  folders: string[]
+  // brain: page slugs the transformer fires on. Default `["index"]`
+  // — the home note. Restricting prevents accidentally stripping
+  // legitimate navigation `<li>`s from other pages.
+  pageSlugs: string[]
+}
+
+const defaultOptions: EmptyDoorFilterOptions = {
+  folders: ["daily"],
+  pageSlugs: ["index"],
+}
+
+// brain: a folder counts as "non-empty" if it contains at least one
+// markdown file whose name is NOT `index.md`. The `index.md` exclusion
+// stops a stale auto-generated index from masking an otherwise-empty
+// folder. Recursive walk so a year-folded ``daily/<YYYY>/<note>.md``
+// layout is handled (the brain CLI nests dailies under year folders).
+function folderHasNotes(folderPath: string): boolean {
+  if (!fs.existsSync(folderPath)) return false
+  let stack: string[] = [folderPath]
+  while (stack.length > 0) {
+    const dir = stack.pop()
+    if (dir === undefined) break
+    let entries: fs.Dirent[]
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      // Permission errors / race deletes — treat as empty for the
+      // affected subtree rather than crashing the build.
+      continue
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        stack.push(full)
+        continue
+      }
+      if (!entry.isFile()) continue
+      if (!entry.name.endsWith(".md")) continue
+      if (entry.name === "index.md") continue
+      return true
+    }
+  }
+  return false
+}
+
+// brain: tolerant href→folder match. `Plugin.CrawlLinks` rewrites
+// internal links to relative URLs; the home note's `daily/` link
+// might resolve to `./daily/`, `daily/`, or `daily/index` depending
+// on `markdownLinkResolution`. We strip a leading `./`, drop a
+// trailing `/`, and trim a trailing `/index` so the comparator
+// against the bare folder name catches every shape.
+function hrefMatchesFolder(href: string, emptyFolders: Set<string>): boolean {
+  if (href.length === 0) return false
+  // Skip absolute / external URLs cheaply — folder refs are always
+  // relative.
+  if (/^[a-z]+:/i.test(href)) return false
+  let cleaned = href.split("#")[0]
+  cleaned = cleaned.replace(/^\.\//, "")
+  cleaned = cleaned.replace(/\/$/, "")
+  cleaned = cleaned.replace(/\/index$/, "")
+  // Folder name is the last path segment for nested doors (none today,
+  // but a future `tools/scratch/` would need this).
+  return emptyFolders.has(cleaned)
+}
+
+// brain: walks an `<li>` subtree to determine if any descendant `<a>`
+// points at one of the empty folders. Hast doesn't ship a visitor
+// helper this targeted (`hast-util-visit` would work but adds an
+// import for what's a 12-line walk), so we recurse manually.
+function listItemPointsAtEmptyFolder(
+  li: Element,
+  emptyFolders: Set<string>,
+): boolean {
+  const stack: RootContent[] = [...li.children]
+  while (stack.length > 0) {
+    const node = stack.pop()
+    if (node === undefined) break
+    if (node.type !== "element") continue
+    const el = node as Element
+    if (el.tagName === "a") {
+      const href = (el.properties ?? {})["href"]
+      if (typeof href === "string" && hrefMatchesFolder(href, emptyFolders)) {
+        return true
+      }
+    }
+    if (Array.isArray(el.children)) {
+      for (const child of el.children) {
+        stack.push(child)
+      }
+    }
+  }
+  return false
+}
+
+// brain: in-place tree edit — splice every `<li>` that points at an
+// empty folder. Walks recursively so a `<li>` nested inside a `<ul>`
+// inside a `<details>` (or any wrapper) is still reachable. We mutate
+// `node.children` to a filtered list; preact reconciles fine with
+// hast tree mutation since rehype-stringify reads the final shape
+// after every transformer plugin runs.
+function stripEmptyDoorListItems(
+  tree: Root | Element,
+  emptyFolders: Set<string>,
+): void {
+  const children = tree.children
+  if (!Array.isArray(children)) return
+  const filtered: typeof children = []
+  for (const child of children) {
+    if (child.type === "element") {
+      const el = child as Element
+      if (el.tagName === "li" && listItemPointsAtEmptyFolder(el, emptyFolders)) {
+        // Drop the entire `<li>` — including any nested children we
+        // would otherwise have recursed into. The whole door (link +
+        // surrounding context — emoji, em-dash subtitle, etc.) is
+        // expected to live inside the same `<li>`, which matches the
+        // home note's authored shape (`- 📅 [Daily notes](daily/) — …`).
+        continue
+      }
+      stripEmptyDoorListItems(el, emptyFolders)
+    }
+    filtered.push(child)
+  }
+  tree.children = filtered as typeof tree.children
+}
+
+export const EmptyDoorFilter: QuartzTransformerPlugin<
+  Partial<EmptyDoorFilterOptions>
+> = (userOpts) => {
+  const opts: EmptyDoorFilterOptions = { ...defaultOptions, ...userOpts }
+  return {
+    name: "EmptyDoorFilter",
+    htmlPlugins(ctx) {
+      // brain: cache empty-folder set per build. The vault filesystem
+      // is read once per `htmlPlugins` invocation (Quartz calls it once
+      // per build); rendering 1000+ pages doesn't re-stat the same
+      // dirs. The `Set` is the comparator the per-page walker hits.
+      const vaultRoot = ctx.argv.directory
+      const emptyFolders = new Set<string>()
+      for (const folder of opts.folders) {
+        if (!folderHasNotes(path.join(vaultRoot, folder))) {
+          emptyFolders.add(folder)
+        }
+      }
+      const pageSlugSet = new Set(opts.pageSlugs)
+      return [
+        () => async (tree: Root, file) => {
+          // brain: short-circuit when nothing's empty — the vast
+          // majority of builds will land here, since the home note's
+          // doors point at populated dirs.
+          if (emptyFolders.size === 0) return
+          const slug = (file.data as { slug?: string }).slug
+          if (typeof slug !== "string" || !pageSlugSet.has(slug)) return
+          stripEmptyDoorListItems(tree, emptyFolders)
+        },
+      ]
+    },
+  }
+}