@cosmoops/connect-sdk 0.7.0 → 0.15.0

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

@@ -1,7 +1,8 @@
 import { type ReactNode } from "react";
+import { type ConnectAskAiProps } from "./ask-ai.js";
 import { type ConnectLinkRenderer, type ConnectNav } from "./nav.js";
 import type { ThemeMode } from "../../types.js";
-export interface ConnectAppShellProps {
+export interface AppShellProps {
     /** This application's name, in the `cosmo·ops VOICE` lockup. See `ConnectLogo`. */
     name: string;
     /** This application's glyph, drawn on the CosmoOps badge. Falls back to the Connect rings. */
@@ -10,34 +11,51 @@ export interface ConnectAppShellProps {
     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;
     /**
@@ -47,7 +65,7 @@ export interface ConnectAppShellProps {
      * 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.
      *
@@ -61,55 +79,91 @@ export interface ConnectAppShellProps {
      * say. Prefix-matched, same as the nav's active resolution.
      */
     gateExemptRoutes?: string[];
+    /**
+     * Mount `ConnectAskAi` - a chat panel grounded in the signed-in workspace's
+     * Context Index, streamed through your own bridge. Pass an object to
+     * override its heading, copy or markdown plugins.
+     *
+     * **On by default**, like `gate`, and for the same reason: a family of
+     * application platforms should answer questions the same way, and a feature
+     * every partner has to remember to switch on is a feature most of them do
+     * not have. It stays inert until it can actually work - the trigger renders
+     * nothing for a signed-out visitor, and a workspace whose Context Index is
+     * off gets a message in the panel rather than a broken answer.
+     *
+     * Set `false` for an application that should not offer it at all.
+     */
+    askAi?: boolean | ConnectAskAiProps;
     className?: string;
     /** Classes on the scrolling content pane - override the default max-width and padding here. */
     contentClassName?: string;
     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 { ConnectAppShell } from "@cosmoops/connect-sdk/client";
- * import { LayoutDashboard, Truck } from "lucide-react";
+ * import { AppShell } from "@cosmoops/connect-sdk/client";
+ * import { LayoutDashboard, Settings, Truck } from "lucide-react";
  *
  * export function Shell({ children }: { children: React.ReactNode }) {
  *   return (
- *     <ConnectAppShell
+ *     <AppShell
  *       name="Dispatch"
  *       icon={<Truck />}
  *       activePath={usePathname()}
  *       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}
- *     </ConnectAppShell>
+ *     </AppShell>
  *   );
  * }
  * ```
  *
+ * **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 ConnectAppShell({ name, icon, homeHref, nav, activePath, renderLink, title, headerActions, sidebarFooter, footer, defaultCollapsed, collapsed: controlledCollapsed, onCollapsedChange, collapsible, showAppsGrid, showAuthButtons, theme, onThemeChange, gate, gateExemptRoutes, className, contentClassName, children, }: ConnectAppShellProps): 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

@@ -0,0 +1,73 @@
+import { type StreamdownProps } from "streamdown";
+export interface ConnectAskAiProps {
+    /** Panel heading. Defaults to `"Ask AI"`. */
+    title?: string;
+    /** Byline over each assistant turn. Defaults to `"Assistant"`. */
+    assistantName?: string;
+    /** Composer placeholder. */
+    placeholder?: string;
+    /** Shown once, above an empty conversation. */
+    hint?: string;
+    /** Start open. The panel owns its state after that. */
+    defaultOpen?: boolean;
+    /**
+     * Streamdown plugins - syntax highlighting, KaTeX, Mermaid, CJK.
+     *
+     * Off unless you pass them, because each is a package of its own and several
+     * are large (Mermaid alone dwarfs this SDK). Prose, GFM tables, task lists
+     * and plain code fences all render without any of them.
+     *
+     * ```tsx
+     * import { code } from "@streamdown/code";
+     * import { mermaid } from "@streamdown/mermaid";
+     *
+     * <ConnectAskAi markdownPlugins={{ code, mermaid }} />
+     * ```
+     *
+     * Hoist the object to module scope: Streamdown compares this prop by
+     * reference, so an inline literal defeats its block memoisation.
+     */
+    markdownPlugins?: StreamdownProps["plugins"];
+}
+/**
+ * Ask AI - a chat panel grounded in the signed-in workspace's Context Index,
+ * streamed through your own bridge.
+ *
+ * Answers are not only prose. Connect's model can call a small set of
+ * presentation tools - `showTable`, `showChart`, `showMetrics`, `showTimeline`,
+ * `showDetails`, `showSteps`, `showSources` - and this panel renders each one
+ * natively: a sortable table with a CSV download, a chart, a row of metric
+ * tiles. Values arrive raw with a format tag, so they are formatted here rather
+ * than by the model, which is what lets a column sort numerically.
+ *
+ * Nothing here holds a credential: it POSTs to `${basePath}/ai/chat` on your
+ * own origin, and `createConnectHandler` is what reaches Connect. The workspace
+ * is resolved from the caller's session there, never sent from the browser - so
+ * a user can only ever ask about the workspace they are signed into.
+ *
+ * ```tsx
+ * <AppShell name="Dispatch" nav={nav}>
+ *   {children}
+ * </AppShell>
+ * ```
+ *
+ * `AppShell` mounts it by default. Mount it directly only when you are not
+ * using the shell: it renders a fixed corner trigger plus a panel that is an
+ * *in-flow flex sibling* at `lg` and up, so opening it pushes your content
+ * aside rather than covering it. That requires it to be the last child of a
+ * `flex` row owning the viewport height - which is exactly what `AppShell` is.
+ * Below `lg` it is a full-screen sheet with a backdrop instead; there is no
+ * room to push anything on a phone.
+ *
+ * **Host setup:** markdown rendering needs `streamdown` installed, one Tailwind
+ * `@source "…/node_modules/streamdown/dist/*.js"` line so its utility classes
+ * are generated, and `import "streamdown/styles.css"` for the streaming
+ * animation. The colour tokens Streamdown expects are already mapped in this
+ * SDK's `theme.css`.
+ *
+ * Answers require the workspace's Context Index to be turned on (a workspace
+ * admin toggle in Connect) and your API key to carry the `ai:chat` scope.
+ * 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;

package/dist/types/client/components/confirm-dialog.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+export interface ConnectConfirmDialogProps {
+    /** The control that opens it. Rendered inside `Modal.Trigger`. */
+    trigger: ReactNode;
+    title: ReactNode;
+    /** What will happen, in the user's words. Name the thing being acted on. */
+    description?: ReactNode;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    /** `danger` for anything that destroys data. */
+    tone?: "danger" | "primary";
+    onConfirm: () => void | Promise<void>;
+}
+/**
+ * The confirmation in front of a destructive action.
+ *
+ * **It closes on confirm, not on response.** Holding the modal open until the
+ * server answers makes every delete feel like a form submission, and the error
+ * path already has somewhere to go - a toast, or the row reappearing. A dialog
+ * that stays open to report failure is right only where the failure is
+ * *expected* and correctable in place (a seat cap, a last-admin invariant),
+ * and that is a blocking form, not this.
+ *
+ * `onConfirm` may return a promise. It is not awaited before closing, but a
+ * rejection is caught here rather than escaping - an error thrown out of an
+ * async transition reaches the nearest error boundary and takes the page down.
+ *
+ * The anatomy is HeroUI's: `Modal.Backdrop` owns the open state,
+ * `Modal.Container` the sizing, `Modal.Dialog` the focus trap. The trigger
+ * goes inside `Modal.Trigger`, which *is* a React Aria button - so pass a
+ * plain element, never a `<Button>`, or the nested button swallows the press
+ * and the dialog silently never opens.
+ */
+export declare function ConnectConfirmDialog({ trigger, title, description, confirmLabel, cancelLabel, tone, onConfirm, }: Readonly<ConnectConfirmDialogProps>): import("react").JSX.Element;

package/dist/types/client/components/cursor-pagination.d.ts

@@ -0,0 +1,27 @@
+export interface ConnectCursorPaginationProps {
+    /** How many rows the current page is showing. Used for the live-region count. */
+    shown: number;
+    /** The cursor for the next page, or `null` when this is the last one. */
+    nextCursor: string | null;
+    /** Whether a previous page exists - the caller owns the cursor history. */
+    hasPrevious: boolean;
+    onNext: (cursor: string) => void;
+    onPrevious: () => void;
+    isPending?: boolean;
+    /** Singular/plural noun for the count, e.g. `["contact", "contacts"]`. */
+    noun?: readonly [string, string];
+}
+/**
+ * Next / previous for a cursor-paginated list.
+ *
+ * Cursor rather than page numbers, and the component shape follows from that:
+ * there is no "page 7 of 42" because a keyset-paginated list does not know how
+ * many pages there are without a second count query over the same filter -
+ * which is a billed index scan for a number nobody acts on. What a user does
+ * act on is "more" and "back", and those are exact.
+ *
+ * The count is announced in a live region so a screen-reader user learns that
+ * filtering or paging changed the result set. Without it the table silently
+ * swaps its contents.
+ */
+export declare function ConnectCursorPagination({ shown, nextCursor, hasPrevious, onNext, onPrevious, isPending, noun, }: Readonly<ConnectCursorPaginationProps>): import("react").JSX.Element;

package/dist/types/client/components/filter-tabs.d.ts

@@ -0,0 +1,26 @@
+export interface ConnectFilterTabsOption<TValue extends string> {
+    value: TValue | null;
+    label: string;
+    /** Shown as a count beside the label. Omit where a count would need its own query. */
+    count?: number;
+}
+export interface ConnectFilterTabsProps<TValue extends string> {
+    options: ReadonlyArray<ConnectFilterTabsOption<TValue>>;
+    value: TValue | null;
+    onChange: (value: TValue | null) => void;
+    /** Names the group for assistive technology - "Filter contacts by lifecycle". */
+    label: string;
+}
+/**
+ * A single-select filter strip - the "All / Open / Won / Lost" row above a
+ * list.
+ *
+ * Real radio semantics rather than a row of buttons: it is a single choice
+ * from a closed set, so arrow keys should move between options and the
+ * selected one should be announced as selected. A group of `<button>`s gets
+ * neither, and that is the usual hand-rolled shape.
+ *
+ * Scrolls horizontally rather than wrapping on a narrow viewport - a filter
+ * strip that wraps to three lines pushes the list itself off the screen.
+ */
+export declare function ConnectFilterTabs<TValue extends string>({ options, value, onChange, label, }: Readonly<ConnectFilterTabsProps<TValue>>): import("react").JSX.Element;

package/dist/types/client/components/grievance-notice.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+export interface ConnectGrievanceNoticeProps {
+    /**
+     * Heading text. `null` renders none, for embedding inside a page that
+     * already has one.
+     */
+    title?: ReactNode;
+    /**
+     * What this application calls itself in the sentence naming the processor
+     * relationship. Omit to leave that sentence out entirely.
+     */
+    applicationName?: string;
+    className?: string;
+}
+/**
+ * The DPDP s.13 grievance channel, rendered.
+ *
+ * Every application on the platform is a Data Processor under one notice, so
+ * the wording lives here rather than being retyped per application - a user
+ * comparing two applications' privacy pages should not find two different
+ * accounts of who their Data Fiduciary is.
+ *
+ * Renders nothing at all while loading and nothing on failure, rather than a
+ * skeleton or an error. That is unusual here and deliberate: this component
+ * is almost always inside a larger privacy page that has its own content, and
+ * a red error box in the middle of a legal notice reads as the notice itself
+ * being broken. The address is also on the public web either way. Pass
+ * `useConnectCompanyProfile()` directly to your own layout if you want to
+ * handle those states yourself.
+ */
+export declare function ConnectGrievanceNotice({ title, applicationName, className, }: Readonly<ConnectGrievanceNoticeProps>): import("react").JSX.Element | null;

package/dist/types/client/components/link-button.d.ts

@@ -1,20 +1,43 @@
 import { type ButtonProps } from "@heroui/react";
+import type { ReactElement, ReactNode } from "react";
 export type ConnectLinkButtonProps = Omit<ButtonProps, "render"> & {
     href: string;
+    /**
+     * The host's router link, if it has one.
+     *
+     * Without it this renders a plain `<a href>`, which navigates under every
+     * router but costs a **full document load** - in an App Router app that
+     * throws away the client cache and re-runs the whole tree, which is very
+     * visible on a button sitting inside a page the user is working in.
+     *
+     * ```tsx
+     * <ConnectLinkButton href="/deals" renderLink={(props) => <Link {...props} />}>
+     *   Open board
+     * </ConnectLinkButton>
+     * ```
+     *
+     * Same shape as `AppShell`'s `renderLink`, so a host declares its router
+     * once and passes the same function to both. This package imports nothing
+     * from `next` - see the `./next` entry's doc comment for why that is a hard
+     * rule - so handing the link component in is the only way it can be a client
+     * transition.
+     */
+    renderLink?: (props: {
+        href: string;
+        className?: string;
+        children: ReactNode;
+    }) => ReactElement;
 };
 /**
- * A HeroUI `Button` that renders a real `<a>`.
+ * A HeroUI `Button` that renders a link.
  *
- * A plain anchor, deliberately not a router link: this package imports nothing
- * from `next` (see the `./next` entry's doc comment for why that is a hard
- * rule), so it cannot know which router - if any - the host app uses. An
- * `<a href>` navigates under all of them, and a host that wants client-side
- * routing can pass its own element via `render` on the underlying `Button`.
+ * HeroUI v3's `Button` has no `as` prop, so `<Button as={Link}>` does not type
+ * check and does not work - this is the supported route, via `render`.
  *
  * The cast is the same one HeroUI's own "Render Function" example needs:
  * `render` types its argument as the props of the element `Button` would have
- * emitted, which is a `<button>` - including a `ref` typed to
+ * emitted, which is a `<button>`, including a `ref` typed to
  * `HTMLButtonElement`. Spreading that onto an anchor is sound at runtime and
- * unrepresentable in the type, which is exactly what a cast is for.
+ * unrepresentable in the type, which is what the cast is for.
  */
-export declare function ConnectLinkButton({ href, ...props }: Readonly<ConnectLinkButtonProps>): import("react").JSX.Element;
+export declare function ConnectLinkButton({ href, renderLink, ...props }: Readonly<ConnectLinkButtonProps>): import("react").JSX.Element;

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

@@ -14,7 +14,23 @@ export interface ConnectLogoProps {
      * Falls back to the Connect rings when omitted.
      */
     icon?: ReactNode;
-    /** Mark only, no wordmark - for a collapsed sidebar or a favicon-sized slot. */
+    /**
+     * Which halves of the lockup to draw.
+     *
+     * - `"full"` - badge and wordmark, the default.
+     * - `"mark"` - the badge alone, for a collapsed rail or a favicon-sized slot.
+     * - `"wordmark"` - the words alone, for a layout that already draws the
+     *   badge somewhere fixed. The sidebar header uses this: the badge stays put
+     *   while the words fade, and rendering a second badge only to hide it with
+     *   a CSS child selector is how that kind of layout quietly rots.
+     */
+    variant?: "full" | "mark" | "wordmark";
+    /**
+     * Mark only, no wordmark.
+     *
+     * @deprecated Pass `variant="mark"`. Kept because it is the published 0.11
+     * API; `variant` wins when both are given.
+     */
     collapsed?: boolean;
     className?: string;
 }
@@ -32,4 +48,4 @@ export interface ConnectLogoProps {
  * as `text-sm`, with the badge, gap and tracking all in proportion. That is
  * why there is no `size` prop.
  */
-export declare function ConnectLogo({ name, icon, collapsed, className }: ConnectLogoProps): import("react").JSX.Element;
+export declare function ConnectLogo({ name, icon, variant, collapsed, className }: ConnectLogoProps): import("react").JSX.Element;

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

@@ -28,11 +28,26 @@ export interface ConnectNavItem {
     items?: ConnectNavItem[];
     /**
      * Leave this route *outside* `ConnectAccessGate` - see
-     * `ConnectAppShellProps.gate`. Declared here, next to the route it applies
+     * `AppShellProps.gate`. Declared here, next to the route it applies
      * to, rather than as a second list somewhere else that has to be kept in
      * step with this one.
      */
     gateExempt?: boolean;
+    /**
+     * Who this route is for. Omit - the default - and it renders for everyone,
+     * which is what every route on an ordinary application is.
+     *
+     * - `"staff"` shows it only to a Connect platform staff session; your
+     *   operator console goes here.
+     * - `"member"` hides it *from* staff. Reach for it on anything that reads
+     *   the workspace - billing, plans, usage, team - since a staff session has
+     *   no workspace and those routes can only fail for it.
+     *
+     * Filtering here is presentation, not access: it decides which links a
+     * person sees, and a link is not a permission. The route itself must still
+     * check `staff` on your server - see `<ConnectPlatformGate>`.
+     */
+    audience?: "staff" | "member";
 }
 /** A titled group of items. Untitled groups render as a plain divider-free block. */
 export interface ConnectNavSection {
@@ -40,7 +55,7 @@ export interface ConnectNavSection {
     items: ConnectNavItem[];
 }
 /**
- * What `ConnectAppShell`/`ConnectSideNav` accept for `nav`: a flat list of
+ * What `AppShell`/`ConnectSideNav` accept for `nav`: a flat list of
  * items, a list of sections, or a mix. Consecutive bare items fold into one
  * untitled section, so the common case is just an array of items.
  */
@@ -106,5 +121,14 @@ export declare function resolveActivePath(pathname: string, nav: ConnectNav): st
  * lights up on every app's home route. External items are never active.
  */
 export declare function isNavItemActive(item: ConnectNavItem, activeHref: string | null): boolean;
-/** Hrefs declared `gateExempt` - the routes `ConnectAppShell` renders outside its `ConnectAccessGate`. */
+/**
+ * `nav` with every item the current session should not see removed - see
+ * `ConnectNavItem.audience`.
+ *
+ * Applied to nested `items` too, and a parent whose children all disappear is
+ * dropped along with them: a section header pointing at nothing reads as a
+ * broken link rather than as a hidden one.
+ */
+export declare function filterNavForAudience(nav: ConnectNav, isStaff: boolean): ConnectNav;
+/** Hrefs declared `gateExempt` - the routes `AppShell` renders outside its `ConnectAccessGate`. */
 export declare function gateExemptPaths(nav: ConnectNav): string[];

package/dist/types/client/components/plan-pricing.d.ts

@@ -24,6 +24,16 @@ export declare function formatPrice(paise: number): string;
  * plan reads as an upgrade over every monthly one.
  */
 export declare function monthlyOf(price: number, billingInterval: Plan["billingInterval"]): number;
+export declare function intervalLabel(billingInterval: Plan["billingInterval"]): {
+    per: string;
+    short: string;
+    adverb: string;
+};
+/**
+ * `/month`, `/year` - and nothing at all for a one-time plan, where a price
+ * with no slash is the honest rendering.
+ */
+export declare function pricePerLabel(billingInterval: Plan["billingInterval"]): string;
 export declare function discountLabel(discount: AppliedDiscount): string;
 /**
  * The minimum a plan-like object has to expose to be grouped or compared -

package/dist/types/client/components/platform-gate.d.ts

@@ -0,0 +1,53 @@
+import type { ReactNode } from "react";
+export interface ConnectPlatformGateProps {
+    /**
+     * Restrict to these platform roles. Omit to accept any staff session, which
+     * is the common case - your application already chose which roles it accepts
+     * when a platform admin turned staff access on for it, and repeating that
+     * list here is a second copy to keep in sync.
+     *
+     * Pass one only when your own console has tiers: a `developer` seeing the
+     * read-only half of what a `platform_admin` can edit.
+     */
+    roles?: string[];
+    children: ReactNode;
+    /**
+     * Rendered for an ordinary member session. Defaults to `null` - hiding the
+     * subtree, which is what this gate is normally for. An operator console is
+     * usually better hidden than explained.
+     */
+    fallback?: ReactNode;
+    /** Shown until the session read settles. Defaults to nothing. */
+    loading?: ReactNode;
+}
+/**
+ * Renders `children` only for a Connect platform staff session.
+ *
+ * ```tsx
+ * <ConnectPlatformGate>
+ *   <LinkMasterConsole />
+ * </ConnectPlatformGate>
+ * ```
+ *
+ * Staff are Connect's own operators - `platform_admin`, `platform_manager`,
+ * `developer` - signing into *your* application. They belong to no workspace,
+ * so a staff session carries no `workspaceId`, no subscription and no member
+ * role; see `SessionAccess.staff`. Staff access is off by default and turned on
+ * per application by a Connect platform admin, so this gate renders nothing
+ * until that happens.
+ *
+ * **This is a UX gate, not a security boundary** - the same caveat every gate
+ * in this package carries, and it matters more here than anywhere else,
+ * because what is behind this one is usually an operator console. The browser
+ * can ignore this component entirely. Every route it reveals must re-check
+ * `staff` on your own server:
+ *
+ * ```ts
+ * const { staff, role } = await client.identity.getUser(sessionToken);
+ * if (!staff) return forbidden();
+ * ```
+ *
+ * Renders `loading` - not `fallback` - while the session is unknown, so an
+ * operator never flickers through the customer layout on the way in.
+ */
+export declare function ConnectPlatformGate({ roles, children, fallback, loading, }: ConnectPlatformGateProps): import("react").JSX.Element;