added range names and bit ranks

Reviewed-on: #13
Reviewed-by: Louis Heredero <louis@herdac.ch>

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [v0.3.0] - 2025-05-03
+- updated CeTZ to 0.3.4
+- updated to Typst 0.13.1
+- updated Tidy to 0.4.2
+- updated Codly to 1.3.0 and codly-languages to 0.1.8
+- added `ltr-bits` config option
+- added a "Loading" section to the manual
+
+## [v0.2.0] - 2025-02-23
+- updated CeTZ to 0.3.2
+- updated to Typst 0.13.0
+- fixed missing bit index on dependencies
+- updated docs (Tidy, codelst -> codly)
+
+## [v0.1.0] - 2024-10-02
+- prepared for publication in Typst Universe
+
+## [v0.0.2] - 2024-06-15
+### Added
+- `width` parameter to `schema.render` for easier integration
+- `all-bit-i` config option
+- colored ranges
+- format specification in the manual
+
+## [v0.0.1] - 2024-05-19
+- initial version
+- ported all features from the [python package](https://git.kb28.ch/HEL/rivet/)

README.md

@@ -1,3 +1,41 @@
 # rivet-typst
 
-Register / Instruction Visualizer & Explainer Tool with Typst, using CeTZ
+RIVET _(Register / Instruction Visualizer & Explainer Tool)_ is a [Typst](https://typst.app) package for visualizing binary instructions or describing the contents of a register, using the [CeTZ](https://typst.app/universe/package/cetz) package.
+
+It is based on the [homonymous Python script](https://git.kb28.ch/HEL/rivet/)
+
+## Examples
+<table>
+  <tr>
+    <td>
+      <a href="./gallery/example1.typ">
+        <img src="./gallery/example1.png" width="1000px">
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>A bit of eveything</td>
+  </tr>
+  <tr>
+    <td>
+      <a href="./gallery/example2.typ">
+        <img src="./gallery/example2.png" width="1000px">
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>RISC-V memory instructions (blueprint)</td>
+  </tr>
+</table>
+
+*Click on the example image to jump to the code.*
+
+## Usage
+For more information, see the [manual](manual.pdf)
+
+To use this package, simply import `schema` from [rivet](https://typst.app/universe/package/rivet) and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
+```typ
+#import "@preview/rivet:0.3.0": schema
+#let doc = schema.load(yaml("path/to/schema.yaml"))
+#schema.render(doc)
+```

docs/config.typ

@@ -0,0 +1,65 @@
+/// Creates a dictionary of all configuration parameters
+///
+/// - default-font-family (str): The default font family
+/// - default-font-size (length): The absolute default font size
+/// - italic-font-family (str): The italic font family (for value descriptions)
+/// - italic-font-size (length): The absolute italic font size
+/// - background (color): The diagram background color
+/// - text-color (color): The default color used to display text
+/// - link-color (color): The color used to display links and arrows
+/// - bit-i-color (color): The color used to display bit indices
+/// - border-color (color): The color used to display borders
+/// - bit-width (float): The width of a bit
+/// - bit-height (float): The height of a bit
+/// - description-margin (float): The margin between descriptions
+/// - dash-length (float): The length of individual dashes (for dashed lines)
+/// - dash-space (float): The space between two dashes (for dashed lines)
+/// - arrow-size (float): The size of arrow heads
+/// - margins (tuple): TODO -> remove
+/// - arrow-margin (float): The margin between arrows and the structures they link
+/// - values-gap (float): The gap between individual values
+/// - arrow-label-distance (float): The distance between arrows and their labels
+/// - force-descs-on-side (bool): If true, descriptions are placed on the side of the structure, otherwise, they are placed as close as possible to the bit
+/// - left-labels (bool): If true, descriptions are put on the left, otherwise, they default to the right hand side
+/// - width (float): TODO -> remove
+/// - height (float): TODO -> remove
+/// - full-page (bool): If true, the page will be resized to fit the diagram and take the background color
+/// - all-bit-i (bool): If true, all bit indices will be rendered, otherwise, only the ends of each range will be displayed
+/// - ltr-bits (bool): If true, bits are placed with the LSB on the left instead of the right
+/// -> dictionary
+#let config(
+  default-font-family: "Ubuntu Mono",
+  default-font-size: 15pt,
+  italic-font-family: "Ubuntu Mono",
+  italic-font-size: 12pt,
+  background: white,
+  text-color: black,
+  link-color: black,
+  bit-i-color: black,
+  border-color: black,
+  bit-width: 30,
+  bit-height: 30,
+  description-margin: 10,
+  dash-length: 6,
+  dash-space: 4,
+  arrow-size: 10,
+  margins: (20, 20, 20, 20),
+  arrow-margin: 4,
+  values-gap: 5,
+  arrow-label-distance: 5,
+  force-descs-on-side: false,
+  left-labels: false,
+  width: 1200,
+  height: 800,
+  full-page: false,
+  all-bit-i: true,
+  ltr-bits: false
+) = {}
+
+/// Dark theme config
+/// - ..args (any): see @@config()
+#let dark(..args) = {}
+
+/// Blueprint theme config
+/// - ..args (any): see @@config()
+#let blueprint(..args) = {}

docs/examples.typ

@@ -0,0 +1,72 @@
+#import "../src/lib.typ": schema
+#import "../src/util.typ"
+
+#let example-preamble = "import \"../src/lib.typ\": *;"
+
+#let example(src, show-src: true, vertical: false, fill: true) = {
+  src = src.text.trim()
+  let full-src = example-preamble + src
+  let body = eval(full-src)
+
+  block(width: 100%,
+    align(center,
+      box(
+        stroke: black + 1pt,
+        radius: .5em,
+        fill: if fill {orange.lighten(95%)} else {none},
+        if show-src {
+          let src-block = align(left, raw(src, lang: "typc"))
+          table(
+            columns: if vertical {1} else {2},
+            inset: 1em,
+            align: horizon + center,
+            stroke: none,
+            body,
+            if vertical {table.hline()} else {table.vline()}, src-block
+          )
+        } else {
+          table(
+            inset: 1em,
+            body
+          )
+        }
+      )
+    )
+  )
+}
+
+#let config-config = example(raw("
+let ex = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: default
+```)
+schema.render(ex, config: config.config())
+"))
+
+#let config-dark = example(raw("
+let ex = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: dark
+```)
+schema.render(ex, config: config.dark())
+"))
+
+#let config-blueprint = example(raw("
+let ex = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: blueprint
+```)
+schema.render(ex, config: config.blueprint())
+"))

docs/schema.typ

@@ -0,0 +1,19 @@
+/// Loads a schema from a file or a raw block.
+/// This function returns a dictionary of structures\
+/// See the #link(<loading>)[Loading] chapter for examples of schema loading for each supported format
+/// 
+/// Supported formats: #schema.valid-extensions.map(e => raw("." + e)).join(", ")
+/// - path-or-schema (str, raw, dictionary):
+///   #list(
+///     [If it is a string, defines the path to load.\ #emoji.warning Warning: this will only work if this package is part of your project, as packages installed in the `@local` or `@preview` namespace cannot access project files],
+///     [If it is a raw block, its content is directly parsed (the block's language will define the format to use)],
+///     [If it is a dictionary, it directly defines the schema structure]
+///   )
+/// -> dictionary
+#let load(path-or-schema) = {}
+
+/// Renders the given schema
+/// - schema (dictionary): A schema dictionary, as returned by @@load()
+/// - config (auto, dictionary): The configuration parameters, as returned by #doc-ref("config.config")
+/// - width (ratio, length): The width of the generated figure
+#let render(schema, config: auto, width: 100%) = {}

gallery/example1.typ

@@ -0,0 +1,6 @@
+#import "../src/lib.typ": schema, config
+
+#let example = schema.load("/gallery/example1.yaml")
+#schema.render(example, config: config.config(
+  full-page: true
+))

gallery/example1.yaml

@@ -0,0 +1,73 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-28:
+        name: cond
+      27:
+        name: 0
+      26:
+        name: 1
+      25:
+        name: I
+      24:
+        name: P
+        description: pre / post indexing bit
+        values:
+          0: post, add offset after transfer
+          1: pre, add offset before transfer
+      23:
+        name: U
+        description: up / down bit
+        values:
+          0: down, subtract offset from base
+          1: up, addition offset to base
+      22:
+        name: B
+        description: byte / word bit
+        values:
+          0: transfer word quantity
+          1: transfer byte quantity
+      21:
+        name: W
+        description: write-back bit
+        values:
+          0: no write-back
+          1: write address into base
+      20:
+        name: L
+        description: load / store bit
+        values:
+          0: store to memory
+          1: load from memory
+      19-16:
+        name: Rn
+        description: base register
+      15-12:
+        name: Rd
+        description: source / destination register
+      11-0:
+        name: offset
+        depends-on: 25
+        values:
+          0:
+            description: offset is an immediate value
+            structure: immediateOffset
+          1:
+            description: offset is a register
+            structure: registerOffset
+  immediateOffset:
+    bits: 12
+    ranges:
+      11-0:
+        name: 12-bit immediate offset
+        description: unsigned number
+  registerOffset:
+    bits: 12
+    ranges:
+      11-4:
+        name: shift
+        description: shift applied to Rm
+      3-0:
+        name: Rm
+        description: offset register

gallery/example2.typ

@@ -0,0 +1,7 @@
+#import "../src/lib.typ": schema, config
+
+#let example = schema.load("/gallery/example2.yaml")
+#schema.render(example, config: config.blueprint(
+  full-page: true,
+  left-labels: true
+))

gallery/example2.yaml

@@ -0,0 +1,78 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-20:
+        name: src
+        depends-on: 5
+        values:
+          0:
+            description:
+            structure: srcImmediate
+          1:
+            description:
+            structure: srcRegister
+      19-15:
+        name: rs1
+      14-12:
+        name: funct3
+        description: function modifier
+        values:
+          000: byte
+          001: half-word
+          "010": word
+          100: upper byte (load only)
+          101: upper half (load only)
+      11-7:
+        name: dst
+        depends-on: 5
+        values:
+          0:
+            description:
+            structure: dstRegister
+          1:
+            description:
+            structure: dstImmediate
+      6:
+        name: 0
+      5:
+        name: I
+      4:
+        name: 0
+      3:
+        name: 0
+      2:
+        name: 0
+      1:
+        name: 1
+      0:
+        name: 1
+
+  srcImmediate:
+    bits: 12
+    ranges:
+      11-0:
+        name: src
+        description: source memory address
+  srcRegister:
+    bits: 12
+    ranges:
+      11-5:
+        name: dstU
+        description: destination address upper bits
+      4-0:
+        name: rs2
+        description: source register
+
+  dstImmediate:
+    bits: 5
+    ranges:
+      4-0:
+        name: destL
+        description: destination address lower bits
+  dstRegister:
+    bits: 5
+    ranges:
+      4-0:
+        name: rd
+        description: destination register

gallery/example3.typ

@@ -0,0 +1,23 @@
+#import "../src/lib.typ": schema, config
+
+#let example = schema.load("/gallery/example1.yaml")
+//#schema.render(example)
+
+= Chapter 1
+#lorem(50)
+
+= Chapter 2
+#lorem(50)
+
+== Section 2.1
+
+#lorem(20)
+
+#figure(
+  schema.render(example, config: config.config(all-bit-i: false)),
+  caption: "Test schema"
+)
+
+#lorem(20)
+
+= Chapter 3

gallery/example3.yaml

@@ -0,0 +1,12 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-24:
+        name: op
+      23-16:
+        name: r1
+      15-8:
+        name: r2
+      7-0:
+        name: r3

gallery/riscv/alu_instr.yaml

@@ -0,0 +1,60 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-20:
+        name: op2
+        depends-on: 5
+        values:
+          0:
+            description: second operand is an immediate value
+            structure: immediateOp
+          1:
+            description: second operand is a register
+            structure: registerOp
+      19-15:
+        name: rs1
+      14-12:
+        name: funct3
+        description: operation
+        values:
+          000: add / sub
+          100: xor
+          110: or
+          111: and
+          001: sl
+          101: sr
+      11-7:
+        name: rd
+      6:
+        name: 0
+      5:
+        name: I
+      4:
+        name: 1
+      3:
+        name: 0
+      2:
+        name: 0
+      1:
+        name: 1
+      0:
+        name: 1
+  immediateOp:
+    bits: 12
+    ranges:
+      11-0:
+        name: 12-bit immediate value
+        description: signed number
+  registerOp:
+    bits: 12
+    ranges:
+      11-5:
+        name: funct7
+        description: function modifier
+        values:
+          0000000: default (add, srl)
+          "0100000": sub, sra
+      4-0:
+        name: rs2
+        description: second register operand

gallery/riscv/branch_instr.yaml

@@ -0,0 +1,34 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-25:
+        name: imm
+      24-20:
+        name: rs2
+      19-15:
+        name: rs1
+      14-12:
+        name: funct3
+        description: function modifier
+        values:
+          000: if equal
+          001: if not equal
+          100: if less
+          101: if greater or equal
+      11-7:
+        name: imm
+      6:
+        name: 1
+      5:
+        name: 1
+      4:
+        name: 0
+      3:
+        name: 0
+      2:
+        name: 0
+      1:
+        name: 1
+      0:
+        name: 1

gallery/riscv/mem_instr.yaml

@@ -0,0 +1,78 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-20:
+        name: src
+        depends-on: 5
+        values:
+          0:
+            description:
+            structure: srcImmediate
+          1:
+            description:
+            structure: srcRegister
+      19-15:
+        name: rs1
+      14-12:
+        name: funct3
+        description: function modifier
+        values:
+          000: byte
+          001: half-word
+          "010": word
+          100: upper byte (load only)
+          101: upper half (load only)
+      11-7:
+        name: dst
+        depends-on: 5
+        values:
+          0:
+            description:
+            structure: dstRegister
+          1:
+            description:
+            structure: dstImmediate
+      6:
+        name: 0
+      5:
+        name: I
+      4:
+        name: 0
+      3:
+        name: 0
+      2:
+        name: 0
+      1:
+        name: 1
+      0:
+        name: 1
+
+  srcImmediate:
+    bits: 12
+    ranges:
+      11-0:
+        name: src
+        description: source memory address
+  srcRegister:
+    bits: 12
+    ranges:
+      11-5:
+        name: dstU
+        description: destination address upper bits
+      4-0:
+        name: rs2
+        description: source register
+
+  dstImmediate:
+    bits: 5
+    ranges:
+      4-0:
+        name: destL
+        description: destination address lower bits
+  dstRegister:
+    bits: 5
+    ranges:
+      4-0:
+        name: rd
+        description: destination register

gallery/riscv/riscv.typ

@@ -0,0 +1,14 @@
+#import "../../src/lib.typ": *
+
+#let conf = config.config(
+  full-page: true,
+  left-labels: true
+)
+#let alu = schema.load("/gallery/riscv/alu_instr.yaml")
+#schema.render(alu, config: conf)
+
+#let branch = schema.load("/gallery/riscv/branch_instr.yaml")
+#schema.render(branch, config: conf)
+
+#let mem = schema.load("/gallery/riscv/mem_instr.yaml")
+#schema.render(mem, config: conf)

gallery/test.json

@@ -0,0 +1,111 @@
+{
+    "structures": {
+        "main": {
+            "bits": 32,
+            "ranges": {
+                "31-28": {
+                    "name": "cond"
+                },
+                "27": {
+                    "name": "0"
+                },
+                "26": {
+                    "name": "1"
+                },
+                "25": {
+                    "name": "I"
+                },
+                "24": {
+                    "name": "P",
+                    "description": "pre / post indexing bit",
+                    "values": {
+                        "0": "post, add offset after transfer",
+                        "1": "pre, add offset before transfer"
+                    }
+                },
+                "23": {
+                    "name": "U",
+                    "description": "up / down bit",
+                    "values": {
+                        "0": "down, subtract offset from base",
+                        "1": "up, addition offset to base"
+                    }
+                },
+                "22": {
+                    "name": "B",
+                    "description": "byte / word bit",
+                    "values": {
+                        "0": "transfer word quantity",
+                        "1": "transfer byte quantity"
+                    }
+                },
+                "21": {
+                    "name": "W",
+                    "description": "write-back bit",
+                    "values": {
+                        "0": "no write-back",
+                        "1": "write address into base"
+                    }
+                },
+                "20": {
+                    "name": "L",
+                    "description": "load / store bit",
+                    "values": {
+                        "0": "store to memory",
+                        "1": "load from memory"
+                    }
+                },
+                "19-16": {
+                    "name": "Rn",
+                    "description": "base register"
+                },
+                "15-12": {
+                    "name": "Rd",
+                    "description": "source / destination register"
+                },
+                "11-0": {
+                    "name": "offset",
+                    "depends-on": "25",
+                    "values": {
+                        "0": {
+                            "description": "offset is an immediate value",
+                            "structure": "immediateOffset"
+                        },
+                        "1": {
+                            "description": "offset is a register",
+                            "structure": "registerOffset"
+                        }
+                    }
+                }
+            }
+        },
+        "immediateOffset": {
+            "bits": 12,
+            "ranges": {
+                "11-0": {
+                    "name": "12-bit immediate offset",
+                    "description": "unsigned number"
+                }
+            }
+        },
+        "registerOffset": {
+            "bits": 12,
+            "ranges": {
+                "11-4": {
+                    "name": "shift",
+                    "description": "shift applied to Rm"
+                },
+                "3-0": {
+                    "name": "Rm",
+                    "description": "offset register"
+                }
+            }
+        }
+    },
+    "colors": {
+        "main": {
+            "31-28": "#FF0000",
+            "11-4": [34, 176, 43]
+        }
+    }
+}

gallery/test.typ

@@ -0,0 +1,139 @@
+#import "../src/lib.typ": *
+
+#let test-yaml = schema.load("/gallery/test.yaml")
+#schema.render(test-yaml, config: config.config(
+  full-page: true
+))
+
+#let test-json = schema.load("/gallery/test.json")
+#schema.render(test-json, config: config.blueprint(
+  full-page: true
+))
+
+#let test-xml = schema.load("/gallery/test.xml")
+#schema.render(test-xml, config: config.dark(
+  full-page: true
+))
+
+#let test-raw = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: test
+```)
+#schema.render(test-raw, config: config.config(
+  full-page: true
+))
+
+#let test-typ = schema.load((
+  structures: (
+    main: (
+      bits: 32,
+      ranges: (
+        "31-28": (name: "cond"),
+        "27": (name: "0"),
+        "26": (name: "1"),
+        "25": (name: "I"),
+        "24": (
+          name: "P",
+          description: "pre / post indexing bit",
+          values: (
+            "0": "post, add offset after transfer",
+            "1": "pre, add offset before transfer"
+          )
+        ),
+        "23": (
+          name: "U",
+          description: "up / down bit",
+          values: (
+            "0": "down, subtract offset from base",
+            "1": "up, addition offset to base"
+          )
+        ),
+        "22": (
+          name: "B",
+          description: "byte / word bit",
+          values: (
+            "0": "transfer word quantity",
+            "1": "transfer byte quantity"
+          )
+        ),
+        "21": (
+          name: "W",
+          description: "write-back bit",
+          values: (
+            "0": "no write-back",
+            "1": "write address into base"
+          )
+        ),
+        "20": (
+          name: "L",
+          description: "load / store bit",
+          values: (
+            "0": "store to memory",
+            "1": "load from memory"
+          )
+        ),
+        "19-16": (
+          name: "Rn",
+          description: "base register"
+        ),
+        "15-12": (
+          name: "Rd",
+          description: "source / destination register"
+        ),
+        "11-0": (
+          name: "offset",
+          depends-on: "25",
+          values: (
+            "0": (
+              description: "offset is an immediate value",
+              structure: "immediateOffset"
+            ),
+            "1": (
+              description: "offset is a register",
+              structure: "registerOffset"
+            )
+          )
+        )
+      )
+    ),
+    immediateOffset: (
+      bits: 12,
+      ranges: (
+        "11-0": (
+          name: "12-bit immediate offset",
+          description: "unsigned number"
+        )
+      )
+    ),
+    registerOffset: (
+      bits: 12,
+      ranges: (
+        "11-4": (
+          name: "shift",
+          description: "shift applied to Rm"
+        ),
+        "3-0": (
+          name: "Rm",
+          description: "offset register"
+        )
+      )
+    )
+  ),
+  colors: (
+    main: (
+      "31-28": red,
+      "11-4": green
+    ),
+    registerOffset: (
+      "11-4": rgb(240, 140, 80)
+    )
+  )
+))
+
+#schema.render(test-typ, config: config.config(
+  full-page: true
+))

gallery/test.xml

@@ -0,0 +1,71 @@
+<schema>
+    <structure id="main" bits="32">
+        <range start="28" end="31" name="cond"></range>
+        <range start="27" end="27" name="0"></range>
+        <range start="26" end="26" name="1"></range>
+        <range start="25" end="25" name="I"></range>
+        <range start="24" end="24" name="P">
+            <description>pre / post indexing bit</description>
+            <values>
+                <case value="0">post, add offset after transfer</case>
+                <case value="1">pre, add offset before transfer</case>
+            </values>
+        </range>
+        <range start="23" end="23" name="U">
+            <description>up / down bit</description>
+            <values>
+                <case value="0">down, subtract offset from base</case>
+                <case value="1">up, addition offset to base</case>
+            </values>
+        </range>
+        <range start="22" end="22" name="B">
+            <description>byte / word bit</description>
+            <values>
+                <case value="0">transfer word quantity</case>
+                <case value="1">transfer byte quantity</case>
+            </values>
+        </range>
+        <range start="21" end="21" name="W">
+            <description>write-back bit</description>
+            <values>
+                <case value="0">no write-back</case>
+                <case value="1">write address into base</case>
+            </values>
+        </range>
+        <range start="20" end="20" name="L">
+            <description>load / store bit</description>
+            <values>
+                <case value="0">store to memory</case>
+                <case value="1">load from memory</case>
+            </values>
+        </range>
+        <range start="16" end="19" name="Rn">
+            <description>base register</description>
+        </range>
+        <range start="12" end="15" name="Rd">
+            <description>source / destination register</description>
+        </range>
+        <range start="0" end="11" name="offset" depends-on="25">
+            <values>
+                <case value="0" structure="immediateOffset">offset is an immediate value</case>
+                <case value="1" structure="registerOffset">offset is a register</case>
+            </values>
+        </range>
+    </structure>
+    <structure id="immediateOffset" bits="12">
+        <range start="0" end="11" name="12-bit immediate offset">
+            <description>unsigned number</description>
+        </range>
+    </structure>
+    <structure id="registerOffset" bits="12">
+        <range start="4" end="11" name="shift">
+            <description>shift applied to Rm</description>
+        </range>
+        <range start="0" end="3" name="Rm">
+            <description>offset register</description>
+        </range>
+    </structure>
+    <color structure="main" color="#FF0000" start="28" end="31" />
+    <color structure="main" color="#255961" start="4" end="11" />
+    <color structure="immediateOffset" color="89,97,37" start="4" end="11" />
+</schema>

gallery/test.yaml

@@ -0,0 +1,81 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-28:
+        name: cond
+      27:
+        name: 0
+      26:
+        name: 1
+      25:
+        name: I
+      24:
+        name: P
+        description: pre / post indexing bit
+        values:
+          0: post, add offset after transfer
+          1: pre, add offset before transfer
+      23:
+        name: U
+        description: up / down bit
+        values:
+          0: down, subtract offset from base
+          1: up, addition offset to base
+      22:
+        name: B
+        description: byte / word bit
+        values:
+          0: transfer word quantity
+          1: transfer byte quantity
+      21:
+        name: W
+        description: write-back bit
+        values:
+          0: no write-back
+          1: write address into base
+      20:
+        name: L
+        description: load / store bit
+        values:
+          0: store to memory
+          1: load from memory
+      19-16:
+        name: Rn
+        description: base register
+      15-12:
+        name: Rd
+        description: source / destination register
+      11-0:
+        name: offset
+        depends-on: 25
+        values:
+          0:
+            description: offset is an immediate value
+            structure: immediateOffset
+          1:
+            description: offset is a register
+            structure: registerOffset
+  immediateOffset:
+    bits: 12
+    ranges:
+      11-0:
+        name: 12-bit immediate offset
+        description: unsigned number
+  registerOffset:
+    bits: 12
+    ranges:
+      11-4:
+        name: shift
+        description: shift applied to Rm
+      3-0:
+        name: Rm
+        description: offset register
+
+colors:
+  main:
+    31-28: "#3EFA6B"
+    25-23:
+      - 100
+      - 150
+      - 200

justfile

@@ -0,0 +1,12 @@
+# Local Variables:
+# mode: makefile
+# End:
+gallery_dir := "./gallery"
+set shell := ["bash", "-uc"]
+
+manual:
+  typst c manual.typ manual.pdf
+
+gallery:
+  for f in "{{gallery_dir}}"/*.typ; do typst c --root . "$f" "${f/typ/pdf}"; done
+  for f in "{{gallery_dir}}"/example*.typ; do typst c --root . "$f" "${f/typ/png}"; done

manual.typ

@@ -0,0 +1,415 @@
+#import "@preview/tidy:0.4.2"
+#import "@preview/codly:1.3.0": codly-init, codly
+#import "@preview/codly-languages:0.1.8": codly-languages
+#import "@preview/showybox:2.0.4": showybox
+#import "src/lib.typ"
+#import "src/schema.typ"
+#import "docs/examples.typ"
+
+#show: codly-init
+
+#codly(languages: codly-languages)
+
+#set heading(numbering: (..num) => if num.pos().len() < 4 {
+  numbering("1.1", ..num)
+})
+
+#set page(numbering: "1/1", header: align(right)[rivet #sym.dash.em v#lib.version])
+
+#let doc-ref(target, full: false, var: false) = {
+  let (module, func) = target.split(".")
+  let label-name = module + "-" + func
+  let display-name = func
+  if full {
+    display-name = target
+  }
+  if not var {
+    label-name += "()"
+    display-name += "()"
+  }
+  link(label(label-name), raw(display-name))
+}
+
+#let note(it) = showybox(
+  title: "Note",
+  title-style: (
+    color: white,
+    weight: "bold"
+  ),
+  frame: (
+    title-color: blue.lighten(30%),
+    border-color: blue.darken(40%)
+  ),
+  it
+)
+
+#show link: set text(blue)
+
+#let sch = schema.load(```yaml
+structures:
+  main:
+    bits: 5
+    ranges:
+      4:
+        name: R
+        description: Register
+      3:
+        name: I
+        description: Instruction
+      2:
+        name: V
+        description: Visualizer
+      1:
+        name: E
+        description: Explainer
+      0:
+        name: T
+        description: Tool
+```)
+#align(center, schema.render(sch, width: 50%, config: lib.config.config(left-labels: true)))
+#v(1fr)
+#box(
+  width: 100%,
+  stroke: black,
+  inset: 1em,
+  outline(indent: auto, depth: 3)
+)
+#pagebreak(weak: true)
+
+= Introduction
+
+This package provides a way to make beautiful register diagrams using the CeTZ package. It can be used to document Assembly instructions or binary registers
+
+This is a port of the #link("https://git.kb28.ch/HEL/rivet")[homonymous Python script] for Typst.
+
+= Usage
+
+#let import-stmt = "#import \"@preview/rivet:" + str(lib.version) + "\""
+
+Simply import the `schema` module and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
+#raw(block: true, lang: "typ", ```typ
+$import: schema
+#let doc = schema.load(yaml("path/to/schema.yaml"))
+#schema.render(doc)
+```.text.replace("$import", import-stmt))
+
+Please read the #link(<loading>)[Loading] chapter for more detailed explanations on how to load schema descriptions.
+
+= Format
+
+This section describes the structure of a schema definition. The examples given use the JSON syntax. For examples in different formats, see #link("https://git.kb28.ch/HEL/rivet-typst/src/branch/main/gallery/test.yaml")[test.yaml], #link("https://git.kb28.ch/HEL/rivet-typst/src/branch/main/gallery/test.json")[test.json] and #link("https://git.kb28.ch/HEL/rivet-typst/src/branch/main/gallery/test.xml")[test.xml]. You can also directly define a schema using Typst dictionaries and arrays.
+
+Since the XML format is quite different from the other, you might find it helpful to look at the examples in the #link("https://git.kb28.ch/HEL/rivet-typst/src/branch/main/gallery/")[Gitea repo] to get familiar with it.
+
+== Main layout
+
+A schema contains a dictionary of structures. There must be at least one defined structure named "main".
+
+It can also optionnaly contain a "colors" dictionary. More details about this in #link(<format-colors>)[Colors]
+
+```json
+{
+  "structures": {
+    "main": {
+      ...
+    },
+    "struct1": {
+      ...
+    },
+    "struct2": {
+      ...
+    },
+    ...
+  }
+}
+```
+
+#pagebreak(weak: true)
+
+== Structure <format-structure>
+
+A structure has a given number of bits and one or multiple ranges. Each range of bits can have a name, a description and / or values with special meaning (see #link(<format-range>)[Range]). A range's structure can also depend on another range's value (see #link(<format-dependencies>)[Dependencies]).
+
+The range name (or key) defines the left- and rightmost bits (e.g. `7-4` goes from bit 7 down to bit 4). The order in which you write the range is not important, meaning `7-4` is equivalent to `4-7`. Bits are displayed in big-endian, i.e. the leftmost bit has the highest value, except if you enable the `ltr-bits` #doc-ref("config.config") option.
+
+```json
+"main": {
+  "bits": 8,
+  "ranges": {
+    "7-4": {
+      ...
+    },
+    "3-2": {
+      ...
+    },
+    "1": {
+      ...
+    },
+    "0": {
+      ...
+    }
+  }
+}
+```
+
+=== Start <format-start>
+
+By default, structures start at bit 0, but you may want to number bits from 1, or another arbitrary value. To do this, you can set the `start` property of a structure to the desired start value. For example,
+
+```json
+"main": {
+  "bits": 8,
+  "start": 4,
+  "ranges": {
+    "11-7": { ... },
+    "6-4": { ... }
+  }
+}
+```
+
+#let start-schema = (structures: (main: (bits: 8, start: 4, ranges: ("11-7": (name: ""), "6-4": (name: "")))))
+
+would render as
+
+#align(
+  center,
+  schema.render(
+    schema.load(start-schema),
+    width: 50%
+  )
+)
+
+
+== Range <format-range>
+
+A range represents a group of consecutive bits. It can have a name (displayed in the bit cells), a description (displayed under the structure) and / or values.
+
+For values depending on other ranges, see #link(<format-dependencies>)[Dependencies].
+
+#note[
+  In YAML, make sure to wrap values in quotes because some values can be interpreted as octal notation (e.g. 010 #sym.arrow.r 8)
+]
+
+```json
+"3-2": {
+  "name": "op",
+  "description": "Logical operation",
+  "values": {
+    "00": "AND",
+    "01": "OR",
+    "10": "XOR",
+    "11": "NAND"
+  }
+}
+```
+
+#pagebreak(weak: true)
+
+== Dependencies <format-dependencies>
+
+The structure of one range may depend on the value of another. To represent this situation, first indicate on the child range the range on which it depends.
+
+Then, in its values, indicate which structure to use. A description can also be added (displayed below the horizontal dependency arrow)
+
+```json
+"7-4": {
+  ...
+  "depends-on": "0",
+  "values": {
+    "0": {
+      "description": "immediate value",
+      "structure": "immediateValue"
+    },
+    "1": {
+      "description": "value in register",
+      "structure": "registerValue"
+    }
+  }
+}
+```
+
+Finally, add the sub-structures to the structure dictionary:
+
+```json
+{
+  "structures": {
+    "main": {
+      ...
+    },
+    "immediateValue": {
+      "bits": 4,
+      ...
+    },
+    "registerValue": {
+      "bits": 4,
+      ...
+    },
+    ...
+  }
+}
+```
+
+#pagebreak(weak: true)
+
+== Colors <format-colors>
+
+You may want to highlight some ranges to make your diagram more readable. For this, you can use colors. Colors may be defined in a separate dictionary, at the same level as the "structures" dictionary:
+
+```json
+{
+  "structures": {
+    ...
+  },
+  "colors": {
+    ...
+  }
+}
+```
+
+It can contain color definitions for any number of ranges. For each range, you may then define a dictionary mapping bit ranges to a particular color:
+
+```json
+"colors": {
+  "main": {
+    "31-28": "#ABCDEF",
+    "27-20": "12,34,56"
+  },
+  "registerValue": {
+    "19-10": [12, 34, 56]
+  }
+}
+```
+
+Valid color formats are:
+- hex string starting with `#`, e.g. `"#23fa78"`
+- array of three integers (only JSON, YAML and Typst), e.g. `[35, 250, 120]`
+- string of three comma-separated integers (useful for XML), e.g. `"35,250,120"`
+- a Typst color (only Typst), e.g. `colors.green` or `rgb(35, 250, 120)`
+
+#note[
+  The XML format implements colors a bit differently. Instead of having a "colors" dictionary, color definitions are directly put on the same level as structure definitions. For this, you can use a `color` node with the attributes "structure", "color", "start" and "end", like so:
+  ```xml
+  <schema>
+    <structure id="main" bits="8">
+      ...
+    </structure>
+    ...
+    <color structure="main" color="#FF0000" start="4" end="7" />
+    <color structure="main" color="255,0,0" start="0" end="3" />
+  </schema>
+  ```
+]
+
+#pagebreak(weak: true)
+
+= Loading <loading>
+
+Due to current limitations of the Typst compiler, the package can only access its own files, unless directly included in your project. For this reason, rivet cannot load a schema from a path, and you will need to read the files yourself to pass their contents to the package.
+
+Here are a number of ways you can load your schemas:
+
+== JSON Format
+
+````typ
+// From file (ONLY IF PACKAGE INSTALLED IN PROJECT)
+#let s = schema.load("schema.json")
+// From file
+#let s = schema.load(json("schema.json"))
+// Raw block
+#let s = schema.load(```json
+{
+  "structures": {
+    "main": {
+      ...
+    }
+  }
+}
+```)
+````
+
+== YAML Format
+
+````typ
+// From file (ONLY IF PACKAGE INSTALLED IN PROJECT)
+#let s = schema.load("schema.yaml")
+// From file
+#let s = schema.load(yaml("schema.yaml"))
+// Raw block
+#let s = schema.load(```yaml
+structures:
+  main:
+    ...
+```)
+````
+
+== Typst Format
+
+```typ
+#let s = schema.load((
+  structures: (
+    main: (
+      ...
+    )
+  )
+))
+```
+
+#pagebreak(weak: true)
+
+== XML Format
+
+````typ
+// From file (ONLY IF PACKAGE INSTALLED IN PROJECT)
+#let x = schema.xml-loader.load("schema.xml")
+#let s = schema.load(x)
+// From file
+#let x = schema.xml-loader.parse(yaml("schema.yaml").first())
+#let s = schema.load(x)
+// Raw block
+#let s = schema.load(```xml
+<schema>
+  <structure id="main" bits="32">
+    ...
+  </structure>
+</schema>
+```)
+````
+
+#pagebreak(weak: true)
+
+= Config presets
+
+Aside from the default config, some example presets are also provided:
+- #doc-ref("config.config", full: true): the default theme, black on white
+  #examples.config-config
+- #doc-ref("config.dark", full: true): a dark theme, with white text and lines on a black background
+  #examples.config-dark
+- #doc-ref("config.blueprint", full: true): a blueprint theme, with white text and lines on a blue background
+  #examples.config-blueprint
+
+#pagebreak(weak: true)
+
+= Reference
+
+#let doc-config = tidy.parse-module(
+  read("docs/config.typ"),
+  name: "config",
+  old-syntax: true,
+  scope: (
+    doc-ref: doc-ref
+  )
+)
+#tidy.show-module(doc-config, sort-functions: false)
+
+#pagebreak()
+
+#let doc-schema = tidy.parse-module(
+  read("docs/schema.typ"),
+  name: "schema",
+  old-syntax: true,
+  scope: (
+    schema: schema,
+    doc-ref: doc-ref
+  )
+)
+#tidy.show-module(doc-schema, sort-functions: false)

src/cetz.typ

@@ -0,0 +1 @@
+#import "@preview/cetz:0.3.4": *

src/config.typ

@@ -0,0 +1,82 @@
+#let config(
+  default-font-family: "Ubuntu Mono",
+  default-font-size: 15pt,
+  italic-font-family: "Ubuntu Mono",
+  italic-font-size: 12pt,
+  background: white,
+  text-color: black,
+  link-color: black,
+  bit-i-color: black,
+  border-color: black,
+  bit-width: 30,
+  bit-height: 30,
+  description-margin: 10,
+  dash-length: 6,
+  dash-space: 4,
+  arrow-size: 10,
+  margins: (20, 20, 20, 20),
+  arrow-margin: 4,
+  values-gap: 5,
+  arrow-label-distance: 5,
+  force-descs-on-side: false,
+  left-labels: false,
+  width: 1200,
+  height: 800,
+  full-page: false,
+  all-bit-i: true,
+  ltr-bits: false,
+) = {
+  return (
+    default-font-family: default-font-family,
+    default-font-size: default-font-size,
+    italic-font-family: italic-font-family,
+    italic-font-size: italic-font-size,
+    background: background,
+    text-color: text-color,
+    link-color: link-color,
+    bit-i-color: bit-i-color,
+    border-color: border-color,
+    bit-width: bit-width,
+    bit-height: bit-height,
+    description-margin: description-margin,
+    dash-length: dash-length,
+    dash-space: dash-space,
+    arrow-size: arrow-size,
+    margins: margins,
+    arrow-margin: arrow-margin,
+    values-gap: values-gap,
+    arrow-label-distance: arrow-label-distance,
+    force-descs-on-side: force-descs-on-side,
+    left-labels: left-labels,
+    width: width,
+    height: height,
+    full-page: full-page,
+    all-bit-i: all-bit-i,
+    ltr-bits: ltr-bits,
+  )
+}
+
+#let dark = config.with(
+  background: rgb(24, 24, 24),
+  text-color: rgb(216, 216, 216),
+  link-color: rgb(150, 150, 150),
+  bit-i-color: rgb(180, 180, 180),
+  border-color: rgb(180, 180, 180)
+)
+
+#let blueprint = config.with(
+  background: rgb(53, 77, 158),
+  text-color: rgb(231, 236, 249),
+  link-color: rgb(169, 193, 228),
+  bit-i-color: rgb(214, 223, 244),
+  border-color: rgb(214, 223, 244)
+)
+
+#let transparent = config.with(
+  background: rgb(0, 0, 0, 0),
+  text-color: rgb(128, 128, 128),
+  link-color: rgb(128, 128, 128),
+  bit-i-color: rgb(128, 128, 128),
+  border-color: rgb(128, 128, 128)
+)
+

src/lib.typ

@@ -0,0 +1,4 @@
+#let version = version(0,3,0)
+
+#import "config.typ"
+#import "schema.typ"

src/range.typ

@@ -0,0 +1,68 @@
+#import "util.typ"
+
+#let key(start, end) = {
+  return str(start) + "->" + str(end)
+}
+
+#let bits(range) = {
+  return range.end - range.start + 1
+}
+
+#let parse-span(span) = {
+  let start-end = span.split("-")
+  if start-end.len() == 1 {
+    start-end.push(start-end.first())
+  }
+  let start = int(start-end.last())
+  let end = int(start-end.first())
+  if end < start {
+    (start, end) = (end, start)
+  }
+  return (start, end)
+}
+
+#let make(
+  start,
+  end,
+  name,
+  description: "",
+  values: none,
+  depends-on: none
+) = {
+  return (
+    start: start,
+    end: end,
+    name: name,
+    description: description,
+    values: values,
+    depends-on: depends-on,
+    last-value-y: -1
+  )
+}
+
+#let load(start, end, data) = {
+  let values = none
+  let bits = end - start + 1
+
+  if "values" in data {
+    values = (:)
+    for (val, desc) in data.values {
+      val = util.z-fill(val, bits)
+      values.insert(val, desc)
+    }
+  }
+
+  let depends-on = data.at("depends-on", default: none)
+  if depends-on != none {
+    depends-on = parse-span(str(depends-on))
+  }
+
+  return make(
+    start,
+    end,
+    str(data.name),
+    description: data.at("description", default: ""),
+    values: values,
+    depends-on: depends-on
+  )
+}

src/render/structure.typ

@@ -0,0 +1,116 @@
+#import "../cetz.typ": draw
+
+#let BACKGROUND-LAYER = -1
+
+#let draw-track(config, schema, struct, pos) = draw.group(name: "track", {
+  let colors = schema.at("colors", default: (:))
+  let total-width = struct.bits * config.bit-width
+
+  let bit-colors = (:)
+
+  if struct.name in colors {
+    for (s, col) in colors.at(struct.name) {
+      let (start, end) = rng.parse-span(s)
+      for i in range(start, end + 1) {
+        bit-colors.insert(str(i), col)
+      }
+    }
+  }
+
+  let boundaries = ()
+  for r in struct.ranges.values() {
+    boundaries.push(if config.ltr-bits {r.end} else {r.start})
+    boundaries.push(if config.ltr-bits {r.start - 1} else {r.end + 1})
+  }
+
+  draw.group(name: "bits", {
+    for i in range(struct.bits) {
+      let rank = struct.start + i
+      let j = if config.ltr-bits {i} else {struct.bits - i - 1}
+      let col = bit-colors.at(str(rank), default: config.background)
+
+      // Background color
+      draw.on-layer(BACKGROUND-LAYER, {
+        draw.rect(
+          (rel: (j * config.bit-width, 0), to: pos),
+          (rel: (config.bit-width, config.bit-height)),
+          fill: col,
+          stroke: none,
+          name: str(rank)
+        )
+      })
+
+      if j != struct.bits - 1 {
+        let top = str(rank) + ".north-east"
+        let bottom = str(rank) + ".south-east"
+
+        // Group boundary
+        if rank in boundaries {
+          draw.line(
+            top,
+            bottom,
+            stroke: config.border-color
+          )
+        
+        // Bit separator
+        } else {
+          draw.line(
+            top,
+            ((), 20%, bottom),
+            stroke: config.border-color
+          )
+          draw.line(
+            bottom,
+            ((), 20%, top),
+            stroke: config.border-color
+          )
+        }
+      }
+    }
+  })
+
+  // Frame
+  draw.rect(
+    "bits.north-west", "bits.south-east",
+    name: "frame",
+    stroke: config.border-color + 2pt
+  )
+
+  // Names
+  for r in struct.ranges.values() {
+    let i0 = r.start
+    let i1 = r.end
+    if not config.ltr-bits {
+      (i0, i1) = (i1, i0)
+    }
+    let start = "bits." + str(i0) + ".north-west"
+    let end = "bits." + str(i1) + ".south-east"
+    draw.content(
+      (start, 50%, end),
+      r.name
+    )
+  }
+
+  let indices = if config.all-bit-i {
+    range(struct.start, struct.start + struct.bits)
+  } else {
+    struct.ranges.values().map(r => (r.start, r.end)).flatten().dedup()
+  }
+  for i in indices {
+    draw.content(
+      "bits." + str(i) + ".north",
+      anchor: "south",
+      str(i),
+      padding: 4pt  // TODO: Maybe configurable
+    )
+  }
+})
+
+#let render(
+  config,
+  schema,
+  struct,
+  pos: (0, 0),
+) = draw.group(name: struct.name, {
+  draw-track(config, schema, struct, pos)
+})

src/renderer.typ

@@ -0,0 +1,15 @@
+#import "cetz.typ": canvas
+#import "render/structure.typ" as struct
+
+#let render(config, schema, width: 100%) = {
+  canvas(length: 1pt, {
+    struct.render(config, schema, schema.structures.main)
+  })
+}
+
+#let make(config) = {
+  return (
+    config: config,
+    render: render.with(config)
+  )
+}

src/schema.typ

@@ -0,0 +1,92 @@
+#import "config.typ" as conf
+#import "renderer.typ"
+#import "structure.typ"
+#import "xml-loader.typ"
+
+#let valid-extensions = ("yaml", "json", "xml")
+
+#let parse-file(path) = {
+  let ext = path.split(".").last()
+
+  if not ext in valid-extensions {
+    let fmts = valid-extensions.map(fmt => "." + fmt).join(", ")
+    fmts = "(" + fmts + ")"
+    panic("." + ext + " files are not supported. Valid formats: " + fmts)
+  }
+
+  if ext == "yaml" {
+    return yaml(path)
+  } else if ext == "json" {
+    return json(path)
+  } else if ext == "xml" {
+    return xml-loader.load(path)
+  }
+}
+
+#let parse-raw(schema) = {
+  let lang = schema.lang
+  let content = bytes(schema.text)
+  if not lang in valid-extensions {
+    let fmts = valid-extensions.join(", ")
+    fmts = "(" + fmts + ")"
+    panic("Unsupported format '" + lang + "'. Valid formats: " + fmts)
+  }
+
+  if lang == "yaml" {
+    return yaml(content)
+  } else if lang == "json" {
+    return json(content)
+  } else if lang == "xml" {
+    return xml-loader.parse(xml(content).first())
+  }
+}
+
+#let load(path-or-schema) = {
+  let schema = if type(path-or-schema) == str {
+    parse-file(path-or-schema)
+  } else if type(path-or-schema) == dictionary {
+    path-or-schema
+  } else {
+    parse-raw(path-or-schema)
+  }
+
+  if "colors" in schema {
+    for struct in schema.colors.keys() {
+      for (span, col) in schema.colors.at(struct) {
+        if type(col) == str {
+          if col.starts-with("#") {
+            col = rgb(col)
+          } else {
+            let (r, g, b) = col.split(",").map(v => int(v))
+            col = rgb(r, g, b)
+          }
+        } else if type(col) == array {
+          col = rgb(..col)
+        } else if type(col) != color {
+          panic("Invalid color format")
+        }
+        schema.colors.at(struct).at(span) = col
+      }
+    }
+  } else {
+    schema.insert("colors", (:))
+  }
+
+  let structures = (:)
+  for (id, data) in schema.structures {
+    id = str(id)
+    structures.insert(id, structure.load(id, data))
+  }
+  return (
+    structures: structures,
+    colors: schema.at("colors", default: (:))
+  )
+}
+
+#let render(schema, width: 100%, config: auto) = {
+  if config == auto {
+    config = conf.config()
+  }
+  let renderer_ = renderer.make(config)
+  (renderer_.render)(schema, width: width)
+}

src/structure.typ

@@ -0,0 +1,57 @@
+#import "range.typ" as rng
+#import "util.typ"
+
+#let make(
+  name,
+  bits,
+  ranges,
+  start: 0
+) = {
+  return (
+    name: name,
+    bits: bits,
+    ranges: ranges,
+    start: start
+  )
+}
+
+#let load(id, data) = {
+  let struct = (id: id)
+  let ranges = (:)
+
+  for (range-span, range-data) in data.ranges {
+    let (start, end) = rng.parse-span(str(range-span))
+    ranges.insert(
+      rng.key(start, end),
+      rng.load(start, end, range-data)
+    )
+  }
+
+  let ranges2 = (:)
+  for (k, range_) in ranges {
+    if range_.values != none and range_.depends-on != none {
+      let depends-key = rng.key(..range_.depends-on)
+      let depends-range = ranges.at(depends-key)
+      let bits = rng.bits(depends-range)
+      let values = (:)
+      for (v, d) in range_.values {
+        v = util.z-fill(str(int(v)), bits)
+        values.insert(v, d)
+      }
+      range_.values = values
+    }
+    ranges2.insert(k, range_)
+  }
+
+  return make(
+    id,
+    int(data.bits),
+    ranges2,
+    start: data.at("start", default: 0)
+  )
+}
+
+#let get-sorted-ranges(struct) = {
+  let ranges = struct.ranges.values()
+  return ranges.sorted(key: r => r.end)
+}

src/util.typ

@@ -0,0 +1,4 @@
+#let z-fill(string, length) = {
+  let filled = "0" * length + string
+  return filled.slice(-length)
+}

src/vec.typ

@@ -0,0 +1,44 @@
+#let vec(x, y) = {
+  return (x: x, y: y)
+}
+
+#let add(v1, v2) = {
+  return vec(
+    v1.x + v2.x,
+    v1.y + v2.y
+  )
+}
+
+#let sub(v1, v2) = {
+  return vec(
+    v1.x - v2.x,
+    v1.y - v2.y
+  )
+}
+
+#let mul(v, f) = {
+  return vec(
+    v.x * f,
+    v.y * f
+  )
+}
+
+#let div(v, f) = {
+  return vec(
+    v.x / f,
+    v.y / f
+  )
+}
+
+#let mag(v) = {
+  return calc.sqrt(v.x * v.x + v.y * v.y)
+}
+
+#let normalize(v) = {
+  let m = mag(v)
+
+  if m == 0 {
+    return (x: 0, y: 0)
+  }
+  return div(v, m)
+}

src/xml-loader.typ

@@ -0,0 +1,117 @@
+#let find(elmt, tag) = {
+  if not "children" in elmt {
+    return none
+  }
+
+  return elmt.children.find(e => "tag" in e and e.tag == tag)
+}
+
+#let find-all(elmt, tag) = {
+  if not "children" in elmt {
+    return ()
+  }
+
+  return elmt.children.filter(e => "tag" in e and e.tag == tag)
+}
+
+#let parse-values(elmt) = {
+  let values = (:)
+  let case-elmts = find-all(elmt, "case")
+
+  for case-elmt in case-elmts {
+    let val = case-elmt.attrs.value
+    let desc = case-elmt.children.first()
+    let struct = none
+    if "structure" in case-elmt.attrs {
+      struct = case-elmt.attrs.structure
+    }
+
+    values.insert(val, 
+      if struct != none {
+        (
+          description: desc,
+          structure: struct
+        )
+      } else {
+        desc
+      }
+    )
+  }
+
+  return values
+}
+
+#let parse-range(elmt) = {
+  let range_ = (
+    name: elmt.attrs.name
+  )
+  let desc = none
+  if "children" in elmt {
+    desc = find(elmt, "description")
+  }
+
+  if desc != none {
+    range_.insert("description", desc.children.first())
+  }
+
+  let values-elmt = find(elmt, "values")
+  if values-elmt != none {
+    range_.insert("values", parse-values(values-elmt))
+  }
+
+  if "depends-on" in elmt.attrs {
+    range_.insert("depends-on", elmt.attrs.depends-on)
+  }
+
+  return range_
+}
+
+#let parse-structure(elmt) = {
+  let ranges = (:)
+  let range-elmts = elmt.children.filter(e => "tag" in e and e.tag == "range")
+
+  for range-elmt in range-elmts {
+    let span = range-elmt.attrs.end + "-" + range-elmt.attrs.start
+    ranges.insert(span, parse-range(range-elmt))
+  }
+
+  return (
+    bits: elmt.attrs.bits,
+    ranges: ranges
+  )
+}
+
+#let parse(content) = {
+  let struct-elmts = content.children.filter(e => "tag" in e and e.tag == "structure")
+  let color-elmts = content.children.filter(e => "tag" in e and e.tag == "color")
+
+  let structures = (:)
+  let colors = (:)
+
+  for struct-elmt in struct-elmts {
+    structures.insert(
+      struct-elmt.attrs.id,
+      parse-structure(struct-elmt)
+    )
+  }
+
+  for color-elmt in color-elmts {
+    let struct = color-elmt.attrs.structure
+    if not struct in colors {
+      colors.insert(struct, (:))
+    }
+
+    let span = color-elmt.attrs.end + "-" + color-elmt.attrs.start
+    colors.at(struct).insert(span, color-elmt.attrs.color)
+  }
+
+  return (
+    structures: structures,
+    colors: colors
+  )
+}
+
+#let load(path) = {
+  let content = xml(path).first()
+  return parse(content)
+}

typst.toml

@@ -0,0 +1,14 @@
+[package]
+name = "rivet"
+version = "0.3.0"
+compiler = "0.13.1"
+repository = "https://git.kb28.ch/HEL/rivet-typst"
+entrypoint = "src/lib.typ"
+authors = [
+    "Louis Heredero <https://git.kb28.ch/HEL>"
+]
+categories = [ "visualization" ]
+license = "Apache-2.0"
+description = "Register / Instruction Visualizer & Explainer Tool with Typst, using CeTZ"
+keywords = [ "assembly", "instruction", "binary" ]
+exclude = [ "gallery", "justfile", "docs" ]