fix: load browser assets directly from Hugging Face

Ensure program IDs keep working even if the PAW site is unavailable by fetching browser metadata and assets from the Hugging Face CDN. Refresh the browser docs and examples around the email-triage-browser slug, and bump the package to 0.3.1.

Author: da03

AGENTS.md

@@ -137,11 +137,13 @@ npm install @programasweights/web
 ```javascript
 import paw from '@programasweights/web';
 
-const fn = await paw.function('programasweights/email-triage');
+const fn = await paw.function('email-triage-browser');
 const result = await fn('Urgent: server is down!');
 // result: "immediate"
 ```
 
+If you load by program ID instead of slug, browser inference depends only on Hugging Face-hosted assets at runtime.
+
 ## Authentication (optional)
 
 Sign in for higher rate limits and program naming. Everything works without it.

README.md

@@ -1,16 +1,16 @@
 # @programasweights/web
 
-Run [PAW (Programs as Weights)](https://programasweights.com) neural programs directly in the browser. No server required.
+Run [PAW (Programs as Weights)](https://programasweights.com) neural programs directly in the browser. No custom server required for inference.
 
-PAW compiles natural language specifications into tiny neural programs. This SDK runs them client-side via WebAssembly, using a shared GPT-2 base model (105 MB, cached after first load) and per-program LoRA adapters (~5 MB each).
+PAW compiles natural language specifications into tiny neural programs. This SDK runs them client-side via WebAssembly, using a shared GPT-2 base model (134 MB, cached after first load) and per-program assets (~12 MB total: ~5 MB LoRA adapter + ~7 MB prefix cache).
 
 ## Quick Start
 
 ```html
 <script type="module">
   import paw from 'https://cdn.jsdelivr.net/npm/@programasweights/web';
 
-  const fn = await paw.function('programasweights/email-triage');
+  const fn = await paw.function('email-triage-browser');
   const result = await fn('Urgent: server is down!');
   console.log(result); // "immediate"
 </script>
@@ -27,8 +27,8 @@ npm install @programasweights/web
 ```typescript
 import paw from '@programasweights/web';
 
-// Load by slug (resolves via API)
-const triage = await paw.function('programasweights/email-triage');
+// Load by slug (resolves via the PAW API)
+const triage = await paw.function('email-triage-browser');
 
 // Load by program ID (direct, no API call needed)
 const fn = await paw.function('abc123def456');
@@ -40,7 +40,7 @@ const result = await triage('Check this urgent message');
 const short = await triage('Check this', 10);
 
 // Show download progress
-const fn2 = await paw.function('programasweights/json-fixer', {
+const fn2 = await paw.function('email-triage-browser', {
   onProgress: ({ loaded, total, stage }) => {
     console.log(`${stage}: ${Math.round(loaded/total*100)}%`);
   },
@@ -52,12 +52,14 @@ await fn2.free();
 
 ## How It Works
 
-1. **First call**: downloads the GPT-2 Q6_K base model (~105 MB) and caches it in IndexedDB
-2. **Per program**: downloads only the LoRA adapter (~5 MB) from HuggingFace CDN
+1. **First call**: downloads the GPT-2 Q8_0 base model (~134 MB) and caches it in IndexedDB
+2. **Per program**: downloads the program assets (~12 MB total: ~5 MB LoRA adapter + ~7 MB prefix cache) from Hugging Face CDN
 3. **Inference**: runs entirely in the browser via WebAssembly (llama.cpp compiled to WASM)
 4. **Subsequent visits**: base model loads from cache instantly
 
-Multiple programs share one cached base model. Loading a second program is just a 5 MB download.
+Multiple programs share one cached base model. Loading a second program is just a ~12 MB download.
+
+If you load a program by content-addressable ID, the browser runtime only depends on Hugging Face-hosted assets. Slugs still need the PAW API for the initial ID lookup.
 
 ## API Reference
 
@@ -66,15 +68,15 @@ Multiple programs share one cached base model. Loading a second program is just
 Loads a PAW program and returns a callable function.
 
 **Parameters:**
-- `slugOrId` — Program slug (e.g., `"programasweights/email-triage"`) or program ID hash
+- `slugOrId` — Program slug (for example `"email-triage-browser"`) or program ID hash
 - `options.onProgress` — Callback for download progress: `({ loaded, total, stage }) => void`
 - `options.maxTokens` — Default max output tokens (default: unlimited, runs until EOS or context limit)
 - `options.temperature` — Sampling temperature, 0 = greedy (default: 0)
 
 **Returns:** `Promise<PawCallable>` — an async callable with per-call options
 
 ```typescript
-const fn = await paw.function('programasweights/email-triage');
+const fn = await paw.function('email-triage-browser');
 
 // Default: generates until EOS or context limit
 const result = await fn('Urgent: server is down!');

__tests__/e2e/browser.spec.ts

@@ -2,12 +2,12 @@
  * Browser E2E tests for @programasweights/web SDK.
  *
  * Runs real browser inference via Playwright + COOP/COEP test server.
- * Downloads the 105MB GPT-2 base model on first run (cached after).
+ * Downloads the 134MB GPT-2 base model on first run (cached after).
  */
 import { test, expect, type Page } from '@playwright/test';
 
 const TEST_URL = 'http://localhost:9876';
-const KNOWN_GPT2_HASH = '3b4e38680509be51f0ff';
+const KNOWN_GPT2_HASH = 'd34792fc9654c0a41483';
 const LOAD_TIMEOUT = 180_000;
 
 async function loadProgram(
@@ -50,8 +50,8 @@ test.beforeEach(async ({ page }) => {
 // ── Loading programs ──
 
 test.describe('Loading programs', () => {
-  test.skip('load by slug', async ({ page }) => {
-    await loadProgram(page, 'email-triage');
+  test('load by slug', async ({ page }) => {
+    await loadProgram(page, 'da03/verb-counter');
     const hasFn = await page.evaluate(() => typeof (window as any)._fn === 'function');
     expect(hasFn).toBe(true);
   });

__tests__/loader.test.ts

@@ -250,22 +250,11 @@ describe('hash detection', () => {
 // ── loadProgramAssets ──
 
 describe('loadProgramAssets', () => {
-  it('loads program detail, polls API assets, and returns runtime-aware URLs', async () => {
+  it('loads HF metadata, polls HF assets, and returns runtime-aware URLs', async () => {
     mockFetch
-      .mockResolvedValueOnce({
-        ok: true,
-        json: async () => ({
-          id: 'abc123def456',
-          spec: 'test spec',
-          interpreter: 'gpt2',
-          compiler_snapshot: 'paw-4b-gpt2-20260406',
-          runtime_id: 'gpt2-q8_0',
-          runtime_manifest_version: 1,
-          created_at: '2026-01-01T00:00:00Z',
-        }),
-      })
+      .mockResolvedValueOnce({ ok: true, status: 200 })
+      .mockResolvedValueOnce({ ok: true, json: async () => GPT2_META })
       .mockResolvedValueOnce({ ok: true, json: async () => GPT2_RUNTIME });
-      // HEAD adapter, HEAD prompt, HEAD cache, HEAD tokens, GET prompt
       [200, 200].forEach((status) => {
         mockFetch.mockResolvedValueOnce({ ok: status === 200, status });
       });
@@ -275,23 +264,20 @@ describe('loadProgramAssets', () => {
     expect(assets.meta.runtime_id).toBe('gpt2-q8_0');
     expect(assets.promptTemplate).toBe('Hello {INPUT_PLACEHOLDER}');
     expect(assets.baseModelUrl).toContain('GPT2-GGUF-Q8_0');
-    expect(assets.adapterUrl).toBe('https://programasweights.com/api/v1/programs/abc123def456/asset/adapter.gguf');
-    expect(assets.prefixCacheUrl).toBe('https://programasweights.com/api/v1/programs/abc123def456/asset/prefix_cache.bin');
-    expect(assets.prefixTokensUrl).toBe('https://programasweights.com/api/v1/programs/abc123def456/asset/prefix_tokens.json');
+    expect(assets.adapterUrl).toBe('https://huggingface.co/programasweights/paw-programs/resolve/main/abc123def456/adapter.gguf');
+    expect(assets.prefixCacheUrl).toBe('https://huggingface.co/programasweights/paw-programs/resolve/main/abc123def456/prefix_cache.bin');
+    expect(assets.prefixTokensUrl).toBe('https://huggingface.co/programasweights/paw-programs/resolve/main/abc123def456/prefix_tokens.json');
   });
 
   it('rejects runtimes without browser support', async () => {
     mockFetch
+      .mockResolvedValueOnce({ ok: true, status: 200 })
       .mockResolvedValueOnce({
         ok: true,
         json: async () => ({
-          id: 'abc123',
-          spec: 'test spec',
+          ...GPT2_META,
           interpreter: 'Qwen/Qwen3-0.6B',
-          compiler_snapshot: 'paw-4b-qwen3-0.6b-20260407',
           runtime_id: 'qwen3-0.6b-q6_k',
-          runtime_manifest_version: 1,
-          created_at: '2026-01-01T00:00:00Z',
         }),
       })
       .mockResolvedValueOnce({
@@ -321,17 +307,10 @@ describe('loadProgramAssets', () => {
 
   it('throws on prompt template fetch failure after assets are ready', async () => {
     mockFetch
+      .mockResolvedValueOnce({ ok: true, status: 200 })
       .mockResolvedValueOnce({
         ok: true,
-        json: async () => ({
-          id: 'abc123',
-          spec: 'test spec',
-          interpreter: 'gpt2',
-          compiler_snapshot: 'paw-4b-gpt2-20260406',
-          runtime_id: 'gpt2-q8_0',
-          runtime_manifest_version: 1,
-          created_at: '2026-01-01T00:00:00Z',
-        }),
+        json: async () => GPT2_META,
       })
       .mockResolvedValueOnce({ ok: true, json: async () => GPT2_RUNTIME });
       [200, 200].forEach((status) => {

examples/basic.html

@@ -25,11 +25,11 @@
 </head>
 <body>
   <h1>PAW Browser Inference</h1>
-  <p class="subtitle">Run neural programs locally in your browser — no server needed.</p>
+  <p class="subtitle">Run neural programs locally in your browser — no custom server needed for inference.</p>
 
   <div class="card">
     <label for="program">Program</label>
-    <input id="program" type="text" value="programasweights/email-triage"
+    <input id="program" type="text" value="email-triage-browser"
       style="width:100%; padding:0.75rem; border:1px solid #ddd; border-radius:8px; font-size:0.9rem;"
       placeholder="Program slug or ID">
 
@@ -68,7 +68,7 @@ <h1>PAW Browser Inference</h1>
 
       btnRun.disabled = true;
       btnRun.textContent = 'Loading model...';
-      elStatus.textContent = 'Downloading base model (first time only, ~105 MB)...';
+      elStatus.textContent = 'Downloading base model (first time only, ~134 MB)...';
 
       try {
         fn = await paw.function(slug, {

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@programasweights/web",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Run PAW (Programs as Weights) neural programs in the browser via WebAssembly",
   "type": "module",
   "main": "dist/index.js",

package.json

@@ -13,7 +13,7 @@ export function configure(config: PawConfig): void {
 /**
  * Load a PAW program for browser-side inference.
  *
- * Accepts a program ID (hash) or a slug (e.g., "email-triage").
+ * Accepts a program ID (hash) or a slug (e.g., "email-triage-browser").
  * Downloads the base GPT-2 model (~134 MB, cached after first load) and the
  * program's browser assets (~12 MB total: ~5 MB adapter + ~7 MB prefix cache).
  * Returns a callable PawCallable.
@@ -22,7 +22,7 @@ export function configure(config: PawConfig): void {
  * ```ts
  * import paw from '@programasweights/web';
  *
- * const fn = await paw.function('email-triage');
+ * const fn = await paw.function('email-triage-browser');
  * const result = await fn('Urgent: server is down!');
  * console.log(result); // "immediate"
  *

src/index.ts

@@ -2,6 +2,7 @@ import type { ProgramAssets, ProgramMeta, ProgressCallback, RuntimeBaseModel, Ru
 
 const DEFAULT_API_URL = 'https://programasweights.com/api/v1';
 const HF_BASE_URL = 'https://huggingface.co';
+const HF_PROGRAMS_REPO = 'programasweights/paw-programs';
 const ASSET_READY_TIMEOUT_MS = 60_000;
 const ASSET_READY_POLL_MS = 2_000;
 
@@ -79,11 +80,11 @@ export function getBaseModelUrl(runtime: RuntimeManifest): string {
 }
 
 function getProgramAssetUrl(programId: string, filename: string): string {
-  return `${configuredApiUrl}/programs/${encodeURIComponent(programId)}/asset/${encodeURIComponent(filename)}`;
+  return `${HF_BASE_URL}/${HF_PROGRAMS_REPO}/resolve/main/${programId}/${filename}`;
 }
 
-function getProgramUrl(programId: string): string {
-  return `${configuredApiUrl}/programs/${encodeURIComponent(programId)}`;
+function getMetaUrl(programId: string): string {
+  return getProgramAssetUrl(programId, 'meta.json');
 }
 
 function getPromptUrl(programId: string, promptFilename = 'prompt_template.txt'): string {
@@ -130,14 +131,6 @@ export async function resolveSlug(slug: string): Promise<string> {
   return data.program_id;
 }
 
-async function getProgramDetail(programId: string): Promise<any> {
-  const resp = await fetch(getProgramUrl(programId));
-  if (!resp.ok) {
-    throw new Error(`Failed to load program metadata for "${programId}": ${resp.status}`);
-  }
-  return resp.json();
-}
-
 async function waitForAssetReady(url: string, label: string, optional = false): Promise<void> {
   const deadline = Date.now() + ASSET_READY_TIMEOUT_MS;
   let lastStatus = 0;
@@ -163,25 +156,12 @@ export async function loadProgramAssets(
   programId: string,
   _onProgress?: ProgressCallback
 ): Promise<ProgramAssets> {
-  const detail = await getProgramDetail(programId);
-  const meta: ProgramMeta = {
-    version: detail.runtime_manifest_version ?? 4,
-    program_id: detail.id,
-    spec: detail.spec,
-    examples: detail.runtime?.examples ?? detail.examples,
-    interpreter: detail.interpreter,
-    compiler_snapshot: detail.compiler_snapshot,
-    compiler_fingerprint: detail.compiler_fingerprint ?? '',
-    compiler_kind: detail.compiler_kind,
-    pseudo_program_strategy: detail.pseudo_program_strategy,
-    runtime_id: detail.runtime_id,
-    runtime_manifest_version: detail.runtime_manifest_version,
-    runtime: detail.runtime,
-    lora_rank: detail.runtime?.adapter?.lora_rank ?? 0,
-    lora_alpha: detail.runtime?.adapter?.lora_alpha ?? 0,
-    prefix_steps: detail.prefix_steps ?? 0,
-    created_at: detail.created_at,
-  };
+  await waitForAssetReady(getMetaUrl(programId), 'program metadata');
+  const metaResp = await fetch(getMetaUrl(programId));
+  if (!metaResp.ok) {
+    throw new Error(`Failed to load program metadata for "${programId}": ${metaResp.status}`);
+  }
+  const meta: ProgramMeta = await metaResp.json();
   const runtime = await resolveRuntimeManifest(meta);
 
   if (!runtime.js_sdk.supported) {

src/loader.ts

@@ -26,7 +26,7 @@
 </head>
 <body>
   <h1>PAW Browser Inference Test</h1>
-  <p class="sub">Loads GPT-2 base + LoRA adapter + KV cache. First load downloads ~117 MB; subsequent loads use cache.</p>
+  <p class="sub">Loads GPT-2 base + LoRA adapter + KV cache. First load downloads ~146 MB; subsequent loads use cache.</p>
 
   <div class="card">
     <label>Program ID (GPT-2)</label>
@@ -94,7 +94,7 @@ <h1>PAW Browser Inference Test</h1>
       wllama = new Wllama(WasmPaths, { suppressNativeLog: false });
 
       // Step 1: Download base model
-      statusEl.textContent = 'Downloading GPT-2 base model (~105 MB)...';
+      statusEl.textContent = 'Downloading GPT-2 base model (~134 MB)...';
       const baseBlob = await fetchWithProgress(BASE_MODEL_URL, 'Base model');
       statusEl.textContent = 'Loading model into WASM...';
       await wllama.loadModel([baseBlob], { n_ctx: 2048 });