@moloodev/layout-sdk 0.0.0-stage → 0.1.0

package/src/catalog-format/schema.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import { fieldName, jsonValue, objectSchema } from "./value-schema";
+
+export const CATALOG_SCHEMA_VERSION = 1;
+const componentKey = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]*\.[A-Za-z][A-Za-z0-9]*$/);
+const targetId = z.string().regex(/^[a-z][a-z0-9-]*$/);
+const identifier = z
+  .string()
+  .min(1)
+  .refine((value) => value.trim() === value);
+const version = z.number().int().positive();
+
+const resourceSchema = z.strictObject({
+  assetId: identifier,
+  assetType: z.string().regex(/^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/),
+});
+
+const implementationSchema = z.strictObject({
+  package: z.string().regex(/^(?:@[a-z0-9-]+\/)?[a-z0-9][a-z0-9._-]*$/),
+  version: z
+    .string()
+    .regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/),
+  entry: fieldName,
+  abi: z.literal(1),
+});
+
+const contractSchema = z
+  .strictObject({
+    version,
+    props: objectSchema,
+    slots: z.record(
+      fieldName,
+      z.strictObject({
+        /** Empty accepts means any component supported by the current target. */
+        accepts: z.array(componentKey),
+      }),
+    ),
+    /** Explicit renderer boundaries; these are not native child slots. */
+    surfaceSlots: z
+      .record(fieldName, z.strictObject({ target: targetId }))
+      .optional(),
+    /** Named json-render events; payloads remain in state/action params. */
+    events: z.array(fieldName),
+    resources: z.record(
+      fieldName,
+      z.strictObject({ assetType: resourceSchema.shape.assetType }),
+    ),
+  })
+  .refine((value) => new Set(value.events).size === value.events.length, {
+    message: "Duplicate event",
+    path: ["events"],
+  });
+
+const patchFields = {
+  defaults: z.record(fieldName, jsonValue),
+  resources: z.record(fieldName, resourceSchema),
+  implementations: z.record(targetId, implementationSchema),
+};
+
+const transformAxes = z
+  .strictObject({
+    x: fieldName.optional(),
+    y: fieldName.optional(),
+    z: fieldName.optional(),
+  })
+  .refine((axes) => Boolean(axes.x || axes.y || axes.z), {
+    message: "At least one transform axis is required",
+  });
+
+const transformSchema = z
+  .strictObject({
+    position: transformAxes.optional(),
+    rotation: transformAxes.optional(),
+    scale: transformAxes.optional(),
+  })
+  .refine((value) => Boolean(value.position || value.rotation || value.scale), {
+    message: "At least one transform operation is required",
+  })
+  .refine(
+    (value) => {
+      const props = Object.values(value).flatMap((axes) =>
+        Object.values(axes ?? {}).filter((prop) => prop !== undefined),
+      );
+      return new Set(props).size === props.length;
+    },
+    {
+      message: "Transform axes must use distinct properties",
+    },
+  );
+
+const editorSchema = z.strictObject({
+  category: z.string(),
+  /** Per-target hints; canvas adapters interpret these, never component names. */
+  layout: z.record(targetId, z.enum(["leaf", "flow", "grid", "spatial"])),
+  /** Direct numeric props controlling root extents. DOM uses border-box CSS pixels. */
+  resize: z
+    .record(
+      targetId,
+      z
+        .strictObject({
+          width: fieldName.optional(),
+          height: fieldName.optional(),
+        })
+        .refine((axes) => Boolean(axes.width || axes.height), {
+          message: "At least one resize axis is required",
+        })
+        .refine((axes) => !axes.width || axes.width !== axes.height, {
+          message: "Resize axes must use distinct properties",
+        }),
+    )
+    .optional(),
+  /** Local position, Euler XYZ rotation in radians, and unitless scale. */
+  transform: z.record(targetId, transformSchema).optional(),
+});
+
+const definitionSchema = z.strictObject({
+  key: componentKey,
+  contract: contractSchema,
+  description: z.string(),
+  ...patchFields,
+  editor: editorSchema,
+});
+
+const overrideSchema = z.strictObject({
+  overrides: componentKey,
+  requiresContract: version,
+  defaults: patchFields.defaults.optional(),
+  resources: patchFields.resources.optional(),
+  implementations: patchFields.implementations.optional(),
+});
+
+export const contentSchema = z.strictObject({
+  version: z.literal(CATALOG_SCHEMA_VERSION),
+  /** Dependencies must appear earlier in the explicit stack; no implicit expansion. */
+  requires: z.array(identifier),
+  entries: z.array(z.union([definitionSchema, overrideSchema])),
+});
+
+export type Content = z.infer<typeof contentSchema>;
+export type ComponentContract = z.infer<typeof contractSchema>;
+export type ComponentDefinition = z.infer<typeof definitionSchema>;
+
+export type ImplementationReference = z.infer<typeof implementationSchema>;
+export type ResourceReference = z.infer<typeof resourceSchema>;

package/src/catalog-format/value-schema.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+
+/** A closed JSON Schema subset. Unsupported keywords fail instead of being ignored. */
+export type ValueSchema =
+  | { type: "string"; enum?: string[]; minLength?: number; maxLength?: number }
+  | { type: "number" | "integer"; minimum?: number; maximum?: number }
+  | { type: "boolean" }
+  | { type: "null" }
+  | { type: "array"; items: ValueSchema; minItems?: number; maxItems?: number }
+  | ObjectSchema;
+
+export type ObjectSchema = {
+  type: "object";
+  properties: Record<string, ValueSchema>;
+  required: string[];
+  additionalProperties: false;
+};
+
+export const fieldName = z
+  .string()
+  .regex(/^[A-Za-z][A-Za-z0-9_-]*$/)
+  .refine(
+    (name) => name !== "prototype" && !Object.hasOwn(Object.prototype, name),
+  );
+const length = z.number().int().nonnegative();
+
+const valueSchema: z.ZodType<ValueSchema> = z.lazy(() =>
+  z
+    .union([
+      z.strictObject({
+        type: z.literal("string"),
+        enum: z.array(z.string()).min(1).optional(),
+        minLength: length.optional(),
+        maxLength: length.optional(),
+      }),
+      z.strictObject({
+        type: z.enum(["number", "integer"]),
+        minimum: z.number().optional(),
+        maximum: z.number().optional(),
+      }),
+      z.strictObject({ type: z.literal("boolean") }),
+      z.strictObject({ type: z.literal("null") }),
+      z.strictObject({
+        type: z.literal("array"),
+        items: valueSchema,
+        minItems: length.optional(),
+        maxItems: length.optional(),
+      }),
+      objectSchema,
+    ])
+    .superRefine((value, context) => {
+      const pairs = [
+        ["minLength", "maxLength"],
+        ["minItems", "maxItems"],
+        ["minimum", "maximum"],
+      ] as const;
+      const bounds = value as Record<string, unknown>;
+      for (const [min, max] of pairs) {
+        if (
+          typeof bounds[min] === "number" &&
+          typeof bounds[max] === "number" &&
+          bounds[min] > bounds[max]
+        )
+          context.addIssue({
+            code: "custom",
+            message: "Invalid bounds",
+            path: [max],
+          });
+      }
+    }),
+);
+
+export const objectSchema: z.ZodType<ObjectSchema> = z.lazy(() =>
+  z
+    .strictObject({
+      type: z.literal("object"),
+      properties: z.record(fieldName, valueSchema),
+      required: z.array(fieldName),
+      additionalProperties: z.literal(false),
+    })
+    .superRefine((value, context) => {
+      if (
+        new Set(value.required).size !== value.required.length ||
+        value.required.some((key) => !Object.hasOwn(value.properties, key))
+      )
+        context.addIssue({
+          code: "custom",
+          message: "Required fields must be unique declared properties",
+          path: ["required"],
+        });
+    }),
+);
+
+/** Only call with a schema accepted by valueSchema/objectSchema. No refs or code. */
+export function valueValidator(schema: ValueSchema): z.ZodType {
+  return z.fromJSONSchema(schema);
+}
+
+type Json =
+  null | boolean | number | string | Json[] | { [key: string]: Json };
+export const jsonValue: z.ZodType<Json> = z.lazy(() =>
+  z.union([
+    z.null(),
+    z.boolean(),
+    z.number(),
+    z.string(),
+    z.array(jsonValue),
+    z.record(z.string(), jsonValue),
+  ]),
+);

package/src/compose.tsx

@@ -0,0 +1,78 @@
+import { createElement, type ComponentType, type ReactNode } from "react";
+import type { ComponentRenderProps } from "@json-render/react";
+import type { PreparedLayout } from "./layout";
+import type { PreparedSurface, RuntimeComponentProps } from "./runtime";
+
+export type ElementIdentity = {
+  surface: string;
+  element: string;
+  type: string;
+  target: string;
+};
+export type ElementObserverProps = {
+  identity: ElementIdentity;
+  nativeSlots: readonly string[];
+  render(
+    rootRef: NonNullable<RuntimeComponentProps["rootRef"]>,
+    slotRefs?: RuntimeComponentProps["slotRefs"],
+  ): ReactNode;
+};
+
+/** Per-element registry entries keep mount identity out of saved props and native children. */
+export function composeSurfaces(
+  layout: PreparedLayout,
+  boundary: (surfaceId: string, parentTarget: string) => ReactNode,
+  Observer?: ComponentType<ElementObserverProps>,
+): Record<string, PreparedSurface> {
+  return Object.fromEntries(
+    Object.entries(layout.surfaces).map(([id, surface]) => {
+      const spec = structuredClone(surface.spec);
+      const registry: PreparedSurface["registry"] = Object.create(null);
+      for (const [elementId, element] of Object.entries(spec.elements)) {
+        const type = element.type;
+        const Component = surface.registry[type]!;
+        const identity = {
+          surface: id,
+          element: elementId,
+          type,
+          target: surface.target,
+        };
+        const nativeSlots = Object.freeze(
+          Object.keys(layout.catalog.components[type]!.contract.slots),
+        );
+        // The alias exists only in the prepared copy; it is not a component contract key.
+        element.type = elementId;
+        registry[elementId] = (props: ComponentRenderProps) => {
+          const surfaces = Object.fromEntries(
+            Object.entries(surface.mounts[elementId] ?? {}).map(
+              ([slot, child]) => [slot, boundary(child, surface.target)],
+            ),
+          );
+          const render = (
+            rootRef?: RuntimeComponentProps["rootRef"],
+            slotRefs?: RuntimeComponentProps["slotRefs"],
+          ) =>
+            createElement(Component, {
+              ...props,
+              element: { ...props.element, type },
+              surfaces,
+              rootRef,
+              slotRefs:
+                slotRefs &&
+                Object.fromEntries(
+                  nativeSlots.flatMap((slot) =>
+                    Object.hasOwn(slotRefs, slot)
+                      ? [[slot, slotRefs[slot]]]
+                      : [],
+                  ),
+                ),
+            } as RuntimeComponentProps);
+          return Observer
+            ? createElement(Observer, { identity, nativeSlots, render })
+            : render();
+        };
+      }
+      return [id, { target: surface.target, spec, registry }];
+    }),
+  );
+}

package/src/examples/components.tsx

@@ -0,0 +1,156 @@
+import { Suspense, useMemo } from "react";
+import { useLoader, type ThreeEvent } from "@react-three/fiber";
+import { TextureLoader } from "three";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import type { RuntimeComponentProps } from "../runtime";
+
+const tileStyles = `
+.moloo-layout-example-tile {
+  box-sizing: border-box;
+  border: 3px solid transparent;
+}
+@media (forced-colors: active) {
+  .moloo-layout-example-tile { border-color: ButtonText; }
+  .moloo-layout-example-tile[aria-pressed="true"] {
+    border-style: double;
+    border-color: Highlight;
+  }
+}
+`;
+
+export function DomTile({
+  element,
+  emit,
+  resources,
+  rootRef,
+}: RuntimeComponentProps) {
+  const { color, selected, size, label } = element.props as {
+    color: string;
+    label: string;
+    selected: boolean;
+    size: number;
+  };
+  return (
+    <>
+      <style
+        href="moloo-layout-example-tile"
+        precedence="moloo-layout-examples"
+      >
+        {tileStyles}
+      </style>
+      <button
+        ref={rootRef}
+        className="moloo-layout-example-tile"
+        type="button"
+        aria-label={label}
+        aria-pressed={selected}
+        style={{
+          width: size * 48,
+          height: size * 48,
+          backgroundColor: color,
+          backgroundImage: `url("${resources.face!.url}")`,
+          backgroundSize: "cover",
+          boxShadow: selected ? "inset 0 0 0 3px currentColor" : undefined,
+        }}
+        onClick={() => emit("press")}
+      />
+    </>
+  );
+}
+
+export function WinterDomTile({ rootRef, ...props }: RuntimeComponentProps) {
+  return (
+    <span ref={rootRef} data-season="winter">
+      <DomTile {...props} />
+    </span>
+  );
+}
+
+export function DomStack({ children, rootRef }: RuntimeComponentProps) {
+  return (
+    <div
+      ref={rootRef}
+      style={{ display: "flex", flexDirection: "column", gap: 8 }}
+    >
+      {children}
+    </div>
+  );
+}
+
+function TexturedTile({
+  element,
+  emit,
+  resources,
+  rootRef,
+}: RuntimeComponentProps) {
+  const texture = useLoader(TextureLoader, resources.face!.url);
+  const { color, selected, size } = element.props as {
+    color: string;
+    selected: boolean;
+    size: number;
+  };
+  return (
+    <mesh
+      ref={rootRef}
+      name="puzzle.Tile"
+      scale={size}
+      onClick={(event) => {
+        event.stopPropagation();
+        emit("press");
+      }}
+    >
+      <boxGeometry args={[1, 1, 0.15]} />
+      <meshBasicMaterial map={texture} color={color} wireframe={selected} />
+    </mesh>
+  );
+}
+
+export function ThreeTile(props: RuntimeComponentProps) {
+  return (
+    <Suspense fallback={null}>
+      <TexturedTile {...props} />
+    </Suspense>
+  );
+}
+
+export function ThreeGroup({ children, rootRef }: RuntimeComponentProps) {
+  return <group ref={rootRef}>{children}</group>;
+}
+
+export function Snowfall({ children, rootRef }: RuntimeComponentProps) {
+  return (
+    <group ref={rootRef} name="winter.Snowfall">
+      {[-1, 0, 1].map((x) => (
+        <mesh key={x} position={[x, 1.5, 0]}>
+          <sphereGeometry args={[0.05, 8, 8]} />
+          <meshBasicMaterial color="white" />
+        </mesh>
+      ))}
+      {children}
+    </group>
+  );
+}
+
+function LoadedBuilding({ emit, resources, rootRef }: RuntimeComponentProps) {
+  const model = useLoader(GLTFLoader, resources.model!.url);
+  // Instances must not share Object3D parentage. Loaded geometry/materials remain cached.
+  const instance = useMemo(() => model.scene.clone(true), [model.scene]);
+  return (
+    <primitive
+      ref={rootRef}
+      object={instance}
+      onClick={(event: ThreeEvent<MouseEvent>) => {
+        event.stopPropagation();
+        emit("press");
+      }}
+    />
+  );
+}
+
+export function Building(props: RuntimeComponentProps) {
+  return (
+    <Suspense fallback={null}>
+      <LoadedBuilding {...props} />
+    </Suspense>
+  );
+}

package/src/examples/index.ts

@@ -0,0 +1 @@
+export { examplePackages } from "./packages";

package/src/examples/packages.ts

@@ -0,0 +1,42 @@
+import {
+  buildingContract,
+  groupContract,
+  tileContract,
+} from "../catalog-format/fixtures";
+import type { ImplementationPackage } from "../runtime";
+import {
+  Building,
+  DomStack,
+  DomTile,
+  Snowfall,
+  ThreeGroup,
+  ThreeTile,
+  WinterDomTile,
+} from "./components";
+
+/** Explicitly registered implementations. No evaluation, URL imports or package downloads. */
+export const examplePackages: readonly ImplementationPackage[] = [
+  {
+    name: "@moloodev/layout-examples",
+    version: "1.0.0",
+    abi: 1,
+    target: "react-dom",
+    entries: {
+      Tile: { contract: tileContract, component: DomTile },
+      WinterTile: { contract: tileContract, component: WinterDomTile },
+      Stack: { contract: groupContract, component: DomStack },
+    },
+  },
+  {
+    name: "@moloodev/layout-examples",
+    version: "1.0.0",
+    abi: 1,
+    target: "react-three-fiber",
+    entries: {
+      Tile: { contract: tileContract, component: ThreeTile },
+      Group: { contract: groupContract, component: ThreeGroup },
+      Snowfall: { contract: groupContract, component: Snowfall },
+      Building: { contract: buildingContract, component: Building },
+    },
+  },
+];

package/src/index.ts

@@ -0,0 +1,18 @@
+export { composeSurfaces } from "./compose";
+export type { ElementIdentity, ElementObserverProps } from "./compose";
+export { prepareLayout } from "./layout";
+export type { PreparedLayout } from "./layout";
+export type { PreparedSurface, RuntimeComponentProps, NativeSlotRefs } from "./runtime";
+export * from "./layout-format";
+export * from "./catalog";
+export {
+  catalogFormat,
+  readContent as readCatalogContent,
+  valueValidator,
+  type Content as CatalogContent,
+  type ComponentContract,
+  type ComponentDefinition,
+  type ResourceReference,
+  type ValueSchema,
+  type ObjectSchema,
+} from "./catalog-format";

package/src/layout-format/bind.ts

@@ -0,0 +1,88 @@
+import {
+  isArray,
+  isMap,
+  rootMap,
+  stopCapturing,
+  toShared,
+  transact,
+  type Doc,
+  type SharedMap,
+} from "@moloodev/editor-sdk/crdt";
+import { assertContent, blankContent } from "./contract";
+import type { Content } from "./schema";
+
+type RecordValue = Record<string, unknown>;
+const record = (value: unknown): value is RecordValue =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+const equal = (a: unknown, b: unknown) =>
+  JSON.stringify(a) === JSON.stringify(b);
+
+function patch(map: SharedMap, before: RecordValue, after: RecordValue): void {
+  for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    const previous = before[key];
+    const next = after[key];
+    if (equal(previous, next)) continue;
+    const shared = map.get(key);
+    if (!Object.hasOwn(after, key)) map.delete(key);
+    else if (record(previous) && record(next) && isMap(shared))
+      patch(shared, previous, next);
+    else if (
+      Array.isArray(previous) &&
+      Array.isArray(next) &&
+      isArray(shared)
+    ) {
+      // Preserve the common prefix/suffix and their Yjs identities, including remote insertions.
+      let start = 0;
+      while (
+        start < previous.length &&
+        start < next.length &&
+        equal(previous[start], next[start])
+      )
+        start++;
+      let end = 0;
+      while (
+        end < previous.length - start &&
+        end < next.length - start &&
+        equal(previous[previous.length - 1 - end], next[next.length - 1 - end])
+      )
+        end++;
+      const removed = previous.length - start - end;
+      if (removed) shared.delete(start, removed);
+      const inserted = next.slice(start, next.length - end);
+      if (inserted.length) shared.insert(start, inserted.map(toShared));
+    } else map.set(key, toShared(next));
+  }
+}
+
+export function projectLayout(doc: Doc): Content {
+  const raw = rootMap(doc).toJSON();
+  if (!Object.keys(raw).length) return blankContent();
+  assertContent(raw);
+  return raw;
+}
+
+/** One synchronous draft callback = one shared undo step. Validation precedes every write.
+ * The host owns createUndo; no additional document, observer, or undo manager is created here.
+ * Semantic validation is injected by ../catalog; format validation is unconditional.
+ */
+export function applyLayoutChange<T>(
+  doc: Doc,
+  change: (draft: Content) => T,
+  validate?: (content: Content) => void,
+): T {
+  const rawBefore = rootMap(doc).toJSON();
+  const before = projectLayout(doc);
+  const draft = structuredClone(before);
+  const result = change(draft);
+  if (result && typeof result === "object" && "then" in result)
+    throw new Error("Layout changes must be synchronous");
+  assertContent(draft);
+  validate?.(draft);
+  if (!equal(rawBefore, rootMap(doc).toJSON()))
+    throw new Error("Layout changed during draft computation");
+  if (equal(before, draft)) return result;
+  stopCapturing(doc);
+  transact(doc, () => patch(rootMap(doc), rootMap(doc).toJSON(), draft));
+  stopCapturing(doc);
+  return result;
+}