@plannotator/ui 0.41.2 → 0.42.0

package/types.ts

@@ -1,6 +1,16 @@
 import type { DiagramAnchor } from '@plannotator/core/diagram-anchor';
+import type { DiagramRenderKind } from '@plannotator/core/annotatable';
 
 export type { DiagramAnchor } from '@plannotator/core/diagram-anchor';
+export type { DiagramRenderKind } from '@plannotator/core/annotatable';
+
+/**
+ * How a document's body is rendered. `markdown` and `html` are the original
+ * pair; the two diagram kinds are whole-file diagram sources (.mmd/.mermaid,
+ * .dot/.gv) that render as ONE diagram through the same engine a ```mermaid
+ * fence uses — see diagramDocumentBlocks in utils/parser.
+ */
+export type DocumentRenderAs = 'markdown' | 'html' | DiagramRenderKind;
 
 export enum AnnotationType {
   DELETION = 'DELETION',
@@ -192,6 +202,16 @@ export interface Block {
   order: number; // Sorting order
   startLine: number; // 1-based line number in source
   sourceLineCount?: number; // Number of source lines consumed when it differs from content lines
+  /**
+   * Line offset a diagram comment's `sourceLine` is measured from, when it
+   * differs from `startLine`. A ```mermaid fence in a document has its opening
+   * line ABOVE the diagram's first line, so `startLine` is the right offset
+   * there and this stays unset. A whole-file diagram source (.mmd/.dot) has no
+   * fence: its first line IS document line 1, so it sets 0 here while
+   * `startLine` keeps naming the block's own first line for the export's
+   * `(lines a–b)` label.
+   */
+  diagramSourceLineOffset?: number;
 }
 
 export interface DiffResult {

package/utils/parser.ts

@@ -541,6 +541,39 @@ export const resolveReferenceLinks = (markdown: string): string => {
     .join('\n');
 };
 
+/**
+ * The block list for a whole-file diagram source (`plannotator annotate
+ * flow.mmd`): ONE code block carrying the file's raw text, which `Viewer`
+ * hands to the same `DiagramBlock` a ```mermaid fence in a plan produces.
+ * Everything downstream — diagram comments, the annotations rail, the export's
+ * `Diagram node <label> (<id>), line <n>` location line, drafts, restore — is
+ * the fence path unchanged.
+ *
+ * `diagramSourceLineOffset: 0` is the load-bearing part. `DiagramBlock` passes
+ * it as the viewer's `sourceLineOffset` and the codec adds it to the 1-based
+ * line WITHIN the diagram source; for a fence that offset is the fence's own
+ * opening line, which sits one line above the diagram's first line. A diagram
+ * FILE has no fence, so its first line is document line 1 and the offset is 0
+ * — the 1 a synthesized ```mermaid wrapper would produce puts every exported
+ * diagram line one too high. `startLine`/`sourceLineCount` still describe the
+ * block itself, so the export's `(lines a–b)` label names the file's real
+ * span.
+ */
+export const diagramDocumentBlocks = (text: string, kind: 'mermaid' | 'graphviz'): Block[] => [
+  {
+    id: 'block-0',
+    type: 'code',
+    content: text,
+    // `dot` is what isGraphvizLanguage reads for the Graphviz engine.
+    language: kind === 'graphviz' ? 'dot' : 'mermaid',
+    order: 1,
+    startLine: 1,
+    // A trailing newline ends the last line, it does not start another.
+    sourceLineCount: text === '' ? 0 : text.replace(/\n$/, '').split('\n').length,
+    diagramSourceLineOffset: 0,
+  },
+];
+
 /**
  * A simplified markdown parser that splits content into linear blocks.
  * For a production app, we would use a robust AST walker (remark),

package/utils/sharing.ts

@@ -8,7 +8,8 @@
  * Inspired by textarea.my's approach.
  */
 
-import { AnnotationType, type Annotation, type ImageAttachment } from '../types';
+import { AnnotationType, type Annotation, type DocumentRenderAs, type ImageAttachment } from '../types';
+import { isDiagramRenderKind } from '@plannotator/core/annotatable';
 import { compress, decompress } from '@plannotator/core/compress';
 import { encrypt, decrypt } from '@plannotator/core/crypto';
 
@@ -31,6 +32,32 @@ export interface SharePayload {
   r?: 'html';  // render mode flag (omitted = markdown)
 }
 
+/**
+ * The markdown a document ships as in a share payload's `p`.
+ *
+ * A whole-file diagram source (.mmd/.dot) has no fence of its own — the
+ * annotate session renders it as one diagram because the SERVER said so in
+ * `renderAs`, and a share link carries no server. So it travels as the fenced
+ * form, which the portal's ordinary markdown parse turns back into the same
+ * diagram block. This is deliberately smaller than adding a render-mode flag
+ * (`r: 'html'`'s sibling): the portal needs no change at all.
+ *
+ * Diagram comments themselves still degrade to text comments in a share link,
+ * exactly as they do today — `diagramAnchor` is dropped like `htmlAnchor`
+ * (see sharing.multiTarget.test.ts).
+ */
+export function shareableDocumentMarkdown(
+  markdown: string,
+  renderAs: DocumentRenderAs | undefined,
+): string {
+  if (!isDiagramRenderKind(renderAs) || markdown === '') return markdown;
+  const language = renderAs === 'graphviz' ? 'dot' : 'mermaid';
+  // A diagram source can itself contain a ``` run only in a comment/label;
+  // a four-backtick fence keeps such a body intact.
+  const fence = markdown.includes('```') ? '````' : '```';
+  return `${fence}${language}\n${markdown.replace(/\n+$/, '')}\n${fence}`;
+}
+
 /**
  * Convert ShareableImage[] to ImageAttachment[] (handles old plain-string format)
  */