Update to Gum

{
  "description": "Create and revise SVG diagrams, plots, mathematical figures, and slides using Gum's JSX language. Use for authoring or debugging Gum figures, not general React or HTML development.",
  "included_files": [
    {
      "relative_path": "references/elements.md",
      "size_in_bytes": 13583
    },
    {
      "relative_path": "references/elements/geometry.md",
      "size_in_bytes": 48285
    },
    {
      "relative_path": "references/elements/layout.md",
      "size_in_bytes": 35829
    },
    {
      "relative_path": "references/elements/maps.md",
      "size_in_bytes": 16419
    },
    {
      "relative_path": "references/elements/math.md",
      "size_in_bytes": 49277
    },
    {
      "relative_path": "references/elements/networks.md",
      "size_in_bytes": 10390
    },
    {
      "relative_path": "references/elements/plotting.md",
      "size_in_bytes": 70413
    },
    {
      "relative_path": "references/elements/special.md",
      "size_in_bytes": 2788
    },
    {
      "relative_path": "references/elements/text.md",
      "size_in_bytes": 31096
    },
    {
      "relative_path": "references/gallery.md",
      "size_in_bytes": 10131
    },
    {
      "relative_path": "references/gallery/api.md",
      "size_in_bytes": 3145
    },
    {
      "relative_path": "references/gallery/geometry.md",
      "size_in_bytes": 43258
    },
    {
      "relative_path": "references/gallery/layout.md",
      "size_in_bytes": 27398
    },
    {
      "relative_path": "references/gallery/maps.md",
      "size_in_bytes": 25909
    },
    {
      "relative_path": "references/gallery/math.md",
      "size_in_bytes": 44487
    },
    {
      "relative_path": "references/gallery/networks.md",
      "size_in_bytes": 23649
    },
    {
      "relative_path": "references/gallery/plotting.md",
      "size_in_bytes": 41093
    },
    {
      "relative_path": "references/gallery/text.md",
      "size_in_bytes": 9006
    },
    {
      "relative_path": "references/guides.md",
      "size_in_bytes": 2739
    },
    {
      "relative_path": "references/guides/arrays.md",
      "size_in_bytes": 3472
    },
    {
      "relative_path": "references/guides/colors.md",
      "size_in_bytes": 1882
    },
    {
      "relative_path": "references/guides/coordinates.md",
      "size_in_bytes": 3564
    },
    {
      "relative_path": "references/guides/custom_elements.md",
      "size_in_bytes": 11951
    },
    {
      "relative_path": "references/guides/fitting.md",
      "size_in_bytes": 3603
    },
    {
      "relative_path": "references/guides/fonts.md",
      "size_in_bytes": 3976
    },
    {
      "relative_path": "references/guides/gum.md",
      "size_in_bytes": 3100
    },
    {
      "relative_path": "references/guides/jsx.md",
      "size_in_bytes": 6670
    },
    {
      "relative_path": "references/guides/maps.md",
      "size_in_bytes": 11383
    },
    {
      "relative_path": "references/guides/math.md",
      "size_in_bytes": 8220
    },
    {
      "relative_path": "references/guides/math_export.md",
      "size_in_bytes": 7091
    },
    {
      "relative_path": "references/guides/math_fonts.md",
      "size_in_bytes": 4751
    },
    {
      "relative_path": "references/guides/math_helpers.md",
      "size_in_bytes": 4954
    },
    {
      "relative_path": "references/guides/point_values.md",
      "size_in_bytes": 5420
    },
    {
      "relative_path": "references/guides/positioning.md",
      "size_in_bytes": 7746
    },
    {
      "relative_path": "references/guides/projections.md",
      "size_in_bytes": 16432
    },
    {
      "relative_path": "references/guides/random.md",
      "size_in_bytes": 2518
    },
    {
      "relative_path": "references/guides/rendering.md",
      "size_in_bytes": 10898
    },
    {
      "relative_path": "references/guides/sizing.md",
      "size_in_bytes": 13181
    },
    {
      "relative_path": "references/guides/stack.md",
      "size_in_bytes": 8210
    },
    {
      "relative_path": "references/guides/style.md",
      "size_in_bytes": 7440
    },
    {
      "relative_path": "references/guides/themes.md",
      "size_in_bytes": 3648
    },
    {
      "relative_path": "references/guides/units.md",
      "size_in_bytes": 4051
    },
    {
      "relative_path": "references/guides/vectors.md",
      "size_in_bytes": 2722
    }
  ],
  "name": "gum-jsx",
  "skill_md_contents": "---\nname: gum-jsx\ndescription: Create and revise SVG diagrams, plots, mathematical figures, and slides using Gum's JSX language. Use for authoring or debugging Gum figures, not general React or HTML development.\n---\n\n# Gum\n\nGum describes figures with JavaScript and JSX, then measures and renders them as\nSVG. It is not React, HTML, or a browser DOM. For environment setup, follow\nthe instructions on CLI setup below before searching for or installing Gum.\n\nUse the references for supported components and properties. Preserve the\nuser's chosen data, visual intent, and output format. Ordinary functions returning\nelements are the simplest way to make reusable components.\n\n## Source format\n\nA single bare JSX element is returned automatically. With declarations or other\nstatements, finish with an explicit `return`. Return one element for a figure;\nrendering hosts wrap a bare root in `Svg`. Put design dimensions and base\nfont props on that root. Use an explicit `Svg` when you need viewport control;\nits width and height accept pixels only (`px(640)` or `\"640px\"`), or can be omitted\nto hug content. The evaluator supplies elements, `px`, `em`, palette constants,\nand numeric helpers. Math bindings are supplied by the rendering host as well.\n\nGum source runs as a function body, not an imported module. Do not put static\nimports in an evaluated `.jsx` file. JSX attribute dashes become underscores:\n`font-size` reaches a component as `font_size`. Use underscore keys in JavaScript\nobjects and spread props; camelCase is not normalized. Unknown SVG/CSS attributes\nare not automatically forwarded.\n\nFor example, a rounded frame around a circle needs no fixed outer viewport:\n\n```jsx\n<Frame font-size={px(20)} padding={em(0.75)} border-radius={em(0.4)}>\n  <Circle width={em(5)} fill={blue} stroke={none} />\n</Frame>\n```\n\nFor repeated elements, use ordinary components and array helpers. Put layout\nprops on the component's outer element so its parent can allocate it:\n\n```jsx\nconst Card = ({ label, color, ...props }) => (\n  <TextFrame padding={em(0.75)} border-color={color} {...props}>\n    <Text color={color}>{label}</Text>\n  </TextFrame>\n)\nreturn (\n  <TextBox width={px(440)} font-size={px(20)} padding={em(0.75)}>\n    <HStack gap={em(0.75)}>\n      <Card label=\"Input\" color={blue} grow={1} />\n      <Card label=\"Output\" color={red} grow={1} />\n    </HStack>\n  </TextBox>\n)\n```\n\nKeep nested JSX and compound math operands on separate, indented lines. `range`,\n`linspace`, `zip`, and array `.map()` are useful for repeated geometry. `linspace`\nincludes the endpoint by default; pass `false` as its fourth argument for periodic samples.\nUse `setSeed` when a generative figure should be repeatable.\n\nUse `Latex` for display math and `Tex` inside `Text` for inline formulas. In a\nJavaScript string expression, use `String.raw` for TeX backslashes, for example\n``<Tex>{String.raw`\\frac{a}{b}`}</Tex>``, without surrounding `$` delimiters.\n\n## Design philosophy\n\nGum code should express the structure of a figure and let the layout system do\nthe measuring and positioning. Strive for the simplest, most elegant composition\nthat preserves the visual intent and is easy to reuse. Hard-coded dimensions and\npositions are a last resort, not the starting point.\n\n- Use layout classes whenever feasible. Compose `HStack`, `VStack`, `TextCol`,\n  `Box`, and `Frame` for rows, columns, spacing, and decoration. Use higher-level\n  elements such as `Slide`, `TextFigure`, and `Plot` for the structures they\n  already understand. Read their documented examples before inventing a layout.\n- Express relationships instead of coordinates. Let content determine natural\n  sizes; use `grow`, `gap`, alignment, and fill sizing to distribute available\n  space. For a note at the bottom of a panel, put flexible content above it in a\n  column rather than assigning the note a y coordinate. Let titles and captions\n  be measured instead of subtracting guessed heights from a canvas.\n- Establish the outer design size and base typography where needed, then use\n  `em` for internal spacing and type scales. Use fractions and aspect ratios for\n  meaningful proportional relationships. Replacing pixel coordinates with `em`\n  coordinates alone does not make a layout compositional.\n- Reuse design decisions. Extract repeated structures into small components,\n  share palette and typography choices, and generate repeated content from data.\n  Forward layout props to a component's outer element so it remains useful in\n  different containers. Prefer a few clear abstractions over copied markup or\n  wrappers that add no useful behavior.\n- Reserve explicit coordinates and fixed sizes for genuine geometric or output\n  requirements, such as data positions, a physical page size, or a diagram whose\n  placement carries meaning. When layout classes cannot express the requirement,\n  keep the manual geometry local and derive related values from shared parameters.\n\nJudge the source as well as the rendered result. A polished picture with brittle\ncode is an unfinished example. Check that changes to text, content count, or\nviewport size are handled by the layout rather than requiring a new set of\nhand-tuned offsets.\n\n## Layout and styling essentials\n\n- Lengths accept `px(24)` / `\"24px\"` and `em(1.5)` / `\"1.5em\"`.\n  `\"50%\"` and `0.5` use the property's established fraction\n  reference. `width={100}` is not 100 pixels. Quoted JSX attributes work directly,\n  including `font-size=\"24px\"` and `padding=\"1em\"`. Zero, including `\"0\"`, needs no\n  reference. Nonzero unitless strings and boolean padding are not supported.\n- Font weights accept numbers or names: `font-weight=\"bold\"`, `{bold}`, and\n  `{700}` are equivalent. `\"light\"` is 300; `\"regular\"` and `\"normal\"` are 400.\n- For a standalone figure, set a design height and base `font-size` on its outer\n  element; `aspect` can supply the width. Viewers scale the completed SVG for\n  display, including text and strokes. Use ems for descendant typography,\n  padding, gaps, and details. Content-sized figures may omit outer dimensions.\n- Boxes, frames, stacks, `TextBox`, `TextFrame`, and `TextCol` are content-sized\n  by default. Use `width=\"fill\"` or `height=\"fill\"` only to occupy an offer;\n  `width={1}` requires an established parent width. Fill is not a length unit.\n  Omit dimensions for content sizing; there is no content-sizing keyword.\n- `align=\"fill\"` allocates automatic child dimensions while respecting explicit\n  sizes and limits; `align=\"stretch\"` imposes the allocation even on sized children.\n  Use `align-self` on a direct child to override its parent's alignment. A child's\n  own `width=\"fill\"` still fills the offer.\n- Whole standalone formulas shrink automatically when needed; inline formulas\n  and nested atoms keep their normal scale. `fit={false}` disables this behavior.\n  Put `fit` directly on a fixed composition to measure naturally and\n  shrink the complete drawing when needed. It hugs the scaled result; ordinary\n  text still reflows unless fitting is requested. `fit=\"contain\"` also enlarges;\n  `fit=\"cover\"` fills and crops. No fitting wrapper is needed. Authored dimensions\n  describe the natural drawing; host offers and maxima bound the fitted result.\n- A `Box` contains one element. Wrap siblings in `HStack`, `VStack`, or `Group`.\n  Use `padding`, `border-width`, `border-color`, `border-radius`, and `background` for\n  its decoration. `fill` and `stroke` instead inherit to child shapes. `Text`\n  uses `color`, not `fill`. Use `justify` for text inside its allocated box.\n  Padding tuples are `[horizontal, vertical]` or `[top, bottom, left, right]`;\n  use named sides when that is clearer.\n- Stack `gap` separates items, `align` controls the cross axis, and `justify`\n  controls the main axis. Set `grow`, `shrink`, and optional `basis` on direct\n  children for flex allocation. Main-axis fractions use the stack length after\n  gaps: two half-width children tile an established row. Unsized children with\n  equal `grow` weights share the remaining budget from zero bases; use\n  `basis=\"auto\"` for content-based growth. Flex props do not pass through wrappers.\n  `HStack wrap` makes multiple rows; give growing cards a `basis` or `min-width`\n  to control row breaks.\n- Every element accepts `aspect` as preferred allocated width divided by height.\n  One established dimension derives the other; naturally sized content grows\n  its allocation to the ratio. Two exact dimensions and conflicting limits take\n  precedence. Aspect does not scale fonts or drawings; use `fit` for that.\n  Stacks do not infer a composite aspect from their children.\n- `Grid columns={3}` shares equal column widths across rows, dividing an offered\n  width or using the widest natural cell. A track array such as\n  `columns={[em(6), \"auto\", em(12)]}` uses explicit and content-sized widths.\n  `column-gap` and `row-gap` override `gap`; rows hug their tallest wrapped cell.\n  Alignment defaults to horizontal fill and vertical start; `align=\"fill\"`\n  also fills automatic cell heights. `TextGrid` converts strings/numbers and\n  defaults to em-based gaps. Use `<Box />` for an intentional blank cell.\n  Numeric tracks are fractions, not weights. Cell percentage heights cannot\n  size content-based rows; use absolute lengths or fill/stretch instead.\n- `Group` is a finite positioning canvas, not a content-hugging box. Establish\n  both axes with dimensions, finite offers, or one dimension plus aspect. Its\n  children use `pos={[x, y]}` or `pos={{x, y}}` and `anchor`, with top-left origin and y pointing down.\n  With `pos`, the default anchor is `\"center\"`; use `anchor=\"start\"` for top-left\n  placement. Without `pos`, children default to a start anchor at the local origin.\n  In `Graph`, `Plot`, and `Network`, bare numeric positions are data coordinates,\n  with y pointing up by default. Unit strings and `px`/`em` positions are local\n  lengths; widths and font sizes also use layout units. Give positioned shapes\n  explicit sizes: each receives an offer for the whole canvas.\n- Projected Graph marks, annotations, and parametric `f(t)` samples accept named\n  numeric records such as `{theta, r}` or `{x, y, z}`. Projection callbacks map\n  records to records or null; Graph needs final `x` and `y` plus explicit limits.\n  GeoMap children use `{lon, lat}` in degrees; `[longitude, latitude]` and `{x, y}`\n  remain aliases. Keep one complete naming scheme per geographic record. Local\n  tagged lengths still use Cartesian pairs. Use two explicit Fill boundary\n  arrays for named coordinates; scalar baselines and Field vectors are Cartesian.\n- Scoped props such as `title-font-size`, `xaxis-label-color`, and `head-open`\n  configure parts created by their owner. Use only the scopes in that owner's\n  reference. Function-valued sampling props such as `SymLine fy` are consumed\n  during construction; callbacks are not arbitrary mutable layout state.\n\nUse shared palette constants such as `blue`, `red`, `green`, `gray`, and `none`,\nor semantic theme paints such as `\"theme:accent\"`. Themes do not paint backgrounds;\nset `background` when needed. Text retains its font size during ordinary layout,\nso wrapping, usable width, and space for labels matter. Keep padding for ink\noverhang; the outer SVG clips at its viewport.\n\nConsult each component's reference for its layout controls: for example, `Box`\nuses padding for spacing around its content, while `Plot` also has a `margin`.\nUse `HStack` and `VStack` for rows and columns, `Grid` for shared columns across\nrows, and `Group` for positioned geometry.\n\n## References\n\nRead the relevant pages when choosing components or resolving a layout question;\nthere is no need to load the entire catalog. Each reference includes its\nrunnable JSX example.\n\n- [Guides](references/guides.md): the language, units, sizing, styles, helpers,\n  fonts, math setup, and host rendering APIs.\n- [Elements by category](references/elements.md): layout, geometry, plotting,\n  maps, networks, text, math, and special elements, including `PngImage`.\n- [Gallery](references/gallery.md): complete figures and focused examples,\n  grouped by category. Start from a close example when it fits the request.\n\nUseful starting points:\n\n- Layout: [Units](references/guides/units.md), [Sizing](references/guides/sizing.md),\n  [Positioning](references/guides/positioning.md), [Fitting](references/guides/fitting.md),\n  [Stacks](references/guides/stack.md),\n  [Box](references/elements/layout.md#Box), [Grid](references/elements/layout.md#Grid), and\n  [Group](references/elements/layout.md#Group).\n- Plots: [Plot](references/elements/plotting.md#Plot), [Graph](references/elements/plotting.md#Graph),\n  [SymLine](references/elements/plotting.md#SymLine), and [BarPlot](references/elements/plotting.md#BarPlot).\n  Plot axes use linear scales. `bounds=\"frame\"` sizes and aligns the data area;\n  leave space for the labels and titles outside it.\n  [Projections](references/guides/projections.md) covers polar Graph callbacks\n  and geographic marks. Supply explicit output limits and sampled paths.\n- Maps: [Making maps](references/guides/maps.md) walks through sources, styles,\n  views, and annotations. [GeoMap](references/elements/maps.md#GeoMap) documents the\n  element and its helpers. Start with `world_countries()` or `us_states()`;\n  nest markers and labels inside GeoMap, or see\n  [map routes](references/gallery/maps.md#map_routes) for a sampled Arrow.\n  [Filtering and bounds](references/gallery/maps.md#filtered_region) combines source\n  `ids` selection with `bounds={[west, south, east, north]}`.\n- Diagrams: [Network](references/elements/networks.md#Network) connects named\n  [Node](references/elements/networks.md#Node) frames, or any element with an `id`, using\n  [Edge](references/elements/networks.md#Edge).\n  It does not automatically arrange nodes or avoid obstacles.\n  Use [Overlay](references/elements/layout.md#Overlay) for annotations around a measured base.\n- Text and math: [Text](references/elements/text.md#Text),\n  [TitleFrame](references/elements/text.md#TitleFrame), [math authoring](references/guides/math.md),\n  and [Shape Algebra](references/gallery/math.md#shape_algebra).\n- Complete compositions: [Transformer](references/gallery/networks.md#transformer),\n  [Pendulum Physics](references/gallery/geometry.md#pendulum_physics), and\n  [Two Columns](references/gallery/layout.md#two_column).\n- Host integration: [Rendering](references/guides/rendering.md),\n  [Fonts](references/guides/fonts.md), and [Custom elements](references/guides/custom_elements.md).\n\nFor features without a dedicated component, compose supported primitives or\nexplain the limitation.\n\n## CLI setup\n\nThe `gum` command evaluates JSX, lays out the result, and writes SVG, PNG, PDF,\nkitty graphics, a fragment tree, or JSON. **Prefer a local package installation\nwith npm and Node.js 24+**. The authoring plugin does not install an executable\nautomatically.\n\nUse this discovery order:\n\n1. Reuse an exact renderer invocation already established in this task.\n2. Look for `gum` on PATH (`command -v gum` in a POSIX shell or\n   `Get-Command gum` in PowerShell). If found, use it.\n3. Otherwise, run `npm prefix` to find the current project's root and check\n   `node_modules/.bin` for `gum` (`gum.cmd` on Windows). If found, use that path.\n\nUse the first available renderer invocation.\n\nStop discovery after these checks: do not search Codex directories, plugin\ncaches, old tasks, user profiles, package-manager caches, or the filesystem for\na hidden installation. Do not use `bunx` or `npx` to probe.\n\nIf no renderer is found, explain that rendering requires downloading and running\nGum 2.0.0. Follow the host's approval flow before installing or running downloaded\nsoftware. Ask the user for setup approval when it is not already authorized.\nHonor installation restrictions and the user's chosen scope. If setup is denied\nor blocked, provide JSX source and rendering instructions.\n\n## Local package installation\n\nCreate a dedicated directory under the task's writable tools or temporary\ndirectory and put a minimal `package.json` containing `{\"private\":true}` there.\nRun this command **from that directory**:\n\n```sh\nnpm install --save-exact --ignore-scripts @gum-jsx/cli@2.0.0\n```\n\nIf npm's default cache is not writable in a sandbox, set `npm_config_cache` to\na writable directory (such as a cache directory under the task's temporary\ndirectory) and retry the installation.\n\nThe bundled package has no runtime package dependencies and needs no install\nscripts. Keep the generated lockfile, including the registry integrity metadata.\nUse the pinned version; if it is unavailable or integrity verification fails,\nstop and report the error. Invoke\n`node /absolute/tools-dir/node_modules/@gum-jsx/cli/dist/npm/cli.js`.\nRetain the exact invocation for later renders. Run rendering commands from the caller's working directory so input\nfiles resolve there.\n\nBun 1.4.2+ works equally well: install with `bun add --exact --ignore-scripts @gum-jsx/cli@2.0.0`\nand use `bun` in place of `node` in the invocation above.\n\nThis installation needs no global install, PATH or shell-profile changes, or\nchanges to the user's project dependencies. Only install into the project when\nthe user requests integration.\n\nIf neither Node.js 24+ nor Bun 1.4.2+ is available and no existing Gum renderer\nwas found, provide JSX source and the npm installation and rendering instructions\nfor an environment with a supported runtime.\n\n## Project and library integration\n\nThe bundled npm CLI runs under Node.js 24+ with no runtime package dependencies.\n\n- **Project CLI:** install with `npm install --save-dev --save-exact --ignore-scripts @gum-jsx/cli@2.0.0`,\n  then use `./node_modules/.bin/gum` (or its Windows wrapper).\n- **Global CLI:** install with `npm install -g --ignore-scripts @gum-jsx/cli@2.0.0`, then use `gum`.\n- **Library integration:** source packages require Bun or a browser bundler.\n  Add the libraries the host code needs, for example\n  `npm install --save-exact --ignore-scripts @gum-jsx/core@2.0.0 @gum-jsx/math@2.0.0`.\n  See [Rendering](references/guides/rendering.md) for evaluation, layout, and export APIs, and\n  [Math export](references/guides/math_export.md) for fonts and standalone formulas.\n\nChoose project-local CLI installation when the user wants dependencies managed\nwith the project; use global installation when they ask for commands across\nprojects. Preserve any scope already chosen.\nIf installation is declined or commands cannot run, provide source and rendering\ninstructions without claiming to have rendered it.\n\n## Render with the CLI\n\nSave a draft `.jsx` file and render it with `gum`. The examples below assume\n`gum` is on PATH; substitute the established local invocation when needed.\nPass a JSX file, multiple JSX files, or one deck directory; omit the input or\nuse `-` to read stdin. Input and output paths are relative to the current directory.\n\n```sh\n# With your source saved in figure.jsx:\ngum figure.jsx -o figure.svg\ngum figure.jsx -o figure.png --ratio 2\ngum figure.jsx -o figure.pdf\ngum figure.jsx -f tree --stats\ngum figure.jsx -f json -o figure.json\ngum --help\n```\n\n### Options\n\n| Option | Meaning |\n|---|---|\n| `[files...]` | JSX files or one deck directory; omit or use `-` for stdin |\n| `-f, --format <format>` | Image output: `kitty`, `svg`, `png`, `pdf`; layout inspection: `tree` or `json` |\n| `-o, --output <file>` | Write to a file instead of stdout |\n| `-W, --width <pixels>` | Exact viewport width in pixels |\n| `-H, --height <pixels>` | Exact viewport height in pixels |\n| `-r, --ratio <number>` | Positive PNG/kitty sampling ratio; default `1` |\n| `--png-encoding <preset>` | Lossless PNG/kitty encoding: `fast` (default) or `standard` |\n| `--select <x,y,width,height>` | Inspect a PNG/kitty region in source pixels; combine with `--ratio` to magnify |\n| `-b, --background <color>` | Paint the viewport background |\n| `-t, --theme <theme>` | `light` or `dark`; override the source root theme |\n| `--title <text>` | SVG or PDF document title |\n| `--id-prefix <name>` | SVG definition prefix; default `gum` |\n| `--precision <digits\\|full>` | Output decimal places, 0–100 or `full`; default `10` |\n| `--text-mode <mode>` | SVG text and math as `path` (default) or `live` text |\n| `--plugin <module>` | Load element/helper exports from a package or file; repeatable, requires Bun |\n| `--stats` | Machine-readable layout counters on stderr |\n| `-V, --version` | Print the CLI version |\n| `-h, --help` | Show help |\n\n#### Inspect a region with `--select`\n\nUse `--select` to examine fine details and alignment without shrinking the whole\nfigure to fit the viewer. Supply `x,y,width,height` in source pixels, with the\norigin at the viewport's top-left. The CLI lays out the full figure, then crops\nbefore rasterization; selecting a region does not reflow its contents.\n\n```sh\ngum figure.jsx --select 100,50,200,100 --ratio 3 -o detail.png\n```\n\nThis produces a 600 × 300 PNG of the 200 × 100 region starting at `(100, 50)`.\n`--ratio` increases sampling resolution, preserving sharp vector edges rather\nthan enlarging an existing bitmap. Use `-f kitty` instead of `-o detail.png` to\nview the crop in a compatible terminal.\n\nSelection works only with PNG and kitty. Width and height must be positive;\nfractional coordinates and regions extending outside the viewport are allowed.\nOutside areas are transparent unless `--background` supplies a paint. Compare\nmagnified crops with the full image to check both detail and composition.\n\n#### Inspect layout with `-f tree` and `-f json`\n\nThese formats expose the fragments produced by layout:\n\n- **`tree`** gives an indented view of fragment names, measured sizes, child\n  offsets and transforms, ink and content bounds, overflow, guides, and clipping.\n  Use it to trace unexpected spacing, alignment, or content extending beyond a box.\n  `--precision full` preserves full numeric precision in this report.\n- **`json`** serializes the fragment data, including drawing commands and nested\n  child placements, for structured inspection or further processing. JSON retains\n  full numeric precision regardless of `--precision`.\n\n```sh\ngum figure.jsx -f tree --precision full\ngum figure.jsx -f json -o fragments.json\n```\n\nBoth formats describe the result after layout. To inspect the source element\ntree before layout, use the host APIs in the\n[rendering guide](references/guides/rendering.md). Combine fragment inspection\nwith temporary `debug` props and a rendered image to connect numeric bounds to\nvisible geometry. `--stats` adds layout counters on stderr without mixing them\ninto the tree or JSON output.\n\n### Output, sizing, and backgrounds\n\nAn explicit format wins; otherwise the output extension selects SVG, PNG, or\nPDF. For a file or stdin, stdout defaults to kitty graphics even when piped or\nredirected. Choose `-f svg` for SVG text on stdout or `-f pdf` for binary PDF.\nKitty display requires a compatible terminal. Directories and multiple files\nrequire PDF output.\n\nWith neither `-W` nor `-H`, JSX gets a 640 × 480 offer; content can hug or exceed\nit, and authored dimensions still win. Viewport overrides are independent: an\nunspecified axis uses source dimensions or hugs content. `-W 320` reflows a\ndocument without fixing its height; it does not uniformly scale fonts or strokes.\nUse `fit` on the composition for uniform scaling. SVG/tree/JSON allow zero-sized\naxes; PNG/PDF/kitty require positive dimensions.\n\n`--ratio` changes raster resolution without changing layout.\n\n`--precision` controls SVG, PDF, and tree numbers without changing layout.\nPNG and kitty use full geometry precision. Both PNG encoding presets preserve\nthe same decoded pixels; they differ in compression policy.\n\nKitty defaults to a dark theme; other formats default to light. A source root\n`<Svg theme=\"light\">` or `<Svg theme=\"dark\">` overrides that default, and\n`--theme` overrides the root selection. Explicit paints and nested themes still\napply. Themes leave backgrounds transparent; `--background` paints behind\nexplicit source backgrounds. See [Themes](references/guides/themes.md).\nFor a fully opaque white PNG, use `--background '#FFFFFF'`: a white root Box\ncan leave transparency along the last pixel row or column when fractional\ndimensions round up to whole pixels.\n\n### Rendering behavior\n\nCore, math, and map bindings are included by default; `GeoMap`,\n`world_countries()`, and `us_states()` need no extra flags. The CLI wraps a bare\nelement in `Svg`; the core evaluator itself does not add this wrapper.\nErrors go to stderr and exit with status 1. `--stats` writes layout counters\nindependently of the rendered output.\n\nPNG and kitty render fragments directly through `@gum-jsx/png`'s WebAssembly\nrenderer. Text and math always use glyph outlines, including when\n`--text-mode live` selects live SVG text. No native addon or host font\nregistration is needed. Emoji without outlines cannot be rasterized; export\nSVG for a browser with suitable fonts.\n\nPDF uses `@gum-jsx/pdf` to write vector pages at 96 pixels per inch with the\nsame viewport, themes, and backgrounds. Text and math are outlines rather than\nselectable text; debug overlays are omitted. `--ratio` and `--id-prefix` do not\naffect PDF output.\n\nWatch mode is not implemented. Only run trusted JSX; evaluation executes JavaScript.\n\nInspect a rendered PNG when image viewing is available. Use `-f tree` or `-f json`\nto inspect allocations and overflow alongside temporary `debug` overlays. If\nvisual inspection is unavailable, report the checks actually performed.\n\n## Multipage PDFs and decks\n\nPass JSX files in argument order or one directory of slides to render a multipage PDF:\n\n```sh\ngum slides/ -o talk.pdf\ngum slides/ > talk.pdf\n```\n\nDirectories and multiple files default to PDF; other output formats are rejected.\nDirectories and stdin cannot be combined with other inputs. Each slide\nmust return a Gum element and becomes one page with its own viewport size. Long\ncontent is not automatically split into pages. Put multiple figures in a deck\ndirectory to combine them into a PDF. `-W` and `-H` apply to every page; `--stats`\nwrites one JSON line per page to stderr.\n\n### Deck manifest\n\nA deck directory can contain an `index.json`:\n\n```json\n{\n  \"title\": \"My talk\",\n  \"prelude\": \"prelude.jsx\",\n  \"slides\": [\"intro.jsx\", \"results.jsx\", \"conclusion.jsx\"]\n}\n```\n\nAll three fields are optional. Paths in the manifest are relative to its\ndirectory. `slides` sets the exact page order. When omitted, Gum uses that\ndirectory's `.jsx` files in natural filename order (`slide_2.jsx` before\n`slide_10.jsx`), excluding the named prelude. It does not recurse into\nsubdirectories. `title` supplies PDF document metadata; `--title` overrides it.\n\n### Shared preludes\n\nUse a prelude for shared colors, data, and reusable JSX components. It contains\nordinary declarations, without imports or exports, and does not need to return\na figure. For example, `prelude.jsx` can define:\n\n```jsx\nconst accent = '#167C73'\nfunction Card({ children, ...props }) {\n  return (\n    <Frame padding={em(0.75)} border-color={accent} {...props}>\n      <Text>{children}</Text>\n    </Frame>\n  )\n}\n```\n\nEach prelude is evaluated once per command, and its top-level bindings are shared\nby the slides that use it. Core and math helpers remain available. Each slide has\nits own local declarations and can be a bare JSX element or JavaScript ending\nwith an explicit `return`:\n\n```jsx\n<Slide title=\"Shared components\">\n  <HStack gap={em(1)}>\n    <Card grow={1}>First idea</Card>\n    <Card grow={1}>Second idea</Card>\n  </HStack>\n</Slide>\n```\n\nManifest and prelude handling applies to directory input. Explicit files or stdin\nuse the standard core, math, and map bindings without loading neighboring `index.json`\nfiles. A slide rendered as an individual file must be self-contained. Pass the\ndeck directory to use its prelude.\n\nThe `gum-jsx-docs/decks/gum` sample deck demonstrates a shared page layout,\nreusable panels, and a five-page manifest.\n\n## Generation Workflow\n\nWork in a short loop: write a draft, render it with the CLI, and revise the\nsource. Start with the main structure and content, then refine spacing,\ntypography, colors, and fine details once the composition works.\n\n1. **Draft.** Save an editable `.jsx` file. Use a relevant example as a starting\n   point and choose dimensions suited to the intended output.\n2. **Render.** Run `gum figure.jsx -o figure.png` using the established CLI\n   invocation. Open the rendered image and assess the whole composition:\n   hierarchy, legibility, spacing, alignment, clipping, and overlapping labels\n   or connectors. A successful command alone does not establish visual quality.\n3. **Revise.** Fix the layout or content causing the problem, render again, and\n   inspect the new result. Check the full composition after local adjustments.\n   Repeat until both the overall figure and its details work.\n\n### Inspection tools\n\nSometimes looking at the rendered PNG is not enough. You can use the following\ntools to inspect the layout and content.\n\n- **Debug overlays:** add temporary `debug` props to the relevant layout\n  elements to reveal allocated rectangles and content bounds. These help locate\n  unexpected spacing, overflow, and alignment problems.\n- **Magnified regions:** use `--select x,y,width,height` with `--ratio` to render\n  a specific region at higher resolution. Selection coordinates are in source\n  pixels, measured from the top-left. This is especially useful for fine details,\n  small text, line joins, and precise alignment; inspect the crop alongside the\n  full figure.\n- **Raw SVG:** render with `-f svg` or save a `.svg` file to inspect paths,\n  transforms, clipping, and paints when the image alone does not explain a\n  problem.\n- **Layout fragments:** use `-f tree` for a readable fragment tree or `-f json`\n  for raw fragment data, including measured sizes and child placements. Add\n  `--stats` when layout counters would help diagnose the behavior.\n- **Source elements:** when necessary, inspect the evaluated element tree before\n  layout and compare it with the resulting fragments. The\n  [rendering guide](references/guides/rendering.md) describes the host APIs for\n  accessing elements and fragments directly.\n"
}