@oddkin/ai 0.0.0-stage → 1.0.0-beta.0

package/agent/references/components/odd-citation.md

@@ -0,0 +1,76 @@
+# `<odd-citation>` (OddkinCitation)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+An inline citation marker with an accessible preview of its source. A missing source record
+renders as an unresolved reference; nothing is invented.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/citation';`
+- Class: `import { OddkinCitation } from '@oddkin/ai/citation';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `sourceId` | `source-id` | string | '' | Citation key (`[^key]`). |
+| `index` | `index` | number | 0 | Display number; 0 shows the key. |
+| `source` | none: assign as a property | { type: "source"; id: string; sourceId: string; url?: string \| undefined; title?: string \| undefined; kind?: "file" \| "web" \| "document" \| "other" \| undefined; excerpt?: string \| undefined; publisher?: string \| undefined; } \| undefined | undefined | The source record; undefined renders an unresolved reference. |
+| `strings` | none: assign as a property | Partial<{ source: string; unresolved: string; unavailable: string; open: string; show: string; untitled: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-citation-open` | CustomEvent<{ readonly sourceId: string; readonly resolved: boolean; }> | user (authored) | A citation was activated. The default reveals the source; cancel to navigate yourself. |
+| `odd-source-reveal` | CustomEvent<{ readonly sourceId: string; }> | user (authored) | Default action of odd-citation-open: the nearest message reveals the source. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `preview` | The source preview. |
+| `trigger` | The marker button. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Inline references from generated text to its sources. (src/citation/citation.ts:43)
+- Not for: Footnotes in authored documents; use links. (src/citation/citation.ts:44)
+- Accessibility: The marker is a button named after the source ("Source 2: Title"); `aria-expanded` reflects the preview. The preview is ordinary content after the button, so screen readers and touch users reach it without hover. (src/citation/citation.ts:41)
+- Keyboard: Enter or Space toggles the preview; Escape closes it and returns focus to the marker. (src/citation/citation.ts:42)
+
+## Examples
+
+- `example:odd-citation/default` in src/citation/citation.examples.ts (package source)
+- `example:odd-citation/unresolved` in src/citation/citation.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 19 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/components/odd-context-picker.md

@@ -0,0 +1,78 @@
+# `<odd-context-picker>` (OddkinContextPicker)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Select, inspect, and remove the context sent with a request: files, documents, links, and
+selected text. Adding is a request; items appear when the host adds their records.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/context-picker';`
+- Class: `import { OddkinContextPicker } from '@oddkin/ai/context-picker';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | none: assign as a property | { label: string; id: string; status: "failed" \| "selected" \| "uploading" \| "uploaded" \| "processing" \| "ready" \| "removed"; kind: "url" \| "file" \| "document" \| "selection"; url?: string \| undefined; ... 4 more ...; detail?: string \| undefined; }[] | [] | Context item records (host-owned). |
+| `accept` | `accept` | string | '' | File types for "Add files" (as `<input accept>`). |
+| `allowUrls` | `allow-urls` | boolean | false | Offer adding links. |
+| `disabled` | `disabled` (reflects) | boolean | false | Prevents adding and removing. |
+| `strings` | none: assign as a property | Partial<{ label: string; empty: string; addFiles: string; addUrl: string; url: string; add: string; invalidUrl: string; inspect: string; hide: string; remove: string; noPreview: string; file: string; document: string; ... 8 more ...; removed: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-context-add` | CustomEvent<ContextAddDetail> | user (authored) | Request to add context; the item appears once the host adds its record. |
+| `odd-context-remove` | CustomEvent<{ readonly itemId: string; }> | user (authored) | Request to remove a context item. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `add` | Add controls. |
+| `base` | The labelled group around the items and the add controls. |
+| `item` | One item. |
+| `list` | Context items. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Attaching and reviewing context for research and agent requests. (src/context-picker/context-picker.ts:43)
+- Not for: File management. (src/context-picker/context-picker.ts:44)
+- Accessibility: A labelled list; each item names its kind and status in text. Inspect toggles a disclosure (`aria-expanded`). Remove buttons are named after the item. (src/context-picker/context-picker.ts:41)
+- Keyboard: Tab through items and controls; Enter adds a link. (src/context-picker/context-picker.ts:42)
+
+## Examples
+
+- `example:odd-context-picker/default` in src/context-picker/context-picker.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 26 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/components/odd-conversation.md

@@ -0,0 +1,106 @@
+# `<odd-conversation>` (OddkinConversation)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A conversation surface: messages as an ARIA feed, history loading, a follow-latest scrolling
+policy that respects reading earlier content, a visible-anchor guarantee when history is
+prepended or content above changes size, an explicit "Jump to latest", the run status bar,
+one announcer for the whole surface, and a slot for the composer. Reads state from one
+authoritative source (`store` or `state`); keeps only presentation state.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/conversation';`
+- Class: `import { OddkinConversation } from '@oddkin/ai/conversation';`
+- Dependency (activity): `<odd-activity>`
+- Dependency (message): `<odd-message>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `store` | none: assign as a property | ExternalSource<ConversationState> \| undefined | undefined | Authoritative state (a controller or an external store). |
+| `state` | none: assign as a property | ConversationState \| undefined | undefined | Controlled snapshot, used when no `store` is set. |
+| `label` | `label` | string | '' | Accessible name of the feed. |
+| `announce` | `announce` | "none" \| "important" \| "all" | 'important' | How much the surface announces. |
+| `markdown` | none: assign as a property | MarkdownOptions \| undefined | undefined | Markdown options for every message. |
+| `renderers` | none: assign as a property | Readonly<Record<string, DataRenderer>> \| undefined | undefined | Validated renderers for `data` parts. |
+| `artifactRenderers` | none: assign as a property | Readonly<Record<string, ArtifactRenderer>> \| undefined | undefined | Artifact renderers by kind. |
+| `renderTool` | none: assign as a property | { render: ToolOutputRenderer; } \| undefined | undefined | Renderer for tool results. |
+| `feedbackReasons` | none: assign as a property | string[] | [] | Reasons offered for negative feedback. |
+| `strings` | none: assign as a property | Partial<{ label: string; empty: string; loadEarlier: string; loading: string; historyError: string; retry: string; jump: string; jumpNew: string; messageLabel: string; user: string; assistant: string; system: string; tool: string; } & AnnouncementStrings> \| undefined | undefined | Localized string overrides (including announcements). |
+| `snapshot` | none (read-only) | ConversationState \| undefined |  | The snapshot being rendered. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `jumpToLatest()` | Resume following the latest content and move focus to the newest message. |
+| `getScrollPosition()` | The current reading position (to restore later, e.g. per conversation or branch). |
+| `restoreScrollPosition()` | Restore a position from `getScrollPosition()`. Unknown messages fall back to the latest. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-history-request` | CustomEvent<{ readonly conversationId: string; readonly beforeMessageId: string \| undefined; }> | user (authored) | Request to load earlier messages. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `composer` | The prompt input. |
+| `empty` | Content shown when there are no messages. |
+| `status` | Extra status content (usage, model) above the composer. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `activity` | The run status bar. |
+| `base` | The column of the scroll container, the run status, and the composer. |
+| `feed` | The feed of messages. |
+| `jump` | The "Jump to latest" button. |
+| `scroller` | The scroll container. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-conversation-max-width` | Maximum line length of the feed. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Chat and assistant conversations, including tool use, approvals, artifacts, and branches. (src/conversation/conversation.ts:64)
+- Not for: Activity logs without messages; use `odd-task-plan` or `odd-activity`. (src/conversation/conversation.ts:65)
+- Accessibility: Messages are `article`s in a `feed` with position and size; `aria-busy` is set while history loads or a response streams. One polite and one assertive live region announce meaningful changes only (sent, responding, complete, stopped, failed, approval needed), never streamed text. Arriving content never moves focus. (src/conversation/conversation.ts:62)
+- Keyboard: Page Down / Page Up move between messages; Ctrl+Home / Ctrl+End leave the feed toward its start or the composer; "Jump to latest" moves focus to the newest message. (src/conversation/conversation.ts:63)
+- Limitations: All messages stay in the DOM (no virtualization) so find-in-page, selection, and assistive technology reading keep working; with 200 messages a streamed snapshot took about 15 ms in Chromium and 30 ms in Firefox (research/experiments/containment, 2026-10-28). (src/conversation/conversation.ts:66)
+
+## Examples
+
+- `example:odd-conversation/default` in src/conversation/conversation.examples.ts (package source)
+- `example:odd-conversation/empty` in src/conversation/conversation.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+- Variables: `--odd-conversation-max-width`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 29 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/components/odd-inline-assist.md

@@ -0,0 +1,84 @@
+# `<odd-inline-assist>` (OddkinInlineAssist)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Selection-based assistance: rewrite, explain, summarize, translate, and expand (or host
+actions). Requests carry the selection with its content revision, so results can be checked
+against the text they were made for. Rewrites become proposals for `odd-change-review`;
+explanations and summaries show in the result area.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/inline-assist';`
+- Class: `import { OddkinInlineAssist } from '@oddkin/ai/inline-assist';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `selection` | none: assign as a property | TextSelection \| undefined | undefined | Captured selection with its content revision. |
+| `documentRevision` | `document-revision` | string | '' | Current content revision; a different selection revision is stale. |
+| `actions` | none: assign as a property | AssistActionOption[] | [] | Actions to offer; defaults to the five built-ins. |
+| `languages` | none: assign as a property | AssistActionOption[] | [] | Target languages for translate (`id` = BCP 47 tag). |
+| `status` | `status` (reflects) | "failed" \| "complete" \| "idle" \| "pending" | 'idle' | Host-reported request state. |
+| `pendingAction` | `pending-action` | string | '' | Action in progress. |
+| `result` | none: assign as a property | string | '' | Explanation or summary text (Markdown). |
+| `error` | none: assign as a property | { code: string; message: string; retryable?: boolean \| undefined; } \| undefined | undefined | Shown when `status` is failed. |
+| `markdown` | none: assign as a property | MarkdownOptions \| undefined | undefined | Options for rendering `result`. |
+| `strings` | none: assign as a property | Partial<{ label: string; rewrite: string; explain: string; summarize: string; translate: string; expand: string; language: string; noSelection: string; stale: string; pending: string; failed: string; selected: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-assist-request` | CustomEvent<AssistRequestDetail> | user (authored) | Request assistance for the captured selection. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The column of the toolbar, the status, and the result. |
+| `result` | Result text (Markdown, rendered inertly). |
+| `toolbar` | The action toolbar. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Contextual help on selected text in editors and documents. (src/inline-assist/inline-assist.ts:42)
+- Not for: Whole-document chat; use the conversation. (src/inline-assist/inline-assist.ts:43)
+- Accessibility: An ARIA toolbar: one tab stop, arrow keys move between actions. Pending and stale states are text. (src/inline-assist/inline-assist.ts:40)
+- Keyboard: Left/Right (or Up/Down) move between actions; Home/End go to the first/last; Enter or Space activates. (src/inline-assist/inline-assist.ts:41)
+
+## Examples
+
+- `example:odd-inline-assist/default` in src/inline-assist/inline-assist.examples.ts (package source)
+- `example:odd-inline-assist/result` in src/inline-assist/inline-assist.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 29 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/components/odd-message-branch.md

@@ -0,0 +1,73 @@
+# `<odd-message-branch>` (OddkinMessageBranch)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Navigate between alternative versions of a message (regenerated answers, edited prompts).
+Every version stays in history; switching only changes which branch is shown.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/message-branch';`
+- Class: `import { OddkinMessageBranch } from '@oddkin/ai/message-branch';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `messageId` | `message-id` | string | '' | The message shown now. |
+| `branch` | none: assign as a property | BranchPosition \| undefined | undefined | Position among sibling versions. |
+| `capabilities` | none: assign as a property | { send?: { available: boolean; reason?: string \| undefined; } \| undefined; stop?: { available: boolean; reason?: string \| undefined; } \| undefined; disconnect?: { available: boolean; reason?: string \| undefined; } \| undefined; ... 12 more ...; feedback?: { ...; } \| undefined; } \| undefined | undefined | `switchBranch` enables navigation. |
+| `strings` | none: assign as a property | Partial<{ label: string; previous: string; next: string; position: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-branch-switch` | CustomEvent<{ readonly messageId: string; readonly targetMessageId: string; }> | user (authored) | Request to show another branch. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The navigation group. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Alternative responses and edited prompts. (src/message-branch/message-branch.ts:21)
+- Not for: Pagination of unrelated content. (src/message-branch/message-branch.ts:22)
+- Accessibility: A labelled group with previous/next buttons and a text position ("Version 2 of 3"). (src/message-branch/message-branch.ts:19)
+- Keyboard: Tab to the buttons; Enter or Space switches. (src/message-branch/message-branch.ts:20)
+
+## Examples
+
+- `example:odd-message-branch/default` in src/message-branch/message-branch.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 12 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/components/odd-message.md

@@ -0,0 +1,99 @@
+# `<odd-message>` (OddkinMessage)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+One message: its role, structured parts in order (text, reasoning, files, sources, tools,
+approvals, artifacts, data), and message actions (copy, regenerate, edit, versions,
+feedback, provenance). Parts with unknown types or missing records render explicit fallbacks.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/message';`
+- Class: `import { OddkinMessage } from '@oddkin/ai/message';`
+- Dependency (approval): `<odd-action-approval>`
+- Dependency (artifact): `<odd-artifact>`
+- Dependency (branch): `<odd-message-branch>`
+- Dependency (button): `<odd-button>`
+- Dependency (feedback): `<odd-response-feedback>`
+- Dependency (label): `<odd-ai-label>`
+- Dependency (response): `<odd-response>`
+- Dependency (sources): `<odd-sources>`
+- Dependency (toolCall): `<odd-tool-call>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `message` | none: assign as a property | { id: string; role: "tool" \| "user" \| "assistant" \| "system"; parts: ({ type: "approval"; id: string; approvalId: string; } \| { type: "data"; id: string; data: JsonValue; name: string; } \| ... 6 more ... \| { ...; })[]; attemptId?: string \| undefined; provenance?: { ...; } \| undefined; createdAt?: string \| undefined;... | undefined | The message record. |
+| `attempt` | none: assign as a property | AttemptRecord \| undefined | undefined | The attempt that writes this (assistant) message. |
+| `tools` | none: assign as a property | Readonly<Record<string, { toolCallId: string; status: "input-streaming" \| "input-available" \| "awaiting-approval" \| "executing" \| "output-available" \| "output-error" \| "denied" \| "cancelled"; ... 9 more ...; output?: JsonValue \| undefined; }>> \| undefined | undefined | Tool call records by id. |
+| `approvals` | none: assign as a property | Readonly<Record<string, { approvalId: string; revision: number; title: string; status: "requested" \| "decision-pending" \| "approved" \| "rejected" \| "expired" \| "superseded" \| "decision-failed"; ... 9 more ...; error?: { ...; } \| undefined; }>> \| undefined | undefined | Approval records by id. |
+| `artifacts` | none: assign as a property | Readonly<Record<string, { title: string; kind: string; artifactId: string; currentRevisionId: string; revisions: { number: number; revisionId: string; content: string; summary?: string \| undefined; createdAt?: string \| undefined; }[]; language?: string \| undefined; }>> \| undefined | undefined | Artifact records by id. |
+| `branch` | none: assign as a property | BranchPosition \| undefined | undefined | Position among alternative versions. |
+| `feedback` | none: assign as a property | { status: "failed" \| "idle" \| "pending" \| "submitted"; messageId: string; error?: { code: string; message: string; retryable?: boolean \| undefined; } \| undefined; rating?: "positive" \| "negative" \| undefined; reasons?: string[] \| undefined; comment?: string \| undefined; } \| undefined | undefined | Feedback record for this message. |
+| `capabilities` | none: assign as a property | { send?: { available: boolean; reason?: string \| undefined; } \| undefined; stop?: { available: boolean; reason?: string \| undefined; } \| undefined; disconnect?: { available: boolean; reason?: string \| undefined; } \| undefined; ... 12 more ...; feedback?: { ...; } \| undefined; } \| undefined | undefined | Enables regenerate, edit, branches, feedback, approvals. |
+| `markdown` | none: assign as a property | MarkdownOptions \| undefined | undefined | Markdown rendering options. |
+| `renderers` | none: assign as a property | Readonly<Record<string, DataRenderer>> \| undefined | undefined | Validated renderers for `data` parts by name. |
+| `artifactRenderers` | none: assign as a property | Readonly<Record<string, ArtifactRenderer>> \| undefined | undefined | Artifact renderers by kind. |
+| `renderTool` | none: assign as a property | { render: ToolOutputRenderer; } \| undefined | undefined | Renderer for tool results. |
+| `feedbackReasons` | none: assign as a property | string[] | [] | Reasons offered for negative feedback. |
+| `strings` | none: assign as a property | Partial<{ user: string; assistant: string; system: string; tool: string; reasoning: string; copy: string; copied: string; copyFailed: string; regenerate: string; edit: string; save: string; cancel: string; ... 6 more ...; file: string; }> \| undefined | undefined | Localized string overrides. |
+| `text` | none (read-only) | string |  | Canonical text of the message (text parts joined), as copied. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-message-edit` | CustomEvent<{ readonly messageId: string; readonly text: string; }> | user (authored) | Request to edit a user message as a new branch. |
+| `odd-message-regenerate` | CustomEvent<{ readonly messageId: string; readonly attemptId: string; }> | user (authored) | Request an alternative answer as a new branch. |
+| `odd-announce` | CustomEvent<AnnounceDetail> | notification (authored) | A status message for the nearest announcer, which cancels it so outer announcers stay silent. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `content` | The parts. |
+| `footer` | Actions, versions, and feedback. |
+| `header` | Role label and provenance. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Rendering a message from a conversation record. (src/message/message.ts:64)
+- Not for: Free-form chat bubbles without records. (src/message/message.ts:65)
+- Accessibility: The role label is visible text. Inside `odd-conversation` the host element is a feed article. Editing moves focus into the edit field only after the user chooses Edit, and back to Edit when cancelled. (src/message/message.ts:62)
+- Keyboard: Tab through actions; Escape cancels editing. (src/message/message.ts:63)
+
+## Examples
+
+- `example:odd-message/default` in src/message/message.examples.ts (package source)
+- `example:odd-message/user` in src/message/message.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 23 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/components/odd-model-select.md

@@ -0,0 +1,84 @@
+# `<odd-model-select>` (OddkinModelSelect)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Choose among application-provided models, with capabilities and availability. Built on a
+native `<select>`; unavailable models are listed but disabled, with the host's reason.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/model-select';`
+- Class: `import { OddkinModelSelect } from '@oddkin/ai/model-select';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `models` | none: assign as a property | { label: string; id: string; available: boolean; description?: string \| undefined; reason?: string \| undefined; capabilities?: string[] \| undefined; provider?: string \| undefined; }[] | [] | Models supplied by the application. |
+| `value` | `value` (reflects) | string | '' | Selected model id. |
+| `label` | `label` | string | '' | Visible label; defaults to the localized "Model". |
+| `disabled` | `disabled` (reflects) | boolean | false | Prevents changing the model. |
+| `strings` | none: assign as a property | Partial<{ label: string; unavailable: string; capabilities: string; none: string; }> \| undefined | undefined | Localized string overrides. |
+| `selected` | none (read-only) | { label: string; id: string; available: boolean; description?: string \| undefined; reason?: string \| undefined; capabilities?: string[] \| undefined; provider?: string \| undefined; } \| undefined |  | The selected model record, if listed. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-model-change` | CustomEvent<{ readonly modelId: string; readonly previousModelId: string; }> | user (authored) | The user selected another model. Cancel to keep the previous one. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `details` | Description, capabilities, and availability of the selected model. |
+| `label` | The visible label of the select. |
+| `select` | The native select. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-field-background` | Background colour of the select. Shared by every form control. |
+| `--odd-field-border-color` | Border colour of the select. Shared by every form control. |
+| `--odd-field-height` | Minimum height of the select (never below the target-size token). Shared by every form control. |
+| `--odd-field-radius` | Corner radius of the select. Shared by every form control. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Letting users choose the model used for the next request. (src/model-select/model-select.ts:26)
+- Not for: Settings unrelated to models. (src/model-select/model-select.ts:27)
+- Accessibility: A labelled native select; details are referenced with `aria-describedby`. (src/model-select/model-select.ts:24)
+- Keyboard: Native select behavior. (src/model-select/model-select.ts:25)
+- Limitations: Programmatic `value` changes never dispatch `odd-model-change`. (src/model-select/model-select.ts:28)
+
+## Examples
+
+- `example:odd-model-select/default` in src/model-select/model-select.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+- Variables: `--odd-field-background`, `--odd-field-border-color`, `--odd-field-height`, `--odd-field-radius`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 23 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)