@wix/himalaya-cli 0.1540.0 → 0.1542.0

package/guides/himi-json-output.md

@@ -287,6 +287,16 @@ unresolved migration finding.
 - `topbar_coverage_failed`: a source top-bar control has no matching action
   with a non-empty `onTap.actionId` (exit 1).
 
+## `himi one-app validate-design` codes
+
+- `invalid_usage`: required options are missing or incompatible (exit 2).
+- `evidence_invalid`: the collected source evidence is missing or invalid (exit 1).
+- `tokens_unreadable`: the token file cannot be read, or `--fix` cannot safely write it (exit 1).
+- `design_mismatch`: a source value differs from the drawn target value (exit 1).
+- `design_unresolved`: `--record` was requested while a design value still needs an
+  adapted ledger row; no evidence is written (exit 1).
+- `record_failed`: `--record` could not safely write its private evidence files (exit 1).
+
 ## `himi one-app coverage` codes
 
 - `invalid_usage`: the mode or required paths are missing (exit 2).

package/guides/one-app-to-himi-app.md

@@ -65,7 +65,7 @@ partial artifacts are diagnostics for recovery, never a usable empty fallback.
 the complete-manifest check or provide a resume command.
 
 The migration invocation authorizes this scoped continuation: plan, local app
-implementation, necessary same-site OAuth client reconciliation, validation, and
+implementation, the same-site One App visitor binding, validation, and
 an authenticated hosted draft. Do not restart generic product discovery or add a
 generic plan-approval pause. Carry this scope through installed agent instructions
 and resume sessions. It does not authorize live promotion, native distribution,
@@ -151,6 +151,23 @@ Apply these interpretation rules:
   a feature to account for; they do not alone prove visibility or access for every
   visitor or member. Resolve those rules separately. This check is specific to this
   migration workflow; it does not change the behavior of `himi validate`.
+- Before publishing, run the migration-only design check:
+  `himi one-app validate-design --evidence-dir .himi/one-app --content .`.
+  It resolves the effective source theme with the reader the source app instance
+  actually uses, then compares the resolved primary, background and content colors
+  and each button's `borderRadius` and `outlineWidth` against the app's `tokens.json`.
+  Hex case and shorthand are normalized; an absent button token is compared with the
+  value the renderer draws (an outline only on `secondary`; a radius of `radius.pill`,
+  else 24), not called a difference. A variant without its own radius must draw the
+  source radius at every Button size. A descriptor's per-button `cornerRadius` overrides
+  the tokens and is not checked. `--fix` writes the mismatching source values into
+  `tokens.json` and pins the dark and high-contrast schemes to what they drew before,
+  because a missing scheme falls back to the light value. Rebuild after `--fix`.
+  The report names every theme pointer the check did not compare, including typography
+  kits and any button `uppercase`, which Himi tokens cannot carry; resolve those
+  explicitly rather than treating a pass as full design parity. A deliberate difference
+  is waived only by a `design` coverage row with status `adapted` that cites the user's
+  instruction and explains the change. This check compares values, not rendered screens.
 - For each configured Detailed header, import and call the shared
   `detailedHeader` builder from `@wix/himalaya/screens`. Do not recreate its
   component tree in the app. Resolve the source fallback and visibility rules
@@ -254,15 +271,17 @@ Run `himi one-app coverage init --evidence-dir .himi/one-app --content .` to
 create `ONE-APP-COVERAGE.json` from the verified source graph. After edits or a
 CLI upgrade, run `coverage sync` and review new rows; `coverage check` fails when
 the file is absent or source requirements have appeared, disappeared or changed.
-Rows cover source graph warnings as well as routes and controls. This is an
-inventory of migration obligations, not proof that their target actions work.
+Rows cover source graph warnings and app-wide design values as well as routes and
+controls. This is an inventory of migration obligations, not proof that their target
+actions work.
 
 Map each row to a target screen and, for interactions or top-bar controls, a
-target control. Set its `status` to `supported`, `adapted`, `conditional`, or
+target control. A `design` row is app-wide, so it needs no screen or control: it is
+satisfied by the design check instead. Set its `status` to `supported`, `adapted`, `conditional`, or
 `unresolved`. For an adaptation, cite the user's instruction and explain the
 change. Each resolved row needs a `verification` record using the required check
 ID for its kind (`route-walkthrough`, `visual-comparison`, `behavior-crawl`,
-`topbar-control`, `access-state`, or `source-resolution`), a safe relative path to
+`topbar-control`, `access-state`, `design-token`, or `source-resolution`), a safe relative path to
 a JSON check record, and the exact release payload SHA-256 in `releaseHash`.
 The JSON file's `checks[]` must contain a passed record with that requirement ID,
 check ID, release hash, target mapping, and a relative `artifact` path to the
@@ -270,6 +289,25 @@ actual screenshot, test output, or walkthrough record. Multiple rows may share
 one file, but each needs its own passed check record. Keep private evidence under
 `.himi/` so it is excluded from the app source archive.
 
+`design-token` evidence is the one kind nobody writes by hand. Run
+`himi one-app validate-design --evidence-dir .himi/one-app --content . --record
+--release-hash <64-hex-sha256>` after the release is built: it writes
+`.himi/one-app/design-report.json` and `.himi/one-app/design-checks.json`, with one
+passed record per matched or adapted design row, and refuses to write either file when
+the check does not pass or any design row remains unresolved. Point each `design` row's
+`verification` at the checks file. `--fix` writes only to a regular token file inside the
+content directory; read-only validation can inspect an external token path.
+The check also compares each idiom overlay selected by the app's statically readable policy
+against the source value. An active overlay
+that changes it needs a deliberate edit or an adapted ledger row that lists the overlay name in
+`adaptation.idioms` (for example, `["ios"]`); a base-token adaptation alone does not waive it.
+`--fix` repairs base tokens only.
+A row the check cannot compare — an `unresolved` one, such as a button `uppercase` —
+gets a record only once it is resolved as `adapted`, with the user's instruction and an
+explanation. An adaptation counts only while the ledger's `sourceHashes` match the
+collected evidence; after recollection, run `coverage sync` and decide again. `--record`
+refuses `--fix` in the same run: the release hash names the tokens as built.
+
 For example, one entry in the referenced JSON file is:
 
 ```json
@@ -357,7 +395,31 @@ not share mutable filters accidentally. Keep static authored content in the app,
 and products, services, availability, posts and member records live on the same site.
 Refresh data after operations without reconnecting layout to the One App editor.
 
-Resolve the same site's mobile OAuth client using the existing idempotent command:
+Bind the app to the same site through its **One App visitor identity**. It is the
+identity a visitor of the source Branded app already has, so it needs no OAuth client
+and creates nothing on the customer's site. The `branded-lite` template does not supply `provisioning.json`:
+bind it directly in the generated app's `config.ts`, with its existing
+`WixConsumerAuthProvider` import and the [Wix auth configuration contract](https://apps.wix.com/_api/himi-serve/docs/wix-api-usage.md).
+Replace the template's placeholders and environment fallbacks so an unrelated local
+`WIX_CLIENT_ID` cannot repoint the build:
+
+```ts
+auth: WixConsumerAuthProvider({
+  visitorSource: "one-app",
+  metaSiteId: "<source-msid>",
+  siteUrl: "<verified-source-website-publicUrl>",
+  bootAsVisitor: true,
+  preserveVisitorOnSignOut: true,
+}),
+```
+
+Every surface reads the site with it: the native apps, the hosted draft preview, and
+`himi run`, `himi render --live` and `himi test --record`. It is a visitor: member
+sign-in still needs a Headless OAuth client.
+
+**Only when the site owner wants member sign-in now**, and with their agreement,
+resolve the site's mobile OAuth client with the existing idempotent command (it is
+an owner-scoped write to the customer's site):
 
 ```sh
 himi site client ensure --site <source-msid> --name <stable-migration-client-name> \
@@ -366,17 +428,13 @@ himi site client ensure --site <source-msid> --name <stable-migration-client-nam
 
 Reuse a compatible client first; create or update only as necessary. Preserve its
 existing redirect URIs when adding the app's redirect. Require a successful,
-non-dry-run result and verify its `siteId`, public `clientId` and `redirectUri`.
-This command reconciles the OAuth client; it does not configure the generated app.
-
-The `branded-lite` template does not supply `provisioning.json`. Bind the result
-directly in the generated app's `config.ts`, using its existing
-`WixConsumerAuthProvider` import and the [Wix auth configuration contract](https://apps.wix.com/_api/himi-serve/docs/wix-api-usage.md).
-Replace the template's placeholders and environment fallbacks with this app's
-verified binding so an unrelated local `WIX_CLIENT_ID` cannot repoint the build:
+non-dry-run result and verify its `siteId`, public `clientId` and `redirectUri`, then
+add them beside the One App binding:
 
 ```ts
 auth: WixConsumerAuthProvider({
+  visitorSource: "one-app",
+  metaSiteId: "<source-msid>",
   clientId: "<returned-public-client-id>",
   siteUrl: "<verified-source-website-publicUrl>",
   redirectUri: "<returned-registered-app-redirect-uri>",
@@ -389,8 +447,9 @@ The site URL comes from the verified `website.publicUrl` in the collected Busine
 context or an existing verified binding; `site client ensure` does not return it.
 Keep visitor/member gates from the reconstruction plan and resolve a missing site
 URL against the auth contract instead of shipping a template URL. Verify that the
-built app uses the intended client and the exact registered redirect. The public
-client ID is app configuration; the collection credential is not.
+built app reads the intended site (and, with a client, uses the exact registered
+redirect). The MetaSite and a public client ID are app configuration; the collection
+credential is not.
 
 Use `--write-provisioning <path>` only when a valid adoption manifest already
 exists, including its identity, branding and installed verticals. That option

package/guides/wix-api-usage.md

@@ -65,11 +65,11 @@ export default defineApp({
   // …
   auth: WixConsumerAuthProvider({
     clientId: "4f58d461-…",   // the site's headless clientId — THIS is the site binding
-                              // (metaSiteId is implied by it; there is no separate field)
+                              // (metaSiteId is implied by it; `metaSiteId` is only for one-app mode below)
     siteUrl: "https://<site>.wixsite.com/<slug>",
-    redirectUri: "himalaya-<app>://oauth/callback",  // REQUIRED — the provider throws
+    redirectUri: "himalaya-<app>://oauth/callback",  // REQUIRED with a clientId — the provider throws
                               // "WixConsumerAuthProvider: redirectUri is required." without it,
-                              // even when bootAsVisitor is true (the check fires unconditionally).
+                              // even when bootAsVisitor is true.
                               // Use your app's URL scheme; the scaffolds ship this exact shape.
     bootAsVisitor: true,      // mint an anonymous visitor token at boot
   }),
@@ -85,6 +85,28 @@ members, etc. Scope is **visitor**: reads a site exposes anonymously work; owner
 live at `@himalaya/wix-auth` in-repo / `@wix/himalaya/wix-auth` off-repo — `himi sdk` lists the runtime
 data clients, not these config-time providers).
 
+**No OAuth client on the site? Bind by MetaSite instead (`visitorSource: "one-app"`).** A Headless
+OAuth client can only be created by the site's owner. An app migrated from a Branded One App reads its
+site the way that app's visitors already do — the site's **One App visitor signed instance** — so it
+needs no client and creates nothing on the site:
+
+```ts
+auth: WixConsumerAuthProvider({
+  visitorSource: "one-app",
+  metaSiteId: "0c55162c-…",          // the site's MetaSite ID
+  siteUrl: "https://www.<site>.com/",
+  bootAsVisitor: true,
+}),
+```
+
+The instance comes from `GET apps.wix.com/_api/one-app-session-web/v3/businesses/<metaSiteId>/signed-instance?signed_instance_type=Visitor`
+(no credentials) and is sent as a bare `Authorization` header (`Bearer <instance>` is a 400). Native
+mints it directly; the browser cannot (no CORS), so the app's own origin mints it at `/v1/visitor/instance`;
+`himi run`, `render --live` and `test --record` mint it in Node. Each mint is a new visitor, so it is
+kept until its `validUntil` (~4h) and re-minted only once expired — a 401 on an unexpired instance is
+the endpoint's answer (members-only reads refuse every visitor). Scope is visitor: member sign-in still
+needs a `clientId` (+ `redirectUri`), which you may add beside it.
+
 Monorepo / native Branded Lite (env overrides, auth bake, shareable binary with icon/splash):
 [branded-lite-site-binding.md](branded-lite-site-binding.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1540.0",
+  "version": "0.1542.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "a1d4dc831a852d303dab5ab6d7d7c2eea37f28a6f0c949a4d2c1ce6f"
+  "falconPackageHash": "df1b4ea698663ced2b915395398ceb7e54e9d4ef814dbfe53215381d"
 }