Provide typed React live-field authoring, strict CLI arguments, and timed build stages

src/bindings/cli.ts

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
 import { readFile, writeFile } from "node:fs/promises";
 import { generateTypeScriptBindings } from "./index.js";
+import path from "node:path";
+import {reactPlatformTypes} from "./react-platform.js";
 
 const main = async () => {
   const [schema, revision, output, options, ...rest] = process.argv.slice(2);
   if (!schema || !revision || !output || rest.length) throw new Error(
     "usage: quixos-codegen-ts SCHEMA.json PACKAGE_REVISION OUTPUT.ts [OPTIONS.json]");
-  const generated = generateTypeScriptBindings(JSON.parse(await readFile(schema, "utf8")), revision,
-    options ? JSON.parse(await readFile(options, "utf8")) : {});
+  const config = options ? JSON.parse(await readFile(options, "utf8")) : {};
+  const generated = generateTypeScriptBindings(JSON.parse(await readFile(schema, "utf8")), revision, config);
   await writeFile(output, generated);
+  if (config.messages?.["org.quixos.web-studio.ReactProps"]) {
+    await writeFile(path.join(path.dirname(output), "web-studio-react-runtime.d.ts"), reactPlatformTypes);
+  }
 };
 main().catch((error: unknown) => { console.error(error instanceof Error ? error.message : error); process.exitCode = 1; });

src/bindings/react-platform.ts

@@ -0,0 +1,62 @@
+/** One authoring contract, distributed by scaffolding and immutable codegen.
+ * Web Studio checks its concrete exports against this contract during its build. */
+export const reactPlatformTypes = `// Generated by the Quixos React platform contract. Do not edit.
+declare module "@quixos/web-studio-react-runtime" {
+  import type * as React from "react";
+  export function useComponentOverlayContainer(): HTMLElement;
+  export function useComponentStyleRoot(): ShadowRoot;
+  export type ObjectRef<AtomId extends string> = string & {
+    readonly $quixosAtom: AtomId;
+  };
+  export type LiveFieldProp<T> = {
+    value: T;
+    source: {
+      objectId: string;
+      slotId: string;
+      valueType?: string;
+      storagePolicy?: string;
+      revision?: string | number | bigint;
+      crdtSnapshot?: {
+        type: string;
+        encoding: string;
+        payload: string;
+      };
+    };
+  };
+  export type ReactComponentHostProps<Action> = {
+    onAction?: (action: Action) => void;
+    fallback?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    onError?: (error: Error) => void;
+  };
+  export type ReactComponentImplementationProps<CaminoProps, RenderProps, Action> = {
+    camino: CaminoProps;
+    render: RenderProps;
+    dispatch: (action: Action) => void;
+  };
+  export const createWebStudioComponent: <
+    ForObject extends ObjectRef<string>, RenderProps extends object, Action,
+  >(config: { expectedAtomId: string }) => (props: {
+    forObject: ForObject;
+  } & RenderProps & ReactComponentHostProps<Action>) => any;
+  export const invokeCapability: <Result = unknown>(
+    objectId: string,
+    interfaceRevisionId: string,
+    operationId: string,
+    value?: unknown,
+    options?: {clientMutationId?: string},
+  ) => Promise<Result>;
+  export const h: typeof React.createElement;
+  export const useLiveField: <T>(
+    field: LiveFieldProp<T>,
+    options?: {
+      reconcileRegister?: (state: {
+        confirmed: T;
+        optimistic: T;
+        pending: boolean;
+      }) => T;
+    },
+  ) => readonly [T, (value: T) => Promise<void>];
+}
+`;