@wix/agent-skills 1.0.0

package/skills/wix-app/references/SERVICE_PLUGIN.md

@@ -0,0 +1,235 @@
+
+# Wix Service Plugin (SPI) Builder
+
+Creates service plugin extensions for Wix CLI applications. Service plugins are a set of APIs defined by Wix that you can use to inject custom logic into the existing backend flows of Wix business solutions or to introduce entirely new flows to Wix sites.
+
+When you implement a service plugin, Wix calls your custom functions during specific flows. Common use cases include eCommerce customization (shipping, fees, payment settings, validations) and Bookings customization (staff sorting), but service plugins can extend any Wix business solution that exposes SPIs.
+
+## Quick Start Checklist
+
+Follow these steps in order when creating a service plugin:
+
+1. [ ] **Read the reference doc** for your SPI type, then **STOP and call `ReadFullDocsMethodSchema`** with the docs URL from the reference to get the exact request/response types — **DO NOT write any code until you have the schema**
+2. [ ] Create plugin folder: `src/extensions/backend/service-plugins/<service-type>/<plugin-name>/`
+3. [ ] Create `plugin.ts` with correct imports and `provideHandlers()` call
+4. [ ] Implement all required handler functions with complete business logic
+5. [ ] Create `extensions.ts` with appropriate builder method and unique UUID
+6. [ ] Update `src/extensions.ts` to import and use the new extension
+7. [ ] Run `npx tsc --noEmit` to verify TypeScript compiles
+8. [ ] Run `npx wix build` to verify build succeeds
+9. [ ] Test by triggering the relevant site action (e.g., add to cart for fees)
+
+## References
+
+**You MUST read the relevant reference document before implementing a relevant SPI.** Each reference contains the correct imports, handler signatures, response structures, and working examples.
+
+| SPI Type | Reference |
+| --- | --- |
+| Additional Fees | [ADDITIONAL-FEES.md](service-plugin/ADDITIONAL-FEES.md) |
+| Discount Triggers | [DISCOUNT-TRIGGERS.md](service-plugin/DISCOUNT-TRIGGERS.md) |
+| Gift Cards | [GIFT-CARDS.md](service-plugin/GIFT-CARDS.md) |
+| Payment Settings | [PAYMENT-SETTINGS.md](service-plugin/PAYMENT-SETTINGS.md) |
+| Shipping Rates | [SHIPPING-RATES.md](service-plugin/SHIPPING-RATES.md) |
+| Validations | [VALIDATIONS.md](service-plugin/VALIDATIONS.md) |
+| Bookings Staff Sorting | [BOOKINGS-STAFF-SORTING.md](service-plugin/BOOKINGS-STAFF-SORTING.md) |
+
+## Output Structure
+
+Service plugins consist of two files that work together. Registration of plugins requires an extension builder file.
+
+```
+src/extensions/backend/service-plugins/
+└── {service-type}/
+    └── {plugin-name}/
+        ├── plugin.ts           # Handler logic with provideHandlers()
+        └── extensions.ts       # Builder configuration (id, name, source)
+```
+
+### File Descriptions
+
+| File | Purpose |
+| --- | --- |
+| `plugin.ts` | Contains the service plugin handler logic with `provideHandlers()` - this is where you implement your custom business logic |
+| `extensions.ts` | Contains the service plugin builder configuration with id (GUID), name, source path, and builder-specific optional fields |
+
+## Implementation Requirements
+
+### Generation Requirements
+
+1. **Implement ALL required handler functions** with complete business logic
+2. **Include proper TypeScript types and error handling**
+3. **Focus on implementing the EXACT business logic** described in the user prompt
+
+### Implementation Patterns
+
+- **If capabilities are undocumented/unavailable**, explicitly state the gap and proceed only with documented minimal logic
+- **Implement all required handler functions** according to Wix specifications
+- **Never use placeholders** - always implement complete, working functionality
+
+### Data Validation
+
+All service plugins must include comprehensive data validation:
+
+- **Validate all input data** from Wix requests
+- **Ensure required fields** are present and properly formatted
+- **Handle missing or malformed data** gracefully
+- **Validate business logic constraints** (e.g., minimum order amounts, valid addresses)
+
+## Implementation Pattern
+
+The handler file (`plugin.ts`) contains the service plugin logic. It must:
+
+1. Import the relevant service plugin from the appropriate package (e.g., `@wix/ecom/service-plugins` for eCommerce, `@wix/bookings/service-plugins` for Bookings)
+2. Call `provideHandlers()` with an object containing handler functions
+3. Each handler function receives a payload with `request` and `metadata`
+4. Return the expected response structure for that SPI type
+
+```typescript
+import { shippingRates } from "@wix/ecom/service-plugins";
+
+shippingRates.provideHandlers({
+  getShippingRates: async (payload) => {
+    const { request, metadata } = payload;
+
+    // Implement custom logic based on request data
+    // - request contains cart items, shipping address, etc.
+    // - metadata contains currency, locale, etc.
+
+    return {
+      shippingRates: [
+        {
+          code: "custom-shipping",
+          title: "Custom Shipping",
+          logistics: {
+            deliveryTime: "3-5 business days",
+          },
+          cost: {
+            price: "9.99",
+            currency: metadata.currency || "USD",
+          },
+        },
+      ],
+    };
+  },
+});
+```
+
+Handler functions are called automatically by Wix when the relevant site action triggers them. Your custom logic should be placed inside each handler function.
+
+## Elevating Permissions for API Calls
+
+When making Wix API calls from service plugins, you must elevate permissions using `auth.elevate` from `@wix/essentials`.
+
+```typescript
+import { auth } from "@wix/essentials";
+import { items } from "@wix/data";
+
+export const myFunction = async () => {
+  const elevatedFunction = auth.elevate(items.query);
+  const elevatedResponse = await elevatedFunction("myCollection");
+  return elevatedResponse;
+};
+```
+
+```typescript
+import { auth } from "@wix/essentials";
+import { cart } from "@wix/ecom";
+
+export const myFunction = async () => {
+  const elevatedFunction = auth.elevate(cart.getCart);
+  const elevatedResponse = await elevatedFunction("cart-id");
+  return elevatedResponse;
+};
+```
+
+```typescript
+import { auth } from "@wix/essentials";
+import { products } from "@wix/stores";
+
+export const myFunction = async () => {
+  const elevatedFunction = auth.elevate(products.deleteCollection);
+  const elevatedResponse = await elevatedFunction("collection-id");
+  return elevatedResponse;
+};
+```
+
+## Best Practices
+
+### Development Workflow
+
+- **Always implement complete, working functionality** - never use placeholders
+- **Handle all required fields** according to Wix documentation
+- **Implement proper validation** for all input data
+- **Return responses in exact format** expected by Wix
+- **Add comprehensive error handling** for all failure scenarios
+- **Use meaningful variable names** and clear code structure
+- **Test thoroughly** with different input combinations
+
+### Implementation Guidelines
+
+- **Validate all input:** Check required fields are present and properly formatted
+- **Handle errors gracefully:** Return appropriate error responses, don't throw unhandled exceptions
+- **Return exact format:** Responses must match Wix documented structure exactly
+- **Use TypeScript types:** Leverage SDK types for better type safety
+- **Test edge cases:** Empty carts, missing addresses, invalid data
+- **Performance:** Keep calculations efficient - these run on every checkout
+- **Logging:** Add console.log for debugging but keep production logs minimal
+
+## Extension Registration
+
+**Extension registration is MANDATORY and has TWO required steps.**
+
+### Step 1: Create Plugin-Specific Extension File
+
+Each service plugin requires an `extensions.ts` file in its folder with the appropriate builder method for the SPI type:
+
+```typescript
+import { extensions } from "@wix/astro/builders";
+
+export const ecomadditionalfeesMyFees = extensions.ecomAdditionalFees({
+  id: "{{GENERATE_UUID}}",
+  name: "My Additional Fees",
+  source: "./extensions/backend/service-plugins/ecom-additional-fees/my-fees/plugin.ts",
+});
+```
+
+**CRITICAL: UUID Generation**
+
+The `id` must be a unique, static UUID v4 string. Generate a fresh UUID for each extension - do NOT use `randomUUID()` or copy UUIDs from examples. Replace `{{GENERATE_UUID}}` with a freshly generated UUID like `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`.
+
+### Builder Configuration Fields
+
+All builder methods accept these three fields:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | string | Service plugin ID as a GUID. Must be unique across all extensions in the project. |
+| `name` | string | The service plugin name (visible in app dashboard when developing an app). |
+| `source` | string | Path to the service plugin handler file that contains the plugin logic. |
+
+**Builder methods by SPI type and their accepted fields:**
+
+| SPI Type          | Builder Method           | Accepted Fields |
+| ----------------- | ------------------------ | --------------- |
+| Shipping Rates    | `ecomShippingRates()`    | `id`, `name`, `source`, `description`, `learnMoreUrl`, `dashboardUrl`, `fallbackDefinitionMandatory`, `thumbnailUrl` |
+| Additional Fees   | `ecomAdditionalFees()`   | `id`, `name`, `source` |
+| Validations       | `ecomValidations()`      | `id`, `name`, `source`, `validateInCart` |
+| Discount Triggers | `ecomDiscountTriggers()` | `id`, `name`, `source` |
+| Gift Cards        | `ecomGiftCards()`        | `id`, `name`, `source` |
+| Payment Settings  | `ecomPaymentSettings()`  | `id`, `name`, `source`, `fallbackValueForRequires3dSecure` |
+| Bookings Staff Sorting | `bookingsStaffSortingProvider()` | `id`, `name`, `source`, `methodName`, `methodDescription` (max 100 chars), `dashboardPluginId` |
+
+Only `ecomShippingRates()` accepts `description`. Passing unsupported fields to other builders causes TypeScript errors. `bookingsStaffSortingProvider()` requires `methodName` and `methodDescription` fields (methodDescription has a 100-character limit), and optionally accepts `dashboardPluginId`.
+
+### Step 2: Register in Main Extensions File
+
+**CRITICAL:** After creating the plugin-specific extension file, you MUST read [Extension Registration reference](EXTENSION_REGISTRATION.md) and follow the "App Registration" section to update `src/extensions.ts`.
+
+**Without completing Step 2, the service plugin will not be active in the eCommerce system.**
+
+## Testing Service Plugins
+
+To test your service plugin extension:
+
+1. **Release a version** with your changes - new service plugins or changes to existing ones won't take effect until you've built and released your project
+2. **Trigger the call** to your service plugin by performing the relevant action (e.g., add items to cart and view cart to test Additional Fees)

package/skills/wix-app/references/SITE_PLUGIN.md

@@ -0,0 +1,436 @@
+
+# Wix Site Plugin Builder
+
+Creates site plugin extensions for Wix CLI applications. Site plugins are custom elements that integrate into predefined **slots** within Wix business solutions (like Wix Stores, Wix Bookings, Wix eCommerce), extending their functionality and user experience.
+
+Site owners can place site plugins into UI slots using the plugin explorer in Wix editors.
+
+## Quick Start Checklist
+
+Follow these steps in order when creating a site plugin:
+
+1. [ ] Create plugin folder: `src/extensions/site/plugins/<plugin-name>/`
+2. [ ] Create `<plugin-name>.tsx` extending `HTMLElement` with `observedAttributes`
+3. [ ] Create `<plugin-name>.panel.tsx` with WDS components and `widget.getProp/setProp`
+4. [ ] Create `<plugin-name>.extension.ts` with `extensions.sitePlugin()` and unique UUID
+5. [ ] Update `src/extensions.ts` to import and use the new extension
+
+## Architecture
+
+Site plugins consist of **three required files**:
+
+### 1. Plugin Component (`<plugin-name>.tsx`)
+
+Custom element component that renders in the slot using native HTMLElement:
+
+- Extend `HTMLElement` class
+- Define `observedAttributes` for reactive properties
+- Implement `connectedCallback()` and `attributeChangedCallback()` for rendering
+- Use inline styles via template strings
+- Attributes use **kebab-case** (e.g., `display-name`)
+
+### 2. Settings Panel (`<plugin-name>.panel.tsx`)
+
+Settings panel shown in the Wix Editor sidebar:
+
+- Uses Wix Design System (`@wix/design-system`) components — see the `wix-design-system` skill for component reference
+- Manages plugin properties via `@wix/editor` widget API
+- Loads initial values with `widget.getProp('kebab-case-name')`
+- Updates properties with `widget.setProp('kebab-case-name', value)`
+- Widget properties are bound to custom element attributes — any property change automatically updates the corresponding attribute
+- Wrapped in `WixDesignSystemProvider > SidePanel > SidePanel.Content`
+
+### 3. Extension Configuration (`<plugin-name>.extension.ts`)
+
+Defines the plugin's placement configuration:
+
+- Specifies which slots the plugin can be added to
+- Configures auto-add behavior on app installation
+- Sets the tag name and file paths
+
+## Plugin Component Pattern
+
+Site plugins use native `HTMLElement` custom elements:
+
+```typescript
+// my-site-plugin.tsx
+class MyElement extends HTMLElement {
+  static get observedAttributes() {
+    return ['display-name'];
+  }
+
+  constructor() {
+    super();
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback() {
+    this.render();
+  }
+
+  render() {
+    const displayName = this.getAttribute('display-name') || "Your Plugin's Title";
+
+    this.innerHTML = `
+      <div style="font-size: 16px; padding: 16px; border: 1px solid #ccc; border-radius: 8px; margin: 16px;">
+        <h2>${displayName}</h2>
+        <hr />
+        <p>
+          This is a Site Plugin generated by Wix CLI.<br />
+          Edit your element's code to change this text.
+        </p>
+      </div>
+    `;
+  }
+}
+
+export default MyElement;
+```
+
+**Key Points:**
+
+- Extend `HTMLElement` class directly
+- Define `observedAttributes` static getter to list reactive attributes
+- Attributes use **kebab-case** (e.g., `display-name`, `bg-color`)
+- Implement `connectedCallback()` for initial render
+- Implement `attributeChangedCallback()` to re-render when attributes change
+- Use inline styles via template strings
+- Use `this.getAttribute('attribute-name')` to read attribute values
+- Wix handles `define()` for you — do NOT call `customElements.define()` in your code
+
+## Settings Panel Pattern
+
+```typescript
+// my-site-plugin.panel.tsx
+import React, { type FC, useState, useEffect, useCallback } from 'react';
+import { widget } from '@wix/editor';
+import {
+  SidePanel,
+  WixDesignSystemProvider,
+  Input,
+  FormField,
+} from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+
+const Panel: FC = () => {
+  const [displayName, setDisplayName] = useState<string>('');
+
+  useEffect(() => {
+    widget.getProp('display-name')
+      .then(displayName => setDisplayName(displayName || "Your Plugin's Title"))
+      .catch(error => console.error('Failed to fetch display-name:', error));
+  }, [setDisplayName]);
+
+  const handleDisplayNameChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
+    const newDisplayName = event.target.value;
+    setDisplayName(newDisplayName);
+    widget.setProp('display-name', newDisplayName);
+  }, [setDisplayName]);
+
+  return (
+    <WixDesignSystemProvider>
+      <SidePanel width="300" height="100vh">
+        <SidePanel.Content noPadding stretchVertically>
+          <SidePanel.Field>
+            <FormField label="Display Name">
+              <Input
+                type="text"
+                value={displayName}
+                onChange={handleDisplayNameChange}
+                aria-label="Display Name"
+              />
+            </FormField>
+          </SidePanel.Field>
+        </SidePanel.Content>
+      </SidePanel>
+    </WixDesignSystemProvider>
+  );
+};
+
+export default Panel;
+```
+
+**Key Points:**
+
+- Prop names in `widget.getProp()` and `widget.setProp()` use **kebab-case** (e.g., `"display-name"`)
+- Always update both local state AND widget prop in onChange handlers
+- Widget properties are bound to custom element attributes — changes automatically update the corresponding attribute
+- Wrap content in `WixDesignSystemProvider > SidePanel > SidePanel.Content`
+- Use WDS components from `@wix/design-system`
+- Import `@wix/design-system/styles.global.css` for styles
+- Include `aria-label` for accessibility
+
+## Color & Font Picker Fields
+
+Site plugin settings panels can use `inputs.selectColor()` and `inputs.selectFont()` from `@wix/editor` to open the native Wix Editor color and font picker dialogs.
+
+### ColorPickerField
+
+Opens the Wix color picker with theme colors, gradients, and more — **NOT** a basic HTML `<input type="color">`.
+
+```typescript
+import React, { type FC } from 'react';
+import { inputs } from '@wix/editor';
+import { FormField, Box, FillPreview, SidePanel } from '@wix/design-system';
+
+interface ColorPickerFieldProps {
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+}
+
+export const ColorPickerField: FC<ColorPickerFieldProps> = ({
+  label,
+  value,
+  onChange,
+}) => (
+  <SidePanel.Field>
+    <FormField label={label}>
+      <Box width="30px" height="30px">
+        <FillPreview
+          fill={value}
+          onClick={() => inputs.selectColor(value, { onChange: (val) => { if (val) onChange(val); } })}
+        />
+      </Box>
+    </FormField>
+  </SidePanel.Field>
+);
+```
+
+### FontPickerField
+
+Opens the Wix font picker with font family, size, bold, italic, and other typography features.
+
+```typescript
+import React, { type FC } from 'react';
+import { inputs } from '@wix/editor';
+import { FormField, Button, Text, SidePanel } from '@wix/design-system';
+
+interface FontValue {
+  font: string;
+  textDecoration: string;
+}
+
+interface FontPickerFieldProps {
+  label: string;
+  value: FontValue;
+  onChange: (value: FontValue) => void;
+}
+
+export const FontPickerField: FC<FontPickerFieldProps> = ({
+  label,
+  value,
+  onChange,
+}) => (
+  <SidePanel.Field>
+    <FormField label={label}>
+      <Button
+        size="small"
+        priority="secondary"
+        onClick={() => inputs.selectFont(value, { onChange: (val) => onChange({ font: val.font, textDecoration: val.textDecoration || "" }) })}
+        fullWidth
+      >
+        <Text size="small" ellipsis>Change Font</Text>
+      </Button>
+    </FormField>
+  </SidePanel.Field>
+);
+```
+
+**Important:**
+- Always use `inputs.selectColor()` from `@wix/editor` with `FillPreview` — do NOT use `<Input type="color">`
+- Always use `inputs.selectFont()` from `@wix/editor` with the callback pattern `inputs.selectFont(value, { onChange })`
+- Import `inputs` from `@wix/editor` (not from `@wix/sdk`)
+
+## Attribute Naming Convention
+
+Site plugins use **kebab-case** consistently for HTML attributes:
+
+| File                              | Convention | Example                            |
+| --------------------------------- | ---------- | ---------------------------------- |
+| `<plugin>.tsx` (getAttribute)     | kebab-case | `this.getAttribute('display-name')` |
+| `<plugin>.tsx` (observedAttributes) | kebab-case | `['display-name', 'bg-color']`     |
+| `<plugin>.panel.tsx` (widget API) | kebab-case | `widget.getProp('display-name')`   |
+
+## Output Structure
+
+Site plugins live under `src/extensions/site/plugins`. Each plugin has its own folder with files named after the plugin.
+
+```
+src/extensions/site/plugins/
+└── {plugin-name}/
+    ├── {plugin-name}.tsx           # Main plugin component (HTMLElement)
+    ├── {plugin-name}.panel.tsx     # Settings panel component
+    └── {plugin-name}.extension.ts  # Extension registration
+public/
+└── {plugin-name}-logo.svg          # Plugin logo (optional)
+```
+
+## References
+
+| Topic | Reference |
+| --- | --- |
+| Complete Examples | [EXAMPLES.md](site-plugin/EXAMPLES.md) |
+| Slots (App IDs, multiple placements, finding slots) | [SLOTS.md](site-plugin/SLOTS.md) |
+| WDS Components | the `wix-design-system` skill |
+
+## Available Slots
+
+Site plugins integrate into predefined slots in Wix business solutions. Each slot is identified by:
+
+- **appDefinitionId**: The ID of the Wix app (e.g., Stores, Bookings)
+- **widgetId**: The ID of the page containing the slot
+- **slotId**: The specific slot identifier
+
+Common placement areas include product pages (Wix Stores), checkout and side cart (Wix eCommerce), booking pages (Wix Bookings), service pages, event pages, and blog post pages.
+
+For supported pages, common Wix App IDs, and how to find slot IDs, see [SLOTS.md](site-plugin/SLOTS.md).
+
+## Extension Registration
+
+**Extension registration is MANDATORY and has TWO required steps.**
+
+### Step 1: Create Plugin-Specific Extension File
+
+Each site plugin requires an extension file in its folder:
+
+```typescript
+// my-site-plugin.extension.ts
+import { extensions } from '@wix/astro/builders';
+
+export default extensions.sitePlugin({
+  id: '{{GENERATE_UUID}}',
+  name: 'My Site Plugin',
+  marketData: {
+    name: 'My Site Plugin',
+    description: 'Marketing Description',
+    logoUrl: '{{BASE_URL}}/my-site-plugin-logo.svg',
+  },
+  placements: [{
+    appDefinitionId: 'a0c68605-c2e7-4c8d-9ea1-767f9770e087',
+    widgetId: '6a25b678-53ec-4b37-a190-65fcd1ca1a63',
+    slotId: 'product-page-details-6',
+  }],
+  installation: { autoAdd: true },
+  tagName: 'my-site-plugin',
+  element: './extensions/site/plugins/my-site-plugin/my-site-plugin.tsx',
+  settings: './extensions/site/plugins/my-site-plugin/my-site-plugin.panel.tsx',
+});
+```
+
+**CRITICAL: UUID Generation**
+
+The `id` must be a unique, static UUID v4 string. Generate a fresh UUID for each extension - do NOT use `randomUUID()` or copy UUIDs from examples. Replace `{{GENERATE_UUID}}` with a freshly generated UUID like `"95a28afd-7df1-4e09-9ec1-ce710b0389a0"`.
+
+| Property                   | Type    | Description                                                     |
+| -------------------------- | ------- | --------------------------------------------------------------- |
+| `id`                       | string  | Unique static UUID v4 (generate fresh)                          |
+| `name`                     | string  | Internal name for the plugin                                    |
+| `marketData.name`          | string  | Display name in plugin explorer and app dashboard               |
+| `marketData.description`   | string  | Description shown in plugin explorer and app dashboard          |
+| `marketData.logoUrl`       | string  | Path to logo file (`{{BASE_URL}}` resolves to public folder)    |
+| `placements`               | array   | Array of slot placements where plugin can be added              |
+| `placements.appDefinitionId` | string | ID of the Wix app containing the slot                          |
+| `placements.widgetId`      | string  | ID of the page containing the slot                              |
+| `placements.slotId`        | string  | ID of the specific slot                                         |
+| `installation.autoAdd`       | boolean | Whether to auto-add plugin to slots on app installation       |
+| `tagName`                  | string  | HTML custom element tag (kebab-case, must contain a hyphen)     |
+| `element`                  | string  | Relative path to plugin component                               |
+| `settings`                 | string  | Relative path to settings panel component                       |
+
+### Step 2: Register in Main Extensions File
+
+**CRITICAL:** After creating the plugin-specific extension file, you MUST read [Extension Registration reference](EXTENSION_REGISTRATION.md) and follow the "App Registration" section to update `src/extensions.ts`.
+
+**Without completing Step 2, the site plugin will not be available in the plugin explorer.**
+
+## Checkout Plugins
+
+If you are building a plugin for the **checkout page**, it may not support automatic addition upon installation. You must create a dashboard page to provide users with a way to add the plugin to their site. See [EXAMPLES.md](site-plugin/EXAMPLES.md) for the dashboard page pattern.
+
+## Examples
+
+For complete examples with all three required files (plugin component, settings panel, extension configuration), see [EXAMPLES.md](site-plugin/EXAMPLES.md).
+
+**Example use cases:**
+
+- **Best Seller Badge** - Customizable badge on product pages with text and color settings
+- **Booking Confirmation** - Custom confirmation message for booking pages
+- **Product Reviews Summary** - Star rating and review count display
+- **Data-Driven Plugin** - Plugin with Wix Data API integration and editor environment handling
+
+## Best Practices
+
+### Implementation Guidelines
+
+- **Use inline styles** - CSS imports are not supported in custom elements
+- **Handle editor environment** - Show placeholders when in editor mode for data-dependent plugins
+- **Do not call `define()`** - Wix handles `customElements.define()` for you automatically
+- **Validate all input** - Check required props are present
+- **Follow naming conventions** - kebab-case for all attributes and widget API
+- **Keep plugins focused** - Each plugin should do one thing well
+- **Test in multiple slots** - If supporting multiple placements, test each one
+- **Support both Stores versions** - Include placements for both old and new Wix Stores product pages for maximum compatibility
+
+### Editor Sandboxing
+
+Site plugins are sandboxed when rendered in the editor. This means they're treated as if they come from a different domain, which impacts access to browser storage APIs.
+
+**Restricted APIs in the editor:**
+- `localStorage` and `sessionStorage` (Web Storage API)
+- `document.cookie` (Cookie Store API)
+- IndexedDB API
+- Cache API
+
+**How to handle sandboxing:**
+
+Use the `viewMode()` function from `@wix/site-window` to check the current mode before accessing restricted APIs:
+
+```typescript
+import { window as wixWindow } from '@wix/site-window';
+
+const viewMode = await wixWindow.viewMode();
+
+if (viewMode === 'Site') {
+  const item = localStorage.getItem('myKey');
+} else {
+  // Mock storage or modify API usage for editor mode
+}
+```
+
+### Using Wix SDK Modules in Site Plugins
+
+Site plugins can import and use Wix SDK modules directly — you do NOT need `createClient()`. The Wix runtime provides the client context automatically.
+
+```typescript
+// ✅ CORRECT — Import SDK modules directly
+import { items } from "@wix/data";
+import { currentCart } from "@wix/ecom";
+import { products } from "@wix/stores";
+
+class MyPlugin extends HTMLElement {
+  async loadData() {
+    // Call SDK methods directly — no createClient needed
+    const result = await items.query("MyCollection").find();
+    const cart = await currentCart.getCurrentCart();
+    const productList = await products.queryProducts().limit(10).find();
+  }
+}
+```
+
+```typescript
+// ❌ WRONG — Do NOT use createClient in site plugins
+import { createClient } from "@wix/sdk";
+const wixClient = createClient({ modules: { items, products } });
+await wixClient.items.query(...); // Wrong — API surface differs through client
+```
+
+### Performance Considerations
+
+- Keep bundle size small - plugins load on user-facing pages
+- Avoid heavy computations on initial render
+- Lazy load data when possible
+- Use efficient re-rendering patterns