wormclaude 1.0.119 → 1.0.121

package/skills/build-mcp-app/references/apps-sdk-messages.md

@@ -1,227 +0,0 @@
-# ext-apps messaging — widget ↔ host ↔ server
-
-The `@modelcontextprotocol/ext-apps` package gives you the `App` class (browser side) plus the `registerAppTool`/`registerAppResource` helpers (server side). The messaging is two-way and persistent.
-
-## Construction
-
-```js
-const app = new App(
-  { name: "MyWidget", version: "1.0.0" },
-  {},                       // capabilities
-  { autoResize: true },     // options
-);
-```
-
-`autoResize: true` hooks up a `ResizeObserver` that fires `ui/notifications/size-changed` so the host iframe's height follows your rendered content. Without it the frame stays fixed-height and tall renders get clipped — turn it on for any widget whose height depends on the data.
-
----
-
-## Widget → Host
-
-### `app.sendMessage({ role, content })`
-
-Push a visible message into the conversation. This is the path by which user actions become conversation turns.
-
-```js
-app.sendMessage({
-  role: "user",
-  content: [{ type: "text", text: "User selected order #1234" }],
-});
-```
-
-The message shows up in chat and WormClaude responds to it. Use `role: "user"` — the widget is speaking on the user's behalf.
-
-### `app.updateModelContext({ content })`
-
-Update WormClaude's context **silently**, with no visible message. Use it for state that's worth knowing but doesn't deserve its own chat bubble.
-
-```js
-app.updateModelContext({
-  content: [{ type: "text", text: "Currently viewing: orders from last 30 days" }],
-});
-```
-
-### `app.callServerTool({ name, arguments })`
-
-Call a tool on your MCP server directly, going around WormClaude. Returns the tool result.
-
-```js
-const result = await app.callServerTool({
-  name: "fetch_order_details",
-  arguments: { orderId: "1234" },
-});
-```
-
-Use it for data fetches that don't need WormClaude's reasoning — pagination, detail lookups, refreshes.
-
-### `app.openLink({ url })`
-
-Open a URL in a new browser tab, brokered by the host. **Required** for any outbound navigation — the iframe sandbox blocks `window.open()` and `<a target="_blank">`.
-
-```js
-await app.openLink({ url: "https://example.com/cart" });
-```
-
-For anchors in rendered HTML, catch the click:
-
-```js
-card.querySelector("a").addEventListener("click", (e) => {
-  e.preventDefault();
-  app.openLink({ url: e.currentTarget.href });
-});
-```
-
-### `app.downloadFile({ name, mimeType, content })`
-
-A host-brokered download (the sandbox blocks a direct `<a download>`). `content` is a base64 string.
-
-```js
-const csv = rows.map((r) => Object.values(r).join(",")).join("\n");
-app.downloadFile({
-  name: "export.csv",
-  mimeType: "text/csv",
-  content: btoa(unescape(encodeURIComponent(csv))),
-});
-```
-
-### `app.requestDisplayMode({ mode })`
-
-Ask the host to move the widget between `"inline"`, `"pip"`, and `"fullscreen"`. Check `getHostContext().availableDisplayModes` first, and hide the control when a mode isn't on offer. The host answers by firing `onhostcontextchanged` with a new `displayMode` and `containerDimensions` — re-render at the new size.
-
-```js
-if (app.getHostContext()?.availableDisplayModes?.includes("fullscreen")) {
-  expandBtn.hidden = false;
-  expandBtn.onclick = () => app.requestDisplayMode({ mode: "fullscreen" });
-}
-```
-
----
-
-## Host → Widget
-
-### `app.ontoolresult = ({ content }) => {...}`
-
-Fires when the tool handler's return value is fed to the widget. This is the main data-in path.
-
-```js
-app.ontoolresult = ({ content }) => {
-  const data = JSON.parse(content[0].text);
-  renderUI(data);
-};
-```
-
-**Set this BEFORE `await app.connect()`** — the result can land right after the connection opens.
-
-### `app.ontoolinput = ({ arguments }) => {...}`
-
-Fires with the arguments WormClaude passed to the tool. Handy when the widget needs to know what was asked for (e.g., to highlight the search term).
-
-### `app.ontoolinputpartial = ({ arguments }) => {...}` / `app.ontoolcancelled = () => {...}`
-
-`ontoolinputpartial` fires while WormClaude is still streaming arguments — use it to show a skeleton ("Preparing: <title>…") before the result arrives. `ontoolcancelled` fires when the call is aborted; clear the skeleton then.
-
-### `app.getHostContext()` / `app.onhostcontextchanged = (ctx) => {...}`
-
-Read the host context and subscribe to its changes. Call `getHostContext()` **after** `connect()`, and subscribe for live updates (the user flips on dark mode, expands to fullscreen).
-
-| `ctx.` field | Use |
-|---|---|
-| `theme` | `"light"` / `"dark"` — toggle a `.dark` class |
-| `styles.variables` | Host CSS tokens — pass to `applyHostStyleVariables()` so colors/fonts match host chrome |
-| `displayMode` / `availableDisplayModes` | Current mode and which `requestDisplayMode` targets are valid |
-| `containerDimensions.{maxHeight,width}` | Size your render to this instead of hard-coded px |
-| `deviceCapabilities.touch` | Switch hover-only affordances to tap (`pointerdown`) |
-| `safeAreaInsets` | Padding for notches / composer overlay |
-
-```js
-const applyTheme = (t) =>
-  document.documentElement.classList.toggle("dark", t === "dark");
-
-app.onhostcontextchanged = (ctx) => applyTheme(ctx.theme);
-await app.connect();
-applyTheme(app.getHostContext()?.theme);
-```
-
-Keep colors in CSS custom properties with a `:root.dark {}` override block, and set `color-scheme: light | dark` so native form controls follow along.
-
----
-
-## Server → Widget (progress)
-
-For long-running operations, emit progress notifications. The client supplies a `progressToken` in the request's `_meta`, and the server emits against it.
-
-```typescript
-// In the tool handler
-async ({ query }, extra) => {
-  const token = extra._meta?.progressToken;
-  for (let i = 0; i < steps.length; i++) {
-    if (token !== undefined) {
-      await extra.sendNotification({
-        method: "notifications/progress",
-        params: { progressToken: token, progress: i, total: steps.length, message: steps[i].name },
-      });
-    }
-    await steps[i].run();
-  }
-  return { content: [{ type: "text", text: "Complete" }] };
-}
-```
-
-No `{ notify }` destructure — `extra` is `RequestHandlerExtra`; progress goes through `sendNotification`.
-
----
-
-## Lifecycle
-
-1. WormClaude calls a tool that declares `_meta.ui.resourceUri`
-2. The host fetches the resource (your HTML) and mounts a **fresh iframe** for this call
-3. The widget script runs, registers handlers, and calls `await app.connect()`
-4. The host feeds the tool's return value in → `ontoolresult` fires
-5. The widget renders and the user interacts with it
-6. The widget calls `sendMessage` / `updateModelContext` / `callServerTool` as needed
-7. The iframe stays in the transcript; **the next call to the same tool mounts another iframe** beside it
-
-There's no explicit "submit and close" — each instance is long-lived, and instances are never reused across calls.
-
-### Supersession
-
-Since earlier instances stay mounted, a click on a stale widget can `sendMessage` after a newer one has rendered. Catch this with a `BroadcastChannel` and make the older instances inert:
-
-```js
-let superseded = false;
-const seq = Date.now() + Math.random();
-const bc = new BroadcastChannel("my-widget");
-bc.onmessage = (e) => {
-  if (e.data?.seq > seq) {
-    superseded = true;
-    document.body.classList.add("superseded"); // opacity:.45; pointer-events:none
-  }
-};
-bc.postMessage({ seq });
-
-// Guard outbound calls:
-function safeSend(msg) {
-  if (!superseded) app.sendMessage(msg);
-}
-```
-
----
-
-## Sandbox & CSP gotchas
-
-The iframe runs under both an HTML `sandbox` attribute **and** a strict Content-Security-Policy. In practice almost nothing external gets through — widgets should be fully self-contained.
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| Widget is a blank rectangle, nothing renders | CDN `import` of ext-apps blocked (transitive SDK fetches) | **Inline** the `ext-apps/app-with-deps` bundle — see `iframe-sandbox.md` |
-| Widget renders but JS doesn't run | Inline event handlers blocked | Use `addEventListener` — never `onclick="..."` in HTML |
-| `eval` / `new Function` errors | Script-src restriction | Don't use them; use JSON.parse for data |
-| `fetch()` to your API fails | Cross-origin blocked | Route through `app.callServerTool()` instead |
-| External CSS doesn't load | `style-src` restriction | Inline styles in a `<style>` tag |
-| Fonts don't load | `font-src` restriction | Use system fonts (`font: 14px system-ui`) |
-| External `<img src>` broken | CSP `img-src` + referrer hotlink blocking | Fetch server-side, inline as `data:` URL in the tool result payload |
-| `window.open()` does nothing | Sandbox lacks `allow-popups` | Use `app.openLink({url})` |
-| `<a target="_blank">` does nothing | Same | Intercept click → `preventDefault()` → `app.openLink` |
-| Edited HTML doesn't appear in Desktop | Desktop caches UI resources | Fully quit (⌘Q) + relaunch, not just window-close |
-
-When you're unsure, open the **iframe's own** devtools console (not the main app's) — CSP violations are logged there. See `iframe-sandbox.md` for the bundle-inlining pattern.

package/skills/build-mcp-app/references/directory-checklist.md

@@ -1,18 +0,0 @@
-# Connector-directory submission checklist
-
-Run through this before submitting a remote MCP app to the WormClaude connector
-directory. Every item is a hard review criterion.
-
-| Area | Requirement |
-|---|---|
-| **Auth** | OAuth (DCR or CIMD) or **`none`** (authless). Static bearer tokens are private-deploy only and block listing. Authless is fine for public-data servers — the server holds any upstream API keys itself. |
-| **Tool annotations** | Every tool sets `annotations.title` plus the relevant hints: `readOnlyHint: true` for fetch/search tools, `destructiveHint` / `idempotentHint` for writes, `openWorldHint: true` when the tool reaches an external system. |
-| **Tool names** | ≤ 64 characters, snake/kebab case. |
-| **Widget layout** | Inline height ≤ 500px, no nested scroll containers, 44pt minimum touch targets, WCAG-AA contrast in both themes. |
-| **Theming** | `html, body { background: transparent }`, `<meta name="color-scheme" content="light dark">`, and pull in host CSS tokens via `applyHostStyleVariables`. |
-| **External links** | Use `app.openLink`. List each origin (e.g. `https://api.example.com`) in the connector's *Allowed link URIs* so the link skips the confirm modal. |
-| **Helper tools** | Widget-only tools (geometry/image fetchers) carry `_meta.ui.visibility: ["app"]` so they stay out of WormClaude's tool list. |
-| **Screenshots** | 3–5 PNGs, ≥ 1000px wide, cropped to the app response alone — no prompt text in frame. |
-
-See `abuse-protection.md` for rate-limit and IP-tiering guidance once the
-authless endpoint goes public.

package/skills/build-mcp-app/references/iframe-sandbox.md

@@ -1,164 +0,0 @@
-# Iframe sandbox constraints
-
-MCP-app widgets run inside a sandboxed `<iframe>` in the host (WormClaude Desktop,
-claude.ai). The sandbox and CSP attributes tightly constrain what the widget can
-do. Each item below was seen failing as a silently blank iframe until the fix
-went in — the error shows up only in the iframe's own devtools console, never
-the host's.
-
----
-
-## Problem → fix table
-
-| Symptom | Root cause | Fix |
-|---|---|---|
-| Widget renders as blank rectangle, no error | CSP `script-src` blocks esm.sh fetching transitive `@modelcontextprotocol/sdk` deps | Inline the `ext-apps/app-with-deps` bundle into the HTML |
-| `window.open()` does nothing | Sandbox lacks `allow-popups` | Use `app.openLink({ url })` |
-| `<a target="_blank">` does nothing | Same | `e.preventDefault()` + `app.openLink({ url })` on click |
-| External `<img src>` broken | CSP `img-src` + referrer hotlink blocking | Fetch server-side, ship as `data:` URL in the tool result payload |
-| Widget edits don't appear after server restart | Host caches UI resources | Fully quit the host (⌘Q / Alt+F4) and relaunch |
-| Top-level `await` throws | Older iframe contexts | Wrap module body in an async IIFE |
-
----
-
-## Inlining the ext-apps bundle
-
-`@modelcontextprotocol/ext-apps` provides a self-contained browser build via the
-`app-with-deps` export (~300KB). It's minified ESM that ends in `export{…}`; to
-consume it from an inline `<script type="module">` block, rewrite that export
-statement into a global assignment at build time:
-
-```ts
-import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-const require = createRequire(import.meta.url);
-
-const bundle = readFileSync(
-  require.resolve("@modelcontextprotocol/ext-apps/app-with-deps"),
-  "utf8",
-).replace(/export\{([^}]+)\};?\s*$/, (_, body) =>
-  "globalThis.ExtApps={" +
-  body.split(",").map((pair) => {
-    const [local, exported] = pair.split(" as ").map((s) => s.trim());
-    return `${exported ?? local}:${local}`;
-  }).join(",") + "};",
-);
-
-const widgetHtml = readFileSync("./widgets/widget.html", "utf8")
-  .replace("/*__EXT_APPS_BUNDLE__*/", () => bundle);
-```
-
-Widget side:
-
-```html
-<script type="module">
-/*__EXT_APPS_BUNDLE__*/
-const { App } = globalThis.ExtApps;
-(async () => {
-  const app = new App({ name: "…", version: "…" }, {});
-  // …
-})();
-</script>
-```
-
-Using the `() => bundle` replacer form (instead of a bare string) matters —
-`String.replace` treats `$…` sequences specially in a string replacement, and
-the minified bundle is packed with them.
-
----
-
-## Outbound links
-
-```js
-// ✗ blocked
-window.open(url, "_blank");
-// ✗ blocked
-<a href="…" target="_blank">…</a>
-
-// ✓ host-mediated
-await app.openLink({ url });
-```
-
-Intercept anchor clicks:
-
-```js
-el.addEventListener("click", (e) => {
-  e.preventDefault();
-  app.openLink({ url: el.href });
-});
-```
-
----
-
-## External images
-
-The default CSP `img-src` (plus many CDN referrer policies) stops
-`<img src="https://external-cdn/…">` from loading. Inline them server-side in
-the tool handler:
-
-```ts
-async function toDataUrl(url: string): Promise<string | undefined> {
-  try {
-    const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
-    if (!res.ok) return undefined;
-    const buf = Buffer.from(await res.arrayBuffer());
-    const mime = res.headers.get("content-type") ?? "image/jpeg";
-    return `data:${mime};base64,${buf.toString("base64")}`;
-  } catch {
-    return undefined;
-  }
-}
-
-// in the tool handler
-const inlined = await Promise.all(
-  items.map(async (it) =>
-    it.thumb ? { ...it, thumb: await toDataUrl(it.thumb) ?? it.thumb } : it,
-  ),
-);
-```
-
-Add `referrerpolicy="no-referrer"` on the `<img>` as a fallback for any URL
-that ends up not inlined.
-
----
-
-## Theme & host styles
-
-The host draws the iframe inside its own card chrome — so paint a **transparent** background and pull in the host CSS tokens so the widget blends in across light/dark and across different hosts.
-
-```html
-<meta name="color-scheme" content="light dark" />
-```
-
-```css
-:root {
-  --ink:  var(--color-text-primary,   #0f1111);
-  --sub:  var(--color-text-secondary, #5a6270);
-  --line: var(--color-border-default, #e3e6ea);
-}
-html, body { background: transparent; color: var(--ink); }
-:root.dark .thumb { mix-blend-mode: normal; } /* multiply → images vanish in dark */
-```
-
-```js
-const { App, applyHostStyleVariables } = globalThis.ExtApps;
-
-function applyHostContext(ctx) {
-  document.documentElement.classList.toggle("dark", ctx?.theme === "dark");
-  if (ctx?.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
-}
-app.onhostcontextchanged = applyHostContext;
-await app.connect();
-applyHostContext(app.getHostContext());
-```
-
-`applyHostStyleVariables` writes the host's `--color-*` / `--font-*` / `--border-radius-*` tokens onto `:root`; the hex values above act as fallbacks for hosts that don't provide them.
-
----
-
-## Debugging
-
-The iframe has a console of its own. In WormClaude Desktop, open DevTools (View →
-Toggle Developer Tools), then flip the context dropdown (top-left of the Console
-tab) from "top" to the widget's iframe. CSP violations, uncaught exceptions, and
-import errors all show up there — the host's main console stays quiet.

package/skills/build-mcp-app/references/payload-budgeting.md

@@ -1,54 +0,0 @@
-# Payload budgeting
-
-Hosts cap tool-result text. claude.ai and WormClaude Desktop truncate at roughly
-**150,000 characters**; Claude Code at ~25k tokens. Once a tool result goes over
-the cap, the host swaps in a file-pointer string in place of your JSON. The
-widget then gets non-JSON in `ontoolresult`, `JSON.parse` throws, and the user
-sees something like *"Bad payload: SyntaxError: Unexpected token 'E'"* — with no
-clue that size was the culprit.
-
-## Symptom → cause
-
-| Symptom | Likely cause |
-|---|---|
-| Widget shows a JSON parse error on `content[0].text` | Result topped the host cap; the host swapped in a file-pointer string |
-| Works for one query, breaks for "all of X" | Row count × column count went past the cap |
-| Works in MCP Inspector, breaks in Desktop | The Inspector has no cap; Desktop does |
-
-## Strategy
-
-Cap your own payload at ~130KB and step down in this order:
-
-1. **Send full rows** while `JSON.stringify(rows).length` stays under the cap.
-2. **Prune columns** down to the ones the rendering spec actually references.
-   Scan the spec for both `field: "..."` keys *and* `datum.X` / `datum['X']`
-   inside expression strings — when the spec aliases a column through a
-   `calculate` transform, the alias shows up as `field:` but the source column
-   only appears as `datum.X`, and dropping it leaves the widget with NaN.
-3. **Truncate rows** only as a last resort, and put `{ truncated: N }` in the
-   payload so the widget can label it.
-
-```ts
-const MAX = 130_000;
-let out = rows;
-if (JSON.stringify(out).length > MAX) {
-  const keep = referencedFields(spec); // field: + datum.X refs
-  out = rows.map((r) => pick(r, keep));
-  if (JSON.stringify(out).length > MAX) {
-    const per = JSON.stringify(out[0] ?? {}).length || 1;
-    out = out.slice(0, Math.floor(MAX / per));
-  }
-}
-```
-
-## Heavy assets go via `callServerTool`, not the result
-
-Geometry, image bytes, or any blob the widget needs but WormClaude doesn't should
-come from a separate tool the widget calls after it mounts:
-
-```js
-const topo = await app.callServerTool({ name: "get-topojson", arguments: { level } });
-```
-
-Tag that helper tool with `_meta.ui.visibility: ["app"]` so it stays out of
-WormClaude's tool list.