@elytracms/core 0.0.6

package/dist/project-graph/issues.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/** Stable codes for structured validation issues (brief §4.11, §7.1). */
+export declare const issueCodeSchema: z.ZodEnum<{
+    "invalid-component-name": "invalid-component-name";
+    "unknown-component": "unknown-component";
+    "duplicate-node-id": "duplicate-node-id";
+    "unknown-prop": "unknown-prop";
+    "invalid-prop": "invalid-prop";
+    "binding-not-allowed": "binding-not-allowed";
+    "unresolved-binding": "unresolved-binding";
+    "missing-required-slot": "missing-required-slot";
+    "unknown-slot": "unknown-slot";
+    "forbidden-component": "forbidden-component";
+    "server-only-component": "server-only-component";
+    "unknown-layout": "unknown-layout";
+    "route-conflict": "route-conflict";
+    "invalid-container-direction": "invalid-container-direction";
+    "invalid-container-alignment": "invalid-container-alignment";
+    "invalid-container-gap": "invalid-container-gap";
+    "invalid-container-columns": "invalid-container-columns";
+    "invalid-container-responsive": "invalid-container-responsive";
+}>;
+export type IssueCode = z.infer<typeof issueCodeSchema>;
+export declare const issueSeveritySchema: z.ZodEnum<{
+    error: "error";
+    warning: "warning";
+}>;
+export type IssueSeverity = z.infer<typeof issueSeveritySchema>;
+/** A structured validation issue carrying a JSON path into the graph. */
+export declare const validationIssueSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        "invalid-component-name": "invalid-component-name";
+        "unknown-component": "unknown-component";
+        "duplicate-node-id": "duplicate-node-id";
+        "unknown-prop": "unknown-prop";
+        "invalid-prop": "invalid-prop";
+        "binding-not-allowed": "binding-not-allowed";
+        "unresolved-binding": "unresolved-binding";
+        "missing-required-slot": "missing-required-slot";
+        "unknown-slot": "unknown-slot";
+        "forbidden-component": "forbidden-component";
+        "server-only-component": "server-only-component";
+        "unknown-layout": "unknown-layout";
+        "route-conflict": "route-conflict";
+        "invalid-container-direction": "invalid-container-direction";
+        "invalid-container-alignment": "invalid-container-alignment";
+        "invalid-container-gap": "invalid-container-gap";
+        "invalid-container-columns": "invalid-container-columns";
+        "invalid-container-responsive": "invalid-container-responsive";
+    }>;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    message: z.ZodString;
+    path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    nodeId: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("./json").JsonValue, unknown, z.core.$ZodTypeInternals<import("./json").JsonValue, unknown>>>>;
+}, z.core.$strip>;
+export type ValidationIssue = z.infer<typeof validationIssueSchema>;
+export type GraphPath = ReadonlyArray<string | number>;

package/dist/project-graph/issues.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { idSchema } from './ids';
+import { jsonValueSchema } from './json';
+/** Stable codes for structured validation issues (brief §4.11, §7.1). */
+export const issueCodeSchema = z.enum([
+    'invalid-component-name',
+    'unknown-component',
+    'duplicate-node-id',
+    'unknown-prop',
+    'invalid-prop',
+    'binding-not-allowed',
+    'unresolved-binding',
+    'missing-required-slot',
+    'unknown-slot',
+    // Placement constraints (EC-186): a component appears where its slot's `allow`
+    // vocabulary — or a composition field's `allow` — forbids it.
+    'forbidden-component',
+    // Canvas-eligibility (EC-191): a server-only (RSC / non-client-renderable)
+    // component was placed in an editor composition, which is client-rendered.
+    // Such components belong in dev frames (page.tsx / layout.tsx), not the canvas.
+    'server-only-component',
+    'unknown-layout',
+    'route-conflict',
+    // Layout containers (EC-161): malformed Stack/Grid canonical props.
+    'invalid-container-direction',
+    'invalid-container-alignment',
+    'invalid-container-gap',
+    'invalid-container-columns',
+    // Responsive defaults (EC-163): malformed Grid stack-on-mobile override.
+    'invalid-container-responsive',
+]);
+export const issueSeveritySchema = z.enum(['error', 'warning']);
+/** A structured validation issue carrying a JSON path into the graph. */
+export const validationIssueSchema = z.object({
+    code: issueCodeSchema,
+    severity: issueSeveritySchema,
+    message: z.string(),
+    /** JSON path into the graph, e.g. ['pages', 0, 'root', 'slots', 'children', 1]. */
+    path: z.array(z.union([z.string(), z.number()])),
+    /** The offending node id, when applicable. */
+    nodeId: idSchema.optional(),
+    meta: z.record(z.string(), jsonValueSchema).optional(),
+});
+//# sourceMappingURL=issues.js.map

package/dist/project-graph/issues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issues.js","sourceRoot":"","sources":["../../src/project-graph/issues.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AAExC,yEAAyE;AACzE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC;IACpC,wBAAwB;IACxB,mBAAmB;IACnB,mBAAmB;IACnB,cAAc;IACd,cAAc;IACd,qBAAqB;IACrB,oBAAoB;IACpB,uBAAuB;IACvB,cAAc;IACd,+EAA+E;IAC/E,8DAA8D;IAC9D,qBAAqB;IACrB,2EAA2E;IAC3E,2EAA2E;IAC3E,gFAAgF;IAChF,uBAAuB;IACvB,gBAAgB;IAChB,gBAAgB;IAChB,oEAAoE;IACpE,6BAA6B;IAC7B,6BAA6B;IAC7B,uBAAuB;IACvB,2BAA2B;IAC3B,yEAAyE;IACzE,8BAA8B;CAC/B,CAAC,CAAA;AAGF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAA;AAG/D,yEAAyE;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,IAAI,EAAE,eAAe;IACrB,QAAQ,EAAE,mBAAmB;IAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,mFAAmF;IACnF,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAChD,8CAA8C;IAC9C,MAAM,EAAE,QAAQ,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,eAAe,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAA"}

package/dist/project-graph/json.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+/** A JSON-serializable value. The project graph contains only these — never functions or runtime handles. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare const jsonValueSchema: z.ZodType<JsonValue>;

package/dist/project-graph/json.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export const jsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema),
+]));
+//# sourceMappingURL=json.js.map

package/dist/project-graph/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/project-graph/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAWvB,MAAM,CAAC,MAAM,eAAe,GAAyB,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAC/D,CAAC,CAAC,KAAK,CAAC;IACN,CAAC,CAAC,MAAM,EAAE;IACV,CAAC,CAAC,MAAM,EAAE;IACV,CAAC,CAAC,OAAO,EAAE;IACX,CAAC,CAAC,IAAI,EAAE;IACR,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;IACxB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,eAAe,CAAC;CACtC,CAAC,CACH,CAAA"}

package/dist/project-graph/node.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import type { BindingReference, Condition } from './binding';
+import type { JsonValue } from './json';
+/** A prop value is either a static JSON value or a binding into a data source. */
+export declare const propValueSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"static">;
+    value: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"binding">;
+    binding: z.ZodObject<{
+        sourceId: z.ZodString;
+        token: z.ZodString;
+        mode: z.ZodEnum<{
+            object: "object";
+            value: "value";
+            spread: "spread";
+            repeaterItem: "repeaterItem";
+            condition: "condition";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "kind">;
+export type PropValue = z.infer<typeof propValueSchema>;
+/**
+ * An instance of a registered component. Recursive via `slots`: each named slot
+ * holds an ordered list of child nodes. The reserved slot `children` is the default
+ * insertion point.
+ */
+export interface ComponentNode {
+    id: string;
+    /** Namespaced registered component id (validated semantically, not at parse time). */
+    componentId: string;
+    props?: Record<string, PropValue>;
+    slots?: Record<string, ComponentNode[]>;
+    condition?: Condition;
+}
+export declare const componentNodeSchema: z.ZodType<ComponentNode>;
+/** Convenience constructors for prop values. */
+export declare function staticProp(value: JsonValue): PropValue;
+export declare function boundProp(binding: BindingReference): PropValue;
+/** Structural guard for a stored component node (id + componentId present). */
+export declare function isComponentNode(value: unknown): value is ComponentNode;
+/**
+ * Coerce a stored blocks/composition field value into its root node list — the
+ * inverse of how a `blocks` field persists (a single node for cardinality
+ * `one`, an array for `many`). Non-node entries are dropped; anything else
+ * yields `[]`.
+ */
+export declare function blockRootsOf(value: unknown): ComponentNode[];

package/dist/project-graph/node.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { bindingReferenceSchema, conditionSchema } from './binding';
+import { idSchema } from './ids';
+import { jsonValueSchema } from './json';
+/** A prop value is either a static JSON value or a binding into a data source. */
+export const propValueSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('static'), value: jsonValueSchema }),
+    z.object({ kind: z.literal('binding'), binding: bindingReferenceSchema }),
+]);
+export const componentNodeSchema = z.lazy(() => z.object({
+    id: idSchema,
+    componentId: idSchema,
+    props: z.record(z.string(), propValueSchema).optional(),
+    slots: z.record(z.string(), z.array(componentNodeSchema)).optional(),
+    condition: conditionSchema.optional(),
+}));
+/** Convenience constructors for prop values. */
+export function staticProp(value) {
+    return { kind: 'static', value };
+}
+export function boundProp(binding) {
+    return { kind: 'binding', binding };
+}
+/** Structural guard for a stored component node (id + componentId present). */
+export function isComponentNode(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.id === 'string' &&
+        typeof value.componentId === 'string');
+}
+/**
+ * Coerce a stored blocks/composition field value into its root node list — the
+ * inverse of how a `blocks` field persists (a single node for cardinality
+ * `one`, an array for `many`). Non-node entries are dropped; anything else
+ * yields `[]`.
+ */
+export function blockRootsOf(value) {
+    if (Array.isArray(value))
+        return value.filter(isComponentNode);
+    return isComponentNode(value) ? [value] : [];
+}
+//# sourceMappingURL=node.js.map

package/dist/project-graph/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../src/project-graph/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAEnE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AAGxC,kFAAkF;AAClF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC1D,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IAC/D,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC;CAC1E,CAAC,CAAA;AAiBF,MAAM,CAAC,MAAM,mBAAmB,GAA6B,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CACvE,CAAC,CAAC,MAAM,CAAC;IACP,EAAE,EAAE,QAAQ;IACZ,WAAW,EAAE,QAAQ;IACrB,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,eAAe,CAAC,CAAC,QAAQ,EAAE;IACvD,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpE,SAAS,EAAE,eAAe,CAAC,QAAQ,EAAE;CACtC,CAAC,CACH,CAAA;AAED,gDAAgD;AAChD,MAAM,UAAU,UAAU,CAAC,KAAgB;IACzC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;AAClC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAA;AACrC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAA0B,CAAC,EAAE,KAAK,QAAQ;QAClD,OAAQ,KAAmC,CAAC,WAAW,KAAK,QAAQ,CACrE,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;IAC9D,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AAC9C,CAAC"}

package/dist/project-graph/normalize.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentNode } from './node';
+import type { ProjectGraph } from './structure';
+/**
+ * Normalize the container structure of a page/layout tree. The root itself is the
+ * tree's anchor and is never dissolved or removed; its subtree is fully normalized.
+ * Returns the same root reference when the tree is already normal.
+ */
+export declare function normalizeContainers(root: ComponentNode): ComponentNode;
+/**
+ * Normalize every layout tree in a project graph (EC-187: layouts-only).
+ * Identity-preserving: returns the same graph reference when nothing changed, so
+ * callers (and undo histories holding normalized snapshots) can detect no-ops by
+ * reference.
+ */
+export declare function normalizeProjectGraph(graph: ProjectGraph): ProjectGraph;
+/** True when a tree is already container-normal (normalization would be a no-op). */
+export declare function isContainerNormalized(root: ComponentNode): boolean;

package/dist/project-graph/normalize.js

@@ -0,0 +1,110 @@
+import { DEFAULT_SLOT } from './ids';
+import { isLayoutContainerNode } from './container';
+/**
+ * Layout-container normalization (EC-161, vision §3.1 / §6).
+ *
+ * Pure, graph-level functions — no UI, no store coupling — that keep container
+ * structure healthy after edits ("no wrapper soup after six months of editing"):
+ *
+ * 1. **Empty containers are removed.** A `Stack`/`Grid` whose `children` slot is
+ *    empty disappears from its parent slot.
+ * 2. **Single-child containers dissolve in place.** The remaining child takes the
+ *    container's position in the parent slot.
+ * 3. **Cascades resolve in one pass.** Normalization is bottom-up, so dissolving
+ *    or removing an inner container can dissolve its (now single-child or empty)
+ *    ancestors in the same call.
+ *
+ * Guard rails (deliberate non-rules):
+ * - **Roots are anchors.** A page/layout root is never dissolved or removed, even
+ *   when it is an empty or single-child container — pages must keep a root, and
+ *   the root's identity is stable for selection/undo.
+ * - **Conditional containers are meaningful wrappers.** A container carrying a
+ *   render `condition` gates its children; dissolving it would drop the gate, so
+ *   it is left intact.
+ * - **Foreign slot content is never dropped.** A container with nodes in any slot
+ *   other than `children` is malformed (validation flags it) but normalization
+ *   refuses to silently destroy content.
+ *
+ * Properties (tested): deterministic, identity-preserving on already-normal input
+ * (`normalize(g) === g`), and therefore idempotent
+ * (`normalize(normalize(g)) === normalize(g)`).
+ */
+/** True when any slot other than `children` holds nodes. */
+function hasForeignSlotContent(node) {
+    return Object.entries(node.slots ?? {}).some(([slot, children]) => slot !== DEFAULT_SLOT && children.length > 0);
+}
+/**
+ * Decide how an already-normalized child node appears in its parent slot:
+ * `[]` removes it, `[child]` dissolves a single-child container in place, and
+ * `[node]` keeps it as-is.
+ */
+function resolveChild(node) {
+    if (!isLayoutContainerNode(node))
+        return [node];
+    if (node.condition)
+        return [node];
+    if (hasForeignSlotContent(node))
+        return [node];
+    const children = node.slots?.[DEFAULT_SLOT] ?? [];
+    if (children.length === 0)
+        return []; // rule 1: empty container removed
+    if (children.length === 1)
+        return [children[0]]; // rule 2: dissolve in place
+    return [node];
+}
+/** Bottom-up normalization of a node's slots. Returns the same reference when nothing changed. */
+function normalizeNode(node) {
+    if (!node.slots)
+        return node;
+    let changed = false;
+    const slots = {};
+    for (const [slot, children] of Object.entries(node.slots)) {
+        let slotChanged = false;
+        const next = [];
+        for (const child of children) {
+            const normalized = normalizeNode(child);
+            const resolved = resolveChild(normalized);
+            if (normalized !== child || resolved.length !== 1 || resolved[0] !== child) {
+                slotChanged = true;
+            }
+            next.push(...resolved);
+        }
+        slots[slot] = slotChanged ? next : children;
+        if (slotChanged)
+            changed = true;
+    }
+    return changed ? { ...node, slots } : node;
+}
+/**
+ * Normalize the container structure of a page/layout tree. The root itself is the
+ * tree's anchor and is never dissolved or removed; its subtree is fully normalized.
+ * Returns the same root reference when the tree is already normal.
+ */
+export function normalizeContainers(root) {
+    return normalizeNode(root);
+}
+function normalizeLayout(layout) {
+    const root = normalizeContainers(layout.root);
+    return root === layout.root ? layout : { ...layout, root };
+}
+/**
+ * Normalize every layout tree in a project graph (EC-187: layouts-only).
+ * Identity-preserving: returns the same graph reference when nothing changed, so
+ * callers (and undo histories holding normalized snapshots) can detect no-ops by
+ * reference.
+ */
+export function normalizeProjectGraph(graph) {
+    let changed = false;
+    const layouts = graph.layouts.map((layout) => {
+        const next = normalizeLayout(layout);
+        if (next !== layout)
+            changed = true;
+        return next;
+    });
+    return changed ? { ...graph, layouts } : graph;
+}
+/** True when a tree is already container-normal (normalization would be a no-op). */
+export function isContainerNormalized(root) {
+    return normalizeContainers(root) === root;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/project-graph/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/project-graph/normalize.ts"],"names":[],"mappings":"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"}

package/dist/project-graph/serialize.d.ts

@@ -0,0 +1,36 @@
+import type { z } from 'zod';
+import type { ProjectGraph } from './structure';
+import type { ComponentNode } from './node';
+/**
+ * Serialize a project graph to JSON. Parsing first guarantees the output contains no
+ * runtime-only values and that defaults are applied (brief §7.1).
+ */
+export declare function serializeProjectGraph(graph: ProjectGraph): string;
+export type ParseResult = {
+    ok: true;
+    graph: ProjectGraph;
+} | {
+    ok: false;
+    error: z.ZodError;
+};
+/** Parse a project graph from a JSON string or already-parsed value. Never throws on invalid input. */
+export declare function parseProjectGraph(input: string | unknown): ParseResult;
+/** True if the graph's schema version matches the version this package understands. */
+export declare function isCompatibleSchemaVersion(graph: ProjectGraph): boolean;
+/**
+ * Serialize a composition **field value** (EC-186, AD-12) — a single
+ * `ComponentNode` tree, not a whole graph. Parsing first applies defaults and
+ * strips runtime-only values, exactly like {@link serializeProjectGraph}. A
+ * field value is an untethered tree (no `schemaVersion` wrapper); revisions ride
+ * the document that holds it.
+ */
+export declare function serializeComponentNode(node: ComponentNode): string;
+export type ParseNodeResult = {
+    ok: true;
+    node: ComponentNode;
+} | {
+    ok: false;
+    error: z.ZodError;
+};
+/** Parse a composition field value from a JSON string or value. Never throws on invalid input. */
+export declare function parseComponentNode(input: string | unknown): ParseNodeResult;

package/dist/project-graph/serialize.js

@@ -0,0 +1,51 @@
+import { PROJECT_GRAPH_SCHEMA_VERSION, projectGraphSchema } from './structure';
+import { componentNodeSchema } from './node';
+/**
+ * Serialize a project graph to JSON. Parsing first guarantees the output contains no
+ * runtime-only values and that defaults are applied (brief §7.1).
+ */
+export function serializeProjectGraph(graph) {
+    const parsed = projectGraphSchema.parse(graph);
+    return JSON.stringify(parsed);
+}
+/** Parse a project graph from a JSON string or already-parsed value. Never throws on invalid input. */
+export function parseProjectGraph(input) {
+    let json;
+    try {
+        json = typeof input === 'string' ? JSON.parse(input) : input;
+    }
+    catch {
+        // Treat malformed JSON the same as a failed schema parse of `undefined`.
+        json = undefined;
+    }
+    const result = projectGraphSchema.safeParse(json);
+    return result.success ? { ok: true, graph: result.data } : { ok: false, error: result.error };
+}
+/** True if the graph's schema version matches the version this package understands. */
+export function isCompatibleSchemaVersion(graph) {
+    return graph.schemaVersion === PROJECT_GRAPH_SCHEMA_VERSION;
+}
+/**
+ * Serialize a composition **field value** (EC-186, AD-12) — a single
+ * `ComponentNode` tree, not a whole graph. Parsing first applies defaults and
+ * strips runtime-only values, exactly like {@link serializeProjectGraph}. A
+ * field value is an untethered tree (no `schemaVersion` wrapper); revisions ride
+ * the document that holds it.
+ */
+export function serializeComponentNode(node) {
+    const parsed = componentNodeSchema.parse(node);
+    return JSON.stringify(parsed);
+}
+/** Parse a composition field value from a JSON string or value. Never throws on invalid input. */
+export function parseComponentNode(input) {
+    let json;
+    try {
+        json = typeof input === 'string' ? JSON.parse(input) : input;
+    }
+    catch {
+        json = undefined;
+    }
+    const result = componentNodeSchema.safeParse(json);
+    return result.success ? { ok: true, node: result.data } : { ok: false, error: result.error };
+}
+//# sourceMappingURL=serialize.js.map

package/dist/project-graph/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../src/project-graph/serialize.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAE9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAA;AAG5C;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAmB;IACvD,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC9C,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;AAC/B,CAAC;AAMD,uGAAuG;AACvG,MAAM,UAAU,iBAAiB,CAAC,KAAuB;IACvD,IAAI,IAAa,CAAA;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,IAAI,GAAG,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IACjD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAA;AAC/F,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,yBAAyB,CAAC,KAAmB;IAC3D,OAAO,KAAK,CAAC,aAAa,KAAK,4BAA4B,CAAA;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAmB;IACxD,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC9C,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;AAC/B,CAAC;AAMD,kGAAkG;AAClG,MAAM,UAAU,kBAAkB,CAAC,KAAuB;IACxD,IAAI,IAAa,CAAA;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IAClD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAA;AAC9F,CAAC"}

package/dist/project-graph/structure.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * A shared layout wrapper. Its root tree contains an `outlet` slot where a page
+ * composition renders (EC-187). Layouts are the dev-frame scaffolding — they
+ * change rarely and remain in the canonical graph; pages moved OUT of the graph
+ * into `page`-collection documents (their `body` is a composition field value).
+ */
+export declare const layoutSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    root: z.ZodType<import("./node").ComponentNode, unknown, z.core.$ZodTypeInternals<import("./node").ComponentNode, unknown>>;
+}, z.core.$strip>;
+export type Layout = z.infer<typeof layoutSchema>;
+/**
+ * Schema version 2 (EC-187): the graph is LAYOUTS-ONLY. Version 1 carried a
+ * `pages` array (page-as-graph-node); v2 removes it — a page is now a document
+ * in the `page` collection whose `body` composition renders into a layout via
+ * `renderCompositionInLayout`. A deployment NOT reseeded to v2 serves a null
+ * graph, so the host degrades to its visible fallback rather than crashing.
+ */
+export declare const PROJECT_GRAPH_SCHEMA_VERSION = 2;
+/**
+ * The canonical project graph — LAYOUTS-ONLY (EC-187). The single source of
+ * truth for the dev-frame layout scaffolding; page content lives in the `page`
+ * collection.
+ */
+export declare const projectGraphSchema: z.ZodObject<{
+    id: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    settingsRef: z.ZodOptional<z.ZodString>;
+    layouts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        root: z.ZodType<import("./node").ComponentNode, unknown, z.core.$ZodTypeInternals<import("./node").ComponentNode, unknown>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ProjectGraph = z.infer<typeof projectGraphSchema>;

package/dist/project-graph/structure.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { idSchema } from './ids';
+import { componentNodeSchema } from './node';
+/**
+ * A shared layout wrapper. Its root tree contains an `outlet` slot where a page
+ * composition renders (EC-187). Layouts are the dev-frame scaffolding — they
+ * change rarely and remain in the canonical graph; pages moved OUT of the graph
+ * into `page`-collection documents (their `body` is a composition field value).
+ */
+export const layoutSchema = z.object({
+    id: idSchema,
+    name: z.string().min(1),
+    root: componentNodeSchema,
+});
+/**
+ * Schema version 2 (EC-187): the graph is LAYOUTS-ONLY. Version 1 carried a
+ * `pages` array (page-as-graph-node); v2 removes it — a page is now a document
+ * in the `page` collection whose `body` composition renders into a layout via
+ * `renderCompositionInLayout`. A deployment NOT reseeded to v2 serves a null
+ * graph, so the host degrades to its visible fallback rather than crashing.
+ */
+export const PROJECT_GRAPH_SCHEMA_VERSION = 2;
+/**
+ * The canonical project graph — LAYOUTS-ONLY (EC-187). The single source of
+ * truth for the dev-frame layout scaffolding; page content lives in the `page`
+ * collection.
+ */
+export const projectGraphSchema = z.object({
+    id: idSchema,
+    schemaVersion: z.number().int().nonnegative(),
+    metadata: z.object({ name: z.string().optional() }).optional(),
+    /** Link to project settings owned by studio-core. */
+    settingsRef: idSchema.optional(),
+    layouts: z.array(layoutSchema).default([]),
+});
+//# sourceMappingURL=structure.js.map

package/dist/project-graph/structure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.js","sourceRoot":"","sources":["../../src/project-graph/structure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,EAAE,EAAE,QAAQ;IACZ,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,IAAI,EAAE,mBAAmB;CAC1B,CAAC,CAAA;AAGF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAA;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,EAAE,EAAE,QAAQ;IACZ,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC7C,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC9D,qDAAqD;IACrD,WAAW,EAAE,QAAQ,CAAC,QAAQ,EAAE;IAChC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC3C,CAAC,CAAA"}

package/dist/project-graph/validate.d.ts

@@ -0,0 +1,84 @@
+import type { ComponentNode } from './node';
+import type { ValidationIssue } from './issues';
+import type { ProjectGraph } from './structure';
+/**
+ * Structural views of a component manifest, supplied by the registry. The graph
+ * package depends only on these shapes (not on `@elytracms/core/component-registry`) so it
+ * stays free of cycles. The registry's Manifest satisfies these structurally.
+ */
+export interface PropView {
+    /** Whether this prop accepts a binding. Defaults to allowed when omitted. */
+    bindable?: boolean;
+    /** Optional static-value validator (typically backed by the manifest's Zod schema). */
+    validate?: (value: unknown) => boolean;
+}
+export interface SlotView {
+    name: string;
+    required?: boolean;
+    /**
+     * Allowed child component ids (EC-186). Omit to allow any registered
+     * component; when present, a child whose `componentId` is not listed is a
+     * `forbidden-component` error. Mirrors the registry's `SlotSpec.allow`.
+     */
+    allow?: readonly string[];
+}
+export interface ManifestView {
+    id: string;
+    props?: Record<string, PropView>;
+    slots?: SlotView[];
+    /**
+     * Canvas-eligibility (EC-191). `false` marks a server-only / RSC component that
+     * is NOT client-renderable, so it may not appear in an editor composition (the
+     * canvas is client-rendered). Omitted/true = canvas-eligible. Only enforced when
+     * `requireCanvasEligible` is set (i.e. validating a composition value, not a
+     * dev-authored page/layout frame).
+     */
+    clientRenderable?: boolean;
+}
+export interface ComponentLookup {
+    has(componentId: string): boolean;
+    get(componentId: string): ManifestView | undefined;
+}
+export interface ValidateOptions {
+    /** When provided, component existence + prop/slot rules are checked. */
+    components?: ComponentLookup;
+    /** When provided, bindings are checked against the set of known data-source ids. */
+    knownSourceIds?: ReadonlySet<string>;
+    /**
+     * Require every node to be canvas-eligible (EC-191): a server-only component
+     * (`clientRenderable === false`) is a `server-only-component` error. Set by
+     * `validateCompositionValue` (editor compositions are client-rendered); off for
+     * `validateProjectGraph` (dev frames may render RSC components).
+     */
+    requireCanvasEligible?: boolean;
+}
+/** Validate a project graph, returning structured issues (never throws on a parsed graph). */
+export declare function validateProjectGraph(graph: ProjectGraph, opts?: ValidateOptions): ValidationIssue[];
+/**
+ * Validate a single component-node tree (EC-186, AD-12) — a composition **field
+ * value**, not a whole graph. Reuses the exact node-tree walk
+ * {@link validateProjectGraph} uses (component/prop/slot/container/binding rules
+ * + slot `allow` placement), but applies none of the graph-level invariants
+ * (layout refs, route conflicts). Node ids are checked for duplicates within
+ * this tree only.
+ */
+export declare function validateComponentNode(node: ComponentNode, opts?: ValidateOptions): ValidationIssue[];
+export interface CompositionValidateOptions extends ValidateOptions {
+    /**
+     * The composition field's allowed vocabulary (EC-186): component ids permitted
+     * as TOP-LEVEL blocks of the value. Omit to allow any registered component;
+     * deeper nesting is governed by slot `allow`. A top-level node outside the set
+     * is a `forbidden-component` error.
+     */
+    allow?: readonly string[];
+}
+/**
+ * Validate a composition **field value** (EC-186, AD-12): one root node
+ * (`cardinality: 'one'`) or an ordered list (`'many'`). Each root is validated as
+ * a component-node tree; the field's `allow` restricts the top-level vocabulary;
+ * duplicate node ids are checked across the whole value. The registry + `allow`
+ * are code (the leash); the tree is data.
+ */
+export declare function validateCompositionValue(value: ComponentNode | readonly ComponentNode[], opts?: CompositionValidateOptions): ValidationIssue[];
+/** True if the graph has no error-severity issues. */
+export declare function isGraphValid(issues: ValidationIssue[]): boolean;