feat(desktop): embed BoosAPI Desktop client as a subproject
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.
This commit is contained in:
boos
@@ -0,0 +1,127 @@
|
||||
---
|
||||
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](/guide/troubleshooting#css-looks-wrong-start-here) | [Tailwind Integration & Style Ordering](/guide/tailwind) |
|
||||
| A trusted tag like `<thinking>` renders as raw HTML | [Docs Site & VitePress](/guide/vitepress-docs-integration) or [Custom Tags & Advanced Components](/guide/custom-components) | [API Reference](/guide/api) |
|
||||
| `window is not defined` or browser-only peers crash during SSR | [Troubleshooting](/guide/troubleshooting) | [Nuxt SSR](/nuxt-ssr) |
|
||||
| Mermaid, KaTeX, Monaco, or D2 does not render | [Installation](/guide/installation) | [Renderer & Node Components](/guide/components) |
|
||||
| Chat output feels slow or reparses too much | [AI Chat & Streaming](/guide/ai-chat-streaming) | [Performance](/guide/performance) |
|
||||
| A built-in node is the wrong shape for your app | [Override Built-in Components](/guide/component-overrides) | [Renderer & Node Components](/guide/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:
|
||||
|
||||
1. import your reset before `markstream-vue/index.css`
|
||||
2. if you use Tailwind or UnoCSS, wrap the import in `@layer components`
|
||||
3. if math is enabled, import `katex/dist/katex.min.css`
|
||||
4. if the renderer lives in a larger app surface, scope overrides with `custom-id`
|
||||
|
||||
Start with the CSS checklist: [Troubleshooting](/guide/troubleshooting#css-looks-wrong-start-here)
|
||||
|
||||
## 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:
|
||||
|
||||
1. make sure the tag is listed in `custom-html-tags`
|
||||
2. register the mapping with `setCustomComponents(customId, mapping)`
|
||||
3. render the page with the matching `custom-id`
|
||||
4. if you are in VitePress, put the registration in `enhanceApp`
|
||||
|
||||
Best paths:
|
||||
|
||||
- docs-site or theme case: [Docs Site & VitePress](/guide/vitepress-docs-integration)
|
||||
- app-level custom tags: [Custom Tags & Advanced Components](/guide/custom-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:
|
||||
|
||||
1. confirm whether the failing peer is browser-only
|
||||
2. move that initialization behind client-only boundaries
|
||||
3. keep server-safe rendering on the base `MarkdownRender` path
|
||||
|
||||
Best paths:
|
||||
|
||||
- general checklist: [Troubleshooting](/guide/troubleshooting)
|
||||
- Nuxt-specific rules: [Nuxt SSR](/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](/guide/installation), then confirm the component-specific notes in [Renderer & Node Components](/guide/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](/guide/ai-chat-streaming), then [Performance](/guide/performance)
|
||||
|
||||
## 6. Still not sure?
|
||||
|
||||
If you still cannot classify the issue:
|
||||
|
||||
1. reproduce it in the playground with the smallest Markdown sample possible
|
||||
2. remove optional peers until the failure becomes simpler
|
||||
3. compare against the nearest scenario guide:
|
||||
`Docs Site & VitePress`, `AI Chat & Streaming`, or `Usage & 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](/guide/troubleshooting).
|
||||
Reference in New Issue
Block a user