even-toolkit 1.1.0 → 1.1.2

package/dist/stt/providers/whisper-local/provider.js

@@ -23,7 +23,7 @@ export class WhisperLocalProvider {
         return new Promise((resolve, reject) => {
             this.initResolve = resolve;
             this.initReject = reject;
-            this.worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' });
+            this.worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
             this.worker.onmessage = (e) => {
                 this.handleWorkerMessage(e.data);
             };

package/glasses/action-bar.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared action button bar for G2 glasses display.
+ *
+ * Renders a row of named buttons with triangle indicators:
+ *   ▶Timer◀  Scroll  ▷Steps◁
+ *
+ * - Selected button (in button-select mode): solid triangles ▶Name◀
+ * - Active button (mode entered): blinking triangles ▶Name◀ / ▷Name◁
+ * - Inactive button: plain  Name
+ */
+
+/**
+ * Build an action bar string from a list of button names.
+ *
+ * @param buttons   Array of button label strings, e.g. ['Timer', 'Scroll', 'Steps']
+ * @param selectedIndex  Index of the currently highlighted button (in button-select mode)
+ * @param activeLabel    Label of the currently active mode button (e.g. 'Scroll'), or null if in button-select mode
+ * @param flashPhase     Current blink phase (true = filled triangles, false = empty)
+ */
+export function buildActionBar(
+  buttons: string[],
+  selectedIndex: number,
+  activeLabel: string | null,
+  flashPhase: boolean,
+): string {
+  const activeIdx = activeLabel ? buttons.indexOf(activeLabel) : -1;
+
+  return buttons.map((name, i) => {
+    if (activeIdx === i) {
+      // Active mode: blink between filled and empty triangles
+      const L = flashPhase ? '\u25B6' : '\u25B7';  // ▶ / ▷
+      const R = flashPhase ? '\u25C0' : '\u25C1';  // ◀ / ◁
+      return `${L}${name}${R}`;
+    }
+    if (activeIdx < 0 && i === selectedIndex) {
+      // Selected in button-select mode: solid triangles
+      return `\u25B6${name}\u25C0`;
+    }
+    return ` ${name} `;
+  }).join(' ');
+}
+
+/**
+ * Build a static action bar (no blinking, always solid triangles on selected).
+ * Useful for screens like recipe detail or completion where there's no mode switching.
+ */
+export function buildStaticActionBar(
+  buttons: string[],
+  selectedIndex: number,
+): string {
+  return buttons.map((name, i) => {
+    if (i === selectedIndex) {
+      return `\u25B6${name}\u25C0`;
+    }
+    return ` ${name} `;
+  }).join(' ');
+}

package/glasses/action-map.ts

@@ -0,0 +1,41 @@
+import type { EvenHubEvent } from '@evenrealities/even_hub_sdk';
+import { OsEventTypeList } from '@evenrealities/even_hub_sdk';
+import type { GlassAction } from './types';
+import { tryConsumeTap, isScrollSuppressed, isScrollDebounced } from './gestures';
+
+export function mapGlassEvent(event: EvenHubEvent): GlassAction | null {
+  if (!event) return null;
+  try {
+    const ev = event.listEvent ?? event.textEvent ?? event.sysEvent;
+    if (!ev) return null;
+    return mapEvent(ev);
+  } catch {
+    return null;
+  }
+}
+
+function mapEvent(event: { eventType?: number; currentSelectItemIndex?: number }): GlassAction | null {
+  const et = event.eventType;
+  switch (et) {
+    case OsEventTypeList.CLICK_EVENT:
+      if (!tryConsumeTap('tap')) return null;
+      return { type: 'SELECT_HIGHLIGHTED' };
+    case OsEventTypeList.DOUBLE_CLICK_EVENT:
+      if (!tryConsumeTap('double')) return null;
+      return { type: 'GO_BACK' };
+    case OsEventTypeList.SCROLL_TOP_EVENT:
+      if (isScrollDebounced('prev') || isScrollSuppressed()) return null;
+      return { type: 'HIGHLIGHT_MOVE', direction: 'up' };
+    case OsEventTypeList.SCROLL_BOTTOM_EVENT:
+      if (isScrollDebounced('next') || isScrollSuppressed()) return null;
+      return { type: 'HIGHLIGHT_MOVE', direction: 'down' };
+    default:
+      // Simulator omits eventType for CLICK_EVENT (value 0).
+      // Catch: currentSelectItemIndex present, or eventType missing entirely.
+      if (et == null || (event.currentSelectItemIndex != null && (et as number) === 0)) {
+        if (!tryConsumeTap('tap')) return null;
+        return { type: 'SELECT_HIGHLIGHTED' };
+      }
+      return null;
+  }
+}

package/glasses/bridge.ts

@@ -0,0 +1,306 @@
+import { EvenBetterSdk } from '@jappyjan/even-better-sdk';
+import type { EvenBetterPage, EvenBetterTextElement } from '@jappyjan/even-better-sdk';
+import {
+  RebuildPageContainer,
+  ImageContainerProperty,
+  ImageRawDataUpdate,
+  TextContainerProperty,
+  TextContainerUpgrade,
+  type EvenAppBridge,
+  type EvenHubEvent,
+} from '@evenrealities/even_hub_sdk';
+import { DISPLAY_W, DISPLAY_H, CHART_TEXT, IMAGE_TILES } from './layout';
+import type { PageMode } from './types';
+import { notifyTextUpdate } from './gestures';
+
+function noBorder(el: EvenBetterTextElement): EvenBetterTextElement {
+  return el.setBorder(b => b.setWidth(0).setColor('0').setRadius(0));
+}
+
+export interface ColumnConfig {
+  x: number;
+  w: number;
+}
+
+export class EvenHubBridge {
+  private sdk: EvenBetterSdk;
+  private rawBridge: EvenAppBridge | null = null;
+  private _currentMode: PageMode | null = null;
+  private _pageReady = false;
+
+  // ── SDK-managed pages ──
+
+  // Single text page (settings, simple screens)
+  private textPage!: EvenBetterPage;
+  private textContent!: EvenBetterTextElement;
+
+  // Column page (watchlist, tables)
+  private columnPage!: EvenBetterPage;
+  private columnElements: EvenBetterTextElement[] = [];
+
+  // Chart dummy (for SDK state tracking before raw bridge chart/home)
+  private chartDummyPage!: EvenBetterPage;
+
+  constructor(columns?: ColumnConfig[]) {
+    this.sdk = new EvenBetterSdk();
+    const cols = columns ?? [
+      { x: 0, w: 192 },
+      { x: 192, w: 192 },
+      { x: 384, w: DISPLAY_W - 384 },
+    ];
+    this.createPages(cols);
+  }
+
+  get pageReady(): boolean { return this._pageReady; }
+  get currentMode(): PageMode | null { return this._currentMode; }
+  /** Alias matching even-market naming convention */
+  get currentLayout(): PageMode | null { return this._currentMode; }
+
+  private createPages(cols: ColumnConfig[]): void {
+    // ── Text page: empty overlay (event capture, no bounce) + visible content ──
+    this.textPage = this.sdk.createPage('text');
+    const textOverlay = noBorder(this.textPage.addTextElement(''));
+    textOverlay
+      .setPosition(p => p.setX(0).setY(0))
+      .setSize(s => s.setWidth(DISPLAY_W).setHeight(DISPLAY_H));
+    textOverlay.markAsEventCaptureElement();
+
+    this.textContent = noBorder(this.textPage.addTextElement(''));
+    this.textContent
+      .setPosition(p => p.setX(0).setY(0))
+      .setSize(s => s.setWidth(DISPLAY_W).setHeight(DISPLAY_H));
+
+    // ── Column page: empty overlay + N column text elements (max 3 columns + overlay = 4 containers) ──
+    this.columnPage = this.sdk.createPage('columns');
+    const colOverlay = noBorder(this.columnPage.addTextElement(''));
+    colOverlay
+      .setPosition(p => p.setX(0).setY(0))
+      .setSize(s => s.setWidth(DISPLAY_W).setHeight(DISPLAY_H));
+    colOverlay.markAsEventCaptureElement();
+
+    this.columnElements = cols.map((col) => {
+      const el = noBorder(this.columnPage.addTextElement(''));
+      el.setPosition(p => p.setX(col.x).setY(0))
+        .setSize(s => s.setWidth(col.w).setHeight(DISPLAY_H));
+      return el;
+    });
+
+    // ── Chart dummy page (for SDK state tracking) ──
+    this.chartDummyPage = this.sdk.createPage('chart-dummy');
+    const dummyText = noBorder(this.chartDummyPage.addTextElement(''));
+    dummyText
+      .setPosition(p => p.setX(0).setY(0))
+      .setSize(s => s.setWidth(1).setHeight(1));
+    dummyText.markAsEventCaptureElement();
+  }
+
+  async init(): Promise<void> {
+    this.rawBridge = await EvenBetterSdk.getRawBridge() as unknown as EvenAppBridge;
+    this._pageReady = true;
+  }
+
+  // ── Setup (required before chart/home layout switch) ──
+
+  async setupTextPage(): Promise<boolean> {
+    if (!this._pageReady) return false;
+    try {
+      this.textContent.setContent('');
+      await this.sdk.renderPage(this.textPage);
+      this._currentMode = 'text';
+      return true;
+    } catch { return false; }
+  }
+
+  // ── Text page (single full-screen text, no bounce) ──
+
+  async showTextPage(content: string): Promise<void> {
+    if (!this._pageReady) return;
+    this.textContent.setContent(content);
+    notifyTextUpdate();
+    await this.sdk.renderPage(this.textPage);
+    this._currentMode = 'text';
+  }
+
+  async updateText(content: string): Promise<void> {
+    if (!this._pageReady) return;
+    this.textContent.setContent(content);
+    notifyTextUpdate();
+    await this.sdk.renderPage(this.textPage);
+  }
+
+  // ── Column page (multi-column text, no bounce) ──
+
+  async showColumnPage(columns: string[]): Promise<void> {
+    if (!this._pageReady) return;
+    for (let i = 0; i < this.columnElements.length && i < columns.length; i++) {
+      this.columnElements[i]!.setContent(columns[i]!);
+    }
+    notifyTextUpdate();
+    await this.sdk.renderPage(this.columnPage);
+    this._currentMode = 'columns';
+  }
+
+  async updateColumns(columns: string[]): Promise<void> {
+    if (!this._pageReady) return;
+    for (let i = 0; i < this.columnElements.length && i < columns.length; i++) {
+      this.columnElements[i]!.setContent(columns[i]!);
+    }
+    notifyTextUpdate();
+    await this.sdk.renderPage(this.columnPage);
+  }
+
+  // ── Convenience: Watchlist (3-column layout) ──
+
+  async switchToWatchlist(colSym: string, colPrice: string, colPct: string): Promise<boolean> {
+    if (!this._pageReady) return false;
+    try {
+      await this.showColumnPage([colSym, colPrice, colPct]);
+      return true;
+    } catch { return false; }
+  }
+
+  async updateWatchlist(colSym: string, colPrice: string, colPct: string): Promise<void> {
+    await this.updateColumns([colSym, colPrice, colPct]);
+  }
+
+  // ── Convenience: Settings (full-screen text) ──
+
+  async switchToSettings(text: string): Promise<boolean> {
+    if (!this._pageReady) return false;
+    try {
+      await this.showTextPage(text);
+      return true;
+    } catch { return false; }
+  }
+
+  async updateSettings(text: string): Promise<void> {
+    await this.updateText(text);
+  }
+
+  // ── Home page (N images + empty overlay + menu text containers, no bounce) ──
+
+  async switchToHomeLayout(menuText: string, imageTiles?: { id: number; name: string; x: number; y: number; w: number; h: number }[]): Promise<boolean> {
+    if (!this.rawBridge || !this._pageReady) return false;
+    try {
+      await this.showHomePage(menuText, imageTiles);
+      return true;
+    } catch { return false; }
+  }
+
+  async showHomePage(menuText: string, imageTiles?: { id: number; name: string; x: number; y: number; w: number; h: number }[]): Promise<void> {
+    if (!this.rawBridge || !this._pageReady) return;
+    await this.sdk.renderPage(this.chartDummyPage);
+
+    const tiles = imageTiles && imageTiles.length > 0 ? imageTiles : [];
+
+    // Text starts below the first image tile (persistent logo tile).
+    // Extra tiles (e.g. splash "Loading...") overlap with text area — cleared with black on transition.
+    const textY = tiles.length > 0 ? tiles[0]!.y + tiles[0]!.h : 0;
+
+    await this.rawBridge.rebuildPageContainer(
+      new RebuildPageContainer({
+        containerTotalNum: 2 + tiles.length,
+        textObject: [
+          new TextContainerProperty({
+            containerID: 1, containerName: 'overlay',
+            xPosition: 0, yPosition: 0, width: DISPLAY_W, height: DISPLAY_H,
+            borderWidth: 0, borderColor: 0, paddingLength: 0,
+            content: '', isEventCapture: 1,
+          }),
+          new TextContainerProperty({
+            containerID: 5, containerName: 'menu',
+            xPosition: 0, yPosition: textY, width: DISPLAY_W, height: DISPLAY_H - textY,
+            borderWidth: 0, borderColor: 0, paddingLength: 6,
+            content: menuText, isEventCapture: 0,
+          }),
+        ],
+        imageObject: tiles.map(t =>
+          new ImageContainerProperty({
+            containerID: t.id, containerName: t.name,
+            xPosition: t.x, yPosition: t.y, width: t.w, height: t.h,
+          }),
+        ),
+      }),
+    );
+    this._currentMode = 'home';
+  }
+
+  async updateHomeText(content: string): Promise<void> {
+    if (!this.rawBridge || !this._pageReady || this._currentMode !== 'home') return;
+    notifyTextUpdate();
+    await this.rawBridge.textContainerUpgrade(
+      new TextContainerUpgrade({
+        containerID: 5, containerName: 'menu',
+        contentOffset: 0, contentLength: 2000, content,
+      }),
+    );
+  }
+
+  // ── Chart page (3 image tiles + 1 text = 4 containers) ──
+
+  async switchToChartLayout(topText: string): Promise<boolean> {
+    if (!this.rawBridge || !this._pageReady) return false;
+    if (this._currentMode === 'chart') return true;
+    try {
+      await this.showChartPage(topText);
+      return true;
+    } catch { return false; }
+  }
+
+  async showChartPage(topText: string): Promise<void> {
+    if (!this.rawBridge || !this._pageReady) return;
+    if (this._currentMode === 'chart') return;
+    await this.sdk.renderPage(this.chartDummyPage);
+    await this.rawBridge.rebuildPageContainer(
+      new RebuildPageContainer({
+        containerTotalNum: 4,
+        textObject: [
+          new TextContainerProperty({
+            containerID: CHART_TEXT.id, containerName: CHART_TEXT.name,
+            xPosition: CHART_TEXT.x, yPosition: CHART_TEXT.y,
+            width: CHART_TEXT.w, height: CHART_TEXT.h,
+            borderWidth: 0, borderColor: 0, paddingLength: 0,
+            content: topText, isEventCapture: 1,
+          }),
+        ],
+        imageObject: IMAGE_TILES.map((t) =>
+          new ImageContainerProperty({
+            containerID: t.id, containerName: t.name,
+            xPosition: t.x, yPosition: t.y, width: t.w, height: t.h,
+          }),
+        ),
+      }),
+    );
+    this._currentMode = 'chart';
+  }
+
+  async updateChartText(content: string): Promise<void> {
+    if (!this.rawBridge || !this._pageReady || this._currentMode !== 'chart') return;
+    notifyTextUpdate();
+    await this.rawBridge.textContainerUpgrade(
+      new TextContainerUpgrade({
+        containerID: CHART_TEXT.id, containerName: CHART_TEXT.name,
+        contentOffset: 0, contentLength: 2000, content,
+      }),
+    );
+  }
+
+  // ── Image sending (for home + chart modes) ──
+
+  async sendImage(containerID: number, containerName: string, pngBytes: Uint8Array): Promise<void> {
+    if (!this.rawBridge || !this._pageReady || this._currentMode === 'text' || this._currentMode === 'columns' || pngBytes.length === 0) return;
+    await this.rawBridge.updateImageRawData(
+      new ImageRawDataUpdate({ containerID, containerName, imageData: pngBytes }),
+    );
+  }
+
+  // ── Events ──
+
+  onEvent(handler: (event: EvenHubEvent) => void): void {
+    this.sdk.addEventListener(handler);
+  }
+
+  dispose(): void {
+    this.rawBridge = null;
+  }
+}

package/glasses/canvas-renderer.ts

@@ -0,0 +1,86 @@
+import { DISPLAY_W, DISPLAY_H } from './layout';
+import { canvasToPngBytes } from './png-utils';
+import type { DisplayData, DisplayLine } from './types';
+
+const FONT_SIZE = 22;
+const LINE_HEIGHT = 28;
+const PADDING_LEFT = 12;
+const PADDING_TOP = 8;
+const FONT = `${FONT_SIZE}px "Courier New", monospace`;
+
+let canvas: HTMLCanvasElement | null = null;
+let ctx: CanvasRenderingContext2D | null = null;
+
+function ensureCanvas(): CanvasRenderingContext2D {
+  if (!canvas) {
+    canvas = document.createElement('canvas');
+    canvas.width = DISPLAY_W;
+    canvas.height = DISPLAY_H;
+    const container = document.getElementById('glasses-canvas');
+    if (container) container.appendChild(canvas);
+  }
+  if (!ctx) {
+    ctx = canvas.getContext('2d')!;
+  }
+  return ctx;
+}
+
+export function getCanvas(): HTMLCanvasElement {
+  ensureCanvas();
+  return canvas!;
+}
+
+function drawLine(ctx: CanvasRenderingContext2D, line: DisplayLine, y: number): void {
+  const x = PADDING_LEFT;
+
+  if (line.style === 'separator') {
+    ctx.strokeStyle = '#333333';
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    ctx.moveTo(x, y + LINE_HEIGHT / 2);
+    ctx.lineTo(DISPLAY_W - PADDING_LEFT, y + LINE_HEIGHT / 2);
+    ctx.stroke();
+    return;
+  }
+
+  if (line.inverted) {
+    ctx.fillStyle = '#606060';
+    ctx.fillRect(0, y, DISPLAY_W, LINE_HEIGHT);
+    ctx.fillStyle = '#000000';
+    ctx.font = FONT;
+    ctx.fillText(line.text, x, y + FONT_SIZE);
+    return;
+  }
+
+  ctx.font = FONT;
+
+  switch (line.style) {
+    case 'meta':
+      ctx.fillStyle = '#808080';
+      break;
+    case 'normal':
+    default:
+      ctx.fillStyle = '#e0e0e0';
+      break;
+  }
+
+  ctx.fillText(line.text, x, y + FONT_SIZE);
+}
+
+export function drawToCanvas(data: DisplayData): void {
+  const c = ensureCanvas();
+
+  c.fillStyle = '#000000';
+  c.fillRect(0, 0, DISPLAY_W, DISPLAY_H);
+
+  let y = PADDING_TOP;
+  for (const line of data.lines) {
+    drawLine(c, line, y);
+    y += LINE_HEIGHT;
+  }
+}
+
+export async function renderToImage(data: DisplayData): Promise<number[]> {
+  drawToCanvas(data);
+  return canvasToPngBytes(canvas!);
+}

package/glasses/composer.ts

@@ -0,0 +1,69 @@
+import {
+  CreateStartUpPageContainer,
+  RebuildPageContainer,
+  ImageContainerProperty,
+  TextContainerProperty,
+} from '@evenrealities/even_hub_sdk';
+import { MAIN_SLOT, dummySlot } from './layout';
+
+function imageContainer(): ImageContainerProperty {
+  return new ImageContainerProperty({
+    containerID: MAIN_SLOT.id,
+    containerName: MAIN_SLOT.name,
+    xPosition: MAIN_SLOT.x,
+    yPosition: MAIN_SLOT.y,
+    width: MAIN_SLOT.w,
+    height: MAIN_SLOT.h,
+  });
+}
+
+function eventCaptureContainer(): TextContainerProperty {
+  return new TextContainerProperty({
+    containerID: 2,
+    containerName: 'events',
+    xPosition: MAIN_SLOT.x,
+    yPosition: MAIN_SLOT.y,
+    width: MAIN_SLOT.w,
+    height: MAIN_SLOT.h,
+    borderWidth: 0,
+    borderColor: 0,
+    borderRdaius: 0,
+    paddingLength: 0,
+    content: '',
+    isEventCapture: 1,
+  });
+}
+
+function dummy(): TextContainerProperty {
+  const s = dummySlot(2);
+  return new TextContainerProperty({
+    containerID: s.id,
+    containerName: s.name,
+    xPosition: s.x,
+    yPosition: s.y,
+    width: s.w,
+    height: s.h,
+    borderWidth: 0,
+    borderColor: 0,
+    borderRdaius: 0,
+    paddingLength: 0,
+    content: '',
+    isEventCapture: 0,
+  });
+}
+
+export function composeStartupPage(): CreateStartUpPageContainer {
+  return new CreateStartUpPageContainer({
+    containerTotalNum: 3,
+    imageObject: [imageContainer()],
+    textObject: [eventCaptureContainer(), dummy()],
+  });
+}
+
+export function composeRebuildPage(): RebuildPageContainer {
+  return new RebuildPageContainer({
+    containerTotalNum: 3,
+    imageObject: [imageContainer()],
+    textObject: [eventCaptureContainer(), dummy()],
+  });
+}

package/glasses/gestures.ts

@@ -0,0 +1,60 @@
+const TAP_COOLDOWN_MS = 220;
+const TAP_DUPLICATE_DEBOUNCE_MS = 90;
+const DOUBLE_TAP_DUPLICATE_DEBOUNCE_MS = 140;
+const SCROLL_SUPPRESS_AFTER_TAP_MS = 110;
+
+// Tuned for G2 hardware — prevents double-scroll from duplicate events
+const SAME_DIRECTION_DEBOUNCE_MS = 350;
+const DIRECTION_CHANGE_DEBOUNCE_MS = 50;
+const SCROLL_SUPPRESS_AFTER_TEXT_MS = 80;
+
+let lastTapTime = 0;
+let lastTapKind: 'tap' | 'double' | null = null;
+
+export function tryConsumeTap(kind: 'tap' | 'double'): boolean {
+  const now = Date.now();
+  const elapsed = now - lastTapTime;
+  const duplicateMs =
+    kind === 'double' ? DOUBLE_TAP_DUPLICATE_DEBOUNCE_MS : TAP_DUPLICATE_DEBOUNCE_MS;
+
+  if (kind === lastTapKind && elapsed < duplicateMs) {
+    return false;
+  }
+
+  if (elapsed < TAP_COOLDOWN_MS && lastTapKind !== null) {
+    return false;
+  }
+
+  lastTapTime = now;
+  lastTapKind = kind;
+  return true;
+}
+
+export function isScrollSuppressed(): boolean {
+  return Date.now() - lastTapTime < SCROLL_SUPPRESS_AFTER_TAP_MS;
+}
+
+let lastScrollTime = 0;
+let lastScrollDir: 'prev' | 'next' | null = null;
+let textUpdateTime = 0;
+
+/** Call after every text container update to suppress spurious G2 scroll events */
+export function notifyTextUpdate(): void {
+  textUpdateTime = Date.now();
+}
+
+export function isScrollDebounced(direction: 'prev' | 'next'): boolean {
+  const now = Date.now();
+
+  // Suppress scrolls briefly after a text update (G2 re-layout fires spurious events)
+  if (now - textUpdateTime < SCROLL_SUPPRESS_AFTER_TEXT_MS) return true;
+
+  const threshold =
+    direction === lastScrollDir ? SAME_DIRECTION_DEBOUNCE_MS : DIRECTION_CHANGE_DEBOUNCE_MS;
+
+  if (now - lastScrollTime < threshold) return true;
+
+  lastScrollTime = now;
+  lastScrollDir = direction;
+  return false;
+}

package/glasses/index.ts

@@ -0,0 +1,10 @@
+// even-g2-sdk — Shared library for Even Realities G2 glasses apps
+// Import individual modules via deep paths: 'even-g2-sdk/types', 'even-g2-sdk/bridge', etc.
+
+export * from './types';
+export * from './action-bar';
+export * from './text-utils';
+export * from './timer-display';
+export * from './gestures';
+export * from './text-clean';
+export * from './paginate-text';

package/glasses/keep-alive.ts

@@ -0,0 +1,30 @@
+let audioCtx: AudioContext | null = null;
+let oscillator: OscillatorNode | null = null;
+let lockPromise: Promise<unknown> | null = null;
+
+export function activateKeepAlive(lockName = 'evenglass_keep_alive'): void {
+  try {
+    audioCtx = new AudioContext();
+    oscillator = audioCtx.createOscillator();
+    oscillator.frequency.value = 1;
+    const gain = audioCtx.createGain();
+    gain.gain.value = 0.001;
+    oscillator.connect(gain);
+    gain.connect(audioCtx.destination);
+    oscillator.start();
+  } catch { /* ignore */ }
+
+  if (navigator.locks) {
+    lockPromise = navigator.locks.request(lockName, () => {
+      return new Promise<void>(() => {});
+    });
+  }
+}
+
+export function deactivateKeepAlive(): void {
+  oscillator?.stop();
+  audioCtx?.close();
+  oscillator = null;
+  audioCtx = null;
+  lockPromise = null;
+}