@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/internal/overlay-manager.js

@@ -0,0 +1,523 @@
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'area[href]',
+    'audio[controls]',
+    'button:not([disabled])',
+    'iframe',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'summary',
+    'textarea:not([disabled])',
+    'video[controls]',
+    '[contenteditable]:not([contenteditable="false"])',
+    '[tabindex]',
+].join(', ');
+const STACK_PROPERTY = '--lyra-overlay-stack-index';
+const STACK_BASE = 1000;
+const STACK_STEP = 2;
+const states = new WeakMap();
+const hostEntries = new WeakMap();
+/** Returns the deepest focused descendant across open shadow roots. */
+export function deepActiveElement(doc = document) {
+    let active = doc.activeElement;
+    while (active) {
+        const inner = active.shadowRoot?.activeElement ?? null;
+        if (!inner)
+            break;
+        active = inner;
+    }
+    return active;
+}
+function isSlot(element) {
+    return element.localName === 'slot' && typeof element.assignedElements === 'function';
+}
+function composedParent(element) {
+    if (element.assignedSlot)
+        return element.assignedSlot;
+    if (element.parentElement)
+        return element.parentElement;
+    const root = element.getRootNode();
+    return root.host ?? null;
+}
+export function composedContains(container, candidate) {
+    let current = candidate;
+    while (current) {
+        if (current === container)
+            return true;
+        current = composedParent(current);
+    }
+    return false;
+}
+function hasInertAncestor(element) {
+    let current = element;
+    while (current) {
+        if (current.inert)
+            return true;
+        current = composedParent(current);
+    }
+    return false;
+}
+function isRendered(element) {
+    if (element.hidden || element.getAttribute('aria-hidden') === 'true' || hasInertAncestor(element))
+        return false;
+    if (element.ownerDocument.defaultView?.getComputedStyle(element).visibility !== 'visible')
+        return false;
+    return element.checkVisibility ? element.checkVisibility() : element.getClientRects().length > 0;
+}
+function isTabbable(element) {
+    if (element.tabIndex < 0 || element.matches(':disabled'))
+        return false;
+    return isRendered(element);
+}
+function collectFocusable(element, result) {
+    if (element.matches(FOCUSABLE_SELECTOR) && isTabbable(element))
+        result.push(element);
+    if (isSlot(element)) {
+        const hasAssignedNodes = element.assignedNodes().length > 0;
+        const assigned = element
+            .assignedNodes({ flatten: true })
+            .filter((node) => node.nodeType === 1);
+        const children = hasAssignedNodes ? assigned : Array.from(element.children);
+        for (const child of children)
+            collectFocusable(child, result);
+        return;
+    }
+    const container = element.shadowRoot ?? element;
+    for (const child of Array.from(container.children))
+        collectFocusable(child, result);
+}
+/** Collects rendered focus targets through slots and nested open shadow roots in browser tab order. */
+export function collectFocusableElements(root) {
+    const result = [];
+    if ('matches' in root) {
+        collectFocusable(root, result);
+    }
+    else {
+        for (const child of Array.from(root.children))
+            collectFocusable(child, result);
+    }
+    const radioGroups = [];
+    for (const element of result) {
+        if (element.localName !== 'input')
+            continue;
+        const input = element;
+        if (input.type !== 'radio' || input.name === '')
+            continue;
+        let group = radioGroups.find((candidate) => candidate.name === input.name && candidate.form === input.form && candidate.root === input.getRootNode());
+        if (!group) {
+            group = { name: input.name, form: input.form, root: input.getRootNode(), members: [] };
+            radioGroups.push(group);
+        }
+        group.members.push(input);
+    }
+    const excludedRadios = new Set();
+    for (const group of radioGroups) {
+        const tabStop = group.members.find((radio) => radio.checked) ?? group.members[0];
+        for (const radio of group.members) {
+            if (radio !== tabStop)
+                excludedRadios.add(radio);
+        }
+    }
+    return result
+        .filter((element) => !excludedRadios.has(element))
+        .map((element, index) => ({ element, index }))
+        .sort((a, b) => {
+        const aPositive = a.element.tabIndex > 0;
+        const bPositive = b.element.tabIndex > 0;
+        if (aPositive !== bPositive)
+            return aPositive ? -1 : 1;
+        if (aPositive && a.element.tabIndex !== b.element.tabIndex)
+            return a.element.tabIndex - b.element.tabIndex;
+        return a.index - b.index;
+    })
+        .map(({ element }) => element);
+}
+function tryFocus(target) {
+    if (!target?.isConnected || !isRendered(target) || target.matches(':disabled'))
+        return false;
+    target.focus();
+    const active = deepActiveElement(target.ownerDocument);
+    return active === target || composedContains(target, active);
+}
+function focusEntry(entry, backwards = false, preserveCurrent = true) {
+    const panel = entry.options.panel();
+    if (!panel)
+        return;
+    const active = deepActiveElement(entry.state.document);
+    if (preserveCurrent && composedContains(panel, active))
+        return;
+    const preferred = entry.options.preferredInitialFocus?.() ?? null;
+    if (preferred && composedContains(panel, preferred) && tryFocus(preferred))
+        return;
+    const focusable = collectFocusableElements(panel);
+    const ordered = backwards ? focusable.reverse() : focusable;
+    for (const target of ordered) {
+        if (tryFocus(target))
+            return;
+    }
+    panel.focus();
+}
+function handleTab(state, entry, event) {
+    const panel = entry.options.panel();
+    if (!panel)
+        return;
+    const focusable = collectFocusableElements(panel);
+    if (focusable.length === 0) {
+        event.preventDefault();
+        panel.focus();
+        return;
+    }
+    const active = deepActiveElement(state.document);
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const activeIndex = active ? focusable.indexOf(active) : -1;
+    if (activeIndex === -1) {
+        event.preventDefault();
+        (event.shiftKey ? last : first).focus();
+    }
+    else if (event.shiftKey && active === first) {
+        event.preventDefault();
+        last.focus();
+    }
+    else if (!event.shiftKey && active === last) {
+        event.preventDefault();
+        first.focus();
+    }
+}
+function scheduleInertUpdate(state) {
+    if (state.inertUpdateQueued)
+        return;
+    state.inertUpdateQueued = true;
+    queueMicrotask(() => {
+        state.inertUpdateQueued = false;
+        applyTopmostInert(state);
+    });
+}
+function handleMutations(state, records) {
+    let needsInertUpdate = false;
+    for (let index = 0; index < records.length; index++) {
+        const record = records[index];
+        if (record.type === 'childList') {
+            needsInertUpdate = true;
+            continue;
+        }
+        if (record.type !== 'attributes' || record.attributeName !== 'inert')
+            continue;
+        const element = record.target;
+        let nextRecord;
+        for (let nextIndex = index + 1; nextIndex < records.length; nextIndex++) {
+            const candidate = records[nextIndex];
+            if (candidate.type === 'attributes' && candidate.attributeName === 'inert' && candidate.target === element) {
+                nextRecord = candidate;
+                break;
+            }
+        }
+        const newValue = nextRecord ? nextRecord.oldValue !== null : element.hasAttribute('inert');
+        const pending = state.pendingInertWrites.get(element);
+        if (pending?.[0] === newValue) {
+            pending.shift();
+            if (pending.length === 0)
+                state.pendingInertWrites.delete(element);
+            continue;
+        }
+        if (state.inerted.has(element)) {
+            state.inerted.set(element, newValue);
+            needsInertUpdate = true;
+        }
+    }
+    if (needsInertUpdate)
+        scheduleInertUpdate(state);
+}
+const mutationObserverOptions = {
+    attributeFilter: ['inert'],
+    attributeOldValue: true,
+    attributes: true,
+    childList: true,
+    subtree: true,
+};
+function observeMutationRoot(state, root) {
+    if (!state.observer || state.observedRoots.has(root))
+        return;
+    state.observer.observe(root === state.document ? state.document.documentElement : root, mutationObserverOptions);
+    state.observedRoots.add(root);
+}
+function startState(state) {
+    state.document.addEventListener('keydown', state.onKeyDown);
+    const Observer = state.document.defaultView?.MutationObserver ?? MutationObserver;
+    state.observer = new Observer((records) => handleMutations(state, records));
+    observeMutationRoot(state, state.document);
+}
+function stopState(state) {
+    state.document.removeEventListener('keydown', state.onKeyDown);
+    state.observer?.disconnect();
+    state.observer = undefined;
+    state.observedRoots.clear();
+    state.pendingInertWrites.clear();
+}
+function createState(doc) {
+    const state = {};
+    state.document = doc;
+    state.stack = [];
+    state.nextStackOrder = 0;
+    state.inerted = new Map();
+    state.pendingInertWrites = new Map();
+    state.observedRoots = new Set();
+    state.inertUpdateQueued = false;
+    state.onKeyDown = (event) => {
+        if (event.defaultPrevented || event.isComposing)
+            return;
+        const entry = state.stack[state.stack.length - 1];
+        if (!entry)
+            return;
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            entry.options.onEscape();
+        }
+        else if (event.key === 'Tab') {
+            if (entry.options.trapFocus === false)
+                entry.options.onTab?.();
+            else
+                handleTab(state, entry, event);
+        }
+    };
+    states.set(doc, state);
+    return state;
+}
+function stateFor(doc) {
+    return states.get(doc) ?? createState(doc);
+}
+function setInertByManager(state, element, value) {
+    if (element.inert === value)
+        return;
+    if (state.observer && state.observedRoots.has(element.getRootNode())) {
+        let pending = state.pendingInertWrites.get(element);
+        if (!pending) {
+            pending = [];
+            state.pendingInertWrites.set(element, pending);
+        }
+        pending.push(value);
+    }
+    else {
+        // No mutation record will be delivered for a detached element or for an
+        // element in a shadow root outside this state's observed document tree.
+        state.pendingInertWrites.delete(element);
+    }
+    element.inert = value;
+}
+function inertElement(state, element, desired) {
+    if (!('inert' in element))
+        return;
+    const htmlElement = element;
+    desired.add(htmlElement);
+    if (!state.inerted.has(htmlElement))
+        state.inerted.set(htmlElement, htmlElement.inert);
+    setInertByManager(state, htmlElement, true);
+}
+function pathParent(element) {
+    return element.assignedSlot ?? element.parentNode;
+}
+function parentPathElement(parent) {
+    if (parent.nodeType === Node.ELEMENT_NODE)
+        return parent;
+    return parent.host ?? null;
+}
+function composedChildren(parent) {
+    if (parent.localName === 'slot') {
+        return parent.assignedElements({ flatten: true });
+    }
+    return 'children' in parent ? Array.from(parent.children) : [];
+}
+function isShadowRoot(node) {
+    return node.nodeType === 11 && 'host' in node;
+}
+function addAllowedPath(allowed, host, doc) {
+    let current = host;
+    while (current && current !== doc.body && current !== doc.documentElement) {
+        const parent = pathParent(current);
+        if (!parent)
+            break;
+        let children = allowed.get(parent);
+        if (!children) {
+            children = new Set();
+            allowed.set(parent, children);
+        }
+        children.add(current);
+        current = parentPathElement(parent);
+    }
+}
+function applyTopmostInert(state) {
+    let modalIndex = -1;
+    for (let index = state.stack.length - 1; index >= 0; index--) {
+        if (state.stack[index].options.modal !== false) {
+            modalIndex = index;
+            break;
+        }
+    }
+    const desired = new Set();
+    if (modalIndex !== -1) {
+        const allowed = new Map();
+        for (const entry of state.stack.slice(modalIndex)) {
+            if (entry.options.host.isConnected)
+                addAllowedPath(allowed, entry.options.host, state.document);
+        }
+        for (const [parent, children] of allowed) {
+            if (isShadowRoot(parent))
+                observeMutationRoot(state, parent);
+            for (const child of composedChildren(parent)) {
+                if (!children.has(child))
+                    inertElement(state, child, desired);
+            }
+        }
+    }
+    for (const [element, intended] of state.inerted) {
+        if (desired.has(element))
+            continue;
+        setInertByManager(state, element, intended);
+        state.inerted.delete(element);
+    }
+}
+function restoreStackStyle(entry) {
+    if (entry.previousStackValue) {
+        entry.options.host.style.setProperty(STACK_PROPERTY, entry.previousStackValue, entry.previousStackPriority);
+    }
+    else {
+        entry.options.host.style.removeProperty(STACK_PROPERTY);
+    }
+}
+function updateStackStyles(state) {
+    state.stack.forEach((entry, index) => {
+        entry.options.host.style.setProperty(STACK_PROPERTY, String(STACK_BASE + index * STACK_STEP));
+    });
+}
+function registerEntry(entry, state, preserveStackOrder = false) {
+    if (state.stack.length === 0)
+        startState(state);
+    if (!preserveStackOrder || entry.state !== state)
+        entry.stackOrder = state.nextStackOrder++;
+    entry.state = state;
+    entry.registered = true;
+    const nextIndex = state.stack.findIndex((candidate) => candidate.stackOrder > entry.stackOrder);
+    if (nextIndex === -1)
+        state.stack.push(entry);
+    else
+        state.stack.splice(nextIndex, 0, entry);
+    updateStackStyles(state);
+    applyTopmostInert(state);
+}
+function unregisterEntry(entry) {
+    if (!entry.registered)
+        return entry.wasTopmostOnSuspend;
+    const state = entry.state;
+    const index = state.stack.indexOf(entry);
+    const wasTopmost = index === state.stack.length - 1;
+    if (index !== -1)
+        state.stack.splice(index, 1);
+    entry.registered = false;
+    entry.wasTopmostOnSuspend = wasTopmost;
+    restoreStackStyle(entry);
+    updateStackStyles(state);
+    applyTopmostInert(state);
+    if (state.stack.length === 0)
+        stopState(state);
+    return wasTopmost;
+}
+function rebaseReturnTargets(entry) {
+    for (const candidate of entry.state.stack) {
+        if (candidate === entry || candidate.stackOrder <= entry.stackOrder)
+            continue;
+        if (candidate.restoreFocusTo && composedContains(entry.options.host, candidate.restoreFocusTo)) {
+            candidate.restoreFocusTo = entry.restoreFocusTo;
+        }
+    }
+}
+function restoreEntryFocus(entry) {
+    if (tryFocus(entry.restoreFocusTo))
+        return;
+    const next = entry.state.stack[entry.state.stack.length - 1];
+    if (next)
+        focusEntry(next, false, false);
+}
+function deactivateEntry(entry, restoreFocus) {
+    if (!entry.active)
+        return;
+    rebaseReturnTargets(entry);
+    const wasTopmost = unregisterEntry(entry);
+    entry.active = false;
+    entry.suspendGeneration++;
+    if (hostEntries.get(entry.options.host) === entry)
+        hostEntries.delete(entry.options.host);
+    if (!wasTopmost)
+        return;
+    if (restoreFocus) {
+        restoreEntryFocus(entry);
+        return;
+    }
+    const next = entry.state.stack[entry.state.stack.length - 1];
+    if (next)
+        focusEntry(next);
+}
+/**
+ * Adds an overlay to a stack scoped to its own `ownerDocument`. One document
+ * listener routes Escape and Tab only to the top entry, while modal inerting,
+ * visual stack depth, and focus return are recomputed as entries move.
+ */
+export function activateOverlay(options) {
+    const previous = hostEntries.get(options.host);
+    const inheritedReturnTarget = previous?.active ? previous.restoreFocusTo : undefined;
+    if (previous?.active)
+        previous.handle.deactivate({ restoreFocus: false });
+    const doc = options.host.ownerDocument;
+    const active = deepActiveElement(doc);
+    const captured = active && typeof active.focus === 'function' ? active : null;
+    const entry = {};
+    entry.options = options;
+    entry.restoreFocusTo =
+        options.restoreFocusTo !== undefined ? options.restoreFocusTo : (inheritedReturnTarget ?? captured);
+    entry.active = true;
+    entry.registered = false;
+    entry.wasTopmostOnSuspend = false;
+    entry.suspendGeneration = 0;
+    entry.state = stateFor(doc);
+    entry.stackOrder = -1;
+    entry.previousStackValue = options.host.style.getPropertyValue(STACK_PROPERTY);
+    entry.previousStackPriority = options.host.style.getPropertyPriority(STACK_PROPERTY);
+    entry.handle = {
+        focusInitial: () => {
+            if (entry.active && entry.registered && entry.state.stack[entry.state.stack.length - 1] === entry) {
+                focusEntry(entry);
+            }
+        },
+        deactivate: (deactivateOptions = {}) => {
+            deactivateEntry(entry, deactivateOptions.restoreFocus !== false);
+        },
+        suspend: () => {
+            if (!entry.active || !entry.registered)
+                return;
+            unregisterEntry(entry);
+            const generation = ++entry.suspendGeneration;
+            queueMicrotask(() => {
+                if (entry.active && !entry.registered && entry.suspendGeneration === generation && !entry.options.host.isConnected) {
+                    deactivateEntry(entry, true);
+                }
+            });
+        },
+        resume: () => {
+            if (!entry.active || entry.registered)
+                return;
+            entry.suspendGeneration++;
+            const state = stateFor(entry.options.host.ownerDocument);
+            registerEntry(entry, state, entry.state === state);
+        },
+        isTopmost: () => entry.active && entry.registered && entry.state.stack[entry.state.stack.length - 1] === entry,
+        isActive: () => entry.active,
+        dismissBackdrop: () => {
+            if (!entry.handle.isTopmost() || !entry.options.onBackdrop)
+                return false;
+            entry.options.onBackdrop();
+            return true;
+        },
+    };
+    hostEntries.set(options.host, entry);
+    registerEntry(entry, entry.state);
+    return entry.handle;
+}

package/dist/internal/positioner.js

@@ -1,4 +1,4 @@
-import { computePosition, autoUpdate, flip, shift, offset, } from '@floating-ui/dom';
+import { computePosition, autoUpdate, flip, shift, offset, size, } from '@floating-ui/dom';
 /**
  * Position `popup` (fixed) relative to `anchor` with flip/shift, keeping it
  * updated on scroll/resize. Returns a cleanup function that stops updating.
@@ -12,10 +12,34 @@ export function place(anchor, popup, opts = {}) {
         // the scroll offset (appears too far down on a scrolled page).
         strategy: 'fixed',
         placement: opts.placement ?? 'bottom-start',
-        middleware: [offset(opts.offset ?? 4), flip(), shift({ padding: 8 })],
+        middleware: [
+            offset(opts.offset ?? 4),
+            flip(),
+            shift({ padding: 8 }),
+            size({
+                padding: 8,
+                apply({ availableWidth, availableHeight, elements }) {
+                    elements.floating.style.setProperty('--lyra-positioner-available-inline-size', `${Math.max(0, availableWidth)}px`);
+                    elements.floating.style.setProperty('--lyra-positioner-available-block-size', `${Math.max(0, availableHeight)}px`);
+                },
+            }),
+        ],
     }).then(({ x, y }) => {
         popup.style.left = `${x}px`;
         popup.style.top = `${y}px`;
     });
-    return autoUpdate(anchor, popup, update);
+    const stopAutoUpdate = autoUpdate(anchor, popup, update);
+    // The visual viewport changes independently of the layout viewport when a
+    // mobile on-screen keyboard opens or closes. Floating UI's normal window
+    // resize listener does not receive those events, so keep the available-size
+    // CSS variables and fixed coordinates in sync with the visual viewport too.
+    const visualViewport = anchor.ownerDocument.defaultView?.visualViewport;
+    const updateFromVisualViewport = () => void update();
+    visualViewport?.addEventListener('resize', updateFromVisualViewport);
+    visualViewport?.addEventListener('scroll', updateFromVisualViewport);
+    return () => {
+        stopAutoUpdate();
+        visualViewport?.removeEventListener('resize', updateFromVisualViewport);
+        visualViewport?.removeEventListener('scroll', updateFromVisualViewport);
+    };
 }

package/dist/internal/rtl.d.ts

@@ -1,3 +1,4 @@
+import type { Placement } from '@floating-ui/dom';
 /**
  * Whether `el` resolves to RTL text direction. Logical CSS properties
  * (`inset-inline-start`, etc.) already flip visual layout for free, but
@@ -5,3 +6,25 @@
  * arrow-key direction) has to consult this explicitly to match.
  */
 export declare function isRtl(el: Element): boolean;
+/** A physical (not logical) horizontal side. */
+export type PhysicalSide = 'left' | 'right';
+/**
+ * Swaps `side` under RTL, passes it through unchanged under LTR -- for
+ * reasoning about a physical side (e.g. which edge an icon should point at,
+ * or which edge of a track a dock panel resizes from) that logical CSS
+ * properties alone can't express, since the caller needs the resolved
+ * physical value itself (to rotate a glyph, to pick a Floating UI
+ * `Placement`), not just a layout that flips for free.
+ */
+export declare function rtlAwareSide(side: PhysicalSide, el: Element): PhysicalSide;
+/**
+ * Swaps the `left`/`right` component of a Floating UI `Placement` under RTL
+ * (`'right-start'` <-> `'left-start'`, etc.) -- `'top'`/`'bottom'`-based
+ * placements are already direction-agnostic and pass through unchanged.
+ * Floating UI's own `computePosition()` has no built-in RTL awareness (it
+ * positions purely by the physical `left`/`right`/`top`/`bottom` it's given),
+ * so a popover that means "anchor to my trailing edge" must resolve that
+ * intent to a physical placement itself before calling `place()` from
+ * `positioner.ts` -- this is the resolution step.
+ */
+export declare function rtlAwarePlacement(placement: Placement, el: Element): Placement;

package/dist/internal/rtl.js

@@ -7,3 +7,31 @@
 export function isRtl(el) {
     return getComputedStyle(el).direction === 'rtl';
 }
+/**
+ * Swaps `side` under RTL, passes it through unchanged under LTR -- for
+ * reasoning about a physical side (e.g. which edge an icon should point at,
+ * or which edge of a track a dock panel resizes from) that logical CSS
+ * properties alone can't express, since the caller needs the resolved
+ * physical value itself (to rotate a glyph, to pick a Floating UI
+ * `Placement`), not just a layout that flips for free.
+ */
+export function rtlAwareSide(side, el) {
+    if (!isRtl(el))
+        return side;
+    return side === 'left' ? 'right' : 'left';
+}
+/**
+ * Swaps the `left`/`right` component of a Floating UI `Placement` under RTL
+ * (`'right-start'` <-> `'left-start'`, etc.) -- `'top'`/`'bottom'`-based
+ * placements are already direction-agnostic and pass through unchanged.
+ * Floating UI's own `computePosition()` has no built-in RTL awareness (it
+ * positions purely by the physical `left`/`right`/`top`/`bottom` it's given),
+ * so a popover that means "anchor to my trailing edge" must resolve that
+ * intent to a physical placement itself before calling `place()` from
+ * `positioner.ts` -- this is the resolution step.
+ */
+export function rtlAwarePlacement(placement, el) {
+    if (!isRtl(el))
+        return placement;
+    return placement.replace(/^(left|right)/, (side) => (side === 'left' ? 'right' : 'left'));
+}

package/dist/internal/safe-url.d.ts

@@ -0,0 +1,12 @@
+/** Returns a trimmed URL safe for an `<img>`/`<video>` `src`, or `null`.
+ * Relative URLs and `http:`, `https:`, `blob:`, and `data:` are allowed. The
+ * platform parser performs the same control-character normalization as DOM
+ * URL sinks, preventing obfuscated schemes such as `java\tscript:`. */
+export declare function safeMediaSrc(url: unknown): string | null;
+/** Returns a trimmed URL safe to pass to `fetch()`, or `null`. This shares the
+ * resource allowlist with media sources so text/image `data:` URLs remain
+ * usable, while navigation-only and executable schemes are rejected. */
+export declare function safeFetchUrl(url: unknown): string | null;
+/** Returns a trimmed URL safe for an `<a href>`, or `null`. `data:` is
+ * intentionally excluded because following it can open an active document. */
+export declare function safeLinkHref(url: unknown): string | null;

package/dist/internal/safe-url.js

@@ -0,0 +1,41 @@
+// URL safety is sink-specific. A `data:` URL is inert when used as media or
+// fetched as data, but navigating an anchor to `data:text/html,...` creates an
+// active document. Keep the link allowlist deliberately narrower.
+const SAFE_RESOURCE_SCHEMES = new Set(['http:', 'https:', 'blob:', 'data:']);
+const SAFE_LINK_SCHEMES = new Set(['http:', 'https:', 'blob:']);
+// A fixed web base makes relative and scheme-relative inputs parse through the
+// same WHATWG URL algorithm as absolute inputs. This also means malformed
+// absolute URLs are rejected instead of being mistaken for relative paths.
+const PARSE_BASE = 'https://lyra.invalid/';
+function safeUrlOrNull(url, allowedSchemes) {
+    if (typeof url !== 'string')
+        return null;
+    const trimmed = url.trim();
+    if (trimmed === '')
+        return null;
+    try {
+        const protocol = new URL(trimmed, PARSE_BASE).protocol;
+        return allowedSchemes.has(protocol) ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns a trimmed URL safe for an `<img>`/`<video>` `src`, or `null`.
+ * Relative URLs and `http:`, `https:`, `blob:`, and `data:` are allowed. The
+ * platform parser performs the same control-character normalization as DOM
+ * URL sinks, preventing obfuscated schemes such as `java\tscript:`. */
+export function safeMediaSrc(url) {
+    return safeUrlOrNull(url, SAFE_RESOURCE_SCHEMES);
+}
+/** Returns a trimmed URL safe to pass to `fetch()`, or `null`. This shares the
+ * resource allowlist with media sources so text/image `data:` URLs remain
+ * usable, while navigation-only and executable schemes are rejected. */
+export function safeFetchUrl(url) {
+    return safeUrlOrNull(url, SAFE_RESOURCE_SCHEMES);
+}
+/** Returns a trimmed URL safe for an `<a href>`, or `null`. `data:` is
+ * intentionally excluded because following it can open an active document. */
+export function safeLinkHref(url) {
+    return safeUrlOrNull(url, SAFE_LINK_SCHEMES);
+}