@mentra/engine 0.1.0-beta.0

package/build/services/DisplayProcessor.d.ts

@@ -0,0 +1,223 @@
+/**
+ * DisplayProcessor
+ *
+ * Processes display events with pixel-accurate text wrapping using the same
+ * display-utils library as the cloud. This ensures the mobile preview matches
+ * exactly what is shown on the glasses.
+ *
+ * Key responsibilities:
+ * 1. Intercept display events before sending to native SGC
+ * 2. Wrap text using the correct device profile (G1, etc.)
+ * 3. Ensure GlassesDisplayMirror shows exactly what glasses will show
+ *
+ * @see cloud/issues/026-mobile-display-processor for design docs
+ */
+import { type DisplayProfile, type WrapOptions, type BreakMode } from "../utils/display";
+/**
+ * Supported device models for display processing
+ */
+export type DeviceModel = "g1" | "g2" | "z100" | "nex" | "mach1" | "mentra-live" | "simulated" | "unknown";
+/**
+ * Display event types that we process
+ */
+export type DisplayLayoutType = "text_wall" | "text_line" | "text_rows" | "reference_card" | "double_text_wall" | "bitmap_view";
+/**
+ * Raw display event from the cloud/WebSocket
+ */
+export interface DisplayEvent {
+    view: "main" | "dashboard";
+    layoutType?: DisplayLayoutType;
+    layout?: {
+        layoutType: DisplayLayoutType;
+        text?: string | string[];
+        title?: string;
+        topText?: string;
+        bottomText?: string;
+        breakMode?: BreakMode;
+        data?: string;
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+        [key: string]: unknown;
+    };
+    text?: string | string[];
+    title?: string;
+    topText?: string;
+    bottomText?: string;
+    breakMode?: BreakMode;
+    [key: string]: unknown;
+}
+/**
+ * Processed display event with guaranteed wrapped text
+ */
+export interface ProcessedDisplayEvent extends DisplayEvent {
+    /** Marks this event as processed */
+    _processed: true;
+    /** The device profile used for processing */
+    _profile: string;
+    /** Pre-split lines for text_wall/text_line (for easy rendering) */
+    _lines?: string[];
+    /** Original layout type before processing (e.g., double_text_wall -> text_wall) */
+    _originalLayoutType?: DisplayLayoutType;
+    /** Column composition metadata for double_text_wall */
+    _composedColumns?: {
+        leftLines: string[];
+        rightLines: string[];
+        config: {
+            leftColumnWidthPx: number;
+            rightColumnStartPx: number;
+            rightColumnWidthPx: number;
+            maxLines: number;
+            leftMarginSpaces?: number;
+        };
+    };
+}
+/**
+ * Options for the DisplayProcessor
+ */
+export interface DisplayProcessorOptions {
+    /** Default break mode for text wrapping */
+    breakMode?: BreakMode;
+    /** Whether to log processing details */
+    debug?: boolean;
+}
+/**
+ * Processes display events with pixel-accurate text wrapping.
+ *
+ * Usage:
+ * ```typescript
+ * const processor = DisplayProcessor.getInstance()
+ *
+ * // When glasses connect
+ * processor.setDeviceModel("Even Realities G1")
+ *
+ * // Process display events
+ * const processed = processor.processDisplayEvent(rawEvent)
+ * ```
+ */
+export declare class DisplayProcessor {
+    private static instance;
+    private measurer;
+    private wrapper;
+    private composer;
+    private profile;
+    private deviceModel;
+    private options;
+    private runtimeAttached;
+    private unsubscribeGlassesStatus;
+    private constructor();
+    /**
+     * Read the current default wearable and subscribe to engine glasses-status changes.
+     * Idempotent — safe to call again after app services start.
+     */
+    attachToRuntime(): void;
+    /** Detach runtime subscriptions installed by attachToRuntime(). */
+    detachFromRuntime(): void;
+    /**
+     * Get the singleton instance
+     */
+    static getInstance(options?: DisplayProcessorOptions): DisplayProcessor;
+    /**
+     * Reset the singleton (useful for testing)
+     */
+    static resetInstance(): void;
+    /**
+     * Set the device model and update the display profile accordingly.
+     * Call this when glasses connect.
+     *
+     * @param modelName - The model name from the connected glasses (e.g., "Even Realities G1")
+     */
+    setDeviceModel(modelName: string | null | undefined): void;
+    /**
+     * Update the display profile and recreate engine
+     */
+    private updateProfile;
+    /**
+     * Get the current device model
+     */
+    getDeviceModel(): DeviceModel;
+    /**
+     * Get the current display profile
+     */
+    getProfile(): DisplayProfile;
+    /**
+     * Process a display event, wrapping text as needed.
+     *
+     * @param event - Raw display event from WebSocket
+     * @returns Processed event with wrapped text
+     */
+    processDisplayEvent(event: DisplayEvent): ProcessedDisplayEvent;
+    /**
+     * Process text_wall or text_line layout
+     */
+    private processTextWall;
+    /**
+     * Process text_rows layout
+     */
+    private processTextRows;
+    /**
+     * Process reference_card layout
+     */
+    private processReferenceCard;
+    /**
+     * Process double_text_wall layout
+     *
+     * Uses ColumnComposer to create a fully composed string with both columns
+     * merged line-by-line with pixel-precise space alignment. This is the single
+     * source of truth for double_text_wall composition, replacing duplicate
+     * implementations in native iOS (G1Text.swift) and Android (G1Text.kt).
+     *
+     * The composed text is sent to native as a regular text_wall - native just
+     * chunks and sends it without any re-wrapping or column composition.
+     */
+    private processDoubleTextWall;
+    /**
+     * Wrap text using the current profile
+     *
+     * @param text - Text to wrap
+     * @param options - Optional override options
+     * @returns Array of wrapped lines
+     */
+    wrapText(text: string, options?: WrapOptions): string[];
+    private getEventBreakMode;
+    /**
+     * Measure the pixel width of text
+     *
+     * @param text - Text to measure
+     * @returns Width in pixels
+     */
+    measureText(text: string): number;
+    /**
+     * Check if text fits on a single line
+     *
+     * @param text - Text to check
+     * @returns true if text fits without wrapping
+     */
+    fitsOnSingleLine(text: string): boolean;
+    /**
+     * Get the display width in pixels
+     */
+    getDisplayWidth(): number;
+    /**
+     * Get the maximum number of lines
+     */
+    getMaxLines(): number;
+    /**
+     * Get detailed text measurement
+     */
+    measureTextDetailed(text: string): import("../utils/display").TextMeasurement;
+    /**
+     * Set the break mode for text wrapping
+     *
+     * @param breakMode - 'character' | 'word' | 'strict-word'
+     */
+    setBreakMode(breakMode: BreakMode): void;
+    /**
+     * Get the current break mode
+     */
+    getBreakMode(): BreakMode;
+}
+export declare const displayProcessor: DisplayProcessor;
+export default displayProcessor;
+//# sourceMappingURL=DisplayProcessor.d.ts.map

package/build/services/DisplayProcessor.d.ts.map

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