Building for the Even Realities G2

A practitioner's guide to the Even Hub platform, written from one shipped app.

Every entry here cost real debugging time. Almost none of it produced an error message — that is the defining property of this stack, and the reason this document is organised by symptom rather than by topic. If something is silently wrong, start with the tables.

The full story of how each one was found is in DEVELOPMENT-PAPER.md; the § column points into it.

The platform in one page

The glasses are a display and input terminal over BLE. All logic runs on the phone. You never draw pixels — you create containers (text, list, image) and update them through the SDK bridge. Your code runs as a web app inside the Even app's WebView, on the phone.

Two consequences worth internalising before designing anything:

A page render is a network round trip. rebuildPageContainer over BLE takes hundreds of milliseconds. Anything time-sensitive — opening a microphone, starting a timer — must not wait on it.

Controls and content compete for the same 288 pixels. Each button row costs ~40 px, about 1.4 lines of text. With three buttons you have roughly four lines left. Adding one convenience control can double a document's page count. This is arithmetic, not taste, and it should be done before adding the control.

Gotchas — Even Hub / glasses

Gotchas — packaging

These are the cruellest ones: none can surface against a dev server. The app works all the way through development and fails only once packaged.

Checklist before packing:

• base: './' in the Vite config
• crossorigin stripped from the built module script
• every origin whitelisted, including ws://
• min_sdk_version exactly matches the installed SDK — irreversible once shipped
• icons produced separately (monochrome, 24 × 24, fg + bg); they are portal upload assets, not manifest fields, so pack succeeds without them
• no unused permissions; each declared one maps to a real API call
• root-page double-tap calls shutDownPageContainer(1) — mode 0 or a custom confirm is rejected
• no secrets in the bundle: an .ehpk is extractable
• package_id is permanent once uploaded

Gotchas — reading messages (SMS, MMS, RCS)

Most of these are undocumented or actively contradicted by the javadoc. They were established from AOSP source and from dumping the device's own state.

Gotchas — NotificationListenerService as a data source

If your app depends on notifications for data it cannot get anywhere else, these decide what your product can honestly claim.

Gotchas — shipping it to other people

| Content unreachable after unfolding a foldable | The unfolded inner screen is shorter than the folded outer one (763dp vs 805dp on a Find N6) while being twice as wide — a page sized to fit folded clips when opened | Make pages scroll with fillViewport; use values-w600dp / layout-w600dp for the extra width | 3.30 | | A drawing pushes content off only on the big screen | Aspect-locked art scales with width, so extra width becomes extra height — on a foldable that is height you just lost | Cap art height, not just width | 3.30 |

Gotchas — Android companion app

Relevant if your plugin talks to a bridge app on the phone.

Patterns that worked

Split layout: a List for controls, a Text container for content. Text containers have no selection model, so they cannot host buttons; lists cannot render prose. Up to 8 non-image containers are allowed per page and only one captures events, so pair them — a list of buttons that takes input, a text container below it that renders the body. Page turns use textContainerUpgrade, which neither rebuilds the page nor resets the selection.

One gesture, one meaning, enforced structurally. Swipe moves the selection, tap activates it, double-tap goes back — everywhere, in one branch before any view-specific logic, so it cannot silently re-acquire exceptions. A gesture that means different things in different places is a quiz. Every other action becomes a visible, selectable, labelled row.

Paginate in rendered lines, not characters. Simulate the word wrap, count the lines, pack exactly what fits. "Paginate at 400–500 characters" is reasonable-sounding advice that fails for conversational text, which is short in characters and tall in lines. There is no metrics API — measure line height and characters-per-line off actual screenshots.

One origin everywhere. The plugin's WebView runs on the phone, so http://localhost:PORT is correct in production. Add adb forward tcp:PORT tcp:PORT and it is also correct from the desktop simulator. No dev/prod switch, therefore no untested shipped path.

Make the dangerous state unrepresentable, not guarded. When merging two identity spaces, put confident and unconfident keys in separate namespaces (tel: / short: / group: / name:). A rule like "only merge when sure" has to be remembered at every call site forever; namespaced keys make the wrong merge impossible because the strings cannot be equal. The same move applies anywhere a heuristic decides whether two things are the same thing.

Judge "read" on the display that shows it, and make persistence observable. Unread state for a glasses list belongs on the glasses — the phone's read flags describe the wrong screen (and a non-default SMS app cannot write them anyway). Seed first-run history as read so install does not produce sixty dots, but spare anything that just arrived: the message from five minutes ago is what the mark exists for, and a blanket seed swallows it. Then make the store's survival visible — one boot line, stored vs seeded — because a state store that silently fails to persist re-seeds every launch and disables the feature forever while looking exactly like a quiet day.

Name things on screen instead of marking them. A leading > to indicate direction disappears on every wrapped line, and at 42 characters most lines wrap. Prefixing each line with a short name survives wrapping.

Give a small model only the fields where vagueness is free — then measure whether it earned the download. Asked for a person's disposition, a 350M model returned "optimistic and enthusiastic", "relaxed and enjoying", "calm and content": not wrong, but constant, which carries no information while looking like it does. Asked to extract a question that was in the text verbatim, it paraphrased the question back. Counting beat it on every field that had a right answer — who opens a conversation, who writes more, when they reply, what they actually asked. Three prompt shapes over eight real threads produced at best two useful lines, against a 218 MB download. Symptoms worth recognising, because each one looks like something else:

• Offer an "if you can't tell, say so" escape hatch and a small model takes it every time — an abstention that costs nothing is the easiest token to predict.
• Give it two worked examples and it will answer an unrelated input with the example's own content, fluently and confidently.
• Require every content word in the output to appear in the source (matched on stems). This kills fabrication outright and is worth doing regardless — but it cannot make a small model interesting, only honest.
• A thinking model (Qwen3 and kin) with a small token budget spends it all on reasoning and returns an empty content. That looks exactly like a broken model. /no_think, or enable_thinking: false, is the difference between "unusable" and "fine".

Before declaring a model class unfit, separate its failures from your harness's. The paragraph above was half wrong, and the corrections are their own gotcha list:

• llama.cpp's Metal path miscomputed Granite 4.0's hybrid-Mamba blocks — every answer was a run of @. The same build on CPU was correct. An eval rig can silently corrupt exactly the model you are judging; sanity-check a new architecture on more than one backend before scoring it.
• Ground only the concrete tokens (capitalised words, numbers). Grounding every word rejects "casual" and "parenting" — correct abstractions no message contains verbatim — and quietly converts "the model is right" into "the filter says it's wrong".
• On Android, AGP's debug variant hands CMake CMAKE_BUILD_TYPE=Debug, so a fetched ggml builds at -O0 — inference runs ~20× slow and reads as "phones can't do this". Force Release and set -march=armv8.2-a+dotprod+i8mm via add_compile_options() (appending to CMAKE_CXX_FLAGS as one string makes clang parse -O3 -march=… as a single argument).
• With all three fixed, the same task the 350M failed, a 1B did usefully: ~15–30 s per conversation on a phone CPU, model opened and closed per pass so the gigabyte of RSS is transient.
• Want more than a phrase? Raise the decode budget, not the question count. Prefill is where a phone's seconds go, and it costs the same for 28 output tokens as for 200. One prompt asking for four labelled sections returns ~10× the content for ~1.5× the time; four separate questions pay for the transcript four times. Parse and ground each section independently so one invented line costs itself, exempt sentence-initial capitals from the proper-noun check ("Friendly and casual" is not a fabricated name), and filter the empty line the model keeps rephrasing ("No recent changes mentioned", "No specific plans mentioned") by shape, not by string.
• A model-written cache needs a freshness clock. Store when the model read the thread and re-queue whenever the conversation's newest message is younger — "computed once, kept forever" is how a profile of a living conversation quietly becomes fiction.

Toolchain and the three test loops

Node ^20 || >=22 (18 is not supported). npm i -g @evenrealities/evenhub-cli @evenrealities/evenhub-simulator; the binary is evenhub (alias eh). Pin the SDK exactly — it is pre-1.0: npm i --save-exact @evenrealities/even_hub_sdk@latest.

{
  "dev":   "vite",
  "sim":   "evenhub-simulator http://localhost:5173",
  "qr":    "evenhub qr --url http://$(ipconfig getifaddr en0):5173",
  "build": "vite build",
  "pack":  "evenhub pack app.json dist -o app.ehpk"
}

1. Simulator — fastest loop, no hardware. It lies in places: it allows 6 image containers where the device allows 4, and it is not pixel-accurate. Anything shippable gets tested on device.
2. On-device HMR — npm run dev + npm run qr, scan from the Even app. Requires vite.config.ts with server: { host: true, hmr: { host: '<lan-ip>' } } or the QR loads a blank page. If the phone is not on the same Wi-Fi — check, do not assume — use adb reverse tcp:5173 tcp:5173 and point the QR at http://localhost:5173; it runs over USB and ignores the network entirely.
3. Packed .ehpk — the only loop that exercises the packaging failures above. Do it before you believe anything works.

Known quirk: @evenrealities/evenhub-simulator loses its .bin symlink on install. If the binary goes missing, npm rebuild @evenrealities/evenhub-simulator.

One more silent one, from the toolchain

The site generator fed markdown to npx marked over a stdin pipe and read the HTML back over a stdout pipe. On a 105 KB document it returned exit code 0, an empty stderr, and 63 KB of the 120 KB output — node exited before its piped stdout flushed. The hosted paper served for a day with its last five sections missing, and the heading count in the build log looked plausible enough that nothing flagged it. Two fixes, both worth stealing: use marked's own -i/-o file arguments (no pipes anywhere), and assert that the HTML is at least as long as the markdown — tags only add, so anything smaller is loss, and loss with exit code 0 is the kind this platform teaches you to expect. A cousin from the same build: a page script that calls an undefined stop() does not throw — it resolves to window.stop(), which halts page loading instead of your animation. Name demo controls something the window has not already claimed.

Two habits that found most of this

Decompile rather than read the docs. javap over android.jar settled more API questions than the documentation pages did — whether an extra exists, what type a constant is, which listener callbacks are available. Where an API takes Bundle extras there is no type checking at all, so a wrong type is a silent no-op that compiles cleanly.

Record what the platform actually did, before theorising about it. Dumping the device's real notification structure produced a correct filter in one pass, after synthetic tests had passed while missing two entire categories. Recording a speech recogniser's callback sequence eliminated three of four competing hypotheses in a single request and pointed at a cause none of them contained. Both replaced multiple rounds of guessing, and in the second case two shipped non-fixes.

A corollary that cost two releases: verifying an adjacent endpoint is worse than verifying nothing. A status endpoint reported speech healthy throughout, because it checked whether an engine existed and never exercised recognition. A green check on the wrong path reads exactly like a green check on the right one.