@moloodev/layout-sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# Layout runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runtime foundation for the layout editor. This package does not mount an editor,
+fetch assets, install packages, or own persistence. See the
+[living spec](../../docs/superpowers/specs/2026-10-20-layout-catalog-runtime.md).
+
+```tsx
+import { createStateStore } from "@json-render/core";
+import { createExampleCatalogs } from "@moloodev/layout-sdk/catalog-format/fixtures";
+import { resolveCatalog } from "@moloodev/layout-sdk/catalog";
+import { Canvas } from "@react-three/fiber";
+import { prepareSurface } from "@moloodev/layout-sdk";
+import { examplePackages } from "@moloodev/layout-sdk/examples";
+import { DomSurface } from "@moloodev/layout-sdk/react";
+import { ThreeScene } from "@moloodev/layout-sdk/three";
+
+// Supply real workspace asset IDs. These examples do not create assets.
+const { puzzle, winter } = createExampleCatalogs({
+  puzzle: puzzleCatalogId,
+  tileImage: tileImageId,
+  winterImage: winterImageId,
+  buildingModel: buildingModelId,
+});
+const catalog = resolveCatalog([
+  { assetId: puzzleCatalogId, content: puzzle },
+  { assetId: winterCatalogId, content: winter },
+]);
+const spec = {
+  root: "tile",
+  elements: {
+    tile: {
+      type: "puzzle.Tile",
+      props: { label: "Snowflake tile", selected: { $state: "/selected" } },
+      on: { press: { action: "select" } },
+    },
+  },
+};
+// Resolve image/model URLs through the application's existing asset access.
+const prepare = (target: string) =>
+  prepareSurface({
+    catalog,
+    target,
+    spec,
+    packages: examplePackages,
+    resolveResource,
+  });
+const hud = prepare("react-dom");
+const scene = prepare("react-three-fiber");
+const store = createStateStore({ selected: false });
+const handlers = { select: () => store.set("/selected", true) };
+
+<div>
+  <DomSurface surface={hud} handlers={handlers} store={store} />
+  <Canvas>
+    <ThreeScene surface={scene} handlers={handlers} store={store} />
+  </Canvas>
+</div>
+```
+
+Use `./react` for a DOM host and `./three` for a scene under an existing R3F
+root. `./examples` registers the sample DOM and R3F implementations. Catalog assembly
+and server-side reference inspection do not need React or Three.
+
+Run `pnpm --filter @moloodev/layout-sdk/catalog-format test`,
+`pnpm --filter @moloodev/layout-sdk/catalog test`, and
+`pnpm --filter @moloodev/layout-sdk test` from the repository root.
+UI verification belongs to the human; these are unit tests, not browser tests.
+
+`prepareLayout` reads the saved layout's explicit catalog stack and prepares all
+surfaces, reusing the prepared spec copies returned by `validateLayout` rather
+than repeating per-surface validation. `composeSurfaces(prepared, boundary)` makes
+per-element runtime registry entries and supplies mounted children through `RuntimeComponentProps.surfaces`.
+The injected boundary callback owns renderer transitions. The host supplies the
+Canvas for a DOM → R3F mount and renders `ThreeScene` for an R3F → R3F mount.
+Saved component keys, props and native children are
+unchanged. Unsupported transitions must fail explicitly.
+
+An optional third argument to `composeSurfaces` is an `ElementObserver` component.
+It receives `{ identity: { surface, element, type, target }, render(rootRef) }`.
+Call `render(rootRef)` to observe the implementation's native root without adding
+a DOM wrapper or Three group. Implementations opt in by attaching the optional
+`RuntimeComponentProps.rootRef` to their primary DOM element or Object3D; all basic
+and example implementations do this. Forward the ref's null notification on
+unmount. The observer must tolerate no root (suspense/visibility) and multiple
+instances of the same spec element (repeat). The original component type, native
+children, named slots and mounted surface identities are preserved. This is a
+runtime-only observation contract; selection, highlighting and interaction modes
+belong to the editor's renderer adapters, not catalog JSON or saved props.
+
+Observers also receive `nativeSlots`, the component contract's native slot names
+(including `default`, even when empty). Surface mount slots are excluded.
+An observer can call `render(rootRef, slotRefs)`; only declared native names reach
+the implementation's optional `RuntimeComponentProps.slotRefs`. Existing observers
+that only pass `rootRef`, and renderers without an observer, keep working.
+
+Attach `slotRefs?.header` directly to the implementation's actual header container,
+and `slotRefs?.default` to its native children container. No wrapper is introduced.
+These are React 19 callback refs that may return a cleanup for each mounted root.
+If forwarding through another callback, return that cleanup; do not discard it.
+Each repeated instance has separate registrations. Multiple roots for one slot
+remain observable so consumers can reject ambiguous geometry. Slots are transient
+renderer observations, not element selection roots or persisted metadata.
+This optional observer extension changes neither catalog/layout schemas nor the
+implementation ABI or existing pinned package references.
+
+`@moloodev/layout-sdk/basic` exports `basicCatalog` and `basicPackages`.
+The catalog defines DOM Stack, Grid, Frame, Panel, Text, Button, and Viewport,
+plus R3F Group, Transform, and Box. It has no resource dependencies.
+Every DOM definition pins `@moloodev/layout-basic@1.3.0`.
+Every R3F definition pins `@moloodev/layout-basic@1.1.0`.
+`basicPackages` installs those two packages.
+Grid uses row auto-placement, 1 to 12 equal-width columns, and a configurable gap.
+Frame is a border-box column flex container with integer width (64–1600px) and
+height (64–1200px), defaulting to 320×240px. It declares `editor.resize["react-dom"]`
+property mappings. The runtime owns no resize gestures.
+Panel supplies header, default, and footer native slots with column flex containers
+and optional `slotRefs`, including empty regions with a 48px minimum height.
+Its gap property applies both between slots and within them, ranging from 0 to
+128px (default 16). Editor-only empty-slot hints are not part of Panel's output.
+Import the catalog JSON as a workspace `.mcat` asset and reference its actual asset
+ID. The runtime does not invent built-in asset IDs or install catalogs into workspaces.
+
+Example Tile labels are supplied through `props.label` (default: "Tile"). Set a
+meaningful label for each tile; the DOM implementation exposes it as its accessible
+name and shows selection with an inset shadow, leaving the browser's focus outline
+available for keyboard navigation. In forced colors, a double border marks selection
+using system colors. Both states reserve the same border width inside the tile's
+dimensions. React hoists and deduplicates the example's stylesheet; consumers do not
+need a separate CSS import. Interactive Three examples consume
+click propagation so occluded objects and parent handlers do not also activate.
+
+Catalog documents are schema version 1. Optional `editor.transform[target]`
+maps numeric props to local position, Euler XYZ rotation in radians, and
+unitless scale. Each operation maps one or more x/y/z axes. Properties must
+be distinct across operations for a target.
+Omitted axes remain unchanged. Implementations that opt in must apply these
+semantics to the observed root, including when a seasonal override supplies the
+values. Metadata stays owned by the original definition. A document whose
+version is not 1 is `unsupported_schema`. Exact implementation versions and ABI
+stay unchanged. This contract does not add transform gestures or infer support
+for existing Group/Box components.
+
+`basic.Transform` opts into the transform contract with `positionX/Y/Z`,
+`rotationX/Y/Z`, and `scaleX/Y/Z`. It renders an observed Three Group with a default
+child slot, local Euler XYZ rotation, and defaults of zero position/rotation and
+unit scale. Scale props have a minimum of 0.01; position and rotation accept any
+finite number. json-render state bindings update the group without changing the
+stored spec. Group and Box share `@moloodev/layout-basic@1.1.0` and do not declare
+`editor.transform`. The runtime adds no gesture controls.

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@moloodev/layout-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./format": "./src/layout-format/index.ts",
+    "./catalog": "./src/catalog/index.ts",
+    "./catalog-format": "./src/catalog-format/index.ts",
+    "./catalog-format/fixtures": "./src/catalog-format/fixtures.ts",
+    "./react": "./src/react.tsx",
+    "./three": "./src/three.tsx",
+    "./examples": "./src/examples/index.ts",
+    "./basic": "./src/basic.tsx"
+  },
+  "dependencies": {
+    "@json-render/core": "^0.20.0",
+    "@json-render/react": "^0.20.0",
+    "@react-three/fiber": "9.8.2",
+    "three": "0.186.1",
+    "zod": "^4.5.4",
+    "@moloodev/platform": "0.2.0",
+    "@moloodev/editor-sdk": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@react-three/test-renderer": "9.1.1",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "@types/three": "0.186.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "@moloodev/typescript-config": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test 'src/**/*.test.ts' 'src/**/*.test.tsx'"
+  }
 }

package/src/basic.tsx

@@ -0,0 +1,366 @@
+import type { CSSProperties } from "react";
+import type {
+  ComponentContract,
+  ComponentDefinition,
+  Content,
+  ObjectSchema,
+} from "./catalog-format";
+import type { ImplementationPackage, RuntimeComponentProps } from "./runtime";
+
+const props = (properties: ObjectSchema["properties"]): ObjectSchema => ({
+  type: "object",
+  properties,
+  required: Object.keys(properties),
+  additionalProperties: false,
+});
+const contract = (
+  properties: ObjectSchema["properties"],
+  slots = false,
+  events: string[] = [],
+): ComponentContract => ({
+  version: 1,
+  props: props(properties),
+  slots: slots ? { default: { accepts: [] } } : {},
+  events,
+  resources: {},
+});
+const contracts = {
+  Stack: contract(
+    {
+      direction: { type: "string", enum: ["row", "column"] },
+      gap: { type: "number", minimum: 0, maximum: 128 },
+    },
+    true,
+  ),
+  Grid: contract(
+    {
+      columns: { type: "integer", minimum: 1, maximum: 12 },
+      gap: { type: "number", minimum: 0, maximum: 128 },
+    },
+    true,
+  ),
+  Frame: contract(
+    {
+      width: { type: "integer", minimum: 64, maximum: 1600 },
+      height: { type: "integer", minimum: 64, maximum: 1200 },
+    },
+    true,
+  ),
+  Panel: {
+    ...contract({ gap: { type: "number", minimum: 0, maximum: 128 } }),
+    slots: {
+      header: { accepts: [] },
+      default: { accepts: [] },
+      footer: { accepts: [] },
+    },
+  },
+  Text: contract({
+    text: { type: "string" },
+    size: { type: "number", minimum: 8, maximum: 96 },
+  }),
+  Button: contract({ text: { type: "string" } }, false, ["press"]),
+  Viewport: {
+    ...contract({ height: { type: "number", minimum: 100, maximum: 1200 } }),
+    surfaceSlots: { scene: { target: "react-three-fiber" } },
+  },
+  Group: contract({}, true),
+  Transform: contract(
+    {
+      positionX: { type: "number" },
+      positionY: { type: "number" },
+      positionZ: { type: "number" },
+      rotationX: { type: "number" },
+      rotationY: { type: "number" },
+      rotationZ: { type: "number" },
+      scaleX: { type: "number", minimum: 0.01 },
+      scaleY: { type: "number", minimum: 0.01 },
+      scaleZ: { type: "number", minimum: 0.01 },
+    },
+    true,
+  ),
+  Box: contract(
+    {
+      color: { type: "string" },
+      size: { type: "number", minimum: 0.1, maximum: 10 },
+    },
+    false,
+    ["press"],
+  ),
+};
+const packageVersion = {
+  "react-dom": "1.3.0",
+  "react-three-fiber": "1.1.0",
+};
+function definition(
+  entry: keyof typeof contracts,
+  target: keyof typeof packageVersion,
+  defaults: ComponentDefinition["defaults"],
+  layout: "leaf" | "flow" | "grid" | "spatial",
+  editing?: Pick<ComponentDefinition["editor"], "resize" | "transform">,
+): ComponentDefinition {
+  return {
+    key: `basic.${entry}`,
+    contract: contracts[entry],
+    description: entry,
+    defaults,
+    resources: {},
+    implementations: {
+      [target]: {
+        package: "@moloodev/layout-basic",
+        version: packageVersion[target],
+        entry,
+        abi: 1,
+      },
+    },
+    editor: {
+      category: target === "react-dom" ? "화면" : "3D 장면",
+      layout: { [target]: layout },
+      ...editing,
+    },
+  };
+}
+
+/** Download/import as an ordinary workspace asset. No virtual catalog IDs or automatic installation. */
+export const basicCatalog: Content = {
+  version: 1,
+  requires: [],
+  entries: [
+    definition("Stack", "react-dom", { direction: "column", gap: 16 }, "flow"),
+    definition("Grid", "react-dom", { columns: 3, gap: 16 }, "grid"),
+    definition(
+      "Frame",
+      "react-dom",
+      { width: 320, height: 240 },
+      "flow",
+      { resize: { "react-dom": { width: "width", height: "height" } } },
+    ),
+    definition("Panel", "react-dom", { gap: 16 }, "flow"),
+    definition("Text", "react-dom", { text: "새 텍스트", size: 24 }, "leaf"),
+    definition("Button", "react-dom", { text: "버튼" }, "leaf"),
+    definition("Viewport", "react-dom", { height: 320 }, "leaf"),
+    definition("Group", "react-three-fiber", {}, "spatial"),
+    definition(
+      "Transform",
+      "react-three-fiber",
+      {
+        positionX: 0,
+        positionY: 0,
+        positionZ: 0,
+        rotationX: 0,
+        rotationY: 0,
+        rotationZ: 0,
+        scaleX: 1,
+        scaleY: 1,
+        scaleZ: 1,
+      },
+      "spatial",
+      {
+        transform: {
+          "react-three-fiber": {
+            position: { x: "positionX", y: "positionY", z: "positionZ" },
+            rotation: { x: "rotationX", y: "rotationY", z: "rotationZ" },
+            scale: { x: "scaleX", y: "scaleY", z: "scaleZ" },
+          },
+        },
+      },
+    ),
+    definition(
+      "Box",
+      "react-three-fiber",
+      { color: "#76a9fa", size: 1 },
+      "leaf",
+    ),
+  ],
+};
+
+function Stack({ element, children, rootRef }: RuntimeComponentProps) {
+  return (
+    <div
+      ref={rootRef}
+      style={{
+        display: "flex",
+        flexDirection: element.props.direction as "row" | "column",
+        gap: Number(element.props.gap),
+        padding: 16,
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+function Text({ element, rootRef }: RuntimeComponentProps) {
+  return (
+    <span ref={rootRef} style={{ fontSize: Number(element.props.size) }}>
+      {String(element.props.text)}
+    </span>
+  );
+}
+function Grid({ element, children, rootRef }: RuntimeComponentProps) {
+  return (
+    <div
+      ref={rootRef}
+      style={{
+        display: "grid",
+        gridTemplateColumns: `repeat(${Number(element.props.columns)}, minmax(0, 1fr))`,
+        gridAutoFlow: "row",
+        gap: Number(element.props.gap),
+        padding: 16,
+        minHeight: 80,
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+function Frame({ element, children, rootRef }: RuntimeComponentProps) {
+  return (
+    <div
+      ref={rootRef}
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: 16,
+        padding: 16,
+        boxSizing: "border-box",
+        flexShrink: 0,
+        width: Number(element.props.width),
+        height: Number(element.props.height),
+        overflow: "auto",
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+function Panel({
+  element,
+  children,
+  slots,
+  rootRef,
+  slotRefs,
+}: RuntimeComponentProps) {
+  const gap = Number(element.props.gap);
+  const style: CSSProperties = {
+    display: "flex",
+    flexDirection: "column",
+    gap,
+    minHeight: 48,
+    minWidth: 80,
+  };
+  return (
+    <section
+      ref={rootRef}
+      style={{ display: "flex", flexDirection: "column", gap, padding: 16 }}
+    >
+      <header ref={slotRefs?.header} style={style}>
+        {slots?.header}
+      </header>
+      <div ref={slotRefs?.default} style={style}>
+        {children}
+      </div>
+      <footer ref={slotRefs?.footer} style={style}>
+        {slots?.footer}
+      </footer>
+    </section>
+  );
+}
+function Button({ element, emit, rootRef }: RuntimeComponentProps) {
+  return (
+    <button
+      ref={rootRef}
+      type="button"
+      style={{
+        border: "1px solid currentColor",
+        padding: "8px 16px",
+        borderRadius: 6,
+      }}
+      onClick={() => emit("press")}
+    >
+      {String(element.props.text)}
+    </button>
+  );
+}
+function Viewport({ element, surfaces, rootRef }: RuntimeComponentProps) {
+  return (
+    <div
+      ref={rootRef}
+      style={{ height: Number(element.props.height), minWidth: 200 }}
+    >
+      {surfaces?.scene ?? <p>3D surface를 연결하세요.</p>}
+    </div>
+  );
+}
+function Group({ children, rootRef }: RuntimeComponentProps) {
+  return <group ref={rootRef}>{children}</group>;
+}
+function Transform({ element, children, rootRef }: RuntimeComponentProps) {
+  const value = element.props;
+  return (
+    <group
+      ref={rootRef}
+      position={[
+        Number(value.positionX),
+        Number(value.positionY),
+        Number(value.positionZ),
+      ]}
+      rotation={[
+        Number(value.rotationX),
+        Number(value.rotationY),
+        Number(value.rotationZ),
+        "XYZ",
+      ]}
+      scale={[Number(value.scaleX), Number(value.scaleY), Number(value.scaleZ)]}
+    >
+      {children}
+    </group>
+  );
+}
+function Box({ element, emit, rootRef }: RuntimeComponentProps) {
+  return (
+    <mesh
+      ref={rootRef}
+      onClick={(event) => {
+        event.stopPropagation();
+        emit("press");
+      }}
+    >
+      <boxGeometry
+        args={[
+          Number(element.props.size),
+          Number(element.props.size),
+          Number(element.props.size),
+        ]}
+      />
+      <meshBasicMaterial color={String(element.props.color)} />
+    </mesh>
+  );
+}
+
+export const basicPackages: ImplementationPackage[] = [
+  {
+    name: "@moloodev/layout-basic",
+    version: packageVersion["react-dom"],
+    abi: 1,
+    target: "react-dom",
+    entries: {
+      Stack: { contract: contracts.Stack, component: Stack },
+      Grid: { contract: contracts.Grid, component: Grid },
+      Frame: { contract: contracts.Frame, component: Frame },
+      Panel: { contract: contracts.Panel, component: Panel },
+      Text: { contract: contracts.Text, component: Text },
+      Button: { contract: contracts.Button, component: Button },
+      Viewport: { contract: contracts.Viewport, component: Viewport },
+    },
+  },
+  {
+    name: "@moloodev/layout-basic",
+    version: packageVersion["react-three-fiber"],
+    abi: 1,
+    target: "react-three-fiber",
+    entries: {
+      Group: { contract: contracts.Group, component: Group },
+      Transform: { contract: contracts.Transform, component: Transform },
+      Box: { contract: contracts.Box, component: Box },
+    },
+  },
+];

package/src/catalog/index.ts

@@ -0,0 +1,3 @@
+export { contractIdentity, resolveCatalog } from "./resolve";
+export type { CatalogSource, ResolvedCatalog } from "./resolve";
+export { prepareSpec, validateLayout, SpecError } from "./validate";