@funnelsgrove/runtime 0.1.56 → 0.1.59

package/dist/components/FunnelContext.d.ts

@@ -1,5 +1,6 @@
 import type { FunnelStepId } from '../runtime/funnel-runtime.js';
 import type { FunnelUserAnswers } from '../sdk/userAnswers.js';
+import type { FunnelNavigationOutcome } from '../runtime/funnel-step-lifecycle.js';
 /** A single record of a completed step, stored in the user's history. */
 export type StepCompletionRecord = {
     stepId: string;
@@ -20,7 +21,7 @@ export type FunnelContextValue = {
     activeStepId: FunnelStepId;
     featureFlags: Record<string, string>;
     isBuilder: boolean;
-    goToStep: (stepId: string) => void;
+    goToStep: (stepId: string, outcome: FunnelNavigationOutcome) => void;
     goNext: () => void;
     goChoice: (choice: 'yes' | 'no', stepId?: string) => void;
     getChoiceTargets: (stepId?: string) => {
@@ -35,8 +36,11 @@ export type FunnelContextValue = {
     user: FunnelUser;
     userBootstrapped: boolean;
     setUser: (user: FunnelUser) => void;
+    submitEmailCapture: (email: string) => Promise<void>;
     /** Manually record a step as completed (used by custom step components). */
     completeStep: (stepId: string, choices?: Record<string, unknown>) => void;
+    /** Complete the active terminal step and emit the canonical funnel conversion once. */
+    completeFunnel: (stepId: string) => void;
 };
 type FunnelProviderProps = {
     value: FunnelContextValue;

package/dist/components/FunnelContext.js

@@ -1,9 +1,10 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext } from 'react';
+import { FunnelChoiceCommitProvider } from '../runtime/use-step-choices.js';
 const FunnelContext = createContext(null);
 export function FunnelProvider({ value, children }) {
-    return _jsx(FunnelContext.Provider, { value: value, children: children });
+    return (_jsx(FunnelChoiceCommitProvider, { carrier: value, children: _jsx(FunnelContext.Provider, { value: value, children: children }) }));
 }
 export function useFunnel() {
     const context = useContext(FunnelContext);

package/dist/components/ManageSubscriptionScreen.js

@@ -152,7 +152,10 @@ export function ManageSubscriptionScreen({ stepId, content, homeStepId, nodeId,
                                         ? content.confirmStage.cancellingLabel
                                         : content.confirmStage.cancelLabel }), _jsx("button", { type: 'button', className: 'manage-subscription-secondary', onClick: () => setStage('why'), children: content.confirmStage.backLabel })] })) : null, stage === 'done' ? (_jsxs(_Fragment, { children: [_jsx("h1", { className: 'manage-subscription-title', children: content.doneStage.title }), _jsx("p", { className: 'manage-subscription-confirm-copy', children: cancelCompleted
                                         ? content.doneStage.cancelledMessage
-                                        : content.doneStage.emptyMessage }), _jsxs("p", { className: 'manage-subscription-support', children: [content.subscriptionsStage.supportPrefix, ' ', _jsx("a", { href: supportLinkHref, children: supportLinkLabel })] }), _jsx("button", { type: 'button', className: 'manage-subscription-primary', onClick: () => goToStep(homeStepId), children: content.doneStage.returnHomeLabel })] })) : null] }) }), _jsx("style", { children: manageSubscriptionScreenStyles })] }));
+                                        : content.doneStage.emptyMessage }), _jsxs("p", { className: 'manage-subscription-support', children: [content.subscriptionsStage.supportPrefix, ' ', _jsx("a", { href: supportLinkHref, children: supportLinkLabel })] }), _jsx("button", { type: 'button', className: 'manage-subscription-primary', onClick: () => goToStep(homeStepId, {
+                                        type: 'exit',
+                                        reason: cancelCompleted ? 'cancel' : 'back',
+                                    }), children: content.doneStage.returnHomeLabel })] })) : null] }) }), _jsx("style", { children: manageSubscriptionScreenStyles })] }));
 }
 const manageSubscriptionScreenStyles = `
 .manage-subscription-step {

package/dist/components/SubscriptionHandoffScreen.d.ts

@@ -23,9 +23,10 @@ export type SubscriptionHandoffContent = {
 };
 type SubscriptionHandoffScreenProps = {
     stepId: string;
+    completionMode?: 'step' | 'funnel';
     content: SubscriptionHandoffContent;
     confirmationUrl?: string | null;
     nodeId?: string;
 };
-export declare function SubscriptionHandoffScreen({ stepId, content, confirmationUrl, nodeId, }: SubscriptionHandoffScreenProps): import("react/jsx-runtime").JSX.Element;
+export declare function SubscriptionHandoffScreen({ stepId, completionMode, content, confirmationUrl, nodeId, }: SubscriptionHandoffScreenProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/SubscriptionHandoffScreen.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useEffect, useMemo, useState, useSyncExternalStore } from 'react';
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react';
 import { getFunnelUserAttribution } from '../runtime/funnel-attribution.js';
 import { resolveSubscriptionHandoff } from '../runtime/subscription-handoff.js';
 import { runtimePublicConfig } from '../services/public-env.js';
@@ -43,8 +43,9 @@ const renderStoreIcon = (variant) => {
     }
     return _jsx(WebLinkIcon, {});
 };
-export function SubscriptionHandoffScreen({ stepId, content, confirmationUrl, nodeId, }) {
-    const { isBuilder, user, userBootstrapped } = useFunnel();
+export function SubscriptionHandoffScreen({ stepId, completionMode = 'step', content, confirmationUrl, nodeId, }) {
+    const { completeFunnel, completeStep, isBuilder, user, userBootstrapped } = useFunnel();
+    const completeHandoff = useCallback(() => completionMode === 'funnel' ? completeFunnel(stepId) : completeStep(stepId), [completeFunnel, completeStep, completionMode, stepId]);
     const [autoOpenAttempted, setAutoOpenAttempted] = useState(false);
     const [emailSent, setEmailSent] = useState(false);
     const browserSnapshotKey = useSyncExternalStore(subscribeToBrowserSnapshot, () => [
@@ -173,18 +174,22 @@ export function SubscriptionHandoffScreen({ stepId, content, confirmationUrl, no
             return;
         }
         window.sessionStorage.setItem(attemptKey, '1');
+        completeHandoff();
         window.location.assign(openAppUrl);
         const statusTimer = window.setTimeout(() => {
             setAutoOpenAttempted(true);
         }, 0);
         return () => window.clearTimeout(statusTimer);
-    }, [handoff.openAppUrl, handoff.platform, handoffReady, stepId, user.id]);
+    }, [completeHandoff, handoff.openAppUrl, handoff.platform, handoffReady, stepId, user.id]);
     return (_jsxs(_Fragment, { children: [_jsxs("div", { className: 'subscription-handoff-step', "data-node-id": nodeId || stepId, children: [_jsxs("header", { className: 'subscription-handoff-head', children: [_jsx("p", { className: 'subscription-handoff-kicker', children: content.kicker }), _jsx("h2", { className: 'subscription-handoff-title', children: content.title })] }), installLinks.length > 0 ? (_jsx("div", { className: 'subscription-handoff-store-links', children: installLinks.map((link) => {
                             const label = `${link.eyebrow} ${link.title}`;
                             const className = `subscription-handoff-store-badge is-${link.variant}${link.disabled ? ' is-disabled' : ''}`;
                             const body = (_jsxs(_Fragment, { children: [renderStoreIcon(link.variant), _jsxs("span", { className: 'subscription-handoff-store-copy', children: [_jsx("span", { className: 'subscription-handoff-store-eyebrow', children: link.eyebrow }), _jsx("span", { className: 'subscription-handoff-store-title', children: link.title })] })] }));
-                            return link.href ? (_jsx("a", { href: link.href, target: '_blank', rel: 'noopener noreferrer', "aria-label": label, className: className, children: body }, link.id)) : (_jsx("span", { role: 'link', "aria-label": label, "aria-disabled": 'true', "aria-busy": 'true', className: className, children: body }, link.id));
-                        }) })) : null, _jsx("p", { className: 'subscription-handoff-copy', children: qrCodeImageUrl ? content.copyWithQr : content.copyWithoutQr }), qrCodeImageUrl && handoff.qrConfirmationUrl ? (_jsx("a", { href: handoff.qrConfirmationUrl, className: 'subscription-handoff-qr-card', target: '_blank', rel: 'noopener noreferrer', "aria-label": content.qrOpenLabel, children: _jsx("span", { "aria-hidden": 'true', className: 'subscription-handoff-qr-image', style: { backgroundImage: `url(${qrCodeImageUrl})` } }) })) : null, _jsx("p", { className: 'subscription-handoff-note', children: content.note }), shouldShowOpenAppButton && handoff.openAppUrl ? (_jsx("a", { href: handoff.openAppUrl, className: 'subscription-handoff-open-app', children: content.openAppLabel })) : null, shouldShowOpenAppButton && !handoff.openAppUrl ? (_jsx("span", { role: 'link', "aria-disabled": 'true', "aria-busy": 'true', className: 'subscription-handoff-open-app is-disabled', children: content.openAppLabel })) : null, emailHref ? (_jsx("a", { href: emailHref, className: 'subscription-handoff-email-button', onClick: () => setEmailSent(true), children: content.emailButtonLabel })) : (_jsx("span", { role: 'link', "aria-disabled": 'true', "aria-busy": 'true', className: 'subscription-handoff-email-button is-disabled', children: content.emailButtonLabel })), emailSent ? (_jsx("p", { className: 'subscription-handoff-status', children: content.emailSentStatus })) : null, autoOpenAttempted ? (_jsx("p", { className: 'subscription-handoff-status', children: content.autoOpenStatus })) : null] }), _jsx("style", { children: subscriptionHandoffScreenStyles })] }));
+                            return link.href ? (_jsx("a", { href: link.href, target: '_blank', rel: 'noopener noreferrer', "aria-label": label, className: className, onClick: completeHandoff, children: body }, link.id)) : (_jsx("span", { role: 'link', "aria-label": label, "aria-disabled": 'true', "aria-busy": 'true', className: className, children: body }, link.id));
+                        }) })) : null, _jsx("p", { className: 'subscription-handoff-copy', children: qrCodeImageUrl ? content.copyWithQr : content.copyWithoutQr }), qrCodeImageUrl && handoff.qrConfirmationUrl ? (_jsx("a", { href: handoff.qrConfirmationUrl, className: 'subscription-handoff-qr-card', target: '_blank', rel: 'noopener noreferrer', "aria-label": content.qrOpenLabel, onClick: completeHandoff, children: _jsx("span", { "aria-hidden": 'true', className: 'subscription-handoff-qr-image', style: { backgroundImage: `url(${qrCodeImageUrl})` } }) })) : null, _jsx("p", { className: 'subscription-handoff-note', children: content.note }), shouldShowOpenAppButton && handoff.openAppUrl ? (_jsx("a", { href: handoff.openAppUrl, className: 'subscription-handoff-open-app', onClick: completeHandoff, children: content.openAppLabel })) : null, shouldShowOpenAppButton && !handoff.openAppUrl ? (_jsx("span", { role: 'link', "aria-disabled": 'true', "aria-busy": 'true', className: 'subscription-handoff-open-app is-disabled', children: content.openAppLabel })) : null, emailHref ? (_jsx("a", { href: emailHref, className: 'subscription-handoff-email-button', onClick: () => {
+                            completeHandoff();
+                            setEmailSent(true);
+                        }, children: content.emailButtonLabel })) : (_jsx("span", { role: 'link', "aria-disabled": 'true', "aria-busy": 'true', className: 'subscription-handoff-email-button is-disabled', children: content.emailButtonLabel })), emailSent ? (_jsx("p", { className: 'subscription-handoff-status', children: content.emailSentStatus })) : null, autoOpenAttempted ? (_jsx("p", { className: 'subscription-handoff-status', children: content.autoOpenStatus })) : null] }), _jsx("style", { children: subscriptionHandoffScreenStyles })] }));
 }
 const subscriptionHandoffScreenStyles = `
 .subscription-handoff-step {

package/dist/config/funnel.manifest.types.d.ts

@@ -1,4 +1,4 @@
-import type { FunnelStepKind, FunnelStepType } from '../steps/types.js';
+import type { FunnelChoiceDescriptor, FunnelStepKind, FunnelStepType } from '../steps/step-contract.js';
 export type TemplateArchitectureVersion = number;
 export type FunnelBreakpointName = 'small' | 'medium' | 'large' | 'desktop-small';
 export type FunnelManifestBreakpoint = {
@@ -31,7 +31,8 @@ export type FunnelManifestStep = {
     componentKey: string;
     type: FunnelStepType;
     kind?: FunnelStepKind;
-    name?: string;
+    name: string;
+    choice?: FunnelChoiceDescriptor;
     title: string;
     tags?: readonly string[];
     assetIds?: readonly string[];
@@ -75,6 +76,7 @@ export type FunnelManifestExperiment = {
 };
 export type FunnelManifest = {
     templateArchitectureVersion: TemplateArchitectureVersion;
+    stepContractVersion: number;
     meta: {
         title: string;
         description: string;

package/dist/generated/step-contract-hash.d.ts

@@ -0,0 +1 @@
+export declare const CURRENT_STEP_CONTRACT_HASH: "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf";

package/dist/generated/step-contract-hash.js

@@ -0,0 +1,2 @@
+// Generated by scripts/generate-funnel-step-contract-artifacts.mjs. DO NOT EDIT.
+export const CURRENT_STEP_CONTRACT_HASH = 'd761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf';

package/dist/index.d.ts

@@ -5,18 +5,26 @@ export * from './config/funnel.experiments.types.js';
 export * from './config/funnel-theme.js';
 export * from './config/font-config.js';
 export * from './content/step-content.js';
+export * from './generated/step-contract-hash.js';
+export * from './migrations/step-contract-v2.js';
+export * from './migrations/step-contract-v3.js';
 export * from './runtime/experiment-assignment.js';
 export * from './runtime/browser-helpers.js';
 export * from './runtime/funnel-flow.js';
 export * from './runtime/funnel-attribution.js';
 export * from './runtime/funnel-manifest.validation.js';
+export * from './runtime/funnel-step-metadata.validation.js';
 export * from './runtime/funnel-runtime.js';
+export type { FunnelNavigationOutcome, FunnelStepExitReason, } from './runtime/funnel-step-lifecycle.js';
 export * from './runtime/posthog-flags.js';
 export * from './runtime/use-funnel-flow-controller.js';
+export { useStepChoices } from './runtime/use-step-choices.js';
+export type { FunnelStepChoices } from './runtime/use-step-choices.js';
 export * from './runtime/preview-bridge.js';
 export * from './runtime/preview-definition-overrides.js';
 export * from './runtime/offer-set-runtime.js';
 export * from './runtime/route-resolver.js';
+export * from './runtime/submit-email-capture.js';
 export * from './runtime/subscription-handoff.js';
 export * from './runtime/url-user-attributes.js';
 export * from './runtime/use-url-user-attributes-sync.js';
@@ -36,4 +44,8 @@ export * from './components/ManageSubscriptionScreen.js';
 export * from './components/RuntimeDevInfoBox.js';
 export * from './components/SubscriptionHandoffScreen.js';
 export * from './components/shared/PrimaryButton.js';
+export * from './steps/choice-contract.js';
+export * from './steps/step-contract.js';
 export * from './steps/types.js';
+export * from './validation/funnel-contract-diagnostics.js';
+export * from './validation/funnel-contract-validator.js';

package/dist/index.js

@@ -8,18 +8,24 @@ export * from './config/font-config.js';
 // Structured content contracts.
 export * from './content/step-content.js';
 // Runtime mechanics.
+export * from './generated/step-contract-hash.js';
+export * from './migrations/step-contract-v2.js';
+export * from './migrations/step-contract-v3.js';
 export * from './runtime/experiment-assignment.js';
 export * from './runtime/browser-helpers.js';
 export * from './runtime/funnel-flow.js';
 export * from './runtime/funnel-attribution.js';
 export * from './runtime/funnel-manifest.validation.js';
+export * from './runtime/funnel-step-metadata.validation.js';
 export * from './runtime/funnel-runtime.js';
 export * from './runtime/posthog-flags.js';
 export * from './runtime/use-funnel-flow-controller.js';
+export { useStepChoices } from './runtime/use-step-choices.js';
 export * from './runtime/preview-bridge.js';
 export * from './runtime/preview-definition-overrides.js';
 export * from './runtime/offer-set-runtime.js';
 export * from './runtime/route-resolver.js';
+export * from './runtime/submit-email-capture.js';
 export * from './runtime/subscription-handoff.js';
 export * from './runtime/url-user-attributes.js';
 export * from './runtime/use-url-user-attributes-sync.js';
@@ -41,4 +47,8 @@ export * from './components/ManageSubscriptionScreen.js';
 export * from './components/RuntimeDevInfoBox.js';
 export * from './components/SubscriptionHandoffScreen.js';
 export * from './components/shared/PrimaryButton.js';
+export * from './steps/choice-contract.js';
+export * from './steps/step-contract.js';
 export * from './steps/types.js';
+export * from './validation/funnel-contract-diagnostics.js';
+export * from './validation/funnel-contract-validator.js';

package/dist/migrations/step-contract-v2.d.ts

@@ -0,0 +1,50 @@
+import { type FunnelContractDiagnostic } from '../validation/funnel-contract-diagnostics.js';
+export type StepContractV2MigrationSourceKind = 'manifest' | 'component';
+export type StepContractV2MigrationField = 'id' | 'name' | 'type' | 'kind' | 'choice';
+export type StepContractV2MigrationRule = 'remove-default-kind' | 'add-name-from-id' | 'restore-reserved-step' | 'sync-manifest-from-component' | 'sync-component-from-manifest';
+export type StepContractV2NormalizedMetadata = Readonly<{
+    id: unknown;
+    name: unknown;
+    type: unknown;
+    kind: unknown;
+    choice: unknown;
+}>;
+export type StepContractV2UniqueMetadataSource = {
+    status: 'unique';
+    sourceId: string;
+    file: string;
+    metadata: StepContractV2NormalizedMetadata;
+};
+export type StepContractV2AmbiguousMetadataSource = {
+    status: 'computed' | 'spread' | 'dynamic' | 'multiple' | 'missing';
+    sourceId: string;
+    file: string;
+};
+export type StepContractV2MetadataSource = StepContractV2UniqueMetadataSource | StepContractV2AmbiguousMetadataSource;
+export type StepContractV2MigrationStepInput = {
+    stepKey: string;
+    manifest: StepContractV2MetadataSource;
+    component: StepContractV2MetadataSource;
+    optionIds: 'stable' | 'ambiguous' | 'not-applicable';
+};
+export type StepContractV2MigrationInput = {
+    steps: readonly StepContractV2MigrationStepInput[];
+};
+export type StepContractV2MigrationOperation = {
+    source: StepContractV2MigrationSourceKind;
+    sourceId: string;
+    stepKey: string;
+    stepId: string | null;
+    field: StepContractV2MigrationField;
+    action: 'set' | 'remove';
+    before: unknown;
+    after: unknown;
+    rule: StepContractV2MigrationRule;
+};
+export type StepContractV2MigrationPlan = {
+    operations: readonly StepContractV2MigrationOperation[];
+    protectedChanges: readonly StepContractV2MigrationOperation[];
+    diagnostics: readonly FunnelContractDiagnostic[];
+    valid: boolean;
+};
+export declare const planStepContractV2Migration: (input: StepContractV2MigrationInput) => StepContractV2MigrationPlan;

package/dist/migrations/step-contract-v2.js

@@ -0,0 +1,310 @@
+import { resolveReservedStepContract, } from '../steps/step-contract.js';
+import { FUNNEL_CHOICE_STEP_TYPES } from '../steps/choice-contract.js';
+import { createFunnelContractDiagnostic, } from '../validation/funnel-contract-diagnostics.js';
+import { validateFunnelManifestContract } from '../validation/funnel-contract-validator.js';
+const METADATA_FIELDS = ['id', 'name', 'type', 'kind', 'choice'];
+const PROTECTED_FIELDS = new Set([
+    'id',
+    'name',
+    'type',
+    'kind',
+]);
+const KEBAB_CASE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const AUTHORING_GUIDE = 'docs/product-specs/funnel-template-step-authoring.md';
+const CHOICE_STEP_TYPE_SET = new Set(FUNNEL_CHOICE_STEP_TYPES);
+const SAFE_RESERVED_CONTRACTS = [
+    'paywall',
+    'subscription-started',
+    'manage-subscription',
+].map((identity) => resolveReservedStepContract(2, identity)).filter((contract) => (contract === null || contract === void 0 ? void 0 : contract.match) === 'exact');
+const copyMetadata = (metadata) => ({
+    id: metadata.id,
+    name: metadata.name,
+    type: metadata.type,
+    kind: metadata.kind,
+    choice: metadata.choice,
+});
+const createPlannedSource = (source, input) => {
+    const before = copyMetadata(input.metadata);
+    return {
+        source,
+        input,
+        before,
+        after: Object.assign({}, before),
+        ruleByField: {},
+    };
+};
+const setPlannedField = (planned, field, value, rule) => {
+    if (planned.after[field] === value) {
+        return;
+    }
+    planned.after[field] = value;
+    planned.ruleByField[field] = rule;
+};
+const choicesMatch = (left, right) => {
+    if (left === undefined || right === undefined) {
+        return left === right;
+    }
+    if (typeof left !== 'object'
+        || left === null
+        || Array.isArray(left)
+        || typeof right !== 'object'
+        || right === null
+        || Array.isArray(right)) {
+        return false;
+    }
+    const leftChoice = left;
+    const rightChoice = right;
+    return leftChoice.answerKey === rightChoice.answerKey
+        && leftChoice.allowEmpty === rightChoice.allowEmpty
+        && Object.keys(leftChoice).length === Object.keys(rightChoice).length;
+};
+const metadataMatches = (left, right) => {
+    return left.id === right.id
+        && left.name === right.name
+        && left.type === right.type
+        && left.kind === right.kind
+        && choicesMatch(left.choice, right.choice);
+};
+const inspectMetadata = (metadata) => {
+    const id = typeof metadata.id === 'string' ? metadata.id : 'migration-candidate';
+    const diagnostics = validateFunnelManifestContract({
+        stepContractVersion: 2,
+        templateArchitectureVersion: 1,
+        steps: [{
+                id: metadata.id,
+                name: metadata.name,
+                type: metadata.type,
+                kind: metadata.kind,
+                choice: metadata.choice,
+                path: `/${id}`,
+                filePath: 'src/steps/migration-candidate.tsx',
+                componentKey: 'migrationCandidate',
+                title: 'Migration candidate',
+            }],
+        entryPoints: [],
+        edgesByStepId: {},
+        branches: [],
+        experiments: [],
+    }, { mode: 'legacy-read' }).filter((diagnostic) => diagnostic.code !== 'FG-RESERVED-002');
+    const choiceValid = diagnostics.every((diagnostic) => diagnostic.code !== 'FG-CHOICE-001');
+    const issue = diagnostics.find((diagnostic) => diagnostic.code !== 'FG-CHOICE-001');
+    return {
+        valid: diagnostics.length === 0,
+        choiceValid,
+        issue: issue ? {
+            code: issue.code,
+            expected: issue.expected,
+            received: issue.received,
+            reason: issue.reason,
+            repair: issue.repair,
+        } : null,
+    };
+};
+const applyMechanicalRules = (manifest, component) => {
+    const sharedId = manifest.after.id;
+    if (typeof sharedId === 'string'
+        && sharedId === component.after.id
+        && KEBAB_CASE_PATTERN.test(sharedId)) {
+        for (const source of [manifest, component]) {
+            if (source.after.name === undefined) {
+                setPlannedField(source, 'name', sharedId, 'add-name-from-id');
+            }
+        }
+    }
+    for (const source of [manifest, component]) {
+        const reserved = SAFE_RESERVED_CONTRACTS.find((candidate) => {
+            return source.after.id === candidate.id && source.after.name === candidate.name;
+        });
+        if (reserved) {
+            setPlannedField(source, 'type', reserved.type, 'restore-reserved-step');
+            setPlannedField(source, 'kind', reserved.kind, 'restore-reserved-step');
+        }
+        else if (source.after.kind === 'default') {
+            setPlannedField(source, 'kind', undefined, 'remove-default-kind');
+        }
+    }
+};
+const applyParityRule = (manifest, component) => {
+    if (metadataMatches(manifest.after, component.after)) {
+        return;
+    }
+    const manifestValid = inspectMetadata(manifest.after).valid;
+    const componentValid = inspectMetadata(component.after).valid;
+    if (manifestValid === componentValid
+        || manifest.after.id !== component.after.id
+        || manifest.after.name !== component.after.name) {
+        return;
+    }
+    const source = manifestValid ? manifest : component;
+    const target = manifestValid ? component : manifest;
+    const rule = manifestValid
+        ? 'sync-component-from-manifest'
+        : 'sync-manifest-from-component';
+    for (const field of ['type', 'kind']) {
+        if (target.after[field] !== source.after[field]) {
+            setPlannedField(target, field, source.after[field], rule);
+        }
+    }
+};
+const buildOperations = (stepKey, plannedSources) => {
+    const operations = [];
+    for (const planned of plannedSources) {
+        for (const field of METADATA_FIELDS) {
+            const rule = planned.ruleByField[field];
+            if (!rule || planned.before[field] === planned.after[field]) {
+                continue;
+            }
+            operations.push({
+                source: planned.source,
+                sourceId: planned.input.sourceId,
+                stepKey,
+                stepId: typeof planned.after.id === 'string' ? planned.after.id : null,
+                field,
+                action: planned.after[field] === undefined ? 'remove' : 'set',
+                before: planned.before[field],
+                after: planned.after[field],
+                rule,
+            });
+        }
+    }
+    return operations;
+};
+const createMigrationDiagnostic = (details, file, stepId) => {
+    return createFunnelContractDiagnostic(Object.assign(Object.assign({}, details), { file,
+        stepId, guide: AUTHORING_GUIDE }));
+};
+const createSourceDiagnostic = (source, input) => {
+    return createMigrationDiagnostic({
+        code: 'FG-CANDIDATE-001',
+        expected: 'one static object-literal metadata match',
+        received: { source, status: input.status },
+        reason: `The ${source} metadata source cannot be located without evaluating or guessing source code.`,
+        repair: 'Replace computed, spread, dynamic, missing, or duplicate metadata with one static object literal.',
+    }, input.file, null);
+};
+const finalStepId = (manifest, component) => {
+    if (typeof manifest.after.id === 'string') {
+        return manifest.after.id;
+    }
+    return typeof component.after.id === 'string' ? component.after.id : null;
+};
+const createChoiceDiagnostic = (manifest, component) => {
+    return createMigrationDiagnostic({
+        code: 'FG-CHOICE-001',
+        expected: 'one unchanged valid choice descriptor on both metadata sides',
+        received: {
+            manifest: manifest.after.choice,
+            component: component.after.choice,
+        },
+        reason: 'Choice answer-key metadata cannot be inferred or synchronized mechanically.',
+        repair: 'Declare and preserve the stable answerKey explicitly on both metadata sides.',
+    }, manifest.input.file, finalStepId(manifest, component));
+};
+const createOptionDiagnostic = (manifest, component, expected, received) => {
+    return createMigrationDiagnostic({
+        code: 'FG-CHOICE-002',
+        expected,
+        received,
+        reason: 'Choice option identities or presentation shapes require an explicit decision.',
+        repair: 'Preserve stable option ids and resolve the option shape before migrating.',
+    }, manifest.input.file, finalStepId(manifest, component));
+};
+const optionEvidenceDiagnostic = (step, manifest, component) => {
+    const evidence = step.optionIds;
+    const allowedEvidence = ['stable', 'ambiguous', 'not-applicable'];
+    if (!allowedEvidence.some((value) => value === evidence)) {
+        return createOptionDiagnostic(manifest, component, allowedEvidence, evidence === undefined ? 'missing' : evidence);
+    }
+    const requiresStableOptions = [manifest.after.type, component.after.type].some((type) => typeof type === 'string' && CHOICE_STEP_TYPE_SET.has(type));
+    if (requiresStableOptions && evidence !== 'stable') {
+        return createOptionDiagnostic(manifest, component, 'stable', evidence);
+    }
+    if (evidence === 'ambiguous') {
+        return createOptionDiagnostic(manifest, component, ['stable', 'not-applicable'], evidence);
+    }
+    return null;
+};
+const createParityDiagnostics = (manifest, component) => {
+    const diagnostics = [];
+    for (const field of ['id', 'name', 'type', 'kind']) {
+        if (manifest.after[field] === component.after[field]) {
+            continue;
+        }
+        diagnostics.push(createMigrationDiagnostic({
+            code: 'FG-PARITY-001',
+            expected: manifest.after[field],
+            received: component.after[field],
+            reason: `Component metadata ${field} does not match the manifest step.`,
+            repair: `Resolve the protected ${field} explicitly before migrating.`,
+        }, component.input.file, finalStepId(manifest, component)));
+    }
+    return diagnostics;
+};
+const collectSemanticDiagnostics = (step, manifest, component) => {
+    var _a, _b, _c;
+    const diagnostics = [];
+    const inspectionBySource = new Map([
+        [manifest, inspectMetadata(manifest.after)],
+        [component, inspectMetadata(component.after)],
+    ]);
+    if (!((_a = inspectionBySource.get(manifest)) === null || _a === void 0 ? void 0 : _a.choiceValid)
+        || !((_b = inspectionBySource.get(component)) === null || _b === void 0 ? void 0 : _b.choiceValid)
+        || !choicesMatch(manifest.after.choice, component.after.choice)) {
+        diagnostics.push(createChoiceDiagnostic(manifest, component));
+    }
+    const optionDiagnostic = optionEvidenceDiagnostic(step, manifest, component);
+    if (optionDiagnostic) {
+        diagnostics.push(optionDiagnostic);
+    }
+    diagnostics.push(...createParityDiagnostics(manifest, component));
+    const metadataSources = (manifest.after.id === component.after.id
+        && manifest.after.name === component.after.name
+        && manifest.after.type === component.after.type
+        && manifest.after.kind === component.after.kind) ? [manifest] : [manifest, component];
+    const issueKeys = new Set();
+    for (const source of metadataSources) {
+        const issue = (_c = inspectionBySource.get(source)) === null || _c === void 0 ? void 0 : _c.issue;
+        if (!issue) {
+            continue;
+        }
+        const issueKey = JSON.stringify({
+            code: issue.code,
+            expected: issue.expected,
+            received: issue.received,
+        });
+        if (issueKeys.has(issueKey)) {
+            continue;
+        }
+        issueKeys.add(issueKey);
+        diagnostics.push(createMigrationDiagnostic(issue, source.input.file, typeof source.after.id === 'string' ? source.after.id : null));
+    }
+    return diagnostics;
+};
+export const planStepContractV2Migration = (input) => {
+    const operations = [];
+    const diagnostics = [];
+    for (const step of input.steps) {
+        if (step.manifest.status !== 'unique') {
+            diagnostics.push(createSourceDiagnostic('manifest', step.manifest));
+        }
+        if (step.component.status !== 'unique') {
+            diagnostics.push(createSourceDiagnostic('component', step.component));
+        }
+        if (step.manifest.status !== 'unique' || step.component.status !== 'unique') {
+            continue;
+        }
+        const manifest = createPlannedSource('manifest', step.manifest);
+        const component = createPlannedSource('component', step.component);
+        applyMechanicalRules(manifest, component);
+        applyParityRule(manifest, component);
+        operations.push(...buildOperations(step.stepKey, [manifest, component]));
+        diagnostics.push(...collectSemanticDiagnostics(step, manifest, component));
+    }
+    return {
+        operations,
+        protectedChanges: operations.filter((operation) => PROTECTED_FIELDS.has(operation.field)),
+        diagnostics,
+        valid: diagnostics.length === 0,
+    };
+};

package/dist/migrations/step-contract-v3.d.ts

@@ -0,0 +1,41 @@
+import { CURRENT_STEP_CONTRACT_VERSION } from '../steps/step-contract.js';
+export type StepContractV3MigrationStep = Readonly<{
+    id?: unknown;
+    name?: unknown;
+    type: unknown;
+    kind?: unknown;
+    metadata?: Readonly<Record<string, unknown>>;
+    [key: string]: unknown;
+}>;
+export type StepContractV3MigrationManifest = Readonly<{
+    stepContractVersion: 2 | 3;
+    steps: readonly StepContractV3MigrationStep[];
+    [key: string]: unknown;
+}>;
+type StepContractV3MigratedMetadata<T> = T extends Readonly<Record<string, unknown>> ? T extends Readonly<{
+    stepType: 'complete_registration';
+}> ? Omit<T, 'stepType'> & Readonly<{
+    stepType: 'purchase_completed';
+}> : T : T;
+type StepContractV3MigratedStep<T> = T extends Readonly<{
+    id: 'subscription-started';
+    name: 'subscription-started';
+    type: 'complete_registration';
+    kind: 'subscription-handoff';
+}> ? Omit<T, 'type' | 'metadata'> & Readonly<{
+    type: 'purchase_completed';
+}> & (T extends Readonly<{
+    metadata: infer M;
+}> ? Readonly<{
+    metadata: StepContractV3MigratedMetadata<M>;
+}> : unknown) : T;
+type StepContractV3MigratedSteps<T extends readonly StepContractV3MigrationStep[]> = {
+    [K in keyof T]: StepContractV3MigratedStep<T[K]>;
+};
+export type StepContractV3MigratedManifest<T extends StepContractV3MigrationManifest> = T extends StepContractV3MigrationManifest ? Omit<T, 'stepContractVersion' | 'steps'> & Readonly<{
+    stepContractVersion: typeof CURRENT_STEP_CONTRACT_VERSION;
+    steps: T['stepContractVersion'] extends 2 ? StepContractV3MigratedSteps<T['steps']> : T['steps'];
+}> : never;
+export declare const isStepContractV2PurchaseTerminal: (step: Pick<StepContractV3MigrationStep, "id" | "name" | "type" | "kind">) => boolean;
+export declare function migrateStepContractV2ToV3<T extends StepContractV3MigrationManifest>(manifest: T): StepContractV3MigratedManifest<T>;
+export {};

package/dist/migrations/step-contract-v3.js

@@ -0,0 +1,26 @@
+import { CURRENT_STEP_CONTRACT_VERSION, resolveReservedStepContract, } from '../steps/step-contract.js';
+const PREVIOUS_TERMINAL_TYPE = 'complete_registration';
+const CURRENT_TERMINAL_TYPE = 'purchase_completed';
+export const isStepContractV2PurchaseTerminal = (step) => {
+    const reserved = resolveReservedStepContract(2, 'subscription-started');
+    return (reserved === null || reserved === void 0 ? void 0 : reserved.match) === 'exact'
+        && step.id === reserved.id
+        && step.name === reserved.name
+        && step.type === reserved.type
+        && step.kind === reserved.kind;
+};
+export function migrateStepContractV2ToV3(manifest) {
+    if (manifest.stepContractVersion === 3) {
+        return manifest;
+    }
+    const steps = manifest.steps.map((step) => {
+        var _a;
+        if (!isStepContractV2PurchaseTerminal(step)) {
+            return step;
+        }
+        const metadata = ((_a = step.metadata) === null || _a === void 0 ? void 0 : _a.stepType) === PREVIOUS_TERMINAL_TYPE
+            ? Object.assign(Object.assign({}, step.metadata), { stepType: CURRENT_TERMINAL_TYPE }) : step.metadata;
+        return Object.assign(Object.assign(Object.assign({}, step), { type: CURRENT_TERMINAL_TYPE }), (metadata === undefined ? {} : { metadata }));
+    });
+    return Object.assign(Object.assign({}, manifest), { stepContractVersion: CURRENT_STEP_CONTRACT_VERSION, steps });
+}