@ulam/halohalo 0.3.0 → 0.3.3

package/README.md

@@ -1,193 +1,212 @@
-# @ulam/halohalo
-
-AI service adapters, model configuration, and provider abstraction. Vanilla core with a React hooks adapter.
-
-Named for halo-halo, the Filipino shaved ice dessert: a mix of many things that somehow works together.
-
-## The ulam framework
-
-```text
-ulam
-├── @ulam/halohalo     mixed  : AI provider adapters  ← you are here
-├── @ulam/taho         warm   : ARIA live region announcer
-├── @ulam/sili         hot    : focus management, overlays, routing
-├── @ulam/calamansi    sour   : i18n, hooks, utilities, logic
-├── @ulam/ube          sweet  : React UI components, theming
-└── @ulam/sawsawan     bridge : wires the above together
-```
-
-## Install
-
-```bash
-npm install @ulam/halohalo
-```
-
-Peer dependencies: `fuse.js >= 7` (for search). Framework adapters add `react >= 18`, `vue >= 3`, or `@angular/core >= 17` as needed.
-
-## Supported providers
-
-- Anthropic (Claude)
-- OpenAI (GPT)
-- Google (Gemini)
-
-Bring your own API key. Keys stay in the browser via localStorage and are sent directly to the provider, never to a server.
-
-## Usage
-
-### Initialize
-
-```js
-import { initApiKeys, initModels, getAiProvider } from '@ulam/halohalo'
-
-initApiKeys({ anthropic: 'sk-ant-...', openai: 'sk-...' })
-initModels({ anthropic: 'claude-sonnet-4-6', openai: 'gpt-4o' })
-
-const provider = getAiProvider() // 'anthropic' | 'openai' | 'google'
-```
-
-### Call a provider
-
-```js
-import { createCompletion } from '@ulam/halohalo'
-
-const result = await createCompletion({
-  prompt: 'Rewrite this finding for a mobile context.',
-  systemPrompt: 'You are an accessibility audit assistant.',
-})
-```
-
-### Anthropic with tool use
-
-```js
-import { callAnthropicWithTools } from '@ulam/halohalo'
-
-const result = await callAnthropicWithTools({
-  messages,
-  tools,
-  system: 'You are an accessibility audit assistant.',
-})
-```
-
-### Agentic mode
-
-Agentic mode uses tool calling to search the corpus for similar past revisions before rewriting, matching the tone and depth of established work.
-
-```js
-import { getAgenticRefinement } from '@ulam/halohalo'
-
-const revised = await getAgenticRefinement({
-  finding,
-  notes: 'This is specific to mobile, element is a tooltip',
-})
-```
-
-### React hooks adapter
-
-```jsx
-import { useProviderConfig, useCompletion } from '@ulam/halohalo/react'
-
-function AISettings() {
-  const { provider, model, setProvider } = useProviderConfig()
-  const { complete, loading } = useCompletion()
-
-  return (
-    <button onClick={() => complete('Rewrite this for mobile.')}>
-      {loading ? 'Revising...' : 'Rewrite'}
-    </button>
-  )
-}
-```
-
-### Vue composables adapter
-
-`@ulam/halohalo/vue` provides composables that wrap the vanilla `createCompletion` and `createProviderConfig` with Vue reactivity. Loading and animating state are `readonly` refs that update as the completion runs.
-
-```js
-import { useCompletion, useProviderConfig } from '@ulam/halohalo/vue'
-import { onUnmounted } from 'vue'
-
-// In setup()
-const { loading, animating, complete, cancel, cleanup } = useCompletion()
-onUnmounted(cleanup)
-
-// loading.value and animating.value are reactive
-await complete({ prompt: 'Rewrite this for mobile.' })
-```
-
-`useProviderConfig()` returns reactive refs for `provider`, `models`, and `mode`, plus all setter functions from the vanilla config store.
-
-```js
-const { provider, setProvider } = useProviderConfig()
-// provider.value is reactive
-setProvider('openai')
-```
-
-Both composables return a `cleanup` function. Call it in `onUnmounted()` if the composable is used inside a component. For app-level use outside a component, cleanup is optional.
-
-### Angular services adapter
-
-`@ulam/halohalo/angular` provides two injectable services backed by Angular signals.
-
-**`CompletionService`** is not `providedIn: 'root'`. Each injection creates a separate completion instance with its own loading state. Provide it at the component level for scoped instances, or at the application level for a shared one.
-
-```ts
-import { CompletionService, ProviderConfigService, provideHalohalo } from '@ulam/halohalo/angular'
-
-// Application root (shared singleton):
-bootstrapApplication(AppComponent, {
-  providers: [provideHalohalo()]
-})
-
-// Or component-level (scoped per component):
-@Component({
-  providers: [CompletionService],
-  template: `
-    <button (click)="rewrite()" [disabled]="completion.loading()">
-      {{ completion.loading() ? 'Revising...' : 'Rewrite' }}
-    </button>
-  `
-})
-export class RewriteButtonComponent {
-  completion = inject(CompletionService)
-
-  async rewrite() {
-    await this.completion.complete({ prompt: 'Rewrite for mobile.' })
-  }
-}
-```
-
-`completion.loading()` and `completion.animating()` are Angular `computed` signals that work directly in templates and in `effect()` calls.
-
-**`ProviderConfigService`** is `providedIn: 'root'`, giving you one config store for the whole app.
-
-```ts
-@Component({ ... })
-export class SettingsComponent {
-  providerConfig = inject(ProviderConfigService)
-
-  // In template:
-  // {{ providerConfig.provider() }}
-  // (click)="providerConfig.setProvider('openai')"
-}
-```
-
-## Design
-
-**Bring your own key.** No proxy, no server, no account. API keys are stored in localStorage and sent directly to the provider.
-
-**Provider-agnostic core.** `createCompletion` works the same regardless of which provider is active. Switch providers without changing call sites.
-
-**Vanilla-first.** The core has no framework dependency. Import from `/react`, `/vue`, or `/angular` only when you need framework reactivity.
-
-## Subpath exports
-
-| Import | Contents |
-| ------ | -------- |
-| `@ulam/halohalo` | Vanilla core: `createCompletion`, `createProviderConfig`, `callProvider`, `callAnthropicWithTools`, `getAgenticRefinement`, `searchItems`, `makeSearchTool`, and more |
-| `@ulam/halohalo/react` | `useCompletion`, `useProviderConfig` |
-| `@ulam/halohalo/vue` | `useCompletion`, `useProviderConfig` |
-| `@ulam/halohalo/angular` | `CompletionService`, `ProviderConfigService`, `provideHalohalo` |
-
-## License
-
-MIT
+# @ulam/halohalo
+
+AI service adapters, model configuration, and provider abstraction. Vanilla core with React, Vue, and Angular adapters.
+
+Named for halo-halo, the Filipino shaved ice dessert: a mix of many things that somehow works together.
+
+## Purpose & Scope
+
+**What halohalo does:**
+
+- Provider abstraction for Anthropic, OpenAI, and Google
+- API key management (localStorage-backed, never sent to server)
+- Model selection and configuration per provider
+- Completion calls with consistent interface across providers
+- Tool calling and agentic mode for complex operations
+- Framework-agnostic vanilla core with framework adapters
+- Zero build-time provider detection or configuration
+
+**What halohalo doesn't do:**
+
+- Message history or conversation management (bring your own state)
+- Streaming response handling (returns complete results)
+- Rate limiting or retry logic (use middleware patterns for these)
+- Token counting or pricing calculation (external concerns)
+- API key validation or rotation (user responsibility)
+- Multi-user authentication or access control
+
+**Who should use halohalo:**
+
+- Apps that need multiple AI provider support with runtime switching
+- Projects storing API keys client-side (browser-only, no backend)
+- Vanilla JavaScript, React, Vue, or Angular apps using AI features
+- Applications wanting provider-agnostic completion calls
+- Teams integrating AI features without external API servers
+
+## The ulam Framework
+
+Halohalo is one of six independent packages in the ulam framework. See [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the complete framework structure and dependency graph.
+
+## Install
+
+```bash
+npm install @ulam/halohalo
+```
+
+Peer dependencies: `fuse.js >= 7` (for search). Framework adapters add `react >= 18`, `vue >= 3`, or `@angular/core >= 17` as needed.
+
+## Supported providers
+
+- Anthropic (Claude)
+- OpenAI (GPT)
+- Google (Gemini)
+
+Bring your own API key. Keys stay in the browser via localStorage and are sent directly to the provider, never to a server.
+
+## Usage
+
+### Initialize
+
+```js
+import { initApiKeys, initModels, getAiProvider } from '@ulam/halohalo'
+
+initApiKeys({ anthropic: 'sk-ant-...', openai: 'sk-...' })
+initModels({ anthropic: 'claude-sonnet-4-6', openai: 'gpt-4o' })
+
+const provider = getAiProvider() // 'anthropic' | 'openai' | 'google'
+```
+
+### Call a provider
+
+```js
+import { createCompletion } from '@ulam/halohalo'
+
+const result = await createCompletion({
+  prompt: 'Rewrite this finding for a mobile context.',
+  systemPrompt: 'You are an accessibility audit assistant.',
+})
+```
+
+### Anthropic with tool use
+
+```js
+import { callAnthropicWithTools } from '@ulam/halohalo'
+
+const result = await callAnthropicWithTools({
+  messages,
+  tools,
+  system: 'You are an accessibility audit assistant.',
+})
+```
+
+### Agentic mode
+
+Agentic mode uses tool calling to search the corpus for similar past revisions before rewriting, matching the tone and depth of established work.
+
+```js
+import { getAgenticRefinement } from '@ulam/halohalo'
+
+const revised = await getAgenticRefinement({
+  finding,
+  notes: 'This is specific to mobile, element is a tooltip',
+})
+```
+
+### React hooks adapter
+
+```jsx
+import { useProviderConfig, useCompletion } from '@ulam/halohalo/react'
+
+function AISettings() {
+  const { provider, model, setProvider } = useProviderConfig()
+  const { complete, loading } = useCompletion()
+
+  return (
+    <button onClick={() => complete('Rewrite this for mobile.')}>
+      {loading ? 'Revising...' : 'Rewrite'}
+    </button>
+  )
+}
+```
+
+### Vue composables adapter
+
+`@ulam/halohalo/vue` provides composables that wrap the vanilla `createCompletion` and `createProviderConfig` with Vue reactivity. Loading and animating state are `readonly` refs that update as the completion runs.
+
+```js
+import { useCompletion, useProviderConfig } from '@ulam/halohalo/vue'
+import { onUnmounted } from 'vue'
+
+// In setup()
+const { loading, animating, complete, cancel, cleanup } = useCompletion()
+onUnmounted(cleanup)
+
+// loading.value and animating.value are reactive
+await complete({ prompt: 'Rewrite this for mobile.' })
+```
+
+`useProviderConfig()` returns reactive refs for `provider`, `models`, and `mode`, plus all setter functions from the vanilla config store.
+
+```js
+const { provider, setProvider } = useProviderConfig()
+// provider.value is reactive
+setProvider('openai')
+```
+
+Both composables return a `cleanup` function. Call it in `onUnmounted()` if the composable is used inside a component. For app-level use outside a component, cleanup is optional.
+
+### Angular services adapter
+
+`@ulam/halohalo/angular` provides two injectable services backed by Angular signals.
+
+**`CompletionService`** is not `providedIn: 'root'`. Each injection creates a separate completion instance with its own loading state. Provide it at the component level for scoped instances, or at the application level for a shared one.
+
+```ts
+import { CompletionService, ProviderConfigService, provideHalohalo } from '@ulam/halohalo/angular'
+
+// Application root (shared singleton):
+bootstrapApplication(AppComponent, {
+  providers: [provideHalohalo()]
+})
+
+// Or component-level (scoped per component):
+@Component({
+  providers: [CompletionService],
+  template: `
+    <button (click)="rewrite()" [disabled]="completion.loading()">
+      {{ completion.loading() ? 'Revising...' : 'Rewrite' }}
+    </button>
+  `
+})
+export class RewriteButtonComponent {
+  completion = inject(CompletionService)
+
+  async rewrite() {
+    await this.completion.complete({ prompt: 'Rewrite for mobile.' })
+  }
+}
+```
+
+`completion.loading()` and `completion.animating()` are Angular `computed` signals that work directly in templates and in `effect()` calls.
+
+**`ProviderConfigService`** is `providedIn: 'root'`, giving you one config store for the whole app.
+
+```ts
+@Component({ ... })
+export class SettingsComponent {
+  providerConfig = inject(ProviderConfigService)
+
+  // In template:
+  // {{ providerConfig.provider() }}
+  // (click)="providerConfig.setProvider('openai')"
+}
+```
+
+## Design
+
+**Bring your own key.** No proxy, no server, no account. API keys are stored in localStorage and sent directly to the provider.
+
+**Provider-agnostic core.** `createCompletion` works the same regardless of which provider is active. Switch providers without changing call sites.
+
+**Vanilla-first.** The core has no framework dependency. Import from `/react`, `/vue`, or `/angular` only when you need framework reactivity.
+
+## Subpath exports
+
+| Import | Contents |
+| ------ | -------- |
+| `@ulam/halohalo` | Vanilla core: `createCompletion`, `createProviderConfig`, `callProvider`, `callAnthropicWithTools`, `getAgenticRefinement`, `searchItems`, `makeSearchTool`, and more |
+| `@ulam/halohalo/react` | `useCompletion`, `useProviderConfig` |
+| `@ulam/halohalo/vue` | `useCompletion`, `useProviderConfig` |
+| `@ulam/halohalo/angular` | `CompletionService`, `ProviderConfigService`, `provideHalohalo` |
+
+See the [root README](../../README.md) for a complete framework support overview across all ulam packages.

package/agenticAiService.js

@@ -1,6 +1,5 @@
 import { callAnthropicWithTools } from './fetch.js'
 import { makeSearchTool } from './search.js'
-import { getAdapter } from '@ulam/sawsawan'
 import { AI_AGENTIC_MAX_TOKENS, AGENTIC_MAX_TOOL_TURNS, LS_APIKEY_PREFIX } from './constants.js'
 import { getAiModel } from './prefs.js'
 import { parseAiResponse } from './aiService.js'
@@ -24,6 +23,7 @@ const CORPUS_SEARCH_FIELDS = [
 const CORPUS_PICK = ['id', 'title', 'primarySC', 'severity', 'desc', 'fix']
 
 export async function getAgenticRefinement({ finding, descText, fixText, note, corpus }) {
+  const { getAdapter } = await import('@ulam/sawsawan')
   const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}anthropic`)
 
   if (!key) throw new Error('Anthropic API key required for agentic mode. Add one in Settings → AI Assist.')

package/aiService.js

@@ -1,5 +1,4 @@
 import { callProvider } from './fetch.js'
-import { getAdapter } from '@ulam/sawsawan'
 import { AI_MAX_TOKENS, AI_DESC_REGEX, AI_FIX_REGEX, LS_APIKEY_PREFIX } from './constants.js'
 import { getAiProvider, getAiModel } from './prefs.js'
 import { getBuildPrompt } from './init.js'
@@ -20,6 +19,7 @@ export async function getAiRefinement({ finding, descText, fixText, note }) {
   if (!buildPrompt) throw new Error('halohalo: call initHalohalo({ buildPrompt }) before getAiRefinement')
 
   const provider = getAiProvider()
+  const { getAdapter } = await import('@ulam/sawsawan')
   const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}${provider}`)
 
   if (!key) throw new Error(`No API key found for ${provider}. Add one in Settings.`)

package/angular.js

@@ -1,102 +1,102 @@
-/**
- * @ulam/halohalo/angular: Angular adapter
- *
- * Injectable services wrapping the vanilla halohalo core with Angular signal
- * reactivity. Provide once at the application root via provideHalohalo().
- */
-import { Injectable, signal, computed } from '@angular/core'
-import { createCompletion } from './createCompletion.js'
-import { createProviderConfig } from './createProviderConfig.js'
-
-/**
- * Service for AI completions. Each inject() call gets its own completion
- * instance; loading/animating state is per-instance.
- *
- * Usage:
- *   private completion = inject(CompletionService)
- *
- *   await this.completion.complete({ prompt: 'Rewrite for mobile.' })
- *   // this.completion.loading() is true while running
- */
-@Injectable()
-export class CompletionService {
-  #instance = createCompletion()
-  #loading = signal(false)
-  #animating = signal(false)
-
-  loading = computed(() => this.#loading())
-  animating = computed(() => this.#animating())
-
-  constructor() {
-    this.#instance.subscribe(({ loading, animating }) => {
-      this.#loading.set(loading)
-      this.#animating.set(animating)
-    })
-  }
-
-  complete(options) {
-    return this.#instance.complete(options)
-  }
-
-  cancel() {
-    this.#instance.cancel()
-  }
-
-  ngOnDestroy() {
-    this.#instance.cancel()
-  }
-}
-
-/**
- * Service for AI provider and model configuration. One config store per application.
- *
- * Usage:
- *   private providerConfig = inject(ProviderConfigService)
- *
- *   this.providerConfig.setProvider('openai')
- *   const current = this.providerConfig.provider()   // Signal<string>
- */
-@Injectable({ providedIn: 'root' })
-export class ProviderConfigService {
-  #config = createProviderConfig()
-  #provider = signal(this.#config.provider)
-  #models = signal(this.#config.models)
-  #mode = signal(this.#config.mode)
-
-  provider = computed(() => this.#provider())
-  models = computed(() => this.#models())
-  mode = computed(() => this.#mode())
-  providers = this.#config.providers
-
-  constructor() {
-    this.#config.subscribe(() => {
-      this.#provider.set(this.#config.provider)
-      this.#models.set(this.#config.models)
-      this.#mode.set(this.#config.mode)
-    })
-  }
-
-  setProvider(id) { this.#config.setProvider(id) }
-  setModel(pid, mid) { this.#config.setModel(pid, mid) }
-  setMode(v) { this.#config.setMode(v) }
-  setKey(pid, v) { return this.#config.setKey(pid, v) }
-  getKey(pid) { return this.#config.getKey(pid) }
-  getModel(pid) { return this.#config.getModel(pid) }
-  getLabel(pid) { return this.#config.getLabel(pid) }
-}
-
-/**
- * Standalone provider function. Use in bootstrapApplication() or as a
- * component-level provider when you need scoped completion instances.
- *
- * App-level (shared singleton):
- *   bootstrapApplication(AppComponent, {
- *     providers: [provideHalohalo()]
- *   })
- *
- * Component-level (scoped instance):
- *   @Component({ providers: [CompletionService] })
- */
-export function provideHalohalo() {
-  return [ProviderConfigService, CompletionService]
-}
+/**
+ * @ulam/halohalo/angular: Angular adapter
+ *
+ * Injectable services wrapping the vanilla halohalo core with Angular signal
+ * reactivity. Provide once at the application root via provideHalohalo().
+ */
+import { Injectable, signal, computed } from '@angular/core'
+import { createCompletion } from './createCompletion.js'
+import { createProviderConfig } from './createProviderConfig.js'
+
+/**
+ * Service for AI completions. Each inject() call gets its own completion
+ * instance; loading/animating state is per-instance.
+ *
+ * Usage:
+ *   private completion = inject(CompletionService)
+ *
+ *   await this.completion.complete({ prompt: 'Rewrite for mobile.' })
+ *   // this.completion.loading() is true while running
+ */
+@Injectable()
+export class CompletionService {
+  #instance = createCompletion()
+  #loading = signal(false)
+  #animating = signal(false)
+
+  loading = computed(() => this.#loading())
+  animating = computed(() => this.#animating())
+
+  constructor() {
+    this.#instance.subscribe(({ loading, animating }) => {
+      this.#loading.set(loading)
+      this.#animating.set(animating)
+    })
+  }
+
+  complete(options) {
+    return this.#instance.complete(options)
+  }
+
+  cancel() {
+    this.#instance.cancel()
+  }
+
+  ngOnDestroy() {
+    this.#instance.cancel()
+  }
+}
+
+/**
+ * Service for AI provider and model configuration. One config store per application.
+ *
+ * Usage:
+ *   private providerConfig = inject(ProviderConfigService)
+ *
+ *   this.providerConfig.setProvider('openai')
+ *   const current = this.providerConfig.provider()   // Signal<string>
+ */
+@Injectable({ providedIn: 'root' })
+export class ProviderConfigService {
+  #config = createProviderConfig()
+  #provider = signal(this.#config.provider)
+  #models = signal(this.#config.models)
+  #mode = signal(this.#config.mode)
+
+  provider = computed(() => this.#provider())
+  models = computed(() => this.#models())
+  mode = computed(() => this.#mode())
+  providers = this.#config.providers
+
+  constructor() {
+    this.#config.subscribe(() => {
+      this.#provider.set(this.#config.provider)
+      this.#models.set(this.#config.models)
+      this.#mode.set(this.#config.mode)
+    })
+  }
+
+  setProvider(id) { this.#config.setProvider(id) }
+  setModel(pid, mid) { this.#config.setModel(pid, mid) }
+  setMode(v) { this.#config.setMode(v) }
+  setKey(pid, v) { return this.#config.setKey(pid, v) }
+  getKey(pid) { return this.#config.getKey(pid) }
+  getModel(pid) { return this.#config.getModel(pid) }
+  getLabel(pid) { return this.#config.getLabel(pid) }
+}
+
+/**
+ * Standalone provider function. Use in bootstrapApplication() or as a
+ * component-level provider when you need scoped completion instances.
+ *
+ * App-level (shared singleton):
+ *   bootstrapApplication(AppComponent, {
+ *     providers: [provideHalohalo()]
+ *   })
+ *
+ * Component-level (scoped instance):
+ *   @Component({ providers: [CompletionService] })
+ */
+export function provideHalohalo() {
+  return [ProviderConfigService, CompletionService]
+}

package/createProviderConfig.js

@@ -1,5 +1,9 @@
 import { DEFAULT_MODELS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_LABELS } from './providers.js'
-import { getAdapter } from '@ulam/sawsawan'
+
+async function getAdapter() {
+  const mod = await import('@ulam/sawsawan')
+  return mod.getAdapter()
+}
 
 /**
  * Vanilla provider config store. No React required.
@@ -8,23 +12,24 @@ import { getAdapter } from '@ulam/sawsawan'
  * storageKeys: { provider, modelPrefix, keyPrefix, mode? }
  * providers: optional array of { id, label, defaultModel? }
  */
-export function createProviderConfig(storageKeys, providers = DEFAULT_PROVIDERS) {
+export async function createProviderConfig(storageKeys, providers = DEFAULT_PROVIDERS) {
   const { provider: providerKey, modelPrefix, keyPrefix, mode: modeKey } = storageKeys
+  const adapter = await getAdapter()
 
   const providerList = providers.map(p =>
     typeof p === 'string' ? { id: p, label: DEFAULT_PROVIDER_LABELS[p] || p } : p
   )
 
-  let provider = getAdapter().readPref(providerKey) || providerList[0]?.id || 'anthropic'
+  let provider = adapter.readPref(providerKey) || providerList[0]?.id || 'anthropic'
 
   let models = Object.fromEntries(
     providerList.map(p => [
       p.id,
-      getAdapter().readPref(`${modelPrefix}${p.id}`) || p.defaultModel || DEFAULT_MODELS[p.id] || '',
+      adapter.readPref(`${modelPrefix}${p.id}`) || p.defaultModel || DEFAULT_MODELS[p.id] || '',
     ])
   )
 
-  let mode = modeKey ? getAdapter().readPref(modeKey) === 'true' : false
+  let mode = modeKey ? adapter.readPref(modeKey) === 'true' : false
 
   const listeners = new Set()
   const notify = () => listeners.forEach(fn => fn())
@@ -36,30 +41,30 @@ export function createProviderConfig(storageKeys, providers = DEFAULT_PROVIDERS)
     get providers() { return providerList },
 
     setProvider(id) {
-      getAdapter().writePref(providerKey, id)
+      adapter.writePref(providerKey, id)
       provider = id
       notify()
     },
 
     setModel(providerId, modelId) {
-      getAdapter().writePref(`${modelPrefix}${providerId}`, modelId)
+      adapter.writePref(`${modelPrefix}${providerId}`, modelId)
       models = { ...models, [providerId]: modelId }
       notify()
     },
 
     setMode(value) {
       if (!modeKey) return
-      getAdapter().writePref(modeKey, value ? 'true' : 'false')
+      adapter.writePref(modeKey, value ? 'true' : 'false')
       mode = value
       notify()
     },
 
     async setKey(providerId, value) {
-      await getAdapter().setKey(`${keyPrefix}${providerId}`, value)
+      await adapter.setKey(`${keyPrefix}${providerId}`, value)
     },
 
     async getKey(providerId) {
-      return (await getAdapter().getKey(`${keyPrefix}${providerId}`)) || ''
+      return (await adapter.getKey(`${keyPrefix}${providerId}`)) || ''
     },
 
     getModel(providerId) {

package/fetch.js

@@ -1,5 +1,22 @@
 import { AiApiError, httpStatusToErrorType, PROVIDER_CONFIGS } from './providers.js'
 
+// ─── Provider URL Whitelist ───────────────────────────────────────────────────
+// Prevents SSRF attacks from user-configured provider URLs.
+const ALLOWED_PROVIDER_HOSTS = new Set([
+  'api.anthropic.com',
+  'api.openai.com',
+  'generativelanguage.googleapis.com',
+])
+
+function validateProviderUrl(url) {
+  try {
+    const hostname = new URL(url).hostname
+    return ALLOWED_PROVIDER_HOSTS.has(hostname)
+  } catch {
+    return false
+  }
+}
+
 // ─── callProvider ─────────────────────────────────────────────────────────────
 // Single-turn completion against any configured provider.
 // Returns the response text string.
@@ -13,7 +30,11 @@ export async function callProvider({ provider, model, key, prompt, maxTokens = 1
     url = config.buildUrl(key, model)
     if (!url) throw new AiApiError('api_error', { provider })
   } else {
-    url = config.url
+    url = config.url.replace('{model}', model)
+  }
+
+  if (!validateProviderUrl(url)) {
+    throw new AiApiError('api_error', { provider })
   }
 
   let res

package/models.js

@@ -1,5 +1,7 @@
-import { getAdapter } from '@ulam/sawsawan'
 import { LS_AI_MODEL_PREFIX, LS_APIKEY_PREFIX, DEFAULT_AI_MODELS } from './constants.js'
+import { getAdapter } from '@ulam/sawsawan'
+
+const _adapter = getAdapter()
 
 export const PROVIDERS = [
   { id: 'anthropic', label: 'Anthropic (Claude)', placeholderKey: 'settings.api_placeholder_anthropic' },
@@ -27,12 +29,12 @@ export const PROVIDER_MODELS = {
 
 export function initModels() {
   return Object.fromEntries(
-    PROVIDERS.map(p => [p.id, getAdapter().readPref(`${LS_AI_MODEL_PREFIX}${p.id}`) || DEFAULT_AI_MODELS[p.id] || ''])
+    PROVIDERS.map(p => [p.id, _adapter.readPref(`${LS_AI_MODEL_PREFIX}${p.id}`) || DEFAULT_AI_MODELS[p.id] || ''])
   )
 }
 
 export function initApiKeys() {
   return Object.fromEntries(
-    PROVIDERS.map(p => [p.id, window.electronAPI ? '' : getAdapter().readPref(`${LS_APIKEY_PREFIX}${p.id}`) || ''])
+    PROVIDERS.map(p => [p.id, window.electronAPI ? '' : _adapter.readPref(`${LS_APIKEY_PREFIX}${p.id}`) || ''])
   )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulam/halohalo",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "AI service adapters, model configuration, and provider abstraction.",
   "type": "module",
   "license": "MIT",

package/providers.js

@@ -60,9 +60,11 @@ export const PROVIDER_CONFIGS = {
   },
 
   google: {
-    buildUrl: (key, model) =>
-      `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${key}`,
-    buildHeaders: () => ({ 'Content-Type': 'application/json' }),
+    url: 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent',
+    buildHeaders: (key) => ({
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${key}`,
+    }),
     buildBody: (prompt, _model, maxTokens) => JSON.stringify({
       contents: [{ parts: [{ text: prompt }] }],
       generationConfig: { maxOutputTokens: maxTokens },

package/useProviderConfig.js

@@ -1,16 +1,21 @@
-import { useState, useCallback, useEffect } from 'react'
+import { useState, useCallback, useSyncExternalStore } from 'react'
 import { createProviderConfig } from './createProviderConfig.js'
 
 export function useProviderConfig(storageKeys, providers) {
   const [config] = useState(() => createProviderConfig(storageKeys, providers))
-  const [, rerender] = useState(0)
-  useEffect(() => config.subscribe(() => rerender(n => n + 1)), [config])
+
+  const snapshot = useSyncExternalStore(
+    (listen) => config.subscribe(listen),
+    () => ({
+      provider: config.provider,
+      models: config.models,
+      mode: config.mode,
+      providers: config.providers,
+    })
+  )
 
   return {
-    provider: config.provider,
-    models: config.models,
-    mode: config.mode,
-    providers: config.providers,
+    ...snapshot,
     setProvider: useCallback((id) => config.setProvider(id), [config]),
     setModel: useCallback((pid, mid) => config.setModel(pid, mid), [config]),
     setMode: useCallback((v) => config.setMode(v), [config]),

package/vue.js

@@ -1,73 +1,73 @@
-/**
- * @ulam/halohalo/vue: Vue composables adapter
- */
-import { ref, readonly } from 'vue'
-import { createCompletion } from './createCompletion.js'
-import { createProviderConfig } from './createProviderConfig.js'
-
-/**
- * Reactive wrapper around createCompletion(). Returns reactive loading and
- * animating state, plus complete() and cancel() functions.
- *
- * @param {object} [defaultOptions] - default options merged into every complete() call
- */
-export function useCompletion(defaultOptions = {}) {
-  const instance = createCompletion()
-  const loading = ref(false)
-  const animating = ref(false)
-
-  const unsubscribe = instance.subscribe(({ loading: l, animating: a }) => {
-    loading.value = l
-    animating.value = a
-  })
-
-  // caller should invoke cleanup() in onUnmounted if used inside a component
-  function cleanup() {
-    instance.cancel()
-    unsubscribe()
-  }
-
-  return {
-    loading: readonly(loading),
-    animating: readonly(animating),
-    complete: (callOptions) => instance.complete({ ...defaultOptions, ...callOptions }),
-    cancel: () => instance.cancel(),
-    cleanup,
-  }
-}
-
-/**
- * Reactive wrapper around createProviderConfig(). All config fields are reactive
- * refs; setters update the underlying singleton and trigger re-reads.
- *
- * @param {object} [storageKeys]
- * @param {Array}  [providers]
- */
-export function useProviderConfig(storageKeys, providers) {
-  const config = createProviderConfig(storageKeys, providers)
-
-  const provider = ref(config.provider)
-  const models = ref(config.models)
-  const mode = ref(config.mode)
-
-  const unsubscribe = config.subscribe(() => {
-    provider.value = config.provider
-    models.value = config.models
-    mode.value = config.mode
-  })
-
-  return {
-    provider: readonly(provider),
-    models: readonly(models),
-    mode: readonly(mode),
-    providers: config.providers,
-    setProvider: (id) => config.setProvider(id),
-    setModel: (pid, mid) => config.setModel(pid, mid),
-    setMode: (v) => config.setMode(v),
-    setKey: (pid, v) => config.setKey(pid, v),
-    getKey: (pid) => config.getKey(pid),
-    getModel: (pid) => config.getModel(pid),
-    getLabel: (pid) => config.getLabel(pid),
-    cleanup: unsubscribe,
-  }
-}
+/**
+ * @ulam/halohalo/vue: Vue composables adapter
+ */
+import { ref, readonly } from 'vue'
+import { createCompletion } from './createCompletion.js'
+import { createProviderConfig } from './createProviderConfig.js'
+
+/**
+ * Reactive wrapper around createCompletion(). Returns reactive loading and
+ * animating state, plus complete() and cancel() functions.
+ *
+ * @param {object} [defaultOptions] - default options merged into every complete() call
+ */
+export function useCompletion(defaultOptions = {}) {
+  const instance = createCompletion()
+  const loading = ref(false)
+  const animating = ref(false)
+
+  const unsubscribe = instance.subscribe(({ loading: l, animating: a }) => {
+    loading.value = l
+    animating.value = a
+  })
+
+  // caller should invoke cleanup() in onUnmounted if used inside a component
+  function cleanup() {
+    instance.cancel()
+    unsubscribe()
+  }
+
+  return {
+    loading: readonly(loading),
+    animating: readonly(animating),
+    complete: (callOptions) => instance.complete({ ...defaultOptions, ...callOptions }),
+    cancel: () => instance.cancel(),
+    cleanup,
+  }
+}
+
+/**
+ * Reactive wrapper around createProviderConfig(). All config fields are reactive
+ * refs; setters update the underlying singleton and trigger re-reads.
+ *
+ * @param {object} [storageKeys]
+ * @param {Array}  [providers]
+ */
+export function useProviderConfig(storageKeys, providers) {
+  const config = createProviderConfig(storageKeys, providers)
+
+  const provider = ref(config.provider)
+  const models = ref(config.models)
+  const mode = ref(config.mode)
+
+  const unsubscribe = config.subscribe(() => {
+    provider.value = config.provider
+    models.value = config.models
+    mode.value = config.mode
+  })
+
+  return {
+    provider: readonly(provider),
+    models: readonly(models),
+    mode: readonly(mode),
+    providers: config.providers,
+    setProvider: (id) => config.setProvider(id),
+    setModel: (pid, mid) => config.setModel(pid, mid),
+    setMode: (v) => config.setMode(v),
+    setKey: (pid, v) => config.setKey(pid, v),
+    getKey: (pid) => config.getKey(pid),
+    getModel: (pid) => config.getModel(pid),
+    getLabel: (pid) => config.getLabel(pid),
+    cleanup: unsubscribe,
+  }
+}