quixos-protocol/src/bindings/react-platform.ts

/** 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;
  /** Aggregate transport counters only; contains no object identities or values. */
  export function getFieldTransportMetrics(): Partial<Record<"get" | "watch" | "register" | "crdt" | "setter", Readonly<{started: number; active: number; completed: number; failed: number; totalMs: number}>>>;
  export type ObjectRef<AtomId extends string> = string & {
    readonly $quixosAtom: AtomId;
  };
  export type ReadableField<T> = {readonly value?: T; readonly $field: "query" | "independent"};
  export type QueryField<T> = ReadableField<T> & {readonly $field: "query"};
  export type IndependentField<T> = ReadableField<T> & {readonly $field: "independent"};
  /** set(T) uses the resolved capability: native CRDT fields send incremental edits;
   * custom/manual setters receive semantic values. Storage provenance grants no authority. */
  export type WritableField<T> = ReadableField<T> & {readonly $writeType?: (value: T) => T; readonly writable: true};
  export type WritableQueryField<T> = WritableField<T> & QueryField<T>;
  export type WritableIndependentField<T> = WritableField<T> & IndependentField<T>;
  export function detachField<T>(field: WritableQueryField<T>): WritableIndependentField<T>;
  export function detachField<T>(field: QueryField<T>): IndependentField<T>;
  export type LiveFieldProp<T> = ReadableField<T>;
  export type InterfaceReference<I extends string, Fields> = {readonly $quixosRef: string; readonly interfaceRevisionId: I; readonly fields: Fields};
  export type ReactInterfaceContract<View> = {readonly interfaceRevisionId: string; readonly $viewType?: (view: View) => View};
  export function defineReactInterfaceContract<View>(interfaceRevisionId: string, interfaces: unknown): ReactInterfaceContract<View>;
  export function tryConform<View>(object: string | {readonly $quixosRef: string}, contract: ReactInterfaceContract<View>, options?: {signal?: AbortSignal}): Promise<View | undefined>;
  export type ConformanceResult<View> = {status: "loading"} | {status: "absent"} | {status: "available"; view: View} | {status: "error"; error: Error};
  export function useTryConform<View>(object: string | {readonly $quixosRef: string}, contract: ReactInterfaceContract<View>): ConformanceResult<View>;
  export type QueryValueType = {kind: "builtin" | "scalar"; name: string} | {kind: "record"; fields: Record<string, QueryValueType>} | {kind: "optional" | "list"; value: QueryValueType} | {kind: "object-ref"; expectation: {kind: "atom"; atomId: string} | {kind: "interface"; interfaceRevisionId: string}};
  export type QueryReference<Contract extends string = string> = {readonly $quixosRef: string; readonly queryContract: Contract};
  export type QueryLiveProjection = {path: readonly string[]; selectionId: string; interfaceRevisionId: string; getOperationId: string; setOperationId?: string; watchOperationId?: string; inputKind: "fields" | "value"; valueType: QueryValueType; conditions: {include: boolean; defaultValue?: boolean; value: {kind: "variable"; name: string} | {kind: "literal"; value: unknown}}[]};
  export interface QueryDescriptor<Variables, Result, Kind extends "object" | "workspace-interface" = "object" | "workspace-interface"> {readonly id: string; readonly definitionDigest: string; readonly root: {readonly kind: Kind; readonly interface: string}; readonly variables: QueryValueType; readonly output: QueryValueType; readonly watch: boolean; readonly liveFields?: readonly QueryLiveProjection[]; readonly $types?: (variables: Variables, result: Result) => [Variables, Result]}
  export type QueryPartial<T> = T extends {readonly $quixosRef: string} | ReadableField<unknown> ? T : T extends readonly (infer Item)[] ? QueryPartial<Item>[] : T extends object ? {[Key in keyof T]?: QueryPartial<T[Key]>} : T;
  export type QueryFieldState = {path: readonly (string | number)[]; status: "pending" | "error"; error?: string};
  export type QueryState<T> = {refreshing: boolean; fields: QueryFieldState[]; runId?: string; sequence?: bigint; consistency?: string} & ({status: "loading"; data?: undefined; error?: undefined} | {status: "ready"; data: T; error?: undefined} | {status: "partial"; data: QueryPartial<T>; error?: undefined} | {status: "error"; data?: T | QueryPartial<T>; error: Error});
  export type WorkspaceQueryScope = {readonly $workspaceQueryScope: true};
  export function getWorkspaceQueryScope<Variables, Result>(descriptor: QueryDescriptor<Variables, Result, "workspace-interface">): Promise<WorkspaceQueryScope>;
  export function useQuery<Variables, Result>(descriptor: QueryDescriptor<Variables, Result, "object">, options: {root: string | {readonly $quixosRef: string}; variables: Variables}): QueryState<Result> & {refresh(): void};
  export function useQuery<Variables, Result>(descriptor: QueryDescriptor<Variables, Result, "workspace-interface">, options: {scope: WorkspaceQueryScope; variables: Variables}): QueryState<Result> & {refresh(): void};
  export interface QueryConnection<Row> {entries: {key: string; node: Row; cursor?: string | null}[]; pageInfo: {hasNextPage: boolean; endCursor?: string | null}}
  export function CollectionView<Result, Row>(props: {result: QueryState<Result> & {refresh(): void}; connection(data: QueryPartial<Result>): QueryPartial<QueryConnection<Row>> | undefined; renderItem(row: QueryPartial<Row>, entryKey: string): React.ReactNode; onCreate?: () => void; onLoadMore?: (cursor: string | null) => void; onReset?: () => void; loadingMore?: boolean; empty?: React.ReactNode; prefetch?: boolean}): React.ReactElement;
  export type ReactComponentHostProps<Action> = {
    onAction?: (action: Action) => void;
    fallback?: React.ReactNode;
    className?: string;
    style?: React.CSSProperties;
    /** Optional extra action. The host still displays and reports errors by default. */
    extraErrorAction?: (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; signal?: AbortSignal},
  ) => Promise<Result>;
  export const h: typeof React.createElement;
  export type FieldReadState = "connecting" | "live" | "snapshot" | "inactive" | "not-selected" | "error" | "obsolete";
  export type LiveFieldState<T> = {readState: FieldReadState; refreshing: boolean; stale: boolean; pendingWrites: number; writeError?: Error; refresh(): Promise<void>; discard(): void} & ({status: "loading"; value?: undefined; error?: undefined} | {status: "ready"; value: T; error?: Error} | {status: "error"; value?: undefined; error: Error});
  export type WritableLiveFieldState<T> = LiveFieldState<T> & {set(value: T): Promise<void>; retry(): Promise<void>};
  export function useLiveField<T>(field: ReadableField<T>, options: {id: string; write: (value: T) => Promise<void>}): WritableLiveFieldState<T>;
  export function useLiveField<T>(field: WritableField<T>): WritableLiveFieldState<T>;
  export function useLiveField<T>(field: ReadableField<T>): LiveFieldState<T>;
  export function useSuspenseLiveField<T>(field: WritableField<T>): WritableLiveFieldState<T> & {status: "ready"; value: T};
  export function useSuspenseLiveField<T>(field: ReadableField<T>): LiveFieldState<T> & {status: "ready"; value: T};
}
`;