umlimator 0.21.0 → 0.23.0

package/lib/umlimator.d.ts

@@ -44,7 +44,7 @@ export interface MapNode {
 /** A typed element in schema version 2's envelope (docs/diagrams/model.md §1): a node, a member, a typed edge, a
  *  fragment. Nodes, edges, members and fragments share one id space; an id never contains "->". A typed edge is an
  *  Element with `from` and `to`, which may name a member. A typed view is a MapView with `diagram` (uml.class), and may
- *  have `subject`, `direction` ('right' | 'down'), `notation`, `present`, `fragments` and `timeline`. umlimator/all draws `uml.class` (0.18.0), `uml.object` and `uml.package` (0.19.0), `uml.sequence` and `uml.communication` (0.20.0), `uml.use-case`, `uml.activity`, `uml.state-machine` and `uml.interaction-overview` (0.21.0); other types draw as plain cards.
+ *  have `subject`, `direction` ('right' | 'down'), `notation`, `present`, `fragments` and `timeline`. umlimator/all draws `uml.class` (0.18.0), `uml.object` and `uml.package` (0.19.0), `uml.sequence` and `uml.communication` (0.20.0), `uml.use-case`, `uml.activity`, `uml.state-machine` and `uml.interaction-overview` (0.21.0), `uml.component`, `uml.deployment` and `uml.composite-structure` (0.22.0), `uml.profile` and `uml.timing` (0.23.0); other types draw as plain cards.
  *  From 0.19.0 the class, object and package types draw a shown package that owns something the view shows as a box holding it (`parent`), and
  *  qualify names (`sales::Order`) from the nearest shown owner, the view's `subject`, or the top. */
 export interface Element {
@@ -157,6 +157,82 @@ export interface UmlTransitionProps { trigger?: string; guard?: string; effect?:
 export type UmlInteractionOverviewElementType = 'uml.InitialNode' | 'uml.ActivityFinalNode' | 'uml.FlowFinalNode' | 'uml.DecisionNode'
   | 'uml.MergeNode' | 'uml.ForkNode' | 'uml.JoinNode' | 'uml.InteractionUse' | 'uml.Interaction' | 'uml.Comment';
 export type UmlInteractionOverviewLineType = 'uml.ControlFlow' | 'uml.CommentLink';
+/** The component diagram's vocabulary (a view with `diagram: 'uml.component'`, umlimator/all from 0.22.0;
+ *  docs/conformance/uml-component.md). A component's `parent` is a component (drawn nested, a box) or a package; its
+ *  ports (a class's too) are members, drawn on its border. A provided interface is always an `uml.Interface` node, joined
+ *  to its provider (a component, a class or a port) by a realization and to its requirers by usages; `present.<id>.as:
+ *  'ball'` draws it as a ball, a usage to it ending in a socket. */
+export type UmlComponentElementType = 'uml.Component' | 'uml.Interface' | 'uml.Artifact' | 'uml.Package' | 'uml.Comment';
+export type UmlComponentMemberType = 'uml.Port';
+export type UmlComponentLineType = 'uml.InterfaceRealization' | 'uml.ComponentRealization' | 'uml.Usage' | 'uml.Connector' | 'uml.Dependency'
+  | 'uml.Manifestation' | 'uml.CommentLink';
+/** A port's props: its type, drawn `name : Type` beside it. */
+export interface UmlPortProps { valueType?: string; stereotypes?: string[]; [key: string]: unknown }
+/** A connector's props: in a component view its kind (an assembly when left out); in a composite structure view, an end
+ *  through a part (UML's partWithPort): `ends.from.part` or `ends.to.part` names the part, `from` or `to` the port of its type. */
+export interface UmlConnectorProps { kind?: 'assembly' | 'delegation'; ends?: { from?: { part?: string }; to?: { part?: string } }; stereotypes?: string[]; [key: string]: unknown }
+/** What a component or composite structure view shows of one element, beside UmlPresent: an interface as a ball; a port's
+ *  side; on a part, each of its type's ports' sides. */
+export interface UmlStructurePresent { as?: 'ball'; side?: 'left' | 'right' | 'top' | 'bottom'; ports?: Record<string, { side?: 'left' | 'right' | 'top' | 'bottom' }> }
+/** The deployment diagram's vocabulary (a view with `diagram: 'uml.deployment'`, umlimator/all from 0.22.0;
+ *  docs/conformance/uml-deployment.md). A node, device or execution environment that holds something shown is a box drawn
+ *  as a cube; an artifact or deployment specification whose `parent` is one is deployed on it, a `uml.Deployment` line
+ *  from it to one is the other form. */
+export type UmlDeploymentElementType = 'uml.Node' | 'uml.Device' | 'uml.ExecutionEnvironment' | 'uml.Artifact' | 'uml.DeploymentSpecification'
+  | 'uml.Component' | 'uml.Comment';
+export type UmlDeploymentLineType = 'uml.Deployment' | 'uml.Manifestation' | 'uml.CommunicationPath' | 'uml.Dependency' | 'uml.CommentLink';
+/** The composite structure diagram's vocabulary (a view with `diagram: 'uml.composite-structure'`, umlimator/all from
+ *  0.22.0; docs/conformance/uml-composite-structure.md). The view's `subject` (a class, component or collaboration, listed
+ *  in `nodeIds`) is drawn as a box holding its parts (`uml.Property` members) and collaboration uses (`parent` the
+ *  subject); a part shows the ports of the class or component its `valueType` names by label, each drawn under the id
+ *  `<part>-><port>`. An open collaboration (listed in `nodeIds`) is a dashed ellipse round its roles. A role binding runs
+ *  from a part to a collaboration use, its `label` the role. */
+export type UmlCompositeStructureElementType = 'uml.Class' | 'uml.Component' | 'uml.Collaboration' | 'uml.CollaborationUse' | 'uml.Comment';
+export type UmlCompositeStructureMemberType = 'uml.Property' | 'uml.Port';
+export type UmlCompositeStructureLineType = 'uml.Connector' | 'uml.RoleBinding' | 'uml.CommentLink';
+/** A part's (or role's) props: the class or component it is, by label; its multiplicity; shared parts are drawn dashed. */
+export interface UmlPartProps { valueType?: string; multiplicity?: string; aggregation?: 'composite' | 'shared'; stereotypes?: string[]; [key: string]: unknown }
+/** A collaboration use's props: the collaboration it uses, by label. */
+export interface UmlCollaborationUseProps { collaboration?: string; stereotypes?: string[]; [key: string]: unknown }
+/** Any UML element's tagged values (0.23.0): by stereotype (as written in `stereotypes`, `Profile::name` when qualified, or
+ *  a required stereotype's name), then by tag name, each value as text. Checked against the profiles applied to the
+ *  element's packages (docs/conformance/uml-profile.md); edited in the properties panel on every typed view. */
+export type UmlTags = Record<string, Record<string, string>>;
+/** The props any UML element may hold from 0.23.0: its stereotypes (a name, or `Profile::name`) and their tags. */
+export interface UmlStereotypedProps { stereotypes?: string[]; tags?: UmlTags; [key: string]: unknown }
+/** The profile diagram's vocabulary (a view with `diagram: 'uml.profile'`, umlimator/all from 0.23.0;
+ *  docs/conformance/uml-profile.md). A stereotype's and a metaclass reference's `parent` is a profile; an enumeration's
+ *  (a tag's type) may be. A metaclass reference's `label` names a UML metaclass (Class, Property, Classifier, …). A
+ *  stereotype's tag definitions are `uml.Property` members (`name : Type [multiplicity] = default`). Any element that
+ *  applies a stereotype may be shown, with a compartment of tags for each stereotype it has. */
+export type UmlProfileElementType = 'uml.Profile' | 'uml.Stereotype' | 'uml.MetaclassReference' | 'uml.Enumeration' | 'uml.Package' | 'uml.Comment';
+export type UmlProfileMemberType = 'uml.Property' | 'uml.EnumerationLiteral';
+/** An extension from a stereotype to a metaclass reference; a profile application from a package to a profile; a
+ *  generalization between stereotypes. */
+export type UmlProfileLineType = 'uml.Extension' | 'uml.ProfileApplication' | 'uml.Generalization' | 'uml.CommentLink';
+/** A stereotype's props: abstract (applied through a specialization). */
+export interface UmlStereotypeProps { isAbstract?: boolean; [key: string]: unknown }
+/** An extension's props: required (the stereotype is applied to every element of the metaclass in its profile's scope). */
+export interface UmlExtensionProps { isRequired?: boolean; [key: string]: unknown }
+/** The timing diagram's vocabulary (a view with `diagram: 'uml.timing'`, umlimator/all from 0.23.0;
+ *  docs/conformance/uml-timing.md). Lifelines are model nodes the view lists in `nodeIds`, top to bottom; messages are inline
+ *  in the view's `edges`; changes and constraints are in its `timeline`. `present.<lifeline>.as: 'values'` draws a value
+ *  lifeline. The scale is derived, never stored. */
+export type UmlTimingElementType = 'uml.Lifeline';
+export type UmlTimingLineType = 'uml.Message';
+/** A timing lifeline's props: what it represents, and its states, top to bottom (ignored by the sequence and
+ *  communication types). */
+export interface UmlTimingLifelineProps { represents?: string; states?: string[]; stereotypes?: string[]; tags?: UmlTags; [key: string]: unknown }
+/** A timing message's props: a sort of call, async or reply, and when it is sent and received, in the view's unit. */
+export interface UmlTimingMessageProps { sort?: 'call' | 'async' | 'reply'; replyTo?: string; sentAt?: number; receivedAt?: number; [key: string]: unknown }
+/** A change of state on a lifeline at a time; an element of the model's id space, drawn by `at`. */
+export interface UmlTimingChange { id: string; lifeline: string; at: number; state: string }
+/** A duration constraint from one change to a later one, or a time constraint on one change. */
+export interface UmlTimingConstraint { id: string; type: 'uml.DurationConstraint' | 'uml.TimeConstraint'; from: string; to?: string; label?: string }
+/** A timing view's `timeline`: the ruler's unit (optional), its changes in any order, its constraints. */
+export interface UmlTimeline { unit?: string; changes?: UmlTimingChange[]; constraints?: UmlTimingConstraint[] }
+/** What a timing view shows of a lifeline, in its `present`: drawn as a value lifeline. */
+export interface UmlTimingPresent { as?: 'values' }
 /** What a line means, drawn as its colour: calls (the default), feeds (hands work on), triggers (suggests, offers, fires),
  *  state (reads or writes a file, board or config: a thinner line, a muted label, no flow) and guard (a hook steps in).
  *  Colours are --um-w-<kind>. An edge's `style` (emphasis, dashed, security) wins over its kind's colour. */

package/lib/umlimator.js

@@ -123,7 +123,7 @@ function registerDiagramType(name, def = {}) {
      reroute is no registry field: reroute: false goes in the dg the type's own layout passes to layoutTyped (src/typed/layout.js).
    Stage 4's (notes/stage-4.md §12.1, §15): edits.rename(model, view, id, text); a hook's { pick, then }; name: false and
    opens on a palette entry; a line's cut, its label's width (150); rows(model, view, id) and word(model, id), the PDF's.
-   Stage 5's: a line's fromPort, toPort, inner, portRank, a box's pad, round, a view's labelGaps (src/typed/layout.js);
+   Stage 5's: a line's fromPort, toPort, inner, portRank, a box's pad, round, head, a view's labelGaps (src/typed/layout.js);
    edits.member, edits.key (src/typed/edit.js). */
 
 /* A view's type: the map for a view with no diagram, the registered type, or null for one this release does not draw */
@@ -131,7 +131,9 @@ const diagramOf = view => TYPES.get(view && view.diagram != null ? view.diagram
 
 /* What only a registered type's geometry uses, installed at load time by the files under src/typed/, which only
    lib/umlimator-all.js holds (tools/build.mjs): rows, rooms and routes in layoutPass, a typed line's ends in svgOf, the
-   gestures of edit.js it takes over (edit). Empty in umlimator.js, where no view is laid out but as a map (risks.md C5) */
+   gestures of edit.js it takes over (edit), diff()'s words for typed models (diff, order: src/uml/diff.js). Empty in
+   umlimator.js, where no view is laid out but as a map (risks.md C5).
+   Stage 6's: across(model), validate()'s rules on the whole model; fields(model, x), more panel fields (notes/stage-6.md §5) */
 const TYPED = {};
 
 const propRefs = type => Object.assign({}, ...[...TYPES.values()].map(T => T.refs && Object.hasOwn(T.refs, type) && T.refs[type]));
@@ -248,6 +250,7 @@ function refs(m, ids, only) {
     arr(v.nodes).forEach((n, j) => element(n, [...at, 'nodes', j], false));
     arr(v.edges).forEach((e, j) => { if (has(e)) say([...at, 'edges', j], 'view'); else element(e, [...at, 'edges', j], true); });
     arr(v.fragments).forEach((f, j) => element(f, [...at, 'fragments', j], false));
+    ['changes', 'constraints'].forEach(k => arr(isObj(v.timeline) && v.timeline[k]).forEach((c, j) => isObj(c) && ['lifeline', 'from', 'to'].forEach(f => { if (has(c[f])) say([...at, 'timeline', k, j, f], 'end'); })));
     [['layout', 'pin'], ['present', 'present'], ['nodeOverrides', 'override']].forEach(([k, kind]) => Object.keys(isObj(v[k]) ? v[k] : {}).forEach(id => { if (has(id)) say([...at, k, id], kind); }));
     if (has(v.subject)) say([...at, 'subject'], 'subject');
     if (!only) ['parent', 'node'].forEach(k => { if (has(v[k])) say([...at, k], 'parent'); }); // a view opened from a card
@@ -374,9 +377,9 @@ function run(m, c, gone) {
       const take = id => { const r = at.get(id); if (!r || now.has(id)) return; now.add(id);
         arr(r.x.members).forEach(y => isObj(y) && take(y.id)); arr(kids.get(id)).forEach(take); }; // what it owns goes with it
       take(c.id);
-      // lines to what is gone go too, lines to those lines, and what a type's refs cascade (a reply with its call)
+      // lines to what is gone go too, lines to those lines, a timeline's items, and what a type's refs cascade (a reply with its call)
       const cascade = x => Object.entries(propRefs(x.type)).some(([p, how]) => how === 'cascade' && [].concat(dig(x, p)).some(id => now.has(id)));
-      for (let more = true; more;) { more = false; for (const [k, o] of at) if (!now.has(k) && (o.kind === 'edge' && (now.has(o.x.from) || now.has(o.x.to)) || cascade(o.x))) { take(k); more = true; } }
+      for (let more = true; more;) { more = false; for (const [k, o] of at) if (!now.has(k) && (o.kind === 'edge' && (now.has(o.x.from) || now.has(o.x.to)) || o.kind === 'time' && [o.x.lifeline, o.x.from, o.x.to].some(i => now.has(i)) || cascade(o.x))) { take(k); more = true; } }
       // what stays in something gone goes to its nearest owner left; an operand's messages to its fragment's parent
       const above = id => { const r = at.get(id); return r && (r.x.parent ?? (r.owner && above(r.owner.id))); };
       for (const [k, o] of at) if (!now.has(k) && now.has(o.x.parent)) { let p = o.x.parent;
@@ -1035,7 +1038,7 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
   // A typed view's boxes (notes/stage-2.md §3.2) take the same code as a map's: their title is the type's (`title`), and a box
   // grows to hold it; laid out turned (direction down), the 24 px header room goes left, the side that becomes the top
   const familyDefs = dg.containers || [], tagged = n => map && (n.author || n.k === 'm-ext'), TB = !map && dg.turned; // tagged: a name tag hangs under the card
-  const headW = f => textW(!map && f.title || f.label || f.id, 11) + 16; // a box's title, as the audit measures it
+  const headW = f => textW(!map && f.title || f.label || f.id, !map && f.head ? 12 : 11) + 16; // a box's title, as the audit measures it (two lines: at 12 px)
   const framesNow = () => { const cache = Object.create(null); // a box may be named 'constructor'
     const frameOf = (f, trail = new Set()) => {
       if (cache[f.id]) return cache[f.id];
@@ -1048,7 +1051,7 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
       const p = 12, x = Math.min(...rects.map(r => r.x)) - p - (TB ? 24 : 0), y = Math.min(...rects.map(r => r.y)) - p - (TB ? 0 : 24);
       const b = {...f, x, y, w:Math.max(...rects.map(r => r.x+r.w)) + p - x, h:Math.max(...rects.map(r => r.y+r.h)) + p - y};
       if (!map) b[TB ? 'h' : 'w'] = Math.max(b[TB ? 'h' : 'w'], headW(f) + 16);
-      return cache[f.id] = dg.typed ? TYPED.frame(b) : b;
+      return cache[f.id] = dg.typed ? TYPED.frame(b, TB) : b;
     };
     const out = familyDefs.map(f => frameOf(f)).filter(Boolean);
     if (map) out.forEach(f => { // the box fits its title and its badges, which are tabs on its top border, at the right
@@ -1450,7 +1453,7 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
   const runRouting = order => {
     routed.length = 0; reserved.length = 0; placed.length = 0; stats = {};
     (dg.blocks || []).forEach(b => { reserved.push(b); placed.push(b); });
-    families.forEach(f => { const h = TB ? { x: f.x + 3, y: f.y + 8, w: 22, h: headOf(f) } : { x: f.x + 8, y: f.y + 3, w: headOf(f), h: 22 }; reserved.push(h); placed.push(h);
+    families.forEach(f => { const t = 22 + (!map && f.head || 0), h = TB ? { x: f.x + 3, y: f.y + 8, w: t, h: headOf(f) } : { x: f.x + 8, y: f.y + 3, w: headOf(f), h: t }; reserved.push(h); placed.push(h);
       placed.push(...[{ x: f.x, y: f.y - 3, w: f.w, h: 6 }, { x: f.x, y: f.y + f.h - 3, w: f.w, h: 6 }, { x: f.x - 3, y: f.y, w: 6, h: f.h }, { x: f.x + f.w - 3, y: f.y, w: 6, h: f.h }].map(r => ({ ...r, band: true }))); }); // lane headers and arrows stay clear
     edges.filter(e => e.fixed).forEach(e => { routed.push(e); if (e.under || e[OWN_ROUTE]) { placeLabel(e); stats[e.how] = (stats[e.how] || 0) + 1; return; } if (e.lbl) { placed.push(e.lbl); reserved.push({ x: e.lbl.x - 3, y: e.lbl.y - 3, w: e.lbl.w + 6, h: e.lbl.h + 6 }); } stats.comb = (stats.comb || 0) + 1; });
     order.forEach(e => {
@@ -1687,7 +1690,7 @@ function routeAudit(geo, where, only, refs) { // only: a set of edges; counts ju
     if (f.parent && (!parent || !inside(parent,f))) say(`${where}: family "${f.label}" sticks out of its parent`, f);
     (f.nodeIds || []).forEach(id => { const n = geo.byId[id]; if (n && !inside(f,n)) say(`${where}: family "${f.label}" does not contain "${n.label}"`, f, n); });
     families.filter(g => g !== f && g.parent === f.parent && g.id > f.id).forEach(g => { if (hit(f,g,-1)) say(`${where}: families "${f.label}" and "${g.label}" overlap`, f, g); });
-    geo.edges.forEach((e,i) => { if (segHit({x:f.x+8,y:f.y+3,w:Math.min(f.w-16,textW(f.label || f.id,11)+16),h:22},i)) say(`${where}: family "${f.label}": header crossed by edge ${name(e)}`, f, e); });
+    geo.edges.forEach((e,i) => { if (segHit({x:f.x+8,y:f.y+3,w:Math.min(f.w-16,textW(f.label || f.id,11)+16),h:22+(!geo.map&&f.head||0)},i)) say(`${where}: family "${f.label}": header crossed by edge ${name(e)}`, f, e); });
     geo.edges.forEach((e,i) => { if (segs[i].some(([a,b]) => { const v = a[0] === b[0], c = v ? a[0] : a[1], p = v ? [a[1], b[1]] : [a[0], b[0]];
       const lo = Math.max(Math.min(...p), v ? f.y : f.x), hi = Math.min(Math.max(...p), v ? f.y + f.h : f.x + f.w);
       return hi - lo > 40 && (v ? [f.x, f.x + f.w] : [f.y, f.y + f.h]).some(u => Math.abs(c - u) < 8); })) say(`${where}: edge ${name(e)} runs along the border of family "${f.label}"`, e, f); });
@@ -1702,7 +1705,7 @@ const box = n => ({ x: n.x, y: n.y, w: n.w, h: n.h });
 function overlapIssues(geo, where, refs) {
   const issues = [], nodes = geo.nodes, say = teller(issues, refs);
   const inside = (a, b) => a.x >= b.x - 1 && a.y >= b.y - 1 && a.x + a.w <= b.x + b.w + 1 && a.y + a.h <= b.y + b.h + 1;
-  const holds = (a, b) => (a.holder && inside(b, a)) || (b.holder && inside(a, b)); // a holder (a sequence's frame) may hold what it meets, not cross it
+  const holds = (a, b) => (a.holder && inside(b, a)) || (b.holder && inside(a, b)) || !geo.map && ((a.owner || 0) === b.id || (b.owner || 0) === a.id); // a holder (a sequence's frame) may hold what it meets, not cross it; a port its owner
   for (let i = 0; i < nodes.length; i++) for (let j = i + 1; j < nodes.length; j++) if (hit(box(nodes[i]), box(nodes[j]), -1) && !holds(nodes[i], nodes[j])) say(`${where}: nodes "${nodes[i].label}" and "${nodes[j].label}" overlap`, nodes[i], nodes[j]);
   return issues;
 }
@@ -2614,9 +2617,10 @@ export function validate(model) {
     out.push(...typedProblems(m).filter(p => !(p.level === 'error' && said.has(p.path))));
     views.forEach((v, i) => { const at = `views[${i}].diagram`; // a well-formed name of a type this release does not draw (M13)
       if (typedView(v) && !diagramOf(v) && !out.some(p => p.path === at)) warn(at, `diagram "${v.diagram}" is not drawn by this release: its nodes are drawn as plain cards`); });
-    const once = new Set(); // each view's type's rules, a problem once; a validate(model) that takes no view, once a type
-    views.filter(typedView).forEach(v => { const T = diagramOf(v); if (!T || !T.validate || once.has(T)) return; if (T.validate.length < 2) once.add(T);
-      T.validate(m, v).forEach(p => { const k = JSON.stringify([p.level, p.path, p.message]); if (!once.has(k)) { once.add(k); out.push(p); } }); });
+    const once = new Set(), say = p => { const k = JSON.stringify([p.level, p.path, p.message]); if (!once.has(k)) { once.add(k); out.push(p); } };
+    // each view's type's rules, a problem once; a validate(model) that takes no view, once a type
+    views.filter(typedView).forEach(v => { const T = diagramOf(v); if (!T || !T.validate || once.has(T)) return; if (T.validate.length < 2) once.add(T); T.validate(m, v).forEach(say); });
+    if (TYPED.across) arrOf(TYPED.across(m)).forEach(say);
   }
   return out;
 }
@@ -2773,14 +2777,16 @@ export function diff(before, after) {
     if (h === 'removed') said.push(`removes ${name(n.id)}`);
     if (h === 'changed') { const [o, x] = was.get(n), keys = diffKeys([o, x]), rest = keys.filter(k => k !== 'label'), p0 = o.parent ?? null, p1 = x.parent ?? null;
       if (keys.join() === 'parent' && p0 !== p1 && A.schemaVersion === 2 && out.schemaVersion === 2) return said.push(`moves ${name(n.id)} ${p1 != null ? 'into ' + name(p1) : 'out of ' + name(p0)}`); // a re-own (schema version 2; absent or null is no owner)
+      const t = TYPED.diff && TYPED.diff(o, x, name, [A, out]); if (t) return said.push(...t); // a typed element's own words (src/uml/diff.js)
       said.push((keys.includes('label') ? `renames ${o.label || o.id} to ${x.label || x.id}` : `changes ${name(n.id)}`) + (rest.length ? ` (${rest.join(', ')})` : '')); } });
   lines.forEach(e => { const h = how.get(e); if (!h || cardHow.get(e.from) === h && h !== 'changed' || cardHow.get(e.to) === h && h !== 'changed') return;
     const ends = `${name(e.from)} to ${name(e.to)}`, lab = e.label ? ` (${e.label})` : '';
     if (h === 'added') said.push(`adds a line from ${ends}${lab}`);
     if (h === 'removed') said.push(`removes the line from ${ends}${lab}`);
-    if (h === 'changed') { const [o, x] = was.get(e);
+    if (h === 'changed') { const [o, x] = was.get(e), t = TYPED.diff && TYPED.diff(o, x, name, [A, out]); if (t) return said.push(...t);
       said.push(`changes the line from ${ends} (${diffKeys([o, x]).map(k => k === 'label' ? `label ${o.label ?? '-'} → ${x.label ?? '-'}` : k).join(', ')})`); } });
   moved.forEach(([verb, id, v]) => said.push(`${verb} ${name(id)} ${verb === 'puts' ? 'in' : 'out of'} the view ${v.title || v.id}`));
+  if (TYPED.order) TYPED.order(A, out, views, V0, said, touched, name);
 
   // the views that show a change: a card or line the diff marks, or a card it put in or took out
   const changed = views.filter(v => v && (touched.has(v.id) || arr(v.nodeIds).some(id => cardHow.has(id)) || linesOf(out, v).some(e => how.has(e)))).map(v => v.id);
@@ -2834,9 +2840,11 @@ const walkFrom = (edges, start, back) => { const seen = new Set([start]); // bre
   for (let q = [start]; q.length;) { const u = q.shift(); edges.forEach(e => { const [a, b] = back ? [e.to, e.from] : [e.from, e.to]; if (a === u && !seen.has(b)) { seen.add(b); q.push(b); } }); }
   return seen; };
 
+const viewType = (model, viewId) => model && model.schemaVersion === 2 && diagramOf(arrOf(model.views).find(v => v && v.id === viewId));
 /** Every card and line on a path from one card to another, following lines forward: the cards both reachable from `from`
  *  and leading to `to`, and the lines between them. [] when no path joins them. */
 export function paths(model, viewId, from, to) {
+  const T = viewType(model, viewId); if (T && T.paths) return T.paths(model, viewId, from, to); // a type's own walk (a sequence's, in time)
   const { ids, edges } = lineGraph(model, viewId);
   if (!ids.includes(from) || !ids.includes(to)) return [];
   const F = walkFrom(edges, from), B = walkFrom(edges, to, true), on = id => F.has(id) && B.has(id);
@@ -2861,7 +2869,7 @@ export function reach(model, viewId, from, options = {}) {
 /** A view in plain sentences: its cards and their kinds, its boxes, what each card's lines do (in run order on a sequence
  *  view), and the cards with no line. The same model gives the same words: a text alternative, docs, or an AI's context. */
 export function describe(model, viewId) {
-  const T = model && model.schemaVersion === 2 && diagramOf(arrOf(model.views).find(v => v && v.id === viewId)); if (T && T.describe) return T.describe(model, viewId); // a type's own words (1.9)
+  const T = viewType(model, viewId); if (T && T.describe) return T.describe(model, viewId); // a type's own words (1.9)
   const { ctx, v, ids, edges } = lineGraph(model, viewId), boxes = (v.containers || []).filter(c => c && c.id);
   const name = id => ctx.N[id] ? ctx.nodeIn(id, viewId).label || id : (boxes.find(c => c.id === id) || {}).label || id;
   const list = xs => xs.length < 3 ? xs.join(' and ') : xs.slice(0, -1).join(', ') + ' and ' + xs[xs.length - 1];
@@ -3642,7 +3650,7 @@ function typedEditor(api) {
   function props() {
     const at = elementsOf(model()), id = selId(at), e = id && at.get(id);
     if (!e) return '<h3>Properties</h3><p class="um-note">Select a card or a line</p>';
-    const x = e.x, P = isRec(x.props) ? x.props : {}, schema = arrOf(isRec(def().props) ? def().props[x.type] : null).filter(f => isRec(f) && typeof f.key === 'string');
+    const x = e.x, P = isRec(x.props) ? x.props : {}, F = a => arrOf(a).filter(f => isRec(f) && typeof f.key === 'string'), own = F(isRec(def().props) ? def().props[x.type] : null), schema = [...own, ...F(TYPED.fields && TYPED.fields(model(), x))];
     const off = can('rename') ? '' : ' disabled'; // the editable flags: a field the host does not offer is shown, to read
     const text = (f, v, name, more = '') => `<label>${esc(name)}<input data-f="${esc(f)}" data-was="${esc(v)}" value="${esc(v)}"${more}${off}></label>`;
     let h = `<h3>Properties${x.type != null ? ': ' + esc(x.type) : ''}</h3>` + text('label', x.label ?? '', 'Name');
@@ -3657,7 +3665,7 @@ function typedEditor(api) {
     const offer = Array.isArray(os) && [{ id: '', label: 'none' }, ...os.filter(o => isRec(o) && o.id != null && !under(o.id))];
     if (offer && x.parent != null && !offer.some(o => o.id === x.parent)) offer.push({ id: x.parent, label: (at.get(x.parent) || { x: {} }).x.label });
     if (offer) h += `<label>Owner<select data-f="owner" data-owner${can('move') ? '' : ' disabled'}>${offer.map(o => `<option value="${esc(o.id)}"${o.id === (x.parent ?? '') ? ' selected' : ''}>${esc(o.label ?? o.id)}</option>`).join('')}</select></label>`;
-    const rest = schema.length ? [] : Object.entries(P); // no schema: what it holds, to read
+    const rest = own.length ? [] : Object.entries(P); // no schema: what it holds, to read
     if (rest.length) h += '<dl>' + rest.map(([k, v]) => `<dt>${esc(k)}</dt><dd>${esc(typeof v === 'string' ? v : JSON.stringify(v))}</dd>`).join('') + '</dl>';
     const M = def().member;
     if (e.kind === 'node' && !(M && M.holds && !M.holds(x))) { // a comment holds none
@@ -3843,7 +3851,7 @@ export function render(container, model, options = {}) {
   const emitSel = (again = false) => {
     const now = JSON.stringify(picked()); if (now === said && !again) return; said = now;
     say(!sel ? 'Nothing selected' : (sel.type === 'node' ? nameOf(sel.id) : sel.type === 'edge' ? (e => e ? `Line from ${nameOf(e.from)} to ${nameOf(e.to)}` : 'Line')(geo.edges[edgeIndex(sel)])
-      : `Box ${(svg.querySelector(`.family[data-family="${CSS.escape(sel.id)}"] .family-title`) || {}).textContent || sel.id}`) + (more.length ? `, ${more.length + 1} ${picked().every(r => r.type === 'node') ? 'cards ' : ''}selected` : ', selected'));
+      : `Box ${[...svg.querySelectorAll(`.family[data-family="${CSS.escape(sel.id)}"] .family-title`)].map(t => t.textContent).join(' ') || sel.id}`) + (more.length ? `, ${more.length + 1} ${picked().every(r => r.type === 'node') ? 'cards ' : ''}selected` : ', selected'));
     emit('select', { target: copyRef(sel), targets: picked() });
   };
   const edgeRef = e => ({ type: 'edge', ids: edgeRefIds(e), view: cur });
@@ -4288,7 +4296,7 @@ export function render(container, model, options = {}) {
     if (ref.type === 'node') { const n = geo.byId[ref.id]; return n ? { x: n.x + 50, y: n.y + n.h / 2 - 13, w: n.w - 58, h: 26 } : null; }
     if (ref.type === 'edge') { const e = geo.edges[edgeIndex(ref)]; if (!e) return null; const L = e.lbl, m = e.pts[Math.floor(e.pts.length / 2)];
       return L ? { x: L.x - 8, y: L.y - 2, w: L.w + 16, h: L.h + 4 } : { x: m[0] - 60, y: m[1] - 12, w: 120, h: 24 }; }
-    const f = ref.type === 'container' && (geo.families || []).find(x => x.id === ref.id); return f ? { x: f.x + 8, y: f.y + 2, w: Math.min(f.w - 16, 220), h: 24 } : null; };
+    const f = ref.type === 'container' && (geo.families || []).find(x => x.id === ref.id); return f ? { x: f.x + 8, y: f.y + 2 + (f.head || 0), w: Math.min(f.w - 16, 220), h: 24 } : null; };
   function editor(where, text, done, ref = null) { // where: a box in map units (a new card's), or ref names what the field sits over
     if (naming) naming.close(false);
     const inp = document.createElement('input');