@nevescloud/pip 3.4.1 → 3.5.0

package/README.md

@@ -38,8 +38,14 @@ import { createPip, createRuntime, openai } from 'https://cdn.jsdelivr.net/npm/@
 ```
 
 ```js
-// Local — in-browser inference via transformers.js + WebGPU (different shape: no runtime, renderer is host-driven)
-import { createPip, createTransformersRenderer } from 'https://cdn.jsdelivr.net/npm/@nevescloud/pip@latest/bundle/local.esm.js';
+// Local — in-browser inference via transformers.js + WebGPU
+import { createPip, createRuntime, local } from 'https://cdn.jsdelivr.net/npm/@nevescloud/pip@latest/bundle/local.esm.js';
+
+const rt = createRuntime({ provider: local({ model: 'LiquidAI/LFM2.5-350M-ONNX' }) });
+const pip = createPip({ onSubmit: rt.onSubmit, onSlash: rt.onSlash, slashSource: rt.slashSource });
+// `createTransformersRenderer` is also exported for hosts that drive
+// a one-shot paint themselves (e.g. an offline fallback that bypasses
+// the turn loop entirely).
 ```
 
 On jsdelivr the `.esm.js` suffix is required — jsdelivr serves files by raw path, not via `package.json` exports. npm-installed consumers can use the shorter `@nevescloud/pip/bundle/anthropic` (Node ESM resolver honors the exports map). `pip/bundle.esm.js` (or `pip/bundle` via npm) is an alias for `bundle/anthropic` — the default when you haven't picked a brain. Bundles are sugar over the layered files; hosts with a different brain shape (UI only, custom provider, in-browser model) import the granular files directly. See [CONSUMERS.md](../../CONSUMERS.md) for the full entry-point list.
@@ -50,7 +56,7 @@ On jsdelivr the `.esm.js` suffix is required — jsdelivr serves files by raw pa
 |---|---|---|
 | `onSubmit(text, ctx)` | — | Required. Returns the reply string (or a promise of one). |
 | `onSlash(text)` | `null` | Legacy fallback intercept for `/`-prefixed input. Runs *after* registered commands and built-ins miss. New code should call `pip.registerSlash()` instead. |
-| `slashSource()` | built-in | Override for the autocomplete dropdown's source. By default, pip enumerates `pip.registerSlash()` registrations + built-in `/help` and `/clear`. ↑/↓ to cycle, Tab/Enter to accept, Esc to close; `complete(partial)` per-keystroke after the space supplies arg suggestions. |
+| `slashSource()` | built-in | Override for the autocomplete dropdown's source. By default, pip enumerates `pip.registerSlash()` registrations + built-in `/clear`. ↑/↓ to cycle, Enter to run, Tab to accept without submitting (use when adding args), Esc to close; `complete(partial)` per-keystroke after the space supplies arg suggestions. |
 | `introText` | `""` | Muted message shown before first turn; auto-dismisses on submit. |
 | `introDismissMs` | `7000` | How long the intro stays before fading. `0` to keep until first message. |
 | `placeholder` | `"Ask Pip…"` | Input placeholder. |
@@ -70,7 +76,7 @@ On jsdelivr the `.esm.js` suffix is required — jsdelivr serves files by raw pa
 
 ## Slash commands
 
-`pip.registerSlash({ name, handler, description?, complete? })` adds a command. Registry-first dispatch: registered commands win over built-ins so a host can override `/help` or `/clear` by registering with the same name.
+`pip.registerSlash({ name, handler, description?, complete? })` adds a command. Registry-first dispatch: registered commands win over built-ins so a host can override `/clear` by registering with the same name.
 
 ```js
 pip.registerSlash({
@@ -86,7 +92,7 @@ pip.registerSlash({
 pip.unregisterSlash("model");
 ```
 
-Handler returns `{ reply?, clearedUI?, openCompletions?, passThrough? } | null`. `null` falls through to `onSlash` (if provided) and then to the LLM. Built-ins ship `/help` (auto-lists registered + built-ins) and `/clear` (wipes pip's local history + DOM).
+Handler returns `{ reply?, clearedUI?, openCompletions?, passThrough? } | null`. `null` falls through to `onSlash` (if provided) and then to the LLM. The autocomplete dropdown is the help surface — every registered + built-in command appears with its description as the user types `/`. Built-in `/clear` wipes pip's local history + DOM.
 
 - `reply` — render as an assistant turn in chat history.
 - `clearedUI` — the handler already painted its own UI (via `startTurn`, `askInChat`, etc.); pip-core skips creating a turn.

package/bundle/local.esm.js

@@ -1,9 +1,18 @@
 // Quickstart entry — pip wired to an in-browser model in one import.
-// Re-exports the two primitives most local-renderer hosts compose.
-// Different shape from bundle/anthropic and bundle/openai: there's no
-// runtime here — the renderer is host-driven (one-shot generate),
-// not part of the turn loop. Consumers shouldn't need to know which
-// underlying library powers the renderer; that's why this entry exists.
+// Re-exports two shapes:
+//
+// * `createRuntime` + `local()` — runtime-compatible provider so local
+//   participates in `/model` alongside anthropic and openai. Same wiring
+//   pattern as bundle/anthropic and bundle/openai.
+//
+// * `createTransformersRenderer` + `splitThinking` — direct renderer for
+//   hosts that paint a one-shot reply themselves (e.g. an offline
+//   fallback that bypasses the turn loop entirely).
+//
+// Consumers shouldn't need to know which underlying library powers either
+// path — the file name signals the category (local), the export name on
+// the renderer signals the library (transformers.js).
 
 export { createPip } from '../pip-core.esm.js';
-export { createTransformersRenderer, splitThinking } from '../providers/local.esm.js';
+export { createRuntime } from '../runtime.esm.js';
+export { local, createTransformersRenderer, splitThinking } from '../providers/local.esm.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevescloud/pip",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Floating assistant bubble + panel + chat runtime. ESM, no build.",
   "type": "module",
   "main": "pip-core.esm.js",

package/pip-core.esm.js

@@ -1559,7 +1559,7 @@ export function createPip(opts = {}) {
 
   // Built-in slash-command registry. Hosts call pip.registerSlash({name,
   // description, handler, complete?}) — dispatched in submit() before
-  // built-ins (/help, /clear) and the legacy onSlash callback. Keeps the
+  // built-in /clear and the legacy onSlash callback. Keeps the
   // single mental model: one place to declare "what / commands does this
   // app expose?", and the autocomplete picks them up automatically.
   const _slashCommands = new Map();
@@ -1652,22 +1652,10 @@ export function createPip(opts = {}) {
   function defaultSlashSource() {
     const out = [];
     for (const s of _slashCommands.values()) out.push({ name: s.name, description: s.description, complete: s.complete });
-    if (!_slashCommands.has("help"))  out.push({ name: "help",  description: "list commands" });
     if (!_slashCommands.has("clear")) out.push({ name: "clear", description: "clear chat history" });
     return out;
   }
   function dispatchBuiltinSlash(cmd) {
-    if (cmd === "help" || cmd === "?") {
-      // The slash autocomplete dropdown already lists every command with
-      // its description — /help duplicating that as a chat turn was visual
-      // noise and history clutter. Reopen the dropdown in cmd-name mode
-      // instead, same surface a user gets by typing `/`.
-      input.value = "/";
-      input.setSelectionRange(1, 1);
-      input.focus();
-      updateSlashSuggest();
-      return { clearedUI: true };
-    }
     if (cmd === "clear") {
       history.length = 0;
       turns.innerHTML = "";
@@ -2091,7 +2079,7 @@ export function createPip(opts = {}) {
 
   function updateSlashSuggest() {
     // No early-return on missing slashSource — the built-in source ensures
-    // even hosts that didn't wire anything still see /help and /clear.
+    // even hosts that didn't wire anything still see /clear.
     const value = input.value;
     if (!value.startsWith("/")) return closeSlashSuggest();
     const slice = value.slice(1);
@@ -2169,19 +2157,15 @@ export function createPip(opts = {}) {
       e.preventDefault();
       closeSlashSuggest();
     } else if (e.key === "Enter") {
-      // Cmd-name mode (no space yet): accept the highlighted command and
-      // stop — user may still want to type or pick args.
-      // Arg mode (space typed): accept the highlighted arg into the input,
-      // then let the form's default Enter→submit fire so the just-mutated
-      // value lands in submit(). Without this, Enter would submit whatever
-      // partial the user had typed, losing the keyboard selection — click
-      // worked only because mousedown ran acceptSlashSuggest before submit.
-      // The early-return at the top of this handler guarantees a visible
-      // dropdown with at least one item, so accept always has a target.
-      const value = input.value;
-      const inCmdMode = value.startsWith("/") && !value.includes(" ");
-      if (inCmdMode) { e.preventDefault(); acceptSlashSuggest(); }
-      else acceptSlashSuggest();
+      // Accept the highlighted entry and submit in one keystroke — CLI
+      // command-palette convention (VS Code, shell tab+enter). Tab is the
+      // path for "accept and keep editing" — e.g. pick the command, then
+      // type args before running. The early-return at the top of this
+      // handler guarantees a visible dropdown with at least one item, so
+      // accept always has a target.
+      e.preventDefault();
+      acceptSlashSuggest();
+      form.requestSubmit();
     }
   });
 

package/providers/local.esm.js

@@ -1,30 +1,19 @@
-// In-browser model renderer using transformers.js. One-shot generate
-// (not part of pip-runtime's turn loop) — hands the host a tokenizer +
-// model loaded over WebGPU and a streaming generate() that paints into
-// a Pip turnEl. Includes the download-progress UI and a `<think>` pill
-// for reasoning models, so consumers don't reinvent either.
+// In-browser model via transformers.js + WebGPU. Two shapes ship:
 //
-// Usage:
-//   import { createTransformersRenderer } from
-//     '@nevescloud/pip/providers/local.esm.js';
+// 1. `local({ model, dtype, maxTokens, genParams })` — runtime-compatible
+//    provider, slots into `createRuntime({ models: [{ provider: local(...) }] })`
+//    next to anthropic() and openai(). Wraps the renderer below and adapts
+//    its setReplyText-callback paint into the runtime's async-generator
+//    event protocol. Use this when local should participate in `/model`.
 //
-//   const renderer = createTransformersRenderer();
-//   renderer.setModel({
-//     id: 'LiquidAI/LFM2.5-350M-ONNX',
-//     dtype: 'q4',
-//     maxTokens: 256,
-//     genParams: { temperature: 0.1, top_k: 50, repetition_penalty: 1.05 },
-//   });
-//   const text = await renderer.generate({
-//     messages,                  // chat messages array
-//     turnEl,                    // pip turnEl (download progress + <think> pill render here)
-//     setReplyText,              // pip's setReplyText
-//     signal,                    // optional AbortSignal for mid-stream cancel
-//   });
+// 2. `createTransformersRenderer()` — direct renderer for hosts that build
+//    their own one-shot paint loop (e.g. neves.cloud's offline fallback,
+//    where local isn't a /model peer but a recovery path when the relay is
+//    unreachable). Exposes `setModel` + `generate({ messages, turnEl,
+//    setReplyText, signal })` returning a Promise<text>.
 //
-// Switching models: call setModel() again with a new config — the cached
-// model+tokenizer drop and reload on the next generate(). Within a single
-// model, repeat generate() calls reuse the loaded artifacts.
+// Both share the same underlying model load (download-progress UI +
+// <think> pill rendering); the provider just adapts the call shape.
 
 import { showLoading, hideLoading } from '../pip-core.esm.js';
 
@@ -270,4 +259,49 @@ export function createTransformersRenderer() {
   };
 }
 
+// Runtime-compatible provider. The renderer streams reply text via the
+// setReplyText callback (cumulative buffer per call); we proxy that
+// callback, diff each call into a `text_delta` event, and yield events
+// the runtime's turn loop already consumes. The <think> pill mounts onto
+// turnEl directly inside the renderer — unaffected, still works.
+//
+// One pitfall handled: the renderer occasionally re-paints the same
+// buffer (no new tokens emitted between calls), so the diff guards
+// against zero-length deltas. AbortSignal flows through naturally —
+// the underlying TextStreamer throws AbortError, which we surface.
+export function local({ model, dtype = 'q4', maxTokens = 256, genParams } = {}) {
+  const renderer = createTransformersRenderer();
+  if (model) renderer.setModel({ id: model, dtype, maxTokens, genParams });
+
+  return ({ messages, signal, turnEl, setReplyText }) => (async function* () {
+    let lastFull = '';
+    const queue = [];
+    let wake = null;
+    let done = false;
+    let error = null;
+
+    const proxySetReplyText = (_el, fullText) => {
+      const delta = fullText.slice(lastFull.length);
+      lastFull = fullText;
+      if (delta) {
+        queue.push({ type: 'text_delta', text: delta });
+        wake?.();
+      }
+    };
+
+    renderer.generate({ messages, turnEl, setReplyText: proxySetReplyText, signal })
+      .then(() => { done = true; wake?.(); })
+      .catch((e) => { error = e; done = true; wake?.(); });
+
+    while (true) {
+      if (queue.length) { yield queue.shift(); continue; }
+      if (done) break;
+      await new Promise((r) => { wake = r; });
+    }
+
+    if (error) throw error;
+    yield { type: 'turn_end', stopReason: 'end_turn' };
+  })();
+}
+
 export { splitThinking };

package/runtime.esm.js

@@ -121,6 +121,12 @@ export function createRuntime({
           tools: buildToolList(),
           system: systemFn(),
           signal: abortCtrl.signal,
+          // turnEl + setReplyText let renderer-shaped providers (e.g. the
+          // local transformers wrapper) paint progress bars and <think>
+          // pills directly onto the active turn. Wire-shape providers
+          // (Anthropic, OpenAI) ignore unknown keys.
+          turnEl,
+          setReplyText,
         });
 
         const assistantContent = [];
@@ -210,8 +216,7 @@ export function createRuntime({
   }
 
   // Registry-first dispatch. Host-registered commands win over built-ins
-  // so `/help` can be overridden if a host wants different formatting.
-  // Built-in `/help` enumerates both layers so users see one combined list.
+  // so `/clear` (etc.) can be overridden if a host wants different behavior.
   function onSlash(text) {
     const slice = text.slice(1);
     const sp = slice.indexOf(' ');
@@ -255,17 +260,6 @@ export function createRuntime({
       const suffix = target.label ? ` (${target.label})` : '';
       return { reply: `Switched to \`${target.name}\`${suffix}.` };
     }
-    if (cmd === 'help' || cmd === '?') {
-      const lines = ['**Commands:**'];
-      for (const s of registeredSlash.values()) {
-        lines.push(`- \`/${s.name}\` — ${s.description || ''}`);
-      }
-      lines.push('- `/clear` — reset conversation');
-      lines.push('- `/tools` — list registered tools');
-      if (models.length) lines.push('- `/model` — list or switch active model');
-      lines.push('- `/help` — this list');
-      return { reply: lines.join('\n') };
-    }
     return null;
   }
 
@@ -281,7 +275,7 @@ export function createRuntime({
   }
 
   // Slash commands. Same shape as registerTool: name + handler are required;
-  // description and complete() are surfaced by autocomplete + /help.
+  // description and complete() are surfaced by the autocomplete dropdown.
   // handler(argsString) returns { reply?, clearedUI?, passThrough? } | null.
   function registerSlash(s) {
     if (!s || !s.name || typeof s.handler !== 'function') {
@@ -311,7 +305,6 @@ export function createRuntime({
           .filter((n) => n.toLowerCase().startsWith(partial.toLowerCase())),
       });
     }
-    out.push({ name: 'help', description: 'list commands' });
     return out;
   }
   function slashSource() {