@plannotator/ui 0.38.2 → 0.40.0

package/theme.css

@@ -243,6 +243,68 @@
   animation: vim-announcement-dialog-in 200ms cubic-bezier(0.22, 1, 0.36, 1) both;
 }
 
+/* First-run terminal-tools announcement: same entrance as the Vim one, and
+ * under reduced motion the panel still fades in, it just does not travel. */
+.terminal-tools-announcement-backdrop {
+  animation: vim-announcement-backdrop-in 160ms ease-out both;
+}
+
+.terminal-tools-announcement-dialog {
+  animation: vim-announcement-dialog-in 220ms cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .terminal-tools-announcement-dialog {
+    animation: vim-announcement-backdrop-in 160ms ease-out both;
+  }
+}
+
+/* The "New · Watch:" corner block on the announcement footage, flush to the
+ * frame's top-left edge. Colors come from the dialog's own --announce-brand*
+ * variables (Herdr Annotate's badge palette, deliberately not app tokens); the
+ * periwinkle edge runs only along the two sides that meet the footage. The
+ * sheen is a slow diagonal highlight across the whole block every 4s, never a
+ * blink; the dialog drops the --sheen class under reduced motion and the media
+ * query below is the backstop. */
+.terminal-tools-announcement-tag {
+  position: absolute;
+  overflow: hidden;
+  background: var(--announce-brand, #312b52);
+  color: var(--announce-brand-text, #c9c6f1);
+  border-right: 1px solid color-mix(in srgb, var(--announce-brand-accent, #B9C0FF) 55%, transparent);
+  border-bottom: 1px solid color-mix(in srgb, var(--announce-brand-accent, #B9C0FF) 55%, transparent);
+  box-shadow:
+    2px 2px 0 rgba(0, 0, 0, 0.18),
+    4px 6px 18px rgba(0, 0, 0, 0.32);
+}
+
+.terminal-tools-announcement-tag--sheen::after {
+  content: '';
+  position: absolute;
+  inset: -1px;
+  pointer-events: none;
+  background: linear-gradient(
+    115deg,
+    transparent 38%,
+    color-mix(in srgb, var(--announce-brand-accent, #B9C0FF) 34%, transparent) 50%,
+    transparent 62%
+  );
+  transform: translateX(-100%);
+  animation: terminal-tools-announcement-sheen 4s ease-in-out infinite;
+}
+
+@keyframes terminal-tools-announcement-sheen {
+  0% { transform: translateX(-100%); }
+  45%, 100% { transform: translateX(100%); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .terminal-tools-announcement-tag--sheen::after {
+    animation: none;
+    display: none;
+  }
+}
+
 .vim-announcement-switch {
   transition:
     border-color 140ms ease,

package/types.ts

@@ -82,6 +82,7 @@ export interface Annotation {
   pageUrl?: string; // set only by live app annotate sessions: the page (pathname + search) the annotation was made on; restore filters to the current page and export groups by page
   inReplyTo?: string; // id of the annotation this one replies to; a reply inherits its parent's anchor, renders indented under it in the panel, and exports grouped under it. Additive: annotations without it render and export exactly as before.
   htmlAnchor?: HtmlElementAnchor; // raw-HTML pinpoint: serialized element anchor for reliable restoration
+  elementContext?: HtmlElementContext; // raw-HTML / live-app pinpoint: bounded agent-facing description of the primary element (never used by restore)
   htmlAdditionalTargets?: HtmlAnnotationTarget[]; // raw-HTML shift-click multi-select: extra elements this one comment covers (primary stays htmlAnchor/originalText)
   // web-highlighter metadata for cross-element selections
   startMeta?: AnnotationTextMeta;
@@ -124,6 +125,50 @@ export interface HtmlAnnotationTarget {
   text: string;
   /** Element anchor for restoration; absent when the bridge failed closed. */
   anchor?: HtmlElementAnchor;
+  /** Agent-facing element description (smaller budget than the primary's). */
+  context?: HtmlElementContext;
+}
+
+/**
+ * A bounded, agent-facing description of a pinpointed element, captured by the
+ * bridge at annotation time (only it can see the DOM). Purely descriptive:
+ * restore never reads it (that is `HtmlElementAnchor`'s job). It exists so the
+ * exported feedback can tell an agent working in the app's SOURCE which
+ * element the comment is about — identity (what it is), location (where it
+ * sits), and hooks (what to grep for) — without dumping the page. Every field
+ * is page-controlled and re-validated at the parent trust boundary
+ * (`parseHtmlElementContext`). Additive: annotations without one export
+ * exactly as before, and share links never carry it.
+ */
+export interface HtmlElementContext {
+  tag: string;
+  id?: string;
+  /** Author classes, generated/hashed ones skipped; may end in "+N more". */
+  classes?: string[];
+  /** Ancestor path, e.g. `body > div#root > header.site-header > nav#site-nav`. */
+  path?: string;
+  /** Explicit `role` or the tag's implicit ARIA role. */
+  role?: string;
+  /** Accessible name: aria-label, aria-labelledby, alt, title, <label for>, own short text. */
+  name?: string;
+  /** Allowlisted attributes in a fixed order (href/src scrubbed of query and fragment). */
+  attrs?: Array<[string, string]>;
+  /** Rendered text (innerText), whitespace-collapsed, word-boundary truncated. */
+  text?: string;
+  /** Collapsed HTML skeleton: opening tag with allowlisted attributes, then children as bare tags. */
+  outline?: string;
+  /** Number of element children (after skipping script/style/template and viewer overlays). */
+  children?: number;
+  /** Viewport-relative bounding box plus the viewport it was seen at. */
+  rect?: { x: number; y: number; w: number; h: number; vw: number; vh: number };
+  /** Nearest enclosing landmark/region, e.g. `header.site-header "Primary"`. */
+  landmark?: string;
+  /** Nearest preceding heading, e.g. `h2 "Usage"`. */
+  heading?: string;
+  /** Nearest author component marker, e.g. `data-component=AppNav`. */
+  component?: string;
+  /** Live-app sessions only: the route the element was seen on and the page title. */
+  page?: { url: string; title?: string };
 }
 
 export type AlertKind = 'note' | 'tip' | 'warning' | 'caution' | 'important';

package/utils/annotationScope.ts

@@ -0,0 +1,159 @@
+/**
+ * Cross-file annotation scope (multi-document annotate sessions).
+ *
+ * A folder session spreads one body of feedback across many documents, but the
+ * annotations panel only ever showed the open file's comments. This module owns
+ * the pure half of the "All files" view: which documents have feedback, how
+ * they are ordered and labelled, and which scope the panel opens on.
+ *
+ * Everything here is pure except the two preference accessors, which use the
+ * shared storage backend (cookies by default) like the other panel prefs.
+ */
+
+import { normalizeBrowserPath, pathIsInsideDir } from '@plannotator/core/browser-paths';
+import type { Annotation } from '../types';
+import { getItem, setItem } from './storage';
+
+/** `current` = only the open document (the incumbent view). `all` = every document. */
+export type AnnotationScope = 'current' | 'all';
+
+const ANNOTATION_SCOPE_KEY = 'plannotator-annotation-scope';
+
+/** The user's explicit last choice, or null when they have never chosen. */
+export function getAnnotationScopePreference(): AnnotationScope | null {
+  const raw = getItem(ANNOTATION_SCOPE_KEY);
+  return raw === 'all' || raw === 'current' ? raw : null;
+}
+
+export function setAnnotationScopePreference(scope: AnnotationScope): void {
+  setItem(ANNOTATION_SCOPE_KEY, scope);
+}
+
+/**
+ * Group key for the open document when it has no path of its own — plan review,
+ * where the plan is the document and `sourceFilePath` is annotate-only. Without
+ * a key the root document forms no group at all, so the "All files" view hid the
+ * plan's own comments while listing every linked document's. It contains no path
+ * separator, so `normalizeBrowserPath` leaves it alone, and the angle brackets
+ * keep it from colliding with a real file path (illegal in Windows paths, and
+ * absent from the absolute paths these groups carry).
+ */
+export const ROOT_DOCUMENT_GROUP_KEY = '<plannotator-root-document>';
+
+export interface AnnotationDocumentInput {
+  /** Absolute path of the document. */
+  path: string;
+  annotations: readonly Annotation[];
+  /** Display name override. Only the pathless root document needs one: every
+   *  other group derives its label from its path. */
+  label?: string;
+}
+
+export interface AnnotationDocumentGroup {
+  path: string;
+  /** Path relative to the nearest session root, else the bare file name. */
+  label: string;
+  annotations: Annotation[];
+  isCurrent: boolean;
+}
+
+/**
+ * Display name for a document: its path relative to the deepest session root
+ * that contains it (the same `${dir}/${node.path}` shape the file browser
+ * renders), falling back to the bare file name when no root matches.
+ */
+export function documentLabel(path: string, roots: readonly string[] = []): string {
+  const normalized = normalizeBrowserPath(path);
+  let best = '';
+  for (const root of roots) {
+    if (!root) continue;
+    const normalizedRoot = normalizeBrowserPath(root);
+    if (!pathIsInsideDir(normalized, normalizedRoot)) continue;
+    if (normalizedRoot.length > best.length) best = normalizedRoot;
+  }
+  if (best && normalized.length > best.length) {
+    return normalized.slice(best.endsWith('/') ? best.length : best.length + 1);
+  }
+  const lastSlash = normalized.lastIndexOf('/');
+  return lastSlash >= 0 ? normalized.slice(lastSlash + 1) : normalized;
+}
+
+/**
+ * One group per document that actually carries feedback, the open document
+ * first and the rest ordered by path. Documents without annotations are
+ * dropped: the view answers "where is my feedback", not "what files exist".
+ */
+export function groupAnnotationsByDocument(
+  documents: Iterable<AnnotationDocumentInput>,
+  currentPath: string | null,
+  roots: readonly string[] = [],
+): AnnotationDocumentGroup[] {
+  const normalizedCurrent = currentPath ? normalizeBrowserPath(currentPath) : null;
+  const groups: AnnotationDocumentGroup[] = [];
+  const seen = new Set<string>();
+  for (const doc of documents) {
+    const path = normalizeBrowserPath(doc.path);
+    if (!path || seen.has(path) || doc.annotations.length === 0) continue;
+    seen.add(path);
+    groups.push({
+      path,
+      label: doc.label ?? documentLabel(path, roots),
+      annotations: [...doc.annotations],
+      isCurrent: path === normalizedCurrent,
+    });
+  }
+  groups.sort((a, b) => {
+    if (a.isCurrent !== b.isCurrent) return a.isCurrent ? -1 : 1;
+    return a.path.localeCompare(b.path);
+  });
+  return groups;
+}
+
+/**
+ * The panel's groups for a session: every cached document plus the OPEN one,
+ * whose live list (externals included) is the same set its "This file" timeline
+ * renders — the cache copy behind it can be stale.
+ *
+ * The open document is always contributed, under `current.key`. In plan review
+ * that key is {@link ROOT_DOCUMENT_GROUP_KEY}: the plan has no path, and keying
+ * groups by path alone dropped it from the list, so the "All files" view hid
+ * the reviewer's own comments on the document in front of them.
+ */
+export function buildAnnotationDocumentGroups(input: {
+  /** Documents held in the linked-doc cache, keyed by path. */
+  cached: Iterable<readonly [string, readonly Annotation[]]>;
+  current: { key: string; label?: string; annotations: readonly Annotation[] };
+  roots?: readonly string[];
+}): AnnotationDocumentGroup[] {
+  const byPath = new Map<string, readonly Annotation[]>();
+  for (const [path, annotations] of input.cached) byPath.set(path, annotations);
+  byPath.set(input.current.key, input.current.annotations);
+  return groupAnnotationsByDocument(
+    Array.from(byPath, ([path, annotations]) => ({
+      path,
+      annotations,
+      label: path === input.current.key ? input.current.label : undefined,
+    })),
+    input.current.key,
+    input.roots ?? [],
+  );
+}
+
+/**
+ * Which scope the panel opens on for the document that just became active.
+ *
+ * The saved preference wins, with one exception that is the whole point of the
+ * feature: landing on a file with no feedback while feedback exists elsewhere
+ * would otherwise show "No annotations yet" next to a session full of comments.
+ */
+export function resolveInitialAnnotationScope(input: {
+  saved: AnnotationScope | null;
+  /** Annotations on the document that is open now. */
+  currentCount: number;
+  /** Annotations on every other document in the session. */
+  otherCount: number;
+}): AnnotationScope {
+  if (input.saved === 'all') return 'all';
+  if (input.currentCount === 0 && input.otherCount > 0) return 'all';
+  return 'current';
+}