@funnelsgrove/runtime

Shared funnel runtime contracts and helpers.

Build And Publish

• 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.

Use This Package For

• manifest types and validation
• route resolution and entry-point handling
• 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
• 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

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

What Does Not Belong Here

• 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