@jxsuite/studio 0.37.1 → 1.1.0

package/src/services/ai-system-prompt.ts

@@ -22,6 +22,149 @@ interface BuildSystemPromptOptions {
   components?: ComponentEntry[] | undefined;
   /** Project root path. */
   projectRoot?: string | undefined;
+  /** Whether a project is open. Defaults to `!!projectRoot` (kept explicit for tests). */
+  hasProject?: boolean | undefined;
+  /** Project-relative file paths for the inventory section (project modes; capped). */
+  fileInventory?: string[] | undefined;
+}
+
+/** Max file paths embedded in the prompt's inventory section. */
+const FILE_INVENTORY_CAP = 100;
+
+// ─── Tool tiers (single source of truth for prompt AND gating) ──────────────
+
+/** Studio state a tool tier requires. Used by the gating registry AND the prompt tool list. */
+export type AiToolTier = "no-project" | "project" | "document";
+
+export interface AiToolInfo {
+  name: string;
+  tier: AiToolTier;
+  /** One-line signature + purpose shown in the system prompt's tool list. */
+  blurb: string;
+}
+
+/**
+ * Every assistant tool with its availability tier and prompt blurb. document-assistant.ts derives
+ * the gating predicates from the same rows, so the advertised tool list and the executable tool
+ * list cannot drift (a test asserts the names match the registered tools).
+ */
+export const AI_TOOL_TIERS: AiToolInfo[] = [
+  // Bootstrap (no project open)
+  {
+    name: "create_project",
+    tier: "no-project",
+    blurb:
+      "create_project(name, description?, template?, directory?, design?) — scaffold a new Jx project (project.json, conventional directories, starter pages) and open it in the studio.",
+  },
+  {
+    name: "list_starters",
+    tier: "no-project",
+    blurb: "list_starters() — list the starter templates available for new projects.",
+  },
+  // Cross-file (project open, document optional)
+  {
+    name: "list_files",
+    tier: "project",
+    blurb: "list_files(dir?) — list the project's files recursively (build folders excluded).",
+  },
+  {
+    name: "read_file",
+    tier: "project",
+    blurb: "read_file(path) — read any project file (Jx documents, markdown, CSS, data).",
+  },
+  {
+    name: "write_file",
+    tier: "project",
+    blurb:
+      "write_file(path, content) — create or overwrite a project file. Jx documents are schema-validated and render-checked BEFORE writing; refused while the file is open with unsaved changes. Not undoable.",
+  },
+  {
+    name: "search_files",
+    tier: "project",
+    blurb: "search_files(query, extensions?) — find files by file NAME (not content).",
+  },
+  {
+    name: "create_component",
+    tier: "project",
+    blurb: "create_component(path, content) — create a new .json component file on disk.",
+  },
+  {
+    name: "create_page",
+    tier: "project",
+    blurb: "create_page(path, content) — create a new .json page file on disk.",
+  },
+  {
+    name: "open_document",
+    tier: "project",
+    blurb:
+      "open_document(path) — open a file on the canvas as the active document; the document tools then operate on it. Use when the user should SEE the page, or for iterative visual refinement.",
+  },
+  // Document (an active document on the canvas)
+  {
+    name: "read_document",
+    tier: "document",
+    blurb:
+      'read_document(path?) — inspect the whole document or the subtree at a path. Paths are JSON arrays of keys/indices from the root, e.g. ["children", 0, "children", 1].',
+  },
+  {
+    name: "set_property",
+    tier: "document",
+    blurb:
+      "set_property(path, key, value) — set or remove a property on the node at path (tagName, textContent, className, style, attributes, $props…). Pass value: null to remove.",
+  },
+  {
+    name: "set_style",
+    tier: "document",
+    blurb:
+      'set_style(path, property, value) — set or remove a CSS style property (camelCase) on a node. Values as strings: "10px", "var(--color-accent)". Pass value: null to remove.',
+  },
+  {
+    name: "set_text",
+    tier: "document",
+    blurb: 'set_text(path, value) — convenient alias for set_property with key: "textContent".',
+  },
+  {
+    name: "add_child",
+    tier: "document",
+    blurb:
+      "add_child(parentPath, index, node) — insert a new node into the children of parentPath at index.",
+  },
+  {
+    name: "remove_node",
+    tier: "document",
+    blurb: "remove_node(path) — remove the node at path.",
+  },
+  {
+    name: "move_node",
+    tier: "document",
+    blurb: "move_node(fromPath, toParentPath, toIndex) — move a node from one location to another.",
+  },
+  {
+    name: "add_state",
+    tier: "document",
+    blurb:
+      "add_state(key, value) — add a reactive state variable under the document's 'state' object. Value can be scalar, typed, computed, function, or data source.",
+  },
+  {
+    name: "update_state",
+    tier: "document",
+    blurb: "update_state(key, value) — update or remove (value: null) an existing state variable.",
+  },
+];
+
+/**
+ * Whether a tier's tools are active for the given studio state. Shared semantics with the gating
+ * registry: bootstrap tools vanish once a project opens; project tools need a project; document
+ * tools need an active document (even in single-file mode without a project).
+ */
+export function tierActive(tier: AiToolTier, hasProject: boolean, hasDocument: boolean): boolean {
+  if (tier === "no-project") {
+    return !hasProject;
+  }
+  if (tier === "project") {
+    return hasProject;
+  }
+  return hasDocument;
 }
 
 // ─── Jx Schema Reference (condensed) ────────────────────────────────────────
@@ -381,41 +524,58 @@ export function buildSystemPrompt({
   projectConfig,
   components,
   projectRoot,
+  hasProject = Boolean(projectRoot),
+  fileInventory,
 }: BuildSystemPromptOptions = {}) {
-  // 1. Role & capabilities
-  const sections = [
-    `You are an expert Jx builder assistant embedded in Jx Studio. You help users build websites, components, pages, and layouts using the Jx JSON schema. The live jxsuite.com marketing site is built entirely with Jx — you can produce production-quality Jx code.
-
-You have access to these tools that read and modify the live Jx document directly. Always prefer tool calls over describing changes in text:
-- read_document(path?) — inspect the whole document or the subtree at a path. Paths are JSON arrays of keys/indices from the root, e.g. ["children", 0, "children", 1].
-- set_property(path, key, value) — set or remove a property on the node at path (tagName, textContent, className, style, attributes, $props…). Pass value: null to remove.
-- set_style(path, property, value) — set or remove a CSS style property (camelCase) on a node. Values as strings: "10px", "var(--color-accent)". Pass value: null to remove.
-- set_text(path, value) — convenient alias for set_property with key: "textContent".
-- add_child(parentPath, index, node) — insert a new node into the children of parentPath at index.
-- remove_node(path) — remove the node at path.
-- move_node(fromPath, toParentPath, toIndex) — move a node from one location to another.
-- add_state(key, value) — add a reactive state variable under the document's 'state' object. Value can be scalar, typed, computed, function, or data source.
-- update_state(key, value) — update or remove (value: null) an existing state variable.
-- create_component(path, content) — create a new .json component file on disk.
-- create_page(path, content) — create a new .json page file on disk.
-- open_document(path) — switch the active document to another file. After opening, all tools operate on the new document. Use this after create_page/create_component to iteratively refine the new file.
+  const hasDocument = Boolean(document);
+
+  // 1. Role, state-appropriate workflow, and the tool list for the current state.
+  const toolList = AI_TOOL_TIERS.filter((t) => tierActive(t.tier, hasProject, hasDocument))
+    .map((t) => `- ${t.blurb}`)
+    .join("\n");
+
+  const role = `You are an expert Jx builder assistant embedded in Jx Studio. You help users build websites, components, pages, and layouts using the Jx JSON schema. The live jxsuite.com marketing site is built entirely with Jx — you can produce production-quality Jx code.`;
+
+  let workflow: string;
+  if (!hasProject && !hasDocument) {
+    workflow = `No project is open yet. Your first job is to bootstrap one:
+1. Gather what the user wants (site type, name, look) — ask briefly only if essential details are missing.
+2. Call create_project with a fitting name, template, and design quickstart (colors/fonts) derived from the request.
+3. After it succeeds the studio opens the project, and the file and document tools become available in the next round — continue building pages, components, and layouts with them without waiting to be asked.
+
+Tools available right now:
+${toolList}`;
+  } else if (!hasDocument) {
+    workflow = `A project is open, but no document is on the canvas. Work across the project's files directly — you do not need to open documents to develop:
+1. Discover with list_files / search_files, inspect with read_file.
+2. Create or modify files with write_file / create_page / create_component. Jx documents are validated before writing; fix reported errors and retry.
+3. Use open_document only when the user should see a page on the canvas, or when you want the finer-grained document tools for iterative edits.
+
+Tools available right now:
+${toolList}`;
+  } else {
+    workflow = `You have tools that read and modify the live Jx document directly, plus project-wide file tools. Always prefer tool calls over describing changes in text:
+${toolList}
 
 When the user asks you to build or modify something:
 1. Call read_document first if needed to discover the current structure and valid paths.
 2. Plan your changes — think about which tools you'll need.
 3. Execute the tools in the right order (e.g., add_child before set_property on the new node).
-4. Summarize what you changed clearly.
+4. For changes spanning OTHER files, use read_file/write_file directly instead of opening each one.
+5. Summarize what you changed clearly.
 
-Your edits apply to the live canvas immediately and are individually undoable. After each edit the document is schema-validated: if a tool returns { success: false } reporting schema errors, your change introduced them — issue a follow-up edit to fix them.
+Your document edits apply to the live canvas immediately and are individually undoable (file writes are not). After each edit the document is schema-validated: if a tool returns { success: false } reporting schema errors, your change introduced them — issue a follow-up edit to fix them.`;
+  }
+
+  const closing = `You have a limited number of tool-call rounds per message. On vague or open-ended prompts ("make it look better", "improve this"), prefer a small number of targeted, high-impact changes over attempting to rebuild the entire page. Explain what you changed and offer to do more.
 
-You have a limited number of tool-call rounds per message. On vague or open-ended prompts ("make it look better", "improve this"), prefer a small number of targeted, high-impact changes over attempting to rebuild the entire page. Explain what you changed and offer to do more.
+Be concise. Don't explain what Jx is unless asked. Just build.`;
 
-Be concise. Don't explain what Jx is unless asked. Just build.`,
-  ];
+  const sections = [`${role}\n\n${workflow}\n\n${closing}`];
 
   // eslint-disable-next-line unicorn/no-immediate-mutation -- conditional section builder: later sections are pushed only when their context exists
   sections.push(
-    // 2. Jx schema reference
+    // 2. Jx schema reference — kept in ALL modes (pre-project the model plans starter content)
     JX_SCHEMA_REFERENCE,
     // 3. State shape decision tree
     STATE_SHAPE_DECISION_TREE,
@@ -436,13 +596,23 @@ Be concise. Don't explain what Jx is unless asked. Just build.`,
   }
 
   // 6. Project context
-  if (projectConfig || components || projectRoot) {
+  if (hasProject && (projectConfig || components || projectRoot)) {
     const projectSummary = buildProjectSummary({ projectConfig, components, projectRoot });
     if (projectSummary) {
       sections.push(`## Project Context\n\n${projectSummary}`);
     }
   }
 
+  // 6a. File inventory — a compact map of the project for cross-file work
+  if (hasProject && fileInventory && fileInventory.length > 0) {
+    const capped = fileInventory.slice(0, FILE_INVENTORY_CAP);
+    const more =
+      fileInventory.length > capped.length
+        ? `\n… and ${fileInventory.length - capped.length} more (use list_files)`
+        : "";
+    sections.push(`## Project Files\n\n${capped.join("\n")}${more}`);
+  }
+
   // 7. Error recovery guidance
   sections.push(`## Error Recovery
 

package/src/services/ai-tools.ts

@@ -33,15 +33,26 @@ const PATH_DESCRIPTION =
   "Path to a node in the document, as a JSON array of keys/indices from the root " +
   '(e.g. ["children", 0, "children", 1]). Use read_document to discover valid paths.';
 
+/** Steering error for document tools called with no active tab. */
+function noDocError(): ToolResult {
+  return {
+    success: false,
+    error:
+      "No document is open — use open_document(path) to open one on the canvas, or " +
+      "read_file/write_file to work with project files directly.",
+  };
+}
+
 /**
  * Translate a raw JSON Schema validation error into a Jx-specific actionable message. The LLM needs
- * concrete guidance on HOW to fix errors, not just what rule was violated.
+ * concrete guidance on HOW to fix errors, not just what rule was violated. Shared with the
+ * project-level file tools (ai-project-tools.ts), which pre-validate Jx documents before writing.
  *
  * @param {string} rawError - Message from ajv (e.g. "/children/0/style: must NOT have additional
  *   property")
  * @returns {string}
  */
-function translateValidationError(rawError: string): string {
+export function translateValidationError(rawError: string): string {
   const lower = rawError.toLowerCase();
 
   // Additional property — extract the offending key from the message if present
@@ -162,6 +173,9 @@ async function applyAndValidate(
  *   renderCheck?: (doc: unknown) => Promise<{ ok: true } | { ok: false; error: string }>;
  *   openDocument?: (path: string) => Promise<void>;
  *   projectStyle?: Record<string, string>;
+ *   getProjectStyle?: () => Record<string, string> | undefined;
+ *   findOpenTab?: (path: string) => import("../tabs/tab").Tab | null;
+ *   reloadTab?: (path: string) => Promise<void>;
  * }} ctx
  */
 export function registerAiTools(
@@ -173,6 +187,9 @@ export function registerAiTools(
     renderCheck,
     openDocument,
     projectStyle,
+    getProjectStyle,
+    findOpenTab,
+    reloadTab,
   }: {
     getTab: () => Tab | null;
     validate?: (doc: unknown) => Promise<string[]>;
@@ -180,8 +197,44 @@ export function registerAiTools(
     renderCheck?: (doc: unknown) => Promise<{ ok: true } | { ok: false; error: string }>;
     openDocument?: (path: string) => Promise<void>;
     projectStyle?: Record<string, string> | undefined;
+    /**
+     * Live variant of `projectStyle` — takes precedence; re-read per tool call so a project
+     * bootstrapped mid-session contributes its design tokens.
+     */
+    getProjectStyle?: () => Record<string, string> | undefined;
+    /** The open tab whose documentPath equals a project-relative path (write reconciliation). */
+    findOpenTab?: (path: string) => Tab | null;
+    /** Reload an open tab's document from disk after a file write. */
+    reloadTab?: (path: string) => Promise<void>;
   },
 ) {
+  const styleOf = getProjectStyle ?? (() => projectStyle);
+
+  /**
+   * Guard a disk write against an open tab: refuse while the tab has unsaved changes (the write
+   * would silently diverge from the editor). Returns null when the write may proceed.
+   */
+  function dirtyTabError(relPath: string): ToolResult | null {
+    const tab = findOpenTab?.(relPath);
+    if (tab?.doc.dirty) {
+      return {
+        success: false,
+        error:
+          `"${relPath}" is open in the editor with unsaved changes. Use open_document plus the ` +
+          `document tools to edit it, or ask the user to save or discard their changes first.`,
+      };
+    }
+    return null;
+  }
+
+  /** Refresh an open (clean) tab from disk after a write; annotate the summary accordingly. */
+  async function reconcileAfterWrite(relPath: string, summary: string): Promise<string> {
+    if (findOpenTab?.(relPath)) {
+      await reloadTab?.(relPath);
+      return `${summary} The file's open editor tab was refreshed. (Saved to disk; not undoable.)`;
+    }
+    return `${summary} (Saved to disk; not undoable.)`;
+  }
   registry.register(
     createToolDefinition({
       name: "read_document",
@@ -202,7 +255,7 @@ export function registerAiTools(
       execute(args) {
         const tab = getTab();
         if (!tab) {
-          return { success: false, error: "No document is open." };
+          return noDocError();
         }
         const { path } = args as { path?: JxPath };
         const node =
@@ -246,7 +299,7 @@ export function registerAiTools(
       async execute(args) {
         const tab = getTab();
         if (!tab) {
-          return { success: false, error: "No document is open." };
+          return noDocError();
         }
         const { path, key, value } = args as { path: JxPath; key: string; value?: JxNodeValue };
         const node = getNodeAtPath(tab.doc.document, path);
@@ -259,7 +312,7 @@ export function registerAiTools(
           `Set "${key}" at ${JSON.stringify(path)}.`,
           validate,
           renderCheck,
-          projectStyle,
+          styleOf(),
         );
       },
     }),
@@ -292,7 +345,7 @@ export function registerAiTools(
       async execute(args) {
         const tab = getTab();
         if (!tab) {
-          return { success: false, error: "No document is open." };
+          return noDocError();
         }
         const {
           parentPath,
@@ -337,7 +390,7 @@ export function registerAiTools(
           `Inserted node at ${JSON.stringify([...parentPath, "children", index])}.`,
           validate,
           renderCheck,
-          projectStyle,
+          styleOf(),
         );
       },
     }),
@@ -378,7 +431,7 @@ export function registerAiTools(
       async execute(args) {
         const tab = getTab();
         if (!tab) {
-          return { success: false, error: "No document is open." };
+          return noDocError();
         }
         const { path, property, value } = args as {
           path: JxPath;
@@ -396,7 +449,7 @@ export function registerAiTools(
           `Set style "${prop}" at ${JSON.stringify(path)}.`,
           validate,
           renderCheck,
-          projectStyle,
+          styleOf(),
         );
       },
     }),
@@ -424,7 +477,7 @@ export function registerAiTools(
       async execute(args) {
         const tab = getTab();
         if (!tab) {
-          return { success: false, error: "No document is open." };
+          return noDocError();
         }
         const { path, value } = args as { path: JxPath; value: string };
         if (getNodeAtPath(tab.doc.document, path) === undefined) {
@@ -440,7 +493,7 @@ export function registerAiTools(
           `Set text at ${JSON.stringify(path)}.`,
           validate,
           renderCheck,
-          projectStyle,
+          styleOf(),
         );
       },
     }),
@@ -470,7 +523,7 @@ export function registerAiTools(
       async execute(args) {
         const tab = getTab();
         if (!tab) {
-          return { success: false, error: "No document is open." };
+          return noDocError();
         }
         const { key, value } = args as { key: string; value: JxStateDefinition };
         if (tab.doc.document.state && tab.doc.document.state[key] !== undefined) {
@@ -495,7 +548,7 @@ export function registerAiTools(
           `Added state "${key}".`,
           validate,
           renderCheck,
-          projectStyle,
+          styleOf(),
         );
       },
     }),
@@ -526,7 +579,7 @@ export function registerAiTools(
       async execute(args) {
         const tab = getTab();
         if (!tab) {
-          return { success: false, error: "No document is open." };
+          return noDocError();
         }
         const { key, value } = args as { key: string; value?: JxStateDefinition | null };
         if (!tab.doc.document.state || tab.doc.document.state[key] === undefined) {
@@ -555,7 +608,7 @@ export function registerAiTools(
           value == null ? `Removed state "${key}".` : `Updated state "${key}".`,
           validate,
           renderCheck,
-          projectStyle,
+          styleOf(),
         );
       },
     }),
@@ -592,7 +645,7 @@ export function registerAiTools(
       async execute(args) {
         const tab = getTab();
         if (!tab) {
-          return { success: false, error: "No document is open." };
+          return noDocError();
         }
         const { fromPath, toParentPath, toIndex } = args as {
           fromPath: JxPath;
@@ -620,7 +673,7 @@ export function registerAiTools(
           `Moved node from ${JSON.stringify(fromPath)} to ${JSON.stringify([...toParentPath, "children", toIndex])}.`,
           validate,
           renderCheck,
-          projectStyle,
+          styleOf(),
         );
       },
     }),
@@ -658,6 +711,10 @@ export function registerAiTools(
           };
         }
         const { path: relPath, content } = args as { path: string; content: object };
+        const dirtyError = dirtyTabError(relPath);
+        if (dirtyError) {
+          return dirtyError;
+        }
         const errors = await validate(content);
         if (errors.length > 0) {
           const formatted = errors.map((e) => `- ${translateValidationError(e)}`).join("\n");
@@ -677,7 +734,10 @@ export function registerAiTools(
         }
         try {
           await saveFile(relPath, JSON.stringify(content, null, 2));
-          return { success: true, summary: `Created component at "${relPath}".` };
+          return {
+            success: true,
+            summary: await reconcileAfterWrite(relPath, `Created component at "${relPath}".`),
+          };
         } catch (error) {
           return {
             success: false,
@@ -719,6 +779,10 @@ export function registerAiTools(
           };
         }
         const { path: relPath, content } = args as { path: string; content: object };
+        const dirtyError = dirtyTabError(relPath);
+        if (dirtyError) {
+          return dirtyError;
+        }
         const errors = await validate(content);
         if (errors.length > 0) {
           const formatted = errors.map((e) => `- ${translateValidationError(e)}`).join("\n");
@@ -738,7 +802,10 @@ export function registerAiTools(
         }
         try {
           await saveFile(relPath, JSON.stringify(content, null, 2));
-          return { success: true, summary: `Created page at "${relPath}".` };
+          return {
+            success: true,
+            summary: await reconcileAfterWrite(relPath, `Created page at "${relPath}".`),
+          };
         } catch (error) {
           return {
             success: false,
@@ -831,7 +898,7 @@ export function registerAiTools(
       async execute(args) {
         const tab = getTab();
         if (!tab) {
-          return { success: false, error: "No document is open." };
+          return noDocError();
         }
         const { path } = args as { path: JxPath };
         if (path.length < 2) {
@@ -846,7 +913,7 @@ export function registerAiTools(
           `Removed node at ${JSON.stringify(path)}.`,
           validate,
           renderCheck,
-          projectStyle,
+          styleOf(),
         );
       },
     }),

package/src/services/automation.ts

@@ -12,6 +12,7 @@
 import { renderOnly, updateUi } from "../store";
 import { activeTab, workspace } from "../workspace/workspace";
 import { applyPanelCollapse, view } from "../view";
+import { setEditZoom as applyEditZoomLevel } from "../canvas/canvas-utils";
 import type { JxPath } from "../state";
 
 /** Callbacks injected from studio.ts (module-local helpers or imports kept out of this module). */
@@ -43,6 +44,7 @@ export interface AutomationApi {
   setStatus: (text: string) => void;
   setTheme: (color: string) => void;
   setZoom: (zoom: number) => void;
+  setEditZoom: (zoom: number) => void;
   waitForCanvasReady: (timeoutMs?: number) => Promise<void>;
 }
 
@@ -94,6 +96,15 @@ export function createAutomationApi(deps: AutomationDeps): AutomationApi {
       deps.render();
     },
     setRightTab(tab: string) {
+      // "assistant" now lives in the persistent chat sidebar, not the right panel — keep the
+      // Screenshot-manifest verb working by opening that sidebar instead.
+      if (tab === "assistant") {
+        view.chatPanelCollapsed = false;
+        applyPanelCollapse();
+        renderOnly("chatPanel");
+        deps.render();
+        return;
+      }
       updateUi("rightTab", tab);
       deps.render();
     },
@@ -107,6 +118,11 @@ export function createAutomationApi(deps: AutomationDeps): AutomationApi {
       updateUi("zoom", zoom);
       deps.render();
     },
+    setEditZoom(zoom: number) {
+      // Deliberately NOT deps.render(): live edit zoom must never re-render the canvas (it would
+      // Rebuild the iframe DOM) — setEditZoom applies bare style writes, matching production paths.
+      applyEditZoomLevel(zoom);
+    },
     waitForCanvasReady(timeoutMs = 30_000) {
       return new Promise((resolve, reject) => {
         const started = Date.now();

package/src/services/context-resolver.ts

@@ -0,0 +1,73 @@
+/**
+ * Context resolver — generic `#/$context/<pointer>` resolution over the project config
+ * (specs/extensions.md §9.1).
+ *
+ * Pointers walk the project config segment by segment. `{@param}` segments substitute values from a
+ * caller-provided scope (e.g. the form's current value record), and the `$formats` virtual root
+ * resolves to the registered format names instead of a project.json key.
+ */
+
+/** Options for {@link resolveContextPointer}. */
+export interface ResolveContextOptions {
+  /** The project configuration object the pointer walks over. */
+  projectConfig: Record<string, unknown>;
+  /** Scope record supplying `{@param}` substitutions (e.g. the enclosing form value). */
+  scope?: Record<string, unknown> | undefined;
+  /** Registered formats backing the `$formats` virtual root. */
+  formats?: { name: string }[] | undefined;
+}
+
+/** Matches a `{@param}` pointer segment, capturing the param name. */
+const PARAM_SEGMENT = /^\{@(\w+)\}$/;
+
+/**
+ * Resolve a `#/$context/<seg>/<seg>…` pointer.
+ *
+ * - `{@param}` segments substitute from `opts.scope`; an unresolvable param yields `undefined`.
+ * - The `$formats` virtual root returns the format names from `opts.formats`.
+ * - Every other pointer is a plain JSON-pointer walk over `opts.projectConfig` — no key is
+ *   special-cased, so both legacy (`contentTypes`) and newer (`content`) sections resolve alike.
+ *
+ * @param {string} pointer
+ * @param {ResolveContextOptions} opts
+ * @returns {unknown} The resolved value, or `undefined` when the pointer does not resolve.
+ */
+export function resolveContextPointer(pointer: string, opts: ResolveContextOptions): unknown {
+  if (!pointer.startsWith("#/$context/")) {
+    return undefined;
+  }
+
+  const segments: string[] = [];
+  for (const raw of pointer.slice("#/$context/".length).split("/")) {
+    const match = raw.match(PARAM_SEGMENT);
+    if (match) {
+      const value = opts.scope?.[match[1]!];
+      if (typeof value !== "string" && typeof value !== "number") {
+        return undefined;
+      }
+      const substituted = String(value);
+      if (!substituted) {
+        return undefined;
+      }
+      segments.push(substituted);
+    } else {
+      segments.push(raw);
+    }
+  }
+
+  if (segments[0] === "$formats") {
+    if (segments.length !== 1) {
+      return undefined;
+    }
+    return (opts.formats ?? []).map((format) => format.name);
+  }
+
+  let node: unknown = opts.projectConfig;
+  for (const segment of segments) {
+    if (node === null || typeof node !== "object") {
+      return undefined;
+    }
+    node = (node as Record<string, unknown>)[segment];
+  }
+  return node;
+}