@jxsuite/studio 3.0.0 → 4.0.0

package/src/services/import-run.ts

@@ -0,0 +1,158 @@
+/**
+ * Import-run.ts — the live state of a site import, for the transcript to draw.
+ *
+ * An import takes minutes and reports a line at a time. Those lines used to render into the New
+ * Project modal and die with it: a successful import destroyed its own account of what it had done
+ * at the moment it handed off. Now the run belongs to a tool call, so the record is keyed by that
+ * call's id and the chip and its progress are one thing rather than two.
+ *
+ * Reactive, so `panels/ai-panel.ts`'s watcher repaints on it through the same rAF coalescer that
+ * carries streaming tokens — a crawl emitting a line per page cannot outrun the frame rate.
+ *
+ * @license MIT
+ */
+
+import { reactive } from "../reactivity";
+
+import type { ImportProgressEvent } from "../types";
+
+/**
+ * Lines kept per run.
+ *
+ * A wide crawl emits one per page plus one per asset batch, and every line is also held in the
+ * session's localStorage budget once the tool result lands — so there is a ceiling, and it is here.
+ * It was 200 back when the view showed the last SIX of them and the rest existed only to be
+ * summarised; the transcript now renders the whole log in a scroller the reader owns, so the number
+ * that matters is how far back they can scroll.
+ */
+export const MAX_LOG_LINES = 500;
+
+export interface ImportRunRecord {
+  /** The tool-call id — the join key with the chip the transcript draws. */
+  id: string;
+  url: string;
+  directory: string;
+  phase: string;
+  message: string;
+  current: number | null;
+  total: number | null;
+  log: ImportProgressEvent[];
+  /** Lines the pipeline marked with `⚠`, kept apart so the summary can name them. */
+  warnings: string[];
+  status: "running" | "done" | "failed" | "stopped";
+  error: string;
+}
+
+/**
+ * One run at a time, because one project is created at a time and `import_site` is `no-project`
+ * tiered. Keyed rather than bare so a finished run still renders under its own chip after the next
+ * one starts, which is what makes the transcript readable after two attempts.
+ */
+const runs = reactive<{ records: ImportRunRecord[] }>({ records: [] });
+
+/** Runs kept before the oldest is dropped. Two attempts and a retry is the realistic ceiling. */
+const MAX_RUNS = 5;
+
+/** Aborts the in-flight run. Owned here because `ToolRegistry.execute` cannot be handed a signal. */
+let controller: AbortController | null = null;
+
+/**
+ * Open a run record and return the signal its request should carry.
+ *
+ * @param {string} id - The tool-call id.
+ * @param {{ url: string; directory: string }} init
+ * @returns {AbortSignal}
+ */
+export function beginImportRun(id: string, init: { url: string; directory: string }): AbortSignal {
+  controller?.abort();
+  controller = new AbortController();
+  runs.records.push({
+    current: null,
+    directory: init.directory,
+    error: "",
+    id,
+    log: [],
+    message: "Starting…",
+    phase: "start",
+    status: "running",
+    total: null,
+    url: init.url,
+    warnings: [],
+  });
+  if (runs.records.length > MAX_RUNS) {
+    runs.records.shift();
+  }
+  return controller.signal;
+}
+
+/**
+ * Record one progress line against a run.
+ *
+ * @param {string} id
+ * @param {ImportProgressEvent} evt
+ */
+export function recordImportProgress(id: string, evt: ImportProgressEvent): void {
+  const record = runs.records.find((r) => r.id === id);
+  if (!record) {
+    return;
+  }
+  record.phase = evt.phase;
+  record.message = evt.message;
+  record.current = evt.current ?? null;
+  record.total = evt.total ?? null;
+  record.log.push(evt);
+  if (record.log.length > MAX_LOG_LINES) {
+    record.log.shift();
+  }
+  /* The pipeline reports a soft failure by prefixing its progress line, and `ImportSiteResult`'s
+     own `warnings` array does not cross the HTTP boundary — so this is the only place they can be
+     recovered from, and the summary needs them to be honest about what was skipped. */
+  if (evt.message.startsWith("⚠")) {
+    record.warnings.push(evt.message.replace(/^⚠\s*/, ""));
+  }
+}
+
+/**
+ * Close a run.
+ *
+ * @param {string} id
+ * @param {{ status: Exclude<ImportRunRecord["status"], "running">; error?: string }} outcome
+ */
+export function finishImportRun(
+  id: string,
+  outcome: { status: Exclude<ImportRunRecord["status"], "running">; error?: string },
+): void {
+  const record = runs.records.find((r) => r.id === id);
+  if (record) {
+    record.status = outcome.status;
+    record.error = outcome.error ?? "";
+  }
+  controller = null;
+}
+
+/**
+ * The record for one tool call, or null. Reactive — read it inside an `effect()` to repaint on it.
+ *
+ * @param {string} id
+ * @returns {ImportRunRecord | null}
+ */
+export function importRun(id: string): ImportRunRecord | null {
+  return runs.records.find((r) => r.id === id) ?? null;
+}
+
+/** The run still going, or null. What the panel's watcher tracks. */
+export function activeImportRun(): ImportRunRecord | null {
+  return runs.records.find((r) => r.status === "running") ?? null;
+}
+
+/** Abort the in-flight run. Called from `assistant.stop`, which cannot reach the tool directly. */
+export function abortImportRun(): void {
+  controller?.abort();
+  controller = null;
+}
+
+/** Drop every record. For New Chat and for tests. */
+export function resetImportRuns(): void {
+  abortImportRun();
+  runs.records.length = 0;
+}

package/src/services/import-seed.ts

@@ -0,0 +1,120 @@
+/**
+ * Import-seed.ts — the New Project Import form's hand-off to the assistant.
+ *
+ * The wizard collects a URL, crawl options, a model and a brief, then closes; the assistant takes
+ * the turn and runs the import as a tool call. This holds what the form gathered for the one turn
+ * that consumes it.
+ *
+ * **Module state, and deliberately NOT a copy of `agent-seed.ts`.** That one uses localStorage keyed
+ * by project root because the project it seeds opens in a NEW WINDOW, and the key is the
+ * cross-window channel. Neither half of that applies here: the project does not exist yet at
+ * hand-off time, so there is no root to key on, and the assistant taking the turn is in this window
+ * — `import_site` is `no-project` tiered precisely because it runs before there is a project. A
+ * localStorage clone would be a channel with nothing on the other end and a key that cannot be
+ * computed.
+ *
+ * @license MIT
+ */
+
+import type { ImportBreakpointPolicy } from "../types";
+
+/** What the wizard gathered, as the tool needs it. */
+export interface ImportBrief {
+  /** Absolute http(s) URL of the site to clone. */
+  url: string;
+  /** Human project name (the wizard prefills it from the hostname). */
+  name: string;
+  /** Absolute destination directory, already resolved from Location + folder name. */
+  directory: string;
+  depth: number;
+  maxPages: number;
+  /**
+   * How many of the site's declared breakpoints the project keeps.
+   *
+   * A real site declares as many as it has accumulated frameworks — nine is ordinary — and each one
+   * is a canvas size in Studio and a column in every style editor. The wizard defaults this to
+   * three because that is the complaint it answers, not because three is a magic number.
+   */
+  breakpoints: ImportBreakpointPolicy;
+  aiComponents: boolean;
+  /** Build and screenshot-diff the result. Off by default — it roughly doubles the run. */
+  verify: boolean;
+  /**
+   * The average fidelity, 0..100, the clone has to reach for `verify` to report success.
+   *
+   * Only meaningful when `verify` is on. A finding rather than a failure here: the project is
+   * written and opened either way, and the assistant says the bar was missed.
+   */
+  minFidelity: number;
+  /** Empty means "whatever the assistant would use" (`preferredModel()`). */
+  model: string;
+  /** What the user wants done with the site once it is cloned. May be empty. */
+  prompt: string;
+}
+
+let _brief: ImportBrief | null = null;
+
+/**
+ * Store the brief the assistant's next turn will act on.
+ *
+ * @param {ImportBrief} brief
+ */
+export function setPendingImportBrief(brief: ImportBrief): void {
+  _brief = brief;
+}
+
+/**
+ * The brief without consuming it — what `import_site` reads to fill in a destination the model was
+ * never told and must not invent.
+ *
+ * @returns {ImportBrief | null}
+ */
+export function pendingImportBrief(): ImportBrief | null {
+  return _brief;
+}
+
+/**
+ * Forget the brief.
+ *
+ * There is deliberately no consume-on-read here, unlike `agent-seed.ts`. TWO readers need the same
+ * brief and they read at different moments: the panel, to compose the turn, and `import_site`, for
+ * the destination — which is minutes later, after the model has decided to call it. A read that
+ * cleared would leave the tool inventing a path the user never chose. The tool clears it once the
+ * import has actually run.
+ */
+export function clearPendingImportBrief(): void {
+  _brief = null;
+}
+
+// ─── The hand-off itself ────────────────────────────────────────────────────
+
+/**
+ * The assistant's side of the hand-off, registered at boot.
+ *
+ * A late-bound slot for the same reason `services/project-adoption.ts` is one: the New Project
+ * wizard must not import `panels/ai-panel.ts`. That import is not just a layering preference — the
+ * panel constructs a `DocumentAssistant` singleton at module load, so reaching for it from
+ * `new-project/` drags a live assistant into every surface that opens the wizard.
+ */
+let _handoff: ((brief: ImportBrief) => Promise<void>) | null = null;
+
+/**
+ * Register the assistant's hand-off (studio.ts boot).
+ *
+ * @param {(brief: ImportBrief) => Promise<void>} fn
+ */
+export function setImportHandoff(fn: (brief: ImportBrief) => Promise<void>): void {
+  _handoff = fn;
+}
+
+/**
+ * Start the import as an assistant turn.
+ *
+ * A no-op with nothing registered — a reduced host (a test fixture, an embedder without the
+ * assistant) would otherwise crash on a button the wizard should simply not have offered.
+ *
+ * @param {ImportBrief} brief
+ */
+export async function runImportHandoff(brief: ImportBrief): Promise<void> {
+  await _handoff?.(brief);
+}

package/src/services/jx-validate.ts

@@ -21,7 +21,7 @@ import coreDocumentSchema from "@jxsuite/schema/schema.json";
 import coreProjectSchema from "@jxsuite/schema/project-schema.json";
 
 type ValidateFn = ((doc: unknown) => boolean) & {
-  errors?: { instancePath?: string; message?: string }[] | null;
+  errors?: { instancePath?: string; message?: string; params?: Record<string, unknown> }[] | null;
 };
 
 /** Which of the two entry documents a validator covers. */
@@ -78,6 +78,16 @@ function getValidator(kind: SchemaKind): Promise<ValidateFn | null> {
   return compiling[kind];
 }
 
+/** A payload half that is usable as a JSON Schema — a non-empty, non-array object. */
+function asSchema(value: unknown): object | undefined {
+  return typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.keys(value).length > 0
+    ? (value as object)
+    : undefined;
+}
+
 /**
  * Swap in the active project's pre-bundled entry documents (the payload behind the platform's
  * `fetchProjectSchemas` member). Each half falls back to its core schema when absent, so a partial
@@ -90,16 +100,24 @@ function getValidator(kind: SchemaKind): Promise<ValidateFn | null> {
 export function applyProjectSchemas(
   schemas: { project?: unknown; document?: unknown } | null,
 ): boolean {
-  const document = (schemas?.document as object | undefined) ?? CORE.document;
-  const project = (schemas?.project as object | undefined) ?? CORE.project;
+  /*
+   * A payload half that is not a schema OBJECT falls back to core.
+   *
+   * `ajv.compile({})` succeeds and accepts everything, so a backend answering `null`, a string, or
+   * an error envelope under `document` would not fail loudly — it would install a validator that
+   * calls every document valid, and every consumer would go on trusting it.
+   */
+  const document = asSchema(schemas?.document) ?? CORE.document;
+  const project = asSchema(schemas?.project) ?? CORE.project;
+  const applied = document !== CORE.document || project !== CORE.project;
   if (document === active.document && project === active.project) {
-    return Boolean(schemas?.document || schemas?.project);
+    return applied;
   }
   active.document = document;
   active.project = project;
   compiling.document = null;
   compiling.project = null;
-  return Boolean(schemas?.document || schemas?.project);
+  return applied;
 }
 
 /** Restore the core schemas (project closed / tests). */
@@ -107,6 +125,17 @@ export function resetProjectSchemas(): void {
   applyProjectSchemas(null);
 }
 
+/**
+ * The keys ajv uses to name the property an error is ABOUT, in the order they can appear.
+ *
+ * `message` alone is not a diagnosis for any of these three. "must NOT have unevaluated properties"
+ * says a key is unrecognised without saying which key — and at the root of a `project.json` that is
+ * the difference between a fixable problem and a mystery. An imported project once produced that
+ * line three times over, naming nothing, and the only way to learn it meant `title`, `description`
+ * and `$style` was to compile the schema by hand.
+ */
+const ERROR_PROPERTY_KEYS = ["unevaluatedProperty", "additionalProperty", "missingProperty"];
+
 /**
  * Format ajv errors the way the agent loop consumes them (see ai-tools.ts
  * `translateValidationError`).
@@ -115,7 +144,11 @@ export function resetProjectSchemas(): void {
  * @returns {string[]} One formatted string per error
  */
 function formatErrors(validate: ValidateFn): string[] {
-  return (validate.errors || []).map((e) => `${e.instancePath || "(root)"}: ${e.message}`);
+  return (validate.errors || []).map((e) => {
+    const key = ERROR_PROPERTY_KEYS.find((name) => typeof e.params?.[name] === "string");
+    const property = key ? ` (${String(e.params?.[key])})` : "";
+    return `${e.instancePath || "(root)"}: ${e.message}${property}`;
+  });
 }
 
 /**
@@ -132,6 +165,25 @@ export async function validateDoc(doc: unknown): Promise<string[]> {
   return formatErrors(validate);
 }
 
+/**
+ * Validate a Jx document, distinguishing "valid" from "could not be checked".
+ *
+ * {@link validateDoc} fails OPEN — an unavailable validator answers `[]`, which is the same answer
+ * as "no errors". That is right where validation decorates an editor and wrong where it GATES a
+ * destructive step: a conversion that says "this will be a valid JSON document" on the strength of
+ * a schema it never compiled is the "never render 0" defect §9.1.1 forbids, one layer down.
+ *
+ * @param doc - Parsed document
+ * @returns The errors, `[]` when valid, or `null` when no validator could be compiled
+ */
+export async function validateDocOrNull(doc: unknown): Promise<string[] | null> {
+  const validate = await getValidator("document");
+  if (!validate) {
+    return null;
+  }
+  return validate(doc) ? [] : formatErrors(validate);
+}
+
 /**
  * Validate a `project.json` config against the active project schema. The per-project entry
  * document is what closes the composition (`unevaluatedProperties: false` over core + every enabled

package/src/services/project-adoption.ts

@@ -9,6 +9,11 @@
  * @license MIT
  */
 
+import { initProjectRepo } from "../files/files";
+import { beginBatch, endBatch, isBatching } from "../tabs/transact";
+import { workspace } from "../workspace/workspace";
+import type { Tab } from "../tabs/tab";
+
 let _adopter: ((root: string) => Promise<void>) | null = null;
 
 /** Register the project-open flow (studio.ts boot). */
@@ -29,3 +34,69 @@ export async function adoptProject(root: string): Promise<void> {
   }
   await _adopter(root);
 }
+
+/** What {@link adoptCreatedProject} observed, so a tool reports the outcome instead of the intent. */
+export interface AdoptOutcome {
+  /** The workspace is now on this root. False means the project exists but this window is not on it. */
+  adopted: boolean;
+  /** Why adoption failed, when it threw. Null when it did not (including when it silently did not). */
+  error: string | null;
+}
+
+/** The seams {@link adoptCreatedProject} runs through, so each caller keeps the one it already had. */
+export interface AdoptCreatedOptions {
+  /** The active tab, read AFTER adoption to re-anchor the agent loop's undo batch. */
+  getTab: () => Tab | null;
+  /** The project-open flow. Defaults to this module's late-bound {@link adoptProject}. */
+  adopt?: (root: string) => Promise<void>;
+  /** Version-control init. Defaults to `files/files.ts`'s `initProjectRepo`. */
+  initRepo?: (root: string) => Promise<boolean>;
+}
+
+/**
+ * Everything that must happen to a project the moment it exists: version control, then adoption.
+ *
+ * Extracted because `create_project` and `import_site` are the same act with different backends,
+ * and the wizard is a third caller of half of it. Two things it does are easy to leave out, and
+ * both were:
+ *
+ * - **Git init.** `specs/desktop.md` §4.5 is normative — _"On the create path, every source,
+ *   including Import and Agent, Studio therefore binds the backend to the new root (`activate`),
+ *   reads `gitStatus`, and runs `gitInit`."_ `initProjectRepo` had exactly two call sites, both in
+ *   the New Project modal, so a project the ASSISTANT bootstrapped was not a repository and nothing
+ *   said so. It runs first because it is what calls `platform.activate(root)`, which the open flow
+ *   below needs.
+ * - **Verifying.** `openRecentProject` swallows its failures into a status message, so a resolved
+ *   promise is not proof of adoption. The caller must be told which of the two happened.
+ *
+ * The batch dance is the third: the agent loop may hold an undo batch on the pre-adoption tab, and
+ * adoption replaces every tab in the workspace. Flush it, adopt, re-open one on whatever tab
+ * adoption left active.
+ *
+ * @param {string} root - Absolute root of the project that was just created.
+ * @param {AdoptCreatedOptions} opts
+ * @returns {Promise<AdoptOutcome>}
+ */
+export async function adoptCreatedProject(
+  root: string,
+  { getTab, adopt = adoptProject, initRepo = initProjectRepo }: AdoptCreatedOptions,
+): Promise<AdoptOutcome> {
+  // Never fails the create: a project that was written stays written (initProjectRepo notifies).
+  await initRepo(root);
+
+  const wasBatching = isBatching();
+  if (wasBatching) {
+    endBatch();
+  }
+  let adoptionError: string | null = null;
+  try {
+    await adopt(root);
+  } catch (error) {
+    adoptionError = error instanceof Error ? error.message : String(error);
+  }
+  if (wasBatching) {
+    beginBatch(getTab());
+  }
+
+  return { adopted: workspace.projectRoot === root, error: adoptionError };
+}

package/src/services/settings/definitions.ts

@@ -127,6 +127,23 @@ export const SETTINGS = {
     normalize: trimmed,
     scope: "user",
   },
+  /**
+   * Whether the Files tree draws what `.gitignore` masks.
+   *
+   * Unset — the default — HIDES them, which is the whole point: a project root holds the author's
+   * forty documents and a tool's forty thousand, and the author already said which is which. The
+   * setting exists so that answer is not a trap. `.env`, a built `dist/` an author wants to read, a
+   * generated file being debugged: each is a legitimate reason to look at an ignored file, and a
+   * sidebar that cannot show one sends the author to a different program.
+   *
+   * Roams, because "show me everything" is a way of working rather than a property of a window.
+   */
+  showIgnoredFiles: {
+    default: "",
+    key: "jx.files.showIgnored",
+    normalize: trimmed,
+    scope: "user",
+  },
   cfAccountId: {
     default: "",
     key: "jx.cf.accountId",

package/src/services/tool-executor.ts

@@ -28,9 +28,24 @@ import type { ToolRegistry } from "@jxsuite/ai/tools";
 import type { Tab } from "../tabs/tab";
 import { batchTab, beginBatch, endBatch } from "../tabs/transact";
 import { beginTurn, endTurn } from "./ai-writes";
+import { beginToolCall, beginTurnSignal, endTurnSignal } from "./ai-turn-signal";
 
 const MAX_ROUNDS = 5;
 
+/**
+ * Hard ceiling on rounds of every kind, so the loop terminates whatever the model does.
+ *
+ * {@link MAX_ROUNDS} bounds AUTONOMOUS work, and a round that ends by blocking on a person is the
+ * opposite of runaway — it cannot advance without them, which is the property the cap was ever a
+ * proxy for. So an interactive round does not spend that budget. This one is the backstop that
+ * keeps `runAgentLoop` provably terminating anyway; a human answering ten questions will have
+ * stopped it long before.
+ */
+const MAX_TOTAL_ROUNDS = 25;
+
+/** Tools that suspend the turn on a human rather than doing work. */
+const INTERACTIVE_TOOLS = new Set(["ask_user"]);
+
 interface RunAgentLoopOptions {
   chatState: ReturnType<typeof createChatState>;
   streamingClient: StreamingClient;
@@ -59,6 +74,11 @@ export async function runAgentLoop({
   const turnId = () => chatState.messages.at(-1)?.id ?? "";
   beginTurn(`turn:${chatState.messages.length}`);
 
+  /* The signal, published for the tools rather than passed to them: `ToolRegistry.execute` takes
+     none. Without it a tool that waits for a human never learns the turn was stopped, and the
+     `await` below is the whole loop. See services/ai-turn-signal.ts. */
+  beginTurnSignal(signal);
+
   // Batch all tool-call mutations into a single undo step, anchored on the tab being edited.
   if (getTab) {
     beginBatch(getTab());
@@ -83,7 +103,9 @@ export async function runAgentLoop({
   };
 
   try {
-    for (let round = 1; round <= MAX_ROUNDS; round++) {
+    /* Rounds that DID something, which is what MAX_ROUNDS bounds — see MAX_TOTAL_ROUNDS. */
+    let workRounds = 0;
+    for (let round = 1; round <= MAX_TOTAL_ROUNDS && workRounds < MAX_ROUNDS; round++) {
       const messages = chatState.toMessagesArray();
       const tools = toolRegistry.listForLLM();
 
@@ -144,8 +166,11 @@ export async function runAgentLoop({
         return;
       }
 
+      let didWork = false;
       for (const [id, call] of toolCalls) {
         let result;
+        // Published, not passed: `ToolRegistry.execute` takes the args and nothing else.
+        beginToolCall(id);
         try {
           const args = call.arguments ? (JSON.parse(call.arguments) as object) : {};
           result = await toolRegistry.execute(call.name, args);
@@ -155,6 +180,9 @@ export async function runAgentLoop({
             error: `Failed to parse arguments: ${(error as Error).message}`,
           };
         }
+        if (!INTERACTIVE_TOOLS.has(call.name)) {
+          didWork = true;
+        }
         reanchorBatch();
         if (!result.success && result.error) {
           allErrors.push(result.error);
@@ -166,7 +194,10 @@ export async function runAgentLoop({
         chatState.pushToolResultMessage(id, JSON.stringify(result));
       }
 
-      if (round < MAX_ROUNDS) {
+      if (didWork) {
+        workRounds += 1;
+      }
+      if (workRounds < MAX_ROUNDS && round < MAX_TOTAL_ROUNDS) {
         chatState.beginAssistantTurn();
       }
     }
@@ -196,6 +227,7 @@ export async function runAgentLoop({
     }
     chatState.setError(tail);
   } finally {
+    endTurnSignal();
     endBatch();
     endTurn(turnId());
   }

package/src/settings/contexts-section.ts

@@ -30,7 +30,7 @@
  * alone), parks any rejection under the control that caused it, and re-renders. §7.1's third tier:
  * a bad value belongs at its control, not in a toast that expires.
  *
- * @docs studio/projects/pages-layouts-components
+ * @docs studio/projects/settings
  */
 
 import { html, render as litRender, nothing } from "lit-html";
@@ -140,6 +140,15 @@ type ErrorTarget = string;
  */
 const errors = new WeakMap<HTMLElement, { target: ErrorTarget; message: string }>();
 
+/**
+ * Schema errors the file already had when this section last wrote to it.
+ *
+ * Reported at section level rather than under a control, because they belong to no control — and
+ * kept per container for the same reason {@link errors} is. Populated by the first write, since
+ * validating on every render would compile a schema for a section nobody is editing.
+ */
+const inheritedErrors = new WeakMap<HTMLElement, string[]>();
+
 /** Read the current failure for a container — exported for tests and for re-render helpers. */
 export function contextsError(container: HTMLElement): { target: string; message: string } | null {
   return errors.get(container) ?? null;
@@ -171,12 +180,26 @@ export function renderContextsSection(container: HTMLElement): void {
    * shape, and the disk can refuse the write. The predecessor surfaces (`Properties › Media` and
    * the CSS-variables "Enable dark scheme") did `void updateSiteConfig(...)` and dropped the
    * rejection, so a failed write read as the field snapping back for no reason.
+   *
+   * **Only the errors THIS edit introduces block it.** The candidate is the whole `project.json`,
+   * so a violation anywhere else in the file used to refuse every context edit and park the reason
+   * under whichever control had been touched — typing `1280px` into Base width reported three
+   * unevaluated-property errors about `title`, `description` and `$style`, none of which is a
+   * width. The baseline is validated first and subtracted, the same way `services/ai-tools.ts`
+   * subtracts it before blaming the model for a document it inherited. A pre-existing problem is
+   * still worth saying, so it is reported once at section level, where a whole-file problem belongs
+   * — and it is reported rather than repaired, because `project.json` is the author's file and a
+   * settings screen that silently drops keys it did not recognise is worse than one that names
+   * them.
    */
   const persistMedia = async (next: Record<string, string>, target: ErrorTarget) => {
     const candidate = { ...config, $media: next } as unknown;
     let schemaErrors: string[] = [];
+    let inherited: string[] = [];
     try {
-      schemaErrors = await validateProjectConfig(candidate);
+      inherited = await validateProjectConfig(config);
+      const found = await validateProjectConfig(candidate);
+      schemaErrors = found.filter((error) => !inherited.includes(error));
     } catch (error) {
       /* A validator that cannot compile must not block the edit — but it must not be silent
          either, so the message rides the same inline slot the schema errors would have used. */
@@ -187,6 +210,7 @@ export function renderContextsSection(container: HTMLElement): void {
       reject(target, schemaErrors.join("; "));
       return;
     }
+    inheritedErrors.set(container, inherited);
     try {
       await updateSiteConfig({ $media: next });
       errors.delete(container);
@@ -199,6 +223,24 @@ export function renderContextsSection(container: HTMLElement): void {
     renderContextsSection(container);
   };
 
+  /**
+   * What is already wrong with `project.json`, said once and not blamed on a control.
+   *
+   * It does not block anything — the edit that surfaced it went through. It is here because a file
+   * that fails its own schema will keep failing it, and until this notice existed the only place
+   * that fact appeared was as an unexplained refusal of an unrelated field.
+   */
+  const inheritedNotice = () => {
+    const inherited = inheritedErrors.get(container) ?? [];
+    return inherited.length === 0
+      ? nothing
+      : html`<p class="settings-section-notice" role="status">
+          project.json has ${inherited.length} pre-existing schema
+          ${inherited.length === 1 ? "problem" : "problems"} that this section did not cause:
+          ${inherited.join("; ")}
+        </p>`;
+  };
+
   /** The error line for one control, when that is where the current failure belongs. */
   const errorFor = (target: ErrorTarget) =>
     shown?.target === target
@@ -370,7 +412,7 @@ export function renderContextsSection(container: HTMLElement): void {
         The conditions this project's pages are rendered under. Define them once here; choose
         between them on the pane's context control while you edit.
       </p>
-      ${errorFor("section")}
+      ${errorFor("section")} ${inheritedNotice()}
 
       <div class="settings-field">
         <label class="settings-field-label">Base width</label>