@graview/layout 0.1.0

package/dist/ids.js

@@ -0,0 +1,115 @@
+import { toggleExpanded, withFocus, withOverview, withWithin, withZoom } from "./view-state.js";
+/*
+ * WHAT AN ID MEANS in the picture. A node's id is its own; the picture adds
+ * ids of its own for the things only it draws — a group (`aggregate:`) and a
+ * kind's card on the kinds plane (`kind:`) — and these say how to make one,
+ * read one, and go into one.
+ */
+export const AGGREGATE_PREFIX = "aggregate:";
+/**
+ * The kinds plane's cards have ids of their own.
+ *
+ * They cannot share `aggregate:<kind>` with a focusable group, because an app
+ * whose primary view IS one kind — the coaching example's formation is
+ * `aggregate:position` — would then place the same id twice: once as the
+ * focus and once as its own card in the strip. The strip is a MAP of kinds,
+ * not a set of groups you focus, so it gets its own namespace.
+ */
+export const KIND_PREFIX = "kind:";
+export function kindCardId(kind) {
+    return `${KIND_PREFIX}${kind}`;
+}
+export function kindOfCard(id) {
+    return id.startsWith(KIND_PREFIX) ? id.slice(KIND_PREFIX.length) : null;
+}
+/**
+ * The card that stands for the districts the row could not hold.
+ *
+ * Its own id rather than a kind's, because it is not a kind: it is the row
+ * saying what it had to leave out, and naming them.
+ */
+export const BEYOND_CARD = "kinds:beyond";
+/** The kinds an id stands for, whichever namespace it is in. */
+export function kindsOf(id) {
+    const card = kindOfCard(id);
+    return card ? [card] : kindsOfAggregate(id);
+}
+/**
+ * The id of a group standing in for one or more kinds.
+ *
+ * Several kinds because a group is a view of a SET of kinds, not a synonym
+ * for one: the household example's week is its blocks and its runs together, and no node
+ * kind called "week" exists or should. Kinds are sorted so the same group is
+ * always the same id, which keeps it stable in a URL.
+ */
+export function aggregateId(...kinds) {
+    return `${AGGREGATE_PREFIX}${[...kinds].sort().join("+")}`;
+}
+export function isAggregateId(id) {
+    return id.startsWith(AGGREGATE_PREFIX);
+}
+/** The kinds a group id names, or an empty list if it is not a group id. */
+export function kindsOfAggregate(id) {
+    // A band's group ("aggregate:song|by|in|…") stands for SOME members, not a kind.
+    if (!isAggregateId(id) || id.includes("|"))
+        return [];
+    return id.slice(AGGREGATE_PREFIX.length).split("+").filter(Boolean);
+}
+/**
+ * Going deeper into a card, as view state.
+ *
+ * A record ZOOMS: the same scene with the record grown to most of it, and
+ * the same gesture on the zoomed record zooms back out. A KIND CARD stands
+ * for a group, so deeper means the group: on the ground it zooms into the
+ * group as a place (`aggregate:<kind>`), and from altitude it opens the
+ * district in place — the exploded view — and the same gesture closes it.
+ *
+ * UNLESS THE KIND HAS A PICTURE OF ITS OWN. A district explodes into a ring
+ * of chips because a bag of names is the best a generic card can do with its
+ * members. A kind with a lens registered over it has something better, and
+ * the card already says so with its ◆ — so "deeper" there means that
+ * picture, and the district stays shut. Exploding it replaced a designed
+ * view with the fallback it exists to improve on.
+ *
+ * The card's own id (`kind:<kind>`) is never made the focus. A focus
+ * resolves to a node or to a group's kinds, and a kind card is neither: a
+ * focus on one laid out an empty scene with the card's name in the URL,
+ * which is what double-clicking a group looked like before this existed.
+ */
+export function withJackIn(state, id, options = {}) {
+    const kind = kindOfCard(id);
+    if (kind !== null && state.overview && options.ownPicture !== true) {
+        return toggleExpanded(state, id);
+    }
+    const target = kind !== null ? aggregateId(kind) : id;
+    /*
+     * Carrying words is never the way back out. Standing zoomed in the very
+     * district the search lit, its count or its row narrows it where you are;
+     * only a bare jack-in on the zoomed district is the toggle out.
+     */
+    if (state.zoom && state.focusId === target && !(kind !== null && options.carry))
+        return withZoom(state, false);
+    if (kind !== null && options.carry) {
+        /*
+         * A SEARCH'S DESCENT COMES DOWN. From altitude every village still
+         * stands, every member a building, and a district "opened narrowed"
+         * up there reads as not narrowed at all. The words took you to it, so
+         * it opens on the ground, close, with only what they found.
+         */
+        const down = withOverview({ ...withFocus(state, target), relation: null }, false);
+        return withWithin(withZoom(down, true), "q", options.carry);
+    }
+    return withZoom({ ...withFocus(state, target), relation: null }, true);
+}
+/**
+ * Ranks by a STABLE key — the node id — and never by a mutable count.
+ *
+ * This is the single rule that protects spatial memory. Ordering people by
+ * "how many runs they have" would reshuffle the whole plane the moment
+ * anything is reassigned, and the picture you remember would stop being the
+ * picture you get.
+ */
+export function byStableKey(a, b) {
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+//# sourceMappingURL=ids.js.map

package/dist/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { aggregateId, isAggregateId, kindCardId, kindOfCard, kindsOf, kindsOfAggregate, KIND_PREFIX, withJackIn, AGGREGATE_PREFIX, } from "./ids.js";
+export { holdLayout, layout, marqueeHeightFor, panLayout, planeOf, ROSTER_MOST, ROSTER_ROW, rosterHeight, rosterRows, SCREEN_LEASH_CELLS } from "./layout.js";
+export { easeInOut, interpolate } from "./interpolate.js";
+export { rankKinds } from "./rank.js";
+export type { KindRank, KindRanking } from "./rank.js";
+export type { InterpolatedLayout, InterpolatedNode } from "./interpolate.js";
+export { DEFAULT_OPTIONS } from "./types.js";
+export type { Aggregate, Connector, Layout, LayoutNode, LayoutOptions, Plane, Via, } from "./types.js";
+export { EDGE_SELECTION_PREFIX, edgeOfSelection, edgeSelectionId, EMPTY_VIEW, fromUrl, sameView, toggleExpanded, toUrl, withFocus, withOverview, withPan, withPast, withQuery, withoutSearch, withShown, withPin, withoutMoves, withRelation, withWithin, withSelection, withZoom, } from "./view-state.js";
+export type { EdgeRef, Pin, ViewState } from "./view-state.js";
+export { areaOf, boxOf, centroidOf, estimateWidth, fitLabel, overlaps, spanAt } from "./label-fit.js";
+export type { FitOptions, FitPoint, FittedLabel, LabelBox, Measure } from "./label-fit.js";
+export { cameraLimit, collides, districtsPastTheEdge, panForZoom, placeCity } from "./city.js";
+export type { CityCard, PastTheEdge, PlacedCard } from "./city.js";
+export type { CityFrame } from "./types.js";
+export { bandAggregateWords, bandCaps, bandOf, chooseGrouping, isBandAggregate, packRuns, runOf, shares } from "./band.js";
+export type { BandItem, BandOptions, Relevance } from "./band.js";
+export type { Opens } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,OAAO,EACP,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC9J,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACvD,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EACV,SAAS,EACT,SAAS,EACT,MAAM,EACN,UAAU,EACV,aAAa,EACb,KAAK,EACL,GAAG,GACJ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,UAAU,EACV,OAAO,EACP,QAAQ,EACR,cAAc,EACd,KAAK,EACL,SAAS,EACT,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,aAAa,EACb,SAAS,EACT,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,aAAa,EACb,QAAQ,GACT,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACtG,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,oBAAoB,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC/F,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACnE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC3H,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAClE,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { aggregateId, isAggregateId, kindCardId, kindOfCard, kindsOf, kindsOfAggregate, KIND_PREFIX, withJackIn, AGGREGATE_PREFIX, } from "./ids.js";
+export { holdLayout, layout, marqueeHeightFor, panLayout, planeOf, ROSTER_MOST, ROSTER_ROW, rosterHeight, rosterRows, SCREEN_LEASH_CELLS } from "./layout.js";
+export { easeInOut, interpolate } from "./interpolate.js";
+export { rankKinds } from "./rank.js";
+export { DEFAULT_OPTIONS } from "./types.js";
+export { EDGE_SELECTION_PREFIX, edgeOfSelection, edgeSelectionId, EMPTY_VIEW, fromUrl, sameView, toggleExpanded, toUrl, withFocus, withOverview, withPan, withPast, withQuery, withoutSearch, withShown, withPin, withoutMoves, withRelation, withWithin, withSelection, withZoom, } from "./view-state.js";
+export { areaOf, boxOf, centroidOf, estimateWidth, fitLabel, overlaps, spanAt } from "./label-fit.js";
+export { cameraLimit, collides, districtsPastTheEdge, panForZoom, placeCity } from "./city.js";
+export { bandAggregateWords, bandCaps, bandOf, chooseGrouping, isBandAggregate, packRuns, runOf, shares } from "./band.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,OAAO,EACP,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC9J,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAU7C,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,UAAU,EACV,OAAO,EACP,QAAQ,EACR,cAAc,EACd,KAAK,EACL,SAAS,EACT,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,aAAa,EACb,SAAS,EACT,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,aAAa,EACb,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAEtG,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,oBAAoB,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG/F,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC"}

package/dist/interpolate.d.ts

@@ -0,0 +1,27 @@
+import type { CityFrame, Connector, Layout, LayoutNode } from "./types.js";
+export interface InterpolatedNode extends Omit<LayoutNode, "plane"> {
+    /** Fractional plane, so the renderer can mix two plane styles. */
+    readonly plane: number;
+    /** 0 while fully absent, 1 while fully present. */
+    readonly opacity: number;
+}
+export interface InterpolatedLayout {
+    readonly nodes: readonly InterpolatedNode[];
+    readonly connectors: readonly (Connector & {
+        opacity: number;
+    })[];
+    readonly width: number;
+    readonly height: number;
+    readonly t: number;
+    /** The destination's lattice, when it has one. */
+    readonly city?: CityFrame;
+}
+/**
+ * Interpolates two layouts. Because layout is a pure function of the view,
+ * ANY two states can be tweened — there is no special-cased transition list,
+ * and a new kind of navigation animates for free.
+ */
+export declare function interpolate(from: Layout, to: Layout, t: number): InterpolatedLayout;
+/** Ease-in-out, so a transition reads as motion rather than a slide. */
+export declare function easeInOut(t: number): number;
+//# sourceMappingURL=interpolate.d.ts.map

package/dist/interpolate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.d.ts","sourceRoot":"","sources":["../src/interpolate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC;IACjE,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,SAAS,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAC;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC3B;AAkGD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAwDnF;AAyED,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK3C"}

package/dist/interpolate.js

@@ -0,0 +1,217 @@
+import { aggregateId, isAggregateId, kindCardId, kindOfCard } from "./ids.js";
+const lerp = (a, b, t) => a + (b - a) * t;
+function centre(node) {
+    return { x: node.x + node.width / 2, y: node.y + node.height / 2 };
+}
+const indexed = new WeakMap();
+function indexOf(layout) {
+    let index = indexed.get(layout);
+    if (index)
+        return index;
+    const byId = new Map();
+    const groupsOf = new Map();
+    for (const node of layout.nodes) {
+        byId.set(node.id, node);
+        for (const member of node.aggregate?.memberIds ?? []) {
+            const groups = groupsOf.get(member);
+            if (groups)
+                groups.push(node);
+            else
+                groupsOf.set(member, [node]);
+        }
+    }
+    index = { byId, groupsOf };
+    indexed.set(layout, index);
+    return index;
+}
+/*
+ * The same node and the same far layout give the same stand-in, and a tween
+ * asks sixty times a second: a group of a thousand songs was a thousand
+ * lookups and a centroid per frame. Answered once per pair.
+ */
+const stoodIn = new WeakMap();
+function standIn(node, other) {
+    let known = stoodIn.get(other);
+    if (!known)
+        stoodIn.set(other, (known = new WeakMap()));
+    if (known.has(node))
+        return known.get(node);
+    const answer = standInFresh(node, other);
+    known.set(node, answer);
+    return answer;
+}
+function standInFresh(node, other) {
+    const { byId, groupsOf } = indexOf(other);
+    /*
+     * A BILLBOARD SINKS INTO ITS VILLAGE, and rises out of it. The picture on
+     * a kind's plot is an aggregate node, and an aggregate's stand-in is the
+     * centroid of its members — but from altitude the members are buildings
+     * on the ground, not nodes, so a billboard leaving had nowhere to go and
+     * faded where it stood, at full size, under the billboard replacing it:
+     * two pictures on top of each other for the length of the tween, and
+     * the old one read as left up. Its kind's card is where it goes — the
+     * signpost and board at the front of the village, where its own small
+     * picture is — and where the next one comes from.
+     */
+    if (node.screenOf !== undefined) {
+        const card = byId.get(kindCardId(node.screenOf));
+        if (card)
+            return { ...node, x: card.x, y: card.y, width: card.width, height: card.height };
+    }
+    if (isAggregateId(node.id) || kindOfCard(node.id) !== null) {
+        // A group vanishing: its members are the thing it becomes. Collapse to
+        // the centroid of wherever they went.
+        const members = (node.aggregate?.memberIds ?? [])
+            .map((id) => byId.get(id))
+            .filter((n) => n !== undefined);
+        if (members.length === 0)
+            return null;
+        const points = members.map(centre);
+        const x = points.reduce((sum, p) => sum + p.x, 0) / points.length;
+        const y = points.reduce((sum, p) => sum + p.y, 0) / points.length;
+        return { ...node, x: x - node.width / 2, y: y - node.height / 2 };
+    }
+    const group = groupsOf
+        .get(node.id)
+        ?.find((candidate) => candidate.id === kindCardId(node.kind) || candidate.id === aggregateId(node.kind));
+    if (!group)
+        return null;
+    const point = centre(group);
+    return { ...node, x: point.x - node.width / 2, y: point.y - node.height / 2 };
+}
+/**
+ * Interpolates two layouts. Because layout is a pure function of the view,
+ * ANY two states can be tweened — there is no special-cased transition list,
+ * and a new kind of navigation animates for free.
+ */
+export function interpolate(from, to, t) {
+    const clamped = Math.max(0, Math.min(1, t));
+    const fromById = new Map(from.nodes.map((node) => [node.id, node]));
+    const toById = new Map(to.nodes.map((node) => [node.id, node]));
+    const nodes = [];
+    for (const [id, start] of fromById) {
+        const end = toById.get(id);
+        if (end) {
+            nodes.push(mix(start, end, clamped, 1));
+            continue;
+        }
+        // Leaving: shrink into whatever now stands in for it, and fade.
+        const target = standIn(start, to) ?? start;
+        nodes.push(mix(start, target, clamped, 1 - clamped));
+    }
+    for (const [id, end] of toById) {
+        if (fromById.has(id))
+            continue;
+        // Entering: grow out of whatever stood in for it, and fade in.
+        const source = standIn(end, from) ?? end;
+        nodes.push(mix(source, end, clamped, clamped));
+    }
+    const fromConnectors = new Map(from.connectors.map((c) => [c.id, c]));
+    const toConnectors = new Map(to.connectors.map((c) => [c.id, c]));
+    const connectors = [];
+    for (const [id, start] of fromConnectors) {
+        const end = toConnectors.get(id);
+        connectors.push(end
+            ? { ...mixConnector(start, end, clamped), opacity: 1 }
+            : { ...start, opacity: 1 - clamped });
+    }
+    for (const [id, end] of toConnectors) {
+        if (fromConnectors.has(id))
+            continue;
+        connectors.push({ ...end, opacity: clamped });
+    }
+    return {
+        // A node that has finished fading out is gone. Leaving it in the list at
+        // opacity 0 means the renderer keeps a texture, a placement and a draw
+        // call for something nobody can see — and it never leaves, because no
+        // further frames are emitted once the tween settles.
+        nodes: nodes
+            .filter((node) => node.opacity > 0)
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+        connectors: connectors
+            .filter((connector) => connector.opacity > 0)
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+        width: lerp(from.width, to.width, clamped),
+        height: lerp(from.height, to.height, clamped),
+        t: clamped,
+        ...(mixCity(from.city, to.city, clamped) ? { city: mixCity(from.city, to.city, clamped) } : {}),
+    };
+}
+/**
+ * THE GROUND MOVES WITH THE CITY. Between two cities — the camera flying
+ * closer, a district pinned elsewhere — the cell and the origin tween, so
+ * the lattice, the plots and the roads slide and grow with the cards on
+ * them rather than snapping to the destination while the cards are still
+ * on their way. Rising, there is no city to start from, so the lattice
+ * arrives with the destination and the ground crossfades to it by the
+ * altitude number; a half-scaled lattice would be no grid. Descending, the
+ * city stays as it was while the ground fades out under the landing
+ * picture, instead of vanishing on the first frame of the way down.
+ */
+function mixCity(from, to, t) {
+    if (!from)
+        return to;
+    if (!to)
+        return from;
+    return {
+        cell: lerp(from.cell, to.cell, t),
+        originX: lerp(from.originX, to.originX, t),
+        originY: lerp(from.originY, to.originY, t),
+        pan: { x: lerp(from.pan.x, to.pan.x, t), y: lerp(from.pan.y, to.pan.y, t) },
+        extent: {
+            x: lerp(from.extent.x, to.extent.x, t),
+            y: lerp(from.extent.y, to.extent.y, t),
+            width: lerp(from.extent.width, to.extent.width, t),
+            height: lerp(from.extent.height, to.extent.height, t),
+        },
+    };
+}
+function mix(a, b, t, opacity) {
+    return {
+        id: b.id,
+        kind: b.kind,
+        plane: lerp(a.plane, b.plane, t),
+        x: lerp(a.x, b.x, t),
+        y: lerp(a.y, b.y, t),
+        width: lerp(a.width, b.width, t),
+        height: lerp(a.height, b.height, t),
+        pinned: b.pinned,
+        opacity,
+        ...(b.aggregate ? { aggregate: b.aggregate } : {}),
+        ...(b.via ? { via: b.via } : {}),
+        ...(b.raised ? { raised: true } : {}),
+        ...(b.focused ? { focused: true } : {}),
+        ...(b.opened ? { opened: true } : {}),
+        ...(b.openedRows !== undefined ? { openedRows: b.openedRows } : {}),
+        ...(b.compact ? { compact: true } : {}),
+        ...(b.rank ? { rank: b.rank } : {}),
+        ...(b.nestedUnder ? { nestedUnder: b.nestedUnder } : {}),
+        /* What a card STANDS FOR travels with it, or the row's overflow card
+           arrives mid-transition as an empty box with no kind and nothing in it. */
+        ...(b.beyond ? { beyond: b.beyond } : {}),
+        /* An address is not a position: it does not tween, it travels. Dropped
+           here, a district mid-flight to altitude has no plot, and the ground
+           under it and the roads to it have nothing to stand on. */
+        ...(b.plot ? { plot: b.plot } : {}),
+        ...(b.screenOf ? { screenOf: b.screenOf } : {}),
+        ...(b.depth === undefined ? {} : { depth: lerp(a.depth ?? 1, b.depth, t) }),
+        ...(b.natural ? { natural: b.natural } : {}),
+    };
+}
+function mixConnector(a, b, t) {
+    return {
+        ...b,
+        x1: lerp(a.x1, b.x1, t),
+        y1: lerp(a.y1, b.y1, t),
+        x2: lerp(a.x2, b.x2, t),
+        y2: lerp(a.y2, b.y2, t),
+    };
+}
+/** Ease-in-out, so a transition reads as motion rather than a slide. */
+export function easeInOut(t) {
+    const clamped = Math.max(0, Math.min(1, t));
+    return clamped < 0.5
+        ? 4 * clamped * clamped * clamped
+        : 1 - (-2 * clamped + 2) ** 3 / 2;
+}
+//# sourceMappingURL=interpolate.js.map

package/dist/interpolate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.js","sourceRoot":"","sources":["../src/interpolate.ts"],"names":[],"mappings":"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"}

package/dist/label-fit.d.ts

@@ -0,0 +1,115 @@
+/**
+ * A NAME THAT FITS THE THING IT NAMES.
+ *
+ * Every drawn surface in this framework eventually has to write a word
+ * inside a shape — a district, a region on a plan, a band on a calendar —
+ * and every one of them starts by centring the text at one size and hoping.
+ * That works for as long as the names are short, which is for as long as a
+ * person is typing them.
+ *
+ * A product asked a model to survey a garden and got seven areas back
+ * called things like "Pea-gravel corner with river-rock border, log seats
+ * and a fire bowl". The map drew each at one size across the middle of its
+ * shape: three ran off the canvas, two were struck through by a
+ * neighbour's outline, and nothing failed — every test passed, the
+ * accessibility tree was perfect, and the picture said "rick patio with
+ * gravel joints". Agent-authored labels are not an edge case; they are the
+ * normal case for anything with an intelligence provider in it.
+ *
+ * So this is the arithmetic, apart from any drawing, where it can be
+ * tested: how much room a shape actually has, and what of a name will fit
+ * in it. Nothing here knows what a zone is.
+ */
+export interface FitPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * How wide a shape is AT A HEIGHT — not its bounding box.
+ *
+ * The shapes that overflow worst are the long thin ones, whose box is
+ * generous exactly where the shape is not. So this is a scanline: cross the
+ * polygon with a horizontal line and take the widest run that is genuinely
+ * inside it. For an L, a crescent or an hourglass waist that is much less
+ * than the box, which is the point.
+ */
+export declare function spanAt(outline: readonly FitPoint[], y: number): {
+    readonly x0: number;
+    readonly x1: number;
+};
+/** The corner-to-corner extent, for the vertical room a label has. */
+export declare function boxOf(outline: readonly FitPoint[]): {
+    readonly top: number;
+    readonly bottom: number;
+};
+/** How much a shape covers, by the shoelace. For ordering, not for display. */
+export declare function areaOf(outline: readonly FitPoint[]): number;
+/**
+ * The area-weighted centroid, which is NOT the mean of the corners.
+ *
+ * An L-shaped region with six corners has four of them bunched at one end,
+ * and averaging drags the label off the shape entirely — onto the
+ * neighbour, where it reads as that neighbour's name. The fallback keeps a
+ * degenerate shape from producing a NaN that silently removes the label.
+ */
+export declare function centroidOf(outline: readonly FitPoint[]): FitPoint;
+/**
+ * HOW WIDE A STRING WILL BE.
+ *
+ * Injected, because the honest answer depends on where you are. A browser
+ * has a 2D canvas context that will measure text synchronously with the same
+ * engine that will draw it; a test and a server have nothing, and have to
+ * estimate. The estimate is what this defaults to and it is deliberately
+ * PESSIMISTIC: the failure it guards is overflow, and being a little small
+ * is not a failure at all.
+ *
+ * The first version only estimated, at 0.52 of the size per character, and
+ * that was wrong by enough to matter — a display serif runs from 0.28 for an
+ * "i" to 0.86 for a "W", so a name full of wide letters measured short and
+ * was drawn running off the picture. Which is the exact fault the fitting
+ * exists to prevent, arrived at from the other side.
+ */
+export type Measure = (text: string, fontSize: number) => number;
+export declare const estimateWidth: Measure;
+export interface FittedLabel {
+    readonly lines: readonly string[];
+    readonly fontSize: number;
+    /** True when the whole name is on the drawing, so nothing has to say it again. */
+    readonly whole: boolean;
+}
+export interface FitOptions {
+    /** The widest a line may be. */
+    readonly room: number;
+    /** The tallest the whole label may be. */
+    readonly height: number;
+    /** The size to draw at when there is room. */
+    readonly size: number;
+    /** The size below which nothing is legible anyway. */
+    readonly floor: number;
+    readonly measure?: Measure;
+    /** How many lines to break onto. One or two; more is a paragraph. */
+    readonly lines?: 1 | 2;
+}
+/**
+ * A name that fits, or no name at all.
+ *
+ * In order: the whole thing on one line; the whole thing broken at the space
+ * nearest the middle, which is what a person lettering a plan does; the same
+ * shrunk, down to the floor; and then cut, with an ellipsis, so the shape is
+ * at least identified.
+ *
+ * A shape too small for four characters gets NOTHING. A two-letter stub over
+ * a flower bed is worse than a clean shape, because it reads as somebody
+ * else's label clipped — and `whole: false` is how the caller knows to say
+ * the name somewhere a person can still read it.
+ */
+export declare function fitLabel(text: string, options: FitOptions): FittedLabel | null;
+export interface LabelBox {
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+}
+/** Whether two boxes touch. The whole of collision avoidance, in one line. */
+export declare const overlaps: (a: LabelBox, b: LabelBox) => boolean;
+//# sourceMappingURL=label-fit.d.ts.map

package/dist/label-fit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-fit.d.ts","sourceRoot":"","sources":["../src/label-fit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAmB5G;AAED,sEAAsE;AACtE,wBAAgB,KAAK,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAQrG;AAED,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAQ3D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,CAiBjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;AAGjE,eAAO,MAAM,aAAa,EAAE,OAA8D,CAAC;AAE3F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAyC9E;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,8EAA8E;AAC9E,eAAO,MAAM,QAAQ,GAAI,GAAG,QAAQ,EAAE,GAAG,QAAQ,KAAG,OACM,CAAC"}