docs(react): toRenderableSchema's header says the bridge is permanent (#4622)

.changeset/schema-input-bridge-permanent-4622.md

@@ -0,0 +1,38 @@
+---
+'@object-ui/react': patch
+---
+
+`toRenderableSchema`'s header now says the bridge is permanent, instead of instructing
+callers to remove it (objectui#4622).
+
+No executable line changes — but the artifact is **not** unchanged, and that is worth
+stating plainly rather than rounding to "comment-only". This package builds with plain
+`tsc`, and `tsconfig.base.json` sets `"removeComments": false` deliberately, so the JSDoc
+is emitted into `dist/schema-input.js` as well as `dist/schema-input.d.ts` — it is both
+what an editor shows on hover at every call site and bytes that ship.
+
+Measured by building the package the way the repo builds it, at both revisions:
+`dist/schema-input.js` grows from 1,486 to 2,377 bytes (1.45 KB to 2.32 KB), and from 850
+to 1,266 bytes gzipped (0.83 KB to 1.24 KB) — **+891 bytes raw, +416 gzipped**. All 19
+differing lines in the emitted file are JSDoc continuations and the three executable lines
+are byte-identical, so the growth is the paragraph and nothing else. The trade is
+deliberate: roughly 0.4 KB gzipped, against the five-hour `Build Docs` outage the old
+paragraph's instruction produced once already.
+
+The old closing paragraph said the two competing repo-wide `SchemaNode` spellings "have
+not been reconciled" and that "when it lands, the call sites using this can go back to
+forwarding directly". Both halves went false when PR #4608 merged, and the second half is
+the harmful one: it is an instruction whose trigger condition has now fired, sitting
+directly above the function a future author is about to call.
+
+The reconciliation (objectui#4580 / PR #4608) resolved the collision in favour of
+`@object-ui/types`' union — `@object-ui/core` now re-exports it rather than hand-declaring
+an interface — while `SchemaRenderer`'s prop stays deliberately narrow per objectui#4548
+ruling Q2 (`schema: BaseSchema | string | null | undefined`, no `number` / `boolean`). So
+a `SchemaNode` became *less* assignable to that prop, not more, and the bridge is a
+permanent crossing between two intentionally different types rather than scaffolding
+awaiting a merge.
+
+Following the old instruction has a measured cost: five `apps/site` call sites were
+forwarding directly when PR #4608 landed, and `Build Docs` was red on `main` for roughly
+five hours until PR #4621 routed all five through this function (objectui#4617).

packages/react/src/schema-input.ts

@@ -25,10 +25,21 @@ import type { SchemaRendererProps } from './SchemaRenderer.js';
  * tells no lie — the value a caller forwards renders identically whether or not
  * it passes through here.
  *
- * It exists because the two competing repo-wide `SchemaNode` spellings
- * (`@object-ui/core`'s interface vs `@object-ui/types`' union) have not been
- * reconciled; that reconciliation is tracked separately. When it lands, the
- * call sites using this can go back to forwarding directly.
+ * The bridge is PERMANENT — not scaffolding awaiting a merge. The two competing
+ * repo-wide `SchemaNode` spellings ARE reconciled (objectui#4580, PR #4608):
+ * `@object-ui/core` stopped hand-declaring its own interface and now re-exports
+ * `@object-ui/types`' union, so one declaration is left to disagree with. That
+ * reconciliation resolved in favour of the UNION, while `SchemaRenderer`'s prop
+ * stays deliberately narrow (objectui#4548 ruling Q2 — it declares no `number`
+ * or `boolean`), so a `SchemaNode` is now LESS assignable to that prop than it
+ * was, not more. This step therefore bridges two intentionally different types,
+ * and it stays. ⛔ Do not "tidy" a call site back into a direct forward: the
+ * five `apps/site` sites that were forwarding directly when PR #4608 landed are
+ * what kept `Build Docs` red on `main` for ~5 hours — each one a TS2322 naming
+ * `number` against this function's return type, spelled
+ * `string | BaseSchema | null | undefined` in objectui#4617's logs — until
+ * PR #4621 routed all five through here. An earlier revision of this paragraph
+ * said the reconciliation was still pending and invited exactly that edit.
  */
 export function toRenderableSchema(
   node: BaseSchema | string | number | boolean | null | undefined,