@nevescloud/pip 2.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonas Neves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# Pip
+
+Floating assistant bubble + panel. ESM, no build, no dependencies. The module owns DOM, CSS, open/close, turn rendering. You provide the brains.
+
+## Use
+
+```js
+import { createPip } from 'https://cdn.jsdelivr.net/npm/@nevescloud/pip@latest/pip-core.esm.js';
+
+const pip = createPip({
+  introText: 'Ask me anything.',
+  placeholder: 'Type here…',
+  async onSubmit(text, ctx) {
+    return await yourAssistant(text);
+  },
+});
+```
+
+`@latest` (above) auto-tracks new releases on next jsdelivr/SW revalidation (~7d browser cache). Pin a specific version (`@2.11.0`) for production sites where a regression is costly — npm distributions are immutable per version, safe for forever-cached CDN delivery. `@2` semver-locks the major (auto-updates minor/patch, catches breaking API changes) if you want a middle ground. See [CONSUMERS.md](../../CONSUMERS.md) for the trade-off.
+
+Or via npm: `npm install @nevescloud/pip`.
+
+## Options
+
+| Key | Default | Notes |
+|---|---|---|
+| `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. |
+| `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. |
+| `autoOpen` | `false` | Open the panel on mount. |
+| `autoOpenDelayMs` | `700` | Delay before auto-open. |
+| `maxLength` | `4000` | Input character cap. |
+| `openHotkey` | `"/"` | Global key that opens pip and prefills the input. `""` or `false` to disable. Skipped while typing in another field. |
+| `historyLimit` | `10` | Rolling history window passed to `onSubmit` via `ctx.history`. |
+| `fallbackReply` | `"Can't think right now — try again?"` | Shown when `onSubmit` returns `null` / `undefined`. Override per host to point at recovery commands you actually expose, e.g. `"Can't think right now — try \`/model tiny\`."`. |
+| `emptyReply` | `"I don't have a good answer for that — tell me more?"` | Shown when `onSubmit` returns `""`. |
+| `modelLabel` | `""` | Small pill rendered in the header strip (active backend / model name). Update via `pip.setModelLabel(label)`. |
+| `slashHint` | `true` | Render a `/` key-cap button that seeds the input + opens the slash autocomplete. Discoverable affordance; set `false` to hide. |
+| `onAbort` | `null` | Called when the user clicks the stop button while pip is responding. Wire to your "abort the in-flight LLM call" path. If omitted, the stop button still renders (visual consistency with the responding state) but click is a no-op. |
+| `mic` | `false` | See [Mic input](#mic-input) below. `true` mounts the Web Speech button with default behavior; pass `{ onChunk, onFinal }` for advanced hooks. |
+| `container` | `document.body` | Mount point. |
+| `onOpen`, `onClose` | `null` | Lifecycle hooks. |
+
+## 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.
+
+```js
+pip.registerSlash({
+  name: "model",
+  description: "switch backend",
+  complete: (partial) => ["claude", "gpt-4o"].filter(s => s.startsWith(partial)),
+  handler: (args) => {
+    setBackend(args.trim());
+    return { reply: `Switched to ${args.trim()}.` };
+  },
+});
+
+pip.unregisterSlash("model");
+```
+
+Handler returns `{ reply?, clearedUI?, 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).
+
+## Tool-using turns
+
+For hosts running multi-step LLM loops (computer-use, tool dispatch), pip's default single-reply model collapses the turn into one block and hides the step-by-step reasoning users want to see. The interleave primitives let a turn render as `[text 1] [tool pill 1] [text 2] [image] [pill 2] [final text]` in arrival order — same shape Anthropic computer-use / hatch / Codex-style UIs converge on.
+
+```js
+const pip = createPip({
+  onSubmit: async (text, { turnEl }) => {
+    let reply = null;
+    for await (const ev of llmStream(text)) {
+      if (ev.type === 'text_delta') {
+        if (!reply) reply = pip.appendReplyBubble(turnEl);
+        reply.setText(ev.fullText);
+      } else if (ev.type === 'tool_start') {
+        reply = null;  // next deltas land below the pill
+        const pill = pip.appendToolPill(turnEl, ev.name, { label: `${ev.name} …` });
+        ev.onFinish = ({ input, result, error, durationMs }) => {
+          pill.finish({ label: summarize(ev.name, result), input, result, error, durationMs });
+        };
+      } else if (ev.type === 'image') {
+        pip.appendTurnImage(turnEl, { src: ev.dataUrl, alt: ev.caption });
+        reply = null;
+      }
+    }
+    return '';  // we owned the rendering; let pip's default-reply stay hidden
+  },
+});
+```
+
+| Method | Returns | Notes |
+|---|---|---|
+| `appendToolPill(turnEl, name, { label? })` | `{ el, finish({ label?, input?, result?, error?, durationMs? }) }` | `.running` → completed/`.error` on finish. Disclosure button expands a pre with args + result (truncated at 240 chars per string). Hold the returned object across the await; pass it back to `finish()` without tracking the DOM separately. |
+| `appendReplyBubble(turnEl)` | `{ el, setText(md), setHtml(html) }` | Multi-bubble per turn. `setText` renders markdown via pip's built-in `renderMd`. `setHtml` skips escaping — sanitize first. |
+| `appendTurnImage(turnEl, { src, alt? })` | `HTMLImageElement` | Inline camera frame / screenshot. Capped at 220px tall. Lazy-loaded. |
+| `scrollToBottom()` | — | Exposed for hosts interleaving their own DOM between primitives. |
+
+## Mic input
+
+`createPip({ mic: true })` mounts a Web Speech-backed mic button next to the send button. Click toggles sticky-mode dictation: final transcripts flow through `onSubmit` exactly as if the user had typed and sent them. Escape cancels. No-speech retry with sticky-disarm after 2 consecutive flakes. No-op when Web Speech isn't supported in the current browser (no broken affordance).
+
+For advanced hosts — safety-verb instant-fire that needs sub-second response, mid-turn injection that bypasses the input field — pass an object:
+
+```js
+const pip = createPip({
+  mic: {
+    onChunk: async (text) => {
+      // Fires on every Web Speech "final chunk" before the silence-commit
+      // window. Return true to consume — pip stops the mic + clears the
+      // input. Use for instant-fire safety verbs ("stop", "halt").
+      if (isSafetyVerb(text)) { handleSafetyVerb(text); return true; }
+      return false;
+    },
+    onFinal: async (text) => {
+      // Fires on final + silence-commit. Return true if you handled the
+      // transcript yourself (e.g. injected into an already-in-flight turn);
+      // pip skips its default submit.
+      if (isMidTurn()) { injectIntoActiveTurn(text); return true; }
+      return false;
+    },
+  },
+});
+
+// Suspend/resume drive the muted visual state for events the gate can't
+// see (your TTS playback, anything else).
+pip.suspendMic();   // drops active session + lights mute icon
+pip.resumeMic();    // re-arms sticky if it was on
+
+// Programmatic toggle — useful for /voice slash:
+pip.toggleMic();
+
+// Render an inline cyan notice for mic-related status (permission, retry).
+pip.surfaceMicNotice("Didn't catch that — try again.");
+
+// Check support before showing affordances:
+if (pip.micSupported) { /* render Voice button */ }
+```
+
+## Styling
+
+CSS is auto-injected. Hosts customize via CSS variables on `:root` or any ancestor:
+
+**Colors / surfaces**
+- `--pip-surface` — panel background
+- `--pip-ink`, `--pip-ink-muted` — text colors
+- `--pip-border` — borders
+- `--pip-accent` — focus / AI-generated highlight color
+
+**Type scale** (defaults shown)
+- `--pip-t-input` — input field. Default `14px` on desktop (`pointer: fine`) and `16px` on touch (mobile floor — going below 16 makes iOS Safari zoom on focus).
+- `--pip-t-body: 14px` — assistant replies (the primary content layer)
+- `--pip-t-caption: 12px` — intro, echoed user question, code blocks
+
+Class overrides (`.pip-panel`, `.pip-input`, `.pip-bubble`, `.pip-notify`, …) work too.
+
+## Runtime + providers
+
+For a turn loop, tool dispatch, history, and an Anthropic provider, pair pip-core with `runtime.esm.js`. See [`docs/RUNTIME.md`](./docs/RUNTIME.md).
+
+## Demo
+
+Live: [jonasneves.github.io/pip/](https://jonasneves.github.io/pip/). Source: `docs/index.html`.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nevescloud/pip",
+  "version": "2.11.0",
+  "description": "Floating assistant bubble + panel + chat runtime. ESM, no build.",
+  "type": "module",
+  "main": "pip-core.esm.js",
+  "exports": {
+    ".": "./pip-core.esm.js",
+    "./pip-core.esm.js": "./pip-core.esm.js",
+    "./runtime.esm.js": "./runtime.esm.js",
+    "./providers/anthropic.esm.js": "./providers/anthropic.esm.js",
+    "./providers/openai.esm.js": "./providers/openai.esm.js",
+    "./providers/transformers.esm.js": "./providers/transformers.esm.js"
+  },
+  "files": [
+    "pip-core.esm.js",
+    "runtime.esm.js",
+    "providers/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "chat",
+    "assistant",
+    "bubble",
+    "esm",
+    "agent",
+    "claude",
+    "anthropic"
+  ],
+  "author": "Jonas Neves",
+  "license": "MIT",
+  "homepage": "https://github.com/jonasneves/pip#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonasneves/pip.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jonasneves/pip/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}