@peripheries/renderer 0.24.0 → 0.26.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,36 @@ bundle's `ThemeProvider` export.
 
 ## Versions
 
+- **Unreleased:** `RENDER_FUNCTIONS` adds `pages_awaiting_release(p_project_id)`:
+  a project's pages whose newest main page-state is newer than the one their
+  client channel's release holds, for staff (an empty array for anyone else).
+  - **Removable in the next minor:** `GraphSource.processSystems` (the process's cached system
+    columns, read only by a source without `graphSystems`). The host no longer implements it;
+    `graphSystems` is the way, and the process columns it reads are being dropped.
+- **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 { x as isEach } from "./chunks/query-CNaB25jE.js";
+import { a as eachFormProblems, c as validatePage, i as componentsFor } from "./chunks/validate-DRkCpQaY.js";
 import { KNOWLEDGE_BUDGETS, KNOWLEDGE_KEY } from "@peripheries/runtime";
 import Ajv2020 from "ajv/dist/2020.js";
 var ref = (kind, key) => `${kind}:${key}`;
@@ -216,7 +216,7 @@ var asNode = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : void 0
 function propsAgainstSchemas(page, catalog, ajv) {
 	const out = [];
 	(Array.isArray(page.content?.cells) ? page.content.cells : []).forEach((cell, i) => {
-		const properties = cell?.component ? catalog.components[cell.component]?.props_schema?.properties : void 0;
+		const properties = cell?.component ? componentsFor(catalog, cell)[cell.component]?.props_schema?.properties : void 0;
 		for (const [prop, value] of Object.entries(cell.props ?? {})) {
 			const schema = properties?.[prop];
 			const path = `content.cells[${i}].props.${prop}`;

package/dist/chunks/{page-bundles-CPj_vx-J.js → page-bundles-_wsGO9WU.js}

@@ -15,16 +15,22 @@ function rowMatches(ref, row) {
 	if (ref.kind === "pinned") return row.id === ref.bundleId;
 	return row.bundle_name === ref.bundle && (ref.kind === "lineage-in-org" ? row.org_id === ref.orgId : row.org_slug === ref.orgSlug);
 }
+function rowsInScope(rows, scope) {
+	return rows.filter((row) => scope.some((r) => rowMatches(r, row)));
+}
+function rowForCell(rows, cell, pageOrgId) {
+	const ref = normalizeRef(cell.bundle_ref, pageOrgId);
+	return ref && rows.find((r) => rowMatches(ref, r)) || null;
+}
 function pageBundles(scope, rows, loaded, pageOrgId, failed = false) {
 	const byRow = new Map((loaded ?? []).map((b) => [b.id, b]));
 	return {
 		failed,
-		scope: loaded ? rows.filter((row) => scope.some((r) => rowMatches(r, row))).flatMap((row) => byRow.get(row.id) ?? []) : null,
+		scope: loaded ? rowsInScope(rows, scope).flatMap((row) => byRow.get(row.id) ?? []) : null,
 		forCell: (cell) => {
-			const ref = normalizeRef(cell.bundle_ref, pageOrgId);
-			const row = ref && rows.find((r) => rowMatches(ref, r));
+			const row = rowForCell(rows, cell, pageOrgId);
 			return (row && byRow.get(row.id)) ?? null;
 		}
 	};
 }
-export { pageBundles as n, pageBundleRefs as t };
+export { rowsInScope as i, pageBundles as n, rowForCell as r, pageBundleRefs as t };

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/{query-D6xQbTFK.js → query-CNaB25jE.js}

@@ -299,6 +299,17 @@ var RENDER_FUNCTIONS = {
 		"edge",
 		"graph"
 	],
+	pages_awaiting_release: [
+		"graph",
+		"graph_node",
+		"node",
+		"process",
+		"system",
+		"edge",
+		"system_version",
+		"system_node_version",
+		"system_node_state"
+	],
 	versions_for: ["system_version"],
 	version_diff: [
 		"system_version",
@@ -316,6 +327,96 @@ var RENDER_FUNCTIONS = {
 		"system_node_state",
 		"graph_node",
 		"edge"
+	],
+	page_read: [
+		"edge",
+		"graph",
+		"graph_node",
+		"node",
+		"process",
+		"system_node_state",
+		"system_node_version",
+		"system_version"
+	],
+	page_by_type: [
+		"edge",
+		"graph",
+		"graph_node",
+		"node",
+		"process",
+		"system_node_state",
+		"system_node_version",
+		"system_version"
+	],
+	page_list: [
+		"edge",
+		"graph",
+		"graph_node",
+		"node",
+		"process",
+		"system_node_state",
+		"system_node_version",
+		"system_version"
+	],
+	form_status_read: [
+		"client_project",
+		"edge",
+		"graph",
+		"graph_edge",
+		"graph_node",
+		"node",
+		"process",
+		"system",
+		"system_node_state",
+		"system_version"
+	],
+	page_read_many: [
+		"edge",
+		"graph",
+		"graph_node",
+		"node",
+		"process",
+		"system_node_state",
+		"system_node_version",
+		"system_version"
+	],
+	page_list_recent: [
+		"edge",
+		"graph",
+		"graph_node",
+		"node",
+		"process",
+		"system_node_state",
+		"system_node_version",
+		"system_version"
+	],
+	page_anchor_of_scope: [
+		"edge",
+		"graph",
+		"graph_node",
+		"node",
+		"process",
+		"system_node_state",
+		"system_node_version",
+		"system_version"
+	],
+	page_summaries: [
+		"edge",
+		"graph",
+		"graph_node",
+		"node",
+		"process",
+		"system_node_state",
+		"system_node_version",
+		"system_version"
+	],
+	edit_proposal_rows: ["system_node_state"],
+	graph_list_items: [
+		"edge",
+		"edge_type",
+		"graph_edge",
+		"graph_node",
+		"node"
 	]
 };
 var RENDER_FUNCTIONS_AHEAD = { form_answers: "SCH M3b" };

package/dist/chunks/{structure-CKBtQHJq.js → structure-B3ikc0oD.js}

@@ -1,4 +1,4 @@
-import { T as settled, w as resolveReferences, x as isEach } from "./query-D6xQbTFK.js";
+import { T as settled, w as resolveReferences, x as isEach } from "./query-CNaB25jE.js";
 import { ACTION_FIELDS, ACTION_KINDS, SECTION_KINDS as SECTION_KINDS$1, isGraphAction } from "@peripheries/runtime";
 var actionBindingKey = (registry, entityKey) => entityKey ? `${registry}#${entityKey}` : registry;
 function normalizeActionDeclaration(decl) {
@@ -147,6 +147,31 @@ function declaredActions(cell, ctx, runAction) {
 	}
 	return Object.keys(out).length ? out : void 0;
 }
+var HOST_READ_KEY = "@host";
+var NAME = /^[a-z][a-z0-9_]{0,63}$/;
+var isHostRead = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && "@host" in value;
+function hostReadProblem(value) {
+	const keys = Object.keys(value);
+	if (keys.length !== 1) return `a host read takes only "@host", not ${keys.filter((k) => k !== HOST_READ_KEY).map((k) => `"${k}"`).join(", ")}`;
+	const name = value[HOST_READ_KEY];
+	if (typeof name !== "string" || !NAME.test(name)) return "\"@host\" must be a name of lowercase letters, digits and underscores, starting with a letter";
+	return null;
+}
+function bindHostReads(props, reads, onUnknown) {
+	let out = null;
+	for (const [prop, value] of Object.entries(props)) {
+		if (!isHostRead(value)) continue;
+		out ??= { ...props };
+		const problem = hostReadProblem(value);
+		const name = value[HOST_READ_KEY];
+		if (!problem && reads && Object.hasOwn(reads, name) && typeof reads[name] === "function") out[prop] = reads[name];
+		else {
+			delete out[prop];
+			onUnknown?.(prop, problem ?? `the host lists no read named "${name}"`);
+		}
+	}
+	return out ?? props;
+}
 var PAGE_DOCUMENT = "__page__";
 function normalizeStructure(nodes) {
 	if (!Array.isArray(nodes)) return [];
@@ -380,4 +405,4 @@ function tableOfContents(structure, cells = []) {
 	});
 	return walk(normalizeStructure(structure), 1, PAGE_DOCUMENT);
 }
-export { resolveAction as C, projectCellActions as S, actionBindingKey as _, deriveSectionReferences as a, declaredActions as b, nodePrintStyle as c, referencesFor as d, sectionAnchor as f, usesStructureLayout as g, tableOfContents as h, deriveSectionNumbering as i, normalizeStructure as l, structureIssues as m, SECTION_KINDS$1 as n, isSectionNode as o, sortByOrder as p, deriveElementReferences as r, mergeSectionReferences as s, PAGE_DOCUMENT as t, numberingFor as u, actionProblems as v, normalizeActionDeclaration as x, actionReferences as y };
+export { actionReferences as C, resolveAction as D, projectCellActions as E, actionProblems as S, normalizeActionDeclaration as T, HOST_READ_KEY as _, deriveSectionReferences as a, isHostRead as b, nodePrintStyle as c, referencesFor as d, sectionAnchor as f, usesStructureLayout as g, tableOfContents as h, deriveSectionNumbering as i, normalizeStructure as l, structureIssues as m, SECTION_KINDS$1 as n, isSectionNode as o, sortByOrder as p, deriveElementReferences as r, mergeSectionReferences as s, PAGE_DOCUMENT as t, numberingFor as u, bindHostReads as v, declaredActions as w, actionBindingKey as x, hostReadProblem as y };

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

@@ -1,5 +1,5 @@
-import { _ as EACH, h as variableLabels, m as validateDescriptor, o as descriptorShape, p as shapeAt, v as EACH_DEFAULT_AS, x as isEach } from "./query-D6xQbTFK.js";
-import { g as usesStructureLayout, m as structureIssues, v as actionProblems } from "./structure-CKBtQHJq.js";
+import { _ as EACH, h as variableLabels, m as validateDescriptor, o as descriptorShape, p as shapeAt, v as EACH_DEFAULT_AS, x as isEach } from "./query-CNaB25jE.js";
+import { S as actionProblems, b as isHostRead, g as usesStructureLayout, m as structureIssues, y as hostReadProblem } from "./structure-B3ikc0oD.js";
 import { DEFAULT_STATE, STATE_NAMES, WALK_DEFAULTS, isDescriptorBinding, isGraphAction, isStateName } from "@peripheries/runtime";
 var TIER_OF_GRAPH_TYPE = {
 	"meta-process": "meta",
@@ -270,6 +270,7 @@ function selectionIssues(cell, queries, at) {
 	visit(cell.conditions, `${at}.conditions`, top);
 	return out;
 }
+var componentsFor = (catalog, cell) => catalog.forCell?.(cell) ?? catalog.components;
 var words = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[\s_-]+/).filter(Boolean);
 function editDistance(a, b) {
 	let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
@@ -491,6 +492,25 @@ function checkProjections(value, path, push, cellId) {
 	});
 	checkProjections(value.map, `${path}.map`, push, cellId);
 }
+function checkHostReads(props, path, push, cellId) {
+	if (!props || typeof props !== "object" || Array.isArray(props)) return;
+	for (const [key, value] of Object.entries(props)) if (isHostRead(value)) {
+		const problem = hostReadProblem(value);
+		if (problem) push({
+			severity: "error",
+			code: "HOST_READ_INVALID",
+			cellId,
+			path: `${path}.${key}`,
+			message: problem
+		});
+	} else if (value && typeof value === "object" && JSON.stringify(value).includes(`"@host"`)) push({
+		severity: "error",
+		code: "HOST_READ_INVALID",
+		cellId,
+		path: `${path}.${key}`,
+		message: "a host read is a prop of its own: it is not read inside another value"
+	});
+}
 function checkActions(cell, path, push) {
 	if (cell.actions === void 0) return;
 	if (!cell.actions || typeof cell.actions !== "object" || Array.isArray(cell.actions)) {
@@ -617,9 +637,10 @@ function validateCell(cell, catalog, path = "cell", ids, options = {}) {
 		message: "an inline cell needs a component"
 	});
 	if (cell.component && catalog && !cell.component.startsWith("@core/")) {
-		const entry = catalog.components[cell.component];
+		const components = componentsFor(catalog, cell);
+		const entry = components[cell.component];
 		if (!entry) {
-			const suggestions = nearestNames(cell.component, Object.keys(catalog.components));
+			const suggestions = nearestNames(cell.component, Object.keys(components));
 			push({
 				severity: nodeManaged ? "warning" : "error",
 				code: "CELL_UNKNOWN_COMPONENT",
@@ -641,6 +662,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,8 +705,17 @@ 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);
+	checkHostReads(cell.props, `${path}.props`, push, cellId);
 	checkProjections(cell.props, `${path}.props`, push, cellId);
 	checkProjections(cell.conditions, `${path}.conditions`, push, cellId);
 	checkTraversal(cell.traversal, `${path}.traversal`, push, cellId);
@@ -775,7 +815,7 @@ function slotIssues(cells, catalog) {
 	cells.forEach((parent) => {
 		if (!parent?.component) return;
 		const kids = parent.children ?? [];
-		const entry = catalog.components[parent.component];
+		const entry = componentsFor(catalog, parent)[parent.component];
 		if (!entry) return;
 		const slots = declaredSlots(entry.props_schema);
 		const filled = new Map();
@@ -826,4 +866,4 @@ function slotIssues(cells, catalog) {
 	});
 	return out;
 }
-export { stateValue as _, nearestNames as a, walkKey as b, selectionIssues as c, needsWalk as d, readField as f, stateNames as g, resolveWalkStart as h, eachFormProblems as i, RESERVED_LABELS as l, referencedLabels as m, STORE_SCOPES as n, validateCell as o, readWalk as p, WALK_DIRECTIONS as r, validatePage as s, RESPONSIVE_BUCKETS as t, mergeStates as u, systemsFromGraphs as v, walkRequest as x, systemsFromProcess as y };
+export { walkRequest as S, stateNames as _, eachFormProblems as a, systemsFromProcess as b, validatePage as c, mergeStates as d, needsWalk as f, resolveWalkStart as g, referencedLabels as h, componentsFor as i, selectionIssues as l, readWalk as m, STORE_SCOPES as n, nearestNames as o, readField as p, WALK_DIRECTIONS as r, validateCell as s, RESPONSIVE_BUCKETS as t, RESERVED_LABELS as u, stateValue as v, walkKey as x, systemsFromGraphs as y };

package/dist/core.js

@@ -1,10 +1,10 @@
-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 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 { 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 { 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-CNaB25jE.js";
+import { S as walkRequest, _ as stateNames, a as eachFormProblems, b as systemsFromProcess, c as validatePage, d as mergeStates, f as needsWalk, g as resolveWalkStart, h as referencedLabels, i as componentsFor, l as selectionIssues, m as readWalk, n as STORE_SCOPES, o as nearestNames, p as readField, r as WALK_DIRECTIONS, s as validateCell, t as RESPONSIVE_BUCKETS, u as RESERVED_LABELS, v as stateValue, x as walkKey, y as systemsFromGraphs } from "./chunks/validate-DRkCpQaY.js";
+import { C as actionReferences, D as resolveAction, E as projectCellActions, S as actionProblems, T as normalizeActionDeclaration, _ as HOST_READ_KEY, a as deriveSectionReferences, b as isHostRead, 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 bindHostReads, w as declaredActions, x as actionBindingKey, y as hostReadProblem } from "./chunks/structure-B3ikc0oD.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";
-import { n as pageBundles, t as pageBundleRefs } from "./chunks/page-bundles-CPj_vx-J.js";
+import { i as rowsInScope, n as pageBundles, r as rowForCell, t as pageBundleRefs } from "./chunks/page-bundles-_wsGO9WU.js";
 import { a as createStackStore, i as saveScope, n as clearScope, r as loadScope } from "./chunks/persistence-hurkUUQ0.js";
 import { ACTION_KINDS, QUERY_DESCRIPTOR_KEY, SECTION_KINDS as SECTION_KINDS$1, STATE_ROLES, STATE_TIERS, WALK_DEFAULTS, isDescriptorBinding, isLiveQueryState, isReadOnlyVersion } from "@peripheries/runtime";
 function resolveDeclarations(queries, systems, diagnostics = [], cellId) {
@@ -801,6 +801,18 @@ 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."
 	},
+	HOST_READ_INVALID: {
+		meaning: "A `{ \"@host\": … }` prop value is malformed.",
+		fix: "Write exactly `{ \"@host\": \"<name>\" }`, a name of lowercase letters, digits and underscores, as a top-level prop."
+	},
+	HOST_READ_UNKNOWN: {
+		meaning: "A `{ \"@host\": \"<name>\" }` prop names a read the host does not list, so the prop is dropped and the component runs without it.",
+		fix: "Use a name the host lists in `hostReads`, or remove the prop."
+	},
+	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 +1066,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 +1144,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, HOST_READ_KEY, 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, bindHostReads, buildDataContext, bundleScope, cellAttributes, cellContext, cellPlacementStyle, cellPropSources, cellResolutionContext, clearScope, collectDeclarations, collectDescriptors, collectScopeIds, collectStatic, componentsFor, createStackStore, declaredActions, deriveElementReferences, deriveSectionNumbering, deriveSectionReferences, descriptorShape, eachFormProblems, editTarget, hasRef, hiddenWhenEmpty, hideWhenEmptyProblem, hostReadProblem, isComponentExport, isEach, isEmptyPropValue, isHostRead, 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, rowForCell, rowsInScope, 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,6 +1,6 @@
-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 { 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 { _ 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-CNaB25jE.js";
+import { a as deriveSectionReferences, 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, v as bindHostReads, w as declaredActions } from "./chunks/structure-B3ikc0oD.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";
 import { Component, Fragment, Suspense, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
@@ -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 = { ...bindHostReads(resolveReferences(cell.props ?? {}, ctx), env.hostReads) };
+	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",
@@ -382,7 +426,13 @@ function CellView({ cell, env, nested = false, injectedProps }) {
 				source
 			}) } : {}
 		};
-		const resolvedProps = resolveReferences(cell.props ?? {}, propsCtx);
+		const resolvedProps = bindHostReads(resolveReferences(cell.props ?? {}, propsCtx), env.hostReads, (prop, why) => env.onDiagnostic?.({
+			severity: "warning",
+			code: "HOST_READ_UNKNOWN",
+			cellId: cell.id,
+			path: `props.${prop}`,
+			message: `${cell.component ?? cell.id}.${prop}: ${why}`
+		}));
 		if (found) env.onPropSources({
 			id: cell.id,
 			source: cell.source
@@ -528,7 +578,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, hostReads, retry, showHiddenCells, showProblemCodes } = environment;
 	useEffect(() => {
 		for (const d of runtime.diagnostics) onDiagnostic(d);
 	}, [runtime.diagnostics, onDiagnostic]);
@@ -556,6 +606,9 @@ function PageRenderer({ runtime, bundles, params, baseProps, context, viewer, en
 			onDiagnostic,
 			frameProps,
 			cellProps,
+			hostReads,
+			showHiddenCells,
+			showProblemCodes,
 			renderEmbed: (cellId) => {
 				const embedded = runtime.embeds?.[cellId];
 				if (!embedded) return jsx(CellNotice, {
@@ -606,7 +659,10 @@ function PageRenderer({ runtime, bundles, params, baseProps, context, viewer, en
 		onDiagnostic,
 		frameProps,
 		cellProps,
+		hostReads,
 		retry,
+		showHiddenCells,
+		showProblemCodes,
 		environment
 	]);
 	const structured = usesStructureLayout(page.layout);
@@ -980,4 +1036,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/runtime.js

@@ -16,6 +16,7 @@ function importMapJson(shared = []) {
 	return JSON.stringify(importMapFor(shared)).replace(/</g, "\\u003c");
 }
 var IMPORT_MAP_JSON = importMapJson();
+var LOAD_GLOBAL = "__STACK_RUNTIME_LOAD__";
 var singleton = null;
 function getStackStore() {
 	return singleton ??= createStackStore();
@@ -52,11 +53,28 @@ function buildRuntime(extra = {}) {
 		...extra
 	};
 }
-function installRuntime(g = globalThis, extra = {}) {
+function installRuntime(g = globalThis, extra = {}, lazy = {}) {
 	const runtime = g[RUNTIME_GLOBAL] ?? buildRuntime(extra);
 	g[RUNTIME_GLOBAL] = runtime;
+	if (typeof g["__STACK_RUNTIME_LOAD__"] !== "function") {
+		const loading = new Map();
+		g[LOAD_GLOBAL] = (specifier) => {
+			const load = lazy[specifier];
+			if (!load || specifier in runtime) return void 0;
+			let pending = loading.get(specifier);
+			if (!pending) {
+				pending = load().then((mod) => void (runtime[specifier] = mod), (error) => {
+					loading.delete(specifier);
+					throw error;
+				});
+				loading.set(specifier, pending);
+			}
+			return pending;
+		};
+	}
 	if (typeof g.require !== "function") g.require = (specifier) => {
 		if (specifier in runtime) return runtime[specifier];
+		if (specifier in lazy) throw new Error(`[runtime] "${specifier}" is lent lazily by the host and is not loaded yet: import it as an ES module, not with require().`);
 		throw new Error(`[runtime] No host module for require("${specifier}"). Add it to PINNED_RUNTIMES or bundle it.`);
 	};
 	if (!g[READY_GLOBAL]) g[READY_GLOBAL] = Promise.resolve();
@@ -75,6 +93,7 @@ function renderShim(specifier, names, hasDefault) {
 		"// Generated by scripts/build-shims.ts. Do not edit.",
 		`// Forwards ${key} to globalThis.${RUNTIME_GLOBAL}[${key}].`,
 		`await globalThis.${READY_GLOBAL};`,
+		`await globalThis.${LOAD_GLOBAL}?.(${key});`,
 		`const R = globalThis.${RUNTIME_GLOBAL}?.[${key}];`,
 		`if (!R) throw new Error('[runtime] ${RUNTIME_GLOBAL}[${key}] is not installed; the host has not booted.');`
 	];

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/testing.js

@@ -1,7 +1,7 @@
-import { l as prepareDocument } from "./chunks/query-D6xQbTFK.js";
+import { l as prepareDocument } from "./chunks/query-CNaB25jE.js";
 import { o as projectModule } from "./chunks/load-b38vUiZM.js";
 import { i as bundleScope } from "./chunks/refs-Csgh6rXq.js";
-import { n as pageBundles, t as pageBundleRefs } from "./chunks/page-bundles-CPj_vx-J.js";
+import { n as pageBundles, t as pageBundleRefs } from "./chunks/page-bundles-_wsGO9WU.js";
 import { r as fromPageSteps } from "./chunks/forms-DxA9WzCt.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 var __defProp = Object.defineProperty;

package/dist/types/core/bundles/page-bundles.d.ts

@@ -2,6 +2,8 @@ import type { PageCell } from '../types.js';
 import type { BundleRow, LoadedBundle } from './load.js';
 import { type LineageRef } from './refs.js';
 export declare function pageBundleRefs(scope: LineageRef[], cells: PageCell[], pageOrgId: string | null): LineageRef[];
+export declare function rowsInScope<R extends Pick<BundleRow, 'id' | 'bundle_name' | 'org_slug' | 'org_id'>>(rows: readonly R[], scope: LineageRef[]): R[];
+export declare function rowForCell<R extends Pick<BundleRow, 'id' | 'bundle_name' | 'org_slug' | 'org_id'>>(rows: readonly R[], cell: PageCell, pageOrgId: string | null): R | null;
 export type PageBundles = {
     scope: LoadedBundle[] | null;
     forCell: (cell: PageCell) => LoadedBundle | null;

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,18 @@ 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 HOST_READ_INVALID: {
+        readonly meaning: "A `{ \"@host\": … }` prop value is malformed.";
+        readonly fix: "Write exactly `{ \"@host\": \"<name>\" }`, a name of lowercase letters, digits and underscores, as a top-level prop.";
+    };
+    readonly HOST_READ_UNKNOWN: {
+        readonly meaning: "A `{ \"@host\": \"<name>\" }` prop names a read the host does not list, so the prop is dropped and the component runs without it.";
+        readonly fix: "Use a name the host lists in `hostReads`, or remove the prop.";
+    };
+    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/host-reads.d.ts

@@ -0,0 +1,6 @@
+export declare const HOST_READ_KEY = "@host";
+export type HostRead = (...args: never[]) => unknown;
+export type HostReads = Readonly<Record<string, HostRead>>;
+export declare const isHostRead: (value: unknown) => value is Record<string, unknown>;
+export declare function hostReadProblem(value: Record<string, unknown>): string | null;
+export declare function bindHostReads(props: Record<string, unknown>, reads: HostReads | undefined, onUnknown?: (prop: string, why: string) => void): Record<string, unknown>;

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';
@@ -6,19 +6,20 @@ export { loadPageData, resolveDataSystem, resolveSystems, type CellData, type Ce
 export { descriptorShape, orderByVariable, PAGING_VARIABLES, pageVariables, prepareDocument, queryKey, RENDER_FUNCTIONS, RENDER_FUNCTIONS_AHEAD, resolveDescriptorVariables, selectionShape, shapeAt, UnsafeDocumentError, validateDescriptor, VARIABLE_NAMESPACES, variableLabels, variableReferences, type PreparedDocument, type ResolvedVariables, type SelectionShape, } from './query.js';
 export { selectionIssues } from './selected.js';
 export { cellPropSources, editTarget, patchAt, STRUCTURE_FIELDS, TOOL_OWNED_KEYS, type EditCell, type EditRefusal, type EditTarget, type OnSource, type PropSource, type PropSourceEntry } from './sources.js';
+export { bindHostReads, HOST_READ_KEY, hostReadProblem, isHostRead, type HostRead, type HostReads } from './host-reads.js';
 export { cellContext, cellResolutionContext, EACH, pageContext, EACH_DEFAULT_AS, isEach, passesConditions, resolveReferences, settled, type CellScope, type Each, type ResolutionContext } from './references.js';
-export { eachFormProblems, nearestNames, RESPONSIVE_BUCKETS, STORE_SCOPES, validateCell, validatePage, WALK_DIRECTIONS, type Catalog, type ValidateOptions } from './validate.js';
+export { componentsFor, eachFormProblems, nearestNames, RESPONSIVE_BUCKETS, STORE_SCOPES, validateCell, validatePage, WALK_DIRECTIONS, type Catalog, type ValidateOptions } from './validate.js';
 export { DIAGNOSTICS, type DiagnosticCode, type DiagnosticEntry } from './diagnostics.js';
 export { LAYOUT_TYPES, PAGE_RULES } from './rules.js';
 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';
-export { pageBundleRefs, pageBundles, type PageBundles } from './bundles/page-bundles.js';
+export { pageBundleRefs, pageBundles, rowForCell, rowsInScope, type PageBundles } from './bundles/page-bundles.js';
 export { bundleScope, CORE_SPECIFIER, MAIN, normalizeRef, PUBLIC, refKey, type BundleRef, type BundleScopeInput, type LineageRef, type SharedLineage } from './bundles/refs.js';
 export { resolveComponent, type CoreRegistry, type ResolvedComponent } from './bundles/resolve.js';
 export { createStackStore, type StackStoreApi } from './store/create-store.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/core/validate.d.ts

@@ -1,15 +1,18 @@
 import { type Diagnostic } from './graph.js';
 import { type Each } from './references.js';
 import type { PageCell, ProjectPage } from './types.js';
+type CatalogEntries = Record<string, {
+    props_schema?: {
+        required?: readonly string[];
+        properties?: Record<string, unknown>;
+        additionalProperties?: unknown;
+    } | null;
+} | undefined>;
 export type Catalog = {
-    components: Record<string, {
-        props_schema?: {
-            required?: readonly string[];
-            properties?: Record<string, unknown>;
-            additionalProperties?: unknown;
-        } | null;
-    } | undefined>;
+    components: CatalogEntries;
+    forCell?: (cell: PageCell) => CatalogEntries | undefined;
 };
+export declare const componentsFor: (catalog: Catalog, cell: PageCell) => CatalogEntries;
 export declare function nearestNames(name: string, names: Iterable<string>, limit?: number): string[];
 export declare const RESPONSIVE_BUCKETS: readonly ["narrow", "compact", "wide"];
 export declare const STORE_SCOPES: readonly ["page", "project"];
@@ -30,3 +33,4 @@ export type SlotDeclaration = {
 export declare function declaredSlots(schema: {
     properties?: Record<string, unknown>;
 } | null | undefined): Map<string, SlotDeclaration>;
+export {};

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

@@ -4,6 +4,7 @@ import type { LoadedBundle } from '../core/bundles/load.js';
 import type { Diagnostic } from '../core/graph.js';
 import { type CoreRegistry } from '../core/bundles/resolve.js';
 import { type RunAction } from '../core/actions.js';
+import { type HostReads } from '../core/host-reads.js';
 import type { CellData } from '../core/load-page.js';
 import { type ResolutionContext } from '../core/references.js';
 import type { StackStoreApi } from '../core/store/create-store.js';
@@ -35,9 +36,12 @@ export type CellEnvironment = {
     onUnresolvedReference?: (cellId: string, ref: string) => void;
     onPropSources?: (cell: EditCell, sources: PropSourceEntry[]) => void;
     renderEmbed?: (cellId: string) => ReactNode;
+    hostReads?: HostReads;
     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

@@ -2,6 +2,7 @@ import type { CellAction, ComponentContract } from '@peripheries/runtime';
 import type { RunAction } from '../core/actions.js';
 import type { PageBundles } from '../core/bundles/page-bundles.js';
 import type { CoreRegistry } from '../core/bundles/resolve.js';
+import type { HostReads } from '../core/host-reads.js';
 import type { Diagnostic } from '../core/graph.js';
 import type { PageRuntime } from '../core/load-page.js';
 import type { EditCell, PropSourceEntry } from '../core/sources.js';
@@ -17,12 +18,15 @@ export type RendererEnvironment = {
     actionsFor?: (cell: PageCell) => Record<string, CellAction> | undefined;
     runAction?: RunAction;
     loadPage?: LoadPage;
+    hostReads?: HostReads;
     onCellError?: (cellId: string, error: Error) => void;
     onUnresolvedReference?: (cellId: string, ref: string) => void;
     onPropSources?: (cell: EditCell, sources: PropSourceEntry[]) => void;
     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/dist/types/runtime/install.d.ts

@@ -1,11 +1,13 @@
 import { READY_GLOBAL, RESOLVE_GLOBAL, RUNTIME_GLOBAL, type RuntimeSpecifier } from '@peripheries/runtime';
+import { LOAD_GLOBAL } from './load-global.js';
 export type StackRuntime = Record<Exclude<RuntimeSpecifier, '@peripheries/ui'>, unknown> & Record<string, unknown>;
 type RuntimeGlobals = {
     [RUNTIME_GLOBAL]?: StackRuntime;
     [READY_GLOBAL]?: Promise<void>;
     [RESOLVE_GLOBAL]?: () => void;
+    [LOAD_GLOBAL]?: (specifier: string) => Promise<void> | undefined;
     require?: (specifier: string) => unknown;
 };
 export declare function buildRuntime(extra?: Record<string, unknown>): StackRuntime;
-export declare function installRuntime(g?: RuntimeGlobals, extra?: Record<string, unknown>): StackRuntime;
+export declare function installRuntime(g?: RuntimeGlobals, extra?: Record<string, unknown>, lazy?: Record<string, () => Promise<unknown>>): StackRuntime;
 export { runtimeReady } from '../core/bundles/load.js';

package/dist/types/runtime/load-global.d.ts

@@ -0,0 +1 @@
+export declare const LOAD_GLOBAL = "__STACK_RUNTIME_LOAD__";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peripheries/renderer",
-  "version": "0.24.0",
+  "version": "0.26.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": [
@@ -47,7 +47,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@peripheries/runtime": "0.23.1",
+    "@peripheries/runtime": "0.25.0",
     "ajv": "8.20.0",
     "graphql": "17.0.2"
   },