@cosmoops/connect-sdk 0.34.1 → 0.35.0

package/CHANGELOG.md

@@ -3,6 +3,104 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.35.0
+
+One addition, `connectProviderProps()`, for a mistake both applications built
+on this SDK shipped before anyone noticed.
+
+### Your server and your browser can address different Connect instances
+
+`CONNECT_APP_URL` points the server at a non-production Connect. It is not
+`NEXT_PUBLIC_`, so it never reaches the browser, and `ConnectProvider` defaults
+`appUrl` to the public instance independently. Point one and not the other and
+nothing fails: your API reads go to staging while every destination the browser
+builds opens **production** - the user menu's Profile and Billing rows, the app
+launcher's link for an unsubscribed application, `ConnectAccessGate`'s subscribe
+target, and checkout.
+
+The docs said to pass both. That was a rule to remember rather than a shape to
+follow, and the sentence next to it - "the provider takes no props, which is the
+point" - was about `clientId` and read as being about all of them.
+
+```tsx title="app/layout.tsx"
+import { connectProviderProps } from "@cosmoops/connect-sdk/next";
+import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+
+<ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
+```
+
+It returns `{ appUrl }`, resolved from `CONNECT_APP_URL` and falling back to the
+production origin - so the line is correct in every environment and you write it
+once. Props you pass yourself still win, as long as the spread comes first.
+
+**Call it in the Server Component, not in your shell.** It reads a server-side
+variable, so it ships from `/next`, which a Client Component cannot import -
+attempting it fails the build naming `this-entry-is-server-only`. A shell that
+needs `usePathname()` takes the result as a prop; `{ appUrl }` is a plain
+serializable object, so that costs nothing.
+
+Already have a helper that owns this origin - because you also build your own
+links into Connect - keep using it. One function owning the read beats this one
+sitting beside it.
+
+Nothing changes if you were already passing `appUrl`, and nothing breaks if you
+were not: the default is unchanged.
+
+**This was never a security issue**, which is worth saying because it sounds
+like one. `appUrl` is a navigation target you set from your own environment: it
+carries no credential, no gate or permission check reads it, it is never
+reachable from a URL or a request body, and redirect URIs are still matched
+exactly server-side. The worst case is a real charge in the wrong instance, not
+a way in.
+
+### The sidebar's nav rows are 36px, so a ten-route rail stops scrolling
+
+`AppShell`'s rail is the only part of the shell that grows with *your* route
+count, and `ConnectSidebarBody` is the only part that scrolls - so a rail that
+overflows overflows there. Ten destinations at the old 40px came to 436px of
+nav against 273px of fixed chrome (header, workspace switcher, secondary-nav
+footer, account footer), which needs a 709px viewport to sit still; a 1366x768
+screen has about 678px of it. The nav scrolled under its own footer on the most
+common small laptop, which reads as a rail with destinations missing from it.
+
+Nav rows - and every 20px-glyph row, so the secondary nav and the app launcher
+too - are now **36px**, and the scrolling region's own vertical padding drops
+from 8px to 4px a side. That is 56px back on a twelve-row integration, enough
+that the same rail sits still. 36px is still past WCAG 2.5.8's 24px target
+minimum, with the row's full width as the hit area.
+
+**The two 32px-glyph rows stay at 40px** - the workspace switcher and the
+account row. There are exactly two of them, neither scales with your nav, and
+both need the height: a 32px avatar in a 36px row has 2px of air, and the
+account row's label is two lines.
+
+**Shrinking the icons would not have done it.** The glyph box is a flex
+centring container for an icon *you* supply at your own size, so a smaller box
+buys no vertical space and only pushes the icon off the 32px horizontal centre
+the collapsed rail is built on - `RAIL_GUTTER + inset + glyph/2 = RAIL_COLLAPSED / 2`
+is what lets the rail collapse without anything drifting sideways.
+
+Nothing in your code changes. If your nav is long enough to still overflow, the
+levers are the row count and `secondaryNav` - a rail is navigation, and past a
+dozen rows a scrolling one is a sitemap.
+
+### `doctor` now catches it
+
+`npx @cosmoops/connect-sdk doctor` reports a **note** when `CONNECT_APP_URL` is
+set and the layout holding `<ConnectProvider>` passes no `appUrl`, with the fix
+in the output. A note rather than a failure, so it cannot break a CI run: the
+prop may be threaded from the layout into a `"use client"` shell, which reading
+the layout cannot see.
+
+### Fixed: the User-Agent reported the wrong version
+
+`SDK_VERSION` was left at `0.34.0` when 0.34.1 shipped, so every request this
+package made identified itself as the previous release. It is in step again, and
+the assertion that pins it to `package.json` is back to green - it had been
+failing since that release, unnoticed because the publish guard runs the build
+and the pack check rather than the test suite. Diagnostic only; nothing behaved
+differently.
+
 ## 0.34.1
 
 Two tabs, or one abandoned sign-in and one fresh one, could not both work -

package/dist/cjs/cli/doctor.js

@@ -1,3 +1,4 @@
+"use client";
 "use strict";
 /**
  * `npx @cosmoops/connect-sdk doctor` - checks a wired-up project for the
@@ -84,14 +85,14 @@ function checkBridge(appDir, root) {
     }
     return { status: "pass", title: `Bridge route handler (${(0, node_path_1.relative)(root, bridge)})` };
 }
-function checkProvider(appDir, root) {
+function checkProvider(appDir, root, env) {
     const layouts = walk(appDir, ["layout.tsx", "layout.jsx"]);
     const hosting = layouts.filter((path) => /<ConnectProvider/.test(read(path)));
     if (hosting.length === 0) {
         return {
             status: "fail",
             title: "ConnectProvider in a layout",
-            detail: 'Nothing renders <ConnectProvider>. Every client hook and component below it throws without one. In app/layout.tsx:\n       import { ConnectProvider } from "@cosmoops/connect-sdk/client";\n       <ConnectProvider>{children}</ConnectProvider>',
+            detail: 'Nothing renders <ConnectProvider>. Every client hook and component below it throws without one. In app/layout.tsx:\n       import { connectProviderProps } from "@cosmoops/connect-sdk/next";\n       import { ConnectProvider } from "@cosmoops/connect-sdk/client";\n       <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>',
         };
     }
     // A nested provider re-fetches the session and keeps a second cache that the
@@ -104,8 +105,42 @@ function checkProvider(appDir, root) {
             detail: `Found in ${hosting.length} layouts (${hosting.map((path) => (0, node_path_1.relative)(root, path)).join(", ")}). Nested providers keep separate caches, so a mutation in one is invisible to the other. Keep the outermost one only.`,
         };
     }
+    /*
+     * The split integration, and the reason this check exists at all.
+     *
+     * `CONNECT_APP_URL` points the *server* at a non-production Connect. It is
+     * not `NEXT_PUBLIC_`, so `ConnectProvider` cannot read it and defaults
+     * `appUrl` to production independently - and nothing fails. The API reads go
+     * to the configured instance while every destination the browser builds
+     * opens production: the user menu's Profile and Billing rows, the launcher's
+     * link for an unsubscribed application, the access gate's subscribe target,
+     * and checkout. Both applications built on this SDK shipped exactly that.
+     *
+     * `warn` rather than `fail`: the prop may be threaded from a parent Server
+     * Component into a `"use client"` shell, which is the documented shape for a
+     * shell needing `usePathname()` - and that assignment is not visible in the
+     * layout this reads. So this cannot tell from the outside, which is what
+     * `warn` means here.
+     */
+    const pointedElsewhere = /^[ \t]*CONNECT_APP_URL[ \t]*=[ \t]*\S/m.test(env);
+    const carriesOrigin = /appUrl|connectProviderProps/.test(read(hosting[0]));
+    if (pointedElsewhere && !carriesOrigin) {
+        return {
+            status: "warn",
+            title: "ConnectProvider in a layout",
+            detail: `CONNECT_APP_URL is set, but ${(0, node_path_1.relative)(root, hosting[0])} passes no appUrl - so your server talks to that instance while every link the browser builds opens production Connect. Spread it in:\n       <ConnectProvider {...connectProviderProps()}>  // from "@cosmoops/connect-sdk/next"\n       Already threading it into a "use client" shell? Then this is fine and you can ignore it.`,
+        };
+    }
     return { status: "pass", title: `ConnectProvider in a layout (${(0, node_path_1.relative)(root, hosting[0])})` };
 }
+/** The env files `checkEnv` reads, as one string, shared with `checkProvider`. */
+function envText(root) {
+    return [".env.local", ".env.development.local", ".env"]
+        .map((name) => (0, node_path_1.join)(root, name))
+        .filter(node_fs_1.existsSync)
+        .map(read)
+        .join("\n");
+}
 /**
  * Order is the whole check.
  *
@@ -146,8 +181,7 @@ function checkTheme(root) {
  * loaded it - exactly the shell `next dev` will inherit.
  */
 function checkEnv(root) {
-    const files = [".env.local", ".env.development.local", ".env"].map((name) => (0, node_path_1.join)(root, name));
-    const combined = files.filter(node_fs_1.existsSync).map(read).join("\n");
+    const combined = envText(root);
     return ["CONNECT_API_KEY", "CONNECT_CLIENT_ID"].map((name) => {
         // Horizontal whitespace only. `\s*` also matches the newline, so a bare
         // `CONNECT_API_KEY=` was satisfied by the *next* line's value and an empty
@@ -191,7 +225,7 @@ function runDoctor(argv = []) {
     console.log(`[connect-sdk] Checking ${(0, node_path_1.relative)(process.cwd(), root) || root}\n`);
     const checks = [
         checkBridge(appDir, root),
-        checkProvider(appDir, root),
+        checkProvider(appDir, root, envText(root)),
         checkTheme(root),
         ...checkEnv(root),
         checkRedirectUri(),

package/dist/cjs/client/components/shell-context.js

@@ -36,22 +36,51 @@ exports.RAIL_GUTTER = 12;
  * The row shape every sidebar control shares - nav items, the workspace tile,
  * the launcher, the user button.
  *
+ * **The height is not here.** It rides on `SIDEBAR_ROW_ICON` /
+ * `SIDEBAR_ROW_TILE` instead, because the two glyph sizes want different
+ * heights and only one of them is in the region that overflows - see those
+ * two constants.
+ *
  * `overflow-hidden` + `whitespace-nowrap` is what makes the collapse smooth:
  * the label is *clipped* by the shrinking rail rather than re-wrapped or
  * re-measured, so a width animation costs no reflow. Fading the label with
  * `SidebarLabel` on top of that hides the clip itself.
  */
-exports.SIDEBAR_ROW = "group/row relative flex h-10 w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
+exports.SIDEBAR_ROW = "group/row relative flex w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
 /**
- * Leading inset for a row whose glyph is 20px wide (a nav icon, the launcher).
+ * Leading inset *and height* for a row whose glyph is 20px wide (a nav icon,
+ * the launcher, a secondary-nav row).
+ *
  * `10 + 10 = 20`, and `RAIL_GUTTER + 20 = 32`. See `RAIL_COLLAPSED`.
+ *
+ * **36px, not 40px, and the height belongs on this axis rather than on
+ * `SIDEBAR_ROW`.** The nav is the only region of the rail that grows with the
+ * host's route count, and `ConnectSidebarBody` is the only region that
+ * scrolls - so a rail that overflows overflows here. Ten destinations at 40px
+ * came to 436px of nav against 273px of fixed chrome (header, switcher, two
+ * footers), which needs a 709px viewport to sit still; a 1366x768 screen has
+ * about 678px of it. Four pixels a row is 48px back across the twelve rows a
+ * real integration draws, and 36px is still comfortably past the 24px
+ * WCAG 2.5.8 target minimum with the row's full width as the hit area.
+ *
+ * It is deliberately *not* a smaller glyph. The 20px box is a flex centring
+ * container for an icon the **host** supplies at its own size, so shrinking
+ * the box buys no vertical space and only pushes the icon off the 32px centre
+ * the collapsed rail is built on.
  */
-exports.SIDEBAR_ROW_ICON = "ps-[10px]";
+exports.SIDEBAR_ROW_ICON = "h-9 ps-[10px]";
 /**
- * Leading inset for a row whose glyph is 32px wide (the avatar, the workspace
- * tile). `4 + 16 = 20`, landing on the same 32px centre as `SIDEBAR_ROW_ICON`.
+ * Leading inset and height for a row whose glyph is 32px wide (the avatar, the
+ * workspace tile). `4 + 16 = 20`, landing on the same 32px centre as
+ * `SIDEBAR_ROW_ICON`.
+ *
+ * **These stay at 40px.** There are exactly two of them and neither scales
+ * with the host's nav, so they are not what overflows - and both need the
+ * height: a 32px tile in a 36px row has 2px of air, and the account row's
+ * label is two lines (name over email, `leading-tight`) which measures ~32px
+ * on its own.
  */
-exports.SIDEBAR_ROW_TILE = "ps-[4px]";
+exports.SIDEBAR_ROW_TILE = "h-10 ps-[4px]";
 /**
  * The class list for one sidebar row, in one place.
  *

package/dist/cjs/client/components/sidebar.js

@@ -116,7 +116,12 @@ function ConnectSidebarBody({ children }) {
     // zoom away over a region of text is a WCAG 1.4.4 failure, and nothing
     // here needs it suppressed. On the desktop rail, where no ancestor
     // restricts anything, the pair is equivalent to the default.
-    (0, jsx_runtime_1.jsx)("div", { className: "flex min-h-0 flex-1 touch-pan-y touch-pinch-zoom flex-col gap-1 overflow-y-auto overflow-x-hidden px-3 py-2", children: children }));
+    // `py-1` rather than the `py-2` every other region carries: this is the
+    // one region that scrolls, so it is the first place to give up air when
+    // the nav is a row or two from overflowing. The rows paint their own
+    // rounded background, so the hairline above the footer is still clear of
+    // them. See `SIDEBAR_ROW_ICON` for the arithmetic this is part of.
+    (0, jsx_runtime_1.jsx)("div", { className: "flex min-h-0 flex-1 touch-pan-y touch-pinch-zoom flex-col gap-1 overflow-y-auto overflow-x-hidden px-3 py-1", children: children }));
 }
 /**
  * A pinned region at the foot of the rail - the secondary nav, the launcher,

package/dist/cjs/next/index.js

@@ -36,6 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectClient = exports.createConnectHandler = void 0;
 exports.connectClient = connectClient;
+exports.connectProviderProps = connectProviderProps;
 exports.cookieSessionStore = cookieSessionStore;
 exports.createConnectHandlers = createConnectHandlers;
 exports.GET = handle;
@@ -68,8 +69,9 @@ const errors_js_1 = require("../errors.js");
  *
  * ```tsx
  * // app/layout.tsx
+ * import { connectProviderProps } from "@cosmoops/connect-sdk/next";
  * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
- * <ConnectProvider>{children}</ConnectProvider>
+ * <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
  * ```
  *
  * No `next.config.ts` changes needed - configuration comes from the
@@ -86,6 +88,10 @@ const errors_js_1 = require("../errors.js");
  * `ConnectProvider` defaults `appUrl` to the production origin independently,
  * so an app pointed at another instance must pass that prop as well or its
  * portal links and its browser-built authorize URL still go to production.
+ * That is what the `connectProviderProps()` spread above is for, and why the
+ * layout is two imports rather than one - leave it off and the server half and
+ * the browser half of the same integration address different instances, with
+ * nothing failing to say so. See that function's own docs.
  *
  * Register `{your origin}/api/connect/callback` as a redirect URI in the
  * application's Connect client section. That is the only step this cannot do
@@ -126,6 +132,55 @@ function connectClient(overrides = {}) {
         cached = client;
     return client;
 }
+/**
+ * The `ConnectProvider` props that come from the environment.
+ *
+ * ```tsx
+ * // app/layout.tsx - a Server Component
+ * import { connectProviderProps } from "@cosmoops/connect-sdk/next";
+ * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+ *
+ * <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
+ * ```
+ *
+ * ## What it is for
+ *
+ * `CONNECT_APP_URL` points the *server* at a non-production Connect. It is not
+ * `NEXT_PUBLIC_`, so it never reaches the browser, and `ConnectProvider`
+ * defaults `appUrl` to the production origin independently - so pointing the
+ * server somewhere else and leaving the prop off splits the integration in
+ * half. The server talks to dev and every destination the browser builds opens
+ * production: the user menu's Profile and Billing rows, the app launcher's link
+ * for an unsubscribed application, `ConnectAccessGate`'s subscribe target, and
+ * checkout. Nothing errors. The customer is simply asked to buy a second
+ * subscription in an instance where they have none.
+ *
+ * Both apps built on this SDK shipped that bug before anyone noticed, from
+ * reading "the provider takes no props" as a rule rather than as a remark about
+ * `clientId`. A root layout is a Server Component, so one spread fixes it with
+ * no browser-visible copy of the variable.
+ *
+ * ## What it deliberately leaves out
+ *
+ * `clientId` and `basePath`. The first is only needed alongside an explicit
+ * `redirectUri`, when you build the authorize URL in the browser rather than
+ * letting `signIn()` bounce through your own `/signin` route - and handing the
+ * browser a value it does not need is surface for nothing. The second is where
+ * *you* mounted the handler, which the environment does not know. Pass either
+ * yourself; a prop you pass always wins over this spread, whichever order you
+ * write them in, as long as the spread comes first.
+ *
+ * ## If you already have an origin helper
+ *
+ * Use it instead. An app that builds its own links into Connect (a "Manage
+ * team" button, a pricing page's subscribe target) needs that origin on the
+ * server too, and one function owning the read is better than this helper
+ * beside it - two readers of one variable is the shape that caused this. This
+ * exists for the integration that has no such helper, which is most of them.
+ */
+function connectProviderProps() {
+    return { appUrl: (process.env.CONNECT_APP_URL ?? client_js_1.DEFAULT_BASE_URL).replace(/\/+$/, "") };
+}
 /**
  * An httpOnly cookie holding the opaque `sessionToken`.
  *

package/dist/cjs/server/client.js

@@ -179,4 +179,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.34.0";
+exports.SDK_VERSION = "0.35.0";

package/dist/esm/cli/doctor.js

@@ -81,14 +81,14 @@ function checkBridge(appDir, root) {
     }
     return { status: "pass", title: `Bridge route handler (${relative(root, bridge)})` };
 }
-function checkProvider(appDir, root) {
+function checkProvider(appDir, root, env) {
     const layouts = walk(appDir, ["layout.tsx", "layout.jsx"]);
     const hosting = layouts.filter((path) => /<ConnectProvider/.test(read(path)));
     if (hosting.length === 0) {
         return {
             status: "fail",
             title: "ConnectProvider in a layout",
-            detail: 'Nothing renders <ConnectProvider>. Every client hook and component below it throws without one. In app/layout.tsx:\n       import { ConnectProvider } from "@cosmoops/connect-sdk/client";\n       <ConnectProvider>{children}</ConnectProvider>',
+            detail: 'Nothing renders <ConnectProvider>. Every client hook and component below it throws without one. In app/layout.tsx:\n       import { connectProviderProps } from "@cosmoops/connect-sdk/next";\n       import { ConnectProvider } from "@cosmoops/connect-sdk/client";\n       <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>',
         };
     }
     // A nested provider re-fetches the session and keeps a second cache that the
@@ -101,8 +101,42 @@ function checkProvider(appDir, root) {
             detail: `Found in ${hosting.length} layouts (${hosting.map((path) => relative(root, path)).join(", ")}). Nested providers keep separate caches, so a mutation in one is invisible to the other. Keep the outermost one only.`,
         };
     }
+    /*
+     * The split integration, and the reason this check exists at all.
+     *
+     * `CONNECT_APP_URL` points the *server* at a non-production Connect. It is
+     * not `NEXT_PUBLIC_`, so `ConnectProvider` cannot read it and defaults
+     * `appUrl` to production independently - and nothing fails. The API reads go
+     * to the configured instance while every destination the browser builds
+     * opens production: the user menu's Profile and Billing rows, the launcher's
+     * link for an unsubscribed application, the access gate's subscribe target,
+     * and checkout. Both applications built on this SDK shipped exactly that.
+     *
+     * `warn` rather than `fail`: the prop may be threaded from a parent Server
+     * Component into a `"use client"` shell, which is the documented shape for a
+     * shell needing `usePathname()` - and that assignment is not visible in the
+     * layout this reads. So this cannot tell from the outside, which is what
+     * `warn` means here.
+     */
+    const pointedElsewhere = /^[ \t]*CONNECT_APP_URL[ \t]*=[ \t]*\S/m.test(env);
+    const carriesOrigin = /appUrl|connectProviderProps/.test(read(hosting[0]));
+    if (pointedElsewhere && !carriesOrigin) {
+        return {
+            status: "warn",
+            title: "ConnectProvider in a layout",
+            detail: `CONNECT_APP_URL is set, but ${relative(root, hosting[0])} passes no appUrl - so your server talks to that instance while every link the browser builds opens production Connect. Spread it in:\n       <ConnectProvider {...connectProviderProps()}>  // from "@cosmoops/connect-sdk/next"\n       Already threading it into a "use client" shell? Then this is fine and you can ignore it.`,
+        };
+    }
     return { status: "pass", title: `ConnectProvider in a layout (${relative(root, hosting[0])})` };
 }
+/** The env files `checkEnv` reads, as one string, shared with `checkProvider`. */
+function envText(root) {
+    return [".env.local", ".env.development.local", ".env"]
+        .map((name) => join(root, name))
+        .filter(existsSync)
+        .map(read)
+        .join("\n");
+}
 /**
  * Order is the whole check.
  *
@@ -143,8 +177,7 @@ function checkTheme(root) {
  * loaded it - exactly the shell `next dev` will inherit.
  */
 function checkEnv(root) {
-    const files = [".env.local", ".env.development.local", ".env"].map((name) => join(root, name));
-    const combined = files.filter(existsSync).map(read).join("\n");
+    const combined = envText(root);
     return ["CONNECT_API_KEY", "CONNECT_CLIENT_ID"].map((name) => {
         // Horizontal whitespace only. `\s*` also matches the newline, so a bare
         // `CONNECT_API_KEY=` was satisfied by the *next* line's value and an empty
@@ -188,7 +221,7 @@ export function runDoctor(argv = []) {
     console.log(`[connect-sdk] Checking ${relative(process.cwd(), root) || root}\n`);
     const checks = [
         checkBridge(appDir, root),
-        checkProvider(appDir, root),
+        checkProvider(appDir, root, envText(root)),
         checkTheme(root),
         ...checkEnv(root),
         checkRedirectUri(),

package/dist/esm/client/components/shell-context.js

@@ -28,22 +28,51 @@ export const RAIL_GUTTER = 12;
  * The row shape every sidebar control shares - nav items, the workspace tile,
  * the launcher, the user button.
  *
+ * **The height is not here.** It rides on `SIDEBAR_ROW_ICON` /
+ * `SIDEBAR_ROW_TILE` instead, because the two glyph sizes want different
+ * heights and only one of them is in the region that overflows - see those
+ * two constants.
+ *
  * `overflow-hidden` + `whitespace-nowrap` is what makes the collapse smooth:
  * the label is *clipped* by the shrinking rail rather than re-wrapped or
  * re-measured, so a width animation costs no reflow. Fading the label with
  * `SidebarLabel` on top of that hides the clip itself.
  */
-export const SIDEBAR_ROW = "group/row relative flex h-10 w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
+export const SIDEBAR_ROW = "group/row relative flex w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
 /**
- * Leading inset for a row whose glyph is 20px wide (a nav icon, the launcher).
+ * Leading inset *and height* for a row whose glyph is 20px wide (a nav icon,
+ * the launcher, a secondary-nav row).
+ *
  * `10 + 10 = 20`, and `RAIL_GUTTER + 20 = 32`. See `RAIL_COLLAPSED`.
+ *
+ * **36px, not 40px, and the height belongs on this axis rather than on
+ * `SIDEBAR_ROW`.** The nav is the only region of the rail that grows with the
+ * host's route count, and `ConnectSidebarBody` is the only region that
+ * scrolls - so a rail that overflows overflows here. Ten destinations at 40px
+ * came to 436px of nav against 273px of fixed chrome (header, switcher, two
+ * footers), which needs a 709px viewport to sit still; a 1366x768 screen has
+ * about 678px of it. Four pixels a row is 48px back across the twelve rows a
+ * real integration draws, and 36px is still comfortably past the 24px
+ * WCAG 2.5.8 target minimum with the row's full width as the hit area.
+ *
+ * It is deliberately *not* a smaller glyph. The 20px box is a flex centring
+ * container for an icon the **host** supplies at its own size, so shrinking
+ * the box buys no vertical space and only pushes the icon off the 32px centre
+ * the collapsed rail is built on.
  */
-export const SIDEBAR_ROW_ICON = "ps-[10px]";
+export const SIDEBAR_ROW_ICON = "h-9 ps-[10px]";
 /**
- * Leading inset for a row whose glyph is 32px wide (the avatar, the workspace
- * tile). `4 + 16 = 20`, landing on the same 32px centre as `SIDEBAR_ROW_ICON`.
+ * Leading inset and height for a row whose glyph is 32px wide (the avatar, the
+ * workspace tile). `4 + 16 = 20`, landing on the same 32px centre as
+ * `SIDEBAR_ROW_ICON`.
+ *
+ * **These stay at 40px.** There are exactly two of them and neither scales
+ * with the host's nav, so they are not what overflows - and both need the
+ * height: a 32px tile in a 36px row has 2px of air, and the account row's
+ * label is two lines (name over email, `leading-tight`) which measures ~32px
+ * on its own.
  */
-export const SIDEBAR_ROW_TILE = "ps-[4px]";
+export const SIDEBAR_ROW_TILE = "h-10 ps-[4px]";
 /**
  * The class list for one sidebar row, in one place.
  *

package/dist/esm/client/components/sidebar.js

@@ -109,7 +109,12 @@ export function ConnectSidebarBody({ children }) {
     // zoom away over a region of text is a WCAG 1.4.4 failure, and nothing
     // here needs it suppressed. On the desktop rail, where no ancestor
     // restricts anything, the pair is equivalent to the default.
-    _jsx("div", { className: "flex min-h-0 flex-1 touch-pan-y touch-pinch-zoom flex-col gap-1 overflow-y-auto overflow-x-hidden px-3 py-2", children: children }));
+    // `py-1` rather than the `py-2` every other region carries: this is the
+    // one region that scrolls, so it is the first place to give up air when
+    // the nav is a row or two from overflowing. The rows paint their own
+    // rounded background, so the hairline above the footer is still clear of
+    // them. See `SIDEBAR_ROW_ICON` for the arithmetic this is part of.
+    _jsx("div", { className: "flex min-h-0 flex-1 touch-pan-y touch-pinch-zoom flex-col gap-1 overflow-y-auto overflow-x-hidden px-3 py-1", children: children }));
 }
 /**
  * A pinned region at the foot of the rail - the secondary nav, the launcher,

package/dist/esm/next/index.js

@@ -1,5 +1,5 @@
 import { cache } from "react";
-import { ConnectClient } from "../server/client.js";
+import { ConnectClient, DEFAULT_BASE_URL } from "../server/client.js";
 import { createConnectHandler } from "../server/handler.js";
 import { ConnectError } from "../errors.js";
 /**
@@ -24,8 +24,9 @@ import { ConnectError } from "../errors.js";
  *
  * ```tsx
  * // app/layout.tsx
+ * import { connectProviderProps } from "@cosmoops/connect-sdk/next";
  * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
- * <ConnectProvider>{children}</ConnectProvider>
+ * <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
  * ```
  *
  * No `next.config.ts` changes needed - configuration comes from the
@@ -42,6 +43,10 @@ import { ConnectError } from "../errors.js";
  * `ConnectProvider` defaults `appUrl` to the production origin independently,
  * so an app pointed at another instance must pass that prop as well or its
  * portal links and its browser-built authorize URL still go to production.
+ * That is what the `connectProviderProps()` spread above is for, and why the
+ * layout is two imports rather than one - leave it off and the server half and
+ * the browser half of the same integration address different instances, with
+ * nothing failing to say so. See that function's own docs.
  *
  * Register `{your origin}/api/connect/callback` as a redirect URI in the
  * application's Connect client section. That is the only step this cannot do
@@ -82,6 +87,55 @@ export function connectClient(overrides = {}) {
         cached = client;
     return client;
 }
+/**
+ * The `ConnectProvider` props that come from the environment.
+ *
+ * ```tsx
+ * // app/layout.tsx - a Server Component
+ * import { connectProviderProps } from "@cosmoops/connect-sdk/next";
+ * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+ *
+ * <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
+ * ```
+ *
+ * ## What it is for
+ *
+ * `CONNECT_APP_URL` points the *server* at a non-production Connect. It is not
+ * `NEXT_PUBLIC_`, so it never reaches the browser, and `ConnectProvider`
+ * defaults `appUrl` to the production origin independently - so pointing the
+ * server somewhere else and leaving the prop off splits the integration in
+ * half. The server talks to dev and every destination the browser builds opens
+ * production: the user menu's Profile and Billing rows, the app launcher's link
+ * for an unsubscribed application, `ConnectAccessGate`'s subscribe target, and
+ * checkout. Nothing errors. The customer is simply asked to buy a second
+ * subscription in an instance where they have none.
+ *
+ * Both apps built on this SDK shipped that bug before anyone noticed, from
+ * reading "the provider takes no props" as a rule rather than as a remark about
+ * `clientId`. A root layout is a Server Component, so one spread fixes it with
+ * no browser-visible copy of the variable.
+ *
+ * ## What it deliberately leaves out
+ *
+ * `clientId` and `basePath`. The first is only needed alongside an explicit
+ * `redirectUri`, when you build the authorize URL in the browser rather than
+ * letting `signIn()` bounce through your own `/signin` route - and handing the
+ * browser a value it does not need is surface for nothing. The second is where
+ * *you* mounted the handler, which the environment does not know. Pass either
+ * yourself; a prop you pass always wins over this spread, whichever order you
+ * write them in, as long as the spread comes first.
+ *
+ * ## If you already have an origin helper
+ *
+ * Use it instead. An app that builds its own links into Connect (a "Manage
+ * team" button, a pricing page's subscribe target) needs that origin on the
+ * server too, and one function owning the read is better than this helper
+ * beside it - two readers of one variable is the shape that caused this. This
+ * exists for the integration that has no such helper, which is most of them.
+ */
+export function connectProviderProps() {
+    return { appUrl: (process.env.CONNECT_APP_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "") };
+}
 /**
  * An httpOnly cookie holding the opaque `sessionToken`.
  *

package/dist/esm/server/client.js

@@ -175,4 +175,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.34.0";
+export const SDK_VERSION = "0.35.0";

package/dist/types/client/components/shell-context.d.ts

@@ -25,22 +25,51 @@ export declare const RAIL_GUTTER = 12;
  * The row shape every sidebar control shares - nav items, the workspace tile,
  * the launcher, the user button.
  *
+ * **The height is not here.** It rides on `SIDEBAR_ROW_ICON` /
+ * `SIDEBAR_ROW_TILE` instead, because the two glyph sizes want different
+ * heights and only one of them is in the region that overflows - see those
+ * two constants.
+ *
  * `overflow-hidden` + `whitespace-nowrap` is what makes the collapse smooth:
  * the label is *clipped* by the shrinking rail rather than re-wrapped or
  * re-measured, so a width animation costs no reflow. Fading the label with
  * `SidebarLabel` on top of that hides the clip itself.
  */
-export declare const SIDEBAR_ROW = "group/row relative flex h-10 w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
+export declare const SIDEBAR_ROW = "group/row relative flex w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
 /**
- * Leading inset for a row whose glyph is 20px wide (a nav icon, the launcher).
+ * Leading inset *and height* for a row whose glyph is 20px wide (a nav icon,
+ * the launcher, a secondary-nav row).
+ *
  * `10 + 10 = 20`, and `RAIL_GUTTER + 20 = 32`. See `RAIL_COLLAPSED`.
+ *
+ * **36px, not 40px, and the height belongs on this axis rather than on
+ * `SIDEBAR_ROW`.** The nav is the only region of the rail that grows with the
+ * host's route count, and `ConnectSidebarBody` is the only region that
+ * scrolls - so a rail that overflows overflows here. Ten destinations at 40px
+ * came to 436px of nav against 273px of fixed chrome (header, switcher, two
+ * footers), which needs a 709px viewport to sit still; a 1366x768 screen has
+ * about 678px of it. Four pixels a row is 48px back across the twelve rows a
+ * real integration draws, and 36px is still comfortably past the 24px
+ * WCAG 2.5.8 target minimum with the row's full width as the hit area.
+ *
+ * It is deliberately *not* a smaller glyph. The 20px box is a flex centring
+ * container for an icon the **host** supplies at its own size, so shrinking
+ * the box buys no vertical space and only pushes the icon off the 32px centre
+ * the collapsed rail is built on.
  */
-export declare const SIDEBAR_ROW_ICON = "ps-[10px]";
+export declare const SIDEBAR_ROW_ICON = "h-9 ps-[10px]";
 /**
- * Leading inset for a row whose glyph is 32px wide (the avatar, the workspace
- * tile). `4 + 16 = 20`, landing on the same 32px centre as `SIDEBAR_ROW_ICON`.
+ * Leading inset and height for a row whose glyph is 32px wide (the avatar, the
+ * workspace tile). `4 + 16 = 20`, landing on the same 32px centre as
+ * `SIDEBAR_ROW_ICON`.
+ *
+ * **These stay at 40px.** There are exactly two of them and neither scales
+ * with the host's nav, so they are not what overflows - and both need the
+ * height: a 32px tile in a 36px row has 2px of air, and the account row's
+ * label is two lines (name over email, `leading-tight`) which measures ~32px
+ * on its own.
  */
-export declare const SIDEBAR_ROW_TILE = "ps-[4px]";
+export declare const SIDEBAR_ROW_TILE = "h-10 ps-[4px]";
 /**
  * The class list for one sidebar row, in one place.
  *
@@ -57,7 +86,10 @@ export declare const SIDEBAR_ROW_TILE = "ps-[4px]";
  * lets a `w-fit`, centred, `px-`-padded button take this shape at all.
  */
 export declare function sidebarRowClass(options?: Readonly<{
-    /** The glyph is 32px (an avatar, a workspace tile) rather than 20px. */
+    /**
+     * The glyph is 32px (an avatar, a workspace tile) rather than 20px - which
+     * also makes the row 40px rather than 36px. See `SIDEBAR_ROW_TILE`.
+     */
     tile?: boolean;
     /** Paint the active treatment. */
     active?: boolean;

package/dist/types/client/components/sidebar.d.ts

@@ -73,13 +73,13 @@ export declare function ConnectSidebarFooter({ children, separated, }: Readonly<
     separated?: boolean;
 }>): import("react").JSX.Element;
 export type ConnectSidebarRowProps = Readonly<{
-    /** The glyph. 20px by default; 32px when `tile`. */
+    /** The glyph. 20px in a 36px row by default; 32px in a 40px row when `tile`. */
     icon: ReactNode;
     /** The row's text, and - when it is a string - its accessible name. */
     label: ReactNode;
     /** Overrides the accessible name. Required when `label` is not a string. */
     "aria-label"?: string;
-    /** The glyph is 32px (an avatar, a workspace tile) rather than 20px. */
+    /** The glyph is 32px (an avatar, a workspace tile) rather than 20px, in a 40px row. */
     tile?: boolean;
     /** Trailing content, e.g. a chevron. Clipped with the label while collapsed. */
     trailing?: ReactNode;

package/dist/types/next/index.d.ts

@@ -9,6 +9,55 @@ import type { UserResponse } from "../types.js";
  * are frequently absent.
  */
 export declare function connectClient(overrides?: Partial<ConnectClientOptions>): ConnectClient;
+/**
+ * The `ConnectProvider` props that come from the environment.
+ *
+ * ```tsx
+ * // app/layout.tsx - a Server Component
+ * import { connectProviderProps } from "@cosmoops/connect-sdk/next";
+ * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+ *
+ * <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
+ * ```
+ *
+ * ## What it is for
+ *
+ * `CONNECT_APP_URL` points the *server* at a non-production Connect. It is not
+ * `NEXT_PUBLIC_`, so it never reaches the browser, and `ConnectProvider`
+ * defaults `appUrl` to the production origin independently - so pointing the
+ * server somewhere else and leaving the prop off splits the integration in
+ * half. The server talks to dev and every destination the browser builds opens
+ * production: the user menu's Profile and Billing rows, the app launcher's link
+ * for an unsubscribed application, `ConnectAccessGate`'s subscribe target, and
+ * checkout. Nothing errors. The customer is simply asked to buy a second
+ * subscription in an instance where they have none.
+ *
+ * Both apps built on this SDK shipped that bug before anyone noticed, from
+ * reading "the provider takes no props" as a rule rather than as a remark about
+ * `clientId`. A root layout is a Server Component, so one spread fixes it with
+ * no browser-visible copy of the variable.
+ *
+ * ## What it deliberately leaves out
+ *
+ * `clientId` and `basePath`. The first is only needed alongside an explicit
+ * `redirectUri`, when you build the authorize URL in the browser rather than
+ * letting `signIn()` bounce through your own `/signin` route - and handing the
+ * browser a value it does not need is surface for nothing. The second is where
+ * *you* mounted the handler, which the environment does not know. Pass either
+ * yourself; a prop you pass always wins over this spread, whichever order you
+ * write them in, as long as the spread comes first.
+ *
+ * ## If you already have an origin helper
+ *
+ * Use it instead. An app that builds its own links into Connect (a "Manage
+ * team" button, a pricing page's subscribe target) needs that origin on the
+ * server too, and one function owning the read is better than this helper
+ * beside it - two readers of one variable is the shape that caused this. This
+ * exists for the integration that has no such helper, which is most of them.
+ */
+export declare function connectProviderProps(): {
+    appUrl: string;
+};
 /**
  * An httpOnly cookie holding the opaque `sessionToken`.
  *

package/dist/types/server/client.d.ts

@@ -138,4 +138,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.34.0";
+export declare const SDK_VERSION = "0.35.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",