@cueloop/schema 0.1.0-alpha.45 → 0.1.0-alpha.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.45",
+  "version": "0.1.0-alpha.47",
   "description": "The ReviewSession primitive: types, markdown block model, quote-primary anchors, feedback serialization",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {

package/src/feedback.test.ts

@@ -34,7 +34,7 @@ describe("renderFeedback", () => {
       artifactContent: PLAN,
       workingCopy: PLAN.replace("one JSON document", "one JSON record"),
       annotations: [],
-      planPath: "docs/plan.md",
+      artifactPath: "docs/plan.md",
     });
 
     // Assert
@@ -200,4 +200,27 @@ describe("renderFeedback", () => {
     // Assert
     expect(feedback).toContain("(§ Persistence)");
   });
+
+  test("a prototype annotation locates by its selector and is never orphan-flagged", () => {
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactType: "prototype",
+      artifactContent: "<main><div class='card'>Pricing</div></main>",
+      annotations: [
+        makeAnnotation({
+          body: "Tighten the padding.",
+          anchor: { quote: "Pricing", prefix: "", suffix: "", selector: "main > div.card" },
+        }),
+      ],
+      artifactPath: "proto.html",
+    });
+
+    // Assert
+    expect(feedback).toContain("(main > div.card)");
+    expect(feedback).toContain("Tighten the padding.");
+    expect(feedback).toContain("by its CSS selector");
+    expect(feedback).not.toContain("orphaned anchor");
+  });
 });

package/src/feedback.ts

@@ -28,8 +28,8 @@ export interface FeedbackInput {
   /** Artifact kind; defaults to "plan". A diff working copy is already a patch. */
   artifactType?: ArtifactType;
   annotations: Annotation[];
-  /** Path the agent knows the plan by, for direct reference. */
-  planPath?: string;
+  /** Path the agent knows the artifact by (plan or prototype), for direct reference. */
+  artifactPath?: string;
   /** Session id, so the document can teach the addressed-ids resubmit call. */
   sessionId?: string;
 }
@@ -37,7 +37,7 @@ export interface FeedbackInput {
 const quoteLines = (text: string) => "> " + text.replace(/\n/g, "\n> ");
 
 export function renderFeedback(input: FeedbackInput): string {
-  const path = input.planPath ?? "plan.md";
+  const path = input.artifactPath ?? "plan.md";
   // agent notes are the submitter's own context - never echoed back as
   // feedback - and annotations a previous revision already addressed stay out
   // of the next document, so the agent only ever sees the open items
@@ -45,6 +45,7 @@ export function renderFeedback(input: FeedbackInput): string {
     (annotation) => !isAgentNote(annotation) && !isAddressed(annotation),
   );
   const isDiff = input.artifactType === "diff";
+  const isPrototype = input.artifactType === "prototype";
   // A diff's annotations anchor to the submitted patch rows; resolve against it,
   // not the curated working copy (which may drop the rejected rows).
   const blocks = parseBlocks(
@@ -98,14 +99,22 @@ export function renderFeedback(input: FeedbackInput): string {
   if (annotations.length) {
     lines.push(`## Annotations (${annotations.length})`);
     lines.push("");
-    lines.push(`Address every item. Locate each one in ${path} by its quoted text.`);
+    lines.push(
+      isPrototype
+        ? `Address every item. Locate each one in ${path} by its CSS selector.`
+        : `Address every item. Locate each one in ${path} by its quoted text.`,
+    );
     lines.push("");
     annotations.forEach((annotation, annotationIndex) => {
-      const resolved = resolveAnchor(annotation.anchor, blocks);
+      // a prototype selector anchor is never resolved or orphaned against blocks
+      const selector = annotation.anchor.selector;
+      const resolved = selector ? null : resolveAnchor(annotation.anchor, blocks);
       const sectionTitle = resolved ? sectionOf(blocks, resolved.blockIndex) : "";
-      const location = sectionTitle ? ` (§ ${sectionTitle})` : "";
+      const location = selector ? ` (${selector})` : sectionTitle ? ` (§ ${sectionTitle})` : "";
       const orphanFlag =
-        resolved === null ? " [orphaned anchor: the quoted text is no longer present]" : "";
+        !selector && resolved === null
+          ? " [orphaned anchor: the quoted text is no longer present]"
+          : "";
       lines.push(
         `### ${annotationIndex + 1}. ${capitalize(annotation.kind)}${location}${orphanFlag}`,
       );
@@ -151,7 +160,7 @@ export function feedbackForSession(
     workingCopy: session.workingCopy,
     artifactType: session.artifact.type,
     annotations: session.annotations,
-    planPath: session.artifact.meta.planPath,
+    artifactPath: session.artifact.meta.prototypePath ?? session.artifact.meta.planPath,
     sessionId: session.id,
   });
 }

package/src/types.ts

@@ -12,7 +12,7 @@ export interface WorkspaceKey {
   branch: string;
 }
 
-export type ArtifactType = "plan" | "diff";
+export type ArtifactType = "plan" | "diff" | "prototype";
 
 export interface ArtifactMeta {
   cwd?: string;
@@ -21,6 +21,8 @@ export interface ArtifactMeta {
   agentSessionId?: string;
   /** Path to the plan file on disk, so feedback can reference it. */
   planPath?: string;
+  /** Path to the prototype's entry HTML file on disk. */
+  prototypePath?: string;
   /** Pull request reference the diff came from, so the verdict can be posted back. */
   pr?: string;
   /** herdr pane the submitting agent runs in - the review returns focus there. */
@@ -67,6 +69,8 @@ export interface Anchor {
   /** Character offsets within that block's text (hint). */
   start?: number;
   end?: number;
+  /** Prototype anchors: the CSS selector of the annotated element (authority). */
+  selector?: string;
 }
 
 /** The annotation kind set is open; these are the built-ins. */