chore(api): Move runtime constant definitions from @commontools/api to @commontools/runner (#2004)

chore(api): Move runtime constant definitions from @commontools/api to @commontools/runner

Changed ID, ID_FIELD, TYPE, NAME, and UI from concrete exports to ambient declarations in @commontools/api, getting it closer to being a pure TypeScript interface package. The actual runtime values are now defined in @commontools/runner/src/builder/types.ts, where the runtime environment is created. Type compatibility is maintained by having the runner reference the API's declared types using typeof, ensuring both locations share the same TypeScript symbol types.

`schema` and `toSchema` are now being defined in runner as well.

`h` is now defined in the `html` package.

Non-pattern code like tests or Lit components should import the types from @commontools/runner instead of @commontools/api

Author: seefeldb

packages/api/index.ts

@@ -5,16 +5,16 @@
  * Workspace code should import these types via `@commontools/builder`.
  */
 
-export const ID: unique symbol = Symbol("ID, unique to the context");
-export const ID_FIELD: unique symbol = Symbol(
-  "ID_FIELD, name of sibling that contains id",
-);
+// Runtime constants - defined by @commontools/runner/src/builder/types.ts
+// These are ambient declarations since the actual values are provided by the runtime environment
+export declare const ID: unique symbol;
+export declare const ID_FIELD: unique symbol;
 
 // Should be Symbol("UI") or so, but this makes repeat() use these when
 // iterating over recipes.
-export const TYPE = "$TYPE";
-export const NAME = "$NAME";
-export const UI = "$UI";
+export declare const TYPE: "$TYPE";
+export declare const NAME: "$NAME";
+export declare const UI: "$UI";
 
 // ============================================================================
 // Cell Brand System
@@ -933,6 +933,22 @@ 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>;
 
+export type HFunction = {
+  (
+    name: string | ((...args: any[]) => VNode),
+    props: { [key: string]: any } | null,
+    ...children: RenderNode[]
+  ): VNode;
+  fragment({ children }: { children: RenderNode[] }): VNode;
+};
+
+// No-op alternative to `as const as JSONSchema`
+export type SchemaFunction = <T extends JSONSchema>(schema: T) => T;
+
+// toSchema is a compile-time transformer that converts TypeScript types to JSONSchema
+// The actual implementation is done by the TypeScript transformer
+export type ToSchemaFunction = <T>(options?: Partial<JSONSchema>) => JSONSchema;
+
 // Recipe environment types
 export interface RecipeEnvironment {
   readonly apiUrl: URL;
@@ -965,6 +981,8 @@ export declare const cell: CellFunction;
 export declare const stream: StreamFunction;
 export declare const byRef: ByRefFunction;
 export declare const getRecipeEnvironment: GetRecipeEnvironmentFunction;
+export declare const schema: SchemaFunction;
+export declare const toSchema: ToSchemaFunction;
 
 /**
  * Helper type to recursively remove `readonly` properties from type `T`.
@@ -976,14 +994,6 @@ export type Mutable<T> = T extends ReadonlyArray<infer U> ? Mutable<U>[]
   : T extends object ? ({ -readonly [P in keyof T]: Mutable<T[P]> })
   : T;
 
-export const schema = <T extends JSONSchema>(schema: T) => schema;
-
-// toSchema is a compile-time transformer that converts TypeScript types to JSONSchema
-// The actual implementation is done by the TypeScript transformer
-export const toSchema = <T>(_options?: Partial<JSONSchema>): JSONSchema => {
-  return {} as JSONSchema;
-};
-
 // Helper type to transform Cell<T> to Opaque<T> in handler inputs
 export type StripCell<T> = T extends Cell<infer U> ? StripCell<U>
   : T extends Array<infer U> ? StripCell<U>[]
@@ -1245,42 +1255,6 @@ export type SchemaWithoutCell<
   Depth extends DepthLevel = 9,
 > = SchemaInner<T, Root, Depth, false>;
 
-/**
- * Fragment element name used for JSX fragments.
- */
-const FRAGMENT_ELEMENT = "common-fragment";
-
-/**
- * JSX factory function for creating virtual DOM nodes.
- * @param name - The element name or component function
- * @param props - Element properties
- * @param children - Child elements
- * @returns A virtual DOM node
- */
-export const h = Object.assign(function h(
-  name: string | ((...args: any[]) => VNode),
-  props: { [key: string]: any } | null,
-  ...children: RenderNode[]
-): VNode {
-  if (typeof name === "function") {
-    return name({
-      ...(props ?? {}),
-      children: children.flat(),
-    });
-  } else {
-    return {
-      type: "vnode",
-      name,
-      props: props ?? {},
-      children: children.flat(),
-    };
-  }
-}, {
-  fragment({ children }: { children: RenderNode[] }) {
-    return h(FRAGMENT_ELEMENT, null, ...children);
-  },
-});
-
 /**
  * Dynamic properties. Can either be string type (static) or a Mustache
  * variable (dynamic).

packages/html/src/h.ts

@@ -0,0 +1,40 @@
+import { type HFunction, type RenderNode, type VNode } from "@commontools/api";
+
+/**
+ * Fragment element name used for JSX fragments.
+ */
+const FRAGMENT_ELEMENT = "common-fragment";
+
+/**
+ * JSX factory function for creating virtual DOM nodes.
+ * @param name - The element name or component function
+ * @param props - Element properties
+ * @param children - Child elements
+ * @returns A virtual DOM node
+ */
+export const h: HFunction = Object.assign(
+  function h(
+    name: string | ((...args: any[]) => VNode),
+    props: { [key: string]: any } | null,
+    ...children: RenderNode[]
+  ): VNode {
+    if (typeof name === "function") {
+      return name({
+        ...(props ?? {}),
+        children: children.flat(),
+      });
+    } else {
+      return {
+        type: "vnode",
+        name,
+        props: props ?? {},
+        children: children.flat(),
+      };
+    }
+  },
+  {
+    fragment({ children }: { children: RenderNode[] }) {
+      return h(FRAGMENT_ELEMENT, null, ...children);
+    },
+  },
+);

packages/html/src/index.ts

@@ -8,3 +8,4 @@ export {
 } from "./render.ts";
 export { debug, setDebug } from "./logger.ts";
 export { isVNode, type VNode } from "./jsx.ts";
+export { h } from "./h.ts";

packages/html/src/jsx-dev-runtime.ts

@@ -10,7 +10,7 @@
  * @module jsx-dev-runtime
  */
 
-import { h } from "@commontools/api";
+import { h } from "./h.ts";
 import type { RenderNode, VNode } from "@commontools/api";
 
 /**

packages/html/src/jsx-runtime.ts

@@ -7,7 +7,7 @@
  * @module jsx-runtime
  */
 
-import { h } from "@commontools/api";
+import { h } from "./h.ts";
 import type { RenderNode, VNode } from "@commontools/api";
 
 /**

packages/html/test/html-recipes.test.ts

@@ -11,7 +11,7 @@ import {
 import { StorageManager } from "@commontools/runner/storage/cache.deno";
 import * as assert from "./assert.ts";
 import { Identity } from "@commontools/identity";
-import { h } from "@commontools/api";
+import { h } from "@commontools/html";
 
 const signer = await Identity.fromPassphrase("test operator");
 const space = signer.did();

packages/html/test/render.test.ts

@@ -1,9 +1,10 @@
 import { beforeEach, describe, it } from "@std/testing/bdd";
-import { h, UI, VNode } from "@commontools/api";
+import { UI, VNode } from "@commontools/runner";
 import { render, renderImpl } from "../src/render.ts";
 import * as assert from "./assert.ts";
 import { serializableEvent } from "../src/render.ts";
 import { MockDoc } from "../src/mock-doc.ts";
+import { h } from "../src/h.ts";
 
 let mock: MockDoc;
 

packages/runner/src/builder/factory.ts

@@ -6,10 +6,10 @@ import type {
   Cell,
   CreateCellFunction,
   JSONSchema,
+  ToSchemaFunction,
 } from "./types.ts";
 import {
   AuthSchema,
-  h,
   ID,
   ID_FIELD,
   isRecipe,
@@ -18,6 +18,7 @@ import {
   TYPE,
   UI,
 } from "./types.ts";
+import { h } from "@commontools/html";
 import { opaqueRef, stream } from "./opaque-ref.ts";
 import { getTopFrame, recipe } from "./recipe.ts";
 import { byRef, compute, derive, handler, lift, render } from "./module.ts";
@@ -40,7 +41,7 @@ import type { IRuntime } from "../runtime.ts";
 
 // Runtime implementation of toSchema - this should never be called
 // The TypeScript transformer should replace all calls at compile time
-const toSchema = <T>(_options?: Partial<JSONSchema>): JSONSchema => {
+const toSchema: ToSchemaFunction = (_options?) => {
   throw new Error(
     "toSchema() should be transformed at compile time. " +
       "Make sure the TypeScript transformer is configured correctly.",

packages/runner/src/builder/types.ts

@@ -14,6 +14,9 @@ import type {
   GenerateObjectFunction,
   GetRecipeEnvironmentFunction,
   HandlerFunction,
+  HFunction,
+  ID as IDSymbol,
+  ID_FIELD as IDFieldSymbol,
   IfElseFunction,
   JSONSchema,
   JSONSchemaObj,
@@ -31,34 +34,35 @@ import type {
   RecipeFunction,
   RenderFunction,
   Schema,
+  schema as schemaFunction,
   StreamDataFunction,
   StreamFunction,
   StrFunction,
   WishFunction,
 } from "@commontools/api";
-import {
-  h,
-  ID,
-  ID_FIELD,
-  NAME,
-  schema,
-  toSchema,
-  TYPE,
-  UI,
-} from "@commontools/api";
+import { toSchema } from "@commontools/api";
 import { AuthSchema } from "./schema-lib.ts";
+import {
+  type IExtendedStorageTransaction,
+  type MemorySpace,
+} from "../storage/interface.ts";
+import { type RuntimeProgram } from "../harness/types.ts";
+
+// Define runtime constants here - actual runtime values
+export const ID: typeof IDSymbol = Symbol("ID, unique to the context") as any;
+export const ID_FIELD: typeof IDFieldSymbol = Symbol(
+  "ID_FIELD, name of sibling that contains id",
+) as any;
+
+// Should be Symbol("UI") or so, but this makes repeat() use these when
+// iterating over recipes.
+export const TYPE = "$TYPE";
+export const NAME = "$NAME";
+export const UI = "$UI";
+
+export const schema: typeof schemaFunction = (schema) => schema;
+
 export { AuthSchema } from "./schema-lib.ts";
-export {
-  h,
-  ID,
-  ID_FIELD,
-  NAME,
-  type Schema,
-  schema,
-  toSchema,
-  TYPE,
-  UI,
-} from "@commontools/api";
 export type {
   AnyCell,
   Cell,
@@ -84,18 +88,15 @@ export type {
   Recipe,
   RecipeFactory,
   RenderNode,
+  Schema,
   SchemaWithoutCell,
   Stream,
   StripCell,
   toJSON,
+  ToSchemaFunction,
   UnwrapCell,
   VNode,
 } from "@commontools/api";
-import {
-  type IExtendedStorageTransaction,
-  type MemorySpace,
-} from "../storage/interface.ts";
-import { type RuntimeProgram } from "../harness/types.ts";
 
 export type JSONSchemaMutable = Mutable<JSONSchemaObj>;
 
@@ -310,7 +311,7 @@ export interface BuilderFunctionsAndConstants {
   AuthSchema: typeof AuthSchema;
 
   // Render utils
-  h: typeof h;
+  h: HFunction;
 }
 
 // Runtime interface needed by createCell

packages/runner/src/index.ts

@@ -79,7 +79,6 @@ export {
   AuthSchema,
   type Cell as BuilderCell,
   type Frame,
-  h,
   type HandlerFactory,
   ID,
   ID_FIELD,