tinky 1.7.0 → 1.9.0

package/lib/components/App.d.ts

@@ -97,7 +97,7 @@ export declare class App extends PureComponent<AppProps, State> {
     rawModeEnabledCount: number;
     internal_eventEmitter: EventEmitter;
     isRawModeSupported(): boolean;
-    render(): import("react/jsx-runtime").JSX.Element;
+    render(): import("react").JSX.Element;
     componentDidMount(): void;
     componentWillUnmount(): void;
     componentDidCatch(error: Error): void;

package/lib/components/ErrorOverview.d.ts

@@ -4,5 +4,5 @@ interface ErrorProps {
 /**
  * Renders an overview of an error, including the message and stack trace.
  */
-export declare function ErrorOverview({ error }: ErrorProps): import("react/jsx-runtime").JSX.Element;
+export declare function ErrorOverview({ error }: ErrorProps): import("react").JSX.Element;
 export {};

package/lib/components/Newline.d.ts

@@ -26,4 +26,4 @@ export interface NewlineProps {
  * );
  * ```
  */
-export declare function Newline({ count }: NewlineProps): import("react/jsx-runtime").JSX.Element;
+export declare function Newline({ count }: NewlineProps): import("react").JSX.Element;

package/lib/components/Raw.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Props for the Raw component.
+ */
+export interface RawProps {
+    /**
+     * Raw content to output unchanged at the component's layout position.
+     * This bypasses normal text rendering: no escaping, wrapping, or
+     * modification is applied.
+     */
+    readonly content: string;
+    /**
+     * Raw content to write to stdout when the component unmounts.
+     * Used as a cleanup sequence (e.g., to clear a terminal image).
+     */
+    readonly cleanup?: string;
+}
+/**
+ * Outputs raw terminal escape sequences at a specific layout position.
+ *
+ * The content bypasses tinky's normal text rendering pipeline and is written
+ * directly to stdout after the main frame is rendered. This is useful for
+ * terminal image protocols (Kitty, iTerm2, Sixel), custom animations, or
+ * any content that must not be modified.
+ *
+ * `Raw` has zero width and height in layout. To reserve space for the raw
+ * content (e.g., for an image), wrap it in a `Box` with the desired
+ * dimensions:
+ *
+ * @example
+ * ```tsx
+ * <Box width={40} height={10}>
+ *   <Raw content={kittyImageSequence} />
+ * </Box>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Raw
+ *   content={imageSequence}
+ *   cleanup={'\x1b_Ga=d\x1b\\'}
+ * />
+ * ```
+ */
+export declare function Raw({ content, cleanup }: RawProps): import("react").JSX.Element;

package/lib/components/Raw.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { useStdout } from "../hooks/use-stdout.js";
+const rawStyle = { width: 0, height: 0 };
+/**
+ * Outputs raw terminal escape sequences at a specific layout position.
+ *
+ * The content bypasses tinky's normal text rendering pipeline and is written
+ * directly to stdout after the main frame is rendered. This is useful for
+ * terminal image protocols (Kitty, iTerm2, Sixel), custom animations, or
+ * any content that must not be modified.
+ *
+ * `Raw` has zero width and height in layout. To reserve space for the raw
+ * content (e.g., for an image), wrap it in a `Box` with the desired
+ * dimensions:
+ *
+ * @example
+ * ```tsx
+ * <Box width={40} height={10}>
+ *   <Raw content={kittyImageSequence} />
+ * </Box>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Raw
+ *   content={imageSequence}
+ *   cleanup={'\x1b_Ga=d\x1b\\'}
+ * />
+ * ```
+ */
+export function Raw({ content, cleanup }) {
+    const { stdout } = useStdout();
+    const cleanupRef = useRef(cleanup);
+    cleanupRef.current = cleanup;
+    useEffect(() => {
+        return () => {
+            const output = cleanupRef.current;
+            if (output) {
+                stdout.write(output);
+            }
+        };
+    }, [stdout]);
+    return _jsx("tinky-raw", { style: rawStyle, internal_rawContent: content });
+}

package/lib/components/Separator.d.ts

@@ -79,4 +79,4 @@ export interface SeparatorProps extends TextStyles {
  * />
  * ```
  */
-export declare function Separator({ char, direction, color, dimColor, backgroundColor, bold, italic, underline, strikethrough, inverse, }: SeparatorProps): import("react/jsx-runtime").JSX.Element;
+export declare function Separator({ char, direction, color, dimColor, backgroundColor, bold, italic, underline, strikethrough, inverse, }: SeparatorProps): import("react").JSX.Element;

package/lib/components/Spacer.d.ts

@@ -16,4 +16,4 @@
  * );
  * ```
  */
-export declare function Spacer(): import("react/jsx-runtime").JSX.Element;
+export declare function Spacer(): import("react").JSX.Element;

package/lib/components/Static.d.ts

@@ -45,4 +45,4 @@ export interface StaticProps<T> {
  * );
  * ```
  */
-export declare function Static<T>(props: StaticProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function Static<T>(props: StaticProps<T>): import("react").JSX.Element;

package/lib/components/Text.d.ts

@@ -47,4 +47,4 @@ export interface TextProps extends TextStyles {
  * );
  * ```
  */
-export declare function Text({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, "aria-label": ariaLabel, "aria-hidden": ariaHidden, }: TextProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function Text({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, "aria-label": ariaLabel, "aria-hidden": ariaHidden, }: TextProps): import("react").JSX.Element | null;

package/lib/components/Text.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useContext } from "react";
+import { useContext, useCallback } from "react";
 import { applyTextStyles, } from "../utils/apply-text-styles.js";
 import { AccessibilityContext } from "../contexts/AccessibilityContext.js";
 import { backgroundContext } from "../contexts/BackgroundContext.js";
@@ -41,7 +41,7 @@ export function Text({ color, backgroundColor, dimColor = false, bold = false, i
     if (childrenOrAriaLabel === undefined || childrenOrAriaLabel === null) {
         return null;
     }
-    const transform = (children) => {
+    const transform = useCallback((children) => {
         return applyTextStyles(children, {
             color,
             backgroundColor: effectiveBackgroundColor,
@@ -52,7 +52,16 @@ export function Text({ color, backgroundColor, dimColor = false, bold = false, i
             strikethrough,
             inverse,
         });
-    };
+    }, [
+        color,
+        effectiveBackgroundColor,
+        dimColor,
+        bold,
+        italic,
+        underline,
+        strikethrough,
+        inverse,
+    ]);
     if (isScreenReaderEnabled && ariaHidden) {
         return null;
     }

package/lib/components/Transform.d.ts

@@ -38,4 +38,4 @@ export interface TransformProps {
  * // Output: HELLO WORLD
  * ```
  */
-export declare function Transform({ children, transform, accessibilityLabel, }: TransformProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function Transform({ children, transform, accessibilityLabel, }: TransformProps): import("react").JSX.Element | null;

package/lib/core/cell-output.d.ts

@@ -2,17 +2,20 @@
  * Output implementation that writes directly into CellBuffer.
  */
 import { type CellBuffer } from "./cell-buffer.js";
-import { type Clip, type OutputLike, type OutputWriteOptions } from "./output.js";
+import { type Clip, type OutputLike, type OutputWriteOptions, type RawEntry } from "./output.js";
 import { type AnsiCode } from "../types/ansi.js";
 export declare class CellOutput implements OutputLike {
     private readonly clips;
     private readonly styleIdByRef;
     private lastStyleRef;
     private lastStyleId;
+    private readonly rawEntries;
     readonly buffer: CellBuffer;
     constructor(buffer: CellBuffer);
     clip(clip: Clip): void;
     unclip(): void;
+    writeRaw(x: number, y: number, content: string): void;
+    getRawEntries(): RawEntry[];
     fill(x: number, y: number, length: number, char: string, charWidth: number, styles: AnsiCode[]): void;
     private resolveStyleId;
     private writePlainLine;

package/lib/core/cell-output.js

@@ -37,6 +37,7 @@ export class CellOutput {
     styleIdByRef = new WeakMap();
     lastStyleRef;
     lastStyleId = 0;
+    rawEntries = [];
     buffer;
     constructor(buffer) {
         this.buffer = buffer;
@@ -47,6 +48,15 @@ export class CellOutput {
     unclip() {
         this.clips.pop();
     }
+    writeRaw(x, y, content) {
+        if (!content) {
+            return;
+        }
+        this.rawEntries.push({ x, y, content });
+    }
+    getRawEntries() {
+        return this.rawEntries;
+    }
     fill(x, y, length, char, charWidth, styles) {
         if (length <= 0) {
             return;

package/lib/core/cell-renderer.d.ts

@@ -1,3 +1,4 @@
+import { type RawEntry } from "./output.js";
 import { type DOMElement } from "./dom.js";
 import { type CellBuffer } from "./cell-buffer.js";
 interface CellRendererResult {
@@ -9,6 +10,8 @@ interface CellRendererResult {
     staticOutput: string;
     /** Screen-reader text when screen-reader mode is enabled. */
     screenReaderOutput?: string;
+    /** Raw entries to write after the main output. */
+    rawEntries: RawEntry[];
 }
 /**
  * Renderer that writes interactive output into a CellBuffer.

package/lib/core/cell-renderer.js

@@ -16,7 +16,7 @@ export const cellRenderer = (node, buffer, isScreenReaderEnabled) => {
     if (!node.taffyNode) {
         buffer.resize(0, 0);
         buffer.clear();
-        return { buffer, outputHeight: 0, staticOutput: "" };
+        return { buffer, outputHeight: 0, staticOutput: "", rawEntries: [] };
     }
     if (isScreenReaderEnabled) {
         const output = renderNodeToScreenReaderOutput(node, {
@@ -34,6 +34,7 @@ export const cellRenderer = (node, buffer, isScreenReaderEnabled) => {
             outputHeight,
             staticOutput: staticOutput ? `${staticOutput}\n` : "",
             screenReaderOutput: output,
+            rawEntries: [],
         };
     }
     const layout = node.taffyNode.tree.getLayout(node.taffyNode.id);
@@ -56,5 +57,6 @@ export const cellRenderer = (node, buffer, isScreenReaderEnabled) => {
         buffer,
         outputHeight: buffer.height,
         staticOutput: staticOutput ? `${staticOutput.get().output}\n` : "",
+        rawEntries: output.getRawEntries(),
     };
 };

package/lib/core/dom.d.ts

@@ -1,6 +1,7 @@
 import { type Styles } from "./styles.js";
 import { type OutputTransformer } from "./render-node-to-output.js";
 import { TaffyNode } from "./taffy-node.js";
+import { type SizeObserver } from "./size-observer.js";
 /**
  * Interface representing a node in the Tinky tree.
  */
@@ -21,7 +22,7 @@ export type TextName = "#text";
 /**
  * Type representing element names in the Tinky DOM.
  */
-export type ElementNames = "tinky-root" | "tinky-box" | "tinky-text" | "tinky-virtual-text" | "tinky-separator";
+export type ElementNames = "tinky-root" | "tinky-box" | "tinky-text" | "tinky-virtual-text" | "tinky-separator" | "tinky-raw";
 /**
  * Union type of all possible node names.
  */
@@ -74,6 +75,8 @@ export type DOMElement = {
     onRender?: () => void;
     /** Callback to trigger an immediate render. */
     onImmediateRender?: () => void;
+    /** Set of resize observers attached to this element. */
+    resizeObservers?: Set<SizeObserver>;
 } & TinkyNode;
 /**
  * Interface representing a text node in Tinky.

package/lib/core/output.d.ts

@@ -21,6 +21,17 @@ export interface Clip {
     /** Bottom boundary (undefined for no limit). */
     y2: number | undefined;
 }
+/**
+ * Represents a raw output entry that bypasses normal text rendering.
+ */
+export interface RawEntry {
+    /** X coordinate (column) of the raw content. */
+    x: number;
+    /** Y coordinate (row) of the raw content. */
+    y: number;
+    /** Raw content to output unchanged. */
+    content: string;
+}
 /**
  * Shared write/clip/unclip surface used by render traversal.
  */
@@ -29,6 +40,8 @@ export interface OutputLike {
     clip(clip: Clip): void;
     unclip(): void;
     fill(x: number, y: number, length: number, char: string, charWidth: number, styles: AnsiCode[]): void;
+    writeRaw(x: number, y: number, content: string): void;
+    getRawEntries(): RawEntry[];
 }
 /**
  * "Virtual" output class
@@ -42,6 +55,7 @@ export declare class Output implements OutputLike {
     width: number;
     height: number;
     private readonly operations;
+    private readonly rawEntries;
     /**
      * Creates a new Output instance.
      *
@@ -68,6 +82,8 @@ export declare class Output implements OutputLike {
      */
     unclip(): void;
     fill(x: number, y: number, length: number, char: string, _charWidth: number, styles: AnsiCode[]): void;
+    writeRaw(x: number, y: number, content: string): void;
+    getRawEntries(): RawEntry[];
     /**
      * Generates the final output string and its height.
      *

package/lib/core/output.js

@@ -14,6 +14,7 @@ export class Output {
     width;
     height;
     operations = [];
+    rawEntries = [];
     /**
      * Creates a new Output instance.
      *
@@ -75,6 +76,15 @@ export class Output {
         const text = prefix + char.repeat(length) + suffix;
         this.write(x, y, text, { transformers: [] });
     }
+    writeRaw(x, y, content) {
+        if (!content) {
+            return;
+        }
+        this.rawEntries.push({ x, y, content });
+    }
+    getRawEntries() {
+        return this.rawEntries;
+    }
     /**
      * Generates the final output string and its height.
      *

package/lib/core/raw-suffix.d.ts

@@ -0,0 +1,14 @@
+import { type RawEntry } from "./output.js";
+/**
+ * Builds a raw suffix string from collected raw entries.
+ *
+ * After the main frame is written to stdout, the raw suffix moves the cursor
+ * to each raw entry's layout position and outputs its content unchanged.
+ * After all entries, the cursor is moved back to the end of the frame.
+ *
+ * @param entries - Raw entries collected during render traversal.
+ * @param frameHeight - Height of the rendered frame in rows.
+ * @param rowOffset - Rows already written above the interactive frame.
+ * @returns The raw suffix string, or empty string if no entries.
+ */
+export declare const buildRawSuffix: (entries: readonly RawEntry[], frameHeight: number, rowOffset?: number) => string;

package/lib/core/raw-suffix.js

@@ -0,0 +1,28 @@
+import ansiEscapes from "../utils/ansi-escapes.js";
+/**
+ * Builds a raw suffix string from collected raw entries.
+ *
+ * After the main frame is written to stdout, the raw suffix moves the cursor
+ * to each raw entry's layout position and outputs its content unchanged.
+ * After all entries, the cursor is moved back to the end of the frame.
+ *
+ * @param entries - Raw entries collected during render traversal.
+ * @param frameHeight - Height of the rendered frame in rows.
+ * @param rowOffset - Rows already written above the interactive frame.
+ * @returns The raw suffix string, or empty string if no entries.
+ */
+export const buildRawSuffix = (entries, frameHeight, rowOffset = 0) => {
+    if (entries.length === 0) {
+        return "";
+    }
+    const normalizedRowOffset = Math.max(0, Math.floor(rowOffset));
+    const parts = [];
+    for (const entry of entries) {
+        const x = Math.max(0, Math.floor(entry.x));
+        const y = normalizedRowOffset + Math.max(0, Math.floor(entry.y));
+        parts.push(ansiEscapes.cursorTo(x, y), entry.content);
+    }
+    const frameEndY = normalizedRowOffset + Math.max(0, Math.floor(frameHeight) - 1);
+    parts.push(ansiEscapes.cursorTo(0, frameEndY));
+    return parts.join("");
+};

package/lib/core/reconciler.js

@@ -5,6 +5,7 @@ import { createContext } from "react";
 import { createTextNode, appendChildNode, insertBeforeNode, removeChildNode, setStyle, setTextNodeValue, createNode, setAttribute, } from "./dom.js";
 import { applyStyles } from "./styles.js";
 import { process } from "../utils/node-adapter.js";
+import { removeSizeObserversInSubtree } from "./size-observer.js";
 // We need to conditionally perform devtools connection to avoid
 // accidentally breaking other third-party code.
 if (process?.env?.["DEV"] === "true") {
@@ -111,6 +112,9 @@ export const reconciler = createReconciler({
         if (hostContext.isInsideText && originalType === "tinky-box") {
             throw new Error(`<Box> can’t be nested inside <Text> component`);
         }
+        if (hostContext.isInsideText && originalType === "tinky-raw") {
+            throw new Error(`<Raw> can’t be nested inside <Text> component`);
+        }
         const type = originalType === "tinky-text" && hostContext.isInsideText
             ? "tinky-virtual-text"
             : originalType;
@@ -204,6 +208,7 @@ export const reconciler = createReconciler({
     insertInContainerBefore: insertBeforeNode,
     removeChildFromContainer(node, removeNode) {
         removeChildNode(node, removeNode);
+        removeSizeObserversInSubtree(removeNode);
         cleanupTaffyNode(removeNode.taffyNode);
     },
     commitUpdate(node, _type, oldProps, newProps) {
@@ -241,6 +246,7 @@ export const reconciler = createReconciler({
     },
     removeChild(node, removeNode) {
         removeChildNode(node, removeNode);
+        removeSizeObserversInSubtree(removeNode);
         cleanupTaffyNode(removeNode.taffyNode);
     },
     setCurrentUpdatePriority(newPriority) {

package/lib/core/render-node-to-output.js

@@ -143,6 +143,13 @@ export const renderNodeToOutput = (node, output, options) => {
             }
             return;
         }
+        if (node.nodeName === "tinky-raw") {
+            const content = node.attributes["internal_rawContent"];
+            if (content) {
+                output.writeRaw(x, y, content);
+            }
+            return;
+        }
         if (node.nodeName === "tinky-separator") {
             const separatorChar = node.attributes["internal_separatorChar"] || "─";
             const direction = node.attributes["internal_separatorDirection"] ||

package/lib/core/renderer.d.ts

@@ -1,4 +1,5 @@
 import { type DOMElement } from "./dom.js";
+import { type RawEntry } from "./output.js";
 /**
  * Interface representing the result of a render operation.
  */
@@ -15,6 +16,8 @@ interface Result {
      * The static output generated during rendering (e.g., from <Static>).
      */
     staticOutput: string;
+    /** Raw entries to write after the main output. */
+    rawEntries: RawEntry[];
 }
 /**
  * Renders the DOM tree to a string output.

package/lib/core/renderer.js

@@ -25,6 +25,7 @@ export const renderer = (node, isScreenReaderEnabled) => {
                 output,
                 outputHeight,
                 staticOutput: staticOutput ? `${staticOutput}\n` : "",
+                rawEntries: [],
             };
         }
         const layout = node.taffyNode.tree.getLayout(node.taffyNode.id);
@@ -55,11 +56,13 @@ export const renderer = (node, isScreenReaderEnabled) => {
             // Newline at the end is needed, because static output doesn't have one,
             // so interactive output will override last line of static output
             staticOutput: staticOutput ? `${staticOutput.buffer.toString()}\n` : "",
+            rawEntries: output.getRawEntries(),
         };
     }
     return {
         output: "",
         outputHeight: 0,
         staticOutput: "",
+        rawEntries: [],
     };
 };

package/lib/core/size-observer.d.ts

@@ -0,0 +1,60 @@
+import { type DOMElement, type DOMNode } from "./dom.js";
+import { type Dimension } from "../utils/dimension.js";
+/**
+ * Interface for elements returned by the SizeObserver callback.
+ */
+export interface SizeObserverEntry {
+    target: DOMElement;
+    dimension: Dimension;
+}
+/**
+ * Callback type for resize observers.
+ */
+export type SizeObserverCallback = (entries: SizeObserverEntry[], observer: SizeObserver) => void;
+/**
+ * Global registry mapping DOMElements to their registered SizeObservers.
+ */
+export declare const resizeObserverRegistry: Map<DOMElement, Set<SizeObserver>>;
+/**
+ * Implements a SizeObserver API similar to the HTML specification.
+ * It allows observing changes to the computed dimensions of Tinky DOM elements.
+ */
+export declare class SizeObserver {
+    private callback;
+    /**
+     * Creates a new SizeObserver.
+     *
+     * @param callback - The function to call when observed elements resize.
+     */
+    constructor(callback: SizeObserverCallback);
+    /**
+     * Starts observing the specified element.
+     *
+     * @param target - The element to observe.
+     */
+    observe(target: DOMElement): void;
+    /**
+     * Stops observing the specified element.
+     *
+     * @param target - The element to stop observing.
+     */
+    unobserve(target: DOMElement): void;
+    /**
+     * Stops observing all elements.
+     */
+    disconnect(): void;
+    /** @internal */
+    _invokeCallback(entries: SizeObserverEntry[]): void;
+}
+/**
+ * Removes all resize observers from a node and its descendants.
+ * Called during mutation cleanup to prevent stale observer entries.
+ *
+ * @param node - Root of the removed subtree.
+ */
+export declare const removeSizeObserversInSubtree: (node: DOMNode) => void;
+/**
+ * Notifies all registered resize observers of their current dimensions.
+ * Called by the Tinky instance after each layout computation pass.
+ */
+export declare const notifySizeObservers: () => void;

package/lib/core/size-observer.js

@@ -0,0 +1,133 @@
+/**
+ * Global registry mapping DOMElements to their registered SizeObservers.
+ */
+export const resizeObserverRegistry = new Map();
+/**
+ * Implements a SizeObserver API similar to the HTML specification.
+ * It allows observing changes to the computed dimensions of Tinky DOM elements.
+ */
+export class SizeObserver {
+    callback;
+    /**
+     * Creates a new SizeObserver.
+     *
+     * @param callback - The function to call when observed elements resize.
+     */
+    constructor(callback) {
+        this.callback = callback;
+    }
+    /**
+     * Starts observing the specified element.
+     *
+     * @param target - The element to observe.
+     */
+    observe(target) {
+        if (!target.resizeObservers) {
+            target.resizeObservers = new Set();
+        }
+        target.resizeObservers.add(this);
+        let observers = resizeObserverRegistry.get(target);
+        if (!observers) {
+            observers = new Set();
+            resizeObserverRegistry.set(target, observers);
+        }
+        observers.add(this);
+    }
+    /**
+     * Stops observing the specified element.
+     *
+     * @param target - The element to stop observing.
+     */
+    unobserve(target) {
+        target.resizeObservers?.delete(this);
+        if (target.resizeObservers?.size === 0) {
+            target.resizeObservers = undefined;
+        }
+        const observers = resizeObserverRegistry.get(target);
+        if (observers) {
+            observers.delete(this);
+            if (observers.size === 0) {
+                resizeObserverRegistry.delete(target);
+            }
+        }
+    }
+    /**
+     * Stops observing all elements.
+     */
+    disconnect() {
+        for (const [target, observers] of resizeObserverRegistry.entries()) {
+            if (observers.has(this)) {
+                this.unobserve(target);
+            }
+        }
+    }
+    /** @internal */
+    _invokeCallback(entries) {
+        this.callback(entries, this);
+    }
+}
+/**
+ * Removes all resize observers from a node and its descendants.
+ * Called during mutation cleanup to prevent stale observer entries.
+ *
+ * @param node - Root of the removed subtree.
+ */
+export const removeSizeObserversInSubtree = (node) => {
+    if (node.nodeName === "#text") {
+        return;
+    }
+    if (node.resizeObservers) {
+        // Collect all observers to avoid disconnecting while iterating
+        const observers = Array.from(node.resizeObservers);
+        for (const observer of observers) {
+            observer.unobserve(node);
+        }
+        node.resizeObservers = undefined;
+    }
+    // Not strictly necessary here since unobserve handles it,
+    // but good for completeness in case it fell through
+    resizeObserverRegistry.delete(node);
+    for (const childNode of node.childNodes) {
+        removeSizeObserversInSubtree(childNode);
+    }
+};
+/**
+ * Notifies all registered resize observers of their current dimensions.
+ * Called by the Tinky instance after each layout computation pass.
+ */
+export const notifySizeObservers = () => {
+    const entriesByObserver = new Map();
+    for (const [node, observers] of resizeObserverRegistry.entries()) {
+        if (!node.taffyNode) {
+            continue;
+        }
+        let layout;
+        try {
+            layout = node.taffyNode.tree.getLayout(node.taffyNode.id);
+        }
+        catch {
+            // Node was removed from the tree before passive effect cleanup ran.
+            const nodeObservers = Array.from(observers);
+            for (const observer of nodeObservers) {
+                observer.unobserve(node);
+            }
+            continue;
+        }
+        const dimension = {
+            width: layout?.width ?? 0,
+            height: layout?.height ?? 0,
+        };
+        const entry = { target: node, dimension };
+        for (const observer of observers) {
+            let entries = entriesByObserver.get(observer);
+            if (!entries) {
+                entries = [];
+                entriesByObserver.set(observer, entries);
+            }
+            entries.push(entry);
+        }
+    }
+    for (const [observer, entries] of entriesByObserver.entries()) {
+        observer._invokeCallback(entries);
+    }
+};

package/lib/core/tinky.d.ts

@@ -101,6 +101,12 @@ export declare class Tinky {
     private readonly rootNode;
     /** Full static output for debug mode. */
     private fullStaticOutput;
+    /** Raw entries from the last rendered frame. */
+    private lastRawEntries;
+    /** Height of the last frame used to place raw output. */
+    private lastRawFrameHeight;
+    /** Raw suffix from the last rendered frame. */
+    private lastRawSuffix;
     /** Promise that resolves when the app exits. */
     private exitPromise?;
     /** Function to restore console after patching. */
@@ -160,6 +166,10 @@ export declare class Tinky {
      * the next render cycle.
      */
     private swapRunBuffers;
+    private updateRawState;
+    private clearRawState;
+    private buildRawSuffix;
+    private writeRawSuffix;
     private redrawRunBuffer;
     /**
      * Renders the given React node.

package/lib/core/tinky.js

@@ -11,6 +11,7 @@ import wrapAnsi from "wrap-ansi";
 import { reconciler } from "./reconciler.js";
 import { renderer } from "./renderer.js";
 import { cellRenderer } from "./cell-renderer.js";
+import { buildRawSuffix } from "./raw-suffix.js";
 import * as dom from "./dom.js";
 import { logUpdate } from "./log-update.js";
 import { cellLogUpdateRun, } from "./cell-log-update-run.js";
@@ -19,9 +20,19 @@ import { App } from "../components/App.js";
 import { AccessibilityContext } from "../contexts/AccessibilityContext.js";
 import { CellBuffer, StyleRegistry } from "./cell-buffer.js";
 import { normalizeIncrementalRendering, } from "./incremental-rendering.js";
+import { notifySizeObservers } from "./size-observer.js";
 const noop = () => {
     // no-op
 };
+const countOutputRows = (output) => {
+    let rows = 0;
+    for (const character of output) {
+        if (character === "\n") {
+            rows++;
+        }
+    }
+    return rows;
+};
 /**
  * Tinky core class responsible for managing the React tree rendering,
  * lifecycle, and terminal output.
@@ -49,6 +60,12 @@ export class Tinky {
     rootNode;
     /** Full static output for debug mode. */
     fullStaticOutput;
+    /** Raw entries from the last rendered frame. */
+    lastRawEntries;
+    /** Height of the last frame used to place raw output. */
+    lastRawFrameHeight;
+    /** Raw suffix from the last rendered frame. */
+    lastRawSuffix;
     /** Promise that resolves when the app exits. */
     exitPromise;
     /** Function to restore console after patching. */
@@ -131,6 +148,9 @@ export class Tinky {
         // that it's rerendered every time, not just new static parts, like in
         // non-debug mode
         this.fullStaticOutput = "";
+        this.lastRawEntries = [];
+        this.lastRawFrameHeight = 0;
+        this.lastRawSuffix = "";
         this.container = reconciler.createContainer(this.rootNode, LegacyRoot, null, false, null, "id", noop, noop, noop, noop, null);
         // Unmount when process exits
         this.unsubscribeExit = onExit(() => {
@@ -222,6 +242,8 @@ export class Tinky {
             }
             return context.measureFunc(availableSpace.width);
         });
+        // Notify all registered resize observers of their current dimensions.
+        notifySizeObservers();
     };
     /**
      * Performs the render operation.
@@ -233,20 +255,26 @@ export class Tinky {
         }
         if (this.usesRunIncrementalRendering && this.backBuffer) {
             const startTime = performance.now();
-            const { buffer, outputHeight, staticOutput } = cellRenderer(this.rootNode, this.backBuffer, false);
+            const { buffer, outputHeight, staticOutput, rawEntries } = cellRenderer(this.rootNode, this.backBuffer, false);
             this.options.onRender?.({ renderTime: performance.now() - startTime });
             const hasStaticOutput = staticOutput && staticOutput !== "\n";
             if (hasStaticOutput) {
                 this.fullStaticOutput += staticOutput;
             }
-            if (this.options.stdout.rows &&
-                this.lastOutputHeight >= this.options.stdout.rows) {
+            const rawSuffix = this.updateRawState(rawEntries, outputHeight);
+            // Raw content uses absolute CUP positioning, so redraw from a known
+            // static prefix before writing the raw suffix.
+            const needsClearTerminal = rawSuffix.length > 0 ||
+                Boolean(this.options.stdout.rows &&
+                    this.lastOutputHeight >= this.options.stdout.rows);
+            if (needsClearTerminal) {
                 const output = buffer.toString();
                 this.options.stdout.write(ansiEscapes.clearTerminal + this.fullStaticOutput + output);
                 this.lastOutput = output;
                 this.lastOutputHeight = outputHeight;
                 this.cellLog?.sync(buffer);
                 this.swapRunBuffers();
+                this.writeRawSuffix();
                 return;
             }
             if (hasStaticOutput) {
@@ -266,7 +294,7 @@ export class Tinky {
             return;
         }
         const startTime = performance.now();
-        const { output, outputHeight, staticOutput } = renderer(this.rootNode, this.isScreenReaderEnabled);
+        const { output, outputHeight, staticOutput, rawEntries } = renderer(this.rootNode, this.isScreenReaderEnabled);
         this.options.onRender?.({ renderTime: performance.now() - startTime });
         // If <Static> output isn't empty, it means new children have been added to
         // it
@@ -275,10 +303,13 @@ export class Tinky {
             if (hasStaticOutput) {
                 this.fullStaticOutput += staticOutput;
             }
+            this.updateRawState(rawEntries, outputHeight);
             this.options.stdout.write(this.fullStaticOutput + output);
+            this.writeRawSuffix();
             return;
         }
         if (this.isCI) {
+            this.clearRawState();
             if (hasStaticOutput) {
                 this.options.stdout.write(staticOutput);
             }
@@ -287,6 +318,7 @@ export class Tinky {
             return;
         }
         if (this.isScreenReaderEnabled) {
+            this.clearRawState();
             if (hasStaticOutput) {
                 // We need to erase the main output before writing new static output
                 const erase = this.lastOutputHeight > 0
@@ -322,12 +354,18 @@ export class Tinky {
         if (hasStaticOutput) {
             this.fullStaticOutput += staticOutput;
         }
-        if (this.options.stdout.rows &&
-            this.lastOutputHeight >= this.options.stdout.rows) {
+        const rawSuffix = this.updateRawState(rawEntries, outputHeight);
+        // Raw content uses absolute CUP positioning, so redraw from a known static
+        // prefix before writing the raw suffix.
+        const needsClearTerminal = rawSuffix.length > 0 ||
+            Boolean(this.options.stdout.rows &&
+                this.lastOutputHeight >= this.options.stdout.rows);
+        if (needsClearTerminal) {
             this.options.stdout.write(ansiEscapes.clearTerminal + this.fullStaticOutput + output);
             this.lastOutput = output;
             this.lastOutputHeight = outputHeight;
             this.log.sync(output);
+            this.writeRawSuffix();
             return;
         }
         // To ensure static output is cleanly rendered before main output, clear
@@ -354,6 +392,28 @@ export class Tinky {
         this.frontBuffer = this.backBuffer;
         this.backBuffer = previous;
     }
+    updateRawState(rawEntries, outputHeight) {
+        this.lastRawEntries = rawEntries;
+        this.lastRawFrameHeight = outputHeight;
+        this.lastRawSuffix = this.buildRawSuffix();
+        return this.lastRawSuffix;
+    }
+    clearRawState() {
+        this.lastRawEntries = [];
+        this.lastRawFrameHeight = 0;
+        this.lastRawSuffix = "";
+    }
+    buildRawSuffix(extraRowOffset = 0) {
+        return buildRawSuffix(this.lastRawEntries, this.lastRawFrameHeight, countOutputRows(this.fullStaticOutput) + extraRowOffset);
+    }
+    writeRawSuffix(prefix = "") {
+        const rawSuffix = prefix
+            ? this.buildRawSuffix(countOutputRows(prefix))
+            : this.lastRawSuffix;
+        if (rawSuffix) {
+            this.options.stdout.write(rawSuffix);
+        }
+    }
     redrawRunBuffer() {
         if (!this.frontBuffer || !this.cellLog) {
             return;
@@ -361,6 +421,7 @@ export class Tinky {
         this.cellLog(this.frontBuffer, this.frontBuffer, { forceFull: true });
         this.lastOutput = this.frontBuffer.toString();
         this.lastOutputHeight = this.frontBuffer.height;
+        this.writeRawSuffix();
     }
     /**
      * Renders the given React node.
@@ -383,6 +444,7 @@ export class Tinky {
         }
         if (this.options.debug) {
             this.options.stdout.write(data + this.fullStaticOutput + this.lastOutput);
+            this.writeRawSuffix(data);
             return;
         }
         if (this.isCI) {
@@ -398,6 +460,7 @@ export class Tinky {
         this.log.clear();
         this.options.stdout.write(data);
         this.log(this.lastOutput);
+        this.writeRawSuffix(data);
     }
     /**
      * Writes data to stderr.
@@ -411,6 +474,7 @@ export class Tinky {
         if (this.options.debug) {
             this.options.stderr.write(data);
             this.options.stdout.write(this.fullStaticOutput + this.lastOutput);
+            this.writeRawSuffix(data);
             return;
         }
         if (this.isCI) {
@@ -426,6 +490,7 @@ export class Tinky {
         this.log.clear();
         this.options.stderr.write(data);
         this.log(this.lastOutput);
+        this.writeRawSuffix(data);
     }
     /**
      * Unmounts the Tinky app.

package/lib/hooks/use-size-observer.d.ts

@@ -0,0 +1,44 @@
+import { type DOMElement } from "../core/dom.js";
+/**
+ * Options for the `useSizeObserver` hook.
+ */
+export interface SizeObserverOptions {
+    /**
+     * Enable or disable the size observer.
+     *
+     * @defaultValue true
+     */
+    isActive?: boolean;
+}
+/**
+ * Hook that observes the computed layout dimensions of a `<Box>` element
+ * and triggers a re-render whenever its size changes.
+ *
+ * The observer is registered in a global resize observer registry that is
+ * invoked by the Tinky core after each layout computation pass. This means
+ * size changes are detected regardless of which component caused the
+ * re-render — including sibling updates and terminal resize events.
+ *
+ * Multiple observers can be attached to the same element.
+ *
+ * This is similar to HTML's `SizeObserver` API.
+ *
+ * @example
+ * ```tsx
+ * import { Box, Text, useSizeObserver } from 'tinky';
+ *
+ * function MyComponent() {
+ *   const [ref, width, height] = useSizeObserver();
+ *
+ *   return (
+ *     <Box ref={ref} width="50%" height={10}>
+ *       <Text>Size: {width}x{height}</Text>
+ *     </Box>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - Configuration options.
+ * @returns A tuple containing `[refCallback, width, height]`. Attach `refCallback` to a `<Box>` element.
+ */
+export declare const useSizeObserver: (options?: SizeObserverOptions) => [(node: DOMElement | null) => void, number, number];

package/lib/hooks/use-size-observer.js

@@ -0,0 +1,70 @@
+import { useCallback, useRef, useState } from "react";
+import { measureElement } from "../utils/measure-element.js";
+import { SizeObserver } from "../core/size-observer.js";
+import { reconciler } from "../core/reconciler.js";
+/**
+ * Hook that observes the computed layout dimensions of a `<Box>` element
+ * and triggers a re-render whenever its size changes.
+ *
+ * The observer is registered in a global resize observer registry that is
+ * invoked by the Tinky core after each layout computation pass. This means
+ * size changes are detected regardless of which component caused the
+ * re-render — including sibling updates and terminal resize events.
+ *
+ * Multiple observers can be attached to the same element.
+ *
+ * This is similar to HTML's `SizeObserver` API.
+ *
+ * @example
+ * ```tsx
+ * import { Box, Text, useSizeObserver } from 'tinky';
+ *
+ * function MyComponent() {
+ *   const [ref, width, height] = useSizeObserver();
+ *
+ *   return (
+ *     <Box ref={ref} width="50%" height={10}>
+ *       <Text>Size: {width}x{height}</Text>
+ *     </Box>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - Configuration options.
+ * @returns A tuple containing `[refCallback, width, height]`. Attach `refCallback` to a `<Box>` element.
+ */
+export const useSizeObserver = (options = {}) => {
+    const [size, setSize] = useState({ width: 0, height: 0 });
+    const observerRef = useRef(null);
+    const prevSize = useRef({ width: 0, height: 0 });
+    const { isActive = true } = options;
+    const callbackRef = useCallback((node) => {
+        // Cleanup previous observer
+        if (observerRef.current) {
+            observerRef.current.disconnect();
+            observerRef.current = null;
+        }
+        // If active and node is attached, start observing
+        if (isActive && node) {
+            const callback = (entries) => {
+                if (entries.length === 0)
+                    return;
+                const { dimension } = entries[0];
+                if (dimension.width !== prevSize.current.width ||
+                    dimension.height !== prevSize.current.height) {
+                    prevSize.current = { ...dimension };
+                    reconciler.batchedUpdates(() => {
+                        setSize({ ...dimension });
+                    }, null);
+                }
+            };
+            const observer = new SizeObserver(callback);
+            // Read initial dimensions
+            const initial = measureElement(node);
+            callback([{ target: node, dimension: initial }]);
+            observer.observe(node);
+            observerRef.current = observer;
+        }
+    }, [isActive]);
+    return [callbackRef, size.width, size.height];
+};

package/lib/index.d.ts

@@ -12,6 +12,7 @@ export { Transform, type TransformProps } from "./components/Transform.js";
 export { Newline, type NewlineProps } from "./components/Newline.js";
 export { Separator, type SeparatorProps } from "./components/Separator.js";
 export { Spacer } from "./components/Spacer.js";
+export { Raw, type RawProps } from "./components/Raw.js";
 export { useInput, type InputHandler, type InputOptions, type Key, } from "./hooks/use-input.js";
 export { useApp } from "./hooks/use-app.js";
 export { useStdin } from "./hooks/use-stdin.js";
@@ -21,6 +22,7 @@ export { useFocus, type FocusOptions, type FocusState, } from "./hooks/use-focus
 export { useFocusManager, type FocusManager, } from "./hooks/use-focus-manager.js";
 export { useIsScreenReaderEnabled } from "./hooks/use-is-screen-reader-enabled.js";
 export { measureElement } from "./utils/measure-element.js";
+export { useSizeObserver, type SizeObserverOptions, } from "./hooks/use-size-observer.js";
 export { type Dimension } from "./utils/dimension.js";
 export { type ForegroundColorName } from "./utils/colorize.js";
 export { applyTextStyles, type TextStyles } from "./utils/apply-text-styles.js";

package/lib/index.js

@@ -10,6 +10,7 @@ export { Transform } from "./components/Transform.js";
 export { Newline } from "./components/Newline.js";
 export { Separator } from "./components/Separator.js";
 export { Spacer } from "./components/Spacer.js";
+export { Raw } from "./components/Raw.js";
 export { useInput, } from "./hooks/use-input.js";
 export { useApp } from "./hooks/use-app.js";
 export { useStdin } from "./hooks/use-stdin.js";
@@ -19,6 +20,7 @@ export { useFocus, } from "./hooks/use-focus.js";
 export { useFocusManager, } from "./hooks/use-focus-manager.js";
 export { useIsScreenReaderEnabled } from "./hooks/use-is-screen-reader-enabled.js";
 export { measureElement } from "./utils/measure-element.js";
+export { useSizeObserver, } from "./hooks/use-size-observer.js";
 export { applyTextStyles } from "./utils/apply-text-styles.js";
 export { boxStyles } from "./core/box-styles.js";
 export { EventEmitter } from "./utils/event-emitter.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinky",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "React for CLIs, re-imagined with the Taffy engine",
   "keywords": [
     "react",