@echothink-ui/runtime 0.1.0

package/src/index.tsx

@@ -0,0 +1,377 @@
+import * as React from "react";
+import { satisfies, valid } from "semver";
+import { ErrorState, EmptyState, Surface } from "@echothink-ui/core";
+import { compositionDocumentSchema, validateWithSchema } from "@echothink-ui/validators";
+
+export type EthSurfaceType =
+  | "page"
+  | "shell"
+  | "rail"
+  | "panel"
+  | "drawer"
+  | "modal"
+  | "table"
+  | "chart"
+  | "form"
+  | "inspector"
+  | "inline"
+  | "composite";
+
+export interface EthCompositionDocument {
+  schemaVersion: "eth.ui.composition.v1";
+  id: string;
+  title: string;
+  generatedBy: "echothink-core" | "app-domain" | "human-authored";
+  versionLock: EthVersionLock;
+  audit: EthAuditMetadata;
+  permissions?: EthPermissionConstraint[];
+  dataSources?: Record<string, EthDataSource>;
+  resources?: Record<string, EthResourceReference>;
+  layout: EthLayoutNode;
+  eventHandlers?: Record<string, EthEventHandler>;
+  fallbacks?: Record<string, EthFallbackSpec>;
+  telemetry?: EthTelemetrySpec;
+}
+
+export interface EthVersionLock {
+  runtime: string;
+  skills: Record<string, string>;
+  components?: Record<string, string>;
+  tokens?: string;
+}
+export interface EthAuditMetadata {
+  requestId: string;
+  traceId?: string;
+  projectId?: string;
+  userId?: string;
+  generatedAt: string;
+  reason?: string;
+  sourceRefs?: string[];
+  riskLevel?: "low" | "medium" | "high" | "critical";
+}
+export interface EthLayoutNode {
+  id: string;
+  type: EthSurfaceType;
+  component?: EthComponentReference;
+  skill?: EthSkillReference;
+  props?: Record<string, unknown>;
+  bindings?: Record<string, EthBinding>;
+  permissions?: EthPermissionConstraint[];
+  children?: EthLayoutNode[];
+  slots?: Record<string, EthLayoutNode | EthLayoutNode[]>;
+  loading?: EthStateSpec;
+  empty?: EthStateSpec;
+  errorBoundary?: EthErrorBoundarySpec;
+  responsive?: EthResponsiveSpec;
+  fallback?: EthFallbackSpec;
+  visibility?: EthVisibilityRule;
+}
+export interface EthSkillReference {
+  id: string;
+  version: string;
+  input?: Record<string, unknown>;
+  childPolicy?: "none" | "declared-only" | "any-registered";
+}
+export interface EthComponentReference {
+  package: string;
+  exportName: string;
+  version?: string;
+}
+export interface EthDataSource {
+  kind: "query" | "stream" | "resource" | "wall" | "inline" | "computed";
+  ref: string;
+  schema?: string;
+  params?: Record<string, unknown>;
+  refresh?: { mode: "manual" | "interval" | "realtime"; intervalMs?: number };
+  cache?: { ttlMs?: number; key?: string };
+  redaction?: EthRedactionPolicy;
+}
+export interface EthResourceReference {
+  kind: "project" | "task" | "document" | "file" | "app-domain" | "agent-run" | "custom";
+  id: string;
+  wallRef?: string;
+  version?: string;
+  tenantBoundary?: string;
+}
+export interface EthBinding {
+  source: string;
+  path?: string;
+  transform?: string;
+  required?: boolean;
+}
+export interface EthPermissionConstraint {
+  action: string;
+  resource?: string;
+  mode?: "render" | "read" | "mutate" | "approve" | "export";
+  fallback?: "hide" | "disable" | "redact" | "readonly" | "error";
+}
+export interface EthEventHandler {
+  event: string;
+  target: "echothink-core" | "local-runtime" | "app-domain-service";
+  action: string;
+  payloadBinding?: Record<string, EthBinding | unknown>;
+  requiresPermission?: EthPermissionConstraint[];
+  audit?: boolean;
+  optimistic?: boolean;
+}
+export interface EthStateSpec {
+  kind: "default" | "component" | "skill" | "message";
+  message?: string;
+  component?: EthComponentReference;
+  skill?: EthSkillReference;
+}
+export interface EthErrorBoundarySpec {
+  mode: "local" | "region" | "page";
+  fallback: EthStateSpec;
+  reportToTelemetry?: boolean;
+}
+export interface EthResponsiveSpec {
+  breakpoints?: Record<string, Partial<EthLayoutNode>>;
+  density?: "compact" | "default" | "comfortable";
+  collapseBehavior?: "stack" | "tabs" | "drawer" | "hide-secondary";
+}
+export interface EthFallbackSpec {
+  reason?: string;
+  state: EthStateSpec;
+}
+export interface EthVisibilityRule {
+  when?: string;
+  defaultVisible?: boolean;
+}
+export interface EthTelemetrySpec {
+  impressions?: boolean;
+  interactions?: boolean;
+  performance?: boolean;
+  errors?: boolean;
+}
+export interface EthRedactionPolicy {
+  policyId: string;
+  fields?: string[];
+  replacement?: "mask" | "placeholder" | "omit";
+}
+
+export interface EthSkillDefinition<TInput = unknown> {
+  id: string;
+  version: string;
+  name: string;
+  category: string;
+  description?: string;
+  inputSchema?: {
+    safeParse: (value: unknown) => { success: boolean; data?: TInput; error?: unknown };
+  };
+  outputSurfaceType: EthSurfaceType;
+  allowedChildSkills?: string[];
+  requiredPermissions?: EthPermissionConstraint[];
+  requiredDataSources?: string[];
+  events?: string[];
+  accessibility?: Record<string, unknown>;
+  deprecated?: { since: string; replacement: string; removeIn: string };
+  load: () => Promise<{ default: React.ComponentType<any> }>;
+}
+
+export class SkillRegistry {
+  private skills = new Map<string, EthSkillDefinition<any>>();
+  register(skill: EthSkillDefinition<any>) {
+    const key = this.key(skill.id, skill.version);
+    if (this.skills.has(key)) throw new Error(`Skill already registered: ${key}`);
+    this.skills.set(key, skill);
+  }
+  registerMany(skills: EthSkillDefinition<any>[]) {
+    skills.forEach((skill) => this.register(skill));
+  }
+  resolve(id: string, versionRange: string) {
+    const candidates = [...this.skills.values()].filter((skill) => skill.id === id);
+    const match =
+      candidates.find(
+        (skill) =>
+          valid(skill.version) &&
+          satisfies(skill.version, versionRange, { includePrerelease: true })
+      ) ?? candidates.find((skill) => skill.version === versionRange);
+    if (!match) throw new Error(`No compatible skill found for ${id}@${versionRange}`);
+    return match;
+  }
+  list() {
+    return [...this.skills.values()];
+  }
+  private key(id: string, version: string) {
+    return `${id}@${version}`;
+  }
+}
+
+export interface EthDataBindingResolver {
+  resolve(binding: EthBinding, document: EthCompositionDocument): unknown | Promise<unknown>;
+}
+export interface EthPermissionGuard {
+  evaluate(constraints: EthPermissionConstraint[]): EthPermissionResult;
+}
+export interface EthEventBridge {
+  dispatch(event: string, payload: unknown, context: EthEventContext): void | Promise<void>;
+}
+export interface EthEventContext {
+  document: EthCompositionDocument;
+  handler?: EthEventHandler;
+  node?: EthLayoutNode;
+}
+export interface EthPermissionResult {
+  allowed: boolean;
+  fallback?: "hide" | "disable" | "redact" | "readonly" | "error";
+  reason?: string;
+}
+
+export const allowAllPermissions: EthPermissionGuard = { evaluate: () => ({ allowed: true }) };
+export const noopEventBridge: EthEventBridge = { dispatch: () => undefined };
+export const fixtureDataResolver: EthDataBindingResolver = {
+  resolve(binding, document) {
+    const source = document.dataSources?.[binding.source] ?? document.resources?.[binding.source];
+    return binding.path ? getByPath(source, binding.path) : source;
+  }
+};
+
+export interface CompositionRendererProps {
+  document: EthCompositionDocument;
+  registry: SkillRegistry;
+  dataResolver?: EthDataBindingResolver;
+  permissionGuard?: EthPermissionGuard;
+  eventBridge?: EthEventBridge;
+  components?: Record<string, React.ComponentType<any>>;
+}
+
+const RuntimeContext = React.createContext<
+  | (Required<Omit<CompositionRendererProps, "document">> & { document: EthCompositionDocument })
+  | null
+>(null);
+
+export function CompositionRenderer({
+  document,
+  registry,
+  dataResolver = fixtureDataResolver,
+  permissionGuard = allowAllPermissions,
+  eventBridge = noopEventBridge,
+  components = {}
+}: CompositionRendererProps) {
+  const validation = validateCompositionDocument(document);
+  if (!validation.ok)
+    return (
+      <ErrorState
+        title="Invalid composition"
+        description={validation.errors.map((error) => error.message).join("; ")}
+      />
+    );
+  return (
+    <RuntimeContext.Provider
+      value={{ document, registry, dataResolver, permissionGuard, eventBridge, components }}
+    >
+      <RenderNode node={document.layout} />
+    </RuntimeContext.Provider>
+  );
+}
+
+export function RenderNode({ node }: { node: EthLayoutNode }) {
+  const ctx = useRuntimeContext();
+  const permission = ctx.permissionGuard.evaluate([
+    ...(ctx.document.permissions ?? []),
+    ...(node.permissions ?? [])
+  ]);
+  if (!permission.allowed && permission.fallback === "hide") return null;
+  if (!permission.allowed && permission.fallback === "error")
+    return <ErrorState title="Permission denied" description={permission.reason} />;
+  if (node.visibility?.defaultVisible === false) return null;
+  const children = node.children?.map((child) => <RenderNode key={child.id} node={child} />);
+  if (node.skill)
+    return (
+      <RenderSkillNode
+        node={node}
+        disabled={!permission.allowed && permission.fallback === "disable"}
+      >
+        {children}
+      </RenderSkillNode>
+    );
+  if (node.component) {
+    const Component = ctx.components[node.component.exportName] ?? Surface;
+    return (
+      <Component {...node.props} data-eth-node-id={node.id}>
+        {children}
+      </Component>
+    );
+  }
+  return (
+    <Surface title={node.props?.title as string | undefined} data-eth-node-id={node.id}>
+      {children}
+    </Surface>
+  );
+}
+
+function RenderSkillNode({
+  node,
+  disabled,
+  children
+}: {
+  node: EthLayoutNode;
+  disabled?: boolean;
+  children?: React.ReactNode;
+}) {
+  const ctx = useRuntimeContext();
+  const [Component, setComponent] = React.useState<React.ComponentType<any> | null>(null);
+  const [error, setError] = React.useState<Error | null>(null);
+  React.useEffect(() => {
+    let mounted = true;
+    Promise.resolve()
+      .then(() => ctx.registry.resolve(node.skill!.id, node.skill!.version).load())
+      .then((module) => mounted && setComponent(() => module.default))
+      .catch(
+        (reason) =>
+          mounted && setError(reason instanceof Error ? reason : new Error(String(reason)))
+      );
+    return () => {
+      mounted = false;
+    };
+  }, [ctx.registry, node.skill]);
+  if (error) return <ErrorState title="Skill failed to load" description={error.message} />;
+  if (!Component) return <EmptyState title="Loading skill" description={node.skill?.id} />;
+  return (
+    <Component
+      {...node.props}
+      {...node.skill?.input}
+      disabled={disabled}
+      data-eth-node-id={node.id}
+    >
+      {children}
+    </Component>
+  );
+}
+
+function useRuntimeContext() {
+  const value = React.useContext(RuntimeContext);
+  if (!value) throw new Error("Composition runtime context is missing");
+  return value;
+}
+
+export function validateCompositionDocument(value: unknown) {
+  return validateWithSchema(compositionDocumentSchema, value);
+}
+
+export function redactValue(value: unknown, policy?: EthRedactionPolicy): unknown {
+  if (!policy || !value || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((item) => redactValue(item, policy));
+  const output: Record<string, unknown> = {};
+  for (const [key, fieldValue] of Object.entries(value)) {
+    if (policy.fields?.includes(key)) {
+      if (policy.replacement === "omit") continue;
+      output[key] = policy.replacement === "placeholder" ? "[redacted]" : "••••";
+    } else {
+      output[key] = redactValue(fieldValue, policy);
+    }
+  }
+  return output;
+}
+
+function getByPath(value: unknown, path: string) {
+  return path
+    .replace(/^\$\.?/, "")
+    .split(".")
+    .filter(Boolean)
+    .reduce<unknown>((current, key) => {
+      if (current && typeof current === "object") return (current as Record<string, unknown>)[key];
+      return undefined;
+    }, value);
+}