diff --git a/deno.json b/deno.json index 5807f7c5e3..eabbd349ec 100644 --- a/deno.json +++ b/deno.json @@ -494,12 +494,12 @@ "build:storybook": "npm --prefix storybook run build-storybook", "storybook:check": "deno test --no-lock --config=scripts/test.deno.json --no-check --allow-read scripts/storybook/storybook-workbench.test.ts", "lint": "DENO_NO_PACKAGE_JSON=1 deno lint && deno lint --config=scripts/test.deno.json scripts/test/ scripts/build/dnt-polyfill.ts scripts/build/dnt-polyfill.test.ts scripts/build/npm-package-metadata.test.ts scripts/build/prepare-framework-sources.test.ts && deno lint --config=scripts/codemods/deno.json scripts/codemods/", - "lint:ci": "deno task lint && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:skipped-tests && deno task lint:chat-ratchets && deno task lint:esm-sh-codemod && deno task lint:test-typecheck && deno task lint:cwd-relative-test-reads && deno task storybook:check && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:public:check && deno test --frozen --config=scripts/test.deno.json --no-check --allow-read --allow-write --allow-run=bash scripts/ci/setup-deno-workflow.test.ts scripts/ci/prepare-rc-build.test.ts scripts/build/generated-artifact-checks.test.ts", + "lint:ci": "deno task lint && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:skipped-tests && deno task lint:chat-ratchets && deno task lint:chat-composability && deno task lint:rfc-status && deno task lint:esm-sh-codemod && deno task lint:test-typecheck && deno task lint:cwd-relative-test-reads && deno task storybook:check && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:public:check && deno test --frozen --config=scripts/test.deno.json --no-check --allow-read --allow-write --allow-run=bash scripts/ci/setup-deno-workflow.test.ts scripts/ci/prepare-rc-build.test.ts scripts/build/generated-artifact-checks.test.ts", "fmt": "deno fmt src/ cli/ react/ templates/ && deno fmt --config=scripts/test.deno.json scripts/test/ scripts/build/dnt-polyfill.ts scripts/build/dnt-polyfill.test.ts scripts/build/prepare-framework-sources.test.ts && deno fmt --config=scripts/codemods/deno.json scripts/codemods/", "fmt:check": "deno fmt --check src/ cli/ react/ templates/ && deno fmt --check --config=scripts/test.deno.json scripts/test/ scripts/build/dnt-polyfill.ts scripts/build/dnt-polyfill.test.ts scripts/build/prepare-framework-sources.test.ts && deno fmt --check --config=scripts/codemods/deno.json scripts/codemods/", "typecheck": "deno task generate:manifests:check && deno check src/index.ts cli/main.ts src/server/index.ts src/routing/api/index.ts src/rendering/index.ts src/platform/index.ts src/platform/adapters/index.ts src/build/index.ts src/build/production-build/index.ts src/transforms/index.ts src/config/index.ts src/utils/index.ts src/data/index.ts src/security/index.ts src/middleware/index.ts src/server/handlers/dev/index.ts src/server/handlers/request/api/index.ts src/rendering/cache/index.ts src/rendering/cache/stores/index.ts src/rendering/rsc/actions/index.ts src/html/index.ts src/html/hydration-script-builder/runtime/main.ts src/modules/index.ts src/proxy/main.ts src/react/components/ui/index.ts src/chat/index.ts src/markdown/index.ts src/mdx/index.ts src/fs/index.ts src/oauth/index.ts src/agent/index.ts src/agent/service/route-export.check.ts src/eval/index.ts src/tool/index.ts src/workflow/index.ts src/prompt/index.ts src/resource/index.ts src/runs/index.ts src/mcp/index.ts src/provider/index.ts", - "verify": "deno task generate:manifests:check && deno task fmt:check && deno task lint && deno task lint:style && deno task lint:chat-composability && deno task lint:chat-ratchets && deno task lint:esm-sh-codemod && deno task lint:cli-boundary && deno task lint:wildcard-exports && deno task lint:barrel-jsdoc && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:skipped-tests && deno task lint:ban-zod && deno task lint:cwd-relative-test-reads && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:validate && deno task typecheck && deno task typecheck:consumer && deno task test && deno task test:scripts && deno task test:e2e:binary", - "verify:quick": "deno task generate:manifests:check && deno task fmt:check && deno task lint && deno task lint:style && deno task lint:chat-composability && deno task lint:chat-ratchets && deno task lint:esm-sh-codemod && deno task lint:cli-boundary && deno task lint:wildcard-exports && deno task lint:barrel-jsdoc && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:skipped-tests && deno task lint:ban-zod && deno task lint:cwd-relative-test-reads && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:validate && deno task typecheck", + "verify": "deno task generate:manifests:check && deno task fmt:check && deno task lint && deno task lint:style && deno task lint:chat-composability && deno task lint:rfc-status && deno task lint:chat-ratchets && deno task lint:esm-sh-codemod && deno task lint:cli-boundary && deno task lint:wildcard-exports && deno task lint:barrel-jsdoc && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:skipped-tests && deno task lint:ban-zod && deno task lint:cwd-relative-test-reads && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:validate && deno task typecheck && deno task typecheck:consumer && deno task test && deno task test:scripts && deno task test:e2e:binary", + "verify:quick": "deno task generate:manifests:check && deno task fmt:check && deno task lint && deno task lint:style && deno task lint:chat-composability && deno task lint:rfc-status && deno task lint:chat-ratchets && deno task lint:esm-sh-codemod && deno task lint:cli-boundary && deno task lint:wildcard-exports && deno task lint:barrel-jsdoc && deno task lint:ban-test-only && deno task lint:sanitizer-baseline && deno task lint:skipped-tests && deno task lint:ban-zod && deno task lint:cwd-relative-test-reads && deno task lint:core-deps && deno task lint:cross-runtime-jsr && deno task lint:dependency-boundaries && deno task lint:module-boundaries && deno task lint:extension-contracts && deno task lint:extension-capabilities && deno task docs:api-reference:check && deno task docs:errors:check && deno task docs:validate && deno task typecheck", "typecheck:consumer": "deno run --allow-read --allow-run --allow-env --allow-write scripts/typecheck/run-consumer-typecheck.ts", "codemod:chat": "deno run --frozen --config=scripts/codemods/deno.json --allow-read --allow-write --allow-env=BABEL_TYPES_8_BREAKING scripts/codemods/migrate-chat-composition.ts", "codemod:esm-sh": "deno run --frozen --config=scripts/codemods/deno.json --allow-read --allow-write --allow-env=BABEL_TYPES_8_BREAKING scripts/codemods/migrate-esm-sh-imports.ts", @@ -528,6 +528,7 @@ "lint:imports": "deno run --allow-read scripts/lint/no-cross-boundary-relative-imports.ts", "lint:ban-internal-root-imports": "deno run --allow-read scripts/lint/ban-internal-root-imports.ts", "lint:chat-composability": "deno run --allow-read scripts/lint/audit-chat-composability.ts", + "lint:rfc-status": "deno run --allow-read scripts/lint/audit-rfc-status.ts", "lint:style": "deno run --allow-read scripts/lint/enforce-style-conventions.ts", "lint:cli-boundary": "deno run --allow-read scripts/lint/enforce-cli-boundary.ts", "validate:architecture": "deno run --allow-read scripts/lint/validate-architecture.ts", @@ -541,7 +542,7 @@ "lint:sanitizer-baseline": "deno run --allow-read scripts/lint/check-sanitizer-baseline.ts", "lint:skipped-tests": "deno run --allow-read scripts/lint/check-skipped-tests-baseline.ts", "lint:cwd-relative-test-reads": "deno run --allow-read scripts/lint/audit-cwd-relative-test-reads.ts", - "test:scripts": "deno test --config=scripts/test.deno.json --no-check --allow-read --allow-write --allow-run scripts/ci/prepare-rc-build.test.ts scripts/ci/publish-npm-packages.test.ts scripts/ci/setup-deno-workflow.test.ts scripts/build/compile-binary.test.ts scripts/build/dnt-polyfill.test.ts scripts/build/generate-sbom.test.ts scripts/build/generated-artifact-checks.test.ts scripts/build/npm-dependency-sources.test.ts scripts/build/npm-extension-package-metadata.test.ts scripts/build/npm-package-metadata.test.ts scripts/build/npm-react-shims.test.ts scripts/build/npm-runtime-helper-contract.test.ts scripts/build/prepare-framework-sources.test.ts scripts/docs/docs-coverage.test.ts scripts/docs/generate-api-reference.test.ts scripts/docs/guide-validation.test.ts scripts/lint/audit-core-deps.test.ts scripts/lint/audit-cwd-relative-test-reads.test.ts scripts/lint/audit-cross-runtime-jsr.test.ts scripts/lint/audit-dependency-boundaries.test.ts scripts/lint/audit-extension-capabilities.test.ts scripts/lint/audit-extension-contracts.test.ts scripts/lint/audit-deps.test.ts scripts/lint/check-module-boundaries.test.ts scripts/lint/lint-config.test.ts scripts/lint/ban-test-only.test.ts scripts/lint/check-sanitizer-baseline.test.ts scripts/lint/check-skipped-tests-baseline.test.ts scripts/lint/check-test-typecheck-baseline.test.ts scripts/lint/check-coverage.test.ts scripts/security/audit-npm.test.ts scripts/security/submit-dependency-snapshot.test.ts scripts/test/template-runtime-e2e.test.ts && deno task test:tool-search-live", + "test:scripts": "deno test --config=scripts/test.deno.json --no-check --allow-read --allow-write --allow-run scripts/ci/prepare-rc-build.test.ts scripts/ci/publish-npm-packages.test.ts scripts/ci/setup-deno-workflow.test.ts scripts/build/compile-binary.test.ts scripts/build/dnt-polyfill.test.ts scripts/build/generate-sbom.test.ts scripts/build/generated-artifact-checks.test.ts scripts/build/npm-dependency-sources.test.ts scripts/build/npm-extension-package-metadata.test.ts scripts/build/npm-package-metadata.test.ts scripts/build/npm-react-shims.test.ts scripts/build/npm-runtime-helper-contract.test.ts scripts/build/prepare-framework-sources.test.ts scripts/docs/docs-coverage.test.ts scripts/docs/generate-api-reference.test.ts scripts/docs/guide-validation.test.ts scripts/lint/audit-chat-composability.test.ts scripts/lint/audit-rfc-status.test.ts scripts/lint/audit-core-deps.test.ts scripts/lint/audit-cwd-relative-test-reads.test.ts scripts/lint/audit-cross-runtime-jsr.test.ts scripts/lint/audit-dependency-boundaries.test.ts scripts/lint/audit-extension-capabilities.test.ts scripts/lint/audit-extension-contracts.test.ts scripts/lint/audit-deps.test.ts scripts/lint/check-module-boundaries.test.ts scripts/lint/lint-config.test.ts scripts/lint/ban-test-only.test.ts scripts/lint/check-sanitizer-baseline.test.ts scripts/lint/check-skipped-tests-baseline.test.ts scripts/lint/check-test-typecheck-baseline.test.ts scripts/lint/check-coverage.test.ts scripts/security/audit-npm.test.ts scripts/security/submit-dependency-snapshot.test.ts scripts/test/template-runtime-e2e.test.ts && deno task test:tool-search-live", "test:sentry-runtime-packages": "deno test --config=scripts/test.deno.json --no-check --no-lock --allow-read --allow-write --allow-run --allow-env=DENO_DIR,HOME,XDG_CACHE_HOME,LOCALAPPDATA,USERPROFILE scripts/build/sentry-runtime-packages.test.ts", "test:tool-search-live": "VF_DISABLE_LRU_INTERVAL=1 deno test --no-check -A tests/agent/verify-tool-search-live.test.ts", "test:cross-runtime": "deno run --allow-all src/platform/compat/cross-runtime.test.ts", diff --git a/docs/rfcs/29-chat-api-shape.md b/docs/rfcs/29-chat-api-shape.md index 7cc82b2021..b736be4a44 100644 --- a/docs/rfcs/29-chat-api-shape.md +++ b/docs/rfcs/29-chat-api-shape.md @@ -2,7 +2,18 @@ > **Per-piece documentation:** every proposed component and hook has a user-facing docs page under [`29-chat-api-shape/`](./29-chat-api-shape/README.md) - 25 components, 34 hooks, helpers, providers. -**Status:** draft for discussion. **North star: `veryfront/ui`.** Chat should be a +> **Status: RFC 29 - partly landed.** This RFC proposes a reset of a library that already shipped, and it is landing piecemeal. Per-symbol truth for this document, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `mergeProps`, `useChatInput`, `useChatInputContext`, `useChatScroll`, `useMessageBranches` +> - **Not exported today:** `formatSize`, `getAgentPromptSuggestionItems` +> +> The per-piece pages carry the same block plus per-delta `shipped` badges; the roll-up of everything that has landed lives in [the reference index](./29-chat-api-shape/README.md#what-has-landed---shipped-srcreactcomponentschatchathooksuse-chat-inputts85). + +## Already landed - `shipped` (src/react/components/chat/chat/hooks/use-chat-input.ts:85) + +[#3277](https://github.com/veryfront/veryfront-code/pull/3277) shipped the L3 prop-getter surface (`useChatInput` with `getFormProps` / `getFieldProps` / `getSubmitProps` / `getAttachProps` / `getVoiceProps`), made **`mergeProps` public**, landed the IME-composition guard behind `ChatInput.Field`, and added `useChatScroll`, `useMessageBranches`, and the `ChatInputContext*` names. A delta has landed only where its own page badges it `shipped`, and the reference index rolls up every delta that has; `deno task lint:rfc-status` fails if a badge and that roll-up disagree, or if any per-piece ledger drifts. + +**North star: `veryfront/ui`.** Chat should be a **regular component library built exactly like `veryfront/ui`** - each component a single, fully-controllable node. `veryfront/ui` already nails this (it's a Radix-API fork + `cva`, `asChild`, `extends HTMLAttributes`); `veryfront/chat` should follow @@ -873,7 +884,7 @@ providers render zero nodes; every `use*Context` has an `Optional` variant. | `extractChatMessageMetadata(value)` | typed metadata off a message | | `formatSize(bytes)` | human-readable byte size (`B`/`KB`/`MB`) | | `agentsToPickerOptions(agents)` | picker option mapping | -| `mergeProps(...propsObjects)` | **new** - the normative merge, public | +| `mergeProps(...propsObjects)` | `shipped` - the normative merge, public | --- diff --git a/docs/rfcs/29-chat-api-shape/README.md b/docs/rfcs/29-chat-api-shape/README.md index 6acf941d74..93c268eea6 100644 --- a/docs/rfcs/29-chat-api-shape/README.md +++ b/docs/rfcs/29-chat-api-shape/README.md @@ -1,6 +1,47 @@ # `veryfront/chat` - proposed API shape -Reference pages for the proposed `veryfront/chat` surface, accompanying the RFC one level up: [`29-chat-api-shape.md`](../29-chat-api-shape.md). Everything here documents the _proposed_ shape - none of it is implemented yet. Each page carries the same status banner; the RFC holds the full rationale, cross-cutting contracts, and resolved decisions. +Reference pages for the proposed `veryfront/chat` surface, accompanying the RFC one level up: [`29-chat-api-shape.md`](../29-chat-api-shape.md). The RFC holds the full rationale, cross-cutting contracts, and resolved decisions; these pages hold the per-piece detail. + +> **Status: RFC 29 - partly landed.** Per-symbol truth for this index, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `mergeProps`, `useChatInput`, `useChatInputContext`, `useChatScroll`, `useMessageBranches` +> - **Not exported today:** `formatSize`, `getAgentPromptSuggestionItems` +> +> Those five symbols resolve on the public surface today. That is **not** the same as a landed delta - see [reading the status block](#reading-the-status-block). For the deltas that have actually landed, see [what has landed](#what-has-landed---shipped-srcreactcomponentschatchathooksuse-chat-inputts85). + +## Reading the status block + +RFC 29 proposes a reset of a library that **already shipped**, and it is landing piecemeal. Every page here therefore carries a status block instead of a page-wide "not implemented" banner, because a page-wide banner is a claim no machine can check - and it went stale the moment [#3277](https://github.com/veryfront/veryfront-code/pull/3277) shipped the prop-getter surface and made `mergeProps` public. + +Read a status block like this: + +- **Exported from `veryfront/chat` today** - these symbols resolve on the real public surface (barrel exports plus compound sub-parts). **This does not mean the page's delta for them has landed.** `ChatInput.Submit` ships; the RFC's reshape of it does not. +- **Not exported today** - these symbols genuinely do not exist. `deno task lint:rfc-status` fails if any of them starts shipping without this list being updated. +- **Not in `src/` today** - the same guarantee for props and hook members, which are not exports (`submitMode`, `getDropTargetProps`). + +The **Import** block on each page shows the shape this RFC _proposes_, not today's barrel - so where the two differ, the status block wins. The most common difference: "every sub-part is also a flat named export" is a proposal on every page except [`ChatInput`](./components/chat-input.md#chatinput-flat-sub-part-exports---new---shipped-srcchatindexts250), where it has actually landed (`src/chat/index.ts:250`). + +What actually landed is marked **per delta**, on the delta's own heading: + +- `` `shipped` (src/path/to/file.ts:42) `` - the delta landed as specified, with the source it landed in. +- `` `partly shipped` (src/path/to/file.ts:42) `` - part of it landed; the section says which part, and what is still proposed. +- no status badge - still proposed. The `kept` / `changed` / `new` / `removed` badge describes the proposal, not the runtime. + +Every anchor is checked: the file must exist and the line must be in it. So must both symbol lists. The check runs in the lint chain, which is what stops this corpus drifting again. + +### What has landed - `shipped` (src/react/components/chat/chat/hooks/use-chat-input.ts:85) + +The complete set, as of `main`, and checked one delta at a time: every row links the delta's own heading, and `deno task lint:rfc-status` pairs each row with that badge. It fails if a badge has no row, if a row's anchor names no badge, if a row links a page without naming a delta, or if two rows claim the same delta. Pairing by page instead of by delta would let one badge cover a page's whole column - which is how the `ChatInput` flat sub-part exports row sat here unbadged. + +| Delta | Status | Landed in | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`mergeProps` made public](./helpers.md#mergeprops---new---shipped-srcreactcomponentschatchathooksuse-chat-inputts85) | `shipped` | `src/react/components/chat/chat/hooks/use-chat-input.ts:85` | +| [`useMessageBranches`](./hooks/use-message-branches.md#usemessagebranches---new---shipped-srcreactcomponentschatchatcontextsmessage-contexttsx87) | `shipped` | `src/react/components/chat/chat/contexts/message-context.tsx:87` | +| [`useChatInputContext` naming](./hooks/use-chat-input-context.md#usechatinputcontext---new---shipped-srcreactcomponentschatchatcontextscomposer-contexttsx83) | `shipped` | `src/react/components/chat/chat/contexts/composer-context.tsx:83` | +| [`useChatInput` + prop getters](./hooks/use-chat-input.md#usechatinput---new---partly-shipped-srcreactcomponentschatchathooksuse-chat-inputts155) | `partly shipped` | `src/react/components/chat/chat/hooks/use-chat-input.ts:155` | +| [`useChatScroll`](./hooks/use-chat-scroll.md#usechatscroll---new---partly-shipped-srcreactcomponentschatchathooksuse-stick-to-bottomts177) | `partly shipped` | `src/react/components/chat/chat/hooks/use-stick-to-bottom.ts:177` | +| [`ChatInput.Field` IME guard + native surface](./components/chat-input.md#chatinputfield---changed---partly-shipped-srcreactcomponentschatchatcompositionchat-composertypests18) | `partly shipped` | `src/react/primitives/input-box.tsx:37` (guard); the native surface landed in `src/react/components/chat/chat/composition/chat-composer.types.ts:18` | +| [`ChatInput` flat sub-part exports](./components/chat-input.md#chatinput-flat-sub-part-exports---new---shipped-srcchatindexts250) | `shipped` | `src/chat/index.ts:250` | ## The three layers diff --git a/docs/rfcs/29-chat-api-shape/components/agent-card.md b/docs/rfcs/29-chat-api-shape/components/agent-card.md index 7200543880..c40182e88c 100644 --- a/docs/rfcs/29-chat-api-shape/components/agent-card.md +++ b/docs/rfcs/29-chat-api-shape/components/agent-card.md @@ -2,7 +2,12 @@ A status card for one running agent: identity header, live status, reasoning, tool calls, and streamed output - render it whole, or compose the parts. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented. Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - proposed; nothing on this page has landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `AgentCard`, `AgentCard.Body`, `AgentCard.Header`, `AgentCard.Reasoning`, `AgentCard.Root`, `AgentCard.Tools` +> - **Not exported today:** none +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). > **⚠ Reusability flag** (see [generic core vs veryfront adapter](../../29-chat-api-shape.md)): the status _values_ (`idle` / `thinking` / `tool_execution` / `streaming` / `completed` / `error`) are **AG-UI-protocol states - generic, not coupling**. The real coupling is that this component imports veryfront agent-SDK `AgentMessage`/`ToolCall` **types** and duplicates `Message`/`ToolCall`/`Reasoning`/`Markdown` for a runtime view. Type it against the generic AG-UI shape, or move the SDK-typed card to the veryfront adapter. diff --git a/docs/rfcs/29-chat-api-shape/components/agent-picker.md b/docs/rfcs/29-chat-api-shape/components/agent-picker.md index d9c5d98d91..bc0862d609 100644 --- a/docs/rfcs/29-chat-api-shape/components/agent-picker.md +++ b/docs/rfcs/29-chat-api-shape/components/agent-picker.md @@ -2,7 +2,12 @@ A searchable popover for choosing an agent - pill trigger, filterable list, optional create/manage actions - render it whole, or compose the parts. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented. Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - proposed; nothing on this page has landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `AgentPicker`, `AgentPicker.Content`, `AgentPicker.Create`, `AgentPicker.Item`, `AgentPicker.List`, `AgentPicker.Manage`, `AgentPicker.Root`, `AgentPicker.Search`, `AgentPicker.Trigger` +> - **Not exported today:** none +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). ## Import diff --git a/docs/rfcs/29-chat-api-shape/components/app-shell.md b/docs/rfcs/29-chat-api-shape/components/app-shell.md index c9b4f43815..dc66fb0efa 100644 --- a/docs/rfcs/29-chat-api-shape/components/app-shell.md +++ b/docs/rfcs/29-chat-api-shape/components/app-shell.md @@ -2,11 +2,16 @@ Application shell layout - dockable sidebars, main pane, header - from `veryfront/ui`. Chat consumes it; it does not own it. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented. Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - proposed; nothing on this page has landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `AppShell`, `AppShell.Content`, `AppShell.Header`, `AppShell.Main`, `AppShell.Sidebar`, `AppShell.SidebarContent`, `AppShell.SidebarFooter`, `AppShell.SidebarHeader`, `AppShell.Trigger` +> - **Not exported today:** none +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). ## Reference only -`AppShell` lives in **`veryfront/ui`**, not `veryfront/chat` - it is already shipped and already close to the convention this RFC applies to chat (single nodes, native spread, `ref` props, compound parts). This page documents its _real, current_ surface so chat compositions can be judged against it; changes to `AppShell` itself (e.g. `asChild`, the icon-slot ban on `.Trigger`) are out of scope for this chat RFC. +`AppShell`'s home is **`veryfront/ui`**, which is what the import below shows; `veryfront/chat` re-exports it (`src/chat/index.ts:311`) so a chat app can compose its shell from one import, which is why it also resolves in the status block above. It is already shipped and already close to the convention this RFC applies to chat (single nodes, native spread, `ref` props, compound parts). This page documents its _real, current_ surface so chat compositions can be judged against it; changes to `AppShell` itself (e.g. `asChild`, the icon-slot ban on `.Trigger`) are out of scope for this chat RFC. ## Import diff --git a/docs/rfcs/29-chat-api-shape/components/attachment-pill.md b/docs/rfcs/29-chat-api-shape/components/attachment-pill.md index 45497b8bf0..6dcb8bbaa7 100644 --- a/docs/rfcs/29-chat-api-shape/components/attachment-pill.md +++ b/docs/rfcs/29-chat-api-shape/components/attachment-pill.md @@ -2,7 +2,12 @@ A pending-upload chip for the composer - one per attachment, with thumbnail, label, retry, and remove. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented. Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - proposed; nothing on this page has landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `AttachmentPill`, `AttachmentPill.Icon`, `AttachmentPill.Label`, `AttachmentPill.Remove`, `AttachmentPill.Retry`, `AttachmentPill.Root`, `AttachmentPill.Thumbnail`, `ChatInput` +> - **Not exported today:** none +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). ## Import diff --git a/docs/rfcs/29-chat-api-shape/components/attachments-panel.md b/docs/rfcs/29-chat-api-shape/components/attachments-panel.md index e7970db8ac..bd89b5e444 100644 --- a/docs/rfcs/29-chat-api-shape/components/attachments-panel.md +++ b/docs/rfcs/29-chat-api-shape/components/attachments-panel.md @@ -2,7 +2,12 @@ A compound component for browsing and managing durable uploaded files, with the same compositional depth as messages. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented. Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - proposed; nothing on this page has landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `AttachmentsPanel`, `AttachmentsPanel.Action`, `AttachmentsPanel.Empty`, `AttachmentsPanel.Header`, `AttachmentsPanel.Item`, `AttachmentsPanel.Item.Icon`, `AttachmentsPanel.Item.Preview`, `AttachmentsPanel.Item.Remove`, `AttachmentsPanel.List`, `AttachmentsPanel.Loading`, `AttachmentsPanel.Root`, `useAttachments` +> - **Not exported today:** `AttachmentsPanel.Item.Name`, `AttachmentsPanel.Item.Size` +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). > **✂ Earns-its-place flag** (see [proposed v1 scope cuts](../../29-chat-api-shape.md)): the durable "file browser" is a RAG / doc-Q&A product feature (empty state: _"upload files to start asking questions about them"_), sitting at the same altitude as the composer - and it is why the attachment surface has **4 hooks, not 2**. **Proposed:** ship it as an optional module, not core v1; the composer keeps `AttachmentPill` + `useUpload`. diff --git a/docs/rfcs/29-chat-api-shape/components/branch-picker.md b/docs/rfcs/29-chat-api-shape/components/branch-picker.md index af4507f244..f228bab51f 100644 --- a/docs/rfcs/29-chat-api-shape/components/branch-picker.md +++ b/docs/rfcs/29-chat-api-shape/components/branch-picker.md @@ -2,7 +2,12 @@ Previous/next navigation between message branches - a namespace re-export of `Message.BranchPicker`. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented. Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - proposed; nothing on this page has landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `BranchPicker`, `BranchPicker.Count`, `BranchPicker.Next`, `BranchPicker.Previous`, `BranchPicker.Root` +> - **Not exported today:** none +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). `BranchPicker` **is** `Message.BranchPicker` - one implementation, re-exported under a standalone name. It is a thin surface over the `getBranches` / `switchBranch` capabilities that **already exist on `useChat`**, via `useMessageBranches`. Today the wiring is split: a presentational `BranchPicker` (controlled `current`/`total`/`onPrev`/`onNext` props) plus a `Message.BranchPicker` wrapper that feeds it from message context - including the off-by-one bookkeeping (`BranchInfo.current` is 1-based, `switchBranch` takes a 0-based index, so prev/next are `switchBranch(id, current - 2)` / `switchBranch(id, current)`). The proposal hides that math inside `useMessageBranches`. diff --git a/docs/rfcs/29-chat-api-shape/components/chat-actions.md b/docs/rfcs/29-chat-api-shape/components/chat-actions.md index d24835f181..57a3d19170 100644 --- a/docs/rfcs/29-chat-api-shape/components/chat-actions.md +++ b/docs/rfcs/29-chat-api-shape/components/chat-actions.md @@ -2,7 +2,12 @@ The composer's actions menu - a dropdown of data-driven rows (attach, custom actions, settings), with thread-level export/clear composed from public helpers. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented. Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - proposed; nothing on this page has landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `ChatActions`, `ChatActions.Content`, `ChatActions.Item`, `ChatActions.Preset`, `ChatActions.Root`, `ChatActions.Trigger` +> - **Not exported today:** none +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). > **⚠ Reusability flag** (see [generic core vs veryfront adapter](../../29-chat-api-shape.md)): `.Preset`'s `settings` submenu toggles (`autoSubmit` "Auto-send queue", `autoFixErrors` "Autofix errors") are veryfront agent-runtime features, not generic chat. Drop `settings` from the public reader; consumers compose a settings submenu from generic `.Item`s. diff --git a/docs/rfcs/29-chat-api-shape/components/chat-agent-picker.md b/docs/rfcs/29-chat-api-shape/components/chat-agent-picker.md index 3df3bf85d8..07009176b6 100644 --- a/docs/rfcs/29-chat-api-shape/components/chat-agent-picker.md +++ b/docs/rfcs/29-chat-api-shape/components/chat-agent-picker.md @@ -2,7 +2,12 @@ The batteries-included preset over `AgentPicker`: fetches the project's agents itself and renders the picker only when there is something to switch between. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented. Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - proposed; nothing on this page has landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `AgentPicker`, `agentsToPickerOptions`, `ChatAgentPicker`, `ChatAgentPickerProps` +> - **Not exported today:** none +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). ## Import diff --git a/docs/rfcs/29-chat-api-shape/components/chat-empty-state.md b/docs/rfcs/29-chat-api-shape/components/chat-empty-state.md index f3d6692f52..3a02701240 100644 --- a/docs/rfcs/29-chat-api-shape/components/chat-empty-state.md +++ b/docs/rfcs/29-chat-api-shape/components/chat-empty-state.md @@ -2,7 +2,12 @@ The zero-messages view: hero agent avatar, heading, and a wrapping row of typed prompt-suggestion chips. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented. Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - proposed; nothing on this page has landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `ChatEmptyState`, `ChatEmptyState.Avatar`, `ChatEmptyState.Heading`, `ChatEmptyState.Root`, `ChatEmptyState.Suggestion`, `ChatEmptyState.Suggestions` +> - **Not exported today:** none +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). > **⚠ Reusability flag** (see [generic core vs veryfront adapter](../../29-chat-api-shape.md)): `Avatar` defaults `alt="Veryfront Agent"` - a brand string a generic consumer would ship to screen readers. Use a neutral default (`"Agent"`), or make `alt` required with no brand default. diff --git a/docs/rfcs/29-chat-api-shape/components/chat-error-boundary.md b/docs/rfcs/29-chat-api-shape/components/chat-error-boundary.md index 79ee3e0886..ab55a65939 100644 --- a/docs/rfcs/29-chat-api-shape/components/chat-error-boundary.md +++ b/docs/rfcs/29-chat-api-shape/components/chat-error-boundary.md @@ -2,7 +2,12 @@ An error boundary for chat surfaces - catches **render** errors in its subtree and shows a resettable fallback. Paired with `useChatErrorHandler` for handler-level (non-render) errors. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented; the component exists today and the RFC keeps its signature (existing props kept, a11y contract applied). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - proposed; nothing on this page has landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `ChatErrorBoundary` +> - **Not exported today:** none +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). > **✂ Earns-its-place flag** (see [proposed v1 scope cuts](../../29-chat-api-shape.md)): a stock React error boundary with a default card - the only "chat" tie is cosmetic default copy. **Proposed:** move to `veryfront/ui` as a generic `ErrorBoundary` rather than ship it as chat API. diff --git a/docs/rfcs/29-chat-api-shape/components/chat-input.md b/docs/rfcs/29-chat-api-shape/components/chat-input.md index c6c92789a3..c3894618e0 100644 --- a/docs/rfcs/29-chat-api-shape/components/chat-input.md +++ b/docs/rfcs/29-chat-api-shape/components/chat-input.md @@ -2,7 +2,12 @@ The chat composer - a single `
` with composable leaves for the field, attachments, model selection, voice, and submit. -> **Status: proposed (RFC).** This page documents the _proposed_ API shape - not yet implemented. Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). +> **Status: RFC 29 - partly landed.** Per-symbol truth, verified against `src/` by `deno task lint:rfc-status`: +> +> - **Exported from `veryfront/chat` today:** `ChatInput`, `ChatInput.Attach`, `ChatInput.Export`, `ChatInput.Field`, `ChatInput.Model`, `ChatInput.Root`, `ChatInput.Send`, `ChatInput.Stop`, `ChatInput.Submit`, `ChatInput.Toolbar`, `ChatInput.Voice` +> - **Not exported today:** none +> +> An exported symbol is not a landed delta - see [reading the status block](../README.md#reading-the-status-block). Full rationale: [`29-chat-api-shape.md`](../../29-chat-api-shape.md). ## Import @@ -12,10 +17,16 @@ import { ChatInput } from "veryfront/chat"; import { ChatInput, ChatInputField, type ChatInputFieldProps } from "veryfront/chat"; ``` +### `ChatInput` flat sub-part exports - `new` - `shipped` (src/chat/index.ts:250) + +The flat sub-part exports above are **not** a proposal: `ChatInputRoot`, `ChatInputField`, `ChatInputToolbar`, `ChatInputAttach`, `ChatInputModel`, `ChatInputVoice`, `ChatInputSubmit`, `ChatInputSend`, `ChatInputStop`, and `ChatInputExport` (with their `Props` types) all ship from `veryfront/chat` today, alongside the `ChatInput.*` namespace aliases. What each leaf _does_ is still the proposal - see the per-delta badges below. + +This is the one page where "every sub-part is also a flat named export" has actually landed; on every other component page it is still proposed. + ## Parts index - [`.Root`](#chatinputroot---changed) - `changed`: two hidden wrapper divs deleted - one ``; ~19 state props collapse into `chat`/`upload`/`voice` -- [`.Field`](#chatinputfield---changed) - `changed`: IME guard + `submitMode` + paste-to-attach added; full native surface opened +- [`.Field`](#chatinputfield---changed---partly-shipped-srcreactcomponentschatchatcompositionchat-composertypests18) - `changed`, **`partly shipped`**: the IME guard and the full native surface landed; `submitMode` and paste-to-attach have not - [`.Submit`](#chatinputsubmit---changed) - `changed`: single always-rendered node (no Send-delegation null-render); `icon`/`stopIcon` removed - [`.Send`](#chatinputsend---changed) - `changed`: `icon` + `WrapClick` `onClick` removed - [`.Stop`](#chatinputstop---changed) - `changed`: `icon` + `WrapClick` `onClick` removed @@ -170,21 +181,29 @@ One `` + the compound's scoped context (`ChatInputContextProvider`). Nativ boolean toggling border classes), `data-compact` (present when the form's inline size is below 560px or the field has a single visual line). -### `ChatInput.Field` - `changed` +### `ChatInput.Field` - `changed` - `partly shipped` (src/react/components/chat/chat/composition/chat-composer.types.ts:18) _Changed: `submitMode`-driven, IME-guarded Enter and paste-to-attach are added, and the full native textarea surface + `asChild` open up (today only `placeholder`/`className`/`aria-label`)._ +**Landed** in [#3277](https://github.com/veryfront/veryfront-code/pull/3277), in **two files** - this delta has two halves, so the badge above and the [roll-up row](../README.md#what-has-landed---shipped-srcreactcomponentschatchathooksuse-chat-inputts85) each cite one of them: + +- **Native surface** (`src/react/components/chat/chat/composition/chat-composer.types.ts:18`, the badge's anchor): `ChatInputFieldProps` now extends `React.TextareaHTMLAttributes` (minus the controlled trio), so the full native surface and `ref` are already the consumer's. +- **IME guard** (`src/react/primitives/input-box.tsx:37`, the roll-up's anchor): `handleInputBoxKeyDown` checks native `isComposing`, synthetic `isComposing`, and the `keyCode === 229` fallback before Enter submits. `.Field` and `useChatInput().getFieldProps()` both route through it, so a custom textarea cannot diverge from the primitive. + +**Still proposed:** `submitMode`, paste-to-attach, and `asChild` on this leaf. + One `