@camox/api-contract 0.68.0 → 0.71.0

package/dist/drafts.d.ts

@@ -69,6 +69,54 @@ export type LookPlaceholderHeight = (typeof LOOK_PLACEHOLDER_HEIGHTS)[number];
  * `[data-camox-viewport-block="unplaced"]`.
  */
 export declare const UNPLACED_BLOCK_ID = "unplaced";
+/**
+ * The attributes the website's artifact frames carry: the artifact field's name, and the id of the
+ * Repeatable Item holding it, when an item's. With the block's `data-camox-viewport-block`, they
+ * find one artifact's frame (`lookArtifactSelector`).
+ */
+export declare const ARTIFACT_FIELD_ATTRIBUTE = "data-camox-artifact";
+export declare const ARTIFACT_ITEM_ATTRIBUTE = "data-camox-item";
+/** The CSS selector of the frame of an artifact field of a block, or of one of its items. */
+export declare const lookArtifactSelector: ({ block, item, field }: {
+  block: string;
+  item?: string;
+  field: string;
+}) => string;
+/** An artifact's Timeline, as its runtime declares it: Marks by name, at times in ms. */
+export type LookTimeline = {
+  duration: number;
+  loop: boolean;
+  marks: Record<string, number>;
+  /** The Mark whose frame stands for the artifact, or null. */
+  poster: string | null;
+};
+/**
+ * One finding of an artifact's guardrail report, about motion that escapes its Timeline or will
+ * look broken: a Web Animation the runtime didn't make (a CSS animation, a CSS transition that no
+ * visitor triggered, one the source made itself), a live timer, a Track the runtime skipped
+ * because it can't play it, Tracks on one element and property that overlap, or a loop cut,
+ * where a looping Timeline's last frame differs from its first.
+ */
+export type LookGuardrailFinding = {
+  kind: "animation" | "timer" | "track" | "overlap" | "loop-cut";
+  /** What's wrong and what to do instead, for the Artifact Agent. */
+  text: string;
+};
+/**
+ * What the look document's artifact frames hold under `LOOK_ARTIFACT_CAPTURE`, for the browser
+ * `look` drives: the artifact's Timeline, null when it declares none; seeking it to `t` ms,
+ * resolved once the frame at that time painted, with the error `render` threw, if it did; and its
+ * guardrail report, empty when nothing escapes its Timeline. Frames of an SDK older than
+ * Timelines hold nothing there.
+ */
+export type LookArtifactCapture = {
+  timeline(): Promise<LookTimeline | null>;
+  seek(t: number): Promise<{
+    error?: string;
+  }>;
+  guardrail(): Promise<LookGuardrailFinding[]>;
+};
+export declare const LOOK_ARTIFACT_CAPTURE = "camoxCapture";
 /**
  * Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
  * exist yet. Its value is `"1"`.

package/dist/drafts.js

@@ -69,6 +69,16 @@ const LOOK_PLACEHOLDER_HEIGHTS = ["short", "tall"];
 */
 const UNPLACED_BLOCK_ID = "unplaced";
 /**
+* The attributes the website's artifact frames carry: the artifact field's name, and the id of the
+* Repeatable Item holding it, when an item's. With the block's `data-camox-viewport-block`, they
+* find one artifact's frame (`lookArtifactSelector`).
+*/
+const ARTIFACT_FIELD_ATTRIBUTE = "data-camox-artifact";
+const ARTIFACT_ITEM_ATTRIBUTE = "data-camox-item";
+/** The CSS selector of the frame of an artifact field of a block, or of one of its items. */
+const lookArtifactSelector = ({ block, item, field }) => `[data-camox-viewport-block="${block}"] iframe[${ARTIFACT_FIELD_ATTRIBUTE}="${field}"]` + (item ? `[${ARTIFACT_ITEM_ATTRIBUTE}="${item}"]` : `:not([${ARTIFACT_ITEM_ATTRIBUTE}])`);
+const LOOK_ARTIFACT_CAPTURE = "camoxCapture";
+/**
 * Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
 * exist yet. Its value is `"1"`.
 */
@@ -236,4 +246,4 @@ function isContentWrite(path) {
 }
 
 //#endregion
-export { CAMOX_ACTOR, CAMOX_NAME, CHECKS_RUNNING_ERROR, CONFLICTS_CHANGED_ERROR, DRAFT_CREATE_HEADER, DRAFT_ENDED_ERROR_CODE, DRAFT_HEADER, DRAFT_SEARCH_PARAM, FINDINGS_OPEN_ERROR, LIVE_READ_ONLY_ERROR, LOCALE_HEADER, LOOK_BLOCKS_PARAM, LOOK_BLOCK_DEFINITION_PARAM, LOOK_CONTENT_PARAM, LOOK_DOCUMENT_PATH, LOOK_LAYOUT_DEFINITION_PARAM, LOOK_LOCALE_PARAM, LOOK_PATH_PARAM, LOOK_PLACEHOLDER_HEIGHTS, LOOK_PLACEHOLDER_PARAM, LOOK_SETTINGS_PARAM, LOOK_TOKEN_COOKIE, LOOK_TOKEN_HEADER, NOT_PUBLISHED_CODES, PUBLISHING_DRAFT_HEADER, PUBLISHING_DRAFT_VAR, PUBLISH_ABORT_REASONS, PUBLISH_BLOCKED_ERROR, REVISION_CHANGED_ERROR, TRANSLATIONS_PENDING_ERROR, UNPLACED_BLOCK_ID, isContentWrite };
+export { ARTIFACT_FIELD_ATTRIBUTE, ARTIFACT_ITEM_ATTRIBUTE, CAMOX_ACTOR, CAMOX_NAME, CHECKS_RUNNING_ERROR, CONFLICTS_CHANGED_ERROR, DRAFT_CREATE_HEADER, DRAFT_ENDED_ERROR_CODE, DRAFT_HEADER, DRAFT_SEARCH_PARAM, FINDINGS_OPEN_ERROR, LIVE_READ_ONLY_ERROR, LOCALE_HEADER, LOOK_ARTIFACT_CAPTURE, LOOK_BLOCKS_PARAM, LOOK_BLOCK_DEFINITION_PARAM, LOOK_CONTENT_PARAM, LOOK_DOCUMENT_PATH, LOOK_LAYOUT_DEFINITION_PARAM, LOOK_LOCALE_PARAM, LOOK_PATH_PARAM, LOOK_PLACEHOLDER_HEIGHTS, LOOK_PLACEHOLDER_PARAM, LOOK_SETTINGS_PARAM, LOOK_TOKEN_COOKIE, LOOK_TOKEN_HEADER, NOT_PUBLISHED_CODES, PUBLISHING_DRAFT_HEADER, PUBLISHING_DRAFT_VAR, PUBLISH_ABORT_REASONS, PUBLISH_BLOCKED_ERROR, REVISION_CHANGED_ERROR, TRANSLATIONS_PENDING_ERROR, UNPLACED_BLOCK_ID, isContentWrite, lookArtifactSelector };

package/dist/router.d.ts

@@ -2279,8 +2279,8 @@ declare const schema: {
       }, {}, {
         length: number | undefined;
       }>;
-      overviewHeadline: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-        name: "overview_headline";
+      openingRequest: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+        name: "opening_request";
         tableName: "drafts";
         dataType: "string";
         columnType: "SQLiteText";
@@ -2298,8 +2298,8 @@ declare const schema: {
       }, {}, {
         length: number | undefined;
       }>;
-      overviewName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-        name: "overview_name";
+      overviewHeadline: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+        name: "overview_headline";
         tableName: "drafts";
         dataType: "string";
         columnType: "SQLiteText";
@@ -10324,7 +10324,10 @@ type DraftSummary = {
   createdAt: number;
   /** When the draft last stored a change, or null while it stores nothing. */
   lastChangedAt: number | null;
-  /** How many entities the draft changes: the length of its publish preview's changes. */
+  /**
+   * How many changes the draft has: the entities its publish preview lists, and its code as one
+   * more once the agent changed it, as publishing ships it.
+   */
   changeCount: number;
   /** The tags of the locales the draft has pending translations into (ADR 0015). */
   translatingLocales: string[];
@@ -10376,12 +10379,10 @@ type Overview =
 } |
 /**
  * Written. A `stale` one describes an older version of the draft's changes: it's still shown
- * while a new one is written. `name` is the short name AI suggests keeping the draft under,
- * null for an overview written before overviews had one.
+ * while a new one is written.
  */
 {
   status: "ready";
-  name: string | null;
   headline: string;
   bullets: string[];
   stale: boolean;
@@ -18126,7 +18127,6 @@ declare const router: {
       };
     }>, import("zod").ZodObject<{
       projectId: import("zod").ZodNumber;
-      name: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
     }, import("zod/v4/core").$strip>, import("@orpc/server").Schema<DraftSummary, DraftSummary>, Record<never, never>, Record<never, never>>;
     get: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<import("@orpc/server").MergedInitialContext<import("@orpc/server").MergedInitialContext<BaseContext & Record<never, never>, BaseContext, BaseContext>, import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>, import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>>, import("@orpc/server").MergedCurrentContext<import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>, {
       draft: DraftRequest | null;
@@ -18179,58 +18179,6 @@ declare const router: {
     }>, import("zod").ZodObject<{
       projectId: import("zod").ZodNumber;
     }, import("zod/v4/core").$strip>, import("@orpc/server").Schema<DraftSummary, DraftSummary>, Record<never, never>, Record<never, never>>;
-    rename: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<import("@orpc/server").MergedInitialContext<import("@orpc/server").MergedInitialContext<BaseContext & Record<never, never>, BaseContext, BaseContext>, import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>, import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>>, import("@orpc/server").MergedCurrentContext<import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>, {
-      draft: DraftRequest | null;
-      locale: string | undefined;
-      publishingDraft: string | undefined;
-      look: LookGrant | undefined;
-    }>, import("@orpc/server").MergedCurrentContext<import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>, {
-      draft: DraftRequest | null;
-      locale: string | undefined;
-      publishingDraft: string | undefined;
-      look: LookGrant | undefined;
-    }>>, import("@orpc/server").MergedCurrentContext<import("@orpc/server").MergedCurrentContext<import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>, {
-      draft: DraftRequest | null;
-      locale: string | undefined;
-      publishingDraft: string | undefined;
-      look: LookGrant | undefined;
-    }>, {
-      db: Database;
-      env: Bindings;
-      headers: Headers;
-      client: string;
-      telemetryDisabled: boolean;
-      waitUntil: (promise: Promise<unknown>) => void;
-      apiOrigin?: string;
-      draft: DraftRequest | null;
-      locale: string | undefined;
-      publishingDraft: string | undefined;
-      look: LookGrant | undefined;
-      user: {
-        id: string;
-        createdAt: Date;
-        updatedAt: Date;
-        email: string;
-        emailVerified: boolean;
-        name: string;
-        image?: string | null | undefined;
-      };
-      session: {
-        id: string;
-        createdAt: Date;
-        updatedAt: Date;
-        userId: string;
-        expiresAt: Date;
-        token: string;
-        ipAddress?: string | null | undefined;
-        userAgent?: string | null | undefined;
-        activeOrganizationId?: string | null | undefined;
-        studio?: boolean | null | undefined;
-      };
-    }>, import("zod").ZodObject<{
-      projectId: import("zod").ZodNumber;
-      name: import("zod").ZodNullable<import("zod").ZodString>;
-    }, import("zod/v4/core").$strip>, import("@orpc/server").Schema<DraftSummary, DraftSummary>, Record<never, never>, Record<never, never>>;
     previewPublish: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<import("@orpc/server").MergedInitialContext<import("@orpc/server").MergedInitialContext<BaseContext & Record<never, never>, BaseContext, BaseContext>, import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>, import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>>, import("@orpc/server").MergedCurrentContext<import("@orpc/server").MergedCurrentContext<BaseContext, Record<never, never>>, {
       draft: DraftRequest | null;
       locale: string | undefined;
@@ -18314,7 +18262,6 @@ declare const router: {
         status: "pending";
       } | {
         status: "ready";
-        name: string | null;
         headline: string;
         bullets: string[];
         stale: boolean;
@@ -18357,7 +18304,6 @@ declare const router: {
         status: "pending";
       } | {
         status: "ready";
-        name: string | null;
         headline: string;
         bullets: string[];
         stale: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.68.0",
+  "version": "0.71.0",
   "license": "MIT",
   "files": [
     "src",

package/src/drafts.ts

@@ -80,6 +80,64 @@ export type LookPlaceholderHeight = (typeof LOOK_PLACEHOLDER_HEIGHTS)[number];
  */
 export const UNPLACED_BLOCK_ID = "unplaced";
 
+/**
+ * The attributes the website's artifact frames carry: the artifact field's name, and the id of the
+ * Repeatable Item holding it, when an item's. With the block's `data-camox-viewport-block`, they
+ * find one artifact's frame (`lookArtifactSelector`).
+ */
+export const ARTIFACT_FIELD_ATTRIBUTE = "data-camox-artifact";
+export const ARTIFACT_ITEM_ATTRIBUTE = "data-camox-item";
+
+/** The CSS selector of the frame of an artifact field of a block, or of one of its items. */
+export const lookArtifactSelector = ({
+  block,
+  item,
+  field,
+}: {
+  block: string;
+  item?: string;
+  field: string;
+}) =>
+  `[data-camox-viewport-block="${block}"] iframe[${ARTIFACT_FIELD_ATTRIBUTE}="${field}"]` +
+  (item ? `[${ARTIFACT_ITEM_ATTRIBUTE}="${item}"]` : `:not([${ARTIFACT_ITEM_ATTRIBUTE}])`);
+
+/** An artifact's Timeline, as its runtime declares it: Marks by name, at times in ms. */
+export type LookTimeline = {
+  duration: number;
+  loop: boolean;
+  marks: Record<string, number>;
+  /** The Mark whose frame stands for the artifact, or null. */
+  poster: string | null;
+};
+
+/**
+ * One finding of an artifact's guardrail report, about motion that escapes its Timeline or will
+ * look broken: a Web Animation the runtime didn't make (a CSS animation, a CSS transition that no
+ * visitor triggered, one the source made itself), a live timer, a Track the runtime skipped
+ * because it can't play it, Tracks on one element and property that overlap, or a loop cut,
+ * where a looping Timeline's last frame differs from its first.
+ */
+export type LookGuardrailFinding = {
+  kind: "animation" | "timer" | "track" | "overlap" | "loop-cut";
+  /** What's wrong and what to do instead, for the Artifact Agent. */
+  text: string;
+};
+
+/**
+ * What the look document's artifact frames hold under `LOOK_ARTIFACT_CAPTURE`, for the browser
+ * `look` drives: the artifact's Timeline, null when it declares none; seeking it to `t` ms,
+ * resolved once the frame at that time painted, with the error `render` threw, if it did; and its
+ * guardrail report, empty when nothing escapes its Timeline. Frames of an SDK older than
+ * Timelines hold nothing there.
+ */
+export type LookArtifactCapture = {
+  timeline(): Promise<LookTimeline | null>;
+  seek(t: number): Promise<{ error?: string }>;
+  guardrail(): Promise<LookGuardrailFinding[]>;
+};
+
+export const LOOK_ARTIFACT_CAPTURE = "camoxCapture";
+
 /**
  * Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
  * exist yet. Its value is `"1"`.