@moloodev/layout-sdk 0.0.0-stage → 0.2.0

package/src/catalog/resolve.ts

@@ -0,0 +1,195 @@
+import {
+  readContent,
+  valueValidator,
+  type Content,
+  type ComponentContract,
+  type ComponentDefinition,
+} from "../catalog-format";
+
+export type CatalogSource = { assetId: string; content: Content };
+type Provenance = {
+  definition: string;
+  overrides: string[];
+  defaults: Record<string, string>;
+  resources: Record<string, string>;
+  implementations: Record<string, string>;
+};
+type ResolvedComponent = ComponentDefinition & {
+  provenance: Provenance;
+};
+export type ResolvedCatalog = {
+  stack: string[];
+  components: Record<string, ResolvedComponent>;
+};
+
+type CatalogErrorCode =
+  | "invalid_catalog"
+  | "duplicate_catalog"
+  | "missing_dependency"
+  | "dependency_order"
+  | "dependency_cycle"
+  | "component_collision"
+  | "missing_override_target"
+  | "contract_mismatch"
+  | "invalid_default"
+  | "invalid_resource"
+  | "missing_resource"
+  | "unknown_component"
+  | "unsupported_target";
+
+export class CatalogError extends Error {
+  constructor(
+    readonly code: CatalogErrorCode,
+    readonly assetId: string,
+    readonly component?: string,
+    readonly field?: string,
+  ) {
+    super([code, assetId, component, field].filter(Boolean).join(": "));
+    this.name = "CatalogError";
+  }
+}
+
+/** Stable structural identity; runtime packages must match the complete contract. */
+export function contractIdentity(contract: ComponentContract): string {
+  function sort(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(sort);
+    if (value !== null && typeof value === "object")
+      return Object.fromEntries(
+        Object.entries(value)
+          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+          .map(([key, child]) => [key, sort(child)]),
+      );
+    return value;
+  }
+  return JSON.stringify(sort(contract));
+}
+
+/** Caller resolves/pins assets. Composition neither fetches nor silently expands the stack. */
+export function resolveCatalog(
+  stack: readonly CatalogSource[],
+): ResolvedCatalog {
+  const sources = new Map<string, CatalogSource>();
+  for (const source of stack) {
+    if (
+      !source.assetId.trim() ||
+      source.assetId.trim() !== source.assetId ||
+      !readContent(source.content)
+    )
+      throw new CatalogError("invalid_catalog", source.assetId);
+    if (sources.has(source.assetId))
+      throw new CatalogError("duplicate_catalog", source.assetId);
+    sources.set(source.assetId, source);
+  }
+
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  function visit(id: string) {
+    if (visiting.has(id)) throw new CatalogError("dependency_cycle", id);
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dependency of sources.get(id)!.content.requires) {
+      if (!sources.has(dependency))
+        throw new CatalogError("missing_dependency", id, undefined, dependency);
+      visit(dependency);
+    }
+    visiting.delete(id);
+    visited.add(id);
+  }
+  stack.forEach(({ assetId }) => visit(assetId));
+
+  const components: Record<string, ResolvedComponent> = Object.create(null);
+  const applied = new Set<string>();
+  for (const { assetId, content } of stack) {
+    for (const dependency of content.requires)
+      if (!applied.has(dependency))
+        throw new CatalogError(
+          "dependency_order",
+          assetId,
+          undefined,
+          dependency,
+        );
+    for (const original of content.entries) {
+      const entry = structuredClone(original);
+      if ("key" in entry) {
+        if (components[entry.key])
+          throw new CatalogError("component_collision", assetId, entry.key);
+        const origin = (values: object) =>
+          Object.fromEntries(Object.keys(values).map((key) => [key, assetId]));
+        components[entry.key] = {
+          ...entry,
+          provenance: {
+            definition: assetId,
+            overrides: [],
+            defaults: origin(entry.defaults),
+            resources: origin(entry.resources),
+            implementations: origin(entry.implementations),
+          },
+        };
+      } else {
+        const current = components[entry.overrides];
+        if (!current)
+          throw new CatalogError(
+            "missing_override_target",
+            assetId,
+            entry.overrides,
+          );
+        if (current.contract.version !== entry.requiresContract)
+          throw new CatalogError("contract_mismatch", assetId, entry.overrides);
+        // Replace entries, never recursively merge objects, arrays, or package references.
+        for (const field of [
+          "defaults",
+          "resources",
+          "implementations",
+        ] as const) {
+          Object.assign(current[field], entry[field]);
+          for (const key of Object.keys(entry[field] ?? {}))
+            current.provenance[field][key] = assetId;
+        }
+        current.provenance.overrides.push(assetId);
+      }
+      // Check every layer, so a later override cannot hide an invalid earlier value.
+      const key = "key" in entry ? entry.key : entry.overrides;
+      const current = components[key]!;
+      for (const [name, value] of Object.entries(current.defaults)) {
+        const schema = current.contract.props.properties[name];
+        if (!schema || !valueValidator(schema).safeParse(value).success)
+          throw new CatalogError("invalid_default", assetId, key, name);
+      }
+      for (const [slot, resource] of Object.entries(current.resources)) {
+        if (current.contract.resources[slot]?.assetType !== resource.assetType)
+          throw new CatalogError("invalid_resource", assetId, key, slot);
+      }
+    }
+    applied.add(assetId);
+  }
+  for (const component of Object.values(components)) {
+    for (const slot of Object.keys(component.contract.resources))
+      if (!component.resources[slot])
+        throw new CatalogError(
+          "missing_resource",
+          component.provenance.definition,
+          component.key,
+          slot,
+        );
+  }
+  return { stack: stack.map(({ assetId }) => assetId), components };
+}
+
+/** Only components used by a surface need an implementation for that surface's target. */
+export function requireTarget(
+  catalog: ResolvedCatalog,
+  keys: readonly string[],
+  target: string,
+): void {
+  for (const key of keys) {
+    const component = catalog.components[key];
+    if (!component) throw new CatalogError("unknown_component", "", key);
+    if (!Object.hasOwn(component.implementations, target))
+      throw new CatalogError(
+        "unsupported_target",
+        component.provenance.definition,
+        key,
+        target,
+      );
+  }
+}

package/src/catalog/validate.ts

@@ -0,0 +1,146 @@
+import { validateSpec, type Spec } from "@json-render/core";
+import { valueValidator } from "../catalog-format";
+import { assertContent, type Content } from "../layout-format";
+import { z } from "zod";
+import { requireTarget, type ResolvedCatalog } from "./resolve";
+
+export class SpecError extends Error {
+  constructor(
+    readonly code: string,
+    readonly element?: string,
+    readonly field?: string,
+  ) {
+    super([code, element, field].filter(Boolean).join(": "));
+    this.name = "SpecError";
+  }
+}
+
+const specShape = z
+  .object({
+    root: z.string().min(1),
+    elements: z.record(
+      z.string(),
+      z
+        .object({
+          type: z.string(),
+          props: z.record(z.string(), z.unknown()),
+          children: z.array(z.string()).optional(),
+          slots: z.record(z.string(), z.array(z.string())).optional(),
+          on: z.record(z.string(), z.unknown()).optional(),
+        })
+        .passthrough(),
+    ),
+  })
+  .passthrough();
+
+function dynamic(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(dynamic);
+  return Object.entries(value).some(
+    ([key, child]) => key.startsWith("$") || dynamic(child),
+  );
+}
+
+/** Renderer-independent validation. Defaults apply to a clone, never the saved spec. */
+export function prepareSpec(
+  catalog: ResolvedCatalog,
+  target: string,
+  input: Spec,
+): Spec {
+  if (!specShape.safeParse(input).success) throw new SpecError("invalid_spec");
+  const spec = structuredClone(input);
+  const seen = new Set<string>();
+  const active = new Set<string>();
+  const used = new Set<string>();
+
+  function walk(id: string) {
+    if (active.has(id)) throw new SpecError("element_cycle", id);
+    if (seen.has(id)) throw new SpecError("multiple_parents", id);
+    const element = Object.hasOwn(spec.elements, id)
+      ? spec.elements[id]
+      : undefined;
+    if (!element) throw new SpecError("missing_element", id);
+    const definition = catalog.components[element.type];
+    if (!definition) throw new SpecError("unknown_component", id, element.type);
+    used.add(element.type);
+    active.add(id);
+    seen.add(id);
+    element.props = { ...definition.defaults, ...element.props };
+    for (const key of definition.contract.props.required)
+      if (!Object.hasOwn(element.props, key))
+        throw new SpecError("missing_prop", id, key);
+    for (const [key, value] of Object.entries(element.props)) {
+      const property = Object.hasOwn(definition.contract.props.properties, key)
+        ? definition.contract.props.properties[key]
+        : undefined;
+      if (
+        !property ||
+        (!dynamic(value) && !valueValidator(property).safeParse(value).success)
+      )
+        throw new SpecError("invalid_prop", id, key);
+    }
+    for (const event of Object.keys(element.on ?? {}))
+      if (!definition.contract.events.includes(event))
+        throw new SpecError("unknown_event", id, event);
+    if (element.slots && Object.hasOwn(element.slots, "default"))
+      throw new SpecError("invalid_default_slot", id);
+    const slots = {
+      ...element.slots,
+      ...(element.children?.length ? { default: element.children } : {}),
+    };
+    for (const [slot, children] of Object.entries(slots)) {
+      const rule = Object.hasOwn(definition.contract.slots, slot)
+        ? definition.contract.slots[slot]
+        : undefined;
+      if (!rule) throw new SpecError("unknown_slot", id, slot);
+      for (const child of children) {
+        if (
+          rule.accepts.length &&
+          !rule.accepts.includes(spec.elements[child]?.type ?? "")
+        )
+          throw new SpecError("invalid_slot_child", id, child);
+        walk(child);
+      }
+    }
+    active.delete(id);
+  }
+  walk(spec.root);
+  if (seen.size !== Object.keys(spec.elements).length)
+    throw new SpecError("unreachable_element");
+  const structural = validateSpec(spec);
+  if (!structural.valid)
+    throw new SpecError(
+      "invalid_spec",
+      structural.issues[0]?.elementKey,
+      structural.issues[0]?.code,
+    );
+  requireTarget(catalog, [...used], target);
+
+  return spec;
+}
+
+/** Validates the whole layout and returns prepared spec copies for runtime reuse.
+ * An editor can inject this into applyLayoutChange before committing a draft. */
+export function validateLayout(
+  content: Content,
+  catalog: ResolvedCatalog,
+): Record<string, Spec> {
+  assertContent(content);
+  if (JSON.stringify(content.catalogs) !== JSON.stringify(catalog.stack))
+    throw new SpecError("catalog_stack_mismatch");
+  const specs: Record<string, Spec> = Object.create(null);
+  for (const [surfaceId, surface] of Object.entries(content.surfaces)) {
+    specs[surfaceId] = prepareSpec(catalog, surface.target, surface.spec);
+    for (const [elementId, slots] of Object.entries(surface.mounts)) {
+      const element = surface.spec.elements[elementId]!;
+      const contract = catalog.components[element.type]!.contract;
+      for (const [slot, mountedId] of Object.entries(slots)) {
+        const rule = contract.surfaceSlots?.[slot];
+        if (!rule) throw new SpecError("unknown_surface_slot", elementId, slot);
+        if (content.surfaces[mountedId]!.target !== rule.target)
+          throw new SpecError("surface_target_mismatch", surfaceId, slot);
+      }
+    }
+  }
+  return specs;
+}

package/src/catalog-format/contract.ts

@@ -0,0 +1,131 @@
+import {
+  CATALOG_SCHEMA_VERSION,
+  contentSchema,
+  type Content,
+} from "./schema";
+import { valueValidator } from "./value-schema";
+
+export function blankContent(): Content {
+  return { version: CATALOG_SCHEMA_VERSION, requires: [], entries: [] };
+}
+
+export const catalogFormat = {
+  currentSchemaVersion: CATALOG_SCHEMA_VERSION,
+  inspect(input: unknown) {
+    const issues: { severity: "error"; code: string; path: (string | number)[] }[] = [];
+    const references: { assetId: string; assetType: string; path: (string | number)[] }[] = [];
+    const rawVersion =
+      input && typeof input === "object" && "version" in input
+        ? input.version
+        : null;
+    const schemaVersion =
+      typeof rawVersion === "number" &&
+      Number.isSafeInteger(rawVersion) &&
+      rawVersion > 0
+        ? rawVersion
+        : null;
+    if (schemaVersion !== CATALOG_SCHEMA_VERSION) {
+      return {
+        schemaVersion,
+        references,
+        issues: [
+          {
+            severity: "error" as const,
+            code:
+              schemaVersion === null
+                ? "invalid_document"
+                : "unsupported_schema",
+            path: ["version"],
+          },
+        ],
+      };
+    }
+    const parsed = contentSchema.safeParse(input);
+    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 = parsed.data;
+    const error = (code: string, path: (string | number)[]) =>
+      issues.push({ severity: "error", code, path });
+    const dependencies = new Set<string>();
+    content.requires.forEach((assetId, index) => {
+      if (dependencies.has(assetId))
+        error("duplicate_dependency", ["requires", index]);
+      dependencies.add(assetId);
+      references.push({
+        assetId,
+        assetType: "moloo.catalog",
+        path: ["requires", index],
+      });
+    });
+    const keys = new Set<string>();
+    content.entries.forEach((entry, index) => {
+      const key = "key" in entry ? entry.key : entry.overrides;
+      if (keys.has(key)) error("duplicate_component", ["entries", index]);
+      keys.add(key);
+      for (const [slot, resource] of Object.entries(entry.resources ?? {}))
+        references.push({
+          ...resource,
+          path: ["entries", index, "resources", slot],
+        });
+      if (!("key" in entry)) return;
+      for (const [target, axes] of Object.entries(entry.editor.resize ?? {})) {
+        const path = ["entries", index, "editor", "resize", target];
+        if (!entry.implementations[target])
+          error("invalid_resize_target", path);
+        for (const [axis, prop] of Object.entries(axes)) {
+          const schema = entry.contract.props.properties[prop];
+          if (
+            !schema ||
+            (schema.type !== "number" && schema.type !== "integer") ||
+            (schema.minimum !== undefined && schema.minimum < 0) ||
+            (schema.maximum !== undefined && schema.maximum <= 0)
+          )
+            error("invalid_resize_property", [...path, axis]);
+        }
+      }
+      for (const [target, transform] of Object.entries(
+        entry.editor.transform ?? {},
+      )) {
+        const path = ["entries", index, "editor", "transform", target];
+        if (!entry.implementations[target])
+          error("invalid_transform_target", path);
+        for (const [operation, axes] of Object.entries(transform)) {
+          for (const [axis, prop] of Object.entries(axes ?? {})) {
+            const schema = entry.contract.props.properties[prop];
+            if (
+              !schema ||
+              (schema.type !== "number" && schema.type !== "integer")
+            )
+              error("invalid_transform_property", [...path, operation, axis]);
+          }
+        }
+      }
+      for (const [name, value] of Object.entries(entry.defaults)) {
+        const schema = entry.contract.props.properties[name];
+        if (!schema || !valueValidator(schema).safeParse(value).success)
+          error("invalid_default", ["entries", index, "defaults", name]);
+      }
+      for (const [slot, resource] of Object.entries(entry.resources)) {
+        if (entry.contract.resources[slot]?.assetType !== resource.assetType)
+          error("invalid_resource", ["entries", index, "resources", slot]);
+      }
+    });
+    return { schemaVersion, issues, references };
+  },
+};
+
+export function readContent(input: unknown): Content | null {
+  if (catalogFormat.inspect(input).issues.length) return null;
+  return input as Content;
+}

package/src/catalog-format/fixtures.ts

@@ -0,0 +1,148 @@
+import type {
+  ComponentContract,
+  ComponentDefinition,
+  Content,
+  ImplementationReference,
+} from "./schema";
+
+/** Portable examples; resource IDs are supplied by callers, never installed into workspaces. */
+export const tileContract: ComponentContract = {
+  version: 1,
+  props: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      color: { type: "string" },
+      label: { type: "string", minLength: 1 },
+      selected: { type: "boolean" },
+      size: { type: "number", minimum: 0.01 },
+    },
+    required: ["color", "selected", "size"],
+  },
+  slots: {},
+  events: ["press"],
+  resources: { face: { assetType: "moloo.image" } },
+};
+
+export const buildingContract: ComponentContract = {
+  version: 1,
+  props: {
+    type: "object",
+    properties: { population: { type: "integer", minimum: 0 } },
+    required: ["population"],
+    additionalProperties: false,
+  },
+  slots: {},
+  events: ["press"],
+  resources: { model: { assetType: "moloo.model" } },
+};
+
+export const groupContract: ComponentContract = {
+  version: 1,
+  props: {
+    type: "object",
+    properties: {},
+    required: [],
+    additionalProperties: false,
+  },
+  slots: { default: { accepts: [] } },
+  events: [],
+  resources: {},
+};
+
+export function exampleImplementation(entry: string): ImplementationReference {
+  return { package: "@moloodev/layout-examples", version: "1.0.0", entry, abi: 1 };
+}
+
+function definition(
+  key: string,
+  contract: ComponentContract,
+  implementations: ComponentDefinition["implementations"],
+  layout: ComponentDefinition["editor"]["layout"],
+): ComponentDefinition {
+  return {
+    key,
+    contract,
+    implementations,
+    defaults: {},
+    resources: {},
+    description: key,
+    editor: { category: key.split(".")[0]!, layout },
+  };
+}
+
+export function createExampleCatalogs(ids: {
+  puzzle: string;
+  tileImage: string;
+  winterImage: string;
+  buildingModel: string;
+}): { puzzle: Content; winter: Content; simulation: Content } {
+  const tile = definition(
+    "puzzle.Tile",
+    structuredClone(tileContract),
+    {
+      "react-dom": exampleImplementation("Tile"),
+      "react-three-fiber": exampleImplementation("Tile"),
+    },
+    { "react-dom": "leaf", "react-three-fiber": "leaf" },
+  );
+  tile.defaults = { label: "Tile", color: "#e57c46", selected: false, size: 1 };
+  tile.resources = {
+    face: { assetId: ids.tileImage, assetType: "moloo.image" },
+  };
+  const snowfall = definition(
+    "winter.Snowfall",
+    structuredClone(groupContract),
+    {
+      "react-three-fiber": exampleImplementation("Snowfall"),
+    },
+    { "react-three-fiber": "spatial" },
+  );
+  const building = definition(
+    "simulation.Building",
+    structuredClone(buildingContract),
+    { "react-three-fiber": exampleImplementation("Building") },
+    { "react-three-fiber": "spatial" },
+  );
+  building.defaults = { population: 0 };
+  building.resources = {
+    model: { assetId: ids.buildingModel, assetType: "moloo.model" },
+  };
+  return {
+    puzzle: {
+      version: 1,
+      requires: [],
+      entries: [
+        tile,
+        definition(
+          "dom.Stack",
+          structuredClone(groupContract),
+          { "react-dom": exampleImplementation("Stack") },
+          { "react-dom": "flow" },
+        ),
+        definition(
+          "scene.Group",
+          structuredClone(groupContract),
+          { "react-three-fiber": exampleImplementation("Group") },
+          { "react-three-fiber": "spatial" },
+        ),
+      ],
+    },
+    winter: {
+      version: 1,
+      requires: [ids.puzzle],
+      entries: [
+        {
+          overrides: "puzzle.Tile",
+          requiresContract: 1,
+          defaults: { color: "#b8e6ff" },
+          resources: {
+            face: { assetId: ids.winterImage, assetType: "moloo.image" },
+          },
+        },
+        snowfall,
+      ],
+    },
+    simulation: { version: 1, requires: [], entries: [building] },
+  };
+}

package/src/catalog-format/index.ts

@@ -0,0 +1,10 @@
+export { catalogFormat, readContent } from "./contract";
+
+export type {
+  Content,
+  ComponentContract,
+  ComponentDefinition,
+  ResourceReference,
+} from "./schema";
+export { valueValidator } from "./value-schema";
+export type { ValueSchema, ObjectSchema } from "./value-schema";