semantic-state-estimator 1.0.0

package/README.md

@@ -0,0 +1,265 @@
+# semantic-state-estimator
+
+[![npm version](https://img.shields.io/npm/v/semantic-state-estimator?style=flat-square)](https://www.npmjs.com/package/semantic-state-estimator)
+[![license](https://img.shields.io/npm/l/semantic-state-estimator?style=flat-square)](LICENSE)
+[![node](https://img.shields.io/node/v/semantic-state-estimator?style=flat-square)](https://nodejs.org)
+
+**Bridge the gap between boolean UI state and semantic AI intent — all inside a WebWorker, on-device, zero-latency.**  
+Instead of asking *"did the user click?"*, this library asks *"what does the user **mean**?"* — fusing local text embeddings with Exponential Moving Average (EMA) to build a living, drifting semantic context of your entire session.
+
+## Installation
+
+```bash
+npm install semantic-state-estimator
+```
+
+> **Peer dependencies:** `react >=18` and/or `zustand >=4` are optional — only install what you need.
+
+---
+
+## Quick Start
+
+### 1. Initialize the `SemanticStateEngine`
+
+```typescript
+import { WorkerManager, SemanticStateEngine } from 'semantic-state-estimator';
+
+// The worker uses import.meta.url so Webpack 5 and Vite resolve the path correctly.
+const workerManager = new WorkerManager();
+
+const engine = new SemanticStateEngine({
+  provider: workerManager,
+  alpha: 0.5,           // Balanced EMA decay — see "Tuning the Math" below
+  driftThreshold: 0.75, // Fire onDriftDetected when similarity drops below this
+  onDriftDetected: (vector, driftScore) => {
+    console.log(`Semantic drift detected! Score: ${driftScore.toFixed(3)}`);
+  },
+});
+
+// Feed events into the engine — it runs inside the WebWorker, never blocks your UI
+await engine.update('user opened the billing settings');
+await engine.update('user clicked "cancel subscription"');
+
+const snapshot = engine.getSnapshot();
+console.log(snapshot.semanticSummary); // "stable" | "drifting" | "volatile"
+```
+
+### 2. Wrap a Zustand Store
+
+```typescript
+import { create } from 'zustand';
+import { semanticMiddleware } from 'semantic-state-estimator/zustand';
+import { WorkerManager, SemanticStateEngine } from 'semantic-state-estimator';
+
+type AppState = {
+  page: string;
+  cartItems: number;
+  setPage: (page: string) => void;
+  addToCart: () => void;
+};
+
+const workerManager = new WorkerManager();
+const engine = new SemanticStateEngine({ provider: workerManager, alpha: 0.5, driftThreshold: 0.75 });
+
+// Wrap your store creator with semanticMiddleware
+export const useAppStore = create<AppState>(
+  semanticMiddleware(
+    engine,
+    // Map each state transition to a semantic string — return null to skip
+    (next, prev) => {
+      if (next.page !== prev.page) return `user navigated to ${next.page}`;
+      if (next.cartItems > prev.cartItems) return 'user added item to cart';
+      return null;
+    },
+    (set) => ({
+      page: 'home',
+      cartItems: 0,
+      setPage: (page) => set({ page }),
+      addToCart: () => set((s) => ({ cartItems: s.cartItems + 1 })),
+    }),
+  ),
+);
+```
+
+---
+
+## Tuning the Math: The EMA α (Decay) Weight
+
+The `alpha` parameter controls how quickly new events override the session history.
+
+| α value | Behavior | Best for |
+|---------|-----------|----------|
+| `0.1` | **Slow drift, highly stable.** Requires many consistent events to shift the state. Past context dominates. | Long-running sessions, background intent tracking |
+| `0.5` | **Balanced.** Responds well to recent events while still remembering session history. | General-purpose apps, e-commerce, dashboards |
+| `0.9` | **Highly reactive.** Almost instantly forgets past context in favour of the latest event. | Real-time chat, game UIs, live coding tools |
+
+The EMA formula applied on every `engine.update(text)` call:
+
+```
+S_t = α · E_t + (1 − α) · S_{t−1}
+```
+
+Where `E_t` is the embedding of the incoming event and `S_{t−1}` is the previous state vector.
+
+---
+
+## The Drift Callback
+
+The `onDriftDetected` callback fires **before** EMA fusion is applied, giving you a chance to react to a sharp semantic shift — e.g. a user suddenly switching from "browsing products" to "requesting a refund".
+
+### With `SemanticStateEngine` directly
+
+```typescript
+const engine = new SemanticStateEngine({
+  provider: workerManager,
+  alpha: 0.5,
+  driftThreshold: 0.75,
+  onDriftDetected: (vector, driftScore) => {
+    // driftScore = 1 − cosine_similarity ∈ [0, 2]
+    if (driftScore > 0.8) {
+      showModal('We noticed your focus shifted. Can we help?');
+    }
+  },
+});
+```
+
+### With the React `useSemanticState` Hook
+
+```tsx
+import { useSemanticState } from 'semantic-state-estimator/react';
+import { useEffect, useState } from 'react';
+
+function SemanticStatusBanner({ engine }) {
+  const [showDriftModal, setShowDriftModal] = useState(false);
+  const snapshot = useSemanticState(engine); // re-renders on every engine.update()
+
+  useEffect(() => {
+    if (snapshot.semanticSummary === 'volatile') {
+      setShowDriftModal(true);
+    }
+  }, [snapshot.semanticSummary]);
+
+  return (
+    <>
+      <div>Health: {(snapshot.healthScore * 100).toFixed(0)}%</div>
+      <div>State: {snapshot.semanticSummary}</div>
+      {showDriftModal && (
+        <Modal onClose={() => setShowDriftModal(false)}>
+          Your session intent has shifted significantly. Need help?
+        </Modal>
+      )}
+    </>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### `new WorkerManager(workerUrl?, modelName?)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `workerUrl` | `string \| URL` | `new URL('./embedding.worker.js', import.meta.url)` | Location of the compiled worker file |
+| `modelName` | `string` | `"Xenova/all-MiniLM-L6-v2"` | HuggingFace model for text embeddings |
+
+### `new SemanticStateEngine(config)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `provider` | `EmbeddingProvider` | *(required)* | Provides async embedding vectors. `WorkerManager` satisfies this interface out of the box; you can also pass a custom OpenAI, Ollama, or any other wrapper. |
+| `alpha` | `number` | — | EMA decay factor α ∈ (0, 1] |
+| `driftThreshold` | `number` | — | Cosine similarity below which drift fires |
+| `onDriftDetected` | `(vector, driftScore) => void` | `undefined` | Callback on semantic drift |
+| `modelName` | `string` | `"Xenova/all-MiniLM-L6-v2"` | Model name (informational) |
+
+### `engine.getSnapshot()` → `Snapshot`
+
+```typescript
+{
+  vector: number[];         // Current EMA state vector
+  healthScore: number;      // Reliability [0, 1] — degrades with age and drift
+  timestamp: number;        // Unix ms of last update
+  semanticSummary: string;  // "stable" | "drifting" | "volatile"
+}
+```
+
+---
+
+## Custom Embedding Providers
+
+The `SemanticStateEngine` accepts any object that implements the `EmbeddingProvider` interface:
+
+```typescript
+import type { EmbeddingProvider } from 'semantic-state-estimator';
+
+interface EmbeddingProvider {
+  getEmbedding(text: string): Promise<Float32Array | number[]>;
+}
+```
+
+`WorkerManager` satisfies this interface automatically, so existing code continues to work. You can also write a thin wrapper to use any other embedding source:
+
+### OpenAI Provider
+
+```typescript
+import type { EmbeddingProvider } from 'semantic-state-estimator';
+
+class OpenAIProvider implements EmbeddingProvider {
+  constructor(private apiKey: string, private model = "text-embedding-3-small") {}
+
+  async getEmbedding(text: string): Promise<number[]> {
+    const res = await fetch("https://api.openai.com/v1/embeddings", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({ input: text, model: this.model })
+    });
+    const data = await res.json();
+    return data.data[0].embedding; // 1536-dimension array
+  }
+}
+
+const engine = new SemanticStateEngine({
+  alpha: 0.5,
+  driftThreshold: 0.75,
+  provider: new OpenAIProvider("sk-..."),
+});
+```
+
+### Ollama Provider
+
+```typescript
+import type { EmbeddingProvider } from 'semantic-state-estimator';
+
+class OllamaProvider implements EmbeddingProvider {
+  constructor(private model = "nomic-embed-text", private url = "http://localhost:11434") {}
+
+  async getEmbedding(text: string): Promise<number[]> {
+    const res = await fetch(`${this.url}/api/embeddings`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ model: this.model, prompt: text })
+    });
+    const data = await res.json();
+    return data.embedding; // 768-dimension array
+  }
+}
+
+const engine = new SemanticStateEngine({
+  alpha: 0.5,
+  driftThreshold: 0.75,
+  provider: new OllamaProvider(),
+});
+```
+
+> ⚠️ **Frontend / high-frequency usage warning:** The built-in `WorkerManager` runs inference locally in the browser in ~20–50 ms. If you replace it with a remote provider such as `OpenAIProvider`, every `engine.update()` call incurs a 300 ms–800 ms network round-trip. When used with `semanticMiddleware` on rapid UI state changes, requests will queue up and you may hit API rate limits quickly. Remote providers are best suited for server-side or local-desktop applications where update frequency is low.
+
+---
+
+## License
+
+MIT

package/dist/SemanticStateEngine-BP5URJOJ.d.cts

@@ -0,0 +1,108 @@
+/**
+ * A generic embedding provider contract.
+ * Any object that can return an embedding vector for a given text satisfies this interface.
+ * This includes `WorkerManager` (on-device WebWorker) as well as custom OpenAI, Ollama,
+ * or other remote-inference wrappers.
+ */
+interface EmbeddingProvider {
+    getEmbedding(text: string): Promise<Float32Array | number[]>;
+}
+/**
+ * Configuration for the SemanticStateEngine.
+ */
+interface SemanticStateEngineConfig {
+    /** EMA decay factor α ∈ (0, 1]. Higher values weight recent embeddings more. */
+    alpha: number;
+    /** Minimum cosine similarity below which drift is detected and the callback fires. */
+    driftThreshold: number;
+    /**
+     * Optional callback invoked when the incoming embedding drifts beyond the threshold.
+     * Fired *before* the EMA fusion is applied.
+     *
+     * @param vector    The incoming embedding that triggered the drift.
+     * @param driftScore Drift magnitude: 1 − cosine_similarity ∈ [0, 2].
+     */
+    onDriftDetected?: (vector: number[], driftScore: number) => void;
+    /**
+     * The embedding provider used to obtain embedding vectors asynchronously.
+     * Any object implementing `getEmbedding(text: string): Promise<Float32Array | number[]>`
+     * satisfies this interface — including `WorkerManager`, or a custom OpenAI / Ollama wrapper.
+     */
+    provider: EmbeddingProvider;
+    /**
+     * The name of the embedding model to use.
+     * Must match the modelName passed to the WorkerManager so the worker
+     * loads the correct model.
+     * @default "Xenova/all-MiniLM-L6-v2"
+     */
+    modelName?: string;
+}
+/**
+ * A point-in-time snapshot of the current semantic state.
+ */
+interface Snapshot {
+    /** The current EMA state vector. */
+    vector: number[];
+    /** Reliability indicator in [0, 1]. Degrades with age and high drift. */
+    healthScore: number;
+    /** Unix timestamp (ms) of the last state update. */
+    timestamp: number;
+    /** Human-readable description of the current state quality. */
+    semanticSummary: string;
+}
+/**
+ * SemanticStateEngine tracks the implicit semantic intent of an event stream
+ * using Exponential Moving Average (EMA) vector fusion.
+ *
+ * It fires an optional drift callback when incoming embeddings diverge
+ * significantly from the current state, and exposes a healthScore that
+ * degrades with both age and volatility.
+ */
+declare class SemanticStateEngine {
+    private readonly alpha;
+    private readonly driftThreshold;
+    private readonly onDriftDetected?;
+    private readonly provider;
+    readonly modelName: string;
+    private stateVector;
+    private lastUpdatedAt;
+    private lastDrift;
+    private updateCount;
+    private readonly listeners;
+    constructor(config: SemanticStateEngineConfig);
+    /**
+     * Obtains an embedding for `text` from the WorkerManager and fuses it into
+     * the rolling semantic state using EMA.
+     *
+     * On the first call the embedding establishes the baseline.
+     * On subsequent calls, if the cosine similarity between the current state
+     * and the new embedding falls below {@link SemanticStateEngineConfig.driftThreshold},
+     * the {@link SemanticStateEngineConfig.onDriftDetected} callback is fired
+     * *before* the EMA fusion is applied.
+     *
+     * @param text Raw text whose embedding will be fused into the state.
+     */
+    update(text: string): Promise<void>;
+    /**
+     * Subscribes to state changes. Returns an unsubscribe function.
+     * The listener is called after every successful `update`.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Returns a point-in-time snapshot of the current semantic state.
+     */
+    getSnapshot(): Snapshot;
+    /**
+     * Computes the current healthScore.
+     *
+     * Starts at 1.0 and subtracts:
+     * - An age penalty proportional to milliseconds elapsed since the last update.
+     * - A drift penalty proportional to the most recent drift magnitude.
+     *
+     * The result is clamped to [0, 1].
+     */
+    private calculateHealth;
+    private buildSummary;
+}
+
+export { type EmbeddingProvider as E, SemanticStateEngine as S, type SemanticStateEngineConfig as a, type Snapshot as b };

package/dist/SemanticStateEngine-BP5URJOJ.d.ts

@@ -0,0 +1,108 @@
+/**
+ * A generic embedding provider contract.
+ * Any object that can return an embedding vector for a given text satisfies this interface.
+ * This includes `WorkerManager` (on-device WebWorker) as well as custom OpenAI, Ollama,
+ * or other remote-inference wrappers.
+ */
+interface EmbeddingProvider {
+    getEmbedding(text: string): Promise<Float32Array | number[]>;
+}
+/**
+ * Configuration for the SemanticStateEngine.
+ */
+interface SemanticStateEngineConfig {
+    /** EMA decay factor α ∈ (0, 1]. Higher values weight recent embeddings more. */
+    alpha: number;
+    /** Minimum cosine similarity below which drift is detected and the callback fires. */
+    driftThreshold: number;
+    /**
+     * Optional callback invoked when the incoming embedding drifts beyond the threshold.
+     * Fired *before* the EMA fusion is applied.
+     *
+     * @param vector    The incoming embedding that triggered the drift.
+     * @param driftScore Drift magnitude: 1 − cosine_similarity ∈ [0, 2].
+     */
+    onDriftDetected?: (vector: number[], driftScore: number) => void;
+    /**
+     * The embedding provider used to obtain embedding vectors asynchronously.
+     * Any object implementing `getEmbedding(text: string): Promise<Float32Array | number[]>`
+     * satisfies this interface — including `WorkerManager`, or a custom OpenAI / Ollama wrapper.
+     */
+    provider: EmbeddingProvider;
+    /**
+     * The name of the embedding model to use.
+     * Must match the modelName passed to the WorkerManager so the worker
+     * loads the correct model.
+     * @default "Xenova/all-MiniLM-L6-v2"
+     */
+    modelName?: string;
+}
+/**
+ * A point-in-time snapshot of the current semantic state.
+ */
+interface Snapshot {
+    /** The current EMA state vector. */
+    vector: number[];
+    /** Reliability indicator in [0, 1]. Degrades with age and high drift. */
+    healthScore: number;
+    /** Unix timestamp (ms) of the last state update. */
+    timestamp: number;
+    /** Human-readable description of the current state quality. */
+    semanticSummary: string;
+}
+/**
+ * SemanticStateEngine tracks the implicit semantic intent of an event stream
+ * using Exponential Moving Average (EMA) vector fusion.
+ *
+ * It fires an optional drift callback when incoming embeddings diverge
+ * significantly from the current state, and exposes a healthScore that
+ * degrades with both age and volatility.
+ */
+declare class SemanticStateEngine {
+    private readonly alpha;
+    private readonly driftThreshold;
+    private readonly onDriftDetected?;
+    private readonly provider;
+    readonly modelName: string;
+    private stateVector;
+    private lastUpdatedAt;
+    private lastDrift;
+    private updateCount;
+    private readonly listeners;
+    constructor(config: SemanticStateEngineConfig);
+    /**
+     * Obtains an embedding for `text` from the WorkerManager and fuses it into
+     * the rolling semantic state using EMA.
+     *
+     * On the first call the embedding establishes the baseline.
+     * On subsequent calls, if the cosine similarity between the current state
+     * and the new embedding falls below {@link SemanticStateEngineConfig.driftThreshold},
+     * the {@link SemanticStateEngineConfig.onDriftDetected} callback is fired
+     * *before* the EMA fusion is applied.
+     *
+     * @param text Raw text whose embedding will be fused into the state.
+     */
+    update(text: string): Promise<void>;
+    /**
+     * Subscribes to state changes. Returns an unsubscribe function.
+     * The listener is called after every successful `update`.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Returns a point-in-time snapshot of the current semantic state.
+     */
+    getSnapshot(): Snapshot;
+    /**
+     * Computes the current healthScore.
+     *
+     * Starts at 1.0 and subtracts:
+     * - An age penalty proportional to milliseconds elapsed since the last update.
+     * - A drift penalty proportional to the most recent drift magnitude.
+     *
+     * The result is clamped to [0, 1].
+     */
+    private calculateHealth;
+    private buildSummary;
+}
+
+export { type EmbeddingProvider as E, SemanticStateEngine as S, type SemanticStateEngineConfig as a, type Snapshot as b };

package/dist/embedding.worker.cjs

@@ -0,0 +1,92 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/worker/embedding.worker.ts
+var embedding_worker_exports = {};
+__export(embedding_worker_exports, {
+  PipelineSingleton: () => PipelineSingleton,
+  getModelName: () => getModelName,
+  handleInitMessage: () => handleInitMessage,
+  handleMessage: () => handleMessage
+});
+module.exports = __toCommonJS(embedding_worker_exports);
+var import_transformers = require("@huggingface/transformers");
+import_transformers.env.allowLocalModels = false;
+var PipelineSingleton = class {
+  static async getInstance(modelName, progressCallback) {
+    if (this.instance === null || this.modelName !== modelName) {
+      this.modelName = modelName;
+      this.instance = (0, import_transformers.pipeline)("feature-extraction", modelName, {
+        dtype: "q8",
+        progress_callback: progressCallback
+      });
+    }
+    return this.instance;
+  }
+};
+PipelineSingleton.instance = null;
+PipelineSingleton.modelName = null;
+var currentModelName = "Xenova/all-MiniLM-L6-v2";
+function getModelName() {
+  return currentModelName;
+}
+async function handleInitMessage(event) {
+  currentModelName = event.data.modelName;
+  self.postMessage({ type: "STATUS", status: "loading" });
+  try {
+    await PipelineSingleton.getInstance(currentModelName, (data) => {
+      if (data.status === "progress" && data.file && data.progress !== void 0) {
+        self.postMessage({ type: "PROGRESS", file: data.file, progress: data.progress });
+      }
+    });
+    self.postMessage({ type: "STATUS", status: "ready" });
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    self.postMessage({ type: "STATUS", status: "failed", error });
+  }
+}
+async function handleMessage(event) {
+  const { id, text } = event.data;
+  try {
+    const extractor = await PipelineSingleton.getInstance(currentModelName);
+    const output = await extractor(text, { pooling: "mean", normalize: true });
+    const response = { type: "EMBED_RES", id, vector: output.data };
+    self.postMessage(response);
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    const response = { type: "EMBED_RES", id, vector: null, error };
+    self.postMessage(response);
+  }
+}
+self.addEventListener("message", (event) => {
+  const msg = event.data;
+  if (msg.type === "INIT") {
+    handleInitMessage(event);
+  } else {
+    handleMessage(event);
+  }
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PipelineSingleton,
+  getModelName,
+  handleInitMessage,
+  handleMessage
+});
+//# sourceMappingURL=embedding.worker.cjs.map

package/dist/embedding.worker.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/worker/embedding.worker.ts"],"sourcesContent":["import { pipeline, env } from \"@huggingface/transformers\";\nimport type { EmbeddingRequest, EmbeddingResponse, WorkerIncomingMessage, WorkerInitMessage } from \"./types.js\";\n\n// Disable local models; always load from the HuggingFace Hub.\nenv.allowLocalModels = false;\n\nexport class PipelineSingleton {\n  static instance: Promise<any> | null = null;\n  static modelName: string | null = null;\n\n  static async getInstance(modelName: string, progressCallback?: (data: any) => void) {\n    if (this.instance === null || this.modelName !== modelName) {\n      this.modelName = modelName;\n      this.instance = pipeline('feature-extraction', modelName, {\n        dtype: 'q8',\n        progress_callback: progressCallback,\n      });\n    }\n    return this.instance;\n  }\n}\n\nlet currentModelName: string = \"Xenova/all-MiniLM-L6-v2\";\n\n/** Returns the model name currently configured in the worker. */\nexport function getModelName(): string {\n  return currentModelName;\n}\n\n/**\n * Handles an INIT message: saves the model name and starts loading the pipeline,\n * broadcasting STATUS events so the main thread can track the model lifecycle.\n */\nexport async function handleInitMessage(event: MessageEvent<WorkerInitMessage>): Promise<void> {\n  currentModelName = event.data.modelName;\n  self.postMessage({ type: 'STATUS', status: 'loading' });\n  try {\n    await PipelineSingleton.getInstance(currentModelName, (data: any) => {\n      if (data.status === 'progress' && data.file && data.progress !== undefined) {\n        self.postMessage({ type: 'PROGRESS', file: data.file, progress: data.progress });\n      }\n    });\n    self.postMessage({ type: 'STATUS', status: 'ready' });\n  } catch (err) {\n    const error = err instanceof Error ? err.message : String(err);\n    self.postMessage({ type: 'STATUS', status: 'failed', error });\n  }\n}\n\n/**\n * Handles an EMBED message: runs the text through the pipeline and posts back\n * the resulting normalized 1D Float32Array.\n */\nexport async function handleMessage(event: MessageEvent<EmbeddingRequest>): Promise<void> {\n  const { id, text } = event.data;\n  try {\n    const extractor = await PipelineSingleton.getInstance(currentModelName);\n    const output = await extractor(text, { pooling: 'mean', normalize: true });\n    const response: EmbeddingResponse = { type: \"EMBED_RES\", id, vector: output.data as Float32Array };\n    self.postMessage(response);\n  } catch (err) {\n    const error = err instanceof Error ? err.message : String(err);\n    const response: EmbeddingResponse = { type: \"EMBED_RES\", id, vector: null, error };\n    self.postMessage(response);\n  }\n}\n\nself.addEventListener(\"message\", (event: Event) => {\n  const msg = (event as MessageEvent<WorkerIncomingMessage>).data;\n  if (msg.type === \"INIT\") {\n    handleInitMessage(event as MessageEvent<WorkerInitMessage>);\n  } else {\n    handleMessage(event as MessageEvent<EmbeddingRequest>);\n  }\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAA8B;AAI9B,wBAAI,mBAAmB;AAEhB,IAAM,oBAAN,MAAwB;AAAA,EAI7B,aAAa,YAAY,WAAmB,kBAAwC;AAClF,QAAI,KAAK,aAAa,QAAQ,KAAK,cAAc,WAAW;AAC1D,WAAK,YAAY;AACjB,WAAK,eAAW,8BAAS,sBAAsB,WAAW;AAAA,QACxD,OAAO;AAAA,QACP,mBAAmB;AAAA,MACrB,CAAC;AAAA,IACH;AACA,WAAO,KAAK;AAAA,EACd;AACF;AAda,kBACJ,WAAgC;AAD5B,kBAEJ,YAA2B;AAcpC,IAAI,mBAA2B;AAGxB,SAAS,eAAuB;AACrC,SAAO;AACT;AAMA,eAAsB,kBAAkB,OAAuD;AAC7F,qBAAmB,MAAM,KAAK;AAC9B,OAAK,YAAY,EAAE,MAAM,UAAU,QAAQ,UAAU,CAAC;AACtD,MAAI;AACF,UAAM,kBAAkB,YAAY,kBAAkB,CAAC,SAAc;AACnE,UAAI,KAAK,WAAW,cAAc,KAAK,QAAQ,KAAK,aAAa,QAAW;AAC1E,aAAK,YAAY,EAAE,MAAM,YAAY,MAAM,KAAK,MAAM,UAAU,KAAK,SAAS,CAAC;AAAA,MACjF;AAAA,IACF,CAAC;AACD,SAAK,YAAY,EAAE,MAAM,UAAU,QAAQ,QAAQ,CAAC;AAAA,EACtD,SAAS,KAAK;AACZ,UAAM,QAAQ,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC7D,SAAK,YAAY,EAAE,MAAM,UAAU,QAAQ,UAAU,MAAM,CAAC;AAAA,EAC9D;AACF;AAMA,eAAsB,cAAc,OAAsD;AACxF,QAAM,EAAE,IAAI,KAAK,IAAI,MAAM;AAC3B,MAAI;AACF,UAAM,YAAY,MAAM,kBAAkB,YAAY,gBAAgB;AACtE,UAAM,SAAS,MAAM,UAAU,MAAM,EAAE,SAAS,QAAQ,WAAW,KAAK,CAAC;AACzE,UAAM,WAA8B,EAAE,MAAM,aAAa,IAAI,QAAQ,OAAO,KAAqB;AACjG,SAAK,YAAY,QAAQ;AAAA,EAC3B,SAAS,KAAK;AACZ,UAAM,QAAQ,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC7D,UAAM,WAA8B,EAAE,MAAM,aAAa,IAAI,QAAQ,MAAM,MAAM;AACjF,SAAK,YAAY,QAAQ;AAAA,EAC3B;AACF;AAEA,KAAK,iBAAiB,WAAW,CAAC,UAAiB;AACjD,QAAM,MAAO,MAA8C;AAC3D,MAAI,IAAI,SAAS,QAAQ;AACvB,sBAAkB,KAAwC;AAAA,EAC5D,OAAO;AACL,kBAAc,KAAuC;AAAA,EACvD;AACF,CAAC;","names":[]}

package/dist/embedding.worker.d.cts

@@ -0,0 +1,38 @@
+/**
+ * Message contract between the Main Thread and the Worker Thread.
+ * Every message carries an `id` so responses can be mapped back to their originating Promises.
+ */
+/** An initialization message sent from the main thread to configure the worker. */
+interface WorkerInitMessage {
+    type: "INIT";
+    /** The name of the embedding model the worker should load. */
+    modelName: string;
+}
+/** A request sent from the main thread to the embedding worker. */
+interface EmbeddingRequest {
+    type: "EMBED";
+    /** UUID that uniquely identifies this request. */
+    id: string;
+    /** The raw text to embed. */
+    text: string;
+}
+
+declare class PipelineSingleton {
+    static instance: Promise<any> | null;
+    static modelName: string | null;
+    static getInstance(modelName: string, progressCallback?: (data: any) => void): Promise<any>;
+}
+/** Returns the model name currently configured in the worker. */
+declare function getModelName(): string;
+/**
+ * Handles an INIT message: saves the model name and starts loading the pipeline,
+ * broadcasting STATUS events so the main thread can track the model lifecycle.
+ */
+declare function handleInitMessage(event: MessageEvent<WorkerInitMessage>): Promise<void>;
+/**
+ * Handles an EMBED message: runs the text through the pipeline and posts back
+ * the resulting normalized 1D Float32Array.
+ */
+declare function handleMessage(event: MessageEvent<EmbeddingRequest>): Promise<void>;
+
+export { PipelineSingleton, getModelName, handleInitMessage, handleMessage };

package/dist/embedding.worker.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Message contract between the Main Thread and the Worker Thread.
+ * Every message carries an `id` so responses can be mapped back to their originating Promises.
+ */
+/** An initialization message sent from the main thread to configure the worker. */
+interface WorkerInitMessage {
+    type: "INIT";
+    /** The name of the embedding model the worker should load. */
+    modelName: string;
+}
+/** A request sent from the main thread to the embedding worker. */
+interface EmbeddingRequest {
+    type: "EMBED";
+    /** UUID that uniquely identifies this request. */
+    id: string;
+    /** The raw text to embed. */
+    text: string;
+}
+
+declare class PipelineSingleton {
+    static instance: Promise<any> | null;
+    static modelName: string | null;
+    static getInstance(modelName: string, progressCallback?: (data: any) => void): Promise<any>;
+}
+/** Returns the model name currently configured in the worker. */
+declare function getModelName(): string;
+/**
+ * Handles an INIT message: saves the model name and starts loading the pipeline,
+ * broadcasting STATUS events so the main thread can track the model lifecycle.
+ */
+declare function handleInitMessage(event: MessageEvent<WorkerInitMessage>): Promise<void>;
+/**
+ * Handles an EMBED message: runs the text through the pipeline and posts back
+ * the resulting normalized 1D Float32Array.
+ */
+declare function handleMessage(event: MessageEvent<EmbeddingRequest>): Promise<void>;
+
+export { PipelineSingleton, getModelName, handleInitMessage, handleMessage };