@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/intent/defaults-resolver.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @file defaults-resolver.ts
+ * @description Genesis V3 Layer 2 (smart auto-fill), ported RIPPLE-NATIVE and
+ * PURE. Given a list of form fields + an INJECTED DefaultsContext, resolves a
+ * default value per empty field by the genesis priority chain:
+ *   profile match → preferences → recent history → time-based → domain → common.
+ * @created 2026-06-08
+ *
+ * LOCKED DECISIONS honoured:
+ *   1. PURE renderer — this module NEVER fetches a user profile or calls a
+ *      service. The DefaultsContext is INJECTED by the host (paw-enterprise
+ *      passes user/time/domain via the spec or the 'ui-defaults-context' Svelte
+ *      context). createTimeContext() MAY read the browser `Date` because this is
+ *      ripple runtime in the browser — the no-Date rule is only for workflow
+ *      scripts, not ripple.
+ *   2. Additive + backward-compatible — `resolveDefaults` only fills EMPTIES; a
+ *      field's explicit `default` always wins, and user input is never
+ *      overridden (FormSection seeds from these only when a value is absent).
+ *      With NO DefaultsContext it is a graceful no-op (returns {} / the field's
+ *      own default), so the existing raw-ui flow is unaffected.
+ *
+ * Genesis reference: ocean-flow/src/lib/ui-renderer/intent/core/defaults-resolver.ts.
+ * Ported off genesis IntentSpec/FormField onto ripple's local, structural field
+ * descriptor so this module has no schema dependency and stays pure.
+ */
+/** Field types the resolver recognises (superset is fine; unknowns no-op). */
+export type DefaultsFieldType = 'text' | 'email' | 'tel' | 'url' | 'password' | 'number' | 'date' | 'time' | 'textarea' | 'select' | 'radio' | 'checkbox' | (string & {});
+/**
+ * The minimal field shape the resolver reads. Structural on purpose: any object
+ * with an `id` (and optionally `type` / `default`) works, so FormLayout's
+ * `FormFieldLike`, FormSection's `FormField`, and a genesis FormField all fit.
+ */
+export interface DefaultsField {
+    id: string;
+    type?: DefaultsFieldType;
+    /** An explicit default authored on the field — always wins over a resolved one. */
+    default?: unknown;
+}
+/** User context for smart defaults resolution (INJECTED by the host). */
+export interface UserContext {
+    /** User preferences from profile / storage. */
+    preferences?: Record<string, unknown>;
+    /** Recent selections/interactions for predictive defaults. */
+    history?: Array<{
+        type: string;
+        value: unknown;
+        timestamp: string;
+    }>;
+    /** User profile data. */
+    profile?: {
+        name?: string;
+        email?: string;
+        phone?: string;
+        address?: string;
+    };
+}
+/** Time context for time-aware defaults (INJECTED, or built via createTimeContext). */
+export interface TimeContext {
+    now: Date;
+    dayOfWeek: string;
+    isWeekend: boolean;
+    timeOfDay: 'morning' | 'afternoon' | 'evening' | 'night';
+    season: 'spring' | 'summer' | 'fall' | 'winter';
+}
+/** Domain context for domain-specific defaults (INJECTED by the host). */
+export interface DomainContext {
+    /** Current domain (food, travel, booking, ecommerce, fitness, …). */
+    domain?: string;
+    /** Previous selections in this flow. */
+    flowSelections?: Record<string, unknown>;
+}
+/** Full context for smart defaults resolution. All keys optional → graceful no-op. */
+export interface DefaultsContext {
+    user?: UserContext;
+    time?: TimeContext;
+    domain?: DomainContext;
+}
+/**
+ * Build a TimeContext from a clock. PURE w.r.t. inputs: pass `now` for
+ * deterministic tests; defaults to the browser `Date` at runtime.
+ */
+export declare function createTimeContext(now?: Date): TimeContext;
+/**
+ * Assemble a DefaultsContext from the pieces a host injects. A convenience for
+ * the host; the resolver itself accepts any DefaultsContext. If `time` is
+ * omitted it is built from the browser clock (ripple runtime — Date is fine).
+ */
+export declare function createDefaultsContext(opts?: {
+    user?: UserContext;
+    domain?: string | DomainContext;
+    time?: TimeContext;
+    now?: Date;
+}): DefaultsContext;
+/**
+ * Resolve smart defaults for a list of fields. Returns a values map keyed by
+ * field id, holding ONLY entries the resolver could fill (the field had no
+ * explicit `default` and the context produced a value). EMPTIES-ONLY by design:
+ * a field with an explicit `default` is skipped here (its own default wins in
+ * FormSection.valueOf). With no context → {} (graceful no-op).
+ *
+ * @param fields the form fields (anything with an `id`).
+ * @param context the INJECTED defaults context (host-provided). Optional.
+ */
+export declare function resolveDefaults(fields: DefaultsField[] | undefined, context?: DefaultsContext): Record<string, unknown>;
+/**
+ * Get the smart default for ONE field, by the genesis priority chain. Returns
+ * `undefined` when nothing applies (the field stays empty).
+ */
+export declare function getSmartDefault(field: DefaultsField, context: DefaultsContext): unknown;
+/**
+ * All defaults for a field list INCLUDING each field's own explicit `default`
+ * (field.default wins). Useful when the host wants the full seeded value map up
+ * front. `resolveDefaults` is the empties-only sibling FormSection uses.
+ */
+export declare function getAllDefaults(fields: DefaultsField[] | undefined, context?: DefaultsContext): Record<string, unknown>;

package/dist/intent/defaults-resolver.js

@@ -0,0 +1,288 @@
+/**
+ * @file defaults-resolver.ts
+ * @description Genesis V3 Layer 2 (smart auto-fill), ported RIPPLE-NATIVE and
+ * PURE. Given a list of form fields + an INJECTED DefaultsContext, resolves a
+ * default value per empty field by the genesis priority chain:
+ *   profile match → preferences → recent history → time-based → domain → common.
+ * @created 2026-06-08
+ *
+ * LOCKED DECISIONS honoured:
+ *   1. PURE renderer — this module NEVER fetches a user profile or calls a
+ *      service. The DefaultsContext is INJECTED by the host (paw-enterprise
+ *      passes user/time/domain via the spec or the 'ui-defaults-context' Svelte
+ *      context). createTimeContext() MAY read the browser `Date` because this is
+ *      ripple runtime in the browser — the no-Date rule is only for workflow
+ *      scripts, not ripple.
+ *   2. Additive + backward-compatible — `resolveDefaults` only fills EMPTIES; a
+ *      field's explicit `default` always wins, and user input is never
+ *      overridden (FormSection seeds from these only when a value is absent).
+ *      With NO DefaultsContext it is a graceful no-op (returns {} / the field's
+ *      own default), so the existing raw-ui flow is unaffected.
+ *
+ * Genesis reference: ocean-flow/src/lib/ui-renderer/intent/core/defaults-resolver.ts.
+ * Ported off genesis IntentSpec/FormField onto ripple's local, structural field
+ * descriptor so this module has no schema dependency and stays pure.
+ */
+// =============================================================================
+// Context construction (browser Date is allowed here — ripple runtime)
+// =============================================================================
+/**
+ * Build a TimeContext from a clock. PURE w.r.t. inputs: pass `now` for
+ * deterministic tests; defaults to the browser `Date` at runtime.
+ */
+export function createTimeContext(now = new Date()) {
+    const hour = now.getHours();
+    const month = now.getMonth();
+    // Season (Northern hemisphere).
+    let season;
+    if (month >= 2 && month <= 4)
+        season = 'spring';
+    else if (month >= 5 && month <= 7)
+        season = 'summer';
+    else if (month >= 8 && month <= 10)
+        season = 'fall';
+    else
+        season = 'winter';
+    // Time of day.
+    let timeOfDay;
+    if (hour < 6)
+        timeOfDay = 'night';
+    else if (hour < 12)
+        timeOfDay = 'morning';
+    else if (hour < 17)
+        timeOfDay = 'afternoon';
+    else if (hour < 21)
+        timeOfDay = 'evening';
+    else
+        timeOfDay = 'night';
+    return {
+        now,
+        dayOfWeek: now.toLocaleDateString('en-US', { weekday: 'long' }),
+        isWeekend: [0, 6].includes(now.getDay()),
+        timeOfDay,
+        season
+    };
+}
+/**
+ * Assemble a DefaultsContext from the pieces a host injects. A convenience for
+ * the host; the resolver itself accepts any DefaultsContext. If `time` is
+ * omitted it is built from the browser clock (ripple runtime — Date is fine).
+ */
+export function createDefaultsContext(opts = {}) {
+    const domain = typeof opts.domain === 'string' ? { domain: opts.domain } : opts.domain;
+    return {
+        user: opts.user,
+        time: opts.time ?? createTimeContext(opts.now),
+        domain
+    };
+}
+// =============================================================================
+// Resolution — the genesis priority chain
+// =============================================================================
+/**
+ * Resolve smart defaults for a list of fields. Returns a values map keyed by
+ * field id, holding ONLY entries the resolver could fill (the field had no
+ * explicit `default` and the context produced a value). EMPTIES-ONLY by design:
+ * a field with an explicit `default` is skipped here (its own default wins in
+ * FormSection.valueOf). With no context → {} (graceful no-op).
+ *
+ * @param fields the form fields (anything with an `id`).
+ * @param context the INJECTED defaults context (host-provided). Optional.
+ */
+export function resolveDefaults(fields, context) {
+    const out = {};
+    if (!fields || fields.length === 0)
+        return out;
+    if (!context)
+        return out; // no-op without a context — never breaks the flow.
+    for (const field of fields) {
+        // A field's explicit default wins — leave it to FormSection, skip here.
+        if (field.default !== undefined)
+            continue;
+        const value = getSmartDefault(field, context);
+        if (value !== undefined)
+            out[field.id] = value;
+    }
+    return out;
+}
+/**
+ * Get the smart default for ONE field, by the genesis priority chain. Returns
+ * `undefined` when nothing applies (the field stays empty).
+ */
+export function getSmartDefault(field, context) {
+    const { id } = field;
+    const type = field.type ?? 'text';
+    // 1. User profile (exact-ish matches).
+    if (context.user?.profile) {
+        const profileValue = getProfileValue(id, context.user.profile);
+        if (profileValue !== undefined)
+            return profileValue;
+    }
+    // 2. User preferences (keyed by field id).
+    if (context.user?.preferences && id in context.user.preferences) {
+        return context.user.preferences[id];
+    }
+    // 3. Recent history (most recent matching entry).
+    const historyDefault = getHistoryDefault(id, context.user?.history);
+    if (historyDefault !== undefined)
+        return historyDefault;
+    // 4. Time-based (date / time fields).
+    if (type === 'date' || id.includes('date')) {
+        return suggestDate(id, context);
+    }
+    if (type === 'time' || id.includes('time')) {
+        return suggestTime(id, context);
+    }
+    // 5. Domain-specific.
+    if (context.domain?.domain) {
+        const domainDefault = getDomainDefault(id, context);
+        if (domainDefault !== undefined)
+            return domainDefault;
+    }
+    // 6. Common field patterns.
+    return getCommonDefault(id, type, context);
+}
+// =============================================================================
+// Priority-chain helpers (pure)
+// =============================================================================
+function getProfileValue(id, profile) {
+    const idLower = id.toLowerCase();
+    if (idLower === 'name' || idLower === 'fullname' || idLower === 'full_name') {
+        return profile.name;
+    }
+    if (idLower === 'email' || idLower === 'email_address') {
+        return profile.email;
+    }
+    if (idLower === 'phone' || idLower === 'phone_number' || idLower === 'tel') {
+        return profile.phone;
+    }
+    if (idLower === 'address' || idLower === 'shipping_address') {
+        return profile.address;
+    }
+    return undefined;
+}
+function getHistoryDefault(id, history) {
+    if (!history || history.length === 0)
+        return undefined;
+    const recent = history
+        .filter((h) => h.type === id)
+        .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())[0];
+    return recent?.value;
+}
+function suggestDate(id, context) {
+    const now = context.time?.now ?? new Date();
+    const idLower = id.toLowerCase();
+    const formatDate = (date) => date.toISOString().split('T')[0];
+    // End-of-range dates → tomorrow.
+    if (idLower.includes('checkout') ||
+        idLower.includes('end') ||
+        idLower.includes('return')) {
+        const tomorrow = new Date(now);
+        tomorrow.setDate(tomorrow.getDate() + 1);
+        return formatDate(tomorrow);
+    }
+    // Travel dates on a weekday → next Friday.
+    if (context.domain?.domain === 'travel' && context.time?.isWeekend === false) {
+        const daysUntilFriday = (5 - now.getDay() + 7) % 7 || 7;
+        const nextFriday = new Date(now);
+        nextFriday.setDate(nextFriday.getDate() + daysUntilFriday);
+        return formatDate(nextFriday);
+    }
+    return formatDate(now);
+}
+function suggestTime(id, context) {
+    if (!context.time)
+        return '19:00';
+    const hour = context.time.now.getHours();
+    const idLower = id.toLowerCase();
+    if (context.domain?.domain === 'food' || context.domain?.domain === 'booking') {
+        if (context.time.timeOfDay === 'morning') {
+            return idLower.includes('lunch') ? '12:00' : '19:00';
+        }
+        if (context.time.timeOfDay === 'afternoon')
+            return '19:00';
+        return hour < 20 ? `${Math.max(hour + 1, 18)}:00` : '19:00';
+    }
+    if (idLower.includes('departure') || idLower.includes('flight')) {
+        return context.time.timeOfDay === 'morning' ? '08:00' : '14:00';
+    }
+    if (hour < 12)
+        return '12:00';
+    if (hour < 17)
+        return '17:00';
+    return `${Math.min(hour + 1, 23)}:00`;
+}
+function getDomainDefault(id, context) {
+    const domain = context.domain?.domain;
+    const idLower = id.toLowerCase();
+    switch (domain) {
+        case 'food':
+            if (idLower === 'party_size' || idLower === 'guests')
+                return 2;
+            if (idLower === 'cuisine')
+                return 'Any';
+            break;
+        case 'travel':
+            if (idLower === 'passengers' || idLower === 'travelers')
+                return 1;
+            if (idLower === 'class' || idLower === 'cabin')
+                return 'economy';
+            if (idLower === 'rooms')
+                return 1;
+            break;
+        case 'booking':
+            if (idLower === 'duration' || idLower === 'length')
+                return 60;
+            break;
+        case 'ecommerce':
+            if (idLower === 'quantity')
+                return 1;
+            break;
+        case 'fitness':
+            if (idLower === 'duration')
+                return 30;
+            if (idLower === 'sets')
+                return 3;
+            if (idLower === 'reps')
+                return 10;
+            break;
+    }
+    return undefined;
+}
+function getCommonDefault(id, type, context) {
+    const idLower = id.toLowerCase();
+    if (idLower === 'quantity' || idLower === 'qty' || idLower === 'count') {
+        return 1;
+    }
+    if (idLower === 'party_size' || idLower === 'guests' || idLower === 'people') {
+        return context.user?.preferences?.party_size ?? 2;
+    }
+    if (idLower === 'rating' || idLower === 'stars') {
+        return 5;
+    }
+    if (type === 'checkbox') {
+        if (idLower === 'notifications' || idLower === 'remember_me')
+            return true;
+        return false;
+    }
+    // Select fields with options — don't guess.
+    if (type === 'select')
+        return undefined;
+    return undefined;
+}
+/**
+ * All defaults for a field list INCLUDING each field's own explicit `default`
+ * (field.default wins). Useful when the host wants the full seeded value map up
+ * front. `resolveDefaults` is the empties-only sibling FormSection uses.
+ */
+export function getAllDefaults(fields, context) {
+    const out = {};
+    if (!fields)
+        return out;
+    for (const field of fields) {
+        const value = field.default ?? (context ? getSmartDefault(field, context) : undefined);
+        if (value !== undefined)
+            out[field.id] = value;
+    }
+    return out;
+}

package/dist/intent/fixtures/onboarding-wizard.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file onboarding-wizard.ts
+ * @description NON-COMMERCE proof fixture for the Chain Flow primitive (RFC 13 M1).
+ * @created 2026-05-31
+ * @updated 2026-06-15 — terminal `onComplete` switched from `emit` to `chat` to
+ *   mirror the production builder. The fixture now matches pocketpaw
+ *   `build_flow('onboarding_wizard')` (`pocketpaw/ripple/_flows.py`
+ *   `build_onboarding_wizard`), whose terminal hands the collected answers back
+ *   to the AGENT via `{kind:'chat', message:<prompt>}` — the flow loops to the
+ *   agent instead of dead-ending on an `emit` event no one consumed. The emit
+ *   terminal kind is still exercised separately in FlowRunner.test.ts.
+ *
+ * A three-step onboarding wizard — "pick a goal -> enter details -> confirm" —
+ * expressed as ONE nested `chain` / `chain_map` `UniversalSpec`. It proves the
+ * primitive without any commerce or network: the whole decision tree is
+ * materialized up front, so the `ChainExecutor` walks it entirely client-side
+ * with zero round-trips between steps. Only the terminal hands back to the agent.
+ *
+ * What it exercises:
+ *   - `chain_map`: step 1 branches on the picked goal id (focus vs collaborate).
+ *   - context accumulation: each step's `flowId` namespaces its data.
+ *   - `{state.x}` cross-step pre-fill: the confirm step reads back the goal and
+ *     the workspace name the user entered earlier via
+ *     `{state.pick_goal_selection.label}` /
+ *     `{state.enter_details_formData.workspace}`.
+ *   - `onComplete`: the terminal step declares a `chat` FlowAction (the chat
+ *     loop) that hands the full accumulated payload back to the agent — the
+ *     same terminal the real `build_flow('onboarding_wizard')` emits.
+ *
+ * UINode shape notes (so the fixture renders for real):
+ *   - `on_click` is a TOP-LEVEL UINode key (sibling of `type`/`props`/`bind`),
+ *     not a prop.
+ *   - the button's visible text comes from `props.label`.
+ *   - steps talk to the FlowRunner with the standard `emit` action whose
+ *     `target` is a flow verb (`flow.next` / `flow.submit`); its `value` carries
+ *     `{ selection, formData }`, with `{state.x}` placeholders the dispatcher
+ *     resolves before the runner sees them.
+ */
+import type { UniversalSpec } from '@ripple-ui/core';
+/**
+ * Build the onboarding-wizard flow spec.
+ *
+ * Kept as a factory so each test gets a fresh, independent tree.
+ */
+export declare function buildOnboardingWizard(): UniversalSpec;

package/dist/intent/fixtures/onboarding-wizard.js

@@ -0,0 +1,182 @@
+/**
+ * @file onboarding-wizard.ts
+ * @description NON-COMMERCE proof fixture for the Chain Flow primitive (RFC 13 M1).
+ * @created 2026-05-31
+ * @updated 2026-06-15 — terminal `onComplete` switched from `emit` to `chat` to
+ *   mirror the production builder. The fixture now matches pocketpaw
+ *   `build_flow('onboarding_wizard')` (`pocketpaw/ripple/_flows.py`
+ *   `build_onboarding_wizard`), whose terminal hands the collected answers back
+ *   to the AGENT via `{kind:'chat', message:<prompt>}` — the flow loops to the
+ *   agent instead of dead-ending on an `emit` event no one consumed. The emit
+ *   terminal kind is still exercised separately in FlowRunner.test.ts.
+ *
+ * A three-step onboarding wizard — "pick a goal -> enter details -> confirm" —
+ * expressed as ONE nested `chain` / `chain_map` `UniversalSpec`. It proves the
+ * primitive without any commerce or network: the whole decision tree is
+ * materialized up front, so the `ChainExecutor` walks it entirely client-side
+ * with zero round-trips between steps. Only the terminal hands back to the agent.
+ *
+ * What it exercises:
+ *   - `chain_map`: step 1 branches on the picked goal id (focus vs collaborate).
+ *   - context accumulation: each step's `flowId` namespaces its data.
+ *   - `{state.x}` cross-step pre-fill: the confirm step reads back the goal and
+ *     the workspace name the user entered earlier via
+ *     `{state.pick_goal_selection.label}` /
+ *     `{state.enter_details_formData.workspace}`.
+ *   - `onComplete`: the terminal step declares a `chat` FlowAction (the chat
+ *     loop) that hands the full accumulated payload back to the agent — the
+ *     same terminal the real `build_flow('onboarding_wizard')` emits.
+ *
+ * UINode shape notes (so the fixture renders for real):
+ *   - `on_click` is a TOP-LEVEL UINode key (sibling of `type`/`props`/`bind`),
+ *     not a prop.
+ *   - the button's visible text comes from `props.label`.
+ *   - steps talk to the FlowRunner with the standard `emit` action whose
+ *     `target` is a flow verb (`flow.next` / `flow.submit`); its `value` carries
+ *     `{ selection, formData }`, with `{state.x}` placeholders the dispatcher
+ *     resolves before the runner sees them.
+ */
+/**
+ * Build the onboarding-wizard flow spec.
+ *
+ * Kept as a factory so each test gets a fresh, independent tree.
+ */
+export function buildOnboardingWizard() {
+    // --- Step 3 (terminal): confirm, pre-filled from earlier answers ----------
+    const confirmStep = {
+        version: '2.0',
+        id: 'onboard-confirm',
+        flowId: 'confirm',
+        intent: 'confirm',
+        title: 'You are all set',
+        // Terminal action: hand the collected answers back to the AGENT via the
+        // chat loop. Mirrors pocketpaw `build_onboarding_wizard` exactly — the
+        // runtime appends the accumulated payload to this message before sending,
+        // so we only supply the human-readable prompt here.
+        onComplete: {
+            kind: 'chat',
+            message: "I've finished onboarding — here are my choices, please set up my workspace."
+        },
+        ui: {
+            type: 'container',
+            props: { class: 'flow-confirm' },
+            children: [
+                { type: 'heading', props: { text: 'Review your setup' } },
+                {
+                    // Pre-fill from step 1's selection (cross-step `{state.x}`).
+                    type: 'text',
+                    props: { text: 'Goal: {state.pick_goal_selection.label}' }
+                },
+                {
+                    // Pre-fill from step 2's form data.
+                    type: 'text',
+                    props: { text: 'Workspace: {state.enter_details_formData.workspace}' }
+                },
+                {
+                    type: 'button',
+                    props: { label: 'Finish' },
+                    on_click: { action: 'emit', target: 'flow.submit', value: {} }
+                }
+            ]
+        }
+    };
+    // --- Step 2 (focus branch): collect workspace details -> confirm ----------
+    const detailsStep = {
+        version: '2.0',
+        id: 'onboard-details',
+        flowId: 'enter_details',
+        intent: 'form',
+        title: 'Set up your workspace',
+        chain: confirmStep,
+        ui: {
+            type: 'container',
+            children: [
+                { type: 'heading', props: { text: 'Name your workspace' } },
+                {
+                    type: 'input',
+                    bind: 'workspace',
+                    props: { label: 'Workspace name', placeholder: 'Acme HQ' }
+                },
+                {
+                    type: 'button',
+                    props: { label: 'Continue' },
+                    on_click: {
+                        action: 'emit',
+                        target: 'flow.next',
+                        // formData carries the entered workspace name forward; the
+                        // `{state.workspace}` placeholder resolves at dispatch time.
+                        value: { formData: { workspace: '{state.workspace}' } }
+                    }
+                }
+            ]
+        }
+    };
+    // --- Step 2 (collaborate branch): a DIFFERENT step (proves chain_map) -----
+    const inviteStep = {
+        version: '2.0',
+        id: 'onboard-invite',
+        flowId: 'enter_details',
+        intent: 'form',
+        title: 'Invite your team',
+        chain: confirmStep,
+        ui: {
+            type: 'container',
+            children: [
+                { type: 'heading', props: { text: 'Name your shared workspace' } },
+                {
+                    type: 'input',
+                    bind: 'workspace',
+                    props: { label: 'Workspace name', placeholder: 'Acme Team' }
+                },
+                {
+                    type: 'button',
+                    props: { label: 'Continue' },
+                    on_click: {
+                        action: 'emit',
+                        target: 'flow.next',
+                        value: { formData: { workspace: '{state.workspace}' } }
+                    }
+                }
+            ]
+        }
+    };
+    // --- Step 1 (root): pick a goal, branch on the selection ------------------
+    const root = {
+        version: '2.0',
+        id: 'onboard-goal',
+        flowId: 'pick_goal',
+        intent: 'select',
+        title: 'What brings you here?',
+        selection: 'single',
+        // Branch: the picked goal's id decides which step 2 we go to.
+        chain_map: {
+            focus: detailsStep,
+            collaborate: inviteStep
+        },
+        ui: {
+            type: 'container',
+            children: [
+                { type: 'heading', props: { text: 'Pick your primary goal' } },
+                {
+                    type: 'button',
+                    props: { label: 'Focus on my own work' },
+                    on_click: {
+                        action: 'emit',
+                        target: 'flow.next',
+                        value: { selection: { id: 'focus', label: 'Focus on my own work' } }
+                    }
+                },
+                {
+                    type: 'button',
+                    props: { label: 'Collaborate with a team' },
+                    on_click: {
+                        action: 'emit',
+                        target: 'flow.next',
+                        value: { selection: { id: 'collaborate', label: 'Collaborate with a team' } }
+                    }
+                }
+            ]
+        }
+    };
+    return root;
+}

package/dist/intent/flow-options.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file flow-options.ts
+ * @description Extracts selectable flow options from a flow `select` step's raw
+ * `ui` widget tree, so a goal-pick step's bare buttons can be re-rendered as
+ * polished OptionList cards (issue c) WITHOUT changing the spec contract.
+ *
+ * A flow `select` step ships its choices as raw `button` nodes whose `on_click`
+ * is an `emit` action targeting a flow verb (`flow.next` / `flow.submit`) with a
+ * `value.selection`. extractFlowOptions() finds those buttons at any depth,
+ * returning one option per button plus the original `on_click` handler so the
+ * caller can re-dispatch the exact same event through the live EventDispatcher.
+ * pruneFlowOptions() returns a copy of the tree without those same buttons (at
+ * any depth), so the rest of the step renders above the cards and no choice
+ * shows twice. Both walkers share isFlowOption(), so what becomes a card is
+ * exactly what leaves the tree.
+ *
+ * PURE: reads the tree only, never mutates it. No state, no dispatch, no fetch.
+ */
+import type { UINode } from '@ripple-ui/core';
+/** A flow option distilled from one option button in the step's `ui` tree. */
+export interface FlowOption {
+    /** Stable option id — the emit value's `selection.id`, else the label. */
+    id: string;
+    /** Visible label (the button's `props.label`). */
+    label: string;
+    /** Optional sub-label if the button carries a description prop. */
+    description?: string;
+    /** Optional Lucide icon slug if the button carries one. */
+    icon?: string;
+    /** The button's original `on_click` handler — re-dispatched verbatim on select. */
+    onClick: unknown;
+}
+/**
+ * Walk a UINode tree and collect every flow-select option button. Returns [] when
+ * the step isn't a button-driven option set (then the caller falls back to the raw
+ * tree, never blocking a render).
+ */
+export declare function extractFlowOptions(root: UINode | undefined): FlowOption[];
+/**
+ * A copy of `root` without its flow-option buttons, at any depth. With `all`
+ * (a step still streaming in) every button goes: one whose `on_click` has not
+ * arrived yet cannot be told apart from an option, and showing it as a plain
+ * button only to swap it for a card is the duplicate flash. A container whose
+ * children were all removed goes too; leaves (text, image) always stay. An
+ * untouched subtree keeps its original reference. Returns undefined when
+ * nothing is left.
+ */
+export declare function pruneFlowOptions(root: UINode | undefined, { all }?: {
+    all?: boolean;
+}): UINode | undefined;