The output half of the contract

What your result looks like.

An algorithm doesn't draw anything — it returns data shaped as blocks, and CommonSense renders them. The block kinds are a closed set: composing a result from these primitives is what keeps every report safe, consistent, and portable across the desktop app, a future web view, and an agent's summary. Here is every kind, with the JSON you emit beside how it renders.

The authoritative shape is result.schema.json#/$defs/Block. Inventing a new kind is a contract-conformance failure — the vocabulary grows only by deliberate additions. For an exact-fidelity preview against your own sample, run your bundle through the desktop app's developer surface; this page is the always-on reference.

rows

Label → value pairs

The workhorse. A titled list of label/value lines; give a value a tone to colour it (moss / amber / rust / neutral).

{
  "kind": "rows",
  "title": "Variant",
  "rows": [
    { "label": "rsID", "value": "rs12913832" },
    { "label": "Gene", "value": "HERC2 / OCA2" },
    { "label": "Genotype", "value": "AA", "tone": "moss" }
  ]
}
Variant
rsIDrs12913832 GeneHERC2 / OCA2 GenotypeAA
score

A value on a min→max track

One number pinned to a scale, with optional reference bands and an interpretation line beneath.

{
  "kind": "score",
  "title": "Call rate",
  "value": 98.6,
  "unit": "%",
  "scale": { "min": 90, "max": 100 },
  "bands": [
    { "at": 95, "label": "ok",   "tone": "amber" },
    { "at": 98, "label": "good", "tone": "moss" }
  ],
  "interpretation": "98.6% of probes returned a confident genotype."
}
Call rate
ok good 98.6 %
98.6% of probes returned a confident genotype.
distribution

Where you fall on a population curve

A pre-binned histogram with the user's value marked; the renderer computes and prints the percentile. The headline "wow" visual.

{
  "kind": "distribution",
  "title": "Predicted height vs. population",
  "unit": "cm",
  "userValue": 180,
  "bins": [
    { "from": 155, "to": 160, "count": 4 },
    { "from": 160, "to": 165, "count": 12 },
    { "from": 165, "to": 170, "count": 22 },
    { "from": 170, "to": 175, "count": 28 },
    { "from": 175, "to": 180, "count": 19 },
    { "from": 180, "to": 185, "count": 9 },
    { "from": 185, "to": 190, "count": 3 }
  ]
}
Predicted height vs. population
YOU 155 cm 190 cm
You sit at the 88th percentile of the population.
table

Columns and rows

Declared columns (each with an optional align) and an array of row objects keyed by column key.

{
  "kind": "table",
  "title": "Top contributing variants",
  "columns": [
    { "key": "rsid",   "label": "rsID" },
    { "key": "gene",   "label": "Gene" },
    { "key": "effect", "label": "Effect", "align": "right" }
  ],
  "rows": [
    { "rsid": "rs1042725", "gene": "HMGA2", "effect": "+0.41 cm" },
    { "rsid": "rs143384",  "gene": "GDF5",  "effect": "+0.38 cm" },
    { "rsid": "rs2247341", "gene": "HHIP",  "effect": "+0.22 cm" }
  ]
}
Top contributing variants
rsIDGeneEffect
rs1042725HMGA2+0.41 cm
rs143384GDF5+0.38 cm
rs2247341HHIP+0.22 cm
bars

Categorical bars

One bar per category (e.g. variants per chromosome). A zero value renders as a faint rust stub so gaps stay visible rather than vanishing.

{
  "kind": "bars",
  "title": "Variants per chromosome",
  "unit": "count",
  "bars": [
    { "label": "1", "value": 48 }, { "label": "2", "value": 51 },
    { "label": "3", "value": 42 }, { "label": "4", "value": 39 },
    { "label": "5", "value": 37 }, { "label": "6", "value": 35 },
    { "label": "7", "value": 33 }, { "label": "8", "value": 30 },
    { "label": "X", "value": 18 }, { "label": "Y", "value": 0 }
  ]
}
Variants per chromosome
1 2 3 4 5 6 7 8 X Y
callout

A toned aside

A short note with a coloured left border — use it for caveats, context, or a headline takeaway. tone sets the colour.

{
  "kind": "callout",
  "tone": "amber",
  "title": "One SNP is a sketch, not a portrait",
  "body": "Eye colour is influenced by many genes. This single read explains most of the blue-vs-brown variation in Europeans but won't capture hazel or green reliably."
}
One SNP is a sketch, not a portrait
Eye colour is influenced by many genes. This single read explains most of the blue-vs-brown variation in Europeans but won't capture hazel or green reliably.
Next

Build one against these primitives.

Compose your result from the blocks above, then test it locally — commonsc-devkit run <project> executes your bundle in the real Tier-1 sandbox and checks the envelope before you ever submit.