Skip to content

Feat/docs#46

Open
EggerMarc wants to merge 8 commits into
mainfrom
feat/docs
Open

Feat/docs#46
EggerMarc wants to merge 8 commits into
mainfrom
feat/docs

Conversation

@EggerMarc
Copy link
Copy Markdown
Owner

@EggerMarc EggerMarc commented Jun 2, 2026

Summary by CodeRabbit

  • New Features

    • Added public builder methods with_before_strategy and with_after_strategy for callback hooks.
    • Comprehensive documentation site with guides for streaming, multimodal content, structured output, embeddings, tools, and providers.
    • Improved SSE event parser to flush buffered data when encountering new event types.
  • Documentation

    • New getting started guide, capability overviews, provider integrations, and trait documentation.
  • Refactor

    • Comment and documentation cleanup throughout core and provider implementations. New UI component library for docs site.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Jun 2, 2026

Review Change Stack

📝 Walkthrough

Walkthrough

Adds before/after middleware strategies to ChatBuilder; fixes SSE parser to flush buffered events on type switches; cleans comments across core, providers, and examples; requests include_usage in Completions streams; loosens provider builder APIs; and introduces a full docs site (TanStack Start + Fumadocs) with routes, components, and MDX content.

Changes

Core runtime, providers, and examples

Layer / File(s) Summary
Middleware strategy hooks and build cleanup
core/src/builder.rs
Adds with_before_strategy/with_after_strategy; minor build comment removal.
SSE parser emits buffered event on type switch
core/src/transport/sse.rs
Flushes previous event when a new event: line appears.
Tool approval aggregation and call loop tweaks
core/src/chat/*
Refactors RequireApproval pause aggregation; minor call-loop cleanups.
Core streaming and transports cleanup
core/src/chat/stream/*, core/src/transport/*
Removes commentary around loops and WS reuse; behavior unchanged.
Core types/message/metadata/tools cleanup
core/src/types/*
Comment removals and small formatting without logic changes.
Completions stream include_usage and request/response cleanups
providers/completions/src/api/*
Requests usage in final chunk; consolidates message content emission; comment removals.
Claude/Gemini stream and request comment removals
providers/claude/*, providers/gemini/*
SSE/request mapping cleanups; no behavioral changes.
Responses wire request/stream/usage cleanups
providers/responses/*
Earlier previous_response_id assignment; section header removals.
Router retry/circuit-breaker comment removals
providers/router/*
Deletes explanatory comments in retry paths and tests.
Provider builder API ergonomics
providers/claude/src/lib.rs, providers/gemini/src/lib.rs
with_model now accepts impl Into.
Examples comment cleanup
examples/**/*
Removes comments across examples; flows unchanged.

Documentation application

Layer / File(s) Summary
Project setup, config, env, and manifests
docs/*
Adds package/config, ignores, editor settings, env/types, template settings, manifest, and README.
App wiring: alchemy, source, router, routes, styles
docs/alchemy.run.ts, docs/src/{router,routes,...}, docs/src/styles.css
Wires Alchemy app, Fumadocs source, routes (root/docs/API), generated route tree, homepage, and styles.
UI components and interactive visuals
docs/src/components/*, docs/src/components/ui/*
Adds FaultyTerminal shader, CodeGallery, CopyableCode, and base UI primitives.
MDX content and section metadata
docs/content/docs/**/*
Introduces landing, getting-started, capabilities, middleware, providers, tools, and traits docs with meta pages.

Sequence Diagram(s)

sequenceDiagram
  participant Browser
  participant FileRoute as /docs/$
  participant ServerFn as createServerFn
  participant Source as Fumadocs Source
  participant ClientLoader
  Browser->>FileRoute: navigate /docs/...
  FileRoute->>ServerFn: loader(slugs)
  ServerFn->>Source: getPage/serializeTree
  Source-->>ServerFn: page, tree
  ServerFn-->>FileRoute: path + tree
  FileRoute->>ClientLoader: preload(path)
  ClientLoader-->>Browser: render MDX
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

A rabbit taps keys in a streaming breeze,
SSEs align, old comments appease.
Before and after, the hooks now sing,
Providers tidy, their models take wing.
Docs sprout routes where shaders glow—
Hop to chat-rs.com; watch tokens flow. 🐇✨

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/docs

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (2)
docs/vite.config.ts (1)

16-16: ⚡ Quick win

Remove the redundant as PluginOption cast for the Alchemy Vite plugin.

alchemy from alchemy/cloudflare/tanstack-start is already typed to return Vite-compatible PluginOption (the wrapper returns a PluginOption, including an array cast), so alchemy() as PluginOption in docs/vite.config.ts is unnecessary and can be dropped.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/vite.config.ts` at line 16, Remove the redundant type assertion on the
Alchemy Vite plugin: locate the usage of alchemy() as PluginOption and replace
it with just alchemy() (the alchemy export already returns a Vite-compatible
PluginOption/array), so drop the "as PluginOption" cast from the plugin array or
config where alchemy is included.
docs/src/router.tsx (1)

9-9: ⚡ Quick win

Consider increasing defaultPreloadStaleTime for static documentation.

Setting defaultPreloadStaleTime: 0 means preloaded routes are immediately considered stale and will refetch when navigated to, making the preload effort wasted. For a documentation site with static MDX content, consider using a longer stale time (e.g., Infinity or a large value) to benefit from preloading.

⚡ Proposed optimization
 export const getRouter = () => {
   return createRouter({
     routeTree,
     scrollRestoration: true,
-    defaultPreloadStaleTime: 0,
+    defaultPreloadStaleTime: Infinity, // or remove this line to use TanStack Router's default
   });
 };
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/src/router.tsx` at line 9, The router config currently sets
defaultPreloadStaleTime: 0 causing preloaded MDX routes to be immediately stale;
update the router preload/stale-time setting (defaultPreloadStaleTime) to a much
longer duration (e.g., Infinity or a large millisecond value) in the router
configuration where defaultPreloadStaleTime is defined so preloaded static docs
remain fresh and avoid unnecessary refetches.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/public/manifest.json`:
- Around line 2-3: Update the PWA manifest metadata by replacing the placeholder
TanStack values in the JSON fields "short_name" and "name" with the chat-rs
project identifiers (e.g., short_name: "chat-rs" and name: "chat-rs" or a more
descriptive project title). Locate the keys "short_name" and "name" in the
manifest.json and change their string values so the install prompt and app
launcher display the correct project name.

In `@docs/README.md`:
- Around line 11-24: The fenced code block showing the project tree in README.md
is missing a language tag and triggers markdownlint MD040; update that block
(the code fence wrapping the directory tree) to include a language identifier
such as "text" (i.e., change the opening ``` to ```text) so the lint warning is
cleared and formatting matches the other fenced blocks in the file.

---

Nitpick comments:
In `@docs/src/router.tsx`:
- Line 9: The router config currently sets defaultPreloadStaleTime: 0 causing
preloaded MDX routes to be immediately stale; update the router
preload/stale-time setting (defaultPreloadStaleTime) to a much longer duration
(e.g., Infinity or a large millisecond value) in the router configuration where
defaultPreloadStaleTime is defined so preloaded static docs remain fresh and
avoid unnecessary refetches.

In `@docs/vite.config.ts`:
- Line 16: Remove the redundant type assertion on the Alchemy Vite plugin:
locate the usage of alchemy() as PluginOption and replace it with just alchemy()
(the alchemy export already returns a Vite-compatible PluginOption/array), so
drop the "as PluginOption" cast from the plugin array or config where alchemy is
included.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 19aabef7-cd6d-4546-9cdd-217b7c00385b

📥 Commits

Reviewing files that changed from the base of the PR and between 3bcf49e and 3c28d95.

⛔ Files ignored due to path filters (4)
  • docs/bun.lock is excluded by !**/*.lock
  • docs/public/favicon.ico is excluded by !**/*.ico
  • docs/public/logo192.png is excluded by !**/*.png
  • docs/public/logo512.png is excluded by !**/*.png
📒 Files selected for processing (80)
  • core/src/builder.rs
  • core/src/chat/completion.rs
  • core/src/chat/mod.rs
  • core/src/chat/stream/handle.rs
  • core/src/chat/stream/input.rs
  • core/src/chat/stream/mod.rs
  • core/src/transport/impls/tokio_tungstenite.rs
  • core/src/transport/impls/tungstenite.rs
  • core/src/transport/sse.rs
  • core/src/types/messages/mod.rs
  • core/src/types/messages/parts.rs
  • core/src/types/metadata/mod.rs
  • core/src/types/metadata/usage.rs
  • core/src/types/options.rs
  • core/src/types/tools.rs
  • docs/.cta.json
  • docs/.env.example
  • docs/.gitignore
  • docs/.vscode/settings.json
  • docs/README.md
  • docs/alchemy.run.ts
  • docs/content/docs/getting-started.mdx
  • docs/content/docs/index.mdx
  • docs/content/docs/meta.json
  • docs/content/docs/openrouter.mdx
  • docs/content/docs/providers.mdx
  • docs/package.json
  • docs/public/manifest.json
  • docs/public/robots.txt
  • docs/source.config.ts
  • docs/src/components/mdx.tsx
  • docs/src/lib/layout.shared.tsx
  • docs/src/lib/source.ts
  • docs/src/routeTree.gen.ts
  • docs/src/router.tsx
  • docs/src/routes/__root.tsx
  • docs/src/routes/api/search.ts
  • docs/src/routes/docs/$.tsx
  • docs/src/routes/index.tsx
  • docs/src/styles.css
  • docs/tsconfig.json
  • docs/types/env.d.ts
  • docs/vite.config.ts
  • examples/claude/hitl.rs
  • examples/claude/stream.rs
  • examples/gemini/classification.rs
  • examples/gemini/google_maps.rs
  • examples/gemini/hitl.rs
  • examples/gemini/image_generation.rs
  • examples/gemini/image_understanding.rs
  • examples/gemini/stream.rs
  • examples/gemini/youtube.rs
  • examples/mistralrs/voice.rs
  • examples/ollama/stream.rs
  • examples/openai/hitl.rs
  • examples/openai/input_stream.rs
  • examples/openai/interactive.rs
  • examples/openai/websocket.rs
  • examples/router/capability.rs
  • providers/claude/src/api/stream.rs
  • providers/claude/src/api/types/error.rs
  • providers/claude/src/api/types/request.rs
  • providers/completions/src/api/stream.rs
  • providers/completions/src/api/types/error.rs
  • providers/completions/src/api/types/request.rs
  • providers/completions/src/api/types/response.rs
  • providers/gemini/src/api/types/error.rs
  • providers/gemini/src/api/types/request.rs
  • providers/gemini/src/api/types/response.rs
  • providers/mistralrs/src/api/stream.rs
  • providers/mistralrs/src/lib.rs
  • providers/ollama/src/lib.rs
  • providers/responses/src/api/stream.rs
  • providers/responses/src/api/types/error.rs
  • providers/responses/src/api/types/request.rs
  • providers/responses/src/api/types/response.rs
  • providers/router/src/circuit_breaker.rs
  • providers/router/src/lib.rs
  • providers/router/src/router.rs
  • providers/router/src/stream_router.rs
💤 Files with no reviewable changes (40)
  • examples/gemini/image_understanding.rs
  • examples/ollama/stream.rs
  • examples/openai/input_stream.rs
  • providers/claude/src/api/types/error.rs
  • providers/ollama/src/lib.rs
  • examples/openai/websocket.rs
  • core/src/types/messages/mod.rs
  • examples/gemini/image_generation.rs
  • core/src/types/tools.rs
  • examples/gemini/youtube.rs
  • core/src/types/metadata/mod.rs
  • examples/router/capability.rs
  • providers/mistralrs/src/api/stream.rs
  • core/src/transport/sse.rs
  • providers/completions/src/api/types/error.rs
  • providers/completions/src/api/types/response.rs
  • providers/mistralrs/src/lib.rs
  • core/src/chat/stream/handle.rs
  • examples/gemini/google_maps.rs
  • core/src/chat/stream/input.rs
  • providers/claude/src/api/types/request.rs
  • providers/responses/src/api/types/error.rs
  • providers/completions/src/api/stream.rs
  • providers/gemini/src/api/types/response.rs
  • providers/responses/src/api/types/response.rs
  • providers/gemini/src/api/types/error.rs
  • providers/router/src/stream_router.rs
  • core/src/types/metadata/usage.rs
  • core/src/chat/stream/mod.rs
  • providers/responses/src/api/stream.rs
  • core/src/chat/completion.rs
  • core/src/types/messages/parts.rs
  • providers/completions/src/api/types/request.rs
  • core/src/builder.rs
  • examples/gemini/hitl.rs
  • providers/router/src/router.rs
  • providers/responses/src/api/types/request.rs
  • examples/gemini/classification.rs
  • core/src/transport/impls/tokio_tungstenite.rs
  • providers/router/src/lib.rs

Comment thread docs/public/manifest.json Outdated
Comment thread docs/README.md
Comment on lines +11 to +24
```
docs/
├── content/docs/ ← MDX documentation pages
├── src/
│ ├── routes/
│ │ ├── index.tsx ← landing page
│ │ ├── docs/$.tsx ← Fumadocs catch-all docs route
│ │ └── api/search.ts ← search endpoint
│ ├── lib/source.ts ← Fumadocs content source
│ └── components/mdx.tsx
├── source.config.ts ← fumadocs-mdx collection config
├── alchemy.run.ts ← Cloudflare deploy definition
└── vite.config.ts
```
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add a language to the fenced code block.

markdownlint (MD040) flags this block. Tagging it (e.g. text) clears the lint warning and is consistent with the other fenced blocks in this file.

📝 Proposed fix
-```
+```text
 docs/
 ├── content/docs/        ← MDX documentation pages
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 11-11: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/README.md` around lines 11 - 24, The fenced code block showing the
project tree in README.md is missing a language tag and triggers markdownlint
MD040; update that block (the code fence wrapping the directory tree) to include
a language identifier such as "text" (i.e., change the opening ``` to ```text)
so the lint warning is cleared and formatting matches the other fenced blocks in
the file.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🧹 Nitpick comments (1)
docs/src/components/FaultyTerminal.tsx (1)

399-419: 💤 Low value

gridMul array literal in deps re-initializes the WebGL context on every re-render.

gridMul is an object dependency, and the homepage passes a new [2, 1] literal each render. Whenever the parent re-renders, the effect tears down and recreates the renderer/program/observer instead of just updating the uniform. Today the parent rarely re-renders so impact is small, but it's a sharp edge. Consider memoizing the value (like tintVec/ditherValue) and depending on the stable reference.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/src/components/FaultyTerminal.tsx` around lines 399 - 419, The effect in
FaultyTerminal re-creates the WebGL renderer because gridMul is an unstable
array literal in the deps; fix by using a stable reference instead of the raw
array: either memoize gridMul in the parent (so the homepage passes a stable
array) or derive a stable local value inside FaultyTerminal (e.g. const
stableGridMul = useMemo(() => [gridMul[0], gridMul[1]], [gridMul[0],
gridMul[1]])) and replace gridMul in the useEffect dependency list with that
stableGridMul (or its scalar components) so the renderer/program/observer are
not torn down on every re-render.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/content/docs/providers/router.mdx`:
- Around line 261-268: The docs imply Router directly supports embeddings;
instead, clarify that embedding-based ranking requires the strategy to call a
separate embeddings-capable client — Router itself does not implement embeddings
or handle chat.embed() calls. Update the "Advanced: routing by embeddings"
paragraph to add a sentence stating that the strategy must obtain embeddings
from a single embedding provider/client (e.g., via an embeddings client used
inside the strategy's rank function) and that Router does not serve chat.embed()
itself. Mention the Router type and the strategy's rank method to make it clear
where to perform embedding calls.

In `@docs/src/components/FaultyTerminal.tsx`:
- Line 422: The div rendering in FaultyTerminal.tsx uses a template string that
appends className directly, which yields a literal "undefined" class when
className is not provided; update the JSX for the div (the element with
ref={containerRef} and props style and {...rest}) to join classes conditionally
instead of interpolating undefined—either wrap className in a ternary (e.g.,
baseClasses + (className ? ` ${className}` : '')) or use the existing cn helper
(cn('w-full h-full relative overflow-hidden', className)); ensure to import/use
cn if not already imported and keep ref={containerRef}, style, and {...rest}
unchanged.
- Line 260: The default for the dpr prop in FaultyTerminal currently reads from
window (dpr = Math.min(window.devicePixelRatio || 1, 2)) which will throw during
SSR; change the default to guard window access (e.g., use typeof window !==
"undefined" ? Math.min(window.devicePixelRatio || 1, 2) : 1) so server renders
use a safe fallback. Locate the dpr default in the FaultyTerminal component and
replace the direct window access with the guarded expression so omitted dpr
props are SSR-safe.

In `@docs/src/styles.css`:
- Line 147: Remove unnecessary quotes around single-token font family names to
satisfy stylelint's font-family-name-quotes rule: update the font-family
declarations that use "Orbit" and "Geist" so they are unquoted (e.g., change
"Orbit" -> Orbit and "Geist" -> Geist) while keeping fallback families
(ui-monospace, monospace) intact; locate these in the CSS rule containing
font-family: "Orbit", ui-monospace, monospace and the `@theme` block that declares
"Geist" and drop the quotes.

---

Nitpick comments:
In `@docs/src/components/FaultyTerminal.tsx`:
- Around line 399-419: The effect in FaultyTerminal re-creates the WebGL
renderer because gridMul is an unstable array literal in the deps; fix by using
a stable reference instead of the raw array: either memoize gridMul in the
parent (so the homepage passes a stable array) or derive a stable local value
inside FaultyTerminal (e.g. const stableGridMul = useMemo(() => [gridMul[0],
gridMul[1]], [gridMul[0], gridMul[1]])) and replace gridMul in the useEffect
dependency list with that stableGridMul (or its scalar components) so the
renderer/program/observer are not torn down on every re-render.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6ebf3743-9749-4893-b98e-fd388d391ec0

📥 Commits

Reviewing files that changed from the base of the PR and between 3c28d95 and fe26554.

⛔ Files ignored due to path filters (1)
  • docs/bun.lock is excluded by !**/*.lock
📒 Files selected for processing (60)
  • core/src/builder.rs
  • docs/components.json
  • docs/content/docs/capabilities/embeddings.mdx
  • docs/content/docs/capabilities/index.mdx
  • docs/content/docs/capabilities/meta.json
  • docs/content/docs/capabilities/multimodal.mdx
  • docs/content/docs/capabilities/streaming.mdx
  • docs/content/docs/capabilities/structured-output.mdx
  • docs/content/docs/getting-started.mdx
  • docs/content/docs/index.mdx
  • docs/content/docs/meta.json
  • docs/content/docs/middleware/index.mdx
  • docs/content/docs/middleware/meta.json
  • docs/content/docs/middleware/retries.mdx
  • docs/content/docs/providers/cerebras.mdx
  • docs/content/docs/providers/claude.mdx
  • docs/content/docs/providers/completions.mdx
  • docs/content/docs/providers/deepseek.mdx
  • docs/content/docs/providers/gemini.mdx
  • docs/content/docs/providers/huggingface.mdx
  • docs/content/docs/providers/index.mdx
  • docs/content/docs/providers/meta.json
  • docs/content/docs/providers/mistralrs.mdx
  • docs/content/docs/providers/ollama.mdx
  • docs/content/docs/providers/openai.mdx
  • docs/content/docs/providers/openrouter.mdx
  • docs/content/docs/providers/responses.mdx
  • docs/content/docs/providers/router.mdx
  • docs/content/docs/tools/context.mdx
  • docs/content/docs/tools/human-in-the-loop.mdx
  • docs/content/docs/tools/index.mdx
  • docs/content/docs/tools/meta.json
  • docs/content/docs/tools/native.mdx
  • docs/content/docs/tools/python.mdx
  • docs/content/docs/traits/completion-provider.mdx
  • docs/content/docs/traits/embeddings-provider.mdx
  • docs/content/docs/traits/index.mdx
  • docs/content/docs/traits/meta.json
  • docs/content/docs/traits/stream-provider.mdx
  • docs/package.json
  • docs/public/icon-dark.webp
  • docs/public/icon-light.webp
  • docs/public/logo-dark.webp
  • docs/public/logo-light.webp
  • docs/public/manifest.json
  • docs/src/components/FaultyTerminal.tsx
  • docs/src/components/code-gallery.tsx
  • docs/src/components/copyable-code.tsx
  • docs/src/components/ui/badge.tsx
  • docs/src/components/ui/button.tsx
  • docs/src/components/ui/card.tsx
  • docs/src/components/ui/separator.tsx
  • docs/src/components/ui/tabs.tsx
  • docs/src/lib/layout.shared.tsx
  • docs/src/lib/utils.ts
  • docs/src/routes/__root.tsx
  • docs/src/routes/index.tsx
  • docs/src/styles.css
  • providers/claude/src/lib.rs
  • providers/gemini/src/lib.rs
✅ Files skipped from review due to trivial changes (29)
  • docs/content/docs/middleware/meta.json
  • docs/content/docs/providers/meta.json
  • docs/src/lib/utils.ts
  • docs/src/components/ui/separator.tsx
  • docs/content/docs/traits/meta.json
  • docs/content/docs/capabilities/index.mdx
  • docs/content/docs/capabilities/meta.json
  • docs/content/docs/capabilities/embeddings.mdx
  • docs/content/docs/traits/stream-provider.mdx
  • docs/content/docs/providers/ollama.mdx
  • docs/content/docs/middleware/retries.mdx
  • docs/src/components/ui/card.tsx
  • docs/content/docs/traits/index.mdx
  • docs/content/docs/tools/meta.json
  • docs/content/docs/providers/cerebras.mdx
  • docs/content/docs/getting-started.mdx
  • docs/content/docs/tools/python.mdx
  • docs/content/docs/providers/openrouter.mdx
  • docs/content/docs/tools/index.mdx
  • docs/content/docs/tools/human-in-the-loop.mdx
  • docs/content/docs/traits/completion-provider.mdx
  • docs/content/docs/providers/huggingface.mdx
  • docs/content/docs/tools/native.mdx
  • docs/content/docs/providers/mistralrs.mdx
  • docs/content/docs/middleware/index.mdx
  • docs/content/docs/index.mdx
  • docs/content/docs/providers/index.mdx
  • docs/content/docs/providers/openai.mdx
  • docs/content/docs/traits/embeddings-provider.mdx
🚧 Files skipped from review as they are similar to previous changes (4)
  • docs/public/manifest.json
  • docs/src/lib/layout.shared.tsx
  • docs/package.json
  • docs/src/routes/__root.tsx

Comment on lines +261 to +268
## Advanced: routing by embeddings

Because a strategy can do async work inside `rank`, you are not limited to
keyword matching. `examples/router/embeddings.rs` embeds a short description of
each provider at build time, stores the vector under
`.with_metadata("embedding", vector)`, and at request time embeds the user's
message and ranks providers by cosine similarity. That gives you semantic
routing without changing anything about how the Router is built or used.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clarify that embedding-based ranking still uses a separate embeddings client.

This section reads close to “Router supports embeddings,” but routing by embeddings only works if the strategy calls some separate embeddings-capable provider/client. Add one sentence making it explicit that Router still cannot serve chat.embed() itself.

Based on learnings: "Router does not support embeddings—embeddings must use a single provider without routing".

🧰 Tools
🪛 LanguageTool

[style] ~264-~264: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...examples/router/embeddings.rs` embeds a short description of each provider at build t...

(QUICK_BRIEF)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/content/docs/providers/router.mdx` around lines 261 - 268, The docs
imply Router directly supports embeddings; instead, clarify that embedding-based
ranking requires the strategy to call a separate embeddings-capable client —
Router itself does not implement embeddings or handle chat.embed() calls. Update
the "Advanced: routing by embeddings" paragraph to add a sentence stating that
the strategy must obtain embeddings from a single embedding provider/client
(e.g., via an embeddings client used inside the strategy's rank function) and
that Router does not serve chat.embed() itself. Mention the Router type and the
strategy's rank method to make it clear where to perform embedding calls.

tint = '#ffffff',
mouseReact = true,
mouseStrength = 0.2,
dpr = Math.min(window.devicePixelRatio || 1, 2),
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

Does TanStack Start server-side render route components by default?

💡 Result:

Yes, TanStack Start renders route components on the server by default [1][2]. When this default behavior is active, the following occurs during the initial server request: - The route's beforeLoad and loader functions are executed on the server [1][3]. - The route component is rendered on the server to generate HTML, which is then sent to the client for hydration [1][3]. This behavior can be configured or disabled globally or on a per-route basis [1][3]: - Per-Route: You can set the ssr property to false in a route's configuration to disable server-side execution of loaders and server-side rendering of the component for that specific route [1][3]. - Globally: You can change the default SSR behavior for the entire application using the defaultSsr option within the createStart configuration [1][3][4]. Note that child routes inherit the ssr configuration from their parent, and they can only be restricted further (e.g., a child route cannot enable SSR if the parent has explicitly disabled it) [1][3].

Citations:


🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Locate the file and inspect around the line with the window default param
ls -la docs/src/components/FaultyTerminal.tsx 2>/dev/null || true
sed -n '220,320p' docs/src/components/FaultyTerminal.tsx

# Find where FaultyTerminal is used and whether dpr is always passed
rg -n "FaultyTerminal" -S docs/src || true
rg -n "dpr=\{?[^}]*\}?" -S docs/src/components/FaultyTerminal.tsx docs/src || true

# Inspect router/start app configuration for SSR defaults (createStart / defaultSsr / ssr: false)
rg -n "defaultSsr|ssr\\s*:\\s*false|createStart\\(" -S docs/src . || true

# If there is a start config file, print it
fd -a "start*.ts" docs/src -tf || true
fd -a "tanstack-start*.ts" . -tf || true
fd -a "router*.ts" docs/src -tf || true

Repository: EggerMarc/chat-rs

Length of output: 3660


🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Show the actual file tree bits where configs might live
find docs -maxdepth 4 -type f \( -name "*start*" -o -name "*router*" -o -name "*ssr*" \) | head -n 200

Repository: EggerMarc/chat-rs

Length of output: 201


🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Locate the file and inspect around the line with the window default param
ls -la docs/src/components/FaultyTerminal.tsx 2>/dev/null || true
sed -n '220,320p' docs/src/components/FaultyTerminal.tsx

# Find where FaultyTerminal is used and whether dpr is always passed
rg -n "FaultyTerminal" -S docs/src || true
rg -n "dpr" -S docs/src/components/FaultyTerminal.tsx docs/src || true

# Inspect router/start app configuration for SSR defaults (createStart / defaultSsr / ssr: false)
rg -n "defaultSsr|ssr\\s*:\\s*false|createStart\\(" -S docs/src . || true

# List likely config files
find . -maxdepth 4 -type f \( -name "*start*" -o -name "*router*" -o -name "*ssr*" \) | head -n 200

Repository: EggerMarc/chat-rs

Length of output: 5168


🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect FaultyTerminal around the offending line
ls -la docs/src/components/FaultyTerminal.tsx 2>/dev/null || true
sed -n '240,290p' docs/src/components/FaultyTerminal.tsx

# Find where FaultyTerminal is used and how dpr is passed
rg -n "FaultyTerminal" -S docs/src || true
rg -n "FaultyTerminal\\b" -S . || true
rg -n "\\bdpr\\b" -S docs/src/components/FaultyTerminal.tsx docs/src || true
rg -n "dpr=\\{?" -S docs/src || true

# Check for TanStack Start SSR configuration
rg -n "defaultSsr|ssr\\s*:\\s*false|createStart\\(" -S . || true

# List likely start/router config files
find . -maxdepth 5 -type f \( -name "*start*" -o -name "*router*" -o -name "*ssr*" \) | head -n 200

Repository: EggerMarc/chat-rs

Length of output: 3251


🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect FaultyTerminal around the offending line
ls -la docs/src/components/FaultyTerminal.tsx 2>/dev/null || true
sed -n '240,290p' docs/src/components/FaultyTerminal.tsx

# Find where FaultyTerminal is used and how dpr is passed
rg -n "FaultyTerminal" -S docs/src || true
rg -n "FaultyTerminal\\b" -S . || true
rg -n "\\bdpr\\b" -S docs/src/components/FaultyTerminal.tsx docs/src || true
rg -n "dpr=\\{?" -S docs/src || true

# Check for TanStack Start SSR configuration
rg -n "defaultSsr|ssr\\s*:\\s*false|createStart\\(" -S . || true

# List likely start/router config files
find . -maxdepth 5 -type f \( -name "*start*" -o -name "*router*" -o -name "*ssr*" \) | head -n 200

Repository: EggerMarc/chat-rs

Length of output: 3251


🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect FaultyTerminal around the offending line
ls -la docs/src/components/FaultyTerminal.tsx 2>/dev/null || true
sed -n '240,290p' docs/src/components/FaultyTerminal.tsx

# Find where FaultyTerminal is used and how dpr is passed
rg -n "FaultyTerminal" -S docs/src || true
rg -n "FaultyTerminal\\b" -S . || true
rg -n "\\bdpr\\b" -S docs/src/components/FaultyTerminal.tsx docs/src || true
rg -n "dpr=\\{?" -S docs/src || true

# Check for TanStack Start SSR configuration
rg -n "defaultSsr|ssr\\s*:\\s*false|createStart\\(" -S . || true

# List likely start/router config files
find . -maxdepth 5 -type f \( -name "*start*" -o -name "*router*" -o -name "*ssr*" \) | head -n 200

Repository: EggerMarc/chat-rs

Length of output: 3251


Guard window access in FaultyTerminal’s dpr default for SSR

dpr = Math.min(window.devicePixelRatio || 1, 2) is evaluated whenever the dpr prop is omitted; with TanStack Start server-rendering routes by default, rendering FaultyTerminal without dpr would throw on the server. Current usage passes dpr={1} (so it’s latent), but the component is still unsafe for any other render without dpr.

🛡️ Proposed guard
-  dpr = Math.min(window.devicePixelRatio || 1, 2),
+  dpr = Math.min(typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1, 2),
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
dpr = Math.min(window.devicePixelRatio || 1, 2),
dpr = Math.min(typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1, 2),
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/src/components/FaultyTerminal.tsx` at line 260, The default for the dpr
prop in FaultyTerminal currently reads from window (dpr =
Math.min(window.devicePixelRatio || 1, 2)) which will throw during SSR; change
the default to guard window access (e.g., use typeof window !== "undefined" ?
Math.min(window.devicePixelRatio || 1, 2) : 1) so server renders use a safe
fallback. Locate the dpr default in the FaultyTerminal component and replace the
direct window access with the guarded expression so omitted dpr props are
SSR-safe.

]);

return (
<div ref={containerRef} className={`w-full h-full relative overflow-hidden ${className}`} style={style} {...rest} />
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

className interpolation emits a literal undefined class.

When className is unset, the template string produces "... overflow-hidden undefined", adding a stray undefined class. Use conditional joining (or the existing cn helper) instead.

🔧 Proposed fix
-    <div ref={containerRef} className={`w-full h-full relative overflow-hidden ${className}`} style={style} {...rest} />
+    <div ref={containerRef} className={`w-full h-full relative overflow-hidden${className ? ` ${className}` : ""}`} style={style} {...rest} />
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<div ref={containerRef} className={`w-full h-full relative overflow-hidden ${className}`} style={style} {...rest} />
<div ref={containerRef} className={`w-full h-full relative overflow-hidden${className ? ` ${className}` : ""}`} style={style} {...rest} />
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/src/components/FaultyTerminal.tsx` at line 422, The div rendering in
FaultyTerminal.tsx uses a template string that appends className directly, which
yields a literal "undefined" class when className is not provided; update the
JSX for the div (the element with ref={containerRef} and props style and
{...rest}) to join classes conditionally instead of interpolating
undefined—either wrap className in a ternary (e.g., baseClasses + (className ? `
${className}` : '')) or use the existing cn helper (cn('w-full h-full relative
overflow-hidden', className)); ensure to import/use cn if not already imported
and keep ref={containerRef}, style, and {...rest} unchanged.

Comment thread docs/src/styles.css

/* Orbit — the "engineering drawing" voice for indices, eyebrows, tags. */
.font-label {
font-family: "Orbit", ui-monospace, monospace;
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Stylelint: remove quotes around single-token font name.

font-family-name-quotes flags "Orbit" since it needs no quotes. The same applies to "Geist" on Line 55 once the @theme block parses. Drop the quotes to clear the lint error.

🔧 Proposed fix
-  font-family: "Orbit", ui-monospace, monospace;
+  font-family: Orbit, ui-monospace, monospace;
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
font-family: "Orbit", ui-monospace, monospace;
font-family: Orbit, ui-monospace, monospace;
🧰 Tools
🪛 Stylelint (17.12.0)

[error] 147-147: Expected no quotes around "Orbit" (font-family-name-quotes)

(font-family-name-quotes)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/src/styles.css` at line 147, Remove unnecessary quotes around
single-token font family names to satisfy stylelint's font-family-name-quotes
rule: update the font-family declarations that use "Orbit" and "Geist" so they
are unquoted (e.g., change "Orbit" -> Orbit and "Geist" -> Geist) while keeping
fallback families (ui-monospace, monospace) intact; locate these in the CSS rule
containing font-family: "Orbit", ui-monospace, monospace and the `@theme` block
that declares "Geist" and drop the quotes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant