@bismawy/pi-arnative 0.2.7 → 0.2.9

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.2.9] - 2026-09-30
+
+### Fixed
+- The startup `[Context]`, `[Skills]`, `[Extensions]` and `[Themes]` lists stacked under the header again on pi ≥ 0.99: pi replaced `ExpandableText`'s `getCollapsedText`/`getExpandedText` fields with a `build` callback plus a `state` object, so the section detector matched nothing and the tabs stayed at `[0]`. Both shapes are read now (`sectionBodyOf`), and the same applies to the `[Extension issues]` box, which read the stale `child.text` snapshot instead of the theme-aware `build()` output.
+- Fixed NPM version badge in `README.md` to reference `@bismawy/pi-arnative` instead of placeholder `react`.
+
+---
+
+## [0.2.8] - 2026-09-28
+
+### Fixed
+- Custom `ctrl+alt+<letter>` shortcuts (`t` next tab, `n` new session, `r` reload) never fired on Windows: Windows Terminal ≥ 1.24 aliases every `Ctrl+Alt` combo to AltGr ([microsoft/terminal#20052](https://github.com/microsoft/terminal/pull/20052)), so the legacy `ESC` + control-byte encoding is never emitted. All of them now also accept `alt+<letter>` on Windows **and WSL** (same input translation), matching pi's own convention (`alt+v`, `alt+p`). Linux keeps `ctrl+alt`, macOS keeps `ctrl+option` (plain Option composes characters there).
+- Shortcut ids, platform variants and cheatsheet labels now come from one place (`lib/shortcuts.ts`) instead of being spelled out per extension; the label is derived from the key id that is actually registered, so a cheatsheet can no longer advertise a key the platform never binds.
+- README: platform notes for Windows/WSL, macOS, Linux desktops and multiplexers, including `PI_TUI_ESC_TIMEOUT` for the intermittent “Escape + stray letter” glitch (`ESC`-prefixed shortcuts flushed by pi's ~10 ms lone-ESC timer).
+- Reload state for the chat clock now lives on a `globalThis` symbol instead of module locals: `/reload` re-imports the module while the prototype patches stay on the class, so the surviving render closure and the new `session_start` handler read the same map and theme. The old shape captured `ctx` in the module, which pi rejects after reload/session replacement, and that throw surfaced as an uncaughtException during a render pass.
+
+---
+
 ## [0.2.7] - 2026-09-28
 
 ### Fixed

package/README.md

@@ -1,9 +1,9 @@
 # Arnative
 
-A visual layer and tool styling tailored to your vibe coding.
+Refined aesthetics. Cohesive tools. Built for Pi.
 
 [![Custom badge](https://shieldcn.dev/badge/pi-%20Packages.svg?variant=outline&size=xs&logo=ri%3APiPiBold)](https://pi.dev/packages/@bismawy/pi-arnative)
-[![badge](https://shieldcn.dev/npm/react.svg?variant=outline&size=xs)](https://www.npmjs.com/package/@bismawy/pi-arnative)
+[![badge](https://shieldcn.dev/npm/@bismawy/pi-arnative.svg?variant=outline&size=xs)](https://www.npmjs.com/package/@bismawy/pi-arnative)
 [![license](https://shieldcn.dev/github/bismawy/pi-arnative/license.svg?variant=outline&size=xs)](https://github.com/bismawy/pi-arnative)
 
 ![Arnative: tabbed header, rounded tool boxes, transcript clock and /usage dashboard](https://raw.githubusercontent.com/bismawy/pi-arnative/main/assets/pi-arnative.webp)
@@ -35,30 +35,30 @@ pi --extension ./extensions/footer.ts
 
 ## Shortcuts
 
-| Key / Action | Result |
+| Key (Linux / Win) | Action |
 | --- | --- |
+| `ctrl+alt+t` · `alt+t` | Cycle header tabs |
+| `ctrl+alt+r` · `alt+r` | Quick reload (`/reload`) |
+| `ctrl+alt+n` · `alt+n` | New session (`/new`) — requires keybinding below |
 | `/usage` | Show session usage & token metrics |
-| `ctrl+alt+t` | Cycle header tabs (Directory → Model → Context → Skills → Extensions → Themes → Shortcut) |
-| `ctrl+alt+n` | Start a new session (`/new`) — see [Keybindings](#keybindings) |
-| `ctrl+alt+r` | Quick reload runtime (`/reload`) |
 | Click tab | Open selected header tab |
 | Click tool / `ctrl+e` | Toggle tool output box |
 
-Same cheatsheet in the header's **Shortcut** tab; on narrow terminals the rightmost tabs drop off first.
+> **Notes:**
+> - **Windows / WSL:** Windows Terminal aliases `Ctrl+Alt` to AltGr; use `alt+…` (or set `"altGrAliasing": false` in WT profile).
+> - **macOS:** uses `ctrl+option+…` (plain Option composes special characters).
+> - **Herdr / tmux glitch:** if shortcuts feel delayed or type stray letters, set `PI_TUI_ESC_TIMEOUT=100` in your shell profile.
 
-## Keybindings
+### Keybindings
 
-`ctrl+alt+n` is a plain user keybinding, not a package shortcut — pi-arnative never registers it.
-Add it once to `~/.pi/agent/keybindings.json`:
+Add to `~/.pi/agent/keybindings.json` to bind `app.session.new`:
 
 ```json
 {
-  "app.session.new": "ctrl+alt+n"
+  "app.session.new": ["ctrl+alt+n", "alt+n"]
 }
 ```
 
-Restart pi to pick it up.
-
 ## Architecture
 
 <details>

package/extensions/footer.ts

@@ -9,16 +9,17 @@
  */
 import type { AssistantMessage } from "@earendil-works/pi-ai";
 import { CustomEditor, FooterComponent, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { execFile } from "node:child_process";
 import { stripAnsi } from "../lib/ansi.ts";
 import { assert, isMain } from "../lib/check.ts";
 import { capitalize, modelDisplayParts } from "../lib/format.ts";
+import { IS_WINDOWS_LIKE, SHORTCUT_RELOAD } from "../lib/shortcuts.ts";
 import { formatTokens } from "../lib/usage-store.ts";
 
+// ctrl+alt+r (alt+r on Windows/WSL — see lib/shortcuts.ts).
 // The TUI drops key-release events before handleInput, so press+release cannot
 // fire this twice even when the terminal reports event types (Kitty flag 2).
-const RELOAD_SHORTCUT = Key.ctrlAlt("r");
 
 // Intercept the built-in FooterComponent to force a pure 2-line footer
 const PATCHED_KEY = Symbol.for("pi-arnative.footer2LinesPatched");
@@ -464,7 +465,7 @@ export default function (pi: ExtensionAPI) {
 				}
 
 				handleInput(data: string) {
-					if (matchesKey(data, RELOAD_SHORTCUT)) {
+					if (SHORTCUT_RELOAD.matches(data)) {
 						this.setText("");
 						if (this.onSubmit) {
 							this.onSubmit("/reload");
@@ -642,9 +643,10 @@ if (isMain(import.meta.url)) {
 
 	// Guard: the reload shortcut must match every encoding a terminal can deliver,
 	// so a typo in the key id fails here instead of silently doing nothing.
-	assert(matchesKey("\x1b\x12", RELOAD_SHORTCUT), "shortcut matches legacy ctrl+alt+r (ESC + 0x12)");
-	assert(matchesKey("\x1b[114;7u", RELOAD_SHORTCUT), "shortcut matches Kitty CSI-u ctrl+alt+r");
-	assert(!matchesKey("\x12", RELOAD_SHORTCUT), "plain ctrl+r does not trigger reload");
-	assert(!matchesKey("r", RELOAD_SHORTCUT), "bare letter r does not trigger reload");
+	assert(SHORTCUT_RELOAD.matches("\x1b\x12"), "shortcut matches legacy ctrl+alt+r (ESC + 0x12)");
+	assert(SHORTCUT_RELOAD.matches("\x1b[114;7u"), "shortcut matches Kitty CSI-u ctrl+alt+r");
+	assert(SHORTCUT_RELOAD.matches("\x1br") === IS_WINDOWS_LIKE, "ESC + r triggers reload only where alt+r is bound");
+	assert(!SHORTCUT_RELOAD.matches("\x12"), "plain ctrl+r does not trigger reload");
+	assert(!SHORTCUT_RELOAD.matches("r"), "bare letter r does not trigger reload");
 	console.log("footer.ts self-check OK");
 }

package/extensions/section-headers.ts

@@ -24,7 +24,6 @@ import {
 import {
 	truncateToWidth,
 	visibleWidth,
-	Key,
 	type Component,
 	type TUI,
 	type TuiMouseEvent,
@@ -34,11 +33,12 @@ import { renderBoxLines } from "../lib/box.ts";
 import { stripAnsi, themeOf } from "../lib/ansi.ts";
 import { assert, isMain } from "../lib/check.ts";
 import { capitalize, modelDisplayParts } from "../lib/format.ts";
+import { SHORTCUT_NEW_SESSION, SHORTCUT_NEXT_TAB, SHORTCUT_RELOAD } from "../lib/shortcuts.ts";
 import { formatTokens, getModelAllTimeUsage } from "../lib/usage-store.ts";
 
 export type TabKey = "Model" | "Directory" | "Context" | "Skills" | "Extensions" | "Themes" | "Shortcut";
 
-// Tab order for Ctrl+Alt+T and for the menu line.
+// Tab order for the next-tab shortcut and for the menu line.
 export const TAB_ORDER: TabKey[] = ["Directory", "Model", "Context", "Skills", "Extensions", "Themes", "Shortcut"];
 
 export const SECTION_ICONS: Record<TabKey, string> = {
@@ -72,6 +72,28 @@ export function fgFirst(th: Themeish, names: string[], text: string): string {
 	return text;
 }
 
+/**
+ * Collapsed body of a pi startup section ("[Skills]\n  a, b"). pi 0.99 dropped
+ * ExpandableText's own getCollapsedText/getExpandedText fields for a `build` callback
+ * plus a `state` object, so both shapes are read here and older pi keeps working.
+ * Returns null when the child is not an expandable section.
+ */
+export function sectionBodyOf(child: any): string | null {
+	if (typeof child?.getCollapsedText === "function") return String(child.getCollapsedText());
+	if (typeof child?.build === "function" && child?.state && typeof child.state === "object") {
+		return String(child.build());
+	}
+	return null;
+}
+
+/** Text of a themed text line, whichever pi version built it (pi 0.99 defers it to `build`). */
+export function themedTextOf(child: any): string {
+	if (typeof child?.build === "function") return String(child.build());
+	const direct = child?.text ?? child?.content;
+	if (typeof direct === "string" && direct !== "") return direct;
+	return typeof child?.getText === "function" ? String(child.getText()) : "";
+}
+
 export function sectionNameOf(text: string): "Context" | "Skills" | "Extensions" | "Themes" | null {
 	const nl = text.indexOf("\n");
 	const first = stripAnsi(nl === -1 ? text : text.slice(0, nl)).trim();
@@ -176,9 +198,9 @@ export const SHORTCUTS: string[] = [
 	"[/] Commands",
 	"[!] Bash",
 	"[Ctrl+o] More/expand",
-	"[Ctrl+alt+t] Next tab",
-	"[Ctrl+alt+n] New",
-	"[Ctrl+alt+r] Reload",
+	`[${SHORTCUT_NEXT_TAB.label}] Next tab`,
+	`[${SHORTCUT_NEW_SESSION.label}] New`,
+	`[${SHORTCUT_RELOAD.label}] Reload`,
 ];
 
 export function wrapCommaItems(items: string[], maxWidth: number): string[] {
@@ -587,20 +609,19 @@ if (UserMessageComponent?.prototype && !(globalThis as Record<symbol, boolean>)[
 		const origAddChild = containerProto.addChild;
 		containerProto.addChild = function (child: any): unknown {
 			try {
-				const sectionName = sectionNameOf(String(child?.getCollapsedText?.() ?? ""));
+				const body = sectionBodyOf(child);
+				const sectionName = body === null ? null : sectionNameOf(body);
 				const isSection =
-					child &&
-					typeof child.getCollapsedText === "function" &&
-					typeof child.getExpandedText === "function" &&
+					body !== null &&
 					typeof child.setText === "function" &&
+					typeof child.render === "function" &&
 					(sectionName === null ? false : SECTION_ICONS[sectionName] !== undefined);
 
-				if (isSection && sectionName) {
+				if (isSection && sectionName && body !== null) {
 					// Mark this container as the loadedResourcesContainer
 					(this as Record<string, unknown>)._isLoadedResourcesContainer = true;
 
-					const origCollapsed = child.getCollapsedText.bind(child) as () => string;
-					const rawBody = origCollapsed().split("\n").slice(1).join("\n");
+					const rawBody = body.split("\n").slice(1).join("\n");
 					const items = extractItemsFromBody(rawBody, sectionName === "Extensions");
 					tabStore.set(sectionName, items);
 
@@ -613,7 +634,7 @@ if (UserMessageComponent?.prototype && !(globalThis as Record<symbol, boolean>)[
 					}
 				} else if ((this as Record<string, unknown>)._isLoadedResourcesContainer) {
 					// pi core's "[Extension issues]" -> wrap in an arnative box.
-					const text = String(child?.text ?? child?.content ?? (typeof child?.getText === "function" ? child.getText() : ""));
+					const text = themedTextOf(child);
 					if (text.includes("[Extension issues]") && typeof child.render === "function") {
 						const origRender = child.render.bind(child);
 						child.render = (w: number) => renderBoxLines(activeThemeProxy, w, origRender(w), undefined, "warning");
@@ -633,17 +654,17 @@ if (UserMessageComponent?.prototype && !(globalThis as Record<symbol, boolean>)[
 }
 
 export default function (pi: ExtensionAPI) {
-	// ctrl+alt+t: next tab.
-	pi.registerShortcut(Key.ctrlAlt("t"), {
-		description: "Next header tab",
-		handler: async () => {
-			const hdr = activeHeaderInstance;
-			if (!hdr) return;
-			const order = TAB_ORDER;
-			hdr.activeTab = order[(order.indexOf(hdr.activeTab) + 1) % order.length]!;
-			hdr.tui?.requestRender?.();
-		},
-	});
+	// Next header tab — every platform variant of the shortcut (lib/shortcuts.ts).
+	const nextTab = async () => {
+		const hdr = activeHeaderInstance;
+		if (!hdr) return;
+		const order = TAB_ORDER;
+		hdr.activeTab = order[(order.indexOf(hdr.activeTab) + 1) % order.length]!;
+		hdr.tui?.requestRender?.();
+	};
+	for (const key of SHORTCUT_NEXT_TAB.keys) {
+		pi.registerShortcut(key, { description: "Next header tab", handler: nextTab });
+	}
 
 	pi.on("session_start", async (_event, ctx) => {
 		activeThemeProxy = themeOf<Themeish>(ctx) ?? activeThemeProxy;
@@ -860,7 +881,10 @@ if (isMain(import.meta.url)) {
 	);
 	const scContent = stripAnsi(linesShortcut.slice(6).join(" "));
 	assert(scContent.includes("[Esc] Interrupt"), "Shortcut tab: legend moved into the content");
-	assert(scContent.includes("[Ctrl+alt+r] Reload"), "Shortcut tab: reload shortcut present in the content");
+	assert(
+		scContent.includes(`[${SHORTCUT_RELOAD.label}] Reload`),
+		`Shortcut tab: reload shortcut present in the content (${SHORTCUT_RELOAD.label})`,
+	);
 	assert(stripAnsi(linesShortcut[2]!).includes("Arnative v"), "line 2 keeps the Arnative brand while the Shortcut tab is active");
 	hdr.activeTab = "Model";
 	hdr.render(140);
@@ -890,5 +914,22 @@ if (isMain(import.meta.url)) {
 	assert(fakeSection.render(80).length === 0, "child of loadedResourcesContainer suppressed (render = [])");
 	assert(tabStore.get("Skills")?.includes("new-skill-1") === true, "new data lands in tabStore");
 
+	// pi 0.99 ExpandableText shape: `build` callback + `state` object, no getters.
+	const modernSection = {
+		state: { expanded: false },
+		build: () => "[Themes]\n  arnative-sun, arnative-dusk",
+		setText: () => {},
+		render: (_w: number) => ["should be hidden"],
+	};
+	container.addChild(modernSection);
+	assert(modernSection.render(80).length === 0, "pi 0.99 section suppressed (build + state shape)");
+	assert(tabStore.get("Themes")?.includes("arnative-sun") === true, "pi 0.99 section data lands in tabStore");
+
+	// Startup help block is not a resource section and must survive untouched.
+	const helpBlock = { build: () => "\u2580\u2580\u2588  v0.99.1\n\u2588\u2580 \u2588 escape interrupt", state: { expanded: false }, render: () => ["help"] };
+	container.addChild(helpBlock);
+	assert(sectionBodyOf(helpBlock) === "\u2580\u2580\u2588  v0.99.1\n\u2588\u2580 \u2588 escape interrupt", "sectionBodyOf reads the build shape");
+	assert(sectionNameOf(sectionBodyOf(helpBlock)!) === null, "startup help block is not a resource section");
+
 	console.log("section-headers.ts self-check OK");
 }

package/extensions/timestamps.ts

@@ -15,9 +15,19 @@ import { sliceByColumn, visibleWidth } from "@earendil-works/pi-tui";
 import { ansiBgOpen, stripAnsi, themeOf } from "../lib/ansi.ts";
 import { assert, isMain } from "../lib/check.ts";
 
-const USER_TIMESTAMPS_MAP = new Map<string, number>();
-let getBranch: (() => readonly unknown[]) | null = null;
-let prefilled = false;
+// Shared across reloads: /reload re-imports this module (moduleCache: false), but the
+// prototype patches below survive on the class, so the patched closure and the newly
+// registered handlers must read the SAME map and theme. Module-local state would leave
+// the closure on stale data — and a captured ctx even on an invalidated one (pi throws
+// "stale after session replacement or reload" inside the render pass -> uncaughtException).
+type ThemeProxy = { fg(color: string, text: string): string; bg?(color: string, text: string): string } | null;
+const TS_STATE_KEY = Symbol.for("pi-arnative.chatTimestampState");
+const tsState = ((globalThis as Record<symbol, unknown>)[TS_STATE_KEY] ??= {
+	patched: false,
+	map: new Map<string, number>(),
+	theme: null as ThemeProxy,
+}) as { patched: boolean; map: Map<string, number>; theme: ThemeProxy };
+const USER_TIMESTAMPS_MAP = tsState.map;
 
 function userTextOf(message: { content?: unknown }): string {
 	const c = message.content;
@@ -44,8 +54,6 @@ function prefillUserTimestamps(entries: readonly unknown[]): void {
 		if (text) USER_TIMESTAMPS_MAP.set(text, m.timestamp || Date.parse(entry.timestamp ?? "") || Date.now());
 	}
 }
-let activeThemeProxy: { fg(color: string, text: string): string; bg?(color: string, text: string): string } | null = null;
-
 function formatClock(timestamp?: number): string {
 	const d = timestamp && timestamp > 0 ? new Date(timestamp) : new Date();
 	const h = String(d.getHours()).padStart(2, "0");
@@ -98,9 +106,8 @@ export function placeTimeAtRight(
 	return `${leftPart}${bg}${pad}${timeBadge} ${reset}`;
 }
 
-const CHAT_TIMESTAMP_PATCHED = Symbol.for("pi-arnative.chatTimestampPatched");
-if (!(globalThis as Record<symbol, boolean>)[CHAT_TIMESTAMP_PATCHED]) {
-	(globalThis as Record<symbol, boolean>)[CHAT_TIMESTAMP_PATCHED] = true;
+if (!tsState.patched) {
+	tsState.patched = true;
 
 	if (UserMessageComponent?.prototype?.render) {
 		const origRender = UserMessageComponent.prototype.render;
@@ -110,22 +117,15 @@ if (!(globalThis as Record<symbol, boolean>)[CHAT_TIMESTAMP_PATCHED]) {
 
 			// Fix the bubble bg first (reset Markdown lines make padding dark),
 			// then paste the clock (which deliberately drops the bg in the badge area).
-			const bgOpen = ansiBgOpen(activeThemeProxy, "userMessageBg");
+			const bgOpen = ansiBgOpen(tsState.theme, "userMessageBg");
 			for (let i = 0; i < lines.length; i++) lines[i] = repairBubbleBg(lines[i], bgOpen);
 
-			// Restore/reload safe: old user messages arrive without message_start events,
-			// so fill the map once from the session history before the first lookup.
-			if (!prefilled && getBranch) {
-				prefillUserTimestamps(getBranch());
-				prefilled = true;
-			}
-
 			const textKey = (this as { text?: string }).text?.trim() ?? "";
 			const ts = USER_TIMESTAMPS_MAP.get(textKey);
 			// No known timestamp -> no clock (a "now" clock would be a lie on old messages).
 			if (!ts) return lines;
 			const timeStr = formatClock(ts);
-			const badge = formatTimeBadge(timeStr, activeThemeProxy);
+			const badge = formatTimeBadge(timeStr, tsState.theme);
 			const timeW = visibleWidth(timeStr);
 
 			// First text line sits at index 1 (below the box top padding)
@@ -165,7 +165,7 @@ if (!(globalThis as Record<symbol, boolean>)[CHAT_TIMESTAMP_PATCHED]) {
 			if (!hasText || lines.length === 0) return lines;
 
 			const timeStr = formatClock(lastMsg?.timestamp);
-			const badge = formatTimeBadge(timeStr, activeThemeProxy);
+			const badge = formatTimeBadge(timeStr, tsState.theme);
 			const timeW = visibleWidth(timeStr);
 
 			// First text line that is neither an OSC zone nor a thinking header
@@ -212,11 +212,15 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	// The active theme is re-read per session (ctx.ui.theme); render reads it lazily.
+	// History for old user messages is read HERE, never at render time: the ctx is only
+	// valid inside a handler. A ctx captured in the module throws after session
+	// replacement/reload (pi's "stale after session replacement or reload" guard) and
+	// that throw would land inside a render pass -> uncaughtException. The session
+	// manager already holds the restored history when session_start fires (all reasons:
+	// startup/resume/fork/new/reload).
 	pi.on("session_start", async (_event, ctx) => {
-		activeThemeProxy = themeOf<typeof activeThemeProxy>(ctx) ?? activeThemeProxy;
-		// History getter for the restore prefill (render-time, once).
-		getBranch = () => ctx.sessionManager.getBranch();
-		prefilled = false;
+		tsState.theme = themeOf<ThemeProxy>(ctx) ?? tsState.theme;
+		prefillUserTimestamps(ctx.sessionManager.getBranch());
 	});
 }
 
@@ -264,5 +268,23 @@ if (isMain(import.meta.url)) {
 	]);
 	assert(USER_TIMESTAMPS_MAP.get("old question") === 1000, "prefill stores the message timestamp");
 	assert((USER_TIMESTAMPS_MAP.get("old reply") ?? 0) > 0, "prefill falls back to the entry timestamp");
+
+	// Reload invariant: /reload re-imports the module while the prototype patch below keeps
+	// running, so the fresh handlers MUST write into the same map/theme the patched render reads.
+	const reloaded = (await import(`${import.meta.url}?reload=1`)) as typeof import("./timestamps.ts");
+	const handlers: Record<string, (event: unknown, ctx: unknown) => unknown> = {};
+	const theme = { fg: (_c: string, t: string) => t };
+	reloaded.default({ on: (ev: string, h: never) => void (handlers[ev] = h) } as never);
+	await handlers.session_start(
+		{},
+		{
+			sessionManager: {
+				getBranch: () => [{ timestamp: "", message: { role: "user", content: "after reload", timestamp: 4242 } }],
+			},
+			ui: { theme },
+		},
+	);
+	assert(USER_TIMESTAMPS_MAP.get("after reload") === 4242, "reloaded module prefills the shared map read by the patched render");
+	assert(tsState.theme === theme, "reloaded module shares the theme read by the patched render");
 	console.log("timestamps.ts self-check OK");
 }

package/lib/shortcuts.ts

@@ -0,0 +1,67 @@
+// Platform-correct key ids for the package's single-letter shortcuts (t / n / r).
+//
+// Windows Terminal >= 1.24 aliases every Ctrl+Alt combo to AltGr (microsoft/terminal
+// PR #20052), so the legacy "ESC + control byte" pair (ctrl+alt+r = \x1b\x12) that
+// matchesKey() looks for is never emitted — the keystroke dies inside the terminal.
+// A WSL pane inherits that same input translation, so it counts as Windows-like too,
+// mirroring pi's own useWindowsKeybindings() (not exported from the package root).
+// pi falls back to alt+<letter> for this class of problem (app.clipboard.pasteImage ->
+// alt+v, app.model.cycleBackward -> alt+p) and every Windows terminal prefixes
+// alt+<letter> with ESC (libuv win/tty.c), so do the same here. macOS keeps ctrl+alt
+// only: plain Option there composes characters (Option+r = ®) unless "Use Option as
+// Meta key" is enabled, while ctrl+alt transmits in every macOS terminal.
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { assert, isMain } from "./check.ts";
+
+/** Windows Terminal's AltGr aliasing hits native Windows and WSL panes alike. */
+export const IS_WINDOWS_LIKE =
+	process.platform === "win32" ||
+	(process.platform === "linux" && Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP));
+
+type Shortcut = {
+	/** Key ids for pi.registerShortcut; the last one is the platform-native key. */
+	keys: string[];
+	/** Cheatsheet label: `Alt+t` on Windows-like, `Ctrl+alt+t` elsewhere, `Ctrl+option+t` on macOS. */
+	label: string;
+	/** Matcher for editors that own their input loop (footer.ts). */
+	matches: (data: string) => boolean;
+};
+
+// Built once, at module scope: `matches` runs on the per-keystroke input path.
+function build(letter: string): Shortcut {
+	const keys = IS_WINDOWS_LIKE ? [Key.ctrlAlt(letter), Key.alt(letter)] : [Key.ctrlAlt(letter)];
+	const native = keys[keys.length - 1]!;
+	const named = process.platform === "darwin" ? native.replace(/alt/g, "option") : native;
+	return {
+		keys,
+		label: named.charAt(0).toUpperCase() + named.slice(1),
+		matches: (data) => keys.some((key) => matchesKey(data, key)),
+	};
+}
+
+export const SHORTCUT_NEXT_TAB = build("t");
+export const SHORTCUT_NEW_SESSION = build("n");
+export const SHORTCUT_RELOAD = build("r");
+
+if (isMain(import.meta.url)) {
+	assert(SHORTCUT_RELOAD.keys[0] === Key.ctrlAlt("r"), "ctrl+alt+r is registered on every platform");
+	assert(
+		SHORTCUT_RELOAD.keys.includes(Key.alt("r")) === IS_WINDOWS_LIKE,
+		"alt+r is registered only where Ctrl+Alt is aliased away",
+	);
+	assert(
+		SHORTCUT_RELOAD.label.toLowerCase().replace(/option/, "alt") === SHORTCUT_RELOAD.keys[SHORTCUT_RELOAD.keys.length - 1],
+		`label derives from the native key id (${SHORTCUT_RELOAD.label})`,
+	);
+	assert(SHORTCUT_RELOAD.matches("\x1b\x12"), "legacy ESC + 0x12 matches ctrl+alt+r");
+	assert(SHORTCUT_RELOAD.matches("\x1b[114;7u"), "Kitty CSI-u matches ctrl+alt+r");
+	assert(SHORTCUT_RELOAD.matches("\x1br") === IS_WINDOWS_LIKE, "ESC + r matches only where alt+r is registered");
+	assert(
+		SHORTCUT_RELOAD.matches("\x1b[114;3u") === IS_WINDOWS_LIKE,
+		"Kitty CSI-u alt+r fires exactly where alt+r is registered",
+	);
+	assert(!SHORTCUT_RELOAD.matches("\x12"), "bare control char does not match ctrl+alt+r");
+	assert(!SHORTCUT_RELOAD.matches("r"), "bare letter does not match ctrl+alt+r");
+	assert(!SHORTCUT_NEXT_TAB.matches("\x1br"), "alt+r does not match the next-tab shortcut");
+	console.log("shortcuts.ts self-check OK");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bismawy/pi-arnative",
-  "version": "0.2.7",
-  "description": "Arnative look for Pi: 11 warm-neutral themes, rounded tool boxes, branded header with tabs, 2-line footer with git/model/status, transcript clock, and a /usage dashboard.",
+  "version": "0.2.9",
+  "description": "Arnative look for Pi: warm-neutral themes, rounded tool boxes, tabbed header, compact footer, transcript clock, and a /usage dashboard.",
   "keywords": [
     "pi-package",
     "pi-theme",
@@ -40,7 +40,7 @@
   },
   "scripts": {
     "dev": "pi --extension ./extensions/tools.ts --extension ./extensions/section-headers.ts --extension ./extensions/footer.ts --extension ./extensions/timestamps.ts --extension ./extensions/ui-render-tweaks.ts --extension ./extensions/usage.ts",
-    "test": "node lib/box.ts && node lib/ansi.ts && node themes/gen-themes.mjs --check && node extensions/tools.ts && node extensions/footer.ts && node extensions/timestamps.ts && node extensions/section-headers.ts && node extensions/ui-render-tweaks.ts && node extensions/usage.ts",
+    "test": "node lib/box.ts && node lib/ansi.ts && node lib/shortcuts.ts && node themes/gen-themes.mjs --check && node extensions/tools.ts && node extensions/footer.ts && node extensions/timestamps.ts && node extensions/section-headers.ts && node extensions/ui-render-tweaks.ts && node extensions/usage.ts",
     "themes": "node themes/gen-themes.mjs"
   }
 }