@vertesia/ui 1.5.0-dev.20260722.120446Z → 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/session/UserSession.test.ts

@@ -6,34 +6,34 @@ function createSession(onboardingProgress: () => Promise<Record<string, boolean>
     const client = {
         account: { onboardingProgress },
     } as unknown as VertesiaClient;
-    const session = new UserSession(client);
-    session.setSession = vi.fn();
-    return session;
+    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 = createSession(async () => ({ project_created: false }));
+        const { session, setSession } = createSession(async () => ({ project_created: false }));
         session.onboardingComplete = false;
 
         await expect(session.fetchOnboardingStatus()).resolves.toBe(false);
-        expect(session.setSession).not.toHaveBeenCalled();
+        expect(setSession).not.toHaveBeenCalled();
     });
 
     it('updates the session and reports when onboarding becomes complete', async () => {
-        const session = createSession(async () => ({ project_created: true }));
+        const { session, setSession } = createSession(async () => ({ project_created: true }));
         session.onboardingComplete = false;
 
         await expect(session.fetchOnboardingStatus()).resolves.toBe(true);
-        expect(session.setSession).toHaveBeenCalledOnce();
-        expect(vi.mocked(session.setSession!).mock.calls[0]?.[0]?.onboardingComplete).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 = createSession(async () => ({ project_created: false }));
+        const { session, setSession } = createSession(async () => ({ project_created: false }));
 
         await expect(session.fetchOnboardingStatus()).resolves.toBe(false);
-        expect(session.setSession).toHaveBeenCalledOnce();
-        expect(vi.mocked(session.setSession!).mock.calls[0]?.[0]?.onboardingComplete).toBe(false);
+        expect(setSession).toHaveBeenCalledOnce();
+        expect(setSession.mock.calls[0]?.[0]?.onboardingComplete).toBe(false);
     });
 });

package/src/widgets/markdown/AgentResourceResolver.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { parseAgentResourceHref } from './AgentResourceResolver';
+
+describe('parseAgentResourceHref', () => {
+    it.each([
+        ['store:doc-1', 'document', 'doc-1'],
+        ['document://doc-1', 'document', 'doc-1'],
+        ['collection:col-1', 'collection', 'col-1'],
+        ['interaction:int-1', 'interaction', 'int-1'],
+        ['prompt:prompt-1', 'prompt', 'prompt-1'],
+        ['agent:agent-1', 'agent', 'agent-1'],
+        ['workflow:workflow-1', 'workflow', 'workflow-1'],
+        ['process:process-1', 'process', 'process-1'],
+        ['run:run-1', 'interaction_run', 'run-1'],
+    ] as const)('maps %s to a resource reference', (rawHref, type, id) => {
+        expect(parseAgentResourceHref(rawHref)).toEqual({ type, id });
+    });
+
+    it('returns undefined for standard, file, and empty resource URLs', () => {
+        expect(parseAgentResourceHref('https://example.com')).toBeUndefined();
+        expect(parseAgentResourceHref('artifact:report.pdf')).toBeUndefined();
+        expect(parseAgentResourceHref('store:')).toBeUndefined();
+    });
+});

package/src/widgets/markdown/AgentResourceResolver.tsx

@@ -0,0 +1,70 @@
+import type { AgentResourceAction, AgentResourceType } from '@vertesia/common';
+import { createContext, useContext } from 'react';
+
+/** Resource identity accepted by link resolvers from either structured tool metadata or Markdown. */
+export interface AgentResourceLinkReference {
+    type: AgentResourceType;
+    id: string;
+    label?: string;
+    action?: AgentResourceAction;
+    revision_id?: string;
+}
+
+export type AgentResourceTarget =
+    | { kind: 'navigate'; href: string }
+    | { kind: 'activate'; onActivate: () => void }
+    | { kind: 'none' };
+
+export interface ResourceResolveContext {
+    workflowRunId?: string;
+    source: 'structured' | 'markdown';
+    /** Original custom-scheme URL when the reference came from Markdown. */
+    rawHref?: string;
+}
+
+export type AgentResourceResolver = (
+    ref: AgentResourceLinkReference,
+    context: ResourceResolveContext,
+) => AgentResourceTarget;
+
+const unresolvedAgentResourceResolver: AgentResourceResolver = () => ({ kind: 'none' });
+const AgentResourceResolverContext = createContext<AgentResourceResolver>(unresolvedAgentResourceResolver);
+
+/** Supplies host-specific navigation for reusable chat and Markdown components. */
+export const AgentResourceResolverProvider = AgentResourceResolverContext.Provider;
+
+export function useAgentResourceResolver(): AgentResourceResolver {
+    return useContext(AgentResourceResolverContext);
+}
+
+const RESOURCE_SCHEME_TYPES = {
+    store: 'document',
+    document: 'document',
+    collection: 'collection',
+    interaction: 'interaction',
+    prompt: 'prompt',
+    agent: 'agent',
+    workflow: 'workflow',
+    process: 'process',
+    run: 'interaction_run',
+} as const satisfies Record<string, AgentResourceType>;
+
+/** Converts a supported agent Markdown scheme into the same resource identity used by tool metadata. */
+export function parseAgentResourceHref(rawHref: string): AgentResourceLinkReference | undefined {
+    const colonIndex = rawHref.indexOf(':');
+    if (colonIndex <= 0) return undefined;
+
+    const scheme = rawHref.slice(0, colonIndex);
+    if (!Object.hasOwn(RESOURCE_SCHEME_TYPES, scheme)) return undefined;
+
+    const id = rawHref
+        .slice(colonIndex + 1)
+        .trim()
+        .replace(/^\/+/, '');
+    if (!id) return undefined;
+
+    return {
+        type: RESOURCE_SCHEME_TYPES[scheme as keyof typeof RESOURCE_SCHEME_TYPES],
+        id,
+    };
+}