@funnelsgrove/runtime 0.1.43 → 0.1.45

package/README.md

@@ -2,60 +2,65 @@
 
 Shared funnel runtime contracts and helpers.
 
-## Build And Publish
+Read this file before editing shared funnel mechanics. Deeper runtime behavior is
+documented in [`docs/product-specs/funnel-template-runtime.md`](../../docs/product-specs/funnel-template-runtime.md).
 
-- Build distributable output with `npm run build --workspace @funnelsgrove/runtime`.
-- Publish from the repo root with `npm publish --workspace @funnelsgrove/runtime --access public`.
-- Local repo installs still resolve this package through npm workspaces when another workspace depends on version `0.1.1`.
-- The build normalizes generated relative ESM imports to explicit `.js` files for published package consumers.
+## Owns funnel mechanics
+
+`@funnelsgrove/runtime` owns the reusable mechanics that every generated or published funnel depends on: manifests, routing, env resolution, funnel state, preview/runtime detection, and generic runtime UI. Funnels bring their own copy, visual design, billing catalog, and step JSX.
 
 ## Use This Package For
 
 - manifest types and validation
 - route resolution and entry-point handling
+- runtime mode and public env/config resolution
 - experiment assignment helpers
 - preview-bridge parsing and preview/runtime detection
 - published theme contract and CSS variable helpers
-- funnel context, base controls, and reusable runtime UI primitives
-- subscription handoff and subscription management screens whose copy stays funnel-local
+- funnel context, flow controller, and generic runtime UI primitives
+- funnel-scoped state/storage helpers
 - browser-safe API client helpers used by funnels
-- a shared test-mode developer info box for funnel-local preview tooling
-
-## Responsibilities
-
-- keep funnel mechanics consistent across every funnel
-- expose stable contracts for routing, previews, and step identity
-- avoid funnel-specific copy, visual design, or billing plan catalogs
-
-## What Belongs Here
-
-- reusable runtime helpers that any funnel can use
-- shared browser/event/storage helpers tied to funnel behavior
-- funnel-scoped paywall state helpers that keep runtime-owned storage keys under `fg_...`
-- hosted-path navigation helpers so static previews keep their `/published/f/...` or `/catalog/...` prefix
-- generic context and base component primitives
-- safe local-only fallbacks when no real SDK publishable key is configured
-- shared preview-checkout publishable key fallback used by paywalls when only the seed placeholder is configured
-- default runtime config values for API/bootstrap wiring
-- env-backed support email rendering for shared subscription management screens
-- full-step subscription management surfaces that avoid exposing an outer page background rim
-- subscription handoff link rendering for iOS, Android, and desktop/web fallbacks from runtime env
-- subscription handoff browser-only values are resolved after mount so published success routes hydrate without text mismatches
-- public subscription summaries with provider plan and period metadata for funnel-local management screens
-- a bottom-right `RuntimeDevInfoBox` that funnels can mount in test mode to inspect public runtime config with one canonical env/config name per row, copy the current funnel user id/email, switch to live mode, and clear funnel-scoped paywall state
+- subscription handoff and subscription management screens whose copy stays funnel-local
+- test-mode developer info surfaces for funnel preview tooling
+
+## Do Not Use This Package For
+
+- funnel-specific step JSX
+- brand/theme assets
+- billing catalog data
+- analytics transport
+- Stripe checkout UI
+- funnel-specific developer widget copy
+- direct provider SDK calls
+
+## Public Surfaces
+
+- `config/*`: manifest, theme, font, env, and builder-preview contracts.
+- `runtime/*`: flow, routing, attribution, feature flags, preview bridge, URL attributes, and manifest validation.
+- `services/*`: API client, runtime mode, public env, project env, logger, and funnel state helpers.
+- `components/*`: generic runtime context, subscription handoff/management, editor panel, dev info, and base controls.
+- `content/*` and `steps/types`: shared step content and taxonomy contracts.
 
 ## Storage Conventions
 
 - runtime user ids stay funnel-scoped under `funnel:<funnelId>:user-id`
 - runtime-generated user ids use the `u_` prefix
 - paywall state is stored through runtime helpers under `fg_state:<funnelId>`
-- developer reset controls should clear paywall state through `clearPaywallStateValue`, including any funnel-provided legacy keys
+- developer reset controls should clear paywall state through `clearPaywallStateValue`, including funnel-provided compatibility keys when a live funnel still needs them
 
-## What Does Not Belong Here
+## Engineering Rules
 
-- funnel-specific step JSX
-- brand/theme assets
-- billing catalog data
-- analytics SDK transport
-- Stripe checkout UI
-- funnel-specific developer widget copy, config extras, or legacy storage keys
+- Do not import `@funnelsgrove/payments` or `@funnelsgrove/analytics` here for checkout or transport orchestration.
+- Runtime UI must be generic and copy-injectable.
+- Browser-only values must resolve after mount when SSR hydration can be affected.
+- Keep env mapping centralized in `config/env.config.ts`.
+
+## Build, Test, Publish
+
+```bash
+npm run test:run --workspace @funnelsgrove/runtime
+npm run build --workspace @funnelsgrove/runtime
+npm publish --workspace @funnelsgrove/runtime --access public
+```
+
+The build normalizes generated relative ESM imports to explicit `.js` files for published package consumers.

package/dist/index.js

@@ -1,10 +1,13 @@
+// Shared config contracts.
 export * from './config/builder-preview.protocol.js';
 export * from './config/env.config.js';
 export * from './config/funnel.manifest.types.js';
 export * from './config/funnel.experiments.types.js';
 export * from './config/funnel-theme.js';
 export * from './config/font-config.js';
+// Structured content contracts.
 export * from './content/step-content.js';
+// Runtime mechanics.
 export * from './runtime/experiment-assignment.js';
 export * from './runtime/browser-helpers.js';
 export * from './runtime/funnel-flow.js';
@@ -20,6 +23,7 @@ export * from './runtime/route-resolver.js';
 export * from './runtime/subscription-handoff.js';
 export * from './runtime/url-user-attributes.js';
 export * from './runtime/use-url-user-attributes-sync.js';
+// Browser-safe services.
 export * from './services/api.service.js';
 export * from './services/funnel-state.service.js';
 export * from './services/logger.js';
@@ -28,6 +32,7 @@ export * from './services/project-env.js';
 export * from './services/public-env.js';
 export * from './services/runtime-api.config.js';
 export * from './services/runtime-mode.service.js';
+// SDK and generic runtime UI.
 export * from './sdk/userAnswers.js';
 export * from './components/FunnelContext.js';
 export * from './components/FunnelEditorPanel.js';

package/dist/runtime/use-funnel-flow-controller.js

@@ -11,7 +11,7 @@ import { resolveExperimentAssignment } from './experiment-assignment.js';
 import { collectCurrentFunnelAttribution } from './funnel-attribution.js';
 import { resolveUrlUserAttributes } from './url-user-attributes.js';
 import { bootstrapPostHog, identifyPostHog, isPostHogReady, resolveExperimentVariant, } from './posthog-flags.js';
-import { isEditorEnabled, useRuntimeMode } from '../services/runtime-mode.service.js';
+import { getRuntimeMode, isEditorEnabled, useRuntimeMode } from '../services/runtime-mode.service.js';
 import { isPreviewFrameRuntime } from '../services/preview-frame.service.js';
 const FIRST_STEP_ENGAGEMENT_THRESHOLD_MS = 1000;
 export function computeRenderSuspended(input) {
@@ -325,9 +325,10 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         const startedAt = stepStartedAtByIdRef.current[meta.id] || record.completedAt;
         dispatchWindowCustomEvent('funnel:step-completed', record);
         if (!isPreviewRuntime) {
+            const analyticsRuntimeMode = getRuntimeMode();
             (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackStepCompleted) === null || _a === void 0 ? void 0 : _a.call(analytics, {
                 userId: currentUserIdRef.current,
-                environment: runtimeMode,
+                environment: analyticsRuntimeMode,
                 stepId: record.stepId,
                 stepName: record.stepName,
                 stepType,
@@ -358,7 +359,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             }
             return updatedUser;
         });
-    }, [analytics, isPreviewRuntime, runtimeMode, stepById]);
+    }, [analytics, isPreviewRuntime, stepById]);
     const completeStep = useCallback((stepId, choices) => {
         recordStepCompletion(stepId, choices);
     }, [recordStepCompletion]);
@@ -383,10 +384,11 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         const stepName = (renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.name) || (renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.title) || renderedStepId;
         const stepType = renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.type;
         stepStartedAtByIdRef.current[renderedStepId] = startedAt;
+        const analyticsRuntimeMode = getRuntimeMode();
         if (!isPreviewRuntime) {
             (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackStepStarted) === null || _a === void 0 ? void 0 : _a.call(analytics, {
                 userId: currentUserIdRef.current,
-                environment: runtimeMode,
+                environment: analyticsRuntimeMode,
                 stepId: renderedStepId,
                 stepName,
                 stepType,
@@ -397,7 +399,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
                 firstStepViewedTrackedRef.current = true;
                 (_b = analytics === null || analytics === void 0 ? void 0 : analytics.trackFunnelStarted) === null || _b === void 0 ? void 0 : _b.call(analytics, {
                     userId: currentUserIdRef.current,
-                    environment: runtimeMode,
+                    environment: analyticsRuntimeMode,
                     stepId: renderedStepId,
                     stepName,
                     stepType,
@@ -406,7 +408,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
                 });
                 (_c = analytics === null || analytics === void 0 ? void 0 : analytics.trackFirstStepViewed) === null || _c === void 0 ? void 0 : _c.call(analytics, {
                     userId: currentUserIdRef.current,
-                    environment: runtimeMode,
+                    environment: analyticsRuntimeMode,
                     stepId: renderedStepId,
                     stepName,
                     stepType,
@@ -435,7 +437,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             const engagedAt = new Date().toISOString();
             (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackStepEngaged) === null || _a === void 0 ? void 0 : _a.call(analytics, {
                 userId: currentUserIdRef.current,
-                environment: runtimeMode,
+                environment: analyticsRuntimeMode,
                 stepId: engagedStepId,
                 stepName: engagedStepName,
                 stepType: engagedStepType,
@@ -458,7 +460,6 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.name,
         renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.title,
         renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.type,
-        runtimeMode,
         safeActiveStepId,
     ]);
     useEffect(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/runtime",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "type": "module",
   "private": false,
   "main": "./dist/index.js",