@funnelsgrove/runtime 0.1.44 → 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/posthog-flags.d.ts

@@ -1,5 +1,6 @@
 import type { PostHog } from 'posthog-js';
 export declare const POSTHOG_FEATURE_FLAG_READY_TIMEOUT_MS = 2500;
+export declare const POSTHOG_SCOPED_FLAG_RELOAD_RETRY_MS = 300;
 type BootstrapConfig = {
     apiKey: string;
     apiHost: string;

package/dist/runtime/posthog-flags.js

@@ -3,6 +3,7 @@ import { runtimePublicConfig } from '../services/public-env.js';
 let initialized = false;
 let readyPromise = null;
 export const POSTHOG_FEATURE_FLAG_READY_TIMEOUT_MS = 2500;
+export const POSTHOG_SCOPED_FLAG_RELOAD_RETRY_MS = 300;
 const STORED_PERSON_PROPERTIES_KEY = '$stored_person_properties';
 const buildFlagScopeProperties = (config) => {
     var _a, _b;
@@ -84,7 +85,17 @@ export const bootstrapPostHog = (config) => {
             bootstrap: { distinctID: config.distinctId },
             loaded: () => {
                 let unsubscribe = null;
-                unsubscribe = posthog.onFeatureFlags(() => {
+                let scopedReloadRetried = false;
+                unsubscribe = posthog.onFeatureFlags((flags) => {
+                    if (Object.keys(scopeProperties).length > 0 &&
+                        flags.length === 0 &&
+                        !scopedReloadRetried) {
+                        scopedReloadRetried = true;
+                        setTimeout(() => {
+                            posthog.reloadFeatureFlags();
+                        }, POSTHOG_SCOPED_FLAG_RELOAD_RETRY_MS);
+                        return;
+                    }
                     unsubscribe === null || unsubscribe === void 0 ? void 0 : unsubscribe();
                     markReady();
                 });

package/package.json

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