@carlesandres/house 0.4.0 → 0.4.2

package/src/keymap/browser.ts

@@ -10,11 +10,19 @@ export type BrowserFocus = "sidebar" | "reader"
 
 export interface BrowserCtx {
 	readonly files: readonly FileEntry[]
+	/** True iff `files[selectedIndex]` resolves to an entry. The honest
+	 *  predicate for File-group actions (`o`, `e`, `[`, `]`): with debounced
+	 *  filter and sticky auto-select, `files.length > 0` can be true while
+	 *  `selectedIndex` is invalid for the displayed list. See #115. */
+	readonly hasSelected: boolean
 	readonly focus: BrowserFocus
 	/** User's sticky sidebar preference. Visibility is `shown || focus==="sidebar"`. */
 	readonly sidebarShown: boolean
 	readonly helpVisible: boolean
 	readonly filterOpen: boolean
+	/** Current applied/edited filter query. Used by `filter.clearOrOpen`'s
+	 *  hint gate so the hint only appears when there is something to clear. */
+	readonly filterQuery: string
 	readonly paletteOpen: boolean
 	readonly setFocus: (next: BrowserFocus | ((prev: BrowserFocus) => BrowserFocus)) => void
 	readonly setSelectedIndex: (updater: (prev: number) => number) => void
@@ -22,12 +30,19 @@ export interface BrowserCtx {
 	readonly toggleShown: () => void
 	readonly setHelpVisible: (updater: (prev: boolean) => boolean) => void
 	readonly openFilter: () => void
+	/** Clear the current filter query and open the filter modal in a single
+	 *  action. Bound to `\` so users can reset a stranded zero-match filter
+	 *  without first reopening with `/` and backspacing. */
+	readonly clearAndOpenFilter: () => void
 	readonly openPalette: () => void
 	readonly cycleTheme: (delta: 1 | -1) => void
 	readonly toggleTone: () => void
 	readonly quit: () => void
 	/** Start (or retarget) the HTML preview server on the focused file. */
 	readonly serveCurrent: () => void
+	/** Suspend the TUI, hand the TTY to `$EDITOR`, resume and re-read on
+	 *  exit. No-op when nothing is selected; gating is the binding's job. */
+	readonly editCurrent: () => void
 }
 
 /** Step size for shift+j/k and the space/b/page keys. Constant for v1; could
@@ -37,6 +52,7 @@ const JUMP = 8
 const clamp = (n: number, min: number, max: number) => Math.max(min, Math.min(max, n))
 const lastIndex = (c: BrowserCtx) => Math.max(0, c.files.length - 1)
 const haveFiles = (c: BrowserCtx) => c.files.length > 0
+const hasSelected = (c: BrowserCtx) => c.hasSelected
 const stepBy = (c: BrowserCtx, delta: number) =>
 	c.setSelectedIndex((i) => clamp(i + delta, 0, lastIndex(c)))
 
@@ -45,7 +61,10 @@ const filterClosed = (c: BrowserCtx) => !c.filterOpen
 const paletteClosed = (c: BrowserCtx) => !c.paletteOpen
 const inReader = (c: BrowserCtx) => c.focus === "reader"
 const inSidebarWithFiles = (c: BrowserCtx) => inSidebar(c) && haveFiles(c)
-const inReaderWithFiles = (c: BrowserCtx) => inReader(c) && haveFiles(c)
+/** Reader-only sibling-step gate: needs a current selection plus a sibling
+ *  to step to. `hasSelected` implies `files.length >= 1`, so `>= 2` is the
+ *  meaningful extra condition. */
+const inReaderWithSibling = (c: BrowserCtx) => inReader(c) && hasSelected(c) && c.files.length >= 2
 
 export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 	// Global
@@ -93,6 +112,28 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		when: filterClosed,
 		run: (c) => c.openFilter(),
 	},
+	{
+		id: "filter.clearOrOpen",
+		group: "Sidebar",
+		description: "Clear filter",
+		hint: "clear",
+		keys: ["ctrl+\\"],
+		// Fires from anywhere outside the filter modal via the keymap.
+		// Inside the filter modal it's intercepted directly in Browser.tsx
+		// (the filter mode owns key handling), but the action is the same —
+		// clear input, keep modal open. Palette/help branches short-circuit
+		// dispatch in Browser.tsx, so we don't need to gate on them for
+		// behavior; the `hintWhen` gate keeps the footer chip from showing
+		// when there's nothing to clear or when a modal owns the input.
+		// Chord chosen over single `\` so the binding works inside the
+		// filter input without colliding with the typed character; ctrl+u
+		// is deliberately left to its reader/sidebar half-page-up role to
+		// avoid overload.
+		when: filterClosed,
+		hintWhen: (c) =>
+			filterClosed(c) && !c.paletteOpen && !c.helpVisible && c.filterQuery.length > 0,
+		run: (c) => c.clearAndOpenFilter(),
+	},
 	{
 		id: "palette.open",
 		group: "Global",
@@ -106,15 +147,6 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		when: paletteClosed,
 		run: (c) => c.openPalette(),
 	},
-	{
-		id: "serve.current",
-		group: "Global",
-		description: "Open current file in browser as HTML",
-		hint: "html",
-		keys: ["o"],
-		when: haveFiles,
-		run: (c) => c.serveCurrent(),
-	},
 	{
 		id: "theme.next",
 		group: "Global",
@@ -213,32 +245,57 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		run: (c) => c.setFocus("reader"),
 	},
 
-	// Reader
+	// File — actions on the currently-selected file. Gated on `hasSelected`
+	// (per #115) so they're available exactly when the reader has something
+	// to act on, regardless of focus or filter state.
 	{
-		id: "reader.back",
-		group: "Reader",
-		description: "Back to sidebar",
-		hint: "back",
-		keys: ["escape", "left", "h"],
-		when: inReader,
-		run: (c) => c.setFocus("sidebar"),
+		id: "serve.current",
+		group: "File",
+		description: "Open current file in browser as HTML",
+		hint: "html",
+		keys: ["o"],
+		when: hasSelected,
+		run: (c) => c.serveCurrent(),
 	},
 	{
+		id: "file.edit",
+		group: "File",
+		description: "Open current file in $EDITOR",
+		hint: "edit",
+		keys: ["e"],
+		when: hasSelected,
+		run: (c) => c.editCurrent(),
+	},
+	{
+		// `[`/`]` keep the `inReader` clause so they're only typed from the
+		// reader (sidebar uses j/k for stepping). The File-group predicate is
+		// additive: needs a selection *and* a sibling to step to.
 		id: "reader.prevFile",
-		group: "Reader",
+		group: "File",
 		description: "Prev file",
 		hint: "prev",
 		keys: ["["],
-		when: inReaderWithFiles,
+		when: inReaderWithSibling,
 		run: (c) => stepBy(c, -1),
 	},
 	{
 		id: "reader.nextFile",
-		group: "Reader",
+		group: "File",
 		description: "Next file",
 		hint: "next",
 		keys: ["]"],
-		when: inReaderWithFiles,
+		when: inReaderWithSibling,
 		run: (c) => stepBy(c, 1),
 	},
+
+	// Reader
+	{
+		id: "reader.back",
+		group: "Reader",
+		description: "Back to sidebar",
+		hint: "back",
+		keys: ["escape", "left", "h"],
+		when: inReader,
+		run: (c) => c.setFocus("sidebar"),
+	},
 ]

package/src/keymap/keymap.ts

@@ -34,6 +34,12 @@ export interface KeyBinding<C> {
 	readonly hint?: string
 	/** If present, the binding only fires when this returns true. */
 	readonly when?: (ctx: C) => boolean
+	/** If present, the footer hint is shown only when this returns true. When
+	 *  absent, hint visibility falls back to `when`. Use when a binding's
+	 *  dispatch gate is broader than the situations where the hint is useful
+	 *  (e.g. "clear filter" fires from anywhere but only deserves a hint when
+	 *  there is actually a filter to clear). */
+	readonly hintWhen?: (ctx: C) => boolean
 	readonly run: (ctx: C) => void
 }
 

package/src/layout/resolve.ts

@@ -18,8 +18,6 @@ export const SIDEBAR_MAX_WIDTH = 60
 export const READER_MIN_WIDTH = 40
 /** Column gap painted between the two panes when both are inline. */
 export const DIVIDER_WIDTH = 1
-/** Launch-bucket threshold for `--sidebar=auto`. < this → start hidden. */
-export const TIGHT_VIEWPORT_THRESHOLD = 80
 
 /**
  * Continuous clamp. `preferred` is the user's desired width (until #13 lands,
@@ -28,7 +26,7 @@ export const TIGHT_VIEWPORT_THRESHOLD = 80
  *
  * Result is not clamped *up* to SIDEBAR_MIN when the viewport itself is too
  * narrow to hold both panes — the caller decides whether to render at all
- * (e.g. drawer instead of inline). See `canFitInline`.
+ * (e.g. single-pane stack instead of inline). See `canFitInline`.
  */
 export const resolveSidebarWidth = (viewport: number, preferred: number): number => {
 	const ceiling = viewport - DIVIDER_WIDTH - READER_MIN_WIDTH
@@ -46,15 +44,17 @@ export const defaultPreferredWidth = (viewport: number): number =>
 
 /**
  * True when an inline (side-by-side) layout still gives the reader at least
- * READER_MIN_WIDTH. When false, the caller should render the sidebar as a
- * drawer instead — see DESIGN.md §7.1 Q2.
+ * READER_MIN_WIDTH. When false, the viewport is "narrow" and the UI runs in
+ * single-pane stack mode — sidebar OR reader fills the pane area, never both.
+ * See DESIGN.md §7.1.
  */
 export const canFitInline = (viewport: number): boolean =>
 	viewport >= SIDEBAR_MIN_WIDTH + DIVIDER_WIDTH + READER_MIN_WIDTH
 
 /**
- * Launch bucket decision for `--sidebar=auto`. Buckets are consulted once at
- * launch only; subsequent visibility changes go through `shown` + focus.
+ * Initial sidebar visibility for `--sidebar=auto`. Always true — every
+ * viewport now boots on the sidebar (narrow: as the single visible screen;
+ * wide: as the focused inline pane). `--sidebar=off` is the only way to
+ * boot directly into the reader.
  */
-export const initialShownForAuto = (viewport: number): boolean =>
-	viewport >= TIGHT_VIEWPORT_THRESHOLD
+export const initialShownForAuto = (_viewport: number): boolean => true

package/src/layout/sidebarRow.ts

@@ -0,0 +1,85 @@
+/**
+ * Sidebar row layout — basename-first with a dim parent suffix sized to the
+ * available width.
+ *
+ * Pure per-row formatting: a row's rendered shape depends only on its own
+ * path and the column budget — never on neighboring rows. That keeps the
+ * sidebar stable as filters change and the file set grows, and keeps the
+ * function trivially predictable. Disambiguation against same-basename
+ * siblings is the header's job (it shows the full relative path of the
+ * selected row); a future auto-scroll on the selected sidebar row can carry
+ * the same information without altering layout for the rest.
+ *
+ * Truncation policy (head-elide, segment-aware):
+ *   - Full parent fits → render whole.
+ *   - Else drop leading segments one at a time, prefixed with `…/`, until
+ *     the remainder fits — never chops a segment mid-character.
+ *   - When even the tail segment with `…/` overflows, drop the marker.
+ *   - When the tail segment alone overflows, hard-truncate it from its head
+ *     (leading `…`) as a last resort.
+ *
+ * Why head-elide: the immediate parent is the segment closest to the file
+ * and the most universally meaningful one when context shrinks.
+ */
+
+export const SIDEBAR_ROW_SEPARATOR = "  ·  "
+const ELISION_PREFIX = "…/"
+const MIN_PARENT_BUDGET = 3
+
+export interface SidebarRowParts {
+	readonly basename: string
+	readonly separator: string
+	readonly parent: string
+}
+
+export const formatSidebarRow = (relativePath: string, totalWidth: number): SidebarRowParts => {
+	const slash = relativePath.lastIndexOf("/")
+	if (slash < 0) {
+		return { basename: fitTail(relativePath, totalWidth), separator: "", parent: "" }
+	}
+
+	const basename = relativePath.slice(slash + 1)
+	const parentFull = relativePath.slice(0, slash)
+
+	if (basename.length >= totalWidth) {
+		return { basename: fitTail(basename, totalWidth), separator: "", parent: "" }
+	}
+
+	const remaining = totalWidth - basename.length - SIDEBAR_ROW_SEPARATOR.length
+	if (remaining < MIN_PARENT_BUDGET || parentFull.length === 0) {
+		return { basename, separator: "", parent: "" }
+	}
+
+	if (parentFull.length <= remaining) {
+		return row(basename, parentFull)
+	}
+
+	const segments = parentFull.split("/")
+	for (let k = segments.length - 1; k >= 1; k--) {
+		const candidate = ELISION_PREFIX + segments.slice(segments.length - k).join("/")
+		if (candidate.length <= remaining) return row(basename, candidate)
+	}
+
+	// Even one segment with the `…/` marker doesn't fit. Try without the marker.
+	const tail = segments[segments.length - 1]!
+	if (tail.length <= remaining) return row(basename, tail)
+
+	// Hard-chop the tail segment from its head as a last resort.
+	return row(basename, "…" + tail.slice(tail.length - remaining + 1))
+}
+
+const row = (basename: string, parent: string): SidebarRowParts => ({
+	basename,
+	separator: SIDEBAR_ROW_SEPARATOR,
+	parent,
+})
+
+const fitTail = (s: string, width: number): string => {
+	if (s.length <= width) return s
+	// At width ≤ 1 there's no room for both a character and the ellipsis; emit
+	// a single char so the result respects the budget. Callers currently clamp
+	// width to ≥ 4, but the helper carries its own floor so a tighter future
+	// caller can't silently overflow the column.
+	if (width <= 1) return s.slice(0, 1)
+	return s.slice(0, width - 1) + "…"
+}

package/src/serve/server.ts

@@ -86,9 +86,12 @@ export const startServer = ({ path, port = 0 }: StartOptions): ServerHandle => {
 		// user's local files, so leaking them to the network would be a
 		// surprise. URL strings are localhost-only by construction below.
 		hostname: "127.0.0.1",
-		async fetch(req) {
+		async fetch(req, server) {
 			const url = new URL(req.url)
 			if (url.pathname === "/__reload") {
+				// SSE stream is silent between file changes; without this Bun
+				// closes the request at the default 10s idleTimeout and warns.
+				server.timeout(req, 0)
 				// `cancel` receives a reason, not the controller — capture
 				// the controller in `start` so we can remove it from the set
 				// on disconnect. Without this, dead clients accumulate.

package/src/theme/colors.ts

@@ -9,24 +9,60 @@ import type { ColorPalette, ResolvedTheme, ThemeDefinition, Tone } from "./types
  * - UI tokens map name-for-name where they overlap.
  * - `surface` ← `backgroundPanel`, `selectedBg` ← `backgroundElement`,
  *   `selectedBgInactive` ← `borderSubtle`.
- * - `textStrong` borrows `markdownStrong` (the brightest/most-emphasized
- *   text token in opencode's palette).
+ * - `textStrong` ← `primary` (opencode's convention for emphasized brand
+ *   text in UI chrome). Markdown rendering still reads `markdownStrong`
+ *   directly via the syntax map.
  * - `syntax` is a fully populated opentui tree-sitter scope map built from
  *   `markdown*` and `syntax*` tokens.
  */
-const buildPalette = (r: ResolvedTheme): ColorPalette => ({
-	background: r.background,
-	surface: r.backgroundPanel,
-	text: r.text,
-	textStrong: r.markdownStrong,
-	textMuted: r.textMuted,
-	border: r.border,
-	borderActive: r.borderActive,
-	selectedBg: r.backgroundElement,
-	selectedBgInactive: r.borderSubtle,
-	error: r.error,
-	syntax: buildSyntaxMap(r),
-})
+/** Relative luminance of a `#rrggbb` color (0..1). Sufficient for ordering
+ *  two near-neutral chrome colors — not a full WCAG contrast calculation.
+ *  Non-hex inputs fall back to 0.5 so the caller's ordering is a no-op. */
+const luminance = (hex: string): number => {
+	const m = /^#([0-9a-fA-F]{6})$/.exec(hex)
+	if (!m) return 0.5
+	const h = m[1]!
+	const r = parseInt(h.slice(0, 2), 16)
+	const g = parseInt(h.slice(2, 4), 16)
+	const b = parseInt(h.slice(4, 6), 16)
+	// Rec. 601 weighting — perceptual ordering, not the linearized WCAG variant.
+	return (0.299 * r + 0.587 * g + 0.114 * b) / 255
+}
+
+/** Pane chrome assumes the active/raised pane sits on the darker of the two
+ *  background tokens and the dim chrome on the lighter one. Most themes
+ *  define `background` darker than `backgroundPanel` and this is a no-op;
+ *  some (e.g. cursor) flip the polarity, in which case we swap so the
+ *  active-pane convention stays consistent across themes. */
+const orientChrome = (r: ResolvedTheme): { raised: string; dim: string } => {
+	const bg = r.background
+	const panel = r.backgroundPanel
+	return luminance(bg) <= luminance(panel) ? { raised: bg, dim: panel } : { raised: panel, dim: bg }
+}
+
+const buildPalette = (r: ResolvedTheme): ColorPalette => {
+	const { raised, dim } = orientChrome(r)
+	return {
+		background: raised,
+		surface: dim,
+		text: r.text,
+		textStrong: r.primary,
+		textMuted: r.textMuted,
+		border: r.border,
+		borderActive: r.borderActive,
+		selectedBg: r.backgroundElement,
+		selectedBgInactive: r.borderSubtle,
+		selectedListItemText: r.selectedListItemText,
+		primary: r.primary,
+		secondary: r.secondary,
+		accent: r.accent,
+		error: r.error,
+		warning: r.warning,
+		success: r.success,
+		info: r.info,
+		syntax: buildSyntaxMap(r),
+	}
+}
 
 const buildSyntaxMap = (r: ResolvedTheme): Record<string, StyleDefinitionInput> => {
 	const codeBg = r.backgroundPanel

package/src/theme/types.ts

@@ -97,7 +97,14 @@ export interface ColorPalette {
 	readonly borderActive: string
 	readonly selectedBg: string
 	readonly selectedBgInactive: string
+	readonly selectedListItemText: string
+	readonly primary: string
+	readonly secondary: string
+	readonly accent: string
 	readonly error: string
+	readonly warning: string
+	readonly success: string
+	readonly info: string
 	readonly syntax: Record<string, StyleDefinitionInput>
 }
 

package/src/update/cache.ts

@@ -0,0 +1,77 @@
+/**
+ * Update-check cache. Stores the last npm-registry probe result on disk so
+ * we hit the registry at most once per TTL window.
+ *
+ * Layout: `$XDG_CACHE_HOME/house/update-check.json` (fallback
+ * `~/.cache/house/update-check.json`). All IO failures are non-fatal — a
+ * missing or unparseable cache simply forces a fresh probe.
+ *
+ * Schema is intentionally minimal. `tarballOk` distinguishes "we saw the
+ * version and confirmed the tarball is downloadable" from "we saw the
+ * version but the CDN HEAD failed" — only the former gates the notice. A
+ * `false` entry forces a retry on the next launch rather than waiting out
+ * the TTL.
+ */
+
+import { dirname, join } from "node:path"
+import { homedir } from "node:os"
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises"
+
+export interface UpdateCacheRecord {
+	readonly checkedAt: number
+	readonly latestVersion: string
+	readonly tarballOk: boolean
+}
+
+export const cacheDir = (): string => {
+	const xdg = process.env.XDG_CACHE_HOME
+	if (xdg && xdg.length > 0) return join(xdg, "house")
+	return join(homedir(), ".cache", "house")
+}
+
+export const cachePath = (): string => join(cacheDir(), "update-check.json")
+
+export const readCache = async (path = cachePath()): Promise<UpdateCacheRecord | null> => {
+	try {
+		const raw = await readFile(path, "utf8")
+		const parsed = JSON.parse(raw) as unknown
+		if (typeof parsed !== "object" || parsed === null) return null
+		const r = parsed as Record<string, unknown>
+		if (
+			typeof r.checkedAt !== "number" ||
+			typeof r.latestVersion !== "string" ||
+			typeof r.tarballOk !== "boolean"
+		) {
+			return null
+		}
+		return {
+			checkedAt: r.checkedAt,
+			latestVersion: r.latestVersion,
+			tarballOk: r.tarballOk,
+		}
+	} catch {
+		return null
+	}
+}
+
+export const writeCache = async (record: UpdateCacheRecord, path = cachePath()): Promise<void> => {
+	// Atomic write: writeFile to a sibling tmp path, then rename. Rename is
+	// atomic on POSIX, so a process.exit() racing the writer either leaves
+	// the prior file intact or installs the new one fully — never a partial
+	// JSON blob that readCache would have to ignore.
+	const tmp = `${path}.${process.pid}.${Date.now()}.tmp`
+	try {
+		await mkdir(dirname(path), { recursive: true })
+		await writeFile(tmp, JSON.stringify(record), "utf8")
+		await rename(tmp, path)
+	} catch {
+		// Cache writes are best-effort. A read-only HOME or full disk should
+		// not break the app; we'll just re-probe on the next launch. Clean up
+		// the tmp file if writeFile partially succeeded but rename did not.
+		try {
+			await unlink(tmp)
+		} catch {
+			// best-effort
+		}
+	}
+}

package/src/update/check.ts

@@ -0,0 +1,165 @@
+/**
+ * Update probe. Resolves to an upgrade record iff a strictly-newer version
+ * is published on npm AND its tarball is actually downloadable.
+ *
+ * The HEAD on `dist.tarball` is the load-bearing step: the npm registry can
+ * publish version metadata moments before the CDN serves the tarball, and
+ * we promised not to nag the user toward a version they cannot install
+ * yet. A non-200 HEAD invalidates the cache entry (tarballOk=false) so the
+ * next launch retries instead of waiting out the TTL.
+ *
+ * All failures are silent. The notice surface is opportunistic — the user
+ * should never see an error from a feature whose job is to whisper.
+ */
+
+import { isNewer } from "./compare.ts"
+import { readCache, writeCache, type UpdateCacheRecord } from "./cache.ts"
+
+export const TTL_MS = 24 * 60 * 60 * 1000
+const FETCH_TIMEOUT_MS = 3000
+const REGISTRY_URL = (pkgName: string) => `https://registry.npmjs.org/${pkgName}/latest`
+
+export interface UpdateInfo {
+	readonly pkgName: string
+	readonly currentVersion: string
+	readonly latestVersion: string
+}
+
+export interface CheckOptions {
+	readonly pkgName: string
+	readonly currentVersion: string
+	/** Override for tests. Defaults to the npm registry + global fetch. */
+	readonly now?: () => number
+	readonly env?: Record<string, string | undefined>
+	readonly fetchImpl?: typeof fetch
+	readonly cacheRead?: () => Promise<UpdateCacheRecord | null>
+	readonly cacheWrite?: (r: UpdateCacheRecord) => Promise<void>
+}
+
+/** Treat any non-empty, non-`0`, non-`false` value as opt-out. Mirrors the
+ *  permissiveness of the de-facto npm-ecosystem convention; a user copy-
+ *  pasting `NO_UPDATE_NOTIFIER=true` from another tool's docs should work. */
+const isTruthyEnv = (value: string | undefined): boolean => {
+	if (!value) return false
+	const v = value.toLowerCase()
+	return v !== "0" && v !== "false" && v !== "no"
+}
+
+/** Most major CIs (GitHub Actions, GitLab, Travis, CircleCI, Jenkins) set
+ *  `CI=true`. A few set it to other truthy values; treat any non-empty
+ *  value as "we're in CI, skip the nag." */
+const isCi = (env: Record<string, string | undefined>): boolean =>
+	typeof env.CI === "string" &&
+	env.CI.length > 0 &&
+	env.CI !== "0" &&
+	env.CI.toLowerCase() !== "false"
+
+/** Run a fetch with a single timeout that covers BOTH the response headers
+ *  and the caller's body read. Returning the bare Response and then reading
+ *  `res.json()` outside the timer leaves the body stream unbounded — a
+ *  stalled connection after headers would hang forever. The consumer
+ *  callback runs while the AbortController is still live, so an abort
+ *  cancels an in-flight body read too. */
+const fetchWithTimeout = async <T>(
+	url: string,
+	init: RequestInit,
+	consume: (res: Response) => Promise<T>,
+	fetchImpl: typeof fetch = fetch,
+): Promise<T> => {
+	const ctrl = new AbortController()
+	const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS)
+	try {
+		const res = await fetchImpl(url, { ...init, signal: ctrl.signal })
+		return await consume(res)
+	} finally {
+		clearTimeout(timer)
+	}
+}
+
+/**
+ * Run the probe and return upgrade info if one applies. `null` covers
+ * every "no nag" case: opt-out, recent cache hit on the same version, no
+ * newer version, registry/CDN failure, malformed response.
+ */
+export const checkForUpdate = async (opts: CheckOptions): Promise<UpdateInfo | null> => {
+	const env = opts.env ?? process.env
+	if (isTruthyEnv(env.NO_UPDATE_NOTIFIER) || isCi(env)) {
+		return null
+	}
+
+	const now = opts.now ?? Date.now
+	const cacheRead = opts.cacheRead ?? (() => readCache())
+	const cacheWrite = opts.cacheWrite ?? ((r: UpdateCacheRecord) => writeCache(r))
+
+	const cached = await cacheRead()
+	const fresh = cached !== null && cached.tarballOk && now() - cached.checkedAt < TTL_MS
+	if (fresh) {
+		return isNewer(cached.latestVersion, opts.currentVersion)
+			? {
+					pkgName: opts.pkgName,
+					currentVersion: opts.currentVersion,
+					latestVersion: cached.latestVersion,
+				}
+			: null
+	}
+
+	// Probe the registry.
+	let latestVersion: string
+	let tarballUrl: string
+	try {
+		const parsed = await fetchWithTimeout(
+			REGISTRY_URL(opts.pkgName),
+			{ headers: { accept: "application/json" } },
+			async (res) => {
+				if (!res.ok) return null
+				const body = (await res.json()) as unknown
+				if (typeof body !== "object" || body === null) return null
+				const obj = body as Record<string, unknown>
+				const version = obj.version
+				const dist = obj.dist as Record<string, unknown> | undefined
+				const tarball = dist?.tarball
+				if (typeof version !== "string" || typeof tarball !== "string") return null
+				// The registry returns a CDN URL we're about to HEAD without
+				// further validation. Pin to https so a compromised or proxied
+				// registry can't redirect us to file://, http://, or another
+				// scheme we'd issue a request against.
+				try {
+					if (new URL(tarball).protocol !== "https:") return null
+				} catch {
+					return null
+				}
+				return { version, tarball }
+			},
+			opts.fetchImpl,
+		)
+		if (!parsed) return null
+		latestVersion = parsed.version
+		tarballUrl = parsed.tarball
+	} catch {
+		return null
+	}
+
+	// Verify the artifact is actually downloadable. This is the step that
+	// makes "only announced when the artifact is available" hold.
+	let tarballOk = false
+	try {
+		tarballOk = await fetchWithTimeout(
+			tarballUrl,
+			{ method: "HEAD" },
+			async (res) => res.ok,
+			opts.fetchImpl,
+		)
+	} catch {
+		tarballOk = false
+	}
+
+	await cacheWrite({ checkedAt: now(), latestVersion, tarballOk })
+
+	if (!tarballOk) return null
+	if (!isNewer(latestVersion, opts.currentVersion)) return null
+	return {
+		pkgName: opts.pkgName,
+		currentVersion: opts.currentVersion,
+		latestVersion,
+	}
+}