@sentropic/diagram-core 0.2.0 → 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.
package/README.md CHANGED
@@ -4,7 +4,7 @@ The typed semantic core of the diagram programme: versioned documents and
4
4
  profiles, views with occurrences, and transactional commands that return their
5
5
  logical inverse. No runtime dependency, no DOM, no framework, no renderer.
6
6
 
7
- This package is public as `@sentropic/diagram-core` (0.1.0, first publication).
7
+ This package is public as `@sentropic/diagram-core`, at version `0.3.0`.
8
8
  Pin the exact version — never a range, never `latest`. Publication is CI-only
9
9
  through `.github/workflows/diagram-core-publish.yml` on tags `diagram-core-v<version>`.
10
10
 
@@ -131,10 +131,8 @@ changing the presentation pin. The package includes
131
131
  [`schemas/diagram-view-schema-3.json`](schemas/diagram-view-schema-3.json) and its
132
132
  [canonical SHA-256](schemas/diagram-view-schema-3.sha256):
133
133
  `b415c05197692baa5f74ab35e3150ce58079cf9f06201df5e581d222a8d2c0df`.
134
- This branch includes the successor `@3` schema lot but defers the specification's
135
- `0.2.0` release lot: the current package version and downstream dependency pins
136
- remain `0.1.0`. The release conductor owns that version/pin/lockfile update and
137
- the owner-confirmed tag; schema inclusion does not certify downstream adoption.
134
+ The `@3` schema shipped with `0.2.0`. `@sentropic/diagram-canvas` pins this
135
+ package by exact version; schema inclusion does not certify downstream adoption.
138
136
 
139
137
  ### Commands are transactions
140
138
 
@@ -188,6 +186,98 @@ so a migrated document may still be unwritable — for instance when a value tha
188
186
  failed to convert was a **required** attribute. The report names the element; the
189
187
  decision is the host's.
190
188
 
189
+ ## Layout-hint vocabulary (`ds-layout-hints@1`)
190
+
191
+ A view declaration names its layout through one closed vocabulary, authored,
192
+ versioned and pinned here. A consumer (engram's view mechanism) references the
193
+ pin and calls the validator; it never keeps a mode table of its own.
194
+
195
+ ```ts
196
+ import { DS_LAYOUT_VOCABULARY_PIN, validateLayoutHints, lowerLayoutHints } from "@sentropic/diagram-core";
197
+
198
+ const layout = { vocabulary: "ds-layout-hints@1", mode: "auto-pack", grouping_axis: "rows" };
199
+ const diagnostics = validateLayoutHints(layout); // [] means valid
200
+ ```
201
+
202
+ | Export | What it is |
203
+ |---|---|
204
+ | `DS_LAYOUT_HINTS_SCHEMA` | JSON Schema 2020-12, closed, deeply frozen. Also shipped as [`schemas/ds-layout-hints-1.json`](schemas/ds-layout-hints-1.json) (canonical bytes) with its [SHA-256](schemas/ds-layout-hints-1.sha256). |
205
+ | `DS_LAYOUT_HINTS_RULES` | The semantic rules as frozen data. Every list equals an enum of the schema's `$defs`. |
206
+ | `validateLayoutHints(value, context?)` | Pure, never throws. Structure and semantics in one pass; diagnostics sorted by (path, code). |
207
+ | `DS_LAYOUT_VOCABULARY_PIN` | `PresentationPin` `{ id, version, contentDigest }`. |
208
+ | `lowerLayoutHints(hints, roots?)` | A valid payload lowered to the hints the layout engine takes. |
209
+
210
+ The pin:
211
+
212
+ ```
213
+ id https://sentropic.dev/schemas/diagram/layout-hints/v1
214
+ version ds-layout-hints@1
215
+ contentDigest e72fd3f3446e19585b2992071f57c3777685f27087165c932806e12354ced42c
216
+ ```
217
+
218
+ `contentDigest` is the SHA-256 (bare 64 lowercase hex) of the RFC 8785 bytes of
219
+ the schema: `sha256Hex(canonicalBytes(DS_LAYOUT_HINTS_SCHEMA))`. The refusal
220
+ classification lives in the schema's `$defs`, so the digest covers it. Any
221
+ change to the schema is `ds-layout-hints@2`; `tests/layout-hints.test.ts`
222
+ recomputes the digest and fails on an edit in place.
223
+
224
+ **Scope rule of `@1`: a payload that validates must render.** The vocabulary
225
+ admits only what the layout engine of `@sentropic/diagram-canvas` executes at
226
+ this version.
227
+
228
+ | `mode` | Engine entry | Admitted on |
229
+ |---|---|---|
230
+ | `auto-pack` | `layoutMeasured` | every view |
231
+ | `layered-flow` | `layoutDocument` | `generic@1` views without a typed presentation, stated through `context` |
232
+
233
+ Hints, read by `auto-pack` only: `ordering`, `rootOrder`, `grouping`
234
+ (recursive groups `{ id, direction, items, stretch? }`), `grouping_axis`
235
+ (`"rows" | "columns"`, a shorthand for one group over the root level, exclusive
236
+ with `grouping`) and `stretch`. `mode` is required: an absent mode is never
237
+ read as `auto-pack`.
238
+
239
+ Refusals are typed, and nothing is coerced to another mode:
240
+
241
+ | Code | Raised when |
242
+ |---|---|
243
+ | `layout-vocabulary-unknown` | `vocabulary` is absent or is not `ds-layout-hints@1`. Nothing else is read. |
244
+ | `layout-hints-invalid` | Structural failure: wrong type, malformed entity reference, missing member. |
245
+ | `layout-mode-not-implemented` | `lane-stack`, `matrix-grid`, `tree`: specified, not executed yet. `details.vocabulary` names `ds-layout-hints@2`. |
246
+ | `layout-mode-unknown` | Any other mode. |
247
+ | `layout-mode-out-of-scope` | `layered-flow` on a view that is not `generic@1`, that carries a typed presentation, that declares a presentation vocabulary, or whose `context` is not stated. |
248
+ | `layout-hint-forbidden` | A spacing override or a coordinate: `density`, `cardGapX`, `cardGapY`, `zoneGapX`, `zoneGapY`, `rankGap`, `gapAfter`, `x`, `y`, `width`, `height`, `edge_label_orientation`. |
249
+ | `layout-hint-not-implemented` | `direction`, `rotate_labels`: specified, not executed yet. |
250
+ | `layout-hint-out-of-scope` | A hint under `layered-flow`, which takes none. |
251
+ | `layout-hint-unknown` | Any other property. |
252
+ | `layout-hint-conflict` | `grouping` with `grouping_axis`; a group id used twice; a leaf placed twice; a member listed twice, ordered under two parents or under itself. |
253
+
254
+ What the validator cannot see: whether a reference exists in the document and
255
+ whether the members of a group are siblings. Both need the document and stay
256
+ with the layout engine (`validateHints` in `@sentropic/diagram-canvas`).
257
+ Whether a view kind takes a layout at all is the declaring grammar's rule.
258
+
259
+ ## Notation pin (`diagram-notation@1`)
260
+
261
+ `DIAGRAM_NOTATION_PIN` is exported beside the layout pin:
262
+
263
+ ```
264
+ id diagram-notation
265
+ version 1
266
+ contentDigest b4bfa7174a7a53ec23b8a8d7580d6bdfc3bab7f29deb1204aa2e4ce12424909f
267
+ ```
268
+
269
+ `contentDigest` is the SHA-256 of the RFC 8785 bytes of
270
+ `{ schema: DIAGRAM_NOTATION_SCHEMA, rules: DIAGRAM_NOTATION_RULES }`. The schema
271
+ (`$id` `engram:diagram-notation-schema/1`) is structural only: closed objects,
272
+ enums, string bounds, required `role`, `nature` and `encoding`, slot shape. The
273
+ rules are frozen data: the role table (nature, `icon`, `kicker`, `variant`,
274
+ `holds`), the variants of each nature, the property list of each encoding,
275
+ slot ownership. Any change to either is `diagram-notation@2`.
276
+
277
+ Not covered: `validateNotation`, `validateViewNotation` and `resolveNotation`.
278
+ This version freezes the vocabulary a consumer pins and ships no executor for
279
+ it; `Profile` has no `notation` member yet.
280
+
191
281
  ## What this package does not import
192
282
 
193
283
  Nothing. Not one specifier that is not a relative module of its own source, which
@@ -221,6 +311,10 @@ a test asserts by scanning every file. In particular:
221
311
  - **Codecs, source text, AST/CST and conversion reports**: GD-M4. Nothing here
222
312
  parses, fetches or executes imported content, a URI or markup.
223
313
  - **Native BPMN / ArchiMate / UML profiles**: GD-M3. See the skeletons' `notes`.
314
+ - **The notation executor**: `diagram-notation@1` is pinned as data only.
315
+ - **Layout modes `lane-stack`, `matrix-grid`, `tree` and the hints `direction`,
316
+ `rotate_labels`**: refused by `ds-layout-hints@1` until the layout engine
317
+ executes them.
224
318
  - **A reference disposition in the delete policy.** The policy governs
225
319
  occurrences, relations and ports. An entity a typed reference attribute still
226
320
  points at cannot be deleted: the transaction refuses itself on the final state
@@ -253,6 +347,8 @@ src/hash.ts fnv1a64, dependency-free, non-cryptographic
253
347
  src/validate.ts every refusal, including the nine named rejected cases
254
348
  src/commands.ts 18 commands, transactions, effects, inverses
255
349
  src/migrate.ts registered migrations and their reports
350
+ src/layout-hints.ts ds-layout-hints@1: schema, rules, validator, pin, lowering
351
+ src/notation.ts diagram-notation@1: schema, rules, pin (no executor)
256
352
  fixtures/ valid documents, a divergent-revision state, a command
257
353
  sequence, the nine rejected cases, a 1.0 stored document
258
354
  tests/ 10 suites; `refs-nominal.test.ts` is a COMPILER test
@@ -29,7 +29,23 @@ export type DiagnosticCode = "erd-missing-pk" | "erd-multiple-pk" | "erd-danglin
29
29
  /** An extension at validation level `unsupported`: preserved on import, never promoted. */
30
30
  | "extension-unsupported" | "malformed-ref" | "duplicate-id" | "record-key-mismatch" | "schema-version-malformed" | "schema-migration-required" | "document-not-an-object" | "unknown-profile" | "profile-not-declared" | "unknown-entity-type" | "unknown-relation-type" | "unknown-port-type" | "flow-types-conflict" | "flow-step-missing" | "flow-step-duplicate" | "flow-branch-overflow" | "flow-scenario-unknown" | "flow-scenario-misused" | "flow-step-end-invalid" | "flow-branch-without-sibling" | "flow-step-gap" | "type-definition-conflict" | "type-definition-reserved" | "type-definition-ambiguous" | "attribute-type-mismatch" | "attribute-required-missing" | "enum-value-not-allowed" | "quantity-unit-not-allowed" | "text-too-long" | "date-not-iso8601" | "unique-attribute-violation" | "endpoint-role-unknown" | "endpoint-cardinality-violation" | "endpoint-target-not-allowed" | "hierarchy-multiple-parents" | "port-direction-not-allowed" | "port-owner-mismatch" | "view-document-mismatch" | "revision-divergence" | "occurrence-endpoint-mismatch" | "value-not-finite" | "value-not-serialisable" | "limit-exceeded"
31
31
  /** A hierarchy endpoint targets a foreign-profile entity with no admitted semantic join (M3 §3.2.3). */
32
- | "endpoint-without-join" | "legend-key-parent-invalid" | "tone-category-unknown" | "text-pattern-mismatch" | "quantity-not-integer" | "quantity-below-min" | "quantity-above-max" | "relationship-matrix-violation" | "multiplicity-invalid" | "stereotype-application-invalid" | "reference-target-type" | "struct-type-unknown" | "struct-field-not-in-schema" | "struct-type-not-allowed" | "supertype-unknown" | "supertype-cycle" | "attribute-conflict" | "abstract-instantiated" | "unknown-command" | "target-already-exists" | "target-missing" | "delete-policy-required" | "delete-policy-refused" | "placement-kind-mismatch" | "inverse-budget-exceeded" | "extension-hash-mismatch" | "extension-source-not-retained" | "view-already-exists";
32
+ | "endpoint-without-join" | "legend-key-parent-invalid" | "tone-category-unknown" | "text-pattern-mismatch" | "quantity-not-integer" | "quantity-below-min" | "quantity-above-max" | "relationship-matrix-violation" | "multiplicity-invalid" | "stereotype-application-invalid" | "reference-target-type" | "struct-type-unknown" | "struct-field-not-in-schema" | "struct-type-not-allowed" | "supertype-unknown" | "supertype-cycle" | "attribute-conflict" | "abstract-instantiated" | "unknown-command" | "target-already-exists" | "target-missing" | "delete-policy-required" | "delete-policy-refused" | "placement-kind-mismatch" | "inverse-budget-exceeded" | "extension-hash-mismatch" | "extension-source-not-retained" | "view-already-exists"
33
+ /** `vocabulary` absent or not the pinned one: nothing else is read. */
34
+ | "layout-vocabulary-unknown"
35
+ /** Structural failure: wrong type, malformed reference, missing required member. */
36
+ | "layout-hints-invalid" | "layout-mode-unknown"
37
+ /** A mode specified for a later vocabulary: refused, never coerced. */
38
+ | "layout-mode-not-implemented"
39
+ /** A mode outside the views it is admitted on. */
40
+ | "layout-mode-out-of-scope" | "layout-hint-unknown"
41
+ /** A spacing override or a coordinate. */
42
+ | "layout-hint-forbidden"
43
+ /** A hint specified for a later vocabulary. */
44
+ | "layout-hint-not-implemented"
45
+ /** A hint the selected mode does not read. */
46
+ | "layout-hint-out-of-scope"
47
+ /** Two authored statements that cannot both hold. */
48
+ | "layout-hint-conflict";
33
49
  export type DiagnosticSeverity = "error" | "warning";
34
50
  export interface Diagnostic {
35
51
  readonly code: DiagnosticCode;
package/dist/index.d.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  * `@sentropic/diagram-core` - the typed semantic core.
3
3
  *
4
4
  * No runtime dependency, no DOM, no framework, no renderer. The package is
5
- * PRIVATE: no npm name is committed without an owner's gesture.
5
+ * public as `@sentropic/diagram-core`.
6
6
  *
7
7
  * Read `README.md` for the model, its limits and what is not covered yet.
8
8
  */
@@ -32,4 +32,6 @@ export * from "./migrate.js";
32
32
  export { relationBaseType, relationSchema } from "./relation-types.js";
33
33
  export { withFlowTypes, validateFlows, flowIndex, type FlowStep, type FlowScenario, type FlowIndex } from "./flows.js";
34
34
  export * from "./erd.js";
35
+ export * from "./layout-hints.js";
36
+ export * from "./notation.js";
35
37
  //# sourceMappingURL=index.d.ts.map
package/dist/index.js CHANGED
@@ -2,7 +2,7 @@
2
2
  * `@sentropic/diagram-core` - the typed semantic core.
3
3
  *
4
4
  * No runtime dependency, no DOM, no framework, no renderer. The package is
5
- * PRIVATE: no npm name is committed without an owner's gesture.
5
+ * public as `@sentropic/diagram-core`.
6
6
  *
7
7
  * Read `README.md` for the model, its limits and what is not covered yet.
8
8
  */
@@ -32,4 +32,6 @@ export * from "./migrate.js";
32
32
  export { relationBaseType, relationSchema } from "./relation-types.js";
33
33
  export { withFlowTypes, validateFlows, flowIndex } from "./flows.js";
34
34
  export * from "./erd.js";
35
+ export * from "./layout-hints.js";
36
+ export * from "./notation.js";
35
37
  //# sourceMappingURL=index.js.map
@@ -0,0 +1,158 @@
1
+ /**
2
+ * `ds-layout-hints@1` — the closed layout-hint vocabulary of the Design System.
3
+ *
4
+ * A view declaration (engram `MetamodelViewDecl.layout`) names a layout by this
5
+ * vocabulary and never by a table of its own. The vocabulary is authored,
6
+ * versioned and pinned here, and nowhere else.
7
+ *
8
+ * Scope rule of `@1`: it admits only what the layout engine of
9
+ * `@sentropic/diagram-canvas` executes at this version.
10
+ * - `auto-pack` = `layoutMeasured` (measured, row-packed views);
11
+ * - `layered-flow` = `layoutDocument` (ranked flow), on `generic@1` views
12
+ * without a typed presentation only.
13
+ * A mode or a hint that is specified but not executed yet (`lane-stack`,
14
+ * `matrix-grid`, `tree`, `direction`, `rotate_labels`) is REFUSED with its own
15
+ * code, never coerced to another mode: a template that validates against `@1`
16
+ * must render. Spacing overrides and coordinates are forbidden outright.
17
+ *
18
+ * Three layers, one source:
19
+ * - `DS_LAYOUT_HINTS_SCHEMA` JSON Schema 2020-12, closed. Its `$defs` also
20
+ * carry the refusal classification, so the pinned bytes cover it.
21
+ * - `DS_LAYOUT_HINTS_RULES` frozen data read from the schema `$defs`.
22
+ * - `validateLayoutHints()` pure; structural and semantic; diagnostics.
23
+ *
24
+ * Any change to the schema is `ds-layout-hints@2`: the pin digest is the
25
+ * SHA-256 of the RFC 8785 bytes of the schema.
26
+ */
27
+ import { type Diagnostic, type DiagnosticCode } from "./diagnostics.js";
28
+ import type { PresentationPin } from "./presentation.js";
29
+ import type { EntityRef } from "./refs.js";
30
+ export declare const DS_LAYOUT_VOCABULARY: "ds-layout-hints@1";
31
+ export declare const DS_LAYOUT_HINTS_SCHEMA_ID: "https://sentropic.dev/schemas/diagram/layout-hints/v1";
32
+ /** Modes the layout engine executes at this version. */
33
+ export declare const DS_LAYOUT_MODES: readonly ["auto-pack", "layered-flow"];
34
+ /** Modes specified for a later vocabulary: refused in `@1`. */
35
+ export declare const DS_LAYOUT_FUTURE_MODES: readonly ["lane-stack", "matrix-grid", "tree"];
36
+ /** Hints specified for a later vocabulary: refused in `@1`. */
37
+ export declare const DS_LAYOUT_FUTURE_HINTS: readonly ["direction", "rotate_labels"];
38
+ /** Spacing overrides and coordinates: refused in every version (one gap law, no authored geometry). */
39
+ export declare const DS_LAYOUT_FORBIDDEN_HINTS: readonly ["cardGapX", "cardGapY", "density", "edge_label_orientation", "gapAfter", "height", "rankGap", "width", "x", "y", "zoneGapX", "zoneGapY"];
40
+ /** Hints read by the measured path only: refused under `layered-flow`. */
41
+ export declare const DS_LAYOUT_MEASURED_HINTS: readonly ["grouping", "grouping_axis", "ordering", "rootOrder", "stretch"];
42
+ export declare const DS_LAYOUT_AXES: readonly ["rows", "columns"];
43
+ export type DsLayoutMode = (typeof DS_LAYOUT_MODES)[number];
44
+ export type DsLayoutFutureMode = (typeof DS_LAYOUT_FUTURE_MODES)[number];
45
+ export type DsLayoutAxis = (typeof DS_LAYOUT_AXES)[number];
46
+ /** A recursive authored group: references and subgroups interleave in `items`. */
47
+ export interface DsLayoutGroup {
48
+ readonly id: string;
49
+ readonly direction: DsLayoutAxis;
50
+ readonly items: readonly (EntityRef | DsLayoutGroup)[];
51
+ readonly stretch?: boolean;
52
+ }
53
+ /** A valid `ds-layout-hints@1` payload. */
54
+ export interface DsLayoutHints {
55
+ readonly vocabulary: typeof DS_LAYOUT_VOCABULARY;
56
+ readonly mode: DsLayoutMode;
57
+ /** Sibling order per semantic parent. */
58
+ readonly ordering?: Readonly<Record<EntityRef, readonly EntityRef[]>>;
59
+ /** Declaration order of the root level. */
60
+ readonly rootOrder?: readonly EntityRef[];
61
+ /** Authored groups. Exclusive with `grouping_axis`. */
62
+ readonly grouping?: readonly DsLayoutGroup[];
63
+ /** Shorthand: one group over the root level, packed along this axis. Exclusive with `grouping`. */
64
+ readonly grouping_axis?: DsLayoutAxis;
65
+ readonly stretch?: boolean;
66
+ }
67
+ /**
68
+ * What the validator must know about the view to judge a mode. Absent facts
69
+ * never widen a scope: `layered-flow` without a context is refused.
70
+ */
71
+ export interface LayoutHintsContext {
72
+ /** Profile references of the view's document (`generic@1`, `archimate@2`, …). */
73
+ readonly profiles?: readonly string[];
74
+ /** True when the view carries a typed presentation (`presentation.diagram`). */
75
+ readonly diagramPresentation?: boolean;
76
+ /** The presentation vocabulary of the declaring profile, when it has one (`diagram-notation@1`). */
77
+ readonly presentationVocabulary?: string;
78
+ }
79
+ declare const LAYERED_FLOW_PROFILE = "generic@1";
80
+ /** The canonical JSON Schema of `ds-layout-hints@1`, deeply frozen. Also shipped as `schemas/ds-layout-hints-1.json`. */
81
+ export declare const DS_LAYOUT_HINTS_SCHEMA: Readonly<Record<string, unknown>>;
82
+ /** SHA-256 (64 lowercase hex) of the RFC 8785 bytes of the schema. */
83
+ export declare const DS_LAYOUT_HINTS_SCHEMA_DIGEST: string;
84
+ /** The pin a view declaration references. Equality is equality of the three fields. */
85
+ export declare const DS_LAYOUT_VOCABULARY_PIN: PresentationPin;
86
+ export type LayoutHintsDiagnosticCode = Extract<DiagnosticCode, `layout-${string}`>;
87
+ export interface DsLayoutHintsRules {
88
+ readonly vocabulary: typeof DS_LAYOUT_VOCABULARY;
89
+ /** Admitted modes, and the code raised for everything else. */
90
+ readonly modes: {
91
+ readonly implemented: readonly DsLayoutMode[];
92
+ /** Refused with `layout-mode-not-implemented`. */
93
+ readonly future: readonly DsLayoutFutureMode[];
94
+ /** The vocabulary a future mode waits for. */
95
+ readonly futureVocabulary: "ds-layout-hints@2";
96
+ };
97
+ /** `layered-flow` is admitted only on a view matching every fact below. */
98
+ readonly layeredFlowScope: {
99
+ readonly profiles: readonly [typeof LAYERED_FLOW_PROFILE];
100
+ readonly diagramPresentation: false;
101
+ readonly presentationVocabulary: "absent";
102
+ };
103
+ readonly hints: {
104
+ /** Read by the measured path; refused under `layered-flow` with `layout-hint-out-of-scope`. */
105
+ readonly measuredOnly: readonly string[];
106
+ /** Refused with `layout-hint-not-implemented`. */
107
+ readonly future: readonly string[];
108
+ /** Refused with `layout-hint-forbidden`. */
109
+ readonly forbidden: readonly string[];
110
+ /** Pairs that cannot be authored together (`layout-hint-conflict`). */
111
+ readonly exclusive: readonly (readonly [string, string])[];
112
+ };
113
+ /** Identity rules checked on a structurally valid payload (`layout-hint-conflict`). */
114
+ readonly identity: readonly ["group-id-unique", "group-leaf-once", "ordering-member-single-parent", "ordering-parent-not-member"];
115
+ }
116
+ /** The semantic rules of `ds-layout-hints@1`, as data. Every list equals the matching schema `$defs` enum. */
117
+ export declare const DS_LAYOUT_HINTS_RULES: DsLayoutHintsRules;
118
+ /**
119
+ * Validate a layout-hint payload against `ds-layout-hints@1`: structure and
120
+ * semantics, in one pass. Pure; never throws; an empty result means valid.
121
+ * Diagnostics are sorted by (path, code).
122
+ *
123
+ * What it cannot see: whether a reference exists in the document and whether
124
+ * the members of a group are siblings. Those need the document and stay with
125
+ * the layout engine (`validateHints` in `@sentropic/diagram-canvas`).
126
+ */
127
+ export declare function validateLayoutHints(value: unknown, context?: LayoutHintsContext): readonly Diagnostic[];
128
+ /** Type guard: true iff `validateLayoutHints` raises nothing. */
129
+ export declare function isLayoutHints(value: unknown, context?: LayoutHintsContext): value is DsLayoutHints;
130
+ /** The engine-side group shape (`LayoutGroup` of `@sentropic/diagram-canvas`), stated structurally. */
131
+ export interface LoweredLayoutGroup {
132
+ readonly id: string;
133
+ readonly direction: DsLayoutAxis;
134
+ readonly items: readonly (EntityRef | LoweredLayoutGroup)[];
135
+ readonly stretch?: boolean;
136
+ }
137
+ /** The engine-side hints (`LayoutHints` of `@sentropic/diagram-canvas`), stated structurally: no gap, no coordinate. */
138
+ export interface LoweredLayoutHints {
139
+ readonly ordering?: Readonly<Record<EntityRef, readonly EntityRef[]>>;
140
+ readonly rootOrder?: readonly EntityRef[];
141
+ readonly grouping?: readonly LoweredLayoutGroup[];
142
+ readonly stretch?: boolean;
143
+ }
144
+ /** The id of the root group `grouping_axis` lowers to. */
145
+ export declare const DS_LAYOUT_ROOT_GROUP_ID: "ds-layout-hints.root";
146
+ /**
147
+ * Lower a VALID payload to the hints the layout engine takes. `mode` selects
148
+ * the engine entry and is not part of the result; `layered-flow` lowers to no
149
+ * hint at all.
150
+ *
151
+ * `grouping_axis` is a shorthand for one group over the root level: it needs
152
+ * the visible root entities, which only the caller knows. Listed roots come
153
+ * first in `rootOrder`, the others after in UTF-16 order (the engine's own
154
+ * rule). Without roots the shorthand lowers to nothing.
155
+ */
156
+ export declare function lowerLayoutHints(hints: DsLayoutHints, roots?: readonly EntityRef[]): LoweredLayoutHints;
157
+ export {};
158
+ //# sourceMappingURL=layout-hints.d.ts.map