@object-ui/react 17.5.0 → 17.6.0

package/dist/SchemaRenderer.js

@@ -8,10 +8,13 @@ import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-run
  */
 import React, { forwardRef, useContext, useMemo, useEffect, useReducer, useState, Component } from 'react';
 import { ComponentRegistry, ExpressionEvaluator, isObjectUIError, ERROR_CODES, debugLog, debugTime, debugTimeEnd, DebugCollector, validateSchema, hasDeclaredPredicate, hasResponsiveStyles, scopeClassFor, compileScopedStyles, } from '@object-ui/core';
-import { SchemaRendererContext } from './context/SchemaRendererContext';
-import { usePredicateScope } from './hooks/useExpression';
-import { usePageVariables } from './hooks/usePageVariables';
-import { resolveKeyedI18nLabel } from './utils/i18n';
+import { SchemaRendererContext } from './context/SchemaRendererContext.js';
+import { useRecordContext } from './context/RecordContext.js';
+import { usePredicateScope } from './hooks/useExpression.js';
+import { usePageVariables } from './hooks/usePageVariables.js';
+import { resolveKeyedI18nLabel } from './utils/i18n.js';
+import { reportUnevaluatedExpressions } from './utils/unevaluatedExpression.js';
+import { reportUnresolvableVisibilityPredicate, reportAdapterOnlyDataPredicate, } from './utils/visibilityDiagnostic.js';
 /**
  * Dev-mode schema validation.
  *
@@ -56,7 +59,6 @@ function validateSchemaOnce(schema) {
             entry = { valid: false, messages: msgs };
             if (!_warnedSchemas.has(schema)) {
                 _warnedSchemas.add(schema);
-                // eslint-disable-next-line no-console
                 console.warn('[ObjectUI] Invalid schema detected:\n' + msgs.join('\n'), schema);
             }
         }
@@ -65,7 +67,6 @@ function validateSchemaOnce(schema) {
         // Validator itself failed — surface but don't crash render.
         if (!_warnedSchemas.has(schema)) {
             _warnedSchemas.add(schema);
-            // eslint-disable-next-line no-console
             console.warn('[ObjectUI] Schema validator threw:', err);
         }
     }
@@ -94,6 +95,167 @@ function resolveAriaProps(schema) {
     }
     return aria;
 }
+/**
+ * Keys the `properties` hoist deliberately refuses to copy onto the node — they
+ * identify WHICH renderer to dispatch to, so an inner `properties.type` (e.g. a
+ * tab's visual style `line` | `card` | `pill`) must never shadow the outer
+ * component descriptor. See the hoist in the evaluation memo below.
+ */
+const HOIST_PROTECTED_KEYS = new Set(['type', 'id']);
+/**
+ * The legacy `props` bag, minus every key the canonical `properties` bag also
+ * declares (objectui#5123).
+ *
+ * A node may spell its config bag `properties` (the spec spelling) or `props`
+ * (the annotated legacy alias). A node that writes BOTH used to get a DIFFERENT
+ * answer for the same key depending on which channel read it, and the two
+ * channels' precedence was exactly OPPOSITE:
+ *
+ *   - config bag: `readProps()` in the `element:*` family merges
+ *     `{ ...schema.props, ...schema.properties }` — `properties` wins.
+ *   - React prop: `createElement` below spread `...componentProps` (which
+ *     carries the hoisted `properties.*` values) and then
+ *     `...(evaluatedSchema.props || {})` LAST, which overwrote them —
+ *     `props` won.
+ *
+ * Measured on one render of one node carrying both:
+ * `bagRead(properties.content)="FROM_PROPERTIES"` while
+ * `reactPropRead(content)="FROM_PROPS"`. Which one reached the screen depended
+ * only on whether the renderer happened to be in the `readProps()` family.
+ *
+ * Maintainer ruling 2026-08-18: **`properties` wins on BOTH channels — one
+ * answer per key.** The config-bag order was already correct and is untouched;
+ * this narrowing is the React-prop half. It restores the declared posture
+ * (`props` is an annotated legacy alias) rather than changing it.
+ *
+ * Implemented by REMOVING the overlapping keys from the alias spread rather
+ * than by re-spreading `properties` after it. That matters: `properties.*` is
+ * already on the node via the hoist, so the values are in `componentProps`
+ * having passed the metadata strip. Re-spreading the raw bag would push
+ * stripped schema metadata back out as React props — exactly the regression
+ * that made a spec-documented `dataSource` binding shadow the injected adapter
+ * and break the component (objectstack#5576). Subtracting adds no key to the
+ * outgoing bag; it only decides which of two co-present values a key carries.
+ *
+ * Scope, deliberately narrow — this only moves a reading where BOTH bags
+ * declare the same key:
+ *   - a key only `props` declares is untouched (the alias keeps working);
+ *   - a key only `properties` declares is untouched (it already won);
+ *   - `type`/`id` are skipped, because the hoist never copied a canonical value
+ *     up for them, so dropping the alias would DELETE the prop rather than
+ *     replace it;
+ *   - a degenerate (non-object) `properties` is left alone — the hoist and
+ *     `readProps()` both merely object-spread it, and there is no canonical bag
+ *     to prefer.
+ *
+ * Adjacent but NOT decided here: objectui#4795's pending question ② (whether
+ * the `properties` envelope is an official `ui:*` authoring channel at all).
+ * This is a precedence rule between two co-present spellings and takes no
+ * position on whether either should exist.
+ */
+function propsWithoutCanonicalKeys(propsBag, propertiesBag) {
+    if (!propsBag)
+        return {};
+    // Only a real object bag can win a key. `typeof null === 'object'` is covered
+    // by the truthiness check; arrays are excluded for the same reason the
+    // evaluation guard excludes them — a degenerate `properties` must not have
+    // its shape reinterpreted here.
+    if (!propertiesBag ||
+        typeof propertiesBag !== 'object' ||
+        Array.isArray(propertiesBag)) {
+        return propsBag;
+    }
+    let narrowed = null;
+    for (const key of Object.keys(propertiesBag)) {
+        if (HOIST_PROTECTED_KEYS.has(key))
+            continue;
+        if (!Object.prototype.hasOwnProperty.call(propsBag, key))
+            continue;
+        // Copy lazily: the overwhelmingly common node declares one bag or neither,
+        // and this runs on every render of every node.
+        if (!narrowed)
+            narrowed = { ...propsBag };
+        delete narrowed[key];
+    }
+    return narrowed ?? propsBag;
+}
+/**
+ * The visibility-chain keys, in the EXACT precedence order the `shouldHide`
+ * IIFE in the evaluation memo consults them (objectui#5756).
+ *
+ * That chain is one sequence of `if (…) return …` — an early-return chain,
+ * not independent checks — so only the FIRST key here found "declared" on a
+ * node is ever the one that decides, and every lower-priority key is never
+ * even asked. `SHOW` keys ask "is it `!== undefined`?" (their `true` means
+ * *shown*, so "absent" already means shown and needs no narrower test);
+ * `HIDE` keys ask {@link hasDeclaredPredicate} instead, because their `true`
+ * means *hidden* and the wider `!== undefined` test would vanish a node for
+ * `hidden: ''` (objectui#3955). See {@link winningVisibilityKey}.
+ */
+const VISIBILITY_SHOW_KEYS = ['visibleWhen', 'visible', 'visibleOn', 'visibility'];
+const VISIBILITY_HIDE_KEYS = ['hidden', 'hiddenOn'];
+/**
+ * Which ONE visibility key actually decides a node's fate, mirroring both the
+ * `properties` hoist's precedence (same-named key: `properties.<key>`
+ * overwrites a node-level `<key>`) and `shouldHide`'s early-return chain
+ * (first-declared-wins across {@link VISIBILITY_SHOW_KEYS} then
+ * {@link VISIBILITY_HIDE_KEYS}) — without waiting for either to run.
+ *
+ * ## Why this exists (objectui#5756)
+ *
+ * A `${…}` template written as `properties.visible` is evaluated — and
+ * collapsed to a plain boolean — by the loop that runs BEFORE the hoist, in
+ * the SAME render pass. By the time `shouldHide` runs, the predicate TEXT is
+ * gone; there is nothing left to diagnose. Reaching it means asking "does
+ * THIS properties key actually decide?" at the one point in the render where
+ * the raw text still exists — which means asking the precedence question
+ * EARLY, on values the hoist has not yet merged and `shouldHide` has not yet
+ * consulted.
+ *
+ * ## Why the precedence question, and not just "is it in `properties`?"
+ *
+ * Without it, a `properties.visible` template that a co-declared `visibleWhen`
+ * OUTRANKS (exactly `shouldHide`'s own early-return: `visibleWhen` short-
+ * circuits before `visible` is ever reached) would be reported even though it
+ * decides nothing — a false positive for a leg that never runs. Restricting
+ * the report to the WINNING key mirrors what `shouldHide` already does for
+ * every OTHER key spelling (objectui#5454's leg-3 reporter is only ever
+ * invoked on the leg that is actually consulted, by construction of the same
+ * early-return chain) rather than inventing a different posture for this one.
+ *
+ * ## Why `node.properties` must already be POST-evaluation here
+ *
+ * The caller runs this AFTER the `properties.*` evaluation loop (so
+ * `node.properties.visible` may already be the collapsed boolean, not the raw
+ * template) and BEFORE the hoist (so a plain node-level key, untouched by that
+ * loop, is still exactly what `shouldHide` will see). That ordering is what
+ * makes "declared" answered here agree bit-for-bit with what `shouldHide`
+ * answers later — including the corner a naive PRE-evaluation read would get
+ * wrong: a template that evaluates to a literal `undefined` (e.g.
+ * `${data.missing}` read alone) is `!== undefined` on its RAW text but not on
+ * its EVALUATED value, and `shouldHide` falls through to the next key for
+ * exactly that reason. Reading pre-eval text here would call `visible` the
+ * winner when the real chain does not.
+ *
+ * Read-only: decides nothing about visibility itself, only which key a
+ * DIAGNOSTIC should look at.
+ */
+function winningVisibilityKey(node) {
+    const propertiesBag = node.properties;
+    const hasPropertiesBag = propertiesBag != null && typeof propertiesBag === 'object' && !Array.isArray(propertiesBag);
+    const effective = (key) => hasPropertiesBag && Object.prototype.hasOwnProperty.call(propertiesBag, key)
+        ? propertiesBag[key]
+        : node[key];
+    for (const key of VISIBILITY_SHOW_KEYS) {
+        if (effective(key) !== undefined)
+            return key;
+    }
+    for (const key of VISIBILITY_HIDE_KEYS) {
+        if (hasDeclaredPredicate(effective(key)))
+            return key;
+    }
+    return undefined;
+}
 export class SchemaErrorBoundary extends Component {
     constructor() {
         super(...arguments);
@@ -194,6 +356,31 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
     // ExpressionProvider. Threaded into `visible`/expression evaluation so
     // component predicates can gate on the signed-in user & deployment flags.
     const predicateScope = usePredicateScope();
+    // The row the page is about, from `RecordContextProvider` (objectui#5454).
+    //
+    // `@objectstack/spec` has always DECLARED that a component node's
+    // `visibleWhen` binds it — `page.zod.ts`: *"Binds `record`, `current_user`,
+    // `page.<var>`"* — and until this change the evaluator below bound no
+    // `record` at all, on any block, on any record page. A `record.*` predicate
+    // therefore could not resolve; this surface is fail-soft, so it resolved to
+    // SHOWN. That is not a gate that misfires, it is a gate that never gates:
+    // both polarities of the same predicate returned the same verdict, measured
+    // on `record:alert`, `record:path`, `page:card` and `element:text`.
+    //
+    // Bound as the `record` ROOT ONLY — the exact three roots the describe
+    // promises, and nothing else:
+    //
+    //   * NOT as bare fields. `page:tabs`' item-level predicate spreads the row
+    //     flat as well (`containers.tsx`), but that breadth is undeclared on
+    //     both surfaces, and contract-first (AGENTS.md #0.1) says bind what the
+    //     spec states rather than accrete a second de-facto spelling here.
+    //   * NOT over `data`. `data` on this evaluator is the data-source ADAPTER
+    //     from `SchemaRendererContext`, which is what `${data.total}` in a
+    //     `properties` / `props` / `content` value resolves against — a
+    //     documented, pinned binding. Overwriting it with the row would be a
+    //     silent interpolation change nobody asked for.
+    const recordContext = useRecordContext();
+    const boundRecord = recordContext?.data;
     // Page-local state (PageSchema.variables), provided by PageVariablesProvider.
     // Exposed to predicates/bindings under `page.<var>` so an interactive element
     // (e.g. element:record_picker) writing a variable can drive another
@@ -236,14 +423,196 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
         // resolve in component `visible`/`visibleOn` expressions. `page` exposes
         // page-local state so predicates can gate on `page.<var>` (e.g. a record
         // picker's selection toggling another component's visibility).
+        //
+        // `record` is written AFTER the ambient spread so a page's own row wins
+        // over anything a host put in the scope — the same precedence
+        // `usePredicateRecordContext` states for the `useCondition` tier. And it is
+        // written CONDITIONALLY, for the other half of that same rule: no row binds
+        // NOTHING rather than an empty object. `{ record: undefined }` would SHADOW
+        // a `record` a host had legitimately supplied through the ambient scope
+        // (how `action:group`'s dropdown leaf is driven), turning "this surface has
+        // no row of its own" into "this surface's row is empty" — only the latter
+        // is entitled to shadow.
         const evaluator = new ExpressionEvaluator({
             ...predicateScope,
             current_user: predicateScope?.user,
+            ...(boundRecord && typeof boundRecord === 'object' && !Array.isArray(boundRecord)
+                ? { record: boundRecord }
+                : null),
             data: dataSource,
             page: pageVariables,
         });
         // Shallow copy
         const newSchema = { ...schema };
+        /**
+         * Evaluate ONE visibility predicate, and make an unresolvable one LOUD
+         * (objectui#5454, leg 3 of the 2026-08-21 ruling).
+         *
+         * ## The verdict is byte-for-byte what it was — only the silence moved
+         *
+         * `evaluateCondition` answers an unresolvable predicate with `true`, on
+         * every one of its three internal paths: the CEL envelope fails soft to its
+         * `true` fallback, a bare expression that throws is caught and returns
+         * `true`, and a `${…}` template that throws returns its own SOURCE TEXT,
+         * which is a non-empty string and therefore truthy. Passing
+         * `throwOnError: true` changes none of those verdicts — it only converts
+         * "could not evaluate" from a value into a throw — so this helper returns
+         * `true` from the catch and reproduces the old answer exactly. That is why
+         * it is safe on the two NON-negated legs (`hidden` / `hiddenOn`) as well,
+         * where the same `true` means HIDE rather than SHOW.
+         *
+         * ## Why it needed saying at all
+         *
+         * A fail-soft surface answers "this predicate is broken" and "this
+         * predicate said yes" with the same word. On the negated legs that word is
+         * SHOWN, so a `record.*` gate written before objectui#5454 bound the row
+         * rendered its block unconditionally and looked exactly like a gate the
+         * author had got right. One of the three paths was already loud — the CEL
+         * envelope's `evalFieldPredicate` warns (objectstack#5149) — and the other
+         * two were mute, so whether an author heard about their own typo depended
+         * on which dialect they happened to write it in.
+         *
+         * Deduped per (node type, key, predicate source): a broken predicate is
+         * re-evaluated on every render, and the point is one line, not a wall.
+         *
+         * ## Defined HERE, ahead of the `properties` evaluation loop below
+         *
+         * It used to sit just above `shouldHide`, its only caller. objectui#5756
+         * added a second call site — inside the `properties` loop below, on the
+         * raw (pre-evaluation) text of whichever key that loop is about to collapse
+         * — so the definition moved up to be in scope for both. Nothing about the
+         * function changed; `shouldHide` below still calls it exactly as before,
+         * on the POST-evaluation, POST-hoist schema, for the real verdict.
+         */
+        const evaluateVisibilityPredicate = (raw, key) => {
+            // PRODUCTION IS THE UNTOUCHED CALL. `throwOnError` is how the fault is
+            // detected, and on the CEL branch `evaluateCelCondition` implements it by
+            // evaluating TWICE (once with each fallback — a value that tracks the
+            // fallback both times is a fault). Spec-parsed metadata normalizes
+            // `visibleWhen` into a `{ dialect: 'cel' }` envelope, so that branch is
+            // the common one in production: paying for the probe unconditionally
+            // would double the engine calls for every predicate of every node, to
+            // build a message no production build ever prints.
+            if (!__DEV__)
+                return evaluator.evaluateCondition(raw);
+            try {
+                const verdict = evaluator.evaluateCondition(raw, { throwOnError: true });
+                // objectui#5687 — the NON-throwing half of the same silence, and it is
+                // reachable ONLY here, on the branch where the predicate evaluated
+                // cleanly. A `data.*` read the adapter cannot answer is not a fault the
+                // evaluator can raise: `undefined == 'draft'` is a perfectly good
+                // `false`. Verdict untouched — `verdict` is returned exactly as
+                // computed, which is what keeps the ruling's "no verdict changes" true
+                // by construction rather than by review.
+                reportAdapterOnlyDataPredicate(newSchema.type, newSchema.id, key, raw, dataSource);
+                return verdict;
+            }
+            catch (err) {
+                reportUnresolvableVisibilityPredicate(newSchema.type, newSchema.id, key, raw, err);
+                // The historical fail-soft answer, unchanged — and identical to what
+                // the production branch above returns for the same input, which is what
+                // keeps the two branches one behaviour rather than two. See the
+                // docblock: `true` is the value EVERY path of `evaluateCondition`
+                // already returned for an unevaluable predicate.
+                return true;
+            }
+        };
+        // Evaluate 'properties' — the SPEC spelling of a node's config bag, of
+        // which `props` (evaluated below) is the legacy alias.
+        //
+        // objectui#4799: only `props` used to be evaluated here. Renderers in the
+        // `element:*` namespace read their config out of `schema.properties` FIRST
+        // (`readProps()` merges `{ ...schema.props, ...schema.properties }`), so a
+        // node written the canonical way handed the renderer the RAW `${…}` source
+        // and put it on screen verbatim, while the same node written with the
+        // "legacy alias" evaluated correctly. Measured through a real render with
+        // `dataSource: { total: 99 }`: `props: { content: '${data.total}' }` → `99`,
+        // `properties: { content: '${data.total}' }` → `${data.total}`. That is the
+        // inverse of contract-first (AGENTS.md #0.1) — the tolerant spelling was
+        // fed and the canonical one starved — so the fix belongs HERE, at the one
+        // producer of evaluated schema, not as a second read in each consumer.
+        //
+        // Order matters: this runs BEFORE the hoist block below, because that block
+        // copies every `properties.*` value onto the node's top level (and those
+        // copies are spread as React props at render). Evaluating first is what
+        // makes one key mean one thing whether it is read as `schema.properties.x`,
+        // as `schema.x`, or as the `x` prop. It also leaves the `content` leg below
+        // idempotent: a value evaluated here no longer carries a `${…}`.
+        //
+        // Per-value and SHALLOW, matching the `props` branch exactly:
+        // `evaluator.evaluate` returns every non-string untouched, so a nested
+        // object/array value is passed through rather than walked (measured: an
+        // `aria: { label: '${data.total}' }` nested under EITHER key renders the raw
+        // source today). Deepening that is a separate decision and would have to be
+        // taken for both spellings at once — not smuggled in on one side here.
+        //
+        // The guard is wider than the `props` branch's bare truthiness on purpose:
+        // this value FEEDS the hoist, so re-shaping a degenerate `properties`
+        // (a string, an array) via the object spread would propagate. Non-objects
+        // skip evaluation and reach the hoist exactly as they do today.
+        // Snapshotted BEFORE evaluation — objectui#5756's diagnostic below reads
+        // the RAW (pre-collapse) text from this reference, since `newSchema.properties`
+        // is about to be replaced with the evaluated copy.
+        const rawPropertiesBag = newSchema.properties &&
+            typeof newSchema.properties === 'object' &&
+            !Array.isArray(newSchema.properties)
+            ? newSchema.properties
+            : undefined;
+        if (rawPropertiesBag) {
+            const newProperties = { ...rawPropertiesBag };
+            for (const [key, val] of Object.entries(newProperties)) {
+                newProperties[key] = evaluator.evaluate(val);
+            }
+            newSchema.properties = newProperties;
+        }
+        /**
+         * objectui#5756 — the `${…}` HALF of the #5687/#5454 silence, reached at
+         * the one point in this render where it still can be: BEFORE the hoist
+         * (which would bury it under the node-level keys) and immediately AFTER
+         * the loop above (so `newSchema.properties` already reflects which key
+         * would win the SAME precedence `shouldHide` applies later — see
+         * {@link winningVisibilityKey}).
+         *
+         * A `${…}`-spelled visibility predicate written inside `properties` is
+         * evaluated — and collapsed to a plain boolean — by the loop directly
+         * above, before `shouldHide` (and its #5454/#5687 reporter) ever sees it.
+         * The bare-string spelling of the SAME gate (`properties: { visible:
+         * "data.status == 'draft'" }`) is untouched by that loop (no `${` to
+         * interpolate) and reaches `shouldHide` intact, where the existing
+         * reporter already catches it — this block exists only to give the
+         * template spelling the same fate, not a different one.
+         *
+         * ## What this does NOT do
+         *
+         * - **No verdict change.** This call's return value is discarded; the
+         *   REAL verdict is still decided by `shouldHide` below, off the
+         *   POST-evaluation, POST-hoist schema, exactly as before this card.
+         * - **No new report shape.** It is the SAME `evaluateVisibilityPredicate`
+         *   `shouldHide` calls — same two reporters, same dedupe `Set`, same
+         *   `__DEV__` gate — called one render-step earlier, on the text this
+         *   step is about to erase. There is nothing here to duplicate the LATER
+         *   call: by the time `shouldHide` runs, this key's value is already the
+         *   collapsed boolean, which carries no `data.` text for either reporter
+         *   to match — so at most one of the two calls ever fires per predicate.
+         * - **Only the WINNING key.** Gated on {@link winningVisibilityKey} so a
+         *   `properties.visible` template that a co-declared `visibleWhen`
+         *   outranks is not reported for deciding nothing (mirrors #5454's own
+         *   leg semantics: its reporter is likewise only ever invoked on the leg
+         *   `shouldHide` actually consults).
+         * - **Only what would actually collapse.** A bare string (no `${`) is
+         *   untouched by the loop above and is left for the existing gate-time
+         *   report to catch, unchanged.
+         */
+        if (__DEV__) {
+            const winningKey = winningVisibilityKey(newSchema);
+            if (winningKey && rawPropertiesBag && Object.prototype.hasOwnProperty.call(rawPropertiesBag, winningKey)) {
+                const rawWinningValue = rawPropertiesBag[winningKey];
+                if (typeof rawWinningValue === 'string' && rawWinningValue.includes('${')) {
+                    // Diagnostic only — the boolean this returns is thrown away.
+                    evaluateVisibilityPredicate(rawWinningValue, winningKey);
+                }
+            }
+        }
         // COMPAT: Hoist 'properties' up to schema level
         // This allows support for strict configs that wrap all props in 'properties'.
         // IMPORTANT: never let inner `properties.type` / `properties.id` shadow the
@@ -279,27 +648,47 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
             }
             newSchema.props = newProps;
         }
-        // Evaluate visibility: visible / visibleWhen / visibleOn / visibility / hidden / hiddenOn
+        // Evaluate visibility: visibleWhen / visible / visibleOn / visibility / hidden / hiddenOn
         const shouldHide = (() => {
-            if (newSchema.visible !== undefined) {
-                return !evaluator.evaluateCondition(newSchema.visible);
-            }
             // `visibleWhen` is the single canonical conditional-visibility predicate
-            // across every layer since ADR-0089 (show-when-truthy). The spec folds the
-            // deprecated `visibleOn` (view) / `visibility` (page) aliases into it at
-            // parse, so it is checked FIRST; the aliases below remain as a defensive
-            // read for any raw / un-normalized metadata reaching the renderer.
+            // across every layer since ADR-0089 (show-when-truthy), and it is the one
+            // this shape DECLARES: `PageComponentSchema` is a closed object that
+            // declares `visibleWhen` (+ the deprecated `visibility`) and REFUSES a
+            // node-level `visible` outright, with the prescription "move it up one
+            // level to the component node's own `visibleWhen` … inside `properties`
+            // it is hoisted onto the node by the renderer but evaluated by nothing"
+            // (`component.zod.ts`, COMPONENT_NODE_VISIBILITY_KEYS).
+            //
+            // It is tested FIRST — ahead of `visible` — since objectui#5454. The
+            // hoist block above copies every `properties.*` value onto the node, so a
+            // node carrying `properties.visible` arrived here with `schema.visible`
+            // set, and the `visible` leg used to short-circuit before the DECLARED
+            // node predicate was ever consulted. Measured on `record:alert`,
+            // `record:path`, `page:card` and `element:text`: `properties.visible`
+            // present and truthy made a co-declared `visibleWhen: false` a no-op, so
+            // the one key the spec tells authors to write was the one key that could
+            // be silently ignored. A declared node predicate now outranks a hoisted
+            // renderer prop; when both resolve to "show", both still have to.
             if (newSchema.visibleWhen !== undefined) {
-                return !evaluator.evaluateCondition(newSchema.visibleWhen);
+                return !evaluateVisibilityPredicate(newSchema.visibleWhen, 'visibleWhen');
+            }
+            // `visible` — objectui's own `BaseSchema` tier (`@object-ui/types`), and
+            // the landing spot of a hoisted `properties.visible`. Kept ABOVE the two
+            // deprecated aliases: they normalize into `visibleWhen` at parse, so a
+            // spec-parsed page never reaches them, and re-ranking them would move
+            // verdicts for raw metadata that objectui#5454 did not rule on.
+            if (newSchema.visible !== undefined) {
+                return !evaluateVisibilityPredicate(newSchema.visible, 'visible');
             }
-            // @deprecated ADR-0089 → `visibleWhen`.
+            // @deprecated ADR-0089 → `visibleWhen`. Defensive read for raw /
+            // un-normalized metadata reaching the renderer.
             if (newSchema.visibleOn !== undefined) {
-                return !evaluator.evaluateCondition(newSchema.visibleOn);
+                return !evaluateVisibilityPredicate(newSchema.visibleOn, 'visibleOn');
             }
             // @deprecated ADR-0089 → `visibleWhen` (was PageNodeSchema.visibility,
             // an ExpressionInput) — show-when-truthy, same semantics as `visibleOn`.
             if (newSchema.visibility !== undefined) {
-                return !evaluator.evaluateCondition(newSchema.visibility);
+                return !evaluateVisibilityPredicate(newSchema.visibility, 'visibility');
             }
             // Ask "is a `hidden` gate DECLARED?" — not "is the key present?"
             // (objectui#3955). These two legs are the only ones in this chain whose
@@ -320,10 +709,10 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
             // equivalence, and pinned as a behaviour change: an UNDECLARED `hidden` no
             // longer short-circuits, so a declared `hiddenOn` is finally consulted.
             if (hasDeclaredPredicate(newSchema.hidden)) {
-                return evaluator.evaluateCondition(newSchema.hidden);
+                return evaluateVisibilityPredicate(newSchema.hidden, 'hidden');
             }
             if (hasDeclaredPredicate(newSchema.hiddenOn)) {
-                return evaluator.evaluateCondition(newSchema.hiddenOn);
+                return evaluateVisibilityPredicate(newSchema.hiddenOn, 'hiddenOn');
             }
             return false;
         })();
@@ -374,7 +763,7 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
             newSchema._disabled = true;
         }
         return newSchema;
-    }, [schema, dataSource, predicateScope, pageVariables]);
+    }, [schema, dataSource, predicateScope, pageVariables, boundRecord]);
     if (!evaluatedSchema)
         return null;
     // If schema is just a string, render it as text
@@ -438,6 +827,24 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
     _disabled: __disabled, // stripped: internal disabled flag
     responsiveStyles: _responsiveStyles, // stripped: compiled to scoped CSS, not a DOM prop
     ...componentProps } = evaluatedSchema;
+    // Dev-build loud diagnostic (objectui#4795, Direction 3): an unevaluated
+    // `${…}` about to be placed verbatim in front of a user.
+    //
+    // Sited HERE, after the metadata destructure, on purpose. `componentProps` is
+    // precisely the set of values that leaves this component for the DOM — it is
+    // spread as React props below, and the same values are what renderers read as
+    // `schema.<key>`. Everything the destructure stripped is schema METADATA:
+    // `visible` / `visibleWhen` / `hidden` / `disabled` / … hold raw predicate
+    // SOURCE by design (they are evaluated as conditions, never placed), so
+    // scanning before the strip would report every correctly-authored predicate
+    // in the repo. The strip list is therefore the diagnostic's exclusion list,
+    // for free and without a second copy of it to drift.
+    //
+    // Read-only: it reports what evaluation already produced and changes nothing
+    // about what is rendered — no DOM attribute either, so no snapshot moves.
+    if (__DEV__) {
+        reportUnevaluatedExpressions(schema, evaluatedSchema.type, evaluatedSchema.id, componentProps, evaluatedSchema.properties, evaluatedSchema.props);
+    }
     // SDUI scoped styling (ADR-0065): a node's `responsiveStyles` compiles to
     // id-scoped CSS injected as a <style> tag, and a scope class is appended to
     // the node's className. Build-independent, collision-free, responsive-correct.
@@ -469,7 +876,12 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
     const rendered = (_jsxs(SchemaErrorBoundary, { componentType: evaluatedSchema.type, resetKey: evaluatedSchema.id ?? null, children: [scopedCss ? (_jsx("style", { "data-os-scope": scopeClass, dangerouslySetInnerHTML: { __html: scopedCss } })) : null, React.createElement(Component, {
                 schema: schemaForComponent,
                 ...componentProps, // Spread non-metadata schema properties as props
-                ...(evaluatedSchema.props || {}), // Override with explicit props if provided
+                // The legacy `props` alias still overrides plain top-level keys, but no
+                // longer overrides the canonical `properties` bag: for a key BOTH bags
+                // declare, `properties` wins here exactly as it already wins in
+                // `readProps()`, so one key has one answer on both channels
+                // (objectui#5123, maintainer ruling 2026-08-18).
+                ...propsWithoutCanonicalKeys(evaluatedSchema.props, evaluatedSchema.properties),
                 ...ariaProps, // Inject ARIA attributes from AriaPropsSchema
                 ...debugAttrs, // Debug-mode data attributes
                 disabled: __disabled || undefined,

package/dist/context/HostNavigationContext.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+/**
+ * HostNavigationContext — the host's own in-app navigate, offered to renderers.
+ *
+ * A published renderer package cannot navigate correctly on its own. Its only
+ * dependency-free option is a browser-level navigation
+ * (`window.location.assign`), which resolves a rooted path such as `/thanks`
+ * against the ORIGIN. Under a host mounted at a sub-path — the framework CLI
+ * configures one for every embedded deployment — that leaves the application
+ * entirely. This is objectui#4989 defect 4, and the same class as
+ * objectui#4190 / #4181.
+ *
+ * The host is the only party that knows its mount, so the host supplies the
+ * navigate. This context is that seam: **optional injection**, ruled by the
+ * maintainer on 2026-08-17. Two mechanisms were rejected in that ruling and are
+ * named here so they are not re-proposed:
+ *
+ *   - **router-presence sniffing** (a renderer reading React Router's context
+ *     when it happens to be there) — implicit magic, and it forces every
+ *     renderer that wants mount-awareness to import `react-router`;
+ *   - **a `react-router` peer requirement** — it imposes module resolution on
+ *     router-less consumers. Two real ones exist in this repo (`apps/site`,
+ *     `packages/plugin-view`), and a published renderer's whole property is
+ *     that it drops into ANY React application.
+ *
+ * Explicit injection keeps every renderer dependency-free and puts
+ * mount-awareness on the type face where a host can see it is missing.
+ *
+ * ## Absent is a supported state, not a degraded one
+ *
+ * The default value is an empty object, so `useHostNavigation()` outside a
+ * provider answers `{ navigate: undefined }` and never throws. A consumer reads
+ * it as "no host navigate — fall back to whatever this renderer did before",
+ * which for a router-less host is already the correct behaviour: with no
+ * router there is no basename, so origin-rooted resolution is right. The seam
+ * changes what a MOUNTED host gets, and changes nothing else.
+ *
+ * ## Relationship to the other navigation seams in this package
+ *
+ * `DrillNavigationContext.openRecordList` is a SEMANTIC navigation — "show me
+ * the records behind this aggregate" — that only the console can turn into a
+ * URL. `ActionProvider`'s `onNavigate` is the ActionRunner's handler for
+ * `type: 'navigate'` actions, reachable only through an action dispatch. This
+ * one is neither: it is the plain "go to this already-resolved in-app path"
+ * that a renderer holds a destination for and cannot perform correctly itself.
+ * All three are supplied by the same shell from the same router `navigate`.
+ */
+import React from 'react';
+export interface HostNavigationValue {
+    /**
+     * Navigate to an in-app path, resolved by the HOST — so a mounted host's
+     * basename is applied and the transition stays inside the application.
+     *
+     * `to` is an already-resolved, application-relative path (e.g. `/thanks`,
+     * `/apps/crm/accounts/r1`), never an absolute URL: a renderer that holds an
+     * external destination must not launder it through the host's router. It is
+     * the CALLER's job to have judged the destination — this seam performs a
+     * navigation, it does not authorize one.
+     *
+     * Absent when no host wired it; consumers fall back to their own default.
+     */
+    navigate?: (to: string, options?: {
+        replace?: boolean;
+    }) => void;
+}
+export declare const HostNavigationContext: React.Context<HostNavigationValue>;
+export declare const HostNavigationProvider: React.FC<{
+    value: HostNavigationValue;
+    children: React.ReactNode;
+}>;
+/**
+ * Consume the host-provided in-app navigate. Answers `{}` (i.e. `navigate`
+ * undefined) when no host wired one — that is a supported state, see the module
+ * docblock.
+ */
+export declare function useHostNavigation(): HostNavigationValue;