@object-ui/react 17.5.0 → 17.6.0

package/dist/spec-bridge/bridges/list-view.js

@@ -5,15 +5,48 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * A spec `ListColumn` in, the same column out — in the spelling the spec
+ * declares (objectui#5068).
+ *
+ * This used to down-translate every column to the data-table adapter's
+ * `{ accessorKey, header }` before handing it to an `object-grid` node, and
+ * `ObjectGrid` translated it straight back through a tolerance branch that
+ * sniffed `columns[0]`. A round trip whose input was ALREADY canonical: the
+ * bridge's own parameter is `@objectstack/spec/ui`'s `ListColumn`, where
+ * `field` is required and `accessorKey` / `header` are refused by name
+ * (`ListColumnSchema` is a strict object). So the producer emitted a spelling
+ * the contract rejects, and the renderer grew a second de-facto contract to
+ * read it back — exactly the shape AGENTS.md #0.1 forbids, and the disposition
+ * objectui#3951 already settled: unify at the producer, no consumer-side alias.
+ *
+ * `accessorKey` is not retired as a concept — it is the TanStack adapter key
+ * `@object-ui/core` deliberately keeps OUT of the metadata identity fold
+ * (`column-identity.ts`'s `TABLE_ADAPTER_COLUMN_KEY`). `ObjectGrid` still
+ * applies it on the way OUT, at the one boundary that owns it. Metadata
+ * vocabulary comes in; adapter vocabulary goes out; one translation, one place.
+ *
+ * Nothing is invented on the way through, which is the second half of the fix.
+ * `header: col.label ?? col.field` used to turn "no label declared" into "the
+ * machine name was declared as the label", and that synthesized value then
+ * pre-empted `ObjectGrid`'s own header chain — `col.label` → the OBJECT
+ * FIELD's label → the prettified name — whose whole purpose is a column
+ * authored as a bare `{ field }`, and whose middle step exists so a localized
+ * field label wins over the name-derived English one on a non-English app. A
+ * bridged view therefore rendered raw machine names where a directly authored
+ * `object-grid` rendered the field's real, localizable label. It now forwards
+ * the declaration and lets the renderer resolve what was left unsaid.
+ */
 function mapColumn(col) {
-    // Spec-legacy shorthand: a bare field name stands for a default column.
+    // Spec shorthand: a bare field name stands for a default column.
     if (typeof col === 'string') {
-        return { accessorKey: col, header: col };
+        return { field: col };
     }
     const mapped = {
-        accessorKey: col.field,
-        header: col.label ?? col.field,
+        field: col.field,
     };
+    if (col.label != null)
+        mapped.label = col.label;
     if (col.width != null)
         mapped.width = col.width;
     if (col.align)
@@ -178,10 +211,6 @@ export const bridgeListView = (spec, _context) => {
         node.filterableFields = spec.filterableFields;
     if (spec.resizable != null)
         node.resizable = spec.resizable;
-    if (spec.striped != null)
-        node.striped = spec.striped;
-    if (spec.bordered != null)
-        node.bordered = spec.bordered;
     if (spec.navigation)
         node.navigation = spec.navigation;
     if (spec.kanban)
@@ -201,8 +230,6 @@ export const bridgeListView = (spec, _context) => {
         node.bulkActions = spec.bulkActions;
     if (spec.bulkActionDefs)
         node.bulkActionDefs = spec.bulkActionDefs;
-    if (spec.virtualScroll != null)
-        node.virtualScroll = spec.virtualScroll;
     if (spec.conditionalFormatting)
         node.conditionalFormatting = spec.conditionalFormatting;
     if (spec.inlineEdit != null)

package/dist/spec-bridge/index.d.ts

@@ -5,7 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { SpecBridge } from './SpecBridge';
-export type { BridgeContext, BridgeFn, ObjectDefLite } from './types';
-export { bridgeListView } from './bridges/list-view';
-export { bridgeFormView } from './bridges/form-view';
+export { SpecBridge } from './SpecBridge.js';
+export type { BridgeContext, BridgeFn, ObjectDefLite } from './types.js';
+export { bridgeListView } from './bridges/list-view.js';
+export { bridgeFormView } from './bridges/form-view.js';

package/dist/spec-bridge/index.js

@@ -5,6 +5,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { SpecBridge } from './SpecBridge';
-export { bridgeListView } from './bridges/list-view';
-export { bridgeFormView } from './bridges/form-view';
+export { SpecBridge } from './SpecBridge.js';
+export { bridgeListView } from './bridges/list-view.js';
+export { bridgeFormView } from './bridges/form-view.js';

package/dist/utils/error-message.d.ts

@@ -12,6 +12,40 @@
  * usable can be extracted, so callers fall back to a generic localized string.
  */
 export declare function extractWriteErrorMessage(err: unknown): string | null;
+/**
+ * The refusal text the PRODUCER explicitly marked as addressed to the end user,
+ * or `null` when the refusal carries no marking.
+ *
+ * `userMessage` is the opt-in channel added by objectstack#9934 (maintainer
+ * ruling 2026-08-19 on objectui#5210), declared on `ApiErrorSchema` /
+ * `EnhancedApiErrorSchema` in the pinned `@objectstack/spec`.
+ * Three properties of the contract decide this reader's whole shape:
+ *
+ *   - **Presence IS the marking.** The mark and the marked text are ONE value —
+ *     a field carrying the text, not a boolean beside `message` — so no boundary
+ *     that rewraps or substitutes `message` can promote platform prose into the
+ *     marked channel. Platform and driver code never set it.
+ *   - **Status-agnostic.** Not a 403 special case; any refusal status may carry
+ *     it. Callers must not gate this read on a status.
+ *   - **Verbatim.** The author wrote it for their user, already localized. It is
+ *     returned untouched — none of {@link extractWriteErrorMessage}'s prefix
+ *     stripping applies, because there is no machine prefix to strip.
+ *
+ * Read from the two places the adapter boundary parks the envelope, both under
+ * the SAME declared key: the error itself (`@objectstack/client` lifts a marked
+ * body onto `err.userMessage`, from either wire dialect) and `details`, which
+ * the client falls back to the whole response body — the identical pair
+ * {@link isPermissionError} reads `code` from. Deliberately NOT read: the raw
+ * JSON tail `ApiDataSource` bakes into its message string. Scraping a marking
+ * out of a transport's prose is the consumer-side guessing objectstack#3821
+ * exists to prevent; a transport that flattens the envelope should carry the
+ * field instead.
+ *
+ * Everything unmarked answers `null`, so callers keep their generic localized
+ * substitution and objectstack#3821's protection holds BY CONSTRUCTION: this
+ * function can never return text the producer did not opt in.
+ */
+export declare function declaredUserMessage(err: unknown): string | null;
 /** One field the server rejected, normalised for `form.setError`. */
 export interface WriteFieldError {
     /** Field name, matching the form control's `name`. */
@@ -50,3 +84,28 @@ export declare function extractFieldErrors(err: unknown): WriteFieldError[] | nu
  * the raw server text.
  */
 export declare function isPermissionError(err: unknown): boolean;
+/** What {@link classifyLoadError} answers. */
+export type LoadErrorKind = 'api-disabled' | 'forbidden' | 'unauthorized' | 'rejected' | 'network';
+/**
+ * Classify a failed data FETCH (as opposed to a failed write, above) by HTTP
+ * status / error code, so an error panel can say what actually happened. A
+ * 403 rendered as "check your connection" is indistinguishable from a real
+ * outage — users were told to debug their network when the server had
+ * (correctly) denied them access.
+ *
+ * Originally `ListView`'s module-local `classifyLoadError`
+ * (`packages/plugin-list/src/ListView.tsx`); lifted here (objectui#4693) so
+ * `RecordAttachmentsPanel` can reuse the same "is this retry-invariant"
+ * verdict for the `sys_attachment` list read instead of re-deriving it. Both
+ * `@object-ui/plugin-list` and `@object-ui/app-shell` already depend on this
+ * package, so the lift adds no new dependency edge to either.
+ *
+ * Purely a classifier — it returns a KIND, never rendered text. Each caller
+ * owns its own copy for what a kind means on its surface (`ListView` shows a
+ * title + message per kind and a Retry for every kind but `api-disabled`;
+ * `RecordAttachmentsPanel` only distinguishes `api-disabled` from everything
+ * else, folding `forbidden`/`unauthorized`/`rejected`/`network` into its own
+ * coarser `denied`/`unavailable` split via {@link isPermissionError}) — so
+ * lifting this function does not couple the two surfaces' i18n or copy.
+ */
+export declare function classifyLoadError(err: unknown): LoadErrorKind;

package/dist/utils/error-message.js

@@ -6,7 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Helpers for turning a failed data-source write into user-facing feedback.
+ * Helpers for turning a failed data-source read or write into user-facing
+ * feedback.
  *
  * Different DataSource adapters throw differently shaped errors:
  *   - the ObjectStack adapter (`@object-ui/data-objectstack`) decorates the
@@ -18,6 +19,7 @@
  * These helpers normalise across both so a caller's `catch` can surface the
  * real reason (e.g. a row-level-security denial) instead of swallowing it.
  */
+import { isApiAccessDeniedError } from '@object-ui/data-objectstack';
 function firstString(...vals) {
     for (const v of vals) {
         if (typeof v === 'string' && v.trim())
@@ -68,6 +70,54 @@ export function extractWriteErrorMessage(err) {
         .trim();
     return clean || null;
 }
+/**
+ * The refusal text the PRODUCER explicitly marked as addressed to the end user,
+ * or `null` when the refusal carries no marking.
+ *
+ * `userMessage` is the opt-in channel added by objectstack#9934 (maintainer
+ * ruling 2026-08-19 on objectui#5210), declared on `ApiErrorSchema` /
+ * `EnhancedApiErrorSchema` in the pinned `@objectstack/spec`.
+ * Three properties of the contract decide this reader's whole shape:
+ *
+ *   - **Presence IS the marking.** The mark and the marked text are ONE value —
+ *     a field carrying the text, not a boolean beside `message` — so no boundary
+ *     that rewraps or substitutes `message` can promote platform prose into the
+ *     marked channel. Platform and driver code never set it.
+ *   - **Status-agnostic.** Not a 403 special case; any refusal status may carry
+ *     it. Callers must not gate this read on a status.
+ *   - **Verbatim.** The author wrote it for their user, already localized. It is
+ *     returned untouched — none of {@link extractWriteErrorMessage}'s prefix
+ *     stripping applies, because there is no machine prefix to strip.
+ *
+ * Read from the two places the adapter boundary parks the envelope, both under
+ * the SAME declared key: the error itself (`@objectstack/client` lifts a marked
+ * body onto `err.userMessage`, from either wire dialect) and `details`, which
+ * the client falls back to the whole response body — the identical pair
+ * {@link isPermissionError} reads `code` from. Deliberately NOT read: the raw
+ * JSON tail `ApiDataSource` bakes into its message string. Scraping a marking
+ * out of a transport's prose is the consumer-side guessing objectstack#3821
+ * exists to prevent; a transport that flattens the envelope should carry the
+ * field instead.
+ *
+ * Everything unmarked answers `null`, so callers keep their generic localized
+ * substitution and objectstack#3821's protection holds BY CONSTRUCTION: this
+ * function can never return text the producer did not opt in.
+ */
+export function declaredUserMessage(err) {
+    if (!err || typeof err !== 'object')
+        return null;
+    const e = err;
+    // Non-empty after trimming, returned untrimmed — the same predicate
+    // `@objectstack/client` applies when it lifts the field off the wire.
+    if (typeof e.userMessage === 'string' && e.userMessage.trim())
+        return e.userMessage;
+    const details = e.details;
+    if (details && typeof details === 'object'
+        && typeof details.userMessage === 'string' && details.userMessage.trim()) {
+        return details.userMessage;
+    }
+    return null;
+}
 /**
  * Per-field errors from a rejected write, or `null` when the failure was not
  * field-scoped.
@@ -136,3 +186,68 @@ export function isPermissionError(err) {
     const text = `${typeof e.message === 'string' ? e.message : ''} ${e.details?.error ?? e.error ?? ''}`;
     return /row-level security|access denied|permission denied|not permitted/i.test(text);
 }
+/** 400-class error codes the data API returns for a request it will never accept. */
+const REJECTED_REQUEST_CODES = new Set([
+    'INVALID_FILTER',
+    'UNSUPPORTED_QUERY_PARAM',
+    'INVALID_QUERY',
+]);
+/**
+ * Classify a failed data FETCH (as opposed to a failed write, above) by HTTP
+ * status / error code, so an error panel can say what actually happened. A
+ * 403 rendered as "check your connection" is indistinguishable from a real
+ * outage — users were told to debug their network when the server had
+ * (correctly) denied them access.
+ *
+ * Originally `ListView`'s module-local `classifyLoadError`
+ * (`packages/plugin-list/src/ListView.tsx`); lifted here (objectui#4693) so
+ * `RecordAttachmentsPanel` can reuse the same "is this retry-invariant"
+ * verdict for the `sys_attachment` list read instead of re-deriving it. Both
+ * `@object-ui/plugin-list` and `@object-ui/app-shell` already depend on this
+ * package, so the lift adds no new dependency edge to either.
+ *
+ * Purely a classifier — it returns a KIND, never rendered text. Each caller
+ * owns its own copy for what a kind means on its surface (`ListView` shows a
+ * title + message per kind and a Retry for every kind but `api-disabled`;
+ * `RecordAttachmentsPanel` only distinguishes `api-disabled` from everything
+ * else, folding `forbidden`/`unauthorized`/`rejected`/`network` into its own
+ * coarser `denied`/`unavailable` split via {@link isPermissionError}) — so
+ * lifting this function does not couple the two surfaces' i18n or copy.
+ */
+export function classifyLoadError(err) {
+    const e = err;
+    // The ObjectStack client decorates errors with `httpStatus`; raw fetch
+    // wrappers surface `status` / `statusCode`; some adapters only embed the
+    // status in the message ("HTTP 403 Forbidden — …").
+    let status = [e?.httpStatus, e?.status, e?.statusCode]
+        .find((s) => typeof s === 'number');
+    if (status === undefined) {
+        const m = /HTTP (\d{3})\b/.exec(String(e?.message ?? ''));
+        if (m)
+            status = Number(m[1]);
+    }
+    const code = typeof e?.code === 'string' ? e.code.toUpperCase() : '';
+    // The object's `enable` block withholds this operation — checked FIRST, on
+    // the CODE alone (delegated to the shared predicate so this file and
+    // `@object-ui/data-objectstack` cannot drift on which codes count). Status
+    // cannot carry this verdict: the denial is a 404, the same status a missing
+    // collection and a missing record answer with, and its 405 sibling is the
+    // same status any other method rejection uses. Unlike every kind below it
+    // this one is not about the request, the session or the network — it is a
+    // permanent property of the object, identical for every persona and every
+    // retry (objectui#4408).
+    if (isApiAccessDeniedError(err))
+        return 'api-disabled';
+    if (status === 403 || code === 'PERMISSION_DENIED' || code === 'FORBIDDEN')
+        return 'forbidden';
+    if (status === 401 || code === 'UNAUTHORIZED' || code === 'UNAUTHENTICATED')
+        return 'unauthorized';
+    // The server understood the request and refused it as malformed. Retrying
+    // sends the identical bad request, so "check your connection and try again"
+    // is the same wrong advice this function exists to stop giving — one status
+    // code over. The server now rejects a `$filter` that is not a filter AST
+    // (objectstack#4121) and an unsupported `$`-parameter, both as 400.
+    if (status === 400 || REJECTED_REQUEST_CODES.has(code))
+        return 'rejected';
+    return 'network';
+}

package/dist/utils/unevaluatedExpression.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Mirrors `ExpressionEvaluator.evaluate`: a `${` with no closing brace, or an
+ * empty `${}`, is not an expression to the evaluator (its interpolation regex
+ * requires at least one character), so it is not one here either. Matching the
+ * PRODUCER's definition is what keeps this from reporting strings the engine
+ * never intended to touch — prose and code samples that merely contain `${`.
+ */
+export declare function findExpressionSources(value: string): string[];
+/** Which authored channel a residual expression was found on. */
+export type UnevaluatedChannel = 'schema' | 'properties' | 'props';
+export interface UnevaluatedExpressionFinding {
+    /** The key holding the raw source. */
+    key: string;
+    /** The authored channel the key was read from. */
+    channel: UnevaluatedChannel;
+    /** The value, verbatim, as it will be handed to the renderer. */
+    value: string;
+    /** The `${…}` fragments inside it. */
+    expressions: string[];
+}
+/**
+ * Collect every unevaluated `${…}` that is about to be handed to a renderer.
+ *
+ * Pure and side-effect free — the reporting half is {@link reportUnevaluatedExpressions}.
+ * Kept separate so the scan can be asserted directly: a diagnostic whose only
+ * test is "a spy was called" goes green the moment someone no-ops it.
+ *
+ * @param spread  The post-strip top-level bag — exactly what `SchemaRenderer`
+ *   spreads as React props, which is also what renderers read as `schema.<key>`.
+ *   Schema METADATA (`visible` / `hidden` / `disabled` / … ) must already be
+ *   removed by the caller: those keys carry raw predicate source BY DESIGN and
+ *   are evaluated as conditions, never placed.
+ * @param properties  The node's `properties` bag, if any. Reported in
+ *   preference to the top-level copy the hoist makes of it, so the finding
+ *   names the key the author actually wrote.
+ * @param props  The node's legacy `props` bag, if any.
+ */
+export declare function collectUnevaluatedExpressions(spread: Record<string, unknown> | undefined | null, properties?: unknown, props?: unknown): UnevaluatedExpressionFinding[];
+/**
+ * Prefix every diagnostic line starts with. Exported so tests can match on it
+ * and so an app can filter it out of its console transport if it must.
+ */
+export declare const UNEVALUATED_EXPRESSION_PREFIX = "[ObjectUI] Unevaluated expression reached the DOM";
+/**
+ * Build the message. Separate from the emit so a test can assert the words a
+ * developer is going to read, not merely that something was logged.
+ */
+export declare function formatUnevaluatedExpressionMessage(type: unknown, id: unknown, findings: UnevaluatedExpressionFinding[]): string;
+/**
+ * Dev-build only. Scans, and on a hit reports once per schema object via
+ * `console.error`.
+ *
+ * `console.error` and not `warn`: this is the loud refusal objectui#4795's
+ * ruling asked for, and it follows the assertion shape objectui#5092 landed in
+ * SchemaForm. (It is also the level that survives happy-dom, which swallows
+ * `console.log`.)
+ *
+ * The caller applies the production gate, so this stays a single dev-only
+ * branch at the call site and the whole module is dead code in a production
+ * build.
+ */
+export declare function reportUnevaluatedExpressions(schema: object | null | undefined, type: unknown, id: unknown, spread: Record<string, unknown> | undefined | null, properties?: unknown, props?: unknown): UnevaluatedExpressionFinding[];

package/dist/utils/unevaluatedExpression.js

@@ -0,0 +1,194 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Dev-build diagnostic: an UNEVALUATED template expression reached the DOM.
+ *
+ * ## The defect this names (objectui#4795, Direction 3)
+ *
+ * A value only reaches the user if it passes two gates: `SchemaRenderer`
+ * must EVALUATE it, and the renderer must READ IT BACK. Those two sets do not
+ * fully overlap, and where they miss, the failure is SILENT — measured on a
+ * real render with `dataSource: { total: 99 }`:
+ *
+ *   { type: 'ui:statistic', value: '${data.n}' }            -> screen shows
+ *                                                              `${data.n}`
+ *   { type: 'ui:card', props: { title: '${data.total}' } }  -> card body EMPTY
+ *                                                              (the evaluated
+ *                                                              `99` landed on a
+ *                                                              DOM attribute)
+ *
+ * The first shape is what this module catches: the memo in `SchemaRenderer`
+ * evaluates `content`, the `properties` / `props` bags and the predicate keys,
+ * and passes every other top-level key through untouched — so the raw source
+ * text is what the renderer receives, and it is placed verbatim. An author
+ * (increasingly, an AI authoring metadata) gets no signal at all: a literal
+ * `${data.n}` on screen reads like a data problem, not a contract violation.
+ *
+ * The second shape this module also catches, in its residue form: when an
+ * expression IS evaluated but the evaluation THROWS, `ExpressionEvaluator`
+ * returns the original source verbatim (`return match` in its interpolation
+ * branch, `defaultValue ?? expression` in its outer catch), so a failed
+ * evaluation is indistinguishable on screen from a key that was never
+ * evaluated at all. Both end as raw `${…}` in front of a user.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It changes NO evaluation behaviour — it reads the schema after the memo has
+ * run and reports. Widening the set of evaluated keys is objectui#4795's
+ * Direction 1, which the maintainer DEFERRED behind a named restart condition
+ * (ruling of 2026-08-17); this diagnostic is Direction 3 and must not
+ * pre-empt it. Merging `props` into the node (Direction 2) is permanently
+ * rejected.
+ *
+ * ## Depth: exactly the evaluator's own radius, and not one level more
+ *
+ * The scan is SHALLOW because evaluation is shallow. `ExpressionEvaluator`
+ * returns every non-string untouched, so a nested `aria: { label: '${…}' }`
+ * under either bag keeps its raw source today — deliberately, and pinned as
+ * such by objectui#4799's parity tests. A deeper scan would therefore report,
+ * as a defect, a shape the repo has explicitly decided not to change yet: the
+ * diagnostic would be louder than the contract it speaks for. Deepening
+ * evaluation is a separate decision, and this scan follows it the day it is
+ * taken, not before.
+ */
+/** What counts as an expression — the evaluator's own definition. */
+const EXPRESSION_PATTERN = /\$\{([^}]+)\}/g;
+/**
+ * Mirrors `ExpressionEvaluator.evaluate`: a `${` with no closing brace, or an
+ * empty `${}`, is not an expression to the evaluator (its interpolation regex
+ * requires at least one character), so it is not one here either. Matching the
+ * PRODUCER's definition is what keeps this from reporting strings the engine
+ * never intended to touch — prose and code samples that merely contain `${`.
+ */
+export function findExpressionSources(value) {
+    const found = [];
+    // `matchAll` needs the /g flag and a fresh lastIndex per call; the literal
+    // above is module-scope, so reset before use rather than allocating a regex
+    // per value (this runs per key, per node, per render, in dev).
+    EXPRESSION_PATTERN.lastIndex = 0;
+    let match = EXPRESSION_PATTERN.exec(value);
+    while (match !== null) {
+        found.push(match[0]);
+        match = EXPRESSION_PATTERN.exec(value);
+    }
+    return found;
+}
+function scanBag(bag, channel, into, skip) {
+    if (!bag || typeof bag !== 'object' || Array.isArray(bag))
+        return;
+    for (const [key, value] of Object.entries(bag)) {
+        if (typeof value !== 'string')
+            continue;
+        if (skip?.(key, value))
+            continue;
+        const expressions = findExpressionSources(value);
+        if (expressions.length > 0) {
+            into.push({ key, channel, value, expressions });
+        }
+    }
+}
+/**
+ * Collect every unevaluated `${…}` that is about to be handed to a renderer.
+ *
+ * Pure and side-effect free — the reporting half is {@link reportUnevaluatedExpressions}.
+ * Kept separate so the scan can be asserted directly: a diagnostic whose only
+ * test is "a spy was called" goes green the moment someone no-ops it.
+ *
+ * @param spread  The post-strip top-level bag — exactly what `SchemaRenderer`
+ *   spreads as React props, which is also what renderers read as `schema.<key>`.
+ *   Schema METADATA (`visible` / `hidden` / `disabled` / … ) must already be
+ *   removed by the caller: those keys carry raw predicate source BY DESIGN and
+ *   are evaluated as conditions, never placed.
+ * @param properties  The node's `properties` bag, if any. Reported in
+ *   preference to the top-level copy the hoist makes of it, so the finding
+ *   names the key the author actually wrote.
+ * @param props  The node's legacy `props` bag, if any.
+ */
+export function collectUnevaluatedExpressions(spread, properties, props) {
+    const findings = [];
+    scanBag(properties, 'properties', findings);
+    // The hoist copies every `properties.*` value onto the node's top level, so
+    // the same residue is visible twice. Report the authored spelling only.
+    const hoisted = properties && typeof properties === 'object' && !Array.isArray(properties)
+        ? properties
+        : undefined;
+    scanBag(spread, 'schema', findings, (key, value) => hoisted?.[key] === value);
+    scanBag(props, 'props', findings);
+    return findings;
+}
+/**
+ * Prefix every diagnostic line starts with. Exported so tests can match on it
+ * and so an app can filter it out of its console transport if it must.
+ */
+export const UNEVALUATED_EXPRESSION_PREFIX = '[ObjectUI] Unevaluated expression reached the DOM';
+/** Where a finding sits, spelled the way an author would search for it. */
+function locate(finding) {
+    switch (finding.channel) {
+        case 'properties':
+            return 'properties.' + finding.key;
+        case 'props':
+            return 'props.' + finding.key;
+        default:
+            return finding.key;
+    }
+}
+/**
+ * Build the message. Separate from the emit so a test can assert the words a
+ * developer is going to read, not merely that something was logged.
+ */
+export function formatUnevaluatedExpressionMessage(type, id, findings) {
+    const node = typeof type === 'string' && type ? '"' + type + '"' : '(untyped node)';
+    const where = typeof id === 'string' && id ? ' (id: "' + id + '")' : '';
+    const lines = findings.map(f => {
+        const site = locate(f);
+        return ('  - ' + site + ': ' + JSON.stringify(f.value) +
+            '  [' + f.expressions.join(', ') + ']');
+    });
+    return (UNEVALUATED_EXPRESSION_PREFIX + ' - node ' + node + where + '\n' +
+        lines.join('\n') + '\n' +
+        'The value above is placed VERBATIM: it is handed to the renderer, and spread\n' +
+        'to the DOM, with its source text intact. Either SchemaRenderer does not\n' +
+        'evaluate this key, or the expression threw and the evaluator returned the\n' +
+        'source unchanged.\n' +
+        'Channels that do evaluate and read back today: `content`, or resolve the\n' +
+        'value in the host before handing the schema to SchemaRenderer.');
+}
+/**
+ * Reported nodes, so a re-render (or the post-mount forceUpdate that picks up
+ * lazy plugin registrations) does not repeat the message. Keyed on the ORIGINAL
+ * schema object, matching `validateSchemaOnce`'s dedup: the evaluated copy is a
+ * fresh object on every memo recompute and would dedup nothing.
+ */
+const _reportedNodes = typeof WeakSet !== 'undefined'
+    ? new WeakSet()
+    : { add() { }, has() { return false; } };
+/**
+ * Dev-build only. Scans, and on a hit reports once per schema object via
+ * `console.error`.
+ *
+ * `console.error` and not `warn`: this is the loud refusal objectui#4795's
+ * ruling asked for, and it follows the assertion shape objectui#5092 landed in
+ * SchemaForm. (It is also the level that survives happy-dom, which swallows
+ * `console.log`.)
+ *
+ * The caller applies the production gate, so this stays a single dev-only
+ * branch at the call site and the whole module is dead code in a production
+ * build.
+ */
+export function reportUnevaluatedExpressions(schema, type, id, spread, properties, props) {
+    const findings = collectUnevaluatedExpressions(spread, properties, props);
+    if (findings.length === 0)
+        return findings;
+    if (schema && typeof schema === 'object') {
+        if (_reportedNodes.has(schema))
+            return findings;
+        _reportedNodes.add(schema);
+    }
+    console.error(formatUnevaluatedExpressionMessage(type, id, findings));
+    return findings;
+}