@oh-my-pi/pi-tui 18.2.5 → 18.2.7

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [18.2.7] - 2026-09-21
+
+### Breaking Changes
+
+- Removed specialized keyword modules in favor of a centralized registration system
+
+### Added
+
+- Added `find` tool renderer to display search results with hit ranking and score visualization
+- Supported collapsing/expanding search hit details and range snippets
+- Enabled file hyperlinking for navigation to absolute paths in search results
+- Added streaming progress display for incomplete find tool operations
+- Added Glyph Protocol support for rendering icons without requiring patched fonts
+- Added `setMagicKeywords` for dynamic configuration of highlightable magic keywords
+
+### Fixed
+
+- Prevented magic keywords from triggering spelling autocorrect and underlining
+
 ## [18.2.5] - 2026-09-17
 
 ### Added

package/THIRD-PARTY-NOTICES.txt

@@ -335,43 +335,6 @@ This license allows the work and adaptations of it to be shared and used
 commercially, as long as it is attributed to Poppy Works. The font is bundled
 here (crates/pi-natives/src/fonts/Silver.ttf) as a CJK/Unicode bitmap fallback.
 
--------------------------------------------------------------------------------
-packages/utils/src/vendor/mermaid-ascii/NOTICE
-
-This directory contains an in-house Mermaid-diagram-to-ASCII renderer adapted
-from beautiful-mermaid (https://github.com/lukilabs/beautiful-mermaid), used
-under the MIT License.
-
-  Copyright (c) 2026 Craft Docs
-
-Only the ASCII rendering pipeline is ported (flowchart/state, sequence, class,
-ER, and xychart diagrams); the SVG renderer and its `elkjs` graph-layout
-dependency, the browser entry point, and the SVG theme/style modules were
-dropped. Terminal display width is reimplemented on `Bun.stringWidth`, and
-inline label formatting (HTML tags, markdown emphasis) is reduced to plain text
-for ASCII output. Layout and edge-routing logic is preserved faithfully so
-ASCII output matches the upstream package.
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
 -------------------------------------------------------------------------------
 packages/coding-agent/src/markit/NOTICE
 

package/dist/types/glyph-protocol.d.ts

@@ -0,0 +1,62 @@
+/** One bundled outline: base64 simple-glyph record plus its scale policy. */
+export interface GlyphBundleEntry {
+    /** Base64 OpenType `glyf` simple-glyph record (§8.2 subset). */
+    glyf: string;
+    /** Fill the cell edge to edge (`size=stretch`, powerline); otherwise `size=contain`. */
+    stretch?: boolean;
+}
+/** Generated icon bundle: shared design metrics plus outlines keyed by lowercase hex codepoint. */
+export interface GlyphBundle {
+    upm: number;
+    /** Authored advance width — identical for every glyph of a Mono face. */
+    aw: number;
+    /** Authored line height (ascender − descender); outlines are lifted so y=0 is the descender line. */
+    lh: number;
+    glyphs: Record<string, GlyphBundleEntry>;
+}
+export declare const GLYPH_BUNDLE: GlyphBundle;
+/**
+ * Codepoint the handshake queries after registration to confirm the bundle
+ * was accepted: the omp mark (`icon.omp`), which the status line always shows.
+ */
+export declare const GLYPH_CONFIRMATION_CODEPOINT = 986455;
+/** Terminal reply to any Glyph Protocol verb, decoded from its APC body. */
+export type GlyphProtocolReply = {
+    verb: "s";
+    formats: string[];
+} | {
+    verb: "q";
+    cp: number;
+    coverage: string[];
+} | {
+    verb: "r";
+    cp: number;
+    status: number;
+    reason?: string;
+} | {
+    verb: "c";
+    status: number;
+    reason?: string;
+};
+/** Whether `cp` lies in one of the three Private Use Areas the protocol accepts. */
+export declare function isPrivateUseCodepoint(cp: number): boolean;
+/** `s` verb: doubles as the protocol-detection ping (any reply confirms support). */
+export declare function encodeGlyphSupportQuery(): string;
+/** `q` verb: ask which sources (system font, session glossary) render `cp`. */
+export declare function encodeGlyphCoverageQuery(cp: number): string;
+/**
+ * `r` verb for one bundled outline at `cp`. Layout hints follow the bundle's
+ * design metrics; `reply=0` suppresses the acknowledgement so bulk startup
+ * registration leaves nothing on stdin to drain.
+ */
+export declare function encodeGlyphRegistration(cp: number, entry: GlyphBundleEntry, metrics?: GlyphBundle): string;
+/** Every bundled icon as one contiguous write. */
+export declare function encodeBundledGlyphRegistrations(metrics?: GlyphBundle): string;
+/** Whether `sequence` is a complete Glyph Protocol APC message. */
+export declare function isGlyphProtocolSequence(sequence: string): boolean;
+/**
+ * Decode a terminal reply. Returns null for anything that is not a well-formed
+ * Glyph Protocol message; unknown keys are ignored per §11 so future
+ * parameters never break detection.
+ */
+export declare function parseGlyphProtocolReply(sequence: string): GlyphProtocolReply | null;

package/dist/types/index.d.ts

@@ -37,6 +37,7 @@ export type * from "./editor-component.js";
 export * from "./fuzzy.js";
 export * from "./keybindings.js";
 export * from "./keys.js";
+export * from "./glyph-protocol.js";
 export * from "./kitty-graphics.js";
 export * from "./latex-block.js";
 export * from "./latex-to-unicode.js";

package/dist/types/overlays/model-browser.d.ts

@@ -1,11 +1,14 @@
 import type { Model } from "@oh-my-pi/pi-ai";
+import type { ModelKind } from "@oh-my-pi/pi-catalog/types";
 import type { Component } from "../tui.js";
 import type { SgrMouseEvent } from "../mouse.js";
 import { type ConfiguredThinkingLevel } from "../thinking.js";
 import { type ThemeColor } from "../theme/theme.js";
 /** Canonical display ordering of built-in model roles. */
-export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "commit" | "tiny" | "task" | "advisor";
+export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "commit" | "tiny" | "memory" | "task" | "advisor" | "image" | "web" | "speech" | "dictation" | "judge";
 export declare const MODEL_ROLE_IDS: ModelRole[];
+export declare const CHAT_MODEL_ROLE_IDS: ModelRole[];
+export declare const KIND_ROLE_IDS: ModelRole[];
 /** Measured model performance shown in browser rows. */
 export interface ModelBrowserPerf {
     samples: number;
@@ -18,6 +21,8 @@ export interface ModelBrowserRoleInfo {
     name: string;
     color?: ThemeColor;
     hidden?: boolean;
+    section: "chat" | "kind";
+    accepts(model: Model): boolean;
 }
 /** Role lookup used for scoped model resolution. */
 export interface ModelRoleLookup {
@@ -38,13 +43,14 @@ export interface ModelBrowserSource extends ModelRoleLookup {
     readonly mruOrder: readonly string[];
     readonly modelPerf: ReadonlyMap<string, ModelBrowserPerf>;
     getRoleInfo(role: string): ModelBrowserRoleInfo;
+    defaultRoleChain(role: string): string[];
     resolveRoleValue(value: string | undefined, models: Model[], roleLookup?: ModelRoleLookup): ResolvedModelRoleValue;
 }
 /** Read-only catalog surface consumed by model browsers. */
 export interface ModelBrowserRegistry {
     getError(): unknown;
-    getAvailable(): Model[];
-    getAll(): Model[];
+    getAvailable(kind?: ModelKind | "all"): Model[];
+    getAll(kind?: ModelKind | "all"): Model[];
 }
 /** One selectable row. `selector` is a canonical model key or host-specific virtual key. */
 export interface ModelBrowserItem {

package/dist/types/prompt/gradient-highlight.d.ts

@@ -9,8 +9,8 @@
 export type KeywordHighlighter = (text: string, resetTo?: string, phase?: number) => string;
 /** Declarative spec for {@link createGradientHighlighter}. */
 export interface GradientHighlightSpec {
-    /** Cheap, stateless presence probe used to skip the boundary regex on most lines. Must be non-global. */
-    probe: RegExp;
+    /** Literal substring whose absence skips the boundary regex on most lines. */
+    probe: string;
     /** Global, word-bounded match regex walked by `.replace`. */
     highlight: RegExp;
     /** Number of color stops swept across the gradient. */

package/dist/types/prompt/magic-keywords.d.ts

@@ -1,10 +1,37 @@
 /**
- * Gradient-highlight every magic keyword ("ultrathink", "orchestrate",
- * "workflowz") that appears as standalone prose, skipping any occurrence inside a
- * code block, inline code span, or XML/HTML section. Each highlighter paints its
- * own keyword with its own gradient, so chaining is order-independent — the
- * earlier passes only inject zero-width SGR escapes (no backticks or angle
- * brackets), which never confuse the later passes' markdown masking.
+ * Magic-keyword engine: standalone prose words the host registers via
+ * {@link setMagicKeywords} glow with a per-word gradient in the editor and in
+ * sent bubbles, and are exempt from spelling autocorrect. The host (coding-agent
+ * `modes/magic-keywords.ts`) owns the word list and the notices each word
+ * injects; this module only knows how to find and paint them.
+ */
+/** One registered magic keyword: the prose trigger and its editor gradient. */
+export interface MagicKeywordSpec {
+    /** Exact lowercase trigger, matched only as standalone prose. */
+    readonly word: string;
+    /** HSL hue sweep `[from, to]` in degrees painted across the word; `to` may exceed 360 to wrap through red. */
+    readonly hue: readonly [number, number];
+}
+/**
+ * Replace the registered keyword set. The host calls this once at startup;
+ * until then nothing glows and no word is exempt from autocorrect.
+ */
+export declare function setMagicKeywords(specs: readonly MagicKeywordSpec[]): void;
+/** Whether `word` is exactly a registered magic keyword (used to shield it from spelling autocorrect). */
+export declare function isMagicKeyword(word: string): boolean;
+/**
+ * Whether `text` contains `word` as standalone lowercase prose — never inside
+ * a code block, inline code span, or XML/HTML section. Pure: does not require
+ * `word` to be registered.
+ */
+export declare function containsMagicKeyword(text: string, word: string): boolean;
+/**
+ * Gradient-highlight every registered keyword that appears as standalone
+ * prose, skipping any occurrence inside a code block, inline code span, or
+ * XML/HTML section. Each pass paints one word with its own gradient, so order
+ * is irrelevant — earlier passes only inject zero-width SGR escapes (no
+ * backticks or angle brackets), which never confuse later passes' markdown
+ * masking.
  *
  * `resetTo` is the SGR foreground sequence restored after each painted keyword;
  * pass the surrounding text color when decorating already-colored content (e.g.
@@ -18,9 +45,9 @@
  */
 export declare function highlightMagicKeywords(text: string, resetTo?: string, phase?: number): string;
 /**
- * Cheap test for "does this text contain any magic keyword as standalone prose?".
- * Short-circuits on a substring probe before paying for the markdown-aware
- * prose check, so the common "no keyword in buffer" path is just three
- * `String#indexOf`s. Used by the live editor to gate the shimmer timer.
+ * Cheap test for "does this text contain any registered keyword as standalone
+ * prose?". Short-circuits on a substring probe before paying for the
+ * markdown-aware prose check, so the common "no keyword in buffer" path is one
+ * `String#includes` per word. Used by the live editor to gate the shimmer timer.
  */
 export declare function hasMagicKeyword(text: string): boolean;

package/dist/types/setup/scenes/glyph.d.ts

@@ -1,3 +1,8 @@
 import type { SetupScene } from "./types.js";
-/** Preview and persist the terminal glyph preset. */
+/**
+ * Preview and persist the terminal glyph preset. Skipped once the Glyph
+ * Protocol handshake confirmed the terminal renders omp's bundled icons: every
+ * row renders cleanly there, and the default `unicode` preset already upgrades
+ * to nerd at runtime while staying safe on terminals without the protocol.
+ */
 export declare const glyphSetupScene: SetupScene;

package/dist/types/terminal-capabilities.d.ts

@@ -215,6 +215,12 @@ export interface RuntimeTerminal extends TerminalInfo {
     textSizing: boolean;
     /** Whether the terminal implements colon-subparameter styled underlines (curly + colored). */
     styledUnderlines: boolean;
+    /**
+     * Whether the terminal answered the Glyph Protocol support query with a
+     * `glyf`-capable reply and the bundled icons have been registered. Probe-
+     * driven: false until {@link ProcessTerminal} resolves it.
+     */
+    glyphProtocol: boolean;
 }
 export declare const TERMINAL: RuntimeTerminal;
 /**
@@ -227,6 +233,8 @@ export declare function setTerminalImageProtocol(imageProtocol: ImageProtocol |
  * resolved once at import and force-disabled under the test runtime.
  */
 export declare function setTerminalDeccara(enabled: boolean): void;
+/** Record the Glyph Protocol probe result (called by ProcessTerminal). */
+export declare function setTerminalGlyphProtocol(supported: boolean): void;
 /** Override screen-to-scrollback clear support for targeted renderer tests. */
 export declare function setTerminalScreenToScrollback(enabled: boolean): void;
 /**

package/dist/types/terminal.d.ts

@@ -106,6 +106,13 @@ export type TerminalAppearanceRequestToken = number;
  * set, 4 permanently reset) when the terminal answered DECRQM.
  */
 export type PrivateModeReportHandler = (mode: number, supported: boolean, confirmed?: boolean, status?: number) => void;
+/**
+ * Fired once when the Glyph Protocol handshake resolves. `supported` is true
+ * only after the bundled icons were written and the terminal confirmed (via a
+ * `q` coverage query) that a registered codepoint is served from its
+ * glossary, so a host can safely repaint — or switch to the nerd preset.
+ */
+export type GlyphProtocolReportHandler = (supported: boolean) => void;
 /**
  * Cursor shapes addressable via DECSCUSR (`CSI <n> SP q`). `"default"` (0) hands the shape back to
  * the terminal's own configuration, which is what teardown restores rather than guessing a shape
@@ -208,6 +215,14 @@ export interface Terminal {
      * `status` is the DECRPM value when the terminal answered DECRQM.
      */
     onPrivateModeReport?(callback: PrivateModeReportHandler): void;
+    /**
+     * Register a callback fired once the startup Glyph Protocol handshake
+     * resolves (see {@link GlyphProtocolReportHandler}). A subscriber that
+     * arrives after the handshake already resolved is called immediately with
+     * the stored outcome. Optional so custom Terminals built against older
+     * pi-tui versions keep working.
+     */
+    onGlyphProtocolReport?(callback: GlyphProtocolReportHandler): void;
 }
 /**
  * True when stdout flows through a ConPTY pseudo-console (native win32, or
@@ -254,6 +269,7 @@ export declare class ProcessTerminal implements Terminal {
      */
     refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
     onPrivateModeReport(callback: PrivateModeReportHandler): void;
+    onGlyphProtocolReport(callback: GlyphProtocolReportHandler): void;
     start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
     enableInput(): void;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;

package/dist/types/theme/mermaid-cache.d.ts

@@ -1,10 +1,10 @@
-import { type MermaidAsciiRenderOptions } from "@oh-my-pi/pi-utils/mermaid-ascii";
+import type { MermaidRenderOptions } from "@oh-my-pi/pi-natives";
 /**
  * Options controlling how fenced Mermaid source is resolved to terminal ASCII.
  * Extends the raw render options (theme, color mode, spacing, `useAscii`) with a
  * viewport-fitting hint.
  */
-export interface MermaidResolveOptions extends MermaidAsciiRenderOptions {
+export interface MermaidResolveOptions extends MermaidRenderOptions {
     /**
      * Maximum display width (terminal columns) the diagram should occupy. A
      * layout that overflows this width is re-rendered in the perpendicular

package/dist/types/tools/eval.d.ts

@@ -68,10 +68,11 @@ interface EvalRenderContext {
     timeout?: number;
 }
 /**
- * Append or replace a status event. `agent` events are progress snapshots keyed
- * by `id`, so they coalesce in place (preserving first-seen order); every other
- * op is a discrete action and simply appends. Keeps the persisted event list
- * bounded even when a subagent emits hundreds of throttled progress ticks.
+ * Append or replace a status event. `agent` and `judge_batch` events are
+ * progress snapshots keyed by `id`, so they coalesce in place (preserving
+ * first-seen order); every other op is a discrete action and simply appends.
+ * Keeps the persisted event list bounded even when a subagent or batch emits
+ * hundreds of throttled progress ticks.
  */
 export declare function upsertStatusEvent(events: EvalStatusEvent[], event: EvalStatusEvent): void;
 /** Render eval code cells, structured display output, and progress events. */

package/dist/types/tools/find.d.ts

@@ -0,0 +1,82 @@
+import type { Theme } from "../theme/theme.js";
+import type { Component } from "../tui.js";
+import type { OutputMeta } from "./output-meta.js";
+import type { RenderResultOptions } from "./renderer.js";
+/** A verified line range with its yes-probability and a one-line preview. */
+export interface FindRange {
+    start: number;
+    end: number;
+    p: number;
+    snippet: string;
+}
+/** A file whose verified passages cleared the threshold; `ranges` are merged positive spans, strongest first. */
+export interface FindHit {
+    /** Display path relative to {@link FindToolDetails.cwd}. */
+    rel: string;
+    /** Filename judgment, when the name batch answered. */
+    nameScore?: number;
+    /** Best verified passage probability. */
+    contentScore: number;
+    ranges: FindRange[];
+    /** Lines of content actually judged, and whether the file held more. */
+    linesSeen: number;
+    truncated: boolean;
+}
+/** Search accounting reported alongside the hits. */
+export interface FindStats {
+    /** Eligible files under the root. */
+    listed: number;
+    requests: number;
+    errors: number;
+    /** Entries judged by name. */
+    judged: number;
+    /** Files whose content was read and sent. */
+    filesRead: number;
+    fileBytes: number;
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+    apiMs: number;
+    windowsJudged: number;
+    windowsPruned: number;
+    mapCards: number;
+    /** Distinct request failures, phase-prefixed. */
+    failures: string[];
+}
+/** Display metadata for find tool results. */
+export interface FindToolDetails {
+    query: string;
+    /** Lexical keywords actually used: derived from the query plus `grep_keywords`. */
+    keywords: string[];
+    /** Verified-passage probability at or above which a file is a hit. */
+    threshold: number;
+    hits: FindHit[];
+    stats: FindStats;
+    elapsedMs: number;
+    /** Session cwd; hit paths are relative to it. */
+    cwd: string;
+    /** Display form of the searched directory when narrower than cwd. */
+    scopePath?: string;
+    meta?: OutputMeta;
+}
+interface FindRenderArgs {
+    query?: string;
+    grep_keywords?: string[];
+    path?: string;
+}
+/** Render find calls and results in the transcript. */
+export declare const findToolRenderer: {
+    renderCall(args: FindRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: FindToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: FindRenderArgs): Component;
+    mergeCallAndResult: true;
+    animatedPendingPreview: true;
+    animatedPartialResult: true;
+};
+export {};

package/dist/types/tools/web-search.d.ts

@@ -66,6 +66,10 @@ export declare const SEARCH_PROVIDER_OPTIONS: readonly [{
     readonly value: "xai";
     readonly label: "xAI";
     readonly description: "Grok web search via xAI Responses API (uses SuperGrok/X Premium+ OAuth via /login xai-oauth, or XAI_API_KEY)";
+}, {
+    readonly value: "openrouter";
+    readonly label: "OpenRouter";
+    readonly description: "OpenRouter plugins-based web search with model-selected grounding";
 }, {
     readonly value: "zai";
     readonly label: "Z.AI";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.2.5",
+	"version": "18.2.7",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -37,14 +37,14 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.2.5",
-		"@oh-my-pi/pi-agent-core": "18.2.5",
-		"@oh-my-pi/pi-ai": "18.2.5",
-		"@oh-my-pi/pi-catalog": "18.2.5",
-		"@oh-my-pi/pi-natives": "18.2.5",
-		"@oh-my-pi/pi-utils": "18.2.5",
-		"@oh-my-pi/pi-wire": "18.2.5",
-		"@oh-my-pi/snapcompact": "18.2.5"
+		"@oh-my-pi/omptype": "18.2.7",
+		"@oh-my-pi/pi-agent-core": "18.2.7",
+		"@oh-my-pi/pi-ai": "18.2.7",
+		"@oh-my-pi/pi-catalog": "18.2.7",
+		"@oh-my-pi/pi-natives": "18.2.7",
+		"@oh-my-pi/pi-utils": "18.2.7",
+		"@oh-my-pi/pi-wire": "18.2.7",
+		"@oh-my-pi/snapcompact": "18.2.7"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/glyph-protocol.ts

@@ -0,0 +1,143 @@
+/**
+ * Glyph Protocol client: ships the TUI's private-use icons to the terminal so
+ * the nerd symbol preset renders without a patched font installed.
+ *
+ * Transport is APC `ESC _ 25a1 ; <verb> [; k=v]* [; payload] ESC \` with four
+ * verbs — `s` (support query), `q` (coverage query), `r` (register), `c`
+ * (clear). {@link ProcessTerminal} drives the handshake: `s` behind its DA1
+ * sentinel at startup; on a `glyf`-capable reply it writes
+ * {@link encodeBundledGlyphRegistrations} in one shot followed by a `q` for
+ * {@link GLYPH_CONFIRMATION_CODEPOINT}, and a `glossary` answer confirms the
+ * bundle landed. Registrations are fire-and-forget (`reply=0`),
+ * session-scoped, and confined to the PUA ranges, so they can never restyle
+ * real text.
+ *
+ * Spec: https://github.com/raphamorim/rio/blob/main/specs/glyph-protocol.md
+ * The bundle is generated by `scripts/gen-glyphs.ts` (`bun run gen:glyphs`).
+ */
+import bundle from "./theme/glyph-bundle.json" with { type: "json" };
+
+/** Protocol identifier: U+25A1 WHITE SQUARE as lowercase hex. */
+const GLYPH_PROTOCOL_ID = "25a1";
+const APC = "\x1b_";
+const ST = "\x1b\\";
+
+/** One bundled outline: base64 simple-glyph record plus its scale policy. */
+export interface GlyphBundleEntry {
+	/** Base64 OpenType `glyf` simple-glyph record (§8.2 subset). */
+	glyf: string;
+	/** Fill the cell edge to edge (`size=stretch`, powerline); otherwise `size=contain`. */
+	stretch?: boolean;
+}
+
+/** Generated icon bundle: shared design metrics plus outlines keyed by lowercase hex codepoint. */
+export interface GlyphBundle {
+	upm: number;
+	/** Authored advance width — identical for every glyph of a Mono face. */
+	aw: number;
+	/** Authored line height (ascender − descender); outlines are lifted so y=0 is the descender line. */
+	lh: number;
+	glyphs: Record<string, GlyphBundleEntry>;
+}
+
+export const GLYPH_BUNDLE: GlyphBundle = bundle;
+
+/**
+ * Codepoint the handshake queries after registration to confirm the bundle
+ * was accepted: the omp mark (`icon.omp`), which the status line always shows.
+ */
+export const GLYPH_CONFIRMATION_CODEPOINT = 0xf0d57;
+
+/** Terminal reply to any Glyph Protocol verb, decoded from its APC body. */
+export type GlyphProtocolReply =
+	| { verb: "s"; formats: string[] }
+	| { verb: "q"; cp: number; coverage: string[] }
+	| { verb: "r"; cp: number; status: number; reason?: string }
+	| { verb: "c"; status: number; reason?: string };
+
+/** Whether `cp` lies in one of the three Private Use Areas the protocol accepts. */
+export function isPrivateUseCodepoint(cp: number): boolean {
+	return (cp >= 0xe000 && cp <= 0xf8ff) || (cp >= 0xf0000 && cp <= 0xffffd) || (cp >= 0x100000 && cp <= 0x10fffd);
+}
+
+/** `s` verb: doubles as the protocol-detection ping (any reply confirms support). */
+export function encodeGlyphSupportQuery(): string {
+	return `${APC}${GLYPH_PROTOCOL_ID};s${ST}`;
+}
+
+/** `q` verb: ask which sources (system font, session glossary) render `cp`. */
+export function encodeGlyphCoverageQuery(cp: number): string {
+	return `${APC}${GLYPH_PROTOCOL_ID};q;cp=${cp.toString(16)}${ST}`;
+}
+
+/**
+ * `r` verb for one bundled outline at `cp`. Layout hints follow the bundle's
+ * design metrics; `reply=0` suppresses the acknowledgement so bulk startup
+ * registration leaves nothing on stdin to drain.
+ */
+export function encodeGlyphRegistration(
+	cp: number,
+	entry: GlyphBundleEntry,
+	metrics: GlyphBundle = GLYPH_BUNDLE,
+): string {
+	if (!isPrivateUseCodepoint(cp))
+		throw new RangeError(`U+${cp.toString(16).toUpperCase()} is not a private-use codepoint`);
+	const size = entry.stretch ? "stretch" : "contain";
+	return `${APC}${GLYPH_PROTOCOL_ID};r;cp=${cp.toString(16)};reply=0;upm=${metrics.upm};aw=${metrics.aw};lh=${metrics.lh};size=${size};${entry.glyf}${ST}`;
+}
+
+/** Every bundled icon as one contiguous write. */
+export function encodeBundledGlyphRegistrations(metrics: GlyphBundle = GLYPH_BUNDLE): string {
+	let out = "";
+	for (const hex in metrics.glyphs) {
+		out += encodeGlyphRegistration(Number.parseInt(hex, 16), metrics.glyphs[hex]!, metrics);
+	}
+	return out;
+}
+
+/** Whether `sequence` is a complete Glyph Protocol APC message. */
+export function isGlyphProtocolSequence(sequence: string): boolean {
+	return sequence.startsWith(`${APC}${GLYPH_PROTOCOL_ID};`) && sequence.endsWith(ST);
+}
+
+/**
+ * Decode a terminal reply. Returns null for anything that is not a well-formed
+ * Glyph Protocol message; unknown keys are ignored per §11 so future
+ * parameters never break detection.
+ */
+export function parseGlyphProtocolReply(sequence: string): GlyphProtocolReply | null {
+	if (!isGlyphProtocolSequence(sequence)) return null;
+	const body = sequence.slice(APC.length + GLYPH_PROTOCOL_ID.length + 1, -ST.length);
+	const parts = body.split(";");
+	const verb = parts[0];
+	const params: Record<string, string> = {};
+	for (let i = 1; i < parts.length; i++) {
+		const part = parts[i]!;
+		const eq = part.indexOf("=");
+		if (eq > 0) params[part.slice(0, eq)] = part.slice(eq + 1);
+	}
+	// Empty list values (`fmt=` / `status=`) mean "none", not one empty name.
+	const list = (value: string | undefined): string[] => (value ? value.split(",") : []);
+	switch (verb) {
+		case "s":
+			return { verb, formats: list(params.fmt) };
+		case "q": {
+			const cp = Number.parseInt(params.cp ?? "", 16);
+			if (!Number.isFinite(cp)) return null;
+			return { verb, cp, coverage: list(params.status) };
+		}
+		case "r": {
+			const cp = Number.parseInt(params.cp ?? "", 16);
+			const status = Number.parseInt(params.status ?? "", 10);
+			if (!Number.isFinite(cp) || !Number.isFinite(status)) return null;
+			return params.reason === undefined ? { verb, cp, status } : { verb, cp, status, reason: params.reason };
+		}
+		case "c": {
+			const status = Number.parseInt(params.status ?? "", 10);
+			if (!Number.isFinite(status)) return null;
+			return params.reason === undefined ? { verb, status } : { verb, status, reason: params.reason };
+		}
+		default:
+			return null;
+	}
+}

package/src/index.ts

@@ -48,6 +48,8 @@ export * from "./fuzzy";
 export * from "./keybindings";
 // Kitty keyboard protocol helpers
 export * from "./keys";
+// Glyph Protocol: in-band icon registration (APC 25a1)
+export * from "./glyph-protocol";
 // Kitty graphics: Unicode placeholders
 export * from "./kitty-graphics";
 // LaTeX → Unicode/ANSI math rendering