Add stats collection and first-run on-glasses onboarding app

This commit is contained in:
James Babcock committed 2026-10-10 17:33:32 -07:00
1 parent 84baee9c76
commit 406cefe0c5
73 files changed
+3906 -98

No files matched your search

+2
View File
@@ -26,6 +26,7 @@ import developerApp from "./developer";
import evenhubApp from "./evenhub";
import glanceboardApp from "./glanceboard";
import settingsApp from "./settings";
import onboardingApp from "./onboarding";
/**
* Every app, in launcher-grid order (the launcher itself is first but hidden
@@ -60,4 +61,5 @@ export const ALL_APPS: readonly AppDefinition[] = [
evenhubApp,
glanceboardApp,
settingsApp,
onboardingApp,
];
@@ -0,0 +1,75 @@
import type { GrayImage } from "../../graphics/image";
import { truncateText } from "../../graphics/textwrap";
import { dataCollectionSetting, dataCollectionSummary, type DataCollectionLevel } from "../../ui/dashboard-settings";
import type { InputEvent } from "../../ui/gestures";
import { Menu, type MenuDrawArgs } from "../../ui/menu-core";
import { LIST_ROW_TEXT_INSET, listRowHeight } from "../../ui/metrics";
import { onboardingFont } from "./onboarding-fonts";
import { drawPageHeading, PAGE_X, type OnboardingNav, type OnboardingPage } from "./onboarding-page";
const CONTENT_GAP = 10;
const BOTTOM_MARGIN = 8;
const LABEL_GAP = 24;
/** None / Minimal / Full, each with a one-line summary; a tap saves the selected level. */
export class DataCollectionPage implements OnboardingPage {
/** Width of the level-name column, measured each paint. */
private labelColumnWidth = 0;
private readonly menu = new Menu<DataCollectionLevel>({
items: dataCollectionSetting.values,
wrap: false,
rowGap: 2,
highlight: { radius: 8 },
getHeight: () => listRowHeight(onboardingFont("body")),
draw: (args) => this.drawRow(args),
});
enter(): void {
this.menu.select(dataCollectionSetting.values.indexOf(dataCollectionSetting.get()));
}
paint(image: GrayImage, focused: boolean): void {
const top = drawPageHeading(
image,
"Data collection",
"Choose what Faceclaw may send its developers to help fix problems and improve the app. " +
"You can change this later in Settings > Privacy.",
3,
) + CONTENT_GAP;
const body = onboardingFont("body");
this.labelColumnWidth =
Math.max(...dataCollectionSetting.values.map((level) => body.measureText(dataCollectionSetting.displayValue(level)))) +
LABEL_GAP;
this.menu.paint(
image,
{ x: PAGE_X - 10, y: top, width: image.width - 2 * (PAGE_X - 10), height: image.height - top - BOTTOM_MARGIN },
focused,
);
}
handleInput(event: InputEvent, nav: OnboardingNav): void {
switch (event.type) {
case "scroll-up":
case "scroll-down":
void this.menu.handleInput(event);
return;
case "click": {
const level = this.menu.selectedItem;
if (level !== null) dataCollectionSetting.set(level);
nav.next();
return;
}
default:
return;
}
}
private drawRow({ image, item: level, x, y, width, height, selected }: MenuDrawArgs<DataCollectionLevel>): void {
const body = onboardingFont("body");
const detail = onboardingFont("detail");
image.drawText(body, x + 10, y + LIST_ROW_TEXT_INSET, dataCollectionSetting.displayValue(level), selected ? 255 : 200);
const summaryX = x + 10 + this.labelColumnWidth;
const summary = truncateText(detail, dataCollectionSummary(level), x + width - 10 - summaryX);
image.drawText(detail, summaryX, y + Math.round((height - detail.lineHeight) / 2), summary, selected ? 210 : 150);
}
}
+17
View File
@@ -0,0 +1,17 @@
import { type AppDefinition } from "../app-definition";
import { createOnboardingAppWindow, ONBOARDING_SURFACE_ID, ONBOARDING_WINDOW_ID } from "./onboarding-app";
import { ONBOARDING_APP_ID } from "./onboarding-progress";
/**
* First-run setup on the glasses: welcome, text size, data-collection
* preference. The connection controllers open it on their own when it is
* due (claimGlassesOnboardingAutoLaunch); the launcher entry reruns it.
*/
const onboardingApp: AppDefinition = {
appId: ONBOARDING_APP_ID,
title: "Onboarding",
icon: "sparkles",
launch: (ctx) => ctx.launchInProcessApp(ONBOARDING_WINDOW_ID, ONBOARDING_SURFACE_ID, createOnboardingAppWindow),
};
export default onboardingApp;
+98
View File
@@ -0,0 +1,98 @@
import { GrayImage } from "../../graphics/image";
import type { InputEvent } from "../../ui/gestures";
import type { Layer, LayerActions, LayerContext } from "../../ui/layers";
import { createInProcessWindow, type InProcessAppOptions, type InProcessWindow } from "../../ui/shell/in-process-window";
import { shell } from "../../ui/shell/shell";
import { findSoundEffect, playSoundEffect } from "../../ui/sound-effects";
import { DataCollectionPage } from "./data-collection-page";
import { markGlassesOnboardingFinished, ONBOARDING_APP_ID } from "./onboarding-progress";
import type { OnboardingPage } from "./onboarding-page";
import { TextSizePage } from "./text-size-page";
import { WelcomePage } from "./welcome-page";
export const ONBOARDING_WINDOW_ID = "onboarding";
export const ONBOARDING_SURFACE_ID = "window:onboarding";
/**
* The on-glasses onboarding: a fixed sequence of pages, opened automatically
* on the first connection after phone-side setup and after each upgrade
* (see onboarding-progress.ts), and from the launcher any time. Finishing
* the last page records this version as onboarded and closes the window;
* closing it early leaves onboarding due.
*/
export function createOnboardingAppWindow(options: InProcessAppOptions): InProcessWindow {
const pages: OnboardingPage[] = [new WelcomePage(), new TextSizePage(), new DataCollectionPage()];
const app = createInProcessWindow({
appId: ONBOARDING_APP_ID,
windowId: ONBOARDING_WINDOW_ID,
title: "Onboarding",
iconLetter: "On",
icon: "sparkles",
closeable: true,
actions: options.actions,
baseLayer: new OnboardingLayer(pages, () => {
markGlassesOnboardingFinished();
shell.closeWindow(ONBOARDING_WINDOW_ID);
}),
submitFrame: options.submitFrame,
setSurfaceVisible: options.setSurfaceVisible,
removeSurface: options.removeSurface,
reconfigureSurface: options.reconfigureSurface,
onClosed: options.onClosed,
});
playWelcomeSound(options.actions);
return app;
}
/** The celebratory jingle that greets the welcome page (formerly played on the first connection). */
function playWelcomeSound(actions: LayerActions): void {
const effect = findSoundEffect("questcomplete");
if (!effect) return;
playSoundEffect(
effect,
(payload) => actions.playBuzzerSequence(payload),
(ms) => new Promise((resolve) => setTimeout(resolve, ms)),
).catch((error) => console.warn(`onboarding welcome sound failed: ${error}`));
}
/**
* Hosts the current page. Double-click steps back a page, or leaves the app
* from the first one (the standard yield to the app switcher); every other
* gesture goes to the page.
*/
class OnboardingLayer implements Layer {
private index = 0;
constructor(
private readonly pages: readonly OnboardingPage[],
private readonly finish: () => void,
) {
pages[0]!.enter?.();
}
paint(ctx: LayerContext): GrayImage {
const { width, height } = ctx.stack.getBaseSize();
const image = new GrayImage(width, height, 0);
this.pages[this.index]!.paint(image, ctx.stack.isFocused());
return image;
}
async handleInput(event: InputEvent): Promise<void> {
if (event.type === "double-click") {
if (this.index === 0) shell.yieldFocusToSidebar();
else this.show(this.index - 1);
return;
}
await this.pages[this.index]!.handleInput(event, { next: () => this.next() });
}
private next(): void {
if (this.index + 1 < this.pages.length) this.show(this.index + 1);
else this.finish();
}
private show(index: number): void {
this.index = index;
this.pages[index]!.enter?.();
}
}
+38
View File
@@ -0,0 +1,38 @@
/**
* The onboarding's own fonts: bundled Roboto at fixed sizes, deliberately
* not the user's UI font, so the pages are readable before (and while) the
* text size is being chosen. Bitmap Terminus stands in where TTF rendering
* is unavailable.
*/
import { getFont, getTerminusFont } from "../../graphics/bdffont";
import type { UiFont } from "../../graphics/image";
import { ensurePreinstalledFonts, installedFontPath } from "../../graphics/installed-fonts";
import { TtfFont } from "../../graphics/ttf-font";
export type OnboardingFontRole = "hero" | "title" | "body" | "detail";
const ROLE_FONTS: Record<OnboardingFontRole, { file: string; size: number; fallback: () => UiFont }> = {
/** The welcome page's "Faceclaw". */
hero: { file: "Roboto-Regular.ttf", size: 44, fallback: () => getFont("terminus32") },
/** Page titles. */
title: { file: "Roboto-Regular.ttf", size: 26, fallback: () => getFont("terminus24") },
/** Prompts and choices. */
body: { file: "Roboto-Regular.ttf", size: 20, fallback: () => getTerminusFont(20, false) ?? getFont("terminus16") },
/** Explanations under titles and beside choices. */
detail: { file: "Roboto-Regular.ttf", size: 16, fallback: () => getFont("terminus16") },
};
let fontsEnsured = false;
export function onboardingFont(role: OnboardingFontRole): UiFont {
if (!fontsEnsured) {
fontsEnsured = true;
try {
ensurePreinstalledFonts(); // onboarding may be the first thing to draw TTF text
} catch (error) {
console.warn(`onboarding font preinstall failed: ${error}`);
}
}
const spec = ROLE_FONTS[role];
return TtfFont.load(installedFontPath(spec.file), spec.size) ?? spec.fallback();
}
+48
View File
@@ -0,0 +1,48 @@
import type { GrayImage } from "../../graphics/image";
import { wrapText } from "../../graphics/textwrap";
import type { InputEvent } from "../../ui/gestures";
import { onboardingFont } from "./onboarding-fonts";
/** Page-to-flow navigation, handed to a page's input handler. */
export type OnboardingNav = {
/** Go to the next page, or finish onboarding from the last one. */
next: () => void;
};
/**
* One onboarding step. The flow owns the page list, back navigation
* (double-click) and finishing; a page paints itself into the window's
* viewport and handles every other gesture.
*/
export interface OnboardingPage {
/** The page became current, going forward or back. */
enter?(): void;
paint(image: GrayImage, focused: boolean): void;
handleInput(event: InputEvent, nav: OnboardingNav): void | Promise<void>;
}
/** Left margin and title position shared by the pages (the UI-wide (18, 10) title spot). */
export const PAGE_X = 18;
export const TITLE_Y = 10;
/**
* Draw a page's title and its wrapped explanation (at most `maxLines`
* lines) in the onboarding fonts. Returns the y just below the explanation.
*/
export function drawPageHeading(
image: GrayImage,
title: string,
explanation: string,
maxLines = 2,
): number {
const titleFont = onboardingFont("title");
const detailFont = onboardingFont("detail");
image.drawText(titleFont, PAGE_X, TITLE_Y, title, 230);
let y = TITLE_Y + titleFont.lineHeight + 2;
const lines = wrapText(detailFont, explanation, image.width - 2 * PAGE_X).slice(0, maxLines);
for (const line of lines) {
image.drawText(detailFont, PAGE_X, y, line, 160);
y += detailFont.lineHeight;
}
return y;
}
@@ -0,0 +1,34 @@
/**
* Whether the on-glasses onboarding is due: it is recorded as finished per
* Faceclaw version, so it runs on the first connection after phone-side
* setup and again after any upgrade. The key shares the phone onboarding's
* "onboarding." prefix so scripts/resetOnboarding.sh clears it too.
*/
import { getStringSetting, setStringSetting } from "../../native/settings-store";
import { FACECLAW_VERSION } from "../../version";
export const ONBOARDING_APP_ID = "onboarding";
const FINISHED_VERSION_KEY = "onboarding.glassesFinishedVersion";
export function isGlassesOnboardingDue(): boolean {
return getStringSetting(FINISHED_VERSION_KEY, "") !== FACECLAW_VERSION;
}
export function markGlassesOnboardingFinished(): void {
setStringSetting(FINISHED_VERSION_KEY, FACECLAW_VERSION);
}
let autoLaunchChecked = false;
/**
* Asked by the connection controllers on each rendered frame (the session
* is warm by then, so the onboarding's welcome jingle won't be dropped).
* True at most once per run, and only when onboarding is due: closing it
* unfinished brings it back on the next app start, not on every reconnect.
*/
export function claimGlassesOnboardingAutoLaunch(): boolean {
if (autoLaunchChecked) return false;
autoLaunchChecked = true;
return isGlassesOnboardingDue();
}
+159
View File
@@ -0,0 +1,159 @@
import { GrayImage, type UiFont } from "../../graphics/image";
import { installedFontPath } from "../../graphics/installed-fonts";
import { wrapText } from "../../graphics/textwrap";
import { TtfFont } from "../../graphics/ttf-font";
import {
fontSelectionLabel,
getDefaultSmallFont,
getUiFontSelection,
setUiFontSelection,
uiFontSizeAllowed,
} from "../../graphics/ui-fonts";
import { FONT_SIZE_CHOICES } from "../../ui/font-picker";
import type { InputEvent } from "../../ui/gestures";
import { Menu, MENU_HIGHLIGHT_FILL, MENU_HIGHLIGHT_STROKE, type MenuBox, type MenuDrawArgs } from "../../ui/menu-core";
import { LIST_ROW_TEXT_INSET, listRowHeight } from "../../ui/metrics";
import { onboardingFont } from "./onboarding-fonts";
import { drawPageHeading, PAGE_X, type OnboardingNav, type OnboardingPage } from "./onboarding-page";
const CONTENT_GAP = 10;
const BOTTOM_MARGIN = 8;
const SIZE_COLUMN_WIDTH = 84;
const COLUMN_GAP = 12;
const PREVIEW_PADDING = 10;
const ROW_GAP = 2;
const PREVIEW_TEXT = "This is how text will look on your glasses.";
/** Drawn while they fit, so smaller sizes visibly show more rows. */
const PREVIEW_ROWS = ["Timers", "Weather", "Music", "Settings", "Files"];
/** The UI font's face, as far as this page is concerned: resizable (TTF) or not (bitmap). */
type Face =
| { kind: "sized"; file: string; path: string; sizes: number[] }
| { kind: "fixed"; label: string };
/**
* The UI font's size, over a preview of list rows and body text in the
* chosen size. The face and weight stay as they are (they live in the
* Settings font picker); a bitmap face has only one size, so the page just
* says so. The size is saved on tap, not while scrolling.
*/
export class TextSizePage implements OnboardingPage {
private face: Face = { kind: "fixed", label: "Terminus" };
private readonly sizeMenu = new Menu<number>({
wrap: false,
rowGap: ROW_GAP,
highlight: { radius: 8 },
getHeight: () => listRowHeight(onboardingFont("body")),
draw: (args) => this.drawSizeRow(args),
});
enter(): void {
// Re-read on every visit: the face may have changed in Settings meanwhile.
const selection = getUiFontSelection();
if (selection.kind === "ttf") {
const path = installedFontPath(selection.file);
const sizes = FONT_SIZE_CHOICES.filter((size) => uiFontSizeAllowed(path, size));
if (sizes.length) {
this.face = { kind: "sized", file: selection.file, path, sizes };
this.sizeMenu.setItems(sizes, nearestIndex(sizes, selection.size));
return;
}
}
// An unloadable TTF selection renders as Terminus, so call it that.
this.face = { kind: "fixed", label: selection.kind === "bitmap" ? fontSelectionLabel(selection) : "Terminus" };
}
paint(image: GrayImage, focused: boolean): void {
if (this.face.kind === "fixed") {
const top = drawPageHeading(
image,
"Text size",
`Your UI font, ${this.face.label}, comes in one size. To choose a size, pick a different font in ` +
"Settings > Customization. Tap to continue.",
3,
) + CONTENT_GAP;
drawPreview(image, getDefaultSmallFont(), {
x: PAGE_X - 10,
y: top,
width: image.width - 2 * (PAGE_X - 10),
height: image.height - top - BOTTOM_MARGIN,
});
return;
}
const top = drawPageHeading(
image,
"Text size",
"Swipe to choose a size, then tap to continue. The typeface and weight can be changed in Settings.",
) + CONTENT_GAP;
const height = image.height - top - BOTTOM_MARGIN;
const menuBox = { x: PAGE_X - 10, y: top, width: SIZE_COLUMN_WIDTH, height };
this.sizeMenu.paint(image, menuBox, focused);
const previewX = menuBox.x + menuBox.width + COLUMN_GAP;
const size = this.sizeMenu.selectedItem;
const font = (size !== null ? TtfFont.load(this.face.path, size) : null) ?? getDefaultSmallFont();
drawPreview(image, font, { x: previewX, y: top, width: image.width - (PAGE_X - 10) - previewX, height });
}
handleInput(event: InputEvent, nav: OnboardingNav): void {
switch (event.type) {
case "scroll-up":
case "scroll-down":
if (this.face.kind === "sized") void this.sizeMenu.handleInput(event);
return;
case "click":
this.save();
nav.next();
return;
default:
return;
}
}
private save(): void {
const size = this.sizeMenu.selectedItem;
if (this.face.kind !== "sized" || size === null) return;
const current = getUiFontSelection();
if (current.kind === "ttf" && current.file === this.face.file && current.size === size) return;
setUiFontSelection({ kind: "ttf", file: this.face.file, size });
}
private drawSizeRow({ image, item: size, x, y, selected }: MenuDrawArgs<number>): void {
image.drawText(onboardingFont("body"), x + 10, y + LIST_ROW_TEXT_INSET, `${size} px`, selected ? 255 : 190);
}
}
/** A framed sample in `font`: a sentence, then menu rows with the first one selected, as many as fit. */
function drawPreview(image: GrayImage, font: UiFont, box: MenuBox): void {
image.drawRoundedRect(box.x, box.y, box.width, box.height, 60, 8);
const left = box.x + PREVIEW_PADDING;
const width = box.width - 2 * PREVIEW_PADDING;
const bottom = box.y + box.height - PREVIEW_PADDING;
let y = box.y + PREVIEW_PADDING;
for (const line of wrapText(font, PREVIEW_TEXT, width)) {
if (y + font.lineHeight > bottom) return;
image.drawText(font, left, y, line, 220);
y += font.lineHeight;
}
y += PREVIEW_PADDING;
const rowHeight = listRowHeight(font);
for (let index = 0; index < PREVIEW_ROWS.length; index++) {
if (y + rowHeight - ROW_GAP > bottom) return;
const label = PREVIEW_ROWS[index]!;
if (index === 0) {
const row = new GrayImage(width, rowHeight - ROW_GAP, 0);
row.drawText(font, 10, LIST_ROW_TEXT_INSET, label, 255);
image.drawMenuSelection(row, left, y, MENU_HIGHLIGHT_FILL, MENU_HIGHLIGHT_STROKE, 8, 0);
} else {
image.drawText(font, left + 10, y + LIST_ROW_TEXT_INSET, label, 200);
}
y += rowHeight;
}
}
function nearestIndex(values: readonly number[], target: number): number {
let best = 0;
for (let index = 1; index < values.length; index++) {
if (Math.abs(values[index]! - target) < Math.abs(values[best]! - target)) best = index;
}
return best;
}
+51
View File
@@ -0,0 +1,51 @@
import type { GrayImage, UiFont } from "../../graphics/image";
import { getFullLogo } from "../../graphics/logo";
import { wrapText } from "../../graphics/textwrap";
import type { InputEvent } from "../../ui/gestures";
import { FACECLAW_VERSION } from "../../version";
import { onboardingFont } from "./onboarding-fonts";
import { PAGE_X, type OnboardingNav, type OnboardingPage } from "./onboarding-page";
const LOGO_MAX_HEIGHT = 180;
const LOGO_MARGIN = 12;
const LOGO_TEXT_GAP = 28;
const PROMPT_GAP = 22;
const PROMPT = "Tap the ring or touchpad to continue";
type TextLine = { font: UiFont; text: string; value: number; spaceBefore: number };
/** The splash: logo beside the name, version and how to go on, centred as one group. */
export class WelcomePage implements OnboardingPage {
paint(image: GrayImage): void {
const { width, height } = image;
const logo = getFullLogo(Math.min(LOGO_MAX_HEIGHT, height - 2 * LOGO_MARGIN));
const logoWidth = logo ? logo.width + LOGO_TEXT_GAP : 0;
const body = onboardingFont("body");
const lines: TextLine[] = [
{ font: onboardingFont("hero"), text: "Faceclaw", value: 240, spaceBefore: 0 },
{ font: body, text: `Version ${FACECLAW_VERSION}`, value: 150, spaceBefore: 0 },
...wrapText(body, PROMPT, width - 2 * PAGE_X - logoWidth).map((text, index) => ({
font: body,
text,
value: 215,
spaceBefore: index === 0 ? PROMPT_GAP : 0,
})),
];
const textWidth = Math.max(...lines.map((line) => line.font.measureText(line.text)));
const textHeight = lines.reduce((total, line) => total + line.spaceBefore + line.font.lineHeight, 0);
const left = Math.max(PAGE_X, Math.round((width - logoWidth - textWidth) / 2));
if (logo) {
image.bitBlt(logo, left, Math.round((height - logo.height) / 2), { transparentZero: true });
}
let y = Math.round((height - textHeight) / 2);
for (const line of lines) {
y += line.spaceBefore;
image.drawText(line.font, left + logoWidth, y, line.text, line.value);
y += line.font.lineHeight;
}
}
handleInput(event: InputEvent, nav: OnboardingNav): void {
if (event.type === "click") nav.next();
}
}