From fcaf21d1c52f1f4aa94bd3ea88320661f70216b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matheus=20Vila=C3=A7a=20de=20Jesus?=
 <matheus@codeatlas.com.br>
Date: Sun, 25 Oct 2026 16:27:51 -0300
Subject: [PATCH 1/2] chore: start #625


From 240c83909a333bbf0e91b7124393d681b5f5f7e4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matheus=20Vila=C3=A7a=20de=20Jesus?=
 <matheus@codeatlas.com.br>
Date: Sun, 25 Oct 2026 18:28:32 -0300
Subject: [PATCH 2/2] refactor: split packages/ui/scripts/build-manifest.ts
 into focused modules (#625)

---
 packages/ui/scripts/build-manifest.ts      | 1640 +-------------------
 packages/ui/scripts/manifest/ast.ts        |   25 +
 packages/ui/scripts/manifest/components.ts |  487 ++++++
 packages/ui/scripts/manifest/demos.ts      |  365 +++++
 packages/ui/scripts/manifest/exports.ts    |  227 +++
 packages/ui/scripts/manifest/guides.ts     |   60 +
 packages/ui/scripts/manifest/paths.ts      |   35 +
 packages/ui/scripts/manifest/styling.ts    |  124 ++
 packages/ui/scripts/manifest/tokens.ts     |  175 +++
 packages/ui/scripts/manifest/writers.ts    |  153 ++
 10 files changed, 1679 insertions(+), 1612 deletions(-)
 create mode 100644 packages/ui/scripts/manifest/ast.ts
 create mode 100644 packages/ui/scripts/manifest/components.ts
 create mode 100644 packages/ui/scripts/manifest/demos.ts
 create mode 100644 packages/ui/scripts/manifest/exports.ts
 create mode 100644 packages/ui/scripts/manifest/guides.ts
 create mode 100644 packages/ui/scripts/manifest/paths.ts
 create mode 100644 packages/ui/scripts/manifest/styling.ts
 create mode 100644 packages/ui/scripts/manifest/tokens.ts
 create mode 100644 packages/ui/scripts/manifest/writers.ts

diff --git a/packages/ui/scripts/build-manifest.ts b/packages/ui/scripts/build-manifest.ts
index 7139b614..1cd0073e 100644
--- a/packages/ui/scripts/build-manifest.ts
+++ b/packages/ui/scripts/build-manifest.ts
@@ -22,1629 +22,45 @@
  * exports (stores, functions, types, Vite/Astro/Kit helpers) is resolved with a TypeScript
  * `Program` over the entry files and reported with its signature and JSDoc summary.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname, join, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import ts from "typescript";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { loadMigrations, migrationMarkdown } from "../src/cli/migrations.ts";
-import { STYLES, type SurfaceStyle } from "../src/lib/theme/define.ts";
-import { DESIGN_STYLES } from "../src/lib/theme/styles.ts";
-import { ENTRY_PAGES, parseRecipes, type Recipe } from "./ai-entry.ts";
 import { buildAtlasFile } from "./atlas-markdown.ts";
 import { buildReleaseFile } from "./changelog-markdown.ts";
 import { buildIndexFiles } from "./index-build.ts";
-import { checkIdRange, checkIndexFacets, ID_PATTERN, type IndexFacets } from "./index-schema.ts";
-import { demoSources, mdxToMarkdown } from "./mdx-to-markdown.ts";
+import { buildManifest } from "./manifest/components.ts";
+import { buildDemos, checkCatalog } from "./manifest/demos.ts";
+import { buildGuides, buildRecipes } from "./manifest/guides.ts";
+import { DEMOS_DIR, ROOT } from "./manifest/paths.ts";
+import { buildSurfaces, buildTokens } from "./manifest/tokens.ts";
+import { buildParts, demosMarkdown, skillMarkdown } from "./manifest/writers.ts";
 import { buildStyleFile } from "./styles-markdown.ts";
 
-// CJS require keeps svelte2tsx out of Vite's transform pipeline (its sourceMappingURL points at a file it does not ship).
-const { svelte2tsx }: typeof import("svelte2tsx") = createRequire(import.meta.url)("svelte2tsx");
-const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const LIB = join(ROOT, "src/lib");
-const PKG = "@codeatlasdev/ui";
-
-/** Public entry points: import specifier → entry file under src/lib. */
-const ENTRIES: Record<string, string> = {
-	[PKG]: "index.ts",
-	[`${PKG}/charts`]: "charts/index.ts",
-	[`${PKG}/map`]: "map/index.ts",
-	[`${PKG}/sound`]: "sound/index.ts",
-	[`${PKG}/table`]: "components/DataTable/index.ts",
-	[`${PKG}/code`]: "components/CodeSnippet/index.ts",
-	[`${PKG}/forms`]: "forms/index.ts",
-};
-
-/** Entries whose non-component exports are documented: specifier → source file (mirrors package.json#exports). */
-const API_ENTRIES: Record<string, string> = {
-	...ENTRIES,
-	[`${PKG}/kit`]: "kit/index.ts",
-	[`${PKG}/vite`]: "vite-plugin.ts",
-	[`${PKG}/astro`]: "astro.ts",
-	[`${PKG}/actions`]: "actions/index.ts",
-	[`${PKG}/seo`]: "seo/index.ts",
-	[`${PKG}/tokens`]: "tokens/index.ts",
-	[`${PKG}/utils/palette-generator`]: "utils/palette-generator.ts",
-	[`${PKG}/utils/color`]: "utils/color.ts",
-};
-
-export type ExportKind = "function" | "store" | "const" | "class" | "type";
-
-export interface ManifestExport {
-	name: string;
-	/** Import specifier, e.g. `@codeatlasdev/ui/kit`. */
-	import: string;
-	kind: ExportKind;
-	/** One-line declaration: `function f(a: A): R`, `interface X { ... }`, `type T = ...`, `const x: T`. */
-	signature: string;
-	/** First paragraph of the JSDoc of the declaration (or of the comment right above it). */
-	description?: string;
-	/** Fields of an exported interface (or object type alias): name, type, optionality, JSDoc. */
-	members?: ManifestExportMember[];
-	/** Source file relative to `src/lib`. */
-	source: string;
-}
-
-export interface ManifestExportMember {
-	name: string;
-	type: string;
-	optional: boolean;
-	description?: string;
-}
-
-export interface ManifestProp {
-	name: string;
-	type: string;
-	optional: boolean;
-	default?: string;
-	/** `$bindable` prop (use `bind:name`). */
-	bindable?: boolean;
-	description?: string;
-}
-
-export interface ManifestComponent {
-	name: string;
-	/** Import specifier, e.g. `@codeatlasdev/ui` or `@codeatlasdev/ui/charts`. */
-	import: string;
-	/** Source file relative to `src/lib`. */
-	source: string;
-	/** First JSDoc/comment paragraph of the component, when present. */
-	description?: string;
-	/** Replacement text of a component-level `@deprecated` ("Use `<Flex>`: ..."). Absent on current components. */
-	deprecated?: string;
-	/** Own props. Inherited attributes (e.g. `HTMLAttributes`) are listed in `extends`. */
-	props: ManifestProp[];
-	/** Props typed as `Snippet`/`Snippet<[...]>`: the holes a caller fills. */
-	snippets: ManifestProp[];
-	/** Text of the interface `extends` clause: native attributes that also pass through. */
-	extends?: string;
-	/** Stable `ca-*` class names defined in the component `<style>` (the stable subset of `styling.parts`). */
-	classes: string[];
-	/** Everything an app may target to restyle this component, each part flagged stable or internal (#381). */
-	styling: ManifestStyling;
-	/** Component tokens: `--ca-<stem>-*` custom properties the `<style>` reads with a fallback (`var(--ca-btn-gap, …)`). Set them on `:root`, a wrapper or `ThemeOptions.components`. */
-	tokens: string[];
-	/** Generic parameters, e.g. `TData extends RowData`. */
-	generics?: string;
-}
-
-export interface ManifestPart {
-	/** Class name without the dot, or a `@keyframes` name. */
-	name: string;
-	/** `false`: private (`ca-x-` prefix, `@keyframes`); it can be renamed in any release. */
-	stable: boolean;
-}
-
-export interface ManifestDataAttribute {
-	name: string;
-	/** Values the component CSS selects on (`[data-size='sm']`); empty when only its presence matters. */
-	values: string[];
-}
-
-export interface ManifestStyling {
-	parts: ManifestPart[];
-	/** Component-scoped `--ca-*` custom properties (not global tokens): set on the element to restyle one axis. */
-	variables: string[];
-	/** `data-*` attributes the component CSS selects on. */
-	data: ManifestDataAttribute[];
-}
-
-export interface Manifest {
-	name: string;
-	version: string;
-	components: ManifestComponent[];
-	/** Every other export of every entry point: functions, stores, constants, classes, types. */
-	exports: ManifestExport[];
-}
-
-// ── entry parsing ─────────────────────────────────────────────────────────────
-
-interface Found {
-	name: string;
-	file: string;
-	entry: string;
-}
-
-/** Resolve `export { default as X } from "./a.svelte"` and `export { X } from "./index.js"` (recursively). */
-function collectExports(entryFile: string, entry: string, out: Found[], seen = new Set<string>()) {
-	const abs = join(LIB, entryFile);
-	if (seen.has(abs) || !existsSync(abs)) return;
-	seen.add(abs);
-	const sf = ts.createSourceFile(abs, readFileSync(abs, "utf8"), ts.ScriptTarget.ESNext, true);
-	const dir = dirname(abs);
-	for (const st of sf.statements) {
-		if (!ts.isExportDeclaration(st) || st.isTypeOnly || !st.moduleSpecifier) continue;
-		if (!ts.isStringLiteral(st.moduleSpecifier) || !st.exportClause) continue;
-		if (!ts.isNamedExports(st.exportClause)) continue;
-		const spec = st.moduleSpecifier.text;
-		if (!spec.startsWith(".")) continue;
-		if (spec.endsWith(".svelte")) {
-			for (const el of st.exportClause.elements) {
-				if (el.isTypeOnly) continue;
-				if ((el.propertyName ?? el.name).text === "default")
-					out.push({ name: el.name.text, file: relative(LIB, join(dir, spec)), entry });
-			}
-		} else if (/\/index\.js$/.test(spec) || spec.endsWith("index")) {
-			// Re-export of named bindings coming from a sub-barrel (Table, Date): follow it,
-			// keeping only the names this entry re-exports.
-			const names = new Set(
-				st.exportClause.elements.filter((e) => !e.isTypeOnly).map((e) => e.name.text)
-			);
-			const sub: Found[] = [];
-			collectExports(relative(LIB, join(dir, spec.replace(/\.js$/, ".ts"))), entry, sub, seen);
-			for (const f of sub) if (names.has(f.name)) out.push(f);
-		}
-	}
-}
-
-// ── props extraction ──────────────────────────────────────────────────────────
-
-/** Last JSDoc comment attached to a node, flattened to one line. */
-function jsDoc(node: ts.Node): string | undefined {
-	const comment = ts.getJSDocCommentsAndTags(node).find(ts.isJSDoc)?.comment;
-	const text = typeof comment === "string" ? comment : comment?.map((c) => c.text).join("");
-	return text?.replace(/\s*\n\s*/g, " ").trim() || undefined;
-}
-
-const propName = (n: ts.PropertyName): string =>
-	ts.isIdentifier(n) || ts.isStringLiteral(n) ? n.text : n.getText();
-
-/** Defaults live in the destructuring: `let { size = 'md', value = $bindable('a') } = $props()`. */
-function readDefaults(decl: ts.VariableDeclaration, sf: ts.SourceFile) {
-	const defaults = new Map<string, { text?: string; bindable: boolean }>();
-	if (!ts.isObjectBindingPattern(decl.name)) return defaults;
-	for (const el of decl.name.elements) {
-		if (el.dotDotDotToken) continue;
-		const key = el.propertyName
-			? propName(el.propertyName as ts.PropertyName)
-			: (el.name as ts.Identifier).text;
-		let text: string | undefined;
-		let bindable = false;
-		const init = el.initializer;
-		if (init) {
-			if (ts.isCallExpression(init) && init.expression.getText(sf) === "$bindable") {
-				bindable = true;
-				text = init.arguments[0]?.getText(sf);
-			} else text = init.getText(sf);
-		}
-		defaults.set(key, { text, bindable });
-	}
-	return defaults;
-}
-
-/** Find `let {...}: T = $props()` in the svelte2tsx output. */
-function findPropsDecl(sf: ts.SourceFile) {
-	let found: ts.VariableDeclaration | undefined;
-	const visit = (n: ts.Node) => {
-		if (found) return;
-		if (
-			ts.isVariableDeclaration(n) &&
-			n.initializer &&
-			ts.isCallExpression(n.initializer) &&
-			n.initializer.expression.getText(sf) === "$props"
-		)
-			found = n;
-		else ts.forEachChild(n, visit);
-	};
-	visit(sf);
-	return found;
-}
-
-/** Members of a component's props, and the native attribute type they extend. */
-interface PropsMembers {
-	members: readonly ts.TypeElement[];
-	ext: string | undefined;
-}
-
-/** Members of `LayoutProps` (components/Layout/layout.ts), the source of every layout primitive's token props. */
-let layoutMembers: Map<string, ts.TypeElement> | undefined;
-function layoutPropMembers(): Map<string, ts.TypeElement> {
-	if (layoutMembers) return layoutMembers;
-	const file = join(LIB, "components/Layout/layout.ts");
-	const sf = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.ESNext, true);
-	layoutMembers = new Map();
-	for (const st of sf.statements)
-		if (ts.isInterfaceDeclaration(st) && st.name.text === "LayoutProps")
-			for (const m of st.members)
-				if (ts.isPropertySignature(m) && m.name) layoutMembers.set(propName(m.name), m);
-	return layoutMembers;
-}
-
-/**
- * `Pick<LayoutProps, 'gap' | 'p'>` (what Flex, Stack, Grid, Box, Container, Section and Surface take): the
- * picked members of `LayoutProps`, so the manifest lists the token props instead of an opaque `extends`.
- * Anything else is `undefined`. Member nodes belong to layout.ts, hence they carry their own source file.
- */
-function layoutPick(
-	type: ts.TypeReferenceNode | ts.ExpressionWithTypeArguments
-): ts.TypeElement[] | undefined {
-	const name = ts.isTypeReferenceNode(type) ? type.typeName : type.expression;
-	if (name.getText() !== "Pick") return undefined;
-	const [target, keys] = type.typeArguments ?? [];
-	if (!target || !keys || target.getText() !== "LayoutProps") return undefined;
-	const names = (ts.isUnionTypeNode(keys) ? keys.types : [keys]).map((k) =>
-		ts.isLiteralTypeNode(k) && ts.isStringLiteral(k.literal) ? k.literal.text : undefined
-	);
-	if (names.some((n) => n === undefined)) return undefined;
-	const all = layoutPropMembers();
-	return names.flatMap((n) => all.get(n as string) ?? []);
-}
-
-/**
- * `PolymorphicAttributes<T, Own>` (Flex, Stack, Grid, Box): `Own` holds the token props, the rest is the tag's
- * own attributes. Returns the members of a `Pick<LayoutProps, ...>` `Own`, or `undefined` for any other shape.
- */
-function polymorphicOwn(type: ts.TypeNode): ts.TypeElement[] | undefined {
-	if (!ts.isTypeReferenceNode(type) || type.typeName.getText() !== "PolymorphicAttributes")
-		return undefined;
-	const own = type.typeArguments?.[1];
-	return own && ts.isTypeReferenceNode(own) ? layoutPick(own) : undefined;
-}
-
-/** Members of the `Props` interface/type alias, or of an inline type literal. */
-function resolvePropsType(sf: ts.SourceFile, type: ts.TypeNode | undefined): PropsMembers {
-	let members: readonly ts.TypeElement[] = [];
-	let ext: string | undefined;
-	if (!type) return { members, ext };
-	if (ts.isTypeLiteralNode(type)) return { members: type.members, ext };
-	if (ts.isTypeReferenceNode(type)) {
-		const name = type.typeName.getText(sf);
-		const decl = sf.statements.find(
-			(s): s is ts.InterfaceDeclaration | ts.TypeAliasDeclaration =>
-				(ts.isInterfaceDeclaration(s) || ts.isTypeAliasDeclaration(s)) && s.name.text === name
-		);
-		// Props may be declared inside `$$render()` (instance script): search the whole file.
-		const inner = decl ?? findDeclDeep(sf, name);
-		if (inner && ts.isInterfaceDeclaration(inner)) {
-			// A base interface declared in the same file (`interface Own`) is part of the component's
-			// own contract: inline its members. Anything else (`Omit<HTMLAttributes>`) is `extends`.
-			const inherited: ts.TypeElement[] = [];
-			const external: string[] = [];
-			for (const h of inner.heritageClauses ?? [])
-				for (const t of h.types) {
-					const base = ts.isIdentifier(t.expression)
-						? findDeclDeep(sf, t.expression.text)
-						: undefined;
-					const picked = layoutPick(t);
-					if (picked) inherited.push(...picked);
-					else if (base && ts.isInterfaceDeclaration(base) && !t.typeArguments)
-						inherited.push(...base.members);
-					else external.push(t.getText(sf));
-				}
-			members = [...inherited, ...inner.members];
-			ext = external.join(", ") || undefined;
-		} else if (inner && ts.isTypeAliasDeclaration(inner)) {
-			const t = inner.type;
-			if (ts.isTypeLiteralNode(t)) members = t.members;
-			else if (ts.isUnionTypeNode(t)) return resolveUnion(sf, t);
-			else if (ts.isIntersectionTypeNode(t)) {
-				const own: ts.TypeElement[] = [];
-				const rest: string[] = [];
-				for (const part of t.types) {
-					const polymorphic = polymorphicOwn(part);
-					if (ts.isTypeLiteralNode(part)) own.push(...part.members);
-					else if (polymorphic) {
-						own.push(...polymorphic);
-						rest.push("PolymorphicAttributes<T>");
-					} else if (ts.isTypeReferenceNode(part) && isLocalInterface(sf, part)) {
-						own.push(...resolvePropsType(sf, part).members);
-					} else rest.push(part.getText(sf));
-				}
-				members = own;
-				ext = rest.join(" & ") || undefined;
-			} else ext = t.getText(sf);
-		}
-	}
-	return { members, ext };
-}
-
-/**
- * `type Props = A | B` (a component whose element changes with a prop, e.g. Button on `href`):
- * the documented props are those declared by the FIRST branch (the default rendering, with its
- * JSDoc), made optional when a later branch leaves them out or optional, and the attribute sets of
- * every branch are reported as `extends` so a reader sees all the native attributes that pass through.
- */
-function resolveUnion(sf: ts.SourceFile, union: ts.UnionTypeNode): PropsMembers {
-	const branches = union.types.map((t) => resolvePropsType(sf, t));
-	const named = (m: ts.TypeElement) =>
-		ts.isPropertySignature(m) && m.name ? propName(m.name) : "";
-	// One entry per prop: the first declaration wins (the shared base, with its docs); a later
-	// branch only narrows it (`href?: undefined`, `type?: 'button' | ...`).
-	const byName = new Map<string, ts.TypeElement>();
-	for (const b of branches)
-		for (const m of b.members) if (named(m) && !byName.has(named(m))) byName.set(named(m), m);
-	const ext = [...new Set(branches.map((b) => b.ext).filter(Boolean))].join(" | ");
-	return { members: [...byName.values()], ext: ext || undefined };
-}
-
-/** A reference to an interface declared in the same component script (its members are the component's own props). */
-function isLocalInterface(sf: ts.SourceFile, ref: ts.TypeReferenceNode) {
-	if (ref.typeArguments) return false;
-	const d = findDeclDeep(sf, ref.typeName.getText(sf));
-	return !!d && ts.isInterfaceDeclaration(d);
-}
-
-function findDeclDeep(sf: ts.SourceFile, name: string) {
-	let hit: ts.InterfaceDeclaration | ts.TypeAliasDeclaration | undefined;
-	const visit = (n: ts.Node) => {
-		if (hit) return;
-		if ((ts.isInterfaceDeclaration(n) || ts.isTypeAliasDeclaration(n)) && n.name.text === name)
-			hit = n;
-		else ts.forEachChild(n, visit);
-	};
-	visit(sf);
-	return hit;
-}
-
-/** `'a' | 'b' | 2 | number`: a union whose members are all literals or the `string`/`number` keywords. */
-function literalUnionText(type: ts.TypeNode, sf: ts.SourceFile): string | undefined {
-	if (!ts.isUnionTypeNode(type)) return undefined;
-	const ok = type.types.every(
-		(t) =>
-			(ts.isLiteralTypeNode(t) && t.literal.kind !== ts.SyntaxKind.NullKeyword) ||
-			t.kind === ts.SyntaxKind.StringKeyword ||
-			t.kind === ts.SyntaxKind.NumberKeyword
-	);
-	return ok ? oneLine(type.getText(sf)) : undefined;
-}
-
-/** Declaration of `name` (an alias) in `sf` or, when it is imported from a relative module, in that file. */
-function findAliasType(
-	sf: ts.SourceFile,
-	dir: string,
-	name: string,
-	depth = 0
-): { type: ts.TypeNode; sf: ts.SourceFile } | undefined {
-	const local = findDeclDeep(sf, name);
-	if (local && ts.isTypeAliasDeclaration(local)) return { type: local.type, sf };
-	if (depth > 2) return undefined;
-	for (const st of sf.statements) {
-		if (!ts.isImportDeclaration(st) || !ts.isStringLiteral(st.moduleSpecifier)) continue;
-		const spec = st.moduleSpecifier.text;
-		if (!spec.startsWith(".")) continue;
-		const named = st.importClause?.namedBindings;
-		if (!named || !ts.isNamedImports(named)) continue;
-		const el = named.elements.find((e) => e.name.text === name);
-		if (!el) continue;
-		const base = resolve(dir, spec.replace(/\.js$/, ""));
-		const file = [`${base}.ts`, join(base, "index.ts")].find((f) => existsSync(f));
-		if (!file) return undefined;
-		const other = ts.createSourceFile(
-			file,
-			readFileSync(file, "utf8"),
-			ts.ScriptTarget.ESNext,
-			true
-		);
-		return findAliasType(other, dirname(file), (el.propertyName ?? el.name).text, depth + 1);
-	}
-	return undefined;
-}
-
-/**
- * A prop typed with a bare alias (`shape?: Shape`) hides its values from the reader. When the alias
- * is a union of literals, show the union. Objects, arrays, generics and external types stay as written.
- */
-function expandLiteralAlias(sf: ts.SourceFile, dir: string, type: string): string {
-	if (!/^[A-Z]\w*$/.test(type)) return type;
-	const hit = findAliasType(sf, dir, type);
-	return (hit && literalUnionText(hit.type, hit.sf)) ?? type;
-}
-
-/** Prose of a `/** ... *\/` block before its first `@tag`, flattened to one paragraph. */
-function docProse(block: string): string | undefined {
-	const lines = block
-		.replace(/^\/\*\*|\*\/$/g, "")
-		.split("\n")
-		.map((l) => l.replace(/^\s*\*?\s?/, "").trimEnd());
-	const tag = lines.findIndex((l) => /^@\w+/.test(l.trim()));
-	const prose = (tag < 0 ? lines : lines.slice(0, tag)).join("\n").split(/\n\s*\n/)[0];
-	return prose.replace(/\n/g, " ").trim() || undefined;
-}
-
-/**
- * Component-level description: a top-level `/** ... *\/` block of a `<script>` that is detached from
- * the declaration below it (blank line between) or that opens the script right before an import.
- * JSDoc on a declaration (`/** doc *\/ interface Props`, a member of `Props`, a `let` destructure)
- * describes that declaration, never the component. Blocks with no prose (`@deprecated ...`) are skipped.
- */
-export function componentDoc(src: string): string | undefined {
-	for (const script of src.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/g)) {
-		const body = script[1];
-		const sf = ts.createSourceFile("c.ts", body, ts.ScriptTarget.ESNext, true);
-		const stops = [...sf.statements.map((s) => s.getFullStart()), sf.endOfFileToken.getFullStart()];
-		for (const [i, full] of stops.entries()) {
-			const next = sf.statements[i];
-			for (const c of ts.getLeadingCommentRanges(body, full) ?? []) {
-				const text = body.slice(c.pos, c.end);
-				if (!text.startsWith("/**")) continue;
-				const gap = body.slice(c.end, next ? next.getStart(sf) : body.length);
-				const attached =
-					next !== undefined && !/\n[ \t]*\n/.test(gap) && !ts.isImportDeclaration(next);
-				if (attached) continue;
-				const prose = docProse(text);
-				if (prose) return prose;
-			}
-		}
-	}
-	return undefined;
-}
-
-/**
- * Text after `@deprecated` in a top-level `/** ... *\/` block of a `<script>` (the replacement to use), or
- * undefined. A `@deprecated` on a prop or declaration inside the component does not deprecate the component.
- */
-export function componentDeprecated(src: string): string | undefined {
-	for (const script of src.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/g)) {
-		const body = script[1];
-		const sf = ts.createSourceFile("c.ts", body, ts.ScriptTarget.ESNext, true);
-		const first = sf.statements[0];
-		const ranges = ts.getLeadingCommentRanges(body, first ? first.getFullStart() : 0) ?? [];
-		for (const c of ranges) {
-			const text = body.slice(c.pos, c.end);
-			if (!text.startsWith("/**")) continue;
-			const lines = text
-				.replace(/^\/\*\*|\*\/$/g, "")
-				.split("\n")
-				.map((l) => l.replace(/^\s*\*?\s?/, "").trimEnd());
-			const at = lines.findIndex((l) => /^@deprecated\b/.test(l.trim()));
-			if (at < 0) continue;
-			const rest = lines.slice(at);
-			const end = rest.findIndex((l, i) => i > 0 && (/^@\w+/.test(l.trim()) || l.trim() === ""));
-			return rest
-				.slice(0, end < 0 ? undefined : end)
-				.join(" ")
-				.replace(/^@deprecated\s*/, "")
-				.replace(/\s+/g, " ")
-				.trim();
-		}
-	}
-	return undefined;
-}
-
-function extractComponent(name: string, file: string, entry: string): ManifestComponent {
-	const abs = join(LIB, file);
-	const src = readFileSync(abs, "utf8");
-	const out: ManifestComponent = {
-		name,
-		import: entry,
-		source: file,
-		props: [],
-		snippets: [],
-		classes: [],
-		styling: { parts: [], variables: [], data: [] },
-		tokens: [],
-	};
-	const css = componentCss(src, dirname(abs));
-	out.styling = extractStyling(css, src, globalTokens());
-	out.classes = out.styling.parts.filter((p) => p.stable).map((p) => p.name);
-	out.tokens = extractComponentTokens(css, out.classes);
-
-	const generics = src.match(/<script[^>]*\bgenerics="([^"]+)"/)?.[1];
-	if (generics) out.generics = generics;
-
-	let code: string;
-	try {
-		code = svelte2tsx(src, { filename: abs, isTsFile: true, mode: "ts", version: "5.57.0" }).code;
-	} catch (e) {
-		throw new Error(`svelte2tsx failed for ${file}: ${(e as Error).message}`);
-	}
-	const sf = ts.createSourceFile(
-		`${abs}.tsx`,
-		code,
-		ts.ScriptTarget.ESNext,
-		true,
-		ts.ScriptKind.TSX
-	);
-	const decl = findPropsDecl(sf);
-	if (!decl) return out;
-
-	const defaults = readDefaults(decl, sf);
-	const { members, ext } = resolvePropsType(sf, decl.type);
-	if (ext) out.extends = ext;
-
-	for (const m of members) {
-		if (!ts.isPropertySignature(m) || !m.name) continue;
-		const written = m.type?.getText(m.getSourceFile()).replace(/\s+/g, " ") ?? "unknown";
-		const type = expandLiteralAlias(sf, dirname(abs), written);
-		const d = defaults.get(propName(m.name));
-		const prop: ManifestProp = {
-			name: propName(m.name),
-			type,
-			optional: !!m.questionToken,
-		};
-		if (d?.text !== undefined && d.text !== "undefined") prop.default = d.text;
-		if (d?.bindable) prop.bindable = true;
-		const doc = jsDoc(m);
-		if (doc) prop.description = doc;
-		(/^\(?\s*Snippet\b/.test(type) ? out.snippets : out.props).push(prop);
-	}
-
-	const description = componentDoc(src);
-	if (description) out.description = description;
-	const deprecated = componentDeprecated(src);
-	if (deprecated) out.deprecated = deprecated;
-	return out;
-}
-
-/** CSS text of a component: its `<style>` blocks plus every local `.css` it imports. */
-function componentCss(src: string, dir: string): string {
-	const css = [...src.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/g)].map((m) => m[1]);
-	for (const m of src.matchAll(/import\s+['"](\.[^'"]+\.css)['"]/g)) {
-		const file = join(dir, m[1]);
-		if (existsSync(file)) css.push(readFileSync(file, "utf8"));
-	}
-	return css.join("\n");
-}
-
-/** Public `ca-*` class names a component's own CSS defines (descendant `:global()` targets owned elsewhere are skipped). */
-export function extractClasses(css: string): string[] {
-	const classes = new Set<string>();
-	for (const rule of css.replace(/\/\*[\s\S]*?\*\//g, "").matchAll(/([^{}]+)\{/g))
-		for (const part of rule[1].split(",")) {
-			// A selector that starts with `:global(` (or `:global .x`) is the component's own global class.
-			const sel = part.trim();
-			const owned = sel.startsWith(":global") ? sel : sel.replace(/:global\([^)]*\)/g, "");
-			for (const c of owned.matchAll(/\.(ca-[A-Za-z0-9_-]+)/g)) classes.add(c[1]);
-		}
-	return [...classes].sort();
-}
-
-/** A private class: `ca-x-` prefix, so a reader sees it is not a hook (naming rule, #381). */
-const INTERNAL_CLASS = /^ca-x-/;
-
-/** Every `--ca-*` the global stylesheets declare: these are tokens, documented in tokens.json. */
-let tokenNames: Set<string> | undefined;
-function globalTokens(): Set<string> {
-	if (tokenNames) return tokenNames;
-	tokenNames = new Set();
-	const walk = (dir: string) => {
-		for (const e of readdirSync(dir, { withFileTypes: true })) {
-			if (e.isDirectory()) walk(join(dir, e.name));
-			else if (e.name.endsWith(".css"))
-				for (const m of readFileSync(join(dir, e.name), "utf8").matchAll(/(--ca-[\w-]+)\s*:/g))
-					tokenNames?.add(m[1]);
-		}
-	};
-	walk(join(LIB, "styles"));
-	return tokenNames;
-}
-
-/** `data-*` hooks a component CSS selects on, with the values it styles (`[data-size='sm']`). */
-export function extractDataAttributes(css: string): ManifestDataAttribute[] {
-	const found = new Map<string, Set<string>>();
-	for (const m of css
-		.replace(/\/\*[\s\S]*?\*\//g, "")
-		.matchAll(/\[(data-[a-z][a-z0-9-]*)(?:[~|^$*]?=(?:'([^']*)'|"([^"]*)"|([^\]\s]+)))?\s*\]/g)) {
-		const values = found.get(m[1]) ?? new Set<string>();
-		const v = m[2] ?? m[3] ?? m[4];
-		if (v !== undefined) values.add(v);
-		found.set(m[1], values);
-	}
-	return [...found]
-		.sort(([a], [b]) => a.localeCompare(b))
-		.map(([name, values]) => ({ name, values: [...values].sort() }));
-}
-
-/**
- * The override surface of a component: classes (stable unless `ca-x-` or a `@keyframes` name), the
- * component-scoped custom properties it declares or reads (`tokens` are excluded: they live in tokens.json)
- * and the `data-*` attributes its CSS selects on.
- */
-export function extractStyling(
-	css: string,
-	_source: string,
-	tokens = new Set<string>()
-): ManifestStyling {
-	const bare = css.replace(/\/\*[\s\S]*?\*\//g, "");
-	const keyframes = [...bare.matchAll(/@keyframes\s+(ca-[A-Za-z0-9_-]+)/g)].map((m) => m[1]);
-	const names = new Set([...extractClasses(css), ...keyframes]);
-	// Plain code-unit order, like `extractClasses`: `classes` (the stable subset) keeps its historical order.
-	const parts = [...names]
-		.sort()
-		.map((name) => ({ name, stable: !INTERNAL_CLASS.test(name) && !keyframes.includes(name) }));
-	const variables = [
-		...new Set(
-			[...bare.matchAll(/(--ca-[\w-]+)\s*:|var\(\s*(--ca-[\w-]+)/g)]
-				.map((m) => m[1] ?? m[2])
-				.filter((v) => !tokens.has(v))
-		),
-	].sort();
-	return { parts, variables, data: extractDataAttributes(css) };
-}
-
-/**
- * Component tokens of a component's own CSS: `var(--ca-<stem>-…, fallback)` reads, where `<stem>` is
- * the stem of one of its classes (`ca-icon-btn--sm` → `icon-btn`). The fallback marks an override
- * hook: a token read without one is a global token owned elsewhere (`--ca-space-3`).
- */
-export function extractComponentTokens(css: string, classes: string[]): string[] {
-	const stems = new Set(classes.map((c) => c.slice(3).split(/--|__/)[0]));
-	const tokens = new Set<string>();
-	for (const m of css.replace(/\/\*[\s\S]*?\*\//g, "").matchAll(/var\((--ca-([a-z0-9-]+?))\s*,/g))
-		if ([...stems].some((s) => m[2] === s || m[2].startsWith(`${s}-`))) tokens.add(m[1]);
-	return [...tokens].sort();
-}
-
-// ── non-component exports ─────────────────────────────────────────────────────
-
-/** Prose before the first `@tag` of the JSDoc attached to a declaration (a variable's doc sits on its statement). */
-function exportDoc(decl: ts.Declaration, sf: ts.SourceFile): string | undefined {
-	let node: ts.Node = decl;
-	if (ts.isBindingElement(node)) {
-		while (!ts.isVariableDeclaration(node)) node = node.parent;
-	}
-	if (ts.isVariableDeclaration(node)) node = node.parent.parent;
-	const own = ts.getJSDocCommentsAndTags(node).find(ts.isJSDoc);
-	if (own)
-		return docProse(
-			own
-				.getText(sf)
-				.replace(/^\/\*\*|\*\/$/g, "")
-				.replace(/^\s*\* ?/gm, "")
-		);
-	return undefined;
-}
-
-const oneLine = (s: string) => s.replace(/\s+/g, " ").trim();
-
-/** Fields of an interface or object type alias, with the JSDoc of each. Methods and index signatures are kept as written. */
-function exportMembers(
-	decl: ts.Declaration,
-	sf: ts.SourceFile
-): ManifestExportMember[] | undefined {
-	let elements: readonly ts.TypeElement[] | undefined;
-	if (ts.isInterfaceDeclaration(decl)) elements = decl.members;
-	else if (ts.isTypeAliasDeclaration(decl) && ts.isTypeLiteralNode(decl.type))
-		elements = decl.type.members;
-	if (!elements?.length) return undefined;
-	const out: ManifestExportMember[] = [];
-	for (const m of elements) {
-		if (!ts.isPropertySignature(m) && !ts.isMethodSignature(m)) continue;
-		const doc = ts.getJSDocCommentsAndTags(m).find(ts.isJSDoc);
-		const description = doc
-			? docProse(
-					doc
-						.getText(sf)
-						.replace(/^\/\*\*|\*\/$/g, "")
-						.replace(/^\s*\* ?/gm, "")
-				)
-			: undefined;
-		const type = ts.isPropertySignature(m)
-			? oneLine(m.type?.getText(sf) ?? "unknown")
-			: `(${m.parameters.map((p) => p.getText(sf)).join(", ")}) => ${oneLine(m.type?.getText(sf) ?? "void")}`;
-		out.push({
-			name: propName(m.name),
-			type,
-			optional: !!m.questionToken,
-			...(description ? { description } : {}),
-		});
-	}
-	return out.length ? out : undefined;
-}
-
-const TYPE_FLAGS =
-	ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
-
-/** `name?: Type` for one parameter: no default value; an unannotated parameter shows its inferred type. */
-function paramSignature(
-	p: ts.ParameterDeclaration,
-	sf: ts.SourceFile,
-	checker: ts.TypeChecker
-): string {
-	const type = p.type
-		? oneLine(p.type.getText(sf))
-		: oneLine(checker.typeToString(checker.getTypeAtLocation(p), p, TYPE_FLAGS));
-	const name = ts.isIdentifier(p.name) ? p.name.text : "options";
-	const dots = p.dotDotDotToken ? "..." : "";
-	return `${dots}${name}${p.questionToken || p.initializer ? "?" : ""}: ${type}`;
-}
-
-/** Declaration as one line without bodies, initializers, default values or comments. */
-function exportSignature(
-	name: string,
-	decl: ts.Declaration,
-	sf: ts.SourceFile,
-	checker: ts.TypeChecker
-): { kind: ExportKind; signature: string } {
-	if (ts.isFunctionDeclaration(decl)) {
-		const tp = decl.typeParameters
-			? `<${decl.typeParameters.map((t) => t.getText(sf)).join(", ")}>`
-			: "";
-		const sig = checker.getSignatureFromDeclaration(decl);
-		if (!decl.type && !sig) throw new Error(`cannot resolve the signature of ${name}`);
-		const ret = decl.type
-			? oneLine(decl.type.getText(sf))
-			: checker.typeToString(
-					checker.getReturnTypeOfSignature(sig as ts.Signature),
-					decl,
-					TYPE_FLAGS
-				);
-		const params = decl.parameters.map((p) => paramSignature(p, sf, checker)).join(", ");
-		return { kind: "function", signature: `function ${name}${tp}(${params}): ${oneLine(ret)}` };
-	}
-	if (ts.isInterfaceDeclaration(decl) || ts.isTypeAliasDeclaration(decl)) {
-		const text = decl
-			.getText(sf)
-			.replace(/\/\*[\s\S]*?\*\//g, "")
-			.replace(/\s\/\/.*$/gm, "")
-			.replace(/^export\s+/, "");
-		return { kind: "type", signature: oneLine(text) };
-	}
-	if (ts.isClassDeclaration(decl)) return { kind: "class", signature: `class ${name}` };
-	if (ts.isVariableDeclaration(decl) || ts.isBindingElement(decl)) {
-		const type = checker.getTypeAtLocation(decl);
-		const init = ts.isVariableDeclaration(decl) ? decl.initializer : undefined;
-		// `.svelte.ts` rune singletons (`const x = createXStore()`) expose getters + methods: report them as stores.
-		const store = /^create\w*Store\(/.test(init?.getText(sf) ?? "");
-		return {
-			kind: store ? "store" : "const",
-			signature: `const ${name}: ${constType(type, decl, checker)}`,
-		};
-	}
-	return { kind: "const", signature: name };
-}
-
-/** Getter without a setter, or a member declared `readonly` (an `as const` literal's properties are). */
-function isReadonlyMember(d: ts.Declaration): boolean {
-	if (ts.isGetAccessor(d)) {
-		const siblings = ts.isObjectLiteralExpression(d.parent)
-			? d.parent.properties
-			: d.parent.members;
-		return !siblings.some((m) => ts.isSetAccessor(m) && m.name.getText() === d.name.getText());
-	}
-	return (ts.getCombinedModifierFlags(d) & ts.ModifierFlags.Readonly) !== 0;
-}
-
-/** Longest one-line type shown as is; object types beyond it list one `name: type` member per line. */
-const MAX_TYPE = 100;
-
-/** A type as text: one line when short, otherwise an object type split one member per line. */
-function constType(type: ts.Type, at: ts.Node, checker: ts.TypeChecker): string {
-	const full = oneLine(checker.typeToString(type, at, TYPE_FLAGS));
-	if (full.length <= MAX_TYPE) return full;
-	const props = type.getProperties();
-	if (!props.length || !(type.flags & ts.TypeFlags.Object) || type.getCallSignatures().length)
-		return full;
-	const members = props.map((p) => {
-		const t = checker.getTypeOfSymbolAtLocation(p, at);
-		const text = oneLine(checker.typeToString(t, at, TYPE_FLAGS));
-		const readonly = !!p.declarations?.length && p.declarations.every(isReadonlyMember);
-		return `  ${readonly ? "readonly " : ""}${p.name}: ${text.length > MAX_TYPE ? `${text.slice(0, MAX_TYPE - 1)}…` : text};`;
-	});
-	return `{\n${members.join("\n")}\n}`;
-}
-
-/** Every export of every entry that is not a component and is declared in this package. */
-export function extractExports(components: ManifestComponent[]): ManifestExport[] {
-	const files = Object.values(API_ENTRIES).map((f) => join(LIB, f));
-	const program = ts.createProgram(files, {
-		target: ts.ScriptTarget.ESNext,
-		module: ts.ModuleKind.ESNext,
-		moduleResolution: ts.ModuleResolutionKind.Bundler,
-		allowImportingTsExtensions: true,
-		skipLibCheck: true,
-		noEmit: true,
-		types: [],
-	});
-	const checker = program.getTypeChecker();
-	const component = new Set(components.map((c) => `${c.import}:${c.name}`));
-	const out: ManifestExport[] = [];
-	for (const [entry, file] of Object.entries(API_ENTRIES)) {
-		const sf = program.getSourceFile(join(LIB, file));
-		const mod = sf && checker.getSymbolAtLocation(sf);
-		if (!mod) throw new Error(`cannot resolve entry ${file}`);
-		for (const exported of checker.getExportsOfModule(mod)) {
-			if (component.has(`${entry}:${exported.name}`)) continue;
-			const target =
-				exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
-			const decl = target.declarations?.[0];
-			const declFile = decl?.getSourceFile();
-			// Foreign (`@internationalized/date`, `clsx`, svelte) symbols are not this package's API.
-			if (
-				!decl ||
-				!declFile ||
-				declFile.fileName.includes("node_modules") ||
-				declFile.fileName.endsWith(".svelte")
-			)
-				continue;
-			const { kind, signature } = exportSignature(exported.name, decl, declFile, checker);
-			const description = exportDoc(decl, declFile);
-			const members = exportMembers(decl, declFile);
-			out.push({
-				name: exported.name,
-				import: entry,
-				kind,
-				signature,
-				...(description ? { description } : {}),
-				...(members ? { members } : {}),
-				source: relative(LIB, declFile.fileName),
-			});
-		}
-	}
-	return out.sort((a, b) => a.import.localeCompare(b.import) || a.name.localeCompare(b.name));
-}
-
-// ── main ──────────────────────────────────────────────────────────────────────
-
-export function buildManifest(): Manifest {
-	const found: Found[] = [];
-	for (const [entry, file] of Object.entries(API_ENTRIES)) collectExports(file, entry, found);
-	const seen = new Set<string>();
-	const components: ManifestComponent[] = [];
-	for (const f of found) {
-		const key = `${f.entry}:${f.name}`;
-		if (seen.has(key)) continue;
-		seen.add(key);
-		components.push(extractComponent(f.name, f.file, f.entry));
-	}
-	components.sort((a, b) => a.name.localeCompare(b.name));
-	const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
-	return { name: pkg.name, version: pkg.version, components, exports: extractExports(components) };
-}
-
-// ── tokens ────────────────────────────────────────────────────────────────────
-
-export interface ManifestToken {
-	name: string;
-	/** Value in `:root` (light / default). */
-	value: string;
-	/** Value under `.dark`, when it differs. */
-	dark?: string;
-	/** Where it is defined: `tokens.css` or `presets/<id>.css`. */
-	source: string;
-	/** Nearest preceding section comment, e.g. "Spacing scale". */
-	group?: string;
-	/** Comment immediately above the declaration: what the token is for and its guarantees. */
-	description?: string;
-}
-
-/** `── Spacing scale (base 4 px) ──` section dividers inside CSS comments. */
-const SECTION = /^\s*──\s*([^─(\n*]+?)\s*(?:\(|─|\*|$)/m;
-
-/** Parse `--ca-*: value;` declarations per rule, keeping `:root` and `.dark` values apart. */
-export function extractTokens(css: string, source: string, out: Map<string, ManifestToken>) {
-	let group: string | undefined;
-	for (const rule of css.matchAll(/(?:\/\*[\s\S]*?\*\/\s*)*([^{}/]+)\{([^{}]*)\}/g)) {
-		const selector = rule[1].trim();
-		// `.dark` rules (also `.dark[data-preset=..]`, `.dark [data-preset=..]`) fill the dark value.
-		const isDark = /\.dark\b|data-theme-scope="dark"/.test(selector);
-		// Walk the body so section comments between declarations update `group` in order.
-		let note: string | undefined;
-		for (const t of rule[2].matchAll(/\/\*([\s\S]*?)\*\/|(--ca-[\w-]+)\s*:\s*([^;]+);/g)) {
-			if (t[1] !== undefined) {
-				const section = t[1].match(SECTION)?.[1];
-				if (section) group = section;
-				// A prose comment (not a `── Section ──` divider) documents the declaration right below it.
-				else note = t[1].replace(/\s*\n\s*\*?\s*/g, " ").trim() || undefined;
-				continue;
-			}
-			const description = note;
-			note = undefined;
-			const name = t[2];
-			const value = t[3]
-				.trim()
-				.replace(/\s+/g, " ")
-				.replace(/\s*\/\*[\s\S]*?\*\//g, "");
-			const prev = out.get(name);
-			if (!prev) {
-				const t0: ManifestToken = isDark
-					? { name, value: "", dark: value, source, group }
-					: { name, value, source, group };
-				if (description) t0.description = description;
-				out.set(name, t0);
-			} else {
-				if (isDark) prev.dark ??= value;
-				else if (prev.value === "") prev.value = value;
-				if (description) prev.description ??= description;
-			}
-		}
-	}
-}
-
-export function buildTokens(): ManifestToken[] {
-	const out = new Map<string, ManifestToken>();
-	const styles = join(LIB, "styles");
-	extractTokens(readFileSync(join(styles, "tokens.css"), "utf8"), "tokens.css", out);
-	// Built-ins repeat the same names per preset; the amber file (`:root` default) is the canonical value.
-	const presets = join(styles, "presets");
-	extractTokens(readFileSync(join(presets, "amber.css"), "utf8"), "presets/amber.css", out);
-	return [...out.values()].sort((a, b) => a.name.localeCompare(b.name));
-}
-
-// ── surfaces ──────────────────────────────────────────────────────────────────
-
-export interface ManifestSurface {
-	/** Value of `<html data-style>` (and `colorScheme.setStyle`). */
-	id: SurfaceStyle;
-	/** The comment above the `[data-style="id"]` block in materials.css. */
-	description?: string;
-	/**
-	 * What the style does to every `--ca-blur-*` token: `full` leaves the `:root` glass blur,
-	 * `reduced` rewrites it to a lighter blur, `none` turns it off (opaque surfaces).
-	 */
-	blur: "full" | "reduced" | "none";
-	/** Every custom property the `[data-style]` blocks of this id rewrite, in first-seen order. */
-	tokens: string[];
-	/** The package default (`defineTheme` without `defaultStyle`). */
-	packageDefault: boolean;
-	/** Design recipes (`designStyle(id)`) whose `defaultStyle` is this one. */
-	recipes: string[];
-}
-
-/** `[data-style="x"]` selectors of a rule, with or without a `.dark`/`html` prefix. */
-const STYLE_SELECTOR = /\[data-style="([a-z]+)"\]/g;
-const BLUR_TOKEN = /^--ca-(?:blur-[a-z-]+|(?:overlay|panel|chrome|upload)-blur)$/;
-
-/** Read the surface styles out of `[data-style]` rules: blur behaviour, rewritten tokens, description. */
-export function extractSurfaces(
-	css: string
-): Pick<ManifestSurface, "id" | "description" | "blur" | "tokens">[] {
-	const acc = new Map<
-		string,
-		{ description?: string; own?: boolean; tokens: Map<string, string> }
-	>();
-	for (const rule of css.matchAll(/((?:\/\*[\s\S]*?\*\/\s*)*)([^{}/]+)\{([^{}]*)\}/g)) {
-		const ids = [...rule[2].matchAll(STYLE_SELECTOR)].map((m) => m[1]);
-		if (!ids.length) continue;
-		// The nearest comment above the block: `── Solid — opaque, no blur ── ` → "Solid — opaque, no blur".
-		const note = [...rule[1].matchAll(/\/\*([\s\S]*?)\*\//g)].pop()?.[1];
-		const description = note
-			?.replace(/^[\s*─-]*|[\s*─-]*$/g, "")
-			.replace(/\s*\n\s*\*?\s*/g, " ")
-			.replace(/\s*─+.*$/, "")
-			.trim();
-		const decls = [...rule[3].matchAll(/(--ca-[\w-]+)\s*:\s*([^;]+);/g)];
-		for (const id of ids) {
-			const cur = acc.get(id) ?? { tokens: new Map<string, string>() };
-			// A style's own block comment beats the comment of a grouped rule that lists it with others.
-			if (description && (cur.description === undefined || (ids.length === 1 && !cur.own))) {
-				cur.description = description;
-				cur.own = ids.length === 1;
-			}
-			for (const d of decls) if (!cur.tokens.has(d[1])) cur.tokens.set(d[1], d[2].trim());
-			acc.set(id, cur);
-		}
-	}
-	return [...acc].map(([id, v]) => {
-		const blurs = [...v.tokens].filter(([name]) => BLUR_TOKEN.test(name));
-		const blur = !blurs.length
-			? "full"
-			: blurs.every(([, value]) => value === "none")
-				? "none"
-				: "reduced";
-		return {
-			id: id as SurfaceStyle,
-			description: v.description,
-			blur,
-			tokens: [...v.tokens.keys()],
-		};
-	});
-}
-
-/** Styles with no `[data-style]` block: glass is the `:root` token set every other style rewrites (it is opt-in; the package default is solid). */
-const GLASS_DESCRIPTION: Partial<Record<SurfaceStyle, string>> = {
-	glass:
-		"Glass (opt-in): the :root tokens untouched, full blur, translucent tints, glow and rim (the look of the liquid recipe)",
-};
-
-/**
- * Every surface style, from `materials.css`: the `[data-style]` blocks give the blur and the tokens,
- * `STYLES` gives the valid ids (glass is the `:root` set, it has no block), `DESIGN_STYLES` the recipes.
- */
-export function buildSurfaces(): ManifestSurface[] {
-	const found = new Map(
-		extractSurfaces(readFileSync(join(LIB, "styles/materials.css"), "utf8")).map((s) => [s.id, s])
-	);
-	return STYLES.map((id) => {
-		const f = found.get(id);
-		const description = f?.description ?? GLASS_DESCRIPTION[id];
-		return {
-			id,
-			...(description ? { description } : {}),
-			blur: f?.blur ?? "full",
-			tokens: f?.tokens ?? [],
-			packageDefault: id === "solid",
-			recipes: Object.values(DESIGN_STYLES)
-				.filter((d) => (d.theme.defaultStyle ?? "solid") === id)
-				.map((d) => d.id),
-		};
-	});
-}
-
-// ── guides ────────────────────────────────────────────────────────────────────
-
-export interface ManifestGuide {
-	/** Path under docs, e.g. `inputs/button`. */
-	slug: string;
-	title: string;
-	group: string;
-	description: string;
-	markdown: string;
-}
-
-const DOCS_DIR = resolve(ROOT, "../../site/src/content/docs");
-
-function mdxFiles(dir: string): string[] {
-	return readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
-		e.isDirectory()
-			? mdxFiles(join(dir, e.name))
-			: e.name.endsWith(".mdx")
-				? [join(dir, e.name)]
-				: []
-	);
-}
-
-/** Raw demo source under site/src/demos, or undefined (also for paths that escape that folder). */
-function readDemo(demoPath: string): string | undefined {
-	const root = resolve(ROOT, "../../site/src/demos");
-	const file = resolve(root, demoPath);
-	return file.startsWith(`${root}/`) && existsSync(file) ? readFileSync(file, "utf8") : undefined;
-}
-
-export function buildGuides(): ManifestGuide[] {
-	if (!existsSync(DOCS_DIR)) return [];
-	return mdxFiles(DOCS_DIR)
-		.map((file) => {
-			const raw = readFileSync(file, "utf8");
-			const fm = raw.match(/^---\n([\s\S]*?)\n---\n/);
-			const field = (k: string) =>
-				fm?.[1].match(new RegExp(`^${k}:\\s*(.+)$`, "m"))?.[1].replace(/^["']|["']$/g, "") ?? "";
-			return {
-				slug: relative(DOCS_DIR, file)
-					.replaceAll("\\", "/")
-					.replace(/\.mdx$/, ""),
-				title: field("title"),
-				group: field("group"),
-				description: field("description"),
-				markdown: mdxToMarkdown(fm ? raw.slice(fm[0].length) : raw, demoSources(raw, readDemo)),
-			};
-		})
-		.sort((a, b) => a.slug.localeCompare(b.slug));
-}
-
-/** Recipes of the "Recipes" docs page (one per `## ` section with an example), for the offline `get_recipe`. */
-export function buildRecipes(guides = buildGuides()): Recipe[] {
-	const page = guides.find((g) => g.slug === ENTRY_PAGES.recipes);
-	return page ? parseRecipes(page.markdown) : [];
-}
-
-// ── demos (ca-prompt catalog) ─────────────────────────────────────────────────
-
-/** One animated property of a motion demo: literal values, each of which must appear verbatim in the demo source. */
-export interface ManifestMotion {
-	property: string;
-	duration: string;
-	easing: string;
-	delay?: string;
-	stagger?: string;
-	spring?: string;
-}
-
-export interface ManifestDemo {
-	id: string;
-	group: string;
-	page: string;
-	variant: string;
-	slug: string;
-	title: string;
-	description: string;
-	summary: string;
-	use: string;
-	spec: string[];
-	tags: string[];
-	/** Motion vocabulary: first = canonical name, the rest are aliases (other languages included). */
-	names?: string[];
-	/** Exact timing of the motion, printed in e/ and p/ so an AI never guesses it. */
-	motion?: ManifestMotion[];
-	shape: "square" | "wide" | "tall";
-	/** Index facets of the sidecar (`index.json`, `/gallery/<id>.md`). */
-	index: IndexFacets;
-	components: string[];
-	imports: { from: string; names: string[] }[];
-	interactive: boolean;
-	/** Live demo URL on the docs site. */
-	demo: string;
-	source: string;
-	needs: string;
-}
-
-const DEMOS_DIR = resolve(ROOT, "../../site/src/demos");
-const SITE = "https://ui.codeatlas.com.br";
-const API = `${SITE}/api/v1`;
-/** Shared building blocks under site/src/demos that are not demos themselves. */
-export const HELPERS = [
-	"foundation/colors/Swatches",
-	"foundation/typography/TypeRows",
-	"navigation/loading-boundary/Report",
-];
-const PEERS: Record<string, string> = {
-	[`${PKG}/charts`]: "echarts",
-	[`${PKG}/map`]: "maplibre-gl",
-	[`${PKG}/table`]: "@tanstack/svelte-table",
-	[`${PKG}/code`]: "shiki",
-};
-
-/** `<Demo title description><X client:…>` per demo path, read from every MDX page. */
-function demoUsages() {
-	const out = new Map<string, { title: string; description: string; interactive: boolean }>();
-	if (!existsSync(DOCS_DIR)) return out;
-	for (const file of mdxFiles(DOCS_DIR)) {
-		const raw = readFileSync(file, "utf8");
-		for (const [, name, path] of raw.matchAll(
-			/^import (\w+) from "~\/demos\/([^"?]+)\.svelte";$/gm
-		)) {
-			const tag = raw.match(new RegExp(`<Demo ([^>]*)>\\s*<${name}\\b([^>]*)>`));
-			if (!tag) continue;
-			const attr = (k: string) => tag[1].match(new RegExp(`${k}="([^"]*)"`))?.[1] ?? "";
-			out.set(path, {
-				title: attr("title"),
-				description: attr("description"),
-				interactive: tag[2].includes("client:"),
-			});
-		}
-	}
-	return out;
-}
-
-type DemoMeta = Pick<
-	ManifestDemo,
-	"summary" | "use" | "spec" | "tags" | "shape" | "names" | "motion" | "index"
->;
-
-const META_KEYS: Record<string, true> = {
-	summary: true,
-	use: true,
-	spec: true,
-	tags: true,
-	shape: true,
-	names: true,
-	motion: true,
-	index: true,
-};
-const MOTION_REQUIRED = ["property", "duration", "easing"] as const;
-const MOTION_OPTIONAL = ["delay", "stagger", "spring"] as const;
-const MOTION_KEYS: string[] = [...MOTION_REQUIRED, ...MOTION_OPTIONAL];
-const SHAPES: Record<string, true> = { square: true, wide: true, tall: true };
-const isLines = (v: unknown): v is string[] =>
-	Array.isArray(v) && v.every((s) => typeof s === "string" && s.trim() !== "");
-
-/** Problems of one sidecar against its demo source: shape of every field, and spec tokens quoted from the source. */
-export function checkMeta(
-	meta: unknown,
-	source: string,
-	ctx: { known?: ReadonlySet<string>; ids?: ReadonlySet<string>; self?: string } = {}
-): string[] {
-	if (!meta || typeof meta !== "object" || Array.isArray(meta)) return ["not an object"];
-	const m = meta as Record<string, unknown>;
-	const errors = Object.keys(m)
-		.filter((k) => !META_KEYS[k])
-		.map((k) => `unknown key "${k}"`);
-	for (const k of ["summary", "use"])
-		if (typeof m[k] !== "string" || m[k].trim().length < 12) errors.push(`${k}: sentence required`);
-	if (!isLines(m.spec) || m.spec.length < 1) errors.push("spec: at least one non-empty line");
-	else
-		for (const line of m.spec)
-			for (const [, token] of line.matchAll(/`([^`]+)`/g))
-				if (!source.includes(token)) errors.push(`spec: \`${token}\` is not in the demo source`);
-	if (!isLines(m.tags) || m.tags.length < 2 || m.tags.some((t) => t !== t.toLowerCase()))
-		errors.push("tags: at least 2 lowercase strings");
-	if (typeof m.shape !== "string" || !SHAPES[m.shape]) errors.push("shape: square | wide | tall");
-	if ("names" in m && (!isLines(m.names) || m.names.length < 1))
-		errors.push("names: non-empty strings, at least one");
-	if ("index" in m) errors.push(...checkIndexFacets(m.index, ctx));
-	if ("motion" in m) {
-		if (!Array.isArray(m.motion) || m.motion.length < 1)
-			errors.push("motion: at least one entry when present");
-		else
-			m.motion.forEach((entry: unknown, i: number) => {
-				const at = `motion[${i}]`;
-				if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-					errors.push(`${at}: not an object`);
-					return;
-				}
-				const e = entry as Record<string, unknown>;
-				for (const k of Object.keys(e).filter((k) => !MOTION_KEYS.includes(k)))
-					errors.push(`${at}: unknown key "${k}"`);
-				for (const k of MOTION_REQUIRED)
-					if (typeof e[k] !== "string" || e[k].trim() === "")
-						errors.push(`${at}.${k}: non-empty string required`);
-				// `property` names what moves (it may be prose); the timing values are the contract.
-				for (const k of ["duration", "easing", ...MOTION_OPTIONAL])
-					if (typeof e[k] === "string" && e[k].trim() !== "" && !source.includes(e[k]))
-						errors.push(`${at}.${k}: \`${e[k]}\` is not in the demo source`);
-				for (const k of MOTION_OPTIONAL)
-					if (k in e && (typeof e[k] !== "string" || e[k].trim() === ""))
-						errors.push(`${at}.${k}: non-empty string required`);
-			});
-	}
-	return errors;
-}
-
-/** Library exports a demo imports from the package (the `components` facet is derived from these, never hand-typed). */
-export function importedNames(source: string): string[] {
-	return [
-		...new Set(
-			[
-				...source.matchAll(/import\s*\{([^}]+)\}\s*from\s*["']@codeatlasdev\/ui[^"']*["']/g),
-			].flatMap(([, names]) =>
-				names
-					.split(",")
-					.map(
-						(n) =>
-							n
-								.trim()
-								.replace(/^type\s+/, "")
-								.split(/\s+as\s+/)[0]
-					)
-					.filter(Boolean)
-			)
-		),
-	];
-}
-
-/** Problems that make the registry invalid: unregistered demos, missing files, duplicate ids/paths, missing or inaccurate sidecars, missing or inconsistent index facets. */
-export function checkCatalog(
-	catalog: readonly { id: string; path: string }[],
-	components: readonly { name: string }[]
-): string[] {
-	const errors: string[] = [];
-	const ids = new Set(catalog.map((d) => d.id));
-	const known = new Set(components.map((c) => c.name));
-	const walk = (dir: string, ext: string): string[] =>
-		readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
-			e.isDirectory()
-				? walk(join(dir, e.name), ext)
-				: e.name.endsWith(ext)
-					? [relative(DEMOS_DIR, join(dir, e.name)).replaceAll("\\", "/").slice(0, -ext.length)]
-					: []
-		);
-	const paths = new Set(catalog.map((d) => d.path));
-	for (const p of walk(DEMOS_DIR, ".svelte"))
-		if (!HELPERS.includes(p) && !paths.has(p)) errors.push(`demo without id: ${p}`);
-	for (const p of walk(DEMOS_DIR, ".meta.json"))
-		if (!paths.has(p)) errors.push(`sidecar without demo: ${p}.meta.json`);
-	const seen = new Set<string>();
-	for (const d of catalog) {
-		if (seen.has(d.id)) errors.push(`duplicate id: ${d.id}`);
-		seen.add(d.id);
-		if (!ID_PATTERN.test(d.id)) errors.push(`#${d.id} id: 3 digits up to 999, 4 digits from 1000`);
-		if (!existsSync(join(DEMOS_DIR, `${d.path}.svelte`))) {
-			errors.push(`#${d.id} missing file: ${d.path}`);
-			continue;
-		}
-		const metaFile = join(DEMOS_DIR, `${d.path}.meta.json`);
-		if (!existsSync(metaFile)) {
-			errors.push(`#${d.id} no sidecar: ${d.path}.meta.json`);
-			continue;
-		}
-		let meta: unknown;
-		try {
-			meta = JSON.parse(readFileSync(metaFile, "utf8"));
-		} catch (e) {
-			errors.push(`#${d.id} ${d.path}.meta.json: ${(e as Error).message}`);
-			continue;
-		}
-		const source = readFileSync(join(DEMOS_DIR, `${d.path}.svelte`), "utf8");
-		for (const e of checkMeta(meta, source, { known, ids, self: d.id }))
-			errors.push(`#${d.id} ${d.path}.meta.json: ${e}`);
-		const facets = (meta as { index?: IndexFacets }).index;
-		if (!facets) {
-			errors.push(`#${d.id} ${d.path}.meta.json: index: facets required (bun run index:backfill)`);
-			continue;
-		}
-		const range = checkIdRange(d.id, facets.kind, facets.subtype);
-		if (range) errors.push(`#${d.id} ${d.path}.meta.json: index: ${range}`);
-		const used = importedNames(source).filter((n) => known.has(n));
-		const listed = [...facets.components].sort().join();
-		if (listed !== [...used].sort().join())
-			errors.push(
-				`#${d.id} ${d.path}.meta.json: index.components must be the imports of the demo: ${used.join(", ") || "none"}`
-			);
-	}
-	if (paths.size !== catalog.length) errors.push("duplicate path in catalog");
-	return errors;
-}
-
-export function buildDemos(
-	manifest: Manifest,
-	catalog: readonly { id: string; path: string }[]
-): { demos: ManifestDemo[]; files: Record<string, string> } {
-	const known = new Set(manifest.components.map((c) => c.name));
-	const usages = demoUsages();
-	const demos = catalog.map(({ id, path }): ManifestDemo => {
-		const [group, page, variant] = path.split("/");
-		const file = join(DEMOS_DIR, `${path}.svelte`);
-		const source = readFileSync(file, "utf8");
-		const meta = JSON.parse(
-			readFileSync(file.replace(/\.svelte$/, ".meta.json"), "utf8")
-		) as DemoMeta;
-		const imports = [
-			...source.matchAll(/import\s*\{([^}]+)\}\s*from\s*["'](@codeatlasdev\/ui[^"']*)["']/g),
-		].map(([, names, from]) => ({
-			from,
-			names: names
-				.split(",")
-				.map(
-					(n) =>
-						n
-							.trim()
-							.replace(/^type\s+/, "")
-							.split(/\s+as\s+/)[0]
-				)
-				.filter(Boolean),
-		}));
-		const components = [...new Set(imports.flatMap((i) => i.names).filter((n) => known.has(n)))];
-		const use = usages.get(path);
-		const title = use?.title || variant;
-		const description = use?.description ?? "";
-		// Same transform as site/src/components/docs/Demo.astro (heading id).
-		const slug = title
-			.toLowerCase()
-			.replace(/[^a-z0-9]+/g, "-")
-			.replace(/^-|-$/g, "");
-		const peers = [...new Set(imports.map((i) => PEERS[i.from]).filter(Boolean))];
-		return {
-			id,
-			group,
-			page,
-			variant,
-			slug,
-			title,
-			description,
-			summary: meta.summary,
-			use: meta.use,
-			spec: meta.spec,
-			tags: meta.tags,
-			...(meta.names && { names: meta.names }),
-			...(meta.motion && { motion: meta.motion }),
-			shape: meta.shape,
-			index: meta.index,
-			components,
-			imports,
-			interactive: use?.interactive ?? false,
-			demo: `${SITE}/docs/${group}/${page}#${slug}`,
-			source,
-			needs: [`${PKG}@${manifest.version}`, ...peers].join(" + "),
-		};
-	});
-	const groups = [...new Set(demos.map((d) => d.group))].map((slug) => {
-		const g = demos.filter((d) => d.group === slug);
-		return { slug, first: g[0].id, last: g[g.length - 1].id, count: g.length };
-	});
-	const files: Record<string, string> = {
-		"catalog.json": `${JSON.stringify({ version: manifest.version, count: demos.length, groups, elements: demos.map(({ source: _, ...d }) => d) }, null, "\t")}\n`,
-		"en/catalog.tsv": `${["id\tgroup\tpage\ttitle\tnames\ttags\tsummary", ...demos.map((d) => [d.id, d.group, d.page, d.title, (d.names ?? []).join(" | "), d.tags.join(","), d.summary].map((v) => v.replace(/[\t\n]/g, " ")).join("\t"))].join("\n")}\n`,
-	};
-	const motionLines = (d: ManifestDemo) =>
-		d.motion?.length
-			? [
-					"Motion:",
-					...d.motion.map(
-						(m) =>
-							`- ${m.property}: ${m.duration} ${m.easing}${[
-								m.delay && ` delay ${m.delay}`,
-								m.stagger && ` stagger ${m.stagger}`,
-								m.spring && ` spring ${m.spring}`,
-							]
-								.filter(Boolean)
-								.join("")}`
-					),
-				]
-			: [];
-	const namesLine = (d: ManifestDemo) => (d.names?.length ? [`Names: ${d.names.join(" | ")}`] : []);
-	for (const d of demos) {
-		const header = [
-			`<!-- ${PKG} demo #${d.id} · MIT License (c) CodeAtlas · ${d.demo} -->`,
-			`Element: #${d.id} ${d.title} (${d.group}/${d.page})`,
-			`What it shows: ${d.summary}`,
-			`When to use: ${d.use}`,
-			"Spec:",
-			...d.spec.map((s) => `- ${s}`),
-			...motionLines(d),
-			...namesLine(d),
-			`Tags: ${d.tags.join(", ")}`,
-			`Needs: ${d.needs}`,
-			`Components: ${d.components.join(", ") || "none"}`,
-			`Live demo: ${d.demo}`,
-		];
-		files[`en/e/${d.id}.txt`] = `${header.join("\n")}\n\n${d.source}`;
-		files[`en/p/${d.id}.txt`] = `${[
-			`Use ${PKG} demo #${d.id} "${d.title}" (${d.group}/${d.page}).`,
-			`What it shows: ${d.summary.replace(/\.$/, "")}. When to use: ${d.use.replace(/\.$/, "")}.`,
-			"Spec:",
-			...d.spec.map((s) => `- ${s}`),
-			...motionLines(d),
-			...namesLine(d),
-			...(d.motion?.length
-				? [
-						"Reproduce the motion values exactly; do not guess timing or curves. Under prefers-reduced-motion render the final state.",
-					]
-				: []),
-			"Check first: Svelte 5 + @codeatlasdev/ui installed? theme in src/lib/theme.ts? Kit 2 or 3?",
-			`Apply: import only from "${PKG}[/charts|/map|/sound|/table|/code|/forms]"; keep component names, props and`,
-			"  variants of the reference as they are; no layout CSS, --ca-* tokens only (SKILL.md rules);",
-			"  replace sample data/copy with the project's; keep the first comment line.",
-			`Report: #${d.id} ${d.title} → file, what changed, ${d.demo}; what you could not check (light/dark, 375px, keyboard, reduced motion).`,
-			`Reference: ${API}/en/e/${d.id}.txt   Components API: ca-ui-mcp get_component(${d.components[0] ?? "…"})`,
-		].join("\n")}\n`;
-	}
-	return { demos, files };
-}
-
-export function demosMarkdown(demos: ManifestDemo[]): string {
-	return `${[
-		"<!-- generated by packages/ui/scripts/build-manifest.ts (bun run --cwd packages/ui manifest -- --skill). Do not edit. -->",
-		"# Demo catalog",
-		"",
-		`Every demo has a stable number. Fetch one with \`get_demo\` (MCP) or ${API}/en/e/NNN.txt.`,
-		"",
-		"| id | title | group/page | components |",
-		"|---|---|---|---|",
-		...demos.map(
-			(d) => `| ${d.id} | ${cell(d.title)} | ${d.group}/${d.page} | ${d.components.join(", ")} |`
-		),
-	].join("\n")}\n`;
-}
-
-// ── agent skill reference ─────────────────────────────────────────────────────
+export type { Manifest, ManifestComponent, ManifestProp } from "./manifest/components.ts";
+// The public API of the manifest builders: tests, the MCP server and the other scripts import from here.
+export { buildManifest, componentDeprecated, componentDoc } from "./manifest/components.ts";
+export type { ManifestDemo, ManifestMotion } from "./manifest/demos.ts";
+export { buildDemos, checkCatalog, checkMeta, HELPERS, importedNames } from "./manifest/demos.ts";
+export type { ExportKind, ManifestExport, ManifestExportMember } from "./manifest/exports.ts";
+export { extractExports } from "./manifest/exports.ts";
+export type { ManifestGuide } from "./manifest/guides.ts";
+export { buildGuides, buildRecipes } from "./manifest/guides.ts";
+export type { ManifestDataAttribute, ManifestPart, ManifestStyling } from "./manifest/styling.ts";
+export {
+	extractClasses,
+	extractComponentTokens,
+	extractDataAttributes,
+	extractStyling,
+} from "./manifest/styling.ts";
+export type { ManifestSurface, ManifestToken } from "./manifest/tokens.ts";
+export { buildSurfaces, buildTokens, extractSurfaces, extractTokens } from "./manifest/tokens.ts";
+export type { PartsFile } from "./manifest/writers.ts";
+export { buildParts, demosMarkdown, partsMarkdown, skillMarkdown } from "./manifest/writers.ts";
 
 const SKILL_API = resolve(ROOT, "../../.agents/skills/codeatlas-ui/API.md");
 const MIGRATION_MD = resolve(ROOT, "MIGRATION.md");
 const SKILL_DEMOS = resolve(ROOT, "../../.agents/skills/codeatlas-ui/DEMOS.md");
 
-const cell = (v: string) => v.replace(/\|/g, "\\|");
-
-/** One component's override surface: stable parts, internal parts, scoped variables, data attributes. */
-function stylingLines(s: ManifestStyling): string[] {
-	const code = (xs: string[]) => xs.map((x) => `\`${x}\``).join(" ");
-	const lines: string[] = [];
-	const stable = s.parts.filter((p) => p.stable).map((p) => p.name);
-	const internal = s.parts.filter((p) => !p.stable).map((p) => p.name);
-	if (stable.length) lines.push(`Parts: ${code(stable)}`, "");
-	if (internal.length) lines.push(`Internal (may change in any release): ${code(internal)}`, "");
-	if (s.variables.length) lines.push(`Variables: ${code(s.variables)}`, "");
-	if (s.data.length)
-		lines.push(
-			`Data attributes: ${s.data.map((d) => `\`${d.name}\`${d.values.length ? ` (${d.values.map((v) => `\`${v}\``).join(" ")})` : ""}`).join(", ")}`,
-			""
-		);
-	return lines;
-}
-
-export interface PartsFile {
-	name: string;
-	version: string;
-	/** Naming rule, repeated in the file so a consumer tool needs nothing else. */
-	rule: string;
-	components: {
-		name: string;
-		import: string;
-		parts: ManifestPart[];
-		variables: string[];
-		data: ManifestDataAttribute[];
-	}[];
-}
-
-const PARTS_RULE =
-	"A `ca-*` class owned by a component is a stable part: renaming or removing it is a breaking change. A `ca-x-*` class and every @keyframes name is internal and may change in any release. Variables and data attributes listed here are stable.";
-
-/** The stable override surface of every component that has one, for `parts.json`, `list_parts` and `workarounds`. */
-export function buildParts(m: Manifest): PartsFile {
-	return {
-		name: m.name,
-		version: m.version,
-		rule: PARTS_RULE,
-		components: m.components
-			.filter((c) => c.styling.parts.length || c.styling.variables.length || c.styling.data.length)
-			.map((c) => ({ name: c.name, import: c.import, ...c.styling })),
-	};
-}
-
-/** Markdown of the override surface, one section per component. Deterministic. */
-export function partsMarkdown(m: Manifest): string {
-	const out = [PARTS_RULE, ""];
-	for (const c of buildParts(m).components) out.push(`## ${c.name}`, "", ...stylingLines(c));
-	return `${out
-		.join("\n")
-		.replace(/\n{3,}/g, "\n\n")
-		.trimEnd()}\n`;
-}
-
-/** Markdown reference of every component's props, snippets and classes, then every other export's signature. Deterministic. */
-export function skillMarkdown(m: Manifest): string {
-	const out = [
-		"<!-- generated by packages/ui/scripts/build-manifest.ts (bun run --cwd packages/ui manifest -- --skill). Do not edit. -->",
-		"# Component API reference",
-		"",
-		`Describes ${m.name}@${m.version}. If the project has another version installed, this file may list props that do not exist there (or miss ones that do): the installed package is the source of truth, through \`ca-ui-mcp\` (\`get_component\`, \`get_export\`) or \`node_modules/${m.name}/dist/components.json\`.`,
-		"",
-		"Generated from the source types: every prop, default and public `ca-*` class. Hand-written usage examples are in [COMPONENTS.md](./COMPONENTS.md).",
-		"Import from the path in each heading. Charts, DataTable, CodeSnippet and the `forms` fields are subpath imports.",
-		"",
-	];
-	for (const c of m.components) {
-		out.push(
-			`## ${c.name}`,
-			"",
-			`\`import { ${c.name} } from "${c.import}"\`${c.generics ? ` (generic: \`${c.generics}\`)` : ""}`,
-			""
-		);
-		if (c.deprecated) out.push(`**Deprecated. ${c.deprecated}**`, "");
-		if (c.description) out.push(c.description, "");
-		if (c.props.length) {
-			out.push("| Prop | Type | Default | Notes |", "|---|---|---|---|");
-			for (const p of c.props)
-				out.push(
-					`| \`${p.name}${p.optional ? "?" : ""}\` | \`${cell(p.type)}\` | ${p.default ? `\`${cell(p.default)}\`` : ""} | ${[p.bindable ? "`bind:`" : "", p.description ? cell(p.description) : ""].filter(Boolean).join(" ")} |`
-				);
-			out.push("");
-		}
-		if (c.snippets.length)
-			out.push(
-				`Snippets: ${c.snippets.map((x) => `\`${x.name}\`${x.type.includes("<") ? ` (\`${cell(x.type)}\`)` : ""}${x.description ? `: ${cell(x.description)}` : ""}`).join("; ")}`,
-				""
-			);
-		if (c.extends) out.push(`Also accepts: \`${cell(c.extends)}\``, "");
-		out.push(...stylingLines(c.styling));
-		if (c.tokens.length) out.push(`Tokens: ${c.tokens.map((x) => `\`${x}\``).join(" ")}`, "");
-	}
-	out.push(
-		"# Non-component exports",
-		"",
-		"Functions, stores, constants and types every entry point exports besides components. Import from the path in each heading; types use `import type`."
-	);
-	for (const entry of [...new Set(m.exports.map((e) => e.import))]) {
-		const here = m.exports.filter((x) => x.import === entry);
-		out.push("", `## ${entry}`, "");
-		for (const e of here.filter((x) => x.kind !== "type")) {
-			out.push(`### ${e.name}`, "", `\`import { ${e.name} } from "${entry}"\``, "");
-			if (e.description) out.push(e.description, "");
-			out.push("```ts", e.signature, "```", "");
-		}
-		const types = here.filter((x) => x.kind === "type");
-		if (types.length) {
-			out.push("Types:", "", "| Type | Declaration | Notes |", "|---|---|---|");
-			for (const t of types)
-				out.push(
-					`| \`${t.name}\` | \`${cell(t.signature)}\` | ${t.description ? cell(t.description) : ""} |`
-				);
-			out.push("");
-			for (const t of types.filter((x) => x.members)) {
-				out.push(`#### ${t.name}`, "", "| Field | Type | Notes |", "|---|---|---|");
-				for (const f of t.members ?? [])
-					out.push(
-						`| \`${f.name}${f.optional ? "?" : ""}\` | \`${cell(f.type)}\` | ${f.description ? cell(f.description) : ""} |`
-					);
-				out.push("");
-			}
-		}
-	}
-	return `${out
-		.join("\n")
-		.replace(/\n{3,}/g, "\n\n")
-		.trimEnd()}\n`;
-}
-
 if (import.meta.main) {
 	const manifest = buildManifest();
 	const tokens = buildTokens();
diff --git a/packages/ui/scripts/manifest/ast.ts b/packages/ui/scripts/manifest/ast.ts
new file mode 100644
index 00000000..36bbce54
--- /dev/null
+++ b/packages/ui/scripts/manifest/ast.ts
@@ -0,0 +1,25 @@
+/** TypeScript AST and JSDoc helpers shared by the component and export extractors. */
+import ts from "typescript";
+
+/** Last JSDoc comment attached to a node, flattened to one line. */
+export function jsDoc(node: ts.Node): string | undefined {
+	const comment = ts.getJSDocCommentsAndTags(node).find(ts.isJSDoc)?.comment;
+	const text = typeof comment === "string" ? comment : comment?.map((c) => c.text).join("");
+	return text?.replace(/\s*\n\s*/g, " ").trim() || undefined;
+}
+
+export const propName = (n: ts.PropertyName): string =>
+	ts.isIdentifier(n) || ts.isStringLiteral(n) ? n.text : n.getText();
+
+/** Prose of a `/** ... *\/` block before its first `@tag`, flattened to one paragraph. */
+export function docProse(block: string): string | undefined {
+	const lines = block
+		.replace(/^\/\*\*|\*\/$/g, "")
+		.split("\n")
+		.map((l) => l.replace(/^\s*\*?\s?/, "").trimEnd());
+	const tag = lines.findIndex((l) => /^@\w+/.test(l.trim()));
+	const prose = (tag < 0 ? lines : lines.slice(0, tag)).join("\n").split(/\n\s*\n/)[0];
+	return prose.replace(/\n/g, " ").trim() || undefined;
+}
+
+export const oneLine = (s: string) => s.replace(/\s+/g, " ").trim();
diff --git a/packages/ui/scripts/manifest/components.ts b/packages/ui/scripts/manifest/components.ts
new file mode 100644
index 00000000..f56e2010
--- /dev/null
+++ b/packages/ui/scripts/manifest/components.ts
@@ -0,0 +1,487 @@
+/** Components: every `export { default as X } from "*.svelte"` of every entry, with props, snippets, defaults and docs. */
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve } from "node:path";
+import ts from "typescript";
+import { docProse, jsDoc, oneLine, propName } from "./ast.ts";
+import type { ManifestExport } from "./exports.ts";
+import { extractExports } from "./exports.ts";
+import { API_ENTRIES, LIB, ROOT } from "./paths.ts";
+import {
+	componentCss,
+	extractComponentTokens,
+	extractStyling,
+	globalTokens,
+	type ManifestStyling,
+} from "./styling.ts";
+
+// CJS require keeps svelte2tsx out of Vite's transform pipeline (its sourceMappingURL points at a file it does not ship).
+const { svelte2tsx }: typeof import("svelte2tsx") = createRequire(import.meta.url)("svelte2tsx");
+
+export interface ManifestProp {
+	name: string;
+	type: string;
+	optional: boolean;
+	default?: string;
+	/** `$bindable` prop (use `bind:name`). */
+	bindable?: boolean;
+	description?: string;
+}
+
+export interface ManifestComponent {
+	name: string;
+	/** Import specifier, e.g. `@codeatlasdev/ui` or `@codeatlasdev/ui/charts`. */
+	import: string;
+	/** Source file relative to `src/lib`. */
+	source: string;
+	/** First JSDoc/comment paragraph of the component, when present. */
+	description?: string;
+	/** Replacement text of a component-level `@deprecated` ("Use `<Flex>`: ..."). Absent on current components. */
+	deprecated?: string;
+	/** Own props. Inherited attributes (e.g. `HTMLAttributes`) are listed in `extends`. */
+	props: ManifestProp[];
+	/** Props typed as `Snippet`/`Snippet<[...]>`: the holes a caller fills. */
+	snippets: ManifestProp[];
+	/** Text of the interface `extends` clause: native attributes that also pass through. */
+	extends?: string;
+	/** Stable `ca-*` class names defined in the component `<style>` (the stable subset of `styling.parts`). */
+	classes: string[];
+	/** Everything an app may target to restyle this component, each part flagged stable or internal (#381). */
+	styling: ManifestStyling;
+	/** Component tokens: `--ca-<stem>-*` custom properties the `<style>` reads with a fallback (`var(--ca-btn-gap, …)`). Set them on `:root`, a wrapper or `ThemeOptions.components`. */
+	tokens: string[];
+	/** Generic parameters, e.g. `TData extends RowData`. */
+	generics?: string;
+}
+
+export interface Manifest {
+	name: string;
+	version: string;
+	components: ManifestComponent[];
+	/** Every other export of every entry point: functions, stores, constants, classes, types. */
+	exports: ManifestExport[];
+}
+
+// ── entry parsing ─────────────────────────────────────────────────────────────
+
+interface Found {
+	name: string;
+	file: string;
+	entry: string;
+}
+
+/** Resolve `export { default as X } from "./a.svelte"` and `export { X } from "./index.js"` (recursively). */
+function collectExports(entryFile: string, entry: string, out: Found[], seen = new Set<string>()) {
+	const abs = join(LIB, entryFile);
+	if (seen.has(abs) || !existsSync(abs)) return;
+	seen.add(abs);
+	const sf = ts.createSourceFile(abs, readFileSync(abs, "utf8"), ts.ScriptTarget.ESNext, true);
+	const dir = dirname(abs);
+	for (const st of sf.statements) {
+		if (!ts.isExportDeclaration(st) || st.isTypeOnly || !st.moduleSpecifier) continue;
+		if (!ts.isStringLiteral(st.moduleSpecifier) || !st.exportClause) continue;
+		if (!ts.isNamedExports(st.exportClause)) continue;
+		const spec = st.moduleSpecifier.text;
+		if (!spec.startsWith(".")) continue;
+		if (spec.endsWith(".svelte")) {
+			for (const el of st.exportClause.elements) {
+				if (el.isTypeOnly) continue;
+				if ((el.propertyName ?? el.name).text === "default")
+					out.push({ name: el.name.text, file: relative(LIB, join(dir, spec)), entry });
+			}
+		} else if (/\/index\.js$/.test(spec) || spec.endsWith("index")) {
+			// Re-export of named bindings coming from a sub-barrel (Table, Date): follow it,
+			// keeping only the names this entry re-exports.
+			const names = new Set(
+				st.exportClause.elements.filter((e) => !e.isTypeOnly).map((e) => e.name.text)
+			);
+			const sub: Found[] = [];
+			collectExports(relative(LIB, join(dir, spec.replace(/\.js$/, ".ts"))), entry, sub, seen);
+			for (const f of sub) if (names.has(f.name)) out.push(f);
+		}
+	}
+}
+
+// ── props extraction ──────────────────────────────────────────────────────────
+
+/** Defaults live in the destructuring: `let { size = 'md', value = $bindable('a') } = $props()`. */
+function readDefaults(decl: ts.VariableDeclaration, sf: ts.SourceFile) {
+	const defaults = new Map<string, { text?: string; bindable: boolean }>();
+	if (!ts.isObjectBindingPattern(decl.name)) return defaults;
+	for (const el of decl.name.elements) {
+		if (el.dotDotDotToken) continue;
+		const key = el.propertyName
+			? propName(el.propertyName as ts.PropertyName)
+			: (el.name as ts.Identifier).text;
+		let text: string | undefined;
+		let bindable = false;
+		const init = el.initializer;
+		if (init) {
+			if (ts.isCallExpression(init) && init.expression.getText(sf) === "$bindable") {
+				bindable = true;
+				text = init.arguments[0]?.getText(sf);
+			} else text = init.getText(sf);
+		}
+		defaults.set(key, { text, bindable });
+	}
+	return defaults;
+}
+
+/** Find `let {...}: T = $props()` in the svelte2tsx output. */
+function findPropsDecl(sf: ts.SourceFile) {
+	let found: ts.VariableDeclaration | undefined;
+	const visit = (n: ts.Node) => {
+		if (found) return;
+		if (
+			ts.isVariableDeclaration(n) &&
+			n.initializer &&
+			ts.isCallExpression(n.initializer) &&
+			n.initializer.expression.getText(sf) === "$props"
+		)
+			found = n;
+		else ts.forEachChild(n, visit);
+	};
+	visit(sf);
+	return found;
+}
+
+/** Members of a component's props, and the native attribute type they extend. */
+interface PropsMembers {
+	members: readonly ts.TypeElement[];
+	ext: string | undefined;
+}
+
+/** Members of `LayoutProps` (components/Layout/layout.ts), the source of every layout primitive's token props. */
+let layoutMembers: Map<string, ts.TypeElement> | undefined;
+function layoutPropMembers(): Map<string, ts.TypeElement> {
+	if (layoutMembers) return layoutMembers;
+	const file = join(LIB, "components/Layout/layout.ts");
+	const sf = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.ESNext, true);
+	layoutMembers = new Map();
+	for (const st of sf.statements)
+		if (ts.isInterfaceDeclaration(st) && st.name.text === "LayoutProps")
+			for (const m of st.members)
+				if (ts.isPropertySignature(m) && m.name) layoutMembers.set(propName(m.name), m);
+	return layoutMembers;
+}
+
+/**
+ * `Pick<LayoutProps, 'gap' | 'p'>` (what Flex, Stack, Grid, Box, Container, Section and Surface take): the
+ * picked members of `LayoutProps`, so the manifest lists the token props instead of an opaque `extends`.
+ * Anything else is `undefined`. Member nodes belong to layout.ts, hence they carry their own source file.
+ */
+function layoutPick(
+	type: ts.TypeReferenceNode | ts.ExpressionWithTypeArguments
+): ts.TypeElement[] | undefined {
+	const name = ts.isTypeReferenceNode(type) ? type.typeName : type.expression;
+	if (name.getText() !== "Pick") return undefined;
+	const [target, keys] = type.typeArguments ?? [];
+	if (!target || !keys || target.getText() !== "LayoutProps") return undefined;
+	const names = (ts.isUnionTypeNode(keys) ? keys.types : [keys]).map((k) =>
+		ts.isLiteralTypeNode(k) && ts.isStringLiteral(k.literal) ? k.literal.text : undefined
+	);
+	if (names.some((n) => n === undefined)) return undefined;
+	const all = layoutPropMembers();
+	return names.flatMap((n) => all.get(n as string) ?? []);
+}
+
+/**
+ * `PolymorphicAttributes<T, Own>` (Flex, Stack, Grid, Box): `Own` holds the token props, the rest is the tag's
+ * own attributes. Returns the members of a `Pick<LayoutProps, ...>` `Own`, or `undefined` for any other shape.
+ */
+function polymorphicOwn(type: ts.TypeNode): ts.TypeElement[] | undefined {
+	if (!ts.isTypeReferenceNode(type) || type.typeName.getText() !== "PolymorphicAttributes")
+		return undefined;
+	const own = type.typeArguments?.[1];
+	return own && ts.isTypeReferenceNode(own) ? layoutPick(own) : undefined;
+}
+
+/** Members of the `Props` interface/type alias, or of an inline type literal. */
+function resolvePropsType(sf: ts.SourceFile, type: ts.TypeNode | undefined): PropsMembers {
+	let members: readonly ts.TypeElement[] = [];
+	let ext: string | undefined;
+	if (!type) return { members, ext };
+	if (ts.isTypeLiteralNode(type)) return { members: type.members, ext };
+	if (ts.isTypeReferenceNode(type)) {
+		const name = type.typeName.getText(sf);
+		const decl = sf.statements.find(
+			(s): s is ts.InterfaceDeclaration | ts.TypeAliasDeclaration =>
+				(ts.isInterfaceDeclaration(s) || ts.isTypeAliasDeclaration(s)) && s.name.text === name
+		);
+		// Props may be declared inside `$$render()` (instance script): search the whole file.
+		const inner = decl ?? findDeclDeep(sf, name);
+		if (inner && ts.isInterfaceDeclaration(inner)) {
+			// A base interface declared in the same file (`interface Own`) is part of the component's
+			// own contract: inline its members. Anything else (`Omit<HTMLAttributes>`) is `extends`.
+			const inherited: ts.TypeElement[] = [];
+			const external: string[] = [];
+			for (const h of inner.heritageClauses ?? [])
+				for (const t of h.types) {
+					const base = ts.isIdentifier(t.expression)
+						? findDeclDeep(sf, t.expression.text)
+						: undefined;
+					const picked = layoutPick(t);
+					if (picked) inherited.push(...picked);
+					else if (base && ts.isInterfaceDeclaration(base) && !t.typeArguments)
+						inherited.push(...base.members);
+					else external.push(t.getText(sf));
+				}
+			members = [...inherited, ...inner.members];
+			ext = external.join(", ") || undefined;
+		} else if (inner && ts.isTypeAliasDeclaration(inner)) {
+			const t = inner.type;
+			if (ts.isTypeLiteralNode(t)) members = t.members;
+			else if (ts.isUnionTypeNode(t)) return resolveUnion(sf, t);
+			else if (ts.isIntersectionTypeNode(t)) {
+				const own: ts.TypeElement[] = [];
+				const rest: string[] = [];
+				for (const part of t.types) {
+					const polymorphic = polymorphicOwn(part);
+					if (ts.isTypeLiteralNode(part)) own.push(...part.members);
+					else if (polymorphic) {
+						own.push(...polymorphic);
+						rest.push("PolymorphicAttributes<T>");
+					} else if (ts.isTypeReferenceNode(part) && isLocalInterface(sf, part)) {
+						own.push(...resolvePropsType(sf, part).members);
+					} else rest.push(part.getText(sf));
+				}
+				members = own;
+				ext = rest.join(" & ") || undefined;
+			} else ext = t.getText(sf);
+		}
+	}
+	return { members, ext };
+}
+
+/**
+ * `type Props = A | B` (a component whose element changes with a prop, e.g. Button on `href`):
+ * the documented props are those declared by the FIRST branch (the default rendering, with its
+ * JSDoc), made optional when a later branch leaves them out or optional, and the attribute sets of
+ * every branch are reported as `extends` so a reader sees all the native attributes that pass through.
+ */
+function resolveUnion(sf: ts.SourceFile, union: ts.UnionTypeNode): PropsMembers {
+	const branches = union.types.map((t) => resolvePropsType(sf, t));
+	const named = (m: ts.TypeElement) =>
+		ts.isPropertySignature(m) && m.name ? propName(m.name) : "";
+	// One entry per prop: the first declaration wins (the shared base, with its docs); a later
+	// branch only narrows it (`href?: undefined`, `type?: 'button' | ...`).
+	const byName = new Map<string, ts.TypeElement>();
+	for (const b of branches)
+		for (const m of b.members) if (named(m) && !byName.has(named(m))) byName.set(named(m), m);
+	const ext = [...new Set(branches.map((b) => b.ext).filter(Boolean))].join(" | ");
+	return { members: [...byName.values()], ext: ext || undefined };
+}
+
+/** A reference to an interface declared in the same component script (its members are the component's own props). */
+function isLocalInterface(sf: ts.SourceFile, ref: ts.TypeReferenceNode) {
+	if (ref.typeArguments) return false;
+	const d = findDeclDeep(sf, ref.typeName.getText(sf));
+	return !!d && ts.isInterfaceDeclaration(d);
+}
+
+function findDeclDeep(sf: ts.SourceFile, name: string) {
+	let hit: ts.InterfaceDeclaration | ts.TypeAliasDeclaration | undefined;
+	const visit = (n: ts.Node) => {
+		if (hit) return;
+		if ((ts.isInterfaceDeclaration(n) || ts.isTypeAliasDeclaration(n)) && n.name.text === name)
+			hit = n;
+		else ts.forEachChild(n, visit);
+	};
+	visit(sf);
+	return hit;
+}
+
+/** `'a' | 'b' | 2 | number`: a union whose members are all literals or the `string`/`number` keywords. */
+function literalUnionText(type: ts.TypeNode, sf: ts.SourceFile): string | undefined {
+	if (!ts.isUnionTypeNode(type)) return undefined;
+	const ok = type.types.every(
+		(t) =>
+			(ts.isLiteralTypeNode(t) && t.literal.kind !== ts.SyntaxKind.NullKeyword) ||
+			t.kind === ts.SyntaxKind.StringKeyword ||
+			t.kind === ts.SyntaxKind.NumberKeyword
+	);
+	return ok ? oneLine(type.getText(sf)) : undefined;
+}
+
+/** Declaration of `name` (an alias) in `sf` or, when it is imported from a relative module, in that file. */
+function findAliasType(
+	sf: ts.SourceFile,
+	dir: string,
+	name: string,
+	depth = 0
+): { type: ts.TypeNode; sf: ts.SourceFile } | undefined {
+	const local = findDeclDeep(sf, name);
+	if (local && ts.isTypeAliasDeclaration(local)) return { type: local.type, sf };
+	if (depth > 2) return undefined;
+	for (const st of sf.statements) {
+		if (!ts.isImportDeclaration(st) || !ts.isStringLiteral(st.moduleSpecifier)) continue;
+		const spec = st.moduleSpecifier.text;
+		if (!spec.startsWith(".")) continue;
+		const named = st.importClause?.namedBindings;
+		if (!named || !ts.isNamedImports(named)) continue;
+		const el = named.elements.find((e) => e.name.text === name);
+		if (!el) continue;
+		const base = resolve(dir, spec.replace(/\.js$/, ""));
+		const file = [`${base}.ts`, join(base, "index.ts")].find((f) => existsSync(f));
+		if (!file) return undefined;
+		const other = ts.createSourceFile(
+			file,
+			readFileSync(file, "utf8"),
+			ts.ScriptTarget.ESNext,
+			true
+		);
+		return findAliasType(other, dirname(file), (el.propertyName ?? el.name).text, depth + 1);
+	}
+	return undefined;
+}
+
+/**
+ * A prop typed with a bare alias (`shape?: Shape`) hides its values from the reader. When the alias
+ * is a union of literals, show the union. Objects, arrays, generics and external types stay as written.
+ */
+function expandLiteralAlias(sf: ts.SourceFile, dir: string, type: string): string {
+	if (!/^[A-Z]\w*$/.test(type)) return type;
+	const hit = findAliasType(sf, dir, type);
+	return (hit && literalUnionText(hit.type, hit.sf)) ?? type;
+}
+
+/**
+ * Component-level description: a top-level `/** ... *\/` block of a `<script>` that is detached from
+ * the declaration below it (blank line between) or that opens the script right before an import.
+ * JSDoc on a declaration (`/** doc *\/ interface Props`, a member of `Props`, a `let` destructure)
+ * describes that declaration, never the component. Blocks with no prose (`@deprecated ...`) are skipped.
+ */
+export function componentDoc(src: string): string | undefined {
+	for (const script of src.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/g)) {
+		const body = script[1];
+		const sf = ts.createSourceFile("c.ts", body, ts.ScriptTarget.ESNext, true);
+		const stops = [...sf.statements.map((s) => s.getFullStart()), sf.endOfFileToken.getFullStart()];
+		for (const [i, full] of stops.entries()) {
+			const next = sf.statements[i];
+			for (const c of ts.getLeadingCommentRanges(body, full) ?? []) {
+				const text = body.slice(c.pos, c.end);
+				if (!text.startsWith("/**")) continue;
+				const gap = body.slice(c.end, next ? next.getStart(sf) : body.length);
+				const attached =
+					next !== undefined && !/\n[ \t]*\n/.test(gap) && !ts.isImportDeclaration(next);
+				if (attached) continue;
+				const prose = docProse(text);
+				if (prose) return prose;
+			}
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Text after `@deprecated` in a top-level `/** ... *\/` block of a `<script>` (the replacement to use), or
+ * undefined. A `@deprecated` on a prop or declaration inside the component does not deprecate the component.
+ */
+export function componentDeprecated(src: string): string | undefined {
+	for (const script of src.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/g)) {
+		const body = script[1];
+		const sf = ts.createSourceFile("c.ts", body, ts.ScriptTarget.ESNext, true);
+		const first = sf.statements[0];
+		const ranges = ts.getLeadingCommentRanges(body, first ? first.getFullStart() : 0) ?? [];
+		for (const c of ranges) {
+			const text = body.slice(c.pos, c.end);
+			if (!text.startsWith("/**")) continue;
+			const lines = text
+				.replace(/^\/\*\*|\*\/$/g, "")
+				.split("\n")
+				.map((l) => l.replace(/^\s*\*?\s?/, "").trimEnd());
+			const at = lines.findIndex((l) => /^@deprecated\b/.test(l.trim()));
+			if (at < 0) continue;
+			const rest = lines.slice(at);
+			const end = rest.findIndex((l, i) => i > 0 && (/^@\w+/.test(l.trim()) || l.trim() === ""));
+			return rest
+				.slice(0, end < 0 ? undefined : end)
+				.join(" ")
+				.replace(/^@deprecated\s*/, "")
+				.replace(/\s+/g, " ")
+				.trim();
+		}
+	}
+	return undefined;
+}
+
+function extractComponent(name: string, file: string, entry: string): ManifestComponent {
+	const abs = join(LIB, file);
+	const src = readFileSync(abs, "utf8");
+	const out: ManifestComponent = {
+		name,
+		import: entry,
+		source: file,
+		props: [],
+		snippets: [],
+		classes: [],
+		styling: { parts: [], variables: [], data: [] },
+		tokens: [],
+	};
+	const css = componentCss(src, dirname(abs));
+	out.styling = extractStyling(css, src, globalTokens());
+	out.classes = out.styling.parts.filter((p) => p.stable).map((p) => p.name);
+	out.tokens = extractComponentTokens(css, out.classes);
+
+	const generics = src.match(/<script[^>]*\bgenerics="([^"]+)"/)?.[1];
+	if (generics) out.generics = generics;
+
+	let code: string;
+	try {
+		code = svelte2tsx(src, { filename: abs, isTsFile: true, mode: "ts", version: "5.57.0" }).code;
+	} catch (e) {
+		throw new Error(`svelte2tsx failed for ${file}: ${(e as Error).message}`);
+	}
+	const sf = ts.createSourceFile(
+		`${abs}.tsx`,
+		code,
+		ts.ScriptTarget.ESNext,
+		true,
+		ts.ScriptKind.TSX
+	);
+	const decl = findPropsDecl(sf);
+	if (!decl) return out;
+
+	const defaults = readDefaults(decl, sf);
+	const { members, ext } = resolvePropsType(sf, decl.type);
+	if (ext) out.extends = ext;
+
+	for (const m of members) {
+		if (!ts.isPropertySignature(m) || !m.name) continue;
+		const written = m.type?.getText(m.getSourceFile()).replace(/\s+/g, " ") ?? "unknown";
+		const type = expandLiteralAlias(sf, dirname(abs), written);
+		const d = defaults.get(propName(m.name));
+		const prop: ManifestProp = {
+			name: propName(m.name),
+			type,
+			optional: !!m.questionToken,
+		};
+		if (d?.text !== undefined && d.text !== "undefined") prop.default = d.text;
+		if (d?.bindable) prop.bindable = true;
+		const doc = jsDoc(m);
+		if (doc) prop.description = doc;
+		(/^\(?\s*Snippet\b/.test(type) ? out.snippets : out.props).push(prop);
+	}
+
+	const description = componentDoc(src);
+	if (description) out.description = description;
+	const deprecated = componentDeprecated(src);
+	if (deprecated) out.deprecated = deprecated;
+	return out;
+}
+
+export function buildManifest(): Manifest {
+	const found: Found[] = [];
+	for (const [entry, file] of Object.entries(API_ENTRIES)) collectExports(file, entry, found);
+	const seen = new Set<string>();
+	const components: ManifestComponent[] = [];
+	for (const f of found) {
+		const key = `${f.entry}:${f.name}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		components.push(extractComponent(f.name, f.file, f.entry));
+	}
+	components.sort((a, b) => a.name.localeCompare(b.name));
+	const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+	return { name: pkg.name, version: pkg.version, components, exports: extractExports(components) };
+}
diff --git a/packages/ui/scripts/manifest/demos.ts b/packages/ui/scripts/manifest/demos.ts
new file mode 100644
index 00000000..d5ca8cb0
--- /dev/null
+++ b/packages/ui/scripts/manifest/demos.ts
@@ -0,0 +1,365 @@
+/** The demo catalog: sidecar and registry checks, the `ManifestDemo` entries and the per-demo e/ and p/ texts. */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { checkIdRange, checkIndexFacets, ID_PATTERN, type IndexFacets } from "../index-schema.ts";
+import type { Manifest } from "./components.ts";
+import { mdxFiles } from "./guides.ts";
+import { API, DEMOS_DIR, DOCS_DIR, PKG, SITE } from "./paths.ts";
+
+/** One animated property of a motion demo: literal values, each of which must appear verbatim in the demo source. */
+export interface ManifestMotion {
+	property: string;
+	duration: string;
+	easing: string;
+	delay?: string;
+	stagger?: string;
+	spring?: string;
+}
+
+export interface ManifestDemo {
+	id: string;
+	group: string;
+	page: string;
+	variant: string;
+	slug: string;
+	title: string;
+	description: string;
+	summary: string;
+	use: string;
+	spec: string[];
+	tags: string[];
+	/** Motion vocabulary: first = canonical name, the rest are aliases (other languages included). */
+	names?: string[];
+	/** Exact timing of the motion, printed in e/ and p/ so an AI never guesses it. */
+	motion?: ManifestMotion[];
+	shape: "square" | "wide" | "tall";
+	/** Index facets of the sidecar (`index.json`, `/gallery/<id>.md`). */
+	index: IndexFacets;
+	components: string[];
+	imports: { from: string; names: string[] }[];
+	interactive: boolean;
+	/** Live demo URL on the docs site. */
+	demo: string;
+	source: string;
+	needs: string;
+}
+
+/** Shared building blocks under site/src/demos that are not demos themselves. */
+export const HELPERS = [
+	"foundation/colors/Swatches",
+	"foundation/typography/TypeRows",
+	"navigation/loading-boundary/Report",
+];
+const PEERS: Record<string, string> = {
+	[`${PKG}/charts`]: "echarts",
+	[`${PKG}/map`]: "maplibre-gl",
+	[`${PKG}/table`]: "@tanstack/svelte-table",
+	[`${PKG}/code`]: "shiki",
+};
+
+/** `<Demo title description><X client:…>` per demo path, read from every MDX page. */
+function demoUsages() {
+	const out = new Map<string, { title: string; description: string; interactive: boolean }>();
+	if (!existsSync(DOCS_DIR)) return out;
+	for (const file of mdxFiles(DOCS_DIR)) {
+		const raw = readFileSync(file, "utf8");
+		for (const [, name, path] of raw.matchAll(
+			/^import (\w+) from "~\/demos\/([^"?]+)\.svelte";$/gm
+		)) {
+			const tag = raw.match(new RegExp(`<Demo ([^>]*)>\\s*<${name}\\b([^>]*)>`));
+			if (!tag) continue;
+			const attr = (k: string) => tag[1].match(new RegExp(`${k}="([^"]*)"`))?.[1] ?? "";
+			out.set(path, {
+				title: attr("title"),
+				description: attr("description"),
+				interactive: tag[2].includes("client:"),
+			});
+		}
+	}
+	return out;
+}
+
+type DemoMeta = Pick<
+	ManifestDemo,
+	"summary" | "use" | "spec" | "tags" | "shape" | "names" | "motion" | "index"
+>;
+
+const META_KEYS: Record<string, true> = {
+	summary: true,
+	use: true,
+	spec: true,
+	tags: true,
+	shape: true,
+	names: true,
+	motion: true,
+	index: true,
+};
+const MOTION_REQUIRED = ["property", "duration", "easing"] as const;
+const MOTION_OPTIONAL = ["delay", "stagger", "spring"] as const;
+const MOTION_KEYS: string[] = [...MOTION_REQUIRED, ...MOTION_OPTIONAL];
+const SHAPES: Record<string, true> = { square: true, wide: true, tall: true };
+const isLines = (v: unknown): v is string[] =>
+	Array.isArray(v) && v.every((s) => typeof s === "string" && s.trim() !== "");
+
+/** Problems of one sidecar against its demo source: shape of every field, and spec tokens quoted from the source. */
+export function checkMeta(
+	meta: unknown,
+	source: string,
+	ctx: { known?: ReadonlySet<string>; ids?: ReadonlySet<string>; self?: string } = {}
+): string[] {
+	if (!meta || typeof meta !== "object" || Array.isArray(meta)) return ["not an object"];
+	const m = meta as Record<string, unknown>;
+	const errors = Object.keys(m)
+		.filter((k) => !META_KEYS[k])
+		.map((k) => `unknown key "${k}"`);
+	for (const k of ["summary", "use"])
+		if (typeof m[k] !== "string" || m[k].trim().length < 12) errors.push(`${k}: sentence required`);
+	if (!isLines(m.spec) || m.spec.length < 1) errors.push("spec: at least one non-empty line");
+	else
+		for (const line of m.spec)
+			for (const [, token] of line.matchAll(/`([^`]+)`/g))
+				if (!source.includes(token)) errors.push(`spec: \`${token}\` is not in the demo source`);
+	if (!isLines(m.tags) || m.tags.length < 2 || m.tags.some((t) => t !== t.toLowerCase()))
+		errors.push("tags: at least 2 lowercase strings");
+	if (typeof m.shape !== "string" || !SHAPES[m.shape]) errors.push("shape: square | wide | tall");
+	if ("names" in m && (!isLines(m.names) || m.names.length < 1))
+		errors.push("names: non-empty strings, at least one");
+	if ("index" in m) errors.push(...checkIndexFacets(m.index, ctx));
+	if ("motion" in m) {
+		if (!Array.isArray(m.motion) || m.motion.length < 1)
+			errors.push("motion: at least one entry when present");
+		else
+			m.motion.forEach((entry: unknown, i: number) => {
+				const at = `motion[${i}]`;
+				if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+					errors.push(`${at}: not an object`);
+					return;
+				}
+				const e = entry as Record<string, unknown>;
+				for (const k of Object.keys(e).filter((k) => !MOTION_KEYS.includes(k)))
+					errors.push(`${at}: unknown key "${k}"`);
+				for (const k of MOTION_REQUIRED)
+					if (typeof e[k] !== "string" || e[k].trim() === "")
+						errors.push(`${at}.${k}: non-empty string required`);
+				// `property` names what moves (it may be prose); the timing values are the contract.
+				for (const k of ["duration", "easing", ...MOTION_OPTIONAL])
+					if (typeof e[k] === "string" && e[k].trim() !== "" && !source.includes(e[k]))
+						errors.push(`${at}.${k}: \`${e[k]}\` is not in the demo source`);
+				for (const k of MOTION_OPTIONAL)
+					if (k in e && (typeof e[k] !== "string" || e[k].trim() === ""))
+						errors.push(`${at}.${k}: non-empty string required`);
+			});
+	}
+	return errors;
+}
+
+/** Library exports a demo imports from the package (the `components` facet is derived from these, never hand-typed). */
+export function importedNames(source: string): string[] {
+	return [
+		...new Set(
+			[
+				...source.matchAll(/import\s*\{([^}]+)\}\s*from\s*["']@codeatlasdev\/ui[^"']*["']/g),
+			].flatMap(([, names]) =>
+				names
+					.split(",")
+					.map(
+						(n) =>
+							n
+								.trim()
+								.replace(/^type\s+/, "")
+								.split(/\s+as\s+/)[0]
+					)
+					.filter(Boolean)
+			)
+		),
+	];
+}
+
+/** Problems that make the registry invalid: unregistered demos, missing files, duplicate ids/paths, missing or inaccurate sidecars, missing or inconsistent index facets. */
+export function checkCatalog(
+	catalog: readonly { id: string; path: string }[],
+	components: readonly { name: string }[]
+): string[] {
+	const errors: string[] = [];
+	const ids = new Set(catalog.map((d) => d.id));
+	const known = new Set(components.map((c) => c.name));
+	const walk = (dir: string, ext: string): string[] =>
+		readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+			e.isDirectory()
+				? walk(join(dir, e.name), ext)
+				: e.name.endsWith(ext)
+					? [relative(DEMOS_DIR, join(dir, e.name)).replaceAll("\\", "/").slice(0, -ext.length)]
+					: []
+		);
+	const paths = new Set(catalog.map((d) => d.path));
+	for (const p of walk(DEMOS_DIR, ".svelte"))
+		if (!HELPERS.includes(p) && !paths.has(p)) errors.push(`demo without id: ${p}`);
+	for (const p of walk(DEMOS_DIR, ".meta.json"))
+		if (!paths.has(p)) errors.push(`sidecar without demo: ${p}.meta.json`);
+	const seen = new Set<string>();
+	for (const d of catalog) {
+		if (seen.has(d.id)) errors.push(`duplicate id: ${d.id}`);
+		seen.add(d.id);
+		if (!ID_PATTERN.test(d.id)) errors.push(`#${d.id} id: 3 digits up to 999, 4 digits from 1000`);
+		if (!existsSync(join(DEMOS_DIR, `${d.path}.svelte`))) {
+			errors.push(`#${d.id} missing file: ${d.path}`);
+			continue;
+		}
+		const metaFile = join(DEMOS_DIR, `${d.path}.meta.json`);
+		if (!existsSync(metaFile)) {
+			errors.push(`#${d.id} no sidecar: ${d.path}.meta.json`);
+			continue;
+		}
+		let meta: unknown;
+		try {
+			meta = JSON.parse(readFileSync(metaFile, "utf8"));
+		} catch (e) {
+			errors.push(`#${d.id} ${d.path}.meta.json: ${(e as Error).message}`);
+			continue;
+		}
+		const source = readFileSync(join(DEMOS_DIR, `${d.path}.svelte`), "utf8");
+		for (const e of checkMeta(meta, source, { known, ids, self: d.id }))
+			errors.push(`#${d.id} ${d.path}.meta.json: ${e}`);
+		const facets = (meta as { index?: IndexFacets }).index;
+		if (!facets) {
+			errors.push(`#${d.id} ${d.path}.meta.json: index: facets required (bun run index:backfill)`);
+			continue;
+		}
+		const range = checkIdRange(d.id, facets.kind, facets.subtype);
+		if (range) errors.push(`#${d.id} ${d.path}.meta.json: index: ${range}`);
+		const used = importedNames(source).filter((n) => known.has(n));
+		const listed = [...facets.components].sort().join();
+		if (listed !== [...used].sort().join())
+			errors.push(
+				`#${d.id} ${d.path}.meta.json: index.components must be the imports of the demo: ${used.join(", ") || "none"}`
+			);
+	}
+	if (paths.size !== catalog.length) errors.push("duplicate path in catalog");
+	return errors;
+}
+
+export function buildDemos(
+	manifest: Manifest,
+	catalog: readonly { id: string; path: string }[]
+): { demos: ManifestDemo[]; files: Record<string, string> } {
+	const known = new Set(manifest.components.map((c) => c.name));
+	const usages = demoUsages();
+	const demos = catalog.map(({ id, path }): ManifestDemo => {
+		const [group, page, variant] = path.split("/");
+		const file = join(DEMOS_DIR, `${path}.svelte`);
+		const source = readFileSync(file, "utf8");
+		const meta = JSON.parse(
+			readFileSync(file.replace(/\.svelte$/, ".meta.json"), "utf8")
+		) as DemoMeta;
+		const imports = [
+			...source.matchAll(/import\s*\{([^}]+)\}\s*from\s*["'](@codeatlasdev\/ui[^"']*)["']/g),
+		].map(([, names, from]) => ({
+			from,
+			names: names
+				.split(",")
+				.map(
+					(n) =>
+						n
+							.trim()
+							.replace(/^type\s+/, "")
+							.split(/\s+as\s+/)[0]
+				)
+				.filter(Boolean),
+		}));
+		const components = [...new Set(imports.flatMap((i) => i.names).filter((n) => known.has(n)))];
+		const use = usages.get(path);
+		const title = use?.title || variant;
+		const description = use?.description ?? "";
+		// Same transform as site/src/components/docs/Demo.astro (heading id).
+		const slug = title
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/^-|-$/g, "");
+		const peers = [...new Set(imports.map((i) => PEERS[i.from]).filter(Boolean))];
+		return {
+			id,
+			group,
+			page,
+			variant,
+			slug,
+			title,
+			description,
+			summary: meta.summary,
+			use: meta.use,
+			spec: meta.spec,
+			tags: meta.tags,
+			...(meta.names && { names: meta.names }),
+			...(meta.motion && { motion: meta.motion }),
+			shape: meta.shape,
+			index: meta.index,
+			components,
+			imports,
+			interactive: use?.interactive ?? false,
+			demo: `${SITE}/docs/${group}/${page}#${slug}`,
+			source,
+			needs: [`${PKG}@${manifest.version}`, ...peers].join(" + "),
+		};
+	});
+	const groups = [...new Set(demos.map((d) => d.group))].map((slug) => {
+		const g = demos.filter((d) => d.group === slug);
+		return { slug, first: g[0].id, last: g[g.length - 1].id, count: g.length };
+	});
+	const files: Record<string, string> = {
+		"catalog.json": `${JSON.stringify({ version: manifest.version, count: demos.length, groups, elements: demos.map(({ source: _, ...d }) => d) }, null, "\t")}\n`,
+		"en/catalog.tsv": `${["id\tgroup\tpage\ttitle\tnames\ttags\tsummary", ...demos.map((d) => [d.id, d.group, d.page, d.title, (d.names ?? []).join(" | "), d.tags.join(","), d.summary].map((v) => v.replace(/[\t\n]/g, " ")).join("\t"))].join("\n")}\n`,
+	};
+	const motionLines = (d: ManifestDemo) =>
+		d.motion?.length
+			? [
+					"Motion:",
+					...d.motion.map(
+						(m) =>
+							`- ${m.property}: ${m.duration} ${m.easing}${[
+								m.delay && ` delay ${m.delay}`,
+								m.stagger && ` stagger ${m.stagger}`,
+								m.spring && ` spring ${m.spring}`,
+							]
+								.filter(Boolean)
+								.join("")}`
+					),
+				]
+			: [];
+	const namesLine = (d: ManifestDemo) => (d.names?.length ? [`Names: ${d.names.join(" | ")}`] : []);
+	for (const d of demos) {
+		const header = [
+			`<!-- ${PKG} demo #${d.id} · MIT License (c) CodeAtlas · ${d.demo} -->`,
+			`Element: #${d.id} ${d.title} (${d.group}/${d.page})`,
+			`What it shows: ${d.summary}`,
+			`When to use: ${d.use}`,
+			"Spec:",
+			...d.spec.map((s) => `- ${s}`),
+			...motionLines(d),
+			...namesLine(d),
+			`Tags: ${d.tags.join(", ")}`,
+			`Needs: ${d.needs}`,
+			`Components: ${d.components.join(", ") || "none"}`,
+			`Live demo: ${d.demo}`,
+		];
+		files[`en/e/${d.id}.txt`] = `${header.join("\n")}\n\n${d.source}`;
+		files[`en/p/${d.id}.txt`] = `${[
+			`Use ${PKG} demo #${d.id} "${d.title}" (${d.group}/${d.page}).`,
+			`What it shows: ${d.summary.replace(/\.$/, "")}. When to use: ${d.use.replace(/\.$/, "")}.`,
+			"Spec:",
+			...d.spec.map((s) => `- ${s}`),
+			...motionLines(d),
+			...namesLine(d),
+			...(d.motion?.length
+				? [
+						"Reproduce the motion values exactly; do not guess timing or curves. Under prefers-reduced-motion render the final state.",
+					]
+				: []),
+			"Check first: Svelte 5 + @codeatlasdev/ui installed? theme in src/lib/theme.ts? Kit 2 or 3?",
+			`Apply: import only from "${PKG}[/charts|/map|/sound|/table|/code|/forms]"; keep component names, props and`,
+			"  variants of the reference as they are; no layout CSS, --ca-* tokens only (SKILL.md rules);",
+			"  replace sample data/copy with the project's; keep the first comment line.",
+			`Report: #${d.id} ${d.title} → file, what changed, ${d.demo}; what you could not check (light/dark, 375px, keyboard, reduced motion).`,
+			`Reference: ${API}/en/e/${d.id}.txt   Components API: ca-ui-mcp get_component(${d.components[0] ?? "…"})`,
+		].join("\n")}\n`;
+	}
+	return { demos, files };
+}
diff --git a/packages/ui/scripts/manifest/exports.ts b/packages/ui/scripts/manifest/exports.ts
new file mode 100644
index 00000000..bd3f1954
--- /dev/null
+++ b/packages/ui/scripts/manifest/exports.ts
@@ -0,0 +1,227 @@
+/** Non-component exports of every entry point: functions, stores, constants, classes and types, with signature and summary. */
+import { join, relative } from "node:path";
+import ts from "typescript";
+import { docProse, oneLine, propName } from "./ast.ts";
+import type { ManifestComponent } from "./components.ts";
+import { API_ENTRIES, LIB } from "./paths.ts";
+
+export type ExportKind = "function" | "store" | "const" | "class" | "type";
+
+export interface ManifestExport {
+	name: string;
+	/** Import specifier, e.g. `@codeatlasdev/ui/kit`. */
+	import: string;
+	kind: ExportKind;
+	/** One-line declaration: `function f(a: A): R`, `interface X { ... }`, `type T = ...`, `const x: T`. */
+	signature: string;
+	/** First paragraph of the JSDoc of the declaration (or of the comment right above it). */
+	description?: string;
+	/** Fields of an exported interface (or object type alias): name, type, optionality, JSDoc. */
+	members?: ManifestExportMember[];
+	/** Source file relative to `src/lib`. */
+	source: string;
+}
+
+export interface ManifestExportMember {
+	name: string;
+	type: string;
+	optional: boolean;
+	description?: string;
+}
+
+// ── non-component exports ─────────────────────────────────────────────────────
+
+/** Prose before the first `@tag` of the JSDoc attached to a declaration (a variable's doc sits on its statement). */
+function exportDoc(decl: ts.Declaration, sf: ts.SourceFile): string | undefined {
+	let node: ts.Node = decl;
+	if (ts.isBindingElement(node)) {
+		while (!ts.isVariableDeclaration(node)) node = node.parent;
+	}
+	if (ts.isVariableDeclaration(node)) node = node.parent.parent;
+	const own = ts.getJSDocCommentsAndTags(node).find(ts.isJSDoc);
+	if (own)
+		return docProse(
+			own
+				.getText(sf)
+				.replace(/^\/\*\*|\*\/$/g, "")
+				.replace(/^\s*\* ?/gm, "")
+		);
+	return undefined;
+}
+
+/** Fields of an interface or object type alias, with the JSDoc of each. Methods and index signatures are kept as written. */
+function exportMembers(
+	decl: ts.Declaration,
+	sf: ts.SourceFile
+): ManifestExportMember[] | undefined {
+	let elements: readonly ts.TypeElement[] | undefined;
+	if (ts.isInterfaceDeclaration(decl)) elements = decl.members;
+	else if (ts.isTypeAliasDeclaration(decl) && ts.isTypeLiteralNode(decl.type))
+		elements = decl.type.members;
+	if (!elements?.length) return undefined;
+	const out: ManifestExportMember[] = [];
+	for (const m of elements) {
+		if (!ts.isPropertySignature(m) && !ts.isMethodSignature(m)) continue;
+		const doc = ts.getJSDocCommentsAndTags(m).find(ts.isJSDoc);
+		const description = doc
+			? docProse(
+					doc
+						.getText(sf)
+						.replace(/^\/\*\*|\*\/$/g, "")
+						.replace(/^\s*\* ?/gm, "")
+				)
+			: undefined;
+		const type = ts.isPropertySignature(m)
+			? oneLine(m.type?.getText(sf) ?? "unknown")
+			: `(${m.parameters.map((p) => p.getText(sf)).join(", ")}) => ${oneLine(m.type?.getText(sf) ?? "void")}`;
+		out.push({
+			name: propName(m.name),
+			type,
+			optional: !!m.questionToken,
+			...(description ? { description } : {}),
+		});
+	}
+	return out.length ? out : undefined;
+}
+
+const TYPE_FLAGS =
+	ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
+
+/** `name?: Type` for one parameter: no default value; an unannotated parameter shows its inferred type. */
+function paramSignature(
+	p: ts.ParameterDeclaration,
+	sf: ts.SourceFile,
+	checker: ts.TypeChecker
+): string {
+	const type = p.type
+		? oneLine(p.type.getText(sf))
+		: oneLine(checker.typeToString(checker.getTypeAtLocation(p), p, TYPE_FLAGS));
+	const name = ts.isIdentifier(p.name) ? p.name.text : "options";
+	const dots = p.dotDotDotToken ? "..." : "";
+	return `${dots}${name}${p.questionToken || p.initializer ? "?" : ""}: ${type}`;
+}
+
+/** Declaration as one line without bodies, initializers, default values or comments. */
+function exportSignature(
+	name: string,
+	decl: ts.Declaration,
+	sf: ts.SourceFile,
+	checker: ts.TypeChecker
+): { kind: ExportKind; signature: string } {
+	if (ts.isFunctionDeclaration(decl)) {
+		const tp = decl.typeParameters
+			? `<${decl.typeParameters.map((t) => t.getText(sf)).join(", ")}>`
+			: "";
+		const sig = checker.getSignatureFromDeclaration(decl);
+		if (!decl.type && !sig) throw new Error(`cannot resolve the signature of ${name}`);
+		const ret = decl.type
+			? oneLine(decl.type.getText(sf))
+			: checker.typeToString(
+					checker.getReturnTypeOfSignature(sig as ts.Signature),
+					decl,
+					TYPE_FLAGS
+				);
+		const params = decl.parameters.map((p) => paramSignature(p, sf, checker)).join(", ");
+		return { kind: "function", signature: `function ${name}${tp}(${params}): ${oneLine(ret)}` };
+	}
+	if (ts.isInterfaceDeclaration(decl) || ts.isTypeAliasDeclaration(decl)) {
+		const text = decl
+			.getText(sf)
+			.replace(/\/\*[\s\S]*?\*\//g, "")
+			.replace(/\s\/\/.*$/gm, "")
+			.replace(/^export\s+/, "");
+		return { kind: "type", signature: oneLine(text) };
+	}
+	if (ts.isClassDeclaration(decl)) return { kind: "class", signature: `class ${name}` };
+	if (ts.isVariableDeclaration(decl) || ts.isBindingElement(decl)) {
+		const type = checker.getTypeAtLocation(decl);
+		const init = ts.isVariableDeclaration(decl) ? decl.initializer : undefined;
+		// `.svelte.ts` rune singletons (`const x = createXStore()`) expose getters + methods: report them as stores.
+		const store = /^create\w*Store\(/.test(init?.getText(sf) ?? "");
+		return {
+			kind: store ? "store" : "const",
+			signature: `const ${name}: ${constType(type, decl, checker)}`,
+		};
+	}
+	return { kind: "const", signature: name };
+}
+
+/** Getter without a setter, or a member declared `readonly` (an `as const` literal's properties are). */
+function isReadonlyMember(d: ts.Declaration): boolean {
+	if (ts.isGetAccessor(d)) {
+		const siblings = ts.isObjectLiteralExpression(d.parent)
+			? d.parent.properties
+			: d.parent.members;
+		return !siblings.some((m) => ts.isSetAccessor(m) && m.name.getText() === d.name.getText());
+	}
+	return (ts.getCombinedModifierFlags(d) & ts.ModifierFlags.Readonly) !== 0;
+}
+
+/** Longest one-line type shown as is; object types beyond it list one `name: type` member per line. */
+const MAX_TYPE = 100;
+
+/** A type as text: one line when short, otherwise an object type split one member per line. */
+function constType(type: ts.Type, at: ts.Node, checker: ts.TypeChecker): string {
+	const full = oneLine(checker.typeToString(type, at, TYPE_FLAGS));
+	if (full.length <= MAX_TYPE) return full;
+	const props = type.getProperties();
+	if (!props.length || !(type.flags & ts.TypeFlags.Object) || type.getCallSignatures().length)
+		return full;
+	const members = props.map((p) => {
+		const t = checker.getTypeOfSymbolAtLocation(p, at);
+		const text = oneLine(checker.typeToString(t, at, TYPE_FLAGS));
+		const readonly = !!p.declarations?.length && p.declarations.every(isReadonlyMember);
+		return `  ${readonly ? "readonly " : ""}${p.name}: ${text.length > MAX_TYPE ? `${text.slice(0, MAX_TYPE - 1)}…` : text};`;
+	});
+	return `{\n${members.join("\n")}\n}`;
+}
+
+/** Every export of every entry that is not a component and is declared in this package. */
+export function extractExports(components: ManifestComponent[]): ManifestExport[] {
+	const files = Object.values(API_ENTRIES).map((f) => join(LIB, f));
+	const program = ts.createProgram(files, {
+		target: ts.ScriptTarget.ESNext,
+		module: ts.ModuleKind.ESNext,
+		moduleResolution: ts.ModuleResolutionKind.Bundler,
+		allowImportingTsExtensions: true,
+		skipLibCheck: true,
+		noEmit: true,
+		types: [],
+	});
+	const checker = program.getTypeChecker();
+	const component = new Set(components.map((c) => `${c.import}:${c.name}`));
+	const out: ManifestExport[] = [];
+	for (const [entry, file] of Object.entries(API_ENTRIES)) {
+		const sf = program.getSourceFile(join(LIB, file));
+		const mod = sf && checker.getSymbolAtLocation(sf);
+		if (!mod) throw new Error(`cannot resolve entry ${file}`);
+		for (const exported of checker.getExportsOfModule(mod)) {
+			if (component.has(`${entry}:${exported.name}`)) continue;
+			const target =
+				exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+			const decl = target.declarations?.[0];
+			const declFile = decl?.getSourceFile();
+			// Foreign (`@internationalized/date`, `clsx`, svelte) symbols are not this package's API.
+			if (
+				!decl ||
+				!declFile ||
+				declFile.fileName.includes("node_modules") ||
+				declFile.fileName.endsWith(".svelte")
+			)
+				continue;
+			const { kind, signature } = exportSignature(exported.name, decl, declFile, checker);
+			const description = exportDoc(decl, declFile);
+			const members = exportMembers(decl, declFile);
+			out.push({
+				name: exported.name,
+				import: entry,
+				kind,
+				signature,
+				...(description ? { description } : {}),
+				...(members ? { members } : {}),
+				source: relative(LIB, declFile.fileName),
+			});
+		}
+	}
+	return out.sort((a, b) => a.import.localeCompare(b.import) || a.name.localeCompare(b.name));
+}
diff --git a/packages/ui/scripts/manifest/guides.ts b/packages/ui/scripts/manifest/guides.ts
new file mode 100644
index 00000000..0b6dc435
--- /dev/null
+++ b/packages/ui/scripts/manifest/guides.ts
@@ -0,0 +1,60 @@
+/** The docs site pages as markdown (offline `get_guide`), and the recipes parsed out of the Recipes page. */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { ENTRY_PAGES, parseRecipes, type Recipe } from "../ai-entry.ts";
+import { demoSources, mdxToMarkdown } from "../mdx-to-markdown.ts";
+import { DEMOS_DIR, DOCS_DIR } from "./paths.ts";
+
+export interface ManifestGuide {
+	/** Path under docs, e.g. `inputs/button`. */
+	slug: string;
+	title: string;
+	group: string;
+	description: string;
+	markdown: string;
+}
+
+export function mdxFiles(dir: string): string[] {
+	return readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+		e.isDirectory()
+			? mdxFiles(join(dir, e.name))
+			: e.name.endsWith(".mdx")
+				? [join(dir, e.name)]
+				: []
+	);
+}
+
+/** Raw demo source under site/src/demos, or undefined (also for paths that escape that folder). */
+function readDemo(demoPath: string): string | undefined {
+	const file = resolve(DEMOS_DIR, demoPath);
+	return file.startsWith(`${DEMOS_DIR}/`) && existsSync(file)
+		? readFileSync(file, "utf8")
+		: undefined;
+}
+
+export function buildGuides(): ManifestGuide[] {
+	if (!existsSync(DOCS_DIR)) return [];
+	return mdxFiles(DOCS_DIR)
+		.map((file) => {
+			const raw = readFileSync(file, "utf8");
+			const fm = raw.match(/^---\n([\s\S]*?)\n---\n/);
+			const field = (k: string) =>
+				fm?.[1].match(new RegExp(`^${k}:\\s*(.+)$`, "m"))?.[1].replace(/^["']|["']$/g, "") ?? "";
+			return {
+				slug: relative(DOCS_DIR, file)
+					.replaceAll("\\", "/")
+					.replace(/\.mdx$/, ""),
+				title: field("title"),
+				group: field("group"),
+				description: field("description"),
+				markdown: mdxToMarkdown(fm ? raw.slice(fm[0].length) : raw, demoSources(raw, readDemo)),
+			};
+		})
+		.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/** Recipes of the "Recipes" docs page (one per `## ` section with an example), for the offline `get_recipe`. */
+export function buildRecipes(guides = buildGuides()): Recipe[] {
+	const page = guides.find((g) => g.slug === ENTRY_PAGES.recipes);
+	return page ? parseRecipes(page.markdown) : [];
+}
diff --git a/packages/ui/scripts/manifest/paths.ts b/packages/ui/scripts/manifest/paths.ts
new file mode 100644
index 00000000..ef68ff36
--- /dev/null
+++ b/packages/ui/scripts/manifest/paths.ts
@@ -0,0 +1,35 @@
+/** Locations, entry points and URLs every manifest module shares. */
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+export const LIB = join(ROOT, "src/lib");
+export const PKG = "@codeatlasdev/ui";
+export const DOCS_DIR = resolve(ROOT, "../../site/src/content/docs");
+export const DEMOS_DIR = resolve(ROOT, "../../site/src/demos");
+export const SITE = "https://ui.codeatlas.com.br";
+export const API = `${SITE}/api/v1`;
+
+/** Public entry points: import specifier → entry file under src/lib. */
+export const ENTRIES: Record<string, string> = {
+	[PKG]: "index.ts",
+	[`${PKG}/charts`]: "charts/index.ts",
+	[`${PKG}/map`]: "map/index.ts",
+	[`${PKG}/sound`]: "sound/index.ts",
+	[`${PKG}/table`]: "components/DataTable/index.ts",
+	[`${PKG}/code`]: "components/CodeSnippet/index.ts",
+	[`${PKG}/forms`]: "forms/index.ts",
+};
+
+/** Entries whose non-component exports are documented: specifier → source file (mirrors package.json#exports). */
+export const API_ENTRIES: Record<string, string> = {
+	...ENTRIES,
+	[`${PKG}/kit`]: "kit/index.ts",
+	[`${PKG}/vite`]: "vite-plugin.ts",
+	[`${PKG}/astro`]: "astro.ts",
+	[`${PKG}/actions`]: "actions/index.ts",
+	[`${PKG}/seo`]: "seo/index.ts",
+	[`${PKG}/tokens`]: "tokens/index.ts",
+	[`${PKG}/utils/palette-generator`]: "utils/palette-generator.ts",
+	[`${PKG}/utils/color`]: "utils/color.ts",
+};
diff --git a/packages/ui/scripts/manifest/styling.ts b/packages/ui/scripts/manifest/styling.ts
new file mode 100644
index 00000000..d7dc2103
--- /dev/null
+++ b/packages/ui/scripts/manifest/styling.ts
@@ -0,0 +1,124 @@
+/** The override surface of a component, read from its CSS: parts, scoped variables, data attributes, tokens. */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { LIB } from "./paths.ts";
+
+export interface ManifestPart {
+	/** Class name without the dot, or a `@keyframes` name. */
+	name: string;
+	/** `false`: private (`ca-x-` prefix, `@keyframes`); it can be renamed in any release. */
+	stable: boolean;
+}
+
+export interface ManifestDataAttribute {
+	name: string;
+	/** Values the component CSS selects on (`[data-size='sm']`); empty when only its presence matters. */
+	values: string[];
+}
+
+export interface ManifestStyling {
+	parts: ManifestPart[];
+	/** Component-scoped `--ca-*` custom properties (not global tokens): set on the element to restyle one axis. */
+	variables: string[];
+	/** `data-*` attributes the component CSS selects on. */
+	data: ManifestDataAttribute[];
+}
+
+/** CSS text of a component: its `<style>` blocks plus every local `.css` it imports. */
+export function componentCss(src: string, dir: string): string {
+	const css = [...src.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/g)].map((m) => m[1]);
+	for (const m of src.matchAll(/import\s+['"](\.[^'"]+\.css)['"]/g)) {
+		const file = join(dir, m[1]);
+		if (existsSync(file)) css.push(readFileSync(file, "utf8"));
+	}
+	return css.join("\n");
+}
+
+/** Public `ca-*` class names a component's own CSS defines (descendant `:global()` targets owned elsewhere are skipped). */
+export function extractClasses(css: string): string[] {
+	const classes = new Set<string>();
+	for (const rule of css.replace(/\/\*[\s\S]*?\*\//g, "").matchAll(/([^{}]+)\{/g))
+		for (const part of rule[1].split(",")) {
+			// A selector that starts with `:global(` (or `:global .x`) is the component's own global class.
+			const sel = part.trim();
+			const owned = sel.startsWith(":global") ? sel : sel.replace(/:global\([^)]*\)/g, "");
+			for (const c of owned.matchAll(/\.(ca-[A-Za-z0-9_-]+)/g)) classes.add(c[1]);
+		}
+	return [...classes].sort();
+}
+
+/** A private class: `ca-x-` prefix, so a reader sees it is not a hook (naming rule, #381). */
+const INTERNAL_CLASS = /^ca-x-/;
+
+/** Every `--ca-*` the global stylesheets declare: these are tokens, documented in tokens.json. */
+let tokenNames: Set<string> | undefined;
+export function globalTokens(): Set<string> {
+	if (tokenNames) return tokenNames;
+	tokenNames = new Set();
+	const walk = (dir: string) => {
+		for (const e of readdirSync(dir, { withFileTypes: true })) {
+			if (e.isDirectory()) walk(join(dir, e.name));
+			else if (e.name.endsWith(".css"))
+				for (const m of readFileSync(join(dir, e.name), "utf8").matchAll(/(--ca-[\w-]+)\s*:/g))
+					tokenNames?.add(m[1]);
+		}
+	};
+	walk(join(LIB, "styles"));
+	return tokenNames;
+}
+
+/** `data-*` hooks a component CSS selects on, with the values it styles (`[data-size='sm']`). */
+export function extractDataAttributes(css: string): ManifestDataAttribute[] {
+	const found = new Map<string, Set<string>>();
+	for (const m of css
+		.replace(/\/\*[\s\S]*?\*\//g, "")
+		.matchAll(/\[(data-[a-z][a-z0-9-]*)(?:[~|^$*]?=(?:'([^']*)'|"([^"]*)"|([^\]\s]+)))?\s*\]/g)) {
+		const values = found.get(m[1]) ?? new Set<string>();
+		const v = m[2] ?? m[3] ?? m[4];
+		if (v !== undefined) values.add(v);
+		found.set(m[1], values);
+	}
+	return [...found]
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([name, values]) => ({ name, values: [...values].sort() }));
+}
+
+/**
+ * The override surface of a component: classes (stable unless `ca-x-` or a `@keyframes` name), the
+ * component-scoped custom properties it declares or reads (`tokens` are excluded: they live in tokens.json)
+ * and the `data-*` attributes its CSS selects on.
+ */
+export function extractStyling(
+	css: string,
+	_source: string,
+	tokens = new Set<string>()
+): ManifestStyling {
+	const bare = css.replace(/\/\*[\s\S]*?\*\//g, "");
+	const keyframes = [...bare.matchAll(/@keyframes\s+(ca-[A-Za-z0-9_-]+)/g)].map((m) => m[1]);
+	const names = new Set([...extractClasses(css), ...keyframes]);
+	// Plain code-unit order, like `extractClasses`: `classes` (the stable subset) keeps its historical order.
+	const parts = [...names]
+		.sort()
+		.map((name) => ({ name, stable: !INTERNAL_CLASS.test(name) && !keyframes.includes(name) }));
+	const variables = [
+		...new Set(
+			[...bare.matchAll(/(--ca-[\w-]+)\s*:|var\(\s*(--ca-[\w-]+)/g)]
+				.map((m) => m[1] ?? m[2])
+				.filter((v) => !tokens.has(v))
+		),
+	].sort();
+	return { parts, variables, data: extractDataAttributes(css) };
+}
+
+/**
+ * Component tokens of a component's own CSS: `var(--ca-<stem>-…, fallback)` reads, where `<stem>` is
+ * the stem of one of its classes (`ca-icon-btn--sm` → `icon-btn`). The fallback marks an override
+ * hook: a token read without one is a global token owned elsewhere (`--ca-space-3`).
+ */
+export function extractComponentTokens(css: string, classes: string[]): string[] {
+	const stems = new Set(classes.map((c) => c.slice(3).split(/--|__/)[0]));
+	const tokens = new Set<string>();
+	for (const m of css.replace(/\/\*[\s\S]*?\*\//g, "").matchAll(/var\((--ca-([a-z0-9-]+?))\s*,/g))
+		if ([...stems].some((s) => m[2] === s || m[2].startsWith(`${s}-`))) tokens.add(m[1]);
+	return [...tokens].sort();
+}
diff --git a/packages/ui/scripts/manifest/tokens.ts b/packages/ui/scripts/manifest/tokens.ts
new file mode 100644
index 00000000..b779742a
--- /dev/null
+++ b/packages/ui/scripts/manifest/tokens.ts
@@ -0,0 +1,175 @@
+/** Design tokens (`--ca-*` custom properties) and surface styles (`[data-style]` blocks of materials.css). */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { STYLES, type SurfaceStyle } from "../../src/lib/theme/define.ts";
+import { DESIGN_STYLES } from "../../src/lib/theme/styles.ts";
+import { LIB } from "./paths.ts";
+
+// ── tokens ────────────────────────────────────────────────────────────────────
+
+export interface ManifestToken {
+	name: string;
+	/** Value in `:root` (light / default). */
+	value: string;
+	/** Value under `.dark`, when it differs. */
+	dark?: string;
+	/** Where it is defined: `tokens.css` or `presets/<id>.css`. */
+	source: string;
+	/** Nearest preceding section comment, e.g. "Spacing scale". */
+	group?: string;
+	/** Comment immediately above the declaration: what the token is for and its guarantees. */
+	description?: string;
+}
+
+/** `── Spacing scale (base 4 px) ──` section dividers inside CSS comments. */
+const SECTION = /^\s*──\s*([^─(\n*]+?)\s*(?:\(|─|\*|$)/m;
+
+/** Parse `--ca-*: value;` declarations per rule, keeping `:root` and `.dark` values apart. */
+export function extractTokens(css: string, source: string, out: Map<string, ManifestToken>) {
+	let group: string | undefined;
+	for (const rule of css.matchAll(/(?:\/\*[\s\S]*?\*\/\s*)*([^{}/]+)\{([^{}]*)\}/g)) {
+		const selector = rule[1].trim();
+		// `.dark` rules (also `.dark[data-preset=..]`, `.dark [data-preset=..]`) fill the dark value.
+		const isDark = /\.dark\b|data-theme-scope="dark"/.test(selector);
+		// Walk the body so section comments between declarations update `group` in order.
+		let note: string | undefined;
+		for (const t of rule[2].matchAll(/\/\*([\s\S]*?)\*\/|(--ca-[\w-]+)\s*:\s*([^;]+);/g)) {
+			if (t[1] !== undefined) {
+				const section = t[1].match(SECTION)?.[1];
+				if (section) group = section;
+				// A prose comment (not a `── Section ──` divider) documents the declaration right below it.
+				else note = t[1].replace(/\s*\n\s*\*?\s*/g, " ").trim() || undefined;
+				continue;
+			}
+			const description = note;
+			note = undefined;
+			const name = t[2];
+			const value = t[3]
+				.trim()
+				.replace(/\s+/g, " ")
+				.replace(/\s*\/\*[\s\S]*?\*\//g, "");
+			const prev = out.get(name);
+			if (!prev) {
+				const t0: ManifestToken = isDark
+					? { name, value: "", dark: value, source, group }
+					: { name, value, source, group };
+				if (description) t0.description = description;
+				out.set(name, t0);
+			} else {
+				if (isDark) prev.dark ??= value;
+				else if (prev.value === "") prev.value = value;
+				if (description) prev.description ??= description;
+			}
+		}
+	}
+}
+
+export function buildTokens(): ManifestToken[] {
+	const out = new Map<string, ManifestToken>();
+	const styles = join(LIB, "styles");
+	extractTokens(readFileSync(join(styles, "tokens.css"), "utf8"), "tokens.css", out);
+	// Built-ins repeat the same names per preset; the amber file (`:root` default) is the canonical value.
+	const presets = join(styles, "presets");
+	extractTokens(readFileSync(join(presets, "amber.css"), "utf8"), "presets/amber.css", out);
+	return [...out.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// ── surfaces ──────────────────────────────────────────────────────────────────
+
+export interface ManifestSurface {
+	/** Value of `<html data-style>` (and `colorScheme.setStyle`). */
+	id: SurfaceStyle;
+	/** The comment above the `[data-style="id"]` block in materials.css. */
+	description?: string;
+	/**
+	 * What the style does to every `--ca-blur-*` token: `full` leaves the `:root` glass blur,
+	 * `reduced` rewrites it to a lighter blur, `none` turns it off (opaque surfaces).
+	 */
+	blur: "full" | "reduced" | "none";
+	/** Every custom property the `[data-style]` blocks of this id rewrite, in first-seen order. */
+	tokens: string[];
+	/** The package default (`defineTheme` without `defaultStyle`). */
+	packageDefault: boolean;
+	/** Design recipes (`designStyle(id)`) whose `defaultStyle` is this one. */
+	recipes: string[];
+}
+
+/** `[data-style="x"]` selectors of a rule, with or without a `.dark`/`html` prefix. */
+const STYLE_SELECTOR = /\[data-style="([a-z]+)"\]/g;
+const BLUR_TOKEN = /^--ca-(?:blur-[a-z-]+|(?:overlay|panel|chrome|upload)-blur)$/;
+
+/** Read the surface styles out of `[data-style]` rules: blur behaviour, rewritten tokens, description. */
+export function extractSurfaces(
+	css: string
+): Pick<ManifestSurface, "id" | "description" | "blur" | "tokens">[] {
+	const acc = new Map<
+		string,
+		{ description?: string; own?: boolean; tokens: Map<string, string> }
+	>();
+	for (const rule of css.matchAll(/((?:\/\*[\s\S]*?\*\/\s*)*)([^{}/]+)\{([^{}]*)\}/g)) {
+		const ids = [...rule[2].matchAll(STYLE_SELECTOR)].map((m) => m[1]);
+		if (!ids.length) continue;
+		// The nearest comment above the block: `── Solid — opaque, no blur ── ` → "Solid — opaque, no blur".
+		const note = [...rule[1].matchAll(/\/\*([\s\S]*?)\*\//g)].pop()?.[1];
+		const description = note
+			?.replace(/^[\s*─-]*|[\s*─-]*$/g, "")
+			.replace(/\s*\n\s*\*?\s*/g, " ")
+			.replace(/\s*─+.*$/, "")
+			.trim();
+		const decls = [...rule[3].matchAll(/(--ca-[\w-]+)\s*:\s*([^;]+);/g)];
+		for (const id of ids) {
+			const cur = acc.get(id) ?? { tokens: new Map<string, string>() };
+			// A style's own block comment beats the comment of a grouped rule that lists it with others.
+			if (description && (cur.description === undefined || (ids.length === 1 && !cur.own))) {
+				cur.description = description;
+				cur.own = ids.length === 1;
+			}
+			for (const d of decls) if (!cur.tokens.has(d[1])) cur.tokens.set(d[1], d[2].trim());
+			acc.set(id, cur);
+		}
+	}
+	return [...acc].map(([id, v]) => {
+		const blurs = [...v.tokens].filter(([name]) => BLUR_TOKEN.test(name));
+		const blur = !blurs.length
+			? "full"
+			: blurs.every(([, value]) => value === "none")
+				? "none"
+				: "reduced";
+		return {
+			id: id as SurfaceStyle,
+			description: v.description,
+			blur,
+			tokens: [...v.tokens.keys()],
+		};
+	});
+}
+
+/** Styles with no `[data-style]` block: glass is the `:root` token set every other style rewrites (it is opt-in; the package default is solid). */
+const GLASS_DESCRIPTION: Partial<Record<SurfaceStyle, string>> = {
+	glass:
+		"Glass (opt-in): the :root tokens untouched, full blur, translucent tints, glow and rim (the look of the liquid recipe)",
+};
+
+/**
+ * Every surface style, from `materials.css`: the `[data-style]` blocks give the blur and the tokens,
+ * `STYLES` gives the valid ids (glass is the `:root` set, it has no block), `DESIGN_STYLES` the recipes.
+ */
+export function buildSurfaces(): ManifestSurface[] {
+	const found = new Map(
+		extractSurfaces(readFileSync(join(LIB, "styles/materials.css"), "utf8")).map((s) => [s.id, s])
+	);
+	return STYLES.map((id) => {
+		const f = found.get(id);
+		const description = f?.description ?? GLASS_DESCRIPTION[id];
+		return {
+			id,
+			...(description ? { description } : {}),
+			blur: f?.blur ?? "full",
+			tokens: f?.tokens ?? [],
+			packageDefault: id === "solid",
+			recipes: Object.values(DESIGN_STYLES)
+				.filter((d) => (d.theme.defaultStyle ?? "solid") === id)
+				.map((d) => d.id),
+		};
+	});
+}
diff --git a/packages/ui/scripts/manifest/writers.ts b/packages/ui/scripts/manifest/writers.ts
new file mode 100644
index 00000000..00e8ffcb
--- /dev/null
+++ b/packages/ui/scripts/manifest/writers.ts
@@ -0,0 +1,153 @@
+/** Writers: the parts file, API.md (agent skill reference) and DEMOS.md (demo catalog table). */
+import type { Manifest } from "./components.ts";
+import type { ManifestDemo } from "./demos.ts";
+import { API } from "./paths.ts";
+import type { ManifestDataAttribute, ManifestPart, ManifestStyling } from "./styling.ts";
+
+export function demosMarkdown(demos: ManifestDemo[]): string {
+	return `${[
+		"<!-- generated by packages/ui/scripts/build-manifest.ts (bun run --cwd packages/ui manifest -- --skill). Do not edit. -->",
+		"# Demo catalog",
+		"",
+		`Every demo has a stable number. Fetch one with \`get_demo\` (MCP) or ${API}/en/e/NNN.txt.`,
+		"",
+		"| id | title | group/page | components |",
+		"|---|---|---|---|",
+		...demos.map(
+			(d) => `| ${d.id} | ${cell(d.title)} | ${d.group}/${d.page} | ${d.components.join(", ")} |`
+		),
+	].join("\n")}\n`;
+}
+
+const cell = (v: string) => v.replace(/\|/g, "\\|");
+
+/** One component's override surface: stable parts, internal parts, scoped variables, data attributes. */
+function stylingLines(s: ManifestStyling): string[] {
+	const code = (xs: string[]) => xs.map((x) => `\`${x}\``).join(" ");
+	const lines: string[] = [];
+	const stable = s.parts.filter((p) => p.stable).map((p) => p.name);
+	const internal = s.parts.filter((p) => !p.stable).map((p) => p.name);
+	if (stable.length) lines.push(`Parts: ${code(stable)}`, "");
+	if (internal.length) lines.push(`Internal (may change in any release): ${code(internal)}`, "");
+	if (s.variables.length) lines.push(`Variables: ${code(s.variables)}`, "");
+	if (s.data.length)
+		lines.push(
+			`Data attributes: ${s.data.map((d) => `\`${d.name}\`${d.values.length ? ` (${d.values.map((v) => `\`${v}\``).join(" ")})` : ""}`).join(", ")}`,
+			""
+		);
+	return lines;
+}
+
+export interface PartsFile {
+	name: string;
+	version: string;
+	/** Naming rule, repeated in the file so a consumer tool needs nothing else. */
+	rule: string;
+	components: {
+		name: string;
+		import: string;
+		parts: ManifestPart[];
+		variables: string[];
+		data: ManifestDataAttribute[];
+	}[];
+}
+
+const PARTS_RULE =
+	"A `ca-*` class owned by a component is a stable part: renaming or removing it is a breaking change. A `ca-x-*` class and every @keyframes name is internal and may change in any release. Variables and data attributes listed here are stable.";
+
+/** The stable override surface of every component that has one, for `parts.json`, `list_parts` and `workarounds`. */
+export function buildParts(m: Manifest): PartsFile {
+	return {
+		name: m.name,
+		version: m.version,
+		rule: PARTS_RULE,
+		components: m.components
+			.filter((c) => c.styling.parts.length || c.styling.variables.length || c.styling.data.length)
+			.map((c) => ({ name: c.name, import: c.import, ...c.styling })),
+	};
+}
+
+/** Markdown of the override surface, one section per component. Deterministic. */
+export function partsMarkdown(m: Manifest): string {
+	const out = [PARTS_RULE, ""];
+	for (const c of buildParts(m).components) out.push(`## ${c.name}`, "", ...stylingLines(c));
+	return `${out
+		.join("\n")
+		.replace(/\n{3,}/g, "\n\n")
+		.trimEnd()}\n`;
+}
+
+/** Markdown reference of every component's props, snippets and classes, then every other export's signature. Deterministic. */
+export function skillMarkdown(m: Manifest): string {
+	const out = [
+		"<!-- generated by packages/ui/scripts/build-manifest.ts (bun run --cwd packages/ui manifest -- --skill). Do not edit. -->",
+		"# Component API reference",
+		"",
+		`Describes ${m.name}@${m.version}. If the project has another version installed, this file may list props that do not exist there (or miss ones that do): the installed package is the source of truth, through \`ca-ui-mcp\` (\`get_component\`, \`get_export\`) or \`node_modules/${m.name}/dist/components.json\`.`,
+		"",
+		"Generated from the source types: every prop, default and public `ca-*` class. Hand-written usage examples are in [COMPONENTS.md](./COMPONENTS.md).",
+		"Import from the path in each heading. Charts, DataTable, CodeSnippet and the `forms` fields are subpath imports.",
+		"",
+	];
+	for (const c of m.components) {
+		out.push(
+			`## ${c.name}`,
+			"",
+			`\`import { ${c.name} } from "${c.import}"\`${c.generics ? ` (generic: \`${c.generics}\`)` : ""}`,
+			""
+		);
+		if (c.deprecated) out.push(`**Deprecated. ${c.deprecated}**`, "");
+		if (c.description) out.push(c.description, "");
+		if (c.props.length) {
+			out.push("| Prop | Type | Default | Notes |", "|---|---|---|---|");
+			for (const p of c.props)
+				out.push(
+					`| \`${p.name}${p.optional ? "?" : ""}\` | \`${cell(p.type)}\` | ${p.default ? `\`${cell(p.default)}\`` : ""} | ${[p.bindable ? "`bind:`" : "", p.description ? cell(p.description) : ""].filter(Boolean).join(" ")} |`
+				);
+			out.push("");
+		}
+		if (c.snippets.length)
+			out.push(
+				`Snippets: ${c.snippets.map((x) => `\`${x.name}\`${x.type.includes("<") ? ` (\`${cell(x.type)}\`)` : ""}${x.description ? `: ${cell(x.description)}` : ""}`).join("; ")}`,
+				""
+			);
+		if (c.extends) out.push(`Also accepts: \`${cell(c.extends)}\``, "");
+		out.push(...stylingLines(c.styling));
+		if (c.tokens.length) out.push(`Tokens: ${c.tokens.map((x) => `\`${x}\``).join(" ")}`, "");
+	}
+	out.push(
+		"# Non-component exports",
+		"",
+		"Functions, stores, constants and types every entry point exports besides components. Import from the path in each heading; types use `import type`."
+	);
+	for (const entry of [...new Set(m.exports.map((e) => e.import))]) {
+		const here = m.exports.filter((x) => x.import === entry);
+		out.push("", `## ${entry}`, "");
+		for (const e of here.filter((x) => x.kind !== "type")) {
+			out.push(`### ${e.name}`, "", `\`import { ${e.name} } from "${entry}"\``, "");
+			if (e.description) out.push(e.description, "");
+			out.push("```ts", e.signature, "```", "");
+		}
+		const types = here.filter((x) => x.kind === "type");
+		if (types.length) {
+			out.push("Types:", "", "| Type | Declaration | Notes |", "|---|---|---|");
+			for (const t of types)
+				out.push(
+					`| \`${t.name}\` | \`${cell(t.signature)}\` | ${t.description ? cell(t.description) : ""} |`
+				);
+			out.push("");
+			for (const t of types.filter((x) => x.members)) {
+				out.push(`#### ${t.name}`, "", "| Field | Type | Notes |", "|---|---|---|");
+				for (const f of t.members ?? [])
+					out.push(
+						`| \`${f.name}${f.optional ? "?" : ""}\` | \`${cell(f.type)}\` | ${f.description ? cell(f.description) : ""} |`
+					);
+				out.push("");
+			}
+		}
+	}
+	return `${out
+		.join("\n")
+		.replace(/\n{3,}/g, "\n\n")
+		.trimEnd()}\n`;
+}