@glassly/engine 0.1.0-dev.0

package/src/utils/display/composer/ColumnComposer.ts

@@ -0,0 +1,285 @@
+/**
+ * ColumnComposer
+ *
+ * Handles composition of multi-column layouts like double_text_wall.
+ * This is the single source of truth for column layout logic, replacing
+ * the duplicate implementations in native iOS (G1Text.swift) and
+ * Android (G1Text.kt, G1.java).
+ *
+ * The composer:
+ * 1. Wraps each column's text to its allocated width
+ * 2. Merges columns line-by-line with pixel-precise space padding
+ * 3. Returns a single pre-composed string ready for native to chunk & send
+ *
+ * @see cloud/issues/026-mobile-display-processor for design docs
+ */
+
+import type {DisplayProfile} from "../profiles/types"
+import {TextMeasurer} from "../measurer/TextMeasurer"
+import {TextWrapper} from "../wrapper/TextWrapper"
+import type {WrapOptions, BreakMode} from "../wrapper/types"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Configuration for column layout
+ */
+export interface ColumnConfig {
+  /** Width of the left column in pixels */
+  leftColumnWidthPx: number
+  /** X position where the right column starts in pixels */
+  rightColumnStartPx: number
+  /** Width of the right column in pixels (calculated from start position) */
+  rightColumnWidthPx: number
+  /** Maximum number of lines to display */
+  maxLines: number
+  /** Left margin in spaces (for indentation) */
+  leftMarginSpaces?: number
+}
+
+/**
+ * Options for composing double text wall
+ */
+export interface ComposeOptions {
+  /** Break mode for text wrapping */
+  breakMode?: BreakMode
+  /** Custom column configuration (overrides profile defaults) */
+  columnConfig?: Partial<ColumnConfig>
+}
+
+/**
+ * Result of column composition
+ */
+export interface ComposeResult {
+  /** The fully composed text with both columns merged */
+  composedText: string
+  /** Lines from the left column (for debugging/preview) */
+  leftLines: string[]
+  /** Lines from the right column (for debugging/preview) */
+  rightLines: string[]
+  /** The column configuration that was used */
+  config: ColumnConfig
+}
+
+// =============================================================================
+// ColumnComposer Class
+// =============================================================================
+
+/**
+ * Composes multi-column layouts for smart glasses displays.
+ *
+ * Usage:
+ * ```typescript
+ * const composer = new ColumnComposer(G1_PROFILE)
+ * const result = composer.composeDoubleTextWall("Left content", "Right content")
+ * // result.composedText is ready to send to native SGC
+ * ```
+ */
+export class ColumnComposer {
+  private profile: DisplayProfile
+  private measurer: TextMeasurer
+  private wrapper: TextWrapper
+  private spaceWidthPx: number
+
+  constructor(profile: DisplayProfile, breakMode: BreakMode = "character-no-hyphen") {
+    this.profile = profile
+    this.measurer = new TextMeasurer(profile)
+    this.wrapper = new TextWrapper(this.measurer, {
+      breakMode,
+    })
+
+    // Cache space width for alignment calculations
+    this.spaceWidthPx = this.measurer.measureText(" ")
+  }
+
+  // ===========================================================================
+  // Public API
+  // ===========================================================================
+
+  /**
+   * Compose a double text wall layout.
+   *
+   * Takes left and right text, wraps each to their column width,
+   * and merges them with pixel-precise space alignment.
+   *
+   * @param leftText - Text for the left column
+   * @param rightText - Text for the right column
+   * @param options - Optional composition settings
+   * @returns Composed result with merged text and metadata
+   */
+  public composeDoubleTextWall(leftText: string, rightText: string, options: ComposeOptions = {}): ComposeResult {
+    const config = this.getColumnConfig(options.columnConfig)
+
+    // Wrap each column independently
+    const leftWrapOptions: WrapOptions = {
+      maxWidthPx: config.leftColumnWidthPx,
+      maxLines: config.maxLines,
+    }
+
+    const rightWrapOptions: WrapOptions = {
+      maxWidthPx: config.rightColumnWidthPx,
+      maxLines: config.maxLines,
+    }
+
+    const leftResult = this.wrapper.wrap(leftText || "", leftWrapOptions)
+    const rightResult = this.wrapper.wrap(rightText || "", rightWrapOptions)
+
+    // Pad arrays to have exactly maxLines entries
+    const leftLines = this.padLines(leftResult.lines, config.maxLines)
+    const rightLines = this.padLines(rightResult.lines, config.maxLines)
+
+    // Merge columns with space alignment
+    const composedText = this.mergeColumns(leftLines, rightLines, config)
+
+    return {
+      composedText,
+      leftLines,
+      rightLines,
+      config,
+    }
+  }
+
+  /**
+   * Get the default column configuration for the current profile.
+   */
+  public getDefaultColumnConfig(): ColumnConfig {
+    return this.getColumnConfig()
+  }
+
+  /**
+   * Update the break mode for text wrapping.
+   */
+  public setBreakMode(breakMode: BreakMode): void {
+    this.wrapper = new TextWrapper(this.measurer, {
+      breakMode,
+    })
+  }
+
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+
+  /**
+   * Get column configuration, merging defaults with overrides.
+   */
+  private getColumnConfig(overrides?: Partial<ColumnConfig>): ColumnConfig {
+    const displayWidth = this.profile.displayWidthPx
+
+    // Default layout: 50% for left column, right starts at 55%
+    // This matches the native G1Text implementations
+    const defaults: ColumnConfig = {
+      leftColumnWidthPx: Math.floor(displayWidth * 0.5),
+      rightColumnStartPx: Math.floor(displayWidth * 0.55),
+      rightColumnWidthPx: displayWidth - Math.floor(displayWidth * 0.55),
+      maxLines: this.profile.maxLines,
+      leftMarginSpaces: 0,
+    }
+
+    return {
+      ...defaults,
+      ...overrides,
+    }
+  }
+
+  /**
+   * Pad lines array to exactly `count` entries.
+   */
+  private padLines(lines: string[], count: number): string[] {
+    const result = [...lines]
+    while (result.length < count) {
+      result.push("")
+    }
+    return result.slice(0, count)
+  }
+
+  /**
+   * Merge left and right columns with pixel-precise space alignment.
+   *
+   * For each line:
+   * 1. Take the left column text
+   * 2. Calculate its pixel width
+   * 3. Calculate how many spaces needed to reach rightColumnStartPx
+   * 4. Append spaces and right column text
+   */
+  private mergeColumns(leftLines: string[], rightLines: string[], config: ColumnConfig): string {
+    const lines: string[] = []
+
+    for (let i = 0; i < config.maxLines; i++) {
+      const leftText = this.cleanEnspaces(leftLines[i] || "")
+      const rightText = this.cleanEnspaces(rightLines[i] || "")
+
+      // Calculate pixel width of left text
+      const leftWidthPx = this.measurer.measureText(leftText)
+
+      // Calculate spaces needed to reach the right column start
+      const spacesNeeded = this.calculateSpacesForAlignment(leftWidthPx, config.rightColumnStartPx)
+
+      // Build the merged line
+      let line = ""
+
+      // Add left margin if configured
+      if (config.leftMarginSpaces && config.leftMarginSpaces > 0) {
+        line += " ".repeat(config.leftMarginSpaces)
+      }
+
+      line += leftText
+      line += " ".repeat(spacesNeeded)
+      line += rightText
+
+      lines.push(line)
+    }
+
+    return lines.join("\n")
+  }
+
+  /**
+   * Calculate the number of spaces needed to align to a target position.
+   *
+   * @param currentWidthPx - Current position in pixels
+   * @param targetPositionPx - Target position in pixels
+   * @returns Number of space characters needed
+   */
+  private calculateSpacesForAlignment(currentWidthPx: number, targetPositionPx: number): number {
+    const pixelsNeeded = targetPositionPx - currentWidthPx
+
+    // Ensure at least one space for separation
+    if (pixelsNeeded <= 0) {
+      return 1
+    }
+
+    // Calculate spaces needed. Use Math.floor (not Math.ceil) to ensure the
+    // right column never starts past rightColumnStartPx. Rounding up caused
+    // the right column to start 1–5px further right than planned, shrinking
+    // its usable width and causing the last character to wrap onto the next
+    // line's left position.
+    const spaces = Math.max(1, Math.floor(pixelsNeeded / this.spaceWidthPx))
+
+    // Cap at a reasonable maximum to prevent runaway spacing
+    return Math.min(spaces, 100)
+  }
+
+  /**
+   * Remove en-space characters (U+2002) that may have been added during wrapping.
+   * Native implementations do this cleanup before merging.
+   */
+  private cleanEnspaces(text: string): string {
+    return text.replace(/\u2002/g, "")
+  }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/**
+ * Create a ColumnComposer for a given profile.
+ *
+ * @param profile - Display profile to use
+ * @param breakMode - Break mode for text wrapping (default: "word")
+ * @returns Configured ColumnComposer instance
+ */
+export function createColumnComposer(profile: DisplayProfile, breakMode: BreakMode = "word"): ColumnComposer {
+  return new ColumnComposer(profile, breakMode)
+}

package/src/utils/display/composer/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Composer Module
+ *
+ * Handles composition of multi-column and complex layouts for smart glasses displays.
+ * This module provides the single source of truth for layout composition logic,
+ * replacing duplicate implementations in native iOS and Android code.
+ */
+
+export {
+  ColumnComposer,
+  createColumnComposer,
+  type ColumnConfig,
+  type ComposeOptions,
+  type ComposeResult,
+} from "./ColumnComposer"

package/src/utils/display/helpers/DisplayHelpers.ts

@@ -0,0 +1,409 @@
+import type {DisplayProfile} from "../profiles/types"
+import {TextMeasurer} from "../measurer/TextMeasurer"
+import {TextWrapper} from "../wrapper/TextWrapper"
+import type {WrapOptions, WrapResult} from "../wrapper/types"
+
+/**
+ * Truncation result with metadata.
+ */
+export interface TruncateResult {
+  /** The truncated text */
+  text: string
+  /** Whether text was truncated */
+  wasTruncated: boolean
+  /** Width in pixels of truncated text */
+  widthPx: number
+  /** Original text length */
+  originalLength: number
+  /** Truncated text length */
+  truncatedLength: number
+}
+
+/**
+ * Page result for pagination.
+ */
+export interface Page {
+  /** Lines on this page */
+  lines: string[]
+  /** Page number (1-indexed) */
+  pageNumber: number
+  /** Total number of pages */
+  totalPages: number
+  /** Whether this is the first page */
+  isFirst: boolean
+  /** Whether this is the last page */
+  isLast: boolean
+}
+
+/**
+ * Chunk result for BLE transmission.
+ */
+export interface Chunk {
+  /** The chunk text */
+  text: string
+  /** Chunk index (0-indexed) */
+  index: number
+  /** Total number of chunks */
+  totalChunks: number
+  /** Byte size of this chunk */
+  bytes: number
+}
+
+/**
+ * Optional helper utilities for common display operations.
+ * Built on top of TextMeasurer and TextWrapper for convenience.
+ */
+export class DisplayHelpers {
+  private readonly measurer: TextMeasurer
+  private readonly wrapper: TextWrapper
+  private readonly profile: DisplayProfile
+
+  constructor(measurer: TextMeasurer, wrapper: TextWrapper) {
+    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: string[], maxLines: number, fromEnd: boolean = false): string[] {
+    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: string, maxWidthPx?: number, ellipsis: string = "..."): TruncateResult {
+    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: string, maxWidthPx?: number): number {
+    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: string, options?: WrapOptions): string[] {
+    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: string, options?: WrapOptions): Page[] {
+    // 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: Page[] = []
+
+    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: string): number {
+    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: string, maxBytes?: number): boolean {
+    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: string, chunkSize?: number): Chunk[] {
+    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: Chunk[] = []
+    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: WrapResult): {
+    averageUtilization: number
+    minUtilization: number
+    maxUtilization: number
+    totalWastedPx: number
+  } {
+    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: string[], targetCount: number, padAtEnd: boolean = true): string[] {
+    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: string[]): string {
+    return lines.join("\n")
+  }
+
+  /**
+   * Get the measurer instance.
+   */
+  getMeasurer(): TextMeasurer {
+    return this.measurer
+  }
+
+  /**
+   * Get the wrapper instance.
+   */
+  getWrapper(): TextWrapper {
+    return this.wrapper
+  }
+
+  /**
+   * Get the display profile.
+   */
+  getProfile(): DisplayProfile {
+    return this.profile
+  }
+}