@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.3

package/dist/lib/pagination/http.js

@@ -0,0 +1,48 @@
+/**
+ * Pagination headers shared by endpoint helpers and typed HTTP clients.
+ *
+ * Collection bodies stay canonical (`{ results }`). Metadata travels in
+ * headers so storage/cloud-api consumers do not need a second wire envelope.
+ */
+export const PAGINATION_HEADERS = {
+    page: 'x-page',
+    pageSize: 'x-per-page',
+    total: 'x-total-count',
+    totalPages: 'x-total-pages',
+    link: 'link'
+};
+function readNonNegativeInteger(headers, name) {
+    const raw = headers.get(name);
+    if (raw === null || raw.trim() === '')
+        return undefined;
+    const value = Number(raw);
+    return Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+function hasLinkRelation(value, relation) {
+    if (!value)
+        return false;
+    return value
+        .split(',')
+        .some((part) => new RegExp(`;\\s*rel=(?:"${relation}"|${relation})(?:\\s*;|\\s*$)`, 'i').test(part));
+}
+/**
+ * Read a paginated collection response without coupling the client to a custom
+ * JSON envelope. Missing headers degrade to the supplied page and result count,
+ * which keeps rolling deploys compatible.
+ */
+export function readPaginationHeaders(headers, fallback) {
+    const page = Math.max(1, readNonNegativeInteger(headers, PAGINATION_HEADERS.page) ?? fallback.page);
+    const pageSize = Math.max(1, readNonNegativeInteger(headers, PAGINATION_HEADERS.pageSize) ?? fallback.pageSize);
+    const total = readNonNegativeInteger(headers, PAGINATION_HEADERS.total) ?? fallback.total ?? 0;
+    const totalPages = readNonNegativeInteger(headers, PAGINATION_HEADERS.totalPages) ??
+        (total === 0 ? 0 : Math.ceil(total / pageSize));
+    const links = headers.get(PAGINATION_HEADERS.link);
+    return {
+        page,
+        pageSize,
+        total,
+        totalPages,
+        hasNext: hasLinkRelation(links, 'next') || page < totalPages,
+        hasPrev: hasLinkRelation(links, 'prev') || page > 1
+    };
+}

package/dist/lib/pagination/index.d.ts

@@ -0,0 +1,2 @@
+export { paginationSchema, paginationResultSchema, type PaginationParams, type PaginationResult, type PaginationMeta, type PaginatedData, type PaginationHeaderFallback } from './schemas/common.ts';
+export { PAGINATION_HEADERS, readPaginationHeaders } from './http.ts';

package/dist/lib/pagination/index.js

@@ -0,0 +1,3 @@
+// Client-safe barrel: export schemas and types only
+export { paginationSchema, paginationResultSchema } from "./schemas/common.js";
+export { PAGINATION_HEADERS, readPaginationHeaders } from "./http.js";

package/dist/lib/pagination/schemas/common.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pagination Schemas
+ *
+ * Kit pagination schemas and types.
+ *
+ * @example
+ * ```typescript
+ * import { paginationSchema, type PaginationParams } from '../../index.ts/pagination';
+ * ```
+ */
+import * as z from 'zod/v4';
+export declare const paginationSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const paginationResultSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodUnknown>;
+    page: z.ZodNumber;
+    pageSize: z.ZodNumber;
+    total: z.ZodOptional<z.ZodNumber>;
+    totalPages: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PaginationParams = z.infer<typeof paginationSchema>;
+export type PaginationResult<T = unknown> = z.infer<typeof paginationResultSchema> & {
+    results: T[];
+};
+export type PaginatedData<T> = {
+    items: T[];
+    pagination: PaginationMeta;
+};
+export interface PaginationMeta {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+    hasNext?: boolean;
+    hasPrev?: boolean;
+}
+export interface PaginationHeaderFallback {
+    page: number;
+    pageSize: number;
+    /** Used when an older endpoint has not started emitting pagination headers. */
+    total?: number;
+}
+export interface PaginationLimits {
+    /** Smallest accepted page size. Defaults to 1. */
+    minPageSize?: number;
+    /** Largest accepted page size. Defaults to 100. */
+    maxPageSize?: number;
+}
+export interface ParameterBudgetOptions {
+    /** Provider bind-variable ceiling. Cloudflare D1 currently allows 100. */
+    maxParameters?: number;
+    /** Bind variables used by predicates outside the repeated value clause. */
+    reservedParameters?: number;
+    /** Bind variables emitted for each value. Defaults to one. */
+    parametersPerValue?: number;
+}

package/dist/lib/pagination/schemas/common.js

@@ -0,0 +1,22 @@
+/**
+ * Pagination Schemas
+ *
+ * Kit pagination schemas and types.
+ *
+ * @example
+ * ```typescript
+ * import { paginationSchema, type PaginationParams } from '../../index.ts/pagination';
+ * ```
+ */
+import * as z from 'zod/v4';
+export const paginationSchema = z.object({
+    page: z.coerce.number().int().min(1).default(1),
+    pageSize: z.coerce.number().int().min(1).max(100).default(20)
+});
+export const paginationResultSchema = z.object({
+    results: z.array(z.unknown()),
+    page: z.number(),
+    pageSize: z.number(),
+    total: z.number().optional(),
+    totalPages: z.number().optional()
+});

package/dist/lib/pagination/server/index.d.ts

@@ -0,0 +1,48 @@
+import { type SQL, type Table } from 'drizzle-orm';
+import type { PaginatedData, PaginationLimits, PaginationMeta, PaginationParams, ParameterBudgetOptions } from '../schemas/common.ts';
+export { type PaginatedData, type PaginationHeaderFallback, type PaginationLimits, type PaginationMeta, type PaginationParams, type ParameterBudgetOptions } from '../schemas/common.ts';
+export { PAGINATION_HEADERS, readPaginationHeaders } from '../http.ts';
+/** Minimal interface for a Drizzle-like query builder that supports limit/offset chaining */
+export interface PaginatableQuery {
+    limit(n: number): this;
+    offset(n: number): this;
+}
+/** Thenable count query used by pagination helpers. */
+export interface CountQuery extends PromiseLike<Array<{
+    count: number;
+}>> {
+    where(condition: SQL): CountQuery;
+}
+/** Minimal interface for a Drizzle-like database instance used in pagination */
+export interface PaginatableDB<T extends Table = Table> {
+    select(selection?: {
+        count: SQL<number>;
+    }): {
+        from(table: T): CountQuery;
+    };
+}
+export declare function getPaginationParams(url: URL, defaults?: Partial<PaginationParams>, limits?: PaginationLimits): PaginationParams;
+export declare function calculatePagination(total: number, params: PaginationParams): PaginationMeta;
+export declare function withPagination<T extends PaginatableQuery>(query: T, params: PaginationParams): T;
+export declare function getPaginatedData<T>(db: PaginatableDB, query: PaginatableQuery & PromiseLike<T[]>, table: Table, params: PaginationParams, whereCondition?: SQL): Promise<PaginatedData<T>>;
+export declare function buildPaginationUrl(baseUrl: URL, page: number, perPage?: number): string;
+/** Build RFC 8288 navigation links plus explicit count/page headers. */
+export declare function buildPaginationHeaders(url: URL, pagination: PaginationMeta): {
+    "x-page": string;
+    "x-per-page": string;
+    "x-total-count": string;
+    "x-total-pages": string;
+} | {
+    link: string;
+    "x-page": string;
+    "x-per-page": string;
+    "x-total-count": string;
+    "x-total-pages": string;
+};
+/**
+ * Split values so every generated query stays under a provider's bind-variable
+ * ceiling. This is deliberately storage-agnostic: the owning query still
+ * decides which predicates each value expands into.
+ */
+export declare function chunkByParameterBudget<T>(values: readonly T[], options?: ParameterBudgetOptions): T[][];
+export declare function validatePageNumber(page: number, totalPages: number): number;

package/dist/lib/pagination/server/index.js

@@ -0,0 +1,102 @@
+import { sql } from 'drizzle-orm';
+import { PAGINATION_HEADERS } from "../http.js";
+export {} from "../schemas/common.js";
+export { PAGINATION_HEADERS, readPaginationHeaders } from "../http.js";
+export function getPaginationParams(url, defaults, limits) {
+    const pageParam = url.searchParams.get('page') || '1';
+    const perPageParam = url.searchParams.get('perPage') || defaults?.pageSize?.toString() || '20';
+    const minPageSize = Math.max(1, limits?.minPageSize ?? 1);
+    const maxPageSize = Math.max(minPageSize, limits?.maxPageSize ?? 100);
+    const page = Math.max(1, parseInt(pageParam, 10) || 1);
+    const pageSize = Math.min(maxPageSize, Math.max(minPageSize, parseInt(perPageParam, 10) || (defaults?.pageSize ?? 20)));
+    return { page, pageSize };
+}
+export function calculatePagination(total, params) {
+    return {
+        page: params.page,
+        pageSize: params.pageSize,
+        total,
+        totalPages: Math.ceil(total / params.pageSize)
+    };
+}
+export function withPagination(query, params) {
+    const offset = (params.page - 1) * params.pageSize;
+    return query.limit(params.pageSize).offset(offset);
+}
+export async function getPaginatedData(db, query, table, params, whereCondition) {
+    let countQuery = db.select({ count: sql `count(*)` }).from(table);
+    if (whereCondition)
+        countQuery = countQuery.where(whereCondition);
+    const countRows = await countQuery;
+    const total = Number(countRows[0]?.count);
+    if (!Number.isFinite(total)) {
+        throw new Error('pagination count query returned no row');
+    }
+    const items = await withPagination(query, params);
+    return { items, pagination: calculatePagination(total, params) };
+}
+export function buildPaginationUrl(baseUrl, page, perPage) {
+    const url = new URL(baseUrl);
+    url.searchParams.set('page', page.toString());
+    if (perPage)
+        url.searchParams.set('perPage', perPage.toString());
+    return url.pathname + url.search;
+}
+/** Build RFC 8288 navigation links plus explicit count/page headers. */
+export function buildPaginationHeaders(url, pagination) {
+    const links = [];
+    if (pagination.hasPrev ?? pagination.page > 1) {
+        links.push(`<${buildPaginationUrl(url, Math.max(1, pagination.page - 1), pagination.pageSize)}>; rel="prev"`);
+    }
+    if (pagination.hasNext ?? pagination.page < pagination.totalPages) {
+        links.push(`<${buildPaginationUrl(url, pagination.page + 1, pagination.pageSize)}>; rel="next"`);
+    }
+    const headers = {
+        [PAGINATION_HEADERS.page]: String(pagination.page),
+        [PAGINATION_HEADERS.pageSize]: String(pagination.pageSize),
+        [PAGINATION_HEADERS.total]: String(pagination.total),
+        [PAGINATION_HEADERS.totalPages]: String(pagination.totalPages)
+    };
+    return links.length > 0 ? { ...headers, [PAGINATION_HEADERS.link]: links.join(', ') } : headers;
+}
+/**
+ * Split values so every generated query stays under a provider's bind-variable
+ * ceiling. This is deliberately storage-agnostic: the owning query still
+ * decides which predicates each value expands into.
+ */
+export function chunkByParameterBudget(values, options = {}) {
+    const maxParameters = Math.floor(options.maxParameters ?? 100);
+    const reservedParameters = Math.floor(options.reservedParameters ?? 0);
+    const parametersPerValue = Math.floor(options.parametersPerValue ?? 1);
+    const available = maxParameters - reservedParameters;
+    if (!Number.isFinite(maxParameters))
+        throw new RangeError('maxParameters must be finite');
+    if (!Number.isFinite(reservedParameters))
+        throw new RangeError('reservedParameters must be finite');
+    if (!Number.isFinite(parametersPerValue))
+        throw new RangeError('parametersPerValue must be finite');
+    if (maxParameters < 1)
+        throw new RangeError('maxParameters must be at least 1');
+    if (reservedParameters < 0)
+        throw new RangeError('reservedParameters cannot be negative');
+    if (parametersPerValue < 1)
+        throw new RangeError('parametersPerValue must be at least 1');
+    if (available < parametersPerValue) {
+        throw new RangeError('parameter budget has no room for a value');
+    }
+    const size = Math.floor(available / parametersPerValue);
+    const chunks = [];
+    for (let index = 0; index < values.length; index += size) {
+        chunks.push(values.slice(index, index + size));
+    }
+    return chunks;
+}
+export function validatePageNumber(page, totalPages) {
+    if (page < 1)
+        return 1;
+    if (totalPages <= 0)
+        return 1;
+    if (page > totalPages)
+        return totalPages;
+    return page;
+}

package/dist/lib/plugins/acme/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ACME Challenge Plugin
+ *
+ * Handles ACME HTTP-01 challenges for Let's Encrypt certificate issuance.
+ * Serves challenge responses at /.well-known/acme-challenge/{token}
+ *
+ * This plugin runs with priority 0 (before auth/security) since ACME
+ * challenges cannot require authentication.
+ */
+import type { VibesPlugin } from '../../types/plugin';
+import type { ACMEPluginConfig } from './types';
+export declare function createACMEPlugin(config: ACMEPluginConfig): VibesPlugin;

package/dist/lib/plugins/acme/index.js

@@ -0,0 +1,68 @@
+/**
+ * ACME Challenge Plugin
+ *
+ * Handles ACME HTTP-01 challenges for Let's Encrypt certificate issuance.
+ * Serves challenge responses at /.well-known/acme-challenge/{token}
+ *
+ * This plugin runs with priority 0 (before auth/security) since ACME
+ * challenges cannot require authentication.
+ */
+import { kitLogger } from '../../kit-logger';
+import { settle } from "../../attempt.js";
+import { failureClass } from "../../failure-class.js";
+const logger = kitLogger('vibeskit-acme');
+export function createACMEPlugin(config) {
+    return {
+        name: 'acme',
+        version: '1.0.0',
+        description: 'ACME HTTP-01 challenge handler for SSL certificate issuance',
+        priority: 0, // Run first - before auth
+        createHandle() {
+            if (!config.enabled) {
+                // Return passthrough if disabled
+                return ({ event, resolve }) => resolve(event);
+            }
+            return async ({ event, resolve }) => {
+                const pathname = event.url.pathname;
+                // Match ACME challenge pattern
+                const match = pathname.match(/^\/.well-known\/acme-challenge\/(.+)$/);
+                if (!match) {
+                    return resolve(event);
+                }
+                const token = match[1];
+                // Log challenge request if configured
+                if (config.onChallengeRequested) {
+                    const notification = await settle(() => config.onChallengeRequested?.(token, new Date()));
+                    if (!notification.ok)
+                        logger.error('Failed to log challenge request', {
+                            failureClass: failureClass(notification.error)
+                        });
+                }
+                // Get challenge response
+                const challenge = await settle(() => config.getChallenge(token));
+                if (!challenge.ok) {
+                    logger.error('Error retrieving challenge', {
+                        failureClass: failureClass(challenge.error)
+                    });
+                    return new Response('Internal Server Error', {
+                        status: 500,
+                        headers: { 'Content-Type': 'text/plain' }
+                    });
+                }
+                if (!challenge.value) {
+                    return new Response('Not Found', {
+                        status: 404,
+                        headers: { 'Content-Type': 'text/plain' }
+                    });
+                }
+                return new Response(challenge.value, {
+                    status: 200,
+                    headers: {
+                        'Content-Type': 'text/plain',
+                        'Cache-Control': 'no-cache, no-store, must-revalidate'
+                    }
+                });
+            };
+        }
+    };
+}

package/dist/lib/plugins/acme/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ACME plugin types
+ */
+export interface ACMEPluginConfig {
+    /** Enable ACME challenge handler */
+    enabled: boolean;
+    /**
+     * Get challenge response for a given token
+     * Should return the key authorization string or null if not found
+     */
+    getChallenge: (token: string) => Promise<string | null>;
+    /**
+     * Called when a challenge is requested
+     * Use for logging/auditing
+     */
+    onChallengeRequested?: (token: string, timestamp: Date) => void | Promise<void>;
+    /**
+     * Called when a challenge is successfully verified
+     * Use for logging/auditing
+     */
+    onChallengeVerified?: (token: string, domain: string) => void | Promise<void>;
+}

package/dist/lib/plugins/acme/types.js

@@ -0,0 +1,4 @@
+/**
+ * ACME plugin types
+ */
+export {};

package/dist/lib/plugins/hostname/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hostname Routing Plugin
+ *
+ * Resolves custom hostnames to project/account context.
+ * Injects resolved context into event.locals.hostname for use in routing.
+ *
+ * This plugin runs with priority 10 (after ACME, before auth) so that
+ * hostname context is available for authentication/authorization.
+ */
+import type { VibesPlugin } from '../../types/plugin';
+import type { HostnamePluginConfig } from './types';
+export declare function createHostnamePlugin(config: HostnamePluginConfig): VibesPlugin;

package/dist/lib/plugins/hostname/index.js

@@ -0,0 +1,62 @@
+/**
+ * Hostname Routing Plugin
+ *
+ * Resolves custom hostnames to project/account context.
+ * Injects resolved context into event.locals.hostname for use in routing.
+ *
+ * This plugin runs with priority 10 (after ACME, before auth) so that
+ * hostname context is available for authentication/authorization.
+ */
+import { minimatch } from 'minimatch';
+import { kitLogger } from '../../kit-logger';
+import { asVibesKitLocals } from '../../server/locals.js';
+import { settle } from "../../attempt.js";
+import { failureClass } from "../../failure-class.js";
+const logger = kitLogger('vibeskit-hostname');
+export function createHostnamePlugin(config) {
+    return {
+        name: 'hostname',
+        version: '1.0.0',
+        description: 'Custom hostname routing and resolution',
+        priority: 10, // Run after ACME, before auth
+        createHandle() {
+            if (!config.enabled) {
+                // Return passthrough if disabled
+                return ({ event, resolve }) => resolve(event);
+            }
+            const pathPattern = config.pathPattern || '/**';
+            return async ({ event, resolve }) => {
+                const pathname = event.url.pathname;
+                // Check if path matches pattern
+                if (!minimatch(pathname, pathPattern)) {
+                    return resolve(event);
+                }
+                // Extract hostname (strip port if present)
+                const hostHeader = event.request.headers.get('host');
+                if (!hostHeader) {
+                    return resolve(event);
+                }
+                const hostname = hostHeader.split(':')[0];
+                // Resolve hostname to context
+                const resolved = await settle(() => config.resolveHostname(hostname));
+                if (!resolved.ok) {
+                    logger.error('Error resolving hostname', { failureClass: failureClass(resolved.error) });
+                    return resolve(event);
+                }
+                const context = resolved.value;
+                if (context) {
+                    const locals = asVibesKitLocals(event.locals);
+                    locals.hostname = context;
+                    if (config.onHostnameResolved) {
+                        const notification = await settle(() => config.onHostnameResolved?.(context));
+                        if (!notification.ok)
+                            logger.error('Failed to log hostname resolution', {
+                                failureClass: failureClass(notification.error)
+                            });
+                    }
+                }
+                return resolve(event);
+            };
+        }
+    };
+}

package/dist/lib/plugins/hostname/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Hostname routing plugin types
+ */
+export interface HostnamePluginConfig {
+    /** Enable hostname routing */
+    enabled: boolean;
+    /**
+     * Resolve hostname to routing context
+     * Should return null if hostname is not recognized
+     */
+    resolveHostname: (hostname: string) => Promise<HostnameContext | null>;
+    /**
+     * Optional path pattern filter
+     * Only apply hostname routing to matching paths
+     * Default: '/**' (all routes)
+     *
+     * Examples:
+     * - '/**' - All routes
+     * - '/' - Root only
+     * - '/!api/**' - Exclude API routes
+     */
+    pathPattern?: string;
+    /**
+     * Called when a hostname is successfully resolved
+     * Use for logging/analytics
+     */
+    onHostnameResolved?: (context: HostnameContext) => void | Promise<void>;
+}
+/**
+ * Hostname context injected into event.locals.hostname
+ */
+export interface HostnameContext {
+    /** The resolved domain */
+    domain: string;
+    /** Project ID (if hostname maps to a project) */
+    projectId?: string | null;
+    /** Project slug (if hostname maps to a project) */
+    projectSlug?: string;
+    /** Project display name */
+    projectName?: string;
+    /** Owning user or organization ID */
+    ownerId?: string;
+    /** Owning resource type */
+    ownerType?: string;
+    /** Deployment target for this hostname */
+    deployTarget?: 'kubernetes' | 'cloudflare';
+    /** Account/organization slug */
+    accountSlug?: string;
+    /** Additional custom data */
+    [key: string]: string | null | undefined;
+}

package/dist/lib/plugins/hostname/types.js

@@ -0,0 +1,4 @@
+/**
+ * Hostname routing plugin types
+ */
+export {};

package/dist/lib/preferences/capture-preference-storage.d.ts

@@ -0,0 +1,3 @@
+import { type PreferenceStorage } from './preference-storage.ts';
+export type PreferenceStorageResolver = () => Promise<PreferenceStorage | undefined>;
+export declare function capturePreferenceStorage(): PreferenceStorageResolver;

package/dist/lib/preferences/capture-preference-storage.js

@@ -0,0 +1,21 @@
+/**
+ * Component-side access to the runtime's preference storage. Call
+ * `capturePreferenceStorage()` during component initialization (Svelte context
+ * is readable only then); await the returned resolver later, from `onMount`.
+ * The resolver answers `undefined` when no runtime store is provided, the
+ * runtime will not load, or it composes no browser host; no fallback runtime
+ * is created.
+ */
+import { peekRuntimeSvelteContext } from '@vibesdotdev/surface-sveltekit/svelte/state';
+import { settle, settleNow } from "../attempt.js";
+import { tryResolvePreferenceStorage } from "./preference-storage.js";
+export function capturePreferenceStorage() {
+    const context = settleNow(() => peekRuntimeSvelteContext());
+    const store = context.ok ? context.value : undefined;
+    return async () => {
+        if (!store)
+            return undefined;
+        const loaded = await settle(() => store.load());
+        return loaded.ok ? tryResolvePreferenceStorage(loaded.value) : undefined;
+    };
+}

package/dist/lib/preferences/preference-storage.d.ts

@@ -0,0 +1,44 @@
+/**
+ * UI preference persistence owned by the runtime. The storage is the handed
+ * runtime's browser host (`runtime/browser-host`), resolved through the kernel
+ * context kind; Kit never reaches a browser storage global itself. Every
+ * preference declares its key, schema and default here, so an absent, blocked
+ * or malformed value reads as the declared default.
+ */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import * as z from 'zod/v4';
+/** Storage shaped like the runtime browser host's (`RuntimeBrowserHost.storage`). */
+export interface PreferenceStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** A persisted preference: where it lives, what it may hold, and what it reads as when unset. */
+export interface PreferenceDefinition<T> {
+    readonly key: string;
+    readonly schema: z.ZodType<T>;
+    readonly default: T;
+}
+/** What a read found. `value` is always usable: the stored value, else the declared default. */
+export interface PreferenceRead<T> {
+    readonly status: 'found' | 'missing' | 'malformed' | 'blocked' | 'unavailable';
+    readonly value: T;
+}
+export declare function definePreference<T>(definition: PreferenceDefinition<T>): PreferenceDefinition<T>;
+/** Sidebar navigation expansion: group/item key to open state. Unset means no explicit toggle. */
+export declare const ExpandedStateSchema: z.ZodRecord<z.ZodString, z.ZodBoolean>;
+export declare function sidebarExpandedPreference(storageKey: string): PreferenceDefinition<Record<string, boolean>>;
+/** One collapsible navigation section's open state; unset reads as the section's declared default. */
+export declare function sectionOpenPreference(sectionKey: string, defaultOpen: boolean): PreferenceDefinition<boolean>;
+/** Read a preference as JSON through `storage`; `undefined` storage is an unavailable runtime. */
+export declare function readPreference<T>(storage: PreferenceStorage | undefined, definition: PreferenceDefinition<T>): PreferenceRead<T>;
+/** Write a preference as JSON; answers whether it reached storage. */
+export declare function writePreference<T>(storage: PreferenceStorage | undefined, definition: PreferenceDefinition<T>, value: T): 'stored' | 'blocked' | 'unavailable';
+/**
+ * The runtime's preference storage. Refuses (`browser-host-unavailable`)
+ * when the runtime composes no browser host; callers treat that as
+ * "no storage" and keep working from cookies and declared defaults.
+ */
+export declare function resolvePreferenceStorage(runtime: Pick<RuntimeRef, 'hasKind' | 'query'>): Promise<PreferenceStorage>;
+/** `resolvePreferenceStorage`, answering `undefined` where the runtime has no usable browser host. */
+export declare function tryResolvePreferenceStorage(runtime: Pick<RuntimeRef, 'hasKind' | 'query'>): Promise<PreferenceStorage | undefined>;