wip

client/browser/src/contentScript/github/codeView.ts

@@ -4,7 +4,7 @@ import { combineLatest, debounceTime, EMPTY, map, mergeMap, Observable, startWit
 import { toLineRangeStrings } from '../../shared/util/toLineRangeStrings'
 import { DEBUG, debugTap } from '../debug'
 import { withDOMElement } from '../detectElements'
-import { annotationsByLine, LINE_CHIPS_CLASSNAME, styledItemChipListParams } from '../ocgUtil'
+import { annotationsByLine, LINE_CHIPS_CLASSNAME, styledChipListParams } from '../ocgUtil'
 
 /**
  * Inject OpenCodeGraph features into the GitHub code view.
@@ -110,7 +110,7 @@ function redraw(annotations: Annotation[]): void {
         const lineEl = document.querySelector(`.react-file-line[data-line-number="${line + 1}"]`)
         if (lineEl) {
             const chipList = createChipList(
-                styledItemChipListParams({
+                styledChipListParams({
                     annotations,
                 })
             )

client/browser/src/contentScript/github/pullRequestFilesView.ts

@@ -3,7 +3,7 @@ import { createChipList } from '@opencodegraph/ui-standalone'
 import { combineLatest, EMPTY, filter, fromEvent, map, mergeMap, startWith, tap, type Observable } from 'rxjs'
 import { DEBUG, debugTap } from '../debug'
 import { withDOMElements } from '../detectElements'
-import { annotationsByLine, LINE_CHIPS_CLASSNAME, styledItemChipListParams } from '../ocgUtil'
+import { annotationsByLine, LINE_CHIPS_CLASSNAME, styledChipListParams } from '../ocgUtil'
 
 /**
  * Inject OpenCodeGraph features into the GitHub pull request files view.
@@ -55,7 +55,7 @@ export function injectOnGitHubPullRequestFilesView(
     )
 }
 
-function getItemChipListElementsAtEndOfLine(lineEl: HTMLElement): HTMLElement[] {
+function getChipListElementsAtEndOfLine(lineEl: HTMLElement): HTMLElement[] {
     // There might be 2 of these in a unified (non-split) diff, since one was added by each of the old
     // and new file's providers.
     return [
@@ -78,12 +78,12 @@ function redraw(file: DiffViewFileVersionData, annotations: Annotation[]): void
             continue
         }
 
-        for (const chipListEl of getItemChipListElementsAtEndOfLine(lineEl)) {
+        for (const chipListEl of getChipListElementsAtEndOfLine(lineEl)) {
             chipListEl.remove()
         }
 
         const chipList = createChipList(
-            styledItemChipListParams({
+            styledChipListParams({
                 annotations: lineAnnotations,
             })
         )
@@ -190,7 +190,7 @@ function fileContentFromDiffViewSelector(fileDiffTableEl: HTMLTableElement, sele
     return els
         .map(el => {
             // Ignore innerText from the OCG chip.
-            const chipListEls = getItemChipListElementsAtEndOfLine(el)
+            const chipListEls = getChipListElementsAtEndOfLine(el)
             for (const chipListEl of chipListEls) {
                 chipListEl.hidden = true
             }

client/browser/src/contentScript/ocgUtil.ts

@@ -17,7 +17,7 @@ export function annotationsByLine(annotations: Annotation[]): { line: number; an
 
 export const LINE_CHIPS_CLASSNAME = 'ocg-line-chips'
 
-export function styledItemChipListParams(
+export function styledChipListParams(
     params: Omit<Parameters<typeof createChipList>[0], 'className' | 'chipClassName' | 'popoverClassName'>
 ): Parameters<typeof createChipList>[0] {
     return {

client/codemirror/src/extension.ts

@@ -1,14 +1,14 @@
 import { Facet, type Extension } from '@codemirror/state'
 import { EditorView } from '@codemirror/view'
 import { type Annotation } from '@opencodegraph/client'
-import { openCodeGraphWidgets } from './itemBlockWidget'
+import { openCodeGraphWidgets } from './blockWidget'
 
 export interface OpenCodeGraphDecorationsConfig {
     createDecoration: (
         container: HTMLElement,
         spec: {
             /**
-             * The leading whitespace on the line of code that the items are attached to.
+             * The leading whitespace on the line of code that the annotations are attached to.
              */
             indent: string | undefined
 

lib/client/src/providerClient/createProviderClient.test.ts

@@ -10,7 +10,7 @@ function testdataFileUri(file: string): string {
 describe('createProviderClient', () => {
     test('simple', async () => {
         const pc = createProviderClient(testdataFileUri('provider.js'))
-        const settings: ProviderSettings = { myItemTitle: 'ABC' }
+        const settings: ProviderSettings = { myTitle: 'ABC' }
 
         // File URI that satisfies the provider's selector.
         expect(

lib/client/src/providerClient/testdata/provider.js

@@ -3,7 +3,7 @@ export default {
   capabilities: () => ({ selector: [{ path: 'foo' }] }),
   annotations: (_params, settings) => [
     {
-      title: settings.myItemTitle,
+      title: settings.myTitle,
       range: { start: { line: 1, character: 2 }, end: { line: 3, character: 4 } },
     },
   ],

lib/schema/src/opencodegraph.schema.json

@@ -33,7 +33,7 @@
           "$ref": "#/definitions/UserInterface"
         },
         "ai": {
-          "description": "Information from the annotation intended for consumption by AI, not humans.222",
+          "description": "Information from the annotation intended for consumption by AI, not humans.",
           "$ref": "#/definitions/AssistantInfo"
         },
         "range": {

lib/ui-standalone/src/chip/Chip.ts

@@ -16,7 +16,7 @@ export function createChip({
     popoverClassName?: string
 }): HTMLElement {
     const el = document.createElement('aside')
-    el.className = clsx(styles.item, className)
+    el.className = clsx(styles.chip, className)
 
     const headerEl = document.createElement('header')
 

web/content/docs/concepts.mdx

@@ -5,22 +5,22 @@ export const info = {
 
 # Concepts
 
-## Items and annotations
+## Annotations
 
-An **item** is a piece of information that is relevant to parts of a code file, such as:
+An annotation is some information that is relevant to parts of a code file, such as:
 
 - A link to an internal wiki page with documentation about a package
 - A link to live logs being printed by a logging statement
 - A design mockup (image) showing how a UI component should appear
 - A user analytics chart showing how often a certain UI button is pressed
 
-The item describes how to present the information to the user and exposes raw information to code AI tools.
+The annotation describes how to present the information to the user and exposes raw information to code AI tools.
 
-An **annotation** attaches an item to one or more ranges in a code file.
+See the [protocol documentation](protocol.mdx) for the schema of annotations.
 
 ## Providers
 
-A provider returns information (items and annotations) about a code file.
+A provider returns annotations for a code file.
 
 A provider is just a program that implements the [provider API](protocol.mdx#provider-api), which is basically: "given a file, return a list of annotations (for ranges in the file)".
 

web/content/docs/protocol.mdx

@@ -98,26 +98,64 @@ interface AnnotationsParams {
 **Response:** `{ result: AnnotationsResult }` or `{ error: { code, integer, data? } }`
 
 ```typescript
-/** Annotations that attach items to specific ranges in the file. */
 type AnnotationsResult = Annotation[]
 
-interface Item {
+/**
+ * An annotation describes information relevant to a file (or a range within a file).
+ */
+interface Annotation {
+  /**
+   * A descriptive title of the annotation.
+   */
   title: string
 
-  /** An external link with more information. */
+  /**
+   * An external URL with more information about the annotation.
+   */
   url?: string
 
-  image?: { url?: string }
+  /**
+   * The human user interface of the annotation, with information for human consumption.
+   */
+  ui?: UserInterface
 
-  // Some fields omitted.
+  /**
+   * Information from the annotation intended for consumption by AI, not humans.
+   */
+  ai?: AssistantInfo
+
+  /**
+   * The range in the file that this annotation applies to. If not set, the annotation applies to the entire file.
+   */
+  range?: { start: Position; end: Position }
 }
 
-interface Annotation {
-  /** The item. */
-  item: Item
+/**
+ * The human user interface of the annotation, with information for human consumption.
+ */
+export interface UserInterface {
+  /**
+   * Text containing additional details for the human, shown when they interact with the annotation.
+   */
+  detail?: string
+  /**
+   * The format of the title and description (Markdown or plain text).
+   */
+  format?: 'markdown' | 'plaintext'
+  /**
+   * If set, this annotation is grouped together with all other annotations with the same `group` value.
+   */
+  group?: string
+}
 
-  /** The range in the file that the item is relevant to. */
-  range: { start: Position; end: Position }
+/**
+ * Information from the annotation intended for consumption by AI, not humans.
+ */
+export interface AssistantInfo {
+  /**
+   * Text content for AI to consume.
+   */
+  content?: string
 }
 
 interface Position {