@magfur-alam/core

Framework-agnostic builder engine: the node tree, undo/redo history, the element registry, Zod-based serialization, style resolution, and URL sanitization. No React, no DOM — this package is safe to import from a Node script, a server realm, or any other JS environment, and it's what makes the engine reusable outside React someday without a rewrite.

Part of the Next.js Database-Backed Visual Page Builder monorepo — see the root README for the full architecture and PLAN.md for how this package was built, phase by phase.

Install

npm install @magfur-alam/core

What's in here

• Tree ops (addNode, removeNode, moveNode, duplicateNode, pasteNode, replaceNode) — pure, Immer-backed functions operating on a PageDocument. Structural sharing means an edit to one node leaves every other node's object reference untouched, which is what lets consumers (like @magfur-alam/react's <PageRenderer>) skip re-rendering unaffected subtrees.
• createPageBuilderStore() — a Zustand vanilla store (not React-bound) wrapping the tree ops with selection-independent state, undo/redo (100-step history, rapid same-node edits coalesced into one step), and clipboard actions.
• The element registry (registerElement, getElement, defaultElementRegistry) — a globalThis-keyed singleton so it survives being imported from more than one bundle/realm (CJS+ESM, server+browser) without silently duplicating itself.
• Serialization (parsePageDocument, serializePageDocument, deserializePageDocument) — Zod schemas validating every incoming page JSON blob, including a guard that rejects any props bag containing a dangerouslySetInnerHTML or bare __html key at any nesting depth (there is no raw-HTML element in this model).
• Styling (stylesToCss, resolveStyleValue, GlobalStyleTokens) — a responsive (desktop/tablet/mobile, with fallback) style schema and a resolver that turns it into inline CSS.
• Security (isSafeUrl, sanitizeUrl) — a URL scheme allowlist (http:/https:/mailto:/tel:/relative), with data:image/* allowed only opt-in and data:image/svg+xml excluded even then (SVG can carry <script>/onload= even served as an "image").

Usage

import { createEmptyDocument, createNode, addNode, createPageBuilderStore, registerElement } from "@magfur-alam/core";

registerElement({
  type: "heading",
  label: "Heading",
  category: "Basic",
  component: MyHeadingComponent, // from @magfur-alam/elements, or your own
});

const store = createPageBuilderStore({ document: createEmptyDocument() });
const node = createNode("heading", { props: { text: "Hello" } });
store.getState().addNode(node, store.getState().document.root.id);

Most apps won't call this package directly — @magfur-alam/react renders its documents, @magfur-alam/editor provides the editing UI, and @magfur-alam/next persists them. This package is the shared foundation underneath all three.