interface is now truly just the public interface. users should only i…

…mport one or the other

packages/builder/src/built-in.ts

@@ -1,18 +1,13 @@
 import { createNodeFactory, lift } from "./module.ts";
-import type { JSONSchema, NodeFactory, Opaque, OpaqueRef } from "./types.ts";
+import type {
+  Cell,
+  JSONSchema,
+  NodeFactory,
+  Opaque,
+  OpaqueRef,
+} from "./types.ts";
 import type { Schema } from "./schema-to-ts.ts";
 
-// Cell interface for global declaration (avoiding circular dependency)
-interface Cell<T = any> {
-  get(): T;
-  set(value: T): void;
-  send(value: T): void;
-  update(values: Partial<T>): void;
-  push(...value: T extends (infer U)[] ? U[] : never): void;
-  equals(other: Cell<any>): boolean;
-  key<K extends keyof T>(valueKey: K): Cell<T[K]>;
-}
-
 export interface BuiltInLLMParams {
   messages?: string[];
   model?: string;

packages/builder/src/factory.ts

@@ -7,7 +7,7 @@ import type {
   Cell,
   CreateCellFunction,
   JSONSchema,
-} from "./interface.ts";
+} from "./types.ts";
 import { opaqueRef, stream } from "./opaque-ref.ts";
 import { getTopFrame, recipe } from "./recipe.ts";
 import { byRef, compute, derive, handler, lift, render } from "./module.ts";

packages/builder/src/index.ts

@@ -1,6 +1,6 @@
 // Export the factory function
 export { createBuilder } from "./factory.ts";
-export type { BuilderFunctions, BuilderRuntime } from "./interface.ts";
+export type { BuilderFunctions, BuilderRuntime } from "./types.ts";
 
 // Internal functions and exports needed by other packages
 export {

packages/builder/src/interface.ts

@@ -1,6 +1,11 @@
 /**
- * Public interface for the builder package.
- * This module exports only the types and functions that are part of the public API.
+ * Public interface for the builder package. This module exports only the types
+ * and functions that are part of the public API.
+ *
+ * Import these types via `types.ts` for internal code.
+ *
+ * Other packages should either import from `@commontools/builder` or
+ * `@commontools/builder/interface`, but not both.
  */
 
 import type { Mutable } from "@commontools/utils/types";
@@ -343,36 +348,6 @@ export type CellFunction = <T>(value?: T, schema?: JSONSchema) => OpaqueRef<T>;
 export type StreamFunction = <T>(initial?: T) => OpaqueRef<T>;
 export type ByRefFunction = <T, R>(ref: string) => ModuleFactory<T, R>;
 
-// Builder functions interface
-export interface BuilderFunctions {
-  // Recipe creation
-  recipe: RecipeFunction;
-
-  // Module creation
-  lift: LiftFunction;
-  handler: HandlerFunction;
-  derive: DeriveFunction;
-  compute: ComputeFunction;
-  render: RenderFunction;
-
-  // Built-in modules
-  str: StrFunction;
-  ifElse: IfElseFunction;
-  llm: LLMFunction;
-  fetchData: FetchDataFunction;
-  streamData: StreamDataFunction;
-  compileAndRun: CompileAndRunFunction;
-  navigateTo: NavigateToFunction;
-
-  // Cell creation
-  createCell: CreateCellFunction;
-  cell: CellFunction;
-  stream: StreamFunction;
-
-  // Utility
-  byRef: ByRefFunction;
-}
-
 // Re-export all function types as values for destructuring imports
 // These will be implemented by the factory
 export declare const recipe: RecipeFunction;
@@ -393,25 +368,3 @@ export declare const createCell: CreateCellFunction;
 export declare const cell: CellFunction;
 export declare const stream: StreamFunction;
 export declare const byRef: ByRefFunction;
-
-// Runtime interface needed by createCell
-export interface BuilderRuntime {
-  getCell<T>(
-    space: string,
-    cause: any,
-    schema?: JSONSchema,
-    log?: any,
-  ): Cell<T>;
-  getCell<S extends JSONSchema = JSONSchema>(
-    space: string,
-    cause: any,
-    schema: S,
-    log?: any,
-  ): Cell<Schema<S>>;
-}
-
-// Factory function to create builder with runtime
-export type CreateBuilder = (
-  runtime: BuilderRuntime,
-  getCellLinkOrThrow?: (value: any) => any,
-) => BuilderFunctions;

packages/builder/src/types.ts

@@ -1,16 +1,37 @@
 import { isObject } from "@commontools/utils/types";
 
 import type {
+  ByRefFunction,
+  Cell,
+  CellFunction,
+  CompileAndRunFunction,
+  ComputeFunction,
+  CreateCellFunction,
+  DeriveFunction,
+  FetchDataFunction,
+  HandlerFunction,
+  IfElseFunction,
   JSONSchema,
   JSONValue,
+  LiftFunction,
+  LLMFunction,
   Module,
+  NavigateToFunction,
   Opaque,
   OpaqueRef,
   Recipe,
+  RecipeFunction,
+  RenderFunction,
+  Schema,
+  StreamDataFunction,
+  StreamFunction,
+  StrFunction,
 } from "./interface.ts";
 
 export { AuthSchema, ID, ID_FIELD, NAME, TYPE, UI } from "./interface.ts";
 export type {
+  Cell,
+  CreateCellFunction,
   Handler,
   HandlerFactory,
   JSONObject,
@@ -27,6 +48,10 @@ export type {
   toJSON,
 } from "./interface.ts";
 
+// Augment the public interface with the internal OpaqueRefMethods interface.
+// Deliberately repeating the original interface to catch any inconsistencies:
+// This here then reflects the entire interface the internal implementation
+// implements.
 declare module "./interface.ts" {
   interface OpaqueRefMethods<T> {
     get(): OpaqueRef<T>;
@@ -219,3 +244,55 @@ export function markAsStatic(value: unknown): unknown {
   (value as any)[isStaticMarker] = true;
   return value;
 }
+
+// Builder functions interface
+export interface BuilderFunctions {
+  // Recipe creation
+  recipe: RecipeFunction;
+
+  // Module creation
+  lift: LiftFunction;
+  handler: HandlerFunction;
+  derive: DeriveFunction;
+  compute: ComputeFunction;
+  render: RenderFunction;
+
+  // Built-in modules
+  str: StrFunction;
+  ifElse: IfElseFunction;
+  llm: LLMFunction;
+  fetchData: FetchDataFunction;
+  streamData: StreamDataFunction;
+  compileAndRun: CompileAndRunFunction;
+  navigateTo: NavigateToFunction;
+
+  // Cell creation
+  createCell: CreateCellFunction;
+  cell: CellFunction;
+  stream: StreamFunction;
+
+  // Utility
+  byRef: ByRefFunction;
+}
+
+// Runtime interface needed by createCell
+export interface BuilderRuntime {
+  getCell<T>(
+    space: string,
+    cause: any,
+    schema?: JSONSchema,
+    log?: any,
+  ): Cell<T>;
+  getCell<S extends JSONSchema = JSONSchema>(
+    space: string,
+    cause: any,
+    schema: S,
+    log?: any,
+  ): Cell<Schema<S>>;
+}
+
+// Factory function to create builder with runtime
+export type CreateBuilder = (
+  runtime: BuilderRuntime,
+  getCellLinkOrThrow?: (value: any) => any,
+) => BuilderFunctions;