@configdirector/nuxt-sdk 1.11.0 → 1.12.0

package/dist/runtime/plugin.client.mjs

@@ -923,10 +923,27 @@ const generateInstanceId = () => {
 	});
 };
 //#endregion
+//#region ../js-client-core/src/browser-globals.ts
+const read = (readValue) => {
+	try {
+		return readValue(globalThis);
+	} catch {
+		return;
+	}
+};
+const readUserAgent = () => read((globals) => globals.navigator?.userAgent);
+const readHost = () => read((globals) => globals.location?.host);
+const localStorageIfAvailable = () => {
+	try {
+		return globalThis.localStorage ?? void 0;
+	} catch {
+		return;
+	}
+};
+//#endregion
 //#region ../js-client-core/src/client-session.ts
 const STORAGE_KEY = "configdirector-sdk:instance-id";
 const RECORD_VERSION = 1;
-const MAX_AGE_MS = 360 * 60 * 1e3;
 const STORAGE_DEADLINE_MS = 1e3;
 const CHECKSUM_SALT = "configdirector.instanceId.v1";
 const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -943,13 +960,6 @@ const checksumFor = (id, createdAt) => {
 	const low = fnv1a(payload, 2166136261);
 	return fnv1a(`${low}|${payload}`, 16777619).toString(16).padStart(8, "0") + low.toString(16).padStart(8, "0");
 };
-const localStorageIfAvailable = () => {
-	try {
-		return globalThis.localStorage ?? void 0;
-	} catch {
-		return;
-	}
-};
 const isUsableRecord = (record) => {
 	if (!record || typeof record !== "object") return false;
 	const { v, id, createdAt, checksum } = record;
@@ -978,11 +988,6 @@ const readStoredInstanceId = async (storage, logger) => {
 		logger.debug("[ConfigDirectorClient] The stored instance id failed validation, generating a new one");
 		return { outcome: "nothing usable" };
 	}
-	const age = Date.now() - record.createdAt;
-	if (age < 0 || age >= MAX_AGE_MS) {
-		logger.debug("[ConfigDirectorClient] The stored instance id has expired, generating a new one");
-		return { outcome: "nothing usable" };
-	}
 	return {
 		outcome: "stored",
 		instanceId: record.id
@@ -1198,17 +1203,6 @@ var PollingTransport = class extends AbstractPollingTransport {
 	}
 };
 //#endregion
-//#region ../js-client-core/src/browser-globals.ts
-const read = (readValue) => {
-	try {
-		return readValue(globalThis);
-	} catch {
-		return;
-	}
-};
-const readUserAgent = () => read((globals) => globals.navigator?.userAgent);
-const readHost = () => read((globals) => globals.location?.host);
-//#endregion
 //#region ../shared/src/context-kind.ts
 const CONTEXT_KIND_MAXIMUM_LENGTH = 64;
 const KIND_SAMPLE_MAXIMUM_CHARACTERS = 128;
@@ -1253,6 +1247,178 @@ const admitContext = (context) => {
 	};
 };
 //#endregion
+//#region ../shared/src/utf8-byte-length.ts
+const isHighSurrogate = (codeUnit) => codeUnit >= 55296 && codeUnit <= 56319;
+const isLowSurrogate = (codeUnit) => codeUnit >= 56320 && codeUnit <= 57343;
+const utf8ByteLength = (text) => {
+	let bytes = 0;
+	for (let i = 0; i < text.length; i++) {
+		const codeUnit = text.charCodeAt(i);
+		if (codeUnit <= 127) bytes += 1;
+		else if (codeUnit <= 2047) bytes += 2;
+		else if (isHighSurrogate(codeUnit) && i + 1 < text.length && isLowSurrogate(text.charCodeAt(i + 1))) {
+			bytes += 4;
+			i++;
+		} else bytes += 3;
+	}
+	return bytes;
+};
+//#endregion
+//#region ../js-client-core/src/cached-values.ts
+const ENTRY_FORMAT_VERSION = 1;
+const DEFAULT_CONTEXT_KIND = "user";
+const CACHED_VALUES_STORAGE_KEY_PREFIX = "configdirector-sdk:cached-values:";
+const DEFAULT_CACHING_SIZE_LIMIT_BYTES = 256 * 1024;
+const planCaching = (connectionPlan, caching, platformProvider) => {
+	if (connectionPlan.kind === "stay-offline") return {
+		kind: "no cache",
+		reason: "offline mode"
+	};
+	if (caching?.enabled === false) return {
+		kind: "no cache",
+		reason: "turned off"
+	};
+	const provider = caching?.provider ?? platformProvider?.(connectionPlan.clientSdkKey);
+	if (!provider) return {
+		kind: "no cache",
+		reason: "no provider available"
+	};
+	return {
+		kind: "cache",
+		provider,
+		clientSdkKey: connectionPlan.clientSdkKey
+	};
+};
+const contextTagFor = (context, instanceId) => {
+	const contextKind = context?.kind ?? DEFAULT_CONTEXT_KIND;
+	if (context?.id != null) return {
+		contextKind,
+		contextId: context.id
+	};
+	return {
+		contextKind,
+		anonymousInstanceId: instanceId
+	};
+};
+const sameContextTag = (stored, launch) => {
+	if (stored.contextKind !== launch.contextKind) return false;
+	if ("contextId" in stored && "contextId" in launch) return stored.contextId === launch.contextId;
+	if ("anonymousInstanceId" in stored && "anonymousInstanceId" in launch) return stored.anonymousInstanceId === launch.anonymousInstanceId;
+	return false;
+};
+const decideCachedValuesAdoption = (cachedValues, launchContextTag, hasReceivedLiveValues) => {
+	if (hasReceivedLiveValues) return "live values already arrived";
+	if (!sameContextTag(cachedValues.contextTag, launchContextTag)) return "context mismatch";
+	return "adopt";
+};
+const isContextTag = (candidate) => {
+	if (!candidate || typeof candidate !== "object") return false;
+	const { contextKind, contextId, anonymousInstanceId } = candidate;
+	if (typeof contextKind !== "string") return false;
+	return typeof contextId === "string" || typeof anonymousInstanceId === "string";
+};
+const isConfigStateMap = (candidate) => {
+	if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return false;
+	return Object.values(candidate).every((config) => config && typeof config === "object" && typeof config.id === "string" && typeof config.key === "string");
+};
+const isEntryFor = (clientSdkKey, candidate) => {
+	if (!candidate || typeof candidate !== "object") return false;
+	const entry = candidate;
+	return entry.formatVersion === ENTRY_FORMAT_VERSION && entry.clientSdkKey === clientSdkKey && isContextTag(entry.contextTag) && typeof entry.environmentId === "string" && typeof entry.projectId === "string" && isConfigStateMap(entry.configs) && typeof entry.receivedAt === "number";
+};
+var CachedValuesStore = class {
+	warned = /* @__PURE__ */ new Set();
+	pendingRead;
+	queuedCachedValues;
+	writing = false;
+	constructor(provider, clientSdkKey, logger) {
+		this.provider = provider;
+		this.clientSdkKey = clientSdkKey;
+		this.logger = logger;
+	}
+	read() {
+		this.pendingRead ??= this.readEntry();
+		return this.pendingRead;
+	}
+	replace(cachedValues) {
+		this.queuedCachedValues = cachedValues;
+		this.writeQueued();
+	}
+	async readEntry() {
+		let raw;
+		try {
+			raw = await this.provider.read();
+		} catch (error) {
+			this.warnOnce("read failed", "Could not read the values kept on the device, starting without them:", error);
+			return { outcome: "failed" };
+		}
+		if (raw == null || raw === "") return { outcome: "nothing stored" };
+		const entry = this.parseEntry(raw);
+		if (!entry) {
+			this.warnOnce("unreadable", "The values kept on the device could not be read and were removed, starting without them");
+			await this.removeEntry();
+			return { outcome: "unreadable" };
+		}
+		return {
+			outcome: "stored",
+			cachedValues: entry
+		};
+	}
+	parseEntry(raw) {
+		try {
+			const candidate = JSON.parse(raw);
+			return isEntryFor(this.clientSdkKey, candidate) ? candidate : void 0;
+		} catch {
+			return;
+		}
+	}
+	async writeQueued() {
+		if (this.writing) return;
+		this.writing = true;
+		try {
+			while (this.queuedCachedValues) {
+				const cachedValues = this.queuedCachedValues;
+				this.queuedCachedValues = void 0;
+				await this.writeEntry(cachedValues);
+			}
+		} finally {
+			this.writing = false;
+		}
+	}
+	async writeEntry(cachedValues) {
+		const entry = {
+			formatVersion: ENTRY_FORMAT_VERSION,
+			clientSdkKey: this.clientSdkKey,
+			...cachedValues
+		};
+		const serialized = JSON.stringify(entry);
+		const size = utf8ByteLength(serialized);
+		const limit = this.provider.sizeLimit();
+		if (size > limit) {
+			this.warnOnce("over the size limit", `The values received (${size} bytes) exceed the caching provider's limit of ${limit} bytes, so no values are kept on the device`);
+			await this.removeEntry();
+			return;
+		}
+		try {
+			await this.provider.write(serialized);
+		} catch (error) {
+			this.warnOnce("write failed", "Could not keep the values on the device:", error);
+		}
+	}
+	async removeEntry() {
+		try {
+			await this.provider.remove();
+		} catch (error) {
+			this.warnOnce("remove failed", "Could not remove the values kept on the device:", error);
+		}
+	}
+	warnOnce(warning, message, ...details) {
+		if (this.warned.has(warning)) return;
+		this.warned.add(warning);
+		this.logger.warn(`[ConfigDirectorClient] ${message}`, ...details);
+	}
+};
+//#endregion
 //#region ../js-client-core/src/DefaultConfigDirectorClient.ts
 const MAX_EXPONENTIAL_DELAY = 9;
 var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
@@ -1270,11 +1436,15 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 	readyPromise;
 	readyResolve;
 	currentContext;
+	submittedContext;
 	connectionPlan;
 	clientSession;
-	static from(liveTelemetryClient, clientSdkKeyOrOptions, sdkOptions, clientOptions) {
-		if (typeof clientSdkKeyOrOptions === "object") return new DefaultConfigDirectorClient(liveTelemetryClient, void 0, sdkOptions, clientSdkKeyOrOptions);
-		return new DefaultConfigDirectorClient(liveTelemetryClient, clientSdkKeyOrOptions, sdkOptions, clientOptions);
+	cachedValuesStore;
+	servingCachedValues = false;
+	cachedValuesAdoptionStarted = false;
+	static from(liveTelemetryClient, clientSdkKeyOrOptions, sdkOptions, clientOptions, internalClientOptions) {
+		if (typeof clientSdkKeyOrOptions === "object") return new DefaultConfigDirectorClient(liveTelemetryClient, void 0, sdkOptions, clientSdkKeyOrOptions, internalClientOptions);
+		return new DefaultConfigDirectorClient(liveTelemetryClient, clientSdkKeyOrOptions, sdkOptions, clientOptions, internalClientOptions);
 	}
 	constructor(liveTelemetryClient, clientSdkKey, sdkOptions, clientOptions, internalClientOptions) {
 		this.logger = clientOptions?.logger ?? createDefaultLogger$1();
@@ -1282,10 +1452,12 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 		this.timeout = clientOptions?.connection?.timeout ?? 3e3;
 		const urlFactory = internalClientOptions?.urlFactory ?? defaultUrlFactory;
 		this.connectionPlan = planConnection(clientSdkKey, clientOptions?.connection, urlFactory);
+		this.cachedValuesStore = this.buildCachedValuesStore(planCaching(this.connectionPlan, clientOptions?.caching, internalClientOptions?.platformCachingProvider));
 		this.telemetryClient = this.buildTelemetryClient(liveTelemetryClient, clientOptions);
 		this.transport = internalClientOptions?.transport ?? this.buildTransport(sdkOptions, clientOptions, urlFactory, internalClientOptions);
 		this.transport.on("configSetReceived", (configSet) => {
 			this.hasReceivedConfigSet = true;
+			this.servingCachedValues = false;
 			this.readyResolve?.();
 			const removedKeys = this.findKeysRemovedBy(configSet);
 			if (!this.configSet || configSet.kind == "full") this.configSet = configSet;
@@ -1293,6 +1465,7 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 				...this.configSet.configs,
 				...configSet.configs
 			};
+			this.keepValuesOnTheDevice(this.configSet);
 			const keys = Object.keys(configSet.configs);
 			this.emit("configsUpdated", {
 				keys,
@@ -1314,6 +1487,80 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 		this.registerHandler("configsUpdated", clientOptions?.hooks?.configsUpdated);
 		this.registerHandler("contextUpdated", clientOptions?.hooks?.contextUpdated);
 		this.registerHandler("connectionError", clientOptions?.hooks?.connectionError);
+		this.registerHandler("cachedValuesLoaded", clientOptions?.hooks?.cachedValuesLoaded);
+	}
+	buildCachedValuesStore(cachingPlan) {
+		switch (cachingPlan.kind) {
+			case "no cache":
+				this.logger.debug(`[ConfigDirectorClient] No values are kept on the device: ${cachingPlan.reason}`);
+				return;
+			case "cache": {
+				const store = new CachedValuesStore(cachingPlan.provider, cachingPlan.clientSdkKey, this.logger);
+				store.read();
+				return store;
+			}
+		}
+	}
+	startCachedValuesAdoption() {
+		const store = this.cachedValuesStore;
+		if (!store || this.cachedValuesAdoptionStarted) return;
+		this.cachedValuesAdoptionStarted = true;
+		this.adoptCachedValues(store);
+	}
+	async adoptCachedValues(store) {
+		const read = await store.read();
+		switch (read.outcome) {
+			case "nothing stored":
+			case "unreadable":
+			case "failed": return;
+			case "stored": break;
+		}
+		const { instanceId } = await this.clientSession;
+		const launchContextTag = contextTagFor(this.submittedContext, instanceId);
+		const adoption = decideCachedValuesAdoption(read.cachedValues, launchContextTag, this.hasReceivedConfigSet);
+		switch (adoption) {
+			case "adopt":
+				this.serveCachedValues(read.cachedValues);
+				return;
+			case "live values already arrived":
+			case "context mismatch":
+				this.logger.debug(`[ConfigDirectorClient] The values kept on the device were not adopted: ${adoption}`);
+				return;
+		}
+	}
+	serveCachedValues(cachedValues) {
+		const { environmentId, projectId, configs } = cachedValues;
+		this.configSet = {
+			environmentId,
+			projectId,
+			configs,
+			kind: "full"
+		};
+		this.servingCachedValues = true;
+		const keys = Object.keys(configs);
+		this.emit("cachedValuesLoaded", {});
+		this.emit("configsUpdated", {
+			keys,
+			removedKeys: []
+		});
+		this.updateWatchers(keys);
+		this.logger.debug("[ConfigDirectorClient] Serving the values kept on the device until live values arrive:", { keys });
+	}
+	keepValuesOnTheDevice(configSet) {
+		const store = this.cachedValuesStore;
+		if (!store) return;
+		const context = this.submittedContext;
+		const receivedAt = Date.now();
+		this.clientSession.then(({ instanceId }) => store.replace({
+			contextTag: contextTagFor(context, instanceId),
+			environmentId: configSet.environmentId,
+			projectId: configSet.projectId,
+			configs: configSet.configs,
+			receivedAt
+		}));
+	}
+	servedReason(reason) {
+		return this.servingCachedValues && reason === "found-match" ? "cached" : reason;
 	}
 	registerHandler(event, handler) {
 		if (!handler) return;
@@ -1407,6 +1654,8 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 		return this.currentContext;
 	}
 	async connectToTransport(context, caller) {
+		this.submittedContext = context;
+		if (caller === "initialization") this.startCachedValuesAdoption();
 		try {
 			this.ready = false;
 			this.readyPromise = new Promise((resolve) => {
@@ -1507,6 +1756,7 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 			return defaultValue;
 		}
 		const parseResult = parseConfigValue(configState, defaultValue);
+		const reason = this.servedReason(parseResult.reason);
 		this.telemetryClient.evaluatedConfig({
 			contextId: this.currentContext?.id,
 			type: configState.type,
@@ -1516,14 +1766,14 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 			evaluatedValue: parseResult.parsedValue,
 			evaluatedValueId: parseResult.parsedValueId,
 			usedDefault: parseResult.usedDefault,
-			evaluationReason: parseResult.reason
+			evaluationReason: reason
 		});
 		this.dispatchEvaluationEvent({
 			key: configKey,
 			value: parseResult.parsedValue,
 			valueId: parseResult.parsedValueId ?? void 0,
 			isDefaultValue: parseResult.usedDefault,
-			reason: parseResult.reason,
+			reason,
 			context: this.context
 		});
 		this.logger.debug(`[ConfigDirectorClient] Evaluated '${configKey}' to '${parseResult.parsedValue}'`);
@@ -1879,6 +2129,25 @@ const generateValueId = async (v) => {
 	return toBase62(new Uint8Array(hashBuffer, 0, 16), BASE62_LENGTH);
 };
 //#endregion
+//#region ../js-browser-client/src/local-storage-caching-provider.ts
+const toHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+const storageKeyFor = async (clientSdkKey) => {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(clientSdkKey));
+	return CACHED_VALUES_STORAGE_KEY_PREFIX + toHex(new Uint8Array(digest));
+};
+const subtleCryptoAvailable = () => typeof crypto !== "undefined" && crypto.subtle != null;
+const localStorageCachingProvider = (clientSdkKey) => {
+	const storage = localStorageIfAvailable();
+	if (!storage || !subtleCryptoAvailable()) return;
+	const storageKey = storageKeyFor(clientSdkKey);
+	return {
+		read: async () => storage.getItem(await storageKey),
+		write: async (value) => storage.setItem(await storageKey, value),
+		remove: async () => storage.removeItem(await storageKey),
+		sizeLimit: () => DEFAULT_CACHING_SIZE_LIMIT_BYTES
+	};
+};
+//#endregion
 //#region ../js-browser-client/src/BrowserConfigDirectorClient.ts
 /**
 * Creates a browser client. With a client SDK key it connects to ConfigDirector; with
@@ -1901,13 +2170,26 @@ const createBrowserClient = (clientSdkKeyOrOptions, sdkOptions, clientOptions) =
 		baseUrl,
 		urlFactory: defaultUrlFactory,
 		valueIdGenerator: generateValueId
-	}), clientSdkKeyOrOptions, sdkOptions, clientOptions);
+	}), clientSdkKeyOrOptions, sdkOptions, clientOptions, { platformCachingProvider: localStorageCachingProvider });
 };
 //#endregion
 //#region ../js-client-core/src/installedTestClient.ts
 const INSTALLED_TEST_CLIENT_SLOT = Symbol.for("@configdirector/installed-test-client");
 const readInstalledTestClient = () => globalThis[INSTALLED_TEST_CLIENT_SLOT];
 //#endregion
+//#region ../shared/src/browser-half.ts
+const decideBrowserHalfSource = (browserHalf, serverConnectionMode) => {
+	if (browserHalf.mode !== void 0 || browserHalf.values !== void 0) return "as-given";
+	if (serverConnectionMode === "offline") return "inherit-offline";
+	return "connect";
+};
+//#endregion
+//#region src/runtime/app/composables/useConfigDirectorClient.ts
+const useConfigDirectorClient = () => {
+	const { $configDirectorClient } = useNuxtApp();
+	return { client: $configDirectorClient };
+};
+//#endregion
 //#region ../shared/src/deepEqual.ts
 const deepEqual = (left, right) => {
 	if (Object.is(left, right)) return true;
@@ -1933,17 +2215,17 @@ const decideMountAction = (client, context) => {
 	return "none";
 };
 //#endregion
-//#region ../shared/src/browser-half.ts
-const decideBrowserHalfSource = (browserHalf, serverConnectionMode) => {
-	if (browserHalf.mode !== void 0 || browserHalf.values !== void 0) return "as-given";
-	if (serverConnectionMode === "offline") return "inherit-offline";
-	return "connect";
-};
-//#endregion
-//#region src/runtime/app/composables/useConfigDirectorClient.ts
-const useConfigDirectorClient = () => {
-	const { $configDirectorClient } = useNuxtApp();
-	return { client: $configDirectorClient };
+//#region src/runtime/client-startup.ts
+const decideStartupAction = (client, context, waitsForFirstContext) => {
+	const mountAction = decideMountAction(client, context);
+	if (!waitsForFirstContext) return mountAction;
+	if (mountAction === "initialize" && context === void 0) return "waitForContext";
+	if (mountAction === "none" && client.isInitializing) return "firstStartInFlight";
+	return mountAction;
+};
+const decideContextUpdateAction = (client, context, waitsForFirstContext) => {
+	if (waitsForFirstContext && decideMountAction(client, context) === "initialize") return "startClient";
+	return "updateContext";
 };
 //#endregion
 //#region src/runtime/app/composables/useConfigDirectorContext.ts
@@ -1954,6 +2236,14 @@ const getEffectiveTimeout = (option) => {
 const useConfigDirectorContext = () => {
 	const state = useState("configdirector-context");
 	const { client } = useConfigDirectorClient();
+	const { $configDirectorClientStartup } = useNuxtApp();
+	const startup = $configDirectorClientStartup;
+	const handContextToClient = (rawContext) => {
+		switch (decideContextUpdateAction(client, rawContext, startup.waitsForFirstContext)) {
+			case "startClient": return startup.start(rawContext);
+			case "updateContext": return client.updateContext(rawContext);
+		}
+	};
 	const updateContext = async (context, options) => {
 		const rawContext = toRaw(context);
 		const oldContext = JSON.stringify(state.value);
@@ -1963,7 +2253,7 @@ const useConfigDirectorContext = () => {
 			const timeout = getEffectiveTimeout(options?.timeoutMilliseconds);
 			let timer;
 			try {
-				await Promise.race([client.updateContext(rawContext), new Promise((resolve) => {
+				await Promise.race([handContextToClient(rawContext), new Promise((resolve) => {
 					timer = setTimeout(() => resolve(), timeout);
 				})]);
 			} finally {
@@ -1990,28 +2280,51 @@ const OFFLINE_VALUES_ROUTE = "/_configdirector/offline-values";
 //#region src/runtime/plugin.client.ts
 const DEFAULT_INITIALIZATION_TIMEOUT_MILLISECONDS = 2e3;
 var plugin_client_default = defineNuxtPlugin(async (nuxtApp) => {
-	const runtimeConfig = useRuntimeConfig();
-	const logger = createDefaultLogger(runtimeConfig.public?.configdirector?.logLevel);
+	const configdirector = useRuntimeConfig().public?.configdirector;
+	const logger = createDefaultLogger(configdirector?.logLevel);
 	const installedTestClient = readInstalledTestClient();
-	const client = installedTestClient ?? await buildClient(runtimeConfig.public?.configdirector, logger);
+	const { client, runsOffline } = installedTestClient ? {
+		client: installedTestClient,
+		runsOffline: false
+	} : await buildClient(configdirector, logger);
 	logger.debug(installedTestClient ? "Installed ConfigDirector Nuxt plugin with a test client" : "Installed ConfigDirector Nuxt plugin");
 	const readyStatus = shallowRef(client.isReady ? "ready" : "loading");
 	client.on("clientReady", () => {
 		readyStatus.value = "ready";
 	});
+	const settleReadyStatus = () => {
+		if (!client.isReady) readyStatus.value = "default";
+	};
+	const startup = {
+		waitsForFirstContext: configdirector?.deferInitialization === true && !runsOffline,
+		start: async (context) => {
+			await client.initialize(context);
+			settleReadyStatus();
+		}
+	};
 	nuxtApp.hooks.hook("app:created", async () => {
 		const { context } = useConfigDirectorContext();
 		const rawContext = toRaw(context.value);
-		const mountAction = decideMountAction(client, rawContext);
-		logger.debug(`Browser client mount action: ${mountAction}`);
-		if (mountAction === "initialize") await client.initialize(rawContext);
-		else if (mountAction === "updateContext" && rawContext !== void 0) await client.updateContext(rawContext);
-		if (!client.isReady) readyStatus.value = "default";
-		logger.debug(`Browser client mount action awaited, ready status: ${client.isReady}`);
+		const startupAction = decideStartupAction(client, rawContext, startup.waitsForFirstContext);
+		logger.debug(`Browser client startup action: ${startupAction}`);
+		switch (startupAction) {
+			case "waitForContext": return;
+			case "firstStartInFlight": return;
+			case "initialize":
+				await client.initialize(rawContext);
+				break;
+			case "updateContext":
+				await client.updateContext(rawContext);
+				break;
+			case "none": break;
+		}
+		settleReadyStatus();
+		logger.debug(`Browser client startup action awaited, ready status: ${client.isReady}`);
 	});
 	return { provide: {
 		configDirectorClient: client,
-		configDirectorClientReadyStatus: readonly(readyStatus)
+		configDirectorClientReadyStatus: readonly(readyStatus),
+		configDirectorClientStartup: startup
 	} };
 });
 const buildClient = async (configdirector, logger) => {
@@ -2021,23 +2334,26 @@ const buildClient = async (configdirector, logger) => {
 		logger.error(message);
 		throw new ConfigDirectorInitializationError(message);
 	}
-	return createBrowserClient(configdirector?.clientSdkKey || void 0, {
-		sdkName: "nuxt-sdk",
-		sdkVersion: "1.11.0"
-	}, {
-		metadata: {
-			appName: configdirector?.appName,
-			appVersion: configdirector?.appVersion
-		},
-		connection: {
-			url: configdirector?.baseUrl || void 0,
-			mode: browserHalf.mode,
-			values: browserHalf.values,
-			pollingInterval: configdirector?.connection?.pollingInterval || void 0,
-			timeout: configdirector?.connection?.timeout || DEFAULT_INITIALIZATION_TIMEOUT_MILLISECONDS
-		},
-		logger
-	});
+	return {
+		client: createBrowserClient(configdirector?.clientSdkKey || void 0, {
+			sdkName: "nuxt-sdk",
+			sdkVersion: "1.12.0"
+		}, {
+			metadata: {
+				appName: configdirector?.appName,
+				appVersion: configdirector?.appVersion
+			},
+			connection: {
+				url: configdirector?.baseUrl || void 0,
+				mode: browserHalf.mode,
+				values: browserHalf.values,
+				pollingInterval: configdirector?.connection?.pollingInterval || void 0,
+				timeout: configdirector?.connection?.timeout || DEFAULT_INITIALIZATION_TIMEOUT_MILLISECONDS
+			},
+			logger
+		}),
+		runsOffline: browserHalf.mode === "offline"
+	};
 };
 const browserHalfConnectionOf = async (configdirector, logger) => {
 	const givenConnection = {