@vtex/faststore 0.0.4 → 0.0.6

package/dist/sdk/state/cart.js

@@ -4,8 +4,7 @@ const orderFormIdVar = makeVar(null);
 /**
 * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes
 * here on every call (cleared synchronously at the start of the next call) and `CartError` reads it
-* via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (specs/actions.md
-* FR-9). Stays in client state — never a query variable or request header.
+* via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Stays in client state — never a query variable or request header.
 */
 const cartUserErrorsVar = makeVar([]);
 /**
@@ -13,7 +12,7 @@ const cartUserErrorsVar = makeVar([]);
 * error and network-catch branches leave it untouched. `CartOpenOnAdd` and `CartRedirectOnAdd` key
 * a `useEffect` on it via `useReactiveVar`, so every successful add re-fires their behavior even when
 * the drawer is already open or was just closed — a boolean would not re-fire on an unchanged value
-* (specs/fspg-822-minicart-open-on-add.md, Decision 2). Client state only — never a query variable
+* (docs/storefront-core/reference-free-particle-model.md § Read side — state). Client state only — never a query variable
 * or request header.
 */
 const cartLastAddVar = makeVar(0);
@@ -28,13 +27,13 @@ const miniCartOpenVar = makeVar(false);
 /**
 * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.
 * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form
-* and never collides with item-write errors (specs/fspg-830-coupon-entry.md AD-2). The coupon
+* and never collides with item-write errors (docs/storefront-core/reference-free-particle-model.md § The cart write contract). The coupon
 * actions publish here on every call (cleared at the start of the next call) and `CartCouponError`
 * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.
 */
 const cartCouponErrorsVar = makeVar([]);
 /**
-* Count of cart writes currently in flight (specs/mini-cart-validation-wiring.md). Every mutating
+* Count of cart writes currently in flight (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Every mutating
 * handler in the cart action namespace registers for the lifetime of its call, so `> 0` means a
 * write is outstanding. The stock-validation open call reads this to skip while a write is running —
 * that write's own response already carries current availability, so re-validating would be
@@ -45,7 +44,7 @@ const cartWritesInFlightVar = makeVar(0);
 /**
 * Epoch-ms timestamp of when the client last received current availability (`0` = never). Stamped on
 * a successful `validate` and on every successful cart write, because a write's response already
-* carries recomputed availability (specs/mini-cart-validation-wiring.md, Decision 2). The
+* carries recomputed availability (docs/storefront-core/reference-cart.md § Validation). The
 * stock-validation open call compares `now - cartAvailabilityFreshAtVar()` against
 * `CART_VALIDATE_STALENESS_MS` and skips while inside the window, so reopening the overlay — or
 * opening it right after an add — does not re-validate. Client state only.
@@ -54,7 +53,7 @@ const cartAvailabilityFreshAtVar = makeVar(0);
 /**
 * The staleness window for the stock-validation open call, in milliseconds. The single tuning knob:
 * the platform's rate limits under real traffic are not known yet, so this value is a starting point,
-* not a contract (specs/mini-cart-validation-wiring.md). The pre-checkout call ignores it and always
+* not a contract (docs/storefront-core/reference-cart.md § Validation). The pre-checkout call ignores it and always
 * runs.
 */
 const CART_VALIDATE_STALENESS_MS = 3e4;

package/dist/sdk/state/cart.js.map

@@ -1 +1 @@
-{"version":3,"file":"cart.js","names":[],"sources":["../../../src/sdk/state/cart.ts"],"sourcesContent":["import { makeVar } from '@apollo/client';\nimport type { CartUserError } from '../cart/operations.js';\n\n// Session-scoped cart identifier (`Cart.id` from the cart query response). Client state only —\n// never sent as a query variable or request header; the x-order-form-id cookie carries cart\n// context on the transport. Starts null; hydrated when the cart entity arrives, which opens the\n// cart action ready gate. See specs/cart-context-client-migrate.md (Decisions 2, 6).\nexport const orderFormIdVar = makeVar<string | null>(null);\n\n/**\n * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes\n * here on every call (cleared synchronously at the start of the next call) and `CartError` reads it\n * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (specs/actions.md\n * FR-9). Stays in client state — never a query variable or request header.\n */\nexport const cartUserErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Monotonic add-success pulse. `addItem` increments it on each successful add (no userErrors); the\n * error and network-catch branches leave it untouched. `CartOpenOnAdd` and `CartRedirectOnAdd` key\n * a `useEffect` on it via `useReactiveVar`, so every successful add re-fires their behavior even when\n * the drawer is already open or was just closed — a boolean would not re-fire on an unchanged value\n * (specs/fspg-822-minicart-open-on-add.md, Decision 2). Client state only — never a query variable\n * or request header.\n */\nexport const cartLastAddVar = makeVar<number>(0);\n\n/**\n * The mini-cart's open state, surfaced context-free. `CartOpenOnAdd` reads it via `useReactiveVar`\n * to control the `DrawerRoot` and writes it back through `onOpenChange` so the header trigger and\n * manual close (Escape / backdrop / close button) stay in sync. The single source of truth for the\n * controlled drawer; `addItem` never writes it. Client state only — never a query variable or\n * request header.\n */\nexport const miniCartOpenVar = makeVar<boolean>(false);\n\n/**\n * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.\n * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form\n * and never collides with item-write errors (specs/fspg-830-coupon-entry.md AD-2). The coupon\n * actions publish here on every call (cleared at the start of the next call) and `CartCouponError`\n * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.\n */\nexport const cartCouponErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Count of cart writes currently in flight (specs/mini-cart-validation-wiring.md). Every mutating\n * handler in the cart action namespace registers for the lifetime of its call, so `> 0` means a\n * write is outstanding. The stock-validation open call reads this to skip while a write is running —\n * that write's own response already carries current availability, so re-validating would be\n * redundant. `validate` itself is read-only upstream and never registers here. Client state only —\n * never a query variable or request header.\n */\nexport const cartWritesInFlightVar = makeVar<number>(0);\n\n/**\n * Epoch-ms timestamp of when the client last received current availability (`0` = never). Stamped on\n * a successful `validate` and on every successful cart write, because a write's response already\n * carries recomputed availability (specs/mini-cart-validation-wiring.md, Decision 2). The\n * stock-validation open call compares `now - cartAvailabilityFreshAtVar()` against\n * `CART_VALIDATE_STALENESS_MS` and skips while inside the window, so reopening the overlay — or\n * opening it right after an add — does not re-validate. Client state only.\n */\nexport const cartAvailabilityFreshAtVar = makeVar<number>(0);\n\n/**\n * The staleness window for the stock-validation open call, in milliseconds. The single tuning knob:\n * the platform's rate limits under real traffic are not known yet, so this value is a starting point,\n * not a contract (specs/mini-cart-validation-wiring.md). The pre-checkout call ignores it and always\n * runs.\n */\nexport const CART_VALIDATE_STALENESS_MS = 30_000;\n"],"mappings":";;AAOA,MAAa,iBAAiB,QAAuB,IAAI;;;;;;;AAQzD,MAAa,oBAAoB,QAAkC,CAAC,CAAC;;;;;;;;;AAUrE,MAAa,iBAAiB,QAAgB,CAAC;;;;;;;;AAS/C,MAAa,kBAAkB,QAAiB,KAAK;;;;;;;;AASrD,MAAa,sBAAsB,QAAkC,CAAC,CAAC;;;;;;;;;AAUvE,MAAa,wBAAwB,QAAgB,CAAC;;;;;;;;;AAUtD,MAAa,6BAA6B,QAAgB,CAAC;;;;;;;AAQ3D,MAAa,6BAA6B"}
+{"version":3,"file":"cart.js","names":[],"sources":["../../../src/sdk/state/cart.ts"],"sourcesContent":["import { makeVar } from '@apollo/client';\nimport type { CartUserError } from '../cart/operations.js';\n\n// Session-scoped cart identifier (`Cart.id` from the cart query response). Client state only —\n// never sent as a query variable or request header; the x-order-form-id cookie carries cart\n// context on the transport. Starts null; hydrated when the cart entity arrives, which opens the\n// cart action ready gate. See docs/storefront-core/reference-cart.md § Cart context; docs/storefront-core/reference-free-particle-model.md § The cart write contract.\nexport const orderFormIdVar = makeVar<string | null>(null);\n\n/**\n * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes\n * here on every call (cleared synchronously at the start of the next call) and `CartError` reads it\n * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Stays in client state — never a query variable or request header.\n */\nexport const cartUserErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Monotonic add-success pulse. `addItem` increments it on each successful add (no userErrors); the\n * error and network-catch branches leave it untouched. `CartOpenOnAdd` and `CartRedirectOnAdd` key\n * a `useEffect` on it via `useReactiveVar`, so every successful add re-fires their behavior even when\n * the drawer is already open or was just closed — a boolean would not re-fire on an unchanged value\n * (docs/storefront-core/reference-free-particle-model.md § Read side — state). Client state only — never a query variable\n * or request header.\n */\nexport const cartLastAddVar = makeVar<number>(0);\n\n/**\n * The mini-cart's open state, surfaced context-free. `CartOpenOnAdd` reads it via `useReactiveVar`\n * to control the `DrawerRoot` and writes it back through `onOpenChange` so the header trigger and\n * manual close (Escape / backdrop / close button) stay in sync. The single source of truth for the\n * controlled drawer; `addItem` never writes it. Client state only — never a query variable or\n * request header.\n */\nexport const miniCartOpenVar = makeVar<boolean>(false);\n\n/**\n * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.\n * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form\n * and never collides with item-write errors (docs/storefront-core/reference-free-particle-model.md § The cart write contract). The coupon\n * actions publish here on every call (cleared at the start of the next call) and `CartCouponError`\n * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.\n */\nexport const cartCouponErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Count of cart writes currently in flight (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Every mutating\n * handler in the cart action namespace registers for the lifetime of its call, so `> 0` means a\n * write is outstanding. The stock-validation open call reads this to skip while a write is running —\n * that write's own response already carries current availability, so re-validating would be\n * redundant. `validate` itself is read-only upstream and never registers here. Client state only —\n * never a query variable or request header.\n */\nexport const cartWritesInFlightVar = makeVar<number>(0);\n\n/**\n * Epoch-ms timestamp of when the client last received current availability (`0` = never). Stamped on\n * a successful `validate` and on every successful cart write, because a write's response already\n * carries recomputed availability (docs/storefront-core/reference-cart.md § Validation). The\n * stock-validation open call compares `now - cartAvailabilityFreshAtVar()` against\n * `CART_VALIDATE_STALENESS_MS` and skips while inside the window, so reopening the overlay — or\n * opening it right after an add — does not re-validate. Client state only.\n */\nexport const cartAvailabilityFreshAtVar = makeVar<number>(0);\n\n/**\n * The staleness window for the stock-validation open call, in milliseconds. The single tuning knob:\n * the platform's rate limits under real traffic are not known yet, so this value is a starting point,\n * not a contract (docs/storefront-core/reference-cart.md § Validation). The pre-checkout call ignores it and always\n * runs.\n */\nexport const CART_VALIDATE_STALENESS_MS = 30_000;\n"],"mappings":";;AAOA,MAAa,iBAAiB,QAAuB,IAAI;;;;;;AAOzD,MAAa,oBAAoB,QAAkC,CAAC,CAAC;;;;;;;;;AAUrE,MAAa,iBAAiB,QAAgB,CAAC;;;;;;;;AAS/C,MAAa,kBAAkB,QAAiB,KAAK;;;;;;;;AASrD,MAAa,sBAAsB,QAAkC,CAAC,CAAC;;;;;;;;;AAUvE,MAAa,wBAAwB,QAAgB,CAAC;;;;;;;;;AAUtD,MAAa,6BAA6B,QAAgB,CAAC;;;;;;;AAQ3D,MAAa,6BAA6B"}

package/dist/utils/loggable-error-name.js

@@ -0,0 +1,49 @@
+//#region src/utils/loggable-error-name.ts
+/**
+* `Error.prototype.name` is a writable own property (security pass, T156 review; fixed here, T160):
+* any collaborator a caller wraps in a `try`/`catch` — a holder's continuation, a pre-flight check,
+* an action provider, a GraphQL mutation rejection — can throw an object whose `.name` is arbitrary
+* text, including text built from card data or PII the caller exists to keep out of a log. An
+* allow-list, not a pattern or a deny-list, mirrors this package's own rule for exactly this shape of
+* problem (`matter/sensitive-field-protection.test.ts`'s own "an allow-list fails loudly ... a
+* deny-list fails silently"). Lives in `utils/`, not in any one domain's `sdk/` subdirectory, because
+* its callers already span two peer domains — `payment` and `identity` — neither of which should
+* import a logging helper from the other (T160, Decision 6).
+*/
+const LOGGABLE_ERROR_NAMES = /* @__PURE__ */ new Set([
+	"Error",
+	"EvalError",
+	"RangeError",
+	"ReferenceError",
+	"SyntaxError",
+	"TypeError",
+	"URIError",
+	"AggregateError"
+]);
+/**
+* The one place every caller below decides what to log for a caught error. Never the raw `.name`.
+*
+* `error` is an untrusted value: a holder's continuation, a pre-flight check, or any other
+* pluggable collaborator can throw whatever object it wants, engineered so that merely inspecting
+* it — not only reading `.name` — throws (fix rounds 1-3, all Medium findings). A `Proxy` can trap
+* `getPrototypeOf` (triggered by the `instanceof` check below), `get` (triggered by the `.name`
+* read), or make either one answer differently across repeated calls. Rather than guard each
+* mechanism one at a time, every operation this function performs on `error` — the `instanceof`
+* check, the `.name` read, and the allow-list membership check — runs inside one `try`/`catch`:
+* whatever throws, and for whatever reason, collapses to `'UnknownError'` exactly like any other
+* unrecognised name. `error.name` is still read exactly once, into `name` below, so a getter that
+* answers differently across separate calls has no second read left to answer differently on.
+*/
+function loggableErrorName(error) {
+	try {
+		if (!(error instanceof Error)) return "UnknownError";
+		const name = error.name;
+		return LOGGABLE_ERROR_NAMES.has(name) ? name : "UnknownError";
+	} catch {
+		return "UnknownError";
+	}
+}
+//#endregion
+export { loggableErrorName };
+
+//# sourceMappingURL=loggable-error-name.js.map

package/dist/utils/loggable-error-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loggable-error-name.js","names":[],"sources":["../../src/utils/loggable-error-name.ts"],"sourcesContent":["/**\n * `Error.prototype.name` is a writable own property (security pass, T156 review; fixed here, T160):\n * any collaborator a caller wraps in a `try`/`catch` — a holder's continuation, a pre-flight check,\n * an action provider, a GraphQL mutation rejection — can throw an object whose `.name` is arbitrary\n * text, including text built from card data or PII the caller exists to keep out of a log. An\n * allow-list, not a pattern or a deny-list, mirrors this package's own rule for exactly this shape of\n * problem (`matter/sensitive-field-protection.test.ts`'s own \"an allow-list fails loudly ... a\n * deny-list fails silently\"). Lives in `utils/`, not in any one domain's `sdk/` subdirectory, because\n * its callers already span two peer domains — `payment` and `identity` — neither of which should\n * import a logging helper from the other (T160, Decision 6).\n */\nconst LOGGABLE_ERROR_NAMES: ReadonlySet<string> = new Set([\n  'Error',\n  'EvalError',\n  'RangeError',\n  'ReferenceError',\n  'SyntaxError',\n  'TypeError',\n  'URIError',\n  'AggregateError',\n]);\n\n/**\n * The one place every caller below decides what to log for a caught error. Never the raw `.name`.\n *\n * `error` is an untrusted value: a holder's continuation, a pre-flight check, or any other\n * pluggable collaborator can throw whatever object it wants, engineered so that merely inspecting\n * it — not only reading `.name` — throws (fix rounds 1-3, all Medium findings). A `Proxy` can trap\n * `getPrototypeOf` (triggered by the `instanceof` check below), `get` (triggered by the `.name`\n * read), or make either one answer differently across repeated calls. Rather than guard each\n * mechanism one at a time, every operation this function performs on `error` — the `instanceof`\n * check, the `.name` read, and the allow-list membership check — runs inside one `try`/`catch`:\n * whatever throws, and for whatever reason, collapses to `'UnknownError'` exactly like any other\n * unrecognised name. `error.name` is still read exactly once, into `name` below, so a getter that\n * answers differently across separate calls has no second read left to answer differently on.\n */\nexport function loggableErrorName(error: unknown): string {\n  try {\n    if (!(error instanceof Error)) {\n      return 'UnknownError';\n    }\n\n    const name = error.name;\n    return LOGGABLE_ERROR_NAMES.has(name) ? name : 'UnknownError';\n  } catch {\n    return 'UnknownError';\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAWA,MAAM,uCAA4C,IAAI,IAAI;CACxD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;;;;;;;;;;AAgBD,SAAgB,kBAAkB,OAAwB;CACxD,IAAI;EACF,IAAI,EAAE,iBAAiB,QACrB,OAAO;EAGT,MAAM,OAAO,MAAM;EACnB,OAAO,qBAAqB,IAAI,IAAI,IAAI,OAAO;CACjD,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/utils/resolve-authored-copy.js

@@ -0,0 +1,18 @@
+//#region src/utils/resolve-authored-copy.ts
+/**
+* Resolve an authored copy value against its default. A store author can write "" or "   " into any
+* `type: 'string'` schema prop — both are valid JSON strings — and neither `??` nor a default
+* parameter falls through on them, so the surface renders a blank label, legend or alert. Logical OR
+* is not a fix either: "   " is truthy.
+*
+* The authored value is returned VERBATIM when it has content — trimmed only to decide, never to
+* render, matching `cart.tsx`'s `configuredLabel` and `region.tsx`'s `$content` idiom.
+*/
+function resolveAuthoredCopy(authored, fallback) {
+	if (authored == null) return fallback;
+	return authored.trim().length > 0 ? authored : fallback;
+}
+//#endregion
+export { resolveAuthoredCopy };
+
+//# sourceMappingURL=resolve-authored-copy.js.map

package/dist/utils/resolve-authored-copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-authored-copy.js","names":[],"sources":["../../src/utils/resolve-authored-copy.ts"],"sourcesContent":["/**\n * Resolve an authored copy value against its default. A store author can write \"\" or \"   \" into any\n * `type: 'string'` schema prop — both are valid JSON strings — and neither `??` nor a default\n * parameter falls through on them, so the surface renders a blank label, legend or alert. Logical OR\n * is not a fix either: \"   \" is truthy.\n *\n * The authored value is returned VERBATIM when it has content — trimmed only to decide, never to\n * render, matching `cart.tsx`'s `configuredLabel` and `region.tsx`'s `$content` idiom.\n */\nexport function resolveAuthoredCopy(authored: string | undefined | null, fallback: string): string {\n  if (authored == null) return fallback;\n  return authored.trim().length > 0 ? authored : fallback;\n}\n"],"mappings":";;;;;;;;;;AASA,SAAgB,oBAAoB,UAAqC,UAA0B;CACjG,IAAI,YAAY,MAAM,OAAO;CAC7B,OAAO,SAAS,KAAK,CAAC,CAAC,SAAS,IAAI,WAAW;AACjD"}

package/dist/utils/safe-href.js

@@ -7,9 +7,9 @@ const ALLOWED_PROTOCOLS = /* @__PURE__ */ new Set([
 ]);
 /**
 * The only gate on a CMS-authored destination: `http:`, `https:`, `mailto:`, `tel:`, and paths
-* starting with a single `/`. Neither the runtime slice nor the sukima preflight enforces a model's
-* `pattern`, so an authored `javascript:` value reaches the component intact and this is what stands
-* between it and an `href`.
+* starting with a single `/`. The runtime slice does not enforce a model's `pattern`, and the sukima
+* preflight that does never sees content published after a deploy, so an authored `javascript:` value
+* can reach the component intact and this is what stands between it and an `href`.
 *
 * Rejects rather than sanitizes: a destination that comes back safe is character-for-character the
 * trimmed authored value, so no value is ever silently rewritten into a different working one.

package/dist/utils/safe-href.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe-href.js","names":[],"sources":["../../src/utils/safe-href.ts"],"sourcesContent":["export type SafeHrefRejection =\n  | 'blank'\n  | 'malformed'\n  | 'protocol-relative'\n  | 'forbidden-scheme'\n  | 'absolute'\n  | 'sign-in-route';\n\nexport type SafeHrefResult = { safe: true; href: string } | { safe: false; reason: SafeHrefRejection };\n\nconst ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:']);\n\n/**\n * The only gate on a CMS-authored destination: `http:`, `https:`, `mailto:`, `tel:`, and paths\n * starting with a single `/`. Neither the runtime slice nor the sukima preflight enforces a model's\n * `pattern`, so an authored `javascript:` value reaches the component intact and this is what stands\n * between it and an `href`.\n *\n * Rejects rather than sanitizes: a destination that comes back safe is character-for-character the\n * trimmed authored value, so no value is ever silently rewritten into a different working one.\n */\nexport function resolveSafeHref(raw: string): SafeHrefResult {\n  const href = raw.trim();\n  if (href.length === 0) {\n    return { safe: false, reason: 'blank' };\n  }\n  // Browsers strip ASCII tabs and newlines from a URL before parsing it, so `java<TAB>script:alert(1)`\n  // executes. Refusing the whole value is the only defense that does not depend on stripping the same\n  // characters in the same order the parser does.\n  if (hasStrippableCharacter(href)) {\n    return { safe: false, reason: 'malformed' };\n  }\n  // A URL parser reads `\\` as `/` under a special scheme, so `/\\evil.example` resolves against the\n  // store's origin as an authority rather than a path. Any pair of leading slashes is an off-site\n  // jump however it is spelled, and only `//` looks like one.\n  if (/^[/\\\\]{2}/.test(href)) {\n    return { safe: false, reason: 'protocol-relative' };\n  }\n  if (href.startsWith('/')) {\n    return { safe: true, href };\n  }\n\n  let protocol: string;\n  try {\n    protocol = new URL(href).protocol;\n  } catch {\n    return { safe: false, reason: 'malformed' };\n  }\n  // `new URL` lowercases the protocol, so `JavaScript:` and `javascript:` are the same rejection.\n  return ALLOWED_PROTOCOLS.has(protocol) ? { safe: true, href } : { safe: false, reason: 'forbidden-scheme' };\n}\n\n/** The storefront's own sign-in route, which forwards to the platform's login. A fixed convention,\n *  never an authored value. */\nconst SIGN_IN_ROUTE = '/login';\n\n/** The parameter carrying the shopper's way back, read by the sign-in route and the platform's login. */\nexport const RETURN_URL_PARAM = 'returnUrl';\n\n/**\n * `resolveSafeHref` narrowed to the site-relative subset: the destinations a shopper may be sent back to\n * across the auth hop. The allowlist admits absolute http(s) values, which are legitimate for an authored\n * link but are exactly what would turn the hop into an open redirect. Every other rejection travels out\n * unchanged, so a caller logging the reason still sees which spelling arrived.\n *\n * Both ends of the flow narrow through here rather than only the sender, because the sender cannot vouch\n * for a URL the shopper typed: the account button builds the destination through `resolveSignInHref`, and\n * the sign-in route revalidates what arrives through `resolveReturnHref`.\n */\nexport function resolveSiteRelativeHref(raw: string): SafeHrefResult {\n  const destination = resolveSafeHref(raw);\n  if (!destination.safe) {\n    return destination;\n  }\n  return destination.href.startsWith('/') ? destination : { safe: false, reason: 'absolute' };\n}\n\n/** The subset of the allowlist that resolves to a page a document can be handed over to. */\nconst NAVIGABLE_PROTOCOLS = new Set(['http:', 'https:']);\n\n/**\n * `resolveSafeHref` narrowed to the destinations that resolve to a page: site-relative, or absolute\n * `http(s)`. `mailto:` and `tel:` are legitimate for an authored link and refused here, since handing a\n * document over to one leaves the shopper in a mail client instead of a login.\n */\nexport function resolveNavigableHref(raw: string): SafeHrefResult {\n  const destination = resolveSafeHref(raw);\n  if (!destination.safe || destination.href.startsWith('/')) {\n    return destination;\n  }\n  // The allowlist already parsed this value, so the protocol is readable without a second guard.\n  const { protocol } = new URL(destination.href);\n  return NAVIGABLE_PROTOCOLS.has(protocol) ? destination : { safe: false, reason: 'forbidden-scheme' };\n}\n\n/**\n * `resolveSiteRelativeHref` narrowed further, for a return arriving at the sign-in route: the route\n * itself is refused. Admitting it sends a shopper who just authenticated back to the trampoline, which\n * hands them to the platform a second time — a sign-in that never lands where the parameter promised.\n */\nexport function resolveReturnHref(raw: string): SafeHrefResult {\n  const destination = resolveSiteRelativeHref(raw);\n  if (!destination.safe) {\n    return destination;\n  }\n  return isSignInRoute(destination.href) ? { safe: false, reason: 'sign-in-route' } : destination;\n}\n\n/** Whether a site-relative value names the storefront's own sign-in route, in any of its spellings. */\nexport function isSignInRoute(href: string): boolean {\n  return pathOf(href) === SIGN_IN_ROUTE;\n}\n\n/**\n * `resolveNavigableHref` narrowed for the address a handover targets: the storefront's own sign-in\n * route is refused. Sending `/login` to `/login` reloads the same document, which mounts the same\n * handover again — a loop the shopper never gets past, and the mirror of the refusal\n * `resolveReturnHref` already makes on the way back.\n *\n * Only the site-relative spelling is decidable here, being same-origin by construction. An absolute\n * address needs the document's own origin to compare against, which this module does not have and a\n * prerender does not either, so `isSignInRoute` is exported for the caller that does. A cross-origin\n * login page whose path happens to be `/login` is a different page and is left alone.\n */\nexport function resolveLoginAddressHref(raw: string): SafeHrefResult {\n  const address = resolveNavigableHref(raw);\n  if (!address.safe || !address.href.startsWith('/')) {\n    return address;\n  }\n  return isSignInRoute(address.href) ? { safe: false, reason: 'sign-in-route' } : address;\n}\n\n/**\n * Builds the sign-in destination, carrying the current path so the shopper can be returned where they\n * started. The sender's half only: nothing stops a hand-crafted link, so the sign-in route is to narrow\n * the parameter again on arrival. A path the narrowing refuses drops the parameter instead of\n * travelling encoded, and so does a router reporting no path — `usePathname()`'s type is why this takes\n * a nullable one.\n */\nexport function resolveSignInHref(pathname: string | null): string {\n  if (!pathname) {\n    return SIGN_IN_ROUTE;\n  }\n  const destination = resolveSiteRelativeHref(pathname);\n  if (!destination.safe) {\n    return SIGN_IN_ROUTE;\n  }\n  return `${SIGN_IN_ROUTE}?${RETURN_URL_PARAM}=${encodeURIComponent(destination.href)}`;\n}\n\n/** Opaque base for resolving a site-relative value to a path. Reserved by RFC 6761, so it never names a\n *  real host; nothing is navigated to it and only `pathname` is read back. */\nconst PATH_COMPARISON_BASE = 'https://store.invalid';\n\n/**\n * The path of a site-relative value, without its query or fragment and without a trailing slash, so a\n * route comparison reads the route rather than one of its spellings. `/loginhelp` is a different path\n * and stays one.\n *\n * Parsed rather than sliced, because `/account/../login`, `/account\\..\\login` and `/account/%2e%2e/login`\n * are all spellings a URL parser resolves to `/login`. A slice compares them literally and admits them,\n * and the value then reaches a receiver that does resolve them — which puts the shopper back on the\n * trampoline the refusal exists to prevent. Only the comparison is normalized: the caller returns the\n * value as it arrived, so the promise that nothing is silently rewritten still holds.\n */\nfunction pathOf(href: string): string {\n  const { pathname } = new URL(href, PATH_COMPARISON_BASE);\n  return pathname.replace(/\\/+$/, '') || '/';\n}\n\n/** Any C0 control or space anywhere in the value — the set a URL parser removes or trims. */\nfunction hasStrippableCharacter(value: string): boolean {\n  for (const character of value) {\n    const code = character.codePointAt(0) ?? 0;\n    if (code <= 0x20 || code === 0x7f) {\n      return true;\n    }\n  }\n  return false;\n}\n"],"mappings":";AAUA,MAAM,oCAAoB,IAAI,IAAI;CAAC;CAAS;CAAU;CAAW;AAAM,CAAC;;;;;;;;;;AAWxE,SAAgB,gBAAgB,KAA6B;CAC3D,MAAM,OAAO,IAAI,KAAK;CACtB,IAAI,KAAK,WAAW,GAClB,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAQ;CAKxC,IAAI,uBAAuB,IAAI,GAC7B,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAY;CAK5C,IAAI,YAAY,KAAK,IAAI,GACvB,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAoB;CAEpD,IAAI,KAAK,WAAW,GAAG,GACrB,OAAO;EAAE,MAAM;EAAM;CAAK;CAG5B,IAAI;CACJ,IAAI;EACF,WAAW,IAAI,IAAI,IAAI,CAAC,CAAC;CAC3B,QAAQ;EACN,OAAO;GAAE,MAAM;GAAO,QAAQ;EAAY;CAC5C;CAEA,OAAO,kBAAkB,IAAI,QAAQ,IAAI;EAAE,MAAM;EAAM;CAAK,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAmB;AAC5G;;;AAIA,MAAM,gBAAgB;;AAGtB,MAAa,mBAAmB;;;;;;;;;;;AAYhC,SAAgB,wBAAwB,KAA6B;CACnE,MAAM,cAAc,gBAAgB,GAAG;CACvC,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,YAAY,KAAK,WAAW,GAAG,IAAI,cAAc;EAAE,MAAM;EAAO,QAAQ;CAAW;AAC5F;;AAGA,MAAM,sCAAsB,IAAI,IAAI,CAAC,SAAS,QAAQ,CAAC;;;;;;AAOvD,SAAgB,qBAAqB,KAA6B;CAChE,MAAM,cAAc,gBAAgB,GAAG;CACvC,IAAI,CAAC,YAAY,QAAQ,YAAY,KAAK,WAAW,GAAG,GACtD,OAAO;CAGT,MAAM,EAAE,aAAa,IAAI,IAAI,YAAY,IAAI;CAC7C,OAAO,oBAAoB,IAAI,QAAQ,IAAI,cAAc;EAAE,MAAM;EAAO,QAAQ;CAAmB;AACrG;;;;;;AAOA,SAAgB,kBAAkB,KAA6B;CAC7D,MAAM,cAAc,wBAAwB,GAAG;CAC/C,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,cAAc,YAAY,IAAI,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAgB,IAAI;AACtF;;AAGA,SAAgB,cAAc,MAAuB;CACnD,OAAO,OAAO,IAAI,MAAM;AAC1B;;;;;;;;;;;;AAaA,SAAgB,wBAAwB,KAA6B;CACnE,MAAM,UAAU,qBAAqB,GAAG;CACxC,IAAI,CAAC,QAAQ,QAAQ,CAAC,QAAQ,KAAK,WAAW,GAAG,GAC/C,OAAO;CAET,OAAO,cAAc,QAAQ,IAAI,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAgB,IAAI;AAClF;;;;;;;;AASA,SAAgB,kBAAkB,UAAiC;CACjE,IAAI,CAAC,UACH,OAAO;CAET,MAAM,cAAc,wBAAwB,QAAQ;CACpD,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,GAAG,cAAc,GAAG,iBAAiB,GAAG,mBAAmB,YAAY,IAAI;AACpF;;;AAIA,MAAM,uBAAuB;;;;;;;;;;;;AAa7B,SAAS,OAAO,MAAsB;CACpC,MAAM,EAAE,aAAa,IAAI,IAAI,MAAM,oBAAoB;CACvD,OAAO,SAAS,QAAQ,QAAQ,EAAE,KAAK;AACzC;;AAGA,SAAS,uBAAuB,OAAwB;CACtD,KAAK,MAAM,aAAa,OAAO;EAC7B,MAAM,OAAO,UAAU,YAAY,CAAC,KAAK;EACzC,IAAI,QAAQ,MAAQ,SAAS,KAC3B,OAAO;CAEX;CACA,OAAO;AACT"}
+{"version":3,"file":"safe-href.js","names":[],"sources":["../../src/utils/safe-href.ts"],"sourcesContent":["export type SafeHrefRejection =\n  | 'blank'\n  | 'malformed'\n  | 'protocol-relative'\n  | 'forbidden-scheme'\n  | 'absolute'\n  | 'sign-in-route';\n\nexport type SafeHrefResult = { safe: true; href: string } | { safe: false; reason: SafeHrefRejection };\n\nconst ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:']);\n\n/**\n * The only gate on a CMS-authored destination: `http:`, `https:`, `mailto:`, `tel:`, and paths\n * starting with a single `/`. The runtime slice does not enforce a model's `pattern`, and the sukima\n * preflight that does never sees content published after a deploy, so an authored `javascript:` value\n * can reach the component intact and this is what stands between it and an `href`.\n *\n * Rejects rather than sanitizes: a destination that comes back safe is character-for-character the\n * trimmed authored value, so no value is ever silently rewritten into a different working one.\n */\nexport function resolveSafeHref(raw: string): SafeHrefResult {\n  const href = raw.trim();\n  if (href.length === 0) {\n    return { safe: false, reason: 'blank' };\n  }\n  // Browsers strip ASCII tabs and newlines from a URL before parsing it, so `java<TAB>script:alert(1)`\n  // executes. Refusing the whole value is the only defense that does not depend on stripping the same\n  // characters in the same order the parser does.\n  if (hasStrippableCharacter(href)) {\n    return { safe: false, reason: 'malformed' };\n  }\n  // A URL parser reads `\\` as `/` under a special scheme, so `/\\evil.example` resolves against the\n  // store's origin as an authority rather than a path. Any pair of leading slashes is an off-site\n  // jump however it is spelled, and only `//` looks like one.\n  if (/^[/\\\\]{2}/.test(href)) {\n    return { safe: false, reason: 'protocol-relative' };\n  }\n  if (href.startsWith('/')) {\n    return { safe: true, href };\n  }\n\n  let protocol: string;\n  try {\n    protocol = new URL(href).protocol;\n  } catch {\n    return { safe: false, reason: 'malformed' };\n  }\n  // `new URL` lowercases the protocol, so `JavaScript:` and `javascript:` are the same rejection.\n  return ALLOWED_PROTOCOLS.has(protocol) ? { safe: true, href } : { safe: false, reason: 'forbidden-scheme' };\n}\n\n/** The storefront's own sign-in route, which forwards to the platform's login. A fixed convention,\n *  never an authored value. */\nconst SIGN_IN_ROUTE = '/login';\n\n/** The parameter carrying the shopper's way back, read by the sign-in route and the platform's login. */\nexport const RETURN_URL_PARAM = 'returnUrl';\n\n/**\n * `resolveSafeHref` narrowed to the site-relative subset: the destinations a shopper may be sent back to\n * across the auth hop. The allowlist admits absolute http(s) values, which are legitimate for an authored\n * link but are exactly what would turn the hop into an open redirect. Every other rejection travels out\n * unchanged, so a caller logging the reason still sees which spelling arrived.\n *\n * Both ends of the flow narrow through here rather than only the sender, because the sender cannot vouch\n * for a URL the shopper typed: the account button builds the destination through `resolveSignInHref`, and\n * the sign-in route revalidates what arrives through `resolveReturnHref`.\n */\nexport function resolveSiteRelativeHref(raw: string): SafeHrefResult {\n  const destination = resolveSafeHref(raw);\n  if (!destination.safe) {\n    return destination;\n  }\n  return destination.href.startsWith('/') ? destination : { safe: false, reason: 'absolute' };\n}\n\n/** The subset of the allowlist that resolves to a page a document can be handed over to. */\nconst NAVIGABLE_PROTOCOLS = new Set(['http:', 'https:']);\n\n/**\n * `resolveSafeHref` narrowed to the destinations that resolve to a page: site-relative, or absolute\n * `http(s)`. `mailto:` and `tel:` are legitimate for an authored link and refused here, since handing a\n * document over to one leaves the shopper in a mail client instead of a login.\n */\nexport function resolveNavigableHref(raw: string): SafeHrefResult {\n  const destination = resolveSafeHref(raw);\n  if (!destination.safe || destination.href.startsWith('/')) {\n    return destination;\n  }\n  // The allowlist already parsed this value, so the protocol is readable without a second guard.\n  const { protocol } = new URL(destination.href);\n  return NAVIGABLE_PROTOCOLS.has(protocol) ? destination : { safe: false, reason: 'forbidden-scheme' };\n}\n\n/**\n * `resolveSiteRelativeHref` narrowed further, for a return arriving at the sign-in route: the route\n * itself is refused. Admitting it sends a shopper who just authenticated back to the trampoline, which\n * hands them to the platform a second time — a sign-in that never lands where the parameter promised.\n */\nexport function resolveReturnHref(raw: string): SafeHrefResult {\n  const destination = resolveSiteRelativeHref(raw);\n  if (!destination.safe) {\n    return destination;\n  }\n  return isSignInRoute(destination.href) ? { safe: false, reason: 'sign-in-route' } : destination;\n}\n\n/** Whether a site-relative value names the storefront's own sign-in route, in any of its spellings. */\nexport function isSignInRoute(href: string): boolean {\n  return pathOf(href) === SIGN_IN_ROUTE;\n}\n\n/**\n * `resolveNavigableHref` narrowed for the address a handover targets: the storefront's own sign-in\n * route is refused. Sending `/login` to `/login` reloads the same document, which mounts the same\n * handover again — a loop the shopper never gets past, and the mirror of the refusal\n * `resolveReturnHref` already makes on the way back.\n *\n * Only the site-relative spelling is decidable here, being same-origin by construction. An absolute\n * address needs the document's own origin to compare against, which this module does not have and a\n * prerender does not either, so `isSignInRoute` is exported for the caller that does. A cross-origin\n * login page whose path happens to be `/login` is a different page and is left alone.\n */\nexport function resolveLoginAddressHref(raw: string): SafeHrefResult {\n  const address = resolveNavigableHref(raw);\n  if (!address.safe || !address.href.startsWith('/')) {\n    return address;\n  }\n  return isSignInRoute(address.href) ? { safe: false, reason: 'sign-in-route' } : address;\n}\n\n/**\n * Builds the sign-in destination, carrying the current path so the shopper can be returned where they\n * started. The sender's half only: nothing stops a hand-crafted link, so the sign-in route is to narrow\n * the parameter again on arrival. A path the narrowing refuses drops the parameter instead of\n * travelling encoded, and so does a router reporting no path — `usePathname()`'s type is why this takes\n * a nullable one.\n */\nexport function resolveSignInHref(pathname: string | null): string {\n  if (!pathname) {\n    return SIGN_IN_ROUTE;\n  }\n  const destination = resolveSiteRelativeHref(pathname);\n  if (!destination.safe) {\n    return SIGN_IN_ROUTE;\n  }\n  return `${SIGN_IN_ROUTE}?${RETURN_URL_PARAM}=${encodeURIComponent(destination.href)}`;\n}\n\n/** Opaque base for resolving a site-relative value to a path. Reserved by RFC 6761, so it never names a\n *  real host; nothing is navigated to it and only `pathname` is read back. */\nconst PATH_COMPARISON_BASE = 'https://store.invalid';\n\n/**\n * The path of a site-relative value, without its query or fragment and without a trailing slash, so a\n * route comparison reads the route rather than one of its spellings. `/loginhelp` is a different path\n * and stays one.\n *\n * Parsed rather than sliced, because `/account/../login`, `/account\\..\\login` and `/account/%2e%2e/login`\n * are all spellings a URL parser resolves to `/login`. A slice compares them literally and admits them,\n * and the value then reaches a receiver that does resolve them — which puts the shopper back on the\n * trampoline the refusal exists to prevent. Only the comparison is normalized: the caller returns the\n * value as it arrived, so the promise that nothing is silently rewritten still holds.\n */\nfunction pathOf(href: string): string {\n  const { pathname } = new URL(href, PATH_COMPARISON_BASE);\n  return pathname.replace(/\\/+$/, '') || '/';\n}\n\n/** Any C0 control or space anywhere in the value — the set a URL parser removes or trims. */\nfunction hasStrippableCharacter(value: string): boolean {\n  for (const character of value) {\n    const code = character.codePointAt(0) ?? 0;\n    if (code <= 0x20 || code === 0x7f) {\n      return true;\n    }\n  }\n  return false;\n}\n"],"mappings":";AAUA,MAAM,oCAAoB,IAAI,IAAI;CAAC;CAAS;CAAU;CAAW;AAAM,CAAC;;;;;;;;;;AAWxE,SAAgB,gBAAgB,KAA6B;CAC3D,MAAM,OAAO,IAAI,KAAK;CACtB,IAAI,KAAK,WAAW,GAClB,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAQ;CAKxC,IAAI,uBAAuB,IAAI,GAC7B,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAY;CAK5C,IAAI,YAAY,KAAK,IAAI,GACvB,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAoB;CAEpD,IAAI,KAAK,WAAW,GAAG,GACrB,OAAO;EAAE,MAAM;EAAM;CAAK;CAG5B,IAAI;CACJ,IAAI;EACF,WAAW,IAAI,IAAI,IAAI,CAAC,CAAC;CAC3B,QAAQ;EACN,OAAO;GAAE,MAAM;GAAO,QAAQ;EAAY;CAC5C;CAEA,OAAO,kBAAkB,IAAI,QAAQ,IAAI;EAAE,MAAM;EAAM;CAAK,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAmB;AAC5G;;;AAIA,MAAM,gBAAgB;;AAGtB,MAAa,mBAAmB;;;;;;;;;;;AAYhC,SAAgB,wBAAwB,KAA6B;CACnE,MAAM,cAAc,gBAAgB,GAAG;CACvC,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,YAAY,KAAK,WAAW,GAAG,IAAI,cAAc;EAAE,MAAM;EAAO,QAAQ;CAAW;AAC5F;;AAGA,MAAM,sCAAsB,IAAI,IAAI,CAAC,SAAS,QAAQ,CAAC;;;;;;AAOvD,SAAgB,qBAAqB,KAA6B;CAChE,MAAM,cAAc,gBAAgB,GAAG;CACvC,IAAI,CAAC,YAAY,QAAQ,YAAY,KAAK,WAAW,GAAG,GACtD,OAAO;CAGT,MAAM,EAAE,aAAa,IAAI,IAAI,YAAY,IAAI;CAC7C,OAAO,oBAAoB,IAAI,QAAQ,IAAI,cAAc;EAAE,MAAM;EAAO,QAAQ;CAAmB;AACrG;;;;;;AAOA,SAAgB,kBAAkB,KAA6B;CAC7D,MAAM,cAAc,wBAAwB,GAAG;CAC/C,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,cAAc,YAAY,IAAI,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAgB,IAAI;AACtF;;AAGA,SAAgB,cAAc,MAAuB;CACnD,OAAO,OAAO,IAAI,MAAM;AAC1B;;;;;;;;;;;;AAaA,SAAgB,wBAAwB,KAA6B;CACnE,MAAM,UAAU,qBAAqB,GAAG;CACxC,IAAI,CAAC,QAAQ,QAAQ,CAAC,QAAQ,KAAK,WAAW,GAAG,GAC/C,OAAO;CAET,OAAO,cAAc,QAAQ,IAAI,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAgB,IAAI;AAClF;;;;;;;;AASA,SAAgB,kBAAkB,UAAiC;CACjE,IAAI,CAAC,UACH,OAAO;CAET,MAAM,cAAc,wBAAwB,QAAQ;CACpD,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,GAAG,cAAc,GAAG,iBAAiB,GAAG,mBAAmB,YAAY,IAAI;AACpF;;;AAIA,MAAM,uBAAuB;;;;;;;;;;;;AAa7B,SAAS,OAAO,MAAsB;CACpC,MAAM,EAAE,aAAa,IAAI,IAAI,MAAM,oBAAoB;CACvD,OAAO,SAAS,QAAQ,QAAQ,EAAE,KAAK;AACzC;;AAGA,SAAS,uBAAuB,OAAwB;CACtD,KAAK,MAAM,aAAa,OAAO;EAC7B,MAAM,OAAO,UAAU,YAAY,CAAC,KAAK;EACzC,IAAI,QAAQ,MAAQ,SAAS,KAC3B,OAAO;CAEX;CACA,OAAO;AACT"}

package/dist/utils/substitute-template.js

@@ -0,0 +1,33 @@
+//#region src/utils/substitute-template.ts
+const TOKEN_PATTERN = /\{(\w+)\}/g;
+/**
+* Shared copy-template substitution (T97, T31 — specs/make-the-payment-components-authored-copy.md
+* Decision 7). Replaces every seven-plus `String.prototype.replace('{token}', value)` call sites
+* across `payment-summary.tsx`, `order-placed-payment-summary.tsx`, and `installments.tsx`, each of
+* which substituted only the *first* occurrence of a token and, at two sites, passed the value as a
+* replacement *string* — letting a server-sourced value containing `$&`/`` $` ``/`$'`/`$$` rewrite the
+* surrounding template text.
+*
+* One `/\{(\w+)\}/g` pass with a replacer *function*: every occurrence of every token is substituted
+* in a single scan, every value is inserted literally (a function's return value is never
+* re-interpreted as a replacement pattern), and a token with no matching entry in `tokens` is left
+* verbatim — so a template can be reworded freely without this helper silently dropping an
+* unrecognized placeholder. Because it is one pass, a substituted value can never itself be re-scanned
+* by a later token's own substitution.
+*
+* `Object.hasOwn`, not `tokenName in tokens` or a bare index lookup (fix pass, finding 6): every plain
+* object inherits from `Object.prototype`, so `tokens['toString']` resolves to
+* `Object.prototype.toString` — a function, therefore never `null`/`undefined` — rather than falling
+* through to `match` on a `??` lookup. `{toString}`, `{constructor}`, and `{__proto__}` would each
+* silently render an inherited value instead of being left verbatim as documented above.
+*/
+function substituteTemplate(template, tokens) {
+	return template.replace(TOKEN_PATTERN, (match, tokenName) => {
+		if (!Object.hasOwn(tokens, tokenName)) return match;
+		return tokens[tokenName] ?? match;
+	});
+}
+//#endregion
+export { substituteTemplate };
+
+//# sourceMappingURL=substitute-template.js.map

package/dist/utils/substitute-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"substitute-template.js","names":[],"sources":["../../src/utils/substitute-template.ts"],"sourcesContent":["const TOKEN_PATTERN = /\\{(\\w+)\\}/g;\n\n/**\n * Shared copy-template substitution (T97, T31 — specs/make-the-payment-components-authored-copy.md\n * Decision 7). Replaces every seven-plus `String.prototype.replace('{token}', value)` call sites\n * across `payment-summary.tsx`, `order-placed-payment-summary.tsx`, and `installments.tsx`, each of\n * which substituted only the *first* occurrence of a token and, at two sites, passed the value as a\n * replacement *string* — letting a server-sourced value containing `$&`/`` $` ``/`$'`/`$$` rewrite the\n * surrounding template text.\n *\n * One `/\\{(\\w+)\\}/g` pass with a replacer *function*: every occurrence of every token is substituted\n * in a single scan, every value is inserted literally (a function's return value is never\n * re-interpreted as a replacement pattern), and a token with no matching entry in `tokens` is left\n * verbatim — so a template can be reworded freely without this helper silently dropping an\n * unrecognized placeholder. Because it is one pass, a substituted value can never itself be re-scanned\n * by a later token's own substitution.\n *\n * `Object.hasOwn`, not `tokenName in tokens` or a bare index lookup (fix pass, finding 6): every plain\n * object inherits from `Object.prototype`, so `tokens['toString']` resolves to\n * `Object.prototype.toString` — a function, therefore never `null`/`undefined` — rather than falling\n * through to `match` on a `??` lookup. `{toString}`, `{constructor}`, and `{__proto__}` would each\n * silently render an inherited value instead of being left verbatim as documented above.\n */\nexport function substituteTemplate(template: string, tokens: Readonly<Record<string, string>>): string {\n  return template.replace(TOKEN_PATTERN, (match, tokenName: string) => {\n    if (!Object.hasOwn(tokens, tokenName)) return match;\n    // `noUncheckedIndexedAccess` still types this lookup as `string | undefined`; the `Object.hasOwn`\n    // check above is what actually guarantees a string is here, so this `??` can never fall through\n    // for a real token — it only satisfies the index-signature type, never re-opens finding 6's bug.\n    return tokens[tokenName] ?? match;\n  });\n}\n"],"mappings":";AAAA,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;AAuBtB,SAAgB,mBAAmB,UAAkB,QAAkD;CACrG,OAAO,SAAS,QAAQ,gBAAgB,OAAO,cAAsB;EACnE,IAAI,CAAC,OAAO,OAAO,QAAQ,SAAS,GAAG,OAAO;EAI9C,OAAO,OAAO,cAAc;CAC9B,CAAC;AACH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/faststore",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "FastStore AI Native component library built on Base UI with AI-editable styles",
   "license": "MIT",
   "homepage": "https://developers.vtex.com/docs/guides/faststore",
@@ -52,6 +52,7 @@
     "@base-ui/react": "^1.3.0",
     "@graphql-typed-document-node/core": "^3.2.0",
     "graphql": "^16.13.1",
+    "react-hook-form": "^7.85.0",
     "react-intl": "^10.1.22",
     "rxjs": "^7.8.2",
     "tailwindcss": "^4.2.2",

package/src/styles/tailwind.css

@@ -30,3 +30,37 @@
   --max-width-md: var(--container-md);
   --max-width-lg: var(--container-lg);
 }
+
+@layer base {
+  /* Default visible focus indicator for the payment surface (T38, REQ-11's WCAG scenario).
+     `@layer base` so any merchant utility class outranks it under Tailwind 4's layer order.
+     `currentColor` because the merchant's palette is unknown here — see Decision 6 on contrast.
+     Scoped by an explicit hook list, not by an ancestor: `PaymentSectionController` renders no DOM
+     element, so no ancestor selector reaches a controller-composed page. */
+  [data-fs-payment-method-list] :focus-visible,
+  [data-fs-installments] :focus-visible,
+  [data-fs-saved-cards] :focus-visible,
+  [data-fs-billing-address] :focus-visible,
+  [data-fs-card-entry] :focus-visible,
+  [data-fs-cardholder-document] :focus-visible,
+  [data-fs-save-card] :focus-visible,
+  [data-fs-place-order] :focus-visible,
+  [data-fs-installments-option]:focus-visible {
+    outline: 2px solid currentColor;
+    outline-offset: 2px;
+  }
+
+  /* `<fieldset>` carries `min-inline-size: min-content`, which Tailwind's preflight does not reset,
+     so it refuses to shrink inside a flex row. Live already via CardEntry's fieldset; mitigated here
+     for the three groups T38 adds. Scoped by the same explicit hook-list approach as the focus rule
+     above, not by `[data-fs-fieldset-root]`: the Fieldset particle emits that attribute
+     unconditionally, so it also reaches `ClientProfileForm`'s optional grouping fieldset — a
+     non-payment component whose rendering must not change (measured: 95px vs. 113px in a 200px flex
+     row with a competing sibling). */
+  [data-fs-payment-method-list-fieldset],
+  [data-fs-installments-fieldset],
+  [data-fs-saved-cards-fieldset],
+  [data-fs-card-entry-fieldset] {
+    min-inline-size: 0;
+  }
+}

package/dist/docs/client-profile-form.md

@@ -1,192 +0,0 @@
-# ClientProfileForm
-
-**Category:** identity
-**Purpose:** The batched customer-information form for the checkout identity step — the `InformationFormUSA` replacement. Pre-fills first/last name, phone, document, and both consent opt-ins from the shopper's saved profile and preferences; displays the email read-only. A single Save / Continue action validates the draft and dispatches at most one `clientProfileUpdate` and one `clientPreferencesUpdate`, each carrying only the fields the shopper edited, with pending/confirmation/error feedback.
-
----
-
-## Visual cues (how to identify in an image)
-
-- A single form block on a checkout identity step titled "Your information" (or similar), grouping: a read-only email display, first name, last name, a country-masked phone field, an optional tax-document field (e.g. CPF for Brazil), and two checkboxes ("email me with news and offers", "save my information for next time").
-- One visible primary button at the bottom labelled "Save and continue" (or similar) — not a hidden submit.
-- Pre-filled values for a returning/identified shopper; blank, still-editable fields for a guest or an incomplete profile.
-- An inline error banner on failure, or a confirmation line on success, appearing near the button.
-
-Use `ClientProfileForm` (not a hand-assembled combination of `Field`/`PhoneField`/`DocumentField`) whenever the image shows this whole batched-save customer-information block.
-
----
-
-## When to use
-
-- The customer-information section of the checkout identity step, for both returning/identified shoppers (pre-fill + edit) and guests (fill from empty).
-- Anywhere name, phone, document, and consent opt-ins must be collected together and persisted in one explicit action.
-
-## When NOT to use
-
-- Editing the email — that is `EmailIdentificationControl`'s job; this form only displays it.
-- A single standalone phone or opt-in field with its own save-on-blur behavior — use `ClientProfilePhoneControl` / `NewsletterOptInControl` / `SavePersonalDataOptInControl` instead. **Never place a standalone per-field identity Control and this form for the same field on the same view** — both would write the field, racing each other.
-- Address fields — those belong to Delivery, not this form.
-
----
-
-## Composition
-
-`ClientProfileForm` is a **compound**: `Root` owns the data + mechanics; the field/fieldset/feedback
-parts are composed freely (any order, any subset). The schema author decides which fields render — a
-merchant whose platform config drops a field (or whose account can't persist one, e.g. an unsupported
-`savePersonalData`) simply does not compose that part.
-
-```
-SessionRoot                                 (required ancestor; session tri-state + canEditData)
-└── ClientProfileForm.Root                  (data-fs-client-profile-form; own fragment/data root; owns draft + Save)
-    ├── ClientProfileForm.Fieldset section="profile" [legend]
-    │     ├── .EmailField                    (read-only)
-    │     ├── .FirstNameField / .LastNameField
-    │     ├── .PhoneField                    (uses country from Root)
-    │     └── .DocumentField                 (self-gates on documentType)
-    ├── ClientProfileForm.Fieldset section="preferences" [legend]
-    │     ├── .NewsletterCheckbox
-    │     └── .SavePersonalDataCheckbox       (omit to drop the field entirely — no CSS hack)
-    ├── .Error / .Confirmation
-    └── .SubmitButton
-```
-
-`Root` is self-contained: it declares the colocated fragment over `clientProfile` + `clientPreferences`
-and must not be nested inside `ClientProfileRoot` / `ClientPreferencesRoot` (those self-persist per
-field on blur, double-writing against this form's batched Save). Every part `requiresContext:
-'client-profile-form'`; a custom/derived field declares its own additional `requiresContext`.
-
----
-
-## Behavior
-
-- **Sections**: compose `ClientProfileForm.Fieldset` blocks with a `section` name → `data-fs-client-profile-form-section="<name>"`, and an optional `legend`. Not hard-coded — the author groups fields however the design needs.
-- **Pre-fill**: every field seeds from `$data` on mount; missing profile fields render empty and stay editable.
-- **Draft & dirty tracking**: edits are tracked locally per field; only touched fields are dispatched. Background `$data` refreshes re-seed untouched fields only — an in-progress edit is never clobbered.
-- **Save**: validates **field format only** — phone mask and document check-digit, each blocking Save when the field is non-empty and malformed. It does not enforce requiredness: the parts are composed freely by the schema, so a required check here could fire for a field the page never mounted. Which fields a shopper must fill is a business rule, waiting on the composable entity forms RFC (#572) to decide where it belongs. The format checks carry the same composition hazard in a narrower form, and it is still open: they key off the Root's `country` and `documentType` rather than off which leaves were composed, so a store that sets `documentType` without composing `DocumentField` can block Save with no field to render the error in and nowhere to move focus. Closing it properly means the leaves registering themselves with the Root, which is that same RFC's territory. The phone case is wider than the document one and needs no merchant configuration at all — see Known gaps below. On Save it dispatches at most one `clientProfileUpdate` (dirty profile fields) and one `clientPreferencesUpdate` (dirty consent flags) in parallel; a Save with nothing dirty dispatches nothing and shows the confirmation, so the press still answers.
-- **Document erase**: clearing a previously-saved document and pressing Save sends `document: ''` — an explicit erase, not an omission.
-- **Feedback**: `data-fs-client-profile-form-pending` while a write is in flight (fieldset disabled, Save not re-triggerable); an inline `role="alert"` region on `userErrors`; an `<output>` confirmation on success, cleared on the next edit.
-- **Read-only**: `session.canEditData === false` renders `data-fs-client-profile-form-readonly`, disables every field, and omits the Save button entirely.
-- **The form announces nothing**: a completed Save shows the confirmation and stops there. It publishes no signal, so nothing elsewhere collapses, advances or reacts. Whether finishing this form should move a section or a wizard is a sequencing question, and the mechanism for it is being designed in the flow-of-steps RFC (#611) rather than assumed here.
-- **The form never learns who listens.** It reports nothing at all, so `IdentityEditController` cannot react to it: that section moves only on its own buttons. Compose the swap around this form: an `IdentityEditController` holding an `IdentitySummaryView` with the summary, an `IdentityEditForm` with `ClientProfileForm.Root`, an `IdentityEditButton` in the heading, and an `IdentityEditCancelButton` as cancel next to the form. The same form therefore works unchanged inside a collapsing section or on a page of its own.
-
----
-
-## Props
-
-**`ClientProfileForm.Root`** — `country` (`'US' | 'BR'`, default `'US'`; provided to the phone leaf via
-context), `documentType` (string, e.g. `'CPF'`; the document leaf renders only when supported).
-Declares `actions: { identity: ['clientProfileUpdate', 'clientPreferencesUpdate'] }`,
-`requiresContext: 'session'`, `providesContext: 'client-profile-form'`.
-
-**`ClientProfileForm.Fieldset`** — `legend` (optional visible title), `section` (name → `data-fs-*-section`).
-
-**Field parts** (`.EmailField`, `.FirstNameField`, `.LastNameField`, `.PhoneField`, `.DocumentField`,
-`.NewsletterCheckbox`, `.SavePersonalDataCheckbox`) — each takes an optional `label` (sensible default).
-**`.Confirmation`** — `message` (default `'Your information has been saved.'`). **`.SubmitButton`** —
-`label` (default `'Save and continue'`) or composed `children`.
-
----
-
-## Canonical schema example
-
-```json
-{
-  "session": {
-    "type": "SessionRoot",
-    "children": ["email-identification", "profile-form"]
-  },
-  "email-identification": {
-    "type": "EmailIdentificationControl",
-    "children": []
-  },
-  "profile-form": {
-    "type": "ClientProfileFormRoot",
-    "props": { "country": "BR", "documentType": "CPF" },
-    "children": ["profile-fieldset", "preferences-fieldset", "form-error", "form-confirmation", "form-submit"]
-  },
-  "profile-fieldset": {
-    "type": "ClientProfileFormFieldset",
-    "props": { "section": "profile", "legend": "Your information" },
-    "children": ["email", "first-name", "last-name", "phone", "document"]
-  },
-  "email": { "type": "ClientProfileFormEmailField", "children": [] },
-  "first-name": { "type": "ClientProfileFormFirstNameField", "children": [] },
-  "last-name": { "type": "ClientProfileFormLastNameField", "children": [] },
-  "phone": { "type": "ClientProfileFormPhoneField", "children": [] },
-  "document": { "type": "ClientProfileFormDocumentField", "children": [] },
-  "preferences-fieldset": {
-    "type": "ClientProfileFormFieldset",
-    "props": { "section": "preferences" },
-    "children": ["newsletter"]
-  },
-  "newsletter": { "type": "ClientProfileFormNewsletterCheckbox", "children": [] },
-  "form-error": { "type": "ClientProfileFormError", "children": [] },
-  "form-confirmation": { "type": "ClientProfileFormConfirmation", "children": [] },
-  "form-submit": { "type": "ClientProfileFormSubmitButton", "children": [] }
-}
-```
-
-Both fieldsets are children of the Root, not siblings of it: every part declares
-`requiresContext: 'client-profile-form'`, so a fieldset placed outside is rejected by the
-context-constraint walk at build time.
-
-(Omitting `ClientProfileFormSavePersonalDataCheckbox` above drops that field entirely — the intended
-way to exclude a field the account can't persist, with no CSS hack and no shared-component change.)
-
----
-
-## Common mistakes
-
-- **Rendering `ClientProfileForm` outside `SessionRoot`.** `useSession()` throws; every identity page must host a `SessionRoot`.
-- **Nesting it inside `ClientProfileRoot` / `ClientPreferencesRoot`, or placing a standalone Control for the same field alongside it.** The form is its own data root and its own write surface — double-nesting or double-placing creates a double-write race.
-- **Expecting the email to be editable.** It is always read-only here; email changes go through `EmailIdentificationControl`.
-- **Expecting per-keystroke or per-blur saves.** All fields are form-bound; only pressing Save dispatches a write.
-- **Expecting the form to enforce required fields.** It validates format only. A blank field saves, because the form cannot know which of its freely-composed parts the page actually mounted.
-- **Rendering a field part outside `ClientProfileForm.Root`.** Every part `requiresContext: 'client-profile-form'` and throws otherwise.
-
----
-
-## Styling
-
-| Component | What you style | Plausible classes |
-|---|---|---|
-| `ClientProfileForm` | The `data-fs-client-profile-form` root; carries `-pending`/`-readonly`/`-saved` presence attributes | `flex flex-col gap-10` |
-| Section | `data-fs-client-profile-form-section="profile\|preferences"` — the two entity-anchored fieldsets | `flex flex-col gap-4` |
-| Field wrapper | `data-fs-client-profile-form-field="email\|first-name\|last-name\|phone\|document\|newsletter\|save-personal-data"` | `flex flex-col gap-4` |
-| Error / confirmation | `[data-fs-client-profile-form-error]` / `[data-fs-client-profile-form-confirmation]` | `text-sm text-red-600` / `text-sm text-green-600` |
-
-Field-level visuals (borders, focus rings, error color) are owned by the composed particles' own swatches (`field`, `phone-field`, `document-field`, `checkbox`, `button`) and are not redefined here.
-
----
-
-## Known gaps
-
-Found by review and deliberately left for the dedicated revision of these components, rather than patched
-here. The first is the widest.
-
-- **Format validation runs against fields the page may never have composed, and the phone case needs no
-  merchant configuration at all.** `country` defaults to `'US'`, so the phone check always runs. A store
-  composing `Root` + name fields + `SubmitButton`, serving a shopper whose stored phone is a legacy
-  malformed value, gets a Save that sets `errors.phone`, finds no phone input to focus, renders no message
-  because `PhoneField` is not mounted, and returns — dead on every press, button still enabled. The
-  `documentType` variant of the same hole at least requires the merchant to have set a Root prop. Closing
-  both properly means the leaves registering themselves with the Root; see the composable entity forms RFC
-  (#572).
-- **Two other early returns leave Save silent.** A missing `$actions.identity`, or a dirty field with no
-  matching write function, returns without touching `pending`, `serverError` or `saved` — the same dead
-  press the pristine branch above was changed to avoid.
-- **`VALIDATION_ORDER` is a hard-coded `['phone', 'document']`,** but the leaves are now composed in any
-  order. With both fields malformed, focus jumps to the phone input even when the document error is the one
-  the shopper can see first. The order should come from DOM position now that the fixed template is gone.
-- **The re-seed of untouched fields mutates a ref during render** and queues its `setDraft` in the same
-  pass. A discarded render keeps the ref but loses the update, so pristine fields can hold stale values
-  after `$data` arrives.
-
-## Related
-
-- [[email-identification]] — the sibling identification control this form's email display defers to.
-- [[client-profile]] — the standalone, per-field-blur phone binding; do not compose alongside this form for the same field.
-- [[client-preferences]] — the standalone, per-field-blur consent Controls; do not compose alongside this form for the same field.
-- [[session]] — provides the identification tri-state and the required `SessionRoot` ancestor.
-- [[phone-field]], [[document-field]], [[field]], [[fieldset]], [[checkbox]] — the particles this matter composes directly.