@esheet/renderer 0.0.4-0 → 0.0.4-2

package/dist/lib/EsheetRenderer.d.ts

@@ -0,0 +1,129 @@
+import { default as React } from 'react';
+import { FormResponse, FormStore, UIStore, ValidationError } from '@esheet/core';
+import { FhirQuestionnaireResponse, ResponseExportOptions } from '@esheet/adapters';
+import { RendererTools } from './renderer-tools.js';
+export interface EsheetRendererProps {
+    /** Form definition — accepts FormDefinition, SurveyJS schema, MCP elicitation envelope,
+     *  or any of the above as a JSON/YAML string. Auto-detected and converted internally.
+     *  Set `strict` to disable auto-conversion and require a valid FormDefinition directly. */
+    formDataInput: unknown;
+    /** Additional CSS classes for root container */
+    className?: string;
+    /** Initial form responses (pre-fill data) */
+    initialResponses?: FormResponse;
+    /** When true, allows `dangerouslyAllowJS: true` in the loaded schema to take effect —
+     *  enabling field calculations and `conditionType: 'js'` conditions.
+     *  When `false` (default), dangerous JS never executes regardless of schema content.
+     *  Only set to `true` when you fully control and trust the form schemas being rendered. */
+    allowDangerousJS?: boolean;
+    /** When true, disables auto-detection of MCP/SurveyJS formats.
+     *  Only accepts a valid eSheet FormDefinition (or JSON/YAML string thereof). */
+    strict?: boolean;
+    /** Called after the form definition has been parsed and loaded into the store. */
+    onReady?: () => void;
+    /**
+     * Called once after the renderer mounts, providing a narrow `RendererTools`
+     * facade for MCP / AI tool integrations.
+     */
+    onRendererToolsReady?: (tools: RendererTools) => void;
+    /**
+     * When provided, a submit button is rendered at the bottom of the form.
+     * Called with the form response after all hard errors pass.
+     * If soft-required fields are unanswered, a bypass popup is shown first.
+     */
+    onSubmit?: (response: FormResponse) => void;
+    /** Label for the submit button. Defaults to `'Submit'`. */
+    submitLabel?: string;
+    /**
+     * Enable touch-optimized mode with larger touch targets.
+     * - `true`: Always enable touch mode
+     * - `false`: Never enable touch mode (CSS media query still applies)
+     * - `'auto'`: Enable based on viewport width (<980px) via JavaScript
+     * - `undefined`: Rely on CSS media query only (default)
+     */
+    touchMode?: boolean | 'auto';
+    /**
+     * Called when touch mode changes (via auto-detection or programmatic toggle).
+     * Useful for syncing external UI with the renderer's touch state.
+     */
+    onTouchModeChange?: (enabled: boolean) => void;
+}
+/** Response format options for getResponse() */
+export type ResponseFormat = 'native' | 'fhir';
+/** Options for getResponse() */
+export interface GetResponseOptions {
+    /** Output format: 'native' (default) or 'fhir' (FHIR QuestionnaireResponse) */
+    format?: ResponseFormat;
+    /** FHIR export options (required when format is 'fhir') */
+    fhir?: Omit<ResponseExportOptions, 'questionnaireUrl'> & {
+        /** Canonical URL of the questionnaire. Falls back to form._sourceData metadata if available. */
+        questionnaireUrl?: string;
+    };
+}
+/** Return type for getResponse() — varies by format */
+export type GetResponseResult<T extends ResponseFormat = 'native'> = T extends 'fhir' ? FhirQuestionnaireResponse : FormResponse;
+export interface EsheetRendererHandle {
+    /** Get current form responses */
+    getRawResponse: () => FormResponse;
+    /**
+     * Get form responses in the specified format.
+     *
+     * @param options - Format and export options
+     * @returns Native FormResponse or FHIR QuestionnaireResponse
+     *
+     * @example
+     * ```ts
+     * // Native format (default)
+     * const native = ref.current.getResponse();
+     *
+     * // FHIR QuestionnaireResponse
+     * const fhir = ref.current.getResponse({
+     *   format: 'fhir',
+     *   fhir: {
+     *     questionnaireUrl: 'http://example.org/Questionnaire/my-form',
+     *     status: 'completed',
+     *   }
+     * });
+     * ```
+     */
+    getResponse: <T extends ResponseFormat = 'native'>(options?: GetResponseOptions & {
+        format?: T;
+    }) => GetResponseResult<T>;
+    /** Get form store instance */
+    getFormStore: () => FormStore;
+    /** Get UI store instance */
+    getUIStore: () => UIStore;
+    /** Get validated form responses (returns null if invalid) */
+    getValidResponse: () => {
+        response: FormResponse | null;
+        errors: ValidationError[];
+    };
+    /** Returns true if touch mode is currently enabled */
+    isTouchModeEnabled: () => boolean;
+    /** Toggle touch mode on/off. Only works when touchMode prop is 'auto' or undefined. Overrides auto-detection. */
+    setTouchMode: (enabled: boolean) => void;
+    /** Reset to auto-detection mode (clears manual override). Only works when touchMode='auto'. */
+    resetTouchMode: () => void;
+}
+/**
+ * EsheetRenderer - Read-only questionnaire form renderer
+ *
+ * Renders a form in fill-out mode with conditional visibility logic.
+ * Reuses all field components from @esheet/fields.
+ *
+ * @example
+ * ```tsx
+ * const rendererRef = useRef<EsheetRendererHandle>(null);
+ *
+ * <EsheetRenderer
+ *   formData={myFormDefinition}
+ *   initialResponses={{ field1: 'answer' }}
+ *   ref={rendererRef}
+ * />
+ *
+ * // Later: get responses
+ * const responses = rendererRef.current?.getRawResponse();
+ * ```
+ */
+export declare const EsheetRenderer: React.ForwardRefExoticComponent<EsheetRendererProps & React.RefAttributes<EsheetRendererHandle>>;
+//# sourceMappingURL=EsheetRenderer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EsheetRenderer.d.ts","sourceRoot":"","sources":["../../src/lib/EsheetRenderer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAY9E,MAAM,WAAW,mBAAmB;IAClC;;+FAE2F;IAC3F,aAAa,EAAE,OAAO,CAAC;IACvB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,YAAY,CAAC;IAChC;;;+FAG2F;IAC3F,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;oFACgF;IAChF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACtD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5C,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAChD;AAMD,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE/C,gCAAgC;AAChC,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,kBAAkB,CAAC,GAAG;QACvD,gGAAgG;QAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAED,uDAAuD;AACvD,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,cAAc,GAAG,QAAQ,IAC/D,CAAC,SAAS,MAAM,GAAG,yBAAyB,GAAG,YAAY,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,cAAc,EAAE,MAAM,YAAY,CAAC;IACnC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAAW,EAAE,CAAC,CAAC,SAAS,cAAc,GAAG,QAAQ,EAC/C,OAAO,CAAC,EAAE,kBAAkB,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,KAC1C,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAC1B,8BAA8B;IAC9B,YAAY,EAAE,MAAM,SAAS,CAAC;IAC9B,4BAA4B;IAC5B,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM;QACtB,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;QAC9B,MAAM,EAAE,eAAe,EAAE,CAAC;KAC3B,CAAC;IACF,sDAAsD;IACtD,kBAAkB,EAAE,MAAM,OAAO,CAAC;IAClC,iHAAiH;IACjH,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,+FAA+F;IAC/F,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,cAAc,kGA+BzB,CAAC"}

package/dist/lib/components/FieldNode.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+import { FormStore, UIStore } from '@esheet/core';
+export interface FieldNodeProps {
+    id: string;
+    form: FormStore;
+    ui: UIStore;
+    /** Nesting depth for visual styling (default: 0) */
+    depth?: number;
+}
+/**
+ * FieldNode - Renders a single field or section with recursive children
+ *
+ * Looks up the field component from the registry and passes field props.
+ * For sections, recursively renders visible children.
+ */
+export declare const FieldNode: React.NamedExoticComponent<FieldNodeProps>;
+//# sourceMappingURL=FieldNode.d.ts.map

package/dist/lib/components/FieldNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldNode.d.ts","sourceRoot":"","sources":["../../../src/lib/components/FieldNode.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAuB,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5E,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;IACZ,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,4CAoLpB,CAAC"}

package/dist/lib/components/RendererBody.d.ts

@@ -0,0 +1,14 @@
+import { FormStore, UIStore } from '@esheet/core';
+export interface RendererBodyProps {
+    form: FormStore;
+    ui: UIStore;
+}
+/**
+ * RendererBody - Iterates over visible root fields and renders them
+ *
+ * Respects conditional visibility logic from form store.
+ * Only renders fields where isVisible() returns true.
+ * Sections recursively render their visible children.
+ */
+export declare function RendererBody({ form, ui }: RendererBodyProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=RendererBody.d.ts.map

package/dist/lib/components/RendererBody.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RendererBody.d.ts","sourceRoot":"","sources":["../../../src/lib/components/RendererBody.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,iBAAiB,2CAyD3D"}

package/dist/lib/components/index.d.ts

@@ -0,0 +1,3 @@
+export { RendererBody } from './RendererBody.js';
+export { FieldNode } from './FieldNode.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/lib/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useRendererInit } from './useRendererInit.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/lib/hooks/useRendererInit.d.ts

@@ -0,0 +1,12 @@
+import { FormResponse, FormStore, UIStore } from '@esheet/core';
+/**
+ * Initialize renderer with form definition.
+ *
+ * Auto-detects and converts the following input formats:
+ * - eSheet FormDefinition (object or JSON/YAML string)
+ * - FHIR R4 Questionnaire resource
+ * - MCP elicitation/create envelope
+ * - SurveyJS schema (has top-level `pages` or `elements` array)
+ */
+export declare function useRendererInit(form: FormStore, ui: UIStore, formData: unknown, initialResponses?: FormResponse, onValidationError?: (errors: string[]) => void, strict?: boolean, onReady?: () => void, allowDangerousJS?: boolean): void;
+//# sourceMappingURL=useRendererInit.d.ts.map

package/dist/lib/hooks/useRendererInit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRendererInit.d.ts","sourceRoot":"","sources":["../../../src/lib/hooks/useRendererInit.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,OAAO,EACb,MAAM,cAAc,CAAC;AAYtB;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EACf,EAAE,EAAE,OAAO,EACX,QAAQ,EAAE,OAAO,EACjB,gBAAgB,CAAC,EAAE,YAAY,EAC/B,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,EAC9C,MAAM,UAAQ,EACd,OAAO,CAAC,EAAE,MAAM,IAAI,EACpB,gBAAgB,UAAQ,GACvB,IAAI,CAyFN"}

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

@@ -0,0 +1,7 @@
+export { executeToolCall } from './tool-executor.js';
+export { RENDERER_TOOL_DEFINITIONS } from './tool-definitions.js';
+export { RENDERER_SYSTEM_PROMPT } from './system-prompt.js';
+export type { ToolDefinition } from './tool-definitions.js';
+export { useRendererMcpToolHandler } from './useRendererToolBridge.js';
+export type { UseRendererMcpToolHandlerOptions } from './useRendererToolBridge.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/lib/mcp/system-prompt.d.ts

@@ -0,0 +1,2 @@
+export declare const RENDERER_SYSTEM_PROMPT: string;
+//# sourceMappingURL=system-prompt.d.ts.map

package/dist/lib/mcp/system-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../../src/lib/mcp/system-prompt.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,QAwByC,CAAC"}

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

@@ -0,0 +1,10 @@
+export interface ToolDefinition {
+    type: string;
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export declare const RENDERER_TOOL_DEFINITIONS: readonly ToolDefinition[];
+//# sourceMappingURL=tool-definitions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-definitions.d.ts","sourceRoot":"","sources":["../../../src/lib/mcp/tool-definitions.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAED,eAAO,MAAM,yBAAyB,EAAE,SAAS,cAAc,EAmG9D,CAAC"}

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

@@ -0,0 +1,5 @@
+import { 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,CAsBlC"}

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

@@ -0,0 +1,28 @@
+import { 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/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":"AAkCA,wBAAgB,sCAAsC,IAAI,IAAI,CA8B7D"}

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

@@ -0,0 +1,56 @@
+import { FormStore, ValidationError } from '@esheet/core';
+import { 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.d.ts

@@ -0,0 +1,49 @@
+import { FieldDefinition, FormDefinition, FormResponse } from '@esheet/core';
+export interface RenderTreeOptions {
+    /** Include fields that resolve to invisible (default: false). */
+    includeHidden?: boolean;
+    /**
+     * Opt-in to allow dangerous JS execution. When `false` (default), any
+     * `dangerouslyAllowJS: true` in the schema is ignored — JS conditions always
+     * return `false`. Only set to `true` when you trust the schema content.
+     */
+    allowDangerousJS?: 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;
+    /** Computed value from setValue effects (if any). */
+    computedValue?: string | number | null;
+    /** Renderable child nodes (sections only). */
+    children: RenderFieldNode[];
+}
+/**
+ * Build a render tree from form definition + responses.
+ *
+ * Sections are represented as nodes with nested `children`.
+ * Computed values from setValue effects are included in computedValue field.
+ */
+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;
+/**
+ * Apply computed values from a render tree to a responses object.
+ *
+ * Iterates through the render tree and merges any computed values
+ * (from setValue effects) into the responses map. Wraps string/number
+ * values as FieldResponse answer objects.
+ *
+ * @param tree - Render tree with computed values.
+ * @param responses - Base responses object to merge into (is modified in-place).
+ * @returns Updated responses object.
+ */
+export declare function applyComputedValues(tree: RenderFieldNode[], responses?: FormResponse): FormResponse;
+//# 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,EAIL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EAElB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;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,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACvC,8CAA8C;IAC9C,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,UAAU,EAAE,cAAc,EAC1B,SAAS,GAAE,YAAiB,EAC5B,OAAO,GAAE,iBAAsB,GAC9B,eAAe,EAAE,CAyDnB;AAED,sEAAsE;AACtE,eAAO,MAAM,eAAe,iBAAW,CAAC;AAExC;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,eAAe,EAAE,EACvB,SAAS,GAAE,YAAiB,GAC3B,YAAY,CAgBd"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esheet/renderer",
-  "version": "0.0.4-0",
+  "version": "0.0.4-2",
   "repository": {
     "type": "git",
     "url": "https://github.com/mieweb/eSheet"
@@ -38,9 +38,9 @@
     ]
   },
   "dependencies": {
-    "@esheet/adapters": "0.0.3",
-    "@esheet/core": "0.0.3",
-    "@esheet/fields": "0.0.3",
+    "@esheet/adapters": "0.0.4-2",
+    "@esheet/core": "0.0.4-2",
+    "@esheet/fields": "0.0.4-2",
     "js-yaml": "^4.1.0"
   },
   "peerDependencies": {