semiotic 3.7.3 → 3.7.4

package/CLAUDE.md

@@ -131,9 +131,9 @@ When the catalog doesn't fit, three HOCs take a layout function emitting scene p
 
 Layout signature differs by family:
 - **XY/Ordinal**: `layout: (ctx) => { nodes, overlays? }`. `ctx`: `data`, `scales` ({x,y} XY | {o,r,projection} ordinal), `dimensions` (plot rect — center-anchored for radial ordinal, top-left otherwise), `theme`, `resolveColor(key)`, `config`.
-- **Network**: `layout: (ctx) => { sceneNodes?, sceneEdges?, labels?, overlays? }`. `ctx`: `nodes`, `edges`, `dimensions`, `theme`, `resolveColor(key)`, `config`. Run external positioners (`d3-flextree`, `dagre`) then emit network scene primitives (circle/rect/arc nodes; line/bezier/curved edges).
+- **Network**: `layout: (ctx) => { sceneNodes?, sceneEdges?, labels?, overlays? }`. `ctx`: `nodes`, `edges`, `dimensions`, `theme`, `resolveColor(key)`, `config`, `selection` (shared-selection predicate `{ isActive, predicate(datum) }` from `LinkedCharts`, `null` when unwired — dim/highlight by it). Run external positioners (`d3-flextree`, `dagre`) then emit network scene primitives (circle/rect/arc nodes; line/bezier/curved edges).
 
-`semiotic/recipes` ships pure layout functions (`waffleLayout`, `calendarLayout`, `marimekkoLayout`, `bulletLayout`, `parallelCoordinatesLayout`, `flextreeLayout`, `dagreLayout`). BYO heavy deps (`d3-flextree`, `dagre`) in user code.
+`semiotic/recipes` ships pure layout functions (`waffleLayout`, `calendarLayout`, `marimekkoLayout`, `bulletLayout`, `parallelCoordinatesLayout`, `flextreeLayout`, `dagreLayout`, `lineageDagLayout`). BYO heavy deps (`d3-flextree`, `dagre`) in user code. `lineageDagLayout` renders a pre-positioned **layered lineage/DAG** (reads logical layer/row coords, no re-layout) with composite node glyphs (one hit-rect per node + icon/label/store-chip chrome in `overlays`), level-of-detail collapse (full→compact→icon→dot), distinct dashed back-edges, and host-driven reach-dimming (`layoutConfig.reachableIds`) + selection (`layoutConfig.selectedId` / shared `ctx.selection`).
 
 **Chrome (labels/axes/legends): the recipe owns it.** Recipes emit own chrome via `overlays` return field (ReactNode painted on top). Built-in axes via `showAxes` on the HOC work for layouts respecting the standard scale. Recipe convention: `showXxx` boolean toggles, `xxxFormat` callbacks. Shipped recipes' toggles: marimekko `showCategoryLabels`, bullet `showLabels`+`showTicks`, parallelCoordinates `showAxes`, flextree/dagre `showLabels`, waffle/calendar none.
 
@@ -143,13 +143,16 @@ Layout signature differs by family:
 - Coords are plot-relative (frame translates by `margin`). Read `ctx.dimensions.plot`. Radial ordinal: `plot.x = -width/2`, `plot.y = -height/2` (center-translated).
 - Layouts needing axis domains: pass `xExtent`/`yExtent` (XY) or `oExtent`/`rExtent` (ordinal) — those flow through scale construction *before* the layout runs.
 - Streaming layouts: ingest via ref (`push`/`pushMany`); layout re-runs on each ingest. Overlays update on data-change paths, NOT per-frame.
+- **On `NetworkCustomChart`, a `layoutConfig` change re-runs the layout (`buildScene`) WITHOUT re-ingesting the node/edge topology** — so drive interaction state, styling, or animation progress through `layoutConfig` for cheap per-frame updates; swapping `nodes`/`edges` (or the chart `width`/`height`) is the heavier path that re-ingests. Custom overlays are read straight from the store at render time (the frame's repaint re-reads them), so a recipe returning fresh JSX every layout call needs no per-frame `setState`.
 - Custom layouts own their colors — always prefer `ctx.resolveColor(key)` over hardcoded literals. `CategoryColorProvider` integration is XY-only; for cross-chart sync on network/ordinal customLayouts, pass matching `colorScheme` to each.
+- `NetworkCustomChart` accepts `selection` / `linkedHover` / `chartId` like the built-in network HOCs: hover/click emit into the shared selection store, and the resolved predicate arrives as `ctx.selection` so the layout can dim/highlight by a cross-chart selection. Host-owned per-render dimming (e.g. a graph-reachability set) is orthogonal — pass it through `layoutConfig` and read `ctx.config`.
 - Tooltips: emit datum keys matching user-visible accessor names. Avoid underscored synthetic keys (default tooltip filters those out).
 
 ## Coordinated Views
 
 **LinkedCharts** — `selections`. **CategoryColorProvider** — `colors`|`categories` + `colorScheme`.
-Chart props: `selection`, `linkedHover`, `linkedBrush`. Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`.
+Chart props: `selection`, `linkedHover`, `linkedBrush`. Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`. Works for `NetworkCustomChart` too — the resolved selection predicate is threaded into the custom layout as `ctx.selection`.
+**`useSelectionActions(name)`** — write-only access (`selectPoints`/`clear`) that does NOT subscribe to selection state, so a *container* can push a selection (e.g. from a hover handler) without re-rendering; only the leaf consumers reading the selection re-render. The provider-at-top / consumers-at-leaves pattern for interaction-heavy coordinated views.
 **Shared categories inside LinkedCharts → wrap in `CategoryColorProvider`.** Gives identical per-category colors AND makes LinkedCharts render one unified legend (suppressing individual chart legends). Without it, mismatched colors and duplicate legends.
 **Linked crosshair**: `linkedHover={{ name: "sync", mode: "x-position", xField: "time" }}`. Click locks crosshair (dashed white); click/Escape unlocks.
 **Linked series highlight** (series↔bar cross-highlight): `linkedHover={{ name: "sync", mode: "series" }}` auto-resolves the chart's series-identity field (colorBy/lineBy/areaBy/stackBy/groupBy) and keys the linked selection off it — no hand-wired `fields`. Add `seriesField: "region"` to override (align charts whose series live under different prop names). Modes are exclusive: `mode` is `"field"` (default) | `"x-position"` (crosshair) | `"series"`.

package/README.md

@@ -12,16 +12,15 @@ Simple charts in 5 lines. Network graphs, streaming data, and coordinated
 dashboards when you need them. Structured schemas and an MCP server so
 AI coding assistants generate correct chart code on the first try.
 
-## What's New in 3.7.3
+## What's New in 3.7.4
 
-3.7.3 is a hosted ChatGPT Apps patch release:
+3.7.4 is a network-chart and maintenance patch release:
 
-- `semiotic-mcp --http` can now serve the OpenAI Apps domain verification challenge from
-  `/.well-known/openai-apps-challenge` when `OPENAI_APPS_CHALLENGE_TOKEN` is configured.
-- The Cloud Run wrapper docs now include the exact Challenge Base URL, token environment variable,
-  and `curl` check for ChatGPT Apps verification.
-- MCP HTTP tests now cover the Apps challenge route while preserving the unauthenticated OAuth
-  discovery 404 behavior.
+- `semiotic/recipes` adds lineage DAG helpers for laying out data-flow and KStreams-style network
+  diagrams.
+- Network custom layouts now preserve selection metadata through streaming layout and render paths.
+- Docs add the KStreams DAG recipe and expand custom network chart guidance, alongside
+  dependency updates for Prettier, TypeScript ESLint, Rollup, and Sharp.
 
 ```jsx
 import { LineChart } from "semiotic/xy"

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.7.3",
+  "version": "3.7.4",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {

package/dist/components/LinkedCharts.d.ts

@@ -1,8 +1,8 @@
 import * as React from "react";
 import type { ResolutionMode } from "./store/SelectionStore";
 type LegendInteractionMode = "highlight" | "isolate" | "none";
-export { useSelection, useLinkedHover, useBrushSelection, useFilteredData } from "./store/useSelection";
-export type { UseSelectionOptions, UseSelectionResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./store/useSelection";
+export { useSelection, useSelectionActions, useLinkedHover, useBrushSelection, useFilteredData } from "./store/useSelection";
+export type { UseSelectionOptions, UseSelectionResult, UseSelectionActionsResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./store/useSelection";
 export { useChartObserver } from "./store/useObservation";
 export type { UseChartObserverOptions, UseChartObserverResult } from "./store/useObservation";
 /** Hook: returns true when a parent LinkedCharts is handling the legend. */

package/dist/components/charts/custom/NetworkCustomChart.d.ts

@@ -29,7 +29,7 @@ export interface NetworkCustomChartProps<TNode extends Datum = Datum, TEdge exte
      * `legendGroups` array yourself and pass it through `frameProps.legend`.
      */
     /** Additional StreamNetworkFrame props for advanced customization. */
-    frameProps?: Partial<Omit<StreamNetworkFrameProps, "nodes" | "edges" | "chartType" | "size" | "customNetworkLayout" | "layoutConfig">>;
+    frameProps?: Partial<Omit<StreamNetworkFrameProps, "nodes" | "edges" | "chartType" | "size" | "customNetworkLayout" | "layoutConfig" | "layoutSelection">>;
 }
 /**
  * NetworkCustomChart — escape hatch for bespoke network geometry.

package/dist/components/recipes/lineageDag.d.ts

@@ -0,0 +1,129 @@
+import type { ReactNode } from "react";
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Level of detail for a node glyph.
+ * - `full`    container + icon + type label + truncated name + store-slot chips
+ * - `compact` container + icon + truncated name
+ * - `icon`    container + icon only
+ * - `dot`     a single ~5px circle (minimap density)
+ */
+export type LineageLod = "full" | "compact" | "icon" | "dot";
+export interface LineageStoreSlot {
+    storeName: string;
+    slotIndex: number;
+}
+export interface LineageDagConfig {
+    /** Number of layers (x domain). Computed from node `x` extents when omitted. */
+    layerCount?: number;
+    /** Largest layer's row count (y domain). Computed from the data when omitted. */
+    maxLayerSize?: number;
+    /** Target full-glyph width / height in px. Shrunk to fit the plot. @default 172 / 54 */
+    nodeWidth?: number;
+    nodeHeight?: number;
+    /** Minimum gap reserved between glyphs when fitting. @default 26 / 18 */
+    minGapX?: number;
+    minGapY?: number;
+    /** Force a level of detail; `"auto"` derives it from the fitted glyph size. @default "auto" */
+    lod?: LineageLod | "auto";
+    /**
+     * Caller-supplied "reachable" set. When present, nodes/edges **outside**
+     * it dim to `dimOpacity`. This is the controlled-dimming channel: the host
+     * computes the set (e.g. downstream BFS of the hovered node) and re-renders.
+     * Independent of, and composes with, `NetworkLayoutContext.selection`.
+     */
+    reachableIds?: Iterable<string> | null;
+    /** Currently-selected node id — drawn with the selection ring. Host-owned. */
+    selectedId?: string | null;
+    /** Opacity for dimmed (out-of-reach / unselected) marks. @default 0.14 */
+    dimOpacity?: number;
+    /** Logical layer index (0 = leftmost). @default "x" */
+    layerAccessor?: string;
+    /** Logical row offset within the layer (centered on 0). @default "y" */
+    rowAccessor?: string;
+    /** Node partition → fill family. @default "partition" */
+    partitionAccessor?: string;
+    /** Node semantic → icon. @default "semantic" */
+    semanticAccessor?: string;
+    /** Human label. @default "label" */
+    labelAccessor?: string;
+    /** Store list — `string[]` or `{storeName,slotIndex}[]`. @default "stores" */
+    storesAccessor?: string;
+    /** Edge "closes a cycle" flag. @default "isBackEdge" */
+    backEdgeAccessor?: string;
+    /** Edge type, drives edge color. @default "edgeType" */
+    edgeTypeAccessor?: string;
+    /** Fill per partition. Overridable; recipe ships dark-theme-friendly defaults. */
+    partitionColors?: Partial<Record<string, string>>;
+    /** Edge stroke per edgeType, plus `back` for back-edges. */
+    edgeColors?: Partial<Record<string, string>>;
+    /** Selection-ring stroke. @default var(--semiotic-focus, #ffcc33) */
+    accentColor?: string;
+    /** Container border stroke. @default var(--semiotic-border, #555) */
+    borderColor?: string;
+    /** Draw the store-slot chips in `full` LOD. @default true */
+    showStoreChips?: boolean;
+    /** Chip fill. @default var(--semiotic-info, #6a8caf) */
+    storeChipColor?: string;
+    /** Base edge opacity (non-dimmed). @default 0.5 */
+    edgeOpacity?: number;
+    /** Forward-edge stroke width in px. @default 1.25 */
+    edgeWidth?: number;
+    /** Back-edge stroke width in px. @default `edgeWidth`, else 1.5 */
+    backEdgeWidth?: number;
+    /**
+     * Render the per-node icon. Receives the resolved semantic/partition, the
+     * pixel size to draw within, and a color hint. Return any SVG node. When
+     * omitted a labelled fallback chip is drawn. The demo passes a KStreams
+     * icon set here — keeping the recipe domain-agnostic.
+     */
+    renderIcon?: (info: {
+        semantic: string;
+        partition: string;
+        size: number;
+        color: string;
+        node: Datum;
+    }) => ReactNode;
+    /** Small type label shown above the name in `full` LOD. @default the semantic. */
+    typeLabel?: (info: {
+        semantic: string;
+        partition: string;
+        node: Datum;
+    }) => string;
+}
+/**
+ * `lineageDagLayout` — a reusable layout recipe for **pre-positioned layered
+ * lineage / DAG graphs** with rich, composite node glyphs. Used here for the
+ * Kafka Streams topology viewer, but domain-agnostic: it reads logical
+ * `x` (layer) / `y` (row) coordinates the caller already computed (e.g. from a
+ * `dagLayoutFromGraph` pipeline) and maps them into the plot — it never runs a
+ * force sim or re-lays-out, so output is deterministic.
+ *
+ * **Composite glyphs as one hit-testable unit.** Each node emits exactly one
+ * `rect` (or `circle` in `dot` LOD) scene node — that single mark owns the
+ * canvas hit area and carries the node datum/id. All glyph chrome (semantic
+ * icon, type label, truncated name, per-store chips, selection ring) is drawn
+ * in the returned `overlays` layer, which is `pointer-events: none`, so it
+ * decorates without ever intercepting a hover. Hover/click therefore always
+ * resolve to the underlying node as a unit — see §5.2(a) of the spec.
+ *
+ * **Controlled dimming + selection, from outside.** `config.reachableIds`
+ * (host-computed set) dims everything outside it; `config.selectedId` draws
+ * the selection ring; both are owned by the host, never by the frame. The
+ * shared `NetworkLayoutContext.selection` predicate (from `LinkedCharts`)
+ * composes on top — a node dims if excluded by *either* cue.
+ *
+ * @example
+ * ```tsx
+ * import { NetworkCustomChart } from "semiotic/network"
+ * import { lineageDagLayout } from "semiotic/recipes"
+ *
+ * <NetworkCustomChart
+ *   nodes={dagNodes}   // each: { id, x: layer, y: row, partition, semantic, stores, label }
+ *   edges={dagEdges}   // each: { source, target, edgeType, isBackEdge }
+ *   layout={lineageDagLayout}
+ *   layoutConfig={{ layerCount, maxLayerSize, reachableIds, selectedId }}
+ * />
+ * ```
+ */
+export declare const lineageDagLayout: NetworkCustomLayout<LineageDagConfig>;

package/dist/components/semiotic-recipes.d.ts

@@ -13,6 +13,8 @@ export { flextreeLayout } from "./recipes/flextree";
 export type { FlextreeConfig } from "./recipes/flextree";
 export { dagreLayout } from "./recipes/dagre";
 export type { DagreConfig } from "./recipes/dagre";
+export { lineageDagLayout } from "./recipes/lineageDag";
+export type { LineageDagConfig, LineageLod, LineageStoreSlot } from "./recipes/lineageDag";
 export { marimekkoLayout } from "./recipes/marimekko";
 export type { MarimekkoConfig } from "./recipes/marimekko";
 export { bulletLayout } from "./recipes/bullet";

package/dist/components/semiotic.d.ts

@@ -32,8 +32,8 @@ export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartTyp
 export type { StreamNetworkFrameProps, StreamNetworkFrameHandle, NetworkChartType, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, ThresholdAlertConfig } from "./stream/networkTypes";
 export type { SelectionConfig, LinkedHoverProp, LinkedBrushProp } from "./charts/shared/types";
 export type { LinkedChartsProps } from "./LinkedCharts";
-export { useSelection, useLinkedHover, useBrushSelection, useFilteredData } from "./LinkedCharts";
-export type { UseSelectionOptions, UseSelectionResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./LinkedCharts";
+export { useSelection, useSelectionActions, useLinkedHover, useBrushSelection, useFilteredData } from "./LinkedCharts";
+export type { UseSelectionOptions, UseSelectionResult, UseSelectionActionsResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./LinkedCharts";
 export { useChartObserver } from "./LinkedCharts";
 export type { UseChartObserverOptions, UseChartObserverResult } from "./LinkedCharts";
 export type { ChartObservation, OnObservationCallback } from "./store/ObservationStore";

package/dist/components/store/useSelection.d.ts

@@ -23,6 +23,28 @@ export interface UseSelectionResult {
     clientId: string;
 }
 export declare function useSelection(options: UseSelectionOptions): UseSelectionResult;
+export interface UseSelectionActionsResult {
+    /** Set a point selection (categorical values) under this client's clause. */
+    selectPoints: (fieldValues: Record<string, unknown[]>) => void;
+    /** Clear this client's clause. */
+    clear: () => void;
+    /** This client's ID. */
+    clientId: string;
+}
+/**
+ * Write-only access to a named selection that **does not subscribe** to the
+ * selection state — selecting only the stable `setClause`/`clearClause`
+ * actions, so the calling component never re-renders when the selection
+ * changes.
+ *
+ * Use this when a *container* needs to push a selection (e.g. from a hover
+ * handler) but only the leaf consumers (the charts reading the selection)
+ * should re-render. Pairs with `LinkedCharts` for the
+ * provider-at-top / consumers-at-leaves pattern: the writer stays out of the
+ * re-render path, avoiding per-interaction reconciliation + allocation in the
+ * container subtree. For read + write, use `useSelection`.
+ */
+export declare function useSelectionActions(name: string, clientId?: string): UseSelectionActionsResult;
 export interface UseLinkedHoverOptions {
     /** Selection name. Defaults to "hover" */
     name?: string;

package/dist/components/stream/networkCustomLayout.d.ts

@@ -1,6 +1,33 @@
 import type { ReactNode } from "react";
 import type { NetworkSceneNode, NetworkSceneEdge, NetworkLabel, RealtimeNode, RealtimeEdge } from "./networkTypes";
 import type { ThemeSemanticColors } from "./types";
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * The shared selection state, projected into the custom-layout context.
+ *
+ * When the chart participates in a `LinkedCharts` / selection store (via
+ * `NetworkCustomChart`'s `selection` / `linkedHover` props), the frame
+ * threads the resolved predicate here so a custom layout can dim or
+ * highlight marks by the *shared* selection — the same predicate the
+ * built-in HOCs apply to `nodeStyle`. Mirrors `SelectionHookResult`.
+ *
+ * `predicate` receives the **raw** datum (the user object you passed in
+ * `nodes`, i.e. `node.data ?? node`), matching the `d.data || d`
+ * convention the built-in network charts use. `isActive` is `false`
+ * when no selection clause is present — when `false`, treat every mark
+ * as selected (draw at full weight).
+ *
+ * This is orthogonal to `config` (your `layoutConfig` blob): use `config`
+ * for host-owned highlight sets you compute yourself (e.g. a graph
+ * reachability set), and `selection` for cross-chart coordination that
+ * rides the shared store.
+ */
+export interface NetworkLayoutSelection {
+    /** Whether a selection clause is currently active. */
+    isActive: boolean;
+    /** Returns `true` when the raw datum matches the active selection. */
+    predicate: (datum: Datum) => boolean;
+}
 /**
  * customLayout escape hatch for `StreamNetworkFrame`.
  *
@@ -54,6 +81,14 @@ export interface NetworkLayoutContext<C extends object = Record<string, unknown>
     resolveColor: (key: string) => string;
     /** User-supplied config blob threaded through `layoutConfig`. */
     config: C;
+    /**
+     * Shared-selection projection. Present when the chart is wired to a
+     * `LinkedCharts` / selection store; `null` otherwise. Use
+     * `selection.isActive` + `selection.predicate(node.data ?? node)` to
+     * dim/highlight marks by the cross-chart selection. See
+     * {@link NetworkLayoutSelection}.
+     */
+    selection?: NetworkLayoutSelection | null;
 }
 export interface NetworkLayoutResult {
     /** Positioned scene primitives. Circles, rects, or arcs. */

package/dist/components/stream/networkTypes.d.ts

@@ -453,6 +453,11 @@ export interface NetworkPipelineConfig {
     customNetworkLayout?: import("./networkCustomLayout").NetworkCustomLayout;
     /** User-supplied config blob threaded through to NetworkLayoutContext.config. */
     layoutConfig?: object;
+    /** Resolved shared-selection predicate, surfaced to a custom layout as
+     *  `NetworkLayoutContext.selection`. Render-only — deliberately kept out of
+     *  the layout/ingest-affecting signature so a selection change re-runs
+     *  `buildScene` (re-emitting dimmed marks) without a re-ingest or re-layout. */
+    layoutSelection?: import("./networkCustomLayout").NetworkLayoutSelection | null;
 }
 export interface StreamNetworkFrameProps<T = Datum> {
     chartType: NetworkChartType;
@@ -566,6 +571,10 @@ export interface StreamNetworkFrameProps<T = Datum> {
     customNetworkLayout?: import("./networkCustomLayout").NetworkCustomLayout;
     /** User-supplied config blob threaded through to NetworkLayoutContext.config. */
     layoutConfig?: object;
+    /** Resolved shared-selection predicate, surfaced to a custom layout as
+     *  `NetworkLayoutContext.selection`. Set by `NetworkCustomChart` from its
+     *  `selection` / `linkedHover` wiring; render-only (no re-ingest on change). */
+    layoutSelection?: import("./networkCustomLayout").NetworkLayoutSelection | null;
 }
 export interface StreamNetworkFrameHandle {
     push(edge: EdgePush): void;