@lostgradient/weft 0.2.0

package/dist/server/task-state.js

@@ -0,0 +1,178 @@
+import { decode, encode } from "../core/codec.js";
+import { KEYS } from "../storage/interface.js";
+import { buildResolvedRecord } from "./task-resolved-record.js";
+export async function getTaskState(storage, operationId) {
+  const [inflight, queued, resolved] = await Promise.all([
+    storage.get(KEYS.operationInflight(operationId)),
+    storage.get(KEYS.operationQueued(operationId)),
+    storage.get(KEYS.operationResolved(operationId))
+  ]);
+  if (inflight !== null)
+    return "inflight";
+  if (queued !== null)
+    return "queued";
+  if (resolved !== null)
+    return "resolved";
+  return null;
+}
+export async function getExclusiveTaskState(storage, operationId) {
+  const [inflight, queued, resolved] = await Promise.all([
+    storage.get(KEYS.operationInflight(operationId)),
+    storage.get(KEYS.operationQueued(operationId)),
+    storage.get(KEYS.operationResolved(operationId))
+  ]), states = [];
+  if (inflight !== null)
+    states.push("inflight");
+  if (queued !== null)
+    states.push("queued");
+  if (resolved !== null)
+    states.push("resolved");
+  if (states.length > 1)
+    throw Error(`Task "${operationId}" occupies multiple states simultaneously: ${states.join(", ")}`);
+  return states[0] ?? null;
+}
+export function isQueuedRecord(value) {
+  if (value === null || typeof value !== "object")
+    return !1;
+  const record = value;
+  return typeof record.operationId === "string" && typeof record.activityName === "string" && typeof record.queue === "string" && typeof record.attempt === "number" && typeof record.visibilityTimeout === "number" && typeof record.queuedAt === "number";
+}
+export function isInflightRecord(value) {
+  if (value === null || typeof value !== "object")
+    return !1;
+  const record = value;
+  return typeof record.operationId === "string" && typeof record.activityName === "string" && typeof record.queue === "string" && typeof record.attempt === "number" && typeof record.visibilityTimeout === "number" && typeof record.workerId === "string" && typeof record.deadline === "number";
+}
+export function isResolvedRecord(value) {
+  if (value === null || typeof value !== "object")
+    return !1;
+  const record = value;
+  return typeof record.operationId === "string" && (record.status === "completed" || record.status === "failed") && typeof record.resolvedAt === "number";
+}
+export async function readQueuedRecord(storage, operationId) {
+  const value = await storage.get(KEYS.operationQueued(operationId));
+  if (value === null)
+    return null;
+  const decoded = decode(value);
+  return isQueuedRecord(decoded) ? decoded : null;
+}
+export async function readInflightRecord(storage, operationId) {
+  const value = await storage.get(KEYS.operationInflight(operationId));
+  if (value === null)
+    return null;
+  const decoded = decode(value);
+  return isInflightRecord(decoded) ? decoded : null;
+}
+function normalizeQueuedRecordLifecycle(record, previous) {
+  const normalized = {
+    ...record,
+    firstQueuedAt: resolveQueuedFirstQueuedAt(record, previous),
+    lastQueuedAt: record.lastQueuedAt ?? record.queuedAt,
+    retryCount: resolveRetryCount(record, previous),
+    requeueCount: record.requeueCount ?? previous?.requeueCount ?? 0
+  };
+  applyPreviousLifecycleFields(normalized, previous);
+  return normalized;
+}
+function normalizeInflightRecordLifecycle(record, previous, now = Date.now()) {
+  const lastDispatchedAt = record.lastDispatchedAt ?? now, firstQueuedAt = resolveInflightFirstQueuedAt(record, previous, lastDispatchedAt), normalized = {
+    ...record,
+    firstQueuedAt,
+    lastQueuedAt: resolveInflightLastQueuedAt(record, previous, firstQueuedAt),
+    lastDispatchedAt,
+    startedAt: record.startedAt ?? lastDispatchedAt,
+    retryCount: resolveRetryCount(record, previous),
+    requeueCount: record.requeueCount ?? previous?.requeueCount ?? 0
+  };
+  applyPreviousLifecycleFields(normalized, previous);
+  return normalized;
+}
+function resolveQueuedFirstQueuedAt(record, previous) {
+  return record.firstQueuedAt ?? previous?.firstQueuedAt ?? previous?.lastQueuedAt ?? record.queuedAt;
+}
+function resolveInflightFirstQueuedAt(record, previous, lastDispatchedAt) {
+  return record.firstQueuedAt ?? previous?.firstQueuedAt ?? previous?.lastQueuedAt ?? previous?.queuedAt ?? lastDispatchedAt;
+}
+function resolveInflightLastQueuedAt(record, previous, firstQueuedAt) {
+  return record.lastQueuedAt ?? previous?.lastQueuedAt ?? previous?.queuedAt ?? firstQueuedAt;
+}
+function resolveRetryCount(record, previous) {
+  return record.retryCount ?? previous?.retryCount ?? Math.max(0, record.attempt - 1);
+}
+function applyPreviousLifecycleFields(record, previous) {
+  if (previous === void 0 || previous === null)
+    return;
+  record.lastDispatchedAt ??= previous.lastDispatchedAt;
+  record.startedAt ??= previous.startedAt;
+  record.lastRequeueReason ??= previous.lastRequeueReason;
+}
+export function calculateQueueLatencyMs(record) {
+  if (record.lastQueuedAt === void 0 || record.lastDispatchedAt === void 0)
+    return;
+  return Math.max(0, record.lastDispatchedAt - record.lastQueuedAt);
+}
+export function calculateExecutionLatencyMs(record, completedAt) {
+  const startedAt = record.startedAt ?? record.lastDispatchedAt;
+  if (startedAt === void 0)
+    return;
+  return Math.max(0, completedAt - startedAt);
+}
+export function calculateHeartbeatAgeMs(record, currentTime) {
+  const heartbeatReference = record.lastHeartbeatAt ?? record.startedAt ?? record.lastDispatchedAt ?? record.deadline;
+  if (heartbeatReference === void 0)
+    return;
+  return Math.max(0, currentTime - heartbeatReference);
+}
+export function isHeartbeatStale(record, currentTime, staleAfterMs) {
+  const heartbeatAgeMs = calculateHeartbeatAgeMs(record, currentTime);
+  return heartbeatAgeMs !== void 0 && heartbeatAgeMs >= staleAfterMs;
+}
+export async function markQueued(storage, record) {
+  const normalizedRecord = normalizeQueuedRecordLifecycle(record);
+  await storage.put(KEYS.operationQueued(record.operationId), encode(normalizedRecord));
+  return normalizedRecord;
+}
+export async function transitionQueuedToInflight(storage, operationId, inflightRecord, options = {}) {
+  const queuedRecord = options.queuedRecord === void 0 ? await readQueuedRecord(storage, operationId) : options.queuedRecord, normalizedInflightRecord = normalizeInflightRecordLifecycle(inflightRecord, queuedRecord, options.now);
+  await storage.batch([
+    { type: "delete", key: KEYS.operationQueued(operationId) },
+    {
+      type: "put",
+      key: KEYS.operationInflight(operationId),
+      value: encode(normalizedInflightRecord)
+    }
+  ]);
+  return normalizedInflightRecord;
+}
+export async function markInflight(storage, record) {
+  await storage.put(KEYS.operationInflight(record.operationId), encode(normalizeInflightRecordLifecycle(record)));
+}
+export async function transitionInflightToResolved(storage, operationId, status, options = {}) {
+  const existingRecord = options.record ?? await readInflightRecord(storage, operationId), resolvedAt = options.resolvedAt ?? Date.now(), normalizedRecord = existingRecord === null ? null : normalizeInflightRecordLifecycle(existingRecord, null, resolvedAt), resolutionReason = options.resolutionReason ?? (status === "completed" ? "completed" : "failed"), resolvedRecord = buildResolvedRecord({
+    operationId,
+    status,
+    resolvedAt,
+    normalizedRecord,
+    resolutionReason,
+    value: options.value,
+    error: options.error,
+    queueLatencyMs: normalizedRecord === null ? void 0 : calculateQueueLatencyMs(normalizedRecord),
+    executionLatencyMs: normalizedRecord === null ? void 0 : calculateExecutionLatencyMs(normalizedRecord, resolvedAt)
+  }), encodedResolvedRecord = encode(resolvedRecord);
+  await storage.batch([
+    { type: "delete", key: KEYS.operationInflight(operationId) },
+    { type: "put", key: KEYS.operationResolved(operationId), value: encodedResolvedRecord },
+    {
+      type: "put",
+      key: KEYS.operationResolvedByTime(resolvedAt, operationId),
+      value: encodedResolvedRecord
+    }
+  ]);
+}
+export async function transitionInflightToQueued(storage, operationId, queuedRecord) {
+  const inflightRecord = await readInflightRecord(storage, operationId), normalizedQueuedRecord = normalizeQueuedRecordLifecycle(queuedRecord, inflightRecord);
+  await storage.batch([
+    { type: "delete", key: KEYS.operationInflight(operationId) },
+    { type: "put", key: KEYS.operationQueued(operationId), value: encode(normalizedQueuedRecord) }
+  ]);
+}

package/dist/server/workflow-event-feed.d.ts

@@ -0,0 +1,166 @@
+/**
+ * `WorkflowEventFeed` — transport-neutral event replay + live-tail
+ * contract shared by REST SSE, WebSocket watch/stream, and JSON-RPC
+ * subscribe. Track 8 design decision 5 and 6.
+ *
+ * **Atomic handoff ordering** (the only sequence that avoids both
+ * duplicates and gaps when a subscriber joins mid-stream):
+ *
+ *   1. Register a live listener into a bounded in-memory buffer.
+ *      From this moment, every newly-emitted event is captured.
+ *   2. Snapshot the current live-tail sequence `S` (read once).
+ *   3. Stream storage replay from `fromCursor` up to and including `S`.
+ *   4. Drain the buffer, dropping any envelope with `sequence <= S`
+ *      (already replayed) and emitting the rest.
+ *   5. Continue emitting live envelopes directly as the listener fires.
+ *
+ * Buffer bound is configurable (default 1000 envelopes per subscription).
+ * Overflow closes the subscription with a `SubscriptionOverflow` signal
+ * (the iterable terminates; the caller reopens with its last delivered
+ * cursor). Unbounded-memory-growth is not an option here.
+ *
+ * **Cursor is opaque.** `encodeCursor(sequence)` and
+ * `decodeCursor(cursor)` are the only code that knows the representation
+ * — REST `Last-Event-ID`, WS `?resumeFrom=`, and JSON-RPC `fromCursor`
+ * all round-trip through this module.
+ */
+import type { WeftEventMap } from '../core/events.ts';
+/**
+ * Discriminator string carried on every envelope. The union covers:
+ *
+ *   - Dispatched `WeftEventMap` event names (`workflow:started`,
+ *     `activity:completed`, `stream:token`, …) — emitted when a
+ *     future log entry type corresponds to a runtime `Event`.
+ *   - Durable log entry types not in `WeftEventMap`
+ *     (`workflow:checkpoint` — the only one today; add others here
+ *     as new log kinds land).
+ *   - Selector-scoped synthetic kinds (`stream:chunk`) for records
+ *     that are not dispatched `Event` objects at all.
+ *   - An open `(string & {})` tail so third-party event kinds don't
+ *     fail typechecking at the envelope construction site while
+ *     IntelliSense still suggests the known literals.
+ *
+ * Cross-transport consumers match on `selector` first, then on
+ * `kind` within that selector. This union is extensible and preserves
+ * completion for known kinds, but the open-string tail means it does
+ * not by itself reject arbitrary or misspelled string literals.
+ */
+export type FeedEventKind = keyof WeftEventMap | 'workflow:checkpoint' | 'stream:chunk' | (string & {});
+/** Opaque cursor. Only `encodeCursor` / `decodeCursor` know the format. */
+export type Cursor = string;
+/**
+ * Encode a non-negative integer sequence as an opaque cursor. The
+ * current encoding is the decimal string form of the sequence, matching
+ * the existing `sequence-cursor.ts` public representation so REST
+ * `Last-Event-ID` / `?after=` clients continue to work unchanged. The
+ * encoding is intentionally not part of the public API — a future
+ * migration to base64 / hex / compact binary can happen without
+ * breaking anything that goes through this module.
+ */
+export declare function encodeCursor(sequence: number): Cursor;
+/**
+ * Decode an opaque cursor back to its sequence. `-1` is the initial
+ * sentinel for "before the first event"; malformed input returns null.
+ */
+export declare function decodeCursor(cursor: Cursor): number | null;
+export type EventSelector = 'events' | 'tokens';
+/**
+ * Unified event envelope delivered by the feed. Transports serialize
+ * this directly (REST SSE `data:` line, WS JSON frame, JSON-RPC
+ * `weft.events.deliver` params). `kind` narrows `payload` shape in
+ * caller code via discriminated-union typing.
+ */
+export type EventEnvelope = {
+    readonly kind: FeedEventKind;
+    readonly workflowId: string;
+    readonly selector: EventSelector;
+    readonly sequence: number;
+    readonly cursor: Cursor;
+    readonly emittedAtMs: number;
+    readonly payload: unknown;
+};
+/**
+ * Pluggable storage + live-event source. The in-memory implementation
+ * is used by unit tests; the production implementation wraps
+ * `engine.storage` event scans + `EngineEventTarget` subscription.
+ */
+export type WorkflowEventFeedBackend = {
+    /**
+     * Yield persisted envelopes with `sequence > afterSequence` in
+     * sequence order. `afterSequence: -1` means "from the beginning."
+     */
+    replay(options: {
+        workflowId: string;
+        selector: EventSelector;
+        afterSequence: number;
+    }): AsyncIterable<EventEnvelope>;
+    /**
+     * Snapshot the current tail sequence for a workflow. Used in the
+     * atomic-handoff sequence to bound the replay scan. Returns -1 if
+     * no events have been emitted yet.
+     */
+    snapshotTailSequence(workflowId: string, selector: EventSelector): Promise<number>;
+    /**
+     * Register a live listener. Returns an unsubscribe function.
+     *
+     * Contract:
+     *   - Envelopes MUST be delivered in monotonically increasing
+     *     sequence order. The feed's live-buffer drain relies on this
+     *     for its dedupe logic — an out-of-order emission would cause
+     *     the feed to advance `lastDelivered` past a later-arriving
+     *     lower-sequence event and silently drop it.
+     *   - The listener SHOULD be invoked synchronously from the
+     *     event-emitter context. Backends that defer to a microtask
+     *     (or later) still work correctly because the feed's listener
+     *     buffers envelopes off the fast path, but synchronous delivery
+     *     minimizes handoff latency.
+     *   - Listener exceptions MUST NOT propagate to the backend's
+     *     event-emitter; the in-memory implementation wraps each
+     *     invocation in try/catch. Production backends should match.
+     */
+    subscribeLive(workflowId: string, selector: EventSelector, listener: (envelope: EventEnvelope) => void): () => void;
+};
+export type WorkflowEventFeed = {
+    /**
+     * Replay stored events only. No live subscription. Yields every
+     * envelope with `sequence > decodeCursor(fromCursor)` up to an
+     * optional `limit`, in sequence order, then completes.
+     */
+    replay(options: {
+        workflowId: string;
+        selector: EventSelector;
+        fromCursor?: Cursor;
+        limit?: number;
+    }): AsyncIterable<EventEnvelope>;
+    /**
+     * Replay + live-tail. Implements the atomic-handoff sequence so a
+     * subscriber joining mid-stream sees every event exactly once.
+     * Caller controls termination via `signal.abort()` or by exiting
+     * the `for await` loop (the feed cleans up the live listener).
+     */
+    subscribe(options: {
+        workflowId: string;
+        selector: EventSelector;
+        fromCursor?: Cursor;
+        signal?: AbortSignal;
+    }): AsyncIterable<EventEnvelope>;
+    /** Tear down any feed-level resources (no-op for the in-memory path). */
+    dispose(): void;
+};
+export type WorkflowEventFeedOptions = {
+    /** Max envelopes the live buffer holds before overflow terminates the subscription. */
+    liveBufferSize?: number;
+};
+export declare function createWorkflowEventFeed(backend: WorkflowEventFeedBackend, options?: WorkflowEventFeedOptions): WorkflowEventFeed;
+export type InMemoryEventBackend = WorkflowEventFeedBackend & {
+    /** Append an envelope to storage (used by tests). */
+    append(envelope: EventEnvelope): Promise<void>;
+    /**
+     * Emit a live event to any active listener WITHOUT persisting it
+     * to storage. Used by tests to simulate the race between storage
+     * writes and live dispatch. Production backends emit and persist in
+     * one step.
+     */
+    emitLive(envelope: EventEnvelope): Promise<void>;
+};
+export declare function createInMemoryEventBackend(): InMemoryEventBackend;

package/dist/server/workflow-event-feed.js

@@ -0,0 +1,193 @@
+const CURSOR_PATTERN = /^(?:-1|\d+)$/;
+export function encodeCursor(sequence) {
+  if (!Number.isInteger(sequence) || sequence < 0)
+    throw Error(`encodeCursor: sequence must be a non-negative integer, got ${sequence}`);
+  return String(sequence);
+}
+export function decodeCursor(cursor) {
+  if (!CURSOR_PATTERN.test(cursor))
+    return null;
+  const value = Number(cursor);
+  if (!Number.isSafeInteger(value) || value < -1)
+    return null;
+  return value;
+}
+const DEFAULT_LIVE_BUFFER_SIZE = 1000;
+export function createWorkflowEventFeed(backend, options) {
+  const bufferSize = options?.liveBufferSize ?? DEFAULT_LIVE_BUFFER_SIZE;
+  async function* replay(args) {
+    const afterSequence = args.fromCursor !== void 0 ? decodeCursor(args.fromCursor) ?? -1 : -1;
+    let yielded = 0;
+    for await (const envelope of backend.replay({
+      workflowId: args.workflowId,
+      selector: args.selector,
+      afterSequence
+    })) {
+      if (args.limit !== void 0 && yielded >= args.limit)
+        return;
+      yield envelope;
+      yielded += 1;
+    }
+  }
+  function subscribe(args) {
+    const buffer = [];
+    let bufferOverflowed = !1, waker = null;
+    const unsubscribe = backend.subscribeLive(args.workflowId, args.selector, (envelope) => {
+      if (buffer.length >= bufferSize)
+        bufferOverflowed = !0;
+      else
+        buffer.push(envelope);
+      if (waker) {
+        const fire = waker;
+        waker = null;
+        fire();
+      }
+    }), onAbort = () => {
+      if (waker) {
+        const fire = waker;
+        waker = null;
+        fire();
+      }
+    };
+    args.signal?.addEventListener("abort", onAbort);
+    async function* generator() {
+      try {
+        if (args.signal?.aborted)
+          return;
+        const snapshot = await backend.snapshotTailSequence(args.workflowId, args.selector), requestedAfter = args.fromCursor !== void 0 ? decodeCursor(args.fromCursor) ?? -1 : -1;
+        if (snapshot > requestedAfter) {
+          yield* replayUpTo(backend, args, requestedAfter, snapshot);
+          if (args.signal?.aborted)
+            return;
+        }
+        yield* drainLive(buffer, snapshot, args.signal, () => bufferOverflowed, (w) => {
+          waker = w;
+        });
+      } finally {
+        args.signal?.removeEventListener("abort", onAbort);
+        unsubscribe();
+      }
+    }
+    return generator();
+  }
+  return {
+    replay,
+    subscribe,
+    dispose() {}
+  };
+}
+async function* replayUpTo(backend, args, afterSequence, snapshot) {
+  for await (const envelope of backend.replay({
+    workflowId: args.workflowId,
+    selector: args.selector,
+    afterSequence
+  })) {
+    if (envelope.sequence > snapshot)
+      break;
+    if (args.signal?.aborted)
+      return;
+    yield envelope;
+  }
+}
+function flushPendingBuffer(buffer, watermark) {
+  const batch = [];
+  let newWatermark = watermark, head = buffer.shift();
+  while (head !== void 0) {
+    if (head.sequence > newWatermark) {
+      batch.push(head);
+      newWatermark = head.sequence;
+    }
+    head = buffer.shift();
+  }
+  return { batch, newWatermark };
+}
+async function armAndWait(buffer, overflowed, signal, installWaker) {
+  const armed = new Promise((resolve) => {
+    installWaker(resolve);
+  });
+  if (buffer.length > 0 || overflowed() || signal?.aborted) {
+    installWaker(null);
+    return;
+  }
+  await armed;
+}
+async function* drainLive(buffer, snapshot, signal, overflowed, installWaker) {
+  let watermark = snapshot;
+  while (!0) {
+    if (signal?.aborted || overflowed())
+      return;
+    const { batch, newWatermark } = flushPendingBuffer(buffer, watermark);
+    watermark = newWatermark;
+    for (const envelope of batch) {
+      if (signal?.aborted || overflowed())
+        return;
+      yield envelope;
+    }
+    if (batch.length > 0)
+      continue;
+    await armAndWait(buffer, overflowed, signal, installWaker);
+  }
+}
+function bucketKey(workflowId, selector) {
+  return `${workflowId}:${selector}`;
+}
+export function createInMemoryEventBackend() {
+  const storage = new Map, listeners = new Map;
+  function fireLive(envelope) {
+    const set = listeners.get(bucketKey(envelope.workflowId, envelope.selector));
+    if (!set)
+      return;
+    for (const listener of set)
+      try {
+        listener(envelope);
+      } catch {}
+  }
+  return {
+    async* replay(options) {
+      const bucket = storage.get(bucketKey(options.workflowId, options.selector));
+      if (!bucket)
+        return;
+      const sorted = [...bucket].toSorted((a, b) => a.sequence - b.sequence);
+      for (const envelope of sorted)
+        if (envelope.sequence > options.afterSequence)
+          yield envelope;
+    },
+    async snapshotTailSequence(workflowId, selector) {
+      const bucket = storage.get(bucketKey(workflowId, selector));
+      if (!bucket || bucket.length === 0)
+        return -1;
+      let max = -1;
+      for (const envelope of bucket)
+        if (envelope.sequence > max)
+          max = envelope.sequence;
+      return max;
+    },
+    subscribeLive(workflowId, selector, listener) {
+      const k = bucketKey(workflowId, selector);
+      let set = listeners.get(k);
+      if (!set) {
+        set = new Set;
+        listeners.set(k, set);
+      }
+      set.add(listener);
+      return () => {
+        set?.delete(listener);
+        if (set && set.size === 0)
+          listeners.delete(k);
+      };
+    },
+    async append(envelope) {
+      const k = bucketKey(envelope.workflowId, envelope.selector);
+      let bucket = storage.get(k);
+      if (!bucket) {
+        bucket = [];
+        storage.set(k, bucket);
+      }
+      bucket.push(envelope);
+      fireLive(envelope);
+    },
+    async emitLive(envelope) {
+      fireLive(envelope);
+    }
+  };
+}

package/dist/service-worker/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Service Worker bootstrap functions for Weft.
+ *
+ * Composable functions that users wire up in their own Service Worker file.
+ * Does NOT auto-register event listeners.
+ *
+ * @module service-worker
+ */
+import type { Engine } from '../core/engine';
+import type { ServiceWorkerScheduler } from './scheduler';
+import type { MinimalExtendableEvent, MinimalFetchEvent, MinimalPeriodicSyncEvent } from './shared.ts';
+export { buildDelegatedRequest, DEFAULT_PERIODIC_SYNC_TAG, normalizePathPrefix } from './shared.ts';
+export type { MinimalExtendableEvent, MinimalFetchEvent, MinimalPeriodicSyncEvent, } from './shared.ts';
+/**
+ * Options for the Service Worker bootstrap functions
+ * (`createFetchHandler`, `createPeriodicSyncHandler`, `createLifecycleHandlers`).
+ *
+ * Supply the {@link Engine} instance that the service worker should delegate
+ * workflow requests to.  Use `pathPrefix` to scope which fetch requests the
+ * handler intercepts (default: `'/weft/'`).
+ *
+ * @example
+ * ```ts
+ * import { createFetchHandler, type ServiceWorkerOptions } from '@lostgradient/weft/service-worker';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * const storage = new MemoryStorage();
+ * const engine = new Engine({ storage });
+ *
+ * const options: ServiceWorkerOptions = { engine, pathPrefix: '/weft/' };
+ * const handleFetch = createFetchHandler(options);
+ * // In a Service Worker file: self.addEventListener('fetch', handleFetch);
+ * void handleFetch;
+ * ```
+ */
+export interface ServiceWorkerOptions {
+    engine: Engine;
+    pathPrefix?: string;
+}
+/**
+ * Create a fetch event handler that intercepts requests matching the given
+ * path prefix and delegates them to the Weft HTTP handler.
+ *
+ * The default `pathPrefix` is `'/weft/'`. A trailing slash is auto-appended
+ * when missing, so `'/weft'` and `'/weft/'` behave identically. Requests
+ * whose pathname does not start with the (normalized) prefix are passed
+ * through — the handler simply returns without calling
+ * `event.respondWith`, leaving the request to the next service-worker
+ * listener or the network. Matching requests have the prefix stripped
+ * before delegation: `/weft/v1/health` becomes `/v1/health` for
+ * {@link Engine}.
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ * import { createFetchHandler } from '@lostgradient/weft/service-worker';
+ *
+ * const engine = new Engine({ storage: new MemoryStorage() });
+ * const handler = createFetchHandler({ engine, pathPrefix: '/weft/' });
+ *
+ * // In your Service Worker:
+ * // self.addEventListener('fetch', handler);
+ * console.log(typeof handler); // 'function'
+ * ```
+ */
+export declare function createFetchHandler(options: ServiceWorkerOptions): (event: MinimalFetchEvent) => void;
+/**
+ * Create a periodic sync event handler that ticks the scheduler
+ * when the matching tag fires.
+ *
+ * The default `tag` is `'weft-timers'`. Events with non-matching tags are
+ * silently ignored. The returned handler invokes `scheduler.tick()` inside
+ * `event.waitUntil(...)` so the sync extends until the tick promise
+ * resolves.
+ *
+ * Note: `ServiceWorkerScheduler` is the parameter type but is not currently
+ * re-exported from `@lostgradient/weft/service-worker` — construct the scheduler in the
+ * module that imports it directly (e.g. the dashboard runtime) and pass
+ * the instance to this factory.
+ *
+ * @example
+ * ```ts
+ * import { createPeriodicSyncHandler } from '@lostgradient/weft/service-worker';
+ *
+ * // In your Service Worker (with a scheduler from the runtime that imports it):
+ * declare const scheduler: { tick(): Promise<void> };
+ * const handler = createPeriodicSyncHandler(
+ *   scheduler as Parameters<typeof createPeriodicSyncHandler>[0],
+ *   'weft-timers',
+ * );
+ * // self.addEventListener('periodicsync', handler);
+ * console.log(typeof handler); // 'function'
+ * ```
+ */
+export declare function createPeriodicSyncHandler(scheduler: ServiceWorkerScheduler, tag?: string): (event: MinimalPeriodicSyncEvent) => void;
+/**
+ * Create install and activate lifecycle event handlers.
+ *
+ * - `install`: Calls `skipWaiting()` so the new Service Worker activates immediately.
+ * - `activate`: Calls `clients.claim()` so open tabs use the new Service Worker.
+ *
+ * Both handlers are defensive: when `skipWaiting` or `clients.claim` are
+ * not present on `globalThis` (e.g. when the module is imported in a unit
+ * test or an environment that is not a Service Worker scope), they silently
+ * fall back to a resolved promise so the import remains safe.
+ *
+ * @example
+ * ```ts
+ * import { createLifecycleHandlers } from '@lostgradient/weft/service-worker';
+ *
+ * const { install, activate } = createLifecycleHandlers();
+ *
+ * // In your Service Worker file:
+ * // self.addEventListener('install', install);
+ * // self.addEventListener('activate', activate);
+ * console.log(typeof install, typeof activate); // 'function function'
+ * ```
+ */
+export declare function createLifecycleHandlers(): {
+    install: (event: MinimalExtendableEvent) => void;
+    activate: (event: MinimalExtendableEvent) => void;
+};
+export { setupServiceWorker, type SetupServiceWorkerOptions, type SetupServiceWorkerResult, } from './setup.ts';