@plannotator/ui 0.22.0

package/utils/quickLabels.ts

@@ -0,0 +1,77 @@
+/**
+ * Quick Labels — preset annotation labels for one-click feedback
+ *
+ * Labels are stored in cookies (same pattern as other settings)
+ * so they persist across different port-based sessions.
+ */
+
+import { storage } from './storage';
+
+const STORAGE_KEY = 'plannotator-quick-labels';
+
+export interface QuickLabel {
+  id: string;     // kebab-case identifier e.g. "needs-tests"
+  emoji: string;  // single emoji e.g. "🧪"
+  text: string;   // display text e.g. "Needs tests"
+  color: string;  // key into LABEL_COLOR_MAP
+  tip?: string;   // optional instruction injected into feedback for the agent
+}
+
+/** Inline styles for label colors (avoids Tailwind dynamic class purging) */
+export const LABEL_COLOR_MAP: Record<string, { bg: string; text: string; darkText: string }> = {
+  blue:   { bg: 'rgba(59,130,246,0.15)',  text: '#2563eb', darkText: '#60a5fa' },
+  red:    { bg: 'rgba(239,68,68,0.15)',   text: '#dc2626', darkText: '#f87171' },
+  orange: { bg: 'rgba(249,115,22,0.15)',  text: '#ea580c', darkText: '#fb923c' },
+  yellow: { bg: 'rgba(234,179,8,0.15)',   text: '#ca8a04', darkText: '#facc15' },
+  purple: { bg: 'rgba(147,51,234,0.15)',  text: '#9333ea', darkText: '#a78bfa' },
+  teal:   { bg: 'rgba(20,184,166,0.15)',  text: '#0d9488', darkText: '#2dd4bf' },
+  pink:   { bg: 'rgba(236,72,153,0.15)',  text: '#db2777', darkText: '#f472b6' },
+  green:  { bg: 'rgba(34,197,94,0.15)',   text: '#16a34a', darkText: '#4ade80' },
+  cyan:   { bg: 'rgba(8,145,178,0.15)',   text: '#0891b2', darkText: '#22d3ee' },
+  amber:  { bg: 'rgba(180,83,9,0.15)',    text: '#b45309', darkText: '#fbbf24' },
+};
+
+export const DEFAULT_QUICK_LABELS: QuickLabel[] = [
+  { id: 'clarify-this',            emoji: '❓', text: 'Clarify this',            color: 'yellow' },
+  { id: 'missing-overview',        emoji: '🗺️', text: 'Missing overview',        color: 'purple', tip: 'Provide a narrative overview of what is being built, why it is being built, and how it will be built. Add this before the implementation details.' },
+  { id: 'verify-this',             emoji: '🔍', text: 'Verify this',             color: 'orange', tip: 'This seems like an assumption. Verify by reading the actual code before proceeding.' },
+  { id: 'give-me-an-example',      emoji: '🔬', text: 'Give me an example',      color: 'cyan', tip: 'This is too abstract. Show a before/after, a sample input/output, or a specific scenario so I can see how this actually works.' },
+  { id: 'match-existing-patterns',  emoji: '🧬', text: 'Match existing patterns',  color: 'teal', tip: 'Search the codebase for existing patterns, components, or utilities that already solve this. Reuse what exists rather than introducing a new approach.' },
+  { id: 'consider-alternatives',    emoji: '🔄', text: 'Consider alternatives',    color: 'pink', tip: 'Propose 2-3 alternative approaches with trade-offs based on the actual codebase. Also check the Plannotator plans directory (PLANNOTATOR_DATA_DIR or ~/.plannotator/plans/) for prior plan versions that may have already explored or rejected similar approaches.' },
+  { id: 'ensure-no-regression',     emoji: '📉', text: 'Ensure no regression',     color: 'amber', tip: 'Verify that this change will not break existing behavior. Identify what could regress and how to protect against it.' },
+  { id: 'out-of-scope',            emoji: '🚫', text: 'Out of scope',            color: 'red', tip: 'This is not part of the current task. Remove it and stay focused on what was actually requested.' },
+  { id: 'needs-tests',             emoji: '🧪', text: 'Needs tests',             color: 'blue' },
+  { id: 'nice-approach',           emoji: '👍', text: 'Nice approach',           color: 'green' },
+];
+
+export function getQuickLabels(): QuickLabel[] {
+  const raw = storage.getItem(STORAGE_KEY);
+  if (!raw) return DEFAULT_QUICK_LABELS;
+  try {
+    const parsed = JSON.parse(raw) as QuickLabel[];
+    return parsed.length > 0 ? parsed : DEFAULT_QUICK_LABELS;
+  } catch {
+    return DEFAULT_QUICK_LABELS;
+  }
+}
+
+export function saveQuickLabels(labels: QuickLabel[]): void {
+  storage.setItem(STORAGE_KEY, JSON.stringify(labels));
+}
+
+export function resetQuickLabels(): void {
+  storage.removeItem(STORAGE_KEY);
+}
+
+/** Find a configured label whose "emoji text" matches an annotation's text field */
+export function findLabelByText(annotationText: string): QuickLabel | undefined {
+  return getQuickLabels().find(l => `${l.emoji} ${l.text}` === annotationText);
+}
+
+/** Get color styles for a label, respecting dark mode */
+export function getLabelColors(color: string): { bg: string; text: string } {
+  const colors = LABEL_COLOR_MAP[color];
+  if (!colors) return { bg: 'rgba(128,128,128,0.15)', text: '#666' };
+  const isDark = document.documentElement.classList.contains('dark');
+  return { bg: colors.bg, text: isDark ? colors.darkText : colors.text };
+}

package/utils/reviewAgentInstructions.ts

@@ -0,0 +1,182 @@
+/**
+ * Builds the clipboard payload that teaches an external agent (Claude Code,
+ * Codex, custom scripts, etc.) how to post annotations into a live Plannotator
+ * **code-review** session via the /api/external-annotations HTTP API.
+ *
+ * The body is intentionally short so an agent can read it top-to-bottom and
+ * start posting in under a minute. Edit freely — this file is the single source
+ * of truth for the review agent-facing contract surface.
+ *
+ * The only dynamic value is `origin`, which is interpolated at click time from
+ * `window.location.origin` so the agent gets the correct base URL whether the
+ * server is running on a random local port or the fixed remote port (19432).
+ */
+export function buildReviewAgentInstructions(origin: string): string {
+  return `# Plannotator — External Review Comments
+
+You can submit review feedback on the user's current code-review session by POSTing annotations to a small HTTP API. The user will see them immediately — pinned inline to the relevant diff lines, plus entries in a sidebar — and can accept, edit, or delete them.
+
+This is one-way submission. Any tool can post: linters, agents, scripts. The user does not see who you are unless you tell them via \`text\` or \`author\`.
+
+## Base URL
+${origin}
+
+All endpoints below are relative to that base. No authentication.
+
+## Workflow
+1. Read the diff so you know what to comment on.
+2. POST your annotations (single or batch).
+3. Optionally clean up your previous annotations before reposting on a re-run.
+
+There is no "send" or "done" step — each POST is live the moment it lands.
+
+## Reading the diff
+
+\`\`\`sh
+curl -s ${origin}/api/diff | jq -r .rawPatch
+\`\`\`
+
+This returns the unified diff (\`rawPatch\`) the user is reviewing. Comment line numbers come straight from the diff's hunk headers:
+
+\`\`\`
+@@ -<oldStart>,<oldLen> +<newStart>,<newLen> @@
+\`\`\`
+
+- For added or unchanged context lines, count from \`newStart\` and post with \`"side": "new"\`.
+- For removed lines, count from \`oldStart\` and post with \`"side": "old"\`.
+
+Use the **file line number**, not the line's position within the diff. \`side\` defaults to \`"new"\` — only set \`"old"\` when commenting on a deleted line.
+
+## Three kinds of comment (\`scope\`)
+
+- **Line comment** (\`scope: "line"\`, the default) — pinned to a specific line range in one file. Requires \`filePath\`, \`lineStart\`, \`lineEnd\`. Use for feedback about specific code.
+- **File comment** (\`scope: "file"\`) — pinned to a whole file, shown as a banner in that file's header. Requires \`filePath\`; no line numbers. Use for feedback about the file as a whole.
+- **General comment** (\`scope: "general"\`) — not tied to any file. Sidebar entry only. Use for review-level feedback like "the error handling is inconsistent across these changes."
+
+## Posting a line comment
+
+\`\`\`sh
+curl -s ${origin}/api/external-annotations \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "source": "claude-code",
+    "scope": "line",
+    "filePath": "src/server/auth.ts",
+    "lineStart": 42,
+    "lineEnd": 42,
+    "side": "new",
+    "text": "This reads the token before checking it exists — guard against undefined."
+  }'
+\`\`\`
+
+## Posting a suggestion (proposed replacement code)
+
+\`\`\`sh
+curl -s ${origin}/api/external-annotations \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "source": "claude-code",
+    "type": "suggestion",
+    "filePath": "src/server/auth.ts",
+    "lineStart": 42,
+    "lineEnd": 44,
+    "text": "Guard against a missing token.",
+    "suggestedCode": "const token = req.headers.authorization;\\nif (!token) return res.status(401).end();"
+  }'
+\`\`\`
+
+## Posting a file comment
+
+\`\`\`sh
+curl -s ${origin}/api/external-annotations \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "source": "claude-code",
+    "scope": "file",
+    "filePath": "src/server/auth.ts",
+    "text": "This module mixes parsing and validation — consider splitting them."
+  }'
+\`\`\`
+
+## Posting a general comment
+
+\`\`\`sh
+curl -s ${origin}/api/external-annotations \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "source": "claude-code",
+    "scope": "general",
+    "text": "Error handling is inconsistent across these files — some throw, some return null."
+  }'
+\`\`\`
+
+All endpoints return \`201 {"ids": ["<uuid>"]}\` on success, \`400 {"error": "..."}\` on validation failure.
+
+### Fields
+
+| Field | Required | Notes |
+|---|---|---|
+| \`source\` | yes | Stable identifier for *you* (e.g. \`"claude-code"\`, \`"codex"\`, \`"my-linter"\`). Reuse the same value for every annotation you post — it lets you clean up your own later. Pick something specific enough that it won't collide with other tools running against the same session. |
+| \`scope\` | no | \`"line"\` (default), \`"file"\`, or \`"general"\`. |
+| \`filePath\` | for \`line\` / \`file\` | Repo-relative path exactly as it appears in the diff (e.g. \`"src/server/auth.ts"\`). |
+| \`lineStart\` | for \`line\` | File line number where the comment starts. |
+| \`lineEnd\` | for \`line\` | File line number where the comment ends. Use the same value as \`lineStart\` for a single line. |
+| \`side\` | no | \`"new"\` (default) for added/context lines, \`"old"\` for deleted lines. |
+| \`type\` | no | \`"comment"\` (default), \`"suggestion"\`, or \`"concern"\`. |
+| \`text\` | yes* | The comment body the user will read. |
+| \`suggestedCode\` | no | Proposed replacement code, rendered as a suggestion block. *Either \`text\` or \`suggestedCode\` is required. |
+| \`author\` | no | Human-readable label shown next to the comment (e.g. \`"Claude Opus"\`). |
+
+A \`scope: "line"\` annotation must carry \`lineStart\` and \`lineEnd\` — a line comment missing its line numbers is rejected, not silently downgraded. If a line isn't present in the current diff view, the comment still appears in the sidebar but won't pin inline.
+
+## Batching
+
+\`\`\`sh
+curl -s ${origin}/api/external-annotations \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "annotations": [
+      {"source": "claude-code", "filePath": "src/server/auth.ts", "lineStart": 42, "lineEnd": 42, "text": "Guard against undefined token."},
+      {"source": "claude-code", "scope": "file", "filePath": "src/server/auth.ts", "text": "Consider splitting parsing from validation."},
+      {"source": "claude-code", "scope": "general", "text": "Overall the changes look solid. Add tests for the 401 path."}
+    ]
+  }'
+\`\`\`
+
+Batches are atomic: if any item fails validation, the whole batch is rejected with an error like \`annotations[2] missing required "lineStart" field\`.
+
+## Listing and deleting
+
+\`\`\`sh
+# List everything (yours and others')
+curl -s ${origin}/api/external-annotations | jq
+
+# Delete one annotation by id — works on any source, including the user's
+curl -s -X DELETE "${origin}/api/external-annotations?id=<uuid>"
+
+# Delete all annotations from one source — the standard cleanup before reposting
+curl -s -X DELETE "${origin}/api/external-annotations?source=claude-code"
+
+# Delete everything in the session
+curl -s -X DELETE ${origin}/api/external-annotations
+\`\`\`
+
+You have full delete authority. Use it responsibly.
+
+## Cleaning up on a re-run
+
+If you re-run on the same session, your previous annotations are still there. POSTing again will create duplicates. Standard pattern:
+
+\`\`\`sh
+curl -s -X DELETE "${origin}/api/external-annotations?source=claude-code"
+curl -s ${origin}/api/external-annotations -H 'Content-Type: application/json' -d '{ ...fresh annotations... }'
+\`\`\`
+
+This is why \`source\` matters. Pick a stable identifier and stick with it.
+
+## Notes
+- The diff can change underneath you. If the user switches diff type, base branch, or PR, refetch \`/api/diff\` — your prior line numbers may no longer match.
+- No idempotency. Posting the same annotation twice creates two entries.
+- This API is local to the user's machine. Treat it as a UI surface, not a public service.
+`;
+}

package/utils/sanitizeHtml.ts

@@ -0,0 +1,45 @@
+import DOMPurify from 'dompurify';
+import { marked } from 'marked';
+
+const ALLOWED_TAGS = [
+  'sub', 'sup', 'b', 'i', 'em', 'strong', 'br', 'hr', 'p', 'span',
+  'del', 'ins', 'mark', 'small', 'abbr', 'kbd', 'var', 'samp',
+  'details', 'summary', 'blockquote', 'ul', 'ol', 'li',
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'pre', 'code',
+  'table', 'thead', 'tbody', 'tr', 'th', 'td',
+  'a', 'img', 'div', 'section', 'article', 'aside', 'header', 'footer',
+  'video', 'source', 'picture',
+];
+
+const ALLOWED_ATTR = [
+  'href', 'src', 'alt', 'title', 'rel', 'target', 'width', 'height', 'align',
+  'open', // preserve <details open> default-expanded state
+  // <video>/<source> — deliberately no `autoplay`, so embedded clips don't play
+  // on their own when a comment/description scrolls into view.
+  'controls', 'poster', 'muted', 'loop', 'playsinline', 'type',
+  // <picture>/<source> and responsive <img> — without these the alternate-format
+  // selection is inert and <source> renders as a no-op.
+  'srcset', 'media', 'sizes',
+];
+
+/**
+ * Render and sanitize the content of a raw HTML block for injection via
+ * innerHTML. Content is first run through `marked` so that markdown nested
+ * between HTML tags (e.g. `**bun**` inside `<details>…</details>`) renders
+ * as real `<strong>`, matching GitHub's flavored behavior. Then DOMPurify
+ * strips anything outside the allowlist — no event handlers, no inline
+ * styles, no scripts.
+ */
+export function sanitizeBlockHtml(html: string): string {
+  const rendered = marked.parse(html, { async: false, gfm: true, breaks: false }) as string;
+  return DOMPurify.sanitize(rendered, { ALLOWED_TAGS, ALLOWED_ATTR });
+}
+
+/**
+ * Sanitize inline HTML that is already HTML (no markdown pass) — same allowlist
+ * as {@link sanitizeBlockHtml}. Used for inline GitHub content (e.g. PR comment
+ * spans) so the allowlist lives in exactly one place.
+ */
+export function sanitizeInlineHtml(html: string): string {
+  return DOMPurify.sanitize(html, { ALLOWED_TAGS, ALLOWED_ATTR });
+}

package/utils/sharing.ts

@@ -0,0 +1,350 @@
+/**
+ * Portable sharing utilities for Plannotator
+ *
+ * Enables sharing plan + annotations via URL hash using:
+ * - Native CompressionStream/DecompressionStream (deflate-raw)
+ * - Base64url encoding for URL safety
+ *
+ * Inspired by textarea.my's approach.
+ */
+
+import { Annotation, AnnotationType, type ImageAttachment } from '../types';
+import { compress, decompress } from '@plannotator/core/compress';
+import { encrypt, decrypt } from '@plannotator/core/crypto';
+
+// Image in shareable format: plain string (old) or [path, name] tuple (new)
+type ShareableImage = string | [string, string];
+
+// Minimal shareable annotation format: [type, originalText, text?, author?, images?, quickLabel?]
+export type ShareableAnnotation =
+  | ['D', string, string | null, ShareableImage[]?]                    // Deletion: type, original, author, images
+  | ['C', string, string, string | null, ShareableImage[]?, (1)?]      // Comment: type, original, comment, author, images, isQuickLabel
+  | ['G', string, string | null, ShareableImage[]?];                   // Global Comment: type, comment, author, images
+
+export interface SharePayload {
+  p: string;  // plan markdown
+  a: ShareableAnnotation[];
+  g?: ShareableImage[];  // global attachments (path strings or [path, name] tuples)
+  d?: (string | null)[];  // diffContext per annotation, parallel to `a`
+  s?: (string | undefined)[];  // source per annotation (external tool identifier), parallel to `a`
+  h?: string;  // raw HTML content (direct HTML rendering mode)
+  r?: 'html';  // render mode flag (omitted = markdown)
+}
+
+/**
+ * Convert ShareableImage[] to ImageAttachment[] (handles old plain-string format)
+ */
+export function parseShareableImages(raw: ShareableImage[] | undefined): ImageAttachment[] | undefined {
+  if (!raw?.length) return undefined;
+  return raw.map(img => {
+    if (typeof img === 'string') {
+      // Old format: plain path string — derive name from filename
+      const name = img.split('/').pop()?.replace(/\.[^.]+$/, '') || 'image';
+      return { path: img, name };
+    }
+    return { path: img[0], name: img[1] };
+  });
+}
+
+/**
+ * Convert ImageAttachment[] to ShareableImage[] for compact serialization
+ */
+export function toShareableImages(images: ImageAttachment[] | undefined): ShareableImage[] | undefined {
+  if (!images?.length) return undefined;
+  return images.map(img => [img.path, img.name]);
+}
+
+// Re-export compress/decompress from shared package (single source of truth)
+export { compress, decompress };
+
+/**
+ * Convert full Annotation objects to minimal shareable format
+ */
+export function toShareable(annotations: Annotation[]): ShareableAnnotation[] {
+  return annotations.map(ann => {
+    const author = ann.author || null;
+    const images = toShareableImages(ann.images);
+
+    // Handle GLOBAL_COMMENT specially - it starts with 'G' (from GLOBAL_COMMENT)
+    if (ann.type === AnnotationType.GLOBAL_COMMENT) {
+      return ['G', ann.text || '', author, images] as ShareableAnnotation;
+    }
+
+    if (ann.type === AnnotationType.DELETION) {
+      return ['D', ann.originalText, author, images] as ShareableAnnotation;
+    }
+
+    // COMMENT
+    if (ann.isQuickLabel) {
+      return ['C', ann.originalText, ann.text || '', author, images ?? undefined, 1] as ShareableAnnotation;
+    }
+    return ['C', ann.originalText, ann.text || '', author, images] as ShareableAnnotation;
+  });
+}
+
+/**
+ * Convert shareable format back to full Annotation objects
+ * Note: blockId, offsets, and meta will need to be populated separately
+ * by finding the text in the rendered document.
+ */
+export function fromShareable(data: ShareableAnnotation[], diffContexts?: (string | null)[] | null, sources?: (string | undefined)[] | null): Annotation[] {
+  const typeMap: Record<string, AnnotationType> = {
+    'D': AnnotationType.DELETION,
+    'C': AnnotationType.COMMENT,
+    'G': AnnotationType.GLOBAL_COMMENT,
+  };
+
+  return data.map((item, index) => {
+    const type = item[0];
+
+    // Handle global comments specially: ['G', text, author, images?]
+    if (type === 'G') {
+      const text = item[1] as string;
+      const author = item[2] as string | null;
+      const rawImages = item[3] as ShareableImage[] | undefined;
+
+      return {
+        id: `shared-${index}-${Date.now()}`,
+        blockId: '',
+        startOffset: 0,
+        endOffset: 0,
+        type: AnnotationType.GLOBAL_COMMENT,
+        text: text || undefined,
+        originalText: '',
+        createdA: Date.now() + index,
+        author: author || undefined,
+        images: parseShareableImages(rawImages),
+        ...(sources?.[index] ? { source: sources[index] } : {}),
+      };
+    }
+
+    const originalText = item[1];
+    // For deletion: [type, original, author, images?]
+    // For others: [type, original, text, author, images?]
+    const text = type === 'D' ? undefined : item[2] as string;
+    const author = type === 'D' ? item[2] as string | null : item[3] as string | null;
+    const rawImages = type === 'D' ? item[3] as ShareableImage[] | undefined : item[4] as ShareableImage[] | undefined;
+    // Comment annotations may have isQuickLabel flag at index 5
+    const isQuickLabel = type === 'C' && item.length > 5 && item[5] === 1 ? true : undefined;
+
+    return {
+      id: `shared-${index}-${Date.now()}`,
+      blockId: '',  // Will be populated during highlight restoration
+      startOffset: 0,
+      endOffset: 0,
+      type: typeMap[type],
+      text: text || undefined,
+      originalText,
+      createdA: Date.now() + index,  // Preserve order
+      author: author || undefined,
+      images: parseShareableImages(rawImages),
+      ...(isQuickLabel ? { isQuickLabel } : {}),
+      ...(diffContexts?.[index] ? { diffContext: diffContexts[index] as Annotation['diffContext'] } : {}),
+      ...(sources?.[index] ? { source: sources[index] } : {}),
+      // startMeta/endMeta will be set by web-highlighter
+    };
+  });
+}
+
+function buildDiffContextArray(annotations: Annotation[]): (string | null)[] | null {
+  const arr = annotations.map(a => a.diffContext || null);
+  return arr.some(v => v !== null) ? arr : null;
+}
+
+function buildSourceArray(annotations: Annotation[]): (string | undefined)[] | null {
+  const arr = annotations.map(a => a.source || undefined);
+  return arr.some(v => v !== undefined) ? arr : null;
+}
+
+/**
+ * Generate a full shareable URL from plan and annotations
+ */
+export async function generateShareUrl(
+  markdown: string,
+  annotations: Annotation[],
+  globalAttachments?: ImageAttachment[],
+  baseUrl: string = DEFAULT_SHARE_BASE,
+  rawHtml?: string,
+): Promise<string | null> {
+  // HTML content is too large for URL hashes — force paste service path
+  if (rawHtml) return null;
+  const diffContexts = buildDiffContextArray(annotations);
+  const sources = buildSourceArray(annotations);
+  const payload: SharePayload = {
+    p: markdown,
+    a: toShareable(annotations),
+    g: globalAttachments?.length ? toShareableImages(globalAttachments) : undefined,
+    ...(diffContexts ? { d: diffContexts } : {}),
+    ...(sources ? { s: sources } : {}),
+  };
+
+  const hash = await compress(payload);
+  return `${baseUrl}/#${hash}`;
+}
+
+/**
+ * Parse a share URL hash and return the payload
+ * Returns null if no valid hash or parsing fails
+ */
+export async function parseShareHash(): Promise<SharePayload | null> {
+  const raw = window.location.hash.slice(1); // Remove leading #
+  const hash = raw.split('?')[0]; // Strip callback params (?cb=...&ct=...)
+
+  if (!hash) {
+    return null;
+  }
+
+  try {
+    return (await decompress(hash)) as SharePayload;
+  } catch (e) {
+    console.warn('Failed to parse share hash:', e);
+    return null;
+  }
+}
+
+/**
+ * Get the size of a URL in a human-readable format
+ */
+export function formatUrlSize(url: string): string {
+  const bytes = new Blob([url]).size;
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+
+// ---------------------------------------------------------------------------
+// Short URL support (paste-service backed)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_PASTE_API = 'https://plannotator-paste.plannotator.workers.dev';
+const DEFAULT_SHARE_BASE = 'https://share.plannotator.ai';
+
+export class ShortShareUrlError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ShortShareUrlError';
+  }
+}
+
+/**
+ * Create a short share URL by posting compressed plan data to the paste service.
+ *
+ * Returns `{ shortUrl, id }` on success, or `null` when the paste service is
+ * unavailable (e.g. self-hosted environments without a paste backend). Callers
+ * should fall back to the hash-based URL in that case.
+ *
+ * The request has a 5-second timeout so UI responsiveness is not affected.
+ */
+export async function createShortShareUrl(
+  markdown: string,
+  annotations: Annotation[],
+  globalAttachments?: ImageAttachment[],
+  options?: {
+    /** Override the paste API base URL (default: https://plannotator-paste.plannotator.workers.dev) */
+    pasteApiUrl?: string;
+    /** Override the share site base URL used in the returned short link */
+    shareBaseUrl?: string;
+  },
+  rawHtml?: string,
+): Promise<{ shortUrl: string; id: string } | null> {
+  const pasteApi = options?.pasteApiUrl ?? DEFAULT_PASTE_API;
+  const shareBase = options?.shareBaseUrl ?? DEFAULT_SHARE_BASE;
+
+  try {
+    const diffContexts = buildDiffContextArray(annotations);
+    const sources = buildSourceArray(annotations);
+    const payload: SharePayload = {
+      p: markdown,
+      a: toShareable(annotations),
+      g: globalAttachments?.length ? toShareableImages(globalAttachments) : undefined,
+      ...(diffContexts ? { d: diffContexts } : {}),
+      ...(sources ? { s: sources } : {}),
+      ...(rawHtml ? { h: rawHtml, r: 'html' as const } : {}),
+    };
+
+    const compressed = await compress(payload);
+
+    // Encrypt before uploading — server only sees ciphertext
+    const { ciphertext, key } = await encrypt(compressed);
+
+    const response = await fetch(`${pasteApi}/api/paste`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ data: ciphertext }),
+      signal: AbortSignal.timeout(5_000),
+    });
+
+    if (!response.ok) {
+      if (response.status === 413) {
+        throw new ShortShareUrlError(await readPasteError(response, 'Share payload is too large'));
+      }
+      console.warn(`[sharing] Paste service returned ${response.status}`);
+      return null;
+    }
+
+    const result = (await response.json()) as { id: string };
+    // Embed paste origin in fragment when non-default so the share portal can
+    // fetch from the right service without a server.
+    const pasteParam = pasteApi !== DEFAULT_PASTE_API
+      ? `&paste=${btoa(pasteApi).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')}`
+      : '';
+    const shortUrl = `${shareBase}/p/${result.id}#key=${key}${pasteParam}`;
+
+    return { shortUrl, id: result.id };
+  } catch (e) {
+    if (e instanceof ShortShareUrlError) {
+      throw e;
+    }
+    // Service unavailable — expected for self-hosted setups without a paste backend.
+    // The caller is responsible for falling back to hash-based sharing silently.
+    console.debug('[sharing] Short URL service unavailable, using hash-based sharing:', e);
+    return null;
+  }
+}
+
+async function readPasteError(response: Response, fallback: string): Promise<string> {
+  try {
+    const body = (await response.json()) as { error?: unknown };
+    return typeof body.error === 'string' && body.error.trim() ? body.error : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Load plan data from a paste service using the paste ID embedded in a short URL.
+ *
+ * Fetches the compressed payload from `<pasteApiUrl>/api/paste/<pasteId>` and
+ * decompresses it into a `SharePayload`. Returns `null` on any failure.
+ */
+export async function loadFromPasteId(
+  pasteId: string,
+  pasteApiUrl: string = DEFAULT_PASTE_API,
+  encryptionKey?: string
+): Promise<SharePayload | null> {
+  try {
+    const response = await fetch(`${pasteApiUrl}/api/paste/${pasteId}`, {
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!response.ok) {
+      console.warn(`[sharing] Paste fetch returned ${response.status} for id ${pasteId}`);
+      return null;
+    }
+
+    const result = (await response.json()) as { data: string };
+
+    if (encryptionKey) {
+      // Encrypted path: decrypt ciphertext, then decompress
+      const compressed = await decrypt(result.data, encryptionKey);
+      return await decompress(compressed) as SharePayload;
+    }
+
+    // Legacy unencrypted path: decompress directly
+    return await decompress(result.data) as SharePayload;
+  } catch (e) {
+    console.warn('[sharing] Failed to load from paste ID:', e);
+    return null;
+  }
+}