@moloodev/layout-sdk 0.0.0-stage → 0.2.0

package/src/runtime.tsx

@@ -0,0 +1,165 @@
+import { createElement, type ComponentType, type ReactNode } from "react";
+import type { Spec } from "@json-render/core";
+import type {
+  ComponentRenderProps,
+  ComponentRegistry,
+} from "@json-render/react";
+import {
+  valueValidator,
+  type ComponentContract,
+  type ResourceReference,
+} from "./catalog-format";
+import {
+  contractIdentity,
+  prepareSpec,
+  SpecError,
+  type ResolvedCatalog,
+} from "./catalog";
+
+type ResolvedResource = { reference: ResourceReference; url: string };
+/** React 19 refs return a cleanup for each mounted slot root, including repeated instances. */
+export type NativeSlotRefs = Readonly<
+  Record<string, (root: unknown | null) => void | (() => void)>
+>;
+export type RuntimeComponentProps = ComponentRenderProps & {
+  /** Optional observation of the implementation's actual root, without a layout wrapper. */
+  rootRef?: (root: unknown | null) => void;
+  /** Optional native slot containers. Attach directly as refs or forward their returned cleanup. */
+  slotRefs?: NativeSlotRefs;
+  surfaces?: Record<string, ReactNode>;
+  resources: Record<string, ResolvedResource>;
+};
+export type ImplementationPackage = {
+  name: string;
+  version: string;
+  target: string;
+  abi: 1;
+  entries: Record<
+    string,
+    {
+      contract: ComponentContract;
+      component: ComponentType<RuntimeComponentProps>;
+    }
+  >;
+};
+export type PreparedSurface = {
+  target: string;
+  spec: Spec;
+  registry: ComponentRegistry;
+};
+
+export class RuntimeError extends Error {
+  constructor(
+    readonly code: string,
+    readonly element?: string,
+    readonly field?: string,
+  ) {
+    super([code, element, field].filter(Boolean).join(": "));
+    this.name = "RuntimeError";
+  }
+}
+
+/** Prepare before mounting. All references resolve against explicitly installed packages. */
+export function prepareSurface({
+  catalog,
+  target,
+  spec: input,
+  packages,
+  resolveResource,
+}: {
+  catalog: ResolvedCatalog;
+  target: string;
+  spec: Spec;
+  packages: readonly ImplementationPackage[];
+  resolveResource: (reference: ResourceReference) => string;
+}): PreparedSurface {
+  let spec: Spec;
+  try {
+    spec = prepareSpec(catalog, target, input);
+  } catch (error) {
+    if (error instanceof SpecError)
+      throw new RuntimeError(error.code, error.element, error.field);
+    throw error;
+  }
+  return bindSurface({ catalog, target, spec, packages, resolveResource });
+}
+
+/** Internal binding step. Callers must pass a spec returned by prepareSpec/validateLayout.
+ * Not exposed by the package; public preparation entry points always validate. */
+export function bindSurface({
+  catalog,
+  target,
+  spec,
+  packages,
+  resolveResource,
+}: {
+  catalog: ResolvedCatalog;
+  target: string;
+  spec: Spec;
+  packages: readonly ImplementationPackage[];
+  resolveResource: (reference: ResourceReference) => string;
+}): PreparedSurface {
+  const used = new Set(
+    Object.values(spec.elements).map((element) => element.type),
+  );
+
+  const installed = new Map<string, ImplementationPackage>();
+  const packageKey = (name: string, version: string, renderer: string) =>
+    JSON.stringify([name, version, renderer]);
+  for (const implementation of packages) {
+    const key = packageKey(
+      implementation.name,
+      implementation.version,
+      implementation.target,
+    );
+    if (installed.has(key))
+      throw new RuntimeError(
+        "duplicate_implementation_package",
+        implementation.name,
+      );
+    installed.set(key, implementation);
+  }
+  const registry: ComponentRegistry = Object.create(null);
+  for (const key of used) {
+    const definition = catalog.components[key]!;
+    const reference = definition.implementations[target]!;
+    const implementation = installed.get(
+      packageKey(reference.package, reference.version, target),
+    );
+    if (!implementation || implementation.abi !== reference.abi)
+      throw new RuntimeError("missing_implementation_package", key);
+    const entry = Object.hasOwn(implementation.entries, reference.entry)
+      ? implementation.entries[reference.entry]
+      : undefined;
+    if (!entry)
+      throw new RuntimeError(
+        "missing_implementation_entry",
+        key,
+        reference.entry,
+      );
+    if (
+      contractIdentity(entry.contract) !== contractIdentity(definition.contract)
+    )
+      throw new RuntimeError("implementation_contract_mismatch", key);
+    const resources = Object.fromEntries(
+      Object.entries(definition.resources).map(([slot, resource]) => {
+        const url = resolveResource(resource);
+        if (!url) throw new RuntimeError("missing_resource_url", key, slot);
+        return [slot, { reference: resource, url }];
+      }),
+    );
+    const propsSchema = valueValidator(definition.contract.props);
+    registry[key] = function ValidatedComponent(props: ComponentRenderProps) {
+      // json-render resolves state/repeat bindings first. Validate actual runtime values too.
+      if (!propsSchema.safeParse(props.element.props).success)
+        throw new RuntimeError("invalid_resolved_props", key);
+      const emit = (event: string) => {
+        if (!definition.contract.events.includes(event))
+          throw new RuntimeError("undeclared_event", key, event);
+        props.emit(event);
+      };
+      return createElement(entry.component, { ...props, emit, resources });
+    };
+  }
+  return { target, spec, registry };
+}

package/src/three.tsx

@@ -0,0 +1,19 @@
+import { useSyncExternalStore } from "react";
+import { isDevtoolsActive, subscribeDevtoolsActive } from "@json-render/core";
+import { useThree } from "@react-three/fiber";
+import { SurfaceContent, type SurfaceProps } from "./react";
+import { RuntimeError } from "./runtime";
+
+/** Mount under a real R3F root; usable with the R3F unit test renderer as well. */
+export function ThreeScene(props: SurfaceProps) {
+  useThree();
+  const domDevtools = useSyncExternalStore(
+    subscribeDevtoolsActive,
+    isDevtoolsActive,
+    () => false,
+  );
+  if (domDevtools) throw new RuntimeError("dom_devtools_in_three_surface");
+  if (props.surface.target !== "react-three-fiber")
+    throw new RuntimeError("wrong_surface_target");
+  return <SurfaceContent {...props} />;
+}