@uicast/core 0.0.1-beta.1 → 0.0.1

package/dist/scope/create-proxy-scope.js

@@ -0,0 +1,295 @@
+import { EntryError } from "../entry-error.js";
+import { PROTOTYPE_KEYS, ROW_FIELDS } from "./parse-set-address.js";
+function createEmitter() {
+    const events = new Map();
+    let emits = 0;
+    return {
+        get emits() {
+            return emits;
+        },
+        on(field, handler) {
+            const handlers = events.get(field);
+            if (handlers)
+                handlers.add(handler);
+            else
+                events.set(field, new Set([handler]));
+            return () => events.get(field)?.delete(handler);
+        },
+        emit(field) {
+            emits++;
+            for (const fn of events.get(field) ?? [])
+                fn();
+            for (const fn of events.get("*") ?? [])
+                fn();
+        },
+    };
+}
+const isObject = (value) => value !== null && typeof value === "object";
+// Every scope's emitter is `createEmitter`'s, so the count is there.
+const countEmits = (scope) => scope.$$emitter.emits;
+function assertField(field) {
+    if (PROTOTYPE_KEYS.has(field)) {
+        throw new EntryError(`Cannot set "${field}": it reaches the prototype chain.`, {
+            reason: "guardrail-violation",
+        });
+    }
+    if (field.includes(".")) {
+        throw new EntryError(`Cannot set "${field}": a scope field has no dots. Write the whole field.`, {
+            reason: "guardrail-violation",
+        });
+    }
+}
+/**
+ * Creates a reactive scope: a shallow proxy over `bag`. A write to a field emits it, so every element reading that
+ * field re-renders.
+ *
+ * @example
+ * const userCtx = createProxyScope({ name: "Hopper", plan: "pro" });
+ * const init: InitFn = ({ scopes }) => { scopes.userCtx = userCtx; }; // read as scopes.userCtx.name
+ *
+ * @example
+ * userCtx.plan = "free"; // emits "plan"
+ * userCtx.$$set("plan", "pro", { default: true }); // no-op: "plan" is set
+ */
+function createProxyScope(bag = {}) {
+    const emitter = createEmitter();
+    const fields = bag;
+    const write = (field, value, options) => {
+        assertField(field);
+        const oldValue = fields[field];
+        if (options?.default && oldValue !== undefined)
+            return;
+        if (Object.is(oldValue, value))
+            return;
+        fields[field] = value;
+        emitter.emit(field);
+    };
+    return new Proxy(bag, {
+        get(target, prop, receiver) {
+            if (prop === "$$emitter")
+                return emitter;
+            if (prop === "$$set")
+                return write;
+            return Reflect.get(target, prop, receiver);
+        },
+        set(target, prop, value) {
+            if (typeof prop !== "string")
+                return Reflect.set(target, prop, value);
+            write(prop, value);
+            return true;
+        },
+    });
+}
+// Deeper than any result the evaluator lets out.
+const MAX_DATA_DEPTH = 256;
+// `value` with each part `swap` changes replaced, down to `depth` levels, copying what holds it; the same value when
+// nothing changes.
+function rebuild(value, swap, depth) {
+    const swapped = swap(value);
+    if (swapped !== value || depth === 0 || !isObject(value))
+        return swapped;
+    if (Array.isArray(value)) {
+        let out = null;
+        for (let i = 0; i < value.length; i++) {
+            const next = rebuild(value[i], swap, depth - 1);
+            if (next === value[i])
+                continue;
+            out ??= [...value];
+            out[i] = next;
+        }
+        return out ?? value;
+    }
+    let out = null;
+    for (const [key, child] of Object.entries(value)) {
+        const next = rebuild(child, swap, depth - 1);
+        if (next === child)
+            continue;
+        out ??= { ...value };
+        out[key] = next;
+    }
+    return out ?? value;
+}
+// How many levels below `value` the item first appears, or -1. Level by level, each object once, so a cycle ends.
+function levelOf(value, item) {
+    if (value === item)
+        return 0;
+    const seen = new WeakSet();
+    let level = [value];
+    for (let depth = 1; level.length > 0; depth++) {
+        const next = [];
+        for (const node of level) {
+            if (!isObject(node) || seen.has(node))
+                continue;
+            seen.add(node);
+            for (const child of Array.isArray(node) ? node : Object.values(node)) {
+                if (child === item)
+                    return depth;
+                if (isObject(child))
+                    next.push(child);
+            }
+        }
+        level = next;
+    }
+    return -1;
+}
+// Follows `path` down own keys, then replaces the item wherever it first appears below.
+function replaceAt(value, path, from, to) {
+    if (path.length === 0) {
+        const depth = levelOf(value, from);
+        return depth === -1 ? value : rebuild(value, (part) => (part === from ? to : part), depth);
+    }
+    const [key, ...rest] = path;
+    if (!isObject(value) || !Object.hasOwn(value, key))
+        return value;
+    const next = replaceAt(value[key], rest, from, to);
+    if (next === value[key])
+        return value;
+    return Array.isArray(value) ? Object.assign([...value], { [key]: next }) : { ...value, [key]: next };
+}
+const forwardTargetsByProxy = new WeakMap();
+// A row window's current item.
+const itemOfWindow = new WeakMap();
+// Every row window in `value` swapped for the item it shows now: a result holds the data, not a live view that a
+// later write changes behind the memo.
+const unwrapRows = (value) => rebuild(value, (part) => (isObject(part) ? (itemOfWindow.get(part)?.() ?? part) : part), MAX_DATA_DEPTH);
+// The fields a row's write replaces: those its list's `each` reads. Empty for a root-kind scope.
+const getForwardTargets = (proxy) => forwardTargetsByProxy.get(proxy)?.() ?? [];
+const ENGINE_DESCRIPTOR = { writable: false, enumerable: false, configurable: true };
+// A write never changes the item: it puts a copy in the fields `each` reads. A field of an outer row is that row's
+// write, so a nested edit climbs to the outermost array.
+function createRowScope() {
+    const emitter = createEmitter();
+    let element;
+    let visible = {};
+    let reads = [];
+    let detached = false;
+    // "scopes.root.data.items" → root's `data` field, then `items` below it. A bare scope names no field.
+    const sources = () => {
+        const out = [];
+        for (const read of reads) {
+            const [name, field, ...path] = read.split(".").slice(1);
+            const scope = Object.hasOwn(visible, name) ? visible[name] : undefined;
+            if (scope && field !== undefined && Object.hasOwn(scope, field))
+                out.push({ scope, field, path });
+        }
+        return out;
+    };
+    const write = (field, value, options) => {
+        assertField(field);
+        if (!isObject(element) || Array.isArray(element)) {
+            const kind = element === null ? "null" : Array.isArray(element) ? "an array" : `a ${typeof element}`;
+            throw new EntryError(`Cannot set "${field}": this row holds ${kind}, not an object. Replace it through the array it came from.`, { reason: "guardrail-violation" });
+        }
+        const oldValue = element[field];
+        if (options?.default && oldValue !== undefined)
+            return;
+        if (Object.is(oldValue, value))
+            return;
+        const copy = { ...element, [field]: value };
+        // Two sources may share a field (`data.a`, `data.b`), so each builds on the last.
+        const next = new Map();
+        for (const { scope, field: name, path } of detached ? [] : sources()) {
+            const pending = next.get(scope);
+            const current = pending?.has(name) ? pending.get(name) : scope[name];
+            const replaced = replaceAt(current, path, element, copy);
+            if (replaced !== current)
+                next.set(scope, (pending ?? new Map()).set(name, replaced));
+        }
+        if (next.size === 0) {
+            throw new EntryError(`Cannot set "${field}": this item is in no field "each" reads — the row was removed, or "each" built a new object. Edit the array it came from.`, { reason: "unknown-reference" });
+        }
+        for (const [scope, fields] of next)
+            for (const [name, replaced] of fields)
+                scope.$$set(name, replaced);
+        element = copy;
+        emitter.emit(field);
+    };
+    const proxy = new Proxy({}, {
+        get(_, prop) {
+            if (prop === "$$emitter")
+                return emitter;
+            if (prop === "$$set")
+                return write;
+            if (typeof prop !== "string")
+                return undefined;
+            return isObject(element) ? element[prop] : undefined;
+        },
+        has(_, prop) {
+            return typeof prop === "string" && isObject(element) && Object.hasOwn(element, prop);
+        },
+        ownKeys() {
+            return isObject(element) ? Reflect.ownKeys(element) : [];
+        },
+        getOwnPropertyDescriptor(_, prop) {
+            if (typeof prop !== "string" || !isObject(element))
+                return undefined;
+            const desc = Object.getOwnPropertyDescriptor(element, prop);
+            // The proxy target has no such property, so it must be reported configurable.
+            return desc ? { ...desc, configurable: true } : undefined;
+        },
+        set(_, prop, value) {
+            if (typeof prop !== "string")
+                return false;
+            write(prop, value);
+            return true;
+        },
+    });
+    forwardTargetsByProxy.set(proxy, () => sources().map(({ scope, field }) => ({ scope, field })));
+    itemOfWindow.set(proxy, () => element);
+    return {
+        proxy,
+        retarget(nextElement) {
+            const moved = nextElement !== element;
+            element = nextElement;
+            return moved;
+        },
+        see(scopes, eachReads) {
+            visible = scopes;
+            reads = eachReads;
+        },
+        detach() {
+            detached = true;
+        },
+    };
+}
+// `scopes.$<as>`: the runtime's read-only `index`, `id` and `value`, then whatever the row's steps set.
+function createRowState() {
+    const scope = createProxyScope(Object.create(null));
+    let runtime = {};
+    const write = (field, value, options) => {
+        if (ROW_FIELDS.has(field)) {
+            throw new EntryError(`Cannot set "${field}": the runtime owns it.`, { reason: "guardrail-violation" });
+        }
+        scope.$$set(field, value, options);
+    };
+    const proxy = new Proxy(scope, {
+        get(target, prop, receiver) {
+            if (prop === "$$set")
+                return write;
+            if (typeof prop === "string" && ROW_FIELDS.has(prop))
+                return runtime[prop];
+            return Reflect.get(target, prop, receiver);
+        },
+        has(target, prop) {
+            return (typeof prop === "string" && ROW_FIELDS.has(prop)) || Reflect.has(target, prop);
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            if (typeof prop === "string" && ROW_FIELDS.has(prop))
+                return { ...ENGINE_DESCRIPTOR, value: runtime[prop] };
+            return Reflect.getOwnPropertyDescriptor(target, prop);
+        },
+        set(_, prop, value) {
+            if (typeof prop !== "string")
+                return false;
+            write(prop, value);
+            return true;
+        },
+    });
+    return {
+        proxy,
+        retarget(element, index, id) {
+            runtime = { index, id, value: isObject(element) ? undefined : element };
+        },
+    };
+}
+export { createProxyScope, createRowScope, createRowState, countEmits, getForwardTargets, unwrapRows, };

package/dist/scope/parse-scope.d.ts

@@ -0,0 +1,2 @@
+export declare const parseScope: (key: string) => [string, string];
+export declare const depKey: (path: string) => string;

package/dist/scope/parse-scope.js

@@ -0,0 +1,11 @@
+const PREFIX = "scopes.";
+// "scopes.root.user.name" → ["root", "user.name"]
+export const parseScope = (key) => {
+    const dot = key.indexOf(".", PREFIX.length);
+    return [key.slice(PREFIX.length, dot), key.slice(dot + 1)];
+};
+// "scopes.root.user.name" → "scopes.root.user"; a bare scope reads every field: "scopes.root.*".
+export const depKey = (path) => {
+    const [scope, field] = path.slice(PREFIX.length).split(".");
+    return field ? `scopes.${scope}.${field}` : `scopes.${scope}.*`;
+};

package/dist/scope/parse-set-address.d.ts

@@ -0,0 +1,16 @@
+import { EntryError } from "../entry-error.js";
+import type { ComponentEntry } from "../types.js";
+export declare const PROTOTYPE_KEYS: Set<string>;
+export declare const ROW_FIELDS: Set<string>;
+type SetAddressFault = {
+    kind: "shape" | "reserved" | "prototype";
+    segment?: string;
+};
+export declare function findSetAddressFault(address: string): SetAddressFault | null;
+export declare function setAddressError(address: string, fault: SetAddressFault, elementKey?: string): EntryError;
+export declare function parseSetAddress(address: string, elementKey?: string): {
+    scope: string;
+    field: string;
+};
+export declare function entrySetAddressError(entry: Pick<ComponentEntry, "key" | "seed" | "callbacks">): EntryError | null;
+export {};

package/dist/scope/parse-set-address.js

@@ -0,0 +1,52 @@
+import { EntryError } from "../entry-error.js";
+const ADDRESS = /^scopes\.([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/;
+export const PROTOTYPE_KEYS = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+    "__defineGetter__",
+    "__defineSetter__",
+    "__lookupGetter__",
+    "__lookupSetter__",
+]);
+// A row's `$<as>` scope: readable, never written.
+export const ROW_FIELDS = new Set(["index", "id", "value"]);
+export function findSetAddressFault(address) {
+    const match = ADDRESS.exec(address);
+    if (!match)
+        return { kind: "shape" };
+    const [, scope, field] = match;
+    const prototype = [scope, field].find((segment) => PROTOTYPE_KEYS.has(segment));
+    if (prototype)
+        return { kind: "prototype", segment: prototype };
+    return scope.startsWith("$") && ROW_FIELDS.has(field) ? { kind: "reserved", segment: field } : null;
+}
+// The message names the fix — the recovery prompt forwards it verbatim.
+export function setAddressError(address, fault, elementKey) {
+    const messages = {
+        shape: `"set": "${address}" is not an address. A set names one field, "scopes.<scope>.<field>"; to change part of a field, write the whole field.`,
+        reserved: `"set": "${address}" writes "${fault.segment}", which the runtime owns (a row's index, id and value are read-only).`,
+        prototype: `"set": "${address}" writes through "${fault.segment}", which reaches the prototype chain.`,
+    };
+    return new EntryError(messages[fault.kind], { reason: "guardrail-violation", elementKey });
+}
+export function parseSetAddress(address, elementKey) {
+    const fault = findSetAddressFault(address);
+    if (fault)
+        throw setAddressError(address, fault, elementKey);
+    const [, scope, field] = ADDRESS.exec(address);
+    return { scope, field };
+}
+// The first bad `set` in the entry's seed and callbacks, as the error it raises.
+export function entrySetAddressError(entry) {
+    for (const steps of [entry.seed ?? [], ...Object.values(entry.callbacks ?? {})]) {
+        for (const { set } of steps) {
+            if (set === undefined)
+                continue;
+            const fault = findSetAddressFault(set);
+            if (fault)
+                return setAddressError(set, fault, entry.key);
+        }
+    }
+    return null;
+}

package/dist/stream-json-lines.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Yields each line of a byte or text stream that parses as JSON. Skips blank and non-JSON lines: code fences, prose,
+ * a cut-off last line.
+ *
+ * @example
+ * for await (const value of streamJsonLines(result.textStream)) {
+ *   if (isComponentEntry(value)) await saveEntry(value);
+ * }
+ *
+ * @example
+ * if (!res.body) throw new Error(`Generation failed (${res.status})`);
+ * const entries = streamJsonLines<ComponentEntry>(res.body);
+ */
+export declare function streamJsonLines<T = unknown>(source: ReadableStream<Uint8Array | string> | AsyncIterable<string | Uint8Array>): AsyncGenerator<T>;

package/dist/stream-json-lines.js

@@ -0,0 +1,59 @@
+/**
+ * Yields each line of a byte or text stream that parses as JSON. Skips blank and non-JSON lines: code fences, prose,
+ * a cut-off last line.
+ *
+ * @example
+ * for await (const value of streamJsonLines(result.textStream)) {
+ *   if (isComponentEntry(value)) await saveEntry(value);
+ * }
+ *
+ * @example
+ * if (!res.body) throw new Error(`Generation failed (${res.status})`);
+ * const entries = streamJsonLines<ComponentEntry>(res.body);
+ */
+export async function* streamJsonLines(source) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for await (const chunk of toAsyncIterable(source)) {
+        buffer += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+        let nl = buffer.indexOf("\n");
+        while (nl !== -1) {
+            yield* parseLine(buffer.slice(0, nl));
+            buffer = buffer.slice(nl + 1);
+            nl = buffer.indexOf("\n");
+        }
+    }
+    yield* parseLine(buffer + decoder.decode());
+}
+function* parseLine(raw) {
+    const line = raw.trim();
+    if (!line)
+        return;
+    try {
+        yield JSON.parse(line);
+    }
+    catch { }
+}
+function toAsyncIterable(source) {
+    if (Symbol.asyncIterator in source) {
+        return source;
+    }
+    // Not every browser's ReadableStream is async-iterable.
+    const stream = source;
+    return {
+        async *[Symbol.asyncIterator]() {
+            const reader = stream.getReader();
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        return;
+                    yield value;
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@uicast/expr";
+type Expression = string;
+type ScopePath = string;
+/**
+ * One value: `literal` is used as is, `expr` is an expression evaluated against the scopes.
+ *
+ * @example
+ * const props: ValueSource = { expr: "({ text: scopes.root.title })" };
+ * const fixed: ValueSource = { literal: { variant: "outline" } };
+ */
+export type ValueSource = {
+    expr: Expression;
+} | {
+    literal: unknown;
+};
+/**
+ * A `seed` step: a value source and the field it writes.
+ *
+ * @example
+ * const step: ValueSourceAssignment = { set: "scopes.root.users", expr: "getUsers()" };
+ */
+export type ValueSourceAssignment = {
+    /** The field to write: `scopes.<scope>.<field>`, never deeper. */
+    set: ScopePath;
+} & ValueSource;
+/**
+ * A callback step: a value source, optionally written to a field, confirmed first or debounced.
+ *
+ * @example
+ * const toggle: CallbackValueSourceAssignment = { set: "scopes.root.open", expr: "!currentValue" };
+ * const remove: CallbackValueSourceAssignment = { confirm: "Delete it?", expr: "deleteRow({ id: scopes.row.id })" };
+ */
+export type CallbackValueSourceAssignment = {
+    /** The field to write: `scopes.<scope>.<field>`. Absent: the step runs for its effect only. */
+    set?: ScopePath;
+    /** A question asked before this step, e.g. `"Delete this row?"`. Declined, this step and the rest are skipped. */
+    confirm?: string;
+    /** This step and the rest wait for 300 ms of quiet; only the latest call runs. */
+    debounce?: boolean;
+} & ValueSource;
+/**
+ * One line of a document: the JSON for one element. List fields are optional, so a `ComponentEntry[]` holds lists
+ * too; `each` marks a list.
+ *
+ * @example
+ * const entry: ComponentEntry = {
+ *   key: "open-count", component: "Typography",
+ *   props: { expr: "({ text: 'Open: ' + scopes.root.open })" },
+ * };
+ */
+export interface ComponentEntry {
+    /** Unique id. Parents name children by it; re-emitting it replaces the element and its subtree. */
+    key: string;
+    /** The component name, matched exactly against the catalog. */
+    component: string;
+    /** The props object, e.g. `{ expr: "({ text: scopes.root.title })" }`. Reactive. */
+    props?: ValueSource;
+    /** Steps that set up state once, at mount. Each writes its field only while it is still undefined. */
+    seed?: ValueSourceAssignment[];
+    /** An expression; truthy hides the element. Reactive. */
+    hidden?: Expression;
+    /** An expression; truthy renders the element as busy. Reactive, like `hidden`. */
+    loading?: Expression;
+    /** Steps per event, e.g. `{ onClick: [{ set: "scopes.root.open", expr: "!currentValue" }] }`. */
+    callbacks?: Record<string, CallbackValueSourceAssignment[]>;
+    /** Child keys, in render order. */
+    children?: string[];
+    /** An expression returning the array to repeat over; it makes the entry a list. */
+    each?: Expression;
+    /** Names each item's two scopes: `scopes.<as>` is the item, `scopes.$<as>` its row. */
+    as?: string;
+    /** The item field that gives the row its `id`. Absent, or missing on an item: the index. */
+    keyBy?: string;
+}
+/**
+ * An entry that repeats once per item of `each`.
+ *
+ * @example
+ * const rows: ComponentListEntry = { key: "task-row", component: "TableRow", each: "scopes.root.tasks", as: "task" };
+ */
+export interface ComponentListEntry extends ComponentEntry {
+    /** An expression returning the array to repeat over. */
+    each: Expression;
+    /** Names each item's two scopes: `scopes.<as>` is the item, `scopes.$<as>` its row. */
+    as: string;
+}
+export declare function isComponentListEntry(entry: ComponentEntry): entry is ComponentListEntry;
+/**
+ * Whether parsed JSON is an entry: string `key` and `component`, and `children`, if present, an array. The renderer
+ * checks the other fields at mount.
+ *
+ * @example
+ * const entries = parsedLines.filter(isComponentEntry);
+ */
+export declare function isComponentEntry(value: unknown): value is ComponentEntry;
+/**
+ * A schema that validates at run time (Standard Schema) and converts to JSON Schema for the prompt (Standard JSON
+ * Schema). Zod 4.2+, Valibot and ArkType schemas fit.
+ *
+ * @example
+ * const props: CombinedSpec = z.strictObject({ text: z.string() });
+ */
+export type CombinedSpec<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output> & StandardJSONSchemaV1<Input, Output>;
+/**
+ * What the model reads about a component: its name, description, props and events. Make one with
+ * `createComponentDefinition`.
+ *
+ * @example
+ * const definitions: ComponentDefinition[] = [...defs, BadgeDef];
+ * getComponentsPartialPrompt({ definitions });
+ */
+export type ComponentDefinition<TProps extends CombinedSpec = CombinedSpec, TCallbacks extends Record<string, CombinedSpec> = Record<string, CombinedSpec>> = {
+    /** What an entry's `component` names, e.g. `"Badge"`. Must be unique: the prompt builder and `<RendererProvider>` throw on a repeat. */
+    name: string;
+    /** When to use the component, printed word for word in the prompt. */
+    description: string;
+    /** The props schema: the prompt prints it, and the renderer parses props through it before `render`. */
+    props: TProps;
+    /** Event name → payload schema, e.g. `{ onChange: z.object({ value: z.string() }), onClear: z.null() }`. */
+    callbacks?: TCallbacks;
+    /** Kept out of the prompt; an entry that names it still renders. */
+    hidden?: boolean;
+};
+export {};

package/dist/types.js

@@ -0,0 +1,19 @@
+export function isComponentListEntry(entry) {
+    return entry.each !== undefined;
+}
+/**
+ * Whether parsed JSON is an entry: string `key` and `component`, and `children`, if present, an array. The renderer
+ * checks the other fields at mount.
+ *
+ * @example
+ * const entries = parsedLines.filter(isComponentEntry);
+ */
+export function isComponentEntry(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const entry = value;
+    return (typeof entry.key === "string" &&
+        typeof entry.component === "string" &&
+        // A string `children` (a plausible LLM slip) would be iterated char by char downstream.
+        (entry.children === undefined || Array.isArray(entry.children)));
+}

package/dist/url-policy.d.ts

@@ -0,0 +1,45 @@
+import { type JSONSchema } from "./json-schema.js";
+/**
+ * Which URLs a prop declared as a URL (`z.url()`) may hold. An object changes the default rules field by field; a
+ * predicate replaces them.
+ *
+ * @example
+ * const urlPolicy: UrlPolicy = { hosts: ["cdn.example.com", "*.imgix.net"] };
+ *
+ * @example
+ * const urlPolicy: UrlPolicy = (url) => url.startsWith("https://cdn.example.com/");
+ */
+export type UrlPolicy = {
+    /** Relative URLs: `/a`, `a/b`, `?q=1`, `#x`. Default `true`. */
+    allowRelative?: boolean;
+    /** Absolute URLs on the page origin. Default `true`. */
+    allowSameOrigin?: boolean;
+    /** Extra http/https hosts: an exact match, or `*.example.com` for subdomains (not the apex, so list both). */
+    hosts?: readonly string[];
+    /** `data:` raster images. Default `true`. SVG is never allowed: it can carry script. */
+    allowDataImages?: boolean;
+    /** The page origin, for where there is no `location` (SSR); without either, only `hosts` matches an absolute URL. */
+    origin?: string;
+} | ((url: string) => boolean);
+type UrlCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare const resolveUrlPolicy: (policy?: Exclude<UrlPolicy, (url: string) => boolean>) => {
+    allowRelative: boolean;
+    allowSameOrigin: boolean;
+    hosts: readonly string[];
+    allowDataImages: boolean;
+    origin: string | undefined;
+};
+export declare const checkUrl: (value: string, policy?: UrlPolicy) => UrlCheck;
+type UrlViolation = {
+    path: string;
+    url: string;
+    reason: string;
+};
+export declare const findUrlViolations: (schema: JSONSchema | undefined, value: unknown, policy?: UrlPolicy) => UrlViolation[];
+export declare const schemaHasUrlFormat: (schema: JSONSchema | undefined) => boolean;
+export {};