@consciousclouds/canvas-runtime 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog — @consciousclouds/canvas-runtime
+
+Versioned on the independent frontend-SDK lifecycle (NOT `contract_version`).
+
+## [0.2.0] — 2026-06-09
+
+### Added
+
+- Renderer-level permission filtering. New optional `permissions?: string[]`
+  prop on `CanvasRenderer`: when provided (even `[]`), a node with a
+  `requiredPermission` is dropped unless that permission — or `*` — is present.
+  Permission-filtered nodes are removed entirely (no placeholder), distinct
+  from the unknown/removed fail-closed placeholder. Enforcement now travels
+  with the package, so every consumer (ENO, Omni, CloudChief, BWC, TT) gets it
+  by default.
+- Exported `isNodePermitted(node, permissions)` predicate.
+
+### Backward compatibility
+
+- Omitting `permissions` leaves filtering **not engaged** — all nodes render,
+  identical to 0.1.0. No change for existing consumers.
+
+## [0.1.0] — 2026-06-09
+
+### Added
+
+- `CanvasRenderer` — renders a `CanvasDefinition` by mapping each node onto a
+  consumer-supplied component (`componentMap`). Product-neutral: the consumer
+  (ENO, CloudChief) supplies its own component implementations.
+- Fail-closed behavior: an unknown / `removed` / unmapped component renders an
+  explicit `UnsupportedComponent` placeholder — never arbitrary markup.
+- Deprecation signalling for `deprecated` registry entries (`onDeprecated`).
+- Action dispatch via an `onAction` callback (never navigates directly).

package/README.md

@@ -0,0 +1,30 @@
+# @consciousclouds/canvas-runtime
+
+React renderer for the Intelligence Runtime **Canvas** layer. It takes a
+`CanvasDefinition` and a **consumer-supplied `componentMap`** and renders each
+node with the consumer's own components.
+
+It is **product-neutral**: the renderer never imports a design system. Each
+consuming app maps canvas component-ids to its own components. This keeps the
+renderer publishable and keeps "AI selects, cannot invent UI" structural — any
+component id not in the approved registry (or not in the map) renders an
+explicit placeholder, never arbitrary markup.
+
+```tsx
+import { CanvasRenderer } from '@consciousclouds/canvas-runtime';
+// Supply your own components for each approved component id:
+import { Stat, Table } from './your-design-system';
+
+<CanvasRenderer
+  definition={canvas}
+  componentMap={{
+    'stat-card': ({ node }) => <Stat {...node.props} />,
+    'data-table': ({ node }) => <Table {...node.props} />,
+  }}
+  onAction={(action, node) => dispatch(action)}
+/>
+```
+
+Data bindings are resolved **server-side** under the authenticated context;
+the renderer receives already-authorized, already-bound values in `node.props`
+and never re-fetches.

package/dist/CanvasRenderer.d.ts

@@ -0,0 +1,35 @@
+import * as React from 'react';
+import type { CanvasDefinition, CanvasNode, ComponentRegistry } from '@consciousclouds/canvas-sdk';
+import type { ComponentMap, ActionHandler } from './types.js';
+export interface CanvasRendererProps {
+    definition: CanvasDefinition;
+    /** Consumer-supplied component implementations, keyed by approved component id. */
+    componentMap: ComponentMap;
+    /** Receives dispatched actions (the renderer never navigates directly). */
+    onAction?: ActionHandler;
+    /** Override the approved-component registry (defaults to the SDK allowlist). */
+    registry?: ComponentRegistry;
+    /** Notified when a rendered node uses a deprecated component. */
+    onDeprecated?: (type: string) => void;
+    /**
+     * Caller's permissions. When provided (even an empty array), any node with a
+     * `requiredPermission` is dropped unless that permission — or the `*`
+     * wildcard — is present. When OMITTED (undefined), permission filtering is
+     * not engaged and all nodes render (backward compatible). Permission-filtered
+     * nodes are removed entirely (no placeholder), distinct from the
+     * unknown/removed fail-closed placeholder.
+     */
+    permissions?: string[];
+}
+/**
+ * Whether a node passes permission filtering. Travels with the renderer so
+ * every consumer (ENO, Omni, CloudChief, BWC, TT) gets identical enforcement.
+ *
+ * - node without `requiredPermission` → permitted
+ * - `permissions` undefined → not engaged → permitted (backward compatible)
+ * - `*` wildcard or exact match → permitted
+ * - otherwise → not permitted (the node is dropped)
+ */
+export declare function isNodePermitted(node: Pick<CanvasNode, 'requiredPermission'>, permissions: string[] | undefined): boolean;
+export declare function CanvasRenderer(props: CanvasRendererProps): React.ReactElement;
+//# sourceMappingURL=CanvasRenderer.d.ts.map

package/dist/CanvasRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasRenderer.d.ts","sourceRoot":"","sources":["../src/CanvasRenderer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAOnG,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,mFAAmF;IACnF,YAAY,EAAE,YAAY,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,iEAAiE;IACjE,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,oBAAoB,CAAC,EAC5C,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,GAChC,OAAO,CAKT;AAaD,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,KAAK,CAAC,YAAY,CAqB7E"}

package/dist/CanvasRenderer.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { COMPONENT_REGISTRY, isApprovedComponent, isDeprecatedComponent, } from '@consciousclouds/canvas-sdk';
+import { UnsupportedComponent } from './UnsupportedComponent.js';
+/**
+ * Whether a node passes permission filtering. Travels with the renderer so
+ * every consumer (ENO, Omni, CloudChief, BWC, TT) gets identical enforcement.
+ *
+ * - node without `requiredPermission` → permitted
+ * - `permissions` undefined → not engaged → permitted (backward compatible)
+ * - `*` wildcard or exact match → permitted
+ * - otherwise → not permitted (the node is dropped)
+ */
+export function isNodePermitted(node, permissions) {
+    if (!node.requiredPermission)
+        return true;
+    if (permissions === undefined)
+        return true;
+    if (permissions.includes('*'))
+        return true;
+    return permissions.includes(node.requiredPermission);
+}
+function layoutStyle(layout) {
+    if (layout.type === 'grid') {
+        return {
+            display: 'grid',
+            gridTemplateColumns: `repeat(${layout.columns ?? 1}, minmax(0, 1fr))`,
+            gap: 12,
+        };
+    }
+    return { display: 'flex', flexDirection: 'column', gap: 12 };
+}
+export function CanvasRenderer(props) {
+    const { definition, componentMap, onAction, registry = COMPONENT_REGISTRY, onDeprecated, permissions, } = props;
+    return (_jsx("div", { "data-canvas-version": definition.version, "data-correlation-id": definition.correlationId, style: layoutStyle(definition.layout), children: definition.nodes
+            .filter((node) => isNodePermitted(node, permissions))
+            .map((node) => renderNode(node, componentMap, registry, onAction, onDeprecated)) }));
+}
+function renderNode(node, componentMap, registry, onAction, onDeprecated) {
+    // Fail closed: unknown or `removed` component id → placeholder, never markup.
+    if (!isApprovedComponent(node.type, registry)) {
+        return _jsx(UnsupportedComponent, { type: node.type, reason: "not in approved registry" }, node.id);
+    }
+    const Component = componentMap[node.type];
+    if (!Component) {
+        return _jsx(UnsupportedComponent, { type: node.type, reason: "no component supplied" }, node.id);
+    }
+    if (isDeprecatedComponent(node.type, registry)) {
+        onDeprecated?.(node.type);
+        if (typeof console !== 'undefined') {
+            console.warn(`[canvas] component '${node.type}' is deprecated`);
+        }
+    }
+    return _jsx(Component, { node: node, onAction: onAction }, node.id);
+}
+//# sourceMappingURL=CanvasRenderer.js.map

package/dist/CanvasRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasRenderer.js","sourceRoot":"","sources":["../src/CanvasRenderer.tsx"],"names":[],"mappings":";AAEA,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAwBjE;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,IAA4C,EAC5C,WAAiC;IAEjC,IAAI,CAAC,IAAI,CAAC,kBAAkB;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,WAAW,CAAC,MAAkC;IACrD,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO;YACL,OAAO,EAAE,MAAM;YACf,mBAAmB,EAAE,UAAU,MAAM,CAAC,OAAO,IAAI,CAAC,mBAAmB;YACrE,GAAG,EAAE,EAAE;SACR,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAA0B;IACvD,MAAM,EACJ,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,QAAQ,GAAG,kBAAkB,EAC7B,YAAY,EACZ,WAAW,GACZ,GAAG,KAAK,CAAC;IAEV,OAAO,CACL,qCACuB,UAAU,CAAC,OAAO,yBAClB,UAAU,CAAC,aAAa,EAC7C,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,YAEpC,UAAU,CAAC,KAAK;aACd,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;aACpD,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,GAC9E,CACP,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CACjB,IAAgB,EAChB,YAA0B,EAC1B,QAA2B,EAC3B,QAAmC,EACnC,YAAkD;IAElD,8EAA8E;IAC9E,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC9C,OAAO,KAAC,oBAAoB,IAAe,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAC,0BAA0B,IAA3D,IAAI,CAAC,EAAE,CAAuD,CAAC;IACnG,CAAC;IAED,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,KAAC,oBAAoB,IAAe,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAC,uBAAuB,IAAxD,IAAI,CAAC,EAAE,CAAoD,CAAC;IAChG,CAAC;IAED,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC/C,YAAY,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;YACnC,OAAO,CAAC,IAAI,CAAC,uBAAuB,IAAI,CAAC,IAAI,iBAAiB,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,OAAO,KAAC,SAAS,IAAe,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,IAAvC,IAAI,CAAC,EAAE,CAAoC,CAAC;AACrE,CAAC"}

package/dist/UnsupportedComponent.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+export interface UnsupportedComponentProps {
+    type: string;
+    reason?: string;
+}
+/**
+ * The fail-closed placeholder. Rendered for any component id that is not in
+ * the approved registry, is `removed`, or has no implementation in the
+ * component map. It is deliberately inert — never arbitrary markup, never the
+ * unknown component.
+ */
+export declare function UnsupportedComponent({ type, reason }: UnsupportedComponentProps): React.ReactElement;
+//# sourceMappingURL=UnsupportedComponent.d.ts.map

package/dist/UnsupportedComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnsupportedComponent.d.ts","sourceRoot":"","sources":["../src/UnsupportedComponent.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,yBAAyB,GAAG,KAAK,CAAC,YAAY,CAiBpG"}

package/dist/UnsupportedComponent.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The fail-closed placeholder. Rendered for any component id that is not in
+ * the approved registry, is `removed`, or has no implementation in the
+ * component map. It is deliberately inert — never arbitrary markup, never the
+ * unknown component.
+ */
+export function UnsupportedComponent({ type, reason }) {
+    return (_jsxs("div", { role: "note", "data-canvas-unsupported": type, style: {
+            padding: 8,
+            border: '1px dashed #c0392b',
+            color: '#c0392b',
+            fontSize: 12,
+            borderRadius: 6,
+        }, children: ["Unsupported component: ", _jsx("code", { children: type }), reason ? ` — ${reason}` : ''] }));
+}
+//# sourceMappingURL=UnsupportedComponent.js.map

package/dist/UnsupportedComponent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnsupportedComponent.js","sourceRoot":"","sources":["../src/UnsupportedComponent.tsx"],"names":[],"mappings":";AAOA;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAAE,IAAI,EAAE,MAAM,EAA6B;IAC9E,OAAO,CACL,eACE,IAAI,EAAC,MAAM,6BACc,IAAI,EAC7B,KAAK,EAAE;YACL,OAAO,EAAE,CAAC;YACV,MAAM,EAAE,oBAAoB;YAC5B,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,EAAE;YACZ,YAAY,EAAE,CAAC;SAChB,wCAEsB,yBAAO,IAAI,GAAQ,EACzC,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IACzB,CACP,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { CanvasRenderer, isNodePermitted } from './CanvasRenderer.js';
+export type { CanvasRendererProps } from './CanvasRenderer.js';
+export { UnsupportedComponent } from './UnsupportedComponent.js';
+export type { UnsupportedComponentProps } from './UnsupportedComponent.js';
+export type { ComponentMap, CanvasComponentProps, ActionHandler } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { CanvasRenderer, isNodePermitted } from './CanvasRenderer.js';
+export { UnsupportedComponent } from './UnsupportedComponent.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentType } from 'react';
+import type { CanvasNode, CanvasNodeType, ActionDef } from '@consciousclouds/canvas-sdk';
+/** Called when a node dispatches an action. Never navigates directly. */
+export type ActionHandler = (action: ActionDef, node: CanvasNode) => void;
+/** Props passed to every consumer-supplied canvas component. */
+export interface CanvasComponentProps {
+    node: CanvasNode;
+    onAction?: ActionHandler;
+}
+/**
+ * Consumer-supplied implementations for approved component ids. The renderer
+ * fails closed for any id missing from this map (or from the registry).
+ */
+export type ComponentMap = Partial<Record<CanvasNodeType, ComponentType<CanvasComponentProps>>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAEzF,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AAE1E,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@consciousclouds/canvas-runtime",
+  "version": "0.2.0",
+  "description": "Conscious Clouds Canvas renderer — maps a CanvasDefinition onto consumer-supplied React components from the approved Component Registry. Fails closed on unknown/removed/unmapped components. Product-neutral (the component map is injected).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run clean && bun run build && bun run type-check"
+  },
+  "dependencies": {
+    "@consciousclouds/canvas-sdk": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.1",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  }
+}