@hops-ops/distributed 4.8.0 → 4.9.0

package/dist/sveltekit/lifecycle.js

@@ -0,0 +1,454 @@
+const STATE_ENDPOINT = '/__distributed/lifecycle';
+const CAPSULE_KEY = '@hops-ops/distributed/reload-capsule/v1';
+const GENERATION_META = 'distributed-generation';
+const MAX_CAPSULE_BYTES = 1024 * 1024;
+const MAX_STATE_DEPTH = 32;
+const PARTICIPANT_ID = /^[A-Za-z0-9_-]{16,128}$/;
+const SECRET_KEY = /(?:authorization|cookie|password|secret|token|credential)/i;
+const AUTH_QUERY_KEY = /^(?:code|samlresponse|session|state)$/i;
+const STATE_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const RESTORE_TIMEOUT_MS = 3_000;
+const CAPSULE_MIN_LIFETIME_MS = 30_000;
+// Preparation is followed by a bounded process-readiness transaction. Keep
+// the capsule alive through the CLI's 90-second aggregate readiness budget,
+// restoration, and ordinary browser scheduling delay.
+const CAPSULE_ACTIVATION_GRACE_MS = 120_000;
+/** Validate one explicitly declared application-state partition before capture. */
+export function validateDistributedReloadState(value, path = 'reloadState') {
+    assertSafeSerializable(value, path, 0, new Set(), true);
+    const encoded = JSON.stringify(value);
+    if (new TextEncoder().encode(encoded).length > MAX_CAPSULE_BYTES) {
+        throw new TypeError(`${path} exceeds 1 MiB`);
+    }
+    return value;
+}
+/** Preserve browser location only when it cannot copy an auth callback secret. */
+export function validateDistributedReloadLocation(location) {
+    const parameters = [location.searchParams];
+    if (location.hash.length > 1) {
+        parameters.push(new URLSearchParams(location.hash.slice(1)));
+    }
+    for (const key of parameters.flatMap((candidate) => [...candidate.keys()])) {
+        if (SECRET_KEY.test(key) || AUTH_QUERY_KEY.test(key)) {
+            throw new TypeError(`reload location parameter ${key} is auth-secret-like`);
+        }
+    }
+    return `${location.pathname}${location.search}${location.hash}`;
+}
+/** Register one generated client with the shared browser reload transaction. */
+export function registerDistributedReloadClient(replica, runtime, options) {
+    const state = new Map((options.state ?? []).map((declaration) => {
+        identity(declaration.key, 'reload state key');
+        identity(declaration.fingerprint, 'reload state fingerprint');
+        if (!STATE_KEY.test(declaration.key) || declaration.key.includes('..')) {
+            throw new TypeError('Distributed reload state keys must be distinct portable names');
+        }
+        return [declaration.key, declaration];
+    }));
+    if (state.size !== (options.state ?? []).length) {
+        throw new TypeError('duplicate Distributed reload state declaration');
+    }
+    return distributedReloadLifecycle().register(Object.freeze({
+        key: identity(options.key, 'reload participant key'),
+        prepare() {
+            const application = [...state.values()].map((declaration) => {
+                const value = declaration.capture();
+                validateDistributedReloadState(value, `reloadState.${declaration.key}`);
+                return Object.freeze({
+                    key: declaration.key,
+                    fingerprint: declaration.fingerprint,
+                    value
+                });
+            });
+            const dehydrated = replica.scope === undefined ? undefined : replica.dehydrate();
+            return Object.freeze({
+                ...(dehydrated === undefined ? {} : { replica: dehydrated }),
+                pendingCommandIds: runtime?.pendingCommandIds?.() ?? Object.freeze([]),
+                state: Object.freeze(application)
+            });
+        },
+        async restore(saved, compatible) {
+            // A client-only application learns its replica authority from its first
+            // query. Retain the capsule until that authority exists instead of
+            // treating a skipped compatible hydrate as successful restoration.
+            if (compatible && saved.replica !== undefined && replica.scope === undefined) {
+                return false;
+            }
+            const replicaCaptured = saved.replica !== undefined;
+            let replicaRestored = saved.replica === undefined;
+            if (compatible && saved.replica !== undefined && replica.scope !== undefined) {
+                replicaRestored = replica.hydrate(saved.replica, replica.scope);
+            }
+            for (const candidate of saved.state) {
+                const declaration = state.get(candidate.key);
+                if (declaration?.fingerprint === candidate.fingerprint) {
+                    await declaration.restore(candidate.value);
+                }
+            }
+            if (saved.pendingCommandIds.length > 0) {
+                await options.recoverPendingCommands?.(saved.pendingCommandIds);
+            }
+            window.dispatchEvent(new CustomEvent('distributed:reload-restored', {
+                detail: Object.freeze({
+                    key: options.key,
+                    replicaCaptured,
+                    replicaRestored,
+                    pendingCommandIds: saved.pendingCommandIds
+                })
+            }));
+            return true;
+        }
+    }));
+}
+let sharedLifecycle;
+// Schedule from the completed request, leaving a full idle window between
+// heartbeats. Besides reducing background work, this preserves browser tooling
+// that defines network-idle as 500 ms without an in-flight request.
+const LIFECYCLE_POLL_INTERVAL_MS = 1_000;
+/** Browser singleton used by every generated SvelteKit surface in one page. */
+export function distributedReloadLifecycle() {
+    if (sharedLifecycle === undefined) {
+        try {
+            sharedLifecycle = createDistributedReloadLifecycle();
+        }
+        catch {
+            // Storage and Web Crypto are optional browser capabilities. Losing
+            // them disables coherent reload state transfer, not the application.
+            sharedLifecycle = inertLifecycle();
+        }
+    }
+    return sharedLifecycle;
+}
+function createDistributedReloadLifecycle() {
+    if (typeof window === 'undefined')
+        return inertLifecycle();
+    const participants = new Map();
+    const participantId = browserParticipantId();
+    let blocked = false;
+    let destroyed = false;
+    let preparing;
+    let reloadRequested = false;
+    let loadedGenerationId = documentGenerationId();
+    let timer;
+    let restoration = Promise.resolve();
+    const queueRestoration = (active) => {
+        const requested = restoration.then(() => restoreAvailableParticipants(participants, active));
+        // Keep the queue usable after a storage/restore failure while returning
+        // the real result to the caller that owns this attempt.
+        restoration = requested.catch(() => undefined);
+        return requested;
+    };
+    const poll = async () => {
+        if (destroyed)
+            return;
+        try {
+            const response = await fetch(STATE_ENDPOINT, {
+                headers: { 'x-distributed-participant': participantId },
+                cache: 'no-store',
+                credentials: 'same-origin'
+            });
+            if (response.status === 404) {
+                blocked = false;
+                return;
+            }
+            if (!response.ok)
+                throw new Error(`lifecycle state returned ${response.status}`);
+            const state = parseLifecycleState(await response.json());
+            // The Vite lifecycle integration stamps the generation that served this
+            // document into its HTML. Fall back to the first observed active state for
+            // consumers that mount the lifecycle client without that integration.
+            loadedGenerationId ??= state.active.generationId;
+            if (state.phase === 'preparing' && state.pending !== undefined && state.transitionId !== undefined) {
+                blocked = true;
+                if (preparing !== state.transitionId) {
+                    preparing = state.transitionId;
+                    window.dispatchEvent(new CustomEvent('distributed:reload-preparing', {
+                        detail: Object.freeze({
+                            transitionId: state.transitionId,
+                            fromGenerationId: state.active.generationId,
+                            toGenerationId: state.pending.generationId
+                        })
+                    }));
+                    await prepareReload(state, participantId, participants);
+                }
+                return;
+            }
+            if (state.active.generationId !== loadedGenerationId) {
+                blocked = true;
+                if (!reloadRequested) {
+                    reloadRequested = true;
+                    markCapsuleRestoring();
+                    window.location.reload();
+                }
+                return;
+            }
+            preparing = undefined;
+            blocked = false;
+            await queueRestoration(state.active);
+        }
+        catch {
+            // A missing/failed lifecycle side channel cannot authorize dispatch
+            // during an already-observed transition.
+            if (preparing !== undefined)
+                blocked = true;
+        }
+        finally {
+            if (!destroyed)
+                timer = setTimeout(() => void poll(), LIFECYCLE_POLL_INTERVAL_MS);
+        }
+    };
+    void poll();
+    return Object.freeze({
+        assertDispatchOpen() {
+            if (blocked)
+                throw new Error('coherent application reload is in progress');
+        },
+        register(participant) {
+            participants.set(participant.key, participant);
+            void queueRestoration().catch(() => undefined);
+            return () => {
+                if (participants.get(participant.key) === participant) {
+                    participants.delete(participant.key);
+                }
+            };
+        },
+        destroy() {
+            destroyed = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            participants.clear();
+        }
+    });
+}
+async function prepareReload(state, participantId, participants) {
+    try {
+        const now = Date.now();
+        const capsule = Object.freeze({
+            version: 1,
+            transitionId: state.transitionId,
+            from: state.active,
+            to: state.pending,
+            location: validateDistributedReloadLocation(new URL(window.location.href)),
+            createdAtUnixMs: now,
+            expiresAtUnixMs: Math.max(now + CAPSULE_MIN_LIFETIME_MS, state.deadlineUnixMs + CAPSULE_ACTIVATION_GRACE_MS),
+            phase: 'prepared',
+            participants: Object.freeze([...participants.values()]
+                .sort((left, right) => left.key.localeCompare(right.key))
+                .map((participant) => Object.freeze({ key: participant.key, ...participant.prepare() })))
+        });
+        storeCapsule(capsule);
+        await acknowledge(state.transitionId, participantId, true);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'unknown preparation failure';
+        console.error('Distributed reload preparation failed:', message);
+        window.dispatchEvent(new CustomEvent('distributed:reload-prepare-failed', {
+            detail: Object.freeze({ transitionId: state.transitionId, message })
+        }));
+        await acknowledge(state.transitionId, participantId, false);
+    }
+}
+async function acknowledge(transitionId, participantId, ok) {
+    const response = await fetch(STATE_ENDPOINT, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        credentials: 'same-origin',
+        body: JSON.stringify({ transitionId, participantId, ok })
+    });
+    if (!response.ok)
+        throw new Error(`lifecycle acknowledgement returned ${response.status}`);
+}
+async function restoreAvailableParticipants(participants, active) {
+    const capsule = readCapsule();
+    if (capsule === undefined ||
+        capsule.phase !== 'restoring' ||
+        (active !== undefined && capsule.to.generationId !== active.generationId))
+        return;
+    const remaining = [];
+    const compatible = capsule.from.compatibilityId === capsule.to.compatibilityId;
+    for (const saved of capsule.participants) {
+        const participant = participants.get(saved.key);
+        if (participant === undefined) {
+            remaining.push(saved);
+            continue;
+        }
+        try {
+            const restored = await withDeadline(Promise.resolve(participant.restore(saved, compatible)), Math.min(RESTORE_TIMEOUT_MS, Math.max(1, capsule.expiresAtUnixMs - Date.now())));
+            if (!restored)
+                remaining.push(saved);
+        }
+        catch {
+            // Incompatible partitions are intentionally dropped; the mounted
+            // operation stores perform their ordinary authoritative fetch.
+        }
+    }
+    if (remaining.length === 0) {
+        sessionStorage.removeItem(CAPSULE_KEY);
+    }
+    else {
+        storeCapsule(Object.freeze({ ...capsule, participants: Object.freeze(remaining) }));
+    }
+}
+function withDeadline(operation, timeoutMs) {
+    return new Promise((resolvePromise, reject) => {
+        const timer = setTimeout(() => reject(new Error('Distributed reload restoration timed out')), timeoutMs);
+        operation.then((value) => {
+            clearTimeout(timer);
+            resolvePromise(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+function storeCapsule(capsule) {
+    assertSafeSerializable(capsule, 'reloadCapsule', 0, new Set(), false);
+    const encoded = JSON.stringify(capsule);
+    if (new TextEncoder().encode(encoded).length > MAX_CAPSULE_BYTES) {
+        throw new TypeError('Distributed reload capsule exceeds 1 MiB');
+    }
+    sessionStorage.setItem(CAPSULE_KEY, encoded);
+}
+function readCapsule() {
+    const encoded = sessionStorage.getItem(CAPSULE_KEY);
+    if (encoded === null || new TextEncoder().encode(encoded).length > MAX_CAPSULE_BYTES)
+        return undefined;
+    try {
+        const value = JSON.parse(encoded);
+        if (value.version !== 1 || value.expiresAtUnixMs < Date.now()) {
+            sessionStorage.removeItem(CAPSULE_KEY);
+            return undefined;
+        }
+        return value;
+    }
+    catch {
+        sessionStorage.removeItem(CAPSULE_KEY);
+        return undefined;
+    }
+}
+function markCapsuleRestoring() {
+    const capsule = readCapsule();
+    if (capsule !== undefined)
+        storeCapsule(Object.freeze({ ...capsule, phase: 'restoring' }));
+}
+function parseLifecycleState(value) {
+    const state = object(value, 'lifecycle');
+    if (state.schemaVersion !== 1 || (state.phase !== 'active' && state.phase !== 'preparing')) {
+        throw new TypeError('invalid Distributed lifecycle state');
+    }
+    const active = parseLifecycleGeneration(state.active, 'lifecycle.active');
+    const pending = state.pending === undefined
+        ? undefined
+        : parseLifecycleGeneration(state.pending, 'lifecycle.pending');
+    const transitionId = state.transitionId === undefined
+        ? undefined
+        : identity(state.transitionId, 'lifecycle.transitionId');
+    const deadlineUnixMs = state.deadlineUnixMs === undefined
+        ? undefined
+        : finiteInteger(state.deadlineUnixMs, 'lifecycle.deadlineUnixMs');
+    if (state.phase === 'preparing' && (pending === undefined || transitionId === undefined || deadlineUnixMs === undefined)) {
+        throw new TypeError('preparing lifecycle state is incomplete');
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        phase: state.phase,
+        active,
+        ...(pending === undefined ? {} : { pending }),
+        ...(transitionId === undefined ? {} : { transitionId }),
+        ...(deadlineUnixMs === undefined ? {} : { deadlineUnixMs })
+    });
+}
+function parseLifecycleGeneration(value, path) {
+    const generation = object(value, path);
+    return Object.freeze({
+        generationId: identity(generation.generationId, `${path}.generationId`),
+        releaseId: identity(generation.releaseId, `${path}.releaseId`),
+        topologyId: identity(generation.topologyId, `${path}.topologyId`),
+        compatibilityId: identity(generation.compatibilityId, `${path}.compatibilityId`)
+    });
+}
+function browserParticipantId() {
+    const key = '@hops-ops/distributed/reload-participant/v1';
+    const existing = sessionStorage.getItem(key);
+    if (existing !== null && PARTICIPANT_ID.test(existing))
+        return existing;
+    // `crypto.randomUUID()` is restricted to secure contexts, while
+    // `getRandomValues()` is intentionally available on ordinary HTTP origins.
+    // Local GitOps and LAN development commonly serve Vite through an HTTP
+    // service hostname, so requiring randomUUID would silently disable the
+    // lifecycle client there.
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    const created = [...bytes]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+    sessionStorage.setItem(key, created);
+    return created;
+}
+function documentGenerationId() {
+    if (typeof document === 'undefined')
+        return undefined;
+    const candidate = document
+        .querySelector(`meta[name="${GENERATION_META}"]`)
+        ?.getAttribute('content');
+    if (candidate === null || candidate === undefined)
+        return undefined;
+    try {
+        return identity(candidate, 'document generation');
+    }
+    catch {
+        return undefined;
+    }
+}
+function inertLifecycle() {
+    return Object.freeze({
+        assertDispatchOpen() { },
+        register() {
+            return () => undefined;
+        },
+        destroy() { }
+    });
+}
+function object(value, path) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`${path} must be an object`);
+    }
+    return value;
+}
+function identity(value, path) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 512 || value !== value.trim() || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new TypeError(`${path} must be a bounded stable identity`);
+    }
+    return value;
+}
+function finiteInteger(value, path) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`${path} must be a non-negative safe integer`);
+    }
+    return value;
+}
+function assertSafeSerializable(value, path, depth, seen, rejectSecretKeys) {
+    if (depth > MAX_STATE_DEPTH)
+        throw new TypeError(`${path} exceeds maximum depth`);
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return;
+    if (typeof value !== 'object')
+        throw new TypeError(`${path} is not JSON serializable`);
+    if (seen.has(value))
+        throw new TypeError(`${path} contains a cycle`);
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            assertSafeSerializable(value[index], `${path}[${index}]`, depth + 1, seen, rejectSecretKeys);
+        }
+    }
+    else {
+        for (const [key, child] of Object.entries(value)) {
+            if (rejectSecretKeys && SECRET_KEY.test(key))
+                throw new TypeError(`${path}.${key} is secret-like state`);
+            assertSafeSerializable(child, `${path}.${key}`, depth + 1, seen, rejectSecretKeys);
+        }
+    }
+    seen.delete(value);
+}

package/dist/sveltekit/replica.d.ts

@@ -3,6 +3,7 @@ import type { GqlAuth, GqlError, GraphqlVariables } from '../types.js';
 import type { WebSocketConstructor } from '../websocket.js';
 import type { FetchLike } from '../request.js';
 import { type PageGraphqlData } from './auth.js';
+import { type DistributedReloadOptions } from './lifecycle.js';
 type UnknownCommandEntries = Readonly<Record<string, never>>;
 export type SveltekitSessionSource = Readonly<{
     /** Current credential. HTTP, WS, and commands all call this exact source. */
@@ -42,11 +43,11 @@ export type SveltekitDistributedPageData = PageGraphqlData & Readonly<{
     distributed?: SveltekitReplicaHydration;
     distributedAuthority?: SveltekitReplicaAuthority;
 }>;
-export type SveltekitCommandRuntimeLike<TCommands> = Pick<ReplicaCommandRuntime<UnknownCommandEntries>, 'dispose'> & Readonly<{
+export type SveltekitCommandRuntimeLike<TCommands> = Pick<ReplicaCommandRuntime<UnknownCommandEntries>, 'dispose' | 'pendingCommandIds'> & Readonly<{
     commands: TCommands;
 }>;
 export type SveltekitCommandRuntimeFactory<TCommands> = (replica: DistributedReplica, transport: ReplicaGraphqlTransport, options: SveltekitCommandRuntimeFactoryOptions) => SveltekitCommandRuntimeLike<TCommands>;
-export type SveltekitCommandRuntimeFactoryOptions = Pick<ReplicaCommandRuntimeOptions, 'diagnostics'>;
+export type SveltekitCommandRuntimeFactoryOptions = Pick<ReplicaCommandRuntimeOptions, 'diagnostics' | 'lifecycle'>;
 export type CreateDistributedSvelteKitOptions<TCommands = Readonly<Record<never, never>>> = Readonly<{
     session: SveltekitSessionSource;
     /** Same-origin `/graphql` by default. */
@@ -64,6 +65,8 @@ export type CreateDistributedSvelteKitOptions<TCommands = Readonly<Record<never,
     createCommands?: SveltekitCommandRuntimeFactory<TCommands>;
     replica?: Omit<DistributedReplicaOptions, 'transport'>;
     onAuthError?: (error: unknown) => void;
+    /** Generated clients supply the surface key; apps may declare safe state partitions. */
+    reload?: DistributedReloadOptions;
 }>;
 export type SveltekitQuerySnapshot<TData> = ReplicaSnapshot<TData> & Readonly<{
     loading: boolean;

package/dist/sveltekit/replica.js

@@ -2,6 +2,7 @@ import { sameAuthCredential, snapshotAuthCredential } from '../identity.js';
 import { createDistributedReplica, createReplicaGraphqlTransport } from '../replica/index.js';
 import { replicaCommandProjectedLifecycleOf } from '../replica/command-runtime.js';
 import { authFromPageData } from './auth.js';
+import { distributedReloadLifecycle, registerDistributedReloadClient } from './lifecycle.js';
 /**
  * Bind the framework-neutral replica to Svelte's readable-store lifecycle.
  *
@@ -65,8 +66,35 @@ export function createDistributedSvelteKit(options) {
     const commandRuntime = options.createCommands?.(replica, transport, Object.freeze({
         ...(options.replica?.diagnostics === undefined
             ? {}
-            : { diagnostics: options.replica.diagnostics })
+            : { diagnostics: options.replica.diagnostics }),
+        ...(options.browser === true && options.reload !== undefined
+            ? { lifecycle: distributedReloadLifecycle() }
+            : {})
     }));
+    let unregisterReload;
+    try {
+        unregisterReload =
+            options.browser === true && options.reload !== undefined
+                ? registerDistributedReloadClient(replica, commandRuntime, options.reload)
+                : undefined;
+    }
+    catch (error) {
+        // Client construction is transactional: a malformed reload declaration
+        // must not retain its session subscription or command authority.
+        try {
+            commandRuntime?.dispose();
+        }
+        catch {
+            // Preserve the construction failure; disposal is best effort here.
+        }
+        try {
+            auth.dispose();
+        }
+        catch {
+            // Preserve the construction failure; disposal is best effort here.
+        }
+        throw error;
+    }
     const commands = commandRuntime === undefined
         ? Object.freeze({})
         : wrapCommandTree(commandRuntime.commands, pending);
@@ -102,6 +130,7 @@ export function createDistributedSvelteKit(options) {
                 store.destroy();
             stores.clear();
             pending.clear();
+            unregisterReload?.();
             commandRuntime?.dispose();
         }
     });

package/dist/sveltekit/vite.d.ts

@@ -49,12 +49,26 @@ type ViteModuleGraphLike = Readonly<{
     getModuleById(id: string): unknown;
     invalidateModule(module: unknown): void;
 }>;
+type ViteMiddlewareRequest = Readonly<{
+    method?: string;
+    headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+    on(event: 'data', listener: (chunk: Uint8Array) => void): void;
+    on(event: 'end' | 'error', listener: (value?: unknown) => void): void;
+}>;
+type ViteMiddlewareResponse = {
+    statusCode: number;
+    setHeader(name: string, value: string): void;
+    end(body?: string | Uint8Array): void;
+};
 type ViteServerLike = Readonly<{
     watcher: Readonly<{
         add(paths: string | readonly string[]): void;
     }>;
     ws: ViteWebSocketLike;
     moduleGraph: ViteModuleGraphLike;
+    middlewares?: Readonly<{
+        use(path: string, handler: (request: ViteMiddlewareRequest, response: ViteMiddlewareResponse) => void): void;
+    }>;
     httpServer?: Readonly<{
         once(event: 'close', listener: () => void): void;
     }> | null;
@@ -62,6 +76,7 @@ type ViteServerLike = Readonly<{
 type ViteHotContextLike = Readonly<{
     file: string;
     server: ViteServerLike;
+    modules?: readonly unknown[];
 }>;
 type RollupWatchContextLike = Readonly<{
     addWatchFile(path: string): void;
@@ -77,10 +92,31 @@ export type DistributedSvelteKitVitePlugin = Readonly<{
     buildStart(this: RollupWatchContextLike): void;
     resolveId(source: string): string | undefined;
     load(id: string): string | undefined;
+    transformIndexHtml(): LifecycleHtmlTag[];
     handleHotUpdate(context: ViteHotContextLike): Promise<never[] | undefined>;
     watchChange(id: string): Promise<void>;
     closeBundle(): Promise<void>;
 }>;
+export type DistributedLifecycleVitePlugin = Readonly<{
+    name: string;
+    enforce: 'pre';
+    configResolved(config: Readonly<{
+        root: string;
+    }>): void;
+    configureServer(server: ViteServerLike): void;
+    transformIndexHtml(): LifecycleHtmlTag[];
+    handleHotUpdate(context: ViteHotContextLike): never[] | undefined;
+}>;
+type LifecycleHtmlTag = Readonly<{
+    tag: 'meta';
+    attrs: Readonly<{
+        name: string;
+        content: string;
+    }>;
+    injectTo: 'head-prepend';
+}>;
+/** Lifecycle-only side channel for projects using committed generated clients. */
+export declare function distributedLifecycle(): DistributedLifecycleVitePlugin;
 /** Generate every configured surface through the same transaction used by Vite. */
 export declare function generateDistributedSvelteKit(options: DistributedSvelteKitViteOptions): Promise<void>;
 /** Check every configured surface through canonical `distributed client --check`; never write. */