@graphlearning/graphl-flow 0.8.0 → 0.10.0

package/README.md

@@ -3,8 +3,9 @@
 Declarative architecture diagrams for React. Describe **groups**, **items** and **edges**; the
 browser lays them out and the engine draws the arrows. Scenes never contain x/y.
 
-> 0.1.0 — seven node types (`group`, `item`, `table`, `code`, `plot`, `tree`, `note`), edges,
+> 0.9.0 — eight node types (`group`, `item`, `table`, `code`, `plot`, `tree`, `note`, `tty`), edges,
 > two themes, fit-to-frame for 4K recording. Content repos pin a version and upgrade deliberately.
+> Maintainer rules: `CLAUDE.md`; their history: `docs/DECISIONS.md`; workspace: `../CLAUDE.md`.
 
 ## Install
 
@@ -35,6 +36,62 @@ const scene: SceneModel = {
 </div>
 ```
 
+## Model
+
+| Type    | Fields |
+|---------|--------|
+| `item`  | `id`, `title`, `muted?`, `sub?`, `icon?`, `bullets?`, `stack?`, `chip?`, `tone?`, `span?` |
+| `group` | `id`, `children`, `title?`, `sub?`, `icon?`, `badge?`, `dir?: 'row' \| 'col' \| 'grid'`, `cols?`, `bare?`, `dashed?`, `muted?`, `spread?`, `cell?: number \| true`, `tone?`, `span?` |
+| `table` | `id`, `rows`, `columns?`, `title?`, `tone?`, `span?` — a row is `[cells…]` or `{ cells, id?, tag?, tone? }` |
+| `code`  | `id`, `code`, `lang?`, `filename?`, `show?: [from, to][]`, `highlight?: number[]`, `terminal?`, `output?`, `console?`, `cols?`, `wrap?`, `tone?`, `span?` — `wrap` soft-wraps a long editor line under its own text |
+| `tty`   | `id`, `screen: string[]`, `title?`, `cols?`, `inverse?`, `bold?` (`[row, from, to][]`) — a full-screen program's grid |
+| `plot`  | `id`, `x`, `y` (axes: `min`, `max`, `step?`, `label?`, or `labels` for categories), `series`, `title?`, `axes?`, `grid?`, `compact?` — with `w`, the plot is that wide and its drawing area takes what the gutters leave |
+| `tree`  | `id`, `entries` (`name`, `children?`, `folder?`, `state?: active \| new \| muted`, `note?`, `icon?`), `title?`, `compact?` (13px rows: a sidebar beside a code pane) |
+| `note`  | `id`, `text`, `tone?` — a dashed callout of wrapping prose |
+| any node | `minW?`/`minH?` (floors), `maxW?`/`maxH?` (caps), `w?`/`h?` (exact), `fill?`, `span?`, `tone?`; groups also `bare?` |
+| `Edge`  | `from`, `to` (a node id; a table row `table.row`; a code line `code.L12`; a tree entry `tree.src/a.py`; a tty row `top.R7`), `label?`, `dashed?`, `bidirectional?` |
+| `Scene` | `nodes`, `edges?`, `title?`, `sub?`, `dir?`, `pulse?`, `padding?` (the fit's margin per side, 0–0.2, default 0.04) |
+
+**Layout.** A group lays its children out as `dir: 'col'` (default), `'row'` (one column per child)
+or `'grid'` (`cols`, default 2). `span: 'all'` gives a child a full row — a rail under columns.
+Siblings in a row stretch to equal height.
+
+**Tone** sets what a box means and is inherited by everything inside it:
+
+| tone | hue | | tone | hue |
+|---|---|---|---|---|
+| `neutral` | grey | | `serve` | violet |
+| `source` | slate | | `consume` | red |
+| `ingest` | blue | | `infra` | orange |
+| `store` | green | | | |
+
+The theme (`dark` | `light`) picks the shade; repos cannot recolour.
+
+## Group and item looks
+
+**`dashed: true`** draws a group's frame dashed — a boundary that is a PLACE, not a thing (an AWS
+Region or Availability Zone, as AWS's own diagrams draw them). Only the line style changes, so
+dashing a group never moves anything.
+
+**`spread: true`** on a group spaces its children evenly over its full height when the group is
+stretched taller than them (a short column beside a tall one).
+
+**`muted: true`** draws an item greyed, or a group as a plain grey outline — a part the system does
+not have yet, at its full size and place (paint only, so muting moves nothing; a muted group does not
+dim its children). An architecture that grows course by course draws its
+whole final shape from the start.
+
+**`chip: true`** draws an item as a small framed pill — a thing counted, not described (`Task 1`,
+`Local disk`); chips fill their grid cell, so a row of them lines up.
+
+A nested group is a plain card, unless it names its OWN `tone` — then it is a coloured column again
+(the Spark study's four columns, and its green worker nodes inside the orange Worker column).
+
+**`stack: true`** puts an item's icon on top with the text centred under it — a card in a column of
+peers (the Business Consumers column).
+
+## Edges
+
 **Edges** connect any two nodes by id — items or groups, at any depth — as right-angle arrows.
 An edge leaves across the larger gap between the two columns (or rows) it connects, so it stays in
 the gaps rather than cutting through a neighbour; ends that face each other connect straight. A face with several edges gives each its
@@ -47,14 +104,11 @@ That period is the recorder's loop (`PULSE_S` in `@graphlearning/shell`'s record
 video has no jump at the join. `pulse: false` on a scene turns it off. `npm run capture` freezes the
 animation at t = 0, so stills are reproducible.
 
-**`dashed: true`** draws a group's frame dashed — a boundary that is a PLACE, not a thing (an AWS
-Region or Availability Zone, as AWS's own diagrams draw them). Only the line style changes, so
-dashing a group never moves anything.
+An edge to an id the scene doesn't have logs a console error naming it.
 
-**`spread: true`** on a group spaces its children evenly over its full height when the group is
-stretched taller than them (a short column beside a tall one).
+## Tables and memory
 
-**Tables and memory.** A `table` is a DB schema, a stack frame, a heap object, an array or a hash
+A `table` is a DB schema, a stack frame, a heap object, an array or a hash
 map's buckets. Every row is addressable as `<table id>.<first cell>` (or `.<id>` when you set one), so
 a pointer is just an edge: `{ from: 'main.nums', to: 'list' }`. There is no memory node type —
 stack and heap are groups of tables:
@@ -71,6 +125,8 @@ A row connects through its left or right end only. Lay a pointer's target BESIDE
 column), not below it — an edge is routed in the gap between two siblings, never around a third.
 `tag` draws a short pill before a row (`PK`, `FK`, `sp`); `tone` on a row tints it.
 
+## Code, consoles and screens
+
 **Code.** `code` takes the source as a (template-literal) string; its common indent is dropped.
 `lang` is `python | sql | scala | java | js | ts | shell | hcl | ini | nginx | nft | text` — one small highlighter with seven
 token colours per theme, sharing one keyword set (Java's primitive types, `record`, `sealed` and
@@ -103,37 +159,49 @@ A full-screen program is a **`tty`**: `screen` (its rows), `cols?` (80), `invers
 as `[row, from, to)` — a fixed grid, padded to `cols`, so two captures of `top` are the same box.
 Its rows are `tty.R<n>`.
 
-**Console frames (0.7).** Two columns, both FIXED: the console (or a `tty` in its slot, same `w`/`h`) |
-the PICTURE of what it just showed — a `bare` group of the rest of 16:9. No edges between them; ring
-the console line with `focus`. See `dev/fixtures/studies/console-frame.ts`.
+## Charts
 
-**IDE frames.** Three columns: `tree` | (editor `code` over terminal `code`, in a `bare` group) |
-a SIDE PANE — a `bare` group with a fixed width `w`. The IDE alone is narrower than 16:9; the side
-pane fills the frame and holds whatever the moment needs (a `note`, a `compact` plot, a small memory
-diagram) or nothing. See `dev/fixtures/studies/ide-frame.ts`.
+A `plot`'s x/y values are DATA in the axes' own units — sample curves in the scene
+file. A series is `line | scatter | area | bar | segment`. Every plot's drawing area is the same
+fixed size, so charts line up across a deck. Series take the next colour of a fixed ramp
+(blue, orange, violet, green) unless given a `tone`. A `segment` is a dashed construction or threshold
+line — muted grey unless toned, solid with `dashed: false`, a vector with `arrow: true`. Bars label
+themselves in a legend; other series label their last point.
+
+## Frames
+
+Recipes for whole video frames; each has a study fixture.
+
+**One grid (0.10).** Every IDE, notebook and console frame is 1344×756 (16:9) with
+`padding: 0.01`, every column a fixed `w` with a full-height floor, so they all land on ONE fit
+(about 42px code in the 4K frame) and `check` asserts it (`SAME_FIT`).
 
-**Notebook frames.** The same three columns with a notebook in the middle: `tree` | a group (the
-notebook: `title: 'explore.ipynb'`, `icon: 'jupyter'`) of CELLS | the fixed side pane. A cell is a
+**IDE frames.** `tree` (`compact`, 175) | editor `code` (`wrap`) over terminal `code`, in a `bare`
+group (715: 72 columns) | a SIDE PANE (434): a group titled with the moment's mental model, `spread`,
+holding a diagram (a memory diagram, a plot with `w`, a result table). Two variants of one height: a
+tall editor over a short terminal, or the reverse. Without the explorer the side pane takes its
+column (619), so the frame still fills 16:9. See `dev/fixtures/studies/ide-frame.ts`.
+
+**Notebook frames.** The same columns with a notebook in the middle: `tree` | a group (the
+notebook: `title: 'explore.ipynb'`, `icon: 'jupyter'`) of CELLS | the side pane. A cell is a
 `group` with `cell: n`, the execution count drawn as `[n]` in a gutter (`cell: true` draws `[ ]`, not
 run yet). Its first child is the input `code` (drawn without a tab bar, stretched to the cell),
 followed by its outputs: `{ type: 'code', output: true }` for printed text (`! ` lines are errors), a
 `table` for a DataFrame, or a `plot`. See `dev/fixtures/studies/notebook-frame.ts`.
 
+**Console frames.** Two columns: the console (760: 80 columns, 29 rows; or a `tty` in its slot, same
+`w`/`h`) | the PICTURE of what it just showed — a `bare`, `spread` group of the rest (574). No edges
+between them; ring the console line with `focus`. See `dev/fixtures/studies/console-frame.ts`.
+
 `minW`/`minH` are FLOORS and `maxW`/`maxH` CAPS, in the scene's own pixels; `w`/`h` set both. Give
 every frame of a video the same floors and a fixed side pane, and they get the same zoom: no pane
 moves between cuts, whatever the side pane holds. Prose wraps to the pane; tables and code do not,
-so keep them narrow. A plot never scales — use `compact: true` (a 420×280 area) in a side pane.
+so keep them narrow. A plot never scales — use `compact: true` (a 420×280 area) in a side pane, or
+`compact` with a `w` to fit a narrower column.
 Don't draw an edge between the IDE's columns: an arrow widens the gap it crosses and moves every
 pane. Point at code with `highlight` and the narration; edges INSIDE the side pane are fine.
 
-**Charts.** A `plot`'s x/y values are DATA in the axes' own units — sample curves in the scene
-file. A series is `line | scatter | area | bar | segment`. Every plot's drawing area is the same
-fixed size, so charts line up across a deck. Series take the next colour of a fixed ramp
-(blue, orange, violet, green) unless given a `tone`. A `segment` is a dashed construction or threshold
-line — muted grey unless toned, solid with `dashed: false`, a vector with `arrow: true`. Bars label
-themselves in a legend; other series label their last point.
-
-An edge to an id the scene doesn't have logs a console error naming it.
+## Rendering: legibility, focus, fit, recording
 
 **Legibility on video.** The fit scales the whole scene to the frame, so what decides how big text
 looks is how WIDE the scene is for the text it holds — not the font size. Item text wraps at a
@@ -146,7 +214,9 @@ diagram hits that, split the slide or trim bullets — a denser scene can only g
 line included — with a ring and a glow in its own tone. It is drawn with box-shadow, so it moves
 nothing: every section of a course can focus a different node on the same scene without a jump.
 
-**Fit.** `Scene` fills its parent and scales the scene to fit, centred, with a 4% margin. The scale
+**Fit.** `Scene` fills its parent and scales the scene to fit, centred, with a 4% margin per side —
+or the scene's own `padding` (a fraction, 0–0.2): a fixed frame template already shaped to the pane
+sets `padding: 0.01` to fill the recording. The scale
 depends only on the parent's size and the scene's natural size, so the same scene in the same frame
 always lands on the same pixels. The view is locked (no zoom/pan); page scroll passes through and text
 stays selectable. The root carries `data-fit="ready"` once fonts have loaded, edges are routed and the fit is applied —
@@ -156,38 +226,9 @@ wait on it before recording.
 `@graphlearning/shell`'s recorders use. In this repo: `npm run capture -- <fixtureId> --theme dark`
 writes `captures/<id>-<theme>.png`.
 
-## Model
-
-| Type    | Fields |
-|---------|--------|
-| `item`  | `id`, `title`, `muted?`, `sub?`, `icon?`, `bullets?`, `stack?`, `chip?`, `tone?`, `span?` |
-| `group` | `id`, `children`, `title?`, `sub?`, `icon?`, `badge?`, `dir?: 'row' \| 'col' \| 'grid'`, `cols?`, `bare?`, `dashed?`, `muted?`, `spread?`, `cell?: number \| true`, `tone?`, `span?` |
-| `table` | `id`, `rows`, `columns?`, `title?`, `tone?`, `span?` — a row is `[cells…]` or `{ cells, id?, tag?, tone? }` |
-| `code`  | `id`, `code`, `lang?`, `filename?`, `show?: [from, to][]`, `highlight?: number[]`, `terminal?`, `output?`, `console?`, `cols?`, `tone?`, `span?` |
-| `tty`   | `id`, `screen: string[]`, `title?`, `cols?`, `inverse?`, `bold?` (`[row, from, to][]`) — a full-screen program's grid |
-| `plot`  | `id`, `x`, `y` (axes: `min`, `max`, `step?`, `label?`, or `labels` for categories), `series`, `title?`, `axes?`, `grid?` |
-| `tree`  | `id`, `entries` (`name`, `children?`, `folder?`, `state?: active \| new \| muted`, `note?`, `icon?`), `title?` |
-| `note`  | `id`, `text`, `tone?` — a dashed callout of wrapping prose |
-| any node | `minW?`/`minH?` (floors), `maxW?`/`maxH?` (caps), `w?`/`h?` (exact), `fill?`, `span?`, `tone?`; groups also `bare?` |
-| `Edge`  | `from`, `to` (a node id; a table row `table.row`; a code line `code.L12`; a tree entry `tree.src/a.py`; a tty row `top.R7`), `label?`, `dashed?`, `bidirectional?` |
-| `Scene` | `nodes`, `edges?`, `title?`, `sub?`, `dir?`, `pulse?` |
+## Icons
 
-**Layout.** A group lays its children out as `dir: 'col'` (default), `'row'` (one column per child)
-or `'grid'` (`cols`, default 2). `span: 'all'` gives a child a full row — a rail under columns.
-Siblings in a row stretch to equal height.
-
-**Tone** sets what a box means and is inherited by everything inside it:
-
-| tone | hue | | tone | hue |
-|---|---|---|---|---|
-| `neutral` | grey | | `serve` | violet |
-| `source` | slate | | `consume` | red |
-| `ingest` | blue | | `infra` | orange |
-| `store` | green | | | |
-
-The theme (`dark` | `light`) picks the shade; repos cannot recolour.
-
-**Icons** share one key space across five sets; an unknown key draws no icon. Keys match
+**Icons** share one key space across six sets; an unknown key draws no icon. Keys match
 `@graphlearning/flow`'s where both have the icon, so scenes port without renaming.
 
 | set | drawn in | keys |
@@ -197,18 +238,5 @@ The theme (`dark` | `light`) picks the shade; repos cannot recolour.
 | AWS service | its own tile | `acm apigateway athena aurora backup budgets cloudformation cloudfront cloudtrail cloudwatch costexplorer dms dynamodb ec2 ecr ecs eks elasticache elb emr eventbridge fargate firehose glue iam identitycenter kinesis kms lakeformation lambda msk mwaa organizations rds redshift route53 s3 sagemaker secretsmanager sns sqs ssm stepfunctions vpc waf xray` |
 | AWS group mark | its own tile (for a group's `icon`) | `account autoscaling privatesubnet publicsubnet region` |
 | AWS resource | a single-colour glyph, no tile | `alb bucket container ecsservice ecstask hostedzone iamrole igw message natgateway permissions queue router sts topic vpcendpoint` |
-| brand | its own colour (ink if it would vanish) | `airflow almalinux apple arch bash debian docker duckdb fedora flink git github githubactions grafana java junit jupyter kafka kubernetes letsencrypt linux macos maven mongodb nginx pandas postgresql prometheus python redhat rocky snowflakedb spark terraform ubuntu zsh` |
-
-**`muted: true`** draws an item greyed, or a group as a plain grey outline — a part the system does
-not have yet, at its full size and place (paint only, so muting moves nothing; a muted group does not
-dim its children). An architecture that grows course by course draws its
-whole final shape from the start.
-
-**`chip: true`** draws an item as a small framed pill — a thing counted, not described (`Task 1`,
-`Local disk`); chips fill their grid cell, so a row of them lines up.
-
-A nested group is a plain card, unless it names its OWN `tone` — then it is a coloured column again
-(the Spark study's four columns, and its green worker nodes inside the orange Worker column).
-
-**`stack: true`** puts an item's icon on top with the text centred under it — a card in a column of
-peers (the Business Consumers column).
+| Google Cloud | its own colours (Google Cloud Icons, Apache-2.0) | `bigquery cloudbuild cloudkms cloudlogging cloudmonitoring composer dataflow dataplex dataproc dlp gcpbilling gcpiam gcpproject gcs pubsub secretmanager` |
+| brand | its own colour (ink if it would vanish) | `airflow almalinux apple arch bash debian docker duckdb fedora flink git github gcp githubactions grafana java junit jupyter kafka kubernetes letsencrypt linux looker macos maven mongodb nginx pandas postgresql prometheus python redhat rocky snowflakedb spark terraform ubuntu zsh` |

package/dist/fit.d.ts

@@ -17,4 +17,4 @@ export declare const MAX_SCALE = 4;
  * That is what makes recordings reproducible: two frames whose scenes have the same natural box get
  * the same scale and put every panel at the same pixels.
  */
-export declare function fitTransform(pane: Size, content: Size): Fit;
+export declare function fitTransform(pane: Size, content: Size, padding?: number): Fit;

package/dist/gcp-icons.d.ts

@@ -0,0 +1,5 @@
+/** Google Cloud product icons in their own colours: 24×24 SVG bodies, keyed as scenes name them. */
+export declare const GCP: Record<string, {
+    title: string;
+    body: string;
+}>;

package/dist/icons.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentType, ReactElement } from 'react';
 import { type LucideIcon } from 'lucide-react';
+import { GCP } from './gcp-icons';
 /** Generic glyphs, drawn in the node's tone accent. */
 export declare const LUCIDE: Record<string, LucideIcon>;
 /** Azure service tiles, in their own colours. The package ships no viewBox; 0 0 18 18 fits all. */
@@ -22,9 +23,9 @@ export declare const BRAND: Record<string, {
     hex: string;
     path: string;
 }>;
+export { GCP };
 /** `size` is a CSS length — in em, so an icon scales WITH its text and the ratio stays designed. */
 type Draw = (size: string, surface: string, ink: string) => ReactElement;
 /** A brand mark under this contrast against the surface draws in ink (Kafka's black on dark). */
 export declare const BRAND_MIN_CONTRAST = 2.2;
 export declare const ICONS: Record<string, Draw>;
-export {};