@carlesandres/house 0.4.0 → 0.4.1

package/src/index.tsx

@@ -10,6 +10,7 @@
 
 import { stat } from "node:fs/promises"
 import { createCliRenderer, SyntaxStyle } from "@opentui/core"
+import type { BorderSides } from "@opentui/core"
 import { createRoot, useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"
 import { RegistryProvider, useAtomSet, useAtomValue } from "@effect/atom-react"
 import { Cause, Duration, Effect, Fiber, Stream } from "effect"
@@ -19,17 +20,21 @@ import { Browser } from "./Browser.tsx"
 import { parseArgv, usage } from "./cli/argv.ts"
 import { defaultConfigPath, formatConfigError, loadConfig } from "./config/load.ts"
 import { walk, type FileEntry, type SortOrder } from "./discovery/walk.ts"
+import { Header } from "./Header.tsx"
 import { readFileText } from "./io/readFile.ts"
 import { openInBrowser } from "./serve/openBrowser.ts"
 import { startServer } from "./serve/server.ts"
 import { colors, setActiveTheme } from "./theme/colors.ts"
 import { themeAtom, type ThemeState } from "./theme/atom.ts"
 import { getThemeDefinition, themeDefinitions } from "./theme/registry.ts"
+import { formatQuitNotice } from "./update/notice.ts"
+import { currentUpdateInfo, startUpdateProbe } from "./update/runtime.ts"
+import { useUpdateNotice } from "./update/useUpdateNotice.ts"
 
 export interface AppProps {
 	/** Markdown source to render. */
 	readonly content: string
-	/** Optional title shown in the frame border. Defaults to a generic label. */
+	/** Optional title shown in the header's current-file slot. Defaults to a generic label. */
 	readonly title?: string
 	/** Cap the rendered markdown's width at N columns (left-aligned). Null = fill the pane. */
 	readonly maxWidth?: number | null
@@ -56,11 +61,13 @@ interface DiscoverShellProps {
 	readonly target: string
 	readonly all: boolean
 	readonly sort: SortOrder
+	readonly mdx: boolean
 	readonly maxWidth: number | null
 	readonly sidebarMode: SidebarMode
 }
 
-const DiscoverShell = ({ target, all, sort, maxWidth, sidebarMode }: DiscoverShellProps) => {
+const DiscoverShell = ({ target, all, sort, mdx, maxWidth, sidebarMode }: DiscoverShellProps) => {
+	const updateNotice = useUpdateNotice()
 	const [files, setFiles] = useState<readonly FileEntry[]>([])
 	const [scanning, setScanning] = useState<boolean>(true)
 	const [scanError, setScanError] = useState<string | null>(null)
@@ -69,7 +76,7 @@ const DiscoverShell = ({ target, all, sort, maxWidth, sidebarMode }: DiscoverShe
 	const countRef = useRef(0)
 
 	useEffect(() => {
-		const program = walk(target, { all, sort }).pipe(
+		const program = walk(target, { all, sort, mdx }).pipe(
 			Stream.groupedWithin(64, Duration.millis(60)),
 			Stream.runForEach((chunk) =>
 				Effect.sync(() => {
@@ -94,17 +101,17 @@ const DiscoverShell = ({ target, all, sort, maxWidth, sidebarMode }: DiscoverShe
 		return () => {
 			Effect.runFork(Fiber.interrupt(fiber))
 		}
-	}, [target, all, sort])
+	}, [target, all, sort, mdx])
 
 	const discoveryStatus = scanError ?? (scanning ? `indexing… ${countRef.current}` : null)
 
 	return (
 		<Browser
 			files={files}
-			title={target}
 			maxWidth={maxWidth}
 			discoveryStatus={discoveryStatus}
 			sidebarMode={sidebarMode}
+			updateNotice={updateNotice}
 		/>
 	)
 }
@@ -145,13 +152,14 @@ export const App = ({ content, title = "house", maxWidth = null, onQuit }: AppPr
 		if (key.name === "l" && key.shift) toggleTone()
 	})
 
+	const paneBorderSides: BorderSides[] = ["top", "bottom"]
+
 	return (
 		<box style={{ width, height, flexDirection: "column", backgroundColor: colors.background }}>
+			<Header width={width} currentFile={title} />
 			<box
-				title={` ${title} `}
-				titleAlignment="left"
 				style={{
-					border: true,
+					border: paneBorderSides,
 					borderColor: colors.border,
 					padding: 1,
 					flexGrow: 1,
@@ -183,6 +191,8 @@ export const App = ({ content, title = "house", maxWidth = null, onQuit }: AppPr
 	)
 }
 
+let updateExitHookRegistered = false
+
 if (import.meta.main) {
 	const args = parseArgv(Bun.argv.slice(2))
 
@@ -200,12 +210,20 @@ if (import.meta.main) {
 	}
 
 	const config = await Effect.runPromise(
-		loadConfig({ cli: { theme: args.theme, tone: args.tone } }),
+		loadConfig({
+			cli: {
+				theme: args.theme,
+				tone: args.tone,
+				// --no-mdx is a one-way override: present means "off". When
+				// absent, fall through to env/file/default.
+				mdx: args.noMdx ? false : null,
+			},
+		}),
 	).catch((err: unknown) => {
 		console.error(`house: ${formatConfigError(err)}`)
 		process.exit(2)
 	})
-	const { theme: themeId, tone } = config
+	const { theme: themeId, tone, mdx } = config
 	const themeDef = getThemeDefinition(themeId)
 	if (themeDef === undefined) {
 		// Unreachable: Config.schema validated themeId against themeDefinitions.
@@ -275,7 +293,17 @@ if (import.meta.main) {
 			}
 			sidebarMode = args.sidebar
 		}
-		await runTui({ target, themeId, tone, maxWidth, all: args.all, sort, sidebarMode })
+		await runTui({
+			target,
+			themeId,
+			tone,
+			maxWidth,
+			all: args.all,
+			sort,
+			mdx,
+			sidebarMode,
+			updateCheck: !args.noUpdateCheck,
+		})
 	}
 }
 
@@ -286,7 +314,11 @@ interface TuiBootOptions {
 	readonly maxWidth: number | null
 	readonly all: boolean
 	readonly sort: SortOrder
+	readonly mdx: boolean
 	readonly sidebarMode: SidebarMode
+	/** Run the npm-registry probe and surface the "update available" notice.
+	 *  False suppresses both the toast and the quit-time print. */
+	readonly updateCheck: boolean
 }
 
 async function runTui({
@@ -296,7 +328,9 @@ async function runTui({
 	maxWidth,
 	all,
 	sort,
+	mdx,
 	sidebarMode,
+	updateCheck,
 }: TuiBootOptions): Promise<void> {
 	let stats: Awaited<ReturnType<typeof stat>>
 	try {
@@ -306,6 +340,24 @@ async function runTui({
 		process.exit(1)
 	}
 
+	if (updateCheck) {
+		// Fire the npm-registry probe in the background. Result lands in a
+		// module singleton; the React tree picks it up via `useUpdateNotice`
+		// for the footer toast, and the 'exit' hook below reads it
+		// synchronously for the scrollback print. Failures are silent — this
+		// whole feature is opportunistic.
+		startUpdateProbe(pkg.name, pkg.version)
+		// Register once per process. Multiple 'exit' listeners would print
+		// the notice multiple times if runTui were ever re-entered.
+		if (!updateExitHookRegistered) {
+			updateExitHookRegistered = true
+			process.on("exit", () => {
+				const info = currentUpdateInfo()
+				if (info) process.stderr.write(formatQuitNotice(info))
+			})
+		}
+	}
+
 	const renderer = await createCliRenderer({ exitOnCtrlC: false })
 	const initialTheme: ThemeState = { id: themeId, tone }
 
@@ -316,6 +368,7 @@ async function runTui({
 					target={target}
 					all={all}
 					sort={sort}
+					mdx={mdx}
 					maxWidth={maxWidth}
 					sidebarMode={sidebarMode}
 				/>

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/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,
+	}
+}

package/src/update/compare.ts

@@ -0,0 +1,41 @@
+/**
+ * Strict-greater version compare for the update notice.
+ *
+ * The notice fires only when the registry's published version is *strictly
+ * greater* than the running version on its numeric base. Pre-release
+ * suffixes are stripped before compare because:
+ *
+ *  - `dist-tags.latest` is by convention a stable, never a pre-release; the
+ *    notice does not target users who opted into pre-releases via a custom
+ *    install command.
+ *  - A local dev build of `0.5.0-dev.3` should NOT be nagged toward the
+ *    published `0.5.0` while iterating on the same base — they're "the
+ *    same version" for nag purposes.
+ */
+
+const toBaseSegments = (version: string): readonly number[] | null => {
+	const base = version.split("-", 1)[0] ?? ""
+	const parts = base.split(".")
+	const nums: number[] = []
+	for (const p of parts) {
+		const n = Number(p)
+		if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) return null
+		nums.push(n)
+	}
+	return nums.length > 0 ? nums : null
+}
+
+/** True iff `candidate` > `current` on the numeric base. Malformed input → false. */
+export const isNewer = (candidate: string, current: string): boolean => {
+	const a = toBaseSegments(candidate)
+	const b = toBaseSegments(current)
+	if (!a || !b) return false
+	const len = Math.max(a.length, b.length)
+	for (let i = 0; i < len; i++) {
+		const x = a[i] ?? 0
+		const y = b[i] ?? 0
+		if (x > y) return true
+		if (x < y) return false
+	}
+	return false
+}

package/src/update/notice.ts

@@ -0,0 +1,29 @@
+/**
+ * Notice formatting for the update check. Kept separate from the probe so
+ * the surfaces (in-app footer, quit-time stderr print) can be reshaped
+ * without touching the network or cache code.
+ *
+ * Install-method note: we don't try to detect npm vs bun vs Homebrew. The
+ * runtime probe (`process.versions.bun`) only tells us how house was
+ * launched, not how it was installed — a user who ran `npm i -g …` and
+ * then happens to invoke via a bun-installed shim would be misled.
+ * Showing both commands is unambiguous and lets the user pick the one
+ * matching their install.
+ */
+
+import type { UpdateInfo } from "./check.ts"
+
+/** One-liner for the footer toast — must fit a tight viewport. */
+export const formatFooterNotice = (info: UpdateInfo): string =>
+	`update available: ${info.latestVersion} (current ${info.currentVersion})`
+
+/** Multi-line block printed to stderr after the renderer tears down. The
+ *  user keeps this in scrollback and can copy the command directly. */
+export const formatQuitNotice = (info: UpdateInfo): string =>
+	[
+		"",
+		`house ${info.latestVersion} is available (you have ${info.currentVersion}).`,
+		`  npm i -g ${info.pkgName}`,
+		`  bun add -g ${info.pkgName}`,
+		"",
+	].join("\n")