@graphlearning/graphl-flow 0.7.0 → 0.9.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?`, `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?` |
+
+**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
@@ -93,10 +149,29 @@ prompt's colours, red for root's `#`; every other row is output, in ink. A comma
 (default 80) wide wrapped, so the rows after it continue the command, and the command is highlighted
 whole across the wrap. `show`, `highlight` and `focus` (`con.L12`) work as on code.
 
+**psql (0.8).** A console also recognises psql's default prompt: `syndica=>` (a new statement),
+`syndica-*>` / `syndica(>` / `syndica'>` (a continued line; `(` and `'` inside brackets or a string),
+`*` a transaction open, `!` a failed one, and `#` a superuser (red, like root). A statement's
+continuation rows are one command, highlighted as SQL across its lines; `\d`, `\q`… draw as psql's
+own commands. Capture with `psql -n` (no readline) in an 80-column pty.
+
 A full-screen program is a **`tty`**: `screen` (its rows), `cols?` (80), `inverse?` and `bold?` runs
 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>`.
 
+## 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.
+
+## Frames
+
+Recipes for whole video frames; each has a study fixture.
+
 **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`.
@@ -120,14 +195,7 @@ so keep them narrow. A plot never scales — use `compact: true` (a 420×280 are
 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
@@ -150,38 +218,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
+## Icons
 
-| 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?` |
-
-**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 |
@@ -191,18 +230,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/Code.d.ts

@@ -15,15 +15,27 @@ type Row = {
  */
 export declare function codeRows(node: Code): Row[];
 export declare const codeLineIds: (node: Code) => string[];
-/** A shell prompt, as the three shells the course meets draw it. `sigil` is `$`/`%`, or `#` for root. */
-export interface Prompt {
+/**
+ * A prompt: a shell's, as the three shells the course meets draw it (`sigil` is `$`/`%`, or `#` for
+ * root), or psql's (0.8) default `%/%R%x%# ` — the database, the input state (`=` a new statement,
+ * `-` a continued one, `(` `'` `"` inside brackets or quotes), the transaction state (`*` open, `!`
+ * failed, `?` unknown) and `>`, or `#` for a superuser.
+ */
+export type Prompt = {
+    style: 'debian' | 'redhat' | 'zsh';
     user: string;
     host: string;
     cwd: string;
     sigil: string;
-    style: 'debian' | 'redhat' | 'zsh';
     cmd: string;
-}
+} | {
+    style: 'psql';
+    db: string;
+    mode: string;
+    tx: string;
+    sigil: string;
+    cmd: string;
+};
 export declare function parsePrompt(row: string): Prompt | null;
 type ConsoleRow = {
     n: number;
@@ -41,8 +53,11 @@ type ConsoleRow = {
 };
 /**
  * Classify a transcript's rows. A prompt row is a command; a command row exactly `cols` wide wrapped,
- * so the rows after it continue the command until one is shorter. The command is tokenized WHOLE and
- * its tokens cut back into rows, so a string or a path that crosses the wrap keeps its colour.
+ * so the rows after it continue the command until one is shorter. psql (0.8) draws a prompt on every
+ * line of a statement, so a psql command also takes the continuation-prompt rows after it (`-`, `(`,
+ * `'`, `"`) as further LINES. The command is tokenized WHOLE — lines joined by `\n` — and its tokens
+ * cut back into rows, so a string crossing a wrap or a line keeps its colour. A shell command is
+ * `shell`, a psql one `sql`.
  */
 export declare function consoleRows(lines: string[], cols: number): Map<number, ConsoleRow>;
 export declare function CodeView({ node, style }: {

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/highlight.d.ts

@@ -5,5 +5,10 @@ export interface Tok {
 }
 export type Lang = 'python' | 'sql' | 'scala' | 'java' | 'js' | 'ts' | 'shell' | 'hcl' | 'ini' | 'nginx' | 'nft' | 'text';
 export declare function tokenize(src: string, lang: Lang): Tok[];
-/** Drop a leading/trailing blank line and the common indent, so scenes can use indented template literals. */
+/**
+ * Drop the template literal's first line break, trailing blank lines and the common indent, so scenes
+ * can use indented template literals. Only ONE leading blank line goes (0.8): a timeline pane's
+ * transcript can START with blank rows — padding that aligns it with the other session — and
+ * stripping them all shifted the whole pane up.
+ */
 export declare function dedent(src: string): 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 {};