@sutraa/kalpa-renderer-contract

@sutraa/kalpa-renderer-contract checks whether a renderer adapter’s declared capability support is consistent with a Kalpa manifest. It supplies a conformance function and a DOM-first fallback resolver; it does not render DOM, Canvas, or any other visual output.

npm install @sutraa/kalpa-renderer-contract

Define an adapter

An adapter identifies its representation, declares its supported capabilities, and projects a graph snapshot plus runtime state into a renderer-owned result.

import {
  evaluateRendererConformance,
  resolveRendererAdapter,
  type RendererAdapter,
} from "@sutraa/kalpa-renderer-contract";

const domAdapter: RendererAdapter = {
  id: "my-dom-adapter",
  representationId: "dom",
  essentialTaskSupport: "complete",
  supportedCapabilities: ["selectable", "inspectable"],
  project(snapshot, state) {
    return {
      rendererId: "my-dom-adapter",
      entityIds: snapshot.entities.map((entity) => entity.id),
      selectedEntityId: state.selectedEntityId,
      inspectedEntityId: state.inspectedEntityId,
      interactionMode: "semantic-controls",
    };
  },
};

const conformance = evaluateRendererConformance(manifest, domAdapter);
if (!conformance.ok) console.error(conformance.diagnostics);

What conformance checks

| Check | Failure condition | | --- | --- | | Representation exists | adapter representation is not declared by the manifest. | | Capability claims | adapter claims a capability absent from the representation declaration. | | Essential tasks | an adapter marked complete omits an essential manifest capability. | | Completion status | a manifest representation marked complete uses a non-complete adapter. |

project is invoked with an initial state during conformance so projectedEntityCount can be reported. Keep projection deterministic and side-effect-free.

Choose a representation with fallback

const result = resolveRendererAdapter(manifest, [domAdapter], "canvas");

console.log(result.adapter.id); // "my-dom-adapter"
console.log(result.reason);     // DOM baseline selected as fallback.

The resolver chooses an adapter matching the requested dom or canvas representation when possible. If a requested non-DOM adapter is non-conformant and a DOM adapter exists, it returns the DOM adapter as the fallback. If no requested adapter exists, it also attempts the DOM adapter. It throws only when no adapter is available.

Scope boundary

The contract understands the schema 0.1 representation IDs (dom and canvas) and declared capability lists. It does not create controls, manage browser events, provide accessibility implementation, or bundle the repository’s reference renderer.

License

MIT. Requires Node.js 18 or later.