@vertesia/ui 1.2.0 → 1.4.0-dev.20260615.042549Z

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

@@ -1,87 +1,92 @@
-import { describe, expect, it } from "vitest";
-import { preprocessMathDelimiters } from "./preprocessMathDelimiters";
+import { describe, expect, it } from 'vitest';
+import { preprocessMathDelimiters } from './preprocessMathDelimiters';
 
-describe("preprocessMathDelimiters", () => {
-    it("preserves LaTeX patterns (commands, subscripts, superscripts, braces)", () => {
-        expect(preprocessMathDelimiters("$x = \\frac{-b}{2a}$")).toBe("$x = \\frac{-b}{2a}$");
-        expect(preprocessMathDelimiters("$n^2$")).toBe("$n^2$");
-        expect(preprocessMathDelimiters("$a_{ij}$")).toBe("$a_{ij}$");
+describe('preprocessMathDelimiters', () => {
+    it('preserves LaTeX patterns (commands, subscripts, superscripts, braces)', () => {
+        expect(preprocessMathDelimiters('$x = \\frac{-b}{2a}$')).toBe('$x = \\frac{-b}{2a}$');
+        expect(preprocessMathDelimiters('$n^2$')).toBe('$n^2$');
+        expect(preprocessMathDelimiters('$a_{ij}$')).toBe('$a_{ij}$');
     });
 
-    it("preserves single-letter variables and variable assignments", () => {
-        expect(preprocessMathDelimiters("rate $r$ can be expressed")).toBe("rate $r$ can be expressed");
-        expect(preprocessMathDelimiters("where $r = 0.235$ (growth)")).toBe("where $r = 0.235$ (growth)");
+    it('preserves single-letter variables and variable assignments', () => {
+        expect(preprocessMathDelimiters('rate $r$ can be expressed')).toBe('rate $r$ can be expressed');
+        expect(preprocessMathDelimiters('where $r = 0.235$ (growth)')).toBe('where $r = 0.235$ (growth)');
     });
 
-    it("preserves ion notation (^+ and ^-)", () => {
-        expect(preprocessMathDelimiters("$Ca^+$")).toBe("$Ca^+$");
-        expect(preprocessMathDelimiters("$Cl^-$")).toBe("$Cl^-$");
-        expect(preprocessMathDelimiters("$Ca^{2+}$")).toBe("$Ca^{2+}$");
+    it('preserves ion notation (^+ and ^-)', () => {
+        expect(preprocessMathDelimiters('$Ca^+$')).toBe('$Ca^+$');
+        expect(preprocessMathDelimiters('$Cl^-$')).toBe('$Cl^-$');
+        expect(preprocessMathDelimiters('$Ca^{2+}$')).toBe('$Ca^{2+}$');
     });
 
-    it("preserves display math ($$...$$)", () => {
-        expect(preprocessMathDelimiters("$$E = mc^2$$")).toBe("$$E = mc^2$$");
-        expect(preprocessMathDelimiters("$$\nx = \\frac{-b}{2a}\n$$")).toBe("$$\nx = \\frac{-b}{2a}\n$$");
+    it('preserves display math ($$...$$)', () => {
+        expect(preprocessMathDelimiters('$$E = mc^2$$')).toBe('$$E = mc^2$$');
+        expect(preprocessMathDelimiters('$$\nx = \\frac{-b}{2a}\n$$')).toBe('$$\nx = \\frac{-b}{2a}\n$$');
     });
 
-    it("escapes currency amounts", () => {
-        expect(preprocessMathDelimiters("between $100M and $500M")).toBe("between \\$100M and \\$500M");
-        expect(preprocessMathDelimiters("all $ figures by $500k")).toBe("all \\$ figures by \\$500k");
-        expect(preprocessMathDelimiters("$100K-$500K range")).toBe("\\$100K-\\$500K range");
+    it('escapes currency amounts', () => {
+        expect(preprocessMathDelimiters('between $100M and $500M')).toBe('between \\$100M and \\$500M');
+        expect(preprocessMathDelimiters('all $ figures by $500k')).toBe('all \\$ figures by \\$500k');
+        expect(preprocessMathDelimiters('$100K-$500K range')).toBe('\\$100K-\\$500K range');
     });
 
-    it("preserves uncertain content as fallback", () => {
-        expect(preprocessMathDelimiters("$100 + 200$")).toBe("$100 + 200$");
+    it('preserves uncertain content as fallback', () => {
+        expect(preprocessMathDelimiters('$100 + 200$')).toBe('$100 + 200$');
     });
 
-    it("skips inline code and fenced code blocks", () => {
-        expect(preprocessMathDelimiters("use `$100 and $200` as values")).toBe("use `$100 and $200` as values");
-        const fenced = "costs $100M and $500M\n```\nprice = $200\n```";
-        expect(preprocessMathDelimiters(fenced)).toBe("costs \\$100M and \\$500M\n```\nprice = $200\n```");
+    it('skips inline code and fenced code blocks', () => {
+        expect(preprocessMathDelimiters('use `$100 and $200` as values')).toBe('use `$100 and $200` as values');
+        const fenced = 'costs $100M and $500M\n```\nprice = $200\n```';
+        expect(preprocessMathDelimiters(fenced)).toBe('costs \\$100M and \\$500M\n```\nprice = $200\n```');
     });
 
-    it("no-ops on empty string and strings without $", () => {
-        expect(preprocessMathDelimiters("")).toBe("");
-        expect(preprocessMathDelimiters("no dollars here")).toBe("no dollars here");
+    it('no-ops on empty string and strings without $', () => {
+        expect(preprocessMathDelimiters('')).toBe('');
+        expect(preprocessMathDelimiters('no dollars here')).toBe('no dollars here');
     });
 
-    it("does not double-escape already escaped \\$", () => {
-        expect(preprocessMathDelimiters("costs \\$100")).toBe("costs \\$100");
+    it('does not double-escape already escaped \\$', () => {
+        expect(preprocessMathDelimiters('costs \\$100')).toBe('costs \\$100');
     });
 
-    it("replaces \\$ inside LaTeX spans with \\text{\\textdollar}", () => {
-        expect(preprocessMathDelimiters("where $P = \\$2,847,500$ end"))
-            .toBe("where $P = \\text{\\textdollar}2,847,500$ end");
+    it('replaces \\$ inside LaTeX spans with \\text{\\textdollar}', () => {
+        expect(preprocessMathDelimiters('where $P = \\$2,847,500$ end')).toBe(
+            'where $P = \\text{\\textdollar}2,847,500$ end',
+        );
     });
 
-    it("does not replace \\$ outside LaTeX spans", () => {
-        expect(preprocessMathDelimiters("costs \\$100")).toBe("costs \\$100");
+    it('does not replace \\$ outside LaTeX spans', () => {
+        expect(preprocessMathDelimiters('costs \\$100')).toBe('costs \\$100');
     });
 
-    it("escapes currency $ adjacent to LaTeX pairs", () => {
-        expect(preprocessMathDelimiters("costs $500M. Also $x = \\frac{1}{2}$ works"))
-            .toBe("costs \\$500M. Also $x = \\frac{1}{2}$ works");
+    it('escapes currency $ adjacent to LaTeX pairs', () => {
+        expect(preprocessMathDelimiters('costs $500M. Also $x = \\frac{1}{2}$ works')).toBe(
+            'costs \\$500M. Also $x = \\frac{1}{2}$ works',
+        );
     });
 
-    it("handles currency and LaTeX on separate lines", () => {
-        expect(preprocessMathDelimiters("between $100M and $500M\nwhere $x = \\frac{1}{2}$"))
-            .toBe("between \\$100M and \\$500M\nwhere $x = \\frac{1}{2}$");
+    it('handles currency and LaTeX on separate lines', () => {
+        expect(preprocessMathDelimiters('between $100M and $500M\nwhere $x = \\frac{1}{2}$')).toBe(
+            'between \\$100M and \\$500M\nwhere $x = \\frac{1}{2}$',
+        );
     });
 
-    it("handles mixed currency, LaTeX, and \\$ in a financial report line", () => {
-        const input = "Where $F = \\$567,800$ (fixed costs), $P = \\$89.99$ (price), and $V = \\$0.42$ (variable). This yields $Q_{\\text{BE}} = 6,338$ units.";
+    it('handles mixed currency, LaTeX, and \\$ in a financial report line', () => {
+        const input =
+            'Where $F = \\$567,800$ (fixed costs), $P = \\$89.99$ (price), and $V = \\$0.42$ (variable). This yields $Q_{\\text{BE}} = 6,338$ units.';
         const result = preprocessMathDelimiters(input);
-        expect(result).toContain("$F = \\text{\\textdollar}567,800$");
-        expect(result).toContain("$P = \\text{\\textdollar}89.99$");
-        expect(result).toContain("$V = \\text{\\textdollar}0.42$");
-        expect(result).toContain("$Q_{\\text{BE}} = 6,338$");
+        expect(result).toContain('$F = \\text{\\textdollar}567,800$');
+        expect(result).toContain('$P = \\text{\\textdollar}89.99$');
+        expect(result).toContain('$V = \\text{\\textdollar}0.42$');
+        expect(result).toContain('$Q_{\\text{BE}} = 6,338$');
     });
 
-    it("handles interleaved currency, inline LaTeX, and display math", () => {
-        const input = "The report for $500M shows that (given $sales = x*e^{y}$) we were off by $15M. This is from $$variance = x*v/2*e^(y-y`)$$";
+    it('handles interleaved currency, inline LaTeX, and display math', () => {
+        const input =
+            'The report for $500M shows that (given $sales = x*e^{y}$) we were off by $15M. This is from $$variance = x*v/2*e^(y-y`)$$';
         const result = preprocessMathDelimiters(input);
-        expect(result).toContain("$sales = x*e^{y}$");
-        expect(result).toContain("$$variance = x*v/2*e^(y-y`)$$");
-        expect(result).toContain("\\$500M");
+        expect(result).toContain('$sales = x*e^{y}$');
+        expect(result).toContain('$$variance = x*v/2*e^(y-y`)$$');
+        expect(result).toContain('\\$500M');
     });
 });

package/src/widgets/markdown/preprocessMathDelimiters.ts

@@ -17,30 +17,32 @@
 
 const FENCED_CODE_BLOCK_REGEX = /(^|\n)(`{3,}|~{3,})[^\n]*\n[\s\S]*?\n\2(?=\n|$)/g; // ```...``` or ~~~...~~~
 const INLINE_CODE_REGEX = /`[^`\n]*`/g; // `...`
-const ESCAPED_DOLLAR_REGEX = /\\\$/g;   // \$ inside LaTeX spans
+const ESCAPED_DOLLAR_REGEX = /\\\$/g; // \$ inside LaTeX spans
 
 // LaTeX positive signals
-const RE_BACKSLASH_CMD = /\\[^\s]/;     // \command or \symbol (\frac, \%, \$, etc.)
-const RE_BRACE_GROUP = /[{}]/;          // brace groups
+const RE_BACKSLASH_CMD = /\\[^\s]/; // \command or \symbol (\frac, \%, \$, etc.)
+const RE_BRACE_GROUP = /[{}]/; // brace groups
 const RE_SUB_SUPERSCRIPT = /[_^][\w{]/; // sub/superscript
-const RE_SINGLE_LETTER = /^[a-zA-Z]$/;  // single letter variable ($r$, $x$, $t$)
+const RE_SINGLE_LETTER = /^[a-zA-Z]$/; // single letter variable ($r$, $x$, $t$)
 const RE_VAR_ASSIGNMENT = /^[a-zA-Z]\s*=/; // variable assignment ($r = 0.235$, $n = 4$)
 
 // LaTeX negative signals
-const RE_LEADING_SPACE = /^\s/;         // space after opening $
-const RE_TRAILING_SPACE = /\s$/;        // space before closing $
+const RE_LEADING_SPACE = /^\s/; // space after opening $
+const RE_TRAILING_SPACE = /\s$/; // space before closing $
 const RE_TRAILING_OPERATOR = /[+*/-]$/; // ends with bare operator
-const RE_ION_NOTATION = /\^[+-]$/;      // except ^+ or ^- (ion notation)
+const RE_ION_NOTATION = /\^[+-]$/; // except ^+ or ^- (ion notation)
 
 /**
  * Returns true if content between `$...$` contains LaTeX structural patterns.
  */
 function hasLatexPattern(content: string): boolean {
-    return RE_BACKSLASH_CMD.test(content)
-        || RE_BRACE_GROUP.test(content)
-        || RE_SUB_SUPERSCRIPT.test(content)
-        || RE_SINGLE_LETTER.test(content)
-        || RE_VAR_ASSIGNMENT.test(content);
+    return (
+        RE_BACKSLASH_CMD.test(content) ||
+        RE_BRACE_GROUP.test(content) ||
+        RE_SUB_SUPERSCRIPT.test(content) ||
+        RE_SINGLE_LETTER.test(content) ||
+        RE_VAR_ASSIGNMENT.test(content)
+    );
 }
 
 /**
@@ -59,10 +61,13 @@ function hasCurrencyPattern(content: string): boolean {
 function findSingleDollarPositions(text: string): number[] {
     const positions: number[] = [];
     for (let i = 0; i < text.length; i++) {
-        if (text[i] !== "$") continue;
-        if (i > 0 && text[i - 1] === "\\") continue;                         // skip \$
-        if (i + 1 < text.length && text[i + 1] === "$") { i++; continue; }   // skip $$ (first)
-        if (i > 0 && text[i - 1] === "$" && (i < 2 || text[i - 2] !== "\\")) continue; // skip $$ (second)
+        if (text[i] !== '$') continue;
+        if (i > 0 && text[i - 1] === '\\') continue; // skip \$
+        if (i + 1 < text.length && text[i + 1] === '$') {
+            i++;
+            continue;
+        } // skip $$ (first)
+        if (i > 0 && text[i - 1] === '$' && (i < 2 || text[i - 2] !== '\\')) continue; // skip $$ (second)
         positions.push(i);
     }
     return positions;
@@ -74,7 +79,7 @@ function findSingleDollarPositions(text: string): number[] {
  */
 function inlineMathContent(text: string, openPos: number, closePos: number): string | null {
     const content = text.slice(openPos + 1, closePos);
-    if (content.length === 0 || content.includes("\n")) return null;
+    if (content.length === 0 || content.includes('\n')) return null;
     return content;
 }
 
@@ -86,8 +91,8 @@ function processTextSegment(text: string): string {
     const positions = findSingleDollarPositions(text);
     if (positions.length < 2) return text;
 
-    const committed = new Set<number>();     // position indices that are paired
-    const toEscape = new Set<number>();      // character offsets in text to escape
+    const committed = new Set<number>(); // position indices that are paired
+    const toEscape = new Set<number>(); // character offsets in text to escape
 
     // Pre-compute content for each adjacent pair (avoids redundant slicing in Pass 1 & 2)
     const adjacentContent: (string | null)[] = new Array(positions.length - 1);
@@ -110,7 +115,10 @@ function processTextSegment(text: string): string {
     // Pass 2: pair remaining positions left-to-right
     let idx = 0;
     while (idx < positions.length) {
-        if (committed.has(idx)) { idx++; continue; }
+        if (committed.has(idx)) {
+            idx++;
+            continue;
+        }
 
         // Find next uncommitted position
         let next = idx + 1;
@@ -165,14 +173,14 @@ function processTextSegment(text: string): string {
 
         if (escPos < spanOpen) {
             if (escPos > segStart) parts.push(text.slice(segStart, escPos));
-            parts.push("\\$");
+            parts.push('\\$');
             segStart = escPos + 1;
             escIdx++;
         } else {
             const [open, close] = latexSpans[spanIdx];
             if (open > segStart) parts.push(text.slice(segStart, open));
             const spanContent = text.slice(open, close + 1);
-            parts.push(spanContent.replace(ESCAPED_DOLLAR_REGEX, "\\text{\\textdollar}"));
+            parts.push(spanContent.replace(ESCAPED_DOLLAR_REGEX, '\\text{\\textdollar}'));
             segStart = close + 1;
             while (escIdx < escapePositions.length && escapePositions[escIdx] <= close) escIdx++;
             spanIdx++;
@@ -180,7 +188,7 @@ function processTextSegment(text: string): string {
     }
 
     if (segStart < text.length) parts.push(text.slice(segStart));
-    return parts.join("");
+    return parts.join('');
 }
 
 /**
@@ -189,17 +197,15 @@ function processTextSegment(text: string): string {
 function processSkippingInlineCode(text: string): string {
     const parts: string[] = [];
     let lastIndex = 0;
-    let match: RegExpExecArray | null;
 
-    INLINE_CODE_REGEX.lastIndex = 0;
-    while ((match = INLINE_CODE_REGEX.exec(text)) !== null) {
+    for (const match of text.matchAll(INLINE_CODE_REGEX)) {
         parts.push(processTextSegment(text.slice(lastIndex, match.index)));
         parts.push(match[0]);
         lastIndex = match.index + match[0].length;
     }
 
     parts.push(processTextSegment(text.slice(lastIndex)));
-    return parts.join("");
+    return parts.join('');
 }
 
 /**
@@ -209,21 +215,19 @@ function processSkippingInlineCode(text: string): string {
  * Skips fenced code blocks and inline code spans.
  */
 export function preprocessMathDelimiters(markdown: string): string {
-    if (!markdown || !markdown.includes("$")) {
+    if (!markdown?.includes('$')) {
         return markdown;
     }
 
     const parts: string[] = [];
     let lastIndex = 0;
-    let match: RegExpExecArray | null;
 
-    FENCED_CODE_BLOCK_REGEX.lastIndex = 0;
-    while ((match = FENCED_CODE_BLOCK_REGEX.exec(markdown)) !== null) {
+    for (const match of markdown.matchAll(FENCED_CODE_BLOCK_REGEX)) {
         parts.push(processSkippingInlineCode(markdown.slice(lastIndex, match.index)));
         parts.push(match[0]);
         lastIndex = match.index + match[0].length;
     }
 
     parts.push(processSkippingInlineCode(markdown.slice(lastIndex)));
-    return parts.join("");
+    return parts.join('');
 }

package/src/widgets/markdown/remarkDirectiveHandler.ts

@@ -8,7 +8,9 @@
  *   :::note / :::warning / :::tip / :::caution / :::important → callout <div>s
  *   :::name             → <div class="md-name"> (generic fallback)
  */
-import { visit, type VisitorResult } from 'unist-util-visit';
+import { type VisitorResult, visit } from 'unist-util-visit';
+
+type RemarkTree = Parameters<typeof visit>[0];
 
 // Callout types mapped to CSS modifier classes (semantic design system)
 const CALLOUT_TYPES: Record<string, string> = {
@@ -39,19 +41,17 @@ interface DirectiveNode {
 }
 
 export function remarkDirectiveHandler() {
-     
-    return (tree: any) => {
+    return (tree: RemarkTree) => {
         visit(tree, (node): VisitorResult => {
-            if (
-                node.type !== 'containerDirective' &&
-                node.type !== 'leafDirective' &&
-                node.type !== 'textDirective'
-            ) {
+            if (node.type !== 'containerDirective' && node.type !== 'leafDirective' && node.type !== 'textDirective') {
                 return;
             }
 
             const d = node as unknown as DirectiveNode;
-            const data = d.data || (d.data = {});
+            if (!d.data) {
+                d.data = {};
+            }
+            const data = d.data;
             const attrs = d.attributes || {};
             const name = d.name;
 
@@ -107,9 +107,7 @@ export function remarkDirectiveHandler() {
             data.hName = 'div';
             data.hProperties = {
                 className: `md-${name}`,
-                ...Object.fromEntries(
-                    Object.entries(attrs).filter(([k]) => k !== 'class'),
-                ),
+                ...Object.fromEntries(Object.entries(attrs).filter(([k]) => k !== 'class')),
             };
             if (attrs.class) {
                 data.hProperties.className += ` ${attrs.class}`;

package/src/widgets/markdown/useArtifactContent.ts

@@ -4,12 +4,9 @@
  * Used by expand:* code blocks to fetch and render artifact content inline.
  */
 
-import { useState, useEffect, useCallback, useRef } from 'react';
 import { useUserSession } from '@vertesia/ui/session';
-import {
-    useArtifactUrlCache,
-    getArtifactCacheKey,
-} from '../../features/agent/chat/useArtifactUrlCache';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { getArtifactCacheKey, useArtifactUrlCache } from '../../features/agent/chat/useArtifactUrlCache';
 
 export interface ArtifactContentState<T = unknown> {
     /** The fetched content, parsed if JSON */
@@ -101,8 +98,6 @@ export function useArtifactContent<T = unknown>({
         contentType: undefined,
     });
 
-    const [retryCount, setRetryCount] = useState(0);
-
     const fetchContent = useCallback(async () => {
         if (!runId) {
             setState({
@@ -126,7 +121,7 @@ export function useArtifactContent<T = unknown>({
             return;
         }
 
-        setState(prev => ({ ...prev, isLoading: true, error: undefined }));
+        setState((prev) => ({ ...prev, isLoading: true, error: undefined }));
 
         const currentClient = clientRef.current;
         const currentUrlCache = urlCacheRef.current;
@@ -139,19 +134,11 @@ export function useArtifactContent<T = unknown>({
 
             if (currentUrlCache) {
                 signedUrl = await currentUrlCache.getOrFetch(cacheKey, async () => {
-                    const result = await currentClient.files.getArtifactDownloadUrl(
-                        runId,
-                        path,
-                        'inline'
-                    );
+                    const result = await currentClient.files.getArtifactDownloadUrl(runId, path, 'inline');
                     return result.url;
                 });
             } else {
-                const result = await currentClient.files.getArtifactDownloadUrl(
-                    runId,
-                    path,
-                    'inline'
-                );
+                const result = await currentClient.files.getArtifactDownloadUrl(runId, path, 'inline');
                 signedUrl = result.url;
             }
 
@@ -209,8 +196,8 @@ export function useArtifactContent<T = unknown>({
     }, [runId, path, parseJson]);
 
     useEffect(() => {
-        fetchContent();
-    }, [fetchContent, retryCount]);
+        void fetchContent();
+    }, [fetchContent]);
 
     const retry = useCallback(() => {
         setState({
@@ -220,8 +207,8 @@ export function useArtifactContent<T = unknown>({
             error: undefined,
             contentType: undefined,
         });
-        setRetryCount(c => c + 1);
-    }, []);
+        void fetchContent();
+    }, [fetchContent]);
 
     return {
         data: state.data,

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

@@ -1,5 +1,5 @@
-import { describe, it, expect } from 'vitest';
-import { parseUrlScheme, mapSchemeToRoute } from './useResolvedUrl';
+import { describe, expect, it } from 'vitest';
+import { mapSchemeToRoute, parseUrlScheme } from './useResolvedUrl';
 
 describe('parseUrlScheme', () => {
     it('should parse artifact: URLs', () => {
@@ -32,6 +32,29 @@ describe('parseUrlScheme', () => {
         expect(result.path).toBe('my-collection');
     });
 
+    it('should strip the // authority from collection:// URLs', () => {
+        const result = parseUrlScheme('collection://my-collection');
+        expect(result.scheme).toBe('collection');
+        expect(result.path).toBe('my-collection');
+    });
+
+    it('should strip the // authority from store:// URLs', () => {
+        const result = parseUrlScheme('store://abc123');
+        expect(result.scheme).toBe('store');
+        expect(result.path).toBe('abc123');
+    });
+
+    it('should parse document: URLs without the // authority', () => {
+        const result = parseUrlScheme('document:doc-id-123');
+        expect(result.scheme).toBe('document');
+        expect(result.path).toBe('doc-id-123');
+    });
+
+    it('should map collection:// through to a single-slash route', () => {
+        const { scheme, path } = parseUrlScheme('collection://my-collection');
+        expect(mapSchemeToRoute(scheme, path)).toBe('/store/collections/my-collection');
+    });
+
     it('should parse standard URLs', () => {
         const result = parseUrlScheme('https://example.com/page');
         expect(result.scheme).toBe('standard');

package/src/widgets/markdown/useResolvedUrl.ts

@@ -1,18 +1,13 @@
-import { useState, useEffect, useCallback, useRef } from 'react';
 import { useUserSession } from '@vertesia/ui/session';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import {
-    useArtifactUrlCache,
     getArtifactCacheKey,
     getFileCacheKey,
+    isProjectFilePath,
+    useArtifactUrlCache,
 } from '../../features/agent/chat/useArtifactUrlCache';
 
-export type UrlScheme =
-    | 'artifact'
-    | 'image'
-    | 'store'
-    | 'document'
-    | 'collection'
-    | 'standard';
+export type UrlScheme = 'artifact' | 'image' | 'store' | 'document' | 'collection' | 'standard';
 
 export interface ResolvedUrlState {
     /** The resolved URL, or undefined if not yet resolved */
@@ -36,6 +31,14 @@ export interface UseResolvedUrlOptions {
     disposition?: 'inline' | 'attachment';
 }
 
+/**
+ * Strip an optional `//` authority (and stray leading slashes) after a scheme colon so
+ * `scheme://path` and `scheme:path` parse identically.
+ */
+function stripSchemePath(raw: string): string {
+    return raw.trim().replace(/^\/+/, '');
+}
+
 /**
  * Parses a URL and returns its scheme and path
  */
@@ -47,13 +50,13 @@ export function parseUrlScheme(rawUrl: string): { scheme: UrlScheme; path: strin
         return { scheme: 'image', path: rawUrl.slice(6).trim() };
     }
     if (rawUrl.startsWith('store:')) {
-        return { scheme: 'store', path: rawUrl.slice(6).trim() };
+        return { scheme: 'store', path: stripSchemePath(rawUrl.slice(6)) };
     }
-    if (rawUrl.startsWith('document://')) {
-        return { scheme: 'document', path: rawUrl.slice(11).trim() };
+    if (rawUrl.startsWith('document:')) {
+        return { scheme: 'document', path: stripSchemePath(rawUrl.slice(9)) };
     }
     if (rawUrl.startsWith('collection:')) {
-        return { scheme: 'collection', path: rawUrl.slice(11).trim() };
+        return { scheme: 'collection', path: stripSchemePath(rawUrl.slice(11)) };
     }
     return { scheme: 'standard', path: rawUrl };
 }
@@ -113,7 +116,7 @@ export function useResolvedUrl({
         // For artifact/image schemes, check cache first
         if (urlCache && (scheme === 'artifact' || scheme === 'image')) {
             let cacheKey: string;
-            if (scheme === 'artifact' && artifactRunId && !path.startsWith('agents/')) {
+            if (scheme === 'artifact' && artifactRunId && !isProjectFilePath(path)) {
                 cacheKey = getArtifactCacheKey(artifactRunId, path, disposition);
             } else {
                 cacheKey = getFileCacheKey(path);
@@ -128,8 +131,6 @@ export function useResolvedUrl({
         return { url: undefined, isLoading: true, error: undefined };
     });
 
-    const [retryCount, setRetryCount] = useState(0);
-
     const fetchUrl = useCallback(async () => {
         // Skip if already resolved or standard URL
         if (mappedRoute || scheme === 'standard') {
@@ -142,7 +143,7 @@ export function useResolvedUrl({
             return;
         }
 
-        setState(prev => ({ ...prev, isLoading: true, error: undefined }));
+        setState((prev) => ({ ...prev, isLoading: true, error: undefined }));
 
         const currentClient = clientRef.current;
         const currentUrlCache = urlCacheRef.current;
@@ -151,14 +152,14 @@ export function useResolvedUrl({
             let url: string;
 
             if (scheme === 'artifact') {
-                if (artifactRunId && !path.startsWith('agents/')) {
+                if (artifactRunId && !isProjectFilePath(path)) {
                     const cacheKey = getArtifactCacheKey(artifactRunId, path, disposition);
                     if (currentUrlCache) {
                         url = await currentUrlCache.getOrFetch(cacheKey, async () => {
                             const result = await currentClient.files.getArtifactDownloadUrl(
                                 artifactRunId,
                                 path,
-                                disposition
+                                disposition,
                             );
                             return result.url;
                         });
@@ -166,7 +167,7 @@ export function useResolvedUrl({
                         const result = await currentClient.files.getArtifactDownloadUrl(
                             artifactRunId,
                             path,
-                            disposition
+                            disposition,
                         );
                         url = result.url;
                     }
@@ -217,18 +218,18 @@ export function useResolvedUrl({
         };
 
         if (!cancelled) {
-            doFetch();
+            void doFetch();
         }
 
         return () => {
             cancelled = true;
         };
-    }, [fetchUrl, retryCount, state.url, state.error]);
+    }, [fetchUrl, state.url, state.error]);
 
     const retry = useCallback(() => {
         setState({ url: undefined, isLoading: true, error: undefined });
-        setRetryCount(c => c + 1);
-    }, []);
+        void fetchUrl();
+    }, [fetchUrl]);
 
     return {
         url: state.url,