@kolbo/mcp 1.88.4 → 1.89.0

package/README.md

@@ -8,6 +8,10 @@ Use `list_fonts` / `get_font` to discover My Fonts. Local stdio clients upload o
 
 Only models reporting `supports_custom_fonts: true` accept these selections. Fonts and backend-generated specimens never go through media upload. See [Personal Fonts](https://docs.kolbo.ai/developer-api/personal-fonts). Availability requires a published client and deployed backend containing these tools; source changes alone do not update installed clients.
 
+## No-background images
+
+`generate_image` and `generate_image_edit` accept `background: "transparent"` for models whose `list_models` record reports `supports_transparent_background: true`. Kolbo also appends the exact phrase `no background` once to the effective prompt, while the structured setting requests the native alpha channel through the configured provider route. Use `output_format: "png"` or `"webp"` (PNG is selected automatically when omitted). Prompt wording alone is not sufficient, and unsupported models reject the request instead of silently returning an opaque image.
+
 Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).
 
 Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.
@@ -278,7 +282,9 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `generate_character_sheet` | Generate a multi-angle character sheet from reference images (credits) → pass URL to create_visual_dna or update_visual_dna |
 | `list_visual_dna_folders` / `create_visual_dna_folder` / `update_visual_dna_folder` / `delete_visual_dna_folder` / `move_visual_dna_to_folder` | Organize Visual DNA characters into user folders (create/rename/recolor/delete + move DNAs in/out) |
 | `create_project` / `update_project` / `archive_project` / `unarchive_project` | Project lifecycle (create/rename/describe/archive; deletion stays in-app) |
-| `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Custom chat agents (reusable named personas; `description` is the system instruction) |
+| `list_skills` / `create_skill` / `update_skill` / `delete_skill` | Skills — reusable named personas for the chat tool; `description` is the system instruction |
+| `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Same four tools under their original names. Still supported and unchanged; new integrations should use the `*_skill` names |
+| `create_video_editor_session` / `export_video_editor_session` | Build an editable timeline from Kolbo-hosted clips, audio and text, then export it to MP4. No new media is generated; identical snapshots reuse the same export job |
 | `get_creative_director_status` | Re-check a Creative Director batch by generation_id until all parallel scenes finish (use after a `_timed_out` Director run) |
 | `list_sessions` | Enumerate sessions across all types, filterable by project, `type`, and `types[]` |
 | `rename_session` / `delete_session` / `restore_session` | Rename a session; soft-delete leftovers after a move; restore from trash |
@@ -307,4 +313,4 @@ Both are optional — the local install logs in via the browser on first use.
 
 ### Chat thinking level
 
-`chat_send_message` accepts optional `thinking_level`, using an ID from `list_models` with `type: "text"`. The server validates it against the resolved model; omitted or invalid values use `thinkingDefault`. Existing safeguards and legacy `deep_think` take precedence. Discover allowed levels through `thinkingLevels`; no package update is required when the server changes a model capability.
+`chat_send_message` accepts optional `thinking_level`, using an ID from `list_models` with `type: "text"`. The server validates it against the resolved model; omitted or invalid values use `thinkingDefault`. Existing safeguards and legacy `deep_think` take precedence. Discover allowed levels through `thinkingLevels`; no package update is required when the server changes a model capability. For the Auto model, optional `routing_mode` accepts `fast`, `balanced`, or `smart`; omitted uses the server default of `balanced`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.88.4",
+  "version": "1.89.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/src/apps/bridge.js

@@ -36,6 +36,22 @@ const BRIDGE_JS = `
   var queue = [];        // deferred host-bound sends until initialized
   var hostContext = null;
   var readyFns = [], toolResultFns = [], themeFns = [], toolInputFns = [];
+  var latestResult, latestInput;
+  function deliver(f, args) {
+    try { f.apply(null, args); }
+    catch (e) {
+      console.error('Kolbo widget render failed', e);
+      var card = document.querySelector('.k-card');
+      var notice = document.getElementById('kolbo-render-error');
+      if (card && !notice) {
+        notice = document.createElement('div');
+        notice.id = 'kolbo-render-error';
+        notice.setAttribute('role', 'alert');
+        notice.textContent = 'This preview could not update. Your generation may still be running. Reopen this card or check your Kolbo library.';
+        card.appendChild(notice);
+      }
+    }
+  }
 
   function post(msg) { window.parent.postMessage(msg, '*'); }
 
@@ -67,11 +83,13 @@ const BRIDGE_JS = `
       return;
     }
     if (m.method === 'ui/notifications/tool-result') {
-      toolResultFns.forEach(function (f) { try { f(m.params || {}); } catch (e) {} });
+      latestResult = m.params || {};
+      toolResultFns.forEach(function (f) { deliver(f, [latestResult]); });
     } else if (m.method === 'ui/notifications/tool-input' || m.method === 'ui/notifications/tool-input-partial') {
       // Fires while the tool is still RUNNING — lets widgets show a real
       // "preparing" state instead of a blank card until the result lands.
-      toolInputFns.forEach(function (f) { try { f((m.params && m.params.arguments) || {}, m.params || {}); } catch (e) {} });
+      latestInput = [(m.params && m.params.arguments) || {}, m.params || {}];
+      toolInputFns.forEach(function (f) { deliver(f, latestInput); });
     } else if (m.method === 'ui/notifications/host-context-changed') {
       hostContext = (m.params && m.params.hostContext) || m.params || hostContext;
       themeFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
@@ -88,12 +106,13 @@ const BRIDGE_JS = `
     appInfo: { name: 'kolbo-widget', version: '1.0.0' },
     appCapabilities: {}
   }).then(function (res) {
+    if (oa) return; // A late JSON-RPC ack must not replace OpenAI host context.
     hostContext = (res && res.hostContext) || null;
     notify('ui/notifications/initialized');
     initialized = true;
     queue.forEach(post);
     queue = [];
-    readyFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
+    readyFns.forEach(function (f) { deliver(f, [hostContext]); });
   }).catch(function () { /* host without apps support — widget stays static */ });
 
   var fsMode = false; // fullscreen: the HOST owns layout — size reports there
@@ -176,9 +195,9 @@ const BRIDGE_JS = `
   document.addEventListener('loadedmetadata', function () { queueSize(60); }, true);
 
   window.kolbo = {
-    ready: function (f) { if (initialized) f(hostContext); else readyFns.push(f); },
-    onToolResult: function (f) { toolResultFns.push(f); },
-    onToolInput: function (f) { toolInputFns.push(f); },
+    ready: function (f) { if (initialized) deliver(f, [hostContext]); else readyFns.push(f); },
+    onToolResult: function (f) { toolResultFns.push(f); if (latestResult) deliver(f, [latestResult]); },
+    onToolInput: function (f) { toolInputFns.push(f); if (latestInput) deliver(f, latestInput); },
     onThemeChange: function (f) { themeFns.push(f); },
     callTool: function (name, args) { return request('tools/call', { name: name, arguments: args || {} }); },
     sendMessage: function (text) {
@@ -218,9 +237,13 @@ const BRIDGE_JS = `
   // came, and sat on "Preparing" with no prompt, no settings and no result —
   // even after the tool had returned. Everything here maps onto the same
   // callbacks the JSON-RPC path drives, so widgets need no host-specific code.
-  var oa = window.openai && typeof window.openai === 'object' ? window.openai : null;
-  if (oa) {
-    var oaInputSeen = false, oaOutputSeen = false;
+  var oa = null;
+  var oaInputSeen, oaOutputSeen;
+  function attachOpenAI(event) {
+    var current = window.openai;
+    if (!current || typeof current !== 'object') return;
+    oa = current;
+    var globals = event && event.detail && event.detail.globals;
     var oaName = function () {
       var meta = oa.toolResponseMetadata || {};
       return oa.toolName || meta['kolbo/tool'] || (oa.toolOutput && oa.toolOutput.tool) || undefined;
@@ -232,18 +255,28 @@ const BRIDGE_JS = `
       if (!initialized) {
         initialized = true;
         queue = [];
-        readyFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
+        readyFns.forEach(function (f) { deliver(f, [hostContext]); });
       } else {
         themeFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
       }
-      if (oa.toolInput && !oaInputSeen) {
-        oaInputSeen = true;
-        toolInputFns.forEach(function (f) { try { f(oa.toolInput, { name: oaName(), arguments: oa.toolInput }); } catch (e) {} });
+      var input = globals && Object.prototype.hasOwnProperty.call(globals, 'toolInput') ? globals.toolInput : oa.toolInput;
+      var output = globals && Object.prototype.hasOwnProperty.call(globals, 'toolOutput') ? globals.toolOutput : oa.toolOutput;
+      var inputKey = JSON.stringify(input);
+      var metadata = globals && globals.toolResponseMetadata || oa.toolResponseMetadata || {};
+      var envelope = metadata.call_tool_result || metadata.mcp_tool_result;
+      var result = envelope && typeof envelope === 'object' ? Object.assign({}, envelope) : {};
+      if (output != null) result.structuredContent = output;
+      result._meta = Object.assign({}, result._meta || {}, metadata);
+      var outputKey = JSON.stringify(result);
+      if (input && inputKey !== oaInputSeen) {
+        oaInputSeen = inputKey;
+        latestInput = [input, { name: oaName(), arguments: input }];
+        toolInputFns.forEach(function (f) { deliver(f, latestInput); });
       }
-      if (oa.toolOutput && !oaOutputSeen) {
-        oaOutputSeen = true;
-        var res = { structuredContent: oa.toolOutput, _meta: oa.toolResponseMetadata || {} };
-        toolResultFns.forEach(function (f) { try { f(res); } catch (e) {} });
+      if ((output || envelope) && outputKey !== oaOutputSeen) {
+        oaOutputSeen = outputKey;
+        latestResult = result;
+        toolResultFns.forEach(function (f) { deliver(f, [latestResult]); });
       }
     };
     var oaCall = function (method) { return typeof oa[method] === 'function'; };
@@ -272,13 +305,14 @@ const BRIDGE_JS = `
       if (!oaCall('requestDisplayMode')) return Promise.resolve({ mode: 'inline' });
       return Promise.resolve(oa.requestDisplayMode({ mode: mode })).then(function (r) { return { mode: (r && r.mode) || mode }; });
     };
-    window.addEventListener('openai:set_globals', oaSync);
     // Deferred: the widget's own script (which registers ready/onToolInput/
     // onToolResult) runs AFTER this bridge block in the same document, and a
     // synchronous sync here fired into empty listener lists and marked the
     // input/output as seen.
-    setTimeout(oaSync, 0);
+    oaSync();
   }
+  window.addEventListener('openai:set_globals', attachOpenAI);
+  setTimeout(attachOpenAI, 0);
 })();
 `;
 

package/src/apps/html.js

@@ -60,6 +60,8 @@ var ICONS = {
   file: _svg('<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/>'),
   copy: _svg('<rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>'),
   chevronDown: _svg('<path d="M6 9l6 6 6-6"/>'),
+  chevronLeft: _svg('<path d="M15 18l-6-6 6-6"/>'),
+  chevronRight: _svg('<path d="M9 18l6-6-6-6"/>'),
   chevronUp: _svg('<path d="M18 15l-6-6-6 6"/>')
 };
 // Media-kind → icon (accepts model kind / media_type strings).

package/src/apps/index.js

@@ -20,8 +20,8 @@ const { generationWidgetHtml } = require('./widgets/generation');
 const { mediaGridWidgetHtml } = require('./widgets/mediaGrid');
 const { catalogWidgetHtml } = require('./widgets/catalog');
 const { transcriptWidgetHtml } = require('./widgets/transcript');
-const { uploadWidgetHtml } = require('./widgets/upload');
-const { fontUploadWidgetHtml } = require('./widgets/fontUpload');
+const { uploadWidgetHtml } = require('./widgets/upload');
+const { fontUploadWidgetHtml } = require('./widgets/fontUpload');
 const { listWidgetHtml } = require('./widgets/list');
 const { HOST_MAP } = require('../cdn');
 const { plansWidgetHtml } = require('./widgets/plans');
@@ -31,8 +31,8 @@ const UI = {
   mediaGrid: 'ui://kolbo/media-grid.html',
   catalog: 'ui://kolbo/catalog.html',
   transcript: 'ui://kolbo/transcript.html',
-  upload: 'ui://kolbo/upload.html',
-  fontUpload: 'ui://kolbo/font-upload.html',
+  upload: 'ui://kolbo/upload.html',
+  fontUpload: 'ui://kolbo/font-upload.html',
   list: 'ui://kolbo/list.html',
   plans: 'ui://kolbo/plans.html',
 };
@@ -42,8 +42,8 @@ const WIDGET_BUILDERS = {
   [UI.mediaGrid]: mediaGridWidgetHtml,
   [UI.catalog]: catalogWidgetHtml,
   [UI.transcript]: transcriptWidgetHtml,
-  [UI.upload]: uploadWidgetHtml,
-  [UI.fontUpload]: fontUploadWidgetHtml,
+  [UI.upload]: uploadWidgetHtml,
+  [UI.fontUpload]: fontUploadWidgetHtml,
   [UI.list]: listWidgetHtml,
   [UI.plans]: plansWidgetHtml,
 };
@@ -734,8 +734,8 @@ const TOOL_WIDGETS = {
   // never saw it as widget-carrying. Result-level _meta alone isn't enough.
   list_color_palettes: UI.mediaGrid,
   // upload widget
-  media_upload_widget: UI.upload,
-  font_upload_widget: UI.fontUpload,
+  media_upload_widget: UI.upload,
+  font_upload_widget: UI.fontUpload,
   // generic list widget — flat record lists with no natural thumbnail
   list_projects: UI.list,
   // Must stay list.html — mapping this to generation.html mounts "Kolbo Generation /

package/src/apps/theme.js

@@ -354,18 +354,64 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
 .k-input:focus { border-color: var(--brand); box-shadow: 0 0 0 3px var(--brand-soft); }
 .k-input::placeholder { color: var(--text-faint); }
 
-/* ---- Grid widget (media / stock / presets) ---- */
-.k-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(140px, 1fr)); gap: 8px; }
-.k-cell { position: relative; border-radius: 10px; overflow: hidden; border: 1px solid var(--border);
-  background: var(--surface); cursor: pointer; transition: transform 250ms var(--spring); }
-.k-cell:hover { transform: translateY(-2px) scale(1.01); }
-.k-cell .k-cell-media { position: relative; aspect-ratio: 1; background: #000; }
-.k-cell .k-cell-media img { width: 100%; height: 100%; object-fit: contain; display: block; }
-.k-cell-play { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); }
-.k-cell .k-cell-label { padding: 6px 8px; font-size: 11px; color: var(--text-muted);
+/* ---- Paged media grid (library / stock / presets / DNAs / moodboards) ----
+   Media-first tiles: the artwork IS the row. A title rides a gradient scrim
+   INSIDE the tile instead of a text block under it, so a page of results reads
+   as a contact sheet rather than a list of captions. No backdrop-filter on the
+   scrim for the same reason .k-gen-badge has none — a dozen blurred strips over
+   a dozen images forces a per-frame backdrop re-sample on phones. */
+.k-grid { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 8px; }
+/* Narrow hosts (Kolbo Code sidebar, phone): step down instead of shrinking
+   tiles below a thumbnail worth looking at. The 520px block further down wins
+   under 520 and takes it to 2. */
+@media (max-width: 620px) { .k-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); } }
+.k-tile { position: relative; aspect-ratio: 1; border-radius: 12px; overflow: hidden;
+  border: 1px solid var(--border); background: var(--surface); cursor: pointer;
+  transition: transform 250ms var(--spring), box-shadow 250ms var(--smooth), border-color 150ms var(--smooth); }
+.k-tile:hover { transform: translateY(-2px); border-color: var(--border-strong);
+  box-shadow: 0 10px 26px rgba(0, 0, 0, 0.42); }
+.k-tile img, .k-tile video { display: block; width: 100%; height: 100%; object-fit: cover; }
+.k-tile-fb { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
+  color: var(--text-faint); font-size: 24px; }
+.k-tile-cap { position: absolute; left: 0; right: 0; bottom: 0; z-index: 2; pointer-events: none;
+  padding: 20px 8px 7px; background: linear-gradient(transparent, rgba(0, 0, 0, 0.78)); }
+.k-tile-t { font-size: 11px; font-weight: 600; color: #fff;
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-.k-cell .k-cell-sub { padding: 0 8px 7px; font-size: 10px; color: var(--text-faint);
+.k-tile-s { font-size: 10px; color: rgba(255, 255, 255, 0.66);
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+/* Hover actions, revealed on pointer devices and always-on where there is no
+   hover — a touch host must never hide the only Use affordance. */
+.k-tile-acts { position: absolute; top: 6px; right: 6px; z-index: 3; display: flex; gap: 4px;
+  opacity: 0; transition: opacity 150ms var(--smooth); }
+.k-tile:hover .k-tile-acts, .k-tile:focus-within .k-tile-acts { opacity: 1; }
+@media (hover: none) { .k-tile-acts { opacity: 1; } }
+.k-tile-act { width: 26px; height: 26px; padding: 0; border-radius: 7px;
+  border: 1px solid rgba(255, 255, 255, 0.18); background: rgba(0, 0, 0, 0.62); color: #fff;
+  display: inline-flex; align-items: center; justify-content: center; cursor: pointer;
+  transition: background 150ms var(--smooth); }
+.k-tile-act:hover { background: var(--brand); border-color: var(--brand); }
+.k-tile-play { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); z-index: 2; }
+
+/* ---- Pager (media grid + list) ----
+   A page of results at a fixed card height, instead of a card that grows a row
+   every time you ask for more. Forward past the last loaded page still goes
+   through the server's page_tool + next_args contract. */
+.k-pager { display: flex; align-items: center; justify-content: center; gap: 12px; margin-top: 12px; }
+.k-pager-btn { width: 28px; height: 28px; padding: 0; border-radius: 8px;
+  border: 1px solid var(--border); background: var(--surface-2); color: var(--text);
+  box-shadow: var(--specular); display: inline-flex; align-items: center; justify-content: center;
+  cursor: pointer; transition: background 150ms var(--smooth); }
+.k-pager-btn:hover:not(:disabled) { background: var(--border-strong); }
+.k-pager-btn:disabled { opacity: 0.3; cursor: default; }
+.k-dots { display: flex; align-items: center; gap: 6px; }
+.k-dot { width: 7px; height: 7px; padding: 0; border: 0; border-radius: 999px; cursor: pointer;
+  background: var(--text); opacity: 0.28;
+  transition: width 220ms var(--spring), opacity 150ms var(--smooth); }
+.k-dot:hover { opacity: 0.6; }
+.k-dot.on { width: 22px; opacity: 0.95; cursor: default; }
+.k-dot.ghost { cursor: default; opacity: 0.14; }
+.k-pager-label { font-size: 11px; color: var(--text-faint);
+  font-family: 'JetBrains Mono', ui-monospace, monospace; min-width: 58px; text-align: center; }
 
 /* ---- Audio rows ---- */
 .k-audio-row { display: flex; align-items: center; gap: 10px; padding: 9px 10px;
@@ -405,6 +451,8 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
   .k-body { padding: 10px 12px 12px; }
   .k-footer { padding: 8px 12px 12px; }
   .k-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px; }
+  .k-tile-act { width: 30px; height: 30px; }
+  .k-pager-btn { width: 34px; height: 34px; }
   .k-actions { flex-direction: column; align-items: stretch; }
   .k-actions .k-btn { width: 100%; min-height: 44px; justify-content: center; }
   .k-btn { min-height: 40px; padding: 10px 14px; }

package/src/apps/widgets/generation.js

@@ -659,6 +659,7 @@ function renderCancelled(creditsRefunded) {
 var MAX_POLL_MS = 35 * 60 * 1000;
 var MAX_POLL_ERRORS = 30;
 var pollStart = 0, pollErrors = 0;
+var pollInFlight = false;
 var cancelRequested = false;   // set by the Stop button; freezes the poll loop
 
 /* ---------- offscreen gate ----------
@@ -696,6 +697,7 @@ function releaseSeen() {
 
 function schedulePoll(sc) {
   if (cancelRequested) return;
+  if (!sc.generation_id && !(sc.generation_ids && sc.generation_ids.length) && !sc.status_args) return;
   if (!seen) { whenSeenFns.push(function () { schedulePoll(sc); }); return; }
   // The call itself long-waits server-side, for one transport-safe window
   // (~45s over the remote connector — see WAIT_WINDOW_MS in tools/generate.js).
@@ -707,12 +709,15 @@ function schedulePoll(sc) {
   pollTimer = setTimeout(function () { poll(sc); }, delay);
 }
 function poll(sc) {
-  if (cancelRequested) return;
+  if (cancelRequested || pollInFlight) return;
   if (pollStart && (Date.now() - pollStart) > MAX_POLL_MS) {
     return renderTrackingIssue('This is still running longer than the tracking window. Do not retry it — any completed result will appear in your Kolbo library.');
   }
   var args = sc.status_args || { generation_id: sc.generation_id, wait: true };
+  pollInFlight = true;
   window.kolbo.callTool(sc.poll_tool || 'get_generation_status', args).then(function (res) {
+    pollInFlight = false;
+    if (cancelRequested || (state && (state.phase === 'completed' || state.phase === 'failed'))) return;
     var st = structured(res) || {};
     var stateName = st.state || st.phase || st.status;
     // A failed status CALL (tool error / not-found / {success:false}) is not a
@@ -766,6 +771,8 @@ function poll(sc) {
       schedulePoll(sc);
     }
   }).catch(function () {
+    pollInFlight = false;
+    if (cancelRequested || (state && (state.phase === 'completed' || state.phase === 'failed'))) return;
     if (++pollErrors >= MAX_POLL_ERRORS) return renderTrackingIssue('Tracking paused after repeated connection errors. The generation may still be running.');
     schedulePoll(sc);
   });
@@ -1340,20 +1347,20 @@ var PRE_VIDEO_KEYS = ['source_video', 'reference_videos'];
 var PRE_AUDIO_KEYS = ['audio', 'audio_url', 'reference_audio_urls', 'seed_reference_audio_urls'];
 
 // The card mounts the moment the tool is CALLED, so the only thing it knows is
-// the raw tool input - and for an edit/elements call the submit that follows is
+// the raw tool input — and for an edit/elements call the submit that follows is
 // the LONGEST wait on the card (local files are re-hosted first). Map the input
 // onto the same shape renderChips already reads for a server payload so the
 // references, DNA count and settings are on screen immediately instead of after
 // a minute of blank skeleton.
 // Deliberately NOT shown here: model, voice, DNA and moodboard NAMES. Those are
 // resolved server-side and arrive with the result (which overwrites all of
-// this) - rendering the raw identifier the caller passed would put an id on the
+// this) — rendering the raw identifier the caller passed would put an id on the
 // card, which is never allowed.
 function preRefSc(toolName, a) {
   var img = [], vid = [], aud = [];
   var take = function (v, bucket) {
     if (typeof v === 'string') {
-      // http(s) only - an absolute local path is not loadable from the iframe.
+      // http(s) only — an absolute local path is not loadable from the iframe.
       if (/^https?:/i.test(v) && bucket.indexOf(v) < 0) bucket.push(v);
       return;
     }
@@ -1484,6 +1491,8 @@ function completedFromPlain(sc) {
 }
 
 /* ---------- wire host events ---------- */
+// Paint before the host handshake: tool input may arrive late or be withheld.
+bootPre(null, null);
 window.kolbo.onToolResult(function (result) {
   var sc = result.structuredContent || structured(result);
   var list = listPayload(sc);

package/src/apps/widgets/list.js

@@ -7,7 +7,8 @@ const { widgetPage } = require('../html');
  * with no natural thumbnail (projects, sessions, agents, docs, folders,
  * knowledge-base sources). Reuses the exact row shell mediaGrid's audio rows
  * and catalog's model rows already use (`.k-audio-row` / `.k-audio-meta` /
- * `.k-chip` / `.k-btn` — no new CSS needed).
+ * `.k-chip` / `.k-btn` — no new CSS needed), and the same pager the media grid
+ * uses, so a long list is a fixed-height page instead of a card that grows.
  *
  * structuredContent contract:
  * {
@@ -43,6 +44,11 @@ const SCRIPT = `
 el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
 el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink('https://app.kolbo.ai'); };
 var state = null;
+var page = 0;
+var PAGE = 8;
+
+function pageCount() { return Math.max(1, Math.ceil(((state && state.items) || []).length / PAGE)); }
+function hasMore() { return !!(state && state.page_tool && state.next_args); }
 
 function boot(sc) {
   var list = listPayload(sc);
@@ -50,49 +56,73 @@ function boot(sc) {
   // listPayload() normalises plain shapes; carry the paging contract through.
   if (sc && sc.page_tool && !list.page_tool) { list.page_tool = sc.page_tool; list.next_args = sc.next_args; list.page = sc.page; }
   state = list;
+  page = 0;
   el('title').textContent = list.title || 'List';
-  var total = list.total != null ? list.total : list.items.length;
+  render();
+  return true;
+}
+
+function render() {
+  var total = state.total != null ? state.total : state.items.length;
   el('count-chip').style.display = '';
   el('count-chip').textContent = total + (total === 1 ? ' item' : ' items');
-  if (!list.items.length) {
+  if (!state.items.length) {
     el('stage').classList.add('k-empty');
     el('stage').innerHTML = 'Nothing here yet';
     window.kolbo.notifySize();
-    return true;
-  }
-  // Render every item the server sent (the old slice(0, 40) silently dropped
-  // rows, and nothing told the user). Load more only when the server said how.
-  var h = list.items.map(itemHTML).join('');
-  var shown = list.items.length;
-  if (list.page_tool && list.next_args) {
-    h += '<button class="k-btn" id="load-more" style="width:100%;margin-top:10px">Load more' +
-      (total > shown ? ' (' + shown + ' of ' + total + ' shown)' : '') + '</button>';
+    return;
   }
+  if (page > pageCount() - 1) page = pageCount() - 1;
+  var h = state.items.slice(page * PAGE, page * PAGE + PAGE).map(itemHTML).join('') + pagerHTML();
   el('stage').innerHTML = h;
   el('stage').classList.remove('k-empty');
   wire();
-  var lm = el('load-more');
-  if (lm) lm.onclick = function () { fetchNextPage(lm); };
   window.kolbo.notifySize();
-  return true;
+}
+
+function pagerHTML() {
+  var n = pageCount();
+  var more = hasMore();
+  if (n <= 1 && !more) return '';
+  var mid;
+  if (n <= 8) {
+    var dots = '';
+    for (var i = 0; i < n; i++) {
+      dots += '<button class="k-dot' + (i === page ? ' on' : '') + '" data-page="' + i + '" aria-label="Page ' + (i + 1) + '"></button>';
+    }
+    if (more) dots += '<span class="k-dot ghost"></span>';
+    mid = '<div class="k-dots">' + dots + '</div>';
+  } else {
+    mid = '<span class="k-pager-label">' + (page + 1) + ' / ' + n + (more ? '+' : '') + '</span>';
+  }
+  return '<div class="k-pager">' +
+    '<button class="k-pager-btn" id="page-prev" aria-label="Previous"' + (page === 0 ? ' disabled' : '') + '>' + ICONS.chevronLeft + '</button>' +
+    mid +
+    '<button class="k-pager-btn" id="page-next" aria-label="Next"' + (page >= n - 1 && !more ? ' disabled' : '') + '>' + ICONS.chevronRight + '</button>' +
+    '</div>';
 }
 
 function fetchNextPage(btn) {
   if (!state || !state.page_tool || !state.next_args || btn.disabled) return;
   btn.disabled = true;
-  var label = btn.textContent;
-  btn.innerHTML = '<span class="k-spin"></span> Loading';
+  btn.innerHTML = '<span class="k-spin"></span>';
   window.kolbo.callTool(state.page_tool, state.next_args).then(function (res) {
     var sc = structured(res);
     var next = sc ? listPayload(sc) || sc : null;
     var more = (next && next.items) || [];
-    if ((res && res.isError) || !next) { btn.disabled = false; btn.textContent = 'Could not load more — try again'; return; }
-    if (!more.length) { btn.textContent = 'No more results'; return; }
+    if ((res && res.isError) || !next) {
+      btn.disabled = false;
+      btn.innerHTML = ICONS.chevronRight;
+      btn.title = 'Could not load more — try again';
+      return;
+    }
+    if (!more.length) { state.next_args = undefined; render(); return; }
     state.items = state.items.concat(more);
     state.next_args = sc.next_args;
     if (sc.total != null) state.total = sc.total;
-    boot(Object.assign({}, state, { widget: 'list', page_tool: state.page_tool, next_args: state.next_args }));
-  }).catch(function () { btn.disabled = false; btn.textContent = label; });
+    page = page + 1;
+    render();
+  }).catch(function () { btn.disabled = false; btn.innerHTML = ICONS.chevronRight; });
 }
 
 function apply(result) {
@@ -101,7 +131,8 @@ function apply(result) {
   return boot(inner.structuredContent || structured(inner) || inner);
 }
 
-function itemHTML(item, i) {
+function itemHTML(item) {
+  var i = state.items.indexOf(item);
   var clickable = !!item.id;
   var avatar = item.thumbnail
     ? '<img class="k-audio-art k-peek-hit" src="' + esc(item.thumbnail) + '" alt="" loading="lazy"'
@@ -119,14 +150,15 @@ function itemHTML(item, i) {
 }
 
 function wire() {
-  bindPeekHits(el('stage'));
-  Array.prototype.forEach.call(document.querySelectorAll('[data-open]'), function (b) {
+  var stage = el('stage');
+  bindPeekHits(stage);
+  Array.prototype.forEach.call(stage.querySelectorAll('[data-open]'), function (b) {
     b.onclick = function (e) {
       e.stopPropagation();
       window.kolbo.openLink(state.items[+b.getAttribute('data-open')].open_url);
     };
   });
-  Array.prototype.forEach.call(document.querySelectorAll('.k-audio-row'), function (row) {
+  Array.prototype.forEach.call(stage.querySelectorAll('.k-audio-row'), function (row) {
     var item = state.items[+row.getAttribute('data-i')];
     if (!item || !item.id) return;
     row.onclick = function (e) {
@@ -134,6 +166,16 @@ function wire() {
       window.kolbo.insertText(String(item.id));
     };
   });
+  Array.prototype.forEach.call(stage.querySelectorAll('[data-page]'), function (d) {
+    d.onclick = function () { var p = +d.getAttribute('data-page'); if (p !== page) { page = p; render(); } };
+  });
+  var prev = el('page-prev');
+  if (prev) prev.onclick = function () { if (page > 0) { page--; render(); } };
+  var next = el('page-next');
+  if (next) next.onclick = function () {
+    if (page < pageCount() - 1) { page++; render(); return; }
+    fetchNextPage(next);
+  };
 }
 
 window.kolbo.onToolResult(function (result) {