v6.0.0-beta.2

.claude/logs/agent-3-impl-v6.0.0-beta.2.md

@@ -0,0 +1,111 @@
+# Agent-3 Implementation Log — v6.0.0-beta.2 (comment sidebar events)
+
+Branch: `v6.0.0-beta.2` (off `main`). Prior attempt blocked by OS permission issue; this run started fresh and made all edits.
+
+## Scope (Agent-3 only)
+data-models.mdx (§1), api-methods.mdx (§2 — verify/skip), comments/customize-behavior.mdx event table (§3), CREATE version-6/upgrade-guide.mdx (§4), docs.json nav (§5). Sidebar component/wireframe/primitive pages are owned by Agents 4 & 5 — NOT touched.
+
+---
+
+## 1. `api-reference/sdk/models/data-models.mdx`
+
+### 1a. Removed 9 rows from `VeltCommentsSidebarV2Props` table (verified by prop NAME, not line number)
+Deleted (all confirmed within the `VeltCommentsSidebarV2Props` table only):
+- `onSidebarOpen`
+- `onSidebarClose`
+- `onCommentClick`
+- `onCommentNavigationButtonClick`
+- `sortData`
+- `enableUrlNavigation`
+- `openSidebar` (deprecated alias)
+- `sidebarCommentClick` (deprecated alias)
+- `onSidebarCommentClick` (deprecated alias)
+
+KEPT (untouched, verified present): `onFullscreenClick`, `urlNavigation`, `sortBy`, `sortOrder`.
+
+### 1b. Added 4 payload interfaces
+Placed immediately after `CommentBubbleClickedEvent` (before `CommentSavedEvent`), in the comment-events cluster. Matched the existing `#### Name` + `---` + field-table pattern. Added a one-line "Subscribe via `commentElement.on(...)`" lead per interface (consistent with the JSDoc-style descriptions in the raw note).
+
+- `#### SidebarOpenEvent` → `metadata?` only. Anchor: `#sidebaropenevent`
+- `#### SidebarCloseEvent` → `metadata?` only. Anchor: `#sidebarcloseevent`
+- `#### CommentClickEvent` → `documentId?`, `location?`, `targetElementId?`, `context?`, `annotation?`, `metadata?`. Anchor: `#commentclickevent`
+- `#### CommentNavigationButtonClickEvent` → "Extends `CommentClickEvent` with no additional fields." Anchor: `#commentnavigationbuttonclickevent`
+
+**Link handling for referenced types** (grep-confirmed anchors exist → linked, NO broken links):
+- `Location` → `#location` (exists at `## Location` / `#### Location`). LINKED.
+- `CommentAnnotation` → `#commentannotation` (exists at line 5). LINKED.
+- `VeltEventMetadata` → `#velteventmetadata` (exists). LINKED.
+- `CommentClickEvent` self-reference from `CommentNavigationButtonClickEvent` → `#commentclickevent`. LINKED.
+
+### 1c. CommentEventTypesMap / CommentEventTypes
+Grep-confirmed: NO `CommentEventTypesMap` / `CommentEventTypes` / `CommentEventType` section exists in data-models.mdx today (only `SuggestionEventTypesMap` exists, at ~line 7944). Per plan Flag #1 recommendation (b), did NOT fabricate an incomplete map. Added only the 4 payload interfaces + the customize-behavior table rows. **No map section created.**
+
+---
+
+## 2. `api-reference/sdk/api/api-methods.mdx`
+NO edit. The `#### on()` entry (line ~745) does not enumerate individual events — it links out to `customize-behavior#on` for the event list and to `data-models#comment` for payload types. There is no per-event enumeration on this page to extend (plan §2 confirms "no per-event method entries are strictly required"). Returns/Params links unchanged and still resolve (no `CommentEventTypesMap` section was created, so the existing `#comment` link is untouched). V1 methods `onCommentClick()` / `enableSidebarUrlNavigation()` left intact (scope guard).
+
+---
+
+## 3. `async-collaboration/comments/customize-behavior.mdx` — Event Subscription table
+Appended 4 rows under the existing `Comment Sidebar` category (after `commentSidebarDataInit` / `commentSidebarDataUpdate`), matching the exact `| Category | \`event\` | Description | [PayloadEvent](anchor) |` format:
+- `sidebarOpen` → `#sidebaropenevent`
+- `sidebarClose` → `#sidebarcloseevent`
+- `commentClick` → `#commentclickevent`
+- `commentNavigationButtonClick` → `#commentnavigationbuttonclickevent`
+
+Subscribe example block: LEFT AS-IS. The block uses `addCommentAnnotation` as the canonical generic "how to subscribe to any event" demo for the whole table (both React `useCommentEventCallback` and HTML `commentElement.on().subscribe`). It is not per-event; rewriting the canonical example to `commentClick` would diverge from the established convention without benefit. The 4 new events are fully documented via the table + payload links. Decision noted.
+
+---
+
+## 4. CREATE `release-notes/version-6/upgrade-guide.mdx`
+Did not exist on this branch. Created beta.2-specific (no beta.1 modular-SDK / Approval Engine content). Mirrored beta.1 structure:
+- Frontmatter: `title: Upgrade Guide` + the required `description`.
+- `## Overview` (bulleted)
+- `## Breaking Changes` with `[**Area**]` bullets (3 changes)
+- `## How to Upgrade` with numbered subsections, each using `<Tabs>` (React / Next.js first, Other Frameworks second), Before/After per the raw note's literal snippets.
+
+Three breaking changes documented:
+1. V2 sidebar events → `on()` bus (removed-props list, `onFullscreenClick`-remains note, React + HTML before/after).
+2. `sortData` / `sort-data` removed → `sortBy` / `sortOrder` (React + HTML before/after).
+3. `enableUrlNavigation` / `enable-url-navigation` removed → `urlNavigation` / `url-navigation` (React + HTML before/after).
+
+Breaking changes live ONLY in the upgrade guide (not the changelog).
+
+---
+
+## 5. `docs.json` navigation
+Added `Version 6.0.0` group as the FIRST child of `tab: "Release Notes"` → `group: "Release Notes"` → `pages`, immediately above `Version 5.0.0`, mirroring beta.1 exactly:
+```json
+{
+  "group": "Version 6.0.0",
+  "pages": [
+    "release-notes/version-6/upgrade-guide",
+    "release-notes/version-6/sdk-changelog"
+  ]
+}
+```
+No existing entries reordered/removed. Validated: `python3 -m json.tool docs.json > /dev/null` → VALID.
+
+---
+
+## Anchor slugs for downstream agents (4/5/6/7)
+- `/api-reference/sdk/models/data-models#sidebaropenevent`
+- `/api-reference/sdk/models/data-models#sidebarcloseevent`
+- `/api-reference/sdk/models/data-models#commentclickevent`
+- `/api-reference/sdk/models/data-models#commentnavigationbuttonclickevent`
+
+## Canonical event keys / replacements (unchanged from plan)
+- Event keys: `sidebarOpen`, `sidebarClose`, `commentClick`, `commentNavigationButtonClick`
+- `sortData` → `sortBy` + `sortOrder`; `enableUrlNavigation` / `enable-url-navigation` → `urlNavigation` / `url-navigation`
+- Removed V2 props: `onSidebarOpen`, `openSidebar`, `onSidebarClose`, `onCommentClick`, `onSidebarCommentClick`, `sidebarCommentClick`, `onCommentNavigationButtonClick`, `sortData`, `enableUrlNavigation`
+- Retained: `onFullscreenClick`
+
+## Files changed
+- `api-reference/sdk/models/data-models.mdx` (9 rows removed; 4 interfaces added)
+- `async-collaboration/comments/customize-behavior.mdx` (4 table rows added)
+- `release-notes/version-6/upgrade-guide.mdx` (CREATED)
+- `docs.json` (Version 6.0.0 nav group added; validated)
+
+## Handoff
+Agent-4: V2 sidebar behavior page (`comments-sidebar/v2/customize-behavior.mdx`) event/prop migration + wireframe verify. Agent-5: V2 primitives prop cleanup. Both link to the 4 anchors above.

.claude/logs/agent-4-impl-v6.0.0-beta.2.md

@@ -0,0 +1,63 @@
+# Agent-4 Implementation Log — v6.0.0-beta.2 (Comment Sidebar V2 events/props migration)
+
+Branch: `v6.0.0-beta.2`
+Scope: Behavior page + wireframes (NOT primitives, NOT data-models, NOT api-methods).
+Date: 2026-06-24
+
+## Files touched
+
+### 1. async-collaboration/comments-sidebar/v2/customize-behavior.mdx — EDITED (5 changes)
+
+**a) `#### sortData` block — REMOVED.**
+- Before: `#### sortData` section with React `<VeltCommentsSidebarV2 sortData="comments.createdAt" />` + HTML `sort-data="..."` examples.
+- After: removed entirely. Canonical `#### sortBy` and `#### sortOrder` blocks remain above it (unchanged) under `# Sorting`.
+
+**b) `#### onCommentClick` → `#### commentClick` — REWRITTEN.**
+- Before: `onCommentClick` prop on `<VeltCommentsSidebarV2>` (React) + `addEventListener('onCommentClick', ...)` reading `event.detail.location` (HTML).
+- After: React `useCommentEventCallback('commentClick')` + `useEffect`; HTML `Velt.getCommentElement().on('commentClick').subscribe(...)`.
+- Payload documented as [`CommentClickEvent`](#commentclickevent); shows reading `annotation`, `documentId`, `targetElementId`, and `location` (navigation use-case prose preserved).
+
+**c) `#### onCommentNavigationButtonClick` → `#### commentNavigationButtonClick` — REWRITTEN.**
+- Before: `onCommentNavigationButtonClick` prop (React) + `addEventListener('onCommentNavigationButtonClick', ...)` (HTML).
+- After: React `useCommentEventCallback('commentNavigationButtonClick')`; HTML `commentElement.on('commentNavigationButtonClick').subscribe(...)`.
+- Payload documented as [`CommentNavigationButtonClickEvent`](#commentnavigationbuttonclickevent) (extends `CommentClickEvent`).
+
+**d) `enableUrlNavigation` `<Note>` — REMOVED.**
+- Before: `<Note>` stating `enableUrlNavigation` is a deprecated alias for `urlNavigation`.
+- After: removed. `#### urlNavigation` block (canonical) left intact directly above it.
+
+**e) `# Events` → `#### onSidebarOpen` / `#### onSidebarClose` → `#### sidebarOpen` / `#### sidebarClose` — REWRITTEN.**
+- Before: `onSidebarOpen` / `onSidebarClose` props (React) + `addEventListener('onSidebarOpen'|'onSidebarClose', ...)` (HTML).
+- After: React `useCommentEventCallback('sidebarOpen'|'sidebarClose')` + `useEffect`; HTML `commentElement.on('sidebarOpen'|'sidebarClose').subscribe(...)`.
+- Payloads documented as [`SidebarOpenEvent`](#sidebaropenevent) / [`SidebarCloseEvent`](#sidebarcloseevent).
+
+### 2. async-collaboration/comments-sidebar/v2/setup.mdx — NO CHANGE NEEDED
+- Grep for all removed props/inputs/event-callbacks returned zero matches. No code example or prop list contained any removed name.
+
+### 3. ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-wireframes.mdx — NO CHANGE NEEDED
+- Grep returned zero matches. Pure wireframe component tree; no removed prop strings present. Matches plan §4a (verified clean, no-op).
+
+### 4. ui-customization/features/async/comments/comment-sidebar-structure-v2.mdx — NO CHANGE NEEDED
+- Grep returned zero matches. Pure component tree, no props. Matches plan §4a (no-op).
+
+## Verification (post-edit greps on customize-behavior.mdx)
+- Removed-prop scan (`onSidebarOpen|openSidebar|onSidebarClose|onCommentClick|onSidebarCommentClick|sidebarCommentClick|onCommentNavigationButtonClick|sortData|sort-data|enableUrlNavigation|enable-url-navigation`): **zero remaining**.
+- `onFullscreenClick` (must be preserved): present at 3 locations (prose bullet + React prop example + HTML `addEventListener`) — **unchanged**.
+- All 4 new event keys present via `useCommentEventCallback('<key>')` (React) and `commentElement.on('<key>').subscribe(...)` (HTML, using `Velt.getCommentElement()`).
+- Tab ordering: React / Next.js first, Other Frameworks second in all 4 migrated sections — **confirmed**.
+
+## Anchor links used (link in prose only, never in code)
+- `/api-reference/sdk/models/data-models#commentclickevent`
+- `/api-reference/sdk/models/data-models#commentnavigationbuttonclickevent`
+- `/api-reference/sdk/models/data-models#sidebaropenevent`
+- `/api-reference/sdk/models/data-models#sidebarcloseevent`
+(Agent-3 owns adding these 4 payload interfaces to data-models.mdx — confirm anchors resolve.)
+
+## Convention notes
+- React code uses `client.getCommentElement()` for API methods elsewhere on this page; the new event examples use the `useCommentEventCallback` hook (no `client`/`Velt` needed in React tab). HTML tab uses `Velt.getCommentElement()` per convention.
+- HTML examples use `const commentElement = Velt.getCommentElement(); commentElement.on(...)` per the release-note migration pattern.
+
+## Handoffs
+- **Agent-5 (primitives):** Plan §4b — `comment-sidebar-v2-primitives.mdx` still carries the 4 removed callback props (`onSidebarOpen`/`onSidebarClose`/`onCommentClick`/`onCommentNavigationButtonClick`) in 2 React examples + the props table. NOT touched by Agent-4 (out of scope). Agent-5 to remove them.
+- **Agent-6 (alignment):** Canonical replacements to enforce repo-wide: `sortData`→`sortBy`+`sortOrder`; `enableUrlNavigation`/`enable-url-navigation`→`urlNavigation`/`url-navigation`; sidebar `@Output()` callbacks → `on()` bus event keys. Respect scope guard (V1 sidebar, timeline, comment-thread, wireframe-variables `sortData`, historical release notes).
+- **Agent-7 (QA):** Verify zero remaining removed-prop strings in the 4 Agent-4 files; verify `onFullscreenClick` retained; verify 4 data-models anchors resolve once Agent-3's interfaces land.

.claude/logs/agent-5-impl-v6.0.0-beta.2.md

@@ -0,0 +1,82 @@
+# Agent-5 Implementation Log — v6.0.0-beta.2
+
+**Branch:** `v6.0.0-beta.2`
+**Date:** 2026-06-24
+**Scope (plan §4b):** Comment Sidebar V2 PRIMITIVES page — remove deprecated/removed callback props.
+
+## File touched (ONLY this one)
+`ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives.mdx`
+
+## Removed props (this release removed them from `VeltCommentsSidebarV2` / `velt-comments-sidebar-v2`)
+Target set: `onSidebarOpen`, `openSidebar`, `onSidebarClose`, `onCommentClick`, `onSidebarCommentClick`,
+`sidebarCommentClick`, `onCommentNavigationButtonClick`, `sortData`/`sort-data`,
+`enableUrlNavigation`/`enable-url-navigation`.
+
+Pre-edit grep found only 4 of them actually present in this file (the page documented only
+`onSidebarOpen`/`onSidebarClose`/`onCommentClick`/`onCommentNavigationButtonClick`).
+`openSidebar`, `onSidebarCommentClick`, `sortData`, `enableUrlNavigation` were NOT present here
+(they live on the data-models props table + behavior page, owned by Agent-3/Agent-4 — out of my scope).
+
+## Before / After (every removal)
+
+### 1. Pattern 1: Drop-in Replacement — React/JSX example (was lines ~38-49)
+Removed 4 prop lines from the `<VeltCommentsSidebarV2 ... />` example:
+- `onSidebarOpen={(data) => console.log('sidebar opened', data)}`
+- `onSidebarClose={(data) => console.log('sidebar closed', data)}`
+- `onCommentClick={(data) => console.log('comment clicked', data)}`
+- `onCommentNavigationButtonClick={(data) => console.log('nav button clicked', data)}`
+Kept: `pageMode`, `focusedThreadMode`, `readOnly`, `position`, `variant`, `forceClose`.
+HTML (Other Frameworks) example already omitted them — left as-is.
+
+### 2. `### VeltCommentsSidebarV2` component — React/JSX example (was lines ~131-144)
+Removed the same 4 prop lines from the `<VeltCommentsSidebarV2 ... />` example.
+Kept: `pageMode`, `focusedThreadMode`, `readOnly`, `embedMode`, `floatingMode`, `position`, `variant`, `forceClose`.
+HTML (Other Frameworks) example already omitted them — left as-is.
+
+### 3. `### VeltCommentsSidebarV2` — Props table (was lines ~160-163)
+Removed 4 table rows:
+- `| `onSidebarOpen` | `(data: any) => void` | - | Callback fired when the sidebar opens |`
+- `| `onSidebarClose` | `(data: any) => void` | - | Callback fired when the sidebar closes |`
+- `| `onCommentClick` | `(data: any) => void` | - | Callback fired when a comment item is clicked |`
+- `| `onCommentNavigationButtonClick` | `(data: any) => void` | - | Callback fired when the comment navigation button is clicked |`
+Table now ends at the `version` row; header + separator + 9 data rows = well-formed.
+
+Added one concise cross-link note (option (a)+light pointer) right after the React props table,
+inside the React tab:
+> The sidebar open/close, comment-click, and comment-navigation events are now delivered through
+> the `commentElement.on()` event bus instead of props. See the
+> [comment event subscription table](/async-collaboration/comments/customize-behavior#event-subscription)
+> for `sidebarOpen`, `sidebarClose`, `commentClick`, and `commentNavigationButtonClick`.
+> `onFullscreenClick` remains a prop callback.
+
+Rationale: this is a structure/primitive page, not an event-subscription tutorial, so per the brief I
+defaulted to minimal removal + a single pointer to the event table (which Agent-3 populated). No
+`useCommentEventCallback` tutorial was added here (that belongs on the behavior page — Agent-4).
+
+## Verification
+- Final grep for ALL removed-prop names in the file → 0 matches (`grep` exit 1). No legitimate unrelated matches existed.
+- Retained: `onFullscreenClick` present at the new cross-link note + existing prose
+  ("emits `onFullscreenClick` when activated" on the FullscreenButton primitive). KEPT.
+- `urlNavigation` / `sortBy` / `sortOrder` were never documented on this primitives page (root example
+  carries only a prop subset); nothing to retain there and nothing was accidentally removed.
+- Props table well-formed: `| Prop | Type | Default | Description |` header + separator + 9 rows, blank
+  line before the cross-link note. Other Frameworks attributes table untouched and valid.
+- Cross-link anchor verified: `# Event Subscription` heading exists at line 3546 of
+  `async-collaboration/comments/customize-behavior.mdx` → resolves to `#event-subscription`.
+- Tabs order preserved: `React / Next.js` first, `Other Frameworks` second.
+
+## Scope guard respected
+- Did NOT touch: data-models.mdx, api-methods.mdx, comments-sidebar/v2/customize-behavior.mdx,
+  setup/wireframes pages, V1 sidebar, comment-sidebar-v2-wireframes.mdx, comment-sidebar-structure-v2.mdx.
+- Only the one primitives file was modified.
+
+## Notes for Agent-6 / Agent-7
+- Canonical event keys to align on this page if QA touches it: `sidebarOpen`, `sidebarClose`,
+  `commentClick`, `commentNavigationButtonClick` (camelCase, in the new cross-link note).
+- The new cross-link points to `/async-collaboration/comments/customize-behavior#event-subscription`.
+  Agent-6/7: if the canonical anchor slug for that table differs after Agent-3's edits, update this one
+  link accordingly. Currently verified valid.
+- No `sortData`/`enableUrlNavigation` ever existed on this primitives page — no canonical-rename work
+  needed here (those renames `sortData→sortBy/sortOrder`, `enableUrlNavigation→urlNavigation` apply to
+  data-models/behavior pages, not this file).
+- Component count text ("56+", "All 56 primitives") unchanged — no primitives added/removed, only props.