@shortlink-org/portolan 0.1.0

package/src/likec4/flow-edges.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "../data";
+import { walkSteps } from "../catalog";
+import { hiddenStepIds } from "../flow/cross-context";
+import { drawnStepIds, pairEdgesToSteps } from "./flow-edges";
+
+describe("pairEdgesToSteps", () => {
+  it("pairs by position, both ways", () => {
+    const pairing = pairEdgesToSteps(
+      ["step-01", "step-02:par.01", "step-02:par.02"],
+      ["s1", "s2", "s3"],
+    );
+    expect(pairing.stepOf.get("step-02:par.01")).toBe("s2");
+    expect(pairing.edgeOf.get("s3")).toBe("step-02:par.02");
+  });
+
+  /**
+   * A length mismatch means the generator and the view have drifted. Guessing
+   * would light the wrong arrow, which is worse than lighting none, so the
+   * pairing is abandoned and highlighting simply stops.
+   */
+  it("abandons the pairing rather than guessing when the lists differ", () => {
+    const pairing = pairEdgesToSteps(["step-01"], ["s1", "s2"]);
+    expect(pairing.stepOf.size).toBe(0);
+    expect(pairing.edgeOf.size).toBe(0);
+  });
+});
+
+describe("drawnStepIds", () => {
+  it("lists every step of the full view, in rail order", () => {
+    for (const flow of catalog.flows) {
+      expect(drawnStepIds(flow, false), flow.slug).toEqual(
+        walkSteps(flow.steps).map((s) => s.id),
+      );
+    }
+  });
+
+  it("drops exactly what the cross-context view hides", () => {
+    for (const flow of catalog.flows) {
+      const hidden = hiddenStepIds(flow);
+      const drawn = drawnStepIds(flow, true);
+      expect(
+        drawn.some((id) => hidden.has(id)),
+        flow.slug,
+      ).toBe(false);
+      expect(drawn.length, flow.slug).toBe(
+        walkSteps(flow.steps).length - hidden.size,
+      );
+    }
+  });
+});

package/src/likec4/flow-edges.ts

@@ -0,0 +1,89 @@
+// Flow steps have catalog ids ("s6"); the LikeC4 edges that draw them have
+// generated ones ("step-04:par.01"). Nothing in the model carries the catalog
+// id across, so the two are paired by position.
+//
+// That is sound because it is the same walk twice: the generator emits steps in
+// the order walkSteps visits them — a step, then each branch of a parallel,
+// then each branch of an alt, then the body of a loop — and the view keeps that
+// order in its edge list. If the two lists ever differ in length the pairing is
+// abandoned rather than guessed at, and the diagram simply stops highlighting.
+
+import type { Flow } from "../catalog";
+import { walkSteps } from "../catalog";
+import { hiddenStepIds } from "../flow/cross-context";
+
+export interface EdgeStepPairing {
+  /** LikeC4 edge id -> catalog step id */
+  stepOf: Map<string, string>;
+  /** catalog step id -> LikeC4 edge id */
+  edgeOf: Map<string, string>;
+}
+
+export const EMPTY_PAIRING: EdgeStepPairing = {
+  stepOf: new Map(),
+  edgeOf: new Map(),
+};
+
+export function pairEdgesToSteps(
+  edgeIds: readonly string[],
+  stepIds: readonly string[],
+): EdgeStepPairing {
+  if (edgeIds.length !== stepIds.length) return EMPTY_PAIRING;
+  const stepOf = new Map<string, string>();
+  const edgeOf = new Map<string, string>();
+  edgeIds.forEach((edgeId, i) => {
+    const stepId = stepIds[i];
+    if (stepId === undefined) return;
+    stepOf.set(edgeId, stepId);
+    edgeOf.set(stepId, edgeId);
+  });
+  return { stepOf, edgeOf };
+}
+
+/**
+ * The frames an edge sits inside, outermost first.
+ *
+ * LikeC4 names an edge by the path that reaches it — "step-07:alt.02:else.01:
+ * break.01" is the first message of the break inside the second branch of the
+ * alt at step 7 — and every frame on the way has a node of its own under the
+ * prefix that names it. So the containment the app needs is already written in
+ * the id, and reading it back out beats pairing a second pair of trees.
+ */
+export function frameAncestors(edgeId: string): string[] {
+  const parts = edgeId.split(".");
+  const out: string[] = [];
+  for (let i = 1; i < parts.length; i += 1) {
+    out.push(parts.slice(0, i).join("."));
+  }
+  return out;
+}
+
+/**
+ * Frames none of whose edges are on the chosen path.
+ *
+ * A frame with even one live edge inside it stays lit: the alt itself still
+ * happens on this path, it is the arms not taken that do not. Only a frame
+ * that contributes nothing at all is hidden.
+ */
+export function offPathFrameIds(
+  edgeIds: readonly string[],
+  onPath: ReadonlySet<string>,
+): string[] {
+  const live = new Set<string>();
+  const seen: string[] = [];
+  for (const edgeId of edgeIds) {
+    for (const frame of frameAncestors(edgeId)) {
+      if (!seen.includes(frame)) seen.push(frame);
+      if (onPath.has(edgeId)) live.add(frame);
+    }
+  }
+  return seen.filter((frame) => !live.has(frame));
+}
+
+/** The step ids a flow view draws, in the order its edges are emitted. */
+export function drawnStepIds(flow: Flow, crossOnly: boolean): string[] {
+  const steps = walkSteps(flow.steps);
+  if (!crossOnly) return steps.map((s) => s.id);
+  const hidden = hiddenStepIds(flow);
+  return steps.filter((s) => !hidden.has(s.id)).map((s) => s.id);
+}

package/src/likec4/frame-theme.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildFrameCss,
+  buildFocusedPathCss,
+  buildWalkthroughCss,
+} from "./frame-theme";
+
+describe("buildFrameCss", () => {
+  const css = buildFrameCss();
+
+  it("retunes every subflow keyword the generator can emit", () => {
+    // `break` is the one portolan's own generator writes, for a terminal alt
+    // branch; the others come with LikeC4's vocabulary.
+    for (const keyword of ["alt", "par", "loop", "break"]) {
+      expect(css).toContain(`--colors-subflow-${keyword}:`);
+      expect(css).toContain(`--colors-subflow-${keyword}-border:`);
+      expect(css).toContain(`--colors-subflow-${keyword}-text:`);
+    }
+  });
+
+  it("paints only in portolan tokens, so a theme swap carries the canvas", () => {
+    const values = css
+      .split("\n")
+      .filter((line) => line.includes(":") && !line.includes("{"))
+      .map((line) => line.slice(line.indexOf(":") + 1));
+    expect(values.length).toBeGreaterThan(0);
+    for (const value of values) {
+      expect(value).toMatch(/var\(--(surface|surface-2|border|border-strong|fg-muted)\)/);
+    }
+  });
+
+  it("scopes itself to the canvas rather than the document", () => {
+    expect(css.startsWith(".react-flow {")).toBe(true);
+  });
+});
+
+describe("buildFocusedPathCss", () => {
+  it("says nothing when every edge, label, node and frame is on the path", () => {
+    expect(buildFocusedPathCss([], [], [], [])).toBe("");
+  });
+
+  it("hides off-path edges, labels, participants and empty frames", () => {
+    const css = buildFocusedPathCss(
+      ["step-08:alt.02:else.01"],
+      [8],
+      ["unused_provider"],
+      ["step-07:alt.02:else"],
+    );
+    expect(css).toContain('.react-flow__edge[data-id="step-08:alt.02:else.01"]');
+    expect(css).toContain(".react-flow__edgelabel-renderer > :nth-child(8)");
+    expect(css).toContain('.react-flow__node[data-id="unused_provider"]');
+    expect(css).toContain('[data-id="step-07:alt.02:else"]');
+    expect(css).toContain("display: none");
+  });
+
+  it("escapes a quote rather than letting it close the selector", () => {
+    expect(buildFocusedPathCss(['a"b'], [], [], [])).toContain('data-id="a\\"b"');
+  });
+});
+
+describe("buildWalkthroughCss", () => {
+  const css = buildWalkthroughCss();
+
+  it("hides the panel LikeC4 opens over the canvas during playback", () => {
+    expect(css).toContain("display: none");
+  });
+
+  it("aims only at a full-height box in the diagram's top-left corner", () => {
+    // Narrow on purpose: anything looser would take the canvas with it.
+    expect(css).toContain(".likec4-root >");
+    expect(css).toContain(".pos_absolute");
+    expect(css).toContain(".top_0");
+    expect(css).toContain(".left_0");
+    expect(css).toContain(".h_100cqh");
+  });
+});

package/src/likec4/frame-theme.ts

@@ -0,0 +1,101 @@
+// The seam between two renderers, painted over.
+//
+// LikeC4 draws the alt/par/loop frames of a sequence in its own palette —
+// saturated fills, one hue per keyword — which inside portolan reads as the
+// loudest thing on the canvas. It is the wrong thing to be loudest. A frame
+// says *under what condition*, and the arrows say *what happens*; the arrows
+// already carry status colour, and a frame competing with them for the same
+// glance costs the reader the one signal the picture is for.
+//
+// So the frames are turned down to the app's own surfaces. This is not a hack
+// around a missing prop: `--colors-subflow-*` are the tokens LikeC4 publishes
+// for exactly this, and every value below is a portolan token, so a theme swap
+// carries the canvas with it.
+
+/** Every subflow keyword LikeC4 paints, including the ones our generator emits. */
+const KEYWORDS = ["alt", "par", "loop", "break", "opt", "try"] as const;
+
+/** Frame fill: present enough to bound the branch, quiet enough to sit under it. */
+const FILL = "color-mix(in srgb, var(--surface) 60%, transparent)";
+/** The keyword badge and the header strip, one step up from the fill. */
+const HEADER = "color-mix(in srgb, var(--surface-2) 70%, transparent)";
+
+/**
+ * The stylesheet, as a string, for the diagram's own root. Scoped to
+ * `.react-flow` because that is the one class React Flow guarantees and the
+ * custom properties inherit from it down to every frame inside.
+ */
+export function buildFrameCss(): string {
+  const vars = KEYWORDS.flatMap((keyword) => [
+    `--colors-subflow-${keyword}: ${FILL};`,
+    `--colors-subflow-${keyword}-border: var(--border);`,
+    `--colors-subflow-${keyword}-header: ${HEADER};`,
+    `--colors-subflow-${keyword}-hovered: var(--surface-2);`,
+    `--colors-subflow-${keyword}-label: var(--border-strong);`,
+    `--colors-subflow-${keyword}-text: var(--fg-muted);`,
+  ]);
+  // The walkthrough paints parallel frames from a token of its own, and a
+  // parallel that changes colour the moment playback starts reads as a
+  // different frame rather than the same one being visited.
+  vars.push("--colors-likec4-walkthrough-parallel-frame: " + FILL + ";");
+  return `.react-flow {\n  ${vars.join("\n  ")}\n}`;
+}
+
+/**
+ * LikeC4's own sequence outline, hidden.
+ *
+ * Starting a walkthrough opens a panel down the left of the canvas listing the
+ * steps and marking the active one — which is, to the pixel, what the rail
+ * beside the canvas already is. Two outlines is one too many, and this is the
+ * one lying on top of the picture.
+ *
+ * There is no prop for it, so it goes by selector. The class names are Panda's
+ * atomic ones, which are derived from the declarations rather than hand-named,
+ * so a LikeC4 upgrade that restyles the panel will bring it back — visibly, as
+ * a panel that reappeared, rather than silently as something broken. The
+ * combination is narrow enough that nothing else in the canvas matches it: a
+ * full-height box pinned to the top-left corner of the diagram root.
+ *
+ * Its width is not reclaimed. LikeC4 frames each walkthrough step inside the
+ * canvas MINUS this panel, so hiding it leaves that band empty rather than
+ * giving it to the diagram — the same space the panel would have taken, just
+ * not covering anything.
+ */
+export function buildWalkthroughCss(): string {
+  return [
+    ".likec4-root > .pos_absolute.top_0.left_0.h_100cqh {",
+    "  display: none;",
+    "}",
+  ].join("\n");
+}
+
+/**
+ * Removes everything outside the executable path the reader selected.
+ *
+ * The default canvas remains the complete decision tree. Once a path is
+ * chosen, keeping its siblings as pale scaffolding defeats the choice on the
+ * large provider graphs this control is for, so both their arrows and their
+ * now-empty frames leave the picture.
+ */
+export function buildFocusedPathCss(
+  edgeIds: readonly string[],
+  edgeLabelPositions: readonly number[],
+  nodeIds: readonly string[],
+  frameIds: readonly string[],
+): string {
+  const selectors = [
+    ...edgeIds.map((id) => `.react-flow__edge[data-id="${cssQuote(id)}"]`),
+    ...edgeLabelPositions.map(
+      (position) => `.react-flow__edgelabel-renderer > :nth-child(${position})`,
+    ),
+    ...nodeIds.map((id) => `.react-flow__node[data-id="${cssQuote(id)}"]`),
+    ...frameIds.map((id) => `.react-flow__node[data-id="${cssQuote(id)}"]`),
+  ];
+  if (selectors.length === 0) return "";
+  return `${selectors.join(",\n")} {\n  display: none;\n}`;
+}
+
+/** CSS string escape for an attribute value. */
+function cssQuote(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}

package/src/likec4/highlight-css.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { buildHighlightCss } from "./highlight-css";
+
+describe("buildHighlightCss", () => {
+  it("writes nothing when nothing is selected", () => {
+    expect(buildHighlightCss([], [])).toBe("");
+  });
+
+  it("dims the other nodes and outlines the one", () => {
+    const css = buildHighlightCss(["shop.oms"], []);
+    expect(css).toContain('.react-flow__node:not([data-id="shop.oms"])');
+    expect(css).toContain('.react-flow__node[data-id="shop.oms"]');
+    expect(css).toContain("outline: 2px solid var(--accent)");
+  });
+
+  /**
+   * Nodes and edges are dimmed independently. Lighting a step must not grey out
+   * the lanes it runs between, so an edge highlight leaves the nodes alone.
+   */
+  it("keeps the two categories apart", () => {
+    const edgesOnly = buildHighlightCss([], ["step-01", "step-02"]);
+    expect(edgesOnly).not.toContain(".react-flow__node");
+    expect(edgesOnly).toContain(
+      '.react-flow__edge:not([data-id="step-01"]):not([data-id="step-02"])',
+    );
+  });
+
+  it("touches nothing but opacity and outline, so no layout can move", () => {
+    const css = buildHighlightCss(["a"], ["b"]);
+    for (const rule of css.split("\n")) {
+      const body = rule.slice(rule.indexOf("{") + 1, rule.lastIndexOf("}"));
+      for (const decl of body.split(";")) {
+        const property = decl.split(":")[0]?.trim();
+        if (!property) continue;
+        expect([
+          "opacity",
+          "outline",
+          "outline-offset",
+          "transition",
+        ]).toContain(property);
+      }
+    }
+  });
+
+  it("escapes a quote in an id rather than breaking out of the selector", () => {
+    const css = buildHighlightCss(['a"b'], []);
+    expect(css).toContain('[data-id="a\\"b"]');
+  });
+});

package/src/likec4/highlight-css.ts

@@ -0,0 +1,52 @@
+// Marking the selection on a LikeC4 canvas is a paint job, nothing more.
+//
+// The diagram is laid out ahead of time and rendered inside a shadow root, so
+// the one safe way to mark something in it is a stylesheet placed inside that
+// root, keyed on the `data-id` React Flow already puts on every node and edge.
+// No prop the layout depends on is touched, which is what keeps a selection
+// from nudging the picture.
+
+const NODE = ".react-flow__node";
+const EDGE = ".react-flow__edge";
+
+/** CSS string escape for an attribute value. */
+function q(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/** `:not()` chained rather than given a list, for older WebKit. */
+function excluding(base: string, ids: readonly string[]): string {
+  return base + ids.map((id) => `:not([data-id="${q(id)}"])`).join("");
+}
+
+function matching(base: string, ids: readonly string[]): string {
+  return ids.map((id) => `${base}[data-id="${q(id)}"]`).join(", ");
+}
+
+/**
+ * Dims everything that is not selected and outlines what is. Dimming is done
+ * per category: highlighting a step must not grey out the lanes it runs
+ * between, and highlighting a service must not grey out the arrows into it.
+ */
+export function buildHighlightCss(
+  nodeIds: readonly string[],
+  edgeIds: readonly string[],
+): string {
+  const rules: string[] = [];
+
+  if (nodeIds.length > 0) {
+    rules.push(
+      `${excluding(NODE, nodeIds)} { opacity: 0.3; transition: opacity 120ms ease; }`,
+      `${matching(NODE, nodeIds)} { outline: 2px solid var(--accent); outline-offset: 3px; }`,
+    );
+  }
+
+  if (edgeIds.length > 0) {
+    rules.push(
+      `${excluding(EDGE, edgeIds)} { opacity: 0.18; transition: opacity 120ms ease; }`,
+      `${matching(EDGE, edgeIds)} { opacity: 1; }`,
+    );
+  }
+
+  return rules.join("\n");
+}

package/src/likec4/ids.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { catalog } from "../testing/estate";
+// The generated sources are generated from the estate the app ships, so the
+// block that reads them off disk is held against that one and not against the
+// frozen fixture the id rules are checked with.
+import { catalog as shipped, catalogProfiles } from "../data";
+import {
+  CONTAINERS_VIEW,
+  LANDSCAPE_VIEW,
+  allViewIds,
+  contextViewId,
+  eventFqn,
+  flowCrossViewId,
+  flowViewId,
+  fqn,
+  participantFqn,
+  profileContainersViewId,
+  profileLandscapeViewId,
+  safeId,
+  serviceInsideViewId,
+  serviceViewId,
+} from "./ids";
+
+describe("safeId", () => {
+  it("replaces characters LikeC4 identifiers cannot hold", () => {
+    expect(safeId("fraud-scoring")).toBe("fraud_scoring");
+    expect(safeId("price-list")).toBe("price_list");
+    expect(safeId("analytics-sink")).toBe("analytics_sink");
+  });
+
+  it("escapes a word the grammar has taken", () => {
+    // An aggregate called `order` is what a shop calls its aggregate, and a
+    // model that declares one under that name does not parse at all.
+    expect(safeId("order")).toBe("_order");
+    expect(safeId("style")).toBe("_style");
+    expect(safeId("view")).toBe("_view");
+  });
+
+  it("never starts an identifier with a digit", () => {
+    expect(safeId("2fa")).toBe("_2fa");
+  });
+
+  it("leaves already-safe ids alone", () => {
+    expect(safeId("OrderPlaced")).toBe("OrderPlaced");
+  });
+});
+
+describe("fqn", () => {
+  it("keeps catalog dots as LikeC4 hierarchy separators", () => {
+    expect(fqn("shop.cart.basket")).toBe("shop.cart.basket");
+    expect(eventFqn("shop.cart.basket.ItemAdded")).toBe(
+      "shop.cart.basket.ItemAdded",
+    );
+  });
+
+  it("escapes only the segment that needs it", () => {
+    // The shop's aggregate is called `order`, and `order` is a word of the
+    // LikeC4 grammar; the segments around it are left alone.
+    expect(fqn("shop.oms.order")).toBe("shop.oms._order");
+    expect(eventFqn("shop.oms.order.OrderPlaced")).toBe(
+      "shop.oms._order.OrderPlaced",
+    );
+  });
+
+  it("sanitises each segment independently", () => {
+    expect(fqn("shop.price-list")).toBe("shop.price_list");
+  });
+
+  it("maps bare participants to root elements", () => {
+    expect(participantFqn("bus")).toBe("bus");
+    expect(participantFqn("fraud-scoring")).toBe("fraud_scoring");
+  });
+
+  it("keeps dots hierarchical for services but literal for root participants", () => {
+    expect(
+      participantFqn({ id: "shop.oms", kind: "service", context: "shop" }),
+    ).toBe("shop.oms");
+    expect(
+      participantFqn({
+        id: "river.order-jobs",
+        kind: "broker",
+        context: null,
+      }),
+    ).toBe("river_order_jobs");
+  });
+});
+
+describe("view ids", () => {
+  it("derives ids from catalog slugs, never from dotted ids", () => {
+    expect(flowViewId("checkout")).toBe("flow_checkout");
+    expect(flowCrossViewId("checkout")).toBe("flow_checkout_cross");
+    expect(contextViewId("shop")).toBe("ctx_shop");
+    expect(serviceViewId("shop.oms")).toBe("svc_shop_oms");
+    expect(serviceInsideViewId("shop.oms")).toBe("svc_shop_oms_inside");
+  });
+
+  it("is unique across the whole catalog", () => {
+    const ids = allViewIds(catalog);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("covers the landscape, the containers, every context, both views of every service and both of every flow", () => {
+    const ids = allViewIds(catalog);
+    const services = catalog.contexts.flatMap((c) => c.services);
+    expect(ids).toHaveLength(
+      2 +
+        catalog.contexts.length +
+        services.length * 2 +
+        catalog.flows.length * 2,
+    );
+    // The three C4 levels: the estate, its containers, a context, and a
+    // service opened up.
+    expect(ids).toContain(LANDSCAPE_VIEW);
+    expect(ids).toContain(CONTAINERS_VIEW);
+    expect(ids).toContain(contextViewId("shop"));
+    expect(ids).toContain(serviceInsideViewId("shop.oms"));
+  });
+
+  it("produces only valid LikeC4 identifiers", () => {
+    for (const id of allViewIds(catalog)) {
+      expect(id, id).toMatch(/^[A-Za-z_][A-Za-z0-9_]*$/);
+    }
+  });
+});
+
+describe("generated sources match the ids the app asks for", () => {
+  const views = readFileSync("likec4/views.c4", "utf8");
+
+  /** Every `view x {` and `dynamic view x {` declared in the generated source. */
+  const declared = [
+    ...views.matchAll(/^\s*(?:dynamic\s+)?view\s+([A-Za-z_][A-Za-z0-9_]*)\b/gm),
+  ].map((m) => m[1] as string);
+
+  it("declares every selected-catalog view and every profile entry point", () => {
+    const askedFor = [
+      ...allViewIds(shipped),
+      ...catalogProfiles.flatMap((profile) => [
+        profileLandscapeViewId(profile.id),
+        profileContainersViewId(profile.id),
+      ]),
+    ];
+    expect(new Set(declared).size).toBe(declared.length);
+    for (const id of askedFor) expect(declared).toContain(id);
+  });
+
+  it("declares the landscape and the containers once each, the only views with fixed names", () => {
+    expect(declared.filter((id) => id === LANDSCAPE_VIEW)).toHaveLength(1);
+    expect(declared.filter((id) => id === CONTAINERS_VIEW)).toHaveLength(1);
+  });
+});

package/src/likec4/ids.ts

@@ -0,0 +1,115 @@
+// LikeC4 identifiers derived from catalog ids. Pure and deterministic: the
+// generator and the app must agree on every name without sharing state.
+
+import type {
+  Catalog,
+  BoundedContext,
+  Event,
+  Flow,
+  Participant,
+  Service,
+} from "../catalog";
+import reserved from "./reserved.json";
+
+/**
+ * Words the LikeC4 grammar has taken. An aggregate called `order` is an
+ * ordinary thing to find in a shop, and a model that declares one does not
+ * parse: the parser reads the keyword and expects the block to end. Whether a
+ * given word breaks depends on where it lands, so every word the grammar knows
+ * is escaped rather than the subset that happens to break today.
+ *
+ * `src/likec4/reserved.json` is read out of the installed grammar:
+ *
+ *   [...bundle.matchAll(/"Keyword","value":"([A-Za-z_][A-Za-z0-9_]*)"/g)]
+ *
+ * over `node_modules/likec4/dist/chunks/node.mjs`. It is a copy, so it can go
+ * stale when likec4 is upgraded; `npm run likec4:validate` is what says so.
+ */
+const RESERVED = new Set<string>(reserved);
+
+/**
+ * LikeC4 identifiers allow letters, digits and underscore, cannot lead with a
+ * digit, and cannot be a word of the grammar. One escape for all three: a
+ * leading underscore, which LikeC4 takes and no catalog id starts with.
+ */
+export function safeId(raw: string): string {
+  const cleaned = raw.replace(/[^A-Za-z0-9_]/g, "_");
+  return /^[0-9]/.test(cleaned) || RESERVED.has(cleaned) ? `_${cleaned}` : cleaned;
+}
+
+/** A catalog id like "shop.oms.basket" becomes the LikeC4 path "shop.oms.basket". */
+export function fqn(catalogId: string): string {
+  return catalogId.split(".").map(safeId).join(".");
+}
+
+export const eventFqn = (event: Event | string): string =>
+  fqn(typeof event === "string" ? event : event.id);
+
+/**
+ * Flow participants are either catalog services (dotted, hierarchical) or
+ * elements at the model root. A root id may itself contain a dot — for example
+ * `river.orders` — and that dot is data, not LikeC4 containment.
+ */
+export function participantFqn(participant: Participant | string): string {
+  const id = typeof participant === "string" ? participant : participant.id;
+  return typeof participant !== "string" && participant.kind !== "service"
+    ? safeId(id)
+    : fqn(id);
+}
+
+// --- view ids -------------------------------------------------------------
+
+/**
+ * C4 level 1, and one of the two views with a name of its own: the estate has
+ * one landscape, so nothing is derived from an id.
+ */
+export const LANDSCAPE_VIEW = "landscape";
+
+/**
+ * C4 level 2, the whole estate: every service inside its context, the store
+ * each keeps its state in, the brokers between them, and the same outsiders
+ * as the landscape. The other fixed name, for the same reason.
+ */
+export const CONTAINERS_VIEW = "containers";
+
+/** Whole-estate views narrowed to one configured catalog profile. */
+export const profileLandscapeViewId = (profile: string): string =>
+  `${LANDSCAPE_VIEW}_${safeId(profile)}`;
+export const profileContainersViewId = (profile: string): string =>
+  `${CONTAINERS_VIEW}_${safeId(profile)}`;
+
+/** C4 level 2, one context: its services, their stores, and the brokers they use. */
+export const contextViewId = (context: BoundedContext | string): string =>
+  `ctx_${safeId(typeof context === "string" ? context : context.id)}`;
+
+/** C4 level 2, one service: the service as a box among the ones it touches. */
+export const serviceViewId = (service: Service | string): string =>
+  `svc_${safeId(typeof service === "string" ? service : service.id)}`;
+
+/** C4 level 3, the same service opened: its aggregates and its stores. */
+export const serviceInsideViewId = (service: Service | string): string =>
+  `${serviceViewId(service)}_inside`;
+
+/** Every flow has two declared views: the whole sequence, and the crossings only. */
+export const flowViewId = (flow: Flow | string): string =>
+  `flow_${safeId(typeof flow === "string" ? flow : flow.slug)}`;
+
+export const flowCrossViewId = (flow: Flow | string): string =>
+  `${flowViewId(flow)}_cross`;
+
+/** Every view id the generator is expected to emit, in a stable order. */
+export function allViewIds(catalog: Catalog): string[] {
+  const out: string[] = [LANDSCAPE_VIEW, CONTAINERS_VIEW];
+  for (const context of catalog.contexts) {
+    out.push(contextViewId(context));
+    for (const service of context.services) {
+      out.push(serviceViewId(service));
+      out.push(serviceInsideViewId(service));
+    }
+  }
+  for (const flow of catalog.flows) {
+    out.push(flowViewId(flow));
+    out.push(flowCrossViewId(flow));
+  }
+  return out;
+}