@graphlearning/graphl-flow 0.5.0 → 0.7.0

package/README.md

@@ -47,6 +47,10 @@ 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.
+
 **`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).
 
@@ -68,13 +72,34 @@ column), not below it — an edge is routed in the gap between two siblings, nev
 `tag` draws a short pill before a row (`PK`, `FK`, `sp`); `tone` on a row tints it.
 
 **Code.** `code` takes the source as a (template-literal) string; its common indent is dropped.
-`lang` is `python | sql | scala | java | js | ts | shell | text` — one small highlighter with seven
+`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
 `switch` included); an `@Name` — a Java annotation, a Python decorator — draws as a keyword, and a
 number keeps its separators and suffix (`1_000_000L`). `show` keeps only those line ranges and folds
 each skipped run into `··· N lines`; `show` and `highlight` use the FILE's line numbers, and so do
 edges: `src.L17`.
-`terminal: true` draws a terminal — `$ ` lines are commands, `! ` lines errors, the rest output.
+`terminal: true` draws a terminal — `$ ` lines are commands, `! ` lines errors, the rest output;
+`show` folds a terminal too (0.6), so a long plan keeps its command, resource line and summary.
+Shell (0.7) has its own keywords (`if then fi for do done case`…), never the shared set: before it,
+`/var/www` drew `var` as a keyword. Config languages (0.7) — `ini` (a systemd unit: `[Section]`,
+`Key=`), `nginx` (a statement's first word is the directive) and `nft` (nftables) — have their own
+words too; in shell and config files `@` and `.` are parts of an address, not an annotation or a
+member access.
+
+**Consoles (0.7).** `console: true` draws a REAL transcript, row for row as an 80-column terminal
+showed it — no `$ ` convention, no `!` marks, nothing edited. A row that starts with a prompt is a
+command — `ana@web-01:~$` (Debian), `[ana@web-02 ~]$` (Red Hat), `ana@mac ~ %` (zsh) — drawn in the
+prompt's colours, red for root's `#`; every other row is output, in ink. A command row exactly `cols`
+(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.
+
+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>`.
+
+**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`.
 
 **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
@@ -129,15 +154,16 @@ writes `captures/<id>-<theme>.png`.
 
 | Type    | Fields |
 |---------|--------|
-| `item`  | `id`, `title`, `sub?`, `icon?`, `bullets?`, `stack?`, `chip?`, `tone?`, `span?` |
-| `group` | `id`, `children`, `title?`, `sub?`, `icon?`, `badge?`, `dir?: 'row' \| 'col' \| 'grid'`, `cols?`, `bare?`, `spread?`, `cell?: number \| true`, `tone?`, `span?` |
+| `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?`, `tone?`, `span?` |
+| `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`), `label?`, `dashed?`, `bidirectional?` |
+| `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)
@@ -155,15 +181,22 @@ Siblings in a row stretch to equal height.
 
 The theme (`dark` | `light`) picks the shade; repos cannot recolour.
 
-**Icons** share one key space across four sets; an unknown key draws no icon. Keys match
+**Icons** share one key space across five 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 |
 |---|---|---|
-| generic (lucide) | the tone accent | `activity admin bell box branch building card chart check clock cloud code cpu database disk factory file filter fingerprint folder globe key layers lock network package pie screen search server settings shield stream table terminal user users workflow zap` |
+| generic (lucide) | the tone accent | `activity admin bell box branch building card chart check clock cloud code archive cert cpu database disk factory file filter fingerprint firewall folder gauge globe key laptop layers lock log memory network package pie power screen search server settings shield stream table terminal timer user users workflow zap` |
 | Azure | its own colours | `adls aks analysisservices azuresql cosmos databricks datafactory defender devops eventhubs functions keyvault loganalytics monitor powerbi purview servicebus storage streamanalytics synapse vm` |
-| AWS | its own tile | `apigateway athena aurora cloudformation cloudwatch dms dynamodb ec2 eks elasticache emr eventbridge firehose glue iam kinesis kms lakeformation lambda msk mwaa rds redshift s3 sagemaker secretsmanager sns sqs stepfunctions vpc` |
-| brand | its own colour (ink if it would vanish) | `airflow docker duckdb flink git github githubactions grafana java junit jupyter kafka kubernetes maven mongodb pandas postgresql prometheus python snowflakedb spark terraform` |
+| 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.

package/dist/Code.d.ts

@@ -1,4 +1,5 @@
 import type { CSSProperties } from 'react';
+import { type Tok } from './highlight';
 import type { Code } from './types';
 type Row = {
     n: number;
@@ -8,11 +9,42 @@ type Row = {
 };
 /**
  * The lines a `code` node draws: every line, or only the `show` ranges with each skipped run
- * folded into one `··· N lines` row. Line numbers are the FILE's. Shared with the edge planner via
+ * folded into one `··· N lines` row — a terminal too (0.6: a long Terraform plan keeps its command,
+ * its resource line and its summary). Line numbers are the FILE's. Shared with the edge planner via
  * `codeLineIds`, so a line edges can address is a line that is drawn.
  */
 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 {
+    user: string;
+    host: string;
+    cwd: string;
+    sigil: string;
+    style: 'debian' | 'redhat' | 'zsh';
+    cmd: string;
+}
+export declare function parsePrompt(row: string): Prompt | null;
+type ConsoleRow = {
+    n: number;
+    kind: 'cmd';
+    prompt: Prompt;
+    toks: Tok[];
+} | {
+    n: number;
+    kind: 'cont';
+    toks: Tok[];
+} | {
+    n: number;
+    kind: 'out';
+    text: string;
+};
+/**
+ * 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.
+ */
+export declare function consoleRows(lines: string[], cols: number): Map<number, ConsoleRow>;
 export declare function CodeView({ node, style }: {
     node: Code;
     style?: CSSProperties;

package/dist/Tty.d.ts

@@ -0,0 +1,12 @@
+import type { CSSProperties } from 'react';
+import type { Tty } from './types';
+/** Rows addressable by edges and `focus` as `<tty>.R<n>`, 1-based like a code line. */
+export declare const ttyRowIds: (node: Tty) => string[];
+/**
+ * A full-screen program's screen: a terminal frame with a fixed grid of `cols` × the screen's rows.
+ * The size comes from the capture, never from the content, so two screenshots of `top` are the same box.
+ */
+export declare function TtyView({ node, style }: {
+    node: Tty;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/highlight.d.ts

@@ -3,7 +3,7 @@ export interface Tok {
     cls: TokClass;
     text: string;
 }
-export type Lang = 'python' | 'sql' | 'scala' | 'java' | 'js' | 'ts' | 'shell' | 'text';
+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. */
 export declare function dedent(src: string): string[];

package/dist/icons.d.ts

@@ -11,6 +11,11 @@ export declare const AZURE: Record<string, ComponentType<{
 export declare const AWS: Record<string, ComponentType<{
     size?: number | string;
 }>>;
+/** AWS RESOURCE icons: a single-colour glyph, no tile — the parts inside a service (a NAT gateway, a
+ *  task, a queue), drawn smaller-looking than a service on purpose, as AWS's own diagrams do. */
+export declare const AWS_RESOURCE: Record<string, ComponentType<{
+    size?: number | string;
+}>>;
 /** Open-source / product marks (simple-icons), in the brand's colour unless it would vanish. */
 export declare const BRAND: Record<string, {
     title: string;

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { Scene } from './Scene';
-export type { Scene as SceneModel, SceneNode, Group, Item, Table, TableRow, Code, Plot, PlotAxis, PlotSeries, Tree, TreeEntry, Note, Edge, Tone, ThemeKey } from './types';
+export type { Scene as SceneModel, SceneNode, Group, Item, Table, TableRow, Code, Plot, PlotAxis, PlotSeries, Tree, TreeEntry, Note, Tty, Edge, Tone, ThemeKey } from './types';