even-toolkit 1.3.2 → 1.4.1

package/README.md

@@ -2,7 +2,7 @@
 
 Design system & component library for **Even Realities G2** smart glasses apps.
 
-55+ web components, 191 pixel-art icons, glasses SDK bridge, light/dark themes, and design tokens — all following the Even Realities 2025 UIUX Design Guidelines.
+55+ web components, 191 pixel-art icons, glasses SDK bridge with per-screen architecture, speech-to-text module, light/dark themes, and design tokens — all following the Even Realities 2025 UIUX Design Guidelines.
 
 **[Live Demo → even-demo.vercel.app](https://even-demo.vercel.app)**
 
@@ -12,6 +12,12 @@ Design system & component library for **Even Realities G2** smart glasses apps.
 npm install even-toolkit
 ```
 
+Scaffold a new app instantly:
+
+```bash
+npx create-even-app my-app
+```
+
 ## What's Inside
 
 ### `/web` — Web Component Library
@@ -44,38 +50,173 @@ import { IcChevronBack, IcTrash, IcSettings } from 'even-toolkit/web/icons/svg-i
 
 **Categories:** Edit & Settings (32), Feature & Function (50), Guide System (20), Menu Bar (8), Navigate (23), Status (54), Health (12)
 
-### `/glasses` — G2 Glasses SDK Bridge
+---
 
-Everything needed to render content on the G2 glasses display.
+## Glasses SDK
 
-```tsx
-import { useGlasses } from 'even-toolkit/useGlasses';
-import { line, separator } from 'even-toolkit/types';
-import { buildActionBar } from 'even-toolkit/action-bar';
+Everything needed to build G2 glasses apps with a clean, per-screen architecture.
+
+### Per-Screen Architecture (v1.4)
+
+Each glasses screen lives in its own file with co-located display + action logic:
+
+```
+src/glass/
+  shared.ts              — Snapshot type + actions interface
+  selectors.ts           — Screen router (3 lines of wiring)
+  splash.ts              — Splash image + loading text
+  AppGlasses.tsx         — useGlasses hook setup
+  screens/
+    home.ts              — { display, action }
+    detail.ts            — { display, action }
+    active.ts            — { display, action }
 ```
 
-**Core:** EvenHubBridge, useGlasses hook, useFlashPhase hook
+#### Define a screen
+
+```ts
+import type { GlassScreen } from 'even-toolkit/glass-screen-router';
+import { buildScrollableList } from 'even-toolkit/glass-display-builders';
+import { moveHighlight } from 'even-toolkit/glass-nav';
+
+export const homeScreen: GlassScreen<MySnapshot, MyActions> = {
+  display(snapshot, nav) {
+    return {
+      lines: buildScrollableList({
+        items: snapshot.items,
+        highlightedIndex: nav.highlightedIndex,
+        maxVisible: 5,
+        formatter: (item) => item.title,
+      }),
+    };
+  },
+
+  action(action, nav, snapshot, ctx) {
+    if (action.type === 'HIGHLIGHT_MOVE') {
+      return { ...nav, highlightedIndex: moveHighlight(nav.highlightedIndex, action.direction, snapshot.items.length - 1) };
+    }
+    if (action.type === 'SELECT_HIGHLIGHTED') {
+      ctx.navigate(`/item/${snapshot.items[nav.highlightedIndex].id}`);
+      return nav;
+    }
+    return nav;
+  },
+};
+```
 
-**Display:** DisplayData, DisplayLine, line(), separator(), text-utils, timer-display, canvas-renderer
+#### Wire screens together
 
-**Input:** action-map, gestures, keyboard bindings
+```ts
+import { createGlassScreenRouter } from 'even-toolkit/glass-screen-router';
+import { homeScreen } from './screens/home';
+import { detailScreen } from './screens/detail';
 
-**Layout:** 576x288px display, text/columns/chart/home page modes, image tiles
+export const { toDisplayData, onGlassAction } = createGlassScreenRouter({
+  'home': homeScreen,
+  'detail': detailScreen,
+}, 'home');
+```
 
-**Utilities:** splash screens, PNG encoding, text cleaning, pagination, keep-alive
+### Navigation Helpers (`glass-nav`)
 
-### Glasses Display Helpers
+```ts
+import { moveHighlight, clampIndex, calcMaxScroll, wrapIndex } from 'even-toolkit/glass-nav';
 
-```tsx
-import { glassHeader, line, separator } from 'even-toolkit/types';
+// Clamped movement (0 to max)
+moveHighlight(current, 'up', max)    // Math.max(0, Math.min(max, current - 1))
+moveHighlight(current, 'down', max)  // Math.max(0, Math.min(max, current + 1))
+
+// Clamp index to button count
+clampIndex(index, buttonCount)       // Math.min(Math.max(0, index), count - 1)
+
+// Max scroll offset
+calcMaxScroll(totalLines, slots)     // Math.max(0, totalLines - slots)
+
+// Wrapping movement (loops around)
+wrapIndex(current, 'down', count)    // (current + 1) % count
+```
+
+### Display Builders (`glass-display-builders`)
+
+```ts
+import {
+  buildScrollableList,
+  buildScrollableContent,
+  slidingWindowStart,
+  G2_TEXT_LINES,          // 10
+  DEFAULT_CONTENT_SLOTS,  // 7 (below glassHeader)
+} from 'even-toolkit/glass-display-builders';
+
+// Scrollable highlighted list with scroll indicators
+const lines = buildScrollableList({
+  items: recipes,
+  highlightedIndex: nav.highlightedIndex,
+  maxVisible: 5,
+  formatter: (r) => r.title,
+});
+
+// Header + scrollable content with indicators
+const display = buildScrollableContent({
+  title: 'Recipe Detail',
+  actionBar: buildStaticActionBar(['Start'], 0),
+  contentLines: ['Line 1', 'Line 2', ...],
+  scrollPos: nav.highlightedIndex,
+});
+```
+
+### Mode Encoding (`glass-mode`)
+
+Pack multiple navigation modes into a single `highlightedIndex`:
+
+```ts
+import { createModeEncoder } from 'even-toolkit/glass-mode';
+
+const mode = createModeEncoder({
+  buttons: 0,    // 0-99: button selection
+  scroll: 100,   // 100+: scroll mode (offset = index - 100)
+  links: 200,    // 200+: link navigation
+});
 
-// Header with separator
-lines.push(...glassHeader('MY APP'));
+mode.getMode(150)    // 'scroll'
+mode.getOffset(150)  // 50
+mode.encode('scroll', 25)  // 125
+```
+
+### Route Mapping (`glass-router`)
+
+```ts
+import { createScreenMapper, createIdExtractor, getHomeTiles } from 'even-toolkit/glass-router';
 
-// Header with action bar
-lines.push(...glassHeader('STEP 1/4', buildActionBar([...], 0, null, true)));
+const deriveScreen = createScreenMapper([
+  { pattern: '/', screen: 'home' },
+  { pattern: /^\/item\/[^/]+$/, screen: 'detail' },
+], 'home');
+
+const extractId = createIdExtractor(/^\/item\/([^/]+)/);
+const homeTiles = getHomeTiles(appSplash);
 ```
 
+### Core Glasses Modules
+
+```ts
+import { useGlasses } from 'even-toolkit/useGlasses';
+import { useFlashPhase } from 'even-toolkit/useFlashPhase';
+import { EvenHubBridge } from 'even-toolkit/bridge';
+import { line, separator, glassHeader } from 'even-toolkit/types';
+import { buildActionBar, buildStaticActionBar } from 'even-toolkit/action-bar';
+import { truncate, applyScrollIndicators } from 'even-toolkit/text-utils';
+import { renderTimerLines } from 'even-toolkit/timer-display';
+import { createSplash, TILE_PRESETS } from 'even-toolkit/splash';
+```
+
+**Display:** 576x288px, 10 text lines, text/columns/chart/home page modes, image tiles (max 288x144)
+
+**Input:** action-map (tap/double-tap/scroll events), gestures (debounce), keyboard bindings
+
+**Utilities:** splash screens, PNG encoding, text cleaning, pagination, keep-alive
+
+---
+
 ## Speech-to-Text (STT)
 
 Provider-agnostic speech-to-text module for voice input in G2 glasses apps.
@@ -130,9 +271,10 @@ Automatically detects the best audio source:
 - **Browser mic** — via `getUserMedia` (desktop)
 - Custom `AudioSource` — pass your own
 
+---
+
 ## SDK 0.0.9 Support
 
-- Container limit increased to 12 (8 text + 4 image)
 - Max image size: 288x144
 - IMU control: `bridge.imuEnable()` / `bridge.imuDisable()`
 - Launch source detection: `LaunchSource` type
@@ -177,7 +319,6 @@ Light theme following Even Realities 2025 guidelines:
 ## Quick Start
 
 ```tsx
-// App.tsx
 import { AppShell, NavBar, ScreenHeader, Button, Card } from 'even-toolkit/web';
 import type { NavItem } from 'even-toolkit/web';
 
@@ -200,7 +341,6 @@ export function App() {
 ```
 
 ```css
-/* app.css */
 @import "tailwindcss";
 @import "even-toolkit/web/theme-light.css";
 @import "even-toolkit/web/typography.css";

package/dist/glasses/glass-display-builders.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Display composition utilities for G2 glasses.
+ * Builds common screen layouts: scrollable lists, scrollable content with headers.
+ */
+import type { DisplayLine, DisplayData } from './types';
+/** G2 display fits 10 lines of text */
+export declare const G2_TEXT_LINES = 10;
+/** glassHeader() produces 2 DisplayLines that occupy 3 visual lines (title + separator + gap) */
+export declare const HEADER_LINES = 3;
+/** Default content slots below a glassHeader */
+export declare const DEFAULT_CONTENT_SLOTS: number;
+/**
+ * Calculate the start index for a centered sliding window.
+ * Keeps the highlighted item roughly centered in the visible area.
+ */
+export declare function slidingWindowStart(highlightedIndex: number, totalItems: number, maxVisible: number): number;
+export interface ScrollableListOptions<T> {
+    items: T[];
+    highlightedIndex: number;
+    maxVisible: number;
+    /** Format an item into a display string */
+    formatter: (item: T, index: number) => string;
+    /** Line style for list items. Default: 'normal' */
+    style?: 'normal' | 'meta';
+}
+/**
+ * Build a scrollable highlighted list with ▲/▼ scroll indicators.
+ * Returns an array of DisplayLines ready to use as DisplayData.lines.
+ */
+export declare function buildScrollableList<T>(opts: ScrollableListOptions<T>): DisplayLine[];
+export interface ScrollableContentOptions {
+    title: string;
+    actionBar: string;
+    contentLines: string[];
+    scrollPos: number;
+    /** Number of visible content lines. Default: DEFAULT_CONTENT_SLOTS (7) */
+    contentSlots?: number;
+    /** Style for content lines. Default: 'meta' */
+    contentStyle?: 'normal' | 'meta';
+}
+/**
+ * Build a header + windowed content display with scroll indicators.
+ * Produces a complete DisplayData with glassHeader at the top,
+ * followed by a scrollable window of content lines.
+ */
+export declare function buildScrollableContent(opts: ScrollableContentOptions): DisplayData;
+//# sourceMappingURL=glass-display-builders.d.ts.map

package/dist/glasses/glass-display-builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glass-display-builders.d.ts","sourceRoot":"","sources":["../../glasses/glass-display-builders.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAIxD,uCAAuC;AACvC,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,iGAAiG;AACjG,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,QAA+B,CAAC;AAElE;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,MAAM,CAMR;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,WAAW,EAAE,CAYpF;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,wBAAwB,GAAG,WAAW,CA+BlF"}

package/dist/glasses/glass-display-builders.js

@@ -0,0 +1,54 @@
+/**
+ * Display composition utilities for G2 glasses.
+ * Builds common screen layouts: scrollable lists, scrollable content with headers.
+ */
+import { line, glassHeader } from './types';
+import { applyScrollIndicators } from './text-utils';
+/** G2 display fits 10 lines of text */
+export const G2_TEXT_LINES = 10;
+/** glassHeader() produces 2 DisplayLines that occupy 3 visual lines (title + separator + gap) */
+export const HEADER_LINES = 3;
+/** Default content slots below a glassHeader */
+export const DEFAULT_CONTENT_SLOTS = G2_TEXT_LINES - HEADER_LINES;
+/**
+ * Calculate the start index for a centered sliding window.
+ * Keeps the highlighted item roughly centered in the visible area.
+ */
+export function slidingWindowStart(highlightedIndex, totalItems, maxVisible) {
+    if (totalItems <= maxVisible)
+        return 0;
+    return Math.max(0, Math.min(highlightedIndex - Math.floor(maxVisible / 2), totalItems - maxVisible));
+}
+/**
+ * Build a scrollable highlighted list with ▲/▼ scroll indicators.
+ * Returns an array of DisplayLines ready to use as DisplayData.lines.
+ */
+export function buildScrollableList(opts) {
+    const { items, highlightedIndex, maxVisible, formatter, style = 'normal' } = opts;
+    const start = slidingWindowStart(highlightedIndex, items.length, maxVisible);
+    const visible = items.slice(start, start + maxVisible).map((item, i) => {
+        const idx = start + i;
+        return line(formatter(item, idx), style, idx === highlightedIndex);
+    });
+    applyScrollIndicators(visible, start, items.length, maxVisible, (t) => line(t, 'meta', false));
+    return visible;
+}
+/**
+ * Build a header + windowed content display with scroll indicators.
+ * Produces a complete DisplayData with glassHeader at the top,
+ * followed by a scrollable window of content lines.
+ */
+export function buildScrollableContent(opts) {
+    const { title, actionBar, contentLines, scrollPos, contentSlots = DEFAULT_CONTENT_SLOTS, contentStyle = 'meta', } = opts;
+    const lines = [...glassHeader(title, actionBar)];
+    const start = Math.max(0, Math.min(scrollPos, contentLines.length - contentSlots));
+    const visible = contentLines.slice(start, start + contentSlots);
+    const contentDisplayLines = [];
+    for (const text of visible) {
+        contentDisplayLines.push(line(text, contentStyle, false));
+    }
+    applyScrollIndicators(contentDisplayLines, start, contentLines.length, contentSlots, (t) => line(t, 'meta', false));
+    lines.push(...contentDisplayLines);
+    return { lines };
+}
+//# sourceMappingURL=glass-display-builders.js.map

package/dist/glasses/glass-display-builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glass-display-builders.js","sourceRoot":"","sources":["../../glasses/glass-display-builders.ts"],"names":[],"mappings":"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"}

package/dist/glasses/glass-mode.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Mode encoding for G2 glasses navigation.
+ *
+ * Packs a mode identifier + offset into a single highlightedIndex number.
+ * E.g. { buttons: 0, read: 100, links: 200 } means:
+ *   - index 0-99: buttons mode, offset = index
+ *   - index 100-199: read mode, offset = index - 100
+ *   - index 200+: links mode, offset = index - 200
+ */
+export interface ModeEncoder<M extends string> {
+    /** Encode a mode + offset into a single highlightedIndex value */
+    encode(mode: M, offset?: number): number;
+    /** Decode an index back to { mode, offset } */
+    decode(index: number): {
+        mode: M;
+        offset: number;
+    };
+    /** Get just the mode name from an encoded index */
+    getMode(index: number): M;
+    /** Get just the offset from an encoded index */
+    getOffset(index: number): number;
+    /** Get the base value for a mode */
+    getBase(mode: M): number;
+}
+/**
+ * Create a mode encoder from a mapping of mode names to base values.
+ * Modes are matched by checking the index against bases in descending order.
+ *
+ * @param modes Record mapping mode names to their base values.
+ *              All bases must be unique non-negative integers.
+ *              E.g. { buttons: 0, scroll: 100, steps: 200 }
+ */
+export declare function createModeEncoder<M extends string>(modes: Record<M, number>): ModeEncoder<M>;
+//# sourceMappingURL=glass-mode.d.ts.map

package/dist/glasses/glass-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glass-mode.d.ts","sourceRoot":"","sources":["../../glasses/glass-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM;IAC3C,kEAAkE;IAClE,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzC,+CAA+C;IAC/C,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,mDAAmD;IACnD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC;IAC1B,gDAAgD;IAChD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,oCAAoC;IACpC,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAChD,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,GACvB,WAAW,CAAC,CAAC,CAAC,CA+BhB"}

package/dist/glasses/glass-mode.js

@@ -0,0 +1,48 @@
+/**
+ * Mode encoding for G2 glasses navigation.
+ *
+ * Packs a mode identifier + offset into a single highlightedIndex number.
+ * E.g. { buttons: 0, read: 100, links: 200 } means:
+ *   - index 0-99: buttons mode, offset = index
+ *   - index 100-199: read mode, offset = index - 100
+ *   - index 200+: links mode, offset = index - 200
+ */
+/**
+ * Create a mode encoder from a mapping of mode names to base values.
+ * Modes are matched by checking the index against bases in descending order.
+ *
+ * @param modes Record mapping mode names to their base values.
+ *              All bases must be unique non-negative integers.
+ *              E.g. { buttons: 0, scroll: 100, steps: 200 }
+ */
+export function createModeEncoder(modes) {
+    // Sort entries by base value descending for decode matching
+    const entries = Object.entries(modes)
+        .sort((a, b) => b[1] - a[1]);
+    function decode(index) {
+        for (const [mode, base] of entries) {
+            if (index >= base) {
+                return { mode, offset: index - base };
+            }
+        }
+        // Fallback to the lowest base mode
+        const last = entries[entries.length - 1];
+        return { mode: last[0], offset: index - last[1] };
+    }
+    return {
+        encode(mode, offset = 0) {
+            return modes[mode] + offset;
+        },
+        decode,
+        getMode(index) {
+            return decode(index).mode;
+        },
+        getOffset(index) {
+            return decode(index).offset;
+        },
+        getBase(mode) {
+            return modes[mode];
+        },
+    };
+}
+//# sourceMappingURL=glass-mode.js.map

package/dist/glasses/glass-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glass-mode.js","sourceRoot":"","sources":["../../glasses/glass-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAwB;IAExB,4DAA4D;IAC5D,MAAM,OAAO,GAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAmB;SACrD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE/B,SAAS,MAAM,CAAC,KAAa;QAC3B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;YACnC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;gBAClB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAG,IAAI,EAAE,CAAC;YACxC,CAAC;QACH,CAAC;QACD,mCAAmC;QACnC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,CAAC;IAED,OAAO;QACL,MAAM,CAAC,IAAO,EAAE,MAAM,GAAG,CAAC;YACxB,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;QAC9B,CAAC;QACD,MAAM;QACN,OAAO,CAAC,KAAa;YACnB,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC;QAC5B,CAAC;QACD,SAAS,CAAC,KAAa;YACrB,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;QAC9B,CAAC;QACD,OAAO,CAAC,IAAO;YACb,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/glasses/glass-nav.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Navigation helpers for G2 glasses display.
+ * Pure functions for cursor movement, index clamping, and scroll math.
+ */
+/** Convert gesture direction to numeric delta */
+export declare function directionDelta(direction: 'up' | 'down'): -1 | 1;
+/** Move a highlight index by one step, clamped to [0, max] */
+export declare function moveHighlight(current: number, direction: 'up' | 'down', max: number): number;
+/** Clamp an index to a valid range [0, count - 1] */
+export declare function clampIndex(index: number, count: number): number;
+/** Calculate maximum scroll offset for windowed content */
+export declare function calcMaxScroll(totalLines: number, visibleSlots: number): number;
+/** Move an index with wrapping (loops around) */
+export declare function wrapIndex(current: number, direction: 'up' | 'down', count: number): number;
+//# sourceMappingURL=glass-nav.d.ts.map

package/dist/glasses/glass-nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glass-nav.d.ts","sourceRoot":"","sources":["../../glasses/glass-nav.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAE/D;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG5F;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG1F"}

package/dist/glasses/glass-nav.js

@@ -0,0 +1,28 @@
+/**
+ * Navigation helpers for G2 glasses display.
+ * Pure functions for cursor movement, index clamping, and scroll math.
+ */
+/** Convert gesture direction to numeric delta */
+export function directionDelta(direction) {
+    return direction === 'up' ? -1 : 1;
+}
+/** Move a highlight index by one step, clamped to [0, max] */
+export function moveHighlight(current, direction, max) {
+    const next = current + directionDelta(direction);
+    return Math.max(0, Math.min(max, next));
+}
+/** Clamp an index to a valid range [0, count - 1] */
+export function clampIndex(index, count) {
+    return Math.min(Math.max(0, index), count - 1);
+}
+/** Calculate maximum scroll offset for windowed content */
+export function calcMaxScroll(totalLines, visibleSlots) {
+    return Math.max(0, totalLines - visibleSlots);
+}
+/** Move an index with wrapping (loops around) */
+export function wrapIndex(current, direction, count) {
+    if (count <= 0)
+        return 0;
+    return (current + directionDelta(direction) + count) % count;
+}
+//# sourceMappingURL=glass-nav.js.map

package/dist/glasses/glass-nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glass-nav.js","sourceRoot":"","sources":["../../glasses/glass-nav.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iDAAiD;AACjD,MAAM,UAAU,cAAc,CAAC,SAAwB;IACrD,OAAO,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,SAAwB,EAAE,GAAW;IAClF,MAAM,IAAI,GAAG,OAAO,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACjD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,KAAa;IACrD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,UAAkB,EAAE,YAAoB;IACpE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC,CAAC;AAChD,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,SAAwB,EAAE,KAAa;IAChF,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACzB,OAAO,CAAC,OAAO,GAAG,cAAc,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAC/D,CAAC"}

package/dist/glasses/glass-router.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Route-to-screen mapping utilities for G2 glasses.
+ * Maps React Router URL paths to glasses screen names.
+ */
+import type { SplashHandle } from './splash';
+export interface ScreenPattern {
+    pattern: RegExp | string;
+    screen: string;
+}
+/**
+ * Create a deriveScreen function from a list of URL patterns.
+ * Patterns are tested in order; first match wins.
+ * String patterns are matched exactly. RegExp patterns use .test().
+ *
+ * @param patterns  Array of { pattern, screen } rules
+ * @param fallback  Screen name to return if no pattern matches
+ */
+export declare function createScreenMapper(patterns: ScreenPattern[], fallback: string): (path: string) => string;
+/**
+ * Create a function that extracts an ID from a URL path.
+ * @param pattern  RegExp with one capture group for the ID
+ */
+export declare function createIdExtractor(pattern: RegExp): (path: string) => string | null;
+/**
+ * Extract the first tile from a splash handle for home screen use.
+ * Returns an array with a single tile, or empty if no tiles available.
+ */
+export declare function getHomeTiles(splash: SplashHandle): {
+    id: number;
+    name: string;
+    bytes: Uint8Array;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}[];
+//# sourceMappingURL=glass-router.d.ts.map

package/dist/glasses/glass-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glass-router.d.ts","sourceRoot":"","sources":["../../glasses/glass-router.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EAAE,EACzB,QAAQ,EAAE,MAAM,GACf,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAW1B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,GACd,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAKjC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,GACnB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,CAG/F"}

package/dist/glasses/glass-router.js

@@ -0,0 +1,46 @@
+/**
+ * Route-to-screen mapping utilities for G2 glasses.
+ * Maps React Router URL paths to glasses screen names.
+ */
+/**
+ * Create a deriveScreen function from a list of URL patterns.
+ * Patterns are tested in order; first match wins.
+ * String patterns are matched exactly. RegExp patterns use .test().
+ *
+ * @param patterns  Array of { pattern, screen } rules
+ * @param fallback  Screen name to return if no pattern matches
+ */
+export function createScreenMapper(patterns, fallback) {
+    return (path) => {
+        for (const { pattern, screen } of patterns) {
+            if (typeof pattern === 'string') {
+                if (path === pattern)
+                    return screen;
+            }
+            else {
+                if (pattern.test(path))
+                    return screen;
+            }
+        }
+        return fallback;
+    };
+}
+/**
+ * Create a function that extracts an ID from a URL path.
+ * @param pattern  RegExp with one capture group for the ID
+ */
+export function createIdExtractor(pattern) {
+    return (path) => {
+        const match = path.match(pattern);
+        return match ? match[1] ?? null : null;
+    };
+}
+/**
+ * Extract the first tile from a splash handle for home screen use.
+ * Returns an array with a single tile, or empty if no tiles available.
+ */
+export function getHomeTiles(splash) {
+    const allTiles = splash.getTiles();
+    return allTiles.length > 0 ? [allTiles[0]] : [];
+}
+//# sourceMappingURL=glass-router.js.map

package/dist/glasses/glass-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glass-router.js","sourceRoot":"","sources":["../../glasses/glass-router.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAyB,EACzB,QAAgB;IAEhB,OAAO,CAAC,IAAY,EAAU,EAAE;QAC9B,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;YAC3C,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAChC,IAAI,IAAI,KAAK,OAAO;oBAAE,OAAO,MAAM,CAAC;YACtC,CAAC;iBAAM,CAAC;gBACN,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;oBAAE,OAAO,MAAM,CAAC;YACxC,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe;IAEf,OAAO,CAAC,IAAY,EAAiB,EAAE;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACzC,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAoB;IAEpB,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IACnC,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACnD,CAAC"}

package/dist/glasses/glass-screen-router.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Screen router for G2 glasses apps.
+ *
+ * Each screen is a self-contained module with display + action logic.
+ * The router composes them into a single toDisplayData + onGlassAction pair
+ * that switches on nav.screen automatically.
+ *
+ * @typeParam S  Snapshot type (app state)
+ * @typeParam C  Context type for side effects (navigate, actions, etc.)
+ */
+import type { DisplayData, GlassNavState, GlassAction } from './types';
+export interface GlassScreen<S, C> {
+    /** Render the display for this screen */
+    display: (snapshot: S, nav: GlassNavState) => DisplayData;
+    /** Handle a glass action. ctx provides side effects like navigate. */
+    action: (action: GlassAction, nav: GlassNavState, snapshot: S, ctx: C) => GlassNavState;
+}
+/**
+ * Create a screen router from a map of screen definitions.
+ *
+ * @param screens  Record mapping screen names to their display + action handlers
+ * @param fallback Screen name to use when nav.screen doesn't match any key
+ */
+export declare function createGlassScreenRouter<S, C>(screens: Record<string, GlassScreen<S, C>>, fallback: string): {
+    toDisplayData(snapshot: S, nav: GlassNavState): DisplayData;
+    onGlassAction(action: GlassAction, nav: GlassNavState, snapshot: S, ctx: C): GlassNavState;
+};
+//# sourceMappingURL=glass-screen-router.d.ts.map

package/dist/glasses/glass-screen-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glass-screen-router.d.ts","sourceRoot":"","sources":["../../glasses/glass-screen-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEvE,MAAM,WAAW,WAAW,CAAC,CAAC,EAAE,CAAC;IAC/B,yCAAyC;IACzC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,KAAK,WAAW,CAAC;IAC1D,sEAAsE;IACtE,MAAM,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,aAAa,CAAC;CACzF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAC1C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAC1C,QAAQ,EAAE,MAAM;4BAOU,CAAC,OAAO,aAAa,GAAG,WAAW;0BAGrC,WAAW,OAAO,aAAa,YAAY,CAAC,OAAO,CAAC,GAAG,aAAa;EAI7F"}

package/dist/glasses/glass-screen-router.js

@@ -0,0 +1,30 @@
+/**
+ * Screen router for G2 glasses apps.
+ *
+ * Each screen is a self-contained module with display + action logic.
+ * The router composes them into a single toDisplayData + onGlassAction pair
+ * that switches on nav.screen automatically.
+ *
+ * @typeParam S  Snapshot type (app state)
+ * @typeParam C  Context type for side effects (navigate, actions, etc.)
+ */
+/**
+ * Create a screen router from a map of screen definitions.
+ *
+ * @param screens  Record mapping screen names to their display + action handlers
+ * @param fallback Screen name to use when nav.screen doesn't match any key
+ */
+export function createGlassScreenRouter(screens, fallback) {
+    const getScreen = (name) => {
+        return screens[name] ?? screens[fallback];
+    };
+    return {
+        toDisplayData(snapshot, nav) {
+            return getScreen(nav.screen).display(snapshot, nav);
+        },
+        onGlassAction(action, nav, snapshot, ctx) {
+            return getScreen(nav.screen).action(action, nav, snapshot, ctx);
+        },
+    };
+}
+//# sourceMappingURL=glass-screen-router.js.map

package/dist/glasses/glass-screen-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glass-screen-router.js","sourceRoot":"","sources":["../../glasses/glass-screen-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAA0C,EAC1C,QAAgB;IAEhB,MAAM,SAAS,GAAG,CAAC,IAAY,EAAqB,EAAE;QACpD,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAE,CAAC;IAC7C,CAAC,CAAC;IAEF,OAAO;QACL,aAAa,CAAC,QAAW,EAAE,GAAkB;YAC3C,OAAO,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACtD,CAAC;QACD,aAAa,CAAC,MAAmB,EAAE,GAAkB,EAAE,QAAW,EAAE,GAAM;YACxE,OAAO,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;QAClE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/glasses/index.d.ts

@@ -5,4 +5,9 @@ export * from './timer-display';
 export * from './gestures';
 export * from './text-clean';
 export * from './paginate-text';
+export * from './glass-nav';
+export * from './glass-display-builders';
+export * from './glass-mode';
+export * from './glass-router';
+export * from './glass-screen-router';
 //# sourceMappingURL=index.d.ts.map

package/dist/glasses/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../glasses/index.ts"],"names":[],"mappings":"AAGA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../glasses/index.ts"],"names":[],"mappings":"AAGA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC"}

package/dist/glasses/index.js

@@ -7,4 +7,9 @@ export * from './timer-display';
 export * from './gestures';
 export * from './text-clean';
 export * from './paginate-text';
+export * from './glass-nav';
+export * from './glass-display-builders';
+export * from './glass-mode';
+export * from './glass-router';
+export * from './glass-screen-router';
 //# sourceMappingURL=index.js.map

package/dist/glasses/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../glasses/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,4FAA4F;AAE5F,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../glasses/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,4FAA4F;AAE5F,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC"}

package/glasses/glass-display-builders.ts

@@ -0,0 +1,110 @@
+/**
+ * Display composition utilities for G2 glasses.
+ * Builds common screen layouts: scrollable lists, scrollable content with headers.
+ */
+
+import type { DisplayLine, DisplayData } from './types';
+import { line, glassHeader } from './types';
+import { applyScrollIndicators } from './text-utils';
+
+/** G2 display fits 10 lines of text */
+export const G2_TEXT_LINES = 10;
+
+/** glassHeader() produces 2 DisplayLines that occupy 3 visual lines (title + separator + gap) */
+export const HEADER_LINES = 3;
+
+/** Default content slots below a glassHeader */
+export const DEFAULT_CONTENT_SLOTS = G2_TEXT_LINES - HEADER_LINES;
+
+/**
+ * Calculate the start index for a centered sliding window.
+ * Keeps the highlighted item roughly centered in the visible area.
+ */
+export function slidingWindowStart(
+  highlightedIndex: number,
+  totalItems: number,
+  maxVisible: number,
+): number {
+  if (totalItems <= maxVisible) return 0;
+  return Math.max(0, Math.min(
+    highlightedIndex - Math.floor(maxVisible / 2),
+    totalItems - maxVisible,
+  ));
+}
+
+export interface ScrollableListOptions<T> {
+  items: T[];
+  highlightedIndex: number;
+  maxVisible: number;
+  /** Format an item into a display string */
+  formatter: (item: T, index: number) => string;
+  /** Line style for list items. Default: 'normal' */
+  style?: 'normal' | 'meta';
+}
+
+/**
+ * Build a scrollable highlighted list with ▲/▼ scroll indicators.
+ * Returns an array of DisplayLines ready to use as DisplayData.lines.
+ */
+export function buildScrollableList<T>(opts: ScrollableListOptions<T>): DisplayLine[] {
+  const { items, highlightedIndex, maxVisible, formatter, style = 'normal' } = opts;
+
+  const start = slidingWindowStart(highlightedIndex, items.length, maxVisible);
+  const visible = items.slice(start, start + maxVisible).map((item, i) => {
+    const idx = start + i;
+    return line(formatter(item, idx), style, idx === highlightedIndex);
+  });
+
+  applyScrollIndicators(visible, start, items.length, maxVisible, (t) => line(t, 'meta', false));
+
+  return visible;
+}
+
+export interface ScrollableContentOptions {
+  title: string;
+  actionBar: string;
+  contentLines: string[];
+  scrollPos: number;
+  /** Number of visible content lines. Default: DEFAULT_CONTENT_SLOTS (7) */
+  contentSlots?: number;
+  /** Style for content lines. Default: 'meta' */
+  contentStyle?: 'normal' | 'meta';
+}
+
+/**
+ * Build a header + windowed content display with scroll indicators.
+ * Produces a complete DisplayData with glassHeader at the top,
+ * followed by a scrollable window of content lines.
+ */
+export function buildScrollableContent(opts: ScrollableContentOptions): DisplayData {
+  const {
+    title,
+    actionBar,
+    contentLines,
+    scrollPos,
+    contentSlots = DEFAULT_CONTENT_SLOTS,
+    contentStyle = 'meta',
+  } = opts;
+
+  const lines = [...glassHeader(title, actionBar)];
+
+  const start = Math.max(0, Math.min(scrollPos, contentLines.length - contentSlots));
+  const visible = contentLines.slice(start, start + contentSlots);
+
+  const contentDisplayLines: DisplayLine[] = [];
+  for (const text of visible) {
+    contentDisplayLines.push(line(text, contentStyle, false));
+  }
+
+  applyScrollIndicators(
+    contentDisplayLines,
+    start,
+    contentLines.length,
+    contentSlots,
+    (t) => line(t, 'meta', false),
+  );
+
+  lines.push(...contentDisplayLines);
+
+  return { lines };
+}

package/glasses/glass-mode.ts

@@ -0,0 +1,65 @@
+/**
+ * Mode encoding for G2 glasses navigation.
+ *
+ * Packs a mode identifier + offset into a single highlightedIndex number.
+ * E.g. { buttons: 0, read: 100, links: 200 } means:
+ *   - index 0-99: buttons mode, offset = index
+ *   - index 100-199: read mode, offset = index - 100
+ *   - index 200+: links mode, offset = index - 200
+ */
+
+export interface ModeEncoder<M extends string> {
+  /** Encode a mode + offset into a single highlightedIndex value */
+  encode(mode: M, offset?: number): number;
+  /** Decode an index back to { mode, offset } */
+  decode(index: number): { mode: M; offset: number };
+  /** Get just the mode name from an encoded index */
+  getMode(index: number): M;
+  /** Get just the offset from an encoded index */
+  getOffset(index: number): number;
+  /** Get the base value for a mode */
+  getBase(mode: M): number;
+}
+
+/**
+ * Create a mode encoder from a mapping of mode names to base values.
+ * Modes are matched by checking the index against bases in descending order.
+ *
+ * @param modes Record mapping mode names to their base values.
+ *              All bases must be unique non-negative integers.
+ *              E.g. { buttons: 0, scroll: 100, steps: 200 }
+ */
+export function createModeEncoder<M extends string>(
+  modes: Record<M, number>,
+): ModeEncoder<M> {
+  // Sort entries by base value descending for decode matching
+  const entries = (Object.entries(modes) as [M, number][])
+    .sort((a, b) => b[1] - a[1]);
+
+  function decode(index: number): { mode: M; offset: number } {
+    for (const [mode, base] of entries) {
+      if (index >= base) {
+        return { mode, offset: index - base };
+      }
+    }
+    // Fallback to the lowest base mode
+    const last = entries[entries.length - 1]!;
+    return { mode: last[0], offset: index - last[1] };
+  }
+
+  return {
+    encode(mode: M, offset = 0): number {
+      return modes[mode] + offset;
+    },
+    decode,
+    getMode(index: number): M {
+      return decode(index).mode;
+    },
+    getOffset(index: number): number {
+      return decode(index).offset;
+    },
+    getBase(mode: M): number {
+      return modes[mode];
+    },
+  };
+}

package/glasses/glass-nav.ts

@@ -0,0 +1,31 @@
+/**
+ * Navigation helpers for G2 glasses display.
+ * Pure functions for cursor movement, index clamping, and scroll math.
+ */
+
+/** Convert gesture direction to numeric delta */
+export function directionDelta(direction: 'up' | 'down'): -1 | 1 {
+  return direction === 'up' ? -1 : 1;
+}
+
+/** Move a highlight index by one step, clamped to [0, max] */
+export function moveHighlight(current: number, direction: 'up' | 'down', max: number): number {
+  const next = current + directionDelta(direction);
+  return Math.max(0, Math.min(max, next));
+}
+
+/** Clamp an index to a valid range [0, count - 1] */
+export function clampIndex(index: number, count: number): number {
+  return Math.min(Math.max(0, index), count - 1);
+}
+
+/** Calculate maximum scroll offset for windowed content */
+export function calcMaxScroll(totalLines: number, visibleSlots: number): number {
+  return Math.max(0, totalLines - visibleSlots);
+}
+
+/** Move an index with wrapping (loops around) */
+export function wrapIndex(current: number, direction: 'up' | 'down', count: number): number {
+  if (count <= 0) return 0;
+  return (current + directionDelta(direction) + count) % count;
+}

package/glasses/glass-router.ts

@@ -0,0 +1,59 @@
+/**
+ * Route-to-screen mapping utilities for G2 glasses.
+ * Maps React Router URL paths to glasses screen names.
+ */
+
+import type { SplashHandle } from './splash';
+
+export interface ScreenPattern {
+  pattern: RegExp | string;
+  screen: string;
+}
+
+/**
+ * Create a deriveScreen function from a list of URL patterns.
+ * Patterns are tested in order; first match wins.
+ * String patterns are matched exactly. RegExp patterns use .test().
+ *
+ * @param patterns  Array of { pattern, screen } rules
+ * @param fallback  Screen name to return if no pattern matches
+ */
+export function createScreenMapper(
+  patterns: ScreenPattern[],
+  fallback: string,
+): (path: string) => string {
+  return (path: string): string => {
+    for (const { pattern, screen } of patterns) {
+      if (typeof pattern === 'string') {
+        if (path === pattern) return screen;
+      } else {
+        if (pattern.test(path)) return screen;
+      }
+    }
+    return fallback;
+  };
+}
+
+/**
+ * Create a function that extracts an ID from a URL path.
+ * @param pattern  RegExp with one capture group for the ID
+ */
+export function createIdExtractor(
+  pattern: RegExp,
+): (path: string) => string | null {
+  return (path: string): string | null => {
+    const match = path.match(pattern);
+    return match ? match[1] ?? null : null;
+  };
+}
+
+/**
+ * Extract the first tile from a splash handle for home screen use.
+ * Returns an array with a single tile, or empty if no tiles available.
+ */
+export function getHomeTiles(
+  splash: SplashHandle,
+): { id: number; name: string; bytes: Uint8Array; x: number; y: number; w: number; h: number }[] {
+  const allTiles = splash.getTiles();
+  return allTiles.length > 0 ? [allTiles[0]!] : [];
+}

package/glasses/glass-screen-router.ts

@@ -0,0 +1,43 @@
+/**
+ * Screen router for G2 glasses apps.
+ *
+ * Each screen is a self-contained module with display + action logic.
+ * The router composes them into a single toDisplayData + onGlassAction pair
+ * that switches on nav.screen automatically.
+ *
+ * @typeParam S  Snapshot type (app state)
+ * @typeParam C  Context type for side effects (navigate, actions, etc.)
+ */
+
+import type { DisplayData, GlassNavState, GlassAction } from './types';
+
+export interface GlassScreen<S, C> {
+  /** Render the display for this screen */
+  display: (snapshot: S, nav: GlassNavState) => DisplayData;
+  /** Handle a glass action. ctx provides side effects like navigate. */
+  action: (action: GlassAction, nav: GlassNavState, snapshot: S, ctx: C) => GlassNavState;
+}
+
+/**
+ * Create a screen router from a map of screen definitions.
+ *
+ * @param screens  Record mapping screen names to their display + action handlers
+ * @param fallback Screen name to use when nav.screen doesn't match any key
+ */
+export function createGlassScreenRouter<S, C>(
+  screens: Record<string, GlassScreen<S, C>>,
+  fallback: string,
+) {
+  const getScreen = (name: string): GlassScreen<S, C> => {
+    return screens[name] ?? screens[fallback]!;
+  };
+
+  return {
+    toDisplayData(snapshot: S, nav: GlassNavState): DisplayData {
+      return getScreen(nav.screen).display(snapshot, nav);
+    },
+    onGlassAction(action: GlassAction, nav: GlassNavState, snapshot: S, ctx: C): GlassNavState {
+      return getScreen(nav.screen).action(action, nav, snapshot, ctx);
+    },
+  };
+}

package/glasses/index.ts

@@ -8,3 +8,8 @@ export * from './timer-display';
 export * from './gestures';
 export * from './text-clean';
 export * from './paginate-text';
+export * from './glass-nav';
+export * from './glass-display-builders';
+export * from './glass-mode';
+export * from './glass-router';
+export * from './glass-screen-router';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "even-toolkit",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "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",
@@ -82,6 +82,26 @@
       "types": "./dist/glasses/paginate-text.d.ts",
       "import": "./dist/glasses/paginate-text.js"
     },
+    "./glass-nav": {
+      "types": "./dist/glasses/glass-nav.d.ts",
+      "import": "./dist/glasses/glass-nav.js"
+    },
+    "./glass-display-builders": {
+      "types": "./dist/glasses/glass-display-builders.d.ts",
+      "import": "./dist/glasses/glass-display-builders.js"
+    },
+    "./glass-mode": {
+      "types": "./dist/glasses/glass-mode.d.ts",
+      "import": "./dist/glasses/glass-mode.js"
+    },
+    "./glass-router": {
+      "types": "./dist/glasses/glass-router.d.ts",
+      "import": "./dist/glasses/glass-router.js"
+    },
+    "./glass-screen-router": {
+      "types": "./dist/glasses/glass-screen-router.d.ts",
+      "import": "./dist/glasses/glass-screen-router.js"
+    },
     "./web": {
       "types": "./dist/web/index.d.ts",
       "import": "./dist/web/index.js"