@salesforce/b2c-dx-mcp 2.1.2 → 3.0.1

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next-figma/skills/sfnext-create-figma-kit/references/FIGMA-COMPONENT-EDITING.md

@@ -0,0 +1,92 @@
+# Figma Component Editing Reference
+
+## 0. Extend before create — check this before building anything new
+
+When a design change is requested, ask these questions in order before creating any new frame or component:
+
+1. **Does an existing Figma component already cover this?** Search by name across all pages.
+2. **Can the existing component be extended with a new variant or property?** Add a variant to the component set first.
+3. **Can composition cover this?** Place the existing component inside a new wrapper frame with additional content alongside it.
+4. **Only if all three are no** — create a new component or frame.
+
+```
+// ❌ WRONG — building a new "<Brand> Button" component from scratch
+//            when the existing .Button component set can take a new variant
+
+// ✅ CORRECT — add a variant="<brand>" to the existing .Button component set
+
+// ❌ WRONG — creating a new "<Brand> Product Gallery" component
+//            when the existing Gallery=Carousel just needs a wrapper with a row below it
+
+// ✅ CORRECT — wrap Gallery=Carousel in a "Gallery Column" frame,
+//             append the new row to the wrapper only
+```
+
+This maps to code: new Figma variants → new CVA variants in React. New Figma compositions → new composite components in `src/components/`. Keep design and code in sync.
+
+## 1. Identify the correct edit layer before touching anything
+
+| Layer | What lives here | Safe to edit for vertical changes? |
+|-------|-----------------|-----------------------------------|
+| **Primitive** (atom) | Icon, Button, Badge, Input | No — shared across all verticals |
+| **Composite** (organism) | ProductGallery, Header, ProductOverviews | Only if the change is universal |
+| **Page composition** | StorefrontHome, ProductPage sections | Yes — the right place for vertical-specific additions |
+
+**Never add vertical-specific elements to a primitive or shared composite.** Add them at the page composition level or wrap in a new parent frame.
+
+## 2. Tokens and variables only — never bespoke color values
+
+Every fill, stroke, and effect applied to a new or edited node **must reference a Figma variable** from the kit's variable collections. Raw hex/RGB values and opacity overrides are forbidden.
+
+```js
+// ❌ WRONG — hardcoded hex on a new text node
+node.fills = [{ type: 'SOLID', color: { r: 0, g: 0.608, b: 0.227 } }]
+
+// ✅ CORRECT — bind to the semantic variable
+const colorVar = await figma.variables.getVariableByIdAsync(semanticGreenId);
+figma.variables.setBoundVariableForPaint(fill, 'color', colorVar);
+```
+
+### Variable lookup order
+
+1. **Semantic collection first** — `text/foreground`, `background/primary`, `status/positive`, etc.
+2. **Brand collection second** — `Brand/primary`, `Brand/black`, `Brand/gray-*` — only if no semantic alias fits.
+3. **New variable needed?** — Stop and ask before creating it. State which node needs it, why no existing variable fits, and the proposed name/value.
+
+| Element | Correct variable | Collection |
+|---------|------------------|------------|
+| Body text | `text/foreground` | Semantic |
+| Secondary / meta text | `text/muted-foreground` | Semantic |
+| Primary button fill | `background/primary` | Semantic |
+| Primary button label | `text/primary-foreground` | Semantic |
+| Card surface | `background/card` | Semantic |
+| Dividers / borders | `border/border` | Semantic |
+| Brand accent (vertical signature color) | `Brand/primary` | Brand |
+| Brand black | `Brand/black` | Brand |
+
+## 3. Instance vs. component boundary
+
+- You **cannot** append children to an INSTANCE node — always find and edit the **source COMPONENT**.
+- Use `node.mainComponent` to find the source from any instance.
+- To add new content alongside an instance, wrap the instance in a new VERTICAL/HORIZONTAL frame.
+
+## 4. Batch ALL font loads at the top of every script
+
+```js
+// Font errors abort mid-script and leave partial state — load everything first.
+await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
+await figma.loadFontAsync({ family: 'Inter', style: 'Semi Bold' });
+await figma.loadFontAsync({ family: 'Jost', style: 'Black' });
+```
+
+## 5. Figma Plugin API enum values
+
+| Property | ❌ Wrong | ✅ Correct |
+|----------|---------|-----------|
+| `primaryAxisSizingMode` | `'HUG'` | `'AUTO'` |
+| `counterAxisSizingMode` | `'HUG'` | `'AUTO'` |
+| `layoutSizingHorizontal` | `'HUG'` | `'AUTO'` or `'FILL'` |
+
+## 6. Screenshot after each logical edit — not at the end
+
+Take a screenshot after each distinct change (logo, token sync, a new row). Catching a wrong-layer mistake early avoids unwinding compound changes.

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next-figma/skills/sfnext-create-figma-kit/references/PROJECT-STRUCTURE.md

@@ -0,0 +1,43 @@
+# Project Structure Reference
+
+Storefront Next is a pnpm monorepo with a React Router v7 retail application.
+
+## Key architecture
+
+- **Monorepo:** pnpm workspaces, packages under `packages/`
+- **Main app:** `packages/template-retail-rsc-app/` — React Router v7 retail application
+- **Build tool:** Vite with SSR
+- **Routing:** React Router v7 file-based routing
+- **Styling:** Tailwind CSS v4, utility-first, token-driven
+- **Commerce:** Salesforce Commerce Cloud (SCAPI) integration
+
+## Theme file layout (the vertical surface)
+
+```
+src/theme/
+├── tailwind.css            # CSS variable → Tailwind utility bridge
+└── tokens/
+    ├── brand.css           # ← the ONLY file that changes per vertical
+    ├── core.css            # semantic roles (bg, fg, card, primary, …)
+    ├── header.css          # header / footer surfaces
+    ├── status.css          # destructive / warning / success / info
+    ├── swatch.css          # variant-selector swatch UI
+    └── components.css       # payment + cart-specific tokens
+```
+
+## App file organization
+
+- **Routes:** `src/routes/` (file-based, mapped in `src/routes.ts`)
+- **Components (composite):** `src/components/`
+- **Components (Shadcn primitives):** `src/components/ui/`
+- **Extensions:** `src/extensions/<name>/`
+- **Providers:** `src/providers/`
+- **Config / fixtures:** `src/config/`
+
+## Common commands
+
+- `pnpm dev` — start the dev server
+- `pnpm build` — production build
+- `pnpm typecheck` — TypeScript checking
+- `pnpm lint` — ESLint (runs with `--max-warnings 0`)
+- `pnpm test-storybook:snapshot:agent` — Storybook snapshot diff

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next-figma/skills/sfnext-create-figma-kit/references/TOKEN-SYSTEM.md

@@ -0,0 +1,130 @@
+# Token System Reference
+
+## The one rule that overrides everything else
+
+**Never use a raw hex value, RGB value, or hardcoded color in any component or CSS file.**
+Always use a semantic Tailwind utility that maps to a CSS variable. The variables are defined in
+`src/theme/tokens/` and bridged to Tailwind utilities in `src/theme/tailwind.css`.
+
+```tsx
+// ✅ correct
+<div className="bg-primary text-primary-foreground" />
+
+// ❌ wrong — breaks dark mode, breaks vertical theming, breaks Figma sync
+<div style={{ background: '#000000', color: '#ffffff' }} />
+<div className="bg-black text-white" />
+```
+
+## Token files and what they own
+
+| File | Owns |
+|------|------|
+| `src/theme/tokens/core.css` | Background, foreground, card, popover, primary, secondary, muted, accent, border, input, ring, separator, rating, charts, sidebar, focus helpers |
+| `src/theme/tokens/brand.css` | Brand palette (`--brand-black`, `--brand-white`, `--brand-gray-*`, `--brand-primary`). **This is the only file that changes per vertical.** |
+| `src/theme/tokens/header.css` | Header background/foreground, header menu surfaces, footer. Dark header = black bg / white text. |
+| `src/theme/tokens/status.css` | Destructive, warning, success, info, status-positive/warning/critical, active-bg |
+| `src/theme/tokens/swatch.css` | Swatch color, labeled, pill — variant selector UI only |
+| `src/theme/tokens/components.css` | Payment provider colors, cart-specific tokens |
+
+## Semantic token meanings — use the right one
+
+### Text colors
+| Token class | When to use |
+|-------------|-------------|
+| `text-foreground` | Default body text, headings |
+| `text-muted-foreground` | Secondary labels, helper text, placeholder, metadata |
+| `text-primary-foreground` | Text on a `bg-primary` surface (e.g. button label) |
+| `text-secondary-foreground` | Text on a `bg-secondary` surface |
+| `text-accent-foreground` | Text on a `bg-accent` surface (hover chips, tags) |
+| `text-destructive` | Error text, destructive action labels |
+| `text-card-foreground` | Text inside card surfaces |
+
+### Background colors
+| Token class | When to use |
+|-------------|-------------|
+| `bg-background` | Page/app background |
+| `bg-primary` | CTAs, filled buttons, strong actions |
+| `bg-secondary` | Secondary button fill, subtle section bg |
+| `bg-muted` | Skeleton, disabled surfaces, subtle fills |
+| `bg-accent` | Hover state, selected chip, tag bg |
+| `bg-card` | Card and tile surfaces |
+| `bg-popover` | Dropdown, tooltip, modal backgrounds |
+
+### Borders
+| Token class | When to use |
+|-------------|-------------|
+| `border-border` | Standard dividers, list separators — uses alpha so it renders correctly on ANY surface color |
+| `border-border-subtle` | Form inputs, card edges — slightly more visible |
+| `border-input` | Input field border specifically |
+| `ring-ring` | Focus ring on interactive elements |
+
+**Never use `border-black`, `border-gray-*`, or `divide-gray-*`.** Use `border-border` or `border-border-subtle`.
+
+### Header/navigation surfaces
+| Token class | When to use |
+|-------------|-------------|
+| `bg-[--header-background]` | Header band background |
+| `text-[--header-foreground]` | Header text and icons |
+| `bg-[--header-menu-background]` | Mega/dropdown menu panel |
+| `bg-[--footer-background]` | Footer background |
+
+### Status and feedback
+| Token class | When to use |
+|-------------|-------------|
+| `text-destructive` / `bg-destructive` | Delete, remove, error state |
+| `bg-warning-bg` / `text-warning-foreground` | Caution messages |
+| `text-status-positive` | In-stock, success indicator |
+| `text-status-critical` | Out of stock, error badge |
+| `bg-active-bg` / `text-active-foreground` | Active/authorized badge |
+
+## Dark mode rules
+
+**Do not write `dark:bg-black` or any dark: hardcoded color.**
+Dark mode is fully handled by `.dark` overrides in `src/theme/tokens/core.css` and other token files.
+Using semantic classes automatically gets the correct dark value.
+
+```tsx
+// ✅ correct — dark mode is automatic
+<div className="bg-card text-card-foreground" />
+
+// ❌ wrong
+<div className="bg-white dark:bg-gray-900 text-black dark:text-white" />
+```
+
+The only valid `dark:` usage is for classes that reference another semantic token:
+
+```tsx
+// ✅ valid dark: override pattern
+className="dark:bg-input/30 dark:border-input"
+```
+
+## What changes per vertical — and what does not
+
+### Changes (vertical-specific, lives in `src/theme/tokens/brand.css`)
+- Brand palette values (`--brand-black`, `--brand-primary`, `--brand-gray-*`)
+- Logo treatment (`--header-logo-filter`)
+- Brand-specific component tokens
+
+### Does NOT change (shared, lives in core/header/status/swatch/components)
+- Semantic token names and their Tailwind utility names
+- Dark mode pairing rules
+- Component variant logic (CVA)
+- Border alpha values
+- Status and feedback colors
+
+**Never override core.css, header.css, status.css, swatch.css, or components.css to create a vertical.**
+Only `brand.css` changes between verticals.
+
+## Tailwind utility bridge
+
+All token → Tailwind utility mappings are defined in `src/theme/tailwind.css`.
+If a CSS variable exists in a token file but has no Tailwind utility in `tailwind.css`, add it there
+before using it in a component. Do not use arbitrary `[--variable-name]` syntax for variables that
+should be in the bridge.
+
+```css
+/* src/theme/tailwind.css — add new token bridge entries here */
+--color-my-new-token: var(--my-new-token);
+```
+
+Then use `bg-my-new-token` in components.

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next-figma/skills/sfnext-create-figma-kit/references/TROUBLESHOOTING.md

@@ -0,0 +1,34 @@
+# Troubleshooting Reference
+
+## Token not found in Tailwind utilities
+If a CSS variable exists in a token file but has no Tailwind utility in `tailwind.css`:
+- Open `src/theme/tailwind.css`.
+- Add a bridge entry: `--color-my-new-token: var(--my-new-token);`.
+- Then use `bg-my-new-token` in components — never the `bg-[--my-new-token]` arbitrary syntax.
+
+## Colors look wrong in dark mode
+- You probably hardcoded a color (`bg-white`, `text-black`, raw hex) instead of using a semantic token.
+- Replace with the semantic utility (`bg-background`, `text-foreground`, etc.). Dark mode is handled by `.dark` overrides in the token files automatically.
+
+## Vertical changes leak into other verticals
+- You edited a shared token file (`core.css`, `header.css`, `status.css`, `swatch.css`, `components.css`). Move the change into `brand.css`.
+- Or you added `if (vertical)` logic to a shared component. Replace it with a CVA variant, a slot/render-prop on the base, or an extension.
+
+## Component already exists
+If a scan finds an existing component that covers the need:
+- Add a new CVA variant instead of creating a new component.
+- Wrap in a thin composite if behaviour differs.
+- Never duplicate.
+
+## Local pages won't render without SCAPI
+- Use fixtures: create `src/config/<vertical>-fixtures.ts` and short-circuit the `_app.tsx` and `_app.product.$productId.tsx` loaders during vertical development.
+- Restore the real SCAPI calls once credentials are available.
+
+## Linter errors after changes
+Run `pnpm lint:fix` first. If errors remain, check:
+- Missing copyright header (required on every `.ts`/`.tsx` file).
+- Raw hex value or hardcoded Tailwind color — replace with a semantic token class.
+- Missing `data-slot` attribute on a component root.
+
+## Snapshot tests fail after visual changes
+Run `pnpm test-storybook:snapshot:agent -- --updateSnapshot` to update baselines after intentional visual changes.

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next-figma/skills/sfnext-create-figma-kit/references/VERTICAL-FIGMA-SYNC.md

@@ -0,0 +1,45 @@
+# Vertical → Figma Kit Sync Reference
+
+When a new vertical is created in code, these steps ensure the Figma kit reflects it correctly.
+
+## Step 1 — Audit changed components before opening Figma
+
+Run `git diff --name-only` (or `git status`) to get the exact list of modified files. Split results into two buckets:
+
+| Bucket | Action |
+|--------|--------|
+| **New vertical-only components** (e.g. `<vertical>-announcement-bar`) | Build new frames in Figma at the page composition layer |
+| **Modified shared components** (e.g. `header/index.tsx`, `product-view.tsx`) | Find the source component in Figma and edit it |
+
+Never guess which Figma component to edit — always trace from the code file to the Figma component ID.
+
+## Step 2 — Build a component ID map once, reuse it
+
+Before the first edit session, run a one-time inspection to map component names → Figma node IDs and which page they live on. Store this map (e.g. as a comment in your skill notes) so you don't rediscover the hierarchy every session.
+
+```
+// Example map for a Beauty vertical
+// .Header            → 10052:10952  (page: 🟢 Header)
+// Product Overviews  → 12174:11185  (page: 🟢 Product Overviews)
+// Gallery=Carousel   → 13055:349861 (page: 🟢 Product Overviews) ← PRIMITIVE, don't add vertical content here
+// Logo (medium)      → 12087:46186  (page: Content (Images & Illustration))
+```
+
+## Step 3 — Token sync before visual edits
+
+Always sync brand tokens (colors, typography) first. Visual component edits that rely on token colors will be wrong if tokens aren't updated.
+
+Order: **tokens → logo → shared component overrides → new page-level frames**
+
+## Step 4 — Logo wordmarks are vectors, not text
+
+In the base kit, logo wordmarks are VECTOR paths (not editable text nodes). To update for a new vertical:
+
+1. Find the `logo 1` source frame inside the logo component.
+2. Remove the VECTOR child.
+3. Insert a TEXT node with the new brand name.
+4. Hide `logo-mark` if the new brand is text-only.
+
+## Step 5 — Verify propagation
+
+After editing a source component, screenshot an INSTANCE of it (e.g. the header on a vertical storefront page) to confirm the change cascaded. Source edits propagate to instances automatically.

package/node_modules/zod/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/zod/README.md

@@ -0,0 +1,218 @@
+<p align="center">
+  <img src="logo.svg" width="200px" align="center" alt="Zod logo" />
+  <h1 align="center">Zod</h1>
+  <p align="center">
+    TypeScript-first schema validation with static type inference
+    <br/>
+    by <a href="https://x.com/colinhacks">@colinhacks</a>
+  </p>
+</p>
+<br/>
+
+<p align="center">
+<a href="https://github.com/colinhacks/zod/actions?query=branch%3Amain"><img src="https://github.com/colinhacks/zod/actions/workflows/test.yml/badge.svg?event=push&branch=main" alt="Zod CI status" /></a>
+<a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/colinhacks/zod" alt="License"></a>
+<a href="https://www.npmjs.com/package/zod" rel="nofollow"><img src="https://img.shields.io/npm/dw/zod.svg" alt="npm"></a>
+<a href="https://discord.gg/KaSRdyX2vc" rel="nofollow"><img src="https://img.shields.io/discord/893487829802418277?label=Discord&logo=discord&logoColor=white" alt="discord server"></a>
+<a href="https://github.com/colinhacks/zod" rel="nofollow"><img src="https://img.shields.io/github/stars/colinhacks/zod" alt="stars"></a>
+</p>
+
+<div align="center">
+  <a href="https://zod.dev/api">Docs</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://discord.gg/RcG33DQJdf">Discord</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://twitter.com/colinhacks">𝕏</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://bsky.app/profile/zod.dev">Bluesky</a>
+  <br />
+</div>
+
+<br/>
+<br/>
+
+### [Read the docs →](https://zod.dev/api)
+
+<br/>
+<br/>
+
+## What is Zod?
+
+Zod is a TypeScript-first validation library. Define a schema and parse some data with it. You'll get back a strongly typed, validated result.
+
+```ts
+import * as z from "zod";
+
+const User = z.object({
+  name: z.string(),
+});
+
+// some untrusted data...
+const input = {
+  /* stuff */
+};
+
+// the parsed result is validated and type safe!
+const data = User.parse(input);
+
+// so you can use it with confidence :)
+console.log(data.name);
+```
+
+<br/>
+
+## Features
+
+- Zero external dependencies
+- Works in Node.js and all modern browsers
+- Tiny: `2kb` core bundle (gzipped)
+- Immutable API: methods return a new instance
+- Concise interface
+- Works with TypeScript and plain JS
+- Built-in JSON Schema conversion
+- Extensive ecosystem
+
+<br/>
+
+## Installation
+
+```sh
+npm install zod
+```
+
+<br/>
+
+## Basic usage
+
+Before you can do anything else, you need to define a schema. For the purposes of this guide, we'll use a simple object schema.
+
+```ts
+import * as z from "zod";
+
+const Player = z.object({
+  username: z.string(),
+  xp: z.number(),
+});
+```
+
+### Parsing data
+
+Given any Zod schema, use `.parse` to validate an input. If it's valid, Zod returns a strongly-typed _deep clone_ of the input.
+
+```ts
+Player.parse({ username: "billie", xp: 100 });
+// => returns { username: "billie", xp: 100 }
+```
+
+**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](https://zod.dev/api#refinements) or [transforms](https://zod.dev/api#transforms), you'll need to use the `.parseAsync()` method instead.
+
+```ts
+const schema = z.string().refine(async (val) => val.length <= 8);
+
+await schema.parseAsync("hello");
+// => "hello"
+```
+
+### AOT compilation
+
+For hot validation paths, `z.compile(schema)` returns a schema clone with an ahead-of-time compiled fast path. Valid inputs take the compiled path; invalid inputs fall back to the regular parser so error reporting stays identical.
+
+Across a 55-schema benchmark the median speedup is **2.4x**, and it scales with how much work the schema does per parse: a large array of objects is ~9x, a 20-key object ~9x, a nested object ~4.5x, while a bare `z.string()` gains nothing — compilation removes per-node dispatch and allocation, and a single `typeof` has none to remove.
+
+```ts
+const CompiledPlayer = z.compile(Player);
+
+CompiledPlayer.parse({ username: "billie", xp: 100 });
+```
+
+To enable compilation globally for schemas constructed after import:
+
+```ts
+import "zod/compile"; // place before modules that define schemas
+```
+
+Things to know:
+
+- Compilation uses `new Function`. Global mode is automatically disabled when `z.config({ jitless: true })` is set (e.g. CSP environments); calling `z.compile()` directly is an explicit opt-in.
+- Schemas with async refinements or transforms can't be compiled, and neither can a few other constructs. That is not an error: `z.compile()` hands the schema back unchanged and it keeps using the regular parser, exactly as global mode leaves it. Pass `{ strict: true }` to throw `ZodCompileAsyncError` / `ZodCompileUnsupportedError` instead.
+- On invalid input, refinements and transforms may run twice (fast path, then fallback).
+- Deriving a new schema from a compiled one (`.refine()`, `.extend()`, etc.) returns an uncompiled schema — compile the final schema.
+
+See [`compile` docs](https://zod.dev/compile) for details.
+
+### Handling errors
+
+When validation fails, the `.parse()` method will throw a `ZodError` instance with granular information about the validation issues.
+
+```ts
+try {
+  Player.parse({ username: 42, xp: "100" });
+} catch (err) {
+  if (err instanceof z.ZodError) {
+    err.issues;
+    /* [
+      {
+        expected: 'string',
+        code: 'invalid_type',
+        path: [ 'username' ],
+        message: 'Invalid input: expected string'
+      },
+      {
+        expected: 'number',
+        code: 'invalid_type',
+        path: [ 'xp' ],
+        message: 'Invalid input: expected number'
+      }
+    ] */
+  }
+}
+```
+
+To avoid a `try/catch` block, you can use the `.safeParse()` method to get back a plain result object containing either the successfully parsed data or a `ZodError`. The result type is a [discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions), so you can handle both cases conveniently.
+
+```ts
+const result = Player.safeParse({ username: 42, xp: "100" });
+if (!result.success) {
+  result.error; // ZodError instance
+} else {
+  result.data; // { username: string; xp: number }
+}
+```
+
+**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](https://zod.dev/api#refinements) or [transforms](https://zod.dev/api#transforms), you'll need to use the `.safeParseAsync()` method instead.
+
+```ts
+const schema = z.string().refine(async (val) => val.length <= 8);
+
+await schema.safeParseAsync("hello");
+// => { success: true; data: "hello" }
+```
+
+### Inferring types
+
+Zod infers a static type from your schema definitions. You can extract this type with the `z.infer<>` utility and use it however you like.
+
+```ts
+const Player = z.object({
+  username: z.string(),
+  xp: z.number(),
+});
+
+// extract the inferred type
+type Player = z.infer<typeof Player>;
+
+// use it in your code
+const player: Player = { username: "billie", xp: 100 };
+```
+
+In some cases, the input & output types of a schema can diverge. For instance, the `.transform()` API can convert the input from one type to another. In these cases, you can extract the input and output types independently:
+
+```ts
+const mySchema = z.string().transform((val) => val.length);
+
+type MySchemaIn = z.input<typeof mySchema>;
+// => string
+
+type MySchemaOut = z.output<typeof mySchema>; // equivalent to z.infer<typeof mySchema>
+// number
+```

package/node_modules/zod/compile.cjs

@@ -0,0 +1,77 @@
+"use strict";
+// Side-effect-only: installs the post-processor on `globalConfig`. Listed in `package.json`'s `sideEffects`, and nothing else references it, so apps that never import it drop the compiler.
+//
+// Usage:
+//
+//   import "zod/compile";
+//   import * as z from "zod";
+//   // every schema constructed below this is compiled on first parse
+//
+// Module evaluation order matters: schemas constructed in modules that evaluate before this import will not be compiled. Place this import in the app entry point, before any module that constructs schemas at top level.
+//
+// Failure handling: if the compiler refuses a schema (async refinement, unsupported feature, etc.) the shim permanently restores the runtime `_zod.run` for that schema. The schema continues to work via the regular runtime parser — no observable difference to the caller.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const compile_js_1 = require("./v4/core/compile.cjs");
+const core = __importStar(require("./v4/core/index.cjs"));
+let compiling = false;
+core.globalConfig.postProcessor = (inst) => {
+    if (compiling)
+        return;
+    const originalRun = inst._zod?.run;
+    if (typeof originalRun !== "function")
+        return;
+    const shim = (payload, ctx) => {
+        // Bypass the fast path for any non-forward / non-sync / check-skipping call. The runtime owns those contracts.
+        if (ctx?.async || ctx?.direction === "backward" || ctx?.skipChecks) {
+            return originalRun(payload, ctx);
+        }
+        compiling = true;
+        try {
+            // Respect the jitless config: it exists precisely so CSP/no-eval environments never reach `new Function`. Global mode must not bypass it (explicit z.compile calls remain an explicit opt-in).
+            if (core.globalConfig.jitless) {
+                inst._zod.run = originalRun;
+                return originalRun(payload, ctx);
+            }
+            // Strict: the shim owns its own fallback below, and a non-strict compile would hand back `inst` — whose run is this shim — and reinstall it on itself.
+            const compiled = (0, compile_js_1.compile)(inst, { strict: true });
+            // Only the run wrapper. Copying the compiled parse/safeParse closures would make their fallback re-enter this instance and run user callbacks a third time.
+            inst._zod.run = compiled._zod.run;
+            inst._zod.bag.fallbackRun = compiled._zod.bag.fallbackRun;
+            inst._zod.bag.validator = compiled._zod.bag.validator;
+        }
+        catch {
+            // Permanent fallback for unsupported schemas.
+            inst._zod.run = originalRun;
+        }
+        finally {
+            compiling = false;
+        }
+        return inst._zod.run(payload, ctx);
+    };
+    // Expose the pre-shim runtime so `compile()` invoked elsewhere can unwrap past the shim and capture the source-of-truth runtime. Without this, a user calling `z.compile(s)` after global mode is enabled would capture the shim itself, which would feed the wrapper into itself on fallback.
+    shim.__originalRun = originalRun;
+    inst._zod.run = shim;
+};

package/node_modules/zod/compile.d.cts

@@ -0,0 +1 @@
+export {};

package/node_modules/zod/compile.d.ts

@@ -0,0 +1 @@
+export {};