@issuegraph/editor 0.1.0

package/dist/create/draft.js

@@ -0,0 +1,114 @@
+/**
+ * Creating an edge, as the one thing all three paths do.
+ *
+ * §17b asks for three **equivalent** create paths — canvas, inspector and
+ * keyboard — and is explicit that they are equivalent rather than a primary
+ * path with two shortcuts. The inspector is "the only path when the target
+ * isn't on canvas", and at any real size most targets are off canvas (§17f:
+ * the canvas is a *local* instrument), so a design where drag is the real path
+ * and the other two are conveniences is a design that stops working at the
+ * size it was built for.
+ *
+ * ## Equivalence is a property of the SHAPE, not a promise a test keeps
+ *
+ * The three paths gather the same three facts in different orders:
+ *
+ *     canvas      source → target → kind      (drag, then the picker at the drop)
+ *     inspector   source → kind   → target    ("+ add" → type → issue search)
+ *     keyboard    source → kind   → target    (`R` → `1`–`5` → search → `⏎`)
+ *
+ * So a draft modelled as a SEQUENCE would need three sequences, and "equivalent"
+ * would mean three implementations that agree today. This models it as a SET of
+ * gathered facts instead: three slots, each filled by its own command, in any
+ * order, and the proposal is emitted on whichever transition completes the set.
+ * Order-independence stops being a thing to verify and becomes a thing that
+ * cannot be otherwise — there is one emitter, and none of the three paths is
+ * spelled out here at all.
+ *
+ * That is also why the draft carries no path identity. A `source` filled by a
+ * drag and one filled by `R` are the same fact, and a field recording which
+ * arrived would be the difference between the paths growing back — every reader
+ * of it a place where one path could start behaving unlike the others. What
+ * genuinely differs between them is where the picker is DRAWN, which is
+ * geometry and lives in {@link ./placement.ts}, not state.
+ *
+ * ## One user act, one `Proposal`
+ *
+ * The same rule `picker/view.ts` keeps for retype and flip. `@issuegraph/store`
+ * closed the operation set at four so that one act is one round trip and one
+ * undo entry, and a create that emitted twice — or that emitted a delete plus a
+ * create — would undo the property the store went out of its way to model.
+ *
+ * ## Validity is the store's, and stays there
+ *
+ * A self-edge, a duplicate edge, an unknown issue: `structuralRefusal` owns all
+ * of them and answers with an `InvalidCode`. This module proposes; it does not
+ * adjudicate. `picker/view.ts` made the same call for `unchanged-kind` and
+ * recorded why — a second validity rule out here is a second place for the
+ * answer to drift, and the surface a refusal is drawn on already exists.
+ */
+/** Nothing gathered. The state before a create starts and after one emits. */
+export const IDLE_CREATE_DRAFT = Object.freeze({
+    source: null,
+    target: null,
+    kind: null,
+});
+function complete(draft) {
+    const { source, target, kind } = draft;
+    if (source === null || target === null || kind === null)
+        return null;
+    return { source, target, kind };
+}
+/**
+ * Apply one command. Total, pure, and never mutates what it is given.
+ *
+ * AN EXHAUSTIVE SWITCH OVER A DISCRIMINATED UNION — the shape `scaleReducer`
+ * already uses here and the one branching form `AGENTS.md`'s boundary rule
+ * leaves open. Adding a command without a case fails the build rather than
+ * silently returning the draft unchanged.
+ *
+ * The direction a create lands with is the gather order: `from` is the source,
+ * `to` is the target. Nothing here infers it. §17b's rule is that direction is
+ * STATED rather than guessed, and it is — by the picker, after the edit lands,
+ * with a flip beside it, which is one act from correct. That is the same
+ * reasoning `picker/view.ts` records for retyping across the directed/symmetric
+ * split, and it is why this module does not ask about directedness at all: a
+ * symmetric kind keeps the pair too, precisely so an editor knows which issue
+ * carries the field.
+ */
+export function createReducer(draft, command) {
+    const next = (() => {
+        switch (command.kind) {
+            case 'begin':
+                return { source: command.source, target: null, kind: null };
+            case 'target':
+                return { ...draft, target: command.ref };
+            case 'type':
+                return { ...draft, kind: command.edgeKind };
+            case 'cancel':
+                return IDLE_CREATE_DRAFT;
+        }
+    })();
+    // `cancel` CANNOT emit, and it needs no guard here to be sure of it: it
+    // empties the draft, so the completeness test below has nothing to find. An
+    // earlier revision carried an explicit early return for it and claimed to be
+    // tested — a mutation control disproved that in the only way it can be
+    // disproved, by deleting the line and watching every test still pass. It was
+    // dead code asserting its own necessity, which is worse than no comment.
+    //
+    // A withdrawal that fired the edit it withdrew would be the worst possible
+    // reading of the key, so the property is still pinned by tests; what changed
+    // is that they now pin a structural guarantee rather than a branch.
+    const ready = complete(next);
+    if (ready === null)
+        return { draft: next, proposal: null };
+    // THE DRAFT RESETS ON EMISSION. Left full, the next command to arrive would
+    // complete it again and emit a second proposal for one user act — the "two
+    // dispatches, two order re-evaluations" the closed operation set exists to
+    // prevent. Emission is the end of the draft, not a state it stays in.
+    return {
+        draft: IDLE_CREATE_DRAFT,
+        proposal: { op: 'create', kind: ready.kind, from: ready.source, to: ready.target },
+    };
+}
+//# sourceMappingURL=draft.js.map

package/dist/create/draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.js","sourceRoot":"","sources":["../../src/create/draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAoBH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAgB,MAAM,CAAC,MAAM,CAAC;IAC1D,MAAM,EAAE,IAAI;IACZ,MAAM,EAAE,IAAI;IACZ,IAAI,EAAE,IAAI;CACX,CAAC,CAAC;AA2CH,SAAS,QAAQ,CAAC,KAAkB;IAClC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IACvC,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa,CAAC,KAAkB,EAAE,OAAsB;IACtE,MAAM,IAAI,GAAG,CAAC,GAAgB,EAAE;QAC9B,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;YACrB,KAAK,OAAO;gBACV,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAC9D,KAAK,QAAQ;gBACX,OAAO,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;YAC3C,KAAK,MAAM;gBACT,OAAO,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;YAC9C,KAAK,QAAQ;gBACX,OAAO,iBAAiB,CAAC;QAC7B,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IAEL,wEAAwE;IACxE,4EAA4E;IAC5E,6EAA6E;IAC7E,uEAAuE;IACvE,6EAA6E;IAC7E,yEAAyE;IACzE,EAAE;IACF,2EAA2E;IAC3E,6EAA6E;IAC7E,oEAAoE;IACpE,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAE3D,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,sEAAsE;IACtE,OAAO;QACL,KAAK,EAAE,iBAAiB;QACxB,QAAQ,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE;KACnF,CAAC;AACJ,CAAC"}

package/dist/create/keys.d.ts

@@ -0,0 +1,225 @@
+/**
+ * The keyboard path, as a pure key map.
+ *
+ * §17b fixes the loop — `R` → `1`–`5` → search → `⏎`, with `⌫` deleting a
+ * selected edge and `T` retyping it — and fixes what it is FOR in four words:
+ * "full loop, no pointer". An owner encoding a backlog can reach every edit
+ * without touching a pointing device, which is what makes the first pass fast.
+ *
+ * No DOM, no events, no side-effects: a key NAME and a context in, an intent
+ * out. Exactly the shape `viewer/navigation.ts` chose, and for the same payoff
+ * — the whole map is exhaustively testable on a runtime with no DOM at all, and
+ * the shell is left with nothing to get wrong except wiring.
+ *
+ * ## The digits are read from the format, never listed
+ *
+ * `1`–`5` select a kind BY ITS POSITION IN `EDGE_FIELDS`, taken from
+ * `@issuegraph/core`. A local `['blocked-by', …]` out here is the drifting
+ * second implementation the package family removes everywhere it appears:
+ * `picker/view.ts` records the same decision for directedness, and the failure
+ * it prevents is specific — a sixth field added to the format would leave the
+ * list silently wrong, with nothing failing to say so. Built from the vocabulary
+ * itself, a sixth field gets a `6` for free and the picker and the keyboard
+ * cannot disagree about which digit means what.
+ *
+ * ## Retype opens the picker; it does not emit a retype
+ *
+ * `T` answers with the edge to open {@link ../picker/view.ts pickerView} on,
+ * whose options already carry one `retype` proposal each. Emitting one from out
+ * here would be a second retype emitter, and the two would be free to disagree
+ * about what a retype IS — which is the whole reason that module exists.
+ *
+ * ## `none` means SOMEONE ELSE OWNS THIS PRESS
+ *
+ * The same contract `NavigationCommand`'s `none` carries, and the single idea
+ * this module keeps getting asked about. A host's whole wiring is "reduce a
+ * non-`none` intent, and `preventDefault()` it" — so every press this map
+ * claims wrongly is a keystroke stolen from its real owner, and one it hands
+ * back is simply the platform working.
+ *
+ * ## Why this asks about OUR interaction rather than about other owners
+ *
+ * Four review rounds each found a different owner this map had failed to
+ * anticipate: the platform's `Cmd+R`, the target search's digits, an input
+ * method's `⏎`, and then an unrelated editable control's `Escape`. Each fix was
+ * correct and each invited the next, because they were all answers to an
+ * unanswerable question — *who else might own this press?* That list is an
+ * inventory of the HOST's widgets, and this package cannot see it, cannot bound
+ * it, and gets one more entry every time a host grows a control.
+ *
+ * So the question is inverted. {@link CreateInteraction} enumerates OUR OWN
+ * interaction, which §17b fixes at three states, and the host says which one it
+ * is in. A fifth widget adds no code here: the host reports `elsewhere` and the
+ * map is silent. What was an open-ended list of other people's claims became a
+ * closed description of this design's own flow.
+ *
+ * Two press-level facts remain, and they are bounded in a way the widget list
+ * never was — a modifier set and a composition flag are fields on the event
+ * itself, not things a host invents. See {@link KeyPress}.
+ *
+ * That leaves the contract: an unbound key is `none`; a press some other part
+ * of the host owns is `none`; everything else is this vocabulary's.
+ *
+ * Which bindings reach the target search is DATA on the binding table, so no
+ * call site decides it and a sixth binding cannot be added without answering.
+ */
+import type { EdgeId, IssueRef, Proposal } from '@issuegraph/store';
+import type { CreateCommand } from './draft.ts';
+/**
+ * What the shell knows when a key arrives.
+ *
+ * Every field is nullable because every one of them is genuinely absent
+ * sometimes — nothing focused, a search matching nothing, no edge selected —
+ * and a key whose subject is missing resolves to {@link KeyIntent} `none`
+ * rather than to a guess.
+ */
+export interface KeyboardContext {
+    /**
+     * The issue holding the tab stop. The SOURCE a new relationship starts from.
+     *
+     * The viewer's roving tab stop is the natural supply for this: its
+     * `NavigationState.focused` is exactly "the issue the reader is standing on".
+     */
+    readonly focused: IssueRef | null;
+    /**
+     * What the target search currently resolves to, or `null`.
+     *
+     * The SEARCH ITSELF IS THE HOST'S. Matching a query against a backlog needs
+     * the backlog — and at the sizes §17f describes, an index the host already
+     * has — so this module takes the answer rather than the question. It also
+     * keeps the create path indifferent to *how* a target was named: the same
+     * `⏎` works over a fuzzy match, a pasted reference or a picked list row.
+     */
+    readonly match: IssueRef | null;
+    /**
+     * The selected edge, or `null` when the selection is an issue or empty.
+     *
+     * A `together-with` CONNECTOR ARRIVES HERE LIKE ANY OTHER EDGE, and that is
+     * why neither `⌫` nor `T` carries a special case for it. The viewer gives the
+     * connector its own edge identity (`GROUP_ATTRIBUTE`) precisely so that an
+     * enclosure — which has no line to click — is still individually selectable,
+     * so by the time a selection reaches this module it is already just an edge
+     * id. §17b asks that such an edge be selectable, retypeable and deletable;
+     * it is, through the ordinary path, with nothing here to keep in step.
+     */
+    readonly selectedEdge: EdgeId | null;
+    /**
+     * Which of this design's own interactions the keyboard is in.
+     *
+     * REQUIRED, NOT OPTIONAL. Every default is wrong for some host, and the
+     * plausible one — "assume the canvas" — is the one that steals keystrokes; a
+     * host that has not thought about it should get a compile error, not silence.
+     *
+     * The host answers it because the host is the only one who can: this package
+     * has no DOM, and which control holds focus is visible only to the shell.
+     * Crucially, answering it needs no knowledge of THIS package — a host maps
+     * its own world onto three states it already understands.
+     */
+    readonly interaction: CreateInteraction;
+}
+/**
+ * Where the keyboard is, in terms of the create flow §17b specifies.
+ *
+ * Three states, and the set is closed by the DESIGN rather than by the host's
+ * inventory of controls — which is the whole reason it replaced a growing list
+ * of other owners.
+ *
+ * - `canvas` — the create vocabulary is live. Every binding reaches it.
+ * - `target-search` — the create flow's OWN search box has focus. Only the
+ *   bindings that must survive it reach: `⏎` commits the target and `Escape`
+ *   withdraws, which is precisely the middle of `R → digit → search → ⏎`. Its
+ *   printable keys belong to the box — most issue references carry a digit, so
+ *   a map that claimed `1`–`5` here would eat nearly every query — and `⌫`
+ *   deletes a CHARACTER rather than the reader's selected edge.
+ * - `elsewhere` — something else owns the keyboard entirely: an inline title,
+ *   a filter box, a modal, a control this package has never heard of. NOTHING
+ *   reaches, `Escape` included, because that control needs `Escape` to cancel
+ *   its own edit.
+ *
+ * `elsewhere` is what makes the set closed. It is the state for everything not
+ * named, so a host growing a fifth control changes nothing here.
+ */
+export type CreateInteraction = 'canvas' | 'target-search' | 'elsewhere';
+/**
+ * What a key means. `none` leaves the key to the host.
+ *
+ * `create` carries a {@link CreateCommand } for {@link ./draft.ts createReducer},
+ * so the keyboard path feeds the same reducer the other two do rather than
+ * building proposals of its own.
+ */
+export type KeyIntent = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'create';
+    readonly command: CreateCommand;
+} | {
+    readonly kind: 'propose';
+    readonly proposal: Proposal;
+}
+/** Open the type picker on this edge; its options carry the proposals. */
+ | {
+    readonly kind: 'retype';
+    readonly edgeId: EdgeId;
+};
+/**
+ * One key press. Structurally a subset of the DOM's `KeyboardEvent`, so a host
+ * passes the event straight in rather than unpacking it.
+ *
+ * TAKING THE PRESS RATHER THAN THE KEY NAME IS THE POINT. An earlier revision
+ * took a bare `key: string`, which cannot tell `R` from `Cmd+R` — so a shell
+ * that forwarded `event.key` and called `preventDefault()` for any non-`none`
+ * intent would hijack reload, new-tab and tab-selection, and no amount of care
+ * on the host's part could recover the distinction this function had already
+ * discarded. The modifiers are part of what a press IS; asking for them is the
+ * only way this map can honestly answer "not mine".
+ *
+ * The three that BLOCK are optional so `{ key: 'r' }` still means an
+ * unmodified press, which is what a test writes and what a synthetic press from
+ * a non-DOM shell has.
+ */
+export interface KeyPress {
+    /** The `KeyboardEvent.key` value. */
+    readonly key: string;
+    readonly ctrlKey?: boolean;
+    readonly metaKey?: boolean;
+    readonly altKey?: boolean;
+    /**
+     * `KeyboardEvent.isComposing` — whether an input method is mid-composition.
+     *
+     * The two keys this protects are exactly the two that survive editable focus.
+     * While an IME is composing, `⏎` CONFIRMS the candidate and `Escape` CANCELS
+     * the composition; both belong to the input method, and claiming them commits
+     * a stale target or discards the draft while the reader is still spelling the
+     * word they meant to search for. Anyone entering CJK text hits it on the
+     * ordinary path, which is why it is not an exotic case.
+     */
+    readonly isComposing?: boolean;
+    /**
+     * `KeyboardEvent.repeat` — whether the OS generated this event by auto-repeat
+     * rather than the reader pressing the key again.
+     *
+     * EVERY BINDING IN THIS VOCABULARY IS A ONE-SHOT COMMAND, so a repeat is not
+     * a second act: holding `⌫` past the repeat delay is one decision to delete
+     * one edge, and emitting a proposal per event breaks the one-act/one-proposal
+     * contract `draft.ts` and the store are both built on. The store makes it
+     * visible rather than harmless — a pending delete keeps its edge drawn and
+     * selection is client state, so the queued proposals settle into
+     * `unknown-edge` records after the first one lands.
+     *
+     * It is blanket rather than a per-binding flag because there is no repeatable
+     * binding here to distinguish: `R`, `1`–`5`, `⏎`, `⌫` and `T` are all
+     * discrete commands, none of them a continuous motion like an arrow key. Add
+     * one that genuinely repeats and that is when this earns a column on the
+     * table — not before.
+     */
+    readonly repeat?: boolean;
+}
+/**
+ * What one key press means, given what the shell currently holds.
+ *
+ * Total and pure. The branching is one exhaustive switch over a discriminated
+ * union — the boundary rule's permitted shape — and every arm is a single
+ * expression, because the decision was already made by the table.
+ */
+export declare function keyIntent(press: KeyPress, context: KeyboardContext): KeyIntent;
+//# sourceMappingURL=keys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/create/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAY,QAAQ,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,eAAe,GAAG,WAAW,CAAC;AAEzE;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE;AAC3D,0EAA0E;GACxE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA+DzD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,QAAQ;IACvB,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AA0ED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,GAAG,SAAS,CA+C9E"}

package/dist/create/keys.js

@@ -0,0 +1,228 @@
+/**
+ * The keyboard path, as a pure key map.
+ *
+ * §17b fixes the loop — `R` → `1`–`5` → search → `⏎`, with `⌫` deleting a
+ * selected edge and `T` retyping it — and fixes what it is FOR in four words:
+ * "full loop, no pointer". An owner encoding a backlog can reach every edit
+ * without touching a pointing device, which is what makes the first pass fast.
+ *
+ * No DOM, no events, no side-effects: a key NAME and a context in, an intent
+ * out. Exactly the shape `viewer/navigation.ts` chose, and for the same payoff
+ * — the whole map is exhaustively testable on a runtime with no DOM at all, and
+ * the shell is left with nothing to get wrong except wiring.
+ *
+ * ## The digits are read from the format, never listed
+ *
+ * `1`–`5` select a kind BY ITS POSITION IN `EDGE_FIELDS`, taken from
+ * `@issuegraph/core`. A local `['blocked-by', …]` out here is the drifting
+ * second implementation the package family removes everywhere it appears:
+ * `picker/view.ts` records the same decision for directedness, and the failure
+ * it prevents is specific — a sixth field added to the format would leave the
+ * list silently wrong, with nothing failing to say so. Built from the vocabulary
+ * itself, a sixth field gets a `6` for free and the picker and the keyboard
+ * cannot disagree about which digit means what.
+ *
+ * ## Retype opens the picker; it does not emit a retype
+ *
+ * `T` answers with the edge to open {@link ../picker/view.ts pickerView} on,
+ * whose options already carry one `retype` proposal each. Emitting one from out
+ * here would be a second retype emitter, and the two would be free to disagree
+ * about what a retype IS — which is the whole reason that module exists.
+ *
+ * ## `none` means SOMEONE ELSE OWNS THIS PRESS
+ *
+ * The same contract `NavigationCommand`'s `none` carries, and the single idea
+ * this module keeps getting asked about. A host's whole wiring is "reduce a
+ * non-`none` intent, and `preventDefault()` it" — so every press this map
+ * claims wrongly is a keystroke stolen from its real owner, and one it hands
+ * back is simply the platform working.
+ *
+ * ## Why this asks about OUR interaction rather than about other owners
+ *
+ * Four review rounds each found a different owner this map had failed to
+ * anticipate: the platform's `Cmd+R`, the target search's digits, an input
+ * method's `⏎`, and then an unrelated editable control's `Escape`. Each fix was
+ * correct and each invited the next, because they were all answers to an
+ * unanswerable question — *who else might own this press?* That list is an
+ * inventory of the HOST's widgets, and this package cannot see it, cannot bound
+ * it, and gets one more entry every time a host grows a control.
+ *
+ * So the question is inverted. {@link CreateInteraction} enumerates OUR OWN
+ * interaction, which §17b fixes at three states, and the host says which one it
+ * is in. A fifth widget adds no code here: the host reports `elsewhere` and the
+ * map is silent. What was an open-ended list of other people's claims became a
+ * closed description of this design's own flow.
+ *
+ * Two press-level facts remain, and they are bounded in a way the widget list
+ * never was — a modifier set and a composition flag are fields on the event
+ * itself, not things a host invents. See {@link KeyPress}.
+ *
+ * That leaves the contract: an unbound key is `none`; a press some other part
+ * of the host owns is `none`; everything else is this vocabulary's.
+ *
+ * Which bindings reach the target search is DATA on the binding table, so no
+ * call site decides it and a sixth binding cannot be added without answering.
+ */
+import { EDGE_FIELDS } from '@issuegraph/core';
+/**
+ * The vocabulary, as data.
+ *
+ * THE KIND TRAVELS IN THE BINDING, not an index into `EDGE_FIELDS`. Storing a
+ * position would put an array lookup on the resolve path, whose miss is
+ * `undefined` — a case that cannot happen and would still have to be answered,
+ * in a language where answering it wrongly means a cast. Reading the vocabulary
+ * once, here, closes it.
+ */
+const BINDINGS = new Map([
+    // `r`, the digits and `t` are PRINTABLE. While a text control has focus they
+    // are that control's characters, so they do not survive editing.
+    ['r', { kind: 'relate', reachesTargetSearch: false }],
+    ...EDGE_FIELDS.map((edgeKind, index) => [
+        String(index + 1),
+        { kind: 'choose-type', edgeKind, reachesTargetSearch: false },
+    ]),
+    // `⏎` and `Escape` SURVIVE, and they are the reason this is a per-binding flag
+    // rather than one "printable" test: the flow §17b specifies is
+    // `R → digit → search → ⏎`, so the search box is focused at precisely the
+    // moment `⏎` has to commit the target. A rule that silenced the whole map
+    // while editing would break the loop it exists to deliver. `Escape` survives
+    // for the same reason it is always available: a draft you cannot abandon is
+    // worse than one you cannot start.
+    ['enter', { kind: 'commit-target', reachesTargetSearch: true }],
+    // BOTH SPELLINGS OF THE DELETE KEY. §17b writes it `⌫`, which is `Backspace`
+    // on the keyboards that have it and `Delete` on those that do not — most
+    // notably Apple's, where the key in that position reports `Backspace` and the
+    // key labelled `Delete` is the forward one. Binding one of the two would make
+    // "no pointer" false on whichever hardware got the other.
+    // NOT SURVIVING EDITING is the non-obvious half: in a focused text box `⌫`
+    // deletes a CHARACTER, and a map that claimed it would delete the reader's
+    // selected edge while they were correcting a typo in the search.
+    ['backspace', { kind: 'delete-edge', reachesTargetSearch: false }],
+    ['delete', { kind: 'delete-edge', reachesTargetSearch: false }],
+    ['t', { kind: 'retype-edge', reachesTargetSearch: false }],
+    ['escape', { kind: 'cancel', reachesTargetSearch: true }],
+]);
+const NONE = Object.freeze({ kind: 'none' });
+/**
+ * Whether this press is a chord that belongs to the platform, not to us.
+ *
+ * `shiftKey` IS DELIBERATELY ABSENT. §17b names its bindings in capitals, and
+ * `Shift+r` is how a keyboard reports `R` — so treating shift as a modifier
+ * would unbind the very keys the design specifies. Shift changes which key was
+ * pressed and is folded by `normalize`; Ctrl, Meta and Alt change whose
+ * shortcut it is, which is a different question and the one that matters here.
+ */
+function chorded(press) {
+    return press.ctrlKey === true || press.metaKey === true || press.altKey === true;
+}
+/**
+ * Whether an input method is mid-composition, and therefore owns this press.
+ *
+ * Its own predicate rather than another clause inside {@link chorded}: a chord
+ * is a fact about which MODIFIERS are held, composition is a fact about the
+ * INPUT METHOD's state, and folding them together would make the name lie about
+ * half of what it tests. They are asked in the same breath below because the
+ * question they answer is the same one.
+ */
+function composing(press) {
+    return press.isComposing === true;
+}
+/**
+ * Whether the OS generated this press by auto-repeat.
+ *
+ * A DIFFERENT QUESTION FROM THE OTHER TWO, which is why it is not folded into
+ * either. Those ask who OWNS the press; this one asks whether it is a fresh ACT
+ * at all. The reader holding a key means one decision, however many events the
+ * repeat delay produces.
+ */
+function repeated(press) {
+    return press.repeat === true;
+}
+/**
+ * Whether a binding is live in the interaction the host reports.
+ *
+ * A DECISION TABLE OVER THE THREE STATES, exhaustive so a fourth interaction —
+ * were the design ever to grow one — is a compile error here rather than a
+ * silently permissive default. `elsewhere` returning `false` for EVERY binding
+ * is the whole of the fix for an unrelated control's `Escape`: that control
+ * needs `Escape` to cancel its own edit, and a create draft it knows nothing
+ * about must not consume it.
+ */
+function reaches(binding, interaction) {
+    switch (interaction) {
+        case 'canvas':
+            return true;
+        case 'target-search':
+            return binding.reachesTargetSearch;
+        case 'elsewhere':
+            return false;
+    }
+}
+/**
+ * Fold a `KeyboardEvent.key` into the table's spelling.
+ *
+ * Lower-casing is what makes `R` and `r` the same key, which matters because
+ * §17b names the bindings in capitals while a keyboard reports the shifted and
+ * unshifted forms differently. `toLowerCase` also folds `Enter`, `Backspace`,
+ * `Delete` and `Escape` onto their entries above, so one rule covers both
+ * families and there is no second spelling table to keep aligned.
+ */
+function normalize(key) {
+    return key.toLowerCase();
+}
+/**
+ * What one key press means, given what the shell currently holds.
+ *
+ * Total and pure. The branching is one exhaustive switch over a discriminated
+ * union — the boundary rule's permitted shape — and every arm is a single
+ * expression, because the decision was already made by the table.
+ */
+export function keyIntent(press, context) {
+    // THE PRESS ITSELF DISQUALIFIES IT, before any lookup — none of these is a
+    // miss to be looked up. All three read a field off the event, so none is the
+    // open-ended widget question `CreateInteraction` replaced: `KeyboardEvent`'s
+    // shape is fixed by the platform rather than by how many controls a host has.
+    // TWO QUESTIONS, NOT ONE. The first two ask who OWNS the press — the platform
+    // holds `Cmd+R`, an input method holds `⏎` while composing. The third asks
+    // whether it is a fresh ACT at all, which is a different thing and the reason
+    // it is its own predicate.
+    // COMPOSITION BITES THE TWO BINDINGS THAT REACH THE TARGET SEARCH, which is
+    // why it cannot be folded into `reachesTargetSearch`: `⏎` and `Escape` are
+    // exactly the two that reach a focused search box, and exactly the two an IME
+    // needs while composing.
+    if (chorded(press) || composing(press) || repeated(press))
+        return NONE;
+    const binding = BINDINGS.get(normalize(press.key));
+    if (binding === undefined)
+        return NONE;
+    if (!reaches(binding, context.interaction))
+        return NONE;
+    switch (binding.kind) {
+        case 'relate':
+            // Nothing focused is nothing to relate FROM. Answering `none` hands the
+            // key back rather than opening a draft with a hole in it.
+            return context.focused === null
+                ? NONE
+                : { kind: 'create', command: { kind: 'begin', source: context.focused } };
+        case 'choose-type':
+            // NO CONTEXT NEEDED, and deliberately usable before a target exists: the
+            // keyboard path gathers kind before target, and the draft is a set, so a
+            // kind chosen early is simply a filled slot.
+            return { kind: 'create', command: { kind: 'type', edgeKind: binding.edgeKind } };
+        case 'commit-target':
+            return context.match === null
+                ? NONE
+                : { kind: 'create', command: { kind: 'target', ref: context.match } };
+        case 'delete-edge':
+            return context.selectedEdge === null
+                ? NONE
+                : { kind: 'propose', proposal: { op: 'delete', edgeId: context.selectedEdge } };
+        case 'retype-edge':
+            return context.selectedEdge === null ? NONE : { kind: 'retype', edgeId: context.selectedEdge };
+        case 'cancel':
+            // ALWAYS AVAILABLE. Escape withdraws whatever is open, and a draft the
+            // reader cannot abandon is worse than one they cannot start.
+            return { kind: 'create', command: { kind: 'cancel' } };
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/create/keys.js.map

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

package/dist/create/placement.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Where the canvas path draws its type picker.
+ *
+ * §17b puts the picker "at the drop point", and the kit's implementation note
+ * fixes how that coordinate is arrived at: *"Hand-authoring these coordinates
+ * against remembered positions is the failure mode; compute them from layout."*
+ * So this takes MEASURED bounds — the container's, and the picker's own — and
+ * derives a position from them. It holds no constants about how big anything is.
+ *
+ * ## The one thing it adds to "at the drop point"
+ *
+ * A drop near the right or bottom edge would put a picker anchored there partly
+ * outside the canvas, where the reader cannot reach the options. So the picker
+ * FLIPS to the other side of the drop point rather than being nudged: a flip
+ * keeps the drop point on a corner of the picker, so the picker still visibly
+ * belongs to the gesture that opened it, while a nudge slides it off the point
+ * and reads as landing somewhere arbitrary.
+ *
+ * A flip is reported rather than only applied ({@link AxisPlacement.flipped}),
+ * because the side the picker opens on decides which corner its callout points
+ * from — and a host that had to re-derive that from the coordinates would be
+ * recomputing a decision already made here.
+ *
+ * ## It is geometry, so it is not in the draft
+ *
+ * The canvas is the only path with a drop point: the inspector opens its picker
+ * in a panel and the keyboard never has a pointer position at all. That is the
+ * whole of what distinguishes the three, and keeping it here — rather than as a
+ * field on {@link ./draft.ts CreateDraft} — is what stops "which path started
+ * this" from becoming state the rest of the create logic could branch on.
+ *
+ * Pure arithmetic on numbers, so it runs under the purity test like everything
+ * else here: it never measures anything itself. Measuring is the shell's, from
+ * `getBoundingClientRect` or its own layout output; both arrive as plain data.
+ */
+/** A measured rectangle, in whatever coordinate space the caller measured in. */
+export interface Bounds {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A measured extent. The picker's own, once the host has laid it out. */
+export interface Size {
+    readonly width: number;
+    readonly height: number;
+}
+/** Where the drag was released, in the container's coordinate space. */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** Where to draw the picker, and which way it opened. */
+export interface PickerPlacement {
+    readonly x: number;
+    readonly y: number;
+    readonly flippedX: boolean;
+    readonly flippedY: boolean;
+}
+/**
+ * The picker's top-left corner for a drop at `drop`, inside `container`.
+ *
+ * Every input is measured by the caller; nothing here assumes a size, a margin
+ * or a viewport. `container` is the canvas's own measured bounds rather than the
+ * window's, because the canvas is the surface the drop happened on and a picker
+ * escaping it would sit over the order rail beside it.
+ */
+export declare function pickerPlacement(drop: Point, picker: Size, container: Bounds): PickerPlacement;
+//# sourceMappingURL=placement.d.ts.map

package/dist/create/placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../../src/create/placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,iFAAiF;AACjF,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAsBD,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAyBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAS7F"}