@atmo-dev/kit 0.7.2 → 0.9.0

package/dist/richtext/facets.js

@@ -0,0 +1,113 @@
+import { isDid } from '@atcute/lexicons/syntax';
+import { safeWebUrl } from './document.js';
+import { detectTokens } from './detect.js';
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function target(feature) {
+    if (!record(feature))
+        return undefined;
+    switch (feature.$type) {
+        case 'app.bsky.richtext.facet#mention':
+            return typeof feature.did === 'string' && isDid(feature.did)
+                ? { type: 'mention', actor: feature.did }
+                : undefined;
+        case 'app.bsky.richtext.facet#link': {
+            const url = safeWebUrl(feature.uri);
+            return url ? { type: 'link', url } : undefined;
+        }
+        case 'app.bsky.richtext.facet#tag':
+            return typeof feature.tag === 'string' && feature.tag
+                ? { type: 'tag', tag: feature.tag }
+                : undefined;
+    }
+}
+/** UTF-8 byte offset -> UTF-16 offset, for code point boundaries only. */
+function byteOffsets(text) {
+    const offsets = new Map([[0, 0]]);
+    let bytes = 0;
+    for (let index = 0; index < text.length;) {
+        const code = text.codePointAt(index);
+        // Lone surrogates encode as U+FFFD (3 bytes).
+        bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+        index += code > 0xffff ? 2 : 1;
+        offsets.set(bytes, index);
+    }
+    return offsets;
+}
+/**
+ * Untrusted record facets -> sorted, non-overlapping ranges with safe destinations.
+ * Malformed facets, unsupported features and ranges inside a code point are ignored.
+ */
+export function resolveFacets(text, facets) {
+    if (!Array.isArray(facets) || !facets.length)
+        return [];
+    const offsets = byteOffsets(text);
+    const ranges = [];
+    for (const facet of facets) {
+        if (!record(facet) || !record(facet.index) || !Array.isArray(facet.features))
+            continue;
+        const { byteStart, byteEnd } = facet.index;
+        if (typeof byteStart !== 'number' || typeof byteEnd !== 'number')
+            continue;
+        const start = offsets.get(byteStart);
+        const end = offsets.get(byteEnd);
+        if (start === undefined || end === undefined || end <= start)
+            continue;
+        const resolved = facet.features.map(target).find(Boolean);
+        if (resolved)
+            ranges.push({ start, end, target: resolved });
+    }
+    ranges.sort((a, b) => a.start - b.start);
+    let cursor = 0;
+    return ranges.filter((range) => {
+        if (range.start < cursor)
+            return false;
+        cursor = range.end;
+        return true;
+    });
+}
+export function hasFacets(facets) {
+    return Array.isArray(facets) && facets.length > 0;
+}
+function facetNode(target, text) {
+    return target.type === 'link'
+        ? { type: 'link', url: target.url, children: [{ type: 'text', value: text }] }
+        : target.type === 'mention'
+            ? { type: 'mention', actor: target.actor, text }
+            : { type: 'tag', tag: target.tag, text };
+}
+/** Split text at ranges given in offsets of `text` itself. */
+export function applyRanges(text, ranges) {
+    const result = [];
+    let cursor = 0;
+    for (const { start, end, target } of ranges) {
+        if (start > cursor)
+            result.push({ type: 'text', value: text.slice(cursor, start) });
+        result.push(facetNode(target, text.slice(start, end)));
+        cursor = end;
+    }
+    if (cursor < text.length || !result.length)
+        result.push({ type: 'text', value: text.slice(cursor) });
+    return result;
+}
+/** Plain-text URL, mention and hashtag detection for text without facets. */
+export function detectLinks(text) {
+    const result = [];
+    for (const token of detectTokens(text)) {
+        const url = token.type === 'autolink' ? safeWebUrl(token.url) : undefined;
+        const node = url
+            ? { type: 'link', url, children: [{ type: 'text', value: token.raw }] }
+            : token.type === 'mention'
+                ? { type: 'mention', actor: token.handle, text: token.raw }
+                : token.type === 'topic'
+                    ? { type: 'tag', tag: token.name, text: token.raw }
+                    : { type: 'text', value: token.raw };
+        const previous = result.at(-1);
+        if (node.type === 'text' && previous?.type === 'text')
+            previous.value += node.value;
+        else
+            result.push(node);
+    }
+    return result;
+}

package/dist/richtext/markdown.d.ts

@@ -0,0 +1,10 @@
+import { type RichTextDocument } from './document.js';
+import { type PlainTextOptions } from './plain.js';
+/** Whether Markdown parsing could be slow; checked in linear time. */
+export declare function exceedsMarkdownLimits(text: string): boolean;
+/**
+ * CommonMark plus ~~strikethrough~~, with facets applied to the parsed text. Raw HTML is shown
+ * literally, images become links and only HTTP(S) destinations are kept. Text that exceeds
+ * the parser's limits is returned as a plain-text document.
+ */
+export declare function parseMarkdown(text: string, options?: PlainTextOptions): RichTextDocument;

package/dist/richtext/markdown.js

@@ -0,0 +1,236 @@
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { gfmStrikethrough } from 'micromark-extension-gfm-strikethrough';
+import { gfmStrikethroughFromMarkdown } from 'mdast-util-gfm-strikethrough';
+import { safeWebUrl } from './document.js';
+import { applyRanges, detectLinks, hasFacets, resolveFacets } from './facets.js';
+import { parsePlainText } from './plain.js';
+// Deeper nesting is shown as literal source instead of recursing further.
+const MAX_DEPTH = 16;
+// micromark slows down quadratically with nested containers (thousands of `>` or `- ` on a
+// line take seconds) and grows with delimiter runs, so long, delimiter-heavy or deeply nested
+// text is rendered as plain text instead. Real descriptions stay far below these limits.
+const MAX_LENGTH = 10_000;
+const MAX_DELIMITERS = 1_000;
+const MAX_LINE_CONTAINERS = 8;
+const MAX_LIST_INDENT = 32;
+const CONTAINER_RE = /[ \t]*(?:>|(?:[-*+]|\d{1,9}[.)])(?=[ \t]|$))/y;
+const LIST_RE = /[ \t]*(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)/y;
+/** Whether Markdown parsing could be slow; checked in linear time. */
+export function exceedsMarkdownLimits(text) {
+    if (text.length > MAX_LENGTH)
+        return true;
+    let delimiters = 0;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if ((char === '*' || char === '_' || char === '~' || char === '[') &&
+            ++delimiters > MAX_DELIMITERS)
+            return true;
+    }
+    for (const line of text.split('\n')) {
+        let containers = 0;
+        CONTAINER_RE.lastIndex = 0;
+        while (CONTAINER_RE.exec(line)) {
+            if (++containers > MAX_LINE_CONTAINERS)
+                return true;
+        }
+        const indent = /^[ \t]*/.exec(line)[0].replaceAll('\t', '    ').length;
+        LIST_RE.lastIndex = 0;
+        if (indent > MAX_LIST_INDENT && LIST_RE.test(line))
+            return true;
+    }
+    return false;
+}
+function literal(node, context) {
+    const start = node.position?.start.offset;
+    const end = node.position?.end.offset;
+    return start === undefined || end === undefined ? '' : context.source.slice(start, end);
+}
+/** Single newlines are line breaks, as in plain-text descriptions. */
+function withBreaks(nodes) {
+    return nodes.flatMap((node) => node.type === 'text' && node.value.includes('\n')
+        ? node.value
+            .split('\n')
+            .flatMap((value, index) => [
+            ...(index ? [{ type: 'break' }] : []),
+            ...(value ? [{ type: 'text', value }] : [])
+        ])
+        : [node]);
+}
+/**
+ * Facets index the Markdown source; a text node's value can differ from its source because
+ * of escapes, entities or stripped indentation. Facets apply only where the facet's source
+ * text appears unchanged within a single text node.
+ */
+function facetText(node, context) {
+    const start = node.position?.start.offset;
+    const end = node.position?.end.offset;
+    const value = node.value;
+    if (start === undefined || end === undefined)
+        return [{ type: 'text', value }];
+    const inside = context.ranges.filter((range) => range.start >= start && range.end <= end);
+    if (!inside.length)
+        return [{ type: 'text', value }];
+    const source = context.source.slice(start, end);
+    const map = [];
+    let cursor = 0;
+    for (let index = 0; index < source.length; index++) {
+        if (cursor < value.length && source[index] === value[cursor])
+            map[index] = cursor++;
+    }
+    if (cursor !== value.length)
+        return [{ type: 'text', value }];
+    const local = [];
+    for (const range of inside) {
+        const from = map[range.start - start];
+        const to = map[range.end - 1 - start];
+        if (from === undefined || to === undefined)
+            continue;
+        if (value.slice(from, to + 1) !== context.source.slice(range.start, range.end))
+            continue;
+        local.push({ start: from, end: to + 1, target: range.target });
+    }
+    return applyRanges(value, local);
+}
+function inline(nodes, context, depth, inLink = false) {
+    const result = [];
+    for (const node of nodes) {
+        if (depth > MAX_DEPTH && node.type !== 'text') {
+            result.push({ type: 'text', value: literal(node, context) });
+            continue;
+        }
+        switch (node.type) {
+            case 'text':
+                result.push(...(inLink
+                    ? [{ type: 'text', value: node.value }]
+                    : context.detect
+                        ? detectLinks(node.value)
+                        : facetText(node, context)));
+                break;
+            case 'emphasis':
+            case 'strong':
+            case 'delete':
+                result.push({
+                    type: node.type,
+                    children: inline(node.children, context, depth + 1, inLink)
+                });
+                break;
+            case 'inlineCode':
+                result.push({ type: 'code', value: node.value });
+                break;
+            case 'break':
+                result.push({ type: 'break' });
+                break;
+            case 'link':
+            case 'linkReference': {
+                const url = safeWebUrl(node.type === 'link' ? node.url : context.definitions.get(node.identifier)?.url);
+                const children = inline(node.children, context, depth + 1, true);
+                if (url && !inLink)
+                    result.push({ type: 'link', url, children });
+                else
+                    result.push(...children);
+                break;
+            }
+            case 'image':
+            case 'imageReference': {
+                // Images are never loaded; a safe image becomes a link labeled by its alt text.
+                const url = safeWebUrl(node.type === 'image' ? node.url : context.definitions.get(node.identifier)?.url);
+                const alt = node.alt ?? '';
+                if (url && !inLink)
+                    result.push({ type: 'link', url, children: [{ type: 'text', value: alt || url }] });
+                else if (alt)
+                    result.push({ type: 'text', value: alt });
+                break;
+            }
+            default:
+                // Raw HTML and anything unsupported is shown as written.
+                result.push({
+                    type: 'text',
+                    value: node.type === 'html' ? node.value : literal(node, context)
+                });
+        }
+    }
+    return withBreaks(result);
+}
+function blocks(nodes, context, depth) {
+    const result = [];
+    for (const node of nodes) {
+        if (depth > MAX_DEPTH) {
+            result.push({
+                type: 'paragraph',
+                children: withBreaks([{ type: 'text', value: literal(node, context) }])
+            });
+            continue;
+        }
+        switch (node.type) {
+            case 'paragraph':
+                result.push({ type: 'paragraph', children: inline(node.children, context, depth) });
+                break;
+            case 'heading':
+                result.push({
+                    type: 'heading',
+                    depth: node.depth,
+                    children: inline(node.children, context, depth)
+                });
+                break;
+            case 'blockquote':
+                result.push({ type: 'blockquote', children: blocks(node.children, context, depth + 1) });
+                break;
+            case 'list':
+                result.push({
+                    type: 'list',
+                    ordered: !!node.ordered,
+                    ...(node.ordered && typeof node.start === 'number' ? { start: node.start } : {}),
+                    items: node.children.map((item) => blocks(item.children, context, depth + 1))
+                });
+                break;
+            case 'code':
+                result.push({ type: 'codeBlock', value: node.value });
+                break;
+            case 'thematicBreak':
+                result.push({ type: 'thematicBreak' });
+                break;
+            case 'definition':
+                break;
+            default:
+                result.push({
+                    type: 'paragraph',
+                    children: withBreaks([
+                        { type: 'text', value: node.type === 'html' ? node.value : literal(node, context) }
+                    ])
+                });
+        }
+    }
+    return result;
+}
+function collectDefinitions(node, definitions, depth = 0) {
+    if (node.type === 'definition') {
+        if (!definitions.has(node.identifier))
+            definitions.set(node.identifier, node);
+    }
+    else if ('children' in node && depth <= MAX_DEPTH + 1) {
+        for (const child of node.children)
+            collectDefinitions(child, definitions, depth + 1);
+    }
+}
+/**
+ * CommonMark plus ~~strikethrough~~, with facets applied to the parsed text. Raw HTML is shown
+ * literally, images become links and only HTTP(S) destinations are kept. Text that exceeds
+ * the parser's limits is returned as a plain-text document.
+ */
+export function parseMarkdown(text, options = {}) {
+    if (exceedsMarkdownLimits(text))
+        return parsePlainText(text, options);
+    const tree = fromMarkdown(text, {
+        extensions: [gfmStrikethrough({ singleTilde: false })],
+        mdastExtensions: [gfmStrikethroughFromMarkdown()]
+    });
+    const definitions = new Map();
+    collectDefinitions(tree, definitions);
+    const context = {
+        source: text,
+        ranges: resolveFacets(text, options.facets),
+        detect: !hasFacets(options.facets) && !!options.detectLinks,
+        definitions
+    };
+    return { version: 1, markdown: true, children: blocks(tree.children, context, 0) };
+}

package/dist/richtext/plain.d.ts

@@ -0,0 +1,9 @@
+import type { RichTextDocument } from './document.js';
+export type PlainTextOptions = {
+    /** Public record facets; validated at runtime. */
+    facets?: unknown;
+    /** Detect plain-text links, mentions and hashtags only when there are no facets. */
+    detectLinks?: boolean;
+};
+/** Plain text with facet links. Small enough to run in the browser. */
+export declare function parsePlainText(text: string, options?: PlainTextOptions): RichTextDocument;

package/dist/richtext/plain.js

@@ -0,0 +1,8 @@
+import { applyRanges, detectLinks, hasFacets, resolveFacets } from './facets.js';
+/** Plain text with facet links. Small enough to run in the browser. */
+export function parsePlainText(text, options = {}) {
+    const children = !hasFacets(options.facets) && options.detectLinks
+        ? detectLinks(text)
+        : applyRanges(text, resolveFacets(text, options.facets));
+    return { version: 1, markdown: false, children: [{ type: 'paragraph', children }] };
+}

package/dist/richtext.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Rich text parsing without Svelte or a DOM. Parse on the server and pass the document to
+ * `RichText` so the Markdown parser stays out of client bundles.
+ */
+import { parseMarkdown } from './richtext/markdown.js';
+import { parsePlainText, type PlainTextOptions } from './richtext/plain.js';
+import type { RichTextDocument } from './richtext/document.js';
+export type RichTextParseOptions = PlainTextOptions & {
+    /** Parse CommonMark and ~~strikethrough~~. Otherwise, text is plain and whitespace is kept. */
+    markdown?: boolean;
+};
+export declare function parseRichText(text: string, options?: RichTextParseOptions): RichTextDocument;
+export { parseMarkdown, parsePlainText };
+export { richTextToPlainText, safeWebUrl } from './richtext/document.js';
+export type { RichTextDocument, RichTextBlock, RichTextInline, RichTextLinkOptions } from './richtext/document.js';
+export type { PlainTextOptions };
+export { detectTokens, type DetectedToken } from './richtext/detect.js';

package/dist/richtext.js

@@ -0,0 +1,12 @@
+/**
+ * Rich text parsing without Svelte or a DOM. Parse on the server and pass the document to
+ * `RichText` so the Markdown parser stays out of client bundles.
+ */
+import { parseMarkdown } from './richtext/markdown.js';
+import { parsePlainText } from './richtext/plain.js';
+export function parseRichText(text, options = {}) {
+    return options.markdown ? parseMarkdown(text, options) : parsePlainText(text, options);
+}
+export { parseMarkdown, parsePlainText };
+export { richTextToPlainText, safeWebUrl } from './richtext/document.js';
+export { detectTokens } from './richtext/detect.js';

package/dist/social/external-embeds.js

@@ -1,4 +1,4 @@
-import { safeWebUrl } from './richtext.js';
+import { safeHttpUrl as safeWebUrl } from '../urls.js';
 function youtubeStart(value) {
     if (!value)
         return 0;

package/dist/social/profile.js

@@ -1,5 +1,5 @@
-import { tokenize } from '@atcute/bluesky-richtext-parser';
-import { safeWebUrl } from './richtext.js';
+import { detectTokens } from '../richtext/detect.js';
+import { safeHttpUrl as safeWebUrl } from '../urls.js';
 import { socialHashtagUrl, socialProfileUrl } from './urls.js';
 /** Only web URLs; never accept executable schemes or disguised credentials. */
 export function safeProfileUrl(value) {
@@ -13,7 +13,7 @@ export function safeProfileUrl(value) {
     return url.username || url.password ? undefined : href;
 }
 export function profileDescriptionSegments(text, options = {}) {
-    return Array.from(tokenize(text), (token) => ({
+    return Array.from(detectTokens(text), (token) => ({
         text: token.raw,
         href: token.type === 'autolink'
             ? safeProfileUrl(token.url)

package/dist/social/richtext.d.ts

@@ -1,5 +1,6 @@
 import type { JSONContent } from '@tiptap/core';
-import type { PreferredSocialClient } from './preferred-client.js';
+import type { RichTextLinkOptions } from '../richtext/document.js';
+export { safeWebUrl } from '../richtext/document.js';
 export type Facet = {
     index: {
         byteStart: number;
@@ -12,24 +13,20 @@ export type Facet = {
         tag?: string;
     }[];
 };
-export declare function safeWebUrl(url: unknown): string | undefined;
 export declare function textToDoc(text: string): JSONContent;
 /** Serialize mention nodes first, then detect links/tags using UTF-8 byte offsets. */
 export declare function editorJsonToBlueskyPost(doc: JSONContent): {
     text: string;
     facets: Facet[];
 };
-export type RichTextOptions = {
-    socialClient?: PreferredSocialClient | null;
-    /** App-owned mention destination; defaults to the selected social client. */
-    mentionUrl?: (identifier: string) => string;
+/** @deprecated Use `RichTextLinkOptions` with `detectLinks` on `RichText` or `parseRichText`. */
+export type RichTextOptions = RichTextLinkOptions & {
     /** Detect plain-text links, mentions and hashtags only when there are no facets. */
     detectLinks?: boolean;
 };
+/** @deprecated `RichText` now renders a `RichTextDocument`. */
 export type RichTextSegment = {
     text: string;
     href?: string;
 };
-/** Plain text and validated links, never HTML or Markdown. Invalid facets leave text intact. */
-export declare function richTextSegments(text: string, facets?: unknown, options?: RichTextOptions): RichTextSegment[];
 export declare function graphemeLength(text: string): number;

package/dist/social/richtext.js

@@ -1,19 +1,5 @@
-import { tokenize } from '@atcute/bluesky-richtext-parser';
-import { isDid } from '@atcute/lexicons/syntax';
-import { socialHashtagUrl, socialProfileUrl } from './urls.js';
-export function safeWebUrl(url) {
-    if (typeof url !== 'string' || !url)
-        return undefined;
-    try {
-        const parsed = new URL(url);
-        return ['https:', 'http:'].includes(parsed.protocol) && !parsed.username && !parsed.password
-            ? parsed.href
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
+import { detectTokens } from '../richtext/detect.js';
+export { safeWebUrl } from '../richtext/document.js';
 export function textToDoc(text) {
     return {
         type: 'doc',
@@ -52,7 +38,7 @@ export function editorJsonToBlueskyPost(doc) {
     });
     const facets = [...mentions];
     let byteStart = 0;
-    for (const token of tokenize(text)) {
+    for (const token of detectTokens(text)) {
         const byteEnd = byteStart + bytes(token.raw);
         if (!mentions.some((m) => byteStart < m.index.byteEnd && byteEnd > m.index.byteStart)) {
             if (token.type === 'autolink')
@@ -70,83 +56,6 @@ export function editorJsonToBlueskyPost(doc) {
     }
     return { text, facets: facets.sort((a, b) => a.index.byteStart - b.index.byteStart) };
 }
-function record(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-/** Only app-relative paths or HTTP(S), including for app-owned mention callbacks. */
-function safeMentionUrl(identifier, options) {
-    const href = options.mentionUrl?.(identifier) ?? socialProfileUrl(identifier, options.socialClient);
-    if (typeof href !== 'string' ||
-        Array.from(href).some((char) => char === '\\' || char.charCodeAt(0) <= 0x20 || char.charCodeAt(0) === 0x7f))
-        return undefined;
-    if (href.startsWith('/') && !href.startsWith('//'))
-        return href;
-    return safeWebUrl(href);
-}
-function featureUrl(feature, options) {
-    if (!record(feature))
-        return undefined;
-    switch (feature.$type) {
-        case 'app.bsky.richtext.facet#mention':
-            return typeof feature.did === 'string' && isDid(feature.did)
-                ? safeMentionUrl(feature.did, options)
-                : undefined;
-        case 'app.bsky.richtext.facet#link':
-            return safeWebUrl(feature.uri);
-        case 'app.bsky.richtext.facet#tag':
-            return typeof feature.tag === 'string' && feature.tag && feature.tag.isWellFormed()
-                ? socialHashtagUrl(feature.tag, options.socialClient)
-                : undefined;
-    }
-}
-/** Plain text and validated links, never HTML or Markdown. Invalid facets leave text intact. */
-export function richTextSegments(text, facets = [], options = {}) {
-    if ((!Array.isArray(facets) || !facets.length) && options.detectLinks) {
-        return Array.from(tokenize(text), (token) => ({
-            text: token.raw,
-            href: token.type === 'autolink'
-                ? safeWebUrl(token.url)
-                : token.type === 'mention'
-                    ? safeMentionUrl(token.handle, options)
-                    : token.type === 'topic'
-                        ? socialHashtagUrl(token.name, options.socialClient)
-                        : undefined
-        }));
-    }
-    const encoded = new TextEncoder().encode(text);
-    const decoder = new TextDecoder();
-    const segments = [];
-    const valid = [];
-    // UTF-8 continuation bytes cannot start/end a facet.
-    const boundary = (offset) => offset === encoded.length || (encoded[offset] & 0xc0) !== 0x80;
-    for (const facet of Array.isArray(facets) ? facets : []) {
-        if (!record(facet) || !record(facet.index) || !Array.isArray(facet.features))
-            continue;
-        const { byteStart, byteEnd } = facet.index;
-        if (typeof byteStart !== 'number' ||
-            typeof byteEnd !== 'number' ||
-            !Number.isSafeInteger(byteStart) ||
-            !Number.isSafeInteger(byteEnd) ||
-            byteStart < 0 ||
-            byteEnd <= byteStart ||
-            byteEnd > encoded.length ||
-            !boundary(byteStart) ||
-            !boundary(byteEnd))
-            continue;
-        valid.push({ byteStart, byteEnd, features: facet.features });
-    }
-    let cursor = 0;
-    for (const { byteStart, byteEnd, features } of valid.sort((a, b) => a.byteStart - b.byteStart)) {
-        if (byteStart < cursor)
-            continue;
-        const href = features.map((feature) => featureUrl(feature, options)).find(Boolean);
-        segments.push({ text: decoder.decode(encoded.slice(cursor, byteStart)) });
-        segments.push({ text: decoder.decode(encoded.slice(byteStart, byteEnd)), href });
-        cursor = byteEnd;
-    }
-    segments.push({ text: decoder.decode(encoded.slice(cursor)) });
-    return segments;
-}
 export function graphemeLength(text) {
     return Array.from(new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(text))
         .length;

package/dist/urls.d.ts

@@ -0,0 +1,9 @@
+/** Untrusted external destinations: absolute HTTP(S) URLs without credentials.
+ * This validates browser destinations, not hosts for server-side fetching (SSRF).
+ */
+export declare function safeHttpUrl(value: unknown): string | undefined;
+/** Navigation also supports root-relative app paths, fragments and mail/phone actions.
+ * Use safeHttpUrl instead when a record field must contain an external website.
+ * Invalid destinations return undefined so renderers omit href rather than falling back to it.
+ */
+export declare function safeLinkHref(value: unknown): string | undefined;

package/dist/urls.js

@@ -0,0 +1,39 @@
+/** Untrusted external destinations: absolute HTTP(S) URLs without credentials.
+ * This validates browser destinations, not hosts for server-side fetching (SSRF).
+ */
+export function safeHttpUrl(value) {
+    if (typeof value !== 'string' || !value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'https:' || url.protocol === 'http:') && !url.username && !url.password
+            ? url.href
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Navigation also supports root-relative app paths, fragments and mail/phone actions.
+ * Use safeHttpUrl instead when a record field must contain an external website.
+ * Invalid destinations return undefined so renderers omit href rather than falling back to it.
+ */
+export function safeLinkHref(value) {
+    const http = safeHttpUrl(value);
+    if (http)
+        return http;
+    if (typeof value !== 'string' || !value)
+        return undefined;
+    // Never normalize an ambiguous local/contact link into a different destination.
+    if (Array.from(value).some((c) => c === '\\' || c.charCodeAt(0) <= 0x20 || c.charCodeAt(0) === 0x7f))
+        return undefined;
+    if (value.startsWith('#') || (value.startsWith('/') && !value.startsWith('//')))
+        return value;
+    try {
+        const url = new URL(value);
+        return url.protocol === 'mailto:' || url.protocol === 'tel:' ? url.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}