@sentropic/diagram-canvas 0.3.1 → 0.4.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.
Files changed (53) hide show
  1. package/README.md +23 -2
  2. package/dist/camera.d.ts +28 -9
  3. package/dist/camera.js +34 -13
  4. package/dist/index.d.ts +4 -0
  5. package/dist/index.js +4 -0
  6. package/dist/layout/cache.js +12 -2
  7. package/dist/layout/channels.d.ts +10 -0
  8. package/dist/layout/channels.js +13 -0
  9. package/dist/layout/conventions.d.ts +117 -0
  10. package/dist/layout/conventions.js +185 -0
  11. package/dist/layout/dock.d.ts +2 -0
  12. package/dist/layout/dock.js +5 -1
  13. package/dist/layout/fingerprint.d.ts +4 -2
  14. package/dist/layout/fingerprint.js +26 -2
  15. package/dist/layout/hints.d.ts +1 -1
  16. package/dist/layout/hints.js +10 -3
  17. package/dist/layout/index.d.ts +5 -3
  18. package/dist/layout/index.js +5 -3
  19. package/dist/layout/labels.d.ts +2 -0
  20. package/dist/layout/labels.js +2 -0
  21. package/dist/layout/measure.d.ts +6 -0
  22. package/dist/layout/measure.js +28 -0
  23. package/dist/layout/measured.js +1051 -100
  24. package/dist/layout/route.d.ts +27 -1
  25. package/dist/layout/route.js +640 -32
  26. package/dist/layout/routeSpacing.d.ts +84 -0
  27. package/dist/layout/routeSpacing.js +472 -0
  28. package/dist/layout/spacing.generated.d.ts +10 -1
  29. package/dist/layout/spacing.generated.js +10 -1
  30. package/dist/layout/types.d.ts +33 -2
  31. package/dist/layout/types.js +2 -0
  32. package/dist/presentation/connectorPath.d.ts +32 -0
  33. package/dist/presentation/connectorPath.js +213 -0
  34. package/dist/presentation/connectorStyle.d.ts +70 -0
  35. package/dist/presentation/connectorStyle.js +99 -0
  36. package/dist/presentation/diagramCardModel.d.ts +1 -1
  37. package/dist/presentation/diagramCardModel.js +1 -1
  38. package/dist/presentation/diagramSceneModel.d.ts +58 -7
  39. package/dist/presentation/diagramSceneModel.js +225 -35
  40. package/dist/presentation/diagramSceneTypes.d.ts +9 -0
  41. package/dist/presentation/index.d.ts +4 -0
  42. package/dist/presentation/index.js +4 -0
  43. package/dist/presentation/linkLegend.d.ts +132 -0
  44. package/dist/presentation/linkLegend.js +231 -0
  45. package/dist/presentation/renderSceneSvg.d.ts +3 -1
  46. package/dist/presentation/renderSceneSvg.js +81 -11
  47. package/dist/presentation/sceneLabelClearance.d.ts +1 -1
  48. package/dist/presentation/sceneLabelClearance.js +19 -3
  49. package/dist/r7Mode.d.ts +13 -0
  50. package/dist/r7Mode.js +67 -0
  51. package/dist/visibility.d.ts +1 -1
  52. package/dist/visibility.js +3 -2
  53. package/package.json +2 -2
package/README.md CHANGED
@@ -346,8 +346,8 @@ empty penalty, hysteresis); absent or empty, the DS defaults apply.
346
346
  `cameraFit` frames the scene bounds on both axes against the 16:9 fit box
347
347
  (`fitW = viewW`, `fitH = min(viewW × 9/16, 0.85 × windowH)`), never above the
348
348
  maximum display scale (0.62: readout 100 %, a card renders at about
349
- 285 × 124 CSS px) and holds a fit at the readability floor (0.45: an 18 px
350
- edge label renders at 8.1 CSS px) when the drawing is larger, reporting
349
+ 285 × 124 CSS px) and holds a fit at the readability floor (0.30: an 18 px
350
+ edge label renders at 5.4 CSS px) when the drawing is larger, reporting
351
351
  `pans`; `clampZoom` and `zoomReadout` complete it. Given a `zoomQuantum`, the
352
352
  applied fit is floored to that grid, never rounded up past the fit box;
353
353
  `sceneFit` passes `FIT_QUANTUM` (1e-3), and a scene host prints that one zoom
@@ -437,3 +437,24 @@ flow tokens, bundles, arrows, badges and internal targets. The pure
437
437
  static `flowMarksSvg`; selection/filter changes require no layout. Shared host
438
438
  acceptance cases are imported directly from unpublished `test-support` source. See
439
439
  [the contract, Vue handoff and limitations](../../docs/DC2C_NUMBERED_FLOWS.md).
440
+
441
+ ## Diagram conventions and opt-in lints (DE-2)
442
+
443
+ - **Arrow direction (`source` = initiator of the action):** on every directed
444
+ relation (`arrowhead !== "none"`), the `source` endpoint denotes the
445
+ initiator of the action and the `target` endpoint denotes the receiver.
446
+ Because initiation cannot be inferred from graph topology alone, the
447
+ `arrow-direction-convention` diagnostic is **opt-in**
448
+ (`conventions: { arrowDirection: true }`) and evaluates only edges that
449
+ declare initiator metadata via the semantic relation's `attributes.initiator`
450
+ text attribute or via `conventions.initiators`.
451
+ - **No opaque acronyms as zone tags:** a zone tag (`kicker`) should carry a
452
+ descriptive label alongside any acronym (for example
453
+ `"IAM — Identity & Access Management"` or `"VPC · Réseau privé"`), never a
454
+ bare unexplained acronym. The `zone-tag-opaque-acronym` diagnostic is
455
+ **opt-in and non-blocking** (`conventions: { zoneTagAcronyms: true }`) and
456
+ defaults to an allowlist (`DEFAULT_ZONE_TAG_ACRONYM_ALLOWLIST`) covering the
457
+ existing product kickers of `DLR-315` (`H2A`, `SENTROPIC`, `ENGRAM`,
458
+ `DESIGN SYSTEM`, `SENTROPIC & 3RD PARTIES`, `SENTROPIC & TIERS`). Both lints
459
+ are also callable directly via `lintArrowDirection`, `lintZoneTagAcronyms`,
460
+ and `lintDiagramConventions`.
package/dist/camera.d.ts CHANGED
@@ -12,19 +12,29 @@
12
12
  export declare const DEFAULT_MAX_DISPLAY_SCALE = 0.62;
13
13
  /**
14
14
  * Hard display floor: fit scales down to it, then the viewport scrolls.
15
- * 0.45 is the smallest two-decimal scale holding both the 18 px edge
16
- * label (BF-2, the binding constraint: 18 × 0.45 = 8.1 CSS px ≥ 8 CSS px
17
- * floor; 0.42 gives 7.56) and the 22 px kicker (22 × 0.45 = 9.9 CSS px).
15
+ * R7 owner decision (21/11): default to fitting the whole figure down to 30 %.
18
16
  */
19
- export declare const DEFAULT_MIN_READABLE_SCALE = 0.45;
20
- /** World font size of an edge label, px (token `diagramScene.edgeLabelFontSize`). */
17
+ export declare const DEFAULT_MIN_READABLE_SCALE = 0.3;
18
+ /** World font size of an edge label, px (token `diagramScene.edgeLabelSize` / `edgeLabelFontSize`). */
19
+ export declare const DEFAULT_EDGE_LABEL_SIZE = 18;
20
+ /** Alias of `DEFAULT_EDGE_LABEL_SIZE` (token `diagramScene.edgeLabelFontSize`). */
21
21
  export declare const DEFAULT_EDGE_LABEL_FONT_SIZE = 18;
22
22
  /** World line box of an edge label, px (token `diagramScene.edgeLabelLineHeight`). */
23
23
  export declare const DEFAULT_EDGE_LABEL_LINE_HEIGHT = 22;
24
- /** Minimum rendered edge-label size, CSS px. */
24
+ /** Dedicated resting connector stroke width, CSS px (token `diagramScene.linkStrokeWidth`, DE-2). */
25
+ export declare const DEFAULT_LINK_STROKE_WIDTH = 2.5;
26
+ /** Related flow connector stroke width, CSS px (token `diagramScene.linkRelatedStrokeWidth`, DE-2). */
27
+ export declare const DEFAULT_LINK_RELATED_STROKE_WIDTH = 3;
28
+ /** Primary flow connector stroke width, CSS px (token `diagramScene.linkPrimaryStrokeWidth`, DE-2). */
29
+ export declare const DEFAULT_LINK_PRIMARY_STROKE_WIDTH = 3.5;
30
+ /** Emphasized connector stroke width, CSS px (token `diagramScene.linkEmphasisStrokeWidth`, DE-2 / G6). */
31
+ export declare const DEFAULT_LINK_EMPHASIS_STROKE_WIDTH = 3.5;
32
+ /** Original DC-2a edge-label readability reference, CSS px. */
25
33
  export declare const MIN_EDGE_LABEL_CSS_PX = 8;
26
34
  /** Share of the window height a figure may take (§5.1 fit box). */
27
35
  export declare const FIT_WINDOW_HEIGHT_SHARE = 0.85;
36
+ /** Vertical viewport margin used by opt-in fit-to-window host framing (`calc(100vh - 24px)`, DE-2 ask 9). */
37
+ export declare const FIT_WINDOW_MARGIN_PX = 24;
28
38
  /** Fit box aspect (§5.1): 16:9. */
29
39
  export declare const FIT_ASPECT: number;
30
40
  export interface CameraFitInput {
@@ -40,7 +50,7 @@ export interface CameraFitInput {
40
50
  /** Measured horizontal scrollbar thickness (`offsetHeight - clientHeight`), CSS px. */
41
51
  readonly scrollbarHeight?: number;
42
52
  readonly maxDisplayScale?: number;
43
- /** Optional higher readability floor; never lowers the absolute 0.45 floor. */
53
+ /** Optional higher readability floor; never lowers the absolute 0.30 floor. */
44
54
  readonly minReadableScale?: number;
45
55
  /**
46
56
  * Grid the applied fit zoom lands on, scale units. The fit is floored to
@@ -49,6 +59,12 @@ export interface CameraFitInput {
49
59
  * stay exact. Absent: the applied zoom is the exact fit.
50
60
  */
51
61
  readonly zoomQuantum?: number;
62
+ /**
63
+ * Opt-in host fit-to-window mode (DE-2 ask 9): frames against
64
+ * `max-height: calc(100vh - 24px)` and `max-width: 100%`, centred.
65
+ * Defaults to `false`, preserving the §5.1 / Z-3 / AC-23 fit box.
66
+ */
67
+ readonly fitToWindow?: boolean;
52
68
  }
53
69
  export interface CameraFit {
54
70
  /** The usable §5.1 fit box, excluding scrollbars, CSS px. */
@@ -69,8 +85,11 @@ export declare const FIT_PAINT_INSET = 1;
69
85
  /** Largest multiple of `quantum` that is not above `value`. A quantum that
70
86
  * is not a finite positive number defines no grid: the value is returned. */
71
87
  export declare function floorToQuantum(value: number, quantum: number): number;
72
- /** §5.1: `fitW = viewW`, `fitH = min(viewW × 9/16, 0.85 × windowH)`. */
73
- export declare function fitBox(viewWidth: number, windowHeight: number): {
88
+ /**
89
+ * §5.1 default fit box: `fitW = viewW`, `fitH = min(viewW × 9/16, 0.85 × windowH)`.
90
+ * When `fitToWindow` is `true` (DE-2 ask 9), uses `windowH - 24` (`calc(100vh - 24px)`).
91
+ */
92
+ export declare function fitBox(viewWidth: number, windowHeight: number, fitToWindow?: boolean): {
74
93
  readonly width: number;
75
94
  readonly height: number;
76
95
  };
package/dist/camera.js CHANGED
@@ -12,19 +12,29 @@
12
12
  export const DEFAULT_MAX_DISPLAY_SCALE = 0.62;
13
13
  /**
14
14
  * Hard display floor: fit scales down to it, then the viewport scrolls.
15
- * 0.45 is the smallest two-decimal scale holding both the 18 px edge
16
- * label (BF-2, the binding constraint: 18 × 0.45 = 8.1 CSS px ≥ 8 CSS px
17
- * floor; 0.42 gives 7.56) and the 22 px kicker (22 × 0.45 = 9.9 CSS px).
15
+ * R7 owner decision (21/11): default to fitting the whole figure down to 30 %.
18
16
  */
19
- export const DEFAULT_MIN_READABLE_SCALE = 0.45;
20
- /** World font size of an edge label, px (token `diagramScene.edgeLabelFontSize`). */
21
- export const DEFAULT_EDGE_LABEL_FONT_SIZE = 18;
17
+ export const DEFAULT_MIN_READABLE_SCALE = 0.30;
18
+ /** World font size of an edge label, px (token `diagramScene.edgeLabelSize` / `edgeLabelFontSize`). */
19
+ export const DEFAULT_EDGE_LABEL_SIZE = 18;
20
+ /** Alias of `DEFAULT_EDGE_LABEL_SIZE` (token `diagramScene.edgeLabelFontSize`). */
21
+ export const DEFAULT_EDGE_LABEL_FONT_SIZE = DEFAULT_EDGE_LABEL_SIZE;
22
22
  /** World line box of an edge label, px (token `diagramScene.edgeLabelLineHeight`). */
23
23
  export const DEFAULT_EDGE_LABEL_LINE_HEIGHT = 22;
24
- /** Minimum rendered edge-label size, CSS px. */
24
+ /** Dedicated resting connector stroke width, CSS px (token `diagramScene.linkStrokeWidth`, DE-2). */
25
+ export const DEFAULT_LINK_STROKE_WIDTH = 2.5;
26
+ /** Related flow connector stroke width, CSS px (token `diagramScene.linkRelatedStrokeWidth`, DE-2). */
27
+ export const DEFAULT_LINK_RELATED_STROKE_WIDTH = 3;
28
+ /** Primary flow connector stroke width, CSS px (token `diagramScene.linkPrimaryStrokeWidth`, DE-2). */
29
+ export const DEFAULT_LINK_PRIMARY_STROKE_WIDTH = 3.5;
30
+ /** Emphasized connector stroke width, CSS px (token `diagramScene.linkEmphasisStrokeWidth`, DE-2 / G6). */
31
+ export const DEFAULT_LINK_EMPHASIS_STROKE_WIDTH = 3.5;
32
+ /** Original DC-2a edge-label readability reference, CSS px. */
25
33
  export const MIN_EDGE_LABEL_CSS_PX = 8;
26
34
  /** Share of the window height a figure may take (§5.1 fit box). */
27
35
  export const FIT_WINDOW_HEIGHT_SHARE = 0.85;
36
+ /** Vertical viewport margin used by opt-in fit-to-window host framing (`calc(100vh - 24px)`, DE-2 ask 9). */
37
+ export const FIT_WINDOW_MARGIN_PX = 24;
28
38
  /** Fit box aspect (§5.1): 16:9. */
29
39
  export const FIT_ASPECT = 16 / 9;
30
40
  /** Screen-space inset for non-scaling strokes and CSS layout rounding. */
@@ -45,14 +55,23 @@ export function floorToQuantum(value, quantum) {
45
55
  steps += 1;
46
56
  return steps / perUnit;
47
57
  }
48
- /** §5.1: `fitW = viewW`, `fitH = min(viewW × 9/16, 0.85 × windowH)`. */
49
- export function fitBox(viewWidth, windowHeight) {
58
+ /**
59
+ * §5.1 default fit box: `fitW = viewW`, `fitH = min(viewW × 9/16, 0.85 × windowH)`.
60
+ * When `fitToWindow` is `true` (DE-2 ask 9), uses `windowH - 24` (`calc(100vh - 24px)`).
61
+ */
62
+ export function fitBox(viewWidth, windowHeight, fitToWindow = false) {
63
+ if (fitToWindow) {
64
+ return {
65
+ width: viewWidth,
66
+ height: Number.isFinite(windowHeight) ? Math.max(0, windowHeight - FIT_WINDOW_MARGIN_PX) : viewWidth / FIT_ASPECT,
67
+ };
68
+ }
50
69
  return { width: viewWidth, height: Math.min(viewWidth / FIT_ASPECT, FIT_WINDOW_HEIGHT_SHARE * windowHeight) };
51
70
  }
52
71
  export function cameraFit(input) {
53
72
  const maxZoom = Math.max(DEFAULT_MIN_READABLE_SCALE, input.maxDisplayScale ?? DEFAULT_MAX_DISPLAY_SCALE);
54
73
  const readableFloor = Math.min(maxZoom, Math.max(DEFAULT_MIN_READABLE_SCALE, input.minReadableScale ?? DEFAULT_MIN_READABLE_SCALE));
55
- const frame = fitBox(input.viewWidth, input.windowHeight);
74
+ const frame = fitBox(input.viewWidth, input.windowHeight, input.fitToWindow ?? false);
56
75
  // Hosts add the scrollbar back to the outer height; fit and placement use
57
76
  // only the drawable area, keeping the combined height inside the fit box.
58
77
  const box = { width: frame.width, height: Math.max(0, frame.height - (input.scrollbarHeight ?? 0)) };
@@ -66,9 +85,11 @@ export function cameraFit(input) {
66
85
  // (transform, camera state, painted-bounds read) gets this single value,
67
86
  // and the fit height below is the one of the drawing at that same zoom.
68
87
  const applied = input.zoomQuantum === undefined || zoomFit >= maxZoom ? zoomFit : floorToQuantum(zoomFit, input.zoomQuantum);
69
- // All hosts and camera inputs share this range. A small frame or a large
70
- // unfolded scene reaches the floor, then scrolls instead of shrinking text.
71
- const zoom = Math.max(readableFloor, applied);
88
+ // The window-fit opt-in can use a smaller overview. Default framing keeps
89
+ // the readability floor and scrolls oversized scenes.
90
+ const zoom = input.fitToWindow && zoomFit > 0
91
+ ? applied || zoomFit
92
+ : Math.max(readableFloor, applied);
72
93
  const fitHeight = Math.min(box.height, Math.ceil((bounds.height * zoom + 2 * FIT_PAINT_INSET) * 64) / 64);
73
94
  return { fitWidth: box.width, fitHeight, zoomFit, zoom, minZoom: zoom, maxZoom, pans: zoom > zoomFit };
74
95
  }
package/dist/index.d.ts CHANGED
@@ -19,8 +19,12 @@ export * from "./transform.js";
19
19
  export * from "./camera.js";
20
20
  export * from "./geometry.js";
21
21
  export * from "./visibility.js";
22
+ export * from "./r7Mode.js";
22
23
  export * from "./scene.js";
23
24
  export * from "./hit.js";
24
25
  export * from "./layout/index.js";
25
26
  export * from "./presentation/erd.js";
27
+ export { connectorPath, parseConnectorPath, DEFAULT_EDGE_CORNER_RADIUS } from "./presentation/connectorPath.js";
28
+ export { ARROWHEAD_MARKER_GEOMETRY, connectorDashArray, connectorMarkerIds, connectorMarkerKind, connectorMarkerRef, extraConnectorMarkers, type ConnectorMarkerEdgeInput, type ConnectorMarkerIds, type ConnectorMarkerSpec, } from "./presentation/connectorStyle.js";
29
+ export { buildSceneLinkLegend, collectLinkLegendStyles, defaultLinkStyleLabel, LINK_LEGEND_ARROWHEAD_ORDER, LINK_LEGEND_EMPHASIS_ORDER, LINK_LEGEND_FONT_SIZE, LINK_LEGEND_GAP, LINK_LEGEND_HEADER_GAP, LINK_LEGEND_HEADER_HEIGHT, LINK_LEGEND_MIN_WIDTH, LINK_LEGEND_PADDING, LINK_LEGEND_ROW_GAP, LINK_LEGEND_ROW_HEIGHT, LINK_LEGEND_STROKE_ORDER, LINK_LEGEND_SWATCH_GAP, LINK_LEGEND_SWATCH_HEIGHT, LINK_LEGEND_SWATCH_WIDTH, linkLegendBoxStyle, linkLegendSwatchGeometry, linkStyleKey, type BuildSceneLinkLegendInput, type LinkLegendAnchor, type LinkLegendEdgeInput, type LinkLegendEntry, type LinkLegendStyleKey, type LinkLegendSwatchGeometry, type SceneLinkLegend, } from "./presentation/linkLegend.js";
26
30
  //# sourceMappingURL=index.d.ts.map
package/dist/index.js CHANGED
@@ -19,8 +19,12 @@ export * from "./transform.js";
19
19
  export * from "./camera.js";
20
20
  export * from "./geometry.js";
21
21
  export * from "./visibility.js";
22
+ export * from "./r7Mode.js";
22
23
  export * from "./scene.js";
23
24
  export * from "./hit.js";
24
25
  export * from "./layout/index.js";
25
26
  export * from "./presentation/erd.js";
27
+ export { connectorPath, parseConnectorPath, DEFAULT_EDGE_CORNER_RADIUS } from "./presentation/connectorPath.js";
28
+ export { ARROWHEAD_MARKER_GEOMETRY, connectorDashArray, connectorMarkerIds, connectorMarkerKind, connectorMarkerRef, extraConnectorMarkers, } from "./presentation/connectorStyle.js";
29
+ export { buildSceneLinkLegend, collectLinkLegendStyles, defaultLinkStyleLabel, LINK_LEGEND_ARROWHEAD_ORDER, LINK_LEGEND_EMPHASIS_ORDER, LINK_LEGEND_FONT_SIZE, LINK_LEGEND_GAP, LINK_LEGEND_HEADER_GAP, LINK_LEGEND_HEADER_HEIGHT, LINK_LEGEND_MIN_WIDTH, LINK_LEGEND_PADDING, LINK_LEGEND_ROW_GAP, LINK_LEGEND_ROW_HEIGHT, LINK_LEGEND_STROKE_ORDER, LINK_LEGEND_SWATCH_GAP, LINK_LEGEND_SWATCH_HEIGHT, LINK_LEGEND_SWATCH_WIDTH, linkLegendBoxStyle, linkLegendSwatchGeometry, linkStyleKey, } from "./presentation/linkLegend.js";
26
30
  //# sourceMappingURL=index.js.map
@@ -1,5 +1,7 @@
1
1
  /** Instance-owned, bounded memoisation around the complete layout/routing call. */
2
2
  import { canonicalise, collapsedOf, tryCanonicalise, } from "@sentropic/diagram-core";
3
+ import { DEFAULT_EDGE_LABEL_SIZE } from "../camera.js";
4
+ import { isR7ConnectorPresentation } from "../r7Mode.js";
3
5
  import { layoutDocument } from "./engine.js";
4
6
  import { digestOf, layoutFingerprint } from "./fingerprint.js";
5
7
  import { layoutFolded, layoutMeasured } from "./measured.js";
@@ -75,7 +77,8 @@ export function createLayoutCache(config = {}) {
75
77
  const collapsed = [...new Set(options.collapsed ?? (sourceView === undefined ? [] : [...collapsedOf(sourceView)]))].sort();
76
78
  const tokens = Object.fromEntries(Object.entries(config.tokens ?? {}).filter(([name]) => !cameraTokens.has(name)));
77
79
  const { previousOrientation: _previous, ...baseOptions } = options;
78
- const fingerprint = layoutFingerprint({ options: { ...baseOptions, collapsed }, tokens });
80
+ const r7Routing = isR7ConnectorPresentation(options.presentation, sourceView, document);
81
+ const fingerprint = layoutFingerprint({ options: { ...baseOptions, collapsed }, tokens, r7Routing });
79
82
  // Camera is host state; measured layout overwrites it rather than reading it.
80
83
  const source = () => sourceView === undefined ? undefined : {
81
84
  ...sourceView, presentation: { ...sourceView.presentation, camera: undefined },
@@ -91,15 +94,22 @@ export function createLayoutCache(config = {}) {
91
94
  if (documentDigest === undefined || presentationDigest === undefined || sourceViewDigest === undefined)
92
95
  return undefined;
93
96
  const metrics = { ...DEFAULT_LAYOUT_METRICS, ...options.metrics };
97
+ const edgeLabelSize = metrics.edgeLabelSize !== undefined && Number.isFinite(metrics.edgeLabelSize) && metrics.edgeLabelSize > 0
98
+ ? metrics.edgeLabelSize
99
+ : DEFAULT_EDGE_LABEL_SIZE;
94
100
  const input = tryCanonicalise({
95
101
  fingerprint, targetWidth: options.targetWidth,
96
102
  // The fingerprint already resolves row gaps and routing metrics. These
97
103
  // remaining compatibility metrics also affect the returned view bytes.
98
- metrics: Object.fromEntries(["nodePaddingX", "nodePaddingY", "nodeMinWidth", "nodeMinHeight", "containerPadding", "titlePaddingY", "rankGap"].map((name) => [name, name === "rankGap" ? options.hints?.rankGap ?? metrics.rankGap : metrics[name]])),
104
+ metrics: {
105
+ ...Object.fromEntries(["nodePaddingX", "nodePaddingY", "nodeMinWidth", "nodeMinHeight", "containerPadding", "titlePaddingY", "rankGap"].map((name) => [name, name === "rankGap" ? options.hints?.rankGap ?? metrics.rankGap : metrics[name]])),
106
+ edgeLabelSize,
107
+ },
99
108
  pathKind: measured ? "measured" : "compatibility",
100
109
  documentDigest, presentationDigest, sourceViewDigest, registry,
101
110
  bindings: options.bindings === undefined ? "" : inputDigest(options.bindings),
102
111
  ...(options.reportSurfaceSame === true ? { reportSurfaceSame: true } : {}),
112
+ ...(options.conventions === undefined ? {} : { conventions: options.conventions }),
103
113
  });
104
114
  // Invalid serialisable inputs still reach the engine's normal refusal path.
105
115
  if (!input.ok)
@@ -8,7 +8,13 @@ export interface ChannelMetrics {
8
8
  readonly gapMax: number;
9
9
  }
10
10
  export declare function channelMetrics(metrics: Partial<LayoutMetrics>, horizontal: boolean): ChannelMetrics;
11
+ /**
12
+ * Flow-sized gap for leaf-card channels (`!zone`). Sibling-zone gutters
13
+ * (`zone === true`, REQ-R7-14) bypass this helper and stay fixed at `zoneGutter`.
14
+ */
11
15
  export declare function channelGap(n: number, labelled: boolean, metrics: ChannelMetrics): number;
16
+ /** Maximum number of parallel longitudinal tracks a gutter of width `gap` holds at `routeSpacing` with `borderClearance` on both sides. */
17
+ export declare function channelCapacity(gap: number, routeSpacing?: number, borderClearance?: number): number;
12
18
  export interface LayoutChannel {
13
19
  readonly id: string;
14
20
  /** Axis of the gap (horizontal gap separates columns). */
@@ -24,5 +30,9 @@ export interface LayoutChannel {
24
30
  readonly labelled: boolean;
25
31
  readonly gap: number;
26
32
  readonly expected: number;
33
+ /** Parallel longitudinal track capacity of this gutter at current spacing tokens (DE-2). */
34
+ readonly capacity?: number;
35
+ /** True when this gutter separates sibling zones (governed by `zoneGutter`, DE-2 ask 3). */
36
+ readonly zone?: boolean;
27
37
  }
28
38
  //# sourceMappingURL=channels.d.ts.map
@@ -8,7 +8,20 @@ export function channelMetrics(metrics, horizontal) {
8
8
  gapMax: (horizontal ? metrics.gapInlineMax : metrics.gapBlockMax) ?? metrics.gapMax ?? spacing.gapMax,
9
9
  };
10
10
  }
11
+ /**
12
+ * Flow-sized gap for leaf-card channels (`!zone`). Sibling-zone gutters
13
+ * (`zone === true`, REQ-R7-14) bypass this helper and stay fixed at `zoneGutter`.
14
+ */
11
15
  export function channelGap(n, labelled, metrics) {
12
16
  return n === 0 ? metrics.gapMin : Math.min(metrics.gapMax, Math.max(metrics.gapMin, metrics.gapBase + n * metrics.trackSpacing + (labelled ? metrics.labelBand : 0)));
13
17
  }
18
+ /** Maximum number of parallel longitudinal tracks a gutter of width `gap` holds at `routeSpacing` with `borderClearance` on both sides. */
19
+ export function channelCapacity(gap, routeSpacing = spacing.routeSpacing, borderClearance = spacing.routeBorderClearance) {
20
+ const usable = gap - 2 * borderClearance;
21
+ if (usable < 0)
22
+ return 0;
23
+ if (!(routeSpacing > 0))
24
+ return 1;
25
+ return Math.floor(usable / routeSpacing) + 1;
26
+ }
14
27
  //# sourceMappingURL=channels.js.map
@@ -0,0 +1,117 @@
1
+ /**
2
+ * Diagram authoring conventions and opt-in non-blocking lints (DE-2 asks 5 & 6).
3
+ *
4
+ * 1. **Arrow-direction convention (ask 5):**
5
+ * In every directed relation, `source` is the initiator of the action and
6
+ * `target` is the receiver / target of the action. Because initiation is a
7
+ * semantic property that cannot be guessed from graph topology alone, the
8
+ * `arrow-direction-convention` lint is opt-in and only evaluates edges that
9
+ * explicitly declare initiator metadata (either via the semantic relation's
10
+ * `attributes.initiator` text value or via `conventions.initiators`).
11
+ *
12
+ * 2. **No opaque acronyms as zone tags (ask 6):**
13
+ * A zone tag (`kicker`) must not consist solely of an unexplained acronym;
14
+ * an acronym is expected with its descriptive label (e.g.
15
+ * `"IAM — Identity & Access Management"` or `"VPC · Réseau privé"`). The
16
+ * `zone-tag-opaque-acronym` lint is opt-in and non-blocking by default, and
17
+ * ships with a default allowlist covering the product kickers of `DLR-315`.
18
+ *
19
+ * Pure computation: zero DOM, zero external dependencies.
20
+ */
21
+ import type { CanonicalArrowheadKind, SemanticDocument } from "@sentropic/diagram-core";
22
+ import type { LayoutWarning } from "./types.js";
23
+ /** Documented DS convention for directed connectors: `source` is the initiator of the action. */
24
+ export declare const ARROW_DIRECTION_CONVENTION: "source-is-initiator";
25
+ /**
26
+ * Default zone-tag allowlist covering existing product kickers of `DLR-315`
27
+ * so legacy and product-scoped scenes are not broken when the lint is enabled.
28
+ */
29
+ export declare const DEFAULT_ZONE_TAG_ACRONYM_ALLOWLIST: readonly string[];
30
+ /** Opt-in convention lint configuration (off and non-blocking by default). */
31
+ export interface DiagramConventionLintOptions {
32
+ /**
33
+ * Opt-in lint for the arrow-direction convention (`source` = initiator of
34
+ * the action, DE-2 ask 5). Off by default; undecidable without initiator
35
+ * metadata, so edges without declared initiator metadata emit nothing.
36
+ */
37
+ readonly arrowDirection?: boolean;
38
+ /**
39
+ * Optional initiator metadata keyed by relation occurrence id or semantic
40
+ * relation id, mapping to the initiating entity id, occurrence id, or local id.
41
+ */
42
+ readonly initiators?: Readonly<Record<string, string>>;
43
+ /**
44
+ * Opt-in non-blocking lint for opaque acronyms used as zone tags (`kicker`)
45
+ * without an accompanying descriptive label (DE-2 ask 6). Off by default.
46
+ */
47
+ readonly zoneTagAcronyms?: boolean;
48
+ /**
49
+ * Additional allowed zone tag values merged with
50
+ * {@link DEFAULT_ZONE_TAG_ACRONYM_ALLOWLIST}.
51
+ */
52
+ readonly zoneTagAcronymAllowlist?: readonly string[];
53
+ }
54
+ /**
55
+ * Returns `true` when `tag` is an unexplained/opaque acronym without an
56
+ * accompanying descriptive label, and is not covered by the allowlist
57
+ * (defaulting to {@link DEFAULT_ZONE_TAG_ACRONYM_ALLOWLIST}).
58
+ */
59
+ export declare function isOpaqueAcronymZoneTag(tag: string, allowlist?: readonly string[]): boolean;
60
+ export interface ArrowDirectionEdgeInput {
61
+ /** Occurrence id (or relation id) identifying the drawn edge. */
62
+ readonly id: string;
63
+ /** Semantic relation id, when backed by a document relation. */
64
+ readonly relationId?: string;
65
+ /** Drawn source entity ref. */
66
+ readonly sourceEntity: string;
67
+ /** Drawn target entity ref. */
68
+ readonly targetEntity: string;
69
+ /** Drawn source occurrence ref, when available. */
70
+ readonly sourceOccurrence?: string;
71
+ /** Drawn target occurrence ref, when available. */
72
+ readonly targetOccurrence?: string;
73
+ /** Semantic relation source entity ref (before fold lifting), when available. */
74
+ readonly semanticSourceEntity?: string;
75
+ /** Semantic relation target entity ref (before fold lifting), when available. */
76
+ readonly semanticTargetEntity?: string;
77
+ /** Resolved arrowhead kind; `"none"` marks an undirected edge and is skipped. */
78
+ readonly arrowhead?: CanonicalArrowheadKind;
79
+ /** Explicit initiator override for this edge (entity ref, occurrence ref, or local id). */
80
+ readonly initiator?: string;
81
+ }
82
+ export interface LintArrowDirectionInput {
83
+ readonly document?: SemanticDocument;
84
+ readonly edges: readonly ArrowDirectionEdgeInput[];
85
+ readonly initiators?: Readonly<Record<string, string>>;
86
+ }
87
+ /**
88
+ * Opt-in lint verifying the arrow-direction convention (`source` = initiator of
89
+ * the action, DE-2 ask 5). Only evaluates directed edges that explicitly
90
+ * declare initiator metadata; returns non-blocking `info` diagnostics.
91
+ */
92
+ export declare function lintArrowDirection(input: LintArrowDirectionInput): readonly LayoutWarning[];
93
+ export interface ZoneTagLintEntry {
94
+ /** Zone occurrence or entity id. */
95
+ readonly id: string;
96
+ /** Zone tag / kicker text. */
97
+ readonly tag: string | undefined;
98
+ }
99
+ export interface LintZoneTagAcronymsInput {
100
+ readonly zones: readonly ZoneTagLintEntry[];
101
+ readonly allowlist?: readonly string[];
102
+ }
103
+ /**
104
+ * Opt-in non-blocking lint flagging zones whose tag (`kicker`) is a bare opaque
105
+ * acronym without a descriptive label (DE-2 ask 6). Product kickers from
106
+ * `DLR-315` are allowed by default.
107
+ */
108
+ export declare function lintZoneTagAcronyms(input: LintZoneTagAcronymsInput): readonly LayoutWarning[];
109
+ export interface LintDiagramConventionsInput {
110
+ readonly options?: DiagramConventionLintOptions;
111
+ readonly document?: SemanticDocument;
112
+ readonly edges?: readonly ArrowDirectionEdgeInput[];
113
+ readonly zones?: readonly ZoneTagLintEntry[];
114
+ }
115
+ /** Run the enabled opt-in convention lints; returns `[]` when no lint is opted into. */
116
+ export declare function lintDiagramConventions(input: LintDiagramConventionsInput): readonly LayoutWarning[];
117
+ //# sourceMappingURL=conventions.d.ts.map
@@ -0,0 +1,185 @@
1
+ /** Documented DS convention for directed connectors: `source` is the initiator of the action. */
2
+ export const ARROW_DIRECTION_CONVENTION = "source-is-initiator";
3
+ /**
4
+ * Default zone-tag allowlist covering existing product kickers of `DLR-315`
5
+ * so legacy and product-scoped scenes are not broken when the lint is enabled.
6
+ */
7
+ export const DEFAULT_ZONE_TAG_ACRONYM_ALLOWLIST = [
8
+ "H2A",
9
+ "SENTROPIC",
10
+ "ENGRAM",
11
+ "DESIGN SYSTEM",
12
+ "SENTROPIC & 3RD PARTIES",
13
+ "SENTROPIC & TIERS",
14
+ ];
15
+ function normalizeTag(value) {
16
+ return value.trim().replace(/\s+/g, " ").toUpperCase();
17
+ }
18
+ function buildAllowlist(extra) {
19
+ const set = new Set();
20
+ for (const entry of DEFAULT_ZONE_TAG_ACRONYM_ALLOWLIST)
21
+ set.add(normalizeTag(entry));
22
+ if (extra !== undefined) {
23
+ for (const entry of extra)
24
+ set.add(normalizeTag(entry));
25
+ }
26
+ return set;
27
+ }
28
+ /**
29
+ * Matches a single bare uppercase acronym/code token:
30
+ * - 2 to 5 uppercase ASCII letters/digits containing at least one letter (e.g. `IAM`, `VPC`, `GCP`, `BQ`, `S3`, `K8S`, `CICD`), or
31
+ * - an uppercase alphanumeric code with digits (e.g. `OAUTH2`, `DLR-315`, `L2A`), or
32
+ * - slash/hyphen-joined bare acronym parts (e.g. `CI/CD`, `IAM/SSO`, `GCP-PRD`).
33
+ */
34
+ const BARE_ACRONYM_PART = /^(?:(?=[A-Z0-9]*[A-Z])[A-Z0-9]{2,5}|[A-Z]{1,5}\d+[A-Z0-9]*)$/;
35
+ function isBareAcronymToken(token) {
36
+ if (token.length === 0)
37
+ return false;
38
+ // Any lowercase letter indicates a descriptive word/label, not a bare uppercase acronym.
39
+ if (/[a-z\u00e0-\u00ff]/.test(token))
40
+ return false;
41
+ if (!/[A-Z]/.test(token))
42
+ return false;
43
+ const parts = token.split(/[/-]+/).filter((part) => part.length > 0);
44
+ if (parts.length === 0)
45
+ return false;
46
+ return parts.every((part) => BARE_ACRONYM_PART.test(part) || /^\d+$/.test(part));
47
+ }
48
+ /**
49
+ * Returns `true` when `tag` is an unexplained/opaque acronym without an
50
+ * accompanying descriptive label, and is not covered by the allowlist
51
+ * (defaulting to {@link DEFAULT_ZONE_TAG_ACRONYM_ALLOWLIST}).
52
+ */
53
+ export function isOpaqueAcronymZoneTag(tag, allowlist) {
54
+ const trimmed = tag.trim();
55
+ if (trimmed.length === 0)
56
+ return false;
57
+ if (buildAllowlist(allowlist).has(normalizeTag(trimmed)))
58
+ return false;
59
+ // Split on label separators (`·`, dashes surrounded by space, `:`, `|`, parens, commas, whitespace).
60
+ // Keep internal `/` and `-` (like `CI/CD` or `DLR-315`) intact inside each token.
61
+ const tokens = trimmed
62
+ .split(/(?:\s+[—–-]\s+|\s*[·—–:|(),]+\s*|\s+)/)
63
+ .map((token) => token.trim())
64
+ .filter((token) => token.length > 0 && token !== "&");
65
+ if (tokens.length === 0)
66
+ return false;
67
+ return tokens.every(isBareAcronymToken);
68
+ }
69
+ function normalizeEndpointId(ref) {
70
+ const trimmed = ref.trim();
71
+ if (trimmed.startsWith("entity:"))
72
+ return trimmed.slice("entity:".length);
73
+ if (trimmed.startsWith("occurrence:e."))
74
+ return trimmed.slice("occurrence:e.".length);
75
+ if (trimmed.startsWith("occurrence:"))
76
+ return trimmed.slice("occurrence:".length);
77
+ return trimmed;
78
+ }
79
+ function matchesEndpoint(declared, candidates) {
80
+ const trimmed = declared.trim();
81
+ const normalized = normalizeEndpointId(trimmed);
82
+ for (const candidate of candidates) {
83
+ if (candidate === undefined)
84
+ continue;
85
+ if (candidate === trimmed || normalizeEndpointId(candidate) === normalized)
86
+ return true;
87
+ }
88
+ return false;
89
+ }
90
+ function readInitiatorAttribute(relation) {
91
+ if (relation === undefined)
92
+ return undefined;
93
+ const attr = relation.attributes["initiator"];
94
+ if (attr !== undefined && attr.kind === "text" && attr.value.trim().length > 0) {
95
+ return attr.value.trim();
96
+ }
97
+ return undefined;
98
+ }
99
+ /**
100
+ * Opt-in lint verifying the arrow-direction convention (`source` = initiator of
101
+ * the action, DE-2 ask 5). Only evaluates directed edges that explicitly
102
+ * declare initiator metadata; returns non-blocking `info` diagnostics.
103
+ */
104
+ export function lintArrowDirection(input) {
105
+ const warnings = [];
106
+ for (const edge of input.edges) {
107
+ if (edge.arrowhead === "none")
108
+ continue;
109
+ const relation = edge.relationId !== undefined ? input.document?.relations[edge.relationId] : undefined;
110
+ const declared = edge.initiator ??
111
+ input.initiators?.[edge.id] ??
112
+ (edge.relationId !== undefined ? input.initiators?.[edge.relationId] : undefined) ??
113
+ readInitiatorAttribute(relation);
114
+ if (declared === undefined || declared.trim().length === 0)
115
+ continue;
116
+ const sourceCandidates = [edge.sourceEntity, edge.sourceOccurrence, edge.semanticSourceEntity];
117
+ const targetCandidates = [edge.targetEntity, edge.targetOccurrence, edge.semanticTargetEntity];
118
+ if (matchesEndpoint(declared, sourceCandidates))
119
+ continue;
120
+ const inverted = matchesEndpoint(declared, targetCandidates);
121
+ warnings.push({
122
+ severity: "info",
123
+ code: "arrow-direction-convention",
124
+ refs: [edge.id],
125
+ message: inverted
126
+ ? `edge ${edge.id} points from ${edge.sourceEntity} to ${edge.targetEntity}, but ${declared} is declared as initiator (convention: source = initiator)`
127
+ : `edge ${edge.id} declares initiator ${declared} which does not match source ${edge.sourceEntity} (convention: source = initiator)`,
128
+ details: {
129
+ convention: ARROW_DIRECTION_CONVENTION,
130
+ reason: inverted ? "source-not-initiator" : "initiator-not-endpoint",
131
+ source: edge.sourceEntity,
132
+ target: edge.targetEntity,
133
+ initiator: declared,
134
+ },
135
+ });
136
+ }
137
+ return warnings;
138
+ }
139
+ /**
140
+ * Opt-in non-blocking lint flagging zones whose tag (`kicker`) is a bare opaque
141
+ * acronym without a descriptive label (DE-2 ask 6). Product kickers from
142
+ * `DLR-315` are allowed by default.
143
+ */
144
+ export function lintZoneTagAcronyms(input) {
145
+ const warnings = [];
146
+ for (const zone of input.zones) {
147
+ if (zone.tag === undefined)
148
+ continue;
149
+ if (!isOpaqueAcronymZoneTag(zone.tag, input.allowlist))
150
+ continue;
151
+ warnings.push({
152
+ severity: "info",
153
+ code: "zone-tag-opaque-acronym",
154
+ refs: [zone.id],
155
+ message: `zone ${zone.id} uses opaque acronym tag "${zone.tag.trim()}" without a descriptive label`,
156
+ details: {
157
+ zone: zone.id,
158
+ tag: zone.tag.trim(),
159
+ },
160
+ });
161
+ }
162
+ return warnings;
163
+ }
164
+ /** Run the enabled opt-in convention lints; returns `[]` when no lint is opted into. */
165
+ export function lintDiagramConventions(input) {
166
+ const opts = input.options;
167
+ if (opts === undefined)
168
+ return [];
169
+ const warnings = [];
170
+ if (opts.arrowDirection === true && input.edges !== undefined) {
171
+ warnings.push(...lintArrowDirection({
172
+ ...(input.document === undefined ? {} : { document: input.document }),
173
+ edges: input.edges,
174
+ ...(opts.initiators === undefined ? {} : { initiators: opts.initiators }),
175
+ }));
176
+ }
177
+ if (opts.zoneTagAcronyms === true && input.zones !== undefined) {
178
+ warnings.push(...lintZoneTagAcronyms({
179
+ zones: input.zones,
180
+ ...(opts.zoneTagAcronymAllowlist === undefined ? {} : { allowlist: opts.zoneTagAcronymAllowlist }),
181
+ }));
182
+ }
183
+ return warnings;
184
+ }
185
+ //# sourceMappingURL=conventions.js.map
@@ -88,6 +88,8 @@ export declare function dockEdges(input: {
88
88
  readonly metrics: LayoutMetrics;
89
89
  readonly labelSizes: ReadonlyMap<RelationRef, TextSize>;
90
90
  readonly fixed?: boolean;
91
+ /** Minimum inset from box corners on fixed-box sides so adjacent-side ports keep route spacing (DE-2). */
92
+ readonly cornerInset?: number;
91
93
  /**
92
94
  * Sides imposed on the two ends of an ordinary pair (neither a self-loop nor
93
95
  * an ancestor pair). The row-pack path docks a labelled bridge between two
@@ -179,7 +179,11 @@ export function dockEdges(input) {
179
179
  const count = orderedKeys.length;
180
180
  const wanted = Math.max(slotSpacingFor(metrics, count >= 2 ? thickness : 0), flowRun ? (input.flowBadgeSize ?? 0) + metrics.labelMargin : 0);
181
181
  if (fixed === true) {
182
- const capacity = Math.max(1, Math.floor(length / wanted) + 1);
182
+ const inset = input.cornerInset !== undefined && input.cornerInset > 0
183
+ ? Math.min(input.cornerInset, length / 2)
184
+ : 0;
185
+ const usableLength = Math.max(0, length - 2 * inset);
186
+ const capacity = Math.max(1, Math.floor(usableLength / wanted) + 1);
183
187
  const centre = centreOf(rect);
184
188
  const pointFor = (offset) => side === "east"
185
189
  ? { x: rect.x + rect.width, y: centre.y + offset }
@@ -1,13 +1,15 @@
1
1
  import type { LayoutMeasurements } from "./measure.js";
2
2
  import { type LayoutOptions } from "./types.js";
3
3
  /** Bumped whenever measured placement changes for unchanged inputs. */
4
- export declare const LAYOUT_ENGINE_VERSION = "dc2c.owner.5";
4
+ export declare const LAYOUT_ENGINE_VERSION = "de2.gutter.2";
5
5
  export interface LayoutFingerprintInput {
6
- readonly options: Pick<LayoutOptions, "collapsed" | "hints" | "metrics" | "rowPack" | "previousOrientation" | "viewId" | "flows" | "flowTokens">;
6
+ readonly options: Pick<LayoutOptions, "collapsed" | "hints" | "metrics" | "presentation" | "rowPack" | "previousOrientation" | "viewId" | "flows" | "flowTokens">;
7
7
  /** Measured sizes of a previous call on the same document and measurer, when a cache has them. */
8
8
  readonly measurements?: LayoutMeasurements;
9
9
  /** Resolved token numbers the host read (gaps, caps, target aspect, display scales, …), by token name. */
10
10
  readonly tokens?: Readonly<Record<string, number>>;
11
+ /** Explicit override when the caller also inspects a retained source view for r7 connector attributes. */
12
+ readonly r7Routing?: boolean;
11
13
  }
12
14
  /** FNV-1a over UTF-16 code units, two seeds: 16 hex digits. A cache key, not a security digest. */
13
15
  export declare function digestOf(text: string): string;