@yagejs-tools/feedback 0.0.0-stage → 0.1.0

package/dist/server.js

@@ -0,0 +1,735 @@
+// src/server/http/server.ts
+import { createServer } from "http";
+
+// src/shared/protocol.ts
+var validId = (id) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id);
+function copyJson(value) {
+  const seen = /* @__PURE__ */ new Set();
+  function visit(item) {
+    if (item === null || typeof item === "string" || typeof item === "boolean")
+      return item;
+    if (typeof item === "number" && Number.isFinite(item)) return item;
+    if (typeof item !== "object" || seen.has(item))
+      throw new Error(
+        "Feedback context must contain finite, acyclic JSON values."
+      );
+    seen.add(item);
+    let result;
+    if (Array.isArray(item)) result = item.map(visit);
+    else {
+      if (Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null)
+        throw new Error("Feedback context must contain plain JSON objects.");
+      result = Object.fromEntries(
+        Object.entries(item).map(([key, entry]) => [key, visit(entry)])
+      );
+    }
+    seen.delete(item);
+    return result;
+  }
+  return visit(value);
+}
+
+// src/shared/canonicalJson.ts
+function canonicalJson(value) {
+  function sort(value2) {
+    if (Array.isArray(value2)) return value2.map(sort);
+    if (value2 !== null && typeof value2 === "object")
+      return Object.fromEntries(
+        Object.keys(value2).sort().map((key) => [key, sort(value2[key])])
+      );
+    return value2;
+  }
+  return JSON.stringify(sort(copyJson(value)));
+}
+
+// src/server/files/FeedbackFiles.ts
+import {
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  writeFile
+} from "fs/promises";
+import path from "path";
+import { randomUUID } from "crypto";
+
+// src/shared/errors.ts
+var FeedbackError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "FeedbackError";
+  }
+  code;
+};
+
+// src/shared/workflow.ts
+var destinations = {
+  ingest: "ingested",
+  address: "addressed",
+  resolve: "resolved",
+  reopen: "open"
+};
+var predecessors = {
+  ingest: ["open"],
+  address: ["ingested"],
+  resolve: ["addressed"],
+  reopen: ["ingested", "addressed", "resolved"]
+};
+function isStatus(value) {
+  return ["open", "ingested", "addressed", "resolved"].includes(String(value));
+}
+function isAction(value) {
+  return typeof value === "string" && Object.hasOwn(destinations, value);
+}
+function parseTransition(value) {
+  const data = copyJson(value);
+  if (!data || typeof data !== "object" || Array.isArray(data) || typeof data.requestId !== "string" || !validId(data.requestId) || typeof data.expectedRevision !== "number" || !Number.isSafeInteger(data.expectedRevision) || data.expectedRevision < 0 || !isAction(data.action) || typeof data.actor !== "string" || !data.actor.trim() || data.actor.length > 200 || data.note !== void 0 && (typeof data.note !== "string" || data.note.length > 1e4)) {
+    throw new FeedbackError(
+      "invalid",
+      "Expected a request UUID, nonnegative revision, action, actor (1\u2013200 characters), and optional note (up to 10000 characters)."
+    );
+  }
+  return {
+    requestId: data.requestId,
+    expectedRevision: data.expectedRevision,
+    action: data.action,
+    actor: data.actor,
+    ...typeof data.note === "string" ? { note: data.note } : {}
+  };
+}
+function authoredComment(comment) {
+  return {
+    id: comment.id,
+    captureId: comment.captureId,
+    text: comment.text,
+    created: comment.created,
+    target: comment.target,
+    status: "open"
+  };
+}
+function readComment(value) {
+  const data = copyJson(value);
+  if (!data || typeof data !== "object" || Array.isArray(data) || typeof data.id !== "string" || !validId(data.id) || typeof data.captureId !== "string" || !validId(data.captureId) || typeof data.text !== "string" || !data.text.trim() || data.text.length > 1e4 || typeof data.created !== "string" || !Number.isFinite(Date.parse(data.created)) || !data.target || typeof data.target !== "object" || Array.isArray(data.target) || !["global", "entities", "area"].includes(String(data.target.kind))) {
+    throw new FeedbackError("invalid", "Invalid stored feedback comment.");
+  }
+  const authored = data;
+  let comment = {
+    ...authoredComment({ ...authored, revision: 0, history: [] }),
+    status: "open",
+    revision: 0,
+    history: []
+  };
+  if (data.revision === void 0 && data.history === void 0 && data.status === "open")
+    return comment;
+  if (!Array.isArray(data.history))
+    throw new FeedbackError("invalid", "Invalid feedback history.");
+  for (const value2 of data.history) {
+    if (!value2 || typeof value2 !== "object" || Array.isArray(value2) || typeof value2.created !== "string" || !Number.isFinite(Date.parse(value2.created)))
+      throw new FeedbackError("invalid", "Invalid feedback history entry.");
+    const request = parseTransition(value2);
+    const previous = comment;
+    comment = transitionComment(comment, request, value2.created);
+    if (comment === previous || value2.revision !== comment.revision || value2.from !== previous.status || value2.to !== comment.status)
+      throw new FeedbackError("invalid", "Invalid feedback history sequence.");
+  }
+  if (data.status !== comment.status || data.revision !== comment.revision)
+    throw new FeedbackError(
+      "invalid",
+      "Feedback status and revision must match history."
+    );
+  return comment;
+}
+function transitionComment(comment, request, created) {
+  const prior = comment.history.find(
+    (entry) => entry.requestId === request.requestId
+  );
+  if (prior) {
+    if (prior.expectedRevision !== request.expectedRevision || prior.action !== request.action || prior.actor !== request.actor || prior.note !== request.note)
+      throw new FeedbackError(
+        "conflict",
+        "Request ID conflict: retry the original command unchanged."
+      );
+    return comment;
+  }
+  if (request.expectedRevision !== comment.revision)
+    throw new FeedbackError(
+      "stale",
+      `Expected revision ${request.expectedRevision}, current revision is ${comment.revision}. Read the comment again.`
+    );
+  if (!predecessors[request.action].includes(comment.status))
+    throw new FeedbackError(
+      "conflict",
+      `Cannot ${request.action} feedback with status ${comment.status}.`
+    );
+  const status = destinations[request.action];
+  const revision = comment.revision + 1;
+  return {
+    ...comment,
+    status,
+    revision,
+    history: [
+      ...comment.history,
+      { ...request, created, revision, from: comment.status, to: status }
+    ]
+  };
+}
+
+// src/server/files/FeedbackFiles.ts
+async function optionalFile(file) {
+  try {
+    return await readFile(file);
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+var FeedbackFiles = class {
+  directory;
+  constructor(directory) {
+    this.directory = path.resolve(directory);
+  }
+  async save(data, bytes) {
+    const { capture, comment } = data;
+    const captureRoot = path.join(this.directory, "captures");
+    const commentsRoot = path.join(this.directory, "comments");
+    await mkdir(captureRoot, { recursive: true });
+    await mkdir(commentsRoot, { recursive: true });
+    const destination = path.join(captureRoot, capture.id);
+    const captureJson = JSON.stringify(capture, null, 2) + "\n";
+    const commentJson = JSON.stringify(readComment(comment), null, 2) + "\n";
+    const commentPath = path.join(commentsRoot, `${comment.id}.json`);
+    const previousComment = await optionalFile(commentPath);
+    if (previousComment && canonicalJson(
+      authoredComment(readComment(JSON.parse(previousComment.toString())))
+    ) !== canonicalJson(authoredComment(readComment(comment))))
+      throw new FeedbackError("conflict", "Comment ID conflict.");
+    const previous = await optionalFile(path.join(destination, "capture.json"));
+    if (previous) {
+      if (canonicalJson(JSON.parse(previous.toString())) !== canonicalJson(capture) || !(await readFile(path.join(destination, "screenshot.png"))).equals(
+        bytes
+      ))
+        throw new FeedbackError("conflict", "Capture ID conflict.");
+    } else {
+      const staging = path.join(captureRoot, `.pending-${randomUUID()}`);
+      await mkdir(staging);
+      try {
+        await writeFile(path.join(staging, "screenshot.png"), bytes);
+        await writeFile(path.join(staging, "capture.json"), captureJson);
+        await rename(staging, destination);
+      } catch (error) {
+        await rm(staging, { recursive: true, force: true });
+        throw error;
+      }
+    }
+    if (!previousComment) {
+      const temporary = path.join(commentsRoot, `.pending-${randomUUID()}`);
+      try {
+        await writeFile(temporary, commentJson);
+        await rename(temporary, commentPath);
+      } catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+      }
+    }
+    return this.show(comment.id);
+  }
+  async list() {
+    const root = path.join(this.directory, "comments");
+    await mkdir(root, { recursive: true });
+    const files = (await readdir(root)).filter((file) => file.endsWith(".json") && validId(file.slice(0, -5))).sort();
+    const comments = await Promise.all(
+      files.map(
+        async (file) => readComment(JSON.parse(await readFile(path.join(root, file), "utf8")))
+      )
+    );
+    return comments.sort(
+      (a, b) => a.created.localeCompare(b.created) || a.id.localeCompare(b.id)
+    );
+  }
+  async show(id) {
+    const comment = readComment(
+      JSON.parse(
+        await readFile(
+          path.join(this.directory, "comments", `${id}.json`),
+          "utf8"
+        )
+      )
+    );
+    const captureRoot = path.join(
+      this.directory,
+      "captures",
+      comment.captureId
+    );
+    const capture = JSON.parse(
+      await readFile(path.join(captureRoot, "capture.json"), "utf8")
+    );
+    return {
+      comment,
+      capture,
+      screenshotPath: path.join(captureRoot, "screenshot.png"),
+      screenshotUrl: `/captures/${comment.captureId}/screenshot.png`
+    };
+  }
+  async writeComment(comment) {
+    const root = path.join(this.directory, "comments");
+    const temporary = path.join(root, `.pending-${randomUUID()}`);
+    try {
+      await writeFile(temporary, JSON.stringify(comment, null, 2) + "\n");
+      await rename(temporary, path.join(root, `${comment.id}.json`));
+    } catch (error) {
+      await rm(temporary, { force: true });
+      throw error;
+    }
+  }
+  async image(id) {
+    return readFile(
+      path.join(this.directory, "captures", id, "screenshot.png")
+    );
+  }
+};
+
+// src/server/service/validatePng.ts
+import { PNG } from "pngjs";
+var MAX_PIXELS = 16777216;
+function validatePng(bytes, width, height) {
+  if (bytes.length < 33 || bytes.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a" || bytes.readUInt32BE(8) !== 13 || bytes.toString("ascii", 12, 16) !== "IHDR")
+    throw new Error("Invalid PNG header.");
+  if (bytes.readUInt32BE(16) !== width || bytes.readUInt32BE(20) !== height)
+    throw new Error("PNG dimensions do not match capture dimensions.");
+  if (width * height > MAX_PIXELS || bytes[28] !== 0)
+    throw new Error(
+      "Screenshots must be non-interlaced PNGs of at most 16777216 pixels."
+    );
+  let offset = 8;
+  let ended = false;
+  while (offset + 12 <= bytes.length) {
+    const length = bytes.readUInt32BE(offset);
+    const next = offset + length + 12;
+    if (next > bytes.length) throw new Error("Truncated PNG chunk.");
+    const type = bytes.toString("ascii", offset + 4, offset + 8);
+    if (type === "IHDR" && offset !== 8)
+      throw new Error("PNG contains multiple headers.");
+    if (type === "IEND") {
+      if (length !== 0 || next !== bytes.length)
+        throw new Error("Invalid PNG end chunk.");
+      ended = true;
+      break;
+    }
+    offset = next;
+  }
+  if (!ended) throw new Error("PNG is missing its end chunk.");
+  try {
+    PNG.sync.read(bytes, { checkCRC: true });
+  } catch (error) {
+    throw new Error("PNG pixels could not be decoded.", { cause: error });
+  }
+}
+
+// src/server/service/validateUpload.ts
+function requireId(id) {
+  if (typeof id !== "string" || !validId(id))
+    throw new FeedbackError("invalid", "Invalid feedback ID.");
+}
+function rectValid(rect, width, height) {
+  return [rect.x, rect.y, rect.width, rect.height].every(Number.isFinite) && rect.x >= 0 && rect.y >= 0 && rect.width > 0 && rect.height > 0 && rect.x + rect.width <= width + 0.01 && rect.y + rect.height <= height + 0.01;
+}
+function validateUpload(data) {
+  copyJson(data);
+  const { capture, comment, image } = data;
+  if ("revision" in comment || "history" in comment)
+    throw new Error("Uploads cannot supply workflow history.");
+  copyJson(capture.context);
+  requireId(capture.id);
+  requireId(capture.sessionId);
+  requireId(comment.id);
+  if (capture.version !== 1 || comment.captureId !== capture.id || comment.status !== "open")
+    throw new Error("Invalid feedback version or capture reference.");
+  if (typeof comment.text !== "string" || !comment.text.trim() || comment.text.length > 1e4)
+    throw new Error("Feedback text must contain 1\u201310000 characters.");
+  if (!Number.isSafeInteger(capture.frame) || capture.frame < 0 || !Number.isSafeInteger(capture.width) || !Number.isSafeInteger(capture.height) || capture.width <= 0 || capture.height <= 0)
+    throw new Error("Invalid capture frame or dimensions.");
+  if (typeof capture.snapshot !== "object" || capture.snapshot === null || Array.isArray(capture.snapshot) || capture.snapshot["frame"] !== capture.frame)
+    throw new Error("Inspector snapshot frame does not match capture frame.");
+  if (typeof capture.url !== "string" || typeof capture.created !== "string" || typeof comment.created !== "string" || !Number.isFinite(Date.parse(capture.created)) || !Number.isFinite(Date.parse(comment.created)))
+    throw new Error("Invalid feedback URL or timestamp.");
+  if (!Array.isArray(capture.entities) || capture.entities.some(
+    (entity) => typeof entity.id !== "string" || typeof entity.sceneId !== "string" || typeof entity.name !== "string" || !Number.isSafeInteger(entity.generation) || entity.generation < 0 || !rectValid(entity.bounds, capture.width, capture.height)
+  ))
+    throw new Error("Invalid capture entities.");
+  const target = comment.target;
+  if (target.kind === "area") {
+    if (!rectValid(target.rect, capture.width, capture.height))
+      throw new Error("Invalid feedback area.");
+  } else if (target.kind === "entities") {
+    if (!Array.isArray(target.entities) || target.entities.length === 0 || target.entities.some(
+      (entity) => !capture.entities.some(
+        (candidate) => canonicalJson(candidate) === canonicalJson(entity)
+      )
+    ))
+      throw new Error("Invalid feedback entities.");
+  } else if (target.kind !== "global")
+    throw new Error("Invalid feedback target.");
+  if (typeof image !== "string" || !/^data:image\/png;base64,[A-Za-z0-9+/]+={0,2}$/.test(image))
+    throw new Error("Expected PNG data URL.");
+  const bytes = Buffer.from(image.slice(image.indexOf(",") + 1), "base64");
+  validatePng(bytes, capture.width, capture.height);
+  return bytes;
+}
+
+// src/server/service/FeedbackService.ts
+var FeedbackService = class {
+  files;
+  tail = Promise.resolve();
+  constructor(directory) {
+    this.files = new FeedbackFiles(directory);
+  }
+  async idle() {
+    await this.tail;
+  }
+  get directory() {
+    return this.files.directory;
+  }
+  run(work) {
+    const result = this.tail.then(work);
+    this.tail = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  }
+  save(value) {
+    return this.run(async () => {
+      let data;
+      let bytes;
+      try {
+        data = copyJson(value);
+        bytes = validateUpload(data);
+      } catch (error) {
+        throw new FeedbackError(
+          "invalid",
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+      return this.files.save(data, bytes);
+    });
+  }
+  async list(status) {
+    if (status !== void 0 && !isStatus(status))
+      throw new FeedbackError("invalid", "Unknown feedback status.");
+    const comments = await this.files.list();
+    return status ? comments.filter((comment) => comment.status === status) : comments;
+  }
+  async show(id) {
+    requireId(id);
+    return this.files.show(id);
+  }
+  async image(id) {
+    requireId(id);
+    return this.files.image(id);
+  }
+  transition(id, value) {
+    return this.run(async () => {
+      requireId(id);
+      const request = parseTransition(value);
+      const detail = await this.files.show(id);
+      const comment = transitionComment(
+        detail.comment,
+        request,
+        (/* @__PURE__ */ new Date()).toISOString()
+      );
+      if (comment !== detail.comment) await this.files.writeComment(comment);
+      return { ...detail, comment };
+    });
+  }
+};
+
+// src/server/files/DirectoryLock.ts
+import {
+  mkdirSync,
+  openSync,
+  writeFileSync,
+  closeSync,
+  unlinkSync
+} from "fs";
+import path2 from "path";
+function acquireDirectoryLock(directory) {
+  mkdirSync(directory, { recursive: true });
+  const file = path2.join(directory, ".server.lock");
+  let descriptor;
+  try {
+    descriptor = openSync(file, "wx");
+  } catch (error) {
+    if (error.code === "EEXIST")
+      throw new Error(
+        `Feedback directory is locked: ${file}. Stop its server first. After a crash, confirm the recorded PID is no longer running before removing the lock.`,
+        { cause: error }
+      );
+    throw error;
+  }
+  try {
+    writeFileSync(
+      descriptor,
+      JSON.stringify({ pid: process.pid, created: (/* @__PURE__ */ new Date()).toISOString() }) + "\n"
+    );
+  } catch (error) {
+    closeSync(descriptor);
+    unlinkSync(file);
+    throw error;
+  }
+  closeSync(descriptor);
+  let released = false;
+  return () => {
+    if (!released) {
+      unlinkSync(file);
+      released = true;
+    }
+  };
+}
+
+// src/shared/endpoint.ts
+function normalizeBasePath(value) {
+  if (!/^\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_-]*\/?$/.test(value))
+    throw new Error(
+      "Feedback base path must contain only slash-separated letters, digits, underscores, or hyphens."
+    );
+  return value.endsWith("/") ? value : value + "/";
+}
+
+// src/server/files/GalleryAssets.ts
+import { readFile as readFile2 } from "fs/promises";
+function readGalleryScript() {
+  return readFile2(new URL("./gallery.js", import.meta.url));
+}
+
+// src/gallery/gallery.html?raw
+var gallery_default = '<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n    <meta name="viewport" content="width=device-width,initial-scale=1" />\n    <meta name="feedback-api" content="FEEDBACK_API_PATH" />\n    <title>YAGE feedback</title>\n    <style>\n      :root {\n        color-scheme: dark;\n        font:\n          15px/1.5 system-ui,\n          sans-serif;\n        color: #e4edf4;\n        background: #101820;\n      }\n      * {\n        box-sizing: border-box;\n      }\n      body {\n        margin: 0;\n      }\n      main {\n        max-width: 1440px;\n        margin: auto;\n        padding: 32px;\n      }\n      header {\n        display: flex;\n        align-items: start;\n        justify-content: space-between;\n        gap: 20px;\n      }\n      h1 {\n        font-size: 28px;\n        margin: 0;\n      }\n      h2 {\n        margin: 0 0 12px;\n      }\n      p {\n        margin: 8px 0;\n      }\n      small,\n      .muted {\n        color: #a6b7c6;\n      }\n      .project {\n        overflow-wrap: anywhere;\n      }\n      .toolbar {\n        display: flex;\n        gap: 10px;\n        flex-wrap: wrap;\n        align-items: center;\n        margin: 24px 0 12px;\n        position: sticky;\n        top: 0;\n        background: #101820;\n        padding: 12px 0;\n        z-index: 1;\n      }\n      button,\n      select,\n      input,\n      textarea {\n        font: inherit;\n        color: inherit;\n        background: #213140;\n        border: 1px solid #4b6375;\n        border-radius: 7px;\n        padding: 9px 12px;\n      }\n      button {\n        cursor: pointer;\n      }\n      button:hover {\n        background: #30495d;\n      }\n      button:disabled {\n        opacity: 0.45;\n        cursor: default;\n      }\n      button:focus-visible,\n      a:focus-visible,\n      input:focus-visible,\n      select:focus-visible {\n        outline: 2px solid #79d8d1;\n        outline-offset: 3px;\n      }\n      input[type="search"] {\n        min-width: 200px;\n        flex: 1;\n      }\n      input[type="checkbox"] {\n        accent-color: #79d8d1;\n        width: 18px;\n        height: 18px;\n      }\n      label {\n        display: flex;\n        gap: 8px;\n        align-items: center;\n      }\n      .grid {\n        display: grid;\n        grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));\n        gap: 18px;\n      }\n      .card {\n        border: 1px solid #324858;\n        border-radius: 10px;\n        overflow: hidden;\n        background: #192631;\n      }\n      .card:has(input:checked) {\n        border-color: #79d8d1;\n      }\n      .preview {\n        padding: 0;\n        border: 0;\n        border-radius: 0;\n        display: block;\n        width: 100%;\n        background: #0b1218;\n      }\n      .preview img {\n        display: block;\n        width: 100%;\n        aspect-ratio: 16/9;\n        object-fit: contain;\n      }\n      .content {\n        padding: 16px;\n      }\n      .comment {\n        white-space: pre-wrap;\n        overflow-wrap: anywhere;\n        margin: 12px 0;\n      }\n      .card .comment {\n        display: -webkit-box;\n        -webkit-line-clamp: 4;\n        -webkit-box-orient: vertical;\n        overflow: hidden;\n      }\n      .badge {\n        font-size: 12px;\n        text-transform: uppercase;\n        letter-spacing: 0.06em;\n        color: #79d8d1;\n        margin-left: auto;\n      }\n      .meta {\n        display: flex;\n        align-items: center;\n        gap: 8px;\n      }\n      .pagination {\n        display: flex;\n        justify-content: center;\n        align-items: center;\n        gap: 16px;\n        margin: 24px;\n      }\n      dialog {\n        color: inherit;\n        background: #15222c;\n        border: 1px solid #4b6375;\n        border-radius: 12px;\n        width: min(1200px, 95vw);\n        max-height: 92vh;\n        padding: 24px;\n      }\n      dialog::backdrop {\n        background: #000a;\n      }\n      .detail-grid {\n        display: grid;\n        grid-template-columns: minmax(0, 1.6fr) minmax(260px, 1fr);\n        gap: 24px;\n        margin-top: 20px;\n      }\n      .capture {\n        position: relative;\n        width: 100%;\n        align-self: start;\n      }\n      .capture img {\n        display: block;\n        width: 100%;\n      }\n      .outline {\n        position: absolute;\n        border: 2px solid #ffca66;\n        background: #ffca661a;\n        pointer-events: none;\n      }\n      pre {\n        white-space: pre-wrap;\n        overflow-wrap: anywhere;\n        font-size: 12px;\n        max-height: 350px;\n        overflow: auto;\n        background: #0d1720;\n        padding: 12px;\n      }\n      summary {\n        cursor: pointer;\n        padding: 8px 0;\n      }\n      .error {\n        color: #ffafab;\n      }\n      textarea {\n        width: 100%;\n        min-height: 130px;\n      }\n      a {\n        color: #79d8d1;\n      }\n      @media (max-width: 720px) {\n        main {\n          padding: 16px;\n        }\n        header {\n          flex-direction: column;\n        }\n        .detail-grid {\n          grid-template-columns: 1fr;\n        }\n        .toolbar {\n          position: static;\n        }\n      }\n    </style>\n  </head>\n  <body>\n    <main>\n      <header>\n        <div>\n          <h1>Feedback</h1>\n          <p class="muted project" id="project">Loading project\u2026</p>\n        </div>\n        <button id="refresh">Refresh</button>\n      </header>\n      <div class="toolbar">\n        <label\n          >Status\n          <select id="status">\n            <option value="pending">Pending</option>\n            <option value="open">Open</option>\n            <option value="ingested">Ingested</option>\n            <option value="addressed">Addressed</option>\n            <option value="resolved">Resolved</option>\n            <option value="all">All</option>\n          </select></label\n        >\n        <input\n          type="search"\n          id="search"\n          aria-label="Search comments"\n          placeholder="Search comments or entity names"\n        />\n        <button id="select-page">Select page</button\n        ><button id="clear">Clear selection</button>\n        <button id="codex" disabled>Copy for Codex</button\n        ><button id="claude" disabled>Copy for Claude</button>\n      </div>\n      <p id="summary" class="muted"></p>\n      <p id="message" role="status"></p>\n      <div class="grid" id="cards"></div>\n      <div class="pagination">\n        <button id="previous">Previous</button><span id="page"></span\n        ><button id="next">Next</button>\n      </div>\n    </main>\n    <dialog id="detail" aria-labelledby="detail-title">\n      <header>\n        <h2 id="detail-title">Comment evidence</h2>\n        <button id="close-detail">Close</button>\n      </header>\n      <div id="evidence"></div>\n    </dialog>\n    <dialog id="copy" aria-labelledby="copy-title">\n      <header>\n        <h2 id="copy-title">Paste into your agent session</h2>\n        <button id="close-copy">Close</button>\n      </header>\n      <p>Clipboard access was unavailable. Copy this instruction:</p>\n      <textarea\n        id="instruction"\n        readonly\n        aria-label="Agent instruction"\n      ></textarea>\n    </dialog>\n    <script type="module" src="./gallery.js"></script>\n  </body>\n</html>\n';
+
+// src/server/http/application.ts
+function createFeedbackApplication(options) {
+  const basePath = normalizeBasePath(options.basePath ?? "/");
+  const galleryPath = normalizeBasePath(
+    options.galleryPath ?? basePath + "gallery/"
+  );
+  const store = new FeedbackService(options.directory);
+  const release = acquireDirectoryLock(store.directory);
+  const active = /* @__PURE__ */ new Set();
+  let closing;
+  const send = (response, status, body) => {
+    response.writeHead(status, {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store"
+    });
+    response.end(JSON.stringify(body));
+  };
+  async function route(request, response) {
+    const remote = request.socket.remoteAddress;
+    if (!remote || !["127.0.0.1", "::1", "::ffff:127.0.0.1"].includes(remote)) {
+      send(response, 403, {
+        error: "Feedback is only available on this machine."
+      });
+      return;
+    }
+    const host = request.headers.host;
+    if (!host || !/^(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]{1,5})?$/i.test(host)) {
+      send(response, 403, {
+        code: "invalid-host",
+        error: "Expected a loopback Host header."
+      });
+      return;
+    }
+    if (closing) {
+      send(response, 503, { error: "Feedback is shutting down." });
+      return;
+    }
+    const origin = request.headers.origin;
+    if (origin && origin !== `http://${host}` && !options.origins?.includes(origin)) {
+      send(response, 403, {
+        error: "Origin is not allowed. Pass --origin to the feedback server."
+      });
+      return;
+    }
+    if (origin) response.setHeader("Access-Control-Allow-Origin", origin);
+    response.setHeader("Vary", "Origin");
+    if (request.method === "OPTIONS") {
+      response.writeHead(204, {
+        "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type"
+      });
+      response.end();
+      return;
+    }
+    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+    if (request.method === "GET" && (url.pathname === galleryPath.slice(0, -1) || url.pathname === basePath + "gallery/" && galleryPath !== basePath + "gallery/")) {
+      response.writeHead(302, { Location: galleryPath });
+      response.end();
+      return;
+    }
+    if (request.method === "GET" && url.pathname === galleryPath + "gallery.js") {
+      const script = await readGalleryScript();
+      response.writeHead(200, {
+        "Content-Type": "text/javascript; charset=utf-8",
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff"
+      });
+      response.end(script);
+      return;
+    }
+    if (request.method === "GET" && url.pathname === galleryPath) {
+      response.writeHead(200, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff"
+      });
+      response.end(gallery_default.replace("FEEDBACK_API_PATH", basePath));
+      return;
+    }
+    if (!url.pathname.startsWith(basePath)) {
+      send(response, 404, { error: "Unknown feedback route." });
+      return;
+    }
+    url.pathname = "/" + url.pathname.slice(basePath.length);
+    if (request.method === "GET" && url.pathname === "/session") {
+      send(response, 200, {
+        directory: store.directory,
+        project: options.project ?? process.cwd(),
+        galleryPath
+      });
+      return;
+    }
+    const detail = (value) => ({
+      ...value,
+      screenshotUrl: basePath + value.screenshotUrl.replace(/^\//, "")
+    });
+    if (request.method === "GET" && url.pathname === "/health") {
+      send(response, 200, { ok: true });
+      return;
+    }
+    if (request.method === "GET" && url.pathname === "/comments") {
+      send(
+        response,
+        200,
+        await store.list(url.searchParams.get("status") ?? void 0)
+      );
+      return;
+    }
+    if (request.method === "GET" && url.pathname.startsWith("/comments/")) {
+      send(response, 200, detail(await store.show(url.pathname.slice(10))));
+      return;
+    }
+    const image = /^\/captures\/([^/]+)\/screenshot\.png$/.exec(url.pathname);
+    if (request.method === "GET" && image?.[1]) {
+      const bytes = await store.image(image[1]);
+      response.writeHead(200, {
+        "Content-Type": "image/png",
+        "Cache-Control": "no-store"
+      });
+      response.end(bytes);
+      return;
+    }
+    const transition = /^\/comments\/([^/]+)\/transitions$/.exec(url.pathname);
+    if (request.method === "POST" && (url.pathname === "/comments" || transition)) {
+      if (!request.headers["content-type"]?.startsWith("application/json")) {
+        send(response, 415, { error: "Expected application/json." });
+        return;
+      }
+      let size = 0;
+      const chunks = [];
+      for await (const chunk of request) {
+        const bytes = Buffer.from(chunk);
+        size += bytes.length;
+        if (size > 24 * 1024 * 1024) {
+          send(response, 413, { error: "Capture exceeds 24 MiB." });
+          return;
+        }
+        chunks.push(bytes);
+      }
+      const data = JSON.parse(Buffer.concat(chunks).toString());
+      send(
+        response,
+        200,
+        detail(
+          transition?.[1] ? await store.transition(transition[1], data) : await store.save(data)
+        )
+      );
+      return;
+    }
+    send(response, 404, { error: "Unknown feedback route." });
+  }
+  const handle = (request, response) => {
+    const operation = route(request, response).catch((error) => {
+      if (response.headersSent) {
+        response.destroy();
+        return;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      const code = error.code;
+      const status = error instanceof FeedbackError ? { invalid: 400, conflict: 409, stale: 409, "not-found": 404 }[error.code] : code === "ENOENT" ? 404 : error instanceof SyntaxError ? 400 : 500;
+      send(response, status, {
+        error: message,
+        code: error instanceof FeedbackError ? error.code : code === "ENOENT" ? "not-found" : status === 400 ? "invalid" : "internal"
+      });
+    });
+    active.add(operation);
+    void operation.finally(() => active.delete(operation));
+  };
+  return {
+    handle,
+    close: () => {
+      closing ??= (async () => {
+        await Promise.all([...active]);
+        await store.idle();
+        release();
+      })();
+      return closing;
+    }
+  };
+}
+
+// src/server/http/server.ts
+async function startFeedbackServer(options) {
+  const port = options.port ?? 5212;
+  if (!Number.isInteger(port) || port < 0 || port > 65535)
+    throw new Error("Feedback port must be an integer from 0 to 65535.");
+  const app = createFeedbackApplication({
+    ...options,
+    // Vite's default dev origins, so a game on `vite` needs no --origin.
+    origins: options.origins ?? [
+      "http://localhost:5173",
+      "http://127.0.0.1:5173"
+    ]
+  });
+  const server = createServer(app.handle);
+  try {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, "127.0.0.1", () => {
+        server.off("error", reject);
+        resolve();
+      });
+    });
+  } catch (error) {
+    await app.close();
+    throw error;
+  }
+  const address = server.address();
+  if (!address || typeof address === "string")
+    throw new Error("Feedback server has no TCP address.");
+  let closing;
+  return {
+    url: `http://127.0.0.1:${address.port}${normalizeBasePath(options.basePath ?? "/").replace(/\/$/, "")}`,
+    close: () => {
+      closing ??= (async () => {
+        await new Promise(
+          (resolve, reject) => server.close((error) => error ? reject(error) : resolve())
+        );
+        await app.close();
+      })();
+      return closing;
+    }
+  };
+}
+export {
+  startFeedbackServer
+};