@diagc/core 0.1.0 → 0.2.0

package/dist/mutate.d.ts

@@ -1,4 +1,4 @@
-import { type Column, type DiagramLayer, type DiagramLegend, type DiagramModel, type DiagramNode, type DiagramPlane, type EdgeLabel, type FontScale, type Polarity, type RelationStyle, type StrideCategory, type TextAlign, type TextRun, type Threat, type ThreatSeverity, type ThreatStatus } from './types.js';
+import { type Column, type Comment, type DiagramLayer, type DiagramLegend, type DiagramModel, type DiagramNode, type DiagramPlane, type EdgeLabel, type FontScale, type Link, type Polarity, type RelationStyle, type StrideCategory, type TextAlign, type TextRun, type Threat, type ThreatSeverity, type ThreatStatus } from './types.js';
 import type { ThreatTarget } from './threat-model.js';
 export declare class CommandError extends Error {
     constructor(message: string);
@@ -22,8 +22,20 @@ export interface NodeDetails {
     metadata?: Record<string, unknown> | null;
     plane?: string | null;
     layer?: string | null;
+    links?: Link[] | null;
 }
 export declare function setNodeDetails(m: DiagramModel, id: string, details: NodeDetails): DiagramModel;
+/** The dated keys of a plan node. A key left undefined is untouched. */
+export interface PlanDates {
+    start?: string;
+    end?: string;
+    at?: string;
+}
+/** Writes zone/event dates into `node.metadata`. Only the FORMAT is guarded
+ * here (a value that is not a real day can never be right); ordering and
+ * nesting are validation's findings, so a drag that momentarily crosses a
+ * bound still lands as a command and undo has something to undo. */
+export declare function setPlanDates(m: DiagramModel, id: string, dates: PlanDates): DiagramModel;
 /** Transitive containment descendants of `id` across every plane, plus `id`
  * itself — the set a cascade delete destroys. */
 export declare function subtreeOf(m: DiagramModel, id: string): Set<string>;
@@ -42,7 +54,20 @@ export interface ThreatPatch {
 export declare function addThreat(m: DiagramModel, target: ThreatTarget, threat: Threat): DiagramModel;
 export declare function updateThreat(m: DiagramModel, target: ThreatTarget, id: string, patch: ThreatPatch): DiagramModel;
 export declare function removeThreat(m: DiagramModel, target: ThreatTarget, id: string): DiagramModel;
-export declare function addContainment(m: DiagramModel, parent: string, child: string, plane?: string): DiagramModel;
+/** Patch for update-comment: `null` clears an optional field. `text` is
+ * required on a {@link Comment}, so it is set-only. */
+export interface CommentPatch {
+    text?: string;
+    by?: string | null;
+    at?: string | null;
+}
+export declare function addComment(m: DiagramModel, target: ThreatTarget, comment: Comment): DiagramModel;
+export declare function updateComment(m: DiagramModel, target: ThreatTarget, id: string, patch: CommentPatch): DiagramModel;
+export declare function removeComment(m: DiagramModel, target: ThreatTarget, id: string): DiagramModel;
+export declare function addContainment(m: DiagramModel, parent: string, child: string, plane?: string, beside?: {
+    sibling: string;
+    side: 'before' | 'after';
+}): DiagramModel;
 /**
  * Group existing nodes under a new abstract parent: add `node`, then nest each
  * member under it. `plane` scopes both the containment edges and (via the

package/dist/mutate.js

@@ -1,6 +1,7 @@
 import { BUILTIN_NOTATIONS, } from './types.js';
 import { normalizeRuns, runsToPlainText } from './text.js';
 import { childrenOf } from './children.js';
+import { isIsoDate } from './dates.js';
 export class CommandError extends Error {
     constructor(message) {
         super(message);
@@ -77,6 +78,7 @@ const NODE_DETAIL_KEYS = [
     'metadata',
     'plane',
     'layer',
+    'links',
 ];
 const _assertNodeKeyCoverage = true;
 void _assertNodeKeyCoverage;
@@ -95,6 +97,10 @@ export function setNodeDetails(m, id, details) {
     if (details.layer != null && !m.layers.some((l) => l.id === details.layer)) {
         throw new CommandError(`Unknown layer '${details.layer}'`);
     }
+    // An emptied list is a cleared one. A panel sends `links` whole, so deleting
+    // the last row arrives as `[]` — and a saved file must no more hold
+    // `links: []` than the threat/comment lists mapList prunes.
+    const patch = details.links?.length === 0 ? { ...details, links: null } : details;
     const nodes = m.nodes.map((n) => {
         if (n.id !== id)
             return n;
@@ -103,7 +109,7 @@ export function setNodeDetails(m, id, details) {
         // 12 hand-written applyNullable calls — adding a field wires automatically
         // and the coverage const above makes an omission a compile error.
         for (const key of NODE_DETAIL_KEYS) {
-            next = applyNullable(next, key, details[key]);
+            next = applyNullable(next, key, patch[key]);
         }
         return next;
     });
@@ -116,6 +122,28 @@ export function setNodeDetails(m, id, details) {
     }
     return next;
 }
+/** Writes zone/event dates into `node.metadata`. Only the FORMAT is guarded
+ * here (a value that is not a real day can never be right); ordering and
+ * nesting are validation's findings, so a drag that momentarily crosses a
+ * bound still lands as a command and undo has something to undo. */
+export function setPlanDates(m, id, dates) {
+    requireNode(m, id);
+    const patch = {};
+    for (const key of ['start', 'end', 'at']) {
+        const v = dates[key];
+        if (v === undefined)
+            continue;
+        if (!isIsoDate(v))
+            throw new CommandError(`'${key}' must be a YYYY-MM-DD date, got '${v}'`);
+        patch[key] = v;
+    }
+    if (Object.keys(patch).length === 0)
+        return m;
+    return {
+        ...m,
+        nodes: m.nodes.map((n) => (n.id === id ? { ...n, metadata: { ...(n.metadata ?? {}), ...patch } } : n)),
+    };
+}
 /** Drop every id satisfying `drop` from each plane's `hides`/`hidesTree`,
  * omitting emptied lists; a plane with no change keeps its reference. */
 function prunePlaneHides(planes, drop) {
@@ -173,29 +201,28 @@ export function setTableColumns(m, id, columns) {
 const THREAT_NULLABLE_KEYS = ['description', 'severity', 'status', 'mitigation'];
 const _assertThreatKeyCoverage = true;
 void _assertThreatKeyCoverage;
-/**
- * Apply `fn` to the threat list of the element `target` names. Threats hang off
- * nodes and relations alike and the list is identical on both, so one seam
- * serves the two; only the named element is replaced, every sibling keeps its
- * reference. A result with no threats drops the key entirely, keeping saved
- * files free of empty arrays.
- */
-function mapThreats(m, target, fn) {
+function mapList(m, target, key, fn) {
     const next = (items, id, what) => {
         if (!items.some((x) => x.id === id))
             throw new CommandError(`Unknown ${what} '${id}'`);
         return items.map((x) => {
             if (x.id !== id)
                 return x;
-            const threats = fn(x.threats ?? []);
-            const { threats: _dropped, ...rest } = x;
-            return (threats.length === 0 ? rest : { ...rest, threats });
+            const record = x;
+            const list = fn(record[key] ?? []);
+            // Computed-key destructuring here defeats tsc's narrowing back to `T`
+            // (the omit doesn't provably overlap); spread-then-delete keeps the same
+            // "drop the key, no empty array survives" behavior without the cast.
+            const rest = { ...record };
+            delete rest[key];
+            return (list.length === 0 ? rest : { ...rest, [key]: list });
         });
     };
     return 'node' in target
         ? { ...m, nodes: next(m.nodes, target.node, 'node') }
         : { ...m, relations: next(m.relations, target.relation, 'relation') };
 }
+const mapThreats = (m, target, fn) => mapList(m, target, 'threats', fn);
 export function addThreat(m, target, threat) {
     return mapThreats(m, target, (threats) => {
         if (threats.some((t) => t.id === threat.id))
@@ -229,6 +256,48 @@ export function removeThreat(m, target, id) {
         return threats.filter((t) => t.id !== id);
     });
 }
+const COMMENT_NULLABLE_KEYS = ['by', 'at'];
+const _assertCommentKeyCoverage = true;
+void _assertCommentKeyCoverage;
+/** A date the studio's date input could not have produced is refused here, not
+ * only at compile time: the studio autosaves on a timer, and a model that fails
+ * validation wedges that save with a 400 while the user is still typing. */
+const checkCommentDate = (at) => {
+    if (at !== undefined && at !== null && !isIsoDate(at))
+        throw new CommandError(`Comment date '${at}' is not a YYYY-MM-DD date`);
+};
+export function addComment(m, target, comment) {
+    checkCommentDate(comment.at);
+    return mapList(m, target, 'comments', (comments) => {
+        if (comments.some((c) => c.id === comment.id))
+            throw new CommandError(`Duplicate comment id '${comment.id}'`);
+        return [...comments, comment];
+    });
+}
+export function updateComment(m, target, id, patch) {
+    checkCommentDate(patch.at);
+    return mapList(m, target, 'comments', (comments) => {
+        if (!comments.some((c) => c.id === id))
+            throw new CommandError(`Unknown comment '${id}'`);
+        return comments.map((c) => {
+            if (c.id !== id)
+                return c;
+            let out = { ...c };
+            if (patch.text !== undefined)
+                out.text = patch.text;
+            for (const key of COMMENT_NULLABLE_KEYS)
+                out = applyNullable(out, key, patch[key]);
+            return out;
+        });
+    });
+}
+export function removeComment(m, target, id) {
+    return mapList(m, target, 'comments', (comments) => {
+        if (!comments.some((c) => c.id === id))
+            throw new CommandError(`Unknown comment '${id}'`);
+        return comments.filter((c) => c.id !== id);
+    });
+}
 function wouldCycle(m, parent, child, plane) {
     const defaultPlane = (m.planes ?? [])[0]?.id;
     const key = plane ?? defaultPlane;
@@ -253,7 +322,17 @@ function wouldCycle(m, parent, child, plane) {
  * Resolve a plane argument to its canonical containment form: undefined stays
  * undefined; a declared plane resolves its `containmentOf` borrow (one hop) and,
  * if that lands on the first-declared (default) plane, collapses to `undefined`
- * so edges are stored/compared in the untagged base form. Throws on unknowns.
+ * so a NEW edge is always written in the untagged base form. Throws on unknowns.
+ *
+ * That collapse is a write-time convention only — an existing edge can still
+ * carry an explicit tag for the default plane (the builder DSL always names
+ * a plan's own plane on its containment, "so the plan need not be the first
+ * plane declared", even when it happens to be first — ZoneBuilder). A caller
+ * comparing against this function's result must therefore resolve THAT side
+ * too (`e.plane ?? defaultPlane`, the same normalisation `wouldCycle` above
+ * already does for its own read), not compare `e.plane` against `canon`
+ * directly, or a builder-tagged default-plane edge never matches a command
+ * that (correctly) canonicalizes to `undefined`.
  */
 function canonicalPlane(m, plane) {
     if (plane === undefined)
@@ -265,18 +344,33 @@ function canonicalPlane(m, plane) {
     const resolved = p.containmentOf ?? p.id;
     return resolved === planes[0]?.id ? undefined : resolved;
 }
-export function addContainment(m, parent, child, plane) {
+export function addContainment(m, parent, child, plane, beside) {
     requireNode(m, parent);
     requireNode(m, child);
     if (parent === child)
         throw new CommandError(`Node '${parent}' cannot contain itself`);
     const canon = canonicalPlane(m, plane);
-    if (m.containment.some((e) => e.parent === parent && e.child === child && e.plane === canon))
+    // Resolved on both sides (see canonicalPlane's comment): an edge already in
+    // the model may carry an explicit tag for what is, today, the default
+    // plane (the builder DSL always tags a plan's containment), which a bare
+    // `e.plane === canon` would miss.
+    const defaultPlane = (m.planes ?? [])[0]?.id;
+    const key = canon ?? defaultPlane;
+    if (m.containment.some((e) => e.parent === parent && e.child === child && (e.plane ?? defaultPlane) === key))
         return m;
     if (wouldCycle(m, parent, child, canon)) {
         throw new CommandError(`'${parent}' > '${child}' would create a containment cycle`);
     }
-    return { ...m, containment: [...m.containment, { parent, child, ...(canon !== undefined ? { plane: canon } : {}) }] };
+    const edge = { parent, child, ...(canon !== undefined ? { plane: canon } : {}) };
+    if (beside === undefined)
+        return { ...m, containment: [...m.containment, edge] };
+    // Children read in declaration order, so the slot in the flat array IS the
+    // sibling order — insert next to the sibling's own membership.
+    const at = m.containment.findIndex((e) => e.parent === parent && e.child === beside.sibling && e.plane === canon);
+    if (at === -1)
+        throw new CommandError(`'${beside.sibling}' is not a child of '${parent}'`);
+    const i = beside.side === 'before' ? at : at + 1;
+    return { ...m, containment: [...m.containment.slice(0, i), edge, ...m.containment.slice(i)] };
 }
 /**
  * Group existing nodes under a new abstract parent: add `node`, then nest each
@@ -294,9 +388,13 @@ export function groupNodes(m, node, memberIds, plane) {
 }
 export function removeContainment(m, parent, child, plane) {
     const canon = canonicalPlane(m, plane);
+    // Same resolved-both-sides comparison as addContainment's duplicate check —
+    // see canonicalPlane's comment.
+    const defaultPlane = (m.planes ?? [])[0]?.id;
+    const key = canon ?? defaultPlane;
     return {
         ...m,
-        containment: m.containment.filter((e) => !(e.parent === parent && e.child === child && e.plane === canon)),
+        containment: m.containment.filter((e) => !(e.parent === parent && e.child === child && (e.plane ?? defaultPlane) === key)),
     };
 }
 /** Pin the diagram's visual style preset id, or clear it with null (the

package/dist/plan.d.ts

@@ -0,0 +1,105 @@
+import type { DiagramModel, DiagramNode } from './types.js';
+/** The notation id a plane (or the model) declares to be drawn as a schedule:
+ * a calendar left to right, zones as bars, events as diamonds, actors (people
+ * or teams) as a roster. Pure — the renderer and the studio derive everything
+ * from here. */
+export declare const PLAN_NOTATION: "plan";
+/** A zone is a CONTAINER with a span: nesting is containment, and whatever
+ * sits inside a zone is scheduled in it. */
+export declare const PLAN_ZONE_TYPE: "plan-zone";
+export declare const PLAN_EVENT_TYPE: "plan-event";
+/** The type a person carries. Deliberately the generic `person` type, not a
+ * `plan-person` of its own — a person is an ordinary node the plan merely
+ * reads, and keeps its pill on every other notation. It is named here because
+ * the builder, the roster layout, the studio's quick-add and the role pickers
+ * all key on it, and a literal in four packages is a drift waiting to happen.
+ * It is NOT in `PLAN_TYPES`: that set gates the inspector's date fields, and a
+ * person has no dates. */
+export declare const PLAN_PERSON_TYPE: "person";
+/** The type a team carries — the same deal as `PLAN_PERSON_TYPE`: a generic
+ * `team`, not a `plan-team`, so it keeps its own pill everywhere else and a
+ * role relation reads it exactly like a person. Not in `PLAN_TYPES` either. */
+export declare const PLAN_TEAM_TYPE: "team";
+export declare const PLAN_TYPES: ReadonlySet<string>;
+/** Everything that can hold a role: a person or a team. `rolesOf` doesn't
+ * check this (a role relation may point `from` any node), but the roster, the
+ * role pickers and the plan's drag rules all mean "an actor" when they say
+ * `PLAN_PERSON_TYPE` — this is the set they should key on instead. */
+export declare const PLAN_ACTOR_TYPES: ReadonlySet<string>;
+export declare const isPlanZone: (n: DiagramNode) => boolean;
+export declare const isPlanEvent: (n: DiagramNode) => boolean;
+export declare const isPlanActor: (n: DiagramNode) => boolean;
+/** Actors (people or teams) attach to a zone through a RELATION of one of
+ * these kinds, actor → zone, never through containment — so one actor is on
+ * many zones. */
+export declare const PLAN_ROLES: readonly ["owns", "executes", "checks"];
+export type PlanRole = (typeof PLAN_ROLES)[number];
+export declare const isPlanRole: (k: string) => k is PlanRole;
+/** Days since 1970-01-01 (UTC) for a real `YYYY-MM-DD`; undefined otherwise.
+ * Whole days, parsed as UTC, so the reader's timezone never shifts a bar. */
+export declare function dayOf(iso: unknown): number | undefined;
+/** The inverse of dayOf. */
+export declare function isoOf(day: number): string;
+/** Inclusive day numbers. */
+export interface PlanSpan {
+    start: number;
+    end: number;
+}
+/** A zone's span, or undefined when the node is not a zone or its dates are
+ * missing, malformed or reversed — each of those is a validation finding
+ * (`plan-missing`, `plan-date`, `plan-span`); here it just means "nothing to
+ * draw". */
+export declare function spanOf(n: DiagramNode): PlanSpan | undefined;
+/** An event's day, or undefined when the node is not an event or `at` is
+ * missing or malformed. */
+export declare function atOf(n: DiagramNode): number | undefined;
+export interface PlanRoles {
+    owns: string[];
+    executes: string[];
+    checks: string[];
+}
+/** People per role for one zone, from the role relations that point INTO it,
+ * in declaration order. */
+export declare function rolesOf(model: DiagramModel, zoneId: string): PlanRoles;
+export interface PlanChildren {
+    zones: string[];
+    events: string[];
+    others: string[];
+}
+export interface PlanGraph {
+    /** zone ids in declaration order (visible on the plane) */
+    zones: string[];
+    events: string[];
+    /** every actor (person or team) holding a role — a role relation into a
+     * visible zone — in declaration order, deduplicated */
+    actors: string[];
+    /** zone/event/borrowed node → its zone parent on the plan plane */
+    parent: ReadonlyMap<string, string>;
+    /** zone → DIRECT children on the plan plane, split by what they are. A child
+     * with two zone parents (a DAG node, e.g. a service two phases both borrow)
+     * is listed under exactly ONE — the same zone `parent` resolves it to, which
+     * is also the one zone the compiled VIEW hosts it under (view/tree.ts's
+     * `host`) — never both, so the layout never schedules it relative to a box
+     * it is not actually drawn inside of. */
+    children: ReadonlyMap<string, PlanChildren>;
+    /** earliest start/at and latest end/at over the whole graph; undefined when nothing is dated */
+    range?: PlanSpan;
+    /** 1 January of range.start's year — the x origin of the drawing */
+    origin?: number;
+}
+/**
+ * The plan plane's structure, derived through buildHierarchy so `containmentOf`
+ * and `hides` behave exactly as the view does. `parent` picks each child's
+ * first zone parent by containment-EDGE declaration order — `h.parentsOf`
+ * already preserves that order (the same rule `boundaryOf` uses) — filtered to
+ * the parents that are zones, since a DAG child can have non-zone parents on
+ * the plane too. `children` is derived FROM `parent`, not from
+ * `h.childrenOf` directly: a zone's direct children are exactly the nodes
+ * `parent` resolves to it, so a DAG child (contained by two zones) lands under
+ * exactly one — the view hosts it under one parent too (view/tree.ts), and the
+ * layout must agree or it draws the child relative to a box it is not in.
+ */
+export declare function planGraph(model: DiagramModel, plane?: string): PlanGraph;
+/** `id` plus every descendant zone and event, pre-order — what moves with a
+ * zone. Borrowed nodes are not listed: their place is their row. */
+export declare function planSubtree(g: PlanGraph, id: string): string[];

package/dist/plan.js

@@ -0,0 +1,172 @@
+import { isIsoDate } from './dates.js';
+import { buildHierarchy } from './view/hierarchy.js';
+/** The notation id a plane (or the model) declares to be drawn as a schedule:
+ * a calendar left to right, zones as bars, events as diamonds, actors (people
+ * or teams) as a roster. Pure — the renderer and the studio derive everything
+ * from here. */
+export const PLAN_NOTATION = 'plan';
+/** A zone is a CONTAINER with a span: nesting is containment, and whatever
+ * sits inside a zone is scheduled in it. */
+export const PLAN_ZONE_TYPE = 'plan-zone';
+export const PLAN_EVENT_TYPE = 'plan-event';
+/** The type a person carries. Deliberately the generic `person` type, not a
+ * `plan-person` of its own — a person is an ordinary node the plan merely
+ * reads, and keeps its pill on every other notation. It is named here because
+ * the builder, the roster layout, the studio's quick-add and the role pickers
+ * all key on it, and a literal in four packages is a drift waiting to happen.
+ * It is NOT in `PLAN_TYPES`: that set gates the inspector's date fields, and a
+ * person has no dates. */
+export const PLAN_PERSON_TYPE = 'person';
+/** The type a team carries — the same deal as `PLAN_PERSON_TYPE`: a generic
+ * `team`, not a `plan-team`, so it keeps its own pill everywhere else and a
+ * role relation reads it exactly like a person. Not in `PLAN_TYPES` either. */
+export const PLAN_TEAM_TYPE = 'team';
+export const PLAN_TYPES = new Set([PLAN_ZONE_TYPE, PLAN_EVENT_TYPE]);
+/** Everything that can hold a role: a person or a team. `rolesOf` doesn't
+ * check this (a role relation may point `from` any node), but the roster, the
+ * role pickers and the plan's drag rules all mean "an actor" when they say
+ * `PLAN_PERSON_TYPE` — this is the set they should key on instead. */
+export const PLAN_ACTOR_TYPES = new Set([PLAN_PERSON_TYPE, PLAN_TEAM_TYPE]);
+export const isPlanZone = (n) => n.type === PLAN_ZONE_TYPE;
+export const isPlanEvent = (n) => n.type === PLAN_EVENT_TYPE;
+export const isPlanActor = (n) => n.type !== undefined && PLAN_ACTOR_TYPES.has(n.type);
+/** Actors (people or teams) attach to a zone through a RELATION of one of
+ * these kinds, actor → zone, never through containment — so one actor is on
+ * many zones. */
+export const PLAN_ROLES = ['owns', 'executes', 'checks'];
+export const isPlanRole = (k) => PLAN_ROLES.includes(k);
+const MS_PER_DAY = 86_400_000;
+/** Days since 1970-01-01 (UTC) for a real `YYYY-MM-DD`; undefined otherwise.
+ * Whole days, parsed as UTC, so the reader's timezone never shifts a bar. */
+export function dayOf(iso) {
+    if (!isIsoDate(iso))
+        return undefined;
+    return Date.parse(`${iso}T00:00:00Z`) / MS_PER_DAY;
+}
+/** The inverse of dayOf. */
+export function isoOf(day) {
+    return new Date(day * MS_PER_DAY).toISOString().slice(0, 10);
+}
+/** A zone's span, or undefined when the node is not a zone or its dates are
+ * missing, malformed or reversed — each of those is a validation finding
+ * (`plan-missing`, `plan-date`, `plan-span`); here it just means "nothing to
+ * draw". */
+export function spanOf(n) {
+    if (!isPlanZone(n))
+        return undefined;
+    const start = dayOf(n.metadata?.start);
+    const end = dayOf(n.metadata?.end);
+    return start === undefined || end === undefined || end < start ? undefined : { start, end };
+}
+/** An event's day, or undefined when the node is not an event or `at` is
+ * missing or malformed. */
+export function atOf(n) {
+    return isPlanEvent(n) ? dayOf(n.metadata?.at) : undefined;
+}
+/** People per role for one zone, from the role relations that point INTO it,
+ * in declaration order. */
+export function rolesOf(model, zoneId) {
+    const roles = { owns: [], executes: [], checks: [] };
+    for (const r of model.relations) {
+        if (r.to === zoneId && isPlanRole(r.kind))
+            roles[r.kind].push(r.from);
+    }
+    return roles;
+}
+/**
+ * The plan plane's structure, derived through buildHierarchy so `containmentOf`
+ * and `hides` behave exactly as the view does. `parent` picks each child's
+ * first zone parent by containment-EDGE declaration order — `h.parentsOf`
+ * already preserves that order (the same rule `boundaryOf` uses) — filtered to
+ * the parents that are zones, since a DAG child can have non-zone parents on
+ * the plane too. `children` is derived FROM `parent`, not from
+ * `h.childrenOf` directly: a zone's direct children are exactly the nodes
+ * `parent` resolves to it, so a DAG child (contained by two zones) lands under
+ * exactly one — the view hosts it under one parent too (view/tree.ts), and the
+ * layout must agree or it draws the child relative to a box it is not in.
+ */
+export function planGraph(model, plane) {
+    const byId = new Map(model.nodes.map((n) => [n.id, n]));
+    const h = buildHierarchy(model, plane);
+    // buildHierarchy seeds parentsOf (to []) for every visible node, so this is
+    // exactly "is this node visible on the plane", including shared nodes with
+    // no containment there (they surface as roots, not as absent).
+    const visible = (id) => h.parentsOf.has(id);
+    const zones = [];
+    const events = [];
+    for (const n of model.nodes) {
+        if (!visible(n.id))
+            continue;
+        if (isPlanZone(n))
+            zones.push(n.id);
+        else if (isPlanEvent(n))
+            events.push(n.id);
+    }
+    const zoneSet = new Set(zones);
+    const parent = new Map();
+    for (const [id, parents] of h.parentsOf) {
+        const zoneParent = parents.find((p) => zoneSet.has(p));
+        if (zoneParent !== undefined)
+            parent.set(id, zoneParent);
+    }
+    // Per zone, its h.childrenOf list keeps that zone's own containment-edge
+    // order; filtering by `parent.get(c) === z` drops a child here when another
+    // zone earlier in ITS OWN edge order already claimed it, leaving each DAG
+    // child in exactly the one zone `parent` (and the view) picked for it.
+    const children = new Map();
+    for (const z of zones) {
+        const split = { zones: [], events: [], others: [] };
+        for (const c of h.childrenOf.get(z) ?? []) {
+            if (parent.get(c) !== z)
+                continue;
+            const node = byId.get(c);
+            if (node === undefined)
+                continue;
+            if (isPlanZone(node))
+                split.zones.push(c);
+            else if (isPlanEvent(node))
+                split.events.push(c);
+            else
+                split.others.push(c);
+        }
+        children.set(z, split);
+    }
+    const actors = [];
+    for (const r of model.relations) {
+        if (isPlanRole(r.kind) && zoneSet.has(r.to) && !actors.includes(r.from) && byId.has(r.from))
+            actors.push(r.from);
+    }
+    let range;
+    const widen = (start, end) => {
+        range = range === undefined ? { start, end } : { start: Math.min(range.start, start), end: Math.max(range.end, end) };
+    };
+    for (const z of zones) {
+        const s = spanOf(byId.get(z));
+        if (s !== undefined)
+            widen(s.start, s.end);
+    }
+    for (const e of events) {
+        const at = atOf(byId.get(e));
+        if (at !== undefined)
+            widen(at, at);
+    }
+    const origin = range === undefined ? undefined : dayOf(`${isoOf(range.start).slice(0, 4)}-01-01`);
+    return { zones, events, actors, parent, children, ...(range !== undefined ? { range } : {}), ...(origin !== undefined ? { origin } : {}) };
+}
+/** `id` plus every descendant zone and event, pre-order — what moves with a
+ * zone. Borrowed nodes are not listed: their place is their row. */
+export function planSubtree(g, id) {
+    const out = [id];
+    const walk = (z) => {
+        const c = g.children.get(z);
+        if (c === undefined)
+            return;
+        for (const child of c.zones) {
+            out.push(child);
+            walk(child);
+        }
+        out.push(...c.events);
+    };
+    walk(id);
+    return out;
+}

package/dist/types.d.ts

@@ -76,6 +76,10 @@ export interface DiagramNode {
     technology?: string;
     /** STRIDE findings against this node (see Threat) */
     threats?: Threat[];
+    /** remarks shown in the element's bubble (see Comment) */
+    comments?: Comment[];
+    /** resources listed in the element's bubble (see Link) */
+    links?: Link[];
     description?: string;
     /** rich multiline label; when present, name === rich.map(r => r.text).join('') */
     rich?: TextRun[];
@@ -181,6 +185,24 @@ export interface Threat {
     status?: ThreatStatus;
     mitigation?: string;
 }
+/** A remark on an element: what was said, by whom, when. Generic like
+ * `threats` — any node or relation in any notation can carry a list. Shown in
+ * the element's bubble on the canvas; never affects layout. */
+export interface Comment {
+    /** unique within its element's list (`c1`, `c2`, … when synthesized) */
+    id: string;
+    text: string;
+    /** author, free text */
+    by?: string;
+    /** `YYYY-MM-DD` */
+    at?: string;
+}
+/** A resource an element points at, beyond the single navigation `link`: a
+ * ticket, a design doc, a repo. Listed in the element's bubble. */
+export interface Link {
+    label: string;
+    url: string;
+}
 export interface DiagramRelation {
     id: string;
     from: string;
@@ -192,6 +214,8 @@ export interface DiagramRelation {
     labels?: EdgeLabel[];
     /** STRIDE findings against this flow (see Threat) */
     threats?: Threat[];
+    /** remarks shown in the relation's bubble (see Comment) */
+    comments?: Comment[];
     style?: RelationStyle;
     description?: string;
     layer?: string;
@@ -220,7 +244,9 @@ export interface LegendItem {
     color?: string;
     icon?: string;
 }
-export declare const LEGEND_SECTIONS: readonly ["layers", "kinds", "types"];
+/** `marks` is what is neither a node type nor a line kind: a threat badge, a table's
+ * key and foreign-key column tags. */
+export declare const LEGEND_SECTIONS: readonly ["layers", "kinds", "types", "marks"];
 export type LegendSection = (typeof LEGEND_SECTIONS)[number];
 export declare const LEGEND_POSITIONS: readonly ["top-left", "top-right", "bottom-left", "bottom-right"];
 export type LegendPosition = (typeof LEGEND_POSITIONS)[number];
@@ -231,7 +257,9 @@ export interface DiagramLegend {
     title?: string;
     /** default 'bottom-right' — the only corner not already occupied by chrome */
     position?: LegendPosition;
-    /** derived sections to include; default ['layers', 'kinds'] */
+    /** derived sections to include, exactly. Absent = `layers`, `kinds`, `marks`, plus the
+     * element shapes that carry no words of their own on the canvas (a start dot, a DFD
+     * process); every other element waits for an explicit `types`. */
     show?: LegendSection[];
     /** hand-written rows, appended after the derived ones */
     items?: LegendItem[];
@@ -390,6 +418,6 @@ export interface Drawings {
 }
 /** Pen width when a stroke names none. In core so editor and renderer cannot drift. */
 export declare const DEFAULT_STROKE_WIDTH = 3;
-export declare const BUILTIN_NOTATIONS: readonly ["causal-loop", "git-graph", "c4", "second-order", "fishbone", "threat-model"];
+export declare const BUILTIN_NOTATIONS: readonly ["causal-loop", "git-graph", "c4", "second-order", "fishbone", "threat-model", "plan"];
 export type NotationId = (typeof BUILTIN_NOTATIONS)[number];
 export type Polarity = '+' | '-';

package/dist/types.js

@@ -20,8 +20,10 @@ export const EDGE_LABEL_SIDES = ['top', 'bottom', 'center'];
 export const STRIDE = ['S', 'T', 'R', 'I', 'D', 'E'];
 export const THREAT_STATUSES = ['open', 'mitigated', 'accepted', 'not-applicable'];
 export const THREAT_SEVERITIES = ['low', 'medium', 'high', 'critical'];
-export const LEGEND_SECTIONS = ['layers', 'kinds', 'types'];
+/** `marks` is what is neither a node type nor a line kind: a threat badge, a table's
+ * key and foreign-key column tags. */
+export const LEGEND_SECTIONS = ['layers', 'kinds', 'types', 'marks'];
 export const LEGEND_POSITIONS = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
 /** Pen width when a stroke names none. In core so editor and renderer cannot drift. */
 export const DEFAULT_STROKE_WIDTH = 3;
-export const BUILTIN_NOTATIONS = ['causal-loop', 'git-graph', 'c4', 'second-order', 'fishbone', 'threat-model'];
+export const BUILTIN_NOTATIONS = ['causal-loop', 'git-graph', 'c4', 'second-order', 'fishbone', 'threat-model', 'plan'];

package/dist/validate.d.ts

@@ -1,6 +1,6 @@
 import { type DiagramModel } from './types.js';
 export interface ValidationIssue {
-    code: 'duplicate-node' | 'reserved-node-id' | 'duplicate-layer' | 'duplicate-plane' | 'duplicate-relation' | 'containment-cycle' | 'dangling-endpoint' | 'unknown-layer' | 'unknown-plane' | 'unknown-hidden-node' | 'redundant-hide' | 'invalid-plane' | 'invalid-style' | 'invalid-legend' | 'invalid-image' | 'invalid-shape' | 'invalid-link' | 'invalid-key' | 'duplicate-key' | 'invalid-include' | 'unknown-notation' | 'invalid-polarity' | 'invalid-delay' | 'invalid-rich' | 'invalid-align' | 'invalid-font-scale' | 'invalid-edge-label' | 'duplicate-column' | 'unknown-column' | 'git-link-endpoints' | 'git-commit-lane' | 'git-parents' | 'git-cycle' | 'git-commit-outside-lane' | 'git-gap' | 'git-stage-span' | 'activity-lane-parent' | 'activity-frame-children' | 'activity-region-parent' | 'so-no-decision' | 'so-cycle' | 'so-unreachable' | 'so-contained' | 'fb-no-effect' | 'fb-many-effects' | 'fb-unattached' | 'fb-misplaced' | 'fb-too-deep' | 'fb-contained' | 'invalid-threats' | 'threat-id' | 'threat-title' | 'threat-category' | 'threat-status' | 'threat-severity' | 'tm-flow-boundary';
+    code: 'duplicate-node' | 'reserved-node-id' | 'duplicate-layer' | 'duplicate-plane' | 'duplicate-relation' | 'containment-cycle' | 'dangling-endpoint' | 'unknown-layer' | 'unknown-plane' | 'unknown-hidden-node' | 'redundant-hide' | 'invalid-plane' | 'invalid-style' | 'invalid-legend' | 'invalid-image' | 'invalid-shape' | 'invalid-link' | 'invalid-key' | 'duplicate-key' | 'invalid-include' | 'unknown-notation' | 'invalid-polarity' | 'invalid-delay' | 'invalid-rich' | 'invalid-align' | 'invalid-font-scale' | 'invalid-edge-label' | 'duplicate-column' | 'unknown-column' | 'git-link-endpoints' | 'git-commit-lane' | 'git-parents' | 'git-cycle' | 'git-commit-outside-lane' | 'git-gap' | 'git-stage-span' | 'activity-lane-parent' | 'activity-frame-children' | 'activity-region-parent' | 'so-no-decision' | 'so-cycle' | 'so-unreachable' | 'so-contained' | 'fb-no-effect' | 'fb-many-effects' | 'fb-unattached' | 'fb-misplaced' | 'fb-too-deep' | 'fb-contained' | 'invalid-threats' | 'threat-id' | 'threat-title' | 'threat-category' | 'threat-status' | 'threat-severity' | 'invalid-comments' | 'comment-id' | 'comment-text' | 'comment-at' | 'invalid-links' | 'tm-flow-boundary' | 'plan-date' | 'plan-missing' | 'plan-span' | 'plan-nested' | 'plan-role-target';
     message: string;
     ref?: string;
 }