@condorinst/mobile-bridge 0.21.0 → 0.22.0

package/docs/device-testing.md

@@ -8,10 +8,11 @@ costs, and how to see what it is doing once it is there.
 
 You do not install a bundle on a phone. The app downloads it:
 
-1. You deliver `bundle.zip`, its `bundleSize` and its `bundleHash` (printed by
-   `condor-mobile-bridge build`) to your Condor contact.
-2. Condor publishes it for **your company**. There is exactly one current
-   bundle per company.
+1. The bundle is published for **your company** — by you, with
+   `npx condor-mobile-bridge canvas publish` (below), or by your Condor
+   contact. There is exactly one current bundle per company.
+2. The server checks it on upload (2 MB, `index.html` at the root,
+   self-contained) and records its `bundleSize` and `bundleHash`.
 3. Each copy of the app asks for its company's manifest when the Home opens
    and every time the app returns to the foreground. If the `bundleHash`
    changed, it downloads the `.zip`, checks size and hash, and swaps the Home
@@ -26,24 +27,52 @@ Consequences:
   bundle, or shows its default screen, if the download fails a gate — which is
   why `validate --strict` must pass before you hand anything over.
 
-## Development and production are separate worlds
+## Test on a test company, never on your real one
 
-Condor runs a **development** environment next to production. An app build
-talks to exactly one of them, and accounts, devices and bundles do not cross
-over:
+You work against production — the store app and the production Condor system.
+Since a publish reaches every user of the company at once, ask Condor for a
+**test company** with:
 
-- a development build of the app sees only development accounts and bundles;
-- the store app sees only production.
+- a **manager** user for you, to publish (see below);
+- one or more **test accounts** with devices, to log in to the store app on
+  your phone.
 
-So, to test on a phone, ask Condor for three things that match: a **test
-account** in a **test company** in the development environment, a
-**development build** of the app (Android), and to publish your bundle **to that
-test company**. Never iterate on a production company: every publish reaches
-real people.
+Each iteration on the device is then: build → `canvas publish` to the test
+company → bring the app to the foreground. Do every iteration you can in the
+harness first, and publish to your real company only what passed there.
 
-Each iteration on the device is therefore: build → validate → hand over →
-Condor publishes → bring the app to the foreground. That is slow, so do every
-iteration you can in the harness first.
+(Condor also runs a development environment for its own staff; a client does
+not need it.)
+
+## Publishing from the command line
+
+```bash
+npx condor-mobile-bridge canvas publish dist/index.html --version 1.4.0
+```
+
+It does what the Condor web admin does, with the same login:
+
+1. It validates the bundle locally (the same gates as `validate`) and refuses
+   anything the app would reject — before sending anything.
+2. It asks for your **company id** and **user id** — the numbers you type in
+   the Condor web login — unless you pass `--company` / `--user` or set
+   `CONDOR_CANVAS_COMPANY` / `CONDOR_CANVAS_USER`.
+3. It shows the company, version, size and hash, warns that the bundle goes
+   **live at once for every user of the company**, and asks `y/N`.
+4. It asks for your **password** without echo — there is no flag or variable
+   for it, and it is never stored — and, when your company uses two-factor
+   login, for the code sent to your e-mail.
+5. It publishes and prints the result.
+
+Each version can be published once per company: publish a fix as a new
+version. `canvas list` shows the bundles of the company, and
+`canvas revoke <id> --fallback-version <v>` takes one back and serves another;
+revoking the current bundle without a fallback leaves the company on the app's
+default screen.
+
+You need a **manager** user of the company. The command needs a terminal (it
+prompts), so it does not run in CI; and an AI agent must not run it on its own
+— it publishes to real people and asks for your password.
 
 ## Seeing what the bundle does on the phone
 
@@ -74,11 +103,12 @@ logging and crash reporting (rate limited: 20 per 10 s, 4 KB per field). Those
 are Condor's tools: when you need the errors of a test session, ask your Condor
 contact, with the test account and the time window.
 
-## Before you ask for a publish
+## Before you publish
 
 - [ ] `npx condor-mobile-bridge validate -i dist/bundle.zip --strict` exits 0.
 - [ ] Every harness scenario passes (`default`, `cold-start`, `no-devices`,
       `shared-serial`, `offline`).
-- [ ] You know which environment and which company the bundle is for.
-- [ ] You sent `bundleSize` and `bundleHash` with the `.zip`, so the published
-      bundle can be checked against what you built.
+- [ ] It is going to the **test company** first, with a version number not
+      used before in that company.
+- [ ] After publishing, the `bundleHash` that `canvas publish` prints matches
+      the one `build` printed.

package/docs/pilot-onboarding.md

@@ -31,7 +31,7 @@ renders inside the app, talking to the device through the Condor bridge.
 ```bash
 npm install @condorinst/mobile-bridge
 ```
-Pin `"@condorinst/mobile-bridge": "^0.21.0"` (beta; auto-updates patches).
+Pin `"@condorinst/mobile-bridge": "^0.22.0"` (beta; auto-updates patches).
 
 ### 2. Start from the example
 Copy [`examples/minimal-home`](../examples/minimal-home) — it already wires the
@@ -76,11 +76,15 @@ sandbox and the CSP block at runtime. **A non-zero exit means do not deliver.**
 Errors are outright rejections by the app; warnings install fine and then
 misbehave on the device, which is harder to diagnose.
 
-### 6. Deliver
-Send `dist/bundle.zip`, with the `bundleSize` and `bundleHash` printed by
-`build`, through the channel Condor gave you. We publish it to your company —
-first to a **development test company**, because a publish reaches every user
-of the company.
+### 6. Publish
+With a manager user of your company:
+```bash
+npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.0
+```
+It validates, shows what goes where, asks for confirmation and your password,
+and publishes. Publish to your **test company** first: a publish reaches every
+user of the company at once. (Without a manager user, send `dist/bundle.zip`
+with its `bundleSize` and `bundleHash` to your Condor contact.)
 
 ### 7. Verify on a device
 Condor publishes → the app downloads, validates and renders your Home the next

package/examples/minimal-home/package.json

@@ -14,7 +14,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@condorinst/mobile-bridge": "^0.21.0"
+    "@condorinst/mobile-bridge": "^0.22.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @condorinst/mobile-bridge 0.21.0 — full documentation
+# @condorinst/mobile-bridge 0.22.0 — full documentation
 
 Generated from the files listed below, in reading order. Payload types are
 canonical in dist/index.d.ts; the machine-readable contract is
@@ -71,7 +71,7 @@ command (denied by policy).
 ## The golden path
 
 ```bash
-npm install @condorinst/mobile-bridge@^0.21.0
+npm install @condorinst/mobile-bridge@^0.22.0
 ```
 
 ```ts
@@ -155,6 +155,15 @@ answered and dropped. The **◀ OS back** button at the top presses the OS back
 button. `--native-version null` (or `0.15.0`, …) makes the handshake report that
 version, to test your capability branches.
 
+## Publishing — ask the human, never run it yourself
+
+`npx condor-mobile-bridge canvas publish` puts the bundle live at once for every
+user of a company, and asks for the person's password. **Do not run it.** When
+the bundle is ready, tell the human the exact command — for example
+`npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.1` — and
+recommend publishing to their **test company** first. See
+`docs/device-testing.md`.
+
 ## The validation loop — run this before you call the work done
 
 ```bash
@@ -225,17 +234,17 @@ 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.21.0 && tar -xzf condorinst-mobile-bridge-*.tgz
+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.21.0`
+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.21.0` gives you patches only, which is what you want.
+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:
 
@@ -502,7 +511,7 @@ Four numbers coexist. Only one tells you what the device can do.
 | `nativeVersion` | `0.17.0` | **The capability signal.** The bridge schema the app on this device implements. |
 | `shellVersion` | `0.6.0` | The Condor shell wrapping your iframe. |
 | client protocol | `0.5.0` | The postMessage protocol `BridgeClient` speaks. |
-| package | `0.21.0` | The npm version you compiled against. |
+| package | `0.22.0` | The npm version you compiled against. |
 
 ```ts
 const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
@@ -1077,10 +1086,11 @@ costs, and how to see what it is doing once it is there.
 
 You do not install a bundle on a phone. The app downloads it:
 
-1. You deliver `bundle.zip`, its `bundleSize` and its `bundleHash` (printed by
-   `condor-mobile-bridge build`) to your Condor contact.
-2. Condor publishes it for **your company**. There is exactly one current
-   bundle per company.
+1. The bundle is published for **your company** — by you, with
+   `npx condor-mobile-bridge canvas publish` (below), or by your Condor
+   contact. There is exactly one current bundle per company.
+2. The server checks it on upload (2 MB, `index.html` at the root,
+   self-contained) and records its `bundleSize` and `bundleHash`.
 3. Each copy of the app asks for its company's manifest when the Home opens
    and every time the app returns to the foreground. If the `bundleHash`
    changed, it downloads the `.zip`, checks size and hash, and swaps the Home
@@ -1095,24 +1105,52 @@ Consequences:
   bundle, or shows its default screen, if the download fails a gate — which is
   why `validate --strict` must pass before you hand anything over.
 
-## Development and production are separate worlds
+## Test on a test company, never on your real one
+
+You work against production — the store app and the production Condor system.
+Since a publish reaches every user of the company at once, ask Condor for a
+**test company** with:
+
+- a **manager** user for you, to publish (see below);
+- one or more **test accounts** with devices, to log in to the store app on
+  your phone.
 
-Condor runs a **development** environment next to production. An app build
-talks to exactly one of them, and accounts, devices and bundles do not cross
-over:
+Each iteration on the device is then: build → `canvas publish` to the test
+company → bring the app to the foreground. Do every iteration you can in the
+harness first, and publish to your real company only what passed there.
 
-- a development build of the app sees only development accounts and bundles;
-- the store app sees only production.
+(Condor also runs a development environment for its own staff; a client does
+not need it.)
 
-So, to test on a phone, ask Condor for three things that match: a **test
-account** in a **test company** in the development environment, a
-**development build** of the app (Android), and to publish your bundle **to that
-test company**. Never iterate on a production company: every publish reaches
-real people.
+## Publishing from the command line
 
-Each iteration on the device is therefore: build → validate → hand over →
-Condor publishes → bring the app to the foreground. That is slow, so do every
-iteration you can in the harness first.
+```bash
+npx condor-mobile-bridge canvas publish dist/index.html --version 1.4.0
+```
+
+It does what the Condor web admin does, with the same login:
+
+1. It validates the bundle locally (the same gates as `validate`) and refuses
+   anything the app would reject — before sending anything.
+2. It asks for your **company id** and **user id** — the numbers you type in
+   the Condor web login — unless you pass `--company` / `--user` or set
+   `CONDOR_CANVAS_COMPANY` / `CONDOR_CANVAS_USER`.
+3. It shows the company, version, size and hash, warns that the bundle goes
+   **live at once for every user of the company**, and asks `y/N`.
+4. It asks for your **password** without echo — there is no flag or variable
+   for it, and it is never stored — and, when your company uses two-factor
+   login, for the code sent to your e-mail.
+5. It publishes and prints the result.
+
+Each version can be published once per company: publish a fix as a new
+version. `canvas list` shows the bundles of the company, and
+`canvas revoke <id> --fallback-version <v>` takes one back and serves another;
+revoking the current bundle without a fallback leaves the company on the app's
+default screen.
+
+You need a **manager** user of the company. The command needs a terminal (it
+prompts), so it does not run in CI; and an AI agent must not run it on its own
+— it publishes to real people and asks for your password.
 
 ## Seeing what the bundle does on the phone
 
@@ -1143,14 +1181,15 @@ logging and crash reporting (rate limited: 20 per 10 s, 4 KB per field). Those
 are Condor's tools: when you need the errors of a test session, ask your Condor
 contact, with the test account and the time window.
 
-## Before you ask for a publish
+## Before you publish
 
 - [ ] `npx condor-mobile-bridge validate -i dist/bundle.zip --strict` exits 0.
 - [ ] Every harness scenario passes (`default`, `cold-start`, `no-devices`,
       `shared-serial`, `offline`).
-- [ ] You know which environment and which company the bundle is for.
-- [ ] You sent `bundleSize` and `bundleHash` with the `.zip`, so the published
-      bundle can be checked against what you built.
+- [ ] It is going to the **test company** first, with a version number not
+      used before in that company.
+- [ ] After publishing, the `bundleHash` that `canvas publish` prints matches
+      the one `build` printed.
 
 <!-- ===== docs/limits.md ===== -->
 
@@ -1340,13 +1379,13 @@ Pin the version with a caret:
 ```jsonc
 // package.json
 "dependencies": {
-  "@condorinst/mobile-bridge": "^0.21.0"
+  "@condorinst/mobile-bridge": "^0.22.0"
 }
 ```
 
-**Updates.** The SDK is on `0.x` during the pilot. With `^0.21.0`, running
-`npm install` (or your CI) auto-picks **patch** releases (`0.21.x`) — bug fixes,
-no action needed. A `0.22.0` (a larger change during beta) is an intentional
+**Updates.** The SDK is on `0.x` during the pilot. With `^0.22.0`, running
+`npm install` (or your CI) auto-picks **patch** releases (`0.22.x`) — bug fixes,
+no action needed. A `0.23.0` (a larger change during beta) is an intentional
 opt-in: you bump the range when you're ready. `1.0.0` will mark the
 production-stable contract.
 
@@ -1648,7 +1687,9 @@ bundles and falls back to a default screen, so keep under the limit.
 
 ## 7. Deliver
 
-Send the resulting `dist/bundle.zip` through the publication channel Condor
+Publish it yourself with a manager user of your company —
+`npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.0` — or
+send the resulting `dist/bundle.zip` through the publication channel Condor
 gave you (the admin upload). The backend validates structure, self-containment,
 and size on upload, and records the `bundleSize`/`bundleHash`. Once published,
 the app downloads, verifies, and renders your Home — for **every user of your
@@ -1711,7 +1752,7 @@ renders inside the app, talking to the device through the Condor bridge.
 ```bash
 npm install @condorinst/mobile-bridge
 ```
-Pin `"@condorinst/mobile-bridge": "^0.21.0"` (beta; auto-updates patches).
+Pin `"@condorinst/mobile-bridge": "^0.22.0"` (beta; auto-updates patches).
 
 ### 2. Start from the example
 Copy [`examples/minimal-home`](../examples/minimal-home) — it already wires the
@@ -1756,11 +1797,15 @@ sandbox and the CSP block at runtime. **A non-zero exit means do not deliver.**
 Errors are outright rejections by the app; warnings install fine and then
 misbehave on the device, which is harder to diagnose.
 
-### 6. Deliver
-Send `dist/bundle.zip`, with the `bundleSize` and `bundleHash` printed by
-`build`, through the channel Condor gave you. We publish it to your company —
-first to a **development test company**, because a publish reaches every user
-of the company.
+### 6. Publish
+With a manager user of your company:
+```bash
+npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.0
+```
+It validates, shows what goes where, asks for confirmation and your password,
+and publishes. Publish to your **test company** first: a publish reaches every
+user of the company at once. (Without a manager user, send `dist/bundle.zip`
+with its `bundleSize` and `bundleHash` to your Condor contact.)
 
 ### 7. Verify on a device
 Condor publishes → the app downloads, validates and renders your Home the next

package/llms.txt

@@ -7,7 +7,7 @@
 > pagination, permissions, system status and language.
 
 Every URL below is plain text over HTTPS, pinned to a released version, and
-needs no authentication. Replace `0.21.0` with the version you depend on; the
+needs no authentication. Replace `0.22.0` with the version you depend on; the
 contract changes between minors while the package is below 1.0.0.
 
 The same files ship inside the npm tarball, so if you have run
@@ -16,29 +16,29 @@ The same files ship inside the npm tarball, so if you have run
 
 ## Start here
 
-- [AGENTS.md](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/AGENTS.md): The contract in one screen — hard rules, the golden-path boot sequence, the browser harness and the validation loop. Read before writing code.
-- [llms-full.txt](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/llms-full.txt): AGENTS.md and every document under docs/ concatenated into one file, for a single fetch.
-- [Agent guide](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/docs/agent-guide.md): Step-by-step construction of a client Home, with the checks to run at each stage.
+- [AGENTS.md](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/AGENTS.md): The contract in one screen — hard rules, the golden-path boot sequence, the browser harness and the validation loop. Read before writing code.
+- [llms-full.txt](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/llms-full.txt): AGENTS.md and every document under docs/ concatenated into one file, for a single fetch.
+- [Agent guide](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/docs/agent-guide.md): Step-by-step construction of a client Home, with the checks to run at each stage.
 
 ## Reference
 
-- [Bridge contract](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/docs/bridge-contract.md): Every observable key, every command, the three error shapes, and the capability matrix by native version.
-- [Machine-readable contract](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/contract/bridge-contract.json): The same contract as JSON. Also importable as `@condorinst/mobile-bridge/contract`.
-- [Limits](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/docs/limits.md): Every hard limit — payload size, rate limits, bundle size, timeouts — with what happens when you cross it.
-- [Troubleshooting](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/docs/troubleshooting.md): Why a command did nothing, and why the device list never came. Silence is the platform's dominant failure mode.
-- [Testing on a device](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/docs/device-testing.md): How a bundle reaches the phone, development vs production, inspecting the WebView, and where errors go.
-- [TypeScript declarations](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/dist/index.d.ts): Authoritative payload shapes, with documentation on every member.
+- [Bridge contract](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/docs/bridge-contract.md): Every observable key, every command, the three error shapes, and the capability matrix by native version.
+- [Machine-readable contract](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/contract/bridge-contract.json): The same contract as JSON. Also importable as `@condorinst/mobile-bridge/contract`.
+- [Limits](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/docs/limits.md): Every hard limit — payload size, rate limits, bundle size, timeouts — with what happens when you cross it.
+- [Troubleshooting](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/docs/troubleshooting.md): Why a command did nothing, and why the device list never came. Silence is the platform's dominant failure mode.
+- [Testing on a device](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/docs/device-testing.md): How a bundle reaches the phone, development vs production, inspecting the WebView, and where errors go.
+- [TypeScript declarations](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/dist/index.d.ts): Authoritative payload shapes, with documentation on every member.
 
 ## Guides
 
-- [Client guide](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/docs/client-guide.md): Narrative walkthrough for a developer building the Home by hand.
-- [Pilot onboarding](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/docs/pilot-onboarding.md): Checklist from zero to a bundle delivered to Condor.
-- [README](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/README.md): Package overview, install, quickstart.
-- [CHANGELOG](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/CHANGELOG.md): When each capability was introduced. The most precise record of what a given native version supports.
+- [Client guide](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/docs/client-guide.md): Narrative walkthrough for a developer building the Home by hand.
+- [Pilot onboarding](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/docs/pilot-onboarding.md): Checklist from zero to a bundle delivered to Condor.
+- [README](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/README.md): Package overview, install, quickstart.
+- [CHANGELOG](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/CHANGELOG.md): When each capability was introduced. The most precise record of what a given native version supports.
 
 ## Examples
 
-- [Minimal home](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.0/examples/minimal-home/src/main.ts): A complete, working client with the reference boot sequence. Copy this as your starting point, and run it with `npx condor-mobile-bridge dev`.
+- [Minimal home](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/examples/minimal-home/src/main.ts): A complete, working client with the reference boot sequence. Copy this as your starting point, and run it with `npx condor-mobile-bridge dev`.
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@condorinst/mobile-bridge",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "TypeScript SDK for the JS↔Native bridge of the Condor white-label mobile app.",
   "license": "SEE LICENSE IN LICENSE",
   "private": false,