@vertesia/ui 1.5.0-dev.20260717.131047Z → 1.5.0-dev.20260725.083715Z

package/src/rich-text/VertesiaRichTextEditor.test.tsx

@@ -0,0 +1,211 @@
+/** @vitest-environment jsdom */
+
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { MarkdownRichTextEditor, type MarkdownRichTextEditorProps, setEditorMarkdown } from '@vertesia/rich-text';
+import { describe, expect, it, vi } from 'vitest';
+import { I18nProvider } from '../i18n/index.js';
+import {
+    VertesiaMarkdownComponentEditor,
+    VertesiaMarkdownDocumentEditor,
+    VertesiaMarkdownRichTextEditor,
+    vertesiaRichTextRenderers,
+} from './VertesiaRichTextEditor.js';
+
+describe('VertesiaMarkdownRichTextEditor', () => {
+    it('renders Markdown and emits serialized Markdown after an editor update', async () => {
+        const onChange = vi.fn();
+        let editor: Parameters<NonNullable<MarkdownRichTextEditorProps['onEditor']>>[0] = null;
+
+        render(
+            <VertesiaMarkdownRichTextEditor
+                value="# Original heading"
+                onChange={onChange}
+                onEditor={(nextEditor) => {
+                    editor = nextEditor;
+                }}
+            />,
+        );
+
+        expect(await screen.findByRole('heading', { name: 'Original heading' })).not.toBeNull();
+        await waitFor(() => expect(editor).not.toBeNull());
+
+        act(() => {
+            if (editor) setEditorMarkdown(editor, '## Updated heading', true);
+        });
+
+        expect(await screen.findByRole('heading', { name: 'Updated heading' })).not.toBeNull();
+        expect(onChange).toHaveBeenLastCalledWith(expect.stringContaining('## Updated heading'));
+    });
+
+    it('provides adapters for each Vertesia-specific Markdown surface', () => {
+        expect(vertesiaRichTextRenderers.codeBlock).toBeTypeOf('function');
+        expect(vertesiaRichTextRenderers.image).toBeTypeOf('function');
+        expect(vertesiaRichTextRenderers.link).toBeTypeOf('function');
+        expect(vertesiaRichTextRenderers.opaqueBlock).toBeTypeOf('function');
+    });
+
+    it('keeps the editor instance when a consumer passes new renderer component identities', async () => {
+        const onEditor = vi.fn();
+        const view = render(<MarkdownRichTextEditor value="Paragraph" codeBlock={() => null} onEditor={onEditor} />);
+        await screen.findByText('Paragraph');
+        const initialEditor = onEditor.mock.calls.find(([value]) => value)?.[0];
+
+        view.rerender(<MarkdownRichTextEditor value="Paragraph" codeBlock={() => null} onEditor={onEditor} />);
+
+        expect(onEditor.mock.calls.filter(([value]) => value).at(-1)?.[0]).toBe(initialEditor);
+        expect(new Set(onEditor.mock.calls.flatMap(([value]) => (value ? [value] : [])))).toHaveLength(1);
+    });
+
+    it('defers external values while focused so the caret is not reset', async () => {
+        const view = render(<MarkdownRichTextEditor value="Original paragraph" />);
+        const textbox = await screen.findByRole('textbox');
+        fireEvent.focus(textbox);
+
+        view.rerender(<MarkdownRichTextEditor value="External paragraph" />);
+        expect(screen.getByText('Original paragraph')).not.toBeNull();
+        expect(screen.queryByText('External paragraph')).toBeNull();
+
+        fireEvent.blur(textbox);
+        expect(await screen.findByText('External paragraph')).not.toBeNull();
+    });
+
+    it('offers a formatting toolbar for both the compact component editor and the full-document editor', async () => {
+        const { rerender } = render(
+            <I18nProvider lng="en">
+                <VertesiaMarkdownComponentEditor value="Component text" />
+            </I18nProvider>,
+        );
+
+        expect(await screen.findByText('Component text')).not.toBeNull();
+        // The compact component editor now carries the same formatting toolbar as the document editor.
+        expect(await screen.findByRole('toolbar')).not.toBeNull();
+
+        rerender(
+            <I18nProvider lng="en">
+                <VertesiaMarkdownDocumentEditor value="# Full document" />
+            </I18nProvider>,
+        );
+
+        expect(await screen.findByRole('heading', { name: 'Full document' })).not.toBeNull();
+        expect(await screen.findByRole('toolbar')).not.toBeNull();
+        expect(screen.getByRole('textbox', { name: 'Markdown document editor' })).not.toBeNull();
+    });
+
+    it('puts the document hand-off in the editor toolbar and highlights it when edits are pending', async () => {
+        const onSendChangesToAgent = vi.fn();
+        const view = render(
+            <I18nProvider lng="en">
+                <VertesiaMarkdownDocumentEditor
+                    value="Document text"
+                    onSendChangesToAgent={onSendChangesToAgent}
+                    hasUnsentChanges={false}
+                />
+            </I18nProvider>,
+        );
+
+        const inactiveButton = await screen.findByRole('button', { name: 'Send changes to agent' });
+        expect(screen.getByRole('toolbar').contains(inactiveButton)).toBe(true);
+        expect(inactiveButton).toHaveProperty('disabled', true);
+        expect(inactiveButton.className).not.toContain('bg-primary');
+
+        view.rerender(
+            <I18nProvider lng="en">
+                <VertesiaMarkdownDocumentEditor
+                    value="Document text"
+                    onSendChangesToAgent={onSendChangesToAgent}
+                    hasUnsentChanges
+                />
+            </I18nProvider>,
+        );
+
+        const activeButton = screen.getByRole('button', { name: 'Send changes to agent' });
+        expect(activeButton).toHaveProperty('disabled', false);
+        expect(activeButton.className).toContain('bg-primary');
+        fireEvent.click(activeButton);
+        expect(onSendChangesToAgent).toHaveBeenCalledTimes(1);
+    });
+
+    it('sends selected-text comments while full-document content editing is locked', async () => {
+        const onSendComment = vi.fn();
+        let editor: Parameters<NonNullable<MarkdownRichTextEditorProps['onEditor']>>[0] = null;
+        render(
+            <I18nProvider lng="en">
+                <VertesiaMarkdownDocumentEditor
+                    value="Locked paragraph."
+                    editable={false}
+                    onSendComment={onSendComment}
+                    onEditor={(nextEditor) => {
+                        editor = nextEditor;
+                    }}
+                />
+            </I18nProvider>,
+        );
+
+        await waitFor(() => expect(editor).not.toBeNull());
+        act(() => {
+            editor?.commands.setTextSelection({ from: 1, to: 7 });
+        });
+        expect(screen.getByRole('button', { name: 'Bold' })).toHaveProperty('disabled', true);
+        const commentButton = await screen.findByRole('button', { name: 'Comment on selection' });
+        expect(screen.getByRole('toolbar').contains(commentButton)).toBe(false);
+        expect(commentButton.parentElement?.className).toContain('pointer-events-auto');
+        expect(commentButton.parentElement?.className).toContain('z-100');
+        fireEvent.click(commentButton);
+        expect(screen.getByRole('dialog', { name: 'Comment on selection' })).not.toBeNull();
+        fireEvent.change(screen.getByPlaceholderText('Describe how the agent should improve this section...'), {
+            target: { value: 'Make this claim measurable.' },
+        });
+        fireEvent.click(screen.getByRole('button', { name: 'Add comment' }));
+        fireEvent.click(screen.getByRole('button', { name: 'Send to agent' }));
+
+        await waitFor(() => expect(onSendComment).toHaveBeenCalledTimes(1));
+        expect(onSendComment).toHaveBeenCalledWith(expect.stringContaining('“Locked”'));
+        expect(onSendComment).toHaveBeenCalledWith(expect.stringContaining('Make this claim measurable.'));
+    });
+
+    it('opens structurally preserving normalized Markdown directly in rich-text mode', async () => {
+        const onChange = vi.fn();
+        render(
+            <I18nProvider lng="en">
+                <VertesiaMarkdownDocumentEditor value={'Setext heading\n=============='} onChange={onChange} />
+            </I18nProvider>,
+        );
+
+        expect(await screen.findByRole('heading', { name: 'Setext heading' })).not.toBeNull();
+        expect(screen.getByRole('textbox', { name: 'Markdown document editor' })).not.toBeNull();
+        expect(screen.queryByRole('heading', { name: 'Some Markdown formatting may change' })).toBeNull();
+        expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('lets the user preserve Markdown source when normalization is lossy', async () => {
+        const onChange = vi.fn();
+        render(
+            <I18nProvider lng="en">
+                <VertesiaMarkdownDocumentEditor value="#" onChange={onChange} />
+            </I18nProvider>,
+        );
+
+        expect(await screen.findByRole('heading', { name: 'Some Markdown formatting may change' })).not.toBeNull();
+        fireEvent.click(screen.getByRole('button', { name: 'Edit Markdown source' }));
+
+        const sourceEditor = screen.getByRole('textbox', { name: 'Markdown source editor' });
+        expect((sourceEditor as HTMLTextAreaElement).value).toBe('#');
+        fireEvent.change(sourceEditor, { target: { value: '##' } });
+        expect(onChange).toHaveBeenLastCalledWith('##');
+    });
+
+    it('lets the user accept a lossy conversion and continue in rich-text mode', async () => {
+        render(
+            <I18nProvider lng="en">
+                <VertesiaMarkdownDocumentEditor value="#" />
+            </I18nProvider>,
+        );
+
+        fireEvent.click(await screen.findByRole('button', { name: 'Continue with rich text' }));
+
+        expect(await screen.findByRole('textbox', { name: 'Markdown document editor' })).not.toBeNull();
+    });
+
+    // Table row/column actions live in the toolbar's Table context dropdown (only when the caret is
+    // in a table); list indent/outdent is handled by Tab / Shift-Tab rather than a toolbar control.
+});

package/src/rich-text/VertesiaRichTextEditor.tsx

@@ -0,0 +1,241 @@
+import {
+    type Editor,
+    getMarkdownCompatibility,
+    MarkdownComponentEditor,
+    type MarkdownComponentEditorProps,
+    MarkdownDocumentEditor,
+    type MarkdownDocumentEditorProps,
+    MarkdownRichTextEditor,
+    type MarkdownRichTextEditorProps,
+    type RichTextCodeBlockRendererProps,
+    type RichTextImageRendererProps,
+    type RichTextLinkRendererProps,
+    type RichTextOpaqueBlockRendererProps,
+    type RichTextRenderers,
+} from '@vertesia/rich-text';
+import { Button, cn, Modal, ModalBody, ModalFooter, ModalTitle, Textarea } from '@vertesia/ui/core';
+import { useUITranslation } from '@vertesia/ui/i18n';
+import { type ReactNode, useCallback, useState } from 'react';
+import { CodeBlockHandlerProvider, useCodeBlockContext } from '../widgets/markdown/CodeBlockContext.js';
+import { useCodeBlockRendererRegistry } from '../widgets/markdown/CodeBlockRendering.js';
+import { createDefaultCodeBlockHandlers, ExpandCodeBlockHandler } from '../widgets/markdown/codeBlockHandlers.js';
+import { MarkdownFigure } from '../widgets/markdown/MarkdownFigure.js';
+import { MarkdownImage } from '../widgets/markdown/MarkdownImage.js';
+import { MarkdownLink } from '../widgets/markdown/MarkdownLink.js';
+import { MarkdownRenderer } from '../widgets/markdown/MarkdownRenderer.js';
+import { EditorToolbar, SendChangesToAgentButton } from './EditorToolbar.js';
+
+const defaultCodeBlockHandlers = createDefaultCodeBlockHandlers();
+
+function VertesiaCodeBlockPreview({ code, language }: RichTextCodeBlockRendererProps) {
+    const registry = useCodeBlockRendererRegistry();
+    const CustomRenderer = language ? registry?.getComponent(language) : undefined;
+    const DefaultRenderer = language ? defaultCodeBlockHandlers[language] : undefined;
+    const Renderer = language?.startsWith('expand:') ? ExpandCodeBlockHandler : (CustomRenderer ?? DefaultRenderer);
+
+    if (!Renderer) return null;
+    return <Renderer code={code} language={language} />;
+}
+
+function VertesiaImagePreview({ src, alt, title }: RichTextImageRendererProps) {
+    const { artifactRunId } = useCodeBlockContext();
+    if (title) {
+        return <MarkdownFigure src={src} alt={alt} caption={title} artifactRunId={artifactRunId} />;
+    }
+    return <MarkdownImage src={src} alt={alt} artifactRunId={artifactRunId} />;
+}
+
+function VertesiaLinkPreview({ href, title, children }: RichTextLinkRendererProps) {
+    const { artifactRunId } = useCodeBlockContext();
+    return (
+        <MarkdownLink href={href} artifactRunId={artifactRunId}>
+            <span title={title}>{children}</span>
+        </MarkdownLink>
+    );
+}
+
+function VertesiaOpaqueBlockPreview({ raw }: RichTextOpaqueBlockRendererProps) {
+    const { artifactRunId } = useCodeBlockContext();
+    return <MarkdownRenderer artifactRunId={artifactRunId}>{raw}</MarkdownRenderer>;
+}
+
+export const vertesiaRichTextRenderers: RichTextRenderers = {
+    codeBlock: VertesiaCodeBlockPreview,
+    image: VertesiaImagePreview,
+    link: VertesiaLinkPreview,
+    opaqueBlock: VertesiaOpaqueBlockPreview,
+};
+
+interface VertesiaEditorProps {
+    artifactRunId?: string;
+}
+
+export interface VertesiaMarkdownRichTextEditorProps
+    extends Omit<MarkdownRichTextEditorProps, keyof RichTextRenderers>,
+        VertesiaEditorProps {}
+
+export function VertesiaMarkdownRichTextEditor({ artifactRunId, ...props }: VertesiaMarkdownRichTextEditorProps) {
+    return (
+        <CodeBlockHandlerProvider artifactRunId={artifactRunId} MarkdownRenderer={MarkdownRenderer}>
+            <MarkdownRichTextEditor {...props} {...vertesiaRichTextRenderers} />
+        </CodeBlockHandlerProvider>
+    );
+}
+
+export interface VertesiaMarkdownComponentEditorProps
+    extends Omit<MarkdownComponentEditorProps, keyof RichTextRenderers>,
+        VertesiaEditorProps {}
+
+export function VertesiaMarkdownComponentEditor({
+    artifactRunId,
+    className,
+    contentClassName,
+    editorClassName,
+    onEditor,
+    ...props
+}: VertesiaMarkdownComponentEditorProps) {
+    const [editor, setEditor] = useState<Editor | null>(null);
+    const handleEditor = useCallback(
+        (next: Editor | null) => {
+            setEditor(next);
+            onEditor?.(next);
+        },
+        [onEditor],
+    );
+
+    return (
+        <CodeBlockHandlerProvider artifactRunId={artifactRunId} MarkdownRenderer={MarkdownRenderer}>
+            <div className={cn('overflow-hidden rounded-md border border-mixer-muted/30 bg-background', className)}>
+                <EditorToolbar editor={editor} editable={props.editable !== false} />
+                <MarkdownComponentEditor
+                    {...props}
+                    {...vertesiaRichTextRenderers}
+                    onEditor={handleEditor}
+                    contentClassName={cn('max-h-80 overflow-auto', contentClassName)}
+                    editorClassName={cn('vprose prose-sm min-h-24 max-w-none px-3 py-2 outline-none', editorClassName)}
+                />
+            </div>
+        </CodeBlockHandlerProvider>
+    );
+}
+
+export interface VertesiaMarkdownDocumentEditorProps
+    extends Omit<MarkdownDocumentEditorProps, keyof RichTextRenderers>,
+        VertesiaEditorProps {
+    /** When set, the toolbar shows comment controls that queue and send a batch to the agent. */
+    onSendComment?: (message: string) => void | Promise<void>;
+    /** When set, the editor shows the document-level hand-off action in its own toolbar. */
+    onSendChangesToAgent?: () => void | Promise<void>;
+    hasUnsentChanges?: boolean;
+    isSendingChanges?: boolean;
+    sendChangesDisabled?: boolean;
+    /** Compact status rendered immediately beside the document hand-off action. */
+    toolbarStatus?: ReactNode;
+}
+
+export function VertesiaMarkdownDocumentEditor({
+    artifactRunId,
+    className,
+    contentClassName,
+    editorClassName,
+    onEditor,
+    onSendComment,
+    onSendChangesToAgent,
+    hasUnsentChanges = false,
+    isSendingChanges = false,
+    sendChangesDisabled = false,
+    toolbarStatus,
+    ...props
+}: VertesiaMarkdownDocumentEditorProps) {
+    const { t } = useUITranslation();
+    const [editor, setEditor] = useState<Editor | null>(null);
+    const handleEditor = useCallback(
+        (next: Editor | null) => {
+            setEditor(next);
+            onEditor?.(next);
+        },
+        [onEditor],
+    );
+    const [editingMode, setEditingMode] = useState<'choose' | 'rich-text' | 'source'>(() =>
+        getMarkdownCompatibility(props.value) === 'lossy' ? 'choose' : 'rich-text',
+    );
+    const resolvedEditingMode = editingMode === 'choose' ? 'source' : editingMode;
+
+    return (
+        <CodeBlockHandlerProvider artifactRunId={artifactRunId} MarkdownRenderer={MarkdownRenderer}>
+            {resolvedEditingMode === 'rich-text' ? (
+                <div className={cn('flex h-full min-h-0 flex-col bg-background', className)}>
+                    <EditorToolbar
+                        editor={editor}
+                        editable={props.editable !== false}
+                        onSendComment={onSendComment}
+                        onSendChangesToAgent={onSendChangesToAgent}
+                        hasUnsentChanges={hasUnsentChanges}
+                        isSendingChanges={isSendingChanges}
+                        sendChangesDisabled={sendChangesDisabled}
+                        toolbarStatus={toolbarStatus}
+                    />
+                    <MarkdownDocumentEditor
+                        {...props}
+                        {...vertesiaRichTextRenderers}
+                        onEditor={handleEditor}
+                        ariaLabel={props.ariaLabel ?? t('richText.documentEditor')}
+                        className="flex min-h-0 flex-1 flex-col"
+                        contentClassName={cn('min-h-0 flex-1 overflow-auto', contentClassName)}
+                        editorClassName={cn(
+                            'vprose prose-sm mx-auto min-h-full w-full max-w-5xl px-6 py-5 outline-none',
+                            editorClassName,
+                        )}
+                    />
+                </div>
+            ) : (
+                <div className={cn('flex h-full min-h-0 flex-col bg-background', className)}>
+                    {onSendChangesToAgent ? (
+                        <div className="flex min-h-10 shrink-0 items-center justify-end gap-1 border-b border-mixer-muted/25 px-1.5 py-1">
+                            {toolbarStatus}
+                            <SendChangesToAgentButton
+                                onSend={onSendChangesToAgent}
+                                hasUnsentChanges={hasUnsentChanges}
+                                isSending={isSendingChanges}
+                                disabled={sendChangesDisabled}
+                            />
+                        </div>
+                    ) : null}
+                    <Textarea
+                        value={props.value}
+                        onChange={(event) => props.onChange?.(event.target.value)}
+                        onFocus={() => props.onFocusChange?.(true)}
+                        onBlur={() => props.onFocusChange?.(false)}
+                        disabled={props.editable === false}
+                        aria-label={t('richText.markdownSourceEditor')}
+                        className={cn(
+                            'vertesia-markdown-document-editor-content min-h-0 flex-1 resize-none rounded-none',
+                            'border-0 px-6 py-5 font-mono text-sm leading-6 outline-none focus-visible:ring-0',
+                            contentClassName,
+                            editorClassName,
+                        )}
+                    />
+                </div>
+            )}
+            <Modal
+                isOpen={editingMode === 'choose'}
+                onClose={() => setEditingMode('source')}
+                className="sm:max-w-lg"
+                disableCloseOnClickOutside
+            >
+                <ModalTitle>{t('richText.sourceCompatibilityWarningTitle')}</ModalTitle>
+                <ModalBody>
+                    <p className="text-sm text-muted">{t('richText.sourceCompatibilityWarningDescription')}</p>
+                </ModalBody>
+                <ModalFooter align="right">
+                    <Button variant="outline" onClick={() => setEditingMode('source')}>
+                        {t('richText.editMarkdownSource')}
+                    </Button>
+                    <Button variant="secondary" onClick={() => setEditingMode('rich-text')}>
+                        {t('richText.continueRichText')}
+                    </Button>
+                </ModalFooter>
+            </Modal>
+        </CodeBlockHandlerProvider>
+    );
+}

package/src/rich-text/index.ts

@@ -0,0 +1,9 @@
+export {
+    VertesiaMarkdownComponentEditor,
+    type VertesiaMarkdownComponentEditorProps,
+    VertesiaMarkdownDocumentEditor,
+    type VertesiaMarkdownDocumentEditorProps,
+    VertesiaMarkdownRichTextEditor,
+    type VertesiaMarkdownRichTextEditorProps,
+    vertesiaRichTextRenderers,
+} from './VertesiaRichTextEditor';

package/src/router/HistoryNavigator.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { HistoryNavigator } from './HistoryNavigator';
+
+describe('HistoryNavigator link interception', () => {
+    afterEach(() => {
+        document.body.replaceChildren();
+        vi.restoreAllMocks();
+    });
+
+    it('leaves targeted internal links to native browser navigation', () => {
+        const navigator = new HistoryNavigator();
+        const navigate = vi.spyOn(navigator as unknown as { _navigate: () => void }, '_navigate');
+        const link = document.createElement('a');
+        const icon = document.createElement('span');
+        link.href = '/store/executions/run-1?p=project&a=account';
+        link.target = '_blank';
+        link.append(icon);
+        document.body.append(link);
+        navigator.start();
+
+        const event = new MouseEvent('click', { bubbles: true, cancelable: true, button: 0 });
+        icon.dispatchEvent(event);
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(navigate).not.toHaveBeenCalled();
+        navigator.stop();
+    });
+
+    it('continues to intercept ordinary same-origin links', () => {
+        const navigator = new HistoryNavigator();
+        const navigate = vi
+            .spyOn(navigator as unknown as { _navigate: () => void }, '_navigate')
+            .mockImplementation(() => undefined);
+        const link = document.createElement('a');
+        const label = document.createElement('span');
+        link.href = '/store/executions/run-1';
+        link.append(label);
+        document.body.append(link);
+        navigator.start();
+
+        const event = new MouseEvent('click', { bubbles: true, cancelable: true, button: 0 });
+        label.dispatchEvent(event);
+
+        expect(event.defaultPrevented).toBe(true);
+        expect(navigate).toHaveBeenCalledOnce();
+        navigator.stop();
+    });
+});

package/src/router/HistoryNavigator.ts

@@ -72,14 +72,16 @@ export interface NavigateOptions {
     title?: string;
 }
 
-function getElementHrefAsUrl(elem: HTMLElement) {
-    if (elem && elem.tagName.toLowerCase() === 'a') {
-        const href = (elem as HTMLAnchorElement)?.href.trim();
-        if (typeof href === 'string' && href.length > 0) {
-            return new URL(href);
-        }
+function getClosestAnchor(target: EventTarget | null): HTMLAnchorElement | null {
+    if (!(target instanceof Element)) {
+        return null;
     }
-    return null;
+    return target.closest<HTMLAnchorElement>('a[href]');
+}
+
+function getElementHrefAsUrl(elem: HTMLAnchorElement) {
+    const href = elem.href.trim();
+    return href.length > 0 ? new URL(href) : null;
 }
 
 export class HistoryNavigator {
@@ -236,16 +238,25 @@ export class HistoryNavigator {
             this.fireLocationChange(new AfterLocationChangeEvent(type, to, state));
         };
         const _linkNavListener = (ev: MouseEvent) => {
-            const target = ev.target as HTMLElement;
-            // Skip anchors with download attribute or blob: URLs - they are file downloads, not navigation
+            // Let the browser handle modifier / non-primary clicks natively (open in new tab/window,
+            // download). Intercepting them here would preventDefault those affordances.
+            if (ev.defaultPrevented || ev.metaKey || ev.altKey || ev.ctrlKey || ev.shiftKey || ev.button !== 0) {
+                return;
+            }
+            const anchor = getClosestAnchor(ev.target);
+            if (!anchor) {
+                return;
+            }
+            const anchorTarget = anchor.getAttribute('target');
+            // Downloads, blob URLs, and explicitly targeted links require native browser navigation.
             if (
-                target.tagName.toLowerCase() === 'a' &&
-                ((target as HTMLAnchorElement).hasAttribute('download') ||
-                    (target as HTMLAnchorElement).href?.startsWith('blob:'))
+                anchor.hasAttribute('download') ||
+                anchor.href.startsWith('blob:') ||
+                (!!anchorTarget && anchorTarget.toLowerCase() !== '_self')
             ) {
                 return;
             }
-            const url = getElementHrefAsUrl(target);
+            const url = getElementHrefAsUrl(anchor);
             if (url && url.origin === window.location.origin) {
                 ev.preventDefault();
                 const to = new URL(this.addStickyParams(url.href));

package/src/router/Nav.tsx

@@ -1,7 +1,16 @@
-import type { SyntheticEvent } from 'react';
+import type { MouseEvent, SyntheticEvent } from 'react';
 import { withMountBasename } from './path';
 import { useNavigate, useRouterContext } from './Router';
 
+/**
+ * True when the click carries a modifier the browser uses for alternate link behavior
+ * (open in new tab/window, download) or is not a primary-button click. Such clicks must fall
+ * through to the native anchor so the browser can handle them instead of the SPA router.
+ */
+function isModifiedClick(ev: MouseEvent): boolean {
+    return ev.metaKey || ev.altKey || ev.ctrlKey || ev.shiftKey || ev.button !== 0;
+}
+
 /**
  * Wraps a <a href="..."> and perform the navigation to href through the router.
  */
@@ -71,19 +80,20 @@ export function NavLink({
     skipStickyParams,
 }: NavLinkProps) {
     const { router } = useRouterContext();
-    // In-app route = not an external URL, `_blank` target, or bare hash. Relative paths count too —
-    // they must be routed, else the global link listener re-applies the module base path (wrong URL).
+    // Resolve internal URLs even when a target makes navigation native. New-tab links still need
+    // the mount path and tenant sticky params, but must not be intercepted by the SPA router.
     const isAnchorOrEmpty = !href || href.startsWith('#');
-    const isExternal = /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//') || (!!target && target !== '_self');
-    const isInternal = !isAnchorOrEmpty && !isExternal;
+    const isExternalUrl = /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//');
+    const isInternalUrl = !isAnchorOrEmpty && !isExternalUrl;
+    const isNativeNavigation = !!target && target !== '_self';
     // Keep the rendered href under the served `<base href>` mount (correct middle-click / hover /
     // open-in-new-tab); the onClick navigates via the router which applies the same rule. No-op when
     // origin-served (Studio UI). Click handler below passes the raw `href` — navigate() re-bases it.
-    const resolvedHref = isInternal
+    const resolvedHref = isInternalUrl
         ? withMountBasename(!skipStickyParams ? router.getTopRouter().navigator.addStickyParams(href) : href)
         : href;
-    const _onClick = (ev: SyntheticEvent) => {
-        if (ev.defaultPrevented || !isInternal) {
+    const _onClick = (ev: MouseEvent) => {
+        if (ev.defaultPrevented || !isInternalUrl || isNativeNavigation || isModifiedClick(ev)) {
             return;
         }
         ev.stopPropagation();

package/src/session/UserSession.test.ts

@@ -0,0 +1,39 @@
+import type { VertesiaClient } from '@vertesia/client';
+import { describe, expect, it, vi } from 'vitest';
+import { UserSession } from './UserSession';
+
+function createSession(onboardingProgress: () => Promise<Record<string, boolean>>) {
+    const client = {
+        account: { onboardingProgress },
+    } as unknown as VertesiaClient;
+    const setSession = vi.fn<(session: UserSession) => void>();
+    const session = new UserSession(client, setSession);
+    return { session, setSession };
+}
+
+describe('UserSession.fetchOnboardingStatus', () => {
+    it('does not replace the session when an incomplete status is unchanged', async () => {
+        const { session, setSession } = createSession(async () => ({ project_created: false }));
+        session.onboardingComplete = false;
+
+        await expect(session.fetchOnboardingStatus()).resolves.toBe(false);
+        expect(setSession).not.toHaveBeenCalled();
+    });
+
+    it('updates the session and reports when onboarding becomes complete', async () => {
+        const { session, setSession } = createSession(async () => ({ project_created: true }));
+        session.onboardingComplete = false;
+
+        await expect(session.fetchOnboardingStatus()).resolves.toBe(true);
+        expect(setSession).toHaveBeenCalledOnce();
+        expect(setSession.mock.calls[0]?.[0]?.onboardingComplete).toBe(true);
+    });
+
+    it('publishes the initial incomplete status without reporting completion', async () => {
+        const { session, setSession } = createSession(async () => ({ project_created: false }));
+
+        await expect(session.fetchOnboardingStatus()).resolves.toBe(false);
+        expect(setSession).toHaveBeenCalledOnce();
+        expect(setSession.mock.calls[0]?.[0]?.onboardingComplete).toBe(false);
+    });
+});