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

package/dist/schemas/citations.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/citations.schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAI5B,eAAO,MAAM,yBAAyB;;;iBAAmD,CAAC;AAC1F,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;oBAWlC,CAAC"}

package/dist/schemas/citations.schema.js

@@ -0,0 +1,17 @@
+import * as z from 'zod/v4';
+import { DocsTopicDescriptorSchema } from "./topic.schema.js";
+const LimitSchema = z.number().int().positive().optional();
+export const DocsCitationSubjectSchema = DocsTopicDescriptorSchema.shape.subject.unwrap();
+export const DocsCitationQuerySchema = z.union([
+    z.object({
+        ids: z.array(z.string().min(1)).min(1),
+        maxTopics: LimitSchema,
+        stalenessThresholdDays: z.number().finite().nonnegative().optional()
+    }).strict(),
+    z.object({
+        subject: z.union([DocsCitationSubjectSchema, z.enum(['entity', 'package'])]),
+        maxTopics: LimitSchema,
+        stalenessThresholdDays: z.number().finite().nonnegative().optional()
+    }).strict()
+]);
+//# sourceMappingURL=citations.schema.js.map

package/dist/schemas/citations.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.schema.js","sourceRoot":"","sources":["../../src/schemas/citations.schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC;AAC3D,MAAM,CAAC,MAAM,yBAAyB,GAAG,yBAAyB,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;AAC1F,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC;IAC9C,CAAC,CAAC,MAAM,CAAC;QACR,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACtC,SAAS,EAAE,WAAW;QACtB,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;KACpE,CAAC,CAAC,MAAM,EAAE;IACX,CAAC,CAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,yBAAyB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;QAC5E,SAAS,EAAE,WAAW;QACtB,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;KACpE,CAAC,CAAC,MAAM,EAAE;CACX,CAAC,CAAC"}

package/dist/schemas/index.d.ts

@@ -0,0 +1,4 @@
+export { DocsTopicManSchema, DocsTopicBodySchema, DocsTopicDescriptorSchema } from './topic.schema.ts';
+export type { DocsTopicMan, DocsTopicBody, DocsTopicDescriptor } from './topic.schema.ts';
+export { DocsCitationQuerySchema, DocsCitationSubjectSchema } from './citations.schema.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/schemas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACX,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/schemas/index.js

@@ -0,0 +1,3 @@
+export { DocsTopicManSchema, DocsTopicBodySchema, DocsTopicDescriptorSchema } from "./topic.schema.js";
+export { DocsCitationQuerySchema, DocsCitationSubjectSchema } from "./citations.schema.js";
+//# sourceMappingURL=index.js.map

package/dist/schemas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/schemas/topic.schema.d.ts

@@ -0,0 +1,179 @@
+import * as z from 'zod/v4';
+export { DocsTopicBodySchema, DocsTopicManSchema } from '@vibesdotdev/docs-contracts';
+export type { DocsTopicBody, DocsTopicMan } from '@vibesdotdev/docs-contracts';
+/** Docs owns provenance declarations; the neutral topic floor owns presentation fields. */
+export declare const DocsTopicDescriptorSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"docs/topic">;
+    id: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    body: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"markdown">;
+        sourceType: z.ZodDefault<z.ZodEnum<{
+            raw: "raw";
+            package: "package";
+        }>>;
+        source: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"component">;
+        path: z.ZodString;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        exportKey: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"route">;
+        path: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"openapi">;
+        source: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"graphql">;
+        source: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"descriptor-ref">;
+        kind: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>], "type">;
+    parent: z.ZodOptional<z.ZodString>;
+    track: z.ZodOptional<z.ZodEnum<{
+        "start-here": "start-here";
+        "framework-kit": "framework-kit";
+        "platform-cloud": "platform-cloud";
+        "local-tooling": "local-tooling";
+        "api-reference": "api-reference";
+        internals: "internals";
+    }>>;
+    order: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    surfaces: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        cli: "cli";
+        mcp: "mcp";
+        web: "web";
+        "in-app": "in-app";
+    }>>>;
+    subject: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    man: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        section: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        synopsis: z.ZodOptional<z.ZodString>;
+        options: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
+            flag: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>>>;
+        examples: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
+            description: z.ZodString;
+            command: z.ZodString;
+        }, z.core.$strip>>>>;
+        seeAlso: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>>;
+    hardware: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        consumer: "consumer";
+        cloud: "cloud";
+    }>>>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    citationOrigin: z.ZodOptional<z.ZodObject<{
+        link: z.ZodObject<{
+            kind: z.ZodString;
+            id: z.ZodString;
+            source: z.ZodString;
+            role: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>;
+        scope: z.ZodString;
+        revision: z.ZodObject<{
+            scheme: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>;
+        anchor: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"code">;
+            path: z.ZodString;
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"region">;
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"fragment">;
+            id: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"heading">;
+            slug: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+        freshness: z.ZodOptional<z.ZodObject<{
+            modifiedAt: z.ZodOptional<z.ZodISODateTime>;
+            stale: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    citationFreshness: z.ZodOptional<z.ZodObject<{
+        document: z.ZodObject<{
+            link: z.ZodObject<{
+                kind: z.ZodString;
+                id: z.ZodString;
+                source: z.ZodString;
+                role: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>;
+            scope: z.ZodString;
+            revision: z.ZodObject<{
+                scheme: z.ZodString;
+                value: z.ZodString;
+            }, z.core.$strip>;
+            anchor: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"code">;
+                path: z.ZodString;
+                startLine: z.ZodNumber;
+                endLine: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"region">;
+                start: z.ZodNumber;
+                end: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"fragment">;
+                id: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"heading">;
+                slug: z.ZodString;
+            }, z.core.$strip>], "kind">>;
+            freshness: z.ZodOptional<z.ZodObject<{
+                modifiedAt: z.ZodOptional<z.ZodISODateTime>;
+                stale: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        references: z.ZodArray<z.ZodObject<{
+            link: z.ZodObject<{
+                kind: z.ZodString;
+                id: z.ZodString;
+                source: z.ZodString;
+                role: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>;
+            scope: z.ZodString;
+            revision: z.ZodObject<{
+                scheme: z.ZodString;
+                value: z.ZodString;
+            }, z.core.$strip>;
+            anchor: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"code">;
+                path: z.ZodString;
+                startLine: z.ZodNumber;
+                endLine: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"region">;
+                start: z.ZodNumber;
+                end: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"fragment">;
+                id: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"heading">;
+                slug: z.ZodString;
+            }, z.core.$strip>], "kind">>;
+            freshness: z.ZodOptional<z.ZodObject<{
+                modifiedAt: z.ZodOptional<z.ZodISODateTime>;
+                stale: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DocsTopicDescriptor = z.output<typeof DocsTopicDescriptorSchema>;
+//# sourceMappingURL=topic.schema.d.ts.map

package/dist/schemas/topic.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/topic.schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAI5B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtF,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE/E,2FAA2F;AAC3F,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/schemas/topic.schema.js

@@ -0,0 +1,15 @@
+import * as z from 'zod/v4';
+import { DocsTopicDescriptorSchema as BaseDocsTopicDescriptorSchema } from '@vibesdotdev/docs-contracts';
+import { CitationSchema } from '@vibesdotdev/shared/citations';
+export { DocsTopicBodySchema, DocsTopicManSchema } from '@vibesdotdev/docs-contracts';
+/** Docs owns provenance declarations; the neutral topic floor owns presentation fields. */
+export const DocsTopicDescriptorSchema = BaseDocsTopicDescriptorSchema.extend({
+    citationOrigin: CitationSchema.optional(),
+    citationFreshness: z.object({
+        document: CitationSchema.refine(citation => citation.anchor === undefined, {
+            message: 'Document freshness requires a complete document citation.'
+        }),
+        references: z.array(CitationSchema)
+    }).optional()
+});
+//# sourceMappingURL=topic.schema.js.map

package/dist/schemas/topic.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.schema.js","sourceRoot":"","sources":["../../src/schemas/topic.schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,yBAAyB,IAAI,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AACzG,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAGtF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,yBAAyB,GAAG,6BAA6B,CAAC,MAAM,CAAC;IAC7E,cAAc,EAAE,cAAc,CAAC,QAAQ,EAAE;IACzC,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC;QAC3B,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE;YAC1E,OAAO,EAAE,2DAA2D;SACpE,CAAC;QACF,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;KACnC,CAAC,CAAC,QAAQ,EAAE;CACb,CAAC,CAAC"}

package/dist/svelte/build/highlight.d.ts

@@ -0,0 +1,33 @@
+import type { Tokens } from 'marked';
+import type { ParsedTopic } from '@vibesdotdev/docs/render';
+/**
+ * Back-compat shape for callers that previously accepted highlighted code
+ * tokens. Rendering is now owned by VibesKit's CodeViewer, so this package no
+ * longer attaches HTML to code tokens.
+ */
+export interface HighlightedCodeToken extends Tokens.Code {
+    highlighted?: string;
+}
+/**
+ * Walk parsed markdown tokens and rewrite link tokens whose href is a bare
+ * topic-id reference into the slug URL. Pure mutation, no I/O.
+ *
+ * Used both at server-load time (top-level topic body) and inside directive
+ * components (Card directives parse their body at render time and need the
+ * same rewrite to keep cross-references working).
+ */
+export declare function rewriteTopicLinks(parsed: ParsedTopic, topicIds: ReadonlySet<string>): void;
+/**
+ * Prepare a parsed topic before rendering. The historical name is retained for
+ * callers, but syntax rendering is now delegated to VibesKit's CodeViewer at
+ * render time so docs-svelte does not own a second highlighter.
+ *
+ * If `topicIds` is provided, link tokens whose href matches a known topic id
+ * (e.g. `app.branding`) are rewritten to the corresponding slug URL
+ * (`/app/branding`). Topic docs cross-reference each other by id rather than
+ * by slug, so the rewrite is what makes those links actually navigable.
+ */
+export declare function highlightParsedTopic(parsed: ParsedTopic, options?: {
+    topicIds?: ReadonlySet<string>;
+}): Promise<ParsedTopic>;
+//# sourceMappingURL=highlight.d.ts.map

package/dist/svelte/build/highlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlight.d.ts","sourceRoot":"","sources":["../../../src/svelte/build/highlight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,MAAM,CAAC,IAAI;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAkBD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAO1F;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACzC,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAO,GAC9C,OAAO,CAAC,WAAW,CAAC,CAYtB"}

package/dist/svelte/build/highlight.js

@@ -0,0 +1,95 @@
+function walkSync(tokens, visit) {
+    for (const tok of tokens) {
+        visit(tok);
+        const nested = tok.tokens;
+        if (Array.isArray(nested))
+            walkSync(nested, visit);
+        if (tok.type === 'list') {
+            const list = tok;
+            for (const item of list.items)
+                walkSync(item.tokens ?? [], visit);
+        }
+        if (tok.type === 'blockquote') {
+            const bq = tok;
+            walkSync(bq.tokens ?? [], visit);
+        }
+    }
+}
+/**
+ * Walk parsed markdown tokens and rewrite link tokens whose href is a bare
+ * topic-id reference into the slug URL. Pure mutation, no I/O.
+ *
+ * Used both at server-load time (top-level topic body) and inside directive
+ * components (Card directives parse their body at render time and need the
+ * same rewrite to keep cross-references working).
+ */
+export function rewriteTopicLinks(parsed, topicIds) {
+    walkSync(parsed.tokens, (tok) => {
+        if (tok.type !== 'link')
+            return;
+        const link = tok;
+        const rewritten = rewriteTopicHref(link.href, topicIds);
+        if (rewritten)
+            link.href = rewritten;
+    });
+}
+/**
+ * Prepare a parsed topic before rendering. The historical name is retained for
+ * callers, but syntax rendering is now delegated to VibesKit's CodeViewer at
+ * render time so docs-svelte does not own a second highlighter.
+ *
+ * If `topicIds` is provided, link tokens whose href matches a known topic id
+ * (e.g. `app.branding`) are rewritten to the corresponding slug URL
+ * (`/app/branding`). Topic docs cross-reference each other by id rather than
+ * by slug, so the rewrite is what makes those links actually navigable.
+ */
+export async function highlightParsedTopic(parsed, options = {}) {
+    const topicIds = options.topicIds;
+    if (!topicIds)
+        return parsed;
+    walkSync(parsed.tokens, (tok) => {
+        if (topicIds && tok.type === 'link') {
+            const link = tok;
+            const rewritten = rewriteTopicHref(link.href, topicIds);
+            if (rewritten)
+                link.href = rewritten;
+        }
+    });
+    return parsed;
+}
+/**
+ * Topic-id shape: dotted identifier (e.g. `app.branding`, `runtime.query`).
+ * No scheme, no slash, no leading punctuation — and at least one dot, so we
+ * don't accidentally rewrite single-word relative links like `index` or `faq`.
+ */
+const TOPIC_ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*(?:\.[a-zA-Z][a-zA-Z0-9_-]*)+$/;
+/**
+ * If `href` looks like a bare topic-id reference (e.g. `app.branding`,
+ * `runtime.query`), return the slug URL (`/app/branding`). Topic-shaped
+ * references are rewritten whether or not the target id is registered — an
+ * unresolved reference will 404 visibly, which beats silently navigating to
+ * a relative path under the current page.
+ *
+ * Returns null for external URLs, absolute paths, anchors, mailto, or
+ * non-topic-shaped relatives — leaving those hrefs untouched.
+ */
+function rewriteTopicHref(href, _topicIds) {
+    if (!href)
+        return null;
+    if (href.startsWith('/') ||
+        href.startsWith('#') ||
+        href.startsWith('?') ||
+        href.startsWith('./') ||
+        href.startsWith('../') ||
+        /^[a-z][a-z0-9+.-]*:/i.test(href)) {
+        return null;
+    }
+    const match = href.match(/^([^#?]+)([#?].*)?$/);
+    if (!match)
+        return null;
+    const id = match[1];
+    const suffix = match[2] ?? '';
+    if (!TOPIC_ID_PATTERN.test(id))
+        return null;
+    return `/${id.replaceAll('.', '/')}${suffix}`;
+}

package/dist/svelte/build/topic-index.d.ts

@@ -0,0 +1,96 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs/schemas';
+import { type ParsedTopic } from '@vibesdotdev/docs/render';
+/**
+ * A `docs/topic` descriptor paired with its parsed AST (for markdown bodies).
+ * Build-time helpers emit these so SvelteKit's prerender doesn't re-parse.
+ */
+export interface IndexedTopic {
+    descriptor: DocsTopicDescriptor;
+    parsed: ParsedTopic | null;
+}
+/**
+ * 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 declare function pageRenderableTopics(descriptors: readonly DocsTopicDescriptor[]): DocsTopicDescriptor[];
+/**
+ * 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 declare function topicEntries(descriptors: readonly DocsTopicDescriptor[]): Array<{
+    slug: string;
+}>;
+/**
+ * Topic id → URL slug. `tools.list` → `tools/list`; `guide` → `guide`.
+ */
+export declare function idToSlug(id: string): string;
+/**
+ * URL slug → topic id. Inverse of `idToSlug`. SvelteKit hands the dynamic
+ * route a `params.slug` string with `/` separators; we restore dots.
+ */
+export declare function slugToId(slug: string): string;
+/**
+ * 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 declare function indexedTopicFor(descriptors: readonly DocsTopicDescriptor[], id: string): IndexedTopic | null;
+export interface SidebarEntry {
+    id: string;
+    title: string;
+    summary?: string;
+    href: string;
+    bodyType: DocsTopicDescriptor['body']['type'];
+    parent?: string;
+    track?: DocsTopicDescriptor['track'];
+    tags: readonly string[];
+    order: number;
+}
+export declare function inferTrackForParent(parent?: string, id?: string): NonNullable<DocsTopicDescriptor['track']>;
+/**
+ * An implicit section root — a `parent` value referenced by topics, but with
+ * no topic of its own. E.g. children declare `parent: 'ai'`, but no descriptor
+ * has `id: 'ai'`, so `/ai` would 404 without a synthesized TOC page.
+ */
+export interface SectionRoot {
+    id: string;
+    title: string;
+    children: SidebarEntry[];
+}
+/**
+ * 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 declare function sectionRoots(descriptors: readonly DocsTopicDescriptor[]): SectionRoot[];
+/**
+ * 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 declare function sectionRootFor(descriptors: readonly DocsTopicDescriptor[], id: string): SectionRoot | null;
+export interface SidebarGroup {
+    parent: string | undefined;
+    track?: DocsTopicDescriptor['track'];
+    title: string;
+    entries: SidebarEntry[];
+}
+/**
+ * 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 declare function buildSidebar(descriptors: readonly DocsTopicDescriptor[]): SidebarGroup[];
+//# sourceMappingURL=topic-index.d.ts.map

package/dist/svelte/build/topic-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-index.d.ts","sourceRoot":"","sources":["../../../src/svelte/build/topic-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,UAAU,EAAE,mBAAmB,CAAC;IAChC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,WAAW,EAAE,SAAS,mBAAmB,EAAE,GACzC,mBAAmB,EAAE,CAevB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC3B,WAAW,EAAE,SAAS,mBAAmB,EAAE,GACzC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAIzB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,WAAW,EAAE,SAAS,mBAAmB,EAAE,EAC3C,EAAE,EAAE,MAAM,GACR,YAAY,GAAG,IAAI,CAQrB;AAED,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAmD3G;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;CACzB;AAcD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,GAAG,WAAW,EAAE,CAuCvF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC7B,WAAW,EAAE,SAAS,mBAAmB,EAAE,EAC3C,EAAE,EAAE,MAAM,GACR,WAAW,GAAG,IAAI,CAEpB;AAED,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,YAAY,EAAE,CAAC;CACxB;AAUD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,GAAG,YAAY,EAAE,CAuDxF"}