boos
e0a5f57793
Vendor the rebranded BoosAPI Desktop client (Tauri + Vue) into metapi as a monorepo subdirectory under desktop/. Source only — node_modules, dist, Cargo target and the upstream .git history are excluded. desktop/ keeps its own independent Cargo workspace (desktop/src-tauri with crates/*); it is not part of the backend boosapi crate, so a `cargo check` at the metapi root still compiles only the backend. Build the desktop app from desktop/src-tauri per desktop/README.md. Note: app icons are still placeholder assets pending the final BoosAPI logo. The updater signing keys live outside the repo and are not included.
4.7 KiB
4.7 KiB
description
| description |
|---|
| Diagnose markstream-vue problems by symptom across CSS order, missing peers, SSR boundaries, trusted tags, and streaming performance. |
Troubleshooting by Symptom
Use this page when something is wrong but you are not yet sure whether the cause is CSS order, missing peers, SSR boundaries, custom-tag wiring, or renderer choice.
If you already know the exact subsystem, jump straight to the deeper page linked from each section below.
Start with the symptom you see
| What you see | Start here | Then go to |
|---|---|---|
| Styles look broken, spacing is off, or Tailwind wins | CSS looks wrong? Start here | Tailwind Integration & Style Ordering |
A trusted tag like <thinking> renders as raw HTML |
Docs Site & VitePress or Custom Tags & Advanced Components | API Reference |
window is not defined or browser-only peers crash during SSR |
Troubleshooting | Nuxt SSR |
| Mermaid, KaTeX, Monaco, or D2 does not render | Installation | Renderer & Node Components |
| Chat output feels slow or reparses too much | AI Chat & Streaming | Performance |
| A built-in node is the wrong shape for your app | Override Built-in Components | Renderer & Node Components |
1. Styles look wrong
Symptoms:
- paragraphs, tables, or lists have odd spacing
- code blocks or images look unstyled
- utility classes from Tailwind or UnoCSS override the renderer
Check in this order:
- import your reset before
markstream-vue/index.css - if you use Tailwind or UnoCSS, wrap the import in
@layer components - if math is enabled, import
katex/dist/katex.min.css - if the renderer lives in a larger app surface, scope overrides with
custom-id
Start with the CSS checklist: Troubleshooting
2. Custom tags or custom components do not appear
Symptoms:
<thinking>shows up as raw HTML- your custom Vue component never renders
- the component works in one place but not another
Check in this order:
- make sure the tag is listed in
custom-html-tags - register the mapping with
setCustomComponents(customId, mapping) - render the page with the matching
custom-id - if you are in VitePress, put the registration in
enhanceApp
Best paths:
- docs-site or theme case: Docs Site & VitePress
- app-level custom tags: Custom Tags & Advanced Components
3. SSR errors or browser-only crashes
Symptoms:
window is not defined- Mermaid or Monaco works locally but fails in SSR
- hydration differs between server and client
Check in this order:
- confirm whether the failing peer is browser-only
- move that initialization behind client-only boundaries
- keep server-safe rendering on the base
MarkdownRenderpath
Best paths:
- general checklist: Troubleshooting
- Nuxt-specific rules: Nuxt SSR
4. Heavy features do not render
Symptoms:
- Mermaid fences stay as source text
- formulas stay blank
- Monaco blocks are empty
- D2 falls back to source
Most of the time, this is not a parser bug. It is one of:
- the peer package is not installed
- required CSS is missing, especially for KaTeX
- SSR or worker boundaries are wrong
Start with Installation, then confirm the component-specific notes in Renderer & Node Components.
5. Streaming or chat output feels slow
Symptoms:
- every token update causes visible reflow
- long chat transcripts get heavy quickly
- the app reparses too much Markdown on each update
The usual fix is architectural rather than cosmetic:
- parse outside
MarkdownRender - pass
nodes+final - keep heavy peers off until they are needed
Best path: AI Chat & Streaming, then Performance
6. Still not sure?
If you still cannot classify the issue:
- reproduce it in the playground with the smallest Markdown sample possible
- remove optional peers until the failure becomes simpler
- compare against the nearest scenario guide:
Docs Site & VitePress,AI Chat & Streaming, orUsage & Streaming
If it still looks like a real bug, collect:
- the minimal Markdown sample
- framework/runtime details
- whether Tailwind, UnoCSS, or SSR is involved
- which optional peers are installed
Then use the hosted test page or issue link from Troubleshooting.