@sayknow-cli/tui 0.3.12 → 0.3.15

package/dist/types/components/markdown.d.ts

@@ -1,5 +1,6 @@
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
+import { type ViewportAnchorSpan } from "../utils";
 /** Test-only clock seam for streaming throttle tests. */
 export declare function __setMarkdownNowForTest(now: (() => number) | undefined): void;
 /** Test/diagnostic seam: number of synchronous highlight invocations since the last reset. */
@@ -70,6 +71,14 @@ export declare class Markdown implements Component {
     dispose(): void;
     invalidate(): void;
     render(width: number): string[];
+    renderWithViewportAnchorSource(width: number, source: {
+        id: string;
+    }): {
+        lines: string[];
+        anchors: Array<({
+            id: string;
+        } & ViewportAnchorSpan) | null>;
+    };
 }
 /**
  * Render inline markdown (bold, italic, code, links, strikethrough) to a styled string.

package/dist/types/components/sayknow-pet.d.ts

@@ -0,0 +1,128 @@
+/**
+ * ┌─ SAYKNOW PET SPRITE SPEC ────────────────────────────────────────────────┐
+ * The pet is a 16×16 pixel octopus drawn beside the composer. Everything here
+ * is data: no PNGs, no assets — each frame is 16 strings of 16 chars, encoded
+ * to a sixel or kitty escape at runtime. Author a new frame by drawing a grid.
+ *
+ * GRID RULES
+ * - Exactly 16 rows × 16 columns. Only PALETTE keys below are valid chars.
+ * - `.` = transparent. Keep the outer columns transparent so the sprite sits
+ *   snug beside the input box (the widget reserves +1 column of slack).
+ *
+ * PALETTE (char → role) — see PALETTE for exact RGB:
+ *   .=transparent  K=dark outline  R=mantle body  r=body highlight
+ *   W=eye white    V=pupil         G=eye sparkle  b=underside
+ *   w=tear         H h A=reserved (unused by the octopus art)
+ *
+ * FRAME CATALOG (SayknowPixelFrameName → PIXEL_GRIDS):
+ *   base    idle rest; also the dance "drop/settle" beat
+ *   gazeL   eyes glance left    ┐ idle loop (see sayknow-pet-widget IDLE_LOOP)
+ *   gazeR   eyes glance right   │
+ *   flicker eyes blink          ┘
+ *   flex    sparkly "yay" eyes; dance accent + random idle flex burst
+ *   danceL  tentacles sway left   ┐ work loop (PARA_PARA_STEPS)
+ *   danceR  tentacles sway right  ┘
+ *   cry1..3 a tear trails from the outer eye corners (BlueOcto sob)
+ *
+ * RENDERING: buildSayknowPixelFrames({ protocol, cellWidthPx, cellHeightPx,
+ * targetRows: 2 }) scales the art to 2 terminal rows and encodes each frame
+ * once. Kitty uses a native `Y=` sub-cell drop (set by the widget) to sit on the
+ * composer border; sixel uses transparent top padding.
+ *
+ * BEHAVIOR (timing, positioning, on/off) lives in
+ * packages/coding-agent/src/modes/components/sayknow-pet-widget.ts.
+ *
+ * ADD A FRAME: draw the grid → add its name to SayknowPixelFrameName → register it in
+ * PIXEL_GRIDS → reference it from an idle/work loop or a skin burst.
+ *
+ * ADD A PET (skin): append one entry to PET_SKINS below — { id, label, description,
+ * palette, burst }. The id flows into PetSkinId/PetMode automatically, the settings
+ * enum, `/pet` command and both selectors derive their options from PET_SKINS, and the
+ * widget reads `burst` to animate — no other file needs editing. Recolor with a palette
+ * spread (see BLUE_PALETTE); add frames only for poses the catalog lacks.
+ * └────────────────────────────────────────────────────────────────────────┘
+ */
+type Rgb = readonly [number, number, number];
+export type Palette = Record<string, Rgb | null>;
+export declare const PET_SKIN_IDS: readonly ["red", "blue"];
+export type PetSkinId = (typeof PET_SKIN_IDS)[number];
+/** Every pet mode: "off" plus each skin id, in menu order. */
+export declare const PET_MODE_IDS: readonly ["off", "red", "blue"];
+export type PetMode = (typeof PET_MODE_IDS)[number];
+/** Narrow an arbitrary string to a PetMode. */
+export declare function isPetMode(value: string): value is PetMode;
+/** Logical pixel-pet frame names shared by the overlay state machine. */
+export type SayknowPixelFrameName = "base" | "gazeL" | "gazeR" | "flicker" | "flex" | "danceL" | "danceR" | "cry1" | "cry2" | "cry3";
+/** Para-para work dance beats: the working loop and each skin's burst "work-in" intro. */
+export declare const PARA_PARA_STEPS: ReadonlyArray<readonly [SayknowPixelFrameName, number]>;
+/**
+ * A skin's idle burst: a short intro sequence, then an optional looping tail. It drives
+ * BOTH the random live show-off AND the selector's preview demo, so give every skin a
+ * real animation (reuse PARA_PARA_STEPS for a work-in intro) rather than one held frame.
+ */
+export interface PetBurst {
+    /** Frames played once, in order, at the start of the burst. */
+    intro: ReadonlyArray<readonly [SayknowPixelFrameName, number]>;
+    /** Frames cycled every `stepMs` for `ms` after the intro (a held or looping finish). */
+    tail?: {
+        frames: readonly SayknowPixelFrameName[];
+        stepMs: number;
+        ms: number;
+    };
+}
+/** Everything that defines a pet skin: identity, UI copy, colors and behavior. */
+export interface PetSkin {
+    id: PetSkinId;
+    /** Selector/settings label, e.g. "RedOctopus". */
+    label: string;
+    /** One-line selector/settings description. */
+    description: string;
+    palette: Palette;
+    /** Idle burst animation played between quiet idle loops. */
+    burst: PetBurst;
+}
+/** Skin registry — the single source for palettes, behavior and selector/command copy. */
+export declare const PET_SKINS: Record<PetSkinId, PetSkin>;
+/** Total burst duration (intro beats plus the looping tail). */
+export declare function petBurstDurationMs(burst: PetBurst): number;
+/** The frame to show `elapsed` ms into a burst (`now` cycles the looping tail). */
+export declare function petBurstFrame(burst: PetBurst, elapsed: number, now: number): SayknowPixelFrameName;
+/** Test-only access to logical art; production rendering still uses encoded frames. */
+export declare const __sayknowPetTestHooks: {
+    getPixelGrid(name: SayknowPixelFrameName): string[];
+};
+/** Encode a grid as a transparent SIXEL image, optionally bottom-aligned by top padding. */
+export declare function encodeGridSixel(grid: string[], scale: number, topPaddingPx?: number, palette?: Palette): string;
+/** Encode a bottom-aligned grid as kitty raw RGBA at `scale`. */
+export declare function encodeGridKitty(grid: string[], scale: number, imageId: number, cols: number, rows: number, topPaddingPx?: number, cellYOffsetPx?: number, leftPaddingPx?: number, rightPaddingPx?: number, palette?: Palette): string;
+export interface SayknowPixelFrames {
+    /** escape payload per logical frame (drawn at the current cursor cell) */
+    frames: Record<SayknowPixelFrameName, string>;
+    /** protocol the frames were encoded for */
+    protocol: "sixel" | "kitty";
+    widthPx: number;
+    heightPx: number;
+    columns: number;
+    rows: number;
+    /** terminal rows touched by the encoded raster, including pixel offset */
+    rasterRows: number;
+}
+/**
+ * Build overlay pixel frames exactly `targetRows` terminal rows tall when the
+ * terminal cells permit it. Nearest-neighbor sampling preserves the 16x16 art
+ * while allowing fractional scale factors such as 36px / 16px.
+ */
+export declare function buildSayknowPixelFrames(options: {
+    protocol: "sixel" | "kitty";
+    cellWidthPx: number;
+    cellHeightPx: number;
+    targetRows?: number;
+    /** Transparent pixel offset above sixel art for sub-cell vertical placement. */
+    sixelTopPaddingPx?: number;
+    /** Native sub-cell `Y=` pixel offset that drops the kitty sprite within its first cell. */
+    kittyCellYOffsetPx?: number;
+    kittyImageId?: number;
+    /** Color skin for the sprite palette (default "red"). */
+    skin?: PetSkinId;
+}): SayknowPixelFrames;
+export {};

package/dist/types/components/text.d.ts

@@ -1,4 +1,5 @@
 import type { Component } from "../tui";
+import { type ViewportAnchorSpan } from "../utils";
 /**
  * Text component - displays multi-line text with word wrapping
  */
@@ -10,4 +11,12 @@ export declare class Text implements Component {
     setCustomBgFn(customBgFn?: (text: string) => string): void;
     invalidate(): void;
     render(width: number): string[];
+    renderWithViewportAnchorSource(width: number, source: {
+        id: string;
+    }): {
+        lines: string[];
+        anchors: Array<({
+            id: string;
+        } & ViewportAnchorSpan) | null>;
+    };
 }

package/dist/types/index.d.ts

@@ -7,6 +7,7 @@ export * from "./components/image";
 export * from "./components/input";
 export * from "./components/loader";
 export * from "./components/markdown";
+export * from "./components/sayknow-pet";
 export * from "./components/select-list";
 export * from "./components/settings-list";
 export * from "./components/spacer";

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

@@ -22,6 +22,42 @@ export declare class TerminalInfo {
     sendNotification(message: string): void;
 }
 export declare function isNotificationSuppressed(): boolean;
+/**
+ * Returns whether the process runs under a terminal multiplexer (tmux, GNU
+ * screen, or zellij). Recognizes the same host markers as the renderer's
+ * multiplexer predicate in tui.ts so capability selection and viewport-repaint
+ * policy agree on what counts as a multiplexed host. Multiplexers intercept
+ * graphics escapes and OSC 8 hyperlinks instead of forwarding them to the
+ * outer terminal.
+ */
+export declare function isUnderTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;
+export interface TerminalGraphicsFallbackOptions {
+    /**
+     * Permit cursor-neutral image escapes (kitty `a=p,C=1` placements) to render
+     * inside this fallback scope. Cursor-advancing protocols (iTerm2/SIXEL)
+     * remain suppressed. A nested scope without this option revokes the
+     * permission for its own subtree.
+     */
+    allowCursorNeutralImages?: boolean;
+}
+/**
+ * Synchronously suppress terminal graphics while rendering a text-only surface.
+ * Nested scopes remain active until the outermost scope exits.
+ */
+export declare function withTerminalGraphicsFallback<T>(fn: () => T, options?: TerminalGraphicsFallbackOptions): T;
+/** Returns whether terminal graphics are currently suppressed by a render scope. */
+export declare function isTerminalGraphicsFallbackActive(): boolean;
+/**
+ * Returns whether cursor-neutral image escapes may render despite an active
+ * graphics-fallback scope. True only when every active fallback scope opted in.
+ */
+export declare function isCursorNeutralImagePermittedInFallback(): boolean;
+/**
+ * Returns whether PI_FORCE_IMAGE_PROTOCOL explicitly configures the image
+ * protocol, including an explicit "off". An explicit configuration is
+ * authoritative: runtime capability probes must not override it.
+ */
+export declare function isImageProtocolForced(): boolean;
 /**
  * Returns true when running in Windows Terminal with known SIXEL support.
  *
@@ -30,6 +66,13 @@ export declare function isNotificationSuppressed(): boolean;
 export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 export declare const TERMINAL_ID: TerminalId;
 export declare const TERMINAL: TerminalInfo;
+type ImageProtocolChangeListener = (imageProtocol: ImageProtocol | null) => void;
+/**
+ * Subscribe to runtime image-protocol changes (e.g. the asynchronous sixel
+ * capability probe enabling graphics after startup). Returns an unsubscribe
+ * function. Listeners fire only on actual changes.
+ */
+export declare function onImageProtocolChanged(listener: ImageProtocolChangeListener): () => void;
 /**
  * Override terminal image protocol at runtime after capability probes complete.
  */
@@ -141,3 +184,4 @@ export interface RenderedImage {
 }
 export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): RenderedImage | null;
 export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;
+export {};

package/dist/types/tui.d.ts

@@ -57,6 +57,32 @@ export declare function isFocusable(component: Component | null): component is C
  */
 export declare const CURSOR_MARKER = "\u001B_pi:c\u0007";
 export { visibleWidth };
+/** Durable source identifier for a semantically anchored viewport row. */
+export type ViewportAnchorId = string;
+export interface ViewportAnchorRow {
+    id: ViewportAnchorId;
+    graphemeStart: number;
+    graphemeEnd: number;
+    cellStart: number;
+    cellEnd: number;
+}
+export interface ViewportAnchorRender {
+    lines: string[];
+    anchors: Array<ViewportAnchorRow | null>;
+}
+export interface ViewportAnchorProvider extends Component {
+    renderWithViewportAnchors(width: number): ViewportAnchorRender;
+}
+export interface ViewportAnchorSource {
+    id: ViewportAnchorId;
+}
+export interface ViewportAnchorSourceRenderer extends Component {
+    renderWithViewportAnchorSource(width: number, source: ViewportAnchorSource): ViewportAnchorRender;
+}
+export declare function isViewportAnchorProvider(component: Component): component is ViewportAnchorProvider;
+export declare function isViewportAnchorSourceRenderer(component: Component): component is ViewportAnchorSourceRenderer;
+export declare function renderComponentWithViewportAnchors(component: Component, width: number): ViewportAnchorRender;
+export declare function renderComponentWithViewportAnchorSource(component: Component, width: number, source: ViewportAnchorSource): ViewportAnchorRender;
 /**
  * Anchor position for overlays
  */
@@ -72,6 +98,18 @@ export interface OverlayMargin {
 }
 /** Value that can be absolute (number) or percentage (string like "50%") */
 export type SizeValue = number | `${number}%`;
+/**
+ * Startup sixel capability probe policy (pure; exported for tests):
+ * - Never probe when PI_FORCE_IMAGE_PROTOCOL is set — an explicit
+ *   configuration (including "off") is authoritative.
+ * - Never probe inside a terminal multiplexer: tmux advertises DA1 ";4"
+ *   whenever it was compiled with sixel support, regardless of whether the
+ *   attached client terminal can render sixel, so a positive reply is not
+ *   end-to-end evidence. Graphics under a multiplexer are strictly opt-in
+ *   via PI_FORCE_IMAGE_PROTOCOL=sixel.
+ * - Probe Windows Terminal (>=1.22 renders sixel but exposes no env marker).
+ */
+export declare function shouldProbeSixelCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
  * True when repainting only the live viewport is safer than clearing/replaying
  * the full transcript. Native Windows console hosts are included even when
@@ -125,7 +163,7 @@ export interface OverlayHandle {
 /**
  * Container - a component that contains other components
  */
-export declare class Container implements Component {
+export declare class Container implements ViewportAnchorProvider {
     #private;
     children: Component[];
     addChild(component: Component): void;
@@ -135,9 +173,12 @@ export declare class Container implements Component {
     clear(): void;
     /** Remove all children without disposing them (for detach-then-readd reuse). */
     detachAll(): void;
+    /** Registers a direct child as eligible for semantic viewport anchoring. */
+    setViewportAnchorSource(component: Component, source: ViewportAnchorSource | null): void;
     dispose(): void;
     invalidate(): void;
     render(width: number): string[];
+    renderWithViewportAnchors(width: number): ViewportAnchorRender;
 }
 type TuiRenderCounterSnapshot = {
     debugRedrawEnvReads: number;
@@ -174,6 +215,12 @@ export declare class TUI extends Container {
     setClearOnShrink(enabled: boolean): void;
     setFocus(component: Component | null): void;
     setBottomPinnedComponent(component: Component | null): void;
+    /** Register the direct child whose rows are eligible for semantic viewport anchoring. */
+    setViewportAnchorComponent(component: Component | null): void;
+    /** Clear manual viewport ownership before replacing the transcript identity namespace. */
+    resetViewportAnchorIntent(): void;
+    /** Allow one semantic-neighbor reconciliation after a definitive same-transcript rebuild. */
+    prepareViewportAnchorForTranscriptRebuild(): void;
     scrollViewportPages(direction: -1 | 1): boolean;
     followLiveViewport(): boolean;
     /**
@@ -212,4 +259,11 @@ export declare class TUI extends Container {
         normalizationLimit: number;
         truncationLimit: number;
     };
+    /**
+     * Register an emitter whose escape payload is appended to every render
+     * write (inside its own synchronized-output block, cursor saved/restored).
+     * Used for absolute-positioned overlays such as pixel-image pets that live
+     * outside the line-based component model. Return null to emit nothing.
+     */
+    setPostRenderEmitter(emitter: (() => string | null) | undefined): void;
 }

package/dist/types/utils.d.ts

@@ -29,6 +29,29 @@ export declare function padding(n: number): string;
  * Get the shared grapheme segmenter instance.
  */
 export declare function getSegmenter(): Intl.Segmenter;
+export interface ViewportAnchorSpan {
+    graphemeStart: number;
+    graphemeEnd: number;
+    cellStart: number;
+    cellEnd: number;
+}
+export interface ViewportAnchorAnnotation {
+    text: string;
+    nextGrapheme: number;
+    nextCell: number;
+    token: string;
+}
+export declare const VIEWPORT_ANCHOR_PREFIX = "\u001B_ASKC_ANCHOR:";
+/**
+ * Tag every visible grapheme with an APC marker that survives ANSI-aware
+ * wrapping. The marker contains source grapheme and monotonic cell offsets.
+ */
+export declare function annotateViewportAnchorGraphemes(text: string, startGrapheme?: number, startCell?: number, token?: `${string}-${string}-${string}-${string}-${string}`): ViewportAnchorAnnotation;
+/** Remove viewport anchor markers and return the exact marked span for each row. */
+export declare function extractViewportAnchorRows(lines: readonly string[], token: string): {
+    lines: string[];
+    spans: Array<ViewportAnchorSpan | null>;
+};
 export declare function visibleWidthRaw(str: string): number;
 /**
  * Calculate the visible width of a string in terminal columns.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.3.12",
+	"version": "0.3.15",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.3.12",
-		"@sayknow-cli/utils": "0.3.12",
+		"@sayknow-cli/natives": "0.3.15",
+		"@sayknow-cli/utils": "0.3.15",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/image.ts

@@ -3,6 +3,8 @@ import {
 	type ImageDimensions,
 	ImageProtocol,
 	imageFallback,
+	isCursorNeutralImagePermittedInFallback,
+	isTerminalGraphicsFallbackActive,
 	kittyImageId,
 	renderImage,
 	TERMINAL,
@@ -40,7 +42,8 @@ export class Image implements Component {
 
 	#cachedLines?: string[];
 	#cachedWidth?: number;
-	// Kitty graphics: content-derived image id + per-instance placement id.
+	#cachedFallbackActive?: boolean;
+	#cachedProtocol?: ImageProtocol | null;
 	// Computed lazily so non-kitty terminals never pay the hash cost.
 	#kittyImageId?: number;
 	readonly #kittyPlacementId = allocatePlacementId();
@@ -62,6 +65,8 @@ export class Image implements Component {
 	invalidate(): void {
 		this.#cachedLines = undefined;
 		this.#cachedWidth = undefined;
+		this.#cachedFallbackActive = undefined;
+		this.#cachedProtocol = undefined;
 	}
 
 	get retainedBase64DataForTest(): string | undefined {
@@ -81,7 +86,19 @@ export class Image implements Component {
 	}
 
 	render(width: number): string[] {
-		if (this.#cachedLines && this.#cachedWidth === width) {
+		// Kitty placements are cursor-neutral, so an opted-in fallback scope
+		// (e.g. the IRC split) can still render them safely; iTerm2/SIXEL
+		// advance the cursor and stay suppressed.
+		const graphicsSuppressed =
+			isTerminalGraphicsFallbackActive() &&
+			!(TERMINAL.imageProtocol === ImageProtocol.Kitty && isCursorNeutralImagePermittedInFallback());
+		const protocol = TERMINAL.imageProtocol;
+		if (
+			this.#cachedLines &&
+			this.#cachedWidth === width &&
+			this.#cachedFallbackActive === graphicsSuppressed &&
+			this.#cachedProtocol === protocol
+		) {
 			return this.#cachedLines;
 		}
 
@@ -90,12 +107,12 @@ export class Image implements Component {
 
 		let lines: string[];
 
-		if (TERMINAL.imageProtocol) {
+		if (protocol && !graphicsSuppressed) {
 			const base64Data = this.#getBase64Data();
 			if (!base64Data) {
 				lines = this.#fallbackLines();
 			} else {
-				if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
+				if (protocol === ImageProtocol.Kitty) {
 					this.#kittyImageId ??= kittyImageId(base64Data);
 				}
 				const result = renderImage(base64Data, this.#dimensions, {
@@ -139,6 +156,8 @@ export class Image implements Component {
 
 		this.#cachedLines = lines;
 		this.#cachedWidth = width;
+		this.#cachedFallbackActive = graphicsSuppressed;
+		this.#cachedProtocol = protocol;
 
 		return lines;
 	}