@brignano/driftwood 0.0.1 → 0.1.0

package/README.md

@@ -23,8 +23,8 @@ Nobody owns the middle. driftwood is the middle.
 
 | Engine | Needs | Output |
 |---|---|---|
-| `graphviz` (native) | `dot` on PATH | SVG. Preferred when present — faster on very large graphs, honours a site's own Graphviz build |
-| `graphviz` (WASM) | **nothing — bundled** | SVG. The default |
+| `graphviz` (native) | `dot` on PATH | SVG, icons and all. Preferred when present — faster on very large graphs, honours a site's own Graphviz build |
+| `graphviz` (WASM) | **nothing — bundled** | SVG with category icons. The default |
 | `dot` | nothing | DOT source (it's just text) |
 | `mermaid` | nothing | Mermaid, renders natively in GitHub |
 
@@ -71,13 +71,15 @@ flowchart LR
         REC["Reconciler<br/>declared vs observed"]
     end
     subgraph Renderers["Renderers — present"]
-        MMD["Mermaid"]
+        GV["Graphviz SVG"]
+        MMD["Mermaid · DOT"]
         LATER["2D live · 3D<br/>(not yet)"]
     end
     TF --> REC
     SOON -.-> REC
     MODEL --> REC
     REC -->|"divergence"| MODEL
+    MODEL --> GV
     MODEL --> MMD
     MODEL -.-> LATER
 ```
@@ -98,11 +100,13 @@ Requires Node 20+. Runtime dependencies are `commander`, `yaml`, `zod`, and `@hp
 ### Import a model from Terraform state
 
 ```bash
-npx tsx src/cli.ts import terraform examples/aws-config.tfstate.json \
-  --name aws-config -o examples/architecture.yaml
+npx tsx src/cli.ts import terraform examples/orders-platform.tfstate.json \
+  --name orders-platform -o examples/architecture.yaml
 ```
 
-Entity ids are Terraform addresses (`aws_s3_bucket.emails`). That's deliberate: the address is stable across plans, readable in a diff, and sidesteps the identity-resolution problem that kills CMDBs. Edges come from Terraform's own `dependencies`.
+Entity ids are Terraform addresses (`aws_s3_bucket.assets`). That's deliberate: the address is stable across plans, readable in a diff, and sidesteps the identity-resolution problem that kills CMDBs. Edges come from Terraform's own `dependencies`.
+
+The worked example in `examples/` is a fictional e-commerce platform — CloudFront and Route 53 at the edge, an ALB in front of two ECS services, Postgres, Redis, DynamoDB and S3 behind them, and an SQS/SNS order pipeline with a Lambda worker. 45 resources: enough that the view mechanism is doing real work rather than decorating a diagram that fits on a page anyway.
 
 ### Validate
 
@@ -115,54 +119,103 @@ Catches schema errors, duplicate ids, edges pointing at entities that don't exis
 ### Render
 
 ```bash
-npx tsx src/cli.ts render examples/architecture.yaml --view email
+npx tsx src/cli.ts render examples/architecture.yaml --view app -o app.svg
 ```
 
+![The app view: an ALB listener and target group feeding two ECS services and their task definitions](docs/app.svg)
+
+Nodes are drawn with a category icon, the entity name, and its `kind` underneath. The icons are **drawn in this repo and chosen by category** — database, queue, load balancer — not by vendor: no icon pack to install, nothing to license, and one glyph that fits an RDS instance, a Cloud SQL instance and an on-prem Postgres alike. Colour groups the categories into families (edge, compute, data, messaging, security), so a diagram reads as a few zones instead of thirty unrelated boxes. Use `--no-icons` for plain boxes.
+
+The icons are inlined into the SVG rather than handed to Graphviz as `image=` attributes, because the native `dot` binary resolves those as filesystem paths — a `data:` URI would work on the WASM tier and break on the native one. Post-processing the SVG means both tiers draw the same picture, and the result stays self-contained — no external references, no base64 bloat.
+
+Every image in this README is generated from `examples/architecture.yaml` by `npm run docs`, and CI re-runs it and fails if the result differs from what is committed. A stale picture of your own output is worse than no picture, so the renders are checked against their source rather than trusted — the drift gate's own argument, one level up.
+
+The `async` view through Mermaid, which renders natively in a pull request:
+
+<!-- generated:async -->
 ```mermaid
 flowchart LR
     subgraph n_lambda["lambda"]
-        n_aws_lambda_function_email_forwarder["email-forwarder<br/>aws_lambda_function"]
+        n_aws_lambda_event_source_mapping_orders[/"orders<br/>aws_lambda_event_source_mapping"/]
+        n_aws_lambda_function_order_worker["shop-order-worker<br/>aws_lambda_function"]
     end
-    subgraph n_s3["s3"]
-        n_aws_s3_bucket_emails[("brignano.io-emails<br/>aws_s3_bucket")]
+    subgraph n_sns["sns"]
+        n_aws_sns_topic_subscription_orders[/"orders<br/>aws_sns_topic_subscription"/]
+        n_aws_sns_topic_order_events[/"shop-order-events<br/>aws_sns_topic"/]
     end
-    subgraph n_ses["ses"]
-        n_aws_ses_receipt_rule_set_main["main<br/>aws_ses_receipt_rule_set"]
-        n_aws_ses_receipt_rule_archive["archive-hi<br/>aws_ses_receipt_rule"]
-        n_aws_ses_receipt_rule_forward["forward-hi<br/>aws_ses_receipt_rule"]
-        n_aws_ses_receipt_rule_noreply["bounce-noreply<br/>aws_ses_receipt_rule"]
+    subgraph n_sqs["sqs"]
+        n_aws_sqs_queue_orders[/"shop-orders<br/>aws_sqs_queue"/]
+        n_aws_sqs_queue_orders_dlq[/"shop-orders-dlq<br/>aws_sqs_queue"/]
     end
-    n_aws_lambda_function_email_forwarder --> n_aws_s3_bucket_emails
-    n_aws_ses_receipt_rule_archive --> n_aws_s3_bucket_emails
-    n_aws_ses_receipt_rule_archive --> n_aws_ses_receipt_rule_set_main
-    n_aws_ses_receipt_rule_forward --> n_aws_lambda_function_email_forwarder
-    n_aws_ses_receipt_rule_forward --> n_aws_ses_receipt_rule_set_main
-    n_aws_ses_receipt_rule_noreply --> n_aws_ses_receipt_rule_set_main
+    n_aws_lambda_event_source_mapping_orders --> n_aws_lambda_function_order_worker
+    n_aws_lambda_event_source_mapping_orders --> n_aws_sqs_queue_orders
+    n_aws_lambda_function_order_worker --> n_aws_sqs_queue_orders
+    n_aws_sns_topic_subscription_orders --> n_aws_sns_topic_order_events
+    n_aws_sns_topic_subscription_orders --> n_aws_sqs_queue_orders
+    n_aws_sqs_queue_orders --> n_aws_sqs_queue_orders_dlq
+    class n_aws_lambda_event_source_mapping_orders f_messaging;
+    class n_aws_lambda_function_order_worker f_compute;
+    class n_aws_sns_topic_subscription_orders f_messaging;
+    class n_aws_sns_topic_order_events f_messaging;
+    class n_aws_sqs_queue_orders f_messaging;
+    class n_aws_sqs_queue_orders_dlq f_messaging;
+    classDef f_compute fill:#fffbeb,stroke:#d97706,color:#0f172a;
+    classDef f_messaging fill:#f5f3ff,stroke:#7c3aed,color:#0f172a;
 ```
+<!-- /generated:async -->
+
+Mermaid has no icon primitive, so it maps the *same* categorisation onto shapes and colours — a queue must not be a queue in one engine and a cylinder in the other, or the two pictures stop describing the same system.
+
+#### The rest of the views
+
+| View | What it scopes to | File |
+|---|---|---|
+| `edge` | Route 53, CloudFront, ACM, WAF, the ALB | [svg](docs/edge.svg) |
+| `app` | Load balancer through to the ECS services | [svg](docs/app.svg) |
+| `data` | Postgres, Redis, DynamoDB, S3 | [svg](docs/data.svg) |
+| `async` | The SQS/SNS/Lambda order pipeline | [svg](docs/async.svg) |
+| `network` | VPC, subnets, security groups, NAT | [svg](docs/network.svg) |
+| `context` | Everything, minus IAM and CloudWatch noise | [svg](docs/context.svg) |
 
-**Views exist from v1, not as a later optimization.** Flat Mermaid becomes unreadable past roughly 150 nodes, and any real enterprise graph blows through that immediately. A view is a scoped slice matching entity ids or groups, with a trailing `*` wildcard.
+**Views exist from v1, not as a later optimization.** Flat Mermaid becomes unreadable past roughly 150 nodes, and any real enterprise graph blows through that immediately. A view is a scoped slice matching entity ids or groups, with a trailing `*` wildcard. The example model ships six — `context`, `edge`, `app`, `data`, `async`, `network` — and even at 45 entities the difference between a view and the whole graph is the difference between a diagram and a wall.
 
 ### Reconcile — the point of the whole thing
 
 ```bash
 npx tsx src/cli.ts reconcile examples/architecture.yaml \
-  --terraform examples/aws-config.drifted.tfstate.json
+  --terraform examples/orders-platform.drifted.tfstate.json
 ```
 
+Two resources created by hand during an incident, one bucket deleted, one database renamed:
+
 ```markdown
 ## Architecture drift detected
 
 ### Present in infrastructure, missing from the model (2)
-- `aws_cloudfront_distribution.cdn` - aws_cloudfront_distribution (d123.cloudfront.net)
-- `aws_sqs_queue.dlq` - aws_sqs_queue (email-forwarder-dlq)
+
+- `aws_elasticache_replication_group.sessions_failover` - aws_elasticache_replication_group (shop-sessions-ha)
+- `aws_sqs_queue.payments` - aws_sqs_queue (shop-payments)
 
 ### Declared in the model, not found in infrastructure (1)
-- `aws_ses_receipt_rule.noreply` - aws_ses_receipt_rule (bounce-noreply)
+
+- `aws_s3_bucket.uploads` - aws_s3_bucket (shop-example-com-uploads)
+
+### Changed (1)
+
+| Entity | Field | Declared | Observed |
+|---|---|---|---|
+| `aws_db_instance.orders` | name | shop-orders-prod | shop-orders-prod-v2 |
 
 ### Relationships
-- **added** `aws_cloudfront_distribution.cdn` -> `aws_s3_bucket.emails`
-- **added** `aws_sqs_queue.dlq` -> `aws_lambda_function.email_forwarder`
-- **removed** `aws_ses_receipt_rule.noreply` -> `aws_ses_receipt_rule_set.main`
+
+- **added** `aws_elasticache_replication_group.sessions_failover` -> `aws_security_group.data`
+- **added** `aws_elasticache_replication_group.sessions_failover` -> `aws_subnet.private_a`
+- **added** `aws_sqs_queue.payments` -> `aws_kms_key.data`
+- **removed** `aws_iam_role_policy.order_worker` -> `aws_s3_bucket.uploads`
+- **removed** `aws_lambda_function.order_worker` -> `aws_s3_bucket.uploads`
+- **removed** `aws_s3_bucket.uploads` -> `aws_kms_key.data`
+
+_Ignored by policy: 1 entities, 0 edges._
 ```
 
 Exits **1** on drift and **0** when clean, so it works directly as a CI gate. Output is markdown because its destination is a pull request body.
@@ -264,20 +317,23 @@ src/
   providers/dynatrace.ts runtime — Smartscape topology, read-only
   render/types.ts        the renderer extension point (probe + render)
   render/select.ts       shared view scoping
+  render/icons.ts        category icons, the kind -> icon/colour table, SVG injection
   render/mermaid.ts      always available
   render/dot.ts          DOT source, always available
   render/graphviz.ts     SVG via native dot or WASM, with tier detection
   reconcile/index.ts     declared vs observed -> drift report
   config.ts              driftwood.config.yaml
   cli.ts                 validate · render · engines · providers · import · reconcile
-examples/                a worked AWS example, a drifted copy, and a config
+examples/                a worked 45-resource AWS platform, a drifted copy, and a config
+scripts/render-docs.ts   regenerates docs/ and the README's embedded render
+docs/                    committed renders of the example, kept current by CI
 .claude/skills/          add-provider and add-renderer walkthroughs for agents
 ```
 
 ## Development
 
 ```bash
-npm test        # 76 tests
+npm test        # 98 tests
 npm run typecheck
 npm run build
 ```
@@ -289,6 +345,7 @@ Built:
 - [x] The model, with a schema and a real validator
 - [x] Pluggable provider registry — Terraform (any platform) and Dynatrace built in
 - [x] Pluggable renderer registry — Graphviz bundled and working out of the box, with Mermaid/DOT fallback
+- [x] Category icons and a family palette, shared by every engine
 - [x] Multi-provider merge with provenance, explicit aliases, and conflict reporting
 - [x] Declarative `driftwood.config.yaml` wiring
 - [x] Reconciler with an explicit drift policy, wired as a CI gate

package/dist/cli.js

@@ -38,11 +38,12 @@ program
     .option('--view <id>', 'render a single named view')
     .option('--engine <name>', 'auto | mermaid | dot | graphviz', 'auto')
     .option('--direction <dir>', 'LR or TD', 'LR')
+    .option('--no-icons', 'draw plain boxes instead of category icons')
     .option('-o, --out <file>', 'write to a file instead of stdout')
     .action(async (path, opts) => {
     const model = requireModel(path);
     const direction = opts.direction === 'TD' ? 'TD' : 'LR';
-    const result = await render(model, { view: opts.view, direction }, opts.engine);
+    const result = await render(model, { view: opts.view, direction, icons: opts.icons }, opts.engine);
     if (result.fellBackFrom) {
         console.error(`note: ${result.fellBackFrom} unavailable, using ${result.renderer.name} (${result.via})`);
     }

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export { importTerraformState, parseTerraformState } from './providers/terraform
 export type { ImportOptions } from './providers/terraform.js';
 export { toModel as dynatraceToModel } from './providers/dynatrace.js';
 export { renderMermaid } from './render/mermaid.js';
+export { iconFor, familyFor, styleFor, iconSvg, ICONS, PALETTE, ICON_SIZE } from './render/icons.js';
+export type { IconKey, Family, FamilyStyle } from './render/icons.js';
 export { renderDot } from './render/dot.js';
 export { renderGraphvizSvg, detectTier, probeNativeDot } from './render/graphviz.js';
 export { selectEntities } from './render/select.js';

package/dist/index.js

@@ -12,6 +12,12 @@ export { importTerraformState, parseTerraformState } from './providers/terraform
 export { toModel as dynatraceToModel } from './providers/dynatrace.js';
 // Renderers
 export { renderMermaid } from './render/mermaid.js';
+// How an entity is classified and coloured. A third-party renderer is told to
+// classify through this rather than inventing a second table, so it has to be
+// reachable from the package entry point, not just from inside the repo.
+// The marker/injection mechanism stays internal: it is a private contract
+// between `renderDot` and the Graphviz renderer, not API to build on.
+export { iconFor, familyFor, styleFor, iconSvg, ICONS, PALETTE, ICON_SIZE } from './render/icons.js';
 export { renderDot } from './render/dot.js';
 export { renderGraphvizSvg, detectTier, probeNativeDot } from './render/graphviz.js';
 export { selectEntities } from './render/select.js';

package/dist/providers/terraform.js

@@ -29,7 +29,17 @@ function groupFor(type) {
  * resource's local name.
  */
 function displayName(r, attrs) {
-    const candidates = ['name', 'bucket', 'domain_name', 'function_name', 'identifier'];
+    const candidates = [
+        'name',
+        'bucket',
+        'domain_name',
+        'function_name',
+        'identifier',
+        'cluster_id',
+        'replication_group_id',
+        'alarm_name',
+        'family',
+    ];
     for (const key of candidates) {
         const v = attrs?.[key];
         if (typeof v === 'string' && v.length > 0)

package/dist/render/dot.js

@@ -1,5 +1,6 @@
 import { defineRenderer } from './types.js';
 import { selectEntities } from './select.js';
+import { ICON_SIZE, MARKER_PREFIX, iconFor, marker, styleFor } from './icons.js';
 /**
  * Graphviz DOT source.
  *
@@ -7,39 +8,61 @@ import { selectEntities } from './select.js';
  * matters: `dot` (this renderer) always works, while `graphviz` (rendering DOT
  * to SVG) needs an engine. So even a locked-down machine can produce DOT for
  * someone else to render, and nothing is lost by not having the binary.
+ *
+ * Nodes are HTML-like labels rather than plain `label="a\nb"` strings for two
+ * reasons. It allows a name/kind type hierarchy — one line at reading size and
+ * one small and muted — instead of two lines competing at the same weight; and
+ * it allows a fixed-size cell to be reserved for an icon (see `icons.ts`),
+ * which Graphviz then accounts for during layout. Both are what stop nodes
+ * coming out as long flat slabs: a box holding an icon above two short lines
+ * is roughly 3:2, while one holding a single wide line of text is closer to
+ * 6:1, and a graph full of 6:1 boxes is what reads as "squashed".
  */
+const INK = '#0f172a';
+const MUTED = '#64748b';
+const CLUSTER_LINE = '#dbe2ea';
+const CLUSTER_FILL = '#f8fafc';
+const EDGE_COLOR = '#94a3b8';
+/** Border and fill applied on top of the family colours when health is known. */
+const HEALTH_COLORS = {
+    healthy: { accent: '#16a34a', tint: '#f0fdf4' },
+    degraded: { accent: '#d97706', tint: '#fffbeb' },
+    down: { accent: '#dc2626', tint: '#fef2f2' },
+};
 function quote(text) {
     return text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 }
-const SHAPES = [
-    [/(s3|bucket|rds|dynamodb|database|efs|volume|storage)/i, 'cylinder'],
-    [/(sqs|sns|queue|topic|kinesis|kafka|eventbridge)/i, 'parallelogram'],
-    [/(route53|dns|cloudfront|vpc|subnet|lb|gateway|cdn|zone|record)/i, 'ellipse'],
-    [/(iam|role|policy|secret|kms|cert|acm|auth)/i, 'hexagon'],
-];
-function shapeFor(kind) {
-    for (const [pattern, shape] of SHAPES)
-        if (pattern.test(kind))
-            return shape;
-    return 'box';
+/**
+ * HTML-like labels are parsed as XML, so the five entity references matter —
+ * an unescaped `&` in a name is a hard parse error, not a cosmetic problem.
+ * The icon marker prefix is stripped here too: a model is data, and data must
+ * not be able to place its own artwork in the output.
+ */
+function xml(text) {
+    return text
+        .split(MARKER_PREFIX)
+        .join('')
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
 }
-const HEALTH_COLORS = {
-    healthy: '#0f9d58',
-    degraded: '#f4b400',
-    down: '#db4437',
-};
 export function renderDot(model, ctx = {}) {
     const view = ctx.view ? model.views.find((v) => v.id === ctx.view) : undefined;
     if (ctx.view && !view) {
         throw new Error(`unknown view: ${ctx.view} (have: ${model.views.map((v) => v.id).join(', ') || 'none'})`);
     }
+    // Off by default: DOT source is meant to be renderable by any Graphviz, and
+    // a marker only becomes artwork if driftwood post-processes the SVG itself.
+    const withIcons = ctx.icons === true;
     const entities = selectEntities(model, view);
     const visible = new Set(entities.map((e) => e.id));
     const lines = [
         `digraph "${quote(model.name)}" {`,
-        `  rankdir=${ctx.direction === 'TD' ? 'TB' : 'LR'};`,
-        '  node [fontname="Helvetica" style=filled fillcolor="#ffffff"];',
-        '  edge [fontname="Helvetica" color="#666666"];',
+        `  graph [rankdir=${ctx.direction === 'TD' ? 'TB' : 'LR'} fontname="Helvetica" fontsize=11 bgcolor="white"`,
+        '         nodesep=0.35 ranksep=0.75 pad=0.3 newrank=true];',
+        '  node [shape=box style="rounded,filled" fontname="Helvetica" margin=0.06 penwidth=1.2];',
+        `  edge [fontname="Helvetica" fontsize=9 fontcolor="${MUTED}" color="${EDGE_COLOR}" penwidth=1.1 arrowsize=0.7];`,
     ];
     const grouped = new Map();
     const ungrouped = [];
@@ -53,16 +76,29 @@ export function renderDot(model, ctx = {}) {
             ungrouped.push(e);
     }
     const nodeLine = (e, indent) => {
-        const label = `${e.name ?? e.id}\\n${e.kind}`;
         const health = ctx.health?.[e.id];
-        const color = health ? ` fillcolor="${HEALTH_COLORS[health]}" fontcolor="#ffffff"` : '';
-        return `${indent}"${quote(e.id)}" [label="${quote(label)}" shape=${shapeFor(e.kind)}${color}];`;
+        const style = (health ? HEALTH_COLORS[health] : undefined) ?? styleFor(e.kind);
+        const penwidth = health ? 2.2 : 1.2;
+        const rows = [];
+        if (withIcons) {
+            // A fixed-size cell so Graphviz reserves exactly the room the icon will
+            // occupy; the 1pt marker inside it is what `injectIcons` finds and
+            // replaces, and is invisible if it somehow survives.
+            rows.push(`<TR><TD FIXEDSIZE="TRUE" WIDTH="${ICON_SIZE + 10}" HEIGHT="${ICON_SIZE + 6}">` +
+                `<FONT POINT-SIZE="1" COLOR="${CLUSTER_FILL}">${marker(iconFor(e.kind))}</FONT></TD></TR>`);
+        }
+        rows.push(`<TR><TD><FONT POINT-SIZE="11" COLOR="${INK}"><B>${xml(e.name ?? e.id)}</B></FONT></TD></TR>`);
+        rows.push(`<TR><TD><FONT POINT-SIZE="8" COLOR="${MUTED}">${xml(e.kind)}</FONT></TD></TR>`);
+        const label = `<<TABLE BORDER="0" CELLBORDER="0" CELLSPACING="0" CELLPADDING="1">${rows.join('')}</TABLE>>`;
+        return (`${indent}"${quote(e.id)}" [label=${label} fillcolor="${style.tint}" ` +
+            `color="${style.accent}" penwidth=${penwidth}];`);
     };
     let clusterIndex = 0;
     for (const [group, members] of [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b))) {
         lines.push(`  subgraph cluster_${clusterIndex++} {`);
-        lines.push(`    label="${quote(group)}";`);
-        lines.push('    style=rounded; color="#999999";');
+        lines.push(`    label=<<FONT POINT-SIZE="11" COLOR="${MUTED}">${xml(group)}</FONT>>;`);
+        lines.push(`    style="rounded,filled"; fillcolor="${CLUSTER_FILL}"; color="${CLUSTER_LINE}";`);
+        lines.push('    penwidth=1; labeljust=l; margin=14;');
         for (const e of members)
             lines.push(nodeLine(e, '    '));
         lines.push('  }');

package/dist/render/graphviz.d.ts

@@ -42,6 +42,15 @@ export declare function loadWasmGraphviz(): Promise<WasmGraphviz | undefined>;
 /** Test seam: forget any cached WASM instance. */
 export declare function resetWasmCache(): void;
 export declare function detectTier(): Promise<GraphvizTier>;
-export declare function renderGraphvizSvg(model: Model, ctx?: RenderContext): Promise<string>;
+/**
+ * @param forceTier Pin the tier instead of detecting one. The committed
+ * example renders use this: layout is byte-deterministic for a given Graphviz
+ * build, but a native `dot` and the bundled WASM build are two different
+ * builds, so a contributor with Graphviz installed would otherwise regenerate
+ * `docs/` into a diff that fails the freshness check in CI, where no `dot`
+ * exists. Pinning is for reproducibility only — nothing in normal rendering
+ * uses it, and `auto` must keep choosing for itself.
+ */
+export declare function renderGraphvizSvg(model: Model, ctx?: RenderContext, forceTier?: Exclude<GraphvizTier, 'none'>): Promise<string>;
 export declare const graphvizRenderer: import("./types.js").Renderer;
 export {};

package/dist/render/graphviz.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { renderDot } from './dot.js';
+import { PALETTE, injectIcons, styleFor } from './icons.js';
 import { defineRenderer } from './types.js';
 /** Runs `dot -V` to see whether a usable native Graphviz is on PATH. */
 export function probeNativeDot(command = 'dot') {
@@ -82,15 +83,35 @@ function runNativeDot(source, engine, format) {
         child.stdin.end();
     });
 }
-export async function renderGraphvizSvg(model, ctx = {}) {
-    const source = renderDot(model, ctx);
-    const tier = await detectTier();
+/**
+ * @param forceTier Pin the tier instead of detecting one. The committed
+ * example renders use this: layout is byte-deterministic for a given Graphviz
+ * build, but a native `dot` and the bundled WASM build are two different
+ * builds, so a contributor with Graphviz installed would otherwise regenerate
+ * `docs/` into a diff that fails the freshness check in CI, where no `dot`
+ * exists. Pinning is for reproducibility only — nothing in normal rendering
+ * uses it, and `auto` must keep choosing for itself.
+ */
+export async function renderGraphvizSvg(model, ctx = {}, forceTier) {
+    // Icons are on unless switched off: this renderer produces the finished
+    // picture, so it is the one place a marker can actually become artwork.
+    const withIcons = ctx.icons !== false;
+    const source = renderDot(model, { ...ctx, icons: withIcons });
+    // Colour by the entity's own kind rather than by anything in the SVG, so the
+    // icon always matches the border Graphviz drew around it.
+    const accents = new Map(model.entities.map((e) => [e.id, styleFor(e.kind).accent]));
+    const finish = (svg) => withIcons ? injectIcons(svg, (id) => accents.get(id) ?? PALETTE.other.accent) : svg;
+    const tier = forceTier ?? (await detectTier());
     if (tier === 'native')
-        return runNativeDot(source, 'dot', 'svg');
+        return finish(await runNativeDot(source, 'dot', 'svg'));
     if (tier === 'wasm') {
         const gv = await loadWasmGraphviz();
         if (gv)
-            return gv.layout(source, 'svg', 'dot');
+            return finish(gv.layout(source, 'svg', 'dot'));
+        // Only reachable when the caller pinned `wasm`; detection would have
+        // returned 'none'. Say which tier was asked for, not just that it failed.
+        throw new Error('the bundled WASM Graphviz was requested but could not load — WebAssembly ' +
+            'is disabled in this runtime (for example `node --jitless`).');
     }
     throw new Error('Graphviz is unavailable because WebAssembly is disabled in this runtime ' +
         '(for example `node --jitless`). Install the `dot` binary, or use ' +

package/dist/render/icons.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Icons for rendered diagrams.
+ *
+ * Two constraints shape this module, and they rule out the obvious answers:
+ *
+ *   1. **No native dependencies and no downloads.** Vendor icon sets (the AWS
+ *      Architecture Icons, Azure's, GCP's) are large binary asset packs with
+ *      their own trademark terms, so they are not something this tool can
+ *      quietly vendor. These icons are therefore drawn here, by category —
+ *      "database", "queue", "load balancer" — not by vendor. A category set
+ *      also survives contact with a multi-cloud estate: an on-prem Postgres,
+ *      an RDS instance and a Cloud SQL instance all want the same glyph.
+ *   2. **Engine parity.** The picture must be identical whether Graphviz ran
+ *      as a native binary or as the bundled WASM build. Graphviz's own
+ *      `image=` attribute is not viable for that: the native binary resolves
+ *      it as a filesystem path, so a `data:` URI works in one tier and fails
+ *      in the other.
+ *
+ * So the icon is not handed to Graphviz at all. `renderDot` reserves a
+ * fixed-size cell in the node's HTML-like label containing a 1pt marker token,
+ * Graphviz lays out the graph knowing exactly how much room the icon needs,
+ * and `injectIcons` swaps each marker for inline SVG afterwards. Both tiers
+ * emit the same SVG structure, so both get the same picture, and the result
+ * stays a self-contained SVG with no external references and no base64 bloat.
+ */
+/**
+ * The visual family an entity belongs to. Icons carry the specific meaning;
+ * families carry the colour, so a diagram reads as a handful of zones rather
+ * than thirty unrelated hues.
+ */
+export type Family = 'edge' | 'compute' | 'data' | 'messaging' | 'security' | 'observability' | 'other';
+export interface FamilyStyle {
+    /** Border and icon colour. */
+    accent: string;
+    /** Node fill — a wash of the accent, light enough for 9pt text on top. */
+    tint: string;
+}
+export declare const PALETTE: Record<Family, FamilyStyle>;
+export type IconKey = 'dns' | 'cdn' | 'api' | 'loadbalancer' | 'network' | 'firewall' | 'certificate' | 'identity' | 'secret' | 'compute' | 'function' | 'container' | 'cluster' | 'service' | 'database' | 'storage' | 'cache' | 'queue' | 'topic' | 'events' | 'email' | 'monitoring' | 'user' | 'generic';
+interface Icon {
+    family: Family;
+    /** SVG shapes on a 24x24 canvas. Stroke and fill are set by the wrapper. */
+    body: string;
+}
+/**
+ * Drawn on a 24x24 grid, stroked rather than filled so a single accent colour
+ * carries the whole glyph and one wrapper `<g>` can restyle it.
+ */
+export declare const ICONS: Record<IconKey, Icon>;
+export declare function iconFor(kind: string): IconKey;
+export declare function familyFor(kind: string): Family;
+export declare function styleFor(kind: string): FamilyStyle;
+/**
+ * Namespaced so it cannot collide with anything a provider might legitimately
+ * put in an entity name. `renderDot` additionally strips the prefix from
+ * labels, so a hostile model cannot inject its own icon.
+ *
+ * Deliberately letters, digits, `_` and `@` only: Graphviz XML-escapes SVG
+ * text, so a hyphen would come back out as `&#45;` and the marker would no
+ * longer match itself.
+ */
+export declare const MARKER_PREFIX = "@@dwicon_";
+export declare function marker(key: IconKey): string;
+/** Rendered size of the icon, in points, matching the cell `renderDot` reserves. */
+export declare const ICON_SIZE = 24;
+export declare function iconSvg(key: IconKey, x: number, y: number, color: string, size?: number): string;
+/**
+ * Replaces every icon marker in a Graphviz-produced SVG with inline vector
+ * artwork. Anything it does not recognise is left exactly as it was, so a
+ * marker-free SVG (Mermaid, or DOT rendered by someone else) passes through
+ * untouched.
+ */
+export declare function injectIcons(svg: string, colorFor?: (nodeId: string) => string): string;
+export {};

package/dist/render/icons.js

@@ -0,0 +1,306 @@
+/**
+ * Icons for rendered diagrams.
+ *
+ * Two constraints shape this module, and they rule out the obvious answers:
+ *
+ *   1. **No native dependencies and no downloads.** Vendor icon sets (the AWS
+ *      Architecture Icons, Azure's, GCP's) are large binary asset packs with
+ *      their own trademark terms, so they are not something this tool can
+ *      quietly vendor. These icons are therefore drawn here, by category —
+ *      "database", "queue", "load balancer" — not by vendor. A category set
+ *      also survives contact with a multi-cloud estate: an on-prem Postgres,
+ *      an RDS instance and a Cloud SQL instance all want the same glyph.
+ *   2. **Engine parity.** The picture must be identical whether Graphviz ran
+ *      as a native binary or as the bundled WASM build. Graphviz's own
+ *      `image=` attribute is not viable for that: the native binary resolves
+ *      it as a filesystem path, so a `data:` URI works in one tier and fails
+ *      in the other.
+ *
+ * So the icon is not handed to Graphviz at all. `renderDot` reserves a
+ * fixed-size cell in the node's HTML-like label containing a 1pt marker token,
+ * Graphviz lays out the graph knowing exactly how much room the icon needs,
+ * and `injectIcons` swaps each marker for inline SVG afterwards. Both tiers
+ * emit the same SVG structure, so both get the same picture, and the result
+ * stays a self-contained SVG with no external references and no base64 bloat.
+ */
+export const PALETTE = {
+    edge: { accent: '#0284c7', tint: '#f0f9ff' },
+    compute: { accent: '#d97706', tint: '#fffbeb' },
+    data: { accent: '#059669', tint: '#ecfdf5' },
+    messaging: { accent: '#7c3aed', tint: '#f5f3ff' },
+    security: { accent: '#e11d48', tint: '#fff1f2' },
+    observability: { accent: '#475569', tint: '#f8fafc' },
+    other: { accent: '#64748b', tint: '#f8fafc' },
+};
+/**
+ * Drawn on a 24x24 grid, stroked rather than filled so a single accent colour
+ * carries the whole glyph and one wrapper `<g>` can restyle it.
+ */
+export const ICONS = {
+    dns: {
+        family: 'edge',
+        body: '<circle cx="12" cy="12" r="9"/><ellipse cx="12" cy="12" rx="4" ry="9"/>' +
+            '<path d="M3.2 12h17.6M5 7h14M5 17h14"/>',
+    },
+    cdn: {
+        family: 'edge',
+        body: '<circle cx="12" cy="12" r="3.6"/>' +
+            '<path d="M12 8.4V4M12 15.6V20M8.9 10.2 5.1 8M15.1 13.8l3.8 2.2M8.9 13.8 5.1 16M15.1 10.2 18.9 8"/>' +
+            '<circle cx="12" cy="3" r="1.6"/><circle cx="12" cy="21" r="1.6"/>' +
+            '<circle cx="3.9" cy="7.3" r="1.6"/><circle cx="20.1" cy="16.7" r="1.6"/>' +
+            '<circle cx="3.9" cy="16.7" r="1.6"/><circle cx="20.1" cy="7.3" r="1.6"/>',
+    },
+    api: {
+        family: 'edge',
+        body: '<path d="M8.5 5.5 3.5 12l5 6.5M15.5 5.5 20.5 12l-5 6.5M13.6 4.2 10.4 19.8"/>',
+    },
+    loadbalancer: {
+        family: 'edge',
+        body: '<rect x="9" y="2.5" width="6" height="5" rx="1.5"/>' +
+            '<path d="M12 7.5v3M4 13.5v-3h16v3M12 10.5v3"/>' +
+            '<rect x="1.5" y="13.5" width="5" height="5" rx="1.5"/>' +
+            '<rect x="9.5" y="13.5" width="5" height="5" rx="1.5"/>' +
+            '<rect x="17.5" y="13.5" width="5" height="5" rx="1.5"/>',
+    },
+    network: {
+        family: 'edge',
+        body: '<circle cx="12" cy="4.6" r="2.6"/><circle cx="4.8" cy="18" r="2.6"/><circle cx="19.2" cy="18" r="2.6"/>' +
+            '<path d="M10.7 6.9 6.1 15.7M13.3 6.9l4.6 8.8M7.4 18h9.2"/>',
+    },
+    firewall: {
+        family: 'security',
+        body: '<path d="M12 2.5 20 5.4v6.2c0 4.9-3.4 8-8 9.9-4.6-1.9-8-5-8-9.9V5.4Z"/><path d="M8.4 12.1 11 14.7l4.6-5"/>',
+    },
+    certificate: {
+        family: 'security',
+        body: '<circle cx="12" cy="9" r="6.1"/><path d="M8.4 14.2v7.3L12 19.4l3.6 2.1v-7.3"/><path d="M9.7 9l1.7 1.8 3-3.4"/>',
+    },
+    identity: {
+        family: 'security',
+        body: '<rect x="2.8" y="3.2" width="18.4" height="17.6" rx="3"/>' +
+            '<circle cx="12" cy="10.2" r="2.9"/><path d="M7.2 17.9a4.9 4.9 0 0 1 9.6 0"/>',
+    },
+    secret: {
+        family: 'security',
+        body: '<circle cx="8.4" cy="8.4" r="4.6"/><path d="M11.7 11.7 20.4 20.4M15.6 19.2l2-2M18.1 16.7l2-2"/>',
+    },
+    compute: {
+        family: 'compute',
+        body: '<rect x="2.8" y="3.6" width="18.4" height="7" rx="1.8"/><rect x="2.8" y="13.4" width="18.4" height="7" rx="1.8"/>' +
+            '<circle cx="6.4" cy="7.1" r=".9" fill="currentColor" stroke="none"/>' +
+            '<circle cx="6.4" cy="16.9" r=".9" fill="currentColor" stroke="none"/>',
+    },
+    function: {
+        family: 'compute',
+        body: '<path d="M13.6 2.4 5.2 13.6h5.6L10.4 21.6l8.4-11.2h-5.6Z"/>',
+    },
+    container: {
+        family: 'compute',
+        body: '<path d="M12 2.6 20.6 7v10L12 21.4 3.4 17V7Z"/><path d="M3.4 7 12 11.4 20.6 7M12 11.4v10"/>',
+    },
+    cluster: {
+        family: 'compute',
+        body: '<path d="M12 2.6 20.6 7v10L12 21.4 3.4 17V7Z"/><circle cx="12" cy="12" r="3.2"/>' +
+            '<path d="M12 8.8V4.6M14.8 13.8l3.6 2.1M9.2 13.8l-3.6 2.1"/>',
+    },
+    service: {
+        family: 'compute',
+        body: '<path d="M12 2.6 20.6 7v10L12 21.4 3.4 17V7Z"/><path d="M8.4 12h7.2M12 8.4v7.2"/>',
+    },
+    database: {
+        family: 'data',
+        body: '<ellipse cx="12" cy="6" rx="8" ry="3.2"/>' +
+            '<path d="M4 6v12c0 1.8 3.6 3.2 8 3.2s8-1.4 8-3.2V6"/>' +
+            '<path d="M4 12c0 1.8 3.6 3.2 8 3.2s8-1.4 8-3.2"/>',
+    },
+    storage: {
+        family: 'data',
+        body: '<ellipse cx="12" cy="6.2" rx="8" ry="2.6"/><path d="M4 6.2 5.9 19a6.2 6.2 0 0 0 12.2 0L20 6.2"/>',
+    },
+    cache: {
+        family: 'data',
+        body: '<rect x="6" y="6" width="12" height="12" rx="2"/><rect x="9.6" y="9.6" width="4.8" height="4.8" rx="1"/>' +
+            '<path d="M9.2 6V2.8M14.8 6V2.8M9.2 18v3.2M14.8 18v3.2M6 9.2H2.8M6 14.8H2.8M18 9.2h3.2M18 14.8h3.2"/>',
+    },
+    queue: {
+        family: 'messaging',
+        body: '<rect x="2.4" y="6" width="19.2" height="12" rx="2"/><path d="M8.8 6v12M15.2 6v12"/>',
+    },
+    topic: {
+        family: 'messaging',
+        body: '<circle cx="12" cy="12" r="2.4" fill="currentColor" stroke="none"/>' +
+            '<path d="M8 8.2a5.4 5.4 0 0 0 0 7.6M16 8.2a5.4 5.4 0 0 1 0 7.6"/>' +
+            '<path d="M5.2 5.2a9.6 9.6 0 0 0 0 13.6M18.8 5.2a9.6 9.6 0 0 1 0 13.6"/>',
+    },
+    events: {
+        family: 'messaging',
+        body: '<path d="M12 2.4 21.6 12 12 21.6 2.4 12Z"/><path d="M12.9 7.2 9.4 12.6h2.5l-.8 4.2 3.5-5.4h-2.5Z"/>',
+    },
+    email: {
+        family: 'messaging',
+        body: '<rect x="2.4" y="5" width="19.2" height="14" rx="2"/><path d="M3.2 7 12 13.4 20.8 7"/>',
+    },
+    monitoring: {
+        family: 'observability',
+        body: '<path d="M3.4 3.4v17.2h17.2"/><path d="M6.6 16.6 11 11.2l3.4 2.8 5.4-7"/>',
+    },
+    user: {
+        family: 'other',
+        body: '<circle cx="12" cy="7.6" r="4"/><path d="M4.4 20.6a7.6 7.6 0 0 1 15.2 0"/>',
+    },
+    generic: {
+        family: 'other',
+        body: '<rect x="3.4" y="3.4" width="17.2" height="17.2" rx="3.4"/><path d="M8.6 12h6.8"/>',
+    },
+};
+/**
+ * `kind` is an open string by design, so this is pattern matching over
+ * vocabularies rather than a lookup table — Terraform types, Kubernetes kinds,
+ * Dynatrace entity types and anything a future provider invents.
+ *
+ * **Order is the whole trick.** More specific patterns must come first, and
+ * several pairs actively collide: `aws_elasticache_cluster` is a cache, not a
+ * Kubernetes cluster; `aws_db_instance` is a database, not an EC2 instance;
+ * `aws_db_subnet_group` is data, not network. Those cases are pinned by tests.
+ */
+/**
+ * Whole-token match. `\b` is no use here: `_` is a word character, so `\bses\b`
+ * never matches `aws_ses_receipt_rule`, and `\bkey\b` never matches
+ * `aws_kms_key`. Separators in the wild are `_`, `-`, `.` and case changes, so
+ * the boundary is "anything that isn't alphanumeric".
+ */
+function tok(alternatives) {
+    return `(?:^|[^a-z0-9])(?:${alternatives})(?:[^a-z0-9]|$)`;
+}
+function rule(source, key) {
+    return [new RegExp(source, 'i'), key];
+}
+const KIND_ICONS = [
+    rule(`route53|hosted_?zone|dns|record_?set|${tok('record|zone|zones')}`, 'dns'),
+    rule(`cloudfront|front_?door|fastly|akamai|${tok('cdn')}`, 'cdn'),
+    rule(`certificate|${tok('acm|cert|certs|tls|ssl')}`, 'certificate'),
+    rule(`waf|firewall|security_?group|network_?acl|${tok('nacl|nsg|acl')}`, 'firewall'),
+    rule(`load_?balanc|target_?group|ingress|${tok('lb|alb|nlb|elb')}`, 'loadbalancer'),
+    rule(`api_?gateway|apigw|appsync|graphql|endpoint|${tok('api')}`, 'api'),
+    rule(`elasticache|memcache|redis|${tok('cache')}`, 'cache'),
+    rule(`rds|dynamodb|aurora|spanner|cosmos|mongo|postgres|mysql|bigtable|firestore|database|${tok('db|sql')}`, 'database'),
+    rule(`bucket|blob|storage|volume|disk|file_?system|glacier|${tok('s3|efs|fs')}`, 'storage'),
+    rule(`vpc|subnet|vnet|nat_?gateway|route_?table|peering|transit_?gateway|network_?interface|${tok('nat|cidr')}`, 'network'),
+    rule('event_?bridge|event_?bus|event_?rule|event_?source|scheduler', 'events'),
+    rule(`sqs|queue|kinesis|kafka|rabbit|stream|${tok('msk')}`, 'queue'),
+    rule('sns|topic|pubsub|subscription|notification', 'topic'),
+    rule(`smtp|email|sendgrid|${tok('ses|mail')}`, 'email'),
+    rule(`task_?definition|container|docker|image|${tok('ecr|pod|pods')}`, 'container'),
+    rule(`cluster|node_?group|node_?pool|${tok('eks|gke|aks')}`, 'cluster'),
+    rule('lambda|function|serverless', 'function'),
+    rule(`virtual_?machine|autoscal|compute|${tok('ec2|vm|asg|instance|instances|server|servers|host|hosts')}`, 'compute'),
+    rule('service|deployment|app_?service|workload|daemonset|statefulset|replicaset', 'service'),
+    rule(`iam|policy|principal|service_?account|user_?pool|cognito|${tok('role|roles|auth|rbac')}`, 'identity'),
+    rule(`secret|key_?vault|parameter_?store|ssm_parameter|vault|${tok('kms|key|keys')}`, 'secret'),
+    rule(`cloudwatch|metric|alarm|monitor|prometheus|grafana|dashboard|log_?group|telemetry|${tok('log|logs|trace|traces')}`, 'monitoring'),
+    rule(`browser|customer|${tok('user|users|client|clients|actor|external')}`, 'user'),
+];
+export function iconFor(kind) {
+    for (const [pattern, key] of KIND_ICONS)
+        if (pattern.test(kind))
+            return key;
+    return 'generic';
+}
+export function familyFor(kind) {
+    return ICONS[iconFor(kind)].family;
+}
+export function styleFor(kind) {
+    return PALETTE[familyFor(kind)];
+}
+/**
+ * Namespaced so it cannot collide with anything a provider might legitimately
+ * put in an entity name. `renderDot` additionally strips the prefix from
+ * labels, so a hostile model cannot inject its own icon.
+ *
+ * Deliberately letters, digits, `_` and `@` only: Graphviz XML-escapes SVG
+ * text, so a hyphen would come back out as `&#45;` and the marker would no
+ * longer match itself.
+ */
+export const MARKER_PREFIX = '@@dwicon_';
+export function marker(key) {
+    return `${MARKER_PREFIX}${key}@@`;
+}
+/** Rendered size of the icon, in points, matching the cell `renderDot` reserves. */
+export const ICON_SIZE = 24;
+export function iconSvg(key, x, y, color, size = ICON_SIZE) {
+    const icon = ICONS[key] ?? ICONS.generic;
+    const scale = size / 24;
+    const left = round(x - size / 2);
+    const top = round(y - size / 2);
+    return (`<g class="driftwood-icon" transform="translate(${left} ${top}) scale(${round(scale)})" ` +
+        `fill="none" stroke="${color}" color="${color}" stroke-width="1.7" ` +
+        `stroke-linecap="round" stroke-linejoin="round">${icon.body}</g>`);
+}
+function round(n) {
+    return Math.round(n * 100) / 100;
+}
+const NODE_RE = /<g id="node\d+" class="node">[\s\S]*?<\/g>/g;
+const MARKER_TEXT_RE = new RegExp(`<text\\b[^>]*\\bx="(-?[\\d.]+)"[^>]*\\by="(-?[\\d.]+)"[^>]*>${escapeRe(MARKER_PREFIX)}([a-z]+)@@</text>`);
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Horizontal centre of a node's shape.
+ *
+ * The marker text's own `x` is the *start* of the run, which depends on the
+ * marker's width in the current font — unusable. The node's outline is not:
+ * every label this renderer emits is a single-column table, so the icon cell's
+ * centre is the shape's centre.
+ */
+function centreX(nodeSvg) {
+    const ellipse = nodeSvg.match(/<ellipse[^>]*\bcx="(-?[\d.]+)"/);
+    if (ellipse?.[1])
+        return Number(ellipse[1]);
+    const geometry = nodeSvg.match(/<(?:polygon|path)[^>]*\b(?:points|d)="([^"]+)"/);
+    if (!geometry?.[1])
+        return undefined;
+    const numbers = geometry[1]
+        .replace(/[A-Za-z]/g, ' ')
+        .split(/[\s,]+/)
+        .filter((t) => t !== '')
+        .map(Number);
+    const xs = [];
+    for (let i = 0; i < numbers.length; i += 2) {
+        const x = numbers[i];
+        if (x !== undefined && Number.isFinite(x))
+            xs.push(x);
+    }
+    if (xs.length === 0)
+        return undefined;
+    return (Math.min(...xs) + Math.max(...xs)) / 2;
+}
+/**
+ * Replaces every icon marker in a Graphviz-produced SVG with inline vector
+ * artwork. Anything it does not recognise is left exactly as it was, so a
+ * marker-free SVG (Mermaid, or DOT rendered by someone else) passes through
+ * untouched.
+ */
+export function injectIcons(svg, colorFor) {
+    return svg.replace(NODE_RE, (node) => {
+        const found = MARKER_TEXT_RE.exec(node);
+        if (!found)
+            return node;
+        const [element, , yRaw, key] = found;
+        const y = Number(yRaw);
+        const x = centreX(node);
+        if (x === undefined || !Number.isFinite(y))
+            return node.replace(element, '');
+        const id = node.match(/<title>([\s\S]*?)<\/title>/)?.[1];
+        const color = colorFor && id ? colorFor(unescapeXml(id)) : PALETTE.other.accent;
+        return node.replace(element, iconSvg((key ?? 'generic'), x, y, color));
+    });
+}
+function unescapeXml(s) {
+    return s
+        .replace(/&#45;/g, '-')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&');
+}

package/dist/render/mermaid.js

@@ -1,3 +1,4 @@
+import { PALETTE, familyFor, iconFor } from './icons.js';
 import { selectEntities } from './select.js';
 import { defineRenderer } from './types.js';
 /**
@@ -13,35 +14,35 @@ function escapeLabel(text) {
     // Mermaid renders <br/> inside a quoted label; a raw newline breaks parsing.
     return text.replace(/"/g, '&quot;').replace(/\n/g, '<br/>');
 }
-const KIND_PATTERNS = [
-    [/(s3|bucket|rds|dynamodb|db|database|efs|volume|storage)/i, 'storage'],
-    [/(sqs|sns|queue|topic|kinesis|kafka|eventbridge)/i, 'messaging'],
-    [/(route53|dns|cloudfront|vpc|subnet|lb|gateway|cdn|zone|record)/i, 'network'],
-    [/(iam|role|policy|secret|kms|cert|acm|auth)/i, 'identity'],
-    [/(lambda|ec2|ecs|function|instance|service|container|app)/i, 'compute'],
-];
-function shapeFor(kind) {
-    for (const [pattern, family] of KIND_PATTERNS) {
-        if (pattern.test(kind))
-            return family;
-    }
-    return 'compute';
-}
+/**
+ * Mermaid has no icon primitive, so the same categorisation that picks an icon
+ * for the Graphviz renderer picks a shape and a colour here. Sharing it is the
+ * point: a queue must not be a cylinder in one engine and a parallelogram in
+ * the other, or the two pictures stop describing the same system.
+ */
+const SHAPES = {
+    database: (id, l) => `${id}[("${l}")]`,
+    storage: (id, l) => `${id}[("${l}")]`,
+    cache: (id, l) => `${id}[("${l}")]`,
+    queue: (id, l) => `${id}[/"${l}"/]`,
+    topic: (id, l) => `${id}[/"${l}"/]`,
+    events: (id, l) => `${id}[/"${l}"/]`,
+    email: (id, l) => `${id}[/"${l}"/]`,
+    dns: (id, l) => `${id}("${l}")`,
+    cdn: (id, l) => `${id}("${l}")`,
+    network: (id, l) => `${id}("${l}")`,
+    loadbalancer: (id, l) => `${id}("${l}")`,
+    api: (id, l) => `${id}("${l}")`,
+    identity: (id, l) => `${id}{{"${l}"}}`,
+    secret: (id, l) => `${id}{{"${l}"}}`,
+    certificate: (id, l) => `${id}{{"${l}"}}`,
+    firewall: (id, l) => `${id}{{"${l}"}}`,
+};
 function renderNode(e) {
     const label = escapeLabel(`${e.name ?? e.id}\n${e.kind}`);
     const id = nodeId(e.id);
-    switch (shapeFor(e.kind)) {
-        case 'storage':
-            return `${id}[("${label}")]`;
-        case 'messaging':
-            return `${id}[/"${label}"/]`;
-        case 'network':
-            return `${id}("${label}")`;
-        case 'identity':
-            return `${id}{{"${label}"}}`;
-        default:
-            return `${id}["${label}"]`;
-    }
+    const shape = SHAPES[iconFor(e.kind)];
+    return shape ? shape(id, label) : `${id}["${label}"]`;
 }
 export function renderMermaid(model, opts = {}) {
     const view = opts.view ? model.views.find((v) => v.id === opts.view) : undefined;
@@ -79,6 +80,18 @@ export function renderMermaid(model, opts = {}) {
         const label = edge.label ? `|"${escapeLabel(edge.label)}"|` : '';
         lines.push(`    ${nodeId(edge.from)} -->${label} ${nodeId(edge.to)}`);
     }
+    // Family colours, matching the Graphviz renderer's palette. Emitted before
+    // the health overlay so that health, being the more urgent fact, wins.
+    const families = new Set();
+    for (const e of entities) {
+        const family = familyFor(e.kind);
+        families.add(family);
+        lines.push(`    class ${nodeId(e.id)} f_${family};`);
+    }
+    for (const family of [...families].sort()) {
+        const { accent, tint } = PALETTE[family];
+        lines.push(`    classDef f_${family} fill:${tint},stroke:${accent},color:#0f172a;`);
+    }
     if (opts.health) {
         lines.push('');
         for (const [id, status] of Object.entries(opts.health)) {

package/dist/render/types.d.ts

@@ -4,6 +4,12 @@ export interface RenderContext {
     direction?: 'LR' | 'TD';
     /** Runtime health, applied at render time. Never committed to the model. */
     health?: Record<string, 'healthy' | 'degraded' | 'down'>;
+    /**
+     * Draw category icons on nodes. Only renderers that produce final artwork
+     * honour this — Mermaid has no icon primitive, and raw DOT source has no
+     * post-processing step to turn a marker into a picture.
+     */
+    icons?: boolean;
 }
 export interface Availability {
     available: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brignano/driftwood",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Architecture as code, reconciled with live infrastructure.",
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,7 @@
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",
     "dev": "tsx src/cli.ts",
+    "docs": "tsx scripts/render-docs.ts",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
@@ -54,6 +55,6 @@
     "@types/node": "^22.7.4",
     "tsx": "^4.19.1",
     "typescript": "^5.6.2",
-    "vitest": "^2.1.2"
+    "vitest": "^3.2.6"
   }
 }