even-toolkit 1.1.0 → 1.1.2

package/glasses/text-utils.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared text utilities for G2 glasses display.
+ */
+
+/** Truncate text to maxLen, appending ~ if truncated */
+export function truncate(text: string, maxLen: number): string {
+  return text.length > maxLen ? text.slice(0, maxLen - 1) + '~' : text;
+}
+
+/** Up arrow scroll indicator */
+export const SCROLL_UP = '\u25B2';  // ▲
+
+/** Down arrow scroll indicator */
+export const SCROLL_DOWN = '\u25BC';  // ▼
+
+/**
+ * Build a header line with title on the left and action bar on the right.
+ *
+ * @param title     Left-side text (e.g. "Step 1/4: Toast the pepper")
+ * @param actionBar Right-side action bar string from buildActionBar()
+ */
+export function buildHeaderLine(title: string, actionBar: string): string {
+  return `${title}  ${actionBar}`;
+}
+
+/**
+ * Apply scroll indicators to a windowed line array.
+ * Replaces the first/last visible line with ▲/▼ if there's more content above/below.
+ *
+ * @param lines       The visible lines array (will be mutated)
+ * @param start       Start index into the full content
+ * @param totalCount  Total number of content lines
+ * @param visibleCount Number of visible lines in the window
+ * @param lineFactory Function to create a DisplayLine (e.g. `(text) => line(text, 'meta', false)`)
+ */
+export function applyScrollIndicators<T>(
+  lines: T[],
+  start: number,
+  totalCount: number,
+  visibleCount: number,
+  lineFactory: (text: string) => T,
+): void {
+  if (lines.length === 0) return;
+  if (start > 0) {
+    lines[0] = lineFactory(SCROLL_UP);
+  }
+  if (start + visibleCount < totalCount) {
+    lines[lines.length - 1] = lineFactory(SCROLL_DOWN);
+  }
+}

package/glasses/timer-display.ts

@@ -0,0 +1,91 @@
+/**
+ * Unicode timer display for G2 glasses.
+ *
+ * Confirmed working on G2:  █ (full block), ─ (box drawing horizontal)
+ * NOT working on G2:  ░ ▒ ▓ (shading), ╔═╗║ (double box drawing), ▀▄ (half blocks)
+ *
+ * Renders as 2 lines — text centered using ─ padding to match bar width:
+ *      ─────── ▶  06:44 ───────
+ *      ████████████────────────
+ */
+
+const BLOCK_FULL = '\u2588';     // █  (filled portion)
+const LINE_THIN = '\u2500';      // ─  (remaining portion + centering filler)
+const ICON_PLAY = '\u25B6';      // ▶
+const ICON_PAUSE = '\u2588';     // █  (single block for paused)
+const ICON_DONE = 'OK';
+const ICON_IDLE = '--';
+
+export interface TimerState {
+  running: boolean;
+  remaining: number;
+  total: number;
+}
+
+function formatTime(seconds: number): string {
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
+}
+
+/** Center text above bar — spaces are ~4.5x narrower than █/─ on G2 font */
+function center(text: string, barWidth: number): string {
+  const pad = Math.max(0, Math.floor((barWidth - text.length) / 2));
+  return ' '.repeat(Math.round(pad * 6.7)) + text;
+}
+
+/**
+ * Render a 2-line timer display for the G2 glasses.
+ * Line 1: ─── icon  MM:SS ─── (centered with ─ filler, same visual width as bar)
+ * Line 2: ████████████──────── (progress bar)
+ *
+ * @param timer    Current timer state
+ * @param barWidth Number of characters for the progress bar (default 24)
+ */
+export function renderTimerLines(timer: TimerState, barWidth = 18): string[] {
+  const { running, remaining, total } = timer;
+
+  if (total === 0 && remaining === 0) {
+    return [
+      center(` ${ICON_IDLE}  00:00 `, barWidth),
+      LINE_THIN.repeat(barWidth),
+    ];
+  }
+
+  if (remaining <= 0 && total > 0) {
+    return [
+      center(` ${ICON_DONE}  00:00 `, barWidth),
+      BLOCK_FULL.repeat(barWidth),
+    ];
+  }
+
+  const icon = running ? ICON_PLAY : ICON_PAUSE;
+  const time = formatTime(remaining);
+  const progress = total > 0 ? (total - remaining) / total : 0;
+  const filled = Math.round(progress * barWidth);
+  const empty = barWidth - filled;
+  const bar = BLOCK_FULL.repeat(filled) + LINE_THIN.repeat(empty);
+
+  return [
+    center(` ${icon}  ${time} `, barWidth),
+    bar,
+  ];
+}
+
+/**
+ * Render a single-line compact timer (for tight spaces).
+ */
+export function renderTimerCompact(timer: TimerState): string {
+  const { running, remaining, total } = timer;
+
+  if (total === 0 && remaining === 0) {
+    return `${ICON_IDLE} 00:00`;
+  }
+
+  if (remaining <= 0 && total > 0) {
+    return `${ICON_DONE} DONE`;
+  }
+
+  const icon = running ? ICON_PLAY : ICON_PAUSE;
+  return `${icon} ${formatTime(remaining)}`;
+}

package/glasses/types.ts

@@ -0,0 +1,59 @@
+// ── Display line types (legacy, still used for single-text pages) ──
+
+export type LineStyle = 'normal' | 'meta' | 'separator' | 'inverted';
+
+export interface DisplayLine {
+  text: string;
+  inverted: boolean;
+  style: LineStyle;
+}
+
+export interface DisplayData {
+  lines: DisplayLine[];
+}
+
+export function line(text: string, style: LineStyle = 'normal', inverted = false): DisplayLine {
+  return { text, inverted, style };
+}
+
+export function separator(): DisplayLine {
+  return { text: '', inverted: false, style: 'separator' };
+}
+
+// ── Column layout types (for multi-text-container pages) ──
+
+export interface ColumnData {
+  /** One string per column — each column is a separate text container at a fixed pixel position */
+  columns: string[];
+}
+
+// ── Image tile types (for chart/image pages) ──
+
+export interface ImageTileData {
+  tiles: { id: number; name: string; bytes: Uint8Array }[];
+  /** Text shown below images (or empty for no-bounce overlay) */
+  text?: string;
+}
+
+// ── Page layout modes ──
+
+export type PageMode =
+  | 'splash'    // initial splash screen (text or image)
+  | 'text'      // single full-screen text container (settings, simple screens)
+  | 'columns'   // multiple side-by-side text containers (watchlist, tables)
+  | 'home'      // image tile + text + empty overlay (home screens)
+  | 'chart';    // 3 image tiles + text (chart detail)
+
+// ── Glass action types ──
+
+export type GlassActionType = 'HIGHLIGHT_MOVE' | 'SELECT_HIGHLIGHTED' | 'GO_BACK';
+
+export type GlassAction =
+  | { type: 'HIGHLIGHT_MOVE'; direction: 'up' | 'down' }
+  | { type: 'SELECT_HIGHLIGHTED' }
+  | { type: 'GO_BACK' };
+
+export interface GlassNavState {
+  highlightedIndex: number;
+  screen: string;
+}

package/glasses/upng.d.ts

@@ -0,0 +1,19 @@
+declare module 'upng-js' {
+  export function encode(
+    imgs: ArrayBuffer[],
+    w: number,
+    h: number,
+    cnum: number,
+    dels?: number[],
+    forbidPlte?: boolean,
+  ): ArrayBuffer;
+  export function decode(buffer: ArrayBuffer): {
+    width: number;
+    height: number;
+    depth: number;
+    ctype: number;
+    frames: Array<{ rect: { x: number; y: number; width: number; height: number }; delay: number }>;
+    data: ArrayBuffer;
+  };
+  export function toRGBA8(img: ReturnType<typeof decode>): ArrayBuffer[];
+}

package/glasses/useFlashPhase.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared flash phase hook for blinking action button indicators.
+ * Toggles a boolean every 500ms when active.
+ *
+ * Usage:
+ *   const flashPhase = useFlashPhase(isInActiveMode);
+ */
+
+import { useState, useEffect } from 'react';
+
+const FLASH_INTERVAL_MS = 500;
+
+export function useFlashPhase(active: boolean): boolean {
+  const [phase, setPhase] = useState(false);
+
+  useEffect(() => {
+    if (!active) {
+      setPhase(false);
+      return;
+    }
+
+    const interval = setInterval(() => {
+      setPhase((prev) => !prev);
+    }, FLASH_INTERVAL_MS);
+
+    return () => clearInterval(interval);
+  }, [active]);
+
+  return phase;
+}

package/glasses/useGlasses.ts

@@ -0,0 +1,214 @@
+import { useEffect, useRef, useCallback } from 'react';
+import { useLocation, useNavigate } from 'react-router';
+import type { DisplayData, GlassAction, GlassNavState, ColumnData } from './types';
+import { EvenHubBridge, type ColumnConfig } from './bridge';
+import { mapGlassEvent } from './action-map';
+import { bindKeyboard } from './keyboard';
+import { activateKeepAlive, deactivateKeepAlive } from './keep-alive';
+import type { SplashHandle } from './splash';
+
+export interface UseGlassesConfig<S> {
+  getSnapshot: () => S;
+  /** Convert snapshot to single text display (for 'text' mode) */
+  toDisplayData: (snapshot: S, nav: GlassNavState) => DisplayData;
+  /** Convert snapshot to column data (for 'columns' mode) — optional */
+  toColumns?: (snapshot: S, nav: GlassNavState) => ColumnData;
+  onGlassAction: (action: GlassAction, nav: GlassNavState, snapshot: S) => GlassNavState;
+  deriveScreen: (path: string) => string;
+  appName: string;
+  /** Page mode per screen — return 'text', 'columns', or 'home'. Default: 'text' */
+  getPageMode?: (screen: string) => 'text' | 'columns' | 'home';
+  /** Column layout config — default: 3 equal columns across 576px */
+  columns?: ColumnConfig[];
+  /** Home page image tiles — sent when getPageMode returns 'home'. Create with createSplash().getTiles() */
+  homeImageTiles?: { id: number; name: string; bytes: Uint8Array; x: number; y: number; w: number; h: number }[];
+  /**
+   * Optional image-based splash screen.
+   * When provided, shows the splash image instead of the default text splash,
+   * then waits minTimeMs before switching to app content.
+   * Create with `createSplash()` from 'even-toolkit/splash'.
+   */
+  splash?: SplashHandle;
+}
+
+export function useGlasses<S>(config: UseGlassesConfig<S>): void {
+  const location = useLocation();
+  const navigate = useNavigate();
+
+  const hubRef = useRef<EvenHubBridge | null>(null);
+  const navRef = useRef<GlassNavState>({ highlightedIndex: 0, screen: '' });
+  const lastSnapshotRef = useRef<S | null>(null);
+  const sendingRef = useRef(false);
+  const pendingRef = useRef(false);
+  const navigateRef = useRef(navigate);
+  navigateRef.current = navigate;
+
+  const configRef = useRef(config);
+  configRef.current = config;
+  const lastHadImagesRef = useRef(false);
+
+  const sendDisplay = useCallback(async () => {
+    if (sendingRef.current || !hubRef.current) {
+      // Queue a retry — the current in-flight send has stale data
+      pendingRef.current = true;
+      return;
+    }
+    sendingRef.current = true;
+    pendingRef.current = false;
+    try {
+      const hub = hubRef.current;
+      const snapshot = configRef.current.getSnapshot();
+      const nav = navRef.current;
+      const getMode = configRef.current.getPageMode ?? (() => 'text');
+      const mode = getMode(nav.screen);
+
+      // Build display text from lines
+      const data = configRef.current.toDisplayData(snapshot, nav);
+      const text = data.lines.map(l => {
+        if (l.style === 'separator') return '\u2500'.repeat(44);
+        if (l.inverted) return `\u25B6 ${l.text}`;
+        return `  ${l.text}`;
+      }).join('\n');
+
+      if (mode === 'columns' && configRef.current.toColumns) {
+        const cols = configRef.current.toColumns(snapshot, nav);
+        if (hub.currentMode === 'columns') {
+          await hub.updateColumns(cols.columns);
+        } else {
+          await hub.showColumnPage(cols.columns);
+        }
+      } else {
+        // All modes use raw bridge (home layout) for consistent rendering.
+        // 'home' mode includes image tiles; 'text' mode passes no images.
+        const tiles = mode === 'home' ? configRef.current.homeImageTiles : undefined;
+        const imageTiles = tiles?.map(t => ({ id: t.id, name: t.name, x: t.x, y: t.y, w: t.w, h: t.h }));
+        const hasImages = !!imageTiles?.length;
+        // Rebuild container when switching modes or changing between image/no-image layouts
+        const needsRebuild = hub.currentMode !== 'home' || hasImages !== lastHadImagesRef.current;
+
+        if (!needsRebuild) {
+          await hub.updateHomeText(text);
+        } else {
+          await hub.showHomePage(text, imageTiles);
+          if (tiles) {
+            for (const tile of tiles) {
+              await hub.sendImage(tile.id, tile.name, tile.bytes);
+            }
+          }
+        }
+        lastHadImagesRef.current = hasImages;
+      }
+    } catch {
+      // SDK unavailable — glasses panel won't update, web still works
+    } finally {
+      sendingRef.current = false;
+      // If a send was queued while we were busy, flush again with fresh data
+      if (pendingRef.current) {
+        pendingRef.current = false;
+        sendDisplay();
+      }
+    }
+  }, []);
+
+  const flushDisplay = useCallback(() => {
+    sendDisplay();
+  }, [sendDisplay]);
+
+  const handleAction = useCallback((action: GlassAction) => {
+    const snapshot = configRef.current.getSnapshot();
+    const newNav = configRef.current.onGlassAction(action, navRef.current, snapshot);
+    navRef.current = newNav;
+    flushDisplay();
+  }, [flushDisplay]);
+
+  // Update screen from URL changes
+  useEffect(() => {
+    const newScreen = configRef.current.deriveScreen(location.pathname);
+    if (newScreen !== navRef.current.screen) {
+      navRef.current = { highlightedIndex: 0, screen: newScreen };
+      flushDisplay();
+    }
+  }, [location.pathname, flushDisplay]);
+
+  // Initialize bridge, keyboard, keep-alive, and polling
+  useEffect(() => {
+    let pollTimer: ReturnType<typeof setInterval> | null = null;
+    let disposed = false;
+
+    const hub = new EvenHubBridge(configRef.current.columns);
+    hubRef.current = hub;
+
+    navRef.current = {
+      highlightedIndex: 0,
+      screen: configRef.current.deriveScreen(location.pathname),
+    };
+
+    async function initBridge() {
+      try {
+        await hub.init();
+        if (disposed) return;
+
+        const splash = configRef.current.splash;
+
+        if (splash) {
+          // Image-based splash: show canvas-rendered image, then wait minTime
+          await splash.show(hub);
+          if (disposed) return;
+
+          hub.onEvent((event) => {
+            const action = mapGlassEvent(event);
+            if (action) handleAction(action);
+          });
+
+          await splash.waitMinTime();
+          if (disposed) return;
+
+          // Clear extra splash tiles (e.g. "Loading..." tile) with black — no rebuild
+          await splash.clearExtras(hub);
+
+          // Splash already set up the home layout — mark it so first render
+          // uses updateHomeText instead of rebuilding (avoids blink)
+          lastHadImagesRef.current = !!configRef.current.homeImageTiles?.length;
+        } else {
+          // Default text splash
+          await hub.showTextPage(`\n\n      ${configRef.current.appName}`);
+          if (disposed) return;
+
+          hub.onEvent((event) => {
+            const action = mapGlassEvent(event);
+            if (action) handleAction(action);
+          });
+        }
+      } catch {
+        // SDK not available — app continues without glasses
+      }
+
+      // Start polling for state changes
+      if (!disposed) {
+        flushDisplay();
+        pollTimer = setInterval(() => {
+          const snapshot = configRef.current.getSnapshot();
+          if (snapshot !== lastSnapshotRef.current) {
+            lastSnapshotRef.current = snapshot;
+            flushDisplay();
+          }
+        }, 100);
+      }
+    }
+
+    initBridge();
+
+    const unbindKeyboard = bindKeyboard(handleAction);
+    activateKeepAlive(`${configRef.current.appName}_keep_alive`);
+
+    return () => {
+      disposed = true;
+      if (pollTimer) clearInterval(pollTimer);
+      unbindKeyboard();
+      hub.dispose();
+      hubRef.current = null;
+      deactivateKeepAlive();
+    };
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "even-toolkit",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Design system & component library for Even Realities G2 smart glasses apps — 55+ web components, 191 pixel-art icons, glasses SDK bridge, and design tokens.",
   "type": "module",
   "main": "./dist/glasses/index.js",
@@ -338,6 +338,8 @@
   "files": [
     "dist",
     "web",
+    "glasses",
+    "stt",
     "README.md",
     "LICENSE"
   ],

package/stt/audio/buffer.ts

@@ -0,0 +1,40 @@
+import { float32ToWav } from './pcm-utils';
+
+/** Audio accumulator — collects Float32 chunks and exports as WAV */
+export function createAudioBuffer(config?: { maxSeconds?: number; sampleRate?: number }) {
+  const sampleRate = config?.sampleRate ?? 16000;
+  const maxSamples = (config?.maxSeconds ?? 30) * sampleRate;
+  const chunks: Float32Array[] = [];
+  let totalSamples = 0;
+
+  function append(chunk: Float32Array): void {
+    if (totalSamples + chunk.length > maxSamples) return;
+    chunks.push(chunk);
+    totalSamples += chunk.length;
+  }
+
+  function getAll(): Float32Array {
+    const out = new Float32Array(totalSamples);
+    let offset = 0;
+    for (const chunk of chunks) {
+      out.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return out;
+  }
+
+  function getWav(): Blob {
+    return float32ToWav(getAll(), sampleRate);
+  }
+
+  function clear(): void {
+    chunks.length = 0;
+    totalSamples = 0;
+  }
+
+  function duration(): number {
+    return totalSamples / sampleRate;
+  }
+
+  return { append, getAll, getWav, clear, duration };
+}

package/stt/audio/pcm-utils.ts

@@ -0,0 +1,60 @@
+/** Convert Uint8Array of 16-bit signed PCM to Int16Array */
+export function uint8ToPcm16(data: Uint8Array): Int16Array {
+  return new Int16Array(data.buffer, data.byteOffset, data.byteLength / 2);
+}
+
+/** Convert Int16Array PCM to Float32Array [-1, 1] */
+export function pcm16ToFloat32(data: Int16Array): Float32Array {
+  const out = new Float32Array(data.length);
+  for (let i = 0; i < data.length; i++) {
+    out[i] = data[i] / 32768;
+  }
+  return out;
+}
+
+/** Convert Float32Array [-1, 1] to Int16Array PCM */
+export function float32ToPcm16(data: Float32Array): Int16Array {
+  const out = new Int16Array(data.length);
+  for (let i = 0; i < data.length; i++) {
+    const s = Math.max(-1, Math.min(1, data[i]));
+    out[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
+  }
+  return out;
+}
+
+/** Convert Float32Array to WAV Blob */
+export function float32ToWav(data: Float32Array, sampleRate: number): Blob {
+  const pcm = float32ToPcm16(data);
+  const buffer = new ArrayBuffer(44 + pcm.byteLength);
+  const view = new DataView(buffer);
+
+  // RIFF header
+  writeString(view, 0, 'RIFF');
+  view.setUint32(4, 36 + pcm.byteLength, true);
+  writeString(view, 8, 'WAVE');
+
+  // fmt chunk
+  writeString(view, 12, 'fmt ');
+  view.setUint32(16, 16, true);          // chunk size
+  view.setUint16(20, 1, true);           // PCM format
+  view.setUint16(22, 1, true);           // mono
+  view.setUint32(24, sampleRate, true);  // sample rate
+  view.setUint32(28, sampleRate * 2, true); // byte rate
+  view.setUint16(32, 2, true);           // block align
+  view.setUint16(34, 16, true);          // bits per sample
+
+  // data chunk
+  writeString(view, 36, 'data');
+  view.setUint32(40, pcm.byteLength, true);
+
+  const bytes = new Uint8Array(buffer, 44);
+  bytes.set(new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength));
+
+  return new Blob([buffer], { type: 'audio/wav' });
+}
+
+function writeString(view: DataView, offset: number, str: string): void {
+  for (let i = 0; i < str.length; i++) {
+    view.setUint8(offset + i, str.charCodeAt(i));
+  }
+}

package/stt/audio/resample.ts

@@ -0,0 +1,18 @@
+/** Linear interpolation resample from one sample rate to another */
+export function resample(input: Float32Array, fromRate: number, toRate: number): Float32Array {
+  if (fromRate === toRate) return input;
+
+  const ratio = fromRate / toRate;
+  const outputLength = Math.round(input.length / ratio);
+  const output = new Float32Array(outputLength);
+
+  for (let i = 0; i < outputLength; i++) {
+    const srcIndex = i * ratio;
+    const srcFloor = Math.floor(srcIndex);
+    const srcCeil = Math.min(srcFloor + 1, input.length - 1);
+    const frac = srcIndex - srcFloor;
+    output[i] = input[srcFloor] * (1 - frac) + input[srcCeil] * frac;
+  }
+
+  return output;
+}

package/stt/audio/vad.ts

@@ -0,0 +1,61 @@
+/** Energy-based Voice Activity Detection */
+
+export interface VADConfig {
+  silenceThresholdMs?: number;  // default 1500
+  speechThresholdDb?: number;   // default -26
+  frameSizeMs?: number;         // default 30
+}
+
+export interface VADResult {
+  isSpeech: boolean;
+  speechStarted: boolean;
+  speechEnded: boolean;
+  energy: number;
+}
+
+export function createVAD(config?: VADConfig) {
+  const silenceMs = config?.silenceThresholdMs ?? 1500;
+  const thresholdDb = config?.speechThresholdDb ?? -26;
+  const threshold = Math.pow(10, thresholdDb / 20);
+
+  let speaking = false;
+  let silenceStart = 0;
+
+  function process(frame: Float32Array): VADResult {
+    // RMS energy
+    let sum = 0;
+    for (let i = 0; i < frame.length; i++) {
+      sum += frame[i] * frame[i];
+    }
+    const rms = Math.sqrt(sum / frame.length);
+    const isSpeech = rms > threshold;
+
+    let speechStarted = false;
+    let speechEnded = false;
+
+    if (isSpeech) {
+      if (!speaking) {
+        speaking = true;
+        speechStarted = true;
+      }
+      silenceStart = 0;
+    } else if (speaking) {
+      if (silenceStart === 0) {
+        silenceStart = Date.now();
+      } else if (Date.now() - silenceStart > silenceMs) {
+        speaking = false;
+        speechEnded = true;
+        silenceStart = 0;
+      }
+    }
+
+    return { isSpeech, speechStarted, speechEnded, energy: rms };
+  }
+
+  function reset() {
+    speaking = false;
+    silenceStart = 0;
+  }
+
+  return { process, reset };
+}