diff --git a/apps/website/content/docs/chat/api/api-docs.json b/apps/website/content/docs/chat/api/api-docs.json index f84ed9db..42d1db31 100644 --- a/apps/website/content/docs/chat/api/api-docs.json +++ b/apps/website/content/docs/chat/api/api-docs.json @@ -1794,7 +1794,7 @@ { "name": "humanContent", "signature": "humanContent(message: unknown)", - "description": "Renderable content for a human-role message bubble. Most human\nmessages are typed prompts and pass through `messageContent`\nunchanged. A2UI action messages (e.g. form submits, button clicks\non a rendered surface) flow through the same submit channel and\nland in the message stream as a HumanMessage whose content is a\nJSON-serialized `A2uiActionMessage`. Showing the raw JSON as if\nthe user typed it leaks the protocol; per the A2UI v0.9 spec\nthose events resemble tool calls more than user utterances.\n\n`a2uiActionLabel` returns a short human-readable label for\nrecognized action shapes (\"Search flights\", \"Selected flight UA123\",\netc.) — or null for any non-action content, in which case we fall\nback to the original text.", + "description": "Renderable content for a human-role message bubble. Most human\nmessages are typed prompts and pass through `messageContent`\nunchanged. A2UI action messages (e.g. form submits, button clicks\non a rendered surface) flow through the same submit channel and\nland in the message stream as a HumanMessage whose content is a\nJSON-serialized `A2uiActionMessage`. Showing the raw JSON as if\nthe user typed it leaks the protocol; per the A2UI spec\nthose events resemble tool calls more than user utterances.\n\n`a2uiActionLabel` returns a short human-readable label for\nrecognized action shapes (\"Search flights\", \"Selected flight UA123\",\netc.) — or null for any non-action content, in which case we fall\nback to the original text.", "params": [ { "name": "message", diff --git a/apps/website/src/app/page.tsx b/apps/website/src/app/page.tsx index 1192d6be..015d3e80 100644 --- a/apps/website/src/app/page.tsx +++ b/apps/website/src/app/page.tsx @@ -70,7 +70,7 @@ export default async function HomePage() { body="Server-emitted JSON specs become Angular components you already own. Vercel json-render and Google A2UI both supported, with per-component fallback and a readiness gate." bullets={[ 'Per-component fallback API + readiness gate', - 'A2UI v0.9-compatible protocol + Vercel json-render adapter', + 'A2UI v1 + Vercel json-render adapter', 'Renders into your existing component library', 'Server-side schema, client-side trust', ]} diff --git a/apps/website/src/app/render/page.tsx b/apps/website/src/app/render/page.tsx index 06ee2db5..2027a060 100644 --- a/apps/website/src/app/render/page.tsx +++ b/apps/website/src/app/render/page.tsx @@ -60,7 +60,7 @@ export default async function RenderPage() {
MIT Vercel json-render - Google A2UI v0.9-compatible + Google A2UI
@@ -73,13 +73,13 @@ export default async function RenderPage() { body="The agent emits structured UI as JSON. @threadplane/render maps each spec node to one of your Angular components — so the design system stays yours, and the agent gets to assemble it." bullets={[ 'Vercel json-render adapter', - 'Google A2UI v0.9-compatible protocol', + 'Google A2UI protocol', 'Component registry — declare once, use everywhere', 'Server schema, client validation', ]} supportingCards={[ { title: 'json-render', description: 'Vercel adapter.' }, - { title: 'A2UI v0.9-compatible', description: 'Google protocol.' }, + { title: 'A2UI v1', description: 'Google A2UI protocol.' }, { title: 'registry', description: 'Spec → component.' }, ]} cta={{ label: 'See @threadplane/render docs', href: '/docs/render/getting-started/introduction' }} diff --git a/docs/gtm/messaging.md b/docs/gtm/messaging.md index 70d51b37..656dae3c 100644 --- a/docs/gtm/messaging.md +++ b/docs/gtm/messaging.md @@ -34,7 +34,7 @@ Repeat across the site, comparison pages, and content. - "No telemetry" → "**App telemetry off by default**" with link to `libs/telemetry/README.md` for the minimal opt-out package install ping. - "All Angular versions" (pricing) → **real compatibility matrix** with supported/experimental/planned/unsupported. -- "A2UI v1" → **"A2UI v0.9-compatible"** until v1 is verified. +- A2UI: present Threadplane's support as **"A2UI v1"**. Note Google-protocol compatibility without a version number (don't claim a Google "v1"; don't pin Google's protocol to a draft version). - "Threadplane" → **"Threadplane"** (category sweep, with care for substring overlap per existing memory note). ## Contact page (Direction A.v2, locked) diff --git a/docs/superpowers/plans/2026-06-05-a2ui-v1-sweep.md b/docs/superpowers/plans/2026-06-05-a2ui-v1-sweep.md new file mode 100644 index 00000000..e994c1bb --- /dev/null +++ b/docs/superpowers/plans/2026-06-05-a2ui-v1-sweep.md @@ -0,0 +1,205 @@ +# A2UI v1 Consistency Sweep Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the remaining live `v0.9` A2UI references with v1-consistent wording — marketing copy, two source-comment citations (+ the generated chat API-docs), and the GTM messaging rule — while keeping genuine Google citations accurate and history untouched. + +**Architecture:** Pure wording/string edits (no behavior change). Marketing pages are Next.js server components; the two source comments are JSDoc that feed `scripts/generate-api-docs.ts` (regenerate after editing); the GTM rule is a markdown bullet. + +**Tech Stack:** Next.js/TSX, TypeScript (libs), `npm run generate-api-docs` (tsx), markdown. + +**Reference spec:** `docs/superpowers/specs/2026-06-05-a2ui-v1-sweep-design.md` + +**Policy:** Threadplane's A2UI support = "A2UI v1". Name Google's protocol with no version number (no "Google v1", no "v0.9-compatible"). Keep real Google spec URLs (`a2ui.org/specification/v0.9-a2ui/`) as-is. Do not touch CHANGELOG / historical superpowers docs / `.venv`. + +--- + +## Task 1: Marketing copy → v1 + +**Files:** +- Modify: `apps/website/src/app/render/page.tsx` +- Modify: `apps/website/src/app/page.tsx` + +- [ ] **Step 1: Edit `render/page.tsx`** + +Make these three exact replacements: + +Pill — replace: +```tsx + Google A2UI v0.9-compatible +``` +with: +```tsx + Google A2UI +``` + +Bullet (in the `bullets` array) — replace: +```tsx + 'Google A2UI v0.9-compatible protocol', +``` +with: +```tsx + 'Google A2UI protocol', +``` + +Supporting card — replace: +```tsx + { title: 'A2UI v0.9-compatible', description: 'Google protocol.' }, +``` +with: +```tsx + { title: 'A2UI v1', description: 'Google A2UI protocol.' }, +``` + +- [ ] **Step 2: Edit `page.tsx`** + +Replace: +```tsx + 'A2UI v0.9-compatible protocol + Vercel json-render adapter', +``` +with: +```tsx + 'A2UI v1 + Vercel json-render adapter', +``` + +- [ ] **Step 3: Lint** + +```bash +cd /Users/blove/repos/angular-agent-framework +npx eslint apps/website/src/app/render/page.tsx apps/website/src/app/page.tsx +``` +Expected: exit 0, no output. (Lint the files directly; do NOT run `nx lint website`.) + +- [ ] **Step 4: Commit** + +```bash +git add apps/website/src/app/render/page.tsx apps/website/src/app/page.tsx +git commit -m "docs(website): A2UI v1 wording in render + home marketing copy" +``` +(Do not stage `next-env.d.ts` / `tsconfig.tsbuildinfo`.) + +--- + +## Task 2: Source-comment citations + regenerate chat API docs + +**Files:** +- Modify: `libs/chat/src/lib/compositions/chat/chat.component.ts` +- Modify: `libs/chat/src/lib/a2ui/action-label.ts` +- Modify (generated): `apps/website/content/docs/chat/api/api-docs.json` + +- [ ] **Step 1: Edit `chat.component.ts`** + +Replace: +```ts + * the user typed it leaks the protocol; per the A2UI v0.9 spec +``` +with: +```ts + * the user typed it leaks the protocol; per the A2UI spec +``` + +- [ ] **Step 2: Edit `action-label.ts`** + +Replace: +```ts + * Per the A2UI v0.9 spec, action messages flow on the client → agent +``` +with: +```ts + * Per the A2UI spec, action messages flow on the client → agent +``` +**Do NOT** change the `https://a2ui.org/specification/v0.9-a2ui/` URL later in the same comment — it's a real Google spec link. + +- [ ] **Step 3: Regenerate the chat API docs** + +```bash +cd /Users/blove/repos/angular-agent-framework +npm run generate-api-docs 2>&1 | tail -5 +git status --short apps/website/content/docs +git diff --stat apps/website/content/docs/chat/api/api-docs.json +``` +Expected: `apps/website/content/docs/chat/api/api-docs.json` changes; the diff should be limited to the "per the A2UI v0.9 spec" → "per the A2UI spec" text. + +- [ ] **Step 4: Verify the regen diff is limited; fallback if not** + +Run: +```bash +cd /Users/blove/repos/angular-agent-framework +git diff apps/website/content/docs/chat/api/api-docs.json | grep -E "^[+-]" | grep -iv "a2ui spec\|a2ui v0.9 spec" | grep -vE "^(\+\+\+|---)" | head +``` +- If that prints nothing (the only +/- lines are the v0.9→spec swap), good — proceed. +- **If regeneration introduced UNRELATED drift** (other api-docs.json files changed, or large unrelated diffs): discard the regen and hand-edit instead — + ```bash + git checkout -- apps/website/content/docs # revert all generated changes + ``` + then edit ONLY the one description string in `apps/website/content/docs/chat/api/api-docs.json`, changing `per the A2UI v0.9 spec` to `per the A2UI spec` (there is exactly one occurrence — confirm with `grep -c "v0.9" apps/website/content/docs/chat/api/api-docs.json` → was 1, should become 0). + +- [ ] **Step 5: Commit** + +Stage only the two source files and the chat api-docs.json (NOT any other regenerated api-docs file if regen touched them and you kept the regen): +```bash +cd /Users/blove/repos/angular-agent-framework +git add libs/chat/src/lib/compositions/chat/chat.component.ts libs/chat/src/lib/a2ui/action-label.ts apps/website/content/docs/chat/api/api-docs.json +git commit -m "docs(chat): version-agnostic A2UI spec citation; regen api-docs" +``` +If `npm run generate-api-docs` legitimately updated OTHER api-docs.json files with already-merged source changes (pre-existing drift unrelated to this task), do NOT include them — `git checkout -- ` those specific files before committing so this PR stays scoped. + +--- + +## Task 3: GTM messaging rule + final verification + +**Files:** +- Modify: `docs/gtm/messaging.md` + +- [ ] **Step 1: Update the rule** + +In `docs/gtm/messaging.md`, replace the line: +```md +- "A2UI v1" → **"A2UI v0.9-compatible"** until v1 is verified. +``` +with: +```md +- A2UI: present Threadplane's support as **"A2UI v1"**. Note Google-protocol compatibility without a version number (don't claim a Google "v1"; don't say "v0.9-compatible"). +``` + +- [ ] **Step 2: Final verification — no stray live v0.9** + +```bash +cd /Users/blove/repos/angular-agent-framework +grep -rnI -e "v0\.9" libs/chat/src apps/website/src apps/website/content/docs/chat/api docs/gtm 2>/dev/null | grep -v "spec.ts" +``` +Expected: the ONLY remaining hit is `libs/chat/src/lib/a2ui/action-label.ts` line ~32 — the `https://a2ui.org/specification/v0.9-a2ui/` Google URL. Nothing in marketing, gtm, or api-docs. If anything else remains, fix it per the policy. + +- [ ] **Step 3: Pages render** + +```bash +cd /Users/blove/repos/angular-agent-framework +lsof -ti tcp:3000 >/dev/null 2>&1 || (export PATH=/Users/blove/.nvm/versions/node/v22.14.0/bin:$PATH && npx nx serve website --port 3000 > /tmp/wd-sweep.log 2>&1 &) +sleep 25 +for p in "/" "/render" "/docs/chat/api/provide-chat"; do curl -s -o /dev/null -w "$p %{http_code}\n" "http://localhost:3000$p"; done +curl -s http://localhost:3000/render | grep -o "Google A2UI" | head -1 +curl -s http://localhost:3000/render | grep -o "v0.9-compatible" | head -1 || echo "no v0.9-compatible on /render (good)" +``` +Expected: all routes 200; "Google A2UI" present on /render; no "v0.9-compatible". + +- [ ] **Step 4: Commit** + +```bash +cd /Users/blove/repos/angular-agent-framework +git add docs/gtm/messaging.md +git commit -m "docs(gtm): A2UI v1 messaging rule" +``` + +--- + +## Manual verification + +- [ ] `/render` and home show "A2UI v1" / "Google A2UI" (no "v0.9-compatible"). +- [ ] The chat API-docs page renders and the HumanMessageContent description reads "per the A2UI spec". +- [ ] `git log` shows only the intended files changed; CHANGELOG and historical superpowers docs untouched; the Google spec URL preserved. + +## Self-Review (completed during planning) + +- **Spec coverage:** Marketing copy (render ×3, home ×1) ✓ (Task 1). Source comments + api-docs regen with fallback ✓ (Task 2). GTM rule ✓ (Task 3). Google URL preserved (explicit "do not change" in Task 2 Step 2 + the verification expecting it to remain). History/`.venv` untouched (not in any task; final grep scoped to live dirs). ✓ +- **Placeholder scan:** No TBD/TODO; every edit shows exact old→new strings; commands have expected output; the regen has a concrete fallback. +- **Consistency:** "A2UI v1" used where we state our support; bare "Google A2UI" where naming the protocol — consistent across Task 1 edits and the Task 3 gtm rule. The final grep's expected single remaining hit (the Google URL) matches the Task 2 instruction to preserve it. diff --git a/docs/superpowers/specs/2026-06-05-a2ui-v1-sweep-design.md b/docs/superpowers/specs/2026-06-05-a2ui-v1-sweep-design.md new file mode 100644 index 00000000..a7310417 --- /dev/null +++ b/docs/superpowers/specs/2026-06-05-a2ui-v1-sweep-design.md @@ -0,0 +1,92 @@ +# A2UI v1 Consistency Sweep — Design + +**Date:** 2026-06-05 +**Status:** Draft for review +**Scope:** Remove the remaining live `v0.9` A2UI references so the repo presents Threadplane's A2UI support as **v1** explicitly and consistently — marketing copy, source-comment citations (+ the generated chat API docs), and the GTM messaging rule. Google-protocol citations stay accurate; historical records are untouched. + +## Goal + +The code, cockpit example, and library docs already use `version: 'v1'`. What +remains are stray `v0.9` strings in **marketing copy**, two **source-comment +citations** (which flow into a generated API-docs JSON), and an obsolete **GTM +messaging rule**. This sweep aligns all of those on v1. + +## Policy (decided) + +- **Threadplane's A2UI support is `v1`.** Where we state our support level, say + "A2UI v1". +- **Name Google's protocol without a version number** where we claim + compatibility (no "Google A2UI v1" — Google has no v1; no "v0.9-compatible" + either, going forward). +- **Cite Google accurately:** real links to Google's spec (e.g. + `a2ui.org/specification/v0.9-a2ui/`) stay as-is — that page really is v0.9. +- **Don't rewrite history:** `CHANGELOG.md` and `docs/superpowers/plans|specs/*` + keep their `v0.9` references (accurate records of past work). Third-party + `.venv` is never touched. + +## Changes + +### 1. Marketing copy + +`apps/website/src/app/render/page.tsx`: +- Pill (≈ line 63): `Google A2UI v0.9-compatible` → `Google A2UI`. +- Bullet (≈ line 76): `Google A2UI v0.9-compatible protocol` → `Google A2UI protocol`. +- Supporting card (≈ line 82): `{ title: 'A2UI v0.9-compatible', description: 'Google protocol.' }` + → `{ title: 'A2UI v1', description: 'Google A2UI protocol.' }`. + +`apps/website/src/app/page.tsx`: +- Bullet (≈ line 73): `A2UI v0.9-compatible protocol + Vercel json-render adapter` + → `A2UI v1 + Vercel json-render adapter`. + +### 2. Source-comment citations (version-agnostic) + +`libs/chat/src/lib/compositions/chat/chat.component.ts` (≈ line 371): +- `per the A2UI v0.9 spec` → `per the A2UI spec`. + +`libs/chat/src/lib/a2ui/action-label.ts` (≈ line 7): +- `Per the A2UI v0.9 spec, action messages flow…` → `Per the A2UI spec, action messages flow…`. +- **Leave line ~32 unchanged** — `https://a2ui.org/specification/v0.9-a2ui/` is a + real Google spec URL (accurate citation). + +### 3. Regenerate the chat API docs + +`apps/website/content/docs/chat/api/api-docs.json` embeds the +`chat.component.ts` HumanMessageContent JSDoc (currently contains "per the A2UI +v0.9 spec"). After editing the source comment, regenerate via +`apps/website/scripts/generate-api-docs.ts` (the project's api-docs generator). +Verify the resulting diff is limited to the changed sentence (no unrelated +drift). **Fallback:** if regeneration pulls in unrelated changes, instead edit +only that one description string in the JSON to `per the A2UI spec` so source and +generated docs stay in sync. + +### 4. GTM messaging rule + +`docs/gtm/messaging.md` (≈ line 37): +- Replace `"A2UI v1" → **"A2UI v0.9-compatible"** until v1 is verified.` with a + rule stating: present Threadplane's A2UI support as **"A2UI v1"**; note + Google-protocol compatibility *without* a version number (don't claim a Google + "v1", don't say "v0.9-compatible"). + +## Testing & verification + +- **Type/lint:** `eslint` the changed `.ts`/`.tsx` files; `tsc --noEmit` shows no + new errors in them (comment-only + string-literal changes — low risk). +- **No stray live v0.9:** after the change, + `grep -rnI -e "v0\.9" libs/chat/src apps/website/src apps/website/content/docs/chat/api docs/gtm | grep -v spec` + returns only the legitimate Google spec URL in `action-label.ts:32` (and + nothing in marketing / gtm / api-docs). +- **Pages render:** `/render` and `/` (home) return HTTP 200 and show the new + wording; `/docs/chat/...` api page still renders. +- **Build sanity:** the website still type-checks/builds (the marketing pages are + server components; string changes only). + +## Out of scope + +- Historical `CHANGELOG.md` / `docs/superpowers/plans|specs/*` (kept accurate to + when the work shipped). +- The cockpit example **envelope-name** staleness (`createSurface` etc. in + `cockpit/chat/a2ui/python/prompts|docs`) — that's a wrong-*format* issue, not a + version string, and a separate follow-up. (The version strings there are + already `v1`.) +- Any change to the actual `version: 'v1'` value or A2UI behavior — this is a + wording/consistency sweep only. diff --git a/libs/chat/src/lib/a2ui/action-label.ts b/libs/chat/src/lib/a2ui/action-label.ts index 2de18d51..517072ec 100644 --- a/libs/chat/src/lib/a2ui/action-label.ts +++ b/libs/chat/src/lib/a2ui/action-label.ts @@ -4,7 +4,7 @@ * message, so the chat composition can render "Search flights" instead * of a raw `{"version":"v1","action":...}` JSON dump as a user bubble. * - * Per the A2UI v0.9 spec, action messages flow on the client → agent + * Per the A2UI spec, action messages flow on the client → agent * return channel and are framed as typed events (closer to tool calls * than user utterances). The spec is silent on chat-bubble rendering; * Google's "A2UI in Practice" article and the Stream Chat reference diff --git a/libs/chat/src/lib/compositions/chat/chat.component.ts b/libs/chat/src/lib/compositions/chat/chat.component.ts index c294dfda..cad0a713 100644 --- a/libs/chat/src/lib/compositions/chat/chat.component.ts +++ b/libs/chat/src/lib/compositions/chat/chat.component.ts @@ -368,7 +368,7 @@ export class ChatComponent { * on a rendered surface) flow through the same submit channel and * land in the message stream as a HumanMessage whose content is a * JSON-serialized `A2uiActionMessage`. Showing the raw JSON as if - * the user typed it leaks the protocol; per the A2UI v0.9 spec + * the user typed it leaks the protocol; per the A2UI spec * those events resemble tool calls more than user utterances. * * `a2uiActionLabel` returns a short human-readable label for