@mohasinac/appkit 4.69.1 → 4.71.0

package/dist/constants/storage-keys.js

@@ -0,0 +1,119 @@
+/**
+ * Browser-storage and postMessage keys — one namespace, configurable.
+ *
+ * ## Why this exists
+ *
+ * Seven call sites hardcoded a `letitrip`-prefixed key:
+ *
+ *   localStorage  "letitrip:section-state" · "letitrip:last-category"
+ *                 "letitrip:announcement-dismissed" · "letitrip_oauth_redirect"
+ *                 "letitrip_search_type"
+ *   postMessage   "letitrip_auth_close"
+ *
+ * For the app that shipped them that is harmless. For a LIBRARY it is not:
+ * every consumer inherits one marketplace's namespace, two appkit apps on the
+ * same origin collide, and the brand is baked into data the user's browser
+ * keeps. Tier AK's whole premise is that appkit should not know whose app it
+ * is in.
+ *
+ * ## 🛑 The prefix is read at CALL TIME, not at module load
+ *
+ * `storageKey()` is a function and the keys below are getters. A consumer sets
+ * the namespace from its own bootstrap, which runs after this module is
+ * evaluated — so a `const KEY = PREFIX + ":x"` captured at import time would
+ * freeze the default and silently ignore the configuration. That is the same
+ * trap as a mirror field (Root Cause #42): two things that must agree, where
+ * only one is ever written.
+ *
+ * ## 🛑 Changing the namespace ORPHANS existing values
+ *
+ * These keys are how a returning visitor's dismissed banner and collapsed
+ * sections are remembered. Renaming the prefix does not migrate them — the old
+ * entries simply stop being read. That is acceptable for UI state and would NOT
+ * be for anything load-bearing, which is why nothing load-bearing belongs here:
+ * the auth session is an HTTP-only cookie, not a storage key.
+ *
+ * ## The separator is deliberately NOT normalised
+ *
+ * Five keys use `:` and three use `_`. They are kept exactly as they were,
+ * because normalising them is a silent data migration for every existing
+ * visitor in exchange for tidiness. New keys should use `:`.
+ */
+/**
+ * Default namespace.
+ *
+ * Deliberately NOT "letitrip" — a library's default must not name one
+ * consumer. `"appkit"` is what an unconfigured install gets, which is both
+ * neutral and obviously-a-default when seen in devtools.
+ */
+const DEFAULT_STORAGE_NAMESPACE = "appkit";
+let namespace = DEFAULT_STORAGE_NAMESPACE;
+/**
+ * Set the prefix every appkit storage key carries. Call once, from the
+ * consumer's client bootstrap, before any UI mounts.
+ *
+ * Idempotent and last-call-wins; there is no unset, because a namespace that
+ * changes mid-session would strand whatever was written under the previous one.
+ */
+export function setStorageNamespace(value) {
+    const trimmed = value.trim();
+    if (trimmed)
+        namespace = trimmed;
+}
+/** The active namespace. Exported for diagnostics, not for building keys. */
+export function getStorageNamespace() {
+    return namespace;
+}
+/**
+ * Build a namespaced key.
+ *
+ * @param suffix the part after the separator, e.g. `"last-category"`
+ * @param separator `":"` for new keys; `"_"` only where an existing key used it
+ */
+export function storageKey(suffix, separator = ":") {
+    return `${namespace}${separator}${suffix}`;
+}
+/**
+ * The keys appkit itself owns.
+ *
+ * Getters, not constants — see the call-time note above. Each records the
+ * literal it replaced so the migration is auditable and a reader can tell at a
+ * glance which separator is historical rather than chosen.
+ */
+export const STORAGE_KEYS = {
+    /** Collapsed account-page sections. Was `"letitrip:section-state"`. */
+    get sectionState() {
+        return storageKey("section-state");
+    },
+    /** Last category visited, for the contextual trail. Was `"letitrip:last-category"`. */
+    get lastCategory() {
+        return storageKey("last-category");
+    },
+    /** Announcement bar dismissal. Was `"letitrip:announcement-dismissed"`. */
+    get announcementDismissed() {
+        return storageKey("announcement-dismissed");
+    },
+    /** OAuth return URL across the popup round-trip. Was `"letitrip_oauth_redirect"`. */
+    get oauthRedirect() {
+        return storageKey("oauth_redirect", "_");
+    },
+    /** Remembered search-type tab. Was `"letitrip_search_type"`. */
+    get searchType() {
+        return storageKey("search_type", "_");
+    },
+};
+/**
+ * postMessage `type` values.
+ *
+ * 🛑 Namespaced for the same reason, and with a sharper edge: a `message`
+ * listener receives events from ANY window that can reach it, so an
+ * unnamespaced type is both a collision and an input-validation question. The
+ * listeners that read this must keep checking `event.origin` regardless — a
+ * namespace is not an authentication mechanism.
+ */
+export const MESSAGE_TYPES = {
+    /** Auth popup signalling it is done. Was `"letitrip_auth_close"`. */
+    get authClose() {
+        return storageKey("auth_close", "_");
+    },
+};

package/dist/contracts/index.d.ts

@@ -2,7 +2,7 @@ export type { WhereOp, SieveQuery, PagedResult, IReadRepository, IWriteRepositor
 export type { AuthPayload, AuthUser, CreateUserInput, IAuthProvider, ISessionProvider, } from "./auth";
 export type { EmailAttachment, EmailOptions, EmailResult, IEmailProvider, } from "./email";
 export type { UploadOptions, StorageFile, IStorageProvider } from "./storage";
-export type { PaymentOrder, PaymentCapture, Refund, Dispute, GatewayPaymentRecord, } from "./payment";
+export type { CheckoutIntentMetadata, PaymentOrder, PaymentCapture, Refund, Dispute, GatewayPaymentRecord, } from "./payment";
 export { IPaymentProvider } from "./payment";
 export type { ShippingAddress, CreateShipmentInput, Shipment, TrackingEvent, TrackingInfo, ServiceabilityResult, WalletBalance, } from "./shipping";
 export { IShippingProvider } from "./shipping";

package/dist/contracts/payment.d.ts

@@ -17,6 +17,23 @@ export interface PaymentOrder {
     /** When this order/attempt expires, if the gateway reports one (PhonePe's `expireAt`). ISO-8601. */
     expiresAt?: string;
 }
+/**
+ * What the buyer was checking out, round-tripped through the gateway's own
+ * metadata so the confirmation path can rebuild the order.
+ *
+ * 🛑 This lived in `providers/payment-phonepe/index.ts` as
+ * `PhonePeCheckoutIntent`, and the name was the only gateway-shaped thing about
+ * it — every field is OURS. That naming forced generic checkout code to import
+ * a concrete provider for a type, which is the coupling Tier AK A4 exists to
+ * remove. PhonePe happens to carry it in `udf1..udf4`; another gateway would
+ * carry it some other way, and neither fact belongs in the type's name.
+ */
+export interface CheckoutIntentMetadata {
+    uid: string;
+    addressId?: string;
+    outOfStockPolicy?: string;
+    notes?: string;
+}
 export interface PaymentCapture {
     id: string;
     orderId: string;
@@ -146,6 +163,31 @@ export declare abstract class IPaymentProvider {
     abstract createOrder(amount: number, currency: string, metadata?: Record<string, JsonValue>): Promise<PaymentOrder>;
     /** Returns true if the webhook signature is valid. */
     abstract verifyWebhook(payload: string, signature: string): boolean;
+    /**
+     * Verify the BUYER-PRESENT checkout callback — a different exchange from a
+     * webhook, which is why `verifyWebhook` cannot serve it.
+     *
+     * A webhook is server-to-server and signed over a raw body. This is the
+     * redirect/callback the buyer's own browser hands back after paying
+     * (Razorpay's `razorpay_order_id` + `razorpay_payment_id` +
+     * `razorpay_signature`). Until this existed, generic checkout code imported
+     * Razorpay's verifier directly — a concrete gateway named in the one place
+     * that must work for every gateway.
+     *
+     * 🛑 MUST FAIL CLOSED. A gateway with no such handshake returns `false`, not
+     * `true`: this call is what decides whether a payment is genuine, so the
+     * default for "I cannot verify this" is rejection. Returning `true` would
+     * accept a forged callback.
+     *
+     * 🛑 The SECRET stays the caller's to resolve, deliberately. The call site
+     * already reads it from settings and fails closed when absent; moving that
+     * inside would change which code holds the key and what happens when it is
+     * missing, which is a bigger change than the dispatch this method is for.
+     *
+     * @param payload the gateway's callback fields, shape-checked by the provider
+     * @param secret  the key secret, resolved by the caller
+     */
+    abstract verifyCheckoutSignature(payload: Record<string, string>, secret: string): boolean;
     abstract capturePayment(orderId: string): Promise<PaymentCapture>;
     abstract refund(paymentId: string, amount?: number): Promise<Refund>;
     abstract getOrder(orderId: string): Promise<PaymentOrder>;

package/dist/contracts/registry.d.ts

@@ -3,6 +3,7 @@ import type { IEmailProvider } from "./email";
 import type { IStorageProvider } from "./storage";
 import type { IPaymentProvider } from "./payment";
 import type { IShippingProvider } from "./shipping";
+import type { ITaxProvider } from "./tax";
 import type { ISearchProvider } from "./search";
 import type { ICacheProvider, IQueueProvider, IEventBus } from "./infra";
 import type { IStyleAdapter } from "./style";
@@ -22,6 +23,13 @@ export interface ProviderRegistry {
     db?: IDbProvider;
     payment?: IPaymentProvider;
     shipping?: IShippingProvider;
+    /**
+     * Jurisdiction tax engine. Optional, and defaults to India GST at the call
+     * site rather than here — an install that never registers one keeps today's
+     * behaviour exactly, which is what makes adopting the seam safe one caller at
+     * a time instead of in a single 42-file sweep.
+     */
+    tax?: ITaxProvider;
     search?: ISearchProvider;
     cache?: ICacheProvider;
     queue?: IQueueProvider;

package/dist/contracts/tax.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The tax seam. Tier AK A3.
+ *
+ * ## Why this exists
+ *
+ * `gstRate`, `hsnCode` and `placeOfSupply` are read across 42 files, and
+ * CGST/SGST/IGST is an Indian GST concept — so appkit shipped an *Indian*
+ * ecommerce tax model rather than a tax model. A buyer of this package selling
+ * in the EU needs VAT with a reverse charge; in the US, destination sales tax
+ * with nexus. Neither is expressible as "split the rate in half when the states
+ * match".
+ *
+ * ## 🛑 The FIELDS DO NOT MOVE, and this is the whole reason the phase is cheap
+ *
+ * `gstRate` / `hsnCode` / `placeOfSupply` stay exactly where they are on
+ * `ProductDocument` and `OrderDocument`. They become the India provider's
+ * PAYLOAD rather than appkit's universal schema. That buys the seam with:
+ *
+ *   · no Firestore migration, so no stored document becomes wrong (Rule #3)
+ *   · no change to any index or query
+ *   · nothing to roll back if a buyer never needs a second jurisdiction
+ *
+ * A schema migration was the first plan and it was the wrong one: the goal is
+ * that appkit does not *compute* one country's tax, not that it forgets the
+ * country exists.
+ *
+ * ## 🛑 Implementations DELEGATE. They do not reimplement.
+ *
+ * `IndiaGstTaxProvider` calls the existing `calculateGst` /
+ * `calculateGstInclusive` / `allocateAcrossMembers`. It is a seam, not a
+ * rewrite — and that is deliberate, because the two existing functions split
+ * the half DIFFERENTLY and the difference is load-bearing:
+ *
+ *   calculateGst           cgst = sgst = round(gst / 2), gst RE-DERIVED as half*2
+ *   calculateGstInclusive  cgst = round(gst / 2), sgst = round(gst - cgst)
+ *
+ * On ₹66.67 at 18% inclusive that is cgst 5.09 / sgst 5.08, preserving the
+ * 10.17 total. A reimplementation that "tidied" the two into agreement would
+ * move a paisa on real invoices, and GST is filed on those figures.
+ *
+ * The gate for this phase is `.build-memory/tax-roundtrip.mjs`: 397 breakdowns
+ * across every slab, both supply directions and the rounding edges, required to
+ * be byte-identical before and after. One paisa of drift is a defect.
+ */
+/** A single tax component on a line, named by the jurisdiction's own vocabulary. */
+export interface TaxComponent {
+    /** `"cgst"`, `"sgst"`, `"igst"`, `"vat"`, `"salesTax"` — the provider's term. */
+    code: string;
+    /** Human label for an invoice line. */
+    label: string;
+    /** Percentage applied, e.g. `9` for half of an 18% intra-state GST. */
+    rate: number;
+    /** Money, in MAJOR currency units — `1.50`, never a minor-unit `150`. */
+    amount: number;
+}
+/**
+ * The result of taxing one amount.
+ *
+ * `components` sums to `taxAmount` exactly — providers are responsible for
+ * assigning any rounding remainder to one component rather than letting the
+ * parts disagree with the total.
+ */
+export interface TaxBreakdown {
+    /** The amount tax was computed ON (ex-tax base). */
+    taxableAmount: number;
+    /** Total tax. Equals the sum of `components`. */
+    taxAmount: number;
+    components: TaxComponent[];
+}
+/**
+ * Where a sale happens, in the only terms a tax engine actually needs.
+ *
+ * Deliberately NOT `placeOfSupply: string`. That is India's word for the
+ * destination state code, and naming the contract after it would re-import the
+ * jurisdiction this interface exists to abstract.
+ */
+export interface TaxJurisdiction {
+    /** Seller's region code — an Indian state code, a US state, an EU country. */
+    origin?: string;
+    /** Buyer's region code. */
+    destination?: string;
+    /** ISO 3166-1 alpha-2, when a provider needs to distinguish cross-border. */
+    country?: string;
+}
+/** What is being taxed. `taxCode` is the jurisdiction's classification (HSN, SIC, …). */
+export interface TaxableItem {
+    /** Rate as a percentage, e.g. `18`. Resolved by the caller from its own data. */
+    rate: number;
+    /** Jurisdiction classification code — India's HSN, and whatever elsewhere. */
+    taxCode?: string;
+}
+export declare abstract class ITaxProvider {
+    /** Stable id, e.g. `"india-gst"`. */
+    abstract readonly id: string;
+    /**
+     * Tax ADDED to an ex-tax amount.
+     *
+     * @param taxableAmount the ex-tax base, in major units
+     */
+    abstract onExclusive(item: TaxableItem, jurisdiction: TaxJurisdiction, taxableAmount: number): TaxBreakdown;
+    /**
+     * Tax EXTRACTED from a tax-inclusive amount.
+     *
+     * 🛑 Not derivable from `onExclusive` by the caller. Backing out of a gross
+     * figure and adding onto a net one round differently, and this codebase
+     * already relies on the difference — see the class docstring.
+     *
+     * @param gross the tax-inclusive total, in major units
+     */
+    abstract onInclusive(item: TaxableItem, jurisdiction: TaxJurisdiction, gross: number): TaxBreakdown;
+    /**
+     * Is this sale taxed as same-region? India splits CGST/SGST when it is and
+     * charges IGST when it is not; other jurisdictions may ignore the question
+     * entirely, which is why it is the provider's to answer and not a caller's
+     * boolean to pass around.
+     */
+    abstract isSameRegion(jurisdiction: TaxJurisdiction): boolean;
+}

package/dist/contracts/tax.js

@@ -0,0 +1,3 @@
+// --- Tax Shared Types ---------------------------------------------------------
+export class ITaxProvider {
+}

package/dist/core/brand-resolver.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The consumer's brand identity, injected once at boot.
+ *
+ * ── Why this seam exists ──────────────────────────────────────────────────
+ *
+ * `appkit.config.js → brand` is the consumer-owned owner of the site's name,
+ * short name and TLD. appkit has no runtime reader for a consumer config file,
+ * so — exactly as `supplier-of-record.ts` does for the statutory identity, and
+ * `baseline-resolver.ts` for currency and locale — the consumer injects it.
+ *
+ * Measured 2026-10-29, this was the FIFTH owner problem that
+ * `supplier-of-record.ts` was written to end, one field over. `brand.name` is
+ * `"LetItRip"`, but five appkit modules read `NEXT_PUBLIC_SITE_NAME` directly
+ * with five DIFFERENT fallbacks (`"LetItRip"`, `"App"`, `"App"`, `""`, and a
+ * comment), and that env var holds `"Let It Rip India"` — which is
+ * `brand.heroCaption`, not the brand name. So the checkout value-OTP message
+ * and the JSON-LD `publisher` both named the site something the brand owner
+ * does not call it, while `SiteLogo` drew a third spelling.
+ *
+ * `seo/json-ld.ts:408` already records the previous round of this:
+ * "Production had NEXT_PUBLIC_SITE_NAME='Letitrip' — the wrong casing". The
+ * env var is not the owner; it never was.
+ *
+ * ── 🛑 The defaults here are NEUTRAL, and that asymmetry is deliberate ─────
+ *
+ * `baseline-resolver.ts`'s BASELINE is documented as matching letitrip.in
+ * ("INR / en-IN / IN / +91 / Asia/Kolkata") and that is defensible: a wrong
+ * currency is visible in the first rendered price, so an unconfigured install
+ * discovers it immediately.
+ *
+ * A wrong brand name is not. It renders plausibly, reads as intentional, and
+ * is someone else's trademark. So an unconfigured install gets `"Site"` —
+ * obviously unconfigured — never this marketplace's name.
+ *
+ * ── 🛑 TWO injection points, because this one is isomorphic ────────────────
+ *
+ * `supplier-of-record` is server-only (invoices). Brand is rendered by client
+ * components — the guide views are `"use client"` prose — so module state set
+ * in `providers.config.ts` (server, via the instrumentation hook) is not
+ * visible in the browser bundle. The consumer therefore calls
+ * `configureBrand()` in BOTH `providers.config.ts` and
+ * `client-providers-init.ts`, which is the same symmetry `setStorageNamespace`
+ * already uses, reading from the one owner in each case.
+ *
+ * @tag domain:core
+ * @tag layer:shared
+ * @tag access:isomorphic
+ * @tag sideEffects:module-state
+ */
+export interface BrandIdentity {
+    /** Display name, e.g. "LetItRip". Appears in prose, email and structured data. */
+    name: string;
+    /** Compact form for tight chrome, e.g. "LT". Defaults to `name`. */
+    shortName: string;
+    /**
+     * Bare host with no scheme, e.g. "letitrip.in". Used for the media watermark
+     * default and for addresses quoted in prose.
+     */
+    domain: string;
+    /** Where buyers and sellers are told to write. Derived from `domain` when unset. */
+    supportEmail: string;
+    /** Envelope sender for transactional mail. Derived from `domain` when unset. */
+    noreplyEmail: string;
+}
+/**
+ * Register the consumer's brand. Call once, at boot, on BOTH sides.
+ *
+ * Merges rather than replaces, so a partial call cannot blank a field that was
+ * already supplied — the same shape `configureMarketDefaults` and
+ * `configurePlatformSupplier` use.
+ */
+export declare function configureBrand(brand: Partial<BrandIdentity>): void;
+/** Reset to the neutral defaults. For tests and the seed CLI's isolated runs. */
+export declare function resetBrand(): void;
+/** Display name. `"Site"` when nothing was injected. */
+export declare function getBrandName(): string;
+/** Compact name, falling back to the display name rather than to `"Site"`. */
+export declare function getBrandShortName(): string;
+/** Bare host, no scheme. */
+export declare function getBrandDomain(): string;
+/**
+ * Support address, derived from `domain` when not injected explicitly.
+ *
+ * Derived rather than required because a consumer who has given us a domain
+ * has already answered this; making it mandatory would mean two config fields
+ * that can disagree (Root Cause #42) for no gain.
+ */
+export declare function getBrandSupportEmail(): string;
+/** Transactional envelope sender, derived from `domain` when not injected. */
+export declare function getBrandNoreplyEmail(): string;
+/** Full resolved identity (neutral defaults + injected overrides + derivations). */
+export declare function getBrand(): Readonly<BrandIdentity>;

package/dist/core/brand-resolver.js

@@ -0,0 +1,120 @@
+/**
+ * The consumer's brand identity, injected once at boot.
+ *
+ * ── Why this seam exists ──────────────────────────────────────────────────
+ *
+ * `appkit.config.js → brand` is the consumer-owned owner of the site's name,
+ * short name and TLD. appkit has no runtime reader for a consumer config file,
+ * so — exactly as `supplier-of-record.ts` does for the statutory identity, and
+ * `baseline-resolver.ts` for currency and locale — the consumer injects it.
+ *
+ * Measured 2026-10-29, this was the FIFTH owner problem that
+ * `supplier-of-record.ts` was written to end, one field over. `brand.name` is
+ * `"LetItRip"`, but five appkit modules read `NEXT_PUBLIC_SITE_NAME` directly
+ * with five DIFFERENT fallbacks (`"LetItRip"`, `"App"`, `"App"`, `""`, and a
+ * comment), and that env var holds `"Let It Rip India"` — which is
+ * `brand.heroCaption`, not the brand name. So the checkout value-OTP message
+ * and the JSON-LD `publisher` both named the site something the brand owner
+ * does not call it, while `SiteLogo` drew a third spelling.
+ *
+ * `seo/json-ld.ts:408` already records the previous round of this:
+ * "Production had NEXT_PUBLIC_SITE_NAME='Letitrip' — the wrong casing". The
+ * env var is not the owner; it never was.
+ *
+ * ── 🛑 The defaults here are NEUTRAL, and that asymmetry is deliberate ─────
+ *
+ * `baseline-resolver.ts`'s BASELINE is documented as matching letitrip.in
+ * ("INR / en-IN / IN / +91 / Asia/Kolkata") and that is defensible: a wrong
+ * currency is visible in the first rendered price, so an unconfigured install
+ * discovers it immediately.
+ *
+ * A wrong brand name is not. It renders plausibly, reads as intentional, and
+ * is someone else's trademark. So an unconfigured install gets `"Site"` —
+ * obviously unconfigured — never this marketplace's name.
+ *
+ * ── 🛑 TWO injection points, because this one is isomorphic ────────────────
+ *
+ * `supplier-of-record` is server-only (invoices). Brand is rendered by client
+ * components — the guide views are `"use client"` prose — so module state set
+ * in `providers.config.ts` (server, via the instrumentation hook) is not
+ * visible in the browser bundle. The consumer therefore calls
+ * `configureBrand()` in BOTH `providers.config.ts` and
+ * `client-providers-init.ts`, which is the same symmetry `setStorageNamespace`
+ * already uses, reading from the one owner in each case.
+ *
+ * @tag domain:core
+ * @tag layer:shared
+ * @tag access:isomorphic
+ * @tag sideEffects:module-state
+ */
+/**
+ * 🛑 "Site" and "example.invalid", not this marketplace's values.
+ *
+ * `.invalid` is reserved by RFC 2606 precisely so it can never resolve, which
+ * makes an unconfigured install fail visibly at the first send rather than
+ * quietly mailing a real domain someone else owns.
+ */
+const NEUTRAL = Object.freeze({
+    name: "Site",
+    shortName: "Site",
+    domain: "example.invalid",
+    supportEmail: "support@example.invalid",
+    noreplyEmail: "noreply@example.invalid",
+});
+let _brand = {};
+/**
+ * Register the consumer's brand. Call once, at boot, on BOTH sides.
+ *
+ * Merges rather than replaces, so a partial call cannot blank a field that was
+ * already supplied — the same shape `configureMarketDefaults` and
+ * `configurePlatformSupplier` use.
+ */
+export function configureBrand(brand) {
+    _brand = { ..._brand, ...brand };
+}
+/** Reset to the neutral defaults. For tests and the seed CLI's isolated runs. */
+export function resetBrand() {
+    _brand = {};
+}
+/** Display name. `"Site"` when nothing was injected. */
+export function getBrandName() {
+    return _brand.name?.trim() || NEUTRAL.name;
+}
+/** Compact name, falling back to the display name rather than to `"Site"`. */
+export function getBrandShortName() {
+    return _brand.shortName?.trim() || getBrandName();
+}
+/** Bare host, no scheme. */
+export function getBrandDomain() {
+    return _brand.domain?.trim() || NEUTRAL.domain;
+}
+/**
+ * Support address, derived from `domain` when not injected explicitly.
+ *
+ * Derived rather than required because a consumer who has given us a domain
+ * has already answered this; making it mandatory would mean two config fields
+ * that can disagree (Root Cause #42) for no gain.
+ */
+export function getBrandSupportEmail() {
+    if (_brand.supportEmail?.trim())
+        return _brand.supportEmail.trim();
+    const domain = _brand.domain?.trim();
+    return domain ? `support@${domain}` : NEUTRAL.supportEmail;
+}
+/** Transactional envelope sender, derived from `domain` when not injected. */
+export function getBrandNoreplyEmail() {
+    if (_brand.noreplyEmail?.trim())
+        return _brand.noreplyEmail.trim();
+    const domain = _brand.domain?.trim();
+    return domain ? `noreply@${domain}` : NEUTRAL.noreplyEmail;
+}
+/** Full resolved identity (neutral defaults + injected overrides + derivations). */
+export function getBrand() {
+    return Object.freeze({
+        name: getBrandName(),
+        shortName: getBrandShortName(),
+        domain: getBrandDomain(),
+        supportEmail: getBrandSupportEmail(),
+        noreplyEmail: getBrandNoreplyEmail(),
+    });
+}

package/dist/core/brand-text.d.ts

@@ -0,0 +1,15 @@
+/** The site-name token, in the vocabulary this codebase already uses. */
+export declare const BRAND_TOKEN = "{{siteName}}";
+/** The bare-host token, e.g. `support@{{siteDomain}}`. */
+export declare const BRAND_DOMAIN_TOKEN = "{{siteDomain}}";
+/**
+ * Substitute every published token in one string, brand included.
+ *
+ * Resolved per call rather than from a module-level snapshot: the values are
+ * read from the injected brand, and a hoisted `const` would capture appkit's
+ * neutral default before `configureBrand()` ran. The resolver is a string
+ * replace over a small map — cheap enough per render.
+ */
+export declare function withBrand(text: string): string;
+/** `withBrand` over an array — the common shape for advice and rule lists. */
+export declare function withBrandAll(texts: readonly string[]): string[];

package/dist/core/brand-text.js

@@ -0,0 +1,73 @@
+/**
+ * Brand tokens for prose that cannot interpolate where it is written.
+ *
+ * ── Why a token at all ────────────────────────────────────────────────────
+ *
+ * Most brand mentions sit inside a component and can just call
+ * `getBrandName()` at render time. A few cannot: they live in module-level
+ * `const` data (`SCAM_TYPES` alone is 19 mentions across ~600 lines of advice),
+ * and a template literal there is evaluated at IMPORT time — before the
+ * consumer's `configureBrand()` has run. It would capture appkit's neutral
+ * `"Site"` permanently and look like it worked.
+ *
+ * Turning those arrays into functions was the alternative, and it is a
+ * BREAKING change for a consumer pinning appkit from the registry: six modules
+ * import `SCAM_TYPES` directly, one of them a consumer API route. So the data
+ * keeps its shape and carries `{{siteName}}`.
+ *
+ * ── 🛑 THIS IS A WRAPPER, NOT A SECOND TOKEN SYSTEM ───────────────────────
+ *
+ * The substitution is `resolvePublishedCopy` — the engine that already renders
+ * every disclaimer, FAQ answer and refund-policy sentence, with five live
+ * consumers and `audit-disclaimer-coverage` behind it. `siteName` was ALREADY
+ * one of its keys.
+ *
+ * The first draft of this file shipped its own `{brand}` token and its own
+ * `split/join` substitution, which was two mistakes at once:
+ *
+ *  - a second resolver for the same job — precisely the duplication Tier AK
+ *    exists to remove, and it was caught only because the guarding audit
+ *    flagged `disclaimers.ts`, which had been doing this correctly all along;
+ *    and
+ *  - a COLLIDING spelling. `{brand}` is an ordinary JSX expression in seven
+ *    detail views, and `{{brand}}` was already taken — it means the PRODUCT's
+ *    manufacturer (6 live uses) against 21 of `{{siteName}}` for the site. So
+ *    a token reading `{brand}` in platform prose would have said "Takara-Tomy"
+ *    to anyone who knew the other system.
+ *
+ * What survives is the ergonomics: `withBrandAll` over an array of advice
+ * strings, and one import instead of two at every call site.
+ *
+ * 🛑 An UNKNOWN token is left VERBATIM by the engine, deliberately — see its
+ * own note: a blanked token reads as clumsy copy nobody reports, while a
+ * visible `{{siteNam}}` on a live page is reported within minutes. Do not add
+ * a "safe" fallback here that defeats that.
+ *
+ * @tag domain:core
+ * @tag layer:shared
+ * @tag access:isomorphic
+ * @tag sideEffects:none
+ */
+import { resolvePublishedCopy, resolvePublishedValues, } from "../_internal/shared/content/published-values.js";
+/** The site-name token, in the vocabulary this codebase already uses. */
+export const BRAND_TOKEN = "{{siteName}}";
+/** The bare-host token, e.g. `support@{{siteDomain}}`. */
+export const BRAND_DOMAIN_TOKEN = "{{siteDomain}}";
+/**
+ * Substitute every published token in one string, brand included.
+ *
+ * Resolved per call rather than from a module-level snapshot: the values are
+ * read from the injected brand, and a hoisted `const` would capture appkit's
+ * neutral default before `configureBrand()` ran. The resolver is a string
+ * replace over a small map — cheap enough per render.
+ */
+export function withBrand(text) {
+    if (!text.includes("{{"))
+        return text;
+    return resolvePublishedCopy(text, resolvePublishedValues());
+}
+/** `withBrand` over an array — the common shape for advice and rule lists. */
+export function withBrandAll(texts) {
+    const values = resolvePublishedValues();
+    return texts.map((t) => t.includes("{{") ? resolvePublishedCopy(t, values) : t);
+}

package/dist/core/hooks/useNewsletterSubscribe.d.ts

@@ -0,0 +1,30 @@
+import type { SupportedNewsletterSource } from "../newsletter-actions";
+export interface UseNewsletterSubscribeOptions {
+    /**
+     * The subscribe endpoint. Supplied by the consumer, which owns its route
+     * map — appkit must not name a consumer's URL.
+     */
+    endpoint: string;
+    /**
+     * Which box this is.
+     *
+     * 🛑 Typed against `SupportedNewsletterSource` rather than `string`, so a
+     * typo is a compile error instead of a row in `newsletterSubscribers` whose
+     * `source` matches no report.
+     */
+    source: SupportedNewsletterSource;
+    /** Toast shown on success. */
+    successToast: string;
+    /** Toast shown when the request fails. */
+    errorMessage?: string;
+    /** Runs after a successful subscribe — clear local UI, flip to a thank-you. */
+    onSuccess?: () => void;
+}
+export declare function useNewsletterSubscribe({ endpoint, source, successToast, errorMessage, onSuccess, }: UseNewsletterSubscribeOptions): {
+    email: string;
+    setEmail: import("react").Dispatch<import("react").SetStateAction<string>>;
+    submit: () => Promise<void>;
+    isPending: boolean;
+    /** Pass to `<Form shellCtx={…}>` — see the note on `form` above. */
+    shellCtx: import("../..").FormShellContextValue;
+};