@12-apps/notifications 4.8.0 → 4.10.0

package/dist/preview-screen-DYJRAnAY.d.ts

@@ -0,0 +1,83 @@
+import { JSX } from 'react';
+
+/**
+ * The SHAPE of the operator screen's words — no words.
+ *
+ * REQUIRED config with no default in any language, the copy-portability
+ * doctrine. `./copy.pt-BR` and `./copy.en-US` ship packs a host passes BY NAME.
+ *
+ * What is NOT here is anything from the mails themselves: a subject, a body and
+ * a button label all arrive from the server already rendered in whichever
+ * language the preview was asked for. That separation is the point of the
+ * language switch — the CHROME follows the operator, the MESSAGE follows its
+ * own recipient.
+ */
+interface EmailPreviewScreenCopy {
+    readonly title: string;
+    readonly description: string;
+    /** The sidebar's filter field. */
+    readonly searchLabel: string;
+    readonly searchPlaceholder: string;
+    /** Nothing matched the filter. */
+    readonly noMatches: string;
+    /** No row is selected yet. */
+    readonly pickOne: string;
+    /** The three views of one message. */
+    readonly tabHtml: string;
+    readonly tabText: string;
+    readonly tabSource: string;
+    /** The two widths the HTML view renders at. */
+    readonly widthDesktop: string;
+    readonly widthMobile: string;
+    /** The subject line's label above the preview. */
+    readonly subjectLabel: string;
+    /** The sandboxed frame's title, for screen readers. */
+    readonly frameTitle: string;
+    /** The coverage strip, when the surface reports a gap. */
+    readonly coverageTitle: string;
+    readonly missingSamples: (keys: string) => string;
+    readonly orphanSamples: (keys: string) => string;
+    /** Loading and failure states. */
+    readonly loading: string;
+    readonly loadError: string;
+    readonly retry: string;
+}
+
+/**
+ * The operator screen over the `./email/previews` catalogue.
+ *
+ * ## What a host supplies, and what it does not
+ *
+ * `apiBase` — where the routes are mounted — and `copy`, by name. Nothing else:
+ * the owners, the languages, the messages and their subjects all arrive from
+ * the surface, because they are facts about the host's own mail that no prop
+ * could usefully restate.
+ *
+ * ## The selection lives in the URL, without a router
+ *
+ * `?id=` and `?locale=`, read and written through `history.replaceState`. A
+ * link to one mail in one language is the actual workflow this screen serves —
+ * "look at what the reset mail says now" — and local state would make every
+ * such conversation a set of instructions instead of a link.
+ *
+ * Deliberately NOT a router integration: this package cannot know whether a
+ * host runs react-router, TanStack Router or a framework's own, and a screen
+ * that imported one would be unmountable in the other two. `replaceState` is
+ * the one API all of them are built on, and `replace` rather than `push` so
+ * browsing twenty mails is not twenty back-button steps.
+ */
+interface EmailPreviewScreenConfig {
+    /** Where the routes are mounted, e.g. `/api/platform/email-previews`. */
+    readonly apiBase: string;
+    /** The screen's words. REQUIRED — see `./copy`. */
+    readonly copy: EmailPreviewScreenCopy;
+}
+/**
+ * Build the screen. One call, one config object — the shape every factory in
+ * this estate has.
+ */
+declare function createEmailPreviewScreen(config: EmailPreviewScreenConfig): {
+    page: () => JSX.Element;
+};
+
+export { type EmailPreviewScreenCopy as E, type EmailPreviewScreenConfig as a, createEmailPreviewScreen as c };

package/dist/react/index.d.ts

@@ -1,8 +1,10 @@
-import { N as NotificationsApiClient } from '../create-web-notifications-DrgqtU4Q.js';
-export { B as BADGE_POLL_MS, a as BADGE_RECONCILE_MS, b as BellButtonProps, I as InboxListStatus, d as InboxState, e as InboxStore, f as NotificationsHttpError, g as NotificationsPanelProps, h as NotificationsResult, i as NotificationsSignalHook, j as NotificationsSubscribe, k as NotificationsTransport, l as NotificationsWebConfig, P as PAGE_SIZE, m as PreferencesPayload, n as PreferencesScreenProps, o as PushRegistrationPayload, W as WebNotifications, p as WebPushPlatformHint, q as WebPushSetupConfig, r as createInboxStore, s as createNotificationsApiClient, c as createWebNotifications, t as httpNotificationsTransport, u as useInboxList, v as useInboxState, w as useUnreadCount } from '../create-web-notifications-DrgqtU4Q.js';
+import { L as LiveActivitiesConfig, N as NotificationsApiClient } from '../create-web-notifications-_NVYmlvy.js';
+export { B as BADGE_POLL_MS, a as BADGE_RECONCILE_MS, b as BellButtonProps, I as InboxListStatus, d as InboxState, e as InboxStore, f as LiveActivitiesHook, g as LiveActivityMessages, h as NotificationsHttpError, i as NotificationsPanelProps, j as NotificationsResult, k as NotificationsSignalHook, l as NotificationsSubscribe, m as NotificationsTransport, n as NotificationsWebConfig, P as PAGE_SIZE, o as PreferencesPayload, p as PreferencesScreenProps, q as PushRegistrationPayload, W as WebNotifications, r as WebPushPlatformHint, s as WebPushSetupConfig, t as createInboxStore, u as createNotificationsApiClient, c as createWebNotifications, v as httpNotificationsTransport, w as useInboxList, x as useInboxState, y as useUnreadCount } from '../create-web-notifications-_NVYmlvy.js';
 import { JSX } from 'react';
-import { N as NotificationMessages } from '../wire-CmRrB3_s.js';
-import '../types-CYJN1xCM.js';
+import { b as LiveActivity } from '../live-DYxEFO49.js';
+export { c as LiveActivityLane, d as LiveActivityStep, l as liveActivityLane } from '../live-DYxEFO49.js';
+import { N as NotificationMessages } from '../wire-BG1kuoXX.js';
+import '../types-BlqZkCWZ.js';
 
 /** Inline SVG bell (no icon-library dependency in this package). */
 
@@ -11,12 +13,59 @@ declare function BellIcon({ size, dim, }: {
     dim?: boolean;
 }): JSX.Element;
 
+/**
+ * The pinned block at the top of the panel: everything that is happening NOW,
+ * above everything that has already happened.
+ *
+ * ## Why it is here and not a second surface
+ *
+ * The notification centre is where a person goes to find out what they missed.
+ * Splitting "happening" into its own bell would make them check two places to
+ * answer one question, and the half they would stop checking is the one that
+ * only has something in it occasionally — which is this one. Above the list,
+ * inside the same drawer, it is on the path they already walk.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * - It does not touch `unread`. A live entry is not news; counting it would put
+ *   a number on the bell that no amount of reading can clear.
+ * - It renders nothing at all when there is nothing live — no heading, no empty
+ *   state, no reserved space. A panel with one permanent empty section in it is
+ *   a panel that has taught its reader to skip the top.
+ * - It does not fetch. `useActivities` is the host's, and `active` tells it
+ *   whether anyone is looking.
+ */
+
+interface LiveSectionProps {
+    config: LiveActivitiesConfig;
+    messages: NotificationMessages;
+    /** Whether the panel is open — passed straight through to the host's hook. */
+    active: boolean;
+    /**
+     * Follow a card's link.
+     *
+     * Optional, and the panel omits it for a host with no router: a card that
+     * cannot go anywhere renders as text rather than as a named control that
+     * does nothing.
+     */
+    onOpen?: (activity: LiveActivity) => void;
+}
+declare function LiveSection({ config, messages, active, onOpen, }: LiveSectionProps): JSX.Element | null;
+
 /**
  * "há 5 min"-style relative timestamp, falling back to an absolute date for
  * anything older than a week. Every word comes from the messages table, so a
  * host in another locale changes the copy and the locale together.
+ *
+ * `now` is a parameter rather than a read, and the live section is why. A
+ * relative phrase is only true for the instant it was computed, so something
+ * has to CAUSE the render that recomputes it — and the live entries' own data
+ * cannot: a host backed by react-query gets the previous object back whenever a
+ * poll is deep-equal (`structuralSharing`, on by default), which within one
+ * stage it always is. The section therefore ticks a clock and hands it down.
+ * Defaulted, so every existing caller reads the wall clock exactly as before.
  */
-declare function relativeTime(iso: string, messages: NotificationMessages): string;
+declare function relativeTime(iso: string, messages: NotificationMessages, now?: number): string;
 
 /**
  * The browser half of Web Push: register the service worker, ask permission,
@@ -44,4 +93,4 @@ declare function enableWebPush(api: NotificationsApiClient, swPath?: string): Pr
 /** Disable flow: unsubscribe the browser and drop the server-side row. */
 declare function disableWebPush(api: NotificationsApiClient): Promise<void>;
 
-export { BellIcon, NotificationsApiClient, type PushSetupResult, disableWebPush, enableWebPush, getExistingPushSubscription, pushSupported, relativeTime };
+export { BellIcon, LiveActivitiesConfig, LiveActivity, LiveSection, type LiveSectionProps, NotificationsApiClient, type PushSetupResult, disableWebPush, enableWebPush, getExistingPushSubscription, pushSupported, relativeTime };

package/dist/react/index.js

@@ -1,18 +1,13 @@
-import {
-  relativeTime
-} from "../chunk-O5BVUXPO.js";
-import {
-  disableWebPush,
-  enableWebPush,
-  getExistingPushSubscription,
-  pushSupported
-} from "../chunk-CQZMTFPY.js";
 import {
   NotificationsHttpError,
   createNotificationsApiClient,
   createWebNotifications,
   httpNotificationsTransport
-} from "../chunk-M5XTROYM.js";
+} from "../chunk-5Y7QRORV.js";
+import {
+  LiveSection,
+  relativeTime
+} from "../chunk-JCVRQ42B.js";
 import {
   BADGE_POLL_MS,
   BADGE_RECONCILE_MS,
@@ -23,12 +18,22 @@ import {
   useInboxState,
   useUnreadCount
 } from "../chunk-BW723CX2.js";
+import {
+  disableWebPush,
+  enableWebPush,
+  getExistingPushSubscription,
+  pushSupported
+} from "../chunk-CQZMTFPY.js";
 import "../chunk-M2TVBVH2.js";
+import {
+  liveActivityLane
+} from "../chunk-RTURLH5U.js";
 import "../chunk-7QVYU63E.js";
 export {
   BADGE_POLL_MS,
   BADGE_RECONCILE_MS,
   BellIcon,
+  LiveSection,
   NotificationsHttpError,
   PAGE_SIZE,
   createInboxStore,
@@ -38,6 +43,7 @@ export {
   enableWebPush,
   getExistingPushSubscription,
   httpNotificationsTransport,
+  liveActivityLane,
   pushSupported,
   relativeTime,
   useInboxList,

package/dist/server/index.d.ts

@@ -1,11 +1,12 @@
-import { A as ApiNotifications } from '../create-api-notifications-WaexrZnn.js';
-export { C as CommittedNotification, E as EMAIL_DRIVERS, c as EmailDriver, d as EmailDriverDeclaration, e as EmailMessage, f as ExtraDrivers, L as ListNotificationsInput, g as NotificationAudienceDirectory, h as NotificationChannelPolicy, i as NotificationCommittedListener, j as NotificationContactDirectory, k as NotificationCreateData, l as NotificationDelegate, m as NotificationDeliveryDelegate, n as NotificationDeliveryRow, o as NotificationDeliveryWhere, p as NotificationDispatchScheduler, q as NotificationInboxStore, r as NotificationPageAfter, s as NotificationPreferenceDelegate, t as NotificationPreferenceRow, u as NotificationPreferenceStore, v as NotificationRouter, w as NotificationWhere, a as NotificationsActor, x as NotificationsApiError, y as NotificationsDb, z as NotificationsDbClient, B as NotificationsDbProvider, D as NotificationsRequest, F as NotificationsResponse, b as NotificationsRoute, N as NotificationsServerConfig, G as NotifyByPermission, H as NotifyOptions, I as NotifyResult, P as PermissionNotificationResult, J as PermissionNotificationSkip, K as PushSubscriptionDelegate, M as PushSubscriptionInput, O as PushSubscriptionRow, Q as PushSubscriptionStore, S as SMS_DRIVERS, R as SmsDriver, T as SmsDriverDeclaration, U as SmsMessage, V as TransportDeclaration, W as TransportRegistry, X as WHATSAPP_DRIVERS, Y as WhatsAppDriver, Z as WhatsAppDriverDeclaration, _ as WhatsAppMessage, $ as createApiNotifications, a0 as createTransportRegistry, a1 as emailTransport, a2 as foldApiError, a3 as formatEmail, a4 as formatSms, a5 as formatWhatsApp, a6 as ok, a7 as smsTransport, a8 as whatsAppTransport } from '../create-api-notifications-WaexrZnn.js';
-export { D as DriverDeclarationBase, F as FetchImpl, N as NotificationProviderError, W as WEB_PUSH_DRIVERS, a as WebPushDriverDeclaration, b as WebPushMessage, c as WebPushSender, d as WebPushSubscription, e as WebPushSubscriptionSource, f as absoluteLink, g as formatWebPush, w as webPushTransport } from '../web-push-iER5StBm.js';
+import { A as ApiNotifications } from '../create-api-notifications-CcPYrM3p.js';
+export { C as CommittedNotification, E as EMAIL_DRIVERS, c as EmailDriver, d as EmailDriverDeclaration, e as EmailMessage, f as ExtraDrivers, L as ListNotificationsInput, g as NotificationAudienceDirectory, h as NotificationChannelPolicy, i as NotificationCommittedListener, j as NotificationContactDirectory, k as NotificationCreateData, l as NotificationDelegate, m as NotificationDeliveryDelegate, n as NotificationDeliveryRow, o as NotificationDeliveryWhere, p as NotificationDispatchScheduler, q as NotificationInboxStore, r as NotificationPageAfter, s as NotificationPreferenceDelegate, t as NotificationPreferenceRow, u as NotificationPreferenceStore, v as NotificationRouter, w as NotificationWhere, a as NotificationsActor, x as NotificationsApiError, y as NotificationsDb, z as NotificationsDbClient, B as NotificationsDbProvider, D as NotificationsRequest, F as NotificationsResponse, b as NotificationsRoute, N as NotificationsServerConfig, G as NotifyByPermission, H as NotifyOptions, I as NotifyResult, P as PermissionNotificationResult, J as PermissionNotificationSkip, K as PushSubscriptionDelegate, M as PushSubscriptionInput, O as PushSubscriptionRow, Q as PushSubscriptionStore, S as SMS_DRIVERS, R as SmsDriver, T as SmsDriverDeclaration, U as SmsMessage, V as TransportDeclaration, W as TransportRegistry, X as WHATSAPP_DRIVERS, Y as WhatsAppDriver, Z as WhatsAppDriverDeclaration, _ as WhatsAppMessage, $ as createApiNotifications, a0 as createTransportRegistry, a1 as emailTransport, a2 as foldApiError, a3 as formatEmail, a4 as formatSms, a5 as formatWhatsApp, a6 as ok, a7 as smsTransport, a8 as whatsAppTransport } from '../create-api-notifications-CcPYrM3p.js';
+export { D as DriverDeclarationBase, F as FetchImpl, N as NotificationProviderError, W as WEB_PUSH_DRIVERS, a as WebPushDriverDeclaration, b as WebPushMessage, c as WebPushSender, d as WebPushSubscription, e as WebPushSubscriptionSource, f as absoluteLink, g as formatWebPush, w as webPushTransport } from '../web-push-Dnyaha2z.js';
 import { NotifyPort } from '@12-apps/wiring/ports';
-export { a as NOTIFICATIONS_DRAIN_CRON, b as NOTIFICATIONS_DRAIN_LEASE_MS, c as NOTIFICATIONS_JOBS, d as NOTIFICATIONS_SWEEP_QUEUE, N as NotificationsJobDeps } from '../jobs-CcsSA0YR.js';
-import '../generators-CH5m8Ucj.js';
-import '../types-CYJN1xCM.js';
-import '../wire-CmRrB3_s.js';
+export { a as NOTIFICATIONS_DRAIN_CRON, b as NOTIFICATIONS_DRAIN_LEASE_MS, c as NOTIFICATIONS_JOBS, d as NOTIFICATIONS_SWEEP_QUEUE, N as NotificationsJobDeps } from '../jobs--fex87-q.js';
+import '../generators-qAD4fNPq.js';
+import '../types-BlqZkCWZ.js';
+import '../wire-BG1kuoXX.js';
+import '../template-Dlt5S54z.js';
 import '@12-apps/wiring';
 
 /**

package/dist/server/index.js

@@ -4,7 +4,7 @@ import {
   NOTIFICATIONS_JOBS,
   NOTIFICATIONS_SWEEP_QUEUE,
   wireNotifyPort
-} from "../chunk-KU4FVOFA.js";
+} from "../chunk-ZIR3ILFH.js";
 import {
   EMAIL_DRIVERS,
   NotificationProviderError,
@@ -25,10 +25,12 @@ import {
   smsTransport,
   webPushTransport,
   whatsAppTransport
-} from "../chunk-7234ROOP.js";
-import "../chunk-GGAZOLNN.js";
-import "../chunk-BGI4BQ66.js";
+} from "../chunk-WVRODNXQ.js";
+import "../chunk-SWOWHIFE.js";
 import "../chunk-M2TVBVH2.js";
+import "../chunk-RTURLH5U.js";
+import "../chunk-6W7INOYQ.js";
+import "../chunk-EKUSNUBT.js";
 import "../chunk-7QVYU63E.js";
 export {
   EMAIL_DRIVERS,

package/dist/template-Dlt5S54z.d.ts

@@ -0,0 +1,196 @@
+/**
+ * The layout's design tokens — the nine colours a mail is drawn from.
+ *
+ * ## Why a theme is a VALUE here and copy is required config
+ *
+ * The copy-portability doctrine is that a package ships no user-facing
+ * sentences: a default in the origin host's language reads as finished to the
+ * next host right up until somebody's customer gets mail in a language they do
+ * not speak. Colour is not that. {@link NEUTRAL_EMAIL_THEME} is not anybody's
+ * brand — it is grey on white, which reads as *unstyled but tidy* rather than
+ * as *somebody else's product*. A host that passes nothing gets a mail that
+ * looks plain, not a mail that looks like a different company.
+ *
+ * So this one has a default and the copy does not, and the difference is
+ * exactly whether getting it wrong is invisible. A missing theme is visible in
+ * the first preview; a wrong-language default is invisible until a customer
+ * complains.
+ *
+ * ## What a host should know before overriding it
+ *
+ * Two rungs of most brand palettes cannot carry light text, and a mail has no
+ * theme to fall back on when a client ignores a colour. {@link accent} is the
+ * one that MUST clear 4.5:1 against white — it is the CTA fill and every link.
+ * A warm mid-tone that looks fine on a screen at 2.6:1 is unreadable in an
+ * inbox, and nothing in the pipeline will say so.
+ */
+interface EmailTheme {
+    /** The page behind the card. Never pure white: a white card needs a ground. */
+    readonly page: string;
+    /** The card itself. */
+    readonly surface: string;
+    /** A quieter panel inside the card — the facts table. */
+    readonly panel: string;
+    /** Every hairline. */
+    readonly border: string;
+    /** Body text. */
+    readonly ink: string;
+    /** Secondary text: the footer, the fallback link, a fact's label. */
+    readonly muted: string;
+    /** The action colour — the CTA fill and every link. Must clear 4.5:1 on white. */
+    readonly accent: string;
+    /** Ink ON {@link accent}. */
+    readonly onAccent: string;
+    /** The rule under the wordmark. Decorative — nothing is written on it. */
+    readonly rule: string;
+}
+/**
+ * A brand-free default: greys, one blue, nothing anybody would mistake for a
+ * product. Every value clears its contrast requirement against its own ground.
+ */
+declare const NEUTRAL_EMAIL_THEME: EmailTheme;
+/**
+ * The font stack, as one string.
+ *
+ * System fonts only, and no web font: a `@font-face` is stripped by Gmail and
+ * by Outlook, so a mail that depends on one renders in whatever the client
+ * substitutes — never the fallback the designer chose. The stack ends in the
+ * emoji faces so a status glyph in a subject line does not drop to a tofu box
+ * on Windows.
+ */
+declare const EMAIL_FONT_STACK = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'";
+/** The card's width. 600px is the width every client lays out without scroll. */
+declare const EMAIL_CONTENT_WIDTH = 600;
+
+/**
+ * THE transactional-mail layout: one document model, one HTML renderer, one
+ * plain-text twin.
+ *
+ * ## The problem it exists for
+ *
+ * A host that sends mail from more than one place ends up rendering it in more
+ * than one way — the notification pipeline emits a bold paragraph and a bare
+ * anchor, the sign-in flow emits a `div` with a max-width, the receipt builds
+ * its own list — and each grows its own `escapeHtml` and its own text twin. The
+ * three look like three different products, because a paragraph with no
+ * document around it inherits whatever the client decides: 13px Arial in Gmail,
+ * Times New Roman in Outlook, no centring anywhere.
+ *
+ * That is a LAYOUT problem rather than a wording one, which is what makes it a
+ * package's to solve. The words stay the host's; the document does not.
+ *
+ * ## Why the document is a MODEL and not a string
+ *
+ * Every caller hands over structure — a heading, some paragraphs, an optional
+ * facts table, at most one call to action — and never markup. Three things fall
+ * out of that, and each is a real defect in the hand-rolled renderers this
+ * replaces:
+ *
+ * 1. **Escaping cannot be forgotten.** Every field is escaped here, once. Of
+ *    the three renderers this was extracted from, two escaped the body and
+ *    interpolated the LINK raw.
+ * 2. **The plain-text twin cannot drift.** Both halves render from the same
+ *    object, so a line added to one is in the other. A `text/html` part with no
+ *    `text/plain` twin is scored by every major spam filter, and it is what a
+ *    watch, a terminal client and a screen reader in plain-text mode show.
+ * 3. **A preview is honest.** `./server`'s catalogue renders exactly this, from
+ *    exactly these inputs, so a preview cannot be right about a mail nobody
+ *    gets.
+ *
+ * ## The client constraints this encodes
+ *
+ * Stated once here, so no caller has to know them:
+ *
+ * - **Tables, not divs.** Outlook 2016+ on Windows lays HTML out with Word,
+ *   which supports no `flex`, no `grid` and no reliable `max-width` on a block.
+ *   A centred 600px table is the one construction every client agrees on.
+ * - **Inline styles.** Gmail strips `<style>` from the document it renders in
+ *   several contexts, and always in the Gmail app for a non-Gmail account. The
+ *   `<style>` block below therefore carries only the mobile media query —
+ *   progressive enhancement, never anything the layout depends on.
+ * - **No web fonts, no `color-mix()`, no CSS variables.** See `./theme`.
+ * - **A preheader.** The inbox list shows the first text in the body after the
+ *   subject; without one it shows the footer's legal line.
+ * - **`role="presentation"`** on every layout table, so a screen reader reads
+ *   the message rather than announcing a five-column grid.
+ */
+/** The words the LAYOUT itself needs — never the message's own sentences. */
+interface EmailChromeCopy {
+    /** "If the button does not work, paste this address into your browser:" */
+    readonly fallbackHint: string;
+    /** "This is an automated message — please do not reply." */
+    readonly automated: string;
+    /** The footer's one line about the product, given the brand name. */
+    readonly tagline: (brand: string) => string;
+}
+/** The one call to action a message may carry. More than one dilutes both. */
+interface EmailAction {
+    readonly label: string;
+    readonly href: string;
+}
+/** One row of the facts panel — a receipt's total, an order's reference. */
+interface EmailFact {
+    readonly label: string;
+    readonly value: string;
+    /** Renders bolder and larger — the one number the reader came for. */
+    readonly emphasis?: boolean;
+}
+/** Everything a message says, with no opinion about how it looks. */
+interface EmailDocument {
+    /** The subject line. Also the document `<title>`. */
+    readonly subject: string;
+    /**
+     * The inbox-list preview, ~90 chars. Falls back to the first paragraph,
+     * which is right far more often than it is wrong.
+     */
+    readonly preheader?: string;
+    /** The `<h1>`. Usually a restatement of the subject in the reader's terms. */
+    readonly heading: string;
+    /** The body, one entry per paragraph. Plain sentences — never markup. */
+    readonly paragraphs?: readonly string[];
+    /** An optional label/value panel under the body. */
+    readonly facts?: readonly EmailFact[];
+    /** At most one CTA. */
+    readonly action?: EmailAction;
+    /** Small print under the CTA — a deadline, a "you can ignore this". */
+    readonly notes?: readonly string[];
+    /**
+     * The layout's own words, in the recipient's language.
+     *
+     * REQUIRED, with no default in any language — the copy-portability doctrine.
+     * `@12-apps/notifications/email/locales` ships a pack per language and a host
+     * passes one BY
+     * NAME, which is a decision rather than a silence.
+     */
+    readonly chrome: EmailChromeCopy;
+    /**
+     * The product name in the header and the footer. REQUIRED: a package that
+     * defaulted this would sign another company's mail.
+     */
+    readonly brand: string;
+    /** The recipient's language, for the document's `lang` attribute. */
+    readonly locale: string;
+    /** Defaults to {@link NEUTRAL_EMAIL_THEME} — see `./theme` for why this one may. */
+    readonly theme?: EmailTheme;
+}
+/** A URL as an attribute value, or `#` when it is not one this layout will emit. */
+declare function safeHref(href: string): string;
+/**
+ * Render the document as the HTML half of the message.
+ *
+ * A complete document rather than a fragment: a `<!DOCTYPE>` is what puts
+ * Outlook into standards mode, and `x-apple-disable-message-reformatting` is
+ * what stops iOS Mail re-flowing the card to the screen width and shrinking the
+ * type with it.
+ */
+declare function renderEmailHtml(document: EmailDocument): string;
+/** Both halves plus the subject — what every driver in this repo is handed. */
+interface RenderedEmail {
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+}
+/** Render one document into the message shape `EmailDriver.send` takes. */
+declare function renderEmail(document: EmailDocument): RenderedEmail;
+
+export { type EmailDocument as E, NEUTRAL_EMAIL_THEME as N, type RenderedEmail as R, EMAIL_CONTENT_WIDTH as a, EMAIL_FONT_STACK as b, type EmailAction as c, type EmailChromeCopy as d, type EmailFact as e, type EmailTheme as f, renderEmailHtml as g, renderEmail as r, safeHref as s };

package/dist/{types-CYJN1xCM.d.ts → types-BlqZkCWZ.d.ts}

@@ -60,7 +60,16 @@ interface NotificationContent {
     body: string;
     /** In-app deep link (a same-origin path such as `/orders/123`). */
     link?: string;
-    /** Structured extras for consumers that want more than text. */
+    /**
+     * Structured extras for consumers that want more than text.
+     *
+     * ONE KEY IS RESERVED: `liveSubject` (`LIVE_SUBJECT_KEY` in `./live`) ties
+     * this notification to a live activity, and the WEB_PUSH transport turns it
+     * into the tray `tag` that collapses every push about one subject onto a
+     * single entry. A host already using that name for something else acquires
+     * that behaviour without asking for it — so it is named here, on the field a
+     * generator actually writes, and not only where the feature is documented.
+     */
     data?: Record<string, unknown>;
 }
 /** Who receives a notification. `clientId` scopes it to a tenant when set. */
@@ -189,4 +198,4 @@ interface NotificationLogger {
     error(message: string, ...meta: unknown[]): void;
 }
 
-export { type DeliveryStatus as D, NOTIFICATION_CHANNELS as N, type TransportRecipient as T, type NotificationCategory as a, type NotificationChannel as b, type NotificationContent as c, type NotificationEvent as d, type NotificationGenerateContext as e, type NotificationGenerator as f, type NotificationLogger as g, type NotificationRecipient as h, type NotificationTaxonomy as i, type NotificationTransport as j, taxonomyOf as t };
+export { type DeliveryStatus as D, type NotificationGenerator as N, type TransportRecipient as T, NOTIFICATION_CHANNELS as a, type NotificationCategory as b, type NotificationChannel as c, type NotificationContent as d, type NotificationEvent as e, type NotificationGenerateContext as f, type NotificationLogger as g, type NotificationRecipient as h, type NotificationTaxonomy as i, type NotificationTransport as j, taxonomyOf as t };

package/dist/web-push/index.d.ts

@@ -1,5 +1,5 @@
-import { c as WebPushSender } from '../web-push-iER5StBm.js';
-import '../types-CYJN1xCM.js';
+import { c as WebPushSender } from '../web-push-Dnyaha2z.js';
+import '../types-BlqZkCWZ.js';
 
 /**
  * `@12-apps/notifications/web-push` — the VAPID sender, behind its own subpath.

package/dist/{web-push-iER5StBm.d.ts → web-push-Dnyaha2z.d.ts}

@@ -1,4 +1,4 @@
-import { g as NotificationLogger, c as NotificationContent, j as NotificationTransport } from './types-CYJN1xCM.js';
+import { g as NotificationLogger, d as NotificationContent, j as NotificationTransport } from './types-BlqZkCWZ.js';
 
 /**
  * The DRIVER port — the reason a host adds a vendor with a config entry and no
@@ -98,6 +98,26 @@ interface WebPushMessage {
     body: string;
     link: string | null;
     data: Record<string, unknown>;
+    /**
+     * The OS tray tag, or `null` for an ordinary event.
+     *
+     * Present for a notification about a LIVE SUBJECT (see `../../live`), and
+     * this is the whole of the live feature's reach onto a locked phone: a tag
+     * makes the next push about the same subject REPLACE the one already in the
+     * tray — silently — instead of stacking under it. Four stages then cost one
+     * entry and one buzz, and the entry that remains is the current one.
+     *
+     * {@link formatWebPush} always sets it, `null` included, so on the WIRE the
+     * key is always there and a service worker reads one shape. A worker that
+     * ignores it keeps today's behaviour exactly, which is what makes this safe
+     * to ship ahead of the workers.
+     *
+     * OPTIONAL in the type, and only in the type: a host that hand-writes its own
+     * `NotificationTransport<WebPushMessage>` — a fixture, a second driver —
+     * would otherwise stop compiling on a field it has no way to know about and
+     * no reason to set.
+     */
+    tag?: string | null;
 }
 interface WebPushDriverDeclaration extends DriverDeclarationBase {
     channel: 'WEB_PUSH';

package/dist/{wire-CmRrB3_s.d.ts → wire-BG1kuoXX.d.ts}

@@ -1,4 +1,4 @@
-import { a as NotificationCategory, b as NotificationChannel } from './types-CYJN1xCM.js';
+import { b as NotificationCategory, c as NotificationChannel } from './types-BlqZkCWZ.js';
 
 /**
  * Every sentence this package can say to a USER, stated by the HOST.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/notifications",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "type": "module",
   "sideEffects": false,
   "description": "Plug-and-play notification system (12-15): an always-on in-app inbox, per-user × per-category channel preferences, and email / SMS / WhatsApp / web-push transports behind vendor DRIVERS so a second provider is a config entry. Framework-free core (.), host-mounted backend surface (./server: inbox / preferences / push-subscription endpoints, the channel router with delivery records + retry sweep, the permission fan-out, duck-typed Prisma seam), Hono adapter (./hono), React surface (./react: bell + badge, inbox drawer, preferences screen), VAPID sender (./web-push) and the package-owned Prisma partial + migrations. Standardized adoption contract in ADOPTING.md.",
@@ -9,6 +9,26 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./email": {
+      "types": "./dist/email/index.d.ts",
+      "default": "./dist/email/index.js"
+    },
+    "./email/locales": {
+      "types": "./dist/email/locales.d.ts",
+      "default": "./dist/email/locales.js"
+    },
+    "./email/previews": {
+      "types": "./dist/email/previews/index.d.ts",
+      "default": "./dist/email/previews/index.js"
+    },
+    "./email/previews/hono": {
+      "types": "./dist/email/previews/hono.d.ts",
+      "default": "./dist/email/previews/hono.js"
+    },
+    "./email/previews/react": {
+      "types": "./dist/email/previews/react/index.d.ts",
+      "default": "./dist/email/previews/react/index.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "default": "./dist/server/index.js"
@@ -51,7 +71,7 @@
     "prisma:sync:check": "node scripts/sync-notifications-schema.mjs --check"
   },
   "dependencies": {
-    "@12-apps/ui": "^6.11.1"
+    "@12-apps/ui": "^6.17.0"
   },
   "peerDependencies": {
     "@12-apps/wiring": ">=1.3.0",

package/src/email/chrome.en-US.ts

@@ -0,0 +1,8 @@
+import type { EmailChromeCopy } from './template';
+
+/** US English — the twin that makes {@link PT_BR_EMAIL_CHROME} a choice. */
+export const EN_US_EMAIL_CHROME: EmailChromeCopy = {
+  fallbackHint: 'If the button above does not work, copy and paste this address into your browser:',
+  automated: 'This is an automated message. Please do not reply to this email.',
+  tagline: (brand) => `Sent by ${brand}.`,
+};

package/src/email/chrome.pt-BR.ts

@@ -0,0 +1,21 @@
+import type { EmailChromeCopy } from './template';
+
+/**
+ * Brazilian Portuguese, as a NAMED pack.
+ *
+ * A host passes this by name — `chrome: PT_BR_EMAIL_CHROME`, or
+ * `localeCopy(EMAIL_CHROME)` for a host whose readers do not share one
+ * language. It is never a default: a pack a host CHOOSES is a decision in a
+ * diff, and a pack a package applies silently is another product's voice in
+ * somebody's inbox.
+ *
+ * The tagline names the brand and stops. It is deliberately not a description
+ * of what the product does — that sentence is the host's, it belongs to a
+ * vocabulary this package cannot know, and a package that guessed one would be
+ * putting words in every adopter's footer.
+ */
+export const PT_BR_EMAIL_CHROME: EmailChromeCopy = {
+  fallbackHint: 'Se o botão acima não funcionar, copie e cole este endereço no seu navegador:',
+  automated: 'Esta é uma mensagem automática. Não responda a este e-mail.',
+  tagline: (brand) => `Enviado por ${brand}.`,
+};