PrismComponentSDK

@zephytiju/prism-component-sdk is the deterministic, framework-neutral authoring and host contract for independently released Prism UI components.

It owns component module and host types, exact Schema references, metadata-definition helpers, layout-variant normalization, manifest and package validation, deterministic fixtures, and local conformance tooling. It deliberately contains no HTTP client, Blueprint model, Meridian runtime type, component implementation, composition state, storage transport, infrastructure, or deployment authority.

Author a component

import {
  defineComponentManifest,
  defineComponentMetadata,
  definePrismComponent,
  exactSchemaRef,
} from "@zephytiju/prism-component-sdk";

const configuration = exactSchemaRef({
  catalog: "prism-components",
  schema: "status-card.configuration",
  version: "1.0.0",
  digest: "sha256:8d969eef6ecad3c29a3a629280e686cff8ca9a4ae6f95c0d54d4a8468e0898e2",
});

export const metadata = defineComponentMetadata({
  configuration: { schema: configuration },
  inputs: [],
  outputs: [],
  events: [],
  intents: [],
  actions: [],
  slots: [],
  layout: {
    supportedRoles: ["content"],
    minimumSpan: { columns: 2, rows: 1 },
    preferredSpan: { columns: 4, rows: 2 },
    resizable: true,
    overflow: "host",
  },
  variants: [
    {
      variantKey: "centered",
      label: "Centered",
      isDefault: true,
      layoutConfigVersion: 1,
      layoutConfig: {
        kind: "alignment",
        horizontal: "center",
        vertical: "center",
      },
    },
  ],
  presentation: {
    label: "Status card",
    category: "Monitoring",
    searchTerms: ["status"],
    compatibleDistributions: ["web-html"],
  },
});

export const manifest = defineComponentManifest({
  manifestVersion: 1,
  componentId: "status-card",
  releaseVersion: "1.0.0",
  moduleEntry: "./dist/component.js",
  prismComponentSdk: ">=1 <2",
  metadataEntry: "./dist/metadata.js",
  requiredHostCapabilities: [],
  dependencies: {},
  producer: { sourceRevision: "0123456789abcdef0123456789abcdef01234567" },
});

export default definePrismComponent({
  manifest,
  metadata,
  mount(context) {
    context.element.textContent = String(context.configuration);
    return () => context.element.replaceChildren();
  },
});

The component receives no layout-variant switch. Workshop materializes a selected variant into host-owned instance layout configuration before mount.

Conformance

Use defineConformanceSuite and runConformanceSuite from @zephytiju/prism-component-sdk/testing, or serialize the same candidate shape and run:

prism-component-conformance ./prism-component.conformance.json

Conformance requires a base fixture and one fixture for every declared variant. Each fixture carries deterministic preview data, accessibility evidence, and compatibility expectations. Layout validation covers simple alignment, nested stack/grid regions, and responsive breakpoint configurations.

Run the repository gates with npm run verify. A runnable, framework-free example is available through npm run example.

Exactness and boundaries

• Schema references require an explicit catalog, schema, immutable version, and SHA-256 digest. Mutable aliases such as latest, current, and active are rejected.
• Package file order, metadata, layout configurations, fixture data, and digests are canonicalized deterministically.
• Layout configurations are declarative data. Executable values, CSS, URLs, credentials, endpoints, and arbitrary prototype-bearing objects are rejected.
• Production dependencies are checked against forbidden Blueprint, Meridian, storage, streaming, infrastructure, and runtime-registry families.

Byte packages and named regions (1.1.0)

Use createComponentPackage for a canonical byte-carrying container and readComponentPackage / extractComponentPackage to verify it before an authorized build-time load. buildComponentPackage remains the unchanged v1 metadata-only descriptor. See the format-2 wire contract for path, ordering, digest, entry and module-graph rules.

createPrismRegionHost maps materialized layouts to stable component content containers; its named-region contract covers nested and responsive layouts, invalid mappings, resize and teardown. No variant switch is passed to component code. npm run example:regions runs the complete shipped fixture; npm run consumer:clean installs the tarball in an isolated consumer, loads its actual module graph and verifies mounting. To verify the published release, run npm run consumer:clean -- @zephytiju/[email protected].