@viniaraujo68/plinth 0.0.0-stage → 0.3.0

package/dist/formatters.d.ts

@@ -0,0 +1,95 @@
+/** A locale tag, or the priority list `Intl` walks when the first tag has no data. */
+export type Locale = string | readonly string[];
+/**
+ * What a formatter accepts as an instant: a `Date`, epoch milliseconds, or a string the platform
+ * `Date` parser understands — API payloads carry timestamps as strings far more often than as
+ * anything else.
+ */
+export type DateInput = Date | string | number;
+/**
+ * What the numeric formatters accept. Strings are here because a backend that keeps money or
+ * rates in an exact decimal type serialises them as strings to avoid the float round trip.
+ * `bigint` is passed to `Intl` untouched, which is the only way it stays exact.
+ */
+export type NumericInput = number | bigint | string;
+/**
+ * The three shapes the same amount takes across a UI:
+ *
+ * - `currency` — symbol and the currency's own decimals: `R$ 1.234,50`.
+ * - `plain` — the same digits without the symbol, for an input a user edits or a column whose
+ *   header already names the currency.
+ * - `axis` — no decimals, for chart axis ticks and any other place where three characters of
+ *   precision cost more room than they are worth.
+ */
+export type MoneyFormat = "currency" | "plain" | "axis";
+/**
+ * Per-formatter `Intl` options merged over the defaults, fixed once for the whole factory.
+ *
+ * Precision and date style are app-wide decisions in the same way the locale is; making them
+ * per-call arguments instead would mean a cache keyed by whatever a caller passes.
+ */
+export interface FormatterOptions {
+    date?: Intl.DateTimeFormatOptions;
+    datetime?: Intl.DateTimeFormatOptions;
+    number?: Intl.NumberFormatOptions;
+    percent?: Intl.NumberFormatOptions;
+    relativeTime?: Intl.RelativeTimeFormatOptions;
+}
+/**
+ * Formats an instant, and passes a missing value through as `null`.
+ *
+ * The two signatures are what makes `{formatters.date(row.releasedAt) ?? "—"}` type-check without
+ * a guard at every call site: a value that cannot be null formats to a `string`, and only a
+ * nullable one widens the result.
+ */
+export interface DateFormatter {
+    (value: DateInput): string;
+    (value: DateInput | null | undefined): string | null;
+}
+/** Formats a number, and passes a missing value through as `null`. */
+export interface NumberFormatter {
+    (value: NumericInput): string;
+    (value: NumericInput | null | undefined): string | null;
+}
+/**
+ * Formats an amount in `code` (an ISO 4217 code: `"BRL"`, `"USD"`, `"JPY"`).
+ *
+ * The value is in whole currency units. Integer cents are an app's storage convention, not this
+ * library's: whoever holds the cents divides by 100.
+ */
+export interface CurrencyFormatter {
+    (value: NumericInput, code: string, format?: MoneyFormat): string;
+    (value: NumericInput | null | undefined, code: string, format?: MoneyFormat): string | null;
+}
+/** Formats the distance from `now` (default: the current time) to `value`. */
+export interface RelativeTimeFormatter {
+    (value: DateInput, now?: DateInput): string;
+    (value: DateInput | null | undefined, now?: DateInput): string | null;
+}
+export interface Formatters {
+    date: DateFormatter;
+    datetime: DateFormatter;
+    number: NumberFormatter;
+    percent: NumberFormatter;
+    currency: CurrencyFormatter;
+    relativeTime: RelativeTimeFormatter;
+}
+/**
+ * Builds the six formatters for one locale.
+ *
+ * Nothing here decides the locale or the currency on its own. The app picks the locale once, at
+ * the factory; the currency code travels per call, so a single-currency app closes over one and a
+ * multi-currency one passes whatever the row holds.
+ *
+ * ```ts
+ * const fmt = createFormatters("pt-BR");
+ * fmt.currency(1234.5, "BRL");          // "R$ 1.234,50"
+ * fmt.currency(1234.5, "BRL", "axis");  // "R$ 1.235"
+ * fmt.relativeTime(sentAt);             // "há 5 minutos"
+ * ```
+ *
+ * The closure is the cache. `Intl` constructors are the expensive part — the `format` calls are
+ * cheap — so building the factory once at module scope of an app, or once per locale in a store,
+ * is the difference between resolving locale data a handful of times and doing it per row.
+ */
+export declare const createFormatters: (locale: Locale, options?: FormatterOptions) => Formatters;

package/dist/formatters.js

@@ -0,0 +1,146 @@
+const DEFAULT_DATE = { dateStyle: "short" };
+const DEFAULT_DATETIME = { dateStyle: "short", timeStyle: "medium" };
+const DEFAULT_NUMBER = {};
+/** A ratio, not a 0-100 scale: `percent(0.125)` is `12.5%`. Two decimals is where rates stop. */
+const DEFAULT_PERCENT = { style: "percent", maximumFractionDigits: 2 };
+/**
+ * `auto` is what makes this a replacement for a hand-built "3 min ago" helper rather than a
+ * stiffer version of one: it spends the locale's own words where they exist — "yesterday",
+ * "last week", "now" — and falls back to the numeric phrasing everywhere else.
+ */
+const DEFAULT_RELATIVE_TIME = { numeric: "auto" };
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * A date-only string ("2026-08-29") parses as UTC midnight, so west of Greenwich it formats as
+ * the previous calendar day. Shifting it by the offset in effect *at that instant* — not today's
+ * offset, which would land dates on the far side of a DST change one day off — makes it local
+ * midnight, and it then formats as the day it names. Any other string already denotes an instant.
+ */
+const toDate = (value) => {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === "number")
+        return new Date(value);
+    const parsed = new Date(value);
+    if (!DATE_ONLY.test(value))
+        return parsed;
+    return new Date(parsed.getTime() + parsed.getTimezoneOffset() * 60_000);
+};
+/**
+ * `Number`, not `parseFloat`: `parseFloat("12 apples")` is `12`, which puts a number on screen
+ * that nobody sent. A value that is not a number reaches `Intl` as `NaN` and renders as such,
+ * because an empty cell would hide the bug instead of showing it.
+ */
+const toNumeric = (value) => typeof value === "string" ? Number(value) : value;
+/** An empty string is a missing value, not a zero and not an invalid date. */
+const isMissing = (value) => value === null || value === undefined || value === "";
+const SECOND = ["second", 1];
+/**
+ * Seconds in each unit, largest first. Month and year are the average Gregorian ones: the unit is
+ * picked to phrase an approximation, so a February that is three days shorter changes nothing a
+ * reader could notice.
+ */
+const RELATIVE_UNITS = [
+    ["year", 31_557_600],
+    ["month", 2_629_800],
+    ["week", 604_800],
+    ["day", 86_400],
+    ["hour", 3_600],
+    ["minute", 60],
+    SECOND,
+];
+/**
+ * Builds the six formatters for one locale.
+ *
+ * Nothing here decides the locale or the currency on its own. The app picks the locale once, at
+ * the factory; the currency code travels per call, so a single-currency app closes over one and a
+ * multi-currency one passes whatever the row holds.
+ *
+ * ```ts
+ * const fmt = createFormatters("pt-BR");
+ * fmt.currency(1234.5, "BRL");          // "R$ 1.234,50"
+ * fmt.currency(1234.5, "BRL", "axis");  // "R$ 1.235"
+ * fmt.relativeTime(sentAt);             // "há 5 minutos"
+ * ```
+ *
+ * The closure is the cache. `Intl` constructors are the expensive part — the `format` calls are
+ * cheap — so building the factory once at module scope of an app, or once per locale in a store,
+ * is the difference between resolving locale data a handful of times and doing it per row.
+ */
+export const createFormatters = (locale, options = {}) => {
+    const dateFormat = new Intl.DateTimeFormat(locale, { ...DEFAULT_DATE, ...options.date });
+    const datetimeFormat = new Intl.DateTimeFormat(locale, {
+        ...DEFAULT_DATETIME,
+        ...options.datetime,
+    });
+    const numberFormat = new Intl.NumberFormat(locale, { ...DEFAULT_NUMBER, ...options.number });
+    const percentFormat = new Intl.NumberFormat(locale, { ...DEFAULT_PERCENT, ...options.percent });
+    const relativeTimeFormat = new Intl.RelativeTimeFormat(locale, {
+        ...DEFAULT_RELATIVE_TIME,
+        ...options.relativeTime,
+    });
+    // Currency is the one axis the factory cannot resolve up front, so it memoises what it meets.
+    // Bounded by the codes an app actually shows, times the three formats.
+    const moneyFormats = new Map();
+    const moneyFormat = (code, format) => {
+        const key = `${code}:${format}`;
+        const cached = moneyFormats.get(key);
+        if (cached)
+            return cached;
+        const built = buildMoneyFormat(code, format);
+        moneyFormats.set(key, built);
+        return built;
+    };
+    const buildMoneyFormat = (code, format) => {
+        const currencyOptions = { style: "currency", currency: code };
+        if (format === "currency")
+            return new Intl.NumberFormat(locale, currencyOptions);
+        if (format === "axis")
+            return new Intl.NumberFormat(locale, {
+                ...currencyOptions,
+                minimumFractionDigits: 0,
+                maximumFractionDigits: 0,
+            });
+        // The symbol is dropped, but the currency still decides the digits: JPY has none, most have
+        // two, and a few have three. Asking the currency formatter what it resolved keeps that right
+        // for every code instead of hardcoding the two decimals of the currencies at hand.
+        const { minimumFractionDigits, maximumFractionDigits } = moneyFormat(code, "currency").resolvedOptions();
+        return new Intl.NumberFormat(locale, { minimumFractionDigits, maximumFractionDigits });
+    };
+    function date(value) {
+        if (isMissing(value))
+            return null;
+        return dateFormat.format(toDate(value));
+    }
+    function datetime(value) {
+        if (isMissing(value))
+            return null;
+        return datetimeFormat.format(toDate(value));
+    }
+    function number(value) {
+        if (isMissing(value))
+            return null;
+        return numberFormat.format(toNumeric(value));
+    }
+    function percent(value) {
+        if (isMissing(value))
+            return null;
+        return percentFormat.format(toNumeric(value));
+    }
+    function currency(value, code, format = "currency") {
+        if (isMissing(value))
+            return null;
+        return moneyFormat(code, format).format(toNumeric(value));
+    }
+    function relativeTime(value, now) {
+        if (isMissing(value))
+            return null;
+        const from = now === undefined ? Date.now() : toDate(now).getTime();
+        const seconds = (toDate(value).getTime() - from) / 1000;
+        const [unit, size] = RELATIVE_UNITS.find(([, span]) => Math.abs(seconds) >= span) ?? SECOND;
+        // Truncated, never rounded: an event 90 seconds old is "1 minute ago", not "2 minutes ago".
+        // Rounding up would also push 59.5 minutes into "60 minutes ago", a phrase no unit owns.
+        return relativeTimeFormat.format(Math.trunc(seconds / size), unit);
+    }
+    return { date, datetime, number, percent, currency, relativeTime };
+};

package/dist/http.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A fetch wrapper, not a query layer. It has no cache, no polling and no request de-duplication:
+ * those belong to whatever the app already uses (TanStack Query, a `load` function, a plain
+ * `$effect`). What it does own is the part every hand-rolled client repeats — joining the base
+ * URL, sending and reading JSON, injecting auth, and turning a failed response into one typed
+ * error the whole app can catch.
+ */
+/** A failed HTTP response, after the body has been read and reduced to a message. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    /** Machine-readable backend error code, when the API sent one. */
+    readonly code: string | undefined;
+    constructor(status: number, message: string, code?: string);
+}
+/**
+ * The token for the `Authorization: Bearer` header. Async because the real sources are async:
+ * Supabase, Auth0 and Firebase all refresh an expired token inside this call.
+ */
+export type AuthTokenSource = () => string | Promise<string>;
+/**
+ * Turns a failed response's parsed body into the message a user reads. The one genuinely
+ * app-specific piece: `{ detail }`, `{ error }` and `{ errors: [...] }` are all conventions, not
+ * standards, and localizing off an error code lives here too. Returning an empty string falls
+ * back to the built-in extraction.
+ */
+export type ErrorMessageParser = (status: number, body: unknown) => string;
+export interface HttpClientOptions {
+    /** Prefix for every path: an absolute URL, or a same-origin prefix such as `/api`. */
+    baseUrl: string;
+    /** `"include"` is the session-cookie case, where the browser holds the credential. */
+    credentials?: RequestCredentials;
+    auth?: AuthTokenSource;
+    parseError?: ErrorMessageParser;
+}
+export interface HttpClient {
+    get: <T = unknown>(path: string) => Promise<T>;
+    post: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+    put: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+    patch: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+    del: <T = unknown>(path: string) => Promise<T>;
+}
+/**
+ * Build a client bound to one API.
+ *
+ * ```ts
+ * // Session cookie, same-origin FastAPI behind a proxy.
+ * const api = createHttpClient({ baseUrl: "/api", credentials: "include" });
+ *
+ * // Bearer token from an async session, separate origin. `apiUrl` comes from whatever config
+ * // module the app already has: this package reads no environment of its own.
+ * const api = createHttpClient({
+ *   baseUrl: apiUrl,
+ *   auth: async () => (await supabase.auth.getSession()).data.session?.access_token ?? "",
+ * });
+ * ```
+ */
+export declare const createHttpClient: ({ baseUrl, credentials, auth, parseError, }: HttpClientOptions) => HttpClient;
+/**
+ * Message of a caught value. A `catch` binding is `unknown`, and narrowing it once here beats
+ * repeating the check at every call site; the `String(e)` fallback means a stray non-`Error`
+ * still reaches the user as text instead of `undefined`.
+ */
+export declare const errorMessage: (error: unknown) => string;
+/**
+ * HTTP status of a caught value, or `0` for anything that did not come from the API — lets a
+ * caller special-case 403 or 404 without an `instanceof` dance.
+ */
+export declare const errorStatus: (error: unknown) => number;

package/dist/http.js

@@ -0,0 +1,138 @@
+/**
+ * A fetch wrapper, not a query layer. It has no cache, no polling and no request de-duplication:
+ * those belong to whatever the app already uses (TanStack Query, a `load` function, a plain
+ * `$effect`). What it does own is the part every hand-rolled client repeats — joining the base
+ * URL, sending and reading JSON, injecting auth, and turning a failed response into one typed
+ * error the whole app can catch.
+ */
+/** A failed HTTP response, after the body has been read and reduced to a message. */
+export class ApiError extends Error {
+    status;
+    /** Machine-readable backend error code, when the API sent one. */
+    code;
+    constructor(status, message, code) {
+        super(message);
+        // Subclass names are erased by most bundlers' minifiers, and this one shows up in logs.
+        this.name = "ApiError";
+        this.status = status;
+        this.code = code;
+    }
+}
+const joinUrl = (baseUrl, path) => {
+    const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    return path.startsWith("/") ? `${base}${path}` : `${base}/${path}`;
+};
+const nonEmpty = (value) => {
+    const trimmed = value?.trim();
+    return trimmed === "" ? undefined : trimmed;
+};
+const asRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+/**
+ * Best-effort message from an error body, walking the shapes the two reference backends produce:
+ * a bare string, `{ detail }` as a string or as a `{ code, message }` object, FastAPI's 422 list
+ * of `{ msg }`, and Go's `{ error }`. Anything it cannot read falls through to the status text,
+ * which is why an app with its own envelope supplies `parseError` instead of extending this.
+ */
+const extractMessage = (body) => {
+    if (typeof body === "string")
+        return nonEmpty(body);
+    if (Array.isArray(body))
+        return nonEmpty(body.map((entry) => extractMessage(entry) ?? "").join("; "));
+    const record = asRecord(body);
+    if (!record)
+        return undefined;
+    for (const key of ["message", "msg", "detail", "error"]) {
+        const found = extractMessage(record[key]);
+        if (found)
+            return found;
+    }
+    return undefined;
+};
+const extractCode = (body) => {
+    const record = asRecord(body);
+    const code = asRecord(record?.detail)?.code ?? record?.code;
+    return typeof code === "string" ? nonEmpty(code) : undefined;
+};
+/**
+ * Build a client bound to one API.
+ *
+ * ```ts
+ * // Session cookie, same-origin FastAPI behind a proxy.
+ * const api = createHttpClient({ baseUrl: "/api", credentials: "include" });
+ *
+ * // Bearer token from an async session, separate origin. `apiUrl` comes from whatever config
+ * // module the app already has: this package reads no environment of its own.
+ * const api = createHttpClient({
+ *   baseUrl: apiUrl,
+ *   auth: async () => (await supabase.auth.getSession()).data.session?.access_token ?? "",
+ * });
+ * ```
+ */
+export const createHttpClient = ({ baseUrl, credentials, auth, parseError, }) => {
+    const request = async (method, path, body) => {
+        const headers = {};
+        // GET and DELETE carry no body, and a `Content-Type` on them makes some CORS setups
+        // preflight a request that would otherwise be simple.
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (auth) {
+            const token = await auth();
+            // An empty token means "not signed in yet": sending `Bearer ` would turn a 401 the app can
+            // reason about into a malformed-header 400 from the gateway.
+            if (token)
+                headers.Authorization = `Bearer ${token}`;
+        }
+        const response = await fetch(joinUrl(baseUrl, path), {
+            method,
+            headers,
+            credentials,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        // Read as text first: 204 and most DELETEs answer with nothing at all, and `response.json()`
+        // throws on an empty body. A non-JSON body (an HTML error page from a proxy) is kept as the
+        // string it is, so the message extraction below still has something to show.
+        const text = await response.text();
+        let parsed = undefined;
+        if (text)
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        if (!response.ok) {
+            const message = nonEmpty(parseError?.(response.status, parsed)) ??
+                extractMessage(parsed) ??
+                nonEmpty(response.statusText) ??
+                `HTTP ${response.status}`;
+            throw new ApiError(response.status, message, extractCode(parsed));
+        }
+        // `undefined` for an empty body, never `null`: JSON `null` is a value a server can legitimately
+        // send, and collapsing the two would hide the difference from the caller's type.
+        return parsed;
+    };
+    // `body` is `unknown` rather than a structural JSON type on purpose: a TypeScript interface has
+    // no implicit index signature, so the app's own DTO interfaces would fail to satisfy one.
+    // A body always goes out, even when the caller passes none — a bodyless POST is a 422 against a
+    // FastAPI endpoint that declares a model, and `{}` is the harmless stand-in both references use.
+    return {
+        get: (path) => request("GET", path),
+        post: (path, body) => request("POST", path, body ?? {}),
+        put: (path, body) => request("PUT", path, body ?? {}),
+        patch: (path, body) => request("PATCH", path, body ?? {}),
+        del: (path) => request("DELETE", path),
+    };
+};
+/**
+ * Message of a caught value. A `catch` binding is `unknown`, and narrowing it once here beats
+ * repeating the check at every call site; the `String(e)` fallback means a stray non-`Error`
+ * still reaches the user as text instead of `undefined`.
+ */
+export const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * HTTP status of a caught value, or `0` for anything that did not come from the API — lets a
+ * caller special-case 403 or 404 without an `instanceof` dance.
+ */
+export const errorStatus = (error) => error instanceof ApiError ? error.status : 0;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The published version of this package.
+ *
+ * Declared as a literal instead of being read back from `package.json`: the packaged output has
+ * no portable way to import its own manifest, and a consumer that only wants to log a version
+ * should not have to bundle one. `version.spec.ts` fails when this drifts from the manifest.
+ */
+export declare const LIBRARY_VERSION = "0.3.0";
+export { AsyncAction, type AsyncActionStatus, type AsyncFn } from "./async-action.svelte.js";
+export { reportError, setErrorReporter, type ErrorReporter } from "./error.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * The published version of this package.
+ *
+ * Declared as a literal instead of being read back from `package.json`: the packaged output has
+ * no portable way to import its own manifest, and a consumer that only wants to log a version
+ * should not have to bundle one. `version.spec.ts` fails when this drifts from the manifest.
+ */
+export const LIBRARY_VERSION = "0.3.0";
+// The root entry carries only what is not tied to one area: the error channel an app installs
+// once, and the async state machine the components are built on. Everything visual is reached
+// through a subpath — `/theme`, `/attachments`, `/components`, `/toast` — so importing a button
+// never drags the toast queue into the bundle.
+export { AsyncAction } from "./async-action.svelte.js";
+export { reportError, setErrorReporter } from "./error.js";

package/dist/routing.svelte.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Everything a dynamic title is allowed to depend on.
+ *
+ * Kept as an object rather than a positional argument so a later addition — the query string,
+ * say — is not a breaking change for every title function an app already wrote.
+ */
+export interface TitleContext {
+    /** Params of the current match, already decoded by SvelteKit. */
+    params: Record<string, string>;
+}
+/**
+ * What the app attaches to one SvelteKit route id.
+ *
+ * There is no `children` field and there never will be: the tree is the filesystem, and
+ * SvelteKit has already matched it by the time this map is read. Re-declaring the hierarchy here
+ * is exactly the duplication the pattern exists to remove.
+ *
+ * An entry without a `title` is plumbing — a segment that has to exist so its descendants can
+ * resolve, but that no user should ever see. It still travels through `matched` and `children`
+ * carrying its `requiredRoles`; renderers drop it by testing `meta.title`.
+ */
+export interface RouteMeta {
+    title?: string | ((context: TitleContext) => string);
+    /** Icon class for nav chrome. The library never parses it — it is handed straight to markup. */
+    icon?: string;
+    /** Flat role names. Whoever owns the user context decides what a role means. */
+    requiredRoles?: string[];
+}
+/**
+ * The config an app hands to {@link RoutingContext}.
+ *
+ * ```ts
+ * import type { RouteId } from "$app/types";
+ * import type { RoutingConfig } from "@viniaraujo68/plinth/routing";
+ *
+ * export const routes: RoutingConfig<RouteId> = {
+ *   meta: { "/": { title: "Home" }, "/orders": { title: "Orders" } },
+ *   pages: import.meta.glob("/src/routes/**\/+page.svelte"),
+ * };
+ * ```
+ */
+export interface RoutingConfig<Id extends string = string> {
+    /**
+     * Presentation and access data per route id.
+     *
+     * Key it with `RouteId` from `$app/types` and a renamed or deleted route becomes a compile
+     * error instead of a silently missing crumb.
+     *
+     * Two structural facts are read back out of this object rather than declared twice: a route
+     * id spells its own ancestry in its segments, and key insertion order — which the language
+     * guarantees for non-numeric string keys — is sibling order. That is all `children` needs.
+     */
+    meta: Partial<Record<Id, RouteMeta>>;
+    /**
+     * The raw result of `import.meta.glob("/src/routes/**\/+page.svelte")`, whose keys say which
+     * ids answer a direct visit.
+     *
+     * It has to be spelled out at the app's own source location: Vite rewrites the literal call
+     * site at build time, so a library that tried to issue the glob on the app's behalf would
+     * glob its own `dist` and find nothing. The values are never read — only the keys — which is
+     * why the type is `unknown` and why a lazy glob costs nothing.
+     */
+    pages: Record<string, unknown>;
+}
+/**
+ * One route id resolved through the meta map — the single shape every navigational consumer
+ * reads, whether it came from `matched` or from `children`.
+ */
+export interface ResolvedRoute {
+    /** The route id, still in bracket notation. */
+    routeId: string;
+    /** Resolved title, or `""` for a plumbing entry. */
+    label: string;
+    /** Concrete pathname, params substituted and group segments dropped. Carries no base path —
+     * put it through {@link resolvePathname} to get an href. */
+    pathname: string;
+    /** Whether a real `+page.svelte` backs this id. An entry without it is a heading, not a link. */
+    navigable: boolean;
+    meta: RouteMeta;
+}
+/**
+ * The reactive match {@link RoutingContext} projects.
+ *
+ * Structural on purpose. The library never imports `$app/state`, so it never assumes a
+ * SvelteKit runtime: an app passes `page`, and a test passes any object with the same three
+ * fields. That is the whole seam.
+ */
+export interface RoutingSource {
+    readonly route: {
+        readonly id: string | null;
+    };
+    readonly params: Record<string, string>;
+    readonly url: URL;
+}
+/**
+ * Reactive view over SvelteKit's own match, projected through a flat metadata map.
+ *
+ * It resolves nothing by itself — no URL parsing, no pattern matching, no ranking. SvelteKit
+ * already decided which route the user is on; this class only answers "what does the app want
+ * displayed and gated for that decision, and for its ancestors".
+ */
+export declare class RoutingContext<Id extends string = string> {
+    private readonly config;
+    /** Every id with a real page, computed once — the filesystem cannot change while the tab is
+     * open, so this is the one part of the class that has no reason to be reactive. */
+    private readonly navigableIds;
+    /** The current URL, straight off the source. Nav chrome reads it for things the route id does
+     * not carry, such as the query string or the host. */
+    url: URL;
+    /** The matched route id, or `null` when nothing matched — a 404, or the first paint of an
+     * error page. */
+    routeId: string | null;
+    /** Decoded params of the current match. */
+    params: Record<string, string>;
+    /**
+     * The declared prefixes of the current match, root first.
+     *
+     * Every ancestor that has a meta entry is here, plumbing included, so a gate declared halfway
+     * up the tree stays reachable (`matched.findLast((r) => r.meta.requiredRoles)`). Prefixes with
+     * no entry contribute nothing and are skipped rather than faked. Empty when `routeId` is null.
+     */
+    matched: ResolvedRoute[];
+    constructor(config: RoutingConfig<Id>, source: RoutingSource);
+    /**
+     * The direct declared children of a route id, in the order the meta map declares them.
+     *
+     * Plumbing children come back too — a caller may want to recurse past them or read their
+     * gates — so a renderer that only wants visible entries filters on `meta.title`. Labels and
+     * pathnames resolve against the current params, which only shows up when a child is itself a
+     * capture and the user is standing on it.
+     */
+    children(routeId: string): ResolvedRoute[];
+    /**
+     * The title of any declared route id, `""` when it is plumbing or unknown.
+     *
+     * A dynamic title is evaluated against the params of the *current* match, so asking about a
+     * capture route the user is not on hands it empty strings. Reading the label off `matched` or
+     * `children` is the normal path; this is for the odd one-off lookup.
+     */
+    label(routeId: Id): string;
+    /** The single place a runtime string is narrowed to the app's route-id union. Every lookup in
+     * this class goes through it so the cast exists once instead of at four call sites. */
+    private metaFor;
+    private resolve;
+    /**
+     * Warn once, in dev, about the two ways the map and the filesystem drift apart.
+     *
+     * Typed keys already catch the common case at compile time. What they cannot catch is a page
+     * added without a meta entry, or a plumbing entry left behind after the last route under it
+     * was deleted — neither is a type error, and both are invisible until a crumb or a nav item
+     * quietly stops appearing.
+     */
+    private reportDrift;
+}
+/**
+ * Turn a pathname computed at runtime into an href that respects the configured base path.
+ *
+ * `$app/paths`' `resolve` is typed as one overload per literal route in the app, so no value
+ * produced at runtime can ever satisfy it. This is where that gets acknowledged, once, instead
+ * of a cast at every nav item and crumb.
+ */
+export declare const resolvePathname: (pathname: string) => string;
+export declare const getRoutingContext: () => RoutingContext<string>, setRoutingContext: (context: RoutingContext<string>) => RoutingContext<string>;
+/**
+ * A copy of `url` with some search parameters set and others removed — `null` or `undefined`
+ * removes. It never edits the URL it was given, which is usually the page store's own and is read
+ * by everything else on the page.
+ */
+export declare const withSearchParams: (url: URL, updates: Record<string, string | null | undefined>) => URL;