@condorinst/mobile-bridge 0.22.0 → 0.23.0

package/docs/agent-guide.md

@@ -1,267 +1,11 @@
-# Agent guide — building a Canvas client
+# Agent guide — merged into AGENTS.md
 
-A working procedure for an AI agent (or a developer) building the client bundle
-that renders as the Home of a Condor Canvas app.
+This page used to repeat `AGENTS.md` as a staged procedure. Two copies of the
+same rules drifted apart, so there is now one of each:
 
-Read `AGENTS.md` first — it is the contract in one screen. This document is the
-procedure: what to do, in what order, and what to check at each stage.
-
-## What you are building
-
-One `.zip` containing one self-contained `index.html`. Condor's app downloads
-it, verifies its SHA-256, and renders it inside a sandboxed iframe as the Home
-screen. Login, settings, Bluetooth and background collection are the app's job.
-Yours is what the person sees when the app opens.
-
-You are not building a website. You have no storage, no network, and no origin.
-Everything you display comes through the bridge, and everything you hold lives
-in memory until the next reload.
-
-## Stage 0 — set up so you can see what you are doing
-
-Start from `examples/minimal-home/` — a complete, working client with the
-reference boot sequence, and a build script that produces a single-file bundle.
-Copy it first, then install, so its `package.json` is the one you keep:
-
-```bash
-mkdir my-home && cd my-home
-npm pack @condorinst/mobile-bridge@^0.22.0 && tar -xzf condorinst-mobile-bridge-*.tgz
-cp -r package/examples/minimal-home/. . && rm -rf package condorinst-mobile-bridge-*.tgz
-npm install
-```
-
-Or, in a project you already have: `npm install @condorinst/mobile-bridge@^0.22.0`
-and copy only `src/main.ts`, `build.mjs` and `index.html` from
-`node_modules/@condorinst/mobile-bridge/examples/minimal-home/`.
-
-Pin the SDK to the minor you are building against. Below `1.0.0`, a minor can
-change the contract — `^0.22.0` gives you patches only, which is what you want.
-
-**Run it in the harness**, not in a bare browser tab:
-
-```bash
-npm run build
-npx condor-mobile-bridge dev -i dist/index.html --scenario default
-```
-
-The harness serves your bundle inside the same sandboxed iframe, shell, policy
-and CSP as the app, with a simulated native side behind it, and a dev panel to
-emit events by hand. It re-reads the file on every reload. Opening
-`dist/index.html` directly does **not** work: there is no shell, so
-`BridgeClient.handshake()` rejects at once.
-
-The scenarios reproduce what the device does to you — switch with the selector
-at the top or `--scenario`:
-
-| Scenario | Your bundle must… |
-| --- | --- |
-| `default` | render two devices |
-| `cold-start` | leave the loading screen although the first `userDevice` requests are lost |
-| `no-devices` | show an empty state when `userDevice` never answers |
-| `shared-serial` | keep two devices with the same `serialNo` apart |
-| `offline` | explain that history is unavailable without internet |
-
-Add `--native-version null` (or an older version such as `0.15.0`) to test
-your capability branches, and use the **◀ OS back** button at the top to press
-the OS back button.
-
-If you already have a dev server (Vite), mount the same harness from your own
-page with `createDevHarness()` from `@condorinst/mobile-bridge/dev` — in the
-host page only, never in the bundle (`validate` rejects that).
-
-## Stage 1 — render before you connect
-
-Write the screen so it paints correctly with **no data at all**: empty roster,
-unknown status, default language. Then fill it as events arrive.
-
-This is not a nicety. Events are emitted on attach, before your bundle exists,
-and again after the handshake — so there is always a window where you have
-nothing. A Home whose first paint depends on an event shows a blank screen on
-every cold start.
-
-## Stage 2 — handshake, and learn what this device can do
-
-```ts
-import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-
-const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
-
-const native = ack.nativeVersion;            // string | null
-const has = (min: string) => native !== null && cmp(native, min) >= 0;
-
-const canReadRawChannels = has('0.16.0');
-const canQueryTimeRange  = has('0.15.0');
-const hasLanguageKey     = has('0.14.0');
-```
-
-Or use the SDK's `versionAtLeast(ack.nativeVersion, '0.16.0')`, which does
-exactly that and returns `false` for `null`. Do not compare version strings
-lexically — `'0.9.0' > '0.16.0'` is `true` as strings and false as versions.
-
-**Do not branch on `ack.accepted`.** It is always `true`; the native side never
-refuses a handshake. Anything you gate on it is ungated.
-
-## Stage 3 — subscribe, then ask
-
-Subscribe before sending the command that triggers the reply. The reply can
-arrive before your next line runs.
-
-```ts
-BridgeClient.on(BRIDGE_KEYS.userDevice, (p) => { setDevices(p); render(); });
-BridgeClient.on(BRIDGE_KEYS.systemStatus, (s) => { setStatus(s); render(); });
-BridgeClient.on(BRIDGE_KEYS.deviceConnection, (c) => { setConnected(c); render(); });
-
-const result = await BridgeClient.requestUserDevices();
-if (result.status === 'timeout') renderEmptyState(result.hasDevices === false);
-```
-
-**Do not replace the helper with `send('userDevice')`.** The device list is
-served by the app's background service, which starts after your bundle; a
-request sent before it is up is lost, and an account with no device never gets
-a reply. The helper resends with backoff for 30 s and then tells you to show the
-empty state. Keep the `userDevice` subscription: roster changes arrive on it
-later without a request. `docs/troubleshooting.md` has the details.
-
-Read device data from the typed items: the list is `devicesConfig`, and the
-name, battery and last sync are in `devicesTelemetry` — join them on
-`deviceId`, never on `serialNo` alone.
-
-Then follow the connection state of each device:
-
-```ts
-for (const d of result.devices.devicesConfig) {
-  BridgeClient.send('deviceConnection', { type: 'add', serialNo: d.serialNo, deviceId: d.deviceId });
-}
-```
-
-`on` returns an unsubscribe function. If your UI has views that mount and
-unmount, call it — otherwise you accumulate handlers that all re-render.
-
-## Stage 4 — handle the environment honestly
-
-`systemStatus` tells you why things are not working. Surface it; do not swallow
-it.
-
-```ts
-if (status.missingEssentialPermissions.length > 0) {
-  // Background collection is OFF. This is blocking — say so.
-  renderBlockingCard(status.missingEssentialPermissions, (name) =>
-    BridgeClient.requestPermission(name));
-} else if (!status.bluetooth) {
-  renderNotice('Bluetooth is off — devices cannot be reached.');
-}
-```
-
-There is no permission-result event. After the person answers the OS prompt,
-the native side re-emits `systemStatus`; your card disappears because the array
-emptied. If you wait for a dedicated ack, you wait forever.
-
-## Stage 5 — real-time, if you need it
-
-Real-time is **off by default**, per device. Turn it on, wait for the ack, and
-only then expect the stream.
-
-```ts
-BridgeClient.on(BRIDGE_KEYS.realTime, (ack) => setRealTime(ack.serialNo, ack.value));
-BridgeClient.on(BRIDGE_KEYS.deviceLightSensors, (p) => {
-  if (p.type === 'actlumus2') { /* 14 channels */ } else { /* 10 channels */ }
-});
-
-BridgeClient.send('realTime', { serialNo, value: true });
-```
-
-`serialNo` is a **number**. A string is dropped in silence.
-
-Two devices can share a `serialNo` (an ActLumus and an ActLumus Plus). To act on
-one of them, send its `deviceId` **together with** `serialNo`, taken from the
-`userDevice` list: `BridgeClient.send('realTime', { serialNo, deviceId, value })`.
-A command with only the shared `serialNo` is ignored on purpose. Gate this on
-`nativeVersion` ≥ 0.17.0; details in `docs/bridge-contract.md`.
-
-In a raw channel, `null` means the channel does not exist on that hardware
-generation. It does not mean zero — `0.0` is a valid reading. Coercing `null`
-to `0` invents data, and has previously led to a confident, wrong conclusion
-about a device.
-
-## Stage 6 — history, if you need it
-
-```ts
-const page = await BridgeClient.fetchSensorLog({
-  requestId: crypto.randomUUID(),
-  serialNo,
-  limit: 200,
-});
-if (!page.success) return showError(page.error);   // resolves, does not reject
-renderLogs(page.logs ?? []);
-```
-
-Timestamps are **device-local**. Build ranges with local `Date` getters, never
-`toISOString()` — converting to UTC shifts every series by the timezone offset
-and produces data that looks entirely plausible.
-
-Paginate with the cursors exactly as received. They are opaque. Without a range
-the first page is the **most recent** one (go older with `endingBefore`); with
-`startTime` it is the **oldest** of the range (go newer with `startingAfter`).
-A device writes one log per period — programmable, 60 s by default — so a week
-is about 10 000 logs: use `limit: 1000` and do not assume the cadence.
-
-## Stage 7 — back button
-
-```ts
-BridgeClient.onBack(() => goBackOnePage());
-// call this on every internal navigation, not once at startup
-BridgeClient.reportNavigation(hasInternalHistory);
-```
-
-If you never report `true`, the OS back button stays with the app — which is
-the correct behaviour for a single-screen Home.
-
-## Stage 8 — build and validate
-
-```bash
-npm run build     # your bundler → dist/index.html, single chunk
-npx condor-mobile-bridge build    -i dist/index.html -o dist/bundle.zip
-npx condor-mobile-bridge validate -i dist/bundle.zip --strict
-```
-
-`validate` applies the gates the app applies plus a lint for APIs the sandbox
-blocks. A non-zero exit is a build failure. Errors mean the app would reject
-the bundle outright; warnings mean it installs and then misbehaves on the
-device, which is worse to debug.
-
-Validation is textual, so it cannot see through minification and it cannot know
-whether you checked `nativeVersion` before using a capability. A clean run is
-necessary, not sufficient.
-
-## Stage 9 — before you call it done
-
-- [ ] `validate --strict` exits 0.
-- [ ] First paint works with no events received.
-- [ ] Every capability past the baseline is guarded by a `nativeVersion` check,
-      and the `null` branch renders something sensible.
-- [ ] No spinner can hang forever — the three confirmable commands
-      (`syncTime`, `deleteMemory`, `logout`) may never ack, because the person
-      can decline.
-- [ ] No `localStorage`, no `fetch`, no `eval`. Not even behind a `try`.
-- [ ] `serialNo` is a number everywhere, and a command for a device whose `serialNo`
-      repeats on the account also carries its `deviceId` (`nativeVersion` ≥ 0.17.0).
-- [ ] Errors are reported through `BridgeClient.send('jsError', …)`, the only
-      channel out.
-- [ ] Every harness scenario passes: `default`, `cold-start`, `no-devices`,
-      `shared-serial`, `offline`.
-- [ ] The `nativeVersion === null` branch renders something sensible.
-
-## Delivery
-
-Hand Condor the `.zip` along with its size and `sha256-<hex>` hash, both printed
-by the `build` command. The app verifies the hash against the manifest and
-rejects any mismatch. Condor publishes it for your company, which reaches every
-user of that company — test on a development test company first.
-`docs/device-testing.md` explains the path to the phone and how to inspect the
-bundle there; `docs/pilot-onboarding.md` has the full checklist.
-
-## When something does not work
-
-`docs/troubleshooting.md`, which starts from the symptom. The most common one
-is that a command did nothing and said nothing — there are six distinct causes
-for that, and they are enumerated there.
+- **The procedure** — setup, boot sequence, harness, validation, definition of
+  done: [`AGENTS.md`](../AGENTS.md).
+- **What every key, command, ack and error means**:
+  [`docs/bridge-contract.md`](./bridge-contract.md).
+- **Harness, scripted tests, `validate`, publishing, the phone**:
+  [`docs/device-testing.md`](./device-testing.md).