pi-libtui 0.3.2

package/src/mouse/events.ts

@@ -0,0 +1,55 @@
+export const TEXT_INTERACTION_TARGET = Symbol.for("pi-libtui/mouse/text-interaction-target/v1");
+
+/** Pointer lifecycle events emitted by the shared mouse bridge. */
+export type TuiMouseEventType = "press" | "release" | "drag" | "wheel" | "enter" | "move" | "leave";
+
+/** A normalized pointer event delivered to a component or registered overlay region. */
+export interface TuiMouseEvent {
+	/** Pointer lifecycle phase. */
+	type: TuiMouseEventType;
+	/** Zero-based row relative to the receiving component or region. */
+	row: number;
+	/** Zero-based column relative to the receiving component or region. */
+	col: number;
+	/** Zero-based row in the complete terminal screen. */
+	screenRow: number;
+	/** Zero-based column in the complete terminal screen. */
+	screenCol: number;
+	/** Pressed or released button: primary, middle, or secondary. Undefined for hover and wheel events. */
+	button: 0 | 1 | 2 | undefined;
+	/** Wheel direction, or undefined for non-wheel events. */
+	wheel: -1 | 1 | undefined;
+	/** Whether Shift was held when the terminal emitted the event. */
+	shift: boolean;
+	/** Whether Alt was held when the terminal emitted the event. */
+	alt: boolean;
+	/** Whether Control was held when the terminal emitted the event. */
+	ctrl: boolean;
+}
+
+/**
+ * Opt-in interaction implemented by controls embedded in selectable transcript text.
+ *
+ * The mouse bridge lets native selection observe pointer presses first, activates
+ * the target only when the gesture ends as a click, and offers keyboard input
+ * only after higher-priority viewport handlers such as copy mode decline it.
+ */
+export interface TextInteractionTarget {
+	readonly [TEXT_INTERACTION_TARGET]: true;
+	/** Synchronize visible keyboard focus owned by the shared viewport bridge. */
+	setViewportFocus(focused: boolean): void;
+	/** Handle one unclaimed viewport key. Return true only when it was consumed. */
+	handleViewportInput(data: string): boolean;
+}
+
+/** A terminal-cell rectangle in zero-based screen coordinates. */
+export interface MouseRect {
+	/** Leftmost screen column. */
+	x: number;
+	/** Topmost screen row. */
+	y: number;
+	/** Width in terminal cells. */
+	width: number;
+	/** Height in terminal rows. */
+	height: number;
+}

package/src/mouse/fullscreen-layout.ts

@@ -0,0 +1,260 @@
+import type { SelectionPoint } from "../selection.ts";
+import type { MouseRect } from "./events.ts";
+import type { ViewportRect } from "./registry.ts";
+
+/** Versioned host capability for Pi's validated fullscreen transcript layout. */
+export const FULLSCREEN_LAYOUT_CAPABILITY_KEY = Symbol.for("pi-libtui/fullscreen-layout/v1");
+export const FULLSCREEN_LAYOUT_PROTOCOL = "pi-libtui/fullscreen-layout/v1" as const;
+
+/** The private scroll-view shape exposed through the fullscreen layout capability. */
+export interface LayoutScrollViewReference {
+	readonly scrollTop: number;
+}
+
+/** The primary transcript scroll view with viewport and scrolling controls. */
+export interface LayoutScrollView extends LayoutScrollViewReference {
+	readonly viewportHeight: number;
+	scrollTo(row: number, options?: { disableFollow?: boolean }): void;
+}
+
+/** A validated component layout box supplied by the Pi host bridge. */
+export interface LayoutBox {
+	readonly component: object;
+	readonly rect: MouseRect;
+	readonly clip: MouseRect;
+	readonly children: readonly LayoutBox[];
+	readonly scrollView?: LayoutScrollViewReference;
+	readonly scrollContentLines?: readonly string[];
+}
+
+/** A validated Pi layout frame. The primary scroll view is absent on non-transcript layouts. */
+export interface LayoutFrame {
+	readonly root: LayoutBox;
+	readonly primaryScrollView?: LayoutScrollView;
+}
+
+/** A selection point tied to the scroll view that owns its logical row. */
+export interface LayoutSelectionPoint extends SelectionPoint {
+	readonly scrollView: LayoutScrollView;
+	readonly boundary?: boolean;
+}
+
+/** Current validated fullscreen transcript geometry and selection mapping. */
+export interface FullscreenLayout {
+	readonly frame: LayoutFrame;
+	readonly primaryBox: LayoutBox;
+	readonly primaryScrollView: LayoutScrollView;
+	readonly lines: readonly string[];
+	readonly viewport: ViewportRect;
+	readonly selectionAnchor: LayoutSelectionPoint | undefined;
+	readonly selectionFocus: LayoutSelectionPoint | undefined;
+	setSelection(anchor: LayoutSelectionPoint | undefined, focus: LayoutSelectionPoint | undefined): void;
+	point(point: SelectionPoint, boundary?: boolean): LayoutSelectionPoint;
+	screenPoint(point: SelectionPoint): SelectionPoint;
+}
+
+/** UI-free provider for current Pi fullscreen layout state. */
+export interface FullscreenLayoutCapability {
+	readonly protocol: typeof FULLSCREEN_LAYOUT_PROTOCOL;
+	readonly version: 1;
+	resolve(renderer: object): FullscreenLayout | undefined;
+}
+
+// type-boundary: Symbol.for can contain a capability from another extension realm; this validator narrows its public shape.
+type UntrustedLayoutValue = unknown;
+
+function isRecord(value: UntrustedLayoutValue): value is Record<PropertyKey, UntrustedLayoutValue> {
+	return value !== null && typeof value === "object";
+}
+
+function isFiniteNumber(value: UntrustedLayoutValue): value is number {
+	return typeof value === "number" && Number.isFinite(value);
+}
+
+function isLayoutRect(value: UntrustedLayoutValue): value is MouseRect {
+	if (!isRecord(value)) return false;
+	return (
+		isFiniteNumber(value.x) &&
+		isFiniteNumber(value.y) &&
+		isFiniteNumber(value.width) &&
+		isFiniteNumber(value.height) &&
+		value.width >= 0 &&
+		value.height >= 0
+	);
+}
+
+function isLayoutScrollView(value: UntrustedLayoutValue): value is LayoutScrollView {
+	if (!isRecord(value)) return false;
+	return (
+		isFiniteNumber(value.scrollTop) &&
+		isFiniteNumber(value.viewportHeight) &&
+		value.viewportHeight >= 0 &&
+		typeof value.scrollTo === "function"
+	);
+}
+
+function isLayoutScrollViewReference(value: UntrustedLayoutValue): value is LayoutScrollViewReference {
+	return isRecord(value) && isFiniteNumber(value.scrollTop);
+}
+
+function isLayoutBox(value: UntrustedLayoutValue, ancestors = new Set<object>()): value is LayoutBox {
+	if (!isRecord(value) || ancestors.has(value)) return false;
+	if (
+		!isRecord(value.component) ||
+		!isLayoutRect(value.rect) ||
+		!isLayoutRect(value.clip) ||
+		!Array.isArray(value.children)
+	)
+		return false;
+	if (value.scrollView !== undefined && !isLayoutScrollViewReference(value.scrollView)) return false;
+	if (
+		value.scrollContentLines !== undefined &&
+		(!Array.isArray(value.scrollContentLines) || !value.scrollContentLines.every((line) => typeof line === "string"))
+	)
+		return false;
+	ancestors.add(value);
+	const valid = value.children.every((child) => isLayoutBox(child, ancestors));
+	ancestors.delete(value);
+	return valid;
+}
+
+function isLayoutFrame(value: UntrustedLayoutValue): value is LayoutFrame {
+	if (!isRecord(value) || !isLayoutBox(value.root)) return false;
+	return value.primaryScrollView === undefined || isLayoutScrollView(value.primaryScrollView);
+}
+
+function isLayoutSelectionPoint(value: UntrustedLayoutValue): value is LayoutSelectionPoint {
+	if (!isRecord(value)) return false;
+	return isFiniteNumber(value.row) && isFiniteNumber(value.col) && isLayoutScrollView(value.scrollView);
+}
+
+function containsLayoutBox(
+	root: LayoutBox,
+	target: UntrustedLayoutValue,
+	ancestors = new Set<object>(),
+): target is LayoutBox {
+	if (root === target) return true;
+	if (ancestors.has(root)) return false;
+	ancestors.add(root);
+	try {
+		return root.children.some((child) => containsLayoutBox(child, target, ancestors));
+	} finally {
+		ancestors.delete(root);
+	}
+}
+
+function isFullscreenLayout(value: UntrustedLayoutValue): value is FullscreenLayout {
+	try {
+		if (!isRecord(value) || !isLayoutFrame(value.frame) || !containsLayoutBox(value.frame.root, value.primaryBox))
+			return false;
+		const viewport = value.viewport as UntrustedLayoutValue;
+		if (
+			!isLayoutScrollView(value.primaryScrollView) ||
+			value.frame.primaryScrollView !== value.primaryScrollView ||
+			value.primaryBox.scrollView !== value.primaryScrollView ||
+			!Array.isArray(value.lines) ||
+			!value.lines.every((line) => typeof line === "string") ||
+			value.primaryBox.scrollContentLines !== value.lines ||
+			!isLayoutRect(viewport) ||
+			!isFiniteNumber(isRecord(viewport) ? viewport.scrollTop : undefined) ||
+			(isRecord(viewport) ? viewport.scrollTop : undefined) !== value.primaryScrollView.scrollTop ||
+			typeof value.setSelection !== "function" ||
+			typeof value.point !== "function" ||
+			typeof value.screenPoint !== "function"
+		)
+			return false;
+		const expectedX = Math.max(value.primaryBox.rect.x, value.primaryBox.clip.x);
+		const expectedY = Math.max(value.primaryBox.rect.y, value.primaryBox.clip.y);
+		const expectedWidth = Math.max(
+			0,
+			Math.min(
+				value.primaryBox.rect.x + value.primaryBox.rect.width,
+				value.primaryBox.clip.x + value.primaryBox.clip.width,
+			) - expectedX,
+		);
+		const expectedHeight = Math.max(
+			0,
+			Math.min(
+				value.primaryBox.rect.y + value.primaryBox.rect.height,
+				value.primaryBox.clip.y + value.primaryBox.clip.height,
+			) - expectedY,
+		);
+		if (
+			expectedWidth <= 0 ||
+			expectedHeight <= 0 ||
+			viewport.x !== expectedX ||
+			viewport.y !== expectedY ||
+			viewport.width !== expectedWidth ||
+			viewport.height !== expectedHeight
+		)
+			return false;
+		if (value.selectionAnchor !== undefined && !isLayoutSelectionPoint(value.selectionAnchor)) return false;
+		if (value.selectionFocus !== undefined && !isLayoutSelectionPoint(value.selectionFocus)) return false;
+		return (
+			(value.selectionAnchor === undefined || value.selectionAnchor.scrollView === value.primaryScrollView) &&
+			(value.selectionFocus === undefined || value.selectionFocus.scrollView === value.primaryScrollView)
+		);
+	} catch {
+		return false;
+	}
+}
+
+function isFullscreenLayoutCapability(value: UntrustedLayoutValue): value is FullscreenLayoutCapability {
+	try {
+		if (!isRecord(value)) return false;
+		const candidate = value as Partial<FullscreenLayoutCapability>;
+		return (
+			candidate.protocol === FULLSCREEN_LAYOUT_PROTOCOL &&
+			candidate.version === 1 &&
+			typeof candidate.resolve === "function"
+		);
+	} catch {
+		return false;
+	}
+}
+
+/** Read the optional host-provided fullscreen layout capability without creating one. */
+export function getFullscreenLayoutCapability(
+	scope: typeof globalThis = globalThis,
+): FullscreenLayoutCapability | undefined {
+	try {
+		const slots = scope as Record<PropertyKey, UntrustedLayoutValue>;
+		const candidate = slots[FULLSCREEN_LAYOUT_CAPABILITY_KEY];
+		return isFullscreenLayoutCapability(candidate) ? candidate : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Publish the host-owned fullscreen layout provider and return an identity-safe disposer. */
+export function publishFullscreenLayoutCapability(
+	capability: FullscreenLayoutCapability,
+	scope: typeof globalThis = globalThis,
+): () => void {
+	const slots = scope as Record<PropertyKey, UntrustedLayoutValue>;
+	const existing = slots[FULLSCREEN_LAYOUT_CAPABILITY_KEY];
+	if (isFullscreenLayoutCapability(existing) && existing !== capability) return () => {};
+	if (existing !== capability) slots[FULLSCREEN_LAYOUT_CAPABILITY_KEY] = capability;
+	let disposed = false;
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		if (slots[FULLSCREEN_LAYOUT_CAPABILITY_KEY] === capability)
+			Reflect.deleteProperty(slots, FULLSCREEN_LAYOUT_CAPABILITY_KEY);
+	};
+}
+
+/** Resolve current fullscreen geometry, tolerating an absent, incompatible, or malformed provider. */
+export function resolveFullscreenLayout(
+	renderer: object,
+	scope: typeof globalThis = globalThis,
+): FullscreenLayout | undefined {
+	const capability = getFullscreenLayoutCapability(scope);
+	if (!capability) return undefined;
+	try {
+		const layout = capability.resolve(renderer);
+		return isFullscreenLayout(layout) ? layout : undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/mouse/registry.ts

@@ -0,0 +1,348 @@
+import type { NativeSelectionGeometry } from "../selection.ts";
+import type { MouseRect, TuiMouseEvent } from "./events.ts";
+
+export const MOUSE_REGISTRY_KEY = Symbol.for("pi-libtui/mouse/registry/v1");
+export const MOUSE_PROTOCOL = "pi-libtui/mouse/registry/v1" as const;
+
+/** The visible primary viewport and its logical vertical scroll offset. */
+export interface ViewportRect extends MouseRect {
+	/** Zero-based logical row at the top of the viewport. */
+	scrollTop: number;
+}
+
+/** Terminal and renderer state supplied to screen decorators. */
+export interface ScreenDecorationContext {
+	/** Current terminal width in cells. */
+	width: number;
+	/** Current terminal height in rows. */
+	height: number;
+	/** Whether Pi currently has a visible overlay. */
+	hasOverlay: boolean;
+	/** Native Pi selection is already painted into the screen. */
+	selectionActive?: boolean;
+	/** Current native selection geometry recomputed from Pi's latest layout. */
+	selection?: NativeSelectionGeometry;
+	/** Visible primary viewport when Pi exposes its layout and scroll state. */
+	viewport?: ViewportRect;
+	/** Current logical transcript rows before viewport clipping, when Pi exposes its fullscreen layout. */
+	transcriptLines?: readonly string[];
+}
+
+/** A viewport input transformation, optionally consuming the resulting input. */
+export type ViewportInputHandlerResult = { consume?: boolean; data?: string } | undefined;
+/** Returns whether native copy handling should be deferred for the current selection release. */
+export type NativeCopyDeferrer = () => boolean;
+
+/** Options for one ordered viewport input handler. */
+export interface ViewportInputHandlerRegistration {
+	/** Stable diagnostic identity for the handler. Registrations are removed by object identity. */
+	id: string;
+	/** Dispatch priority. Higher values run first; equal priorities run newest first. Defaults to zero. */
+	priority?: number;
+	/**
+	 * Inspects or transforms viewport input.
+	 *
+	 * @param data Current input after transformations from earlier handlers.
+	 * @returns A replacement `data`, a `consume` decision, both, or undefined to pass through unchanged.
+	 */
+	handle(data: string): ViewportInputHandlerResult;
+}
+
+/** Options for one ordered fullscreen screen decorator. */
+export interface ScreenDecoratorRegistration {
+	/** Stable diagnostic identity for the decorator. Registrations are removed by object identity. */
+	id: string;
+	/** Dispatch priority. Higher values run first; equal priorities run newest first. Defaults to zero. */
+	priority?: number;
+	/**
+	 * Decorates the current rendered screen.
+	 *
+	 * @param screen Current screen after earlier decorators have run.
+	 * @param context Current terminal, overlay, selection, and viewport state.
+	 * @returns The complete screen to pass to the next decorator.
+	 */
+	decorate(screen: string[], context: ScreenDecorationContext): string[];
+}
+
+/** Options for a screen-positioned pointer target outside Pi's component layout. */
+export interface OverlayMouseRegion {
+	/** Stable diagnostic identity for the region. Registrations are removed by object identity. */
+	id: string;
+	/** Higher priorities are hit first. Equal priorities use latest registration first. */
+	priority?: number;
+	/** Resolve on every event because Pi can move or resize an overlay. */
+	getRect(): MouseRect | undefined;
+	/**
+	 * Handles an event whose `row` and `col` are relative to the latest resolved rectangle.
+	 *
+	 * @param event Normalized pointer event for this region.
+	 * @returns `true` when the region handled the event and dispatch should stop.
+	 */
+	onMouse(event: TuiMouseEvent): boolean;
+}
+
+/** Versioned cross-extension registry for pointer, input, copy, and screen-decoration hooks. */
+export interface MouseRegistry {
+	/** Protocol identity used to validate a registry shared through `globalThis`. */
+	readonly protocol: typeof MOUSE_PROTOCOL;
+	/** Public registry API version. */
+	readonly version: 1;
+	/**
+	 * Registers a dynamic screen-positioned pointer target.
+	 *
+	 * @param region Region definition to register.
+	 * @returns An idempotent function that removes this exact registration object.
+	 */
+	registerOverlayRegion(region: OverlayMouseRegion): () => void;
+	/**
+	 * Registers an ordered viewport input handler.
+	 *
+	 * @param handler Handler definition to register.
+	 * @returns An idempotent function that removes this exact registration object.
+	 */
+	registerViewportInputHandler(handler: ViewportInputHandlerRegistration): () => void;
+	/**
+	 * Runs viewport input through registered handlers until one consumes it.
+	 * Handler failures are ignored so optional extensions cannot break input.
+	 *
+	 * @param data Raw viewport input to dispatch.
+	 * @returns The final transformed data and whether a handler consumed it.
+	 */
+	dispatchViewportInput(data: string): { data: string; consumed: boolean };
+	/**
+	 * Registers a predicate that can defer Pi's native copy handling.
+	 *
+	 * @param deferrer Predicate evaluated during native selection release.
+	 * @returns An idempotent function that removes this exact predicate.
+	 */
+	registerNativeCopyDeferrer(deferrer: NativeCopyDeferrer): () => void;
+	/**
+	 * Evaluates registered copy deferrers until one returns true.
+	 * Predicate failures are ignored.
+	 *
+	 * @returns `true` when native copy should be deferred; otherwise `false`.
+	 */
+	shouldDeferNativeCopy(): boolean;
+	/**
+	 * Registers an ordered fullscreen screen decorator.
+	 *
+	 * @param decorator Decorator definition to register.
+	 * @returns An idempotent function that removes this exact registration object.
+	 */
+	registerScreenDecorator(decorator: ScreenDecoratorRegistration): () => void;
+	/**
+	 * Composes registered decorators over a rendered screen.
+	 * Throwing decorators and invalid non-string-array results are ignored.
+	 *
+	 * @param screen Initial rendered screen.
+	 * @param context Current terminal and renderer state.
+	 * @returns The final valid decorated screen, or the last valid screen when a decorator fails.
+	 */
+	dispatchScreenDecorators(screen: string[], context: ScreenDecorationContext): string[];
+	/** Ask the active fullscreen bridge to keep the primary viewport anchored for the next resize. */
+	preserveViewportOnResize?(): void;
+}
+
+/** Shared registration storage used by the mouse bridge for direct overlay dispatch. */
+export interface MouseRegistryState {
+	/** Registered overlay regions in registration order. */
+	readonly regions: OverlayMouseRegion[];
+	/** Registered viewport input handlers in registration order. */
+	readonly viewportInputHandlers: ViewportInputHandlerRegistration[];
+	/** Registered native-copy predicates in registration order. */
+	readonly nativeCopyDeferrers: NativeCopyDeferrer[];
+	/** Registered screen decorators in registration order. */
+	readonly screenDecorators: ScreenDecoratorRegistration[];
+	viewportPreserver?: () => void;
+}
+
+const STATE_KEY = Symbol.for("pi-libtui/mouse/registry-state/v1");
+const states = new WeakMap<MouseRegistry, MouseRegistryState>();
+
+// type-boundary: Symbol.for capabilities can be populated by another extension realm; this validator narrows the public methods.
+type UntrustedRegistryValue = unknown;
+
+function isRegistry(value: UntrustedRegistryValue): value is MouseRegistry {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<MouseRegistry>;
+	return (
+		candidate.protocol === MOUSE_PROTOCOL &&
+		candidate.version === 1 &&
+		typeof candidate.registerOverlayRegion === "function" &&
+		typeof candidate.registerViewportInputHandler === "function" &&
+		typeof candidate.dispatchViewportInput === "function" &&
+		typeof candidate.registerNativeCopyDeferrer === "function" &&
+		typeof candidate.shouldDeferNativeCopy === "function" &&
+		typeof candidate.registerScreenDecorator === "function" &&
+		typeof candidate.dispatchScreenDecorators === "function"
+	);
+}
+
+function stateFor(registry: MouseRegistry): MouseRegistryState {
+	const existing = states.get(registry);
+	if (existing) return existing;
+	const shared = Reflect.get(registry as object, STATE_KEY) as UntrustedRegistryValue;
+	if (isState(shared)) {
+		states.set(registry, shared);
+		return shared;
+	}
+	const state: MouseRegistryState = {
+		regions: [],
+		viewportInputHandlers: [],
+		nativeCopyDeferrers: [],
+		screenDecorators: [],
+	};
+	Object.defineProperty(registry, STATE_KEY, {
+		value: state,
+		enumerable: false,
+		configurable: false,
+	});
+	states.set(registry, state);
+	return state;
+}
+
+function isState(value: UntrustedRegistryValue): value is MouseRegistryState {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<MouseRegistryState>;
+	return (
+		Array.isArray(candidate.regions) &&
+		Array.isArray(candidate.viewportInputHandlers) &&
+		Array.isArray(candidate.nativeCopyDeferrers) &&
+		Array.isArray(candidate.screenDecorators)
+	);
+}
+
+/**
+ * Returns the shared registration state associated with a mouse registry.
+ *
+ * @param registry Registry whose state should be resolved.
+ * @returns The stable state object shared across compatible extension realms.
+ */
+export function getMouseRegistryState(registry: MouseRegistry): MouseRegistryState {
+	return stateFor(registry);
+}
+
+function removeIdentity<T>(values: T[], value: T): void {
+	const index = values.indexOf(value);
+	if (index >= 0) values.splice(index, 1);
+}
+
+function prioritized<T extends { priority?: number }>(values: readonly T[]): T[] {
+	return values
+		.map((value, order) => ({ value, order }))
+		.sort((left, right) => (right.value.priority ?? 0) - (left.value.priority ?? 0) || right.order - left.order)
+		.map(({ value }) => value);
+}
+
+/**
+ * Resolves or creates the process-wide version-one mouse registry.
+ *
+ * Compatible registries already published under {@link MOUSE_REGISTRY_KEY} are reused so
+ * independently loaded extensions share registrations without runtime dependencies.
+ *
+ * @param scope Global object that owns the registry capability. Defaults to `globalThis`.
+ * @returns The existing compatible registry, or a newly installed version-one registry.
+ */
+export function ensureMouseRegistry(scope: typeof globalThis = globalThis): MouseRegistry {
+	const slots = scope as Record<PropertyKey, UntrustedRegistryValue>;
+	const existing = slots[MOUSE_REGISTRY_KEY];
+	if (isRegistry(existing)) {
+		stateFor(existing);
+		return existing;
+	}
+	const registry: MouseRegistry = {
+		protocol: MOUSE_PROTOCOL,
+		version: 1,
+		registerOverlayRegion(region) {
+			const state = stateFor(registry);
+			state.regions.push(region);
+			return () => removeIdentity(state.regions, region);
+		},
+		registerViewportInputHandler(handler) {
+			const state = stateFor(registry);
+			state.viewportInputHandlers.push(handler);
+			return () => removeIdentity(state.viewportInputHandlers, handler);
+		},
+		dispatchViewportInput(data) {
+			let current = data;
+			for (const handler of prioritized(stateFor(registry).viewportInputHandlers)) {
+				let result: ViewportInputHandlerResult;
+				try {
+					result = handler.handle(current);
+				} catch {
+					continue;
+				}
+				if (typeof result?.data === "string") current = result.data;
+				if (result?.consume === true) return { data: current, consumed: true };
+			}
+			return { data: current, consumed: false };
+		},
+		registerNativeCopyDeferrer(deferrer) {
+			const state = stateFor(registry);
+			state.nativeCopyDeferrers.push(deferrer);
+			return () => removeIdentity(state.nativeCopyDeferrers, deferrer);
+		},
+		shouldDeferNativeCopy() {
+			for (const deferrer of [...stateFor(registry).nativeCopyDeferrers]) {
+				try {
+					if (deferrer()) return true;
+				} catch {
+					// Optional predicates must not affect native copy behavior.
+				}
+			}
+			return false;
+		},
+		registerScreenDecorator(decorator) {
+			const state = stateFor(registry);
+			state.screenDecorators.push(decorator);
+			return () => removeIdentity(state.screenDecorators, decorator);
+		},
+		dispatchScreenDecorators(screen, context) {
+			let current = screen;
+			for (const decorator of prioritized(stateFor(registry).screenDecorators)) {
+				try {
+					const decorated = decorator.decorate(current, context);
+					if (Array.isArray(decorated) && decorated.every((line) => typeof line === "string")) current = decorated;
+				} catch {
+					// Optional decorators must not break fullscreen rendering.
+				}
+			}
+			return current;
+		},
+		preserveViewportOnResize() {
+			try {
+				stateFor(registry).viewportPreserver?.();
+			} catch {
+				// The fullscreen bridge is optional and must not break tool interaction.
+			}
+		},
+	};
+	stateFor(registry);
+	slots[MOUSE_REGISTRY_KEY] = registry;
+	return registry;
+}
+
+/** Preserve the host transcript viewport across an expansion resize when a bridge is installed. */
+export function preserveViewportOnResize(scope: typeof globalThis = globalThis): void {
+	ensureMouseRegistry(scope).preserveViewportOnResize?.();
+}
+
+/** Options for blocking transcript selection behind a modal pointer surface. */
+export interface ModalPointerShieldOptions {
+	/** Stable diagnostic identity for the registered region. */
+	id: string;
+	/** Current screen bounds covered by the modal surface. */
+	getRect(): MouseRect | undefined;
+	/** Hit priority below the modal's own region; defaults to 9999. */
+	priority?: number;
+}
+
+/** Consume pointer gestures behind a modal overlay before Pi can begin transcript selection. */
+export function registerModalPointerShield(registry: MouseRegistry, options: ModalPointerShieldOptions): () => void {
+	return registry.registerOverlayRegion({
+		id: options.id,
+		priority: options.priority ?? 9_999,
+		getRect: options.getRect,
+		onMouse: (event) => event.type === "press" || event.type === "drag" || event.type === "release",
+	});
+}

package/src/mouse.ts

@@ -0,0 +1,37 @@
+export {
+	type MouseRect,
+	TEXT_INTERACTION_TARGET,
+	type TextInteractionTarget,
+	type TuiMouseEvent,
+	type TuiMouseEventType,
+} from "./mouse/events.ts";
+export {
+	FULLSCREEN_LAYOUT_CAPABILITY_KEY,
+	FULLSCREEN_LAYOUT_PROTOCOL,
+	type FullscreenLayout,
+	type FullscreenLayoutCapability,
+	getFullscreenLayoutCapability,
+	type LayoutBox,
+	type LayoutFrame,
+	type LayoutScrollView,
+	type LayoutScrollViewReference,
+	type LayoutSelectionPoint,
+	publishFullscreenLayoutCapability,
+	resolveFullscreenLayout,
+} from "./mouse/fullscreen-layout.ts";
+export {
+	ensureMouseRegistry,
+	MOUSE_PROTOCOL,
+	MOUSE_REGISTRY_KEY,
+	type ModalPointerShieldOptions,
+	type MouseRegistry,
+	type NativeCopyDeferrer,
+	type OverlayMouseRegion,
+	preserveViewportOnResize,
+	registerModalPointerShield,
+	type ScreenDecorationContext,
+	type ScreenDecoratorRegistration,
+	type ViewportInputHandlerRegistration,
+	type ViewportInputHandlerResult,
+	type ViewportRect,
+} from "./mouse/registry.ts";