@diagc/core 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,12 @@
 # @diagc/core
 
-The diagram model behind [`diagc`](https://www.npmjs.com/package/diagc): the `DiagramModel` types, `validate()`, the builder DSL, and the view compiler. No React, no filesystem — it does not know it is going to be drawn.
+The diagram model behind [`diagc`](https://www.npmjs.com/package/@diagc/cli): the `DiagramModel` types, `validate()`, the builder DSL, and the view compiler. No React, no filesystem — it does not know it is going to be drawn.
 
 ```bash
 npm i -D @diagc/core
 ```
 
-Install it alongside `diagc` to get types and completion when authoring `.diagram.ts` files:
+Install it alongside the CLI (`@diagc/cli`) to get types and completion when authoring `.diagram.ts` files:
 
 ```ts
 import { model } from '@diagc/core';
@@ -24,4 +24,4 @@ Docs and the full model reference: <https://github.com/Ferroman/diagc>
 
 ## License
 
-MIT
+[AGPL-3.0-only](https://github.com/Ferroman/diagc/blob/main/LICENSE), with additional permissions under section 7: diagrams you author, and the pages and images built from them, are yours to license however you like. A commercial license is available. See the [project README](https://github.com/Ferroman/diagc#license).

package/dist/builder.d.ts

@@ -1,4 +1,5 @@
-import type { Column, DiagramLegend, DiagramModel, EdgeLabel, FontScale, LayerRule, NotationId, Polarity, RelationStyle, TextAlign, TextRun, Threat } from './types.js';
+import type { Column, Comment, DiagramLegend, DiagramModel, EdgeLabel, FontScale, LayerRule, Link, NotationId, Polarity, RelationStyle, TextAlign, TextRun, Threat } from './types.js';
+import { type ElementTarget } from './comments.js';
 import { type FishbonePreset } from './fishbone.js';
 import { type Valence } from './second-order.js';
 import { type ThreatTarget } from './threat-model.js';
@@ -42,6 +43,10 @@ export interface NodeOpts {
     columns?: Column[];
     /** STRIDE findings (see DiagramNode.threats) */
     threats?: Threat[];
+    /** remarks shown in this node's bubble (see DiagramNode.comments) */
+    comments?: Comment[];
+    /** resources this node points at, listed in its bubble (see DiagramNode.links) */
+    links?: Link[];
 }
 export interface RelateOpts {
     kind: string;
@@ -63,11 +68,19 @@ export interface RelateOpts {
     toColumn?: string;
     /** STRIDE findings (see DiagramRelation.threats) */
     threats?: Threat[];
+    /** remarks shown in this relation's bubble (see DiagramRelation.comments) */
+    comments?: Comment[];
 }
 /** A threat as authored: the id is synthesized (`t1`, `t2`, …) unless given. */
 export type ThreatOpts = Omit<Threat, 'id'> & {
     id?: string;
 };
+/** A comment as authored: the id is synthesized (`c1`, `c2`, …) unless given. */
+export interface CommentOpts {
+    id?: string;
+    by?: string;
+    at?: string;
+}
 export interface ContainsOpts {
     /** plane the containment belongs to; defaults to the model's first-declared plane */
     plane?: string;
@@ -82,6 +95,10 @@ export declare class NodeRef {
      * threat-model ones: threat-modelling an existing C4 or ER diagram annotates
      * the nodes it already has. */
     threat(opts: ThreatOpts): this;
+    /** A remark on this element, shown in its bubble. */
+    comment(text: string, opts?: CommentOpts): this;
+    /** A resource this element points at, listed in its bubble. */
+    link(label: string, url: string): this;
 }
 export interface CommitOpts {
     /** default `${branchId}-${n}`, n = this branch's 1-based commit count */
@@ -189,12 +206,14 @@ export declare class FishboneBuilder {
     /** the bones of a standard set, keyed by their slug ids (`presetId`) */
     categories(preset: FishbonePreset): Record<string, CategoryRef>;
 }
-/** A data flow: a relation ref that takes threats, the way a NodeRef does. */
+/** A data flow: a relation ref that takes threats and comments, the way a NodeRef does. */
 export declare class FlowRef {
     readonly id: string;
     private readonly m;
     constructor(id: string, m: ModelBuilder);
     threat(opts: ThreatOpts): this;
+    /** A remark on this flow, shown in its bubble. */
+    comment(text: string, opts?: CommentOpts): this;
 }
 /** A DFD element's node options, minus the two its helper already supplies:
  * `type` from the helper itself, `name` from its second argument. */
@@ -217,6 +236,58 @@ export declare class ThreatModelBuilder {
     /** a data flow; a string is its label */
     flow(from: NodeRef, to: NodeRef, labelOrOpts?: string | Omit<RelateOpts, 'kind'>): FlowRef;
 }
+/** A zone's node options: the two dates are required, `type`/`plane`/`metadata`
+ * are the builder's. */
+export interface ZoneOpts extends Omit<NodeOpts, 'type' | 'metadata' | 'plane'> {
+    start: string;
+    end: string;
+}
+export interface EventOpts extends Omit<NodeOpts, 'type' | 'metadata' | 'plane'> {
+    at: string;
+}
+/**
+ * A zone: a NodeRef (so comment/link/threat compose) whose helpers nest on the
+ * PLAN plane. Everything a zone creates is scoped to that plane — a plan added
+ * to an architecture model must not leak bars into the architecture view — and
+ * every containment edge names the plane, so the plan need not be the first
+ * plane declared.
+ */
+export declare class ZoneBuilder extends NodeRef {
+    private readonly m;
+    /** the plan plane's id */
+    readonly plane: string;
+    constructor(id: string, m: ModelBuilder, 
+    /** the plan plane's id */
+    plane: string);
+    /** a nested zone */
+    zone(id: string, opts: ZoneOpts): ZoneBuilder;
+    /** an event inside this zone */
+    event(id: string, opts: EventOpts): NodeRef;
+    /** schedule any node (a C4 container, an ER table…) inside this zone */
+    contains(...nodes: NodeRef[]): this;
+    private role;
+    owner(n: NodeRef): this;
+    executor(n: NodeRef): this;
+    checker(n: NodeRef): this;
+}
+/** Root-level plan helpers; see ZoneBuilder for the nested ones. */
+export declare class PlanBuilder {
+    private readonly m;
+    readonly plane: string;
+    constructor(m: ModelBuilder, plane: string);
+    /** a top-level zone */
+    zone(id: string, opts: ZoneOpts): ZoneBuilder;
+    /** a top-level event, drawn in the header */
+    event(id: string, opts: EventOpts): NodeRef;
+    /** a person to hand roles to (`zone.owner(p)` …). `plane` is omitted, not
+     * just overridden: a person is always scoped to the plan plane, and `...opts`
+     * spreads after `plane: this.plane`, so a merely-overridden plane would
+     * silently win over the forced one. */
+    person(id: string, name?: string, opts?: Omit<ElementOpts, 'plane'>): NodeRef;
+    /** a team to hand roles to, same deal as `person` — an actor that holds a
+     * role but is never an individual. Same forced-plane guard. */
+    team(id: string, name?: string, opts?: Omit<ElementOpts, 'plane'>): NodeRef;
+}
 export interface ActivityElementOpts {
     color?: string;
 }
@@ -281,6 +352,7 @@ export declare class ModelBuilder {
     private so;
     private fb;
     private tm;
+    private pl;
     constructor(id: string, name: string);
     node(id: string, opts?: NodeOpts): NodeRef;
     /** ER table: a node of type 'db-table' carrying `columns`. */
@@ -298,6 +370,11 @@ export declare class ModelBuilder {
     /** internal — appends a threat to the node or relation `target` names; used by
      * NodeRef.threat() and FlowRef.threat() */
     addThreat(target: ThreatTarget, opts: ThreatOpts): void;
+    /** internal — appends a comment to the node or relation `target` names; used by
+     * NodeRef.comment() and FlowRef.comment() */
+    addComment(target: ElementTarget, text: string, opts: CommentOpts): void;
+    /** internal — appends a link to a node; used by NodeRef.link() */
+    addLink(nodeId: string, link: Link): void;
     relate(from: NodeRef, to: NodeRef, opts: RelateOpts): this;
     /** internal — like relate(), but returns the new relation's id (FlowRef needs
      * it to hang threats off the flow) */
@@ -353,6 +430,15 @@ export declare class ModelBuilder {
         plane?: string;
         name?: string;
     }): ThreatModelBuilder;
+    /**
+     * Declare a plan (schedule) plane. Always a plane — zones are containers with
+     * dates, and the plan's containment must not be the architecture's. Need not
+     * be the first plane: the intended use is a plan plane added to an existing
+     * model, scheduling that model's nodes inside its zones.
+     */
+    plan(id?: string, opts?: {
+        name?: string;
+    }): PlanBuilder;
     /** Declare an activity diagram: a framed swimlane flow. Repeatable — each
      * call is one frame; frames are ordinary containers on whatever plane the
      * model uses (no notation, no plane creation). */

package/dist/builder.js

@@ -1,8 +1,10 @@
+import { nextCommentId } from './comments.js';
 import { FB_CATEGORY_TYPE, FB_CAUSE_OF_KIND, FB_CAUSE_TYPE, FB_EFFECT_TYPE, FISHBONE_PRESETS, presetId } from './fishbone.js';
 import { GIT_STAGE_TYPE } from './git.js';
 import { SO_DECISION_TYPE, SO_LEADS_TO_KIND, consequenceTypeOf } from './second-order.js';
 import { TM_BOUNDARY_TYPE, TM_ENTITY_TYPE, TM_FLOW_KIND, TM_NOTATION, TM_PROCESS_TYPE, TM_STORE_TYPE, } from './threat-model.js';
 import { DiagramValidationError, validate } from './validate.js';
+import { PLAN_EVENT_TYPE, PLAN_NOTATION, PLAN_PERSON_TYPE, PLAN_TEAM_TYPE, PLAN_ZONE_TYPE } from './plan.js';
 export class NodeRef {
     id;
     builder;
@@ -27,6 +29,16 @@ export class NodeRef {
         this.builder.addThreat({ node: this.id }, opts);
         return this;
     }
+    /** A remark on this element, shown in its bubble. */
+    comment(text, opts = {}) {
+        this.builder.addComment({ node: this.id }, text, opts);
+        return this;
+    }
+    /** A resource this element points at, listed in its bubble. */
+    link(label, url) {
+        this.builder.addLink(this.id, { label, url });
+        return this;
+    }
 }
 export class CommitRef extends NodeRef {
     branch;
@@ -201,7 +213,7 @@ export class FishboneBuilder {
         }));
     }
 }
-/** A data flow: a relation ref that takes threats, the way a NodeRef does. */
+/** A data flow: a relation ref that takes threats and comments, the way a NodeRef does. */
 export class FlowRef {
     id;
     m;
@@ -213,6 +225,11 @@ export class FlowRef {
         this.m.addThreat({ relation: this.id }, opts);
         return this;
     }
+    /** A remark on this flow, shown in its bubble. */
+    comment(text, opts = {}) {
+        this.m.addComment({ relation: this.id }, text, opts);
+        return this;
+    }
 }
 /** The four DFD element kinds plus flows. Everything it hands back is an
  * ordinary NodeRef/FlowRef, so the rest of the builder — contains, relate,
@@ -247,6 +264,93 @@ export class ThreatModelBuilder {
         return new FlowRef(this.m.addRelation(from, to, { kind: TM_FLOW_KIND, ...opts }), this.m);
     }
 }
+/**
+ * A zone: a NodeRef (so comment/link/threat compose) whose helpers nest on the
+ * PLAN plane. Everything a zone creates is scoped to that plane — a plan added
+ * to an architecture model must not leak bars into the architecture view — and
+ * every containment edge names the plane, so the plan need not be the first
+ * plane declared.
+ */
+export class ZoneBuilder extends NodeRef {
+    m;
+    plane;
+    constructor(id, m, 
+    /** the plan plane's id */
+    plane) {
+        super(id, m);
+        this.m = m;
+        this.plane = plane;
+    }
+    /** a nested zone */
+    zone(id, opts) {
+        const z = planZone(this.m, this.plane, id, opts);
+        this.m.addContainment(this.id, id, this.plane);
+        return z;
+    }
+    /** an event inside this zone */
+    event(id, opts) {
+        const e = planEvent(this.m, this.plane, id, opts);
+        this.m.addContainment(this.id, id, this.plane);
+        return e;
+    }
+    /** schedule any node (a C4 container, an ER table…) inside this zone */
+    contains(...nodes) {
+        for (const n of nodes)
+            this.m.addContainment(this.id, n.id, this.plane);
+        return this;
+    }
+    role(n, kind) {
+        this.m.addRelation(n, this, { kind });
+        return this;
+    }
+    owner(n) {
+        return this.role(n, 'owns');
+    }
+    executor(n) {
+        return this.role(n, 'executes');
+    }
+    checker(n) {
+        return this.role(n, 'checks');
+    }
+}
+function planZone(m, plane, id, opts) {
+    const { start, end, ...rest } = opts;
+    m.node(id, { type: PLAN_ZONE_TYPE, plane, metadata: { start, end }, ...rest });
+    return new ZoneBuilder(id, m, plane);
+}
+function planEvent(m, plane, id, opts) {
+    const { at, ...rest } = opts;
+    return m.node(id, { type: PLAN_EVENT_TYPE, plane, metadata: { at }, ...rest });
+}
+/** Root-level plan helpers; see ZoneBuilder for the nested ones. */
+export class PlanBuilder {
+    m;
+    plane;
+    constructor(m, plane) {
+        this.m = m;
+        this.plane = plane;
+    }
+    /** a top-level zone */
+    zone(id, opts) {
+        return planZone(this.m, this.plane, id, opts);
+    }
+    /** a top-level event, drawn in the header */
+    event(id, opts) {
+        return planEvent(this.m, this.plane, id, opts);
+    }
+    /** a person to hand roles to (`zone.owner(p)` …). `plane` is omitted, not
+     * just overridden: a person is always scoped to the plan plane, and `...opts`
+     * spreads after `plane: this.plane`, so a merely-overridden plane would
+     * silently win over the forced one. */
+    person(id, name, opts = {}) {
+        return this.m.node(id, { type: PLAN_PERSON_TYPE, plane: this.plane, ...(name !== undefined ? { name } : {}), ...opts });
+    }
+    /** a team to hand roles to, same deal as `person` — an actor that holds a
+     * role but is never an individual. Same forced-plane guard. */
+    team(id, name, opts = {}) {
+        return this.m.node(id, { type: PLAN_TEAM_TYPE, plane: this.plane, ...(name !== undefined ? { name } : {}), ...opts });
+    }
+}
 /** Shared element surface of a lane and a region: each helper creates a typed
  * node contained by this scope and hands back a plain NodeRef, so everything
  * composes with the rest of the builder (relate, layers, contains). */
@@ -361,6 +465,7 @@ export class ModelBuilder {
     so;
     fb;
     tm;
+    pl;
     constructor(id, name) {
         this.id = id;
         this.name = name;
@@ -419,6 +524,33 @@ export class ModelBuilder {
         }
         element.threats = [...threats, threat];
     }
+    /** internal — appends a comment to the node or relation `target` names; used by
+     * NodeRef.comment() and FlowRef.comment() */
+    addComment(target, text, opts) {
+        const element = 'node' in target
+            ? this.nodes.find((n) => n.id === target.node)
+            : this.relations.find((r) => r.id === target.relation);
+        if (element === undefined) {
+            throw new Error('node' in target
+                ? `comment(): unknown node '${target.node}'`
+                : `comment(): unknown relation '${target.relation}'`);
+        }
+        const comments = element.comments ?? [];
+        const { id, ...rest } = opts;
+        // per-element ids, as threats: two elements' first comments are both c1
+        const comment = { id: id ?? nextCommentId(comments), text, ...pruneUndefined(rest) };
+        if (comments.some((c) => c.id === comment.id)) {
+            throw new Error(`comment(): duplicate comment id '${comment.id}' on '${element.id}'`);
+        }
+        element.comments = [...comments, comment];
+    }
+    /** internal — appends a link to a node; used by NodeRef.link() */
+    addLink(nodeId, link) {
+        const node = this.nodes.find((n) => n.id === nodeId);
+        if (node === undefined)
+            throw new Error(`link(): unknown node '${nodeId}'`);
+        node.links = [...(node.links ?? []), link];
+    }
     relate(from, to, opts) {
         this.addRelation(from, to, opts);
         return this;
@@ -523,6 +655,19 @@ export class ModelBuilder {
         this.tm = new ThreatModelBuilder(this);
         return this.tm;
     }
+    /**
+     * Declare a plan (schedule) plane. Always a plane — zones are containers with
+     * dates, and the plan's containment must not be the architecture's. Need not
+     * be the first plane: the intended use is a plan plane added to an existing
+     * model, scheduling that model's nodes inside its zones.
+     */
+    plan(id = 'plan', opts = {}) {
+        if (this.pl !== undefined)
+            throw new Error('plan() already declared');
+        this.plane(id, { name: opts.name ?? 'Plan', notation: PLAN_NOTATION });
+        this.pl = new PlanBuilder(this, id);
+        return this.pl;
+    }
     /** Declare an activity diagram: a framed swimlane flow. Repeatable — each
      * call is one frame; frames are ordinary containers on whatever plane the
      * model uses (no notation, no plane creation). */

package/dist/commands.d.ts

@@ -1,6 +1,6 @@
-import type { Column, DiagramLayer, DiagramLegend, DiagramModel, DiagramNode, DiagramPlane, Drawings, EdgeLabelPlacement, LayoutOverlay, LayoutSettings, Stroke, TextRun, Threat } from './types.js';
+import type { Column, Comment, DiagramLayer, DiagramLegend, DiagramModel, DiagramNode, DiagramPlane, Drawings, EdgeLabelPlacement, LayoutOverlay, LayoutSettings, Stroke, TextRun, Threat } from './types.js';
 import { type ThreatTarget } from './threat-model.js';
-import { type NodeDetails, type RelationOptsInput, type RelationPatch, type ThreatPatch } from './mutate.js';
+import { type CommentPatch, type NodeDetails, type PlanDates, type RelationOptsInput, type RelationPatch, type ThreatPatch } from './mutate.js';
 export interface EditorState {
     model: DiagramModel;
     layout: LayoutOverlay;
@@ -18,9 +18,13 @@ export declare function openingPins(layout: LayoutOverlay | undefined, m: Diagra
 export type EditorCommand = {
     type: 'add-node';
     node: DiagramNode;
+    /** `before`/`after` name a sibling to slot the new membership beside:
+     * child order is containment declaration order (activity lanes, git lanes) */
     parent?: {
         id: string;
         plane?: string;
+        before?: string;
+        after?: string;
     };
 } | {
     type: 'rename-node';
@@ -30,6 +34,10 @@ export type EditorCommand = {
     type: 'set-node-details';
     id: string;
     details: NodeDetails;
+} | {
+    type: 'set-plan-dates';
+    id: string;
+    dates: PlanDates;
 } | {
     type: 'set-node-rich';
     id: string;
@@ -54,6 +62,21 @@ export type EditorCommand = {
     type: 'remove-threat';
     target: ThreatTarget;
     id: string;
+}
+/** Comments ride on the element too — same target type as the threat trio. */
+ | {
+    type: 'add-comment';
+    target: ThreatTarget;
+    comment: Comment;
+} | {
+    type: 'update-comment';
+    target: ThreatTarget;
+    id: string;
+    patch: CommentPatch;
+} | {
+    type: 'remove-comment';
+    target: ThreatTarget;
+    id: string;
 } | {
     type: 'set-node-plane-hidden';
     nodeId: string;

package/dist/commands.js

@@ -1,8 +1,9 @@
 import { threatTargetKey } from './threat-model.js';
+import { hasNoteContent } from './comments.js';
 import { resolveContainmentPlane } from './view/compile.js';
 import { addStroke, deleteStroke, pruneDrawingsPlane } from './drawings.js';
 import { relationLabels } from './labels.js';
-import { addContainment, addNode, addRelation, addThreat, CommandError, deleteLayer, deleteNode, deletePlane, deleteRelation, groupNodes, mergeLayers, removeContainment, removeThreat, renameNode, setDiagramLegend, setDiagramNotation, setDiagramStyle, setNodeDetails, setNodePlaneHidden, setNodeRich, setTableColumns, subtreeOf, updateRelation, updateThreat, upsertLayer, upsertPlane, } from './mutate.js';
+import { addComment, addContainment, addNode, addRelation, addThreat, CommandError, deleteLayer, deleteNode, deletePlane, deleteRelation, groupNodes, mergeLayers, removeComment, removeContainment, removeThreat, renameNode, setDiagramLegend, setDiagramNotation, setDiagramStyle, setNodeDetails, setNodePlaneHidden, setNodeRich, setPlanDates, setTableColumns, subtreeOf, updateComment, updateRelation, updateThreat, upsertLayer, upsertPlane, } from './mutate.js';
 export const emptyLayout = () => ({ version: 1, planes: {} });
 export function layoutPlaneKey(m, plane) {
     return resolveContainmentPlane(m, plane) ?? 'default';
@@ -122,19 +123,22 @@ function withOpen(p, open) {
 }
 /**
  * Mirror hygiene for `notes` after a command changed the model: a note exists
- * only while its element has a threat, so an offset for an element that lost
- * its last threat — or was deleted — is dead data. Identity is kept when
- * nothing is dropped, like pruneEdgeLabels.
+ * only while its element has something to show, so an offset for an element
+ * that lost its last threat/comment/link — or was deleted — is dead data.
+ * `hasNoteContent` is the renderer's own test for drawing a bubble; reusing it
+ * is what stops a command that merely rewrote `nodes` (a rename, an edited
+ * comment) from throwing away a live bubble's saved place. Identity is kept
+ * when nothing is dropped, like pruneEdgeLabels.
  */
 function pruneNotes(layout, before, after) {
     if (layout.notes === undefined || (before.nodes === after.nodes && before.relations === after.relations))
         return layout;
     const alive = new Set();
     for (const n of after.nodes)
-        if ((n.threats?.length ?? 0) > 0)
+        if (hasNoteContent(n))
             alive.add(threatTargetKey({ node: n.id }));
     for (const r of after.relations)
-        if ((r.threats?.length ?? 0) > 0)
+        if (hasNoteContent(r))
             alive.add(threatTargetKey({ relation: r.id }));
     let changed = false;
     const planes = {};
@@ -241,7 +245,13 @@ function applyModelLayout(state, command) {
         case 'add-node': {
             let next = addNode(model, command.node);
             if (command.parent !== undefined) {
-                next = addContainment(next, command.parent.id, command.node.id, command.parent.plane);
+                const { id, plane, before, after } = command.parent;
+                const beside = before !== undefined
+                    ? { sibling: before, side: 'before' }
+                    : after !== undefined
+                        ? { sibling: after, side: 'after' }
+                        : undefined;
+                next = addContainment(next, id, command.node.id, plane, beside);
             }
             return { model: next, layout };
         }
@@ -249,6 +259,8 @@ function applyModelLayout(state, command) {
             return { model: renameNode(model, command.id, command.name), layout };
         case 'set-node-details':
             return { model: setNodeDetails(model, command.id, command.details), layout };
+        case 'set-plan-dates':
+            return { model: setPlanDates(model, command.id, command.dates), layout };
         case 'set-node-rich':
             return { model: setNodeRich(model, command.id, command.runs), layout };
         case 'set-table-columns':
@@ -259,6 +271,12 @@ function applyModelLayout(state, command) {
             return { model: updateThreat(model, command.target, command.id, command.patch), layout };
         case 'remove-threat':
             return { model: removeThreat(model, command.target, command.id), layout };
+        case 'add-comment':
+            return { model: addComment(model, command.target, command.comment), layout };
+        case 'update-comment':
+            return { model: updateComment(model, command.target, command.id, command.patch), layout };
+        case 'remove-comment':
+            return { model: removeComment(model, command.target, command.id), layout };
         case 'set-node-plane-hidden':
             return { model: setNodePlaneHidden(model, command.nodeId, command.plane, command.hidden), layout };
         case 'set-diagram-style':

package/dist/comments.d.ts

@@ -0,0 +1,24 @@
+import type { ThreatTarget } from './threat-model.js';
+import type { Comment, DiagramModel } from './types.js';
+/** Which element a comment command or a bubble refers to. The same two-way key
+ * threats use (`threatTargetKey` files both under `LayoutOverlay.notes`): an
+ * element has ONE bubble, whatever it holds. */
+export type ElementTarget = ThreatTarget;
+/** The element's comment list — `[]` when it carries none, undefined when there
+ * is no such element (the two are different answers; see threatsOf). */
+export declare function commentsOf(m: DiagramModel, t: ElementTarget): readonly Comment[] | undefined;
+/**
+ * Whether an element gets a note bubble: threats, comments or links. The
+ * renderer derives bubbles from this and layout hygiene keeps note entries by
+ * it — the two must never disagree, or an edit silently drops a bubble's saved
+ * place (which is what happened when they did). Structurally typed rather than
+ * taking `DiagramNode | DiagramRelation`, so a relation (which carries no
+ * `links`) answers the same question without a second predicate.
+ */
+export declare function hasNoteContent(el: {
+    threats?: readonly unknown[];
+    comments?: readonly unknown[];
+    links?: readonly unknown[];
+}): boolean;
+/** First free `c<n>` — scoped to the element, like threat ids. */
+export declare function nextCommentId(comments: readonly Comment[]): string;

package/dist/comments.js

@@ -0,0 +1,25 @@
+/** The element's comment list — `[]` when it carries none, undefined when there
+ * is no such element (the two are different answers; see threatsOf). */
+export function commentsOf(m, t) {
+    const el = 'node' in t ? m.nodes.find((n) => n.id === t.node) : m.relations.find((r) => r.id === t.relation);
+    return el === undefined ? undefined : (el.comments ?? []);
+}
+/**
+ * Whether an element gets a note bubble: threats, comments or links. The
+ * renderer derives bubbles from this and layout hygiene keeps note entries by
+ * it — the two must never disagree, or an edit silently drops a bubble's saved
+ * place (which is what happened when they did). Structurally typed rather than
+ * taking `DiagramNode | DiagramRelation`, so a relation (which carries no
+ * `links`) answers the same question without a second predicate.
+ */
+export function hasNoteContent(el) {
+    return (el.threats?.length ?? 0) > 0 || (el.comments?.length ?? 0) > 0 || (el.links?.length ?? 0) > 0;
+}
+/** First free `c<n>` — scoped to the element, like threat ids. */
+export function nextCommentId(comments) {
+    const taken = new Set(comments.map((c) => c.id));
+    let n = 1;
+    while (taken.has(`c${n}`))
+        n += 1;
+    return `c${n}`;
+}

package/dist/dates.d.ts

@@ -0,0 +1 @@
+export declare function isIsoDate(s: unknown): s is string;

package/dist/dates.js

@@ -0,0 +1,12 @@
+/** Calendar dates in the model are `YYYY-MM-DD` strings: readable in a diff,
+ * sortable as text, and free of the timezone a `Date` would smuggle in. Parsed
+ * as UTC so "2026-02-30" is caught by the round trip (Date.parse would roll it
+ * to March 2nd) rather than accepted. Shared by comments (`at`) today and by the
+ * plan notation's zones and events next. */
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+export function isIsoDate(s) {
+    if (typeof s !== 'string' || !ISO_DAY.test(s))
+        return false;
+    const t = Date.parse(`${s}T00:00:00Z`);
+    return !Number.isNaN(t) && new Date(t).toISOString().slice(0, 10) === s;
+}

package/dist/eject.js

@@ -85,7 +85,7 @@ function quoted(s) {
 const NODE_OPT_KEYS = [
     'type', 'name', 'icon', 'shape', 'image', 'color', 'textColor', 'technology',
     'link', 'description', 'rich', 'textAlign', 'fontScale', 'metadata', 'key', 'include',
-    'includePlane', 'includePlanes', 'plane', 'layer', 'columns', 'threats',
+    'includePlane', 'includePlanes', 'plane', 'layer', 'columns', 'threats', 'comments', 'links',
 ];
 // Drift guard: a field added to DiagramNode without a matching entry above
 // fails this line at `pnpm typecheck` — a future model field silently
@@ -98,7 +98,7 @@ void _nodeOptCoverage;
  * — mirrors the interface declaration in builder.ts. */
 const RELATE_OPT_KEYS = [
     'label', 'labels', 'style', 'description', 'layer', 'polarity', 'delay',
-    'fromColumn', 'toColumn', 'threats',
+    'fromColumn', 'toColumn', 'threats', 'comments',
 ];
 // Drift guard, same shape as _nodeOptCoverage above. `id` and `kind` are
 // emitted explicitly ahead of the opts object; `from`/`to` are the node refs

package/dist/index.d.ts

@@ -2,10 +2,12 @@ export declare const CORE_VERSION = 1;
 export { ejectSource } from './eject.js';
 export * from './types.js';
 export * from './mutate.js';
+export { commentsOf, hasNoteContent, nextCommentId, type ElementTarget } from './comments.js';
+export { isIsoDate } from './dates.js';
 export { normalizeRuns, runsToPlainText } from './text.js';
 export { relationLabels } from './labels.js';
 export { defaultLayoutDirection, type LayoutDirection } from './layout-defaults.js';
-export { model, ModelBuilder, NodeRef, BranchRef, CommitRef, GitGraphBuilder, ActivityBuilder, ActivityScope, LaneRef, RegionRef, ConsequenceRef, SecondOrderBuilder, FishboneBuilder, CategoryRef, CauseRef, ThreatModelBuilder, FlowRef, type NodeOpts, type RelateOpts, type CommitOpts, type StageOpts, type MergeOpts, type ActivityElementOpts, type ConsequenceOpts, type FishboneOpts, type ThreatOpts, type ElementOpts, } from './builder.js';
+export { model, ModelBuilder, NodeRef, BranchRef, CommitRef, GitGraphBuilder, ActivityBuilder, ActivityScope, LaneRef, RegionRef, ConsequenceRef, SecondOrderBuilder, FishboneBuilder, CategoryRef, CauseRef, ThreatModelBuilder, FlowRef, PlanBuilder, ZoneBuilder, type NodeOpts, type RelateOpts, type CommitOpts, type StageOpts, type MergeOpts, type ActivityElementOpts, type ConsequenceOpts, type FishboneOpts, type ThreatOpts, type CommentOpts, type ElementOpts, type ZoneOpts, type EventOpts, } from './builder.js';
 export { validate, DiagramValidationError, IMAGE_REF, LIBRARY_IMAGE_REF, type ValidationIssue } from './validate.js';
 export { isDrawings, isLayoutOverlay } from './guards.js';
 export { addStroke, deleteStroke, emptyDrawings, pruneDrawingsPlane, uniqueStrokeId } from './drawings.js';
@@ -23,3 +25,4 @@ export { GIT_KINDS, GIT_NOTATION, GIT_STAGE_TYPE, gapOf, gitGraph, isGitKind, la
 export { SECOND_ORDER_NOTATION, SO_CONSEQUENCE_TYPES, SO_DECISION_TYPE, SO_LEADS_TO_KIND, consequenceOrders, consequenceTypeOf, isSecondOrderNode, valenceOf, type ConsequenceOrders, type Valence, } from './second-order.js';
 export { FB_CATEGORY_TYPE, FB_CAUSE_OF_KIND, FB_CAUSE_TYPE, FB_EFFECT_TYPE, FISHBONE_NOTATION, FISHBONE_PRESET_NAMES, FISHBONE_PRESETS, FISHBONE_TYPES, fishboneParents, fishboneTree, isFishboneNode, presetId, type FishboneCategory, type FishboneCause, type FishbonePreset, type FishboneTree, } from './fishbone.js';
 export { TM_NOTATION, TM_ENTITY_TYPE, TM_PROCESS_TYPE, TM_STORE_TYPE, TM_BOUNDARY_TYPE, TM_FLOW_KIND, TM_TYPES, STRIDE_NAMES, NEW_THREAT_TITLE, isThreatModelNode, isOpen, strideFor, boundaryOf, boundaryName, crossings, crossingLabel, threatRegister, threatSummary, threatTargetKey, threatsOf, nextThreatId, nextThreatStatus, allNotesOpen, type ThreatTarget, type Crossing, type ThreatRow, } from './threat-model.js';
+export { PLAN_NOTATION, PLAN_ZONE_TYPE, PLAN_EVENT_TYPE, PLAN_PERSON_TYPE, PLAN_TEAM_TYPE, PLAN_ACTOR_TYPES, PLAN_TYPES, PLAN_ROLES, isPlanZone, isPlanEvent, isPlanActor, isPlanRole, dayOf, isoOf, spanOf, atOf, rolesOf, planGraph, planSubtree, type PlanRole, type PlanSpan, type PlanRoles, type PlanGraph, type PlanChildren, } from './plan.js';

package/dist/index.js

@@ -23,10 +23,12 @@ export const CORE_VERSION = 1;
 export { ejectSource } from './eject.js';
 export * from './types.js';
 export * from './mutate.js';
+export { commentsOf, hasNoteContent, nextCommentId } from './comments.js';
+export { isIsoDate } from './dates.js';
 export { normalizeRuns, runsToPlainText } from './text.js';
 export { relationLabels } from './labels.js';
 export { defaultLayoutDirection } from './layout-defaults.js';
-export { model, ModelBuilder, NodeRef, BranchRef, CommitRef, GitGraphBuilder, ActivityBuilder, ActivityScope, LaneRef, RegionRef, ConsequenceRef, SecondOrderBuilder, FishboneBuilder, CategoryRef, CauseRef, ThreatModelBuilder, FlowRef, } from './builder.js';
+export { model, ModelBuilder, NodeRef, BranchRef, CommitRef, GitGraphBuilder, ActivityBuilder, ActivityScope, LaneRef, RegionRef, ConsequenceRef, SecondOrderBuilder, FishboneBuilder, CategoryRef, CauseRef, ThreatModelBuilder, FlowRef, PlanBuilder, ZoneBuilder, } from './builder.js';
 export { validate, DiagramValidationError, IMAGE_REF, LIBRARY_IMAGE_REF } from './validate.js';
 export { isDrawings, isLayoutOverlay } from './guards.js';
 export { addStroke, deleteStroke, emptyDrawings, pruneDrawingsPlane, uniqueStrokeId } from './drawings.js';
@@ -43,3 +45,4 @@ export { GIT_KINDS, GIT_NOTATION, GIT_STAGE_TYPE, gapOf, gitGraph, isGitKind, la
 export { SECOND_ORDER_NOTATION, SO_CONSEQUENCE_TYPES, SO_DECISION_TYPE, SO_LEADS_TO_KIND, consequenceOrders, consequenceTypeOf, isSecondOrderNode, valenceOf, } from './second-order.js';
 export { FB_CATEGORY_TYPE, FB_CAUSE_OF_KIND, FB_CAUSE_TYPE, FB_EFFECT_TYPE, FISHBONE_NOTATION, FISHBONE_PRESET_NAMES, FISHBONE_PRESETS, FISHBONE_TYPES, fishboneParents, fishboneTree, isFishboneNode, presetId, } from './fishbone.js';
 export { TM_NOTATION, TM_ENTITY_TYPE, TM_PROCESS_TYPE, TM_STORE_TYPE, TM_BOUNDARY_TYPE, TM_FLOW_KIND, TM_TYPES, STRIDE_NAMES, NEW_THREAT_TITLE, isThreatModelNode, isOpen, strideFor, boundaryOf, boundaryName, crossings, crossingLabel, threatRegister, threatSummary, threatTargetKey, threatsOf, nextThreatId, nextThreatStatus, allNotesOpen, } from './threat-model.js';
+export { PLAN_NOTATION, PLAN_ZONE_TYPE, PLAN_EVENT_TYPE, PLAN_PERSON_TYPE, PLAN_TEAM_TYPE, PLAN_ACTOR_TYPES, PLAN_TYPES, PLAN_ROLES, isPlanZone, isPlanEvent, isPlanActor, isPlanRole, dayOf, isoOf, spanOf, atOf, rolesOf, planGraph, planSubtree, } from './plan.js';