@wix/himalaya-cli 0.1571.0 → 0.1573.0

package/guides/index.json

@@ -296,6 +296,12 @@
       "category": "Wix SDK",
       "file": "one-app-to-himi-app.md"
     },
+    {
+      "id": "recipe-one-app-coverage-mapping",
+      "title": "Recipe: map One App coverage decisions",
+      "category": "Recipes",
+      "file": "recipe-one-app-coverage-mapping.md"
+    },
     {
       "id": "one-app-reference",
       "title": "One App reconstruction references and provenance",
@@ -441,6 +447,7 @@
     "showcaseFile": "stocks-dashboard.descriptor.json"
   },
   "examples": [
+    "map-one-app-coverage.js",
     "counter.service.ts",
     "counter-t5.descriptor.json",
     "stocks-dashboard.descriptor.json",

package/guides/map-one-app-coverage.js

@@ -0,0 +1,117 @@
+// Local reference recipe, not a readiness check. See himi docs recipe-one-app-coverage-mapping.
+import { execFileSync } from "node:child_process";
+import { lstatSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+const sameTarget = (a, b) => a?.screenId === b?.screenId && a?.controlId === b?.controlId;
+const needsControl = row => row.kind === "interaction" || row.kind === "top-bar";
+
+function idsIn(value, ids = new Set()) {
+  if (Array.isArray(value)) value.forEach(item => idsIn(item, ids));
+  else if (object(value)) {
+    const component = typeof value.body?.type === "string" || (typeof value.type === "string" && object(value.props));
+    if (component && typeof value.id === "string" && !value.id.includes("$")) ids.add(value.id);
+    for (const [key, item] of Object.entries(value)) if (key !== "params" && key !== "metadata") idsIn(item, ids);
+  }
+  return ids;
+}
+
+function controlIds(screen) {
+  const ids = idsIn([screen.payload, screen.stickyHeader, screen.stickyFooter]);
+  for (const action of screen.topBar?.actions ?? []) {
+    if (typeof action.id === "string" && !action.id.includes("$")) ids.add(action.id);
+  }
+  return ids;
+}
+
+/** Inputs are explicit decisions and the full authored descriptor map, with effective top bars. */
+export function mapCoverage(ledger, decisions, screens) {
+  if (ledger?.version !== 1 || ledger.workflow !== "one-app-to-himi-app" || !Array.isArray(ledger.requirements)
+    || !Array.isArray(decisions) || !object(screens)) throw new Error("Expected a coverage ledger, decision array and authored screen map.");
+  const coverage = structuredClone(ledger);
+  const rows = coverage.requirements;
+  if (new Set(rows.map(row => row.id)).size !== rows.length) throw new Error("Duplicate ledger row IDs; run coverage check.");
+  const issues = [];
+  const selected = new Map();
+  const invalidate = row => {
+    row.status = "unresolved";
+    delete row.target;
+    delete row.verification;
+    delete row.adaptation;
+  };
+  const targetProblem = (row, target) => {
+    if (!object(target) || Object.keys(target).some(key => !["screenId", "controlId"].includes(key))) return "Expected only screenId and optional controlId.";
+    if (typeof target.screenId !== "string" || !target.screenId.trim()) return "An explicit target screenId is required.";
+    const screen = Object.hasOwn(screens, target.screenId) && screens[target.screenId];
+    if (!object(screen) || screen.screenId !== target.screenId) return "Target screen is absent from the authored descriptor map.";
+    if (needsControl(row) && (typeof target.controlId !== "string" || !target.controlId.trim())) return "This row requires an explicit controlId.";
+    if (target.controlId !== undefined && !controlIds(screen).has(target.controlId)) return "Target control ID is absent from that screen, including its effective top bar.";
+  };
+  // A removed target cannot retain a passing record merely because no decision mentions it.
+  for (const row of rows) if (row.kind !== "design" && targetProblem(row, row.target)) invalidate(row);
+  for (const [index, decision] of decisions.entries()) {
+    if (!object(decision)) { issues.push({ decision: index, reason: "Expected an explicit row/source decision." }); continue; }
+    const matches = rows.filter(row => typeof decision.id === "string" ? row.id === decision.id
+      : typeof decision.source === "string" && row.source === decision.source && row.kind === decision.kind && row.platform === decision.platform);
+    if (matches.length !== 1) { issues.push({ decision: index, reason: "Unknown or ambiguous row/source; use the exact row ID or kind/source/platform." }); continue; }
+    const row = matches[0];
+    if (row.kind === "design") { issues.push({ decision: index, id: row.id, reason: "Design rows belong to validate-design, not screen mapping." }); continue; }
+    const allowed = typeof decision.id === "string" ? ["id", "target"] : ["source", "kind", "platform", "target"];
+    const problem = Object.keys(decision).some(key => !allowed.includes(key)) ? "Decisions cannot set status, verification, adaptation or other row fields."
+      : targetProblem(row, decision.target);
+    if (selected.has(row.id)) {
+      selected.set(row.id, null);
+      invalidate(row);
+      issues.push({ decision: index, id: row.id, reason: "Duplicate decisions for this row; left unresolved." });
+    } else {
+      selected.set(row.id, problem ? null : decision.target);
+      if (problem) { invalidate(row); issues.push({ decision: index, id: row.id, reason: problem }); }
+    }
+  }
+  for (const [id, target] of selected) {
+    if (!target) continue;
+    const row = rows.find(row => row.id === id);
+    if (!sameTarget(row.target, target)) {
+      invalidate(row);
+      row.target = { ...target };
+    }
+  }
+  return {
+    coverage,
+    issues,
+    unmapped: rows.filter(row => row.kind !== "design" && !row.target).map(({ id, kind, source, platform }) => ({ id, kind, source, ...(platform ? { platform } : {}) })),
+    // Inventory checks cannot validate retained proof against the author's current built release.
+    needsVerification: rows.map(row => row.id),
+  };
+}
+
+export function main(args) {
+  const [content, evidence, decisionsFile, screensFile, ...flags] = args;
+  if (!screensFile || flags.some(flag => flag !== "--write") || flags.length > 1) throw new Error("Usage: node map-one-app-coverage.js <content> <evidence-dir> <decisions.json> <screens.json> [--write]");
+  // Reuse the installed CLI's actual source hashes, derived row IDs and schema checks. No sync/write.
+  execFileSync(process.env.HIMI_BIN ?? "himi", ["one-app", "coverage", "check", "--content", content, "--evidence-dir", evidence, "--json", "--skip-version-check"], { stdio: ["ignore", "pipe", "pipe"] });
+  const ledgerFile = resolve(content, "ONE-APP-COVERAGE.json");
+  if (!lstatSync(ledgerFile).isFile() || lstatSync(ledgerFile).isSymbolicLink()) throw new Error("The ledger must be a regular file.");
+  const read = file => JSON.parse(readFileSync(file, "utf8"));
+  const result = mapCoverage(read(ledgerFile), read(decisionsFile), read(screensFile));
+  if (flags.includes("--write")) {
+    for (let directory = resolve(content);; directory = dirname(directory)) {
+      const stat = lstatSync(directory);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("Use a physical content directory without symlinked parents for --write.");
+      if (directory === dirname(directory)) break;
+    }
+    writeFileSync(ledgerFile, JSON.stringify(result.coverage, null, 2) + "\n");
+  }
+  console.log(JSON.stringify({ ...result, written: flags.includes("--write") }, null, 2));
+  return result.issues.length || result.unmapped.length ? 1 : 0;
+}
+
+if (process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+  try { process.exitCode = main(process.argv.slice(2)); }
+  catch (error) {
+    console.error(JSON.stringify({ ok: false, code: "coverage_mapping_input_invalid", error: error.message }));
+    process.exitCode = 1;
+  }
+}

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

@@ -136,6 +136,50 @@ Missing or virtual map points stay absent; an address alone is not coordinates.
 If a transient failure makes this read unavailable, the manifest records
 `business_contact_unavailable`. Keep contact coverage unresolved until the data is
 verified, rather than inventing an address or silently omitting the section.
+
+### Native widget defaults
+
+Empty settings do not mean an empty native widget. Coverage derives separate
+`native-widget` obligations for each placement from the runtime checklist below,
+including repeated sections, detached pages and Business Profile placements.
+These are behaviors to compare, not claims that the target implements them.
+The CLI's versioned native-widget inventory supplies these rows automatically.
+
+| Source section type | Effective behavior to verify |
+| --- | --- |
+| `bookings_services_list_section` | Search, category and location filters. |
+| `single_group_feed_section`, `groups_feed_section` | Post actions, attachments, comments/post destination, topic filter and the group's Members / Library / Rules / Media destinations. |
+| `platform_general_contact_section`, `platform_general_contact_section_bp` | Business address and map, respecting authored visibility and available coordinates. |
+| `achievements_list_section` | Category filter, including All Categories with no categories; actual visitor/member login, access/join/payment/Continue states; participants line; default limit 2 and See All when applicable. |
+| `achievements_carousel_section` | The same Program state/display rules, default limit 5 and page dots. |
+| `newBlog_postlist_vertical_section` | See All Posts when a limited list has more results, preserving its scope. |
+| `events_list_section` | Date badge, Share and the appropriate RSVP/ticket action. |
+| `platform_general_members_section`, `platform_general_members_section_bp` | Effective member strip and directory journey: totals/search, alphabetical sections, Follow, activity/privacy. Distinguish badge chips from actual viewed-member program progress. |
+
+This initial checklist comes from reported native source-device observations
+on 2026-11-02 across two migrations, not editor demo records.
+Program settings are also backed by the pinned
+[Program section implementation](https://github.com/wix-private/wix-one-app-achievements/tree/f844eee1fe7cc7732531c3deaa7dca777e53c548/sections "audience-lint-ok: optional pinned upstream evidence, not a local authoring dependency").
+Its absent category selection means All/future categories; explicit empty selection
+means none. MANUAL order prioritizes selected IDs without excluding other records.
+Use current collected settings and source-device behavior to resolve each instance.
+An explicit disable/override is source evidence: faithfully preserving it requires
+no adaptation waiver, and this checklist must not force the disabled control on.
+Data/access-dependent controls need the relevant source state; never fabricate
+participants or derive program completion from a badge title.
+
+The table is not exhaustive. Other section types get an explicit unverified-defaults
+obligation; inventory their effective source behavior rather than assuming there
+are no defaults. Changing the behavior contract creates new requirement identities.
+Recollection invalidates status/check evidence while preserving unchanged mappings.
+
+Compare every tab in the actual Player or Branded Lite host with the source app
+on device and live data under the same site and visitor/member identity. The editor
+can show demo members/badges or blank verticals; editor-only observations remain
+unverified. Until missing behavior is implemented, retain an honest unresolved,
+conditional or explicitly authorized adapted row. Do not mark it supported merely
+because its placement exists.
+
 `business-context.json.memberCount` preserves a valid Business aggregate
 `members.count` when available. For source `platform_general_members_section` or
 `platform_general_members_section_bp` widgets, collection instead reads the
@@ -235,10 +279,30 @@ Apply these interpretation rules:
   because a missing scheme falls back to the light value. Rebuild after `--fix`.
   For Branded apps, known source typography IDs (for example `lato`) become family
   names (`Lato`); tokens whose names contain title/heading/headline/display/hero use the heading family; other
-  typography tokens use the body family. Numeric metrics stay unchanged. Unknown IDs,
-  families outside the Himi font catalog, and missing target typography roles remain unresolved; resolve them before recording
-  a pass, even when the coverage ledger cites an adaptation. A deliberate difference
-  between resolved font roles can still be adapted. Build/font validation still has
+  typography tokens use the body family. Numeric metrics stay unchanged. Read each
+  source heading/body family and check `himi fonts list`; use `himi fonts add <Family>`
+  when it is available. A known source family that Himi does not ship (for example
+  `spaceGrotesk` → Space Grotesk) is still compared with the actual target family.
+  Choose an available replacement, such as `$system`, only with the owner's explicit
+  instruction; this is an adaptation, never a font match. Sync the coverage ledger
+  against the current source evidence, then mark the corresponding `design` requirement
+  `adapted` with `adaptation.instruction` citing that instruction and
+  `adaptation.explanation` naming the source, replacement and reason. Bind a base font decision
+  to the exact reported `target` string in `adaptation.target` (for example,
+  `"body: $system, caption: $system"`); a later replacement requires a new decision.
+  When an active idiom changes the font, name it in `adaptation.idioms` and copy its
+  reported target into `adaptation.idiomTargets[idiom]`. An overlay that keeps the base
+  fonts needs no separate font approval. When the base already matches, an idiom-only
+  decision needs only `idioms` and `idiomTargets`, without a base `target`.
+  Rerun `himi one-app validate-design` to produce
+  the source-to-target report; without that adaptation the difference fails the check.
+  `--fix` imports supported source families but never chooses a fallback or writes
+  an unavailable family. Unknown source IDs, unsupported target families and missing
+  or invalid target typography metrics remain unresolved even with an adaptation.
+  Omitted families also remain unresolved: renderer defaults differ across surfaces;
+  author `$system` explicitly when that is the approved replacement. `--fix` may fill
+  omitted families from a supported source while preserving valid numeric metrics.
+  Build/font validation still has
   to prove the font bytes are available. Unresolved fonts and contrast also fail
   the plain check used by push, not only `--record`.
   Branded accent text must reach 4.5:1: `textOnAccent` against the fill, and `accentText` against the target page and declared neutral
@@ -437,6 +501,53 @@ mapping rows are research leads: inspect the current CLI's component, SDK and
 template contracts before using them. A previously empty row does not prove the
 feature is impossible today.
 
+### Standalone launch tab
+
+When the reconstructed navigation has a tab bar, preserve the app's actual tab
+IDs, source order, labels, icons and content. Do not keep the starter template's
+`home` ID or rename the first tab to `home` merely to match a shell default.
+An actual source tab named `home` is valid; the name is not reserved or required.
+A tab ID is not a `screenId`: a Community tab can use `id: "community"` with
+`screenId: "community_home"` and its visible Community label.
+For navigation with no tab bar, do not add a synthetic Home tab.
+
+Validate that tab IDs are non-empty and unique. Keep the source-to-target lookup,
+every `tabId` in
+`navigation.linkableScreens`, tab-selection actions and worker navigation requests
+consistent with the actual destination IDs, including detail screens that belong
+to the first tab. Remove stale template references instead of renaming the app's
+tabs to make them match. `himi validate --strict` rejects empty or duplicate tab
+IDs and linkable `tabId` references outside the selectable primary navigation
+on enabled surfaces when chrome lists are configured. An auxiliary drawer row is
+not a compact responsive tab: use an empty/default-stack `tabId` for a pushed
+screen without an owning tab. Explicit primary drawer/sidebar modes and declared
+surface overrides use their own destinations. This config-only membership check
+does not prove source fidelity, dynamic navigation requests, or deep-link behavior
+on every surface; verify those independently. For example,
+the navigation fragment for a Community-first app is:
+
+```json
+{
+  "tabBar": {
+    "items": [
+      { "id": "community", "screenId": "community_home", "label": "Community", "icon": "people" },
+      { "id": "profile", "screenId": "member_profile", "label": "Profile", "icon": "person" }
+    ]
+  },
+  "linkableScreens": [
+    { "screenId": "community_home", "isPublic": true, "paramKeys": [], "parentScreenId": "", "tabId": "community" },
+    { "screenId": "community_post", "isPublic": true, "paramKeys": ["id"], "parentScreenId": "community_home", "tabId": "community" }
+  ]
+}
+```
+
+Current standalone bottom-tab chrome selects the first visible configured tab
+when its stored selection is unknown. Do not infer this fallback for sidebar or
+responsive-wide chrome: verify its launch selection independently. A stored
+template default such as `home` must not override the app's navigation or leave
+it blank. If a binary does not handle the app's actual IDs, fix or update that
+shell and report the incompatibility; do not disguise it by renaming the first tab.
+
 ## 2. Write the reconstruction plan and resolve gaps
 
 Write `.himi/one-app/reconstruction-plan.md` before scaffolding. Describe the app
@@ -578,9 +689,10 @@ 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 and app-wide design values as well as routes and
+Rows cover native widget behavior, 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.
+actions work. For explicit batch target decisions without inventing verification, use the
+[executable ledger mapping recipe](https://apps.wix.com/_api/himi-serve/docs/recipe-one-app-coverage-mapping.md).
 
 Preserve the existing app mark after scaffolding: run `himi icon from-one-app
 --content . --evidence-dir .himi/one-app`. This reads the hash-verified collected
@@ -602,7 +714,7 @@ satisfied by the design check instead. Set its `status` to `supported`, `adapted
 `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`, `design-token`, or `source-resolution`), a safe relative path to
+`topbar-control`, `access-state`, `design-token`, `source-resolution`, or `native-widget-behavior`), 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
@@ -638,6 +750,21 @@ For example, one entry in the referenced JSON file is:
 The artifact must exist. Review the actual route and state shown in it before
 recording a pass; a valid record is an index to the check, not a substitute for it.
 
+For a `native-widget` row use `check: "native-widget-behavior"` and include
+`sourceBaseline` and `targetContext` in that check record. For example:
+
+```json
+{"checks":[{"requirementId":"<widget-row-id>","check":"native-widget-behavior","releaseHash":"<64-hex-sha256>","status":"passed","target":{"screenId":"home"},"artifact":".himi/one-app/device/target.png","sourceBaseline":{"kind":"native-device","artifact":".himi/one-app/device/source.png","siteId":"<same-site-id>","identityContext":"visitor-session-1"},"targetContext":{"siteId":"<same-site-id>","identityContext":"visitor-session-1"}}]}
+```
+
+`identityContext` is a private, opaque label for the compared identity, never a
+credential, email address or session token. Both artifacts must be local safe
+relative paths. The check rejects editor baselines and mismatched site/identity
+labels. It checks record consistency; it cannot establish that screenshots are
+authentic or that the observed behavior matches them. Review the artifacts and
+exercise each effective control, including authored overrides and access states.
+This comparison does not replace the QA APK/native proof below.
+
 After publishing a draft, build a QA APK pinned to that draft release with
 `himi dist --platform android --release <draft-id> --allow-draft`. Install
 and walk through every requirement on the device. Save
@@ -851,6 +978,13 @@ transactions against fixtures only. Read-only live checks verify the correct sit
 entity selection and runtime identity; they do not authorize placing orders,
 bookings, payments, form submissions or destructive updates during validation.
 
+For a tabbed migration, cold-launch the standalone app without a launch-screen
+override or incoming deep link. Confirm the first tab is selected and displays
+content. Then switch tabs and open a detail link belonging to the first tab;
+confirm it selects that tab and opens the intended screen. A hosted preview alone
+does not establish standalone launch behavior. Record an unavailable native check
+as unverified in the migration report.
+
 The UX audit requires app-specific network fixtures. `himi test --record` records
 only boot-time reads with the app's visitor identity, then crawls hermetically.
 Review its recorded/refused requests; do not run a source getter known to mutate

package/guides/recipe-one-app-coverage-mapping.md

@@ -0,0 +1,74 @@
+# Recipe: map a One App coverage ledger
+
+Use explicit reconstruction decisions to map a large `ONE-APP-COVERAGE.json` without
+rewriting its source-derived IDs. This recipe only assigns targets. It never records a
+passed check, chooses a customer route, or makes an unresolved requirement supported.
+
+Run the existing coverage commands first:
+
+```sh
+himi one-app coverage init --evidence-dir .himi/one-app --content .
+# After source recollection or a CLI upgrade, use coverage sync and review its changes.
+himi one-app coverage check --evidence-dir .himi/one-app --content .
+```
+
+The runnable example is installed by `himi init` and refreshed by `himi agent-init` at
+`.agents/skills/himalaya/examples/map-one-app-coverage.js`. It uses the installed
+`himi one-app coverage check` before reading the ledger, so stale hashes, invented rows
+and changed source requirements refuse the operation. It does not execute app workers
+or call Wix. Keep decisions, descriptors and reports under `.himi/`.
+
+Write `.himi/one-app/mapping-decisions.json` as an array. Select each row by its exact
+`id`, or by exact `kind`, JSON-pointer `source`, and `platform` when present:
+
+```json
+[
+  { "kind": "route", "source": "/screens/source_home", "target": { "screenId": "home" } },
+  { "id": "<interaction-row-id-from-the-ledger>", "target": { "screenId": "home", "controlId": "view_products" } }
+]
+```
+
+Copy source pointers and IDs from the ledger; do not derive them from labels, row
+positions, or guessed routes. An ambiguous source selector requires the row ID. Each
+decision may set only its target, never status, adaptation or verification. A `design`
+row is app-wide and belongs to `validate-design`; leave it out of mapping decisions.
+
+Generate `.himi/one-app/mapping-screens.json` from the **same authored descriptor data**
+used by the app generator: `{ "home": { "screenId": "home", "payload": { … } }, … }`.
+Include every authored screen and each screen's effective top bar (its override or the
+actual `navigation.topBarDefault`). Serialize builders at generation time. Do not
+invent a screen/control inventory to make a decision pass. Missing or dynamically
+unresolved IDs stay unmapped. Control-ID presence is only an identity check; a real
+interaction or top-bar check must still prove the behavior.
+
+Inspect a dry run first, then write the reviewed mappings:
+
+```sh
+node .agents/skills/himalaya/examples/map-one-app-coverage.js \
+  . .himi/one-app .himi/one-app/mapping-decisions.json .himi/one-app/mapping-screens.json \
+  > .himi/one-app/mapping-review.json
+# Review coverage, issues, unmapped and needsVerification in that JSON.
+node .agents/skills/himalaya/examples/map-one-app-coverage.js \
+  . .himi/one-app .himi/one-app/mapping-decisions.json .himi/one-app/mapping-screens.json --write
+himi one-app coverage check --evidence-dir .himi/one-app --content .
+himi one-app validate-topbar --evidence-dir .himi/one-app --content .
+```
+
+For `--write`, use the physical app directory, without symlinked parent directories;
+the ledger itself must also be a regular file. Running the installed script through a
+symlink is supported. Without `--write` the ledger is unchanged. Exit 1 means there are invalid decisions or
+unmapped rows; the JSON lists them. With `--write`, valid decisions are retained while
+unknown targets, missing controls and duplicate decisions leave their rows unresolved.
+An unknown source/row creates no requirement and is reported in `issues`.
+
+A changed mapping loses its old verification and adaptation and becomes `unresolved`.
+An unchanged mapping retains its existing evidence; unrelated valid rows, IDs and source
+hashes are preserved. A target removed from the authored map also loses its old evidence.
+`needsVerification` lists every row: this recipe cannot validate retained proof against
+the current built release. Use `coverage verify --release-hash <sha256>` with the real
+release hash to check it, including unchanged mappings and previously saved records.
+Mapping output is not a readiness verdict. Decide supported/adapted/conditional status
+only after implementing and testing the corresponding behavior, with the required
+artifact and exact release hash. Run `validate-design --fix`, rebuild, then record the
+final design/UX/coverage evidence before pushing; repeat affected records after content
+changes. The main migration guide defines those checks and their limitations.

package/guides/sdk-reference.json

@@ -2771,7 +2771,7 @@
         "name": "OrderFailureCode",
         "kind": "type",
         "jsdoc": "",
-        "decl": "export type OrderFailureCode =\n  | \"notEnabled\" | \"notConfigured\" | \"signInRequired\" | \"unsupportedItem\" | \"notAppleRoute\"\n  | \"storageUnavailable\" | \"approvalRequired\" | \"orderClosed\" | \"orderRefused\" | \"chargeFailed\"\n  | \"paymentRefused\" | \"paymentHeld\" | \"alreadyOwned\" | \"paymentInProgress\" | \"productChanged\"\n  | \"invalidAssociation\" | \"needsSupport\" | \"unavailable\" | \"sessionChanged\" | \"outcomeUnknown\";"
+        "decl": "export type OrderFailureCode =\n  | \"notEnabled\" | \"notConfigured\" | \"signInRequired\" | \"unsupportedItem\" | \"notAppleRoute\"\n  | \"storageUnavailable\" | \"approvalRequired\" | \"orderClosed\" | \"orderRefused\" | \"chargeFailed\"\n  | \"paymentRefused\" | \"paymentHeld\" | \"alreadyOwned\" | \"paymentInProgress\" | \"productChanged\"\n  | \"sitePaymentUnavailable\" | \"invalidAssociation\" | \"needsSupport\" | \"unavailable\" | \"sessionChanged\" | \"outcomeUnknown\";"
       },
       {
         "name": "PaymentAccess",
@@ -2849,7 +2849,7 @@
         "name": "IapPurchaseCopy",
         "kind": "interface",
         "jsdoc": "/** Labels from the screen's copy pack; the shared layer only chooses between them. */",
-        "decl": "export interface IapPurchaseCopy {\n  buy: string;\n  buyAnother?: string;\n  processing: string;\n  awaitingApproval: string;\n  unavailable: string;\n  signInRequired: string;\n  retry: string;\n  priceChanged: string;\n  support: string;\n}"
+        "decl": "export interface IapPurchaseCopy {\n  buy: string;\n  buyAnother?: string;\n  processing: string;\n  awaitingApproval: string;\n  unavailable: string;\n  signInRequired: string;\n  retry: string;\n  /** Optional for existing SDK consumers; the app supplies a localized recovery message. */\n  sitePaymentUnavailable?: string;\n  priceChanged: string;\n  support: string;\n}"
       },
       {
         "name": "IapPurchaseFields",
@@ -23606,6 +23606,12 @@
         "jsdoc": "/** List the signed-in member's notifications, newest first. MOBILE channel. */",
         "decl": "export async function queryNotifications(limit = 25, options?: WixCallOptions): Promise<MfvNotification[]>;"
       },
+      {
+        "name": "countUnseenNotifications",
+        "kind": "function",
+        "jsdoc": "/** Source member-app MOBILE/UNSEEN aggregate, capped at 100. Requires a bound\n * single-site Member transport; old native binaries and web reject. A missing,\n * malformed or failed result is unavailable, never an authoritative zero. */",
+        "decl": "export async function countUnseenNotifications(options: { site: string }): Promise<number>;"
+      },
       {
         "name": "markRead",
         "kind": "function",
@@ -25554,13 +25560,37 @@
         "jsdoc": "",
         "decl": "export interface WixListFeedItemsResponse {\n  feedItems: WixFeedItem[];\n  profiles?: WixFeedProfile[];\n  nextPageCursor?: string;\n}"
       },
+      {
+        "name": "WixFeedPageOptions",
+        "kind": "interface",
+        "jsdoc": "/** Read controls shared by the source's single-group and central feeds. */",
+        "decl": "export interface WixFeedPageOptions extends WixCallOptions {\n  /** Opaque server cursor; pass it back unchanged when loading the next page. */\n  cursor?: string;\n  invalidatePermissionsCache?: boolean;\n}"
+      },
+      {
+        "name": "WixGroupFeedOptions",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixGroupFeedOptions extends WixFeedPageOptions {\n  topicId?: string;\n}"
+      },
+      {
+        "name": "WixCentralFeedOptions",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixCentralFeedOptions extends WixFeedPageOptions {\n  withSuggestedPosts?: boolean;\n  /** Omit to use the central-feed service's default representation. */\n  contentType?: \"DRAFTJS\";\n}"
+      },
       {
         "name": "listFeedItems",
         "kind": "function",
-        "jsdoc": "/**\n * List a group's activity feed — GET\n * https://social.wix.com/serverless/mobile/feed/v4/feedPosts (the ENRICHED read the\n * real mobile app uses). Each item carries content (Ricos blocks), commentsCount, and\n * reactionsList (count = length); the response's top-level `profiles[]` resolves each\n * item's author.id → userName + profileImage. Verified live (200). Replaces the lean\n * GET /api/v1/feed/items read, which omitted counts + author.\n *\n * @scope member — verified live with a signed-in member session; visitor/anonymous\n * readability of a public group's feed is unconfirmed.\n */",
-        "decl": "export function listFeedItems(groupId: string, limit = 20, options?: WixCallOptions): Promise<WixListFeedItemsResponse>;",
+        "jsdoc": "/**\n * List one group's activity feed. Mirrors wix-one-app-feed getFeedPosts:\n * containerId + Groups appDefId + feedType=all + contentType=DRAFTJS, with optional\n * topic and opaque paging cursor. Existing site/cache options remain per-call.\n * Reactions lists must not be treated as authoritative totals.\n *\n * @scope member — verified live with a signed-in member session; visitor readability\n * depends on group permissions and is not established by the central-feed probe.\n */",
+        "decl": "export function listFeedItems(groupId: string, limit = 20, options?: WixGroupFeedOptions): Promise<WixListFeedItemsResponse>;",
         "scope": "member"
       },
+      {
+        "name": "listCentralFeedItems",
+        "kind": "function",
+        "jsdoc": "/**\n * List the site's combined feed, rather than substituting a selected group's feed.\n * Mirrors wix-one-app-feed getCentralFeedPosts: there is no containerId or appDefId.\n * Authentication and business selection belong to the bridge (or per-call `site`).\n *\n * Source: wix-one-app-feed@6ef53170e94e27349d2a6c1cf08038b078d86228,\n * src/services/feed-api.ts. A real Visitor read returned 200 with posts and a cursor.\n * That establishes the server contract only: native consumers need a core release with the exact read-route guard, and\n * production web still refuses social.wix.com. This SDK method does\n * not change those policies or establish membership/write permission. Consumers must\n * surface a transport refusal; they must not substitute a group directory or empty feed.\n */",
+        "decl": "export function listCentralFeedItems(limit = 20, options?: WixCentralFeedOptions): Promise<WixListFeedItemsResponse>;"
+      },
       {
         "name": "createFeedItem",
         "kind": "function",

package/guides/webview-page-sdk.md

@@ -94,7 +94,28 @@ every message none of them claims, including a handler registered directly on
 `himalaya.webview.onPageMessage` after `@himalaya/webview` loaded).
 
 ```ts
-import { emitToPage, onPageLifecycle, onPageRequest, openPageStream } from "@himalaya/webview";
+import { defineService } from "@himalaya/state";
+import { emitToPage, onPageLifecycle, onPageRequest, openPageStream, type PageStream } from "@himalaya/webview";
+
+// The worker has NO setTimeout / setInterval on any renderer. A stream that produces over time
+// is paced by the host clock: an action returns a `_poll`, and each tick sends the next chunk.
+const watching = new Set<PageStream>();
+let armed = false; // re-arming a live id with `immediate` fires an extra tick at once — arm once
+const steps = defineService("steps", {
+  state: {},
+  actions: {
+    arm: (s) => ({ ...s, _poll: { id: "steps", intervalMs: 1000, action: "steps.tick", immediate: true } }),
+    tick: (s) => {
+      for (const stream of watching) {
+        if (stream.closed) watching.delete(stream); // ended, or the page broke out of its loop
+        else stream.next({ steps: Math.random() });
+      }
+      if (watching.size) return s;
+      armed = false;
+      return { ...s, _poll: { id: "steps", stop: true } };
+    },
+  },
+});
 
 onPageRequest("nano", {
   // (args, ctx) → value | promise. ctx = { instanceId, requestId, active }.
@@ -102,8 +123,8 @@ onPageRequest("nano", {
   // Return a stream handle to answer with many chunks.
   "steps.watch": (_args, ctx) => {
     const stream = openPageStream(ctx.instanceId, ctx.requestId);
-    const timer = setInterval(() => stream.next({ steps: Math.random() }), 1000);
-    stream.onCancel(() => clearInterval(timer)); // the page broke out of its loop
+    watching.add(stream);
+    if (!armed) { armed = true; void steps.arm(); }
     return stream;
   },
 });
@@ -112,6 +133,9 @@ emitToPage("*", "nano.theme.changed", { dark: true }); // or one instance id
 const off = onPageLifecycle(({ instanceId, state }) => console.log(instanceId, state)); // mounted … unmounted
 ```
 
+A timer in a worker is not a style choice: `setInterval` here throws `Can't find variable` on the
+device, and the page sees the request fail (`_poll`: [Tier-5 guide](tier-5-add-a-screen.md#refresh-on-a-cadence-with-_poll-the-worker-has-no-clock)).
+
 - `ctx.instanceId` is the WebView the **host** says the request came from; a page-sent `iid` is
   ignored. `ctx.active` is live: `false` between `inactive` and `active` lifecycle events.
 - A namespace — and an exposed capability id — follows the capability-id pattern
@@ -255,3 +279,44 @@ The page is served at `/web/webview-sdk.html`. Its companion worker is
 probes. Safe probes run on load.
 Verbs that prompt, write, or open system UI stay allowlisted and are not called. Streaming
 helpers that return a live object stay on the worker.
+
+## Embedding worker-bridged WebViews
+
+A Tier-5 SDUI screen embeds any number of `WebView` nodes that talk to the **owning screen's
+worker** over the same channel: set `bridge: "worker"` on the node, declare `"webview"`
+in the screen's `logic_bundle`, and give each widget an explicit `instance_id` (inside a
+`LazyList`/`Carousel` item template it must be item-derived, e.g. `"row-$item.id"`). Untrusted or
+LLM-generated inline HTML additionally wants `origin_isolation: "per_instance"` (its own origin +
+storage per widget), `frame_policy: "content"` (top frame pinned, bridge main-frame-only),
+`bridge_security: { profile: "app_content" }` (multi-line-friendly caps) and `console_forwarding`.
+The host injects the page client at document start, so the page imports nothing; an app alias
+(`inject_js_document_start: "window.demoSdk = himalaya.demo;"`) runs after it, and the platform
+knows no app names. On web (phase 1), only an app-controlled **cross-origin `url`** page listed in
+`allowed_origins` is bridged; an inline (`srcdoc`) widget stays unbridged and the worker hears
+`mounted` with `detail: { bridged: false, reason: "web_srcdoc_unbridged" }` — show a fallback.
+
+A complete shape to copy — the demo app's **Embedded widgets** screen (`demo_app_embedded_widgets`)
+is built exactly this way:
+
+- three isolated inline widgets in a `Carousel` with `live_window: 1`, so only the current widget
+  and its neighbours are mounted (swiping to widget 3 unmounts widget 1), plus one bridged
+  cross-origin `url` page — all served by **one** worker;
+- the worker answers `onPageRequest("demo", { echo, bump, stream })`: a request, a per-instance
+  counter that answers with `emitToPage(ctx.instanceId, "demo.tick", n)`, and a 5-chunk stream the
+  page can stop (`break` out of its loop), paced by a host `_poll` as above;
+- `muted_path`, `active_path` and one widget's `reload_key_path` bound to worker state, and an
+  `onPageLifecycle` handler that shows each widget's last state;
+- each widget keeps its own `localStorage` counter, which survives a relaunch and is never visible
+  to its neighbours.
+
+Test such a screen by the document, not only by lifecycle envelopes: put state in a widget's page
+(an echo reply), swipe away and back, and check the state survived where the widget should have
+stayed mounted. **Crash recovery:** when a widget's content process dies, the host sends `crashed`
+and then remounts it (`reloaded`). On iOS and macOS each widget has its own content process, so the
+page exhausting memory (the demo's "Crash widget 3" does) kills only that widget; killing the
+`com.apple.WebKit.WebContent` process serving it by hand on a simulator triggers the same two
+envelopes. **On Android, don't use a memory hog:** one renderer process serves every WebView of the
+app — the screen's own worker included — so the hog takes them all down, and repeated renderer
+crashes exhaust the worker's recovery budget. Trigger it by hand instead: kill the app's sandboxed
+WebView process (`adb shell ps -A | grep sandboxed_process`, then `adb shell kill <pid>`) and watch
+for `crashed` then `reloaded`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1571.0",
+  "version": "0.1573.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": "fec01235dfeb9ac45a855684328263dcff0fa8e5ecf05db7d6e9b9da"
+  "falconPackageHash": "39a44e1a057f7d34899d550863397025bfdec7b4f241a6e45b677246"
 }

package/templates/beauty-salon/tier5-src/_shared/iap-worker.ts

@@ -4,6 +4,7 @@
 // SDK; this only supplies the copy and the hydration reset.
 import { hostSessionFromGlobal, type IapPriceCopy } from "@himalaya/iap";
 import type { IapCommerce, IapPurchaseCopy, IapRestoreResult } from "@himalaya/iap-checkout";
+import { paymentSetupMessage } from "./payment-setup.js";
 import { copyParam, copyTemplate } from "./himi-copy.js";
 
 /** Price labels from the screen's copy pack (`<prefix>.priceLoadingText`, …). */
@@ -25,6 +26,7 @@ export function iapPurchaseCopy(prefix: string): IapPurchaseCopy {
     awaitingApproval: copyParam(`${prefix}.purchaseAwaitingApprovalText`, "Waiting for approval"),
     unavailable: copyParam(`${prefix}.purchaseTemporarilyUnavailableText`, "Purchasing is temporarily unavailable."),
     signInRequired: copyParam(`${prefix}.purchaseSignInText`, "Sign in to buy."),
+    sitePaymentUnavailable: paymentSetupMessage(prefix),
     retry: copyParam(`${prefix}.purchaseRetryText`, "Something went wrong. Try again."),
     priceChanged: copyParam(`${prefix}.purchasePriceChangedText`, "The price changed. Check it and try again."),
     support: copyParam(`${prefix}.purchaseSupportText`, "We couldn't finish this purchase. Contact support."),

package/templates/beauty-salon/tier5-src/_shared/payment-setup.ts

@@ -0,0 +1,6 @@
+import { copyParam } from "./himi-copy.js";
+
+/** No provider or country guess: Wix only established that online payment is unavailable. */
+export function paymentSetupMessage(prefix: string): string {
+  return copyParam(`${prefix}.paymentSetupUnavailable`, "This site is not accepting online payments. Go back or contact the business for other payment options.");
+}