@funnelsgrove/runtime

Shared funnel runtime contracts and helpers.

Read this file before editing shared funnel mechanics. Deeper runtime behavior is documented in docs/product-specs/funnel-template-runtime.md.

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, flow controller, and generic runtime UI primitives
• funnel-scoped state/storage helpers
• browser-safe API client helpers used by funnels
• reactive browser query-string access through useBrowserLocationSearch
• 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.
• runtime/published-runtime-resolution: running-experiment normalization and immutable offer-set selection from pricing assignments.
• 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 funnel-provided compatibility keys when a live funnel still needs them

Engineering Rules

• 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.
• Funnel code must not copy useSyncExternalStore/popstate query-string hooks. Use useBrowserLocationSearch; the shared controller also notifies it after history.pushState and history.replaceState navigation.
• Keep env mapping centralized in config/env.config.ts.

Build, Test, Publish

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.