@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/intent/flow-options.js

@@ -0,0 +1,111 @@
+/**
+ * @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 { asText } from '../widgets/text-coerce.js';
+const FLOW_VERBS = new Set(['flow.next', 'flow.submit']);
+function asRecord(v) {
+    return v && typeof v === 'object' ? v : null;
+}
+/** Is this `on_click` an emit targeting a flow verb that carries a selection? */
+function isFlowSelectClick(onClick) {
+    const h = asRecord(onClick);
+    if (!h)
+        return false;
+    if (h.action !== 'emit')
+        return false;
+    if (typeof h.target !== 'string' || !FLOW_VERBS.has(h.target))
+        return false;
+    const value = asRecord(h.value);
+    // Must carry a selection — that's what makes it an OPTION, not a Continue/Finish.
+    return !!value && 'selection' in value;
+}
+function isFlowOption(n) {
+    return n.type === 'button' && isFlowSelectClick(n.on_click);
+}
+function labelOf(node) {
+    const props = asRecord(node.props) ?? {};
+    return asText(props.label ?? props.text);
+}
+function selectionOf(onClick) {
+    const value = asRecord(onClick.value);
+    return asRecord(value?.selection);
+}
+/**
+ * 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 function extractFlowOptions(root) {
+    if (!root)
+        return [];
+    const out = [];
+    const visit = (node) => {
+        const n = asRecord(node);
+        if (!n)
+            return;
+        const onClick = n.on_click;
+        if (isFlowOption(n)) {
+            const handler = onClick;
+            const sel = selectionOf(handler);
+            const label = labelOf(n);
+            const props = asRecord(n.props) ?? {};
+            out.push({
+                id: asText(sel?.id ?? sel?.value ?? label),
+                label,
+                description: sel?.description != null ? asText(sel.description) : (props.description != null ? asText(props.description) : undefined),
+                icon: sel?.icon != null ? asText(sel.icon) : (props.icon != null ? asText(props.icon) : undefined),
+                onClick
+            });
+        }
+        const children = n.children;
+        if (Array.isArray(children)) {
+            for (const c of children)
+                visit(c);
+        }
+    };
+    visit(root);
+    return out;
+}
+/**
+ * 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 function pruneFlowOptions(root, { all = false } = {}) {
+    const drop = (n) => isFlowOption(n) || (all && n.type === 'button');
+    const prune = (node) => {
+        const n = asRecord(node);
+        if (!n)
+            return node;
+        if (drop(n))
+            return undefined;
+        const children = n.children;
+        if (!Array.isArray(children) || children.length === 0)
+            return node;
+        const kept = children.map(prune).filter((c) => c !== undefined);
+        if (kept.length === 0)
+            return undefined;
+        const same = kept.length === children.length && kept.every((c, i) => c === children[i]);
+        return same ? node : { ...n, children: kept };
+    };
+    return prune(root);
+}

package/dist/intent/index.d.ts

@@ -0,0 +1,19 @@
+export * from './layout-engine.js';
+export * from './pattern-detector.js';
+export { resolveDefaults, getSmartDefault, getAllDefaults, createDefaultsContext, createTimeContext, type DefaultsContext, type DefaultsField, type DefaultsFieldType, type UserContext as DefaultsUserContext, type TimeContext as DefaultsTimeContext, type DomainContext as DefaultsDomainContext } from './defaults-resolver.js';
+export { ChainExecutor, MAX_HISTORY_DEPTH, type ChainState, type TerminalResult } from './chain-executor.svelte.js';
+export { default as FlowRunner } from './FlowRunner.svelte';
+export { default as IntentRenderer } from './IntentRenderer.svelte';
+export { default as ChainProgress } from './ChainProgress.svelte';
+export { default as FormLayout } from './layouts/FormLayout.svelte';
+export { default as SummaryLayout } from './layouts/SummaryLayout.svelte';
+export { default as CardGridLayout } from './layouts/CardGridLayout.svelte';
+export { default as ListLayout } from './layouts/ListLayout.svelte';
+export { default as SelectLayout } from './layouts/SelectLayout.svelte';
+export { default as DetailLayout } from './layouts/DetailLayout.svelte';
+export { default as InfoHeroLayout } from './layouts/InfoHeroLayout.svelte';
+export { default as SearchLayout } from './layouts/SearchLayout.svelte';
+export { extractFlowOptions, type FlowOption } from './flow-options.js';
+export { toLayoutInput, resolveLayoutMode, summaryItemsFromContext, type LayoutInput, type LayoutMode, type FieldMapping as LayoutFieldMapping } from './layout-adapter.js';
+export { buildOnboardingWizard } from './fixtures/onboarding-wizard.js';
+export { DashboardManager, createDashboardManager, type DashboardSpec, type DashboardWidget } from './dashboard-manager.svelte.js';

package/dist/intent/index.js

@@ -0,0 +1,19 @@
+export * from './layout-engine.js';
+export * from './pattern-detector.js';
+export { resolveDefaults, getSmartDefault, getAllDefaults, createDefaultsContext, createTimeContext } from './defaults-resolver.js';
+export { ChainExecutor, MAX_HISTORY_DEPTH } from './chain-executor.svelte.js';
+export { default as FlowRunner } from './FlowRunner.svelte';
+export { default as IntentRenderer } from './IntentRenderer.svelte';
+export { default as ChainProgress } from './ChainProgress.svelte';
+export { default as FormLayout } from './layouts/FormLayout.svelte';
+export { default as SummaryLayout } from './layouts/SummaryLayout.svelte';
+export { default as CardGridLayout } from './layouts/CardGridLayout.svelte';
+export { default as ListLayout } from './layouts/ListLayout.svelte';
+export { default as SelectLayout } from './layouts/SelectLayout.svelte';
+export { default as DetailLayout } from './layouts/DetailLayout.svelte';
+export { default as InfoHeroLayout } from './layouts/InfoHeroLayout.svelte';
+export { default as SearchLayout } from './layouts/SearchLayout.svelte';
+export { extractFlowOptions } from './flow-options.js';
+export { toLayoutInput, resolveLayoutMode, summaryItemsFromContext } from './layout-adapter.js';
+export { buildOnboardingWizard } from './fixtures/onboarding-wizard.js';
+export { DashboardManager, createDashboardManager } from './dashboard-manager.svelte.js';

package/dist/intent/layout-adapter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @file layout-adapter.ts
+ * @description The SCHEMA-as-adapter boundary (locked decision 2). Ripple keeps
+ * its own `UniversalSpec` as the contract; this module maps a spec's fields to
+ * what an intent layout needs, WITHOUT adopting genesis's IntentSpec wholesale.
+ * @created 2026-06-07
+ * @changes
+ *   - 2026-09-17: display coercions route through asText (objects → JSON, not
+ *     "[object Object]") — oxlint no-base-to-string sweep
+ *   - 2026-06-07: wire `review_rows` (pocketpaw start_flow confirm contract) —
+ *     `review_rows: [{label, value}]` emitted by the pocketpaw builder on confirm
+ *     steps is treated equivalently to `form_fields` for mode detection, and
+ *     surfaced as `items` for SummaryLayout / ResultsSummary so the confirm step
+ *     renders a designed review card instead of falling to raw-ui.
+ *
+ * Two render modes, decided per spec:
+ *   - 'data'   the spec carries structured layout DATA (genesis style):
+ *              `form_fields` for a form, `review_rows` for a confirm, or
+ *              `data.items` / accumulated context for a summary / list. The
+ *              designed layout renders the data directly.
+ *   - 'raw-ui' the spec only carries a raw `ui` widget tree (our current
+ *              `start_flow` steps: heading/input/button). The layout renders that
+ *              `ui` via NodeRenderer INSIDE the polished card chrome — the user
+ *              still sees a card + step header, never a bare tree, AND the inner
+ *              buttons keep driving the flow (flow.next / flow.submit) because the
+ *              tree is untouched.
+ *
+ * PURE: every helper reads only data already present on the spec. No service
+ * call, no fetch (locked decision 1).
+ */
+import type { UniversalSpec } from '@ripple-ui/core';
+import type { LayoutMetadata } from './layout-engine.js';
+/** How a layout should source its content for a given spec. */
+export type LayoutMode = 'data' | 'raw-ui';
+/** Field-name mapping a layout uses to read items (genesis FieldMapping). */
+export type FieldMapping = Record<string, string>;
+/**
+ * The normalized input a layout consumes — the adapter's whole output. Layouts
+ * read THIS, never the raw UniversalSpec, so the schema bridge lives in one place.
+ */
+export interface LayoutInput {
+    /** The originating spec (for title/description/ui escape hatch). */
+    spec: UniversalSpec;
+    /** Whether to render structured data or the raw `ui` tree. */
+    mode: LayoutMode;
+    /** Step heading — the spec title (rendered as the card header). */
+    title?: string;
+    /** Optional sub-heading. */
+    description?: string;
+    /** Structured rows for the layout (summary/list); empty in raw-ui mode. */
+    items: Record<string, unknown>[];
+    /** Form fields (genesis style); empty/undefined in raw-ui mode. */
+    formFields: unknown[];
+    /** Field-name mapping for reading items. */
+    fields: FieldMapping;
+    /** Layout sizing/selection metadata from the layout engine. */
+    meta: LayoutMetadata;
+}
+/**
+ * Does this spec expose structured layout data, or only a raw `ui` tree?
+ * Structured = genesis-style `form_fields`, pocketpaw `review_rows`, or
+ * `data.items` / `data.stats`. Anything else (flow steps with only a `ui`
+ * tree) is raw-ui.
+ */
+export declare function resolveLayoutMode(spec: UniversalSpec): LayoutMode;
+/**
+ * Build summary rows from the flow's accumulated context for a confirm step that
+ * carries no structured data of its own. Mirrors genesis's confirm fallback:
+ * turns each `<flowId>_selection` into a labelled "Goal: …" style row. Pure —
+ * `context` is handed in by FlowRunner from the executor; no executor access here.
+ */
+export declare function summaryItemsFromContext(context: Record<string, unknown> | undefined): Record<string, unknown>[];
+/**
+ * The adapter: map a UniversalSpec (+ optional flow context) to a LayoutInput.
+ * This is the ONLY place that knows how ripple's spec shape feeds a layout.
+ */
+export declare function toLayoutInput(spec: UniversalSpec, context?: Record<string, unknown>): LayoutInput;

package/dist/intent/layout-adapter.js

@@ -0,0 +1,135 @@
+/**
+ * @file layout-adapter.ts
+ * @description The SCHEMA-as-adapter boundary (locked decision 2). Ripple keeps
+ * its own `UniversalSpec` as the contract; this module maps a spec's fields to
+ * what an intent layout needs, WITHOUT adopting genesis's IntentSpec wholesale.
+ * @created 2026-06-07
+ * @changes
+ *   - 2026-09-17: display coercions route through asText (objects → JSON, not
+ *     "[object Object]") — oxlint no-base-to-string sweep
+ *   - 2026-06-07: wire `review_rows` (pocketpaw start_flow confirm contract) —
+ *     `review_rows: [{label, value}]` emitted by the pocketpaw builder on confirm
+ *     steps is treated equivalently to `form_fields` for mode detection, and
+ *     surfaced as `items` for SummaryLayout / ResultsSummary so the confirm step
+ *     renders a designed review card instead of falling to raw-ui.
+ *
+ * Two render modes, decided per spec:
+ *   - 'data'   the spec carries structured layout DATA (genesis style):
+ *              `form_fields` for a form, `review_rows` for a confirm, or
+ *              `data.items` / accumulated context for a summary / list. The
+ *              designed layout renders the data directly.
+ *   - 'raw-ui' the spec only carries a raw `ui` widget tree (our current
+ *              `start_flow` steps: heading/input/button). The layout renders that
+ *              `ui` via NodeRenderer INSIDE the polished card chrome — the user
+ *              still sees a card + step header, never a bare tree, AND the inner
+ *              buttons keep driving the flow (flow.next / flow.submit) because the
+ *              tree is untouched.
+ *
+ * PURE: every helper reads only data already present on the spec. No service
+ * call, no fetch (locked decision 1).
+ */
+import { getLayoutMetadata } from './layout-engine.js';
+import { asText } from '../widgets/text-coerce.js';
+const DEFAULT_FIELDS = {
+    id: 'id',
+    title: 'title',
+    subtitle: 'subtitle',
+    description: 'description',
+    price: 'price',
+    image: 'image',
+    icon: 'icon'
+};
+/**
+ * Does this spec expose structured layout data, or only a raw `ui` tree?
+ * Structured = genesis-style `form_fields`, pocketpaw `review_rows`, or
+ * `data.items` / `data.stats`. Anything else (flow steps with only a `ui`
+ * tree) is raw-ui.
+ */
+export function resolveLayoutMode(spec) {
+    const s = spec;
+    const hasFormFields = Array.isArray(s.form_fields) && s.form_fields.length > 0;
+    const hasReviewRows = Array.isArray(s.review_rows) && s.review_rows.length > 0;
+    const hasItems = !!s.data &&
+        typeof s.data === 'object' &&
+        ((Array.isArray(s.data.items) && s.data.items.length > 0) ||
+            (Array.isArray(s.data.stats) && s.data.stats.length > 0));
+    return hasFormFields || hasReviewRows || hasItems ? 'data' : 'raw-ui';
+}
+/**
+ * Build summary rows from the flow's accumulated context for a confirm step that
+ * carries no structured data of its own. Mirrors genesis's confirm fallback:
+ * turns each `<flowId>_selection` into a labelled "Goal: …" style row. Pure —
+ * `context` is handed in by FlowRunner from the executor; no executor access here.
+ */
+export function summaryItemsFromContext(context) {
+    if (!context)
+        return [];
+    const rows = [];
+    const formatLabel = (key) => key
+        .replace(/_selection$/, '')
+        .replace(/_formData$/, '')
+        .replace(/_/g, ' ')
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+    for (const [key, value] of Object.entries(context)) {
+        if (value == null)
+            continue;
+        if (!key.endsWith('_selection') && !key.endsWith('_formData'))
+            continue;
+        let display = '';
+        if (typeof value === 'string' || typeof value === 'number') {
+            display = String(value);
+        }
+        else if (typeof value === 'object') {
+            const v = value;
+            display = asText(v.label ?? v.title ?? v.name ?? v.id ?? Object.values(v)[0]);
+        }
+        if (display)
+            rows.push({ title: formatLabel(key), subtitle: display });
+    }
+    return rows;
+}
+/**
+ * The adapter: map a UniversalSpec (+ optional flow context) to a LayoutInput.
+ * This is the ONLY place that knows how ripple's spec shape feeds a layout.
+ */
+export function toLayoutInput(spec, context) {
+    const s = spec;
+    const mode = resolveLayoutMode(spec);
+    let items = [];
+    if (mode === 'data') {
+        if (Array.isArray(s.review_rows) && s.review_rows.length > 0) {
+            // pocketpaw confirm contract: review_rows [{label, value}] → summary rows.
+            // SummaryLayout reads `item.label` and `item.value` (via rowLabel/rowValue),
+            // so we surface them directly with the `label`/`subtitle` shape the layout
+            // understands regardless of the generic field mapping.
+            items = s.review_rows.map((r) => ({
+                title: r.label,
+                subtitle: asText(r.value),
+                label: r.label,
+                value: asText(r.value)
+            }));
+        }
+        else {
+            items = s.data?.items ?? s.data?.stats ?? [];
+            // A confirm step with no items of its own summarizes the flow context.
+            if (items.length === 0 && (spec.intent === 'confirm' || spec.intent === 'quick_confirm')) {
+                items = summaryItemsFromContext(context);
+            }
+        }
+    }
+    else if (spec.intent === 'confirm' || spec.intent === 'quick_confirm') {
+        // Even in raw-ui mode, a confirm step can show the accumulated summary
+        // ABOVE its raw tree, so the user reviews what they chose.
+        items = summaryItemsFromContext(context);
+    }
+    return {
+        spec,
+        mode,
+        title: spec.title,
+        description: spec.description,
+        items,
+        formFields: s.form_fields ?? [],
+        fields: { ...DEFAULT_FIELDS, ...(s.fields ?? {}) },
+        meta: getLayoutMetadata(s)
+    };
+}

package/dist/intent/layout-engine.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @file layout-engine.ts
+ * @description Determines the best layout for an IntentSpec based on
+ * intent type, data shape, and display hints.
+ *
+ * This is the "smart" part of the system that makes layout decisions
+ * so the AI doesn't have to specify exact layouts.
+ *
+ * @changes
+ *   - 2026-06-07: map the composite + ported display.layout hints
+ *     (comparison/checklist/invoice/report/timeline/table/article) to dedicated
+ *     LayoutType values, so IntentRenderer can route a generic spec to a
+ *     designed composite layout via the hint without a new IntentType. The
+ *     auto-determine switch is unchanged — only explicit hints reach these.
+ *   - 2026-06-08: analyzeData now falls back to `spec.data.stats` when `items`
+ *     is absent (`items ?? stats ?? []`), matching layout-adapter's normalization
+ *     so a stats-only info/dashboard spec analyzes its fields correctly.
+ */
+import type { UniversalSpec } from '@ripple-ui/core';
+type IntentSpec = UniversalSpec & {
+    form_fields?: any[];
+    data?: any;
+    display?: any;
+    fields?: Record<string, string>;
+};
+export type LayoutType = 'card-grid' | 'image-grid' | 'icon-grid' | 'media-grid' | 'list' | 'list-detail' | 'scrollable-list' | 'detail-hero' | 'detail-split' | 'detail-simple' | 'detail' | 'article' | 'workout-player' | 'form-simple' | 'form-sections' | 'form-wizard' | 'search-results' | 'search' | 'summary-card' | 'info-hero' | 'info-grid' | 'action-buttons' | 'table' | 'comparison' | 'checklist' | 'invoice' | 'report' | 'timeline' | 'workspace' | 'dashboard' | 'widget' | 'itinerary' | 'custom';
+export interface LayoutContext {
+    /** Resolved IntentSpec */
+    spec: IntentSpec;
+    /** Number of items in data */
+    itemCount: number;
+    /** Which fields are available in the data */
+    availableFields: Set<string>;
+    /** Device type (future use) */
+    device?: 'mobile' | 'tablet' | 'desktop';
+}
+/**
+ * Analyze the data to understand what fields are available.
+ */
+export declare function analyzeData(spec: IntentSpec): {
+    itemCount: number;
+    availableFields: Set<string>;
+};
+/**
+ * Determine the best layout for an IntentSpec.
+ */
+export declare function determineLayout(spec: IntentSpec): LayoutType;
+export interface LayoutMetadata {
+    /** Layout type */
+    type: LayoutType;
+    /** Number of columns (for grid layouts) */
+    columns: number;
+    /** Whether to show selection indicators */
+    showSelection: boolean;
+    /** Whether to show images */
+    showImages: boolean;
+    /** Whether to show prices */
+    showPrices: boolean;
+    /** Compact mode */
+    compact: boolean;
+}
+/**
+ * Get layout metadata for rendering configuration.
+ */
+export declare function getLayoutMetadata(spec: IntentSpec): LayoutMetadata;
+export {};

package/dist/intent/layout-engine.js

@@ -0,0 +1,247 @@
+/**
+ * @file layout-engine.ts
+ * @description Determines the best layout for an IntentSpec based on
+ * intent type, data shape, and display hints.
+ *
+ * This is the "smart" part of the system that makes layout decisions
+ * so the AI doesn't have to specify exact layouts.
+ *
+ * @changes
+ *   - 2026-06-07: map the composite + ported display.layout hints
+ *     (comparison/checklist/invoice/report/timeline/table/article) to dedicated
+ *     LayoutType values, so IntentRenderer can route a generic spec to a
+ *     designed composite layout via the hint without a new IntentType. The
+ *     auto-determine switch is unchanged — only explicit hints reach these.
+ *   - 2026-06-08: analyzeData now falls back to `spec.data.stats` when `items`
+ *     is absent (`items ?? stats ?? []`), matching layout-adapter's normalization
+ *     so a stats-only info/dashboard spec analyzes its fields correctly.
+ */
+/**
+ * Analyze the data to understand what fields are available.
+ */
+export function analyzeData(spec) {
+    // Handle missing or invalid data
+    if (!spec.data || typeof spec.data !== 'object') {
+        return { itemCount: 0, availableFields: new Set() };
+    }
+    // Fall back to `stats` when `items` is absent, matching layout-adapter's
+    // `s.data?.items ?? s.data?.stats ?? []` so all three agree on the source.
+    const items = spec.data.items ?? spec.data.stats ?? [];
+    const itemCount = items.length;
+    // Collect all unique keys from items
+    const availableFields = new Set();
+    for (const item of items) {
+        if (item && typeof item === 'object') {
+            for (const key of Object.keys(item)) {
+                availableFields.add(key);
+            }
+        }
+    }
+    return { itemCount, availableFields };
+}
+/**
+ * Check if a field is mapped and available in data.
+ */
+function hasField(fields, fieldName, available) {
+    if (!fields)
+        return false;
+    const mappedTo = fields[fieldName];
+    if (!mappedTo || typeof mappedTo !== 'string')
+        return false;
+    return available.has(mappedTo);
+}
+/**
+ * Determine the best layout for an IntentSpec.
+ */
+export function determineLayout(spec) {
+    const { intent, display, fields } = spec;
+    const { itemCount, availableFields } = analyzeData(spec);
+    // If explicit layout specified and not 'auto', use it
+    if (display?.layout && display.layout !== 'auto') {
+        return mapHintToLayout(display.layout, spec);
+    }
+    // Auto-determine based on intent and data
+    switch (intent) {
+        case 'browse':
+            return determineBrowseLayout(spec, itemCount, availableFields);
+        case 'select':
+            return determineSelectLayout(spec, itemCount, availableFields);
+        case 'detail':
+            return determineDetailLayout(spec, availableFields);
+        case 'form':
+            return determineFormLayout(spec);
+        case 'confirm':
+        case 'quick_confirm':
+            // If it has form fields, use a form layout to allow editing
+            if (spec.form_fields && spec.form_fields.length > 0) {
+                return 'form-simple';
+            }
+            return 'summary-card';
+        case 'info':
+            return determineInfoLayout(spec, itemCount);
+        case 'search':
+            return 'search-results';
+        case 'action':
+            return 'action-buttons';
+        case 'workspace':
+            return 'workspace';
+        case 'dashboard':
+            return 'dashboard';
+        case 'widget':
+            return 'widget';
+        case 'itinerary':
+            return 'itinerary';
+        case 'custom':
+            return 'custom';
+        default:
+            return 'list';
+    }
+}
+/**
+ * Map display hint to actual layout type.
+ */
+function mapHintToLayout(hint, spec) {
+    const { availableFields } = analyzeData(spec);
+    const hasImages = hasField(spec.fields, 'image', availableFields);
+    switch (hint) {
+        case 'cards':
+            return hasImages ? 'card-grid' : 'icon-grid';
+        case 'list':
+            return 'list';
+        case 'grid':
+            return hasImages ? 'image-grid' : 'card-grid';
+        case 'masonry':
+            return 'image-grid';
+        case 'carousel':
+            return 'scrollable-list';
+        case 'split':
+            return 'detail-split';
+        case 'table':
+            return 'table';
+        case 'hero':
+            return 'info-hero';
+        case 'itinerary':
+            return 'itinerary';
+        // Composite + ported designed-layout hints (2026-06-07).
+        case 'comparison':
+            return 'comparison';
+        case 'checklist':
+            return 'checklist';
+        case 'invoice':
+            return 'invoice';
+        case 'report':
+            return 'report';
+        case 'timeline':
+            return 'timeline';
+        case 'article':
+            return 'article';
+        default:
+            return 'list';
+    }
+}
+/**
+ * Determine layout for 'browse' intent.
+ */
+function determineBrowseLayout(spec, itemCount, availableFields) {
+    const hasImages = hasField(spec.fields, 'image', availableFields);
+    const hasIcons = hasField(spec.fields, 'icon', availableFields);
+    const hasPrices = hasField(spec.fields, 'price', availableFields);
+    // Many items with images -> image grid
+    if (hasImages && itemCount > 10) {
+        return 'image-grid';
+    }
+    // Products (images + prices) -> card grid
+    if (hasImages && hasPrices) {
+        return 'card-grid';
+    }
+    // Has images -> card grid
+    if (hasImages) {
+        return 'card-grid';
+    }
+    // Icons only -> icon grid
+    if (hasIcons) {
+        return 'icon-grid';
+    }
+    // Text only -> list
+    return 'list';
+}
+/**
+ * Determine layout for 'select' intent.
+ */
+function determineSelectLayout(spec, itemCount, availableFields) {
+    const hasImages = hasField(spec.fields, 'image', availableFields);
+    const hasIcons = hasField(spec.fields, 'icon', availableFields);
+    // Few items with visuals -> cards
+    if (itemCount <= 6 && (hasImages || hasIcons)) {
+        return hasImages ? 'card-grid' : 'icon-grid';
+    }
+    // Many items -> scrollable list
+    if (itemCount > 8) {
+        return 'scrollable-list';
+    }
+    // Default -> list
+    return 'list';
+}
+/**
+ * Determine layout for 'detail' intent.
+ */
+function determineDetailLayout(spec, availableFields) {
+    const hasImages = hasField(spec.fields, 'image', availableFields);
+    const hasDescription = hasField(spec.fields, 'description', availableFields);
+    // Has image -> hero layout
+    if (hasImages) {
+        return 'detail-hero';
+    }
+    // Long content -> simple layout
+    if (hasDescription) {
+        return 'detail-simple';
+    }
+    return 'detail-simple';
+}
+/**
+ * Determine layout for 'form' intent.
+ */
+function determineFormLayout(spec) {
+    const fieldCount = spec.form_fields?.length ?? 0;
+    // Many fields -> sections
+    if (fieldCount > 6) {
+        return 'form-sections';
+    }
+    return 'form-simple';
+}
+/**
+ * Determine layout for 'info' intent.
+ */
+function determineInfoLayout(spec, itemCount) {
+    // Single item -> hero display
+    if (itemCount <= 1) {
+        return 'info-hero';
+    }
+    // Multiple items -> grid
+    return 'info-grid';
+}
+/**
+ * Get layout metadata for rendering configuration.
+ */
+export function getLayoutMetadata(spec) {
+    const layout = determineLayout(spec);
+    const { availableFields } = analyzeData(spec);
+    const hasImages = hasField(spec.fields, 'image', availableFields);
+    const hasPrices = hasField(spec.fields, 'price', availableFields);
+    // Determine columns based on layout
+    let columns = spec.display?.columns ?? 2;
+    if (layout === 'list' || layout === 'scrollable-list') {
+        columns = 1;
+    }
+    else if (layout === 'image-grid') {
+        columns = 3;
+    }
+    return {
+        type: layout,
+        columns,
+        showSelection: spec.intent === 'select',
+        showImages: hasImages && (spec.display?.show_images !== false),
+        showPrices: hasPrices && (spec.display?.show_prices !== false),
+        compact: spec.display?.compact ?? false
+    };
+}