Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(shipfeed): publish a ship feed with provenance, its package, API, MCP server and public surface
nirholas8f062ba9ed45
diff --git a/api/_lib/ship-provenance.js b/api/_lib/ship-provenance.jsnew file mode 100644index 000000000..6faa5e986--- /dev/null+++ b/api/_lib/ship-provenance.js@@ -0,0 +1,99 @@+// @ts-check+// Provenance for a changelog entry: which commits actually produced it.+//+// The holder channel carries two feeds that describe the same work and have+// never known about each other (api/_lib/changelog-push.js posts the sentence,+// api/_lib/commit-feed-push.js posts the code). This module is the join: it+// reads recent commits once per process window and hands each release note the+// count and sha range of the work behind it, so the announcement can point at+// the diff instead of leaving a reader to guess which of that afternoon's+// thirty commits it meant.+//+// Every part of it is best-effort by design. A release announcement must go out+// even when GitHub is rate-limited, so every failure here resolves to null and+// the caller posts the message it would have posted anyway.++import { linkCommits, entryKey, fetchGitHubCommits } from '../../packages/shipfeed/src/index.js';+import { fetchUpstream } from './upstream-fetch.js';++const REPO = 'nirholas/three.ws';+const COMMIT_LIMIT = 300;+const CACHE_TTL_MS = 5 * 60_000;++/** Process-local cache: one GitHub read serves every entry in a cron tick. */+let cache = { at: 0, commits: null };++const boundedFetch = (url, init) =>+ fetchUpstream(url, init, {+ name: 'github-commits',+ timeoutMs: 12_000,+ attempts: 2,+ okWhen: () => true,+ });++/**+ * Recent commits on main, or null when GitHub cannot be read right now.+ * @param {{now?: number}} [options]+ */+export async function recentCommits(options = {}) {+ const now = options.now ?? Date.now();+ if (cache.commits && now - cache.at < CACHE_TTL_MS) return cache.commits;+ try {+ const commits = await fetchGitHubCommits({+ repo: REPO,+ branch: 'main',+ limit: COMMIT_LIMIT,+ token: process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '',+ fetchImpl: boundedFetch,+ userAgent: 'three.ws-shipfeed',+ });+ cache = { at: now, commits };+ return commits;+ } catch (err) {+ console.warn(`[ship-provenance] commit read failed: ${err?.message || err}`);+ return null;+ }+}++/**+ * Map each entry key to the work behind it.+ *+ * @param {{date: string, title: string, summary?: string, tags?: string[], link?: string}[]} entries+ * @param {{commits?: object[]|null}} [options] injected commits (tests, callers that already read them)+ * @returns {Promise<Map<string, {count: number, range: string, compareUrl: string}>>}+ * empty when commits are unavailable, so callers need no special case+ */+export async function provenanceByEntry(entries, options = {}) {+ const out = new Map();+ if (!Array.isArray(entries) || entries.length === 0) return out;++ // `commits` present but null means "the caller already tried and failed";+ // absent means "read them yourself". Coalescing the two would send a test,+ // or a caller handling its own outage, back out to the network.+ const commits = 'commits' in options ? options.commits : await recentCommits();+ if (!commits || commits.length === 0) return out;++ const { byEntry } = linkCommits(entries, commits);+ for (const entry of entries) {+ const bucket = byEntry.get(entryKey(entry));+ if (!bucket || bucket.commits.length === 0) continue;+ const first = bucket.commits[0];+ const last = bucket.commits[bucket.commits.length - 1];+ const range = `${first.shortSha}..${last.shortSha}`;+ out.set(entryKey(entry), {+ count: bucket.commits.length,+ range,+ // A one-commit range has nothing to compare against, so link the commit.+ compareUrl:+ bucket.commits.length === 1+ ? `https://github.com/${REPO}/commit/${first.sha}`+ : `https://github.com/${REPO}/compare/${first.sha}...${last.sha}`,+ });+ }+ return out;+}++/** Reset the process cache. Tests use this; production never needs it. */+export function resetProvenanceCache() {+ cache = { at: 0, commits: null };+}diff --git a/packages/herald-mcp/LICENSE b/packages/herald-mcp/LICENSEnew file mode 100644index 000000000..dff21b7f4--- /dev/null+++ b/packages/herald-mcp/LICENSE@@ -0,0 +1,20 @@+Copyright 2026 nirholas++All rights reserved.++This software is proprietary and may not be used, copied, modified, distributed,+translated, or made available to any third party without the express written+permission of the copyright owner.++No rights are granted by implication, estoppel, or otherwise. Use of this+software is subject to the terms of a separate license agreement with the+copyright owner.++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 COPYRIGHT OWNER 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.diff --git a/packages/herald-mcp/README.md b/packages/herald-mcp/README.mdnew file mode 100644index 000000000..191e50236--- /dev/null+++ b/packages/herald-mcp/README.md@@ -0,0 +1,116 @@+# @three-ws/herald-mcp++**Let your agent tell you something in person.**++An MCP server with one idea behind it: when an agent finishes something that+mattered, or gets stuck, it should not add a line to a log you will never scroll+back to. It should walk up to you and say so.++Wire this in, and it does. Your own 3D companion appears in the corner of+whatever browser tab you have open, gestures, and says the line out loud, with a+link to click through.++```+you: run the migration, then the backfill, and tell me when it's done+agent: [runs for 22 minutes]+ [calls announce_result: task "the backfill", outcome succeeded, 1320s]+your browser: your avatar walks on: "the backfill finished in 22m"+```++## Tools++| Tool | What it does |+| --- | --- |+| `announce` | Say one line, with importance (0-100), tone, a gesture, and an optional link. |+| `announce_result` | Report a finished task. The urgency is chosen from the outcome, so a failure cuts through quiet hours and a success does not. |+| `check_rail` | Prove the key and the rail work, without interrupting anybody (queues at importance 0, which every client drops). |++## Install++```sh+npx -y @three-ws/herald-mcp+```++Claude Code:++```sh+claude mcp add herald -e THREE_WS_API_KEY=sk_live_... -- npx -y @three-ws/herald-mcp+```++Claude Desktop / Cursor (`mcp.json`):++```json+{+ "mcpServers": {+ "herald": {+ "command": "npx",+ "args": ["-y", "@three-ws/herald-mcp"],+ "env": { "THREE_WS_API_KEY": "sk_live_..." }+ }+ }+}+```++## The key++Create one at [three.ws/dashboard/developers](https://three.ws/dashboard/developers)+with the **`herald:announce`** scope, and put it in `THREE_WS_API_KEY`.++An announcement is always delivered to **the key owner's own** live sessions.+There is no recipient parameter: this server cannot be pointed at anybody else,+so the worst a leaked key can do is annoy the person who leaked it. Revoke it in+the same place.++| Variable | Required | Default | Notes |+| --- | --- | --- | --- |+| `THREE_WS_API_KEY` | yes | | API key with `herald:announce`, or an OAuth access token. Aliases: `THREE_WS_TOKEN`, `THREE_WS_BEARER`. |+| `THREE_WS_BASE` | no | `https://three.ws` | Override for self-hosting or a preview deployment. |+| `THREE_WS_TIMEOUT_MS` | no | `20000` | Per-request timeout. |++## When to use it (and when not to)++Announcements are scarce on purpose. The receiving client applies an importance+floor, a rate limit, dedupe, quiet hours, and a freshness window, so anything+that does not clear the bar is dropped rather than queued. That is the feature:+an interruption only works while it is rare.++Good: a long job finished, a job failed, a decision is needed, something broke,+money moved.++Bad: progress updates, "starting step 3 of 7", anything the person can read+later. Those belong in the notification inbox+([@three-ws/notifications-mcp](https://www.npmjs.com/package/@three-ws/notifications-mcp)).++If nothing is open to hear it, the line expires in about five minutes. The rail+is a live channel, not an archive.++## Example calls++```jsonc+// something broke, and it should wake somebody up+{ "name": "announce", "arguments": {+ "text": "The payments worker has been failing for 10 minutes",+ "from": "watchdog", "importance": 95, "tone": "error",+ "url": "https://three.ws/dashboard", "key": "payments-worker-down" } }++// a long task finished, and it should not+{ "name": "announce_result", "arguments": {+ "task": "the nightly backfill", "outcome": "succeeded", "seconds": 1320 } }++// wiring check+{ "name": "check_rail", "arguments": { "note": "claude-code" } }+```++## How it reaches a browser++`POST /api/herald/announce` queues the line on the account's rail; the page+listens over SSE and hands it to [@three-ws/herald](https://www.npmjs.com/package/@three-ws/herald),+which decides whether it clears the person's own rules and then delivers it+through the 3D companion (or an accessible card when there is no GPU).++Try the whole loop, including the rules engine, at+[three.ws/herald](https://three.ws/herald).++## License++Apache-2.0.diff --git a/packages/herald-mcp/package.json b/packages/herald-mcp/package.jsonnew file mode 100644index 000000000..b47f97725--- /dev/null+++ b/packages/herald-mcp/package.json@@ -0,0 +1,56 @@+{+ "name": "@three-ws/herald-mcp",+ "version": "0.1.0",+ "mcpName": "io.github.nirholas/herald-mcp",+ "description": "Let an AI agent tell its human something in person: a 3D character walks onto the browser tab they have open and says it out loud. Announce a line, report a finished task with the right urgency, or check the rail. Account-scoped over the live three.ws API via a Bearer API key.",+ "type": "module",+ "author": "nirholas <[email protected]>",+ "license": "Apache-2.0",+ "homepage": "https://three.ws/herald",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/nirholas/three.ws.git",+ "directory": "packages/herald-mcp"+ },+ "bugs": {+ "url": "https://github.com/nirholas/three.ws/issues"+ },+ "keywords": [+ "mcp",+ "three.ws",+ "herald",+ "notifications",+ "avatar",+ "agent",+ "tts",+ "alerts"+ ],+ "publishConfig": {+ "access": "public"+ },+ "files": [+ "src",+ "server.json",+ "README.md",+ "LICENSE"+ ],+ "bin": {+ "herald-mcp": "src/index.js"+ },+ "main": "./src/index.js",+ "exports": {+ ".": "./src/index.js"+ },+ "engines": {+ "node": ">=20"+ },+ "scripts": {+ "start": "node src/index.js",+ "test": "node --test \"test/**/*.test.mjs\"",+ "inspect": "npx -y @modelcontextprotocol/inspector node src/index.js"+ },+ "dependencies": {+ "@modelcontextprotocol/sdk": "^1.29.0",+ "zod": "^3.23.8"+ }+}diff --git a/packages/herald-mcp/server.json b/packages/herald-mcp/server.jsonnew file mode 100644index 000000000..6c21c6e25--- /dev/null+++ b/packages/herald-mcp/server.json@@ -0,0 +1,56 @@+{+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",+ "name": "io.github.nirholas/herald-mcp",+ "title": "three.ws Herald",+ "description": "Tell your human something in person: a 3D character walks onto the browser tab they have open and says it.",+ "websiteUrl": "https://three.ws/herald",+ "icons": [+ {+ "src": "https://three.ws/three-ws-mcp-icon.svg",+ "mimeType": "image/svg+xml",+ "sizes": [+ "any"+ ]+ }+ ],+ "repository": {+ "url": "https://github.com/nirholas/three.ws",+ "source": "github",+ "subfolder": "packages/herald-mcp"+ },+ "version": "0.1.0",+ "packages": [+ {+ "registryType": "npm",+ "identifier": "@three-ws/herald-mcp",+ "version": "0.1.0",+ "runtimeHint": "npx",+ "transport": {+ "type": "stdio"+ },+ "environmentVariables": [+ {+ "name": "THREE_WS_API_KEY",+ "description": "A three.ws API key (sk_live_… / sk_test_…) with the herald:announce scope, or an OAuth access token for the same account, carried as Authorization: Bearer. Required: an announcement is always delivered to the key owner's own sessions. Aliases: THREE_WS_TOKEN, THREE_WS_BEARER. Treat like a password.",+ "format": "string",+ "isRequired": true,+ "isSecret": true+ },+ {+ "name": "THREE_WS_BASE",+ "description": "Base URL of the three.ws API. Override only when self-hosting or targeting a preview deployment.",+ "format": "string",+ "isRequired": false,+ "default": "https://three.ws"+ },+ {+ "name": "THREE_WS_TIMEOUT_MS",+ "description": "Per-request timeout in milliseconds for the announce call.",+ "format": "number",+ "isRequired": false,+ "default": "20000"+ }+ ]+ }+ ]+}diff --git a/packages/herald-mcp/smithery.yaml b/packages/herald-mcp/smithery.yamlnew file mode 100644index 000000000..c067345d5--- /dev/null+++ b/packages/herald-mcp/smithery.yaml@@ -0,0 +1,10 @@+# Smithery deployment config for @three-ws/herald-mcp+# https://smithery.ai/docs/config#smitheryyaml+startCommand:+ type: stdio+ configSchema:+ type: object+ properties: {}+ required: []+ commandFunction: |+ (config) => ({ command: "npx", args: ["-y", "@three-ws/herald-mcp"], env: {} })diff --git a/packages/herald-mcp/src/config.js b/packages/herald-mcp/src/config.jsnew file mode 100644index 000000000..887c71513--- /dev/null+++ b/packages/herald-mcp/src/config.js@@ -0,0 +1,43 @@+// Centralized env + HTTP base for the herald MCP.+//+// This server has exactly one job: hand a line to the three.ws delivery rail so+// the human who owns the key hears it from their own 3D companion. It is+// authenticated (a Bearer credential on every request), it signs nothing+// locally, and it holds no other secret.+//+// The addressing model is worth understanding before wiring an agent to it: an+// announcement always goes to the *key owner's own* sessions. There is no+// recipient parameter, so an agent cannot use this to interrupt anyone else.++export function env(key, fallback) {+ const v = process.env[key];+ return v !== undefined && String(v).trim() !== '' ? String(v).trim() : fallback;+}++// Base URL of the three.ws API. Override only when self-hosting or pointing at+// a preview deployment.+export const THREE_WS_BASE = env('THREE_WS_BASE', 'https://three.ws').replace(/\/+$/, '');++// The agent owner's three.ws credential: an API key (sk_live_… / sk_test_…)+// carrying the `herald:announce` scope, or an OAuth access token for the same+// account. REQUIRED: the rail is account-scoped and returns 401 without it.+// THREE_WS_TOKEN / THREE_WS_BEARER are accepted aliases.+export const THREE_WS_API_KEY =+ env('THREE_WS_API_KEY') || env('THREE_WS_TOKEN') || env('THREE_WS_BEARER') || '';++// Per-request timeout (ms). One small POST; generous enough to ride out a cold+// edge without leaving an agent hanging.+export const HTTP_TIMEOUT_MS = (() => {+ const raw = env('THREE_WS_TIMEOUT_MS');+ if (raw === undefined) return 20000;+ const n = Number(raw);+ if (!Number.isFinite(n) || n <= 0) {+ throw Object.assign(new Error(`THREE_WS_TIMEOUT_MS must be a positive number (got "${raw}")`), {+ code: 'bad_config',+ });+ }+ return n;+})();++// Identifies this client to the API in request logs.+export const USER_AGENT = '@three-ws/herald-mcp';diff --git a/packages/herald-mcp/src/index.js b/packages/herald-mcp/src/index.jsnew file mode 100755index 000000000..57ce8e65a--- /dev/null+++ b/packages/herald-mcp/src/index.js@@ -0,0 +1,124 @@+#!/usr/bin/env node+// @three-ws/herald-mcp: MCP server entry point.+//+// Gives an AI agent a way to tell its human something in person. Not another+// line in a log the person will never scroll back to: their own 3D companion+// walks onto the browser tab they have open, gestures, and says it out loud,+// with a link to click through.+//+// • announce say one line, with importance, tone, gesture and a link+// • announce_result report a finished task with the urgency chosen for you+// • check_rail prove the key and the rail work, interrupting nobody+//+// AUTHENTICATED, and deliberately unable to reach anyone else: an announcement+// always goes to the key owner's own live sessions. There is no recipient+// parameter, so the worst a leaked key can do is annoy the person who leaked+// it. Keys are minted at https://three.ws/dashboard/developers with the+// `herald:announce` scope and revoked there.+//+// Run standalone:+// THREE_WS_API_KEY=sk_live_… node packages/herald-mcp/src/index.js+//+// Or wire into Claude Code / Cursor: see README.md.++import { realpathSync } from 'node:fs';+import { createRequire } from 'node:module';+import { pathToFileURL } from 'node:url';++import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';++import { def as announce } from './tools/announce.js';+import { def as announceResult } from './tools/announce-result.js';+import { def as checkRail } from './tools/check-rail.js';++// Single source of truth for the advertised server version: package.json.+const require = createRequire(import.meta.url);+const { version: PKG_VERSION } = require('../package.json');++export const TOOLS = [announce, announceResult, checkRail];++/**+ * Construct a fully-registered McpServer without connecting a transport.+ * Registration is env-free (no key needed to advertise the tool surface), so+ * this is safe to import from tests. A credential is required only to run one.+ * @returns {McpServer}+ */+export function buildServer() {+ const server = new McpServer(+ { name: 'herald-mcp', title: 'three.ws Herald', version: PKG_VERSION },+ {+ capabilities: { tools: {} },+ instructions:+ 'three.ws Herald MCP: deliver a message to your human in person. announce says one line ' ++ "through the owner's own 3D companion on whatever browser tab they have open, with " ++ 'importance (0-100), tone, a gesture and an optional link. announce_result reports a ' ++ 'finished task and picks the urgency from the outcome, so a failure cuts through quiet ' ++ 'hours and a success does not. check_rail verifies the credential without interrupting ' ++ 'anybody. Reserve these for moments that deserve to interrupt a person: the client applies ' ++ 'an importance floor, a rate limit, dedupe and quiet hours, so chatter is dropped rather ' ++ 'than queued. Every announcement is delivered to the key owner and nobody else, and an ' ++ 'undelivered one expires in about five minutes rather than piling up. Requires ' ++ 'THREE_WS_API_KEY with the herald:announce scope. $THREE is the only coin.',+ },+ );++ for (const tool of TOOLS) {+ server.registerTool(+ tool.name,+ {+ title: tool.title,+ description: tool.description,+ inputSchema: tool.inputSchema,+ annotations: tool.annotations,+ },+ async (args, extra) => {+ try {+ const result = await tool.handler(args, extra);+ const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);+ return { content: [{ type: 'text', text }] };+ } catch (err) {+ const payload = {+ ok: false,+ error: err?.code || 'unhandled',+ message: err?.message || String(err),+ ...(err?.status ? { status: err.status } : {}),+ ...(err?.body ? { detail: err.body } : {}),+ };+ return {+ content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],+ isError: true,+ };+ }+ },+ );+ }++ return server;+}++async function main() {+ const server = buildServer();+ const transport = new StdioServerTransport();+ await server.connect(transport);+ console.error(`[herald-mcp@${PKG_VERSION}] connected over stdio with ${TOOLS.length} tools`);+}++// Connect stdio ONLY when this file is the process entry point. Importing the+// module (tests, embedding) must not grab the transport. realpath both sides:+// npm bin shims are symlinks, so argv[1] may differ from import.meta.url.+function isProcessEntryPoint() {+ if (!process.argv[1]) return false;+ try {+ return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;+ } catch {+ return false;+ }+}++if (isProcessEntryPoint()) {+ main().catch((err) => {+ console.error('[herald-mcp] fatal:', err);+ process.exit(1);+ });+}diff --git a/packages/herald-mcp/src/lib/api.js b/packages/herald-mcp/src/lib/api.jsnew file mode 100644index 000000000..3e76a05d1--- /dev/null+++ b/packages/herald-mcp/src/lib/api.js@@ -0,0 +1,80 @@+// Real HTTP access to the three.ws herald rail. No mocks, no fixtures: every+// call is a live, authenticated request to THREE_WS_BASE. The Bearer credential+// is attached here (single HTTP client, single auth path) and errors are+// normalized into one shape so tool handlers surface a clean message + status.++import { THREE_WS_BASE, HTTP_TIMEOUT_MS, USER_AGENT, THREE_WS_API_KEY } from '../config.js';++// Thrown before any request when the server has no credential. The rail is+// account-scoped, so a missing key is a config error, not an upstream 401.+export class MissingCredentialError extends Error {+ constructor() {+ super(+ 'No three.ws credential configured. Set THREE_WS_API_KEY to a three.ws API key ' ++ '(sk_live_… / sk_test_…) carrying the herald:announce scope, or an OAuth access token ' ++ 'for the same account. Create one at https://three.ws/dashboard/developers.',+ );+ this.code = 'missing_credential';+ this.status = 401;+ }+}++/**+ * Call a three.ws endpoint and return its parsed JSON body.+ *+ * @param {string} path Endpoint path beginning with `/`.+ * @param {{ method?: string, body?: unknown }} [opts]+ * @returns {Promise<any>}+ * @throws {MissingCredentialError} when no credential is configured.+ * @throws {Error} with `.code` ('timeout' | 'network_error' | 'upstream_error'),+ * and on upstream errors `.status` + `.body`.+ */+export async function apiRequest(path, { method = 'GET', body } = {}) {+ if (!THREE_WS_API_KEY) throw new MissingCredentialError();++ const controller = new AbortController();+ const timer = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);++ let res;+ try {+ res = await fetch(`${THREE_WS_BASE}${path}`, {+ method,+ headers: {+ accept: 'application/json',+ 'user-agent': USER_AGENT,+ // Capital-B "Bearer " — the server's CSRF guard exempts requests on+ // this exact prefix, so authenticated writes need no CSRF token.+ authorization: `Bearer ${THREE_WS_API_KEY}`,+ ...(body !== undefined ? { 'content-type': 'application/json' } : {}),+ },+ body: body !== undefined ? JSON.stringify(body) : undefined,+ signal: controller.signal,+ });+ } catch (err) {+ clearTimeout(timer);+ if (err?.name === 'AbortError') {+ throw Object.assign(new Error(`three.ws ${path} timed out after ${HTTP_TIMEOUT_MS}ms`), {+ code: 'timeout',+ });+ }+ throw Object.assign(new Error(`three.ws ${path} request failed: ${err?.message || err}`), {+ code: 'network_error',+ });+ }+ clearTimeout(timer);++ const text = await res.text();+ let data;+ try {+ data = text ? JSON.parse(text) : {};+ } catch {+ data = { raw: text };+ }++ if (!res.ok) {+ const message =+ data?.error_description || data?.message || data?.error || `three.ws ${path} returned HTTP ${res.status}`;+ throw Object.assign(new Error(message), { code: 'upstream_error', status: res.status, body: data });+ }+ return data;+}diff --git a/packages/herald-mcp/src/tools/announce-result.js b/packages/herald-mcp/src/tools/announce-result.jsnew file mode 100644index 000000000..9666c59f2--- /dev/null+++ b/packages/herald-mcp/src/tools/announce-result.js@@ -0,0 +1,93 @@+// `announce_result` — report a finished task with the urgency it deserves.+//+// The importance/tone choice is the part an agent gets wrong, so this tool+// makes it for you from the outcome: a failure is loud enough to cut through+// quiet hours, a success is not.++import { z } from 'zod';++import { apiRequest } from '../lib/api.js';++const IMPORTANCE = { failed: 95, needs_input: 90, succeeded: 65 };+const TONE = { failed: 'error', needs_input: 'alert', succeeded: 'celebrate' };+const EMOTE = { failed: undefined, needs_input: 'wave', succeeded: 'dance' };++function humanDuration(seconds) {+ if (!Number.isFinite(seconds) || seconds <= 0) return null;+ if (seconds < 60) return `${Math.round(seconds)}s`;+ if (seconds < 3600) return `${Math.round(seconds / 60)}m`;+ return `${(seconds / 3600).toFixed(1)}h`;+}++export const def = {+ name: 'announce_result',+ title: 'Report a finished task in person',+ annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },+ description:+ 'Tell the human how a task went, in person, with the urgency chosen for you from the outcome: ' ++ '`failed` and `needs_input` are loud enough to cut through quiet hours, `succeeded` is not. Pass ' ++ 'the task name, the outcome, and optionally how long it took and where to look. This is the right ' ++ 'tool at the end of anything long enough that the person walked away from it. Returns the queued ' ++ 'announcement.',+ inputSchema: {+ task: z+ .string()+ .trim()+ .min(1)+ .max(120)+ .describe('What was being done, in human words ("the nightly backfill", "your test suite").'),+ outcome: z+ .enum(['succeeded', 'failed', 'needs_input'])+ .describe('How it ended. Drives importance, tone and gesture.'),+ detail: z+ .string()+ .trim()+ .max(160)+ .optional()+ .describe('One short clause of context ("3 tests failing", "waiting on your approval").'),+ seconds: z+ .number()+ .min(0)+ .optional()+ .describe('How long it took, in seconds. Rendered as "in 4m" when given.'),+ url: z+ .string()+ .trim()+ .max(2048)+ .optional()+ .describe('Where to look: the run, the diff, the dashboard.'),+ key: z+ .string()+ .trim()+ .max(120)+ .optional()+ .describe('Dedupe key, so a retry loop reporting the same result says it once.'),+ },+ async handler(args) {+ const took = humanDuration(args.seconds);+ const verb =+ args.outcome === 'succeeded' ? 'finished' : args.outcome === 'failed' ? 'failed' : 'needs you';+ const parts = [`${args.task} ${verb}`];+ if (took) parts[0] += args.outcome === 'succeeded' ? ` in ${took}` : ` after ${took}`;+ if (args.detail) parts.push(args.detail);++ const data = await apiRequest('/api/herald/announce', {+ method: 'POST',+ body: {+ text: parts.join(': ').slice(0, 280),+ importance: IMPORTANCE[args.outcome],+ tone: TONE[args.outcome],+ emote: EMOTE[args.outcome],+ url: args.url,+ key: args.key,+ },+ });+ return {+ ok: true,+ id: data?.id ?? null,+ queued: data?.queued === true,+ said: data?.announcement?.text ?? null,+ importance: IMPORTANCE[args.outcome],+ };+ },+};diff --git a/packages/herald-mcp/src/tools/announce.js b/packages/herald-mcp/src/tools/announce.jsnew file mode 100644index 000000000..ca13ed1f3--- /dev/null+++ b/packages/herald-mcp/src/tools/announce.js@@ -0,0 +1,90 @@+// `announce` — say one line, in person, on the owner's own screen.++import { z } from 'zod';++import { apiRequest } from '../lib/api.js';++export const def = {+ name: 'announce',+ title: 'Tell your human, in person',+ annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },+ description:+ 'Deliver one line to the human who owns this key, in person: their 3D companion walks onto the ' ++ 'browser tab they have open, gestures, and says it, with an optional link to click through. Use ' ++ 'this for the handful of moments that deserve to interrupt someone (a long task finished, a ' ++ 'decision is needed, something broke), not for progress chatter: the client applies an importance ' ++ 'floor, a rate limit, quiet hours and dedupe, so noise is dropped rather than queued. The message ' ++ 'is always delivered to the key owner and nobody else. If no browser is open it expires quietly in ' ++ 'about five minutes; the durable record is the notification inbox, not this. Returns the queued ' ++ 'announcement and how long it stays deliverable.',+ inputSchema: {+ text: z+ .string()+ .trim()+ .min(1)+ .max(280)+ .describe('The line to say out loud. One sentence. Write it as speech, not as a log line.'),+ from: z+ .string()+ .trim()+ .max(60)+ .optional()+ .describe('Who it is from, spoken as attribution ("your build", "Stripe", the agent\'s name).'),+ importance: z+ .number()+ .int()+ .min(0)+ .max(100)+ .optional()+ .describe(+ '0-100, default 70. The client drops anything under its floor (50 by default) and only ' ++ 'lets 90+ through quiet hours. Use 90+ for something broken or blocking, 60-80 for a ' ++ 'finished task, under 50 for something that can wait for the inbox.',+ ),+ url: z+ .string()+ .trim()+ .max(2048)+ .optional()+ .describe('Where clicking through goes: an absolute https URL or a three.ws path.'),+ tone: z+ .enum(['neutral', 'alert', 'celebrate', 'error'])+ .optional()+ .describe('Colours the bubble and picks a default gesture. Default alert.'),+ emote: z+ .enum(['wave', 'dance', 'punch', 'backflip'])+ .optional()+ .describe('Gesture the avatar arrives with. Rigs without it fall back to a wave.'),+ key: z+ .string()+ .trim()+ .max(120)+ .optional()+ .describe(+ 'Dedupe key. Two announcements sharing a key are said once, so a retrying job can call ' ++ 'this every attempt without repeating itself.',+ ),+ },+ async handler(args) {+ const data = await apiRequest('/api/herald/announce', {+ method: 'POST',+ body: {+ text: args.text,+ from: args.from,+ importance: args.importance,+ url: args.url,+ tone: args.tone,+ emote: args.emote,+ key: args.key,+ },+ });+ return {+ ok: true,+ id: data?.id ?? null,+ queued: data?.queued === true,+ expires_in_seconds: data?.expires_in ?? null,+ delivered_to: 'the key owner\'s own live sessions',+ announcement: data?.announcement ?? null,+ };+ },+};diff --git a/packages/herald-mcp/src/tools/check-rail.js b/packages/herald-mcp/src/tools/check-rail.jsnew file mode 100644index 000000000..636bb8832--- /dev/null+++ b/packages/herald-mcp/src/tools/check-rail.js@@ -0,0 +1,42 @@+// `check_rail` — prove the credential and the rail work, without interrupting.++import { z } from 'zod';++import { apiRequest } from '../lib/api.js';+import { THREE_WS_BASE } from '../config.js';++export const def = {+ name: 'check_rail',+ title: 'Check the delivery rail',+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },+ description:+ 'Verify that the configured key works and the delivery rail accepts announcements, without ' ++ 'interrupting anybody: it queues a line at importance 0, which every client drops under its own ' ++ 'floor. Use this once when wiring an agent up, or when announce fails and you need to tell a bad ' ++ 'key apart from an unreachable rail. Returns the base URL and whether the credential was accepted.',+ inputSchema: {+ note: z+ .string()+ .trim()+ .max(60)+ .optional()+ .describe('Optional label recorded on the probe, to tell two agents apart in a log.'),+ },+ async handler(args) {+ await apiRequest('/api/herald/announce', {+ method: 'POST',+ body: {+ text: `herald check${args?.note ? `: ${args.note}` : ''}`,+ importance: 0,+ key: 'herald:mcp:check',+ },+ });+ return {+ ok: true,+ base: THREE_WS_BASE,+ credential: 'accepted',+ interrupted_anyone: false,+ note: 'Queued at importance 0, which every client drops under its own floor.',+ };+ },+};diff --git a/packages/herald-mcp/test/registration.test.mjs b/packages/herald-mcp/test/registration.test.mjsnew file mode 100644index 000000000..e966acbe5--- /dev/null+++ b/packages/herald-mcp/test/registration.test.mjs@@ -0,0 +1,65 @@+// Tool-surface invariants for @three-ws/herald-mcp.+//+// Importing src/index.js is side-effect-free: the stdio transport only connects+// when the file is the process entry point, and buildServer() needs no+// credential to advertise the tool surface. These tests run offline: they never+// touch the network.+//+// Run: node --test packages/herald-mcp/test/registration.test.mjs++import { test } from 'node:test';+import assert from 'node:assert/strict';++import { TOOLS, buildServer } from '../src/index.js';++const EXPECTED_NAMES = ['announce', 'announce_result', 'check_rail'];+// Anything that queues a real interruption is a write.+const WRITE_NAMES = new Set(['announce', 'announce_result']);++test('registers exactly the advertised tools', () => {+ assert.deepEqual(+ TOOLS.map((t) => t.name),+ EXPECTED_NAMES,+ );+});++test('every tool carries a title, a description and a schema', () => {+ for (const tool of TOOLS) {+ assert.ok(tool.title, `${tool.name} needs a title`);+ assert.ok(tool.description?.length > 80, `${tool.name} needs a real description`);+ assert.equal(typeof tool.inputSchema, 'object', `${tool.name} needs an input schema`);+ assert.equal(typeof tool.handler, 'function', `${tool.name} needs a handler`);+ }+});++test('write tools never claim to be read-only, and the probe does', () => {+ for (const tool of TOOLS) {+ const readOnly = tool.annotations?.readOnlyHint === true;+ if (WRITE_NAMES.has(tool.name)) {+ assert.equal(readOnly, false, `${tool.name} queues a real interruption`);+ } else {+ assert.equal(readOnly, true, `${tool.name} should be marked read-only`);+ }+ }+});++test('announce constrains the line the way the API does', () => {+ const schema = TOOLS.find((t) => t.name === 'announce').inputSchema;+ assert.equal(schema.text.safeParse('').success, false);+ assert.equal(schema.text.safeParse('x'.repeat(281)).success, false);+ assert.equal(schema.text.safeParse('Deploy is green').success, true);+ assert.equal(schema.importance.safeParse(101).success, false);+ assert.equal(schema.importance.safeParse(80).success, true);+});++test('announce_result only accepts the three outcomes it maps', () => {+ const schema = TOOLS.find((t) => t.name === 'announce_result').inputSchema;+ for (const outcome of ['succeeded', 'failed', 'needs_input']) {+ assert.equal(schema.outcome.safeParse(outcome).success, true);+ }+ assert.equal(schema.outcome.safeParse('maybe').success, false);+});++test('buildServer constructs without a credential', () => {+ assert.ok(buildServer());+});diff --git a/packages/shipfeed/tests/feed.test.js b/packages/shipfeed/tests/feed.test.jsnew file mode 100644index 000000000..dbb2c76c2--- /dev/null+++ b/packages/shipfeed/tests/feed.test.js@@ -0,0 +1,161 @@+import { describe, it, expect } from 'vitest';+import { buildShipFeed } from '../src/feed.js';+import { groupIntoShips } from '../src/group.js';+import { commitsFromGitLog, normalizeChangelog, GIT_LOG_FORMAT } from '../src/sources.js';++const NUL = String.fromCharCode(0);+const RS = String.fromCharCode(30);++const commit = (sha, message, date, extra = {}) => ({+ sha: sha.padEnd(40, '0'),+ html_url: `https://github.com/o/r/commit/${sha}`,+ parents: [{ sha: 'p' }],+ commit: {+ message,+ author: { name: 'nirholas', date },+ committer: { date },+ },+ author: { login: 'nirholas' },+ ...extra,+});++const entries = [+ {+ date: '2026-08-27',+ title: 'Text-to-3D now has five independent image sources behind it',+ summary:+ 'Every text-to-3D generation starts by painting a concept image. The painter now tries five independent image providers in order under one shared time budget.',+ tags: ['fix', 'infra'],+ link: '/forge',+ },+];++const background = [+ commit('d001', 'docs(seeker): write the dApp Store release runbook', '2026-08-27T07:00:00Z'),+ commit('d002', 'fix(wallet): tell the owner a wallet is unsignable', '2026-08-27T07:30:00Z'),+ commit('d003', 'test(agent-index): cover the backlog drain', '2026-08-27T08:00:00Z'),+];++describe('buildShipFeed', () => {+ const commits = [+ commit('aaa1', 'fix(forge): put every concept image provider on one shared time budget', '2026-08-27T09:00:00Z'),+ commit('bbb2', 'chore(deps): bump ws', '2026-08-27T09:10:00Z'),+ commit('ccc3', 'feat(companion): let the corner avatar deliver a message', '2026-08-26T18:00:00Z'),+ ...background,+ ];++ it('attaches commits to the release note they produced', () => {+ const feed = buildShipFeed({ commits, entries, repo: 'o/r', siteUrl: 'https://three.ws' });+ const release = feed.releases[0];+ expect(release.commits.map((c) => c.shortSha)).toContain('aaa1000');+ expect(release.stats.commits).toBeGreaterThan(0);+ expect(release.url).toBe(+ 'https://three.ws/changelog/2026-08-27-text-to-3d-now-has-five-independent-image-sources-behind-it',+ );+ });++ it('carries a confidence and a reason on every linked commit', () => {+ const feed = buildShipFeed({ commits, entries, repo: 'o/r' });+ for (const c of feed.releases.flatMap((r) => r.commits)) {+ expect(c.confidence).toBeGreaterThan(0);+ expect(Array.isArray(c.why)).toBe(true);+ expect(c.why.length).toBeGreaterThan(0);+ }+ });++ it('groups everything no note claimed into ships', () => {+ const feed = buildShipFeed({ commits, entries, repo: 'o/r' });+ const shipShas = feed.ships.flatMap((s) => s.commits.map((c) => c.shortSha));+ const linkedShas = feed.releases.flatMap((r) => r.commits.map((c) => c.shortSha));+ expect(shipShas.length + linkedShas.length).toBe(commits.length);+ expect(shipShas.some((s) => linkedShas.includes(s))).toBe(false);+ });++ it('reports coverage, audience mix, and velocity', () => {+ const feed = buildShipFeed({ commits, entries, repo: 'o/r', now: Date.parse('2026-08-28T00:00:00Z') });+ expect(feed.stats.commits).toBe(commits.length);+ expect(feed.stats.coverage).toBeGreaterThan(0);+ expect(feed.stats.coverage).toBeLessThanOrEqual(1);+ expect(feed.stats.byAudience.holder + feed.stats.byAudience.developer + feed.stats.byAudience.internal).toBe(+ commits.length,+ );+ expect(feed.stats.velocity.map((v) => v.date)).toEqual(['2026-08-26', '2026-08-27']);+ expect(feed.stats.topAuthors[0]).toEqual({ name: 'nirholas', count: commits.length });+ });++ it('hides machinery at the holder floor and says how much it hid', () => {+ const feed = buildShipFeed({ commits, entries, repo: 'o/r', minAudience: 'holder' });+ const shown = [+ ...feed.releases.flatMap((r) => r.commits),+ ...feed.ships.flatMap((s) => s.commits),+ ];+ expect(shown.some((c) => c.shortSha === 'bbb2000')).toBe(false);+ expect(feed.stats.hidden).toBeGreaterThan(0);+ });++ it('drops release notes from outside the commit window', () => {+ const old = { date: '2020-01-01', title: 'Ancient history', summary: 'Long gone.', tags: [] };+ const feed = buildShipFeed({ commits, entries: [...entries, old], repo: 'o/r' });+ expect(feed.releases.map((r) => r.title)).not.toContain('Ancient history');+ expect(feed.stats.entriesConsidered).toBe(2);+ });++ it('returns an empty but well-formed feed for an empty repository', () => {+ const feed = buildShipFeed({ commits: [], entries: [] });+ expect(feed.releases).toEqual([]);+ expect(feed.ships).toEqual([]);+ expect(feed.stats.commits).toBe(0);+ expect(feed.stats.coverage).toBe(0);+ });+});++describe('groupIntoShips', () => {+ it('splits bursts on a quiet gap and headlines each by its strongest commit', () => {+ const ships = groupIntoShips([+ commit('a1', 'chore: tidy an import', '2026-08-27T09:00:00Z'),+ commit('a2', 'feat(forge): add a provider rung to the painter', '2026-08-27T09:20:00Z'),+ commit('b1', 'fix(wallet): stop a double withdrawal prompt', '2026-08-27T16:00:00Z'),+ ]);+ expect(ships).toHaveLength(2);+ expect(ships[0].commits).toHaveLength(1); // newest ship first+ expect(ships[1].title).toBe('Feature · forge');+ expect(ships[1].commits).toHaveLength(2);+ });+});++describe('commitsFromGitLog', () => {+ it('parses git log output into the same shape the API returns', () => {+ const record = [+ 'f'.repeat(40),+ '2026-08-27T09:00:00Z',+ '2026-08-27T08:55:00Z',+ 'nirholas',+ 'nirholas',+ 'parent1 parent2',+ 'feat(forge): a thing\n\nbody',+ ].join(NUL);+ const [parsed] = commitsFromGitLog(record + RS, { repo: 'o/r' });+ expect(parsed.sha).toBe('f'.repeat(40));+ expect(parsed.parents).toHaveLength(2);+ expect(parsed.commit.committer.date).toBe('2026-08-27T09:00:00Z');+ expect(parsed.html_url).toBe(`https://github.com/o/r/commit/${'f'.repeat(40)}`);+ });++ it('publishes the exact format string it expects', () => {+ expect(GIT_LOG_FORMAT).toContain('%x00');+ expect(GIT_LOG_FORMAT.endsWith('%x1e')).toBe(true);+ });+});++describe('normalizeChangelog', () => {+ it('accepts the three.ws feed shape and a bare array alike', () => {+ const wrapped = normalizeChangelog({ entries });+ const bare = normalizeChangelog(entries);+ expect(wrapped).toEqual(bare);+ expect(wrapped[0].tags).toEqual(['fix', 'infra']);+ });++ it('drops entries with no date or title rather than inventing one', () => {+ expect(normalizeChangelog([{ title: 'no date' }, { date: '2026-08-27' }, null])).toEqual([]);+ });+});diff --git a/public/ship/index.html b/public/ship/index.htmlnew file mode 100644index 000000000..d99ec9e5a--- /dev/null+++ b/public/ship/index.html@@ -0,0 +1,289 @@+<!doctype html>+<html lang="en">+<head>+<meta charset="utf-8" />+<meta name="viewport" content="width=device-width,initial-scale=1" />+<title>Ship log · three.ws</title>+<meta name="description" content="Every three.ws release note joined to the commits that produced it, with a confidence score and the reasoning behind every link." />+<link rel="canonical" href="https://three.ws/ship" />+<link rel="alternate" type="application/rss+xml" title="three.ws ship log" href="/api/ship/feed?format=rss" />+<link rel="stylesheet" href="/nav.css" />+<link rel="stylesheet" href="/footer.css" />+<script>/* three.ws theme boot — no-flash; runtime in /theme-switcher.js */(function(){try{var m=localStorage.getItem('twx_theme');var l=m==='auto'?(window.matchMedia&&window.matchMedia('(prefers-color-scheme: light)').matches):m==='light';document.documentElement.setAttribute('data-theme',l?'light':'dark');}catch(e){document.documentElement.setAttribute('data-theme','dark');}})();</script>+<style>+ body { margin: 0; background: var(--bg-0); color: var(--ink); font-family: var(--font-body); -webkit-font-smoothing: antialiased; }+ .sl-wrap { max-width: 940px; margin: 0 auto; padding: 96px 24px 72px; }++ .sl-hero h1 { font-size: clamp(34px, 5vw, 52px); margin: 0 0 12px; letter-spacing: -0.02em; color: var(--ink-bright); }+ .sl-hero p { color: var(--ink-dim); font-size: 17px; margin: 0 0 8px; line-height: 1.55; max-width: 62ch; }+ .sl-hero a { color: var(--ink); }++ .sl-stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: 10px; margin: 28px 0 0; }+ .sl-stat { background: var(--surface-1); border: 1px solid var(--stroke); border-radius: var(--radius-lg); padding: 14px 16px; }+ .sl-stat-value { font-size: 26px; font-weight: var(--weight-bold); color: var(--ink-bright); font-variant-numeric: tabular-nums; letter-spacing: -0.01em; }+ .sl-stat-label { font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--ink-faint); margin-top: 4px; }+ .sl-spark { display: flex; align-items: flex-end; gap: 2px; height: 30px; margin-top: 6px; }+ .sl-spark span { flex: 1 1 0; background: color-mix(in srgb, var(--success) 55%, transparent); border-radius: 2px 2px 0 0; min-height: 2px; transition: background var(--duration-fast) var(--ease-standard); }+ .sl-spark span:hover { background: var(--success); }++ .sl-controls { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin: 26px 0 0; }+ .sl-filter { background: var(--surface-1); border: 1px solid var(--stroke); color: var(--ink-dim); font-size: 12px; font-weight: var(--weight-semibold); letter-spacing: 0.03em; border-radius: var(--radius-pill); padding: 6px 14px; cursor: pointer; transition: border-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard); }+ .sl-filter:hover { border-color: var(--stroke-strong); color: var(--ink-bright); }+ .sl-filter:focus-visible { outline: 2px solid var(--focus-ring-color); outline-offset: 2px; }+ .sl-filter[aria-pressed="true"] { border-color: var(--success); color: var(--success); background: color-mix(in srgb, var(--success) 8%, transparent); }+ .sl-spacer { flex: 1 1 auto; }++ .sl-section-title { font-size: 12px; text-transform: uppercase; letter-spacing: 0.08em; color: var(--ink-faint); margin: 48px 0 14px; }++ .sl-release { background: var(--surface-1); border: 1px solid var(--stroke); border-radius: var(--radius-lg); padding: 18px 20px; margin-bottom: 12px; transition: border-color var(--duration-fast) var(--ease-standard); }+ .sl-release:hover { border-color: var(--stroke-strong); }+ .sl-release-head { display: flex; align-items: baseline; gap: 10px; flex-wrap: wrap; }+ .sl-date { font-family: var(--font-mono); font-size: 12px; color: var(--ink-faint); letter-spacing: 0.04em; }+ .sl-title { color: var(--ink-bright); font-weight: var(--weight-semibold); font-size: 17px; line-height: 1.35; margin: 0; }+ .sl-title a { color: inherit; text-decoration: none; }+ .sl-title a:hover, .sl-title a:focus-visible { text-decoration: underline; }+ .sl-summary { color: var(--ink-dim); font-size: 14px; line-height: 1.6; margin: 8px 0 0; }+ .sl-tags { margin-top: 10px; display: flex; flex-wrap: wrap; gap: 6px; }+ .sl-tag { font-size: 10px; font-weight: var(--weight-bold); letter-spacing: 0.05em; text-transform: uppercase; border-radius: var(--radius-pill); padding: 2px 8px; border: 1px solid var(--stroke); color: var(--ink-dim); }++ details.sl-commits { margin-top: 14px; border-top: 1px solid var(--stroke); padding-top: 12px; }+ details.sl-commits > summary { cursor: pointer; list-style: none; font-size: 12px; font-family: var(--font-mono); color: var(--ink-faint); display: flex; align-items: center; gap: 8px; }+ details.sl-commits > summary::-webkit-details-marker { display: none; }+ details.sl-commits > summary:focus-visible { outline: 2px solid var(--focus-ring-color); outline-offset: 3px; border-radius: 4px; }+ details.sl-commits > summary::before { content: '+'; display: inline-block; width: 14px; text-align: center; color: var(--ink-dim); }+ details.sl-commits[open] > summary::before { content: '-'; }+ .sl-commit { display: grid; grid-template-columns: 74px 1fr auto; gap: 10px; align-items: baseline; padding: 7px 0; border-bottom: 1px dashed color-mix(in srgb, var(--stroke) 70%, transparent); }+ .sl-commit:last-child { border-bottom: none; }+ .sl-sha { font-family: var(--font-mono); font-size: 12px; color: var(--ink-faint); text-decoration: none; }+ .sl-sha:hover, .sl-sha:focus-visible { color: var(--accent); text-decoration: underline; }+ .sl-commit-text { font-size: 13px; line-height: 1.5; color: var(--ink-dim); }+ .sl-commit-headline { color: var(--ink); font-weight: var(--weight-semibold); }+ .sl-audience { font-size: 10px; text-transform: uppercase; letter-spacing: 0.05em; border-radius: var(--radius-pill); padding: 1px 7px; border: 1px solid var(--stroke); color: var(--ink-faint); white-space: nowrap; }+ .sl-audience-holder { color: var(--success); border-color: color-mix(in srgb, var(--success) 35%, transparent); }+ .sl-audience-developer { color: var(--accent); border-color: color-mix(in srgb, var(--accent) 35%, transparent); }+ .sl-why { background: none; border: none; padding: 0 0 0 6px; font: inherit; font-size: 11px; color: var(--ink-faint); cursor: pointer; font-family: var(--font-mono); }+ .sl-why:hover { color: var(--ink-bright); }+ .sl-why:focus-visible { outline: 2px solid var(--focus-ring-color); outline-offset: 2px; border-radius: 3px; }+ .sl-reasons { grid-column: 1 / -1; margin: 4px 0 6px 84px; font-size: 12px; color: var(--ink-faint); font-family: var(--font-mono); line-height: 1.6; }+ .sl-reasons li { list-style: none; }+ .sl-empty-note { color: var(--ink-faint); font-size: 12px; font-style: italic; margin-top: 12px; }++ .sl-skeleton { background: var(--surface-1); border: 1px solid var(--stroke); border-radius: var(--radius-lg); height: 118px; margin-bottom: 12px; overflow: hidden; position: relative; }+ .sl-skeleton::after { content: ''; position: absolute; inset: 0; transform: translateX(-100%); background: linear-gradient(90deg, transparent, color-mix(in srgb, var(--ink) 6%, transparent), transparent); animation: sl-shimmer 1.4s infinite; }+ @keyframes sl-shimmer { 100% { transform: translateX(100%); } }+ @media (prefers-reduced-motion: reduce) { .sl-skeleton::after { animation: none; } }++ .sl-error { color: var(--ink-dim); font-size: 15px; line-height: 1.6; }+ .sl-error a { color: var(--ink); }+ @media (max-width: 560px) {+ .sl-commit { grid-template-columns: 66px 1fr; }+ .sl-audience { grid-column: 2; justify-self: start; }+ .sl-reasons { margin-left: 0; }+ }+</style>+ <meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1">+ <meta property="og:type" content="website">+ <meta property="og:site_name" content="three.ws">+ <meta property="og:locale" content="en_US">+ <meta property="og:title" content="Ship log · three.ws">+ <meta property="og:description" content="Every three.ws release note joined to the commits that produced it, with a confidence score and the reasoning behind every link.">+ <meta property="og:url" content="https://three.ws/ship">+ <meta property="og:image" content="https://three.ws/api/page-og?s=learn&t=Ship+log&d=Every+release+note%2C+joined+to+the+commits+that+produced+it.&p=%2Fship">+ <meta property="og:image:width" content="1200">+ <meta property="og:image:height" content="630">+ <meta property="og:image:type" content="image/png">+ <meta property="og:image:alt" content="Ship log — three.ws">+ <meta name="twitter:card" content="summary_large_image">+ <meta name="twitter:site" content="@trythreews">+ <meta name="twitter:title" content="Ship log · three.ws">+ <meta name="twitter:description" content="Every three.ws release note joined to the commits that produced it, with a confidence score and the reasoning behind every link.">+ <meta name="twitter:image" content="https://three.ws/api/page-og?s=learn&t=Ship+log&d=Every+release+note%2C+joined+to+the+commits+that+produced+it.&p=%2Fship">+ <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebPage","name":"Ship log","description":"Every three.ws release note joined to the commits that produced it, with a confidence score and the reasoning behind every link.","url":"https://three.ws/ship","isPartOf":{"@type":"WebSite","name":"three.ws","url":"https://three.ws"}}]}</script>+</head>+<body>+ <div id="nav-container"></div>+ <script src="/nav.js"></script>+ <main class="sl-wrap">+ <div class="sl-hero">+ <h1>Ship log</h1>+ <p>The changelog says what shipped. The commit log says how. This page is the join: every release note with the code that produced it underneath, matched by <a href="/docs/shipfeed">an open-source scorer</a> that shows its reasoning and its confidence for every link.</p>+ <p>Feeds: <a href="/api/ship/feed">JSON</a> · <a href="/api/ship/feed?format=rss">RSS</a> · <a href="/api/ship/feed?format=markdown">Markdown</a> · <a href="/changelog">plain changelog</a></p>+ <div class="sl-stats" id="sl-stats" aria-live="polite"></div>+ </div>++ <div class="sl-controls" id="sl-controls" role="group" aria-label="Filter the ship log by audience"></div>++ <div id="sl-content">+ <div class="sl-skeleton" aria-hidden="true"></div>+ <div class="sl-skeleton" aria-hidden="true"></div>+ <div class="sl-skeleton" aria-hidden="true"></div>+ <p class="sr-only" role="status">Loading the ship log.</p>+ </div>+ </main>++ <script type="module">+ const content = document.getElementById('sl-content');+ const statsElt = document.getElementById('sl-stats');+ const controls = document.getElementById('sl-controls');+ const FILTERS = [+ ['internal', 'Everything'],+ ['developer', 'Developers'],+ ['holder', 'Product news'],+ ];+ let audience = 'internal';+ let feed = null;+ let inFlight = null;++ const esc = (s) => String(s ?? '').replace(/[<>&"]/g, (c) => ({ '<': '<', '>': '>', '&': '&', '"': '"' })[c]);++ function fmtDate(iso) {+ try {+ return new Date(iso + 'T00:00:00Z').toLocaleDateString(undefined, { month: 'short', day: 'numeric', year: 'numeric', timeZone: 'UTC' });+ } catch { return iso; }+ }++ function renderStats(f) {+ const v = f.stats.velocity;+ const max = Math.max(1, ...v.map((d) => d.count));+ const bars = v.map((d) => `<span style="height:${Math.max(6, Math.round((d.count / max) * 100))}%" title="${esc(d.date)}: ${d.count} commits"></span>`).join('');+ statsElt.innerHTML = [+ ['Commits read', f.stats.commits],+ ['Release notes', f.stats.releases],+ ['Linked to code', `${Math.round(f.stats.coverage * 100)}%`],+ ['Unannounced', f.stats.orphans],+ ].map(([label, value]) => `+ <div class="sl-stat">+ <div class="sl-stat-value">${esc(value)}</div>+ <div class="sl-stat-label">${esc(label)}</div>+ </div>`).join('') + `+ <div class="sl-stat">+ <div class="sl-spark" role="img" aria-label="Commits per day over the window">${bars}</div>+ <div class="sl-stat-label">Daily commits</div>+ </div>`;+ }++ function commitRow(c) {+ const audienceClass = `sl-audience sl-audience-${esc(c.audience)}`;+ const why = c.why && c.why.length+ ? `<button class="sl-why" type="button" data-sha="${esc(c.sha)}" aria-expanded="false">why ${Math.round((c.confidence || 0) * 100)}%</button>`+ : '';+ return `+ <div class="sl-commit" id="c-${esc(c.shortSha)}">+ <a class="sl-sha" href="${esc(c.url)}" rel="noreferrer">${esc(c.shortSha)}</a>+ <div class="sl-commit-text"><span class="sl-commit-headline">${esc(c.headline)}</span> ${esc(c.summary)}${why}</div>+ <span class="${audienceClass}">${esc(c.audience)}</span>+ </div>`;+ }++ function releaseCard(r) {+ const tags = r.tags.map((t) => `<span class="sl-tag">${esc(t)}</span>`).join('');+ const commits = r.commits.map(commitRow).join('');+ const body = r.commits.length+ ? `<details class="sl-commits"><summary>${r.commits.length} commit${r.commits.length === 1 ? '' : 's'}${r.stats.range ? ` · ${esc(r.stats.range)}` : ''}</summary>${commits}</details>`+ : '<p class="sl-empty-note">No commit in this window matched this note with enough confidence to claim it.</p>';+ return `+ <article class="sl-release">+ <div class="sl-release-head">+ <span class="sl-date">${esc(fmtDate(r.date))}</span>+ <h2 class="sl-title">${r.url ? `<a href="${esc(r.url)}">${esc(r.title)}</a>` : esc(r.title)}</h2>+ </div>+ ${r.summary ? `<p class="sl-summary">${esc(r.summary)}</p>` : ''}+ ${tags ? `<div class="sl-tags">${tags}</div>` : ''}+ ${body}+ </article>`;+ }++ function shipCard(s) {+ return `+ <article class="sl-release">+ <div class="sl-release-head">+ <span class="sl-date">${esc(fmtDate(String(s.start).slice(0, 10)))}</span>+ <h2 class="sl-title">${esc(s.title)}</h2>+ </div>+ <p class="sl-summary">${esc(s.summary)}</p>+ <details class="sl-commits"><summary>${s.commits.length} commit${s.commits.length === 1 ? '' : 's'} · ${esc(s.id)}</summary>${s.commits.map(commitRow).join('')}</details>+ </article>`;+ }++ function render() {+ if (!feed) return;+ renderStats(feed);+ const releases = feed.releases.filter((r) => r.commits.length || audience === 'internal');+ const parts = [];+ if (releases.length === 0 && feed.ships.length === 0) {+ parts.push('<p class="sl-error">Nothing in this window yet. Try <a href="/changelog">the changelog</a>.</p>');+ }+ if (releases.length) {+ parts.push('<h2 class="sl-section-title">Announced</h2>', releases.map(releaseCard).join(''));+ }+ if (feed.ships.length) {+ parts.push(+ '<h2 class="sl-section-title">Unannounced: shipped, never written up</h2>',+ feed.ships.map(shipCard).join(''),+ );+ }+ content.innerHTML = parts.join('');+ content.querySelectorAll('.sl-why').forEach((btn) => {+ btn.addEventListener('click', () => toggleReasons(btn));+ });+ }++ function toggleReasons(btn) {+ const row = btn.closest('.sl-commit');+ const open = btn.getAttribute('aria-expanded') === 'true';+ const existing = row.nextElementSibling;+ if (open && existing && existing.classList.contains('sl-reasons')) existing.remove();+ if (!open) {+ const sha = btn.dataset.sha;+ const commit = [...feed.releases.flatMap((r) => r.commits), ...feed.ships.flatMap((s) => s.commits)].find((c) => c.sha === sha);+ const list = document.createElement('ul');+ list.className = 'sl-reasons';+ list.innerHTML = (commit?.why || []).map((w) => `<li>${esc(w)}</li>`).join('');+ row.after(list);+ }+ btn.setAttribute('aria-expanded', String(!open));+ }++ function renderControls() {+ controls.innerHTML = FILTERS.map(([value, label]) =>+ `<button class="sl-filter" type="button" data-audience="${value}" aria-pressed="${value === audience}">${label}</button>`,+ ).join('') + '<span class="sl-spacer"></span>';+ controls.querySelectorAll('.sl-filter').forEach((btn) => {+ btn.addEventListener('click', () => {+ if (btn.dataset.audience === audience) return;+ audience = btn.dataset.audience;+ renderControls();+ load();+ });+ });+ }++ async function load() {+ content.innerHTML = '<div class="sl-skeleton" aria-hidden="true"></div><div class="sl-skeleton" aria-hidden="true"></div><div class="sl-skeleton" aria-hidden="true"></div>';+ inFlight?.abort();+ const controller = new AbortController();+ inFlight = controller;+ try {+ const res = await fetch(`/api/ship/feed?limit=200&audience=${audience}`, {+ headers: { accept: 'application/json' },+ signal: AbortSignal.any([controller.signal, AbortSignal.timeout(20000)]),+ });+ if (!res.ok) throw new Error('feed ' + res.status);+ feed = await res.json();+ render();+ } catch (err) {+ if (controller.signal.aborted) return;+ content.innerHTML = '<p class="sl-error">The ship log could not be built right now. The <a href="/changelog">changelog</a> is always available, and the raw feed is at <a href="/api/ship/feed">/api/ship/feed</a>.</p>';+ console.error('[ship]', err);+ }+ }++ renderControls();+ load();+ </script>+ <script src="/brand.js" defer></script>+ <div id="footer-container"></div>+ <script src="/footer.js"></script>+ <script type="module" src="/i18n.js"></script>+</body>+</html>