yarramate 1.24.0 → 1.25.1

package/dist/adapters/visual/layout-sidecar.d.ts

@@ -0,0 +1,28 @@
+import type { VisualLayoutPositions, VisualLayoutRoutes } from './protocol-contract.js';
+/** Where every host writes a projection's sidecar, and reads it back from. */
+export declare const LAYOUT_SIDECAR_DIR = ".yarramate/visual-layout";
+export declare const layoutSidecarPath: (projectionId: string) => string;
+/** A path a store or directory holds that could be a sidecar. */
+export declare const isLayoutSidecarPath: (path: string) => boolean;
+export interface LayoutSidecars {
+    readonly layouts: Record<string, VisualLayoutPositions>;
+    readonly folds: Record<string, {
+        folded: string[];
+        unfolded: string[];
+    }>;
+    readonly routes: Record<string, VisualLayoutRoutes>;
+}
+/**
+ * What the sidecars say, keyed by the projection id each one names.
+ *
+ * Presentation state must never fail a session (ADR 0023): a source that does
+ * not parse or does not validate is skipped, not reported. A sidecar written
+ * before #473 has neither fold list and says nothing about folding rather
+ * than "fold nothing" - the view's own default decides - so only a sidecar
+ * that STATES a fold yields a `folds` entry. A sidecar written before the
+ * routes says nothing about them, and the layout recomputes.
+ */
+export declare const readLayoutSidecars: (sources: Iterable<{
+    readonly path: string;
+    readonly source: string;
+}>) => LayoutSidecars;

package/dist/adapters/visual/layout-sidecar.js

@@ -0,0 +1,61 @@
+/**
+ * The layout sidecar, read back the one way (#503).
+ *
+ * A drag saves `.yarramate/visual-layout/<projectionId>.yaml` (ADR 0085), and
+ * since 1.25.0 the routes and the fold state ride in it beside the positions
+ * (ADR 0147, #473). Two hosts write that file and two hosts have to read it:
+ * the session server from disk, the local host a product mounts from its
+ * store. Until this module the server had a reader and the local host had
+ * none, so on a mounted host a saved drag was written faithfully and never
+ * applied again - found by ApertureX on 1.25.0 (#503). One reader here, and
+ * the two cannot drift apart a second time.
+ *
+ * Pure: it takes sources and returns what the model carries. Whoever can read
+ * a directory or a store hands the bytes over.
+ */
+import { parse } from 'yaml';
+import { validateVisualLayout } from '../../schema-validation.js';
+/** Where every host writes a projection's sidecar, and reads it back from. */
+export const LAYOUT_SIDECAR_DIR = '.yarramate/visual-layout';
+export const layoutSidecarPath = (projectionId) => `${LAYOUT_SIDECAR_DIR}/${projectionId}.yaml`;
+/** A path a store or directory holds that could be a sidecar. */
+export const isLayoutSidecarPath = (path) => path.startsWith(`${LAYOUT_SIDECAR_DIR}/`) &&
+    !path.slice(LAYOUT_SIDECAR_DIR.length + 1).includes('/') &&
+    (path.endsWith('.yaml') || path.endsWith('.yml'));
+/**
+ * What the sidecars say, keyed by the projection id each one names.
+ *
+ * Presentation state must never fail a session (ADR 0023): a source that does
+ * not parse or does not validate is skipped, not reported. A sidecar written
+ * before #473 has neither fold list and says nothing about folding rather
+ * than "fold nothing" - the view's own default decides - so only a sidecar
+ * that STATES a fold yields a `folds` entry. A sidecar written before the
+ * routes says nothing about them, and the layout recomputes.
+ */
+export const readLayoutSidecars = (sources) => {
+    const layouts = {};
+    const folds = {};
+    const routes = {};
+    for (const { source } of sources) {
+        let parsed;
+        try {
+            parsed = parse(source);
+        }
+        catch {
+            continue;
+        }
+        if (!validateVisualLayout(parsed))
+            continue;
+        const sidecar = parsed;
+        layouts[sidecar.projectionId] = sidecar.positions;
+        if (sidecar.routes !== undefined)
+            routes[sidecar.projectionId] = sidecar.routes;
+        if (sidecar.folded !== undefined || sidecar.unfolded !== undefined) {
+            folds[sidecar.projectionId] = {
+                folded: [...(sidecar.folded ?? [])],
+                unfolded: [...(sidecar.unfolded ?? [])],
+            };
+        }
+    }
+    return { layouts, folds, routes };
+};

package/dist/adapters/visual/protocol-contract.d.ts

@@ -267,6 +267,23 @@ export interface VisualLayoutPositions {
         readonly y: number;
     };
 }
+/**
+ * The routes the canvas was drawing when a layout was saved (ADR 0147), keyed
+ * by relationship id: absolute canvas coordinates from the source end, both
+ * endpoints included, and where along the route the label sits. Saved WITH
+ * the positions, because a route is only right for the positions it was
+ * computed for: a reader who moved one subject keeps every other edge's
+ * route, and only the moved subject's edges fall back to a straight line.
+ */
+export interface VisualLayoutRoutes {
+    readonly [relationshipId: string]: {
+        readonly points: readonly {
+            readonly x: number;
+            readonly y: number;
+        }[];
+        readonly labelAt: number | null;
+    };
+}
 /**
  * A change to a projection document, staged rather than written (ADR 0103).
  *
@@ -332,6 +349,8 @@ export interface VisualLayoutSavePayload {
      */
     readonly folded?: readonly string[];
     readonly unfolded?: readonly string[];
+    /** The routes in force at save time (ADR 0147); absent when nothing was routed. */
+    readonly routes?: VisualLayoutRoutes;
 }
 /**
  * Terminal event payload. Every reason is the runtime's to choose: only it

package/dist/adapters/visual/session-server.js

@@ -6,7 +6,6 @@ import { basename, extname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import Ajv2020Module from "ajv/dist/2020.js";
 import { WebSocketServer } from "ws";
-import { parse } from "yaml";
 import { VISUAL_LIMITS, VISUAL_PROTOCOL_VERSION, digestOf, parseVisualBrowserInput, parseVisualResponse, parseVisualSessionStarted, parseVisualStatus, toWireFileUri, visualBrowserInputType, } from "./protocol.js";
 import { appendTerminalEvent, appendVisualEvent, appendVisualResponse, createVisualSession, isActionableVisualEvent, recoverVisualSession, removeVisualSession, writeVisualSessionDescriptor, } from "./session-store.js";
 import { loadProjection, } from "../../projection.js";
@@ -17,17 +16,13 @@ import { planOperations, posixDirectoryOf, writeConflictDiagnostics, } from "../
 import { createFileSystemStore } from "../../source-store.js";
 import { emitYaml } from "../../yaml-emission.js";
 import { loadWorkspaceManifest, } from "../../workspace.js";
-import visualLayoutSchema from "../../../schema/yarramate-visual-layout.schema.json" with { type: "json" };
-import visualProjectionSchema from "../../../schema/yarramate-projection.schema.json" with { type: "json" };
+import { LAYOUT_SIDECAR_DIR, isLayoutSidecarPath, layoutSidecarPath, readLayoutSidecars, } from "./layout-sidecar.js";
 // The layout sidecar is adapter-owned presentation state (ADR 0023) that
 // protocol.ts's validators never touch — the browser's own `layout.save`
 // payload is already schema-validated by `parseVisualBrowserInput` before it
 // reaches this module — so this file compiles its own single-purpose
 // validator for the sidecar files it reads directly off disk.
 const Ajv2020 = Ajv2020Module.default;
-const layoutAjv = new Ajv2020({ allErrors: true });
-layoutAjv.addSchema(visualProjectionSchema);
-const validateVisualLayout = layoutAjv.compile(visualLayoutSchema);
 /**
  * Returned on every response. The policy admits no external origin at all, so
  * neither a compromised model nor a hostile chat message can reach the network,
@@ -454,44 +449,30 @@ export const startVisualServer = async (options) => {
     // Drag positions are adapter-owned presentation state (ADR 0023): never
     // validated by Core. An invalid or unreadable sidecar is skipped exactly
     // like a broken saved view above — presentation state must never fail a
-    // session.
-    const layoutDir = resolve(options.cwd, ".yarramate/visual-layout");
-    const { layouts, folds } = (() => {
-        const layouts = {};
-        const folds = {};
+    // session. The reading itself is shared with the local host (#503): this
+    // host can read a directory, so it hands the bytes over.
+    const layoutDir = resolve(options.cwd, LAYOUT_SIDECAR_DIR);
+    const { layouts, folds, routes } = readLayoutSidecars((() => {
         let entries;
         try {
             entries = readdirSync(layoutDir);
         }
         catch {
-            return { layouts, folds };
+            return [];
         }
-        for (const entry of entries) {
-            if (extname(entry) !== ".yaml" && extname(entry) !== ".yml")
-                continue;
+        return entries.flatMap((entry) => {
+            const path = `${LAYOUT_SIDECAR_DIR}/${entry}`;
+            if (!isLayoutSidecarPath(path))
+                return [];
             try {
-                const source = readFileSync(join(layoutDir, entry), "utf8");
-                const parsed = parse(source);
-                if (!validateVisualLayout(parsed))
-                    continue;
-                const sidecar = parsed;
-                layouts[sidecar.projectionId] = sidecar.positions;
-                // A sidecar written before #473 has neither list, and says nothing
-                // about folding rather than saying "fold nothing" - the view's own
-                // default decides for it. Only a sidecar that STATES a fold overrides.
-                if (sidecar.folded !== undefined || sidecar.unfolded !== undefined) {
-                    folds[sidecar.projectionId] = {
-                        folded: [...(sidecar.folded ?? [])],
-                        unfolded: [...(sidecar.unfolded ?? [])],
-                    };
-                }
+                return [{ path, source: readFileSync(join(layoutDir, entry), "utf8") }];
             }
             catch {
                 // Skipped sidecar: presentation state must never fail a session.
+                return [];
             }
-        }
-        return { layouts, folds };
-    })();
+        });
+    })());
     // `request.initialModel.graph` is the caller's compile (`buildVisualModelGraph`,
     // before invoking `yarramate-visual start`) and is only the fallback below:
     // `recompileWorkspace` immediately below is the one path that actually fills
@@ -505,6 +486,7 @@ export const startVisualServer = async (options) => {
         vocabulary: { conceptKinds: [], relationshipKinds: [] },
         layouts,
         ...(Object.keys(folds).length === 0 ? {} : { folds }),
+        ...(Object.keys(routes).length === 0 ? {} : { routes }),
         sourceDigests: request.initialModel.sourceDigests,
         // The request's model has no projections in it - `visual-model/v1` carries
         // a graph, not a workspace - so the fallback states nothing rather than
@@ -643,6 +625,11 @@ export const startVisualServer = async (options) => {
                 initialView: rendered.initialView,
                 documents: resolvedWorkspace.documents,
                 layouts: rendered.layouts,
+                // The fold state and the routes the sidecars said, or a save set,
+                // carried across the recompile like the positions are (#503): a
+                // commit is not a reason to forget how the reviewer arranged things.
+                ...(rendered.folds === undefined ? {} : { folds: rendered.folds }),
+                ...(rendered.routes === undefined ? {} : { routes: rendered.routes }),
                 // Minted from the bytes this compile just read, so what the browser
                 // renders and what it can later claim it rendered are the same read.
                 sourceDigests: Object.fromEntries(sources.map(({ path, source }) => [path, digestOf(source)])),
@@ -1424,7 +1411,7 @@ export const startVisualServer = async (options) => {
                 // never `git commit`ed. It never asks the agent anything, so it is
                 // answered here directly rather than through the pending queue a
                 // poll would drain.
-                const { projectionId, positions, folded, unfolded } = event.payload;
+                const { projectionId, positions, folded, unfolded, routes: savedRoutes } = event.payload;
                 if (!views.some((view) => view.id === projectionId)) {
                     sendFrame(socket, {
                         kind: "layout-save-result",
@@ -1435,7 +1422,7 @@ export const startVisualServer = async (options) => {
                     });
                     return;
                 }
-                const path = `.yarramate/visual-layout/${projectionId}.yaml`;
+                const path = layoutSidecarPath(projectionId);
                 mkdirSync(layoutDir, { recursive: true });
                 writeFileSync(resolve(options.cwd, path), emitYaml({
                     format: "yarramate/visual-layout/v1",
@@ -1446,10 +1433,16 @@ export const startVisualServer = async (options) => {
                     // sidecar written by one host is read by the other.
                     ...(folded === undefined ? {} : { folded }),
                     ...(unfolded === undefined ? {} : { unfolded }),
+                    // The routes in force, beside the positions they were computed
+                    // for (ADR 0147); a save with nothing routed writes none.
+                    ...(savedRoutes === undefined ? {} : { routes: savedRoutes }),
                 }), "utf8");
                 rendered = {
                     ...rendered,
                     layouts: { ...rendered.layouts, [projectionId]: positions },
+                    ...(savedRoutes === undefined
+                        ? {}
+                        : { routes: { ...rendered.routes, [projectionId]: savedRoutes } }),
                     ...(folded === undefined && unfolded === undefined
                         ? {}
                         : {

package/dist/adapters/visual/wire.d.ts

@@ -1,6 +1,6 @@
 import type { CanvasGraph } from '../../graph-projection.js';
 import type { PatternMembership, PatternVacancy } from '../../compiler.js';
-import type { VISUAL_PROTOCOL_VERSION, VisualApplyResultPayload, VisualAuthority, VisualBrowserInput, VisualCapabilities, VisualChoicePresentPayload, VisualDiagnostic, VisualFilterResultPayload, VisualFreezeReason, VisualKindOption, VisualPatternOption, VisualLayoutPositions, VisualLayoutSaveResultPayload, VisualResponse, VisualTerminationReason, VisualViewSummary } from './protocol-contract.js';
+import type { VISUAL_PROTOCOL_VERSION, VisualApplyResultPayload, VisualAuthority, VisualBrowserInput, VisualCapabilities, VisualChoicePresentPayload, VisualDiagnostic, VisualFilterResultPayload, VisualFreezeReason, VisualKindOption, VisualPatternOption, VisualLayoutPositions, VisualLayoutRoutes, VisualLayoutSaveResultPayload, VisualResponse, VisualTerminationReason, VisualViewSummary } from './protocol-contract.js';
 /**
  * Transport shapes the session server and the browser application both speak.
  *
@@ -77,6 +77,14 @@ export interface VisualRenderedModel {
             readonly unfolded: readonly string[];
         };
     };
+    /**
+     * The routes each saved layout was drawing (ADR 0147), keyed by projection
+     * id. A sibling of `layouts` for the reason `folds` is: a layout entry is
+     * positions, and widening it would reach every reader of it.
+     */
+    readonly routes?: {
+        readonly [projectionId: string]: VisualLayoutRoutes;
+    };
     /**
      * Which subject fills which slot of which instance (ADR 0131), and which
      * slots nothing fills (#447), forwarded so the browser can draw containment

package/dist/notation/archimate.d.ts

@@ -55,7 +55,12 @@ export interface ConceptNotation extends ShapeMeta {
 }
 export declare const CONCEPT_NOTATION: readonly ConceptNotation[];
 export declare function conceptNotationOf(kindLabel: string): ConceptNotation | null;
-export declare function kindGlyphDataUriOf(kindLabel: string): string | null;
+/**
+ * The glyph as a data URI, drawn in `ink` - the notation's own by default, or
+ * the light stroke a dark ground needs (ADR 0148). The stroke is the only
+ * thing that varies; the strokes themselves are the notation's.
+ */
+export declare function kindGlyphDataUriOf(kindLabel: string, ink?: string): string | null;
 export interface ArrowNotation {
     readonly shape: 'none' | 'diamond' | 'triangle' | 'circle' | 'vee';
     readonly fill?: 'filled' | 'hollow';

package/dist/notation/archimate.js

@@ -38,10 +38,10 @@ export const ASPECT_SHAPES = {
 const KIND_SHAPE_OVERRIDES = {
     grouping: { borderStyle: 'dashed' },
 };
-function svg(body) {
+function svg(body, ink = INK) {
     return (`<svg xmlns="http://www.w3.org/2000/svg" width="${ICON_SIZE}" height="${ICON_SIZE}" ` +
         `viewBox="0 0 ${ICON_SIZE} ${ICON_SIZE}">` +
-        `<g fill="none" stroke="${INK}" stroke-width="1" stroke-linecap="round" stroke-linejoin="round">${body}</g>` +
+        `<g fill="none" stroke="${ink}" stroke-width="1" stroke-linecap="round" stroke-linejoin="round">${body}</g>` +
         `</svg>`);
 }
 function toDataUri(svgMarkup) {
@@ -205,9 +205,14 @@ const CONCEPT_NOTATION_BY_ID = Object.fromEntries(CONCEPT_NOTATION.map((row) =>
 export function conceptNotationOf(kindLabel) {
     return CONCEPT_NOTATION_BY_ID[kindLabel] ?? null;
 }
-export function kindGlyphDataUriOf(kindLabel) {
+/**
+ * The glyph as a data URI, drawn in `ink` - the notation's own by default, or
+ * the light stroke a dark ground needs (ADR 0148). The stroke is the only
+ * thing that varies; the strokes themselves are the notation's.
+ */
+export function kindGlyphDataUriOf(kindLabel, ink = INK) {
     const glyph = CONCEPT_NOTATION_BY_ID[kindLabel]?.glyph;
-    return glyph == null ? null : toDataUri(svg(glyph));
+    return glyph == null ? null : toDataUri(svg(glyph, ink));
 }
 // The 11 rows from `graph-canvas.tsx`'s ArchiMate edge selectors (Task 11).
 const RELATIONSHIP_STYLE = {

package/dist/schema-validation.d.ts

@@ -39,4 +39,5 @@ export declare const validateEvidence: ValidateFunction;
 export declare const validateCoreContract: ValidateFunction;
 export declare const validateAdapterMapping: ValidateFunction;
 export declare const validateCatalogue: ValidateFunction;
+export declare const validateVisualLayout: ValidateFunction;
 export declare const validateOperations: ValidateFunction;

package/dist/schema-validation.js

@@ -40,4 +40,5 @@ export const validateEvidence = generated.validateEvidence;
 export const validateCoreContract = generated.validateCoreContract;
 export const validateAdapterMapping = generated.validateAdapterMapping;
 export const validateCatalogue = generated.validateCatalogue;
+export const validateVisualLayout = generated.validateVisualLayout;
 export const validateOperations = generatedOperations.validateOperations;

package/dist/schema-validators.generated.d.ts

@@ -52,4 +52,10 @@ declare function validate74(data: any, { instancePath, parentData, parentDataPro
     instancePath?: string | undefined;
     rootData?: any;
 }): boolean;
+export declare const validateVisualLayout: typeof validate82;
+declare function validate82(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    dynamicAnchors?: {} | undefined;
+    instancePath?: string | undefined;
+    rootData?: any;
+}): boolean;
 export {};