@moloodev/layout-sdk 0.0.0-stage → 0.1.0

package/src/layout-format/contract.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import { contentSchema, type Content, type Element } from "./schema";
+
+export function blankContent(): Content {
+  return { version: 1, catalogs: [], rootSurface: null, surfaces: {} };
+}
+
+export function childIds(element: Element): string[] {
+  return [
+    ...(element.children ?? []),
+    ...Object.values(element.slots ?? {}).flat(),
+  ];
+}
+
+export const layoutFormat = {
+  currentSchemaVersion: 1,
+  inspect(input: unknown) {
+    const rawVersion =
+      input && typeof input === "object" && "version" in input
+        ? input.version
+        : null;
+    const schemaVersion =
+      typeof rawVersion === "number" &&
+      Number.isSafeInteger(rawVersion) &&
+      rawVersion > 0
+        ? rawVersion
+        : null;
+    const issues: { severity: "error"; code: string; path: (string | number)[] }[] = [];
+    const error = (code: string, path: (string | number)[]) =>
+      issues.push({ severity: "error", code, path });
+    if (schemaVersion !== 1) {
+      error(
+        schemaVersion === null ? "invalid_document" : "unsupported_schema",
+        ["version"],
+      );
+      return { schemaVersion, issues, references: [] };
+    }
+    const json = z.json().safeParse(input);
+    const parsed = json.success ? contentSchema.safeParse(input) : json;
+    if (!parsed.success)
+      return {
+        schemaVersion,
+        references: [],
+        issues: parsed.error.issues.map((issue) => ({
+          severity: "error" as const,
+          code: "invalid_structure",
+          path: issue.path.filter(
+            (key): key is string | number => typeof key !== "symbol",
+          ),
+        })),
+      };
+    const content = input as Content;
+    const references = content.catalogs.map((assetId, index) => ({
+      assetId,
+      assetType: "moloo.catalog",
+      path: ["catalogs", index],
+    }));
+    if (new Set(content.catalogs).size !== content.catalogs.length)
+      error("duplicate_catalog", ["catalogs"]);
+    const allIds = new Set(Object.keys(content.surfaces));
+    for (const [surfaceId, surface] of Object.entries(content.surfaces)) {
+      const base = ["surfaces", surfaceId];
+      const elements = surface.spec.elements;
+      for (const id of Object.keys(elements)) {
+        if (allIds.has(id))
+          error("duplicate_id", [...base, "spec", "elements", id]);
+        allIds.add(id);
+      }
+      const seen = new Set<string>();
+      const active = new Set<string>();
+      const walk = (id: string): void => {
+        const path = [...base, "spec", "elements", id];
+        if (active.has(id)) {
+          error("element_cycle", path);
+          return;
+        }
+        if (seen.has(id)) {
+          error("multiple_parents", path);
+          return;
+        }
+        const element = elements[id];
+        if (!element) {
+          error("missing_element", path);
+          return;
+        }
+        seen.add(id);
+        active.add(id);
+        childIds(element).forEach(walk);
+        active.delete(id);
+      };
+      walk(surface.spec.root);
+      for (const id of Object.keys(elements))
+        if (!seen.has(id))
+          error("unreachable_element", [...base, "spec", "elements", id]);
+      for (const elementId of Object.keys(surface.mounts))
+        if (!elements[elementId])
+          error("missing_mount_element", [...base, "mounts", elementId]);
+    }
+    const seen = new Set<string>();
+    const active = new Set<string>();
+    const walkSurface = (id: string): void => {
+      const path = ["surfaces", id];
+      if (active.has(id)) {
+        error("surface_cycle", path);
+        return;
+      }
+      if (seen.has(id)) {
+        error("multiple_surface_parents", path);
+        return;
+      }
+      const surface = content.surfaces[id];
+      if (!surface) {
+        error("missing_surface", path);
+        return;
+      }
+      seen.add(id);
+      active.add(id);
+      for (const mounts of Object.values(surface.mounts))
+        Object.values(mounts).forEach(walkSurface);
+      active.delete(id);
+    };
+    if (content.rootSurface !== null) walkSurface(content.rootSurface);
+    for (const id of Object.keys(content.surfaces))
+      if (!seen.has(id)) error("unreachable_surface", ["surfaces", id]);
+    return { schemaVersion, issues, references };
+  },
+};
+
+export function readContent(input: unknown): Content | null {
+  return layoutFormat.inspect(input).issues.length ? null : (input as Content);
+}
+
+export class LayoutError extends Error {
+  constructor(
+    readonly code: string,
+    readonly path: readonly (string | number)[] = [],
+  ) {
+    super([code, ...path].join(": "));
+    this.name = "LayoutError";
+  }
+}
+
+export function assertContent(input: unknown): asserts input is Content {
+  const issue = layoutFormat.inspect(input).issues[0];
+  if (issue) throw new LayoutError(issue.code, issue.path);
+}

package/src/layout-format/edit.ts

@@ -0,0 +1,278 @@
+import { createId } from "@moloodev/platform";
+import { assertContent, childIds, LayoutError } from "./contract";
+import { slotName, type Content, type Element, type Surface } from "./schema";
+
+/** Index is measured after detaching a moved node. Omitted index appends. */
+export type Position = {
+  surface: string;
+  parent: string;
+  slot?: string;
+  index?: number;
+};
+export type Mount = { surface: string; element: string; slot: string };
+export type Fragment = { version: 1; content: Content };
+
+function surfaceAt(content: Content, id: string): Surface {
+  const surface = Object.hasOwn(content.surfaces, id)
+    ? content.surfaces[id]
+    : undefined;
+  if (!surface) throw new LayoutError("missing_surface", [id]);
+  return surface;
+}
+function elementAt(surface: Surface, id: string): Element {
+  const element = Object.hasOwn(surface.spec.elements, id)
+    ? surface.spec.elements[id]
+    : undefined;
+  if (!element) throw new LayoutError("missing_element", [id]);
+  return element;
+}
+function descendants(surface: Surface, root: string): string[] {
+  const ids: string[] = [];
+  const visit = (id: string) => {
+    ids.push(id);
+    childIds(elementAt(surface, id)).forEach(visit);
+  };
+  visit(root);
+  return ids;
+}
+function listAt(content: Content, position: Position): string[] {
+  const parent = elementAt(
+    surfaceAt(content, position.surface),
+    position.parent,
+  );
+  if (!position.slot || position.slot === "default")
+    return (parent.children ??= []);
+  if (!slotName.safeParse(position.slot).success)
+    throw new LayoutError("invalid_slot");
+  parent.slots ??= {};
+  return (parent.slots[position.slot] ??= []);
+}
+function attach(content: Content, position: Position, id: string): void {
+  const list = listAt(content, position);
+  const index = position.index ?? list.length;
+  if (!Number.isInteger(index) || index < 0 || index > list.length)
+    throw new LayoutError("invalid_index");
+  list.splice(index, 0, id);
+}
+function detach(surface: Surface, id: string): void {
+  for (const element of Object.values(surface.spec.elements)) {
+    for (const list of [
+      element.children ?? [],
+      ...Object.values(element.slots ?? {}),
+    ]) {
+      const index = list.indexOf(id);
+      if (index >= 0) {
+        list.splice(index, 1);
+        return;
+      }
+    }
+  }
+  throw new LayoutError("cannot_move_root", [id]);
+}
+
+/** Pure edits run against a draft owned by applyLayoutChange; commit validates the whole draft. */
+export function insertElement(
+  content: Content,
+  position: Position,
+  element: Element,
+): string {
+  if (childIds(element).length) throw new LayoutError("insert_requires_leaf");
+  const id = createId();
+  surfaceAt(content, position.surface).spec.elements[id] =
+    structuredClone(element);
+  attach(content, position, id);
+  return id;
+}
+
+export function addSurface(
+  content: Content,
+  target: string,
+  root: Element,
+  mount?: Mount,
+  label = "",
+): string {
+  if (childIds(root).length) throw new LayoutError("insert_requires_leaf");
+  const id = createId();
+  const rootId = createId();
+  if (mount) {
+    const host = surfaceAt(content, mount.surface);
+    elementAt(host, mount.element);
+    if (host.mounts[mount.element]?.[mount.slot])
+      throw new LayoutError("occupied_mount");
+    if (!slotName.safeParse(mount.slot).success)
+      throw new LayoutError("invalid_slot");
+    (host.mounts[mount.element] ??= {})[mount.slot] = id;
+  } else {
+    if (content.rootSurface !== null)
+      throw new LayoutError("root_surface_exists");
+    content.rootSurface = id;
+  }
+  content.surfaces[id] = {
+    target,
+    label,
+    spec: { root: rootId, elements: { [rootId]: structuredClone(root) } },
+    mounts: {},
+  };
+  return id;
+}
+
+export function moveElement(
+  content: Content,
+  surfaceId: string,
+  id: string,
+  position: Position,
+): void {
+  if (surfaceId !== position.surface)
+    throw new LayoutError("cross_surface_move");
+  const surface = surfaceAt(content, surfaceId);
+  if (descendants(surface, id).includes(position.parent))
+    throw new LayoutError("element_cycle", [id]);
+  detach(surface, id);
+  attach(content, position, id);
+}
+
+function removeSurface(content: Content, id: string): void {
+  const surface = surfaceAt(content, id);
+  for (const slots of Object.values(surface.mounts))
+    for (const child of Object.values(slots)) removeSurface(content, child);
+  for (const host of Object.values(content.surfaces))
+    for (const [element, slots] of Object.entries(host.mounts)) {
+      for (const [slot, child] of Object.entries(slots))
+        if (child === id) delete slots[slot];
+      if (!Object.keys(slots).length) delete host.mounts[element];
+    }
+  delete content.surfaces[id];
+  if (content.rootSurface === id) content.rootSurface = null;
+}
+
+export function removeElement(
+  content: Content,
+  surfaceId: string,
+  id: string,
+): void {
+  const surface = surfaceAt(content, surfaceId);
+  if (surface.spec.root === id) {
+    removeSurface(content, surfaceId);
+    return;
+  }
+  const ids = descendants(surface, id);
+  detach(surface, id);
+  for (const node of ids) {
+    for (const mounted of Object.values(surface.mounts[node] ?? {}))
+      removeSurface(content, mounted);
+    delete surface.mounts[node];
+    delete surface.spec.elements[node];
+  }
+}
+
+/** Snapshot only the subtree and its mounted surfaces. State paths and action params stay literal. */
+export function copyElement(
+  content: Content,
+  surfaceId: string,
+  id: string,
+): Fragment {
+  assertContent(content);
+  const source = surfaceAt(content, surfaceId);
+  const ids = new Set(descendants(source, id));
+  const surface = structuredClone(source);
+  surface.spec.root = id;
+  // A paste never implicitly replaces the destination's state or spec extensions.
+  surface.spec = {
+    root: id,
+    elements: Object.fromEntries(
+      Object.entries(surface.spec.elements).filter(([key]) => ids.has(key)),
+    ),
+  };
+  surface.mounts = Object.fromEntries(
+    Object.entries(surface.mounts).filter(([key]) => ids.has(key)),
+  );
+  const surfaces: Content["surfaces"] = { [surfaceId]: surface };
+  const copyMounts = (host: Surface) => {
+    for (const slots of Object.values(host.mounts))
+      for (const child of Object.values(slots)) {
+        surfaces[child] = structuredClone(content.surfaces[child]!);
+        copyMounts(surfaces[child]!);
+      }
+  };
+  copyMounts(surface);
+  return {
+    version: 1,
+    content: {
+      version: 1,
+      catalogs: [...content.catalogs],
+      rootSurface: surfaceId,
+      surfaces,
+    },
+  };
+}
+
+export function pasteElement(
+  content: Content,
+  position: Position,
+  fragment: Fragment,
+): { root: string; ids: Record<string, string> } {
+  if (fragment.version !== 1) throw new LayoutError("unsupported_clipboard");
+  assertContent(fragment.content);
+  const source = fragment.content;
+  if (source.rootSurface === null) throw new LayoutError("empty_clipboard");
+  const rootSurface = source.surfaces[source.rootSurface]!;
+  const destination = surfaceAt(content, position.surface);
+  if (destination.target !== rootSurface.target)
+    throw new LayoutError("clipboard_target_mismatch");
+  // Explicitly reject cross-stack migration until contracts can be mapped by the editor.
+  if (JSON.stringify(source.catalogs) !== JSON.stringify(content.catalogs))
+    throw new LayoutError("clipboard_catalog_mismatch");
+  const ids: Record<string, string> = {};
+  for (const [id, surface] of Object.entries(source.surfaces)) {
+    ids[id] = createId();
+    for (const node of Object.keys(surface.spec.elements))
+      ids[node] = createId();
+  }
+  const remap = (surface: Surface): Surface => {
+    const next = structuredClone(surface);
+    next.spec.root = ids[surface.spec.root]!;
+    next.spec.elements = Object.fromEntries(
+      Object.entries(next.spec.elements).map(([id, element]) => {
+        if (element.children)
+          element.children = element.children.map((child) => ids[child]!);
+        if (element.slots)
+          element.slots = Object.fromEntries(
+            Object.entries(element.slots).map(([slot, children]) => [
+              slot,
+              children.map((child) => ids[child]!),
+            ]),
+          );
+        return [ids[id]!, element];
+      }),
+    );
+    next.mounts = Object.fromEntries(
+      Object.entries(next.mounts).map(([id, slots]) => [
+        ids[id]!,
+        Object.fromEntries(
+          Object.entries(slots).map(([slot, child]) => [slot, ids[child]!]),
+        ),
+      ]),
+    );
+    return next;
+  };
+  for (const [id, surface] of Object.entries(source.surfaces)) {
+    const next = remap(surface);
+    if (id === source.rootSurface) {
+      Object.assign(destination.spec.elements, next.spec.elements);
+      Object.assign(destination.mounts, next.mounts);
+    } else content.surfaces[ids[id]!] = next;
+  }
+  const root = ids[rootSurface.spec.root]!;
+  attach(content, position, root);
+  ids[source.rootSurface] = position.surface;
+  return { root, ids };
+}
+
+export function duplicateElement(
+  content: Content,
+  surface: string,
+  id: string,
+  position: Position,
+) {
+  return pasteElement(content, position, copyElement(content, surface, id));
+}

package/src/layout-format/index.ts

@@ -0,0 +1,18 @@
+export type { Content, Element, Surface } from "./schema";
+export {
+  layoutFormat,
+  blankContent,
+  readContent,
+  assertContent,
+} from "./contract";
+export { projectLayout, applyLayoutChange } from "./bind";
+export {
+  addSurface,
+  insertElement,
+  removeElement,
+  moveElement,
+  copyElement,
+  pasteElement,
+  duplicateElement,
+} from "./edit";
+export type { Position, Mount, Fragment } from "./edit";

package/src/layout-format/schema.ts

@@ -0,0 +1,97 @@
+import {
+  ActionConfirmSchema,
+  ActionOnErrorSchema,
+  ActionOnSuccessSchema,
+  VisibilityConditionStrictSchema,
+  type Spec,
+  type UIElement,
+} from "@json-render/core";
+import { z } from "zod";
+
+const LAYOUT_SCHEMA_VERSION = 1;
+const idSchema = z.string().regex(/^[a-z0-9]{24}$/);
+export const slotName = z
+  .string()
+  .regex(/^[A-Za-z][A-Za-z0-9_-]*$/)
+  .refine(
+    (key) => key !== "prototype" && !Object.hasOwn(Object.prototype, key),
+  );
+const json = z.json();
+const action = z
+  .object({
+    action: z.string().min(1),
+    params: z.record(z.string(), json).optional(),
+    confirm: ActionConfirmSchema.optional(),
+    onSuccess: ActionOnSuccessSchema.optional(),
+    onError: ActionOnErrorSchema.optional(),
+    preventDefault: z.boolean().optional(),
+  })
+  .catchall(json);
+const actions = z.record(z.string().min(1), z.union([action, z.array(action)]));
+const elementSchema = z
+  .object({
+    type: z.string().regex(/^[a-z][a-z0-9-]*\.[A-Za-z][A-Za-z0-9]*$/),
+    props: z.record(z.string(), json),
+    children: z.array(idSchema).optional(),
+    slots: z
+      .record(
+        slotName.refine((key) => key !== "default"),
+        z.array(idSchema),
+      )
+      .optional(),
+    on: actions.optional(),
+    watch: actions.optional(),
+    visible: VisibilityConditionStrictSchema.optional(),
+    repeat: z
+      .strictObject({
+        statePath: z.union([z.string(), z.strictObject({ $item: z.string() })]),
+        key: z.string().optional(),
+      })
+      .optional(),
+    label: z.string().optional(),
+  })
+  .catchall(json);
+
+const surfaceSchema = z.strictObject({
+  target: z.string().regex(/^[a-z][a-z0-9-]*$/),
+  label: z.string(),
+  spec: z
+    .object({
+      root: idSchema,
+      elements: z.record(idSchema, elementSchema),
+      state: z.record(z.string(), json).optional(),
+    })
+    .catchall(json),
+  /** Native children stay within one renderer; boundaries use explicit mounts. */
+  mounts: z.record(idSchema, z.record(slotName, idSchema)),
+});
+export const contentSchema = z.strictObject({
+  version: z.literal(LAYOUT_SCHEMA_VERSION),
+  catalogs: z.array(
+    z
+      .string()
+      .min(1)
+      .refine((id) => id.trim() === id),
+  ),
+  rootSurface: idSchema.nullable(),
+  surfaces: z.record(idSchema, surfaceSchema),
+});
+
+/** Compatible json-render extensions are retained verbatim, including bindings and actions. */
+export type Element = UIElement & { label?: string; [key: string]: unknown };
+type LayoutSpec = Spec & {
+  elements: Record<string, Element>;
+  [key: string]: unknown;
+};
+export type Surface = {
+  target: string;
+  label: string;
+  spec: LayoutSpec;
+  mounts: Record<string, Record<string, string>>;
+};
+export type Content = {
+  version: 1;
+  catalogs: string[];
+  rootSurface: string | null;
+  surfaces: Record<string, Surface>;
+};

package/src/layout.ts

@@ -0,0 +1,74 @@
+import type { ResourceReference } from "./catalog-format";
+import {
+  resolveCatalog,
+  validateLayout,
+  type CatalogSource,
+  type ResolvedCatalog,
+} from "./catalog";
+import {
+  assertContent,
+  type Content,
+  type Surface,
+} from "./layout-format";
+import {
+  bindSurface,
+  RuntimeError,
+  type ImplementationPackage,
+  type PreparedSurface,
+} from "./runtime";
+
+export type PreparedLayout = {
+  catalog: ResolvedCatalog;
+  rootSurface: string | null;
+  surfaces: Record<string, PreparedSurface & { mounts: Surface["mounts"] }>;
+};
+
+/** Source documents are supplied by the host; the document's stack determines precedence.
+ * Mounts are explicit composition instructions for host boundary adapters, not native children.
+ */
+export function prepareLayout({
+  content,
+  catalogs,
+  packages,
+  resolveResource,
+}: {
+  content: Content;
+  catalogs: readonly CatalogSource[];
+  packages: readonly ImplementationPackage[];
+  resolveResource: (reference: ResourceReference) => string;
+}): PreparedLayout {
+  assertContent(content);
+  const sources = new Map<string, CatalogSource>();
+  for (const source of catalogs) {
+    if (sources.has(source.assetId))
+      throw new RuntimeError("duplicate_catalog_source", source.assetId);
+    sources.set(source.assetId, source);
+  }
+  const catalog = resolveCatalog(
+    content.catalogs.map((id) => {
+      const source = sources.get(id);
+      if (!source) throw new RuntimeError("missing_catalog_source", id);
+      return source;
+    }),
+  );
+  const specs = validateLayout(content, catalog);
+  return {
+    catalog,
+    rootSurface: content.rootSurface,
+    surfaces: Object.fromEntries(
+      Object.entries(content.surfaces).map(([id, surface]) => [
+        id,
+        {
+          ...bindSurface({
+            catalog,
+            target: surface.target,
+            spec: specs[id]!,
+            packages,
+            resolveResource,
+          }),
+          mounts: structuredClone(surface.mounts),
+        },
+      ]),
+    ),
+  };
+}

package/src/react.tsx

@@ -0,0 +1,34 @@
+import {
+  ActionProvider,
+  Renderer,
+  StateProvider,
+  VisibilityProvider,
+  type ActionProviderProps,
+} from "@json-render/react";
+import type { StateStore } from "@json-render/core";
+import { type PreparedSurface, RuntimeError } from "./runtime";
+
+export type SurfaceProps = {
+  surface: PreparedSurface;
+  handlers?: ActionProviderProps["handlers"];
+  store?: StateStore;
+};
+
+/** Host renderer must provide its own root (DOM or R3F Canvas). Providers create no DOM. */
+export function SurfaceContent({ surface, handlers, store }: SurfaceProps) {
+  return (
+    <StateProvider store={store} initialState={surface.spec.state ?? {}}>
+      <VisibilityProvider>
+        <ActionProvider handlers={handlers}>
+          <Renderer spec={surface.spec} registry={surface.registry} />
+        </ActionProvider>
+      </VisibilityProvider>
+    </StateProvider>
+  );
+}
+
+export function DomSurface(props: SurfaceProps) {
+  if (props.surface.target !== "react-dom")
+    throw new RuntimeError("wrong_surface_target");
+  return <SurfaceContent {...props} />;
+}

package/src/render-fixture.ts

@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import {
+  createExampleCatalogs,
+  exampleImplementation,
+} from "./catalog-format/fixtures";
+import { resolveCatalog } from "./catalog";
+import type { Spec } from "@json-render/core";
+import { prepareSurface } from "./runtime";
+import { examplePackages } from "./examples/packages";
+
+export function prepare(
+  target: string,
+  season = true,
+  implementationOverride = false,
+) {
+  const { puzzle, winter } = createExampleCatalogs({
+    puzzle: "puzzle",
+    tileImage: "tile",
+    winterImage: "winter",
+    buildingModel: "building",
+  });
+  if (implementationOverride) {
+    const override = winter.entries[0]!;
+    assert.ok("overrides" in override);
+    override.implementations = {
+      "react-dom": exampleImplementation("WinterTile"),
+    };
+  }
+  const catalog = resolveCatalog([
+    { assetId: "puzzle", content: puzzle },
+    ...(season ? [{ assetId: "winter", content: winter }] : []),
+  ]);
+  const spec: Spec = {
+    root: "tile",
+    state: { selected: true },
+    elements: {
+      tile: {
+        type: "puzzle.Tile",
+        props: { selected: { $state: "/selected" } },
+        on: { press: { action: "select" } },
+      },
+    },
+  };
+  return prepareSurface({
+    catalog,
+    target,
+    spec,
+    packages: examplePackages,
+    resolveResource: ({ assetId }) => `/assets/${assetId}.png`,
+  });
+}