sysml-diagram 0.20.3 → 0.21.0

package/out/main.js

@@ -162498,8 +162498,37 @@ function disjointTargets(node) {
   return out;
 }
 var SysmlDiagramModelProvider = class _SysmlDiagramModelProvider {
+  shared;
   perParseCache = /* @__PURE__ */ new WeakMap();
   featurePaths = new FeaturePathResolver();
+  annotationFeaturePaths = /* @__PURE__ */ new Map();
+  indexEpoch = 0;
+  // REQ-210 — Annotation graphics
+  // Shared services are optional so pure single-document tests stay cheap. In
+  // production they provide both workspace documents and the linker's private
+  // lazy library documents used by inherited members.
+  constructor(shared) {
+    this.shared = shared;
+    shared?.workspace.DocumentBuilder.onBuildPhase(DocumentState.IndexedContent, () => {
+      this.indexEpoch += 1;
+    });
+  }
+  externalDocumentRoot(uri) {
+    if (!this.shared)
+      return void 0;
+    const parsed = URI2.parse(uri);
+    try {
+      const services = this.shared.ServiceRegistry.getServices(parsed);
+      const linker = services.references.Linker;
+      const linked = linker.resolveDocumentRoot?.(parsed);
+      if (linked)
+        return linked;
+    } catch {
+    }
+    if (!this.shared.workspace.LangiumDocuments.hasDocument(parsed))
+      return void 0;
+    return this.shared.workspace.LangiumDocuments.getDocument(parsed)?.parseResult?.value;
+  }
   perParse(root4) {
     let entry = this.perParseCache.get(root4);
     if (!entry) {
@@ -162528,12 +162557,52 @@ var SysmlDiagramModelProvider = class _SysmlDiagramModelProvider {
     const key = `${kind}\0${preferFileOverview ? "F" : "-"}\0${rootSymbol ?? ""}`;
     const cacheKey = kind === "grv" ? `${key}::${gridPreset}${gridPreset === "matrix" ? `::${matrixRelationship}` : ""}` : key;
     const hit = cache.models.get(cacheKey);
+    if (hit && hit.indexEpoch === this.indexEpoch && this.externalRootsAreCurrent(hit.externalRoots))
+      return hit.model;
     if (hit)
-      return hit;
+      cache.models.delete(cacheKey);
     const model = this.computeDiagramModel(document2, root4, rootSymbol, kind, preferFileOverview, gridPreset, matrixRelationship);
-    cache.models.set(cacheKey, model);
+    cache.models.set(cacheKey, {
+      model,
+      externalRoots: this.externalRootsOf(model, document2.uri.toString()),
+      indexEpoch: this.indexEpoch
+    });
     return model;
   }
+  // REQ-210 — Annotation graphics
+  // A model may project members and notes from another document. The anchor's
+  // parse identity does not change when that source file is edited, so validate
+  // those dependency roots before returning a warm per-anchor cache entry.
+  externalRootsAreCurrent(roots) {
+    for (const [uri, root4] of roots) {
+      if (this.externalDocumentRoot(uri) !== root4)
+        return false;
+    }
+    return true;
+  }
+  externalRootsOf(model, anchorUri) {
+    const uris = /* @__PURE__ */ new Set();
+    const add = (source) => {
+      if (source?.uri && source.uri !== anchorUri)
+        uris.add(source.uri);
+    };
+    for (const node of model.nodes) {
+      add(node.source);
+      for (const port of node.ports ?? [])
+        add(port.source);
+    }
+    for (const frame2 of model.frames ?? []) {
+      add(frame2.source);
+      for (const port of frame2.ports ?? [])
+        add(port.source);
+    }
+    add(model.ivBoundary?.source);
+    for (const port of model.ivBoundary?.ports ?? [])
+      add(port.source);
+    for (const edge of model.edges)
+      add(edge.source);
+    return new Map([...uris].map((uri) => [uri, this.externalDocumentRoot(uri)]));
+  }
   computeDiagramModel(document2, root4, rootSymbol, kind, preferFileOverview, gridPreset = "requirements", matrixRelationship = "allocation") {
     const uri = document2.uri.toString();
     const empty2 = (note) => ({
@@ -162549,28 +162618,126 @@ var SysmlDiagramModelProvider = class _SysmlDiagramModelProvider {
       return empty2(`No anchor element found for the ${kind.toUpperCase()} view.`);
     const ctx = { uri, index: index2, anchor, gridPreset, matrixRelationship };
     const overview = isPackage(anchor) || isDocument(anchor);
-    switch (kind) {
-      case "gv":
-        return this.buildGeneralView(ctx);
-      case "iv":
-        return overview ? this.buildInterconnectionOverview(ctx) : this.buildInterconnectionView(ctx);
-      case "afv":
-        return overview ? this.buildActionFlowOverview(ctx) : this.buildActionFlowView(ctx);
-      case "stv":
-        return overview ? this.buildStateTransitionOverview(ctx) : this.buildStateTransitionView(ctx);
-      case "sv":
-        return overview ? this.buildSequenceOverview(ctx) : this.buildSequenceView(ctx);
-      case "cv":
-        return this.buildCaseView(ctx);
-      case "gev":
-        return overview ? this.buildGeometryOverview(ctx) : this.buildGeometryView(ctx);
-      case "grv":
-        return this.buildGridView(ctx);
-      case "bv":
-        return this.buildBrowserView(ctx);
-      default:
-        return empty2(`Unsupported diagram kind ${kind}.`);
+    const build = () => {
+      switch (kind) {
+        case "gv":
+          return this.buildGeneralView(ctx);
+        case "iv":
+          return overview ? this.buildInterconnectionOverview(ctx) : this.buildInterconnectionView(ctx);
+        case "afv":
+          return overview ? this.buildActionFlowOverview(ctx) : this.buildActionFlowView(ctx);
+        case "stv":
+          return overview ? this.buildStateTransitionOverview(ctx) : this.buildStateTransitionView(ctx);
+        case "sv":
+          return overview ? this.buildSequenceOverview(ctx) : this.buildSequenceView(ctx);
+        case "cv":
+          return this.buildCaseView(ctx);
+        case "gev":
+          return overview ? this.buildGeometryOverview(ctx) : this.buildGeometryView(ctx);
+        case "grv":
+          return this.buildGridView(ctx);
+        case "bv":
+          return this.buildBrowserView(ctx);
+        default:
+          return empty2(`Unsupported diagram kind ${kind}.`);
+      }
+    };
+    return this.withNotes(build(), root4, index2, uri);
+  }
+  // REQ-210 — Annotation graphics
+  // issue #229: attach the modeled notes of every DRAWN element to that
+  // element, on every view.
+  //
+  // The General View builds its own richer annotation pass (comment + rep +
+  // metadata, with package placement), the Browser View lists annotations as
+  // tree rows, and the Grid View is a table, so all three are left untouched.
+  // Every other view gets its notes here, once, after the builder (and its
+  // overview tiling / id prefixing) has settled the final node ids.
+  //
+  // A `comment` is always a note. A `doc` documents its owner and already has
+  // a textual home in that owner's `doc` compartment (issue #107), so it only
+  // becomes a note on the views that draw no compartments at all.
+  withNotes(model, root4, index2, uri) {
+    if (model.kind === "gv" || model.kind === "bv" || model.kind === "grv")
+      return model;
+    const docAsNote = model.kind === "sv" || model.kind === "gev";
+    const drawn = /* @__PURE__ */ new Map();
+    const externalUris = /* @__PURE__ */ new Set();
+    const key = (source) => source && `${source.uri}:${source.range.start.line}:${source.range.start.character}`;
+    const claim = (source, target) => {
+      const k = key(source);
+      if (!k)
+        return;
+      if (source && source.uri !== uri)
+        externalUris.add(source.uri);
+      const list = drawn.get(k);
+      if (list)
+        list.push(target);
+      else
+        drawn.set(k, [target]);
+    };
+    for (const n2 of model.nodes) {
+      claim(n2.source, { id: n2.id, parent: n2.parent, frame: n2.frame });
+      for (const port of n2.ports ?? []) {
+        claim(port.source, { id: port.id, parent: n2.parent, frame: n2.frame, port: true });
+      }
+    }
+    for (const f of model.frames ?? []) {
+      claim(f.source, { id: f.id, frame: f.id });
+      for (const port of f.ports ?? []) {
+        claim(port.source, { id: port.id, frame: f.id, port: true });
+      }
+    }
+    if (model.ivBoundary) {
+      claim(model.ivBoundary.source, { id: model.ivBoundary.id, frame: model.ivBoundary.id });
+      for (const port of model.ivBoundary.ports ?? []) {
+        claim(port.source, { id: port.id, frame: model.ivBoundary.id, port: true });
+      }
+    }
+    if (!drawn.size)
+      return model;
+    const nodes = [...model.nodes];
+    const edges = [...model.edges];
+    let noteCount = 0;
+    let edgeCount = edges.length;
+    const note = (annotation) => {
+      const targets = drawn.get(key(sourceOf2(annotation.owner, uri)) ?? "")?.filter((target) => annotation.keyword !== "doc" || docAsNote || target.port);
+      if (!targets?.length)
+        return;
+      for (const target of targets) {
+        const id2 = `__note_${noteCount++}__`;
+        nodes.push({
+          id: id2,
+          name: annotation.label,
+          keyword: annotation.keyword,
+          isDef: false,
+          shape: "annotation",
+          type: annotation.body,
+          // Sit in the same container as the element the note is about,
+          // so the note travels with it instead of floating at the root.
+          ...target.parent ? { parent: target.parent } : {},
+          ...target.frame ? { frame: target.frame } : {},
+          source: sourceOf2(annotation.annotation, uri)
+        });
+        edges.push({
+          id: `e${edgeCount++}`,
+          from: id2,
+          to: target.id,
+          kind: "annotation",
+          source: sourceOf2(annotation.annotation, uri)
+        });
+      }
+    };
+    for (const annotation of this.semanticAnnotations(root4, index2))
+      note(annotation);
+    for (const externalUri of externalUris) {
+      const externalRoot = this.externalDocumentRoot(externalUri);
+      if (externalRoot) {
+        for (const annotation of this.semanticAnnotations(externalRoot, this.localIndex(externalRoot)))
+          note(annotation);
+      }
     }
+    return noteCount ? { ...model, nodes, edges } : model;
   }
   // REQ-224 — Detect the file/anchor-specific view kinds that will render
   // substantive diagram content. The extension uses this to limit the
@@ -162649,6 +162816,132 @@ var SysmlDiagramModelProvider = class _SysmlDiagramModelProvider {
     cache.contents = contents;
     return contents;
   }
+  // REQ-210 — Annotation graphics
+  // Keep the whole-document filter out of each view build. Target resolution
+  // remains live because the workspace index can become more complete without
+  // reparsing the document.
+  annotationMembers(root4) {
+    const cache = this.perParse(root4);
+    if (cache.annotations)
+      return cache.annotations;
+    const comments = [];
+    const docs = [];
+    for (const node of [root4, ...this.rootContents(root4)]) {
+      if (node.$type === "CommentStmt")
+        comments.push(node);
+      else if (node.$type === "DocCommentMember")
+        docs.push(node);
+    }
+    cache.annotations = { comments, docs };
+    return cache.annotations;
+  }
+  // REQ-210 — Annotation graphics
+  // Resolve a document's modeled annotations once for every workspace-index
+  // epoch. Different diagram kinds then only match semantic owners to their
+  // rendered source identities instead of walking and resolving the AST again.
+  semanticAnnotations(root4, index2) {
+    const cache = this.perParse(root4);
+    if (cache.semanticAnnotations?.epoch === this.indexEpoch)
+      return cache.semanticAnnotations.values;
+    const members = this.annotationMembers(root4);
+    const values2 = [];
+    for (const comment of members.comments) {
+      const rawTargets = comment.targets ?? [];
+      const owners = rawTargets.length ? this.commentTargets(comment, index2) : [comment.$container];
+      for (const owner of owners) {
+        if (!owner)
+          continue;
+        values2.push({
+          annotation: comment,
+          owner,
+          keyword: "comment",
+          label: nameOf2(comment) ?? "comment",
+          body: annotationText(trailingBlockBody(comment))
+        });
+      }
+    }
+    for (const doc of members.docs) {
+      if (!doc.$container)
+        continue;
+      values2.push({
+        annotation: doc,
+        owner: doc.$container,
+        keyword: "doc",
+        label: nameOf2(doc) ?? "doc",
+        body: annotationText(docCommentBody(doc))
+      });
+    }
+    cache.semanticAnnotations = { epoch: this.indexEpoch, values: values2 };
+    return values2;
+  }
+  annotationPathResolver(node) {
+    if (!this.shared)
+      return this.featurePaths;
+    try {
+      const services = this.shared.ServiceRegistry.getServices(ast_utils_exports.getDocument(node).uri);
+      let resolver = this.annotationFeaturePaths.get(services);
+      if (!resolver) {
+        resolver = new FeaturePathResolver(services);
+        this.annotationFeaturePaths.set(services, resolver);
+      }
+      return resolver;
+    } catch {
+      return this.featurePaths;
+    }
+  }
+  annotationDescriptionNode(context, description) {
+    if (!description)
+      return void 0;
+    if (!this.shared)
+      return description.node;
+    try {
+      const services = this.shared.ServiceRegistry.getServices(ast_utils_exports.getDocument(context).uri);
+      const linker = services.references.Linker;
+      return linker.resolveIndexedNode?.(description) ?? description.node;
+    } catch {
+      return description.node;
+    }
+  }
+  // REQ-210 — Annotation graphics
+  /** Resolve every `comment about` target by semantic path identity. */
+  commentTargets(comment, index2) {
+    const rawTargets = comment.targets ?? [];
+    if (!rawTargets.length)
+      return [];
+    const root4 = this.documentRootOf(comment);
+    const all = [root4, ...this.rootContents(root4)];
+    const resolver = this.annotationPathResolver(comment);
+    const resolved = rawTargets.map((raw, occurrence) => {
+      const segment = resolver.resolvePropertyPath(comment, "targets", occurrence).segments.at(-1);
+      const linked = segment?.target ?? this.annotationDescriptionNode(comment, segment?.description);
+      if (linked)
+        return linked;
+      const path10 = this.featurePath(raw)?.trim();
+      if (!path10)
+        return void 0;
+      const unrooted = path10.replace(/^\s*\$\s*::\s*/u, "");
+      if (!/::|\./u.test(unrooted)) {
+        for (let scope = comment.$container; scope; scope = scope.$container) {
+          const local = membersOf(scope).find((member) => member !== comment && nameOf2(member) === unrooted);
+          if (local)
+            return local;
+          const declaringIndex = this.localIndex(this.documentRootOf(scope));
+          for (const inherited of this.inheritedTypesOf(scope, declaringIndex)) {
+            const inheritedMember = membersOf(inherited).find((member) => nameOf2(member) === unrooted);
+            if (inheritedMember)
+              return inheritedMember;
+          }
+        }
+        return index2.get(unrooted);
+      }
+      const qualified = all.filter((candidate) => {
+        const qname = qnameOf(candidate);
+        return qname.length > 0 && pathMatchesQName(unrooted, qname);
+      });
+      return qualified.length === 1 ? qualified[0] : void 0;
+    }).filter((target) => target !== void 0);
+    return [...new Set(resolved)];
+  }
   // REQ-192/REQ-193 — prefer Langium's linked typing target. The diagram's
   // local index deliberately contains only the active document, so consulting
   // it alone drops structure declared in an imported workspace/library file
@@ -163723,8 +164016,7 @@ var SysmlDiagramModelProvider = class _SysmlDiagramModelProvider {
       }
     }
     let annotationCount = 0;
-    const annotate = (m, keyword, label, detail, target) => {
-      const owner = target ?? m.$container;
+    const annotate = (m, keyword, label, detail, targets) => {
       const annId = `__annotation_${annotationCount++}__`;
       nodes.push({
         id: annId,
@@ -163736,17 +164028,33 @@ var SysmlDiagramModelProvider = class _SysmlDiagramModelProvider {
         ...packageOf2(m),
         source: sourceOf2(m, uri)
       });
-      if (owner && ids.has(owner)) {
-        edges.push({ id: `e${e++}`, from: annId, to: ids.get(owner), kind: "annotation", source: sourceOf2(m, uri) });
+      const owners = targets?.length ? targets : m.$container ? [m.$container] : [];
+      for (const owner of new Set(owners)) {
+        if (!ids.has(owner))
+          continue;
+        edges.push({
+          id: `e${e++}`,
+          from: annId,
+          to: ids.get(owner),
+          kind: "annotation",
+          source: sourceOf2(m, uri)
+        });
+      }
+    };
+    const drawnAnnotationTarget = (target) => {
+      for (let current2 = target; current2; current2 = current2.$container) {
+        if (ids.has(current2))
+          return current2;
       }
+      return void 0;
     };
     for (const m of all) {
       if (m.$type === "CommentStmt") {
-        const targets = m.targets ?? [];
-        const target = targets.length ? byName.get(lastSeg(String(this.featurePath(targets[0]) ?? ""))) : void 0;
-        if (targets.length && !target)
+        const rawTargets = m.targets ?? [];
+        const targets = rawTargets.length ? this.commentTargets(m, index2).map(drawnAnnotationTarget).filter((target) => target !== void 0) : void 0;
+        if (rawTargets.length && !targets?.length)
           continue;
-        annotate(m, "comment", nameOf2(m) ?? "comment", annotationText(trailingBlockBody(m)), target);
+        annotate(m, "comment", nameOf2(m) ?? "comment", annotationText(trailingBlockBody(m)), targets);
       } else if (m.$type === "RepStmt") {
         const lang = `language "${String(m.language ?? "")}"`;
         const body = annotationText(trailingBlockBody(m));
@@ -163757,7 +164065,7 @@ var SysmlDiagramModelProvider = class _SysmlDiagramModelProvider {
           continue;
         const body = annotationText(docCommentBody(m));
         if (body)
-          annotate(m, "doc", nameOf2(m) ?? "doc", body, owner);
+          annotate(m, "doc", nameOf2(m) ?? "doc", body, owner ? [owner] : void 0);
       } else if (isMetadataDecl(m) && m.isDef !== true && (nameOf2(m) || typeText(m)) && !ids.has(m)) {
         const attrs = metadataAttrsText(m);
         const detail = typeText(m) ? `${typeText(m)}${attrs ? ` { ${attrs} }` : ""}` : attrs;
@@ -178003,6 +178311,20 @@ var SysmlLinker = class extends DefaultLinker {
   resolveIndexedNode(nodeDescription) {
     return this.loadAstNode(nodeDescription);
   }
+  // REQ-210 — Annotation graphics
+  /**
+   * Return the parsed root for a live workspace or lazily loaded library file.
+   * Diagram projection uses this to collect annotations declared beside an
+   * inherited member without adding standard-library files to the workspace.
+   */
+  resolveDocumentRoot(uri) {
+    const live = this.langiumDocuments().getDocument(uri)?.parseResult?.value;
+    if (live)
+      return live;
+    if (!isStandardLibraryUri(uri))
+      return void 0;
+    return this.parsedLibraryDocument(uri)?.parseResult?.value;
+  }
   /** Parse (once) the standard-library file a precomputed description points at.
    *  Prefers an already-live workspace document when one exists (runtime-loaded
    *  library, or the user opened the file) so there is never a second copy. */
@@ -182200,6 +182522,7 @@ function portLabelPlacement(side, x, y, label, half = PORT_GLYPH_HALF, alongHalf
 }
 var SEQ_MSG_TOP = 76;
 var SEQ_MSG_GAP = 46;
+var SEQ_NOTE_GAP = 40;
 function sequenceSlotBoundaryY(slot) {
   return SEQ_MSG_TOP + (slot - 0.5) * SEQ_MSG_GAP;
 }
@@ -182298,6 +182621,12 @@ function gvNodeCategory(node) {
   };
   return alias[k] ?? "other";
 }
+function withoutOrphanedAnnotations(original, nodes, edges) {
+  const originallyAttached = new Set(original.edges.filter((edge) => edge.kind === "annotation").map((edge) => edge.from));
+  if (originallyAttached.size === 0) return nodes;
+  const stillAttached = new Set(edges.filter((edge) => edge.kind === "annotation").map((edge) => edge.from));
+  return nodes.filter((node) => node.shape !== "annotation" || !originallyAttached.has(node.id) || stillAttached.has(node.id));
+}
 function applyGvFilters(model, hidden) {
   if (model.kind !== "gv" || hidden.size === 0) return model;
   const nodes = model.nodes.filter((n2) => n2.shape === "package" || !hidden.has(gvNodeCategory(n2)));
@@ -182308,7 +182637,7 @@ function applyGvFilters(model, hidden) {
     for (const p of n2.ports ?? []) keptIds.add(p.id);
   }
   const edges = model.edges.filter((e) => keptIds.has(e.from) && keptIds.has(e.to));
-  return { ...model, nodes, edges };
+  return { ...model, nodes: withoutOrphanedAnnotations(model, nodes, edges), edges };
 }
 var PAD = 10;
 var NODE_W = 168;
@@ -182805,9 +183134,10 @@ function applyCaseDefs(model, show) {
   if (hidden.size === 0) return model;
   const edges = model.edges.filter((e) => !hidden.has(e.from) && !hidden.has(e.to));
   const retainedEndpoints = new Set(edges.flatMap((edge) => [edge.from, edge.to]));
+  const nodes = model.nodes.filter((n2) => !hidden.has(n2.id) && (n2.meta?.cvAuxiliary !== true || retainedEndpoints.has(n2.id)));
   return {
     ...model,
-    nodes: model.nodes.filter((n2) => !hidden.has(n2.id) && (n2.meta?.cvAuxiliary !== true || retainedEndpoints.has(n2.id))),
+    nodes: withoutOrphanedAnnotations(model, nodes, edges),
     edges
   };
 }
@@ -182887,7 +183217,7 @@ function applyBehaviorFilters(model, filters) {
     ...nextFrames.flatMap((f) => (f.ports ?? []).map((p) => p.id))
   ]);
   const edges = model.edges.filter((e) => !(model.kind === "afv" && !filters.definedBy && e.kind === "definedBy") && !hiddenPortIds.has(e.from) && !hiddenPortIds.has(e.to) && liveIds.has(e.from) && liveIds.has(e.to));
-  return { ...model, frames: nextFrames, nodes, edges };
+  return { ...model, frames: nextFrames, nodes: withoutOrphanedAnnotations(model, nodes, edges), edges };
 }
 function collapseIvModel(model, hiddenInternals) {
   const frames = model.frames ?? [];
@@ -183496,6 +183826,7 @@ var GEO_TARGET_H = 520;
 var GEO_DEF_W = 400;
 var GEO_DEF_H = 300;
 var GEO_STRIP_GAP = 16;
+var GEO_STRIP_INSET = 16;
 var GEO_FRAME_ID = "__geoframe__";
 var GEO_EMPTY_W = 560;
 var GEO_EMPTY_H = 320;
@@ -183564,7 +183895,7 @@ function layoutGeometry(nodes, edges, meta) {
     const frame2 = makeGeoFrameNode(kind, GEO_EMPTY_W, GEO_EMPTY_H, {
       geoEmpty: { hLabel: axes.h ?? "x", vLabel: axes.v ?? "z", unit }
     });
-    placeStrip(strip, GEO_MARGIN_LEFT + 16, GEO_EMPTY_H + GEO_STRIP_GAP);
+    placeStrip(strip, GEO_MARGIN_LEFT + GEO_STRIP_INSET, GEO_EMPTY_H + GEO_STRIP_GAP);
     return { nodes: [frame2, ...strip], edges };
   }
   const is3d = placed.some((n2) => n2.data.node.geo.shape !== void 0 || n2.data.node.geo.z !== void 0);
@@ -195490,13 +195821,18 @@ var SEQ_EVENT_GAP = 22;
 function layoutSequence(nodes, edges, overrides) {
   const ov = overrides ?? {};
   const lifelines = nodes.filter((n2) => n2.data.node?.shape === "lifeline").sort((a2, b) => Number(a2.data.node?.meta?.order ?? 0) - Number(b.data.node?.meta?.order ?? 0));
+  const lifelineIds = new Set(lifelines.map((n2) => n2.id));
+  const noteNodes = nodes.filter((n2) => n2.data.node?.shape === "annotation");
+  const isMessage = (edge) => edge.data?.edge.kind === "message" && lifelineIds.has(edge.source) && lifelineIds.has(edge.target);
+  const nonMessageEdges = edges.filter((edge) => !isMessage(edge));
+  const msgs = edges.filter(isMessage);
   const slotFor = (e, i) => {
     const s = e.data?.edge.meta?.slot;
     return typeof s === "number" && Number.isFinite(s) && s >= 0 ? s : i;
   };
-  const msgY = edges.map((e, i) => MSG_TOP + slotFor(e, i) * MSG_GAP);
-  const lastMsgY = edges.length ? Math.max(...msgY) : MSG_TOP;
-  let maxSlot = edges.length ? Math.max(...edges.map(slotFor)) : -1;
+  const msgY = msgs.map((e, i) => MSG_TOP + slotFor(e, i) * MSG_GAP);
+  const lastMsgY = msgs.length ? Math.max(...msgY) : MSG_TOP;
+  let maxSlot = msgs.length ? Math.max(...msgs.map(slotFor)) : -1;
   const eventBase = lastMsgY + 22;
   let maxEventY = 0;
   const eventsByLifeline = /* @__PURE__ */ new Map();
@@ -195519,7 +195855,7 @@ function layoutSequence(nodes, edges, overrides) {
     baseX.push(cursorX);
     cursorX += n2.data.w + LIFELINE_MIN_GAP;
   }
-  const msgHandles = edges.map((_edge, i) => ({ id: `m${i}`, y: msgY[i] }));
+  const msgHandles = msgs.map((_edge, i) => ({ id: `m${i}`, y: msgY[i] }));
   const insertHandles = Array.from({ length: Math.max(maxSlot, -1) + 2 }, (_2, k) => ({
     id: `d${k}`,
     y: sequenceSlotBoundaryY(k),
@@ -195530,7 +195866,7 @@ function layoutSequence(nodes, edges, overrides) {
     const w = n2.data.w;
     const x = overrideFor(n2, ov)?.x ?? baseX[i];
     xOf.set(n2.id, x + w / 2);
-    const ys = edges.map((e, idx) => e.source === n2.id || e.target === n2.id ? msgY[idx] : void 0).filter((y) => y != null);
+    const ys = msgs.map((e, idx) => e.source === n2.id || e.target === n2.id ? msgY[idx] : void 0).filter((y) => y != null);
     const activation = ys.length ? { from: Math.min(...ys) - 6, to: Math.max(...ys) + 6 } : void 0;
     return {
       ...n2,
@@ -195549,7 +195885,7 @@ function layoutSequence(nodes, edges, overrides) {
       draggable: true
     };
   });
-  const outEdges = edges.map((e, i) => {
+  const outEdges = msgs.map((e, i) => {
     const y = msgY[i];
     return {
       ...e,
@@ -195586,7 +195922,21 @@ function layoutSequence(nodes, edges, overrides) {
     const h = Math.max(40, bottom - top);
     return { ...n2, position: { x: left, y: top }, width: w, height: h, data: { ...n2.data, w, h }, zIndex: 0 };
   });
-  return { nodes: [...fragmentNodes, ...out], edges: outEdges, height: bodyH };
+  const noteX = out.length ? Math.max(...out.map((node) => node.position.x + (node.width ?? node.data.w))) + SEQ_NOTE_GAP : 20 + SEQ_NOTE_GAP;
+  let noteY = MSG_TOP;
+  const placedNotes = noteNodes.map((n2) => {
+    const o = overrideFor(n2, ov);
+    const y = o?.y ?? noteY;
+    noteY = Math.max(noteY, y + n2.data.h + SEQ_NOTE_GAP);
+    return { ...n2, position: { x: o?.x ?? noteX, y }, draggable: true };
+  });
+  const sequenceNodes = [...fragmentNodes, ...out, ...placedNotes];
+  assignEdgeSides(sequenceNodes, nonMessageEdges);
+  return {
+    nodes: sequenceNodes,
+    edges: [...outEdges, ...nonMessageEdges],
+    height: Math.max(bodyH, noteY)
+  };
 }
 var TILE_PAD = 22;
 var TILE_HEADER = 38;
@@ -195650,7 +196000,12 @@ async function layoutTiledOverview(model, nodes, edges, args) {
     }));
     const localOverrides = overrideSubset(members, args.overrides);
     const meta = tileMeta[frame2.id];
-    const laidPromise = model.kind === "sv" ? Promise.resolve(layoutSequence(detached, tileEdges, localOverrides)) : model.kind === "gev" ? Promise.resolve(layoutGeometry(detached, tileEdges, meta ?? model.meta)) : layoutFlow(detached, tileEdges, {
+    const laidPromise = model.kind === "sv" ? Promise.resolve(layoutSequence(detached, tileEdges, localOverrides)) : model.kind === "gev" ? Promise.resolve(layoutGeometryWithAnnotationEdges(
+      detached,
+      tileEdges,
+      meta ?? model.meta,
+      args.connectPointSpacing
+    )) : layoutFlow(detached, tileEdges, {
       ...args,
       overrides: localOverrides,
       kind: args.kind ?? model.kind,
@@ -196104,13 +196459,25 @@ async function layoutBands(nodes, edges, overrides, direction = "TB", connectPoi
   assignEdgeSides(all, edges, false, connectPointSpacing);
   return { nodes: all, edges };
 }
+function layoutGeometryWithAnnotationEdges(nodes, edges, meta, connectPointSpacing = CONNECT_POINT_SPACING_DEFAULT) {
+  const laid = layoutGeometry(nodes, edges, meta);
+  assignEdgeSides(
+    laid.nodes,
+    laid.edges.filter((edge) => edge.data?.edge.kind === "annotation"),
+    false,
+    connectPointSpacing
+  );
+  return laid;
+}
 async function layoutDiagram(model, nodes, edges, args) {
   const { kind, direction, overrides, connectPointSpacing } = args;
   if (model.meta?.groupMode === "tiled-h" || model.meta?.groupMode === "tiled-v") {
     return layoutTiledOverview(model, nodes, edges, { direction, overrides, kind, connectPointSpacing });
   }
   const profile2 = profileFor(kind);
-  if (profile2.layout === "geometry") return layoutGeometry(nodes, edges, model.meta);
+  if (profile2.layout === "geometry") {
+    return layoutGeometryWithAnnotationEdges(nodes, edges, model.meta, connectPointSpacing);
+  }
   if (profile2.layout === "sequence") return layoutSequence(nodes, edges, overrides);
   if (kind === "gv" && (args.gvMode ?? "group") === "group") {
     return layoutBands(nodes, edges, overrides, direction, connectPointSpacing);
@@ -198610,7 +198977,7 @@ function getViewState(sc, anchor, kind) {
 }
 
 // src/node-markup.tsx
-var import_react10 = __toESM(require_react(), 1);
+var import_react11 = __toESM(require_react(), 1);
 var import_server = __toESM(require_server_node(), 1);
 
 // ../extension/src/webview/diagram/flow/context.ts
@@ -198661,7 +199028,7 @@ function useDiagram() {
 }
 
 // ../extension/src/webview/diagram/flow/nodes.tsx
-var import_react8 = __toESM(require_react());
+var import_react9 = __toESM(require_react());
 
 // ../extension/src/webview/diagram/derive.ts
 function edgeKindLabel(kind) {
@@ -199014,6 +199381,7 @@ var DIRECT_NAME_RE = new RegExp(`^${DIRECT_NAME_SEGMENT}$`);
 var DIRECT_PATH_RE = new RegExp(`^${DIRECT_NAME_SEGMENT}(?:\\.${DIRECT_NAME_SEGMENT})*$`);
 function isWritableRelationEndpoint(endpoint) {
   if (!endpoint) return false;
+  if (endpoint.shape === "annotation") return false;
   if (pseudostateEndpointPath(endpoint.keyword)) return true;
   if (!endpoint.source || /^__flow_\d+__(?:\.|$)/u.test(endpoint.id)) return false;
   if (!endpoint.name.trim() && ["if", "while", "loop", "for"].includes(endpoint.keyword.trim().toLowerCase())) return true;
@@ -199034,6 +199402,7 @@ var TERMINAL_RELATION = "finish";
 function relationToolsForNode(keyword, viewKind, shape) {
   const { base, isDefinition, isDecision } = normalizedElementKeyword(keyword);
   const tools = TOOLBOX[viewKind]?.relations ?? [];
+  if (shape === "annotation") return [];
   if (viewKind === "afv" && ["if", "while", "loop", "for"].includes(base)) {
     return tools.filter((tool) => tool.kind === "terminate");
   }
@@ -199110,6 +199479,12 @@ function relationToolsForNode(keyword, viewKind, shape) {
 var import_react7 = __toESM(require_react());
 var import_jsx_runtime3 = __toESM(require_jsx_runtime());
 var ptStr = (pts) => pts.map((p) => `${p[0].toFixed(1)},${p[1].toFixed(1)}`).join(" ");
+var GEO_HANDLE_POSITION = {
+  top: Position3.Top,
+  right: Position3.Right,
+  bottom: Position3.Bottom,
+  left: Position3.Left
+};
 function niceStep(range, target = 5) {
   if (!(range > 0)) return 1;
   const raw = range / target;
@@ -199324,7 +199699,7 @@ function GeoShapeNode({ id: id2, data, selected: selected2 }) {
   const origin = data.origin;
   const iso = data.geo3d && node.geo && origin;
   const approx = node.geo?.approx;
-  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
     "div",
     {
       className: `rf-node rf-geo${selected2 ? " selected" : ""}${approx ? " dgeo-approx" : ""}`,
@@ -199334,19 +199709,38 @@ function GeoShapeNode({ id: id2, data, selected: selected2 }) {
         e.stopPropagation();
         ctx.onContextNode(id2, e.clientX, e.clientY);
       },
-      children: /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("svg", { className: "rf-node-svg", width: w, height: h, style: { overflow: "visible" }, children: [
-        iso ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_jsx_runtime3.Fragment, { children: [
-          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("g", { className: `dgeo3d-node${selected2 ? " selected" : ""}`, transform: `translate(${-origin.x},${-origin.y})`, children: geoShapeBody(node, data.geo3d) }),
-          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("text", { className: "dgeo3d-name", x: w / 2, y: -3, textAnchor: "middle", children: node.name })
-        ] }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_jsx_runtime3.Fragment, { children: [
-          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("rect", { className: `dnode-rect${selected2 ? " selected" : ""}`, x: 0, y: 0, width: w, height: h, rx: node.isDef ? 0 : 12 }),
-          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("text", { className: "dnode-label", x: w / 2, y: h / 2 + 3, textAnchor: "middle", children: node.name })
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("svg", { className: "rf-node-svg", width: w, height: h, style: { overflow: "visible" }, children: [
+          iso ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_jsx_runtime3.Fragment, { children: [
+            /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("g", { className: `dgeo3d-node${selected2 ? " selected" : ""}`, transform: `translate(${-origin.x},${-origin.y})`, children: geoShapeBody(node, data.geo3d) }),
+            /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("text", { className: "dgeo3d-name", x: w / 2, y: -3, textAnchor: "middle", children: node.name })
+          ] }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_jsx_runtime3.Fragment, { children: [
+            /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("rect", { className: `dnode-rect${selected2 ? " selected" : ""}`, x: 0, y: 0, width: w, height: h, rx: node.isDef ? 0 : 12 }),
+            /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("text", { className: "dnode-label", x: w / 2, y: h / 2 + 3, textAnchor: "middle", children: node.name })
+          ] }),
+          approx ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("text", { className: "dgeo-approx-mark", x: w - 2, y: -3, textAnchor: "end", children: [
+            "\u26A0",
+            /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("title", { children: `${node.name}: ${approx}` })
+          ] }) : null
         ] }),
-        approx ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("text", { className: "dgeo-approx-mark", x: w - 2, y: -3, textAnchor: "end", children: [
-          "\u26A0",
-          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("title", { children: `${node.name}: ${approx}` })
-        ] }) : null
-      ] })
+        PORT_DOCK_SIDES.flatMap((side) => (data.edgeSideAnchors?.[side] ?? []).map((offset2) => {
+          const point = sidePoint(side, offset2, w, h);
+          return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+            Handle,
+            {
+              type: "target",
+              id: sideAnchorHandleId(side, offset2),
+              position: GEO_HANDLE_POSITION[side],
+              style: { left: point.x, top: point.y, transform: "translate(-50%,-50%)" },
+              className: "rf-handle rf-handle-side",
+              isConnectable: true,
+              isConnectableStart: false,
+              isConnectableEnd: true
+            },
+            `${side}-${offset2}`
+          );
+        }))
+      ]
     }
   );
 }
@@ -199475,8 +199869,8 @@ function mountedNodeSidePointOffsets(data, side, connectable, exposeAll) {
 function useMountedHandleRegistration(id2, sideOffsets) {
   const mountedKey = mountedHandleKey(sideOffsets);
   const updateNodeInternals2 = useUpdateNodeInternals();
-  const lastKeyRef = (0, import_react8.useRef)(mountedKey);
-  (0, import_react8.useEffect)(() => {
+  const lastKeyRef = (0, import_react9.useRef)(mountedKey);
+  (0, import_react9.useEffect)(() => {
     if (lastKeyRef.current === mountedKey) return;
     lastKeyRef.current = mountedKey;
     updateNodeInternals2(id2);
@@ -199493,9 +199887,9 @@ var SIDE_NORMAL = {
 };
 var clampOffset = (v) => Math.max(0.06, Math.min(0.94, v));
 function usePortDrag(containerRef, w, h, topReserve, onPortMove, onPortPreview, onSelect) {
-  const [dragId, setDragId] = (0, import_react8.useState)(void 0);
-  const gestureRef = (0, import_react8.useRef)(void 0);
-  (0, import_react8.useEffect)(() => () => gestureRef.current?.abort(), []);
+  const [dragId, setDragId] = (0, import_react9.useState)(void 0);
+  const gestureRef = (0, import_react9.useRef)(void 0);
+  (0, import_react9.useEffect)(() => () => gestureRef.current?.abort(), []);
   const onPortPointerDown = (portId, e, origin, draggable = true) => {
     if (e.button !== 0) return;
     e.stopPropagation();
@@ -200170,8 +200564,8 @@ function ContainerControls({
   ] });
 }
 function InlineEditor({ initial, mode, elementKind, onCommit, onCancel, w }) {
-  const ref = (0, import_react8.useRef)(null);
-  (0, import_react8.useEffect)(() => {
+  const ref = (0, import_react9.useRef)(null);
+  (0, import_react9.useEffect)(() => {
     const el2 = ref.current;
     if (el2) {
       el2.focus();
@@ -200269,7 +200663,7 @@ function shapeBody(node, data) {
 var CLIP_EXEMPT = /* @__PURE__ */ new Set(["fork", "join", "dot", "initial", "final", "terminate", "lifeline", "actor"]);
 function NodeBody({ node, data, selectedPortId, hoveredPortId, movingPortId, connectTargetPortId, connectTargetPortSide, showPortConnectStart, onPortSelect, onPortContext }) {
   const { w, h } = data;
-  const rawId = (0, import_react8.useId)();
+  const rawId = (0, import_react9.useId)();
   const clipId = `dnode-clip-${rawId.replace(/[^a-zA-Z0-9_-]/g, "")}`;
   const clip = !CLIP_EXEMPT.has(node.shape) || data.kind === "gv" && node.shape === "actor";
   const elementColorClass = diagramElementColorClass(diagramElementColorTypeForNode(node.shape, node.keyword));
@@ -200316,7 +200710,7 @@ function SysmlNode({ id: id2, data, draggable, selected: selected2, width, heigh
   const internalNoun = INTERNAL_NOUN[data.kind] ?? "internal parts";
   const featureCompartmentsVisible = node.meta?.featureCompartmentsVisible === true;
   const featureCompartmentHeight = featureBandTopReserve(data);
-  const containerRef = (0, import_react8.useRef)(null);
+  const containerRef = (0, import_react9.useRef)(null);
   const portSource = (pid) => {
     const p = node.ports?.find((pp) => pp.id === pid);
     ctx.onPortSelected?.();
@@ -200343,8 +200737,8 @@ function SysmlNode({ id: id2, data, draggable, selected: selected2, width, heigh
   const nodeSideStartable = directRelation !== void 0 && data.kind !== "sv" && node.shape !== "lifeline" && !isPackageEndpoint(node.shape, node.keyword);
   const selectedPortId = useInteraction(ctx.store, (s) => typeof s.selectedId === "string" && myPortIds.includes(s.selectedId) ? s.selectedId : void 0);
   const dropClass = useDropState(ctx.store, id2);
-  const [hoveredPortId, setHoveredPortId] = (0, import_react8.useState)(void 0);
-  const [sidePointsHovered, setSidePointsHovered] = (0, import_react8.useState)(false);
+  const [hoveredPortId, setHoveredPortId] = (0, import_react9.useState)(void 0);
+  const [sidePointsHovered, setSidePointsHovered] = (0, import_react9.useState)(false);
   const isPackageNode = isPackageEndpoint(node.shape, node.keyword);
   const sideConnectable = data.kind !== "sv" && !isPackageNode;
   const perimeterControl = keepsPerimeterSidePointsMounted(node.shape);
@@ -200655,7 +201049,7 @@ function FrameNode({ id: id2, data, selected: selected2, width, height }) {
   const h = height ?? data.h;
   const partitionKindFull = isExhibitLane ? "\xABexhibited by\xBB" : "\xABperformer\xBB";
   const partitionKindShown = fitKind(partitionKindFull, Math.max(1, w - 20));
-  const rawClipId = (0, import_react8.useId)();
+  const rawClipId = (0, import_react9.useId)();
   const clipId = `dframe-clip-${rawClipId.replace(/[^a-zA-Z0-9_-]/g, "")}`;
   const structuredPrefix = `\xAB${structuredKeyword}\xBB`;
   const structuredConditionShown = structuredCondition ? fitText(structuredCondition, Math.max(1, w - 24 - structuredPrefix.length * 9 * 0.78), 11) : "";
@@ -200683,7 +201077,7 @@ function FrameNode({ id: id2, data, selected: selected2, width, height }) {
     performer: frame2.meta?.performerLane === true,
     structured: frame2.meta?.structuredControl === true
   }));
-  const containerRef = (0, import_react8.useRef)(null);
+  const containerRef = (0, import_react9.useRef)(null);
   const portSource = (pid) => {
     ctx.onPortSelected?.();
     ctx.onReveal(frame2.ports?.find((p) => p.id === pid)?.source, pid);
@@ -200711,8 +201105,8 @@ function FrameNode({ id: id2, data, selected: selected2, width, height }) {
   const selectedPortId = useInteraction(ctx.store, (s) => typeof s.selectedId === "string" && myPortIds.includes(s.selectedId) ? s.selectedId : void 0);
   const dropClass = useDropState(ctx.store, id2);
   const editing = useInteraction(ctx.store, (s) => s.editing?.nodeId === id2 && !s.editing?.at && !s.editing?.edgeId ? s.editing : void 0);
-  const [hoveredPortId, setHoveredPortId] = (0, import_react8.useState)(void 0);
-  const [sidePointsHovered, setSidePointsHovered] = (0, import_react8.useState)(false);
+  const [hoveredPortId, setHoveredPortId] = (0, import_react9.useState)(void 0);
+  const [sidePointsHovered, setSidePointsHovered] = (0, import_react9.useState)(false);
   const sideConnectable = data.kind !== "sv" && !isPackageFrame && !isPartitionLane && !isOuterViewFrame;
   const sideOffsets = isPartitionLane ? SIDES.map(() => []) : SIDES.map((side) => mountedNodeSidePointOffsets(
     data,
@@ -201100,12 +201494,12 @@ function SeqFragmentNode({ data, width, height }) {
   ] }) });
 }
 var nodeTypes = {
-  sysml: (0, import_react8.memo)(SysmlNode),
-  frame: (0, import_react8.memo)(FrameNode),
-  lane: (0, import_react8.memo)(LaneNode),
-  seqfragment: (0, import_react8.memo)(SeqFragmentNode),
-  geo: (0, import_react8.memo)(GeoShapeNode),
-  geoframe: (0, import_react8.memo)(GeoFrameNode)
+  sysml: (0, import_react9.memo)(SysmlNode),
+  frame: (0, import_react9.memo)(FrameNode),
+  lane: (0, import_react9.memo)(LaneNode),
+  seqfragment: (0, import_react9.memo)(SeqFragmentNode),
+  geo: (0, import_react9.memo)(GeoShapeNode),
+  geoframe: (0, import_react9.memo)(GeoFrameNode)
 };
 
 // src/node-markup.tsx
@@ -201169,13 +201563,13 @@ function renderNodeBody(node, lineStyle, index2) {
     width: node.width ?? node.measured?.width ?? node.data.w,
     height: node.height ?? node.measured?.height ?? node.data.h
   };
-  const markup = (0, import_server.renderToStaticMarkup)((0, import_react10.createElement)(
+  const markup = (0, import_server.renderToStaticMarkup)((0, import_react11.createElement)(
     ReactFlowProvider,
     null,
-    (0, import_react10.createElement)(
+    (0, import_react11.createElement)(
       DiagramContext.Provider,
       { value: exportContext(lineStyle) },
-      (0, import_react10.createElement)(Component, props)
+      (0, import_react11.createElement)(Component, props)
     )
   ));
   const inner = extractNodeSvgInner(markup);
@@ -201355,7 +201749,7 @@ async function runExport(command) {
   const root4 = command.workspace ? path8.resolve(command.workspace) : findWorkspaceRoot(file);
   const settings = diagramSettingsFor(readProjectConfig(root4));
   const sideCar = command.autoLayout ? emptySideCar() : readSideCar(root4, file);
-  const provider = new SysmlDiagramModelProvider();
+  const provider = new SysmlDiagramModelProvider(services.shared);
   const kinds = command.all ? CANVAS_KINDS.filter((kind) => provider.buildAvailableDiagramKinds(document2, command.anchor).some((available) => available.kind === kind)) : [command.view ?? settings.defaultKind];
   const written = [];
   const empty2 = [];
@@ -201383,7 +201777,7 @@ async function runExport(command) {
 }
 
 // src/main.ts
-var VERSION2 = true ? "0.20.3" : "dev";
+var VERSION2 = true ? "0.21.0" : "dev";
 function display(file) {
   const rel2 = path9.relative(process.cwd(), file);
   return rel2 && !rel2.startsWith("..") ? rel2.split(path9.sep).join("/") : file;