@popoverai/dotrequirements 0.39.5 → 0.40.0

package/dist/commands/solution/ask.js

@@ -1,8 +1,10 @@
 import { api } from "../../convex.js";
 import { solutionClient } from "./client.js";
+import { readImage } from "./image.js";
 import { pushBeforeRecord } from "./pushing.js";
 import { readRequest } from "./request.js";
 import { onOutcome, requireWhere } from "./run-file.js";
+import { uploadToApp } from "./upload.js";
 /**
  * `dotreq solution ask <request-file>`: the drafter or a reviewer puts a
  * decision to the owner, on the outcome it is at or the one `--outcome`
@@ -14,22 +16,54 @@ export async function askCommand(file, options) {
     if ((file === undefined) === (options.approvalRequest === undefined)) {
         throw new Error("Ask with a request file, or with --approval-request '<action>' alone: one of them.");
     }
-    const asking = file !== undefined
-        ? { request: readRequest(file) }
-        : { approvalRequest: actionFrom(options.approvalRequest ?? "") };
+    // DIRECTION-1.1: a picture that can't be shown is refused before anything happens.
+    const request = file !== undefined ? readRequest(file) : undefined;
+    const pictures = request !== undefined ? picturesIn(request) : [];
+    const approvalRequest = file === undefined ? actionFrom(options.approvalRequest ?? "") : undefined;
     const where = requireWhere(options);
     const { solutionId, agent } = where;
     const client = solutionClient();
     // SOLBRANCH-3.0: the drafter's commits reach the branch before Quinn is asked.
     await pushBeforeRecord(client, where);
+    for (const { written, image } of pictures) {
+        const storageId = await uploadToApp(client, api.solutions.images.uploadUrl, { solutionId }, image, "so nothing was put to the owner. Ask again.");
+        // The file becomes the copy the app keeps (`pictureSchema`).
+        delete written.file;
+        Object.assign(written, { storageId, name: image.name });
+    }
     const decision = await client.mutation(api.solutions.mutations.ask, {
         solutionId,
         agent,
         ...(where.outcome ? { outcome: where.outcome } : {}),
-        ...asking,
+        ...(request !== undefined ? { request } : { approvalRequest }),
     });
     console.log(`Asked${onOutcome(where.outcome)}. It waits on the owner's decision${decision ? ` (${decision})` : ""}.`);
 }
+/**
+ * The pictures on a request's options, each read from its file: a request
+ * whose picture isn't there, or isn't an image a browser can show, goes no
+ * further (DIRECTION-1.1). Anything else about the request is the backend's
+ * to check against the contract.
+ */
+function picturesIn(request) {
+    const options = request?.options;
+    if (!Array.isArray(options))
+        return [];
+    return options.flatMap((option) => {
+        const pictures = option?.pictures;
+        if (!Array.isArray(pictures))
+            return [];
+        return pictures.map((written) => {
+            if (typeof written?.file !== "string") {
+                throw new Error('A picture on an option names its image with "file", so nothing was put to the owner.');
+            }
+            return {
+                written,
+                image: readImage(written.file, "nothing was put to the owner"),
+            };
+        });
+    });
+}
 /** The action `--approval-request` names, as JSON. The backend checks it. */
 function actionFrom(text) {
     try {

package/dist/commands/solution/brief.d.ts

@@ -22,6 +22,12 @@ export type Brief = {
     text: string;
     reviewing?: BriefOutcome[];
     against?: BriefOutcome[];
+    /** As far as the CLI reads it: the pictures a decision was decided on (DIRECTION-6.4.0, 6.5). */
+    thread?: Array<{
+        pictures?: Array<{
+            storageId: string;
+        }>;
+    }>;
 };
 /** An outcome the brief lists, as far as the CLI reads it. */
 export type BriefOutcome = {

package/dist/commands/solution/contract.d.ts

@@ -5,5 +5,5 @@
  * request is validated against; the CLI can't import the backend, so this
  * is that text, and a test keeps the two the same.
  */
-export declare const REQUEST_CONTRACT = "Ask the person to decide something about the outcome you are drafting or reviewing. A choice presents options with a recommendation. The person may answer in their own words instead of picking an option, and their words are then the decision you work from. One decision per request: if two things need deciding, ask twice.\n\nA request is JSON with a \"kind\" and the fields of that kind:\n\nchoice:\n  question (text, up to 200 characters): The question, phrased as a question in the words the person will read it, not as a topic.\n  options (list, at least 2): The live alternatives. More than four makes deciding harder; give more only when each is a genuine choice. Leave out anything you have already ruled out.\n    name (text, up to 200 characters): The option as you would say it to the person: a noun phrase they can repeat back, not a label.\n    benefits (list of text, each up to 200 characters): What is better if this option is taken. One line each, in your own words.\n    costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.\n    note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.\n    action (object, optional): An action you may take only with the person's permission, which choosing this option gives. Once they choose it, take it with `dotreq solution approval complete <decision>`. Leave it out for anything you may do yourself.\n      tool (text, up to 200 characters): The action, by name. Those that need the person's permission: \"fix\", starting a fix, and \"make with you\", making the outcome you're on with the person and the solution's agent instead (args: { outcome }), when it needs their judgement more than your best guess (CONVO-8).\n      args (object): The action's arguments, as it takes them: a fix's are below.\n  recommendation (object): Which option you would take, and the one reason why.\n    option (text, up to 200 characters): The name of the option you recommend, exactly as it appears in options.\n    because (text, up to 200 characters): The one reason that carries it, in one line. The full reasoning belongs in background.\n  background (text, up to 4000 characters): What the person needs to know to decide well that the options do not already say. Include only context that would substantially change the quality of the decision. The person reads this after the options, so do not reiterate them.\n\nThe args of a \"fix\" action:\n  name (text, up to 120 characters): A short name for the fix, from what it puts right, as \"dice below the controls\".\n  words (text, up to 2000 characters): What you found, in your own words.\n  plan (text, up to 2000 characters): The fix as you would put it to the person, in a sentence or two.\n  redo (list, at least 1): The outcomes the fix redoes, and what would change in each.\n    outcome (text, up to 200 characters): An outcome to redo, by its name.\n    change (text, up to 2000 characters): What would change in it.\n  rerun (list of text, each up to 200 characters): The outcomes that await the ones redone and should run again from them. Empty when none should.";
+export declare const REQUEST_CONTRACT = "Ask the person to decide something about the outcome you are drafting or reviewing. A choice presents options with a recommendation. The person may answer in their own words instead of picking an option, and their words are then the decision you work from. One decision per request: if two things need deciding, ask twice.\n\nA request is JSON with a \"kind\" and the fields of that kind:\n\nchoice:\n  question (text, up to 200 characters): The question, phrased as a question in the words the person will read it, not as a topic.\n  options (list, at least 2): The live alternatives. More than four makes deciding harder; give more only when each is a genuine choice. Leave out anything you have already ruled out.\n    name (text, up to 200 characters): The option as you would say it to the person: a noun phrase they can repeat back, not a label.\n    benefits (list of text, each up to 200 characters): What is better if this option is taken. One line each, in your own words.\n    costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.\n    note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.\n    pictures (list, optional): Pictures of this option, when the choice is about how something looks. The person flips between options to compare them, so give each option the same screens, in the same order, at the same window size. Leave it out of a choice that isn't about how something looks.\n      file (text, up to 200 characters): The image's path, from where you run `dotreq solution ask`: a PNG, JPEG, GIF, WebP or AVIF file. Its file name must be one no other image in the solution has, so name it for the option and the screen.\n      caption (text, up to 200 characters, optional): What this picture shows, the same on each option, as \"With work waiting on you\". Leave it out when there is one picture and nothing to say.\n    action (object, optional): An action you may take only with the person's permission, which choosing this option gives. Once they choose it, take it with `dotreq solution approval complete <decision>`. Leave it out for anything you may do yourself.\n      tool (text, up to 200 characters): The action, by name. Those that need the person's permission: \"fix\", starting a fix, and \"make with you\", making the outcome you're on with the person and the solution's agent instead (args: { outcome }), when it needs their judgement more than your best guess (CONVO-8).\n      args (object): The action's arguments, as it takes them: a fix's are below.\n  recommendation (object): Which option you would take, and the one reason why.\n    option (text, up to 200 characters): The name of the option you recommend, exactly as it appears in options.\n    because (text, up to 200 characters): The one reason that carries it, in one line. The full reasoning belongs in background.\n  background (text, up to 4000 characters): What the person needs to know to decide well that the options do not already say. Include only context that would substantially change the quality of the decision. The person reads this after the options, so do not reiterate them.\n\nThe args of a \"fix\" action:\n  name (text, up to 120 characters): A short name for the fix, from what it puts right, as \"dice below the controls\".\n  words (text, up to 2000 characters): What you found, in your own words.\n  plan (text, up to 2000 characters): The fix as you would put it to the person, in a sentence or two.\n  redo (list, at least 1): The outcomes the fix redoes, and what would change in each.\n    outcome (text, up to 200 characters): An outcome to redo, by its name.\n    change (text, up to 2000 characters): What would change in it.\n  rerun (list of text, each up to 200 characters): The outcomes that await the ones redone and should run again from them. Empty when none should.";
 //# sourceMappingURL=contract.d.ts.map

package/dist/commands/solution/contract.js

@@ -16,6 +16,9 @@ choice:
     benefits (list of text, each up to 200 characters): What is better if this option is taken. One line each, in your own words.
     costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.
     note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.
+    pictures (list, optional): Pictures of this option, when the choice is about how something looks. The person flips between options to compare them, so give each option the same screens, in the same order, at the same window size. Leave it out of a choice that isn't about how something looks.
+      file (text, up to 200 characters): The image's path, from where you run \`dotreq solution ask\`: a PNG, JPEG, GIF, WebP or AVIF file. Its file name must be one no other image in the solution has, so name it for the option and the screen.
+      caption (text, up to 200 characters, optional): What this picture shows, the same on each option, as "With work waiting on you". Leave it out when there is one picture and nothing to say.
     action (object, optional): An action you may take only with the person's permission, which choosing this option gives. Once they choose it, take it with \`dotreq solution approval complete <decision>\`. Leave it out for anything you may do yourself.
       tool (text, up to 200 characters): The action, by name. Those that need the person's permission: "fix", starting a fix, and "make with you", making the outcome you're on with the person and the solution's agent instead (args: { outcome }), when it needs their judgement more than your best guess (CONVO-8).
       args (object): The action's arguments, as it takes them: a fix's are below.

package/dist/commands/solution/image.d.ts

@@ -1,26 +1,12 @@
+import { ACCEPTED_IMAGE_FORMATS, type ImageContentType, type ImageFormat, imageFormat } from "../../schema/image-format.js";
 import type { solutionClient } from "./client.js";
 /**
  * Images on an outcome (SIGHT-9), such as a screenshot: the drafter submits an
  * image file from its checkout or anywhere it can read, and the app keeps a
- * copy; nothing is committed.
- *
- * Every browser we support (Chrome, Edge, Firefox, Safari on macOS and iOS)
- * shows PNG, JPEG, GIF, WebP and AVIF (MDN's image type guide; AVIF from
- * Safari 16.4). HEIC and TIFF show only in Safari, and JPEG XL not in Edge,
- * so they are refused. SVG is refused too: opened at full size in its own
- * tab, an SVG runs whatever script it carries. The format is read from the
- * file's first bytes (the WHATWG MIME Sniffing signatures; AVIF's brand in
- * its `ftyp` box), since an extension says nothing about it. Kept in step
- * with the backend's `ACCEPTED_IMAGE_FORMATS` (convex/solutions/images.ts).
+ * copy; nothing is committed. Which files are images a browser can show is
+ * `schema/image-format.ts`.
  */
-export declare const ACCEPTED_IMAGE_FORMATS = "a PNG, JPEG, GIF, WebP or AVIF image";
-export type ImageContentType = "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "image/avif";
-/** What the file is: a format a browser shows, or why it isn't one. */
-export type ImageFormat = {
-    contentType: ImageContentType;
-} | {
-    refused: string;
-};
+export { ACCEPTED_IMAGE_FORMATS, type ImageContentType, type ImageFormat, imageFormat, };
 /** An image read from the checkout, ready to upload. */
 export type Image = {
     name: string;
@@ -32,8 +18,6 @@ export type Image = {
  * (SIGHT-9.0.0) and what came of it: by default, that nothing was submitted.
  */
 export declare function readImage(path: string, outcome?: string): Image;
-/** What image format the bytes hold, read from the file's signature. */
-export declare function imageFormat(bytes: Uint8Array): ImageFormat;
 /**
  * Where an image's copy is saved in the checkout, relative to the
  * repository's root (SIGHT-9.3): a folder git ignores, then one folder per
@@ -59,5 +43,4 @@ type BriefOutcome = {
 export declare function saveImageCopies(client: ReturnType<typeof solutionClient>, solutionId: string, outcomes: readonly BriefOutcome[], cwd?: string): Promise<void>;
 /** Upload an image to the app (SIGHT-9.0), and the stored copy's id back. */
 export declare function uploadImage(client: ReturnType<typeof solutionClient>, solutionId: string, image: Image): Promise<string>;
-export {};
 //# sourceMappingURL=image.d.ts.map

package/dist/commands/solution/image.js

@@ -1,23 +1,16 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { api } from "../../convex.js";
+import { ACCEPTED_IMAGE_FORMATS, imageFormat, } from "../../schema/image-format.js";
 import { repositoryRoot } from "./branch.js";
 import { uploadToApp } from "./upload.js";
 /**
  * Images on an outcome (SIGHT-9), such as a screenshot: the drafter submits an
  * image file from its checkout or anywhere it can read, and the app keeps a
- * copy; nothing is committed.
- *
- * Every browser we support (Chrome, Edge, Firefox, Safari on macOS and iOS)
- * shows PNG, JPEG, GIF, WebP and AVIF (MDN's image type guide; AVIF from
- * Safari 16.4). HEIC and TIFF show only in Safari, and JPEG XL not in Edge,
- * so they are refused. SVG is refused too: opened at full size in its own
- * tab, an SVG runs whatever script it carries. The format is read from the
- * file's first bytes (the WHATWG MIME Sniffing signatures; AVIF's brand in
- * its `ftyp` box), since an extension says nothing about it. Kept in step
- * with the backend's `ACCEPTED_IMAGE_FORMATS` (convex/solutions/images.ts).
+ * copy; nothing is committed. Which files are images a browser can show is
+ * `schema/image-format.ts`.
  */
-export const ACCEPTED_IMAGE_FORMATS = "a PNG, JPEG, GIF, WebP or AVIF image";
+export { ACCEPTED_IMAGE_FORMATS, imageFormat, };
 /**
  * The image at a path, or a refusal naming the accepted formats
  * (SIGHT-9.0.0) and what came of it: by default, that nothing was submitted.
@@ -34,65 +27,6 @@ export function readImage(path, outcome = "nothing was submitted") {
     }
     return { name: basename(full), contentType: format.contentType, bytes };
 }
-const AVIF_BRANDS = new Set(["avif", "avis"]);
-const HEIF_BRANDS = new Set(["heic", "heix", "heim", "heis", "hevc", "hevx"]);
-/** What image format the bytes hold, read from the file's signature. */
-export function imageFormat(bytes) {
-    const starts = (...signature) => signature.every((byte, at) => bytes[at] === byte);
-    if (starts(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)) {
-        return { contentType: "image/png" };
-    }
-    if (starts(0xff, 0xd8, 0xff))
-        return { contentType: "image/jpeg" };
-    if (ascii(bytes, 0, 6) === "GIF87a" || ascii(bytes, 0, 6) === "GIF89a") {
-        return { contentType: "image/gif" };
-    }
-    if (ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 6) === "WEBPVP") {
-        return { contentType: "image/webp" };
-    }
-    if (ascii(bytes, 4, 4) === "ftyp") {
-        // ISO-BMFF: the major brand, then compatible brands to the box's end.
-        // AVIF lists avif or avis; HEIC shares the box and lists its own.
-        const size = readUint32(bytes, 0);
-        const end = Math.min(bytes.length, size);
-        const brands = [ascii(bytes, 8, 4)];
-        for (let at = 16; at + 4 <= end; at += 4)
-            brands.push(ascii(bytes, at, 4));
-        if (brands.some((brand) => AVIF_BRANDS.has(brand))) {
-            return { contentType: "image/avif" };
-        }
-        if (brands.some((brand) => HEIF_BRANDS.has(brand))) {
-            return { refused: "it is a HEIC image, which only Safari shows" };
-        }
-        return { refused: "it isn't an image file" };
-    }
-    if (starts(0x49, 0x49, 0x2a, 0x00) || starts(0x4d, 0x4d, 0x00, 0x2a)) {
-        return { refused: "it is a TIFF image, which only Safari shows" };
-    }
-    if (/^\s*(<\?xml[^>]*>\s*)?(<!--[\s\S]*?-->\s*)*<svg[\s>]/i.test(head(bytes))) {
-        return {
-            refused: "it is an SVG, which runs its scripts when opened at full size",
-        };
-    }
-    return { refused: "it isn't an image file" };
-}
-function ascii(bytes, at, length) {
-    return at + length <= bytes.length
-        ? String.fromCharCode(...bytes.subarray(at, at + length))
-        : "";
-}
-function readUint32(bytes, at) {
-    let value = 0;
-    for (let i = 0; i < 4; i++)
-        value = value * 256 + (bytes[at + i] ?? 0);
-    return value;
-}
-/** The file's start as text, for telling an SVG by its root element. */
-function head(bytes) {
-    return new TextDecoder("utf-8", { fatal: false })
-        .decode(bytes.subarray(0, 1024))
-        .replace(/^/, "");
-}
 /**
  * Where an image's copy is saved in the checkout, relative to the
  * repository's root (SIGHT-9.3): a folder git ignores, then one folder per

package/dist/commands/solution/index.js

@@ -119,6 +119,13 @@ would fix it. Say exactly what has to change:
 
   dotreq solution stall "<what has to change>"
 
+Open it on one sentence that stands on its own and says what is needed and
+from whom: the owner, written "from you"; a teammate, by name; or a fix to the
+product. The owner sees that sentence first, wherever the stall shows, and
+opens the rest. For example:
+
+  Needs a way past Vercel's login on previews, from you.
+
 The outcome waits until that is fixed and you are started again.
 `;
 /** The command as the Stop hook prints it, after the request contract on `ask --help`. */

package/dist/commands/solution/next.js

@@ -43,6 +43,13 @@ export async function nextCommand(options) {
     await saveImageCopies(client, solutionId, [
         ...(result.reviewing ?? []),
         ...(result.against ?? []),
+        // DIRECTION-6.4.0, 6.5: the pictures a decision on it was decided on.
+        {
+            things: (result.thread ?? []).flatMap((entry) => (entry.pictures ?? []).map(({ storageId }) => ({
+                kind: "image",
+                storageId,
+            }))),
+        },
     ]);
 }
 //# sourceMappingURL=next.js.map

package/dist/schema/browser.d.ts

@@ -6,6 +6,7 @@
 export { buildRequirementMarkdown, buildRequirementsMarkdown, DEFAULT_DELIMITER, } from "./builder.js";
 export type { ConvexRequirement } from "./conversions.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
+export { imageFormat } from "./image-format.js";
 export { DELIMITER_PATTERN, type ExtractedRequirementBlock, extractFrontmatterBlock, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, ROOT_LABEL_MARKER, splitRequirementFenceContent, stripFrontmatterBlock, } from "./parser-core.js";
 export { carriesBranchVersion } from "./provenance.js";
 export type { Metadata, ParsedCriterion, RequirementKey, RequirementNode, RequirementPrefix, RequirementsFile, } from "./schemas.js";

package/dist/schema/browser.js

@@ -6,6 +6,9 @@
 // Building (uses yaml package - browser-safe)
 export { buildRequirementMarkdown, buildRequirementsMarkdown, DEFAULT_DELIMITER, } from "./builder.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
+// What format an image's bytes hold, for a picture the web app's runner reads
+// from a sandbox (DIRECTION-5.2) as the CLI reads one from a checkout
+export { imageFormat } from "./image-format.js";
 // Parser core (pure TypeScript - browser-safe, no fs dependency)
 // These functions parse markdown strings directly without file I/O
 export { DELIMITER_PATTERN, 

package/dist/schema/image-format.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What image format a file's bytes hold (SIGHT-9), read from its signature.
+ *
+ * Every browser we support (Chrome, Edge, Firefox, Safari on macOS and iOS)
+ * shows PNG, JPEG, GIF, WebP and AVIF (MDN's image type guide; AVIF from
+ * Safari 16.4). HEIC and TIFF show only in Safari, and JPEG XL not in Edge,
+ * so they are refused. SVG is refused too: opened at full size in its own
+ * tab, an SVG runs whatever script it carries. The format is read from the
+ * file's first bytes (the WHATWG MIME Sniffing signatures; AVIF's brand in
+ * its `ftyp` box), since an extension says nothing about it. Kept in step
+ * with the backend's `ACCEPTED_IMAGE_FORMATS` (convex/solutions/images.ts).
+ *
+ * Browser-safe, since the web app's runner reads a picture the same way
+ * (DIRECTION-5.2).
+ */
+export declare const ACCEPTED_IMAGE_FORMATS = "a PNG, JPEG, GIF, WebP or AVIF image";
+export type ImageContentType = "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "image/avif";
+/** What the file is: a format a browser shows, or why it isn't one. */
+export type ImageFormat = {
+    contentType: ImageContentType;
+} | {
+    refused: string;
+};
+/** What image format the bytes hold, read from the file's signature. */
+export declare function imageFormat(bytes: Uint8Array): ImageFormat;
+//# sourceMappingURL=image-format.d.ts.map

package/dist/schema/image-format.js

@@ -0,0 +1,76 @@
+/**
+ * What image format a file's bytes hold (SIGHT-9), read from its signature.
+ *
+ * Every browser we support (Chrome, Edge, Firefox, Safari on macOS and iOS)
+ * shows PNG, JPEG, GIF, WebP and AVIF (MDN's image type guide; AVIF from
+ * Safari 16.4). HEIC and TIFF show only in Safari, and JPEG XL not in Edge,
+ * so they are refused. SVG is refused too: opened at full size in its own
+ * tab, an SVG runs whatever script it carries. The format is read from the
+ * file's first bytes (the WHATWG MIME Sniffing signatures; AVIF's brand in
+ * its `ftyp` box), since an extension says nothing about it. Kept in step
+ * with the backend's `ACCEPTED_IMAGE_FORMATS` (convex/solutions/images.ts).
+ *
+ * Browser-safe, since the web app's runner reads a picture the same way
+ * (DIRECTION-5.2).
+ */
+export const ACCEPTED_IMAGE_FORMATS = "a PNG, JPEG, GIF, WebP or AVIF image";
+const AVIF_BRANDS = new Set(["avif", "avis"]);
+const HEIF_BRANDS = new Set(["heic", "heix", "heim", "heis", "hevc", "hevx"]);
+/** What image format the bytes hold, read from the file's signature. */
+export function imageFormat(bytes) {
+    const starts = (...signature) => signature.every((byte, at) => bytes[at] === byte);
+    if (starts(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)) {
+        return { contentType: "image/png" };
+    }
+    if (starts(0xff, 0xd8, 0xff))
+        return { contentType: "image/jpeg" };
+    if (ascii(bytes, 0, 6) === "GIF87a" || ascii(bytes, 0, 6) === "GIF89a") {
+        return { contentType: "image/gif" };
+    }
+    if (ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 6) === "WEBPVP") {
+        return { contentType: "image/webp" };
+    }
+    if (ascii(bytes, 4, 4) === "ftyp") {
+        // ISO-BMFF: the major brand, then compatible brands to the box's end.
+        // AVIF lists avif or avis; HEIC shares the box and lists its own.
+        const size = readUint32(bytes, 0);
+        const end = Math.min(bytes.length, size);
+        const brands = [ascii(bytes, 8, 4)];
+        for (let at = 16; at + 4 <= end; at += 4)
+            brands.push(ascii(bytes, at, 4));
+        if (brands.some((brand) => AVIF_BRANDS.has(brand))) {
+            return { contentType: "image/avif" };
+        }
+        if (brands.some((brand) => HEIF_BRANDS.has(brand))) {
+            return { refused: "it is a HEIC image, which only Safari shows" };
+        }
+        return { refused: "it isn't an image file" };
+    }
+    if (starts(0x49, 0x49, 0x2a, 0x00) || starts(0x4d, 0x4d, 0x00, 0x2a)) {
+        return { refused: "it is a TIFF image, which only Safari shows" };
+    }
+    if (/^\s*(<\?xml[^>]*>\s*)?(<!--[\s\S]*?-->\s*)*<svg[\s>]/i.test(head(bytes))) {
+        return {
+            refused: "it is an SVG, which runs its scripts when opened at full size",
+        };
+    }
+    return { refused: "it isn't an image file" };
+}
+function ascii(bytes, at, length) {
+    return at + length <= bytes.length
+        ? String.fromCharCode(...bytes.subarray(at, at + length))
+        : "";
+}
+function readUint32(bytes, at) {
+    let value = 0;
+    for (let i = 0; i < 4; i++)
+        value = value * 256 + (bytes[at + i] ?? 0);
+    return value;
+}
+/** The file's start as text, for telling an SVG by its root element. */
+function head(bytes) {
+    return new TextDecoder("utf-8", { fatal: false })
+        .decode(bytes.subarray(0, 1024))
+        .replace(/^/, "");
+}
+//# sourceMappingURL=image-format.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.39.5",
+  "version": "0.40.0",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {