blume 1.6.0 → 1.6.1

package/dist/types/core/data.d.ts

@@ -82,6 +82,11 @@ export interface BlumeRoute {
     alternates: RouteAlternate[];
     /** Astro collection the entry renders through (`"docs"` | `"staged"`). */
     collection: string;
+    /**
+     * Meta description as the page head renders it (`seo.description` over the
+     * front matter `description`), or `null` when the page declares neither.
+     */
+    description: string | null;
     draft: boolean;
     /** "Edit this page" URL, or `null` when no repo/source provides one. */
     editUrl: string | null;
@@ -176,7 +181,11 @@ export interface BlumeDataConfig {
      * kept out of this snapshot, which pages serialize into HTML.
      */
     og: {
-        /** Card subtitle: `seo.og.description` (`false` omits it) over the site description. */
+        /**
+         * Site-wide card subtitle: `seo.og.description` (`false` omits it) over
+         * the site description. A page with its own description shows that
+         * instead; this is the fallback for pages without one.
+         */
         description?: string;
         enabled: boolean;
         /** Inlined SVG brand mark; `false` renders the card without any mark. */

package/dist/types/core/i18n-ui.d.ts

@@ -17,6 +17,7 @@ declare const uiStringsObject: z.ZodObject<{
         copyClaudeCode: z.ZodDefault<z.ZodString>;
         copyCode: z.ZodDefault<z.ZodString>;
         copyCodex: z.ZodDefault<z.ZodString>;
+        copyFailed: z.ZodDefault<z.ZodString>;
         copyMarkdown: z.ZodDefault<z.ZodString>;
         copyServerUrl: z.ZodDefault<z.ZodString>;
         edit: z.ZodDefault<z.ZodString>;
@@ -129,6 +130,7 @@ export declare const uiStringsSchema: z.ZodPrefault<z.ZodObject<{
         copyClaudeCode: z.ZodDefault<z.ZodString>;
         copyCode: z.ZodDefault<z.ZodString>;
         copyCodex: z.ZodDefault<z.ZodString>;
+        copyFailed: z.ZodDefault<z.ZodString>;
         copyMarkdown: z.ZodDefault<z.ZodString>;
         copyServerUrl: z.ZodDefault<z.ZodString>;
         edit: z.ZodDefault<z.ZodString>;

package/dist/types/core/schema.d.ts

@@ -477,6 +477,7 @@ declare const openapiSourceSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     noindex: z.ZodDefault<z.ZodBoolean>;
     route: z.ZodOptional<z.ZodString>;
+    seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
     spec: z.ZodString;
 }, z.core.$strict>;
 export type OpenApiSource = z.input<typeof openapiSourceSchema>;
@@ -492,6 +493,7 @@ declare const graphqlSourceSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     noindex: z.ZodDefault<z.ZodBoolean>;
     route: z.ZodOptional<z.ZodString>;
+    seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
     spec: z.ZodString;
     endpoint: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -598,6 +600,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
             route: z.ZodOptional<z.ZodString>;
+            seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
         }, z.core.$strict>>>;
         spec: z.ZodOptional<z.ZodString>;
@@ -795,6 +798,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
             route: z.ZodOptional<z.ZodString>;
+            seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
             endpoint: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
@@ -942,6 +946,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
             route: z.ZodOptional<z.ZodString>;
+            seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
         }, z.core.$strict>>>;
         spec: z.ZodOptional<z.ZodString>;

package/dist/types/core/types.d.ts

@@ -347,6 +347,12 @@ export interface RouteManifestEntry {
     /** Adapter-supplied "edit this page" URL (non-filesystem sources). */
     editUrl?: string;
     title: string;
+    /**
+     * The page's meta description as the head renders it: `seo.description`
+     * over the front matter `description`. Feeds the generated OG card's
+     * subtitle, so a shared link's image and its `og:description` agree.
+     */
+    description?: string;
     contentType: string;
     hidden: boolean;
     draft: boolean;

package/dist/types/openapi/references.d.ts

@@ -47,6 +47,11 @@ export interface ReferenceSource {
     includeInSearch: boolean;
     /** Whether generated pages emit noindex metadata and stay out of the sitemap. */
     noindex: boolean;
+    /**
+     * Whether operation meta descriptions end with the generated English
+     * "Reference for …" sentence, or carry the spec's own prose alone.
+     */
+    seoDescriptionSuffix: boolean;
     /** Local path or `http(s)` URL, verbatim from config. */
     spec: string;
     /**

package/docs/07-faq.mdx

@@ -87,14 +87,14 @@ We reported it upstream in [oxc-project/oxc#24096](https://github.com/oxc-projec
 
 Patch oxfmt so it preserves the line break that sits directly against a `:::` fence. Blume ships the same fix in its own repo, and you can apply it in any project.
 
-1. Save the patch as `patches/oxfmt@0.61.0.patch`:
-
-   ```diff patches/oxfmt@0.61.0.patch
-   diff --git a/dist/markdown-ZuiQU4Xe.js b/dist/markdown-ZuiQU4Xe.js
-   index 566b9e6d27f36061d64b93736e238e871e1ee2b2..82d0595acc010807c2939fc4a1717dde887a8555 100644
-   --- a/dist/markdown-ZuiQU4Xe.js
-   +++ b/dist/markdown-ZuiQU4Xe.js
-   @@ -4875,7 +4875,43 @@ function lu(e, t, r) {
+1. Save the patch as `patches/oxfmt@0.66.0.patch`:
+
+   ```diff patches/oxfmt@0.66.0.patch
+   diff --git a/dist/markdown-BgZGxhM2.js b/dist/markdown-BgZGxhM2.js
+   index 859231f9387a50df16419bc22b5268c4e446ddbc..dcc0ffda6f71adb27a03e3918a3db6fc7a58ffe9 100644
+   --- a/dist/markdown-BgZGxhM2.js
+   +++ b/dist/markdown-BgZGxhM2.js
+   @@ -4872,7 +4872,43 @@ function lu(e, t, r) {
     		case "sentence": return Oh(e, r);
     		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
     		case "whitespace": {
@@ -146,7 +146,7 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    ```json package.json
    {
      "patchedDependencies": {
-       "oxfmt@0.61.0": "patches/oxfmt@0.61.0.patch"
+       "oxfmt@0.66.0": "patches/oxfmt@0.66.0.patch"
      }
    }
    ```

package/docs/advanced/api-reference.mdx

@@ -139,6 +139,15 @@ openapi: {
 - `includeInLlms: false` keeps them out of both `llms.txt` files.
 - `noindex: true` adds crawler noindex metadata and removes the pages from the sitemap.
 
+Each operation page's meta description is the operation's own `description` (or `summary`), followed by a generated sentence naming the endpoint — "Reference for the `GET /pets` endpoint in the Petstore API." — so a spec of terse one-line summaries still ships a distinct, snippet-length description per page. That sentence is English. On a site whose spec prose is written in another language, set `seoDescriptionSuffix: false` on the source to drop it and describe each page with the authored prose alone; an operation with neither a `description` nor a `summary` falls back to its title (`GET /pets`), so no page ships an empty description:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
+}
+```
+
 With the [Scalar renderer](#the-scalar-renderer), only `noindex` applies — a Scalar-rendered reference already sits outside Blume's search and `llms.txt`, so the two `include*` settings have nothing to act on there.
 
 ## Authorization
@@ -202,7 +211,7 @@ AsyncAPI **2.x specs are normalized to 3.x automatically** with the official Asy
 
 Code samples are **protocol-aware**, keyed off the operation's binding (or its servers' protocol): `wscat` and a browser `WebSocket` snippet for WebSockets, `kcat` for Kafka, `mosquitto_pub`/`mosquitto_sub` for MQTT. `codeSamples` filters that set, the same way it picks languages on the `openapi` block; a protocol without a supported tool renders the message payload example alone rather than a fabricated client.
 
-Everything documented above carries over, [`playground`](#try-it-for-events) included: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags, and search indexing by operation summary and tag.
+Everything documented above carries over, [`playground`](#try-it-for-events) included: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags (`seoDescriptionSuffix` too — the generated sentence names the channel and action instead of an endpoint), and search indexing by operation summary and tag.
 
 Setting `renderer: "scalar"` opts back into the embedded Scalar SPA, where — as with OpenAPI — only `noindex` applies. Scalar has no AsyncAPI playground of its own; its embed auto-detects the document type and renders channels, operations, messages, and a Models section, so that swap trades the composer away.
 

package/docs/advanced/custom-pages.mdx

@@ -272,7 +272,9 @@ import data from "blume:data";
 
 ## 404 page
 
-Blume ships a default **not found** page out of the box: a centered "404" message wrapped in the site chrome (header, search, theme), served for any unmatched URL. `blume build` writes it to `404.html`, which static hosts serve automatically, and `blume dev` shows it for unknown routes.
+Blume ships a default **not found** page out of the box: a centered "404" message wrapped in the site chrome (header, search, theme), served for any unmatched URL. `blume build` writes it to `404.html`, which static hosts serve automatically, and `blume dev` shows it for unknown routes. Under the message, a **Where to look next** list links every top-level section plus the `sitemap.xml` and [`llms.txt`](/docs/configuration/ai#llmstxt) indexes when they exist, so a reader — or an agent that followed a stale URL — has a way back.
+
+The page also has a Markdown twin at `/404.md` with the same recovery links (absolute URLs once [`deployment.site`](/docs/deployment) is set). On a [Vercel server build](/docs/deployment#server-rendering), a request for a missing page that sends [`Accept: text/markdown`](/docs/configuration/ai#content-negotiation), or asks for a `.md` URL no page backs, gets that Markdown body with the `404` status instead of the HTML shell — so an agent never has to parse a page of chrome to learn where to go next.
 
 To replace it with your own, add a `pages/404.astro`. It owns the `/404` route the same way `pages/changelog.astro` takes over the changelog — your page wins and the default is dropped. Build it like any other custom page, in `PageLayout` or `RootLayout`:
 

package/docs/advanced/graphql.mdx

@@ -66,7 +66,7 @@ graphql: {
 }
 ```
 
-Each source takes the same per-source controls as the [OpenAPI block](/docs/advanced/api-reference): `includeInSearch`, `includeInLlms`, and `noindex`.
+Each source takes the same [per-source controls](/docs/advanced/api-reference#per-source-indexing) as the OpenAPI block: `includeInSearch`, `includeInLlms`, `noindex`, and `seoDescriptionSuffix` (here the generated sentence names the query, mutation, or type — "Reference for the `pets` query in the GraphQL API.").
 
 ## Try it playground
 

package/docs/configuration/ai.mdx

@@ -81,6 +81,8 @@ The `.md` variant _downlevels_ components to plain Markdown for consumers that c
 
 Agents don't need to know the `.md` convention: requesting a page's own URL with an [`Accept: text/markdown`](https://acceptmarkdown.com) header serves the Markdown variant at the same address, with `Vary: Accept` so caches keep the two apart. The dev server honors the header out of the box, and a [Vercel or Cloudflare server build](/docs/deployment#server-rendering) wires the same negotiation into the deploy automatically — routing rules on Vercel, a generated Worker on Cloudflare — no configuration needed. The homepage always negotiates, even when it's a custom landing page rather than a content page: its Markdown mirror falls back to the [`llms.txt`](#llmstxt) index, so an agent asking the site root for Markdown gets the machine-readable map of the site. Markdown responses also carry an `x-markdown-tokens` header — an estimated token count (~4 characters per token), following the convention of [Cloudflare's Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) — on every surface where Blume controls response headers: the dev server, server-rendered responses, and the negotiated homepage on Vercel and Cloudflare. Other deploy targets serve prerendered pages from a static layer with no request-time hook, so agents there fetch the `.md` URL directly; the [agent readability manifest](#agent-readability) advertises `contentNegotiation` only on deployments that honor the header.
 
+Missing pages negotiate too. Every build emits a Markdown [404 page](/docs/advanced/custom-pages#404-page) at `/404.md` — the not-found message followed by recovery links to every top-level section, the sitemap, and `llms.txt` — and on Vercel a request for a nonexistent URL that prefers Markdown, or any `.md` URL with no page behind it, gets that body with a real `404` status rather than the HTML shell.
+
 ### Custom component serializers
 
 Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes, with the page's `frontmatter` in scope), its `children` (already downleveled to Markdown), and the page's `frontmatter` data, and returns the replacement — or `null` to leave the JSX as-is:
@@ -109,6 +111,8 @@ Serializers live in `blume.config.ts`, not `components.tsx`: the config file is
 
 Every page carries a **Copy as Markdown** action — in the [page actions](/docs/content/navigation#page-actions) beneath the table of contents — that copies the page's raw Markdown to the clipboard. It's the same source served at the [`.md` URL](#raw-markdown) above, ready to paste into an LLM, an issue, or your notes. It's available on every page, in dev and production, with no configuration.
 
+Where the Clipboard API is unavailable or the browser denies it — in-app browsers, WebViews, insecure origins — the action falls back to the legacy copy command, and if nothing lands on the clipboard the button reports **Copy failed** (localized via `actions.copyFailed`) rather than staying silent. The same fallback backs every copy button Blume renders.
+
 ## Open in chat
 
 The **Open in chat** action opens the current page in an AI assistant — v0, ChatGPT, Claude, T3 Chat, Scira, or Cursor — pre-filled with a prompt that points it at the page's raw Markdown so it can answer questions about what you're reading:

package/docs/configuration/seo.mdx

@@ -125,7 +125,7 @@ seo: {
 }
 ```
 
-By default, each card is derived from your content and theme — the **page title** as the headline, your **site title** as the eyebrow, and your theme **accent** for the mark. Images are served at `/og/<slug>.png`, mirroring each route, and are prerendered as static files even in server mode:
+By default, each card is derived from your content and theme — the **page title** as the headline, the **page description** as the subtitle (the same text as its `og:description`, so `seo.description` wins over `description`), your **site title** as the eyebrow, and your theme **accent** for the mark. Images are served at `/og/<slug>.png`, mirroring each route, and are prerendered as static files even in server mode:
 
 | Page route          | Image URL                  |
 | ------------------- | -------------------------- |
@@ -151,13 +151,13 @@ Emoji in a page title or site title render as [Twemoji](https://github.com/jdeck
 
 ### Show, hide, or override card layers
 
-Beyond the headline, the card carries three optional layers: the **brand mark** in the top-left (your logo, or an accent tile with the site title's initial), the **subtitle** under the headline (your site `description`), and a **footer** with your repo slug (from `github`) and the site's URL — the deployment site's host plus [`deployment.base`](/docs/deployment#subpath-deploys), so a GitHub Pages project site reads `user.github.io/repo`. Override any of them with a string of your own, or hide one with `false`:
+Beyond the headline, the card carries three optional layers: the **brand mark** in the top-left (your logo, or an accent tile with the site title's initial), the **subtitle** under the headline (the page `description`, or your site `description` for pages without one), and a **footer** with your repo slug (from `github`) and the site's URL — the deployment site's host plus [`deployment.base`](/docs/deployment#subpath-deploys), so a GitHub Pages project site reads `user.github.io/repo`. Override any of them with a string of your own, or hide one with `false`:
 
 ```ts blume.config.ts lineNumbers
 seo: {
   og: {
     site: "docs.acme.com", // footer URL text, or false to hide it
-    description: false, // hide the subtitle; a string overrides it
+    description: false, // hide the subtitle on every card; a string replaces the site fallback
     logo: false, // no brand mark at all — not even the initial tile
   },
 }

package/docs/configuration/theming.mdx

@@ -206,6 +206,12 @@ Drop a `theme.css` in your project root to override any design token. It's the l
 
 Set a token under `:root` for light mode and under `:root[data-theme="dark"]` for dark mode. Color tokens have distinct built-in dark values declared at the dark selector's higher specificity, so a `:root`-only override of `--blume-accent`, `--blume-background`, and friends applies to light mode only — declare the dark block too when both modes should change.
 
+`theme.css` is inlined into the site's Tailwind entry, so Tailwind directives work in it too. The one to know for a monorepo is `@source`: Blume scans your project for utility classes, and a page that imports components from a sibling workspace package needs that package scanned as well. Point at it relative to `theme.css` — the standard Tailwind rule — and Blume carries the path into the generated sheet:
+
+```css theme.css lineNumbers
+@source "../../packages/ui/src";
+```
+
 ### Design tokens
 
 | Token                       | Controls                                  |

package/docs/content/components.mdx

@@ -567,7 +567,7 @@ The card reads the instance from [`github.host`](/docs/configuration#github-ente
 
 `Component` renders an example file from your project's `examples/` directory as a live preview alongside its highlighted source, in tabs. Point it at a file with `path` — its location under `examples/`, without the extension (so `examples/counter.tsx` is `path="counter"`). React, Vue, Svelte, and Astro examples are all supported; framework examples hydrate, Astro ones render statically. It keeps the preview and the code in sync from a single file.
 
-The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your example files and anything they import), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live. The pane sizes itself to the rendered example — and keeps tracking it if the example grows or shrinks after load — with the Preview and Code tabs sharing one height so toggling them never shifts the page.
+The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your project and your examples directory), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live. The pane sizes itself to the rendered example — and keeps tracking it if the example grows or shrinks after load — with the Preview and Code tabs sharing one height so toggling them never shifts the page.
 
 To style previews with your own design system — say, shadcn variables — point `examples.css` at a stylesheet. It's injected into every preview frame after Blume's defaults, so your tokens win. Don't `@import "tailwindcss"` in it; the frame already provides Tailwind. Both `.dark` and `[data-theme="dark"]` work for dark-mode overrides:
 
@@ -623,6 +623,13 @@ export default defineConfig({
 <Component path="file-list/examples/basic" />
 ```
 
+In a monorepo, the components your examples import usually live in a sibling workspace package. Tailwind's `@source` scans files, not imports: Blume scans your project and the `examples` directory (wherever `source` points, even outside the project), so a class used only inside that sibling package isn't generated until you add the package to the scan. Do that with an `@source` directive in `examples.css` (for the preview frames) or `theme.css` (for the site), written relative to the file it sits in — the standard Tailwind rule — and Blume carries it into the generated sheet:
+
+```css
+/* examples/theme.css */
+@source "../../../packages/ui/src";
+```
+
 <Component path="counter" />
 
 ```astro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -66,107 +66,107 @@
     "typecheck": "tsgo --noEmit && tsgo -p test/tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@astrojs/check": "^0.9.0",
-    "@astrojs/markdown-satteri": "^0.3.2",
-    "@astrojs/mdx": "^7.0.0",
-    "@astrojs/node": "^11.0.0",
-    "@astrojs/react": "^6.0.0",
-    "@astrojs/vercel": "^11.0.3",
+    "@astrojs/check": "^0.9.10",
+    "@astrojs/markdown-satteri": "^0.4.0",
+    "@astrojs/mdx": "^8.0.0",
+    "@astrojs/node": "^11.1.5",
+    "@astrojs/react": "^6.0.5",
+    "@astrojs/vercel": "^11.0.10",
     "@asyncapi/converter": "^2.0.2",
     "@clack/prompts": "^1.7.0",
-    "@iconify-json/lucide": "^1.2.115",
+    "@iconify-json/lucide": "^1.2.129",
     "@iconify/types": "^2.0.0",
-    "@iconify/utils": "^3.1.3",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@iconify/utils": "^3.1.5",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@orama/orama": "^3.1.18",
-    "@pierre/diffs": "^1.2.11",
-    "@scalar/astro": "^0.4.5",
+    "@pierre/diffs": "^1.4.1",
+    "@scalar/astro": "^0.4.17",
     "@scalar/openapi-parser": "^0.29.0",
-    "@scalar/openapi-types": "^0.9.1",
-    "@shikijs/transformers": "^4.2.0",
-    "@shikijs/twoslash": "^4.2.0",
+    "@scalar/openapi-types": "^0.9.5",
+    "@shikijs/transformers": "^4.4.3",
+    "@shikijs/twoslash": "^4.4.3",
     "@tailwindcss/typography": "^0.5.20",
-    "@tailwindcss/vite": "^4",
+    "@tailwindcss/vite": "^4.3.3",
     "@types/mdast": "^4.0.4",
     "@vercel/analytics": "^2.0.1",
-    "ai": "^7.0.42",
-    "astro": "^7.2.3",
+    "ai": "^7.0.93",
+    "astro": "^7.3.1",
     "babel-plugin-react-compiler": "^1.0.0",
     "chokidar": "^5.0.0",
-    "citty": "^0.1.6",
-    "consola": "^3.4.0",
+    "citty": "^0.2.2",
+    "consola": "^3.4.2",
     "cross-spawn": "^7.0.6",
-    "dompurify": "^3.4.13",
+    "dompurify": "^3.4.14",
     "dotenv": "^17.4.2",
     "epub-gen-memory": "^1.1.2",
-    "fast-xml-parser": "^5.10.1",
+    "fast-xml-parser": "^5.11.1",
     "github-slugger": "^2.0.0",
     "graphql": "^17.0.2",
     "gray-matter": "^4.0.3",
     "html-escaper": "^3.0.3",
     "image-size": "^2.0.2",
-    "jiti": "^2.4.0",
+    "jiti": "^2.7.0",
     "js-yaml": "^5.4.1",
-    "katex": "^0.18.1",
+    "katex": "^0.18.6",
     "markdown-table": "^3.0.4",
-    "marked": "^18.0.5",
+    "marked": "^18.0.11",
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-gfm": "^3.1.0",
     "mdast-util-to-string": "^4.0.0",
     "medium-zoom": "^1.1.0",
-    "mermaid": "^11.16.1",
+    "mermaid": "^11.17.2",
     "micromark-extension-gfm": "^3.0.0",
     "nanotar": "^0.3.0",
-    "node-html-parser": "^9.0.0",
-    "openapi-sampler": "^1.7.4",
-    "p-limit": "^7.3.1",
-    "p-map": "^7.0.6",
-    "p-retry": "^8.0.0",
+    "node-html-parser": "^9.0.3",
+    "openapi-sampler": "^1.7.5",
+    "p-limit": "^7.3.2",
+    "p-map": "^7.0.7",
+    "p-retry": "^8.0.1",
     "package-manager-detector": "^1.8.0",
-    "pagefind": "^1.3.0",
-    "pathe": "^2.0.0",
+    "pagefind": "^1.5.2",
+    "pathe": "^2.0.3",
     "perfect-debounce": "^2.1.0",
-    "picomatch": "^4.0.5",
+    "picomatch": "^4.0.7",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "robots-parser": "^3.0.1",
     "satteri": "^0.10.5",
     "semver": "^7.8.5",
-    "sharp": "^0.35.3",
-    "shiki": "^4.2.0",
+    "sharp": "^0.35.4",
+    "shiki": "^4.4.3",
     "simple-icons": "^16.29.0",
-    "string-width": "^8.1.0",
+    "string-width": "^8.2.2",
     "sucrase": "^3.35.1",
     "tailwindcss": "^4.3.3",
-    "takumi-js": "^2.2.1",
-    "tinyglobby": "^0.2.10",
+    "takumi-js": "^2.13.6",
+    "tinyglobby": "^0.2.17",
     "twoslash": "^0.3.9",
     "typescript": "^6.0.3",
     "ufo": "^1.6.4",
-    "undici": "^8.9.0",
+    "undici": "^8.10.2",
     "write-file-atomic": "^8.0.0",
-    "zod": "^4.3.6"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@ai-sdk/openai-compatible": "^3.0.0",
-    "@mixedbread/sdk": "^0.76.0",
+    "@ai-sdk/openai-compatible": "^3.0.44",
+    "@mixedbread/sdk": "^0.77.0",
     "@notionhq/client": "^5.26.0",
     "@openrouter/ai-sdk-provider": "^3.0.0",
-    "@oramacloud/client": "^2.1.0",
-    "@sanity/client": "^8.4.0",
+    "@oramacloud/client": "^2.1.4",
+    "@sanity/client": "^8.5.0",
     "@types/cross-spawn": "^6.0.6",
     "@types/html-escaper": "^3.0.4",
-    "@types/node": "^22.10.0",
+    "@types/node": "^22.20.1",
     "@types/picomatch": "^4.0.3",
     "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.0.0",
+    "@types/react-dom": "^19.2.7",
     "@types/semver": "^7.8.0",
     "@types/write-file-atomic": "^4.0.3",
-    "@typescript/native-preview": "^7.0.0-dev.20260626.1",
-    "algoliasearch": "^5.55.0",
-    "bun-types": "^1.3.14",
-    "flexsearch": "^0.8.0",
-    "typesense": "^3.0.0"
+    "@typescript/native-preview": "^7.0.0-dev.20260707.2",
+    "algoliasearch": "^5.57.0",
+    "bun-types": "^1.4.2",
+    "flexsearch": "^0.8.212",
+    "typesense": "^3.0.6"
   },
   "peerDependencies": {
     "@ai-sdk/openai-compatible": "^3.0.0",
@@ -174,7 +174,7 @@
     "@astrojs/netlify": "^8.0.0",
     "@astrojs/svelte": "^9.0.0",
     "@astrojs/vue": "^7.0.0",
-    "@mixedbread/sdk": "^0.76.0",
+    "@mixedbread/sdk": "^0.77.0",
     "@notionhq/client": "^5.0.0",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "@oramacloud/client": "^2.1.0",

package/src/astro/examples.ts

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 
 import pMap from "p-map";
-import { join, relative } from "pathe";
+import { isAbsolute, join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
 import type { ExampleLookup } from "../core/types.ts";
@@ -28,6 +28,11 @@ export interface ExampleSpec {
 }
 
 export interface ExampleDiscovery {
+  /**
+   * Absolute directory the examples were discovered under: the configured
+   * `examples.source` (or a glob's static prefix) resolved against the root.
+   */
+  dir: string;
   examples: ExampleSpec[];
   warnings: string[];
 }
@@ -56,6 +61,28 @@ const DEFAULT_EXAMPLE_GLOB = "**/*.{astro,jsx,svelte,tsx,vue}";
 /** Ceiling on concurrent example-file reads; unbounded fan-out risks EMFILE. */
 const READ_CONCURRENCY = 16;
 
+/**
+ * Files the preview-frame Tailwind entry scans for utility classes, appended
+ * to each directory from `exampleScanRoots`.
+ */
+export const EXAMPLE_SCAN_GLOB = "**/*.{astro,jsx,svelte,ts,tsx,vue}";
+
+/**
+ * Directories the `<Component />` preview sheet scans for utility classes:
+ * the project root, plus the examples directory when it lives outside the
+ * root (a sibling workspace package, say). Tailwind's `@source` is a file
+ * glob, not an import graph, so an out-of-root examples directory would
+ * otherwise contribute no utilities and previews would render half-styled.
+ */
+export const exampleScanRoots = (
+  root: string,
+  examplesDir: string
+): string[] => {
+  const path = relative(root, examplesDir);
+  const outside = path.startsWith("..") || isAbsolute(path);
+  return outside ? [root, examplesDir] : [root];
+};
+
 // Glob magic that turns `examples` from a plain directory into a pattern. `()`,
 // `@`, and `+` are excluded so literal path segments (npm scopes, parens) keep
 // resolving as directories; the extglob leads `*?!` still trigger here.
@@ -153,7 +180,7 @@ export const discoverExamples = async (
     collectExample(file, sources[index] ?? "");
   }
 
-  return { examples, warnings };
+  return { dir, examples, warnings };
 };
 
 /**