From 2a7fb48841dedb0adac74bf6d379c88f2eb2c1af Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 6 Sep 2026 14:04:54 +0000
Subject: [PATCH] docs(react-runtime): compile every README snippet and leave
 the UNGATED_DOCS ledger
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Part of #5174 — batch 23 of the UNGATED_DOCS burn-down.

All 5 ts/tsx blocks in packages/react-runtime/README.md now compile against the
built types, so the document leaves the ledger. The gate file's only change is
the two lines of that one entry; the strictness region is byte-identical.

The 27 diagnostics across 7 codes were three families, not seven:
  - undefined ambient demo names (TS2304, TS18004 shorthand, TS2552) — the
    values a reader injects into the runtime scope, now declared;
  - a missing self-import of ReactRunner in three blocks;
  - one catalogue block that declared `Page` four ways. TS2300x4 plus the
    TS2813/TS2814 the ledger called "candidate real defects, un-triaged" are
    all downstream of that one collision, and are NOT defects: the lines are
    alternative sources shown together. They are named apart so the block
    compiles, with prose saying so.

No packages/** source touched, no public type widened, no gate loosened, and no
new fragment marker.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr
---
 packages/react-runtime/README.md    | 46 ++++++++++++++++++++++++-----
 scripts/check-doc-snippet-types.mjs |  2 --
 2 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/packages/react-runtime/README.md b/packages/react-runtime/README.md
index 705061bb09..0091ac867c 100644
--- a/packages/react-runtime/README.md
+++ b/packages/react-runtime/README.md
@@ -29,8 +29,16 @@ npm install @object-ui/react-runtime
 ## Usage
 
 ```tsx
+import type { ComponentType } from 'react';
 import { ReactRunner } from '@object-ui/react-runtime';
 
+// Whatever your app already has to hand: the values it injects into the runtime
+// scope, and the sink it reports errors to.
+declare const ObjectGrid: ComponentType;
+declare const useAdapter: () => unknown;
+declare const data: unknown;
+declare const report: (error: Error) => void;
+
 <ReactRunner
   code={`
     function Page() {
@@ -60,16 +68,23 @@ import { ReactRunner } from '@object-ui/react-runtime';
 declaration, `()`, or `class`:
 
 ```tsx
-<p>hi</p>                              // ✅ bare JSX
-function Page() { return <p/>; }       // ✅ function declaration
-() => <p>hi</p>                        // ✅ arrow expression
-class Page extends React.Component {}  // ✅ class
-
-const Page = () => <p/>;               // ❌ exports nothing — see below
-const Page = () => <p/>;
-export default Page;                   // ✅ export it explicitly
+// `React` is always in the runtime scope, so a source never imports it.
+declare const React: typeof import('react');
+
+<p>hi</p>                                   // ✅ bare JSX
+function PageFunction() { return <p/>; }    // ✅ function declaration
+() => <p>hi</p>                             // ✅ arrow expression
+class PageClass extends React.Component {}  // ✅ class
+
+const PageNotExported = () => <p/>;         // ❌ exports nothing — see below
+const PageExported = () => <p/>;
+export default PageExported;                // ✅ export it explicitly
 ```
 
+Each line above is a **separate source** — they are alternatives, not one file.
+They carry different names only so the block compiles as a single program; the
+rule is about the shape the source *starts with*, never about the name.
+
 The `const Page = …` form is the one authors reach for most, and it does **not**
 get the implicit export. It used to render a blank page with no error anywhere;
 it now throws with a message naming the fix, which `fallback` surfaces.
@@ -81,6 +96,11 @@ There is no module resolver. `import x from 'y'` compiles to a `require('y')`
 that reads `scope.import`:
 
 ```tsx
+import { ReactRunner } from '@object-ui/react-runtime';
+
+declare const code: string;
+declare const dateFns: Record<string, unknown>;
+
 <ReactRunner code={code} scope={{ import: { 'date-fns': dateFns } }} />
 ```
 
@@ -116,6 +136,13 @@ Build the scope with `useMemo` (or hoist it to module scope) and keep its
 dependencies stable.
 
 ```tsx
+import { useMemo, type ComponentType } from 'react';
+import { ReactRunner } from '@object-ui/react-runtime';
+
+declare const src: string;
+declare const ObjectGrid: ComponentType;
+declare const data: unknown;
+
 // ❌ new object every render — the page remounts and loses its useState
 <ReactRunner code={src} scope={{ ObjectGrid, data }} />
 
@@ -135,6 +162,9 @@ just transpile/eval failures. New inputs clear it and recompile.
 ```ts
 import { generateElement, transform, type Scope } from '@object-ui/react-runtime';
 
+declare const code: string;
+declare const scope: Scope;
+
 transform(code)                  // JSX/TS → JS (classic runtime, imports → require)
 generateElement(code, scope)     // transpile + eval → ReactElement | null (throws, see above)
 ```
diff --git a/scripts/check-doc-snippet-types.mjs b/scripts/check-doc-snippet-types.mjs
index 9beae7db59..dfff5201e5 100644
--- a/scripts/check-doc-snippet-types.mjs
+++ b/scripts/check-doc-snippet-types.mjs
@@ -739,8 +739,6 @@ const UNGATED_DOCS = {
     '3 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies',
   'packages/providers/README.md':
     '7 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2741x1 — candidate real defects, un-triaged',
-  'packages/react-runtime/README.md':
-    '25 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2813x1 TS2814x1 — candidate real defects, un-triaged',
 };
 
 // ── Fence scanning ───────────────────────────────────────────────────────────