@wix/himalaya-cli 0.1622.0 → 0.1623.0

package/guides/himi-json-output.md

@@ -464,6 +464,40 @@ top-level `code` on stderr.
   `navLogicBundle` that differs, or its `navigation` cannot be edited safely; the
   literal to merge is returned in `snippet` and nothing is written (exit 1).
 
+## `himi one-app access` codes
+
+Carries the source's locked pages (members only, a badge, a paid plan) and its app-wide login requirement into a
+migrated app. Success prints `ok: true` and a `status`: `written`, `unchanged`, `would_write` (`--dry-run`), `in_sync`
+(`--check`) or `no_gates`; `unmapped` lists locked pages with no Himi screen, which are never guessed, and `loginWall`
+says `required`, `not_required` or `unknown` with its `basis` (`evidence`, `flag` or `none`); when it is `required` it also
+lists `enforcedOn` (`ios`, `android`) and `notEnforcedOn` (`web`: the web host enforces a wall only for its own account
+mode). `loginWall.kept` is true when the source does not require login but the app already has a wall (for example one chosen with `--login-wall required`): it stays, and only an explicit `--login-wall none` is refused. `homeEntries` lists the locked pages whose entry is the app's home destination: it stays on the bar behind its lock screen and is never hidden. `himi one-app migrate` adds
+the warning `access_policy_unavailable` to the manifest when the source did not report the login setting. Failures print `ok: false` and a top-level `code`
+on stderr.
+
+- `invalid_usage`: required options are missing, duplicated or unknown, `--screen` is not `<layoutItemId>=<screenId>`,
+  `--login-wall` is not `required` or `none`, or `--dry-run` and `--check` are both given (exit 2).
+- `evidence_invalid`: the evidence manifest or `raw-structure.json` is missing, invalid or fails its recorded hash,
+  `access-policy.json` does not match the hash in the manifest, or the coverage ledger cannot be read or has rows whose
+  source changed (exit 1).
+- `app_uninspectable`: `config.ts` or `dev/index.ts` cannot be read or parsed, `dev/index.ts` has no literal `SCREENS`,
+  or a file cannot be written; in that case every file written so far is put back as it was (exit 1).
+- `access_engine_missing`: the app lacks `tier5-src/_shared/access-gates.ts` or
+  `tier5-src/himi-branded-lite-access-nav`, so a table naming gates would lock nothing; re-scaffold from the current
+  template (exit 1).
+- `gate_screen_missing`: a `--screen` names a screen `dev/index.ts` does not declare (exit 1).
+- `app_services_unavailable`: page locks read app-level state through app services, which only an app that has never
+  shipped an older binary may use, and the app neither declares `app: { newApp: true }` nor was given `--new-app`; nothing
+  is written (exit 1). `--new-app` is the author's statement that the app is new.
+- `needs_manual_merge`: a locked page is mapped to another screen than the app carries (`moved` lists `layoutItemId`, `from`, `to`: the old screen is still wrapped in its lock), a screen payload holds more than `id`, `body` and `modifiers` (or is not a literal object), an entry or row already has a
+  different `hiddenPath`, `navigation.navLogicBundle` is a worker that does not answer the gates, `config.ts` has no
+  literal `auth`, or the app requires login (`requireLogin`) while the source no longer does; nothing is written (exit 1).
+- `gates_removed`: the app carries gates that this run would not carry: the source has none, or fewer `--screen`
+  mappings were given than the app already has gates; `dropped` names the gate keys. Taking a lock out is not
+  automatic (exit 1).
+- `access_out_of_sync` (`--check`): the app does not carry the source's rules as they are now; `outOfSync` names the
+  files, and a locked page with no `--screen` yet counts too, so a script that gates on the exit code never passes while a locked page is open (exit 1).
+
 ## `himi one-app validate-design` codes
 
 - `invalid_usage`: required options are missing or incompatible (exit 2).

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

@@ -388,6 +388,8 @@ Apply these interpretation rules:
 - Keep navigation visibility, reachability and data access separate. Reevaluate
   membership/plan/badge gates at runtime; an operator's successful read is not an
   end-user access policy. Never expose protected content beneath a visual gate.
+  Carry a locked page's rule with `himi one-app access` (see "Locked pages" below):
+  it is a presentation rule, and the data stays protected by its own Wix API.
 - Exclude `ntt.*` definitions and placements from coverage. Preserve configured
   header/top-bar intent; do not add unconfigured drawer or header surfaces.
 - Before publishing, run the migration-only top-bar coverage check:
@@ -1306,6 +1308,108 @@ then compare those four source journeys in the real host. Keep their missing
 behavior explicit in coverage and the report. A stock template screenshot or a
 passing identity check cannot substitute for the fresh reconstruction/device pass.
 
+### Locked pages: members only, a badge, a paid plan
+
+A One App owner can lock a page (a layout item) for members only, for holders of a badge or for holders of a paid
+plan, and choose whether a viewer who may not enter sees a lock screen with the owner's message and button, or no
+tab at all. Those rules are in the AUTHORED structure (`raw-structure.json`, `layoutItems[].permissions`). The
+structure a Visitor reads is already evaluated for that Visitor: every rule becomes "members only" and the badge and
+plan ids are gone, so never read the rules from an enriched view. `himi one-app coverage` lists each rule as an
+`access` row; the rows stay `unresolved` until you carry the rule:
+
+```bash
+himi one-app access --evidence-dir .himi/one-app --content . --new-app \
+  --screen <layoutItemId>=<himiScreenId> --screen <layoutItemId>=<himiScreenId>
+```
+
+Pass every `--screen` of the app each time: a run that names fewer screens than the gates already in the app would
+drop a lock, and is refused (`gates_removed`, which lists what it would drop).
+
+The route decision (which Himi screen a locked page became) is yours; no file records it, so pass it with `--screen`
+(or `--screens-file`). A locked page with no screen is listed under `unmapped`, never guessed. The command:
+
+- writes `tier5-src/_shared/access-gates-table.ts`, the gate table the nav worker reads;
+- puts each gated screen behind a lock screen: the screen's `payload` becomes a `FragmentSlot` whose `open` case is
+  the original screen, moved as it was, and whose default case is the lock, so the page body is not mounted until the
+  viewer is shown to be allowed (a cold start, an unresolved value and an unknown value all render the lock);
+- binds the tab-bar and drawer entries, and the rows that open the screen, of every gate that may hide (hidden mode,
+  or a lock only members see) to the gate's flag in the app-level nav worker: `$service:brandedLiteNav.accessHidden.<key>`
+  on a tab or drawer entry, `$app:brandedLiteNav.accessHidden.<key>` on a row inside a screen. Tab and drawer
+  entries also get `hiddenUntilResolved`, so they stay off the bar until the worker answers;
+  The home destination (the first tab, the first rail item, or the first drawer row of an app with neither) is the one
+  entry that is never hidden: the boot route, deep links and push taps root on it, and the nav check rejects
+  `hiddenUntilResolved` there. A lock on the home page stays on the bar and shows its lock screen instead; the output
+  lists it as `homeEntries`;
+- reads the gate's answer inside each lock screen from the same worker, through `$app:brandedLiteNav.accessState.<key>`.
+  A screen has its own worker, so a `$service:` binding there would read that worker and never see the answer;
+  `$app:` reads the app-level one. App services are a feature of apps that have never shipped an older binary, so the
+  command needs your word that this app is new: `--new-app` writes `app: { newApp: true }` into `config.ts`. Without it
+  (and without that declaration already in the file) the command stops with `app_services_unavailable` and writes
+  nothing. An app that has already shipped gets page locks only after its native floor supports app services (1.9.0 or later):
+  until then the command refuses it, and that is by design;
+- points the app-level bundle (`navigation.navLogicBundle`, or `app.logicBundle` when the app already uses that
+  spelling; declaring both is refused) at `himi-branded-lite-access-nav`, the badges worker that also answers the
+  gates. Ids that normalize to one gate key (`page-a`, `page_a`) get a short hash suffix, so no two pages share a decision; a key an earlier run wrote stays with its page, so a later run never renames it. Mapping a locked page to a different screen than before is refused (`needs_manual_merge`, `moved`): the old screen is still wrapped in its lock. An app whose source locks no page keeps the badges-only worker, byte for byte, and pays nothing;
+- ties each `access` row of the coverage ledger to the screen and gate (`target`), and never overwrites a target you
+  set. The status stays `unresolved`: it moves only on recorded `access-state` evidence from a device.
+
+It is idempotent. `--dry-run` writes nothing; `--check` fails with `access_out_of_sync` and names the files that no
+longer carry the source's rules, so run it after any change to the source or the screens. It refuses to edit what it
+cannot edit safely (`needs_manual_merge`) and removes nothing it wrote earlier (`gates_removed`).
+
+**What the lock is.** It is PRESENTATION ONLY, as it is in the One App. The data behind a page stays protected by its
+own Wix API: a Visitor's call still gets a 401, 403 or 428, and a screen shows its sign-in state. The descriptor is
+served to every device, and the One App itself sends a locked page's structure to the viewer it denies, so static
+content in a locked screen is not a secret. What the lock keeps is the owner's rule on the tab, for public data too.
+
+**Who sees what** (decided by the worker in `tier5-src/_shared/access-gates.ts`):
+
+- No rule: open. Rules by precedence: badges, then paid plans, then members only.
+- A Visitor is blocked by every rule and always gets the sign-in lock, with the owner's message and button when the
+  owner set them, else the stock copy. When only members may see the lock, the tab is hidden for a Visitor and the
+  stock copy applies.
+- A member opens a badge gate with one of its badge ids (`POST /badges/v4/assignments/query`, filtered to the member)
+  and a plan gate with an active plan order of one of its plan ids (`@himalaya/checkout` `activePlanIds`). A blocked
+  member sees the lock for the rule's own kind: a badge asks to contact the business, a plan offers the plans, or asks to
+  contact the business when none of its plans is on offer any more.
+- Hidden mode removes the tab for anyone blocked. There is NO owner or admin bypass: an owner uses the owner app.
+- Every gate starts locked and opens only on proof. A read that fails leaves the member locked with that rule's button,
+  except that a gate already open stays open through a failed re-read (a blip while offline). Nothing is persisted or
+  restored: a snapshot can never open a tab. A new identity closes every gate before the next answer is read.
+
+**One cost of locking a list.** A screen whose body is a paged list now has that list inside the lock's `FragmentSlot`.
+The descriptor check reports it as the warning `paged_list_not_at_scroll_root`: Android recycles rows only for a list
+that sits directly in the root column, so a long locked list is drawn without recycling. Renderers accept it and the
+lock works; keep a locked list short, or lock a screen that holds the list in a detail page.
+
+**Differences from the One App to report.** The plans lock does not name the plans (the One App does); the badge button
+opens the business chat without the prefilled request message; two stock lines (`plansDescription`, `contact*`) are this
+repository's own, because the One App's zero-plans strings are not in any source read. Translate the stock copy through
+the app's catalog like any other string. A gated screen's own worker still loads while locked (the lock is a
+presentation rule), and an entry that is not a tab, drawer entry or a row that opens the screen directly (a button, a
+link, a card) is not hidden: it opens the lock. A row bound inside a screen is hidden only once the app worker has answered: a
+node-level `hiddenPath` has no fail-closed mode (only tab, drawer and rail entries have `hiddenUntilResolved`), so until the worker
+answers, or for good when it never loads, a Visitor sees that row. Opening it shows the lock, never the page.
+
+**The app-wide login requirement.** The dashboard's Sign up & login switch decides whether the source app asks for a
+sign-in before showing anything (`visitorModeEnabled` false) or lets people browse first. `himi one-app migrate` reads it
+as the site's Visitor (no owner login) and saves it as `access-policy.json`, bound to the manifest hash. It is
+supporting context: when the source does not report it, the value is `null` and the manifest warns
+(`access_policy_unavailable`); unknown is never read as either answer. `himi one-app access` then turns the app's own
+login wall on when the source requires login: `auth` in `config.ts` becomes `requireLogin(...)`, a one-line helper
+written beside the imports that sets `required: true` on the provider block. With the wall on, the app shows the sign-in
+(the stock one, or your own gate screen) before any content, and a Visitor session does not pass it. The command never
+takes a wall out (`needs_manual_merge`): dropping a login requirement is yours to decide. For evidence collected before
+the setting was recorded, or when the owner tells you, decide it explicitly with `--login-wall required|none`; the
+explicit choice wins over the evidence. The wall works with or without locked pages.
+The wall is enforced on iOS and Android. The web host enforces a wall only for its own account mode, so a
+migrated app opened in the web host still shows its content to a Visitor: the command's output says so
+(`loginWall.notEnforcedOn`), and a web release must not rely on it. Enforcing the wall on web is a separate follow-up, not part of this command.
+
+**Check on a device**, as a Visitor, as a signed-in member who has neither the badge nor the plan, and as one who has
+it, and record the result as the rows' `access-state` evidence. The member probe of the badge read is the one thing no
+source read can prove: `queryBadgeAssignments` is declared for the app identity, so confirm it answers a member session.
+
 ### Screen-content contract
 
 Use the current [screen design guide](https://apps.wix.com/_api/himi-serve/docs/designing-himi-screens.md) and the app's

package/guides/sdk-reference.json

@@ -8722,6 +8722,44 @@
         "jsdoc": "",
         "decl": "export function updateBadgesOrder(\n  req: WixUpdateBadgesOrderRequest = {} as WixUpdateBadgesOrderRequest,\n  opts?: WixCallOptions,\n): Promise<WixUpdateBadgesOrderResponse>;",
         "http": "PATCH /badges/v4/badges/order"
+      },
+      {
+        "name": "WixBadgeAssignment",
+        "kind": "interface",
+        "jsdoc": "/** One badge given to one member. */",
+        "decl": "export interface WixBadgeAssignment {\n  id?: string;\n  badgeId?: string;\n  memberId?: string;\n  createdDate?: string;\n  updatedDate?: string;\n}"
+      },
+      {
+        "name": "WixQueryBadgeAssignmentsRequest",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixQueryBadgeAssignmentsRequest {\n  query?: { filter?: Record<string, unknown>; cursorPaging?: WixCursorPaging };\n}"
+      },
+      {
+        "name": "WixQueryBadgeAssignmentsResponse",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixQueryBadgeAssignmentsResponse {\n  badgeAssignments?: WixBadgeAssignment[];\n  pagingMetadata?: WixCursorPagingMetadata;\n}"
+      },
+      {
+        "name": "WixBadgeIcon",
+        "kind": "interface",
+        "jsdoc": "/** The badge icon exactly as the live API sends it. The generated `WixBadge.icon` is typed `string`\n *  from the upstream package, but the service returns this image object. */",
+        "decl": "export interface WixBadgeIcon {\n  id?: string;\n  url?: string;\n  height?: number;\n  width?: number;\n}"
+      },
+      {
+        "name": "queryBadgeAssignments",
+        "kind": "function",
+        "jsdoc": "/** Which badges members hold — POST /badges/v4/assignments/query. A Visitor can read it\n *  (`BADGES.BADGE_READ_MEMBERS`), so a members list can show badges without a sign-in.\n *  Filter by `memberId: { $in: [...] }` and page with `cursorPaging`: a member can hold dozens of\n *  badges, so one page of many members can need several calls.\n *\n *  Prefer this over the generated `listMembersBadgeIds`, whose route\n *  (`POST /badges/v4/badges/members`) answers 404 on the live service.\n *\n * @scope visitor — an anonymous Visitor reads it (200, observed live). The generated spec declares the app\n * identity only, so a signed-in member's read is not yet observed: an empty or refused answer means \"no badge\n * known\", never \"no badge held\". */",
+        "decl": "export function queryBadgeAssignments(\n  req: WixQueryBadgeAssignmentsRequest = {},\n  opts?: WixCallOptions,\n): Promise<WixQueryBadgeAssignmentsResponse>;",
+        "http": "POST /badges/v4/assignments/query",
+        "scope": "visitor"
+      },
+      {
+        "name": "badgeIconUrl",
+        "kind": "function",
+        "jsdoc": "/** The icon image URL of a badge, or \"\" when it has none. Reads the live `{ url }` object and also the\n *  plain string the generated type promises, so a caller needs no cast. */",
+        "decl": "export function badgeIconUrl(badge: Pick<WixBadge, \"icon\">): string;"
       }
     ]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1622.0",
+  "version": "0.1623.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": [
@@ -72,5 +72,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "8493c132a80fa7832da317fe9ee68a3a247dd79165b74cbcc352855c"
+  "falconPackageHash": "b76913451cea96b12d1d1a1c061494918590b615daded10ac1c988fc"
 }

package/templates/branded-lite/tier5-src/_shared/access-gates-table.ts

@@ -0,0 +1,8 @@
+// This app's access gates: the One App page rules (members only, badge, paid plan) the app keeps.
+//
+// EMPTY in a scaffold, and then nothing in `access-gates.ts` reads or publishes anything. `himi one-app access`
+// replaces this file for a migrated One App whose source locks a page; do not edit it by hand, re-run the command
+// (it is idempotent).
+import type { AccessGate } from "./access-gates.js";
+
+export const ACCESS_GATES: readonly AccessGate[] = [];

package/templates/branded-lite/tier5-src/_shared/access-gates.ts

@@ -0,0 +1,341 @@
+// One App access gates: who may open a tab, decided in the app-level nav worker.
+//
+// A One App owner can lock a page (layout item) for members only, for holders of a badge, or for holders of a
+// paid plan, and choose whether a viewer who may not enter sees a lock screen or no tab at all. The One App
+// evaluates that per viewer on its server (`DisplayCriteria.getLayoutItemContentDisplayInfo`, `EnrichedViewer`)
+// and draws the lock on the client. A migrated Himi app carries the same rules in `access-gates-table.ts`
+// (written by `himi one-app access`) and this module answers them for the viewer.
+//
+// PRESENTATION ONLY. The data behind a gated tab stays protected by its own Wix API (a Visitor's call still
+// gets a 401/403/428). The descriptor is served to every device, so static content in it is not a secret; the
+// One App also sends a gated page's structure to the viewer it denies. This is the rule an owner set on the
+// tab, kept, and nothing stronger.
+//
+// FAIL CLOSED. Every gate starts `pending` (locked, and hidden when it may be hidden) and opens only on
+// positive proof. A read that fails leaves the member locked with the call to action for that rule. The state is
+// declared `notPersisted` and `notHydrated` on the service, so a restored snapshot can never unlock a tab, and a
+// new identity drops every gate back to `pending` before the next answer is read.
+//
+// ONE FLAG PER GATE, bound by the app: the tab bar binds `$service:brandedLiteNav.accessHidden.<key>` (with
+// `hiddenUntilResolved`), and the gated screen's `FragmentSlot` binds `$app:brandedLiteNav.accessState.<key>` (a screen's
+// own worker is not this one, so `$app:` reads the app-level nav worker), with the locked case as its default, so an unresolved value renders the lock and the page body is not mounted.
+//
+// Shared by the two app-level nav workers (`himi-branded-lite-nav`, `himi-branded-lite-header-badges`), which
+// name the same service. With an empty table nothing here reads anything.
+import { hostSessionFromGlobal } from "@himalaya/iap";
+import { activePlanIds } from "@himalaya/checkout";
+import { queryBadgeAssignments } from "@himalaya/wix-badges";
+import { getMyMember } from "@himalaya/wix-members";
+import { listPublicPlans } from "@himalaya/wix-pricing-plans";
+import { ACCESS_GATES } from "./access-gates-table.js";
+
+// ───────────────────────────── the table ─────────────────────────────
+
+/** What the owner required, as the One App stores it on the layout item. */
+export type AccessRule =
+  | { kind: "membersOnly" }
+  | { kind: "badges"; ids: string[] }
+  | { kind: "paidPlans"; ids: string[] };
+
+export interface AccessGate {
+  /** Flag-safe id (`[a-z0-9_]`), the key under `accessState` and `accessHidden`. */
+  key: string;
+  /** The One App layout item the rule was authored on. */
+  layoutItemId: string;
+  /** The Himi screen whose body is gated. */
+  screenId: string;
+  /** The page's title, for the lock screen. */
+  title: string;
+  rule: AccessRule;
+  /** `accessScreenSettings.screenVisible`: `locked` shows a lock screen, `hidden` removes the tab. */
+  mode: "locked" | "hidden";
+  /** `accessScreenSettings.membersOnly`: only a signed-in member may see the lock; a Visitor gets no tab. */
+  hideFromVisitors: boolean;
+  /** The owner's lock message and button label, or "" for the stock copy. */
+  message: string;
+  ctaTitle: string;
+}
+
+/** The lock screen a gated screen shows, and the one `pending` that renders until the first answer lands. */
+export type AccessCase = "pending" | "open" | "signIn" | "plans" | "contact";
+
+export interface AccessOutcome {
+  state: AccessCase;
+  /** The tab should not be listed at all. */
+  hidden: boolean;
+}
+
+/** Everything the rules ask about the viewer. */
+export interface AccessViewer {
+  member: boolean;
+  badgeIds: ReadonlySet<string>;
+  /** Plans the member holds an active order for. */
+  planIds: ReadonlySet<string>;
+  /** Plans the site offers (public, not archived): a lock can only offer a plan that can still be bought. */
+  publicPlanIds: ReadonlySet<string>;
+}
+
+const anyIn = (ids: readonly string[], held: ReadonlySet<string>): boolean => ids.some((id) => held.has(id));
+
+/** The plan ids a gate asks for; none for a rule of another kind. */
+const requiredPlanIds = (gate: AccessGate): readonly string[] => gate.rule.kind === "paidPlans" ? gate.rule.ids : [];
+
+/** Whether a Visitor or a member who may not enter should still see the tab (as a lock). */
+function listed(gate: AccessGate, visitor: boolean): boolean {
+  if (gate.mode === "hidden") return false;
+  return !(visitor && gate.hideFromVisitors);
+}
+
+/**
+ * The One App's rule for one gate. Mirrors `DisplayCriteria.getLayoutItemContentDisplayInfo` and
+ * `EnrichedViewer.filterLayoutItems`:
+ *  - a Visitor is blocked by every rule kind, and always gets the members-only lock (`signIn`);
+ *  - a member holds the badge (one of its ids), holds an active plan (one of its ids), or passes a members-only rule;
+ *  - a blocked member gets the lock for the rule's own kind: a badge asks to contact the business, a plan offers the
+ *    plans, or asks to contact the business when none of its plans is on offer any more (hidden or archived), as the
+ *    One App does (`LayoutItem.ts` `onPermissionZeroPlansClick`).
+ * There is no owner or admin bypass: an owner uses the owner app.
+ */
+export function decide(gate: AccessGate, viewer: AccessViewer): AccessOutcome {
+  if (!viewer.member) return { state: "signIn", hidden: !listed(gate, true) };
+  switch (gate.rule.kind) {
+    case "membersOnly":
+      return { state: "open", hidden: false };
+    case "badges":
+      return anyIn(gate.rule.ids, viewer.badgeIds) ? { state: "open", hidden: false } : { state: "contact", hidden: !listed(gate, false) };
+    case "paidPlans":
+      if (anyIn(gate.rule.ids, viewer.planIds)) return { state: "open", hidden: false };
+      return { state: anyIn(gate.rule.ids, viewer.publicPlanIds) ? "plans" : "contact", hidden: !listed(gate, false) };
+  }
+}
+
+/** Before any answer: locked, and hidden for every gate that some viewer would not see listed. */
+export function pendingOutcome(gate: AccessGate): AccessOutcome {
+  return { state: "pending", hidden: gate.mode === "hidden" || gate.hideFromVisitors };
+}
+
+// ───────────────────────────── the state ─────────────────────────────
+
+export interface AccessGateState {
+  /** `AccessCase` per gate key. Bound by the gated screen's `FragmentSlot`. */
+  accessState: Record<string, AccessCase>;
+  /** True per gate key when the tab is not listed. Bound by the tab bar, fail-closed. */
+  accessHidden: Record<string, boolean>;
+}
+
+export const ACCESS_STATE_KEYS: ("accessState" | "accessHidden")[] = ["accessState", "accessHidden"];
+
+export function pendingAccessState(gates: readonly AccessGate[]): AccessGateState {
+  const accessState: Record<string, AccessCase> = {};
+  const accessHidden: Record<string, boolean> = {};
+  for (const gate of gates) {
+    const outcome = pendingOutcome(gate);
+    accessState[gate.key] = outcome.state;
+    accessHidden[gate.key] = outcome.hidden;
+  }
+  return { accessState, accessHidden };
+}
+
+/** The initial service state: every gate pending. Empty for an app with no gates. */
+export const ACCESS_GATES_INITIAL: AccessGateState = pendingAccessState(ACCESS_GATES);
+
+/** The action signatures a service that uses `accessGates` declares in its `defineService` generic. */
+// A `type` for the same reason as `HeaderBadgeActionSignatures`: `defineService` wants an index signature.
+export type AccessGateActionSignatures<S> = {
+  /** Re-read who the viewer is and what they hold, then re-decide every gate. Only the newest read lands. */
+  refreshAccess: (s: S) => Promise<S>;
+  /** Put every gate back to pending (a new identity), committed at once so nothing stale stays open. */
+  dropAccess: (s: S) => Promise<S>;
+  /** Reserved lifecycle hooks the app-service host delivers to every service that declares them. */
+  onForeground: (s: S) => Promise<S>;
+  onIdentityChange: (s: S) => Promise<S>;
+};
+
+export interface AccessGates<S> {
+  actions: AccessGateActionSignatures<S>;
+  /** Call once after `defineService`: the launch read, and the session clock's notifications. */
+  start(): void;
+}
+
+type Update<S> = (s: S, change: (current: S) => Promise<S>) => Promise<S>;
+type Self = () => { refreshAccess(): Promise<unknown>; dropAccess(): Promise<unknown> };
+
+const sameJson = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
+
+/** The plans the site offers: public and not archived (the public list already leaves archived plans out). */
+async function readPublicPlanIds(): Promise<Set<string>> {
+  const res = await listPublicPlans();
+  return new Set((res.plans ?? []).filter((plan) => plan.id && !plan.archived).map((plan) => plan.id));
+}
+
+/** The bridge's refusal of a viewer who is not a member: `HTTP 401` or `HTTP 403` in its rejection text (which a caller
+ *  may prefix). A Visitor gets exactly `403 PERMISSION_DENIED` from `/members/my` (observed live). Any other status
+ *  (a 408, a 429, a 5xx) or a network failure says nothing about who the viewer is, so it must not decide anyone as a Visitor. */
+function isRefusal(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : String(error);
+  const at = text.indexOf("HTTP ");
+  if (at < 0) return false;
+  const status = Number(text.slice(at + 5, at + 8));
+  return status === 401 || status === 403;
+}
+
+/** Most pages of badge assignments one member can need (100 per page). A member past this is not realistic. */
+const MAX_BADGE_PAGES = 20;
+
+/** The badge ids a member holds. A read that cannot finish rejects, so the caller keeps the member locked. */
+async function readBadgeIds(memberId: string): Promise<Set<string>> {
+  const held = new Set<string>();
+  const seen = new Set<string>();
+  let cursor: string | undefined;
+  for (let page = 0; page < MAX_BADGE_PAGES; page++) {
+    // The cursor encodes the filter: a Wix query refuses a filter sent beside a cursor, so only the first page carries it.
+    const res = await queryBadgeAssignments({
+      query: cursor ? { cursorPaging: { limit: 100, cursor } } : { filter: { memberId: { $in: [memberId] } }, cursorPaging: { limit: 100 } },
+    });
+    for (const assignment of res.badgeAssignments ?? []) if (assignment.badgeId) held.add(assignment.badgeId);
+    const next = res.pagingMetadata?.cursors?.next;
+    if (!res.pagingMetadata?.hasNext) return held;
+    // More pages were promised but no cursor to reach them: a truncated answer, not a complete one. It must fail the read (the
+    // member stays locked, or an already-open page stays open) instead of passing a partial set off as everything.
+    if (!next) throw new Error("Badge assignment page said more were available but gave no cursor.");
+    if (seen.has(next)) throw new Error("Badge assignment pagination did not advance.");
+    seen.add(next);
+    cursor = next;
+  }
+  throw new Error("A member holds more badge assignments than one read pages.");
+}
+
+/**
+ * @param gates the app's table (a test passes its own)
+ * @param update serializes state changes for the worker, so overlapping actions build on the preceding result
+ * @param self the worker's own service handle (read lazily: it does not exist yet when this is called)
+ */
+export function accessGates<S extends AccessGateState>(update: Update<S>, self: Self, gates: readonly AccessGate[] = ACCESS_GATES): AccessGates<S> {
+  /** Which read is the newest: an older one that finishes later must not overwrite a newer answer. */
+  let read = 0;
+  /** The host session generation the gates on show were decided under. */
+  let generation = -1;
+  const session = hostSessionFromGlobal();
+  const needsBadges = gates.some((gate) => gate.rule.kind === "badges");
+  const needsPlans = gates.some((gate) => gate.rule.kind === "paidPlans");
+
+  /** The signed-in member's id, `null` for a Visitor, `undefined` when it could not be told (a failed read that is
+   *  not a refusal, such as being offline). A host that fences calls to the member publishes the id with its
+   *  session clock; any other host (web) answers it from the member record, which a Visitor cannot read. */
+  async function memberIdOf(): Promise<string | null | undefined> {
+    if (session.identityBound) {
+      const snapshot = session.current();
+      if (snapshot.kind !== "member") return null;
+      const id = session.identity(snapshot)?.memberId;
+      if (id) return id;
+    }
+    try {
+      return (await getMyMember({ fieldsets: ["PUBLIC"] })).member?.id || null;
+    } catch (error) {
+      return isRefusal(error) ? null : undefined;
+    }
+  }
+
+  const pending = (current: S): S => ({ ...current, ...pendingAccessState(gates) });
+
+  const actions: AccessGateActionSignatures<S> = {
+    refreshAccess: async (s) => {
+      if (!gates.length) return s;
+      const mine = ++read;
+      const startedUnder = session.current().generation;
+      const memberId = await memberIdOf();
+      let badgeIds = new Set<string>();
+      let planIds = new Set<string>();
+      let publicPlanIds = new Set<string>();
+      let badgesFailed = false;
+      let plansFailed = false;
+      if (memberId) {
+        const [badges, plans] = await Promise.all([
+          needsBadges ? readBadgeIds(memberId).catch(() => { badgesFailed = true; return new Set<string>(); }) : Promise.resolve(new Set<string>()),
+          needsPlans ? activePlanIds().then((ids) => new Set(ids)).catch(() => { plansFailed = true; return new Set<string>(); }) : Promise.resolve(new Set<string>()),
+        ]);
+        badgeIds = badges;
+        planIds = plans;
+        // Which plans can still be bought matters only to a member a plan gate blocks: read it then, not for everyone.
+        const required = gates.map(requiredPlanIds);
+        if (plansFailed) {
+          // What the member holds is unknown: offer every required plan, the plans list is the useful action.
+          publicPlanIds = new Set(required.flat());
+        } else if (needsPlans && required.some((ids) => ids.length > 0 && !anyIn(ids, planIds))) {
+          // A read of the offer that fails offers every required plan too, and the plans list reads for itself.
+          publicPlanIds = await readPublicPlanIds().catch(() => new Set(required.flat()));
+        }
+      }
+      const viewer: AccessViewer = { member: memberId !== null && memberId !== undefined, badgeIds, planIds, publicPlanIds };
+      return update(s, async (current) => {
+        // Drop an answer read for another read or another identity: the newer one decides.
+        if (mine !== read || session.current().generation !== startedUnder) return current;
+        // Who the viewer is could not be told: change nothing (pending stays pending, so locked).
+        if (memberId === undefined) return current;
+        const accessState: Record<string, AccessCase> = {};
+        const accessHidden: Record<string, boolean> = {};
+        for (const gate of gates) {
+          const readFailed = (gate.rule.kind === "badges" && badgesFailed) || (gate.rule.kind === "paidPlans" && plansFailed);
+          // A failed read must not lock out a member already shown the page (a blip while offline). Otherwise the
+          // member is treated as not holding the badge or plan: locked, with that rule's call to action.
+          if (readFailed && current.accessState[gate.key] === "open") {
+            accessState[gate.key] = "open";
+            accessHidden[gate.key] = false;
+            continue;
+          }
+          const outcome = decide(gate, viewer);
+          accessState[gate.key] = outcome.state;
+          accessHidden[gate.key] = outcome.hidden;
+        }
+        // Publish only a change: an unchanged answer reaches no view (and costs the worker nothing).
+        if (sameJson(current.accessState, accessState) && sameJson(current.accessHidden, accessHidden)) return current;
+        return { ...current, accessState, accessHidden };
+      });
+    },
+    dropAccess: async (s) => {
+      ++read; // a read already in flight belongs to the previous identity
+      return update(s, async (current) => pending(current));
+    },
+    onForeground: async (s) => update(s, async (current) => current).finally(() => { void self().refreshAccess(); }),
+    onIdentityChange: async (s) => {
+      ++read;
+      const dropped = await update(s, async (current) => pending(current));
+      void self().refreshAccess();
+      return dropped;
+    },
+  };
+
+  /** A session notification: a new generation is a new identity, so the previous one's gates close first. */
+  async function onSession(): Promise<void> {
+    const now = session.current().generation;
+    if (now !== generation) {
+      generation = now;
+      await self().dropAccess();
+    }
+    await self().refreshAccess();
+  }
+
+  return {
+    actions,
+    start(): void {
+      if (!gates.length) return;
+      // Subscribing notifies at once, which is the launch read; a host with no clock needs the explicit one.
+      let notified = false;
+      session.subscribe(() => { notified = true; void onSession(); });
+      if (!notified) void self().refreshAccess();
+    },
+  };
+}
+
+/**
+ * The reserved lifecycle hooks of a service that serves more than one piece (header badges, access gates): the host
+ * calls one `onForeground` and one `onIdentityChange`, so each piece's hook runs in turn.
+ */
+export function chainLifecycle<S>(
+  ...pieces: Array<{ onForeground: (s: S) => Promise<S>; onIdentityChange: (s: S) => Promise<S> }>
+): { onForeground: (s: S) => Promise<S>; onIdentityChange: (s: S) => Promise<S> } {
+  return {
+    onForeground: async (s) => { let next = s; for (const piece of pieces) next = await piece.onForeground(next); return next; },
+    onIdentityChange: async (s) => { let next = s; for (const piece of pieces) next = await piece.onIdentityChange(next); return next; },
+  };
+}

package/templates/branded-lite/tier5-src/himi-branded-lite-access-nav/index.ts

@@ -0,0 +1,45 @@
+// The app-level nav worker (`navigation.navLogicBundle`) of a migrated One App that keeps locked pages: the live counts
+// behind the header's bell, chat and cart buttons (the same piece as `himi-branded-lite-header-badges`), plus the page
+// access gates (members only, badge, paid plan) the source's owner set (`_shared/access-gates.ts`).
+//
+// It is a separate bundle on purpose. The gates read the member, their badges and their plans, which an app that locks
+// no page has no use for, and a worker's source is parsed at every boot. `himi one-app access` points an app's
+// `navLogicBundle` here only when the source locks a page; every other app keeps the badges-only worker, unchanged.
+//
+// The service is named `brandedLiteNav`, like the full worker's, so a top-bar action binds the same
+// `$service:brandedLiteNav.<field>` path and the tab bar and gated screens bind `accessHidden` and `accessState`
+// under it. A scaffold ships this source INERT: nothing loads it until the app's config names it.
+
+import { defineService } from "@himalaya/state";
+import { HEADER_BADGE_KEYS, headerBadges, type HeaderBadgeActionSignatures, type HeaderBadges, type HeaderBadgeState } from "../_shared/header-badges.js";
+import { ACCESS_GATES_INITIAL, ACCESS_STATE_KEYS, accessGates, chainLifecycle, type AccessGateActionSignatures, type AccessGates, type AccessGateState } from "../_shared/access-gates.js";
+
+type State = HeaderBadgeState & AccessGateState;
+
+// State changes await native work; overlapping actions must use the preceding result.
+let stateQueue: Promise<State> | undefined;
+function updateInOrder(s: State, update: (current: State) => Promise<State>): Promise<State> {
+  const previous = stateQueue ?? Promise.resolve(s);
+  const result = previous.then(update);
+  stateQueue = result.catch(() => previous);
+  return result;
+}
+
+const badges: HeaderBadges<State> = headerBadges<State>(updateInOrder, () => svc);
+const access: AccessGates<State> = accessGates<State>(updateInOrder, () => svc);
+
+const svc = defineService<State, HeaderBadgeActionSignatures<State> & AccessGateActionSignatures<State>>("brandedLiteNav", {
+  // Every count unavailable until the first read lands, and no failure to report. Every gate pending (locked).
+  state: { notificationsBadge: null, chatBadge: null, cartBadge: null, errorText: "", ...ACCESS_GATES_INITIAL },
+  // The counts and the gates describe THIS run (see _shared/header-badges.ts, _shared/access-gates.ts): never stored,
+  // never restored, so a snapshot can neither show another day's numbers nor keep a tab open.
+  notPersisted: [...HEADER_BADGE_KEYS, ...ACCESS_STATE_KEYS],
+  notHydrated: [...HEADER_BADGE_KEYS, ...ACCESS_STATE_KEYS],
+  // The host calls one `onForeground` and one `onIdentityChange`: each piece runs in turn.
+  actions: { ...badges.actions, ...access.actions, ...chainLifecycle<State>(badges.actions, access.actions) },
+});
+
+export { svc };
+
+badges.start();
+access.start();