@cascivo/react 0.16.1 → 0.17.1

package/dist/date-picker/date-picker.js

@@ -2,25 +2,25 @@
 
 import e from "./date-picker.module.js";
 import { useId as t, useRef as n } from "react";
-import { batch as r, cn as i, createMachine as a, useMachine as o, useSignal as s, useSignalEffect as c, useSignals as ee } from "@cascivo/core";
-import { builtin as l, currentLocale as te, t as u } from "@cascivo/i18n";
-import { jsx as d, jsxs as f } from "react/jsx-runtime";
+import { batch as r, cn as i, createMachine as a, useControllableSignal as o, useMachine as s, useSignal as c, useSignalEffect as l, useSignals as ee } from "@cascivo/core";
+import { builtin as u, currentLocale as d, t as f } from "@cascivo/i18n";
+import { jsx as p, jsxs as m } from "react/jsx-runtime";
 //#region ../components/src/date-picker/date-picker.tsx
-var p = a({
+var h = a({
 	initial: "closed",
 	states: {
 		closed: { on: { OPEN: "open" } },
 		open: { on: { CLOSE: "closed" } }
 	}
 });
-function ne(e) {
+function g(e) {
 	try {
 		let t = new Intl.Locale(e).weekInfo;
 		if (t) return t.firstDay % 7;
 	} catch {}
 	return 1;
 }
-function m(e, t, n) {
+function te(e, t, n) {
 	let r = new Date(Date.UTC(e, t, 1)), i = new Date(Date.UTC(e, t + 1, 0)), a = (r.getUTCDay() - n + 7) % 7, o = [];
 	for (let e = 0; e < a; e++) o.push(null);
 	for (let n = 1; n <= i.getUTCDate(); n++) o.push(new Date(Date.UTC(e, t, n)));
@@ -29,170 +29,171 @@ function m(e, t, n) {
 	for (let e = 0; e < o.length; e += 7) s.push(o.slice(e, e + 7));
 	return s;
 }
-function h(e, t) {
+function _(e, t) {
 	return new Intl.DateTimeFormat(t).format(e);
 }
-function g(e) {
+function v(e) {
 	return e.toISOString().slice(0, 10);
 }
-function _(e) {
+function y(e) {
 	let [t, n, r] = e.split("-").map(Number);
 	return new Date(Date.UTC(t, n - 1, r));
 }
-function v({ value: a, defaultValue: v, onValueChange: y, onChange: b, min: x, max: S, clearable: C = !1, label: w, hint: T, error: E, size: D = "md", disabled: O = !1, labels: k, className: re, id: A }) {
+function b({ value: a, defaultValue: b, onValueChange: ne, onChange: x, min: S, max: C, clearable: w = !1, label: T, hint: E, error: D, size: re = "md", disabled: O = !1, labels: k, className: ie, id: ae }) {
 	ee();
-	let [j, M] = o(p), N = t(), P = A ?? `cascade-date-picker-${N}`, F = `${N}-grid`, I = te(), ie = k?.placeholder ?? u(l.datePicker.placeholder), ae = k?.previousMonth ?? u(l.datePicker.previousMonth), L = k?.nextMonth ?? u(l.datePicker.nextMonth), R = k?.clear ?? u(l.datePicker.clear), z = /* @__PURE__ */ new Date(), B = g(z), V = s(a ?? v);
-	a !== void 0 && (V.value = a);
-	let H = s(V.value ? _(V.value).getUTCFullYear() : z.getUTCFullYear()), U = s(V.value ? _(V.value).getUTCMonth() : z.getUTCMonth()), W = s(V.value), G = n(null);
-	c(() => {
-		if (j.value !== "open") return;
+	let [A, j] = s(h), M = t(), N = ae ?? `cascade-date-picker-${M}`, P = `${M}-grid`, F = d(), I = k?.placeholder ?? f(u.datePicker.placeholder), L = k?.previousMonth ?? f(u.datePicker.previousMonth), R = k?.nextMonth ?? f(u.datePicker.nextMonth), z = k?.clear ?? f(u.datePicker.clear), B = /* @__PURE__ */ new Date(), V = v(B), [H] = o({
+		value: a,
+		defaultValue: b
+	}), U = c(H.value ? y(H.value).getUTCFullYear() : B.getUTCFullYear()), W = c(H.value ? y(H.value).getUTCMonth() : B.getUTCMonth()), G = c(H.value), K = n(null);
+	l(() => {
+		if (A.value !== "open") return;
 		let e = (e) => {
-			G.current && !G.current.contains(e.target) && M("CLOSE");
+			K.current && !K.current.contains(e.target) && j("CLOSE");
 		};
 		return document.addEventListener("mousedown", e), () => document.removeEventListener("mousedown", e);
 	});
-	let K = () => {
-		O || M("OPEN");
-	}, q = () => M("CLOSE"), J = y ?? b, Y = (e) => {
-		x && e < x || S && e > S || (a === void 0 && (V.value = e), J?.(e), q());
+	let q = () => {
+		O || j("OPEN");
+	}, J = () => j("CLOSE"), Y = ne ?? x, X = (e) => {
+		S && e < S || C && e > C || (a === void 0 && (H.value = e), Y?.(e), J());
 	}, oe = (e) => {
-		e.stopPropagation(), a === void 0 && (V.value = void 0), J?.(void 0);
+		e.stopPropagation(), a === void 0 && (H.value = void 0), Y?.(void 0);
 	}, se = () => {
-		U.value === 0 ? r(() => {
-			H.value--, U.value = 11;
-		}) : U.value--;
+		W.value === 0 ? r(() => {
+			U.value--, W.value = 11;
+		}) : W.value--;
 	}, ce = () => {
-		U.value === 11 ? r(() => {
-			H.value++, U.value = 0;
-		}) : U.value++;
-	}, X = ne(I), Z = m(H.value, U.value, X), le = new Intl.DateTimeFormat(I, { weekday: "short" }), ue = Array.from({ length: 7 }, (e, t) => {
-		let n = new Date(Date.UTC(2024, 0, 7 + X + t));
-		return le.format(n);
-	}), Q = new Intl.DateTimeFormat(I, {
+		W.value === 11 ? r(() => {
+			U.value++, W.value = 0;
+		}) : W.value++;
+	}, Z = g(F), le = te(U.value, W.value, Z), ue = new Intl.DateTimeFormat(F, { weekday: "short" }), de = Array.from({ length: 7 }, (e, t) => {
+		let n = new Date(Date.UTC(2024, 0, 7 + Z + t));
+		return ue.format(n);
+	}), Q = new Intl.DateTimeFormat(F, {
 		month: "long",
 		year: "numeric"
-	}).format(new Date(Date.UTC(H.value, U.value, 1))), de = (e) => {
-		let t = W.value;
+	}).format(new Date(Date.UTC(U.value, W.value, 1))), fe = (e) => {
+		let t = G.value;
 		if (!t) return;
-		let n = _(t), i;
+		let n = y(t), i;
 		if (e.key === "ArrowRight") i = new Date(Date.UTC(n.getUTCFullYear(), n.getUTCMonth(), n.getUTCDate() + 1));
 		else if (e.key === "ArrowLeft") i = new Date(Date.UTC(n.getUTCFullYear(), n.getUTCMonth(), n.getUTCDate() - 1));
 		else if (e.key === "ArrowDown") i = new Date(Date.UTC(n.getUTCFullYear(), n.getUTCMonth(), n.getUTCDate() + 7));
 		else if (e.key === "ArrowUp") i = new Date(Date.UTC(n.getUTCFullYear(), n.getUTCMonth(), n.getUTCDate() - 7));
 		else if (e.key === "Enter" || e.key === " ") {
-			e.preventDefault(), Y(t);
+			e.preventDefault(), X(t);
 			return;
 		} else if (e.key === "Escape") {
-			q();
+			J();
 			return;
 		} else return;
 		if (e.preventDefault(), i) {
-			let e = g(i);
-			if (x && e < x || S && e > S) return;
-			W.value = e, r(() => {
-				H.value = i.getUTCFullYear(), U.value = i.getUTCMonth();
+			let e = v(i);
+			if (S && e < S || C && e > C) return;
+			G.value = e, r(() => {
+				U.value = i.getUTCFullYear(), W.value = i.getUTCMonth();
 			});
 		}
-	}, $ = V.value ? h(_(V.value), I) : "";
-	return /* @__PURE__ */ f("div", {
-		ref: G,
-		className: i(e.wrapper, re),
-		"data-state": E ? "error" : j.value,
-		"data-size": D,
+	}, $ = H.value ? _(y(H.value), F) : "";
+	return /* @__PURE__ */ m("div", {
+		ref: K,
+		className: i(e.wrapper, ie),
+		"data-state": D ? "error" : A.value,
+		"data-size": re,
 		children: [
-			w && /* @__PURE__ */ d("label", {
+			T && /* @__PURE__ */ p("label", {
 				className: e.label,
-				htmlFor: P,
-				children: w
+				htmlFor: N,
+				children: T
 			}),
-			/* @__PURE__ */ f("div", {
+			/* @__PURE__ */ m("div", {
 				className: e.field,
-				children: [/* @__PURE__ */ f("button", {
-					id: P,
+				children: [/* @__PURE__ */ m("button", {
+					id: N,
 					type: "button",
 					role: "combobox",
-					"aria-expanded": j.value === "open",
-					"aria-controls": F,
+					"aria-expanded": A.value === "open",
+					"aria-controls": P,
 					"aria-haspopup": "dialog",
-					"aria-invalid": E ? !0 : void 0,
-					"aria-describedby": E ? `${N}-error` : T ? `${N}-hint` : void 0,
+					"aria-invalid": D ? !0 : void 0,
+					"aria-describedby": D ? `${M}-error` : E ? `${M}-hint` : void 0,
 					className: e.trigger,
 					disabled: O,
-					onClick: j.value === "open" ? q : K,
-					children: [/* @__PURE__ */ d("span", {
+					onClick: A.value === "open" ? J : q,
+					children: [/* @__PURE__ */ p("span", {
 						className: i(e.value, $ ? void 0 : e.placeholder),
-						children: $ || ie
-					}), /* @__PURE__ */ d("span", {
+						children: $ || I
+					}), /* @__PURE__ */ p("span", {
 						className: e.icon,
 						"aria-hidden": "true",
 						children: "📅"
 					})]
-				}), C && V.value !== void 0 && /* @__PURE__ */ d("button", {
+				}), w && H.value !== void 0 && /* @__PURE__ */ p("button", {
 					type: "button",
 					className: e.clear,
-					"aria-label": R,
+					"aria-label": z,
 					onClick: oe,
 					children: "✕"
 				})]
 			}),
-			/* @__PURE__ */ f("div", {
-				id: F,
+			/* @__PURE__ */ m("div", {
+				id: P,
 				role: "dialog",
 				"aria-label": Q,
 				className: e.calendar,
-				"data-state": j.value,
-				onKeyDown: de,
-				children: [/* @__PURE__ */ f("div", {
+				"data-state": A.value,
+				onKeyDown: fe,
+				children: [/* @__PURE__ */ m("div", {
 					className: e.header,
 					children: [
-						/* @__PURE__ */ d("button", {
+						/* @__PURE__ */ p("button", {
 							type: "button",
 							className: e.navButton,
-							"aria-label": ae,
+							"aria-label": L,
 							onClick: se,
 							children: "‹"
 						}),
-						/* @__PURE__ */ d("span", {
+						/* @__PURE__ */ p("span", {
 							className: e.monthLabel,
 							"aria-live": "polite",
 							children: Q
 						}),
-						/* @__PURE__ */ d("button", {
+						/* @__PURE__ */ p("button", {
 							type: "button",
 							className: e.navButton,
-							"aria-label": L,
+							"aria-label": R,
 							onClick: ce,
 							children: "›"
 						})
 					]
-				}), /* @__PURE__ */ f("table", {
+				}), /* @__PURE__ */ m("table", {
 					role: "grid",
 					className: e.grid,
-					children: [/* @__PURE__ */ d("thead", { children: /* @__PURE__ */ d("tr", { children: ue.map((t) => /* @__PURE__ */ d("th", {
+					children: [/* @__PURE__ */ p("thead", { children: /* @__PURE__ */ p("tr", { children: de.map((t) => /* @__PURE__ */ p("th", {
 						className: e.weekday,
 						abbr: t,
 						scope: "col",
 						children: t
-					}, t)) }) }), /* @__PURE__ */ d("tbody", { children: Z.map((t, n) => /* @__PURE__ */ d("tr", { children: t.map((t, n) => {
-						if (!t) return /* @__PURE__ */ d("td", { className: e.empty }, n);
-						let r = g(t), i = r === V.value, a = r === B, o = r === W.value, s = x !== void 0 && r < x || S !== void 0 && r > S;
-						return /* @__PURE__ */ d("td", {
+					}, t)) }) }), /* @__PURE__ */ p("tbody", { children: le.map((t, n) => /* @__PURE__ */ p("tr", { children: t.map((t, n) => {
+						if (!t) return /* @__PURE__ */ p("td", { className: e.empty }, n);
+						let r = v(t), i = r === H.value, a = r === V, o = r === G.value, s = S !== void 0 && r < S || C !== void 0 && r > C;
+						return /* @__PURE__ */ p("td", {
 							className: e.cell,
-							children: /* @__PURE__ */ d("button", {
+							children: /* @__PURE__ */ p("button", {
 								type: "button",
 								className: e.day,
 								tabIndex: o ? 0 : -1,
 								"aria-pressed": i,
-								"aria-label": h(t, I),
+								"aria-label": _(t, F),
 								"aria-current": a ? "date" : void 0,
 								"aria-disabled": s || void 0,
 								"data-selected": i || void 0,
 								"data-today": a || void 0,
 								onClick: () => {
-									s || Y(r);
+									s || X(r);
 								},
 								onFocus: () => {
-									W.value = r;
+									G.value = r;
 								},
 								children: t.getUTCDate()
 							})
@@ -200,19 +201,19 @@ function v({ value: a, defaultValue: v, onValueChange: y, onChange: b, min: x, m
 					}) }, n)) })]
 				})]
 			}),
-			E && /* @__PURE__ */ d("span", {
-				id: `${N}-error`,
+			D && /* @__PURE__ */ p("span", {
+				id: `${M}-error`,
 				className: e.error,
 				role: "alert",
-				children: E
+				children: D
 			}),
-			!E && T && /* @__PURE__ */ d("span", {
-				id: `${N}-hint`,
+			!D && E && /* @__PURE__ */ p("span", {
+				id: `${M}-hint`,
 				className: e.hint,
-				children: T
+				children: E
 			})
 		]
 	});
 }
 //#endregion
-export { v as DatePicker };
+export { b as DatePicker };

package/dist/dock/dock.js

@@ -26,7 +26,7 @@ function s({ items: s, activeIndex: c, className: l, ariaLabel: u }) {
 					className: e.label,
 					children: n.label
 				})]
-			}, r);
+			}, n.id ?? `${r}-${n.label}`);
 		})
 	});
 }

package/dist/field/field.css

@@ -1 +1 @@
-@layer cascivo.component{._field_ws86v_2{gap:var(--cascivo-space-2);font-family:var(--cascivo-font-sans);display:grid}._field_ws86v_2[data-disabled]{opacity:.5}._description_ws86v_12{font-size:var(--cascivo-text-sm);line-height:var(--cascivo-leading-snug);color:var(--cascivo-color-text-muted);margin:0}._error_ws86v_19{font-size:var(--cascivo-text-sm);line-height:var(--cascivo-leading-snug);color:var(--cascivo-color-destructive);margin:0}}@media (forced-colors:active){._error_ws86v_19{color:buttontext}}
+@layer cascivo.component{._field_1y14o_2{gap:var(--cascivo-space-2);font-family:var(--cascivo-font-sans);align-content:start;display:grid}._field_1y14o_2[data-disabled]{opacity:.5}._description_1y14o_20{font-size:var(--cascivo-text-sm);line-height:var(--cascivo-leading-snug);color:var(--cascivo-color-text-muted);margin:0}._error_1y14o_27{font-size:var(--cascivo-text-sm);line-height:var(--cascivo-leading-snug);color:var(--cascivo-color-destructive);margin:0}}@media (forced-colors:active){._error_1y14o_27{color:buttontext}}

package/dist/field/field.module.js

@@ -1,8 +1,8 @@
 import './field.css';
 var e = {
-	field: "_field_ws86v_2",
-	description: "_description_ws86v_12",
-	error: "_error_ws86v_19"
+	field: "_field_1y14o_2",
+	description: "_description_1y14o_20",
+	error: "_error_1y14o_27"
 };
 //#endregion
 export { e as default };

package/dist/index.d.ts

@@ -24,6 +24,16 @@
 import { AnchorHTMLAttributes, ButtonHTMLAttributes, FormHTMLAttributes, HTMLAttributes, ImgHTMLAttributes, InputHTMLAttributes, LabelHTMLAttributes, LiHTMLAttributes, MouseEvent, ReactElement, ReactNode, RefObject, SelectHTMLAttributes, TextareaHTMLAttributes, TimeHTMLAttributes } from "react";
 import { DismissableLayer, DismissableLayerProps, ErrorBoundary, FocusScope, LinkComponent, LinkComponentProps, Machine, MachineConfig, Portal, Presence, ProgressInput, RovingOrientation, Signal, Slot, SlotProps, SpaceStep, SuspenseBoundary, ThemeProvider, ThemeProviderProps, ToneInput, UseClipboardOptions, UseClipboardReturn, UseControllableSignalOptions, UseDisclosureOptions, UseDisclosureReturn, VisuallyHidden, VisuallyHiddenProps, applyTheme, batch, cn, composeRefs, computePosition, computed, createMachine, createScope, createStreamBuffer, effect, getLinkComponent, mergeProps, setLinkComponent, setTheme, signal, themePreloadScript, themeSignal, useAnchorPosition, useClipboard, useComputed, useControllableSignal, useDisclosure, useEffectPropSignal, useId, useMachine, useMediaQuery, useRovingFocus, useScope, useScrollLock, useSignal, useSignalEffect, useSignals, useStreamBuffer, useTheme, useTypeahead } from "@cascivo/core";
 
+/**
+ * Button.
+ *
+ * ⚠ **DOM shape:** children are wrapped in an inner `<span>` so the loading `Spinner` can be
+ * a sibling rather than being nested inside the label. Layout CSS written against
+ * `.my-button > span` therefore targets that wrapper, not your content — one adopter's
+ * `> span { display: flex }` hit the wrapper and collapsed the spacing inside it. The wrapper
+ * is already a flex row that inherits the button's `gap`, so composing an icon with a label
+ * needs no CSS of your own.
+ */
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   /**
    * Selects the visual style variant.
@@ -78,7 +88,12 @@ interface CardProps extends HTMLAttributes<HTMLDivElement> {
    */
   variant?: 'default' | 'outlined' | 'elevated';
   /**
-   * Inner padding of the component.
+   * Inner padding of the CARD BOX. ⚠ `padding="none"` deliberately does NOT strip the
+   * padding from CardHeader/CardContent/CardFooter — those keep their own. It means "let a
+   * flush child (a LogViewer, an image, an edge-to-edge table) reach the card's edge";
+   * zeroing both put the title flush against the border and made the mode unusable with the
+   * composition it exists for. For an edge-to-edge table, skip CardContent and pass the
+   * table as a direct child.
    *
    * @defaultValue `md`
    * @see the component manifest
@@ -128,16 +143,29 @@ declare function CardFooter({
   children,
   ...props
 }: CardFooterProps): import("react").JSX.Element;
-/** Badge-only looks that aren't a severity tone. */
-type BadgeShape = 'secondary' | 'outline' | 'primary';
+/**
+ * Badge-only looks that aren't a severity tone.
+ *
+ * Named for the PROP it types, not for a prop that does not exist. As `BadgeShape` it sat
+ * directly above `BadgeProps` in the generated `.d.ts` and read as the type of a `shape`
+ * prop, so an adopter wrote `<Badge shape="outline">` in four files before the compiler
+ * disagreed (2026-08-08 report A). A type named after a prop the component does not have is
+ * a trap of our own making.
+ */
+type BadgeVariant = 'secondary' | 'outline' | 'primary';
 interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
   /**
    * Severity tone or badge-specific look. Accepts the catalog-wide `Tone` vocabulary
    * (`neutral | info | success | warning | danger`) as well as Badge's historical spellings
    * (`default`, `destructive`, `error`) — they are aliases of the same tones, so one domain
    * enum can drive `Badge`, `Tag`, `Status` and `Notification` with no lookup table.
+   *
+   * To name this type in your own code, import it: `import type { Tone } from
+   * '@cascivo/react/types'` on the prebuilt path, or from `@cascivo/core` if you copied the
+   * source. Do not add `@cascivo/core` to a prebuilt app just for this; it is a transitive
+   * dependency there.
    */
-  variant?: ToneInput | BadgeShape;
+  variant?: ToneInput | BadgeVariant;
   size?: 'sm' | 'md';
 }
 declare function Badge({
@@ -685,7 +713,8 @@ interface TabsTriggerProps extends HTMLAttributes<HTMLButtonElement> {
    *
    * With `asChild`, `disabled` becomes `aria-disabled`: it is not a valid attribute on an
    * anchor, and a slotted element gets no `type` either. See
-   * [USING-WITH-A-ROUTER.md](../../../../docs/USING-WITH-A-ROUTER.md) for the full recipe.
+   * https://cascivo.com/docs/using-with-a-router.md for the full recipe — offline:
+   * `npx -y @cascivo/docs guide using-with-a-router`.
    */
   asChild?: boolean;
 }
@@ -816,7 +845,8 @@ interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
    * styling lands on your router's `Link`. **This is the supported way to style an
    * in-content router link** — `setLinkComponent` only covers the config-driven nav
    * components (SideNav, ShellHeader, Breadcrumb, …), not links you write in page
-   * content. See `docs/USING-WITH-A-ROUTER.md`.
+   * content. See https://cascivo.com/docs/using-with-a-router.md — offline:
+   * `npx -y @cascivo/docs guide using-with-a-router`.
    *
    * ```tsx
    * <Link asChild><RouterLink to="/projects/a">Project A</RouterLink></Link>
@@ -832,6 +862,17 @@ interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
  */
 declare const Link: import("react").ForwardRefExoticComponent<LinkProps & import("react").RefAttributes<HTMLAnchorElement>>;
 interface BreadcrumbItem {
+  /**
+   * Stable React key. Provide when `label`/`href` may repeat.
+   *
+   * A real breadcrumb repeats hrefs — "Overview" and "Projects" both pointing at `/` is the
+   * normal shape of a console trail — and without an `id` the crumbs key on their index, so
+   * reordering or truncating the trail re-keys every row after the change.
+   * `SideNavItem`, `ShellHeaderNavLink`, `ShellHeaderNavMenuItem`, `HeaderLink`,
+   * `CommandItem` and `SwitcherLink` all carry this field; `BreadcrumbItem` was missed by
+   * both earlier sweeps (2026-08-14 report §9).
+   */
+  id?: string;
   label: string;
   href?: string;
 }
@@ -1461,6 +1502,14 @@ interface Column<Row> {
    * can exceed its container — the extra columns are reachable by horizontal scroll, not
    * dropped. Leave at least one free-form column unsized unless you specifically want
    * page-stable widths.
+   *
+   * ⚠ **"Leave one unsized" is necessary, not sufficient.** The leftover width is split
+   * between the unsized columns by `table-layout: auto`, which weighs them by content — so
+   * if the sized columns nearly fill the table, what remains can be narrower than the
+   * content needs and long tokens wrap mid-word (`acme-` / `storefront`). Reported at
+   * 6-of-8 columns sized. Rules of thumb: leave the widest free-form column unsized, keep
+   * the sized columns to roughly two thirds of the table, and give the free-form one a
+   * `minWidth` when the data has long unbreakable tokens like slugs or IDs.
    */
   width?: string;
   /**
@@ -1515,6 +1564,18 @@ interface DataTableProps<Row> {
     onClick: (selectedIds: string[]) => void;
   }[];
   renderExpandedRow?: (row: Row) => ReactNode;
+  /**
+   * Row height preset.
+   *
+   * ⚠ It sets a row **height floor** (`--_row-height`), so it is invisible whenever the cell
+   * content is already taller — a two-line cell or a cell containing a `Badge` stack looks
+   * identical at every density. Reported as "barely distinguishable"; the prop is working,
+   * the content is simply winning. Shrink the cell content, or set
+   * `--cascivo-data-table-cell-gap` to tighten the horizontal rhythm too.
+   *
+   * @defaultValue `normal`
+   * @see the component manifest
+   */
   density?: 'compact' | 'normal' | 'relaxed';
   /**
    * When true, applies alternating row striping.
@@ -2650,6 +2711,16 @@ declare function HeaderPanel({
   className
 }: HeaderPanelProps): import("react").JSX.Element;
 interface SwitcherLink {
+  /**
+   * Stable React key. Provide when `label`/`href` may repeat (e.g. placeholder `#` links).
+   *
+   * Without it the rows key on `href`, so three sibling teams that all link to `/` produce
+   * duplicate-key warnings on every render and the adopter has to make the hrefs artificially
+   * distinct (2026-08-08 report A). `SideNavItem`, `ShellHeaderNavLink`,
+   * `ShellHeaderNavMenuItem`, `HeaderLink` and `CommandItem` all carry this field already;
+   * `Switcher` was missed by that sweep.
+   */
+  id?: string;
   label: string;
   href: string;
   active?: boolean;
@@ -2729,6 +2800,16 @@ interface StatProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
    * a `Card` you control; `Kpi` always brings its own chrome, which made a `Stat` row and
    * a `Kpi` row on adjacent pages of one dashboard look like different products. Set this
    * when you are mixing the two, or use it instead of hand-wrapping every `Stat` in a `Card`.
+   *
+   * ⚠ **`card` matches the CHROME only — the internal layout still differs, so do not mix
+   * `Stat` and `Kpi` in one app.** `Kpi` puts value and delta on one line with the sparkline
+   * below; `Stat` stacks value → delta → help text and puts `visual` in a trailing slot.
+   * With `card` set they share surface, border, radius and padding and still read as two
+   * tile designs (2026-08-14 report §6 — the exact symptom this prop was added to cure, on
+   * an overview page using `Stat card` next to an analytics page using `Kpi`).
+   *
+   * Pick one per app: `Kpi` when you have a numeric delta it should format and a sparkline;
+   * `Stat` otherwise.
    */
   card?: boolean;
   /** Trailing visual, e.g. a `Sparkline` from the separate `@cascivo/charts` package (not exported from `@cascivo/react`; `pnpm add @cascivo/charts`). Purely decorative — mark it `aria-hidden` yourself if it duplicates the value/delta already announced. */
@@ -2751,6 +2832,11 @@ interface StatusProps extends HTMLAttributes<HTMLSpanElement> {
    * Severity tone. Accepts the catalog-wide `Tone` vocabulary
    * (`neutral | info | success | warning | danger`) plus Status's historical spellings
    * (`error`, `destructive`, `default`).
+   *
+   * To name this type in your own code — a `Record<DeployState, Tone>` is the usual shape —
+   * import it: `import type { Tone } from '@cascivo/react/types'` on the prebuilt path, or
+   * from `@cascivo/core` if you copied the source. Do not add `@cascivo/core` to a prebuilt
+   * app just for this; it is a transitive dependency there.
    */
   status?: ToneInput;
   /**
@@ -4128,6 +4214,16 @@ declare function Resizable({
   label
 }: ResizableProps): import("react").JSX.Element;
 interface DockItem {
+  /**
+   * Stable React key. Provide when `label`/`href` may repeat.
+   *
+   * Without it the items key on their array index, so inserting or reordering a dock entry
+   * re-keys every item after it. `SideNavItem`, `ShellHeaderNavLink`, `SwitcherLink`,
+   * `BreadcrumbItem` and the rest carry this field; `Dock` was missed by all three earlier
+   * sweeps and found only once the guard derived its subjects instead of listing them
+   * (2026-08-14 report §9).
+   */
+  id?: string;
   label: string;
   icon: React.ReactNode;
   onClick?: () => void;
@@ -4442,8 +4538,24 @@ interface NativeSelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>
 declare const NativeSelect: import("react").ForwardRefExoticComponent<NativeSelectProps & import("react").RefAttributes<HTMLSelectElement>>;
 type CodeLang = 'bash' | 'css' | 'js' | 'ts';
 interface CodeSnippetProps {
-  /** The code to display (and copy). */
-  code: string;
+  /**
+   * The code to display (and copy). Equivalent to passing a plain string as `children`;
+   * `code` wins if you pass both.
+   *
+   * One of the two is required. It is a **string**, not a `ReactNode`, because the content
+   * is tokenized for highlighting and handed to the clipboard — neither works on arbitrary
+   * JSX, so accepting nodes here would silently produce an uncopyable snippet.
+   */
+  code?: string;
+  /**
+   * The code, as children — `<CodeSnippet>npm i foo</CodeSnippet>`.
+   *
+   * Every other content component in the catalog takes children, so this was the natural
+   * guess and the only compile error in a 2026-08-14 adopter's whole build (§8). Must be a
+   * plain string for the reason on `code` above; interpolation is fine
+   * (`{`npm i ${pkg}`}`), arbitrary elements are not.
+   */
+  children?: string;
   /**
    * inline = a <code> span; single = one-line <pre>; multi = multi-line <pre>.
    *
@@ -4482,6 +4594,7 @@ interface CodeSnippetProps {
  */
 declare function CodeSnippet({
   code,
+  children,
   variant,
   language,
   terminal,
@@ -4645,6 +4758,20 @@ interface AppShellProps extends HTMLAttributes<HTMLDivElement> {
   defaultOpen?: boolean;
   /** Fired when the nav requests open/close (burger, Escape, scrim). */
   onOpenChange?: ((open: boolean) => void) | undefined;
+  /**
+   * Inset around the main content area, as a space-scale step.
+   *
+   * ⚠ It **defaults to `6`**, not to none. `<main>` shipped with `padding: 0` for three
+   * releases, so every adopter wrote the same wrapper `<div style={{ padding: … }}>` and
+   * every app's first screenshot had its buttons clipped against the viewport edge — the CLI's
+   * own generated dashboard modelled the workaround with an inline style its sibling
+   * AGENTS.md forbids. Reported three times (2026-07-24, 2026-08-06, 2026-08-08).
+   *
+   * Pass `'none'` for a full-bleed layout that owns its own insets (a map, a split pane).
+   *
+   * @defaultValue `6`
+   */
+  padding?: SpaceStep | 'none';
   className?: string | undefined;
 }
 /**
@@ -4673,6 +4800,7 @@ declare function AppShell({
   open,
   defaultOpen,
   onOpenChange,
+  padding,
   className,
   ...props
 }: AppShellProps): import("react").JSX.Element;
@@ -4969,8 +5097,27 @@ declare function AutoGrid({
   ...props
 }: AutoGridProps): import("react").JSX.Element;
 interface PageHeaderProps {
-  title: string;
-  description?: string;
+  /**
+   * The page title, rendered as the `<h1>`.
+   *
+   * `ReactNode`, not `string`, so a deploy console can put the production domain in the
+   * heading as a link and a status badge beside the project name — the canonical shape of a
+   * project header. `RECIPE-DASHBOARD.md` tells you not to hand-compose `PageHeader` out of
+   * `Heading`/`Text`/`Flex`, so this has to be composable here (2026-08-14 report §7).
+   *
+   * ```tsx
+   * <PageHeader
+   *   title={<>acme-web <Badge variant="success">Ready</Badge></>}
+   *   description={<>Deployed from <Link asChild><RouterLink to="/c/abc">abc123</RouterLink></Link></>}
+   * />
+   * ```
+   *
+   * Keep it short and heading-like: it is an `<h1>`, so anything block-level inside it is
+   * invalid HTML and will fight the heading's own typography.
+   */
+  title: ReactNode;
+  /** Supporting line under the title, rendered as a `<p>`. Accepts nodes, like `title`. */
+  description?: ReactNode;
   breadcrumb?: ReactNode;
   actions?: ReactNode;
   className?: string;

package/dist/large-title-header/large-title-header.js

@@ -1,5 +1,5 @@
 import e from "./large-title-header.module.js";
-import { cn as t } from "@cascivo/core";
+import { cn as t } from "@cascivo/core/pure";
 import { jsx as n, jsxs as r } from "react/jsx-runtime";
 //#region ../components/src/large-title-header/large-title-header.tsx
 function i({ title: i, children: a, leading: o, actions: s, level: c = 1, collapseDistance: l = 48, className: u }) {

package/dist/layouts/src/grid/grid.css

@@ -1 +1 @@
-@layer cascivo.component{._grid-container_qly9o_5{display:grid;container-type:inline-size}._grid_qly9o_2{grid-template-columns:repeat(var(--_grid-cols,12), minmax(0, 1fr));gap:var(--_grid-gap,var(--cascivo-space-4));align-items:var(--_grid-align,stretch);justify-items:var(--_grid-justify,stretch);min-inline-size:0;display:grid;container-type:inline-size}@container (width<=40rem){._grid_qly9o_2:not([data-responsive]){grid-template-columns:1fr}}@container (width>=30rem){._grid_qly9o_2[data-responsive]{grid-template-columns:repeat(var(--_grid-cols-sm,var(--_grid-cols,12)), minmax(0, 1fr))}}@container (width>=40rem){._grid_qly9o_2[data-responsive]{grid-template-columns:repeat(var(--_grid-cols-md,var(--_grid-cols-sm,var(--_grid-cols,12))), minmax(0, 1fr))}}@container (width>=64rem){._grid_qly9o_2[data-responsive]{grid-template-columns:repeat(var(--_grid-cols-lg,var(--_grid-cols-md,var(--_grid-cols-sm,var(--_grid-cols,12)))), minmax(0, 1fr))}}@container (width>=80rem){._grid_qly9o_2[data-responsive]{grid-template-columns:repeat(var(--_grid-cols-xl,var(--_grid-cols-lg,var(--_grid-cols-md,var(--_grid-cols-sm,var(--_grid-cols,12))))), minmax(0, 1fr))}}._grid-item_qly9o_55{grid-column:span var(--_span,1)}@container (width>=30rem){._grid-item_qly9o_55[data-responsive]{grid-column:span var(--_span-sm,var(--_span,1))}}@container (width>=40rem){._grid-item_qly9o_55[data-responsive]{grid-column:span var(--_span-md,var(--_span-sm,var(--_span,1)))}}@container (width>=64rem){._grid-item_qly9o_55[data-responsive]{grid-column:span var(--_span-lg,var(--_span-md,var(--_span-sm,var(--_span,1))))}}@container (width>=80rem){._grid-item_qly9o_55[data-responsive]{grid-column:span var(--_span-xl,var(--_span-lg,var(--_span-md,var(--_span-sm,var(--_span,1)))))}}}
+@layer cascivo.component{._grid-container_1tchk_5{display:grid;container-type:inline-size}._grid_1tchk_2{grid-template-columns:repeat(var(--_grid-cols,12), minmax(0, 1fr));gap:var(--_grid-gap,var(--cascivo-space-4));align-items:var(--_grid-align,stretch);justify-items:var(--_grid-justify,stretch);min-inline-size:0;display:grid;container-type:inline-size}@container (width<=40rem){._grid_1tchk_2:not([data-responsive]){grid-template-columns:1fr}}@container (width>=30rem){._grid_1tchk_2[data-responsive]{grid-template-columns:repeat(var(--_grid-cols-sm,var(--_grid-cols,12)), minmax(0, 1fr))}}@container (width>=40rem){._grid_1tchk_2[data-responsive]{grid-template-columns:repeat(var(--_grid-cols-md,var(--_grid-cols-sm,var(--_grid-cols,12))), minmax(0, 1fr))}}@container (width>=64rem){._grid_1tchk_2[data-responsive]{grid-template-columns:repeat(var(--_grid-cols-lg,var(--_grid-cols-md,var(--_grid-cols-sm,var(--_grid-cols,12)))), minmax(0, 1fr))}}@container (width>=80rem){._grid_1tchk_2[data-responsive]{grid-template-columns:repeat(var(--_grid-cols-xl,var(--_grid-cols-lg,var(--_grid-cols-md,var(--_grid-cols-sm,var(--_grid-cols,12))))), minmax(0, 1fr))}}._grid-item_1tchk_55{grid-column:span var(--_span,1);align-content:stretch;display:grid}@container (width>=30rem){._grid-item_1tchk_55[data-responsive]{grid-column:span var(--_span-sm,var(--_span,1))}}@container (width>=40rem){._grid-item_1tchk_55[data-responsive]{grid-column:span var(--_span-md,var(--_span-sm,var(--_span,1)))}}@container (width>=64rem){._grid-item_1tchk_55[data-responsive]{grid-column:span var(--_span-lg,var(--_span-md,var(--_span-sm,var(--_span,1))))}}@container (width>=80rem){._grid-item_1tchk_55[data-responsive]{grid-column:span var(--_span-xl,var(--_span-lg,var(--_span-md,var(--_span-sm,var(--_span,1)))))}}}