gum-jsx 1.5.0 → 1.6.0

package/README.md

@@ -1,24 +1,38 @@
 <div align="center">
-<img src="image/logo.png" alt="logo" width="500" />
+<img src="images/logo.svg" alt="logo" width="500" />
 <br/>
 </div>
 
 <div align="center">
-<img src="image/nexus.svg" alt="nexus" width="250" />
+<img src="images/nexus.svg" alt="nexus" width="250" />
 <br/><br/>
 </div>
 
-A language for creating visualizations using a React-like JSX dialect that evaluates to SVG. Designed for general graphics, plots, graphs, and network diagrams.
+<p align="center">
+  Gum is a JSX vector graphics language that evaluates to SVG.
+  <br/>
+  It is designed for plots, diagrams, flow charts, and more.
+</p>
 
-Head to **[compendiumlabs.ai/gum](https://compendiumlabs.ai/gum)** for a live demo and documentation. For Python bindings, see [gum.py](https://github.com/CompendiumLabs/gum.py).
+<p align="center">
+  <a href="https://compendiumlabs.ai/gum/studio">Live Demo</a>
+  |
+  <a href="https://compendiumlabs.ai/gum/docs">Documentation</a>
+  |
+  <a href="https://compendiumlabs.ai/gum/docs/gala">Gallery</a>
+</p>
 
-# Installation
+## Installation
 
 ```bash
 bun i gum-jsx
 ```
 
-# Usage
+This will install the `gum` command and the `gum-jsx` package. Add a `-g` flag to install globally. To download the skill file (which is just a zip), click on the release on the right or use `skills/gum-jsx.skill`.
+
+See [react-gum-jsx](https://github.com/CompendiumLabs/react-gum-jsx) for React bindings. See [gum.py](https://github.com/CompendiumLabs/gum.py) for a Python wrapper.
+
+## Library Usage
 
 Write some `gum.jsx` code:
 
@@ -38,49 +52,50 @@ const svg = elem.svg()
 
 Which will produce the following:
 
-<img src="image/plot.png" alt="sine wave plot" width="750" />
+<img src="images/plot.svg" alt="sine wave plot" width="750" />
 
 You can also use JavaScript directly:
 
 ```javascript
 import { Svg, Box, Text, Circle, Plot, SymLine, pi, sin } from 'gum'
 const elem = new Plot({
-  children: new SymLine({ fy: sin, stroke: blue, stroke_width: 2 }),
+  children: [ new SymLine({ fy: sin, stroke: blue, stroke_width: 2 }) ],
   xlim: [0, 2*pi], ylim: [-1.5, 1.5], grid: true, margin: [0.2, 0.1], aspect: 2,
 })
 const svg = elem.svg()
 ```
 
-# CLI
+## Command Line
 
-You can use the `gum` command to convert `gum.jsx` into SVG text or PNG data. You can even just display it directly in the terminal! For the latter you need a terminal that supports images, such as `ghostty` or `kitty`. There are a bunch of code examples in `docs/code/` and `docs/gallery/` to try out.
+You can use the `gum` command to convert `gum.jsx` into SVG text or PNG data. You can even just display it directly in the terminal. For the latter you need a terminal that supports images, such as `ghostty` or `kitty`. There are a bunch of code examples in `docs/code/` and `gala/code/` to try out.
 
 Generate an SVG from a `gum.jsx` file:
 
 ```bash
-cat input.jsx | bun run cli -f svg > output.svg
+gum input.jsx -o output.svg
 ```
 
 Generate a PNG from a `gum.jsx` file:
 
 ```bash
-cat input.jsx | bun run cli -f png > output.png
+gum input.jsx -o output.png
 ```
 
 Display a `gum.jsx` file in the terminal:
 ```bash
-cat input.jsx | bun run cli
+gum input.jsx
 ```
 
 CLI options:
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `-s, --size <size>` | Image size in pixels | 500 |
+| `file` | Gum JSX file to render | stdin |
+| `-s, --size <size>` | Image size in pixels | 1000 |
 | `-t, --theme <theme>` | Theme: `light` or `dark` | light |
-| `-w, --width <width>` | Width of the PNG | null |
-| `-h, --height <height>` | Height of the PNG | null |
-| `-f, --format <format>` | Format: `svg` or `png` | `svg` |
-| `-b, --background <color>` | Background color | null (transparent) |
-| `-o, --output <output>` | Output file | null (stdout) |
-| `-u, --update` | Live update display | false |
+| `-b, --background <color>` | Background color | white |
+| `-f, --format <format>` | Format: `json`, `svg`, `png`, `kitty` | auto |
+| `-o, --output <output>` | Output file | stdout |
+| `-w, --width <width>` | Max width of the PNG | auto |
+| `-h, --height <height>` | Max height of the PNG | auto |
+| `-d, --dev` | Live update display | off |

package/docs/code/Arc.jsx

@@ -1,4 +1,4 @@
-// elliptical and circular arcs using degree ranges
+// elliptical and circular arcs using start and end angles
 <Group>
   <Arc pos={[0.32, 0.5]} size={[0.44, 0.32]} start={-45} end={210} stroke={blue} stroke-width={2} />
   <Arc pos={[0.72, 0.5]} size={0.32} start={90} end={-150} stroke={red} stroke-width={2} />

package/docs/code/Edge.jsx

@@ -1,6 +1,6 @@
-// Two boxes with text in them that have black borders and gray interiors. The box in the upper left says "hello" and the box in the lower right says "world!". The arrowhead from "Hello" is filled in red and the arrowhead to "World!" is filled in blue.
-<Network aspect node-fill={gray} edge-arrow>
-  <Node id="hello" pos={[0.25, 0.25]}>Hello</Node>
-  <Node id="world" pos={[0.75, 0.75]}>World!</Node>
-  <Edge start="hello" end="world" start-fill={red} end-fill={blue} />
+// Two boxes with text in them that have black borders and gray interiors. The box in the upper left says "hello" and the box in the lower right says "world!". There is a city-block path connecting the two boxes. The arrowhead from "Hello" is filled in red and the arrowhead to "World!" is filled in blue.
+<Network aspect node-fill={gray} edge-arrow edge-rounded={0.025}>
+  <Node id="hello" pos={[0.3, 0.25]}>Hello</Node>
+  <Node id="world" pos={[0.7, 0.75]}>World!</Node>
+  <Edge start="hello" end="world" points={[[0.3, 0.5], [0.7, 0.5]]}/>
 </Network>

package/docs/code/Node.jsx

@@ -1,6 +1,23 @@
-// Two boxes with text in them that have black borders and gray interiors. The box in the upper left says "hello" and the box in the lower right says "world!".
-<Network aspect node-fill={gray}>
-  <Node id="hello" pos={[0.25, 0.25]}>Hello</Node>
-  <Node id="world" pos={[0.75, 0.75]}>World!</Node>
-  <Edge start="hello" end="world" />
+// A simple connected network where each rounded node contains an emoji icon stacked above a text label. The example shows idea → design → launch.
+<Network aspect={2} node-fill={gray} node-rounded node-padding node-ysize={0.35}>
+  <Node id="idea" pos={[0.2, 0.5]}>
+    <VStack spacing={0.15}>
+      <Text>💡</Text>
+      <Text stack-size={0.25}>Idea</Text>
+    </VStack>
+  </Node>
+  <Node id="design" pos={[0.5, 0.5]}>
+    <VStack spacing={0.15}>
+      <Text>🎨</Text>
+      <Text stack-size={0.25}>Design</Text>
+    </VStack>
+  </Node>
+  <Node id="launch" pos={[0.8, 0.5]}>
+    <VStack spacing={0.15}>
+      <Text>🚀</Text>
+      <Text stack-size={0.25}>Launch</Text>
+    </VStack>
+  </Node>
+  <Edge start="idea" end="design" />
+  <Edge start="design" end="launch" />
 </Network>

package/docs/code/RoundedLine.jsx

@@ -0,0 +1,15 @@
+// a city-block route in blue with rounded corners, with the underlying
+// vertices marked as black dots to show how the corners are rounded
+const points = [
+  [0.10, 0.20],
+  [0.40, 0.20],
+  [0.40, 0.80],
+  [0.70, 0.80],
+  [0.70, 0.50],
+  [0.90, 0.50],
+]
+return <Frame margin>
+  <Line opacity={0.3} points={points} />
+  <RoundedLine stroke={blue} stroke-width={2} radius={0.08} points={points} />
+  <Points point-size={0.015} points={points} />
+</Frame>

package/docs/code/TitleFrame.jsx

@@ -1,9 +1,9 @@
-// Various food emojis are arrnaged in a spaced out grid and framed with the title "Fruits & Veggies". Each emoji is framed by a rounded square with a gray background.
+// Various food emojis are arrnaged in a spaced out grid and framed with the title "Fruits & Veggies". Each emoji is framed by a rounded square
 const emoji = [ '🍇', '🥦', '🍔', '🍉', '🍍', '🌽', '🍩', '🥝', '🍟' ]
 return <TitleFrame title="Fruits & Veggies" margin padding rounded>
   <Grid rows={3} spacing={0.05}>
     {emoji.map(e =>
-      <Frame aspect rounded fill padding><Text>{e}</Text></Frame>
+      <Frame aspect rounded padding><Text>{e}</Text></Frame>
     )}
   </Grid>
 </TitleFrame>

package/docs/meta.json

@@ -18,7 +18,8 @@
         "Shape",
         "Fill",
         "Spline",
-        "Arrow"
+        "Arrow",
+        "RoundedLine"
     ],
     "text": [
         "Text",

package/docs/text/Arc.md

@@ -1,11 +1,11 @@
 # Arc
 
-*Inherits*: [Element](/docs/Element)
+*Inherits*: **Path** > [Element](/docs/Element)
 
 This draws an elliptical arc that inscribes its allocated rectangle, like [Ellipse](/docs/Ellipse), but only over a selected angular interval.
 
 Parameters:
-- `degrees` = `[0, 360]` — start and end angle in degrees
-- `range` — alias for `degrees`
+- `start` — first angle in degrees
+- `end` — second angle in degrees
 
-Angles follow gum's usual screen-space convention: `0` points right and `90` points down.
+Angles follow the current coordinate system: `0` points right and positive angles follow positive y. In the default screen coordinate system, `90` points down; inside a default [Graph](/docs/Graph), where y is flipped upward, `90` points up. The two angles are treated as an interval; their order does not change the drawn arc.

package/docs/text/Arrow.md

@@ -13,7 +13,8 @@ Parameters:
 - `start-dir` / `end-dir` — the direction of the arrowheads at the start and end
 - `arrow` / `arrow-start` / `arrow-end` — toggles whether the respective arrowheads are included. Defaults to `true` for `arrow-end` and `false` for `arrow-start`, meaning a directed graph edge
 - `arrow-size` = `0.04` — size of the arrowhead
-- `curve` = `null` — curvature factor forwarded to the spline (`null` or zero means straight line)
+- `curve` = `null` — curvature factor forwarded to the [Spline](/docs/Spline) (`null` or zero means straight line)
+- `rounded` = `null` — corner radius for a city-block path through `points`. When set, the shaft is a [RoundedLine](/docs/RoundedLine) (takes precedence over `curve`)
 
 Subunit names:
 - `line` — forwarded to the shaft line

package/docs/text/Edge.md

@@ -13,4 +13,5 @@ Parameters:
 - `points` — the intermediate points to draw the spline between
 - `arrow` / `arrow-start` / `arrow-end` — toggles whether the respective arrowheads are included. Defaults to `true` for `arrow-end` and `false` for `arrow-start`, meaning a directed graph edge
 - `arrow-size` = `0.04` — the arrowhead size to use for both arrows
-- `curve` = `2` — curvature factor forwarded to the spline
+- `curve` = `2` — curvature factor forwarded to the [Spline](/docs/Spline)
+- `rounded` = `null` — corner radius for a city-block path using [RoundedLine](/docs/RoundedLine)

package/docs/text/RoundedLine.md

@@ -0,0 +1,13 @@
+# RoundedLine
+
+*Inherits*: **Path** > [Element](/docs/Element)
+
+The `RoundedLine` element draws a polyline through a series of points with rounded corners at each interior vertex. It is most useful for *city-block* (right-angle) routes — for instance, edges in a network diagram that you want to bend cleanly around obstacles rather than curving with [Spline](/docs/Spline). Spline curvature along an otherwise-straight `points` route produces undulating bumps; `RoundedLine` keeps the straight segments straight and only rounds the turns.
+
+Each interior vertex is replaced by a circular arc whose radius is derived from `radius` in coord space. When the coordinate system is not square, `RoundedLine` uses the smaller mapped axis so corners stay circular in pixel space instead of stretching into ellipses. If a segment is too short for the requested radius, the corner is automatically clamped so adjacent corners can never overlap.
+
+For straight-line polylines (no corner rounding) use [Line](/docs/Line). For smooth curves through points use [Spline](/docs/Spline).
+
+Parameters:
+- `points` — array of point coordinates (minimum of 2 required)
+- `radius` = `0.05` — corner back-off distance in coord space, applied at each interior vertex

package/docs/text/Stack.md

@@ -2,17 +2,19 @@
 
 *Inherits*: [Group](/docs/Group) > [Element](/docs/Element)
 
-Stack one or more **Element** either vertically or horizontally. There are specialized components **VStack** and **HStack** that don't take the `direc` argument. Proportional spacing between children can be specified with the `spacing` parameter. This handles child positioning and sizing, so any `pos`/`size` arguments will be overridden.
+Stack one or more **Element** either vertically or horizontally. There are specialized components **VStack** and **HStack** that don't take the `direc` argument. This element handles child positioning and sizing, so any child `pos`/`size` arguments will be overridden. Proportional spacing between children can be specified with the `spacing` parameter.
 
-Elements can specify their own sizing with the `stack-size` parameter, which controls the child's relative share of the available space along the stack axis (do not use `size`/`xsize`/`ysize` on child elements, this will be overridden). If `stack-size` is not specified and `stack-expand` is not set to `false`, space will be distributed according to the child's aspect ratio. If `stack-expand` is set to `false`, the child will be given an even share of the remaining space.
+The simplest case is when all children have aspect ratios. In the **HStack** case, the overall aspect ratio of the stack is the sum of the child aspect ratios. Children are allocated space in proportion to their aspect ratios. The **VStack** case is similar, but we need to deal in inverse aspect ratio terms.
+
+When some children lack aspect ratios, they will be allocated any remaining space evenly. Regardless of whether a child has an aspect ratio or not, it can be given a fixed size with the `stack-size` parameter. This is specified as a fraction between 0 and 1, independent of spacing.
 
 Whenever possible, the aspect ratio of the overall stack is set so that all elements with defined aspect ratios will reach full width (in the **VStack** case) or full height (in the **HStack** case).
 
 Child parameters:
 - `stack-size` = `null` — the child's relative share of the available space along the stack axis
-- `stack-expand` = `true` — whether to expand the child to fill the remaining space
 
 Parameters:
 - `direc` — the direction of stacking: `v` or `h`
 - `spacing` = `0` — total amount of space to add between child elements
+- `justify` = `center` — how to justify children along the stack axis
 - `even` = `false` — whether to distribute sizes evenly (`stack-size = 1 / n`)

package/gala/code/macro_economy.jsx

@@ -6,23 +6,23 @@ const col = {
 }
 
 return <Slide title="Macroeconomic Flows">
-  <Network aspect={2} coord={[0, 0, 1.6, 0.8]} node-ysize={0.16} node-rounded={0.06} node-fill={gray} node-text-color="#333" edge-stroke-width={2} edge-arrow-size={0.02} edge-stroke="#444">
-    <Node id="trade" pos={[0.8, 0.15]} fill={col.trade} fill-opacity={0.15} border-stroke={col.trade} wrap={6}>Foreign Trade</Node>
-    <Node id="prod" pos={[0.3, 0.4]} fill={col.prod} fill-opacity={0.15} border-stroke={col.prod} wrap={6}>Producers (Firms)</Node>
-    <Node id="cons" pos={[1.3, 0.4]} fill={col.cons} fill-opacity={0.15} border-stroke={col.cons} wrap={6}>Consumers (Households)</Node>
-    <Node id="govt" pos={[0.8, 0.65]} ysize={0.12} fill={col.govt} fill-opacity={0.15} border-stroke={col.govt} wrap={6}>Government</Node>
+  <Network aspect={2} coord={[0, 0, 1.6, 0.8]} node-ysize={0.16} node-rounded={0.06} node-fill={gray} node-fill-opacity={0.15} edge-stroke-width={1} edge-arrow-size={0.04} edge-stroke="#444" edge-arrow edge-arrow-curve={2.5} node-text-wrap={6}>
+    <Node id="trade" pos={[0.8, 0.15]} fill={col.trade} border-stroke={col.trade} text-color={col.trade}>Foreign Trade</Node>
+    <Node id="prod" pos={[0.3, 0.4]} fill={col.prod} border-stroke={col.prod} text-color={col.prod}>Producers (Firms)</Node>
+    <Node id="cons" pos={[1.3, 0.4]} fill={col.cons} border-stroke={col.cons} text-color={col.cons}>Consumers (Households)</Node>
+    <Node id="govt" pos={[0.8, 0.65]} ysize={0.12} fill={col.govt} border-stroke={col.govt} text-color={col.govt}>Government</Node>
 
-    <Edge start="prod" end="cons" arrow />
-    <Edge start="govt" end="prod" end-side="s" arrow curve={2.5} />
-    <Edge start="govt" end="cons" end-side="s" arrow curve={2.5} />
-    <Edge start="trade" end="prod" end-side="n" arrow curve={2.5} />
-    <Edge start="trade" end="cons" end-side="n" arrow curve={2.5} />
+    <Edge start="prod" end="cons" />
+    <Edge start="govt" end="prod" end-side="s" />
+    <Edge start="govt" end="cons" end-side="s" />
+    <Edge start="trade" end="prod" end-side="n" />
+    <Edge start="trade" end="cons" end-side="n" />
 
     <Text pos={[0.8, 0.35]} ysize={0.05} color={col.prod}>Goods + Services →</Text>
     <Text pos={[0.8, 0.45]} ysize={0.05} color={col.cons}>← Wages, Rent, Profit</Text>
-    <Text pos={[0.3, 0.65]} ysize={0.04} color={darkgray} spin={30}>Subsidies / Taxes</Text>
-    <Text pos={[1.3, 0.65]} ysize={0.04} color={darkgray} spin={-30}>Transfers / Taxes</Text>
-    <Text pos={[0.3, 0.13]} ysize={0.04} color={darkgray} spin={-30}>Imports / Exports</Text>
-    <Text pos={[1.3, 0.13]} ysize={0.04} color={darkgray} spin={30}>Transfers</Text>
+    <Text pos={[0.3, 0.65]} ysize={0.045} spin={30}>Subsidies / Taxes</Text>
+    <Text pos={[1.3, 0.65]} ysize={0.045} spin={-30}>Transfers / Taxes</Text>
+    <Text pos={[0.3, 0.13]} ysize={0.045} spin={-30}>Imports / Exports</Text>
+    <Text pos={[1.3, 0.13]} ysize={0.045} spin={30}>Transfers</Text>
   </Network>
 </Slide>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gum-jsx",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Language for vector graphics generation.",
   "type": "module",
   "author": "Douglas Hanley",
@@ -41,7 +41,7 @@
   "scripts": {
     "cli": "bun ./scripts/gum.ts",
     "test": "bun ./scripts/test.ts",
-    "skill": "bun ./scripts/skill.ts && zip -r skills/gum-jsx.skill skills/gum-jsx",
+    "skill": "bun ./scripts/skill.ts && cd skills/gum-jsx && zip -r gum-jsx.skill * && mv gum-jsx.skill ..",
     "claude": "bun run skill && bun ./scripts/claude.ts"
   },
   "bin": {
@@ -51,6 +51,7 @@
     "@types/node": "^25.2.3",
     "@types/papaparse": "^5.5.2",
     "acorn-jsx": "^5.3.2",
+    "canvas": "^3.2.3",
     "emojibase-regex": "^17.0.0",
     "katex": "^0.16.33",
     "linebreak": "^1.1.0",
@@ -60,7 +61,6 @@
   },
   "optionalDependencies": {
     "@modelcontextprotocol/sdk": "^1.25.3",
-    "@resvg/resvg-js": "^2.6.2",
     "commander": "^14.0.3",
     "express": "^5.2.1",
     "zod": "^4.3.6"

package/prompt/gen.md

@@ -1,49 +1,43 @@
 # Using CLI commands
 
-To test the output of a particular `gum.jsx` snippet or file, you can pipe it to the `gum` command, which is assumed to be installed globally. If you have vision capabilities, this can be useful for see the actual output of the code, either in SVG or PNG format. Even without vision, one can infer properties of the output by reading the SVG output directly.
+To test the output of a particular Gum JSX snippet or file, you can pipe it to the `gum` command. If this command is not available globally, try to install the `gum-jsx` package with Bun (preferred) or NPM.
+
+If you have vision capabilities, seeing an actual image can be useful for see the actual output of the code, either in SVG or PNG format. Even without vision, one can infer properties of the output by reading the SVG output directly.
 
 For one off tests, pipe the code using `echo`. It is recommended that you use single quotes as the outer delimiter, to accommodate code that includes double quotes for component properties (e.g. `justify="left"`).
 
 For more difficult tasks, use a file provide the filename as an argument or `cat` it in. Using a file allows you to view and refine your code repeatedly. If you wish to avoid output redirection to a file, use the `-o` option to write to a file.
 
-In general, it makes a lot of sense to write a draft to a file, view its output, then refine the code until you're satisfied. This way you can start simple and add complexity as needed.
+In general, it makes a lot of sense to write a draft to a file, view its output, then refine the code until you're satisfied. This way you can start simple and add complexity as needed. When in doubt, write the output file to the same directory as the input file with the same base name but with the appropriate extension.
 
 **Examples:**
 ```bash
-# Generate SVG from a gum.jsx snippet
-echo '<Rectangle rounded fill={blue} />' | gum -f svg > output.svg
-
-# Generate PNG from a gum.jsx snippet
-echo '<Rectangle rounded fill={blue} />' | gum -f png > output.png
+# generate an .svg file from a .jsx file
+gum test.jsx -o test.svg
 
-# Generate SVG from a .jsx file
-cat test.jsx | gum -f svg > output.svg
+# generate a .png file from a .jsx file
+gum test.jsx -o test.png
 
-# Generate PNG from a .jsx file
-cat test.jsx | gum -f png > output.png
+# generate SVG from a Gum JSX snippet and print to stdout
+echo '<Rectangle rounded fill={blue} />' | gum
 
-# Generate SVG from a .jsx file without redirection
-gum test.jsx -o output.svg
-
-# Generate PNG from a .jsx file without redirection
-gum test.jsx -o output.png
+# generate PNG from a Gum JSX snippet and save to file
+echo '<Rectangle rounded fill={blue} />' | gum -o test.png
 ```
 
 **CLI options:**
-- `file`: gum.jsx file to render (reads from stdin if not provided)
+- `file`: Gum JSX file to render (reads from stdin if not provided)
 - `-t, --theme <theme>`: theme to use (default: light)
 - `-b, --background <color>`: background color (default: white)
-- `-i, --input <input>`: input format (default: jsx)
-- `-f, --format <format>`: output format: svg or png (default: kitty or auto-detected)
+- `-f, --format <format>`: output format: json, svg, png, kitty (default: auto)
 - `-o, --output <output>`: output file (default: stdout)
 - `-s, --size <size>`: size of the SVG (default: 1000)
-- `-w, --width <width>`: width of the PNG (default: auto)
-- `-h, --height <height>`: height of the PNG (default: auto)
-- `-u, --update`: enable live update display
+- `-w, --width <width>`: max width of the PNG (default: null)
+- `-h, --height <height>`: max height of the PNG (default: null)
 
-# Using in TypeScript
+# Using Gum in TypeScript
 
-You can use gum.jsx directly in TypeScript/JavaScript code by importing from the `gum-jsx` package. This is useful for programmatic generation, integration into other tools, or when you want to avoid the CLI.
+There are a couple of ways to use Gum in TypeScript. You can evaluate JSX strings directly, or you can construct Gum components directly. If you want to use Gum components in React, you can use the `react-gum-jsx` package.
 
 ## Evaluating JSX strings
 
@@ -77,7 +71,7 @@ const tree = evaluateGum(code, {
 
 ## Using components directly
 
-You can also construct components directly by importing them from `gum-jsx` and calling their constructors. Each component takes a single args object.
+You can also construct Gum components directly by importing them from `gum-jsx` and calling their constructors. Each component takes a single args object.
 
 ```typescript
 import { Svg, Rectangle, Circle, HStack, Text, blue, red, white } from 'gum-jsx'
@@ -99,3 +93,38 @@ When constructing manually, note that:
 - Utility functions like `range`, `linspace`, `zip` are also available from `gum-jsx`
 - Call `.svg()` on the top-level `Svg` element to get the SVG string output
 - The realized size of the SVG is available on the `Svg` element as `size`
+
+## Using in React with `react-gum-jsx`
+
+You can use Gum components directly in React components by importing from the `react-gum-jsx` package. This is useful for creating interactive visualizations in React.
+
+Here's an example of how to use Gum in a React component. It's basically the same as what you would pass to `evaluateGum` but as a default export:
+
+```tsx
+import { blue, red } from 'gum-jsx'
+import { GUM } from 'react-gum-jsx'
+const { Frame, HStack, Square, Circle, Text } = GUM
+
+export default function Demo() {
+  return <Frame padding margin rounded>
+    <HStack padding>
+      <Square fill={blue} />
+      <Circle fill={red} />
+      <Text>Hello</Text>
+    </HStack>
+  </Frame>
+}
+```
+
+To run this in a CLI setting, just pass a file with a default export to the `gum-react` command that comes with the `react-gum-jsx` package. This takes very similar arguments to the regular `gum` command.
+
+If you are in a web setting, you'll need to wrap this export in a `<Gum>` component, which takes roughly the same arguments as `evaluateGum`. This would look like:
+
+```tsx
+import { Gum } from 'react-gum-jsx'
+<Gum size={[640, 360]}>
+  <Demo />
+</Gum>
+```
+
+If the inner component has an `aspect` it will be embedded inside the given size bounds. If it is aspectless, it will be stretched to fill the given size bounds.