@jxsuite/studio 10.4.0 → 10.5.0

package/src/panels/events-panel.ts

@@ -76,6 +76,7 @@ import {
   bindableSignalNames,
   defaultAsString,
   isInspectorSectionOpen,
+  mapListSignalsFor,
   mapSignalsFor,
   setInspectorSection,
 } from "./properties-panel";
@@ -348,6 +349,7 @@ function addField(
         (next) => spec.onChange({ $expression: next } as JsonValue),
         {
           allowEventRef: false,
+          extraRefs: spec.extraSignals,
           stateDefs: [...spec.stateDefs],
           stateEntries: null,
         },
@@ -452,7 +454,7 @@ export function projectLogicPanel(): LogicView {
     view.repeaterFields = [
       addField(fields, `prop|${key}|items`, "items", {
         caps: "repeaterItems",
-        extraSignals: null,
+        extraSignals: mapListSignalsFor(doc, selection),
         label: "Items",
         literalDefault: literalDefaultOf(node.items),
         onChange: (v?: JsonValue) =>
@@ -475,7 +477,7 @@ export function projectLogicPanel(): LogicView {
         // `SwitchDef` is a $ref and nothing else, so From data… is the only rung — a $switch is
         // Inherently dynamic, and de-escalating it would delete the key and demote the node.
         caps: "switchDiscriminant",
-        extraSignals: mapSignalsFor(selection),
+        extraSignals: mapSignalsFor(doc, selection),
         label: "Expression",
         literalDefault: literalDefaultOf(node.$switch),
         onChange: (v?: JsonValue) =>
@@ -620,6 +622,7 @@ function bindingView(
         {
           allowEventRef: true,
           emits: fn.emits ?? [],
+          extraRefs: mapSignalsFor(tab.doc.document, selection),
           /* The Inspector's copy, named by the handler it edits. It answered to
              `navigator/statements` until the docks were split, and then to a bare
              `inspector/statements` — which the binding list stamps once per structured handler, so
@@ -657,6 +660,7 @@ function bindingView(
     plan.paint = (host) =>
       mountExpressionEditor(host, expression, commitExpression, {
         allowEventRef: true,
+        extraRefs: mapSignalsFor(tab.doc.document, selection),
         onInsertDef: insertDef,
         preview,
         stateDefs: Object.keys(defs),

package/src/panels/formula-workspace.ts

@@ -59,6 +59,7 @@ import { livePreviewExpression } from "../services/live-preview";
 import { closeFunctionEditor, syncFunctionEditor } from "./editors";
 import { registerPanel } from "./panel-registry";
 import { dataTypeLabel, paintDataTree, unwrapSignal } from "./data-explorer";
+import { mapSignalsFor } from "./properties-panel";
 import { disposeDetachedDataTrees } from "../surfaces/panel-data";
 import { emptyLogicWorkspaceView, mountLogicWorkspace } from "../surfaces/logic-workspace";
 
@@ -72,6 +73,7 @@ import {
 
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { PanelBody } from "./panel-registry";
+import type { SurfaceOption } from "../ui/surface";
 import type { ExpressionPreview } from "../services/preview-eval";
 import type { FormulaEditDef, FunctionEditDef } from "../types";
 import type { Tab } from "../tabs/tab";
@@ -314,6 +316,8 @@ interface Resolved {
   stateEntries: Record<string, JxStateDefinition>;
   preview: ExpressionPreview | null;
   allowEventRef: boolean;
+  /** The repeater item's fields, for an event handler inside a template. */
+  extraRefs: SurfaceOption[] | null;
   /** Chip key → node path, so a chip click needs no path parsing (a `switch` case may hold "/"). */
   chipPaths: Map<string, NodePath>;
   /** Rail entry name → the value its tree draws. */
@@ -475,6 +479,10 @@ export function workspaceView(): LogicWorkspaceView {
     allowEventRef: editing.type === "event",
     chipPaths,
     editing,
+    extraRefs:
+      editing.type === "event" && editing.path
+        ? mapSignalsFor(tab.doc.document, editing.path)
+        : null,
     preview,
     root,
     scopeValues: rail.values,
@@ -528,6 +536,7 @@ function paintEditor(): void {
   mountExpressionEditor(host, held.selected, writeSelected, {
     allowEventRef: held.allowEventRef,
     depth: 1,
+    extraRefs: held.extraRefs,
     onInsertDef: insertDef,
     path: held.selectedPath,
     preview: held.preview,

package/src/panels/properties-panel.ts

@@ -41,7 +41,7 @@
  * @docs studio/design/properties
  */
 
-import { getNodeAtPath } from "../store";
+import { getNodeAtPath, projectState } from "../store";
 import { effect, effectScope, reactive } from "../reactivity";
 import {
   displayTagName,
@@ -50,6 +50,7 @@ import {
   isRef,
   isString,
   isTagExpression,
+  isTemplateString,
 } from "@jxsuite/schema/guards";
 import type { JsonValue } from "../types";
 import {
@@ -114,6 +115,13 @@ import type { LinkKind } from "../utils/link-target";
 import { clickAnythingTo, openPageAction, staleSelectionMessage } from "./empty-state";
 import { mountMediaPicker, unmountMediaPicker } from "../ui/media-picker";
 import { colorTokens, resolvedColor } from "../ui/color-selector";
+import {
+  childrenTemplate,
+  fieldOfChildrenTemplate,
+  mapRefLabel,
+  repeaterItemFields,
+} from "../editor/repeater-scope";
+import type { RepeaterField } from "../editor/repeater-scope";
 import { mountExpressionEditor } from "../ui/expression-editor";
 import type { ExpressionEditorOpts } from "../ui/expression-editor";
 import {
@@ -182,20 +190,45 @@ function nodeAtPath(doc: JxMutableNode, path: JxPath): JxMutableNode | undefined
 // ─── The binding vocabulary, shared with the Logic tab ───────────────────────
 
 /**
- * The two extra signals a position inside a repeater template can bind to, or `null` outside one.
+ * The extra signals a position inside a repeater template can bind to, or `null` outside one: the
+ * item, every field of the item the document and project declare, and its index.
  *
  * A "map" segment addresses a repeater template (`[…, "children", i, "map", …]`, or the legacy `[…,
  * "children", "map", …]`), so anything at or below it is inside one.
  *
  * Exported because Content and Logic both offer them and there is one right answer: a `$switch`
- * inside a `$map` can read `$map/item`, and so can the `alt` attribute two nodes below it.
+ * inside a `$map` can read `$map/item/data/title`, and so can the `alt` attribute two nodes below
+ * it. `$map/item` stays first, because a fresh binding lands on the first signal offered.
+ *
+ * `withNodes` adds the fields holding child nodes, for the one position that can draw them.
+ */
+export function mapSignalsFor(
+  doc: JxMutableNode,
+  path: JxPath,
+  options: { withNodes?: boolean } = {},
+): SurfaceOption[] | null {
+  if (!path.includes("map")) {
+    return null;
+  }
+  const fields = repeaterItemFields(doc, path, projectState?.projectConfig, options);
+  return [
+    { label: "item", value: "$map/item" },
+    ...fields.map((field) => ({ label: field.token, value: field.pointer })),
+    { label: "index", value: "$map/index" },
+  ];
+}
+
+/**
+ * What a repeater's own Items can read from the repeater around it: the lists on the outer item.
+ * Only those, because an Items position takes a list, and the index or a text field would render
+ * nothing.
  */
-export function mapSignalsFor(path: JxPath): SurfaceOption[] | null {
-  return path.includes("map")
-    ? [
-        { label: "$map/item", value: "$map/item" },
-        { label: "$map/index", value: "$map/index" },
-      ]
+export function mapListSignalsFor(doc: JxMutableNode, path: JxPath): SurfaceOption[] | null {
+  const lists = repeaterItemFields(doc, path, projectState?.projectConfig).filter(
+    (field) => field.isArray,
+  );
+  return lists.length > 0
+    ? lists.map((field) => ({ label: field.token, value: field.pointer }))
     : null;
 }
 
@@ -228,7 +261,7 @@ export function defaultAsString(def: JxStateDefinition | undefined) {
 function bindingDonor(value: JxDocumentValue | undefined): string {
   if (isRef(value)) {
     const ref = value.$ref;
-    return ref.startsWith("#/state/") ? ref.slice(8) : ref || "nothing yet";
+    return ref.startsWith("#/state/") ? ref.slice(8) : mapRefLabel(ref) || ref || "nothing yet";
   }
   return isString(value) ? "a template" : "a formula";
 }
@@ -1098,6 +1131,7 @@ function applyLadder(row: ContentRowView, plan: RowPlan, opts: LadderOpts): void
     plan.draft = undefined;
     const editorOpts: ExpressionEditorOpts = {
       allowEventRef: false,
+      extraRefs: opts.extraSignals,
       preview: null,
       stateDefs: opts.stateDefs,
       stateEntries: null,
@@ -1230,7 +1264,7 @@ function sectionsFor(node: JxMutableNode, path: JxPath): ContentSectionView[] {
   const tagName = displayTagName(node.tagName) || "div";
   const isCustomInstance = displayTagName(node.tagName).includes("-");
   const attrs = node.attributes || {};
-  const mapSignals = mapSignalsFor(path);
+  const mapSignals = mapSignalsFor(doc, path);
   const bindableSignals = bindableSignalNames(doc);
 
   // ── Which attributes this tag has, by section ──
@@ -1276,7 +1310,7 @@ function sectionsFor(node: JxMutableNode, path: JxPath): ContentSectionView[] {
   const sections: ContentSectionView[] = [
     sectionView("__element", "Element", isInspectorSectionOpen("__element", false), [], 0),
   ];
-  sections[0]!.rows = elementRows(node, path, tagName, mapSignals, bindableSignals);
+  sections[0]!.rows = elementRows(node, path, tagName, bindableSignals);
 
   if (isCustomInstance) {
     const definitionOfThis = isComponentDefinitionOpen(node);
@@ -1366,11 +1400,90 @@ function draftKey(path: JxPath, name: string): string {
   return `prop:${path.join("/")}:${name}`;
 }
 
+/**
+ * What a write to the content row leaves in `children`: the template to hold, or `null` for none.
+ *
+ * `$children` is a list of nodes, so it cannot be held in `textContent`, which would draw it as
+ * `[object Object]`. Picking it, or typing a template that reads it, moves the binding to the
+ * computed-children form the compiler already expands (spec.md §8.4). A template the row already
+ * held there that names no such field (`${state.entry.$children}`) stays there as it is edited.
+ */
+function computedChildrenFrom(
+  value: JsonValue | undefined,
+  nodeFields: readonly RepeaterField[],
+  keepsTemplate: boolean,
+): string | null {
+  if (isRef(value)) {
+    const field = nodeFields.find((f) => f.pointer === value.$ref);
+    return field ? childrenTemplate(field) : null;
+  }
+  if (!isTemplateString(value)) {
+    return null;
+  }
+  return keepsTemplate || fieldOfChildrenTemplate(value, nodeFields) ? value : null;
+}
+
+/**
+ * The Text Content row, which is also where an element's child nodes are bound.
+ *
+ * One row for two properties, because they are one question: what fills this element. A node with
+ * computed children has no text to show, and it used to draw this row empty and on Fixed value, so
+ * the binding could not be seen and typing here wrote text the compiled page never drew.
+ */
+function contentRow(
+  node: JxMutableNode,
+  path: JxPath,
+  bindableSignals: string[],
+  propertyChip: (name: string, human: string) => FieldProvenance,
+): ContentRowView {
+  const doc = activeTab.value!.doc.document;
+  const nodeFields = repeaterItemFields(doc, path, projectState?.projectConfig, {
+    withNodes: true,
+  }).filter((field) => field.holdsNodes);
+  const computed = isTemplateString(node.children) ? node.children : null;
+  const bound = computed === null ? undefined : fieldOfChildrenTemplate(computed, nodeFields);
+  const value = bound ? { $ref: bound.pointer } : (computed ?? node.textContent);
+  const write = (next?: JsonValue): void => {
+    const template = computedChildrenFrom(next, nodeFields, computed !== null && !bound);
+    transactDoc(activeTab.value, (t) => {
+      if (template === null || node.textContent !== undefined) {
+        mutateUpdateProperty(t, path, "textContent", template === null ? next : undefined);
+      }
+      if (template !== computed) {
+        mutateUpdateProperty(t, path, "children", template ?? undefined);
+      }
+    });
+  };
+
+  const textDraft = draft(draftKey(path, "textContent"));
+  const text = blankRow(
+    "prop|textContent",
+    "textContent",
+    computed === null ? "Text Content" : "Content",
+  );
+  text.kind = "textarea";
+  text.value = getFieldValue(textDraft, isString(value) ? value : "");
+  const plan: RowPlan = { commit: write, debounceMs: LIVE_PREVIEW, draft: textDraft };
+  applyLadder(text, plan, {
+    caps: "textProperty",
+    extraSignals: mapSignalsFor(doc, path, { withNodes: true }),
+    fieldKey: `prop|${path.join("/")}|textContent`,
+    onChange: write,
+    stateDefs: bindableSignals,
+    value,
+  });
+  if (computed !== null) {
+    applyChip(text, plan, "textContent", propertyChip("children", "content"));
+  } else if (node.textContent !== undefined) {
+    applyChip(text, plan, "textContent", propertyChip("textContent", "text"));
+  }
+  return withPlan(text, plan);
+}
+
 function elementRows(
   node: JxMutableNode,
   path: JxPath,
   tagName: string,
-  mapSignals: SurfaceOption[] | null,
   bindableSignals: string[],
 ): ContentRowView[] {
   const chosenTag = isTagExpression(node.tagName) ? node.tagName.$expression : null;
@@ -1459,28 +1572,7 @@ function elementRows(
   rows.push(withPlan(cls.row, cls.plan));
 
   if (!Array.isArray(node.children) || node.children.length === 0) {
-    const textDraft = draft(draftKey(path, "textContent"));
-    const text = blankRow("prop|textContent", "textContent", "Text Content");
-    text.kind = "textarea";
-    text.value = getFieldValue(textDraft, isString(node.textContent) ? node.textContent : "");
-    const plan: RowPlan = {
-      commit: writeProperty("textContent"),
-      debounceMs: LIVE_PREVIEW,
-      draft: textDraft,
-    };
-    applyLadder(text, plan, {
-      caps: "textProperty",
-      extraSignals: mapSignals,
-      fieldKey: `prop|${path.join("/")}|textContent`,
-      onChange: (v) =>
-        transactDoc(activeTab.value, (t) => mutateUpdateProperty(t, path, "textContent", v)),
-      stateDefs: bindableSignals,
-      value: node.textContent,
-    });
-    if (node.textContent !== undefined) {
-      applyChip(text, plan, "textContent", propertyChip("textContent", "text"));
-    }
-    rows.push(withPlan(text, plan));
+    rows.push(contentRow(node, path, bindableSignals, propertyChip));
   }
 
   const hidden = blankRow("prop|hidden", "hidden", "Hidden");

package/src/panels/statement-editor.ts

@@ -62,6 +62,8 @@ export interface StatementEditorOpts {
   stateDefs: string[];
   stateEntries?: Record<string, JxStateDefinition> | null;
   allowEventRef: boolean;
+  /** Pointers beyond the document's own signals: inside a repeater, its item and that item's fields. */
+  extraRefs?: readonly SurfaceOption[] | null | undefined;
   /** The entry's declared CEM events — offered as dispatchEvent name completions. */
   emits?: CemEvent[];
   /**
@@ -342,6 +344,7 @@ function operandOpts(opts: StatementEditorOpts) {
   return {
     allowEventRef: opts.allowEventRef,
     depth: 0,
+    extraRefs: opts.extraRefs,
     stateDefs: opts.stateDefs,
     stateEntries: opts.stateEntries ?? null,
   };
@@ -578,6 +581,7 @@ export function flattenStatements(
           (n) => commit(n as JxStatement),
           {
             allowEventRef: opts.allowEventRef,
+            extraRefs: opts.extraRefs,
             stateDefs: opts.stateDefs,
             stateEntries: opts.stateEntries ?? null,
           },

package/src/panels/tab-strip.ts

@@ -16,7 +16,7 @@
  * **The chip is a `jx-tab` now, and three of the things it used to draw by hand are the kit's**:
  * the selected state (`aria-selected` on a real `tab` inside a real `tablist`, where an `.active`
  * class used to be), the close button, and the dirty dot. The three that are Studio's own live in
- * `jx-tab`'s slots — the drill-in marker in `icon`, the draft pill in `status`, the pin toggle in
+ * `jx-tab`'s slots — the drill-in marker in `icon`, the hold pill in `status`, the pin toggle in
  * `actions` — which is the gap that kept this strip out of the tab pattern (`ui.md` §5.4). With it
  * closed the strip is one stop in the tab order, the arrows walk it, Home and End reach its ends,
  * and Delete closes a tab: a keyboard contract the × has never had.
@@ -57,8 +57,8 @@ import { gridTabLabel } from "../grid/grid-source";
 import { workspaceTabOrder } from "../workspace/tab-workspace";
 import { workspaceHomeLabel } from "../workspace/workspace-ids";
 import { shell, workspaceDrawsTabStrip } from "../shell";
-import { entryDraftPill } from "../content/entry-editor";
-import { DRAFT_FIELD, isDraftEntry } from "../content/draft-state";
+import { entryHoldPill } from "../content/entry-editor";
+import { holdFields, holdSwitch } from "../content/hold-state";
 import { entryFields } from "../content/entry-fields";
 import { collectionOfPath } from "../content/entry-model";
 import { activeRegistry } from "../commands/active-registry";
@@ -262,9 +262,11 @@ export function mount(host: HTMLElement) {
         void tab.pinned;
         void tab.preview;
         void tab.session.openedFrom;
-        // The draft pill is on the chip, so the chip has to repaint when the flag changes — reading
-        // The absent key tracks its ADDITION too, which is the transition that matters most.
-        void tab.doc.content.frontmatter[DRAFT_FIELD];
+        // The hold pill is on the chip, so the chip has to repaint when a field its rules read
+        // Changes. Reading an absent key tracks its ADDITION too, which matters most.
+        for (const field of holdFields(collectionOfPath(tab.documentPath)?.def)) {
+          void tab.doc.content.frontmatter[field];
+        }
       }
       // An edit is a commitment: a preview tab with unsaved changes is no longer disposable, and
       // The dirty flags this effect already tracks are exactly the signal.
@@ -685,15 +687,15 @@ function chipView(
   if (!tab) {
     return [];
   }
-  /* The draft pill (`site-architecture.md` §7.6). On the CHIP, not only inside the entry editor:
+  /* The hold pill (`site-architecture.md` §7.6). On the CHIP, not only inside the entry editor:
      the mistake this prevents — publishing something you believed was private — is made while
      glancing at a row of tabs, and it is made about a document that may not even be the active
      one. */
-  const pill = entryDraftPill(tab);
+  const pill = entryHoldPill(tab);
   return [
     {
       dirty: tab.doc.dirty || imageEditorDirty(tab),
-      draft: pill?.draft ?? false,
+      held: pill?.held ?? false,
       index,
       key: id,
       label: labels.get(id) ?? "Untitled",
@@ -1011,24 +1013,25 @@ export function dismissTabContextMenu() {
  * A tab addresses ONE document, and this is everything the chip can say about it — keyed by the
  * ARGUMENT NAME that asks for it.
  *
- * The whole `context/tab` placement asks for exactly one argument today: `content.setDraft
- * {draft}`. The other five records take none, because they read the ACTIVE document — which is why
+ * The whole `context/tab` placement asks for exactly one argument today: `content.setHold {hold}`.
+ * The other five records take none, because they read the ACTIVE document — which is why
  * {@link openTabContextMenu} activates the chip before it builds a single row.
  *
  * A fact is stated ONLY when it is true of this tab, and that is what decides whether a command
- * appears at all: `styles/main.css` is an entry of no collection, so it states no `draft`, so "Set
- * Draft" is not offered on it. The condition is `collectionOfPath` — the same question
- * `content.setDraft`'s own `enablement` asks — so the menu never invents a rule the command does
- * not have, and never renders a row into a refusal.
+ * appears at all: `styles/main.css` is an entry of no collection, so it has no hold rules, so "Set
+ * Hold" is not offered on it. The condition is `collectionOfPath` — the same question
+ * `content.setHold`'s own `enablement` asks — so the menu never invents a rule the command does not
+ * have, and never renders a row into a refusal.
  *
  * The VALUE is the state the row would reach, not the state the tab is in: a setter is named for
- * where it lands (`content/draft-state.ts` says why), so the row offers the flip of what is true
- * now and {@link statedChecked} reads the current state back out of it for the checkmark.
+ * where it lands (`content/hold-state.ts` says why), so the row offers the flip of what is true now
+ * and {@link statedChecked} reads the current state back out of it for the checkmark.
  */
 function tabRowFacts(tab: Tab): CommandArgValues {
   const facts: CommandArgValues = {};
-  if (collectionOfPath(tab.documentPath)) {
-    facts.draft = !isDraftEntry(entryFields(tab));
+  const toggle = holdSwitch(collectionOfPath(tab.documentPath)?.def);
+  if (toggle) {
+    facts.hold = entryFields(tab)[toggle.field] !== true;
   }
   return facts;
 }
@@ -1040,16 +1043,16 @@ function tabRowFacts(tab: Tab): CommandArgValues {
  * A menu is the one surface that is READ before it is used, so it is the one surface that can show
  * a boolean instead of asking the author to remember it. That is an argument for the SETTER over
  * the toggle, and it is why this is derived from the args rather than from a list of command ids:
- * `content.setDraft {draft}` names the state it reaches, so the row can say which state the tab is
- * in now and still land somewhere definite when clicked. `document.togglePinned` names no state —
- * "Pin / Unpin Document" is a title that admits it does not know which it will do — so it renders
- * as a plain row here. Its idempotent sibling `document.setPinned {pinned}` would state its own
- * value, with no edit to this file, on the day its record declares `context/tab`; that declaration
- * lives in `workspace/workspace.ts`, which is the only place it can be made.
+ * `content.setHold {hold}` names the state it reaches, so the row can say which state the tab is in
+ * now and still land somewhere definite when clicked. `document.togglePinned` names no state — "Pin
+ * / Unpin Document" is a title that admits it does not know which it will do — so it renders as a
+ * plain row here. Its idempotent sibling `document.setPinned {pinned}` would state its own value,
+ * with no edit to this file, on the day its record declares `context/tab`; that declaration lives
+ * in `workspace/workspace.ts`, which is the only place it can be made.
  *
  * **It is a real checkbox row now, which it could not be under Spectrum.** `sp-menu` reassigned
  * every item's role one frame after connect whenever the menu declared no `selects`, so
- * `role="menuitemcheckbox"` did not survive and the state had to be printed as a sentence ("Draft:
+ * `role="menuitemcheckbox"` did not survive and the state had to be printed as a sentence ("Held:
  * no") in the description line instead. `jx-menu-item` derives `role` and `aria-checked` from
  * `checked` and nothing rewrites them, so the row states the boolean the way a screen reader
  * already knows how to announce — and the five rows that carry no state stay plain `menuitem`s,

package/src/services/ai-project-tools.ts

@@ -28,7 +28,7 @@ import { adoptCreatedProject } from "./project-adoption";
 import { translateValidationError } from "./ai-tools";
 import { validateDoc, validateProjectConfig } from "./jx-validate";
 import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
-import type { CandidateDocument } from "./ai-write-report";
+import type { CandidateDocument, RenderProbe } from "./ai-write-report";
 import { invalidPathResult, normalizeRelPath } from "./project-path";
 
 /** Directories the file tools never descend into or report. */
@@ -71,7 +71,7 @@ export interface ProjectToolsCtx {
    * judges the live configuration and a candidate parsed from the model's text alike.
    */
   validateProject?: (config: ProjectConfig | JsonValue) => Promise<string[]>;
-  renderCheck?: (doc: CandidateDocument) => Promise<{ ok: true } | { ok: false; error: string }>;
+  renderCheck?: RenderProbe;
   /** Live getter — the project style appears only after a project is open/bootstrapped. */
   getProjectStyle?: () => Record<string, string> | undefined;
   /** The open tab whose `documentPath` equals the given project-relative path, if any. */
@@ -323,7 +323,7 @@ export function registerProjectTools(
             };
           }
           if (renderCheck) {
-            const renderResult = await renderCheck(parsed);
+            const renderResult = await renderCheck(parsed, { documentPath: relPath });
             if (!renderResult.ok) {
               return {
                 success: false,

package/src/services/ai-tools.ts

@@ -18,7 +18,7 @@ import { validateDoc } from "./jx-validate";
 import { invalidPathResult, normalizeRelPath } from "./project-path";
 import { serializeJson } from "@jxsuite/schema/json-layout";
 import { translateValidationError } from "./ai-write-report";
-import type { CandidateDocument } from "./ai-write-report";
+import type { CandidateDocument, RenderProbe } from "./ai-write-report";
 import { studioDocumentHost, studioWriteReporter } from "./harness/studio-documents";
 
 /* Re-exported from its new home so `ai-project-tools.ts` and the tests keep their import: the
@@ -34,7 +34,7 @@ export { translateValidationError } from "./ai-write-report";
  *   getTab: () => import("../tabs/tab").Tab | null;
  *   validate?: (doc: CandidateDocument) => Promise<string[]>;
  *   saveFile?: (relPath: string, content: string) => Promise<void>;
- *   renderCheck?: (doc: CandidateDocument) => Promise<{ ok: true } | { ok: false; error: string }>;
+ *   renderCheck?: RenderProbe;
  *   projectStyle?: Record<string, string>;
  *   getProjectStyle?: () => Record<string, string> | undefined;
  *   findOpenTab?: (path: string) => import("../tabs/tab").Tab | null;
@@ -56,7 +56,7 @@ export function registerAiTools(
     getTab: () => Tab | null;
     validate?: (doc: CandidateDocument) => Promise<string[]>;
     saveFile?: (relPath: string, content: string) => Promise<void>;
-    renderCheck?: (doc: CandidateDocument) => Promise<{ ok: true } | { ok: false; error: string }>;
+    renderCheck?: RenderProbe;
     projectStyle?: Record<string, string> | undefined;
     /**
      * Live variant of `projectStyle` — takes precedence; re-read per tool call so a project
@@ -164,7 +164,7 @@ export function registerAiTools(
           };
         }
         if (renderCheck) {
-          const renderResult = await renderCheck(content);
+          const renderResult = await renderCheck(content, { documentPath: relPath });
           if (!renderResult.ok) {
             return {
               success: false,
@@ -252,7 +252,7 @@ export function registerAiTools(
           };
         }
         if (renderCheck) {
-          const renderResult = await renderCheck(content);
+          const renderResult = await renderCheck(content, { documentPath: relPath });
           if (!renderResult.ok) {
             return {
               success: false,

package/src/services/ai-write-report.ts

@@ -22,7 +22,7 @@
  */
 
 import type { ToolResult } from "@jxsuite/ai/tools";
-import type { JsonValue, JxMutableNode } from "@jxsuite/schema/types";
+import type { JsonValue, JxDocumentValue, JxMutableNode } from "@jxsuite/schema/types";
 import { toRaw } from "../reactivity";
 import type { Tab } from "../tabs/tab";
 import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
@@ -37,12 +37,28 @@ export type RenderVerdict = { ok: true } | { ok: false; error: string };
  */
 export type CandidateDocument = JxMutableNode | JsonValue;
 
+/** Where a document under a render check lives: what its route and relative references resolve from. */
+export interface RenderSource {
+  /** Its project-relative path, once it has one. */
+  documentPath?: string | null | undefined;
+  /** A format-class page's frontmatter, which is where its `$paths` is. */
+  frontmatter?: Record<string, JxDocumentValue | undefined> | null | undefined;
+}
+
+/** A detached-DOM render probe. */
+export type RenderProbe = (doc: CandidateDocument, source?: RenderSource) => Promise<RenderVerdict>;
+
+/** Where an open tab's document lives, as a render check reads it. */
+function renderSourceOf(tab: Tab): RenderSource {
+  return { documentPath: tab.documentPath, frontmatter: tab.doc.content.frontmatter };
+}
+
 /** What a write reporter needs. Every member is what `registerAiTools` already takes by injection. */
 export interface WriteReportDeps {
   /** Schema errors for a document, as raw ajv sentences. */
   validate: (doc: CandidateDocument) => Promise<string[]>;
   /** The detached-DOM render probe, when the host has one. */
-  renderCheck?: ((doc: CandidateDocument) => Promise<RenderVerdict>) | undefined;
+  renderCheck?: RenderProbe | undefined;
   /** The project's design tokens, read per call so a project opened mid-session contributes. */
   getProjectStyle?: (() => Record<string, string> | undefined) | undefined;
 }
@@ -122,7 +138,9 @@ export function translateValidationError(rawError: string): string {
 export async function snapshotBeforeWrite(tab: Tab, deps: WriteReportDeps): Promise<WriteSnapshot> {
   const rawBefore = toRaw(tab.doc.document);
   const errors = new Set(await deps.validate(rawBefore));
-  const rendered = deps.renderCheck ? await deps.renderCheck(rawBefore) : { ok: true };
+  const rendered = deps.renderCheck
+    ? await deps.renderCheck(rawBefore, renderSourceOf(tab))
+    : { ok: true };
   return { errors, renderOk: rendered.ok };
 }
 
@@ -159,7 +177,7 @@ export async function reportDocumentWrite(
   }
 
   if (deps.renderCheck && before.renderOk) {
-    const renderResult = await deps.renderCheck(rawAfter);
+    const renderResult = await deps.renderCheck(rawAfter, renderSourceOf(tab));
     if (!renderResult.ok) {
       return {
         success: false,