@cosmoops/connect-sdk 0.9.0 → 0.16.0

package/dist/esm/store.js

@@ -0,0 +1,141 @@
+/**
+ * Building blocks for `data.commit` - the transform sentinels, and the two
+ * ways to say "only if nothing has moved".
+ *
+ * Isomorphic and dependency-free, so a Server Component and a client component
+ * building the same write use the same constructors. They are functions rather
+ * than object literals you write by hand because the sentinel shape is an
+ * encoding, not an API: `{ __transform: "increment", by: 1 }` is what goes over
+ * the wire, and nothing outside this file should have to know that.
+ */
+/**
+ * Add to a number, atomically.
+ *
+ * **The one operation you genuinely cannot do yourself.** Increments are
+ * commutative, so two concurrent `increment(500)` calls both land - where
+ * read-add-write from your own process loses one of them however carefully it
+ * retries, because the read and the write are two round trips with a gap in
+ * between. Use this for balances, counters and tallies, and reach for a
+ * precondition only when the new value depends on the old one in a way
+ * addition cannot express.
+ *
+ * Negative to subtract; there is no separate `decrement`.
+ */
+export function increment(by) {
+    return { __transform: "increment", by };
+}
+/** Connect's own write time, rather than a clock reading from your process. */
+export function serverTimestamp() {
+    return { __transform: "serverTimestamp" };
+}
+/** Adds the values not already in the array. Order is not preserved. */
+export function arrayUnion(...values) {
+    return { __transform: "arrayUnion", values };
+}
+/** Removes every occurrence of each value. */
+export function arrayRemove(...values) {
+    return { __transform: "arrayRemove", values };
+}
+/**
+ * Removes the field entirely.
+ *
+ * `merge` only - a `replace` already drops every field it does not list, so
+ * asking it to delete one is a contradiction rather than a narrowing.
+ */
+export function deleteField() {
+    return { __transform: "delete" };
+}
+/**
+ * "Only if this document has not changed since I read it."
+ *
+ * Pass the document a read returned, and the precondition is built from its
+ * `_updateTime`. Taking the document rather than the timestamp is deliberate:
+ * a caller who has to reach for `doc.data._updateTime` themselves is one typo
+ * away from a precondition that silently does nothing.
+ *
+ * Throws rather than degrading when the document carries no `_updateTime` -
+ * that only happens for a document you built yourself rather than read, and a
+ * precondition that quietly became "no precondition" is worse than a crash at
+ * the call site.
+ */
+export function unchangedSince(document) {
+    const updateTime = document.data._updateTime;
+    if (typeof updateTime !== "string") {
+        throw new Error(`Document "${document.id}" has no _updateTime, so there is no version to hold it to. Preconditions are built from documents you read back, not from ones you constructed.`);
+    }
+    return { updateTime };
+}
+/** "Only if this document exists" / "only if it does not." */
+export function documentExists(exists = true) {
+    return { exists };
+}
+/** Firestore treats these as a range scan, which constrains where they may sit. */
+const RANGE_OPERATORS = new Set(["!=", "not-in", "<", "<=", ">", ">="]);
+/** Served by an equality-shaped index entry - `in` is a disjunction of equalities. */
+const EQUALITY_OPERATORS = new Set(["==", "in"]);
+/**
+ * The composite index a query shape needs, or `null` when Firestore's
+ * automatic single-field indexes already serve it.
+ *
+ * Use it to generate your Store tab declarations from the queries your code
+ * actually makes, rather than transcribing them by hand and discovering the
+ * gap in production:
+ *
+ * ```ts
+ * const needed = MY_QUERY_SHAPES.map(storeIndexFor).filter(Boolean);
+ * ```
+ *
+ * **Field order is Firestore's, not yours.** Equality fields first (sorted, so
+ * the order you passed them in cannot produce two different declarations for
+ * one query), then the `array-contains` field, then the field the query orders
+ * by. Declaring the same shape twice in two orders builds two indexes, one of
+ * which is dead weight on every document write.
+ *
+ * Connect runs the same derivation server-side and is the authority: a query
+ * with no matching declared index is refused with the index it needs spelled
+ * out, so a disagreement here surfaces on the first call rather than silently.
+ *
+ * Throws for a query Firestore cannot serve at all - two `array-contains`
+ * filters, ranges over two fields, or a range ordered by a different field.
+ */
+export function storeIndexFor(query) {
+    const filters = query.filters ?? [];
+    const orderBy = query.orderBy ?? null;
+    const equalities = filters.filter((filter) => EQUALITY_OPERATORS.has(filter.op));
+    const arrayContains = filters.filter((filter) => filter.op === "array-contains");
+    const rangeFields = [
+        ...new Set(filters.filter((filter) => RANGE_OPERATORS.has(filter.op)).map((f) => f.field)),
+    ];
+    if (arrayContains.length > 1) {
+        throw new Error(`A query may use "array-contains" once; this one uses it ${arrayContains.length} times.`);
+    }
+    if (rangeFields.length > 1) {
+        throw new Error(`A query may range over one field; this one ranges over ${rangeFields.join(", ")}.`);
+    }
+    const rangeField = rangeFields[0] ?? null;
+    if (rangeField && orderBy && orderBy.field !== rangeField) {
+        throw new Error(`A range filter on "${rangeField}" must be ordered by "${rangeField}" - Firestore cannot order a range scan by "${orderBy.field}".`);
+    }
+    const ordered = orderBy?.field ?? rangeField;
+    const distinct = new Set([...filters.map((filter) => filter.field), ...(ordered ? [ordered] : [])]);
+    if (filters.length <= 1 && distinct.size <= 1)
+        return null;
+    const fields = [
+        ...[...new Set(equalities.map((filter) => filter.field))]
+            .sort()
+            .map((field) => ({ field, direction: "asc" })),
+        ...arrayContains.map((filter) => ({ field: filter.field, direction: "array-contains" })),
+    ];
+    if (ordered)
+        fields.push({ field: ordered, direction: orderBy?.direction ?? "asc" });
+    return fields;
+}
+/**
+ * An index as one comparable string - `"status:asc,createdAt:desc"`.
+ *
+ * Deduplicate a generated list on this before declaring it: a dozen query
+ * shapes across a screen usually collapse to two or three distinct indexes.
+ */
+export function storeIndexSignature(fields) {
+    return fields.map((entry) => `${entry.field}:${entry.direction}`).join(",");
+}

package/dist/esm/ui/empty-state.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card } from "@heroui/react";
+/**
+ * What a list, grid or table shows when it has nothing to show.
+ *
+ * **The two empty states are different facts and the copy must say so.** "You
+ * have no contacts" and "no contacts match this filter" call for different
+ * words and a different action - create the thing, versus undo the filter
+ * hiding it. Both render through here; the caller decides which by what it
+ * passes as `action`. Getting this wrong costs a user real time: an
+ * unfiltered-looking empty state in front of a filtered list reads as data
+ * loss.
+ *
+ * `variant` chooses the container by what the state stands *in*: `card` (the
+ * default), `dashed` for a region that will be filled in place - a file grid,
+ * a board column - where the outline is what says "things appear here", and
+ * `plain` for a slot already inside a card that would otherwise nest two
+ * borders.
+ */
+export function ConnectEmptyState({ icon, title, description, action, variant = "card", className, }) {
+    const body = (_jsxs("div", { className: "flex flex-col items-center text-center", children: [icon && (_jsx("span", { "aria-hidden": true, className: "mb-3 text-muted [&>svg]:size-8", children: icon })), _jsx("p", { className: "text-sm font-medium text-foreground", children: title }), description && _jsx("p", { className: "mt-1 max-w-md text-sm text-muted", children: description }), action && _jsx("div", { className: "mt-3", children: action })] }));
+    if (variant === "plain")
+        return _jsx("div", { className: className, children: body });
+    return (_jsx(Card, { className: `p-5 sm:p-8 ${variant === "dashed" ? "border-dashed" : ""} ${className ?? ""}`, children: body }));
+}

package/dist/esm/ui/index.js

@@ -0,0 +1,34 @@
+/**
+ * Page-composition primitives - the layer between HeroUI and your features.
+ *
+ * Deliberately **not** `"use client"`. Everything here is presentational, with
+ * no hooks and no state, so it renders in a Server Component and stays out of
+ * the browser bundle. That is the whole reason this is a separate entry point
+ * from `@cosmoops/connect-sdk/client`: that module's barrel carries a
+ * `"use client"` directive, so re-exporting a `<Card>` wrapper through it
+ * would turn every page shell in your app into a client boundary for no gain.
+ *
+ * The interactive counterparts - a confirm dialog, cursor pagination, filter
+ * tabs - hold state and live in `/client` alongside the rest of the browser
+ * half.
+ *
+ * ```tsx
+ * import { ConnectPageShell, ConnectSection } from "@cosmoops/connect-sdk/ui";
+ *
+ * export default function ContactsPage() {
+ *   return (
+ *     <ConnectPageShell title="Contacts" description="Everyone you do business with.">
+ *       <ConnectPageShell.Async fallback={<TableSkeleton />}>
+ *         <ContactsTable />
+ *       </ConnectPageShell.Async>
+ *     </ConnectPageShell>
+ *   );
+ * }
+ * ```
+ */
+export { ConnectPageShell } from "./page-shell.js";
+export { ConnectPageHeader } from "./page-header.js";
+export { ConnectSection } from "./section.js";
+export { ConnectEmptyState } from "./empty-state.js";
+export { ConnectSettingRow } from "./setting-row.js";
+export { ConnectStatusChip } from "./status-chip.js";

package/dist/esm/ui/page-header.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The title / description / action block a page opens with.
+ *
+ * The structure is the point, not the styling. The action is a peer of the
+ * **title**, not of the block, so nothing below the first line can move it -
+ * the common hand-rolled shape puts the action after the description, which
+ * makes the vertical position of a page's primary control a function of how
+ * long someone wrote the paragraph above it. On a phone that pushes it most of
+ * a thumb's reach down the screen.
+ *
+ * Mobile-first, and the two axes are separate decisions: the title row is a
+ * `justify-between` at every width (title left, action right, where a thumb
+ * expects it), while the description is clamped to two lines on a phone and
+ * released from `sm` up.
+ *
+ * An `h2`, because the document's `h1` is the application itself.
+ *
+ * No hooks and no state, so this renders from a Server Component - which is
+ * why it lives in `@cosmoops/connect-sdk/ui` rather than `/client`.
+ */
+export function ConnectPageHeader({ title, description, action, clamp = true, className, }) {
+    return (_jsxs("header", { className: `flex items-start justify-between gap-3 ${className ?? ""}`, children: [_jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("h2", { className: "flex items-center gap-2 text-lg font-semibold", children: title }), description && (_jsx("p", { className: `mt-2 text-sm text-muted ${clamp ? "line-clamp-2 sm:line-clamp-none" : ""}`, children: description }))] }), action && _jsx("div", { className: "shrink-0", children: action })] }));
+}

package/dist/esm/ui/page-shell.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense } from "react";
+import { ConnectPageHeader } from "./page-header.js";
+/**
+ * The frame a page opens with: its vertical rhythm, its header, and the
+ * suspended regions beneath.
+ *
+ * **The header is a prop, so it renders in the static shell** - above and
+ * outside every `<Suspense>` boundary. That is the one bug this component
+ * exists to make unrepresentable: rendering the header inside the async child
+ * makes a page's own title wait on a data read, and under Next's partial
+ * prefetching the route's shared App Shell loses it as well. There is no
+ * arrangement of `children` that reaches the header slot.
+ *
+ * A detail route is the honest exception, and it has its own door:
+ * `ConnectPageShell.Header` renders the identical header from inside an async
+ * child, for a page whose title is data it does not have yet. Pair it with a
+ * skeleton header in the fallback. The rule is that a *static* title must
+ * never be made to wait, not that every title can be static.
+ *
+ * `space-y-5` is the page gap, owned here so it has exactly one definition.
+ */
+export function ConnectPageShell({ title, description, action, clamp, above, children, }) {
+    return (_jsxs("div", { className: "space-y-5", children: [above, title !== undefined && (_jsx(ConnectPageHeader, { title: title, description: description, action: action, clamp: clamp })), children] }));
+}
+/**
+ * The page header, for a detail route that can only name itself once its data
+ * has loaded. The same component the shell renders from its props, so the two
+ * cannot drift apart.
+ */
+ConnectPageShell.Header = ConnectPageHeader;
+/**
+ * A suspended region of the page.
+ *
+ * The donut: a static shell with async children behind their own boundaries,
+ * so a slow read costs its own section rather than the whole page. Give each
+ * independent region its own `Async` and they stream separately.
+ */
+ConnectPageShell.Async = function ConnectPageShellAsync({ fallback = null, children, }) {
+    return _jsx(Suspense, { fallback: fallback, children: children });
+};

package/dist/esm/ui/section.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card } from "@heroui/react";
+/**
+ * One titled block inside a page: a card, its heading, what it is for, and the
+ * one control that acts on it.
+ *
+ * The heading is an `h3` - `ConnectPageHeader` renders the page title as an
+ * `h2`, so a block *inside* a page is a level below it. Hand-rolled sections
+ * reliably use `h2`, which makes every settings block a sibling of the page it
+ * sits in and flattens the outline a screen reader announces.
+ *
+ * As in the page header, the action is a peer of the title rather than of the
+ * block, so its position does not move with the length of the description.
+ */
+export function ConnectSection({ title, description, action, titleId, className, bodyClassName, children, }) {
+    return (_jsxs(Card, { className: className ?? "p-4 sm:p-5", children: [_jsxs("div", { className: "flex flex-wrap items-start justify-between gap-3", children: [_jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("h3", { id: titleId, className: "text-base font-semibold", children: title }), description && _jsx("p", { className: "mt-1 text-sm text-muted", children: description })] }), action && _jsx("div", { className: "shrink-0", children: action })] }), children && _jsx("div", { className: bodyClassName ?? "mt-4 space-y-4", children: children })] }));
+}

package/dist/esm/ui/setting-row.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * One labelled setting inside a `ConnectSection`.
+ *
+ * Stacks on a phone and goes side-by-side from `sm` up, rather than shrinking
+ * a two-column row until neither column is readable. The control keeps its
+ * intrinsic width so truncation lands on the description.
+ */
+export function ConnectSettingRow({ title, description, action, children, className, }) {
+    return (_jsxs("div", { className: `flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between ${className ?? ""}`, children: [_jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "text-sm font-medium text-foreground", children: title }), description && _jsx("p", { className: "mt-1 text-sm text-muted", children: description }), children && _jsx("div", { className: "mt-3", children: children })] }), action && _jsx("div", { className: "shrink-0 sm:pl-4", children: action })] }));
+}

package/dist/esm/ui/status-chip.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Chip } from "@heroui/react";
+/**
+ * One status, rendered the way every status should be.
+ *
+ * Domain knowledge stays in the domain: each caller exports its own
+ * `ConnectStatusPresentation` next to the union it describes, and this renders
+ * it. A status whose *rendering* carries real logic - a scheduled cancellation
+ * outranking a running trial, say - keeps its own component and calls this for
+ * the final chip. A map cannot express precedence.
+ */
+export function ConnectStatusChip({ status, presentation, className, }) {
+    return (_jsx(Chip, { color: presentation.tone[status], size: "sm", variant: "soft", className: className, children: presentation.label[status] }));
+}

package/dist/types/client/components/ai-screens.d.ts

@@ -0,0 +1,25 @@
+import type { ConnectScreen } from "../../types.js";
+/**
+ * The declared screen a live path is on, or `null` if none matches.
+ *
+ * `null` is a normal outcome, not an error: an application need only describe
+ * the screens it wants the assistant to know about, and an undescribed one
+ * simply costs the assistant its orientation rather than costing the user an
+ * answer.
+ */
+export declare function matchConnectScreen(screens: readonly ConnectScreen[], path: string): ConnectScreen | null;
+/**
+ * Whether an href the model produced may be rendered as a link.
+ *
+ * Same reasoning as Connect's own `showActions` check, and the same conclusion:
+ * an assistant that can emit an arbitrary URL is a redirect the model can be
+ * talked into, and retrieved content shares a context window with its
+ * tool-calling authority. So a link is drawn only when it resolves to a screen
+ * *your application declared* - which makes an external destination structurally
+ * impossible, since no route pattern has a scheme or a host.
+ *
+ * The protocol-relative form is refused separately: `//evil.example.com` has no
+ * scheme for a path matcher to trip over, and would otherwise reach an anchor
+ * as an absolute destination.
+ */
+export declare function isLinkableConnectScreen(screens: readonly ConnectScreen[], href: string): boolean;

package/dist/types/client/components/ai-widgets.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { AiChartInput, AiDetailsInput, AiMetricsInput, AiSourcesInput, AiStepsInput, AiTableInput, AiTimelineInput } from "../../types.js";
+import type { AiChartInput, AiDetailsInput, AiMetricsInput, AiSourcesInput, AiStepsInput, AiActionsInput, AiTableInput, AiTimelineInput, ConnectScreen } from "../../types.js";
 /**
  * `showTable`. Sorting and CSV are what a table is *for* - once an answer is
  * tabular the next thing anyone wants is to reorder it or take it elsewhere,
@@ -40,3 +40,36 @@ export declare function AiSteps({ title, steps, renderDetail, }: Readonly<AiStep
  * without is still a named row - never a marker with nothing behind it.
  */
 export declare function AiSources({ sources }: Readonly<AiSourcesInput>): import("react").JSX.Element;
+/**
+ * Where to go next, as links into *your* application.
+ *
+ * ## Why links and not navigation
+ *
+ * The obvious version of "the assistant can act" moves the user. It is also the
+ * version that breaks the property the whole design rests on: nothing happens
+ * without a click. Retrieved content shares a context window with the model's
+ * tool-calling authority, so an auto-navigate is a redirect primitive that
+ * content can reach. A link cannot be, and loses nothing - the user was going
+ * to click something anyway.
+ *
+ * ## Why every href is checked against your declared screens
+ *
+ * The model can emit any string. Only your application knows which strings are
+ * real routes, which is why `screens` is a prop rather than something Connect
+ * could supply. A link that does not resolve is *dropped* rather than rendered
+ * broken - the prose around it still stands, so a missing link reads as terse
+ * rather than wrong.
+ *
+ * `renderLink` is how this stays router-agnostic. Given one, a link is your
+ * framework's - a Next `<Link>`, a TanStack `<Link>` - and navigation is a
+ * client transition. Without one it falls back to an anchor, which works
+ * everywhere and costs a document load.
+ */
+export declare function AiActions({ title, actions, screens, renderLink, }: Readonly<AiActionsInput & {
+    screens: readonly ConnectScreen[];
+    renderLink?: (props: {
+        href: string;
+        className: string;
+        children: ReactNode;
+    }) => ReactNode;
+}>): import("react").JSX.Element | null;

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

@@ -11,34 +11,51 @@ export interface AppShellProps {
     homeHref?: string;
     /** The sidebar's destinations - items, sections, or a mix. See `ConnectNav`. */
     nav: ConnectNav;
-    /** Current path. Pass `usePathname()` in Next; see `ConnectSideNavProps.activePath`. */
+    /**
+     * A second nav group, pinned to the foot of the rail above the account row.
+     *
+     * For the routes a product has but does not want competing with its own:
+     * settings, help, changelog, status. They are the same `ConnectNav` shape
+     * and get the same active resolution and audience filtering - the only
+     * difference is where they sit, which is the difference between "what this
+     * product is for" and "everything else".
+     *
+     * A route belongs up top if a user goes there to *do the job*, and down here
+     * if they go there to change how the job works. Putting Settings in the
+     * primary list is what makes a nine-item rail out of a five-item product.
+     */
+    secondaryNav?: ConnectNav;
+    /** Current path. Pass `usePathname()` in Next; see `ConnectSidebarNavProps.activePath`. */
     activePath?: string;
     /** See `ConnectLinkRenderer` - how this app renders a link. Defaults to a plain `<a>`. */
     renderLink?: ConnectLinkRenderer;
+    /** Extra rows pinned to the bottom of the sidebar, above the account row. See `ConnectSidebarRow`. */
+    sidebarFooter?: ReactNode;
     /**
-     * Page heading in the top bar. A string renders as the page's `<h1>`, so
-     * don't also put one at the top of the page; pass a node for breadcrumbs or
-     * anything else.
+     * The workspace switcher under the brand. On by default, and it hides itself
+     * for an account with only one workspace - so the reason to pass `false` is
+     * not "most users have one" (already handled) but "this application renders
+     * its own".
      */
-    title?: ReactNode;
-    /** Your own controls in the top bar, left of the Connect ones. */
-    headerActions?: ReactNode;
-    /** Extra content pinned to the bottom of the sidebar, above the fold-away. */
-    sidebarFooter?: ReactNode;
+    workspaceSwitcher?: false;
     /** Rendered below `children`, inside the scrolling content pane. */
     footer?: ReactNode;
-    /** Start the rail collapsed. Ignored when `collapsed` is supplied. */
+    /**
+     * Start the rail collapsed. **Defaults to `true`** - see the component's
+     * own doc comment. Ignored when `collapsed` is supplied, and overridden by
+     * a stored preference from the user's last visit.
+     */
     defaultCollapsed?: boolean;
     /** Drive the rail yourself. Supply `onCollapsedChange` with it. */
     collapsed?: boolean;
     onCollapsedChange?: (collapsed: boolean) => void;
     /** Remove the collapse control and pin the rail expanded. */
     collapsible?: boolean;
-    /** The app launcher in the top bar. On by default. */
+    /** The app launcher, in the sidebar footer. On by default. */
     showAppsGrid?: boolean;
-    /** "Continue with Connect" / "Create account" in the top bar when signed out. On by default. */
+    /** "Continue with Connect" / "Create account" in the sidebar footer when signed out. On by default. */
     showAuthButtons?: boolean;
-    /** Passed to `ConnectUserMenu` - the SDK has no theme provider, so this is host-controlled. */
+    /** Passed to `ConnectUserButton` - the SDK has no theme provider, so this is host-controlled. */
     theme?: ThemeMode;
     onThemeChange?: (theme: ThemeMode) => void;
     /**
@@ -48,7 +65,7 @@ export interface AppShellProps {
      * gate asks for, and an app that mounts a shell and forgets the gate is an
      * app that lets a suspended workspace keep working.
      *
-     * The chrome is never gated: the sidebar, the lockup, the user menu and
+     * The chrome is never gated: the sidebar, the lockup, the account row and
      * sign-out stay reachable in every blocked state, so a blocked customer can
      * always get to the page that unblocks them.
      *
@@ -83,23 +100,21 @@ export interface AppShellProps {
     children: ReactNode;
 }
 /**
- * The application frame every CosmoOps application platform runs inside: a
- * collapsible sidebar, a top bar carrying the app launcher and the account
- * menu, and your pages in the middle.
+ * The application frame every CosmoOps application platform runs inside: one
+ * rail down the side holding the brand, the workspace, the navigation and the
+ * account, and your pages in the rest.
  *
  * This is the piece each partner was otherwise writing by hand, and writing
- * slightly differently - which is how a family of applications stops looking like
- * one product. Everything that should be identical across platforms (the
- * lockup, the rail geometry, the active-route treatment, the launcher, the
- * account menu, the access gate) lives here; everything that genuinely
- * differs is a prop:
+ * slightly differently - which is how a family of applications stops looking
+ * like one product. Everything that should be identical across platforms
+ * lives here; everything that genuinely differs is a prop:
  *
  * ```tsx
  * "use client";
  * import Link from "next/link";
  * import { usePathname } from "next/navigation";
  * import { AppShell } from "@cosmoops/connect-sdk/client";
- * import { LayoutDashboard, Truck } from "lucide-react";
+ * import { LayoutDashboard, Settings, Truck } from "lucide-react";
  *
  * export function Shell({ children }: { children: React.ReactNode }) {
  *   return (
@@ -110,7 +125,10 @@ export interface AppShellProps {
  *       renderLink={(props) => <Link {...props} />}
  *       nav={[
  *         { label: "Overview", href: "/", icon: <LayoutDashboard className="size-5" /> },
- *         { label: "Plans", href: "/plans", icon: <Truck className="size-5" />, gateExempt: true },
+ *         { label: "Shipments", href: "/shipments", icon: <Truck className="size-5" /> },
+ *       ]}
+ *       secondaryNav={[
+ *         { label: "Settings", href: "/settings", icon: <Settings className="size-5" /> },
  *       ]}
  *     >
  *       {children}
@@ -119,13 +137,33 @@ export interface AppShellProps {
  * }
  * ```
  *
+ * **There is no top bar.** There used to be one, carrying a page title, the
+ * launcher and the account menu - and it was a second, half-width strip of
+ * chrome saying things the rail was better placed to say. The launcher and
+ * the account row moved into the rail's footer, where they are one press from
+ * wherever the pointer already is; the page title moved into the page, where
+ * `ConnectPageShell` renders it next to that page's own actions and
+ * breadcrumbs. What is left is a single column of chrome and a full-height
+ * content pane, which is what every application this shell is modelled on
+ * settled at.
+ *
+ * The one exception is below `md`, where a slim bar carries the drawer
+ * trigger. A phone has no rail to put it in, and a navigation you cannot open
+ * is not a smaller navigation.
+ *
+ * **The rail starts collapsed.** `defaultCollapsed` is `true`: the icon rail
+ * is the resting state, and expanding is the deliberate act. That is the right
+ * default because the rail's job is to be *there*, not to be read - a person
+ * learns five glyphs in a day and then wants the 200px back for their data.
+ * A stored preference from the user's last visit always wins over it.
+ *
  * There is no `isSignedIn` branch anywhere in here, and there should be none
- * in yours: the auth buttons render nothing once a session exists, the user
- * menu renders nothing without one, and the launcher renders nothing when
+ * in yours: the auth buttons render nothing once a session exists, the account
+ * row renders nothing without one, and the launcher renders nothing when
  * signed out. The swap happens inside the components.
  *
  * It renders no provider of its own - mount `ConnectProvider` above it, once,
  * so a page with a shell, a plan table and a usage meter still makes one
  * session read.
  */
-export declare function AppShell({ name, icon, homeHref, nav, activePath, renderLink, title, headerActions, sidebarFooter, footer, defaultCollapsed, collapsed: controlledCollapsed, onCollapsedChange, collapsible, showAppsGrid, showAuthButtons, theme, onThemeChange, gate, gateExemptRoutes, askAi, className, contentClassName, children, }: AppShellProps): import("react").JSX.Element;
+export declare function AppShell({ name, icon, homeHref, nav, secondaryNav, activePath, renderLink, sidebarFooter, workspaceSwitcher, footer, defaultCollapsed, collapsed: controlledCollapsed, onCollapsedChange, collapsible, showAppsGrid, showAuthButtons, theme, onThemeChange, gate, gateExemptRoutes, askAi, className, contentClassName, children, }: AppShellProps): import("react").JSX.Element;

package/dist/types/client/components/apps-grid.d.ts

@@ -1,8 +1,17 @@
 export interface ConnectAppsGridProps {
     /** Extra classes on the trigger button. */
     className?: string;
-    /** Trigger label for screen readers. */
+    /** Trigger label for screen readers, and the collapsed rail's tooltip. */
     label?: string;
+    /**
+     * How the trigger is drawn.
+     *
+     * - `"row"` - a full-width sidebar row, glyph on the rail's shared 32px
+     *   centre. The default, since the launcher lives in the sidebar footer now
+     *   that there is no top bar to hold it.
+     * - `"icon"` - the square accent button, for a bar of your own.
+     */
+    variant?: "row" | "icon";
 }
 /**
  * The Google-style app launcher: a grid icon in your top bar that opens a
@@ -17,4 +26,4 @@ export interface ConnectAppsGridProps {
  * Renders nothing when signed out: a launcher with nothing to launch is just a
  * button that opens an empty box.
  */
-export declare function ConnectAppsGrid({ className, label }: ConnectAppsGridProps): import("react").JSX.Element | null;
+export declare function ConnectAppsGrid({ className, label, variant }: ConnectAppsGridProps): import("react").JSX.Element | null;

package/dist/types/client/components/ask-ai.d.ts

@@ -1,5 +1,51 @@
+import { type ReactNode } from "react";
 import { type StreamdownProps } from "streamdown";
+import type { ConnectScreen } from "../../types.js";
 export interface ConnectAskAiProps {
+    /**
+     * The screens in your application, described for the assistant.
+     *
+     * Without these it answers from general knowledge about software, because
+     * Connect has no idea what your product is - see `ConnectScreen`. With them,
+     * "what can I do here?" answers in your own words, the empty panel offers
+     * your own opening questions, and `showActions` can link into your routes.
+     *
+     * Prose and links only: Connect never uses them to decide what anyone may do,
+     * and never executes anything on your behalf.
+     */
+    screens?: readonly ConnectScreen[];
+    /**
+     * The route the user is currently on.
+     *
+     * **Usually omit this.** Left unset, the panel resolves the live path itself
+     * through `useActivePath`, which reads `location.pathname` from a
+     * `useSyncExternalStore` whose server snapshot is empty - so it works inside
+     * a shared App Shell, where `usePathname()` is refused outright
+     * (`CLIENT_HOOK_DYNAMIC`) because URL data cannot live in an artifact shared
+     * across URLs. That is the same reason `ConnectAppShell` recommends leaving
+     * its own `activePath` unset in a Next app.
+     *
+     * Pass it only where your router's path is not `location.pathname` - a
+     * hash router, or a panel embedded under a basePath your routes do not
+     * include.
+     */
+    activePath?: string;
+    /**
+     * Renders an action link with your router, so following one is a client
+     * transition rather than a document load. Omit it and links are plain
+     * anchors, which work everywhere.
+     *
+     * ```tsx
+     * renderLink={({ href, className, children }) => (
+     *   <Link href={href} className={className}>{children}</Link>
+     * )}
+     * ```
+     */
+    renderLink?: (props: {
+        href: string;
+        className: string;
+        children: ReactNode;
+    }) => ReactNode;
     /** Panel heading. Defaults to `"Ask AI"`. */
     title?: string;
     /** Byline over each assistant turn. Defaults to `"Assistant"`. */
@@ -70,4 +116,4 @@ export interface ConnectAskAiProps {
  * Neither is something the browser can discover, so both surface as a message
  * in the panel rather than as a hidden button.
  */
-export declare function ConnectAskAi({ title, assistantName, placeholder, hint, defaultOpen, markdownPlugins, }: ConnectAskAiProps): import("react").JSX.Element | null;
+export declare function ConnectAskAi({ title, assistantName, placeholder, hint, defaultOpen, markdownPlugins, screens, activePath, renderLink, }: ConnectAskAiProps): import("react").JSX.Element | null;