@8ux-co/eelzap 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -5,7 +5,69 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.10.0] - Unreleased
+## [0.10.1] - Unreleased
+
+### Added
+
+- The site client's on-page read returns the viewer's own `email` and an `editorUrl` for the record the page resolves to («Abrir en Zap»), plus `records` naming the other records the page shows.
+- **`webhookChanges` covers SEO, collection, schema and site events**, so a
+  site that revalidates on webhooks also refreshes when they change:
+  - `zap.seo.updated` gives the same `item` or `document` change an edit
+    does (action `updated`), one per entry or document;
+  - `zap.collection.created`, `updated` and `deleted` give a `collection`
+    change carrying `collectionKey`;
+  - `zap.schema.field_changed` (action `field_changed`) gives one
+    `collection` change per collection whose fields changed, with
+    `resourceKey` and `collectionKey` set to the collection's key, and one
+    `document` change per document whose fields changed, named by the
+    document's key. Zap now sends `collection_key` and `document_key` on
+    every schema change. An older payload without them names a collection
+    by its id (no `collectionKey`) and widens a document's fields to one
+    `site` change;
+  - `zap.site.updated` gives a `site` change.
+- `WebhookEventType` adds `'collection'` and `'site'`, and `WebhookAction`
+  adds `'field_changed'`. The item, document and media changes keep their
+  shape.
+- Typed `data` for these events: `WebhookSeoEventData`,
+  `WebhookCollectionEventData`, `WebhookSchemaEventData` (with optional
+  `collection_key` and `document_key`) and `WebhookSiteEventData`.
+
+### Changed
+
+- **`canonicalUrl` takes a path or a full URL** (`SeoInput`, docs only; the
+  type is still `string | null`). A path such as `/blog/original-post` is
+  stored as sent and resolved against the site URL on delivery, so it
+  follows a change of address; a full https URL (http only on localhost) is
+  kept as sent, for content first published on another domain. Leave it
+  unset and delivery uses the record's own URL. Zap refuses `//host`,
+  `javascript:` and other schemes, whitespace and credentials with a 400
+  whose `details[].message` says why.
+- `Seo.canonicalUrl` on delivery is always an absolute URL or null, as
+  before; a stored path arrives resolved. `VersionSeo.canonicalUrl` and the
+  SEO routes return the value as stored.
+- The canonical is an SEO field only: it no longer changes the page Zap's
+  preview opens. Where a record lives is its preview path.
+- **A document without a preview path is site-wide** (a header and footer
+  document, say): `Seo.canonicalUrl` and `ogUrl` are null for it unless an
+  editor set a canonical, instead of `/{documentKey}`. A document that is a
+  page keeps its preview path's URL.
+- **Zap keeps every version.** The per-site version limit is gone, so
+  `WebhookSiteEventData.changed` on `zap.site.updated` never lists
+  `maxVersionsPerEntry`, and `itemVersions.list()` and `documentVersions.list()`
+  return the whole history. No SDK type carried the setting, so no code changes.
+
+### Fixed
+
+- `webhookChanges` returns an empty list for `zap.item.draft_updated` and
+  `zap.document.draft_updated`: saving a draft changes nothing the live site
+  serves.
+- **The preview client pauses instead of running away.** When the tagged
+  count passes 5,000, or grows on three passes in a row that nothing on the
+  page explains, the client stops observing the page and writing values,
+  logs one warning and tells Zap's editor (`zap:paused`), which offers a
+  reload. Values carrying stega markers no longer add markers on each pass.
+
+## [0.10.0] - 2026-10-06
 
 The first release as **`@8ux-co/eelzap`**, which replaces
 `@8ux-co/eelzap-api-sdk-ts` (its last release, 0.9.1, points here). One

package/README.md

@@ -761,20 +761,77 @@ never include comment text. Their types are `WebhookCommentCreatedData`,
 
 ### Cache invalidation
 
-`webhookChanges(payload)` flattens an item, document or media event into one
-`WebhookChange` per entry — `{ type, action, id, resourceKey, collectionKey?,
-siteKey }`, where `resourceKey` is the item's slug, the document's key or the
-file's id. Any other event gives an empty list.
+`webhookChanges(payload)` flattens an event into the changes a site
+revalidates by, `{ type, action, id, resourceKey, collectionKey?, siteKey }`:
+
+| `type`       | From                                                                    | `resourceKey`        | `collectionKey` |
+| ------------ | ----------------------------------------------------------------------- | -------------------- | --------------- |
+| `item`       | `zap.item.*`, and `zap.seo.updated` on entries (action `updated`)       | the entry's slug     | its collection  |
+| `document`   | `zap.document.*`, and `zap.seo.updated` on documents (action `updated`) | the document's key   |                 |
+| `document`   | `zap.schema.field_changed` on a document's fields (`field_changed`)     | the document's key   |                 |
+| `media`      | `zap.media.*`                                                           | the file's id        |                 |
+| `collection` | `zap.collection.*`                                                      | the collection's key | the same key    |
+| `collection` | `zap.schema.field_changed` on a collection's fields (`field_changed`)   | the collection's key | the same key    |
+| `site`       | `zap.site.updated`                                                      | the site's key       |                 |
+
+One event can name several entries, documents or files: each is its own
+change. A `collection` change means everything that shows that collection; a
+`site` change means the whole site. Drafts (`draft_updated`), assignments,
+comments, API keys, `ping`, and sites created or deleted give an empty list.
+
+A `zap.schema.field_changed` sent before the event carried `collection_key`
+and `document_key` names its owners by id only: a collection's fields give a
+`collection` change whose `resourceKey` is the collection's id, with no
+`collectionKey`, and a document's fields give one `site` change.
+
+#### Subscribing a live site
+
+Subscribe the site's webhook, narrowed to the site with `site_ids`, to:
+
+- the `zap.item.*`, `zap.document.*` and `zap.media.*` events, except
+  `zap.item.draft_updated`, `zap.document.draft_updated`, `zap.item.assigned`
+  and `zap.document.assigned`;
+- `zap.collection.created`, `zap.collection.updated` and
+  `zap.collection.deleted`;
+- `zap.seo.updated`, `zap.schema.field_changed` and `zap.site.updated`.
+
+Do not subscribe to `draft_updated` or `assigned`: a saved draft and a new
+Responsable change nothing the site serves, and drafts save often.
+
+#### Revalidating
+
+A Next.js route handler for a site that serves documents at `/<key>` and
+entries at `/<collection>/<slug>`:
 
 ```ts
+// app/api/zap-webhook/route.ts
+import { revalidatePath } from 'next/cache'
 import {
-  MemoryCacheAdapter,
   verifyWebhookSignature,
   webhookChanges,
+  type WebhookChange,
   type WebhookPayload,
 } from '@8ux-co/eelzap'
 
-const cache = new MemoryCacheAdapter()
+function revalidate(change: WebhookChange) {
+  switch (change.type) {
+    case 'item':
+      revalidatePath(`/${change.collectionKey}/${change.resourceKey}`)
+      revalidatePath(`/${change.collectionKey}`) // the listing
+      return
+    case 'document':
+      revalidatePath(`/${change.resourceKey}`)
+      return
+    case 'collection':
+      // An older field change without the key names the collection by id: refresh the whole site.
+      revalidatePath(change.collectionKey ? `/${change.collectionKey}` : '/', 'layout')
+      return
+    case 'media':
+    case 'site':
+      revalidatePath('/', 'layout')
+      return
+  }
+}
 
 export async function POST(request: Request) {
   const payload = await request.text()
@@ -785,13 +842,16 @@ export async function POST(request: Request) {
   }
 
   for (const change of webhookChanges(JSON.parse(payload) as WebhookPayload)) {
-    if (change.type === 'document') cache.delete(change.resourceKey)
-    if (change.type === 'item') cache.delete(`${change.collectionKey}:${change.resourceKey}`)
+    revalidate(change)
   }
   return new Response('ok')
 }
 ```
 
+With `cachedFetch` and a `MemoryCacheAdapter`, do the same with
+`cache.delete(key)` for an item or a document, and `cache.clear()` for a
+`collection`, `media` or `site` change.
+
 `WEBHOOK_SIGNATURE_HEADER`, `WEBHOOK_TIMESTAMP_HEADER` and
 `WEBHOOK_TOLERANCE_SECONDS` export the header names and the default window.
 

package/dist/{chunk-QN53G5P7.js → chunk-6XHCA4U4.js}

@@ -15,6 +15,7 @@ function siteClientId(zapOrigin, siteId) {
 
 // src/preview/site/token.ts
 var EXPIRY_MARGIN_MS = 3e4;
+var REFRESH_LIFETIME_MS = 8 * 60 * 60 * 1e3;
 function store(win) {
   try {
     return win.sessionStorage;
@@ -22,15 +23,26 @@ function store(win) {
     return null;
   }
 }
-function readToken(win, siteId, now = Date.now()) {
+function parse(raw, siteId) {
+  if (!raw) return null;
+  const value = JSON.parse(raw);
+  if (typeof value.token !== "string" || !value.token.startsWith("eel_at_") || typeof value.exp !== "number" || value.site !== siteId) {
+    return null;
+  }
+  const refresh = typeof value.refresh === "string" && value.refresh.startsWith("eel_rt_") && typeof value.rexp === "number" ? { refresh: value.refresh, rexp: value.rexp } : {};
+  return { token: value.token, exp: value.exp, site: value.site, ...refresh };
+}
+function accessLive(value, now = Date.now()) {
+  return value.exp - EXPIRY_MARGIN_MS > now;
+}
+function refreshLive(value, now = Date.now()) {
+  return !!value.refresh && typeof value.rexp === "number" && value.rexp > now;
+}
+function readSession(win, siteId, now = Date.now()) {
   const storage = store(win);
   try {
-    const raw = storage?.getItem(TOKEN_STORAGE_KEY);
-    if (!raw) return null;
-    const value = JSON.parse(raw);
-    if (typeof value.token === "string" && value.token.startsWith("eel_at_") && typeof value.exp === "number" && value.exp - EXPIRY_MARGIN_MS > now && value.site === siteId) {
-      return { token: value.token, exp: value.exp, site: value.site };
-    }
+    const value = parse(storage?.getItem(TOKEN_STORAGE_KEY), siteId);
+    if (value && (accessLive(value, now) || refreshLive(value, now))) return value;
     storage?.removeItem(TOKEN_STORAGE_KEY);
   } catch {
   }
@@ -57,8 +69,12 @@ export {
   STATE_PREFIX,
   PENDING_STORAGE_KEY,
   siteClientId,
-  readToken,
+  EXPIRY_MARGIN_MS,
+  REFRESH_LIFETIME_MS,
+  accessLive,
+  refreshLive,
+  readSession,
   writeToken,
   clearToken
 };
-//# sourceMappingURL=chunk-QN53G5P7.js.map
+//# sourceMappingURL=chunk-6XHCA4U4.js.map

package/dist/chunk-6XHCA4U4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/preview/site/config.ts","../src/preview/site/token.ts"],"sourcesContent":["/**\n * «Editar» and «Comentar» on the customer's site (zap-cms-v2 §3.4, ADR 041):\n * the constants and the context the core hands its two lazy chunks.\n *\n * Three pieces, so an ordinary visitor downloads nothing beyond the core:\n *\n * - the core (`boot.ts`, in the `./preview` budget): the opt-in trigger\n *   (`?zap` in the URL, or Shift Z), the OAuth callback relay on `{origin}/`,\n *   and the loader;\n * - `signin` (loaded only on the trigger): the launcher, «Entrar con Eel», PKCE,\n *   the popup or full-page redirect and the code exchange at Nest;\n * - `suggest` (loaded only after sign-in; the name is the file's, kept): the\n *   toolbar, Navegar, Editar and Comentar, the composer, the numbered pins\n *   and the calls to Zap.\n *\n * No directive, no imports: pure values both chunks and the core share.\n */\n\n/** Nest, the suite's OAuth issuer (ADR 024). Compiled in; `authOrigin` is the dev opt-in. */\nexport const NEST_PRODUCTION_ORIGIN = 'https://auth.eel.software'\n\n/**\n * The scope a site client asks for, by name (ADR 041 §2). `zap:preview:read`\n * is not asked for until a «Ver borradores» feature needs it (Manager,\n * 2026-10-05); Nest would drop it anyway.\n */\nexport const SITE_CLIENT_SCOPE = 'zap:suggest:write'\n\n/** The popup hands the code to the opener tab over this channel (same origin). */\nexport const SIGNIN_CHANNEL = 'eel-zap'\n\n/** Every `state` this client mints starts with it, so a site's own `?code=` is never ours. */\nexport const STATE_PREFIX = 'zap1.'\n\n/** sessionStorage only (ADR 041 §7): the token, and a pending full-page sign-in. */\nexport const TOKEN_STORAGE_KEY = 'eelzap:site-token'\nexport const PENDING_STORAGE_KEY = 'eelzap:signin'\n\nexport type ChunkName = 'signin' | 'suggest'\n\n/** What a callback page carries back from Nest (`{origin}/?code&state&iss`). */\nexport interface CallbackParams {\n  code: string\n  state: string\n  iss: string\n}\n\nexport interface StartOptions {\n  /**\n   * signin: open the panel at once, and why (`expired` after a 401 or the\n   * hour). suggest: `renewed` after a sign-in that followed an expiry, which\n   * says «Sesión renovada» (board SitioRenovacion).\n   */\n  reason?: 'expired' | 'trigger' | 'renewed'\n  /** signin: finish a full-page sign-in that landed on this page. */\n  callback?: CallbackParams\n  /**\n   * signin: start signing in at once, as if «Entrar con Eel» was pressed.\n   * Passed by «Volver a entrar» (the bar's expired state), inside its click, so\n   * the popup is still allowed.\n   */\n  signIn?: boolean\n}\n\nexport interface ChunkHandle {\n  destroy(): void\n}\n\nexport interface ChunkModule {\n  start(ctx: SiteContext, options?: StartOptions): ChunkHandle\n}\n\n/** Everything a chunk needs, decided once by the core. */\nexport interface SiteContext {\n  win: Window\n  doc: Document\n  /** The Zap site's id (`data-site-id`); names its OAuth client. */\n  siteId: string\n  /** Where Zap's API and the client's CIMD document live. */\n  zapOrigin: string\n  /** Nest, the issuer: `/oauth/authorize`, `/api/oauth/token`, and the `iss` to expect. */\n  authOrigin: string\n  /** `{zapOrigin}/oauth/clients/{siteId}.json` (ADR 041 §1). */\n  clientId: string\n  /** `{page origin}/`, exactly as the CIMD document lists it. */\n  redirectUri: string\n  locale: 'es' | 'en'\n  /** The letter pressed with Shift to open the tools, for the launcher's hint; false when off. */\n  shortcut: string | false\n  /**\n   * The site's draft-mode route (`/api/zap-preview` by default), as the page\n   * announced it: «Editar» enters draft mode through it on an untagged page\n   * (`draft-session.ts`). Null or absent when the site has none.\n   */\n  draftRoute?: string | null\n  /** Replace whatever chunk is showing with `name`. */\n  open(name: ChunkName, options?: StartOptions): Promise<void>\n  /** Close the showing chunk; the trigger works again. */\n  close(): void\n}\n\n/** The client id of one site, the same string `@eel/api-keys` `zapSiteClientId` builds. */\nexport function siteClientId(zapOrigin: string, siteId: string): string {\n  return `${zapOrigin}/oauth/clients/${siteId.toLowerCase()}.json`\n}\n","import { TOKEN_STORAGE_KEY } from './config'\n\n/**\n * The site client's tokens (ADR 041 §7): in memory and in `sessionStorage`,\n * never in `localStorage` or a cookie. The access token lives one hour. Since\n * ADR 041's amendment of 2026-10-06 it comes with a short refresh token (eight\n * hours, rotating, redeemable only inside the person's remembered consent and\n * from this origin), which `session.ts` spends to renew the hour without a\n * sign-in; when that fails the person signs in again.\n *\n * Stored with the expiries and the site it was issued for: a token for another\n * site, a malformed entry, or one whose access AND refresh are both spent reads\n * as nothing and is removed.\n */\n\nexport interface SiteToken {\n  /** The `eel_at_` access token. */\n  token: string\n  /** Epoch ms when it stops working. */\n  exp: number\n  /** The site it was issued for. */\n  site: string\n  /** The `eel_rt_` refresh token, when Nest issued one. */\n  refresh?: string\n  /** Epoch ms after which the refresh token is not worth trying. */\n  rexp?: number\n}\n\n/** How long before the real expiry we stop using a token, so a call never races it. */\nexport const EXPIRY_MARGIN_MS = 30_000\n\n/** A refresh token lives eight hours at Nest (ADR 041 amendment 2026-10-06). */\nexport const REFRESH_LIFETIME_MS = 8 * 60 * 60 * 1000\n\nfunction store(win: Window): Storage | null {\n  try {\n    return win.sessionStorage\n  } catch {\n    return null\n  }\n}\n\nfunction parse(raw: string | null | undefined, siteId: string): SiteToken | null {\n  if (!raw) return null\n  const value = JSON.parse(raw) as Partial<SiteToken>\n  if (\n    typeof value.token !== 'string' ||\n    !value.token.startsWith('eel_at_') ||\n    typeof value.exp !== 'number' ||\n    value.site !== siteId\n  ) {\n    return null\n  }\n  const refresh =\n    typeof value.refresh === 'string' &&\n    value.refresh.startsWith('eel_rt_') &&\n    typeof value.rexp === 'number'\n      ? { refresh: value.refresh, rexp: value.rexp }\n      : {}\n  return { token: value.token, exp: value.exp, site: value.site, ...refresh }\n}\n\n/** True while the access token is still worth sending. */\nexport function accessLive(value: SiteToken, now = Date.now()): boolean {\n  return value.exp - EXPIRY_MARGIN_MS > now\n}\n\n/** True while the refresh token is still worth trying. */\nexport function refreshLive(value: SiteToken, now = Date.now()): boolean {\n  return !!value.refresh && typeof value.rexp === 'number' && value.rexp > now\n}\n\n/**\n * The stored session while it can still act: a live access token, or a\n * refresh token that may renew it (`session.ts` does). Anything else is\n * removed and reads as null.\n */\nexport function readSession(win: Window, siteId: string, now = Date.now()): SiteToken | null {\n  const storage = store(win)\n  try {\n    const value = parse(storage?.getItem(TOKEN_STORAGE_KEY), siteId)\n    if (value && (accessLive(value, now) || refreshLive(value, now))) return value\n    storage?.removeItem(TOKEN_STORAGE_KEY)\n  } catch {\n    // Unreadable entry or blocked storage: no token.\n  }\n  return null\n}\n\n/** The stored session only while its ACCESS token is live (no renewal needed). */\nexport function readToken(win: Window, siteId: string, now = Date.now()): SiteToken | null {\n  const value = readSession(win, siteId, now)\n  return value && accessLive(value, now) ? value : null\n}\n\nexport function writeToken(win: Window, value: SiteToken): void {\n  try {\n    store(win)?.setItem(TOKEN_STORAGE_KEY, JSON.stringify(value))\n  } catch {\n    // Blocked storage: the token lives in memory for this page only.\n  }\n}\n\nexport function clearToken(win: Window): void {\n  try {\n    store(win)?.removeItem(TOKEN_STORAGE_KEY)\n  } catch {\n    // Nothing to clear.\n  }\n}\n"],"mappings":";;;;;AAmBO,IAAM,yBAAyB;AAO/B,IAAM,oBAAoB;AAG1B,IAAM,iBAAiB;AAGvB,IAAM,eAAe;AAGrB,IAAM,oBAAoB;AAC1B,IAAM,sBAAsB;AAkE5B,SAAS,aAAa,WAAmB,QAAwB;AACtE,SAAO,GAAG,SAAS,kBAAkB,OAAO,YAAY,CAAC;AAC3D;;;AC3EO,IAAM,mBAAmB;AAGzB,IAAM,sBAAsB,IAAI,KAAK,KAAK;AAEjD,SAAS,MAAM,KAA6B;AAC1C,MAAI;AACF,WAAO,IAAI;AAAA,EACb,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,MAAM,KAAgC,QAAkC;AAC/E,MAAI,CAAC,IAAK,QAAO;AACjB,QAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,MACE,OAAO,MAAM,UAAU,YACvB,CAAC,MAAM,MAAM,WAAW,SAAS,KACjC,OAAO,MAAM,QAAQ,YACrB,MAAM,SAAS,QACf;AACA,WAAO;AAAA,EACT;AACA,QAAM,UACJ,OAAO,MAAM,YAAY,YACzB,MAAM,QAAQ,WAAW,SAAS,KAClC,OAAO,MAAM,SAAS,WAClB,EAAE,SAAS,MAAM,SAAS,MAAM,MAAM,KAAK,IAC3C,CAAC;AACP,SAAO,EAAE,OAAO,MAAM,OAAO,KAAK,MAAM,KAAK,MAAM,MAAM,MAAM,GAAG,QAAQ;AAC5E;AAGO,SAAS,WAAW,OAAkB,MAAM,KAAK,IAAI,GAAY;AACtE,SAAO,MAAM,MAAM,mBAAmB;AACxC;AAGO,SAAS,YAAY,OAAkB,MAAM,KAAK,IAAI,GAAY;AACvE,SAAO,CAAC,CAAC,MAAM,WAAW,OAAO,MAAM,SAAS,YAAY,MAAM,OAAO;AAC3E;AAOO,SAAS,YAAY,KAAa,QAAgB,MAAM,KAAK,IAAI,GAAqB;AAC3F,QAAM,UAAU,MAAM,GAAG;AACzB,MAAI;AACF,UAAM,QAAQ,MAAM,SAAS,QAAQ,iBAAiB,GAAG,MAAM;AAC/D,QAAI,UAAU,WAAW,OAAO,GAAG,KAAK,YAAY,OAAO,GAAG,GAAI,QAAO;AACzE,aAAS,WAAW,iBAAiB;AAAA,EACvC,QAAQ;AAAA,EAER;AACA,SAAO;AACT;AAQO,SAAS,WAAW,KAAa,OAAwB;AAC9D,MAAI;AACF,UAAM,GAAG,GAAG,QAAQ,mBAAmB,KAAK,UAAU,KAAK,CAAC;AAAA,EAC9D,QAAQ;AAAA,EAER;AACF;AAEO,SAAS,WAAW,KAAmB;AAC5C,MAAI;AACF,UAAM,GAAG,GAAG,WAAW,iBAAiB;AAAA,EAC1C,QAAQ;AAAA,EAER;AACF;","names":[]}

package/dist/{chunk-VW4EH7NY.js → chunk-7CXQK2PR.js}

@@ -1,6 +1,6 @@
 import {
   __publicField
-} from "./chunk-QN53G5P7.js";
+} from "./chunk-6XHCA4U4.js";
 
 // src/refs.ts
 var FIELD_KEY_RE = /^[a-z][a-z0-9_]{0,127}$/;
@@ -63,7 +63,14 @@ var MAX_TAG_REPORT = 2e3;
 var MAX_LABELS = 500;
 var MAX_PINS = 50;
 var OVERLAY_MODES = ["inspect", "select", "spot", "off"];
-var CAPABILITIES = ["overlay", "values", "stega", "pins", "links"];
+var CAPABILITIES = [
+  "overlay",
+  "values",
+  "stega",
+  "pins",
+  "links",
+  "refresh"
+];
 var MAX_EMAIL_LENGTH = 320;
 function emptyDropStats() {
   return {
@@ -200,12 +207,13 @@ var PAGE_VALIDATORS = {
   "zap:tags": (p) => Array.isArray(p) && p.length <= MAX_TAG_REPORT && p.every(
     (t) => isObject(t) && typeof t.tag === "string" && isRecordRef(t.recordRef) && isFieldKey(t.fieldKey) && t.tag === `${t.recordRef}#${t.fieldKey}` && Number.isInteger(t.count) && t.count > 0 && (t.source === void 0 || t.source === "stega" || t.source === "attr")
   ),
-  "zap:click": isFieldRef,
+  "zap:click": (p) => isFieldRef(p) && (p.rect === void 0 || isObject(p.rect) && isFiniteNumber(p.rect.x, -1e7, 1e7) && isFiniteNumber(p.rect.y, -1e7, 1e7) && isFiniteNumber(p.rect.w, 0, 1e7) && isFiniteNumber(p.rect.h, 0, 1e7)),
   "zap:select": (p) => isObject(p) && isAnchorList(p.anchors, isPageAnchor),
   "zap:navigate": (p) => isObject(p) && isHttpUrl(p.url),
   "zap:error": (p) => isObject(p) && typeof p.code === "string" && ERROR_CODE_RE.test(p.code) && isOptional(p.detail, (d) => isString(d, 500)),
   "zap:spot": (p) => isObject(p) && isSpotPoint(p.spot) && isObject(p.viewport) && isFiniteNumber(p.viewport.w, 1, 1e5) && isFiniteNumber(p.viewport.h, 1, 1e7) && isHttpUrl(p.pageUrl),
-  "zap:pin": (p) => isObject(p) && isPinId(p.id)
+  "zap:pin": (p) => isObject(p) && isPinId(p.id),
+  "zap:paused": (p) => isObject(p) && (p.reason === "runaway" || p.reason === "cap") && Number.isInteger(p.count) && p.count >= 0
 };
 var EDITOR_VALIDATORS = {
   "zap:hello": (p) => {
@@ -214,10 +222,11 @@ var EDITOR_VALIDATORS = {
     if (p.theme !== void 0 && !isTheme(p.theme)) return false;
     if (p.zoom !== void 0 && !isZoom(p.zoom)) return false;
     if (p.previewToken !== void 0 && !isPreviewTokenShape(p.previewToken)) return false;
-    const labels = p.labels;
-    if (!isObject(labels)) return false;
-    const entries = Object.entries(labels);
-    return entries.length <= MAX_LABELS && entries.every(([key, label]) => isFieldKey(key) && isString(label, 200));
+    const within = (map, ok) => isObject(map) && Object.keys(map).length <= MAX_LABELS && Object.entries(map).every(([key, value]) => ok(key, value));
+    return within(p.labels, (key, label) => isFieldKey(key) && isString(label, 200)) && within(
+      p.foreign ?? {},
+      (tag, pair) => !!parseTag(tag) && Array.isArray(pair) && pair.length === 2 && pair.every((part) => isString(part, 200))
+    );
   },
   "zap:values": (p) => {
     if (!isObject(p) || !isRecordRef(p.recordRef) || !isLocale(p.locale)) return false;
@@ -228,6 +237,7 @@ var EDITOR_VALIDATORS = {
   "zap:focus-field": isFieldRef,
   "zap:mode": isMode,
   "zap:zoom": (p) => isObject(p) && isZoom(p.zoom),
+  "zap:refresh": isObject,
   "zap:highlight": (p) => isObject(p) && isAnchorList(p.anchors, isDomAnchor),
   "zap:pins": (p) => isObject(p) && Array.isArray(p.pins) && p.pins.length <= MAX_PINS && p.pins.every(isPin)
 };
@@ -272,6 +282,53 @@ function envelope(type, session, payload) {
   return { source: PROTOCOL_SOURCE, v: PROTOCOL_VERSION, session, type, payload };
 }
 
+// src/stega.ts
+var DIGITS = ["\u200B", "\u200C", "\u200D", "\u2060"];
+var PREFIX = "\u2060\u200D\u200C\u200C\u200D\u200D\u200C\u2060";
+var PAYLOAD_RE = /^(doc:[a-z0-9]+(?:-[a-z0-9]+)*|[a-z0-9]+(?:-[a-z0-9]+)*\/[a-z0-9]+(?:-[a-z0-9]+)*)#([a-z][a-z0-9_]{0,127})(?:@([A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}))?$/;
+var MARKER_RE = /⁠‍‌‌‍‍‌⁠(?:[​‌][​‌‍⁠]{3})*/g;
+function hasStega(value) {
+  return typeof value === "string" && value.includes(PREFIX);
+}
+function stegaDecode(text) {
+  if (!text.includes(PREFIX)) return [];
+  const found = [];
+  for (const match of text.match(MARKER_RE) ?? []) {
+    let payload = "";
+    for (let i = PREFIX.length; i + 4 <= match.length; i += 4) {
+      let byte = 0;
+      for (let j = 0; j < 4; j++) byte = byte * 4 + DIGITS.indexOf(match[i + j]);
+      payload += String.fromCharCode(byte);
+    }
+    const parsed = PAYLOAD_RE.exec(payload);
+    if (!parsed) continue;
+    found.push({
+      recordRef: parsed[1],
+      fieldKey: parsed[2],
+      locale: parsed[3] ?? null,
+      tag: `${parsed[1]}#${parsed[2]}`
+    });
+  }
+  return found;
+}
+function splitStega(text) {
+  if (!text.includes(PREFIX)) return { text, markers: "" };
+  return { text: text.replace(MARKER_RE, ""), markers: (text.match(MARKER_RE) ?? []).join("") };
+}
+function cleanString(text) {
+  return text.includes(PREFIX) ? text.replace(MARKER_RE, "") : text;
+}
+function cleanStega(value) {
+  if (typeof value === "string") return cleanString(value);
+  if (Array.isArray(value)) return value.map((item) => cleanStega(item));
+  if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) out[key] = cleanStega(item);
+    return out;
+  }
+  return value;
+}
+
 // src/preview/anchor.ts
 function cssEscape(value) {
   const native = globalThis.CSS?.escape;
@@ -352,7 +409,7 @@ function fit(selector) {
   return utf8Length(selector) <= MAX_SELECTOR_BYTES ? selector : null;
 }
 function normalizeText(value) {
-  return value.replace(/\s+/g, " ").trim();
+  return cleanStega(value).replace(/\s+/g, " ").trim();
 }
 function textQuoteFor(element, doc) {
   const exact = normalizeText(element.textContent ?? "").slice(0, MAX_QUOTE_EXACT);
@@ -480,6 +537,7 @@ var Overlay = class {
     __publicField(this, "zoom", 1);
     __publicField(this, "theme", { ...DEFAULT_THEME });
     __publicField(this, "labels", {});
+    __publicField(this, "foreign", {});
     __publicField(this, "hover", null);
     __publicField(this, "focused", []);
     __publicField(this, "highlighted", []);
@@ -538,6 +596,7 @@ var Overlay = class {
       if (!event.relatedTarget) this.setHover(null);
     });
     this.listen(win, "click", (event) => this.onClick(event));
+    this.listen(win, "submit", (event) => this.mode !== "off" && this.consume(event));
     this.listen(win, "keydown", (event) => this.onKey(event));
     this.listen(win, "scroll", () => this.schedule());
     this.listen(win, "resize", () => this.schedule());
@@ -584,17 +643,17 @@ var Overlay = class {
     this.theme = { ...DEFAULT_THEME, ...theme ?? {} };
     this.schedule();
   }
-  setLabels(labels) {
+  /** Labels by field key; `foreign`, by full tag, the fields of other records (`HelloPayload.foreign`). */
+  setLabels(labels, foreign = {}) {
     this.labels = { ...labels };
+    this.foreign = { ...foreign };
     this.schedule();
   }
   /** Outline every element of a field and scroll the first into view. */
   focusField(elements) {
     this.focused = elements.slice();
     const first = elements[0];
-    if (first && typeof first.scrollIntoView === "function") {
-      first.scrollIntoView({ block: "center", behavior: "smooth" });
-    }
+    if (first) reveal(this.options.win, first);
     this.schedule();
     return elements.length;
   }
@@ -602,9 +661,7 @@ var Overlay = class {
   highlight(elements) {
     this.highlighted = elements.slice(0, MAX_ANCHORS);
     const first = this.highlighted[0];
-    if (first && typeof first.scrollIntoView === "function") {
-      first.scrollIntoView({ block: "center", behavior: "smooth" });
-    }
+    if (first) reveal(this.options.win, first);
     this.schedule();
   }
   /** Draw these pins (≤ 50); drops the pending spot pin. */
@@ -672,6 +729,7 @@ var Overlay = class {
   }
   onClick(event) {
     if (this.mode === "off" || this.isOwn(event.target)) return;
+    if (event.target.closest?.("a[href],area[href]")) this.consume(event);
     if (this.mode === "spot") {
       this.consume(event);
       return this.spotAt(event);
@@ -758,7 +816,8 @@ var Overlay = class {
       if (seen.has(element) || !element.isConnected) return;
       seen.add(element);
       const tagged = this.options.index.get(element);
-      boxes.push({ element, kind, label: tagged ? this.labelFor(tagged) : null });
+      const [label, suffix] = tagged ? this.labelFor(tagged) : [null];
+      boxes.push({ element, kind, label, suffix });
     };
     if (this.mode !== "off") {
       for (const element of this.selected) add(element, "selected");
@@ -788,6 +847,12 @@ var Overlay = class {
       }
     }
     layer.replaceChildren(...nodes);
+    const inset = EDGE_PX / this.zoom;
+    for (const chip of layer.querySelectorAll(".chip")) {
+      const { left, right } = chip.getBoundingClientRect();
+      const dx = Math.min(Math.max(0, inset - left), this.options.win.innerWidth - inset - right);
+      chip.style.transform = `translateX(${dx}px)`;
+    }
   }
   /** A gold teardrop whose point (bottom-left) sits on `[x, y]`; without a pin, the pending one. */
   drawPin([x, y], pin) {
@@ -795,9 +860,12 @@ var Overlay = class {
     node.className = "pin";
     const z = this.zoom;
     const size = PIN_PX / z;
+    const vw = this.options.win.innerWidth;
+    const below = y >= 0 && y - size < EDGE_PX / z;
+    if (below) node.style.borderRadius = "0 999px 999px";
     Object.assign(node.style, {
-      left: `${x}px`,
-      top: `${y - size}px`,
+      left: `${x <= vw ? Math.min(x, vw - size - EDGE_PX / z) : x}px`,
+      top: `${below ? y : y - size}px`,
       width: `${size}px`,
       height: `${size}px`,
       fontSize: `${11 / z}px`,
@@ -814,8 +882,8 @@ var Overlay = class {
     return node;
   }
   labelFor(tagged) {
-    const label = this.labels[tagged.fieldKey];
-    return typeof label === "string" && label.trim() ? label : tagged.fieldKey;
+    const [label, suffix] = this.foreign[tagged.tag] ?? [this.labels[tagged.fieldKey]];
+    return [typeof label === "string" && label.trim() ? label : tagged.fieldKey, suffix];
   }
   drawBox(box) {
     const doc = this.options.doc;
@@ -839,9 +907,11 @@ var Overlay = class {
     if (box.label && box.kind !== "highlight" && !tooSmall) {
       const chip = doc.createElement("span");
       chip.className = "chip";
+      const lift = 27 / z;
+      const above = rect.top - offset - lift >= EDGE_PX / z || rect.bottom + lift > this.options.win.innerHeight;
       Object.assign(chip.style, {
         right: px(-5),
-        top: px(-27),
+        [above ? "top" : "bottom"]: px(-27),
         height: px(CHIP_HEIGHT_PX),
         padding: `0 ${px(7)}`,
         gap: px(4),
@@ -859,13 +929,26 @@ var Overlay = class {
         chip.appendChild(icon);
       }
       chip.appendChild(doc.createTextNode(box.label));
+      if (box.suffix) {
+        const muted = doc.createElement("span");
+        muted.className = "of";
+        muted.textContent = box.suffix;
+        chip.appendChild(muted);
+      }
       node.appendChild(chip);
     }
     return node;
   }
 };
 var LARGE_SHARE = 0.5;
+function reveal(win, element) {
+  const { top, bottom, height } = element.getBoundingClientRect();
+  const h = win.innerHeight;
+  if (top < 0 || bottom > h)
+    win.scrollTo?.({ top: win.scrollY + top - Math.max(0, (h - height) / 2), behavior: "smooth" });
+}
 var CHIP_HEIGHT_PX = 20;
+var EDGE_PX = 4;
 var PIN_PX = 22;
 var STYLES = `
 .layer { position: fixed; inset: 0; pointer-events: none; }
@@ -875,6 +958,7 @@ var STYLES = `
   font-family: Poppins, ui-sans-serif, system-ui, sans-serif; font-weight: 600; line-height: 1;
   letter-spacing: 0; box-sizing: border-box;
 }
+.of { font-weight: 400; opacity: .72; }
 .capture { position: fixed; inset: 0; pointer-events: auto; cursor: crosshair; display: none; }
 .pin {
   position: fixed; box-sizing: border-box; pointer-events: auto; cursor: pointer; text-align: center;
@@ -885,53 +969,6 @@ var STYLES = `
 .icon svg { width: 100%; height: 100%; display: block; }
 `;
 
-// src/stega.ts
-var DIGITS = ["\u200B", "\u200C", "\u200D", "\u2060"];
-var PREFIX = "\u2060\u200D\u200C\u200C\u200D\u200D\u200C\u2060";
-var PAYLOAD_RE = /^(doc:[a-z0-9]+(?:-[a-z0-9]+)*|[a-z0-9]+(?:-[a-z0-9]+)*\/[a-z0-9]+(?:-[a-z0-9]+)*)#([a-z][a-z0-9_]{0,127})(?:@([A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}))?$/;
-var MARKER_RE = /⁠‍‌‌‍‍‌⁠(?:[​‌][​‌‍⁠]{3})*/g;
-function hasStega(value) {
-  return typeof value === "string" && value.includes(PREFIX);
-}
-function stegaDecode(text) {
-  if (!text.includes(PREFIX)) return [];
-  const found = [];
-  for (const match of text.match(MARKER_RE) ?? []) {
-    let payload = "";
-    for (let i = PREFIX.length; i + 4 <= match.length; i += 4) {
-      let byte = 0;
-      for (let j = 0; j < 4; j++) byte = byte * 4 + DIGITS.indexOf(match[i + j]);
-      payload += String.fromCharCode(byte);
-    }
-    const parsed = PAYLOAD_RE.exec(payload);
-    if (!parsed) continue;
-    found.push({
-      recordRef: parsed[1],
-      fieldKey: parsed[2],
-      locale: parsed[3] ?? null,
-      tag: `${parsed[1]}#${parsed[2]}`
-    });
-  }
-  return found;
-}
-function splitStega(text) {
-  if (!text.includes(PREFIX)) return { text, markers: "" };
-  return { text: text.replace(MARKER_RE, ""), markers: (text.match(MARKER_RE) ?? []).join("") };
-}
-function cleanString(text) {
-  return text.includes(PREFIX) ? text.replace(MARKER_RE, "") : text;
-}
-function cleanStega(value) {
-  if (typeof value === "string") return cleanString(value);
-  if (Array.isArray(value)) return value.map((item) => cleanStega(item));
-  if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
-    const out = {};
-    for (const [key, item] of Object.entries(value)) out[key] = cleanStega(item);
-    return out;
-  }
-  return value;
-}
-
 // src/preview/tags.ts
 var TAG_SELECTOR = "[data-zap],[data-zap-field]";
 function readElementTag(element) {
@@ -1065,6 +1102,17 @@ var TagIndex = class {
     })).sort((a, b) => a.tag < b.tag ? -1 : a.tag > b.tag ? 1 : 0);
   }
 };
+var MAX_TAGGED = 5e3;
+var RUNAWAY_PASSES = 3;
+function tagGuard() {
+  let last = 0;
+  let grew = 0;
+  return (count, page) => {
+    grew = count > last && !page ? grew + 1 : 0;
+    last = count;
+    return count > MAX_TAGGED ? "cap" : grew >= RUNAWAY_PASSES ? "runaway" : null;
+  };
+}
 function observeTags(target, onChange, options = {}) {
   const throttleMs = options.throttleMs ?? 250;
   const set = options.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
@@ -1075,17 +1123,24 @@ function observeTags(target, onChange, options = {}) {
   };
   let timer = null;
   let last = -Infinity;
-  const fire = () => {
-    timer = null;
-    last = Date.now();
-    onChange();
-  };
-  const observer = new Observer((records) => {
+  let page = false;
+  const queue = (records, fromPage) => {
     if (options.ignore && records.every((record) => options.ignore(record.target))) return;
+    page || (page = fromPage);
     if (timer !== null) return;
     const wait = Math.max(0, last + throttleMs - Date.now());
     timer = set(fire, Math.max(wait, 16));
-  });
+  };
+  const fire = () => {
+    timer = null;
+    last = Date.now();
+    const changed = page;
+    page = false;
+    onChange(changed);
+    const own = observer.takeRecords();
+    if (own.length) queue(own, false);
+  };
+  const observer = new Observer((records) => queue(records, true));
   observer.observe(target, {
     subtree: true,
     childList: true,
@@ -1099,6 +1154,15 @@ function observeTags(target, onChange, options = {}) {
   };
 }
 
+// src/preview/site/shortcut.ts
+var DEFAULT_SHORTCUT = "Z";
+var TYPING = 'input,textarea,select,[contenteditable]:not([contenteditable="false"])';
+function isShortcut(event, key) {
+  const target = event.composedPath?.()[0] ?? event.target;
+  return event.shiftKey && !(event.ctrlKey || event.metaKey || event.altKey || event.repeat || event.isComposing) && // Some browsers report a key inside an IME composition only as keyCode 229.
+  event.keyCode !== 229 && event.key?.toLowerCase() === key.toLowerCase() && !target?.closest?.(TYPING);
+}
+
 export {
   FIELD_KEY_RE,
   parseRecordRef,
@@ -1141,6 +1205,8 @@ export {
   parseEditorMessage,
   parsePageMessage,
   envelope,
+  splitStega,
+  cleanStega,
   cssEscape,
   safeQueryAll,
   buildSelector,
@@ -1152,11 +1218,13 @@ export {
   findAnchorElement,
   OVERLAY_HOST_TAG,
   Overlay,
-  splitStega,
-  cleanStega,
+  reveal,
   TAG_SELECTOR,
   readElementTag,
   TagIndex,
-  observeTags
+  tagGuard,
+  observeTags,
+  DEFAULT_SHORTCUT,
+  isShortcut
 };
-//# sourceMappingURL=chunk-VW4EH7NY.js.map
+//# sourceMappingURL=chunk-7CXQK2PR.js.map