@wix/himalaya-cli 0.981.0 → 0.982.0

package/guides/headless-loop.md

@@ -246,24 +246,39 @@ errors** — a compile failure, a failed-to-build screen, a missing bundle, an e
 descriptor issue, or a worker that throws on boot. Fix them, or pass `--force`. Warnings never block.
 
 The push JSON includes:
-- `previewWeb` — live SPA eyes (`/preview/a/<app>?release=`)
-- `context` — agent brain (`/v1/preview/a/<app>?release=`) — one-shot ok/issues/screens/links
+- `previewWeb` — live SPA eyes. On a plane with a shared store (prod/bo) this is a one-hop
+  HANDOVER link — `/preview/a/<app>?h=<code>` — an opaque, single-use code with **no credential
+  in it at all**: the plane holds the browser-preview token behind `sha256(code)` and delivers it
+  into the preview document the first time the link is opened. Only where there is no shared
+  store (the local dev loop) does it fall back to the old shape,
+  `/preview/a/<app>?release=<id>&pvt=<token>`, with the token riding the query string.
+- `context` — agent brain (`/v1/preview/a/<app>?release=`) — one-shot ok/issues/screens/links.
+  This one always carries `?release=` and no bearer: it authenticates over a header, not a link
+  handed to a person, so it never had a credential in the URL to remove.
 - `screensUrl` / `deeplinksUrl` — catalog + nav map
 - `next` — suggested `himi context` / `himi screens` follow-ups
 
-The browser-preview token embedded in `previewWeb` is scoped to this app + draft release and
-expires after **45 minutes**. The JSON also includes `previewTokenExpiresAt` — read that rather
-than this number when you are talking to a plane you did not start. If review takes longer, run
-`himi preview --app my-app --release <id> --target wix`: it renews the browser token without
-promoting the draft. For header-only function calls against the same draft, pass the separately
-issued short-lived function token as `--preview-token <token>`.
-
-**When you hand `previewWeb` to a person, the expiry is theirs, not yours.** Renewing it needs
-this CLI and your credentials, so a link handed over near the end of a session leaves the
-recipient with a deadline and no way to extend it. Re-mint immediately before handing it over
-rather than passing on a link minted earlier, and say the expiry in their timezone. If they sign
-in to the Wix account that owns the app, its own owner page previews it for them
-without this CLI and without you — that, not the link, is the durable way back in.
+The browser-preview token behind `previewWeb` is scoped to this app + draft release and expires
+after **45 minutes** — the handover changes how the token TRAVELS, not how long it lives. What is
+new is that the LINK is single-use regardless of the token's own remaining life: opening it once
+redeems it, and that same browser tab can still reload (it re-reads what the page stashed on
+first load) — but a different tab, a different browser, or anyone the link was forwarded to gets
+a plain refusal, not the draft. The JSON also includes `previewTokenExpiresAt` — read that rather
+than the 45-minute figure when you are talking to a plane you did not start. If review takes
+longer, run `himi preview --app my-app --release <id> --target wix`: it mints a FRESH handover
+(or renews the token directly, on a plane with no store) without promoting the draft. For
+header-only function calls against the same draft, pass the separately issued short-lived
+function token as `--preview-token <token>`.
+
+**When you hand `previewWeb` to a person, both the expiry and the single use are theirs, not
+yours.** Renewing it needs this CLI and your credentials, so a link handed over near the end of a
+session leaves the recipient with a deadline and no way to extend it — and because a handover
+code is spent on first open, re-sending the exact same link after someone has already opened it
+once (even if their tab crashed) hands them a link that no longer works; mint again instead of
+resending. Re-mint immediately before handing it over rather than passing on a link minted
+earlier, and say the expiry in their timezone. If they sign in to the Wix account that owns the
+app, its own owner page previews it for them without this CLI and without you — that, not the
+link, is the durable way back in.
 
 ## 5b. Agent preview (machine-readable, no browser scrape)
 

package/guides/sdk-reference.json

@@ -2489,6 +2489,18 @@
         "kind": "const",
         "jsdoc": "/** Capability version, for bundles that gate on min binary version. */",
         "decl": "export const version = 1;"
+      },
+      {
+        "name": "NotificationEvent",
+        "kind": "interface",
+        "jsdoc": "/** One notification, as a worker sees it. Every field is always present; an\n *  absent one reads as `\"\"` rather than `undefined`, so a `$service:` binding at\n *  a field this payload omitted renders nothing instead of the text \"undefined\". */",
+        "decl": "export interface NotificationEvent {\n  /** Ping template that produced it, e.g. \"stores.order_shipped\". */\n  templateId: string;\n  /** Ping topic, e.g. \"stores\". */\n  topic: string;\n  /** The site the payload named, when it named one. */\n  metaSiteId: string;\n  /** Stable per-notification id — the key to deduplicate on. */\n  notificationId: string;\n  /** The link exactly as delivered, before any route translation. */\n  link: string;\n  /** What the route table translated `link` into, or `\"\"` when no route\n   *  matched. Empty is NOT an error: the notification still arrived, and a\n   *  worker may want to count one it cannot open. */\n  resolvedLink: string;\n  /** True only when the user TAPPED. A foreground receipt is `false` and must\n   *  not be treated as intent to navigate. */\n  tapped: boolean;\n}"
+      },
+      {
+        "name": "readNotificationEvent",
+        "kind": "function",
+        "jsdoc": "/**\n * Read the params a dispatched `observerAction` receives.\n *\n * Runs on the untrusted edge of the bridge, so it never throws whatever arrives.\n * `tapped` needs this reader more than the rest: the bridge stringifies every\n * param, so a worker testing `params.tapped` truthily would read the string\n * `\"false\"` as a tap.\n */",
+        "decl": "export function readNotificationEvent(params: unknown): NotificationEvent;"
       }
     ]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.981.0",
+  "version": "0.982.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": [
@@ -64,5 +64,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "8c6c57df555495fb76153e6101f19971862f487629e302e57aa4fdc0"
+  "falconPackageHash": "2148a718160adaaf2dd1bf36a397e2015e080ba32885973148deee70"
 }