@sentropic/diagram-canvas 0.2.5 → 0.3.1

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,47 @@ 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
+ /** Preserves v1's −2 px body-vs-header offset (`10 − 12 = −2`, matching `14 − 16`). */
72
+ bodyInsetFromBar: 10,
73
+ foldedHeaderTextWidth: 210,
74
+ /** Title on one line first (addendum 8); v1 keeps two lines. */
75
+ allocatedLines: { kicker: 1, title: 1, body: 2, footer: 1 },
76
+ };
77
+ /** Select the card geometry for a pinned anatomy (default `"v1"`). */
78
+ export function anatomyCardGeometry(anatomy) {
79
+ return anatomy === "v2" ? CARD_GEOMETRY_V2 : CARD_GEOMETRY;
80
+ }
81
+ /**
82
+ * Effective header/footer alignment for a card or zone:
83
+ * - Absent `align` is always `"left"` (compact `v2` never centres implicitly).
84
+ * - Explicit `"v1"` anatomy (including `fallback-v1`) keeps the frozen 0.41.5
85
+ * alignment (`"left"`); view-driven centring applies only when a view
86
+ * explicitly asks `align: "center"` on compact `v2`.
87
+ * - Direct unpinned calls (`anatomy === undefined`) preserve 0.41.5's
88
+ * `props.align ?? "left"` behaviour.
89
+ */
90
+ export function resolveDiagramAlign(anatomy, align) {
91
+ if (anatomy === "v1")
92
+ return "left";
93
+ return align ?? "left";
94
+ }
79
95
  /**
80
96
  * Edge label typography (DC-2a, tokens `diagramScene.edgeLabelFontSize` /
81
97
  * `diagramScene.edgeLabelLineHeight`): 18 px on a 22 px line box. One line
@@ -143,6 +159,14 @@ export function projectCardProps(presentation, opts) {
143
159
  ...(presentation.categoryRef === undefined ? {} : { tone: presentation.categoryRef }),
144
160
  ...(presentation.proposed === undefined ? {} : { proposed: presentation.proposed }),
145
161
  ...(opts.toggle === undefined ? {} : { toggle: opts.toggle }),
162
+ ...(() => {
163
+ const anatomy = presentation.anatomy ?? opts.anatomy;
164
+ return anatomy === undefined ? {} : { anatomy };
165
+ })(),
166
+ ...(() => {
167
+ const align = presentation.align ?? opts.align;
168
+ return align === undefined ? {} : { align };
169
+ })(),
146
170
  },
147
171
  };
148
172
  }
@@ -538,14 +562,15 @@ export function headerSlotGeometry(opts) {
538
562
  const kickerHeight = lineBoxHeight(g.kicker.size);
539
563
  const titleHeight = lineBoxHeight(g.title.size);
540
564
  const contentHeight = opts.kickerLines * kickerHeight + opts.titleLines * titleHeight;
541
- const blockHeight = opts.hasIcon ? Math.max(g.iconSize, contentHeight) : contentHeight;
565
+ const iconSize = opts.iconSize ?? g.iconSize;
566
+ const blockHeight = opts.hasIcon ? Math.max(iconSize, contentHeight) : contentHeight;
542
567
  return {
543
568
  kickerHeight,
544
569
  titleHeight,
545
570
  contentHeight,
546
571
  blockHeight,
547
572
  textTopOffset: (blockHeight - contentHeight) / 2,
548
- iconTopOffset: opts.hasIcon ? (blockHeight - g.iconSize) / 2 : 0,
573
+ iconTopOffset: opts.hasIcon ? (blockHeight - iconSize) / 2 : 0,
549
574
  };
550
575
  }
551
576
  /** Fixed-slot truncation shared by cards and zones (owner A14). */
@@ -580,20 +605,14 @@ export function cardFullText(props) {
580
605
  export function zoneFullText(props) {
581
606
  return [props.kicker, props.title, props.subtitle, props.footer].filter(Boolean).join('\n');
582
607
  }
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) {
608
+ function layoutCardAt(props, measure, anatomy, align) {
589
609
  const icon = props.icon ?? "base";
590
610
  const suppressed = icon === "none";
591
611
  const missing = !suppressed && props.iconGlyph === undefined && getDiagramGlyph(icon) === undefined;
592
612
  props = { ...props, autoSize: props.autoSize ?? true, icon: missing ? "unknown" : icon,
593
613
  iconGlyph: suppressed ? { face: "" } : props.iconGlyph ?? getDiagramGlyph(icon) ?? getDiagramGlyph("unknown") };
594
- const g = CARD_GEOMETRY;
614
+ const g = anatomyCardGeometry(anatomy);
595
615
  const diagnostics = missing ? [{ code: "card-icon-missing", slot: "icon", entityId: props.entityId, neededPx: 1, allocatedPx: 0 }] : [];
596
- const align = props.align ?? "left";
597
616
  const bodyMode = props.bodyMode ?? "leaf";
598
617
  const contentTop = g.borderWidth + g.padding;
599
618
  const contentRight = g.width - g.borderWidth - g.padding;
@@ -639,6 +658,7 @@ export function layoutCard(props, measure) {
639
658
  hasIcon,
640
659
  kickerLines: kickerTexts.length,
641
660
  titleLines: titleTexts.length,
661
+ iconSize: g.iconSize,
642
662
  });
643
663
  const kickerHeight = headerGeo.kickerHeight;
644
664
  const titleHeight = headerGeo.titleHeight;
@@ -658,7 +678,7 @@ export function layoutCard(props, measure) {
658
678
  // (collapsed zone, §6.2.1) the body is the centred subtitle: wrapped at the
659
679
  // frozen 396 px measure (width − 2 × (collapsedInset + marginInline)).
660
680
  const subtitleMode = bodyMode === "subtitle";
661
- const subtitleMeasure = g.width - 2 * (ZONE_GEOMETRY.collapsedInset + ZONE_GEOMETRY.collapsedSubtitleMarginInline);
681
+ const subtitleMeasure = g.width - 2 * (anatomyZoneGeometry(anatomy).collapsedInset + anatomyZoneGeometry(anatomy).collapsedSubtitleMarginInline);
662
682
  const bodyTextX = subtitleMode ? (g.width - subtitleMeasure) / 2 : g.bodyInsetFromBar;
663
683
  const bodyWidth = subtitleMode ? subtitleMeasure : contentRight - bodyTextX;
664
684
  // The body block is centred horizontally inside its box on every card
@@ -776,6 +796,46 @@ export function layoutCard(props, measure) {
776
796
  diagnostics,
777
797
  };
778
798
  }
799
+ /**
800
+ * Lay out fixed card slots with measured ellipses and a pinned footer.
801
+ * Informational diagnostics retain the original text and hidden length.
802
+ * Missing glyphs use the visible unknown icon (owner A2/A11).
803
+ * Compact `v2` cards default to `"left"` alignment (centring only when
804
+ * `align: "center"` is explicitly requested on compact `v2`) and fall back
805
+ * per box to frozen `v1` (`460 × 200`, `"left"` header/footer alignment as in
806
+ * 0.41.5) on overflow instead of dropping slots.
807
+ */
808
+ export function layoutCard(props, measure) {
809
+ const align = resolveDiagramAlign(props.anatomy, props.align);
810
+ const primary = layoutCardAt(props, measure, props.anatomy, align);
811
+ if (props.anatomy !== "v2")
812
+ return primary;
813
+ const v2Overflows = primary.diagnostics.filter((diagnostic) => diagnostic.code === "card-overflow");
814
+ if (v2Overflows.length === 0)
815
+ return primary;
816
+ const fallback = layoutCardAt(props, measure, "v1", "left");
817
+ const stillOverflows = fallback.diagnostics.some((diagnostic) => diagnostic.code === "card-overflow");
818
+ const diagnostics = stillOverflows
819
+ ? [...fallback.diagnostics]
820
+ : [
821
+ ...fallback.diagnostics,
822
+ ...v2Overflows.map((diagnostic) => ({
823
+ code: "card-overflow",
824
+ slot: diagnostic.slot,
825
+ entityId: diagnostic.entityId,
826
+ neededPx: diagnostic.neededPx,
827
+ allocatedPx: diagnostic.allocatedPx,
828
+ ...(diagnostic.text === undefined ? {} : { text: diagnostic.text }),
829
+ severity: "info",
830
+ reason: "fallback-v1",
831
+ })),
832
+ ];
833
+ return {
834
+ ...fallback,
835
+ anatomyFallback: "v1",
836
+ diagnostics,
837
+ };
838
+ }
779
839
  /* ------------------------------------------------------------------ *
780
840
  * DC-2 static half — the wrapping card `DiagramZone` (spec §6). *
781
841
  * Same module, same rules: zero imports, one geometry source. *
@@ -834,6 +894,44 @@ export const ZONE_GEOMETRY = {
834
894
  collapsedSubtitleMarginInline: 16,
835
895
  allocatedLines: { kicker: 1, title: 2, subtitle: 2, footer: 1 },
836
896
  };
897
+ /**
898
+ * Compact zone geometry (`diagram-anatomy/v2`): the collapsed zone IS the
899
+ * compact card (`352 × 154`, collapsed subtitle measure `352 − 2 × 24 = 304`,
900
+ * preserving v1's ~86 % width ratio); expanded chrome follows the compact
901
+ * insets (header `12`, icon `52`, gap `4`). Unlisted leaves keep v1 values;
902
+ * type scale unchanged.
903
+ */
904
+ export const ZONE_GEOMETRY_V2 = {
905
+ ...ZONE_GEOMETRY,
906
+ headerInset: CARD_GEOMETRY_V2.headerInset,
907
+ iconSize: CARD_GEOMETRY_V2.iconSize,
908
+ iconTextGap: CARD_GEOMETRY_V2.iconTextGap,
909
+ /**
910
+ * Expanded header text inset for v2: `12 + 52 + 4 + 86 = 154` so the
911
+ * inline-end toggle reserve stays `86 px` (matching v1) instead of
912
+ * growing to `110 px`.
913
+ */
914
+ headerTextInset: 154,
915
+ collapsedWidth: CARD_GEOMETRY_V2.width,
916
+ collapsedHeight: CARD_GEOMETRY_V2.height,
917
+ collapsedInset: 12,
918
+ collapsedSubtitleMarginInline: 12,
919
+ allocatedLines: { kicker: 1, title: 1, subtitle: 2, footer: 1 },
920
+ };
921
+ /** Select the zone geometry for a pinned anatomy (default `"v1"`). */
922
+ export function anatomyZoneGeometry(anatomy) {
923
+ return anatomy === "v2" ? ZONE_GEOMETRY_V2 : ZONE_GEOMETRY;
924
+ }
925
+ /** Nesting depth of a zone: `0` is the top level. */
926
+ export function normalizeZoneDepth(depth) {
927
+ if (depth === undefined || !Number.isFinite(depth))
928
+ return 0;
929
+ return Math.max(0, Math.floor(depth));
930
+ }
931
+ /** Resolve the depth surface for a zone (default start parity `0`). */
932
+ export function zoneDepthSurface(depth, startParity = 0) {
933
+ return (normalizeZoneDepth(depth) + startParity) % 2 === 0 ? "surface1" : "surface2";
934
+ }
837
935
  /** Centred collapsed-subtitle measure (§6.2.1): 460 − 2 × (16 + 16). */
838
936
  export const COLLAPSED_SUBTITLE_MEASURE = ZONE_GEOMETRY.collapsedWidth -
839
937
  2 * (ZONE_GEOMETRY.collapsedInset + ZONE_GEOMETRY.collapsedSubtitleMarginInline);
@@ -848,6 +946,7 @@ export function zoneCollapsedCardProps(props) {
848
946
  return {
849
947
  ...(props.autoSize === undefined ? {} : { autoSize: props.autoSize }),
850
948
  ...(props.height === undefined ? {} : { height: props.height }),
949
+ ...(props.anatomy === undefined ? {} : { anatomy: props.anatomy }),
851
950
  entityId: props.entityId,
852
951
  ...(props.kicker === undefined ? {} : { kicker: props.kicker }),
853
952
  title: props.title,
@@ -861,6 +960,11 @@ export function zoneCollapsedCardProps(props) {
861
960
  ? {}
862
961
  : { toggle: { collapsed: true, label: props.toggleLabel } }),
863
962
  ...(props.align === undefined ? {} : { align: props.align }),
963
+ // A folded zone keeps its depth background (owner addendum 1); no pin
964
+ // means no surface key, so unthreaded cards render byte-identical.
965
+ ...((props.depth === undefined && props.depthParityStart === undefined
966
+ ? {}
967
+ : { surface: zoneDepthSurface(props.depth, props.depthParityStart) })),
864
968
  bodyMode: "subtitle",
865
969
  };
866
970
  }
@@ -893,10 +997,23 @@ export function layoutZone(props, measure, children = []) {
893
997
  const missing = !suppressed && props.iconGlyph === undefined && getDiagramGlyph(icon) === undefined;
894
998
  props = { ...props, autoSize: props.autoSize ?? true, icon: missing ? "unknown" : icon,
895
999
  iconGlyph: suppressed ? { face: "" } : props.iconGlyph ?? getDiagramGlyph(icon) ?? getDiagramGlyph("unknown") };
896
- const g = { ...ZONE_GEOMETRY, ...(props.containerPadding === undefined ? {} : { contentInsetTop: props.containerPadding, contentInsetBottom: props.containerPadding, contentInsetInline: props.containerPadding }) };
1000
+ const g = { ...anatomyZoneGeometry(props.anatomy), ...(props.containerPadding === undefined ? {} : { contentInsetTop: props.containerPadding, contentInsetBottom: props.containerPadding, contentInsetInline: props.containerPadding }) };
897
1001
  const x = props.x ?? 0;
898
1002
  const y = props.y ?? 0;
899
1003
  const diagnostics = missing ? [{ code: "card-icon-missing", slot: "icon", entityId: props.entityId, neededPx: 1, allocatedPx: 0 }] : [];
1004
+ // Owner addendum 1: resolve the depth surface once; both states and the
1005
+ // folded card share it, so fold/unfold never repaints the layer. Without
1006
+ // depth pins the layout keeps its exact v1 shape (anatomy golden).
1007
+ const hasDepthPins = props.depth !== undefined || props.depthParityStart !== undefined;
1008
+ const depth = normalizeZoneDepth(props.depth);
1009
+ const surface = zoneDepthSurface(props.depth, props.depthParityStart);
1010
+ // Informational and opt-in: a leaf card (default card surface) on a
1011
+ // same-colour zone surface. Only explicit children compositions report
1012
+ // it — hosts lay children out flat, so host rendering never changes.
1013
+ if (props.reportSurfaceSame === true && surface === "surface1"
1014
+ && children.some((child) => child.kind === "card" && child.zone === undefined && child.card?.tone === undefined)) {
1015
+ diagnostics.push({ code: "zone-surface-same", slot: "surface", entityId: props.entityId, neededPx: 1, allocatedPx: 0 });
1016
+ }
900
1017
  if (missing) {
901
1018
  diagnostics.push({
902
1019
  code: "zone-icon-unknown",
@@ -916,13 +1033,16 @@ export function layoutZone(props, measure, children = []) {
916
1033
  neededPx: diagnostic.neededPx,
917
1034
  allocatedPx: diagnostic.allocatedPx,
918
1035
  ...(diagnostic.text === undefined ? {} : { text: diagnostic.text }),
919
- ...(diagnostic.hiddenLength === undefined ? {} : { hiddenLength: diagnostic.hiddenLength, severity: diagnostic.severity, reason: diagnostic.reason }),
1036
+ ...(diagnostic.severity === undefined ? {} : { severity: diagnostic.severity }),
1037
+ ...(diagnostic.reason === undefined ? {} : { reason: diagnostic.reason }),
1038
+ ...(diagnostic.hiddenLength === undefined ? {} : { hiddenLength: diagnostic.hiddenLength }),
920
1039
  });
921
1040
  }
922
1041
  return {
923
1042
  icon: { name: props.icon, glyph: props.iconGlyph },
924
- box: { x, y, width: g.collapsedWidth, height: card.box.height },
1043
+ box: { x, y, width: card.box.width, height: card.box.height },
925
1044
  collapsed: true,
1045
+ ...(hasDepthPins ? { surface, depth } : {}),
926
1046
  card,
927
1047
  diagnostics,
928
1048
  };
@@ -941,7 +1061,7 @@ export function layoutZone(props, measure, children = []) {
941
1061
  ? g.headerInset
942
1062
  : g.headerTextInset - (g.headerInset + g.iconSize + g.iconTextGap);
943
1063
  const headerTextWidth = Math.max(0, x + width - headerTextX - rightHeaderReserve);
944
- const align = props.align ?? "left";
1064
+ const align = resolveDiagramAlign(props.anatomy, props.align);
945
1065
  const headerAnchor = align === "center" ? "middle" : "start";
946
1066
  const headerLineX = align === "center" ? headerTextX + headerTextWidth / 2 : headerTextX;
947
1067
  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 }));
@@ -958,6 +1078,7 @@ export function layoutZone(props, measure, children = []) {
958
1078
  hasIcon,
959
1079
  kickerLines: kickerTexts.length,
960
1080
  titleLines: titleTexts.length,
1081
+ iconSize: g.iconSize,
961
1082
  });
962
1083
  const kickerHeight = headerGeo.kickerHeight;
963
1084
  const titleHeight = headerGeo.titleHeight;
@@ -1081,6 +1202,7 @@ export function layoutZone(props, measure, children = []) {
1081
1202
  icon: { name: props.icon, glyph: props.iconGlyph },
1082
1203
  box: { x, y, width, height },
1083
1204
  collapsed: false,
1205
+ ...(hasDepthPins ? { surface, depth } : {}),
1084
1206
  header: {
1085
1207
  ...(iconBox === undefined ? {} : { iconBox }),
1086
1208
  headerTextX,
@@ -1139,9 +1261,24 @@ export function projectZoneProps(presentation, opts) {
1139
1261
  })()),
1140
1262
  ...(presentation.categoryRef === undefined ? {} : { tone: presentation.categoryRef }),
1141
1263
  ...(presentation.proposed === undefined ? {} : { proposed: presentation.proposed }),
1264
+ ...(() => {
1265
+ const anatomy = presentation.anatomy ?? opts.anatomy;
1266
+ return anatomy === undefined ? {} : { anatomy };
1267
+ })(),
1142
1268
  collapsed: opts.collapsed,
1143
1269
  ...(opts.toggleLabel === undefined ? {} : { toggleLabel: opts.toggleLabel }),
1144
- ...(opts.align === undefined ? {} : { align: opts.align }),
1270
+ ...(() => {
1271
+ const align = presentation.align ?? opts.align;
1272
+ return align === undefined ? {} : { align };
1273
+ })(),
1274
+ ...(() => {
1275
+ const depth = presentation.depth ?? opts.depth;
1276
+ return depth === undefined ? {} : { depth };
1277
+ })(),
1278
+ ...(() => {
1279
+ const start = presentation.depthParityStart ?? opts.depthParityStart;
1280
+ return start === undefined ? {} : { depthParityStart: start };
1281
+ })(),
1145
1282
  ...(opts.x === undefined ? {} : { x: opts.x }),
1146
1283
  ...(opts.y === undefined ? {} : { y: opts.y }),
1147
1284
  ...(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,13 @@ 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
+ readonly contains: string;
255
+ };
256
+ /** Full presentation text retained alongside the textual relations (A14, DE-1b). */
257
+ export declare function sceneTextRows(scene: SceneModel, document: SceneDocument, labels?: Partial<Pick<DiagramSceneFigureLabels, "contains">>): readonly string[];
243
258
  export interface SceneCameraInput {
244
259
  readonly bounds?: Rect;
245
260
  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,100 @@ 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) => {
52
+ const resolved = entry.anatomy === undefined && viewAnatomy !== undefined ? { ...entry, anatomy: viewAnatomy } : entry;
53
+ // View-level centring applies only when explicitly requested on compact v2 anatomy.
54
+ if (resolved.anatomy !== "v2" && resolved.align === "center") {
55
+ const { align: _ignored, ...rest } = resolved;
56
+ return rest;
57
+ }
58
+ return resolved;
59
+ };
44
60
  const entities = Object.fromEntries(Object.entries(presentation.entities).map(([id, entry]) => {
45
61
  if (entry.form !== "card" && entry.form !== "container" && entry.form !== "legend")
46
- return [id, entry];
62
+ return [id, withViewAnatomy(entry)];
47
63
  const entityId = view?.entityOccurrences[id]?.entity ?? id.replace(/^occurrence:e\./, "entity:");
48
64
  const entity = document.entities[entityId];
49
65
  if (entity?.profile === "erd@1")
50
- return [id, entry];
66
+ return [id, withViewAnatomy(entry)];
51
67
  const binding = bindings[entity === undefined ? "" : entity.profile + ":" + entity.type] ?? bindings[entity?.type ?? ""];
52
68
  if (binding?.shape !== undefined && binding.shape !== "component")
53
- return [id, { ...entry, icon: entry.icon ?? "none" }];
69
+ return [id, withViewAnatomy({ ...entry, icon: entry.icon ?? "none" })];
54
70
  const role = binding?.role ?? (entry.form === "card" ? "card" : "zone");
55
71
  const icon = entry.icon ?? binding?.icon ?? ROLE_ICONS[role];
72
+ if (icon === "none")
73
+ return [id, withViewAnatomy({ ...entry, icon: "none" })];
56
74
  if (icon === undefined || resolveGlyph(icon) === undefined) {
57
75
  missing.push(id);
58
- return [id, { ...entry, icon: strict ? "unknown" : "none" }];
76
+ return [id, withViewAnatomy({ ...entry, icon: strict ? "unknown" : "none" })];
59
77
  }
60
- return [id, { ...entry, icon }];
78
+ return [id, withViewAnatomy({ ...entry, icon })];
79
+ }));
80
+ /**
81
+ * Owner addendum 1 — stamp nesting depth from the view groups (or from
82
+ * semantic `contains` relations when no view is supplied) onto zone
83
+ * entries (top level `0`), so frames alternate without page code. Entries
84
+ * pinning their own depth keep it; card entries are untouched (their
85
+ * semantic tints never change). The selectable `startParity` rides along
86
+ * the same way when the scene selects it.
87
+ */
88
+ const startParity = options.depthParityStart ?? 0;
89
+ const hasViewGroups = view !== undefined && Object.keys(view.groups).length > 0;
90
+ const semanticParentOf = new Map();
91
+ if (!hasViewGroups && document.relations !== undefined) {
92
+ for (const relation of Object.values(document.relations)) {
93
+ const baseType = document.typeDefinitions?.[relation.type]?.baseType ?? relation.type;
94
+ if (baseType !== "contains")
95
+ continue;
96
+ const parent = relation.endpoints.find((endpoint) => endpoint.role === "parent")?.target;
97
+ const child = relation.endpoints.find((endpoint) => endpoint.role === "child")?.target;
98
+ if (parent !== undefined && child !== undefined)
99
+ semanticParentOf.set(child, parent);
100
+ }
101
+ }
102
+ const depthOf = (id) => {
103
+ let depth = 0;
104
+ const seen = new Set();
105
+ if (hasViewGroups) {
106
+ for (let parent = parentOccurrenceOf(view, id); parent !== undefined && !seen.has(parent); parent = parentOccurrenceOf(view, parent)) {
107
+ seen.add(parent);
108
+ depth += 1;
109
+ }
110
+ return depth;
111
+ }
112
+ const entityId = view?.entityOccurrences[id]?.entity ?? id.replace(/^occurrence:e\./, "entity:");
113
+ for (let parent = semanticParentOf.get(entityId); parent !== undefined && !seen.has(parent); parent = semanticParentOf.get(parent)) {
114
+ seen.add(parent);
115
+ depth += 1;
116
+ }
117
+ return depth;
118
+ };
119
+ const stamped = Object.fromEntries(Object.entries(entities).map(([id, entry]) => {
120
+ const zone = entry;
121
+ if (zone.form !== "container" && zone.form !== "legend")
122
+ return [id, entry];
123
+ // Lean stamps: the top level and the default parity need no key
124
+ // (absent means `0` / `0` everywhere downstream). Explicit depth pins are
125
+ // preserved while still inheriting a non-default scene `depthParityStart`.
126
+ const depth = zone.depth === undefined ? depthOf(id) : undefined;
127
+ const needsParity = zone.depthParityStart === undefined && startParity !== 0;
128
+ if ((depth === undefined || depth === 0) && !needsParity)
129
+ return [id, entry];
130
+ return [id, {
131
+ ...entry,
132
+ ...(depth === undefined || depth === 0 ? {} : { depth }),
133
+ ...(needsParity ? { depthParityStart: startParity } : {}),
134
+ }];
61
135
  }));
62
- return { presentation: { ...presentation, entities }, missing };
136
+ return { presentation: { ...presentation, entities: stamped }, missing };
63
137
  }
64
138
  /**
65
139
  * One full layout pass (§6.5: fold → measure → place → route, never patched).
@@ -69,7 +143,7 @@ export function resolveScenePresentation(document, presentation, bindings = {},
69
143
  * required field carries no second metric source.
70
144
  */
71
145
  export function layoutScene(input) {
72
- const resolved = resolveScenePresentation(input.document, input.presentation, input.iconBindings, input.strictIcons, input.view, input.resolveGlyph);
146
+ const resolved = resolveScenePresentation(input.document, input.presentation, input.iconBindings, input.strictIcons, input.view, input.resolveGlyph, input.depthParityStart === undefined ? {} : { depthParityStart: input.depthParityStart });
73
147
  const options = {
74
148
  registry: input.registry,
75
149
  ...(input.flows === undefined ? {} : { flows: input.flows }),
@@ -93,6 +167,7 @@ export function layoutScene(input) {
93
167
  rowPack: input.rowPack ?? {},
94
168
  targetWidth: input.targetWidth ?? DEFAULT_SCENE_TARGET_WIDTH,
95
169
  ...(input.previousOrientation === undefined ? {} : { previousOrientation: input.previousOrientation }),
170
+ ...(input.reportSurfaceSame === undefined ? {} : { reportSurfaceSame: input.reportSurfaceSame }),
96
171
  };
97
172
  const result = input.cache !== undefined
98
173
  ? (input.view === undefined
@@ -164,7 +239,7 @@ function edgeLabelOf(document, relation) {
164
239
  */
165
240
  export function resolveScene(result, input) {
166
241
  const view = result.view;
167
- const resolved = resolveScenePresentation(input.document, input.presentation, input.iconBindings, input.strictIcons, input.view, input.resolveGlyph);
242
+ const resolved = resolveScenePresentation(input.document, input.presentation, input.iconBindings, input.strictIcons, view, input.resolveGlyph, input.depthParityStart === undefined ? {} : { depthParityStart: input.depthParityStart });
168
243
  const frame = buildScene({ document: input.document, views: { [view.viewId]: view } }, view.viewId);
169
244
  const bundledMembers = new Set(Object.values(result.edgeBundles ?? {}).flatMap(bundle => bundle.members.slice(1)));
170
245
  const items = frame.items.filter(item => item.kind !== "edge" || !bundledMembers.has(item.occurrence));
@@ -213,26 +288,27 @@ export function resolveScene(result, input) {
213
288
  const height = headerHeights.get(node.occurrence);
214
289
  if (height === undefined)
215
290
  continue;
216
- const ruleClearance = (ZONE_GEOMETRY.ruleHeight / 2 + 1) / DEFAULT_MIN_READABLE_SCALE;
291
+ const zoneGeo = anatomyZoneGeometry(node.presentation?.anatomy);
292
+ const ruleClearance = (zoneGeo.ruleHeight / 2 + 1) / DEFAULT_MIN_READABLE_SCALE;
217
293
  blockers.push({
218
294
  x: node.rect.x,
219
295
  y: node.rect.y,
220
296
  width: node.rect.width,
221
- height: CONTENT_INSET + height + ZONE_GEOMETRY.ruleHeight / 2 + ruleClearance,
297
+ height: zoneGeo.headerInset + height + zoneGeo.ruleHeight / 2 + ruleClearance,
222
298
  });
223
299
  // A zone footer has one allocated line. Reserve its fixed chrome from
224
300
  // the presentation instead of measuring the scene again during replay.
225
301
  const reserve = node.presentation?.text.footer?.trim()
226
- ? lineBoxHeight(ZONE_GEOMETRY.footer.size) + ZONE_GEOMETRY.ruleHeight + 2 * ZONE_GEOMETRY.ruleMargin + ZONE_GEOMETRY.footerBottomInset : 0;
302
+ ? lineBoxHeight(zoneGeo.footer.size) + zoneGeo.ruleHeight + 2 * zoneGeo.ruleMargin + zoneGeo.footerBottomInset : 0;
227
303
  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 });
304
+ blockers.push({ x: node.rect.x, y: node.rect.y + node.rect.height - reserve - zoneGeo.borderWidth - ruleClearance,
305
+ width: node.rect.width, height: reserve + zoneGeo.borderWidth + ruleClearance });
230
306
  // The footer line as `layoutZone` seats it: one line box pinned above
231
307
  // the bottom border, from the content inset, as wide as its measured
232
308
  // text (the whole inner width when the result carries no measurement).
233
309
  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;
310
+ const lineHeight = lineBoxHeight(zoneGeo.footer.size);
311
+ const bottom = node.rect.y + node.rect.height - zoneGeo.borderWidth - zoneGeo.footerBottomInset;
236
312
  const pad = paintClearance + CONNECTOR_CUTOUT_SLACK;
237
313
  connectorCutouts.push({
238
314
  x: node.rect.x + zoneInset - pad,
@@ -369,12 +445,30 @@ export function resolveScene(result, input) {
369
445
  orientations: result.orientations ?? {},
370
446
  };
371
447
  }
372
- /** Full presentation text retained alongside the textual relations (A14). */
373
- export function sceneTextRows(scene, document) {
448
+ /** Default labels for `DiagramSceneFigure`, including the DE-1b containment fallback label. */
449
+ export const DEFAULT_SCENE_LABELS = Object.freeze({
450
+ ...DEFAULT_FLOW_STRINGS,
451
+ controls: "Zoom",
452
+ zoomIn: "Zoom in",
453
+ zoomOut: "Zoom out",
454
+ fit: "Fit",
455
+ zoomLevel: (percent) => `Zoom ${percent} %`,
456
+ viewport: "Diagram",
457
+ expand: (title) => `Expand ${title}`,
458
+ collapse: (title) => `Collapse ${title}`,
459
+ contains: "includes",
460
+ });
461
+ /** Full presentation text retained alongside the textual relations (A14, DE-1b). */
462
+ export function sceneTextRows(scene, document, labels) {
463
+ const containsLabel = labels?.contains ?? DEFAULT_SCENE_LABELS.contains;
374
464
  const rows = scene.nodes.map(node => Object.values(node.presentation?.text ?? {}).filter(Boolean).join(" · "));
375
465
  for (const relation of Object.values(document.relations)) {
376
466
  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));
467
+ const explicit = edgeLabelOf(document, relation.id);
468
+ // W1-28: only replace the literal "contains" relation type so refined
469
+ // containment subtypes (e.g. "owns" with baseType "contains") keep their name.
470
+ const fallback = relation.type === "contains" ? containsLabel : relation.type;
471
+ rows.push(names.join(" → ") + " · " + (explicit ?? fallback));
378
472
  }
379
473
  return rows;
380
474
  }