@fireweaveai/web-sdk-cjs 0.0.0-reserve.0

package/dist/application/runtime.d.ts

@@ -0,0 +1,70 @@
+import type { ContextInput, ContextLimits } from '../domain/context.js';
+import type { ExpectedFlagType } from '../domain/validation.js';
+import type { RegisterTargetOptions, RegisterTargetResult, WebBackendAdapter } from './ports.js';
+import type { Decision, Exposure, JsonValue, LifecycleState, ReleaseContext, Signal } from '../domain/types.js';
+export type { ExpectedFlagType } from '../domain/validation.js';
+/** Ceiling on the initial prefetch so a hung backend cannot block boot. */
+export declare const DEFAULT_FLAGS_READY_TIMEOUT_MS = 5000;
+export interface FireweaveWebRuntimeConfig {
+    /** Context applied to every evaluation unless overridden per call. */
+    readonly globalContext?: ContextInput;
+    readonly limits?: Partial<ContextLimits>;
+    /** Additional reserved attribute keys, beyond DEFAULT_RESERVED_ATTRIBUTE_KEYS. */
+    readonly reservedAttributeKeys?: readonly string[];
+    readonly flagsReadyTimeoutMs?: number;
+    /** Restrict prefetch to a known set of control points. */
+    readonly controlPointKeys?: readonly string[];
+    /** Emit a Fireweave exposure on each successful evaluation. Default false. */
+    readonly sendExposure?: boolean;
+}
+export declare class FireweaveWebRuntime {
+    readonly adapter: WebBackendAdapter;
+    readonly config: FireweaveWebRuntimeConfig;
+    private state;
+    private cache;
+    private globalContext;
+    private readonly contextPolicy;
+    private releaseContext;
+    private readonly listeners;
+    constructor(adapter: WebBackendAdapter, config?: FireweaveWebRuntimeConfig);
+    getState(): LifecycleState;
+    onStateChange(listener: (state: LifecycleState) => void): () => void;
+    private setState;
+    setReleaseContext(ctx: ReleaseContext): void;
+    getReleaseContext(): ReleaseContext;
+    /** Initialize the adapter and populate the cache. Never throws. */
+    initialize(context?: ContextInput): Promise<void>;
+    /**
+     * Replace the global context and re-prefetch — the identity-change path.
+     *
+     * Call this after sign-in with the user's stable id, so percentage ramps
+     * bucket on that id rather than on an anonymous one. Returns the keys whose
+     * decisions changed, so a provider can emit a targeted ConfigurationChanged.
+     */
+    setContext(context: ContextInput): Promise<readonly string[]>;
+    /** Re-run the prefetch against the current global context. */
+    refresh(): Promise<void>;
+    /**
+     * Synchronous evaluation against the prefetched cache. Never throws —
+     * failures surface as ERROR decisions, exactly like the OpenFeature
+     * contract.
+     *
+     * Validates in the fixed order spec/control-points.md "Validation, before
+     * any I/O" names — key, default-vs-type, context, lifecycle — stopping at
+     * the first failure. Only once all four pass does this consult the cache.
+     */
+    evaluateSync(controlPointKey: string, expectedType: ExpectedFlagType, defaultValue: JsonValue, invocationContext?: ContextInput): Decision;
+    private reasonFor;
+    private metadataFor;
+    private recordExposureFor;
+    recordExposure(exposure: Exposure): void;
+    recordSignal(signal: Signal): void;
+    registerTarget(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
+    flush(options?: {
+        beacon?: boolean;
+    }): Promise<void>;
+    shutdown(): Promise<void>;
+    private changedKeys;
+    private lifecycleError;
+    private errorDecision;
+}

package/dist/application/runtime.js

@@ -0,0 +1,348 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FireweaveWebRuntime = exports.DEFAULT_FLAGS_READY_TIMEOUT_MS = void 0;
+/**
+ * FireweaveWebRuntime — the async/sync boundary.
+ *
+ * `initialize()` and `setContext()` prefetch a decision cache asynchronously;
+ * `evaluateSync()` is a pure read of that cache. That split is what lets a
+ * synchronous OpenFeature web provider sit on top of an architecture that is
+ * otherwise async, without either side bending.
+ *
+ * ## Fail-open, not fail-silent
+ *
+ * A hung backend must not block app boot, so the prefetch races a ceiling. What
+ * happens when the ceiling wins is the design decision that matters: this
+ * runtime enters `STALE` — not `READY` — and serves defaults with reason
+ * `STALE`, so a timed-out boot is DISTINGUISHABLE from a successful one.
+ *
+ * The tempting alternative (resolve the race and carry on) makes a failed
+ * prefetch look exactly like a successful one where every control point
+ * happened to be off. Under a progressive rollout that is the difference
+ * between "nobody got the feature because the ramp is at 0%" and "nobody got
+ * the feature because the SDK never reached the server", and no operator can
+ * tell those apart after the fact.
+ *
+ * ## Validation order (spec/control-points.md "Validation, before any I/O")
+ *
+ * `evaluateSync` validates in the fixed order the spec names — key,
+ * default-vs-type, context, lifecycle — stopping at the first failure, and
+ * only THEN consults the prefetched cache. "Before any I/O" reads literally
+ * for node (the adapter call is the I/O); web has already done its I/O
+ * earlier (the prefetch), so here the same four-step order gates the cache
+ * READ instead, for the same reason: a malformed call must degrade to the
+ * caller's default without depending on what happens to be in the cache.
+ */
+const errors_js_1 = require("../domain/errors.js");
+const context_js_1 = require("../domain/context.js");
+const validation_js_1 = require("../domain/validation.js");
+/** Ceiling on the initial prefetch so a hung backend cannot block boot. */
+exports.DEFAULT_FLAGS_READY_TIMEOUT_MS = 5_000;
+class FireweaveWebRuntime {
+    adapter;
+    config;
+    state = 'UNINITIALIZED';
+    cache = new Map();
+    globalContext;
+    contextPolicy;
+    releaseContext = {};
+    listeners = new Set();
+    constructor(adapter, config = {}) {
+        this.adapter = adapter;
+        this.config = config;
+        this.globalContext = { ...(config.globalContext ?? {}) };
+        this.contextPolicy = {
+            limits: { ...context_js_1.DEFAULT_CONTEXT_LIMITS, ...(config.limits ?? {}) },
+            reservedAttributeKeys: [...context_js_1.DEFAULT_RESERVED_ATTRIBUTE_KEYS, ...(config.reservedAttributeKeys ?? [])],
+            // Not required at the generic context-validation layer — web's
+            // targetingKey requirement is enforced at the remote adapter's
+            // prefetch/registerTarget boundary, not on every read.
+            requireTargetingKey: false,
+        };
+    }
+    getState() {
+        return this.state;
+    }
+    onStateChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    setState(next) {
+        this.state = next;
+        for (const l of this.listeners)
+            l(next);
+    }
+    setReleaseContext(ctx) {
+        this.releaseContext = { ...ctx };
+    }
+    getReleaseContext() {
+        return this.releaseContext;
+    }
+    /** Initialize the adapter and populate the cache. Never throws. */
+    async initialize(context) {
+        if (this.state === 'SHUTDOWN')
+            return;
+        this.setState('INITIALIZING');
+        if (context !== undefined)
+            this.globalContext = { ...this.globalContext, ...context };
+        try {
+            await this.adapter.initialize();
+        }
+        catch {
+            this.setState('ERROR');
+            return;
+        }
+        await this.refresh();
+    }
+    /**
+     * Replace the global context and re-prefetch — the identity-change path.
+     *
+     * Call this after sign-in with the user's stable id, so percentage ramps
+     * bucket on that id rather than on an anonymous one. Returns the keys whose
+     * decisions changed, so a provider can emit a targeted ConfigurationChanged.
+     */
+    async setContext(context) {
+        this.globalContext = { ...context };
+        const before = this.cache;
+        await this.refresh();
+        return this.changedKeys(before, this.cache);
+    }
+    /** Re-run the prefetch against the current global context. */
+    async refresh() {
+        if (this.state === 'SHUTDOWN')
+            return;
+        let canonical;
+        try {
+            canonical = (0, validation_js_1.canonicalizeContext)((0, context_js_1.mergeContexts)(this.globalContext), this.contextPolicy);
+        }
+        catch {
+            this.setState('ERROR');
+            return;
+        }
+        const timeoutMs = this.config.flagsReadyTimeoutMs ?? exports.DEFAULT_FLAGS_READY_TIMEOUT_MS;
+        let timer;
+        const TIMED_OUT = Symbol('timeout');
+        const prefetch = this.adapter.prefetch(canonical, this.config.controlPointKeys !== undefined ? { controlPointKeys: this.config.controlPointKeys } : undefined);
+        try {
+            const result = await Promise.race([
+                prefetch,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+                }),
+            ]);
+            if (result === TIMED_OUT) {
+                // Fail OPEN (boot continues) but not SILENT: reads will carry STALE and
+                // the lifecycle says so. Swallow the late rejection so a slow failure
+                // does not surface as an unhandled rejection minutes later.
+                void prefetch.catch(() => undefined);
+                this.setState('STALE');
+                return;
+            }
+            this.cache = result;
+            this.setState('READY');
+        }
+        catch {
+            this.setState('STALE');
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * Synchronous evaluation against the prefetched cache. Never throws —
+     * failures surface as ERROR decisions, exactly like the OpenFeature
+     * contract.
+     *
+     * Validates in the fixed order spec/control-points.md "Validation, before
+     * any I/O" names — key, default-vs-type, context, lifecycle — stopping at
+     * the first failure. Only once all four pass does this consult the cache.
+     */
+    evaluateSync(controlPointKey, expectedType, defaultValue, invocationContext) {
+        const keyResult = (0, validation_js_1.validateControlPointKey)(controlPointKey);
+        if (!keyResult.ok) {
+            return this.errorDecision(controlPointKey, defaultValue, keyResult.error);
+        }
+        const defaultResult = (0, validation_js_1.validateDefaultValue)(expectedType, defaultValue);
+        if (!defaultResult.ok) {
+            return this.errorDecision(controlPointKey, defaultValue, defaultResult.error);
+        }
+        // The validated context here is not what SELECTS the cached decision —
+        // that was fixed by the last prefetch (ADR-0009: evaluation is a pure
+        // cache read). It still has to be validated: a caller must not be able to
+        // bypass context limits/reserved-key checks just by moving an oversized or
+        // malformed structure into the per-call argument instead of the
+        // constructor's globalContext.
+        const merged = (0, context_js_1.mergeContexts)(this.globalContext, invocationContext);
+        const contextResult = (0, validation_js_1.validateContext)(merged, this.contextPolicy);
+        if (!contextResult.ok) {
+            return this.errorDecision(controlPointKey, defaultValue, contextResult.error);
+        }
+        const lifecycleError = this.lifecycleError();
+        if (lifecycleError !== undefined) {
+            return this.errorDecision(controlPointKey, defaultValue, lifecycleError);
+        }
+        const resolution = this.cache.get(controlPointKey);
+        if (resolution === undefined || resolution.found === false) {
+            // spec/modes.md "Behaviour per mode": local's unknown-key row is
+            // `default`/reason `DEFAULT` — deliberately not an error. The local
+            // adapter signals this via `missReason: 'DEFAULT'` (adapter.ts); every
+            // other adapter leaves it undefined and keeps the path below.
+            if (this.adapter.missReason === 'DEFAULT') {
+                return { controlPointKey, value: defaultValue, reason: 'DEFAULT', metadata: {} };
+            }
+            // A cache miss while STALE is not a missing control point — it is an
+            // unanswered question. Reporting FLAG_NOT_FOUND there would send a
+            // caller hunting for a flag that may well exist.
+            if (this.state === 'STALE') {
+                return {
+                    controlPointKey,
+                    value: defaultValue,
+                    reason: 'STALE',
+                    variant: 'default',
+                    metadata: { 'fireweave.stale': true },
+                };
+            }
+            return this.errorDecision(controlPointKey, defaultValue, new errors_js_1.FireweaveError('ControlPointNotFound'));
+        }
+        const value = resolution.value ?? null;
+        if (!(0, validation_js_1.matchesExpectedType)(value, expectedType)) {
+            return this.errorDecision(controlPointKey, defaultValue, new errors_js_1.FireweaveError('TypeMismatch'));
+        }
+        const metadata = this.metadataFor(resolution);
+        const decision = {
+            controlPointKey,
+            value,
+            reason: this.reasonFor(resolution),
+            ...(resolution.variant !== undefined ? { variant: resolution.variant } : {}),
+            ...(metadata !== undefined ? { metadata } : {}),
+        };
+        if (this.config.sendExposure === true) {
+            this.recordExposureFor(decision, invocationContext);
+        }
+        return decision;
+    }
+    reasonFor(resolution) {
+        // A STALE runtime is serving the last good decisions after a failed or
+        // timed-out re-fetch (spec/control-points.md): say so, whatever reason the
+        // backend gave when the decision was fresh.
+        if (this.state === 'STALE')
+            return 'STALE';
+        if (resolution.enabled === false)
+            return 'DISABLED';
+        if (resolution.reason !== undefined)
+            return resolution.reason;
+        return 'TARGETING_MATCH';
+    }
+    metadataFor(resolution) {
+        const metadata = {};
+        if (resolution.version !== undefined)
+            metadata['fireweave.controlPointVersion'] = resolution.version;
+        if (resolution.reasonCode !== undefined)
+            metadata['fireweave.reasonCode'] = resolution.reasonCode;
+        if (resolution.quotaLimited === true)
+            metadata['fireweave.quotaLimited'] = true;
+        return Object.keys(metadata).length > 0 ? metadata : undefined;
+    }
+    recordExposureFor(decision, invocationContext) {
+        if (this.adapter.recordExposure === undefined)
+            return;
+        const merged = (0, context_js_1.mergeContexts)(this.globalContext, invocationContext);
+        const targetingKey = typeof merged.targetingKey === 'string' ? merged.targetingKey : '';
+        if (targetingKey === '')
+            return;
+        const rc = this.releaseContext;
+        const exposure = {
+            controlPointKey: decision.controlPointKey,
+            targetingKey,
+            value: decision.value,
+            ...(decision.variant !== undefined ? { variant: decision.variant } : {}),
+            ...(rc.rolloutId !== undefined ? { rolloutId: rc.rolloutId } : {}),
+            ...(rc.changeId !== undefined ? { changeId: rc.changeId } : {}),
+            ...(rc.stampId !== undefined ? { stampId: rc.stampId } : {}),
+        };
+        this.adapter.recordExposure(exposure);
+    }
+    recordExposure(exposure) {
+        this.adapter.recordExposure?.(exposure);
+    }
+    recordSignal(signal) {
+        this.adapter.recordSignal?.(signal);
+    }
+    async registerTarget(targetingKey, options = {}) {
+        if (this.state === 'SHUTDOWN') {
+            return { ok: false, error: new errors_js_1.FireweaveError('AlreadyClosed') };
+        }
+        if (this.adapter.registerTarget === undefined) {
+            return { ok: false, error: new errors_js_1.FireweaveError('UnsupportedCapability') };
+        }
+        try {
+            return await this.adapter.registerTarget(targetingKey, options);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: (0, errors_js_1.isFireweaveError)(err) ? err : new errors_js_1.FireweaveError('BackendUnavailable'),
+            };
+        }
+    }
+    async flush(options = {}) {
+        await this.adapter.flush?.(options);
+    }
+    async shutdown() {
+        if (this.state === 'SHUTDOWN')
+            return;
+        try {
+            await this.adapter.flush?.();
+        }
+        catch {
+            // best-effort flush; never throw from shutdown
+        }
+        try {
+            await this.adapter.shutdown();
+        }
+        catch {
+            // never throw from shutdown
+        }
+        this.cache = new Map();
+        this.setState('SHUTDOWN');
+    }
+    changedKeys(before, after) {
+        const keys = new Set([...before.keys(), ...after.keys()]);
+        const changed = [];
+        for (const key of keys) {
+            const a = before.get(key);
+            const b = after.get(key);
+            if (JSON.stringify(a ?? null) !== JSON.stringify(b ?? null))
+                changed.push(key);
+        }
+        return changed;
+    }
+    lifecycleError() {
+        switch (this.state) {
+            case 'UNINITIALIZED':
+            case 'INITIALIZING':
+                return new errors_js_1.FireweaveError('NotReady');
+            case 'ERROR':
+                return new errors_js_1.FireweaveError('BackendUnavailable');
+            case 'SHUTDOWN':
+                return new errors_js_1.FireweaveError('AlreadyClosed');
+            default:
+                // READY, STALE: no lifecycle error — a STALE miss is handled
+                // specially in the cache-lookup branch above.
+                return undefined;
+        }
+    }
+    errorDecision(controlPointKey, defaultValue, err) {
+        return {
+            controlPointKey,
+            value: defaultValue,
+            reason: 'ERROR',
+            errorCode: err.openFeatureErrorCode,
+            errorKind: err.kind,
+            errorMessage: err.message,
+            metadata: { 'fireweave.errorKind': err.kind, ...err.metadata },
+        };
+    }
+}
+exports.FireweaveWebRuntime = FireweaveWebRuntime;

package/dist/build/node/define.d.ts

@@ -0,0 +1,14 @@
+import type { PolicyConfig } from '../src/start/policy.js';
+import { type BuildOptions } from './shared.js';
+export interface FireweaveDefineOptions extends BuildOptions {
+    /** The variable holding the browser key. Default FIREWEAVE_BROWSER_KEY. */
+    readonly keyVariable?: string;
+    /** Read these values instead of process.env (tests). */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Where the summary line goes. Default console.info. */
+    readonly log?: (line: string) => void;
+}
+/** Fail the build (throw) when the start profile would not start; returns the resolved config. */
+export declare function assertFireweaveBuild(options?: FireweaveDefineOptions): PolicyConfig;
+/** assertFireweaveBuild, plus the define map that hands the result to start(). */
+export declare function fireweaveDefine(options?: FireweaveDefineOptions): Record<string, string>;

package/dist/build/node/define.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertFireweaveBuild = assertFireweaveBuild;
+exports.fireweaveDefine = fireweaveDefine;
+/**
+ * @fireweaveai/web-sdk/define — the start profile's build check for bundlers
+ * other than Vite (Next.js, webpack, esbuild, Rollup). No vite import.
+ *
+ *   // next.config.mjs (or any build config)
+ *   import { fireweaveDefine } from '@fireweaveai/web-sdk/define';
+ *   const define = fireweaveDefine(); // throws if the build would ship without a usable key
+ *   // webpack: new webpack.DefinePlugin(define) · esbuild: { define } · Rollup: replace({ values: define })
+ *
+ * Reads process.env only: FIREWEAVE_BROWSER_KEY (or `keyVariable`),
+ * FIREWEAVE_URL, and the environment name FIREWEAVE_ENV, then APP_ENV, then
+ * NODE_ENV. Same policy and messages as the Vite plugin.
+ */
+const names_js_1 = require("../src/start/names.js");
+const policy_js_1 = require("../src/start/policy.js");
+const shared_js_1 = require("./shared.js");
+function resolveFromEnv(options) {
+    const env = options.env ?? process.env;
+    const lookup = (name) => (0, policy_js_1.sourced)(env[name], name);
+    const resolved = (0, shared_js_1.resolveBuild)(options, lookup, options.keyVariable ?? names_js_1.BUILD_ENV.key, [names_js_1.BUILD_ENV.environment, names_js_1.ENVIRONMENT_FALLBACK, 'NODE_ENV']);
+    const log = options.log ?? ((line) => console.info(line));
+    for (const w of resolved.warnings)
+        log(w);
+    log((0, shared_js_1.summaryLine)(resolved.config));
+    return resolved;
+}
+/** Fail the build (throw) when the start profile would not start; returns the resolved config. */
+function assertFireweaveBuild(options = {}) {
+    return resolveFromEnv(options).config;
+}
+/** assertFireweaveBuild, plus the define map that hands the result to start(). */
+function fireweaveDefine(options = {}) {
+    return { [names_js_1.INJECTED_CONFIG_NAME]: JSON.stringify(resolveFromEnv(options).injected) };
+}

package/dist/build/node/shared.d.ts

@@ -0,0 +1,19 @@
+import { type InjectedConfig, type PolicyConfig, type Sourced } from '../src/start/policy.js';
+/** A variable read at build time: its value and a source label for logs (never the value). */
+export type EnvLookup = (name: string) => Sourced | undefined;
+export interface BuildOptions {
+    /** Browser key. Prefer FIREWEAVE_BROWSER_KEY in the build environment. */
+    readonly key?: string;
+    /** fw-server URL or a same-origin proxy path ('/fw'). Default: FIREWEAVE_URL, else the SDK channel host. */
+    readonly url?: string;
+    /** Environment name for the mode rule. Default: FIREWEAVE_ENV, else APP_ENV. */
+    readonly environment?: string;
+}
+export interface BuildResolution {
+    readonly config: PolicyConfig;
+    readonly injected: InjectedConfig;
+    readonly warnings: readonly string[];
+}
+export declare function resolveBuild(options: BuildOptions, lookup: EnvLookup, keyVariable: string, environmentNames: readonly string[], extraEnvironment?: Sourced): BuildResolution;
+/** One summary line for build output. Names sources, never values. */
+export declare function summaryLine(config: PolicyConfig): string;

package/dist/build/node/shared.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBuild = resolveBuild;
+exports.summaryLine = summaryLine;
+/**
+ * Build-time resolution shared by the Vite plugin and the define helper.
+ * Runs in Node at config time, never in a browser. It reuses the browser's
+ * own policy (src/start/policy.ts), so a build fails for exactly the reasons
+ * the page would.
+ */
+const build_info_js_1 = require("../src/start/build-info.js");
+const names_js_1 = require("../src/start/names.js");
+const policy_js_1 = require("../src/start/policy.js");
+function resolveBuild(options, lookup, keyVariable, environmentNames, extraEnvironment) {
+    const key = (0, policy_js_1.firstOf)((0, policy_js_1.sourced)(options.key, 'fireweave({ key })'), lookup(keyVariable));
+    const url = (0, policy_js_1.firstOf)((0, policy_js_1.sourced)(options.url, 'fireweave({ url })'), lookup(names_js_1.BUILD_ENV.url));
+    const environment = (0, policy_js_1.firstOf)((0, policy_js_1.sourced)(options.environment, 'fireweave({ environment })'), ...environmentNames.map((name) => lookup(name)), extraEnvironment);
+    const checked = [`fireweave({ environment })`, ...environmentNames, ...(extraEnvironment !== undefined ? [extraEnvironment.source] : [])].join(', ');
+    const policy = (0, policy_js_1.resolvePolicy)({ key, url, environment, channel: build_info_js_1.SDK_CHANNEL, keyVariable, environmentChecked: checked });
+    if (!policy.ok)
+        throw new Error(policy.message);
+    const config = policy.config;
+    const injected = {
+        v: 1,
+        ...(config.mode === 'remote' && key !== undefined ? { key: key.value, keySource: key.source } : {}),
+        ...(url !== undefined ? { url: url.value, urlSource: url.source } : {}),
+        ...(environment !== undefined ? { environment: environment.value, environmentSource: environment.source } : {}),
+    };
+    return { config, injected, warnings: policy.warnings };
+}
+/** One summary line for build output. Names sources, never values. */
+function summaryLine(config) {
+    if (config.mode === 'local') {
+        const why = config.modeSource === 'environment' ? `environment '${config.environment ?? ''}' from ${config.environmentSource ?? ''}` : 'mode option';
+        return `[fireweave] local mode (${why}): values come from your control-points object; nothing is sent to fw-server.`;
+    }
+    const host = config.url !== undefined && !config.url.startsWith('/') ? new URL(config.url).host : config.url;
+    return `[fireweave] remote mode: browser key from ${config.keySource}, fw-server ${host} (${config.urlSource ?? ''}).`;
+}

package/dist/build/node/vite.d.ts

@@ -0,0 +1,53 @@
+import { type BuildOptions } from './shared.js';
+export type FireweavePluginOptions = BuildOptions;
+/** The subset of Vite's types the plugin touches, so the package needs no vite types to build. */
+interface UserConfigLike {
+    readonly root?: string;
+    readonly envDir?: string | false;
+    readonly build?: {
+        readonly lib?: unknown;
+    };
+}
+interface ConfigEnvLike {
+    readonly command: 'serve' | 'build';
+    readonly mode: string;
+    readonly isPreview?: boolean;
+}
+interface ResolvedConfigLike {
+    readonly envPrefix?: string | readonly string[];
+    readonly build?: {
+        readonly ssr?: unknown;
+    };
+}
+type OutputFileLike = {
+    readonly type: 'chunk';
+    readonly code: string;
+} | {
+    readonly type: 'asset';
+    readonly source: string | Uint8Array;
+};
+interface PluginContextLike {
+    readonly environment?: {
+        readonly config?: {
+            readonly consumer?: string;
+        };
+    };
+}
+export type LoadEnv = (mode: string, envDir: string, prefixes: string[]) => Record<string, string> | Promise<Record<string, string>>;
+export interface FireweaveVitePlugin {
+    readonly name: 'fireweave';
+    readonly enforce: 'pre';
+    config(userConfig: UserConfigLike, env: ConfigEnvLike): Promise<Record<string, unknown> | undefined>;
+    configResolved(config: ResolvedConfigLike): void;
+    generateBundle(this: PluginContextLike, options: unknown, bundle: Readonly<Record<string, OutputFileLike>>): void;
+}
+/** Test seam: the env-file loader and the process environment. */
+export interface PluginDeps {
+    readonly loadEnv?: LoadEnv;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly log?: (line: string) => void;
+}
+export declare function createFireweavePlugin(options?: FireweavePluginOptions, deps?: PluginDeps): FireweaveVitePlugin;
+/** The fireweave() Vite plugin. Add it to `plugins` in vite.config.ts (or a framework's `vite.plugins`). */
+export declare function fireweave(options?: FireweavePluginOptions): FireweaveVitePlugin;
+export {};