@vibesdotdev/docs 0.0.0-stage → 1.0.0-rc.2

package/dist/svelte/tool-widgets/RunbookToolCard.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	/**
+	 * First-party widget for `runbook`: runbook name and ordered steps.
+	 */
+	import {
+		ToolCard,
+		ToolCardBody,
+		type ToolWidgetProps
+	} from '@vibesdotdev/kit/components/tool-widgets';
+	import { runbookToolCardModel } from './models.js';
+
+	let { tool, compact = false }: ToolWidgetProps = $props();
+
+	const model = $derived(runbookToolCardModel(tool));
+</script>
+
+<ToolCard {tool} {compact} title={model.name || 'Runbook'} icon="lucide:list-checks">
+	<ToolCardBody {compact}>
+		{#if model.steps.length}
+			<ol class="list-inside list-decimal text-muted-foreground">
+				{#each model.steps as step (step)}
+					<li class="text-foreground">{step}</li>
+				{/each}
+			</ol>
+		{:else if !tool.error}
+			<p class="text-muted-foreground italic">No steps returned.</p>
+		{/if}
+	</ToolCardBody>
+</ToolCard>

package/dist/svelte/tool-widgets/RunbookToolCard.svelte.d.ts

@@ -0,0 +1,8 @@
+/**
+     * First-party widget for `runbook`: runbook name and ordered steps.
+     */
+import { type ToolWidgetProps } from '@vibesdotdev/kit/components/tool-widgets';
+declare const RunbookToolCard: import("svelte").Component<ToolWidgetProps, {}, "">;
+type RunbookToolCard = ReturnType<typeof RunbookToolCard>;
+export default RunbookToolCard;
+//# sourceMappingURL=RunbookToolCard.svelte.d.ts.map

package/dist/svelte/tool-widgets/RunbookToolCard.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunbookToolCard.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/tool-widgets/RunbookToolCard.svelte.ts"],"names":[],"mappings":"AAGA;;OAEI;AACJ,OAAO,EAGL,KAAK,eAAe,EACpB,MAAM,0CAA0C,CAAC;AA6BnD,QAAA,MAAM,eAAe,qDAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/dist/svelte/tool-widgets/index.d.ts

@@ -0,0 +1,7 @@
+export { default as DocsToolCard } from './DocsToolCard.svelte';
+export { default as DocumentReadToolCard } from './DocumentReadToolCard.svelte';
+export { default as RunbookToolCard } from './RunbookToolCard.svelte';
+export { default as PresentationsToolCard } from './PresentationsToolCard.svelte';
+export { DOCS_OWNED_TOOL_IDS, docsToolCardModel, documentReadToolCardModel, runbookToolCardModel, presentationsToolCardModel } from './models.ts';
+export type { DocsOwnedToolId, DocsHit, DocsToolCardModel, DocumentReadToolCardModel, RunbookToolCardModel, PresentationsToolCardModel } from './models.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/svelte/tool-widgets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/svelte/tool-widgets/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAClF,OAAO,EACN,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,0BAA0B,EAC1B,MAAM,aAAa,CAAC;AACrB,YAAY,EACX,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,0BAA0B,EAC1B,MAAM,aAAa,CAAC"}

package/dist/svelte/tool-widgets/index.js

@@ -0,0 +1,5 @@
+export { default as DocsToolCard } from './DocsToolCard.svelte';
+export { default as DocumentReadToolCard } from './DocumentReadToolCard.svelte';
+export { default as RunbookToolCard } from './RunbookToolCard.svelte';
+export { default as PresentationsToolCard } from './PresentationsToolCard.svelte';
+export { DOCS_OWNED_TOOL_IDS, docsToolCardModel, documentReadToolCardModel, runbookToolCardModel, presentationsToolCardModel } from "./models.js";

package/dist/svelte/tool-widgets/models.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Designed fields for docs-owned Kit tool cards.
+ *
+ * `docs` → query / hits
+ * `document.read` → path / excerpt
+ * `runbook` → name / steps
+ * `presentations` → title
+ */
+export declare const DOCS_OWNED_TOOL_IDS: readonly ["docs", "document.read", "runbook", "presentations"];
+export type DocsOwnedToolId = (typeof DOCS_OWNED_TOOL_IDS)[number];
+export interface DocsHit {
+    id: string;
+    title: string;
+    summary: string;
+}
+export interface DocsToolCardModel {
+    query: string;
+    hits: DocsHit[];
+}
+export declare function docsToolCardModel(tool: {
+    input?: unknown;
+    output?: unknown;
+}): DocsToolCardModel;
+export interface DocumentReadToolCardModel {
+    path: string;
+    excerpt: string;
+}
+export declare function documentReadToolCardModel(tool: {
+    input?: unknown;
+    output?: unknown;
+}): DocumentReadToolCardModel;
+export interface RunbookToolCardModel {
+    name: string;
+    steps: string[];
+}
+export declare function runbookToolCardModel(tool: {
+    input?: unknown;
+    output?: unknown;
+}): RunbookToolCardModel;
+export interface PresentationsToolCardModel {
+    title: string;
+}
+export declare function presentationsToolCardModel(tool: {
+    input?: unknown;
+    output?: unknown;
+}): PresentationsToolCardModel;
+//# sourceMappingURL=models.d.ts.map

package/dist/svelte/tool-widgets/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../src/svelte/tool-widgets/models.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,eAAO,MAAM,mBAAmB,gEAAiE,CAAC;AAElG,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAoBnE,MAAM,WAAW,OAAO;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,EAAE,CAAC;CAChB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,iBAAiB,CA2BhG;AAED,MAAM,WAAW,yBAAyB;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC/C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,yBAAyB,CAqB5B;AAED,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,oBAAoB,CA+BvB;AAED,MAAM,WAAW,0BAA0B;IAC1C,KAAK,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,0BAA0B,CAQ7B"}

package/dist/svelte/tool-widgets/models.js

@@ -0,0 +1,112 @@
+/**
+ * Designed fields for docs-owned Kit tool cards.
+ *
+ * `docs` → query / hits
+ * `document.read` → path / excerpt
+ * `runbook` → name / steps
+ * `presentations` → title
+ */
+import * as z from 'zod/v4';
+import { JsonObjectSchema } from '@vibesdotdev/kernel/schemas/json';
+export const DOCS_OWNED_TOOL_IDS = ['docs', 'document.read', 'runbook', 'presentations'];
+const EXCERPT_MAX = 280;
+const LIST_MAX = 8;
+function rec(value) {
+    const parsed = JsonObjectSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+function str(value) {
+    const parsed = z.string().safeParse(value);
+    return parsed.success ? parsed.data.trim() : '';
+}
+function truncate(value, max = EXCERPT_MAX) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max).trimEnd()}…`;
+}
+export function docsToolCardModel(tool) {
+    const input = rec(tool.input);
+    const output = rec(tool.output);
+    const query = str(input?.query) || str(input?.topicId) || str(input?.tag);
+    const hits = [];
+    const topics = output?.topics;
+    if (Array.isArray(topics)) {
+        for (const topic of topics) {
+            const row = rec(topic);
+            const id = str(row?.id);
+            const title = str(row?.title) || id;
+            if (!id && !title)
+                continue;
+            hits.push({ id: id || title, title, summary: str(row?.summary) });
+        }
+    }
+    const topic = rec(output?.topic);
+    if (topic) {
+        const id = str(topic.id);
+        const title = str(topic.title) || id;
+        if (id || title) {
+            hits.push({ id: id || title, title, summary: str(topic.summary) });
+        }
+    }
+    return { query, hits: hits.slice(0, LIST_MAX) };
+}
+export function documentReadToolCardModel(tool) {
+    const input = rec(tool.input);
+    const output = rec(tool.output);
+    const ref = rec(input?.ref);
+    const path = str(ref?.path) || str(ref?.url) || str(ref?.documentId);
+    const pages = output?.pages;
+    if (Array.isArray(pages)) {
+        for (const page of pages) {
+            const row = rec(page);
+            const text = str(row?.text) || str(row?.message);
+            if (text)
+                return { path, excerpt: truncate(text) };
+        }
+    }
+    const rows = output?.rows;
+    if (Array.isArray(rows) && rows.length > 0) {
+        return { path, excerpt: `${rows.length} structured row${rows.length === 1 ? '' : 's'}` };
+    }
+    return { path, excerpt: '' };
+}
+export function runbookToolCardModel(tool) {
+    const input = rec(tool.input);
+    const output = rec(tool.output);
+    const runbook = rec(output?.runbook);
+    const steps = [];
+    const phases = runbook?.phases;
+    if (Array.isArray(phases)) {
+        for (const phase of phases) {
+            const phaseRow = rec(phase);
+            const phaseSteps = phaseRow?.steps;
+            if (!Array.isArray(phaseSteps))
+                continue;
+            for (const step of phaseSteps) {
+                const stepRow = rec(step);
+                const label = str(stepRow?.comment) || str(stepRow?.tool);
+                if (label)
+                    steps.push(label);
+            }
+        }
+    }
+    const listed = output?.runbooks;
+    if (Array.isArray(listed)) {
+        for (const entry of listed) {
+            const row = rec(entry);
+            const label = str(row?.name) || str(row?.id);
+            if (label)
+                steps.push(label);
+        }
+    }
+    const name = str(runbook?.name) || str(input?.id) || (listed ? 'Runbooks' : '');
+    return { name, steps: [...new Set(steps)].slice(0, LIST_MAX) };
+}
+export function presentationsToolCardModel(tool) {
+    const input = rec(tool.input);
+    const output = rec(tool.output);
+    const request = rec(output?.request);
+    const target = rec(request?.target) ?? rec(input?.target);
+    const title = str(target?.title) || str(request?.message) || str(input?.message) || str(input?.action);
+    return { title };
+}

package/dist/svelte/ui/DocViewer.svelte

@@ -0,0 +1,122 @@
+<script lang="ts">
+	/**
+	 * <DocViewer /> — render the body of a docs topic.
+	 *
+	 * Accepts either an explicit `doc` prop or — when omitted — falls back to
+	 * `docsState.activeDoc`. Markdown bodies are parsed and rendered via the
+	 * existing `<MarkdownView />`. Non-markdown bodies render a short
+	 * placeholder + "Open in docs" link, matching the `<HelpDialog />` policy.
+	 */
+	import type { DocsTopicDescriptor } from '@vibesdotdev/docs/schemas';
+	import { parseMarkdown, type ParsedTopic } from '@vibesdotdev/docs/render';
+	import { getRuntimeSvelteContext } from '@vibesdotdev/surface-sveltekit/svelte';
+	import { docsTopicHref, resolveDocsServiceOrigin } from '../docs-origin.js';
+	import { getDocsState } from '../state.svelte.js';
+ const docsState = getDocsState();
+	import MarkdownView from './markdown/MarkdownView.svelte';
+
+	interface Props {
+		doc?: DocsTopicDescriptor | null;
+		docsOrigin?: string;
+	}
+
+	const { doc: docProp, docsOrigin }: Props = $props();
+	const doc = $derived(docProp ?? docsState.activeDoc);
+	const runtimeStore = getRuntimeSvelteContext();
+	let catalogOrigin = $state<string | null>(null);
+
+	$effect(() => {
+		const explicit = docsOrigin;
+		if (explicit) {
+			catalogOrigin = null;
+			return;
+		}
+		const runtime = runtimeStore.runtime;
+		if (!runtime) {
+			void runtimeStore.load();
+			return;
+		}
+		let cancelled = false;
+		void resolveDocsServiceOrigin(runtime).then((origin) => {
+			if (!cancelled) catalogOrigin = origin;
+		});
+		return () => {
+			cancelled = true;
+		};
+	});
+
+	const parsed = $derived.by<ParsedTopic | null>(() => {
+		if (!doc) return null;
+		if (doc.body.type !== 'markdown') return null;
+		if (doc.body.sourceType !== 'raw') return null;
+		return parseMarkdown(doc.body.source);
+	});
+
+	const externalUrl = $derived.by(() => {
+		if (!doc) return '';
+		return docsTopicHref(docsOrigin ?? catalogOrigin, doc.id);
+	});
+</script>
+
+{#if !doc}
+	<p class="doc-viewer__placeholder">Select a topic.</p>
+{:else}
+	<article class="doc-viewer">
+		<header class="doc-viewer__header">
+			<h2 class="doc-viewer__title">{doc.title}</h2>
+			{#if doc.summary}
+				<p class="doc-viewer__summary">{doc.summary}</p>
+			{/if}
+		</header>
+		<div class="doc-viewer__body">
+			{#if parsed}
+				<MarkdownView {parsed} />
+			{:else}
+				<p class="doc-viewer__placeholder">This topic is best viewed in the docs app.</p>
+			{/if}
+			<p class="doc-viewer__more">
+				<a href={externalUrl} target="_blank" rel="noopener noreferrer"> Open in docs → </a>
+			</p>
+		</div>
+	</article>
+{/if}
+
+<style>
+	.doc-viewer {
+		display: flex;
+		flex-direction: column;
+		gap: 0.75rem;
+	}
+	.doc-viewer__header {
+		display: flex;
+		flex-direction: column;
+		gap: 0.25rem;
+	}
+	.doc-viewer__title {
+		margin: 0;
+		font-size: 1.125rem;
+		font-weight: 600;
+	}
+	.doc-viewer__summary {
+		margin: 0;
+		font-size: 0.875rem;
+		color: var(--color-muted-foreground, hsl(220 13% 26%));
+	}
+	.doc-viewer__body {
+		display: flex;
+		flex-direction: column;
+		gap: 0.875rem;
+	}
+	.doc-viewer__placeholder {
+		margin: 0;
+		font-size: 0.875rem;
+		color: var(--color-muted-foreground, hsl(220 13% 26%));
+	}
+	.doc-viewer__more {
+		margin: 0;
+		font-size: 0.8125rem;
+	}
+	.doc-viewer__more a {
+		color: var(--color-link, hsl(217 91% 60%));
+	}
+</style>

package/dist/svelte/ui/DocViewer.svelte.d.ts

@@ -0,0 +1,17 @@
+/**
+     * <DocViewer /> — render the body of a docs topic.
+     *
+     * Accepts either an explicit `doc` prop or — when omitted — falls back to
+     * `docsState.activeDoc`. Markdown bodies are parsed and rendered via the
+     * existing `<MarkdownView />`. Non-markdown bodies render a short
+     * placeholder + "Open in docs" link, matching the `<HelpDialog />` policy.
+     */
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs/schemas';
+interface Props {
+    doc?: DocsTopicDescriptor | null;
+    docsOrigin?: string;
+}
+declare const DocViewer: import("svelte").Component<Props, {}, "">;
+type DocViewer = ReturnType<typeof DocViewer>;
+export default DocViewer;
+//# sourceMappingURL=DocViewer.svelte.d.ts.map

package/dist/svelte/ui/DocViewer.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocViewer.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/ui/DocViewer.svelte.ts"],"names":[],"mappings":"AAGA;;;;;;;OAOI;AACJ,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAQpE,UAAU,KAAK;IACd,GAAG,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AA6EF,QAAA,MAAM,SAAS,2CAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/svelte/ui/DocsLoader.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+	/**
+	 * <DocsLoader /> — non-visual initializer for `docsState`.
+	 *
+	 * Wrap search/viewer children, or establish getDocsState() in a parent
+	 * layout when the loader and consumers are siblings.
+	 *
+	 * Optionally accepts `initialDocs` / `initialActiveDocId` to seed from a
+	 * SvelteKit `+layout.server.ts` payload, avoiding a redundant runtime list
+	 * call on first render.
+	 */
+	import type { DocsTopicDescriptor } from '@vibesdotdev/docs/schemas';
+	import { getRuntimeSvelteContext } from '@vibesdotdev/surface-sveltekit/svelte';
+	import { getDocsState } from '../state.svelte.js';
+ const docsState = getDocsState();
+
+	import { untrack, type Snippet } from 'svelte';
+
+	interface Props {
+  children?: Snippet;
+		initialDocs?: readonly DocsTopicDescriptor[];
+		initialActiveDocId?: string | null;
+	}
+
+	const { initialDocs, initialActiveDocId, children }: Props = $props();
+
+	const runtimeStore = getRuntimeSvelteContext();
+
+ $effect(() => {
+  const options = { runtimeStore, initialDocs, initialActiveDocId: initialActiveDocId ?? null };
+  // Observe host replacement, while keeping projection reads out of this effect.
+  void runtimeStore.runtime;
+  untrack(() => { void docsState.init(options); });
+ });
+</script>
+
+{@render children?.()}

package/dist/svelte/ui/DocsLoader.svelte.d.ts

@@ -0,0 +1,21 @@
+/**
+     * <DocsLoader /> — non-visual initializer for `docsState`.
+     *
+     * Wrap search/viewer children, or establish getDocsState() in a parent
+     * layout when the loader and consumers are siblings.
+     *
+     * Optionally accepts `initialDocs` / `initialActiveDocId` to seed from a
+     * SvelteKit `+layout.server.ts` payload, avoiding a redundant runtime list
+     * call on first render.
+     */
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs/schemas';
+import { type Snippet } from 'svelte';
+interface Props {
+    children?: Snippet;
+    initialDocs?: readonly DocsTopicDescriptor[];
+    initialActiveDocId?: string | null;
+}
+declare const DocsLoader: import("svelte").Component<Props, {}, "">;
+type DocsLoader = ReturnType<typeof DocsLoader>;
+export default DocsLoader;
+//# sourceMappingURL=DocsLoader.svelte.d.ts.map

package/dist/svelte/ui/DocsLoader.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocsLoader.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/ui/DocsLoader.svelte.ts"],"names":[],"mappings":"AAGA;;;;;;;;;OASI;AACJ,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAIrE,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAG9C,UAAU,KAAK;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC7C,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AA2BF,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/svelte/ui/DocsSearch.svelte

@@ -0,0 +1,129 @@
+<script lang="ts">
+	/**
+	 * <DocsSearch /> — search input + filtered topic list bound to `docsState`.
+	 *
+	 * Renders nothing until the loader has run. Clicking an entry calls
+	 * `onSelect` (when provided) or sets `docsState.activeDocId`.
+	 */
+	import type { DocsTopicDescriptor } from '@vibesdotdev/docs/schemas';
+	import { getDocsState } from '../state.svelte.js';
+ const docsState = getDocsState();
+
+	interface Props {
+		placeholder?: string;
+		onSelect?: (doc: DocsTopicDescriptor) => void;
+	}
+
+	const { placeholder = 'Search docs…', onSelect }: Props = $props();
+</script>
+
+<div class="docs-search">
+	<input
+		type="search"
+		class="docs-search__input"
+		{placeholder}
+		value={docsState.searchQuery}
+		oninput={(event) => docsState.setSearchQuery(event.currentTarget.value)}
+	/>
+
+	{#if docsState.loading && !docsState.initialized}
+		<p class="docs-search__status">Loading docs…</p>
+	{:else if docsState.error}
+		<p class="docs-search__status docs-search__status--error">
+			Failed to load docs: {docsState.error}
+		</p>
+	{:else if docsState.results.length === 0}
+		<p class="docs-search__status">
+			{docsState.searchQuery ? 'No matching topics.' : 'No docs registered.'}
+		</p>
+	{:else}
+		<ul class="docs-search__list">
+			{#each docsState.results as doc (doc.id)}
+				<li>
+					<button
+						type="button"
+						class="docs-search__entry"
+						class:docs-search__entry--active={doc.id === docsState.activeDocId}
+						onclick={() => {
+							if (onSelect) onSelect(doc);
+							else docsState.setActiveDoc(doc.id);
+						}}
+					>
+						<span class="docs-search__title">{doc.title}</span>
+						{#if doc.summary}
+							<span class="docs-search__summary">{doc.summary}</span>
+						{/if}
+					</button>
+				</li>
+			{/each}
+		</ul>
+	{/if}
+</div>
+
+<style>
+	.docs-search {
+		display: flex;
+		flex-direction: column;
+		gap: 0.5rem;
+	}
+	.docs-search__input {
+		appearance: none;
+		font: inherit;
+		padding: 0.5rem 0.75rem;
+		border: 1px solid var(--color-border, hsl(0 0% 90%));
+		border-radius: 0.375rem;
+		background: var(--color-card, hsl(0 0% 100%));
+		color: var(--color-foreground, hsl(0 0% 7%));
+	}
+	.docs-search__input:focus {
+		outline: 2px solid var(--color-ring, hsl(217 91% 60%));
+		outline-offset: 1px;
+	}
+	.docs-search__status {
+		margin: 0;
+		font-size: 0.8125rem;
+		color: var(--color-muted-foreground, hsl(220 13% 26%));
+	}
+	.docs-search__status--error {
+		color: var(--color-destructive-foreground, hsl(0 84% 60%));
+	}
+	.docs-search__list {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		display: flex;
+		flex-direction: column;
+		gap: 0.125rem;
+		max-height: 24rem;
+		overflow: auto;
+	}
+	.docs-search__entry {
+		display: flex;
+		flex-direction: column;
+		align-items: flex-start;
+		gap: 0.125rem;
+		width: 100%;
+		text-align: left;
+		padding: 0.5rem 0.625rem;
+		border-radius: 0.375rem;
+		border: 1px solid transparent;
+		background: transparent;
+		color: inherit;
+		cursor: pointer;
+	}
+	.docs-search__entry:hover {
+		background: var(--color-muted, hsl(220 13% 95%));
+	}
+	.docs-search__entry--active {
+		background: var(--color-muted, hsl(220 13% 95%));
+		border-color: var(--color-border, hsl(0 0% 90%));
+	}
+	.docs-search__title {
+		font-weight: 600;
+		font-size: 0.875rem;
+	}
+	.docs-search__summary {
+		font-size: 0.75rem;
+		color: var(--color-muted-foreground, hsl(220 13% 26%));
+	}
+</style>

package/dist/svelte/ui/DocsSearch.svelte.d.ts

@@ -0,0 +1,15 @@
+/**
+     * <DocsSearch /> — search input + filtered topic list bound to `docsState`.
+     *
+     * Renders nothing until the loader has run. Clicking an entry calls
+     * `onSelect` (when provided) or sets `docsState.activeDocId`.
+     */
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs/schemas';
+interface Props {
+    placeholder?: string;
+    onSelect?: (doc: DocsTopicDescriptor) => void;
+}
+declare const DocsSearch: import("svelte").Component<Props, {}, "">;
+type DocsSearch = ReturnType<typeof DocsSearch>;
+export default DocsSearch;
+//# sourceMappingURL=DocsSearch.svelte.d.ts.map

package/dist/svelte/ui/DocsSearch.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocsSearch.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/ui/DocsSearch.svelte.ts"],"names":[],"mappings":"AAGA;;;;;OAKI;AACJ,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAIpE,UAAU,KAAK;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAC;CAC9C;AA+CF,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/svelte/ui/directives/Card.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+	import type { DirectiveNode } from '@vibesdotdev/docs';
+	import { parseMarkdown } from '@vibesdotdev/docs/render';
+	import MarkdownView from '../markdown/MarkdownView.svelte';
+	import { getDocsTopics } from '../../context.js';
+	import { rewriteTopicLinks } from '../../build/highlight.js';
+
+	interface Props {
+		node: DirectiveNode;
+	}
+	const { node }: Props = $props();
+
+	const title = $derived(node.attrs.title);
+	const topics = getDocsTopics();
+	const topicIds = new Set(topics.map((t) => t.id));
+	const parsed = $derived.by(() => {
+		const p = parseMarkdown(node.body.trim());
+		if (topicIds.size > 0) rewriteTopicLinks(p, topicIds);
+		return p;
+	});
+</script>
+
+<section class="card">
+	{#if title}
+		<h3 class="card__title">{title}</h3>
+	{/if}
+	<div class="card__body">
+		<MarkdownView {parsed} />
+	</div>
+</section>
+
+<style>
+	.card {
+		border: 1px solid var(--border, hsl(0 0% 90%));
+		border-radius: 0.75rem;
+		padding: 1rem 1.25rem;
+		background: var(--card, hsl(0 0% 99%));
+		margin: 1.25rem 0;
+	}
+	.card__title {
+		font-size: 0.9375rem;
+		font-weight: 600;
+		margin: 0 0 0.5rem;
+		color: var(--foreground);
+	}
+	/* Tighten the prose chrome inside cards — they shouldn't look like
+	   another full article. */
+	.card :global(.markdown-view) {
+		font-size: 0.875rem;
+	}
+	.card :global(.markdown-view > :first-child) {
+		margin-top: 0;
+	}
+	.card :global(.markdown-view > :last-child) {
+		margin-bottom: 0;
+	}
+	.card :global(.markdown-view ul),
+	.card :global(.markdown-view ol) {
+		margin: 0;
+	}
+</style>

package/dist/svelte/ui/directives/Card.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { DirectiveNode } from '@vibesdotdev/docs';
+interface Props {
+    node: DirectiveNode;
+}
+declare const Card: import("svelte").Component<Props, {}, "">;
+type Card = ReturnType<typeof Card>;
+export default Card;
+//# sourceMappingURL=Card.svelte.d.ts.map

package/dist/svelte/ui/directives/Card.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Card.svelte.d.ts","sourceRoot":"","sources":["../../../../src/svelte/ui/directives/Card.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOtD,UAAU,KAAK;IACd,IAAI,EAAE,aAAa,CAAC;CACpB;AAiCF,QAAA,MAAM,IAAI,2CAAwC,CAAC;AACnD,KAAK,IAAI,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;AACpC,eAAe,IAAI,CAAC"}