@czap/core 0.1.0

package/src/component.ts

@@ -0,0 +1,102 @@
+/**
+ * ComponentDef -- adaptive component primitive for constraint-based rendering.
+ *
+ * A component binds a boundary, styles, and named slots into a single
+ * content-addressed unit. Content-addressed via FNV-1a.
+ *
+ * @module
+ */
+
+import type { ContentAddress } from './brands.js';
+import type { Boundary } from './boundary.js';
+import type { Style } from './style.js';
+import { CanonicalCbor } from './cbor.js';
+import { fnv1aBytes } from './fnv.js';
+
+/** Per-slot configuration on a component — whether the slot must be provided, plus optional description. */
+export interface SlotConfig {
+  readonly required: boolean;
+  readonly description?: string;
+}
+
+interface ComponentDef<
+  B extends Boundary.Shape = Boundary.Shape,
+  SlotNames extends readonly string[] = readonly string[],
+> {
+  readonly _tag: 'ComponentDef';
+  readonly _version: 1;
+  readonly id: ContentAddress;
+  readonly name: string;
+  readonly boundary?: B;
+  readonly styles: Style.Shape<B>;
+  readonly slots: { readonly [K in SlotNames[number]]: SlotConfig };
+  readonly defaultSlot?: SlotNames[number];
+}
+
+interface ComponentFactory {
+  make<B extends Boundary.Shape, const SN extends readonly [string, ...string[]]>(config: {
+    readonly name: string;
+    readonly boundary?: B;
+    readonly styles: Style.Shape<B>;
+    readonly slots: { readonly [K in SN[number]]: SlotConfig };
+    readonly defaultSlot?: SN[number];
+  }): ComponentDef<B, SN>;
+}
+
+function deterministicId<SlotNames extends readonly string[]>(
+  name: string,
+  boundaryId: string | undefined,
+  stylesId: string,
+  slots: { readonly [K in SlotNames[number]]: SlotConfig },
+  defaultSlot?: string,
+): ContentAddress {
+  return fnv1aBytes(
+    CanonicalCbor.encode({
+      _tag: 'ComponentDef',
+      _version: 1,
+      name,
+      boundaryId: boundaryId ?? null,
+      stylesId,
+      slots,
+      defaultSlot: defaultSlot ?? null,
+    }),
+  );
+}
+
+/**
+ * Component — the content-addressed unit that binds a {@link Boundary}, a
+ * {@link Style}, and named slots into a single declaration compilers can
+ * target. The optional boundary gates style variants; the slots describe
+ * the consumer-facing API.
+ */
+export const Component: ComponentFactory = {
+  make<B extends Boundary.Shape, const SN extends readonly [string, ...string[]]>(config: {
+    readonly name: string;
+    readonly boundary?: B;
+    readonly styles: Style.Shape<B>;
+    readonly slots: { readonly [K in SN[number]]: SlotConfig };
+    readonly defaultSlot?: SN[number];
+  }): ComponentDef<B, SN> {
+    const id = deterministicId<SN>(config.name, config.boundary?.id, config.styles.id, config.slots, config.defaultSlot);
+
+    const def: ComponentDef<B, SN> = {
+      _tag: 'ComponentDef',
+      _version: 1,
+      id,
+      name: config.name,
+      ...(config.boundary !== undefined ? { boundary: config.boundary } : {}),
+      styles: config.styles,
+      slots: config.slots,
+      ...(config.defaultSlot !== undefined ? { defaultSlot: config.defaultSlot } : {}),
+    };
+    return Object.freeze(def);
+  },
+};
+
+export declare namespace Component {
+  /** Structural shape of a component definition, parameterized by its boundary and slot names. */
+  export type Shape<
+    B extends Boundary.Shape = Boundary.Shape,
+    SN extends readonly string[] = readonly string[],
+  > = ComponentDef<B, SN>;
+}

package/src/composable.ts

@@ -0,0 +1,328 @@
+/**
+ * Composable -- ECS Composition over Existing Primitives
+ *
+ * Universal composition API leveraging existing deterministic primitives.
+ * Zero boilerplate, type-safe, content-addressed entity composition.
+ *
+ * @module
+ */
+
+import type { ContentAddress } from './brands.js';
+import type { Token } from './token.js';
+import type { Style } from './style.js';
+import type { World } from './ecs.js';
+import type { EntityId } from './ecs.js';
+import { Token as TokenNS } from './token.js';
+import { Style as StyleNS } from './style.js';
+import { Boundary } from './boundary.js';
+import { Part } from './ecs.js';
+import { fnv1aBytes } from './fnv.js';
+import { TypedRef } from './typed-ref.js';
+import { Effect } from 'effect';
+
+// ---------------------------------------------------------------------------
+// Entity Composition Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Component map for a {@link ComposableEntity} — well-known slots for czap
+ * primitives plus arbitrary user-defined keys.
+ */
+export interface EntityComponents {
+  readonly boundary?: Boundary.Shape;
+  readonly token?: Token.Shape;
+  readonly style?: Style.Shape;
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Content-addressed entity: the identity is an FNV-1a hash over its components,
+ * so two entities with structurally equal components share the same `id`.
+ */
+export interface ComposableEntity<T extends EntityComponents = EntityComponents> {
+  readonly id: ContentAddress;
+  readonly components: T;
+  readonly _tag: 'ComposableEntity';
+}
+
+// ---------------------------------------------------------------------------
+// Composable Factory
+// ---------------------------------------------------------------------------
+
+interface ComposableFactory {
+  make<T extends EntityComponents>(components: T): ComposableEntity<T>;
+  compose<T extends EntityComponents>(entity1: ComposableEntity<T>, entity2: ComposableEntity<T>): ComposableEntity<T>;
+  merge<T extends EntityComponents>(...entities: ComposableEntity<T>[]): ComposableEntity<T>;
+}
+
+function makeEntityId(components: EntityComponents): ContentAddress {
+  const canonical = canonicalizeForAddress(components);
+  return fnv1aBytes(TypedRef.canonicalize(canonical));
+}
+
+function canonicalizeForAddress(value: unknown): unknown {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => {
+      const canonical = canonicalizeForAddress(entry);
+      return canonical === undefined ? null : canonical;
+    });
+  }
+
+  if (typeof value === 'object') {
+    const entries = Object.entries(value)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, canonicalizeForAddress(entry)]);
+
+    return Object.fromEntries(entries);
+  }
+
+  return String(value);
+}
+
+function _make<T extends EntityComponents>(components: T): ComposableEntity<T> {
+  const id = makeEntityId(components);
+
+  return {
+    id,
+    components,
+    _tag: 'ComposableEntity',
+  };
+}
+
+function _compose<T extends EntityComponents>(
+  entity1: ComposableEntity<T>,
+  entity2: ComposableEntity<T>,
+): ComposableEntity<T> {
+  // Merge components with entity2 taking precedence
+  const merged = { ...entity1.components, ...entity2.components };
+  return _make(merged);
+}
+
+function _merge<T extends EntityComponents>(...entities: ComposableEntity<T>[]): ComposableEntity<T> {
+  if (entities.length === 0) {
+    throw new Error('Cannot merge zero entities');
+  }
+  const first = entities[0];
+  if (!first) {
+    throw new Error('First entity is undefined');
+  }
+  return entities.slice(1).reduce((acc, entity) => _compose(acc, entity), first);
+}
+
+// ---------------------------------------------------------------------------
+// ECS Integration
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a runtime `Map<string, unknown>` (from ECS query results) into a typed
+ * `Pick<Schema, K>`. The ECS query filters guarantee the required keys are present;
+ * this helper contains the one boundary cast where runtime shape joins the type lattice.
+ */
+function entriesToPick<Schema extends EntityComponents, K extends keyof Schema>(
+  components: ReadonlyMap<string, unknown>,
+): Pick<Schema, K> {
+  return Object.fromEntries(components) as Pick<Schema, K>;
+}
+
+interface TypedComposableWorld<Schema extends EntityComponents = EntityComponents> {
+  spawn<T extends Schema>(components: T): Effect.Effect<ComposableEntity<T>>;
+  spawnWith<T extends Schema>(entity: ComposableEntity<T>): Effect.Effect<ComposableEntity<T>>;
+  query<K extends keyof Schema>(...componentTypes: K[]): Effect.Effect<readonly ComposableEntity<Pick<Schema, K>>[]>;
+  evaluate<T extends Schema>(
+    entity: ComposableEntity<T>,
+    input: Record<string, number>,
+  ): Effect.Effect<Record<string, string>>;
+}
+
+function makeComposableWorld<Schema extends EntityComponents = EntityComponents>(
+  world: World.Shape,
+): TypedComposableWorld<Schema> {
+  // Mapping from ContentAddress to ECS EntityId for query reconstruction
+  const addressToEntityId = new Map<ContentAddress, EntityId>();
+
+  return {
+    spawn<T extends Schema>(components: T): Effect.Effect<ComposableEntity<T>> {
+      return Effect.gen(function* () {
+        const entity = _make(components);
+        const ecsId = yield* world.spawn(components);
+        addressToEntityId.set(entity.id, ecsId);
+        return entity;
+      });
+    },
+
+    spawnWith<T extends Schema>(entity: ComposableEntity<T>): Effect.Effect<ComposableEntity<T>> {
+      return Effect.gen(function* () {
+        const ecsId = yield* world.spawn(entity.components);
+        addressToEntityId.set(entity.id, ecsId);
+        return entity;
+      });
+    },
+
+    query<K extends keyof Schema>(...componentTypes: K[]): Effect.Effect<readonly ComposableEntity<Pick<Schema, K>>[]> {
+      return Effect.gen(function* () {
+        const names = [...componentTypes].map((k) => String(k)).sort();
+        const entities = yield* world.query(...names);
+        return [...entities]
+          .sort((left, right) => left.id.localeCompare(right.id))
+          .map((entityShape) => {
+            // world.query guarantees entityShape.components contains at least the K keys
+            // that were queried for; convert the runtime Map<string, unknown> to the typed
+            // Pick<Schema, K> via a single contained cast (runtime shape is validated by
+            // the ECS query filter).
+            const components = entriesToPick<Schema, K>(entityShape.components);
+            return _make(components);
+          });
+      });
+    },
+
+    evaluate<T extends Schema>(
+      entity: ComposableEntity<T>,
+      input: Record<string, number>,
+    ): Effect.Effect<Record<string, string>> {
+      return Effect.gen(function* () {
+        const results: Record<string, string> = {};
+
+        // Evaluate boundary component: quantize continuous input to discrete state
+        let boundaryState: string | undefined;
+        if (entity.components.boundary) {
+          const boundary = entity.components.boundary;
+          const boundaryInput = input[boundary.input] ?? 0;
+          const state = Boundary.evaluate(boundary, boundaryInput);
+          results[boundary.input] = state;
+          boundaryState = state;
+        }
+
+        // Evaluate token component: resolve axis values or fall back
+        if (entity.components.token) {
+          const token = entity.components.token;
+          // Build axis values from input keys. Token.tap expects string axis values,
+          // so we convert matching numeric inputs to strings.
+          const axisValues: Record<string, string> = {};
+          for (const axis of token.axes) {
+            if (axis in input) {
+              axisValues[axis] = String(input[axis]);
+            }
+          }
+          // Use Token.tap for proper axis-key lookup with fallback
+          const resolved = TokenNS.tap(token, axisValues);
+          results[token.name] = String(resolved);
+        }
+
+        // Evaluate style component: resolve properties for the current boundary state
+        if (entity.components.style) {
+          const style = entity.components.style;
+          const resolvedProps = StyleNS.tap(style, boundaryState);
+          for (const [prop, val] of Object.entries(resolvedProps)) {
+            results[prop] = val;
+          }
+        }
+
+        return results;
+      });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dense Store Integration
+// ---------------------------------------------------------------------------
+
+interface ComposableDenseStore {
+  create(name: string, capacity: number): Effect.Effect<Part.Dense>;
+  store<T extends EntityComponents>(entity: ComposableEntity<T>, value: number): Effect.Effect<void>;
+  retrieve<T extends EntityComponents>(entity: ComposableEntity<T>): Effect.Effect<number | undefined>;
+}
+
+function makeComposableDenseStore(world: World.Shape): ComposableDenseStore {
+  // Maintain a mapping from ContentAddress to ECS EntityId for dense store ops
+  const addressToEntityId = new Map<ContentAddress, EntityId>();
+  let denseStore: Part.Dense | undefined;
+
+  return {
+    create(name: string, capacity: number): Effect.Effect<Part.Dense> {
+      return Effect.gen(function* () {
+        const store = Part.dense(name, capacity);
+        yield* world.addDenseStore(store);
+        denseStore = store;
+        return store;
+      });
+    },
+
+    store<T extends EntityComponents>(entity: ComposableEntity<T>, value: number): Effect.Effect<void> {
+      return Effect.gen(function* () {
+        if (!denseStore) {
+          throw new Error('No dense store created. Call create() first.');
+        }
+        // Ensure we have an ECS EntityId for this composable entity
+        let ecsId = addressToEntityId.get(entity.id);
+        if (!ecsId) {
+          // Spawn into the world to get an EntityId, then track mapping
+          ecsId = yield* world.spawn(entity.components);
+          addressToEntityId.set(entity.id, ecsId);
+        }
+        denseStore.set(ecsId, value);
+      });
+    },
+
+    retrieve<T extends EntityComponents>(entity: ComposableEntity<T>): Effect.Effect<number | undefined> {
+      return Effect.gen(function* () {
+        if (!denseStore) {
+          return undefined;
+        }
+        const ecsId = addressToEntityId.get(entity.id);
+        if (!ecsId) {
+          return undefined;
+        }
+        return denseStore.get(ecsId);
+      });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+/**
+ * Composable — content-addressed entity algebra over czap primitives.
+ *
+ * Build entities from a bag of components (boundaries, tokens, styles, …),
+ * merge them associatively via `Composable.compose` / `Composable.merge`, and
+ * rely on the content address to deduplicate structurally-equal entities.
+ */
+export const Composable: ComposableFactory = {
+  /** Content-address a component bag into a {@link ComposableEntity}. */
+  make: _make,
+  /** Pairwise merge — right-biased; produces a new entity with a fresh content address. */
+  compose: _compose,
+  /** Variadic `Composable.compose`. Throws if called with zero entities. */
+  merge: _merge,
+};
+
+/**
+ * Bridge between a raw ECS {@link World} and typed {@link ComposableEntity}
+ * operations (`spawn`, `query`, `evaluate`) plus a thin dense-store integration.
+ */
+export const ComposableWorld = {
+  /** Wrap a {@link World} with the typed composable-entity API. */
+  make: makeComposableWorld,
+  /** Build a dense-store bridge over a {@link World} for per-entity numeric data. */
+  dense: makeComposableDenseStore,
+};
+
+export declare namespace ComposableWorld {
+  /** Structural shape of the typed world returned by {@link ComposableWorld.make}. */
+  export type Shape<Schema extends EntityComponents = EntityComponents> = TypedComposableWorld<Schema>;
+}
+
+// Type exports -- keep legacy alias for backward compatibility
+export type { TypedComposableWorld as ComposableWorldShape };

package/src/compositor-pool.ts

@@ -0,0 +1,162 @@
+/**
+ * CompositorStatePool -- ring buffer of pre-allocated CompositeState objects.
+ *
+ * The compositor grabs one, writes into it, hands it to the renderer,
+ * which returns it after DOM application. Zero-allocation hot path.
+ *
+ * @module
+ */
+
+import type { CompositeState } from './compositor.js';
+import { COMPOSITOR_POOL_CAP } from './defaults.js';
+
+// Zero-allocation ring buffer: pre-allocated fixed-size pool with index-wrapping reads/writes. No GC pressure on hot path.
+
+interface CompositorStatePoolShape {
+  acquire(): CompositeState;
+  release(state: CompositeState): void;
+  readonly size: number;
+  readonly available: number;
+}
+
+/**
+ * Mutable views into a CompositeState's fields. `CompositeState` declares
+ * its fields as `readonly Record<...>`, but the compositor and the pool
+ * both need to mutate those records in place for the zero-allocation
+ * hot path. This helper centralises the single cast that strips
+ * `readonly` so callers can stay type-safe without re-casting at each
+ * write site.
+ */
+export interface MutableCompositeStateViews {
+  readonly discrete: Record<string, string>;
+  readonly blend: Record<string, Record<string, number>>;
+  readonly css: Record<string, number | string>;
+  readonly glsl: Record<string, number>;
+  readonly aria: Record<string, string>;
+}
+
+type MutableCompositeState = {
+  -readonly [K in keyof CompositeState]: CompositeState[K] extends Readonly<infer U> ? U : CompositeState[K];
+} & {
+  outputs: {
+    -readonly [K in keyof CompositeState['outputs']]: CompositeState['outputs'][K];
+  };
+};
+
+/**
+ * Expose the inner `Record<…>`s of a {@link CompositeState} as mutable views
+ * for the zero-allocation hot path. Single sanctioned site that strips
+ * `readonly` — do not cast at other call sites.
+ */
+export function accessCompositeState(state: CompositeState): MutableCompositeStateViews {
+  const mutable = state as MutableCompositeState;
+  return {
+    discrete: mutable.discrete,
+    blend: mutable.blend,
+    css: mutable.outputs.css,
+    glsl: mutable.outputs.glsl,
+    aria: mutable.outputs.aria,
+  };
+}
+
+function createMutableState(): CompositeState {
+  return {
+    discrete: {},
+    blend: {},
+    outputs: { css: {}, glsl: {}, aria: {} },
+  };
+}
+
+function resetState(state: CompositeState): void {
+  // Clear all fields in-place (cheaper than allocation)
+  const { discrete, blend, css, glsl, aria } = accessCompositeState(state);
+  for (const k of Object.keys(discrete)) delete discrete[k];
+  for (const k of Object.keys(blend)) delete blend[k];
+  for (const k of Object.keys(css)) delete css[k];
+  for (const k of Object.keys(glsl)) delete glsl[k];
+  for (const k of Object.keys(aria)) delete aria[k];
+}
+
+/**
+ * Creates a ring-buffer pool of pre-allocated CompositeState objects.
+ * Acquire/release pattern avoids GC allocations on the hot render path.
+ * Default 8 slots -- enough for typical compositor with 4-6 quantizers + headroom.
+ *
+ * @example
+ * ```ts
+ * const pool = CompositorStatePool.make(4);
+ * const state = pool.acquire();
+ * state.discrete['theme'] = 'dark';
+ * state.outputs.css['--bg'] = '#000';
+ * pool.release(state); // resets and returns to pool
+ * pool.available; // 4
+ * ```
+ */
+function _make(capacity = COMPOSITOR_POOL_CAP): CompositorStatePoolShape {
+  const buffer: CompositeState[] = [];
+  for (let i = 0; i < capacity; i++) {
+    buffer.push(createMutableState());
+  }
+
+  const free: boolean[] = new Array(capacity).fill(true);
+  let acquirePtr = 0;
+
+  return {
+    acquire(): CompositeState {
+      // Scan from current pointer for a free slot
+      for (let i = 0; i < capacity; i++) {
+        const idx = (acquirePtr + i) % capacity;
+        if (free[idx]) {
+          free[idx] = false;
+          acquirePtr = (idx + 1) % capacity;
+          return buffer[idx]!;
+        }
+      }
+      // All slots in use — allocate overflow (cold path)
+      const overflow = createMutableState();
+      buffer.push(overflow);
+      free.push(false);
+      return overflow;
+    },
+
+    release(state: CompositeState): void {
+      const idx = buffer.indexOf(state);
+      if (idx !== -1) {
+        resetState(state);
+        free[idx] = true;
+      }
+    },
+
+    get size(): number {
+      return buffer.length;
+    },
+
+    get available(): number {
+      let count = 0;
+      for (let i = 0; i < free.length; i++) {
+        if (free[i]) count++;
+      }
+      return count;
+    },
+  };
+}
+
+/**
+ * CompositorStatePool -- ring buffer of pre-allocated CompositeState objects.
+ * Zero-allocation hot path: acquire a state, write into it, render, then release.
+ *
+ * @example
+ * ```ts
+ * const pool = CompositorStatePool.make(8);
+ * const state = pool.acquire();
+ * // Write compositor output into state.discrete, state.blend, state.outputs
+ * pool.release(state); // resets and returns to pool
+ * console.log(pool.size, pool.available); // 8, 8
+ * ```
+ */
+export const CompositorStatePool = { make: _make };
+
+export declare namespace CompositorStatePool {
+  /** Structural shape of a pool instance: `acquire`, `release`, `size`, `available`. */
+  export type Shape = CompositorStatePoolShape;
+}