@yagejs-tools/feedback 0.0.0 → 0.1.0

package/dist/index.js

@@ -0,0 +1,1057 @@
+// src/shared/shortcuts.ts
+var shortcutActions = [
+  "feedback",
+  "freeze",
+  "stepFrame",
+  "stepTenFrames"
+];
+function resolveShortcuts(options = true) {
+  if (typeof options !== "boolean" && (!options || typeof options !== "object" || Array.isArray(options)))
+    throw new Error(
+      "Feedback shortcuts must be a boolean or a bindings object."
+    );
+  if (typeof options === "object") {
+    for (const key of Object.keys(options))
+      if (!shortcutActions.some((action) => action === key))
+        throw new Error(`Unknown feedback shortcut action: ${key}.`);
+  }
+  const resolve = (action, code, shift = false) => {
+    const configured = typeof options === "object" ? options[action] : void 0;
+    const binding = options === false ? false : configured === void 0 ? { code, shift } : configured;
+    if (binding === false) return false;
+    if (!binding || typeof binding !== "object" || typeof binding.code !== "string" || !/^[A-Za-z][A-Za-z0-9]*$/.test(binding.code) || /^(?:Shift|Control|Alt|Meta)(?:Left|Right)$/.test(binding.code))
+      throw new Error(
+        `Feedback shortcuts.${action}: provide a non-modifier KeyboardEvent.code.`
+      );
+    for (const key of Object.keys(binding))
+      if (!["code", "ctrl", "alt", "shift", "meta"].includes(key))
+        throw new Error(`Feedback shortcuts.${action}: unknown option ${key}.`);
+    for (const modifier of ["ctrl", "alt", "shift", "meta"])
+      if (binding[modifier] !== void 0 && typeof binding[modifier] !== "boolean")
+        throw new Error(
+          `Feedback shortcuts.${action}.${modifier} must be a boolean.`
+        );
+    return {
+      code: binding.code,
+      ctrl: binding.ctrl ?? false,
+      alt: binding.alt ?? false,
+      shift: binding.shift ?? false,
+      meta: binding.meta ?? false
+    };
+  };
+  const result = {
+    feedback: resolve("feedback", "F8"),
+    freeze: resolve("freeze", "F9"),
+    stepFrame: resolve("stepFrame", "F10"),
+    stepTenFrames: resolve("stepTenFrames", "F10", true)
+  };
+  const used = /* @__PURE__ */ new Set();
+  for (const action of shortcutActions) {
+    const binding = result[action];
+    if (!binding) continue;
+    const identity = JSON.stringify(binding);
+    if (used.has(identity))
+      throw new Error("Feedback shortcuts must use different bindings.");
+    used.add(identity);
+  }
+  return result;
+}
+function shortcutLabel(binding) {
+  return binding ? [
+    binding.ctrl && "Ctrl",
+    binding.alt && "Alt",
+    binding.shift && "Shift",
+    binding.meta && "Meta",
+    binding.code.replace(/^(Key|Digit)(?=.)/, "")
+  ].filter(Boolean).join("+") : "";
+}
+
+// src/client/FeedbackClient.ts
+var FeedbackClient = class {
+  constructor(server = "http://127.0.0.1:5212", timeoutMs = 3e4) {
+    this.timeoutMs = timeoutMs;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 3e5)
+      throw new Error(
+        "Feedback request timeout must be an integer from 1 to 300000 ms."
+      );
+    this.base = new URL(server);
+    this.base.pathname = this.base.pathname.replace(/\/?$/, "/");
+    if (this.base.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(this.base.hostname) || this.base.username || this.base.password || this.base.search || this.base.hash)
+      throw new Error(
+        "Feedback server must be a loopback HTTP URL without credentials, query, or fragment."
+      );
+  }
+  timeoutMs;
+  base;
+  async request(route, body, signal) {
+    const timeout = AbortSignal.timeout(this.timeoutMs);
+    const response = await fetch(new URL(route.replace(/^\//, ""), this.base), {
+      ...body !== void 0 ? {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      } : {},
+      signal: signal ? AbortSignal.any([signal, timeout]) : timeout
+    });
+    if (!response.ok)
+      throw new Error(
+        `Feedback server returned ${response.status}: ${await response.text()}`
+      );
+    return await response.json();
+  }
+  get galleryUrl() {
+    return new URL("gallery/", this.base).href;
+  }
+  session() {
+    return this.request("session");
+  }
+  list(status) {
+    return this.request(`/comments${status ? `?status=${status}` : ""}`);
+  }
+  show(id) {
+    return this.request(`/comments/${encodeURIComponent(id)}`);
+  }
+  save(upload, signal) {
+    return this.request("/comments", upload, signal);
+  }
+  transition(id, request) {
+    return this.request(
+      `/comments/${encodeURIComponent(id)}/transitions`,
+      request
+    );
+  }
+};
+
+// src/browser/session/FeedbackSession.ts
+var FeedbackSession = class {
+  constructor(host, client) {
+    this.host = host;
+    this.client = client;
+  }
+  host;
+  client;
+  observation;
+  abort;
+  draft;
+  saved = [];
+  get pending() {
+    return this.draft !== void 0;
+  }
+  get draftComment() {
+    return this.draft?.comment;
+  }
+  get comments() {
+    return this.saved;
+  }
+  open() {
+    if (this.observation) return this.observation;
+    if (this.draft) {
+      this.host.freeze();
+      this.observation = {
+        capture: this.draft.capture,
+        image: this.draft.image
+      };
+    } else this.observation = this.host.capture();
+    return this.observation;
+  }
+  async save(text, target) {
+    if (!this.observation) throw new Error("Open feedback before saving.");
+    if (this.abort) return false;
+    if (!this.draft) {
+      if (!text.trim() || text.trim().length > 1e4)
+        throw new Error("Write a comment of 1\u201310000 characters.");
+      this.draft = {
+        ...this.observation,
+        comment: {
+          id: crypto.randomUUID(),
+          captureId: this.observation.capture.id,
+          created: (/* @__PURE__ */ new Date()).toISOString(),
+          text: text.trim(),
+          target: structuredClone(target),
+          status: "open"
+        }
+      };
+    }
+    const abort = new AbortController();
+    this.abort = abort;
+    try {
+      const detail = await this.client.save(this.draft, abort.signal);
+      if (this.abort !== abort) return false;
+      this.saved.push(detail.comment);
+      this.draft = void 0;
+      return true;
+    } catch (error) {
+      if (this.abort !== abort) return false;
+      throw error;
+    } finally {
+      if (this.abort === abort) this.abort = void 0;
+    }
+  }
+  discard() {
+    if (this.abort)
+      throw new Error("Wait for the current save before discarding.");
+    this.draft = void 0;
+  }
+  canStep() {
+    return !this.observation && this.host.canStep();
+  }
+  step(frames) {
+    if (this.observation)
+      throw new Error("Return to the game view before stepping.");
+    this.host.step(frames);
+  }
+  toggleFreeze() {
+    return this.host.toggleFreeze();
+  }
+  cancelSave() {
+    this.abort?.abort();
+    this.abort = void 0;
+  }
+  close() {
+    this.cancelSave();
+    this.observation = void 0;
+    this.host.release();
+  }
+};
+
+// src/browser/runtime/RuntimeFeedbackHost.ts
+import {
+  EngineKey,
+  ErrorBoundaryKey,
+  InspectorKey as InspectorKey2,
+  ServiceKey
+} from "@yagejs/core";
+
+// src/browser/runtime/capture.ts
+import { InspectorKey } from "@yagejs/core";
+import { RendererKey, VisualComponent } from "@yagejs/renderer";
+
+// src/shared/protocol.ts
+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/browser/runtime/capture.ts
+function captureView(engine, sessionId, context) {
+  const renderer = engine.context.resolve(RendererKey);
+  const inspector = engine.context.resolve(InspectorKey);
+  const debug = inspector.getExtension("debug");
+  const wasHudVisible = debug?.isHudVisible() ?? false;
+  const { canvas } = renderer;
+  let image;
+  try {
+    if (wasHudVisible) debug?.setHudVisible(false);
+    renderer.application.render();
+    image = canvas.toDataURL("image/png");
+  } finally {
+    if (wasHudVisible) debug?.setHudVisible(true);
+  }
+  const snapshot = inspector.snapshot();
+  const entities = captureEntities(engine, snapshot);
+  return {
+    image,
+    capture: {
+      version: 1,
+      id: crypto.randomUUID(),
+      sessionId,
+      created: (/* @__PURE__ */ new Date()).toISOString(),
+      frame: snapshot.frame,
+      url: location.href,
+      width: canvas.width,
+      height: canvas.height,
+      context,
+      snapshot: copyJson(JSON.parse(JSON.stringify(snapshot))),
+      entities
+    }
+  };
+}
+function captureEntities(engine, snapshot) {
+  const renderer = engine.context.resolve(RendererKey);
+  const { width, height } = renderer.canvas;
+  const screen = renderer.application.renderer.screen;
+  const result = [];
+  for (const scene of engine.scenes.all) {
+    for (const entity of scene.getEntities()) {
+      const visualBounds = [];
+      for (const component of entity.getAll(VisualComponent)) {
+        const display = component.renderObject;
+        let visible = true;
+        let parent = display;
+        while (true) {
+          if (!parent.visible || !parent.renderable || parent.alpha <= 0)
+            visible = false;
+          if (!parent.parent) break;
+          parent = parent.parent;
+        }
+        if (!visible || parent !== renderer.application.stage) continue;
+        const bounds = display.getBounds();
+        const x2 = Math.max(0, bounds.x * width / screen.width);
+        const y2 = Math.max(0, bounds.y * height / screen.height);
+        const right2 = Math.min(
+          width,
+          (bounds.x + bounds.width) * width / screen.width
+        );
+        const bottom2 = Math.min(
+          height,
+          (bounds.y + bounds.height) * height / screen.height
+        );
+        if ([x2, y2, right2, bottom2].every(Number.isFinite) && right2 > x2 && bottom2 > y2)
+          visualBounds.push({ x: x2, y: y2, width: right2 - x2, height: bottom2 - y2 });
+      }
+      if (visualBounds.length === 0) continue;
+      const x = Math.min(...visualBounds.map((box) => box.x));
+      const y = Math.min(...visualBounds.map((box) => box.y));
+      const right = Math.max(...visualBounds.map((box) => box.x + box.width));
+      const bottom = Math.max(...visualBounds.map((box) => box.y + box.height));
+      const capturedScene = snapshot.scenes.find(
+        (candidate) => candidate.entities.some((one) => one.id === String(entity.id))
+      );
+      const captured = capturedScene?.entities.find(
+        (one) => one.id === String(entity.id)
+      );
+      if (captured && capturedScene)
+        result.push({
+          sceneId: capturedScene.id,
+          id: captured.id,
+          generation: captured.generation,
+          name: entity.name,
+          bounds: { x, y, width: right - x, height: bottom - y }
+        });
+    }
+  }
+  return result;
+}
+
+// src/browser/runtime/RuntimeFeedbackHost.ts
+var InputKey = new ServiceKey("inputManager");
+var RuntimeFeedbackHost = class {
+  constructor(context, metadata) {
+    this.context = context;
+    this.metadata = metadata;
+    this.engine = context.resolve(EngineKey);
+  }
+  context;
+  metadata;
+  engine;
+  lease;
+  wasFrozen = false;
+  sessionId = crypto.randomUUID();
+  /** Resolved on use: the Inspector is installed by DebugPlugin at start. */
+  get inspector() {
+    return this.context.resolve(InspectorKey2);
+  }
+  capture() {
+    if (this.inspector.time.isOwned())
+      throw new Error(
+        "Pause the lab or other clock owner, then click here to leave feedback."
+      );
+    let metadata = {};
+    const callback = this.metadata;
+    if (callback)
+      this.context.resolve(ErrorBoundaryKey).wrapCallback(
+        () => {
+          metadata = copyJson(callback());
+        },
+        { kind: "Feedback context" }
+      );
+    this.freeze();
+    try {
+      const observation = captureView(this.engine, this.sessionId, metadata);
+      this.context.tryResolve(InputKey)?.clearAll();
+      return observation;
+    } catch (error) {
+      this.release();
+      throw error;
+    }
+  }
+  freeze() {
+    this.lease = this.inspector.time.acquire();
+    this.wasFrozen = this.lease.isFrozen();
+    this.lease.freeze();
+    this.context.tryResolve(InputKey)?.clearAll();
+  }
+  toggleFreeze() {
+    const time = this.inspector.time;
+    if (time.isOwned())
+      throw new Error(
+        "Pause the current clock owner before changing freeze state."
+      );
+    const lease = time.acquire();
+    if (lease.isFrozen()) lease.thaw();
+    else lease.freeze();
+    const frozen = lease.isFrozen();
+    this.context.tryResolve(InputKey)?.clearAll();
+    lease.release();
+    return frozen;
+  }
+  canStep() {
+    const time = this.inspector.time;
+    return time.isFrozen() && !time.isOwned();
+  }
+  step(frames) {
+    if (frames !== 1 && frames !== 10)
+      throw new Error(
+        `RuntimeFeedbackHost.step: expected 1 or 10 frames, got ${frames}.`
+      );
+    if (!this.canStep())
+      throw new Error(
+        "Freeze the game and pause any other clock owner before stepping."
+      );
+    const lease = this.inspector.time.acquire();
+    try {
+      this.context.tryResolve(InputKey)?.clearAll();
+      lease.step(frames);
+    } finally {
+      lease.release();
+    }
+  }
+  release() {
+    if (!this.lease) return;
+    this.context.tryResolve(InputKey)?.clearAll();
+    if (!this.wasFrozen) this.lease.thaw();
+    this.lease.release();
+    this.lease = void 0;
+  }
+};
+
+// src/browser/ui/FeedbackLauncher.ts
+var FeedbackLauncher = class {
+  constructor(actions, shortcuts, galleryUrl) {
+    this.actions = actions;
+    this.shortcuts = shortcuts;
+    this.element.className = "yage-feedback-launch";
+    this.element.setAttribute("aria-label", "Feedback controls");
+    this.feedback.textContent = "Leave feedback";
+    const feedbackKey = shortcutLabel(shortcuts.feedback);
+    this.feedback.title = feedbackKey ? `Leave feedback (${feedbackKey})` : "Leave feedback";
+    this.freeze.textContent = "Freeze / resume";
+    const freezeKey = shortcutLabel(shortcuts.freeze);
+    this.freeze.title = freezeKey ? `Freeze / resume (${freezeKey})` : "Freeze / resume";
+    this.feedback.onclick = () => this.actions.open();
+    this.freeze.onclick = () => this.toggle();
+    this.stepFrame.textContent = "+1 frame";
+    this.stepTenFrames.textContent = "+10 frames";
+    for (const [button, binding] of [
+      [this.stepFrame, shortcuts.stepFrame],
+      [this.stepTenFrames, shortcuts.stepTenFrames]
+    ]) {
+      const label = shortcutLabel(binding);
+      button.title = label ? `${button.textContent} (${label})` : button.textContent ?? "";
+    }
+    this.stepFrame.onclick = () => this.step(1);
+    this.stepTenFrames.onclick = () => this.step(10);
+    this.element.append(
+      this.feedback,
+      this.freeze,
+      this.stepFrame,
+      this.stepTenFrames
+    );
+    if (galleryUrl) {
+      const gallery = document.createElement("button");
+      gallery.textContent = "Feedback gallery";
+      gallery.onclick = () => {
+        window.open(galleryUrl, "_blank", "noopener,noreferrer");
+      };
+      this.element.append(gallery);
+    }
+    for (const type of [
+      "keydown",
+      "keyup",
+      "pointerdown",
+      "pointerup",
+      "click"
+    ])
+      this.element.addEventListener(type, (event) => event.stopPropagation());
+    window.addEventListener("keydown", this.keyboard, true);
+    window.addEventListener("keyup", this.keyboard, true);
+    window.addEventListener("blur", this.blur);
+    document.body.append(this.element);
+    this.sync();
+    this.timer = window.setInterval(this.sync, 200);
+  }
+  actions;
+  shortcuts;
+  element = document.createElement("nav");
+  feedback = document.createElement("button");
+  freeze = document.createElement("button");
+  stepFrame = document.createElement("button");
+  stepTenFrames = document.createElement("button");
+  timer;
+  sync = () => {
+    const disabled = !!document.querySelector("dialog[open]") || !this.actions.canStep();
+    this.stepFrame.disabled = disabled;
+    this.stepTenFrames.disabled = disabled;
+  };
+  consumed = /* @__PURE__ */ new Set();
+  blur = () => {
+    this.consumed.clear();
+  };
+  keyboard = (event) => {
+    if (this.consumed.has(event.code)) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      if (event.type === "keyup") this.consumed.delete(event.code);
+      return;
+    }
+    if (event.type !== "keydown" || event.repeat || event.isComposing || document.querySelector("dialog[open]") || event.target instanceof HTMLElement && (event.target.isContentEditable || ["INPUT", "TEXTAREA", "SELECT"].includes(event.target.tagName)))
+      return;
+    const action = shortcutActions.find((key) => {
+      const binding = this.shortcuts[key];
+      return binding && event.code === binding.code && event.ctrlKey === binding.ctrl && event.altKey === binding.alt && event.shiftKey === binding.shift && event.metaKey === binding.meta;
+    });
+    if (!action) return;
+    this.consumed.add(event.code);
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    if (action === "feedback") this.actions.open();
+    else if (action === "freeze") this.toggle();
+    else if (this.actions.canStep()) this.step(action === "stepFrame" ? 1 : 10);
+  };
+  toggle() {
+    try {
+      this.freeze.setAttribute(
+        "aria-pressed",
+        String(this.actions.toggleFreeze())
+      );
+      this.reset();
+    } catch (error) {
+      this.error(error);
+    }
+  }
+  step(frames) {
+    try {
+      if (document.querySelector("dialog[open]")) return;
+      this.actions.step(frames);
+      this.reset();
+    } catch (error) {
+      this.error(error);
+    }
+    this.sync();
+  }
+  error(error) {
+    this.feedback.textContent = error instanceof Error ? error.message : String(error);
+  }
+  reset() {
+    this.feedback.textContent = "Leave feedback";
+    this.sync();
+  }
+  focus() {
+    this.feedback.focus();
+  }
+  destroy() {
+    window.removeEventListener("keydown", this.keyboard, true);
+    window.removeEventListener("keyup", this.keyboard, true);
+    window.removeEventListener("blur", this.blur);
+    this.consumed.clear();
+    window.clearInterval(this.timer);
+    this.element.remove();
+  }
+};
+
+// src/browser/ui/styles.ts
+var CSS = `
+.yage-feedback-launch {position:fixed;right:18px;bottom:18px;z-index:10000;display:flex;flex-wrap:wrap;justify-content:flex-end;max-width:calc(100vw - 36px);gap:6px;opacity:.4;transition:opacity .15s}
+.yage-feedback-launch:hover,.yage-feedback-launch:focus-within {opacity:1}
+.yage-feedback-launch button {padding:8px 12px;border:1px solid #87a8ff;border-radius:8px;background:#203665;color:white;font:14px system-ui;cursor:pointer}
+@media(hover:none){.yage-feedback-launch{opacity:1}}
+.yage-feedback {box-sizing:border-box;width:min(1120px,96vw);max-height:94vh;padding:20px;border:1px solid #536789;border-radius:14px;background:#111c30;color:#edf3ff;font:14px/1.5 system-ui;overflow:auto}
+.yage-feedback::backdrop {background:#030813cc}
+.yage-feedback * {box-sizing:border-box}
+.yage-feedback h2 {margin:0;font-size:22px}.yage-feedback p {color:#bac9e2;margin:6px 0 14px}
+.yage-feedback button,.yage-feedback select,.yage-feedback textarea {font:inherit;border-radius:6px;border:1px solid #536789;background:#20304b;color:#edf3ff;padding:8px}
+.yage-feedback button {cursor:pointer}.yage-feedback button:disabled {opacity:.5;cursor:default}
+.yage-feedback header,.yage-feedback nav {display:flex;gap:10px;align-items:center;justify-content:space-between;margin-bottom:12px}
+.yage-feedback .layout {display:grid;grid-template-columns:minmax(0,1fr) 300px;gap:20px}
+.yage-feedback figure {position:relative;margin:0;align-self:start;line-height:0;touch-action:none;user-select:none;background:#000}
+.yage-feedback img {display:block;width:100%;height:auto;pointer-events:none}
+.yage-feedback .outlines {position:absolute;inset:0;pointer-events:none}
+.yage-feedback .outline {position:absolute;border:2px solid #a4c4ff;background:#78a4ff22}
+.yage-feedback textarea {width:100%;min-height:100px;resize:vertical}.yage-feedback .targets {margin:8px 0}.yage-feedback label {display:block;padding:3px 0}
+.yage-feedback .entity-picker {border:1px solid #536789;border-radius:6px;background:#20304b}
+.yage-feedback .entity-picker summary {padding:8px;cursor:pointer}
+.yage-feedback .entity-picker fieldset {border:0;margin:0;padding:8px;min-width:0}
+.yage-feedback .entity-picker input[type="search"] {width:100%;padding:8px;font:inherit;color:#edf3ff;background:#111c30;border:1px solid #536789;border-radius:4px;margin-bottom:6px}
+.yage-feedback .entity-results {max-height:180px;overflow:auto;overflow-wrap:anywhere}
+.yage-feedback .entity-paging {display:flex;gap:8px;margin:8px 0}
+.yage-feedback .entity-selection {color:#bac9e2;font-size:12px;margin-top:6px;overflow-wrap:anywhere}
+.yage-feedback .status {min-height:24px;color:#b5d4ff;white-space:pre-wrap}.yage-feedback .history {max-height:150px;overflow:auto;padding-left:20px}
+@media(max-width:760px){.yage-feedback .layout{grid-template-columns:1fr}}
+`;
+
+// src/browser/ui/EntityPicker.ts
+var PAGE_SIZE = 50;
+var EntityPicker = class {
+  constructor(root, entities, selected, change) {
+    this.entities = entities;
+    this.selected = selected;
+    this.change = change;
+    this.matches = [...entities];
+    this.details.className = "entity-picker";
+    this.search.type = "search";
+    this.search.placeholder = "Filter by name, ID, or scene";
+    this.search.setAttribute("aria-label", "Filter entities");
+    this.results.className = "entity-results";
+    this.selection.className = "entity-selection";
+    this.count.setAttribute("aria-live", "polite");
+    this.previous.textContent = "Previous";
+    this.next.textContent = "Next";
+    this.clear.textContent = "Clear selection";
+    for (const button of [this.previous, this.next, this.clear])
+      button.type = "button";
+    const paging = document.createElement("div");
+    paging.className = "entity-paging";
+    paging.append(this.previous, this.next);
+    this.fields.append(
+      this.search,
+      this.count,
+      this.results,
+      paging,
+      this.clear
+    );
+    this.details.append(this.summary, this.fields);
+    root.append(this.details, this.selection);
+    this.summary.onclick = (event) => {
+      if (this.disabled) event.preventDefault();
+    };
+    this.details.ontoggle = () => {
+      if (this.details.open) this.search.focus();
+    };
+    this.search.oninput = () => {
+      const terms = this.search.value.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
+      this.matches = this.entities.filter((entity) => {
+        const label = `${entity.name} ${entity.id} ${entity.sceneId}`.toLocaleLowerCase();
+        return terms.every((term) => label.includes(term));
+      });
+      this.page = 0;
+      this.renderResults();
+    };
+    this.search.onkeydown = (event) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        event.stopPropagation();
+        this.details.open = false;
+        this.summary.focus();
+      }
+    };
+    this.previous.onclick = () => {
+      this.page--;
+      this.renderResults();
+    };
+    this.next.onclick = () => {
+      this.page++;
+      this.renderResults();
+    };
+    this.clear.onclick = () => this.change([]);
+    this.renderResults();
+  }
+  entities;
+  selected;
+  change;
+  details = document.createElement("details");
+  summary = document.createElement("summary");
+  search = document.createElement("input");
+  results = document.createElement("div");
+  count = document.createElement("span");
+  previous = document.createElement("button");
+  next = document.createElement("button");
+  clear = document.createElement("button");
+  selection = document.createElement("div");
+  fields = document.createElement("fieldset");
+  page = 0;
+  disabled = false;
+  matches;
+  refresh() {
+    const selected = this.selected();
+    this.summary.textContent = selected.length ? `${selected.length} entities selected` : "Select entities\u2026";
+    this.selection.textContent = selected.length ? selected.slice(0, 3).map((entity) => `${entity.name || "Entity"} (${entity.id})`).join(", ") + (selected.length > 3 ? ` +${selected.length - 3} more` : "") : "No entities selected";
+    this.clear.disabled = selected.length === 0;
+    const ids = new Set(
+      selected.map((entity) => `${entity.sceneId}:${entity.id}`)
+    );
+    for (const input of this.results.querySelectorAll(
+      "input"
+    ))
+      input.checked = ids.has(input.value);
+  }
+  setDisabled(disabled) {
+    this.disabled = disabled;
+    this.fields.disabled = disabled;
+    this.summary.setAttribute("aria-disabled", String(disabled));
+    if (disabled) this.details.open = false;
+  }
+  renderResults() {
+    this.results.replaceChildren();
+    const start = this.page * PAGE_SIZE;
+    const page = this.matches.slice(start, start + PAGE_SIZE);
+    this.count.textContent = page.length ? `${start + 1}\u2013${start + page.length} of ${this.matches.length} matches` : "No matching entities";
+    this.previous.disabled = this.page === 0;
+    this.next.disabled = start + PAGE_SIZE >= this.matches.length;
+    for (const entity of page) {
+      const label = document.createElement("label");
+      const input = document.createElement("input");
+      input.type = "checkbox";
+      input.value = `${entity.sceneId}:${entity.id}`;
+      input.onchange = () => this.change(
+        input.checked ? [...this.selected(), entity] : this.selected().filter((one) => one !== entity)
+      );
+      label.append(
+        input,
+        ` ${entity.name || "Entity"} (${entity.id}) \xB7 ${entity.sceneId}`
+      );
+      this.results.append(label);
+    }
+    this.refresh();
+  }
+};
+
+// src/browser/ui/FeedbackPanel.ts
+var FeedbackPanel = class {
+  constructor(session, shortcuts, galleryUrl) {
+    this.session = session;
+    this.style.textContent = CSS;
+    document.head.append(this.style);
+    this.launcher = new FeedbackLauncher(
+      {
+        open: () => this.open(),
+        toggleFreeze: () => this.session.toggleFreeze(),
+        canStep: () => this.session.canStep(),
+        step: (frames) => this.session.step(frames)
+      },
+      shortcuts,
+      galleryUrl
+    );
+  }
+  session;
+  style = document.createElement("style");
+  launcher;
+  dialog;
+  destroyed = false;
+  open() {
+    if (this.dialog || this.destroyed) return;
+    let observation;
+    try {
+      observation = this.session.open();
+    } catch (error) {
+      this.launcher.error(error);
+      return;
+    }
+    this.launcher.reset();
+    const { capture, image } = observation;
+    const dialog = document.createElement("dialog");
+    this.dialog = dialog;
+    dialog.className = "yage-feedback";
+    dialog.setAttribute("aria-label", "YAGE feedback");
+    dialog.innerHTML = `<header><h2>Leave feedback</h2><button data-close>Return to view</button></header>
+      <p data-frame></p><div class="layout"><figure aria-label="Captured game view"><img alt="Captured game viewport"><div class="outlines"></div></figure>
+      <section><label>Target <select aria-label="Target mode"><option value="global">Whole view</option><option value="entities">Entities</option><option value="area">Area</option></select></label>
+      <div class="targets"></div><label>Comment<textarea aria-label="Comment" maxlength="10000" placeholder="What would you like changed?"></textarea></label>
+      <button data-save>Save comment</button><button data-cancel hidden>Cancel save</button><button data-discard hidden>Discard unsaved draft</button><p class="status" role="status"></p><strong>Comments in this session</strong><ol class="history"></ol></section></div>`;
+    const query = (selector) => {
+      const element = dialog.querySelector(selector);
+      if (!element) throw new Error(`Feedback UI element missing: ${selector}`);
+      return element;
+    };
+    query("[data-frame]").textContent = `Frame ${capture.frame} \xB7 ${capture.width} \xD7 ${capture.height} \xB7 Select a target and add one or more comments.`;
+    query("img").src = image;
+    const figure = query("figure");
+    const select = query("select");
+    const textarea = query("textarea");
+    const save = query("[data-save]");
+    const close = query("[data-close]");
+    const discard = query("[data-discard]");
+    const cancel = query("[data-cancel]");
+    const status = query(".status");
+    const targets = query(".targets");
+    const outlines = query(".outlines");
+    let selected = [];
+    let area;
+    let start;
+    const draw = () => {
+      outlines.replaceChildren();
+      const boxes = select.value === "entities" ? selected.map((entity) => entity.bounds) : select.value === "area" && area ? [area] : [];
+      for (const box of boxes) {
+        const outline = document.createElement("div");
+        outline.className = "outline";
+        Object.assign(outline.style, {
+          left: `${box.x / capture.width * 100}%`,
+          top: `${box.y / capture.height * 100}%`,
+          width: `${box.width / capture.width * 100}%`,
+          height: `${box.height / capture.height * 100}%`
+        });
+        outlines.append(outline);
+      }
+      targets.hidden = select.value !== "entities";
+      picker.refresh();
+    };
+    const picker = new EntityPicker(
+      targets,
+      capture.entities,
+      () => selected,
+      (entities) => {
+        selected = entities;
+        draw();
+      }
+    );
+    select.onchange = () => {
+      area = void 0;
+      selected = [];
+      draw();
+    };
+    const point = (event) => {
+      const box = figure.getBoundingClientRect();
+      return {
+        x: Math.max(
+          0,
+          Math.min(
+            capture.width,
+            (event.clientX - box.left) / box.width * capture.width
+          )
+        ),
+        y: Math.max(
+          0,
+          Math.min(
+            capture.height,
+            (event.clientY - box.top) / box.height * capture.height
+          )
+        )
+      };
+    };
+    figure.onpointerdown = (event) => {
+      if (event.button !== 0 || this.session.pending) return;
+      const p = point(event);
+      if (select.value === "area") {
+        start = p;
+        area = void 0;
+        figure.setPointerCapture(event.pointerId);
+      }
+      if (select.value === "entities") {
+        const candidates = capture.entities.filter(
+          ({ bounds: b }) => p.x >= b.x && p.x <= b.x + b.width && p.y >= b.y && p.y <= b.y + b.height
+        );
+        const entity = candidates.at(-1);
+        if (entity)
+          selected = event.shiftKey ? selected.includes(entity) ? selected.filter((one) => one !== entity) : [...selected, entity] : [entity];
+        else if (!event.shiftKey) selected = [];
+        status.textContent = candidates.length > 1 ? "Overlapping bounds: use the entity dropdown to choose the intended entity." : "";
+      }
+      draw();
+    };
+    figure.onpointermove = (event) => {
+      if (!start) return;
+      const p = point(event);
+      area = {
+        x: Math.min(start.x, p.x),
+        y: Math.min(start.y, p.y),
+        width: Math.abs(p.x - start.x),
+        height: Math.abs(p.y - start.y)
+      };
+      draw();
+    };
+    figure.onpointerup = () => {
+      start = void 0;
+    };
+    figure.onpointercancel = () => {
+      start = void 0;
+      area = void 0;
+      draw();
+    };
+    const history = () => {
+      const list = query(".history");
+      list.replaceChildren();
+      for (const comment of this.session.comments) {
+        const li = document.createElement("li");
+        li.textContent = comment.text;
+        list.append(li);
+      }
+    };
+    const closeDialog = () => {
+      this.close();
+    };
+    close.onclick = closeDialog;
+    dialog.oncancel = (event) => {
+      event.preventDefault();
+      closeDialog();
+    };
+    for (const type of [
+      "keydown",
+      "keyup",
+      "pointerdown",
+      "pointerup",
+      "pointermove",
+      "mousedown",
+      "mouseup",
+      "click",
+      "wheel"
+    ])
+      dialog.addEventListener(type, (event) => event.stopPropagation());
+    const showPending = () => {
+      const draft = this.session.draftComment;
+      if (!draft) return;
+      textarea.value = draft.text;
+      select.value = draft.target.kind;
+      const target = draft.target;
+      if (target.kind === "entities")
+        selected = capture.entities.filter(
+          (entity) => target.entities.some(
+            (one) => one.sceneId === entity.sceneId && one.id === entity.id && one.generation === entity.generation
+          )
+        );
+      if (target.kind === "area") area = { ...target.rect };
+      textarea.disabled = true;
+      select.disabled = true;
+      picker.setDisabled(true);
+      save.disabled = false;
+      save.textContent = "Retry save";
+      discard.hidden = false;
+      cancel.hidden = true;
+      draw();
+    };
+    cancel.onclick = () => {
+      this.session.cancelSave();
+      showPending();
+      status.textContent = "Save cancelled. The draft is retained; retry or return to the view. A server commit may already have completed.";
+    };
+    discard.onclick = () => {
+      this.session.discard();
+      textarea.value = "";
+      textarea.disabled = false;
+      select.disabled = false;
+      close.disabled = false;
+      picker.setDisabled(false);
+      save.textContent = "Save comment";
+      discard.hidden = true;
+      status.textContent = "Draft discarded. Any comment already saved on the server remains there.";
+    };
+    save.onclick = () => {
+      void (async () => {
+        let target = { kind: "global" };
+        if (!this.session.pending) {
+          if (select.value === "entities") {
+            if (!selected.length) {
+              status.textContent = "Select at least one entity.";
+              return;
+            }
+            target = { kind: "entities", entities: [...selected] };
+          } else if (select.value === "area") {
+            if (!area || area.width < 1 || area.height < 1) {
+              status.textContent = "Draw an area on the image.";
+              return;
+            }
+            target = { kind: "area", rect: { ...area } };
+          }
+          if (!textarea.value.trim()) {
+            status.textContent = "Write a comment first.";
+            return;
+          }
+        }
+        save.disabled = true;
+        cancel.hidden = false;
+        select.disabled = true;
+        textarea.disabled = true;
+        picker.setDisabled(true);
+        status.textContent = "Saving\u2026";
+        discard.hidden = true;
+        try {
+          const saved = await this.session.save(textarea.value, target);
+          if (this.dialog !== dialog || !saved) return;
+          textarea.value = "";
+          textarea.disabled = false;
+          select.disabled = false;
+          close.disabled = false;
+          picker.setDisabled(false);
+          save.textContent = "Save comment";
+          status.textContent = "Saved. Add another comment or return to the view.";
+          history();
+        } catch (error) {
+          if (this.dialog !== dialog) return;
+          status.textContent = `${error instanceof Error ? error.message : String(error)}
+The draft is retained. Retry or return to the view.`;
+          save.textContent = "Retry save";
+          discard.hidden = false;
+        }
+        save.disabled = false;
+        cancel.hidden = true;
+      })();
+    };
+    showPending();
+    draw();
+    history();
+    document.body.append(dialog);
+    dialog.showModal();
+  }
+  close() {
+    this.dialog?.remove();
+    this.dialog = void 0;
+    this.session.close();
+    this.launcher.focus();
+  }
+  destroy() {
+    this.destroyed = true;
+    if (this.dialog) this.close();
+    this.launcher.destroy();
+    this.style.remove();
+  }
+};
+
+// src/browser/FeedbackPlugin.ts
+var FeedbackPlugin = class {
+  constructor(options) {
+    this.options = options;
+    this.shortcuts = resolveShortcuts(options.shortcuts);
+    const configured = typeof document === "undefined" ? void 0 : document.querySelector(
+      'meta[name="yage-feedback-server"]'
+    )?.content;
+    this.client = new FeedbackClient(
+      options.server ?? (configured ? new URL(configured, location.href).href : void 0)
+    );
+  }
+  options;
+  name = "feedback";
+  version = "0.0.0";
+  dependencies = ["renderer", "debug"];
+  context;
+  panel;
+  client;
+  shortcuts;
+  install(context) {
+    this.context = context;
+  }
+  onStart() {
+    if (!this.options.enabled || !this.context) return;
+    const host = new RuntimeFeedbackHost(this.context, this.options.context);
+    this.panel = new FeedbackPanel(
+      new FeedbackSession(host, this.client),
+      this.shortcuts,
+      this.client.galleryUrl
+    );
+  }
+  onDestroy() {
+    this.panel?.destroy();
+    this.panel = void 0;
+  }
+};
+export {
+  FeedbackPlugin
+};