@funnelsgrove/cli 0.1.14 → 0.1.15

package/dist/localSync.js

@@ -198,12 +198,12 @@ function formatByteSize(byteCount) {
 async function readSourceFiles(rootDir, manifestFiles) {
     const files = await Promise.all(manifestFiles.map(async (file) => {
         const absolutePath = path.join(rootDir, assertSafeSyncPath(file.path));
-        const imageContentType = inferImageContentType(file.path);
+        const binaryContentType = inferBinaryContentType(file.path);
         const buffer = await readFile(absolutePath);
         return {
             path: file.path,
-            content: imageContentType ? `data:${imageContentType};base64,${buffer.toString('base64')}` : buffer.toString('utf8'),
-            contentType: imageContentType || 'text/plain',
+            content: binaryContentType ? `data:${binaryContentType};base64,${buffer.toString('base64')}` : buffer.toString('utf8'),
+            contentType: binaryContentType || 'text/plain',
         };
     }));
     return files.sort((left, right) => left.path.localeCompare(right.path));
@@ -242,27 +242,31 @@ async function collectSyncFiles(rootDir, dir) {
 async function hashFile(filePath) {
     return createHash('sha256').update(await readFile(filePath)).digest('hex');
 }
-function inferImageContentType(filePath) {
-    const extension = path.extname(filePath).toLowerCase();
-    if (extension === '.png') {
-        return 'image/png';
-    }
-    if (extension === '.jpg' || extension === '.jpeg') {
-        return 'image/jpeg';
-    }
-    if (extension === '.webp') {
-        return 'image/webp';
-    }
-    if (extension === '.gif') {
-        return 'image/gif';
-    }
-    if (extension === '.svg') {
-        return 'image/svg+xml';
-    }
-    if (extension === '.avif') {
-        return 'image/avif';
-    }
-    return null;
+const BINARY_CONTENT_TYPE_BY_EXTENSION = {
+    '.aac': 'audio/aac',
+    '.avif': 'image/avif',
+    '.flac': 'audio/flac',
+    '.gif': 'image/gif',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.m4a': 'audio/mp4',
+    '.m4v': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.oga': 'audio/ogg',
+    '.ogg': 'audio/ogg',
+    '.ogv': 'video/ogg',
+    '.opus': 'audio/ogg',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.wav': 'audio/wav',
+    '.weba': 'audio/webm',
+    '.webm': 'video/webm',
+    '.webp': 'image/webp',
+};
+function inferBinaryContentType(filePath) {
+    return BINARY_CONTENT_TYPE_BY_EXTENSION[path.extname(filePath).toLowerCase()] || null;
 }
 function decodeDataUrl(content) {
     const match = content.trim().match(/^data:([^;,]+);base64,([A-Za-z0-9+/=\s_-]+)$/);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "type": "module",
   "bin": {

package/template_docs/AGENTS.md

@@ -8,7 +8,7 @@ Source-of-truth guide for editing this synced FunnelsGrove funnel. Read the matc
 | --- | --- | --- | --- |
 | Add or edit a step | [docs/editing-step.md](docs/editing-step.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) | `src/steps/*` + registries + manifest | < 3 min to first preview |
 | Change step order / branching | [docs/editing-flow.md](docs/editing-flow.md) | `src/config/funnel.manifest.ts` | < 2 min |
-| Set up an A/B experiment | [docs/ab-experiments.md](docs/ab-experiments.md) | `src/config/experiments.ts` | < 1 min when variant step exists |
+| Set up an A/B experiment | [docs/ab-experiments.md](docs/ab-experiments.md) | FunnelsGrove UI/API + `src/config/experiments.generated.ts`; manifest steps/edges | < 1 min when variant step exists |
 | Edit copy or images | [docs/editor-and-content.md](docs/editor-and-content.md) | `src/steps/content/*.content.ts` | < 2 min |
 | Edit image loading/performance | [docs/editing-flow.md](docs/editing-flow.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) + [docs/publishing-and-versioning.md](docs/publishing-and-versioning.md) | `src/config/funnel.manifest.ts`, `src/components/FunnelFlow.tsx`, image assets | careful, QA required |
 | Change plans, prices, discounts | [docs/payment-plans-and-discounts.md](docs/payment-plans-and-discounts.md) | `src/config/billing.plans.ts` | careful, read doc fully |
@@ -63,7 +63,7 @@ with the same local source diff.
 4. **Goal-driven execution.** Define the success check before editing ("step renders at all default breakpoints and Continue advances to step-X"), then loop until it passes.
 5. **Image performance locked.** Keep build-time raster compression plus AVIF/WebP variants enabled. For funnel step images, use `funnelManifest.assets` + step `assetIds`, priority/preload only for first-viewport images, and low-priority next-step warming from the shell. Do not preload the whole funnel image set.
 6. **Meaningful URLs.** New step `path` values are public product routes, so use readable slugs like `/motivation`, `/fitness-goal`, or `/email-capture`. Sequential ids and `step-NN-*` filenames are okay for ordering, but do not create public routes like `/step-1`.
-7. **Flow labeling hygiene.** When changing `edgesByStepId`, keep manifest `branches` current for conditional paths that own steps before reconverging. Keep builder metadata ClaimBee-style and source-readable: `edgesByStepId` keys/targets and `branches: [...]` must use inline string literals, not `someStep.id` variables or a `branches: flowBranches` indirection. Each branch needs a readable `name`, answer-derived `label` such as `yes-branch`, useful `tags`, and the owned `stepIds`. Running experiment variants need labels/tags like `paywall-test-control` and `paywall-test-variant-b`; stopped A/B variants or other inactive screens should keep stable tags and remain unreachable from the default flow so builder marks them `unused`.
+7. **Flow labeling hygiene.** When changing `edgesByStepId`, keep manifest `branches` current for conditional paths that own steps before reconverging. Keep builder metadata ClaimBee-style and source-readable: `edgesByStepId` keys/targets and `branches: [...]` must use inline string literals, not `someStep.id` variables or indirection like `branches: flowBranches`. Each branch needs a readable `name`, answer-derived `label` such as `yes-branch`, useful `tags`, and the owned `stepIds`. Every experiment control or variant route target must be a real manifest step with normal outgoing edges. Prefer creating/updating experiments through the FunnelsGrove UI/API so the platform owns the database row, PostHog flag, and generated `src/config/experiments.generated.ts`; keep `src/config/experiments.ts` as the generated compatibility wrapper when possible. If a code-authored experiment is necessary, keep `sourceStepId`/`stepId`, variant labels, traffic percentages, and route target ids as explicit literals so deploy sync and analytics can import it. Running experiment variants need labels/tags like `paywall-test-control` and `paywall-test-variant-b`; stopped A/B variants or other inactive screens should keep stable tags and remain unreachable from the default flow so builder marks them `unused`.
 
 Architecture docs are part of the change: if you change routing, runtime state, SDK contracts, URL handoff parameters, checkout behavior, analytics events, or shared package boundaries, update the matching doc in the same change.
 

package/template_docs/docs/ab-experiments.md

@@ -1,10 +1,53 @@
 # A/B Experiments
 
-Experiments are config, not code: declared in `src/config/experiments.ts`, exported into the manifest, resolved by the shared runtime. Never write variant conditionals inside step components. If the variant step already exists, setting up the experiment is a one-file edit that takes under a minute.
+Experiments are config, not component code. Prefer creating or updating the
+experiment through the FunnelsGrove UI/API, which owns the database row,
+PostHog flag, and generated `src/config/experiments.generated.ts` file. Keep
+`src/config/experiments.ts` as the generated compatibility wrapper when
+possible. Make sure every control or variant route target is a real manifest
+step with normal outgoing edges. Never write variant conditionals inside step
+components. If the variant step already exists, setting up the experiment is
+mostly config plus publish sync.
 
 ## Recipe: Step or Paywall Test
 
-Open `src/config/experiments.ts` and add one entry inside `defineFunnelExperiments([...])`:
+Open `src/config/funnel.manifest.ts` and make sure every control and variant
+screen exists in `steps` with readable tags:
+
+```ts
+steps: [
+  { id: 'paywall', path: '/offer', tags: ['paywall-ab-control'], /* ... */ },
+  { id: 'paywall-b', path: '/offer-b', tags: ['paywall-ab-variant-b'], /* ... */ },
+]
+```
+
+Add normal outgoing edges for both routes:
+
+```ts
+edgesByStepId: {
+  paywall: [{ toStepId: 'checkout' }],
+  'paywall-b': [{ toStepId: 'checkout' }],
+}
+```
+
+Then create the experiment in the FunnelsGrove UI/API and pull the generated
+config. The synced source should export it from `src/config/experiments.generated.ts`
+and keep `src/config/experiments.ts` as a wrapper:
+
+```ts
+import {
+  defineFunnelExperiments,
+  toManifestExperiments,
+} from '@funnelsgrove/runtime';
+import { generatedExperiments } from './experiments.generated';
+
+export const experiments = defineFunnelExperiments(generatedExperiments);
+
+export const manifestExperiments = toManifestExperiments(experiments);
+```
+
+If a code-authored experiment is necessary, add one explicit object inside the
+local experiment array or `defineFunnelExperiments([...])` call:
 
 ```ts
 export const experiments = defineFunnelExperiments([
@@ -12,18 +55,30 @@ export const experiments = defineFunnelExperiments([
     id: 'paywall-ab',                       // durable, readable, never reused
     name: 'Paywall copy test',
     type: 'paywall',                        // 'step' for quiz steps, 'paywall' for paywall tests
-    status: 'running',                      // 'paused' | 'stopped' removes it from the manifest
+    status: 'running',                      // non-running entries stay out of active routing
     launchDate: '2026-06-12T00:00:00.000Z',
-    control: { stepId: 'paywall', label: 'paywall-ab-control', trafficPercent: 50 },
-    variant: { stepId: 'paywall-b', label: 'paywall-ab-variant-b', trafficPercent: 50 },
+    stepId: 'paywall',
+    variants: [
+      { variantKey: 'control', stepId: 'paywall', label: 'paywall-ab-control', trafficPercent: 50 },
+      { variantKey: 'variant_b', stepId: 'paywall-b', label: 'paywall-ab-variant-b', trafficPercent: 50 },
+    ],
   },
 ] as const);
 ```
 
-That's it — `toManifestExperiments(experiments)` in the same file feeds the manifest, traffic percents are validated to sum to 100, and non-`running` entries are filtered out automatically. (Older funnels may declare a plain array and map it manually — follow the local file's existing shape there.) Preconditions (each is its own task if missing):
+Preconditions:
 
-1. Both `control.stepId` and `variant.stepId` exist in the manifest with normal `edgesByStepId` exits ([editing-step.md](editing-step.md) to create a variant step — usually a copy of the control step with one deliberate change).
+1. Every control or variant `stepId` exists in the manifest `steps` array.
 2. Both steps route to the same next step, unless the experiment is explicitly about the flow.
+3. `steps`, `edgesByStepId`, experiment `stepId`, and experiment `label` values use explicit string literals that analytics can read.
+
+The manifest may keep `experiments: manifestExperiments` and import the
+runnable experiment shape from `src/config/experiments.ts`. That is fine as
+long as the separate file exports a generated wrapper or a source-readable
+`experiments` array. Do not hide step ids or labels behind computed variables.
+For route experiments where the source step differs from the rendered control
+step, set `sourceStepId` or `stepId` to the source step and set each variant's
+`stepId` to its rendered route.
 
 ## How the Runtime Behaves
 
@@ -48,7 +103,8 @@ Check: opening the source URL promotes to the assigned route, each variant rende
 
 - One deliberate change per experiment. Don't bundle unrelated edits into a variant.
 - `control` stays stable; never edit the control step as part of launching a variant.
-- Add stable `control.label` and `variant.label` values in the `<experiment-id>-control` / `<experiment-id>-variant-b` format so builder labels and analytics views stay readable.
+- Add stable variant `label` values in the `<experiment-id>-control` / `<experiment-id>-variant-b` format so builder labels and analytics views stay readable.
+- Add matching `steps[].tags` to every control and variant step.
 - Variant keys and experiment ids are durable — they flow into analytics. Never recycle an id for a different hypothesis.
 - Keep every variant step's outgoing edge in `edgesByStepId`, or assigned visitors strand.
 - If a paywall variant changes plans or pricing, follow [payment-plans-and-discounts.md](payment-plans-and-discounts.md) for the plan/discount sync rules and QA both variants' checkout ([qa-checklist.md](qa-checklist.md)).

package/template_docs/docs/editing-flow.md

@@ -15,10 +15,10 @@ The manifest defines:
   variants. Funnel shells may use this data to warm likely next-step images,
   but first-viewport images should still use the framework's normal
   priority/preload mechanism.
-- `steps`: every routable step with `id`, `path`, `filePath`, `componentKey`, `type`, optional `kind`, optional `tags`, and optional `assetIds`. New `path` values must be meaningful public route slugs, not `/step-1` style URLs. Sequential ids are acceptable when the funnel uses them internally.
+- `steps`: every routable step with `id`, `path`, `filePath`, `componentKey`, `type`, optional `kind`, optional `tags`, and optional `assetIds`. This includes experiment variant screens and intentionally inactive screens that should appear as `unused` in builder. New `path` values must be meaningful public route slugs, not `/step-1` style URLs. Sequential ids are acceptable when the funnel uses them internally.
 - `edgesByStepId`: graph edges between steps.
 - `branches`: builder metadata for conditional paths that own one or more steps before reconverging.
-- `experiments`: optional variant routing.
+- `experiments`: optional variant routing. This may be imported from `src/config/experiments.ts` when that file keeps source-readable experiment definitions.
 
 Keep `steps[].id`, `path`, and answer keys stable unless the request is a migration.
 When adding a step, prefer a semantic path like `/motivation`, `/fitness-goal`,
@@ -101,6 +101,13 @@ Experiments attach to a step and route to variant steps:
 }
 ```
 
+Keep every control and variant route target as a real step in
+`funnel.manifest.ts`. The runnable experiment entry may live in
+`src/config/experiments.ts` and be imported into the manifest as
+`experiments: manifestExperiments`; if so, keep the experiment `stepId`, labels,
+and traffic as explicit string/number literals so analytics can parse them.
+Do not hide step ids or labels behind computed variables.
+
 The runtime resolves assignments through the shared analytics/runtime integration outside preview and uses editor overrides inside preview/editor mode. Opening the source step waits for the assignment, then opens the assigned route and keeps the URL in sync. Continue then advances from the assigned route's normal graph edge, with the already-applied experiment ignored for that continuation.
 
 Keep experiment redirects out of step components. Add normal `edgesByStepId` entries for the source/control step and every variant step, then let `goNext()` or the shell Continue button use the shared runtime.
@@ -112,6 +119,10 @@ Keep the control variant stable and do not remove a running variant until analyt
 - Add or update the manifest step.
 - Register the component in `src/runtime/step-registry.ts`.
 - Update `edgesByStepId`, `entryPoints`, `branches`, step `tags`, and `assetIds` if needed.
+- Add every experiment control and variant route target to `steps`.
+- Add normal outgoing `edgesByStepId` entries for every experiment route target.
+- Add each running experiment to `src/config/experiments.ts` or the manifest's inline `experiments` array, matching the local funnel pattern.
+- Keep experiment config synchronized with manifest steps, tags, and edges.
 - Label every branch-owned path with `branches[].name`, answer-derived `label`, useful `tags`, and owned `stepIds`.
 - Keep builder metadata inline/literal so groups, labels, and `unused` badges are visible in builder.
 - Label every running experiment variant with stable tags/labels like `<experiment-id>-control` and `<experiment-id>-variant-b`.