- {t("filesPage.myFiles", "My Files")}
+ {t("fileSidebar.myFiles", "File library")}
diff --git a/frontend/editor/src/core/components/filesPage/filesPageReturnRoute.ts b/frontend/editor/src/core/components/filesPage/filesPageReturnRoute.ts
index 5e6292d62f..69a1bc1c53 100644
--- a/frontend/editor/src/core/components/filesPage/filesPageReturnRoute.ts
+++ b/frontend/editor/src/core/components/filesPage/filesPageReturnRoute.ts
@@ -1,6 +1,6 @@
/**
* Stores the route the user came from when they open files into the
- * workbench from My Files. Lets the workbench show a "Back to My Files"
+ * workbench from the file library. Lets the workbench show a "Back to File library"
* affordance and return to the exact folder they were browsing.
*
* Persisted in sessionStorage so a hard reload keeps the return path
diff --git a/frontend/editor/src/core/components/layout/AppFrame.css b/frontend/editor/src/core/components/layout/AppFrame.css
new file mode 100644
index 0000000000..0cc20b30c6
--- /dev/null
+++ b/frontend/editor/src/core/components/layout/AppFrame.css
@@ -0,0 +1,18 @@
+/* ========== APP FRAME ========== */
+/* The rail's column, then whichever app is mounted, so a switch changes only the app. */
+.app-frame {
+ display: flex;
+ height: 100vh;
+ height: 100dvh; /* track mobile browser chrome */
+ overflow: hidden;
+ background-color: var(--c-bg);
+}
+
+/* min-width: 0 so the app shrinks instead of forcing the frame past the window. */
+.app-frame__content {
+ flex: 1;
+ min-width: 0;
+ height: 100%;
+}
+
+/* The rail hides itself below the mobile breakpoint - see QuickNavRailContainer.css. */
diff --git a/frontend/editor/src/core/components/layout/AppFrame.tsx b/frontend/editor/src/core/components/layout/AppFrame.tsx
new file mode 100644
index 0000000000..38fa92ecba
--- /dev/null
+++ b/frontend/editor/src/core/components/layout/AppFrame.tsx
@@ -0,0 +1,22 @@
+import { Suspense } from "react";
+import { Outlet } from "react-router-dom";
+import { LoadingFallback } from "@app/components/shared/LoadingFallback";
+import { QuickNavHostProvider } from "@app/contexts/QuickNavHostContext";
+import { QuickNavRailHost } from "@app/components/shared/quickNav/QuickNavRailHost";
+import "@app/components/layout/AppFrame.css";
+
+/** The rail renders once outside both apps; Suspense sits inside it, not above. */
+export function AppFrame() {
+ return (
+
+
+
+
+
{open && (
-
);
diff --git a/frontend/editor/src/core/components/notifications/NotificationPanel.tsx b/frontend/editor/src/core/components/notifications/NotificationPanel.tsx
new file mode 100644
index 0000000000..f3ff0c621e
--- /dev/null
+++ b/frontend/editor/src/core/components/notifications/NotificationPanel.tsx
@@ -0,0 +1,135 @@
+import { Fragment, useEffect, useId, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import DividerWithText from "@app/components/shared/DividerWithText";
+import { useNotifications } from "@app/hooks/useNotifications";
+import type { ClientActionRegistry } from "@app/components/notifications/notificationActions";
+import { NotificationItem } from "@app/components/notifications/NotificationItem";
+import "@app/components/notifications/NotificationBell.css";
+
+/** Named so a trigger in another tree can point at it with aria-controls. */
+export const NOTIFICATIONS_PANEL_ID = "quick-nav-notifications-panel";
+
+export interface NotificationPanelProps {
+ onClose: () => void;
+ id?: string;
+ /** Passed in: its document handover has to run whether the panel is open or not. */
+ registry: ClientActionRegistry;
+ style?: React.CSSProperties;
+ className?: string;
+}
+
+/** Mounted only while open, since mounting is what marks everything read. */
+export function NotificationPanel({
+ onClose,
+ registry,
+ id,
+ style,
+ className,
+}: NotificationPanelProps) {
+ const { t } = useTranslation();
+ const { notifications, unreadCount, documentStateFor, markAllSeen } =
+ useNotifications();
+ const panel = useRef setOpen(false)}
+ registry={registry}
style={anchor ? { top: anchor.top, right: anchor.right } : undefined}
- >
-
+ />
)}
- {t("notifications.title", "Notifications")} -
- - {notifications.length === 0 ? ( -- {t("notifications.empty", "Nothing to report.")} -
- ) : ( --
- {notifications.map((notification, index) => (
-
-
-
-
- )}
- {/* Only with something on both sides: a lone "Earlier" over everything says
- nothing the empty badge has not. */}
- {index === dividedAt && dividedAt > 0 && (
- -
-
-
- )}
-
+
+ );
+}
diff --git a/frontend/editor/src/core/components/shared/AppSwitch.tsx b/frontend/editor/src/core/components/shared/AppSwitch.tsx
index 71d35ed5ad..fbbe85ccdb 100644
--- a/frontend/editor/src/core/components/shared/AppSwitch.tsx
+++ b/frontend/editor/src/core/components/shared/AppSwitch.tsx
@@ -11,12 +11,7 @@ interface AppSwitchMenuItemsProps {
onSwitch: (app: AppSwitchTarget) => void;
}
-/**
- * The editor / processor items for the app-switch menu. Rendered inside the
- * BrandSwitcher's logo dropdown, which both apps use as their switcher. The
- * mark is the shared + {t("notifications.title", "Notifications")} +
+ + {notifications.length === 0 ? ( ++ {t("notifications.empty", "Nothing to report.")} +
+ ) : ( +-
+ {notifications.map((notification, index) => (
+
-
+
+
+ )}
+ {/* Only with unread rows above it. */}
+ {index === dividedAt && dividedAt > 0 && (
+ -
+
+
+ )}
+
-
-
- }
- >
- {!collapsed &&
-
-
-
-
- );
-}
diff --git a/frontend/editor/src/core/components/shared/BrandTile.tsx b/frontend/editor/src/core/components/shared/BrandTile.tsx
new file mode 100644
index 0000000000..e8ccba6db8
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/BrandTile.tsx
@@ -0,0 +1,29 @@
+interface BrandTileProps {
+ /** CSS length. Omit to let the caller's CSS size it. */
+ size?: string;
+ className?: string;
+}
+
+/** The mark in a rounded square. Decorative: call sites carry the accessible name. */
+export function BrandTile({ size, className }: BrandTileProps) {
+ return (
+
+ );
+}
diff --git a/frontend/editor/src/core/components/shared/FileSidebar.css b/frontend/editor/src/core/components/shared/FileSidebar.css
index 2347d9a2b2..76db9deab4 100644
--- a/frontend/editor/src/core/components/shared/FileSidebar.css
+++ b/frontend/editor/src/core/components/shared/FileSidebar.css
@@ -1,7 +1,9 @@
/* ========== FILE SIDEBAR ========== */
.file-sidebar {
- background-color: var(--c-bg);
+ /* One solid panel, with a rule only on the workbench side, so it frames the document. */
+ background-color: var(--c-surface);
+ border-inline-end: 1px solid var(--c-border-subtle);
display: flex;
flex-direction: column;
height: 100%;
@@ -37,12 +39,19 @@
gap: 0.5rem;
}
-/* ---- Brand header (logo / editor⇄processor switcher) ---- */
-.file-sidebar-brand {
+/* Flattened here; two classes deep to beat .sui-nav-surface without relying on order. */
+.file-sidebar .sui-nav-surface {
+ background: transparent;
+ border: 0;
+ border-radius: 0;
+}
+
+/* ---- Header row (wordmark + collapse toggle) ---- */
+.file-sidebar-header {
display: flex;
align-items: center;
- min-height: 40px;
- padding: 0 0.375rem;
+ min-height: var(--nav-header-h);
+ padding: 0 var(--nav-gutter);
flex-shrink: 0;
}
@@ -51,9 +60,9 @@
flex-shrink: 0;
}
-.file-sidebar[data-collapsed="true"] .file-sidebar-brand {
- flex-direction: column;
- gap: 0.25rem;
+/* Collapsed the row holds only the toggle, so centre it. */
+.file-sidebar[data-collapsed="true"] .file-sidebar-header {
+ justify-content: center;
padding: 0;
}
.file-sidebar[data-collapsed="true"] .file-sidebar-collapse-toggle {
diff --git a/frontend/editor/src/core/components/shared/FileSidebar.tsx b/frontend/editor/src/core/components/shared/FileSidebar.tsx
index f9337bd880..1dcf4a7301 100644
--- a/frontend/editor/src/core/components/shared/FileSidebar.tsx
+++ b/frontend/editor/src/core/components/shared/FileSidebar.tsx
@@ -24,7 +24,6 @@ import { useViewer } from "@app/contexts/ViewerContext";
import { useFileHandler } from "@app/hooks/useFileHandler";
import { useAccountIdentity } from "@app/hooks/useAccountIdentity";
import { useFreeCreditsSummary } from "@app/hooks/useFreeCreditsSummary";
-import { useOtherAppSwitch } from "@app/hooks/useOtherAppSwitch";
import { useOpenPlan } from "@app/hooks/useOpenPlan";
import { NavFooter } from "@app/components/shared/navFooter/NavFooter";
import {
@@ -32,8 +31,7 @@ import {
useIndexedDBRevision,
} from "@app/contexts/IndexedDBContext";
import { GoogleDriveIcon } from "@app/components/shared/CloudStorageIcons";
-import { AppSwitcher } from "@app/components/shared/AppSwitcher";
-import { SidebarToggleIcon } from "@app/components/shared/SidebarToggleIcon";
+import { SidebarHeader } from "@app/components/shared/SidebarHeader";
import type { StirlingFileStub } from "@app/types/fileContext";
import FolderOpenIcon from "@mui/icons-material/FolderOpen";
import FolderSpecialIcon from "@mui/icons-material/FolderSpecial";
@@ -78,8 +76,9 @@ import { WATCHED_FOLDERS_ENABLED } from "@app/constants/featureFlags";
import { useToolWorkflow } from "@app/contexts/ToolWorkflowContext";
import "@app/components/shared/FileSidebar.css";
-const COLLAPSED_WIDTH = "3.5rem";
-const EXPANDED_WIDTH = "16.25rem"; // ~260px
+// Shared with the processor sidebar via tokens, so the two cannot drift.
+const COLLAPSED_WIDTH = "var(--sidebar-collapsed-w)";
+const EXPANDED_WIDTH = "var(--sidebar-w)";
// Inlined to avoid a circular import with WatchedFoldersRegistration.
const WATCHED_FOLDER_VIEW_ID = "watchedFolder";
@@ -98,9 +97,11 @@ export interface FileSidebarProps {
collapsed?: boolean;
onToggleCollapse?: () => void;
onOpenSettings?: () => void;
- /** Accessible name override for the toggle button. */
+ /** The quick nav rail owns the account control, so the footer drops its own row. */
+ accountHoisted?: boolean;
+ /** Accessible name override for the collapse toggle. */
toggleAriaLabel?: string;
- /** Icon override for the toggle button (e.g. back-arrow on /files). */
+ /** Icon override for the collapse toggle (e.g. back-arrow on /files). */
toggleIcon?: React.ReactNode;
/** Override the Open-from-computer handler (e.g. upload to /files folder). */
onUploadFiles?: (files: File[]) => void | Promise
- (
{/* Tooltips only fire when collapsed - when expanded the visible
text label below already identifies each row, so a tooltip
would just flash a duplicate. Distinct icons (UploadFile for
- "Open from computer" vs FolderOpen for "My Files") so the
+ "Open from computer" vs FolderOpen for "File library") so the
collapsed rail isn't two identical folder icons either. */}
(
onClick={() => {
// "Open from computer" goes straight to the native OS file
// picker. The full file manager (recent + drives + folders)
- // is reachable via "My Files" below.
+ // is reachable via "File library" below.
nativeFileInputRef.current?.click();
}}
role="button"
@@ -1080,7 +1068,7 @@ const FileSidebar = forwardRef(
)}
(
}}
role="button"
tabIndex={0}
- aria-label={t("fileSidebar.myFiles", "My Files")}
+ aria-label={t("fileSidebar.myFiles", "File library")}
onKeyDown={(e) => {
if (e.key === "Enter" || e.key === " ") {
e.preventDefault();
@@ -1105,7 +1093,7 @@ const FileSidebar = forwardRef(
@@ -1370,15 +1358,15 @@ const FileSidebar = forwardRef
- onToggleCollapse()}
- aria-label={
- toggleAriaLabel ??
- (collapsed
- ? t("fileSidebar.expand", "Expand sidebar")
- : t("fileSidebar.collapse", "Collapse sidebar"))
- }
- >
- {toggleIcon ??
- )}
-
+
+ {!collapsed &&
+ );
+}
diff --git a/frontend/editor/src/core/components/shared/SidebarToggleButton.tsx b/frontend/editor/src/core/components/shared/SidebarToggleButton.tsx
new file mode 100644
index 0000000000..3a1345360b
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/SidebarToggleButton.tsx
@@ -0,0 +1,36 @@
+import { useTranslation } from "react-i18next";
+import { ActionIcon } from "@app/ui/ActionIcon";
+import { SidebarToggleIcon } from "@app/components/shared/SidebarToggleIcon";
+
+export interface SidebarToggleButtonProps {
+ collapsed?: boolean;
+ onToggle: () => void;
+ ariaLabel?: string;
+ icon?: React.ReactNode;
+}
+
+/** Opens and closes the sidebar; on /files the caller swaps in a back arrow. */
+export function SidebarToggleButton({
+ collapsed,
+ onToggle,
+ ariaLabel,
+ icon,
+}: SidebarToggleButtonProps) {
+ const { t } = useTranslation();
+ return (
+
+
+ );
+}
+
export const Tooltip: React.FC
+ {header.logo || (
+ 
+ )}
+
+ {header.title}
+
-
- )}
+ {header &&
- {header.logo || (
-
- )}
-
- {header.title}
-
{returnRoute && hasFiles && (
<>
@@ -501,7 +503,7 @@ export default function WorkbenchBar({
: "filesPage.backToMyFiles",
returnRoute.label
? `Back to ${returnRoute.label}`
- : "Back to My Files",
+ : "Back to File library",
{ folder: returnRoute.label ?? "" },
)}
leftSection={
);
diff --git a/frontend/editor/src/core/components/shared/navFooter/NavFooter.tsx b/frontend/editor/src/core/components/shared/navFooter/NavFooter.tsx
index 373c91bccf..848c0cb4a5 100644
--- a/frontend/editor/src/core/components/shared/navFooter/NavFooter.tsx
+++ b/frontend/editor/src/core/components/shared/navFooter/NavFooter.tsx
@@ -33,6 +33,8 @@ export interface NavFooterProps {
otherApp?: NavFooterAppLink | null;
/** Extra rows above the account row (the self-hosted link-account CTA). */
accountExtras?: ReactNode;
+ /** False where the rail owns the account control, so only one avatar is drawn. */
+ showAccount?: boolean;
/** Icon-rail state: labels collapse to tooltips. */
collapsed?: boolean;
className?: string;
@@ -69,6 +71,7 @@ export function NavFooter({
onOpenPlan,
otherApp,
accountExtras,
+ showAccount = true,
collapsed = false,
className,
}: NavFooterProps) {
@@ -144,49 +147,51 @@ export function NavFooter({
});
}
- rows.push({
- key: "account",
- node: (
-
+
+
+
+
+ );
+}
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavHostBridge.tsx b/frontend/editor/src/core/components/shared/quickNav/QuickNavHostBridge.tsx
new file mode 100644
index 0000000000..9a9101a826
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavHostBridge.tsx
@@ -0,0 +1,85 @@
+import { useCallback, useMemo, useState } from "react";
+import { useAccountIdentity } from "@app/hooks/useAccountIdentity";
+import {
+ NotificationPanel,
+ NOTIFICATIONS_PANEL_ID,
+} from "@app/components/notifications/NotificationPanel";
+import { useNotificationActions } from "@app/components/notifications/notificationActions";
+import { useQuickNavToolReasons } from "@app/components/shared/quickNav/useQuickNavToolReasons";
+import { useNotificationsAvailable } from "@app/components/notifications/useNotificationsAvailable";
+import { useSigningBadgeCount } from "@app/hooks/signing/useSigningBadgeCount";
+import {
+ useRegisterQuickNavHost,
+ type QuickNavToolReasons,
+} from "@app/contexts/QuickNavHostContext";
+import type { ToolId } from "@app/types/toolId";
+
+export interface QuickNavHostBridgeProps {
+ portalAccess?: boolean;
+ readerMode?: boolean;
+ onSetReaderMode?: (on: boolean) => void;
+ onOpenSettings: () => void;
+ requestNavigation?: (go: () => void) => void;
+ onGoToDefaultState?: () => void;
+ onSelectTool?: (toolId: ToolId) => void;
+ /** Merged over the reasons worked out here, for what only the app can see. */
+ toolReasons?: QuickNavToolReasons;
+}
+
+/** Registers with the rail what only the app can see, and owns the notifications panel. */
+export function QuickNavHostBridge({
+ portalAccess = false,
+ readerMode = false,
+ onSetReaderMode,
+ onOpenSettings,
+ requestNavigation,
+ onSelectTool,
+ onGoToDefaultState,
+ toolReasons,
+}: QuickNavHostBridgeProps) {
+ const { displayName, profilePictureUrl } = useAccountIdentity();
+ const signingBadge = useSigningBadgeCount();
+ const notificationsAvailable = useNotificationsAvailable();
+ // Built even when closed: it carries a one-shot document pickup that would sit unclaimed.
+ const notificationActions = useNotificationActions();
+ const endpointReasons = useQuickNavToolReasons();
+ const mergedToolReasons = useMemo(() => {
+ // An empty map from the app is silence, not an answer.
+ const extra =
+ toolReasons && Object.keys(toolReasons).length > 0 ? toolReasons : null;
+ if (!endpointReasons && !extra) return undefined;
+ return { ...endpointReasons, ...extra };
+ }, [endpointReasons, toolReasons]);
+ const [notificationsOpen, setNotificationsOpen] = useState(false);
+ const closeNotifications = useCallback(() => setNotificationsOpen(false), []);
+
+ useRegisterQuickNavHost(
+ {
+ identity: { displayName, profilePictureUrl },
+ signingBadge,
+ portalAccess,
+ readerMode,
+ notificationsOpen,
+ toolReasons: mergedToolReasons,
+ },
+ {
+ openSettings: onOpenSettings,
+ requestNavigation,
+ selectTool: onSelectTool,
+ setReaderMode: onSetReaderMode,
+ goToDefaultState: onGoToDefaultState,
+ toggleNotifications: () => setNotificationsOpen((open) => !open),
+ },
+ );
+
+ // Mounted only while open, so a closed panel never subscribes to the poll.
+ if (!notificationsAvailable || !notificationsOpen) return null;
+ return (
+
+
+ {/* A span, not the Avatar: Tooltip binds by cloning its child. */}
+
+
+
+ );
+}
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavRailBase.test.tsx b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailBase.test.tsx
new file mode 100644
index 0000000000..328f2d8f4e
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailBase.test.tsx
@@ -0,0 +1,123 @@
+import { describe, it, expect } from "vitest";
+import { render } from "@testing-library/react";
+import {
+ QuickNavRailBase,
+ type QuickNavEntry,
+} from "@app/components/shared/quickNav/QuickNavRailBase";
+
+/** The rail needs no providers. */
+function withProviders(ui: React.ReactNode) {
+ return <>{ui};
+}
+
+function entry(
+ id: string,
+ overrides: Partial
+
+
+
+ }
+ />
+
+
+
-
-
-
-
+
+
+
+ {/* Inside the Popover: Tooltip binds by cloning, and Popover passes no ref on. */}
+
-
-
-
+
+
- {
- /** Element to render; `section`/`aside` when the box is a landmark. */
- as?: "div" | "section" | "aside";
+ /** Element to render; `section`/`aside`/`nav` when the box is a landmark. */
+ as?: "div" | "section" | "aside" | "nav";
}
/**
diff --git a/frontend/editor/src/core/utils/homePageNavigation.ts b/frontend/editor/src/core/utils/homePageNavigation.ts
index 001e026710..7a91bfec65 100644
--- a/frontend/editor/src/core/utils/homePageNavigation.ts
+++ b/frontend/editor/src/core/utils/homePageNavigation.ts
@@ -1,4 +1,4 @@
-import type { WorkbenchType } from "@app/types/workbench";
+import { getDefaultWorkbench, type WorkbenchType } from "@app/types/workbench";
export type StartupWorkbench = "viewer" | "fileEditor";
@@ -7,6 +7,13 @@ export interface StartupNavigationAction {
activeFileIndex?: number;
}
+/** Several files means the file editor; one or none the viewer. */
+export function getDefaultWorkbenchForFileCount(
+ fileCount: number,
+): WorkbenchType {
+ return fileCount > 1 ? "fileEditor" : getDefaultWorkbench();
+}
+
export function getStartupNavigationAction(
previousFileCount: number,
currentFileCount: number,
diff --git a/frontend/editor/src/core/utils/pendingReaderMode.ts b/frontend/editor/src/core/utils/pendingReaderMode.ts
new file mode 100644
index 0000000000..faacfba6b8
--- /dev/null
+++ b/frontend/editor/src/core/utils/pendingReaderMode.ts
@@ -0,0 +1,13 @@
+let pending = false;
+
+/** Carries "open in reading mode" across an app switch, and deliberately not a reload. */
+export function requestReaderMode(): void {
+ pending = true;
+}
+
+/** True once per request. */
+export function consumeReaderModeRequest(): boolean {
+ if (!pending) return false;
+ pending = false;
+ return true;
+}
diff --git a/frontend/editor/src/core/utils/viewTransition.test.ts b/frontend/editor/src/core/utils/viewTransition.test.ts
new file mode 100644
index 0000000000..5fb11c8aa2
--- /dev/null
+++ b/frontend/editor/src/core/utils/viewTransition.test.ts
@@ -0,0 +1,63 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { withViewTransition } from "@app/utils/viewTransition";
+
+// The stub carries only the field the helper reads, hence the cast through unknown.
+type MutableDoc = { startViewTransition?: unknown };
+const doc = document as unknown as MutableDoc;
+
+function stubApi(): ReturnType {
+ const start = vi.fn((cb: () => void) => {
+ cb();
+ return { finished: Promise.resolve() };
+ });
+ doc.startViewTransition = start;
+ return start;
+}
+
+function stubReducedMotion(reduced: boolean): void {
+ vi.stubGlobal("matchMedia", (query: string) => ({
+ matches: reduced && query.includes("prefers-reduced-motion"),
+ media: query,
+ addEventListener: () => {},
+ removeEventListener: () => {},
+ }));
+}
+
+afterEach(() => {
+ delete doc.startViewTransition;
+ vi.unstubAllGlobals();
+});
+
+describe("withViewTransition", () => {
+ it("runs the update inside a transition when one is possible", async () => {
+ const start = stubApi();
+ stubReducedMotion(false);
+ const update = vi.fn();
+
+ await withViewTransition(update);
+
+ expect(start).toHaveBeenCalledTimes(1);
+ expect(update).toHaveBeenCalledTimes(1);
+ });
+
+ it("skips the transition when the user asked for less motion", async () => {
+ // The state change must still happen - only the animation is dropped.
+ const start = stubApi();
+ stubReducedMotion(true);
+ const update = vi.fn();
+
+ await withViewTransition(update);
+
+ expect(start).not.toHaveBeenCalled();
+ expect(update).toHaveBeenCalledTimes(1);
+ });
+
+ it("still applies the update where the API is unavailable", async () => {
+ stubReducedMotion(false);
+ const update = vi.fn();
+
+ await withViewTransition(update);
+
+ expect(update).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/frontend/editor/src/core/utils/viewTransition.ts b/frontend/editor/src/core/utils/viewTransition.ts
index 049c3e7673..85a05ca78d 100644
--- a/frontend/editor/src/core/utils/viewTransition.ts
+++ b/frontend/editor/src/core/utils/viewTransition.ts
@@ -4,21 +4,20 @@ type ViewTransitionDoc = Document & {
startViewTransition?: (cb: () => void) => { finished: Promise };
};
-/**
- * Run a state update inside a View Transition so the browser cross-fades
- * (and morphs any elements sharing a {@code view-transition-name}) between
- * the before/after DOMs.
- *
- * Falls back to a plain synchronous update when the API is unavailable
- * (Firefox <130, JSDOM, motion-reduced preference).
- */
+/** Runs a state update in a View Transition, plainly where that is unavailable. */
export function withViewTransition(update: () => void): Promise {
if (typeof document === "undefined") {
update();
return Promise.resolve();
}
+ // Callers don't each check: reduced motion still gets the state change.
+ const reduced =
+ typeof window !== "undefined" &&
+ typeof window.matchMedia === "function" &&
+ window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
const doc = document as ViewTransitionDoc;
- if (doc.startViewTransition) {
+ if (doc.startViewTransition && !reduced) {
return doc.startViewTransition(() => flushSync(update)).finished;
}
update();
diff --git a/frontend/editor/src/desktop/components/shared/AppSwitcher.tsx b/frontend/editor/src/desktop/components/shared/AppSwitcher.tsx
deleted file mode 100644
index 21896d9a1d..0000000000
--- a/frontend/editor/src/desktop/components/shared/AppSwitcher.tsx
+++ /dev/null
@@ -1,18 +0,0 @@
-import { Logo } from "@app/ui/Logo";
-import { type AppSwitcherProps } from "@core/components/shared/AppSwitcher";
-
-/**
- * Desktop inherits proprietary's layers but does not ship the portal (see
- * desktop/routes/adminRouteExtensions), so there's nothing to switch to —
- * shadow the brand header back to a plain logo. (Also avoids the desktop
- * bundle referencing @portal via the proprietary switcher's imports.)
- */
-export function AppSwitcher({ collapsed }: AppSwitcherProps) {
- return (
-
+ {
- const next = !c;
- writePersistedSidebarCollapsed(next);
- return next;
- });
- }}
- onOpenSettings={() => setConfigModalOpen(true)}
- />
+ toggleIcon={
+ navigationState.workbench === "myFiles" ? (
+
- openSettings()} />
+
{children}
diff --git a/frontend/editor/src/portal/components/EditorStatusCard.tsx b/frontend/editor/src/portal/components/EditorStatusCard.tsx
index e4918ed859..774dc4d1be 100644
--- a/frontend/editor/src/portal/components/EditorStatusCard.tsx
+++ b/frontend/editor/src/portal/components/EditorStatusCard.tsx
@@ -11,31 +11,9 @@ import {
import { type EditorInstance } from "@portal/api/editorDeploy";
import { DownloadEditorModal } from "@portal/components/DownloadEditorModal";
import "@portal/theme/surface.css";
+import { BrandTile } from "@app/components/shared/BrandTile";
import "@portal/components/EditorStatusCard.css";
-/** The Stirling brand mark, drawn at the hero size. Decorative. */
-function StirlingMark() {
- return (
-
- );
-}
-
/** The instance to headline: the busiest healthy one, else the first. */
function primaryInstance(instances: EditorInstance[]): EditorInstance | null {
if (instances.length === 0) return null;
@@ -126,7 +104,7 @@ export function EditorStatusCard({ footer }: EditorStatusCardProps) {
>
+
{mobileNavOpen && (
-
+ {/* Phone only: above that the rail carries it, and this would be a second. */}
+ {isPhone && (
+
+
+ )}
-
diff --git a/frontend/editor/src/portal/components/PortalSearchBar.css b/frontend/editor/src/portal/components/PortalSearchBar.css
index 8e253b6136..847991af20 100644
--- a/frontend/editor/src/portal/components/PortalSearchBar.css
+++ b/frontend/editor/src/portal/components/PortalSearchBar.css
@@ -1,5 +1,4 @@
-/* Unpainted strip at the top of the main column. Height matches the sidebar's
- logo row (.portal-sidebar__logo, 51px) so the search lines up with the brand. */
+/* Unpainted strip at the top of the main column, matching the sidebar header's height. */
.portal-searchbar {
display: flex;
align-items: center;
diff --git a/frontend/editor/src/portal/components/Sidebar.css b/frontend/editor/src/portal/components/Sidebar.css
index 48b54b177d..43f8c44695 100644
--- a/frontend/editor/src/portal/components/Sidebar.css
+++ b/frontend/editor/src/portal/components/Sidebar.css
@@ -1,8 +1,10 @@
.portal-sidebar {
- width: 15rem;
+ width: var(--sidebar-w);
height: 100vh;
height: 100dvh; /* track mobile browser chrome */
- background: var(--c-bg);
+ /* Matches the editor's sidebar: one solid panel with a rule on the content side. */
+ background: var(--c-surface);
+ border-inline-end: 1px solid var(--c-border-subtle);
display: flex;
flex-direction: column;
flex-shrink: 0;
@@ -21,10 +23,6 @@
/* Nav labels stay on one line and are clipped by the narrowing rail so they
reveal/hide cleanly as the width animates rather than wrapping. */
-.portal-sidebar__nav,
-.portal-sidebar__footer {
- overflow-x: hidden;
-}
.portal-sidebar .sui-navitem__label,
.portal-sidebar__section-label {
white-space: nowrap;
@@ -34,6 +32,8 @@
.portal-sidebar__close {
display: none;
flex-shrink: 0;
+ /* Trailing edge: on mobile this is the row's only control. */
+ margin-left: auto;
}
.portal-sidebar__collapse {
@@ -78,23 +78,16 @@
/* ---- Collapsed icon rail (desktop only) ---- */
.portal-sidebar[data-collapsed] {
- width: var(--nav-rail-w);
-}
-.portal-sidebar[data-collapsed] .portal-sidebar__logo {
- flex-direction: column;
- height: auto;
- padding: 0.5rem 0;
- gap: 0.375rem;
-}
-.portal-sidebar[data-collapsed] .portal-sidebar__collapse {
- margin-left: 0;
+ width: var(--sidebar-collapsed-w);
}
+/* Flush, like the nav: the selected row runs the full width of the rail. */
.portal-sidebar[data-collapsed] .portal-sidebar__nav {
- padding-inline: 0.375rem;
+ padding-inline: 0;
}
+/* Stretch, not centre: a centred group shrinks to its content, so rows can't fill the rail. */
.portal-sidebar[data-collapsed] .portal-sidebar__section {
padding-inline: 0;
- align-items: center;
+ align-items: stretch;
}
.portal-sidebar[data-collapsed] .portal-sidebar__section-label {
display: none;
@@ -111,23 +104,16 @@
margin-inline: 0;
padding-inline: 0;
width: 100%;
-}
-/* Neutralise the active-item edge-bar geometry (negative margins + overhang)
- that assumes the full-width rail. */
-.portal-sidebar[data-collapsed] .sui-navitem.is-active {
- width: 100%;
- margin-inline: 0;
- border-left: none;
- border-radius: 0.5rem;
- padding-left: 0;
+ /* A square target, so it takes the rail's radius rather than NavItem's pill. */
+ border-radius: var(--radius-md);
}
.portal-sidebar[data-collapsed] .portal-sidebar__footer {
margin-inline: 0.375rem;
}
-.portal-sidebar__logo {
- height: 3.1875rem; /* 51px */
- padding: 0 0.875rem;
+.portal-sidebar__header {
+ height: var(--nav-header-h);
+ padding: 0 var(--nav-gutter);
display: flex;
align-items: center;
gap: 0.5rem;
@@ -136,35 +122,58 @@
.portal-sidebar__nav {
flex: 0 1 auto;
overflow-y: auto;
- padding: 0.75rem 0.625rem;
+ overflow-x: clip;
+ /* No inline inset above the rows, so a row is full width and needs no bleed past the clip. */
+ padding: var(--nav-gutter) 0;
display: flex;
flex-direction: column;
- gap: 0.5rem;
+ gap: var(--nav-gutter);
}
.portal-sidebar .sui-navitem {
- margin-inline: 0.25rem;
- padding-inline: 0.625rem;
+ margin-inline: 0;
+ padding-inline: 1.75rem;
}
-.portal-sidebar .sui-navitem.is-active {
- width: calc(100% + 0.75rem);
- margin-inline: -0.375rem;
+/* The selected view, marked as the rail marks the current app: a knocked-out solid block. */
+.portal-sidebar .sui-navitem.is-active,
+.portal-sidebar .sui-navitem.is-active:hover {
+ background: var(--c-text);
+ color: var(--c-surface);
border-radius: 0;
- border-left: 3px solid var(--c-primary);
- padding-left: calc(1.25rem - 3px);
+}
+
+/* On a dark ground full ink is white, so mix the block back toward the surface. */
+[data-theme="dark"] .portal-sidebar .sui-navitem.is-active,
+[data-theme="dark"] .portal-sidebar .sui-navitem.is-active:hover,
+html[data-app-theme="midnight"] .portal-sidebar .sui-navitem.is-active,
+html[data-app-theme="midnight"] .portal-sidebar .sui-navitem.is-active:hover,
+[data-mantine-color-scheme="dark"] .portal-sidebar .sui-navitem.is-active,
+[data-mantine-color-scheme="dark"]
+ .portal-sidebar
+ .sui-navitem.is-active:hover {
+ background: color-mix(in srgb, var(--c-text) 80%, var(--c-surface));
+ color: var(--c-surface);
}
.portal-sidebar__section {
- padding: 0.5rem 0.375rem 0.375rem;
+ padding: 0.5rem 0 0.375rem;
display: flex;
flex-direction: column;
gap: 0.375rem;
}
+/* Flattened here; two classes deep to beat .sui-nav-surface regardless of load order. */
+.portal-sidebar .sui-nav-surface {
+ background: transparent;
+ border: 0;
+ border-radius: 0;
+}
+
.portal-sidebar__section-label {
margin: 0;
- padding: 0 0.5rem;
+ /* Its own 0.5rem, plus the inset the nav and section no longer add. */
+ padding: 0 1.375rem;
font-size: 0.8125rem;
font-weight: 600;
letter-spacing: 0.02em;
@@ -181,4 +190,18 @@
only positions it. */
.portal-sidebar__footer {
margin: 0 0.625rem 0.75rem;
+ overflow-x: hidden;
+}
+
+/* Fills the frame, not the viewport: a 100vh sticky column would overhang it. */
+.workspace-frame .portal-sidebar {
+ height: 100%;
+ position: static;
+}
+
+@media (max-width: 48rem) {
+ .workspace-frame .portal-sidebar {
+ position: fixed;
+ height: auto;
+ }
}
diff --git a/frontend/editor/src/portal/components/Sidebar.tsx b/frontend/editor/src/portal/components/Sidebar.tsx
index 685fa32722..2895ad4ec4 100644
--- a/frontend/editor/src/portal/components/Sidebar.tsx
+++ b/frontend/editor/src/portal/components/Sidebar.tsx
@@ -1,20 +1,16 @@
import { useMediaQuery } from "@mantine/hooks";
import { Tooltip } from "@mantine/core";
import { ActionIcon, NavItem, NavSurface } from "@app/ui";
-import { BrandSwitcher } from "@app/components/shared/BrandSwitcher";
+import { SidebarToggleButton } from "@app/components/shared/SidebarToggleButton";
+import { Logo } from "@app/ui/Logo";
import { NavFooter } from "@app/components/shared/navFooter/NavFooter";
import { useAccountIdentity } from "@app/hooks/useAccountIdentity";
import { useFreeCreditsSummary } from "@portal/hooks/useFreeCreditsSummary";
import { useOpenPlan } from "@portal/hooks/useOpenPlan";
-import { SidebarToggleIcon } from "@app/components/shared/SidebarToggleIcon";
import { useTranslation } from "react-i18next";
-import { useNavigate } from "react-router-dom";
import { useView, type ViewId } from "@portal/contexts/ViewContext";
import { useUI } from "@portal/contexts/UIContext";
import { LinkAccountFooterItem } from "@portal/components/LinkAccountFooterItem";
-import { EDITOR_URL, EDITOR_IS_SAME_APP } from "@portal/auth/editorUrl";
-import { EDITOR_BASENAME } from "@app/routes/editorBasename";
-import { takeEditorReturnPath } from "@app/services/workbenchSession";
import { CloseIcon } from "@portal/components/icons";
import {
GROUP_PROCESSOR,
@@ -30,19 +26,17 @@ const NAV_SECTIONS: NavGroup[] = [
];
/** Must match the shell breakpoint in AppShell.css / Sidebar.css. */
-const MOBILE_QUERY = "(max-width: 48rem)";
+export const MOBILE_QUERY = "(max-width: 48rem)";
export function Sidebar() {
const { activeView, setActiveView } = useView();
const {
- openSettings,
mobileNavOpen,
closeMobileNav,
sidebarCollapsed,
toggleSidebarCollapsed,
} = useUI();
const { t } = useTranslation();
- const navigate = useNavigate();
const isMobile = useMediaQuery(MOBILE_QUERY, false, {
getInitialValueInEffect: false,
});
@@ -54,14 +48,6 @@ export function Sidebar() {
// off-canvas drawer, so the icon-rail state never applies there.
const collapsed = sidebarCollapsed && !isMobile;
- // Editor and portal are one SPA when the editor serves this origin's root, so
- // the switch stays client-side; an absolute EDITOR_URL (dev cross-app setup)
- // needs a full page load.
- const goToEditor = () => {
- if (EDITOR_IS_SAME_APP) navigate(takeEditorReturnPath() ?? EDITOR_BASENAME);
- else window.location.href = EDITOR_URL;
- };
-
// Procurement is no longer a nav tab — it lives on Home as the deal-status hero and expands into
// a takeover modal (matching the marketing prototype).
@@ -107,25 +93,13 @@ export function Sidebar() {
// Off-canvas on mobile: remove from the tab order and accessibility tree.
inert={isMobile && !mobileNavOpen}
>
-
-
+ {!collapsed &&
-
+
-
-
-
-
-
-
-
- }
- />
+ {/* All other routes need AppProviders for backend integration. RootGate
+ routes "/" by role before any of it mounts. */}
+
+
+
+
+ {/* Not the app: no rail over any of these, ever. */}
+
+ {/* The editor and its tool routes - Landing handles auth logic */}
+
);
diff --git a/frontend/editor/src/proprietary/components/shared/AppSwitcher.tsx b/frontend/editor/src/proprietary/components/shared/AppSwitcher.tsx
deleted file mode 100644
index 9ba0b6438d..0000000000
--- a/frontend/editor/src/proprietary/components/shared/AppSwitcher.tsx
+++ /dev/null
@@ -1,35 +0,0 @@
-import { Logo } from "@app/ui/Logo";
-import { BrandSwitcher } from "@app/components/shared/BrandSwitcher";
-import { type AppSwitcherProps } from "@core/components/shared/AppSwitcher";
-import { useOtherAppSwitch } from "@app/hooks/useOtherAppSwitch";
-
-/**
- * Sidebar brand header for builds that ship the processor. When this user can
- * open it, the Stirling logo doubles as the editor⇄processor switcher: the mark
- * morphs into a chevron and opens the switch menu (the same BrandSwitcher the
- * processor sidebar uses). Users without access get a plain logo.
- *
- * The access gate lives in {@link useOtherAppSwitch} so this header and the
- * sidebar footer's "Open PDF Processor" row are driven by one answer.
- */
-export function AppSwitcher({ collapsed }: AppSwitcherProps) {
- const otherApp = useOtherAppSwitch();
-
- if (!otherApp) {
- return (
- (null);
const modRef = useRef(null);
- const active = enabled && includePortal;
+ // Without the portal these entities have nowhere to open, so don't fetch them.
+ const active = enabled && HAS_PORTAL;
const hasQuery = trimmed.length > 0;
useEffect(() => {
diff --git a/frontend/editor/src/proprietary/data/processorSearchIndex.ts b/frontend/editor/src/proprietary/data/processorSearchIndex.ts
index ae48893e25..8d99b2f77a 100644
--- a/frontend/editor/src/proprietary/data/processorSearchIndex.ts
+++ b/frontend/editor/src/proprietary/data/processorSearchIndex.ts
@@ -3,15 +3,10 @@ import { PORTAL_BASENAME } from "@app/routes/portalBasename";
// the lazy portal chunk into the main bundle the way @portal/* values would.
import { usersCapabilities } from "@app/portal/usersCapabilities";
import type { ProcessorSearchEntry } from "@core/data/processorSearchIndex";
+import { HAS_PORTAL } from "@app/routes/hasPortal";
export type { ProcessorSearchEntry };
-// Mirrors the admin-route seam's gate: the portal route-set is only mounted in
-// dev and in builds made with VITE_INCLUDE_PORTAL=true, so the search must not
-// offer destinations that would 404 elsewhere.
-const includePortal =
- import.meta.env.VITE_INCLUDE_PORTAL === "true" || import.meta.env.DEV;
-
/**
* The portal's in-app views. Deliberately a static mirror of the portal's nav
* (labels via the same portal.nav.* keys its sidebar uses) rather than an
@@ -91,7 +86,8 @@ const VIEWS: ProcessorSearchEntry[] = [
},
];
-export const PROCESSOR_SEARCH_INDEX: ProcessorSearchEntry[] = includePortal
+// Empty without the portal: these destinations would 404.
+export const PROCESSOR_SEARCH_INDEX: ProcessorSearchEntry[] = HAS_PORTAL
? VIEWS
: [];
diff --git a/frontend/editor/src/proprietary/routes/Landing.tsx b/frontend/editor/src/proprietary/routes/Landing.tsx
index 62c9083aad..7406078d30 100644
--- a/frontend/editor/src/proprietary/routes/Landing.tsx
+++ b/frontend/editor/src/proprietary/routes/Landing.tsx
@@ -2,6 +2,7 @@ import { useEffect } from "react";
import { Navigate, useLocation, useNavigate } from "react-router-dom";
import { useAuth } from "@app/auth/UseSession";
import { useAppConfig } from "@app/contexts/AppConfigContext";
+import { useSuppressQuickNavRail } from "@app/contexts/QuickNavHostContext";
import HomePage from "@app/pages/HomePage";
import { useBackendProbe } from "@app/hooks/useBackendProbe";
import { EDITOR_BASENAME } from "@app/routes/editorBasename";
@@ -27,6 +28,9 @@ export default function Landing() {
const loading = authLoading || configLoading || backendProbe.loading;
+ // The backend-down screen is not the app. Loading is: it resolves in a moment.
+ useSuppressQuickNavRail(!session && backendProbe.status !== "up");
+
// Debug: Track Landing component lifecycle
useEffect(() => {
const mountId = Math.random().toString(36).substring(7);
diff --git a/frontend/editor/src/proprietary/routes/adminRouteExtensions.tsx b/frontend/editor/src/proprietary/routes/adminRouteExtensions.tsx
index 22ce46f03c..a422376086 100644
--- a/frontend/editor/src/proprietary/routes/adminRouteExtensions.tsx
+++ b/frontend/editor/src/proprietary/routes/adminRouteExtensions.tsx
@@ -2,11 +2,9 @@ import { lazy } from "react";
import type { ReactElement } from "react";
import { Route } from "react-router-dom";
import { PORTAL_BASENAME } from "@app/routes/portalBasename";
+import { HAS_PORTAL } from "@app/routes/hasPortal";
-const includePortal =
- import.meta.env.VITE_INCLUDE_PORTAL === "true" || import.meta.env.DEV;
-
-const PortalApp = includePortal
+const PortalApp = HAS_PORTAL
? lazy(async () => {
const m = await import("@portal/PortalApp");
return { default: m.PortalApp };
@@ -16,7 +14,7 @@ const PortalApp = includePortal
/**
* Return leg of the account-link handshake, which Stirling redirects to with the admin's session in the URL fragment.
*/
-const ConnectCallback = includePortal
+const ConnectCallback = HAS_PORTAL
? lazy(async () => {
const m = await import("@portal/views/ConnectCallback");
return { default: m.default };
diff --git a/frontend/editor/src/proprietary/routes/hasPortal.ts b/frontend/editor/src/proprietary/routes/hasPortal.ts
new file mode 100644
index 0000000000..e3c54bc50e
--- /dev/null
+++ b/frontend/editor/src/proprietary/routes/hasPortal.ts
@@ -0,0 +1,3 @@
+/** Dev always ships it, so the switch is there to work on. */
+export const HAS_PORTAL =
+ import.meta.env.VITE_INCLUDE_PORTAL === "true" || import.meta.env.DEV;
diff --git a/frontend/editor/src/saas/App.tsx b/frontend/editor/src/saas/App.tsx
index 2e091ebf05..07a563ea5f 100644
--- a/frontend/editor/src/saas/App.tsx
+++ b/frontend/editor/src/saas/App.tsx
@@ -19,6 +19,8 @@ import OAuthConsent from "@app/routes/OAuthConsent";
import ConnectApprove from "@app/routes/ConnectApprove";
import ShareLinkPage from "@app/routes/ShareLinkPage";
import { getAdminRouteExtensions } from "@app/routes/adminRouteExtensions";
+import { AppFrame } from "@app/components/layout/AppFrame";
+import { NoAppChrome } from "@app/components/layout/NoAppChrome";
import OnboardingBootstrap from "@app/components/OnboardingBootstrap";
import SignupRequiredBootstrap from "@app/components/SignupRequiredBootstrap";
import UsageLimitModalHost from "@app/components/UsageLimitModalHost";
@@ -96,46 +98,63 @@ export default function App() {
}
/>
- {/* Admin-only route-set (the portal): its own top-level shell, mounted
- before the catch-all. */}
- {getAdminRouteExtensions()}
+ {/* Both apps, under a shared frame so the rail renders once outside them. */}
+
-
-
-
-
-
-
-
- }
- />
+ {/* Everything else needs the auth/backend providers. RootGate routes "/"
+ by role before any of it mounts. */}
+
+
+
+
+ {/* Not the app: no rail over any of these, ever. */}
+
+
);
From a48356a2d22babeae7ad7c66673bee9a405fa083 Mon Sep 17 00:00:00 2001
From: Anthony Stirling <77850077+Frooodle@users.noreply.github.com>
Date: Thu, 27 Aug 2026 23:17:21 +0100
Subject: [PATCH 09/27] Deploy a dev SaaS server alongside the PR previews and
main demo (#7697)
---
.github/workflows/Saas-Dev-Deploy.yml | 246 ++++++++++++++++++++++++++
1 file changed, 246 insertions(+)
create mode 100644 .github/workflows/Saas-Dev-Deploy.yml
diff --git a/.github/workflows/Saas-Dev-Deploy.yml b/.github/workflows/Saas-Dev-Deploy.yml
new file mode 100644
index 0000000000..733b92bca2
--- /dev/null
+++ b/.github/workflows/Saas-Dev-Deploy.yml
@@ -0,0 +1,246 @@
+name: Auto SaaS Dev Deployment
+
+on:
+ push:
+ branches:
+ - saas-prod
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+env:
+ FRONTEND_PORT: "901"
+ BACKEND_PORT: "902"
+ DEPLOY_DIR: /stirling/SAAS-DEV
+
+jobs:
+ deploy-saas-dev:
+ runs-on: ubuntu-latest
+ environment: saas-dev
+ concurrency:
+ group: saas-dev-deploy
+ cancel-in-progress: true
+ permissions:
+ contents: read
+ packages: write
+
+ steps:
+ - name: Harden Runner
+ uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+ with:
+ egress-policy: audit
+
+ - name: Check SaaS configuration
+ id: config
+ env:
+ PROJECT_REF: ${{ secrets.SAAS_DB_PROJECT_REF }}
+ run: |
+ echo "supabase_url=https://${PROJECT_REF}.supabase.co" >> "$GITHUB_OUTPUT"
+ echo "meter_endpoint=https://${PROJECT_REF}.supabase.co/functions/v1/meter-payg-units" >> "$GITHUB_OUTPUT"
+
+ - name: Checkout repository
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ fetch-depth: 0
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+
+ - name: Login to GitHub Container Registry
+ uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ github.token }}
+
+ - name: Convert repository owner to lowercase
+ id: repoowner
+ run: echo "lowercase=$(echo ${{ github.repository_owner }} | awk '{print tolower($0)}')" >> $GITHUB_OUTPUT
+
+ - name: Get commit hash
+ id: commit-hash
+ run: echo "app_short=$(git rev-parse --short=8 HEAD)" >> $GITHUB_OUTPUT
+
+ - name: Build and push backend image
+ uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+ with:
+ context: .
+ file: ./docker/backend/Dockerfile
+ push: true
+ cache-from: type=gha,scope=stirling-saas-backend
+ cache-to: type=gha,mode=max,scope=stirling-saas-backend
+ tags: |
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-backend-${{ steps.commit-hash.outputs.app_short }}
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-backend-latest
+ build-args: |
+ VERSION_TAG=v2-alpha
+ STIRLING_FLAVOR=saas
+ platforms: linux/amd64
+
+ - name: Build and push frontend image
+ uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+ with:
+ context: .
+ file: ./docker/frontend/Dockerfile
+ push: true
+ cache-from: type=gha,scope=stirling-saas-frontend
+ cache-to: type=gha,mode=max,scope=stirling-saas-frontend
+ tags: |
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-frontend-${{ steps.commit-hash.outputs.app_short }}
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-frontend-latest
+ build-args: |
+ VERSION_TAG=v2-alpha
+ STIRLING_FLAVOR=saas
+ VITE_BUILD_MODE=development
+ VITE_SUPABASE_URL=${{ steps.config.outputs.supabase_url }}
+ VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY=${{ secrets.SAAS_SUPABASE_PUBLISHABLE_KEY }}
+ platforms: linux/amd64
+
+ - name: Build and push AI engine image
+ uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+ with:
+ context: .
+ file: ./engine/Dockerfile
+ push: true
+ cache-from: type=gha,scope=stirling-saas-engine
+ cache-to: type=gha,mode=max,scope=stirling-saas-engine
+ tags: |
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-engine-${{ steps.commit-hash.outputs.app_short }}
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-engine-latest
+ platforms: linux/amd64
+
+ - name: Set up SSH
+ env:
+ SSH_KEY: ${{ secrets.NEW_VPS_SSH_KEY }}
+ run: |
+ mkdir -p ~/.ssh/
+ echo "$SSH_KEY" > ../private.key
+ sudo chmod 600 ../private.key
+
+ - name: Deploy to VPS
+ env:
+ IMAGE_BASE: ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test
+ IMAGE_TAG: ${{ steps.commit-hash.outputs.app_short }}
+ GHCR_USER: ${{ github.actor }}
+ GHCR_TOKEN: ${{ github.token }}
+ VPS_USERNAME: ${{ secrets.NEW_VPS_USERNAME }}
+ VPS_HOST: ${{ secrets.NEW_VPS_HOST }}
+ SAAS_DB_URL: ${{ secrets.SAAS_DB_URL }}
+ SAAS_DB_USERNAME: ${{ secrets.SAAS_DB_USERNAME || 'postgres' }}
+ SAAS_DB_PASSWORD: ${{ secrets.SAAS_DB_PASSWORD }}
+ SAAS_DB_PROJECT_REF: ${{ secrets.SAAS_DB_PROJECT_REF }}
+ SUPABASE_EDGE_FUNCTION_SECRET: ${{ secrets.SUPABASE_EDGE_FUNCTION_SECRET }}
+ PAYG_METER_ENDPOINT: ${{ steps.config.outputs.meter_endpoint }}
+ STIRLING_KEYGEN_ENABLED: ${{ secrets.KEYGEN_ACCOUNT_ID != '' && secrets.KEYGEN_API_TOKEN != '' && secrets.KEYGEN_POLICY_ID != '' }}
+ KEYGEN_ACCOUNT_ID: ${{ secrets.KEYGEN_ACCOUNT_ID }}
+ KEYGEN_API_TOKEN: ${{ secrets.KEYGEN_API_TOKEN }}
+ KEYGEN_POLICY_ID: ${{ secrets.KEYGEN_POLICY_ID }}
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+ VOYAGE_API_KEY: ${{ secrets.VOYAGE_API_KEY }}
+ run: |
+ set -euo pipefail
+
+ BASE_URL="http://${VPS_HOST}:${FRONTEND_PORT}"
+
+ yaml() {
+ printf "'%s'" "$(printf '%s' "$1" | sed -e "s/'/''/g" -e 's/\$/$$/g')"
+ }
+
+ ENGINE_SECRET="$(openssl rand -hex 32)"
+ AI_BACKEND_VARS="
+ SYSTEM_AIENGINE_ENABLED: \"true\"
+ SYSTEM_AIENGINE_URL: \"http://saas-engine:5001\"
+ APP_AI_SERVICEBASEURL: \"http://saas-engine:5001\"
+ STIRLING_ENGINE_SHARED_SECRET: $(yaml "$ENGINE_SECRET")"
+ AI_SERVICE="
+
+ saas-engine:
+ container_name: stirling-saas-dev-engine
+ image: ${IMAGE_BASE}:saas-engine-${IMAGE_TAG}
+ environment:
+ ANTHROPIC_API_KEY: $(yaml "$ANTHROPIC_API_KEY")
+ VOYAGE_API_KEY: $(yaml "$VOYAGE_API_KEY")
+ STIRLING_ENGINE_SHARED_SECRET: $(yaml "$ENGINE_SECRET")
+ restart: on-failure:5"
+
+ cat > docker-compose.yml << EOF
+ version: '3.3'
+ services:
+ saas-backend:
+ container_name: stirling-saas-dev-backend
+ image: ${IMAGE_BASE}:saas-backend-${IMAGE_TAG}
+ ports:
+ - "${BACKEND_PORT}:8080"
+ volumes:
+ - ${DEPLOY_DIR}/config:/configs:rw
+ - ${DEPLOY_DIR}/logs:/logs:rw
+ - ${DEPLOY_DIR}/storage:/storage:rw
+ environment:
+ SPRING_PROFILES_ACTIVE: "saas"
+ DISABLE_ADDITIONAL_FEATURES: "false"
+ SAAS_DB_URL: $(yaml "$SAAS_DB_URL")
+ SAAS_DB_USERNAME: $(yaml "$SAAS_DB_USERNAME")
+ SAAS_DB_PASSWORD: $(yaml "$SAAS_DB_PASSWORD")
+ SAAS_DB_PROJECT_REF: $(yaml "$SAAS_DB_PROJECT_REF")
+ SUPABASE_EDGE_FUNCTION_SECRET: $(yaml "$SUPABASE_EDGE_FUNCTION_SECRET")
+ PAYG_METER_ENDPOINT: $(yaml "$PAYG_METER_ENDPOINT")
+ STIRLING_KEYGEN_ENABLED: $(yaml "$STIRLING_KEYGEN_ENABLED")
+ KEYGEN_ACCOUNT_ID: $(yaml "$KEYGEN_ACCOUNT_ID")
+ KEYGEN_API_TOKEN: $(yaml "$KEYGEN_API_TOKEN")
+ KEYGEN_POLICY_ID: $(yaml "$KEYGEN_POLICY_ID")
+ SYSTEM_DEFAULTLOCALE: en-US
+ SYSTEM_MAXFILESIZE: "100"
+ METRICS_ENABLED: "true"
+ SYSTEM_GOOGLEVISIBILITY: "false"
+ SWAGGER_SERVER_URL: "${BASE_URL}"
+ baseUrl: "${BASE_URL}"${AI_BACKEND_VARS}
+ restart: on-failure:5
+
+ saas-frontend:
+ container_name: stirling-saas-dev-frontend
+ image: ${IMAGE_BASE}:saas-frontend-${IMAGE_TAG}
+ ports:
+ - "${FRONTEND_PORT}:80"
+ environment:
+ VITE_API_BASE_URL: "http://saas-backend:8080"
+ depends_on:
+ - saas-backend
+ restart: on-failure:5${AI_SERVICE}
+ EOF
+
+ SSH_OPTS=(-i ../private.key -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null)
+
+ scp "${SSH_OPTS[@]}" docker-compose.yml "${VPS_USERNAME}@${VPS_HOST}:/tmp/saas-dev-docker-compose.yml"
+
+ ssh "${SSH_OPTS[@]}" -T "${VPS_USERNAME}@${VPS_HOST}" << ENDSSH
+ set -e
+ mkdir -p ${DEPLOY_DIR}/{config,logs,storage}
+ mv /tmp/saas-dev-docker-compose.yml ${DEPLOY_DIR}/docker-compose.yml
+ chmod 600 ${DEPLOY_DIR}/docker-compose.yml
+ cd ${DEPLOY_DIR}
+ printf '%s' "${GHCR_TOKEN}" | docker login ghcr.io -u "${GHCR_USER}" --password-stdin
+ docker-compose down --remove-orphans 2>/dev/null || true
+ docker-compose pull
+ docker-compose up -d
+ docker logout ghcr.io >/dev/null 2>&1 || true
+ docker image prune -af --filter "until=336h" --filter "label!=keep=true" || true
+ ENDSSH
+
+ - name: Wait for the backend to answer
+ env:
+ VPS_HOST: ${{ secrets.NEW_VPS_HOST }}
+ run: |
+ URL="http://${VPS_HOST}:${BACKEND_PORT}/api/v1/info/status"
+ for i in $(seq 1 60); do
+ code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$URL" || true)
+ if [ "$code" = "200" ]; then echo "Healthy after $((i * 10))s"; exit 0; fi
+ sleep 10
+ done
+ echo "::error::SaaS dev backend did not become healthy within 10 minutes"
+ exit 1
+
+ - name: Cleanup temporary files
+ if: always()
+ run: rm -f ../private.key docker-compose.yml
+ continue-on-error: true
From 849d616451feb79b706ad6f9a9250924327b0020 Mon Sep 17 00:00:00 2001
From: James Brunton
Date: Thu, 27 Aug 2026 23:45:10 +0100
Subject: [PATCH 10/27] Fix refreshing causing you to go to the Processor
(#7694)
---
.../common/util/RequestUriUtilsTest.java | 10 ++++++++
.../configuration/SecurityConfiguration.java | 6 ++---
.../src/proprietary/routes/Login.test.tsx | 23 ++++++++++++++++++-
.../editor/src/proprietary/routes/Login.tsx | 8 +++++--
.../proprietary/services/apiClientSetup.ts | 4 ++++
5 files changed, 45 insertions(+), 6 deletions(-)
diff --git a/app/common/src/test/java/stirling/software/common/util/RequestUriUtilsTest.java b/app/common/src/test/java/stirling/software/common/util/RequestUriUtilsTest.java
index 72e5eae9a2..c144f9726e 100644
--- a/app/common/src/test/java/stirling/software/common/util/RequestUriUtilsTest.java
+++ b/app/common/src/test/java/stirling/software/common/util/RequestUriUtilsTest.java
@@ -113,6 +113,16 @@ class RequestUriUtilsTest {
assertTrue(RequestUriUtils.isFrontendRoute("", "/split-pdf"));
}
+ @Test
+ void testIsFrontendRoute_editorRouteOwnedByFrontend() {
+ // /editor (and its tool routes) is an SPA route: a direct-nav/refresh must
+ // serve index.html, not the auth filter's 302-to-/login. Regression test for
+ // the editor moving from / to /editor, whose refresh bounced processor users
+ // to the processor because the redirect dropped the return path.
+ assertTrue(RequestUriUtils.isFrontendRoute("", "/editor"));
+ assertTrue(RequestUriUtils.isFrontendRoute("/app", "/app/editor"));
+ }
+
@Test
void testIsFrontendRoute_filesRouteOwnedByFrontend() {
// /files and /files/ are FileManagerView routes - they
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java
index 9fc4428f73..0f0c7315d9 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java
@@ -357,12 +357,12 @@ public class SecurityConfiguration {
req -> {
String uri = req.getRequestURI();
String contextPath = req.getContextPath();
- // Check if it's a public auth endpoint or static
- // resource
return RequestUriUtils.isStaticResource(
contextPath, uri)
|| RequestUriUtils.isPublicAuthEndpoint(
- uri, contextPath);
+ uri, contextPath)
+ || RequestUriUtils.isFrontendRoute(
+ contextPath, uri);
})
.permitAll()
.anyRequest()
diff --git a/frontend/editor/src/proprietary/routes/Login.test.tsx b/frontend/editor/src/proprietary/routes/Login.test.tsx
index 29ae9d9d79..5553f202fb 100644
--- a/frontend/editor/src/proprietary/routes/Login.test.tsx
+++ b/frontend/editor/src/proprietary/routes/Login.test.tsx
@@ -234,7 +234,10 @@ describe("Login", () => {
);
};
- afterEach(() => window.history.replaceState({}, "", "/"));
+ afterEach(() => {
+ window.history.replaceState({}, "", "/");
+ sessionStorage.clear();
+ });
it("returns to where the user came from", async () => {
signedIn();
@@ -247,6 +250,24 @@ describe("Login", () => {
});
});
+ // A full-page 401 redirect drops router state and Spring can strip ?from=,
+ // leaving the return path only in the sessionStorage stash. Without reading
+ // it here a processor user refreshing /editor falls through to the role
+ // router and lands on the processor.
+ it("returns to the stashed path when there is no ?from=", async () => {
+ signedIn();
+ sessionStorage.setItem("stirling_post_login_path", "/compress");
+ renderAtLogin("");
+
+ await waitFor(() => {
+ expect(mockNavigate).toHaveBeenCalledWith("/compress", {
+ replace: true,
+ });
+ });
+ // Consumed, so a later sign-in can't reuse a stale path.
+ expect(sessionStorage.getItem("stirling_post_login_path")).toBeNull();
+ });
+
// Delegated to the shared isSafePostLoginRedirect, so the backslash form
// (browsers normalise "\" to "/") and auth routes are covered too.
it.each([
diff --git a/frontend/editor/src/proprietary/routes/Login.tsx b/frontend/editor/src/proprietary/routes/Login.tsx
index b134d9ee89..7fd3e86670 100644
--- a/frontend/editor/src/proprietary/routes/Login.tsx
+++ b/frontend/editor/src/proprietary/routes/Login.tsx
@@ -7,7 +7,10 @@ import {
} from "react-router-dom";
import { Button } from "@app/ui/Button";
import { isSafePostLoginRedirect } from "@app/auth";
-import { setPostLoginRedirectPath } from "@app/auth/spring/springAuthClient";
+import {
+ setPostLoginRedirectPath,
+ consumePostLoginRedirectPath,
+} from "@app/auth/spring/springAuthClient";
import { useAuth } from "@app/auth/UseSession";
import { useAppConfig } from "@app/contexts/AppConfigContext";
import { useTranslation } from "react-i18next";
@@ -207,7 +210,8 @@ export default function Login() {
useEffect(() => {
if (loading) return;
if (!session) return;
- const returnPath = resolveReturnPath();
+ const stashed = consumePostLoginRedirectPath();
+ const returnPath = resolveReturnPath() ?? stashed;
if (returnPath) {
navigate(returnPath, { replace: true });
return;
diff --git a/frontend/editor/src/proprietary/services/apiClientSetup.ts b/frontend/editor/src/proprietary/services/apiClientSetup.ts
index 8615156e9a..3f50e1bb4c 100644
--- a/frontend/editor/src/proprietary/services/apiClientSetup.ts
+++ b/frontend/editor/src/proprietary/services/apiClientSetup.ts
@@ -1,6 +1,7 @@
import { AxiosInstance, AxiosError, InternalAxiosRequestConfig } from "axios";
import { withBasePath } from "@app/constants/app";
import { getBrowserId } from "@app/utils/browserIdentifier";
+import { setPostLoginRedirectPath } from "@app/auth/spring/springAuthClient";
let isRefreshing = false;
let failedQueue: Array<{
@@ -93,6 +94,9 @@ async function refreshAuthToken(client: AxiosInstance): Promise {
// Redirect to login
const loginPath = withBasePath("/login");
if (window.location.pathname !== loginPath) {
+ setPostLoginRedirectPath(
+ window.location.pathname + window.location.search,
+ );
console.log("[API Client] Redirecting to login page...");
window.location.href = loginPath;
}
From 0a3f0c181474e1b0ebd03744330481aee6f495be Mon Sep 17 00:00:00 2001
From: James Brunton
Date: Fri, 28 Aug 2026 10:03:52 +0000
Subject: [PATCH 11/27] Fix redirect bugs in SaaS (#7721)
# Description of Changes
Fixes various bugs that affected SaaS (and some self-hosted):
- Refreshing on Editor caused the user to be redirected to Processor
- User was unable to access Processor in SaaS
- Deep link hijacking fixes
- Fix double prefix `/app/app` issue
- Fix going from tool -> editor -> processor -> editor putting you back
into tool
---------
Co-authored-by: Anthony Stirling <77850077+Frooodle@users.noreply.github.com>
---
.../shared/quickNav/QuickNavRailHost.tsx | 4 +-
.../src/core/contexts/ToolWorkflowContext.tsx | 16 +++
.../editor/src/core/hooks/useUrlSync.test.tsx | 80 +++++++++++
frontend/editor/src/core/hooks/useUrlSync.ts | 30 +++-
.../httpErrorHandler.basePath.test.ts | 76 +++++++++++
.../src/core/services/httpErrorHandler.ts | 28 ++--
.../core/services/postLoginRedirect.test.ts | 39 ++++++
.../src/core/services/postLoginRedirect.ts | 15 ++
.../core/services/workbenchSession.test.ts | 8 +-
.../src/core/services/workbenchSession.ts | 5 +-
.../auth/spring/springAuthClient.ts | 22 +--
.../proprietary/auth/supabase/UseSession.tsx | 14 +-
.../auth/supabase/portalAccessFetch.test.tsx | 128 ++++++++++++++++++
.../hooks/useOtherAppSwitch.test.tsx | 5 +-
.../proprietary/hooks/useOtherAppSwitch.ts | 5 +-
.../proprietary/services/apiClientSetup.ts | 6 +-
.../services/postLoginRedirect.test.ts | 25 ++++
.../proprietary/services/postLoginRedirect.ts | 7 +
.../src/saas/hooks/useOtherAppSwitch.ts | 5 +-
.../editor/src/saas/routes/AuthCallback.tsx | 21 ++-
frontend/editor/src/saas/routes/Login.tsx | 13 +-
.../src/saas/services/apiClient.test.ts | 51 ++++++-
.../editor/src/saas/services/apiClient.ts | 25 +++-
23 files changed, 545 insertions(+), 83 deletions(-)
create mode 100644 frontend/editor/src/core/hooks/useUrlSync.test.tsx
create mode 100644 frontend/editor/src/core/services/httpErrorHandler.basePath.test.ts
create mode 100644 frontend/editor/src/core/services/postLoginRedirect.test.ts
create mode 100644 frontend/editor/src/core/services/postLoginRedirect.ts
create mode 100644 frontend/editor/src/proprietary/auth/supabase/portalAccessFetch.test.tsx
create mode 100644 frontend/editor/src/proprietary/services/postLoginRedirect.test.ts
create mode 100644 frontend/editor/src/proprietary/services/postLoginRedirect.ts
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavRailHost.tsx b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailHost.tsx
index 5c748b36cc..3fba4d7e1f 100644
--- a/frontend/editor/src/core/components/shared/quickNav/QuickNavRailHost.tsx
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailHost.tsx
@@ -20,7 +20,7 @@ const SIZE = "1.125rem";
export function QuickNavRailHost() {
const { t } = useTranslation();
const navigate = useNavigate();
- const { pathname, search } = useLocation();
+ const { pathname } = useLocation();
const host = useQuickNavHost();
const appMounted = Boolean(host?.appMounted);
@@ -74,7 +74,7 @@ export function QuickNavRailHost() {
returnHome();
return;
}
- saveEditorReturnPath(pathname + search);
+ saveEditorReturnPath();
go(PORTAL_BASENAME);
},
},
diff --git a/frontend/editor/src/core/contexts/ToolWorkflowContext.tsx b/frontend/editor/src/core/contexts/ToolWorkflowContext.tsx
index 070442a966..b4ef874184 100644
--- a/frontend/editor/src/core/contexts/ToolWorkflowContext.tsx
+++ b/frontend/editor/src/core/contexts/ToolWorkflowContext.tsx
@@ -29,6 +29,8 @@ import {
isBaseWorkbench,
} from "@app/types/workbench";
import { useNavigationUrlSync } from "@app/hooks/useUrlSync";
+import { stripBasePath } from "@app/constants/app";
+import { EDITOR_BASENAME } from "@app/routes/editorBasename";
import { filterToolRegistryByQuery } from "@app/utils/toolSearch";
import { useToolHistory } from "@app/hooks/tools/useUserToolActivity";
import {
@@ -373,15 +375,28 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
// This runs once to navigate to the user's preferred tab (read/automate)
// instead of always starting on the tools tab.
const hasAppliedStartupView = React.useRef(false);
+ // Set when the startup view picks the tool, so the URL sync knows this
+ // selection came from a preference and must not be written to the address.
+ const startupSelectedToolRef = React.useRef(null);
useEffect(() => {
if (hasAppliedStartupView.current) return;
+ // The URL wins: the startup view decides what you see when you arrive at the
+ // editor's home, never what a deep link to a tool shows. Without this, a
+ // "Reader" preference rewrote every / link to /read.
+ const path = stripBasePath(window.location.pathname);
+ if (path !== "/" && path !== EDITOR_BASENAME) {
+ hasAppliedStartupView.current = true;
+ return;
+ }
const startupView = preferences.defaultStartupView;
if (startupView === "read") {
hasAppliedStartupView.current = true;
+ startupSelectedToolRef.current = "read";
setReaderMode(true);
actions.setSelectedTool("read");
} else if (startupView === "automate") {
hasAppliedStartupView.current = true;
+ startupSelectedToolRef.current = "automate";
actions.setSelectedTool("automate");
setLeftPanelView("toolContent");
}
@@ -573,6 +588,7 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
handleBackToTools,
allTools,
true,
+ startupSelectedToolRef,
);
// Ref-backed wrappers so callback identities stay stable across renders.
diff --git a/frontend/editor/src/core/hooks/useUrlSync.test.tsx b/frontend/editor/src/core/hooks/useUrlSync.test.tsx
new file mode 100644
index 0000000000..e35c7dbd44
--- /dev/null
+++ b/frontend/editor/src/core/hooks/useUrlSync.test.tsx
@@ -0,0 +1,80 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useRef } from "react";
+import type { ToolId } from "@app/types/toolId";
+
+const h = vi.hoisted(() => ({
+ updateToolRoute: vi.fn(),
+ clearToolRoute: vi.fn(),
+}));
+
+vi.mock("@app/utils/urlRouting", () => ({
+ parseToolRoute: () => ({ workbench: "fileEditor", toolId: null }),
+ updateToolRoute: h.updateToolRoute,
+ clearToolRoute: h.clearToolRoute,
+}));
+vi.mock("@app/utils/scarfTracking", () => ({ firePixel: vi.fn() }));
+vi.mock("@app/contexts/AppConfigContext", () => ({
+ useAppConfig: () => ({ config: { premiumEnabled: true } }),
+}));
+
+import { useNavigationUrlSync } from "@app/hooks/useUrlSync";
+
+const registry = {
+ read: { name: "Read", workbench: "viewer" },
+ compress: { name: "Compress", workbench: "fileEditor" },
+} as never;
+
+/** Drives the hook the way ToolWorkflowContext does, with a startup marker. */
+function useHarness(selectedTool: ToolId | null, startupTool: ToolId | null) {
+ const ref = useRef(startupTool);
+ useNavigationUrlSync(selectedTool, vi.fn(), vi.fn(), registry, true, ref);
+ return ref;
+}
+
+describe("useNavigationUrlSync — startup-view selections", () => {
+ beforeEach(() => h.updateToolRoute.mockClear());
+
+ // The default-startup-view preference selects a tool to change the *view*.
+ // Writing it to the address turned every visit to /editor into /read.
+ it("never writes the URL for the startup-applied tool", () => {
+ const { rerender } = renderHook(
+ ({ tool }: { tool: ToolId | null }) => useHarness(tool, "read" as ToolId),
+ { initialProps: { tool: null as ToolId | null } },
+ );
+ rerender({ tool: "read" as ToolId });
+ expect(h.updateToolRoute).not.toHaveBeenCalled();
+ });
+
+ // The effect re-runs whenever the registry identity changes, so a marker that
+ // was consumed on first sight let the second run write /read anyway.
+ it("survives a re-run for the same tool", () => {
+ const { rerender } = renderHook(
+ ({ tool }: { tool: ToolId | null }) => useHarness(tool, "read" as ToolId),
+ { initialProps: { tool: null as ToolId | null } },
+ );
+ rerender({ tool: "read" as ToolId });
+ rerender({ tool: "read" as ToolId });
+ rerender({ tool: "read" as ToolId });
+ expect(h.updateToolRoute).not.toHaveBeenCalled();
+ });
+
+ it("still writes the URL when the user picks a different tool", () => {
+ const { rerender } = renderHook(
+ ({ tool }: { tool: ToolId | null }) => useHarness(tool, "read" as ToolId),
+ { initialProps: { tool: null as ToolId | null } },
+ );
+ rerender({ tool: "read" as ToolId });
+ rerender({ tool: "compress" as ToolId });
+ expect(h.updateToolRoute).toHaveBeenCalledWith("compress", registry, false);
+ });
+
+ it("writes the URL for a tool chosen without a startup marker", () => {
+ const { rerender } = renderHook(
+ ({ tool }: { tool: ToolId | null }) => useHarness(tool, null),
+ { initialProps: { tool: null as ToolId | null } },
+ );
+ rerender({ tool: "read" as ToolId });
+ expect(h.updateToolRoute).toHaveBeenCalledWith("read", registry, false);
+ });
+});
diff --git a/frontend/editor/src/core/hooks/useUrlSync.ts b/frontend/editor/src/core/hooks/useUrlSync.ts
index 5fad71ba29..76fd67178a 100644
--- a/frontend/editor/src/core/hooks/useUrlSync.ts
+++ b/frontend/editor/src/core/hooks/useUrlSync.ts
@@ -2,7 +2,7 @@
* URL synchronization hooks for tool routing with registry support
*/
-import { useEffect, useCallback, useRef } from "react";
+import { useEffect, useCallback, useRef, type MutableRefObject } from "react";
import { ToolId } from "@app/types/toolId";
import {
parseToolRoute,
@@ -24,6 +24,11 @@ export function useNavigationUrlSync(
clearToolSelection: () => void,
registry: ToolRegistry,
enableSync: boolean = true,
+ /**
+ * Tool the default-startup-view preference selected, if any. That selection
+ * sets the view, not the address, so it must not be written to the URL.
+ */
+ startupSelectedToolRef?: MutableRefObject,
) {
const { config } = useAppConfig();
const premiumEnabled = config?.premiumEnabled;
@@ -77,8 +82,16 @@ export function useNavigationUrlSync(
useEffect(() => {
if (!enableSync) return;
+ const startupTool = startupSelectedToolRef?.current ?? null;
+
if (selectedTool) {
- updateToolRoute(selectedTool, registry, false); // Use pushState for user navigation
+ // A startup-view selection is a view preference, not a navigation: writing
+ // it here rewrote /editor to /read on every load. The effect re-runs
+ // whenever the registry identity changes, so the marker has to survive
+ // until the selection actually moves off it (cleared below).
+ if (startupTool !== selectedTool) {
+ updateToolRoute(selectedTool, registry, false); // Use pushState for user navigation
+ }
} else if (prevSelectedTool.current !== null) {
// Only clear URL if we had a tool before (user navigated away)
// Don't clear on initial load when both current and previous are null
@@ -88,8 +101,19 @@ export function useNavigationUrlSync(
}
}
+ // Spent once the user leaves the startup-applied tool, so re-picking it
+ // later is a real navigation and does update the URL.
+ if (
+ startupSelectedToolRef &&
+ startupTool !== null &&
+ prevSelectedTool.current === startupTool &&
+ selectedTool !== startupTool
+ ) {
+ startupSelectedToolRef.current = null;
+ }
+
prevSelectedTool.current = selectedTool;
- }, [selectedTool, registry, enableSync]);
+ }, [selectedTool, registry, enableSync, startupSelectedToolRef]);
// Handle browser back/forward navigation
useEffect(() => {
diff --git a/frontend/editor/src/core/services/httpErrorHandler.basePath.test.ts b/frontend/editor/src/core/services/httpErrorHandler.basePath.test.ts
new file mode 100644
index 0000000000..27a4231a2c
--- /dev/null
+++ b/frontend/editor/src/core/services/httpErrorHandler.basePath.test.ts
@@ -0,0 +1,76 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@app/components/toast", () => ({ alert: vi.fn() }));
+vi.mock("@app/services/specialErrorToasts", () => ({
+ showSpecialErrorToast: vi.fn(() => false),
+}));
+vi.mock("@app/services/saasErrorInterceptor", () => ({
+ handleSaaSError: vi.fn(() => false),
+}));
+vi.mock("@app/services/errorUtils", () => ({
+ broadcastErroredFiles: vi.fn(),
+ extractErrorFileIds: vi.fn(() => []),
+ normalizeAxiosErrorData: vi.fn(async (d: unknown) => d),
+}));
+
+const hrefs: string[] = [];
+
+/** Serve the app from `base`, sitting on `pathname`, then load the handler fresh. */
+async function loadAt(base: string, pathname: string) {
+ document.head.innerHTML = ` = {};
@@ -21,26 +22,9 @@ const SPECIAL_SUPPRESS_MS = 1500; // brief window to suppress generic duplicate
// Mirrors the key in proprietary/auth/springAuthClient.ts; AuthCallback consumes it.
const POST_LOGIN_REDIRECT_STORAGE_KEY = "stirling_post_login_path";
-function isSafePostLoginPath(path: string): boolean {
- if (
- !path.startsWith("/") ||
- path.startsWith("//") ||
- path.startsWith("/\\")
- ) {
- return false;
- }
- const lowered = path.toLowerCase();
- return (
- !lowered.startsWith("/login") &&
- !lowered.startsWith("/auth/") &&
- !lowered.startsWith("/oauth2") &&
- !lowered.startsWith("/saml2")
- );
-}
-
function stashPostLoginRedirect(path: string): void {
try {
- if (typeof window === "undefined" || !isSafePostLoginPath(path)) return;
+ if (typeof window === "undefined" || !isSafePostLoginRedirect(path)) return;
window.sessionStorage.setItem(POST_LOGIN_REDIRECT_STORAGE_KEY, path);
} catch {
// sessionStorage unavailable (private mode) — fail open
@@ -128,7 +112,11 @@ export async function handleHttpError(error: unknown): Promise {
console.debug("[httpErrorHandler] 401 detected, redirecting to login");
// Spring 302-strips the ?from= query from /login, so stash the return
// path in sessionStorage (AuthCallback reads it after SSO round-trip).
- const currentLocation = window.location.pathname + window.location.search;
+ // Router-relative, not browser-relative: every consumer replays this
+ // through navigate(), which re-applies the basename. Keeping the base
+ // path here yields /app/app/ on a subpath deploy.
+ const currentLocation =
+ stripBasePath(window.location.pathname) + window.location.search;
stashPostLoginRedirect(currentLocation);
let hadStoredJwt = false;
try {
diff --git a/frontend/editor/src/core/services/postLoginRedirect.test.ts b/frontend/editor/src/core/services/postLoginRedirect.test.ts
new file mode 100644
index 0000000000..9f1687f392
--- /dev/null
+++ b/frontend/editor/src/core/services/postLoginRedirect.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { isSafePostLoginRedirect } from "@app/services/postLoginRedirect";
+
+// Core default. Rejects off-origin forms and the auth routes every build has
+// (/login, /auth/…); Spring SSO routes are the proprietary override's concern.
+describe("isSafePostLoginRedirect (core base)", () => {
+ it("accepts same-origin router paths", () => {
+ expect(isSafePostLoginRedirect("/editor")).toBe(true);
+ expect(isSafePostLoginRedirect("/compress")).toBe(true);
+ expect(isSafePostLoginRedirect("/editor?foo=bar")).toBe(true);
+ expect(isSafePostLoginRedirect("/oauth/consent?x=1")).toBe(true);
+ expect(isSafePostLoginRedirect("/")).toBe(true);
+ });
+
+ it("rejects empty and non-string values", () => {
+ expect(isSafePostLoginRedirect(null)).toBe(false);
+ expect(isSafePostLoginRedirect(undefined)).toBe(false);
+ expect(isSafePostLoginRedirect("")).toBe(false);
+ expect(isSafePostLoginRedirect(42 as unknown)).toBe(false);
+ });
+
+ it("rejects off-origin and protocol-relative forms", () => {
+ expect(isSafePostLoginRedirect("//evil.example.com")).toBe(false);
+ expect(isSafePostLoginRedirect("/\\evil.example.com")).toBe(false);
+ expect(isSafePostLoginRedirect("https://evil.example.com")).toBe(false);
+ expect(isSafePostLoginRedirect("editor")).toBe(false);
+ });
+
+ it("rejects the universal auth routes so returning back can never loop", () => {
+ expect(isSafePostLoginRedirect("/login")).toBe(false);
+ expect(isSafePostLoginRedirect("/login?next=%2Feditor")).toBe(false);
+ expect(isSafePostLoginRedirect("/auth/callback")).toBe(false);
+ });
+
+ it("leaves the Spring SSO routes to the proprietary override", () => {
+ expect(isSafePostLoginRedirect("/oauth2/authorize")).toBe(true);
+ expect(isSafePostLoginRedirect("/saml2/login")).toBe(true);
+ });
+});
diff --git a/frontend/editor/src/core/services/postLoginRedirect.ts b/frontend/editor/src/core/services/postLoginRedirect.ts
new file mode 100644
index 0000000000..d9ffe82940
--- /dev/null
+++ b/frontend/editor/src/core/services/postLoginRedirect.ts
@@ -0,0 +1,15 @@
+/**
+ * Is `path` safe to send a user back to after they log in?
+ */
+export function isSafePostLoginRedirect(path: unknown): path is string {
+ if (typeof path !== "string" || path.length === 0) return false;
+ if (
+ !path.startsWith("/") ||
+ path.startsWith("//") ||
+ path.startsWith("/\\")
+ ) {
+ return false;
+ }
+ const lowered = path.toLowerCase();
+ return !lowered.startsWith("/login") && !lowered.startsWith("/auth/");
+}
diff --git a/frontend/editor/src/core/services/workbenchSession.test.ts b/frontend/editor/src/core/services/workbenchSession.test.ts
index d9feec8d1c..0258b83623 100644
--- a/frontend/editor/src/core/services/workbenchSession.test.ts
+++ b/frontend/editor/src/core/services/workbenchSession.test.ts
@@ -55,10 +55,14 @@ describe("workbench session record", () => {
});
describe("editor return path", () => {
- it("is consumed by the first take", () => {
- saveEditorReturnPath("/compress?x=1");
+ it("captures the live address bar and is consumed by the first take", () => {
+ // The editor writes its tool route via raw history.pushState, so the save
+ // must read window.location, not a lagging router location.
+ window.history.pushState({}, "", "/compress?x=1");
+ saveEditorReturnPath();
expect(takeEditorReturnPath()).toBe("/compress?x=1");
expect(takeEditorReturnPath()).toBeNull();
+ window.history.pushState({}, "", "/");
});
});
diff --git a/frontend/editor/src/core/services/workbenchSession.ts b/frontend/editor/src/core/services/workbenchSession.ts
index 67f6d1abfc..2f23db8655 100644
--- a/frontend/editor/src/core/services/workbenchSession.ts
+++ b/frontend/editor/src/core/services/workbenchSession.ts
@@ -2,6 +2,7 @@
// does not cost the user their workbench. sessionStorage on purpose: per-tab, tabs never clobber.
import type { StirlingFileStub } from "@app/types/fileContext";
+import { stripBasePath } from "@app/constants/app";
const SESSION_KEY = "stirling.workbench.session";
/** Bumped when the record's shape or meaning changes, so an old one is discarded rather than
@@ -153,8 +154,10 @@ export function isSeedableView(
return view !== undefined && SEEDABLE_VIEWS.includes(view);
}
-export function saveEditorReturnPath(path: string): void {
+export function saveEditorReturnPath(): void {
try {
+ const path =
+ stripBasePath(window.location.pathname) + window.location.search;
sessionStorage.setItem(RETURN_PATH_KEY, path);
} catch {
// Best-effort: the switch back just lands on the editor root.
diff --git a/frontend/editor/src/proprietary/auth/spring/springAuthClient.ts b/frontend/editor/src/proprietary/auth/spring/springAuthClient.ts
index b9583e3dee..6d887ce8a9 100644
--- a/frontend/editor/src/proprietary/auth/spring/springAuthClient.ts
+++ b/frontend/editor/src/proprietary/auth/spring/springAuthClient.ts
@@ -16,6 +16,7 @@ import { AxiosError, type AxiosRequestConfig } from "axios";
import { getSpringAuthConfig } from "@app/auth/config";
import { type OAuthProvider } from "@app/auth/spring/oauthTypes";
import { resetOAuthState } from "@app/auth/spring/oauthStorage";
+import { isSafePostLoginRedirect } from "@app/services/postLoginRedirect";
import type {
AuthUser as User,
AuthSession as Session,
@@ -100,23 +101,10 @@ function persistRedirectPath(path: string): void {
}
}
-// Same-origin relative path, not pointing at auth plumbing. Rejects protocol-relative
-// URLs to guard against open-redirect abuse if the stored value is tampered with.
-export function isSafePostLoginRedirect(path: unknown): path is string {
- if (typeof path !== "string" || path.length === 0) return false;
- if (!path.startsWith("/") || path.startsWith("//")) return false;
- if (path.startsWith("/\\")) return false;
- const lowered = path.toLowerCase();
- if (
- lowered.startsWith("/login") ||
- lowered.startsWith("/auth/") ||
- lowered.startsWith("/oauth2") ||
- lowered.startsWith("/saml2")
- ) {
- return false;
- }
- return true;
-}
+// The safe-return-path rule lives in the shared @app/services/postLoginRedirect
+// extension point (proprietary override adds the Spring SSO routes). Re-exported
+// here so existing importers via @app/auth keep resolving it.
+export { isSafePostLoginRedirect };
export function setPostLoginRedirectPath(
path: string | null | undefined,
diff --git a/frontend/editor/src/proprietary/auth/supabase/UseSession.tsx b/frontend/editor/src/proprietary/auth/supabase/UseSession.tsx
index 385f3f4e35..07670bfff5 100644
--- a/frontend/editor/src/proprietary/auth/supabase/UseSession.tsx
+++ b/frontend/editor/src/proprietary/auth/supabase/UseSession.tsx
@@ -16,6 +16,7 @@ import type {
import { getSupabaseClient } from "@app/auth/supabase/supabaseClient";
import { AuthContext } from "@app/auth/context";
import { isAdminRole } from "@app/auth/roles";
+import { getApiBaseUrl } from "@app/services/apiClientConfig";
import {
defaultTranslate,
type AuthContextValue,
@@ -154,14 +155,23 @@ export function SupabaseAuthProvider({
return;
}
let cancelled = false;
+ // Same API base the rest of the app uses: SaaS serves the frontend and the
+ // API from different hosts, so a root-relative path never reaches /me.
+ const apiBase = (getApiBaseUrl() || "").replace(/\/+$/, "");
+ const meUrl = `${apiBase}/api/v1/auth/me`;
const loadAccess = () => {
- void fetch("/api/v1/auth/me", {
+ void fetch(meUrl, {
headers: {
Authorization: `Bearer ${token}`,
Accept: "application/json",
},
})
- .then((res) => (res.ok ? res.json() : null))
+ .then((res) => {
+ // Must throw, not resolve null: swallowing a non-ok leaves
+ // portalAccess undefined and hangs the portal gate on a spinner.
+ if (!res.ok) throw new Error(`auth/me responded ${res.status}`);
+ return res.json();
+ })
.then(
(
data: {
diff --git a/frontend/editor/src/proprietary/auth/supabase/portalAccessFetch.test.tsx b/frontend/editor/src/proprietary/auth/supabase/portalAccessFetch.test.tsx
new file mode 100644
index 0000000000..3b3d9b37c8
--- /dev/null
+++ b/frontend/editor/src/proprietary/auth/supabase/portalAccessFetch.test.tsx
@@ -0,0 +1,128 @@
+import { beforeEach, afterEach, describe, expect, it, vi } from "vitest";
+import { render, waitFor } from "@testing-library/react";
+import { useContext } from "react";
+
+const h = vi.hoisted(() => ({ apiBase: "/" }));
+
+vi.mock("@app/services/apiClientConfig", () => ({
+ getApiBaseUrl: () => h.apiBase,
+}));
+
+const sbSession = {
+ access_token: "supabase-token",
+ user: {
+ id: "u1",
+ email: "user@example.com",
+ is_anonymous: false,
+ app_metadata: {},
+ user_metadata: {},
+ },
+};
+
+vi.mock("@app/auth/supabase/supabaseClient", () => ({
+ getSupabaseClient: () => ({
+ auth: {
+ getSession: () => Promise.resolve({ data: { session: sbSession } }),
+ onAuthStateChange: () => ({
+ data: { subscription: { unsubscribe: () => {} } },
+ }),
+ refreshSession: () => Promise.resolve({ data: {}, error: null }),
+ signOut: () => Promise.resolve({ error: null }),
+ },
+ }),
+}));
+
+import { SupabaseAuthProvider } from "@app/auth/supabase/UseSession";
+import { AuthContext } from "@app/auth/context";
+
+function Probe() {
+ const v = useContext(AuthContext);
+ return (
+ <>
+ {String(v?.portalAccess)}
+ {/* Raw, un-defaulted value: this is what SaasPortalGate reads to decide
+ "access not known yet" vs "denied". undefined = spinner forever. */}
+ {String(v?.user?.portalAccess)}
+
+ );
+}
+
+const mount = () =>
+ render(
+
+ ,
+ );
+
+let fetchMock: ReturnType;
+
+beforeEach(() => {
+ fetchMock = vi.fn();
+ vi.stubGlobal("fetch", fetchMock);
+});
+afterEach(() => vi.unstubAllGlobals());
+
+describe("supabase provider portalAccess lookup", () => {
+ // SaaS serves the frontend and the API from different hosts; a root-relative
+ // path silently missed /me, so a granted non-admin was denied the Processor.
+ it("calls /me on the configured API base, not the page origin", async () => {
+ h.apiBase = "https://api.example.com";
+ fetchMock.mockResolvedValue({
+ ok: true,
+ json: () => Promise.resolve({ user: { portalAccess: true } }),
+ });
+ mount();
+ await waitFor(() =>
+ expect(fetchMock).toHaveBeenCalledWith(
+ "https://api.example.com/api/v1/auth/me",
+ expect.anything(),
+ ),
+ );
+ });
+
+ it("keeps a same-origin base as a single leading slash", async () => {
+ h.apiBase = "/";
+ fetchMock.mockResolvedValue({
+ ok: true,
+ json: () => Promise.resolve({ user: { portalAccess: true } }),
+ });
+ mount();
+ await waitFor(() =>
+ expect(fetchMock).toHaveBeenCalledWith(
+ "/api/v1/auth/me",
+ expect.anything(),
+ ),
+ );
+ });
+
+ it("grants access when /me says so", async () => {
+ h.apiBase = "https://api.example.com";
+ fetchMock.mockResolvedValue({
+ ok: true,
+ json: () => Promise.resolve({ user: { portalAccess: true } }),
+ });
+ const { getByTestId } = mount();
+ await waitFor(() => expect(getByTestId("access").textContent).toBe("true"));
+ });
+
+ // A non-ok used to resolve to null and return early, leaving the raw
+ // portalAccess undefined forever - SaasPortalGate reads that as "still
+ // loading" and hangs on a spinner instead of falling back.
+ it("resolves the raw portalAccess when /me returns non-ok", async () => {
+ h.apiBase = "https://api.example.com";
+ fetchMock.mockResolvedValue({
+ ok: false,
+ status: 401,
+ json: () => Promise.resolve({}),
+ });
+ const { getByTestId } = mount();
+ await waitFor(() => expect(getByTestId("raw").textContent).toBe("false"));
+ });
+
+ it("leaves the raw portalAccess defined when the request rejects", async () => {
+ h.apiBase = "https://api.example.com";
+ fetchMock.mockRejectedValue(new Error("network down"));
+ const { getByTestId } = mount();
+ await waitFor(() => expect(getByTestId("raw").textContent).toBe("false"));
+ });
+});
diff --git a/frontend/editor/src/proprietary/hooks/useOtherAppSwitch.test.tsx b/frontend/editor/src/proprietary/hooks/useOtherAppSwitch.test.tsx
index c2a81c53d9..4acdc7a17a 100644
--- a/frontend/editor/src/proprietary/hooks/useOtherAppSwitch.test.tsx
+++ b/frontend/editor/src/proprietary/hooks/useOtherAppSwitch.test.tsx
@@ -7,9 +7,10 @@ const mocks = vi.hoisted(() => ({
portalAccess: true,
}));
+// The hook reads window.location for the return path (not useLocation), because
+// the editor's raw history.pushState leaves react-router's location stale.
vi.mock("react-router-dom", () => ({
useNavigate: () => mocks.navigate,
- useLocation: () => ({ pathname: "/compress", search: "?mode=fast" }),
}));
vi.mock("@app/auth/context", () => ({
useAuth: () => ({ portalAccess: mocks.portalAccess }),
@@ -27,6 +28,7 @@ beforeEach(() => {
sessionStorage.clear();
vi.clearAllMocks();
mocks.portalAccess = true;
+ window.history.pushState({}, "", "/");
});
describe("useOtherAppSwitch", () => {
@@ -45,6 +47,7 @@ describe("useOtherAppSwitch", () => {
});
it("records where to return to, then navigates to the processor", () => {
+ window.history.pushState({}, "", "/compress?mode=fast");
const { result } = renderHook(() => useOtherAppSwitch());
result.current?.onOpen();
mocks.requestNavigation.mock.calls[0][0]();
diff --git a/frontend/editor/src/proprietary/hooks/useOtherAppSwitch.ts b/frontend/editor/src/proprietary/hooks/useOtherAppSwitch.ts
index dff36a06f4..69b55aff35 100644
--- a/frontend/editor/src/proprietary/hooks/useOtherAppSwitch.ts
+++ b/frontend/editor/src/proprietary/hooks/useOtherAppSwitch.ts
@@ -1,4 +1,4 @@
-import { useLocation, useNavigate } from "react-router-dom";
+import { useNavigate } from "react-router-dom";
import { useAuth } from "@app/auth/context";
import { useNavigationActions } from "@app/contexts/NavigationContext";
import { PORTAL_BASENAME } from "@app/routes/portalBasename";
@@ -12,7 +12,6 @@ import { type NavFooterAppLink } from "@app/components/shared/navFooter/NavFoote
export function useOtherAppSwitch(): NavFooterAppLink | null {
const { portalAccess } = useAuth();
const navigate = useNavigate();
- const location = useLocation();
const { actions } = useNavigationActions();
if (!portalAccess) return null;
return {
@@ -20,7 +19,7 @@ export function useOtherAppSwitch(): NavFooterAppLink | null {
onOpen: () =>
// Through the guard, so unsaved edits get the same warning as any other navigation.
actions.requestNavigation(() => {
- saveEditorReturnPath(location.pathname + location.search);
+ saveEditorReturnPath();
navigate(PORTAL_BASENAME);
}),
};
diff --git a/frontend/editor/src/proprietary/services/apiClientSetup.ts b/frontend/editor/src/proprietary/services/apiClientSetup.ts
index 3f50e1bb4c..459f527080 100644
--- a/frontend/editor/src/proprietary/services/apiClientSetup.ts
+++ b/frontend/editor/src/proprietary/services/apiClientSetup.ts
@@ -1,5 +1,5 @@
import { AxiosInstance, AxiosError, InternalAxiosRequestConfig } from "axios";
-import { withBasePath } from "@app/constants/app";
+import { stripBasePath, withBasePath } from "@app/constants/app";
import { getBrowserId } from "@app/utils/browserIdentifier";
import { setPostLoginRedirectPath } from "@app/auth/spring/springAuthClient";
@@ -94,8 +94,10 @@ async function refreshAuthToken(client: AxiosInstance): Promise {
// Redirect to login
const loginPath = withBasePath("/login");
if (window.location.pathname !== loginPath) {
+ // Router-relative: Login replays this through navigate(), which applies
+ // the basename itself. See the same note in httpErrorHandler.
setPostLoginRedirectPath(
- window.location.pathname + window.location.search,
+ stripBasePath(window.location.pathname) + window.location.search,
);
console.log("[API Client] Redirecting to login page...");
window.location.href = loginPath;
diff --git a/frontend/editor/src/proprietary/services/postLoginRedirect.test.ts b/frontend/editor/src/proprietary/services/postLoginRedirect.test.ts
new file mode 100644
index 0000000000..6f2451f336
--- /dev/null
+++ b/frontend/editor/src/proprietary/services/postLoginRedirect.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { isSafePostLoginRedirect } from "@app/services/postLoginRedirect";
+
+// Proprietary override: the core base plus the Spring SSO routes (/oauth2, /saml2).
+describe("isSafePostLoginRedirect (proprietary override)", () => {
+ it("still accepts ordinary router paths", () => {
+ expect(isSafePostLoginRedirect("/editor")).toBe(true);
+ expect(isSafePostLoginRedirect("/share/abc123?x=1")).toBe(true);
+ expect(isSafePostLoginRedirect("/")).toBe(true);
+ });
+
+ it("inherits the base rejections", () => {
+ expect(isSafePostLoginRedirect("")).toBe(false);
+ expect(isSafePostLoginRedirect(null)).toBe(false);
+ expect(isSafePostLoginRedirect("//evil.example")).toBe(false);
+ expect(isSafePostLoginRedirect("/\\evil")).toBe(false);
+ expect(isSafePostLoginRedirect("/login")).toBe(false);
+ expect(isSafePostLoginRedirect("/auth/callback")).toBe(false);
+ });
+
+ it("also rejects the Spring SSO routes", () => {
+ expect(isSafePostLoginRedirect("/oauth2/authorization/google")).toBe(false);
+ expect(isSafePostLoginRedirect("/saml2/authenticate/x")).toBe(false);
+ });
+});
diff --git a/frontend/editor/src/proprietary/services/postLoginRedirect.ts b/frontend/editor/src/proprietary/services/postLoginRedirect.ts
new file mode 100644
index 0000000000..5cd6546fa7
--- /dev/null
+++ b/frontend/editor/src/proprietary/services/postLoginRedirect.ts
@@ -0,0 +1,7 @@
+import { isSafePostLoginRedirect as isSafeBaseRedirect } from "@core/services/postLoginRedirect";
+
+export function isSafePostLoginRedirect(path: unknown): path is string {
+ if (!isSafeBaseRedirect(path)) return false;
+ const lowered = path.toLowerCase();
+ return !lowered.startsWith("/oauth2") && !lowered.startsWith("/saml2");
+}
diff --git a/frontend/editor/src/saas/hooks/useOtherAppSwitch.ts b/frontend/editor/src/saas/hooks/useOtherAppSwitch.ts
index 67d0aa7d49..e97d4d0ed3 100644
--- a/frontend/editor/src/saas/hooks/useOtherAppSwitch.ts
+++ b/frontend/editor/src/saas/hooks/useOtherAppSwitch.ts
@@ -1,4 +1,4 @@
-import { useLocation, useNavigate } from "react-router-dom";
+import { useNavigate } from "react-router-dom";
import { usePortalAccess } from "@app/hooks/usePortalAccess";
import { useNavigationActions } from "@app/contexts/NavigationContext";
import { PORTAL_BASENAME } from "@app/routes/portalBasename";
@@ -13,7 +13,6 @@ import { type NavFooterAppLink } from "@app/components/shared/navFooter/NavFoote
export function useOtherAppSwitch(): NavFooterAppLink | null {
const portalAccess = usePortalAccess();
const navigate = useNavigate();
- const location = useLocation();
const { actions } = useNavigationActions();
if (!portalAccess) return null;
return {
@@ -21,7 +20,7 @@ export function useOtherAppSwitch(): NavFooterAppLink | null {
onOpen: () =>
// Through the guard, so unsaved edits get the same warning as any other navigation.
actions.requestNavigation(() => {
- saveEditorReturnPath(location.pathname + location.search);
+ saveEditorReturnPath();
navigate(PORTAL_BASENAME);
}),
};
diff --git a/frontend/editor/src/saas/routes/AuthCallback.tsx b/frontend/editor/src/saas/routes/AuthCallback.tsx
index b69619b85d..3fe081ed82 100644
--- a/frontend/editor/src/saas/routes/AuthCallback.tsx
+++ b/frontend/editor/src/saas/routes/AuthCallback.tsx
@@ -5,6 +5,7 @@ import { supabase } from "@app/auth/supabase";
import { Button } from "@app/ui/Button";
import { withBasePath } from "@app/constants/app";
import { readPendingConnect } from "@app/routes/pendingConnect";
+import { isSafePostLoginRedirect } from "@app/services/postLoginRedirect";
import { AuthShell } from "@app/auth/ui/AuthShell";
import ErrorMessage from "@app/auth/ui/ErrorMessage";
import { Spinner } from "@app/ui/Spinner";
@@ -136,18 +137,16 @@ export default function AuthCallback() {
// else on the editor.
// Explicit `next` first, so a sign-in started for another reason is not
// hijacked by a remembered connect request.
- const explicitNext = url.searchParams.get("next");
+ const explicitNext =
+ url.searchParams.get("next") ?? url.searchParams.get("from");
const pendingConnect = readPendingConnect();
- const destination =
- explicitNext &&
- explicitNext.startsWith("/") &&
- !explicitNext.startsWith("//")
- ? explicitNext
- : pendingConnect
- ? `/link?request=${encodeURIComponent(pendingConnect)}`
- : next.startsWith("/") && !next.startsWith("//")
- ? next
- : await resolveLandingPath();
+ const destination = isSafePostLoginRedirect(explicitNext)
+ ? explicitNext
+ : pendingConnect
+ ? `/link?request=${encodeURIComponent(pendingConnect)}`
+ : isSafePostLoginRedirect(next)
+ ? next
+ : await resolveLandingPath();
console.log("[Auth Callback Debug] Redirecting to:", destination);
setTimeout(() => navigate(destination, { replace: true }), 1500);
diff --git a/frontend/editor/src/saas/routes/Login.tsx b/frontend/editor/src/saas/routes/Login.tsx
index 418616104e..ba251561fd 100644
--- a/frontend/editor/src/saas/routes/Login.tsx
+++ b/frontend/editor/src/saas/routes/Login.tsx
@@ -14,6 +14,7 @@ import {
getBaseUrl,
withBasePath,
} from "@app/constants/app";
+import { isSafePostLoginRedirect } from "@app/services/postLoginRedirect";
import LinkRoundedIcon from "@mui/icons-material/LinkRounded";
// Import login components
@@ -48,14 +49,14 @@ export default function Login() {
}
}, []);
- // Same-origin relative path to return to after login (e.g. the OAuth
- // consent page). Same sanitization rules as AuthCallback's `next`.
+ // Same-origin router path to return to after login (e.g. the OAuth consent
+ // page, or the editor a 401 bounced the user off). `?next=` is what this app
+ // writes; `?from=` is what the shared core 401 handler writes.
const nextPath = useMemo(() => {
try {
- const next = new URL(window.location.href).searchParams.get("next");
- return next && next.startsWith("/") && !next.startsWith("//")
- ? next
- : null;
+ const params = new URL(window.location.href).searchParams;
+ const candidate = params.get("next") ?? params.get("from");
+ return isSafePostLoginRedirect(candidate) ? candidate : null;
} catch (_) {
return null;
}
diff --git a/frontend/editor/src/saas/services/apiClient.test.ts b/frontend/editor/src/saas/services/apiClient.test.ts
index 45646bf8d8..af4a1d90f4 100644
--- a/frontend/editor/src/saas/services/apiClient.test.ts
+++ b/frontend/editor/src/saas/services/apiClient.test.ts
@@ -219,10 +219,11 @@ describe("apiClient", () => {
// Import apiClient after mocking
const { default: apiClient } = await import("@app/services/apiClient");
- // Mock window.location for redirect test
+ // On /editor when the session dies: the return path must ride along so the
+ // login screen sends the user back here, not to the role-based landing.
Object.defineProperty(window, "location", {
writable: true,
- value: { href: "" },
+ value: { href: "", pathname: "/editor", search: "" },
});
const mockAdapter = vi.fn((config) => {
@@ -245,8 +246,50 @@ describe("apiClient", () => {
} catch (_) {
// Verify refresh was attempted
expect(supabase.auth.refreshSession).toHaveBeenCalled();
- // Verify redirect to login
- expect(window.location.href).toBe("/login");
+ // Verify redirect to login carries the return path
+ expect(window.location.href).toBe("/login?next=%2Feditor");
+ }
+ });
+
+ it("does not redirect (or loop) when already on the login page", async () => {
+ expectConsole.error(/\[API Client\] Token refresh failed/);
+ const oldSession = { access_token: "old", user: { id: "user-123" } };
+ vi.mocked(supabase.auth.getSession).mockResolvedValue({
+ data: { session: oldSession as unknown as Session },
+ error: null,
+ });
+ vi.mocked(supabase.auth.refreshSession).mockResolvedValue({
+ data: { user: null, session: null },
+ error: {
+ name: "AuthError",
+ message: "Refresh failed",
+ status: 400,
+ code: "auth_error",
+ } as unknown as AuthError,
+ });
+
+ const { default: apiClient } = await import("@app/services/apiClient");
+
+ Object.defineProperty(window, "location", {
+ writable: true,
+ value: { href: "", pathname: "/login", search: "?next=%2Feditor" },
+ });
+
+ apiClient.defaults.adapter = vi.fn((config) =>
+ Promise.reject(
+ Object.assign(new Error("Unauthorized"), {
+ response: { status: 401, data: { error: "Unauthorized" } },
+ config,
+ }),
+ ),
+ );
+
+ try {
+ await apiClient.get("/api/v1/test");
+ expect(true).toBe(false);
+ } catch (_) {
+ // Left untouched: no second redirect off the login page.
+ expect(window.location.href).toBe("");
}
});
});
diff --git a/frontend/editor/src/saas/services/apiClient.ts b/frontend/editor/src/saas/services/apiClient.ts
index 64cd05fd01..73ebe97e47 100644
--- a/frontend/editor/src/saas/services/apiClient.ts
+++ b/frontend/editor/src/saas/services/apiClient.ts
@@ -5,8 +5,9 @@ import {
classifyPaygError,
handlePaygError,
} from "@app/services/paygErrorInterceptor";
-import { withBasePath } from "@app/constants/app";
+import { stripBasePath, withBasePath } from "@app/constants/app";
import { getBrowserId } from "@app/utils/browserIdentifier";
+import { isSafePostLoginRedirect } from "@app/services/postLoginRedirect";
// Helper: decode base64url JWT payload safely
function decodeJwtPayload(token: string): Record | null {
@@ -113,6 +114,21 @@ function refreshSessionOnce(): ReturnType {
return inFlightRefresh;
}
+// Hard-redirect to /login, carrying where the user was so the login screen can
+// return them there instead of falling through to the role-based landing (which
+// sends processor users to the processor - the "refresh /editor bounces me to
+// the processor" bug). Router-relative, matching what Login reads via `?next=`.
+function redirectToLogin(): void {
+ const loginPath = withBasePath("/login");
+ // Already on the login page: another redirect would just loop.
+ if (window.location.pathname === loginPath) return;
+ const returnPath =
+ stripBasePath(window.location.pathname) + window.location.search;
+ window.location.href = isSafePostLoginRedirect(returnPath)
+ ? `${loginPath}?next=${encodeURIComponent(returnPath)}`
+ : loginPath;
+}
+
// Response interceptor for handling token refresh
apiClient.interceptors.response.use(
(response) => response,
@@ -173,7 +189,7 @@ apiClient.interceptors.response.use(
// The session genuinely can't be recovered. Send protected requests
// to login; public ones just fail quietly (no redirect).
if (!isPublicEndpoint) {
- window.location.href = withBasePath("/login");
+ redirectToLogin();
}
return Promise.reject(error);
@@ -194,10 +210,7 @@ apiClient.interceptors.response.use(
console.debug(
"[API Client] No session to refresh, 401 on protected endpoint",
);
- const loginPath = withBasePath("/login");
- if (window.location.pathname !== loginPath) {
- window.location.href = loginPath;
- }
+ redirectToLogin();
return Promise.reject(error);
}
} catch (refreshError) {
From 658aa54c20446f9f1188f59cf35fb82fa86bc81e Mon Sep 17 00:00:00 2001
From: James Brunton
Date: Fri, 28 Aug 2026 10:35:41 +0000
Subject: [PATCH 12/27] Update tool models to fix main (#7725)
# Description of Changes
When #6697 merged, the CI didn't run for some reason so it was never
caught that the tool models were out of date. This PR updates them to
the correct state.
---
engine/src/stirling/models/tool_models.py | 3 +++
frontend/editor/src/core/types/toolApiTypes.ts | 4 ++++
2 files changed, 7 insertions(+)
diff --git a/engine/src/stirling/models/tool_models.py b/engine/src/stirling/models/tool_models.py
index 6650942b6f..dff977a7f7 100644
--- a/engine/src/stirling/models/tool_models.py
+++ b/engine/src/stirling/models/tool_models.py
@@ -725,6 +725,9 @@ class OcrPdfParams(ApiModel):
)
ocr_type: OcrType = Field(..., description="Specify the OCR type, e.g., 'skip-text', 'force-ocr', or 'Normal'")
remove_images_after: bool | None = Field(None, description="Remove images from the output PDF if set to true")
+ rotate_pages: bool | None = Field(
+ None, description="Auto-correct page orientation (90/180/270) using Tesseract OSD if set to true"
+ )
sidecar: bool | None = Field(None, description="Include OCR text in a sidecar text file if set to true")
diff --git a/frontend/editor/src/core/types/toolApiTypes.ts b/frontend/editor/src/core/types/toolApiTypes.ts
index 55938d231e..d980029624 100644
--- a/frontend/editor/src/core/types/toolApiTypes.ts
+++ b/frontend/editor/src/core/types/toolApiTypes.ts
@@ -1022,6 +1022,10 @@ export interface ProcessPdfWithOcrRequest {
* Remove images from the output PDF if set to true
*/
removeImagesAfter?: boolean;
+ /**
+ * Auto-correct page orientation (90/180/270) using Tesseract OSD if set to true
+ */
+ rotatePages?: boolean;
/**
* Include OCR text in a sidecar text file if set to true
*/
From 4ab2505a6c8fe2ed469576b6d4e93d7565b2567a Mon Sep 17 00:00:00 2001
From: ConnorYoh <40631091+ConnorYoh@users.noreply.github.com>
Date: Fri, 28 Aug 2026 10:56:50 +0000
Subject: [PATCH 13/27] Comment-quality standard, and the gate that enforces it
(#7663)
## The problem
AI PRs write comments that restate the line below them, mark sections
with box drawing, and narrate the diff. Nothing in the repo said not to,
and nothing checked. `AGENTS.md` had one line about comments and it was
buried in the Python section.
Banners and `Step N:` narration have zero occurrences in the 15 months
before Aug 2025, so this is new.
## The fix
A written standard, plus a linter that enforces the mechanical part of
it on added lines only.
-
[devGuide/CODE_COMMENTS.md](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/devGuide/CODE_COMMENTS.md)
holds the reasoning and worked examples; a section in
[AGENTS.md](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/AGENTS.md)
holds the operative rules, kept short so they stay in an agent's
context. The two are split by kind rather than duplicated, because the
same prose in two places drifts.
- Rules in
[comment-rules.mjs](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs),
shared by both engines.
- Two engines. `.ts` / `.tsx` / `.mjs` go to an [oxlint JS
plugin](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-lint-oxlint-plugin.mjs)
so comments come from the parser rather than a line scan; `.java` /
`.py` go to a [line
scanner](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-lint.mjs).
Neither reads the other's files, so they cannot disagree about one file.
- Between them they read every comment form the repo writes: `//` and
`/* */`, Javadoc and JSDoc, JSX comments, `#`, and Python docstrings.
- Runs in `task pre-commit`, so the git hook and the `pre_commit.yml` CI
job both get it, and as a Claude Code [`Stop`
hook](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-lint-hook.mjs)
so an agent fixes the comment inside the turn that wrote it.
## The rules
The part worth arguing about. **Every rule blocks.** A rule that only
warns is a rule nobody acts on, so a finding you believe is wrong is a
bug in the rule: narrow it, or mark the line and say why.
| | Fires on |
| --- | --- |
|
[CMT001](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L71)
| Every word in the comment already appears in the code below it. Max 6
words, skipped for prose punctuation and for a bare Arrange/Act/Assert
marker |
|
[CMT002](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L92)
| 4+ rule or box-drawing characters, or a bare section label from [a
fixed
list](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L84)
(`Types`, `Helpers`, `State`, `Handlers`, ...) |
|
[CMT003](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L110)
| `Step N:` with a separator, or `Then,` / `Next,` / `Finally,`.
Suppressed in test files |
|
[CMT004](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L129)
| A comment about the code's own past: `this used to`, `renamed from`,
`was previously called`. Suppressed in test files |
|
[CMT005](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L154)
| 3+ consecutive comment lines where 2/3 [parse as
code](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L143)
|
|
[CMT006](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L31)
| A run of implementation comment over 12 lines, outside the first 5
lines of a file. Doc blocks are exempt, because the standard asks for
thorough contracts |
|
[CMT007](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L180)
| A parameter or return description that adds no word its name lacks.
Reads Javadoc/JSDoc `@param`, Sphinx `:param name:` and Google `name:
description` |
|
[CMT008](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L239)
| An allow directive naming a rule that does not exist, or one that
silenced nothing |
|
[CMT009](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L219)
| A `TODO` / `FIXME` / `HACK` naming no issue or link. An owner is not
accepted: a username goes stale, an issue outlives it |
Each rule carries the readings it deliberately excludes, next to the
rule. Those exclusions came from running the rules over this repo, not
from taste: `CMT004` does not match a bare "no longer needed" because
that is as often about runtime lifecycle as about history, and `CMT003`
needs a separator after the number so a wrapped line beginning "step 2
unmounts + remounts the panel" reads as the prose it is.
A comment sharing a line with code is judged by the rules that do not
depend on the code below it, so a trailing `// TODO fix this` or `/*
this used to run before the flush */` still reports, while `50L * 1024 *
1024 // 50 MB` does not. `CMT001` would have been wrong about six in
seven trailing comments here, so it stays out of them.
If a finding is wrong, `// comment-lint-allow: CMT002` on the line
above. Rule-specific, [no blanket
disable](https://github.com/Stirling-Tools/Stirling-PDF/blob/claude/ai-pr-comment-quality-dd970e/scripts/lint/comment-rules.mjs#L229).
A directive naming a rule that does not exist, or silencing nothing, is
itself a `CMT008` failure, so a typo cannot quietly disable a rule and a
stale one gets deleted rather than accumulating.
No native linter covers `CMT007`. `eslint-plugin-jsdoc`'s
`require-param-description`, Checkstyle's `NonEmptyAtclauseDescription`
and ruff's D-rules all check that a description exists, not whether it
says anything.
## Scoping
Added comment **text** only, not lines git calls new. Reindenting a file
or moving a block makes git mark untouched comments as added; findings
are matched against the comment text at the base, so only genuinely new
content reports.
The whole file is read and every comment in it evaluated. Only the
*reporting* is filtered, so a rule still sees the code a comment
introduces, the full run it belongs to, and the base version of the
file.
Existing tree is untouched. `task pre-commit:comment-lint:all` reports
it and always exits 0:
| | java | ts/js | py |
| --- | --- | --- | --- |
| findings | 1,218 | 741 | 204 |
2,163 across 542 files, mostly `CMT002` banners (1,482) and `CMT001`
restatements (456). Clearing it is separate work, by directory.
Not in this PR: an advisory LLM review layer for the things no pattern
can judge.
## Verification
Run against
[#7494](https://github.com/Stirling-Tools/Stirling-PDF/pull/7494) as CI
would, in a throwaway worktree: **two findings on a 78 file, +4,512 line
change, both genuine banners, in 952ms**. A whole-file scan of those
same files gives 11; the other 9 were withheld because that PR's author
did not write them, and they are the `@param teamId the team ID` shape
this standard exists to stop.
Both scanners blank string and character literals before looking for
comment markers, because a partial lex desynchronises everything after
it: one apostrophe in a Java comment, or one Python template whose
closing quotes start a line, is enough to read dozens of lines of code
as a single comment. Two fixtures carry canaries that stop being
reported if either engine ever desynchronises again.
The [fixture
corpus](https://github.com/Stirling-Tools/Stirling-PDF/tree/claude/ai-pr-comment-quality-dd970e/scripts/lint/fixtures)
pins all 9 rules against both engines, and `--selftest` fails if the two
disagree about the same file.
## Two things reviewers should know
**The oxlint JS plugin API is alpha.** oxlint itself is stable and
already this repo's frontend linter; the plugin API is the new
dependency. Its documented failure mode
([oxc#25203](https://github.com/oxc-project/oxc/issues/25203)) is being
skipped silently while oxlint still reports success. That affects the
standalone release binary rather than the npm package this invokes, but
the class of failure reads exactly like clean code, so the run asserts
`number_of_rules >= 1` from oxlint's own report and a broken engine
exits 2 rather than passing. If the API ever breaks, the fallback is
folding these rules into the line scanner, which already implements all
nine for Java and Python.
**`.claude/settings.json` is now committed**, carrying the hook and
nothing else: 19 lines, no `permissions`, nothing machine-specific. That
partly reverts `c35546a212` ("Ignore claude dir"), which existed because
this file had twice been committed by accident with a personal
`permissions` allowlist, once with absolute machine paths. Personal
config still belongs in `.claude/settings.local.json`, which the new
pattern keeps ignored, and hook entries merge across the two so nobody's
own hooks are lost.
If you already hand-wrote a `.claude/settings.json`, copy it somewhere
first: that path used to be git-ignored, and git overwrites an ignored
file without warning when a commit starts tracking it. Across 19 local
checkouts here, 13 have `settings.local.json` and none has a
hand-written `settings.json`.
To turn the hook off, `{ "env": { "COMMENT_LINT_HOOK": "0" } }` in local
settings. Claude Code can only disable all hooks at once, hence the
switch. The commit-time gate still applies.
## How to test
```bash
task pre-commit:comment-lint:ci
```
The fixture corpus, then the diff. The corpus checks the rules
themselves rather than the code under review, so it runs on CI and
before a rule change, not on every local commit.
```bash
task comment-lint:branch
```
`clean (34 files in scope)`. `task comment-lint` is the same thing
scoped to uncommitted work, which is what the git hook and CI run.
To watch it bite, add `// Is banner` above `export function isBanner` in
`scripts/lint/comment-rules.mjs` and run `task comment-lint`: one
`CMT001`, exit 1. The gate covers its own source, which is why these
scripts have no section dividers.
```bash
task pre-commit:comment-lint:all
```
The standing backlog, report-only.
Verified on the pinned oxlint 1.77.0, not only the 1.79 the plugin was
prototyped against.
---
.claude/settings.json | 19 +
.github/pull_request_template.md | 1 +
.github/workflows/pre_commit.yml | 5 +
.gitignore | 9 +-
.taskfiles/pre-commit.yml | 82 +++
AGENTS.md | 39 +-
CONTRIBUTING.md | 1 +
Taskfile.yml | 14 +
devGuide/CODE_COMMENTS.md | 232 ++++++
devGuide/README.md | 1 +
frontend/oxlint.comments.config.ts | 31 +
scripts/lint/comment-lint-hook.mjs | 119 ++++
scripts/lint/comment-lint-oxlint-plugin.mjs | 126 ++++
scripts/lint/comment-lint.mjs | 743 ++++++++++++++++++++
scripts/lint/comment-rules.mjs | 500 +++++++++++++
scripts/lint/fixtures/AaaTest.java | 19 +
scripts/lint/fixtures/README.md | 17 +
scripts/lint/fixtures/allow.java | 32 +
scripts/lint/fixtures/apostrophes.java | 23 +
scripts/lint/fixtures/clean.java | 26 +
scripts/lint/fixtures/clean.ts | 17 +
scripts/lint/fixtures/deadcode.java | 14 +
scripts/lint/fixtures/docs.java | 12 +
scripts/lint/fixtures/docstrings.py | 36 +
scripts/lint/fixtures/expected.json | 63 ++
scripts/lint/fixtures/narration.java | 22 +
scripts/lint/fixtures/narration.tsx | 17 +
scripts/lint/fixtures/restates.java | 24 +
scripts/lint/fixtures/restates.py | 9 +
scripts/lint/fixtures/restates.ts | 20 +
scripts/lint/fixtures/strings.java | 11 +
scripts/lint/fixtures/templates.py | 24 +
scripts/lint/fixtures/todos.java | 25 +
scripts/lint/fixtures/trailing.java | 22 +
34 files changed, 2352 insertions(+), 3 deletions(-)
create mode 100644 .claude/settings.json
create mode 100644 devGuide/CODE_COMMENTS.md
create mode 100644 frontend/oxlint.comments.config.ts
create mode 100644 scripts/lint/comment-lint-hook.mjs
create mode 100644 scripts/lint/comment-lint-oxlint-plugin.mjs
create mode 100644 scripts/lint/comment-lint.mjs
create mode 100644 scripts/lint/comment-rules.mjs
create mode 100644 scripts/lint/fixtures/AaaTest.java
create mode 100644 scripts/lint/fixtures/README.md
create mode 100644 scripts/lint/fixtures/allow.java
create mode 100644 scripts/lint/fixtures/apostrophes.java
create mode 100644 scripts/lint/fixtures/clean.java
create mode 100644 scripts/lint/fixtures/clean.ts
create mode 100644 scripts/lint/fixtures/deadcode.java
create mode 100644 scripts/lint/fixtures/docs.java
create mode 100644 scripts/lint/fixtures/docstrings.py
create mode 100644 scripts/lint/fixtures/expected.json
create mode 100644 scripts/lint/fixtures/narration.java
create mode 100644 scripts/lint/fixtures/narration.tsx
create mode 100644 scripts/lint/fixtures/restates.java
create mode 100644 scripts/lint/fixtures/restates.py
create mode 100644 scripts/lint/fixtures/restates.ts
create mode 100644 scripts/lint/fixtures/strings.java
create mode 100644 scripts/lint/fixtures/templates.py
create mode 100644 scripts/lint/fixtures/todos.java
create mode 100644 scripts/lint/fixtures/trailing.java
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000000..40d0b73379
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,19 @@
+{
+ "$schema": "https://json.schemastore.org/claude-code-settings.json",
+ "hooks": {
+ "Stop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node",
+ "args": [
+ "${CLAUDE_PROJECT_DIR}/scripts/lint/comment-lint-hook.mjs"
+ ],
+ "timeout": 60
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index d9eb6dbe10..41666ff608 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -20,6 +20,7 @@ Closes #(issue_number)
- [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable)
- [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable)
- [ ] I have performed a self-review of my own code
+- [ ] Every comment I added says something the code does not ([guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/CODE_COMMENTS.md))
- [ ] My changes generate no new warnings
### Documentation
diff --git a/.github/workflows/pre_commit.yml b/.github/workflows/pre_commit.yml
index 674822363b..3566f5864f 100644
--- a/.github/workflows/pre_commit.yml
+++ b/.github/workflows/pre_commit.yml
@@ -38,3 +38,8 @@ jobs:
- name: Run pre-commit checks
run: task pre-commit
+
+ # The fixture corpus checks the comment rules themselves, so it runs here
+ # rather than on every local commit.
+ - name: Check the comment-lint fixture corpus
+ run: task pre-commit:comment-lint:selftest
diff --git a/.gitignore b/.gitignore
index 1290056e05..ca683dc5d4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -298,8 +298,13 @@ docs/type3/signatures/
**/application-dev-local.properties
-# Claude
-.claude/
+# Claude. Contents are ignored so personal config stays local, with the two
+# shared pieces re-included: settings.json (the comment-lint hook) and skills/.
+# The directory itself cannot be ignored or git will not look inside it.
+.claude/*
+!.claude/settings.json
+!.claude/skills/
+.claude/settings.local.json
# Playwright MCP screenshots / traces
.playwright-mcp/
diff --git a/.taskfiles/pre-commit.yml b/.taskfiles/pre-commit.yml
index 444115010f..f65a296160 100644
--- a/.taskfiles/pre-commit.yml
+++ b/.taskfiles/pre-commit.yml
@@ -11,6 +11,7 @@ vars:
'.github/scripts/*.py'
'app/core/src/main/resources/static/python/*.py'
':(exclude)*split_photos.py'
+ ':(exclude)scripts/lint/fixtures/*'
SPELL_FILES: >-
'*.html'
'*.css'
@@ -59,6 +60,7 @@ tasks:
- task: gitleaks
- task: whitespace
- task: toml-sort
+ - task: comment-lint
fix:
desc: "Auto-fix formatting, spelling, and secrets issues across the repo"
@@ -75,6 +77,7 @@ tasks:
vars: { FIX: '1' }
- task: codespell
- task: gitleaks
+ - task: comment-lint
install:
desc: "Install the pinned pre-commit Python tools"
@@ -130,6 +133,85 @@ tasks:
cmds:
- "{{.GITLEAKS_BIN}} git --pre-commit --redact --staged --verbose"
+ comment-lint:
+ desc: "Check comment quality on the lines this branch adds"
+ summary: |
+ Blocks a comment that restates the code below it, a section banner, or a
+ block of commented-out code. Everything else it reports is advisory.
+
+ Scoped to added lines, so touching an old file never surfaces the standing
+ backlog. The standard is devGuide/CODE_COMMENTS.md.
+
+ With no arguments it diffs the working tree against HEAD, which is what a
+ pre-commit run wants: the lines you are about to commit. On a CI pull request
+ it diffs against the target branch instead, via GITHUB_BASE_REF.
+
+ To ask what a whole branch adds instead, use the branch variant, which
+ needs no argument passing:
+ task comment-lint:branch
+
+ Full tree (report only): task pre-commit:comment-lint:all
+ Fixture corpus: task pre-commit:comment-lint:selftest
+ # Depends on the frontend install because the .ts/.tsx half of the rule set
+ # runs as an oxlint plugin. Without it the TS engine warns and skips, which
+ # would leave the frontend silently unchecked on CI.
+ deps: [":frontend:install"]
+ cmds:
+ - node scripts/lint/comment-lint.mjs {{.CLI_ARGS}}
+
+ comment-lint:branch:
+ desc: "Check comment quality on everything this branch adds over its base"
+ summary: |
+ Like `task comment-lint`, but scoped to the whole branch rather than to
+ uncommitted work, so it still reports after you commit.
+
+ Exists as its own task because passing `-- --since origin/main` through Task
+ is not portable: with the npm build of Task the launcher is a PowerShell
+ script, and PowerShell strips the `--` before Task sees it, leaving Task to
+ print its own usage.
+
+ Override the base with BASE=.
+ vars:
+ BASE: '{{.BASE | default "origin/main"}}'
+ deps: [":frontend:install"]
+ cmds:
+ - node scripts/lint/comment-lint.mjs --since {{.BASE}}
+
+ comment-lint:ci:
+ desc: "Comment gate as CI runs it: fixture corpus, then the diff"
+ summary: |
+ The corpus checks the rules themselves rather than the code under review, so
+ it belongs on CI and not on every local commit. Run this before changing a
+ rule, and let CI run it on every pull request.
+ deps: [":frontend:install"]
+ cmds:
+ - node scripts/lint/comment-lint.mjs --selftest
+ - node scripts/lint/comment-lint.mjs {{.CLI_ARGS}}
+
+ comment-lint:hook:
+ desc: "Comment gate for the editor hook: everything this turn changed"
+ summary: |
+ Same scope as `task comment-lint`, kept as its own name so the hook has a
+ stable entry point and the taskfile shows every way the linter is invoked.
+
+ Not in the frontend-install dependency chain on purpose: this runs at the end
+ of every turn, so it stays as short as it can be. If oxlint is missing the TS
+ half warns and skips.
+ cmds:
+ - node scripts/lint/comment-lint.mjs
+
+ comment-lint:all:
+ desc: "Report every comment finding in the tree (never fails)"
+ deps: [":frontend:install"]
+ cmds:
+ - node scripts/lint/comment-lint.mjs --all
+
+ comment-lint:selftest:
+ desc: "Check both comment-lint engines against the fixture corpus"
+ deps: [":frontend:install"]
+ cmds:
+ - node scripts/lint/comment-lint.mjs --selftest
+
gitleaks-bin:
internal: true
desc: "Ensure the pinned, checksum-verified gitleaks binary is cached in .task/bin"
diff --git a/AGENTS.md b/AGENTS.md
index 7383ab3c3d..88543ca3c8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,43 @@ Task `desc:` fields should describe **what** the task does, not **how** it does
- `task docker:build` — build standard Docker image
- `task docker:up` — start Docker compose stack
+## Comments
+
+A comment must carry information the code cannot. If a reader could derive it from the code in front of them, delete it.
+
+Comment the current state. Not what the code used to do, not what changed, not why it changed: git holds that. Where history explains the shape, state the reason instead, so "this used to reimplement the modal internals" becomes "thin wrapper over the shared Modal: duplicating its portal and focus trap is how dialogs drift apart". Future state goes in a TODO with an issue.
+
+Write a comment when it does one of these four jobs:
+
+- **Contract.** What a caller must know that the signature cannot say: preconditions, invariants, units, ownership and lifetime, thread-safety, error semantics, side effects. Document the contract of everything a caller outside the file can reach, and nothing else. Goes on the type/method/module as Javadoc, JSDoc, or a docstring.
+- **Why.** The constraint the code satisfies, the bug it avoids, the alternative rejected and the reason.
+- **Hazard.** "Must stay in sync with X", "order matters because Y", "do not remove, it prevents Z".
+- **Map.** A short orientation at the top of a genuinely complex file: what it owns, and what it deliberately does not.
+
+Never write:
+
+- A comment that restates the next line. `// Handle drag start` above `handleDragStart` is noise.
+- Section banners or position markers: `// --- Types ---`, `// Helpers`, `// =====`.
+- Step narration in a function body (`// Step 1:`, `// Then we`). If the steps need labels they need names: extract functions. Numbering a genuinely numbered thing, like a wizard step, is fine.
+- Commented-out code. Delete it.
+- Doc tags that restate the signature. `@param blob - The blob` says nothing; omit the tag rather than pad it.
+- Docs on self-explanatory members with no constraint to state.
+
+Two tests before keeping a comment:
+
+- **Delete it.** Is any information lost? If not, it stays deleted.
+- **Could a name carry it instead?** A better identifier, an extracted function, or a named constant beats a comment. Prefer the code change.
+
+A comment at the end of a line usually decodes that line, and that is worth keeping: `{0x25, 0x50} // "%PDF"`, `50L * 1024 * 1024 // 50 MB`. The rules that compare a comment against the code below it do not apply there, but a trailing TODO or a trailing bit of history is judged like any other.
+
+A reference is supplementary, never load-bearing: the comment must survive deleting it. `// See #1234` is a dead end; `// saving first loses every annotation (#6865)` is not. Prefer a spec (`RFC 3161`) or CVE where one applies.
+
+A TODO needs an issue, not an owner: `// TODO(#1234): re-enable the gate once account syncing lands`. If it is not worth an issue, it is not worth a TODO. A question is not a TODO.
+
+A comment block over ~12 lines outside a file or type header usually means the code needs restructuring, or that the prose is product documentation and belongs in the docs repo.
+
+`task comment-lint` checks the mechanical part of this on the lines you add, and runs inside `task pre-commit`. Reasoning, worked examples and the linter's own rules: @devGuide/CODE_COMMENTS.md
+
## Common Development Commands
### Build and Test
@@ -70,7 +107,7 @@ The project structure is defined in `engine/pyproject.toml`. Any new dependencie
- Avoid nested functions and nested classes unless the language construct requires them.
- Prefer composition to inheritance when combining concepts.
- Avoid speculative abstractions. Add a layer only when it removes real duplication or clarifies lifecycle.
-- Add comments sparingly and only when they explain non-obvious intent.
+- Comments follow the repo-wide rules in the "Comments" section above.
#### Python Typing and Models
- Deserialize into Pydantic models as early as possible.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 65fc4bc262..371630193b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,6 +42,7 @@ Please make sure your Pull Request adheres to the following guidelines:
- Keep commits atomic. One commit should contain one change. If you want to make multiple changes, submit multiple Pull Requests.
- Commits should be clear, concise, and easy to understand.
- References to the Issue number in the Pull Request and/or Commit message.
+- Every comment in the diff should say something the code does not. See [Code comments](devGuide/CODE_COMMENTS.md); `task comment-lint` checks the mechanical part.
## Translations
diff --git a/Taskfile.yml b/Taskfile.yml
index e364242f1f..eaec7dec92 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -266,6 +266,20 @@ tasks:
cmds:
- task: frontend:lint
- task: engine:lint
+ - task: comment-lint
+
+ comment-lint:
+ desc: "Check comment quality on the lines this branch adds"
+ aliases: [comments]
+ cmds:
+ - task: pre-commit:comment-lint
+ vars: { CLI_ARGS: '{{.CLI_ARGS}}' }
+
+ comment-lint:branch:
+ desc: "Check comment quality on everything this branch adds over its base"
+ cmds:
+ - task: pre-commit:comment-lint:branch
+ vars: { BASE: '{{.BASE}}' }
fix:
desc: "Auto-fix all components"
diff --git a/devGuide/CODE_COMMENTS.md b/devGuide/CODE_COMMENTS.md
new file mode 100644
index 0000000000..739744142f
--- /dev/null
+++ b/devGuide/CODE_COMMENTS.md
@@ -0,0 +1,232 @@
+# Code comments
+
+A comment must carry information the code cannot. If a reader could derive it from
+the code in front of them, delete it: a redundant comment still has to be
+maintained, will eventually contradict the code, and dilutes the comments that
+matter.
+
+The operative rules are in `AGENTS.md`, kept short so they stay in an agent's
+context. This document is the reasoning and the worked examples behind them, plus
+how to run the linter.
+
+## Comment the current state
+
+Describe the code as it is. Not what it used to be, not what changed, not why it
+changed. A comment that narrates history is stale the moment the next change
+lands, and git already holds that record.
+
+When you know the history and it explains the shape of the code, the useful half is
+the reason, not the sequence. State the reason:
+
+```java
+// Don't:
+// This used to reimplement the modal internals, which is how the procurement
+// dialogs drifted from the billing ones.
+
+// Do:
+// Thin wrapper over the shared Modal: duplicating its portal and focus trap is
+// how dialogs drift apart.
+```
+
+Future state is the exception, and it belongs in a TODO with an issue.
+
+## The four jobs
+
+**Contract.** What a caller must know that the signature cannot say:
+preconditions, invariants, units, ownership and lifetime, thread-safety, error
+semantics, side effects.
+
+The bound is the surface, not the volume: document the contract of everything a
+caller outside the file can reach, and nothing else. Inside that surface say
+whatever a caller needs; outside it a comment earns its place on the same terms as
+any other.
+
+```java
+/**
+ * Authority on which filesystem locations a policy may read or write. Fail-closed
+ * in order: denied entirely under the saas profile; Stirling's own config dir is
+ * always rejected; the path must resolve within policies.allowedFolderRoots.
+ *
+ *