@bbigbang/protocol 0.1.0

package/dist/panel.js

@@ -0,0 +1,2116 @@
+export const DEFAULT_PANEL_PAGE_SIZE = 10;
+export const MIN_PANEL_PAGE_SIZE = 1;
+export const MAX_PANEL_PAGE_SIZE = 50;
+export const MIN_PANEL_REFRESH_INTERVAL_MS = 1000;
+export const MAX_PANEL_REFRESH_INTERVAL_MS = 60_000;
+export const INLINE_ROWS_MAX = 1000;
+export const PANEL_API_JSONL_MAX_URLS = 16;
+export const PANEL_MEDIA_FETCH_CONCURRENCY = 6;
+export const PANEL_MEDIA_REMOTE_FETCH_TIMEOUT_MS = 10_000;
+export const PANEL_IMAGE_MEDIA_MAX_BYTES = 5 * 1024 * 1024;
+export const PANEL_TEXT_MEDIA_MAX_BYTES = 1024 * 1024;
+const PANEL_API_JSONL_LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+const PANEL_API_JSONL_AUTH_PROFILE_RE = /^[A-Za-z0-9_.:-]{1,64}$/u;
+export function normalizePanelApiJsonlAuthProfileName(rawProfile) {
+    const trimmed = rawProfile.trim();
+    if (!PANEL_API_JSONL_AUTH_PROFILE_RE.test(trimmed))
+        return null;
+    return trimmed;
+}
+export function normalizePanelApiJsonlAuthProfileNames(rawProfiles) {
+    const entries = typeof rawProfiles === 'string'
+        ? rawProfiles.split(/[,\s]+/u)
+        : Array.isArray(rawProfiles)
+            ? [...rawProfiles]
+            : [];
+    const seen = new Set();
+    const profiles = [];
+    for (const entry of entries) {
+        if (typeof entry !== 'string')
+            continue;
+        const normalized = normalizePanelApiJsonlAuthProfileName(entry);
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        profiles.push(normalized);
+    }
+    return profiles;
+}
+export function validatePanelApiJsonlAuthProfile(rawAuth, options = {}) {
+    if (rawAuth === undefined || rawAuth === null)
+        return { ok: true, authProfile: null };
+    if (typeof rawAuth !== 'object' || Array.isArray(rawAuth)) {
+        return { ok: false, reason: 'dataset.source.auth must be an object with a profile name.' };
+    }
+    const rawProfile = rawAuth.profile;
+    const profile = typeof rawProfile === 'string' ? normalizePanelApiJsonlAuthProfileName(rawProfile) : null;
+    if (!profile) {
+        return { ok: false, reason: 'dataset.source.auth.profile must be 1-64 chars of letters, numbers, dot, underscore, colon, or dash.' };
+    }
+    const allowedProfiles = normalizePanelApiJsonlAuthProfileNames(options.allowedAuthProfiles);
+    if (!allowedProfiles.includes(profile)) {
+        return { ok: false, reason: 'dataset.source.auth.profile must match an auth profile advertised by the agent node.' };
+    }
+    return { ok: true, authProfile: profile };
+}
+export function normalizePanelApiJsonlAllowedOrigin(rawOrigin) {
+    const trimmed = rawOrigin.trim();
+    if (!trimmed || trimmed.includes('\0') || /[\r\n]/u.test(trimmed))
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return null;
+    if (parsed.username || parsed.password)
+        return null;
+    if ((parsed.pathname && parsed.pathname !== '/') || parsed.search || parsed.hash)
+        return null;
+    return parsed.origin;
+}
+export function normalizePanelApiJsonlAllowedOrigins(rawOrigins) {
+    const entries = typeof rawOrigins === 'string'
+        ? rawOrigins.split(/[,\s]+/u)
+        : Array.isArray(rawOrigins)
+            ? [...rawOrigins]
+            : [];
+    const seen = new Set();
+    const origins = [];
+    for (const entry of entries) {
+        if (typeof entry !== 'string')
+            continue;
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const normalized = normalizePanelApiJsonlAllowedOrigin(trimmed);
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        origins.push(normalized);
+    }
+    return origins;
+}
+export function normalizePanelApiJsonlAllowedUrlPrefix(rawPrefix) {
+    const trimmed = rawPrefix.trim();
+    if (!trimmed || trimmed.includes('\0') || /[\r\n]/u.test(trimmed))
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return null;
+    if (parsed.username || parsed.password)
+        return null;
+    if (parsed.search || parsed.hash)
+        return null;
+    return `${parsed.origin}${parsed.pathname}`;
+}
+export function normalizePanelApiJsonlAllowedUrlPrefixes(rawPrefixes) {
+    const entries = typeof rawPrefixes === 'string'
+        ? rawPrefixes.split(/[,\s]+/u)
+        : Array.isArray(rawPrefixes)
+            ? [...rawPrefixes]
+            : [];
+    const seen = new Set();
+    const prefixes = [];
+    for (const entry of entries) {
+        if (typeof entry !== 'string')
+            continue;
+        const normalized = normalizePanelApiJsonlAllowedUrlPrefix(entry);
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        prefixes.push(normalized);
+    }
+    return prefixes;
+}
+export function matchPanelApiJsonlAllowedUrlPrefix(parsed, rawPrefixes) {
+    for (const prefix of normalizePanelApiJsonlAllowedUrlPrefixes(rawPrefixes)) {
+        const parsedPrefix = new URL(prefix);
+        if (parsed.origin !== parsedPrefix.origin)
+            continue;
+        const prefixPath = parsedPrefix.pathname;
+        const pathMatches = prefixPath.endsWith('/')
+            ? parsed.pathname.startsWith(prefixPath)
+            : parsed.pathname === prefixPath || parsed.pathname.startsWith(`${prefixPath}/`);
+        if (!pathMatches)
+            continue;
+        return prefix;
+    }
+    return null;
+}
+export function isPanelApiJsonlDefaultLoopbackUrl(parsed) {
+    return parsed.protocol === 'http:' && PANEL_API_JSONL_LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase());
+}
+export function validatePanelApiJsonlUrl(rawUrl, options = {}) {
+    const trimmed = rawUrl.trim();
+    if (!trimmed || trimmed.includes('\0') || /[\r\n]/u.test(trimmed)) {
+        return { ok: false, reason: 'api_jsonl url must be a non-empty URL without control characters.' };
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return { ok: false, reason: 'api_jsonl url must be a valid URL.' };
+    }
+    if (parsed.username || parsed.password) {
+        return { ok: false, reason: 'api_jsonl url must not include credentials.' };
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return {
+            ok: false,
+            reason: 'api_jsonl only supports http:// loopback endpoints or configured http(s) origins / URL prefixes.',
+        };
+    }
+    const defaultLoopback = isPanelApiJsonlDefaultLoopbackUrl(parsed);
+    const allowedOrigins = normalizePanelApiJsonlAllowedOrigins(options.allowedOrigins);
+    const matchedAllowedPrefix = matchPanelApiJsonlAllowedUrlPrefix(parsed, options.allowedUrlPrefixes);
+    if (!defaultLoopback && !allowedOrigins.includes(parsed.origin) && !matchedAllowedPrefix) {
+        return {
+            ok: false,
+            reason: 'api_jsonl endpoints must target localhost, 127.0.0.1, or ::1, or match a configured allowlisted origin or URL prefix on the agent node.',
+        };
+    }
+    return {
+        ok: true,
+        url: parsed.toString(),
+        origin: parsed.origin,
+        defaultLoopback,
+        matchedAllowedPrefix,
+    };
+}
+export function validatePanelApiJsonlUrlList(source, options = {}) {
+    const hasUrl = source.url !== undefined;
+    const hasUrls = source.urls !== undefined;
+    if (hasUrl && hasUrls) {
+        return {
+            ok: false,
+            reason: 'dataset.source.url and dataset.source.urls are mutually exclusive.',
+        };
+    }
+    if (!hasUrl && !hasUrls) {
+        return {
+            ok: false,
+            reason: 'dataset.source.url or dataset.source.urls is required.',
+            missingField: 'dataset.source.url',
+        };
+    }
+    const rawUrls = hasUrl
+        ? [source.url]
+        : Array.isArray(source.urls)
+            ? source.urls
+            : null;
+    if (!rawUrls) {
+        return {
+            ok: false,
+            reason: 'dataset.source.urls must be an array of URL strings.',
+        };
+    }
+    if (rawUrls.length < 1) {
+        return {
+            ok: false,
+            reason: 'dataset.source.urls must include at least one URL.',
+        };
+    }
+    if (rawUrls.length > PANEL_API_JSONL_MAX_URLS) {
+        return {
+            ok: false,
+            reason: `dataset.source.urls supports at most ${PANEL_API_JSONL_MAX_URLS} URLs.`,
+        };
+    }
+    const seen = new Set();
+    const urls = [];
+    for (let index = 0; index < rawUrls.length; index += 1) {
+        const rawUrl = rawUrls[index];
+        if (typeof rawUrl !== 'string') {
+            return {
+                ok: false,
+                reason: hasUrl ? 'dataset.source.url must be a URL string.' : `dataset.source.urls[${index}] must be a URL string.`,
+            };
+        }
+        const validation = validatePanelApiJsonlUrl(rawUrl, options);
+        if (!validation.ok) {
+            return {
+                ok: false,
+                reason: hasUrl ? validation.reason : `dataset.source.urls[${index}]: ${validation.reason}`,
+            };
+        }
+        if (seen.has(validation.url)) {
+            return {
+                ok: false,
+                reason: `dataset.source.urls[${index}] duplicates an earlier URL.`,
+            };
+        }
+        seen.add(validation.url);
+        urls.push(validation.url);
+    }
+    const authValidation = validatePanelApiJsonlAuthProfile(source.auth, {
+        allowedAuthProfiles: options.allowedAuthProfiles,
+    });
+    if (!authValidation.ok) {
+        return { ok: false, reason: authValidation.reason };
+    }
+    return { ok: true, urls, authProfile: authValidation.authProfile };
+}
+export function isPanelTemplateContainerNode(node) {
+    return node?.type === 'Row'
+        || node?.type === 'Column'
+        || node?.type === 'Card'
+        || node?.type === 'Tabs'
+        || node?.type === 'Accordion'
+        || node?.type === 'Columns'
+        || node?.type === 'Stack'
+        || node?.type === 'Inline'
+        || node?.type === 'Grid';
+}
+export function walkPanelTemplateNodes(node, visitor) {
+    if (!node)
+        return;
+    const visit = (current, context) => {
+        if (visitor(current, context) === false)
+            return;
+        for (const child of getPanelTemplateChildEntries(current)) {
+            visit(child.node, {
+                parent: current,
+                depth: context.depth + 1,
+                index: child.index,
+                ...(child.columnIndex !== undefined ? { columnIndex: child.columnIndex } : {}),
+                ...(child.tabIndex !== undefined ? { tabIndex: child.tabIndex } : {}),
+            });
+        }
+    };
+    visit(node, { parent: null, depth: 0, index: null });
+}
+export function collectPanelTemplateUnsupportedNodes(node, policy = {}) {
+    const unsupported = [];
+    walkPanelTemplateNodes(node, (current) => {
+        const interactiveBlocked = policy.allowInteractiveTypes !== true
+            && panelTemplateNodeTypeIn(current.type, policy.interactiveTypes);
+        if (interactiveBlocked
+            || panelTemplateNodeTypeIn(current.type, policy.unsupportedTypes)
+            || policy.predicate?.(current) === true) {
+            unsupported.push(current);
+        }
+    });
+    return unsupported;
+}
+export function isPanelLevelContainerNode(node) {
+    return node?.type === 'Section'
+        || node?.type === 'ParameterFormSection'
+        || node?.type === 'Card'
+        || node?.type === 'Columns'
+        || node?.type === 'Stack'
+        || node?.type === 'Inline'
+        || node?.type === 'Grid';
+}
+export function isPanelLevelActionBarNode(node) {
+    return node?.type === 'ActionBar';
+}
+export function isPanelLevelParameterInputNode(node) {
+    switch (node?.type) {
+        case 'TextInput':
+        case 'TextArea':
+        case 'NumberInput':
+        case 'Checkbox':
+        case 'Select':
+        case 'MultiSelect':
+        case 'TagInput':
+        case 'Slider':
+        case 'DatePicker':
+        case 'FileUpload':
+            return true;
+        default:
+            return false;
+    }
+}
+export function isPanelLevelDatasetAggregateNode(node) {
+    return node?.type === 'AggregateValue' && node.scope === 'dataset';
+}
+export function walkPanelLevelNodes(node, visitor) {
+    if (!node)
+        return;
+    const visit = (current, context) => {
+        if (visitor(current, context) === false)
+            return;
+        for (const child of getPanelLevelChildEntries(current)) {
+            visit(child.node, {
+                parent: current,
+                depth: context.depth + 1,
+                index: child.index,
+                ...(child.columnIndex !== undefined ? { columnIndex: child.columnIndex } : {}),
+            });
+        }
+    };
+    visit(node, { parent: null, depth: 0, index: null });
+}
+export function mapPanelLevelNodes(node, mapper, options = {}) {
+    if (!node)
+        return null;
+    const visit = (current, context) => {
+        const mapped = mapper(current, context);
+        if (mapped === null)
+            return { node: null, changed: true };
+        const base = mapped ?? current;
+        let changed = mapped !== undefined && mapped !== current;
+        switch (base.type) {
+            case 'Section':
+            case 'ParameterFormSection':
+            case 'Card':
+            case 'Stack':
+            case 'Inline':
+            case 'Grid': {
+                const sourceChildren = Array.isArray(base.children)
+                    ? [...base.children]
+                    : [];
+                const children = [];
+                let childrenChanged = !Array.isArray(base.children);
+                for (let index = 0; index < sourceChildren.length; index += 1) {
+                    const child = sourceChildren[index];
+                    const childResult = visit(child, {
+                        parent: base,
+                        depth: context.depth + 1,
+                        index,
+                    });
+                    if (childResult.node) {
+                        children.push(childResult.node);
+                    }
+                    else {
+                        childrenChanged = true;
+                    }
+                    if (childResult.changed || childResult.node !== child)
+                        childrenChanged = true;
+                }
+                if (options.pruneEmptyContainers === true && children.length === 0) {
+                    return { node: null, changed: true };
+                }
+                if (options.collapseSingleChildContainers === true
+                    && children.length === 1
+                    && children.length !== sourceChildren.length) {
+                    return { node: children[0], changed: true };
+                }
+                if (childrenChanged || children.length !== sourceChildren.length) {
+                    changed = true;
+                    return { node: { ...base, children }, changed };
+                }
+                return { node: base, changed };
+            }
+            case 'Columns': {
+                const sourceColumns = Array.isArray(base.columns)
+                    ? [...base.columns]
+                    : [];
+                const columns = [];
+                let columnsChanged = !Array.isArray(base.columns);
+                for (let columnIndex = 0; columnIndex < sourceColumns.length; columnIndex += 1) {
+                    const column = sourceColumns[columnIndex];
+                    if (!isRecord(column) || !Array.isArray(column.children)) {
+                        columnsChanged = true;
+                        continue;
+                    }
+                    const children = [];
+                    let childrenChanged = false;
+                    for (let index = 0; index < column.children.length; index += 1) {
+                        const child = column.children[index];
+                        const childResult = visit(child, {
+                            parent: base,
+                            depth: context.depth + 1,
+                            index,
+                            columnIndex,
+                        });
+                        if (childResult.node) {
+                            children.push(childResult.node);
+                        }
+                        else {
+                            childrenChanged = true;
+                        }
+                        if (childResult.changed || childResult.node !== child)
+                            childrenChanged = true;
+                    }
+                    if (options.pruneEmptyColumns === true && children.length === 0) {
+                        columnsChanged = true;
+                        continue;
+                    }
+                    const nextColumn = {
+                        ...(typeof column.width === 'string' ? { width: column.width } : {}),
+                        children,
+                    };
+                    columns.push(nextColumn);
+                    if (childrenChanged || children.length !== column.children.length) {
+                        columnsChanged = true;
+                    }
+                }
+                if (options.pruneEmptyContainers === true && columns.length === 0) {
+                    return { node: null, changed: true };
+                }
+                if (columnsChanged || columns.length !== sourceColumns.length) {
+                    changed = true;
+                    return { node: { type: 'Columns', columns }, changed };
+                }
+                return { node: base, changed };
+            }
+            default:
+                return { node: base, changed };
+        }
+    };
+    return visit(node, { parent: null, depth: 0, index: null }).node;
+}
+export function collectPanelLevelActionBars(node) {
+    const actionBars = [];
+    walkPanelLevelNodes(node, (current) => {
+        if (isPanelLevelActionBarNode(current))
+            actionBars.push(current);
+    });
+    return actionBars;
+}
+export function panelLevelNodeHasActionBar(node) {
+    return collectPanelLevelActionBars(node).length > 0;
+}
+export function collectPanelLevelParameterInputs(node) {
+    const inputs = [];
+    walkPanelLevelNodes(node, (current) => {
+        if (isPanelLevelParameterInputNode(current))
+            inputs.push(current);
+    });
+    return inputs;
+}
+export function collectDatasetAggregateNodes(node) {
+    const aggregates = [];
+    walkPanelLevelNodes(node, (current) => {
+        if (isPanelLevelDatasetAggregateNode(current))
+            aggregates.push(current);
+    });
+    return aggregates;
+}
+export function panelLevelNodeUsesDatasetAggregate(node) {
+    return collectDatasetAggregateNodes(node).length > 0;
+}
+export function panelLevelNodeContainsEmptyLayoutContainer(node) {
+    if (!node)
+        return false;
+    switch (node.type) {
+        case 'Section':
+        case 'ParameterFormSection':
+        case 'Card':
+        case 'Stack':
+        case 'Inline':
+        case 'Grid': {
+            const children = Array.isArray(node.children)
+                ? node.children
+                : [];
+            return children.length === 0 || children.some(panelLevelNodeContainsEmptyLayoutContainer);
+        }
+        case 'Columns': {
+            const columns = Array.isArray(node.columns)
+                ? node.columns
+                : [];
+            return columns.length === 0
+                || columns.some((column) => (!isRecord(column)
+                    || !Array.isArray(column.children)
+                    || column.children.length === 0
+                    || column.children.some(panelLevelNodeContainsEmptyLayoutContainer)));
+        }
+        default:
+            return false;
+    }
+}
+export function isPanelLevelNodeEffectivelyEmpty(node) {
+    if (!node)
+        return true;
+    switch (node.type) {
+        case 'Section':
+        case 'ParameterFormSection':
+        case 'Card':
+        case 'Stack':
+        case 'Inline':
+        case 'Grid': {
+            const children = Array.isArray(node.children)
+                ? node.children
+                : [];
+            return children.length === 0 || children.every(isPanelLevelNodeEffectivelyEmpty);
+        }
+        case 'Columns': {
+            const columns = Array.isArray(node.columns)
+                ? node.columns
+                : [];
+            return columns.length === 0
+                || columns.every((column) => (!isRecord(column)
+                    || !Array.isArray(column.children)
+                    || column.children.length === 0
+                    || column.children.every(isPanelLevelNodeEffectivelyEmpty)));
+        }
+        default:
+            return false;
+    }
+}
+export function collectPanelLevelUnsupportedNodes(node, policy = {}) {
+    const unsupported = [];
+    walkPanelLevelNodes(node, (current) => {
+        const interactiveBlocked = policy.allowInteractiveTypes !== true
+            && panelLevelNodeTypeIn(current.type, policy.interactiveTypes);
+        if (interactiveBlocked
+            || panelLevelNodeTypeIn(current.type, policy.unsupportedTypes)
+            || policy.predicate?.(current) === true) {
+            unsupported.push(current);
+        }
+    });
+    return unsupported;
+}
+function getPanelLevelChildEntries(node) {
+    switch (node.type) {
+        case 'Section':
+        case 'ParameterFormSection':
+        case 'Card':
+        case 'Stack':
+        case 'Inline':
+        case 'Grid': {
+            const children = Array.isArray(node.children)
+                ? node.children
+                : [];
+            return children.map((child, index) => ({ node: child, index }));
+        }
+        case 'Columns': {
+            const columns = Array.isArray(node.columns)
+                ? node.columns
+                : [];
+            return columns.flatMap((column, columnIndex) => {
+                if (!isRecord(column) || !Array.isArray(column.children))
+                    return [];
+                return column.children.map((child, index) => ({ node: child, index, columnIndex }));
+            });
+        }
+        default:
+            return [];
+    }
+}
+function getPanelTemplateChildEntries(node) {
+    switch (node.type) {
+        case 'Row':
+        case 'Column':
+        case 'Card':
+        case 'Accordion':
+        case 'Stack':
+        case 'Inline':
+        case 'Grid': {
+            const children = Array.isArray(node.children)
+                ? node.children
+                : [];
+            return children.map((child, index) => ({ node: child, index }));
+        }
+        case 'Tabs': {
+            const items = Array.isArray(node.items)
+                ? node.items
+                : [];
+            return items.flatMap((item, itemIndex) => (isRecord(item) && isRecord(item.node)
+                ? [{ node: item.node, index: itemIndex, tabIndex: itemIndex }]
+                : []));
+        }
+        case 'Columns': {
+            const columns = Array.isArray(node.columns)
+                ? node.columns
+                : [];
+            return columns.flatMap((column, columnIndex) => {
+                if (!isRecord(column) || !Array.isArray(column.children))
+                    return [];
+                return column.children.map((child, index) => ({ node: child, index, columnIndex }));
+            });
+        }
+        default:
+            return [];
+    }
+}
+function panelLevelNodeTypeIn(type, types) {
+    if (!types)
+        return false;
+    if (Array.isArray(types))
+        return types.includes(type);
+    return types.has(type);
+}
+function panelTemplateNodeTypeIn(type, types) {
+    if (!types)
+        return false;
+    if (Array.isArray(types))
+        return types.includes(type);
+    return types.has(type);
+}
+export const COMPONENT_CONTRACTS = {
+    ImageReviewGrid: {
+        name: 'ImageReviewGrid',
+        displayName: 'Image Review Grid',
+        description: 'Split-layout grid for reviewing images with LaTeX annotations. Left column shows image + label; right column renders LaTeX text.',
+        dataModel: { kind: 'paged_rows' },
+        propsSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string' },
+                showScore: { type: 'boolean' },
+                pageSize: {
+                    type: 'integer',
+                    minimum: MIN_PANEL_PAGE_SIZE,
+                    maximum: MAX_PANEL_PAGE_SIZE,
+                    default: DEFAULT_PANEL_PAGE_SIZE,
+                    description: 'Optional row page size. Defaults to 10 and is limited to 1-50.',
+                },
+                refreshIntervalMs: {
+                    type: 'integer',
+                    minimum: MIN_PANEL_REFRESH_INTERVAL_MS,
+                    maximum: MAX_PANEL_REFRESH_INTERVAL_MS,
+                    description: 'Optional auto-refresh interval for dynamic query_handle or api_jsonl rows. Omit to disable polling. Limited to 1000-60000 ms.',
+                },
+            },
+        },
+        datasetSchema: {
+            fields: [
+                { name: 'label', label: 'Label', type: 'string', filterable: true, sortable: true },
+                { name: 'score', label: 'Score', type: 'number', filterable: true, sortable: true },
+                { name: 'category', label: 'Category', type: 'string', filterable: true, sortable: true },
+                { name: 'latex', label: 'LaTeX', type: 'string' },
+            ],
+            mediaSlots: [
+                { name: 'img', kind: 'workspace_path', displayType: 'img' },
+            ],
+        },
+        stateSchema: {
+            type: 'object',
+            properties: {
+                filters: { type: 'object' },
+                sort: { type: 'object' },
+                selection: { type: 'array' },
+            },
+        },
+        sharedStateKeys: ['selection'],
+        clientInteractions: ['filter', 'sort', 'select', 'hover', 'zoom'],
+        supportedActions: [
+            {
+                id: 'ocr',
+                label: 'OCR 选中项',
+                description: 'Run OCR on selected images',
+            },
+        ],
+    },
+    RowTemplateGrid: {
+        name: 'RowTemplateGrid',
+        displayName: 'Row Template Grid',
+        description: 'Paged row grid that renders each row through a safe declarative template made from registered primitives: Row, Column, Card, Tabs, TextField, LatexBlock, Badge, ComputedValue, ImageSlot, Checkbox, FormField, ActionButton, SubmitButton, Sparkline, Accordion, Divider, Callout, Columns, DiffView, CodeBlock, JsonView, and MarkdownText. Template nodes can use visibleWhen for bounded row-field conditional rendering. Badge supports bounded valueMap label/variant mapping for declared row values. FormField supports text, number, checkbox, textarea, bounded static select, and form-only tags inputs for row-level form deltas; tags may not bind dataset fields. ComputedValue supports fixed cross-field operations such as sum, ratio, percent, average, weighted_sum, and concat without arbitrary expressions or JavaScript. ImageSlot can optionally render editable annotation boxes when bound to annotationsField, including shortcutLabels for single-key label/color updates and autosaved staged form state. Supports optional summary and parameterForm panel-level slots, including Section/ParameterFormSection, Card, Columns, AggregateValue page or server-side dataset aggregates, BarChart/LineChart with optional zoomable brush, Histogram, grouped/stacked BarChart, ProgressBar, StatusBadge, Timeline, LogBlock, Tool-only RunStatusCard/RunLogViewer/ArtifactList widgets, ActionBar plus TextInput, TextArea, NumberInput, DatePicker, FileUpload with clipboard paste, Checkbox, Select, MultiSelect, TagInput, Slider, and Button controls. Select and MultiSelect option objects may use visibleWhen against current parameter form values for bounded option cascading.',
+        dataModel: { kind: 'paged_rows' },
+        propsSchema: {
+            type: 'object',
+            required: ['fields', 'template'],
+            properties: {
+                title: { type: 'string' },
+                pageSize: {
+                    type: 'integer',
+                    minimum: MIN_PANEL_PAGE_SIZE,
+                    maximum: MAX_PANEL_PAGE_SIZE,
+                    default: DEFAULT_PANEL_PAGE_SIZE,
+                    description: 'Optional row page size. Defaults to 10 and is limited to 1-50.',
+                },
+                refreshIntervalMs: {
+                    type: 'integer',
+                    minimum: MIN_PANEL_REFRESH_INTERVAL_MS,
+                    maximum: MAX_PANEL_REFRESH_INTERVAL_MS,
+                    description: 'Optional auto-refresh interval for dynamic query_handle or api_jsonl rows. Omit to disable polling. Limited to 1000-60000 ms.',
+                },
+                fields: { type: 'array' },
+                mediaSlots: { type: 'array' },
+                template: { type: 'object' },
+                summary: {
+                    type: 'object',
+                    description: 'Optional panel-level slot. Supports MetricCard, AggregateValue, BarChart, LineChart, PieChart, Histogram, ProgressBar, StatusBadge, Timeline, LogBlock, and Tool-only RunStatusCard/RunLogViewer/ArtifactList widgets when rendered in a tool-scoped surface.',
+                },
+                parameterForm: {
+                    type: 'object',
+                    description: 'Optional panel-level form/action slot. Supports Section/ParameterFormSection, Card, Columns, TextInput, TextArea, NumberInput, Checkbox, Select, MultiSelect, TagInput, Slider, DatePicker, FileUpload with clipboard paste, Button, and ActionBar.',
+                },
+            },
+        },
+        datasetSchema: {
+            fields: [],
+            mediaSlots: [],
+        },
+        stateSchema: {
+            type: 'object',
+            properties: {
+                filters: { type: 'object' },
+                sort: { type: 'object' },
+                selection: { type: 'array' },
+                formValues: { type: 'object' },
+            },
+        },
+        sharedStateKeys: ['selection'],
+        clientInteractions: ['filter', 'sort', 'select', 'hover', 'zoom', 'edit', 'autosave'],
+    },
+};
+export function getComponentContract(name) {
+    return COMPONENT_CONTRACTS[name];
+}
+export function listComponentContracts() {
+    return Object.values(COMPONENT_CONTRACTS);
+}
+const FIELD_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_:-]{0,63}$/;
+const FIELD_PATH_PATTERN = /^[A-Za-z_][A-Za-z0-9_:-]{0,63}(?:\.[A-Za-z_][A-Za-z0-9_:-]{0,63}){0,15}$/;
+const MAX_TEMPLATE_DEPTH = 8;
+const MAX_TEMPLATE_CHILDREN = 12;
+const MAX_FORM_FIELD_OPTIONS = 50;
+const MAX_PANEL_LEVEL_DEPTH = 8;
+const MAX_PANEL_LEVEL_CHILDREN = 50;
+const ROW_CONTEXT_NODE_TYPES = new Set([
+    'TextField', 'LatexBlock', 'MarkdownField', 'CodeField', 'JsonField', 'DiffField',
+    'Badge', 'ComputedValue', 'ImageSlot', 'MediaBlock', 'FormField',
+    'ActionButton', 'SubmitButton', 'Sparkline',
+]);
+const PANEL_LEVEL_ONLY_TYPES = new Set([
+    'Section', 'ParameterFormSection', 'MetricCard', 'BarChart', 'LineChart', 'PieChart', 'Histogram',
+    'ProgressBar', 'StatusBadge', 'Timeline', 'LogBlock', 'RunStatusCard', 'RunLogViewer', 'ArtifactList', 'TextInput', 'TextArea', 'NumberInput', 'Select',
+    'MultiSelect', 'TagInput', 'Slider', 'DatePicker', 'FileUpload', 'Button',
+    'ActionBar', 'AggregateValue',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isPrimitiveMapValue(value) {
+    return value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+}
+function isFormFieldOptionValue(value) {
+    return typeof value === 'string'
+        || (typeof value === 'number' && Number.isFinite(value))
+        || typeof value === 'boolean';
+}
+function isValidBadgeVariant(value) {
+    return value === 'default' || value === 'success' || value === 'warning' || value === 'danger';
+}
+function isValidKeyValueTone(value) {
+    return value === 'default' || value === 'success' || value === 'warning' || value === 'danger';
+}
+function validateLayoutGap(value, path, errors, allowNone = true) {
+    if (value !== undefined
+        && value !== 'sm'
+        && value !== 'md'
+        && value !== 'lg'
+        && (allowNone !== true || value !== 'none')) {
+        errors.push(`${path} must be ${allowNone ? 'none, ' : ''}sm, md, or lg`);
+    }
+}
+function validateLayoutAlign(value, path, errors, allowStretch = true) {
+    if (value !== undefined
+        && value !== 'start'
+        && value !== 'center'
+        && value !== 'end'
+        && (allowStretch !== true || value !== 'stretch')) {
+        errors.push(`${path} must be start, center, end${allowStretch ? ', or stretch' : ''}`);
+    }
+}
+function validateToolRunSelector(value, path, errors) {
+    if (value === undefined || value === 'latest')
+        return;
+    if (!isRecord(value)) {
+        errors.push(`${path} must be "latest" or { id: string }`);
+        return;
+    }
+    hasOnlyKeys(value, ['id'], path, errors);
+    if (typeof value.id !== 'string' || value.id.trim().length === 0) {
+        errors.push(`${path}.id must be a non-empty string`);
+    }
+}
+function validateStringArrayOption(value, path, errors) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        errors.push(`${path} must be an array`);
+        return;
+    }
+    if (value.length > 50) {
+        errors.push(`${path} exceeds maximum 50 items`);
+    }
+    value.forEach((item, index) => {
+        if (typeof item !== 'string' || item.trim().length === 0) {
+            errors.push(`${path}[${index}] must be a non-empty string`);
+        }
+    });
+}
+function validateKeyValueListNode(node, options) {
+    const { path, errors, fieldNames, template } = options;
+    const keyValidator = template ? hasOnlyTemplateKeys : hasOnlyKeys;
+    keyValidator(node, ['type', 'items'], path, errors);
+    if (!Array.isArray(node.items)) {
+        errors.push(`${path}.items must be an array`);
+        return;
+    }
+    if (node.items.length > 50) {
+        errors.push(`${path}.items exceeds max 50`);
+    }
+    node.items.forEach((item, index) => {
+        const itemPath = `${path}.items[${index}]`;
+        if (!isRecord(item)) {
+            errors.push(`${itemPath} must be an object`);
+            return;
+        }
+        hasOnlyKeys(item, ['label', 'field', 'source', 'value', 'fallback', 'tone'], itemPath, errors);
+        if (typeof item.label !== 'string' || item.label.trim().length === 0) {
+            errors.push(`${itemPath}.label must be a non-empty string`);
+        }
+        if (item.field !== undefined && (typeof item.field !== 'string' || !fieldNames.has(item.field))) {
+            errors.push(`${itemPath}.field references an unknown field`);
+        }
+        if (item.source !== undefined && typeof item.source !== 'string') {
+            errors.push(`${itemPath}.source must be a string`);
+        }
+        if (template && item.source !== undefined) {
+            errors.push(`${itemPath}.source is only supported in panel-level KeyValueList nodes`);
+        }
+        if (item.fallback !== undefined && typeof item.fallback !== 'string') {
+            errors.push(`${itemPath}.fallback must be a string`);
+        }
+        if (item.tone !== undefined && !isValidKeyValueTone(item.tone)) {
+            errors.push(`${itemPath}.tone must be default, success, warning, or danger`);
+        }
+        if (!Object.prototype.hasOwnProperty.call(item, 'value')
+            && item.field === undefined
+            && item.source === undefined) {
+            errors.push(`${itemPath} must declare field, source, or value`);
+        }
+    });
+}
+function isPanelLevelOnlyType(type) {
+    return PANEL_LEVEL_ONLY_TYPES.has(type);
+}
+function isRowContextNodeType(type) {
+    return ROW_CONTEXT_NODE_TYPES.has(type);
+}
+function validateFieldSchemas(value, path) {
+    const errors = [];
+    if (!Array.isArray(value)) {
+        return { fields: [], errors: [`${path} must be an array`] };
+    }
+    const seen = new Set();
+    const fields = [];
+    value.forEach((item, index) => {
+        const itemPath = `${path}[${index}]`;
+        if (!isRecord(item)) {
+            errors.push(`${itemPath} must be an object`);
+            return;
+        }
+        const name = item.name;
+        const type = item.type;
+        if (typeof name !== 'string' || !FIELD_PATH_PATTERN.test(name)) {
+            errors.push(`${itemPath}.name must be a safe field name or dot path`);
+            return;
+        }
+        if (seen.has(name)) {
+            errors.push(`${itemPath}.name duplicates "${name}"`);
+            return;
+        }
+        if (type !== 'string' && type !== 'number' && type !== 'boolean') {
+            errors.push(`${itemPath}.type must be string, number, or boolean`);
+            return;
+        }
+        if (item.label !== undefined && typeof item.label !== 'string') {
+            errors.push(`${itemPath}.label must be a string`);
+            return;
+        }
+        const label = typeof item.label === 'string' && item.label.trim()
+            ? item.label.trim()
+            : undefined;
+        seen.add(name);
+        fields.push({
+            name,
+            ...(label ? { label } : {}),
+            type,
+            filterable: item.filterable === true,
+            sortable: item.sortable === true,
+        });
+    });
+    return { fields, errors };
+}
+function validateMediaSlotSchemas(value, path) {
+    const errors = [];
+    if (value === undefined)
+        return { mediaSlots: [], errors };
+    if (!Array.isArray(value)) {
+        return { mediaSlots: [], errors: [`${path} must be an array`] };
+    }
+    const seen = new Set();
+    const mediaSlots = [];
+    value.forEach((item, index) => {
+        const itemPath = `${path}[${index}]`;
+        if (!isRecord(item)) {
+            errors.push(`${itemPath} must be an object`);
+            return;
+        }
+        const name = item.name;
+        const kind = item.kind;
+        const displayType = item.displayType;
+        if (typeof name !== 'string' || !FIELD_NAME_PATTERN.test(name)) {
+            errors.push(`${itemPath}.name must be a safe media slot name`);
+            return;
+        }
+        if (seen.has(name)) {
+            errors.push(`${itemPath}.name duplicates "${name}"`);
+            return;
+        }
+        if (kind !== 'workspace_path' && kind !== 'asset') {
+            errors.push(`${itemPath}.kind must be workspace_path or asset`);
+            return;
+        }
+        if (displayType !== 'img' && displayType !== 'latex' && displayType !== 'text') {
+            errors.push(`${itemPath}.displayType must be img, latex, or text`);
+            return;
+        }
+        seen.add(name);
+        mediaSlots.push({ name, kind, displayType });
+    });
+    return { mediaSlots, errors };
+}
+function hasOnlyKeys(value, keys, path, errors) {
+    const allowed = new Set(keys);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            errors.push(`${path}.${key} is not allowed`);
+        }
+    }
+}
+function hasOnlyTemplateKeys(value, keys, path, errors) {
+    hasOnlyKeys(value, [...keys, 'visibleWhen'], path, errors);
+}
+function validateVisibilityCondition(value, options) {
+    const { fieldNames, path, errors } = options;
+    if (value === undefined)
+        return;
+    if (!isRecord(value)) {
+        errors.push(`${path}.visibleWhen must be an object`);
+        return;
+    }
+    hasOnlyKeys(value, ['field', 'op', 'value', 'values'], `${path}.visibleWhen`, errors);
+    if (typeof value.field !== 'string' || !fieldNames.has(value.field)) {
+        errors.push(`${path}.visibleWhen.field references an unknown field`);
+    }
+    const op = value.op ?? 'truthy';
+    const validOps = new Set(['exists', 'not_empty', 'equals', 'not_equals', 'in', 'not_in', 'contains', 'truthy', 'falsy']);
+    if (typeof op !== 'string' || !validOps.has(op)) {
+        errors.push(`${path}.visibleWhen.op must be exists, not_empty, equals, not_equals, in, not_in, contains, truthy, or falsy`);
+        return;
+    }
+    if ((op === 'equals' || op === 'not_equals' || op === 'contains') && !Object.prototype.hasOwnProperty.call(value, 'value')) {
+        errors.push(`${path}.visibleWhen.value is required for ${op}`);
+    }
+    if (op === 'in' || op === 'not_in') {
+        if (!Array.isArray(value.values)) {
+            errors.push(`${path}.visibleWhen.values must be an array for ${op}`);
+        }
+        else if (value.values.length > 50) {
+            errors.push(`${path}.visibleWhen.values exceeds max 50`);
+        }
+    }
+}
+export function validatePanelLevelNode(node, options) {
+    const { path, depth, errors, slotName, actionIds = new Set(), fieldNames = new Set() } = options;
+    if (depth > MAX_PANEL_LEVEL_DEPTH) {
+        errors.push(`${path} exceeds max depth ${MAX_PANEL_LEVEL_DEPTH}`);
+        return;
+    }
+    if (!isRecord(node)) {
+        errors.push(`${path} must be an object`);
+        return;
+    }
+    const type = node.type;
+    if (typeof type !== 'string') {
+        errors.push(`${path}.type is required`);
+        return;
+    }
+    if (type === 'FormField') {
+        if (slotName === 'parameterForm') {
+            errors.push('Parameter form slot may not contain row-context field binding: FormField');
+        }
+        else {
+            errors.push(`Panel-level slot ${slotName} may not contain row-context node: ${type}`);
+        }
+        return;
+    }
+    if (type === 'Sparkline') {
+        errors.push(`Panel-level slot ${slotName} may not contain row-level node: Sparkline`);
+        return;
+    }
+    if (isRowContextNodeType(type)) {
+        errors.push(`Panel-level slot ${slotName} may not contain row-context node: ${type}`);
+        return;
+    }
+    switch (type) {
+        case 'Section':
+        case 'ParameterFormSection':
+        case 'Card': {
+            hasOnlyKeys(node, type === 'Card' ? ['type', 'title', 'children'] : ['type', 'children'], path, errors);
+            if (type === 'Card' && node.title !== undefined && typeof node.title !== 'string') {
+                errors.push(`${path}.title must be a string`);
+            }
+            if (!Array.isArray(node.children)) {
+                errors.push(`${path}.children must be an array`);
+                return;
+            }
+            if (node.children.length > MAX_PANEL_LEVEL_CHILDREN) {
+                errors.push(`${path}.children exceeds maximum children per container (${MAX_PANEL_LEVEL_CHILDREN})`);
+            }
+            node.children.forEach((child, index) => validatePanelLevelNode(child, {
+                path: `${path}.children[${index}]`,
+                depth: depth + 1,
+                errors,
+                slotName,
+                actionIds,
+                fieldNames,
+            }));
+            break;
+        }
+        case 'Stack':
+        case 'Inline':
+        case 'Grid': {
+            const allowedKeys = type === 'Stack'
+                ? ['type', 'children', 'direction', 'gap', 'align', 'wrap']
+                : type === 'Inline'
+                    ? ['type', 'children', 'gap', 'align', 'wrap']
+                    : ['type', 'children', 'minColumnWidth', 'maxColumns', 'gap'];
+            hasOnlyKeys(node, allowedKeys, path, errors);
+            if (type === 'Stack' && node.direction !== undefined && node.direction !== 'vertical' && node.direction !== 'horizontal') {
+                errors.push(`${path}.direction must be vertical or horizontal`);
+            }
+            if (type === 'Stack' || type === 'Inline') {
+                validateLayoutGap(node.gap, `${path}.gap`, errors);
+                validateLayoutAlign(node.align, `${path}.align`, errors, type === 'Stack');
+                if (node.wrap !== undefined && typeof node.wrap !== 'boolean') {
+                    errors.push(`${path}.wrap must be a boolean`);
+                }
+            }
+            else {
+                validateLayoutGap(node.gap, `${path}.gap`, errors, false);
+                if (node.minColumnWidth !== undefined && (typeof node.minColumnWidth !== 'number'
+                    || !Number.isInteger(node.minColumnWidth)
+                    || node.minColumnWidth < 80
+                    || node.minColumnWidth > 640)) {
+                    errors.push(`${path}.minColumnWidth must be an integer from 80 to 640`);
+                }
+                if (node.maxColumns !== undefined && (typeof node.maxColumns !== 'number'
+                    || !Number.isInteger(node.maxColumns)
+                    || node.maxColumns < 1
+                    || node.maxColumns > 12)) {
+                    errors.push(`${path}.maxColumns must be an integer from 1 to 12`);
+                }
+            }
+            if (!Array.isArray(node.children)) {
+                errors.push(`${path}.children must be an array`);
+                return;
+            }
+            if (node.children.length > MAX_PANEL_LEVEL_CHILDREN) {
+                errors.push(`${path}.children exceeds maximum children per container (${MAX_PANEL_LEVEL_CHILDREN})`);
+            }
+            node.children.forEach((child, index) => validatePanelLevelNode(child, {
+                path: `${path}.children[${index}]`,
+                depth: depth + 1,
+                errors,
+                slotName,
+                actionIds,
+                fieldNames,
+            }));
+            break;
+        }
+        case 'Columns': {
+            hasOnlyKeys(node, ['type', 'columns'], path, errors);
+            if (!Array.isArray(node.columns)) {
+                errors.push(`${path}.columns must be an array`);
+                break;
+            }
+            if (node.columns.length > MAX_PANEL_LEVEL_CHILDREN) {
+                errors.push(`${path}.columns exceeds maximum children per container (${MAX_PANEL_LEVEL_CHILDREN})`);
+            }
+            node.columns.forEach((col, index) => {
+                const colPath = `${path}.columns[${index}]`;
+                if (!isRecord(col)) {
+                    errors.push(`${colPath} must be an object`);
+                    return;
+                }
+                hasOnlyKeys(col, ['width', 'children'], colPath, errors);
+                if (col.width !== undefined && typeof col.width !== 'string') {
+                    errors.push(`${colPath}.width must be a string`);
+                }
+                if (!Array.isArray(col.children)) {
+                    errors.push(`${colPath}.children must be an array`);
+                    return;
+                }
+                if (col.children.length > MAX_PANEL_LEVEL_CHILDREN) {
+                    errors.push(`${colPath}.children exceeds maximum children per container (${MAX_PANEL_LEVEL_CHILDREN})`);
+                }
+                col.children.forEach((child, childIndex) => validatePanelLevelNode(child, {
+                    path: `${colPath}.children[${childIndex}]`,
+                    depth: depth + 1,
+                    errors,
+                    slotName,
+                    actionIds,
+                    fieldNames,
+                }));
+            });
+            break;
+        }
+        case 'KeyValueList':
+            validateKeyValueListNode(node, { path, errors, fieldNames, template: false });
+            break;
+        case 'MetricCard':
+        case 'BarChart':
+        case 'LineChart':
+        case 'PieChart':
+        case 'Histogram':
+            hasOnlyKeys(node, ['type', 'props'], path, errors);
+            break;
+        case 'ProgressBar':
+        case 'StatusBadge':
+        case 'Timeline':
+            hasOnlyKeys(node, ['type', 'source', 'label'], path, errors);
+            if (node.source !== undefined && typeof node.source !== 'string') {
+                errors.push(`${path}.source must be a string`);
+            }
+            if (node.label !== undefined && typeof node.label !== 'string') {
+                errors.push(`${path}.label must be a string`);
+            }
+            break;
+        case 'LogBlock':
+            hasOnlyKeys(node, ['type', 'source', 'title', 'maxLines', 'emptyText'], path, errors);
+            if (node.source !== undefined && typeof node.source !== 'string') {
+                errors.push(`${path}.source must be a string`);
+            }
+            if (node.title !== undefined && typeof node.title !== 'string') {
+                errors.push(`${path}.title must be a string`);
+            }
+            if (node.maxLines !== undefined && (typeof node.maxLines !== 'number'
+                || !Number.isInteger(node.maxLines)
+                || node.maxLines < 1
+                || node.maxLines > 500)) {
+                errors.push(`${path}.maxLines must be an integer from 1 to 500`);
+            }
+            if (node.emptyText !== undefined && typeof node.emptyText !== 'string') {
+                errors.push(`${path}.emptyText must be a string`);
+            }
+            break;
+        case 'RunStatusCard':
+            hasOnlyKeys(node, ['type', 'run', 'showTarget', 'showRevision'], path, errors);
+            validateToolRunSelector(node.run, `${path}.run`, errors);
+            if (node.showTarget !== undefined && typeof node.showTarget !== 'boolean') {
+                errors.push(`${path}.showTarget must be a boolean`);
+            }
+            if (node.showRevision !== undefined && typeof node.showRevision !== 'boolean') {
+                errors.push(`${path}.showRevision must be a boolean`);
+            }
+            break;
+        case 'RunLogViewer':
+            hasOnlyKeys(node, ['type', 'run', 'maxLines', 'levels', 'emptyText'], path, errors);
+            validateToolRunSelector(node.run, `${path}.run`, errors);
+            if (node.maxLines !== undefined && (typeof node.maxLines !== 'number'
+                || !Number.isInteger(node.maxLines)
+                || node.maxLines < 1
+                || node.maxLines > 500)) {
+                errors.push(`${path}.maxLines must be an integer from 1 to 500`);
+            }
+            validateStringArrayOption(node.levels, `${path}.levels`, errors);
+            if (node.emptyText !== undefined && typeof node.emptyText !== 'string') {
+                errors.push(`${path}.emptyText must be a string`);
+            }
+            break;
+        case 'ArtifactList':
+            hasOnlyKeys(node, ['type', 'run', 'kinds', 'emptyText'], path, errors);
+            validateToolRunSelector(node.run, `${path}.run`, errors);
+            validateStringArrayOption(node.kinds, `${path}.kinds`, errors);
+            if (node.emptyText !== undefined && typeof node.emptyText !== 'string') {
+                errors.push(`${path}.emptyText must be a string`);
+            }
+            break;
+        case 'AggregateValue': {
+            hasOnlyKeys(node, ['type', 'op', 'scope', 'field', 'label', 'precision', 'prefix', 'suffix', 'fallback'], path, errors);
+            const validOps = new Set(['count', 'sum', 'avg', 'min', 'max']);
+            if (typeof node.op !== 'string' || !validOps.has(node.op)) {
+                errors.push(`${path}.op must be count, sum, avg, min, or max`);
+            }
+            if (node.scope !== undefined && node.scope !== 'page' && node.scope !== 'dataset') {
+                errors.push(`${path}.scope must be page or dataset`);
+            }
+            if (node.field !== undefined && (typeof node.field !== 'string' || !fieldNames.has(node.field))) {
+                errors.push(`${path}.field references an unknown field`);
+            }
+            if (node.op !== 'count' && typeof node.field !== 'string') {
+                errors.push(`${path}.field is required for ${node.op}`);
+            }
+            if (node.label !== undefined && typeof node.label !== 'string') {
+                errors.push(`${path}.label must be a string`);
+            }
+            if (node.precision !== undefined && (typeof node.precision !== 'number'
+                || !Number.isInteger(node.precision)
+                || node.precision < 0
+                || node.precision > 6)) {
+                errors.push(`${path}.precision must be an integer from 0 to 6`);
+            }
+            if (node.prefix !== undefined && typeof node.prefix !== 'string') {
+                errors.push(`${path}.prefix must be a string`);
+            }
+            if (node.suffix !== undefined && typeof node.suffix !== 'string') {
+                errors.push(`${path}.suffix must be a string`);
+            }
+            if (node.fallback !== undefined && typeof node.fallback !== 'string') {
+                errors.push(`${path}.fallback must be a string`);
+            }
+            break;
+        }
+        case 'TextInput':
+        case 'TextArea':
+        case 'NumberInput':
+        case 'Checkbox':
+        case 'Select':
+        case 'MultiSelect':
+        case 'TagInput':
+        case 'Slider':
+        case 'DatePicker':
+        case 'FileUpload':
+            hasOnlyKeys(node, ['type', 'props'], path, errors);
+            break;
+        case 'ActionBar':
+            hasOnlyKeys(node, ['type', 'actionIds', 'layout', 'title', 'showDescriptions', 'showHelp'], path, errors);
+            if (node.actionIds !== undefined) {
+                if (!Array.isArray(node.actionIds)) {
+                    errors.push(`${path}.actionIds must be an array`);
+                }
+                else {
+                    node.actionIds.forEach((actionId, index) => {
+                        if (typeof actionId !== 'string' || !actionIds.has(actionId)) {
+                            errors.push(`${path}.actionIds[${index}] references an unknown action id`);
+                        }
+                    });
+                }
+            }
+            if (node.layout !== undefined && node.layout !== 'wrap' && node.layout !== 'stack') {
+                errors.push(`${path}.layout must be wrap or stack`);
+            }
+            if (node.title !== undefined && typeof node.title !== 'string') {
+                errors.push(`${path}.title must be a string`);
+            }
+            if (node.showDescriptions !== undefined && typeof node.showDescriptions !== 'boolean') {
+                errors.push(`${path}.showDescriptions must be a boolean`);
+            }
+            if (node.showHelp !== undefined && typeof node.showHelp !== 'boolean') {
+                errors.push(`${path}.showHelp must be a boolean`);
+            }
+            break;
+        case 'Button':
+            hasOnlyKeys(node, ['type', 'props'], path, errors);
+            break;
+        default:
+            errors.push(`Unknown panel-level node type: ${type}`);
+            break;
+    }
+}
+function validateTemplateNode(node, options) {
+    const { fieldNames, fieldTypes, mediaSlotNames, mediaSlotDisplayTypes, actionIds, path, depth, errors } = options;
+    if (depth > MAX_TEMPLATE_DEPTH) {
+        errors.push(`${path} exceeds max depth ${MAX_TEMPLATE_DEPTH}`);
+        return;
+    }
+    if (!isRecord(node)) {
+        errors.push(`${path} must be an object`);
+        return;
+    }
+    const type = node.type;
+    if (typeof type !== 'string') {
+        errors.push(`${path}.type is required`);
+        return;
+    }
+    if (isPanelLevelOnlyType(type)) {
+        errors.push(`Row template may not contain panel-level node: ${type}`);
+        return;
+    }
+    validateVisibilityCondition(node.visibleWhen, { fieldNames, path, errors });
+    const requireStringRef = (key, refs) => {
+        const value = node[key];
+        if (typeof value !== 'string' || !refs.has(value)) {
+            errors.push(`${path}.${key} references an unknown ${key === 'slot' ? 'media slot' : 'field'}`);
+        }
+    };
+    switch (type) {
+        case 'Row':
+        case 'Column': {
+            hasOnlyTemplateKeys(node, ['type', 'children', 'gap', 'align'], path, errors);
+            if (node.gap !== undefined && node.gap !== 'none' && node.gap !== 'sm' && node.gap !== 'md' && node.gap !== 'lg') {
+                errors.push(`${path}.gap must be none, sm, md, or lg`);
+            }
+            if (node.align !== undefined && node.align !== 'start' && node.align !== 'center' && node.align !== 'end' && node.align !== 'stretch') {
+                errors.push(`${path}.align must be start, center, end, or stretch`);
+            }
+            if (!Array.isArray(node.children)) {
+                errors.push(`${path}.children must be an array`);
+                return;
+            }
+            if (node.children.length > MAX_TEMPLATE_CHILDREN) {
+                errors.push(`${path}.children exceeds max ${MAX_TEMPLATE_CHILDREN}`);
+            }
+            node.children.forEach((child, index) => validateTemplateNode(child, {
+                fieldNames,
+                fieldTypes,
+                mediaSlotNames,
+                mediaSlotDisplayTypes,
+                actionIds,
+                path: `${path}.children[${index}]`,
+                depth: depth + 1,
+                errors,
+            }));
+            break;
+        }
+        case 'Card': {
+            hasOnlyTemplateKeys(node, ['type', 'children', 'title', 'titleField'], path, errors);
+            if (node.title !== undefined && typeof node.title !== 'string')
+                errors.push(`${path}.title must be a string`);
+            if (node.titleField !== undefined && (typeof node.titleField !== 'string' || !fieldNames.has(node.titleField))) {
+                errors.push(`${path}.titleField references an unknown field`);
+            }
+            if (!Array.isArray(node.children)) {
+                errors.push(`${path}.children must be an array`);
+                return;
+            }
+            if (node.children.length > MAX_TEMPLATE_CHILDREN) {
+                errors.push(`${path}.children exceeds max ${MAX_TEMPLATE_CHILDREN}`);
+            }
+            node.children.forEach((child, index) => validateTemplateNode(child, {
+                fieldNames,
+                fieldTypes,
+                mediaSlotNames,
+                mediaSlotDisplayTypes,
+                actionIds,
+                path: `${path}.children[${index}]`,
+                depth: depth + 1,
+                errors,
+            }));
+            break;
+        }
+        case 'Tabs': {
+            hasOnlyTemplateKeys(node, ['type', 'items', 'defaultIndex'], path, errors);
+            const defaultIndex = node.defaultIndex;
+            if (defaultIndex !== undefined && (typeof defaultIndex !== 'number' || !Number.isInteger(defaultIndex) || defaultIndex < 0)) {
+                errors.push(`${path}.defaultIndex must be a non-negative integer`);
+            }
+            if (!Array.isArray(node.items)) {
+                errors.push(`${path}.items must be an array`);
+                return;
+            }
+            if (node.items.length > MAX_TEMPLATE_CHILDREN) {
+                errors.push(`${path}.items exceeds max ${MAX_TEMPLATE_CHILDREN}`);
+            }
+            node.items.forEach((item, index) => {
+                const itemPath = `${path}.items[${index}]`;
+                if (!isRecord(item)) {
+                    errors.push(`${itemPath} must be an object`);
+                    return;
+                }
+                hasOnlyKeys(item, ['label', 'node'], itemPath, errors);
+                if (typeof item.label !== 'string')
+                    errors.push(`${itemPath}.label must be a string`);
+                validateTemplateNode(item.node, {
+                    fieldNames,
+                    fieldTypes,
+                    mediaSlotNames,
+                    mediaSlotDisplayTypes,
+                    actionIds,
+                    path: `${itemPath}.node`,
+                    depth: depth + 1,
+                    errors,
+                });
+            });
+            break;
+        }
+        case 'Stack':
+        case 'Inline':
+        case 'Grid': {
+            const allowedKeys = type === 'Stack'
+                ? ['type', 'children', 'direction', 'gap', 'align', 'wrap']
+                : type === 'Inline'
+                    ? ['type', 'children', 'gap', 'align', 'wrap']
+                    : ['type', 'children', 'minColumnWidth', 'maxColumns', 'gap'];
+            hasOnlyTemplateKeys(node, allowedKeys, path, errors);
+            if (type === 'Stack' && node.direction !== undefined && node.direction !== 'vertical' && node.direction !== 'horizontal') {
+                errors.push(`${path}.direction must be vertical or horizontal`);
+            }
+            if (type === 'Stack' || type === 'Inline') {
+                validateLayoutGap(node.gap, `${path}.gap`, errors);
+                validateLayoutAlign(node.align, `${path}.align`, errors, type === 'Stack');
+                if (node.wrap !== undefined && typeof node.wrap !== 'boolean') {
+                    errors.push(`${path}.wrap must be a boolean`);
+                }
+            }
+            else {
+                validateLayoutGap(node.gap, `${path}.gap`, errors, false);
+                if (node.minColumnWidth !== undefined && (typeof node.minColumnWidth !== 'number'
+                    || !Number.isInteger(node.minColumnWidth)
+                    || node.minColumnWidth < 80
+                    || node.minColumnWidth > 640)) {
+                    errors.push(`${path}.minColumnWidth must be an integer from 80 to 640`);
+                }
+                if (node.maxColumns !== undefined && (typeof node.maxColumns !== 'number'
+                    || !Number.isInteger(node.maxColumns)
+                    || node.maxColumns < 1
+                    || node.maxColumns > 12)) {
+                    errors.push(`${path}.maxColumns must be an integer from 1 to 12`);
+                }
+            }
+            if (!Array.isArray(node.children)) {
+                errors.push(`${path}.children must be an array`);
+                return;
+            }
+            if (node.children.length > MAX_TEMPLATE_CHILDREN) {
+                errors.push(`${path}.children exceeds max ${MAX_TEMPLATE_CHILDREN}`);
+            }
+            node.children.forEach((child, index) => validateTemplateNode(child, {
+                fieldNames,
+                fieldTypes,
+                mediaSlotNames,
+                mediaSlotDisplayTypes,
+                actionIds,
+                path: `${path}.children[${index}]`,
+                depth: depth + 1,
+                errors,
+            }));
+            break;
+        }
+        case 'KeyValueList':
+            validateKeyValueListNode(node, { path, errors, fieldNames, template: true });
+            break;
+        case 'TextField':
+            hasOnlyTemplateKeys(node, ['type', 'field', 'label', 'fallback'], path, errors);
+            requireStringRef('field', fieldNames);
+            if (node.label !== undefined && typeof node.label !== 'string')
+                errors.push(`${path}.label must be a string`);
+            if (node.fallback !== undefined && typeof node.fallback !== 'string')
+                errors.push(`${path}.fallback must be a string`);
+            break;
+        case 'LatexBlock':
+            hasOnlyTemplateKeys(node, ['type', 'field', 'fallback'], path, errors);
+            requireStringRef('field', fieldNames);
+            if (node.fallback !== undefined && typeof node.fallback !== 'string')
+                errors.push(`${path}.fallback must be a string`);
+            break;
+        case 'MarkdownField':
+            hasOnlyTemplateKeys(node, ['type', 'field', 'fallback'], path, errors);
+            requireStringRef('field', fieldNames);
+            if (node.fallback !== undefined && typeof node.fallback !== 'string')
+                errors.push(`${path}.fallback must be a string`);
+            break;
+        case 'CodeField':
+            hasOnlyTemplateKeys(node, ['type', 'field', 'language', 'languageField', 'fallback'], path, errors);
+            requireStringRef('field', fieldNames);
+            if (node.language !== undefined && typeof node.language !== 'string')
+                errors.push(`${path}.language must be a string`);
+            if (node.languageField !== undefined && (typeof node.languageField !== 'string' || !fieldNames.has(node.languageField))) {
+                errors.push(`${path}.languageField references an unknown field`);
+            }
+            if (node.fallback !== undefined && typeof node.fallback !== 'string')
+                errors.push(`${path}.fallback must be a string`);
+            break;
+        case 'JsonField':
+            hasOnlyTemplateKeys(node, ['type', 'field', 'expanded', 'fallback'], path, errors);
+            requireStringRef('field', fieldNames);
+            if (node.expanded !== undefined && typeof node.expanded !== 'boolean')
+                errors.push(`${path}.expanded must be a boolean`);
+            if (node.fallback !== undefined && typeof node.fallback !== 'string')
+                errors.push(`${path}.fallback must be a string`);
+            break;
+        case 'DiffField':
+            hasOnlyTemplateKeys(node, ['type', 'leftField', 'rightField', 'mode', 'title'], path, errors);
+            if (typeof node.leftField !== 'string' || !fieldNames.has(node.leftField)) {
+                errors.push(`${path}.leftField references an unknown field`);
+            }
+            if (typeof node.rightField !== 'string' || !fieldNames.has(node.rightField)) {
+                errors.push(`${path}.rightField references an unknown field`);
+            }
+            if (node.mode !== undefined && node.mode !== 'line' && node.mode !== 'char') {
+                errors.push(`${path}.mode must be line or char`);
+            }
+            if (node.title !== undefined && typeof node.title !== 'string')
+                errors.push(`${path}.title must be a string`);
+            break;
+        case 'Badge':
+            hasOnlyTemplateKeys(node, ['type', 'field', 'label', 'variant', 'valueMap', 'fallback'], path, errors);
+            requireStringRef('field', fieldNames);
+            if (node.label !== undefined && typeof node.label !== 'string')
+                errors.push(`${path}.label must be a string`);
+            if (node.variant !== undefined && !isValidBadgeVariant(node.variant)) {
+                errors.push(`${path}.variant must be default, success, warning, or danger`);
+            }
+            if (node.fallback !== undefined && typeof node.fallback !== 'string')
+                errors.push(`${path}.fallback must be a string`);
+            if (node.valueMap !== undefined) {
+                if (!Array.isArray(node.valueMap)) {
+                    errors.push(`${path}.valueMap must be an array`);
+                }
+                else if (node.valueMap.length > 50) {
+                    errors.push(`${path}.valueMap exceeds max 50`);
+                }
+                else {
+                    node.valueMap.forEach((entry, index) => {
+                        const entryPath = `${path}.valueMap[${index}]`;
+                        if (!isRecord(entry)) {
+                            errors.push(`${entryPath} must be an object`);
+                            return;
+                        }
+                        hasOnlyKeys(entry, ['value', 'label', 'variant'], entryPath, errors);
+                        if (!Object.prototype.hasOwnProperty.call(entry, 'value')
+                            || !isPrimitiveMapValue(entry.value)
+                            || (typeof entry.value === 'number' && !Number.isFinite(entry.value))) {
+                            errors.push(`${entryPath}.value must be a string, finite number, boolean, or null`);
+                        }
+                        if (entry.label !== undefined && typeof entry.label !== 'string')
+                            errors.push(`${entryPath}.label must be a string`);
+                        if (entry.variant !== undefined && !isValidBadgeVariant(entry.variant)) {
+                            errors.push(`${entryPath}.variant must be default, success, warning, or danger`);
+                        }
+                    });
+                }
+            }
+            break;
+        case 'ComputedValue': {
+            hasOnlyTemplateKeys(node, ['type', 'op', 'fields', 'weights', 'label', 'precision', 'prefix', 'suffix', 'separator', 'fallback'], path, errors);
+            const op = node.op;
+            const validOps = new Set(['sum', 'difference', 'product', 'ratio', 'percent', 'average', 'weighted_sum', 'concat']);
+            if (typeof op !== 'string' || !validOps.has(op)) {
+                errors.push(`${path}.op must be sum, difference, product, ratio, percent, average, weighted_sum, or concat`);
+            }
+            if (!Array.isArray(node.fields)) {
+                errors.push(`${path}.fields must be an array`);
+                break;
+            }
+            if (node.fields.length === 0 || node.fields.length > 8) {
+                errors.push(`${path}.fields must contain 1-8 fields`);
+            }
+            if ((op === 'difference' || op === 'ratio' || op === 'percent') && node.fields.length !== 2) {
+                errors.push(`${path}.fields must contain exactly 2 fields for ${op}`);
+            }
+            if (op === 'weighted_sum') {
+                if (!Array.isArray(node.weights)) {
+                    errors.push(`${path}.weights must be an array for weighted_sum`);
+                }
+                else {
+                    if (node.weights.length !== node.fields.length) {
+                        errors.push(`${path}.weights must have the same length as fields for weighted_sum`);
+                    }
+                    node.weights.forEach((weight, index) => {
+                        if (typeof weight !== 'number' || !Number.isFinite(weight)) {
+                            errors.push(`${path}.weights[${index}] must be a finite number`);
+                        }
+                    });
+                }
+            }
+            else if (node.weights !== undefined) {
+                errors.push(`${path}.weights is only allowed for weighted_sum`);
+            }
+            node.fields.forEach((field, index) => {
+                if (typeof field !== 'string' || !fieldNames.has(field)) {
+                    errors.push(`${path}.fields[${index}] references an unknown field`);
+                    return;
+                }
+                if (op !== 'concat' && fieldTypes.get(field) !== 'number') {
+                    errors.push(`${path}.fields[${index}] must reference a number field for ${op}`);
+                }
+            });
+            if (node.label !== undefined && typeof node.label !== 'string')
+                errors.push(`${path}.label must be a string`);
+            if (node.precision !== undefined
+                && (typeof node.precision !== 'number' || !Number.isInteger(node.precision) || node.precision < 0 || node.precision > 6)) {
+                errors.push(`${path}.precision must be an integer from 0 to 6`);
+            }
+            if (node.prefix !== undefined && typeof node.prefix !== 'string')
+                errors.push(`${path}.prefix must be a string`);
+            if (node.suffix !== undefined && typeof node.suffix !== 'string')
+                errors.push(`${path}.suffix must be a string`);
+            if (node.separator !== undefined && typeof node.separator !== 'string')
+                errors.push(`${path}.separator must be a string`);
+            if (node.fallback !== undefined && typeof node.fallback !== 'string')
+                errors.push(`${path}.fallback must be a string`);
+            break;
+        }
+        case 'ImageSlot':
+            hasOnlyTemplateKeys(node, ['type', 'slot', 'labelField', 'annotationsField', 'editable', 'newAnnotationLabel', 'shortcutLabels'], path, errors);
+            requireStringRef('slot', mediaSlotNames);
+            if (node.labelField !== undefined && (typeof node.labelField !== 'string' || !fieldNames.has(node.labelField))) {
+                errors.push(`${path}.labelField references an unknown field`);
+            }
+            if (node.annotationsField !== undefined && (typeof node.annotationsField !== 'string' || !fieldNames.has(node.annotationsField))) {
+                errors.push(`${path}.annotationsField references an unknown field`);
+            }
+            if (node.editable !== undefined && typeof node.editable !== 'boolean') {
+                errors.push(`${path}.editable must be a boolean`);
+            }
+            if (node.editable === true && typeof node.annotationsField !== 'string') {
+                errors.push(`${path}.editable requires annotationsField`);
+            }
+            if (node.newAnnotationLabel !== undefined && typeof node.newAnnotationLabel !== 'string') {
+                errors.push(`${path}.newAnnotationLabel must be a string`);
+            }
+            if (node.shortcutLabels !== undefined) {
+                if (!Array.isArray(node.shortcutLabels)) {
+                    errors.push(`${path}.shortcutLabels must be an array`);
+                }
+                else {
+                    if (node.shortcutLabels.length > 20) {
+                        errors.push(`${path}.shortcutLabels exceeds max 20`);
+                    }
+                    node.shortcutLabels.forEach((shortcut, index) => {
+                        const shortcutPath = `${path}.shortcutLabels[${index}]`;
+                        if (!isRecord(shortcut)) {
+                            errors.push(`${shortcutPath} must be an object`);
+                            return;
+                        }
+                        hasOnlyKeys(shortcut, ['key', 'label', 'color'], shortcutPath, errors);
+                        if (typeof shortcut.key !== 'string' || shortcut.key.trim().length === 0 || shortcut.key.length > 10) {
+                            errors.push(`${shortcutPath}.key must be a non-empty string up to 10 characters`);
+                        }
+                        if (typeof shortcut.label !== 'string' || shortcut.label.trim().length === 0) {
+                            errors.push(`${shortcutPath}.label must be a non-empty string`);
+                        }
+                        if (shortcut.color !== undefined && typeof shortcut.color !== 'string') {
+                            errors.push(`${shortcutPath}.color must be a string`);
+                        }
+                    });
+                }
+            }
+            break;
+        case 'MediaBlock':
+            hasOnlyTemplateKeys(node, ['type', 'slot', 'labelField', 'displayType', 'maxLines', 'annotationsField', 'editable', 'newAnnotationLabel', 'shortcutLabels'], path, errors);
+            requireStringRef('slot', mediaSlotNames);
+            if (node.labelField !== undefined && (typeof node.labelField !== 'string' || !fieldNames.has(node.labelField))) {
+                errors.push(`${path}.labelField references an unknown field`);
+            }
+            if (node.displayType !== undefined && node.displayType !== 'img' && node.displayType !== 'text' && node.displayType !== 'latex') {
+                errors.push(`${path}.displayType must be img, text, or latex`);
+            }
+            if (typeof node.slot === 'string' && mediaSlotDisplayTypes.has(node.slot) && node.displayType !== undefined && mediaSlotDisplayTypes.get(node.slot) !== node.displayType) {
+                errors.push(`${path}.displayType must match declared media slot displayType`);
+            }
+            const effectiveMediaDisplayType = node.displayType ?? (typeof node.slot === 'string' ? mediaSlotDisplayTypes.get(node.slot) : undefined);
+            if (effectiveMediaDisplayType === 'text' || effectiveMediaDisplayType === 'latex') {
+                for (const imageOnlyKey of ['annotationsField', 'editable', 'newAnnotationLabel', 'shortcutLabels']) {
+                    if (node[imageOnlyKey] !== undefined) {
+                        errors.push(`${path}.${imageOnlyKey} is only allowed when displayType is img`);
+                    }
+                }
+            }
+            if (node.maxLines !== undefined && (typeof node.maxLines !== 'number'
+                || !Number.isInteger(node.maxLines)
+                || node.maxLines < 1
+                || node.maxLines > 500)) {
+                errors.push(`${path}.maxLines must be an integer from 1 to 500`);
+            }
+            if (node.annotationsField !== undefined && (typeof node.annotationsField !== 'string' || !fieldNames.has(node.annotationsField))) {
+                errors.push(`${path}.annotationsField references an unknown field`);
+            }
+            if (node.editable !== undefined && typeof node.editable !== 'boolean') {
+                errors.push(`${path}.editable must be a boolean`);
+            }
+            if (node.editable === true && typeof node.annotationsField !== 'string') {
+                errors.push(`${path}.editable requires annotationsField`);
+            }
+            if (node.newAnnotationLabel !== undefined && typeof node.newAnnotationLabel !== 'string') {
+                errors.push(`${path}.newAnnotationLabel must be a string`);
+            }
+            if (node.shortcutLabels !== undefined) {
+                if (!Array.isArray(node.shortcutLabels)) {
+                    errors.push(`${path}.shortcutLabels must be an array`);
+                }
+                else {
+                    if (node.shortcutLabels.length > 20) {
+                        errors.push(`${path}.shortcutLabels exceeds max 20`);
+                    }
+                    node.shortcutLabels.forEach((shortcut, index) => {
+                        const shortcutPath = `${path}.shortcutLabels[${index}]`;
+                        if (!isRecord(shortcut)) {
+                            errors.push(`${shortcutPath} must be an object`);
+                            return;
+                        }
+                        hasOnlyKeys(shortcut, ['key', 'label', 'color'], shortcutPath, errors);
+                        if (typeof shortcut.key !== 'string' || shortcut.key.trim().length === 0 || shortcut.key.length > 10) {
+                            errors.push(`${shortcutPath}.key must be a non-empty string up to 10 characters`);
+                        }
+                        if (typeof shortcut.label !== 'string' || shortcut.label.trim().length === 0) {
+                            errors.push(`${shortcutPath}.label must be a non-empty string`);
+                        }
+                        if (shortcut.color !== undefined && typeof shortcut.color !== 'string') {
+                            errors.push(`${shortcutPath}.color must be a string`);
+                        }
+                    });
+                }
+            }
+            break;
+        case 'Checkbox':
+            hasOnlyTemplateKeys(node, ['type', 'label'], path, errors);
+            if (node.label !== undefined && typeof node.label !== 'string')
+                errors.push(`${path}.label must be a string`);
+            break;
+        case 'FormField':
+            hasOnlyTemplateKeys(node, ['type', 'name', 'label', 'field', 'input', 'placeholder', 'options'], path, errors);
+            if (typeof node.name !== 'string' || !FIELD_NAME_PATTERN.test(node.name)) {
+                errors.push(`${path}.name must be a safe field name`);
+            }
+            if (node.label !== undefined && typeof node.label !== 'string')
+                errors.push(`${path}.label must be a string`);
+            if (node.field !== undefined && (typeof node.field !== 'string' || !fieldNames.has(node.field))) {
+                errors.push(`${path}.field references an unknown field`);
+            }
+            if (node.input !== undefined
+                && node.input !== 'text'
+                && node.input !== 'number'
+                && node.input !== 'checkbox'
+                && node.input !== 'textarea'
+                && node.input !== 'select'
+                && node.input !== 'tags') {
+                errors.push(`${path}.input must be text, number, checkbox, textarea, select, or tags`);
+            }
+            if (typeof node.field === 'string' && fieldNames.has(node.field) && typeof node.input === 'string') {
+                const fieldType = fieldTypes.get(node.field);
+                if (node.input === 'number' && fieldType !== 'number') {
+                    errors.push(`${path}.input number requires a number field`);
+                }
+                if (node.input === 'checkbox' && fieldType !== 'boolean') {
+                    errors.push(`${path}.input checkbox requires a boolean field`);
+                }
+                if (node.input === 'tags') {
+                    errors.push(`${path}.input tags may not bind field because dataset fields are scalar`);
+                }
+            }
+            if (node.placeholder !== undefined && typeof node.placeholder !== 'string')
+                errors.push(`${path}.placeholder must be a string`);
+            if (node.options !== undefined && node.input !== 'select') {
+                errors.push(`${path}.options is only allowed when input is select`);
+            }
+            if (node.input === 'select') {
+                if (!Array.isArray(node.options)) {
+                    errors.push(`${path}.options must be a non-empty array for select`);
+                }
+                else if (node.options.length === 0) {
+                    errors.push(`${path}.options must include at least one option for select`);
+                }
+                else if (node.options.length > MAX_FORM_FIELD_OPTIONS) {
+                    errors.push(`${path}.options exceeds max ${MAX_FORM_FIELD_OPTIONS}`);
+                }
+                else {
+                    const fieldType = typeof node.field === 'string' ? fieldTypes.get(node.field) : undefined;
+                    node.options.forEach((option, index) => {
+                        const optionPath = `${path}.options[${index}]`;
+                        if (!isRecord(option)) {
+                            errors.push(`${optionPath} must be an object`);
+                            return;
+                        }
+                        hasOnlyKeys(option, ['label', 'value'], optionPath, errors);
+                        if (!Object.prototype.hasOwnProperty.call(option, 'value') || !isFormFieldOptionValue(option.value)) {
+                            errors.push(`${optionPath}.value must be a string, finite number, or boolean`);
+                        }
+                        else if (fieldType !== undefined && typeof option.value !== fieldType) {
+                            errors.push(`${optionPath}.value must match selected field type ${fieldType}`);
+                        }
+                        if (option.label !== undefined && typeof option.label !== 'string') {
+                            errors.push(`${optionPath}.label must be a string`);
+                        }
+                    });
+                }
+            }
+            break;
+        case 'Sparkline':
+            hasOnlyTemplateKeys(node, ['type', 'field'], path, errors);
+            if (typeof node.field !== 'string' || !fieldNames.has(node.field)) {
+                errors.push(`${path}.field references an unknown field`);
+            }
+            break;
+        case 'Accordion': {
+            hasOnlyTemplateKeys(node, ['type', 'title', 'children', 'expanded'], path, errors);
+            if (typeof node.title !== 'string') {
+                errors.push(`${path}.title must be a string`);
+            }
+            if (node.expanded !== undefined && typeof node.expanded !== 'boolean') {
+                errors.push(`${path}.expanded must be a boolean`);
+            }
+            if (!Array.isArray(node.children)) {
+                errors.push(`${path}.children must be an array`);
+                break;
+            }
+            if (node.children.length > MAX_TEMPLATE_CHILDREN) {
+                errors.push(`${path}.children exceeds max ${MAX_TEMPLATE_CHILDREN}`);
+            }
+            node.children.forEach((child, index) => validateTemplateNode(child, {
+                fieldNames,
+                fieldTypes,
+                mediaSlotNames,
+                mediaSlotDisplayTypes,
+                actionIds,
+                path: `${path}.children[${index}]`,
+                depth: depth + 1,
+                errors,
+            }));
+            break;
+        }
+        case 'Divider': {
+            hasOnlyTemplateKeys(node, ['type', 'title'], path, errors);
+            if (node.title !== undefined && typeof node.title !== 'string') {
+                errors.push(`${path}.title must be a string`);
+            }
+            break;
+        }
+        case 'Callout': {
+            hasOnlyTemplateKeys(node, ['type', 'calloutType', 'title', 'content'], path, errors);
+            if (!['info', 'warning', 'success', 'error'].includes(node.calloutType)) {
+                errors.push(`${path}.calloutType must be info, warning, success, or error`);
+            }
+            if (node.title !== undefined && typeof node.title !== 'string') {
+                errors.push(`${path}.title must be a string`);
+            }
+            if (node.content !== undefined && typeof node.content !== 'string') {
+                errors.push(`${path}.content must be a string`);
+            }
+            break;
+        }
+        case 'Columns': {
+            hasOnlyTemplateKeys(node, ['type', 'columns'], path, errors);
+            if (!Array.isArray(node.columns)) {
+                errors.push(`${path}.columns must be an array`);
+                break;
+            }
+            if (node.columns.length > MAX_TEMPLATE_CHILDREN) {
+                errors.push(`${path}.columns exceeds max ${MAX_TEMPLATE_CHILDREN}`);
+            }
+            node.columns.forEach((col, index) => {
+                const colPath = `${path}.columns[${index}]`;
+                if (!isRecord(col)) {
+                    errors.push(`${colPath} must be an object`);
+                    return;
+                }
+                hasOnlyKeys(col, ['width', 'children'], colPath, errors);
+                if (col.width !== undefined && typeof col.width !== 'string') {
+                    errors.push(`${colPath}.width must be a string`);
+                }
+                if (!Array.isArray(col.children)) {
+                    errors.push(`${colPath}.children must be an array`);
+                    return;
+                }
+                if (col.children.length > MAX_TEMPLATE_CHILDREN) {
+                    errors.push(`${colPath}.children exceeds max ${MAX_TEMPLATE_CHILDREN}`);
+                }
+                col.children.forEach((child, childIndex) => validateTemplateNode(child, {
+                    fieldNames,
+                    fieldTypes,
+                    mediaSlotNames,
+                    mediaSlotDisplayTypes,
+                    actionIds,
+                    path: `${colPath}.children[${childIndex}]`,
+                    depth: depth + 1,
+                    errors,
+                }));
+            });
+            break;
+        }
+        case 'ActionButton':
+            hasOnlyTemplateKeys(node, ['type', 'actionId', 'label', 'help', 'showHelp'], path, errors);
+            if (typeof node.actionId !== 'string' || !actionIds.has(node.actionId)) {
+                errors.push(`${path}.actionId references an unknown action id`);
+            }
+            if (node.label !== undefined && typeof node.label !== 'string')
+                errors.push(`${path}.label must be a string`);
+            if (node.help !== undefined && typeof node.help !== 'string')
+                errors.push(`${path}.help must be a string`);
+            if (node.showHelp !== undefined && typeof node.showHelp !== 'boolean')
+                errors.push(`${path}.showHelp must be a boolean`);
+            break;
+        case 'SubmitButton':
+            hasOnlyTemplateKeys(node, ['type', 'submitKind', 'label', 'variant', 'help', 'showHelp'], path, errors);
+            if (node.submitKind !== 'form' && node.submitKind !== 'apply' && node.submitKind !== 'done') {
+                errors.push(`${path}.submitKind must be form, apply, or done`);
+            }
+            if (node.label !== undefined && typeof node.label !== 'string')
+                errors.push(`${path}.label must be a string`);
+            if (node.variant !== undefined && node.variant !== 'primary' && node.variant !== 'secondary' && node.variant !== 'danger') {
+                errors.push(`${path}.variant must be primary, secondary, or danger`);
+            }
+            if (node.help !== undefined && typeof node.help !== 'string')
+                errors.push(`${path}.help must be a string`);
+            if (node.showHelp !== undefined && typeof node.showHelp !== 'boolean')
+                errors.push(`${path}.showHelp must be a boolean`);
+            break;
+        case 'DiffView':
+            hasOnlyTemplateKeys(node, ['type', 'left', 'right', 'mode'], path, errors);
+            if (typeof node.left !== 'string')
+                errors.push(`${path}.left must be a string`);
+            if (typeof node.right !== 'string')
+                errors.push(`${path}.right must be a string`);
+            if (node.mode !== undefined && node.mode !== 'line' && node.mode !== 'char') {
+                errors.push(`${path}.mode must be line or char`);
+            }
+            break;
+        case 'CodeBlock':
+            hasOnlyTemplateKeys(node, ['type', 'code', 'language'], path, errors);
+            if (typeof node.code !== 'string')
+                errors.push(`${path}.code must be a string`);
+            if (node.language !== undefined && typeof node.language !== 'string')
+                errors.push(`${path}.language must be a string`);
+            break;
+        case 'JsonView':
+            hasOnlyTemplateKeys(node, ['type', 'data', 'expanded'], path, errors);
+            if (node.data === undefined)
+                errors.push(`${path}.data is required`);
+            if (node.expanded !== undefined && typeof node.expanded !== 'boolean')
+                errors.push(`${path}.expanded must be a boolean`);
+            break;
+        case 'MarkdownText':
+            hasOnlyTemplateKeys(node, ['type', 'content'], path, errors);
+            if (typeof node.content !== 'string')
+                errors.push(`${path}.content must be a string`);
+            break;
+        default:
+            errors.push(`${path}.type "${type}" is not allowed`);
+            break;
+    }
+}
+export function getEffectiveDatasetSchema(componentOrContract, props) {
+    const contract = typeof componentOrContract === 'string'
+        ? getComponentContract(componentOrContract)
+        : componentOrContract;
+    if (!contract)
+        return undefined;
+    if (contract.name !== 'RowTemplateGrid')
+        return contract.datasetSchema;
+    const fieldResult = validateFieldSchemas(props?.fields, 'props.fields');
+    const mediaResult = validateMediaSlotSchemas(props?.mediaSlots, 'props.mediaSlots');
+    if (fieldResult.errors.length > 0 || mediaResult.errors.length > 0) {
+        return { fields: [], mediaSlots: [] };
+    }
+    return {
+        fields: fieldResult.fields,
+        mediaSlots: mediaResult.mediaSlots,
+    };
+}
+export function validatePanelTemplateProps(componentOrContract, props, actions = []) {
+    const contract = typeof componentOrContract === 'string'
+        ? getComponentContract(componentOrContract)
+        : componentOrContract;
+    if (!contract) {
+        return { ok: false, errors: ['Unknown component contract'] };
+    }
+    if (contract.name !== 'RowTemplateGrid') {
+        return { ok: true, datasetSchema: contract.datasetSchema ?? { fields: [], mediaSlots: [] } };
+    }
+    const fieldResult = validateFieldSchemas(props.fields, 'props.fields');
+    const mediaResult = validateMediaSlotSchemas(props.mediaSlots, 'props.mediaSlots');
+    const errors = [...fieldResult.errors, ...mediaResult.errors];
+    if (fieldResult.fields.length === 0) {
+        errors.push('props.fields must declare at least one field');
+    }
+    if (props.title !== undefined && typeof props.title !== 'string') {
+        errors.push('props.title must be a string');
+    }
+    const actionIds = new Set();
+    for (const action of actions) {
+        if (typeof action.id === 'string' && action.id.trim())
+            actionIds.add(action.id);
+    }
+    validateTemplateNode(props.template, {
+        fieldNames: new Set(fieldResult.fields.map((field) => field.name)),
+        fieldTypes: new Map(fieldResult.fields.map((field) => [field.name, field.type])),
+        mediaSlotNames: new Set(mediaResult.mediaSlots.map((slot) => slot.name)),
+        mediaSlotDisplayTypes: new Map(mediaResult.mediaSlots.map((slot) => [slot.name, slot.displayType])),
+        actionIds,
+        path: 'props.template',
+        depth: 1,
+        errors,
+    });
+    if (props.summary !== undefined && props.summary !== null) {
+        validatePanelLevelNode(props.summary, {
+            path: 'props.summary',
+            depth: 1,
+            errors,
+            slotName: 'summary',
+            actionIds,
+            fieldNames: new Set(fieldResult.fields.map((field) => field.name)),
+        });
+    }
+    if (props.parameterForm !== undefined && props.parameterForm !== null) {
+        validatePanelLevelNode(props.parameterForm, {
+            path: 'props.parameterForm',
+            depth: 1,
+            errors,
+            slotName: 'parameterForm',
+            actionIds,
+            fieldNames: new Set(fieldResult.fields.map((field) => field.name)),
+        });
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return {
+        ok: true,
+        datasetSchema: {
+            fields: fieldResult.fields,
+            mediaSlots: mediaResult.mediaSlots,
+        },
+    };
+}
+const COMPONENT_PROPOSAL_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+export function validateComponentProposal(input, existingContractNames) {
+    const errors = [];
+    if (!isRecord(input)) {
+        return { ok: false, errors: [{ field: '', message: 'Proposal must be an object' }] };
+    }
+    const name = input.name;
+    if (typeof name !== 'string' || !COMPONENT_PROPOSAL_NAME_PATTERN.test(name)) {
+        errors.push({ field: 'name', message: 'name must be a PascalCase identifier (1-64 chars, alphanumeric and underscore, starting with a letter)' });
+    }
+    else if (existingContractNames.has(name)) {
+        errors.push({ field: 'name', message: `name "${name}" collides with an existing component contract` });
+    }
+    const displayName = input.displayName;
+    if (typeof displayName !== 'string' || displayName.trim().length === 0) {
+        errors.push({ field: 'displayName', message: 'displayName is required and must be a non-empty string' });
+    }
+    const description = input.description;
+    if (typeof description !== 'string' || description.trim().length === 0) {
+        errors.push({ field: 'description', message: 'description is required and must be a non-empty string' });
+    }
+    const dataModel = input.dataModel;
+    if (!isRecord(dataModel)) {
+        errors.push({ field: 'dataModel', message: 'dataModel is required and must be an object' });
+    }
+    else {
+        const kind = dataModel.kind;
+        if (kind !== 'inline' && kind !== 'paged_rows') {
+            errors.push({ field: 'dataModel.kind', message: 'dataModel.kind must be "inline" or "paged_rows"' });
+        }
+    }
+    if (input.propsSchema === undefined) {
+        errors.push({ field: 'propsSchema', message: 'propsSchema is required and must be an object' });
+    }
+    else if (!isRecord(input.propsSchema)) {
+        errors.push({ field: 'propsSchema', message: 'propsSchema must be an object' });
+    }
+    if (input.datasetSchema === undefined) {
+        errors.push({ field: 'datasetSchema', message: 'datasetSchema is required and must be an object' });
+    }
+    else {
+        const ds = input.datasetSchema;
+        if (!isRecord(ds)) {
+            errors.push({ field: 'datasetSchema', message: 'datasetSchema must be an object' });
+        }
+        else {
+            if (!Array.isArray(ds.fields)) {
+                errors.push({ field: 'datasetSchema.fields', message: 'datasetSchema.fields must be an array' });
+            }
+            if (ds.mediaSlots !== undefined && !Array.isArray(ds.mediaSlots)) {
+                errors.push({ field: 'datasetSchema.mediaSlots', message: 'datasetSchema.mediaSlots must be an array when provided' });
+            }
+        }
+    }
+    if (typeof input.rationale !== 'string' || input.rationale.trim().length === 0) {
+        errors.push({ field: 'rationale', message: 'rationale is required and must be a non-empty string' });
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true };
+}