@burdenoff/fe-libs 2026.1021.12 → 2026.1021.14

package/dist/shared/assistant/pageContextKeys.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The page-context keys the assistant sandbox actually reads, and the host-side
+ * filter that keeps every other key in the browser (G52, PR-AI-03 / BOFF-3908).
+ *
+ * The sandbox (`ai-assistant`) reads `pageContext` in exactly two places:
+ *
+ * - `src/context-loader.ts` `ALLOWED_CONTEXT_KEYS` — the keys `injectPageContext`
+ *   writes into the session for the model. Any other key is skipped there.
+ * - `src/context-redaction.ts` `CONTEXT_ID_KEYS` — the opaque ids whose values
+ *   are redacted from the assistant's replies. `organizationId` is on this list
+ *   but NOT the first, so it must still be forwarded: dropping it would stop the
+ *   sandbox from redacting an organisation id the model learnt from a tool call.
+ *
+ * Both lists are private Sets in that repo, and ai-assistant cannot import
+ * fe-libs, so they are mirrored here and pinned by a drift test against
+ * `__fixtures__/aiAssistantContextKeys.json`, which
+ * `scripts/assistant-context-keys/vendor.ts` cuts from an ai-assistant checkout
+ * (it records the commit and each source file's SHA-256). Re-vendor, then
+ * update these lists, whenever either Set changes.
+ *
+ * The filter is defence in depth: the sandbox already drops unknown keys before
+ * the model sees them, so this changes nothing the model receives. It stops the
+ * browser from sending data nobody reads (the user agent, a timestamp, anything
+ * a product adds by accident) through the gateway and the sandbox proxy.
+ */
+/** Mirror of ai-assistant `ALLOWED_CONTEXT_KEYS`: the keys the model is shown. */
+export declare const ASSISTANT_MODEL_CONTEXT_KEYS: readonly ["currentUrl", "currentPage", "entityType", "entityId", "entityName", "pageTitle", "pageType", "activeTab", "activeTool", "selectedText", "workspaceId", "workspaceName", "projectId", "projectName", "platform", "version", "viewportSize", "vibeId", "vibeName", "vibePath", "sessionId", "sessionName", "agentId", "agentName"];
+/** Mirror of ai-assistant `CONTEXT_ID_KEYS`: the ids redacted from replies. */
+export declare const ASSISTANT_REDACTED_CONTEXT_ID_KEYS: readonly ["workspaceId", "organizationId", "projectId", "entityId", "vibeId", "sessionId", "agentId"];
+export type AssistantPageContextKey = (typeof ASSISTANT_MODEL_CONTEXT_KEYS)[number] | (typeof ASSISTANT_REDACTED_CONTEXT_ID_KEYS)[number];
+/**
+ * Every key a host may send in `pageContext`: the union of the two server
+ * lists, in a stable order (model keys first, then the redaction-only ones).
+ */
+export declare const ASSISTANT_PAGE_CONTEXT_KEYS: readonly AssistantPageContextKey[];
+/** Whether the sandbox reads `key` from `pageContext`. */
+export declare function isAssistantPageContextKey(key: string): key is AssistantPageContextKey;
+/**
+ * The part of a host's page context that goes on the wire: only allow-listed
+ * keys, with their values untouched. `undefined` stays `undefined`, so a turn
+ * with no context still produces the body it always did; a context with no
+ * allow-listed key becomes `{}`, which the sandbox treats as "no context".
+ *
+ * Own enumerable keys only — an inherited or prototype key is never forwarded.
+ */
+export declare function filterAssistantPageContext(pageContext: Readonly<Record<string, unknown>> | undefined): Record<string, unknown> | undefined;

package/dist/shared/assistant/pageContextKeys.js

@@ -0,0 +1,46 @@
+//#region src/shared/assistant/pageContextKeys.ts
+var e = [
+	"currentUrl",
+	"currentPage",
+	"entityType",
+	"entityId",
+	"entityName",
+	"pageTitle",
+	"pageType",
+	"activeTab",
+	"activeTool",
+	"selectedText",
+	"workspaceId",
+	"workspaceName",
+	"projectId",
+	"projectName",
+	"platform",
+	"version",
+	"viewportSize",
+	"vibeId",
+	"vibeName",
+	"vibePath",
+	"sessionId",
+	"sessionName",
+	"agentId",
+	"agentName"
+], t = [
+	"workspaceId",
+	"organizationId",
+	"projectId",
+	"entityId",
+	"vibeId",
+	"sessionId",
+	"agentId"
+], n = Object.freeze(Array.from(new Set([...e, ...t]))), r = new Set(n);
+function i(e) {
+	return r.has(e);
+}
+function a(e) {
+	if (e === void 0) return;
+	let t = {};
+	for (let [n, i] of Object.entries(e)) r.has(n) && (t[n] = i);
+	return t;
+}
+//#endregion
+export { e as ASSISTANT_MODEL_CONTEXT_KEYS, n as ASSISTANT_PAGE_CONTEXT_KEYS, t as ASSISTANT_REDACTED_CONTEXT_ID_KEYS, a as filterAssistantPageContext, i as isAssistantPageContextKey };

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;

package/dist/shared/components/DocsLink.js

@@ -0,0 +1,97 @@
+import { normalizeProductSlug as e } from "../config/productSlug.js";
+import { buildProductDocsUrl as t, resolveProductDocsOrigin as n, toTrustedDocsOrigin as r } from "../config/docsUrls.js";
+import { useSafeGateway as i } from "../graphql/GatewayContext.js";
+import { useAppShell as a } from "../providers/shell/AppShellContext.js";
+import { useEffect as o, useState as s } from "react";
+import { Fragment as c, jsx as l } from "react/jsx-runtime";
+import { gql as u } from "@apollo/client/core";
+//#region src/shared/components/DocsLink.tsx
+var d = u`
+  query PublicProductDocsUrl($slug: String!) {
+    publicProduct(slug: $slug) {
+      docsUrl
+    }
+  }
+`, f = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new Map();
+function m(e) {
+	if (!e || typeof e != "object") return null;
+	let t = e.publicProduct;
+	if (!t || typeof t != "object") return null;
+	let n = t.docsUrl;
+	return typeof n == "string" && r(n) ? n : null;
+}
+function h(t) {
+	return f.get(e(t));
+}
+function g(t, n) {
+	let r = e(n), i = f.get(r);
+	if (i !== void 0) return Promise.resolve(i);
+	let a = p.get(r);
+	if (a) return a;
+	let o = t.query({
+		query: d,
+		variables: { slug: r },
+		fetchPolicy: "cache-first"
+	}).then((e) => {
+		let t = m(e.data);
+		return f.set(r, t), t;
+	}).catch(() => null).finally(() => {
+		p.delete(r);
+	});
+	return p.set(r, o), o;
+}
+function _(e, t) {
+	let n = i(), [r, a] = s(() => h(e) ?? null);
+	return o(() => {
+		if (!t || !n) return;
+		let r = h(e);
+		if (r !== void 0) {
+			a(r);
+			return;
+		}
+		a(null);
+		let i = !0;
+		return g(n.getClient("global"), e).then((e) => {
+			i && a(e);
+		}), () => {
+			i = !1;
+		};
+	}, [
+		t,
+		n,
+		e
+	]), t ? r : null;
+}
+function v(e = {}) {
+	let t = a(), r = e.productSlug ?? t.productSlug;
+	return n(r, {
+		registryDocsUrl: _(r, e.registry !== !1),
+		domain: e.productSlug ? void 0 : t.domain,
+		environment: e.environment
+	});
+}
+function y(e, n = {}) {
+	let r = a(), i = n.productSlug ?? r.productSlug;
+	return t(i, e, {
+		registryDocsUrl: _(i, n.registry !== !1),
+		domain: n.productSlug ? void 0 : r.domain,
+		environment: n.environment
+	});
+}
+function b({ path: e, productSlug: t, registry: n, environment: r, children: i, ...a }) {
+	let o = y(e, {
+		productSlug: t,
+		registry: n,
+		environment: r
+	});
+	return o ? /* @__PURE__ */ l("a", {
+		...a,
+		href: o,
+		target: "_blank",
+		rel: "noopener noreferrer",
+		"data-docs-link": "",
+		children: i
+	}) : /* @__PURE__ */ l(c, { children: i });
+}
+//#endregion
+export { b as DocsLink, d as PUBLIC_PRODUCT_DOCS_URL_QUERY, g as fetchRegistryDocsUrl, m as readRegistryDocsUrl, v as useProductDocsOrigin, y as useProductDocsUrl };

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

@@ -30,6 +30,8 @@ export type { QuotaUpgradeBridgeProps, QuotaUpgradeBridgeOptions, QuotaUpgradeCo
 export { getSSORedirectUrl, redirectToSSO, SSORedirectSpinner, checkSLO, checkRemoteSLO, clearLocalAuthState, } from './SSORedirectGuard';
 export { MAIN_CONTENT_ID, MainLandmark, PublicLayout, SkipToContentLink, focusSkipTarget, useInsideMainLandmark, } from './SkipToContent';
 export type { MainLandmarkProps, PublicLayoutProps, SkipTarget, SkipToContentLinkProps, } from './SkipToContent';
+export { DocsLink, useProductDocsOrigin, useProductDocsUrl, fetchRegistryDocsUrl, readRegistryDocsUrl, PUBLIC_PRODUCT_DOCS_URL_QUERY, } from './DocsLink';
+export type { DocsLinkProps, DocsRegistryClient, UseProductDocsOptions } from './DocsLink';
 export { LandingOrDashboardRedirect, LandingGateView, resolveLandingGate, hasStoredValidSession, } from './LandingOrDashboardRedirect';
 export type { LandingOrDashboardRedirectProps, LandingGateViewProps, LandingGateDecision, LandingGateInput, } from './LandingOrDashboardRedirect';
 export { AssistantWidget, ASSISTANT_WIDGET_TOGGLE_EVENT } from './assistantWidget/AssistantWidget';

package/dist/shared/config/docsUrls.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Environment-aware product documentation URLs (G91).
+ *
+ * Every product publishes its docs at `docs.<product-domain>` in production
+ * and `alphadocs.<product-domain>` in alpha (behind Cloudflare Access, like
+ * every other alpha host). In-app "Learn more" and Help links must follow the
+ * environment the shell is running in: an alpha shell that links to the prod
+ * docs shows readers documentation for a build they are not using.
+ *
+ * Resolution, highest precedence first:
+ *  1. The product registry `docsUrl` (`publicProduct(slug).docsUrl`), when it
+ *     is an https URL on a trusted product domain.
+ *  2. The static catalog: the product's production app host with `app.`
+ *     swapped for `docs.`.
+ *  3. `docs.<domain>` from the shell's own `domain`, for a product the static
+ *     catalog does not know yet.
+ *
+ * The chosen origin is then canonicalised (legacy docs hosts are mapped to
+ * their canonical twin — FluidGrids' canonical domain is fluidgrids.ai) and
+ * converted to the current environment (`docs.` ↔ `alphadocs.`).
+ *
+ * @module @burdenoff/fe-libs/shared/config/docsUrls
+ */
+/** The docs estate a link should point at. Local dev servers read the prod docs. */
+export type DocsEnvironment = 'prod' | 'alpha';
+/**
+ * Legacy docs hosts and the canonical host each one 301s to. A registry row or
+ * shell config that still carries the legacy host resolves straight to the
+ * canonical one, so a link never relies on the redirect.
+ */
+export declare const CANONICAL_DOCS_HOSTS: Readonly<Record<string, string>>;
+/**
+ * Parse a docs base URL and return its `https://host` origin, or null when it
+ * is not a usable docs origin: not https, not on a known product domain,
+ * or not parseable. Registry values are user-editable admin data, so an
+ * arbitrary host must never become an in-app link.
+ */
+export declare function toTrustedDocsOrigin(url: string | null | undefined): string | null;
+/** Map a legacy docs origin to its canonical twin; other origins are returned unchanged. */
+export declare function canonicalizeDocsOrigin(origin: string): string;
+/**
+ * Convert a docs origin to the given environment: `docs.x` ↔ `alphadocs.x`.
+ * An origin that follows neither convention is returned unchanged, because
+ * guessing an alpha twin for it could produce a host that does not exist.
+ */
+export declare function toEnvironmentDocsOrigin(origin: string, environment: DocsEnvironment): string;
+/**
+ * The default prod docs origin for a product from the static catalog
+ * (`app.<domain>` → `docs.<domain>`), canonicalised. Undefined when the
+ * catalog does not know the product.
+ */
+export declare function getCatalogDocsOrigin(productSlug: string): string | undefined;
+/**
+ * Which docs estate the running shell belongs to.
+ *
+ * - Desktop (Electron): the baked runtime config's `environment`.
+ * - Capacitor: the build's deploy target (the WebView origin is always localhost).
+ * - Web: `alphaapp.*` / `alphaadmin.*` hosts are alpha; everything else is prod.
+ *   A localhost dev server built for alpha (`VITE_DEPLOY_ENV=alpha` or
+ *   `VITE_GATEWAY_TARGET=alpha`) reads the alpha docs; otherwise prod, because
+ *   docs are not served by the local stack.
+ */
+export declare function resolveDocsEnvironment(hostname?: string): DocsEnvironment;
+export interface ResolveDocsOriginOptions {
+    /** The registry's `docsUrl` for the product, when the shell has it. */
+    registryDocsUrl?: string | null;
+    /** The shell's own domain (AppShellConfig `domain`), for products missing from the catalog. */
+    domain?: string;
+    /** Override the detected environment (tests, previews). */
+    environment?: DocsEnvironment;
+}
+/**
+ * The environment-correct docs origin for a product, e.g.
+ * `https://alphadocs.vibecontrols.com` on alphaapp.vibecontrols.com.
+ * Undefined only when no source names a trusted docs host.
+ */
+export declare function resolveProductDocsOrigin(productSlug: string, options?: ResolveDocsOriginOptions): string | undefined;
+/**
+ * Normalise a docs path: must be site-relative. Absolute URLs and
+ * protocol-relative `//host` paths are rejected (they would let a caller turn
+ * a "docs" link into an arbitrary external link). Query and hash are kept.
+ */
+export declare function normalizeDocsPath(path: string | undefined): string | null;
+/**
+ * Full docs URL for a product page, e.g.
+ * `buildProductDocsUrl('fluidgrids', '/users/workflows')` →
+ * `https://docs.fluidgrids.ai/users/workflows` in prod and
+ * `https://alphadocs.fluidgrids.ai/users/workflows` in alpha.
+ * Undefined when there is no trusted docs origin or the path is not site-relative.
+ */
+export declare function buildProductDocsUrl(productSlug: string, path?: string, options?: ResolveDocsOriginOptions): string | undefined;

package/dist/shared/config/docsUrls.js

@@ -0,0 +1,70 @@
+import { isCapacitorNative as e } from "../native/capacitor.js";
+import { getDesktopRuntimeConfig as t } from "../native/desktop.js";
+import { ALL_PRODUCT_DOMAINS as n, ALPHA_HOSTS as r, getCurrentHostname as i, resolveNativeDeployTarget as a } from "./gatewayUrls.js";
+import { legacyProductSlug as o, normalizeProductSlug as s } from "./productSlug.js";
+import { PRODUCT_URLS as c } from "./products.js";
+//#region src/shared/config/docsUrls.ts
+var l = "docs.", u = "alphadocs.", d = {
+	"docs.fluidgrids.com": "docs.fluidgrids.ai",
+	"alphadocs.fluidgrids.com": "alphadocs.fluidgrids.ai"
+}, f = new Set(n);
+function p(e) {
+	let t = e.toLowerCase();
+	for (let e of f) if (t === e || t.endsWith(`.${e}`)) return !0;
+	return !1;
+}
+function m(e) {
+	if (typeof e != "string" || e.trim() === "") return null;
+	let t;
+	try {
+		t = new URL(e.trim());
+	} catch {
+		return null;
+	}
+	return t.protocol !== "https:" || t.username || t.password || t.port || !p(t.hostname) ? null : `https://${t.hostname.toLowerCase()}`;
+}
+function h(e) {
+	let t = d[e.replace(/^https:\/\//, "")];
+	return t ? `https://${t}` : e;
+}
+function g(e, t) {
+	let n = e.replace(/^https:\/\//, ""), r = null;
+	return n.startsWith(u) ? r = n.slice(10) : n.startsWith(l) && (r = n.slice(5)), r ? `https://${t === "alpha" ? u : l}${r}` : e;
+}
+function _(e) {
+	let t = c.production, n = s(e), r = t[n] ?? t[o(n)];
+	if (!r) return;
+	let i;
+	try {
+		i = new URL(r).hostname;
+	} catch {
+		return;
+	}
+	return h(`https://${l}${i.startsWith("app.") ? i.slice(4) : i}`);
+}
+function v(n = i()) {
+	let o = t()?.environment;
+	if (o) return o === "alpha" ? "alpha" : "prod";
+	if (e()) return a() === "alpha" ? "alpha" : "prod";
+	let s = n.toLowerCase(), c = () => a() === "alpha" ? "alpha" : "prod";
+	return r.has(s) ? "alpha" : s.endsWith(".local.burdenoff.com") ? c() : s.startsWith("alpha") && p(s) ? "alpha" : p(s) ? "prod" : c();
+}
+function y(e, t = {}) {
+	let n = t.domain ? m(`https://${l}${t.domain.replace(/^www\./, "")}`) : null, r = m(t.registryDocsUrl) ?? _(e) ?? n ?? void 0;
+	if (!r) return;
+	let i = t.environment ?? v();
+	return g(h(r), i);
+}
+function b(e) {
+	if (e === void 0 || e === "") return "";
+	let t = e.trim();
+	return /^[a-z][a-z0-9+.-]*:/i.test(t) || t.startsWith("//") || t.includes("\\") ? null : t.startsWith("/") || t.startsWith("#") || t.startsWith("?") ? t : `/${t}`;
+}
+function x(e, t, n = {}) {
+	let r = y(e, n);
+	if (!r) return;
+	let i = b(t);
+	if (i !== null) return `${r}${i}`;
+}
+//#endregion
+export { d as CANONICAL_DOCS_HOSTS, x as buildProductDocsUrl, h as canonicalizeDocsOrigin, _ as getCatalogDocsOrigin, b as normalizeDocsPath, v as resolveDocsEnvironment, y as resolveProductDocsOrigin, g as toEnvironmentDocsOrigin, m as toTrustedDocsOrigin };

package/dist/shared/config/index.d.ts

@@ -68,6 +68,8 @@ export { resolveGatewayUrls } from './gatewayUrls';
 export type { RuntimeGatewayUrls } from './gatewayUrls';
 export { resolveAuthBridgeConfig, resolveShellAuthBridgeConfig } from './authBridgeUrls';
 export type { RuntimeAuthBridgeConfig } from './authBridgeUrls';
+export { CANONICAL_DOCS_HOSTS, buildProductDocsUrl, canonicalizeDocsOrigin, getCatalogDocsOrigin, normalizeDocsPath, resolveDocsEnvironment, resolveProductDocsOrigin, toEnvironmentDocsOrigin, toTrustedDocsOrigin, } from './docsUrls';
+export type { DocsEnvironment, ResolveDocsOriginOptions } from './docsUrls';
 export { PRODUCTS, PRODUCT_URLS, BOTMANOR_PRODUCT_SLUG, getProductUrl, getProductsWithUrls, findProductConfig, } from './products';
 export type { ProductConfig } from './products';
 export { PRODUCT_SLUG_RENAMES, PRODUCT_SLUG_EMIT, normalizeProductSlug, legacyProductSlug, isSameProductSlug, emitProductSlug, } from './productSlug';