@r0hitsharma/dashboard-kit 0.12.0-rohit-fork-ci.1

package/dist/renderer.d.ts

@@ -0,0 +1,38 @@
+import { type JSX } from 'react';
+import { type InteractionContextValue } from './interaction.js';
+import { type ComponentRegistry } from './registry.js';
+import type { DashboardSpec, DashboardDataSources, LayoutNode } from './schema.js';
+type RenderContext = {
+    widgets: DashboardSpec['widgets'];
+    dataSources: DashboardDataSources;
+    registry: ComponentRegistry;
+    interaction: InteractionContextValue;
+};
+export declare function renderLayoutNode(node: LayoutNode, ctx: RenderContext, key: string): JSX.Element;
+export type DashboardRendererProps = {
+    spec: DashboardSpec;
+    dataSources: DashboardDataSources;
+    /**
+     * The string -> component registry. Defaults to {@link DEFAULT_REGISTRY};
+     * pass a merged registry (see `mergeRegistries`) to add domain adapters.
+     */
+    registry?: ComponentRegistry;
+    /**
+     * A real interaction store (e.g. charting-backed via
+     * `useChartingInteraction`). Omit to use a self-contained local store, which
+     * every standalone manifest (a story, a preview) can rely on unchanged.
+     */
+    interaction?: InteractionContextValue;
+    /**
+     * Skip the zod gate. Only for a spec the caller authored and trusts (where
+     * validation is a dev-time assertion, not a trust boundary); leave it on for
+     * any spec an agent or a command bar produced.
+     */
+    skipValidation?: boolean;
+};
+/**
+ * Renders a `DashboardSpec`. Validates first (unless `skipValidation`), showing
+ * an annotated rejection for an invalid manifest rather than throwing.
+ */
+export declare function DashboardRenderer({ spec, dataSources, registry, interaction, skipValidation, }: DashboardRendererProps): JSX.Element;
+export {};

package/dist/renderer.js

@@ -0,0 +1,140 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Panel, SplitLayout } from '@r0hitsharma/design-system';
+import {} from 'react';
+import { useLocalInteraction, } from './interaction.js';
+import { DEFAULT_REGISTRY, UnknownWidget, } from './registry.js';
+import { validateDashboardSpec } from './validate.js';
+/**
+ * The recursive `DashboardSpec` -> JSX renderer. Walks `spec.layout`
+ * (positions/nesting only — see schema.ts for why layout stays separate from
+ * widget config and data binding), resolving each `widget` leaf through
+ * `spec.widgets` and then through the string -> component `registry`. An
+ * unresolved widget ref or component key renders an inline `UnknownWidget`
+ * marker instead of throwing, so one bad manifest entry doesn't blank the
+ * whole dashboard.
+ *
+ * A `split` node with `resizable: true` becomes a design-system `SplitLayout`
+ * (an Ark `Splitter`), one drag-resizable panel per child; otherwise it's a
+ * plain flex box that wraps at narrow widths. Nesting works either way — each
+ * panel's content is just another recursive render.
+ */
+/** Default height for a resizable split that declares none (a `column` split must; validation enforces it). */
+const DEFAULT_RESIZABLE_HEIGHT = '420px';
+const rootStyle = {
+    width: '100%',
+    minWidth: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '1rem',
+};
+const titleStyle = {
+    fontSize: '1.125rem',
+    fontWeight: 600,
+    color: 'var(--colors-text-default, currentColor)',
+    margin: 0,
+};
+const invalidStyle = {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '0.5rem',
+    padding: '1rem',
+    borderRadius: '0.5rem',
+    borderWidth: '1px',
+    borderStyle: 'solid',
+    borderColor: 'var(--colors-border-critical, currentColor)',
+    background: 'var(--colors-bg-critical, transparent)',
+    color: 'var(--colors-text-critical, currentColor)',
+    fontSize: '0.875rem',
+};
+const issueListStyle = {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '0.25rem',
+    fontFamily: 'var(--fonts-mono, monospace)',
+    fontSize: '0.75rem',
+    listStyle: 'none',
+    padding: 0,
+    margin: 0,
+};
+/**
+ * What an invalid manifest renders instead of a dashboard: an annotated list,
+ * not a thrown error — the whole point of the gate is that an agent-submitted
+ * patch produces a readable rejection a human (or the agent) can act on.
+ */
+function InvalidSpec({ issues }) {
+    return (_jsxs("div", { style: invalidStyle, role: "alert", children: [_jsxs("strong", { children: ["This dashboard manifest is invalid (", issues.length, " issue", issues.length === 1 ? '' : 's', ") and was not rendered."] }), _jsx("ul", { style: issueListStyle, children: issues.map((issue) => (_jsxs("li", { children: [_jsx("code", { children: issue.path }), " \u2014 ", issue.message] }, `${issue.path}:${issue.message}`))) })] }));
+}
+function renderWidget(ref, ctx) {
+    const widget = ctx.widgets[ref];
+    if (!widget) {
+        return (_jsx(UnknownWidget, { label: `layout references unknown widget "${ref}"` }));
+    }
+    const Adapter = ctx.registry[widget.component];
+    if (!Adapter) {
+        return _jsx(UnknownWidget, { label: widget.component });
+    }
+    const data = widget.dataBinding
+        ? (ctx.dataSources[widget.dataBinding.source] ?? [])
+        : [];
+    return (_jsx(Panel, { title: widget.title, style: { width: '100%', minWidth: 0 }, "data-widget-id": widget.id, "data-widget-component": widget.component, children: _jsx(Adapter, { widget: widget, data: data, interaction: ctx.interaction }) }));
+}
+function splitContainerStyle(direction) {
+    return {
+        display: 'flex',
+        flexDirection: direction,
+        flexWrap: direction === 'row' ? 'wrap' : 'nowrap',
+        gap: '1rem',
+        width: '100%',
+        minWidth: 0,
+    };
+}
+function ResizableSplit({ node, ctx, nodeKey, }) {
+    const panels = node.children.map((child, index) => ({
+        id: `${nodeKey}.${index}`,
+        size: child.size ?? 1,
+        content: renderLayoutNode(child, ctx, `${nodeKey}.${index}`),
+    }));
+    const height = node.height ?? DEFAULT_RESIZABLE_HEIGHT;
+    return (_jsx("div", { style: { width: '100%', minWidth: 0, height }, children: _jsx(SplitLayout, { orientation: node.direction === 'row' ? 'horizontal' : 'vertical', panels: panels }) }));
+}
+export function renderLayoutNode(node, ctx, key) {
+    if (node.type === 'widget') {
+        return (_jsx("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                minWidth: '280px',
+                flexGrow: node.size ?? 1,
+                flexBasis: 0,
+            }, children: renderWidget(node.ref, ctx) }, key));
+    }
+    const inner = node.resizable ? (_jsx(ResizableSplit, { node: node, ctx: ctx, nodeKey: key })) : (_jsx("div", { style: splitContainerStyle(node.direction), children: node.children.map((child, index) => renderLayoutNode(child, ctx, `${key}.${index}`)) }));
+    return (_jsx("div", { style: {
+            display: 'flex',
+            flexDirection: 'column',
+            minWidth: 0,
+            flexGrow: node.size ?? 1,
+            flexBasis: 0,
+        }, children: inner }, key));
+}
+/**
+ * Renders a `DashboardSpec`. Validates first (unless `skipValidation`), showing
+ * an annotated rejection for an invalid manifest rather than throwing.
+ */
+export function DashboardRenderer({ spec, dataSources, registry = DEFAULT_REGISTRY, interaction, skipValidation = false, }) {
+    const localInteraction = useLocalInteraction();
+    const resolvedInteraction = interaction ?? localInteraction;
+    if (!skipValidation) {
+        const result = validateDashboardSpec(spec, {
+            knownComponents: Object.keys(registry),
+        });
+        if (!result.ok)
+            return _jsx(InvalidSpec, { issues: result.issues });
+    }
+    const ctx = {
+        widgets: spec.widgets,
+        dataSources,
+        registry,
+        interaction: resolvedInteraction,
+    };
+    return (_jsxs("div", { style: rootStyle, children: [spec.title ? _jsx("h2", { style: titleStyle, children: spec.title }) : null, renderLayoutNode(spec.layout, ctx, 'root')] }));
+}

package/dist/schema.d.ts

@@ -0,0 +1,138 @@
+/**
+ * `@r0hitsharma/dashboard-kit` — the generic, manifest-driven dashboard
+ * engine.
+ *
+ * Three concerns stay SEPARABLE rather than conflated the way Grafana (flat,
+ * absolute `gridPos` + string-interpolated query blobs) or Superset (three
+ * disconnected config blobs) do:
+ *
+ *   1. `layout`  — a recursive composition tree (Vega-Lite `hconcat`/
+ *      `vconcat` style), independent of what each leaf renders.
+ *   2. `widgets` — a flat, id-keyed registry of widget nodes (`{component,
+ *      props, dataBinding}`), each resolved through a string -> component
+ *      registry key (see `registry.tsx`).
+ *   3. `dataBinding` — a typed `{source, fields}` pointer at a data source,
+ *      uniform across whatever transport a consuming app resolves `source`
+ *      ids against (live tail, replay cursor, a REST poll, ...).
+ *
+ * The one addition none of Grafana/Superset/Perspective/Vega-Lite model as
+ * part of the *widget* node itself is `interaction.reads`/`writes`: the
+ * shared-selection keys a widget consumes or produces. Declaring it here
+ * makes cross-filtering a declared, auditable property of the manifest
+ * instead of implicit wiring buried in component code — see `interaction.ts`
+ * for how those keys reach a real interaction store.
+ */
+export type LayoutDirection = 'row' | 'column';
+/** A recursive split node — maps onto the design-system's `SplitLayout` orientation. */
+export type SplitLayoutNode = {
+    type: 'split';
+    direction: LayoutDirection;
+    /** Relative share of the parent split's main axis; children need not sum to 1. */
+    size?: number;
+    /**
+     * Render this split as a DRAG-RESIZABLE panel group (design-system's
+     * `SplitLayout`, itself an Ark `Splitter`) instead of a plain flex box,
+     * with one panel per child and a resize handle between each pair. N-way by
+     * construction: three children give two handles.
+     *
+     * Opt-in rather than the default, because a `SplitLayout` needs hard panel
+     * sizes and therefore cannot flex-wrap: the non-resizable path keeps the
+     * responsive wrapping some dashboards rely on at narrow widths. A
+     * `direction: 'column'` split additionally needs {@link height}, since a
+     * vertical splitter has no content-driven size to divide.
+     */
+    resizable?: boolean;
+    /** Required for a resizable `column` split: the CSS height to divide. */
+    height?: string;
+    children: LayoutNode[];
+};
+/** A leaf that resolves to one entry in the flat `widgets` registry. */
+export type WidgetLayoutNode = {
+    type: 'widget';
+    /** Key into `DashboardSpec['widgets']`. */
+    ref: string;
+    /** Relative share of the parent split's main axis. */
+    size?: number;
+};
+export type LayoutNode = SplitLayoutNode | WidgetLayoutNode;
+/**
+ * What data source feeds a widget, and how its fields map onto the shape the
+ * component needs — a typed channel-to-field mapping (Vega-Lite style)
+ * rather than an opaque query string. `source` ids are resolved through
+ * whatever {@link DashboardDataSources} table the host app supplies;
+ * `dashboard-kit` itself is agnostic to what backs a source (a mock array, a
+ * live tail, a replay cursor).
+ */
+export type DataBinding = {
+    /** Data-source id, e.g. `"stream:metrics.throughput"`. */
+    source: string;
+    /** Field name mapping: which field of a source record feeds which slot. */
+    fields: Record<string, string>;
+};
+/**
+ * Shared-selection keys a widget consumes (`reads`) or produces (`writes`).
+ * Symmetric by design — any widget may read or write any key, no
+ * master/detail hardcoding.
+ */
+export type WidgetInteraction = {
+    reads?: string[];
+    writes?: string[];
+    /**
+     * Per-field AGENT EXPOSURE: which of this widget's interaction keys an
+     * agent (a drive tool, a command bar) may write. **Default-deny**: a key a
+     * human can write through the UI is NOT agent-writable unless it is listed
+     * here.
+     *
+     * This is the manifest's half of the contract; a host app's agent-facing
+     * tools consult {@link collectAgentWritableKeys} and refuse anything
+     * outside it, so the agent surface is a declared, auditable property of
+     * the dashboard rather than "whatever setters happen to be in scope".
+     */
+    agentWritable?: string[];
+};
+export type ThresholdSeverity = 'success' | 'warning' | 'critical';
+export type ThresholdRule = {
+    op: 'gte' | 'lte' | 'gt' | 'lt' | 'eq';
+    value: number;
+    severity: ThresholdSeverity;
+};
+/** One declarative column for a table-rendering widget. */
+export type WidgetTableColumn = {
+    accessorKey: string;
+    header: string;
+    /** How the registry's table adapter should render the cell. */
+    render?: 'text' | 'number' | 'currency' | 'percent' | 'badge' | 'sparkline';
+};
+export type WidgetNode = {
+    id: string;
+    /** Component-registry key, e.g. `"panel.stat"` or `"chart.line"`. */
+    component: string;
+    title?: string;
+    /**
+     * Component-specific configuration, passed through to the resolved
+     * component-registry entry. Kept to JSON-serializable shapes (no
+     * functions) so a manifest stays a genuine, inspectable data value —
+     * `columns` for table widgets is the one structured exception.
+     */
+    props?: Record<string, unknown> & {
+        columns?: WidgetTableColumn[];
+    };
+    dataBinding?: DataBinding;
+    interaction?: WidgetInteraction;
+    thresholds?: ThresholdRule[];
+};
+export type DashboardSpec = {
+    version: 1;
+    title?: string;
+    layout: LayoutNode;
+    /** Flat registry of widget nodes, referenced by id from `layout`. */
+    widgets: Record<string, WidgetNode>;
+};
+/**
+ * Data-source table keyed by `DataBinding['source']` — every source resolves
+ * to an array of plain records; scalar widgets (e.g. a stat tile reading a
+ * gauge) read the last record. A host app owns populating this (from a mock
+ * fixture, a live subscription snapshot, a query result, ...); the engine
+ * only ever reads it.
+ */
+export type DashboardDataSources = Record<string, Record<string, unknown>[]>;

package/dist/schema.js

@@ -0,0 +1,25 @@
+/**
+ * `@r0hitsharma/dashboard-kit` — the generic, manifest-driven dashboard
+ * engine.
+ *
+ * Three concerns stay SEPARABLE rather than conflated the way Grafana (flat,
+ * absolute `gridPos` + string-interpolated query blobs) or Superset (three
+ * disconnected config blobs) do:
+ *
+ *   1. `layout`  — a recursive composition tree (Vega-Lite `hconcat`/
+ *      `vconcat` style), independent of what each leaf renders.
+ *   2. `widgets` — a flat, id-keyed registry of widget nodes (`{component,
+ *      props, dataBinding}`), each resolved through a string -> component
+ *      registry key (see `registry.tsx`).
+ *   3. `dataBinding` — a typed `{source, fields}` pointer at a data source,
+ *      uniform across whatever transport a consuming app resolves `source`
+ *      ids against (live tail, replay cursor, a REST poll, ...).
+ *
+ * The one addition none of Grafana/Superset/Perspective/Vega-Lite model as
+ * part of the *widget* node itself is `interaction.reads`/`writes`: the
+ * shared-selection keys a widget consumes or produces. Declaring it here
+ * makes cross-filtering a declared, auditable property of the manifest
+ * instead of implicit wiring buried in component code — see `interaction.ts`
+ * for how those keys reach a real interaction store.
+ */
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Manifest validation — the gate that must land before any "an agent or
+ * command bar submits a manifest patch" feature can trust a `DashboardSpec`.
+ *
+ * Two layers, because zod alone can't catch the interesting failures:
+ *
+ *   1. STRUCTURAL — `dashboardSpecSchema` below. Shape, enums, required
+ *      fields, no malformed widget nodes.
+ *   2. REFERENTIAL — {@link validateDashboardSpec}'s extra passes. Every
+ *      `layout` leaf must name a widget that exists; every widget must be
+ *      reachable from the layout; a resizable `column` split must carry a
+ *      `height`; an `agentWritable` key must actually be writable. These are
+ *      the mistakes an agent-authored patch actually makes, and none of them
+ *      are expressible as a type.
+ *
+ * `zod` deliberately does NOT validate `component` against a registry here:
+ * `schema.ts` is the data contract and a registry is one possible resolution
+ * of it. The renderer degrades gracefully on an unknown component key (it
+ * renders an `UnknownWidget` marker), and coupling the two would make the
+ * schema un-shareable. {@link validateDashboardSpec} takes an optional set of
+ * known component keys for callers who DO want that checked.
+ */
+import { z } from 'zod';
+import type { DashboardSpec } from './schema.js';
+export declare const dashboardSpecSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    title: z.ZodOptional<z.ZodString>;
+    layout: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    widgets: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        component: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        props: z.ZodOptional<z.ZodObject<{
+            columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                accessorKey: z.ZodString;
+                header: z.ZodString;
+                render: z.ZodOptional<z.ZodEnum<{
+                    badge: "badge";
+                    currency: "currency";
+                    number: "number";
+                    percent: "percent";
+                    sparkline: "sparkline";
+                    text: "text";
+                }>>;
+            }, z.core.$strip>>>;
+        }, z.core.$loose>>;
+        dataBinding: z.ZodOptional<z.ZodObject<{
+            source: z.ZodString;
+            fields: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strip>>;
+        interaction: z.ZodOptional<z.ZodObject<{
+            reads: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            writes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            agentWritable: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        thresholds: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            op: z.ZodEnum<{
+                eq: "eq";
+                gt: "gt";
+                gte: "gte";
+                lt: "lt";
+                lte: "lte";
+            }>;
+            value: z.ZodNumber;
+            severity: z.ZodEnum<{
+                critical: "critical";
+                success: "success";
+                warning: "warning";
+            }>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ManifestIssue = {
+    /** Dotted path into the spec, e.g. `widgets.exposure.component`. */
+    path: string;
+    message: string;
+};
+export type ManifestValidation = {
+    ok: true;
+    spec: DashboardSpec;
+    issues: [];
+} | {
+    ok: false;
+    issues: ManifestIssue[];
+};
+export type ValidateOptions = {
+    /**
+     * When supplied, every widget's `component` must be one of these keys.
+     * Pass `Object.keys(registry)` to catch a typo'd or hallucinated component
+     * name before it renders as an `UnknownWidget` placeholder.
+     */
+    knownComponents?: Iterable<string>;
+};
+/**
+ * Validates a candidate manifest. Never throws — an agent-submitted patch is
+ * untrusted input, and the caller needs the reasons, not a stack trace.
+ */
+export declare function validateDashboardSpec(candidate: unknown, { knownComponents }?: ValidateOptions): ManifestValidation;
+/**
+ * The set of interaction keys an agent is allowed to write, collected across
+ * every widget in the manifest. Default-deny: an empty set means an agent may
+ * read the dashboard but drive nothing.
+ */
+export declare function collectAgentWritableKeys(spec: DashboardSpec): Set<string>;

package/dist/validate.js

@@ -0,0 +1,174 @@
+/**
+ * Manifest validation — the gate that must land before any "an agent or
+ * command bar submits a manifest patch" feature can trust a `DashboardSpec`.
+ *
+ * Two layers, because zod alone can't catch the interesting failures:
+ *
+ *   1. STRUCTURAL — `dashboardSpecSchema` below. Shape, enums, required
+ *      fields, no malformed widget nodes.
+ *   2. REFERENTIAL — {@link validateDashboardSpec}'s extra passes. Every
+ *      `layout` leaf must name a widget that exists; every widget must be
+ *      reachable from the layout; a resizable `column` split must carry a
+ *      `height`; an `agentWritable` key must actually be writable. These are
+ *      the mistakes an agent-authored patch actually makes, and none of them
+ *      are expressible as a type.
+ *
+ * `zod` deliberately does NOT validate `component` against a registry here:
+ * `schema.ts` is the data contract and a registry is one possible resolution
+ * of it. The renderer degrades gracefully on an unknown component key (it
+ * renders an `UnknownWidget` marker), and coupling the two would make the
+ * schema un-shareable. {@link validateDashboardSpec} takes an optional set of
+ * known component keys for callers who DO want that checked.
+ */
+import { z } from 'zod';
+const layoutDirection = z.enum(['row', 'column']);
+const widgetLayoutNode = z.object({
+    type: z.literal('widget'),
+    ref: z.string().min(1),
+    size: z.number().positive().optional(),
+});
+/**
+ * Recursive by `z.lazy` — a split's children are layout nodes, which may be
+ * splits.
+ */
+const layoutNode = z.lazy(() => z.union([widgetLayoutNode, splitLayoutNode]));
+const splitLayoutNode = z.object({
+    type: z.literal('split'),
+    direction: layoutDirection,
+    size: z.number().positive().optional(),
+    resizable: z.boolean().optional(),
+    height: z.string().min(1).optional(),
+    children: z.array(layoutNode).min(1),
+});
+const dataBinding = z.object({
+    source: z.string().min(1),
+    fields: z.record(z.string(), z.string()),
+});
+const widgetInteraction = z.object({
+    reads: z.array(z.string().min(1)).optional(),
+    writes: z.array(z.string().min(1)).optional(),
+    agentWritable: z.array(z.string().min(1)).optional(),
+});
+const thresholdRule = z.object({
+    op: z.enum(['gte', 'lte', 'gt', 'lt', 'eq']),
+    value: z.number(),
+    severity: z.enum(['success', 'warning', 'critical']),
+});
+const widgetTableColumn = z.object({
+    accessorKey: z.string().min(1),
+    header: z.string(),
+    render: z
+        .enum(['text', 'number', 'currency', 'percent', 'badge', 'sparkline'])
+        .optional(),
+});
+const widgetNode = z.object({
+    id: z.string().min(1),
+    component: z.string().min(1),
+    title: z.string().optional(),
+    // `props` stays open (it's per-component config) EXCEPT `columns`, which is
+    // structured enough — and mistyped often enough — to be worth checking.
+    props: z
+        .looseObject({ columns: z.array(widgetTableColumn).optional() })
+        .optional(),
+    dataBinding: dataBinding.optional(),
+    interaction: widgetInteraction.optional(),
+    thresholds: z.array(thresholdRule).optional(),
+});
+export const dashboardSpecSchema = z.object({
+    version: z.literal(1),
+    title: z.string().optional(),
+    layout: layoutNode,
+    widgets: z.record(z.string(), widgetNode),
+});
+function walkLayout(node, path, visit) {
+    visit(node, path);
+    node.children?.forEach((child, index) => walkLayout(child, `${path}.children[${index}]`, visit));
+}
+/**
+ * Validates a candidate manifest. Never throws — an agent-submitted patch is
+ * untrusted input, and the caller needs the reasons, not a stack trace.
+ */
+export function validateDashboardSpec(candidate, { knownComponents } = {}) {
+    const parsed = dashboardSpecSchema.safeParse(candidate);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            issues: parsed.error.issues.map((issue) => ({
+                path: issue.path.join('.') || '(root)',
+                message: issue.message,
+            })),
+        };
+    }
+    const spec = parsed.data;
+    const issues = [];
+    const known = knownComponents ? new Set(knownComponents) : null;
+    // ── Referential pass ────────────────────────────────────────────────────
+    const referenced = new Set();
+    walkLayout(spec.layout, 'layout', (node, path) => {
+        if (node.type === 'widget') {
+            const ref = node.ref;
+            referenced.add(ref);
+            if (!(ref in spec.widgets)) {
+                issues.push({
+                    path: `${path}.ref`,
+                    message: `layout references unknown widget "${ref}" — add it to \`widgets\` or fix the ref`,
+                });
+            }
+            return;
+        }
+        if (node.resizable && node.direction === 'column' && !node.height) {
+            issues.push({
+                path: `${path}.height`,
+                message: 'a resizable `column` split needs an explicit `height` — a vertical splitter has no content-driven size to divide',
+            });
+        }
+    });
+    for (const [key, widget] of Object.entries(spec.widgets)) {
+        if (widget.id !== key) {
+            issues.push({
+                path: `widgets.${key}.id`,
+                message: `widget id "${widget.id}" does not match its registry key "${key}"`,
+            });
+        }
+        if (!referenced.has(key)) {
+            issues.push({
+                path: `widgets.${key}`,
+                message: `widget "${key}" is never placed by \`layout\` — it will not render`,
+            });
+        }
+        if (known && !known.has(widget.component)) {
+            issues.push({
+                path: `widgets.${key}.component`,
+                message: `unknown component "${widget.component}"`,
+            });
+        }
+        // An agent-writable key that the widget cannot actually write is a policy
+        // that silently does nothing — worth catching at the gate. `writes` is the
+        // set of keys a widget produces; an `agentWritable` key must be one of them.
+        const writes = widget.interaction?.writes ?? [];
+        for (const exposed of widget.interaction?.agentWritable ?? []) {
+            if (!writes.includes(exposed)) {
+                issues.push({
+                    path: `widgets.${key}.interaction.agentWritable`,
+                    message: `"${exposed}" is marked agent-writable but is not in this widget's \`writes\``,
+                });
+            }
+        }
+    }
+    return issues.length > 0
+        ? { ok: false, issues }
+        : { ok: true, spec, issues: [] };
+}
+/**
+ * The set of interaction keys an agent is allowed to write, collected across
+ * every widget in the manifest. Default-deny: an empty set means an agent may
+ * read the dashboard but drive nothing.
+ */
+export function collectAgentWritableKeys(spec) {
+    const keys = new Set();
+    for (const widget of Object.values(spec.widgets)) {
+        for (const key of widget.interaction?.agentWritable ?? [])
+            keys.add(key);
+    }
+    return keys;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@r0hitsharma/dashboard-kit",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "prepare": "npm run build",
+    "type:check": "tsc -p tsconfig.json --noEmit",
+    "lint": "oxlint -c oxlint.config.ts --max-warnings=0 src",
+    "lint:fix": "oxlint -c oxlint.config.ts --fix src",
+    "format": "oxfmt -c oxfmt.config.ts --write src",
+    "format:check": "oxfmt -c oxfmt.config.ts --check src",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@r0hitsharma/charting": "*",
+    "@r0hitsharma/design-system": "*",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "@tanstack/react-table": "9.2.4",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@r0hitsharma/charting": "*",
+    "@r0hitsharma/design-system": "*",
+    "@r0hitsharma/oxfmt-config": "*",
+    "@r0hitsharma/oxlint-config": "*",
+    "@r0hitsharma/tsconfig": "*",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "jsdom": "^30.0.0",
+    "oxfmt": "0.67.0",
+    "oxlint": "1.82.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vitest": "^4.1.9"
+  },
+  "version": "0.12.0-rohit-fork-ci.1",
+  "repository": {
+    "url": "https://github.com/r0hitsharma/uikit"
+  }
+}