@camox/api-contract 0.62.0 → 0.65.1

package/dist/threads.d.ts

@@ -10,6 +10,14 @@ import { Message } from "@earendil-works/pi-ai";
  * studio as they sent it (`editorTextOf`).
  */
 export declare const EDITOR_MESSAGE_ENTRY = "camox.editor-message";
+/**
+ * The kind of the transcript entry recording a Connected Agent's message (ADR 0030), with its
+ * member and client as data (`connectedAgentMessageDataSchema`). The model reads it as a user
+ * message, as it does an editor's: its first text part is what the Connected Agent wrote, and a
+ * second one, which only the model reads, says who sent it. Studios show it as the member's AI,
+ * never as the member.
+ */
+export declare const CONNECTED_AGENT_MESSAGE_ENTRY = "camox.connected-agent-message";
 /** The kind of the transcript entry recording that an editor stopped a run, with them as data. */
 export declare const RUN_STOPPED_ENTRY = "camox.run-stopped";
 /**
@@ -27,7 +35,8 @@ export declare const RECONCILE_ENTRY = "camox.reconcile";
 /**
  * The kind of the transcript entry opening a draft's thread a Live thread handed a request off
  * to: the Brief, which the model reads and editors see as from Camox, ahead of the editor's
- * messages.
+ * messages. In a draft Camox opened, such as its Patrol Draft, Camox's own messages are Briefs
+ * too, with their `operationId` as data, and start the agent's run, which acts for Camox.
  */
 export declare const BRIEF_ENTRY = "camox.brief";
 /**
@@ -45,8 +54,8 @@ export declare const PUSH_ENTRY = "camox.push";
 /** How a pushed head's build ended: built, built with type errors, or built but not previewed. */
 export declare const pushOutcomeSchema: z.ZodEnum<{
   built: "built";
-  typeErrors: "typeErrors";
   notPreviewed: "notPreviewed";
+  typeErrors: "typeErrors";
 }>;
 export type PushOutcome = z.infer<typeof pushOutcomeSchema>;
 /**
@@ -56,6 +65,8 @@ export type PushOutcome = z.infer<typeof pushOutcomeSchema>;
 export declare const START_DRAFT_TOOL = "startDraft";
 /** The agent's tool building its code changes mid-turn, which the end of a turn also does. */
 export declare const BUILD_TOOL = "build";
+/** The agent's tool rendering the draft in a browser and returning screenshots to the model. */
+export declare const LOOK_TOOL = "look";
 /**
  * The tools whose calls change a draft: the content tools that write, and the code tools that
  * write files. The model calls the code tools, and code mode scripts call both. A test in the API
@@ -103,6 +114,32 @@ export declare const threadSenderSchema: z.ZodObject<{
 export type ThreadSender = z.infer<typeof threadSenderSchema>;
 /** Whether `data` names a sender. */
 export declare const isSender: (data: unknown) => data is ThreadSender;
+/**
+ * The app a Connected Agent runs in, by the name it gave: verified when it comes from a Client ID
+ * Metadata Document, self-asserted otherwise.
+ */
+export declare const connectedAgentClientSchema: z.ZodObject<{
+  name: z.ZodString;
+  verified: z.ZodBoolean;
+}, z.core.$strip>;
+export type ConnectedAgentClient = z.infer<typeof connectedAgentClientSchema>;
+/**
+ * What a Connected Agent's message entry records: the member it acts as, its client, and the
+ * operation id it was sent with.
+ */
+export declare const connectedAgentMessageDataSchema: z.ZodObject<{
+  member: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    image: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>;
+  client: z.ZodObject<{
+    name: z.ZodString;
+    verified: z.ZodBoolean;
+  }, z.core.$strip>;
+  operationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ConnectedAgentMessageData = z.infer<typeof connectedAgentMessageDataSchema>;
 /** What a push's entry records: who pushed, their commits' subjects, oldest first, and the build. */
 export declare const pushDataSchema: z.ZodObject<{
   pusher: z.ZodObject<{
@@ -113,8 +150,8 @@ export declare const pushDataSchema: z.ZodObject<{
   subjects: z.ZodArray<z.ZodString>;
   outcome: z.ZodEnum<{
     built: "built";
-    typeErrors: "typeErrors";
     notPreviewed: "notPreviewed";
+    typeErrors: "typeErrors";
   }>;
 }, z.core.$strip>;
 export type PushData = z.infer<typeof pushDataSchema>;
@@ -142,18 +179,18 @@ export type StartedDraft = z.infer<typeof startedDraftSchema>;
 /** How a write touched what it names. */
 export declare const touchKindSchema: z.ZodEnum<{
   created: "created";
+  deleted: "deleted";
   edited: "edited";
   moved: "moved";
-  deleted: "deleted";
   settings: "settings";
 }>;
 export type TouchKind = z.infer<typeof touchKindSchema>;
 export declare const touchSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   kind: z.ZodEnum<{
     created: "created";
+    deleted: "deleted";
     edited: "edited";
     moved: "moved";
-    deleted: "deleted";
     settings: "settings";
   }>;
   locale: z.ZodOptional<z.ZodString>;
@@ -163,9 +200,9 @@ export declare const touchSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
   kind: z.ZodEnum<{
     created: "created";
+    deleted: "deleted";
     edited: "edited";
     moved: "moved";
-    deleted: "deleted";
     settings: "settings";
   }>;
   locale: z.ZodOptional<z.ZodString>;
@@ -174,9 +211,9 @@ export declare const touchSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
   kind: z.ZodEnum<{
     created: "created";
+    deleted: "deleted";
     edited: "edited";
     moved: "moved";
-    deleted: "deleted";
     settings: "settings";
   }>;
   locale: z.ZodOptional<z.ZodString>;
@@ -194,9 +231,9 @@ export declare const touchedBatchSchema: z.ZodObject<{
   touches: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodEnum<{
       created: "created";
+      deleted: "deleted";
       edited: "edited";
       moved: "moved";
-      deleted: "deleted";
       settings: "settings";
     }>;
     locale: z.ZodOptional<z.ZodString>;
@@ -206,9 +243,9 @@ export declare const touchedBatchSchema: z.ZodObject<{
   }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodEnum<{
       created: "created";
+      deleted: "deleted";
       edited: "edited";
       moved: "moved";
-      deleted: "deleted";
       settings: "settings";
     }>;
     locale: z.ZodOptional<z.ZodString>;
@@ -217,9 +254,9 @@ export declare const touchedBatchSchema: z.ZodObject<{
   }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodEnum<{
       created: "created";
+      deleted: "deleted";
       edited: "edited";
       moved: "moved";
-      deleted: "deleted";
       settings: "settings";
     }>;
     locale: z.ZodOptional<z.ZodString>;
@@ -236,6 +273,17 @@ export type ThreadMessage = {
   sender: ThreadSender;
   text: string;
 } |
+/**
+ * A member's Connected Agent's message: the member's own AI, in its client, writing as itself.
+ * Never shown as the member's own words.
+ */
+{
+  id: string;
+  from: "connectedAgent";
+  member: ThreadSender;
+  client: ConnectedAgentClient;
+  text: string;
+} |
 /** Camox's own message, starting a turn it began itself: why it did. */
 {
   id: string;
@@ -291,10 +339,12 @@ export type ThreadMessage = {
  * - `changing`: a call of that round changes the draft (`CHANGING_TOOLS`), as soon as it's written
  *   or, in a code mode script, as soon as the script calls one.
  * - `building`: its `build` call runs, or the end of the turn builds its code changes.
+ * - `checking`: it looks at what it designed, from writing a `look` call until the model is
+ *   called again.
  * - `fixing`: the end of the turn's build failed, and the agent fixes it.
  * - `startingDraft`: on Live, its `startDraft` call runs.
  */
-export type AgentActivity = "thinking" | "exploring" | "changing" | "building" | "fixing" | "startingDraft";
+export type AgentActivity = "thinking" | "exploring" | "changing" | "building" | "checking" | "fixing" | "startingDraft";
 /** Everything the studio shows for a thread. */
 export type ThreadView = {
   messages: readonly ThreadMessage[];
@@ -324,6 +374,8 @@ export type ThreadState = {
    * or making it until the model is called again.
    */
   changing?: boolean;
+  /** Whether the model's latest round calls `look`: from writing the call until it's called again. */
+  checking?: boolean;
   /** The drafts the thread's cards name, as the thread last looked them up. */
   drafts?: DraftCardStates;
 };
@@ -337,6 +389,11 @@ type ThreadStep = {
   text: string;
   /** The draft the message went to, as the agent on Live handed the request off. */
   handedOffTo?: string;
+} | {
+  type: "connectedAgent";
+  member: ThreadSender;
+  client: ConnectedAgentClient;
+  text: string;
 } |
 /** Camox starting a turn of its own, saying why. */
 {
@@ -509,7 +566,7 @@ export declare const editorTextOf: (content: Message["content"]) => string;
  * run is over, or a later message started another run after its last model call came back
  * unfinished. While Pi retries a failed call, the run goes on, so the turn shows as working.
  */
-export declare function threadViewOf({ steps, running, toolCalls, callingTools, changing, drafts }: ThreadState): ThreadView;
+export declare function threadViewOf({ steps, running, toolCalls, callingTools, changing, checking, drafts }: ThreadState): ThreadView;
 /** Folds one of Pi's agent events into the thread's state. */
 export declare function reduceThreadState(state: ThreadState, event: AgentEvent): ThreadState;
 /** Folds a batch of Pi's agent events into the thread's state. */

package/dist/threads.js

@@ -8,6 +8,14 @@ import { z } from "zod";
 * studio as they sent it (`editorTextOf`).
 */
 const EDITOR_MESSAGE_ENTRY = "camox.editor-message";
+/**
+* The kind of the transcript entry recording a Connected Agent's message (ADR 0030), with its
+* member and client as data (`connectedAgentMessageDataSchema`). The model reads it as a user
+* message, as it does an editor's: its first text part is what the Connected Agent wrote, and a
+* second one, which only the model reads, says who sent it. Studios show it as the member's AI,
+* never as the member.
+*/
+const CONNECTED_AGENT_MESSAGE_ENTRY = "camox.connected-agent-message";
 /** The kind of the transcript entry recording that an editor stopped a run, with them as data. */
 const RUN_STOPPED_ENTRY = "camox.run-stopped";
 /**
@@ -25,7 +33,8 @@ const RECONCILE_ENTRY = "camox.reconcile";
 /**
 * The kind of the transcript entry opening a draft's thread a Live thread handed a request off
 * to: the Brief, which the model reads and editors see as from Camox, ahead of the editor's
-* messages.
+* messages. In a draft Camox opened, such as its Patrol Draft, Camox's own messages are Briefs
+* too, with their `operationId` as data, and start the agent's run, which acts for Camox.
 */
 const BRIEF_ENTRY = "camox.brief";
 /**
@@ -53,6 +62,8 @@ const pushOutcomeSchema = z.enum([
 const START_DRAFT_TOOL = "startDraft";
 /** The agent's tool building its code changes mid-turn, which the end of a turn also does. */
 const BUILD_TOOL = "build";
+/** The agent's tool rendering the draft in a browser and returning screenshots to the model. */
+const LOOK_TOOL = "look";
 /**
 * The tools whose calls change a draft: the content tools that write, and the code tools that
 * write files. The model calls the code tools, and code mode scripts call both. A test in the API
@@ -61,6 +72,7 @@ const BUILD_TOOL = "build";
 const CHANGING_TOOLS = /* @__PURE__ */ new Set([
 	"addBackToLocale",
 	"addLocale",
+	"applyFindingFix",
 	"createBlock",
 	"createCollectionRecord",
 	"createPage",
@@ -97,6 +109,23 @@ const threadSenderSchema = z.object({
 });
 /** Whether `data` names a sender. */
 const isSender = (data) => threadSenderSchema.safeParse(data).success;
+/**
+* The app a Connected Agent runs in, by the name it gave: verified when it comes from a Client ID
+* Metadata Document, self-asserted otherwise.
+*/
+const connectedAgentClientSchema = z.object({
+	name: z.string(),
+	verified: z.boolean()
+});
+/**
+* What a Connected Agent's message entry records: the member it acts as, its client, and the
+* operation id it was sent with.
+*/
+const connectedAgentMessageDataSchema = z.object({
+	member: threadSenderSchema,
+	client: connectedAgentClientSchema,
+	operationId: z.string().optional()
+});
 /** What a push's entry records: who pushed, their commits' subjects, oldest first, and the build. */
 const pushDataSchema = z.object({
 	pusher: threadSenderSchema,
@@ -291,6 +320,19 @@ function threadStepOf(entry) {
 				...handedOffTo && { handedOffTo }
 			};
 		}
+		if (entry.kind === "camox.connected-agent-message") {
+			const data = connectedAgentMessageDataSchema.safeParse(entry.data).data;
+			return data && {
+				id,
+				type: "connectedAgent",
+				member: senderOf(data.member),
+				client: {
+					name: data.client.name,
+					verified: data.client.verified
+				},
+				text: editorTextOf(message.content)
+			};
+		}
 		if (entry.kind === "camox.brief") return {
 			id,
 			type: "camox",
@@ -331,7 +373,7 @@ function threadStepOf(entry) {
 * run is over, or a later message started another run after its last model call came back
 * unfinished. While Pi retries a failed call, the run goes on, so the turn shows as working.
 */
-function threadViewOf({ steps, running, toolCalls = [], callingTools = false, changing = false, drafts = {} }) {
+function threadViewOf({ steps, running, toolCalls = [], callingTools = false, changing = false, checking = false, drafts = {} }) {
 	const messages = [];
 	let waiting;
 	let unfinished = false;
@@ -374,6 +416,17 @@ function threadViewOf({ steps, running, toolCalls = [], callingTools = false, ch
 			waiting = step.id;
 			break;
 		}
+		case "connectedAgent":
+			if (unfinished) fail();
+			messages.push({
+				id: step.id,
+				from: "connectedAgent",
+				member: step.member,
+				client: step.client,
+				text: step.text
+			});
+			waiting = step.id;
+			break;
 		case "camox":
 			if (unfinished) fail();
 			messages.push({
@@ -458,14 +511,16 @@ function threadViewOf({ steps, running, toolCalls = [], callingTools = false, ch
 			status,
 			toolCalls,
 			callingTools,
-			changing
+			changing,
+			checking
 		})
 	};
 }
 /** What the agent is doing during a run, from where the turn's build stands and its tool calls. */
-function activityOf({ status, toolCalls, callingTools, changing }) {
+function activityOf({ status, toolCalls, callingTools, changing, checking }) {
 	const calling = (name) => toolCalls.some((call) => call.name === name);
 	if (status === "building" || calling("build")) return "building";
+	if (checking) return "checking";
 	if (status === "fixing") return "fixing";
 	if (calling("startDraft")) return "startingDraft";
 	if (changing) return "changing";
@@ -476,6 +531,8 @@ function activityOf({ status, toolCalls, callingTools, changing }) {
 const changes = (name) => CHANGING_TOOLS.has(name);
 /** Whether a block of the model's message is a call of a tool that changes the draft. */
 const callsChangingTool = (block) => block.type === "toolCall" && changes(block.name);
+/** Whether a block of the model's message is a call of `look`. */
+const callsLook = (block) => block.type === "toolCall" && block.name === "look";
 const append = (state, entry) => {
 	const step = entry && threadStepOf(entry);
 	if (!step || state.steps.some((known) => known.id === step.id)) return state;
@@ -499,6 +556,7 @@ function reduceThreadState(state, event) {
 				running: event.run !== void 0,
 				toolCalls,
 				callingTools: generated.some((part) => part.type === "toolCall"),
+				checking: generated.some(callsLook) || toolCalls.some((call) => call.name === "look"),
 				changing: generated.some(callsChangingTool) || toolCalls.some((call) => changes(call.name)) || event.nestedTools.some((nested) => changes(nested.name) && toolCalls.some((call) => nested.parentCallId === call.callId || nested.parentCallId.startsWith(`${call.callId}/`)))
 			};
 		}
@@ -511,12 +569,14 @@ function reduceThreadState(state, event) {
 			running: false,
 			toolCalls: [],
 			callingTools: false,
-			changing: false
+			changing: false,
+			checking: false
 		};
 		case "message_start": return event.message.role === "assistant" ? {
 			...state,
 			callingTools: false,
-			changing: false
+			changing: false,
+			checking: false
 		} : state;
 		case "message_update": {
 			const calls = event.changes.flatMap((change) => change.type === "toolcall_start" || change.type === "block" ? [change.block] : change.type === "message" ? change.message.content : []);
@@ -524,7 +584,8 @@ function reduceThreadState(state, event) {
 			return {
 				...state,
 				callingTools: state.callingTools || calls.some((block) => block.type === "toolCall"),
-				changing: state.changing || calls.some(callsChangingTool)
+				changing: state.changing || calls.some(callsChangingTool),
+				checking: state.checking || calls.some(callsLook)
 			};
 		}
 		case "tool_execution_start": {
@@ -536,6 +597,7 @@ function reduceThreadState(state, event) {
 			return {
 				...state,
 				changing,
+				checking: state.checking || event.toolName === "look",
 				toolCalls: [...state.toolCalls ?? [], {
 					callId: event.toolCallId,
 					name: event.toolName
@@ -566,4 +628,4 @@ function reduceThreadFrame(state, frame) {
 }
 
 //#endregion
-export { BRIEF_ENTRY, BUILD_STATUS_ENTRY, BUILD_TOOL, CHANGING_TOOLS, DRAFT_ENDED_ENTRY, EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, PUSH_ENTRY, RECONCILE_ENTRY, RUN_STOPPED_ENTRY, START_DRAFT_TOOL, THREAD_ENDED_CLOSE_CODE, buildStatusDataSchema, buildStatusSchema, editorMessageDataSchema, editorSelectionSchema, editorTextOf, editorWhereSchema, isSender, pushDataSchema, pushOutcomeSchema, reconcileDataSchema, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftCardSchema, startedDraftSchema, textOf, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };
+export { BRIEF_ENTRY, BUILD_STATUS_ENTRY, BUILD_TOOL, CHANGING_TOOLS, CONNECTED_AGENT_MESSAGE_ENTRY, DRAFT_ENDED_ENTRY, EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, LOOK_TOOL, PUSH_ENTRY, RECONCILE_ENTRY, RUN_STOPPED_ENTRY, START_DRAFT_TOOL, THREAD_ENDED_CLOSE_CODE, buildStatusDataSchema, buildStatusSchema, connectedAgentClientSchema, connectedAgentMessageDataSchema, editorMessageDataSchema, editorSelectionSchema, editorTextOf, editorWhereSchema, isSender, pushDataSchema, pushOutcomeSchema, reconcileDataSchema, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftCardSchema, startedDraftSchema, textOf, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.62.0",
+  "version": "0.65.1",
   "license": "MIT",
   "files": [
     "src",
@@ -51,6 +51,10 @@
     "./router": {
       "types": "./dist/router.d.ts",
       "default": "./dist/router.js"
+    },
+    "./layout-routes": {
+      "types": "./dist/layout-routes.d.ts",
+      "default": "./dist/layout-routes.js"
     }
   },
   "dependencies": {
@@ -60,7 +64,8 @@
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.3.0",
-    "@earendil-works/pi-durable": "1.3.0"
+    "@earendil-works/pi-durable": "1.3.0",
+    "tsrs": "0.20.1-ts7.1.0-beta"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "1.3.0",
@@ -85,6 +90,7 @@
           "^production",
           "{workspaceRoot}/apps/api/src/**/*",
           "{workspaceRoot}/packages/ai-tools/src/**/*",
+          "{workspaceRoot}/tsconfig.dts.api-contract.json",
           "!{workspaceRoot}/**/*.test.ts"
         ]
       }

package/src/drafts.ts

@@ -25,6 +25,46 @@ export const PUBLISHING_DRAFT_HEADER = "x-camox-publishing-draft";
  */
 export const PUBLISHING_DRAFT_VAR = "CAMOX_PUBLISHING_DRAFT";
 
+/**
+ * Request header carrying a look token (ADR 0032): a short-lived, read-only credential the API
+ * signs for the agent's `look` tool, naming one project and one draft. A request carrying a valid
+ * one reads that draft's content, named with `DRAFT_HEADER`, as a member would, without a session.
+ * It writes nothing, reads no other draft, and reads none of Live's private data.
+ */
+export const LOOK_TOKEN_HEADER = "x-camox-look-token";
+
+/**
+ * The cookie the browser `look` drives carries the look token in, set for the website's host
+ * only, so third-party requests never see it. The website forwards it as `LOOK_TOKEN_HEADER`.
+ */
+export const LOOK_TOKEN_COOKIE = "camox_look";
+
+/**
+ * The website's lightweight document the browser `look` drives loads (the SDK runtime's
+ * `RUNTIME_ROUTE_PATHS.look`): one page of the draft `DRAFT_SEARCH_PARAM` names, at the path
+ * `LOOK_PATH_PARAM` gives in the locale `LOOK_LOCALE_PARAM` names, its Default Locale without.
+ */
+export const LOOK_DOCUMENT_PATH = "/_camox/look";
+export const LOOK_PATH_PARAM = "path";
+export const LOOK_LOCALE_PARAM = "locale";
+
+/**
+ * The look document's Block Definition mode: instead of a page, the block of the Block Definition
+ * `LOOK_BLOCK_DEFINITION_PARAM` names, alone in the site's shell, with its default content and
+ * Block Settings and the overrides `LOOK_CONTENT_PARAM` and `LOOK_SETTINGS_PARAM` give as JSON, in
+ * the shape the content tools take.
+ */
+export const LOOK_BLOCK_DEFINITION_PARAM = "blockDefinition";
+export const LOOK_CONTENT_PARAM = "content";
+export const LOOK_SETTINGS_PARAM = "settings";
+
+/**
+ * The id of a block shown without being placed, as the look document's Block Definition mode
+ * shows it: never a stored block's, which are UUIDs. Its element is
+ * `[data-camox-viewport-block="unplaced"]`.
+ */
+export const UNPLACED_BLOCK_ID = "unplaced";
+
 /**
  * Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
  * exist yet. Its value is `"1"`.
@@ -87,19 +127,34 @@ export const PUBLISH_BLOCKED_ERROR = "PUBLISH_BLOCKED";
 
 /**
  * oRPC error code for a publish refused because the draft still has pending translations: every
- * locale goes live together, unless the caller publishes anyway (ADR 0017).
+ * locale goes live together, and there is no publishing anyway (ADR 0033).
  */
 export const TRANSLATIONS_PENDING_ERROR = "TRANSLATIONS_PENDING";
 
+/**
+ * oRPC error code for a publish refused because the draft has open findings, each to fix or for a
+ * member to dismiss: there is no publishing past them (ADR 0033).
+ */
+export const FINDINGS_OPEN_ERROR = "FINDINGS_OPEN";
+
+/**
+ * oRPC error code for a publish refused because a patroller's check at publish hasn't read the
+ * draft's latest changes yet: publishing waits for it (ADR 0033).
+ */
+export const CHECKS_RUNNING_ERROR = "CHECKS_RUNNING";
+
 /**
  * Why the publish tool published nothing of a draft with changes, and returned a fresh preview to
  * review again, by the error code of each: Live changed since the preview, the draft has blockers,
- * translations are still running, or the draft's code changed since the preview.
+ * translations are still running, the draft has open findings, a check at publish is still
+ * running, or the draft's code changed since the preview.
  */
 export const NOT_PUBLISHED_CODES = {
   conflictsChanged: CONFLICTS_CHANGED_ERROR,
   blocked: PUBLISH_BLOCKED_ERROR,
   translating: TRANSLATIONS_PENDING_ERROR,
+  findings: FINDINGS_OPEN_ERROR,
+  checking: CHECKS_RUNNING_ERROR,
   revisionChanged: REVISION_CHANGED_ERROR,
 } as const;
 
@@ -133,6 +188,7 @@ const BLOCK_WRITES: Record<keyof Router["blocks"], boolean> = {
   getUsageCounts: false,
   getPagesUsing: false,
   getSyncedContent: false,
+  getUnplaced: false,
   create: true,
   updateContent: true,
   updateSettings: true,
@@ -208,6 +264,14 @@ const LOCALE_WRITES: Record<keyof Router["locales"], boolean> = {
   addBack: true,
 };
 
+// Applying a finding's fix edits content as the member would; dismissing one is the project's,
+// never content (ADR 0034).
+const PATROL_WRITES: Record<keyof Router["patrol"], boolean> = {
+  get: false,
+  applyFix: true,
+  dismissFinding: false,
+};
+
 // `definitions` is absent: its sync is a release, never a studio content write.
 const CONTENT_WRITES: Partial<Record<keyof Router, Record<string, boolean>>> = {
   blocks: BLOCK_WRITES,
@@ -215,6 +279,7 @@ const CONTENT_WRITES: Partial<Record<keyof Router, Record<string, boolean>>> = {
   collectionDefinitions: COLLECTION_WRITES,
   files: FILE_WRITES,
   pages: PAGE_WRITES,
+  patrol: PATROL_WRITES,
   repeatableItems: ITEM_WRITES,
 };
 

package/src/layout-routes.ts

@@ -0,0 +1,51 @@
+/** How a layout's pages come about: authored by editors, derived from data, or one fixed page. */
+export type LayoutKind = "curated" | "derived" | "singleton";
+
+/** A layout as route matching reads it: its id, which is its file route, and its kind. */
+export type LayoutRoute = { id: string; kind: LayoutKind };
+
+/** The segments of a layout's file route, such as `blog.$slug`: `$` segments are params. */
+export function routeSegments(id: string) {
+  return id.split(".");
+}
+
+/**
+ * The singleton or derived layout whose route matches `pathname`, a path in its Locale, with its
+ * params, or null. The route with the fewest params wins, so a singleton's fixed route wins over
+ * a derived route that would match it too. The SDK renders pages and the API checks them with it.
+ */
+export function matchLayoutRoute<L>(
+  layouts: readonly L[],
+  pathname: string,
+  routeOf: (layout: L) => LayoutRoute,
+): { layout: L; params: Record<string, string> } | null {
+  const path = pathname.replace(/^\/|\/$/g, "").split("/");
+  const paramCount = (layout: L) =>
+    routeSegments(routeOf(layout).id).filter((s) => s.startsWith("$")).length;
+  const candidates = layouts
+    .filter((layout) => routeOf(layout).kind !== "curated")
+    .sort((a, b) => paramCount(a) - paramCount(b));
+  for (const layout of candidates) {
+    const segments = routeSegments(routeOf(layout).id);
+    if (segments.length !== path.length) continue;
+    const params: Record<string, string> = {};
+    let matches = true;
+    for (const [index, segment] of segments.entries()) {
+      let value: string;
+      try {
+        value = decodeURIComponent(path[index]!);
+      } catch {
+        matches = false;
+        break;
+      }
+      if (segment.startsWith("$") && value && !value.includes("/"))
+        params[segment.slice(1)] = value;
+      else if (segment !== value) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) return { layout, params };
+  }
+  return null;
+}

package/src/locales.ts

@@ -15,6 +15,13 @@ export function localePrefix(locale: LocaleView): string {
   return locale.isDefault ? "" : `/${locale.tag.toLowerCase()}`;
 }
 
+/** A locale-relative path under its locale's prefix, keeping its search and hash: `/` is `/de`. */
+export function localizedPath(path: string, locale: LocaleView): string {
+  const prefix = localePrefix(locale);
+  if (!prefix) return path;
+  return path === "/" || /^\/[?#]/.test(path) ? `${prefix}${path.slice(1)}` : `${prefix}${path}`;
+}
+
 /**
  * The locale a runtime path names, and the path after its prefix, without search or hash. A first
  * segment that isn't a non-default locale's prefix leaves the path the default locale's. A