@plannotator/ui 0.39.0 → 0.41.0

package/utils/parser.ts

@@ -1,6 +1,7 @@
 import type { Block, Annotation, CodeAnnotation, EditorAnnotation, ImageAttachment } from '../types';
 import { planDenyFeedback } from '@plannotator/core/feedback-templates';
 import { resolveReplyParents } from '@plannotator/core/annotation-threads';
+import { diagramAnchorLocationLine, parseDiagramAnchor } from '@plannotator/core/diagram-anchor';
 import { skillReferenceExportBlock } from './skillReferences';
 
 /**
@@ -1131,6 +1132,9 @@ export interface ElementContextExportOptions {
   /** Emit the live-app route line. The grouped export already prints a
    *  `## Page:` heading, so it passes false; a single copied entry passes true. */
   includeRoute?: boolean;
+  /** Print the identity lines WITHOUT the fenced outline, for model turns where
+   *  the 600-char outline is the expensive part. Default true. */
+  includeOutline?: boolean;
 }
 
 /** The agent-facing element block for a raw-HTML / live-app pinpoint: a
@@ -1141,8 +1145,9 @@ export interface ElementContextExportOptions {
 export const elementContextExportBlock = (ann: any, opts: ElementContextExportOptions = {}): string => {
   const context = ann?.elementContext;
   if (!context || typeof context !== 'object' || typeof context.tag !== 'string') return '';
+  const includeOutline = opts.includeOutline ?? true;
   let block = '';
-  if (typeof context.outline === 'string' && context.outline.trim()) {
+  if (includeOutline && typeof context.outline === 'string' && context.outline.trim()) {
     // Fence at 4 backticks; the boundary already defuses 3+ runs inside the
     // outline, and a 4-run here cannot be closed by anything the page wrote.
     const outline = context.outline.replace(/`{3,}/g, "'''").trim();
@@ -1205,11 +1210,18 @@ const additionalTargetsExportBlock = (ann: any): string => {
     // Element identity for the agent, one line per extra target: the
     // selector and the path (a full context block per target would swamp
     // the comment; the rest of the context stays persisted, not exported).
+    //
+    // Gated on the target carrying element context, which is what makes the
+    // element-context work additive in the literal sense it claims: a target
+    // captured before it existed (or restored from an older draft) has an
+    // anchor but no context, and exports byte-identically to before.
     const locators: string[] = [];
-    const selector = target?.anchor?.selector;
-    if (typeof selector === 'string' && selector) locators.push(`\`${safeInline(selector, 300)}\``);
-    const path = target?.context?.path;
-    if (typeof path === 'string' && path) locators.push(`\`${safeInline(path, 512)}\``);
+    if (target?.context && typeof target.context === 'object') {
+      const selector = target?.anchor?.selector;
+      if (typeof selector === 'string' && selector) locators.push(`\`${safeInline(selector, 300)}\``);
+      const path = target?.context?.path;
+      if (typeof path === 'string' && path) locators.push(`\`${safeInline(path, 512)}\``);
+    }
     block += `- ${label}"${clipped}"${locators.length ? ` — ${locators.join(' · ')}` : ''}\n`;
   });
   return block;
@@ -1238,10 +1250,14 @@ export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOption
         output += `[${ann.text}] ${commentHeadingLine(ann)}\n`;
         if (ann.quickLabelTip) output += `> ${ann.quickLabelTip}\n`;
       } else {
-        output += `${commentHeadingLine(ann)}\n> ${ann?.text ?? ''}\n`;
+        output += `${commentHeadingLine(ann)}\n${diagramLocationExportLine(ann)}> ${ann?.text ?? ''}\n`;
       }
   }
-  output += elementContextExportBlock(ann, opts);
+  const resolvedOpts: ElementContextExportOptions = {
+    includeRoute: opts.includeRoute ?? true,
+    ...(opts.includeOutline !== undefined ? { includeOutline: opts.includeOutline } : {}),
+  };
+  output += elementContextExportBlock(ann, resolvedOpts);
   output += additionalTargetsExportBlock(ann);
   if (Array.isArray(ann?.images) && ann.images.length > 0) {
     output += `**Attached images:**\n`;
@@ -1252,6 +1268,16 @@ export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOption
   return output;
 };
 
+/** The location line under a comment made on a rendered diagram part:
+ *  `Diagram node Approve? (D), line 4` — the part's own id (what the agent
+ *  greps the fence for) and the DOCUMENT line that declares it. Emits
+ *  nothing for every other annotation, keeping their output byte-identical;
+ *  a malformed anchor (an older or foreign writer) is skipped, never thrown. */
+const diagramLocationExportLine = (ann: any): string => {
+  const anchor = ann?.diagramAnchor === undefined ? null : parseDiagramAnchor(ann.diagramAnchor);
+  return anchor === null ? '' : `${safeInline(diagramAnchorLocationLine(anchor), 600)}\n`;
+};
+
 const lineLabelForAnnotation = (blocks: Block[], ann: any): string | null => {
   if (!ann.blockId || ann.type === 'GLOBAL_COMMENT') return null;
   if (typeof ann.blockId === 'string' && ann.blockId.startsWith('diff-block-')) return null;
@@ -1420,11 +1446,13 @@ export const exportAnnotations = (
       case 'COMMENT':
         if (ann.isQuickLabel) {
           output += `[${ann.text}] ${commentHeadingLine(ann)}\n`;
+          output += diagramLocationExportLine(ann);
           if (ann.quickLabelTip) {
             output += `> ${ann.quickLabelTip}\n`;
           }
         } else {
           output += `${commentHeadingLine(ann)}\n`;
+          output += diagramLocationExportLine(ann);
           output += `> ${ann.text}\n`;
         }
         break;
@@ -1539,6 +1567,7 @@ export const exportLinkedDocAnnotations = (
 
         case 'COMMENT':
           output += `${commentHeadingLine(ann)}\n`;
+          output += diagramLocationExportLine(ann);
           output += `> ${ann.text}\n`;
           break;
 

package/utils/terminalToolsAnnouncement.ts

@@ -0,0 +1,76 @@
+/**
+ * One-time gate for the terminal-tools announcement (Plannotator TUI and
+ * Herdr Annotate). Cookie-backed like the other announcement gates, so a
+ * dismissal survives Plannotator's random localhost ports, and shared by the
+ * plan editor, the annotate surfaces and the code review editor: dismissing it
+ * anywhere retires it everywhere.
+ */
+
+import { storage } from './storage';
+
+const STORAGE_KEY = 'plannotator-announce-tui-herdr-seen';
+// Bump to re-announce after a meaningful revision.
+const CURRENT_VERSION = '1';
+
+export function needsTerminalToolsAnnouncement(): boolean {
+  return storage.getItem(STORAGE_KEY) !== CURRENT_VERSION;
+}
+
+export function markTerminalToolsAnnouncementSeen(): void {
+  storage.setItem(STORAGE_KEY, CURRENT_VERSION);
+}
+
+export interface TerminalToolsAnnouncementGateState {
+  /**
+   * Latched at mount from needsTerminalToolsAnnouncement(). Latched rather than
+   * read per render so a dismissal cannot unmount the dialog before its own
+   * click handler finishes.
+   */
+  readonly announcementPending: boolean;
+  /** The app has not finished loading its initial payload. */
+  readonly isLoading: boolean;
+  /**
+   * The session has no author to address: archive browsing, a read-only shared
+   * plan, and any session with no Plannotator server behind it (the share
+   * portal's root and its demo plan included — those are not "shared
+   * sessions", so the host must fold that in). Telling a viewer about a CLI
+   * they did not open is noise, and the cookie is deliberately NOT consumed,
+   * so the next authoring session still shows it.
+   */
+  readonly readOnlySession: boolean;
+  /**
+   * Plannotator's compact touch shell. The panel is desktop-shaped (install
+   * commands to copy, four outbound links) and a phone is not where anyone
+   * installs a terminal tool. Also deferred rather than consumed.
+   */
+  readonly compact: boolean;
+  /**
+   * Any other first-run dialog is on screen. The chain dialogs never stack.
+   */
+  readonly otherFirstRunDialogVisible: boolean;
+}
+
+/**
+ * Chain gate for the announcement. It is LAST in each app's first-run dialog
+ * chain, after every dialog that asks the user to decide something (code
+ * review: guide intro, look-and-feel, review setup, edit mode, token hover
+ * cards; plan and annotate: look-and-feel, goal setup, permission mode).
+ *
+ * Last rather than first because none of those dialogs consume this cookie:
+ * a session that is busy asking questions defers the announcement to the next
+ * load instead of burning it. That also puts it in front of the right reader.
+ * Someone opening Plannotator for the first time is still learning this app;
+ * the people who should hear that it now runs in a terminal are the ones who
+ * already answered every setup question, and they see it on their next load.
+ */
+export function terminalToolsAnnouncementCanShow(
+  state: TerminalToolsAnnouncementGateState,
+): boolean {
+  return (
+    state.announcementPending &&
+    !state.isLoading &&
+    !state.readOnlySession &&
+    !state.compact &&
+    !state.otherFirstRunDialogVisible
+  );
+}

package/components/mermaidSvg.ts

@@ -1,33 +0,0 @@
-// Pure SVG-markup helpers for MermaidBlock. Kept free of React and the
-// mermaid library so they can be unit-tested without loading mermaid's
-// browser-only `initialize()` (which throws in headless test environments).
-
-// Bake sizing attrs into the SVG markup so they survive repeated
-// dangerouslySetInnerHTML re-injection — imperative setAttribute gets wiped.
-export function normalizeMermaidSvgMarkup(markup: string): string {
-  return markup.replace(/<svg\b([^>]*)>/i, (_match, attrs: string) => {
-    let next = attrs;
-
-    if (/\bstyle\s*=\s*"/i.test(next)) {
-      next = next.replace(/\bstyle\s*=\s*"([^"]*)"/i, (_m, styleVal: string) => {
-        const rules = styleVal
-          .split(';')
-          .map((s) => s.trim())
-          .filter((s) => s.length > 0 && !/^max-width\s*:/i.test(s));
-        rules.push('max-width: none');
-        return `style="${rules.join('; ')}"`;
-      });
-    } else {
-      next += ' style="max-width: none"';
-    }
-
-    if (!/\bpreserveAspectRatio\s*=/i.test(next)) {
-      next += ' preserveAspectRatio="xMidYMid meet"';
-    }
-    if (!/\bheight\s*=/i.test(next)) {
-      next += ' height="100%"';
-    }
-
-    return `<svg${next}>`;
-  });
-}