@jmbarzee/force-graph 0.0.1

package/dist-lib/graph/axis.d.ts

@@ -0,0 +1,290 @@
+/** A named axis of node identity, e.g. the type axis or the source-file axis. */
+export type AxisId = string;
+/**
+ * One value on an axis. A stable interned string: two nodes on the same value
+ * must produce keys that are `===` equal, not merely equivalent.
+ */
+export type AxisValue = string;
+/** Where a node sits on every axis it has a value for. */
+export type AxisValues = Readonly<Record<AxisId, AxisValue>>;
+/**
+ * Fold anything into a stable value key.
+ *
+ * Composite selections are the trap this exists for. Passing an array or an
+ * object gives a deterministic string rather than a new object each call, so a
+ * `Set` of these deduplicates the way the caller expects.
+ */
+export declare function internValue(parts: string | readonly string[]): AxisValue;
+/** One button in a filter bar: a label, an optional glyph, and the values it toggles. */
+export interface FilterChip {
+    id: string;
+    label: string;
+    icon?: string;
+    /** A style value whose colour this chip wears, in the pane's theme; none means neutral. */
+    tint?: AxisValue;
+    /**
+     * Hover text, when the label alone is not enough to identify the chip.
+     *
+     * A chip for a path shows its last segment and needs the whole path here:
+     * two paths with the same last segment are otherwise indistinguishable.
+     * Omitted means "Show/Hide <label>", which is right for a chip whose label is
+     * already the whole identity.
+     */
+    tooltip?: string;
+    /** Toggled as a unit — "any on" turns the whole group off. */
+    values: readonly AxisValue[];
+}
+/**
+ * How an axis names itself and its values — the part of a descriptor a control
+ * surface needs, split out so the style axis (which is not a filter and has no
+ * descriptor) can supply one too and share the identity-mapping builder.
+ */
+export interface AxisNamer {
+    id: AxisId;
+    /** Human label for the axis itself, e.g. for a dropdown or a chip group. */
+    label: string;
+    labelFor(value: AxisValue): string;
+    /** One or two characters for a token. */
+    abbreviationFor(value: AxisValue): string;
+}
+/** What a filter change asks of the running simulation. */
+export interface ReheatPolicy {
+    /** Alpha to reheat to. */
+    alpha: number;
+    /** Seed newly-revealed nodes at their nearest visible ancestor first. */
+    seedRevealed: boolean;
+    /** Clear the initial-fit guard, so the camera refits to the new extent. */
+    refit: boolean;
+    /** Resume ticking. */
+    resume: boolean;
+}
+/**
+ * One filter axis, as a host declares it: its id, its label, and what an
+ * empty selection on it means. Everything else is policy with a default that
+ * follows from `emptyMeans`, because the two kinds of axis want opposite
+ * answers to each question:
+ *
+ *   - an **allow-list** (`emptyMeans: 'none'`): a node with no value is
+ *     hidden, a focus always expands the selection, a change reseeds the
+ *     revealed nodes at their ancestors, refits the camera and reheats to
+ *     0.5, and the initial selection is every value;
+ *   - a **narrowing** axis (`emptyMeans: 'all'`): a node with no value stays
+ *     visible, a focus expands only an already-active selection (adding the
+ *     first value would narrow everything to one thing — the opposite of
+ *     focus), a change reheats to 0.3 in place and keeps the user's pan and
+ *     zoom, and the initial selection is empty.
+ *
+ * **It does not carry the values.** Those are derived, not declared: the style
+ * axis's values come from the taxonomy, and an origin axis's from scanning the
+ * graph. Declaring them here too would be the same fact in two places with
+ * nothing enforcing agreement, free to drift apart unnoticed.
+ */
+export interface AxisDescriptor {
+    id: AxisId;
+    /** Human label for the axis itself, e.g. for a dropdown or a chip group. Default: the id. */
+    label?: string;
+    /**
+     * What an EMPTY selection on this axis means: `none` hides everything (the
+     * chips are an allow-list), `all` shows everything (the chips narrow).
+     */
+    emptyMeans: 'all' | 'none';
+    /** What happens to a node carrying NO value on this axis while a selection is active. */
+    absentMeans?: 'visible' | 'hidden';
+    /**
+     * How a focus widens this axis to reveal its target: `always` adds the
+     * target's value; `whenActive` adds it only while a selection is active
+     * (on a narrowing axis, adding the first value would narrow everything to
+     * that one value — the opposite of a reveal). Default: `always` on an
+     * allow-list, `whenActive` on a narrowing axis.
+     */
+    widens?: 'always' | 'whenActive';
+    /**
+     * Whether a change on this axis keeps the user's pan and zoom. Default: an
+     * allow-list refits the camera to the new extent (and seeds revealed nodes
+     * at their ancestors); a narrowing axis keeps the camera and reheats in
+     * place.
+     */
+    keepCamera?: boolean;
+    /**
+     * How this axis's available values group into chips. Not one chip per
+     * value: a chip may cover several values. Takes the available values
+     * rather than reading a declared list, because an axis's values are
+     * derived from the graph. Absent, one chip per value, labelled by
+     * `labelFor` and, on the style axis, wearing the value's icon and tint.
+     */
+    chipsFor?(values: readonly AxisValue[]): readonly FilterChip[];
+    /** A value's display name. Absent: the style's label on the style axis, else the value itself. */
+    labelFor?(value: AxisValue): string;
+    /** One or two characters for a token. Absent: the style's abbreviation on the style axis, else the first two characters of `labelFor`'s answer. */
+    abbreviationFor?(value: AxisValue): string;
+    /** A chip's hover text, when the label alone does not identify the value (a file's full path under its basename). Absent: none. */
+    tooltipFor?(value: AxisValue): string;
+    /** A value's glyph, drawn on its chip. Absent: the style's icon on the style axis, none elsewhere. */
+    iconFor?(value: AxisValue): string;
+    /**
+     * The values selected when the view first opens, given the values the
+     * graph presents on this axis. Absent: every value on an allow-list,
+     * none on a narrowing axis. `initialFilter` reads it; a host that passes the
+     * `defaultFilter` prop has chosen its own start, and this is not consulted.
+     */
+    initialSelection?(values: readonly AxisValue[]): readonly AxisValue[];
+    /**
+     * How the bar draws this axis's chips. `chip` (the default) is a tinted,
+     * glyph-led button that reads as a category; `tag` is a quieter, neutral
+     * label that reads as an origin — a file, a source, a place — and shows an
+     * "everything included" state when the selection is empty on an
+     * `emptyMeans: 'all'` axis.
+     */
+    presentation?: 'chip' | 'tag';
+}
+/** A filter axis with every policy filled in — what `Taxonomy.filterAxes` carries. */
+export interface ResolvedAxisDescriptor extends AxisNamer {
+    emptyMeans: 'all' | 'none';
+    absentMeans: 'visible' | 'hidden';
+    /** How a focus widens this axis to reveal its target. */
+    widens: 'always' | 'whenActive';
+    /** Whether a change on this axis keeps the user's pan and zoom (a narrowing axis does; an allow-list refits). */
+    keepCamera: boolean;
+    tooltipFor?(value: AxisValue): string;
+    /** A value's glyph, or '' for none. */
+    iconFor(value: AxisValue): string;
+    chipsFor(values: readonly AxisValue[]): readonly FilterChip[];
+    initialSelection(values: readonly AxisValue[]): readonly AxisValue[];
+    presentation: 'chip' | 'tag';
+}
+/** How the style axis names and adorns its values, for a descriptor's defaults. */
+export interface StyleNamer {
+    axis: AxisId;
+    labelFor(value: AxisValue): string;
+    abbreviationFor(value: AxisValue): string;
+    iconFor(value: AxisValue): string;
+}
+/**
+ * A declared axis with every default filled in. The policies follow from
+ * `emptyMeans`; the names follow from the style axis when this is it, and
+ * from the value itself otherwise.
+ */
+export declare function resolveDescriptor(d: AxisDescriptor, style: StyleNamer): ResolvedAxisDescriptor;
+/** Where a node sits on one axis, or undefined when it carries no value there. */
+export declare function valueOf(values: AxisValues, axis: AxisId): AxisValue | undefined;
+/** One bucket of a mapping: a named group of source values. */
+export interface MappingBucket {
+    id: string;
+    /** Display name — a tooltip, a column header. */
+    label: string;
+    /**
+     * One or two characters for a token. Required rather than derived: a control
+     * surface has no room for a name, and truncating one is a guess the host can
+     * answer better.
+     */
+    abbreviation: string;
+    values: readonly AxisValue[];
+}
+/**
+ * A function from an axis's values to an equal-or-smaller set.
+ *
+ * The point is to bound a control surface. Push/pull renders one draggable
+ * token per mapped pair, so an axis with fifty values has no usable control
+ * surface until something collapses it — and a mapping is that something. The
+ * existing example is three separate kinds folded into one filter chip.
+ */
+export interface AxisMapping {
+    id: string;
+    label: string;
+    axis: AxisId;
+    buckets: readonly MappingBucket[];
+    /** The bucket a value belongs to, or undefined if the mapping omits it. */
+    bucketFor(value: AxisValue | undefined): MappingBucket | undefined;
+}
+/** What `createAxisMapping` is given: the mapping's id, label, axis and buckets, before the buckets are checked for overlap. */
+export interface AxisMappingSpec {
+    id: string;
+    label: string;
+    axis: AxisId;
+    buckets: readonly MappingBucket[];
+}
+/**
+ * Build a mapping, refusing to build an incoherent one.
+ *
+ * **Buckets must not intersect.** A value in two buckets has no answer to "which
+ * token tunes this node", and the failure would otherwise surface as a layout
+ * that depends on bucket declaration order — the kind of bug that is found
+ * months later by someone reordering a list for readability. So it throws here,
+ * loudly, at construction, rather than resolving arbitrarily per lookup.
+ */
+export declare function createAxisMapping(spec: AxisMappingSpec): AxisMapping;
+/**
+ * The identity mapping for an axis — one bucket per value.
+ *
+ * Useful as the default for an axis that is already small enough to control
+ * directly, so a consumer never has to special-case "no mapping".
+ */
+export declare function identityMapping(axis: AxisNamer, values: readonly AxisValue[]): AxisMapping;
+/**
+ * True when every bucket is one value named after itself — the shape under
+ * which bucket ids ARE the axis's values, so a rule written over values applies
+ * to buckets unchanged. Structural, not a flag: a flag would be a second fact
+ * about the buckets with nothing holding it to the first.
+ */
+export declare function isIdentityMapping(mapping: AxisMapping): boolean;
+/**
+ * The distinct values a set of subjects carries on one axis, in first-encounter
+ * order. The domain of an axis is whatever the graph presents on it — the
+ * engine declares no value vocabulary of its own — so this is how a control
+ * surface or a filter learns what an axis can take.
+ */
+export declare function valuesOn(subjects: Iterable<{
+    values: AxisValues;
+}>, axis: AxisId): AxisValue[];
+/**
+ * How many entities carry each value on each of the given axes — the chip
+ * badges' numbers when a host does not supply its own reading. The copies of
+ * one entity (`copyKey`) count once; a subject with neither key nor id counts
+ * as itself. An axis no subject has a value on gets an empty map, never a
+ * missing one.
+ */
+export declare function countsOn(subjects: Iterable<{
+    values: AxisValues;
+    id?: string;
+    copyKey?: string;
+}>, axes: readonly AxisId[]): ReadonlyMap<AxisId, ReadonlyMap<AxisValue, number>>;
+/**
+ * Does this table declare `key` itself, rather than inheriting it?
+ *
+ * Every keyed lookup on an axis value must go through this. Values are
+ * host-supplied strings, so a plain `table[key]` read walks the prototype chain
+ * and a value named `constructor`, `toString` or `__proto__` resolves to an
+ * inherited member. That member is not `undefined`, which means every
+ * `?? default` and `!== undefined` guard downstream silently accepts it.
+ *
+ * Spelled with `Object.prototype.hasOwnProperty.call` rather than the tidier
+ * `Object.hasOwn` so it needs no lib bump, and called on the prototype rather
+ * than the table so a table that itself declares a key named `hasOwnProperty`
+ * cannot shadow the check.
+ */
+export declare function hasOwn(table: object, key: string): boolean;
+/**
+ * What a change on one axis asks of the simulation, from its two declared
+ * policies: an allow-list reheats harder; an axis that keeps the camera
+ * neither seeds revealed nodes at their ancestors nor refits.
+ */
+export declare function reheatOf(axis: Pick<ResolvedAxisDescriptor, 'emptyMeans' | 'keepCamera'>): ReheatPolicy;
+/** What a filter change asks of the running simulation, folded across axes. */
+export interface ReheatPlan extends ReheatPolicy {
+    /** The axes that actually changed — empty means "do nothing". */
+    changed: readonly AxisId[];
+}
+/**
+ * Fold the per-axis reheat policies of every axis that changed. Several axes
+ * can move at once (a view switch does exactly that), so the policies combine
+ * rather than the last one winning: the strongest reheat, and any axis that
+ * wants seeding, refitting or resuming gets it.
+ */
+export declare function foldReheatPolicy(changedAxes: readonly ResolvedAxisDescriptor[]): ReheatPlan;
+/**
+ * The structural meaning of an edge — the one fact about an edge the engine
+ * reads for itself (graduation, highlighting and spring resolution branch on
+ * it). It is a field of the edge, not an axis: every axis, on nodes and on
+ * edges, is the host's own.
+ */
+export type Relation = 'containment' | 'dependency';

package/dist-lib/graph/groups.d.ts

@@ -0,0 +1,31 @@
+import { Theme } from './scheme';
+/** The cycling glow palette per theme; a group with no `color` of its own takes the slot for its place in the list. */
+export declare const GROUP_PALETTE: Readonly<Record<Theme, readonly string[]>>;
+/** The glow strength of the group holding the hovered or selected node. */
+export declare const NODE_FOCUS_STRENGTH = 2.2;
+/** A group as the host asks for it: over the whole graph, visible or not. */
+export interface NodeGroup {
+    id: string;
+    nodeIds: ReadonlySet<string>;
+    /** Whether the host emphasises this group; the view glows it stronger. A host's legend inside the pane uses `groupsControl`'s `emphasize` instead and leaves this out. */
+    emphasized?: boolean;
+    /** The glow's colour, hex or rgb(); absent, the palette's slot for this group's place in the list. */
+    color?: string;
+}
+/** A group as drawn: the visible node ids it covers and its palette colour. */
+export interface ActiveGroup {
+    id: string;
+    color: string;
+    /** The glow's intensity: 1, or more for a group that is emphasised or holds the hovered or selected node. */
+    strength: number;
+    nodeIds: ReadonlySet<string>;
+}
+/**
+ * The groups as drawn: each restricted to the visible set
+ * (filter-as-source-of-truth), the empty dropped, each coloured by its place
+ * in the host's list in the theme's palette — so hiding one group recolours
+ * none of the others.
+ */
+export declare function activeGroupsOf(groups: readonly NodeGroup[], visibleIds: ReadonlySet<string>, theme?: Theme, emphasized?: string | null): ActiveGroup[];
+/** The active groups with any that holds one of the given nodes glowing at `NODE_FOCUS_STRENGTH`; the same array when none does. */
+export declare function boostGroupsForNodes(groups: ActiveGroup[], focusIds: Array<string | null>): ActiveGroup[];

package/dist-lib/graph/layout.d.ts

@@ -0,0 +1,104 @@
+import { AxisId } from './axis';
+import { ScalarSpan } from './scalar';
+import { SpringPhysics } from './shapes';
+import { Taxonomy } from './taxonomy';
+declare const LAYOUT_STATE: unique symbol;
+/**
+ * The layout as the user tuned it: the forces (which axis push and pull key
+ * on and the per-bucket overrides; the two layout axes with theirs; the
+ * multipliers, exponents, gravities and dynamics) and the node scale. Opaque
+ * to a host: keep it, hand it back as `layout` or `defaultLayout`, and carry
+ * it to a store through `layoutToJSON` and `layoutFromJSON`. The view retunes
+ * it for the graph and taxonomy it faces — a tuning on an axis the graph no
+ * longer carries returns to the style axis — and reports the result.
+ */
+export interface LayoutState {
+    readonly [LAYOUT_STATE]: true;
+}
+/** One layout axis as plain data: a node axis with the bands the user changed, or a computed scalar with the span they dragged. */
+export type LayoutTuningJSON = {
+    axis: AxisId;
+    overrides?: Record<string, {
+        min: number;
+        max: number;
+    }>;
+} | {
+    scalar: string;
+    span?: ScalarSpan;
+};
+/**
+ * A layout as plain data, for a store, a URL or a host's own hand: what
+ * `layoutToJSON` writes and `layoutFromJSON` reads. Every part is optional
+ * and defaults to the taxonomy's, so a host that wants the view to open on a
+ * scalar writes `{ forces: { bandY: { scalar: 'credits' } } }` and nothing
+ * else.
+ */
+export interface LayoutJSON {
+    forces?: {
+        /** The axis push and pull key on, with the buckets the user changed: each bucket's charge and core radius, each edge type's spring. */
+        pair?: {
+            axis: AxisId;
+            push?: Record<string, {
+                charge: number;
+                coreRadius: number;
+            }>;
+            spring?: Record<string, SpringPhysics>;
+        };
+        /** The horizontal layout axis. */
+        bandX?: LayoutTuningJSON;
+        /** The vertical layout axis. */
+        bandY?: LayoutTuningJSON;
+        /** Scales every charge (repulsion). */
+        pushMultiplier?: number;
+        /** Scales every core radius (the softening of a charge at close range). */
+        coreRadiusMultiplier?: number;
+        /** The power of (distance² + softening) a charge falls off by; 1 is inverse-square. */
+        chargeExponent?: number;
+        /** Scales every spring (attraction). */
+        pullMultiplier?: number;
+        /** Scales every rest length. */
+        distanceMultiplier?: number;
+        /** The power of a spring's displacement; 1 is Hooke's law. */
+        linkExponent?: number;
+        /** The horizontal band gravity; 0 switches it off. */
+        gravityX?: number;
+        /** The vertical band gravity; 0 switches it off. */
+        gravityY?: number;
+        /** The power of the displacement outside a rest band; 1 is linear. */
+        gravityBandExp?: number;
+        /** Radial layout: the vertical axis's bands become rings about the origin. */
+        radial?: boolean;
+        /** The inward pull on a node by its downstream reach; 0 is off. */
+        gravityTopological?: number;
+        /** The power of the reach score; higher makes the biggest hubs pull hardest. */
+        gravityTopologicalExp?: number;
+        /** The pull toward the origin — the baseline when no band axis acts. */
+        gravityCenter?: number;
+        /** Whether the topological pull acts. */
+        topologicalEnabled?: boolean;
+        /** How fast the simulation cools per tick. */
+        alphaDecay?: number;
+        /** The temperature the simulation stops at. */
+        alphaMin?: number;
+        /** How much of a node's velocity survives a tick. */
+        velocityDecay?: number;
+    };
+    /** The node scale: the size knob, and how small and how large zoom may draw a node. */
+    nodeScale?: {
+        baseMul?: number;
+        minZoomMul?: number;
+        maxZoomMul?: number;
+    };
+}
+/** A layout as plain data — every tuning by its axis or scalar, every override by its bucket, every number — for a store or a URL. */
+export declare function layoutToJSON(layout: LayoutState): LayoutJSON;
+/**
+ * The layout `layoutToJSON` wrote — or a host's own partial one — over the
+ * taxonomy's defaults, or undefined when a part present is not its shape:
+ * stored data is not trusted to be, and a host falls back to the default
+ * rather than to a layout that means something else. A tuning on an axis
+ * other than the style axis is built without buckets and completed by the
+ * view when the graph arrives, its overrides kept where their values survive.
+ */
+export declare function layoutFromJSON(value: unknown, taxonomy: Taxonomy): LayoutState | undefined;
+export {};

package/dist-lib/graph/model.d.ts

@@ -0,0 +1,149 @@
+import { AxisValues, Relation } from './axis';
+/** A node of the host's graph: an opaque id, a name, its values on the host's axes, and an optional parent, copy key, ring, badges and payload. */
+export interface GraphNode {
+    /**
+     * Stable identity, owned by whoever produced the graph.
+     *
+     * **Opaque.** The engine compares ids and looks them up; it never parses one
+     * or reads structure out of it. A host is free to make them hierarchical, or
+     * not — the two behave identically here, and that is the property worth
+     * keeping: the moment anything splits an id on a separator, the id's format
+     * becomes part of this model's contract.
+     */
+    id: string;
+    /**
+     * Where this node sits on every axis the taxonomy declares. Features elect
+     * one axis each and read it from here; nothing composes across axes.
+     */
+    values: AxisValues;
+    name: string;
+    /**
+     * Metadata the host owns and the library does not interpret.
+     *
+     * Deliberately opaque: it is per-domain display detail — the things a tooltip
+     * shows — and the moment the library reads a key out of it by name, that key
+     * is part of the library's vocabulary again.
+     */
+    payload?: Readonly<Record<string, unknown>>;
+    /**
+     * The container this node sits in, when it has one. One string: containment
+     * is a tree, and an entity that sits in two containers is modelled as two
+     * nodes sharing a `copyKey`. The view derives the containment edge from
+     * this node to its container (`withContainmentEdges`) when the host does
+     * not list one, so a host writes the fact once; a host may still list
+     * containment edges of its own, between any two nodes.
+     */
+    parentId?: string;
+    /**
+     * A mark the host puts on a node that is set apart: a dashed ring drawn
+     * around it. What "set apart" means is the host's — say, a node that
+     * has no container. Absent, no ring.
+     */
+    ring?: 'dashed';
+    /**
+     * The key every copy of one underlying entity shares. One entity placed in
+     * three containers produces three nodes with three `id`s and one `copyKey`;
+     * the view draws the copies with a halo, lights them together, counts them
+     * once on a chip and tells them apart in the hover box ("copy 2 of 3").
+     * Absent, the node is its own key. Like `id`, opaque: the host decides how
+     * to derive it.
+     */
+    copyKey?: string;
+    /**
+     * Short texts drawn as chips above the node, as given — a cardinality, a
+     * tag, a count. Display only, never identity. Absent or empty, no chips.
+     */
+    badges?: readonly string[];
+}
+/** The key a node's copies share: its `copyKey`, or its own id. */
+export declare const copyKeyOf: (node: Pick<GraphNode, "id" | "copyKey">) => string;
+/**
+ * Every node id by the key it shares with its copies, over a whole graph —
+ * the index the view and a host's group overlay read. Derived here from the
+ * nodes, once per graph, rather than supplied beside them.
+ */
+export declare function copyGroups(graph: Pick<Graph, 'nodes'>): Map<string, Set<string>>;
+/**
+ * Read one string out of a node's host-owned payload.
+ *
+ * The library offers the accessor, never the key: a caller that knows the key
+ * is by definition domain-aware, and this keeps that knowledge at the call site
+ * instead of smuggling it into the model. Returns undefined for a missing key
+ * or a non-string value rather than coercing, so a payload shape change surfaces
+ * as an absent field instead of "[object Object]" in a tooltip.
+ */
+export declare function payloadString(node: {
+    payload?: Readonly<Record<string, unknown>>;
+}, key: string): string | undefined;
+/** Read one number out of a node's host-owned payload; undefined for a missing key or a non-number, never a coercion. */
+export declare function payloadNumber(node: {
+    payload?: Readonly<Record<string, unknown>>;
+}, key: string): number | undefined;
+/** An edge of the host's graph: two node ids, a relation, the edge's own axis values and an opaque payload. */
+export interface GraphEdge {
+    id: string;
+    sourceId: string;
+    targetId: string;
+    /**
+     * What the edge means to the engine: a `containment` edge runs from a node
+     * to its container and is drawn dashed and undirected; a `dependency` edge
+     * is directed, walked by the highlight and re-pointed when an end is
+     * hidden. Absent, `dependency`. The containment edge from a node to its
+     * `parentId` is derived; a host may list containment edges of its own,
+     * which are drawn and sprung but never walked as the parent.
+     */
+    relation?: Relation;
+    /** Where this edge sits on the host's own axes (a call kind, say) — what an edge type's `match` reads. Absent, none. */
+    values?: AxisValues;
+    /**
+     * Metadata the host owns and the library does not interpret — the same
+     * contract as `GraphNode.payload`. Per-call-site detail that is not identity
+     * and not an axis lives here.
+     */
+    payload?: Readonly<Record<string, unknown>>;
+}
+/** The edge's relation: as declared, or `dependency`. A misspelt relation is `validateGraph`'s to name. */
+export declare function relationOf(edge: Pick<GraphEdge, 'relation'>): Relation;
+/** Does this edge express containment (as opposed to a dependency)? */
+export declare function isContainment(edge: Pick<GraphEdge, 'relation'>): boolean;
+/**
+ * Every node by id — the index a reader builds once per graph when it needs
+ * lookups. A duplicated id keeps its first node; `validateGraph` names the
+ * duplicate and the view drops the later one.
+ */
+export declare function nodesById(nodes: Iterable<GraphNode>): Map<string, GraphNode>;
+/**
+ * The graph with a containment edge from every node to its `parentId`, for
+ * each node whose host listed none: `in:<node id>`, from the child to its
+ * container. A node whose parent is not in the graph gets none (validation
+ * names that), and a host's own edge to the parent stands. The host's
+ * objects are not mutated; a graph needing nothing is returned as is.
+ */
+export declare function withContainmentEdges(graph: Graph): Graph;
+/**
+ * A graph as a reader sees it — its nodes, its edges, and a lookup by id —
+ * the shape a computed scalar, the layout frame and the view's visible-graph
+ * derivation all read. A `Simulation` satisfies it structurally.
+ */
+export interface ReadableGraph {
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+    getNode(id: string): GraphNode | undefined;
+}
+/** A host's graph as a reader sees it: its nodes and edges, and a lookup by id built once. */
+export declare function readableGraph(graph: Graph): ReadableGraph;
+/**
+ * The host's graph: its nodes, in the order they are laid out, and its edges.
+ * Read, never written, by the view, which indexes the nodes itself.
+ */
+export interface Graph {
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+}
+/**
+ * Whether two graphs say the same thing: the same nodes in the same order
+ * with the same fields, and the same edges — values compared, payloads by
+ * identity. A new graph object equal to the last is the sign of a host
+ * rebuilding what it could have kept; the view says so once.
+ */
+export declare function graphEquals(a: Graph, b: Graph): boolean;

package/dist-lib/graph/scalar.d.ts

@@ -0,0 +1,88 @@
+import { ReadableGraph } from './model';
+/** A computed scalar a layout axis may key on: a number per node, read off the graph and mapped onto [0, 1]. */
+export interface ScalarAxis {
+    /** Stable id — the tuning names the scalar by it. */
+    readonly id: string;
+    /** The control's label. Default: the id. */
+    readonly label?: string;
+    /** The control's hover text. Default: the label. */
+    readonly tooltip?: string;
+    /**
+     * One value per node — a finite number, which the frame maps onto [0, 1]
+     * as `normalize` says: non-negative under `max`, any under `range`,
+     * already in [0, 1] under `none`. A node absent from the map has no value
+     * on this axis and rests at the axis's centre, the same answer as a node
+     * in no bucket on a mapped axis. A true 0 is a value, and the built-ins
+     * answer it as one.
+     */
+    compute(graph: ReadableGraph): Map<string, number>;
+    /**
+     * How the frame maps the answers onto [0, 1]: `max` (the default) divides
+     * by the largest, so 0 stays 0 and a negative answer is refused, loudly;
+     * `range` puts the smallest at 0 and the largest at 1, whatever their
+     * sign; `none` says the answers already lie in [0, 1], and the frame
+     * refuses one outside it.
+     */
+    readonly normalize?: 'max' | 'range' | 'none';
+}
+/** A scalar with its words filled in — what `Taxonomy.scalars` carries. */
+export interface ResolvedScalarAxis extends ScalarAxis {
+    readonly label: string;
+    readonly tooltip: string;
+}
+/** A declared scalar with its defaults filled in: the id as label, the label as tooltip. */
+export declare function resolveScalarAxis(scalar: ScalarAxis): ResolvedScalarAxis;
+/**
+ * Where a scalar's unit interval lands on an axis: the world coordinate a
+ * score of 0 rests at, and the one a score of 1 rests at. Either may be the
+ * lower — a span reads like a chart's axis and flips by dragging its ends
+ * past each other.
+ */
+export interface ScalarSpan {
+    readonly zero: number;
+    readonly one: number;
+}
+/**
+ * A layout axis backed by a computed scalar: which scalar, and — only
+ * once the user has dragged an end — its span. Absent, the span is the
+ * taxonomy's (`defaultSpan`), so it follows the taxonomy as a band axis's
+ * declared bands do; the tuning stores what the user decided, nothing else.
+ */
+export interface ScalarTuning {
+    readonly scalar: string;
+    readonly span?: ScalarSpan;
+}
+/** The guard on a layout tuning: scalar, or a mapping with its overrides. */
+export declare function isScalarTuning<T extends object>(t: ScalarTuning | T): t is ScalarTuning;
+/**
+ * Downstream reach: how many dependency levels deep a node's subtree runs,
+ * propagated up the containment hierarchy (one rank per tier, so a container
+ * strictly out-ranks everything it hosts), normalized by the top container.
+ * Leaves score 0; a graph with no dependency edges scores 0 everywhere.
+ * Topological gravity reads this over the visible subgraph; as an axis it is
+ * read over the whole graph. Either way the answer covers exactly the graph's
+ * nodes: propagation stops at an ancestor the graph does not hold.
+ */
+export declare function computeDownstreamReach(graph: ReadableGraph): Map<string, number>;
+/** Dependency edges in and out, as a fraction of the busiest node's. */
+export declare function computeDegree(graph: ReadableGraph): Map<string, number>;
+/** Containment depth: 0 at the top of the hierarchy, 1 at the deepest node. */
+export declare function computeContainmentDepth(graph: ReadableGraph): Map<string, number>;
+/**
+ * Divide by the maximum so the answer spans [0, 1]; a maximum of 0 is a true
+ * 0 for every node, not an absence — the span's zero end, not the centre.
+ */
+export declare function normalized(values: Map<string, number>): Map<string, number>;
+/**
+ * Map the smallest answer to 0 and the largest to 1; answers all alike are a
+ * true 0 for every node — the span's zero end, not the centre.
+ */
+export declare function rangeNormalized(values: Map<string, number>): Map<string, number>;
+/** The built-in reach scalar. */
+export declare const downstreamReach: ScalarAxis;
+/** The built-in degree scalar. */
+export declare const degree: ScalarAxis;
+/** The built-in depth scalar. */
+export declare const containmentDepth: ScalarAxis;
+/** The scalars every host gets: structural, so they need no domain knowledge. */
+export declare const BUILT_IN_SCALARS: readonly ScalarAxis[];