@wix/himalaya-cli 0.1141.0 → 0.1143.0

package/guides/designing-himi-screens.md

@@ -281,7 +281,7 @@ Concrete patterns lifted from real usage:
 - **Cell list** — `card([ vstack({ spacing: 0, alignment: "leading", children: [ …ListItem cells… ] }) ])`. `spacing: 0` because the cells own their own dividers/padding.
 - **Overlay** — `zstack({ alignment: "center", children: [ backdropImage(cornerRadius 12), withModifiers(label, { padding, background: { token: "accentPrimary" }, cornerRadius: 10 }) ] })`.
 - **Responsive** — `grid({ columns: 1, columnsMedium: 2, spacing: 12 })` for 1-up on phone / 2-up on tablet; `splitView({ primary, detail, primaryMaxWidth: 280 })` for master/detail that stacks on a phone; set `contentMaxWidth` in tokens so wide surfaces keep a readable column instead of running edge-to-edge.
-- **Centered separator, not a flanked divider** — the classic "—— or ——" needs each `divider()` to take equal remaining width, and the HStack row-share only kicks in for controls with an intrinsic fill. **A bare `divider()` inside an HStack is a column separator, not a flanking line**: iOS, macOS, Android and web draw it as a thin vertical rule the height of the row that takes no share of the width, which is right for a stats row (`12 | 340 | 87`) and wrong for "—— or ——" (React Native, opt-in, still draws a full-width bar there that squeezes its siblings, so on RN separate stat columns with spacing). For "—— or ——", use a **centered caption**: `hstack({ children: [spacer(), text("or continue with", "caption", { color: "textSecondary" }), spacer()] })`, optionally over a single full-width `divider()`.
+- **Centered separator, not a flanked divider** — the classic "—— or ——" needs each `divider()` to take equal remaining width, and the HStack row-share only kicks in for controls with an intrinsic fill. **A bare `divider()` inside an HStack is a column separator, not a flanking line**: iOS, macOS, Android, web and React Native all draw it as a thin vertical rule the height of the row that takes no share of the width, which is right for a stats row (`12 | 340 | 87`) and wrong for "—— or ——". For "—— or ——", use a **centered caption**: `hstack({ children: [spacer(), text("or continue with", "caption", { color: "textSecondary" }), spacer()] })`, optionally over a single full-width `divider()`.
 
 > **Intrinsic-fill controls grab the row.** `Button` and `TextField` have an intrinsic FILL, so the next four idioms are about NOT letting that surprise you (they were the papercuts every off-repo app hit):
 

package/guides/getting-started.md

@@ -75,7 +75,11 @@ or `--template owner-lite` (owner CRUD/management: lists, details, forms). That
 worker layer — trim it or mine it (`himi docs trim-a-template`): **trim** to the approved
 `SPEC.md` when most of its screens fit, or **mine** it when few do — keep the
 `tier5-src/_shared/` helpers and Wix worker chains and write your own screens. Do not delete
-`tier5-src/` + `dev/` and start from blank. For a small **non-Wix** pattern, `himi init --template chat-bot --remote`. `himi template
+`tier5-src/` + `dev/` and start from blank. Never read that file whole: `himi template screens`
+lists its screens (size, workers, `onAppear`), `--show <id>` prints one entry, and
+`--write <id> --from <file>` puts an edited entry back (refused if it breaks the file). Not sure
+which template fits? `himi template recommend --text "<the business>"` (or `--book <site analyze
+dir>` for a site's verticals) ranks the catalog with reasons. For a small **non-Wix** pattern, `himi init --template chat-bot --remote`. `himi template
 list --remote` shows the full catalog (title/description/tags) — including templates published
 to Wix — and `--remote` on `himi init` fetches one from there (the bundled copy is
 the offline fallback). Publish any app of your own as a template with `himi template publish` —
@@ -102,7 +106,12 @@ done. Print one yourself with `himi template prompt <name>`.
 **Consent preflight before a template preview.** `branded-lite` and `owner-lite` are Wix-integrated
 full apps; their workers can request Wix data when they boot. Do not start their worker or web
 host under a synthetic/local-only authorization unless you have first removed or mocked every such
-startup path and verified the network log is empty of Wix/external requests. Prefer a blank,
+startup path and verified the network log is empty of Wix/external requests. You do not have to
+read the workers to know: `himi init --template` answers it in its envelope's `adopt` block
+(`bootsOffline`, and `.himi/adopt.json` → `bootRequests` names each screen action and the Wix
+modules or `fetch` it can reach; `himi template inspect` recomputes it after edits). It is a
+static answer on the safe side — "may request" — so `bootsOffline: true` clears the preflight and
+`false` means authorize, mock or remove those paths first. Prefer a blank,
 local-only scaffold for that stage. A browser render that causes an unapproved request is a failed
 consent gate, not a harmless preview.
 
@@ -113,10 +122,11 @@ web host and call it owner-private, and do not let a template worker boot there
 network paths are authorized and preflighted.
 
 **Adopt, don't just rename, a template.** The approved `SPEC.md` and `MOBILE-UX.md` are the
-plan, and the plan wins over anything `himi init` seeds. `init` seeds placeholder copies of
-both and can overwrite plan files already in the package root, so keep a copy of the approved
-plan until `init` has run. After `init`, open both files:
-if either holds `init`'s boilerplate rather than the approved plan, put the approved plan back in
+plan, and the plan wins over anything `himi init` seeds. `init` keeps a `SPEC.md` /
+`MOBILE-UX.md` already in the target folder — its envelope lists them under `kept` — and seeds
+its skeleton only where none exists, so write the approved plan there before `init`. After
+`init`, open both files: if either holds `init`'s boilerplate rather than the approved plan (an
+older CLI, or a plan kept elsewhere), put the approved plan back in
 its place — never the reverse — and finish it with the actual customer, data/auth assumptions,
 placeholder copy, flow/state matrix, and compact/phone/expanded + device evidence before calling
 the app ready. Keep scenario switches out of customer UI. A labelled preview fallback is acceptable
@@ -126,18 +136,26 @@ only when the host cannot perform the task and it cannot write customer data.
 product. Right after `init`:
 
 1. **Inventory what you inherited** before editing: its screens, local and remote data, auth,
-   capabilities, demo/fallback behaviour, and template-specific copy. Write it down — it is the
-   list the next steps work through.
+   capabilities, demo/fallback behaviour, and template-specific copy. A current `himi init
+   --template` writes it for you as `.himi/adopt.json` (`himi template inspect` rewrites it) —
+   the list the next steps work through.
 2. **Replace the template's identity**: its app name, addresses, sample content, and every
    `YOUR_*` / `replace with` placeholder. A placeholder left in is shipped as copy —
-   `himi ux audit --strict` fails on one as `template-placeholder`.
+   `himi ux audit --strict` fails on one as `template-placeholder`. `adopt.json` lists every
+   placeholder and sample-copy hit; `himi template sweep --set "Old=>New"` replaces them inside
+   string literals only.
 3. **Put each inherited risky flow in the acceptance matrix** — booking/cancellation, payments,
-   deletion, media, maps, entitlement — or remove it (`himi template trim`). A flow the plan does
-   not mention is a flow nobody approved.
+   deletion, media, maps, entitlement — or remove it (`himi template trim`; `--from-spec` keeps
+   exactly the screen ids in `SPEC.md`'s Screen catalogue — dry-run first and add every
+   `fromSpec.droppedPrimary` target, or a kept screen loses its own primary action while `validate`
+   stays green). A flow the plan does not mention is a
+   flow nobody approved. `.himi/adopt-matrix.md` proposes the `## Data access` rows from the
+   template's actions (writes, payments, destructive) — proposals for the owner, never approvals.
 4. **Classify every control** as primary, secondary, destructive, or preview/fallback, and keep a
    destructive or writing control only when the approved data-access matrix allows it.
 5. **Prove each adopted flow, not just each screen**: with fixtures or `dev/net-mocks.json`, prove
    typed input → submit → the persisted result with a typed journey in `himi-test.json`
+   (`.himi/himi-test.stub.json` has a skeleton per form: fill the values and expected text)
    (`--deep` replays action chains but never types a field value), then prove the destination
    and cancel/back recovery separately — a typed journey is screen-local and does not follow
    navigation, so use a render of the destination or a device drive. A fresh-screen crawl alone

package/guides/himi-skill.md

@@ -104,7 +104,11 @@ or `--template owner-lite` (owner CRUD/management: lists, details, forms). That
 worker layer — trim it or mine it (`himi docs trim-a-template`): **trim** to the approved
 `SPEC.md` when most of its screens fit, or **mine** it when few do — keep the
 `tier5-src/_shared/` helpers and Wix worker chains and write your own screens. Do not delete
-`tier5-src/` + `dev/` and start from blank. For a small **non-Wix** pattern, `himi init --template chat-bot --remote`. `himi template
+`tier5-src/` + `dev/` and start from blank. Never read that file whole: `himi template screens`
+lists its screens (size, workers, `onAppear`), `--show <id>` prints one entry, and
+`--write <id> --from <file>` puts an edited entry back (refused if it breaks the file). Not sure
+which template fits? `himi template recommend --text "<the business>"` (or `--book <site analyze
+dir>` for a site's verticals) ranks the catalog with reasons. For a small **non-Wix** pattern, `himi init --template chat-bot --remote`. `himi template
 list --remote` shows the full catalog (title/description/tags) — including templates published
 to Wix — and `--remote` on `himi init` fetches one from there (the bundled copy is
 the offline fallback). Publish any app of your own as a template with `himi template publish` —
@@ -131,7 +135,12 @@ done. Print one yourself with `himi template prompt <name>`.
 **Consent preflight before a template preview.** `branded-lite` and `owner-lite` are Wix-integrated
 full apps; their workers can request Wix data when they boot. Do not start their worker or web
 host under a synthetic/local-only authorization unless you have first removed or mocked every such
-startup path and verified the network log is empty of Wix/external requests. Prefer a blank,
+startup path and verified the network log is empty of Wix/external requests. You do not have to
+read the workers to know: `himi init --template` answers it in its envelope's `adopt` block
+(`bootsOffline`, and `.himi/adopt.json` → `bootRequests` names each screen action and the Wix
+modules or `fetch` it can reach; `himi template inspect` recomputes it after edits). It is a
+static answer on the safe side — "may request" — so `bootsOffline: true` clears the preflight and
+`false` means authorize, mock or remove those paths first. Prefer a blank,
 local-only scaffold for that stage. A browser render that causes an unapproved request is a failed
 consent gate, not a harmless preview.
 
@@ -142,10 +151,11 @@ web host and call it owner-private, and do not let a template worker boot there
 network paths are authorized and preflighted.
 
 **Adopt, don't just rename, a template.** The approved `SPEC.md` and `MOBILE-UX.md` are the
-plan, and the plan wins over anything `himi init` seeds. `init` seeds placeholder copies of
-both and can overwrite plan files already in the package root, so keep a copy of the approved
-plan until `init` has run. After `init`, open both files:
-if either holds `init`'s boilerplate rather than the approved plan, put the approved plan back in
+plan, and the plan wins over anything `himi init` seeds. `init` keeps a `SPEC.md` /
+`MOBILE-UX.md` already in the target folder — its envelope lists them under `kept` — and seeds
+its skeleton only where none exists, so write the approved plan there before `init`. After
+`init`, open both files: if either holds `init`'s boilerplate rather than the approved plan (an
+older CLI, or a plan kept elsewhere), put the approved plan back in
 its place — never the reverse — and finish it with the actual customer, data/auth assumptions,
 placeholder copy, flow/state matrix, and compact/phone/expanded + device evidence before calling
 the app ready. Keep scenario switches out of customer UI. A labelled preview fallback is acceptable
@@ -155,18 +165,26 @@ only when the host cannot perform the task and it cannot write customer data.
 product. Right after `init`:
 
 1. **Inventory what you inherited** before editing: its screens, local and remote data, auth,
-   capabilities, demo/fallback behaviour, and template-specific copy. Write it down — it is the
-   list the next steps work through.
+   capabilities, demo/fallback behaviour, and template-specific copy. A current `himi init
+   --template` writes it for you as `.himi/adopt.json` (`himi template inspect` rewrites it) —
+   the list the next steps work through.
 2. **Replace the template's identity**: its app name, addresses, sample content, and every
    `YOUR_*` / `replace with` placeholder. A placeholder left in is shipped as copy —
-   `himi ux audit --strict` fails on one as `template-placeholder`.
+   `himi ux audit --strict` fails on one as `template-placeholder`. `adopt.json` lists every
+   placeholder and sample-copy hit; `himi template sweep --set "Old=>New"` replaces them inside
+   string literals only.
 3. **Put each inherited risky flow in the acceptance matrix** — booking/cancellation, payments,
-   deletion, media, maps, entitlement — or remove it (`himi template trim`). A flow the plan does
-   not mention is a flow nobody approved.
+   deletion, media, maps, entitlement — or remove it (`himi template trim`; `--from-spec` keeps
+   exactly the screen ids in `SPEC.md`'s Screen catalogue — dry-run first and add every
+   `fromSpec.droppedPrimary` target, or a kept screen loses its own primary action while `validate`
+   stays green). A flow the plan does not mention is a
+   flow nobody approved. `.himi/adopt-matrix.md` proposes the `## Data access` rows from the
+   template's actions (writes, payments, destructive) — proposals for the owner, never approvals.
 4. **Classify every control** as primary, secondary, destructive, or preview/fallback, and keep a
    destructive or writing control only when the approved data-access matrix allows it.
 5. **Prove each adopted flow, not just each screen**: with fixtures or `dev/net-mocks.json`, prove
    typed input → submit → the persisted result with a typed journey in `himi-test.json`
+   (`.himi/himi-test.stub.json` has a skeleton per form: fill the values and expected text)
    (`--deep` replays action chains but never types a field value), then prove the destination
    and cancel/back recovery separately — a typed journey is screen-local and does not follow
    navigation, so use a render of the destination or a device drive. A fresh-screen crawl alone

package/guides/sdk-reference.json

@@ -1331,6 +1331,132 @@
     "source": "core/sdk/iap/src/index.ts",
     "description": "Tier-5 typed binding to the platform's in-app-purchase capability.",
     "api": [
+      {
+        "name": "SessionSnapshot",
+        "kind": "interface",
+        "jsdoc": "/** Trusted host session snapshot. Not a credential: the backend adapter resolves real\n *  credentials from its own authenticated transport, bound to this `generation`. */",
+        "decl": "export interface SessionSnapshot {\n  /** Changes on every sign-in, sign-out, member or site change. */\n  generation: number;\n  kind: \"member\" | \"visitor\" | \"owner\" | \"signedOut\";\n}"
+      },
+      {
+        "name": "SessionProvider",
+        "kind": "interface",
+        "jsdoc": "/** Supplied by the host, never by worker UI state. */",
+        "decl": "export interface SessionProvider {\n  current(): SessionSnapshot;\n  /** Called after `current()` changes; returns an unsubscribe function. */\n  subscribe(listener: () => void): () => void;\n}"
+      },
+      {
+        "name": "PurchaseContext",
+        "kind": "interface",
+        "jsdoc": "/** A catalog item resolved by the backend for the captured member. */",
+        "decl": "export interface PurchaseContext {\n  productId: string;\n  /** Canonical UUID the backend associates with this site/member. */\n  appAccountToken: string;\n  /** Opaque site/member scope the acknowledgement must echo. */\n  scopeKey: string;\n}"
+      },
+      {
+        "name": "MemberContext",
+        "kind": "interface",
+        "jsdoc": "/** The current member's association, used to recover purchases without a catalog item. */",
+        "decl": "export interface MemberContext {\n  appAccountToken: string;\n  scopeKey: string;\n}"
+      },
+      {
+        "name": "ContextResult",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type ContextResult<T> =\n  | { status: \"ok\"; context: T }\n  | { status: \"authRequired\" | \"rejected\" }\n  | { status: \"retryable\"; retryAfterMs?: number };"
+      },
+      {
+        "name": "ProcessingAcknowledgement",
+        "kind": "interface",
+        "jsdoc": "/** Bound to one transaction and scope. Means verification AND durable access persistence\n *  completed; an HTTP 2xx, a receipt or a job id is not an acknowledgement. */",
+        "decl": "export interface ProcessingAcknowledgement {\n  transactionId: string;\n  productId: string;\n  environment: AppleTransaction[\"environment\"];\n  scopeKey: string;\n}"
+      },
+      {
+        "name": "SubmitProofResult",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type SubmitProofResult =\n  | { status: \"processed\" | \"alreadyProcessed\"; acknowledgement: ProcessingAcknowledgement }\n  | { status: \"retryable\"; retryAfterMs?: number }\n  | { status: \"authRequired\" | \"ownershipConflict\" | \"rejected\" };"
+      },
+      {
+        "name": "DeliveryBackend",
+        "kind": "interface",
+        "jsdoc": "/** PROPOSED backend agreement. Every call carries the session captured when the work\n *  started, never whichever session is current when the request is sent. Responses are\n *  decoded strictly; anything unrecognised is treated as invalid, never as success. */",
+        "decl": "export interface DeliveryBackend {\n  getPurchaseContext(session: SessionSnapshot, catalogRef: string): Promise<ContextResult<PurchaseContext>>;\n  getMemberContext(session: SessionSnapshot): Promise<ContextResult<MemberContext>>;\n  /** Must be idempotent per store/environment/transaction id; delivery is at-least-once. */\n  submitProof(session: SessionSnapshot, transaction: AppleTransaction): Promise<SubmitProofResult>;\n}"
+      },
+      {
+        "name": "TransactionStore",
+        "kind": "interface",
+        "jsdoc": "/** The three managed verbs; `appleManagedStore` in index.ts is the production binding. */",
+        "decl": "export interface TransactionStore {\n  purchaseForVerification(input: { productId: string; appAccountToken: string }): Promise<VerificationPurchaseResult>;\n  getUnfinishedTransactions(): Promise<UnfinishedTransactionsResult>;\n  finishTransaction(input: { transactionId: string }): Promise<FinishTransactionResult>;\n}"
+      },
+      {
+        "name": "Clock",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface Clock {\n  /** Epoch milliseconds. */\n  now(): number;\n}"
+      },
+      {
+        "name": "DeliveryPhase",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type DeliveryPhase = \"idle\" | \"purchasing\" | \"awaitingApproval\" | \"cancelled\" | \"signInRequired\" | \"unavailable\";"
+      },
+      {
+        "name": "DeliveryErrorCode",
+        "kind": "type",
+        "jsdoc": "/** `sessionChanged`: a purchase was requested under an earlier session and was not carried out. */",
+        "decl": "export type DeliveryErrorCode = TransactionErrorCode | \"contextUnavailable\" | \"contextRejected\" | \"proofRejected\"\n  | \"sessionChanged\";"
+      },
+      {
+        "name": "AccessStatus",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type AccessStatus = \"pending\" | \"confirming\" | \"waitingToRetry\" | \"signInRequired\"\n  | \"ownershipConflict\" | \"rejected\" | \"confirmed\";"
+      },
+      {
+        "name": "CompletionStatus",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type CompletionStatus = \"pending\" | \"finished\" | \"notFound\" | \"retryRequired\";"
+      },
+      {
+        "name": "DeliveryItemState",
+        "kind": "interface",
+        "jsdoc": "/** Safe to render and persist: no proof, account token, transaction or member id. */",
+        "decl": "export interface DeliveryItemState {\n  productId: string;\n  environment: AppleTransaction[\"environment\"];\n  /** Present in the last native unfinished enumeration; null before one succeeded. */\n  held: boolean | null;\n  /** `confirmed` only from a matching acknowledgement for the current session. */\n  access: AccessStatus;\n  completion: CompletionStatus;\n  attempts: number;\n  nextAttemptAt: number | null;\n  errorCode: DeliveryErrorCode | null;\n}"
+      },
+      {
+        "name": "DeliveryState",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface DeliveryState {\n  phase: DeliveryPhase;\n  errorCode: DeliveryErrorCode | null;\n  items: DeliveryItemState[];\n  /** From the last successful enumeration; null when unknown or it failed. */\n  unfinishedCount: number | null;\n  /** Earliest `nextAttemptAt`; hosts schedule `tick()` for it (e.g. a worker `_poll`). */\n  nextWakeAt: number | null;\n}"
+      },
+      {
+        "name": "PurchaseCoordinatorDependencies",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface PurchaseCoordinatorDependencies {\n  store: TransactionStore;\n  backend: DeliveryBackend;\n  session: SessionProvider;\n  clock: Clock;\n  /** Extra milliseconds added to a backoff step; inject for deterministic tests. */\n  jitter?: (baseDelayMs: number) => number;\n  /** Receives a fresh safe snapshot after every change. */\n  onState?: (state: DeliveryState) => void;\n}"
+      },
+      {
+        "name": "PurchaseCoordinator",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface PurchaseCoordinator {\n  /** Reconciles unfinished purchases now and again after every later session change. */\n  start(): Promise<DeliveryState>;\n  /** Buys a catalog item; the backend resolves its product id and account token.\n   *  The same member's purchase of the same item already in progress is shared, not repeated. */\n  purchase(catalogRef: string): Promise<DeliveryState>;\n  /** Re-enumerates unfinished purchases and delivers eligible ones (e.g. on resume). */\n  reconcile(): Promise<DeliveryState>;\n  /** Unblocks every waiting or blocked item with a fresh attempt budget, then reconciles. */\n  retry(): Promise<DeliveryState>;\n  /** Runs whatever retries are due at `clock.now()`. */\n  tick(): Promise<DeliveryState>;\n  getState(): DeliveryState;\n  /** Drops the session subscription and suppresses every later callback. */\n  dispose(): void;\n}"
+      },
+      {
+        "name": "MAX_AUTOMATIC_ATTEMPTS",
+        "kind": "const",
+        "jsdoc": "/** Automatic attempts per item per reconciliation run; the item is never discarded after. */",
+        "decl": "export const MAX_AUTOMATIC_ATTEMPTS = 5;"
+      },
+      {
+        "name": "MAX_RETRY_DELAY_MS",
+        "kind": "const",
+        "jsdoc": "",
+        "decl": "export const MAX_RETRY_DELAY_MS = 60_000;"
+      },
+      {
+        "name": "createPurchaseCoordinator",
+        "kind": "function",
+        "jsdoc": "/** Creates a coordinator owned by the host/service lifecycle, not by a screen or render.\n *  Closures, not classes: Tier-5 bundles must also evaluate on Hermes, which has no `class`. */",
+        "decl": "export function createPurchaseCoordinator(deps: PurchaseCoordinatorDependencies): PurchaseCoordinator;"
+      },
       {
         "name": "ProductType",
         "kind": "type",
@@ -1462,6 +1588,12 @@
         "kind": "function",
         "jsdoc": "/** Trusted callers must first obtain durable backend processing acknowledgement. */",
         "decl": "export async function finishTransaction(input: { transactionId: string }): Promise<FinishTransactionResult>;"
+      },
+      {
+        "name": "appleManagedStore",
+        "kind": "const",
+        "jsdoc": "/** The managed native verbs as the delivery coordinator's store. */",
+        "decl": "export const appleManagedStore: TransactionStore = { purchaseForVerification, getUnfinishedTransactions, finishTransaction };"
       }
     ]
   },

package/guides/templates.md

@@ -93,6 +93,39 @@ as a raw descriptor (megabytes for the full templates), so replacing it is often
 editing it. Both paths, and how `dev/index.ts`, `tier5-src/`, and `navigation.linkableScreens`
 relate: `himi docs trim-a-template`.
 
+## Adopt — what the CLI works out for you
+
+Starting from a template is a fork of a large app, and most of what an agent needs to know about it
+is mechanical. `himi init --template` answers it in the envelope's `adopt` block and writes the
+details beside the app:
+
+| File | What it holds |
+|---|---|
+| `.himi/adopt.json` | every screen (size, workers, `onAppear`), every worker's Wix modules / `wixApi` / `fetch` reach, navigation, **`bootRequests`** + **`bootsOffline`**, placeholder and sample-copy hits |
+| `.himi/adopt-matrix.md` | proposed `## Data access` rows from the template's actions — writes, payments, destructive — in the exact table `himi test` reads. Proposals for the owner, never approvals |
+| `.himi/himi-test.stub.json` | a typed-journey skeleton per form (every field, then its submit) with `<FILL>` slots |
+
+`bootsOffline` is the consent preflight: it is `false` when any screen's `onAppear` dispatches into
+a worker that can reach Wix or the network, and `bootRequests` names each one. It is static and errs
+on the safe side ("may request"). The commands behind it:
+
+```sh
+himi template recommend --text "a salon where clients book and buy products"   # rank the catalog (or --verticals / --book)
+himi template inspect                        # recompute the inventory after edits (--dry-run writes nothing)
+himi template screens                        # list dev/index.ts screens without reading the file
+himi template screens --show himi_saved > saved.txt    # ONE screen's entry
+himi template screens --write himi_saved --from saved.txt   # put it back — re-parsed, refused if it breaks the file
+himi template sweep --set "Sample content=>Our latest" --dry-run   # copy inside string literals only
+himi template trim --from-spec --links drop --dry-run   # keep SPEC.md's Screen catalogue ids — read fromSpec.droppedPrimary first
+```
+
+`sweep` works on the TypeScript AST, so comments and code are never candidates — only string
+literals, and of those only prose (has whitespace), a template placeholder (`YOUR_*`), or the value
+of a copy key (`title`, `text`, `label`, `placeholder`, …; `name` only in `config.ts`, because in a
+descriptor it is an Icon id). A one-word literal elsewhere — a service name, a component type, an
+action id, a URL — is wiring, and is never rewritten. Every changed file is syntax-checked before
+anything is written.
+
 **Point a `branded-lite` (or vertical overlay) scaffold at your site.** Set
 `WIX_CLIENT_ID` (Headless OAuth client on that site) and `WIX_SITE_URL` before build /
 preview — the `clientId` **is** the site binding (no separate MSID field). Placeholders

package/guides/trim-a-template.md

@@ -48,6 +48,19 @@ himi template trim --keep himi_shop,himi_product,himi_cart,himi_account --dry-ru
 himi template trim --keep himi_shop,himi_product,himi_cart,himi_account --links drop   # do it
 ```
 
+**From the plan:** `himi template trim --from-spec [SPEC.md] --links drop` takes `--keep` from the
+first column of `SPEC.md`'s `## Screen catalogue` (backticked screen ids; prose rows are ignored).
+Its report adds `fromSpec.specOnly` — the plan screens the template does not have, which you author
+(the "mine" part) — and `fromSpec.droppedPrimary`: each kept screen whose own primary action (a list
+row's tap, a CTA) opened a screen the plan left out. `--links drop` removes those taps and `validate`
+stays green, so a Services list that listed its services but could no longer book one passed every
+check. Dry-run first, add each `droppedPrimary` target to the catalogue (or confirm the plan drops
+that flow), then trim for real. A tap whose target a WORKER computes is invisible to trim; `himi test`
+reports it as `nav-target-missing`. A trim that keeps its tree (a success, or `--force`) also
+refreshes `.himi/adopt.json`; it leaves an existing `adopt-matrix.md` / `himi-test.stub.json` alone,
+since those are the files you fill in (`himi template inspect` regenerates all three). `himi template screens`
+lists the ids to put in that column.
+
 Run it in (or point `--content` at) the app `himi init --template` scaffolded — not the
 template itself, which it refuses. `--keep` takes `SCREENS` ids and templated route ids (the
 part before the brackets: `himi_product` for `himi_product[_{id}]`). The home screen is always

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1141.0",
+  "version": "0.1143.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": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "b820f4eed1d9ed9b0d30bcf1f8cb0b2c3355091ccb6fc9701db1bb4b"
+  "falconPackageHash": "7d92bfb40f295121fe145451b71e6d7d5f3bbba165b18f60bc10d4eb"
 }

package/templates/beauty-salon/dev/index.ts

@@ -2493,6 +2493,7 @@ const SCREENS = runtimeSetting({
                         "type": "TextField",
                         "props": {
                           "placeholder": "Password",
+                          "valuePath": "$service:himiStoreAccount.password",
                           "secure": true,
                           "autoCapitalization": "none",
                           "onChange": {
@@ -27653,6 +27654,7 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                                         "type": "TextField",
                                         "props": {
                                           "placeholder": "Password",
+                                          "valuePath": "$service:himiBookingTime.password",
                                           "secure": true,
                                           "autoCapitalization": "none",
                                           "onChange": {

package/templates/beauty-salon/tier5-src/himi-booking-time/index.ts

@@ -603,7 +603,7 @@ const svc = defineService<S, {
           message: copyParam("time.signedInReady", "Signed in. You can book this time now."),
         });
       } catch {
-        return derive({ ...s, message: copyParam("time.signInFailed", "Sign in failed. Try again.") });
+        return derive({ ...s, password: "", message: copyParam("time.signInFailed", "Sign in failed. Try again.") });
       }
     },
     register: async (s) => {
@@ -626,7 +626,7 @@ const svc = defineService<S, {
           message: copyParam("time.registerReady", "Account created. You can book this time now."),
         });
       } catch {
-        return derive({ ...s, message: copyParam("time.registerFailed", "Account creation failed. Try another email.") });
+        return derive({ ...s, password: "", message: copyParam("time.registerFailed", "Account creation failed. Try another email.") });
       }
     },
     bookSelected: async (s) => {

package/templates/beauty-salon/tier5-src/himi-store-account/index.ts

@@ -77,7 +77,10 @@ async function authenticate(s: S, submit: () => Promise<unknown>, notMemberMessa
     if (!next.isMember) return derive({ ...next, message: notMemberMessage });
     return resumeAfterAuth(derive({ ...next, message: "" }));
   } catch {
-    return derive({ ...s, message: failedMessage });
+    // Clear the password: service state is snapshotted to disk (the worker-state
+    // store), so a failed attempt must not leave it there in cleartext. The Password
+    // field binds `valuePath` to it, so the field empties too and a retry re-types.
+    return derive({ ...s, password: "", message: failedMessage });
   } finally {
     authInFlight = false;
   }
@@ -168,6 +171,9 @@ interface S {
   noReturnPath: boolean;
   returnCta: string;
   email: string;
+  /** Held only from typing to the submit. Service state is persisted, so every
+   *  submitted sign-in/register clears it (success, not-a-member, and failure), as
+   *  do recovery and sign-out. Sign-in <-> register keeps it: the field stays up. */
   password: string;
   firstName: string;
   lastName: string;

package/templates/branded-lite/dev/index.ts

@@ -3080,6 +3080,7 @@ const SCREENS = runtimeSetting({
                         "type": "TextField",
                         "props": {
                           "placeholder": "Password",
+                          "valuePath": "$service:himiStoreAccount.password",
                           "secure": true,
                           "autoCapitalization": "none",
                           "onChange": {
@@ -82309,6 +82310,7 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                                         "type": "TextField",
                                         "props": {
                                           "placeholder": "Password",
+                                          "valuePath": "$service:himiBookingTime.password",
                                           "secure": true,
                                           "autoCapitalization": "none",
                                           "onChange": {
@@ -85183,7 +85185,7 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                                 "type": "TextField",
                                 "props": {
                                   "placeholder": "Password",
-                                  "value": "",
+                                  "valuePath": "$service:himiEventsRsvp.password",
                                   "secure": true,
                                   "autoCapitalization": "none",
                                   "onChange": {

package/templates/branded-lite/tier5-src/himi-booking-time/index.ts

@@ -603,7 +603,7 @@ const svc = defineService<S, {
           message: copyParam("time.signedInReady", "Signed in. You can book this time now."),
         });
       } catch {
-        return derive({ ...s, message: copyParam("time.signInFailed", "Sign in failed. Try again.") });
+        return derive({ ...s, password: "", message: copyParam("time.signInFailed", "Sign in failed. Try again.") });
       }
     },
     register: async (s) => {
@@ -626,7 +626,7 @@ const svc = defineService<S, {
           message: copyParam("time.registerReady", "Account created. You can book this time now."),
         });
       } catch {
-        return derive({ ...s, message: copyParam("time.registerFailed", "Account creation failed. Try another email.") });
+        return derive({ ...s, password: "", message: copyParam("time.registerFailed", "Account creation failed. Try another email.") });
       }
     },
     bookSelected: async (s) => {

package/templates/branded-lite/tier5-src/himi-events-rsvp/index.ts

@@ -179,9 +179,9 @@ const svc = defineService<S, {
       try {
         await dispatch("himi.wix.signInDirect", { email: s.email, password: s.password });
         const p = await probeMember({ ...s, isMember: true, identityLine: s.email });
-        return derive({ ...p, message: p.isMember ? copyParam("rsvp.signedInReady", "Signed in. You can RSVP now.") : copyParam("rsvp.signInCheckDetails", "Sign in failed. Check your details.") });
+        return derive({ ...p, password: "", message: p.isMember ? copyParam("rsvp.signedInReady", "Signed in. You can RSVP now.") : copyParam("rsvp.signInCheckDetails", "Sign in failed. Check your details.") });
       } catch {
-        return derive({ ...s, message: copyParam("rsvp.signInFailed", "Sign in failed. Try again.") });
+        return derive({ ...s, password: "", message: copyParam("rsvp.signInFailed", "Sign in failed. Try again.") });
       }
     },
     rsvp: async (s) => {

package/templates/branded-lite/tier5-src/himi-store-account/index.ts

@@ -77,7 +77,10 @@ async function authenticate(s: S, submit: () => Promise<unknown>, notMemberMessa
     if (!next.isMember) return derive({ ...next, message: notMemberMessage });
     return resumeAfterAuth(derive({ ...next, message: "" }));
   } catch {
-    return derive({ ...s, message: failedMessage });
+    // Clear the password: service state is snapshotted to disk (the worker-state
+    // store), so a failed attempt must not leave it there in cleartext. The Password
+    // field binds `valuePath` to it, so the field empties too and a retry re-types.
+    return derive({ ...s, password: "", message: failedMessage });
   } finally {
     authInFlight = false;
   }
@@ -168,6 +171,9 @@ interface S {
   noReturnPath: boolean;
   returnCta: string;
   email: string;
+  /** Held only from typing to the submit. Service state is persisted, so every
+   *  submitted sign-in/register clears it (success, not-a-member, and failure), as
+   *  do recovery and sign-out. Sign-in <-> register keeps it: the field stays up. */
   password: string;
   firstName: string;
   lastName: string;

package/templates/community-club/dev/index.ts

@@ -2115,6 +2115,7 @@ const SCREENS = runtimeSetting({
                         "type": "TextField",
                         "props": {
                           "placeholder": "Password",
+                          "valuePath": "$service:himiStoreAccount.password",
                           "secure": true,
                           "autoCapitalization": "none",
                           "onChange": {
@@ -18328,7 +18329,7 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                                 "type": "TextField",
                                 "props": {
                                   "placeholder": "Password",
-                                  "value": "",
+                                  "valuePath": "$service:himiEventsRsvp.password",
                                   "secure": true,
                                   "autoCapitalization": "none",
                                   "onChange": {

package/templates/community-club/tier5-src/himi-events-rsvp/index.ts

@@ -179,9 +179,9 @@ const svc = defineService<S, {
       try {
         await dispatch("himi.wix.signInDirect", { email: s.email, password: s.password });
         const p = await probeMember({ ...s, isMember: true, identityLine: s.email });
-        return derive({ ...p, message: p.isMember ? copyParam("rsvp.signedInReady", "Signed in. You can RSVP now.") : copyParam("rsvp.signInCheckDetails", "Sign in failed. Check your details.") });
+        return derive({ ...p, password: "", message: p.isMember ? copyParam("rsvp.signedInReady", "Signed in. You can RSVP now.") : copyParam("rsvp.signInCheckDetails", "Sign in failed. Check your details.") });
       } catch {
-        return derive({ ...s, message: copyParam("rsvp.signInFailed", "Sign in failed. Try again.") });
+        return derive({ ...s, password: "", message: copyParam("rsvp.signInFailed", "Sign in failed. Try again.") });
       }
     },
     rsvp: async (s) => {

package/templates/community-club/tier5-src/himi-store-account/index.ts

@@ -77,7 +77,10 @@ async function authenticate(s: S, submit: () => Promise<unknown>, notMemberMessa
     if (!next.isMember) return derive({ ...next, message: notMemberMessage });
     return resumeAfterAuth(derive({ ...next, message: "" }));
   } catch {
-    return derive({ ...s, message: failedMessage });
+    // Clear the password: service state is snapshotted to disk (the worker-state
+    // store), so a failed attempt must not leave it there in cleartext. The Password
+    // field binds `valuePath` to it, so the field empties too and a retry re-types.
+    return derive({ ...s, password: "", message: failedMessage });
   } finally {
     authInFlight = false;
   }
@@ -168,6 +171,9 @@ interface S {
   noReturnPath: boolean;
   returnCta: string;
   email: string;
+  /** Held only from typing to the submit. Service state is persisted, so every
+   *  submitted sign-in/register clears it (success, not-a-member, and failure), as
+   *  do recovery and sign-out. Sign-in <-> register keeps it: the field stays up. */
   password: string;
   firstName: string;
   lastName: string;

package/templates/events-meetups/dev/index.ts

@@ -2299,6 +2299,7 @@ const SCREENS = runtimeSetting({
                         "type": "TextField",
                         "props": {
                           "placeholder": "Password",
+                          "valuePath": "$service:himiStoreAccount.password",
                           "secure": true,
                           "autoCapitalization": "none",
                           "onChange": {
@@ -16326,7 +16327,7 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                                 "type": "TextField",
                                 "props": {
                                   "placeholder": "Password",
-                                  "value": "",
+                                  "valuePath": "$service:himiEventsRsvp.password",
                                   "secure": true,
                                   "autoCapitalization": "none",
                                   "onChange": {