@issuegraph/editor 0.1.0

package/dist/firstpass/keys.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The first pass, as a pure key map: `Y` / `N` / `S`, and `⌫` to undo.
+ *
+ * §17e is explicit that the queue is keyboard-first, and about why: each answer
+ * has to take two seconds, and reaching for a pointer between questions is most
+ * of the two seconds. "Keyboard-first" here means the pointer is optional
+ * rather than assisted — the whole loop is reachable without one.
+ *
+ * ## It is `create/keys.ts`'s shape, deliberately and for its scar tissue
+ *
+ * That module took four review rounds to arrive at asking about OUR OWN
+ * interaction instead of trying to enumerate the host's other widgets, and it
+ * records the reasoning at length. This map inherits the conclusion rather than
+ * re-deriving it: a `KeyPress` carrying the modifier and composition facts, an
+ * interaction state supplied by the host, and `none` for everything else.
+ *
+ * What is NOT inherited is the interaction vocabulary. `CreateInteraction`'s
+ * `target-search` is a state of the CREATE flow, and this surface has no search
+ * box — so reusing that type would ask a host to answer a question about a flow
+ * it is not in. See {@link FirstPassInteraction}.
+ *
+ * ## `Y`, `N` and `S` are printable, which decides the whole table
+ *
+ * All three answers are letters. In any focused text control they are that
+ * control's characters, so none of them survives editing — and unlike the
+ * create flow there is no `⏎`-shaped exception, because nothing in this loop
+ * requires typing. That makes the table simpler than `create/keys.ts`'s and the
+ * simplicity is a fact about the design rather than a saving: a queue you
+ * answer by typing would not be a two-second queue.
+ */
+import type { KeyPress } from '../create/keys.ts';
+import type { QueueCommand } from './queue.ts';
+/**
+ * Where the keyboard is, in terms of THIS surface.
+ *
+ * - `queue` — the queue has the keyboard. Every binding reaches it.
+ * - `elsewhere` — anything else at all: an inline edit, a filter box, the
+ *   canvas, a modal, a control this package has never heard of. Nothing
+ *   reaches.
+ *
+ * TWO STATES, NOT THREE, and the missing one is the point. `create/keys.ts`
+ * needs `target-search` because its own flow contains a text box that two of
+ * its bindings must survive. This flow contains none, so a third state would be
+ * a distinction with no binding on either side of it — and every state a host
+ * has to map its world onto is a chance to map it wrongly.
+ */
+export type FirstPassInteraction = 'queue' | 'elsewhere';
+/** What the shell knows when a key arrives. */
+export interface FirstPassContext {
+    /**
+     * Which of this surface's interactions the keyboard is in.
+     *
+     * REQUIRED, NOT OPTIONAL, on the same reasoning `KeyboardContext.interaction`
+     * records: every default is wrong for some host, and the plausible default —
+     * "assume the queue" — is the one that steals keystrokes from a host that has
+     * not thought about it.
+     */
+    readonly interaction: FirstPassInteraction;
+    /**
+     * Whether a candidate is on screen.
+     *
+     * An answer with nothing to answer is `none` rather than a command the
+     * reducer would discard, so the host does not `preventDefault()` a key it did
+     * not consume. The reducer treats the same case as a no-op independently —
+     * two guards for one property, which is right here because they protect
+     * different things: this one protects the KEY, that one protects the STATE.
+     */
+    readonly hasCandidate: boolean;
+    /**
+     * Whether anything has been answered, i.e. whether `⌫` has work.
+     *
+     * Same reasoning: an undo with an empty history hands the key back.
+     */
+    readonly canUndo: boolean;
+}
+/** What a key means. `none` leaves the key to the host. */
+export type FirstPassIntent = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'queue';
+    readonly command: QueueCommand;
+};
+/**
+ * What one key press means, given what the shell currently holds.
+ *
+ * Total and pure. One exhaustive switch over a discriminated union, every arm a
+ * single expression, because the decision was already made by the table.
+ */
+export declare function firstPassIntent(press: KeyPress, context: FirstPassContext): FirstPassIntent;
+//# sourceMappingURL=keys.d.ts.map

package/dist/firstpass/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/firstpass/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,WAAW,CAAC;AAEzD,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC;AA+D/D;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAuB3F"}

package/dist/firstpass/keys.js

@@ -0,0 +1,112 @@
+/**
+ * The first pass, as a pure key map: `Y` / `N` / `S`, and `⌫` to undo.
+ *
+ * §17e is explicit that the queue is keyboard-first, and about why: each answer
+ * has to take two seconds, and reaching for a pointer between questions is most
+ * of the two seconds. "Keyboard-first" here means the pointer is optional
+ * rather than assisted — the whole loop is reachable without one.
+ *
+ * ## It is `create/keys.ts`'s shape, deliberately and for its scar tissue
+ *
+ * That module took four review rounds to arrive at asking about OUR OWN
+ * interaction instead of trying to enumerate the host's other widgets, and it
+ * records the reasoning at length. This map inherits the conclusion rather than
+ * re-deriving it: a `KeyPress` carrying the modifier and composition facts, an
+ * interaction state supplied by the host, and `none` for everything else.
+ *
+ * What is NOT inherited is the interaction vocabulary. `CreateInteraction`'s
+ * `target-search` is a state of the CREATE flow, and this surface has no search
+ * box — so reusing that type would ask a host to answer a question about a flow
+ * it is not in. See {@link FirstPassInteraction}.
+ *
+ * ## `Y`, `N` and `S` are printable, which decides the whole table
+ *
+ * All three answers are letters. In any focused text control they are that
+ * control's characters, so none of them survives editing — and unlike the
+ * create flow there is no `⏎`-shaped exception, because nothing in this loop
+ * requires typing. That makes the table simpler than `create/keys.ts`'s and the
+ * simplicity is a fact about the design rather than a saving: a queue you
+ * answer by typing would not be a two-second queue.
+ */
+/**
+ * The vocabulary, as data.
+ *
+ * §17e names the keys `Y` / `N` / `S` and `⌫`. The letters are mnemonics in
+ * English, which is a real limitation and one this package cannot fix from
+ * here: a rebinding belongs to the host, and the reducer takes {@link Answer}
+ * values rather than key names precisely so a host can bind whatever its
+ * readers' keyboards spell without reaching into {@link ./queue.ts}.
+ */
+const BINDINGS = new Map([
+    ['y', { action: 'answer', answer: 'apply' }],
+    ['n', { action: 'answer', answer: 'reject' }],
+    ['s', { action: 'answer', answer: 'skip' }],
+    // BOTH SPELLINGS OF THE DELETE KEY, for the reason `create/keys.ts` records:
+    // §17e writes it `⌫`, which is `Backspace` on the keyboards that have it and
+    // `Delete` on those that do not — most notably Apple's. Binding one of the
+    // two would make "no pointer" false on whichever hardware got the other.
+    ['backspace', { action: 'undo' }],
+    ['delete', { action: 'undo' }],
+]);
+const NONE = Object.freeze({ kind: 'none' });
+/**
+ * The press type is `create/keys.ts`'s, imported rather than redeclared.
+ *
+ * A KEY PRESS IS A PLATFORM FACT, not a fact about either flow: the fields are
+ * `KeyboardEvent`'s, fixed by the DOM, and identical here for reasons that are
+ * identical too — a bare key name cannot tell `Y` from `Cmd+Y`, an input method
+ * owns every printable key while composing, and an auto-repeat is not a second
+ * act. Two structurally identical declarations of it would be the drifting
+ * second implementation this package family removes everywhere it appears, and
+ * they would drift in the worst possible place: the day the DOM grows a field
+ * one flow must honour, only one of the two would learn about it.
+ *
+ * So the shared definition is imported across, and the package's surface keeps
+ * exporting it exactly once, from where it is declared — a host wiring both
+ * surfaces holds one `KeyPress` and forwards the same event to either map.
+ */
+/**
+ * Whether this press is a chord that belongs to the platform.
+ *
+ * `shiftKey` IS DELIBERATELY ABSENT — §17e names its bindings in capitals, and
+ * `Shift+y` is how a keyboard reports `Y`, so treating shift as a modifier
+ * would unbind the very keys the design specifies. Folded by {@link normalize}.
+ */
+function chorded(press) {
+    return press.ctrlKey === true || press.metaKey === true || press.altKey === true;
+}
+/** Fold `KeyboardEvent.key` into the table's spelling — see `create/keys.ts`. */
+function normalize(key) {
+    return key.toLowerCase();
+}
+/**
+ * What one key press means, given what the shell currently holds.
+ *
+ * Total and pure. One exhaustive switch over a discriminated union, every arm a
+ * single expression, because the decision was already made by the table.
+ */
+export function firstPassIntent(press, context) {
+    // THE PRESS ITSELF DISQUALIFIES IT, before any lookup. A chord and a
+    // composition belong to someone else; a repeat is not a fresh act at all.
+    if (chorded(press) || press.isComposing === true || press.repeat === true)
+        return NONE;
+    // NOTHING REACHES FROM `elsewhere`. Written as an early return rather than a
+    // decision table on the binding because — unlike the create map — no binding
+    // here survives another control's focus, so a per-binding column would have
+    // one value in every row. `create/keys.ts` earns its table; this would be
+    // ceremony asserting a distinction the design does not make.
+    if (context.interaction !== 'queue')
+        return NONE;
+    const binding = BINDINGS.get(normalize(press.key));
+    if (binding === undefined)
+        return NONE;
+    switch (binding.action) {
+        case 'answer':
+            return context.hasCandidate
+                ? { kind: 'queue', command: { kind: 'answer', answer: binding.answer } }
+                : NONE;
+        case 'undo':
+            return context.canUndo ? { kind: 'queue', command: { kind: 'undo' } } : NONE;
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/firstpass/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/firstpass/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA4DH;;;;;;;;GAQG;AACH,MAAM,QAAQ,GAAiC,IAAI,GAAG,CAAkB;IACtE,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC5C,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC7C,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC3C,6EAA6E;IAC7E,6EAA6E;IAC7E,2EAA2E;IAC3E,yEAAyE;IACzE,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjC,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;CAC/B,CAAC,CAAC;AAEH,MAAM,IAAI,GAAoB,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;GAMG;AACH,SAAS,OAAO,CAAC,KAAe;IAC9B,OAAO,KAAK,CAAC,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC;AACnF,CAAC;AAED,iFAAiF;AACjF,SAAS,SAAS,CAAC,GAAW;IAC5B,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAe,EAAE,OAAyB;IACxE,qEAAqE;IACrE,0EAA0E;IAC1E,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,WAAW,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvF,6EAA6E;IAC7E,6EAA6E;IAC7E,4EAA4E;IAC5E,0EAA0E;IAC1E,6DAA6D;IAC7D,IAAI,OAAO,CAAC,WAAW,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAEjD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAEvC,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC;QACvB,KAAK,QAAQ;YACX,OAAO,OAAO,CAAC,YAAY;gBACzB,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE;gBACxE,CAAC,CAAC,IAAI,CAAC;QACX,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACjF,CAAC;AACH,CAAC"}

package/dist/firstpass/queue.d.ts

@@ -0,0 +1,183 @@
+/**
+ * The first-pass review queue: one candidate, one keystroke, one answer.
+ *
+ * §17e's loop is `Y` / `N` / `S` with `⌫` to undo, over candidates the host
+ * found. This module is the whole of that as a reducer — the same shape
+ * `create/draft.ts` and `scale/commands.ts` already use here, so a host
+ * reducing one reduces this without learning a second protocol.
+ *
+ * ## Nothing is applied without a keystroke, and the shape is what guarantees it
+ *
+ * §17e gives the reason and it is worth quoting rather than paraphrasing: "A
+ * wrong `duplicate-of` silently removes real work from the order, so it always
+ * costs one keystroke of consent."
+ *
+ * A `duplicate-of` excludes an issue from the order ENTIRELY. Applied without
+ * consent, that is work vanishing from the backlog while looking handled — the
+ * dead-duplicate audit class arriving through automation instead of decay.
+ *
+ * So consent is structural rather than promised: the ONLY thing in this module
+ * that returns a non-null proposal is the `answer` command carrying
+ * {@link Answer} `apply`, and nothing else here constructs one at all. Advancing
+ * the queue, loading it, rendering it and undoing all emit `null` because there
+ * is no code path on which they could emit anything else. `queue.test.ts` pins
+ * it from the other side — a whole queue driven to exhaustion by `reject` and
+ * `skip` dispatches nothing — and `render.test.ts` pins the surface: drawing a
+ * candidate is not answering it.
+ *
+ * ## Progress is bounded by CANDIDATES, and never by backlog size
+ *
+ * "Progress is bounded by candidates found, not backlog size, so first pass has
+ * an end. 100% encoded is never the goal and the workspace never implies it is
+ * — most issues legitimately have no relationships."
+ *
+ * The denominator is therefore {@link QueueState.candidates}`.length` and this
+ * module is never told how many issues exist — it cannot compute the wrong
+ * denominator because it does not hold the number that would be wrong. An owner
+ * with 248 legitimately-isolated issues is not shown "20% done"; they are shown
+ * a queue of 64 questions with an end, which is the difference between a
+ * surface that gets finished and one that gets abandoned.
+ *
+ * ## Undo returns the QUESTION; it does not retract the WRITE
+ *
+ * `⌫` steps the cursor back and un-answers the candidate. What it cannot do is
+ * un-dispatch a proposal that already went to the store — that is the store's
+ * undo, over its own mutation set, and a second retraction path out here would
+ * be free to disagree with it about what undoing a create means.
+ *
+ * So an undo that withdraws an `apply` REPORTS the withdrawal
+ * ({@link QueueResult.withdrawn}) and the host routes it to the store. The
+ * queue's own state is honest either way: the candidate is unanswered again,
+ * which is what the reader just asked for.
+ */
+import type { Proposal } from '@issuegraph/store';
+import type { Candidate, CandidateId } from './candidates.ts';
+/**
+ * What an owner said about a candidate.
+ *
+ * Three, closed by §17e, and named for the DECISION rather than for the key —
+ * `apply` rather than `yes`, because the keyboard spelling belongs to
+ * {@link ./keys.ts} and a rebinding must not have to reach in here.
+ *
+ * - `apply` — yes, create it. The one answer that emits.
+ * - `reject` — no, this is not a relationship. Answered, and gone.
+ * - `skip` — not now. Answered for the purpose of PROGRESS, because the owner
+ *   did the work of looking; deferring it into a second pass would make the
+ *   progress bar a lie in the direction that matters, by never letting a queue
+ *   with hard cases in it end.
+ */
+export type Answer = 'apply' | 'reject' | 'skip';
+/** A candidate, and what was said about it. */
+export interface Answered {
+    readonly candidate: Candidate;
+    readonly answer: Answer;
+}
+/**
+ * The queue.
+ *
+ * `cursor` indexes {@link candidates} and is the number of answers given, which
+ * is not a coincidence to be maintained but the reason there is no second
+ * field: answers are given in order and undone in order, so the two cannot
+ * drift. `answers[i]` is the answer to `candidates[i]`.
+ */
+export interface QueueState {
+    /** Everything the host found. The denominator, and never anything else. */
+    readonly candidates: readonly Candidate[];
+    /** How far in. Equal to `answers.length`; past the end means finished. */
+    readonly cursor: number;
+    /** What was said, oldest first. */
+    readonly answers: readonly Answered[];
+}
+/** A queue over the candidates a host supplied, with nothing answered yet. */
+export declare function openQueue(candidates: readonly Candidate[]): QueueState;
+/**
+ * One act.
+ *
+ * `answer` carries the DECISION and not the candidate: the queue shows exactly
+ * one candidate, so which one is being answered is the queue's own state rather
+ * than something a caller can get wrong. A command naming a candidate would
+ * admit answering one that is not on screen, which is consent for a question
+ * nobody was asked.
+ */
+export type QueueCommand = {
+    readonly kind: 'answer';
+    readonly answer: Answer;
+} | {
+    readonly kind: 'undo';
+};
+/**
+ * The next queue, what this transition emitted, and what it took back.
+ *
+ * Three fields rather than a union because a host wires all three once —
+ * `state` always, `proposal` to the store, `withdrawn` to the store's undo —
+ * and a union would make the ordinary reduction a switch over cases that mostly
+ * do the same thing. Same reasoning `CreateResult` records for its pair.
+ */
+export interface QueueResult {
+    readonly state: QueueState;
+    /** Non-null on exactly one transition: an `apply`. */
+    readonly proposal: Proposal | null;
+    /**
+     * The answer an `undo` took back, or `null`.
+     *
+     * A withdrawn `apply` is the one the host must act on — its proposal is
+     * already at the store. A withdrawn `reject` or `skip` dispatched nothing, so
+     * there is nothing to undo beyond the queue position, and it is reported
+     * anyway so the host has one code path rather than two.
+     */
+    readonly withdrawn: Answered | null;
+}
+/** Progress, as §17e defines it. */
+export interface QueueProgress {
+    /** Answers given. */
+    readonly answered: number;
+    /**
+     * Candidates FOUND. The denominator, and the whole point of this type.
+     *
+     * Named `found` rather than `total` deliberately: `total` is the word that
+     * invites a reader to reach for the backlog size, and this number is not
+     * that. See the module header.
+     */
+    readonly found: number;
+    /** Still to answer. */
+    readonly remaining: number;
+    /** Nothing left. A queue over no candidates is finished immediately. */
+    readonly finished: boolean;
+}
+export declare function queueProgress(state: QueueState): QueueProgress;
+/**
+ * The candidate on screen, or `null` when the queue is finished.
+ *
+ * `null` rather than a sentinel candidate: "there is nothing to answer" is a
+ * genuinely different state from "here is a question", and a placeholder would
+ * be answerable.
+ */
+export declare function currentCandidate(state: QueueState): Candidate | null;
+/**
+ * Apply one command. Total, pure, and never mutates what it is given.
+ *
+ * An exhaustive switch over a discriminated union — the one branching form
+ * `AGENTS.md`'s boundary rule leaves open, and the shape every reducer in this
+ * package already uses. Adding a command without a case fails the build.
+ */
+export declare function queueReducer(state: QueueState, command: QueueCommand): QueueResult;
+/**
+ * The candidates an owner deferred, in the order they were deferred.
+ *
+ * §17e's `S` is "not now" rather than "no", so the deferred set is the thing a
+ * second pass is built from — and it is DERIVED here rather than accumulated in
+ * {@link QueueState}, so an undo cannot leave it disagreeing with the answers
+ * it summarises. That is the same reason `queueProgress` derives its counts:
+ * two fields recording one fact is one fact that can be wrong.
+ */
+export declare function skippedCandidates(state: QueueState): readonly Candidate[];
+/**
+ * Whether a candidate has already been answered in this queue.
+ *
+ * For a host merging a fresh candidate set into an open queue — a second
+ * detector finishing late, say. It asks by {@link CandidateId} because that is
+ * the identity the HOST minted, for exactly the reason `candidates.ts` records:
+ * two findings about the same pair are not necessarily the same finding.
+ */
+export declare function isAnswered(state: QueueState, id: CandidateId): boolean;
+//# sourceMappingURL=queue.d.ts.map

package/dist/firstpass/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/firstpass/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjD,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;CACvC;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,UAAU,CAEtE;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9B;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;CACrC;AAED,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC5B,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uBAAuB;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAI9D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,IAAI,CAEpE;AAeD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,GAAG,WAAW,CAyClF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,SAAS,EAAE,CAIzE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,WAAW,GAAG,OAAO,CAEtE"}

package/dist/firstpass/queue.js

@@ -0,0 +1,159 @@
+/**
+ * The first-pass review queue: one candidate, one keystroke, one answer.
+ *
+ * §17e's loop is `Y` / `N` / `S` with `⌫` to undo, over candidates the host
+ * found. This module is the whole of that as a reducer — the same shape
+ * `create/draft.ts` and `scale/commands.ts` already use here, so a host
+ * reducing one reduces this without learning a second protocol.
+ *
+ * ## Nothing is applied without a keystroke, and the shape is what guarantees it
+ *
+ * §17e gives the reason and it is worth quoting rather than paraphrasing: "A
+ * wrong `duplicate-of` silently removes real work from the order, so it always
+ * costs one keystroke of consent."
+ *
+ * A `duplicate-of` excludes an issue from the order ENTIRELY. Applied without
+ * consent, that is work vanishing from the backlog while looking handled — the
+ * dead-duplicate audit class arriving through automation instead of decay.
+ *
+ * So consent is structural rather than promised: the ONLY thing in this module
+ * that returns a non-null proposal is the `answer` command carrying
+ * {@link Answer} `apply`, and nothing else here constructs one at all. Advancing
+ * the queue, loading it, rendering it and undoing all emit `null` because there
+ * is no code path on which they could emit anything else. `queue.test.ts` pins
+ * it from the other side — a whole queue driven to exhaustion by `reject` and
+ * `skip` dispatches nothing — and `render.test.ts` pins the surface: drawing a
+ * candidate is not answering it.
+ *
+ * ## Progress is bounded by CANDIDATES, and never by backlog size
+ *
+ * "Progress is bounded by candidates found, not backlog size, so first pass has
+ * an end. 100% encoded is never the goal and the workspace never implies it is
+ * — most issues legitimately have no relationships."
+ *
+ * The denominator is therefore {@link QueueState.candidates}`.length` and this
+ * module is never told how many issues exist — it cannot compute the wrong
+ * denominator because it does not hold the number that would be wrong. An owner
+ * with 248 legitimately-isolated issues is not shown "20% done"; they are shown
+ * a queue of 64 questions with an end, which is the difference between a
+ * surface that gets finished and one that gets abandoned.
+ *
+ * ## Undo returns the QUESTION; it does not retract the WRITE
+ *
+ * `⌫` steps the cursor back and un-answers the candidate. What it cannot do is
+ * un-dispatch a proposal that already went to the store — that is the store's
+ * undo, over its own mutation set, and a second retraction path out here would
+ * be free to disagree with it about what undoing a create means.
+ *
+ * So an undo that withdraws an `apply` REPORTS the withdrawal
+ * ({@link QueueResult.withdrawn}) and the host routes it to the store. The
+ * queue's own state is honest either way: the candidate is unanswered again,
+ * which is what the reader just asked for.
+ */
+/** A queue over the candidates a host supplied, with nothing answered yet. */
+export function openQueue(candidates) {
+    return { candidates, cursor: 0, answers: [] };
+}
+export function queueProgress(state) {
+    const found = state.candidates.length;
+    const answered = state.answers.length;
+    return { answered, found, remaining: found - answered, finished: answered >= found };
+}
+/**
+ * The candidate on screen, or `null` when the queue is finished.
+ *
+ * `null` rather than a sentinel candidate: "there is nothing to answer" is a
+ * genuinely different state from "here is a question", and a placeholder would
+ * be answerable.
+ */
+export function currentCandidate(state) {
+    return state.candidates[state.cursor] ?? null;
+}
+const NOTHING = Object.freeze({ proposal: null, withdrawn: null });
+/**
+ * The proposal an `apply` stands for.
+ *
+ * ITS OWN FUNCTION, so the module has exactly one place that builds a
+ * `Proposal` and the consent claim in the header is checkable by reading rather
+ * than by trusting. It is also the only reason `Proposal` is imported at all.
+ */
+function proposalFor(candidate) {
+    return { op: 'create', kind: candidate.kind, from: candidate.from, to: candidate.to };
+}
+/**
+ * Apply one command. Total, pure, and never mutates what it is given.
+ *
+ * An exhaustive switch over a discriminated union — the one branching form
+ * `AGENTS.md`'s boundary rule leaves open, and the shape every reducer in this
+ * package already uses. Adding a command without a case fails the build.
+ */
+export function queueReducer(state, command) {
+    switch (command.kind) {
+        case 'answer': {
+            const candidate = currentCandidate(state);
+            // ANSWERING A FINISHED QUEUE IS A NO-OP, not an error and not a wrap-round.
+            // A key press racing the last answer is ordinary — the reader is going
+            // fast, which is the design target — and the alternatives are both worse
+            // than doing nothing: throwing turns a fast reader into an error dialog,
+            // and wrapping re-asks a question they already answered.
+            if (candidate === null)
+                return { state, ...NOTHING };
+            const answered = { candidate, answer: command.answer };
+            const next = {
+                ...state,
+                cursor: state.cursor + 1,
+                answers: [...state.answers, answered],
+            };
+            // THE ONLY EMISSION IN THIS MODULE. `reject` and `skip` advance and say
+            // nothing, which is what makes "no candidate is applied without a
+            // keystroke" a property of the shape rather than a promise.
+            return {
+                state: next,
+                proposal: command.answer === 'apply' ? proposalFor(candidate) : null,
+                withdrawn: null,
+            };
+        }
+        case 'undo': {
+            const last = state.answers[state.answers.length - 1];
+            // Nothing answered is nothing to undo. Same reasoning as above: the key
+            // is handed back rather than made into an error.
+            if (last === undefined)
+                return { state, ...NOTHING };
+            return {
+                state: {
+                    ...state,
+                    cursor: state.cursor - 1,
+                    answers: state.answers.slice(0, -1),
+                },
+                proposal: null,
+                withdrawn: last,
+            };
+        }
+    }
+}
+/**
+ * The candidates an owner deferred, in the order they were deferred.
+ *
+ * §17e's `S` is "not now" rather than "no", so the deferred set is the thing a
+ * second pass is built from — and it is DERIVED here rather than accumulated in
+ * {@link QueueState}, so an undo cannot leave it disagreeing with the answers
+ * it summarises. That is the same reason `queueProgress` derives its counts:
+ * two fields recording one fact is one fact that can be wrong.
+ */
+export function skippedCandidates(state) {
+    return state.answers
+        .filter((answered) => answered.answer === 'skip')
+        .map((answered) => answered.candidate);
+}
+/**
+ * Whether a candidate has already been answered in this queue.
+ *
+ * For a host merging a fresh candidate set into an open queue — a second
+ * detector finishing late, say. It asks by {@link CandidateId} because that is
+ * the identity the HOST minted, for exactly the reason `candidates.ts` records:
+ * two findings about the same pair are not necessarily the same finding.
+ */
+export function isAnswered(state, id) {
+    return state.answers.some((answered) => answered.candidate.id === id);
+}
+//# sourceMappingURL=queue.js.map

package/dist/firstpass/queue.js.map

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

package/dist/firstpass/render.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The first-pass queue, as markup.
+ *
+ * ## Drawing a candidate answers nothing
+ *
+ * The property §17e turns on, and the one this file most has to be trusted
+ * with: rendering emits no proposal, wires no listener and dispatches nothing.
+ * It publishes `data-ig-answer` on three buttons and stops. The consent
+ * §17e requires — "it always costs one keystroke" — survives because the
+ * only thing in this package that builds a `Proposal` from a candidate is
+ * `queue.ts`'s `apply` arm, and nothing here calls it.
+ *
+ * `render.test.ts` asserts it from the outside: a rendered candidate produces
+ * no proposal, because there is no return channel on which it could.
+ *
+ * ## Every readable byte comes from the host or from the document
+ *
+ * The same total claim `picker/render.ts` makes, and it is stricter here than
+ * it looks, because the evidence text is host prose flowing through a package
+ * surface. This module never reads it, never truncates it and never summarises
+ * it — it places it, with the evidence `token` beside it as a data attribute so
+ * a host can style a class of reason and a test can assert one without matching
+ * on words.
+ *
+ * ## Progress is drawn as a number the host worded, not a bar
+ *
+ * §17e: "100% encoded is never the goal and the workspace never implies it is."
+ * A progress BAR implies a target by its geometry — an empty tail is a thing
+ * left undone — and no wording can undo that. So the surface publishes the two
+ * counts as attributes and renders the host's sentence, and a host that wants a
+ * bar draws one knowing what it is claiming. `<progress>` is deliberately not
+ * used for the same reason.
+ *
+ * ## It names itself without claiming a heading level
+ *
+ * Same call `picker/render.ts` records: a heading would be a claim about the
+ * HOST's document outline — whether this surface is a section of something, and
+ * at what depth — which a package rendered into an unknown page cannot make.
+ *
+ * That refusal used to be the whole of it, and it left the root `<section>`
+ * with no accessible name at all: a screen-reader user navigating by landmarks
+ * met an unnamed generic region and could not tell it from any other. The
+ * refusal was right and the silence that followed it was not, so the region now
+ * carries an `aria-label` from {@link ./words.ts FirstPassWords} — which names
+ * the surface without asserting anything about where it sits in an outline. A
+ * host that wants it in the outline still wraps it in a heading of its own
+ * choosing.
+ */
+import { type Theme } from '@issuegraph/viewer';
+import { type FirstPassView } from './view.ts';
+import type { QueueState } from './queue.ts';
+import type { FirstPassWords } from './words.ts';
+/** The attribute a shell reads to know which answer a control stands for. */
+export declare const ANSWER_ATTRIBUTE = "data-ig-answer";
+/**
+ * The attribute on the undo control.
+ *
+ * ITS OWN ATTRIBUTE, not `data-ig-answer="undo"`. {@link ./queue.ts Answer} is
+ * a closed union of three, and undo is not one of them — so a shell reading
+ * `data-ig-answer` and switching over `Answer` would be handed a value outside
+ * the type it was told to expect. `data-ig-command` is the spelling
+ * `picker/render.ts` already uses for a control that is not a choice.
+ */
+export declare const COMMAND_ATTRIBUTE = "data-ig-command";
+/** The attribute carrying an evidence item's machine-readable token. */
+export declare const EVIDENCE_TOKEN_ATTRIBUTE = "data-ig-evidence";
+/** Answers given, on the root. */
+export declare const ANSWERED_ATTRIBUTE = "data-ig-answered";
+/** Candidates found — the denominator, on the root. */
+export declare const FOUND_ATTRIBUTE = "data-ig-found";
+export interface FirstPassOptions {
+    /** The words. Required — see {@link ./words.ts FirstPassWords} for why. */
+    readonly words: FirstPassWords;
+    readonly theme?: Theme | undefined;
+    /** The selector the theme's custom properties are written onto. */
+    readonly themeSelector?: string | undefined;
+}
+export interface FirstPassResult {
+    readonly view: FirstPassView;
+    /** The question, its evidence, the answers and the progress, under one root. */
+    readonly markup: string;
+    /**
+     * The theme and this surface's own stylesheet. Install both.
+     *
+     * The VIEWER's stylesheet is deliberately not among them, on the same
+     * reasoning `picker/render.ts` records: this surface draws no viewer
+     * elements, so shipping the canvas sheet with it would give a host that
+     * installs the queue alone a stylesheet whose every selector matches nothing.
+     */
+    readonly styles: string;
+}
+/**
+ * Draw the queue.
+ *
+ * Takes a {@link QueueState} — never a store and never a source. A host hands
+ * the proposal a reduction produced to `Store.propose`, which is the only thing
+ * in the family that dispatches.
+ */
+export declare function renderFirstPass(state: QueueState, options: FirstPassOptions): FirstPassResult;
+//# sourceMappingURL=render.d.ts.map