@upstart.gg/vite-plugins 0.1.61 → 0.1.63

package/dist/upstart-editor-api.js

@@ -1,3 +1,5 @@
+import { analyzeRouteMeta } from "./page-meta.js";
+import { ensureRootSiteMeta } from "./site-meta.js";
 import MagicString from "magic-string";
 import { parseSync } from "oxc-parser";
 import fs from "node:fs/promises";
@@ -57,6 +59,213 @@ function inferArrayQuote(code, elements) {
 	}
 	return "\"";
 }
+/** Read the ArrayExpression a `meta` export resolves to, or explain why we can't. */
+function readMetaArray(node) {
+	if (node.type === "ArrayExpression") return {
+		ok: true,
+		array: node
+	};
+	if (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression") {
+		const body = node.body;
+		if (body.type === "ArrayExpression") return {
+			ok: true,
+			array: body
+		};
+		if (body.type === "BlockStatement") {
+			const argument = (body.body ?? []).find((st) => st.type === "ReturnStatement")?.argument;
+			if (argument?.type === "ArrayExpression") return {
+				ok: true,
+				array: argument
+			};
+		}
+	}
+	return {
+		ok: false,
+		reason: "The page meta is computed by code"
+	};
+}
+/** Turn a static array of object literals into plain key/value entries, or null if any part is dynamic. */
+function readStaticEntries(elements) {
+	const entries = [];
+	for (const element of elements) {
+		if (!element || element.type !== "ObjectExpression") return null;
+		const entry = [];
+		for (const prop of element.properties ?? []) {
+			if (prop.type !== "Property" || prop.computed || prop.shorthand || prop.kind !== "init") return null;
+			const key = prop.key;
+			const value = prop.value;
+			const keyName = key.type === "Identifier" ? key.name : key.type === "Literal" && typeof key.value === "string" ? key.value : null;
+			if (keyName === null) return null;
+			if (value.type !== "Literal" || typeof value.value !== "string") return null;
+			entry.push({
+				key: keyName,
+				value: value.value
+			});
+		}
+		entries.push(entry);
+	}
+	return entries;
+}
+/** Locate the route's `meta` export and read it if it is fully static. */
+function findMetaExport(code, filePath) {
+	const body = parseSync(filePath, code, { sourceType: "module" }).program?.body ?? [];
+	for (const statement of body) {
+		if (statement.type !== "ExportNamedDeclaration") continue;
+		const declaration = statement.declaration;
+		if (!declaration) {
+			if ((statement.specifiers ?? []).some((spec) => {
+				const name = spec.exported;
+				return name?.type === "Identifier" && name.name === "meta";
+			})) return {
+				kind: "dynamic",
+				reason: "The page meta is exported indirectly"
+			};
+			continue;
+		}
+		let source = null;
+		if (declaration.type === "VariableDeclaration") for (const decl of declaration.declarations ?? []) {
+			const id = decl.id;
+			if (id.type === "Identifier" && id.name === "meta") source = decl.init ?? null;
+		}
+		else if (declaration.type === "FunctionDeclaration") {
+			const id = declaration.id;
+			if (id?.type === "Identifier" && id.name === "meta") source = declaration;
+		}
+		if (!source) continue;
+		const array = readMetaArray(source);
+		if (!array.ok) return {
+			kind: "dynamic",
+			reason: array.reason
+		};
+		const entries = readStaticEntries(array.array.elements ?? []);
+		if (!entries) return {
+			kind: "dynamic",
+			reason: "The page meta contains dynamic values"
+		};
+		return {
+			kind: "static",
+			arrayStart: array.array.start,
+			arrayEnd: array.array.end,
+			entries
+		};
+	}
+	return { kind: "none" };
+}
+/** Offset right after the last top-level import, or the end of the file when there is none. */
+function findMetaInsertOffset(code, filePath) {
+	const body = parseSync(filePath, code, { sourceType: "module" }).program?.body ?? [];
+	let offset = null;
+	for (const statement of body) if (statement.type === "ImportDeclaration") offset = statement.end;
+	return offset ?? code.length;
+}
+/** Serialize entries back to source, one object literal per line. */
+function printMetaArray(entries, indent) {
+	if (entries.length === 0) return "[]";
+	return `[\n${entries.map((entry) => {
+		return `${indent}  { ${entry.map(({ key, value }) => {
+			return `${/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : `"${escapeStringLiteralBody(key, "\"")}"`}: "${escapeStringLiteralBody(value, "\"")}"`;
+		}).join(", ")} },`;
+	}).join("\n")}\n${indent}]`;
+}
+/** Read the value of `{ name: <name>, content: X }` (or `{ title: X }` when name is "title"). */
+function findMetaValue(entries, name) {
+	for (const entry of entries) {
+		if (name === "title") {
+			const title = entry.find((p) => p.key === "title");
+			if (title && entry.length === 1) return title.value;
+			continue;
+		}
+		if (entry.some((p) => p.key === "name" && p.value === name)) return entry.find((p) => p.key === "content")?.value ?? null;
+	}
+	return null;
+}
+/**
+* Update/insert/remove the entry for `name`, leaving every other entry (og:*, twitter:*,
+* canonical…) untouched and in place. An empty `value` removes the entry.
+*/
+function upsertMetaValue(entries, name, value) {
+	const matches = (entry) => name === "title" ? entry.length === 1 && entry[0].key === "title" : entry.some((p) => p.key === "name" && p.value === name);
+	const index = entries.findIndex(matches);
+	const next = entries.filter((entry, i) => i === index || !matches(entry));
+	if (value === "") return next.filter((entry) => !matches(entry));
+	const entry = name === "title" ? [{
+		key: "title",
+		value
+	}] : [{
+		key: "name",
+		value: name
+	}, {
+		key: "content",
+		value
+	}];
+	if (index === -1) return name === "title" ? [entry, ...next] : [...next, entry];
+	return next.map((existing, i) => i === index ? entry : existing);
+}
+/** Number of times a translation key appears in the app sources. */
+function countKeyUsages(sources, key) {
+	let count = 0;
+	let index = sources.indexOf(key);
+	while (index !== -1) {
+		const before = sources[index - 1];
+		const after = sources[index + key.length];
+		const isBoundary = (char) => char === void 0 || char === "\"" || char === "'" || char === "`" || char === ":";
+		if (isBoundary(before) && isBoundary(after)) count++;
+		index = sources.indexOf(key, index + key.length);
+	}
+	return count;
+}
+/**
+* Read a key from a locale document. i18next accepts both a flat key ("a.b" as a literal
+* property) and a nested path, so both are tried — flat first, as the generated sites use it.
+*/
+function readLocaleValue(data, key) {
+	const flat = data[key];
+	if (typeof flat === "string") return flat;
+	let current = data;
+	for (const part of key.split(".")) {
+		if (!current || typeof current !== "object") return null;
+		current = current[part];
+	}
+	return typeof current === "string" ? current : null;
+}
+/** Write a key, keeping the shape it already has; new keys are created flat. */
+function writeLocaleValue(data, key, value) {
+	if (typeof data[key] === "string") {
+		data[key] = value;
+		return;
+	}
+	const parts = key.split(".");
+	let current = data;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const next = current[parts[i]];
+		if (!next || typeof next !== "object") {
+			data[key] = value;
+			return;
+		}
+		current = next;
+	}
+	const leaf = parts[parts.length - 1];
+	if (typeof current[leaf] === "string") {
+		current[leaf] = value;
+		return;
+	}
+	data[key] = value;
+}
+/**
+* Render a meta tag to insert in a route that doesn't have one yet. Values that JSX can hold
+* verbatim are written as plain text/attributes; anything else goes through an expression
+* container so quotes and braces survive.
+*/
+function printMetaTag(fieldName, value) {
+	if (fieldName === "title") return !/[{}<>&\n]/.test(value) ? `<title>${value}</title>` : `<title>{"${escapeStringLiteralBody(value, "\"")}"}</title>`;
+	return `<meta name="${fieldName}" ${/["\n]/.test(value) ? `content={"${escapeStringLiteralBody(value, "\"")}"}` : `content="${value}"`} />`;
+}
+/** Start of the line `offset` sits on, so a removed tag doesn't leave a blank line behind. */
+function lineRangeStart(code, offset) {
+	const lineStart = code.lastIndexOf("\n", offset);
+	if (lineStart === -1) return offset;
+	return code.slice(lineStart + 1, offset).trim() === "" ? lineStart : offset;
+}
 const payloadEditText = z.object({
 	action: z.literal("editText"),
 	language: z.string().length(2).regex(/^[a-z]{2}$/),
@@ -94,6 +303,29 @@ const payloadArraySet = z.object({
 	arrayId: z.string().min(1),
 	items: z.array(z.string()).min(1)
 });
+const routeIdSchema = z.string().min(1).regex(/^[a-zA-Z0-9._$/()[\]+~-]+$/).refine((id) => !id.split("/").includes("..") && !id.startsWith("/"), "Invalid route id");
+const payloadGetPageMeta = z.object({
+	action: z.literal("getPageMeta"),
+	routeId: routeIdSchema,
+	/** Locale to read the translated values in. Defaults to the site's default language. */
+	language: z.string().regex(/^[a-zA-Z-]{2,10}$/).optional()
+});
+const payloadSetPageMeta = z.object({
+	action: z.literal("setPageMeta"),
+	routeId: routeIdSchema,
+	language: z.string().regex(/^[a-zA-Z-]{2,10}$/).optional(),
+	title: z.string().default(""),
+	description: z.string().default(""),
+	keywords: z.string().default(""),
+	robotsIndexing: z.boolean().default(true)
+});
+const payloadGetSiteMeta = z.object({ action: z.literal("getSiteMeta") });
+const publicImagePath = z.string().regex(/^\/[A-Za-z0-9._\-/]+$/).refine((value) => !value.includes(".."), "Invalid image path");
+const payloadSetSiteMeta = z.object({
+	action: z.literal("setSiteMeta"),
+	favicon: publicImagePath.nullable().optional(),
+	socialImage: publicImagePath.nullable().optional()
+});
 var UpstartEditorAPI = class {
 	registry = null;
 	projectRoot;
@@ -425,6 +657,529 @@ var UpstartEditorAPI = class {
 			};
 		}
 	}
+	/**
+	* Read the page metadata shown in the browser tab and in search results.
+	*
+	* Two shapes are supported, in this order: React-rendered tags (`<title>{title}</title>`
+	* fed by the loader, the shape the AI assistant generates — the text then lives in the
+	* locale files), and a static `export const meta` array.
+	*/
+	async getPageMeta(params) {
+		const parsed = payloadGetPageMeta.safeParse(params);
+		if (!parsed.success) return {
+			success: false,
+			error: `Invalid payload: ${parsed.error.message}`
+		};
+		const route = await this.resolveRouteFile(parsed.data.routeId);
+		if (!route) return {
+			success: false,
+			error: `Route file not found for "${parsed.data.routeId}"`
+		};
+		let code;
+		try {
+			code = await fs.readFile(route.filePath, "utf-8");
+		} catch {
+			return {
+				success: false,
+				error: `Failed to read route file: ${route.relativeFile}`
+			};
+		}
+		const languages = await this.listLanguages();
+		const language = await this.resolveLanguage(parsed.data.language, languages);
+		const files = await this.readAppSources();
+		const analysis = analyzeRouteMeta(code, route.relativeFile, this.createModuleLoader(files, route.filePath));
+		if (analysis.hasJsxMeta) {
+			const sources = [...files.values()].join("\n");
+			const [title, description, keywords] = await Promise.all([
+				this.describeField(analysis.title, language, sources),
+				this.describeField(analysis.description, language, sources),
+				this.describeField(analysis.keywords, language, sources)
+			]);
+			const robots = analysis.robots.origin;
+			const robotsEditable = robots.kind === "absent" || robots.kind === "literal";
+			return {
+				success: true,
+				...route,
+				mode: "jsx",
+				languages,
+				language,
+				title,
+				description,
+				keywords,
+				robotsIndexing: robots.kind === "literal" ? !/noindex/i.test(robots.value) : true,
+				robotsEditable,
+				...robotsEditable ? {} : { robotsReason: "This tag is computed by code" }
+			};
+		}
+		const plain = (value, editable, reason) => ({
+			value,
+			editable,
+			...reason ? { reason } : {},
+			translated: false,
+			shared: false,
+			prefix: "",
+			suffix: ""
+		});
+		const lookup = findMetaExport(code, route.relativeFile);
+		if (lookup.kind === "dynamic") return {
+			success: true,
+			...route,
+			mode: "meta-export",
+			languages,
+			language,
+			title: plain("", false, lookup.reason),
+			description: plain("", false, lookup.reason),
+			keywords: plain("", false, lookup.reason),
+			robotsIndexing: true,
+			robotsEditable: false,
+			robotsReason: lookup.reason
+		};
+		const entries = lookup.kind === "static" ? lookup.entries : [];
+		const robotsValue = findMetaValue(entries, "robots");
+		return {
+			success: true,
+			...route,
+			mode: "meta-export",
+			languages,
+			language,
+			title: plain(findMetaValue(entries, "title") ?? "", true),
+			description: plain(findMetaValue(entries, "description") ?? "", true),
+			keywords: plain(findMetaValue(entries, "keywords") ?? "", true),
+			robotsIndexing: robotsValue === null ? true : !/noindex/i.test(robotsValue),
+			robotsEditable: true
+		};
+	}
+	/**
+	* Write the page metadata back. Values backed by a translation key are written to the
+	* locale file of `language`; everything else is written into the route source. Returns
+	* every file that changed so the caller can commit them together.
+	*/
+	async setPageMeta(params) {
+		const parsed = payloadSetPageMeta.safeParse(params);
+		if (!parsed.success) return {
+			success: false,
+			error: `Invalid payload: ${parsed.error.message}`
+		};
+		const { routeId, title, description, keywords, robotsIndexing } = parsed.data;
+		const route = await this.resolveRouteFile(routeId);
+		if (!route) return {
+			success: false,
+			error: `Route file not found for "${routeId}"`
+		};
+		try {
+			const code = await fs.readFile(route.filePath, "utf-8");
+			const languages = await this.listLanguages();
+			const language = await this.resolveLanguage(parsed.data.language, languages);
+			const files = await this.readAppSources();
+			const analysis = analyzeRouteMeta(code, route.relativeFile, this.createModuleLoader(files, route.filePath));
+			if (!analysis.hasJsxMeta) return this.setMetaExport(route, code, {
+				title,
+				description,
+				keywords,
+				robotsIndexing
+			});
+			const sources = [...files.values()].join("\n");
+			const s = new MagicString(code);
+			const locales = /* @__PURE__ */ new Map();
+			const changedLocales = /* @__PURE__ */ new Set();
+			let sourceChanged = false;
+			const loadLocale = async (lang, namespace) => {
+				const id = `${lang}/${namespace}`;
+				const cached = locales.get(id);
+				if (cached) return cached;
+				const data = await this.readLocale(lang, namespace);
+				locales.set(id, data);
+				return data;
+			};
+			const applyField = async (element, next, fieldName) => {
+				const { origin } = element;
+				if (origin.kind === "unsupported" || origin.kind === "prop") return;
+				if (origin.kind === "absent") {
+					if (next === "" || analysis.insertOffset === null) return;
+					s.appendLeft(analysis.insertOffset, `\n${analysis.insertIndent}${printMetaTag(fieldName, next)}`);
+					sourceChanged = true;
+					return;
+				}
+				if (origin.kind === "literal") {
+					if (origin.value === next) return;
+					s.overwrite(origin.start, origin.end, escapeStringLiteralBody(next, origin.quote));
+					sourceChanged = true;
+					return;
+				}
+				const data = await loadLocale(language, origin.namespace);
+				if ((readLocaleValue(data, origin.key) ?? "") === next) return;
+				if (countKeyUsages(sources, origin.key) > 1) {
+					const newKey = await this.allocateMetaKey(origin.key, fieldName, sources, origin.namespace);
+					for (const lang of languages) {
+						const langData = await loadLocale(lang, origin.namespace);
+						const previous = readLocaleValue(langData, origin.key);
+						if (previous === null) continue;
+						writeLocaleValue(langData, newKey, previous);
+						changedLocales.add(`${lang}/${origin.namespace}`);
+					}
+					const raw = code.slice(origin.keyStart, origin.keyEnd);
+					const prefix = raw.includes(":") ? `${raw.slice(0, raw.indexOf(":") + 1)}` : "";
+					s.overwrite(origin.keyStart, origin.keyEnd, `${prefix}${newKey}`);
+					sourceChanged = true;
+					writeLocaleValue(await loadLocale(language, origin.namespace), newKey, next);
+				} else writeLocaleValue(data, origin.key, next);
+				changedLocales.add(`${language}/${origin.namespace}`);
+			};
+			await applyField(analysis.title, title, "title");
+			await applyField(analysis.description, description, "description");
+			await applyField(analysis.keywords, keywords, "keywords");
+			const robots = analysis.robots;
+			if (robotsIndexing) {
+				if (robots.origin.kind === "literal" && robots.elementStart !== void 0) {
+					s.remove(lineRangeStart(code, robots.elementStart), robots.elementEnd);
+					sourceChanged = true;
+				}
+			} else if (robots.origin.kind === "literal") {
+				if (!/noindex/i.test(robots.origin.value)) {
+					s.overwrite(robots.origin.start, robots.origin.end, "noindex, nofollow");
+					sourceChanged = true;
+				}
+			} else if (robots.origin.kind === "absent" && analysis.insertOffset !== null) {
+				s.appendLeft(analysis.insertOffset, `\n${analysis.insertIndent}${printMetaTag("robots", "noindex, nofollow")}`);
+				sourceChanged = true;
+			}
+			const filePaths = [];
+			if (sourceChanged) {
+				await fs.writeFile(route.filePath, s.toString());
+				filePaths.push(route.filePath);
+				this.registry = null;
+			}
+			for (const id of changedLocales) {
+				const [lang, namespace] = id.split("/");
+				const data = locales.get(id);
+				if (!data) continue;
+				const localePath = this.localePath(lang, namespace);
+				await fs.writeFile(localePath, `${JSON.stringify(data, null, 2)}\n`);
+				filePaths.push(localePath);
+			}
+			return {
+				success: true,
+				filePaths
+			};
+		} catch (err) {
+			return {
+				success: false,
+				error: String(err)
+			};
+		}
+	}
+	/**
+	* Read the site-wide settings rendered by `app/root.tsx`: the browser-tab icon and the
+	* image shown when a page is shared on social networks.
+	*/
+	async getSiteMeta(params) {
+		const parsed = payloadGetSiteMeta.safeParse(params);
+		if (!parsed.success) return {
+			success: false,
+			error: `Invalid payload: ${parsed.error.message}`
+		};
+		const config = await this.readSiteConfig();
+		if (!config) return {
+			success: false,
+			error: "This site has no app/config/site.json"
+		};
+		const root = await this.readRootFile();
+		const upgrade = root ? ensureRootSiteMeta(root.code, root.relativeFile) : null;
+		return {
+			success: true,
+			favicon: typeof config.favicon === "string" ? config.favicon : null,
+			socialImage: typeof config.socialImage === "string" ? config.socialImage : null,
+			editable: !!upgrade?.ok,
+			...upgrade && !upgrade.ok ? { reason: upgrade.reason } : {},
+			...root ? {} : { reason: "This site has no app/root.tsx" }
+		};
+	}
+	/**
+	* Write the site-wide settings to `app/config/site.json`, upgrading `app/root.tsx` to
+	* render them if it does not already. The image files themselves are copied into the
+	* workspace by the caller, which has bucket access.
+	*/
+	async setSiteMeta(params) {
+		const parsed = payloadSetSiteMeta.safeParse(params);
+		if (!parsed.success) return {
+			success: false,
+			error: `Invalid payload: ${parsed.error.message}`
+		};
+		const { favicon, socialImage } = parsed.data;
+		if (favicon === void 0 && socialImage === void 0) return {
+			success: true,
+			filePaths: []
+		};
+		try {
+			const config = await this.readSiteConfig();
+			if (!config) return {
+				success: false,
+				error: "This site has no app/config/site.json"
+			};
+			const filePaths = [];
+			const root = await this.readRootFile();
+			if (!root) return {
+				success: false,
+				error: "This site has no app/root.tsx"
+			};
+			const upgrade = ensureRootSiteMeta(root.code, root.relativeFile);
+			if (!upgrade.ok) return {
+				success: false,
+				error: `${upgrade.reason} — ask Upsie to update it`
+			};
+			if (upgrade.changed) {
+				await fs.writeFile(root.filePath, upgrade.code);
+				filePaths.push(root.filePath);
+				this.registry = null;
+			}
+			const next = { ...config };
+			const apply = (key, value) => {
+				if (value === void 0) return;
+				if (value === null) delete next[key];
+				else next[key] = value;
+			};
+			apply("favicon", favicon);
+			apply("socialImage", socialImage);
+			const configPath = path.join(this.projectRoot, "app", "config", "site.json");
+			await fs.writeFile(configPath, `${JSON.stringify(next, null, 2)}\n`);
+			filePaths.push(configPath);
+			return {
+				success: true,
+				filePaths
+			};
+		} catch (err) {
+			return {
+				success: false,
+				error: String(err)
+			};
+		}
+	}
+	async readSiteConfig() {
+		try {
+			const raw = await fs.readFile(path.join(this.projectRoot, "app", "config", "site.json"), "utf-8");
+			const parsed = JSON.parse(raw);
+			return parsed && typeof parsed === "object" ? parsed : null;
+		} catch {
+			return null;
+		}
+	}
+	async readRootFile() {
+		for (const ext of ["tsx", "jsx"]) {
+			const filePath = path.join(this.projectRoot, "app", `root.${ext}`);
+			try {
+				return {
+					filePath,
+					relativeFile: path.relative(this.projectRoot, filePath),
+					code: await fs.readFile(filePath, "utf-8")
+				};
+			} catch {}
+		}
+		return null;
+	}
+	/** Rewrite a static `export const meta` array (routes that don't render meta as JSX). */
+	async setMetaExport(route, code, values) {
+		const lookup = findMetaExport(code, route.relativeFile);
+		if (lookup.kind === "dynamic") return {
+			success: false,
+			error: `${lookup.reason} and cannot be edited here`
+		};
+		let entries = lookup.kind === "static" ? lookup.entries : [];
+		entries = upsertMetaValue(entries, "title", values.title);
+		entries = upsertMetaValue(entries, "description", values.description);
+		entries = upsertMetaValue(entries, "keywords", values.keywords);
+		entries = upsertMetaValue(entries, "robots", values.robotsIndexing ? "" : "noindex, nofollow");
+		const s = new MagicString(code);
+		if (lookup.kind === "static") {
+			const lineStart = code.lastIndexOf("\n", lookup.arrayStart) + 1;
+			const indent = code.slice(lineStart, lookup.arrayStart).match(/^[ \t]*/)?.[0] ?? "";
+			s.overwrite(lookup.arrayStart, lookup.arrayEnd, printMetaArray(entries, indent));
+		} else {
+			const insertAt = findMetaInsertOffset(code, route.relativeFile);
+			s.appendLeft(insertAt, `\nexport const meta = () => ${printMetaArray(entries, "")};\n`);
+		}
+		await fs.writeFile(route.filePath, s.toString());
+		this.registry = null;
+		return {
+			success: true,
+			filePaths: [route.filePath]
+		};
+	}
+	/**
+	* Render the read-only parts around an editable value: literal chunks as-is, other
+	* translations resolved to the text they currently produce, anything dynamic as "…".
+	*/
+	async renderSegments(segments, language) {
+		return (await Promise.all(segments.map(async (segment) => {
+			if ("text" in segment) return segment.text;
+			const { origin } = segment;
+			if (origin.kind === "literal") return origin.value;
+			if (origin.kind === "i18n") return readLocaleValue(await this.readLocale(language, origin.namespace), origin.key) ?? "";
+			return "…";
+		}))).join("");
+	}
+	/** Turn an analyzed meta element into what the settings panel needs to render. */
+	async describeField(element, language, sources) {
+		const { origin } = element;
+		const [prefix, suffix] = await Promise.all([this.renderSegments(element.prefixSegments, language), this.renderSegments(element.suffixSegments, language)]);
+		const base = {
+			prefix,
+			suffix
+		};
+		if (origin.kind === "unsupported" || origin.kind === "prop") {
+			const reason = origin.kind === "prop" ? "This value is set by the page's SEO component" : origin.reason;
+			return {
+				...base,
+				value: "",
+				editable: false,
+				reason,
+				translated: false,
+				shared: false
+			};
+		}
+		if (origin.kind === "absent") return {
+			...base,
+			value: "",
+			editable: true,
+			translated: false,
+			shared: false
+		};
+		if (origin.kind === "literal") return {
+			...base,
+			value: origin.value,
+			editable: true,
+			translated: false,
+			shared: false
+		};
+		const data = await this.readLocale(language, origin.namespace);
+		return {
+			...base,
+			value: readLocaleValue(data, origin.key) ?? "",
+			editable: true,
+			translated: true,
+			i18nKey: origin.key,
+			shared: countKeyUsages(sources, origin.key) > 1
+		};
+	}
+	/** Languages the site ships translations for, from `app/locales/<lang>/`. */
+	async listLanguages() {
+		try {
+			return (await fs.readdir(path.join(this.projectRoot, "app", "locales"), { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+		} catch {
+			return [];
+		}
+	}
+	/** Requested language when it exists, else the site default, else the first available one. */
+	async resolveLanguage(requested, languages) {
+		if (requested && languages.includes(requested)) return requested;
+		try {
+			const raw = await fs.readFile(path.join(this.projectRoot, "app", "config", "site.json"), "utf-8");
+			const config = JSON.parse(raw);
+			if (config.defaultLanguage && languages.includes(config.defaultLanguage)) return config.defaultLanguage;
+		} catch {}
+		return languages[0] ?? "en";
+	}
+	localePath(language, namespace) {
+		return path.join(this.projectRoot, "app", "locales", language, `${namespace}.json`);
+	}
+	async readLocale(language, namespace) {
+		try {
+			const raw = await fs.readFile(this.localePath(language, namespace), "utf-8");
+			const parsed = JSON.parse(raw);
+			return parsed && typeof parsed === "object" ? parsed : {};
+		} catch {
+			return {};
+		}
+	}
+	/**
+	* Every source file of the app, keyed by absolute path. Serves two purposes at once:
+	* telling whether a translation key is referenced more than once, and following a route
+	* to the shared component it hands its metadata to.
+	*/
+	async readAppSources() {
+		const files = /* @__PURE__ */ new Map();
+		const visit = async (dir) => {
+			const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+			for (const entry of entries) {
+				const full = path.join(dir, entry.name);
+				if (entry.isDirectory()) {
+					if (entry.name === "node_modules" || entry.name === "locales" || entry.name.startsWith(".")) continue;
+					await visit(full);
+				} else if (/\.(tsx?|jsx?)$/.test(entry.name)) try {
+					files.set(full, await fs.readFile(full, "utf-8"));
+				} catch {}
+			}
+		};
+		await visit(path.join(this.projectRoot, "app"));
+		return files;
+	}
+	/**
+	* Resolve the import specifiers a route can use for a local component — "~/components/X"
+	* (the template's alias for `app/`) and relative paths — against the files already read.
+	*/
+	createModuleLoader(files, fromFile) {
+		return (specifier) => {
+			let base;
+			if (specifier.startsWith("~/")) base = path.join(this.projectRoot, "app", specifier.slice(2));
+			else if (specifier.startsWith(".")) base = path.resolve(path.dirname(fromFile), specifier);
+			else return null;
+			for (const candidate of [
+				base,
+				`${base}.tsx`,
+				`${base}.ts`,
+				`${base}.jsx`,
+				`${base}.js`,
+				path.join(base, "index.tsx"),
+				path.join(base, "index.ts")
+			]) {
+				const code = files.get(candidate);
+				if (code !== void 0) return {
+					code,
+					filePath: candidate
+				};
+			}
+			return null;
+		};
+	}
+	/**
+	* Pick a free key dedicated to this page's meta, derived from the shared key
+	* ("atelier.title" + "title" -> "atelier.meta.title"). Never reuses a key that already
+	* exists in the locales or is referenced by the code.
+	*/
+	async allocateMetaKey(sharedKey, fieldName, sources, namespace) {
+		const base = sharedKey.split(".")[0] || "page";
+		const languages = await this.listLanguages();
+		const documents = await Promise.all(languages.map((lang) => this.readLocale(lang, namespace)));
+		for (let attempt = 0; attempt < 50; attempt++) {
+			const candidate = attempt === 0 ? `${base}.meta.${fieldName}` : `${base}.meta.${fieldName}${attempt + 1}`;
+			if (!(countKeyUsages(sources, candidate) > 0 || documents.some((doc) => readLocaleValue(doc, candidate) !== null))) return candidate;
+		}
+		return `${base}.meta.${fieldName}.${Date.now()}`;
+	}
+	/**
+	* Resolve a react-router route id ("routes/_layout._index", "root") to its source file
+	* inside the workspace. Never escapes `<projectRoot>/app`.
+	*/
+	async resolveRouteFile(routeId) {
+		const appDir = path.join(this.projectRoot, "app");
+		for (const ext of [
+			"tsx",
+			"ts",
+			"jsx",
+			"js"
+		]) {
+			const filePath = path.join(appDir, `${routeId}.${ext}`);
+			const resolved = path.resolve(filePath);
+			if (resolved !== appDir && !resolved.startsWith(appDir + path.sep)) continue;
+			try {
+				await fs.access(resolved);
+				return {
+					filePath: resolved,
+					relativeFile: path.relative(this.projectRoot, resolved)
+				};
+			} catch {}
+		}
+		return null;
+	}
 	/** Parse "<relativeFile>:<offset>" into an absolute path + numeric offset. */
 	resolveArrayId(arrayId) {
 		const sep = arrayId.lastIndexOf(":");
@@ -529,6 +1284,6 @@ var UpstartEditorAPI = class {
 	}
 };
 //#endregion
-export { UpstartEditorAPI, escapeStringLiteralBody, payloadArrayItemAdd, payloadArrayItemDelete, payloadArraySet, payloadEditClassName, payloadEditImage, payloadEditText, payloadEditTextDirect };
+export { UpstartEditorAPI, escapeStringLiteralBody, payloadArrayItemAdd, payloadArrayItemDelete, payloadArraySet, payloadEditClassName, payloadEditImage, payloadEditText, payloadEditTextDirect, payloadGetPageMeta, payloadGetSiteMeta, payloadSetPageMeta, payloadSetSiteMeta, readLocaleValue, writeLocaleValue };
 
 //# sourceMappingURL=upstart-editor-api.js.map