@rei-standard/amsg-shared 0.4.0-next.6 → 0.4.0-next.8

package/README.md

@@ -70,7 +70,7 @@ omit all four.
 
 | Field                | Type                                      | Notes |
 |----------------------|-------------------------------------------|-------|
-| `show`               | `'auto' \| 'always' \| 'when-hidden' \| false` | Display policy. `auto` follows SW defaults. |
+| `show`               | `'auto' \| 'always' \| 'when-hidden' \| false` | Display policy — see [选哪个 `show`](#选哪个-show). |
 | `title`              | `string?`                                | Notification title override. |
 | `body`               | `string?`                                | Notification body override. |
 | `icon`               | `string?`                                | Notification icon URL. |
@@ -78,12 +78,56 @@ omit all four.
 | `tag`                | `string?`                                | Notification grouping tag. |
 | `renotify`           | `boolean?`                               | Re-alert when a matching `tag` replaces an existing notification. |
 | `requireInteraction` | `boolean?`                               | Keep the notification visible until the user dismisses it. |
-| `silent`             | `boolean?`                               | Suppress notification sound and vibration. |
+| `silent`             | `(boolean \| 'when-visible')?`            | Suppress notification sound and vibration — see [选哪个 `silent`](#选哪个-silent). |
 | `data`               | `Record<string, unknown>?`               | Custom data passed to the notification. |
 
 Unknown fields are preserved for forward compatibility, but the known
 fields above are validated by the builders when present.
 
+### 选哪个 `show`
+
+订阅是按 `userVisibleOnly: true` 建的，收到 push 却不弹通知就是违约：Chrome 替你弹一条通用横幅，Firefox 有配额、超了退订，iOS 给新订阅几天宽限期（跟条数无关）、过期后一条不弹就吊销订阅。所以口径只有一条，跟机型无关——**要推就一定弹，不想弹就别推。**
+
+| 值 | SW 那边 | 什么时候用 |
+|---|---|---|
+| 不配 / `'auto'` | 按 `messageKind` 走默认（`content` / `result` 弹，其余不弹） | 默认，多数 payload 不用管 |
+| `'always'` | 一定弹 | 要推的一律用它。嫌打扰配 `tag` 折叠加 `silent`，而不是不弹 |
+| `false` | 一定不弹 | 明说这条不弹。有收件箱的发送端据此**根本不发这条 push**，内容落收件箱等客户端补拉 |
+| `'when-hidden'` | 有可见窗口就不弹 | 兼容档，新代码不选——应用在前台时它就是一条不弹的 push，那笔账照记 |
+
+所以 `show: false` 在发送端和接收端不是同一件事：有服务端收件箱的发送端（`@rei-standard/amsg-server` 单用户线）见到它压根不发，SW 那边收不到；没有收件箱的发送端才是「推过去、SW 不弹」。
+
+想要「立刻推到、但页面自己渲染」没有专门的档：用 `'always'` + `tag` + `silent`，页面自绘不受影响（`postMessage` 跟弹不弹通知无关）。
+
+完整取舍见 [`@rei-standard/amsg-sw` README 的「不展示通知的代价」](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/sw/README.md#不展示通知的代价)。
+
+### 选哪个 `silent`
+
+`silent` 管的是「响不响铃、震不震」，跟弹不弹（`show`）是两件独立的事——通知照样进通知中心，只是安静地进。
+
+| 值 | SW 那边 | 什么时候用 |
+|---|---|---|
+| 不配 / `false` | 正常响铃震动 | 默认 |
+| `true` | 一律不响 | 一串连着来的通知配 `tag` 折叠，只想在通知中心留个痕迹 |
+| `'when-visible'` | 有可见窗口就静音，没有就照常响 | 页面自己会把内容画出来的那类消息：用户正看着页面就别再响一声，人切后台了照样叫得动 |
+
+`'when-visible'` 只能由 Service Worker 当场算：发送端发推那一刻并不知道用户此刻在不在前台，写死 `silent: true` 的话，用户切到后台收到的那条也不会响。判定用的是跟 `show: 'when-hidden'` 同一套窗口可见性口径，一条 payload 只算一次。
+
+### `notificationIntent(payload)`
+
+把上面这套规则算成一个值，`'always'` / `'when-hidden'` / `'never'`：`notification.show` 说了算，没说才按 `messageKind` 走默认。两端读同一份——SW 拿它决定要不要 `showNotification`，发送端拿它决定这条值不值得占用推送通道（`'never'` 的 payload 推过去不会有任何可见反馈，`@rei-standard/amsg-server` 只把它落进收件箱，等客户端上线 `GET /outbox?since=` 补拉）。
+
+```js
+import { notificationIntent } from '@rei-standard/amsg-shared';
+
+notificationIntent({ messageKind: 'content' });                                  // 'always'
+notificationIntent({ messageKind: 'reasoning' });                                // 'never'
+notificationIntent({ messageKind: 'reasoning', notification: { show: 'always' } }); // 'always'
+notificationIntent({ messageKind: 'content', notification: { show: false } });   // 'never'
+```
+
+`'when-hidden'` 单独占一档，因为它到底弹不弹要看当下有没有可见窗口，那只有 SW 知道；发送端把它当「可能会弹」照发。
+
 ---
 
 ## Per-kind fields
@@ -168,7 +212,7 @@ The legacy `type` field is **gone** — do not look for it on
 两处与别的 kind 不同：
 
 - **投递路径**：产出方（`@rei-standard/amsg-server` 的 `ctx.emitResult()`）除了推送，还把它落进服务端收件箱，客户端下次 `GET /outbox?since=` 一定拿得到。
-- **通知**：SW 侧默认弹（与 `content` 同待遇，其余三种是静默送给页面）——结果往往正是「跑完了，回来看看」那句话。不想弹就带 `notification: { show: false }`。
+- **通知**：SW 侧默认弹（与 `content` 同待遇，其余三种是静默送给页面）——结果往往正是「跑完了，回来看看」那句话。不想弹就带 `notification: { show: false }`：这一档 `amsg-server` 不发推送、只落收件箱，客户端补拉时拿到（见[选哪个 `show`](#选哪个-show)）。
 
 ---
 

package/dist/index.cjs

@@ -66,6 +66,7 @@ __export(src_exports, {
   jsonToBase64Url: () => jsonToBase64Url,
   normalizeAiApiUrl: () => normalizeAiApiUrl,
   normalizeVapidSubject: () => normalizeVapidSubject,
+  notificationIntent: () => notificationIntent,
   randomBytes: () => randomBytes,
   randomUUID: () => randomUUID,
   readReasoningContent: () => readReasoningContent,
@@ -845,6 +846,17 @@ var PUSH_SOURCE = Object.freeze({
   INSTANT: "instant",
   SCHEDULED: "scheduled"
 });
+function notificationIntent(payload) {
+  const notification = payload && typeof payload === "object" && payload.notification;
+  const show = notification && typeof notification === "object" ? notification.show : void 0;
+  if (show === "always") return "always";
+  if (show === "when-hidden") return "when-hidden";
+  if (show === false) return "never";
+  if (!payload || typeof payload !== "object") return "never";
+  const kind = payload.messageKind;
+  if (kind === void 0 || kind === null) return "always";
+  return kind === MESSAGE_KIND.CONTENT || kind === MESSAGE_KIND.RESULT ? "always" : "never";
+}
 function requireField(kind, field, value) {
   if (value === void 0 || value === null || value === "") {
     throw new Error(`[amsg-shared] ${kind}: '${field}' is required`);
@@ -952,11 +964,14 @@ function validateNotificationArg(kind, value) {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
     }
   }
-  for (const f of ["renotify", "requireInteraction", "silent"]) {
+  for (const f of ["renotify", "requireInteraction"]) {
     if (n[f] !== void 0 && typeof n[f] !== "boolean") {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
     }
   }
+  if (n.silent !== void 0 && typeof n.silent !== "boolean" && n.silent !== "when-visible") {
+    throw new Error(`[amsg-shared] ${kind}: 'notification.silent' must be true, false, or "when-visible"`);
+  }
   if (n.data !== void 0 && (n.data === null || typeof n.data !== "object" || Array.isArray(n.data))) {
     throw new Error(`[amsg-shared] ${kind}: 'notification.data' must be a plain object when present`);
   }

package/dist/index.d.cts

@@ -1,3 +1,110 @@
+/**
+ * Fields present on every push, regardless of kind. Discriminator
+ * fields (`messageKind`) and kind-specific fields live on the kind
+ * interfaces below.
+ *
+ * `metadata` is a passthrough namespace owned by the caller. Packages
+ * are forbidden from writing their own fields into `metadata` — any
+ * protocol-level data goes on top-level fields.
+ *
+ * Scheduling identity (`taskId` / `taskUuid` / `recurrenceType` /
+ * `occurrenceMs`) is stamped by `@rei-standard/amsg-server` on every push
+ * that came out of a scheduled task row. It tells the client which task
+ * this is, whether the task will come back, and which nominal fire time
+ * produced this burst — so a task the client never created (one the
+ * character scheduled for itself at fire time) still arrives fully
+ * identified. Pushes with no task behind them (amsg-instant) omit all four.
+ *
+ * @typedef {Object} AmsgPushCommon
+ * @property {MessageType} messageType   - How the push was produced.
+ * @property {PushSource}  source        - Which sub-package routed it.
+ * @property {string}      messageId     - Unique per push. Format owned by the producer.
+ * @property {string}      sessionId     - Shared across all pushes from one LLM round (reasoning + content) and across iterations of a single agentic-loop request. Opaque id — do not parse it for task identity, read the fields below.
+ * @property {string}      timestamp     - ISO 8601 timestamp at producer.
+ * @property {string}      [messageSubtype] - Caller-defined business namespace. Defaults to 'chat' at producers.
+ * @property {Object}      [metadata]    - Caller passthrough. Packages MUST NOT write here.
+ * @property {NotificationDirective} [notification] - SW notification strategy.
+ * @property {number | string | null} [taskId] - Scheduled task row id.
+ * @property {string | null} [taskUuid] - Scheduled task uuid (the id the scheduling side chose).
+ * @property {'none' | 'daily' | 'weekly'} [recurrenceType] - Whether that task fires again.
+ * @property {number | null} [occurrenceMs] - Nominal fire time of this occurrence (epoch ms).
+ */
+/**
+ * SW-rendering directive. Mirrors the fields that `amsg-sw`'s
+ * `createNotificationFromPayload` consumes (`notification.{show,title,body,icon,badge,tag,renotify,requireInteraction,silent,data}`)
+ * so producers get builder validation for the fields the SW actually reads.
+ *
+ * Routing in SW:
+ *   - By default (`show: "auto"` or omitted), `messageKind: 'content'` / `'result'` (and legacy
+ *     un-kinded payloads) will display a system notification. `reasoning` / `tool_request` /
+ *     `error` will dispatch silently.
+ *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
+ *   - `silent: "when-visible"` is resolved by the SW at render time from the
+ *     same window-visibility check `show: "when-hidden"` uses: silent while a
+ *     `visibilityState === "visible"` window client exists, audible otherwise.
+ *     `true` / `false` stay literal.
+ *   - When rendering, `notification.*` is consulted first, with per-field
+ *     fallback to the matching top-level payload fields (`title`,
+ *     `body`/`message`, `icon`/`avatarUrl`, `badge`, `tag`/`messageId`,
+ *     `renotify`, `requireInteraction`, `silent`, `data`), and finally to
+ *     the SW's `defaultIcon` / `defaultBadge` options (boolean knobs
+ *     default to `false` at the SW). Prefer setting overrides under
+ *     `notification` for explicitness; top-level fallback exists so that
+ *     legacy un-namespaced payloads keep working byte-for-byte.
+ *
+ * 选 `show` 的口径只有一条，跟机型无关：**要推就一定弹**（`"always"`，嫌打扰
+ * 配 `tag` 折叠 + `silent`），**不想弹就别推**（不配或配 `false`，内容落服务端
+ * 收件箱，等客户端上线补拉）。收到 push 却不弹通知是违约：Firefox 按配额退
+ * 订，iOS 过了订阅宽限期直接吊销。`"when-hidden"` 是给老部署留的兼容档，新代
+ * 码不选。`show: false` 在两端也不是同一件事——有收件箱的发送端见到它根本不发
+ * 这条 push，SW 压根收不到。
+ *
+ * 想要「前台安静、切后台照常响」就配 `silent: "when-visible"`：`show` 照旧
+ * `"always"`（通知一定弹出来，那笔账不欠），响不响铃由 SW 收到时看有没有可见
+ * 窗口现算。发送端定不了这件事——它发推那一刻并不知道用户在不在前台，写死
+ * `silent: true` 的结果是切后台也不响。
+ *
+ * 各档取舍见本包 README 的「选哪个 `show`」与 `@rei-standard/amsg-sw` README
+ * 的「不展示通知的代价」。
+ *
+ * @typedef {Object} NotificationDirective
+ * @property {"auto" | "always" | "when-hidden" | false} [show] - Rendering strategy. Defaults to "auto" (render only if messageKind is content).
+ * @property {string}  [title]              - Notification title override (falls back to top-level `title`, then `来自 {contactName}`).
+ * @property {string}  [body]               - Notification body override (falls back to top-level `body`, then `message`).
+ * @property {string}  [icon]               - Icon URL override (falls back to top-level `icon`/`avatarUrl`, then SW `defaultIcon`).
+ * @property {string}  [badge]              - Badge URL override (falls back to top-level `badge`, then SW `defaultBadge`).
+ * @property {string}  [tag]                - Notification grouping tag; matching tag replaces the prior notification (falls back to top-level `tag`, then `messageId`, then a generated unique tag).
+ * @property {boolean} [renotify]           - When tag matches, still vibrate/sound (falls back to top-level `renotify`, default false at SW).
+ * @property {boolean} [requireInteraction] - Notification stays until user dismisses (falls back to top-level `requireInteraction`, default false at SW).
+ * @property {boolean | "when-visible"} [silent] - Suppress sound and vibration. `true` / `false` are literal; `"when-visible"` is decided by the SW at render time — silent while a window client is visible, audible otherwise (falls back to top-level `silent`, default false at SW).
+ * @property {Record<string, unknown>} [data] - Custom payload data to attach to the notification (falls back to top-level `data`).
+ */
+/**
+ * 这条 payload 到了客户端会不会弹系统通知——发送端与 SW 共用的这一份判定。
+ *
+ * 三个取值：
+ *
+ * | 返回值          | 意思 |
+ * |----------------|------|
+ * | `'always'`     | 一定弹 |
+ * | `'when-hidden'`| 看有没有可见窗口，由 SW 当场定（发送端无从知道）。兼容档，新代码用 `'always'` |
+ * | `'never'`      | 一定不弹 |
+ *
+ * 判定顺序跟 SW 里一模一样：`notification.show` 说了算，没说才按 `messageKind`
+ * 走默认（`content` / `result` 与缺 kind 的 2.0.x 老 payload 弹，`reasoning` /
+ * `tool_request` / `error` 不弹）。
+ *
+ * 两端各拿它做一件事：
+ *
+ * - **SW**：决定要不要 `showNotification`。
+ * - **发送端**：决定这条值不值得占用推送通道。`'never'` 的 payload 推过去就是
+ *   一次「收了 push 却不弹通知」，浏览器那边要记账；有收件箱兜底的发送端
+ *   （`@rei-standard/amsg-server`）因此只落行、不推，等客户端上线补拉。
+ *
+ * @param {Record<string, unknown>|null|undefined} payload
+ * @returns {'always' | 'when-hidden' | 'never'}
+ */
+export function notificationIntent(payload: Record<string, unknown> | null | undefined): "always" | "when-hidden" | "never";
 /**
  * Build a {@link ContentPush}. Use this for legacy sentence-split
  * bursts (set `messageIndex` 1-based + `totalMessages`) or for a
@@ -576,6 +683,10 @@ export type AmsgPushCommon = {
  *     un-kinded payloads) will display a system notification. `reasoning` / `tool_request` /
  *     `error` will dispatch silently.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
+ *   - `silent: "when-visible"` is resolved by the SW at render time from the
+ *     same window-visibility check `show: "when-hidden"` uses: silent while a
+ *     `visibilityState === "visible"` window client exists, audible otherwise.
+ *     `true` / `false` stay literal.
  *   - When rendering, `notification.*` is consulted first, with per-field
  *     fallback to the matching top-level payload fields (`title`,
  *     `body`/`message`, `icon`/`avatarUrl`, `badge`, `tag`/`messageId`,
@@ -584,6 +695,21 @@ export type AmsgPushCommon = {
  *     default to `false` at the SW). Prefer setting overrides under
  *     `notification` for explicitness; top-level fallback exists so that
  *     legacy un-namespaced payloads keep working byte-for-byte.
+ *
+ * 选 `show` 的口径只有一条，跟机型无关：**要推就一定弹**（`"always"`，嫌打扰
+ * 配 `tag` 折叠 + `silent`），**不想弹就别推**（不配或配 `false`，内容落服务端
+ * 收件箱，等客户端上线补拉）。收到 push 却不弹通知是违约：Firefox 按配额退
+ * 订，iOS 过了订阅宽限期直接吊销。`"when-hidden"` 是给老部署留的兼容档，新代
+ * 码不选。`show: false` 在两端也不是同一件事——有收件箱的发送端见到它根本不发
+ * 这条 push，SW 压根收不到。
+ *
+ * 想要「前台安静、切后台照常响」就配 `silent: "when-visible"`：`show` 照旧
+ * `"always"`（通知一定弹出来，那笔账不欠），响不响铃由 SW 收到时看有没有可见
+ * 窗口现算。发送端定不了这件事——它发推那一刻并不知道用户在不在前台，写死
+ * `silent: true` 的结果是切后台也不响。
+ *
+ * 各档取舍见本包 README 的「选哪个 `show`」与 `@rei-standard/amsg-sw` README
+ * 的「不展示通知的代价」。
  */
 export type NotificationDirective = {
     /**
@@ -619,9 +745,9 @@ export type NotificationDirective = {
      */
     requireInteraction?: boolean;
     /**
-     * - Suppress sound and vibration (falls back to top-level `silent`, default false at SW).
+     * - Suppress sound and vibration. `true` / `false` are literal; `"when-visible"` is decided by the SW at render time — silent while a window client is visible, audible otherwise (falls back to top-level `silent`, default false at SW).
      */
-    silent?: boolean;
+    silent?: boolean | "when-visible";
     /**
      * - Custom payload data to attach to the notification (falls back to top-level `data`).
      */

package/dist/index.d.ts

@@ -1,3 +1,110 @@
+/**
+ * Fields present on every push, regardless of kind. Discriminator
+ * fields (`messageKind`) and kind-specific fields live on the kind
+ * interfaces below.
+ *
+ * `metadata` is a passthrough namespace owned by the caller. Packages
+ * are forbidden from writing their own fields into `metadata` — any
+ * protocol-level data goes on top-level fields.
+ *
+ * Scheduling identity (`taskId` / `taskUuid` / `recurrenceType` /
+ * `occurrenceMs`) is stamped by `@rei-standard/amsg-server` on every push
+ * that came out of a scheduled task row. It tells the client which task
+ * this is, whether the task will come back, and which nominal fire time
+ * produced this burst — so a task the client never created (one the
+ * character scheduled for itself at fire time) still arrives fully
+ * identified. Pushes with no task behind them (amsg-instant) omit all four.
+ *
+ * @typedef {Object} AmsgPushCommon
+ * @property {MessageType} messageType   - How the push was produced.
+ * @property {PushSource}  source        - Which sub-package routed it.
+ * @property {string}      messageId     - Unique per push. Format owned by the producer.
+ * @property {string}      sessionId     - Shared across all pushes from one LLM round (reasoning + content) and across iterations of a single agentic-loop request. Opaque id — do not parse it for task identity, read the fields below.
+ * @property {string}      timestamp     - ISO 8601 timestamp at producer.
+ * @property {string}      [messageSubtype] - Caller-defined business namespace. Defaults to 'chat' at producers.
+ * @property {Object}      [metadata]    - Caller passthrough. Packages MUST NOT write here.
+ * @property {NotificationDirective} [notification] - SW notification strategy.
+ * @property {number | string | null} [taskId] - Scheduled task row id.
+ * @property {string | null} [taskUuid] - Scheduled task uuid (the id the scheduling side chose).
+ * @property {'none' | 'daily' | 'weekly'} [recurrenceType] - Whether that task fires again.
+ * @property {number | null} [occurrenceMs] - Nominal fire time of this occurrence (epoch ms).
+ */
+/**
+ * SW-rendering directive. Mirrors the fields that `amsg-sw`'s
+ * `createNotificationFromPayload` consumes (`notification.{show,title,body,icon,badge,tag,renotify,requireInteraction,silent,data}`)
+ * so producers get builder validation for the fields the SW actually reads.
+ *
+ * Routing in SW:
+ *   - By default (`show: "auto"` or omitted), `messageKind: 'content'` / `'result'` (and legacy
+ *     un-kinded payloads) will display a system notification. `reasoning` / `tool_request` /
+ *     `error` will dispatch silently.
+ *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
+ *   - `silent: "when-visible"` is resolved by the SW at render time from the
+ *     same window-visibility check `show: "when-hidden"` uses: silent while a
+ *     `visibilityState === "visible"` window client exists, audible otherwise.
+ *     `true` / `false` stay literal.
+ *   - When rendering, `notification.*` is consulted first, with per-field
+ *     fallback to the matching top-level payload fields (`title`,
+ *     `body`/`message`, `icon`/`avatarUrl`, `badge`, `tag`/`messageId`,
+ *     `renotify`, `requireInteraction`, `silent`, `data`), and finally to
+ *     the SW's `defaultIcon` / `defaultBadge` options (boolean knobs
+ *     default to `false` at the SW). Prefer setting overrides under
+ *     `notification` for explicitness; top-level fallback exists so that
+ *     legacy un-namespaced payloads keep working byte-for-byte.
+ *
+ * 选 `show` 的口径只有一条，跟机型无关：**要推就一定弹**（`"always"`，嫌打扰
+ * 配 `tag` 折叠 + `silent`），**不想弹就别推**（不配或配 `false`，内容落服务端
+ * 收件箱，等客户端上线补拉）。收到 push 却不弹通知是违约：Firefox 按配额退
+ * 订，iOS 过了订阅宽限期直接吊销。`"when-hidden"` 是给老部署留的兼容档，新代
+ * 码不选。`show: false` 在两端也不是同一件事——有收件箱的发送端见到它根本不发
+ * 这条 push，SW 压根收不到。
+ *
+ * 想要「前台安静、切后台照常响」就配 `silent: "when-visible"`：`show` 照旧
+ * `"always"`（通知一定弹出来，那笔账不欠），响不响铃由 SW 收到时看有没有可见
+ * 窗口现算。发送端定不了这件事——它发推那一刻并不知道用户在不在前台，写死
+ * `silent: true` 的结果是切后台也不响。
+ *
+ * 各档取舍见本包 README 的「选哪个 `show`」与 `@rei-standard/amsg-sw` README
+ * 的「不展示通知的代价」。
+ *
+ * @typedef {Object} NotificationDirective
+ * @property {"auto" | "always" | "when-hidden" | false} [show] - Rendering strategy. Defaults to "auto" (render only if messageKind is content).
+ * @property {string}  [title]              - Notification title override (falls back to top-level `title`, then `来自 {contactName}`).
+ * @property {string}  [body]               - Notification body override (falls back to top-level `body`, then `message`).
+ * @property {string}  [icon]               - Icon URL override (falls back to top-level `icon`/`avatarUrl`, then SW `defaultIcon`).
+ * @property {string}  [badge]              - Badge URL override (falls back to top-level `badge`, then SW `defaultBadge`).
+ * @property {string}  [tag]                - Notification grouping tag; matching tag replaces the prior notification (falls back to top-level `tag`, then `messageId`, then a generated unique tag).
+ * @property {boolean} [renotify]           - When tag matches, still vibrate/sound (falls back to top-level `renotify`, default false at SW).
+ * @property {boolean} [requireInteraction] - Notification stays until user dismisses (falls back to top-level `requireInteraction`, default false at SW).
+ * @property {boolean | "when-visible"} [silent] - Suppress sound and vibration. `true` / `false` are literal; `"when-visible"` is decided by the SW at render time — silent while a window client is visible, audible otherwise (falls back to top-level `silent`, default false at SW).
+ * @property {Record<string, unknown>} [data] - Custom payload data to attach to the notification (falls back to top-level `data`).
+ */
+/**
+ * 这条 payload 到了客户端会不会弹系统通知——发送端与 SW 共用的这一份判定。
+ *
+ * 三个取值：
+ *
+ * | 返回值          | 意思 |
+ * |----------------|------|
+ * | `'always'`     | 一定弹 |
+ * | `'when-hidden'`| 看有没有可见窗口，由 SW 当场定（发送端无从知道）。兼容档，新代码用 `'always'` |
+ * | `'never'`      | 一定不弹 |
+ *
+ * 判定顺序跟 SW 里一模一样：`notification.show` 说了算，没说才按 `messageKind`
+ * 走默认（`content` / `result` 与缺 kind 的 2.0.x 老 payload 弹，`reasoning` /
+ * `tool_request` / `error` 不弹）。
+ *
+ * 两端各拿它做一件事：
+ *
+ * - **SW**：决定要不要 `showNotification`。
+ * - **发送端**：决定这条值不值得占用推送通道。`'never'` 的 payload 推过去就是
+ *   一次「收了 push 却不弹通知」，浏览器那边要记账；有收件箱兜底的发送端
+ *   （`@rei-standard/amsg-server`）因此只落行、不推，等客户端上线补拉。
+ *
+ * @param {Record<string, unknown>|null|undefined} payload
+ * @returns {'always' | 'when-hidden' | 'never'}
+ */
+export function notificationIntent(payload: Record<string, unknown> | null | undefined): "always" | "when-hidden" | "never";
 /**
  * Build a {@link ContentPush}. Use this for legacy sentence-split
  * bursts (set `messageIndex` 1-based + `totalMessages`) or for a
@@ -576,6 +683,10 @@ export type AmsgPushCommon = {
  *     un-kinded payloads) will display a system notification. `reasoning` / `tool_request` /
  *     `error` will dispatch silently.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
+ *   - `silent: "when-visible"` is resolved by the SW at render time from the
+ *     same window-visibility check `show: "when-hidden"` uses: silent while a
+ *     `visibilityState === "visible"` window client exists, audible otherwise.
+ *     `true` / `false` stay literal.
  *   - When rendering, `notification.*` is consulted first, with per-field
  *     fallback to the matching top-level payload fields (`title`,
  *     `body`/`message`, `icon`/`avatarUrl`, `badge`, `tag`/`messageId`,
@@ -584,6 +695,21 @@ export type AmsgPushCommon = {
  *     default to `false` at the SW). Prefer setting overrides under
  *     `notification` for explicitness; top-level fallback exists so that
  *     legacy un-namespaced payloads keep working byte-for-byte.
+ *
+ * 选 `show` 的口径只有一条，跟机型无关：**要推就一定弹**（`"always"`，嫌打扰
+ * 配 `tag` 折叠 + `silent`），**不想弹就别推**（不配或配 `false`，内容落服务端
+ * 收件箱，等客户端上线补拉）。收到 push 却不弹通知是违约：Firefox 按配额退
+ * 订，iOS 过了订阅宽限期直接吊销。`"when-hidden"` 是给老部署留的兼容档，新代
+ * 码不选。`show: false` 在两端也不是同一件事——有收件箱的发送端见到它根本不发
+ * 这条 push，SW 压根收不到。
+ *
+ * 想要「前台安静、切后台照常响」就配 `silent: "when-visible"`：`show` 照旧
+ * `"always"`（通知一定弹出来，那笔账不欠），响不响铃由 SW 收到时看有没有可见
+ * 窗口现算。发送端定不了这件事——它发推那一刻并不知道用户在不在前台，写死
+ * `silent: true` 的结果是切后台也不响。
+ *
+ * 各档取舍见本包 README 的「选哪个 `show`」与 `@rei-standard/amsg-sw` README
+ * 的「不展示通知的代价」。
  */
 export type NotificationDirective = {
     /**
@@ -619,9 +745,9 @@ export type NotificationDirective = {
      */
     requireInteraction?: boolean;
     /**
-     * - Suppress sound and vibration (falls back to top-level `silent`, default false at SW).
+     * - Suppress sound and vibration. `true` / `false` are literal; `"when-visible"` is decided by the SW at render time — silent while a window client is visible, audible otherwise (falls back to top-level `silent`, default false at SW).
      */
-    silent?: boolean;
+    silent?: boolean | "when-visible";
     /**
      * - Custom payload data to attach to the notification (falls back to top-level `data`).
      */

package/dist/index.mjs

@@ -761,6 +761,17 @@ var PUSH_SOURCE = Object.freeze({
   INSTANT: "instant",
   SCHEDULED: "scheduled"
 });
+function notificationIntent(payload) {
+  const notification = payload && typeof payload === "object" && payload.notification;
+  const show = notification && typeof notification === "object" ? notification.show : void 0;
+  if (show === "always") return "always";
+  if (show === "when-hidden") return "when-hidden";
+  if (show === false) return "never";
+  if (!payload || typeof payload !== "object") return "never";
+  const kind = payload.messageKind;
+  if (kind === void 0 || kind === null) return "always";
+  return kind === MESSAGE_KIND.CONTENT || kind === MESSAGE_KIND.RESULT ? "always" : "never";
+}
 function requireField(kind, field, value) {
   if (value === void 0 || value === null || value === "") {
     throw new Error(`[amsg-shared] ${kind}: '${field}' is required`);
@@ -868,11 +879,14 @@ function validateNotificationArg(kind, value) {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
     }
   }
-  for (const f of ["renotify", "requireInteraction", "silent"]) {
+  for (const f of ["renotify", "requireInteraction"]) {
     if (n[f] !== void 0 && typeof n[f] !== "boolean") {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
     }
   }
+  if (n.silent !== void 0 && typeof n.silent !== "boolean" && n.silent !== "when-visible") {
+    throw new Error(`[amsg-shared] ${kind}: 'notification.silent' must be true, false, or "when-visible"`);
+  }
   if (n.data !== void 0 && (n.data === null || typeof n.data !== "object" || Array.isArray(n.data))) {
     throw new Error(`[amsg-shared] ${kind}: 'notification.data' must be a plain object when present`);
   }
@@ -1262,6 +1276,7 @@ export {
   jsonToBase64Url,
   normalizeAiApiUrl,
   normalizeVapidSubject,
+  notificationIntent,
   randomBytes,
   randomUUID,
   readReasoningContent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-shared",
-  "version": "0.4.0-next.6",
+  "version": "0.4.0-next.8",
   "description": "ReiStandard Active Messaging shared types and push builders — the lowest layer (no deps on other amsg packages)",
   "repository": {
     "type": "git",