prompt-api-polyfill 1.2.1 → 1.3.0

package/README.md

@@ -140,17 +140,6 @@ npm install prompt-api-polyfill
     apiKey: 'dummy', // Required for now by the loader
     device: 'webgpu', // 'webgpu' or 'cpu'
     dtype: 'q4f16', // Quantization level
-    env: {
-      // Optional: Pass low-level Transformers.js environment overrides
-      allowRemoteModels: false,
-      backends: {
-        onnx: {
-          wasm: {
-            wasmPaths: 'https://cdn.example.com/wasm-assets/',
-          },
-        },
-      },
-    },
   };
 
   if (!('LanguageModel' in window)) {
@@ -179,8 +168,8 @@ including:
 - `LanguageModel.create()` with options
 - `prompt()` and `promptStreaming()`
 - Multimodal inputs (text, image, audio)
-- `append()` and `measureInputUsage()`
-- Quota handling via `onquotaoverflow`
+- `append()` and `measureContextUsage()`
+- Quota handling via `oncontextwindowoverflow`
 - `clone()` and `destroy()`
 
 A simplified version of how it is wired up:
@@ -236,18 +225,6 @@ This repo ships with a template file:
   // For Transformers.js:
   "device": "webgpu",
   "dtype": "q4f16",
-
-  // Optional library-level overrides:
-  "env": {
-    "allowRemoteModels": false,
-    "backends": {
-      "onnx": {
-        "wasm": {
-          "wasmPaths": "https://cdn.example.com/wasm-assets/"
-        }
-      }
-    }
-  }
 }
 ```
 
@@ -304,17 +281,7 @@ Then open `.env.json` and fill in the values.
   "apiKey": "dummy",
   "modelName": "onnx-community/gemma-3-1b-it-ONNX-GQA",
   "device": "webgpu",
-  "dtype": "q4f16",
-  "env": {
-    "allowRemoteModels": false,
-    "backends": {
-      "onnx": {
-        "wasm": {
-          "wasmPaths": "https://cdn.example.com/wasm-assets/"
-        }
-      }
-    }
-  }
+  "dtype": "q4f16"
 }
 ```
 
@@ -337,9 +304,6 @@ Then open `.env.json` and fill in the values.
 
 - `device`: **Transformers.js only**. Either `"webgpu"` or `"cpu"`.
 - `dtype`: **Transformers.js only**. Quantization level (e.g., `"q4f16"`).
-- `env` (optional): **Transformers.js only**. A flexible object to override
-  [Transformers.js environment variables](https://huggingface.co/docs/transformers.js/api/env).
-  This is useful for specifying local `wasmPaths` or proxy settings.
 
 - `modelName` (optional): The model ID to use. If not provided, the polyfill
   uses the defaults defined in [`backends/defaults.js`](backends/defaults.js).
@@ -460,21 +424,17 @@ export default class CustomBackend extends PolyfillBackend {
 
 ### Register your backend
 
-The polyfill uses a "First-Match Priority" strategy based on global
-configuration. You need to register your backend in the `prompt-api-polyfill.js`
-file by adding it to the static `#backends` array:
+The polyfill uses an automated registration strategy. To register your new
+backend, simply run the registration script:
 
-```js
-// prompt-api-polyfill.js
-static #backends = [
-  // ... existing backends
-  {
-    config: 'CUSTOM_CONFIG', // The global object to look for on `window`
-    path: './backends/custom.js',
-  },
-];
+```bash
+npm run generate:registry
 ```
 
+This updates the `backends-registry.js` file, which the polyfill imports. The
+registry contains the configuration mapping and a dynamic loader that ensures
+compatibility with bundlers and CDNs.
+
 ### Set a default model
 
 Define the fallback model identity in `backends/defaults.js`. This is used when
@@ -490,9 +450,11 @@ export const DEFAULT_MODELS = {
 
 ### Enable local development and testing
 
-The project uses a discovery script (`scripts/list-backends.js`) to generate
-test matrices. To include your new backend in the test runner, create a
-`.env-[name].json` file (for example, `.env-custom.json`) in the root directory:
+The project uses a discovery script (`scripts/backend-discovery.js`) to generate
+test matrices and list active backends based on the presence of
+`.env-[name].json` files. To include your new backend in the test runner, create
+a `.env-[name].json` file (for example, `.env-custom.json`) in the root
+directory:
 
 ```json
 {
@@ -501,6 +463,12 @@ test matrices. To include your new backend in the test runner, create a
 }
 ```
 
+Then run the WPT generation script:
+
+```bash
+npm run generate:wpt
+```
+
 ### Verify via Web Platform Tests (WPT)
 
 The final step is ensuring compliance. Because the polyfill is spec-driven, any

package/dist/backends/transformers.js

@@ -1,74 +1,68 @@
-import { env as j, pipeline as z, TextStreamer as C } from "@huggingface/transformers";
-import { P as $, D as y } from "../chunks/defaults-CNQngzSd.js";
-class I extends $ {
+import { pipeline as z, TextStreamer as C } from "@huggingface/transformers";
+import { P as j, D as y } from "../chunks/defaults-CNQngzSd.js";
+class D extends j {
   #e;
   #t;
-  #i;
-  #o;
+  #a;
   #n;
-  constructor(o = {}) {
-    if (super(o.modelName || y.transformers.modelName), this.#i = o.device || y.transformers.device, this.#o = o.dtype || y.transformers.dtype, o.env) {
-      const t = (n, a) => {
-        for (const [l, e] of Object.entries(a))
-          e && typeof e == "object" && !Array.isArray(e) && n[l] && typeof n[l] == "object" ? t(n[l], e) : n[l] = e;
-      };
-      t(j, o.env);
-    }
+  #o;
+  constructor(n = {}) {
+    super(n.modelName || y.transformers.modelName), this.#a = n.device || y.transformers.device, this.#n = n.dtype || y.transformers.dtype;
   }
   /**
    * Loaded models can be large, so we initialize them lazily.
    * @param {EventTarget} [monitorTarget] - The event target to dispatch download progress events to.
    * @returns {Promise<Object>} The generator.
    */
-  async #s(o) {
+  async #s(n) {
     if (!this.#e) {
-      const t = /* @__PURE__ */ new Map(), n = await M(this.modelName, {
-        dtype: this.#o
+      const t = /* @__PURE__ */ new Map(), a = await $(this.modelName, {
+        dtype: this.#n
       });
-      for (const { path: e, size: r } of n)
-        t.set(e, { loaded: 0, total: r });
-      const a = (e) => {
-        if (!o)
+      for (const { path: e, size: o } of a)
+        t.set(e, { loaded: 0, total: o });
+      const i = (e) => {
+        if (!n)
           return;
-        const r = 1 / 65536, c = Math.floor(e / r) * r;
-        c <= o.__lastProgressLoaded || (o.dispatchEvent(
+        const o = 1 / 65536, c = Math.floor(e / o) * o;
+        c <= n.__lastProgressLoaded || (n.dispatchEvent(
           new ProgressEvent("downloadprogress", {
             loaded: c,
             total: 1,
             lengthComputable: !0
           })
-        ), o.__lastProgressLoaded = c);
+        ), n.__lastProgressLoaded = c);
       }, l = (e) => {
         if (e.status === "initiate")
           if (t.has(e.file)) {
-            const r = t.get(e.file);
-            e.total && (r.total = e.total);
+            const o = t.get(e.file);
+            e.total && (o.total = e.total);
           } else
             t.set(e.file, { loaded: 0, total: e.total || 0 });
         else if (e.status === "progress")
           t.has(e.file) && (t.get(e.file).loaded = e.loaded);
         else if (e.status === "done") {
           if (t.has(e.file)) {
-            const r = t.get(e.file);
-            r.loaded = r.total;
+            const o = t.get(e.file);
+            o.loaded = o.total;
           }
         } else if (e.status === "ready") {
-          a(1);
+          i(1);
           return;
         }
         if (e.status === "progress" || e.status === "done") {
-          let r = 0, c = 0;
+          let o = 0, c = 0;
           for (const { loaded: f, total: d } of t.values())
-            r += f, c += d;
+            o += f, c += d;
           if (c > 0) {
-            const f = r / c;
-            a(Math.min(f, 0.9999));
+            const f = o / c;
+            i(Math.min(f, 0.9999));
           }
         }
       };
-      a(0), this.#e = await z("text-generation", this.modelName, {
-        device: this.#i,
-        dtype: this.#o,
+      i(0), this.#e = await z("text-generation", this.modelName, {
+        device: this.#a,
+        dtype: this.#n,
         progress_callback: l
       }), this.#t = this.#e.tokenizer;
     }
@@ -79,9 +73,9 @@ class I extends $ {
    * @param {Object} options - LanguageModel options.
    * @returns {string} 'available' or 'unavailable'.
    */
-  static availability(o) {
-    if (o?.expectedInputs && Array.isArray(o.expectedInputs)) {
-      for (const t of o.expectedInputs)
+  static availability(n) {
+    if (n?.expectedInputs && Array.isArray(n.expectedInputs)) {
+      for (const t of n.expectedInputs)
         if (t.type === "audio" || t.type === "image")
           return "unavailable";
     }
@@ -94,55 +88,55 @@ class I extends $ {
    * @param {EventTarget} [monitorTarget] - The event target to dispatch download progress events to.
    * @returns {Promise<Object>} The generator.
    */
-  async createSession(o, t, n) {
-    return o.responseConstraint && console.warn(
+  async createSession(n, t, a) {
+    return n.responseConstraint && console.warn(
       "The `responseConstraint` flag isn't supported by the Transformers.js backend and was ignored."
-    ), await this.#s(n), this.generationConfig = {
+    ), await this.#s(a), this.generationConfig = {
       max_new_tokens: 512,
       // Default limit
       temperature: t.generationConfig?.temperature ?? 1,
       top_p: 1,
       do_sample: t.generationConfig?.temperature !== 0,
       return_full_text: !1
-    }, this.#n = t.systemInstruction, this.#e;
+    }, this.#o = t.systemInstruction, this.#e;
   }
-  async generateContent(o) {
-    const t = await this.#s(), n = this.#r(o), a = this.#t.apply_chat_template(n, {
+  async generateContent(n) {
+    const t = await this.#s(), a = this.#r(n), i = this.#t.apply_chat_template(a, {
       tokenize: !1,
       add_generation_prompt: !0
-    }), e = (await t(a, {
+    }), e = (await t(i, {
       ...this.generationConfig,
       add_special_tokens: !1
-    }))[0].generated_text, r = await this.countTokens(o);
-    return { text: e, usage: r };
+    }))[0].generated_text, o = await this.countTokens(n);
+    return { text: e, usage: o };
   }
-  async generateContentStream(o) {
-    const t = await this.#s(), n = this.#r(o), a = this.#t.apply_chat_template(n, {
+  async generateContentStream(n) {
+    const t = await this.#s(), a = this.#r(n), i = this.#t.apply_chat_template(a, {
       tokenize: !1,
       add_generation_prompt: !0
     }), l = [];
-    let e, r = new Promise((i) => e = i), c = !1;
-    const f = (i) => {
-      l.push(i), e && (e(), e = null);
+    let e, o = new Promise((r) => e = r), c = !1;
+    const f = (r) => {
+      l.push(r), e && (e(), e = null);
     }, d = new C(this.#t, {
       skip_prompt: !0,
       skip_special_tokens: !0,
       callback_function: f
     });
-    return t(a, {
+    return t(i, {
       ...this.generationConfig,
       add_special_tokens: !1,
       streamer: d
     }).then(() => {
       c = !0, e && (e(), e = null);
-    }).catch((i) => {
-      console.error("[Transformers.js] Generation error:", i), c = !0, e && (e(), e = null);
+    }).catch((r) => {
+      console.error("[Transformers.js] Generation error:", r), c = !0, e && (e(), e = null);
     }), (async function* () {
       for (; ; ) {
-        for (l.length === 0 && !c && (e || (r = new Promise((i) => e = i)), await r); l.length > 0; ) {
-          const i = l.shift();
+        for (l.length === 0 && !c && (e || (o = new Promise((r) => e = r)), await o); l.length > 0; ) {
+          const r = l.shift();
           yield {
-            text: () => i,
+            text: () => r,
             usageMetadata: { totalTokenCount: 0 }
           };
         }
@@ -151,67 +145,67 @@ class I extends $ {
       }
     })();
   }
-  async countTokens(o) {
+  async countTokens(n) {
     await this.#s();
-    const t = this.#r(o);
+    const t = this.#r(n);
     return this.#t.apply_chat_template(t, {
       tokenize: !0,
       add_generation_prompt: !1,
       return_tensor: !1
     }).length;
   }
-  #r(o) {
-    const t = o.map((n) => {
-      let a = n.role === "model" ? "assistant" : n.role === "system" ? "system" : "user";
-      const l = n.parts.map((e) => e.text).join("");
-      return { role: a, content: l };
+  #r(n) {
+    const t = n.map((a) => {
+      let i = a.role === "model" ? "assistant" : a.role === "system" ? "system" : "user";
+      const l = a.parts.map((e) => e.text).join("");
+      return { role: i, content: l };
     });
-    if (this.#n && !t.some((n) => n.role === "system") && t.unshift({ role: "system", content: this.#n }), this.modelName.toLowerCase().includes("gemma")) {
-      const n = t.findIndex((a) => a.role === "system");
-      if (n !== -1) {
-        const a = t[n], l = t.findIndex(
-          (e, r) => e.role === "user" && r > n
+    if (this.#o && !t.some((a) => a.role === "system") && t.unshift({ role: "system", content: this.#o }), this.modelName.toLowerCase().includes("gemma")) {
+      const a = t.findIndex((i) => i.role === "system");
+      if (a !== -1) {
+        const i = t[a], l = t.findIndex(
+          (e, o) => e.role === "user" && o > a
         );
-        l !== -1 ? (t[l].content = a.content + `
+        l !== -1 ? (t[l].content = i.content + `
 
-` + t[l].content, t.splice(n, 1)) : (a.content += `
+` + t[l].content, t.splice(a, 1)) : (i.content += `
 
-`, a.role = "user");
+`, i.role = "user");
       }
     }
     return t;
   }
 }
-async function M(g, o = {}) {
-  const { dtype: t = "q8", branch: n = "main" } = o;
-  let a = null;
-  const l = `transformers_model_files_${g}_${t}_${n}`;
+async function $(g, n = {}) {
+  const { dtype: t = "q8", branch: a = "main" } = n;
+  let i = null;
+  const l = `transformers_model_files_${g}_${t}_${a}`;
   try {
     const s = localStorage.getItem(l);
     if (s) {
-      a = JSON.parse(s);
-      const { timestamp: p, files: u } = a, v = 1440 * 60 * 1e3;
+      i = JSON.parse(s);
+      const { timestamp: p, files: u } = i, v = 1440 * 60 * 1e3;
       if (Date.now() - p < v)
         return u;
     }
   } catch (s) {
     console.warn("Failed to read from localStorage cache:", s);
   }
-  const e = `https://huggingface.co/api/models/${g}/tree/${n}?recursive=true`;
-  let r;
+  const e = `https://huggingface.co/api/models/${g}/tree/${a}?recursive=true`;
+  let o;
   try {
-    if (r = await fetch(e), !r.ok)
-      throw new Error(`Manifest fetch failed: ${r.status}`);
+    if (o = await fetch(e), !o.ok)
+      throw new Error(`Manifest fetch failed: ${o.status}`);
   } catch (s) {
-    if (a)
+    if (i)
       return console.warn(
         "Failed to fetch manifest from network, falling back to cached data (expired):",
         s
-      ), a.files;
+      ), i.files;
     throw s;
   }
-  const c = await r.json(), f = new Map(c.map((s) => [s.path, s.size])), d = [], h = (s) => f.has(s), i = (s) => h(s) ? (d.push({ path: s, size: f.get(s) }), !0) : !1;
-  i("config.json"), i("generation_config.json"), i("preprocessor_config.json"), h("tokenizer.json") ? (i("tokenizer.json"), i("tokenizer_config.json")) : (i("tokenizer_config.json"), i("special_tokens_map.json"), i("vocab.json"), i("merges.txt"), i("vocab.txt"));
+  const c = await o.json(), f = new Map(c.map((s) => [s.path, s.size])), d = [], h = (s) => f.has(s), r = (s) => h(s) ? (d.push({ path: s, size: f.get(s) }), !0) : !1;
+  r("config.json"), r("generation_config.json"), r("preprocessor_config.json"), h("tokenizer.json") ? (r("tokenizer.json"), r("tokenizer_config.json")) : (r("tokenizer_config.json"), r("special_tokens_map.json"), r("vocab.json"), r("merges.txt"), r("vocab.txt"));
   const w = "onnx";
   let m = [];
   t === "fp32" ? m = [""] : t === "quantized" ? m = ["_quantized"] : (m = [`_${t}`], t === "q8" && m.push(""));
@@ -234,11 +228,11 @@ async function M(g, o = {}) {
     (s) => s.includes("decoder_model_merged")
   ), b = _.filter((s) => !(x && s.includes("decoder_model") && !s.includes("merged")));
   for (const s of b) {
-    i(s);
+    r(s);
     const p = `${s}_data`;
-    if (i(p)) {
+    if (r(p)) {
       let u = 1;
-      for (; i(`${p}_${u}`); )
+      for (; r(`${p}_${u}`); )
         u++;
     }
   }
@@ -256,5 +250,5 @@ async function M(g, o = {}) {
   return d;
 }
 export {
-  I as default
+  D as default
 };