@plannotator/ui 0.39.0 → 0.40.0

package/utils/parser.ts

@@ -1131,6 +1131,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 +1144,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 +1209,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;
@@ -1241,7 +1252,11 @@ export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOption
         output += `${commentHeadingLine(ann)}\n> ${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`;

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
+  );
+}