@burdenoff/fe-libs 2026.1021.13 → 2026.1021.15

package/dist/platform-pages/AffiliatesPage.js

@@ -0,0 +1,583 @@
+import { resolveGatewayUrls as e } from "../shared/config/gatewayUrls.js";
+import "../shared-config.js";
+import { useAuth as t } from "../shared/providers/shell/AuthProvider.js";
+import { useAuthToken as n } from "../shared/providers/shell/AuthTokenProvider.js";
+import { useCallback as r, useEffect as i, useMemo as a, useReducer as o, useState as s } from "react";
+import { jsx as c, jsxs as l } from "react/jsx-runtime";
+//#region src/platform-pages/AffiliatesPage.tsx
+function u(e) {
+	return {
+		label: "",
+		productSlug: e,
+		destinationUrl: ""
+	};
+}
+var d = {
+	codes: [],
+	loading: !0,
+	error: null
+};
+function f(e, t) {
+	switch (t.type) {
+		case "load:start": return {
+			...e,
+			loading: !0,
+			error: null
+		};
+		case "load:success": return {
+			...e,
+			loading: !1,
+			codes: t.codes
+		};
+		case "error": return {
+			...e,
+			loading: !1,
+			error: t.message
+		};
+		case "error:clear": return {
+			...e,
+			error: null
+		};
+	}
+}
+var p = {
+	selectedCodeId: null,
+	analytics: null,
+	notes: []
+};
+function m(e, t) {
+	switch (t.type) {
+		case "select": return e.selectedCodeId === t.id ? e : {
+			selectedCodeId: t.id,
+			analytics: null,
+			notes: []
+		};
+		case "detail:loaded": return {
+			...e,
+			analytics: t.analytics,
+			notes: t.notes
+		};
+		case "notes:set": return {
+			...e,
+			notes: t.notes
+		};
+	}
+}
+async function h(e) {
+	let t = await fetch(e.url, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			...e.authToken ? { authorization: `Bearer ${e.authToken}` } : {},
+			...e.actorId ? {
+				"x-actor-id": e.actorId,
+				"x-actor-type": "user"
+			} : {}
+		},
+		body: JSON.stringify({
+			query: e.query,
+			variables: e.variables ?? {}
+		})
+	}), n = await t.json();
+	if (!t.ok || n.errors?.length || !n.data) throw Error(n.errors?.[0]?.message ?? "Request failed");
+	return n.data;
+}
+function g({ productSlug: g }) {
+	let { user: x } = t(), { accessToken: S } = n(), C = S ?? "", w = `${a(() => e(), []).globalBaseUrl}/global/graphql`, [T, E] = o(f, d), [D, O] = o(m, p), [k, A] = s(""), [j, M] = s(() => u(g)), { codes: N, loading: P, error: F } = T, { selectedCodeId: I, analytics: L, notes: R } = D, z = x?.id ?? "", B = r(async () => {
+		if (z) {
+			E({ type: "load:start" });
+			try {
+				E({
+					type: "load:success",
+					codes: (await h({
+						url: w,
+						authToken: C,
+						actorId: z,
+						query: "query MyAffiliateCodes {\n          myAffiliateCodes(limit: 50, offset: 0) {\n            items {\n              id code ownerUserId productSlug label description destinationUrl\n              isActive visits signups paidConversions storePurchases\n              revenueAmount rewardAmount createdAt\n            }\n            totalCount\n          }\n        }"
+					})).myAffiliateCodes.items
+				});
+			} catch (e) {
+				E({
+					type: "error",
+					message: e instanceof Error ? e.message : String(e)
+				});
+			}
+		}
+	}, [
+		w,
+		C,
+		z
+	]);
+	i(() => {
+		Promise.resolve().then(() => B());
+	}, [B]), i(() => {
+		!I || !z || Promise.all([h({
+			url: w,
+			authToken: C,
+			actorId: z,
+			query: "query CodeAnalytics($id: ID!) {\n          affiliateCodeAnalytics(id: $id) {\n            visits uniqueJourneys signups paidConversions storePurchases\n            revenueAmount rewardAmount conversionRate\n            topCountries { country visits conversions }\n            topModes { mode visits conversions }\n          }\n        }",
+			variables: { id: I }
+		}), h({
+			url: w,
+			authToken: C,
+			actorId: z,
+			query: "query CodeNotes($id: ID!) {\n          affiliateCode(id: $id) {\n            id\n            notes { id body authorType createdAt }\n          }\n        }",
+			variables: { id: I }
+		})]).then(([e, t]) => {
+			O({
+				type: "detail:loaded",
+				analytics: e.affiliateCodeAnalytics,
+				notes: t.affiliateCode?.notes ?? []
+			});
+		}).catch((e) => E({
+			type: "error",
+			message: e instanceof Error ? e.message : String(e)
+		}));
+	}, [
+		I,
+		w,
+		C,
+		z
+	]);
+	let V = r(async () => {
+		if (z) try {
+			await h({
+				url: w,
+				authToken: C,
+				actorId: z,
+				query: "mutation CreateCode($input: CreateAffiliateCodeInput!) {\n          createAffiliateCode(input: $input) { id code }\n        }",
+				variables: { input: j }
+			}), M(u(g)), await B();
+		} catch (e) {
+			E({
+				type: "error",
+				message: e instanceof Error ? e.message : String(e)
+			});
+		}
+	}, [
+		w,
+		C,
+		z,
+		j,
+		B,
+		g
+	]), H = r(async (e) => {
+		if (z) try {
+			await h({
+				url: w,
+				authToken: C,
+				actorId: z,
+				query: "mutation Regen($id: ID!) {\n            regenerateAffiliateCode(id: $id) { id code }\n          }",
+				variables: { id: e }
+			}), await B();
+		} catch (e) {
+			E({
+				type: "error",
+				message: e instanceof Error ? e.message : String(e)
+			});
+		}
+	}, [
+		w,
+		C,
+		z,
+		B
+	]), U = r(async (e) => {
+		if (z) try {
+			await h({
+				url: w,
+				authToken: C,
+				actorId: z,
+				query: "mutation Deactivate($id: ID!) {\n            deactivateAffiliateCode(id: $id) { id isActive }\n          }",
+				variables: { id: e }
+			}), await B();
+		} catch (e) {
+			E({
+				type: "error",
+				message: e instanceof Error ? e.message : String(e)
+			});
+		}
+	}, [
+		w,
+		C,
+		z,
+		B
+	]), W = r(async () => {
+		if (!(!z || !I || !k.trim())) try {
+			await h({
+				url: w,
+				authToken: C,
+				actorId: z,
+				query: "mutation AddNote($input: AddAffiliateCodeNoteInput!) {\n          addAffiliateCodeNote(input: $input) { id body createdAt }\n        }",
+				variables: { input: {
+					codeId: I,
+					body: k.trim()
+				} }
+			}), A(""), O({
+				type: "notes:set",
+				notes: (await h({
+					url: w,
+					authToken: C,
+					actorId: z,
+					query: "query CodeNotes($id: ID!) {\n          affiliateCode(id: $id) {\n            notes { id body authorType createdAt }\n          }\n        }",
+					variables: { id: I }
+				})).affiliateCode?.notes ?? []
+			});
+		} catch (e) {
+			E({
+				type: "error",
+				message: e instanceof Error ? e.message : String(e)
+			});
+		}
+	}, [
+		w,
+		C,
+		z,
+		I,
+		k
+	]), G = r((e) => {
+		O({
+			type: "select",
+			id: e
+		});
+	}, []);
+	return /* @__PURE__ */ l("div", {
+		className: "p-6 space-y-6",
+		children: [
+			/* @__PURE__ */ l("header", {
+				className: "flex items-center justify-between",
+				children: [/* @__PURE__ */ l("div", { children: [/* @__PURE__ */ c("h1", {
+					className: "text-2xl font-semibold text-foreground",
+					children: "Affiliates"
+				}), /* @__PURE__ */ c("p", {
+					className: "text-sm text-muted-foreground",
+					children: "Manage your referral codes, see clicks/conversions/earnings, add internal notes."
+				})] }), /* @__PURE__ */ c("button", {
+					type: "button",
+					onClick: () => void B(),
+					className: "rounded-md border border-border bg-card px-3 py-2 text-sm font-medium text-foreground",
+					children: "Refresh"
+				})]
+			}),
+			F ? /* @__PURE__ */ c("div", {
+				className: "rounded-lg border border-destructive bg-card p-3 text-sm text-destructive",
+				children: F
+			}) : null,
+			/* @__PURE__ */ c(_, {
+				form: j,
+				onChange: M,
+				onSubmit: () => void V()
+			}),
+			/* @__PURE__ */ c(v, {
+				loading: P,
+				codes: N,
+				selectedCodeId: I,
+				onSelect: G,
+				onRegenerate: (e) => void H(e),
+				onDeactivate: (e) => void U(e)
+			}),
+			I && L ? /* @__PURE__ */ c(y, { analytics: L }) : null,
+			I ? /* @__PURE__ */ c(b, {
+				notes: R,
+				newNote: k,
+				onNewNoteChange: A,
+				onSubmit: () => void W()
+			}) : null
+		]
+	});
+}
+function _(e) {
+	let { form: t, onChange: n, onSubmit: r } = e;
+	return /* @__PURE__ */ l("section", {
+		className: "rounded-lg border border-border bg-card p-4",
+		children: [
+			/* @__PURE__ */ c("h2", {
+				className: "mb-3 text-lg font-semibold text-foreground",
+				children: "Create new code"
+			}),
+			/* @__PURE__ */ l("div", {
+				className: "grid gap-3 md:grid-cols-3",
+				children: [
+					/* @__PURE__ */ c("input", {
+						"aria-label": "Label (e.g. Summer launch)",
+						value: t.label,
+						onChange: (e) => n({
+							...t,
+							label: e.target.value
+						}),
+						placeholder: "Label (e.g. Summer launch)",
+						className: "rounded-md border border-border bg-background px-3 py-2 text-sm"
+					}),
+					/* @__PURE__ */ c("input", {
+						"aria-label": "Product slug",
+						value: t.productSlug,
+						onChange: (e) => n({
+							...t,
+							productSlug: e.target.value
+						}),
+						placeholder: "Product slug",
+						className: "rounded-md border border-border bg-background px-3 py-2 text-sm"
+					}),
+					/* @__PURE__ */ c("input", {
+						"aria-label": "Destination URL",
+						value: t.destinationUrl,
+						onChange: (e) => n({
+							...t,
+							destinationUrl: e.target.value
+						}),
+						placeholder: "Destination URL",
+						className: "rounded-md border border-border bg-background px-3 py-2 text-sm"
+					})
+				]
+			}),
+			/* @__PURE__ */ c("button", {
+				type: "button",
+				onClick: r,
+				className: "mt-3 rounded-md border border-border bg-primary px-3 py-2 text-sm font-medium text-primary-foreground",
+				children: "Create code"
+			})
+		]
+	});
+}
+function v(e) {
+	let { loading: t, codes: n, selectedCodeId: r, onSelect: i, onRegenerate: a, onDeactivate: o } = e;
+	return /* @__PURE__ */ l("section", {
+		className: "rounded-lg border border-border bg-card p-4",
+		children: [/* @__PURE__ */ c("h2", {
+			className: "mb-3 text-lg font-semibold text-foreground",
+			children: "My codes"
+		}), t ? /* @__PURE__ */ c("p", {
+			className: "text-sm text-muted-foreground",
+			children: "Loading…"
+		}) : n.length === 0 ? /* @__PURE__ */ c("p", {
+			className: "text-sm text-muted-foreground",
+			children: "No codes yet. Create one above."
+		}) : /* @__PURE__ */ l("table", {
+			className: "min-w-full text-sm",
+			children: [/* @__PURE__ */ c("thead", {
+				className: "text-left text-muted-foreground",
+				children: /* @__PURE__ */ l("tr", {
+					className: "border-b border-border",
+					children: [
+						/* @__PURE__ */ c("th", {
+							className: "px-3 py-2",
+							children: "Code"
+						}),
+						/* @__PURE__ */ c("th", {
+							className: "px-3 py-2",
+							children: "Label"
+						}),
+						/* @__PURE__ */ c("th", {
+							className: "px-3 py-2",
+							children: "Product"
+						}),
+						/* @__PURE__ */ c("th", {
+							className: "px-3 py-2",
+							children: "Visits"
+						}),
+						/* @__PURE__ */ c("th", {
+							className: "px-3 py-2",
+							children: "Conversions"
+						}),
+						/* @__PURE__ */ c("th", {
+							className: "px-3 py-2",
+							children: "Reward"
+						}),
+						/* @__PURE__ */ c("th", {
+							className: "px-3 py-2",
+							children: "Status"
+						}),
+						/* @__PURE__ */ c("th", {
+							className: "px-3 py-2",
+							children: "Actions"
+						})
+					]
+				})
+			}), /* @__PURE__ */ c("tbody", { children: n.map((e) => /* @__PURE__ */ l("tr", {
+				className: `cursor-pointer border-b border-border/70 ${r === e.id ? "bg-muted/40" : ""}`,
+				onClick: () => i(e.id),
+				children: [
+					/* @__PURE__ */ c("td", {
+						className: "px-3 py-2 font-mono text-foreground",
+						children: e.code
+					}),
+					/* @__PURE__ */ c("td", {
+						className: "px-3 py-2",
+						children: e.label ?? "—"
+					}),
+					/* @__PURE__ */ c("td", {
+						className: "px-3 py-2",
+						children: e.productSlug ?? "—"
+					}),
+					/* @__PURE__ */ c("td", {
+						className: "px-3 py-2",
+						children: e.visits
+					}),
+					/* @__PURE__ */ c("td", {
+						className: "px-3 py-2",
+						children: e.paidConversions + e.storePurchases
+					}),
+					/* @__PURE__ */ c("td", {
+						className: "px-3 py-2",
+						children: e.rewardAmount.toFixed(2)
+					}),
+					/* @__PURE__ */ c("td", {
+						className: "px-3 py-2",
+						children: e.isActive ? "Active" : "Inactive"
+					}),
+					/* @__PURE__ */ l("td", {
+						className: "px-3 py-2",
+						children: [/* @__PURE__ */ c("button", {
+							type: "button",
+							onClick: (t) => {
+								t.stopPropagation(), a(e.id);
+							},
+							className: "mr-2 rounded border border-border px-2 py-1 text-xs",
+							children: "Regenerate"
+						}), e.isActive ? /* @__PURE__ */ c("button", {
+							type: "button",
+							onClick: (t) => {
+								t.stopPropagation(), o(e.id);
+							},
+							className: "rounded border border-border px-2 py-1 text-xs",
+							children: "Deactivate"
+						}) : null]
+					})
+				]
+			}, e.id)) })]
+		})]
+	});
+}
+function y({ analytics: e }) {
+	return /* @__PURE__ */ l("section", {
+		className: "rounded-lg border border-border bg-card p-4",
+		children: [
+			/* @__PURE__ */ c("h2", {
+				className: "mb-3 text-lg font-semibold text-foreground",
+				children: "Analytics"
+			}),
+			/* @__PURE__ */ l("div", {
+				className: "grid gap-3 md:grid-cols-4",
+				children: [
+					/* @__PURE__ */ c(x, {
+						label: "Visits",
+						value: e.visits
+					}),
+					/* @__PURE__ */ c(x, {
+						label: "Unique journeys",
+						value: e.uniqueJourneys
+					}),
+					/* @__PURE__ */ c(x, {
+						label: "Signups",
+						value: e.signups
+					}),
+					/* @__PURE__ */ c(x, {
+						label: "Conversion rate",
+						value: `${(e.conversionRate * 100).toFixed(1)}%`
+					}),
+					/* @__PURE__ */ c(x, {
+						label: "Paid",
+						value: e.paidConversions
+					}),
+					/* @__PURE__ */ c(x, {
+						label: "Store",
+						value: e.storePurchases
+					}),
+					/* @__PURE__ */ c(x, {
+						label: "Revenue",
+						value: e.revenueAmount.toFixed(2)
+					}),
+					/* @__PURE__ */ c(x, {
+						label: "Reward",
+						value: e.rewardAmount.toFixed(2)
+					})
+				]
+			}),
+			/* @__PURE__ */ l("div", {
+				className: "mt-4 grid gap-3 md:grid-cols-2",
+				children: [/* @__PURE__ */ l("div", { children: [/* @__PURE__ */ c("h3", {
+					className: "mb-2 text-sm font-medium text-foreground",
+					children: "Top countries"
+				}), e.topCountries.length ? /* @__PURE__ */ c("ul", {
+					className: "space-y-1 text-sm",
+					children: e.topCountries.map((e) => /* @__PURE__ */ l("li", {
+						className: "flex justify-between",
+						children: [/* @__PURE__ */ c("span", { children: e.country }), /* @__PURE__ */ c("span", { children: e.visits })]
+					}, e.country))
+				}) : /* @__PURE__ */ c("p", {
+					className: "text-sm text-muted-foreground",
+					children: "No data"
+				})] }), /* @__PURE__ */ l("div", { children: [/* @__PURE__ */ c("h3", {
+					className: "mb-2 text-sm font-medium text-foreground",
+					children: "Top modes"
+				}), e.topModes.length ? /* @__PURE__ */ c("ul", {
+					className: "space-y-1 text-sm",
+					children: e.topModes.map((e) => /* @__PURE__ */ l("li", {
+						className: "flex justify-between",
+						children: [/* @__PURE__ */ c("span", { children: e.mode }), /* @__PURE__ */ c("span", { children: e.visits })]
+					}, e.mode))
+				}) : /* @__PURE__ */ c("p", {
+					className: "text-sm text-muted-foreground",
+					children: "No data"
+				})] })]
+			})
+		]
+	});
+}
+function b(e) {
+	let { notes: t, newNote: n, onNewNoteChange: r, onSubmit: i } = e;
+	return /* @__PURE__ */ l("section", {
+		className: "rounded-lg border border-border bg-card p-4",
+		children: [
+			/* @__PURE__ */ c("h2", {
+				className: "mb-3 text-lg font-semibold text-foreground",
+				children: "Internal notes"
+			}),
+			/* @__PURE__ */ l("div", {
+				className: "flex items-center gap-2",
+				children: [/* @__PURE__ */ c("input", {
+					"aria-label": "Note for this code",
+					value: n,
+					onChange: (e) => r(e.target.value),
+					placeholder: "Add a note for this code…",
+					className: "flex-1 rounded-md border border-border bg-background px-3 py-2 text-sm"
+				}), /* @__PURE__ */ c("button", {
+					type: "button",
+					onClick: i,
+					className: "rounded-md border border-border bg-primary px-3 py-2 text-sm font-medium text-primary-foreground",
+					children: "Add"
+				})]
+			}),
+			/* @__PURE__ */ l("ul", {
+				className: "mt-4 space-y-2",
+				children: [t.map((e) => /* @__PURE__ */ l("li", {
+					className: "rounded-md border border-border bg-background p-2 text-sm",
+					children: [/* @__PURE__ */ l("div", {
+						className: "text-xs text-muted-foreground",
+						children: [
+							e.authorType,
+							" · ",
+							new Date(e.createdAt).toLocaleString()
+						]
+					}), /* @__PURE__ */ c("div", { children: e.body })]
+				}, e.id)), t.length === 0 ? /* @__PURE__ */ c("li", {
+					className: "text-sm text-muted-foreground",
+					children: "No notes yet."
+				}) : null]
+			})
+		]
+	});
+}
+function x({ label: e, value: t }) {
+	return /* @__PURE__ */ l("div", {
+		className: "rounded-md border border-border bg-background p-3",
+		children: [/* @__PURE__ */ c("p", {
+			className: "text-xs text-muted-foreground",
+			children: e
+		}), /* @__PURE__ */ c("p", {
+			className: "text-lg font-semibold text-foreground",
+			children: t
+		})]
+	});
+}
+//#endregion
+export { g as AffiliatesPage };

package/dist/platform-pages/AppearanceSettingsPage.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Appearance / Theme Preferences page.
+ *
+ * Thin wrapper around the shared Boff UI 2.0 `ThemePreferences` customizer
+ * (fe-libs/chrome). It exposes the full system: the six built-in themes,
+ * per-product accent, density, typography, glass intensity, reduced motion,
+ * and user-designed CUSTOM themes (create / save / apply / delete) — all wired
+ * straight to the fe-libs ThemeProvider and persisted, with a live preview.
+ *
+ * Shared by every app shell (`@burdenoff/fe-libs/platform-pages`); mount it at
+ * `/settings/appearance`. It is purely client-side, so it needs no gateway.
+ */
+export declare function AppearanceSettingsPage(): import('react/jsx-runtime').JSX.Element;
+export default AppearanceSettingsPage;

package/dist/platform-pages/AppearanceSettingsPage.js

@@ -0,0 +1,14 @@
+import { ThemePreferences as e } from "../chrome/ThemePreferences.js";
+import { jsx as t } from "react/jsx-runtime";
+//#region src/platform-pages/AppearanceSettingsPage.tsx
+function n() {
+	return /* @__PURE__ */ t("div", {
+		className: "min-h-full bg-bg-canvas",
+		children: /* @__PURE__ */ t("div", {
+			className: "mx-auto w-full max-w-6xl px-4 py-6 md:px-6 lg:px-8",
+			children: /* @__PURE__ */ t(e, {})
+		})
+	});
+}
+//#endregion
+export { n as default };

package/dist/platform-pages/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @burdenoff/fe-libs/platform-pages
+ *
+ * Platform pages that every app shell mounts at the same paths. They used to be
+ * copied into each shell (vibecontrols-app first), so the copies drifted; the
+ * shells now import them from here.
+ *
+ * | Page                     | Path                     | Mount                          |
+ * |--------------------------|--------------------------|--------------------------------|
+ * | `AppearanceSettingsPage` | `/settings/appearance`   | protected, no gateway          |
+ * | `AffiliatesPage`         | `/affiliates`            | protected (global gateway URL) |
+ * | `AcceptShareRoute`       | `/share/accept/:token`   | protected (workspace gateway)  |
+ *
+ * `AdminOverviewPage` (`/admin/overview`) lives in
+ * `@burdenoff/fe-libs/admin-overview` because it needs the optional
+ * `@xyflow/react` peer.
+ */
+export { AppearanceSettingsPage } from './AppearanceSettingsPage';
+export { AffiliatesPage, type AffiliatesPageProps } from './AffiliatesPage';
+export { AcceptShareRoute, resolveAcceptedShareDestination, type AcceptShareRouteProps, } from './AcceptShareRoute';

package/dist/platform-pages.d.ts

@@ -0,0 +1,2 @@
+export * from './platform-pages/index.js'
+export {}

package/dist/platform-pages.js

@@ -0,0 +1,4 @@
+import e from "./platform-pages/AppearanceSettingsPage.js";
+import { AffiliatesPage as t } from "./platform-pages/AffiliatesPage.js";
+import { AcceptShareRoute as n, resolveAcceptedShareDestination as r } from "./platform-pages/AcceptShareRoute.js";
+export { n as AcceptShareRoute, t as AffiliatesPage, e as AppearanceSettingsPage, r as resolveAcceptedShareDestination };

package/dist/shared/components/DocsLink.d.ts

@@ -0,0 +1,56 @@
+import { AnchorHTMLAttributes, ReactNode } from 'react';
+import { DocsEnvironment } from '../config/docsUrls';
+export declare const PUBLIC_PRODUCT_DOCS_URL_QUERY: import('graphql').DocumentNode;
+/** Minimal client surface the registry lookup needs (an ApolloClient satisfies it). */
+export interface DocsRegistryClient {
+    query: (options: {
+        query: typeof PUBLIC_PRODUCT_DOCS_URL_QUERY;
+        variables: {
+            slug: string;
+        };
+        fetchPolicy: 'cache-first';
+    }) => Promise<{
+        data?: unknown;
+    }>;
+}
+/** Read `publicProduct.docsUrl` out of a query result, trusted origins only. */
+export declare function readRegistryDocsUrl(data: unknown): string | null;
+/** The cached registry docsUrl for a slug: string, `null` (none), or undefined (not fetched). */
+export declare function getCachedRegistryDocsUrl(productSlug: string): string | null | undefined;
+/**
+ * Look up the registry docsUrl once per slug. Failures resolve to `null` (the
+ * catalog default stays in use) and are not cached, so a later mount retries.
+ */
+export declare function fetchRegistryDocsUrl(client: DocsRegistryClient, productSlug: string): Promise<string | null>;
+/** Test seam: forget every cached registry answer. */
+export declare function resetRegistryDocsUrlCache(): void;
+export interface UseProductDocsOptions {
+    /** Another product's docs instead of the running shell's. */
+    productSlug?: string;
+    /** Skip the registry lookup and use the static catalog default only. */
+    registry?: boolean;
+    /** Override the detected environment (tests, previews). */
+    environment?: DocsEnvironment;
+}
+/**
+ * The environment-correct docs origin for the running shell's product, e.g.
+ * `https://docs.vibecontrols.com` or `https://alphadocs.vibecontrols.com`.
+ */
+export declare function useProductDocsOrigin(options?: UseProductDocsOptions): string | undefined;
+/**
+ * The environment-correct docs URL for a page of the running shell's product.
+ * `path` is site-relative (`/users/workflows`); undefined when it is not, or
+ * when the product has no trusted docs host.
+ */
+export declare function useProductDocsUrl(path?: string, options?: UseProductDocsOptions): string | undefined;
+export interface DocsLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'target' | 'rel'>, UseProductDocsOptions {
+    /** Site-relative docs path, e.g. `/users/workflows`. Defaults to the docs home. */
+    path?: string;
+    children: ReactNode;
+}
+/**
+ * A new-tab link to the product's docs for the current environment. Renders
+ * its children without a link when no trusted docs URL resolves, so a page
+ * never shows a dead "Learn more".
+ */
+export declare function DocsLink({ path, productSlug, registry, environment, children, ...anchorProps }: DocsLinkProps): import('react/jsx-runtime').JSX.Element;