@zweer/mage-space-client 1.1.2 → 1.3.0

package/dist/index.mjs

@@ -17,12 +17,38 @@ var AuthError = class extends MageSpaceError {
 };
 /** Action-hash discovery failures (page/chunk fetch, empty registry). */
 var DiscoveryError = class extends MageSpaceError {
+	/**
+	* `true` when the action name was absent even after a forced re-discovery
+	* (a fallback trigger); `false` for scrape failures (no chunks/no hashes).
+	*/
+	notFound;
 	constructor(message, options) {
 		super(message, options);
 		this.name = "DiscoveryError";
+		this.notFound = options?.notFound ?? false;
+	}
+};
+/**
+* A required action is unavailable on the active host (a persistent 404 / HTML
+* fallback that survived one in-place re-discovery). A fallback trigger.
+*/
+var ActionUnavailableError = class extends MageSpaceError {
+	action;
+	targetKey;
+	constructor(action, targetKey, options) {
+		super(`Action "${action}" is unavailable on target "${targetKey}"`, options);
+		this.action = action;
+		this.targetKey = targetKey;
+		this.name = "ActionUnavailableError";
 	}
 };
-/** A Server Action returned 404, indicating a stale (post-deploy) hash. */
+/**
+* A Server Action returned 404, indicating a stale (post-deploy) hash.
+*
+* @deprecated Legacy export kept for backward compatibility; no longer thrown.
+* The current signal for a definitively unavailable action is
+* {@link ActionUnavailableError}.
+*/
 var StaleActionError = class extends MageSpaceError {
 	action;
 	constructor(action, options) {
@@ -214,7 +240,7 @@ var ActionRegistry = class {
 			snapshot = await this.refresh();
 			hash = snapshot.hashes[action];
 		}
-		if (hash === void 0) throw new DiscoveryError(`Action "${action}" not found after discovery`);
+		if (hash === void 0) throw new DiscoveryError(`Action "${action}" not found after discovery`, { notFound: true });
 		return {
 			hash,
 			deploymentId: snapshot.deploymentId
@@ -326,9 +352,11 @@ function resolveFlightValue(value, rows, seen = /* @__PURE__ */ new Set()) {
 		if (ref) {
 			const refId = ref[1];
 			if (refId === void 0 || seen.has(refId)) return;
-			seen.add(refId);
 			const target = rows.get(refId);
-			return target === void 0 ? void 0 : resolveFlightValue(target, rows, seen);
+			if (target === void 0) return;
+			const nextSeen = new Set(seen);
+			nextSeen.add(refId);
+			return resolveFlightValue(target, rows, nextSeen);
 		}
 		if (value.startsWith("$$")) return value.slice(1);
 		if (value.startsWith("$D")) return new Date(value.slice(2));
@@ -375,6 +403,26 @@ function unwrapResult(value) {
 /** Character actions are served from the `/explore` page. */
 const CHARACTERS_PATH = "/explore";
 const DEFAULT_SEARCH_LIMIT = 10;
+/** Server-enforced username constraints (from module 64428). */
+const USERNAME_MIN = 1;
+const USERNAME_MAX$1 = 15;
+const USERNAME_RE$1 = /^[a-z][a-z0-9_-]*$/;
+/**
+* Generate a username from a display name, matching the web UI logic:
+* lowercase, strip special chars, append a 4-char random suffix, truncate to 15.
+*/
+function generateUsername$1(name) {
+	const suffix = Math.random().toString(36).substring(2, 6);
+	const base = name.toLowerCase().trim().replace(/[^a-z0-9\s]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+	const maxBase = USERNAME_MAX$1 - suffix.length - 1;
+	return `${base.slice(0, maxBase).replace(/[-_]+$/, "")}-${suffix}`;
+}
+/** Validate a username and throw early with a clear message instead of a server 500. */
+function validateUsername$1(username) {
+	if (username.length < USERNAME_MIN) throw new MageSpaceError("Username is required (min 1 character)");
+	if (username.length > USERNAME_MAX$1) throw new MageSpaceError(`Username "${username}" is too long (${username.length} chars, max ${USERNAME_MAX$1})`);
+	if (!USERNAME_RE$1.test(username)) throw new MageSpaceError(`Username "${username}" is invalid: must start with a lowercase letter and contain only a-z, 0-9, _ or -`);
+}
 var CharactersService = class {
 	http;
 	auth;
@@ -402,10 +450,12 @@ var CharactersService = class {
 	}
 	/** Create a new character from an already-uploaded image URL. */
 	async create(input) {
+		const username = input.username ?? generateUsername$1(input.name);
+		validateUsername$1(username);
 		const session = await this.auth.getSession();
 		const body = {
 			name: input.name,
-			username: input.username,
+			username,
 			image_url: input.image_url,
 			audio_url: input.audio_url ?? null,
 			description: input.description ?? null,
@@ -592,7 +642,7 @@ const SESSION_DEFAULT_TTL_MS = 864e5;
 const ID_TOKEN_DEFAULT_TTL_S = 3600;
 var AuthManager = class {
 	refreshToken;
-	http;
+	getHttp;
 	fetchImpl;
 	apiKey;
 	sessionPath;
@@ -600,11 +650,19 @@ var AuthManager = class {
 	session = null;
 	constructor(opts) {
 		this.refreshToken = opts.refreshToken;
-		this.http = opts.http;
+		this.getHttp = opts.getHttp;
 		this.fetchImpl = opts.fetch;
 		this.apiKey = opts.firebaseApiKey ?? DEFAULT_FIREBASE_API_KEY;
 		this.sessionPath = opts.sessionPath ?? "/creations";
 	}
+	/**
+	* Drop the cached `__session` cookie so the next {@link getSession} mints a
+	* fresh one against the (newly) active host. The Firebase token chain is kept
+	* because it is host-independent.
+	*/
+	resetSession() {
+		this.session = null;
+	}
 	/** Return a valid Firebase ID token, refreshing via the refresh token if needed. */
 	async getIdToken() {
 		if (this.tokens !== null && Date.now() < this.tokens.expiresAt - EXPIRY_BUFFER_MS) return this.tokens.idToken;
@@ -619,7 +677,7 @@ var AuthManager = class {
 	async getSession() {
 		if (this.session !== null && Date.now() < this.session.expiresAt - EXPIRY_BUFFER_MS) return this.session.cookie;
 		const idToken = await this.getIdToken();
-		const cookie = extractSessionCookie((await this.http.callAction({
+		const cookie = extractSessionCookie((await this.getHttp().callAction({
 			action: "createUserSession",
 			path: this.sessionPath,
 			args: [idToken]
@@ -677,9 +735,58 @@ function extractSessionCookie(headers) {
 	return null;
 }
 //#endregion
+//#region lib/targets.ts
+/** Resolve a logical action to its host-specific wire name (identity if unlisted). */
+function resolveActionName(target, logical) {
+	return target.actionNames[logical] ?? logical;
+}
+/**
+* Production target.
+*
+* @remarks
+* Maps each logical action to the wire name the current production deploy
+* actually serves (all VERIFIED against `lib/seed.ts` / the existing MSW tests):
+* `submitGeneration → runArchitecture`, `cancelJob → cancelArchitectureJob`,
+* `listHistory → getHistoryPaginated`, `listCreations → getCreationsPaginatedParallel`,
+* and `getHistoryById → getHistoryById` (identity). The table is explicit rather
+* than empty so production behaviour is reproduced exactly regardless of the
+* logical-name vocabulary.
+*/
+const PRODUCTION_TARGET = {
+	key: "production",
+	baseUrl: "https://www.mage.space",
+	actionNames: {
+		submitGeneration: "runArchitecture",
+		getHistoryById: "getHistoryById",
+		cancelJob: "cancelArchitectureJob",
+		listHistory: "getHistoryPaginated",
+		listCreations: "getCreationsPaginatedParallel"
+	},
+	pollStrategy: "byId"
+};
+/**
+* Beta target. Beta facts are assumptions pending a reverse-engineering capture
+* under `docs/api/beta` — treat them as unverified until that doc lands.
+*/
+const BETA_TARGET = {
+	key: "beta",
+	baseUrl: "https://beta.mage.space",
+	actionNames: {
+		submitGeneration: "runArchitecture",
+		cancelJob: "cancelArchitectureJob",
+		listHistory: "getHistoryPaginated",
+		listCreations: "getCreationsPaginated"
+	},
+	pollStrategy: "paginated"
+};
+/** Default ordered fallback chain: production first, then beta. */
+const DEFAULT_TARGET_CHAIN = [PRODUCTION_TARGET, BETA_TARGET];
+//#endregion
 //#region lib/generation.ts
 /** Generation actions are served from the `/explore` page. */
 const GENERATION_PATH = "/explore";
+/** Mirrors HistoryService.HISTORY_PATH ('/creations'); kept local to avoid coupling the two services. */
+const HISTORY_PATH$1 = "/creations";
 /** RSC sentinel for an absent value. */
 const UNDEFINED$1 = "$undefined";
 /** Default concept id for mango-v3-pro (from docs — verify per model via rev-eng). */
@@ -691,9 +798,14 @@ const DEFAULT_TIMEOUT_MS = 3e5;
 var GenerationService = class {
 	http;
 	auth;
-	constructor(http, auth) {
+	target;
+	/** Single-status-read primitive; overridable so the client can make it fallback-aware. */
+	pollOnce;
+	constructor(http, auth, target, pollOnce) {
 		this.http = http;
 		this.auth = auth;
+		this.target = target;
+		this.pollOnce = pollOnce ?? ((id) => this.getHistory(id));
 	}
 	/** Submit an image generation job and return its `historyId`. */
 	async submit(opts) {
@@ -745,7 +857,7 @@ var GenerationService = class {
 			generationMode
 		}];
 		const { data } = await this.http.callAction({
-			action: "runArchitecture",
+			action: resolveActionName(this.target, "submitGeneration"),
 			path: GENERATION_PATH,
 			args,
 			session
@@ -758,22 +870,68 @@ var GenerationService = class {
 		if (typeof historyId !== "string") throw new GenerationError("runArchitecture did not return a history_id");
 		return { historyId };
 	}
-	/** Fetch a single history record by id. */
+	/** Fetch a single history record by id, dispatching on the target's poll strategy. */
 	async getHistory(historyId) {
+		if (this.target.pollStrategy === "paginated") return this.getHistoryPaginated(historyId);
 		const session = await this.auth.getSession();
 		const { data } = await this.http.callAction({
-			action: "getHistoryById",
+			action: resolveActionName(this.target, "getHistoryById"),
 			path: GENERATION_PATH,
 			args: [historyId],
 			session
 		});
 		return data;
 	}
+	/**
+	* Beta status read: `getHistoryById` is absent, so page `getHistoryPaginated`
+	* and find the item whose `id === historyId`.
+	*
+	* @remarks
+	* ASSUMED (pending docs/api/beta): each page window is swept in two phases —
+	* `running` first, then the raw `$undefined` sentinel (terminal items) — since
+	* which filter surfaces a running job on beta is not yet documented. Bounded by
+	* {@link PAGINATED_POLL_MAX_PAGES} pages of {@link PAGINATED_POLL_PAGE_SIZE}.
+	*/
+	async getHistoryPaginated(historyId) {
+		const uid = await this.auth.getUserId();
+		const limit = 20;
+		let offset = 0;
+		for (let pageIndex = 0; pageIndex < 10; pageIndex += 1) {
+			for (const status of ["running", UNDEFINED$1]) {
+				const page = await this.fetchHistoryPage(uid, status, limit, offset);
+				const found = page.histories.find((h) => h.id === historyId);
+				if (found !== void 0) return found;
+				if (status === UNDEFINED$1 && !page.hasMore) throw new GenerationError(`history ${historyId} not found on beta`);
+			}
+			offset += limit;
+		}
+		throw new GenerationError(`history ${historyId} not found on beta`);
+	}
+	/** Fetch one page of history via `listHistory` (resolved per target) on `/creations`. */
+	async fetchHistoryPage(uid, status, limit, offset) {
+		const session = await this.auth.getSession();
+		const filters = {
+			status,
+			type: UNDEFINED$1
+		};
+		const { data } = await this.http.callAction({
+			action: resolveActionName(this.target, "listHistory"),
+			path: HISTORY_PATH$1,
+			args: [
+				uid,
+				limit,
+				offset,
+				filters
+			],
+			session
+		});
+		return unwrapResult(data);
+	}
 	/** Cancel a running generation job. */
 	async cancelJob(historyId) {
 		const session = await this.auth.getSession();
 		await this.http.callAction({
-			action: "cancelArchitectureJob",
+			action: resolveActionName(this.target, "cancelJob"),
 			path: GENERATION_PATH,
 			args: [historyId],
 			session
@@ -786,7 +944,7 @@ var GenerationService = class {
 		const deadline = Date.now() + timeoutMs;
 		for (;;) {
 			if (opts.signal?.aborted === true) throw new TimeoutError("waitForResult was aborted");
-			const item = await this.getHistory(historyId);
+			const item = await this.pollOnce(historyId);
 			if (item.status === "success") return item;
 			if (item.status === "error") throw new GenerationError(`Generation failed: ${JSON.stringify(item.error ?? null)}`);
 			if (Date.now() > deadline) throw new TimeoutError(`Generation timed out after ${timeoutMs}ms (last status: ${item.status})`);
@@ -832,9 +990,11 @@ const UNDEFINED = "$undefined";
 var HistoryService = class {
 	http;
 	auth;
-	constructor(http, auth) {
+	target;
+	constructor(http, auth, target) {
 		this.http = http;
 		this.auth = auth;
+		this.target = target;
 	}
 	/** List generation history for the authenticated user. */
 	async list(opts = {}) {
@@ -846,7 +1006,7 @@ var HistoryService = class {
 			type: UNDEFINED
 		};
 		const { data } = await this.http.callAction({
-			action: "getHistoryPaginated",
+			action: resolveActionName(this.target, "listHistory"),
 			path: HISTORY_PATH,
 			args: [
 				uid,
@@ -864,7 +1024,7 @@ var HistoryService = class {
 		const limit = opts.limit ?? DEFAULT_LIMIT;
 		const offset = opts.offset ?? 0;
 		const { data } = await this.http.callAction({
-			action: "getCreationsPaginatedParallel",
+			action: resolveActionName(this.target, "listCreations"),
 			path: HISTORY_PATH,
 			args: [
 				uid,
@@ -949,75 +1109,21 @@ var HistoryService = class {
 	}
 };
 //#endregion
-//#region lib/http.ts
-const DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36";
-/**
-* Known RSC error digests mapped to human-readable messages.
-* Discovered via reverse engineering; the server does not expose error details.
-*/
-const KNOWN_DIGESTS = {
-	"709776019": "Username already taken (duplicate character/reference username)",
-	"1853426377": "Username already taken (duplicate character/reference username)"
-};
-var HttpClient = class {
-	registry;
-	fetchImpl;
-	baseUrl;
-	userAgent;
-	constructor(registry, fetchImpl, baseUrl, userAgent = DEFAULT_USER_AGENT) {
-		this.registry = registry;
-		this.fetchImpl = fetchImpl;
-		this.baseUrl = baseUrl;
-		this.userAgent = userAgent;
-	}
-	async callAction(params, retried = false) {
-		const { hash, deploymentId } = await this.registry.getHash(params.action);
-		const headers = {
-			accept: "text/x-component",
-			"content-type": "text/plain;charset=UTF-8",
-			"next-action": hash,
-			"x-deployment-id": deploymentId,
-			origin: this.baseUrl,
-			referer: `${this.baseUrl}${params.path}`,
-			"user-agent": this.userAgent
-		};
-		if (params.session !== void 0) headers.cookie = `__session=${params.session}`;
-		const res = await this.fetchImpl(`${this.baseUrl}${params.path}`, {
-			method: "POST",
-			headers,
-			body: JSON.stringify(params.args)
-		});
-		const contentType = res.headers.get("content-type") ?? "";
-		const isHtmlFallback = res.ok && contentType.includes("text/html");
-		if ((res.status === 404 || isHtmlFallback) && !retried) {
-			await safeText(res);
-			await this.registry.invalidate();
-			return this.callAction(params, true);
-		}
-		if (!res.ok) {
-			const body = await safeText(res);
-			const digest = body.match(/E\{"digest":"([^"]+)"\}/)?.[1];
-			const knownDigest = digest !== void 0 ? KNOWN_DIGESTS[digest] : void 0;
-			const hint = knownDigest ? ` — ${knownDigest}` : digest ? ` (server digest: ${digest})` : "";
-			const raw = body.length > 0 ? ` — ${body.slice(0, 200)}` : "";
-			throw new MageSpaceError(`Action "${params.action}" failed: HTTP ${res.status}${hint}${raw}`);
-		}
-		return {
-			data: parseServerActionResponse(await res.text()),
-			headers: res.headers,
-			deploymentId: res.headers.get("x-deployment-id") ?? deploymentId
-		};
-	}
-};
-async function safeText(res) {
-	try {
-		return await res.text();
-	} catch {
-		return "";
-	}
-}
-//#endregion
 //#region lib/references.ts
+/** Server-enforced username constraints (shared with characters, module 64428). */
+const USERNAME_MAX = 15;
+const USERNAME_RE = /^[a-z][a-z0-9_-]*$/;
+/** Generate a username from a display name (same logic as characters). */
+function generateUsername(name) {
+	const suffix = Math.random().toString(36).substring(2, 6);
+	const base = name.toLowerCase().trim().replace(/[^a-z0-9\s]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+	const maxBase = USERNAME_MAX - suffix.length - 1;
+	return `${base.slice(0, maxBase).replace(/[-_]+$/, "")}-${suffix}`;
+}
+function validateUsername(username) {
+	if (username.length > USERNAME_MAX) throw new MageSpaceError(`Username "${username}" is too long (${username.length} chars, max ${USERNAME_MAX})`);
+	if (!USERNAME_RE.test(username)) throw new MageSpaceError(`Username "${username}" is invalid: must start with a lowercase letter and contain only a-z, 0-9, _ or -`);
+}
 /** Reference actions are served from the `/explore` page. */
 const REFERENCES_PATH = "/explore";
 const DEFAULT_PAGE_LIMIT = 20;
@@ -1045,10 +1151,12 @@ var ReferencesService = class {
 	}
 	/** Create a reusable reference from an uploaded image/audio URL. */
 	async create(input) {
+		const username = input.username ?? generateUsername(input.name);
+		validateUsername(username);
 		const session = await this.auth.getSession();
 		const body = {
 			name: input.name,
-			username: input.username,
+			username,
 			image_url: input.image_url,
 			audio_url: input.audio_url ?? null,
 			modality: input.modality ?? "image",
@@ -1241,105 +1349,307 @@ const SEED_SNAPSHOT = {
 	}
 };
 //#endregion
+//#region lib/http.ts
+const DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36";
+/**
+* HTTP statuses that mean "this action is unavailable on this host". A stale
+* (post-deploy) action hash surfaces as a 404 on the production host and as a
+* 409 ("Server Action unavailable") on the beta host — both mean the same
+* thing: invalidate the registry, re-discover, and (if still unavailable) fall
+* back to the next host.
+*/
+const UNAVAILABLE_STATUSES = /* @__PURE__ */ new Set([404, 409]);
+/**
+* Known RSC error digests mapped to human-readable messages.
+* Discovered via reverse engineering; the server does not expose error details.
+*/
+const KNOWN_DIGESTS = {
+	"709776019": "Username already taken (duplicate character/reference username)",
+	"1853426377": "Invalid username (must be 1–15 lowercase chars, start with a letter, only a-z 0-9 _ -)"
+};
+var HttpClient = class {
+	registry;
+	fetchImpl;
+	baseUrl;
+	targetKey;
+	userAgent;
+	constructor(registry, fetchImpl, baseUrl, targetKey, userAgent = DEFAULT_USER_AGENT) {
+		this.registry = registry;
+		this.fetchImpl = fetchImpl;
+		this.baseUrl = baseUrl;
+		this.targetKey = targetKey;
+		this.userAgent = userAgent;
+	}
+	/** A response that means the action is unavailable (stale hash or gone). */
+	isUnavailable(res) {
+		const contentType = res.headers.get("content-type") ?? "";
+		const isHtmlFallback = res.ok && contentType.includes("text/html");
+		return UNAVAILABLE_STATUSES.has(res.status) || isHtmlFallback;
+	}
+	async callAction(params, retried = false) {
+		const { hash, deploymentId } = await this.registry.getHash(params.action);
+		const headers = {
+			accept: "text/x-component",
+			"content-type": "text/plain;charset=UTF-8",
+			"next-action": hash,
+			"x-deployment-id": deploymentId,
+			origin: this.baseUrl,
+			referer: `${this.baseUrl}${params.path}`,
+			"user-agent": this.userAgent
+		};
+		if (params.session !== void 0) headers.cookie = `__session=${params.session}`;
+		const res = await this.fetchImpl(`${this.baseUrl}${params.path}`, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(params.args)
+		});
+		if (this.isUnavailable(res) && !retried) {
+			await safeText(res);
+			await this.registry.invalidate();
+			return this.callAction(params, true);
+		}
+		if (this.isUnavailable(res)) {
+			await safeText(res);
+			throw new ActionUnavailableError(params.action, this.targetKey);
+		}
+		if (!res.ok) {
+			const body = await safeText(res);
+			const digest = body.match(/E\{"digest":"([^"]+)"\}/)?.[1];
+			const knownDigest = digest !== void 0 ? KNOWN_DIGESTS[digest] : void 0;
+			const hint = knownDigest ? ` — ${knownDigest}` : digest ? ` (server digest: ${digest})` : "";
+			const raw = body.length > 0 ? ` — ${body.slice(0, 200)}` : "";
+			throw new MageSpaceError(`Action "${params.action}" failed: HTTP ${res.status}${hint}${raw}`);
+		}
+		return {
+			data: parseServerActionResponse(await res.text()),
+			headers: res.headers,
+			deploymentId: res.headers.get("x-deployment-id") ?? deploymentId
+		};
+	}
+};
+async function safeText(res) {
+	try {
+		return await res.text();
+	} catch {
+		return "";
+	}
+}
+//#endregion
+//#region lib/target-context.ts
+/**
+* A {@link TargetContext} bundles one host's {@link ActionRegistry} and
+* {@link HttpClient} so the client can hold one pair per target and switch by
+* selecting the other pair (rather than mutating a shared `baseUrl`).
+*/
+/**
+* Build the registry + HTTP client for a single target.
+*
+* @remarks
+* The caller's `cache` and the production `seed` are production-only concerns:
+* the bundled seed holds production hashes and the single-slot cache cannot be
+* namespaced per host. Non-production targets always discover fresh with their
+* own {@link InMemoryActionCache} and no seed.
+*/
+function createTargetContext(target, deps) {
+	const isProduction = target.key === "production";
+	const registry = new ActionRegistry({
+		fetch: deps.fetch,
+		baseUrl: target.baseUrl,
+		cache: isProduction ? deps.cache : new InMemoryActionCache(),
+		seed: isProduction ? deps.seed : void 0
+	});
+	return {
+		target,
+		registry,
+		http: new HttpClient(registry, deps.fetch, target.baseUrl, target.key, deps.userAgent)
+	};
+}
+//#endregion
 //#region lib/client.ts
 /**
 * {@link MageSpaceClient} — the public facade that wires together action
 * discovery, authentication, generation, and history.
+*
+* The client models each mage.space host as a {@link Target} and holds an
+* ordered chain (production first, then beta). When the active host can no
+* longer serve a required action, the client advances to the next target and
+* retries once. The switch is sticky for the lifetime of the instance.
 */
-const DEFAULT_BASE_URL = "https://www.mage.space";
 var MageSpaceClient = class {
-	registry;
 	auth;
-	generationService;
-	historyService;
-	/** Character management (search, CRUD, pagination, uploads). */
+	chain;
+	auto;
+	contextDeps;
+	contexts = /* @__PURE__ */ new Map();
+	activeIndex;
+	activeContext;
+	activeBundle;
+	/**
+	* Character management (search, CRUD, pagination, uploads).
+	*
+	* @remarks
+	* Bound to the initial host (production by default) and does not follow an
+	* automatic beta fallback. Construct a client with `fallback: { start: 'beta' }`
+	* to use these against beta.
+	*/
 	characters;
-	/** Reference asset management (upload, create, update, list, feed). */
+	/**
+	* Reference asset management (upload, create, update, list, feed).
+	*
+	* @remarks
+	* Bound to the initial host (production by default) and does not follow an
+	* automatic beta fallback. Construct a client with `fallback: { start: 'beta' }`
+	* to use these against beta.
+	*/
 	references;
 	constructor(options) {
 		if (!options.refreshToken) throw new Error("MageSpaceClient requires a refreshToken");
-		const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
 		const fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
-		this.registry = new ActionRegistry({
+		const fallback = options.fallback;
+		const baseUrlPinned = typeof options.baseUrl === "string" && options.baseUrl.length > 0;
+		if (baseUrlPinned && fallback !== void 0 && (fallback.chain !== void 0 || fallback.start !== void 0 || fallback.auto !== void 0)) throw new Error("baseUrl pins a single host and cannot be combined with fallback options");
+		if (baseUrlPinned) {
+			this.chain = [{
+				key: "production",
+				baseUrl: options.baseUrl,
+				actionNames: {},
+				pollStrategy: "byId"
+			}];
+			this.auto = false;
+		} else {
+			const chain = fallback?.chain ?? DEFAULT_TARGET_CHAIN;
+			if (chain.length === 0) throw new Error("fallback.chain must be a non-empty array");
+			this.chain = chain;
+			this.auto = fallback?.auto ?? true;
+		}
+		const startKey = baseUrlPinned ? "production" : fallback?.start ?? "production";
+		const startIndex = this.chain.findIndex((t) => t.key === startKey);
+		if (startIndex === -1) throw new Error(`fallback.start '${startKey}' is not in the target chain`);
+		this.contextDeps = {
 			fetch: fetchImpl,
-			baseUrl,
+			userAgent: options.userAgent,
 			cache: options.cache,
 			seed: options.seed ?? SEED_SNAPSHOT
-		});
-		const http = new HttpClient(this.registry, fetchImpl, baseUrl, options.userAgent);
+		};
+		this.activeIndex = startIndex;
+		this.activeContext = this.getContext(startIndex);
 		this.auth = new AuthManager({
 			refreshToken: options.refreshToken,
-			http,
+			getHttp: () => this.activeContext.http,
 			fetch: fetchImpl,
 			firebaseApiKey: options.firebaseApiKey
 		});
-		this.generationService = new GenerationService(http, this.auth);
-		this.historyService = new HistoryService(http, this.auth);
-		this.characters = new CharactersService(http, this.auth);
-		this.references = new ReferencesService(http, this.auth);
+		this.activeBundle = this.buildBundle(this.activeContext);
+		this.characters = new CharactersService(this.activeContext.http, this.auth);
+		this.references = new ReferencesService(this.activeContext.http, this.auth);
+	}
+	/** Lazily build (and memoise) the {@link TargetContext} for a chain index. */
+	getContext(index) {
+		const target = this.chain[index];
+		const existing = this.contexts.get(target.key);
+		if (existing !== void 0) return existing;
+		const context = createTargetContext(target, this.contextDeps);
+		this.contexts.set(target.key, context);
+		return context;
+	}
+	/** Build the generation/history service bundle for a context. */
+	buildBundle(context) {
+		const pollOnce = (id) => this.withFallback((bundle) => bundle.generationService.getHistory(id));
+		return {
+			target: context.target,
+			generationService: new GenerationService(context.http, this.auth, context.target, pollOnce),
+			historyService: new HistoryService(context.http, this.auth, context.target)
+		};
+	}
+	/** Advance to the next target (sticky). Returns `null` if none or `auto` is off. */
+	advanceTarget() {
+		if (this.auto === false || this.activeIndex >= this.chain.length - 1) return null;
+		this.activeIndex += 1;
+		this.activeContext = this.getContext(this.activeIndex);
+		this.activeBundle = this.buildBundle(this.activeContext);
+		return this.activeBundle;
+	}
+	/** Whether an error is a definitive action-unavailable signal (a fallback trigger). */
+	shouldFallback(err) {
+		return err instanceof ActionUnavailableError || err instanceof DiscoveryError && err.notFound === true;
+	}
+	/** Run `op` against the active bundle, switching to the next target once on a trigger. */
+	async withFallback(op) {
+		try {
+			return await op(this.activeBundle);
+		} catch (err) {
+			if (!this.shouldFallback(err)) throw err;
+			if (this.advanceTarget() === null) throw err;
+			this.auth.resetSession();
+			return op(this.activeBundle);
+		}
 	}
 	/** Submit a generation job; returns its `historyId`. */
 	generate(options) {
-		return this.generationService.submit(options);
+		return this.withFallback((b) => b.generationService.submit(options));
 	}
 	/** Submit a video generation job (Berry-2 family); returns its `historyId`. */
 	generateVideo(options) {
-		return this.generationService.submitVideo(options);
+		return this.withFallback((b) => b.generationService.submitVideo(options));
 	}
 	/** Fetch the current state of a generation by id. */
 	getResult(historyId) {
-		return this.generationService.getHistory(historyId);
+		return this.withFallback((b) => b.generationService.getHistory(historyId));
 	}
 	/** Poll until a generation finishes (or fails / times out). */
 	waitForResult(historyId, options) {
-		return this.generationService.waitForResult(historyId, options);
+		return this.withFallback((b) => b.generationService.waitForResult(historyId, options));
 	}
 	/** Cancel a running generation job. */
 	cancelJob(historyId) {
-		return this.generationService.cancelJob(historyId);
+		return this.withFallback((b) => b.generationService.cancelJob(historyId));
 	}
 	/** List past generations for the authenticated user. */
 	listHistory(options) {
-		return this.historyService.list(options);
+		return this.withFallback((b) => b.historyService.list(options));
 	}
 	/** List the user's permanently saved creations. */
 	listCreations(options) {
-		return this.historyService.listCreations(options);
+		return this.withFallback((b) => b.historyService.listCreations(options));
 	}
 	/** Save a completed generation result as a permanent creation. */
 	saveCreation(result) {
-		return this.historyService.saveCreation(result);
+		return this.withFallback((b) => b.historyService.saveCreation(result));
 	}
 	/** Permanently delete a history item. Irreversible — requires `{ confirm: true }`. */
 	deleteHistory(historyId, options) {
-		return this.historyService.deleteHistory(historyId, options);
+		return this.withFallback((b) => b.historyService.deleteHistory(historyId, options));
 	}
 	/** Permanently delete many history items. Irreversible — requires `{ confirm: true }`. */
 	deleteManyHistories(historyIds, options) {
-		return this.historyService.deleteManyHistories(historyIds, options);
+		return this.withFallback((b) => b.historyService.deleteManyHistories(historyIds, options));
 	}
 	/** Permanently delete a saved creation. Irreversible — requires `{ confirm: true }`. */
 	deleteCreation(creationId, options) {
-		return this.historyService.deleteCreation(creationId, options);
+		return this.withFallback((b) => b.historyService.deleteCreation(creationId, options));
 	}
 	/** Permanently delete many creations. Irreversible — requires `{ confirm: true }`. */
 	deleteManyCreations(creationIds, options) {
-		return this.historyService.deleteManyCreations(creationIds, options);
+		return this.withFallback((b) => b.historyService.deleteManyCreations(creationIds, options));
 	}
-	/** Force re-discovery of the Server Action hashes. */
+	/** Force re-discovery of the Server Action hashes on the active host. */
 	refreshActions() {
-		return this.registry.refresh();
+		return this.activeContext.registry.refresh();
 	}
 	/** Return the authenticated user's Firebase uid. */
 	getUid() {
 		return this.auth.getUserId();
 	}
+	/** Return the key of the currently active target (`'production'` or `'beta'`). */
+	getActiveTarget() {
+		return this.chain[this.activeIndex].key;
+	}
 };
 //#endregion
 //#region lib/index.ts
 /** Public entry point for `@zweer/mage-space-client`. */
 const VERSION = "0.0.0";
 //#endregion
-export { ActionRegistry, AuthError, CharactersService, DiscoveryError, GenerationError, InMemoryActionCache, MageSpaceClient, MageSpaceError, ReferencesService, RscParseError, SEED_SNAPSHOT, StaleActionError, TimeoutError, VERSION, discoverActions, parseFlightRows, parseServerActionResponse, resolveFlightValue, unwrapResult };
+export { ActionRegistry, ActionUnavailableError, AuthError, BETA_TARGET, CharactersService, DEFAULT_TARGET_CHAIN, DiscoveryError, GenerationError, InMemoryActionCache, MageSpaceClient, MageSpaceError, PRODUCTION_TARGET, ReferencesService, RscParseError, SEED_SNAPSHOT, StaleActionError, TimeoutError, VERSION, discoverActions, parseFlightRows, parseServerActionResponse, resolveActionName, resolveFlightValue, unwrapResult };
 
 //# sourceMappingURL=index.mjs.map