@upstart.gg/vite-plugins 0.1.60 → 0.1.62

package/src/upstart-editor-api.ts

@@ -4,6 +4,8 @@ import fs from "fs/promises";
 import path from "path";
 import z from "zod";
 import type { EditableEntry } from "./vite-plugin-upstart-attrs";
+import { analyzeRouteMeta, type MetaElement, type MetaSegment, type ModuleLoader } from "./page-meta";
+import { ensureRootSiteMeta } from "./site-meta";
 
 /**
  * Escape user-typed text so it can be safely written as the BODY of a JS string
@@ -79,6 +81,252 @@ function inferArrayQuote(code: string, elements: AstNode[]): string {
   return '"';
 }
 
+/** One `{ key: "value" }` entry of a route's `meta` array, keys in source order. */
+type StaticMetaEntry = { key: string; value: string }[];
+
+type MetaExportLookup =
+  | { kind: "none" }
+  | { kind: "dynamic"; reason: string }
+  | { kind: "static"; arrayStart: number; arrayEnd: number; entries: StaticMetaEntry[] };
+
+/** Read the ArrayExpression a `meta` export resolves to, or explain why we can't. */
+function readMetaArray(node: AstNode): { ok: true; array: AstNode } | { ok: false; reason: string } {
+  if (node.type === "ArrayExpression") return { ok: true, array: node };
+  if (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression") {
+    const body = node.body as AstNode;
+    if (body.type === "ArrayExpression") return { ok: true, array: body };
+    if (body.type === "BlockStatement") {
+      const statements = (body.body as AstNode[]) ?? [];
+      const ret = statements.find((st) => st.type === "ReturnStatement");
+      const argument = ret?.argument as AstNode | null | undefined;
+      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: (AstNode | null)[]): StaticMetaEntry[] | null {
+  const entries: StaticMetaEntry[] = [];
+  for (const element of elements) {
+    if (!element || element.type !== "ObjectExpression") return null;
+    const entry: StaticMetaEntry = [];
+    for (const prop of (element.properties as AstNode[]) ?? []) {
+      if (prop.type !== "Property" || prop.computed || prop.shorthand || prop.kind !== "init") return null;
+      const key = prop.key as AstNode;
+      const value = prop.value as AstNode;
+      const keyName =
+        key.type === "Identifier"
+          ? (key.name as string)
+          : 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: string, filePath: string): MetaExportLookup {
+  const ast = parseSync(filePath, code, { sourceType: "module" });
+  const body = (ast.program?.body as AstNode[] | undefined) ?? [];
+
+  for (const statement of body) {
+    if (statement.type !== "ExportNamedDeclaration") continue;
+    const declaration = statement.declaration as AstNode | null;
+
+    // export { meta } / export { x as meta } — we can't follow the reference.
+    if (!declaration) {
+      const specifiers = (statement.specifiers as AstNode[]) ?? [];
+      const exported = specifiers.some((spec) => {
+        const name = spec.exported as AstNode | undefined;
+        return name?.type === "Identifier" && name.name === "meta";
+      });
+      if (exported) return { kind: "dynamic", reason: "The page meta is exported indirectly" };
+      continue;
+    }
+
+    let source: AstNode | null = null;
+    if (declaration.type === "VariableDeclaration") {
+      for (const decl of (declaration.declarations as AstNode[]) ?? []) {
+        const id = decl.id as AstNode;
+        if (id.type === "Identifier" && id.name === "meta") source = (decl.init as AstNode) ?? null;
+      }
+    } else if (declaration.type === "FunctionDeclaration") {
+      const id = declaration.id as AstNode | null;
+      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 as (AstNode | null)[]) ?? []);
+    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: string, filePath: string): number {
+  const ast = parseSync(filePath, code, { sourceType: "module" });
+  const body = (ast.program?.body as AstNode[] | undefined) ?? [];
+  let offset: number | null = 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: StaticMetaEntry[], indent: string): string {
+  if (entries.length === 0) return "[]";
+  const lines = entries.map((entry) => {
+    const props = entry
+      .map(({ key, value }) => {
+        const printedKey = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+          ? key
+          : `"${escapeStringLiteralBody(key, '"')}"`;
+        return `${printedKey}: "${escapeStringLiteralBody(value, '"')}"`;
+      })
+      .join(", ");
+    return `${indent}  { ${props} },`;
+  });
+  return `[\n${lines.join("\n")}\n${indent}]`;
+}
+
+/** Read the value of `{ name: <name>, content: X }` (or `{ title: X }` when name is "title"). */
+function findMetaValue(entries: StaticMetaEntry[], name: string): string | null {
+  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: StaticMetaEntry[], name: string, value: string): StaticMetaEntry[] {
+  const matches = (entry: StaticMetaEntry) =>
+    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: StaticMetaEntry =
+    name === "title"
+      ? [{ key: "title", value }]
+      : [
+          { key: "name", value: name },
+          { key: "content", value },
+        ];
+
+  if (index === -1) {
+    // Title first, everything else appended — matches how meta arrays are usually written.
+    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: string, key: string): number {
+  let count = 0;
+  let index = sources.indexOf(key);
+  while (index !== -1) {
+    // Only count whole keys: "about.meta" must not match inside "about.meta.title".
+    const before = sources[index - 1];
+    const after = sources[index + key.length];
+    const isBoundary = (char: string | undefined) =>
+      char === undefined || 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.
+ */
+export function readLocaleValue(data: Record<string, unknown>, key: string): string | null {
+  const flat = data[key];
+  if (typeof flat === "string") return flat;
+  let current: unknown = data;
+  for (const part of key.split(".")) {
+    if (!current || typeof current !== "object") return null;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return typeof current === "string" ? current : null;
+}
+
+/** Write a key, keeping the shape it already has; new keys are created flat. */
+export function writeLocaleValue(data: Record<string, unknown>, key: string, value: string): void {
+  if (typeof data[key] === "string") {
+    data[key] = value;
+    return;
+  }
+  const parts = key.split(".");
+  let current: Record<string, unknown> = 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 as Record<string, unknown>;
+  }
+  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: string, value: string): string {
+  if (fieldName === "title") {
+    const plain = !/[{}<>&\n]/.test(value);
+    return plain ? `<title>${value}</title>` : `<title>{"${escapeStringLiteralBody(value, '"')}"}</title>`;
+  }
+  const attribute = /["\n]/.test(value)
+    ? `content={"${escapeStringLiteralBody(value, '"')}"}`
+    : `content="${value}"`;
+  return `<meta name="${fieldName}" ${attribute} />`;
+}
+
+/** Start of the line `offset` sits on, so a removed tag doesn't leave a blank line behind. */
+function lineRangeStart(code: string, offset: number): number {
+  const lineStart = code.lastIndexOf("\n", offset);
+  if (lineStart === -1) return offset;
+  return code.slice(lineStart + 1, offset).trim() === "" ? lineStart : offset;
+}
+
 export const payloadEditText = z.object({
   action: z.literal("editText"),
   language: z
@@ -146,6 +394,117 @@ export const payloadArraySet = z.object({
 
 export type PayloadArraySet = z.infer<typeof payloadArraySet>;
 
+// React-router route id, as reported by the client runtime (e.g. "routes/_layout._index",
+// "root"). Resolved to `<projectRoot>/app/<routeId>.<ext>` — see `resolveRouteFile`.
+const routeIdSchema = z
+  .string()
+  .min(1)
+  // Flat-route ids carry the file-name conventions: optional segments "($lang)", dynamic
+  // "$slug", escaped characters "sitemap[.]xml", layout prefixes "_layout.".
+  .regex(/^[a-zA-Z0-9._$/()[\]+~-]+$/)
+  .refine((id) => !id.split("/").includes("..") && !id.startsWith("/"), "Invalid route id");
+
+export 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(),
+});
+
+export type PayloadGetPageMeta = z.infer<typeof payloadGetPageMeta>;
+
+export const payloadSetPageMeta = z.object({
+  action: z.literal("setPageMeta"),
+  routeId: routeIdSchema,
+  language: z
+    .string()
+    .regex(/^[a-zA-Z-]{2,10}$/)
+    .optional(),
+  // Empty string removes the corresponding meta tag (keywords, robots) or clears the text.
+  title: z.string().default(""),
+  description: z.string().default(""),
+  keywords: z.string().default(""),
+  robotsIndexing: z.boolean().default(true),
+});
+
+export type PayloadSetPageMeta = z.infer<typeof payloadSetPageMeta>;
+
+export const payloadGetSiteMeta = z.object({
+  action: z.literal("getSiteMeta"),
+});
+
+export type PayloadGetSiteMeta = z.infer<typeof payloadGetSiteMeta>;
+
+// Site-root-relative path of an image already copied into the workspace, e.g. "/images/x.webp".
+const publicImagePath = z
+  .string()
+  .regex(/^\/[A-Za-z0-9._\-/]+$/)
+  .refine((value) => !value.includes(".."), "Invalid image path");
+
+export const payloadSetSiteMeta = z.object({
+  action: z.literal("setSiteMeta"),
+  // `null` clears the setting, `undefined` leaves it untouched.
+  favicon: publicImagePath.nullable().optional(),
+  socialImage: publicImagePath.nullable().optional(),
+});
+
+export type PayloadSetSiteMeta = z.infer<typeof payloadSetSiteMeta>;
+
+export type GetSiteMetaResult =
+  | {
+      success: true;
+      favicon: string | null;
+      socialImage: string | null;
+      /** False when root.tsx was customized and can no longer be upgraded automatically. */
+      editable: boolean;
+      reason?: string;
+    }
+  | { success: false; error: string };
+
+export type SetSiteMetaResult = { success: true; filePaths: string[] } | { success: false; error: string };
+
+export interface PageMetaField {
+  value: string;
+  editable: boolean;
+  /** Why the field is read-only (dynamic value, computed title…). */
+  reason?: string;
+  /** True when the text lives in the locale files rather than in the route source. */
+  translated: boolean;
+  i18nKey?: string;
+  /**
+   * True when the translation key is also used elsewhere (typically as a heading on the
+   * page). Saving then moves this page's meta onto its own key instead of rewriting the
+   * shared one.
+   */
+  shared: boolean;
+  /** Static text rendered around the value, e.g. `{`${title} | Acme`}`. */
+  prefix: string;
+  suffix: string;
+}
+
+export type GetPageMetaResult =
+  | {
+      success: true;
+      filePath: string;
+      relativeFile: string;
+      /** "jsx" for React-rendered meta tags, "meta-export" for a `export const meta` route. */
+      mode: "jsx" | "meta-export";
+      languages: string[];
+      language: string;
+      title: PageMetaField;
+      description: PageMetaField;
+      keywords: PageMetaField;
+      robotsIndexing: boolean;
+      robotsEditable: boolean;
+      robotsReason?: string;
+    }
+  | { success: false; error: string };
+
+export type SetPageMetaResult = { success: true; filePaths: string[] } | { success: false; error: string };
+
 export interface EditableRegistry {
   version: number;
   generatedAt: string;
@@ -492,6 +851,588 @@ export class UpstartEditorAPI {
     }
   }
 
+  /**
+   * 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: PayloadGetPageMeta): Promise<GetPageMetaResult> {
+    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: string;
+    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: string, editable: boolean, reason?: string): PageMetaField => ({
+      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: PayloadSetPageMeta): Promise<SetPageMetaResult> {
+    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);
+      // Locale documents are loaded once, mutated by every field, then written back.
+      const locales = new Map<string, Record<string, unknown>>();
+      const changedLocales = new Set<string>();
+      let sourceChanged = false;
+
+      const loadLocale = async (lang: string, namespace: string) => {
+        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: MetaElement, next: string, fieldName: string) => {
+        const { origin } = element;
+        // "prop" is resolved while analyzing; it should never reach here, and writing it
+        // would have nowhere to go.
+        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;
+        }
+
+        // Translation-backed value: write to the locale file rather than to the route.
+        const data = await loadLocale(language, origin.namespace);
+        const current = readLocaleValue(data, origin.key) ?? "";
+        if (current === next) return;
+
+        if (countKeyUsages(sources, origin.key) > 1) {
+          // The key is also used elsewhere (usually a heading rendered on the page), so
+          // give this page its own key instead of silently rewriting the shared text.
+          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);
+            // A language that never translated the shared key stays untranslated: writing an
+            // empty string there would render an empty title instead of falling back.
+            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");
+
+      // Robots is a plain on/off tag: absent means "indexable".
+      const robots = analysis.robots;
+      if (robotsIndexing) {
+        if (robots.origin.kind === "literal" && robots.elementStart !== undefined) {
+          s.remove(lineRangeStart(code, robots.elementStart), robots.elementEnd as number);
+          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: string[] = [];
+      if (sourceChanged) {
+        await fs.writeFile(route.filePath, s.toString());
+        filePaths.push(route.filePath);
+        // Byte offsets in the registry are stale after a source rewrite.
+        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: PayloadGetSiteMeta): Promise<GetSiteMetaResult> {
+    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" };
+
+    // Report up front whether saving would be able to upgrade root.tsx, so the panel can
+    // stay read-only instead of failing at save time.
+    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: PayloadSetSiteMeta): Promise<SetSiteMetaResult> {
+    const parsed = payloadSetSiteMeta.safeParse(params);
+    if (!parsed.success) {
+      return { success: false, error: `Invalid payload: ${parsed.error.message}` };
+    }
+    const { favicon, socialImage } = parsed.data;
+    if (favicon === undefined && socialImage === undefined) {
+      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: string[] = [];
+      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);
+        // Byte offsets recorded for inline editing no longer match the rewritten file.
+        this.registry = null;
+      }
+
+      const next = { ...config };
+      const apply = (key: "favicon" | "socialImage", value: string | null | undefined) => {
+        if (value === undefined) 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) };
+    }
+  }
+
+  private async readSiteConfig(): Promise<Record<string, unknown> | null> {
+    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 as Record<string, unknown>) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async readRootFile(): Promise<{ filePath: string; relativeFile: string; code: string } | null> {
+    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 {
+        // try next extension
+      }
+    }
+    return null;
+  }
+
+  /** Rewrite a static `export const meta` array (routes that don't render meta as JSX). */
+  private async setMetaExport(
+    route: { filePath: string; relativeFile: string },
+    code: string,
+    values: { title: string; description: string; keywords: string; robotsIndexing: boolean },
+  ): Promise<SetPageMetaResult> {
+    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") {
+      // Indentation of the line the array starts on, so the rewritten literal lines up.
+      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 {
+      // No `meta` export yet: insert one after the imports (or at the end of the file).
+      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 "…".
+   */
+  private async renderSegments(segments: MetaSegment[], language: string): Promise<string> {
+    const parts = 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") {
+          const data = await this.readLocale(language, origin.namespace);
+          return readLocaleValue(data, origin.key) ?? "";
+        }
+        return "…";
+      }),
+    );
+    return parts.join("");
+  }
+
+  /** Turn an analyzed meta element into what the settings panel needs to render. */
+  private async describeField(
+    element: MetaElement,
+    language: string,
+    sources: string,
+  ): Promise<PageMetaField> {
+    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>/`. */
+  private async listLanguages(): Promise<string[]> {
+    try {
+      const entries = await fs.readdir(path.join(this.projectRoot, "app", "locales"), {
+        withFileTypes: true,
+      });
+      return entries
+        .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. */
+  private async resolveLanguage(requested: string | undefined, languages: string[]): Promise<string> {
+    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) as { defaultLanguage?: string | null };
+      if (config.defaultLanguage && languages.includes(config.defaultLanguage)) {
+        return config.defaultLanguage;
+      }
+    } catch {
+      // no site config — fall through
+    }
+    return languages[0] ?? "en";
+  }
+
+  private localePath(language: string, namespace: string): string {
+    return path.join(this.projectRoot, "app", "locales", language, `${namespace}.json`);
+  }
+
+  private async readLocale(language: string, namespace: string): Promise<Record<string, unknown>> {
+    try {
+      const raw = await fs.readFile(this.localePath(language, namespace), "utf-8");
+      const parsed = JSON.parse(raw);
+      return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+    } 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.
+   */
+  private async readAppSources(): Promise<Map<string, string>> {
+    const files = new Map<string, string>();
+    const visit = async (dir: string): Promise<void> => {
+      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 {
+            // unreadable file — ignore
+          }
+        }
+      }
+    };
+    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.
+   */
+  private createModuleLoader(files: Map<string, string>, fromFile: string): ModuleLoader {
+    return (specifier) => {
+      let base: string;
+      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; // a package, not a file of the site
+      }
+      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 !== undefined) 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.
+   */
+  private async allocateMetaKey(
+    sharedKey: string,
+    fieldName: string,
+    sources: string,
+    namespace: string,
+  ): Promise<string> {
+    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}`;
+      const taken =
+        countKeyUsages(sources, candidate) > 0 ||
+        documents.some((doc) => readLocaleValue(doc, candidate) !== null);
+      if (!taken) 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`.
+   */
+  private async resolveRouteFile(
+    routeId: string,
+  ): Promise<{ filePath: string; relativeFile: string } | null> {
+    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 {
+        // try next extension
+      }
+    }
+    return null;
+  }
+
   /** Parse "<relativeFile>:<offset>" into an absolute path + numeric offset. */
   private resolveArrayId(arrayId: string): { filePath: string; relativeFile: string; offset: number } | null {
     const sep = arrayId.lastIndexOf(":");