@cosmoops/connect-sdk 0.9.0 → 0.16.0

package/dist/cjs/store.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.increment = increment;
+exports.serverTimestamp = serverTimestamp;
+exports.arrayUnion = arrayUnion;
+exports.arrayRemove = arrayRemove;
+exports.deleteField = deleteField;
+exports.unchangedSince = unchangedSince;
+exports.documentExists = documentExists;
+exports.storeIndexFor = storeIndexFor;
+exports.storeIndexSignature = storeIndexSignature;
+/**
+ * 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`.
+ */
+function increment(by) {
+    return { __transform: "increment", by };
+}
+/** Connect's own write time, rather than a clock reading from your process. */
+function serverTimestamp() {
+    return { __transform: "serverTimestamp" };
+}
+/** Adds the values not already in the array. Order is not preserved. */
+function arrayUnion(...values) {
+    return { __transform: "arrayUnion", values };
+}
+/** Removes every occurrence of each value. */
+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.
+ */
+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.
+ */
+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." */
+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.
+ */
+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.
+ */
+function storeIndexSignature(fields) {
+    return fields.map((entry) => `${entry.field}:${entry.direction}`).join(",");
+}

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

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectEmptyState = ConnectEmptyState;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("@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.
+ */
+function ConnectEmptyState({ icon, title, description, action, variant = "card", className, }) {
+    const body = ((0, jsx_runtime_1.jsxs)("div", { className: "flex flex-col items-center text-center", children: [icon && ((0, jsx_runtime_1.jsx)("span", { "aria-hidden": true, className: "mb-3 text-muted [&>svg]:size-8", children: icon })), (0, jsx_runtime_1.jsx)("p", { className: "text-sm font-medium text-foreground", children: title }), description && (0, jsx_runtime_1.jsx)("p", { className: "mt-1 max-w-md text-sm text-muted", children: description }), action && (0, jsx_runtime_1.jsx)("div", { className: "mt-3", children: action })] }));
+    if (variant === "plain")
+        return (0, jsx_runtime_1.jsx)("div", { className: className, children: body });
+    return ((0, jsx_runtime_1.jsx)(react_1.Card, { className: `p-5 sm:p-8 ${variant === "dashed" ? "border-dashed" : ""} ${className ?? ""}`, children: body }));
+}

package/dist/cjs/ui/index.js

@@ -0,0 +1,44 @@
+"use client";
+"use strict";
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectStatusChip = exports.ConnectSettingRow = exports.ConnectEmptyState = exports.ConnectSection = exports.ConnectPageHeader = exports.ConnectPageShell = void 0;
+var page_shell_js_1 = require("./page-shell.js");
+Object.defineProperty(exports, "ConnectPageShell", { enumerable: true, get: function () { return page_shell_js_1.ConnectPageShell; } });
+var page_header_js_1 = require("./page-header.js");
+Object.defineProperty(exports, "ConnectPageHeader", { enumerable: true, get: function () { return page_header_js_1.ConnectPageHeader; } });
+var section_js_1 = require("./section.js");
+Object.defineProperty(exports, "ConnectSection", { enumerable: true, get: function () { return section_js_1.ConnectSection; } });
+var empty_state_js_1 = require("./empty-state.js");
+Object.defineProperty(exports, "ConnectEmptyState", { enumerable: true, get: function () { return empty_state_js_1.ConnectEmptyState; } });
+var setting_row_js_1 = require("./setting-row.js");
+Object.defineProperty(exports, "ConnectSettingRow", { enumerable: true, get: function () { return setting_row_js_1.ConnectSettingRow; } });
+var status_chip_js_1 = require("./status-chip.js");
+Object.defineProperty(exports, "ConnectStatusChip", { enumerable: true, get: function () { return status_chip_js_1.ConnectStatusChip; } });

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

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectPageHeader = ConnectPageHeader;
+const jsx_runtime_1 = require("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`.
+ */
+function ConnectPageHeader({ title, description, action, clamp = true, className, }) {
+    return ((0, jsx_runtime_1.jsxs)("header", { className: `flex items-start justify-between gap-3 ${className ?? ""}`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "min-w-0 flex-1", children: [(0, jsx_runtime_1.jsx)("h2", { className: "flex items-center gap-2 text-lg font-semibold", children: title }), description && ((0, jsx_runtime_1.jsx)("p", { className: `mt-2 text-sm text-muted ${clamp ? "line-clamp-2 sm:line-clamp-none" : ""}`, children: description }))] }), action && (0, jsx_runtime_1.jsx)("div", { className: "shrink-0", children: action })] }));
+}

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

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectPageShell = ConnectPageShell;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const page_header_js_1 = require("./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.
+ */
+function ConnectPageShell({ title, description, action, clamp, above, children, }) {
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "space-y-5", children: [above, title !== undefined && ((0, jsx_runtime_1.jsx)(page_header_js_1.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 = page_header_js_1.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 (0, jsx_runtime_1.jsx)(react_1.Suspense, { fallback: fallback, children: children });
+};

package/dist/cjs/ui/section.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectSection = ConnectSection;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("@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.
+ */
+function ConnectSection({ title, description, action, titleId, className, bodyClassName, children, }) {
+    return ((0, jsx_runtime_1.jsxs)(react_1.Card, { className: className ?? "p-4 sm:p-5", children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex flex-wrap items-start justify-between gap-3", children: [(0, jsx_runtime_1.jsxs)("div", { className: "min-w-0 flex-1", children: [(0, jsx_runtime_1.jsx)("h3", { id: titleId, className: "text-base font-semibold", children: title }), description && (0, jsx_runtime_1.jsx)("p", { className: "mt-1 text-sm text-muted", children: description })] }), action && (0, jsx_runtime_1.jsx)("div", { className: "shrink-0", children: action })] }), children && (0, jsx_runtime_1.jsx)("div", { className: bodyClassName ?? "mt-4 space-y-4", children: children })] }));
+}

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

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectSettingRow = ConnectSettingRow;
+const jsx_runtime_1 = require("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.
+ */
+function ConnectSettingRow({ title, description, action, children, className, }) {
+    return ((0, jsx_runtime_1.jsxs)("div", { className: `flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between ${className ?? ""}`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "min-w-0 flex-1", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-sm font-medium text-foreground", children: title }), description && (0, jsx_runtime_1.jsx)("p", { className: "mt-1 text-sm text-muted", children: description }), children && (0, jsx_runtime_1.jsx)("div", { className: "mt-3", children: children })] }), action && (0, jsx_runtime_1.jsx)("div", { className: "shrink-0 sm:pl-4", children: action })] }));
+}

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

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectStatusChip = ConnectStatusChip;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("@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.
+ */
+function ConnectStatusChip({ status, presentation, className, }) {
+    return ((0, jsx_runtime_1.jsx)(react_1.Chip, { color: presentation.tone[status], size: "sm", variant: "soft", className: className, children: presentation.label[status] }));
+}

package/dist/esm/cli/doctor.js

@@ -159,8 +159,8 @@ function checkEnv(root) {
             status: "fail",
             title: `${name} set`,
             detail: declaredEmpty
-                ? `Declared but empty in .env.local. The value is in your application's Integration tab in Connect.`
-                : `Not found in .env.local or the environment. Both values are in your application's Integration tab in Connect.`,
+                ? `Declared but empty in .env.local. The value is in your application's Connect client section in Connect.`
+                : `Not found in .env.local or the environment. Both values are in your application's Connect client section in Connect.`,
         };
     });
 }
@@ -173,7 +173,7 @@ function checkRedirectUri() {
     return {
         status: "warn",
         title: "Redirect URI registered in Connect",
-        detail: "Not checkable from here. Confirm {your origin}/api/connect/callback is listed as a redirect URI in your application's Integration tab - including the deployed origin, not just http://localhost:3000.",
+        detail: "Not checkable from here. Confirm {your origin}/api/connect/callback is listed as a redirect URI in your application's Connect client section - including the deployed origin, not just http://localhost:3000.",
     };
 }
 const MARKER = { pass: "  ok  ", warn: " note ", fail: " FAIL " };

package/dist/esm/cli/init.js

@@ -39,7 +39,7 @@ const PLANS_PAGE = `"use client";
 // with the other exports) whenever you want your own copy or layout.
 export { ConnectPlansPage as default } from "@cosmoops/connect-sdk/client";
 `;
-const ENV_TEMPLATE = `# CosmoOps Connect - values come from your application's Integration tab.
+const ENV_TEMPLATE = `# CosmoOps Connect - values come from your application's Connect client section.
 CONNECT_API_KEY=
 CONNECT_CLIENT_ID=
 `;
@@ -106,7 +106,7 @@ export function runInit(argv = []) {
         console.log(`  ${marker}  ${relative(root, target)}  - ${scaffold.description}`);
     }
     const env = ensureEnv(root);
-    console.log(`  ${env === "skipped" ? "exists " : env === "appended" ? "updated" : "created"}  .env.local  - fill in the two values from your application's Integration tab`);
+    console.log(`  ${env === "skipped" ? "exists " : env === "appended" ? "updated" : "created"}  .env.local  - fill in the two values from your application's Connect client section`);
     // The two steps a scaffolder must not do for you: editing an existing layout
     // means parsing and rewriting JSX someone else wrote, and the redirect URI
     // lives in Connect, not in this repo.
@@ -132,7 +132,7 @@ Three things left, all one-time:
      Tailwind roots its content scan inside node_modules and skips your app.
 
   3. Register {your origin}/api/connect/callback as a redirect URI in your
-     application's Integration tab in Connect.
+     application's Connect client section in Connect.
 
 No next.config.ts changes needed - not even transpilePackages: dist/ is
 already ES2022 with "use client" hoisted, so Turbopack and webpack consume it

package/dist/esm/client/components/access-gate.js

@@ -36,12 +36,31 @@ function formatDate(iso) {
 export function useConnectAccessGate() {
     const { session, isLoading: sessionLoading } = useConnect();
     const { data, isLoading: entitlementsLoading } = useConnectEntitlements();
-    if (sessionLoading || (session?.user && entitlementsLoading)) {
+    if (sessionLoading) {
         return { state: "loading", blocker: null, paymentRetry: null };
     }
     if (!session?.user) {
         return { state: "signed_out", blocker: null, paymentRetry: null };
     }
+    // Connect platform staff pass straight through, and this check has to come
+    // *before* the entitlements read below or the gate would hard-block them.
+    //
+    // Every state this gate can report is a fact about a workspace - suspended,
+    // no plan, wrong audience, awaiting approval, payment due. A staff session
+    // has no workspace at all (see `SessionAccess.staff`), so it has no subscription
+    // either, and `subscription_missing` would send an operator to your plan
+    // picker to buy a plan for a workspace that does not exist. "Nothing is
+    // blocking this session" is the truthful answer, not a lenient one.
+    //
+    // The entitlements request is still issued - hooks cannot be called
+    // conditionally - and the bridge answers it `403 no_workspace`. That costs
+    // one failed request per staff page load, and its result is ignored here.
+    if (session.staff) {
+        return { state: "clear", blocker: null, paymentRetry: null };
+    }
+    if (entitlementsLoading) {
+        return { state: "loading", blocker: null, paymentRetry: null };
+    }
     if (!data) {
         // Signed in, not loading, yet nothing came back - a failed read (see
         // `error` on `useConnectEntitlements`). Fail open rather than hard-block

package/dist/esm/client/components/ai-screens.js

@@ -0,0 +1,69 @@
+/**
+ * Matching a live path against the screens your application declared.
+ *
+ * The same rule Connect uses for its own routes, and it has to be here too
+ * because only this side knows what your app's routes are: a dynamic segment
+ * matches exactly one path segment, and where several patterns fit, the most
+ * *literal* wins - so `/deals/new` resolves to itself rather than to
+ * `/deals/[dealId]` merely because that also fits.
+ *
+ * Plain functions with no React and no imports beyond the type, so the panel,
+ * the action links and any host that wants to reuse the matching can share one
+ * implementation.
+ */
+/** Trims the query string, the hash and any trailing slash. */
+function normalise(path) {
+    const withoutQuery = path.split(/[?#]/)[0] ?? "";
+    return withoutQuery.length > 1 ? withoutQuery.replace(/\/+$/, "") : withoutQuery;
+}
+/**
+ * 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 function matchConnectScreen(screens, path) {
+    const segments = normalise(path).split("/").filter(Boolean);
+    let best = null;
+    for (const screen of screens) {
+        const pattern = normalise(screen.path).split("/").filter(Boolean);
+        if (pattern.length !== segments.length)
+            continue;
+        let literals = 0;
+        let matches = true;
+        for (let i = 0; i < pattern.length; i++) {
+            const part = pattern[i];
+            if (part.startsWith("[") && part.endsWith("]"))
+                continue;
+            if (part !== segments[i]) {
+                matches = false;
+                break;
+            }
+            literals++;
+        }
+        if (matches && (!best || literals > best.literals))
+            best = { screen, literals };
+    }
+    return best?.screen ?? 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 function isLinkableConnectScreen(screens, href) {
+    if (!href.startsWith("/") || href.startsWith("//"))
+        return false;
+    return matchConnectScreen(screens, href) !== null;
+}

package/dist/esm/client/components/ai-widgets.js

@@ -1,8 +1,9 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useMemo, useState } from "react";
+import { Fragment, useMemo, useState } from "react";
 import { Button } from "@heroui/react";
 import { ArrowDown, ArrowUp, ChevronsUpDown, Download, ExternalLink, FileText, Minus, TrendingDown, TrendingUp } from "lucide-react";
+import { isLinkableConnectScreen } from "./ai-screens.js";
 import { AI_EMPTY_VALUE, AI_TONE_CHIP, AI_TONE_DOT, aiStatusTone, formatAiValue, isNumericAiFormat, } from "./ai-format.js";
 /**
  * What Ask AI draws.
@@ -221,3 +222,38 @@ export function AiSources({ sources }) {
                     return (_jsx("li", { children: source.uri ? (_jsxs("a", { href: source.uri, target: "_blank", rel: "noopener noreferrer", className: "flex gap-1.5 rounded-sm hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus", children: [label, _jsx(ExternalLink, { className: "mt-0.5 size-3 shrink-0 text-muted", "aria-hidden": true })] })) : (_jsx("span", { className: "flex gap-1.5", children: label })) }, `${source.uri ?? source.title}-${index}`));
                 }) })] }));
 }
+/**
+ * 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 function AiActions({ title, actions, screens, renderLink, }) {
+    const resolved = actions.filter((action) => isLinkableConnectScreen(screens, action.href));
+    if (resolved.length === 0)
+        return null;
+    const className = "group flex items-center gap-2 rounded-lg border border-separator bg-surface px-3 py-2 no-underline transition-colors hover:border-accent";
+    return (_jsxs("div", { className: "my-3", children: [title ? _jsx("p", { className: "mb-1.5 text-xs font-medium text-muted", children: title }) : null, _jsx("div", { className: "flex flex-col gap-1.5", children: resolved.map((action) => {
+                    const body = (_jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-xs font-medium text-foreground", children: action.label }), action.detail ? (_jsx("span", { className: "block truncate text-[11px] text-muted", children: action.detail })) : null] }));
+                    return (_jsx(Fragment, { children: renderLink ? (renderLink({ href: action.href, className, children: body })) : (_jsx("a", { href: action.href, className: className, children: body })) }, action.href));
+                }) })] }));
+}