@glassly/engine 0.1.0-dev.0

package/build/utils/display/helpers/DisplayHelpers.js

@@ -0,0 +1,312 @@
+/**
+ * Optional helper utilities for common display operations.
+ * Built on top of TextMeasurer and TextWrapper for convenience.
+ */
+export class DisplayHelpers {
+    measurer;
+    wrapper;
+    profile;
+    constructor(measurer, wrapper) {
+        this.measurer = measurer;
+        this.wrapper = wrapper;
+        this.profile = measurer.getProfile();
+    }
+    /**
+     * Truncate lines array to max count.
+     *
+     * @param lines - Array of lines
+     * @param maxLines - Maximum lines to keep
+     * @param fromEnd - If true, keep last N lines; if false, keep first N (default: false)
+     * @returns Truncated lines array
+     */
+    truncateToLines(lines, maxLines, fromEnd = false) {
+        if (lines.length <= maxLines) {
+            return lines;
+        }
+        if (fromEnd) {
+            // Keep the last N lines (most recent)
+            return lines.slice(-maxLines);
+        }
+        else {
+            // Keep the first N lines
+            return lines.slice(0, maxLines);
+        }
+    }
+    /**
+     * Truncate text to fit within pixel width, adding ellipsis if needed.
+     *
+     * @param text - Text to truncate
+     * @param maxWidthPx - Maximum width in pixels
+     * @param ellipsis - Ellipsis string (default: '...')
+     * @returns Truncation result
+     */
+    truncateWithEllipsis(text, maxWidthPx, ellipsis = "...") {
+        const width = maxWidthPx ?? this.profile.displayWidthPx;
+        const textWidth = this.measurer.measureText(text);
+        if (textWidth <= width) {
+            return {
+                text,
+                wasTruncated: false,
+                widthPx: textWidth,
+                originalLength: text.length,
+                truncatedLength: text.length,
+            };
+        }
+        const ellipsisWidth = this.measurer.measureText(ellipsis);
+        const targetWidth = width - ellipsisWidth;
+        // Find how many characters fit
+        let truncated = "";
+        let currentWidth = 0;
+        for (const char of text) {
+            const charWidth = this.measurer.measureChar(char);
+            if (currentWidth + charWidth > targetWidth) {
+                break;
+            }
+            truncated += char;
+            currentWidth += charWidth;
+        }
+        // Trim trailing whitespace before ellipsis
+        truncated = truncated.trimEnd();
+        const finalText = truncated + ellipsis;
+        return {
+            text: finalText,
+            wasTruncated: true,
+            widthPx: this.measurer.measureText(finalText),
+            originalLength: text.length,
+            truncatedLength: truncated.length,
+        };
+    }
+    /**
+     * Estimate how many lines text will need without fully wrapping.
+     * This is a quick estimate based on average character width.
+     *
+     * @param text - Text to estimate
+     * @param maxWidthPx - Optional width override
+     * @returns Estimated line count
+     */
+    estimateLineCount(text, maxWidthPx) {
+        if (!text)
+            return 1;
+        const width = maxWidthPx ?? this.profile.displayWidthPx;
+        const textWidth = this.measurer.measureText(text);
+        // Account for explicit newlines
+        const newlineCount = (text.match(/\n/g) || []).length;
+        // Estimate wrapped lines
+        const wrappedLines = Math.ceil(textWidth / width);
+        return wrappedLines + newlineCount;
+    }
+    /**
+     * Wrap and truncate text to fit screen in one call.
+     *
+     * @param text - Text to fit
+     * @param options - Wrap options
+     * @returns Lines that fit on screen
+     */
+    fitToScreen(text, options) {
+        const result = this.wrapper.wrap(text, options);
+        return result.lines.slice(0, this.profile.maxLines);
+    }
+    /**
+     * Wrap text and paginate into screen-sized pages.
+     *
+     * @param text - Text to paginate
+     * @param options - Wrap options (maxLines will be used as page size)
+     * @returns Array of pages
+     */
+    paginate(text, options) {
+        // Wrap without line limit to get all lines
+        const wrapResult = this.wrapper.wrap(text, {
+            ...options,
+            maxLines: Infinity,
+            maxBytes: Infinity,
+        });
+        const linesPerPage = options?.maxLines ?? this.profile.maxLines;
+        const allLines = wrapResult.lines;
+        const pages = [];
+        for (let i = 0; i < allLines.length; i += linesPerPage) {
+            const pageLines = allLines.slice(i, i + linesPerPage);
+            const pageNumber = Math.floor(i / linesPerPage) + 1;
+            const totalPages = Math.ceil(allLines.length / linesPerPage);
+            pages.push({
+                lines: pageLines,
+                pageNumber,
+                totalPages,
+                isFirst: pageNumber === 1,
+                isLast: pageNumber === totalPages,
+            });
+        }
+        return pages.length > 0
+            ? pages
+            : [
+                {
+                    lines: [""],
+                    pageNumber: 1,
+                    totalPages: 1,
+                    isFirst: true,
+                    isLast: true,
+                },
+            ];
+    }
+    /**
+     * Calculate UTF-8 byte size of text.
+     *
+     * @param text - Text to measure
+     * @returns Byte size
+     */
+    calculateByteSize(text) {
+        return this.measurer.getByteSize(text);
+    }
+    /**
+     * Check if text exceeds byte limit.
+     *
+     * @param text - Text to check
+     * @param maxBytes - Optional override (defaults to profile)
+     * @returns true if exceeds limit
+     */
+    exceedsByteLimit(text, maxBytes) {
+        const limit = maxBytes ?? this.profile.maxPayloadBytes;
+        return this.calculateByteSize(text) > limit;
+    }
+    /**
+     * Split text into BLE-safe chunks.
+     * Tries to split at word/line boundaries when possible.
+     *
+     * @param text - Text to chunk
+     * @param chunkSize - Optional override (defaults to profile)
+     * @returns Array of chunks
+     */
+    splitIntoChunks(text, chunkSize) {
+        const size = chunkSize ?? this.profile.bleChunkSize;
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(text);
+        if (bytes.length <= size) {
+            return [
+                {
+                    text,
+                    index: 0,
+                    totalChunks: 1,
+                    bytes: bytes.length,
+                },
+            ];
+        }
+        const chunks = [];
+        let offset = 0;
+        while (offset < bytes.length) {
+            let endOffset = Math.min(offset + size, bytes.length);
+            // Back off to avoid splitting a multi-byte character
+            if (endOffset < bytes.length) {
+                // Find a valid UTF-8 boundary
+                while (endOffset > offset && (bytes[endOffset] & 0xc0) === 0x80) {
+                    endOffset--;
+                }
+                // Try to find a good break point (space or newline)
+                let breakPoint = endOffset;
+                for (let i = endOffset - 1; i > offset + size / 2; i--) {
+                    if (bytes[i] === 0x20 || bytes[i] === 0x0a) {
+                        // space or newline
+                        breakPoint = i + 1;
+                        break;
+                    }
+                }
+                if (breakPoint > offset) {
+                    endOffset = breakPoint;
+                }
+            }
+            const chunkBytes = bytes.slice(offset, endOffset);
+            const chunkText = new TextDecoder().decode(chunkBytes);
+            chunks.push({
+                text: chunkText,
+                index: chunks.length,
+                totalChunks: 0, // Will be set after loop
+                bytes: chunkBytes.length,
+            });
+            offset = endOffset;
+        }
+        // Update total chunks count
+        for (const chunk of chunks) {
+            chunk.totalChunks = chunks.length;
+        }
+        return chunks;
+    }
+    /**
+     * Calculate line utilization statistics.
+     *
+     * @param result - Wrap result to analyze
+     * @returns Utilization statistics
+     */
+    calculateUtilization(result) {
+        if (result.lines.length === 0 || result.lineMetrics.length === 0) {
+            return {
+                averageUtilization: 0,
+                minUtilization: 0,
+                maxUtilization: 0,
+                totalWastedPx: 0,
+            };
+        }
+        const maxWidthPx = this.profile.displayWidthPx;
+        let totalUtilization = 0;
+        let minUtilization = 100;
+        let maxUtilization = 0;
+        let totalWastedPx = 0;
+        for (const metric of result.lineMetrics) {
+            totalUtilization += metric.utilizationPercent;
+            minUtilization = Math.min(minUtilization, metric.utilizationPercent);
+            maxUtilization = Math.max(maxUtilization, metric.utilizationPercent);
+            totalWastedPx += maxWidthPx - metric.widthPx;
+        }
+        return {
+            averageUtilization: Math.round(totalUtilization / result.lineMetrics.length),
+            minUtilization,
+            maxUtilization,
+            totalWastedPx,
+        };
+    }
+    /**
+     * Pad lines array to exact count with empty strings.
+     *
+     * @param lines - Lines to pad
+     * @param targetCount - Target number of lines
+     * @param padAtEnd - If true, pad at end; if false, pad at start (default: true)
+     * @returns Padded lines array
+     */
+    padToLineCount(lines, targetCount, padAtEnd = true) {
+        if (lines.length >= targetCount) {
+            return lines.slice(0, targetCount);
+        }
+        const padding = Array(targetCount - lines.length).fill("");
+        if (padAtEnd) {
+            return [...lines, ...padding];
+        }
+        else {
+            return [...padding, ...lines];
+        }
+    }
+    /**
+     * Join lines with newlines for display.
+     *
+     * @param lines - Lines to join
+     * @returns Joined string
+     */
+    joinLines(lines) {
+        return lines.join("\n");
+    }
+    /**
+     * Get the measurer instance.
+     */
+    getMeasurer() {
+        return this.measurer;
+    }
+    /**
+     * Get the wrapper instance.
+     */
+    getWrapper() {
+        return this.wrapper;
+    }
+    /**
+     * Get the display profile.
+     */
+    getProfile() {
+        return this.profile;
+    }
+}
+//# sourceMappingURL=DisplayHelpers.js.map

package/build/utils/display/helpers/DisplayHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DisplayHelpers.js","sourceRoot":"","sources":["../../../../src/utils/display/helpers/DisplayHelpers.ts"],"names":[],"mappings":"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","sourcesContent":["import type {DisplayProfile} from \"../profiles/types\"\nimport {TextMeasurer} from \"../measurer/TextMeasurer\"\nimport {TextWrapper} from \"../wrapper/TextWrapper\"\nimport type {WrapOptions, WrapResult} from \"../wrapper/types\"\n\n/**\n * Truncation result with metadata.\n */\nexport interface TruncateResult {\n  /** The truncated text */\n  text: string\n  /** Whether text was truncated */\n  wasTruncated: boolean\n  /** Width in pixels of truncated text */\n  widthPx: number\n  /** Original text length */\n  originalLength: number\n  /** Truncated text length */\n  truncatedLength: number\n}\n\n/**\n * Page result for pagination.\n */\nexport interface Page {\n  /** Lines on this page */\n  lines: string[]\n  /** Page number (1-indexed) */\n  pageNumber: number\n  /** Total number of pages */\n  totalPages: number\n  /** Whether this is the first page */\n  isFirst: boolean\n  /** Whether this is the last page */\n  isLast: boolean\n}\n\n/**\n * Chunk result for BLE transmission.\n */\nexport interface Chunk {\n  /** The chunk text */\n  text: string\n  /** Chunk index (0-indexed) */\n  index: number\n  /** Total number of chunks */\n  totalChunks: number\n  /** Byte size of this chunk */\n  bytes: number\n}\n\n/**\n * Optional helper utilities for common display operations.\n * Built on top of TextMeasurer and TextWrapper for convenience.\n */\nexport class DisplayHelpers {\n  private readonly measurer: TextMeasurer\n  private readonly wrapper: TextWrapper\n  private readonly profile: DisplayProfile\n\n  constructor(measurer: TextMeasurer, wrapper: TextWrapper) {\n    this.measurer = measurer\n    this.wrapper = wrapper\n    this.profile = measurer.getProfile()\n  }\n\n  /**\n   * Truncate lines array to max count.\n   *\n   * @param lines - Array of lines\n   * @param maxLines - Maximum lines to keep\n   * @param fromEnd - If true, keep last N lines; if false, keep first N (default: false)\n   * @returns Truncated lines array\n   */\n  truncateToLines(lines: string[], maxLines: number, fromEnd: boolean = false): string[] {\n    if (lines.length <= maxLines) {\n      return lines\n    }\n\n    if (fromEnd) {\n      // Keep the last N lines (most recent)\n      return lines.slice(-maxLines)\n    } else {\n      // Keep the first N lines\n      return lines.slice(0, maxLines)\n    }\n  }\n\n  /**\n   * Truncate text to fit within pixel width, adding ellipsis if needed.\n   *\n   * @param text - Text to truncate\n   * @param maxWidthPx - Maximum width in pixels\n   * @param ellipsis - Ellipsis string (default: '...')\n   * @returns Truncation result\n   */\n  truncateWithEllipsis(text: string, maxWidthPx?: number, ellipsis: string = \"...\"): TruncateResult {\n    const width = maxWidthPx ?? this.profile.displayWidthPx\n    const textWidth = this.measurer.measureText(text)\n\n    if (textWidth <= width) {\n      return {\n        text,\n        wasTruncated: false,\n        widthPx: textWidth,\n        originalLength: text.length,\n        truncatedLength: text.length,\n      }\n    }\n\n    const ellipsisWidth = this.measurer.measureText(ellipsis)\n    const targetWidth = width - ellipsisWidth\n\n    // Find how many characters fit\n    let truncated = \"\"\n    let currentWidth = 0\n\n    for (const char of text) {\n      const charWidth = this.measurer.measureChar(char)\n      if (currentWidth + charWidth > targetWidth) {\n        break\n      }\n      truncated += char\n      currentWidth += charWidth\n    }\n\n    // Trim trailing whitespace before ellipsis\n    truncated = truncated.trimEnd()\n    const finalText = truncated + ellipsis\n\n    return {\n      text: finalText,\n      wasTruncated: true,\n      widthPx: this.measurer.measureText(finalText),\n      originalLength: text.length,\n      truncatedLength: truncated.length,\n    }\n  }\n\n  /**\n   * Estimate how many lines text will need without fully wrapping.\n   * This is a quick estimate based on average character width.\n   *\n   * @param text - Text to estimate\n   * @param maxWidthPx - Optional width override\n   * @returns Estimated line count\n   */\n  estimateLineCount(text: string, maxWidthPx?: number): number {\n    if (!text) return 1\n\n    const width = maxWidthPx ?? this.profile.displayWidthPx\n    const textWidth = this.measurer.measureText(text)\n\n    // Account for explicit newlines\n    const newlineCount = (text.match(/\\n/g) || []).length\n\n    // Estimate wrapped lines\n    const wrappedLines = Math.ceil(textWidth / width)\n\n    return wrappedLines + newlineCount\n  }\n\n  /**\n   * Wrap and truncate text to fit screen in one call.\n   *\n   * @param text - Text to fit\n   * @param options - Wrap options\n   * @returns Lines that fit on screen\n   */\n  fitToScreen(text: string, options?: WrapOptions): string[] {\n    const result = this.wrapper.wrap(text, options)\n    return result.lines.slice(0, this.profile.maxLines)\n  }\n\n  /**\n   * Wrap text and paginate into screen-sized pages.\n   *\n   * @param text - Text to paginate\n   * @param options - Wrap options (maxLines will be used as page size)\n   * @returns Array of pages\n   */\n  paginate(text: string, options?: WrapOptions): Page[] {\n    // Wrap without line limit to get all lines\n    const wrapResult = this.wrapper.wrap(text, {\n      ...options,\n      maxLines: Infinity,\n      maxBytes: Infinity,\n    })\n\n    const linesPerPage = options?.maxLines ?? this.profile.maxLines\n    const allLines = wrapResult.lines\n    const pages: Page[] = []\n\n    for (let i = 0; i < allLines.length; i += linesPerPage) {\n      const pageLines = allLines.slice(i, i + linesPerPage)\n      const pageNumber = Math.floor(i / linesPerPage) + 1\n      const totalPages = Math.ceil(allLines.length / linesPerPage)\n\n      pages.push({\n        lines: pageLines,\n        pageNumber,\n        totalPages,\n        isFirst: pageNumber === 1,\n        isLast: pageNumber === totalPages,\n      })\n    }\n\n    return pages.length > 0\n      ? pages\n      : [\n          {\n            lines: [\"\"],\n            pageNumber: 1,\n            totalPages: 1,\n            isFirst: true,\n            isLast: true,\n          },\n        ]\n  }\n\n  /**\n   * Calculate UTF-8 byte size of text.\n   *\n   * @param text - Text to measure\n   * @returns Byte size\n   */\n  calculateByteSize(text: string): number {\n    return this.measurer.getByteSize(text)\n  }\n\n  /**\n   * Check if text exceeds byte limit.\n   *\n   * @param text - Text to check\n   * @param maxBytes - Optional override (defaults to profile)\n   * @returns true if exceeds limit\n   */\n  exceedsByteLimit(text: string, maxBytes?: number): boolean {\n    const limit = maxBytes ?? this.profile.maxPayloadBytes\n    return this.calculateByteSize(text) > limit\n  }\n\n  /**\n   * Split text into BLE-safe chunks.\n   * Tries to split at word/line boundaries when possible.\n   *\n   * @param text - Text to chunk\n   * @param chunkSize - Optional override (defaults to profile)\n   * @returns Array of chunks\n   */\n  splitIntoChunks(text: string, chunkSize?: number): Chunk[] {\n    const size = chunkSize ?? this.profile.bleChunkSize\n    const encoder = new TextEncoder()\n    const bytes = encoder.encode(text)\n\n    if (bytes.length <= size) {\n      return [\n        {\n          text,\n          index: 0,\n          totalChunks: 1,\n          bytes: bytes.length,\n        },\n      ]\n    }\n\n    const chunks: Chunk[] = []\n    let offset = 0\n\n    while (offset < bytes.length) {\n      let endOffset = Math.min(offset + size, bytes.length)\n\n      // Back off to avoid splitting a multi-byte character\n      if (endOffset < bytes.length) {\n        // Find a valid UTF-8 boundary\n        while (endOffset > offset && (bytes[endOffset] & 0xc0) === 0x80) {\n          endOffset--\n        }\n\n        // Try to find a good break point (space or newline)\n        let breakPoint = endOffset\n        for (let i = endOffset - 1; i > offset + size / 2; i--) {\n          if (bytes[i] === 0x20 || bytes[i] === 0x0a) {\n            // space or newline\n            breakPoint = i + 1\n            break\n          }\n        }\n        if (breakPoint > offset) {\n          endOffset = breakPoint\n        }\n      }\n\n      const chunkBytes = bytes.slice(offset, endOffset)\n      const chunkText = new TextDecoder().decode(chunkBytes)\n\n      chunks.push({\n        text: chunkText,\n        index: chunks.length,\n        totalChunks: 0, // Will be set after loop\n        bytes: chunkBytes.length,\n      })\n\n      offset = endOffset\n    }\n\n    // Update total chunks count\n    for (const chunk of chunks) {\n      chunk.totalChunks = chunks.length\n    }\n\n    return chunks\n  }\n\n  /**\n   * Calculate line utilization statistics.\n   *\n   * @param result - Wrap result to analyze\n   * @returns Utilization statistics\n   */\n  calculateUtilization(result: WrapResult): {\n    averageUtilization: number\n    minUtilization: number\n    maxUtilization: number\n    totalWastedPx: number\n  } {\n    if (result.lines.length === 0 || result.lineMetrics.length === 0) {\n      return {\n        averageUtilization: 0,\n        minUtilization: 0,\n        maxUtilization: 0,\n        totalWastedPx: 0,\n      }\n    }\n\n    const maxWidthPx = this.profile.displayWidthPx\n    let totalUtilization = 0\n    let minUtilization = 100\n    let maxUtilization = 0\n    let totalWastedPx = 0\n\n    for (const metric of result.lineMetrics) {\n      totalUtilization += metric.utilizationPercent\n      minUtilization = Math.min(minUtilization, metric.utilizationPercent)\n      maxUtilization = Math.max(maxUtilization, metric.utilizationPercent)\n      totalWastedPx += maxWidthPx - metric.widthPx\n    }\n\n    return {\n      averageUtilization: Math.round(totalUtilization / result.lineMetrics.length),\n      minUtilization,\n      maxUtilization,\n      totalWastedPx,\n    }\n  }\n\n  /**\n   * Pad lines array to exact count with empty strings.\n   *\n   * @param lines - Lines to pad\n   * @param targetCount - Target number of lines\n   * @param padAtEnd - If true, pad at end; if false, pad at start (default: true)\n   * @returns Padded lines array\n   */\n  padToLineCount(lines: string[], targetCount: number, padAtEnd: boolean = true): string[] {\n    if (lines.length >= targetCount) {\n      return lines.slice(0, targetCount)\n    }\n\n    const padding = Array(targetCount - lines.length).fill(\"\")\n\n    if (padAtEnd) {\n      return [...lines, ...padding]\n    } else {\n      return [...padding, ...lines]\n    }\n  }\n\n  /**\n   * Join lines with newlines for display.\n   *\n   * @param lines - Lines to join\n   * @returns Joined string\n   */\n  joinLines(lines: string[]): string {\n    return lines.join(\"\\n\")\n  }\n\n  /**\n   * Get the measurer instance.\n   */\n  getMeasurer(): TextMeasurer {\n    return this.measurer\n  }\n\n  /**\n   * Get the wrapper instance.\n   */\n  getWrapper(): TextWrapper {\n    return this.wrapper\n  }\n\n  /**\n   * Get the display profile.\n   */\n  getProfile(): DisplayProfile {\n    return this.profile\n  }\n}\n"]}

package/build/utils/display/helpers/ScrollView.d.ts

@@ -0,0 +1,183 @@
+import type { DisplayProfile } from "../profiles/types";
+import { TextMeasurer } from "../measurer/TextMeasurer";
+import { TextWrapper } from "../wrapper/TextWrapper";
+import type { WrapOptions } from "../wrapper/types";
+/**
+ * Scroll position information.
+ */
+export interface ScrollPosition {
+    /** Current scroll offset (0 = top) */
+    offset: number;
+    /** Total number of lines in content */
+    totalLines: number;
+    /** Number of visible lines (viewport size) */
+    visibleLines: number;
+    /** Maximum scroll offset */
+    maxOffset: number;
+    /** Whether we're at the top */
+    atTop: boolean;
+    /** Whether we're at the bottom */
+    atBottom: boolean;
+    /** Scroll percentage (0-100) */
+    scrollPercent: number;
+}
+/**
+ * Visible content from the scroll view.
+ */
+export interface ScrollViewport {
+    /** Lines currently visible */
+    lines: string[];
+    /** Scroll position info */
+    position: ScrollPosition;
+    /** Whether content was truncated during wrapping */
+    contentTruncated: boolean;
+}
+/**
+ * ScrollView provides a scrollable viewport into long wrapped text.
+ *
+ * Unlike pagination (discrete pages), scrolling allows continuous
+ * movement through content line by line.
+ *
+ * @example
+ * ```typescript
+ * const scrollView = new ScrollView(measurer, wrapper)
+ * scrollView.setContent("Very long text that wraps to many lines...")
+ *
+ * // Get initial view (top)
+ * let view = scrollView.getViewport()
+ * console.log(view.lines) // First 5 lines
+ *
+ * // Scroll down
+ * scrollView.scrollDown(2) // Move down 2 lines
+ * view = scrollView.getViewport()
+ *
+ * // Scroll to bottom
+ * scrollView.scrollToBottom()
+ *
+ * // Scroll to specific position
+ * scrollView.scrollTo(10) // Line 10 at top of viewport
+ * ```
+ */
+export declare class ScrollView {
+    private readonly measurer;
+    private readonly wrapper;
+    private readonly profile;
+    private readonly viewportSize;
+    private allLines;
+    private wrapResult;
+    private scrollOffset;
+    constructor(measurer: TextMeasurer, wrapper: TextWrapper, viewportSize?: number);
+    /**
+     * Set the content to display in the scroll view.
+     * Wraps the text and resets scroll position to top.
+     *
+     * @param text - Text content to display
+     * @param options - Optional wrap options
+     */
+    setContent(text: string, options?: Omit<WrapOptions, "maxLines">): void;
+    /**
+     * Append content to the existing scroll view.
+     * Useful for streaming/live content like captions.
+     *
+     * @param text - Text to append
+     * @param options - Optional wrap options
+     * @param autoScroll - If true, scroll to show new content (default: true)
+     */
+    appendContent(text: string, options?: Omit<WrapOptions, "maxLines">, autoScroll?: boolean): void;
+    /**
+     * Get the current viewport (visible lines).
+     */
+    getViewport(): ScrollViewport;
+    /**
+     * Get current scroll position information.
+     */
+    getPosition(): ScrollPosition;
+    /**
+     * Scroll to a specific line offset.
+     *
+     * @param offset - Line offset (0 = top)
+     */
+    scrollTo(offset: number): void;
+    /**
+     * Scroll down by a number of lines.
+     *
+     * @param lines - Number of lines to scroll (default: 1)
+     */
+    scrollDown(lines?: number): void;
+    /**
+     * Scroll up by a number of lines.
+     *
+     * @param lines - Number of lines to scroll (default: 1)
+     */
+    scrollUp(lines?: number): void;
+    /**
+     * Scroll down by one viewport (page down).
+     */
+    pageDown(): void;
+    /**
+     * Scroll up by one viewport (page up).
+     */
+    pageUp(): void;
+    /**
+     * Scroll to the top.
+     */
+    scrollToTop(): void;
+    /**
+     * Scroll to the bottom.
+     */
+    scrollToBottom(): void;
+    /**
+     * Scroll to show a specific line in the viewport.
+     *
+     * @param lineIndex - The line index to show
+     * @param position - Where in viewport: 'top', 'center', 'bottom' (default: 'top')
+     */
+    scrollToLine(lineIndex: number, position?: "top" | "center" | "bottom"): void;
+    /**
+     * Scroll by a percentage of total content.
+     *
+     * @param percent - Percentage (0-100)
+     */
+    scrollToPercent(percent: number): void;
+    /**
+     * Check if currently at the top.
+     */
+    isAtTop(): boolean;
+    /**
+     * Check if currently at the bottom.
+     */
+    isAtBottom(): boolean;
+    /**
+     * Check if content is scrollable (more lines than viewport).
+     */
+    isScrollable(): boolean;
+    /**
+     * Get all lines (not just visible).
+     */
+    getAllLines(): string[];
+    /**
+     * Get total line count.
+     */
+    getTotalLines(): number;
+    /**
+     * Get the viewport size.
+     */
+    getViewportSize(): number;
+    /**
+     * Clear all content and reset scroll position.
+     */
+    clear(): void;
+    /**
+     * Get the measurer instance.
+     */
+    getMeasurer(): TextMeasurer;
+    /**
+     * Get the wrapper instance.
+     */
+    getWrapper(): TextWrapper;
+    /**
+     * Get the display profile.
+     */
+    getProfile(): DisplayProfile;
+}
+//# sourceMappingURL=ScrollView.d.ts.map

package/build/utils/display/helpers/ScrollView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScrollView.d.ts","sourceRoot":"","sources":["../../../../src/utils/display/helpers/ScrollView.ts"],"names":[],"mappings":"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"}