@pixelhop/dit 0.3.0 → 0.4.0

package/README.md

@@ -116,11 +116,15 @@ dit upload --project marketing-site --review pr-1234 \
 
 `--review` takes either an existing `rev_…` id or your own reference — a PR number, a run
 id, anything stable. A reference that has been seen before reuses that review, so a job
-that runs twice on the same PR adds revisions instead of a second review. `--project`
+that runs twice on the same PR adds screens to the existing review. To update an existing
+screen, use `dit revision --artifact <id>` instead. `--project`
 takes the project slug or its `prj_…` id.
 
 Per-capture context, all optional: `--route /checkout`, `--viewport 390x844@3`,
-`--scenario "logged out"`, `--title`. Pass `--json` for the machine-readable form; the
+`--scenario "logged out"`, `--title`, `--description`, and `--group`. Give each screen a
+clear title and describe what the reviewer should check. These flags apply to every file
+in a command; use separate commands with the same `--round` key when titles, descriptions
+or viewports differ. Pass `--json` for the machine-readable form; the
 default prints the review URL and the Markdown block to paste into a PR.
 
 Images are sniffed by magic bytes (PNG, JPEG, WebP, GIF) and their dimensions read from
@@ -128,6 +132,42 @@ the file, so a mislabelled extension does not matter. For MP4 and WebM the CLI s
 to `ffprobe` for duration and dimensions, and to `ffmpeg` for a poster frame — both are
 optional. Without them the upload still succeeds, with a warning, minus the poster.
 
+### Design alternatives
+
+Use the same `--group` name within a review for alternatives to the same design. Upload
+options separately so each has its own title, description, artifact ID and revision history:
+
+```bash
+dit upload --project marketing-site --review pr-1234 --file checkout-a.png \
+  --title "Checkout — compact" --description "Shorter form with an inline order summary" \
+  --group "Checkout layout" --round checkout-options --summary "Two checkout layouts to compare"
+dit upload --project marketing-site --review pr-1234 --file checkout-b.png \
+  --title "Checkout — split" --description "Form and order summary side by side" \
+  --group "Checkout layout" --round checkout-options
+```
+
+Use `--json` to get artifact IDs and keep them for later `revision` commands. A variation group
+connects alternatives; a round groups a batch of changes. The human chooses the preferred
+option.
+
+### Review rounds
+
+Each upload or revision command creates one round; an upload includes all of its files. Use the same
+`--round` key on upload and revision commands to group one batch of changes:
+
+```sh
+dit revision --artifact art_123 --file overview.png --round polish-2 --summary "Tightened spacing and simplified the mobile header"
+dit upload --project my-app --review rev_123 --file mobile.png --round polish-2
+```
+
+Use a new key for the next batch. Historical round keys cannot be extended after a
+new round starts. The first declaration supplies the round's optional summary.
+Review rounds track evidence; screen titles, choices and feedback retain their
+current state. Older uploads are shown as an Earlier uploads baseline.
+Rounds let the reviewer step through the evidence timeline. Their Updated filter and
+Mark as seen state are personal: agents must not clear them or verify the review.
+After a feedback pass, reply, mark the relevant threads addressed, and return the review URL.
+
 ### `dit feedback`
 
 ```bash

package/dist/args.d.ts

@@ -16,7 +16,11 @@ export type CliArgs = ({
     review: string;
     files: string[];
 } & RuntimeFlags & JsonFlag & {
+    round?: string;
+    summary?: string;
     title?: string;
+    description?: string;
+    group?: string;
     commit?: string;
     branch?: string;
     route?: string;
@@ -38,6 +42,8 @@ export type CliArgs = ({
     command: "revision";
     artifact: string;
     file: string;
+    round?: string;
+    summary?: string;
 } & RuntimeFlags & JsonFlag) | ({
     command: "markdown";
     review: string;

package/dist/args.js

@@ -7,11 +7,15 @@ const runtimeOptions = {
 };
 const commandOptions = {
     upload: {
+        round: { type: "string" },
+        summary: { type: "string" },
         ...runtimeOptions,
         project: { type: "string" },
         review: { type: "string" },
         file: { type: "string", multiple: true },
         title: { type: "string" },
+        description: { type: "string" },
+        group: { type: "string" },
         commit: { type: "string" },
         branch: { type: "string" },
         route: { type: "string" },
@@ -36,6 +40,8 @@ const commandOptions = {
         message: { type: "string" },
     },
     revision: {
+        round: { type: "string" },
+        summary: { type: "string" },
         ...runtimeOptions,
         artifact: { type: "string" },
         file: { type: "string" },
@@ -98,7 +104,11 @@ export function parseCliArgs(argv) {
             project: required(values, "project", name),
             review: required(values, "review", name),
             files,
+            ...optional(values, "round"),
+            ...optional(values, "summary"),
             ...optional(values, "title"),
+            ...optional(values, "description"),
+            ...optional(values, "group"),
             ...optional(values, "commit"),
             ...optional(values, "branch"),
             ...optional(values, "route"),
@@ -156,6 +166,8 @@ export function parseCliArgs(argv) {
             command: name,
             artifact: required(values, "artifact", name),
             file: required(values, "file", name),
+            ...optional(values, "round"),
+            ...optional(values, "summary"),
             ...(values.json ? { json: true } : {}),
             ...runtime,
         };

package/dist/index.js

@@ -22,7 +22,7 @@ Commands:
   feedback  --review <ref|id> [--status open|addressed|resolved|all] [--json]
   reply     --thread <id> --message <text>
   address   --thread <id> [--message <text>]
-  revision  --artifact <id> --file <path> [--json]
+  revision  --artifact <id> --file <path> [--round <key>] [--summary <text>] [--json]
   markdown  --review <ref|id>
   project create --name <name> [--json]
 
@@ -35,6 +35,19 @@ Global options:
 Upload options:
   --title <text> --commit <sha> --branch <name> --route <path>
   --viewport <WIDTHxHEIGHT[@SCALE]> --scenario <name> --json
+  --description <text> --group <name>  Context and alternatives for the same design
+  --round <key> --summary <text>  Group uploads into a review round with a change summary
+
+Review workflow:
+  Give screens a clear --title and --description. Upload flags apply to every file.
+  Alternatives: upload each option with a distinct title and the same --group name.
+  Existing screen: use revision --artifact <id> to retain its history and notes.
+  One feedback pass: share a --round key across upload and revision commands.
+  Use a new key for the next pass; older rounds cannot be extended once a new one starts.
+  The first command sets --summary. Without --round, each command creates a round.
+  Reuse --review for the same PR; upload adds screens, revision updates a screen.
+  Read feedback --json, fix, upload revisions, reply, then address the threads.
+  Humans choose preferred designs, mark updates as seen, and verify reviews.
 `;
 async function main() {
     const args = parseCliArgs(process.argv.slice(2));

package/dist/operations.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { getCatalog, resolveProject, resolveReview } from "./catalog.js";
 import { ApiError } from "./errors.js";
 import { prepareMedia } from "./media.js";
@@ -62,6 +63,7 @@ async function upload(args, client, output) {
             },
         });
     }
+    const roundKey = args.round ?? randomUUID();
     const completions = [];
     for (const file of args.files) {
         const prepared = await prepareMedia(file, output.warn);
@@ -69,9 +71,13 @@ async function upload(args, client, output) {
             completions.push(await declareUploadComplete(client, prepared, {
                 path: "/v1/artifacts/uploads",
                 declaration: {
+                    roundKey,
+                    ...(args.summary ? { roundSummary: args.summary } : {}),
                     reviewId: reviewPayload.review.id,
                     kind: prepared.kind,
                     title: args.title ?? stripExtension(prepared.name),
+                    ...(args.description ? { description: args.description } : {}),
+                    ...(args.group ? { variationGroup: args.group } : {}),
                     ...(args.route ? { route: args.route } : {}),
                     ...(args.viewport ? { viewport: args.viewport } : {}),
                     ...(args.commit ? { commit: args.commit } : {}),
@@ -100,7 +106,10 @@ async function revision(args, client, output) {
     try {
         const completion = await declareUploadComplete(client, prepared, {
             path: `/v1/artifacts/${encodeURIComponent(args.artifact)}/revisions`,
-            declaration: {},
+            declaration: {
+                roundKey: args.round ?? randomUUID(),
+                ...(args.summary ? { roundSummary: args.summary } : {}),
+            },
         });
         if (args.json) {
             output.out(printJson(completion));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelhop/dit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Did It Though? CLI for coding agents — upload PR screenshots and videos, pull structured feedback back",
   "keywords": [
     "agents",