@sentropic/diagram-canvas 0.2.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,30 +1,5 @@
1
1
  import { DIAGRAM_SCENE_SPACING as spacing } from '../layout/spacing.generated.js';
2
2
  import { getDiagramGlyph } from "./registry.js";
3
- /**
4
- * DiagramCard shared model — geometry, projection and line layout (DC-1).
5
- *
6
- * Pure TypeScript, zero imports: the Svelte `DiagramCard` (barrel graph)
7
- * and the `diagram-render` pure renderer (subpath graph) both consume this
8
- * module, so it must live outside both subpath directories and import
9
- * nothing. Glyph path data arrives via props (resolved by the caller from
10
- * the `diagram-icons` subpath); this module never resolves a glyph name.
11
- *
12
- * One geometry source (§5.6): every number below is frozen by
13
- * spec/SPEC_EVOL_DS_DIAGRAM_CARDS.md §5.3/Appendix A and mirrors
14
- * - the `diagramCard` component tokens (`packages/tokens/src/component.ts`),
15
- * - `packages/diagram-canvas/src/layout/measure.ts`
16
- * (`FIXED_CARD_WIDTH 460`, `FIXED_CARD_HEIGHT 200`,
17
- * `TOGGLE_ALLOCATION 66`, `CONTENT_INSET 16`, `RULE_GAP 4`).
18
- * The token↔constant agreement test asserts the sources agree.
19
- *
20
- * Line boxes use the kit's 1/64 px grid (`floor(size * 1.3 * 64) / 64`,
21
- * cf. `frameHeaderContent`): with those boxes the frozen content sums
22
- * exactly — footer text-box bottom at `198 − 9.25`, rule gaps 4/4 — instead
23
- * of drifting by fractional pixels (DIF-04). Text baselines follow the
24
- * kit's glyph bounds: a 24 px role sits 22 px above its baseline, the
25
- * 22 px kicker and the 32 px title at their own size (cf. the frozen SVG:
26
- * kicker baseline `headerY + 16 + 22`, title `+ 32`, subtitle `+ 22`).
27
- */
28
3
  /** Frozen card geometry, in card pixels (spec §5.3, Appendix A). */
29
4
  export const CARD_GEOMETRY = {
30
5
  width: 460,
@@ -76,6 +51,31 @@ export const CARD_GEOMETRY = {
76
51
  /** Card allocations, frozen-box-derived (see module doc). */
77
52
  allocatedLines: { kicker: 1, title: 2, body: 2, footer: 1 },
78
53
  };
54
+ /**
55
+ * Compact card geometry (`diagram-anatomy/v2`): `352 × 154` with padding
56
+ * `6`, header inset `12`, accent `6`, icon `52` / gap `4`. Type scale is
57
+ * unchanged (`22 / 32 / 24`). Unlisted leaves keep their v1 values. Title is
58
+ * one line first (owner addendum 8): over-long titles report `card-overflow`
59
+ * instead of growing the box. The folded header width is derived, not
60
+ * pinned: `352 − border 2 − padding 6 − toggle 66 − headerText 68 = 210`.
61
+ */
62
+ export const CARD_GEOMETRY_V2 = {
63
+ ...CARD_GEOMETRY,
64
+ width: 352,
65
+ height: 154,
66
+ padding: 6,
67
+ accentWidth: 6,
68
+ headerInset: 12,
69
+ iconSize: 52,
70
+ iconTextGap: 4,
71
+ foldedHeaderTextWidth: 210,
72
+ /** Title on one line first (addendum 8); v1 keeps two lines. */
73
+ allocatedLines: { kicker: 1, title: 1, body: 2, footer: 1 },
74
+ };
75
+ /** Select the card geometry for a pinned anatomy (default `"v1"`). */
76
+ export function anatomyCardGeometry(anatomy) {
77
+ return anatomy === "v2" ? CARD_GEOMETRY_V2 : CARD_GEOMETRY;
78
+ }
79
79
  /**
80
80
  * Edge label typography (DC-2a, tokens `diagramScene.edgeLabelFontSize` /
81
81
  * `diagramScene.edgeLabelLineHeight`): 18 px on a 22 px line box. One line
@@ -143,6 +143,14 @@ export function projectCardProps(presentation, opts) {
143
143
  ...(presentation.categoryRef === undefined ? {} : { tone: presentation.categoryRef }),
144
144
  ...(presentation.proposed === undefined ? {} : { proposed: presentation.proposed }),
145
145
  ...(opts.toggle === undefined ? {} : { toggle: opts.toggle }),
146
+ ...(() => {
147
+ const anatomy = presentation.anatomy ?? opts.anatomy;
148
+ return anatomy === undefined ? {} : { anatomy };
149
+ })(),
150
+ ...(() => {
151
+ const align = presentation.align ?? opts.align;
152
+ return align === undefined ? {} : { align };
153
+ })(),
146
154
  },
147
155
  };
148
156
  }
@@ -538,14 +546,15 @@ export function headerSlotGeometry(opts) {
538
546
  const kickerHeight = lineBoxHeight(g.kicker.size);
539
547
  const titleHeight = lineBoxHeight(g.title.size);
540
548
  const contentHeight = opts.kickerLines * kickerHeight + opts.titleLines * titleHeight;
541
- const blockHeight = opts.hasIcon ? Math.max(g.iconSize, contentHeight) : contentHeight;
549
+ const iconSize = opts.iconSize ?? g.iconSize;
550
+ const blockHeight = opts.hasIcon ? Math.max(iconSize, contentHeight) : contentHeight;
542
551
  return {
543
552
  kickerHeight,
544
553
  titleHeight,
545
554
  contentHeight,
546
555
  blockHeight,
547
556
  textTopOffset: (blockHeight - contentHeight) / 2,
548
- iconTopOffset: opts.hasIcon ? (blockHeight - g.iconSize) / 2 : 0,
557
+ iconTopOffset: opts.hasIcon ? (blockHeight - iconSize) / 2 : 0,
549
558
  };
550
559
  }
551
560
  /** Fixed-slot truncation shared by cards and zones (owner A14). */
@@ -580,20 +589,14 @@ export function cardFullText(props) {
580
589
  export function zoneFullText(props) {
581
590
  return [props.kicker, props.title, props.subtitle, props.footer].filter(Boolean).join('\n');
582
591
  }
583
- /**
584
- * Lay out fixed card slots with measured ellipses and a pinned footer.
585
- * Informational diagnostics retain the original text and hidden length.
586
- * Missing glyphs use the visible unknown icon (owner A2/A11).
587
- */
588
- export function layoutCard(props, measure) {
592
+ function layoutCardAt(props, measure, anatomy, align) {
589
593
  const icon = props.icon ?? "base";
590
594
  const suppressed = icon === "none";
591
595
  const missing = !suppressed && props.iconGlyph === undefined && getDiagramGlyph(icon) === undefined;
592
596
  props = { ...props, autoSize: props.autoSize ?? true, icon: missing ? "unknown" : icon,
593
597
  iconGlyph: suppressed ? { face: "" } : props.iconGlyph ?? getDiagramGlyph(icon) ?? getDiagramGlyph("unknown") };
594
- const g = CARD_GEOMETRY;
598
+ const g = anatomyCardGeometry(anatomy);
595
599
  const diagnostics = missing ? [{ code: "card-icon-missing", slot: "icon", entityId: props.entityId, neededPx: 1, allocatedPx: 0 }] : [];
596
- const align = props.align ?? "left";
597
600
  const bodyMode = props.bodyMode ?? "leaf";
598
601
  const contentTop = g.borderWidth + g.padding;
599
602
  const contentRight = g.width - g.borderWidth - g.padding;
@@ -639,6 +642,7 @@ export function layoutCard(props, measure) {
639
642
  hasIcon,
640
643
  kickerLines: kickerTexts.length,
641
644
  titleLines: titleTexts.length,
645
+ iconSize: g.iconSize,
642
646
  });
643
647
  const kickerHeight = headerGeo.kickerHeight;
644
648
  const titleHeight = headerGeo.titleHeight;
@@ -658,11 +662,13 @@ export function layoutCard(props, measure) {
658
662
  // (collapsed zone, §6.2.1) the body is the centred subtitle: wrapped at the
659
663
  // frozen 396 px measure (width − 2 × (collapsedInset + marginInline)).
660
664
  const subtitleMode = bodyMode === "subtitle";
661
- const subtitleMeasure = g.width - 2 * (ZONE_GEOMETRY.collapsedInset + ZONE_GEOMETRY.collapsedSubtitleMarginInline);
665
+ const subtitleMeasure = g.width - 2 * (anatomyZoneGeometry(anatomy).collapsedInset + anatomyZoneGeometry(anatomy).collapsedSubtitleMarginInline);
662
666
  const bodyTextX = subtitleMode ? (g.width - subtitleMeasure) / 2 : g.bodyInsetFromBar;
663
667
  const bodyWidth = subtitleMode ? subtitleMeasure : contentRight - bodyTextX;
664
- const bodyAnchor = subtitleMode || align === "center" ? "middle" : "start";
665
- const bodyLineX = bodyAnchor === "middle" ? bodyTextX + bodyWidth / 2 : bodyTextX;
668
+ // The body block is centred horizontally inside its box on every card
669
+ // (owner card-body-centring): each line anchors middle at the box centre.
670
+ const bodyAnchor = "middle";
671
+ const bodyLineX = bodyTextX + bodyWidth / 2;
666
672
  const wrappedBody = [];
667
673
  let detailLines = 0;
668
674
  for (const [bodyIndex, line] of props.body.entries()) {
@@ -700,11 +706,11 @@ export function layoutCard(props, measure) {
700
706
  const bodyAreaBottom = ruleY === undefined ? g.height - g.borderWidth - g.padding : ruleY - g.ruleMargin;
701
707
  const bodyBudget = Math.max(0, Math.floor((bodyAreaBottom - bodyY) / bodyHeight));
702
708
  const bodyTexts = fitSlot(bodySourceText, "body", bodyWidth, bodyBudget, bodySlot);
703
- // Subtitle mode centres the line block vertically inside the body area
704
- // (§6.2.1); leaf lines stay top-aligned (§5.2).
705
- const bodyBlockTop = subtitleMode
706
- ? bodyY + Math.max(0, (bodyAreaBottom - bodyY - bodyTexts.length * bodyHeight) / 2)
707
- : bodyY;
709
+ // The line block is centred vertically inside the remaining body area on
710
+ // every card (owner card-body-centring) — leaf lines exactly like the
711
+ // collapsed-zone subtitle (§6.2.1). A block that fills the area keeps the
712
+ // top-aligned baselines; a shorter block drops by half the spare space.
713
+ const bodyBlockTop = bodyY + Math.max(0, (bodyAreaBottom - bodyY - bodyTexts.length * bodyHeight) / 2);
708
714
  const detailStart = wrappedBody.length - detailLines;
709
715
  const body = bodyTexts.map((text, index) => ({
710
716
  text,
@@ -715,7 +721,7 @@ export function layoutCard(props, measure) {
715
721
  secondary: !subtitleMode && index >= detailStart && (props.detailCount ?? 0) > 0,
716
722
  anchor: bodyAnchor,
717
723
  }));
718
- const bodyBottom = bodyY + bodyTexts.length * bodyHeight;
724
+ const bodyBottom = bodyBlockTop + bodyTexts.length * bodyHeight;
719
725
  const kicker = kickerTexts.map((text, index) => ({
720
726
  text,
721
727
  x: headerLineX,
@@ -774,6 +780,44 @@ export function layoutCard(props, measure) {
774
780
  diagnostics,
775
781
  };
776
782
  }
783
+ /**
784
+ * Lay out fixed card slots with measured ellipses and a pinned footer.
785
+ * Informational diagnostics retain the original text and hidden length.
786
+ * Missing glyphs use the visible unknown icon (owner A2/A11).
787
+ * Compact `v2` cards default to `"center"` alignment and fall back per box
788
+ * to frozen `v1` (`460 × 200`) on overflow instead of dropping slots.
789
+ */
790
+ export function layoutCard(props, measure) {
791
+ const align = props.align ?? (props.anatomy === "v2" ? "center" : "left");
792
+ const primary = layoutCardAt(props, measure, props.anatomy, align);
793
+ if (props.anatomy !== "v2")
794
+ return primary;
795
+ const v2Overflows = primary.diagnostics.filter((diagnostic) => diagnostic.code === "card-overflow");
796
+ if (v2Overflows.length === 0)
797
+ return primary;
798
+ const fallback = layoutCardAt(props, measure, "v1", align);
799
+ const stillOverflows = fallback.diagnostics.some((diagnostic) => diagnostic.code === "card-overflow");
800
+ const diagnostics = stillOverflows
801
+ ? [...fallback.diagnostics]
802
+ : [
803
+ ...fallback.diagnostics,
804
+ ...v2Overflows.map((diagnostic) => ({
805
+ code: "card-overflow",
806
+ slot: diagnostic.slot,
807
+ entityId: diagnostic.entityId,
808
+ neededPx: diagnostic.neededPx,
809
+ allocatedPx: diagnostic.allocatedPx,
810
+ ...(diagnostic.text === undefined ? {} : { text: diagnostic.text }),
811
+ severity: "info",
812
+ reason: "fallback-v1",
813
+ })),
814
+ ];
815
+ return {
816
+ ...fallback,
817
+ anatomyFallback: "v1",
818
+ diagnostics,
819
+ };
820
+ }
777
821
  /* ------------------------------------------------------------------ *
778
822
  * DC-2 static half — the wrapping card `DiagramZone` (spec §6). *
779
823
  * Same module, same rules: zero imports, one geometry source. *
@@ -832,6 +876,41 @@ export const ZONE_GEOMETRY = {
832
876
  collapsedSubtitleMarginInline: 16,
833
877
  allocatedLines: { kicker: 1, title: 2, subtitle: 2, footer: 1 },
834
878
  };
879
+ /**
880
+ * Compact zone geometry (`diagram-anatomy/v2`): the collapsed zone IS the
881
+ * compact card (`352 × 154`, collapsed subtitle measure `352 − 2 × 32`);
882
+ * expanded chrome follows the compact insets (header `12`, icon `52`,
883
+ * gap `4`). Unlisted leaves keep v1 values; type scale unchanged.
884
+ */
885
+ export const ZONE_GEOMETRY_V2 = {
886
+ ...ZONE_GEOMETRY,
887
+ headerInset: CARD_GEOMETRY_V2.headerInset,
888
+ iconSize: CARD_GEOMETRY_V2.iconSize,
889
+ iconTextGap: CARD_GEOMETRY_V2.iconTextGap,
890
+ /**
891
+ * Expanded header text inset for v2: `12 + 52 + 4 + 86 = 154` so the
892
+ * inline-end toggle reserve stays `86 px` (matching v1) instead of
893
+ * growing to `110 px`.
894
+ */
895
+ headerTextInset: 154,
896
+ collapsedWidth: CARD_GEOMETRY_V2.width,
897
+ collapsedHeight: CARD_GEOMETRY_V2.height,
898
+ allocatedLines: { kicker: 1, title: 1, subtitle: 2, footer: 1 },
899
+ };
900
+ /** Select the zone geometry for a pinned anatomy (default `"v1"`). */
901
+ export function anatomyZoneGeometry(anatomy) {
902
+ return anatomy === "v2" ? ZONE_GEOMETRY_V2 : ZONE_GEOMETRY;
903
+ }
904
+ /** Nesting depth of a zone: `0` is the top level. */
905
+ export function normalizeZoneDepth(depth) {
906
+ if (depth === undefined || !Number.isFinite(depth))
907
+ return 0;
908
+ return Math.max(0, Math.floor(depth));
909
+ }
910
+ /** Resolve the depth surface for a zone (default start parity `0`). */
911
+ export function zoneDepthSurface(depth, startParity = 0) {
912
+ return (normalizeZoneDepth(depth) + startParity) % 2 === 0 ? "surface1" : "surface2";
913
+ }
835
914
  /** Centred collapsed-subtitle measure (§6.2.1): 460 − 2 × (16 + 16). */
836
915
  export const COLLAPSED_SUBTITLE_MEASURE = ZONE_GEOMETRY.collapsedWidth -
837
916
  2 * (ZONE_GEOMETRY.collapsedInset + ZONE_GEOMETRY.collapsedSubtitleMarginInline);
@@ -846,6 +925,7 @@ export function zoneCollapsedCardProps(props) {
846
925
  return {
847
926
  ...(props.autoSize === undefined ? {} : { autoSize: props.autoSize }),
848
927
  ...(props.height === undefined ? {} : { height: props.height }),
928
+ ...(props.anatomy === undefined ? {} : { anatomy: props.anatomy }),
849
929
  entityId: props.entityId,
850
930
  ...(props.kicker === undefined ? {} : { kicker: props.kicker }),
851
931
  title: props.title,
@@ -859,6 +939,11 @@ export function zoneCollapsedCardProps(props) {
859
939
  ? {}
860
940
  : { toggle: { collapsed: true, label: props.toggleLabel } }),
861
941
  ...(props.align === undefined ? {} : { align: props.align }),
942
+ // A folded zone keeps its depth background (owner addendum 1); no pin
943
+ // means no surface key, so unthreaded cards render byte-identical.
944
+ ...((props.depth === undefined && props.depthParityStart === undefined
945
+ ? {}
946
+ : { surface: zoneDepthSurface(props.depth, props.depthParityStart) })),
862
947
  bodyMode: "subtitle",
863
948
  };
864
949
  }
@@ -891,10 +976,23 @@ export function layoutZone(props, measure, children = []) {
891
976
  const missing = !suppressed && props.iconGlyph === undefined && getDiagramGlyph(icon) === undefined;
892
977
  props = { ...props, autoSize: props.autoSize ?? true, icon: missing ? "unknown" : icon,
893
978
  iconGlyph: suppressed ? { face: "" } : props.iconGlyph ?? getDiagramGlyph(icon) ?? getDiagramGlyph("unknown") };
894
- const g = { ...ZONE_GEOMETRY, ...(props.containerPadding === undefined ? {} : { contentInsetTop: props.containerPadding, contentInsetBottom: props.containerPadding, contentInsetInline: props.containerPadding }) };
979
+ const g = { ...anatomyZoneGeometry(props.anatomy), ...(props.containerPadding === undefined ? {} : { contentInsetTop: props.containerPadding, contentInsetBottom: props.containerPadding, contentInsetInline: props.containerPadding }) };
895
980
  const x = props.x ?? 0;
896
981
  const y = props.y ?? 0;
897
982
  const diagnostics = missing ? [{ code: "card-icon-missing", slot: "icon", entityId: props.entityId, neededPx: 1, allocatedPx: 0 }] : [];
983
+ // Owner addendum 1: resolve the depth surface once; both states and the
984
+ // folded card share it, so fold/unfold never repaints the layer. Without
985
+ // depth pins the layout keeps its exact v1 shape (anatomy golden).
986
+ const hasDepthPins = props.depth !== undefined || props.depthParityStart !== undefined;
987
+ const depth = normalizeZoneDepth(props.depth);
988
+ const surface = zoneDepthSurface(props.depth, props.depthParityStart);
989
+ // Informational and opt-in: a leaf card (default card surface) on a
990
+ // same-colour zone surface. Only explicit children compositions report
991
+ // it — hosts lay children out flat, so host rendering never changes.
992
+ if (props.reportSurfaceSame === true && surface === "surface1"
993
+ && children.some((child) => child.kind === "card" && child.zone === undefined && child.card?.tone === undefined)) {
994
+ diagnostics.push({ code: "zone-surface-same", slot: "surface", entityId: props.entityId, neededPx: 1, allocatedPx: 0 });
995
+ }
898
996
  if (missing) {
899
997
  diagnostics.push({
900
998
  code: "zone-icon-unknown",
@@ -914,13 +1012,16 @@ export function layoutZone(props, measure, children = []) {
914
1012
  neededPx: diagnostic.neededPx,
915
1013
  allocatedPx: diagnostic.allocatedPx,
916
1014
  ...(diagnostic.text === undefined ? {} : { text: diagnostic.text }),
917
- ...(diagnostic.hiddenLength === undefined ? {} : { hiddenLength: diagnostic.hiddenLength, severity: diagnostic.severity, reason: diagnostic.reason }),
1015
+ ...(diagnostic.severity === undefined ? {} : { severity: diagnostic.severity }),
1016
+ ...(diagnostic.reason === undefined ? {} : { reason: diagnostic.reason }),
1017
+ ...(diagnostic.hiddenLength === undefined ? {} : { hiddenLength: diagnostic.hiddenLength }),
918
1018
  });
919
1019
  }
920
1020
  return {
921
1021
  icon: { name: props.icon, glyph: props.iconGlyph },
922
- box: { x, y, width: g.collapsedWidth, height: card.box.height },
1022
+ box: { x, y, width: card.box.width, height: card.box.height },
923
1023
  collapsed: true,
1024
+ ...(hasDepthPins ? { surface, depth } : {}),
924
1025
  card,
925
1026
  diagnostics,
926
1027
  };
@@ -939,7 +1040,7 @@ export function layoutZone(props, measure, children = []) {
939
1040
  ? g.headerInset
940
1041
  : g.headerTextInset - (g.headerInset + g.iconSize + g.iconTextGap);
941
1042
  const headerTextWidth = Math.max(0, x + width - headerTextX - rightHeaderReserve);
942
- const align = props.align ?? "left";
1043
+ const align = props.align ?? (props.anatomy === "v2" ? "center" : "left");
943
1044
  const headerAnchor = align === "center" ? "middle" : "start";
944
1045
  const headerLineX = align === "center" ? headerTextX + headerTextWidth / 2 : headerTextX;
945
1046
  const fitSlot = (text, role, width, budget, slot = role) => truncateSlot(text, role, width, budget, measure, diagnostic => diagnostics.push({ ...diagnostic, code: "zone-overflow", slot, entityId: props.entityId }));
@@ -956,6 +1057,7 @@ export function layoutZone(props, measure, children = []) {
956
1057
  hasIcon,
957
1058
  kickerLines: kickerTexts.length,
958
1059
  titleLines: titleTexts.length,
1060
+ iconSize: g.iconSize,
959
1061
  });
960
1062
  const kickerHeight = headerGeo.kickerHeight;
961
1063
  const titleHeight = headerGeo.titleHeight;
@@ -1079,6 +1181,7 @@ export function layoutZone(props, measure, children = []) {
1079
1181
  icon: { name: props.icon, glyph: props.iconGlyph },
1080
1182
  box: { x, y, width, height },
1081
1183
  collapsed: false,
1184
+ ...(hasDepthPins ? { surface, depth } : {}),
1082
1185
  header: {
1083
1186
  ...(iconBox === undefined ? {} : { iconBox }),
1084
1187
  headerTextX,
@@ -1137,9 +1240,24 @@ export function projectZoneProps(presentation, opts) {
1137
1240
  })()),
1138
1241
  ...(presentation.categoryRef === undefined ? {} : { tone: presentation.categoryRef }),
1139
1242
  ...(presentation.proposed === undefined ? {} : { proposed: presentation.proposed }),
1243
+ ...(() => {
1244
+ const anatomy = presentation.anatomy ?? opts.anatomy;
1245
+ return anatomy === undefined ? {} : { anatomy };
1246
+ })(),
1140
1247
  collapsed: opts.collapsed,
1141
1248
  ...(opts.toggleLabel === undefined ? {} : { toggleLabel: opts.toggleLabel }),
1142
- ...(opts.align === undefined ? {} : { align: opts.align }),
1249
+ ...(() => {
1250
+ const align = presentation.align ?? opts.align;
1251
+ return align === undefined ? {} : { align };
1252
+ })(),
1253
+ ...(() => {
1254
+ const depth = presentation.depth ?? opts.depth;
1255
+ return depth === undefined ? {} : { depth };
1256
+ })(),
1257
+ ...(() => {
1258
+ const start = presentation.depthParityStart ?? opts.depthParityStart;
1259
+ return start === undefined ? {} : { depthParityStart: start };
1260
+ })(),
1143
1261
  ...(opts.x === undefined ? {} : { x: opts.x }),
1144
1262
  ...(opts.y === undefined ? {} : { y: opts.y }),
1145
1263
  ...(opts.width === undefined ? {} : { width: opts.width }),
@@ -1,6 +1,7 @@
1
1
  import { type FlowIndex, type FlowStep } from "@sentropic/diagram-core";
2
2
  import type { FlowArrow, FlowBundle, FlowVisibleTarget } from "../layout/flows.js";
3
- import type { Visible } from "./flowModel.js";
3
+ import { type Visible } from "./flowModel.js";
4
+ import type { DiagramSceneFigureLabels } from "./diagramSceneTypes.js";
4
5
  import { type ErdCard } from "./erd.js";
5
6
  /**
6
7
  * `DiagramSceneFigure` — the pure half of the scene host (DC-2a lot L4,
@@ -18,6 +19,7 @@ import { type ErdCard } from "./erd.js";
18
19
  import { layoutMeasured, type CameraFit, type LayoutCacheStats, type LayoutHints, type LayoutMetrics, type LayoutOptions, type LayoutResult, type LevelOrientation, type LineMeasurer, type Rect, type RowPackOptions, type Vec2 } from "../index.js";
19
20
  import { type BundleLabelGroup } from "../layout/bundleLabel.js";
20
21
  import type { EntityPresentation } from "@sentropic/diagram-core";
22
+ import type { AlignPinned, AnatomyPinned, DepthPinned } from "./diagramCardModel.js";
21
23
  /** The semantic document the layout engine reads. */
22
24
  export type SceneDocument = Parameters<typeof layoutMeasured>[0];
23
25
  /** A view document: the optional retained source view, and the emitted view. */
@@ -67,10 +69,12 @@ export type SceneIconBindings = Readonly<Record<string, {
67
69
  readonly shape?: "component" | "flow" | "erd" | "note";
68
70
  }>>;
69
71
  export declare const ROLE_ICONS: Readonly<Record<string, string>>;
70
- export declare function resolveScenePresentation(document: SceneDocument, presentation: ScenePresentation, bindings?: SceneIconBindings, strict?: boolean, view?: SceneView, resolveGlyph?: (name: string) => import("./diagramCardModel.js").DiagramGlyphPaths | undefined): {
72
+ export declare function resolveScenePresentation(document: SceneDocument, presentation: ScenePresentation, bindings?: SceneIconBindings, strict?: boolean, view?: SceneView, resolveGlyph?: (name: string) => import("./diagramCardModel.js").DiagramGlyphPaths | undefined, options?: {
73
+ readonly depthParityStart?: 0 | 1;
74
+ }): {
71
75
  presentation: {
72
76
  entities: {
73
- [k: string]: EntityPresentation;
77
+ [k: string]: EntityPresentation & AnatomyPinned & AlignPinned & DepthPinned;
74
78
  };
75
79
  contractPin: import("@sentropic/diagram-core").PresentationPin;
76
80
  legends: Readonly<Record<string, import("@sentropic/diagram-core").LegendPresentation>>;
@@ -81,6 +85,13 @@ export declare function resolveScenePresentation(document: SceneDocument, presen
81
85
  export interface SceneLayoutInput {
82
86
  readonly iconBindings?: SceneIconBindings;
83
87
  readonly strictIcons?: boolean;
88
+ /**
89
+ * Owner addendum 1 — selectable start parity for the depth rule: `1`
90
+ * flips which parity the top level takes. Absent means `0`.
91
+ */
92
+ readonly depthParityStart?: 0 | 1;
93
+ /** Opt-in informational `zone-surface-same` diagnostic on untinted leaf cards inside `surface1` zones. */
94
+ readonly reportSurfaceSame?: boolean;
84
95
  readonly resolveGlyph?: (name: string) => import("./diagramCardModel.js").DiagramGlyphPaths | undefined;
85
96
  readonly cache?: SceneLayoutCache;
86
97
  readonly document: SceneDocument;
@@ -117,7 +128,7 @@ export interface SceneNodeModel {
117
128
  /** Zones only: drawn as the atomic card (collapsed) or as the frame. */
118
129
  readonly collapsed: boolean;
119
130
  readonly rect: Rect;
120
- readonly presentation?: EntityPresentation;
131
+ readonly presentation?: EntityPresentation & AnatomyPinned & AlignPinned & DepthPinned;
121
132
  /** Text of a node with no card form (L-R12 label) or of a legend key. */
122
133
  readonly text: string;
123
134
  readonly erd?: ErdCard;
@@ -237,9 +248,11 @@ export interface SceneModel {
237
248
  * collapsed boxes and the title band of each expanded zone — an expanded
238
249
  * zone's interior is not a blocker on the row-pack path).
239
250
  */
240
- export declare function resolveScene(result: SceneLaidOut, input: Pick<SceneLayoutInput, "document" | "presentation" | "measureLines" | "metrics" | "iconBindings" | "strictIcons" | "view" | "resolveGlyph" | "flows">): SceneModel;
241
- /** Full presentation text retained alongside the textual relations (A14). */
242
- export declare function sceneTextRows(scene: SceneModel, document: SceneDocument): readonly string[];
251
+ export declare function resolveScene(result: SceneLaidOut, input: Pick<SceneLayoutInput, "document" | "presentation" | "measureLines" | "metrics" | "iconBindings" | "strictIcons" | "view" | "resolveGlyph" | "flows" | "depthParityStart">): SceneModel;
252
+ /** Default labels for `DiagramSceneFigure`, including the DE-1b containment fallback label. */
253
+ export declare const DEFAULT_SCENE_LABELS: DiagramSceneFigureLabels;
254
+ /** Full presentation text retained alongside the textual relations (A14, DE-1b). */
255
+ export declare function sceneTextRows(scene: SceneModel, document: SceneDocument, labels?: Partial<Pick<DiagramSceneFigureLabels, "contains">>): readonly string[];
243
256
  export interface SceneCameraInput {
244
257
  readonly bounds?: Rect;
245
258
  readonly viewWidth: number;
@@ -1,4 +1,5 @@
1
1
  import { flowIndex, parentOccurrenceOf, representativeOf } from "@sentropic/diagram-core";
2
+ import { DEFAULT_FLOW_STRINGS } from "./flowModel.js";
2
3
  import { measureErdCard, renderErdMarkerSvg, erdText, wrapErdText, placeErdRoleLabels, ERD_GEOMETRY } from "./erd.js";
3
4
  /**
4
5
  * `DiagramSceneFigure` — the pure half of the scene host (DC-2a lot L4,
@@ -16,7 +17,7 @@ import { measureErdCard, renderErdMarkerSvg, erdText, wrapErdText, placeErdRoleL
16
17
  import { buildScene, cameraFit, clampZoom, CONTENT_INSET, DEFAULT_ALLOCATED_LINES, DEFAULT_LAYOUT_METRICS, DEFAULT_MIN_READABLE_SCALE, FIT_PAINT_INSET, layoutFolded, layoutMeasured, placeEdgeLabels, rectUnion, relationRoute, sceneNodes, sceneEdges, } from "../index.js";
17
18
  import { measureBundleLabel } from "../layout/bundleLabel.js";
18
19
  import { getDiagramGlyph } from "./registry.js";
19
- import { lineBoxHeight, ZONE_GEOMETRY } from "./diagramCardModel.js";
20
+ import { anatomyZoneGeometry, lineBoxHeight, ZONE_GEOMETRY } from "./diagramCardModel.js";
20
21
  import { clearSceneLabels } from "./sceneLabelClearance.js";
21
22
  /**
22
23
  * `targetWidth` handed to the engine when the host supplies none. The
@@ -39,27 +40,92 @@ export function sceneContentSize(result) {
39
40
  return result?.status === "laid-out" ? { width: result.fit.width, height: result.fit.height } : { width: 0, height: 0 };
40
41
  }
41
42
  export const ROLE_ICONS = { card: "base", zone: "cluster", store: "db", actor: "user", api: "api", runtime: "server" };
42
- export function resolveScenePresentation(document, presentation, bindings = {}, strict = true, view, resolveGlyph = getDiagramGlyph) {
43
+ export function resolveScenePresentation(document, presentation, bindings = {}, strict = true, view, resolveGlyph = getDiagramGlyph, options = {}) {
43
44
  const missing = [];
45
+ /**
46
+ * View-level anatomy default (DE-1): a view pins `diagram-anatomy/v1 | v2`
47
+ * and its boxes inherit the pin unless they carry their own. Absent
48
+ * everywhere means `"v1"` — existing views do not move.
49
+ */
50
+ const viewAnatomy = view?.presentation?.anatomy;
51
+ const withViewAnatomy = (entry) => entry.anatomy === undefined && viewAnatomy !== undefined ? { ...entry, anatomy: viewAnatomy } : entry;
44
52
  const entities = Object.fromEntries(Object.entries(presentation.entities).map(([id, entry]) => {
45
53
  if (entry.form !== "card" && entry.form !== "container" && entry.form !== "legend")
46
- return [id, entry];
54
+ return [id, withViewAnatomy(entry)];
47
55
  const entityId = view?.entityOccurrences[id]?.entity ?? id.replace(/^occurrence:e\./, "entity:");
48
56
  const entity = document.entities[entityId];
49
57
  if (entity?.profile === "erd@1")
50
- return [id, entry];
58
+ return [id, withViewAnatomy(entry)];
51
59
  const binding = bindings[entity === undefined ? "" : entity.profile + ":" + entity.type] ?? bindings[entity?.type ?? ""];
52
60
  if (binding?.shape !== undefined && binding.shape !== "component")
53
- return [id, { ...entry, icon: entry.icon ?? "none" }];
61
+ return [id, withViewAnatomy({ ...entry, icon: entry.icon ?? "none" })];
54
62
  const role = binding?.role ?? (entry.form === "card" ? "card" : "zone");
55
63
  const icon = entry.icon ?? binding?.icon ?? ROLE_ICONS[role];
64
+ if (icon === "none")
65
+ return [id, withViewAnatomy({ ...entry, icon: "none" })];
56
66
  if (icon === undefined || resolveGlyph(icon) === undefined) {
57
67
  missing.push(id);
58
- return [id, { ...entry, icon: strict ? "unknown" : "none" }];
68
+ return [id, withViewAnatomy({ ...entry, icon: strict ? "unknown" : "none" })];
69
+ }
70
+ return [id, withViewAnatomy({ ...entry, icon })];
71
+ }));
72
+ /**
73
+ * Owner addendum 1 — stamp nesting depth from the view groups (or from
74
+ * semantic `contains` relations when no view is supplied) onto zone
75
+ * entries (top level `0`), so frames alternate without page code. Entries
76
+ * pinning their own depth keep it; card entries are untouched (their
77
+ * semantic tints never change). The selectable `startParity` rides along
78
+ * the same way when the scene selects it.
79
+ */
80
+ const startParity = options.depthParityStart ?? 0;
81
+ const hasViewGroups = view !== undefined && Object.keys(view.groups).length > 0;
82
+ const semanticParentOf = new Map();
83
+ if (!hasViewGroups && document.relations !== undefined) {
84
+ for (const relation of Object.values(document.relations)) {
85
+ const baseType = document.typeDefinitions?.[relation.type]?.baseType ?? relation.type;
86
+ if (baseType !== "contains")
87
+ continue;
88
+ const parent = relation.endpoints.find((endpoint) => endpoint.role === "parent")?.target;
89
+ const child = relation.endpoints.find((endpoint) => endpoint.role === "child")?.target;
90
+ if (parent !== undefined && child !== undefined)
91
+ semanticParentOf.set(child, parent);
92
+ }
93
+ }
94
+ const depthOf = (id) => {
95
+ let depth = 0;
96
+ const seen = new Set();
97
+ if (hasViewGroups) {
98
+ for (let parent = parentOccurrenceOf(view, id); parent !== undefined && !seen.has(parent); parent = parentOccurrenceOf(view, parent)) {
99
+ seen.add(parent);
100
+ depth += 1;
101
+ }
102
+ return depth;
59
103
  }
60
- return [id, { ...entry, icon }];
104
+ const entityId = view?.entityOccurrences[id]?.entity ?? id.replace(/^occurrence:e\./, "entity:");
105
+ for (let parent = semanticParentOf.get(entityId); parent !== undefined && !seen.has(parent); parent = semanticParentOf.get(parent)) {
106
+ seen.add(parent);
107
+ depth += 1;
108
+ }
109
+ return depth;
110
+ };
111
+ const stamped = Object.fromEntries(Object.entries(entities).map(([id, entry]) => {
112
+ const zone = entry;
113
+ if (zone.form !== "container" && zone.form !== "legend")
114
+ return [id, entry];
115
+ // Lean stamps: the top level and the default parity need no key
116
+ // (absent means `0` / `0` everywhere downstream). Explicit depth pins are
117
+ // preserved while still inheriting a non-default scene `depthParityStart`.
118
+ const depth = zone.depth === undefined ? depthOf(id) : undefined;
119
+ const needsParity = zone.depthParityStart === undefined && startParity !== 0;
120
+ if ((depth === undefined || depth === 0) && !needsParity)
121
+ return [id, entry];
122
+ return [id, {
123
+ ...entry,
124
+ ...(depth === undefined || depth === 0 ? {} : { depth }),
125
+ ...(needsParity ? { depthParityStart: startParity } : {}),
126
+ }];
61
127
  }));
62
- return { presentation: { ...presentation, entities }, missing };
128
+ return { presentation: { ...presentation, entities: stamped }, missing };
63
129
  }
64
130
  /**
65
131
  * One full layout pass (§6.5: fold → measure → place → route, never patched).
@@ -69,7 +135,7 @@ export function resolveScenePresentation(document, presentation, bindings = {},
69
135
  * required field carries no second metric source.
70
136
  */
71
137
  export function layoutScene(input) {
72
- const resolved = resolveScenePresentation(input.document, input.presentation, input.iconBindings, input.strictIcons, input.view, input.resolveGlyph);
138
+ const resolved = resolveScenePresentation(input.document, input.presentation, input.iconBindings, input.strictIcons, input.view, input.resolveGlyph, input.depthParityStart === undefined ? {} : { depthParityStart: input.depthParityStart });
73
139
  const options = {
74
140
  registry: input.registry,
75
141
  ...(input.flows === undefined ? {} : { flows: input.flows }),
@@ -93,6 +159,7 @@ export function layoutScene(input) {
93
159
  rowPack: input.rowPack ?? {},
94
160
  targetWidth: input.targetWidth ?? DEFAULT_SCENE_TARGET_WIDTH,
95
161
  ...(input.previousOrientation === undefined ? {} : { previousOrientation: input.previousOrientation }),
162
+ ...(input.reportSurfaceSame === undefined ? {} : { reportSurfaceSame: input.reportSurfaceSame }),
96
163
  };
97
164
  const result = input.cache !== undefined
98
165
  ? (input.view === undefined
@@ -164,7 +231,7 @@ function edgeLabelOf(document, relation) {
164
231
  */
165
232
  export function resolveScene(result, input) {
166
233
  const view = result.view;
167
- const resolved = resolveScenePresentation(input.document, input.presentation, input.iconBindings, input.strictIcons, input.view, input.resolveGlyph);
234
+ const resolved = resolveScenePresentation(input.document, input.presentation, input.iconBindings, input.strictIcons, view, input.resolveGlyph, input.depthParityStart === undefined ? {} : { depthParityStart: input.depthParityStart });
168
235
  const frame = buildScene({ document: input.document, views: { [view.viewId]: view } }, view.viewId);
169
236
  const bundledMembers = new Set(Object.values(result.edgeBundles ?? {}).flatMap(bundle => bundle.members.slice(1)));
170
237
  const items = frame.items.filter(item => item.kind !== "edge" || !bundledMembers.has(item.occurrence));
@@ -213,26 +280,27 @@ export function resolveScene(result, input) {
213
280
  const height = headerHeights.get(node.occurrence);
214
281
  if (height === undefined)
215
282
  continue;
216
- const ruleClearance = (ZONE_GEOMETRY.ruleHeight / 2 + 1) / DEFAULT_MIN_READABLE_SCALE;
283
+ const zoneGeo = anatomyZoneGeometry(node.presentation?.anatomy);
284
+ const ruleClearance = (zoneGeo.ruleHeight / 2 + 1) / DEFAULT_MIN_READABLE_SCALE;
217
285
  blockers.push({
218
286
  x: node.rect.x,
219
287
  y: node.rect.y,
220
288
  width: node.rect.width,
221
- height: CONTENT_INSET + height + ZONE_GEOMETRY.ruleHeight / 2 + ruleClearance,
289
+ height: zoneGeo.headerInset + height + zoneGeo.ruleHeight / 2 + ruleClearance,
222
290
  });
223
291
  // A zone footer has one allocated line. Reserve its fixed chrome from
224
292
  // the presentation instead of measuring the scene again during replay.
225
293
  const reserve = node.presentation?.text.footer?.trim()
226
- ? lineBoxHeight(ZONE_GEOMETRY.footer.size) + ZONE_GEOMETRY.ruleHeight + 2 * ZONE_GEOMETRY.ruleMargin + ZONE_GEOMETRY.footerBottomInset : 0;
294
+ ? lineBoxHeight(zoneGeo.footer.size) + zoneGeo.ruleHeight + 2 * zoneGeo.ruleMargin + zoneGeo.footerBottomInset : 0;
227
295
  if (reserve > 0) {
228
- blockers.push({ x: node.rect.x, y: node.rect.y + node.rect.height - reserve - ZONE_GEOMETRY.borderWidth - ruleClearance,
229
- width: node.rect.width, height: reserve + ZONE_GEOMETRY.borderWidth + ruleClearance });
296
+ blockers.push({ x: node.rect.x, y: node.rect.y + node.rect.height - reserve - zoneGeo.borderWidth - ruleClearance,
297
+ width: node.rect.width, height: reserve + zoneGeo.borderWidth + ruleClearance });
230
298
  // The footer line as `layoutZone` seats it: one line box pinned above
231
299
  // the bottom border, from the content inset, as wide as its measured
232
300
  // text (the whole inner width when the result carries no measurement).
233
301
  const inner = Math.max(0, node.rect.width - 2 * zoneInset);
234
- const lineHeight = lineBoxHeight(ZONE_GEOMETRY.footer.size);
235
- const bottom = node.rect.y + node.rect.height - ZONE_GEOMETRY.borderWidth - ZONE_GEOMETRY.footerBottomInset;
302
+ const lineHeight = lineBoxHeight(zoneGeo.footer.size);
303
+ const bottom = node.rect.y + node.rect.height - zoneGeo.borderWidth - zoneGeo.footerBottomInset;
236
304
  const pad = paintClearance + CONNECTOR_CUTOUT_SLACK;
237
305
  connectorCutouts.push({
238
306
  x: node.rect.x + zoneInset - pad,
@@ -369,12 +437,32 @@ export function resolveScene(result, input) {
369
437
  orientations: result.orientations ?? {},
370
438
  };
371
439
  }
372
- /** Full presentation text retained alongside the textual relations (A14). */
373
- export function sceneTextRows(scene, document) {
440
+ /** Default labels for `DiagramSceneFigure`, including the DE-1b containment fallback label. */
441
+ export const DEFAULT_SCENE_LABELS = Object.freeze({
442
+ ...DEFAULT_FLOW_STRINGS,
443
+ controls: "Zoom",
444
+ zoomIn: "Zoom in",
445
+ zoomOut: "Zoom out",
446
+ fit: "Fit",
447
+ zoomLevel: (percent) => `Zoom ${percent} %`,
448
+ viewport: "Diagram",
449
+ expand: (title) => `Expand ${title}`,
450
+ collapse: (title) => `Collapse ${title}`,
451
+ contains: "includes",
452
+ });
453
+ function isContainmentRelation(document, relation) {
454
+ const baseType = document.typeDefinitions?.[relation.type]?.baseType ?? relation.type;
455
+ return baseType === "contains";
456
+ }
457
+ /** Full presentation text retained alongside the textual relations (A14, DE-1b). */
458
+ export function sceneTextRows(scene, document, labels) {
459
+ const containsLabel = labels?.contains ?? DEFAULT_SCENE_LABELS.contains;
374
460
  const rows = scene.nodes.map(node => Object.values(node.presentation?.text ?? {}).filter(Boolean).join(" · "));
375
461
  for (const relation of Object.values(document.relations)) {
376
462
  const names = relation.endpoints.map(end => { const value = document.entities[end.target]?.attributes["name"]; return value?.kind === "text" ? String(value.value) : end.target; });
377
- rows.push(names.join(" → ") + " · " + (edgeLabelOf(document, relation.id) ?? relation.type));
463
+ const explicit = edgeLabelOf(document, relation.id);
464
+ const fallback = isContainmentRelation(document, relation) ? containsLabel : relation.type;
465
+ rows.push(names.join(" → ") + " · " + (explicit ?? fallback));
378
466
  }
379
467
  return rows;
380
468
  }