@peripheries/renderer 0.24.0 → 0.25.0

package/README.md

@@ -51,6 +51,11 @@ const runtime = await loadPageData(page, source, { params, baseProps, viewer, co
 - `frameProps(cell, contract)`: extra attributes and style on a cell's frame,
   for what the host doesn't apply yet (a print policy, say).
 - `onDiagnostic(d)`: a page configuration problem.
+- `showHiddenCells`: where a page is being built or reviewed (an editor, a
+  harness, a preview), a cell its `hide_when_empty` leaves out shows as a
+  small "hidden (empty)" placeholder instead of nothing.
+- `showProblemCodes`: a cell's problem notice adds its diagnostic code, for
+  staff and editors; without it a viewer reads only the plain wording.
 
 A consumer with resolved values instead of a graph (the component repos'
 harness) builds its runtime with `pageRuntimeFromValues(page, { values,
@@ -70,6 +75,7 @@ names: 0.8.0 dropped the old client-prefixed twins and container names.
 | A cell's buckets | `data-hide-when`, `data-show-when`, `data-stack-when`, `data-truncate-when` |
 | A structure section | `data-section`, `data-section-level`, `data-section-kind`, `data-derived-ordinal` |
 | A missing component's notice | `data-missing-component` |
+| A cell `hide_when_empty` left out, shown by `showHiddenCells` | `.cell-hidden`, `data-cell-state="hidden-empty"` |
 
 The store specifier and runtime global are in `@peripheries/runtime`'s README.
 The theme reaches a page as CSS, in the `theme` layer; the renderer ignores a
@@ -77,6 +83,30 @@ bundle's `ThemeProvider` export.
 
 ## Versions
 
+- **0.25.0** (2026-10-24): `hide_when_empty`, a cell-level list of prop names.
+  - **A cell with `hide_when_empty: ["title", "items"]`** renders nothing, and leaves no gap,
+    when every prop it names is empty once bound: null, undefined, text that is blank once
+    trimmed, `[]` or `{}`. `0` and `false` are content. A slot or `children` filled by child
+    cells is content. Print follows the screen. The check runs before the bundles load, so a
+    server render and the browser agree.
+  - **A refused, failed or unresolved read is not empty.** A named prop that reads a label whose
+    read was refused or failed keeps the cell's error notice. One whose query never ran because
+    its own reference resolved to nothing (`QUERY_UNRESOLVED`) shows the same notice instead of
+    hiding (`hideWhenEmptyProblem`). A label still loading isn't decided yet (the cell renders).
+  - **`RendererEnvironment.showProblemCodes`**: a problem notice adds its diagnostic code
+    (`data-cell-code`, `.cell-notice__code`) for staff and editors; a client reads only "This
+    part of the page couldn't load." The host sets it in the platform environment and in a
+    proposal preview.
+  - **`RendererEnvironment.showHiddenCells`**: an editor, a harness or a preview shows a hidden
+    cell as a small "hidden (empty)" placeholder (`CellHidden`, `.cell-hidden`).
+  - **Validation:** `validatePage` reports `PROP_UNKNOWN` (warning) at
+    `content.cells[i].hide_when_empty[j]` for a name the component's `props_schema` doesn't
+    declare, and `HIDE_WHEN_EMPTY_INVALID` (error) for anything but a non-empty list of names.
+  - A ref cell's node owns `hide_when_empty` (`CONTENT_FIELDS`, via `RENDER_FIELDS`). `/core`
+    exports `hiddenWhenEmpty`, `hideWhenEmptyProblem` and `isEmptyPropValue`. `PAGE_RULES` names the key.
+  - The renderer's `PageCell` type adds `hide_when_empty?: string[]`; `@peripheries/runtime`'s
+    `PageCell` gains it at its next release.
+
 - **0.24.0** (2026-10-20): one renderer batch (CX).
   - **`layerName(system)` and `LAYER_ROLES`** in `/core`: a system's state name (its layer's role,
     else a registered layer's own type, `question`, `answer`, …) from the layer catalog, which is

package/dist/catalog.js

@@ -1,5 +1,5 @@
 import { x as isEach } from "./chunks/query-D6xQbTFK.js";
-import { i as eachFormProblems, s as validatePage } from "./chunks/validate-BcB_PA1k.js";
+import { i as eachFormProblems, s as validatePage } from "./chunks/validate-CrHGlwey.js";
 import { KNOWLEDGE_BUDGETS, KNOWLEDGE_KEY } from "@peripheries/runtime";
 import Ajv2020 from "ajv/dist/2020.js";
 var ref = (kind, key) => `${kind}:${key}`;

package/dist/chunks/{projection-zhu32_KJ.js → projection-e8MHn6Bt.js}

@@ -16,7 +16,12 @@ var STORE_FIELDS = [
 	"viewState",
 	"live"
 ];
-var CONTENT_FIELDS = [...HYDRATED_CELL_FIELDS.filter((f) => f !== "layout"), ...STORE_FIELDS];
+var RENDER_FIELDS = ["hide_when_empty"];
+var CONTENT_FIELDS = [
+	...HYDRATED_CELL_FIELDS.filter((f) => f !== "layout"),
+	...STORE_FIELDS,
+	...RENDER_FIELDS
+];
 function normalizeCell(cell, path = "cell") {
 	const diagnostics = [];
 	if (cell.ref) return {
@@ -114,6 +119,39 @@ function failedLabels(cell, data) {
 		return Boolean(entry?.error) && !entry?.unresolved?.length && !entry?.isLoading && (entry?.data === void 0 || entry?.data === null);
 	});
 }
+function isEmptyPropValue(value) {
+	if (value === null || value === void 0) return true;
+	if (typeof value === "string") return value.trim() === "";
+	if (Array.isArray(value)) return value.length === 0;
+	if (typeof value === "object") {
+		const proto = Object.getPrototypeOf(value);
+		return (proto === Object.prototype || proto === null) && Object.keys(value).length === 0;
+	}
+	return false;
+}
+var propLabels = (value) => [...JSON.stringify(value ?? null).matchAll(LABEL_REF)].map((m) => m[1]);
+function hideWhenEmptyProblem(cell, data) {
+	const names = cell.hide_when_empty;
+	if (!Array.isArray(names)) return null;
+	for (const name of names) {
+		if (typeof name !== "string") continue;
+		for (const label of propLabels(cell.props?.[name])) if (data[label]?.unresolved?.length && !data[label]?.isLoading) return "QUERY_UNRESOLVED";
+	}
+	return null;
+}
+function hiddenWhenEmpty(cell, props, data) {
+	const names = cell.hide_when_empty;
+	if (!Array.isArray(names) || names.length === 0) return false;
+	for (const name of names) {
+		if (typeof name !== "string") return false;
+		for (const label of propLabels(cell.props?.[name])) {
+			const entry = data[label];
+			if (entry?.isLoading || entry?.error) return false;
+		}
+		if (!isEmptyPropValue(props[name])) return false;
+	}
+	return true;
+}
 function assembleCellProps(i) {
 	const { style: _fromConfig, ...resolved } = i.resolvedProps;
 	const props = { ...resolved };
@@ -304,4 +342,4 @@ function collectScopeIds(ctx, selections, viewState) {
 	}
 	return [...ids];
 }
-export { normalizeCell as C, hasRef as S, rootCells as T, failedLabels as _, projectSelections as a, HYDRATED_CELL_FIELDS as b, pageScopeKey as c, resolveComponent as d, cellAttributes as f, assembleCellProps as g, pageContainerStyle as h, projectLive as i, projectScopeKey as l, documentProfile as m, attachViewStateSetters as n, projectViewState as o, cellPlacementStyle as p, collectScopeIds as r, shallowEqualBundle as s, attachSelectionSetters as t, resolveScopeId as u, projectCellData as v, resolveCell as w, STORE_FIELDS as x, CONTENT_FIELDS as y };
+export { HYDRATED_CELL_FIELDS as C, normalizeCell as D, hasRef as E, resolveCell as O, CONTENT_FIELDS as S, STORE_FIELDS as T, failedLabels as _, projectSelections as a, isEmptyPropValue as b, pageScopeKey as c, resolveComponent as d, cellAttributes as f, assembleCellProps as g, pageContainerStyle as h, projectLive as i, rootCells as k, projectScopeKey as l, documentProfile as m, attachViewStateSetters as n, projectViewState as o, cellPlacementStyle as p, collectScopeIds as r, shallowEqualBundle as s, attachSelectionSetters as t, resolveScopeId as u, hiddenWhenEmpty as v, RENDER_FIELDS as w, projectCellData as x, hideWhenEmptyProblem as y };

package/dist/chunks/{validate-BcB_PA1k.js → validate-CrHGlwey.js}

@@ -641,6 +641,16 @@ function validateCell(cell, catalog, path = "cell", ids, options = {}) {
 					message: `${cell.component} requires ${prop}`
 				});
 			}
+			const listed = schema?.properties;
+			if (listed && Array.isArray(cell.hide_when_empty)) cell.hide_when_empty.forEach((prop, i) => {
+				if (typeof prop === "string" && prop !== "children" && !(prop in listed)) push({
+					severity: "warning",
+					code: "PROP_UNKNOWN",
+					cellId,
+					path: `${path}.hide_when_empty[${i}]`,
+					message: `hide_when_empty names ${prop}, which ${cell.component} doesn’t declare`
+				});
+			});
 			const declared = schema?.properties;
 			if (declared && schema?.additionalProperties !== true && typeof schema?.additionalProperties !== "object") {
 				for (const prop of Object.keys(cell.props ?? {})) if (prop !== "children" && prop !== "style" && !(prop in declared)) push({
@@ -674,6 +684,14 @@ function validateCell(cell, catalog, path = "cell", ids, options = {}) {
 		path: `${path}.children`,
 		message: `child cell "${child}" is not on the page`
 	});
+	const hide = cell.hide_when_empty;
+	if (hide !== void 0 && (!Array.isArray(hide) || hide.length === 0 || hide.some((p) => typeof p !== "string" || !p))) push({
+		severity: "error",
+		code: "HIDE_WHEN_EMPTY_INVALID",
+		cellId,
+		path: `${path}.hide_when_empty`,
+		message: "hide_when_empty takes a non-empty list of prop names"
+	});
 	checkBindings(cell.data?.queries, `${path}.data.queries`, push, cellId, options.template);
 	checkActions(cell, path, push);
 	checkProjections(cell.props, `${path}.props`, push, cellId);

package/dist/core.js

@@ -1,6 +1,6 @@
-import { C as normalizeCell, S as hasRef, T as rootCells, a as projectSelections, b as HYDRATED_CELL_FIELDS, c as pageScopeKey, d as resolveComponent, f as cellAttributes, g as assembleCellProps, h as pageContainerStyle, i as projectLive, l as projectScopeKey, n as attachViewStateSetters, o as projectViewState, p as cellPlacementStyle, r as collectScopeIds, s as shallowEqualBundle, t as attachSelectionSetters, u as resolveScopeId, v as projectCellData, w as resolveCell, x as STORE_FIELDS, y as CONTENT_FIELDS } from "./chunks/projection-zhu32_KJ.js";
+import { C as HYDRATED_CELL_FIELDS, D as normalizeCell, E as hasRef, O as resolveCell, S as CONTENT_FIELDS, T as STORE_FIELDS, a as projectSelections, b as isEmptyPropValue, c as pageScopeKey, d as resolveComponent, f as cellAttributes, g as assembleCellProps, h as pageContainerStyle, i as projectLive, k as rootCells, l as projectScopeKey, n as attachViewStateSetters, o as projectViewState, p as cellPlacementStyle, r as collectScopeIds, s as shallowEqualBundle, t as attachSelectionSetters, u as resolveScopeId, v as hiddenWhenEmpty, w as RENDER_FIELDS, x as projectCellData, y as hideWhenEmptyProblem } from "./chunks/projection-e8MHn6Bt.js";
 import { C as passesConditions, S as pageContext, T as settled, _ as EACH, a as VARIABLE_NAMESPACES, b as cellResolutionContext, c as pageVariables, d as resolveDescriptorVariables, f as selectionShape, g as variableReferences, h as variableLabels, i as UnsafeDocumentError, l as prepareDocument, m as validateDescriptor, n as RENDER_FUNCTIONS, o as descriptorShape, p as shapeAt, r as RENDER_FUNCTIONS_AHEAD, s as orderByVariable, t as PAGING_VARIABLES, u as queryKey, v as EACH_DEFAULT_AS, w as resolveReferences, x as isEach, y as cellContext } from "./chunks/query-D6xQbTFK.js";
-import { _ as stateValue, a as nearestNames, b as walkKey, c as selectionIssues, d as needsWalk, f as readField, g as stateNames, h as resolveWalkStart, i as eachFormProblems, l as RESERVED_LABELS, m as referencedLabels, n as STORE_SCOPES, o as validateCell, p as readWalk, r as WALK_DIRECTIONS, s as validatePage, t as RESPONSIVE_BUCKETS, u as mergeStates, v as systemsFromGraphs, x as walkRequest, y as systemsFromProcess } from "./chunks/validate-BcB_PA1k.js";
+import { _ as stateValue, a as nearestNames, b as walkKey, c as selectionIssues, d as needsWalk, f as readField, g as stateNames, h as resolveWalkStart, i as eachFormProblems, l as RESERVED_LABELS, m as referencedLabels, n as STORE_SCOPES, o as validateCell, p as readWalk, r as WALK_DIRECTIONS, s as validatePage, t as RESPONSIVE_BUCKETS, u as mergeStates, v as systemsFromGraphs, x as walkRequest, y as systemsFromProcess } from "./chunks/validate-CrHGlwey.js";
 import { C as resolveAction, S as projectCellActions, _ as actionBindingKey, a as deriveSectionReferences, b as declaredActions, c as nodePrintStyle, d as referencesFor, f as sectionAnchor, g as usesStructureLayout, h as tableOfContents, i as deriveSectionNumbering, l as normalizeStructure, m as structureIssues, n as SECTION_KINDS, r as deriveElementReferences, s as mergeSectionReferences, t as PAGE_DOCUMENT, u as numberingFor, v as actionProblems, x as normalizeActionDeclaration, y as actionReferences } from "./chunks/structure-CKBtQHJq.js";
 import { a as loadBundlesSettled, i as loadBundles, n as isComponentExport, o as projectModule, r as loadBundle, s as runtimeReady, t as _clearBundleCache } from "./chunks/load-b38vUiZM.js";
 import { a as normalizeRef, i as bundleScope, n as MAIN, o as refKey, r as PUBLIC, t as CORE_SPECIFIER } from "./chunks/refs-Csgh6rXq.js";
@@ -801,6 +801,10 @@ var DIAGNOSTICS = {
 		meaning: "A literal prop value fails its schema.",
 		fix: "Write the value in the shape `props_schema` gives, or bind it with a whole-string `@label.path` reference."
 	},
+	HIDE_WHEN_EMPTY_INVALID: {
+		meaning: "A cell’s `hide_when_empty` isn’t a list of prop names.",
+		fix: "Write `hide_when_empty: [\"title\", \"items\"]`: the props that, all empty once bound (null, blank text, `[]`, `{}`), leave the cell out."
+	},
 	CELL_UNKNOWN_CHILD: {
 		meaning: "`children` names a cell that is not on the page.",
 		fix: "List only ids of cells on this page in `children`."
@@ -1054,7 +1058,7 @@ The host's rules for every page. Components, kits and patterns are in the catalo
 - Every cell has a unique \`id\`. Inline: \`{ id, component, props, layout? }\`. Managed by a cell node: \`{ id, ref: { graph_node_id }, layout? }\`; its \`component\` and \`props\` are the fallback.
 - \`children\` lists child cell ids, rendered inside the cell in place of \`props.children\`.
 - A child with \`slot\` fills that \`x-slot\` of its parent; others are \`children\`.
-- \`conditions.showIf\` / \`hideIf\` test a value, usually a reference, for truthiness.
+- \`conditions.showIf\` / \`hideIf\` test a value for truthiness; \`hide_when_empty: [props]\` hides the cell if all are empty.
 - An embed cell \`{ id, embed: { page_id } | { page_type, project_id?, process_id? } }\` renders another published page, one level deep.
 
 ## Data and references
@@ -1132,4 +1136,4 @@ function manifestPageFrom(graphNodeId, data) {
 		}
 	};
 }
-export { CONTENT_FIELDS, CORE_SPECIFIER, DIAGNOSTICS, EACH, EACH_DEFAULT_AS, HYDRATED_CELL_FIELDS, LAYER_ROLES, LAYOUT_TYPES, MAIN, PAGE_DOCUMENT, PAGE_RULES, PAGING_VARIABLES, PUBLIC, RENDER_FUNCTIONS, RENDER_FUNCTIONS_AHEAD, RESERVED_LABELS, RESPONSIVE_BUCKETS, SECTION_KINDS, STORE_FIELDS, STORE_SCOPES, STRUCTURE_FIELDS, TOOL_OWNED_KEYS, UnsafeDocumentError, VARIABLE_NAMESPACES, WALK_DIRECTIONS, _clearBundleCache, actionBindingKey, actionProblems, actionReferences, assembleCellProps, attachSelectionSetters, attachViewStateSetters, buildDataContext, bundleScope, cellAttributes, cellContext, cellPlacementStyle, cellPropSources, cellResolutionContext, clearScope, collectDeclarations, collectDescriptors, collectScopeIds, collectStatic, createStackStore, declaredActions, deriveElementReferences, deriveSectionNumbering, deriveSectionReferences, descriptorShape, eachFormProblems, editTarget, hasRef, isComponentExport, isEach, layerName, loadBundle, loadBundles, loadBundlesSettled, loadPageData, loadScope, manifestPageFrom, mergeSectionReferences, mergeStates, nearestNames, needsWalk, nodePrintStyle, normalizeActionDeclaration, normalizeCell, normalizeRef, normalizeStructure, numberingFor, orderByVariable, pageBundleRefs, pageBundles, pageContainerStyle, pageContext, pageRuntimeFromValues, pageScopeKey, pageVariables, passesConditions, patchAt, prepareDocument, projectCellActions, projectCellData, projectLive, projectModule, projectScopeKey, projectSelections, projectViewState, queryKey, readField, readWalk, refKey, referencedLabels, referencesFor, resolveAction, resolveCell, resolveComponent, resolveDataSystem, resolveDeclarations, resolveDescriptorVariables, resolveReferences, resolveScopeId, resolveSystems, resolveWalkStart, rootCells, runtimeReady, saveScope, sectionAnchor, selectionIssues, selectionShape, settled, shallowEqualBundle, shapeAt, stateNames, stateValue, structureIssues, systemsFromGraphs, systemsFromProcess, tableOfContents, usesStructureLayout, validateCell, validateDescriptor, validateManifest, validatePage, variableLabels, variableReferences, walkKey, walkRequest };
+export { CONTENT_FIELDS, CORE_SPECIFIER, DIAGNOSTICS, EACH, EACH_DEFAULT_AS, HYDRATED_CELL_FIELDS, LAYER_ROLES, LAYOUT_TYPES, MAIN, PAGE_DOCUMENT, PAGE_RULES, PAGING_VARIABLES, PUBLIC, RENDER_FIELDS, RENDER_FUNCTIONS, RENDER_FUNCTIONS_AHEAD, RESERVED_LABELS, RESPONSIVE_BUCKETS, SECTION_KINDS, STORE_FIELDS, STORE_SCOPES, STRUCTURE_FIELDS, TOOL_OWNED_KEYS, UnsafeDocumentError, VARIABLE_NAMESPACES, WALK_DIRECTIONS, _clearBundleCache, actionBindingKey, actionProblems, actionReferences, assembleCellProps, attachSelectionSetters, attachViewStateSetters, buildDataContext, bundleScope, cellAttributes, cellContext, cellPlacementStyle, cellPropSources, cellResolutionContext, clearScope, collectDeclarations, collectDescriptors, collectScopeIds, collectStatic, createStackStore, declaredActions, deriveElementReferences, deriveSectionNumbering, deriveSectionReferences, descriptorShape, eachFormProblems, editTarget, hasRef, hiddenWhenEmpty, hideWhenEmptyProblem, isComponentExport, isEach, isEmptyPropValue, layerName, loadBundle, loadBundles, loadBundlesSettled, loadPageData, loadScope, manifestPageFrom, mergeSectionReferences, mergeStates, nearestNames, needsWalk, nodePrintStyle, normalizeActionDeclaration, normalizeCell, normalizeRef, normalizeStructure, numberingFor, orderByVariable, pageBundleRefs, pageBundles, pageContainerStyle, pageContext, pageRuntimeFromValues, pageScopeKey, pageVariables, passesConditions, patchAt, prepareDocument, projectCellActions, projectCellData, projectLive, projectModule, projectScopeKey, projectSelections, projectViewState, queryKey, readField, readWalk, refKey, referencedLabels, referencesFor, resolveAction, resolveCell, resolveComponent, resolveDataSystem, resolveDeclarations, resolveDescriptorVariables, resolveReferences, resolveScopeId, resolveSystems, resolveWalkStart, rootCells, runtimeReady, saveScope, sectionAnchor, selectionIssues, selectionShape, settled, shallowEqualBundle, shapeAt, stateNames, stateValue, structureIssues, systemsFromGraphs, systemsFromProcess, tableOfContents, usesStructureLayout, validateCell, validateDescriptor, validateManifest, validatePage, variableLabels, variableReferences, walkKey, walkRequest };

package/dist/react.js

@@ -1,4 +1,4 @@
-import { T as rootCells, _ as failedLabels, a as projectSelections, d as resolveComponent, f as cellAttributes, g as assembleCellProps, h as pageContainerStyle, i as projectLive, m as documentProfile, n as attachViewStateSetters, o as projectViewState, p as cellPlacementStyle, s as shallowEqualBundle, t as attachSelectionSetters, u as resolveScopeId, v as projectCellData } from "./chunks/projection-zhu32_KJ.js";
+import { _ as failedLabels, a as projectSelections, d as resolveComponent, f as cellAttributes, g as assembleCellProps, h as pageContainerStyle, i as projectLive, k as rootCells, m as documentProfile, n as attachViewStateSetters, o as projectViewState, p as cellPlacementStyle, s as shallowEqualBundle, t as attachSelectionSetters, u as resolveScopeId, v as hiddenWhenEmpty, x as projectCellData, y as hideWhenEmptyProblem } from "./chunks/projection-e8MHn6Bt.js";
 import { C as passesConditions, S as pageContext, T as settled, b as cellResolutionContext, c as pageVariables, v as EACH_DEFAULT_AS, w as resolveReferences, y as cellContext } from "./chunks/query-D6xQbTFK.js";
 import { a as deriveSectionReferences, b as declaredActions, c as nodePrintStyle, d as referencesFor, f as sectionAnchor, g as usesStructureLayout, i as deriveSectionNumbering, l as normalizeStructure, m as structureIssues, o as isSectionNode, p as sortByOrder, r as deriveElementReferences, s as mergeSectionReferences, t as PAGE_DOCUMENT, u as numberingFor } from "./chunks/structure-CKBtQHJq.js";
 import { a as goToQuestion, c as missing, f as progress, g as visibleSteps, h as stepKind, i as goTo, l as move, m as settle, n as enterAdvances, o as isReadOnlyStatus, p as questionsOf, s as linkTo, t as defaultMode, u as positionFromLink } from "./chunks/forms-DxA9WzCt.js";
@@ -12,18 +12,34 @@ function CellPlaceholder({ state }) {
 		"aria-busy": state === "loading"
 	});
 }
-function CellNotice({ state, component, onRetry, children }) {
+function CellHidden() {
+	return jsx("div", {
+		className: "cell-hidden",
+		"data-cell-state": "hidden-empty",
+		role: "note",
+		children: "hidden (empty)"
+	});
+}
+function CellNotice({ state, component, onRetry, code, showCode, children }) {
 	return jsxs("div", {
 		className: "cell-notice",
 		"data-cell-state": state,
 		role: state === "error" ? "alert" : "note",
 		...state === "not-found" && component ? { "data-missing-component": component } : {},
-		children: [children, onRetry && jsxs(Fragment$1, { children: [" ", jsx("button", {
-			type: "button",
-			className: "cell-notice__retry",
-			onClick: onRetry,
-			children: "Try again"
-		})] })]
+		children: [
+			children,
+			code && showCode && jsxs(Fragment$1, { children: [" ", jsx("code", {
+				className: "cell-notice__code",
+				"data-cell-code": code,
+				children: code
+			})] }),
+			onRetry && jsxs(Fragment$1, { children: [" ", jsx("button", {
+				type: "button",
+				className: "cell-notice__retry",
+				onClick: onRetry,
+				children: "Try again"
+			})] })
+		]
 	});
 }
 var CellErrorBoundary = class extends Component {
@@ -219,6 +235,23 @@ function mergeActions(a, b) {
 		...b
 	} : void 0;
 }
+function boundProps(cell, ctx, env, injectedProps) {
+	const out = { ...resolveReferences(cell.props ?? {}, ctx) };
+	for (const id of cell.children ?? []) {
+		const child = env.cellsById.get(id);
+		if (!child) continue;
+		const slot = typeof child.slot === "string" && child.slot ? child.slot : "children";
+		if (slot === "item" && cell.props?.each !== void 0) {
+			const each = out.each;
+			out[slot] = Array.isArray(each) ? each : out[slot];
+		} else out[slot] = [...Array.isArray(out[slot]) ? out[slot] : [], id];
+	}
+	return {
+		...out,
+		...injectedProps,
+		...env.cellProps?.(cell)
+	};
+}
 function CellView({ cell, env, nested = false, injectedProps }) {
 	const frame = useRef(null);
 	const store = useCellStore(cell, env.scope, env.store);
@@ -305,8 +338,19 @@ function CellView({ cell, env, nested = false, injectedProps }) {
 		context
 	]);
 	if (!passesConditions(cell.conditions, ctx)) return null;
+	const deciding = Boolean(cell.hide_when_empty?.length && cell.component && !cell.embed && !failedLabels(cell, ctx.data).length);
+	const problem = deciding ? hideWhenEmptyProblem(cell, ctx.data) : null;
+	const hidden = deciding && !problem && hiddenWhenEmpty(cell, boundProps(cell, ctx, env, injectedProps), ctx.data);
+	if (hidden && !env.showHiddenCells) return null;
 	let body;
-	if (cell.embed) body = env.renderEmbed?.(cell.id) ?? null;
+	if (hidden) body = jsx(CellHidden, {});
+	else if (problem) body = jsx(CellNotice, {
+		state: "error",
+		code: problem,
+		showCode: env.showProblemCodes,
+		children: "This part of the page couldn't load."
+	});
+	else if (cell.embed) body = env.renderEmbed?.(cell.id) ?? null;
 	else if (!cell.component) body = jsx(CellPlaceholder, { state: "pending" });
 	else if (failedLabels(cell, ctx.data).length) body = jsx(CellNotice, {
 		state: "error",
@@ -528,7 +572,7 @@ var warn = (d) => console.warn(`[render] ${d.code}${d.cellId ? ` (cell ${d.cellI
 function PageRenderer({ runtime, bundles, params, baseProps, context, viewer, environment }) {
 	const { page, cells } = runtime;
 	const declared = useMemo(() => new Set(runtime.declared), [runtime.declared]);
-	const { core, navigate, store, onDiagnostic = warn, actionsFor, runAction, loadPage, onCellError, onUnresolvedReference, onPropSources, frameProps, cellProps, retry } = environment;
+	const { core, navigate, store, onDiagnostic = warn, actionsFor, runAction, loadPage, onCellError, onUnresolvedReference, onPropSources, frameProps, cellProps, retry, showHiddenCells, showProblemCodes } = environment;
 	useEffect(() => {
 		for (const d of runtime.diagnostics) onDiagnostic(d);
 	}, [runtime.diagnostics, onDiagnostic]);
@@ -556,6 +600,8 @@ function PageRenderer({ runtime, bundles, params, baseProps, context, viewer, en
 			onDiagnostic,
 			frameProps,
 			cellProps,
+			showHiddenCells,
+			showProblemCodes,
 			renderEmbed: (cellId) => {
 				const embedded = runtime.embeds?.[cellId];
 				if (!embedded) return jsx(CellNotice, {
@@ -607,6 +653,8 @@ function PageRenderer({ runtime, bundles, params, baseProps, context, viewer, en
 		frameProps,
 		cellProps,
 		retry,
+		showHiddenCells,
+		showProblemCodes,
 		environment
 	]);
 	const structured = usesStructureLayout(page.layout);
@@ -980,4 +1028,4 @@ function bindActions(v, path, latest) {
 	if (v && typeof v === "object") return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, bindActions(x, [...path, k], latest)]));
 	return v;
 }
-export { CellErrorBoundary, CellNotice, CellPlaceholder, CellView, FORM_SAVE_DEBOUNCE_MS, PageRenderer, StructureView, answerInputId, cellLabels, useCellStore, useContainerSize, useFormsRuntime, usePaging, useStructureFacts };
+export { CellErrorBoundary, CellHidden, CellNotice, CellPlaceholder, CellView, FORM_SAVE_DEBOUNCE_MS, PageRenderer, StructureView, answerInputId, cellLabels, useCellStore, useContainerSize, useFormsRuntime, usePaging, useStructureFacts };

package/dist/styles.css

@@ -6,6 +6,8 @@
     --cell-placeholder-bg: var(--color-surface-sunken, #f1f1f1);
     --cell-notice-bg: var(--color-warning-surface, #fff4d6);
     --cell-notice-fg: var(--color-warning, #6b4e00);
+    --cell-hidden-border: var(--color-border, #c8c8c8);
+    --cell-hidden-fg: var(--color-text-muted, #6b6b6b);
   }
   
   [data-page-container] { font-family: var(--font-body, system-ui, sans-serif); color: var(--color-text, inherit); }
@@ -17,7 +19,9 @@
   .cell-placeholder[aria-busy='true'] { animation: cell-pulse 1.5s ease-in-out infinite; }
   @keyframes cell-pulse { 50% { opacity: 0.55; } }
   @media (prefers-reduced-motion: reduce) { .cell-placeholder[aria-busy='true'] { animation: none; } }
+  .cell-hidden { padding: 0.125rem 0.5rem; border: 1px dashed var(--cell-hidden-border); border-radius: 0.375rem; color: var(--cell-hidden-fg); font-size: 0.75rem; line-height: 1.5; }
   .cell-notice { padding: 0.75rem 1rem; border-radius: 0.5rem; background: var(--cell-notice-bg); color: var(--cell-notice-fg); }
+  .cell-notice__code { font-family: var(--font-mono, ui-monospace, monospace); font-size: 0.75rem; }
 
   
   [data-show-when] { display: none; }
@@ -45,6 +49,8 @@
       --cell-placeholder-bg: #262626;
       --cell-notice-bg: #3a300f;
       --cell-notice-fg: #f5dc9a;
+      --cell-hidden-border: #4a4a4a;
+      --cell-hidden-fg: #a3a3a3;
     }
   }
 

package/dist/types/core/cell-props.d.ts

@@ -9,6 +9,9 @@ export declare function projectCellData(cell: PageCell, ctx: DataContext): {
     status: CellStatus;
 } | null;
 export declare function failedLabels(cell: PageCell, data: DataContext): string[];
+export declare function isEmptyPropValue(value: unknown): boolean;
+export declare function hideWhenEmptyProblem(cell: Pick<PageCell, 'hide_when_empty' | 'props'>, data: DataContext): 'QUERY_UNRESOLVED' | null;
+export declare function hiddenWhenEmpty(cell: Pick<PageCell, 'hide_when_empty' | 'props'>, props: Record<string, unknown>, data: DataContext): boolean;
 export type AssembledInputs = {
     resolvedProps: Record<string, unknown>;
     children: unknown;

package/dist/types/core/cells.d.ts

@@ -2,7 +2,8 @@ import type { Diagnostic } from './graph.js';
 import type { PageCell } from './types.js';
 export declare const HYDRATED_CELL_FIELDS: readonly ["component", "props", "layout", "conditions", "children", "traversal", "data", "bundle_ref", "actions", "embed"];
 export declare const STORE_FIELDS: readonly ["selections", "viewState", "live"];
-export declare const CONTENT_FIELDS: readonly [...("data" | "component" | "props" | "conditions" | "children" | "traversal" | "bundle_ref" | "actions" | "embed")[], "selections", "viewState", "live"];
+export declare const RENDER_FIELDS: readonly ["hide_when_empty"];
+export declare const CONTENT_FIELDS: readonly [...("component" | "props" | "conditions" | "children" | "traversal" | "data" | "bundle_ref" | "actions" | "embed")[], "selections", "viewState", "live", "hide_when_empty"];
 export type CellSource = 'inline' | 'node' | 'fallback' | 'pending';
 export type ResolvedCell = PageCell & {
     source: CellSource;

package/dist/types/core/diagnostics.d.ts

@@ -51,6 +51,10 @@ export declare const DIAGNOSTICS: {
         readonly meaning: "A literal prop value fails its schema.";
         readonly fix: "Write the value in the shape `props_schema` gives, or bind it with a whole-string `@label.path` reference.";
     };
+    readonly HIDE_WHEN_EMPTY_INVALID: {
+        readonly meaning: "A cell’s `hide_when_empty` isn’t a list of prop names.";
+        readonly fix: "Write `hide_when_empty: [\"title\", \"items\"]`: the props that, all empty once bound (null, blank text, `[]`, `{}`), leave the cell out.";
+    };
     readonly CELL_UNKNOWN_CHILD: {
         readonly meaning: "`children` names a cell that is not on the page.";
         readonly fix: "List only ids of cells on this page in `children`.";

package/dist/types/core/index.d.ts

@@ -1,4 +1,4 @@
-export { CONTENT_FIELDS, hasRef, HYDRATED_CELL_FIELDS, normalizeCell, resolveCell, rootCells, STORE_FIELDS, type CellSource, type ResolvedCell } from './cells.js';
+export { CONTENT_FIELDS, hasRef, HYDRATED_CELL_FIELDS, normalizeCell, resolveCell, RENDER_FIELDS, rootCells, STORE_FIELDS, type CellSource, type ResolvedCell } from './cells.js';
 export { buildDataContext, collectDeclarations, collectDescriptors, collectStatic, readField, resolveDeclarations, type ResolvedDeclaration, type StateRead } from './data-context.js';
 export { mergeStates, needsWalk, readWalk, referencedLabels, RESERVED_LABELS, resolveWalkStart, stateNames, stateValue, systemsFromGraphs, systemsFromProcess, walkKey, walkRequest, type Diagnostic, type GraphSystem, type ProcessSystems, type RawWalk, type WalkBinding, type WalkRequest, type WalkStart, } from './graph.js';
 export { LAYER_ROLES, layerName, type LayerType } from './layers.js';
@@ -14,7 +14,7 @@ export { pageRuntimeFromValues } from './values.js';
 export { actionBindingKey, actionProblems, actionReferences, declaredActions, normalizeActionDeclaration, projectCellActions, resolveAction, type RunAction } from './actions.js';
 export type { ActionDeclaration } from '@peripheries/runtime';
 export type * from './types.js';
-export { assembleCellProps, projectCellData, type CellStatus } from './cell-props.js';
+export { assembleCellProps, hiddenWhenEmpty, hideWhenEmptyProblem, isEmptyPropValue, projectCellData, type CellStatus } from './cell-props.js';
 export { cellAttributes, cellPlacementStyle, pageContainerStyle } from './layout.js';
 export { deriveElementReferences, deriveSectionNumbering, deriveSectionReferences, mergeSectionReferences, nodePrintStyle, normalizeStructure, numberingFor, PAGE_DOCUMENT, referencesFor, SECTION_KINDS, sectionAnchor, structureIssues, tableOfContents, usesStructureLayout, type ContentsEntry, type LayoutNode, type SectionNumbering, type SectionReference, type SectionReferences, } from './structure.js';
 export { _clearBundleCache, isComponentExport, loadBundle, loadBundles, loadBundlesSettled, projectModule, runtimeReady, type BundleFiles, type BundleRow, type LoadedBundle, type LoadedBundles, } from './bundles/load.js';

package/dist/types/core/types.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredBinding, PageCell, QueryDescriptor } from '@peripheries/runtime';
+import type { DeclaredBinding, PageCell as RuntimePageCell, QueryDescriptor } from '@peripheries/runtime';
 export type DataPage = {
     hasMore: boolean;
     endCursor: string | null;
@@ -37,7 +37,10 @@ export type DataOrigin = {
     kind: 'reserved';
 };
 export type DataContext = Record<string, DataEntry>;
-export type { CellData, CellLayout, DeclaredBinding, PageCell, ResponsiveBucket } from '@peripheries/runtime';
+export type { CellData, CellLayout, DeclaredBinding, ResponsiveBucket } from '@peripheries/runtime';
+export type PageCell = RuntimePageCell & {
+    hide_when_empty?: string[];
+};
 export type PageContent = {
     cells?: PageCell[];
     data?: {

package/dist/types/react/cell-states.d.ts

@@ -2,10 +2,13 @@ import { Component, type ReactNode } from 'react';
 export declare function CellPlaceholder({ state }: {
     state: 'loading' | 'pending';
 }): import("react").JSX.Element;
-export declare function CellNotice({ state, component, onRetry, children }: {
+export declare function CellHidden(): import("react").JSX.Element;
+export declare function CellNotice({ state, component, onRetry, code, showCode, children }: {
     state: 'not-found' | 'error';
     component?: string;
     onRetry?: () => void;
+    code?: string;
+    showCode?: boolean;
     children: ReactNode;
 }): import("react").JSX.Element;
 export declare class CellErrorBoundary extends Component<{

package/dist/types/react/cell-view.d.ts

@@ -38,6 +38,8 @@ export type CellEnvironment = {
     onDiagnostic?: (d: Diagnostic) => void;
     frameProps?: (cell: PageCell, contract: ComponentContract | undefined) => FrameProps | undefined;
     cellProps?: (cell: PageCell) => Record<string, unknown> | undefined;
+    showHiddenCells?: boolean;
+    showProblemCodes?: boolean;
 };
 export type FrameProps = {
     attributes?: Record<string, string>;

package/dist/types/react/index.d.ts

@@ -1,4 +1,4 @@
-export { CellErrorBoundary, CellNotice, CellPlaceholder } from './cell-states.js';
+export { CellErrorBoundary, CellHidden, CellNotice, CellPlaceholder } from './cell-states.js';
 export { CellView, type CellEnvironment, type FrameProps } from './cell-view.js';
 export { PageRenderer, type PageRendererProps, type RendererEnvironment } from './page-renderer.js';
 export { StructureView, useStructureFacts } from './structure-view.js';

package/dist/types/react/page-renderer.d.ts

@@ -23,6 +23,8 @@ export type RendererEnvironment = {
     retry?: () => void;
     frameProps?: (cell: PageCell, contract: ComponentContract | undefined) => FrameProps | undefined;
     cellProps?: (cell: PageCell) => Record<string, unknown> | undefined;
+    showHiddenCells?: boolean;
+    showProblemCodes?: boolean;
 };
 export type PageRendererProps = {
     runtime: PageRuntime;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peripheries/renderer",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "The one renderer for pages of federated component bundles: a framework-free core, a React renderer, the runtime a page boots with, and golden pages for testing.",
   "type": "module",
   "sideEffects": [