Merge pull request 'v0.3.0: updates, left-to-right bits and "Loading" manual section' (#7) from dev into main

Reviewed-on: #7

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

@@ -31,14 +31,11 @@ It is based on the [homonymous Python script](https://git.kb28.ch/HEL/rivet/)
 *Click on the example image to jump to the code.*
 
 ## Usage
-For information, see the [manual](manual.pdf)
+For more information, see the [manual](manual.pdf)
 
-To use this package, simply import `schema` [src/lib.typ](src/lib.typ) and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
+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 "src/lib.typ": schema
+#import "@preview/rivet:0.3.0": schema
 #let doc = schema.load("path/to/schema.yaml")
 #schema.render(doc)
 ```
-
-## Installing
-> TODO

docs/config.typ

@@ -1,7 +1,7 @@
 /// Creates a dictionary of all configuration parameters
 ///
 /// - default-font-family (str): The default font family
-/// - default font-size (length): The absolute default font size
+/// - 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
@@ -15,7 +15,7 @@
 /// - 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[float]): TODO -> remove
+/// - 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
@@ -24,6 +24,8 @@
 /// - 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",
@@ -49,13 +51,15 @@
   left-labels: false,
   width: 1200,
   height: 800,
-  full-page: false
+  full-page: false,
+  all-bit-i: true,
+  ltr-bits: false
 ) = {}
 
 /// Dark theme config
-/// - ..args (any): see #doc-ref("config.config")
+/// - ..args (any): see @@config()
 #let dark(..args) = {}
 
 /// Blueprint theme config
-/// - ..args (any): see #doc-ref("config.config")
+/// - ..args (any): see @@config()
 #let blueprint(..args) = {}

docs/examples.typ

@@ -1,4 +1,3 @@
-#import "@preview/cetz:0.2.2": draw
 #import "../src/lib.typ": schema
 #import "../src/util.typ"
 
@@ -14,7 +13,7 @@
       box(
         stroke: black + 1pt,
         radius: .5em,
-        fill: if fill {yellow.lighten(80%)} else {none},
+        fill: if fill {orange.lighten(95%)} else {none},
         if show-src {
           let src-block = align(left, raw(src, lang: "typc"))
           table(

docs/schema.typ

@@ -1,14 +1,19 @@
 /// Loads a schema from a file or a raw block.
-/// This function returns a dictionary of structures
+/// 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): If it is a string, defines the path to load. \
+/// - path-or-schema (str, raw, dictionary):
-///   If it is a raw block, its content is directly parsed (the block's language will define the format to use)
+///   #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
-/// This functions
+/// - schema (dictionary): A schema dictionary, as returned by @@load()
-/// - structures (dictionary): A schema dictionary, as returned by #doc-ref("schema.load")
 /// - config (auto, dictionary): The configuration parameters, as returned by #doc-ref("config.config")
-#let render(structures, config: auto)
+/// - width (ratio, length): The width of the generated figure
+#let render(schema, config: auto, width: 100%) = {}

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/test.json

@@ -101,5 +101,11 @@
                 }
             }
         }
+    },
+    "colors": {
+        "main": {
+            "31-28": "#FF0000",
+            "11-4": [34, 176, 43]
+        }
     }
 }

gallery/test.typ

@@ -26,3 +26,114 @@ structures:
 #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

@@ -65,4 +65,7 @@
             <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

@@ -71,3 +71,11 @@ structures:
       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

@@ -1,20 +1,24 @@
-#import "@preview/tidy:0.3.0"
+#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)
 })
-#{
-  outline(indent: true, depth: 3)
-}
 
 #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 label-name = module + "-" + func
   let display-name = func
   if full {
     display-name = target
@@ -23,25 +27,327 @@
     label-name += "()"
     display-name += "()"
   }
-  link(label(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. For more information on the schema format, please check out the original project's #link("https://git.kb28.ch/HEL/rivet/src/branch/main/format.md")[format.md]
+This is a port of the #link("https://git.kb28.ch/HEL/rivet")[homonymous Python script] for Typst.
 
 = Usage
 
-Simply import `schema` from #link("src/lib.typ") and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
+#let import-stmt = "#import \"@preview/rivet:" + str(lib.version) + "\""
-#pad(left: 1em)[```typ
+
-#import "src/lib.typ": schema
+Simply import the `schema` module and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
-#let doc = schema.load("path/to/schema.yaml")
+#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": {
+      ...
+    }
+  }
+}
+```
+
+== 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
 
@@ -60,6 +366,7 @@ Aside from the default config, some example presets are also provided:
 #let doc-config = tidy.parse-module(
   read("docs/config.typ"),
   name: "config",
+  old-syntax: true,
   scope: (
     doc-ref: doc-ref
   )
@@ -71,6 +378,7 @@ Aside from the default config, some example presets are also provided:
 #let doc-schema = tidy.parse-module(
   read("docs/schema.typ"),
   name: "schema",
+  old-syntax: true,
   scope: (
     schema: schema,
     doc-ref: doc-ref

src/config.typ

@@ -22,7 +22,9 @@
   left-labels: false,
   width: 1200,
   height: 800,
-  full-page: false
+  full-page: false,
+  all-bit-i: true,
+  ltr-bits: false,
 ) = {
   return (
     default-font-family: default-font-family,
@@ -48,7 +50,9 @@
     left-labels: left-labels,
     width: width,
     height: height,
-    full-page: full-page
+    full-page: full-page,
+    all-bit-i: all-bit-i,
+    ltr-bits: ltr-bits,
   )
 }
 

src/lib.typ

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

src/range.typ

@@ -15,6 +15,9 @@
   }
   let start = int(start-end.last())
   let end = int(start-end.first())
+  if end < start {
+    (start, end) = (end, start)
+  }
   return (start, end)
 }
 

src/renderer.typ

@@ -1,4 +1,4 @@
-#import "@preview/cetz:0.2.2": canvas, draw
+#import "@preview/cetz:0.3.4": canvas, draw
 
 #import "range.typ" as rng
 #import "structure.typ"
@@ -33,19 +33,11 @@
     text-params.insert("style", "italic")
   }
 
-  let content-params = (:)
-  if fill != none {
-    content-params.insert("fill", fill)
-    content-params.insert("frame", "rect")
-    content-params.insert("padding", (4pt, 0pt))
-  }
-
   draw.content(
     (x, -y),
     text(txt, fill: color, size: size, ..text-params),
     anchor: anchor,
-    stroke: none,
+    stroke: none
-    ..content-params
   )
 }
 
@@ -253,7 +245,7 @@
 
 #let draw-dependency(
   draw-struct, config,
-  struct, structures, bits-x, bits-y, range_, desc-x, desc-y
+  struct, schema, bits-x, bits-y, range_, desc-x, desc-y
 ) = {
   let shapes = ()
 
@@ -261,7 +253,15 @@
   let bit-h = config.bit-height
   let arrow-margin = config.arrow-margin
 
-  let start-i = struct.bits - range_.end - 1
+  let to-real-i(i) = {
+    return if config.ltr-bits {
+      i
+    } else {
+      struct.bits - i - 1
+    }
+  }
+
+  let start-i = to-real-i(if config.ltr-bits {range_.start} else {range_.end})
   let start-x = bits-x + start-i * bit-w
   let width = rng.bits(range_) * bit-w
 
@@ -276,7 +276,7 @@
     depend-range.last-value-y
   }
 
-  let depend-start-i = struct.bits - depend-range.end - 1
+  let depend-start-i = to-real-i(depend-range.end)
   let depend-start-x = bits-x + depend-start-i * bit-w
   let depend-width = rng.bits(depend-range) * bit-w
   let depend-mid = depend-start-x + depend-width / 2
@@ -301,7 +301,7 @@
     val-struct = structure.load("", val-struct)
 
     let shapes_
-    (shapes_, ..) = draw-struct(config, val-struct, structures, ox: depend-start-x, oy: desc-y)
+    (shapes_, ..) = draw-struct(config, val-struct, schema, ox: depend-start-x, oy: desc-y)
     shapes += shapes_
 
     let y = desc-y + bit-h * 1.5
@@ -310,7 +310,9 @@
     let x2
 
     // Arrow from left to right
-    if depend-range.end > range_.start {
+    let i1 = to-real-i(range_.start)
+    let i2 = to-real-i(depend-range.end)
+    if i2 < i1 {
       x1 = depend-start-x + depend-width + arrow-margin
       x2 = start-x - arrow-margin
     
@@ -332,7 +334,7 @@
     prev-range-y = prev-depend-y
     depend-range.last-value-y = prev-depend-y
 
-    (shapes_, desc-y) = draw-struct(config, structures.at(data.structure), structures, ox: start-x, oy: desc-y)
+    (shapes_, desc-y) = draw-struct(config, schema.structures.at(data.structure), schema, ox: start-x, oy: desc-y)
     shapes += shapes_
   }
 
@@ -341,8 +343,9 @@
   return (shapes, desc-x, desc-y, struct)
 }
 
-#let draw-structure(config, struct, structures, ox: 0, oy: 0) = {
+#let draw-structure(config, struct, schema, ox: 0, oy: 0) = {
   let shapes
+  let colors = schema.at("colors", default: (:))
   let bg-col = config.background
   let txt-col = config.text-color
   let border-col = config.border-color
@@ -352,33 +355,91 @@
   let (bits-x, bits-y) = (ox, oy + bit-h)
   let bits-width = struct.bits * bit-w
   let start-bit = struct.start
+  let bit-colors = (:)
+
+  let to-real-i(i) = {
+    return if config.ltr-bits {
+      i - start-bit
+    } else {
+      struct.bits - i - 1 + start-bit
+    }
+  }
+
+  let to-bit-i(real-i) = {
+    return if config.ltr-bits {
+      real-i + start-bit
+    } else {
+      struct.bits - real-i - 1 + start-bit
+    }
+  }
+
+  for i in range(struct.bits) {
+    bit-colors.insert(str(i), bg-col)
+  }
+  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) {
+        let real-i = to-real-i(i)
+        bit-colors.insert(str(real-i), col)
+      }
+    }
+  }
+  let range-boundaries = ()
+  for r in struct.ranges.values() {
+    let i = to-real-i(if config.ltr-bits {r.start} else {r.end})
+    range-boundaries.push(i)
+  }
+
+  // Draw colors
+  for i in range(struct.bits) {
+    let bit-x = ox + i * bit-w
+    shapes += draw-rect(bit-colors.at(str(i)), bit-x, bits-y, bit-w+1, bit-h)
+  }
 
   // Draw rectangle around structure
   shapes += draw-rect(border-col, bits-x, bits-y, bits-width, bit-h, thickness: 2)
 
+  let indices = range(struct.start, struct.start + struct.bits)
+  if not config.all-bit-i {
+    indices = ()
+    for r in struct.ranges.values() {
+      indices.push(r.start)
+      indices.push(r.end)
+    }
+  }
+
   for i in range(struct.bits) {
     let bit-x = ox + i * bit-w
+    let bit-i = to-bit-i(i)
+
+    if bit-i in indices {
       shapes += draw-text(
-      str(struct.bits - i - 1 + start-bit),
+        str(bit-i),
         txt-col,
         bit-x + bit-w / 2,
         oy + bit-h / 2 
       )
+    }
 
     // Draw separator
-    if i != 0 {
+    if i != 0 and not i in range-boundaries {
-      shapes += draw-line(border-col, (bit-x, bits-y), (bit-x, bits-y + bit-h))
+      shapes += draw-line(border-col, (bit-x, bits-y), (bit-x, bits-y + bit-h * 0.2))
+      shapes += draw-line(border-col, (bit-x, bits-y + bit-h * 0.8), (bit-x, bits-y + bit-h))
     }
   }
 
   let ranges = structure.get-sorted-ranges(struct)
+  if config.ltr-bits {
+    ranges = ranges.rev()
+  }
   if config.left-labels {
     ranges = ranges.rev()
   }
 
   let desc-x
   if config.force-descs-on-side {
-    desc-x = config.margins.at(3) + structures.main.bits * bit-w
+    desc-x = config.margins.at(3) + schema.structures.main.bits * bit-w
     if config.left-labels {
       desc-x = config.width - desc-x
     }
@@ -393,20 +454,15 @@
 
   // Names + simple descriptions
   for range_ in ranges {
-    let start-i = struct.bits - range_.end + start-bit - 1
+    let start-i = to-real-i(if config.ltr-bits {range_.start} else {range_.end})
     let start-x = bits-x + start-i * bit-w
     let width = rng.bits(range_) * bit-w
 
     let name-x = start-x + width / 2
     let name-y = bits-y + bit-h / 2
 
-    shapes += draw-rect(
+    let line-x = if config.ltr-bits {start-x + width} else {start-x}
-      bg-col,
+    shapes += draw-line(border-col, (line-x, bits-y), (line-x, bits-y + bit-h))
-      start-x + bit-w / 2,
-      name-y - bit-h * 0.3,
-      width - bit-w,
-      bit-h * 0.6
-    )
     shapes += draw-text(range_.name, txt-col, name-x, name-y, fill: bg-col)
     
     if range_.description != "" {
@@ -424,7 +480,7 @@
       let shapes_
       (shapes_, desc-x, desc-y, struct) = draw-dependency(
         draw-structure, config,
-        struct, structures, bits-x, bits-y, range_, desc-x, desc-y
+        struct, schema, bits-x, bits-y, range_, desc-x, desc-y,
       )
       shapes += shapes_
     }
@@ -433,13 +489,13 @@
   return (shapes, desc-y)
 }
 
-#let render(config, structures) = {
+#let render(config, schema, width: 100%) = {
   set text(
     font: config.default-font-family,
     size: config.default-font-size
   )
 
-  let main = structures.main
+  let main = schema.structures.main
   let ox = config.margins.at(3)
   if config.left-labels {
     ox = config.width - ox - main.bits * config.bit-width
@@ -458,9 +514,9 @@
 
   set page(..params)
 
-  canvas(length: 1pt, background: config.background, {
+  let cnvs = canvas(length: 1pt, background: config.background, {
     let (shapes, _) = draw-structure(
-      config, main, structures,
+      config, main, schema,
       ox: ox,
       oy: config.margins.at(0)
     )
@@ -475,6 +531,36 @@
       fill: none
     )
   })
+
+  if config.full-page {
+    cnvs
+  } else {
+    layout(size => {
+      let m = measure(cnvs)
+      let w = m.width
+      let h = m.height
+      let base-w = if type(width) == ratio {
+        size.width * width
+      } else {
+        width
+      }
+      let r = if w == 0 {
+        0
+      } else {
+        base-w / w
+      }
+
+      let new-w = w * r
+      let new-h = h * r
+      r *= 100%
+
+      box(
+        width: new-w,
+        height: new-h,
+        scale(x: r, y: r, cnvs, reflow: true)
+      )
+    })
+  }
 }
 
 #let make(config) = {

src/schema.typ

@@ -25,7 +25,7 @@
 
 #let parse-raw(schema) = {
   let lang = schema.lang
-  let content = schema.text
+  let content = bytes(schema.text)
   if not lang in valid-extensions {
     let fmts = valid-extensions.join(", ")
     fmts = "(" + fmts + ")"
@@ -33,33 +33,60 @@
   }
 
   if lang == "yaml" {
-    return yaml.decode(content)
+    return yaml(content)
   } else if lang == "json" {
-    return json.decode(content)
+    return json(content)
   } else if lang == "xml" {
-    return xml-loader.parse(xml.decode(content).first())
+    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
+  return (
+    structures: structures,
+    colors: schema.at("colors", default: (:))
+  )
 }
 
-#let render(structures, config: auto) = {
+#let render(schema, width: 100%, config: auto) = {
   if config == auto {
     config = conf.config()
   }
   let renderer_ = renderer.make(config)
-  (renderer_.render)(structures)
+  (renderer_.render)(schema, width: width)
 }

src/xml-loader.typ

@@ -83,8 +83,10 @@
 
 #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(
@@ -93,8 +95,19 @@
     )
   }
 
+  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
+    structures: structures,
+    colors: colors
   )
 }
 

typst.toml

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