@pixelatlarge/peanut-gallery-core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Anna Poirier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @pixelatlarge/peanut-gallery-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared pieces of [Peanut Gallery](https://github.com/PixelAtLarge/peanut-gallery): types, DOM element anchoring (selector, text fingerprint and position fallbacks), the GitHub issue format for review sessions, and the theme. You usually get this as a dependency of `@pixelatlarge/peanut-gallery-widget`, `@pixelatlarge/peanut-gallery-relay` or the `peanut-gallery` CLI.
+
+```ts
+import { createAnchor, resolveAnchor, sessionToIssue, issueToSession } from '@pixelatlarge/peanut-gallery-core';
+```
+
+MIT licensed.

package/dist/index.cjs

@@ -0,0 +1,353 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_FONTS_URL: () => DEFAULT_FONTS_URL,
+  DEFAULT_THEME: () => DEFAULT_THEME,
+  ISSUE_BLOCK_LANG: () => ISSUE_BLOCK_LANG,
+  LABELS: () => LABELS,
+  MAX_STEPS: () => MAX_STEPS,
+  PALETTE: () => PALETTE,
+  buildSelector: () => buildSelector,
+  createAnchor: () => createAnchor,
+  issueToSession: () => issueToSession,
+  newIssueUrl: () => newIssueUrl,
+  normalizeText: () => normalizeText,
+  resolveAnchor: () => resolveAnchor,
+  resolveTheme: () => resolveTheme,
+  sessionToIssue: () => sessionToIssue,
+  stepLabel: () => stepLabel,
+  themeToCssVars: () => themeToCssVars,
+  uid: () => uid
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var MAX_STEPS = 5;
+function stepLabel(step) {
+  const t = (step.textFingerprint ?? "").trim();
+  if (t) return `\u201C${t.length > 40 ? t.slice(0, 39) + "\u2026" : t}\u201D`;
+  return step.selector.length > 60 ? step.tag : step.selector;
+}
+var LABELS = {
+  root: "peanut-gallery",
+  feedback: "peanut-gallery:feedback",
+  proposal: "peanut-gallery:proposal",
+  accepted: "peanut-gallery:accepted",
+  rejected: "peanut-gallery:rejected"
+};
+var ISSUE_BLOCK_LANG = "json peanut-gallery";
+
+// src/anchor.ts
+var MAX_FINGERPRINT = 80;
+function normalizeText(s) {
+  return (s ?? "").replace(/\s+/g, " ").trim().slice(0, MAX_FINGERPRINT);
+}
+function cssEscape(s) {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") return CSS.escape(s);
+  return s.replace(/([^a-zA-Z0-9_-])/g, "\\$1");
+}
+var ATTR_PRIORITY = ["data-testid", "data-test", "data-cy", "data-proto-id", "id", "name", "aria-label"];
+function isGeneratedToken(v) {
+  return /[0-9a-f]{6,}/i.test(v) || /^(css|sc|emotion|svelte|jsx)-/.test(v) || /^_/.test(v) || v.length > 40;
+}
+function segmentFor(el) {
+  for (const attr of ATTR_PRIORITY) {
+    const v = el.getAttribute(attr);
+    if (v && !isGeneratedToken(v)) {
+      const seg2 = attr === "id" ? `#${cssEscape(v)}` : `${el.tagName.toLowerCase()}[${attr}="${v.replace(/"/g, '\\"')}"]`;
+      const doc = el.ownerDocument;
+      try {
+        if (doc.querySelectorAll(seg2).length === 1) return { seg: seg2, unique: true };
+      } catch {
+      }
+    }
+  }
+  const tag = el.tagName.toLowerCase();
+  const stableClasses = Array.from(el.classList).filter((c) => !isGeneratedToken(c)).slice(0, 2);
+  let seg = tag + stableClasses.map((c) => `.${cssEscape(c)}`).join("");
+  const parent = el.parentElement;
+  if (parent) {
+    const siblings = Array.from(parent.children).filter((c) => c.tagName === el.tagName);
+    if (siblings.length > 1) seg += `:nth-of-type(${siblings.indexOf(el) + 1})`;
+  }
+  return { seg, unique: false };
+}
+function buildSelector(el) {
+  const parts = [];
+  let cur = el;
+  while (cur && cur !== cur.ownerDocument.documentElement) {
+    const { seg, unique } = segmentFor(cur);
+    parts.unshift(seg);
+    if (unique) break;
+    cur = cur.parentElement;
+    if (parts.length > 8) break;
+  }
+  return parts.join(" > ");
+}
+function nearestContext(el) {
+  let cur = el;
+  while (cur) {
+    const heading = cur.querySelector('h1, h2, h3, legend, [role="heading"]');
+    if (heading && heading !== el && cur !== el) return normalizeText(heading.textContent);
+    const label = cur.getAttribute?.("aria-label") ?? cur.getAttribute?.("aria-labelledby");
+    if (label && cur !== el) return normalizeText(label);
+    cur = cur.parentElement;
+  }
+  return void 0;
+}
+function createAnchor(el, clientX, clientY) {
+  const r = el.getBoundingClientRect();
+  const win = el.ownerDocument.defaultView;
+  return {
+    selector: buildSelector(el),
+    textFingerprint: normalizeText(el.textContent),
+    tag: el.tagName.toLowerCase(),
+    rect: { x: r.left + win.scrollX, y: r.top + win.scrollY, width: r.width, height: r.height },
+    offset: {
+      x: r.width ? Math.min(1, Math.max(0, (clientX - r.left) / r.width)) : 0.5,
+      y: r.height ? Math.min(1, Math.max(0, (clientY - r.top) / r.height)) : 0.5
+    },
+    context: nearestContext(el)
+  };
+}
+function textScore(el, fp) {
+  if (!fp) return 0.5;
+  const t = normalizeText(el.textContent);
+  if (t === fp) return 1;
+  if (t.includes(fp) || fp.includes(t)) return 0.75;
+  return 0;
+}
+function resolveAnchor(anchor, doc) {
+  let candidates = [];
+  try {
+    candidates = Array.from(doc.querySelectorAll(anchor.selector));
+  } catch {
+    candidates = [];
+  }
+  if (candidates.length === 1) {
+    const s = textScore(candidates[0], anchor.textFingerprint);
+    if (s > 0) return { el: candidates[0], confidence: 0.95 };
+  }
+  if (candidates.length > 1) {
+    const ranked = candidates.map((el) => ({ el, s: textScore(el, anchor.textFingerprint) })).sort((a, b) => b.s - a.s);
+    if (ranked[0].s > 0) return { el: ranked[0].el, confidence: 0.8 };
+  }
+  if (anchor.textFingerprint) {
+    const sameTag = Array.from(doc.getElementsByTagName(anchor.tag));
+    const ranked = sameTag.map((el) => ({ el, s: textScore(el, anchor.textFingerprint) })).sort((a, b) => b.s - a.s);
+    if (ranked[0]?.s >= 0.75) return { el: ranked[0].el, confidence: 0.6 };
+  }
+  if (candidates.length === 1) return { el: candidates[0], confidence: 0.5 };
+  const win = doc.defaultView;
+  if (win && typeof doc.elementFromPoint === "function") {
+    const cx = anchor.rect.x + anchor.rect.width / 2 - win.scrollX;
+    const cy = anchor.rect.y + anchor.rect.height / 2 - win.scrollY;
+    const el = doc.elementFromPoint(cx, cy);
+    if (el) return { el, confidence: 0.3 };
+  }
+  return { el: null, confidence: 0 };
+}
+
+// src/issue-format.ts
+function sessionToIssue(session) {
+  const n = session.annotations.length;
+  const page = safePath(session.annotations[0]?.pageUrl ?? session.prototypeUrl);
+  const title = `Prototype feedback: ${n} comment${n === 1 ? "" : "s"} on ${page}`;
+  const lines = [];
+  lines.push(`**Prototype:** ${session.prototypeUrl}`);
+  if (session.author) lines.push(`**Reviewer:** ${session.author}`);
+  lines.push(`**Session:** \`${session.id}\` \xB7 ${session.createdAt}`);
+  lines.push("");
+  session.annotations.forEach((a, i) => {
+    lines.push(`### ${i + 1}. ${a.kind ? `[${a.kind}] ` : ""}${firstLine(a.text)}`);
+    if (a.text.includes("\n")) lines.push(a.text.split("\n").slice(1).join("\n"));
+    lines.push("");
+    lines.push(`- **Page:** ${a.pageUrl}`);
+    lines.push(`- **Element:** \`${a.anchor.tag ?? "?"}\` \u2192 \`${a.anchor.selector}\``);
+    if (a.anchor.textFingerprint) lines.push(`- **Text:** \u201C${a.anchor.textFingerprint}\u201D`);
+    if (a.anchor.context) lines.push(`- **Near:** ${a.anchor.context}`);
+    if (a.steps?.length) lines.push(`- **Reached by clicking:** ${a.steps.map(stepLabel).join(" \u2192 ")}`);
+    if (a.viewport && Number.isFinite(a.viewport.width) && Number.isFinite(a.viewport.height)) lines.push(`- **Viewport:** ${a.viewport.width}\xD7${a.viewport.height}`);
+    lines.push("");
+  });
+  lines.push("<details><summary>peanut-gallery data (do not edit)</summary>");
+  lines.push("");
+  lines.push("```" + ISSUE_BLOCK_LANG);
+  lines.push(JSON.stringify(session, null, 2));
+  lines.push("```");
+  lines.push("");
+  lines.push("</details>");
+  return { title, body: lines.join("\n") };
+}
+function issueToSession(body) {
+  const re = new RegExp("```" + ISSUE_BLOCK_LANG.replace(/ /g, "\\s+") + "\\s*\\n([\\s\\S]*?)\\n```");
+  const m = body.match(re);
+  if (!m) return null;
+  try {
+    const parsed = JSON.parse(m[1]);
+    if (!Array.isArray(parsed.annotations)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function newIssueUrl(repo, session, labels = [], maxLen = 7500) {
+  const base = `https://github.com/${repo}/issues/new`;
+  const build = (s) => {
+    const { title, body } = sessionToIssue(s);
+    const params = new URLSearchParams({ title, body });
+    if (labels.length) params.set("labels", labels.join(","));
+    return `${base}?${params.toString()}`;
+  };
+  let url = build(session);
+  if (url.length <= maxLen) return url;
+  const slim = {
+    ...session,
+    userAgent: void 0,
+    annotations: session.annotations.map((a) => ({
+      ...a,
+      anchor: {
+        ...a.anchor,
+        context: void 0,
+        textFingerprint: a.anchor.textFingerprint.slice(0, 40),
+        rect: roundRect(a.anchor.rect)
+      },
+      steps: a.steps?.map((st) => ({ ...st, context: void 0, textFingerprint: st.textFingerprint.slice(0, 40), rect: roundRect(st.rect) }))
+    }))
+  };
+  url = build(slim);
+  if (url.length <= maxLen) return url;
+  const kept = [];
+  for (const a of slim.annotations) {
+    const trial = build({ ...slim, annotations: [...kept, a] });
+    if (trial.length > maxLen) break;
+    kept.push(a);
+  }
+  return build({ ...slim, annotations: kept });
+}
+function roundRect(r) {
+  return { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) };
+}
+function firstLine(s) {
+  return s.split("\n")[0].trim().slice(0, 100) || "(no text)";
+}
+function safePath(url) {
+  try {
+    const u = new URL(url);
+    return u.pathname === "/" ? u.host : u.pathname;
+  } catch {
+    return url;
+  }
+}
+function uid(prefix = "") {
+  const rand = typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID().slice(0, 8) : Math.random().toString(36).slice(2, 10);
+  return prefix ? `${prefix}_${rand}` : rand;
+}
+
+// src/theme.ts
+var PALETTE = {
+  conifer: "#1E4D36",
+  emerald: "#0F7B52",
+  wasabi: "#719872",
+  matcha: "#9CC98A",
+  pistachio: "#CFE1B4",
+  seaGlass: "#CDE2F2",
+  hydrangea: "#A6BFE5",
+  harbor: "#40648A",
+  chambray: "#6C8EBD",
+  prep: "#152A4A",
+  sunnyside: "#EAC26C",
+  linen: "#F6F3E4",
+  white: "#FFFFFF",
+  gull: "#A5B0B6",
+  carbon: "#22272B"
+};
+var DEFAULT_THEME = {
+  bg: PALETTE.linen,
+  surface: PALETTE.white,
+  text: PALETTE.carbon,
+  muted: "#5A6268",
+  line: "#DEDCCB",
+  heading: PALETTE.conifer,
+  primary: PALETTE.emerald,
+  primaryHover: "#006340",
+  // emerald 700
+  onPrimary: PALETTE.white,
+  toolbar: PALETTE.conifer,
+  toolbarButton: "#325D46",
+  // conifer 700
+  toolbarButtonHover: "#4E7660",
+  // conifer 600
+  onToolbar: PALETTE.white,
+  accent: PALETTE.sunnyside,
+  onAccent: PALETTE.carbon,
+  highlight: PALETTE.emerald,
+  highlightTint: "rgba(15, 123, 82, 0.10)",
+  pinLow: PALETTE.gull,
+  chip: PALETTE.seaGlass,
+  onChip: PALETTE.prep,
+  count: PALETTE.pistachio,
+  onCount: PALETTE.conifer,
+  ghost: "#EDEBE3",
+  // linen 100
+  ghostHover: "#DBD8CA",
+  // linen 200
+  link: PALETTE.prep,
+  toast: PALETTE.prep,
+  onToast: PALETTE.linen,
+  danger: "#F6E3DF",
+  onDanger: "#9B3426",
+  success: PALETTE.emerald,
+  successTint: "#D4F4E2",
+  // emerald 100
+  fontBody: '"Manrope", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+  fontDisplay: '"Young Serif", Georgia, "Times New Roman", serif',
+  fontMono: '"JetBrains Mono", ui-monospace, Menlo, Consolas, monospace'
+};
+var DEFAULT_FONTS_URL = "https://fonts.googleapis.com/css2?family=Young+Serif&family=Manrope:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap";
+function resolveTheme(overrides) {
+  return { ...DEFAULT_THEME, ...overrides ?? {} };
+}
+var kebab = (s) => s.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
+function themeToCssVars(theme) {
+  return Object.keys(theme).map((k) => `--pg-${kebab(k)}: ${theme[k]};`).join(" ");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_FONTS_URL,
+  DEFAULT_THEME,
+  ISSUE_BLOCK_LANG,
+  LABELS,
+  MAX_STEPS,
+  PALETTE,
+  buildSelector,
+  createAnchor,
+  issueToSession,
+  newIssueUrl,
+  normalizeText,
+  resolveAnchor,
+  resolveTheme,
+  sessionToIssue,
+  stepLabel,
+  themeToCssVars,
+  uid
+});

package/dist/index.d.cts

@@ -0,0 +1,233 @@
+/**
+ * An anchor ties a comment to a DOM element robustly enough to survive
+ * minor markup changes. We store several independent signals and resolve
+ * using the first that matches confidently.
+ */
+interface ElementAnchor {
+    /** Stable-ish CSS selector (prefers data-testid / id / semantic path). */
+    selector: string;
+    /** Normalized, truncated textContent of the element at annotation time. */
+    textFingerprint: string;
+    /** Tag name, lowercase. */
+    tag: string;
+    /** Bounding rect relative to the document at annotation time (CSS px). */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Position of the click inside the element, 0..1 on each axis. */
+    offset: {
+        x: number;
+        y: number;
+    };
+    /** Nearest landmark/heading text to help humans + AI orient. */
+    context?: string;
+}
+interface Annotation {
+    id: string;
+    text: string;
+    anchor: ElementAnchor;
+    /** Page URL (origin + path + search) where the comment was left. */
+    pageUrl: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    createdAt: string;
+    author?: string;
+    /** Optional free-form tag chosen by the reviewer, e.g. "bug", "copy", "layout". */
+    kind?: AnnotationKind;
+    /**
+     * Clicks the reviewer made on this page before leaving the note, oldest first (at most 5,
+     * reset on navigation). Screenshots replay them when the element isn't on the freshly
+     * loaded page, e.g. a note inside a modal. Element identities only, never typed values.
+     */
+    steps?: ElementAnchor[];
+}
+/** Most clicks kept per note. */
+declare const MAX_STEPS = 5;
+/** Short human label for a recorded click, e.g. `“Remove”` or `button#save`. */
+declare function stepLabel(step: Pick<ElementAnchor, 'tag' | 'textFingerprint' | 'selector'>): string;
+type AnnotationKind = 'bug' | 'copy' | 'layout' | 'visual' | 'flow' | 'question' | 'praise';
+interface ReviewSession {
+    id: string;
+    /** Base URL of the hosted prototype. */
+    prototypeUrl: string;
+    annotations: Annotation[];
+    createdAt: string;
+    author?: string;
+    userAgent?: string;
+}
+/** A change proposal derived (by Claude) from one or more annotations. */
+interface Proposal {
+    id: string;
+    title: string;
+    /** One-paragraph rationale written for humans. */
+    summary: string;
+    /** Concrete, implementable instructions for the coding agent. */
+    instructions: string;
+    /** Annotation ids this proposal addresses. */
+    annotationIds: string[];
+    /** Issue numbers the annotations came from. */
+    issueNumbers: number[];
+    /** Pages (URLs) affected; used to decide what to screenshot. */
+    pages: string[];
+    /** Anchors to screenshot close-up, before and after. */
+    focusAnchors: ElementAnchor[];
+    effort: 'small' | 'medium' | 'large';
+    confidence: number;
+    /** Who asked for this (distinct reviewers) — computed from the annotations, not by the model. */
+    support: {
+        reviewers: string[];
+        count: number;
+        annotationCount: number;
+    };
+    /**
+     * Present when reviewers disagree about the same element/change. `apply` skips contested
+     * proposals until one position is chosen (`peanut-gallery decide <id> <n>`), or applies the
+     * model's recommendation with --include-contested.
+     */
+    contested?: {
+        /** Why this is a conflict, one sentence. */
+        reason: string;
+        positions: ProposalPosition[];
+        /** Index into positions the model recommends; `instructions` on the proposal already reflect it. */
+        recommended: number;
+    };
+}
+interface ProposalPosition {
+    summary: string;
+    instructions: string;
+    reviewers: string[];
+    annotationIds: string[];
+}
+interface ProposalRun {
+    proposalId: string;
+    branch: string;
+    prUrl?: string;
+    prNumber?: number;
+    comparePath?: string;
+    screenshots: {
+        label: string;
+        before: string;
+        after: string;
+    }[];
+    status: 'proposed' | 'decision-needed' | 'applied' | 'pr-opened' | 'accepted' | 'rejected';
+}
+declare const LABELS: {
+    readonly root: "peanut-gallery";
+    readonly feedback: "peanut-gallery:feedback";
+    readonly proposal: "peanut-gallery:proposal";
+    readonly accepted: "peanut-gallery:accepted";
+    readonly rejected: "peanut-gallery:rejected";
+};
+declare const ISSUE_BLOCK_LANG = "json peanut-gallery";
+
+declare function normalizeText(s: string | null | undefined): string;
+/** Build a CSS selector that prefers stable, human-meaningful hooks. */
+declare function buildSelector(el: Element): string;
+declare function createAnchor(el: Element, clientX: number, clientY: number): ElementAnchor;
+/**
+ * Resolve an anchor to an element in `doc`. Strategy:
+ * 1. selector matches exactly one element -> use it (verify text loosely)
+ * 2. selector matches several -> pick best text match
+ * 3. selector fails -> search same tag by text fingerprint
+ * 4. fall back to element at the stored rect center
+ */
+declare function resolveAnchor(anchor: ElementAnchor, doc: Document): {
+    el: Element | null;
+    confidence: number;
+};
+
+/** Human-readable + machine-parseable GitHub issue body for a review session. */
+declare function sessionToIssue(session: ReviewSession): {
+    title: string;
+    body: string;
+};
+/** Parse a session back out of an issue body. Returns null if no block found. */
+declare function issueToSession(body: string): ReviewSession | null;
+/**
+ * Build a `/issues/new` URL. GitHub caps URLs around 8k chars; if the body
+ * is too long we trim the machine block to the essentials and note it.
+ */
+declare function newIssueUrl(repo: string, session: ReviewSession, labels?: string[], maxLen?: number): string;
+declare function uid(prefix?: string): string;
+
+/**
+ * Default look: the "Conifer, Prep & Wasabi" palette.
+ * Deep forest and navy grounds, creamy greens, coastal blues, one warm yellow accent, carbon text.
+ *
+ * Every role can be overridden (widget: `theme` option; CLI: `theme` in peanut-gallery.config.json),
+ * so teams can match their own design system.
+ */
+declare const PALETTE: {
+    readonly conifer: "#1E4D36";
+    readonly emerald: "#0F7B52";
+    readonly wasabi: "#719872";
+    readonly matcha: "#9CC98A";
+    readonly pistachio: "#CFE1B4";
+    readonly seaGlass: "#CDE2F2";
+    readonly hydrangea: "#A6BFE5";
+    readonly harbor: "#40648A";
+    readonly chambray: "#6C8EBD";
+    readonly prep: "#152A4A";
+    readonly sunnyside: "#EAC26C";
+    readonly linen: "#F6F3E4";
+    readonly white: "#FFFFFF";
+    readonly gull: "#A5B0B6";
+    readonly carbon: "#22272B";
+};
+interface Theme {
+    /** Page / report background */
+    bg: string;
+    /** Cards, popovers */
+    surface: string;
+    text: string;
+    muted: string;
+    line: string;
+    heading: string;
+    /** Primary actions (Add note, Submit) */
+    primary: string;
+    primaryHover: string;
+    onPrimary: string;
+    /** Floating toolbar */
+    toolbar: string;
+    toolbarButton: string;
+    toolbarButtonHover: string;
+    onToolbar: string;
+    /** "Commenting" state, pins, element outlines in screenshots */
+    accent: string;
+    onAccent: string;
+    /** Hover outline on the element being picked */
+    highlight: string;
+    highlightTint: string;
+    pinLow: string;
+    /** Kind tags (bug, copy, layout…) */
+    chip: string;
+    onChip: string;
+    /** Count badge on the Review button */
+    count: string;
+    onCount: string;
+    ghost: string;
+    ghostHover: string;
+    link: string;
+    toast: string;
+    onToast: string;
+    danger: string;
+    onDanger: string;
+    success: string;
+    successTint: string;
+    fontBody: string;
+    fontDisplay: string;
+    fontMono: string;
+}
+declare const DEFAULT_THEME: Theme;
+/** Google Fonts stylesheet for the default type (Manrope, Young Serif, JetBrains Mono). */
+declare const DEFAULT_FONTS_URL = "https://fonts.googleapis.com/css2?family=Young+Serif&family=Manrope:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap";
+declare function resolveTheme(overrides?: Partial<Theme>): Theme;
+/** `--pg-primary: #0F7B52; …` for every role. */
+declare function themeToCssVars(theme: Theme): string;
+
+export { type Annotation, type AnnotationKind, DEFAULT_FONTS_URL, DEFAULT_THEME, type ElementAnchor, ISSUE_BLOCK_LANG, LABELS, MAX_STEPS, PALETTE, type Proposal, type ProposalPosition, type ProposalRun, type ReviewSession, type Theme, buildSelector, createAnchor, issueToSession, newIssueUrl, normalizeText, resolveAnchor, resolveTheme, sessionToIssue, stepLabel, themeToCssVars, uid };

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+/**
+ * An anchor ties a comment to a DOM element robustly enough to survive
+ * minor markup changes. We store several independent signals and resolve
+ * using the first that matches confidently.
+ */
+interface ElementAnchor {
+    /** Stable-ish CSS selector (prefers data-testid / id / semantic path). */
+    selector: string;
+    /** Normalized, truncated textContent of the element at annotation time. */
+    textFingerprint: string;
+    /** Tag name, lowercase. */
+    tag: string;
+    /** Bounding rect relative to the document at annotation time (CSS px). */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Position of the click inside the element, 0..1 on each axis. */
+    offset: {
+        x: number;
+        y: number;
+    };
+    /** Nearest landmark/heading text to help humans + AI orient. */
+    context?: string;
+}
+interface Annotation {
+    id: string;
+    text: string;
+    anchor: ElementAnchor;
+    /** Page URL (origin + path + search) where the comment was left. */
+    pageUrl: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    createdAt: string;
+    author?: string;
+    /** Optional free-form tag chosen by the reviewer, e.g. "bug", "copy", "layout". */
+    kind?: AnnotationKind;
+    /**
+     * Clicks the reviewer made on this page before leaving the note, oldest first (at most 5,
+     * reset on navigation). Screenshots replay them when the element isn't on the freshly
+     * loaded page, e.g. a note inside a modal. Element identities only, never typed values.
+     */
+    steps?: ElementAnchor[];
+}
+/** Most clicks kept per note. */
+declare const MAX_STEPS = 5;
+/** Short human label for a recorded click, e.g. `“Remove”` or `button#save`. */
+declare function stepLabel(step: Pick<ElementAnchor, 'tag' | 'textFingerprint' | 'selector'>): string;
+type AnnotationKind = 'bug' | 'copy' | 'layout' | 'visual' | 'flow' | 'question' | 'praise';
+interface ReviewSession {
+    id: string;
+    /** Base URL of the hosted prototype. */
+    prototypeUrl: string;
+    annotations: Annotation[];
+    createdAt: string;
+    author?: string;
+    userAgent?: string;
+}
+/** A change proposal derived (by Claude) from one or more annotations. */
+interface Proposal {
+    id: string;
+    title: string;
+    /** One-paragraph rationale written for humans. */
+    summary: string;
+    /** Concrete, implementable instructions for the coding agent. */
+    instructions: string;
+    /** Annotation ids this proposal addresses. */
+    annotationIds: string[];
+    /** Issue numbers the annotations came from. */
+    issueNumbers: number[];
+    /** Pages (URLs) affected; used to decide what to screenshot. */
+    pages: string[];
+    /** Anchors to screenshot close-up, before and after. */
+    focusAnchors: ElementAnchor[];
+    effort: 'small' | 'medium' | 'large';
+    confidence: number;
+    /** Who asked for this (distinct reviewers) — computed from the annotations, not by the model. */
+    support: {
+        reviewers: string[];
+        count: number;
+        annotationCount: number;
+    };
+    /**
+     * Present when reviewers disagree about the same element/change. `apply` skips contested
+     * proposals until one position is chosen (`peanut-gallery decide <id> <n>`), or applies the
+     * model's recommendation with --include-contested.
+     */
+    contested?: {
+        /** Why this is a conflict, one sentence. */
+        reason: string;
+        positions: ProposalPosition[];
+        /** Index into positions the model recommends; `instructions` on the proposal already reflect it. */
+        recommended: number;
+    };
+}
+interface ProposalPosition {
+    summary: string;
+    instructions: string;
+    reviewers: string[];
+    annotationIds: string[];
+}
+interface ProposalRun {
+    proposalId: string;
+    branch: string;
+    prUrl?: string;
+    prNumber?: number;
+    comparePath?: string;
+    screenshots: {
+        label: string;
+        before: string;
+        after: string;
+    }[];
+    status: 'proposed' | 'decision-needed' | 'applied' | 'pr-opened' | 'accepted' | 'rejected';
+}
+declare const LABELS: {
+    readonly root: "peanut-gallery";
+    readonly feedback: "peanut-gallery:feedback";
+    readonly proposal: "peanut-gallery:proposal";
+    readonly accepted: "peanut-gallery:accepted";
+    readonly rejected: "peanut-gallery:rejected";
+};
+declare const ISSUE_BLOCK_LANG = "json peanut-gallery";
+
+declare function normalizeText(s: string | null | undefined): string;
+/** Build a CSS selector that prefers stable, human-meaningful hooks. */
+declare function buildSelector(el: Element): string;
+declare function createAnchor(el: Element, clientX: number, clientY: number): ElementAnchor;
+/**
+ * Resolve an anchor to an element in `doc`. Strategy:
+ * 1. selector matches exactly one element -> use it (verify text loosely)
+ * 2. selector matches several -> pick best text match
+ * 3. selector fails -> search same tag by text fingerprint
+ * 4. fall back to element at the stored rect center
+ */
+declare function resolveAnchor(anchor: ElementAnchor, doc: Document): {
+    el: Element | null;
+    confidence: number;
+};
+
+/** Human-readable + machine-parseable GitHub issue body for a review session. */
+declare function sessionToIssue(session: ReviewSession): {
+    title: string;
+    body: string;
+};
+/** Parse a session back out of an issue body. Returns null if no block found. */
+declare function issueToSession(body: string): ReviewSession | null;
+/**
+ * Build a `/issues/new` URL. GitHub caps URLs around 8k chars; if the body
+ * is too long we trim the machine block to the essentials and note it.
+ */
+declare function newIssueUrl(repo: string, session: ReviewSession, labels?: string[], maxLen?: number): string;
+declare function uid(prefix?: string): string;
+
+/**
+ * Default look: the "Conifer, Prep & Wasabi" palette.
+ * Deep forest and navy grounds, creamy greens, coastal blues, one warm yellow accent, carbon text.
+ *
+ * Every role can be overridden (widget: `theme` option; CLI: `theme` in peanut-gallery.config.json),
+ * so teams can match their own design system.
+ */
+declare const PALETTE: {
+    readonly conifer: "#1E4D36";
+    readonly emerald: "#0F7B52";
+    readonly wasabi: "#719872";
+    readonly matcha: "#9CC98A";
+    readonly pistachio: "#CFE1B4";
+    readonly seaGlass: "#CDE2F2";
+    readonly hydrangea: "#A6BFE5";
+    readonly harbor: "#40648A";
+    readonly chambray: "#6C8EBD";
+    readonly prep: "#152A4A";
+    readonly sunnyside: "#EAC26C";
+    readonly linen: "#F6F3E4";
+    readonly white: "#FFFFFF";
+    readonly gull: "#A5B0B6";
+    readonly carbon: "#22272B";
+};
+interface Theme {
+    /** Page / report background */
+    bg: string;
+    /** Cards, popovers */
+    surface: string;
+    text: string;
+    muted: string;
+    line: string;
+    heading: string;
+    /** Primary actions (Add note, Submit) */
+    primary: string;
+    primaryHover: string;
+    onPrimary: string;
+    /** Floating toolbar */
+    toolbar: string;
+    toolbarButton: string;
+    toolbarButtonHover: string;
+    onToolbar: string;
+    /** "Commenting" state, pins, element outlines in screenshots */
+    accent: string;
+    onAccent: string;
+    /** Hover outline on the element being picked */
+    highlight: string;
+    highlightTint: string;
+    pinLow: string;
+    /** Kind tags (bug, copy, layout…) */
+    chip: string;
+    onChip: string;
+    /** Count badge on the Review button */
+    count: string;
+    onCount: string;
+    ghost: string;
+    ghostHover: string;
+    link: string;
+    toast: string;
+    onToast: string;
+    danger: string;
+    onDanger: string;
+    success: string;
+    successTint: string;
+    fontBody: string;
+    fontDisplay: string;
+    fontMono: string;
+}
+declare const DEFAULT_THEME: Theme;
+/** Google Fonts stylesheet for the default type (Manrope, Young Serif, JetBrains Mono). */
+declare const DEFAULT_FONTS_URL = "https://fonts.googleapis.com/css2?family=Young+Serif&family=Manrope:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap";
+declare function resolveTheme(overrides?: Partial<Theme>): Theme;
+/** `--pg-primary: #0F7B52; …` for every role. */
+declare function themeToCssVars(theme: Theme): string;
+
+export { type Annotation, type AnnotationKind, DEFAULT_FONTS_URL, DEFAULT_THEME, type ElementAnchor, ISSUE_BLOCK_LANG, LABELS, MAX_STEPS, PALETTE, type Proposal, type ProposalPosition, type ProposalRun, type ReviewSession, type Theme, buildSelector, createAnchor, issueToSession, newIssueUrl, normalizeText, resolveAnchor, resolveTheme, sessionToIssue, stepLabel, themeToCssVars, uid };

package/dist/index.js

@@ -0,0 +1,310 @@
+// src/types.ts
+var MAX_STEPS = 5;
+function stepLabel(step) {
+  const t = (step.textFingerprint ?? "").trim();
+  if (t) return `\u201C${t.length > 40 ? t.slice(0, 39) + "\u2026" : t}\u201D`;
+  return step.selector.length > 60 ? step.tag : step.selector;
+}
+var LABELS = {
+  root: "peanut-gallery",
+  feedback: "peanut-gallery:feedback",
+  proposal: "peanut-gallery:proposal",
+  accepted: "peanut-gallery:accepted",
+  rejected: "peanut-gallery:rejected"
+};
+var ISSUE_BLOCK_LANG = "json peanut-gallery";
+
+// src/anchor.ts
+var MAX_FINGERPRINT = 80;
+function normalizeText(s) {
+  return (s ?? "").replace(/\s+/g, " ").trim().slice(0, MAX_FINGERPRINT);
+}
+function cssEscape(s) {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") return CSS.escape(s);
+  return s.replace(/([^a-zA-Z0-9_-])/g, "\\$1");
+}
+var ATTR_PRIORITY = ["data-testid", "data-test", "data-cy", "data-proto-id", "id", "name", "aria-label"];
+function isGeneratedToken(v) {
+  return /[0-9a-f]{6,}/i.test(v) || /^(css|sc|emotion|svelte|jsx)-/.test(v) || /^_/.test(v) || v.length > 40;
+}
+function segmentFor(el) {
+  for (const attr of ATTR_PRIORITY) {
+    const v = el.getAttribute(attr);
+    if (v && !isGeneratedToken(v)) {
+      const seg2 = attr === "id" ? `#${cssEscape(v)}` : `${el.tagName.toLowerCase()}[${attr}="${v.replace(/"/g, '\\"')}"]`;
+      const doc = el.ownerDocument;
+      try {
+        if (doc.querySelectorAll(seg2).length === 1) return { seg: seg2, unique: true };
+      } catch {
+      }
+    }
+  }
+  const tag = el.tagName.toLowerCase();
+  const stableClasses = Array.from(el.classList).filter((c) => !isGeneratedToken(c)).slice(0, 2);
+  let seg = tag + stableClasses.map((c) => `.${cssEscape(c)}`).join("");
+  const parent = el.parentElement;
+  if (parent) {
+    const siblings = Array.from(parent.children).filter((c) => c.tagName === el.tagName);
+    if (siblings.length > 1) seg += `:nth-of-type(${siblings.indexOf(el) + 1})`;
+  }
+  return { seg, unique: false };
+}
+function buildSelector(el) {
+  const parts = [];
+  let cur = el;
+  while (cur && cur !== cur.ownerDocument.documentElement) {
+    const { seg, unique } = segmentFor(cur);
+    parts.unshift(seg);
+    if (unique) break;
+    cur = cur.parentElement;
+    if (parts.length > 8) break;
+  }
+  return parts.join(" > ");
+}
+function nearestContext(el) {
+  let cur = el;
+  while (cur) {
+    const heading = cur.querySelector('h1, h2, h3, legend, [role="heading"]');
+    if (heading && heading !== el && cur !== el) return normalizeText(heading.textContent);
+    const label = cur.getAttribute?.("aria-label") ?? cur.getAttribute?.("aria-labelledby");
+    if (label && cur !== el) return normalizeText(label);
+    cur = cur.parentElement;
+  }
+  return void 0;
+}
+function createAnchor(el, clientX, clientY) {
+  const r = el.getBoundingClientRect();
+  const win = el.ownerDocument.defaultView;
+  return {
+    selector: buildSelector(el),
+    textFingerprint: normalizeText(el.textContent),
+    tag: el.tagName.toLowerCase(),
+    rect: { x: r.left + win.scrollX, y: r.top + win.scrollY, width: r.width, height: r.height },
+    offset: {
+      x: r.width ? Math.min(1, Math.max(0, (clientX - r.left) / r.width)) : 0.5,
+      y: r.height ? Math.min(1, Math.max(0, (clientY - r.top) / r.height)) : 0.5
+    },
+    context: nearestContext(el)
+  };
+}
+function textScore(el, fp) {
+  if (!fp) return 0.5;
+  const t = normalizeText(el.textContent);
+  if (t === fp) return 1;
+  if (t.includes(fp) || fp.includes(t)) return 0.75;
+  return 0;
+}
+function resolveAnchor(anchor, doc) {
+  let candidates = [];
+  try {
+    candidates = Array.from(doc.querySelectorAll(anchor.selector));
+  } catch {
+    candidates = [];
+  }
+  if (candidates.length === 1) {
+    const s = textScore(candidates[0], anchor.textFingerprint);
+    if (s > 0) return { el: candidates[0], confidence: 0.95 };
+  }
+  if (candidates.length > 1) {
+    const ranked = candidates.map((el) => ({ el, s: textScore(el, anchor.textFingerprint) })).sort((a, b) => b.s - a.s);
+    if (ranked[0].s > 0) return { el: ranked[0].el, confidence: 0.8 };
+  }
+  if (anchor.textFingerprint) {
+    const sameTag = Array.from(doc.getElementsByTagName(anchor.tag));
+    const ranked = sameTag.map((el) => ({ el, s: textScore(el, anchor.textFingerprint) })).sort((a, b) => b.s - a.s);
+    if (ranked[0]?.s >= 0.75) return { el: ranked[0].el, confidence: 0.6 };
+  }
+  if (candidates.length === 1) return { el: candidates[0], confidence: 0.5 };
+  const win = doc.defaultView;
+  if (win && typeof doc.elementFromPoint === "function") {
+    const cx = anchor.rect.x + anchor.rect.width / 2 - win.scrollX;
+    const cy = anchor.rect.y + anchor.rect.height / 2 - win.scrollY;
+    const el = doc.elementFromPoint(cx, cy);
+    if (el) return { el, confidence: 0.3 };
+  }
+  return { el: null, confidence: 0 };
+}
+
+// src/issue-format.ts
+function sessionToIssue(session) {
+  const n = session.annotations.length;
+  const page = safePath(session.annotations[0]?.pageUrl ?? session.prototypeUrl);
+  const title = `Prototype feedback: ${n} comment${n === 1 ? "" : "s"} on ${page}`;
+  const lines = [];
+  lines.push(`**Prototype:** ${session.prototypeUrl}`);
+  if (session.author) lines.push(`**Reviewer:** ${session.author}`);
+  lines.push(`**Session:** \`${session.id}\` \xB7 ${session.createdAt}`);
+  lines.push("");
+  session.annotations.forEach((a, i) => {
+    lines.push(`### ${i + 1}. ${a.kind ? `[${a.kind}] ` : ""}${firstLine(a.text)}`);
+    if (a.text.includes("\n")) lines.push(a.text.split("\n").slice(1).join("\n"));
+    lines.push("");
+    lines.push(`- **Page:** ${a.pageUrl}`);
+    lines.push(`- **Element:** \`${a.anchor.tag ?? "?"}\` \u2192 \`${a.anchor.selector}\``);
+    if (a.anchor.textFingerprint) lines.push(`- **Text:** \u201C${a.anchor.textFingerprint}\u201D`);
+    if (a.anchor.context) lines.push(`- **Near:** ${a.anchor.context}`);
+    if (a.steps?.length) lines.push(`- **Reached by clicking:** ${a.steps.map(stepLabel).join(" \u2192 ")}`);
+    if (a.viewport && Number.isFinite(a.viewport.width) && Number.isFinite(a.viewport.height)) lines.push(`- **Viewport:** ${a.viewport.width}\xD7${a.viewport.height}`);
+    lines.push("");
+  });
+  lines.push("<details><summary>peanut-gallery data (do not edit)</summary>");
+  lines.push("");
+  lines.push("```" + ISSUE_BLOCK_LANG);
+  lines.push(JSON.stringify(session, null, 2));
+  lines.push("```");
+  lines.push("");
+  lines.push("</details>");
+  return { title, body: lines.join("\n") };
+}
+function issueToSession(body) {
+  const re = new RegExp("```" + ISSUE_BLOCK_LANG.replace(/ /g, "\\s+") + "\\s*\\n([\\s\\S]*?)\\n```");
+  const m = body.match(re);
+  if (!m) return null;
+  try {
+    const parsed = JSON.parse(m[1]);
+    if (!Array.isArray(parsed.annotations)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function newIssueUrl(repo, session, labels = [], maxLen = 7500) {
+  const base = `https://github.com/${repo}/issues/new`;
+  const build = (s) => {
+    const { title, body } = sessionToIssue(s);
+    const params = new URLSearchParams({ title, body });
+    if (labels.length) params.set("labels", labels.join(","));
+    return `${base}?${params.toString()}`;
+  };
+  let url = build(session);
+  if (url.length <= maxLen) return url;
+  const slim = {
+    ...session,
+    userAgent: void 0,
+    annotations: session.annotations.map((a) => ({
+      ...a,
+      anchor: {
+        ...a.anchor,
+        context: void 0,
+        textFingerprint: a.anchor.textFingerprint.slice(0, 40),
+        rect: roundRect(a.anchor.rect)
+      },
+      steps: a.steps?.map((st) => ({ ...st, context: void 0, textFingerprint: st.textFingerprint.slice(0, 40), rect: roundRect(st.rect) }))
+    }))
+  };
+  url = build(slim);
+  if (url.length <= maxLen) return url;
+  const kept = [];
+  for (const a of slim.annotations) {
+    const trial = build({ ...slim, annotations: [...kept, a] });
+    if (trial.length > maxLen) break;
+    kept.push(a);
+  }
+  return build({ ...slim, annotations: kept });
+}
+function roundRect(r) {
+  return { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) };
+}
+function firstLine(s) {
+  return s.split("\n")[0].trim().slice(0, 100) || "(no text)";
+}
+function safePath(url) {
+  try {
+    const u = new URL(url);
+    return u.pathname === "/" ? u.host : u.pathname;
+  } catch {
+    return url;
+  }
+}
+function uid(prefix = "") {
+  const rand = typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID().slice(0, 8) : Math.random().toString(36).slice(2, 10);
+  return prefix ? `${prefix}_${rand}` : rand;
+}
+
+// src/theme.ts
+var PALETTE = {
+  conifer: "#1E4D36",
+  emerald: "#0F7B52",
+  wasabi: "#719872",
+  matcha: "#9CC98A",
+  pistachio: "#CFE1B4",
+  seaGlass: "#CDE2F2",
+  hydrangea: "#A6BFE5",
+  harbor: "#40648A",
+  chambray: "#6C8EBD",
+  prep: "#152A4A",
+  sunnyside: "#EAC26C",
+  linen: "#F6F3E4",
+  white: "#FFFFFF",
+  gull: "#A5B0B6",
+  carbon: "#22272B"
+};
+var DEFAULT_THEME = {
+  bg: PALETTE.linen,
+  surface: PALETTE.white,
+  text: PALETTE.carbon,
+  muted: "#5A6268",
+  line: "#DEDCCB",
+  heading: PALETTE.conifer,
+  primary: PALETTE.emerald,
+  primaryHover: "#006340",
+  // emerald 700
+  onPrimary: PALETTE.white,
+  toolbar: PALETTE.conifer,
+  toolbarButton: "#325D46",
+  // conifer 700
+  toolbarButtonHover: "#4E7660",
+  // conifer 600
+  onToolbar: PALETTE.white,
+  accent: PALETTE.sunnyside,
+  onAccent: PALETTE.carbon,
+  highlight: PALETTE.emerald,
+  highlightTint: "rgba(15, 123, 82, 0.10)",
+  pinLow: PALETTE.gull,
+  chip: PALETTE.seaGlass,
+  onChip: PALETTE.prep,
+  count: PALETTE.pistachio,
+  onCount: PALETTE.conifer,
+  ghost: "#EDEBE3",
+  // linen 100
+  ghostHover: "#DBD8CA",
+  // linen 200
+  link: PALETTE.prep,
+  toast: PALETTE.prep,
+  onToast: PALETTE.linen,
+  danger: "#F6E3DF",
+  onDanger: "#9B3426",
+  success: PALETTE.emerald,
+  successTint: "#D4F4E2",
+  // emerald 100
+  fontBody: '"Manrope", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+  fontDisplay: '"Young Serif", Georgia, "Times New Roman", serif',
+  fontMono: '"JetBrains Mono", ui-monospace, Menlo, Consolas, monospace'
+};
+var DEFAULT_FONTS_URL = "https://fonts.googleapis.com/css2?family=Young+Serif&family=Manrope:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap";
+function resolveTheme(overrides) {
+  return { ...DEFAULT_THEME, ...overrides ?? {} };
+}
+var kebab = (s) => s.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
+function themeToCssVars(theme) {
+  return Object.keys(theme).map((k) => `--pg-${kebab(k)}: ${theme[k]};`).join(" ");
+}
+export {
+  DEFAULT_FONTS_URL,
+  DEFAULT_THEME,
+  ISSUE_BLOCK_LANG,
+  LABELS,
+  MAX_STEPS,
+  PALETTE,
+  buildSelector,
+  createAnchor,
+  issueToSession,
+  newIssueUrl,
+  normalizeText,
+  resolveAnchor,
+  resolveTheme,
+  sessionToIssue,
+  stepLabel,
+  themeToCssVars,
+  uid
+};

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@pixelatlarge/peanut-gallery-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Shared types, DOM anchoring, and GitHub issue serialization for peanut-gallery.",
+  "keywords": [
+    "prototype",
+    "feedback",
+    "annotation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PixelAtLarge/peanut-gallery.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/PixelAtLarge/peanut-gallery#readme",
+  "bugs": {
+    "url": "https://github.com/PixelAtLarge/peanut-gallery/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}