@czap/astro 0.1.0

package/src/runtime/runtime-session.ts

@@ -0,0 +1,139 @@
+/**
+ * Generic runtime-session lifecycle used by every `@czap/astro` client
+ * directive. Owns a microtask scheduler, a set of pending timers, and
+ * a state machine (`idle` / `active` / `reconnecting` / `disposed`)
+ * that every concrete session (stream, llm, gpu, ...) composes.
+ *
+ * @module
+ */
+
+/** Lifecycle states a runtime session progresses through. */
+export type RuntimeSessionState = 'idle' | 'active' | 'reconnecting' | 'disposed';
+
+/**
+ * Shared lifecycle surface shared by every runtime-session kind.
+ *
+ * `schedule` batches callbacks into a single microtask flush;
+ * `setTimer` / `clearTimer` mirror `setTimeout` but participate in
+ * `dispose()` so no task outlives the session.
+ */
+export interface RuntimeSessionShape {
+  readonly state: RuntimeSessionState;
+  activate(): void;
+  beginReconnect(): void;
+  schedule(task: () => void): Promise<void>;
+  setTimer(callback: () => void, delay: number): ReturnType<typeof setTimeout> | null;
+  clearTimer(handle: ReturnType<typeof setTimeout> | null | undefined): null;
+  isDisposed(): boolean;
+  dispose(): void;
+}
+
+/**
+ * Build a fresh runtime session. Every session starts in the `idle`
+ * state and must be explicitly `activate()`d before tasks are allowed
+ * to run.
+ */
+export function createRuntimeSession(): RuntimeSessionShape {
+  let state: RuntimeSessionState = 'idle';
+  let scheduled = false;
+  let tasks: Array<() => void> | null = null;
+  let resolvers: Array<() => void> | null = null;
+  let timers: Set<ReturnType<typeof setTimeout>> | null = null;
+  const resolvePending = (pendingResolvers: ReadonlyArray<() => void>): void => {
+    for (const resolve of pendingResolvers) {
+      resolve();
+    }
+  };
+
+  const flush = (): void => {
+    scheduled = false;
+    const pendingTasks = tasks ?? [];
+    tasks = null;
+    const pendingResolvers = resolvers ?? [];
+    resolvers = null;
+
+    if (state === 'disposed') {
+      resolvePending(pendingResolvers);
+      return;
+    }
+
+    for (const task of pendingTasks) {
+      task();
+    }
+
+    resolvePending(pendingResolvers);
+  };
+
+  return {
+    get state(): RuntimeSessionState {
+      return state;
+    },
+
+    activate(): void {
+      if (state !== 'disposed') {
+        state = 'active';
+      }
+    },
+
+    beginReconnect(): void {
+      if (state !== 'disposed') {
+        state = 'reconnecting';
+      }
+    },
+
+    schedule(task: () => void): Promise<void> {
+      if (state === 'disposed') {
+        return Promise.resolve();
+      }
+
+      (tasks ??= []).push(task);
+      if (!scheduled) {
+        scheduled = true;
+        queueMicrotask(flush);
+      }
+
+      return new Promise<void>((resolve) => {
+        (resolvers ??= []).push(resolve);
+      });
+    },
+
+    setTimer(callback: () => void, delay: number): ReturnType<typeof setTimeout> | null {
+      if (state === 'disposed') {
+        return null;
+      }
+
+      const handle = setTimeout(() => {
+        timers?.delete(handle);
+        callback();
+      }, delay);
+      (timers ??= new Set()).add(handle);
+      return handle;
+    },
+
+    clearTimer(handle: ReturnType<typeof setTimeout> | null | undefined): null {
+      if (!handle) {
+        return null;
+      }
+
+      clearTimeout(handle);
+      timers?.delete(handle);
+      return null;
+    },
+
+    isDisposed(): boolean {
+      return state === 'disposed';
+    },
+
+    dispose(): void {
+      state = 'disposed';
+      for (const handle of timers ?? []) {
+        clearTimeout(handle);
+      }
+      timers = null;
+      tasks = null;
+      const pendingResolvers = resolvers ?? [];
+      resolvers = null;
+      resolvePending(pendingResolvers);
+    },
+  };
+}

package/src/runtime/satellite.ts

@@ -0,0 +1,80 @@
+import {
+  applyBoundaryState,
+  attachViewportObserver,
+  evaluateBoundary,
+  parseBoundary,
+  readSignalValue,
+} from './boundary.js';
+
+/**
+ * Entry point used by the `client:satellite` directive. Parses the
+ * serialised boundary off `element`, attaches a viewport observer
+ * (when the signal is viewport-backed), and recomputes
+ * `data-czap-state` plus CSS variables whenever the signal crosses a
+ * threshold. Honors `czap:reinit` and `czap:dispose` custom events to
+ * re-read / tear down without remounting the island.
+ *
+ * @param load - Dynamic-import factory the directive passes in.
+ * @param element - Satellite root carrying `data-czap-boundary`.
+ */
+export function initSatelliteDirective(load: () => Promise<unknown>, element: HTMLElement): void {
+  let runtimeBoundary = parseBoundary(element.getAttribute('data-czap-boundary'));
+  if (!runtimeBoundary) {
+    return;
+  }
+
+  let previousState = element.getAttribute('data-czap-state') ?? '';
+  let cleanupObserver: (() => void) | null = null;
+
+  const updateState = (): void => {
+    if (!runtimeBoundary) {
+      return;
+    }
+
+    const value = readSignalValue(runtimeBoundary.input);
+    if (value === undefined) {
+      return;
+    }
+
+    const state = evaluateBoundary(runtimeBoundary, value, previousState || undefined);
+    if (state === previousState) {
+      return;
+    }
+
+    previousState = state;
+    applyBoundaryState(
+      element,
+      runtimeBoundary,
+      {
+        discrete: { [runtimeBoundary.name]: state },
+      },
+      'czap:satellite-state',
+    );
+  };
+
+  const cleanup = (): void => {
+    cleanupObserver?.();
+    cleanupObserver = null;
+  };
+
+  const init = (): void => {
+    updateState();
+    if (runtimeBoundary) {
+      cleanupObserver = attachViewportObserver(runtimeBoundary.input, updateState);
+    }
+  };
+
+  element.addEventListener('czap:reinit', () => {
+    cleanup();
+    runtimeBoundary = parseBoundary(element.getAttribute('data-czap-boundary'));
+    previousState = element.getAttribute('data-czap-state') ?? '';
+    init();
+  });
+
+  element.addEventListener('czap:dispose', () => {
+    cleanup();
+  });
+
+  init();
+  load();
+}

package/src/runtime/slots.ts

@@ -0,0 +1,136 @@
+import { SlotRegistry } from '@czap/web';
+import { readRuntimeGlobal, writeRuntimeGlobal } from './globals.js';
+
+interface RuntimeWindow extends Window {
+  __CZAP_SLOT_REGISTRY__?: SlotRegistry.Shape;
+  __CZAP_SLOT_BOOTSTRAPPED__?: boolean;
+  __CZAP_SWAP_REINIT__?: boolean;
+  __CZAP_SLOTS__?: {
+    readonly registry: SlotRegistry.Shape;
+    readonly entries: Record<string, { path: string; mode: string }>;
+  };
+}
+
+const REINIT_SELECTOR = '[data-czap-boundary],[data-czap-stream-url],[data-czap-llm-url],[data-czap-wasm]';
+
+function isSlotRegistryShape(value: unknown): value is SlotRegistry.Shape {
+  if (typeof value !== 'object' || value === null) return false;
+  if (!('get' in value) || !('register' in value) || !('entries' in value)) return false;
+  return typeof value.get === 'function' && typeof value.register === 'function' && typeof value.entries === 'function';
+}
+
+function isBoolean(value: unknown): value is boolean {
+  return typeof value === 'boolean';
+}
+
+function runtimeWindow(): RuntimeWindow | null {
+  return typeof window === 'undefined' ? null : (window as RuntimeWindow);
+}
+
+/**
+ * Return the document-scoped {@link SlotRegistry.Shape}, creating and
+ * persisting one on `window.__CZAP_SLOT_REGISTRY__` the first time
+ * it's requested. Returns a detached registry under SSR.
+ */
+export function getSlotRegistry(): SlotRegistry.Shape {
+  const win = runtimeWindow();
+  if (!win) {
+    return SlotRegistry.create();
+  }
+
+  const existingRegistry = readRuntimeGlobal('__CZAP_SLOT_REGISTRY__', isSlotRegistryShape);
+  if (!existingRegistry) {
+    return writeRuntimeGlobal('__CZAP_SLOT_REGISTRY__', SlotRegistry.create());
+  }
+
+  return existingRegistry;
+}
+
+/**
+ * Clear and rebuild the slot registry by scanning `root` for
+ * `data-czap-slot` elements. Also writes a serialised
+ * `__CZAP_SLOTS__` snapshot for devtools / diagnostics consumers.
+ */
+export function rescanSlots(root: ParentNode = document): SlotRegistry.Shape {
+  const registry = getSlotRegistry();
+  const existingPaths = Array.from(registry.entries().keys());
+  for (const path of existingPaths) {
+    registry.unregister(path);
+  }
+
+  const scanRoot = root instanceof Element ? root : document.documentElement;
+  SlotRegistry.scanDOM(registry, scanRoot);
+
+  const win = runtimeWindow();
+  if (win) {
+    writeRuntimeGlobal('__CZAP_SLOTS__', {
+      registry,
+      entries: Object.fromEntries(
+        Array.from(registry.entries().entries()).map(([path, entry]) => [path, { path, mode: entry.mode }]),
+      ),
+    });
+  }
+
+  return registry;
+}
+
+/**
+ * One-shot bootstrap: arm a slot-registry scan on
+ * `DOMContentLoaded` (or immediately if the document is already
+ * ready) and re-scan after every Astro View Transitions `after-swap`
+ * event. Idempotent -- subsequent calls return the same registry.
+ */
+export function bootstrapSlots(): SlotRegistry.Shape {
+  const win = runtimeWindow();
+  if (!win) {
+    return SlotRegistry.create();
+  }
+
+  const scan = (): void => {
+    rescanSlots(document.documentElement);
+  };
+
+  if (!readRuntimeGlobal('__CZAP_SLOT_BOOTSTRAPPED__', isBoolean)) {
+    writeRuntimeGlobal('__CZAP_SLOT_BOOTSTRAPPED__', true);
+
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', scan, { once: true });
+    } else {
+      scan();
+    }
+
+    document.addEventListener('astro:after-swap', scan);
+  }
+
+  return getSlotRegistry();
+}
+
+/**
+ * Dispatch `czap:dispose` + `czap:reinit` on every known directive
+ * root. Used after Astro View Transitions `after-swap` so directives
+ * can re-read fresh `data-czap-*` attributes without remounting.
+ */
+export function reinitializeDirectives(): void {
+  document.querySelectorAll<HTMLElement>(REINIT_SELECTOR).forEach((element) => {
+    element.dispatchEvent(new CustomEvent('czap:dispose', { bubbles: true }));
+    element.dispatchEvent(new CustomEvent('czap:reinit', { bubbles: true }));
+  });
+}
+
+/**
+ * Install a one-time listener that fires
+ * {@link reinitializeDirectives} on every Astro `after-swap`.
+ * Guarded by `window.__CZAP_SWAP_REINIT__` so repeated module loads
+ * do not stack listeners.
+ */
+export function installSwapReinit(): void {
+  const win = runtimeWindow();
+  if (!win || readRuntimeGlobal('__CZAP_SWAP_REINIT__', isBoolean)) {
+    return;
+  }
+
+  writeRuntimeGlobal('__CZAP_SWAP_REINIT__', true);
+  document.addEventListener('astro:after-swap', () => {
+    reinitializeDirectives();
+  });
+}

package/src/runtime/stream-session.ts

@@ -0,0 +1,125 @@
+/**
+ * Stream-patch scheduler backing the `client:stream` directive.
+ *
+ * Batches incoming HTML patches into a single DOM write per microtask
+ * and reports whether any of the coalesced patches requires a slot
+ * rescan. Delegates lifecycle (activate / dispose / reconnect timer)
+ * to a shared {@link createRuntimeSession}.
+ *
+ * @module
+ */
+import { createRuntimeSession, type RuntimeSessionState } from './runtime-session.js';
+
+/**
+ * A single HTML patch pulled off the stream. `requiresRescan` flags
+ * patches that inserted or removed slot-bearing elements.
+ */
+export interface StreamPatch {
+  readonly html: string;
+  readonly requiresRescan: boolean;
+}
+
+/** Callbacks the scheduler invokes when it writes a batch. */
+export interface StreamSchedulerConfig {
+  /** Write a coalesced HTML patch into the live document. */
+  readonly applyHtml: (html: string) => void;
+  /** Observer fired after each flush with batch metadata. */
+  readonly onFlush: (context: { readonly patchCount: number; readonly requiresRescan: boolean }) => void;
+}
+
+/** Host surface of a stream scheduler. */
+export interface StreamSchedulerShape {
+  readonly state: RuntimeSessionState;
+  activate(): void;
+  beginReconnect(): void;
+  enqueue(patch: StreamPatch): Promise<void>;
+  enqueueBatch(patches: readonly StreamPatch[]): Promise<void>;
+  setReconnectTimer(callback: () => void, delay: number): ReturnType<typeof setTimeout> | null;
+  clearReconnectTimer(handle: ReturnType<typeof setTimeout> | null | undefined): null;
+  dispose(): void;
+}
+
+/**
+ * Build a new stream scheduler. The scheduler coalesces patches into a
+ * single microtask-flushed DOM write and calls `config.onFlush` once
+ * per batch.
+ */
+export function createStreamScheduler(config: StreamSchedulerConfig): StreamSchedulerShape {
+  const runtime = createRuntimeSession();
+  let queue: StreamPatch[] = [];
+  let resolvers: Array<() => void> = [];
+
+  const flush = (): void => {
+    const patches = queue;
+    queue = [];
+    const pendingResolvers = resolvers;
+    resolvers = [];
+
+    let requiresRescan = false;
+    for (const patch of patches) {
+      requiresRescan ||= patch.requiresRescan;
+      config.applyHtml(patch.html);
+    }
+
+    if (patches.length > 0) {
+      config.onFlush({ patchCount: patches.length, requiresRescan });
+    }
+
+    for (const resolve of pendingResolvers) {
+      resolve();
+    }
+  };
+
+  const schedule = (): Promise<void> => {
+    return new Promise<void>((resolve) => {
+      resolvers.push(resolve);
+      void runtime.schedule(flush);
+    });
+  };
+
+  return {
+    get state(): RuntimeSessionState {
+      return runtime.state;
+    },
+
+    activate() {
+      runtime.activate();
+    },
+
+    beginReconnect() {
+      runtime.beginReconnect();
+    },
+
+    enqueue(patch) {
+      queue.push(patch);
+      return schedule();
+    },
+
+    enqueueBatch(patches) {
+      if (patches.length === 0) {
+        return Promise.resolve();
+      }
+
+      queue.push(...patches);
+      return schedule();
+    },
+
+    setReconnectTimer(callback, delay) {
+      return runtime.setTimer(callback, delay);
+    },
+
+    clearReconnectTimer(handle) {
+      return runtime.clearTimer(handle);
+    },
+
+    dispose() {
+      queue = [];
+      const pendingResolvers = resolvers;
+      resolvers = [];
+      for (const resolve of pendingResolvers) {
+        resolve();
+      }
+      runtime.dispose();
+    },
+  };
+}