@carlesandres/house 0.4.0 → 0.4.1

package/src/Footer.tsx

@@ -71,30 +71,40 @@ const displayKey = (raw: string): string => {
 	}
 }
 
-const formatHint = <C,>(b: KeyBinding<C>): string | null => {
+/** Hint row entries. `key === null` is a standalone chip (e.g. the filter
+ *  chip) and renders as muted text without the key/label split. */
+interface Hint {
+	readonly key: string | null
+	readonly label: string
+}
+
+const hintWidth = (h: Hint): number =>
+	h.key === null ? h.label.length : h.key.length + 1 + h.label.length // key + " " + label
+
+const formatHint = <C,>(b: KeyBinding<C>): Hint | null => {
 	if (!b.hint) return null
 	const first = b.keys[0]
 	if (!first) return null
-	return `${displayKey(first)}:${b.hint}`
+	return { key: displayKey(first), label: b.hint }
 }
 
-/** Drop hints from the end until the joined string fits within `width`.
- *  If not even the first hint fits, fall back to the bare key portion so
- *  the user still sees a discoverability anchor (e.g. `?` instead of an
- *  empty row on an 8-column terminal). */
-const fitHints = (hints: readonly string[], width: number): string => {
-	if (width <= 0 || hints.length === 0) return ""
-	let acc = ""
+/** Drop hints from the end until they fit within `width`. If not even the
+ *  first hint fits, fall back to the bare key (or label chip) truncated to
+ *  width, so the row is never silently blank on tight viewports. */
+const fitHints = (hints: readonly Hint[], width: number): Hint[] => {
+	if (width <= 0 || hints.length === 0) return []
+	const acc: Hint[] = []
+	let used = 0
 	for (const h of hints) {
-		const next = acc.length === 0 ? h : `${acc}${HINT_SEPARATOR}${h}`
-		if (next.length > width) break
-		acc = next
+		const add = acc.length === 0 ? hintWidth(h) : HINT_SEPARATOR.length + hintWidth(h)
+		if (used + add > width) break
+		acc.push(h)
+		used += add
 	}
 	if (acc.length > 0) return acc
-	// Nothing fit. Render just the first hint's key (everything before `:`)
-	// truncated to width, so the row is never silently blank.
-	const firstKey = hints[0]!.split(":")[0] ?? ""
-	return firstKey.slice(0, width)
+	const first = hints[0]!
+	if (first.key === null) return [{ key: null, label: first.label.slice(0, width) }]
+	return [{ key: first.key.slice(0, width), label: "" }]
 }
 
 const STATUS_SEPARATOR = " · "
@@ -116,16 +126,16 @@ export const Footer = <C,>({
 		flexDirection: "row",
 		paddingLeft: 1,
 		paddingRight: 1,
-		backgroundColor: colors.background,
+		backgroundColor: colors.surface,
 	} as const
 
-	const hints: string[] = []
+	const hints: Hint[] = []
 	// The filter chip prepends to the hint row when a filter is applied and the
 	// input is closed. Bracketed to avoid looking like a `key:hint` binding —
 	// "filter" is not a key. Surfaces the otherwise-invisible invariant that
 	// `[`/`]` walks the filtered set. See DESIGN.md §7.1 Q1.
 	if (filterQuery && filterQuery.length > 0) {
-		hints.push(`[filter: ${filterQuery}]`)
+		hints.push({ key: null, label: `[filter: ${filterQuery}]` })
 	}
 	for (const b of bindings) {
 		if (b.when && !b.when(ctx)) continue
@@ -139,7 +149,7 @@ export const Footer = <C,>({
 	const status = discoveryStatus && discoveryStatus.length > 0 ? discoveryStatus : null
 	const statusBudget = status ? Math.min(status.length + STATUS_SEPARATOR.length, usableWidth) : 0
 	const hintsWidth = Math.max(0, usableWidth - statusBudget)
-	const hintContent = fitHints(hints, hintsWidth)
+	const visibleHints = fitHints(hints, hintsWidth)
 	const statusContent = status
 		? status.slice(0, Math.max(0, statusBudget - STATUS_SEPARATOR.length))
 		: ""
@@ -150,6 +160,40 @@ export const Footer = <C,>({
 			: notice
 		: null
 
+	// Two-tone hint row: keys render in `text` (foreground-strength), the
+	// `:label` portion in `textMuted`. Matches ghui's footer treatment so
+	// the key — the actionable token — visually leads each hint.
+	const renderHints = () =>
+		visibleHints.flatMap((h, i) => {
+			const sep =
+				i > 0
+					? [
+							<text
+								key={`s${i}`}
+								content={HINT_SEPARATOR}
+								wrapMode="none"
+								style={{ fg: colors.textMuted }}
+							/>,
+						]
+					: []
+			if (h.key === null) {
+				return [
+					...sep,
+					<text key={`l${i}`} content={h.label} wrapMode="none" style={{ fg: colors.textMuted }} />,
+				]
+			}
+			return [
+				...sep,
+				<text key={`k${i}`} content={h.key} wrapMode="none" style={{ fg: colors.text }} />,
+				<text
+					key={`l${i}`}
+					content={` ${h.label}`}
+					wrapMode="none"
+					style={{ fg: colors.textMuted }}
+				/>,
+			]
+		})
+
 	// Priority: notice > (status + hints). Notice fg is strong; status sits
 	// at the muted level so it reads as ambient state, not an event.
 	if (noticeContent !== null) {
@@ -165,14 +209,10 @@ export const Footer = <C,>({
 			<box style={rowStyle}>
 				<text content={statusContent} wrapMode="none" style={{ fg: colors.textMuted }} />
 				<text content={STATUS_SEPARATOR} wrapMode="none" style={{ fg: colors.textMuted }} />
-				<text content={hintContent} wrapMode="none" style={{ fg: colors.textMuted }} />
+				{renderHints()}
 			</box>
 		)
 	}
 
-	return (
-		<box style={rowStyle}>
-			<text content={hintContent} wrapMode="none" style={{ fg: colors.textMuted }} />
-		</box>
-	)
+	return <box style={rowStyle}>{renderHints()}</box>
 }

package/src/Header.tsx

@@ -0,0 +1,68 @@
+/**
+ * Header — single-row chrome above the two-pane area.
+ *
+ * Borderless single line modeled on ghui's PlainLine header: brand and
+ * current filename on the left, version on the right. The row is
+ * informational, not interactive — see issue #38 for the design discussion.
+ *
+ * Width degrades gracefully: the version drops first when the row gets
+ * tight, then the filename, leaving the brand mark as the irreducible
+ * identity element. Always rendered — the row is worth one cell on any
+ * viewport so the user never loses the filename indicator (notably, when
+ * the sidebar drawer overlays the reader on narrow viewports).
+ */
+
+import pkg from "../package.json" with { type: "json" }
+import { BRAND, BRAND_NAME } from "./brand.ts"
+import { colors } from "./theme/colors.ts"
+
+export const HEADER_HEIGHT = 1
+
+const FILE_SEPARATOR = " · "
+
+export interface HeaderProps {
+	readonly width: number
+	/** Currently selected file's relative path. When set, the Header shows
+	 *  it next to the brand mark — replaces the per-pane border title that
+	 *  used to carry this information. */
+	readonly currentFile?: string | null
+	/** Optional override for the version string (testing). Defaults to
+	 *  the running package's version. */
+	readonly version?: string
+}
+
+export const Header = ({ width, currentFile, version = pkg.version }: HeaderProps) => {
+	const brand = `${BRAND} ${BRAND_NAME}`
+	const right = `v${version}`
+	const file = currentFile && currentFile.length > 0 ? currentFile : null
+	const usableWidth = Math.max(0, width - 2) // 1-cell horizontal padding each side
+
+	// Priority: brand > filename > version. Brand is the irreducible identity
+	// anchor. Filename is per-selection useful info — keep it before the
+	// largely-static version string. `1` is the minimum gap between left and
+	// right groups so they never visually collide.
+	const leftWithFile = file !== null ? `${brand}${FILE_SEPARATOR}${file}` : brand
+	const showFileWithVersion = leftWithFile.length + 1 + right.length <= usableWidth
+	const showFileWithoutVersion = leftWithFile.length <= usableWidth
+	const showFile = file !== null && (showFileWithVersion || showFileWithoutVersion)
+	const left = showFile ? leftWithFile : brand
+	const showRight = left.length + 1 + right.length <= usableWidth
+
+	return (
+		<box
+			style={{
+				width,
+				height: HEADER_HEIGHT,
+				flexShrink: 0,
+				flexDirection: "row",
+				justifyContent: "space-between",
+				paddingLeft: 1,
+				paddingRight: 1,
+				backgroundColor: colors.surface,
+			}}
+		>
+			<text content={left} wrapMode="none" style={{ fg: colors.text }} />
+			{showRight && <text content={right} wrapMode="none" style={{ fg: colors.text }} />}
+		</box>
+	)
+}

package/src/HelpOverlay.tsx

@@ -6,9 +6,13 @@
  * keys — the dispatcher and the help text are the same source of truth.
  */
 
+import { RGBA } from "@opentui/core"
 import type { KeyBinding } from "./keymap/keymap.ts"
 import { colors } from "./theme/colors.ts"
 
+// See CommandPalette.tsx for the scrim rationale.
+const SCRIM = RGBA.fromInts(0, 0, 0, 150)
+
 export interface HelpOverlayProps<C> {
 	readonly bindings: readonly KeyBinding<C>[]
 	readonly viewportWidth: number
@@ -82,49 +86,63 @@ export const HelpOverlay = <C,>({
 	return (
 		<box
 			position="absolute"
-			left={left}
-			top={top}
-			width={overlayWidth}
-			height={overlayHeight}
+			left={0}
+			top={0}
+			width={viewportWidth}
+			height={viewportHeight}
 			zIndex={10}
-			title=" Help "
-			titleAlignment="left"
-			style={{
-				border: true,
-				borderColor: colors.borderActive,
-				padding: 1,
-				flexDirection: "column",
-				backgroundColor: colors.surface,
-			}}
+			style={{ backgroundColor: SCRIM }}
 		>
-			{rows.map((row) => {
-				switch (row.kind) {
-					case "header":
-						return (
-							<text
-								key={row.key}
-								wrapMode="none"
-								content={row.text}
-								style={{ fg: colors.borderActive, attributes: 1 /* bold */ }}
-							/>
-						)
-					case "footer":
-						return (
-							<text
-								key={row.key}
-								wrapMode="none"
-								content={row.text}
-								style={{ fg: colors.textMuted }}
-							/>
-						)
-					case "spacer":
-						return <text key={row.key} content=" " />
-					case "binding":
-						return (
-							<text key={row.key} wrapMode="none" content={row.text} style={{ fg: colors.text }} />
-						)
-				}
-			})}
+			<box
+				position="absolute"
+				left={left}
+				top={top}
+				width={overlayWidth}
+				height={overlayHeight}
+				title=" Help "
+				titleAlignment="left"
+				style={{
+					border: true,
+					borderColor: colors.textMuted,
+					padding: 1,
+					flexDirection: "column",
+					backgroundColor: colors.surface,
+				}}
+			>
+				{rows.map((row) => {
+					switch (row.kind) {
+						case "header":
+							return (
+								<text
+									key={row.key}
+									wrapMode="none"
+									content={row.text}
+									style={{ fg: colors.borderActive, attributes: 1 /* bold */ }}
+								/>
+							)
+						case "footer":
+							return (
+								<text
+									key={row.key}
+									wrapMode="none"
+									content={row.text}
+									style={{ fg: colors.textMuted }}
+								/>
+							)
+						case "spacer":
+							return <text key={row.key} content=" " />
+						case "binding":
+							return (
+								<text
+									key={row.key}
+									wrapMode="none"
+									content={row.text}
+									style={{ fg: colors.text }}
+								/>
+							)
+					}
+				})}
+			</box>
 		</box>
 	)
 }

package/src/brand.ts

@@ -0,0 +1,7 @@
+/**
+ * Brand mark. U+2302 HOUSE is a single-cell glyph in every monospace font
+ * we care about; falls back to a tofu box on rare fonts that lack it.
+ * Single import point so future placements (#76) stay in sync.
+ */
+export const BRAND = "⌂"
+export const BRAND_NAME = "house"

package/src/cli/argv.ts

@@ -25,6 +25,12 @@ export interface ParsedArgs {
 	readonly configPath: boolean
 	/** Value of `--sidebar <mode>` (`auto`, `on`, `off`), or null. Validated by the boot layer. */
 	readonly sidebar: string | null
+	/** True when `--no-update-check` was passed: suppress the npm-registry
+	 *  probe and the "update available" notice. Mirrors the
+	 *  `NO_UPDATE_NOTIFIER` env var so opt-out is reachable without env state. */
+	readonly noUpdateCheck: boolean
+	/** True when `--no-mdx` was passed: exclude `.mdx` files from discovery. */
+	readonly noMdx: boolean
 }
 
 /**
@@ -47,6 +53,8 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 	let version = false
 	let configPath = false
 	let sidebar: string | null = null
+	let noUpdateCheck = false
+	let noMdx = false
 
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i]!
@@ -99,13 +107,34 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 				}
 				continue
 			}
+			case "--no-update-check":
+				noUpdateCheck = true
+				continue
+			case "--no-mdx":
+				noMdx = true
+				continue
 		}
 		if (path === null && !arg.startsWith("-")) {
 			path = arg
 		}
 	}
 
-	return { path, theme, tone, width, all, sort, serve, port, help, version, configPath, sidebar }
+	return {
+		path,
+		theme,
+		tone,
+		width,
+		all,
+		sort,
+		serve,
+		port,
+		help,
+		version,
+		configPath,
+		sidebar,
+		noUpdateCheck,
+		noMdx,
+	}
 }
 
 const themeList = themeDefinitions.map((t) => t.id).join(", ")
@@ -126,9 +155,11 @@ options:
   -h, --help     show this help and exit
   -v, --version  print version and exit
   --config-path  print path to the config file and exit
+  --no-update-check  suppress the "newer version available" check (also via NO_UPDATE_NOTIFIER=1)
+  --no-mdx       exclude .mdx files from discovery (default: included)
 
 configuration:
   file: $XDG_CONFIG_HOME/house/config.toml  (default ~/.config/house/config.toml)
-  keys: theme, tone
-  env:  HOUSE_THEME, HOUSE_TONE
+  keys: theme, tone, mdx
+  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_MDX
   precedence (high → low): flags → env → file → defaults`

package/src/config/load.ts

@@ -18,39 +18,96 @@ import { themeDefinitions } from "../theme/registry.ts"
 export interface HouseConfig {
 	readonly theme: string
 	readonly tone: "dark" | "light"
+	readonly mdx: boolean
 }
 
 export interface CliOverrides {
 	readonly theme: string | null
 	readonly tone: string | null
+	readonly mdx: boolean | null
 }
 
 const DEFAULT_THEME = "opencode"
 const DEFAULT_TONE: "dark" | "light" = "dark"
+const DEFAULT_MDX = true
 
 const themeIds = themeDefinitions.map((t) => t.id)
 
 /**
  * Top-level keys the config file is allowed to set. Kept in sync by hand
  * with `schema` below — when adding a key, add it both places.
- * Used by `fileProvider` to reject typo'd keys (e.g. `them = "..."`) loudly
- * rather than silently falling back to defaults.
+ * Used by `fileProvider` to warn about unrecognized keys (with a
+ * did-you-mean hint when one is close) while still loading the rest.
  */
-const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set(["theme", "tone"])
+const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set(["theme", "tone", "mdx"])
 
 const schema = Config.all({
 	theme: Config.schema(Schema.Literals(themeIds), "theme"),
 	tone: Config.schema(Schema.Literals(["dark", "light"] as const), "tone"),
+	// Boolean stored as string literal because providers stringify values
+	// (TOML bools, env vars, CLI flags all flow through as text). Mapped to
+	// a real boolean in `loadConfig` below.
+	mdx: Config.schema(Schema.Literals(["true", "false"] as const), "mdx"),
 })
 
 const defaultsProvider = (): ConfigProvider.ConfigProvider =>
-	ConfigProvider.fromUnknown({ theme: DEFAULT_THEME, tone: DEFAULT_TONE })
+	ConfigProvider.fromUnknown({
+		theme: DEFAULT_THEME,
+		tone: DEFAULT_TONE,
+		mdx: String(DEFAULT_MDX),
+	})
+
+/**
+ * Levenshtein edit distance, capped at `cap` for early exit.
+ * Used only to suggest "did you mean X?" when a config key looks like a
+ * typo of a known one. Tiny inputs (≤ ~20 chars), so the naive O(n·m)
+ * fill is fine.
+ */
+const editDistance = (a: string, b: string, cap: number): number => {
+	if (Math.abs(a.length - b.length) > cap) return cap + 1
+	const prev: number[] = Array.from({ length: b.length + 1 })
+	const curr: number[] = Array.from({ length: b.length + 1 })
+	for (let j = 0; j <= b.length; j++) prev[j] = j
+	for (let i = 1; i <= a.length; i++) {
+		curr[0] = i
+		let rowMin = curr[0]!
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1
+			curr[j] = Math.min(prev[j]! + 1, curr[j - 1]! + 1, prev[j - 1]! + cost)
+			if (curr[j]! < rowMin) rowMin = curr[j]!
+		}
+		if (rowMin > cap) return cap + 1
+		for (let j = 0; j <= b.length; j++) prev[j] = curr[j]!
+	}
+	return prev[b.length]!
+}
+
+const suggestKey = (unknown: string, known: readonly string[]): string | null => {
+	let best: { key: string; dist: number } | null = null
+	for (const k of known) {
+		const d = editDistance(unknown, k, 2)
+		if (d <= 2 && (best === null || d < best.dist)) best = { key: k, dist: d }
+	}
+	return best?.key ?? null
+}
+
+const formatUnknownKeyWarning = (path: string, key: string, known: readonly string[]): string => {
+	const suggestion = suggestKey(key, known)
+	const hint = suggestion ? ` — did you mean "${suggestion}"?` : ""
+	return `house: ignoring unknown key "${key}" in ${path}${hint}`
+}
 
 /**
  * Reads a TOML file at `path`. Missing file → `undefined` for every key
- * (per-key fallthrough). Malformed TOML → `SourceError` (hard fail upstream).
+ * (per-key fallthrough). Malformed TOML → `SourceError` (hard fail
+ * upstream). Unknown top-level keys are warned about via `onWarning` and
+ * dropped — this preserves forward-compat with newer config schemas while
+ * still flagging typos like `them = "..."`.
  */
-const fileProvider = (path: string): ConfigProvider.ConfigProvider => {
+const fileProvider = (
+	path: string,
+	onWarning: (message: string) => void,
+): ConfigProvider.ConfigProvider => {
 	let cache: { data: Record<string, unknown> | null } | null = null
 	const load = Effect.gen(function* () {
 		if (cache !== null) return cache.data
@@ -69,17 +126,17 @@ const fileProvider = (path: string): ConfigProvider.ConfigProvider => {
 					cause,
 				}),
 		})
-		const unknown = Object.keys(parsed).filter((k) => !KNOWN_FILE_KEYS.has(k))
-		if (unknown.length > 0) {
-			const known = [...KNOWN_FILE_KEYS].join(", ")
-			return yield* Effect.fail(
-				new ConfigProvider.SourceError({
-					message: `unknown key${unknown.length > 1 ? "s" : ""} in ${path}: ${unknown.map((k) => `"${k}"`).join(", ")} (known: ${known})`,
-				}),
-			)
+		const known = [...KNOWN_FILE_KEYS]
+		const filtered: Record<string, unknown> = {}
+		for (const [k, v] of Object.entries(parsed)) {
+			if (KNOWN_FILE_KEYS.has(k)) {
+				filtered[k] = v
+			} else {
+				onWarning(formatUnknownKeyWarning(path, k, known))
+			}
 		}
-		cache = { data: parsed }
-		return parsed
+		cache = { data: filtered }
+		return filtered
 	})
 	return ConfigProvider.make((path) =>
 		Effect.gen(function* () {
@@ -112,8 +169,10 @@ const envProvider = (env: Record<string, string | undefined>): ConfigProvider.Co
 	const entries: Array<[string, string]> = []
 	const theme = env["HOUSE_THEME"]
 	const tone = env["HOUSE_TONE"]
+	const mdx = env["HOUSE_MDX"]
 	if (theme !== undefined) entries.push(["theme", theme])
 	if (tone !== undefined) entries.push(["tone", tone])
+	if (mdx !== undefined) entries.push(["mdx", mdx])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
 }
 
@@ -121,6 +180,7 @@ const cliProvider = (overrides: CliOverrides): ConfigProvider.ConfigProvider =>
 	const entries: Array<[string, string]> = []
 	if (overrides.theme !== null) entries.push(["theme", overrides.theme])
 	if (overrides.tone !== null) entries.push(["tone", overrides.tone])
+	if (overrides.mdx !== null) entries.push(["mdx", String(overrides.mdx)])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
 }
 
@@ -130,6 +190,8 @@ export interface LoadOptions {
 	readonly filePath?: string
 	/** Override env (tests). Defaults to `process.env`. */
 	readonly env?: Record<string, string>
+	/** Sink for non-fatal warnings (unknown keys). Defaults to stderr. */
+	readonly onWarning?: (message: string) => void
 }
 
 export const defaultConfigPath = (): string =>
@@ -156,11 +218,14 @@ export const formatConfigError = (err: unknown): string => {
 export const loadConfig = (
 	options: LoadOptions = {},
 ): Effect.Effect<HouseConfig, Config.ConfigError> => {
-	const cli = options.cli ?? { theme: null, tone: null }
+	const cli = options.cli ?? { theme: null, tone: null, mdx: null }
+	const onWarning = options.onWarning ?? ((msg) => process.stderr.write(`${msg}\n`))
 	const provider = cliProvider(cli).pipe(
 		ConfigProvider.orElse(envProvider(options.env ?? process.env)),
-		ConfigProvider.orElse(fileProvider(options.filePath ?? defaultConfigPath())),
+		ConfigProvider.orElse(fileProvider(options.filePath ?? defaultConfigPath(), onWarning)),
 		ConfigProvider.orElse(defaultsProvider()),
 	)
-	return schema.parse(provider)
+	return schema
+		.parse(provider)
+		.pipe(Effect.map((raw) => ({ theme: raw.theme, tone: raw.tone, mdx: raw.mdx === "true" })))
 }

package/src/discovery/walk.ts

@@ -19,6 +19,8 @@ export interface WalkOptions {
 	readonly all?: boolean
 	/** Group order within each directory. Default `dirs-first`. */
 	readonly sort?: SortOrder
+	/** Include `.mdx` files alongside `.md`/`.markdown`. Default `true`. */
+	readonly mdx?: boolean
 }
 
 export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
@@ -27,6 +29,7 @@ export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
 }> {}
 
 const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdx"])
+const MARKDOWN_EXTENSIONS_NO_MDX = new Set([".md", ".markdown"])
 const HARD_SKIP_DIRS = new Set(["node_modules", ".git", ".venv"])
 
 interface IgnoreLevel {
@@ -85,7 +88,7 @@ async function* walkDirGen(
 	dirPath: string,
 	rootPath: string,
 	parentLevels: readonly IgnoreLevel[],
-	opts: { all: boolean; sort: SortOrder },
+	opts: { all: boolean; sort: SortOrder; mdx: boolean },
 	signal: AbortSignal,
 ): AsyncGenerator<FileEntry, void, void> {
 	if (signal.aborted) return
@@ -119,7 +122,8 @@ async function* walkDirGen(
 
 		if (!entry.isFile()) continue
 		if (!opts.all && entry.name.startsWith(".")) continue
-		if (!MARKDOWN_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue
+		const allowed = opts.mdx ? MARKDOWN_EXTENSIONS : MARKDOWN_EXTENSIONS_NO_MDX
+		if (!allowed.has(extname(entry.name).toLowerCase())) continue
 		if (!opts.all && isIgnored(entryPath, false, levels)) continue
 
 		yield {
@@ -137,7 +141,7 @@ async function* walkDirGen(
  * at its next `signal.aborted` check.
  *
  * Rules (see DESIGN.md §6):
- * - Extensions: `.md`, `.markdown`, `.mdx`.
+ * - Extensions: `.md`, `.markdown`, and `.mdx` (unless `mdx: false`).
  * - Hard skips (always): `node_modules`, `.git`, `.venv`.
  * - Hidden files/dirs (leading `.`) skipped unless `all: true`.
  * - `.gitignore` honored, including nested `.gitignore` files.
@@ -153,6 +157,7 @@ export const walk = (
 	const opts = {
 		all: options.all ?? false,
 		sort: options.sort ?? ("dirs-first" as SortOrder),
+		mdx: options.mdx ?? true,
 	}
 	const controller = new AbortController()
 	const iterable: AsyncIterable<FileEntry> = {