capdag 0.100.226 → 0.104.240

package/capdag.js

@@ -1222,13 +1222,14 @@ class MediaSpec {
    * @param {string|null} profile - Optional profile URL
    * @param {Object|null} schema - Optional JSON Schema for local validation
    * @param {string|null} title - Optional display-friendly title
-   * @param {string|null} description - Optional description
+   * @param {string|null} description - Optional short plain-text description
    * @param {string|null} mediaUrn - Source media URN for tag-based checks
    * @param {Object|null} validation - Optional validation rules (min, max, min_length, max_length, pattern, allowed_values)
    * @param {Object|null} metadata - Optional metadata (arbitrary key-value pairs for display/categorization)
    * @param {string[]} extensions - File extensions for storing this media type (e.g., ['pdf'], ['jpg', 'jpeg'])
+   * @param {string|null} documentation - Optional long-form markdown documentation. Rendered in media info panels, the cap navigator, capdag-dot-com, and anywhere else a rich-text explanation of the media spec is useful.
    */
-  constructor(contentType, profile = null, schema = null, title = null, description = null, mediaUrn = null, validation = null, metadata = null, extensions = []) {
+  constructor(contentType, profile = null, schema = null, title = null, description = null, mediaUrn = null, validation = null, metadata = null, extensions = [], documentation = null) {
     this.contentType = contentType;
     this.profile = profile;
     this.schema = schema;
@@ -1238,6 +1239,7 @@ class MediaSpec {
     this.validation = validation;
     this.metadata = metadata;
     this.extensions = extensions;
+    this.documentation = documentation;
   }
 
   /**
@@ -1387,12 +1389,19 @@ function resolveMediaUrn(mediaUrn, mediaSpecs = []) {
     const def = mediaSpecs.find(spec => spec.urn === mediaUrn);
 
     if (def) {
-      // Object form: { urn, media_type, title, profile_uri?, schema?, description?, validation?, metadata?, extensions? }
+      // Object form: { urn, media_type, title, profile_uri?, schema?, description?, documentation?, validation?, metadata?, extensions? }
       const mediaType = def.media_type || def.mediaType;
       const profileUri = def.profile_uri || def.profileUri || null;
       const schema = def.schema || null;
       const title = def.title || null;
       const description = def.description || null;
+      // Long-form markdown body for rich info panels. Strict
+      // snake_case (`documentation`) to match the JSON schema; no
+      // camelCase fallback because all generator pipelines write the
+      // canonical form.
+      const documentation = typeof def.documentation === 'string' && def.documentation.length > 0
+        ? def.documentation
+        : null;
       const validation = def.validation || null;
       const metadata = def.metadata || null;
       const extensions = Array.isArray(def.extensions) ? def.extensions : [];
@@ -1404,7 +1413,7 @@ function resolveMediaUrn(mediaUrn, mediaSpecs = []) {
         );
       }
 
-      return new MediaSpec(mediaType, profileUri, schema, title, description, mediaUrn, validation, metadata, extensions);
+      return new MediaSpec(mediaType, profileUri, schema, title, description, mediaUrn, validation, metadata, extensions, documentation);
     }
   }
 
@@ -1888,11 +1897,12 @@ class Cap {
    * @param {CapUrn} urn - The capability URN
    * @param {string} title - The human-readable title (required)
    * @param {string} command - The command string
-   * @param {string|null} capDescription - Optional description
+   * @param {string|null} capDescription - Optional short plain-text description
    * @param {Object} metadata - Optional metadata object
    * @param {Object|null} metadataJson - Optional arbitrary metadata as JSON object
+   * @param {string|null} documentation - Optional long-form markdown documentation. Rendered in capability info panels, the cap navigator, capdag-dot-com, and anywhere else a rich-text explanation of the cap is useful.
    */
-  constructor(urn, title, command, capDescription = null, metadata = {}, metadataJson = null) {
+  constructor(urn, title, command, capDescription = null, metadata = {}, metadataJson = null, documentation = null) {
     if (!(urn instanceof CapUrn)) {
       throw new Error('URN must be a CapUrn instance');
     }
@@ -1907,6 +1917,7 @@ class Cap {
     this.title = title;
     this.command = command;
     this.cap_description = capDescription;
+    this.documentation = documentation;
     this.metadata = metadata || {};
     this.mediaSpecs = [];  // Media spec definitions array
     this.args = [];  // Array of CapArg - unified argument format
@@ -1915,6 +1926,31 @@ class Cap {
     this.registered_by = null;  // Registration attribution
   }
 
+  /**
+   * Get the long-form markdown documentation, if any.
+   * @returns {string|null}
+   */
+  getDocumentation() {
+    return this.documentation;
+  }
+
+  /**
+   * Set the long-form markdown documentation.
+   * @param {string|null} documentation
+   */
+  setDocumentation(documentation) {
+    this.documentation = (typeof documentation === 'string' && documentation.length > 0)
+      ? documentation
+      : null;
+  }
+
+  /**
+   * Clear the long-form markdown documentation.
+   */
+  clearDocumentation() {
+    this.documentation = null;
+  }
+
   /**
    * Get the media type expected for stdin (derived from args with stdin source)
    * @returns {string|null} The media URN for stdin, or null if cap doesn't accept stdin
@@ -2098,6 +2134,7 @@ class Cap {
            this.title === other.title &&
            this.command === other.command &&
            this.cap_description === other.cap_description &&
+           this.documentation === other.documentation &&
            JSON.stringify(this.metadata) === JSON.stringify(other.metadata) &&
            JSON.stringify(this.mediaSpecs) === JSON.stringify(other.mediaSpecs) &&
            JSON.stringify(this.args.map(a => a.toJSON())) === JSON.stringify(other.args.map(a => a.toJSON())) &&
@@ -2122,6 +2159,12 @@ class Cap {
       output: this.output
     };
 
+    // Long-form markdown documentation. Only emitted when set, to match
+    // the Rust serializer which skips this field when None.
+    if (typeof this.documentation === 'string' && this.documentation.length > 0) {
+      result.documentation = this.documentation;
+    }
+
     if (this.metadata_json !== null && this.metadata_json !== undefined) {
       result.metadata_json = this.metadata_json;
     }
@@ -2141,7 +2184,10 @@ class Cap {
     }
     const urn = CapUrn.fromString(json.urn);
 
-    const cap = new Cap(urn, json.title, json.command, json.cap_description, json.metadata, json.metadata_json);
+    const documentation = (typeof json.documentation === 'string' && json.documentation.length > 0)
+      ? json.documentation
+      : null;
+    const cap = new Cap(urn, json.title, json.command, json.cap_description, json.metadata, json.metadata_json, documentation);
     cap.mediaSpecs = json.media_specs || json.mediaSpecs || [];
     // Parse args (new format)
     if (json.args && Array.isArray(json.args)) {
@@ -4648,6 +4694,64 @@ class Machine {
     return lines.join('\n');
   }
 
+  /**
+   * Serialize this machine graph to machine notation in the specified format.
+   *
+   * The output is deterministic: same graph + same format → same string.
+   * @param {'bracketed' | 'line-based'} format - The notation format to use.
+   * @returns {string}
+   */
+  toMachineNotationFormatted(format) {
+    if (this._edges.length === 0) {
+      return '';
+    }
+
+    const { aliases, nodeNames, edgeOrder } = this._buildSerializationMaps();
+    const bracketed = format === 'bracketed';
+    const open = bracketed ? '[' : '';
+    const close = bracketed ? ']' : '';
+    const lines = [];
+
+    // Emit headers in alias-sorted order
+    const sortedAliases = Array.from(aliases.entries()).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+
+    for (const [alias, { edgeIdx }] of sortedAliases) {
+      const edge = this._edges[edgeIdx];
+      lines.push(`${open}${alias} ${edge.capUrn}${close}`);
+    }
+
+    // Emit wirings in edge order
+    for (const edgeIdx of edgeOrder) {
+      const edge = this._edges[edgeIdx];
+      let alias = null;
+      for (const [a, info] of aliases) {
+        if (info.edgeIdx === edgeIdx) {
+          alias = a;
+          break;
+        }
+      }
+
+      const sources = edge.sources.map(s => {
+        const key = s.toString();
+        return nodeNames.get(key);
+      });
+
+      const targetKey = edge.target.toString();
+      const targetName = nodeNames.get(targetKey);
+
+      const loopPrefix = edge.isLoop ? 'LOOP ' : '';
+
+      if (sources.length === 1) {
+        lines.push(`${open}${sources[0]} -> ${loopPrefix}${alias} -> ${targetName}${close}`);
+      } else {
+        const group = sources.join(', ');
+        lines.push(`${open}(${group}) -> ${loopPrefix}${alias} -> ${targetName}${close}`);
+      }
+    }
+
+    return bracketed ? lines.join('') : lines.join('\n');
+  }
+
   /**
    * Build the alias map, node name map, and edge ordering for serialization.
    *

package/capdag.test.js

@@ -1836,6 +1836,86 @@ function testJS_capJSONSerialization() {
   assertEqual(restored.urn.getOutSpec(), MEDIA_OBJECT, 'Should restore outSpec');
 }
 
+// JS round-trip for the documentation field on Cap. Mirrors TEST920 in
+// capdag/src/cap/definition.rs — the body is non-trivial (newlines,
+// backticks, embedded quotes, Unicode) so escaping mismatches between
+// JSON.stringify on this side and the Rust serializer on the other side
+// surface as failures here.
+function testJS_capDocumentationRoundTrip() {
+  const urn = CapUrn.fromString(testUrn('op=documented'));
+  const cap = new Cap(urn, 'Documented Cap', 'documented');
+  const body = '# Documented Cap\r\n\nDoes the thing.\n\n```bash\necho "hi"\n```\n\nSee also: \u2605\n';
+  cap.setDocumentation(body);
+  assertEqual(cap.getDocumentation(), body, 'Setter must store the body verbatim');
+
+  const json = cap.toJSON();
+  assertEqual(json.documentation, body, 'toJSON must include documentation when set');
+
+  // Stringify and parse to simulate writing to disk and reading back.
+  const wireJson = JSON.parse(JSON.stringify(json));
+  const restored = Cap.fromJSON(wireJson);
+  assertEqual(restored.getDocumentation(), body, 'fromJSON must preserve documentation body verbatim');
+  assert(restored.equals(cap), 'Round-tripped cap must equal the original');
+}
+
+// When documentation is null, toJSON must omit the field entirely. This
+// matches the Rust serializer's skip-when-None semantics and the ObjC
+// toDictionary behaviour. A regression where null is emitted as
+// `documentation: null` would break the symmetric round-trip with Rust
+// (which has no null sentinel) and pollute generated JSON.
+function testJS_capDocumentationOmittedWhenNull() {
+  const urn = CapUrn.fromString(testUrn('op=undocumented'));
+  const cap = new Cap(urn, 'Undocumented Cap', 'undocumented');
+  assertEqual(cap.getDocumentation(), null, 'Default documentation must be null');
+
+  const json = cap.toJSON();
+  assert(!('documentation' in json), 'toJSON must omit documentation key when null');
+
+  // fromJSON of a missing key must yield null, not undefined or empty string.
+  const restored = Cap.fromJSON(JSON.parse(JSON.stringify(json)));
+  assertEqual(restored.getDocumentation(), null, 'Missing documentation must round-trip as null');
+
+  // Empty-string body is treated as absent (matches the resolver's
+  // non-empty-string-only rule). This catches code paths that would store
+  // an empty string and then emit it as a literal field.
+  cap.setDocumentation('');
+  assertEqual(cap.getDocumentation(), null, 'Empty string must collapse to null');
+}
+
+// Documentation propagates from a mediaSpecs definition through
+// resolveMediaUrn into the resolved MediaSpec. Mirrors TEST924 on the Rust
+// side. This is the path every UI consumer uses, so a break here makes the
+// new field invisible everywhere downstream.
+function testJS_mediaSpecDocumentationPropagatesThroughResolve() {
+  const body = '## Markdown body\n\nWith `code` and a [link](https://example.com).';
+  const mediaSpecs = [
+    {
+      urn: 'media:doc-test;textable',
+      media_type: 'text/plain',
+      title: 'Documented',
+      description: 'short desc',
+      documentation: body
+    }
+  ];
+
+  const resolved = resolveMediaUrn('media:doc-test;textable', mediaSpecs);
+  assertEqual(resolved.documentation, body, 'documentation must propagate into MediaSpec');
+  // The short description must remain distinct from the long markdown
+  // body — they are different fields with different semantics.
+  assertEqual(resolved.description, 'short desc', 'description must remain distinct from documentation');
+
+  // Missing documentation must collapse to null, not '' or undefined.
+  const noDoc = resolveMediaUrn('media:doc-test;textable', [
+    { urn: 'media:doc-test;textable', media_type: 'text/plain', title: 'No Doc' }
+  ]);
+  assertEqual(noDoc.documentation, null, 'Missing documentation must resolve to null');
+
+  const emptyDoc = resolveMediaUrn('media:doc-test;textable', [
+    { urn: 'media:doc-test;textable', media_type: 'text/plain', title: 'Empty', documentation: '' }
+  ]);
+  assertEqual(emptyDoc.documentation, null, 'Empty documentation string must collapse to null');
+}
+
 function testJS_stdinSourceKindConstants() {
   assert(StdinSourceKind.DATA !== undefined, 'DATA kind should be defined');
   assert(StdinSourceKind.FILE_REFERENCE !== undefined, 'FILE_REFERENCE kind should be defined');
@@ -2793,6 +2873,117 @@ function testMachine_unterminatedBracketFails() {
   );
 }
 
+// --- Machine parser line-based mode tests ---
+
+function testMachine_lineBasedSimpleChain() {
+  const g = Machine.fromString(
+    'extract cap:in="media:pdf";op=extract;out="media:txt;textable"\n' +
+    'doc -> extract -> text'
+  );
+  assertEqual(g.edgeCount(), 1);
+  const edge = g.edges()[0];
+  assert(edge.sources[0].isEquivalent(MediaUrn.fromString('media:pdf')),
+    'Source should be media:pdf');
+  assert(edge.target.isEquivalent(MediaUrn.fromString('media:txt;textable')),
+    'Target should be media:txt;textable');
+}
+
+function testMachine_lineBasedTwoStepChain() {
+  const g = Machine.fromString(
+    'extract cap:in="media:pdf";op=extract;out="media:txt;textable"\n' +
+    'embed cap:in="media:txt;textable";op=embed;out="media:embedding-vector;record;textable"\n' +
+    'doc -> extract -> text\n' +
+    'text -> embed -> vectors'
+  );
+  assertEqual(g.edgeCount(), 2);
+}
+
+function testMachine_lineBasedLoop() {
+  const g = Machine.fromString(
+    'p2t cap:in="media:disbound-page;textable";op=page_to_text;out="media:txt;textable"\n' +
+    'pages -> LOOP p2t -> texts'
+  );
+  assertEqual(g.edgeCount(), 1);
+  assertEqual(g.edges()[0].isLoop, true);
+}
+
+function testMachine_lineBasedFanIn() {
+  const g = Machine.fromString(
+    'thumb cap:in="media:pdf";op=generate_thumbnail;out="media:image;png;thumbnail"\n' +
+    'model_dl cap:in="media:model-spec;textable";op=download;out="media:model-spec;textable"\n' +
+    'describe cap:in="media:image;png";op=describe_image;out="media:image-description;textable"\n' +
+    'doc -> thumb -> thumbnail\n' +
+    'spec_input -> model_dl -> model_spec\n' +
+    '(thumbnail, model_spec) -> describe -> description'
+  );
+  assertEqual(g.edgeCount(), 3);
+  assertEqual(g.edges()[2].sources.length, 2);
+}
+
+function testMachine_mixedBracketedAndLineBased() {
+  const g = Machine.fromString(
+    '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]\n' +
+    'doc -> extract -> text'
+  );
+  assertEqual(g.edgeCount(), 1);
+}
+
+function testMachine_lineBasedEquivalentToBracketed() {
+  const g1 = Machine.fromString(
+    '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]' +
+    '[doc -> extract -> text]'
+  );
+  const g2 = Machine.fromString(
+    'extract cap:in="media:pdf";op=extract;out="media:txt;textable"\n' +
+    'doc -> extract -> text'
+  );
+  assert(g1.isEquivalent(g2), 'Line-based and bracketed must produce equivalent graphs');
+}
+
+function testMachine_lineBasedFormatSerialization() {
+  const g = new Machine([
+    new MachineEdge(
+      [MediaUrn.fromString('media:pdf')],
+      CapUrn.fromString('cap:in="media:pdf";op=extract;out="media:txt;textable"'),
+      MediaUrn.fromString('media:txt;textable'),
+      false
+    ),
+  ]);
+  const lineBased = g.toMachineNotationFormatted('line-based');
+  assert(!lineBased.includes('['), 'Line-based format must not contain brackets');
+  assert(!lineBased.includes(']'), 'Line-based format must not contain brackets');
+  assert(lineBased.includes('extract cap:'), 'Should contain header');
+  assert(lineBased.includes('-> extract ->'), 'Should contain wiring');
+
+  // Round-trip
+  const reparsed = Machine.fromString(lineBased);
+  assert(g.isEquivalent(reparsed), 'Line-based round-trip must produce equivalent graph');
+}
+
+function testMachine_lineBasedAndBracketedParseSameGraph() {
+  const g = new Machine([
+    new MachineEdge(
+      [MediaUrn.fromString('media:pdf')],
+      CapUrn.fromString('cap:in="media:pdf";op=extract;out="media:txt;textable"'),
+      MediaUrn.fromString('media:txt;textable'),
+      false
+    ),
+    new MachineEdge(
+      [MediaUrn.fromString('media:txt;textable')],
+      CapUrn.fromString('cap:in="media:txt;textable";op=embed;out="media:embedding-vector;record;textable"'),
+      MediaUrn.fromString('media:embedding-vector;record;textable'),
+      false
+    ),
+  ]);
+  const bracketed = g.toMachineNotationFormatted('bracketed');
+  const lineBased = g.toMachineNotationFormatted('line-based');
+
+  const gBracketed = Machine.fromString(bracketed);
+  const gLineBased = Machine.fromString(lineBased);
+  assert(gBracketed.isEquivalent(gLineBased),
+    'Bracketed and line-based must parse to equivalent graphs');
+}
+
 // --- Machine graph tests (mirrors graph.rs tests) ---
 
 function testMachine_edgeEquivalenceSameUrns() {
@@ -3552,6 +3743,595 @@ function assertThrowsWithCode(fn, expectedCode) {
   }
 }
 
+// ============================================================================
+// cap-graph-renderer helpers — pure functions that do not require a DOM.
+// The renderer class itself needs cytoscape + DOM and is exercised by hand
+// in the browser; these tests cover the pure data transforms underneath it.
+// ============================================================================
+
+const {
+  cardinalityLabel: rendererCardinalityLabel,
+  cardinalityFromCap: rendererCardinalityFromCap,
+  canonicalMediaUrn: rendererCanonicalMediaUrn,
+  mediaNodeLabel: rendererMediaNodeLabel,
+  buildStrandGraphData: rendererBuildStrandGraphData,
+  buildRunGraphData: rendererBuildRunGraphData,
+  buildMachineGraphData: rendererBuildMachineGraphData,
+  classifyStrandCapSteps: rendererClassifyStrandCapSteps,
+  validateStrandPayload: rendererValidateStrandPayload,
+  validateRunPayload: rendererValidateRunPayload,
+  validateMachinePayload: rendererValidateMachinePayload,
+  validateStrandStep: rendererValidateStrandStep,
+  validateBodyOutcome: rendererValidateBodyOutcome,
+} = require('./cap-graph-renderer.js');
+
+// The renderer module reads its dependencies off `window` or `global` at
+// call time (it is browser-first). Node has no window, so we install the
+// needed capdag-js classes on `global` before the tests run. Every
+// renderer path exercised by the tests resolves through these.
+if (typeof global.TaggedUrn === 'undefined') {
+  global.TaggedUrn = require('tagged-urn').TaggedUrn;
+}
+if (typeof global.MediaUrn === 'undefined') global.MediaUrn = MediaUrn;
+if (typeof global.CapUrn === 'undefined') global.CapUrn = CapUrn;
+if (typeof global.Cap === 'undefined') global.Cap = Cap;
+if (typeof global.CapGraph === 'undefined') global.CapGraph = CapGraph;
+// Reference the top-of-file destructured createCap via the module export.
+if (typeof global.createCap === 'undefined') {
+  global.createCap = require('./capdag.js').createCap;
+}
+
+function testRenderer_cardinalityLabel_allFourCases() {
+  assertEqual(rendererCardinalityLabel(false, false), '1\u21921', 'scalar-to-scalar');
+  assertEqual(rendererCardinalityLabel(true, false),  'n\u21921', 'sequence-to-scalar');
+  assertEqual(rendererCardinalityLabel(false, true),  '1\u2192n', 'scalar-to-sequence');
+  assertEqual(rendererCardinalityLabel(true, true),   'n\u2192n', 'sequence-to-sequence');
+}
+
+function testRenderer_cardinalityLabel_usesUnicodeArrow() {
+  // The label must use the real rightwards arrow (U+2192), not ASCII "->".
+  // Downstream styling and tests depend on this glyph.
+  const label = rendererCardinalityLabel(false, true);
+  assert(label.includes('\u2192'), 'label should contain U+2192 rightwards arrow');
+  assert(!label.includes('->'), 'label must not contain the ASCII replacement "->"');
+}
+
+function testRenderer_cardinalityFromCap_findsStdinArgNotFirstArg() {
+  // The main input arg is the one whose sources include a stdin source.
+  // A naive implementation that reads args[0] would see `cli-only` (not a
+  // sequence) and report 1→1 even though the stdin arg is a sequence.
+  const cap = {
+    urn: 'cap:in="media:textable;list";op=transcribe;out="media:textable"',
+    args: [
+      {
+        display_name: 'cli-only',
+        is_sequence: false,
+        sources: [{ cli_flag: '--mode' }],
+      },
+      {
+        display_name: 'main-input',
+        is_sequence: true,
+        sources: [{ stdin: {} }],
+      },
+    ],
+    output: { is_sequence: false },
+  };
+  assertEqual(rendererCardinalityFromCap(cap), 'n\u21921',
+    'must pick the arg that has a stdin source, not args[0]');
+}
+
+function testRenderer_cardinalityFromCap_scalarDefaultsWhenFieldsMissing() {
+  // No args and no output: both sides collapse to 1 (scalar default).
+  // If a bug makes the function return "n" for missing data, this fails.
+  const cap = { urn: 'cap:in="media:";op=noop;out="media:"' };
+  assertEqual(rendererCardinalityFromCap(cap), '1\u21921',
+    'missing args/output must default to scalar on both sides');
+}
+
+function testRenderer_cardinalityFromCap_outputOnlySequence() {
+  // One scalar stdin arg, output is a sequence: expects 1→n.
+  const cap = {
+    urn: 'cap:in="media:textable";op=generate;out="media:textable;list"',
+    args: [{ sources: [{ stdin: {} }], is_sequence: false }],
+    output: { is_sequence: true },
+  };
+  assertEqual(rendererCardinalityFromCap(cap), '1\u2192n',
+    'scalar stdin with sequence output must yield 1→n');
+}
+
+function testRenderer_cardinalityFromCap_rejectsStringIsSequence() {
+  // The function must use strict `=== true` to avoid treating truthy strings
+  // as booleans. "true" is a string, not a boolean — it must NOT be treated
+  // as a sequence, because downstream renderers expect boolean semantics.
+  const cap = {
+    urn: 'cap:in="media:";op=x;out="media:"',
+    args: [{ sources: [{ stdin: {} }], is_sequence: 'true' }],
+    output: { is_sequence: 'true' },
+  };
+  assertEqual(rendererCardinalityFromCap(cap), '1\u21921',
+    'string "true" must not be treated as boolean true');
+}
+
+function testRenderer_cardinalityFromCap_throwsOnNonObject() {
+  // Fail-hard on invalid input; no fallback to a default cardinality.
+  let threw = false;
+  try {
+    rendererCardinalityFromCap(null);
+  } catch (e) {
+    threw = true;
+  }
+  assert(threw, 'cardinalityFromCap(null) must throw');
+
+  threw = false;
+  try {
+    rendererCardinalityFromCap('not-an-object');
+  } catch (e) {
+    threw = true;
+  }
+  assert(threw, 'cardinalityFromCap(string) must throw');
+}
+
+function testRenderer_canonicalMediaUrn_normalizesTagOrder() {
+  // Two media URNs with identical tags in different input orders must
+  // produce the same canonical string. If canonicalization is bypassed,
+  // the two strings remain different and this test exposes it.
+  const a = rendererCanonicalMediaUrn('media:video;h264;list');
+  const b = rendererCanonicalMediaUrn('media:list;h264;video');
+  assertEqual(a, b, 'tag-order differences must not survive canonicalization');
+}
+
+function testRenderer_canonicalMediaUrn_preservesValueTags() {
+  const c = rendererCanonicalMediaUrn('media:model;quant=q4');
+  assert(c.includes('quant=q4'), 'value tag must be preserved');
+}
+
+function testRenderer_canonicalMediaUrn_rejectsCapUrn() {
+  // MediaUrn.fromString enforces the media: prefix. Feeding a cap URN to
+  // canonicalMediaUrn must fail hard.
+  let threw = false;
+  try {
+    rendererCanonicalMediaUrn('cap:op=x;in="media:";out="media:"');
+  } catch (e) {
+    threw = true;
+  }
+  assert(threw, 'canonicalMediaUrn must reject non-media URNs');
+}
+
+function testRenderer_mediaNodeLabel_oneLinePerTag_valueAndMarker() {
+  // A media URN with one value tag and one marker tag renders two lines:
+  // value tag as "key: value", marker tag as bare key. Order is canonical
+  // (alphabetical, matching TaggedUrn's sorted key iteration).
+  const label = rendererMediaNodeLabel('media:video;quant=q4');
+  const lines = label.split('\n');
+  assertEqual(lines.length, 2, 'two tags must produce two lines');
+  assert(lines.includes('quant: q4'), 'value tag rendered as key: value');
+  assert(lines.includes('video'),     'marker tag rendered as bare key');
+}
+
+function testRenderer_mediaNodeLabel_stableAcrossTagOrder() {
+  // Labels must be tag-order-independent so that the same media URN
+  // produces the same multi-line label regardless of how the source
+  // happened to spell it.
+  const a = rendererMediaNodeLabel(rendererCanonicalMediaUrn('media:list;textable'));
+  const b = rendererMediaNodeLabel(rendererCanonicalMediaUrn('media:textable;list'));
+  assertEqual(a, b, 'label must be stable across tag orderings');
+}
+
+// ---------------- strand builder ----------------
+
+function makeCapStep(capUrn, title, fromSpec, toSpec, inSeq, outSeq) {
+  return {
+    step_type: {
+      Cap: {
+        cap_urn: capUrn,
+        title,
+        specificity: 0,
+        input_is_sequence: inSeq,
+        output_is_sequence: outSeq,
+      },
+    },
+    from_spec: fromSpec,
+    to_spec: toSpec,
+  };
+}
+
+function makeForEachStep(mediaSpec) {
+  return {
+    step_type: { ForEach: { media_spec: mediaSpec } },
+    from_spec: mediaSpec,
+    to_spec: mediaSpec,
+  };
+}
+
+function makeCollectStep(mediaSpec) {
+  return {
+    step_type: { Collect: { media_spec: mediaSpec } },
+    from_spec: mediaSpec,
+    to_spec: mediaSpec,
+  };
+}
+
+function testRenderer_validateStrandStep_rejectsUnknownVariant() {
+  // A step with an unknown variant must fail hard at validation; no
+  // silent coercion.
+  let threw = false;
+  try {
+    rendererValidateStrandStep({
+      step_type: { WrongVariant: {} },
+      from_spec: 'media:a',
+      to_spec: 'media:a',
+    }, 'test');
+  } catch (e) {
+    threw = true;
+    assert(e.message.includes('WrongVariant'), 'error must name the bad variant');
+  }
+  assert(threw, 'unknown variant must throw');
+}
+
+function testRenderer_validateStrandStep_requiresBooleanIsSequence() {
+  // A Cap variant must have boolean is_sequence fields; number or string
+  // must reject.
+  let threw = false;
+  try {
+    rendererValidateStrandStep({
+      step_type: { Cap: {
+        cap_urn: 'cap:in="media:a";op=x;out="media:b"',
+        title: 't',
+        input_is_sequence: 1,  // number, not boolean
+        output_is_sequence: false,
+      }},
+      from_spec: 'media:a',
+      to_spec: 'media:b',
+    }, 'test');
+  } catch (e) {
+    threw = true;
+    assert(e.message.includes('input_is_sequence'), 'error must name the bad field');
+  }
+  assert(threw, 'non-boolean is_sequence must throw');
+}
+
+function testRenderer_classifyStrandCapSteps_capFlags() {
+  // Strand: ForEach → cap1 → cap2 → cap3 → Collect. cap1 should have
+  // prevForEach=true; cap3 should have nextCollect=true; cap2 should
+  // have neither.
+  const steps = [
+    makeForEachStep('media:pdf;list'),
+    makeCapStep('cap:in="media:pdf";op=a;out="media:png"', 'a', 'media:pdf', 'media:png', false, false),
+    makeCapStep('cap:in="media:png";op=b;out="media:jpg"', 'b', 'media:png', 'media:jpg', false, false),
+    makeCapStep('cap:in="media:jpg";op=c;out="media:txt"', 'c', 'media:jpg', 'media:txt', false, false),
+    makeCollectStep('media:txt'),
+  ];
+  const { capStepIndices, capFlags } = rendererClassifyStrandCapSteps(steps);
+  assertEqual(capStepIndices.length, 3, 'three cap steps');
+  assert(capFlags.get(1).prevForEach, 'cap1 has prevForEach');
+  assert(!capFlags.get(1).nextCollect, 'cap1 has no nextCollect');
+  assert(!capFlags.get(2).prevForEach, 'cap2 has no prevForEach');
+  assert(!capFlags.get(2).nextCollect, 'cap2 has no nextCollect');
+  assert(!capFlags.get(3).prevForEach, 'cap3 has no prevForEach');
+  assert(capFlags.get(3).nextCollect, 'cap3 has nextCollect');
+}
+
+function testRenderer_classifyStrandCapSteps_nestedForks() {
+  // Nested strand: ForEach → cap1 → ForEach → cap2 → Collect → cap3 → Collect.
+  // cap1 has prevForEach (outer), cap2 has prevForEach (inner) and
+  // nextCollect (inner), cap3 has nextCollect (outer).
+  const steps = [
+    makeForEachStep('media:a;list'),
+    makeCapStep('cap:in="media:a";op=a;out="media:b"', 'a', 'media:a', 'media:b', false, false),
+    makeForEachStep('media:b;list'),
+    makeCapStep('cap:in="media:b";op=b;out="media:c"', 'b', 'media:b', 'media:c', false, false),
+    makeCollectStep('media:c'),
+    makeCapStep('cap:in="media:c";op=c;out="media:d"', 'c', 'media:c', 'media:d', false, false),
+    makeCollectStep('media:d'),
+  ];
+  const { capFlags } = rendererClassifyStrandCapSteps(steps);
+  assert(capFlags.get(1).prevForEach && !capFlags.get(1).nextCollect, 'cap1 outer entry');
+  assert(capFlags.get(3).prevForEach && capFlags.get(3).nextCollect, 'cap2 inner both');
+  assert(!capFlags.get(5).prevForEach && capFlags.get(5).nextCollect, 'cap3 outer exit');
+}
+
+function testRenderer_buildStrandGraphData_labelsForkBoundaries() {
+  // End-to-end: a foreach strand in which source_spec (media:pdf;list)
+  // differs from the first cap's from_spec (media:pdf) produces an
+  // explicit fix-up edge source→firstCap.from labeled "for each". The
+  // cap edge carries only the cap title. The topology is
+  //   media:pdf;list --[for each]--> media:pdf --[extract text]--> media:txt
+  // Only two edges — ForEach is NOT a separate node, Collect is absent
+  // because the strand's target_spec already matches the last cap's
+  // to_spec (no fan-in fix-up needed).
+  const payload = {
+    source_spec: 'media:pdf;list',
+    target_spec: 'media:txt',
+    steps: [
+      makeForEachStep('media:pdf;list'),
+      makeCapStep('cap:in="media:pdf";op=extract;out="media:txt"', 'extract text', 'media:pdf', 'media:txt', false, false),
+    ],
+  };
+  const built = rendererBuildStrandGraphData(payload);
+  assertEqual(built.edges.length, 2, 'one fix-up edge + one cap edge');
+  const forEachEdge = built.edges[0];
+  assertEqual(forEachEdge.label, 'for each', 'first edge is the for-each fan-out');
+  assertEqual(forEachEdge.source, 'media:pdf;list', 'for-each sources from source_spec');
+  assertEqual(forEachEdge.target, 'media:pdf', 'for-each targets first cap.from_spec');
+  const capEdge = built.edges[1];
+  assertEqual(capEdge.label, 'extract text', 'cap edge carries only the cap title');
+  assertEqual(capEdge.source, 'media:pdf', 'cap sources from its from_spec');
+  assertEqual(capEdge.target, 'media:txt', 'cap targets its to_spec');
+}
+
+function testRenderer_buildStrandGraphData_collectFixupEdge() {
+  // When the strand's target_spec (media:pdf;list) differs from the
+  // last cap's to_spec (media:pdf), the builder emits an explicit
+  // fix-up edge lastCap.to → target labeled "collect".
+  const payload = {
+    source_spec: 'media:a',
+    target_spec: 'media:pdf;list',
+    steps: [
+      makeCapStep('cap:in="media:a";op=x;out="media:pdf"', 'x', 'media:a', 'media:pdf', false, false),
+      makeCollectStep('media:pdf'),
+    ],
+  };
+  const built = rendererBuildStrandGraphData(payload);
+  assertEqual(built.edges.length, 2, 'one cap edge + one collect fix-up');
+  const capEdge = built.edges[0];
+  assertEqual(capEdge.label, 'x', 'cap edge plain title');
+  const collectEdge = built.edges[1];
+  assertEqual(collectEdge.label, 'collect', 'collect fix-up labeled "collect"');
+  assertEqual(collectEdge.source, 'media:pdf', 'collect sources from last cap.to_spec');
+  assertEqual(collectEdge.target, 'media:pdf;list', 'collect targets target_spec');
+}
+
+function testRenderer_buildStrandGraphData_plainCapNoMarker() {
+  // A plain 1→1 cap step (no ForEach/Collect adjacency, no sequence)
+  // must not emit any cardinality marker in the label. This catches a
+  // regression where "1→1" was accidentally appended to every edge.
+  const payload = {
+    source_spec: 'media:a',
+    target_spec: 'media:b',
+    steps: [
+      makeCapStep('cap:in="media:a";op=x;out="media:b"', 'x', 'media:a', 'media:b', false, false),
+    ],
+  };
+  const built = rendererBuildStrandGraphData(payload);
+  assertEqual(built.edges.length, 1, 'one edge');
+  assertEqual(built.edges[0].label, 'x', 'plain cap has no cardinality suffix');
+}
+
+function testRenderer_buildStrandGraphData_sequenceShowsCardinality() {
+  // A cap with input_is_sequence=true MUST emit "(n→1)" on the label.
+  const payload = {
+    source_spec: 'media:a;list',
+    target_spec: 'media:b',
+    steps: [
+      makeCapStep('cap:in="media:a;list";op=x;out="media:b"', 'x', 'media:a;list', 'media:b', true, false),
+    ],
+  };
+  const built = rendererBuildStrandGraphData(payload);
+  assertEqual(built.edges.length, 1, 'one edge');
+  assert(built.edges[0].label.includes('(n\u21921)'),
+    `edge label must include (n\u21921) marker; got: ${built.edges[0].label}`);
+}
+
+function testRenderer_validateStrandPayload_missingSourceSpec() {
+  let threw = false;
+  try {
+    rendererValidateStrandPayload({ target_spec: 'media:b', steps: [] });
+  } catch (e) {
+    threw = true;
+    assert(e.message.includes('source_spec'), 'error must name source_spec');
+  }
+  assert(threw, 'missing source_spec must throw');
+}
+
+// ---------------- run builder ----------------
+
+function testRenderer_validateBodyOutcome_rejectsNegativeIndex() {
+  let threw = false;
+  try {
+    rendererValidateBodyOutcome({ body_index: -1, success: true, cap_urns: [] }, 'test');
+  } catch (e) {
+    threw = true;
+  }
+  assert(threw, 'negative body_index must throw');
+}
+
+function testRenderer_buildRunGraphData_pagesSuccessesAndFailures() {
+  // 6 successes, 4 failures. visible_success_count=3, visible_failure_count=2,
+  // total_body_count=10. The builder must:
+  //  - render exactly 3 success replicas (one node per cap step per body)
+  //  - render exactly 2 failure replicas
+  //  - emit a success show-more node with hidden count 3
+  //  - emit a failure show-more node with hidden count 2
+  const strand = {
+    source_spec: 'media:pdf;list',
+    target_spec: 'media:txt',
+    steps: [
+      makeForEachStep('media:pdf;list'),
+      makeCapStep('cap:in="media:pdf";op=a;out="media:png"', 'a', 'media:pdf', 'media:png', false, false),
+      makeCapStep('cap:in="media:png";op=b;out="media:txt"', 'b', 'media:png', 'media:txt', false, false),
+      makeCollectStep('media:txt'),
+    ],
+  };
+  const outcomes = [];
+  for (let i = 0; i < 6; i++) {
+    outcomes.push({ body_index: i, success: true, cap_urns: [], saved_paths: [], total_bytes: 0, duration_ms: 0 });
+  }
+  for (let i = 6; i < 10; i++) {
+    outcomes.push({
+      body_index: i,
+      success: false,
+      cap_urns: [],
+      saved_paths: [],
+      total_bytes: 0,
+      duration_ms: 0,
+      failed_cap: 'cap:in="media:png";op=b;out="media:txt"',
+      error: 'oom',
+    });
+  }
+  const payload = {
+    resolved_strand: strand,
+    body_outcomes: outcomes,
+    visible_success_count: 3,
+    visible_failure_count: 2,
+    total_body_count: 10,
+  };
+  const built = rendererBuildRunGraphData(payload);
+
+  // Count replica nodes by classes.
+  let successNodes = 0;
+  let failureNodes = 0;
+  for (const n of built.replicaNodes) {
+    if (n.classes === 'body-success') successNodes++;
+    if (n.classes === 'body-failure') failureNodes++;
+  }
+  assertEqual(successNodes, 3 * 2, 'three successful bodies × two cap steps each = 6 success nodes');
+  // Failed bodies truncate at failed_cap (cap b = second cap), so trace
+  // length includes both cap a and cap b → 2 nodes per failed body.
+  assertEqual(failureNodes, 2 * 2, 'two failed bodies × two nodes each (trace truncated at failed_cap)');
+
+  // Show-more nodes: one for success (hidden 3), one for failure (hidden 2).
+  const successShowMore = built.showMoreNodes.find(n => n.data.showMoreGroup === 'success');
+  const failureShowMore = built.showMoreNodes.find(n => n.data.showMoreGroup === 'failure');
+  assert(successShowMore !== undefined, 'success show-more present');
+  assert(failureShowMore !== undefined, 'failure show-more present');
+  assertEqual(successShowMore.data.hiddenCount, 3, 'success hidden count = 3');
+  assertEqual(failureShowMore.data.hiddenCount, 2, 'failure hidden count = 2');
+}
+
+function testRenderer_buildRunGraphData_failureWithoutFailedCapRendersFullTrace() {
+  // A failure without failed_cap (e.g. infrastructure failure) must still
+  // render the full body trace — the builder must not crash or produce
+  // zero replicas.
+  const strand = {
+    source_spec: 'media:pdf;list',
+    target_spec: 'media:txt',
+    steps: [
+      makeForEachStep('media:pdf;list'),
+      makeCapStep('cap:in="media:pdf";op=a;out="media:txt"', 'a', 'media:pdf', 'media:txt', false, false),
+      makeCollectStep('media:txt'),
+    ],
+  };
+  const payload = {
+    resolved_strand: strand,
+    body_outcomes: [
+      { body_index: 0, success: false, cap_urns: [], saved_paths: [], total_bytes: 0, duration_ms: 0, error: 'unknown' },
+    ],
+    visible_success_count: 0,
+    visible_failure_count: 5,
+    total_body_count: 1,
+  };
+  const built = rendererBuildRunGraphData(payload);
+  let failureNodes = 0;
+  for (const n of built.replicaNodes) {
+    if (n.classes === 'body-failure') failureNodes++;
+  }
+  assertEqual(failureNodes, 1, 'full trace (one cap) renders as one failure node');
+}
+
+function testRenderer_buildRunGraphData_usesCapUrnIsEquivalentForFailedCap() {
+  // The renderer matches failed_cap against step cap URNs via
+  // CapUrn.isEquivalent, NOT string equality. Feed a payload where
+  // failed_cap and the step's cap_urn differ only in tag order — they
+  // should still match, proving URNs are not treated as strings.
+  const strand = {
+    source_spec: 'media:a',
+    target_spec: 'media:c',
+    steps: [
+      makeForEachStep('media:a;list'),
+      // Canonical form places tags alphabetically: op after in/out.
+      makeCapStep(
+        'cap:in="media:a";op=x;out="media:b"',
+        'x', 'media:a', 'media:b', false, false
+      ),
+      makeCapStep(
+        'cap:in="media:b";op=y;out="media:c"',
+        'y', 'media:b', 'media:c', false, false
+      ),
+      makeCollectStep('media:c'),
+    ],
+  };
+  // The failed_cap URN is semantically the same as step 1 (cap y). If
+  // CapUrn.fromString canonicalizes (it should), any equivalent form
+  // will match. Feed a fully-specified form that is equivalent.
+  const payload = {
+    resolved_strand: strand,
+    body_outcomes: [
+      {
+        body_index: 0,
+        success: false,
+        cap_urns: [],
+        saved_paths: [],
+        total_bytes: 0,
+        duration_ms: 0,
+        failed_cap: 'cap:in="media:b";out="media:c";op=y',  // different tag order
+        error: 'fail',
+      },
+    ],
+    visible_success_count: 0,
+    visible_failure_count: 1,
+    total_body_count: 1,
+  };
+  const built = rendererBuildRunGraphData(payload);
+  let failureNodes = 0;
+  for (const n of built.replicaNodes) {
+    if (n.classes === 'body-failure') failureNodes++;
+  }
+  // cap x + cap y = 2 nodes for a body trace that terminates at cap y.
+  assertEqual(failureNodes, 2, 'trace truncates at cap y via isEquivalent, yielding 2 failure nodes');
+}
+
+// ---------------- machine builder ----------------
+
+function testRenderer_validateMachinePayload_rejectsUnknownKind() {
+  let threw = false;
+  try {
+    rendererValidateMachinePayload({
+      elements: [{ kind: 'widget', graph_id: 'w1' }],
+    });
+  } catch (e) {
+    threw = true;
+    assert(e.message.includes('widget') || e.message.includes('kind'),
+      'error must name the bad kind');
+  }
+  assert(threw, 'unknown element kind must throw');
+}
+
+function testRenderer_buildMachineGraphData_preservesTokenIds() {
+  // Token IDs are the bridge for editor cross-highlighting. Every
+  // element MUST carry its tokenId through into the cytoscape data.
+  const data = {
+    elements: [
+      { kind: 'node', graph_id: 'n1', label: 'a', token_id: 't-node-a' },
+      { kind: 'cap',  graph_id: 'c1', label: 'fn', token_id: 't-cap-fn' },
+      { kind: 'edge', graph_id: 'e1', source_graph_id: 'n1', target_graph_id: 'c1', label: '', token_id: 't-edge-1' },
+    ],
+  };
+  const built = rendererBuildMachineGraphData(data);
+  const nodeTokens = built.nodes.map(n => n.data.tokenId).sort();
+  assertEqual(JSON.stringify(nodeTokens), JSON.stringify(['t-cap-fn', 't-node-a']),
+    'node tokenIds must round-trip');
+  assertEqual(built.edges.length, 1, 'one edge');
+  assertEqual(built.edges[0].data.tokenId, 't-edge-1', 'edge tokenId must round-trip');
+  // Kinds are carried as element data for editor-side filtering.
+  const kinds = built.nodes.map(n => n.data.kind).sort();
+  assertEqual(JSON.stringify(kinds), JSON.stringify(['cap', 'node']),
+    'element kinds must be preserved');
+}
+
+function testRenderer_buildMachineGraphData_rejectsEdgeWithMissingSource() {
+  let threw = false;
+  try {
+    rendererBuildMachineGraphData({
+      elements: [
+        { kind: 'edge', graph_id: 'e1', target_graph_id: 't' },
+      ],
+    });
+  } catch (e) {
+    threw = true;
+  }
+  assert(threw, 'edge without source_graph_id must throw');
+}
+
 // ============================================================================
 // Test runner
 // ============================================================================
@@ -3719,6 +4499,9 @@ async function runTests() {
   runTest('JS: get_extension_mappings', testJS_getExtensionMappings);
   runTest('JS: cap_with_media_specs', testJS_capWithMediaSpecs);
   runTest('JS: cap_json_serialization', testJS_capJSONSerialization);
+  runTest('JS: cap_documentation_round_trip', testJS_capDocumentationRoundTrip);
+  runTest('JS: cap_documentation_omitted_when_null', testJS_capDocumentationOmittedWhenNull);
+  runTest('JS: media_spec_documentation_propagates_through_resolve', testJS_mediaSpecDocumentationPropagatesThroughResolve);
   runTest('JS: stdin_source_kind_constants', testJS_stdinSourceKindConstants);
   runTest('JS: stdin_source_null_data', testJS_stdinSourceNullData);
   const p1 = runTest('JS: args_passed_to_executeCap', testJS_argsPassedToExecuteCap);
@@ -3808,6 +4591,17 @@ async function runTests() {
   runTest('MACHINE:malformed_input_fails', testMachine_malformedInputFails);
   runTest('MACHINE:unterminated_bracket_fails', testMachine_unterminatedBracketFails);
 
+  // machine module: line-based mode tests
+  console.log('\n--- machine/parser.rs (line-based) ---');
+  runTest('MACHINE:line_based_simple_chain', testMachine_lineBasedSimpleChain);
+  runTest('MACHINE:line_based_two_step_chain', testMachine_lineBasedTwoStepChain);
+  runTest('MACHINE:line_based_loop', testMachine_lineBasedLoop);
+  runTest('MACHINE:line_based_fan_in', testMachine_lineBasedFanIn);
+  runTest('MACHINE:mixed_bracketed_and_line_based', testMachine_mixedBracketedAndLineBased);
+  runTest('MACHINE:line_based_equivalent_to_bracketed', testMachine_lineBasedEquivalentToBracketed);
+  runTest('MACHINE:line_based_format_serialization', testMachine_lineBasedFormatSerialization);
+  runTest('MACHINE:line_based_and_bracketed_parse_same_graph', testMachine_lineBasedAndBracketedParseSameGraph);
+
   // machine module: graph tests (mirrors graph.rs)
   console.log('\n--- machine/graph.rs ---');
   runTest('MACHINE:edge_equivalence_same_urns', testMachine_edgeEquivalenceSameUrns);
@@ -3888,6 +4682,43 @@ async function runTests() {
   runTest('REGISTRY: capRegistryClient_construction', testMachine_capRegistryClient_construction);
   runTest('REGISTRY: capRegistryEntry_defaults', testMachine_capRegistryEntry_defaults);
 
+  // cap-graph-renderer pure helpers (no DOM dependency)
+  console.log('\n--- cap-graph-renderer helpers ---');
+  runTest('RENDERER: cardinalityLabel_allFourCases',          testRenderer_cardinalityLabel_allFourCases);
+  runTest('RENDERER: cardinalityLabel_usesUnicodeArrow',      testRenderer_cardinalityLabel_usesUnicodeArrow);
+  runTest('RENDERER: cardinalityFromCap_findsStdinArg',       testRenderer_cardinalityFromCap_findsStdinArgNotFirstArg);
+  runTest('RENDERER: cardinalityFromCap_scalarDefaults',      testRenderer_cardinalityFromCap_scalarDefaultsWhenFieldsMissing);
+  runTest('RENDERER: cardinalityFromCap_outputOnlySequence',  testRenderer_cardinalityFromCap_outputOnlySequence);
+  runTest('RENDERER: cardinalityFromCap_rejectsStringBool',   testRenderer_cardinalityFromCap_rejectsStringIsSequence);
+  runTest('RENDERER: cardinalityFromCap_throwsOnNonObject',   testRenderer_cardinalityFromCap_throwsOnNonObject);
+  runTest('RENDERER: canonicalMediaUrn_normalizesTagOrder',   testRenderer_canonicalMediaUrn_normalizesTagOrder);
+  runTest('RENDERER: canonicalMediaUrn_preservesValueTags',   testRenderer_canonicalMediaUrn_preservesValueTags);
+  runTest('RENDERER: canonicalMediaUrn_rejectsCapUrn',        testRenderer_canonicalMediaUrn_rejectsCapUrn);
+  runTest('RENDERER: mediaNodeLabel_valueAndMarker',          testRenderer_mediaNodeLabel_oneLinePerTag_valueAndMarker);
+  runTest('RENDERER: mediaNodeLabel_stableAcrossTagOrder',    testRenderer_mediaNodeLabel_stableAcrossTagOrder);
+
+  console.log('\n--- cap-graph-renderer strand builder ---');
+  runTest('RENDERER: validateStrandStep_unknownVariant',      testRenderer_validateStrandStep_rejectsUnknownVariant);
+  runTest('RENDERER: validateStrandStep_booleanIsSequence',   testRenderer_validateStrandStep_requiresBooleanIsSequence);
+  runTest('RENDERER: classifyStrandCapSteps_simple',          testRenderer_classifyStrandCapSteps_capFlags);
+  runTest('RENDERER: classifyStrandCapSteps_nested',          testRenderer_classifyStrandCapSteps_nestedForks);
+  runTest('RENDERER: buildStrand_labelsForkBoundaries',       testRenderer_buildStrandGraphData_labelsForkBoundaries);
+  runTest('RENDERER: buildStrand_collectFixupEdge',           testRenderer_buildStrandGraphData_collectFixupEdge);
+  runTest('RENDERER: buildStrand_plainCapNoMarker',           testRenderer_buildStrandGraphData_plainCapNoMarker);
+  runTest('RENDERER: buildStrand_sequenceShowsCardinality',   testRenderer_buildStrandGraphData_sequenceShowsCardinality);
+  runTest('RENDERER: validateStrand_missingSourceSpec',       testRenderer_validateStrandPayload_missingSourceSpec);
+
+  console.log('\n--- cap-graph-renderer run builder ---');
+  runTest('RENDERER: validateBodyOutcome_negativeIndex',      testRenderer_validateBodyOutcome_rejectsNegativeIndex);
+  runTest('RENDERER: buildRun_pagesSuccessesAndFailures',     testRenderer_buildRunGraphData_pagesSuccessesAndFailures);
+  runTest('RENDERER: buildRun_failureWithoutFailedCap',       testRenderer_buildRunGraphData_failureWithoutFailedCapRendersFullTrace);
+  runTest('RENDERER: buildRun_usesIsEquivalentForFailedCap',  testRenderer_buildRunGraphData_usesCapUrnIsEquivalentForFailedCap);
+
+  console.log('\n--- cap-graph-renderer machine builder ---');
+  runTest('RENDERER: validateMachine_unknownKind',            testRenderer_validateMachinePayload_rejectsUnknownKind);
+  runTest('RENDERER: buildMachine_preservesTokenIds',         testRenderer_buildMachineGraphData_preservesTokenIds);
+  runTest('RENDERER: buildMachine_rejectsEdgeMissingSource',  testRenderer_buildMachineGraphData_rejectsEdgeWithMissingSource);
+
   // Summary
   console.log(`\n${passCount + failCount} tests: ${passCount} passed, ${failCount} failed`);
   if (failCount > 0) {

package/machine.pegjs

@@ -1,17 +1,26 @@
-// Bracket-delimited machine notation grammar for Peggy.
+// Machine notation grammar for Peggy.
 //
 // This grammar mirrors the Rust pest grammar in machine.pest exactly.
 // All actions return location() for LSP position tracking.
 //
-// Examples:
+// Two equally valid statement forms:
+//
+// Bracketed (one or more statements per line, any layout):
 //   [extract cap:in="media:pdf";op=extract;out="media:txt;textable"]
 //   [doc -> extract -> text]
-//   [(thumbnail, model_spec) -> describe -> description]
-//   [pages -> LOOP p2t -> texts]
+//
+// Line-based (one statement per line, no brackets):
+//   extract cap:in="media:pdf";op=extract;out="media:txt;textable"
+//   doc -> extract -> text
+//   (thumbnail, model_spec) -> describe -> description
+//   pages -> LOOP p2t -> texts
+//
+// Both forms can be freely mixed in the same program.
 
 program = _ stmts:stmt* _ { return stmts; }
 
 stmt = "[" _ inner:inner _ "]" _ { return inner; }
+     / inner:inner _ { return inner; }
 
 inner = wiring / header
 
@@ -48,11 +57,14 @@ alias = $( [a-zA-Z_] [a-zA-Z0-9_-]* )
 // Cap URN with location tracking
 cap_urn_loc = c:cap_urn { return { value: c, location: location() }; }
 
-// Cap URN: starts with "cap:", reads until the statement-closing "]",
-// except quoted strings can contain "]".
+// Cap URN: starts with "cap:", reads until a statement terminator:
+// "]" for bracketed mode, or newline for line-based mode.
+// Quoted strings can contain "]" and newlines.
 cap_urn = $( "cap:" cap_urn_body* )
 
-cap_urn_body = quoted_value / ( !"]" . )
+cap_urn_body = quoted_value / ( !"]" !NL . )
+
+NL "newline" = "\r\n" / "\n" / "\r"
 
 // Quoted strings support escaped quotes.
 quoted_value = '"' ( '\\"' / '\\\\' / (!'"' .) )* '"'

package/package.json

@@ -37,5 +37,5 @@
     "pretest": "npm run build:parser",
     "test": "node capdag.test.js"
   },
-  "version": "0.100.226"
+  "version": "0.104.240"
 }