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

package/dist/svelte/build/topic-index.js

@@ -0,0 +1,247 @@
+import { parseMarkdown } from '@vibesdotdev/docs/render';
+/**
+ * Filter the descriptor set down to topics renderable as standalone web pages
+ * via the dynamic `[...slug]` route — `markdown`, `component`, and
+ * `descriptor-ref` bodies. Excludes `route` bodies (those have their own
+ * SvelteKit routes) and `openapi`/`graphql` (which route through dedicated
+ * explorer routes added in Tier 3/4).
+ */
+export function pageRenderableTopics(descriptors) {
+    return descriptors.filter((d) => {
+        if (d.enabled === false)
+            return false;
+        if (!d.surfaces.includes('web'))
+            return false;
+        switch (d.body.type) {
+            case 'markdown':
+            case 'component':
+            case 'descriptor-ref':
+                return true;
+            case 'route':
+            case 'openapi':
+            case 'graphql':
+                return false;
+        }
+    });
+}
+/**
+ * Build the prerender entries list for `+page.ts`'s `entries()` export.
+ * Returns `[{ slug: ['tools', 'list'] }, ...]` for each page-renderable topic.
+ *
+ * The slug is the topic id split on `.` so `tools.list` becomes
+ * `/tools/list` in the URL (SvelteKit `[...slug]` joins the array back).
+ * Topics with no `.` in the id become single-segment slugs like `['guide']`
+ * → `/guide`.
+ */
+export function topicEntries(descriptors) {
+    return pageRenderableTopics(descriptors).map((d) => ({
+        slug: idToSlug(d.id)
+    }));
+}
+/**
+ * Topic id → URL slug. `tools.list` → `tools/list`; `guide` → `guide`.
+ */
+export function idToSlug(id) {
+    return id.replaceAll('.', '/');
+}
+/**
+ * URL slug → topic id. Inverse of `idToSlug`. SvelteKit hands the dynamic
+ * route a `params.slug` string with `/` separators; we restore dots.
+ */
+export function slugToId(slug) {
+    return slug.replaceAll('/', '.');
+}
+/**
+ * Resolve + parse a topic for rendering. Returns the descriptor + parsed AST
+ * (markdown bodies only). Non-markdown bodies return `parsed: null` — the
+ * `<MarkdownView />` component skips the walk and the page's +page.svelte
+ * picks the appropriate branch (route navigation, component mount, etc.).
+ */
+export function indexedTopicFor(descriptors, id) {
+    const descriptor = descriptors.find((d) => d.id === id) ?? null;
+    if (!descriptor)
+        return null;
+    const body = descriptor.body;
+    if (body.type === 'markdown' && body.sourceType === 'raw') {
+        return { descriptor, parsed: parseMarkdown(body.source) };
+    }
+    return { descriptor, parsed: null };
+}
+export function inferTrackForParent(parent, id) {
+    const p = (parent ?? id ?? '').toLowerCase();
+    const root = p.split('.')[0];
+    if (root === 'getting-started' || root === 'tutorials' || root === 'guided-flows') {
+        return 'start-here';
+    }
+    if (root === 'ui' ||
+        root === 'kit' ||
+        root === 'charts' ||
+        root === 'chat' ||
+        root === 'app' ||
+        root === 'theme' ||
+        root === 'media') {
+        return 'framework-kit';
+    }
+    if (root === 'platform' ||
+        root === 'storage' ||
+        root === 'auth' ||
+        root === 'workers' ||
+        root === 'integrations' ||
+        root === 'cache' ||
+        root === 'secrets' ||
+        root === 'account' ||
+        root === 'forge' ||
+        root === 'notifications') {
+        return 'platform-cloud';
+    }
+    if (root === 'cli' ||
+        root === 'tools' ||
+        root === 'localdb' ||
+        root === 'session' ||
+        root === 'agents' ||
+        root === 'ai' ||
+        root === 'mcp' ||
+        root === 'knowledge' ||
+        root === 'workbench' ||
+        root === 'desktop' ||
+        root === 'vessel') {
+        return 'local-tooling';
+    }
+    if (root === 'api' || root === 'api-explorer' || root === 'packages' || root === 'runtime-client') {
+        return 'api-reference';
+    }
+    return 'internals';
+}
+/**
+ * Humanize a parent id (`runtime-client` → `Runtime Client`, `ai` → `Ai`,
+ * `ai.providers` → `Ai Providers`). Matches the layout's title casing so the
+ * synthesized section page header reads consistently with the sidebar group.
+ */
+function titleizeParent(id) {
+    return id.replace(/(^|\.|_|-)([a-z])/g, (_, sep, c) => {
+        const space = sep === '' ? '' : ' ';
+        return `${space}${c.toUpperCase()}`;
+    }).trim();
+}
+/**
+ * Return one entry per implicit section root. A "section root" is any
+ * `parent` value referenced by an enabled web-surface topic that does *not*
+ * itself have a matching topic descriptor. Children are sorted the same way
+ * as `buildSidebar`.
+ *
+ * Use this to generate auto-index pages at `/<parent>` so visiting a section
+ * URL (e.g. `/ai`, `/runnable`) lands on a TOC instead of a 404.
+ */
+export function sectionRoots(descriptors) {
+    const enabled = descriptors.filter((d) => d.enabled !== false && d.surfaces.includes('web'));
+    const knownIds = new Set(enabled.map((d) => d.id));
+    const byParent = new Map();
+    for (const d of enabled) {
+        if (!d.parent)
+            continue;
+        if (knownIds.has(d.parent))
+            continue;
+        const href = d.body.type === 'route' ? d.body.path : `/${idToSlug(d.id)}`;
+        const entry = {
+            id: d.id,
+            title: d.title,
+            summary: d.summary,
+            href,
+            bodyType: d.body.type,
+            parent: d.parent,
+            tags: d.tags,
+            order: d.order ?? Number.MAX_SAFE_INTEGER
+        };
+        const list = byParent.get(d.parent) ?? [];
+        list.push(entry);
+        byParent.set(d.parent, list);
+    }
+    const roots = [];
+    for (const [parent, entries] of byParent) {
+        entries.sort((a, b) => {
+            if (a.order !== b.order)
+                return a.order - b.order;
+            return a.title.localeCompare(b.title);
+        });
+        roots.push({
+            id: parent,
+            title: titleizeParent(parent),
+            children: entries
+        });
+    }
+    roots.sort((a, b) => a.id.localeCompare(b.id));
+    return roots;
+}
+/**
+ * Look up a single implicit section root by id. Returns null if the id is a
+ * real topic, or if no topic declares it as a parent.
+ */
+export function sectionRootFor(descriptors, id) {
+    return sectionRoots(descriptors).find((r) => r.id === id) ?? null;
+}
+/**
+ * Group ids pinned ahead of the alphabetical sort in {@link buildSidebar} —
+ * orientation content a first-time visitor needs before anything else, so it
+ * must never be buried by where its name falls in the alphabet. Order within
+ * this list is the pin order (first entry sorts first).
+ */
+const PINNED_GROUPS = ['getting-started'];
+/**
+ * Build the sidebar grouped by `parent`. Topics without a parent fall into a
+ * synthetic root group. `body.type: 'route'` topics use their `path` as the
+ * href; everything else uses the slug derived from the id.
+ */
+export function buildSidebar(descriptors) {
+    const enabled = descriptors.filter((d) => d.enabled !== false && d.surfaces.includes('web'));
+    const grouped = new Map();
+    for (const d of enabled) {
+        const href = d.body.type === 'route' ? d.body.path : `/${idToSlug(d.id)}`;
+        const entry = {
+            id: d.id,
+            title: d.title,
+            summary: d.summary,
+            href,
+            bodyType: d.body.type,
+            parent: d.parent,
+            track: d.track ?? inferTrackForParent(d.parent, d.id),
+            tags: d.tags,
+            order: d.order ?? Number.MAX_SAFE_INTEGER
+        };
+        const key = d.parent;
+        const list = grouped.get(key) ?? [];
+        list.push(entry);
+        grouped.set(key, list);
+    }
+    const groups = [];
+    for (const [parent, entries] of grouped) {
+        entries.sort((a, b) => {
+            if (a.order !== b.order)
+                return a.order - b.order;
+            return a.title.localeCompare(b.title);
+        });
+        const groupTrack = entries.find((e) => e.track)?.track ?? inferTrackForParent(parent);
+        groups.push({
+            parent,
+            track: groupTrack,
+            title: parent ?? 'Overview',
+            entries
+        });
+    }
+    groups.sort((a, b) => {
+        if (a.parent === undefined && b.parent !== undefined)
+            return -1;
+        if (a.parent !== undefined && b.parent === undefined)
+            return 1;
+        const aPin = PINNED_GROUPS.indexOf(a.parent ?? '');
+        const bPin = PINNED_GROUPS.indexOf(b.parent ?? '');
+        if (aPin !== -1 || bPin !== -1) {
+            if (aPin === -1)
+                return 1;
+            if (bPin === -1)
+                return -1;
+            return aPin - bPin;
+        }
+        return (a.parent ?? '').localeCompare(b.parent ?? '');
+    });
+    return groups;
+}

package/dist/svelte/context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Svelte context API for the docs topic registry.
+ *
+ * Apps that embed `<HelpIcon />` set the topics array once at layout level
+ * (`setDocsTopics(topics)`); the helper components resolve topic ids
+ * locally via this context. Keeps the components decoupled from any
+ * specific runtime client or app's registry path.
+ */
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs/schemas';
+export declare function setDocsTopics(topics: readonly DocsTopicDescriptor[]): void;
+export declare function getDocsTopics(): readonly DocsTopicDescriptor[];
+//# sourceMappingURL=context.d.ts.map

package/dist/svelte/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/svelte/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAIrE,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,GAAG,IAAI,CAE1E;AAED,wBAAgB,aAAa,IAAI,SAAS,mBAAmB,EAAE,CAE9D"}

package/dist/svelte/context.js

@@ -0,0 +1,16 @@
+/**
+ * Svelte context API for the docs topic registry.
+ *
+ * Apps that embed `<HelpIcon />` set the topics array once at layout level
+ * (`setDocsTopics(topics)`); the helper components resolve topic ids
+ * locally via this context. Keeps the components decoupled from any
+ * specific runtime client or app's registry path.
+ */
+import { getContext, setContext } from 'svelte';
+const DOCS_TOPICS_KEY = Symbol('docs-topics');
+export function setDocsTopics(topics) {
+    setContext(DOCS_TOPICS_KEY, topics);
+}
+export function getDocsTopics() {
+    return getContext(DOCS_TOPICS_KEY) ?? [];
+}

package/dist/svelte/docs-origin.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Docs-app origin for in-app "Open in docs" links.
+ *
+ * Preferred source when a runtime is in hand: the declared `docs`
+ * `infra/service` (`serviceOrigin`). When that service is undeclared, or
+ * when no runtime is in the svelte tree, the `docs.svelte` `publicOrigin`
+ * descriptor default (`https://docs.vibes.dev`) keeps the link.
+ */
+import { type VibesRuntime } from '@vibesdotdev/kernel';
+/** Schema default for Open in docs; read when it runs, never at import. */
+export declare function docsPublicOriginDefault(): string;
+export declare function resolveDocsServiceOrigin(runtime: VibesRuntime): Promise<string>;
+export declare function docsTopicHref(origin: string | null | undefined, topicId: string): string;
+//# sourceMappingURL=docs-origin.d.ts.map

package/dist/svelte/docs-origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-origin.d.ts","sourceRoot":"","sources":["../../src/svelte/docs-origin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAQzE,2EAA2E;AAC3E,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAwBD,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAMrF;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKxF"}

package/dist/svelte/docs-origin.js

@@ -0,0 +1,49 @@
+/**
+ * Docs-app origin for in-app "Open in docs" links.
+ *
+ * Preferred source when a runtime is in hand: the declared `docs`
+ * `infra/service` (`serviceOrigin`). When that service is undeclared, or
+ * when no runtime is in the svelte tree, the `docs.svelte` `publicOrigin`
+ * descriptor default (`https://docs.vibes.dev`) keeps the link.
+ */
+import { getLogger } from '@vibesdotdev/logging';
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { serviceOrigin } from '@vibesdotdev/infra-core/service';
+import { DOCS_SVELTE_CONFIG_MANIFEST_ID, DocsSvelteConfigSchema } from "../config/docs.svelte.config.descriptor.js";
+/** Schema default for Open in docs; read when it runs, never at import. */
+export function docsPublicOriginDefault() {
+    return DocsSvelteConfigSchema.parse({}).publicOrigin.replace(/\/$/, '');
+}
+async function readDocsPublicOrigin(runtime) {
+    if (!runtime.hasKind('config/manifest')) {
+        return docsPublicOriginDefault();
+    }
+    try {
+        const { ConfigManifest } = await import('@vibesdotdev/config/manifest/config-manifest');
+        const config = await ConfigManifest.forRuntime(runtime, DOCS_SVELTE_CONFIG_MANIFEST_ID).load();
+        return config.publicOrigin.replace(/\/$/, '');
+    }
+    catch (error) {
+        if (error instanceof CapabilityError && error.reason === 'config-manifest-unregistered') {
+            getLogger('docs.svelte.origin', runtime).warn('docs.svelte publicOrigin unread; using schema default', {
+                error: error.message
+            });
+            return docsPublicOriginDefault();
+        }
+        throw error;
+    }
+}
+export async function resolveDocsServiceOrigin(runtime) {
+    if (runtime.hasKind('infra/service')) {
+        const selected = await runtime.query('infra/service').withId('docs').select();
+        if (selected)
+            return (await serviceOrigin(runtime, 'docs')).replace(/\/$/, '');
+    }
+    return readDocsPublicOrigin(runtime);
+}
+export function docsTopicHref(origin, topicId) {
+    const declared = origin?.replace(/\/$/, '');
+    const base = declared && declared.length > 0 ? declared : docsPublicOriginDefault();
+    const path = topicId.replaceAll('.', '/');
+    return path ? `${base}/${path}` : `${base}/`;
+}

package/dist/svelte/docs-svelte.plugin.d.ts

@@ -0,0 +1,121 @@
+export declare const docsToolWidgetDescriptor: {
+    id: string;
+    kind: "tools/ui";
+    surfaces: ("cli" | "web" | "tui" | "worker" | "bridge")[];
+    role: "badge" | "widget" | "approval";
+    targetToolId: string;
+    name?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    enabled?: boolean | undefined;
+    priority?: number | undefined;
+    capabilityId?: string | undefined;
+    requiredContext?: string[] | undefined;
+    optionalContext?: string[] | undefined;
+    config?: unknown;
+    retention?: string | {
+        reason: string;
+        maxAgeDays?: number | undefined;
+        maxEntries?: number | undefined;
+        maxBytes?: number | undefined;
+        cascadeFrom?: string | undefined;
+        ageField?: string | undefined;
+        enforcedBy?: string | undefined;
+    } | undefined;
+    hardware?: ("consumer" | "cloud")[] | undefined;
+    targetId?: string | undefined;
+    placement?: "inline" | "top" | "bottom" | undefined;
+};
+export declare const documentReadToolWidgetDescriptor: {
+    id: string;
+    kind: "tools/ui";
+    surfaces: ("cli" | "web" | "tui" | "worker" | "bridge")[];
+    role: "badge" | "widget" | "approval";
+    targetToolId: string;
+    name?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    enabled?: boolean | undefined;
+    priority?: number | undefined;
+    capabilityId?: string | undefined;
+    requiredContext?: string[] | undefined;
+    optionalContext?: string[] | undefined;
+    config?: unknown;
+    retention?: string | {
+        reason: string;
+        maxAgeDays?: number | undefined;
+        maxEntries?: number | undefined;
+        maxBytes?: number | undefined;
+        cascadeFrom?: string | undefined;
+        ageField?: string | undefined;
+        enforcedBy?: string | undefined;
+    } | undefined;
+    hardware?: ("consumer" | "cloud")[] | undefined;
+    targetId?: string | undefined;
+    placement?: "inline" | "top" | "bottom" | undefined;
+};
+export declare const runbookToolWidgetDescriptor: {
+    id: string;
+    kind: "tools/ui";
+    surfaces: ("cli" | "web" | "tui" | "worker" | "bridge")[];
+    role: "badge" | "widget" | "approval";
+    targetToolId: string;
+    name?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    enabled?: boolean | undefined;
+    priority?: number | undefined;
+    capabilityId?: string | undefined;
+    requiredContext?: string[] | undefined;
+    optionalContext?: string[] | undefined;
+    config?: unknown;
+    retention?: string | {
+        reason: string;
+        maxAgeDays?: number | undefined;
+        maxEntries?: number | undefined;
+        maxBytes?: number | undefined;
+        cascadeFrom?: string | undefined;
+        ageField?: string | undefined;
+        enforcedBy?: string | undefined;
+    } | undefined;
+    hardware?: ("consumer" | "cloud")[] | undefined;
+    targetId?: string | undefined;
+    placement?: "inline" | "top" | "bottom" | undefined;
+};
+export declare const presentationsToolWidgetDescriptor: {
+    id: string;
+    kind: "tools/ui";
+    surfaces: ("cli" | "web" | "tui" | "worker" | "bridge")[];
+    role: "badge" | "widget" | "approval";
+    targetToolId: string;
+    name?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    enabled?: boolean | undefined;
+    priority?: number | undefined;
+    capabilityId?: string | undefined;
+    requiredContext?: string[] | undefined;
+    optionalContext?: string[] | undefined;
+    config?: unknown;
+    retention?: string | {
+        reason: string;
+        maxAgeDays?: number | undefined;
+        maxEntries?: number | undefined;
+        maxBytes?: number | undefined;
+        cascadeFrom?: string | undefined;
+        ageField?: string | undefined;
+        enforcedBy?: string | undefined;
+    } | undefined;
+    hardware?: ("consumer" | "cloud")[] | undefined;
+    targetId?: string | undefined;
+    placement?: "inline" | "top" | "bottom" | undefined;
+};
+/**
+ * Runtime plugin (read-surface parity).
+ *
+ * Designed Kit cards for docs-owned agent tools register `tools/ui` here so
+ * Chat hosts discover them through the widget registry, not a host-local table.
+ */
+export declare const docsSveltePlugin: import("@vibesdotdev/kernel").RuntimePlugin;
+export default docsSveltePlugin;
+//# sourceMappingURL=docs-svelte.plugin.d.ts.map

package/dist/svelte/docs-svelte.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-svelte.plugin.d.ts","sourceRoot":"","sources":["../../src/svelte/docs-svelte.plugin.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAuD,CAAC;AAC7F,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;CAE3C,CAAC;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA0D,CAAC;AACnG,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;CAE5C,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,6CAyB3B,CAAC;AAEH,eAAe,gBAAgB,CAAC"}

package/dist/svelte/docs-svelte.plugin.js

@@ -0,0 +1,35 @@
+import { createRuntimePlugin } from '@vibesdotdev/kernel';
+import { createSvelteToolWidgetDescriptor, createSvelteToolWidgetLoader } from '@vibesdotdev/tools/svelte/tool-widgets';
+export const docsToolWidgetDescriptor = createSvelteToolWidgetDescriptor({ toolId: 'docs' });
+export const documentReadToolWidgetDescriptor = createSvelteToolWidgetDescriptor({
+    toolId: 'document.read'
+});
+export const runbookToolWidgetDescriptor = createSvelteToolWidgetDescriptor({ toolId: 'runbook' });
+export const presentationsToolWidgetDescriptor = createSvelteToolWidgetDescriptor({
+    toolId: 'presentations'
+});
+/**
+ * Runtime plugin (read-surface parity).
+ *
+ * Designed Kit cards for docs-owned agent tools register `tools/ui` here so
+ * Chat hosts discover them through the widget registry, not a host-local table.
+ */
+export const docsSveltePlugin = createRuntimePlugin({
+    id: '@vibesdotdev/docs/svelte',
+    name: 'Docs Svelte',
+    description: 'Svelte/browser surface for docs-owned tool cards',
+    dependencies: ['tools'],
+    descriptors: [
+        docsToolWidgetDescriptor,
+        documentReadToolWidgetDescriptor,
+        runbookToolWidgetDescriptor,
+        presentationsToolWidgetDescriptor
+    ],
+    loaders: [
+        createSvelteToolWidgetLoader(docsToolWidgetDescriptor, () => import('./tool-widgets/DocsToolCard.svelte')),
+        createSvelteToolWidgetLoader(documentReadToolWidgetDescriptor, () => import('./tool-widgets/DocumentReadToolCard.svelte')),
+        createSvelteToolWidgetLoader(runbookToolWidgetDescriptor, () => import('./tool-widgets/RunbookToolCard.svelte')),
+        createSvelteToolWidgetLoader(presentationsToolWidgetDescriptor, () => import('./tool-widgets/PresentationsToolCard.svelte'))
+    ]
+});
+export default docsSveltePlugin;