From 43f41923fec0d4ffc8c902637f12e34ac4fe0efd Mon Sep 17 00:00:00 2001
From: Mathew Goldsborough <1759329+mgoldsborough@users.noreply.github.com>
Date: Tue, 23 Jun 2026 21:53:23 -1000
Subject: [PATCH 1/3] fix(ui): supply the root-height chain AppFrame's
 height:100% needs

AppFrame fills its host pane with height:100%, which only resolves against
a definite-height ancestor chain (#root -> body -> html). The SDK shipped no
such chain, so a bare app iframe resolved height:100% against a content-height
ancestor and the whole shell collapsed to content height: full width, short
height (issue #22). The precondition the shell depended on was neither supplied
nor enforced, so multiple apps hit it.

AppFrame now establishes the chain itself on render via injectBaseReset(), so
every app built on it fills the pane with no per-app index.html requirement.
The same reset ships as a `@nimblebrain/synapse/ui/base` side-effect import for
apps that want the chain before first paint (no layout jump) or that render a
full-pane root without AppFrame.

The reset is a percentage chain (html, body, #root { height: 100% } plus
body { margin: 0 }), not a viewport unit: percentages resolve against the
actual allocated pane, staying correct on hosts that give an app a pane shorter
than the viewport, where a vh/dvh unit would overflow with a second scrollbar.
AppFrame's height:100% and internal scroll model are unchanged.
---
 CHANGELOG.md                      | 12 ++++++++++-
 README.md                         |  1 +
 package-lock.json                 |  4 ++--
 package.json                      |  7 ++++++-
 src/__tests__/ui/base.test.ts     | 33 +++++++++++++++++++++++++++++++
 src/__tests__/ui/layouts.test.tsx | 14 +++++++++++++
 src/ui/base.ts                    | 24 ++++++++++++++++++++++
 src/ui/internal/base-reset.ts     | 33 +++++++++++++++++++++++++++++++
 src/ui/layouts/AppFrame.tsx       | 11 +++++++++++
 tsup.config.ts                    |  1 +
 10 files changed, 136 insertions(+), 4 deletions(-)
 create mode 100644 src/__tests__/ui/base.test.ts
 create mode 100644 src/ui/base.ts
 create mode 100644 src/ui/internal/base-reset.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e374cf7..ed761a5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,17 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/).
 
-## [0.10.2] - 2026-06-23
+## [0.11.0] - 2026-06-23
+
+Fixes a silent full-pane collapse. `AppFrame` fills its host pane with `height: 100%`, but that only resolves against a definite-height ancestor chain (`#root` → `body` → `html`) — and the SDK shipped no such chain. A Synapse app iframe is its own bare document, so unless the app added `html, body, #root { height: 100% }` to its own `index.html`, `AppFrame`'s `height: 100%` resolved against a content-height ancestor and the whole app collapsed to content height: full width, short height (e.g. an empty board rendering as a ~442px band inside an 868px pane). The precondition the shell depended on was neither supplied nor enforced, so multiple apps hit it.
+
+### Added
+
+- `@nimblebrain/synapse/ui/base` — a side-effect import that injects the root-height chain (`html, body, #root { height: 100% }`) plus `body { margin: 0 }`. Import it in an app entry to establish the chain before first paint (no layout jump), or for a full-pane app that renders without `AppFrame`.
+
+### Fixed
+
+- `AppFrame` now establishes the root-height chain itself, calling the same base reset on render, so **every** app built on it fills the pane with no per-app `index.html` requirement — existing apps included. The fix uses a percentage chain rather than a viewport unit (`vh`/`dvh`): percentages resolve against the actual allocated pane, staying correct on hosts that give an app a pane shorter than the viewport (where a viewport unit would overflow with a second scrollbar). `AppFrame`'s `height: 100%` and internal scroll model are unchanged; the missing precondition is simply now supplied.
 
 Fixes three `ui` tokens that were theme-blind in dark mode. `tokens.bgSubtle`, `tokens.fgFaint`, and `tokens.borderStrong` reference CSS vars (`--color-background-tertiary`, `--color-text-tertiary`, `--color-border-secondary`) that no host injected, so they always resolved to their hardcoded **light** fallbacks — rendering white-on-white surfaces, invisible borders, and illegible faint text whenever a host signaled dark. This hit the SDK's own components (Card, ListRow, Prose, Table, Badge, Button, Avatar, SearchField, SegmentedControl, EmptyState, StatusDot) and any app pairing one of these with a theme-aware token. A `var()` fallback is a static literal that can't branch on theme, so the fix is a theme-aware default layer, not a smarter fallback.
 
diff --git a/README.md b/README.md
index 646e353..baa23f8 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,7 @@ npm install @nimblebrain/synapse
 | `@nimblebrain/synapse/react` | React hooks and providers (`AppProvider`, `SynapseProvider`) |
 | `@nimblebrain/synapse/ui` | Component library — tokens, primitives, components, layouts |
 | `@nimblebrain/synapse/ui/fonts` | Side-effect import that loads the brand fonts into the iframe |
+| `@nimblebrain/synapse/ui/base` | Side-effect import that establishes the root-height chain (`html, body, #root`) the app shell fills. `AppFrame` does this automatically on render; import it in your entry to apply it before first paint |
 | `@nimblebrain/synapse/vite` | Vite plugin for dev mode |
 | `@nimblebrain/synapse/codegen` | CLI + programmatic code generation |
 | `@nimblebrain/synapse/iife` | Pre-built IIFE bundle for `<script>` tags (`window.Synapse`) |
diff --git a/package-lock.json b/package-lock.json
index 6b3a10e..bfe84db 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@nimblebrain/synapse",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@nimblebrain/synapse",
-      "version": "0.10.0",
+      "version": "0.11.0",
       "license": "MIT",
       "bin": {
         "synapse": "dist/codegen/cli.js"
diff --git a/package.json b/package.json
index 0f5902e..2bea46e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@nimblebrain/synapse",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Agent-aware app SDK for the MCP ext-apps protocol",
   "type": "module",
   "exports": {
@@ -24,6 +24,11 @@
       "import": "./dist/ui/fonts.js",
       "require": "./dist/ui/fonts.cjs"
     },
+    "./ui/base": {
+      "types": "./dist/ui/base.d.ts",
+      "import": "./dist/ui/base.js",
+      "require": "./dist/ui/base.cjs"
+    },
     "./vite": {
       "types": "./dist/vite/index.d.ts",
       "import": "./dist/vite/index.js",
diff --git a/src/__tests__/ui/base.test.ts b/src/__tests__/ui/base.test.ts
new file mode 100644
index 0000000..8619bae
--- /dev/null
+++ b/src/__tests__/ui/base.test.ts
@@ -0,0 +1,33 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+// Importing the side-effect entry runs `injectBaseReset()` once at load — the
+// re-exported function is what we exercise per-test.
+import { injectBaseReset } from "../../ui/base.js";
+
+const STYLE_ID = "nb-synapse-base";
+
+describe("injectBaseReset", () => {
+  beforeEach(() => {
+    document.getElementById(STYLE_ID)?.remove();
+  });
+  afterEach(() => {
+    document.getElementById(STYLE_ID)?.remove();
+  });
+
+  it("supplies the root-height chain and removes the body margin", () => {
+    injectBaseReset();
+    const el = document.getElementById(STYLE_ID);
+    expect(el).not.toBeNull();
+    // The fix is a percentage chain, not a viewport unit — guard against a
+    // regression back to vh/dvh, which overflows panes shorter than the viewport.
+    expect(el?.textContent).toContain("html, body, #root");
+    expect(el?.textContent).toContain("height: 100%");
+    expect(el?.textContent).toContain("margin: 0");
+    expect(el?.textContent).not.toMatch(/dvh|vh/);
+  });
+
+  it("is idempotent — injecting twice yields a single style element", () => {
+    injectBaseReset();
+    injectBaseReset();
+    expect(document.querySelectorAll(`#${STYLE_ID}`)).toHaveLength(1);
+  });
+});
diff --git a/src/__tests__/ui/layouts.test.tsx b/src/__tests__/ui/layouts.test.tsx
index 95a0a98..ad807bd 100644
--- a/src/__tests__/ui/layouts.test.tsx
+++ b/src/__tests__/ui/layouts.test.tsx
@@ -41,6 +41,20 @@ describe("AppFrame", () => {
     expect(screen.getByText("Body")).toBeDefined();
     expect(screen.getByText("Footer")).toBeDefined();
   });
+
+  it("establishes the root-height chain on render so the shell can't collapse", () => {
+    document.getElementById("nb-synapse-base")?.remove();
+    render(
+      <AppFrame>
+        <AppFrame.Body>Body</AppFrame.Body>
+      </AppFrame>,
+    );
+    // Without a definite-height ancestor chain, AppFrame's `height: 100%` would
+    // collapse to content height inside the host pane (issue #22). Rendering it
+    // must supply the chain, with no per-app `index.html` requirement.
+    const reset = document.getElementById("nb-synapse-base");
+    expect(reset?.textContent).toContain("height: 100%");
+  });
 });
 
 describe("SidebarLayout", () => {
diff --git a/src/ui/base.ts b/src/ui/base.ts
new file mode 100644
index 0000000..0795d5b
--- /dev/null
+++ b/src/ui/base.ts
@@ -0,0 +1,24 @@
+/**
+ * Establishes the root-height chain a full-pane Synapse app needs. Import for
+ * the side effect:
+ *
+ * ```ts
+ * import "@nimblebrain/synapse/ui/base";
+ * ```
+ *
+ * This injects `html, body, #root { height: 100% }` (so a `height: 100%` app
+ * shell resolves against the iframe's allocated pane) and `body { margin: 0 }`
+ * (so the pane has no UA-margin gap). See `./internal/base-reset.ts` for why a
+ * percentage chain — not a viewport unit — is the correct mechanism.
+ *
+ * `AppFrame` already calls `injectBaseReset()` on render, so apps built on it
+ * get the chain automatically. Import this module explicitly to establish the
+ * chain *before* React mounts — avoiding a first-paint layout jump — or for an
+ * app that renders a full-pane root without `AppFrame`.
+ */
+
+import { injectBaseReset } from "./internal/base-reset.js";
+
+injectBaseReset();
+
+export { injectBaseReset };
diff --git a/src/ui/internal/base-reset.ts b/src/ui/internal/base-reset.ts
new file mode 100644
index 0000000..cf16712
--- /dev/null
+++ b/src/ui/internal/base-reset.ts
@@ -0,0 +1,33 @@
+/**
+ * The root-height chain every full-pane Synapse app needs, as a plain function
+ * (no side effect on import — so a component can call it on render without the
+ * mere act of importing injecting anything). The side-effect entry point is
+ * `../base.ts` (`@nimblebrain/synapse/ui/base`).
+ *
+ * `AppFrame` sizes the app shell with `height: 100%`, which only resolves if its
+ * ancestor chain (`#root` → `body` → `html`) has a definite height. Each app
+ * iframe is its own bare document, so without this chain the shell collapses to
+ * content height — full width, short height — inside the host pane.
+ *
+ * Percentages resolve against the actual pane box, which is correct whether the
+ * app is sandboxed in an iframe or mounted into a host panel. A viewport unit
+ * (`vh`/`dvh`) would instead assume the pane equals the viewport — wrong on
+ * hosts that allocate a pane shorter than the viewport (it overflows with a
+ * second scrollbar). The `#root` rule targets the conventional mount id and
+ * harmlessly matches nothing if an app mounts elsewhere; `html, body` still
+ * apply. `body { margin: 0 }` removes the UA default so the pane has no gap.
+ */
+
+import { ensureStyle } from "./inject-style.js";
+
+const STYLE_ID = "nb-synapse-base";
+const RULES = "html, body, #root { height: 100%; } body { margin: 0; }";
+
+/**
+ * Inject the root-height + body-margin reset once. Idempotent (keyed by a
+ * single style id) and SSR-safe (no-ops when `document` is unavailable, via
+ * `ensureStyle`).
+ */
+export function injectBaseReset(): void {
+  ensureStyle(STYLE_ID, RULES);
+}
diff --git a/src/ui/layouts/AppFrame.tsx b/src/ui/layouts/AppFrame.tsx
index f7b806b..84d0a31 100644
--- a/src/ui/layouts/AppFrame.tsx
+++ b/src/ui/layouts/AppFrame.tsx
@@ -3,6 +3,13 @@
  * an optional fixed footer, filling the iframe pane. Every Synapse app uses it;
  * a body layout (SidebarLayout, ListView, …) goes inside `AppFrame.Body`.
  *
+ * The shell fills the pane with `height: 100%`, which needs a definite-height
+ * ancestor chain (`#root` → `body` → `html`) — something a bare app document
+ * does not supply on its own. So AppFrame establishes that chain itself on
+ * render via `injectBaseReset()`; without it the shell would collapse to
+ * content height. Apps wanting the chain before first paint can also
+ * `import "@nimblebrain/synapse/ui/base"` in their entry.
+ *
  * The `contentWidth` knob is a personality lever: `reading` centers header,
  * body, and footer in a ~760px column (Conversations, Research), while `full`
  * uses the whole pane (CRM, dashboards). Header/body/footer share the same
@@ -16,6 +23,7 @@ import {
   type ReactNode,
   useContext,
 } from "react";
+import { injectBaseReset } from "../internal/base-reset.js";
 import { tokens } from "../tokens.js";
 
 type ContentWidth = "reading" | "full";
@@ -32,6 +40,9 @@ interface AppFrameProps extends HTMLAttributes<HTMLDivElement> {
 }
 
 function AppFrameRoot({ contentWidth = "full", style, children, ...rest }: AppFrameProps) {
+  // The shell's `height: 100%` only resolves against a definite-height ancestor
+  // chain; supply it (same render-time pattern as the components' `ensureStyle`).
+  injectBaseReset();
   return (
     <ContentWidthCtx.Provider value={contentWidth}>
       <div
diff --git a/tsup.config.ts b/tsup.config.ts
index ab29db0..8f7c6ed 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -8,6 +8,7 @@ export default defineConfig([
       "react/index": "src/react/index.ts",
       "ui/index": "src/ui/index.ts",
       "ui/fonts": "src/ui/fonts.ts",
+      "ui/base": "src/ui/base.ts",
       "vite/index": "src/vite/index.ts",
       "codegen/index": "src/codegen/index.ts",
       "codegen/cli": "src/codegen/cli.ts",

From 846c0ae0582c8c6f9a880a8bad68303136fb9c62 Mon Sep 17 00:00:00 2001
From: Mathew Goldsborough <1759329+mgoldsborough@users.noreply.github.com>
Date: Tue, 23 Jun 2026 22:05:10 -1000
Subject: [PATCH 2/3] docs(changelog): restore the published 0.10.2 section,
 isolate 0.11.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 0.11.0 entry was written by replacing the 0.10.2 heading, which dropped
0.10.2 from the changelog and orphaned its (already-shipped) dark-mode-token
notes under 0.11.0 — leaving a malformed section with two ### Fixed blocks.
Re-add the 0.10.2 section (verbatim to the v0.10.2 tag, which is published as
npm latest) above a now self-contained 0.11.0 section.
---
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ed761a5..d6b8c95 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ Fixes a silent full-pane collapse. `AppFrame` fills its host pane with `height:
 
 - `AppFrame` now establishes the root-height chain itself, calling the same base reset on render, so **every** app built on it fills the pane with no per-app `index.html` requirement — existing apps included. The fix uses a percentage chain rather than a viewport unit (`vh`/`dvh`): percentages resolve against the actual allocated pane, staying correct on hosts that give an app a pane shorter than the viewport (where a viewport unit would overflow with a second scrollbar). `AppFrame`'s `height: 100%` and internal scroll model are unchanged; the missing precondition is simply now supplied.
 
+## [0.10.2] - 2026-06-23
+
 Fixes three `ui` tokens that were theme-blind in dark mode. `tokens.bgSubtle`, `tokens.fgFaint`, and `tokens.borderStrong` reference CSS vars (`--color-background-tertiary`, `--color-text-tertiary`, `--color-border-secondary`) that no host injected, so they always resolved to their hardcoded **light** fallbacks — rendering white-on-white surfaces, invisible borders, and illegible faint text whenever a host signaled dark. This hit the SDK's own components (Card, ListRow, Prose, Table, Badge, Button, Avatar, SearchField, SegmentedControl, EmptyState, StatusDot) and any app pairing one of these with a theme-aware token. A `var()` fallback is a static literal that can't branch on theme, so the fix is a theme-aware default layer, not a smarter fallback.
 
 ### Fixed

From cc61ca5b7429fd4e407bbb6760fd08215823145e Mon Sep 17 00:00:00 2001
From: Mathew Goldsborough <1759329+mgoldsborough@users.noreply.github.com>
Date: Tue, 23 Jun 2026 22:14:42 -1000
Subject: [PATCH 3/3] test(ui): drop redundant alternation in the viewport-unit
 guard

`/vh/` already matches inside `dvh`, so the alternation was redundant; the
comment now records that matching "vh" catches "dvh" too.
---
 src/__tests__/ui/base.test.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/__tests__/ui/base.test.ts b/src/__tests__/ui/base.test.ts
index 8619bae..ee8edce 100644
--- a/src/__tests__/ui/base.test.ts
+++ b/src/__tests__/ui/base.test.ts
@@ -18,11 +18,12 @@ describe("injectBaseReset", () => {
     const el = document.getElementById(STYLE_ID);
     expect(el).not.toBeNull();
     // The fix is a percentage chain, not a viewport unit — guard against a
-    // regression back to vh/dvh, which overflows panes shorter than the viewport.
+    // regression back to vh/dvh (matching "vh" also catches "dvh"), which
+    // overflows panes shorter than the viewport.
     expect(el?.textContent).toContain("html, body, #root");
     expect(el?.textContent).toContain("height: 100%");
     expect(el?.textContent).toContain("margin: 0");
-    expect(el?.textContent).not.toMatch(/dvh|vh/);
+    expect(el?.textContent).not.toMatch(/vh/);
   });
 
   it("is idempotent — injecting twice yields a single style element", () => {