@issuegraph/editor 0.1.0

package/dist/reevaluate/view.d.ts

@@ -0,0 +1,102 @@
+/**
+ * What the last edit did to the order, as a view model.
+ *
+ * `@issuegraph/store` already computes the change — `diffOrder` ships
+ * {@link OrderChange}, and it deliberately stops at COUNTS rather than a
+ * sentence so a host writes "3 rows moved · 1 promoted" in its own words. This
+ * module keeps that property. It turns the counts into the parts a summary is
+ * built from, and it decides which rendered row each delta belongs to. It
+ * writes no sentence and holds no state.
+ *
+ * ## Placement, and why it is asked of the scene rather than of the document
+ *
+ * A {@link RankDelta} names an ISSUE. A row is keyed by its slot's LEAD, and a
+ * `together-with` unit is one row whose partners get none — so a delta about a
+ * partner has no row of its own to sit on. `Scene.stationOf` is exactly the
+ * "key -> the key that represents it in this projection" map, and
+ * `Scene.navigable` is every key the projection actually drew. Asking the scene
+ * means the answer comes from the render that just happened, rather than from a
+ * second walk over the document that could disagree with it.
+ *
+ * ## A delta that reaches no row is REPORTED, never dropped
+ *
+ * With one exception, and it is the interesting one: a delta whose `presence`
+ * is `left` describes a row that has gone from the order, so its absence from
+ * the rail is the fact it is reporting rather than a failure to place it. Its
+ * count still reaches the summary, which is where the reader learns it
+ * happened. Everything else that fails to place is a diagnostic — an absence
+ * rendered as a value licenses a false conclusion, and the false conclusion
+ * here would be "nothing happened to that issue".
+ */
+import type { Mutation, MutationId, OrderChange, OrderStatus, RankDelta } from '@issuegraph/store';
+import type { Scene } from '@issuegraph/viewer';
+/**
+ * The facets a change can have, in the order a summary reads them.
+ *
+ * Declared as the tuple and narrowed from it, so the list and the type cannot
+ * drift: adding a facet here is what makes {@link COUNT_OF} and a host's
+ * {@link ./words.ts ChangeWords} fail to compile until both carry it.
+ */
+export declare const CHANGE_FACETS: readonly ["moved", "promoted", "newly-held", "entered", "left"];
+export type ChangeFacet = (typeof CHANGE_FACETS)[number];
+/** One facet that actually happened. Never carries a zero. */
+export interface SummaryPart {
+    readonly facet: ChangeFacet;
+    readonly count: number;
+}
+/** The blast radius of one landed edit, ready to be worded by a host. */
+export interface ChangeSummary {
+    readonly mutationId: MutationId;
+    /** Which edit this was. The host names it; this only says which kind. */
+    readonly op: Mutation['op'];
+    /** Every facet with a non-zero count, in {@link CHANGE_FACETS} order. */
+    readonly parts: readonly SummaryPart[];
+    /**
+     * The edit landed and moved nothing.
+     *
+     * Named rather than left to `parts.length === 0`, because it is a FINDING —
+     * the one an owner auditing an encoding most needs — and a renderer that
+     * reads it as an empty list draws nothing at all. `change.ts` says the same
+     * thing from the other end: reporting it as the absence of a change would
+     * hide it.
+     */
+    readonly unchanged: boolean;
+}
+/**
+ * One rendered row, and everything that changed on it.
+ *
+ * `deltas` IS A LIST BECAUSE A ROW CAN BE MORE THAN ONE ISSUE. A `together-with`
+ * unit is a single row keyed by its lead, while the store's order carries a row
+ * per REF — so when a unit moves, every member produces its own delta and all of
+ * them resolve to that one key. One chip per delta would put two chips on one
+ * row, stacked on top of each other by any mount that positions them by key.
+ * Grouping here means the collision cannot be built rather than being left for a
+ * host to notice.
+ */
+export interface PlacedChip {
+    /** The key the rail drew, which is a slot's lead — not always a delta's ref. */
+    readonly key: string;
+    /** In the order the change reported them. Never empty. */
+    readonly deltas: readonly RankDelta[];
+}
+export interface ReevaluateView {
+    /** `null` when no edit has landed since the last dismissal. */
+    readonly summary: ChangeSummary | null;
+    /** Only rows that changed, and only ones the rail actually drew. */
+    readonly chips: readonly PlacedChip[];
+    /** A write is in flight, so the order shown is the one from before it. */
+    readonly held: boolean;
+    readonly diagnostics: readonly string[];
+}
+/** The parts of a change, largest structure first: counts in, zeroes out. */
+export declare function summaryOf(change: OrderChange): ChangeSummary;
+/**
+ * The whole re-evaluate view for one render.
+ *
+ * `change` is the store's `lastChange`, which is absent until an edit lands and
+ * again once `dismissChange()` is called. Absent means there is nothing to
+ * report — NOT that nothing happened, which is what {@link ChangeSummary.unchanged}
+ * says.
+ */
+export declare function reevaluateView(change: OrderChange | null | undefined, scene: Scene, status: OrderStatus): ReevaluateView;
+//# sourceMappingURL=view.d.ts.map

package/dist/reevaluate/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/reevaluate/view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAgB,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACjH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,iEAMf,CAAC;AAEZ,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAmBzD,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IACvC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,CAY5D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,EACtC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,WAAW,GAClB,cAAc,CA4BhB"}

package/dist/reevaluate/view.js

@@ -0,0 +1,111 @@
+/**
+ * What the last edit did to the order, as a view model.
+ *
+ * `@issuegraph/store` already computes the change — `diffOrder` ships
+ * {@link OrderChange}, and it deliberately stops at COUNTS rather than a
+ * sentence so a host writes "3 rows moved · 1 promoted" in its own words. This
+ * module keeps that property. It turns the counts into the parts a summary is
+ * built from, and it decides which rendered row each delta belongs to. It
+ * writes no sentence and holds no state.
+ *
+ * ## Placement, and why it is asked of the scene rather than of the document
+ *
+ * A {@link RankDelta} names an ISSUE. A row is keyed by its slot's LEAD, and a
+ * `together-with` unit is one row whose partners get none — so a delta about a
+ * partner has no row of its own to sit on. `Scene.stationOf` is exactly the
+ * "key -> the key that represents it in this projection" map, and
+ * `Scene.navigable` is every key the projection actually drew. Asking the scene
+ * means the answer comes from the render that just happened, rather than from a
+ * second walk over the document that could disagree with it.
+ *
+ * ## A delta that reaches no row is REPORTED, never dropped
+ *
+ * With one exception, and it is the interesting one: a delta whose `presence`
+ * is `left` describes a row that has gone from the order, so its absence from
+ * the rail is the fact it is reporting rather than a failure to place it. Its
+ * count still reaches the summary, which is where the reader learns it
+ * happened. Everything else that fails to place is a diagnostic — an absence
+ * rendered as a value licenses a false conclusion, and the false conclusion
+ * here would be "nothing happened to that issue".
+ */
+/**
+ * The facets a change can have, in the order a summary reads them.
+ *
+ * Declared as the tuple and narrowed from it, so the list and the type cannot
+ * drift: adding a facet here is what makes {@link COUNT_OF} and a host's
+ * {@link ./words.ts ChangeWords} fail to compile until both carry it.
+ */
+export const CHANGE_FACETS = Object.freeze([
+    'moved',
+    'promoted',
+    'newly-held',
+    'entered',
+    'left',
+]);
+/**
+ * Where each facet's number lives on {@link ChangeCounts}.
+ *
+ * A table rather than a switch, and rather than a name transform: `newly-held`
+ * and `newlyHeld` are the same fact spelled for two different readers — one a
+ * DOM attribute, one a TypeScript field — and deriving either from the other
+ * would put a string manipulation between the count and the thing it counts.
+ * `Record<ChangeFacet, …>` is what makes the table exhaustive at compile time.
+ */
+const COUNT_OF = Object.freeze({
+    moved: (counts) => counts.moved,
+    promoted: (counts) => counts.promoted,
+    'newly-held': (counts) => counts.newlyHeld,
+    entered: (counts) => counts.entered,
+    left: (counts) => counts.left,
+});
+/** The parts of a change, largest structure first: counts in, zeroes out. */
+export function summaryOf(change) {
+    const parts = CHANGE_FACETS.map((facet) => ({
+        facet,
+        count: COUNT_OF[facet](change.counts),
+    })).filter((part) => part.count > 0);
+    return {
+        mutationId: change.mutation.mutationId,
+        op: change.mutation.op,
+        parts,
+        unchanged: parts.length === 0,
+    };
+}
+/**
+ * The whole re-evaluate view for one render.
+ *
+ * `change` is the store's `lastChange`, which is absent until an edit lands and
+ * again once `dismissChange()` is called. Absent means there is nothing to
+ * report — NOT that nothing happened, which is what {@link ChangeSummary.unchanged}
+ * says.
+ */
+export function reevaluateView(change, scene, status) {
+    const held = status === 'held';
+    if (change === null || change === undefined) {
+        return { summary: null, chips: [], held, diagnostics: [] };
+    }
+    const drawn = new Set(scene.navigable);
+    // Insertion-ordered, so the chips come out in the order the change reported
+    // them and a row that changed twice still appears once, where it first did.
+    const byKey = new Map();
+    const diagnostics = [];
+    for (const delta of change.deltas) {
+        const key = scene.stationOf.get(delta.ref) ?? delta.ref;
+        if (drawn.has(key)) {
+            const group = byKey.get(key);
+            if (group === undefined)
+                byKey.set(key, [delta]);
+            else
+                group.push(delta);
+            continue;
+        }
+        // A row that LEFT the order is expected to be missing from the rail that
+        // renders the order it left. Its count still reaches the summary.
+        if (delta.presence === 'left')
+            continue;
+        diagnostics.push(`${delta.ref} changed, but no row draws it; its chip has nowhere to attach`);
+    }
+    const chips = [...byKey].map(([key, deltas]) => ({ key, deltas }));
+    return { summary: summaryOf(change), chips, held, diagnostics };
+}
+//# sourceMappingURL=view.js.map

package/dist/reevaluate/view.js.map

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

package/dist/reevaluate/words.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The words. Supplied by the host, never by this package.
+ *
+ * `@issuegraph/store` ships the change as COUNTS rather than as a sentence, so
+ * that a host writes "3 rows moved · 1 promoted · 1 newly held" in its own
+ * words, its own order and its own language. This package is the presentation
+ * over that data, and shipping a default sentence here would take the choice
+ * back one layer down — the host would have a summary it could not theme away
+ * and could not translate.
+ *
+ * SO IT IS REQUIRED, NOT DEFAULTED, on the same reasoning `StoreConfig.derive`
+ * is required: "a store cannot invent an order, and a default would be a second
+ * implementation of one." A default vocabulary here would be a language choice
+ * this package is not entitled to make.
+ *
+ * That is a narrow claim, and it is worth being exact about its edge. Layer 1
+ * does write fixed strings for the rail itself. This module does not re-open
+ * that decision; it only declines to add a SECOND fixed string exactly where
+ * the store deliberately refused to add the first.
+ *
+ * ## One vocabulary, read in two places
+ *
+ * {@link ChangeWords.facets} words both the summary line ("3 **rows moved**")
+ * and the per-row chips ("**promoted**"), so each entry has to read on its own
+ * as well as after a number. A host wanting two registers renders the view
+ * model itself; nothing here is load-bearing for that.
+ */
+import type { ChangeFacet } from './view.ts';
+export interface ChangeWords {
+    /**
+     * One word or phrase per facet.
+     *
+     * `Record<ChangeFacet, string>` rather than a partial map: a facet with no
+     * word would render a bare number, which reads as a different quantity rather
+     * than as a missing label. Adding a facet fails a host's build here, which is
+     * where it can be fixed.
+     */
+    readonly facets: Readonly<Record<ChangeFacet, string>>;
+    /**
+     * Shown, on its own and in the summary's own place, when the edit landed and
+     * moved nothing. Not an empty state — the finding.
+     */
+    readonly unchanged: string;
+    /**
+     * Labels the order while a write is in flight and the rows are the ones from
+     * before it. The rail is greyed a step; this says why.
+     */
+    readonly computing: string;
+    /** The dismiss control. The only thing besides the next edit that clears the summary. */
+    readonly dismiss: string;
+    /** How a movement chip names its direction. */
+    readonly direction: Readonly<Record<'up' | 'down', string>>;
+}
+//# sourceMappingURL=words.d.ts.map

package/dist/reevaluate/words.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"words.d.ts","sourceRoot":"","sources":["../../src/reevaluate/words.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7D"}

package/dist/reevaluate/words.js

@@ -0,0 +1,29 @@
+/**
+ * The words. Supplied by the host, never by this package.
+ *
+ * `@issuegraph/store` ships the change as COUNTS rather than as a sentence, so
+ * that a host writes "3 rows moved · 1 promoted · 1 newly held" in its own
+ * words, its own order and its own language. This package is the presentation
+ * over that data, and shipping a default sentence here would take the choice
+ * back one layer down — the host would have a summary it could not theme away
+ * and could not translate.
+ *
+ * SO IT IS REQUIRED, NOT DEFAULTED, on the same reasoning `StoreConfig.derive`
+ * is required: "a store cannot invent an order, and a default would be a second
+ * implementation of one." A default vocabulary here would be a language choice
+ * this package is not entitled to make.
+ *
+ * That is a narrow claim, and it is worth being exact about its edge. Layer 1
+ * does write fixed strings for the rail itself. This module does not re-open
+ * that decision; it only declines to add a SECOND fixed string exactly where
+ * the store deliberately refused to add the first.
+ *
+ * ## One vocabulary, read in two places
+ *
+ * {@link ChangeWords.facets} words both the summary line ("3 **rows moved**")
+ * and the per-row chips ("**promoted**"), so each entry has to read on its own
+ * as well as after a number. A host wanting two registers renders the view
+ * model itself; nothing here is load-bearing for that.
+ */
+export {};
+//# sourceMappingURL=words.js.map

package/dist/reevaluate/words.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"words.js","sourceRoot":"","sources":["../../src/reevaluate/words.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/scale/commands.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The ladder's view state, and the only transitions that reach it.
+ *
+ * Focusing a component, searching for one, and opening the isolated list are
+ * NOT edits: nothing about the document changes, so none of them is a
+ * `Proposal` and none of them goes near the store. They are the reader's
+ * position in the ladder, which is why they live in their own tiny reducer
+ * rather than being threaded through the render as loose arguments.
+ *
+ * THE THREE FIELDS ARE ORTHOGONAL, and every transition touches exactly one of
+ * them. That is a decision rather than an omission: an earlier sketch had
+ * `focus` close the isolated list, which reads as tidy and is really a second
+ * rule a reader has to hold — the list is a list of issues that are in no
+ * component, so it says nothing about which component is drawn and has no
+ * reason to move when that changes.
+ */
+/** Where the reader is standing in the ladder. */
+export interface ScaleState {
+    /**
+     * A key inside the component the canvas is narrowed to, or `null` for every
+     * component at once.
+     *
+     * ANY MEMBER, NOT THE LEAD. Search-to-focus hands back the issue the reader
+     * searched for, and making that the lead's problem would mean the caller
+     * resolving a component before it can ask for one.
+     */
+    readonly focus: string | null;
+    /** The search box's contents, verbatim. Empty means the box is untouched. */
+    readonly query: string;
+    readonly isolatedOpen: boolean;
+}
+export declare const INITIAL_SCALE_STATE: ScaleState;
+export type ScaleCommand = {
+    readonly kind: 'focus';
+    readonly key: string;
+} | {
+    readonly kind: 'clear-focus';
+} | {
+    readonly kind: 'search';
+    readonly query: string;
+} | {
+    readonly kind: 'open-isolated';
+} | {
+    readonly kind: 'close-isolated';
+};
+/**
+ * Apply one command. Total, pure, and never mutates what it is given.
+ *
+ * AN EXHAUSTIVE SWITCH OVER A DISCRIMINATED UNION, which is the one branching
+ * shape `AGENTS.md`'s boundary rule leaves open and the shape this repository
+ * already uses for the same job (`sceneFor`, in the viewer's `render.ts`). The
+ * table it would otherwise be — `kind` to handler — cannot be dispatched
+ * without a cast: the handlers' parameter types intersect rather than union at
+ * the call site, and a cast is exactly what the strict-TypeScript rule forbids.
+ * A compile-time-total switch buys the same guarantee honestly: adding a
+ * command without a case fails the build here rather than silently returning
+ * the state unchanged.
+ */
+export declare function scaleReducer(state: ScaleState, command: ScaleCommand): ScaleState;
+//# sourceMappingURL=commands.d.ts.map

package/dist/scale/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/scale/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,eAAO,MAAM,mBAAmB,EAAE,UAIhC,CAAC;AAEH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,GAAG,UAAU,CAajF"}

package/dist/scale/commands.js

@@ -0,0 +1,49 @@
+/**
+ * The ladder's view state, and the only transitions that reach it.
+ *
+ * Focusing a component, searching for one, and opening the isolated list are
+ * NOT edits: nothing about the document changes, so none of them is a
+ * `Proposal` and none of them goes near the store. They are the reader's
+ * position in the ladder, which is why they live in their own tiny reducer
+ * rather than being threaded through the render as loose arguments.
+ *
+ * THE THREE FIELDS ARE ORTHOGONAL, and every transition touches exactly one of
+ * them. That is a decision rather than an omission: an earlier sketch had
+ * `focus` close the isolated list, which reads as tidy and is really a second
+ * rule a reader has to hold — the list is a list of issues that are in no
+ * component, so it says nothing about which component is drawn and has no
+ * reason to move when that changes.
+ */
+export const INITIAL_SCALE_STATE = Object.freeze({
+    focus: null,
+    query: '',
+    isolatedOpen: false,
+});
+/**
+ * Apply one command. Total, pure, and never mutates what it is given.
+ *
+ * AN EXHAUSTIVE SWITCH OVER A DISCRIMINATED UNION, which is the one branching
+ * shape `AGENTS.md`'s boundary rule leaves open and the shape this repository
+ * already uses for the same job (`sceneFor`, in the viewer's `render.ts`). The
+ * table it would otherwise be — `kind` to handler — cannot be dispatched
+ * without a cast: the handlers' parameter types intersect rather than union at
+ * the call site, and a cast is exactly what the strict-TypeScript rule forbids.
+ * A compile-time-total switch buys the same guarantee honestly: adding a
+ * command without a case fails the build here rather than silently returning
+ * the state unchanged.
+ */
+export function scaleReducer(state, command) {
+    switch (command.kind) {
+        case 'focus':
+            return { ...state, focus: command.key };
+        case 'clear-focus':
+            return { ...state, focus: null };
+        case 'search':
+            return { ...state, query: command.query };
+        case 'open-isolated':
+            return { ...state, isolatedOpen: true };
+        case 'close-isolated':
+            return { ...state, isolatedOpen: false };
+    }
+}
+//# sourceMappingURL=commands.js.map

package/dist/scale/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/scale/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAkBH,MAAM,CAAC,MAAM,mBAAmB,GAAe,MAAM,CAAC,MAAM,CAAC;IAC3D,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,EAAE;IACT,YAAY,EAAE,KAAK;CACpB,CAAC,CAAC;AASH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,KAAiB,EAAE,OAAqB;IACnE,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,OAAO;YACV,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1C,KAAK,aAAa;YAChB,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACnC,KAAK,QAAQ;YACX,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC5C,KAAK,eAAe;YAClB,OAAO,EAAE,GAAG,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QAC1C,KAAK,gBAAgB;YACnB,OAAO,EAAE,GAAG,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/dist/scale/ladder.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The scale ladder — which of the three canvas tiers applies, and the route out
+ * of the two that refuse.
+ *
+ * The list scales; the graph does not, and that is fine because they answer
+ * different questions. The order rail is complete at any size — "what gets
+ * worked next" is answerable for every issue in the document — while the canvas
+ * is a LOCAL instrument answering "what surrounds this issue". So past its
+ * budget the canvas refuses rather than thinning, and this module is what makes
+ * that refusal actionable.
+ *
+ * ## Why this is layer 2 rather than more of layer 1
+ *
+ * `@issuegraph/viewer` already decides the same three tiers and already draws a
+ * refusal — deliberately an INFORMATIONAL one. Its own source says why: that
+ * package does not narrow, it renders exactly what it is given, so a control it
+ * published could never complete the action it advertised. Narrowing is the
+ * host's, and the editor is the host. What lands here is only the half layer 1
+ * refused to own: a component the reader can actually choose, a search that
+ * reaches one, and a chip that opens the issues the canvas leaves out.
+ *
+ * ## What this module deliberately does not compute
+ *
+ * Components, blocking counts, cycle flags and chain depth all come from
+ * `clustersOf` in the viewer. A second pass out here would be a mirror whose
+ * input space drifts from the canvas it is describing — the exact failure the
+ * package split exists to prevent — and the two would eventually disagree about
+ * whether a component contains a cycle while both were rendered on one screen.
+ */
+import { type ViewerDocument, type ViewerIssue } from '@issuegraph/viewer';
+import { type ScaleState } from './commands.ts';
+/** Which of the design's three scale states the canvas is in. */
+export type ScaleTier = 
+/** At or under the node budget: the neighbourhood is drawn. */
+'direct'
+/** Past the node budget: component capsules instead of a hairball. */
+ | 'capsules'
+/** Past the cluster-only budget: capsules are truncated and search leads. */
+ | 'clusters';
+/** One connected component, as the refusal presents it. */
+export interface ScaleCapsule {
+    /**
+     * The member a `focus` command should name to draw this component. It is the
+     * component's first member in the viewer's own ordering, so two renders of
+     * one document always offer the same handle.
+     */
+    readonly lead: string;
+    readonly size: number;
+    readonly blockedByEdges: number;
+    readonly chainDepth: number;
+    readonly hasCycle: boolean;
+    readonly members: readonly string[];
+}
+/**
+ * A move the reader can make from a refusal.
+ *
+ * KINDS, NOT INSTANCES. An earlier shape emitted one route per capsule, which
+ * made `routes` a second copy of `capsules` that could disagree with it. The
+ * capsules carry the identities; this says what can be done with them.
+ */
+export type ScaleRouteKind = 'focus-cluster' | 'search' | 'clear-focus' | 'order-rail';
+export interface ScaleRoute {
+    readonly kind: ScaleRouteKind;
+    readonly label: string;
+}
+/** Why the canvas declined, and where to go instead. Never routeless. */
+export interface ScaleRefusal {
+    readonly reason: string;
+    readonly nodeCount: number;
+    /** The drawing budget the count is past. */
+    readonly budget: number;
+    readonly routes: readonly ScaleRoute[];
+}
+/**
+ * The issues carrying no relationship at all, collapsed to a count.
+ *
+ * THIS IS NOT `NormalizedDocument.isolated`, and the difference is the whole
+ * reason the field is defined here. That one means "in no slot AND on no edge",
+ * which in a grooming view — where every issue holds an order position — is
+ * empty however many relationship-free issues the backlog has. The design's
+ * chip counts issues with no RELATIONSHIP, because in a relationship graph they
+ * are dots carrying no information. Two different questions; reusing one name
+ * for both would report an absence as a value.
+ */
+export interface IsolatedChip {
+    readonly count: number;
+    /** The chip's own text — the count is the information these issues carry. */
+    readonly label: string;
+    readonly open: boolean;
+    /** The issues themselves, and only once the chip has been opened. */
+    readonly issues: readonly ViewerIssue[];
+}
+export interface ScaleMatch {
+    readonly key: string;
+    readonly title: string;
+    /** The `focus` handle for the component this match sits in. */
+    readonly lead: string;
+}
+export interface ScaleSearch {
+    readonly query: string;
+    readonly matches: readonly ScaleMatch[];
+    /** Matches found beyond the ones listed. */
+    readonly omitted: number;
+}
+export interface ScaleLadder {
+    readonly tier: ScaleTier;
+    /** The nodes the canvas would draw: the focused component, or all of them. */
+    readonly nodeCount: number;
+    readonly budgets: {
+        readonly node: number;
+        readonly clusterOnly: number;
+    };
+    /** The focused member, once resolved against a real component. */
+    readonly focus: string | null;
+    readonly refusal: ScaleRefusal | null;
+    readonly capsules: readonly ScaleCapsule[];
+    /** Components found beyond the capsules listed. */
+    readonly capsulesOmitted: number;
+    readonly isolated: IsolatedChip;
+    /** The affordance, present exactly when the canvas refuses. */
+    readonly search: ScaleSearch | null;
+    /**
+     * The document for the CANVAS ZONE — never for the order rail.
+     *
+     * Narrowing the canvas is not narrowing the order, and the two must not be
+     * confused: the rail is rendered from the whole document by the workspace
+     * that assembles the zones. Handing this to a rail would silently shorten the
+     * one surface the design guarantees is complete at any size.
+     */
+    readonly canvas: ViewerDocument;
+    readonly diagnostics: readonly string[];
+}
+/**
+ * Resolve one document and one reader position into a ladder.
+ *
+ * Pure and total: no global is read, nothing is fetched, and a `focus` naming a
+ * key this document does not place in any component produces a diagnostic and
+ * every component, rather than a silently unnarrowed canvas that looks focused.
+ */
+export declare function scaleLadder(input: ViewerDocument, state?: ScaleState): ScaleLadder;
+//# sourceMappingURL=ladder.d.ts.map

package/dist/scale/ladder.d.ts.map

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