Integrate Restormel Graph in a SvelteKit app

This page is the single public integration doc for Restormel Graph. Prefer it over ad hoc prompts: it is versioned with the restormel.dev site and mirrors the maintainer note docs/restormel-graph-sophia-consumer.md for SOPHIA-depth wiring. Step-by-step on this site is the primary interface; CLI or MCP tooling is fine only if it is generated or tested against the same content and never treated as the only source of truth.

What to install

Minimum published versions (bump as your semver range allows; verify on npm after a fresh publish—registry lag can briefly hide tarballs):

Package	Role	Peer / notes
@restormel/graph-core	DTOs + layout / trace / workspace	Node >=20; no Svelte peer
@restormel/ui-graph-svelte	Svelte UI + semantic styles + packaged CSS export	Peer: svelte ^5.0.0; @sveltejs/kit is a consumer framework, not a peer

pnpm add @restormel/graph-core @restormel/ui-graph-svelte

Or add to package.json:

{
  "dependencies": {
    "@restormel/graph-core": "^0.1.1",
    "@restormel/ui-graph-svelte": "^0.1.1"
  }
}

What each package owns

• graph-core — Contract v0 types in viewModel; orbital layout; trace labels; workspace filters. No components, no contracts package.
• ui-graph-svelte — GraphCanvas, NodeDetail, graphCanvasEdgeKey, optional styles.css.

Stable import map

Use only paths declared in each package’s exports. Do not deep-import src/.

Import path	Purpose
@restormel/graph-core/viewModel	GraphData, GraphNode, GraphEdge, ghosts, GraphRendererProps, semantic style types
@restormel/graph-core/layout	computeLayout (orbital positions)
@restormel/graph-core/trace	Trace tags / labels
@restormel/graph-core/workspace	Filter / scope helpers
@restormel/graph-core	Barrel of MVP exports
@restormel/ui-graph-svelte	GraphCanvas, NodeDetail, graphCanvasEdgeKey; types GraphCanvasProps, NodeDetailProps
@restormel/ui-graph-svelte/styles.css	Packaged component CSS (see CSS contract)

Framework wiring (Vite / SvelteKit)

Prebundling and SSR can break Svelte libraries unless both packages are treated as external for SSR bundling. Mirror apps/restormel-graph-demo/vite.config.ts in this repo:

import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [sveltekit()],
  ssr: {
    noExternal: ["@restormel/ui-graph-svelte", "@restormel/graph-core"],
  },
});

If dev prebundle errors mention graph-core only, try optimizeDeps.include for @restormel/graph-core/layout (rare).

CSS contract

The canvas expects a :root token story. Use the table below to decide what you must define vs what is optional; diff your design-tokens.css (or equivalent) against the demo reference file.

Layer	Required for sensible defaults	Optional / extended parity
Surfaces & text	--color-bg, --color-text, --color-muted, --color-border, --color-surface, --color-surface-raised	--color-surface-sunken, --color-dim (decorative only)
Accents & states	--color-sage (+ --color-sage-bg, --color-sage-border where used)	--color-copper, --color-blue, --color-teal, --color-coral, --color-purple, --color-amber (+ matching *-bg / *-border)
Type & rhythm	--font-ui, --text-meta or --text-ui, --text-body, --leading-body, --space-* used by controls	--font-display, --font-body, larger type scale tokens
Chrome	--radius-sm, --radius-md, --transition-fast, --focus-ring-width, --focus-ring-color, --focus-ring-offset	—
Packaged library CSS	—	@restormel/ui-graph-svelte/styles.css — component-scoped rules (build artefact dist/ui-graph-svelte.css in repo). Does not define the palette; import for layout / animation parity or when you have no token sheet yet.

Stable references to diff or copy from: apps/restormel-graph-demo/src/lib/graph-demo-tokens.css (full SOPHIA Design B mirror used by the demo) · packaged stylesheet entrypoint in repo tree packages/ui-graph-svelte (exports["./styles.css"] → built CSS).

/* Optional: component-level rules from the package */
import "@restormel/ui-graph-svelte/styles.css";

Integration seam

Hosts produce GraphData; adapters live in the app. Domain-specific mappers (e.g. from an internal graph kit) should return types compatible with @restormel/graph-core/viewModel.

Minimal runnable example (analogue to a five-line quickstart)

<script lang="ts">
  import { GraphCanvas } from "@restormel/ui-graph-svelte";
  import type { GraphData } from "@restormel/graph-core/viewModel";

  const graphData: GraphData = {
    nodes: [
      { id: "a", type: "source", label: "Source A" },
      { id: "b", type: "claim", label: "Claim B" },
    ],
    edges: [{ from: "a", to: "b", type: "supports" }],
    ghostNodes: [],
    ghostEdges: [],
  };
</script>

<GraphCanvas
  nodes={graphData.nodes}
  edges={graphData.edges}
  ghostNodes={graphData.ghostNodes}
  ghostEdges={graphData.ghostEdges}
/>

A full SvelteKit demo with mock data lives under apps/restormel-graph-demo (/dev/graph-portability).

Verification

After install:

npm view @restormel/graph-core version
npm view @restormel/ui-graph-svelte version

Then in your app:

pnpm run check
pnpm run build

Upstream CI runs scripts/smoke-graph-packages-consumer.sh (tarball install + check + build on a copy of the demo outside the workspace graph).

Upgrade / drift

• Authoritative DTOs: packages/graph-core/src/viewModel.ts in restormel-keys (banner: RESTORMEL GRAPH CONTRACT v0).
• Diff that file across versions before bumping; if fields change, semver should reflect breaks and your adapter must update first.
• Track package history via npm and GitHub releases tagged graph-v*.

Not in MVP (explicit)

• No @restormel/contracts inside graph-core or ui-graph-svelte.
• Compare, lineage, projection, evaluation, diff, and summary ship in the published package @restormel/graph-reasoning-extensions (with contracts) — not inside the canvas packages. Adapt their outputs into GraphData for GraphCanvas.

Troubleshooting

• SSR / “Cannot find module” during dev or build: ensure both @restormel/ui-graph-svelte and @restormel/graph-core are in ssr.noExternal. Listing only the UI package is a common mistake when graph-core subpaths are pulled in transitively.
• Vite prebundle errors: try optimizeDeps.include: ["@restormel/graph-core/layout"] (or the subpath mentioned in the error); clear Vite cache if upgrades look “stuck.”
• svelte-check / callback types: import GraphCanvasProps / NodeDetailProps from @restormel/ui-graph-svelte; trust published .d.ts over inferred props.
• Duplicate @restormel/graph-core: a workspace package with the same name as npm will shadow installs—rename or remove the local package and use npm (or explicit tarball overrides) as a single source.
• Lockfile mismatch: after bumping one of the pair, run a fresh install so ui-graph-svelte resolves the same graph-core version you intend.

Related docs

Reasoning extensions & contracts · Contract v0 scope · Recipes · API reference · Migrate from a custom canvas · Releases & support