@stardust-cms/vce-adapter

A reusable adapter that bridges the pure versioned-content-engine to the @stardust-cms/dashboard ContentStoreAdapter seam.

The dashboard hands the adapter structured HostContentOps and re-injects the returned ContentSnapshot; internally each op is translated to a versioned-content-engine operation and a materialized VCE snapshot is projected back to dashboard ContentPayload[] — giving the editor draft / live / publish / version history for free.

Why a separate package

The adapter imports both a concrete engine (versioned-content-engine) and the dashboard contract. The dashboard's own dependency-cruiser rules forbid importing a concrete store/engine under its src/**, so the adapter cannot live inside the dashboard. It is therefore its own package, depending on both as peers.

Install

npm install @stardust-cms/vce-adapter versioned-content-engine @stardust-cms/dashboard

Usage

The core adapter is generic over your VCE content-type map and stays content-type-agnostic by delegating every payload decision to an injected PayloadPolicy. For the demo's CmsContent, a ready-made policy ships on the /cms-content subpath:

import { VceContentStoreAdapter } from "@stardust-cms/vce-adapter";
import {
  cmsContentPayloadPolicy,
  type CmsContentTypeMap,
} from "@stardust-cms/vce-adapter/cms-content";
import { createLocalStoragePersistence } from "@stardust-cms/vce-adapter/local-storage";

const store = new VceContentStoreAdapter<CmsContentTypeMap>(SEED_CONTENT, {
  policy: cmsContentPayloadPolicy,
  persistence: createLocalStoragePersistence({ key: "my-app-content" }),
});

store satisfies the dashboard ContentStoreAdapter contract, including the optional subscribe(listener) (added in dashboard 0.1.8): every snapshot-changing operation — apply, publish, setViewVersion — notifies all listeners, so direct publish() / setViewVersion() calls re-inject in the dashboard.

Public surface

| Export | Subpath | Purpose | | --- | --- | --- | | VceContentStoreAdapter, VceAdapterOptions | . | The generic adapter class + its options. | | PayloadPolicy, EditPatch, InsertPayload | . | The injectable content-type bridge. | | PersistenceAdapter | . | The pluggable persistence seam. | | cmsContentPayloadPolicy, CmsContentTypeMap | ./cms-content | Ready-made policy reproducing the demo's exact CmsContent behavior. | | createLocalStoragePersistence | ./local-storage | Browser localStorage persistence (browser-only; kept off the core path). |

Persistence semantics

createLocalStoragePersistence persists only the current working draft (as SeedItem[]), not version history — "re-seed working draft, drop history." On reload the saved draft becomes a fresh published baseline. All storage access is guarded and quota-tolerant: a failure degrades to the built-in seed rather than throwing.

Layering

• Core (adapter, types, project, host-contract) is generic and environment-agnostic.
• CmsContent policy (/cms-content) is the only module that pulls in @stardust-cms/iframe-adapter protocol types.
• Browser persistence (/local-storage) is the only module that touches localStorage / DOM.

These edges are enforced by dependency-cruiser, strict TypeScript, and ESLint (typescript-eslint strict + stylistic, no any / non-null ! / ts-* comments / eslint-disable).