@vtex/faststore 0.0.7 → 0.0.8

package/dist/utils/safe-href.d.ts

@@ -1,11 +1,11 @@
+import { PageRef } from "../sdk/navigation/types.js";
 //#region src/utils/safe-href.d.ts
 /**
- * Builds the sign-in destination, carrying the current path so the shopper can be returned where they
+ * The sign-in page, carrying the current logical path so the shopper can be returned where they
  * started. The sender's half only: nothing stops a hand-crafted link, so the sign-in route is to narrow
  * the parameter again on arrival. A path the narrowing refuses drops the parameter instead of
- * travelling encoded, and so does a router reporting no path — `usePathname()`'s type is why this takes
- * a nullable one.
+ * travelling encoded, and so does a router reporting no path.
  */
-export declare function resolveSignInHref(pathname: string | null): string;
+export declare function signInTarget(path: string | null): PageRef;
 //#endregion
 //# sourceMappingURL=safe-href.d.ts.map

package/dist/utils/safe-href.js

@@ -49,9 +49,8 @@ function resolveSafeHref(raw) {
 		reason: "forbidden-scheme"
 	};
 }
-/** The storefront's own sign-in route, which forwards to the platform's login. A fixed convention,
-*  never an authored value. */
-const SIGN_IN_ROUTE = "/login";
+/** The storefront's own sign-in page, which forwards to the platform's login. Never an authored value. */
+const SIGN_IN_PAGE = { standard: "sign-in" };
 /** The parameter carrying the shopper's way back, read by the sign-in route and the platform's login. */
 const RETURN_URL_PARAM = "returnUrl";
 /**
@@ -61,7 +60,7 @@ const RETURN_URL_PARAM = "returnUrl";
 * unchanged, so a caller logging the reason still sees which spelling arrived.
 *
 * Both ends of the flow narrow through here rather than only the sender, because the sender cannot vouch
-* for a URL the shopper typed: the account button builds the destination through `resolveSignInHref`, and
+* for a URL the shopper typed: the account button builds the destination through `signInTarget`, and
 * the sign-in route revalidates what arrives through `resolveReturnHref`.
 */
 function resolveSiteRelativeHref(raw) {
@@ -92,50 +91,60 @@ function resolveNavigableHref(raw) {
 * `resolveSiteRelativeHref` narrowed further, for a return arriving at the sign-in route: the route
 * itself is refused. Admitting it sends a shopper who just authenticated back to the trampoline, which
 * hands them to the platform a second time — a sign-in that never lands where the parameter promised.
+*
+* `signInPath` is the sign-in page's logical path, since a return is one; `null` when the store has no
+* sign-in page, and then no return is the route.
 */
-function resolveReturnHref(raw) {
+function resolveReturnHref(raw, signInPath) {
 	const destination = resolveSiteRelativeHref(raw);
 	if (!destination.safe) return destination;
-	return isSignInRoute(destination.href) ? {
+	return isSignInRoute(destination.href, signInPath) ? {
 		safe: false,
 		reason: "sign-in-route"
 	} : destination;
 }
-/** Whether a site-relative value names the storefront's own sign-in route, in any of its spellings. */
-function isSignInRoute(href) {
-	return pathOf(href) === SIGN_IN_ROUTE;
+/**
+* Whether a site-relative value names the sign-in page at `signInPath`, in any of its spellings. `null`
+* is a store without a sign-in page, where nothing is the route.
+*/
+function isSignInRoute(href, signInPath) {
+	return signInPath !== null && pathOf(href) === pathOf(signInPath);
 }
 /**
 * `resolveNavigableHref` narrowed for the address a handover targets: the storefront's own sign-in
-* route is refused. Sending `/login` to `/login` reloads the same document, which mounts the same
+* route is refused. Sending the route to itself reloads the same document, which mounts the same
 * handover again — a loop the shopper never gets past, and the mirror of the refusal
 * `resolveReturnHref` already makes on the way back.
 *
 * Only the site-relative spelling is decidable here, being same-origin by construction. An absolute
 * address needs the document's own origin to compare against, which this module does not have and a
 * prerender does not either, so `isSignInRoute` is exported for the caller that does. A cross-origin
-* login page whose path happens to be `/login` is a different page and is left alone.
+* login page whose path happens to be the route's is a different page and is left alone.
+*
+* `signInPath` is the sign-in page's public path, since the address is a document URL.
 */
-function resolveLoginAddressHref(raw) {
+function resolveLoginAddressHref(raw, signInPath) {
 	const address = resolveNavigableHref(raw);
 	if (!address.safe || !address.href.startsWith("/")) return address;
-	return isSignInRoute(address.href) ? {
+	return isSignInRoute(address.href, signInPath) ? {
 		safe: false,
 		reason: "sign-in-route"
 	} : address;
 }
 /**
-* Builds the sign-in destination, carrying the current path so the shopper can be returned where they
+* The sign-in page, carrying the current logical path so the shopper can be returned where they
 * started. The sender's half only: nothing stops a hand-crafted link, so the sign-in route is to narrow
 * the parameter again on arrival. A path the narrowing refuses drops the parameter instead of
-* travelling encoded, and so does a router reporting no path — `usePathname()`'s type is why this takes
-* a nullable one.
+* travelling encoded, and so does a router reporting no path.
 */
-function resolveSignInHref(pathname) {
-	if (!pathname) return SIGN_IN_ROUTE;
-	const destination = resolveSiteRelativeHref(pathname);
-	if (!destination.safe) return SIGN_IN_ROUTE;
-	return `${SIGN_IN_ROUTE}?${RETURN_URL_PARAM}=${encodeURIComponent(destination.href)}`;
+function signInTarget(path) {
+	if (!path) return SIGN_IN_PAGE;
+	const destination = resolveSiteRelativeHref(path);
+	if (!destination.safe) return SIGN_IN_PAGE;
+	return {
+		standard: "sign-in",
+		query: { [RETURN_URL_PARAM]: destination.href }
+	};
 }
 /** Opaque base for resolving a site-relative value to a path. Reserved by RFC 6761, so it never names a
 *  real host; nothing is navigated to it and only `pathname` is read back. */
@@ -164,6 +173,6 @@ function hasStrippableCharacter(value) {
 	return false;
 }
 //#endregion
-export { RETURN_URL_PARAM, isSignInRoute, resolveLoginAddressHref, resolveNavigableHref, resolveReturnHref, resolveSafeHref, resolveSignInHref, resolveSiteRelativeHref };
+export { RETURN_URL_PARAM, SIGN_IN_PAGE, isSignInRoute, resolveLoginAddressHref, resolveNavigableHref, resolveReturnHref, resolveSafeHref, resolveSiteRelativeHref, signInTarget };
 
 //# sourceMappingURL=safe-href.js.map

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 `/`. 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"}
+{"version":3,"file":"safe-href.js","names":[],"sources":["../../src/utils/safe-href.ts"],"sourcesContent":["import type { PageRef } from '../sdk/navigation/types.js';\n\nexport 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 page, which forwards to the platform's login. Never an authored value. */\nexport const SIGN_IN_PAGE: PageRef = { standard: 'sign-in' };\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 `signInTarget`, 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 *\n * `signInPath` is the sign-in page's logical path, since a return is one; `null` when the store has no\n * sign-in page, and then no return is the route.\n */\nexport function resolveReturnHref(raw: string, signInPath: string | null): SafeHrefResult {\n  const destination = resolveSiteRelativeHref(raw);\n  if (!destination.safe) {\n    return destination;\n  }\n  return isSignInRoute(destination.href, signInPath) ? { safe: false, reason: 'sign-in-route' } : destination;\n}\n\n/**\n * Whether a site-relative value names the sign-in page at `signInPath`, in any of its spellings. `null`\n * is a store without a sign-in page, where nothing is the route.\n */\nexport function isSignInRoute(href: string, signInPath: string | null): boolean {\n  return signInPath !== null && pathOf(href) === pathOf(signInPath);\n}\n\n/**\n * `resolveNavigableHref` narrowed for the address a handover targets: the storefront's own sign-in\n * route is refused. Sending the route to itself 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 the route's is a different page and is left alone.\n *\n * `signInPath` is the sign-in page's public path, since the address is a document URL.\n */\nexport function resolveLoginAddressHref(raw: string, signInPath: string | null): SafeHrefResult {\n  const address = resolveNavigableHref(raw);\n  if (!address.safe || !address.href.startsWith('/')) {\n    return address;\n  }\n  return isSignInRoute(address.href, signInPath) ? { safe: false, reason: 'sign-in-route' } : address;\n}\n\n/**\n * The sign-in page, carrying the current logical 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.\n */\nexport function signInTarget(path: string | null): PageRef {\n  if (!path) {\n    return SIGN_IN_PAGE;\n  }\n  const destination = resolveSiteRelativeHref(path);\n  if (!destination.safe) {\n    return SIGN_IN_PAGE;\n  }\n  return { standard: 'sign-in', query: { [RETURN_URL_PARAM]: 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":";AAYA,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;;AAGA,MAAa,eAAwB,EAAE,UAAU,UAAU;;AAG3D,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;;;;;;;;;AAUA,SAAgB,kBAAkB,KAAa,YAA2C;CACxF,MAAM,cAAc,wBAAwB,GAAG;CAC/C,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,cAAc,YAAY,MAAM,UAAU,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAgB,IAAI;AAClG;;;;;AAMA,SAAgB,cAAc,MAAc,YAAoC;CAC9E,OAAO,eAAe,QAAQ,OAAO,IAAI,MAAM,OAAO,UAAU;AAClE;;;;;;;;;;;;;;AAeA,SAAgB,wBAAwB,KAAa,YAA2C;CAC9F,MAAM,UAAU,qBAAqB,GAAG;CACxC,IAAI,CAAC,QAAQ,QAAQ,CAAC,QAAQ,KAAK,WAAW,GAAG,GAC/C,OAAO;CAET,OAAO,cAAc,QAAQ,MAAM,UAAU,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAgB,IAAI;AAC9F;;;;;;;AAQA,SAAgB,aAAa,MAA8B;CACzD,IAAI,CAAC,MACH,OAAO;CAET,MAAM,cAAc,wBAAwB,IAAI;CAChD,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO;EAAE,UAAU;EAAW,OAAO,GAAG,mBAAmB,YAAY,KAAK;CAAE;AAChF;;;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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/faststore",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "FastStore AI Native component library built on Base UI with AI-editable styles",
   "license": "MIT",
   "homepage": "https://developers.vtex.com/docs/guides/faststore",
@@ -50,12 +50,16 @@
   },
   "files": [
     "dist",
+    "skills",
     "src/styles/tailwind.css",
     "CHANGELOG.md"
   ],
   "dependencies": {
     "@base-ui/react": "^1.3.0",
     "@graphql-typed-document-node/core": "^3.2.0",
+    "@vtex/country-forms": "1.14.0",
+    "@vtex/faststore-catalog": "0.0.8",
+    "esbuild": "~0.27.3",
     "graphql": "^16.13.1",
     "react-hook-form": "^7.85.0",
     "react-intl": "^10.1.22",

package/skills/storefront-asset/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: storefront-asset
+description: FastStore extension authoring with @vtex/faststore. Scaffold a storefront Asset, write its API side (defineSubgraph) or UI side (defineComponent), and fix storefront-* Findings until vtex extension validate is green. Use when creating or editing an Asset whose asset.yaml says kind storefront.
+---
+
+# FastStore extension
+
+A FastStore extension is a **storefront Asset**: one package at `extensions/<ext>/<asset>/` whose
+`asset.yaml` says `kind: storefront`. It holds at most one **API side** (fields it adds to the
+storefront graph) and at most one **UI side** (components a store places). An extension holds at
+most one storefront Asset. The Asset depends on `@vtex/faststore` alone, and `vtex extension` loads
+the checks from that same package, so the code and its checks share one version.
+
+Run the CLI from the Account Repo root as `pnpm extension <command>`, the script
+`vtex extension init` writes. With stdout piped it prints JSON and puts its messages on stderr.
+`pnpm extension commands --json` describes every command and flag.
+
+The Asset is **green** when `pnpm extension validate <ext>` exits 0. Exit 1 means an error Finding
+and exit 2 means warnings only. An `info` Finding, such as `extension-not-installed`, leaves it
+green.
+
+## Steps
+
+1. **Check the SDK.** Run `pnpm extension validate <ext> --json`. A `provider-invalid` Finding on
+   the Asset's `package.json` that names `@vtex/faststore` ("is not a valid storefront provider")
+   means the installed SDK predates the storefront provider, and none of the checks below ran.
+   `provider-failed` means the provider threw. Either one is the human's to resolve: stop and ask
+   which `@vtex/faststore` to install. Done when neither code appears.
+2. **Create the Asset when it is missing.** On pnpm 11, first set `allowBuilds:` with
+   `esbuild: false` in the root's `pnpm-workspace.yaml`, replacing any placeholder value pnpm wrote
+   there. Without it pnpm refuses esbuild's build script, and `add` ends in `tool-failed` with the
+   Asset's `package.json` but no template. Then `pnpm extension add <ext>/<asset> --kind storefront`
+   writes the API side; add `--template ui` for the UI side. When `<ext>` is new too, pass
+   `--vendor` and `--description`: outside a terminal `add` exits 3 instead of asking. `add` writes
+   `asset.yaml`, `package.json` and the template's files, and installs their packages. An Asset that
+   `add` left without its template, or one made by hand, takes its files and `package.json` fields
+   from the side's reference. Done when the folder holds every file its sides need.
+3. **Read the side's reference, then write the change in its shapes.** A resolver, a GraphQL type,
+   a secret or data from an outside service is the API side:
+   [references/api-side.md](references/api-side.md). A React component, an editable prop or a
+   catalog key is the UI side: [references/ui-side.md](references/ui-side.md). A change that needs
+   both sides reads both, and the Asset takes the both-sides layout below.
+4. **Validate until green.** Run `pnpm extension validate <ext> --json`. For each `storefront-*`
+   Finding, apply the fix in its row of [references/findings.md](references/findings.md), then run
+   it again. Done when it exits 0.
+5. **Run the Asset's own checks.** In the Asset's folder, `pnpm typecheck`, and for an API side
+   `pnpm test`. An Asset made by hand may lack the scripts: run `pnpm exec tsc --noEmit` and
+   `pnpm exec vitest run`. Done when each exits 0.
+
+## Layout
+
+The provider reads an Asset's sides from `package.json` and two paths. A storefront `asset.yaml`
+holds the envelope and an empty body, so nothing in it changes the layout.
+
+| Side | What marks it | Entry |
+| --- | --- | --- |
+| API | `package.json#main`, or, with neither `main` nor `exports["./catalog.json"]`, `src/index.ts` | The declaration module, which `export default`s a `defineSubgraph(...)` |
+| UI | A `src/components/` directory, or `exports["./catalog.json"]` | Every `defineComponent` under `src/components/` |
+
+An Asset with both sides names its declaration through `main` (for example `api/index.ts`) and
+keeps `src/index.ts` as the component barrel. Without `main`, a `src/index.ts` beside a
+`./catalog.json` export is the barrel.
+
+The templates set these `package.json` fields, and an Asset made by hand sets them itself. Both
+sides take `"type": "module"`, a `typecheck` script and `typescript@^5.9.3` in devDependencies;
+`validate` reports `storefront-typescript-unsupported` without TypeScript 5. The API side adds
+`graphql`, `vitest` and a `test` script. The UI side adds `@types/react`, `react` as a peer, and
+these exports:
+
+```json
+"exports": {
+  ".": "./src/index.ts",
+  "./catalog.json": "./dist/catalog.json"
+}
+```
+
+A store lists the Asset's package as a dependency and compiles its components from `src/`.
+
+## Environment
+
+`dev` needs `VTEX_ACCOUNT` in the repo root's `.env`, or `STOREFRONT_CORE_URL` to override the core
+URL derived from the account. `VTEX_WORKSPACE` defaults to `master`. `VTEX_TOKEN`, which is
+optional, and the value of every secret a declaration lists go in the root's `.env.local`, which
+git ignores. Keep the Asset's folder free of `.env` files, so one place holds every value.
+`validate` reads none of them.
+
+## Running it live
+
+`dev` runs until it is stopped, so start it in the background. Start it through the CLI's bin, so a
+stop signal reaches the CLI rather than a pnpm wrapper:
+`node node_modules/@vtex/cli-plugin-extension/dist/bin/vtex-extension.js dev <ext>` from the repo
+root. It serves one local router over every API side and rebuilds each UI side's
+`dist/catalog.json` on every save under `src/`. The first run downloads the Hive Router into
+`.vtex/storefront/`, and the Assets stay `starting` until it lands.
+
+`.vtex/dev-session.json` at the repo root lists each Asset's `status` (`starting`, `ready` or
+`failed`), its `findings`, and, once `ready`, its `details`: the router `url`, the `subgraph` and
+the `catalog`. Query the router `url`; the subgraph's port changes on every reload. A Finding
+leaves the Asset `ready`, so read `findings` after each save. The file's shape is provisional.
+
+One session runs per repo, and a second `dev` exits 1 and names the running one. SIGTERM or SIGINT
+stops it with exit 0 and removes the file.
+
+## Building it
+
+`pnpm extension build <ext>` validates first, then writes each Asset's output to
+`.vtex/build/<ext>/<asset>/` (`--out <dir>` puts it under another root). The API side emits
+`server.mjs` and `extension.graphql`. The UI side emits `catalog.json`, `content-types.json` when
+there is one, and `docs/`. An Asset with an error Finding is `failed` and leaves no folder. The
+output is what the pipeline collects; the UI side's `catalog.json` also lands in the Asset's `dist/`,
+where its export points, so a store build finds it. `--json` prints each Asset's status.

package/skills/storefront-asset/references/api-side.md

@@ -0,0 +1,153 @@
+# The API side
+
+The API side is one declaration module: `src/index.ts`, or the file `package.json#main` names when
+the Asset has a UI side too.
+
+## The declaration
+
+```ts
+import { defineSubgraph, gql } from '@vtex/faststore/graphql';
+
+const REVIEWS_BY_SLUG: Record<string, Array<{ id: string; rating: number; text: string }>> = {
+  'sample-product-slug': [{ id: '1', rating: 5, text: 'Replace this with data from your own source.' }],
+};
+
+export default defineSubgraph({
+  vendor: 'acme',
+
+  typeDefs: gql`
+    extend type Product @key(fields: "slug") {
+      slug: String! @external
+      reviews: [Review!]!
+    }
+
+    type Review {
+      id: ID!
+      rating: Int!
+      text: String!
+    }
+  `,
+
+  extends: ['Product'],
+
+  resolvers: {
+    Product: {
+      reviews: (product: { slug: string }) => REVIEWS_BY_SLUG[product.slug] ?? [],
+    },
+  },
+});
+```
+
+`@vtex/faststore/graphql` exports `defineSubgraph`, `gql` and the types `SubgraphContext`,
+`SubgraphDefinition` and `SubgraphResolvers`. `defineSubgraph` returns its argument unchanged; the
+provider builds the schema from it.
+
+| Field | What it is |
+| --- | --- |
+| `vendor` | Required. Matches `^[a-z][a-z0-9]*$`: lowercase letters and digits, starting with a letter. It prefixes every name the Asset contributes. |
+| `typeDefs` | SDL in a `gql` tag, with bare names. Write `@key` and `@external` on the entity you extend; the provider injects the federation preamble. |
+| `extends` | The core entities the SDL extends. `Product`, keyed by `slug`, is the only one. |
+| `resolvers` | Keyed by bare names. The provider renames the keys to the prefixed names and adds each entity's `__resolveReference`. |
+| `secrets` | Optional. The environment names the resolvers read; see Secrets. |
+| `name` | Optional. The subgraph name; the package name by default. |
+
+## The vendor prefix
+
+The build prefixes every name the Asset contributes with `<vendor>_`: fields added to `Product`,
+root `Query` and `Mutation` fields, and each declared type with every reference to it. The
+declaration above exposes `Product.acme_reviews` of type `[acme_Review!]!`. Write bare names in the
+declaration and let the build add the prefix. The `@key` field of an extended entity keeps its core
+name.
+
+## The resolver context
+
+A resolver's third argument has exactly these five keys:
+
+| Key | Value |
+| --- | --- |
+| `ctx.account` | The `x-vtex-account` header, `''` when absent |
+| `ctx.workspace` | The `x-vtex-workspace` header, `''` when absent |
+| `ctx.headers` | `x-vtex-locale`, `x-vtex-segment` and `x-vtex-session`, each only when the request carried it |
+| `ctx.token` | The raw `authorization` header, `''` when absent |
+| `ctx.secrets` | The declared secret names that are set, mapped to their values |
+
+```ts
+import type { SubgraphContext } from '@vtex/faststore/graphql';
+
+const reviews = (product: { slug: string }, _args: unknown, ctx: SubgraphContext) =>
+  fetchReviews(product.slug, { apiKey: ctx.secrets.ACME_API_KEY, account: ctx.account });
+```
+
+## Secrets
+
+`secrets: ['ACME_API_KEY']` declares the environment names the Asset reads. Each name matches
+`^[A-Z][A-Z0-9_]*$`. The provider rejects `PATH`, `HOME`, `PWD`, `SHELL`, `TMPDIR` and any name
+that starts with `VTEX_` or `NODE_`. A declared name that is not set is absent from `ctx.secrets`;
+`dev` logs one warning for each. Values come from the repo root's `.env` and `.env.local`; keep
+secret values in `.env.local`, which git ignores. A resolver reads them through `ctx.secrets` only.
+
+## The capability boundary
+
+The provider lints the declaration and every `./` or `../` module it imports. Each rule is an error
+Finding at the line it flags:
+
+| Rule | What it flags | What to write instead |
+| --- | --- | --- |
+| `process-env` | Any `process.env` member access | Declare the name in `secrets` and read `ctx.secrets` |
+| `fs-import` | A runtime import of `fs` or `fs/promises`, bare or `node:` | Fetch the data from a service |
+| `child-process-import` | A runtime import of `child_process` | Call a service over HTTP |
+
+Static `import`, `import x = require()`, `require()`, dynamic `import()` and value re-exports all
+count; type-only imports do not. The lint does not walk packages, so route every secret through `ctx.secrets` even when a
+dependency could read the environment: the deployed server scrubs the declared names from its
+environment after boot.
+
+## The test
+
+`src/index.test.ts` sits beside the declaration. It builds the subgraph with `buildSubgraph` from
+`@vtex/faststore/cli` and resolves the field through `_entities`, the join a federated query makes:
+
+```ts
+import { buildSubgraph } from '@vtex/faststore/cli';
+import { graphql } from 'graphql';
+import { describe, expect, it } from 'vitest';
+import definition from './index';
+
+describe('acme extension', () => {
+  it('builds a subgraph and resolves the sample field via _entities', async () => {
+    const schema = buildSubgraph(definition);
+
+    const result = await graphql({
+      schema,
+      source: `
+        query ($representations: [_Any!]!) {
+          _entities(representations: $representations) {
+            ... on Product {
+              acme_reviews {
+                rating
+                text
+              }
+            }
+          }
+        }
+      `,
+      variableValues: {
+        representations: [{ __typename: 'Product', slug: 'sample-product-slug' }],
+      },
+    });
+
+    expect(result.errors).toBeUndefined();
+    const entities = result.data?._entities as Array<{ acme_reviews: Array<{ rating: number }> }>;
+    expect(entities[0]?.acme_reviews[0]?.rating).toBe(5);
+  });
+});
+```
+
+The test sees the built schema, so it queries the prefixed name (`acme_reviews`). `buildSubgraph`
+and `_entities` are the whole surface a test uses.
+
+## What validate checks here
+
+`validate` runs the capability lint, loads the declaration and builds the subgraph, which is where
+the `vendor` grammar, the `extends` list, the secret names and the SDL fail. It then composes the
+slice with the storefront core schema. `dev` runs the same checks at boot and on every save.

package/skills/storefront-asset/references/findings.md

@@ -0,0 +1,40 @@
+# The Findings
+
+Every code `vtex extension validate` reports for a storefront Asset. All are errors. `file` is
+relative to the repo root, and a Finding with a `range` points at its line and column. `dev` reports
+the API-side and UI-side codes for the same faults and replaces them on every reload, and never the
+two kind rules. `build` validates each Asset first, so it reports every code `validate` does before
+it writes, plus `storefront-build-failed`.
+
+## The Asset's code
+
+| Code | Trigger | On | Fix |
+| --- | --- | --- | --- |
+| `storefront-typescript-unsupported` | The Asset's `typescript` is missing or has no TypeScript 5 compiler API, so the capability lint did not run | `package.json` | `pnpm add -D typescript@^5.9.3` in the Asset's folder |
+| `storefront-capability-process-env` | A `process.env` member access in the declaration or a module it imports | The source line | Declare the name in `secrets` and read `ctx.secrets` |
+| `storefront-capability-fs-import` | A runtime import of `fs` or `fs/promises` | The source line | Fetch the data from a service; a resolver has no filesystem |
+| `storefront-capability-child-process-import` | A runtime import of `child_process` | The source line | Call a service; a resolver spawns no process |
+| `storefront-declaration-invalid` | `main` names no file; the declaration does not bundle or import; it does not `export default defineSubgraph(...)`; or the build rejects it: a `vendor` outside `^[a-z][a-z0-9]*$`, an `extends` entry other than `Product`, a `@key` other than `slug`, a secret name outside the grammar, or SDL that does not parse | The declaration entry | The message names the field or the SDL error. On a UI-only Asset's `src/index.ts`, add `exports["./catalog.json"]`: without it the barrel was read as a declaration |
+| `storefront-composition-failed` | The built slice does not compose with the storefront core schema: a type or field that collides with core's, or a federation directive the composer rejects. In `dev`, also a conflict between two Assets' slices | The declaration entry | Change the SDL as the message says. Keep `@key(fields: "slug")` on `Product` and bare names elsewhere |
+| `storefront-catalog-export-missing` | The Asset has `src/components/` and `package.json#exports` has no `./catalog.json` key | `package.json` | Add `"./catalog.json": "./dist/catalog.json"` and `".": "./src/index.ts"` to `exports` |
+| `storefront-catalog-export-invalid` | The `./catalog.json` export names no file, or a path that is not `./`-relative, has `..` or resolves outside the Asset through a link; `dev` and `build` write where it points, so the catalog goes to `dist/` meanwhile | `package.json` | Point the export at a file inside the Asset: `"./catalog.json": "./dist/catalog.json"` |
+| `storefront-catalog-invalid` | The catalog build threw: no component under `src/components/` (`NoExtensionComponents`), two components with one name, a fragment spread with no definition (`UnresolvedSpread`), no `package.json#name` (`MissingPackageName`), or a top-level `defineActions` | `package.json` | The message names the file or component. Add a `defineComponent`, rename the duplicate, drop the spread, set `name`, or remove `defineActions` |
+| `storefront-build-failed` | The build step after `validate` passed failed: no or invalid `tsconfig.json`, a TypeScript diagnostic, the `server.mjs` bundle, two component docs sharing a basename, or the catalog | `package.json` | The message is the runner's error. Fix what it names and run `pnpm extension build` again |
+
+`storefront-declaration-invalid`, `storefront-catalog-invalid` and `storefront-build-failed` carry
+the build's own error verbatim in their message: read it before changing code.
+
+## The kind rules
+
+`validate` and `build` check these before either side; `dev` does not.
+
+| Code | Trigger | On | Fix |
+| --- | --- | --- | --- |
+| `storefront-one-per-extension` | The extension already has a storefront Asset, and this one is its second | The Asset's `asset.yaml`, at `kind` | Merge the two into one Asset with both sides, or move this one to its own extension |
+| `storefront-store-extension-not-installed` | A store under `stores/` depends on the Asset's package, and an account that uses that store does not list the extension under `installed:` in `accounts.yaml` | The store's `package.json` | Add `<vendor>.<ext>@<range>` to each such account's `installed:`, or drop the dependency |
+
+## The provider's own faults
+
+`provider-invalid` on the Asset's `package.json` means the installed `@vtex/faststore` has no
+storefront provider. `provider-failed` means the provider threw. Both belong to the SDK, so the
+human decides which `@vtex/faststore` to install.

package/skills/storefront-asset/references/ui-side.md

@@ -0,0 +1,94 @@
+# The UI side
+
+The UI side is the set of components under `src/components/`, each registered with
+`defineComponent` from `@vtex/faststore`, and the barrel `src/index.ts` a store imports them from.
+The provider builds a catalog of the registrations. A store reads the catalog to place the
+components and compiles them from `src/`; the Asset ships no JavaScript build.
+
+## A component
+
+```tsx
+import { defineComponent } from '@vtex/faststore';
+import type { ComponentPropsWithRef } from 'react';
+
+/** Props for {@link HeroBanner}. Extends all native `<section>` attributes. */
+export type HeroBannerProps = ComponentPropsWithRef<'section'> & {
+  /** The headline text. */
+  title?: string;
+};
+
+export const HeroBannerDefinition = defineComponent<HeroBannerProps>({
+  name: 'HeroBanner',
+  importPath: '@acme/reviews-ui',
+  component: HeroBanner,
+  editor: { label: 'Hero Banner', category: 'content' },
+  schema: {
+    title: { type: 'string', label: 'Title' },
+  },
+});
+
+export function HeroBanner({ title, className, ...props }: HeroBannerProps) {
+  return (
+    <section {...props} className={className} data-fs-hero-banner="">
+      <h1>{title}</h1>
+    </section>
+  );
+}
+```
+
+| Field | What it is |
+| --- | --- |
+| `name` | The exported function's name. |
+| `importPath` | The Asset's `package.json#name`. A store imports the component from there. |
+| `component` | The function. A function declaration hoists, so the definition may come first. |
+| `editor` | `label`, the name an editor shows, and `category`, a free string that groups it. `description` and `icon` are optional. |
+| `schema` | The editable props. Each has a `type` (`string`, `number`, `boolean`, `object`, `array` or a list of string literals), an optional `label` and an optional `default`; an `array` may name its allowed elements in `items`. Values are serializable: strings, numbers, booleans, objects and arrays of them. |
+
+The provider finds definitions by a static scan of `src/components/`, recursive, skipping
+`*.test.tsx`, `*.stories.tsx` and `generated/`. Export each one as a top-level `const` named
+`<Component>Definition` whose argument is an object literal.
+
+The root element carries `data-fs-<component>=""` as its identity, and `data-fs-<component>-<prop>`
+for each prop that changes its look. The component accepts `className` and renders it. A store
+styles it through those attributes, so the component ships no CSS.
+
+## The barrel
+
+`src/index.ts` re-exports every component and its definition:
+
+```ts
+export type { HeroBannerProps } from './components/HeroBanner';
+export { HeroBanner, HeroBannerDefinition } from './components/HeroBanner';
+```
+
+It is the `exports["."]` target. With `exports["./catalog.json"]` set, the provider reads it as the
+barrel, never as a declaration.
+
+## The catalog
+
+Each registration becomes one catalog entry keyed `<packageName>:<Component>`, for example
+`@acme/reviews-ui:HeroBanner`. The package name, taken verbatim from `package.json#name`, is the
+namespace, so two Assets never collide.
+
+`dev` builds `dist/catalog.json` at boot and on every save under `src/`; `exports["./catalog.json"]`
+points there, and git ignores `dist/`. `build` writes the same file there beside its output folder,
+so a store built after `pnpm extension build` finds it without a `dev` loop. `validate` builds the
+catalog into the Asset's `.vtex/storefront/` scratch folder and leaves `dist/` as it is. A failed
+build keeps the previous `catalog.json` until the next save fixes it.
+
+A store sees the Asset as a UI side through the `./catalog.json` export alone. Without it, no store
+sees the components, and `validate` reports `storefront-catalog-export-missing`. The export must
+name a `./` path inside the Asset, since `dev` and `build` write the catalog where it points; one
+that does not is `storefront-catalog-export-invalid`, and the catalog goes to `dist/` meanwhile.
+
+## Props and content only
+
+Keep each component to its props and editor content. A GraphQL fragment spread fails the catalog
+build with `UnresolvedSpread` (reported as `storefront-catalog-invalid`), because no convention yet
+names where a storefront Asset's generated fragments live.
+
+## What validate checks here
+
+`validate` fails a UI side whose `package.json` lacks the `./catalog.json` export, whose
+`src/components/` declares no component, that has two components with one name, or that spreads a
+fragment with no definition.

package/src/styles/tailwind.css

@@ -63,4 +63,31 @@
   [data-fs-card-entry-fieldset] {
     min-inline-size: 0;
   }
+
+  /* Baseline look and viewport bound for the select popup. Nothing else styles it, and a matter-composed
+     popup is portaled out of reach of a store's descendant selectors, so unstyled it is transparent text
+     drawn over the next field, content-wide and free to run past the viewport. `--anchor-width` and
+     `--available-height` are set on the positioner by Base UI; the latter bounds the popup (not the list)
+     to the viewport. Preflight's `border-box` counts the 1px border inside that bound, and the flex column
+     hands the leftover height, minus any composed scroll arrows, to the list, so a tall popup never
+     overruns the viewport by the border or the arrows. `@layer base` so any merchant utility class (`max-h-60`,
+     `overflow-*`) outranks it under Tailwind 4's layer order. */
+  [data-fs-select-popup] {
+    max-height: var(--available-height);
+    display: flex;
+    flex-direction: column;
+    min-width: var(--anchor-width);
+    background-color: var(--color-bg);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+  }
+
+  /* The list, not the popup, is the scroll container: that is the Select contract (`SelectList` is the
+     "scrollable container"), and Base UI's scroll arrows watch the list's scroll position, so a popup
+     that scrolled instead would leave them inert. `min-height: 0` lets the flex item shrink below its
+     content so the popup's bound reaches it. */
+  [data-fs-select-list] {
+    min-height: 0;
+    overflow-y: auto;
+  }
 }