@burdenoff/fe-libs 2026.1021.9 → 2026.1021.11

package/dist/chrome/AppShellLayout.d.ts

@@ -52,6 +52,18 @@ export interface AppShellLayoutProps {
      * `bottomBar` + `NativeTopBar`.
      */
     nativeCompact?: boolean;
+    /**
+     * Id of the `<main>` landmark, which the skip link targets.
+     * Default `'main-content'` (`MAIN_CONTENT_ID`).
+     */
+    mainId?: string;
+    /**
+     * Render the visually-hidden "Skip to content" link as the first focusable
+     * element of the shell (WCAG 2.4.1). Default `true`.
+     */
+    skipLink?: boolean;
+    /** Overrides the skip link text (default: the `appShell.skipToContent` shell label). */
+    skipLinkLabel?: string;
 }
 /**
  * AppShellLayout Component
@@ -64,6 +76,8 @@ export interface AppShellLayoutProps {
  * - Visibility controls for each section
  * - Responsive layout: overlay on mobile, push on desktop
  * - Custom content styling
+ * - One `<main id="main-content">` landmark plus a "Skip to content" link
+ *   ahead of the header (keyboard users bypass the header and nav)
  *
  * Responsive Behavior:
  * - Mobile (< md): Sidebar as overlay drawer with backdrop

package/dist/chrome/AppShellLayout.js

@@ -1,50 +1,56 @@
-import { Fragment as e, jsx as t, jsxs as n } from "react/jsx-runtime";
+import { MAIN_CONTENT_ID as e, MainLandmark as t, SkipToContentLink as n } from "../shared/components/SkipToContent.js";
+import { Fragment as r, jsx as i, jsxs as a } from "react/jsx-runtime";
 //#region src/chrome/AppShellLayout.tsx
-var r = ({ header: r, sidebar: i, footer: a, bottomPanel: o, rightPanel: s, statusBar: c, children: l, headerVisible: u = !0, footerVisible: d = !0, sidebarVisible: f = !0, contentClassName: p, contentPadding: m = "px-6 lg:px-8 py-6", footerInContent: h = !1, safeArea: g = !0, bottomBar: _, nativeCompact: v = !1 }) => {
-	let y = v ? "p-0" : m, b = h ? `flex-1 overflow-auto bg-bg-canvas flex flex-col ${y}` : `flex-1 overflow-auto bg-bg-canvas ${y}`, x = p || b, S = "max(var(--safe-top, 0px), env(safe-area-inset-top, 0px))", C = "max(var(--safe-bottom, 0px), env(safe-area-inset-bottom, 0px))", w = "max(var(--safe-left, 0px), env(safe-area-inset-left, 0px))", T = "max(var(--safe-right, 0px), env(safe-area-inset-right, 0px))", E = g ? v ? {
-		paddingTop: v && u && r ? void 0 : S,
-		paddingBottom: _ ? void 0 : C
+var o = ({ header: o, sidebar: s, footer: c, bottomPanel: l, rightPanel: u, statusBar: d, children: f, headerVisible: p = !0, footerVisible: m = !0, sidebarVisible: h = !0, contentClassName: g, contentPadding: _ = "px-6 lg:px-8 py-6", footerInContent: v = !1, safeArea: y = !0, bottomBar: b, nativeCompact: x = !1, mainId: S = e, skipLink: C = !0, skipLinkLabel: w }) => {
+	let T = x ? "p-0" : _, E = v ? `flex-1 overflow-auto bg-bg-canvas flex flex-col ${T}` : `flex-1 overflow-auto bg-bg-canvas ${T}`, D = g || E, O = "max(var(--safe-top, 0px), env(safe-area-inset-top, 0px))", k = "max(var(--safe-bottom, 0px), env(safe-area-inset-bottom, 0px))", A = "max(var(--safe-left, 0px), env(safe-area-inset-left, 0px))", j = "max(var(--safe-right, 0px), env(safe-area-inset-right, 0px))", M = y ? x ? {
+		paddingTop: x && p && o ? void 0 : O,
+		paddingBottom: b ? void 0 : k
 	} : {
-		paddingTop: S,
-		paddingBottom: C,
-		paddingLeft: w,
-		paddingRight: T
-	} : {}, D = _ || v && g ? {
-		..._ ? { paddingBottom: "var(--mobile-tabbar-height, 0px)" } : {},
-		...v && g ? {
-			paddingLeft: w,
-			paddingRight: T
+		paddingTop: O,
+		paddingBottom: k,
+		paddingLeft: A,
+		paddingRight: j
+	} : {}, N = b || x && y ? {
+		...b ? { paddingBottom: "var(--mobile-tabbar-height, 0px)" } : {},
+		...x && y ? {
+			paddingLeft: A,
+			paddingRight: j
 		} : {}
 	} : void 0;
-	return /* @__PURE__ */ n("div", {
+	return /* @__PURE__ */ a("div", {
 		className: "flex flex-col h-screen bg-bg-canvas",
-		style: E,
-		"data-native-shell": v ? "" : void 0,
+		style: M,
+		"data-native-shell": x ? "" : void 0,
 		children: [
-			u && r,
-			/* @__PURE__ */ n("div", {
+			C && /* @__PURE__ */ i(n, {
+				targetId: S,
+				label: w
+			}),
+			p && o,
+			/* @__PURE__ */ a("div", {
 				className: "flex flex-1 overflow-hidden relative",
-				children: [f && i, /* @__PURE__ */ n("div", {
+				children: [h && s, /* @__PURE__ */ a("div", {
 					className: "flex flex-1 overflow-hidden",
-					children: [/* @__PURE__ */ n("div", {
+					children: [/* @__PURE__ */ a("div", {
 						className: "flex flex-col flex-1 overflow-hidden",
-						children: [/* @__PURE__ */ t("main", {
-							className: `scrollbar-slim ${x}`,
-							style: D,
+						children: [/* @__PURE__ */ i(t, {
+							id: S,
+							className: `scrollbar-slim ${D}`,
+							style: N,
 							"data-shell-scroll-container": !0,
-							children: h ? /* @__PURE__ */ n(e, { children: [/* @__PURE__ */ t("div", {
-								className: d ? "flex-1" : "flex-1 min-h-0",
-								children: l
-							}), d && a] }) : l
-						}), o]
-					}), s]
+							children: v ? /* @__PURE__ */ a(r, { children: [/* @__PURE__ */ i("div", {
+								className: m ? "flex-1" : "flex-1 min-h-0",
+								children: f
+							}), m && c] }) : f
+						}), l]
+					}), u]
 				})]
 			}),
-			!h && d && a,
-			c,
-			_
+			!v && m && c,
+			d,
+			b
 		]
 	});
 };
 //#endregion
-export { r as AppShellLayout };
+export { o as AppShellLayout };

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

@@ -1,5 +1,5 @@
 import { AssistantUiCatalogue } from './uiActions/uiCatalogue';
-import { AssistantMode, AssistantPromptPart, AssistantRawMessage, AssistantSandboxAuthContext, AssistantArtifact, AssistantSessionInfo, DownloadedAssistantArtifact, StreamAccess } from './types';
+import { AssistantMode, AssistantPromptPart, AssistantRawMessage, AssistantTokenUsage, AssistantSandboxAuthContext, AssistantArtifact, AssistantSessionInfo, DownloadedAssistantArtifact, StreamAccess } from './types';
 import { SandboxWriteCapabilities, WriteApprovalMode, WriteExecutionState } from './writeProposals';
 import { WriteReplyKind, WriteReplyOrigin } from './writeReplyBinder';
 /**
@@ -568,7 +568,4 @@ export declare function downloadAssistantArtifact(sandboxId: string, workspaceId
  */
 mode: AssistantMode | undefined, authContext: AssistantSandboxAuthContext): Promise<DownloadedAssistantArtifact>;
 export declare function checkAssistantAiCredits(workspaceId: string, authContext: AssistantSandboxAuthContext): Promise<boolean>;
-export declare function reportAssistantAiTokenUsage(workspaceId: string, sessionId: string, messageId: string, model: string | undefined, tokens: {
-    input: number;
-    output: number;
-}, authContext: AssistantSandboxAuthContext): Promise<void>;
+export declare function reportAssistantAiTokenUsage(workspaceId: string, sessionId: string, messageId: string, model: string | undefined, tokens: AssistantTokenUsage, authContext: AssistantSandboxAuthContext): Promise<void>;

package/dist/shared/assistant/api.js

@@ -594,20 +594,35 @@ async function We(e, t) {
 		authContext: t
 	})).checkAiCredits;
 }
-async function Ge(e, t, n, r, i, o) {
-	let s = Math.max(0, Math.round(i.input ?? 0)), c = Math.max(0, Math.round(i.output ?? 0));
-	s + c === 0 || !r || await a({
+async function Ge(e, t, n, r, o, s) {
+	let c = Math.max(0, Math.round(o.input ?? 0)), l = Math.max(0, Math.round(o.output ?? 0)), u = Math.max(0, Math.round(o.cache?.read ?? 0)), d = Math.max(0, Math.round(o.cache?.write ?? 0));
+	if (c + l + u + d === 0 || !r) return;
+	let f = !1;
+	if (o.cache) try {
+		f = (await i({
+			query: "query AiCacheTokensSupported { aiCacheTokensSupported }",
+			operationName: "AiCacheTokensSupported",
+			variables: {},
+			workspaceId: e,
+			authContext: s
+		})).aiCacheTokensSupported === !0;
+	} catch {}
+	await a({
 		query: ee,
 		operationName: "ReportAiTokenUsage",
 		variables: { input: {
 			sessionId: t,
 			messageId: n,
 			model: r,
-			inputTokens: s,
-			outputTokens: c
+			inputTokens: c,
+			outputTokens: l,
+			...f ? {
+				cacheReadTokens: u,
+				cacheWriteTokens: d
+			} : {}
 		} },
 		workspaceId: e,
-		authContext: o
+		authContext: s
 	});
 }
 //#endregion

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

@@ -1,7 +1,7 @@
 import { PendingWrite } from './pendingWrite';
 import { WriteProposalMessageRef } from './writeProposalDiscovery';
 import { AssistantMessageAttachment } from './attachments';
-import { AssistantMode } from './types';
+import { AssistantMode, AssistantTokenUsage } from './types';
 export type AssistantSandboxStatus = "none" | "provisioning" | "running" | "stopping" | "error";
 export type AssistantConversationStatus = "idle" | "provisioning" | "connecting" | "streaming" | "complete" | "error";
 /**
@@ -259,10 +259,7 @@ export interface Message {
     role: "user" | "assistant" | "system";
     content: string;
     timestamp: string;
-    tokens?: {
-        input: number;
-        output: number;
-    };
+    tokens?: AssistantTokenUsage;
     metadata?: AssistantMessageMetadata;
     /**
      * ★ BOFF-7335: where this message stands with server history — `pending`

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

@@ -1,7 +1,7 @@
 import { LocalUiCommandOptions } from './localUiCommands';
 import { ReactNode } from 'react';
 import { AssistantModeConfig } from './conversation';
-import { AssistantMode, PageContext } from './types';
+import { AssistantMode, AssistantTokenUsage, PageContext } from './types';
 import { WriteApprovalMode, WriteProposalView } from './writeProposals';
 /**
  * The sixth argument of `buildPrompt` (BOFF-7803 5a, design §3.5): which write
@@ -100,10 +100,7 @@ export interface AssistantProductCapabilities {
         sessionId: string;
         messageId?: string;
         model?: string;
-        tokens: {
-            input: number;
-            output: number;
-        };
+        tokens: AssistantTokenUsage;
     }) => Promise<void>;
     /**
      * Where the assistant's files land in the workspace file library.

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

@@ -1,6 +1,6 @@
 import { PendingWrite } from './pendingWrite';
 import { AssistantProgressOptions } from './progress';
-import { AssistantRawMessage } from './types';
+import { AssistantRawMessage, AssistantTokenUsage } from './types';
 /** What one poll of the sandbox says this turn has produced so far. */
 export interface AssistantTurnProgress {
     /**
@@ -35,10 +35,7 @@ export interface AssistantTurnProgress {
      */
     usedTools?: boolean;
     done: boolean;
-    tokens?: {
-        input: number;
-        output: number;
-    };
+    tokens?: AssistantTokenUsage;
     /**
      * Identity + model of the message these tokens came from, needed to charge the
      * turn: `messageId` is half the server's idempotency hash and `model` selects the

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

@@ -104,6 +104,15 @@ export type AssistantPromptPart = {
     data?: string;
     name?: string;
 };
+/** Runtime input excludes the separately reported provider cache counts. */
+export interface AssistantTokenUsage {
+    input: number;
+    output: number;
+    cache?: {
+        read?: number;
+        write?: number;
+    };
+}
 export interface AssistantRawMessage {
     info?: {
         id?: string;
@@ -115,10 +124,7 @@ export interface AssistantRawMessage {
         parentID?: string;
         providerID?: string;
         modelID?: string;
-        tokens?: {
-            input: number;
-            output: number;
-        };
+        tokens?: AssistantTokenUsage;
         time?: {
             created?: number;
             completed?: number;

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

@@ -1,14 +1,12 @@
 import { AssistantSendRefusal } from './turnOutcome';
+import { AssistantTokenUsage } from './types';
 /** One finished turn's charge, as a product's `reportTokenUsage` receives it. */
 export interface UsageReport {
     workspaceId: string;
     sessionId: string;
     messageId?: string;
     model?: string;
-    tokens: {
-        input: number;
-        output: number;
-    };
+    tokens: AssistantTokenUsage;
 }
 /** Sends one report to its ledger. Rejects when the ledger did not record it. */
 export type UsageReporter = (report: UsageReport) => Promise<void>;

package/dist/shared/assistant/usageReporting.js

@@ -48,14 +48,26 @@ var v = (e) => typeof e == "number" && Number.isFinite(e) && e >= 0, y = (e) =>
 function b(e, t) {
 	if (!e || typeof e != "object") return null;
 	let n = e, r = n.tokens;
-	return n.workspaceId !== t || typeof n.sessionId != "string" || n.sessionId.length === 0 || !y(n.messageId) || !y(n.model) || !r || typeof r != "object" || !v(r.input) || !v(r.output) ? null : {
+	if (n.workspaceId !== t || typeof n.sessionId != "string" || n.sessionId.length === 0 || !y(n.messageId) || !y(n.model) || !r || typeof r != "object" || !v(r.input) || !v(r.output)) return null;
+	let i;
+	if (r.cache !== void 0) {
+		if (!r.cache || typeof r.cache != "object" || Array.isArray(r.cache)) return null;
+		let e = r.cache;
+		if (e.read !== void 0 && !v(e.read) || e.write !== void 0 && !v(e.write)) return null;
+		i = {
+			...v(e.read) ? { read: e.read } : {},
+			...v(e.write) ? { write: e.write } : {}
+		};
+	}
+	return {
 		workspaceId: t,
 		sessionId: n.sessionId,
 		...typeof n.messageId == "string" ? { messageId: n.messageId } : {},
 		...typeof n.model == "string" ? { model: n.model } : {},
 		tokens: {
 			input: r.input,
-			output: r.output
+			output: r.output,
+			...i ? { cache: i } : {}
 		}
 	};
 }

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

@@ -0,0 +1,95 @@
+import { HTMLAttributes, ReactNode } from 'react';
+/**
+ * Skip link + `<main>` landmark primitives (WCAG 2.4.1 "Bypass Blocks").
+ *
+ * Every product page needs exactly ONE `<main>` landmark, and a keyboard user
+ * needs a way past the header/nav to reach it. The signed-in shell
+ * (`AppShellLayout`) and the public landing/auth pages (`PublicLayout`,
+ * `ModernLanding`, `NativeWelcome`) all build on these, so the id, the label
+ * and the focus behaviour are the same on every product.
+ *
+ * ★ One `<main>` per page, whatever the nesting. `MainLandmark` marks its
+ *   subtree; a `MainLandmark` rendered inside another one (a public page
+ *   mounted inside the signed-in shell, `ModernLanding` wrapped in
+ *   `PublicLayout`) renders a plain `<div>` instead of a second `<main>`, and
+ *   a nested `SkipToContentLink` renders nothing, because the outer layout
+ *   already owns both.
+ */
+/** The id every shared layout gives its `<main>`; the skip link's default target. */
+export declare const MAIN_CONTENT_ID = "main-content";
+/** True inside a `MainLandmark` (so a page-level `<main>` already exists). */
+export declare function useInsideMainLandmark(): boolean;
+/** The minimal element surface `focusSkipTarget` needs (a DOM `HTMLElement` fits). */
+export interface SkipTarget {
+    hasAttribute(name: string): boolean;
+    setAttribute(name: string, value: string): void;
+    focus(options?: FocusOptions): void;
+    scrollIntoView?(arg?: boolean | ScrollIntoViewOptions): void;
+}
+/**
+ * Move focus (and the viewport) to the skip-link target.
+ *
+ * Returns false when there is no target, so the caller can leave the native
+ * `#hash` jump alone. A target that is not focusable on its own gets
+ * `tabindex="-1"` first: an element that cannot take focus would leave the
+ * sequential focus point where it was, and the next Tab would land back in
+ * the header.
+ */
+export declare function focusSkipTarget(target: SkipTarget | null): boolean;
+export interface SkipToContentLinkProps {
+    /** Id of the element to jump to. Default `MAIN_CONTENT_ID`. */
+    targetId?: string;
+    /** Visible text when focused. Default: the `appShell.skipToContent` shell label. */
+    label?: string;
+    className?: string;
+}
+/**
+ * "Skip to content" link: visually hidden until it takes keyboard focus, then
+ * pinned to the top-left above all chrome. Render it as the FIRST focusable
+ * element of the page, before the header.
+ *
+ * The click is handled in script rather than left to the `#hash`: under a
+ * `HashRouter` (installed apps) a hash change is a route change, and in every
+ * router the native jump scrolls without reliably moving focus.
+ */
+export declare function SkipToContentLink({ targetId, label, className, }: SkipToContentLinkProps): import('react/jsx-runtime').JSX.Element | null;
+export interface MainLandmarkProps extends Omit<HTMLAttributes<HTMLElement>, 'id' | 'tabIndex'> {
+    /** Element id, the skip link's target. Default `MAIN_CONTENT_ID`. */
+    id?: string;
+    children?: ReactNode;
+}
+/**
+ * The page's `<main>` landmark: `id` for the skip link and `tabIndex={-1}` so
+ * focus can land on it (programmatic only; it never joins the Tab order).
+ * Inside another `MainLandmark` it renders a `<div>` with no id, so a page
+ * never has two `<main>`s or two `#main-content`s.
+ */
+export declare function MainLandmark({ id, className, children, ...rest }: MainLandmarkProps): import('react/jsx-runtime').JSX.Element;
+export interface PublicLayoutProps {
+    /** Page header (brand, sign-in button). Rendered between the skip link and `<main>`. */
+    header?: ReactNode;
+    /** Page footer. Rendered after `<main>`. */
+    footer?: ReactNode;
+    children: ReactNode;
+    /** `<main>` id. Default `MAIN_CONTENT_ID`. */
+    mainId?: string;
+    /** Overrides the skip link text. */
+    skipLinkLabel?: string;
+    /** Classes for the outer wrapper. */
+    className?: string;
+    /** Classes for `<main>` (it already grows to fill the page). */
+    mainClassName?: string;
+}
+/**
+ * Landmark frame for public (signed-out) routes: the landing page and the
+ * `/auth/*` pages, which render outside `AppShellLayout` and so had no
+ * `<main>` and no skip link.
+ *
+ * ```tsx
+ * <PublicLayout header={<LandingHeader />} footer={<LandingFooter />}>
+ *   <Hero />
+ *   <Features />
+ * </PublicLayout>
+ * ```
+ */
+export declare function PublicLayout({ header, footer, children, mainId, skipLinkLabel, className, mainClassName, }: PublicLayoutProps): import('react/jsx-runtime').JSX.Element;

package/dist/shared/components/SkipToContent.js

@@ -0,0 +1,61 @@
+import { useShellLabel as e } from "../providers/shell/useShellLabel.js";
+import { cn as t } from "../../shared-utils.js";
+import { createContext as n, useContext as r } from "react";
+import { jsx as i, jsxs as a } from "react/jsx-runtime";
+//#region src/shared/components/SkipToContent.tsx
+var o = "main-content", s = n(!1);
+function c() {
+	return r(s);
+}
+function l(e) {
+	return e ? (e.hasAttribute("tabindex") || e.setAttribute("tabindex", "-1"), e.focus({ preventScroll: !0 }), e.scrollIntoView?.({ block: "start" }), !0) : !1;
+}
+function u({ targetId: n = o, label: r, className: a }) {
+	let s = e();
+	return c() ? null : /* @__PURE__ */ i("a", {
+		href: `#${n}`,
+		onClick: (e) => {
+			l(document.getElementById(n)) && e.preventDefault();
+		},
+		"data-skip-link": "",
+		className: t("sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4 focus:z-[var(--z-toast,1400)]", "focus:rounded-lg focus:border focus:border-border-subtle focus:bg-bg-surface focus:px-4 focus:py-2", "focus:text-sm focus:font-medium focus:text-text-primary focus:shadow-elevation-3", "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-focus-ring)]", a),
+		children: r ?? s("appShell.skipToContent", "Skip to content")
+	});
+}
+function d({ id: e = o, className: n, children: r, ...a }) {
+	return c() ? /* @__PURE__ */ i("div", {
+		className: n,
+		...a,
+		children: r
+	}) : /* @__PURE__ */ i(s.Provider, {
+		value: !0,
+		children: /* @__PURE__ */ i("main", {
+			id: e,
+			tabIndex: -1,
+			className: t("focus:outline-none", n),
+			...a,
+			children: r
+		})
+	});
+}
+function f({ header: e, footer: n, children: r, mainId: s = o, skipLinkLabel: c, className: l, mainClassName: f }) {
+	return /* @__PURE__ */ a("div", {
+		className: t("flex min-h-[100dvh] flex-col", l),
+		"data-public-layout": "",
+		children: [
+			/* @__PURE__ */ i(u, {
+				targetId: s,
+				label: c
+			}),
+			e,
+			/* @__PURE__ */ i(d, {
+				id: s,
+				className: t("flex-1", f),
+				children: r
+			}),
+			n
+		]
+	});
+}
+//#endregion
+export { o as MAIN_CONTENT_ID, d as MainLandmark, f as PublicLayout, u as SkipToContentLink, l as focusSkipTarget, c as useInsideMainLandmark };

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

@@ -28,6 +28,8 @@ export type { UpgradeInlineBannerProps } from './UpgradeInlineBanner';
 export { QuotaUpgradeBridge, useQuotaUpgradeBridge, dispatchProductQuotaExhausted, resolveQuotaUpgradeCopy, quotaEventKind, claimQuotaDialog, captureQuotaDialogOwners, useQuotaDialogOwnership, withQuotaDialogOwnership, DEFAULT_QUOTA_UPGRADE_COPY, } from './QuotaUpgradeBridge';
 export type { QuotaUpgradeBridgeProps, QuotaUpgradeBridgeOptions, QuotaUpgradeCopy, QuotaUpgradeCopyByKind, ProductQuotaExhaustedDetail, } from './QuotaUpgradeBridge';
 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 { LandingOrDashboardRedirect, LandingGateView, resolveLandingGate, hasStoredValidSession, } from './LandingOrDashboardRedirect';
 export type { LandingOrDashboardRedirectProps, LandingGateViewProps, LandingGateDecision, LandingGateInput, } from './LandingOrDashboardRedirect';
 export { AssistantWidget, ASSISTANT_WIDGET_TOGGLE_EVENT } from './assistantWidget/AssistantWidget';