@bettercms-ai/kit 1.0.0 → 2.0.0

package/dist/library/catalog.js

@@ -0,0 +1,307 @@
+import { BLOCK_LIBRARY, EXAMPLES } from "./examples/index.js";
+import { KIT_LIBRARY } from "./entries/index.js";
+import { CORE_NOTES } from "./coreNotes.js";
+//#region src/library/catalog.ts
+/**
+* Kit Library catalog — the library entries (`./entries/*.entries.ts`) plus the
+* original Block Kit examples ("Core examples"), normalised into one list the page, the coverage matrix and
+* the search use. Pure data: no React.
+*/
+var CORE_CATEGORY = "Core examples";
+/** Display order of the categories (the contract's union order). */
+var CATEGORY_ORDER = [
+	"Navigation & chrome",
+	"Heroes",
+	"Features & storytelling",
+	"Social proof",
+	"Media & galleries",
+	"Commerce",
+	"Pricing & plans",
+	"Conversion & forms",
+	"Listings & feeds",
+	"Long-form & docs",
+	"Company & people",
+	"Events & places",
+	"Data & interactive",
+	"Advanced patterns"
+];
+/** Every edge tag, in a reading order (structure → content → behaviour → output). */
+var EDGE_TAGS = [
+	{
+		tag: "deep-nesting",
+		label: "Deep nesting",
+		hint: "4+ levels of drill-in"
+	},
+	{
+		tag: "repeater",
+		label: "Repeater",
+		hint: "Arrays of objects"
+	},
+	{
+		tag: "polymorphic-array",
+		label: "Polymorphic array",
+		hint: "Array of mixed block types"
+	},
+	{
+		tag: "slots",
+		label: "Slots",
+		hint: "Blocks placed inside a block"
+	},
+	{
+		tag: "variants",
+		label: "Variants",
+		hint: "Layout variants of one block"
+	},
+	{
+		tag: "conditional",
+		label: "Conditional",
+		hint: "Fields shown or hidden by other values"
+	},
+	{
+		tag: "references",
+		label: "References",
+		hint: "Links to pages or CMS items"
+	},
+	{
+		tag: "dynamic-query",
+		label: "Dynamic query",
+		hint: "Pulls N items from a collection by filter"
+	},
+	{
+		tag: "global-synced",
+		label: "Global / synced",
+		hint: "Shared block with per-instance overrides"
+	},
+	{
+		tag: "localized",
+		label: "Localized",
+		hint: "Per-field translations"
+	},
+	{
+		tag: "rich-text",
+		label: "Rich text",
+		hint: "Portable text body with embeds"
+	},
+	{
+		tag: "media-heavy",
+		label: "Media-heavy",
+		hint: "Images, video, galleries, focal points"
+	},
+	{
+		tag: "embed",
+		label: "Embed",
+		hint: "iframe, HTML, code or third-party"
+	},
+	{
+		tag: "form",
+		label: "Form",
+		hint: "Collects visitor input"
+	},
+	{
+		tag: "commerce",
+		label: "Commerce",
+		hint: "Price, inventory, variants"
+	},
+	{
+		tag: "personalization",
+		label: "Personalization",
+		hint: "Audience or A/B variants"
+	},
+	{
+		tag: "validation",
+		label: "Validation",
+		hint: "Limits, required, patterns"
+	},
+	{
+		tag: "a11y",
+		label: "Accessibility",
+		hint: "Alt text, captions, labels"
+	},
+	{
+		tag: "seo-structured",
+		label: "SEO structured",
+		hint: "Emits JSON-LD"
+	},
+	{
+		tag: "responsive-layout",
+		label: "Responsive layout",
+		hint: "Per-breakpoint layout settings"
+	}
+];
+var TAG_LABEL = Object.fromEntries(EDGE_TAGS.map((t) => [t.tag, t.label]));
+/** Edge cases the original examples exercise (they predate the contract, so the library assigns them). */
+var CORE_TAGS = {
+	faq: [
+		"repeater",
+		"conditional",
+		"validation",
+		"dynamic-query"
+	],
+	megaMenu: [
+		"deep-nesting",
+		"repeater",
+		"global-synced",
+		"validation"
+	],
+	tabs: [
+		"slots",
+		"polymorphic-array",
+		"repeater",
+		"variants"
+	],
+	pricing: [
+		"repeater",
+		"conditional",
+		"commerce",
+		"variants",
+		"validation"
+	],
+	bento: [
+		"slots",
+		"polymorphic-array",
+		"variants",
+		"responsive-layout",
+		"media-heavy"
+	],
+	journalStory: [
+		"rich-text",
+		"references",
+		"media-heavy",
+		"seo-structured",
+		"localized",
+		"validation",
+		"embed"
+	],
+	hero: [
+		"variants",
+		"media-heavy",
+		"localized",
+		"a11y"
+	]
+};
+var CORE_LAYOUT = {
+	faq: "accordion",
+	megaMenu: "nav",
+	tabs: "tabs",
+	pricing: "grid-3",
+	bento: "bento",
+	journalStory: "article",
+	hero: "split"
+};
+var hayOf = (parts) => parts.filter(Boolean).join(" 
 ").toLowerCase();
+function fromEntry(e) {
+	return {
+		id: e.id,
+		ex: e,
+		entry: e,
+		core: false,
+		category: e.category,
+		tags: e.tags ?? [],
+		notes: e.notes,
+		brand: e.brand,
+		previewLayout: e.previewLayout,
+		hay: hayOf([
+			e.label,
+			e.schema.title,
+			e.schema.name,
+			e.schema.description,
+			e.proves,
+			e.category,
+			e.brand,
+			...(e.tags ?? []).map((t) => `${t} ${TAG_LABEL[t] ?? ""}`),
+			...e.notes?.htmlSignals ?? []
+		])
+	};
+}
+function fromCore(x) {
+	const tags = CORE_TAGS[x.id] ?? [];
+	const notes = CORE_NOTES[x.id];
+	return {
+		id: `core-${x.id}`,
+		ex: x,
+		core: true,
+		category: CORE_CATEGORY,
+		tags,
+		notes,
+		brand: "Caldera",
+		previewLayout: CORE_LAYOUT[x.id],
+		hay: hayOf([
+			x.label,
+			x.schema.title,
+			x.schema.name,
+			x.schema.description,
+			x.proves,
+			CORE_CATEGORY,
+			...tags.map((t) => `${t} ${TAG_LABEL[t] ?? ""}`),
+			...notes?.htmlSignals ?? []
+		])
+	};
+}
+var catRank = (c) => {
+	const i = CATEGORY_ORDER.indexOf(c);
+	return c === "Core examples" ? 1e3 : i === -1 ? 500 : i;
+};
+/** Library entries (sorted by category order, then file order) followed by the core examples. Ids are unique. */
+function buildCatalog(library = KIT_LIBRARY) {
+	const seen = /* @__PURE__ */ new Set();
+	return [...library.filter((e) => e && e.id && e.schema && !seen.has(e.id) && (seen.add(e.id), true)).map(fromEntry).map((it, i) => ({
+		it,
+		i
+	})).sort((a, b) => catRank(a.it.category) - catRank(b.it.category) || a.i - b.i).map((x) => x.it), ...EXAMPLES.map(fromCore)];
+}
+var CATALOG = buildCatalog();
+/** Categories present in a list, in display order, with counts. */
+function categoriesOf(items) {
+	const m = /* @__PURE__ */ new Map();
+	for (const it of items) m.set(it.category, (m.get(it.category) ?? 0) + 1);
+	return [...m.entries()].sort((a, b) => catRank(a[0]) - catRank(b[0])).map(([category, count]) => ({
+		category,
+		count
+	}));
+}
+/** Every term must appear somewhere in the haystack. */
+function matches(it, terms, tags) {
+	if (tags.length && !tags.every((t) => it.tags.includes(t))) return false;
+	return terms.every((t) => it.hay.includes(t));
+}
+var termsOf = (q) => q.trim().toLowerCase().split(/\s+/).filter(Boolean);
+/**
+* Block schemas a slot can resolve: the shared example blocks plus every library entry whose schema is a block
+* (so an entry may place another entry's block in a slot by its schema name). First definition wins.
+*/
+var LIBRARY_BLOCKS = (() => {
+	const out = [];
+	const names = /* @__PURE__ */ new Set();
+	for (const s of [
+		...BLOCK_LIBRARY,
+		...KIT_LIBRARY.flatMap((e) => e.blocks ?? []),
+		...KIT_LIBRARY.map((e) => e.schema)
+	]) {
+		if (!s?.name || names.has(s.name)) continue;
+		names.add(s.name);
+		out.push(s);
+	}
+	return out;
+})();
+var BLOCK_BY_NAME = new Map(LIBRARY_BLOCKS.map((b) => [b.name, b]));
+var resolveLibraryBlock = (type) => BLOCK_BY_NAME.get(type);
+/** Blocks offered by "+ Add block": only real blocks (not entries / pages). */
+var PICKABLE_BLOCKS = LIBRARY_BLOCKS.filter((b) => b.kind === "block");
+/** Slot resolution for one catalog item: its entry-local `blocks` first (contract), then the shared library. */
+function blocksFor(it) {
+	const local = it.entry?.blocks?.filter((b) => b?.name) ?? [];
+	if (!local.length) return {
+		resolve: resolveLibraryBlock,
+		library: PICKABLE_BLOCKS
+	};
+	const own = new Map(local.map((b) => [b.name, b]));
+	const names = new Set(local.map((b) => b.name));
+	return {
+		resolve: (type) => own.get(type) ?? BLOCK_BY_NAME.get(type),
+		library: [...local, ...PICKABLE_BLOCKS.filter((b) => !names.has(b.name))]
+	};
+}
+//#endregion
+export { CATALOG, CATEGORY_ORDER, CORE_CATEGORY, EDGE_TAGS, LIBRARY_BLOCKS, PICKABLE_BLOCKS, TAG_LABEL, blocksFor, buildCatalog, categoriesOf, matches, resolveLibraryBlock, termsOf };
+
+//# sourceMappingURL=catalog.js.map

package/dist/library/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","names":[],"sources":["../../src/library/catalog.ts"],"sourcesContent":["/**\n * Kit Library catalog — the library entries (`./entries/*.entries.ts`) plus the\n * original Block Kit examples (\"Core examples\"), normalised into one list the page, the coverage matrix and\n * the search use. Pure data: no React.\n */\nimport { BLOCK_LIBRARY, EXAMPLES, type KitExample } from \"./examples\";\nimport { KIT_LIBRARY } from \"./entries\";\nimport { CORE_NOTES } from \"./coreNotes\";\nimport type { EdgeTag, KitCategory, KitEntry, KitModelNotes, KitPreviewLayout } from \"./types\";\nimport type { TypeSchema } from \"../schema/types\";\n\nexport const CORE_CATEGORY = \"Core examples\" as const;\nexport type CatalogCategory = KitCategory | typeof CORE_CATEGORY;\n\n/** Display order of the categories (the contract's union order). */\nexport const CATEGORY_ORDER: KitCategory[] = [\n  \"Navigation & chrome\",\n  \"Heroes\",\n  \"Features & storytelling\",\n  \"Social proof\",\n  \"Media & galleries\",\n  \"Commerce\",\n  \"Pricing & plans\",\n  \"Conversion & forms\",\n  \"Listings & feeds\",\n  \"Long-form & docs\",\n  \"Company & people\",\n  \"Events & places\",\n  \"Data & interactive\",\n  \"Advanced patterns\",\n];\n\n/** Every edge tag, in a reading order (structure → content → behaviour → output). */\nexport const EDGE_TAGS: { tag: EdgeTag; label: string; hint: string }[] = [\n  { tag: \"deep-nesting\", label: \"Deep nesting\", hint: \"4+ levels of drill-in\" },\n  { tag: \"repeater\", label: \"Repeater\", hint: \"Arrays of objects\" },\n  { tag: \"polymorphic-array\", label: \"Polymorphic array\", hint: \"Array of mixed block types\" },\n  { tag: \"slots\", label: \"Slots\", hint: \"Blocks placed inside a block\" },\n  { tag: \"variants\", label: \"Variants\", hint: \"Layout variants of one block\" },\n  { tag: \"conditional\", label: \"Conditional\", hint: \"Fields shown or hidden by other values\" },\n  { tag: \"references\", label: \"References\", hint: \"Links to pages or CMS items\" },\n  { tag: \"dynamic-query\", label: \"Dynamic query\", hint: \"Pulls N items from a collection by filter\" },\n  { tag: \"global-synced\", label: \"Global / synced\", hint: \"Shared block with per-instance overrides\" },\n  { tag: \"localized\", label: \"Localized\", hint: \"Per-field translations\" },\n  { tag: \"rich-text\", label: \"Rich text\", hint: \"Portable text body with embeds\" },\n  { tag: \"media-heavy\", label: \"Media-heavy\", hint: \"Images, video, galleries, focal points\" },\n  { tag: \"embed\", label: \"Embed\", hint: \"iframe, HTML, code or third-party\" },\n  { tag: \"form\", label: \"Form\", hint: \"Collects visitor input\" },\n  { tag: \"commerce\", label: \"Commerce\", hint: \"Price, inventory, variants\" },\n  { tag: \"personalization\", label: \"Personalization\", hint: \"Audience or A/B variants\" },\n  { tag: \"validation\", label: \"Validation\", hint: \"Limits, required, patterns\" },\n  { tag: \"a11y\", label: \"Accessibility\", hint: \"Alt text, captions, labels\" },\n  { tag: \"seo-structured\", label: \"SEO structured\", hint: \"Emits JSON-LD\" },\n  { tag: \"responsive-layout\", label: \"Responsive layout\", hint: \"Per-breakpoint layout settings\" },\n];\nexport const TAG_LABEL: Record<string, string> = Object.fromEntries(EDGE_TAGS.map((t) => [t.tag, t.label]));\n\nexport interface CatalogItem {\n  /** URL id: the entry id, or `core-{id}` for the original examples */\n  id: string;\n  ex: KitExample;\n  entry?: KitEntry;\n  core: boolean;\n  category: CatalogCategory;\n  tags: EdgeTag[];\n  notes?: KitModelNotes;\n  brand?: string;\n  previewLayout?: KitPreviewLayout;\n  /** lower-cased haystack: name, description, proves, category, tags, html signals, brand */\n  hay: string;\n}\n\n/** Edge cases the original examples exercise (they predate the contract, so the library assigns them). */\nconst CORE_TAGS: Record<string, EdgeTag[]> = {\n  faq: [\"repeater\", \"conditional\", \"validation\", \"dynamic-query\"],\n  megaMenu: [\"deep-nesting\", \"repeater\", \"global-synced\", \"validation\"],\n  tabs: [\"slots\", \"polymorphic-array\", \"repeater\", \"variants\"],\n  pricing: [\"repeater\", \"conditional\", \"commerce\", \"variants\", \"validation\"],\n  bento: [\"slots\", \"polymorphic-array\", \"variants\", \"responsive-layout\", \"media-heavy\"],\n  journalStory: [\"rich-text\", \"references\", \"media-heavy\", \"seo-structured\", \"localized\", \"validation\", \"embed\"],\n  hero: [\"variants\", \"media-heavy\", \"localized\", \"a11y\"],\n};\nconst CORE_LAYOUT: Record<string, KitPreviewLayout> = {\n  faq: \"accordion\", megaMenu: \"nav\", tabs: \"tabs\", pricing: \"grid-3\", bento: \"bento\", journalStory: \"article\", hero: \"split\",\n};\n\nconst hayOf = (parts: (string | undefined)[]) => parts.filter(Boolean).join(\" \\u0001 \").toLowerCase();\n\nfunction fromEntry(e: KitEntry): CatalogItem {\n  return {\n    id: e.id,\n    ex: e,\n    entry: e,\n    core: false,\n    category: e.category,\n    tags: e.tags ?? [],\n    notes: e.notes,\n    brand: e.brand,\n    previewLayout: e.previewLayout,\n    hay: hayOf([e.label, e.schema.title, e.schema.name, e.schema.description, e.proves, e.category, e.brand, ...(e.tags ?? []).map((t) => `${t} ${TAG_LABEL[t] ?? \"\"}`), ...(e.notes?.htmlSignals ?? [])]),\n  };\n}\nfunction fromCore(x: KitExample): CatalogItem {\n  const tags = CORE_TAGS[x.id] ?? [];\n  const notes = CORE_NOTES[x.id];\n  return {\n    id: `core-${x.id}`,\n    ex: x,\n    core: true,\n    category: CORE_CATEGORY,\n    tags,\n    notes,\n    brand: \"Caldera\",\n    previewLayout: CORE_LAYOUT[x.id],\n    hay: hayOf([x.label, x.schema.title, x.schema.name, x.schema.description, x.proves, CORE_CATEGORY, ...tags.map((t) => `${t} ${TAG_LABEL[t] ?? \"\"}`), ...(notes?.htmlSignals ?? [])]),\n  };\n}\n\nconst catRank = (c: CatalogCategory) => {\n  const i = CATEGORY_ORDER.indexOf(c as KitCategory);\n  return c === CORE_CATEGORY ? 1000 : i === -1 ? 500 : i;\n};\n\n/** Library entries (sorted by category order, then file order) followed by the core examples. Ids are unique. */\nexport function buildCatalog(library: KitEntry[] = KIT_LIBRARY): CatalogItem[] {\n  const seen = new Set<string>();\n  const lib = library\n    .filter((e) => e && e.id && e.schema && !seen.has(e.id) && (seen.add(e.id), true))\n    .map(fromEntry)\n    .map((it, i) => ({ it, i }))\n    .sort((a, b) => catRank(a.it.category) - catRank(b.it.category) || a.i - b.i)\n    .map((x) => x.it);\n  return [...lib, ...EXAMPLES.map(fromCore)];\n}\n\nexport const CATALOG: CatalogItem[] = buildCatalog();\n\n/** Categories present in a list, in display order, with counts. */\nexport function categoriesOf(items: CatalogItem[]): { category: CatalogCategory; count: number }[] {\n  const m = new Map<CatalogCategory, number>();\n  for (const it of items) m.set(it.category, (m.get(it.category) ?? 0) + 1);\n  return [...m.entries()].sort((a, b) => catRank(a[0]) - catRank(b[0])).map(([category, count]) => ({ category, count }));\n}\n\n/** Every term must appear somewhere in the haystack. */\nexport function matches(it: CatalogItem, terms: string[], tags: EdgeTag[]): boolean {\n  if (tags.length && !tags.every((t) => it.tags.includes(t))) return false;\n  return terms.every((t) => it.hay.includes(t));\n}\nexport const termsOf = (q: string) => q.trim().toLowerCase().split(/\\s+/).filter(Boolean);\n\n/**\n * Block schemas a slot can resolve: the shared example blocks plus every library entry whose schema is a block\n * (so an entry may place another entry's block in a slot by its schema name). First definition wins.\n */\nexport const LIBRARY_BLOCKS: TypeSchema[] = (() => {\n  const out: TypeSchema[] = [];\n  const names = new Set<string>();\n  for (const s of [...BLOCK_LIBRARY, ...KIT_LIBRARY.flatMap((e) => e.blocks ?? []), ...KIT_LIBRARY.map((e) => e.schema)]) {\n    if (!s?.name || names.has(s.name)) continue;\n    names.add(s.name);\n    out.push(s);\n  }\n  return out;\n})();\nconst BLOCK_BY_NAME = new Map(LIBRARY_BLOCKS.map((b) => [b.name, b]));\nexport const resolveLibraryBlock = (type: string) => BLOCK_BY_NAME.get(type);\n/** Blocks offered by \"+ Add block\": only real blocks (not entries / pages). */\nexport const PICKABLE_BLOCKS: TypeSchema[] = LIBRARY_BLOCKS.filter((b) => b.kind === \"block\");\n\n/** Slot resolution for one catalog item: its entry-local `blocks` first (contract), then the shared library. */\nexport function blocksFor(it: CatalogItem): { resolve: (type: string) => TypeSchema | undefined; library: TypeSchema[] } {\n  const local = it.entry?.blocks?.filter((b) => b?.name) ?? [];\n  if (!local.length) return { resolve: resolveLibraryBlock, library: PICKABLE_BLOCKS };\n  const own = new Map(local.map((b) => [b.name, b]));\n  const names = new Set(local.map((b) => b.name));\n  return {\n    resolve: (type) => own.get(type) ?? BLOCK_BY_NAME.get(type),\n    library: [...local, ...PICKABLE_BLOCKS.filter((b) => !names.has(b.name))],\n  };\n}\n"],"mappings":"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"}

package/dist/library/coreNotes.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Model notes for the seven core examples (src/kit/library/examples). They predate the entry contract, so the
+ * catalog attaches these by example id, as it does CORE_TAGS. Every claim is sourced from the example's own schema
+ * and `proves`, the backend skill's worked examples (hero, pricing, FAQ, blog entry, mega menu, tabs) and the MCP
+ * playbook §2–§5 and §14. The `mcp` text is in create_component / update_layout / create_content_model terms.
+ */
+import type { KitModelNotes } from "./types";
+export declare const CORE_NOTES: Record<string, KitModelNotes>;

package/dist/library/coreNotes.js

@@ -0,0 +1,111 @@
+//#region src/library/coreNotes.ts
+var CORE_NOTES = {
+	faq: {
+		why: "Questions are same-shaped rows, so `items` is one list whose row holds a plain-string question and a rich-text answer (bold, links and lists live in answers). `source` switches between questions written here and references into a FAQs collection; each list shows only for its own choice, so the two never disagree. Search, rich results, columns and the anchor are Settings, not copy, and the anchor is locked to people who manage the schema.",
+		htmlSignals: [
+			"Repeated <details> with a <summary> holding the question (often an <h3> plus a chevron <svg>) and a body <div> holding the answer",
+			"The first <details> carries `open`",
+			"A hand-written <script type=\"application/ld+json\"> with \"@type\":\"FAQPage\" beside the band",
+			"A closing line with a support link under the list (\"Still stuck? Talk to support\")"
+		],
+		mcp: "create_component with sectionType 'FAQ'; each prop needs a `target` into your own blockJson (a root `section` with `style`). eyebrow/heading/intro → text props on heading/text blocks. items → ONE `table` prop: config.fields question (text, required) + answer (richtext, required), plus category (select) and open (boolean); ui { preview: { title: 'question' }, itemLabel: 'Question', icon: 'help-circle' }. source → a select with ui.control 'segmented'; give items and collection a `showIf` on source ('inline' / 'collection'), placed after source. collection → multi-reference with config.contentModelId of the FAQs model. showSearch/richResults/columns/anchor → ui.tab 'Settings'. Accordion and Two columns are two components sharing sectionType 'FAQ' with the same prop keys.",
+		pitfalls: [
+			"richResults does nothing by itself: FAQPage markup comes from update_page schemaType 'FAQPage', and the builder finds the first list whose rows have keys containing `question` and `answer`. Delete the hand-written JSON-LD.",
+			"`open` on the first item is behaviour in the worked example and stays in the template; keep the per-item boolean only if the template reads it.",
+			"Bind the question on the <h3>, not the <summary>, or a save erases the chevron."
+		]
+	},
+	megaMenu: {
+		why: "The navigation is a GLOBAL block: one copy synced across every page, edited once. Its menu is five levels deep (Navigation › menu item › column › link › badge) to prove drill-in and breadcrumb truncation. A menu item `kind` decides whether it is a plain link or opens a mega panel of columns plus a featured card, so a link row never carries panel data. Sticky, transparent and the mobile style sit in a Behaviour tab; the logo and its screen-reader text share a Brand fieldset.",
+		htmlSignals: [
+			"A <header> on every page holding <nav aria-label=\"Main\"> with a logo <a><img></a> and a <ul> of menu items",
+			"A <button aria-expanded aria-controls> that opens a hidden panel, beside plain <a> items that just link",
+			"Panel columns: a title <p> over a <ul> of links, each link a label <span>, an optional description <span> and an optional badge (\"New\")",
+			"Sign-in link and a primary button at the end of the bar"
+		],
+		mcp: "Site chrome is the Layout, never a page section: get_layout, then update_layout scope 'global' with `add-field` commands on the reserved `navigation` Section (ifMatch from get_layout), set-field-value for the rows, publish_layout. Read the Section's existing logo, link and button fields first and add only what is missing. If the header is a component placed with `add-component`, each prop needs a `target` into your own blockJson: items → a `table` prop (ui { itemLabel: 'Menu item', preview: { title: 'label' } }) whose rows hold label, link (a `link` value), kind (select) and ONE nested `table` of links with `column` as a text sub-field; cta → a `button` prop on a button block's `props`. logo/logoText → ui.group 'brand'; sticky/transparent/mobile → ui.tab 'Behaviour'.",
+		pitfalls: [
+			"Two list levels is the cap for a component's props and the depth chrome is proven to bind at: store menu → links and put the column title on each link row. The kit's third level (columns) and the badge object do not fit; flatten the badge to a scalar on the link row.",
+			"A nav placed on a page as a section renders nowhere, and a page that draws its own header gets no Layout copy on top: remove page-level copies.",
+			"The worked example keeps `sticky`, colours and height in code; expose the Behaviour props only if the template reads them."
+		]
+	},
+	tabs: {
+		why: "Tabs are a list (2–6), and each tab is a label, an optional icon and a SLOT of blocks, so a panel can hold text, images, features, stats, quotes, CTA cards, product cards or video in any order. The allow list keeps panels to small content blocks. Which tab opens first and whether the URL remembers it are settings; underline, pills and side tabs are layout variants.",
+		htmlSignals: [
+			"A role=\"tablist\" of <button role=\"tab\" aria-controls aria-selected>, often each with an icon <i>",
+			"One role=\"tabpanel\" per tab, all but the first `hidden`",
+			"Panels that hold their own rows of cards, images and stats rather than one paragraph"
+		],
+		mcp: "A band one page owns can stay a `section` block holding a `tabs` block {tabs:[{id,label,children}]} (worked example 8). As a component: create_component with a sectionType naming the family (e.g. 'Tabs'); each prop needs a `target` into your own blockJson. tabs → ONE `table` prop (ui { itemLabel: 'Tab', preview: { title: 'label' }, icon: 'layout-list' }) with config.fields label (text, required), icon (`icon`) and content: a `slot` sub-field with config.multiple, maxItems 6 and config.componentIds; point the table at your tabs block the way §14's slider table targets props.slides. heading → text prop; defaultTab → number with config.min 1, max 6. Underline, Pills and Side tabs are three components sharing sectionType 'Tabs' with the same prop keys.",
+		pitfalls: [
+			"The kit's slot allow list names kit blocks, not components: config.componentIds must list published components of this project.",
+			"Slot children are `{ componentId, overrides? }` with no `_variant`: a variant is its own component.",
+			"Give every block, tab and instance a stable `id`; changing one orphans the edits made against it."
+		]
+	},
+	pricing: {
+		why: "Tiers are same-shaped rows (1–4). A tier's priceType decides what shows: a fixed tier shows the amount and billing interval, a custom tier swaps in a Contact sales button, so a tier never shows a price and 'Contact sales' at once. Features are tiny rows (label, included, tooltip) that open inline. The comparison table, currency, the monthly/yearly switch and its discount are Display settings; Three tiers, Two tiers and Comparison table are variants.",
+		htmlSignals: [
+			"A grid of plan <article>s, each with an <h3> name, a short audience line, a price, a <ul class=\"checks\"> and one CTA <a>",
+			"One card flagged with a ribbon or modifier class (\"Most popular\")",
+			"A price <span> with data-monthly / data-yearly next to a role=\"radiogroup\" billing toggle (\"Save 20%\")",
+			"A price in words (\"Let's talk\") linking to contact sales instead of an amount",
+			"A <table class=\"compare\"> with one column per plan and check / cross icons labelled by aria-label"
+		],
+		mcp: "create_component with sectionType 'Pricing' and category 'conversion'; it lands as a draft, then publish_component. Each prop needs a `target` into your own blockJson: tiers → ONE `table` prop targeting props.rows of a `section` block whose children mirror one row, ui { itemLabel: 'Tier', preview: { title: 'name' }, icon: 'tiers' }; its config.fields hold name, tagline, priceType (select, ui.control 'segmented'), price (number) and interval with `showIf` priceType eq 'fixed', contactSales and cta as `button` sub-fields, featured (boolean) and features as a nested `table` of scalars. comparison → a second `table` prop, one row per feature and one key per tier. currency/toggle/discount → ui.tab 'Display'. Variants are sibling components sharing sectionType 'Pricing' and the same prop keys.",
+		pitfalls: [
+			"Store numbers, never '$24/mo'. A price in words is its own text key, shown when the numbers are empty.",
+			"The nested features table is the deepest a prop goes: its rows take scalars only.",
+			"A tier added to the comparison is a new sub-field, a schema change. No Offer JSON-LD is built from prices; paste it as `schema` on update_page when needed."
+		]
+	},
+	bento: {
+		why: "A bento is a SLOT of 3–9 cells, and each cell is any allowed block (image, stat, quote, text, CTA card, product card, video). Size (1×1, 2×1, 1×2, 2×2) and surface (light, dark, brand) belong to the cell's place in this grid, not to the block, so they are per-slot settings rather than fields on every block. The gap is a design select; four and three columns are variants.",
+		htmlSignals: [
+			"A grid section whose cells span different column/row counts (wide, tall and large tiles beside small ones)",
+			"Cells of mixed kinds in one grid: a photo, a big number with a label, a quote, a product card, a CTA card, a video",
+			"Some cells on a dark or brand-coloured surface while their neighbours are light"
+		],
+		mcp: "create_component with a sectionType naming the family (e.g. 'Bento'); each prop needs a `target` into your own blockJson. cells → a `slot` prop with config.multiple, minItems 3, maxItems 9, config.componentIds of your published cell components, and config.slotSettings span (select 1x1/2x1/1x2/2x2, ui.control 'cards') and tone (select light/dark/brand, ui.control 'segmented'); target a container's child list (props.children on a section, props.columns.<n> on a columns block). Each child is `{ componentId, overrides? }` and its settings sit in `_settings`. eyebrow/heading → text props; gap → select with ui.control 'segmented'. 4 columns and 3 columns are two components sharing sectionType 'Bento' with the same prop keys.",
+		pitfalls: [
+			"The kit's allow list names kit blocks; config.componentIds must name this project's published components, and the renderer needs their definitions or every cell draws empty.",
+			"A slot child has no `_variant`: a variant is its own component.",
+			"slotSettings are leaf fields only; a cell's own copy stays in the cell component's props."
+		]
+	},
+	journalStory: {
+		why: "A story is an ENTRY, one of many, with its own URL: content in groups (Content, Media, Settings) and fieldsets (Byline, a collapsed Gear review, Publishing). Authors and topics are references to their own collections, not copied names; the reviewed product is a reference to commerce. The body is the one long rich-text field. Layout, accent, internal tags, related stories and developer-only custom CSS are Settings. It proves references, rich text, SEO-friendly limits (title, excerpt) and changed-since-publish.",
+		htmlSignals: [
+			"An <article> (often itemtype BlogPosting) with an <h1>, a dek <p>, a byline with <a rel=\"author\"> and <time datetime>",
+			"A cover <figure> with <img> and <figcaption> above a prose body of <h2>, <p>, lists, figures, tables and code",
+			"A topic link above the title and a reading time (\"7 min read\") in the byline",
+			"One of many pages under a shared route such as /blog/<slug>"
+		],
+		mcp: "Not a component: create_content_model for the stories (a collection with urlPattern '/blog/:slug' and one dynamic page), and create_content_entry per story. Find or create the author and topic entries first and reference them by id. title, slug, excerpt, cover, gallery and film are fields; body is the ONE `document` field (top level, at most one per schema); dates are ISO 8601 with their offset. Publish authors and topics, then the post, then the template page. The `component` shape below is props-shaped only for comparison; if you place a story teaser as a component, each prop needs a `target` into your own blockJson.",
+		pitfalls: [
+			"Never model SEO fields: entry meta (metaTitle, metaDescription, og, canonical) goes in update_content_entry `meta`, and BlogPosting markup is automatic for a collection with a body, a date and an author.",
+			"Reading time is computed by the template; no field stores it today, so don't copy \"7 min read\" into readingTime.",
+			"Bind the body wrapper as kind `document`, never `richtext`, or a save repaints the article from plain text."
+		]
+	},
+	hero: {
+		why: "The opening band: an eyebrow, a headline (required, 90 max, 60 recommended), supporting text, two buttons and a proof line of rating plus label. Each button is one unit, so label, link and look travel together. The proof is a small object because the stars are drawn from the number. Media (a required image, an optional background video) and Design (alignment, theme, overlay, fill-the-screen) are their own tabs, so copy, media and look never mix; split, centered and full-bleed are variants.",
+		htmlSignals: [
+			"The first <section> after the header with one <h1>, a short eyebrow <p> above it and a lede <p> below",
+			"Two links styled as buttons (btn-primary / btn-ghost), sometimes with an arrow icon",
+			"A <picture>/<img> beside the copy (split) or absolutely positioned behind it with a dark scrim <div> (full-bleed)",
+			"A rating line: star glyphs with aria-label=\"Rated 4.8 out of 5\" and \"from 310 reviews\""
+		],
+		mcp: "create_component with sectionType 'Hero' and category 'hero'; root is a `section` block with `style`, content in props.children. Each prop needs a `target` into your own blockJson: eyebrow/body → text props on text blocks (props.html), heading → props.text of a level-1 heading block, primary/secondary → one `button` prop each (label, link and look in one unit) on a button block's `props`, image → an `image` prop on an image block's props.src plus a text prop on props.alt, video → a video block's props.url, proof → an `object` prop with config.fields rating (number) and label (text). Put image/video in ui.tab 'Media' and align/theme/overlay/fullHeight in ui.tab 'Design' (theme with ui.control 'segmented'). Split image, Centered and Full-bleed image are three components sharing sectionType 'Hero' with the same prop keys.",
+		pitfalls: [
+			"Overlay and height have no section token today: the scrim and spacing stay in the template's classes unless the template reads those props.",
+			"object-position is the image's focal point (50% 35% → { x: 0.5, y: 0.35 }); store the number 4.8, never the star glyphs.",
+			"A variant that renames a key (title vs heading) silently drops that content on a swap."
+		]
+	}
+};
+//#endregion
+export { CORE_NOTES };
+
+//# sourceMappingURL=coreNotes.js.map

package/dist/library/coreNotes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coreNotes.js","names":[],"sources":["../../src/library/coreNotes.ts"],"sourcesContent":["/**\n * Model notes for the seven core examples (src/kit/library/examples). They predate the entry contract, so the\n * catalog attaches these by example id, as it does CORE_TAGS. Every claim is sourced from the example's own schema\n * and `proves`, the backend skill's worked examples (hero, pricing, FAQ, blog entry, mega menu, tabs) and the MCP\n * playbook §2–§5 and §14. The `mcp` text is in create_component / update_layout / create_content_model terms.\n */\nimport type { KitModelNotes } from \"./types\";\n\nexport const CORE_NOTES: Record<string, KitModelNotes> = {\n  faq: {\n    why:\n      \"Questions are same-shaped rows, so `items` is one list whose row holds a plain-string question and a rich-text answer (bold, links and lists live in answers). `source` switches between questions written here and references into a FAQs collection; each list shows only for its own choice, so the two never disagree. Search, rich results, columns and the anchor are Settings, not copy, and the anchor is locked to people who manage the schema.\",\n    htmlSignals: [\n      \"Repeated <details> with a <summary> holding the question (often an <h3> plus a chevron <svg>) and a body <div> holding the answer\",\n      \"The first <details> carries `open`\",\n      \"A hand-written <script type=\\\"application/ld+json\\\"> with \\\"@type\\\":\\\"FAQPage\\\" beside the band\",\n      \"A closing line with a support link under the list (\\\"Still stuck? Talk to support\\\")\",\n    ],\n    mcp:\n      \"create_component with sectionType 'FAQ'; each prop needs a `target` into your own blockJson (a root `section` with `style`). eyebrow/heading/intro → text props on heading/text blocks. items → ONE `table` prop: config.fields question (text, required) + answer (richtext, required), plus category (select) and open (boolean); ui { preview: { title: 'question' }, itemLabel: 'Question', icon: 'help-circle' }. source → a select with ui.control 'segmented'; give items and collection a `showIf` on source ('inline' / 'collection'), placed after source. collection → multi-reference with config.contentModelId of the FAQs model. showSearch/richResults/columns/anchor → ui.tab 'Settings'. Accordion and Two columns are two components sharing sectionType 'FAQ' with the same prop keys.\",\n    pitfalls: [\n      \"richResults does nothing by itself: FAQPage markup comes from update_page schemaType 'FAQPage', and the builder finds the first list whose rows have keys containing `question` and `answer`. Delete the hand-written JSON-LD.\",\n      \"`open` on the first item is behaviour in the worked example and stays in the template; keep the per-item boolean only if the template reads it.\",\n      \"Bind the question on the <h3>, not the <summary>, or a save erases the chevron.\",\n    ],\n  },\n  megaMenu: {\n    why:\n      \"The navigation is a GLOBAL block: one copy synced across every page, edited once. Its menu is five levels deep (Navigation › menu item › column › link › badge) to prove drill-in and breadcrumb truncation. A menu item `kind` decides whether it is a plain link or opens a mega panel of columns plus a featured card, so a link row never carries panel data. Sticky, transparent and the mobile style sit in a Behaviour tab; the logo and its screen-reader text share a Brand fieldset.\",\n    htmlSignals: [\n      \"A <header> on every page holding <nav aria-label=\\\"Main\\\"> with a logo <a><img></a> and a <ul> of menu items\",\n      \"A <button aria-expanded aria-controls> that opens a hidden panel, beside plain <a> items that just link\",\n      \"Panel columns: a title <p> over a <ul> of links, each link a label <span>, an optional description <span> and an optional badge (\\\"New\\\")\",\n      \"Sign-in link and a primary button at the end of the bar\",\n    ],\n    mcp:\n      \"Site chrome is the Layout, never a page section: get_layout, then update_layout scope 'global' with `add-field` commands on the reserved `navigation` Section (ifMatch from get_layout), set-field-value for the rows, publish_layout. Read the Section's existing logo, link and button fields first and add only what is missing. If the header is a component placed with `add-component`, each prop needs a `target` into your own blockJson: items → a `table` prop (ui { itemLabel: 'Menu item', preview: { title: 'label' } }) whose rows hold label, link (a `link` value), kind (select) and ONE nested `table` of links with `column` as a text sub-field; cta → a `button` prop on a button block's `props`. logo/logoText → ui.group 'brand'; sticky/transparent/mobile → ui.tab 'Behaviour'.\",\n    pitfalls: [\n      \"Two list levels is the cap for a component's props and the depth chrome is proven to bind at: store menu → links and put the column title on each link row. The kit's third level (columns) and the badge object do not fit; flatten the badge to a scalar on the link row.\",\n      \"A nav placed on a page as a section renders nowhere, and a page that draws its own header gets no Layout copy on top: remove page-level copies.\",\n      \"The worked example keeps `sticky`, colours and height in code; expose the Behaviour props only if the template reads them.\",\n    ],\n  },\n  tabs: {\n    why:\n      \"Tabs are a list (2–6), and each tab is a label, an optional icon and a SLOT of blocks, so a panel can hold text, images, features, stats, quotes, CTA cards, product cards or video in any order. The allow list keeps panels to small content blocks. Which tab opens first and whether the URL remembers it are settings; underline, pills and side tabs are layout variants.\",\n    htmlSignals: [\n      \"A role=\\\"tablist\\\" of <button role=\\\"tab\\\" aria-controls aria-selected>, often each with an icon <i>\",\n      \"One role=\\\"tabpanel\\\" per tab, all but the first `hidden`\",\n      \"Panels that hold their own rows of cards, images and stats rather than one paragraph\",\n    ],\n    mcp:\n      \"A band one page owns can stay a `section` block holding a `tabs` block {tabs:[{id,label,children}]} (worked example 8). As a component: create_component with a sectionType naming the family (e.g. 'Tabs'); each prop needs a `target` into your own blockJson. tabs → ONE `table` prop (ui { itemLabel: 'Tab', preview: { title: 'label' }, icon: 'layout-list' }) with config.fields label (text, required), icon (`icon`) and content: a `slot` sub-field with config.multiple, maxItems 6 and config.componentIds; point the table at your tabs block the way §14's slider table targets props.slides. heading → text prop; defaultTab → number with config.min 1, max 6. Underline, Pills and Side tabs are three components sharing sectionType 'Tabs' with the same prop keys.\",\n    pitfalls: [\n      \"The kit's slot allow list names kit blocks, not components: config.componentIds must list published components of this project.\",\n      \"Slot children are `{ componentId, overrides? }` with no `_variant`: a variant is its own component.\",\n      \"Give every block, tab and instance a stable `id`; changing one orphans the edits made against it.\",\n    ],\n  },\n  pricing: {\n    why:\n      \"Tiers are same-shaped rows (1–4). A tier's priceType decides what shows: a fixed tier shows the amount and billing interval, a custom tier swaps in a Contact sales button, so a tier never shows a price and 'Contact sales' at once. Features are tiny rows (label, included, tooltip) that open inline. The comparison table, currency, the monthly/yearly switch and its discount are Display settings; Three tiers, Two tiers and Comparison table are variants.\",\n    htmlSignals: [\n      \"A grid of plan <article>s, each with an <h3> name, a short audience line, a price, a <ul class=\\\"checks\\\"> and one CTA <a>\",\n      \"One card flagged with a ribbon or modifier class (\\\"Most popular\\\")\",\n      \"A price <span> with data-monthly / data-yearly next to a role=\\\"radiogroup\\\" billing toggle (\\\"Save 20%\\\")\",\n      \"A price in words (\\\"Let's talk\\\") linking to contact sales instead of an amount\",\n      \"A <table class=\\\"compare\\\"> with one column per plan and check / cross icons labelled by aria-label\",\n    ],\n    mcp:\n      \"create_component with sectionType 'Pricing' and category 'conversion'; it lands as a draft, then publish_component. Each prop needs a `target` into your own blockJson: tiers → ONE `table` prop targeting props.rows of a `section` block whose children mirror one row, ui { itemLabel: 'Tier', preview: { title: 'name' }, icon: 'tiers' }; its config.fields hold name, tagline, priceType (select, ui.control 'segmented'), price (number) and interval with `showIf` priceType eq 'fixed', contactSales and cta as `button` sub-fields, featured (boolean) and features as a nested `table` of scalars. comparison → a second `table` prop, one row per feature and one key per tier. currency/toggle/discount → ui.tab 'Display'. Variants are sibling components sharing sectionType 'Pricing' and the same prop keys.\",\n    pitfalls: [\n      \"Store numbers, never '$24/mo'. A price in words is its own text key, shown when the numbers are empty.\",\n      \"The nested features table is the deepest a prop goes: its rows take scalars only.\",\n      \"A tier added to the comparison is a new sub-field, a schema change. No Offer JSON-LD is built from prices; paste it as `schema` on update_page when needed.\",\n    ],\n  },\n  bento: {\n    why:\n      \"A bento is a SLOT of 3–9 cells, and each cell is any allowed block (image, stat, quote, text, CTA card, product card, video). Size (1×1, 2×1, 1×2, 2×2) and surface (light, dark, brand) belong to the cell's place in this grid, not to the block, so they are per-slot settings rather than fields on every block. The gap is a design select; four and three columns are variants.\",\n    htmlSignals: [\n      \"A grid section whose cells span different column/row counts (wide, tall and large tiles beside small ones)\",\n      \"Cells of mixed kinds in one grid: a photo, a big number with a label, a quote, a product card, a CTA card, a video\",\n      \"Some cells on a dark or brand-coloured surface while their neighbours are light\",\n    ],\n    mcp:\n      \"create_component with a sectionType naming the family (e.g. 'Bento'); each prop needs a `target` into your own blockJson. cells → a `slot` prop with config.multiple, minItems 3, maxItems 9, config.componentIds of your published cell components, and config.slotSettings span (select 1x1/2x1/1x2/2x2, ui.control 'cards') and tone (select light/dark/brand, ui.control 'segmented'); target a container's child list (props.children on a section, props.columns.<n> on a columns block). Each child is `{ componentId, overrides? }` and its settings sit in `_settings`. eyebrow/heading → text props; gap → select with ui.control 'segmented'. 4 columns and 3 columns are two components sharing sectionType 'Bento' with the same prop keys.\",\n    pitfalls: [\n      \"The kit's allow list names kit blocks; config.componentIds must name this project's published components, and the renderer needs their definitions or every cell draws empty.\",\n      \"A slot child has no `_variant`: a variant is its own component.\",\n      \"slotSettings are leaf fields only; a cell's own copy stays in the cell component's props.\",\n    ],\n  },\n  journalStory: {\n    why:\n      \"A story is an ENTRY, one of many, with its own URL: content in groups (Content, Media, Settings) and fieldsets (Byline, a collapsed Gear review, Publishing). Authors and topics are references to their own collections, not copied names; the reviewed product is a reference to commerce. The body is the one long rich-text field. Layout, accent, internal tags, related stories and developer-only custom CSS are Settings. It proves references, rich text, SEO-friendly limits (title, excerpt) and changed-since-publish.\",\n    htmlSignals: [\n      \"An <article> (often itemtype BlogPosting) with an <h1>, a dek <p>, a byline with <a rel=\\\"author\\\"> and <time datetime>\",\n      \"A cover <figure> with <img> and <figcaption> above a prose body of <h2>, <p>, lists, figures, tables and code\",\n      \"A topic link above the title and a reading time (\\\"7 min read\\\") in the byline\",\n      \"One of many pages under a shared route such as /blog/<slug>\",\n    ],\n    mcp:\n      \"Not a component: create_content_model for the stories (a collection with urlPattern '/blog/:slug' and one dynamic page), and create_content_entry per story. Find or create the author and topic entries first and reference them by id. title, slug, excerpt, cover, gallery and film are fields; body is the ONE `document` field (top level, at most one per schema); dates are ISO 8601 with their offset. Publish authors and topics, then the post, then the template page. The `component` shape below is props-shaped only for comparison; if you place a story teaser as a component, each prop needs a `target` into your own blockJson.\",\n    pitfalls: [\n      \"Never model SEO fields: entry meta (metaTitle, metaDescription, og, canonical) goes in update_content_entry `meta`, and BlogPosting markup is automatic for a collection with a body, a date and an author.\",\n      \"Reading time is computed by the template; no field stores it today, so don't copy \\\"7 min read\\\" into readingTime.\",\n      \"Bind the body wrapper as kind `document`, never `richtext`, or a save repaints the article from plain text.\",\n    ],\n  },\n  hero: {\n    why:\n      \"The opening band: an eyebrow, a headline (required, 90 max, 60 recommended), supporting text, two buttons and a proof line of rating plus label. Each button is one unit, so label, link and look travel together. The proof is a small object because the stars are drawn from the number. Media (a required image, an optional background video) and Design (alignment, theme, overlay, fill-the-screen) are their own tabs, so copy, media and look never mix; split, centered and full-bleed are variants.\",\n    htmlSignals: [\n      \"The first <section> after the header with one <h1>, a short eyebrow <p> above it and a lede <p> below\",\n      \"Two links styled as buttons (btn-primary / btn-ghost), sometimes with an arrow icon\",\n      \"A <picture>/<img> beside the copy (split) or absolutely positioned behind it with a dark scrim <div> (full-bleed)\",\n      \"A rating line: star glyphs with aria-label=\\\"Rated 4.8 out of 5\\\" and \\\"from 310 reviews\\\"\",\n    ],\n    mcp:\n      \"create_component with sectionType 'Hero' and category 'hero'; root is a `section` block with `style`, content in props.children. Each prop needs a `target` into your own blockJson: eyebrow/body → text props on text blocks (props.html), heading → props.text of a level-1 heading block, primary/secondary → one `button` prop each (label, link and look in one unit) on a button block's `props`, image → an `image` prop on an image block's props.src plus a text prop on props.alt, video → a video block's props.url, proof → an `object` prop with config.fields rating (number) and label (text). Put image/video in ui.tab 'Media' and align/theme/overlay/fullHeight in ui.tab 'Design' (theme with ui.control 'segmented'). Split image, Centered and Full-bleed image are three components sharing sectionType 'Hero' with the same prop keys.\",\n    pitfalls: [\n      \"Overlay and height have no section token today: the scrim and spacing stay in the template's classes unless the template reads those props.\",\n      \"object-position is the image's focal point (50% 35% → { x: 0.5, y: 0.35 }); store the number 4.8, never the star glyphs.\",\n      \"A variant that renames a key (title vs heading) silently drops that content on a swap.\",\n    ],\n  },\n};\n"],"mappings":";AAQA,IAAa,aAA4C;CACvD,KAAK;EACH,KACE;EACF,aAAa;GACX;GACA;GACA;GACA;EACF;EACA,KACE;EACF,UAAU;GACR;GACA;GACA;EACF;CACF;CACA,UAAU;EACR,KACE;EACF,aAAa;GACX;GACA;GACA;GACA;EACF;EACA,KACE;EACF,UAAU;GACR;GACA;GACA;EACF;CACF;CACA,MAAM;EACJ,KACE;EACF,aAAa;GACX;GACA;GACA;EACF;EACA,KACE;EACF,UAAU;GACR;GACA;GACA;EACF;CACF;CACA,SAAS;EACP,KACE;EACF,aAAa;GACX;GACA;GACA;GACA;GACA;EACF;EACA,KACE;EACF,UAAU;GACR;GACA;GACA;EACF;CACF;CACA,OAAO;EACL,KACE;EACF,aAAa;GACX;GACA;GACA;EACF;EACA,KACE;EACF,UAAU;GACR;GACA;GACA;EACF;CACF;CACA,cAAc;EACZ,KACE;EACF,aAAa;GACX;GACA;GACA;GACA;EACF;EACA,KACE;EACF,UAAU;GACR;GACA;GACA;EACF;CACF;CACA,MAAM;EACJ,KACE;EACF,aAAa;GACX;GACA;GACA;GACA;EACF;EACA,KACE;EACF,UAAU;GACR;GACA;GACA;EACF;CACF;AACF"}

package/dist/library/coverage.d.ts

@@ -0,0 +1,40 @@
+import { type EntryStats } from "./analysis";
+import { type CatalogCategory, type CatalogItem } from "./catalog";
+export type CoverageView = "tags" | "types" | "features";
+export interface CoverageColumn {
+    key: string;
+    label: string;
+    hint?: string;
+    /** 0 when the entry does not test it; a count for field types, 1 otherwise */
+    get: (it: CatalogItem, s: EntryStats) => number;
+}
+export interface CoverageRow {
+    it: CatalogItem;
+    s: EntryStats;
+}
+export interface Coverage {
+    rows: CoverageRow[];
+    columns: CoverageColumn[];
+    /** per column: how many entries test it */
+    totals: number[];
+    /** columns under the bar: fewer than 3 entries for edge cases, none for field types; never flagged for features */
+    thin: {
+        column: CoverageColumn;
+        count: number;
+    }[];
+    categories: {
+        category: CatalogCategory;
+        count: number;
+    }[];
+    facts: {
+        sections: number;
+        categories: number;
+        tagsCovered: number;
+        tagsTotal: number;
+        typesUsed: number;
+        typesTotal: number;
+        fields: number;
+        deepest: number;
+    };
+}
+export declare function coverageOf(view: CoverageView, withCore: boolean, catalog?: CatalogItem[]): Coverage;

package/dist/library/coverage.js

@@ -0,0 +1,59 @@
+import { FEATURE_COLUMNS, TYPE_COLUMNS, statsOf } from "./analysis.js";
+import { CATALOG, EDGE_TAGS, blocksFor, categoriesOf } from "./catalog.js";
+//#region src/library/coverage.ts
+/** Field-type columns: the fixed reading order, then any type the schema language grows later, sorted. */
+function typeColumns(rows) {
+	const extra = /* @__PURE__ */ new Set();
+	for (const r of rows) for (const t of Object.keys(r.s.types)) if (!TYPE_COLUMNS.includes(t)) extra.add(t);
+	return [...TYPE_COLUMNS, ...[...extra].sort()];
+}
+function coverageOf(view, withCore, catalog = CATALOG) {
+	const items = catalog.filter((c) => withCore || !c.core);
+	const rows = items.map((it) => ({
+		it,
+		s: statsOf(it, blocksFor(it).resolve)
+	}));
+	const types = typeColumns(rows);
+	const columns = view === "tags" ? EDGE_TAGS.map((t) => ({
+		key: t.tag,
+		label: t.label,
+		hint: t.hint,
+		get: (it) => it.tags.includes(t.tag) ? 1 : 0
+	})) : view === "types" ? types.map((t) => ({
+		key: t,
+		label: t,
+		get: (_it, s) => s.types[t] ?? 0
+	})) : FEATURE_COLUMNS.map((f) => ({
+		key: f.key,
+		label: f.label,
+		get: (_it, s) => s.features[f.key] ? 1 : 0
+	}));
+	const totals = columns.map((c) => rows.reduce((n, r) => n + (c.get(r.it, r.s) > 0 ? 1 : 0), 0));
+	const bar = view === "tags" ? 3 : 1;
+	const thin = view === "features" ? [] : columns.map((column, i) => ({
+		column,
+		count: totals[i]
+	})).filter((x) => x.count < bar);
+	const categories = categoriesOf(items);
+	return {
+		rows,
+		columns,
+		totals,
+		thin,
+		categories,
+		facts: {
+			sections: rows.length,
+			categories: categories.length,
+			tagsCovered: EDGE_TAGS.filter((t) => rows.some((r) => r.it.tags.includes(t.tag))).length,
+			tagsTotal: EDGE_TAGS.length,
+			typesUsed: types.filter((t) => rows.some((r) => (r.s.types[t] ?? 0) > 0)).length,
+			typesTotal: types.length,
+			fields: rows.reduce((n, r) => n + r.s.fields, 0),
+			deepest: rows.reduce((m, r) => Math.max(m, r.s.depth), 0)
+		}
+	};
+}
+//#endregion
+export { coverageOf };
+
+//# sourceMappingURL=coverage.js.map

package/dist/library/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","names":[],"sources":["../../src/library/coverage.ts"],"sourcesContent":["/**\n * Coverage matrix logic: what the library actually tests. Entries against edge cases, field types (how many\n * fields of each) or schema features, plus the deepest drill-in per entry and the columns nothing (or too little)\n * tests. The V2 /kit/coverage page computed this inline; it lives here so the page only draws it.\n */\nimport type { SchemaType } from \"../schema/types\";\nimport { FEATURE_COLUMNS, statsOf, TYPE_COLUMNS, type EntryStats } from \"./analysis\";\nimport { blocksFor, CATALOG, categoriesOf, EDGE_TAGS, type CatalogCategory, type CatalogItem } from \"./catalog\";\n\nexport type CoverageView = \"tags\" | \"types\" | \"features\";\n\nexport interface CoverageColumn {\n  key: string;\n  label: string;\n  hint?: string;\n  /** 0 when the entry does not test it; a count for field types, 1 otherwise */\n  get: (it: CatalogItem, s: EntryStats) => number;\n}\n\nexport interface CoverageRow {\n  it: CatalogItem;\n  s: EntryStats;\n}\n\nexport interface Coverage {\n  rows: CoverageRow[];\n  columns: CoverageColumn[];\n  /** per column: how many entries test it */\n  totals: number[];\n  /** columns under the bar: fewer than 3 entries for edge cases, none for field types; never flagged for features */\n  thin: { column: CoverageColumn; count: number }[];\n  categories: { category: CatalogCategory; count: number }[];\n  facts: { sections: number; categories: number; tagsCovered: number; tagsTotal: number; typesUsed: number; typesTotal: number; fields: number; deepest: number };\n}\n\n/** Field-type columns: the fixed reading order, then any type the schema language grows later, sorted. */\nfunction typeColumns(rows: CoverageRow[]): SchemaType[] {\n  const extra = new Set<string>();\n  for (const r of rows) for (const t of Object.keys(r.s.types)) if (!(TYPE_COLUMNS as string[]).includes(t)) extra.add(t);\n  return [...TYPE_COLUMNS, ...([...extra].sort() as SchemaType[])];\n}\n\nexport function coverageOf(view: CoverageView, withCore: boolean, catalog: CatalogItem[] = CATALOG): Coverage {\n  const items = catalog.filter((c) => withCore || !c.core);\n  const rows = items.map((it) => ({ it, s: statsOf(it, blocksFor(it).resolve) }));\n  const types = typeColumns(rows);\n  const columns: CoverageColumn[] =\n    view === \"tags\"\n      ? EDGE_TAGS.map((t) => ({ key: t.tag, label: t.label, hint: t.hint, get: (it) => (it.tags.includes(t.tag) ? 1 : 0) }))\n      : view === \"types\"\n        ? types.map((t) => ({ key: t, label: t, get: (_it, s) => s.types[t] ?? 0 }))\n        : FEATURE_COLUMNS.map((f) => ({ key: f.key, label: f.label, get: (_it, s) => (s.features[f.key] ? 1 : 0) }));\n  const totals = columns.map((c) => rows.reduce((n, r) => n + (c.get(r.it, r.s) > 0 ? 1 : 0), 0));\n  const bar = view === \"tags\" ? 3 : 1;\n  const thin = view === \"features\" ? [] : columns.map((column, i) => ({ column, count: totals[i] })).filter((x) => x.count < bar);\n  const categories = categoriesOf(items);\n  return {\n    rows,\n    columns,\n    totals,\n    thin,\n    categories,\n    facts: {\n      sections: rows.length,\n      categories: categories.length,\n      tagsCovered: EDGE_TAGS.filter((t) => rows.some((r) => r.it.tags.includes(t.tag))).length,\n      tagsTotal: EDGE_TAGS.length,\n      typesUsed: types.filter((t) => rows.some((r) => (r.s.types[t] ?? 0) > 0)).length,\n      typesTotal: types.length,\n      fields: rows.reduce((n, r) => n + r.s.fields, 0),\n      deepest: rows.reduce((m, r) => Math.max(m, r.s.depth), 0),\n    },\n  };\n}\n"],"mappings":";;;;AAoCA,SAAS,YAAY,MAAmC;CACtD,MAAM,wBAAQ,IAAI,IAAY;CAC9B,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,OAAO,KAAK,EAAE,EAAE,KAAK,GAAG,IAAI,CAAE,aAA0B,SAAS,CAAC,GAAG,MAAM,IAAI,CAAC;CACtH,OAAO,CAAC,GAAG,cAAc,GAAI,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAkB;AACjE;AAEA,SAAgB,WAAW,MAAoB,UAAmB,UAAyB,SAAmB;CAC5G,MAAM,QAAQ,QAAQ,QAAQ,MAAM,YAAY,CAAC,EAAE,IAAI;CACvD,MAAM,OAAO,MAAM,KAAK,QAAQ;EAAE;EAAI,GAAG,QAAQ,IAAI,UAAU,EAAE,CAAC,CAAC,OAAO;CAAE,EAAE;CAC9E,MAAM,QAAQ,YAAY,IAAI;CAC9B,MAAM,UACJ,SAAS,SACL,UAAU,KAAK,OAAO;EAAE,KAAK,EAAE;EAAK,OAAO,EAAE;EAAO,MAAM,EAAE;EAAM,MAAM,OAAQ,GAAG,KAAK,SAAS,EAAE,GAAG,IAAI,IAAI;CAAG,EAAE,IACnH,SAAS,UACP,MAAM,KAAK,OAAO;EAAE,KAAK;EAAG,OAAO;EAAG,MAAM,KAAK,MAAM,EAAE,MAAM,MAAM;CAAE,EAAE,IACzE,gBAAgB,KAAK,OAAO;EAAE,KAAK,EAAE;EAAK,OAAO,EAAE;EAAO,MAAM,KAAK,MAAO,EAAE,SAAS,EAAE,OAAO,IAAI;CAAG,EAAE;CACjH,MAAM,SAAS,QAAQ,KAAK,MAAM,KAAK,QAAQ,GAAG,MAAM,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC;CAC9F,MAAM,MAAM,SAAS,SAAS,IAAI;CAClC,MAAM,OAAO,SAAS,aAAa,CAAC,IAAI,QAAQ,KAAK,QAAQ,OAAO;EAAE;EAAQ,OAAO,OAAO;CAAG,EAAE,CAAC,CAAC,QAAQ,MAAM,EAAE,QAAQ,GAAG;CAC9H,MAAM,aAAa,aAAa,KAAK;CACrC,OAAO;EACL;EACA;EACA;EACA;EACA;EACA,OAAO;GACL,UAAU,KAAK;GACf,YAAY,WAAW;GACvB,aAAa,UAAU,QAAQ,MAAM,KAAK,MAAM,MAAM,EAAE,GAAG,KAAK,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;GAClF,WAAW,UAAU;GACrB,WAAW,MAAM,QAAQ,MAAM,KAAK,MAAM,OAAO,EAAE,EAAE,MAAM,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;GAC1E,YAAY,MAAM;GAClB,QAAQ,KAAK,QAAQ,GAAG,MAAM,IAAI,EAAE,EAAE,QAAQ,CAAC;GAC/C,SAAS,KAAK,QAAQ,GAAG,MAAM,KAAK,IAAI,GAAG,EAAE,EAAE,KAAK,GAAG,CAAC;EAC1D;CACF;AACF"}

package/dist/library/entries/advanced.entries.d.ts

@@ -0,0 +1,2 @@
+import type { KitEntry } from "../types";
+export declare const ENTRIES: KitEntry[];