@embeddables/cli 0.11.0 → 0.12.0

package/.prompts/custom/build-funnel.md

@@ -2,7 +2,7 @@ We need to build the pages from the attached images. Please create a plan and hi
 
 Embeddable ID: <EMBEDDABLE_ID>
 
-Important: Always read the Embeddables CLI context before starting (e.g. @.cursor/rules/embeddables-cli.md, @.claude/embeddables-cli.md, or @AGENTS.md depending on your editor).
+Important: Always read the Embeddables CLI context before starting (e.g. @.cursor/rules/embeddables-cli.md, @.claude/embeddables-cli.md, @AGENTS.md, or @.agent/rules/embeddables-cli.md depending on your editor).
 
 [KEEP / REMOVE]
 Use the designs from the images but use the content from the attached document instead, and build out the pages based on that content. Therefore, when using the designs from the images, for each page just find the most relevant design for the page's content and design it based on that. However, don't be confined to the provided designs - just find the closest design and modify it to fit the content required.

package/.prompts/embeddables-cli.md

@@ -7,7 +7,9 @@ alwaysApply: true
 
 This document provides comprehensive context for Cursor AI when working with Embeddables in the CLI codebase. The CLI transforms Embeddable JSON into a local file structure for development, then compiles it back to JSON for saving.
 
-**Note**: All TypeScript types are defined in `.types/types-builder.d.ts`. Refer to that file for complete type definitions. This document focuses on contextual information about how the system works.
+## Types as Source of Truth (MANDATORY)
+
+**Always consult `.types/` before adding, modifying, or using component props, Flow properties, or any API.** The types are the authoritative source of truth.
 
 ## Overview
 
@@ -498,13 +500,17 @@ Computed fields are stored in `Flow.computedFields` and transform to JS files. T
 
 **File Mapping**: `computed-fields/{key}.js` (e.g., `computed-fields/total_price.js`)
 
-**Code Structure**: The `code` property contains JavaScript that must include a function called `result` that returns the computed value:
+**Code Structure**: The `code` property contains JavaScript that must include a function called `result`. The runtime passes a `context` object as the first argument:
 
 ```javascript
-function result() {
+function result(context) {
   // Access user data via global userData object
   const price = userData.price || 0
   const quantity = userData.quantity || 0
+
+  // context.triggerContext is available (see Actions section for shape)
+  // context.trackCustomEvent(name, props) can track analytics events
+
   return price * quantity
 }
 ```
@@ -515,6 +521,7 @@ function result() {
 - The function has access to a global `userData` object containing all user data
 - If `async` is true, the function can return a Promise
 - `input_triggers` specify additional keys that trigger recalculation
+- The `context` parameter provides `triggerContext` and `trackCustomEvent()` — same as actions (see "Trigger Context" and "Custom Event Tracking" under Actions)
 
 ## Actions Structure
 
@@ -529,14 +536,20 @@ Actions are stored in `Flow.dataOutputs` and transform to JS files. The `Action`
 
 **File Mapping**: `actions/{name}.js` (e.g., `actions/submit_form.js`)
 
-**Code Structure**: For `output: "custom"`, the `code` property contains JavaScript that must include a function called `output`:
+**Code Structure**: For `output: "custom"`, the `code` property contains JavaScript that must include a function called `output`. The runtime passes a `context` object as the first argument:
 
 ```javascript
-function output() {
+function output(context) {
   // Access user data via global userData object
   const email = userData.email
   const name = userData.name
 
+  // context.triggerContext contains metadata about what fired this action (see below)
+  const trigger = context.triggerContext
+
+  // Track a custom analytics event (in-action usage)
+  context.trackCustomEvent('form_submitted', { email })
+
   // Perform action (API call, data transformation, etc.)
   return {
     success: true,
@@ -547,10 +560,195 @@ function output() {
 
 **Important**:
 
-- Actions are triggered by various events (button clicks, page completion, etc.)
+- Actions are triggered by `outputs_on*` fields (see "Action Trigger Wiring" below) or programmatically
 - The function has access to a global `userData` object
+- The `context` parameter provides `triggerContext` and `trackCustomEvent` (see below)
 - For non-custom actions (airtable, hubspot, etc.), the action configuration is stored in config.json, not in the JS file
 
+### Action Trigger Wiring (`outputs_on*` Fields)
+
+Actions are wired to events via `outputs_on*` properties. Each property holds an **action ID** (string) or an **array of action IDs** (`string[]`) referencing entries in `dataOutputs`. When the event fires, the engine runs the referenced actions.
+
+#### Flow-Level Triggers
+
+These are top-level properties on the `Flow` object (stored in `config.json`):
+
+| Field                  | Type                 | Fires when                                     |
+| ---------------------- | -------------------- | ---------------------------------------------- |
+| `outputs_onloadflow`   | `string \| string[]` | The embeddable script loads and initializes    |
+| `outputs_onviewflow`   | `string \| string[]` | The embeddable becomes visible in the viewport |
+| `outputs_onremoved`    | `string[]`           | The embeddable is removed from the DOM         |
+| `outputs_onopenpopup`  | `string \| string[]` | A popup embeddable is opened                   |
+| `outputs_onclosepopup` | `string \| string[]` | A popup embeddable is closed                   |
+
+#### Page-Level Triggers
+
+These are properties on `FlowPage` objects (stored in the page entry in `config.json`):
+
+| Field                     | Type                 | Fires when                                                 |
+| ------------------------- | -------------------- | ---------------------------------------------------------- |
+| `outputs_oncomplete`      | `string \| string[]` | The user completes this page (i.e. moves to the next page) |
+| `outputs_onload`          | `string \| string[]` | The page is loaded / navigated to                          |
+| `outputs_onopen_infobox`  | `string[]`           | An info box on this page is opened                         |
+| `outputs_onclose_infobox` | `string[]`           | An info box on this page is closed                         |
+
+#### Component-Level Triggers
+
+These are properties on component objects (written as props in React/TSX files):
+
+**Base (all components)**:
+
+| Field                        | Type       | Fires when                           |
+| ---------------------------- | ---------- | ------------------------------------ |
+| `outputs_onmounted`          | `string[]` | The component mounts in the DOM      |
+| `outputs_onunmounted`        | `string[]` | The component unmounts from the DOM  |
+| `outputs_onrepeatablerender` | `string[]` | A repeater re-renders this component |
+
+**CustomButton**:
+
+| Field             | Type                 | Fires when            |
+| ----------------- | -------------------- | --------------------- |
+| `outputs_onclick` | `string \| string[]` | The button is clicked |
+
+**InputBox**:
+
+| Field              | Type       | Fires when              |
+| ------------------ | ---------- | ----------------------- |
+| `outputs_onchange` | `string[]` | The input value changes |
+
+**OptionSelector**:
+
+| Field                               | Type       | Fires when                     |
+| ----------------------------------- | ---------- | ------------------------------ |
+| `outputs_onchange`                  | `string[]` | The selected option(s) change  |
+| `outputs_onbuttonsrepeatablerender` | `string[]` | The button repeater re-renders |
+
+**FileUpload**:
+
+| Field              | Type       | Fires when                    |
+| ------------------ | ---------- | ----------------------------- |
+| `outputs_onchange` | `string[]` | Files are uploaded or removed |
+
+**Payment Components** (StripeCheckout2, PaypalCheckout):
+
+| Field                          | Type     | Fires when                         |
+| ------------------------------ | -------- | ---------------------------------- |
+| `on_payment_complete_outputs`  | `string` | Payment succeeds                   |
+| `on_payment_failed_outputs`    | `string` | Payment fails (Stripe only)        |
+| `on_payment_attempted_outputs` | `string` | Payment is attempted (Stripe only) |
+
+#### Example: Wiring an Action to a Button Click
+
+```tsx
+<CustomButton
+  id="comp_0000000001"
+  key="submit_button"
+  text="Submit"
+  action="no-action"
+  outputs_onclick={['action_1234567890']}
+/>
+```
+
+Where `action_1234567890` is the `id` of an action in `dataOutputs`. The button's built-in `action` prop (`"next-page"`, `"prev-page"`, etc.) handles navigation; `outputs_onclick` fires separate data actions.
+
+#### Example: Wiring an Action to Page Completion
+
+In `config.json`:
+
+```json
+{
+  "pages": [
+    {
+      "id": "page_0000000001",
+      "key": "contact_page",
+      "outputs_oncomplete": ["action_1234567890"]
+    }
+  ]
+}
+```
+
+### Programmatic Action Triggering
+
+You can trigger an Action from code by doing this:
+
+```javascript
+window.Savvy.triggerAction(embeddableId, actionId)
+```
+
+### Trigger Context (`triggerContext`)
+
+When the engine fires an action, it passes a `context` object to the `output(context)` function. `context.triggerContext` contains metadata about what triggered the action:
+
+| Field          | Type                  | Description                                                                                                                       |
+| -------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `triggerType`  | `string`              | The event type that fired the action (e.g. `"onclick"`, `"onchange"`, `"oncomplete"`, `"onloadflow"`, `"onviewflow"`, `"manual"`) |
+| `componentId`  | `string \| undefined` | The component ID that fired the trigger (for component-level triggers)                                                            |
+| `componentKey` | `string \| undefined` | The component key that fired the trigger                                                                                          |
+| `pageId`       | `string \| undefined` | The page ID associated with the trigger                                                                                           |
+| `pageKey`      | `string \| undefined` | The page key associated with the trigger                                                                                          |
+
+Example usage inside an action:
+
+```javascript
+function output(context) {
+  const { triggerType, componentKey, pageKey } = context.triggerContext || {}
+
+  if (triggerType === 'oncomplete' && pageKey === 'checkout_page') {
+    // Only run full submission on checkout page completion
+    return submitOrder(userData)
+  }
+
+  // For other triggers, just track progress
+  return { tracked: true }
+}
+```
+
+Computed fields also receive `context` in the `result(context)` function with the same `triggerContext` shape, which is useful for computed fields that need to behave differently based on what triggered their recalculation.
+
+### Custom Event Tracking
+
+Embeddables support tracking custom analytics events. There are two contexts where you can track events:
+
+#### 1. Inside Action or Computed Field Code (Runtime Context)
+
+Use `context.trackCustomEvent(eventName, eventProps)` inside `output()` or `result()` functions:
+
+```javascript
+function output(context) {
+  const plan = userData.selected_plan
+
+  // Track a custom event from within an action
+  context.trackCustomEvent('plan_selected', {
+    plan: plan,
+    price: userData.plan_price,
+  })
+
+  return { success: true }
+}
+```
+
+#### 2. From the Host Page (Window API)
+
+Use `window.Savvy.trackCustomEvent(flowId, eventName, eventProps)` from the host page embedding the embeddable:
+
+```javascript
+window.Savvy.trackCustomEvent('flow_abc123', 'external_checkout_complete', {
+  orderId: '12345',
+  total: 99.99,
+})
+```
+
+- `flowId` — the embeddable's `id`
+- `eventName` — a custom event name string
+- `eventProps` — an object of key-value pairs to attach to the event
+
+#### When to Use Which
+
+| Context                        | API                                                  | Use when                                                                                                                                             |
+| ------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Inside `output()` / `result()` | `context.trackCustomEvent(name, props)`              | Tracking events as part of action/computed field logic (e.g. after a form submission, when a computed value changes)                                 |
+| Host page JS                   | `window.Savvy.trackCustomEvent(flowId, name, props)` | Tracking events from outside the embeddable (e.g. after an external checkout, on a parent SPA route change, from a third-party integration callback) |
+
 ## Conditions Structure
 
 Conditions control visibility of components and pages based on User Data. The `Condition`, `ConditionOperator`, `ConditionValue`, and `ConditionalTag` types are defined in `src/types-builder.ts`.
@@ -601,6 +799,7 @@ The `config.json` file contains the reduced Embeddable JSON with:
 - Style selectors but NOT style values (styles are in CSS files)
 - Computed field metadata (id, key, inputs, etc.) but NOT code (code is in JS files)
 - Action metadata (id, name, output, mappings, etc.) but NOT code (code is in JS files)
+- `_docs` (string) — preserved at top-level, in pages, computedFields, and dataOutputs
 - All other Flow properties (experiments, transitions, settings, etc.)
 
 **Example config.json structure**:
@@ -643,6 +842,22 @@ The `config.json` file contains the reduced Embeddable JSON with:
 }
 ```
 
+## \_docs Property
+
+The `_docs` property (string only) documents non-obvious aspects of the embeddable. It can appear at:
+
+- **Top-level** — embeddable-wide notes (e.g. flow purpose, integration details)
+- **Pages** — page-specific notes (e.g. why a page exists, routing logic)
+- **Computed fields** — notes about formulas or dependencies
+- **Actions (dataOutputs)** — notes about what an action does or when it runs
+
+**AI behavior**:
+
+- **Read** all `_docs` when working on an embeddable, page, computed field, or action to understand context that may not be obvious from the code.
+- **Add** `_docs` when building or discovering something that should be documented because it is non-obvious (e.g. a computed field with non-trivial logic, an action with special side effects, a page with conditional routing).
+
+**Storage**: When reverse-compiled, `_docs` is preserved in `config.json` at the corresponding level (top-level, `pages[]`, `computedFields[]`, `dataOutputs[]`).
+
 ## File Organization Rules
 
 ### React Files (Pages)
@@ -671,19 +886,21 @@ The `config.json` file contains the reduced Embeddable JSON with:
 
 - Location: `computed-fields/{key}.js`
 - Export: Function named `result` that returns computed value
-- Access: Global `userData` object available
+- Access: Global `userData` object available; `context` parameter provides `triggerContext` and `trackCustomEvent()`
 
 ### JS Files (Actions)
 
 - Location: `actions/{name}.js`
 - Export: Function named `output` for custom actions
-- Access: Global `userData` object available
+- Access: Global `userData` object available; `context` parameter provides `triggerContext` and `trackCustomEvent()`
 
 ## Key Principles for Modifications
 
-1. **Component Keys**: Must be unique and descriptive. Keys become User Data keys for input components.
+1. **Types first**: Before adding or changing any component props, Flow properties, validation, or behavior, read the relevant interfaces in `.types/types.d.ts`. Use the types as the source of truth—do not guess or infer from examples.
+
+2. **Component Keys**: Must be unique and descriptive. Keys become User Data keys for input components.
 
-2. **Tags**: Used for CSS styling. Apply tags consistently:
+3. **Tags**: Used for CSS styling. Apply tags consistently:
    - Primary tag (required): Describes component type (e.g., `standard_button`, `price_card`)
    - Secondary tag (optional): Variant of primary (e.g., `primary_button`, `outline_button`)
    - Utility tag (optional): Only for margins that can't be applied via primary/secondary (e.g., `m_2`)
@@ -691,28 +908,28 @@ The `config.json` file contains the reduced Embeddable JSON with:
    - Standard tags to recognize:
      `standard_plain_text`, `standard_rich_text`, `standard_container`, `standard_image`, `standard_button`, `standard_media_embed`, `standard_slider`, `standard_input`, `standard_checkbox`, `standard_option_buttons`, `standard_dropdown`, `standard_switch`, `standard_file_upload`, `standard_stripe_checkout`, `standard_calendly`, `standard_hubspot`, `standard_progress_bar`, `standard_progress_circle`
 
-3. **Component Types**:
+4. **Component Types**:
    - Use `PlainText` by default
    - Use `RichTextMarkdown` only for mixed formatting (bold, italic, lists, links, colors)
    - Use `CustomHTML` for presentational content only (overlays, inline SVGs, decorative HTML). **Caution**: CustomHTML is for presentational content only. For interactive elements like buttons or selectable options, always use `CustomButton` or `OptionSelector` — CustomHTML elements have no access to flow actions or user data outputs.
 
-4. **Nested Components**: Containers can have `components[]` array with child components. Render as nested JSX.
+5. **Nested Components**: Containers can have `components[]` array with child components. Render as nested JSX.
 
-5. **Global Components**: Must use the filenames to replace the `_location` property.
+6. **Global Components**: Must use the filenames to replace the `_location` property.
 
-6. **Conditions**: Stored in config.json, applied at runtime. Multiple values in one condition = OR, multiple conditions = AND. For experiment-gated conditions, when setting the control variant's conditions always include both the control variant value and `_no_value` so both control and unassigned users see the intended default.
+7. **Conditions**: Stored in config.json, applied at runtime. Multiple values in one condition = OR, multiple conditions = AND. For experiment-gated conditions, when setting the control variant's conditions always include both the control variant value and `_no_value` so both control and unassigned users see the intended default.
 
-7. **CSS Selectors**: Must follow exact structure with proper spacing (trailing space on breakpoints, leading space on sub-elements).
+8. **CSS Selectors**: Must follow exact structure with proper spacing (trailing space on breakpoints, leading space on sub-elements).
 
-8. **No `!important` in CSS**: Do not use `!important` in embeddable styles. If a style does not apply, fix the selector per the CSS Selector System (principle 7); do not use `!important` as a fix.
+9. **No `!important` in CSS**: Do not use `!important` in embeddable styles. If a style does not apply, fix the selector per the CSS Selector System (principle 8); do not use `!important` as a fix.
 
-9. **User Data Keys**: Input component keys become User Data keys. Choose descriptive names (e.g., `email` not `email_input`).
+10. **User Data Keys**: Input component keys become User Data keys. Choose descriptive names (e.g., `email` not `email_input`).
 
-10. **Computed Field Dependencies**: `inputs` array defines which User Data keys trigger recalculation. Can reference other computed fields.
+11. **Computed Field Dependencies**: `inputs` array defines which User Data keys trigger recalculation. Can reference other computed fields.
 
-11. **Action Triggers**: Actions are triggered by events (button clicks, page completion, etc.). Configuration stored in config.json, code in JS files.
+12. **Action Triggers**: Actions fire from `outputs_on*` fields that store action IDs. Flow-level triggers (e.g. `outputs_onloadflow`) go in `config.json` top-level; page-level triggers (e.g. `outputs_oncomplete`) go in the page entry in `config.json`; component-level triggers (e.g. `outputs_onclick`, `outputs_onchange`) go as props in React files. Actions can be invoked via `window.Savvy.triggerAction()`. See "Action Trigger Wiring" and "Programmatic Action Triggering" sections for details.
 
-12. **Asset URL Source of Truth**: If `assets.json` exists in the project root, use it as the first source for image/file URLs. Prefer matching by `flow_id` (or `flow_id: null` for project-level shared assets) and use `relativePath` when mapping local files to uploaded URLs. Always use the (uploaded) url property, not local relative paths, as the image src when building in React.
+13. **Asset URL Source of Truth**: If `assets.json` exists in the project root, use it as the first source for image/file URLs. Prefer matching by `flow_id` (or `flow_id: null` for project-level shared assets) and use `relativePath` when mapping local files to uploaded URLs. Always use the (uploaded) url property, not local relative paths, as the image src when building in React.
 
 ## Common Patterns
 
@@ -725,11 +942,12 @@ The `config.json` file contains the reduced Embeddable JSON with:
 
 ### Adding a Component to a Page
 
-1. Update the page's React file (`pages/{pageKey}.page.tsx`)
-2. Add component JSX with appropriate props
-3. If new tags are used, ensure CSS exists for those tags
-4. If any tag is a `standard_*` tag, check `default-styles.css` in project root and add missing style selectors for that tag to `styles/index.css`
-5. Update config.json if component metadata is needed (rarely)
+1. Check `.types/types.d.ts` for the component interface (e.g. `InputBox`, `CustomButton`) and `Base` for shared props—use only props that exist in the types.
+2. Update the page's React file (`pages/{pageKey}.page.tsx`)
+3. Add component JSX with appropriate props
+4. If new tags are used, ensure CSS exists for those tags
+5. If any tag is a `standard_*` tag, check `default-styles.css` in project root and add missing style selectors for that tag to `styles/index.css`
+6. Update config.json if component metadata is needed (rarely)
 
 ### Styling a Component
 
@@ -748,9 +966,10 @@ The `config.json` file contains the reduced Embeddable JSON with:
 ### Adding an Action
 
 1. Create JS file: `actions/{name}.js`
-2. Implement `output()` function (for custom actions)
+2. Implement `output(context)` function (for custom actions) — use `context.triggerContext` for trigger metadata and `context.trackCustomEvent()` for analytics
 3. Add metadata to config.json: `dataOutputs` array
 4. Configure action type and mappings in config.json
+5. Wire the action to a trigger: add the action's `id` to the appropriate `outputs_on*` field on the flow (config.json top-level), page (config.json pages entry), or component (React prop)
 
 ### Modifying Global Components