@esheet/renderer 0.0.3 → 0.0.4-1

package/dist/lib/mcp/tool-definitions.js

@@ -0,0 +1,66 @@
+export const RENDERER_TOOL_DEFINITIONS = [
+    {
+        type: 'function',
+        function: {
+            name: 'get_form',
+            description: 'Returns visible fields split into filled vs unfilled. Response: {formId, totalFields, filledCount, unfilledFields (full details), filledFieldIds (just IDs)}. Use unfilledFields to see what needs filling.\n\nFILL LOOP PATTERN:\n1. Call get_form — fill every field in unfilledFields using fill_field.\n2. Call get_form again. If new fields appeared in unfilledFields (revealed by conditional logic), fill those too.\n3. Repeat until unfilledFields is empty.\n\nNever assume you are done after a single pass — conditional logic frequently reveals new fields.',
+            parameters: { type: 'object', properties: {} },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_form_raw',
+            description: 'Returns ALL fields in the form regardless of visibility, conditional rules, or enabled state. Use this to see the full form schema.',
+            parameters: { type: 'object', properties: {} },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_responses',
+            description: 'Get the current raw response values for all fields.',
+            parameters: { type: 'object', properties: {} },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_valid_response',
+            description: 'Run form validation. Returns the full response object if all required fields pass, or null plus field-level errors if validation fails. Call this before submitting.',
+            parameters: { type: 'object', properties: {} },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'fill_field',
+            description: 'Set a response value for ONE visible field. Returns { result, filledCount, unfilledFields } where unfilledFields contains ONLY the fields still needing values (with full details including options/valueFormat). You are done when unfilledFields is empty.\n\nField type rules:\n- radio/dropdown/boolean/rating/slider: pass a single string matching one of the options values\n- check/multiselectdropdown: pass an array of strings matching option values\n- ranking: pass an ordered array of option value strings representing the desired rank order\n- multitext: pass an array of strings, one per option slot in order\n- singlematrix: pass an object { "Row Label": "Column Label" } for each row\n- multimatrix: pass an object { "Row Label": ["Col1", "Col2"] } for each row\n- text: use the valueFormat from the field\'s schema (e.g. YYYY-MM-DD for date, YYYY-MM-DDTHH:mm for datetime-local, YYYY-MM for month, HH:mm for time). Wrong formats are rejected with an error.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    fieldId: { type: 'string' },
+                    fieldQuestion: { type: 'string' },
+                    value: {},
+                },
+                required: ['value'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'clear_responses',
+            description: 'Clear all current form responses.',
+            parameters: { type: 'object', properties: {} },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_form_tree',
+            description: 'Get the full rendered field tree including visibility, enabled, and required state for each field given current responses.',
+            parameters: { type: 'object', properties: {} },
+        },
+    },
+];

package/dist/lib/mcp/tool-executor.d.ts

@@ -0,0 +1,5 @@
+import type { RendererTools } from '../renderer-tools.js';
+type ToolArgs = Record<string, unknown>;
+export declare function executeToolCall(toolName: string, args: ToolArgs, tools: RendererTools): string | Record<string, unknown>;
+export {};
+//# sourceMappingURL=tool-executor.d.ts.map

package/dist/lib/mcp/tool-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-executor.d.ts","sourceRoot":"","sources":["../../../src/lib/mcp/tool-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExC,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,aAAa,GACnB,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBlC"}

package/dist/lib/mcp/tool-executor.js

@@ -0,0 +1,55 @@
+export function executeToolCall(toolName, args, tools) {
+    switch (toolName) {
+        case 'get_form':
+            return getFormOptimized(tools);
+        case 'get_form_raw':
+            return tools.getFormRaw();
+        case 'get_responses':
+            return tools.getResponses();
+        case 'get_valid_response':
+            return tools.getValidResponse();
+        case 'fill_field':
+            return fillField(args, tools);
+        case 'clear_responses':
+            tools.clearResponses();
+            return 'Responses cleared';
+        case 'get_form_tree':
+            return { fields: tools.getFormTree() };
+        default:
+            return `Unknown tool: ${toolName}`;
+    }
+}
+/** Optimized get_form: returns full details only for unfilled fields to reduce token usage. */
+function getFormOptimized(tools) {
+    const form = tools.getForm();
+    const filledFields = form.fields.filter((f) => f.hasValue);
+    const unfilledFields = form.fields.filter((f) => !f.hasValue);
+    return {
+        formId: form.formId,
+        totalFields: form.fieldCount,
+        filledCount: filledFields.length,
+        // Only unfilled fields need full details (options, questions, etc.)
+        unfilledFields,
+        // Filled fields: just IDs for reference
+        filledFieldIds: filledFields.map((f) => f.id),
+    };
+}
+function fillField(args, tools) {
+    const fieldId = tools.resolveFieldId(args['fieldId'], args['fieldQuestion']);
+    if (!fieldId)
+        return 'Error: field not found — provide fieldId or fieldQuestion';
+    const result = tools.fillField(fieldId, args['value']);
+    if (typeof result === 'string')
+        return result; // format validation error
+    if (!result)
+        return `Error: field "${fieldId}" is not currently visible — call get_form to see the current visible fields`;
+    const form = tools.getForm();
+    // Return only unfilled fields with full details (token optimization)
+    const filledFields = form.fields.filter((f) => f.hasValue);
+    const unfilledFields = form.fields.filter((f) => !f.hasValue);
+    return {
+        result: `Field "${fieldId}" updated`,
+        filledCount: filledFields.length,
+        unfilledFields,
+    };
+}

package/dist/lib/mcp/useRendererToolBridge.d.ts

@@ -0,0 +1,28 @@
+import type { RendererTools } from '../renderer-tools.js';
+export interface UseRendererMcpToolHandlerOptions {
+    /**
+     * The DOM element to listen on for tool-call events.
+     * Pass `document` to listen globally, or a specific element to scope it.
+     */
+    target?: EventTarget;
+    /**
+     * The event name to listen for, e.g. `'ozwell-tool-call'`.
+     */
+    eventName: string;
+}
+/**
+ * Listens for AI tool-call events on a target element and dispatches them to
+ * the renderer's MCP tool executor. Returns the `onRendererToolsReady` callback
+ * to pass to `<EsheetRenderer>`.
+ *
+ * @example – default (listens on document)
+ * const onRendererToolsReady = useRendererMcpToolHandler({ eventName: 'ozwell-tool-call' });
+ * <EsheetRenderer onRendererToolsReady={onRendererToolsReady} ... />
+ *
+ * @example – scoped to a container element
+ * const ref = React.useRef<HTMLDivElement>(null);
+ * const onRendererToolsReady = useRendererMcpToolHandler({ target: ref.current ?? undefined, eventName: 'ozwell-tool-call' });
+ * <div ref={ref}><EsheetRenderer onRendererToolsReady={onRendererToolsReady} ... /></div>
+ */
+export declare function useRendererMcpToolHandler(options: UseRendererMcpToolHandlerOptions): (tools: RendererTools) => void;
+//# sourceMappingURL=useRendererToolBridge.d.ts.map

package/dist/lib/mcp/useRendererToolBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRendererToolBridge.d.ts","sourceRoot":"","sources":["../../../src/lib/mcp/useRendererToolBridge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gCAAgC,GACxC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAgDhC"}

package/dist/lib/mcp/useRendererToolBridge.js

@@ -0,0 +1,53 @@
+import React from 'react';
+import { executeToolCall } from './tool-executor.js';
+/**
+ * Listens for AI tool-call events on a target element and dispatches them to
+ * the renderer's MCP tool executor. Returns the `onRendererToolsReady` callback
+ * to pass to `<EsheetRenderer>`.
+ *
+ * @example – default (listens on document)
+ * const onRendererToolsReady = useRendererMcpToolHandler({ eventName: 'ozwell-tool-call' });
+ * <EsheetRenderer onRendererToolsReady={onRendererToolsReady} ... />
+ *
+ * @example – scoped to a container element
+ * const ref = React.useRef<HTMLDivElement>(null);
+ * const onRendererToolsReady = useRendererMcpToolHandler({ target: ref.current ?? undefined, eventName: 'ozwell-tool-call' });
+ * <div ref={ref}><EsheetRenderer onRendererToolsReady={onRendererToolsReady} ... /></div>
+ */
+export function useRendererMcpToolHandler(options) {
+    const { target, eventName } = options;
+    const toolsRef = React.useRef(null);
+    const onRendererToolsReady = React.useCallback((tools) => {
+        toolsRef.current = tools;
+    }, []);
+    React.useEffect(() => {
+        const el = target ?? document;
+        function onToolCall(e) {
+            const { name: rawName, arguments: args, respond, } = e.detail;
+            // Strip 'postMessage:' prefix if present (added by Ozwell widget internally)
+            const name = rawName.replace(/^postMessage:/, '');
+            if (!toolsRef.current) {
+                respond({ success: false, message: 'Renderer not ready' });
+                return;
+            }
+            const toResponse = (r) => typeof r === 'string' ? { result: r } : r;
+            try {
+                const result = executeToolCall(name, args, toolsRef.current);
+                if (result instanceof Promise) {
+                    result
+                        .then((r) => respond(toResponse(r)))
+                        .catch((err) => respond({ error: String(err) }));
+                }
+                else {
+                    respond(toResponse(result));
+                }
+            }
+            catch (err) {
+                respond({ error: String(err) });
+            }
+        }
+        el.addEventListener(eventName, onToolCall);
+        return () => el.removeEventListener(eventName, onToolCall);
+    }, [target, eventName]);
+    return onRendererToolsReady;
+}

package/dist/lib/register-defaults.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureDefaultFieldComponentsRegistered(): void;
+//# sourceMappingURL=register-defaults.d.ts.map

package/dist/lib/register-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-defaults.d.ts","sourceRoot":"","sources":["../../src/lib/register-defaults.ts"],"names":[],"mappings":"AAgCA,wBAAgB,sCAAsC,IAAI,IAAI,CA4B7D"}

package/dist/lib/register-defaults.js

@@ -0,0 +1,36 @@
+// ---------------------------------------------------------------------------
+// Built-in field component registration for the renderer
+// ---------------------------------------------------------------------------
+// Called from EsheetRenderer runtime path so consumers get built-in defaults
+// without relying on package entry side-effect imports.
+// ---------------------------------------------------------------------------
+import { registerFieldComponents } from '@esheet/fields';
+import { TextField, LongTextField, MultiTextField, RadioField, CheckField, BooleanField, DropdownField, MultiSelectDropdownField, RatingField, RankingField, SliderField, SingleMatrixField, MultiMatrixField, SectionField, SignatureField, DiagramField, ImageField, HtmlField, DisplayField, } from '@esheet/fields';
+let defaultsRegistered = false;
+export function ensureDefaultFieldComponentsRegistered() {
+    if (defaultsRegistered) {
+        return;
+    }
+    registerFieldComponents({
+        text: TextField,
+        longtext: LongTextField,
+        multitext: MultiTextField,
+        radio: RadioField,
+        check: CheckField,
+        boolean: BooleanField,
+        dropdown: DropdownField,
+        multiselectdropdown: MultiSelectDropdownField,
+        rating: RatingField,
+        ranking: RankingField,
+        slider: SliderField,
+        singlematrix: SingleMatrixField,
+        multimatrix: MultiMatrixField,
+        section: SectionField,
+        signature: SignatureField,
+        diagram: DiagramField,
+        image: ImageField,
+        html: HtmlField,
+        display: DisplayField,
+    });
+    defaultsRegistered = true;
+}

package/dist/lib/renderer-tools.d.ts

@@ -0,0 +1,56 @@
+import { type FormStore, type ValidationError } from '@esheet/core';
+import type { RenderFieldNode } from './renderer.js';
+/** Summary of a single field, suitable for AI context. */
+export interface RendererFieldSummary {
+    id: string;
+    fieldType: string;
+    /** For text fields: the HTML input type (e.g. 'date', 'datetime-local', 'month', 'time', 'email', 'number'). Use the correct format when filling this field. */
+    inputType?: string;
+    /** Required value format for structured input types. Use this exact format when calling fill_field. */
+    valueFormat?: string;
+    question: string | undefined;
+    required: boolean;
+    /** True if this field already has a response value. False means it is still empty and needs to be filled. */
+    hasValue: boolean;
+    /** Available option values for selection fields (radio, check, dropdown, etc.). Only present when the field has options. */
+    options?: string[];
+    /** Available row labels for matrix fields. Only present for singlematrix / multimatrix. */
+    rows?: string[];
+    /** Available column labels for matrix fields. Only present for singlematrix / multimatrix. */
+    columns?: string[];
+}
+/**
+ * Narrow interface exposed to MCP / AI tools via `onRendererToolsReady`.
+ * Read-oriented: inspect responses, fill responses, and query the render tree.
+ */
+export interface RendererTools {
+    /** Currently visible, fillable fields with their available options. */
+    getForm: () => {
+        formId: string;
+        fieldCount: number;
+        fields: RendererFieldSummary[];
+    };
+    /** All fields in the form regardless of visibility, rules, or enabled state. */
+    getFormRaw: () => {
+        formId: string;
+        fieldCount: number;
+        fields: RendererFieldSummary[];
+    };
+    /** Get current raw responses keyed by field ID. */
+    getResponses: () => Record<string, unknown>;
+    /** Get validated responses — returns null if validation fails. */
+    getValidResponse: () => {
+        response: Record<string, unknown> | null;
+        errors: ValidationError[];
+    };
+    /** Set a response value for one visible field. Returns true on success, false if field not found/visible, or an error string if the value format is invalid. */
+    fillField: (fieldId: string, value: unknown) => boolean | string;
+    /** Clear all responses. */
+    clearResponses: () => void;
+    /** Full render tree with visibility/enabled/required per field. */
+    getFormTree: () => RenderFieldNode[];
+    /** Find a field ID by exact ID or partial question match. */
+    resolveFieldId: (fieldId?: string, fieldQuestion?: string) => string | undefined;
+}
+export declare function createRendererTools(formStore: FormStore): RendererTools;
+//# sourceMappingURL=renderer-tools.d.ts.map

package/dist/lib/renderer-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer-tools.d.ts","sourceRoot":"","sources":["../../src/lib/renderer-tools.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,gKAAgK;IAChK,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uGAAuG;IACvG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,6GAA6G;IAC7G,QAAQ,EAAE,OAAO,CAAC;IAClB,4HAA4H;IAC5H,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,OAAO,EAAE,MAAM;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,oBAAoB,EAAE,CAAC;KAChC,CAAC;IACF,gFAAgF;IAChF,UAAU,EAAE,MAAM;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,oBAAoB,EAAE,CAAC;KAChC,CAAC;IACF,mDAAmD;IACnD,YAAY,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,kEAAkE;IAClE,gBAAgB,EAAE,MAAM;QACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACzC,MAAM,EAAE,eAAe,EAAE,CAAC;KAC3B,CAAC;IACF,gKAAgK;IAChK,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,MAAM,CAAC;IACjE,2BAA2B;IAC3B,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,mEAAmE;IACnE,WAAW,EAAE,MAAM,eAAe,EAAE,CAAC;IACrC,6DAA6D;IAC7D,cAAc,EAAE,CACd,OAAO,CAAC,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,KACnB,MAAM,GAAG,SAAS,CAAC;CACzB;AAkBD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,GAAG,aAAa,CA4XvE"}

package/dist/lib/renderer-tools.js

@@ -0,0 +1,305 @@
+// ---------------------------------------------------------------------------
+// RendererTools — narrow facade for MCP / AI tool callers only.
+// ---------------------------------------------------------------------------
+import { validateForm, } from '@esheet/core';
+import { renderer } from './renderer.js';
+const NON_INPUT = new Set(['section', 'html', 'display', 'image', 'diagram']);
+/** Flatten the render tree into only visible, fillable leaf nodes. */
+function flattenVisible(nodes) {
+    const result = [];
+    for (const node of nodes) {
+        if (!node.visible)
+            continue;
+        if (node.children.length > 0) {
+            result.push(...flattenVisible(node.children));
+        }
+        else if (!NON_INPUT.has(node.definition.fieldType)) {
+            result.push(node);
+        }
+    }
+    return result;
+}
+export function createRendererTools(formStore) {
+    function resolveFieldId(fieldId, fieldQuestion) {
+        if (fieldId)
+            return fieldId;
+        if (fieldQuestion) {
+            const q = fieldQuestion.toLowerCase();
+            const { normalized } = formStore.getState();
+            for (const id of Object.keys(normalized.byId)) {
+                const question = normalized.byId[id].definition.question;
+                if (question?.toLowerCase().includes(q))
+                    return id;
+            }
+        }
+        return undefined;
+    }
+    function getCurrentRenderTree() {
+        const { formId, responses } = formStore.getState();
+        const definition = formStore.getState().hydrateDefinition();
+        if (!definition)
+            return [];
+        return renderer({ ...definition, id: formId }, responses);
+    }
+    const INPUT_TYPE_FORMAT = {
+        date: 'YYYY-MM-DD',
+        'datetime-local': 'YYYY-MM-DDTHH:mm',
+        month: 'YYYY-MM',
+        time: 'HH:mm',
+    };
+    function toFieldSummary(id, def, required) {
+        const response = formStore.getState().responses[id];
+        const hasValue = response != null &&
+            Object.values(response).some((v) => v != null &&
+                v !== '' &&
+                !(Array.isArray(v) && v.length === 0) &&
+                !(typeof v === 'object' &&
+                    !Array.isArray(v) &&
+                    Object.keys(v).length === 0));
+        const summary = {
+            id,
+            fieldType: def.fieldType,
+            question: def.question,
+            required: required ?? def.required ?? false,
+            hasValue,
+        };
+        if (def.inputType)
+            summary.inputType = def.inputType;
+        if (def.inputType && INPUT_TYPE_FORMAT[def.inputType])
+            summary.valueFormat = INPUT_TYPE_FORMAT[def.inputType];
+        if (def.options && def.options.length > 0)
+            summary.options = def.options.map((o) => o.value);
+        if (def.rows && def.rows.length > 0)
+            summary.rows = def.rows.map((r) => r.value);
+        if (def.columns && def.columns.length > 0)
+            summary.columns = def.columns.map((c) => c.value);
+        return summary;
+    }
+    /**
+     * Normalize and validate a text value for a given inputType.
+     * Returns the normalized string on success, or null if the value cannot
+     * be coerced into a valid format (caller should reject the fill).
+     */
+    function normalizeTextValue(value, inputType) {
+        if (!value)
+            return value;
+        switch (inputType) {
+            case 'date': {
+                if (/^\d{4}-\d{2}-\d{2}$/.test(value))
+                    return value;
+                if (/^\d{4}-\d{2}$/.test(value))
+                    return `${value}-01`;
+                if (/^\d{4}$/.test(value))
+                    return `${value}-01-01`;
+                return null; // not a recognisable date
+            }
+            case 'month': {
+                if (/^\d{4}-\d{2}$/.test(value))
+                    return value;
+                if (/^\d{4}-\d{2}-\d{2}$/.test(value))
+                    return value.slice(0, 7);
+                return null;
+            }
+            case 'datetime-local': {
+                const n = value.replace(' ', 'T');
+                if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(n))
+                    return n;
+                if (/^\d{4}-\d{2}-\d{2}$/.test(n))
+                    return `${n}T00:00`;
+                return null;
+            }
+            case 'time': {
+                if (/^\d{2}:\d{2}$/.test(value))
+                    return value;
+                const match = value.match(/^(\d{1,2}):(\d{2})\s*(AM|PM)$/i);
+                if (match) {
+                    let h = parseInt(match[1], 10);
+                    const m = match[2];
+                    const period = match[3].toUpperCase();
+                    if (period === 'AM' && h === 12)
+                        h = 0;
+                    if (period === 'PM' && h !== 12)
+                        h += 12;
+                    return `${String(h).padStart(2, '0')}:${m}`;
+                }
+                return null;
+            }
+            default:
+                return value;
+        }
+    }
+    function applyFieldValue(fieldId, value, checkVisibility) {
+        const { normalized } = formStore.getState();
+        const node = normalized.byId[fieldId];
+        if (!node)
+            return false;
+        if (checkVisibility) {
+            const visibleIds = new Set(flattenVisible(getCurrentRenderTree()).map((n) => n.id));
+            if (!visibleIds.has(fieldId))
+                return false;
+        }
+        const def = node.definition;
+        let response;
+        if (def.fieldType === 'singlematrix' &&
+            value !== null &&
+            typeof value === 'object') {
+            const rows = def.rows ?? [];
+            const columns = def.columns ?? [];
+            const existing = (formStore.getState().responses[fieldId]?.selected ??
+                {});
+            const selected = {
+                ...existing,
+            };
+            const entries = Array.isArray(value)
+                ? value.map((v, i) => [rows[i]?.value ?? String(i), v])
+                : Object.entries(value);
+            for (const [rowKey, colVal] of entries) {
+                const row = rows.find((r) => r.value.toLowerCase() === rowKey.toLowerCase() || r.id === rowKey);
+                if (!row)
+                    continue;
+                const colStr = String(colVal);
+                const col = columns.find((c) => c.value.toLowerCase() === colStr.toLowerCase() || c.id === colStr) ?? columns[parseInt(colStr, 10)];
+                if (col)
+                    selected[row.id] = { id: col.id, value: col.value };
+            }
+            response = { selected };
+        }
+        else if (def.fieldType === 'multimatrix' &&
+            value !== null &&
+            typeof value === 'object') {
+            // multimatrix: { selected: Record<rowId, SelectedOption[]> }
+            const rows = def.rows ?? [];
+            const columns = def.columns ?? [];
+            const existing = (formStore.getState().responses[fieldId]?.selected ??
+                {});
+            const selected = {
+                ...existing,
+            };
+            const entries = Array.isArray(value)
+                ? value.map((v, i) => [rows[i]?.value ?? String(i), v])
+                : Object.entries(value);
+            for (const [rowKey, colVals] of entries) {
+                const row = rows.find((r) => r.value.toLowerCase() === rowKey.toLowerCase() || r.id === rowKey);
+                if (!row)
+                    continue;
+                const colValArr = Array.isArray(colVals)
+                    ? colVals
+                    : [colVals];
+                const matched = colValArr
+                    .map((v) => {
+                    const s = String(v);
+                    return columns.find((c) => c.value.toLowerCase() === s.toLowerCase() || c.id === s);
+                })
+                    .filter((c) => c != null);
+                if (matched.length > 0)
+                    selected[row.id] = matched;
+            }
+            response = { selected };
+        }
+        else if (['radio', 'dropdown', 'boolean', 'rating', 'slider'].includes(def.fieldType)) {
+            const opts = def.options ?? [];
+            const match = opts.find((o) => o.value.toLowerCase() === String(value).toLowerCase() ||
+                o.id === value);
+            // For slider/rating, also try matching by numeric index or option value as number
+            const numVal = Number(value);
+            const numMatch = !match && !isNaN(numVal) ? opts[numVal - 1] ?? opts[numVal] : undefined;
+            const resolved = match ?? numMatch;
+            response = resolved
+                ? { selected: { id: resolved.id, value: resolved.value } }
+                : { selected: undefined };
+        }
+        else if (def.fieldType === 'check' ||
+            def.fieldType === 'multiselectdropdown') {
+            const opts = def.options ?? [];
+            const vals = Array.isArray(value) ? value : [value];
+            const matches = opts.filter((o) => vals.some((v) => o.value.toLowerCase() === String(v).toLowerCase() || o.id === v));
+            response = {
+                selected: matches.map((o) => ({ id: o.id, value: o.value })),
+            };
+        }
+        else if (def.fieldType === 'ranking') {
+            // ranking: { selected: SelectedOption[] } in the user-specified order
+            const opts = def.options ?? [];
+            const vals = Array.isArray(value) ? value : [value];
+            const ordered = vals
+                .map((v) => opts.find((o) => o.value.toLowerCase() === String(v).toLowerCase() || o.id === v))
+                .filter((o) => o != null);
+            // append any options not mentioned by the user at the end
+            const mentioned = new Set(ordered.map((o) => o.id));
+            const remaining = opts.filter((o) => !mentioned.has(o.id));
+            response = { selected: [...ordered, ...remaining] };
+        }
+        else if (def.fieldType === 'multitext') {
+            // multitext: { multitextAnswers: Record<optionId, string> }
+            const opts = def.options ?? [];
+            const vals = Array.isArray(value)
+                ? value
+                : typeof value === 'object' && value !== null
+                    ? Object.values(value)
+                    : [value];
+            const multitextAnswers = {};
+            opts.forEach((opt, i) => {
+                if (vals[i] != null)
+                    multitextAnswers[opt.id] = String(vals[i]);
+            });
+            response = { multitextAnswers };
+        }
+        else {
+            if (value == null) {
+                response = { answer: undefined };
+            }
+            else {
+                const normalized = normalizeTextValue(String(value), def.inputType);
+                if (normalized === null) {
+                    const fmt = {
+                        date: 'YYYY-MM-DD',
+                        'datetime-local': 'YYYY-MM-DDTHH:mm',
+                        month: 'YYYY-MM',
+                        time: 'HH:mm',
+                    };
+                    const expected = fmt[def.inputType ?? ''];
+                    return expected
+                        ? `Error: invalid value for inputType "${def.inputType}" — expected format ${expected} (e.g. ${new Date()
+                            .toISOString()
+                            .slice(0, expected.length)
+                            .replace('T', 'T')
+                            .replace(/[^\dT:-]/g, '0')})`
+                        : `Error: invalid value for field`;
+                }
+                response = { answer: normalized };
+            }
+        }
+        formStore.getState().setResponse(fieldId, response);
+        return true;
+    }
+    return {
+        getForm: () => {
+            const { formId } = formStore.getState();
+            const visibleNodes = flattenVisible(getCurrentRenderTree());
+            const fields = visibleNodes.map((node) => toFieldSummary(node.id, node.definition, node.required));
+            return { formId, fieldCount: fields.length, fields };
+        },
+        getFormRaw: () => {
+            const { normalized, formId } = formStore.getState();
+            const fields = Object.keys(normalized.byId)
+                .filter((id) => !NON_INPUT.has(normalized.byId[id].definition.fieldType))
+                .map((id) => toFieldSummary(id, normalized.byId[id].definition));
+            return { formId, fieldCount: fields.length, fields };
+        },
+        getResponses: () => formStore.getState().responses,
+        getValidResponse: () => {
+            const state = formStore.getState();
+            const errors = validateForm(state.normalized, state.responses);
+            return {
+                response: errors.length === 0
+                    ? state.responses
+                    : null,
+                errors,
+            };
+        },
+        fillField: (fieldId, value) => applyFieldValue(fieldId, value, true),
+        clearResponses: () => formStore.getState().resetResponses(),
+        getFormTree: () => getCurrentRenderTree(),
+        resolveFieldId,
+    };
+}

package/dist/lib/renderer.d.ts

@@ -0,0 +1,28 @@
+import { type FieldDefinition, type FormDefinition, type FormResponse } from '@esheet/core';
+export interface RenderTreeOptions {
+    /** Include fields that resolve to invisible (default: false). */
+    includeHidden?: boolean;
+}
+export interface RenderFieldNode {
+    /** Field identifier. */
+    id: string;
+    /** Field definition without nested children. */
+    definition: Omit<FieldDefinition, 'fields'>;
+    /** Computed visible state. */
+    visible: boolean;
+    /** Computed enabled state. */
+    enabled: boolean;
+    /** Computed required state. */
+    required: boolean;
+    /** Renderable child nodes (sections only). */
+    children: RenderFieldNode[];
+}
+/**
+ * Build a render tree from form definition + responses.
+ *
+ * Sections are represented as nodes with nested `children`.
+ */
+export declare function renderer(definition: FormDefinition, responses?: FormResponse, options?: RenderTreeOptions): RenderFieldNode[];
+/** Alias for readability in consumers that prefer explicit naming. */
+export declare const buildRenderTree: typeof renderer;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/lib/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/lib/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;IAC5C,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,+BAA+B;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,UAAU,EAAE,cAAc,EAC1B,SAAS,GAAE,YAAiB,EAC5B,OAAO,GAAE,iBAAsB,GAC9B,eAAe,EAAE,CA2CnB;AAED,sEAAsE;AACtE,eAAO,MAAM,eAAe,iBAAW,CAAC"}