@sagmans/dsh-tui 0.1.2 → 0.3.0

package/lib/export.js

@@ -1,19 +1,45 @@
+import { rowText } from "./cards.js";
 import { displayText } from "./text.js";
 /** Directory-relative default the reader can find without being told. */
 export const DEFAULT_EXPORT_PREFIX = 'dsh-session';
+/** How the dump marks a nested call that returned an error, which the screen carried as colour. */
+const SUBCALL_FAILED_SUFFIX = ' (failed)';
 /** Id characters kept in a file name, so a session id cannot escape the directory. */
 const UNSAFE_NAME = /[^A-Za-z0-9._-]/gu;
+/** The shortest code fence; a longer backtick run in the body needs a longer one. */
+const MIN_FENCE = 3;
+const BACKTICK_RUN = /`+/gu;
+/** A comment body must not close the comment that carries it. */
+const COMMENT_CLOSE = '-->';
+const COMMENT_CLOSE_DEFUSED = '-->';
 /** Default file for a dump: the session's own name, in the working directory. */
 export function defaultExportFile(sessionId) {
     return `${DEFAULT_EXPORT_PREFIX}-${sessionId.replace(UNSAFE_NAME, '_')}.md`;
 }
+/**
+ * A fence the body cannot close early.
+ *
+ * Tool output and thinking are arbitrary text, and a run of three backticks in
+ * either would end the block and spill the rest into the document as prose.
+ */
+function fenceFor(text) {
+    let longest = 0;
+    for (const run of text.match(BACKTICK_RUN) ?? [])
+        longest = Math.max(longest, run.length);
+    return '`'.repeat(Math.max(MIN_FENCE, longest + 1));
+}
+/** Comment text with any closing marker defused, so the comment stays one. */
+function commentBody(text) {
+    return displayText(text).replaceAll(COMMENT_CLOSE, COMMENT_CLOSE_DEFUSED);
+}
 /**
  * Render the visible transcript as markdown.
  *
- * The surface's own glyphs are kept so a pasted dump reads like the screen it
- * came from, and every fragment is escaped for display for the same reason a
- * rendered row is: the file may be opened in a terminal, and it is full of
- * model and tool output.
+ * The dump outlives the screen it came from, so each row is given the markdown
+ * construct that carries its meaning rather than whichever mark the surface
+ * happened to draw, and every fragment is escaped for display for the same
+ * reason a rendered row is: the file may be opened in a terminal, and it is
+ * full of model and tool output.
  */
 export function transcriptToText(entries) {
     const lines = [];
@@ -26,23 +52,46 @@ export function transcriptToText(entries) {
                 lines.push('', displayText(entry.text));
                 break;
             case 'notice':
-                lines.push('', `<!-- ${displayText(entry.text)} -->`);
+                lines.push('', `<!-- ${commentBody(entry.text)} -->`);
                 break;
             case 'marker':
                 lines.push('', `--- ${displayText(entry.text)} ---`);
                 break;
-            case 'reasoning':
-                lines.push('', `<!-- ${displayText(entry.summary)} -->`);
+            case 'reasoning': {
+                // The thought is on screen now, so it belongs in the dump; only the
+                // count is metadata, and the body is the part a reader came for.
+                const body = entry.body.split('\n').map(displayText);
+                const fence = fenceFor(body.join('\n'));
+                lines.push('', `<!-- ${commentBody(entry.summary)} -->`, `${fence}reasoning`);
+                lines.push(...body);
+                lines.push(fence);
                 break;
+            }
             case 'tool': {
                 const mark = entry.card.failed ? 'ERROR' : 'tool';
-                lines.push('', `### ${mark}: ${displayText(entry.card.title)}`, '', '```');
-                for (const row of entry.card.detail)
-                    lines.push(displayText(row));
-                if (entry.card.totalLines > entry.card.detail.length) {
-                    lines.push(`… ${entry.card.totalLines - entry.card.detail.length} more lines`);
+                // The dump is the words, not the screen: row classes exist so the
+                // surface can style a line, and a file has no use for them.
+                const rows = entry.card.detail.map(row => displayText(rowText(row)));
+                const more = entry.card.totalLines > entry.card.detail.length
+                    ? `… ${entry.card.totalLines - entry.card.detail.length} more lines`
+                    : undefined;
+                const fence = fenceFor([displayText(entry.card.title), ...rows, more ?? ''].join('\n'));
+                lines.push('', `### ${mark}: ${displayText(entry.card.title)}`);
+                // The calls are what the reader saw under the card, so a dump that
+                // dropped them would lose the only record of what the program reached.
+                const subCalls = entry.card.subCalls ?? [];
+                for (const call of subCalls) {
+                    const text = call.argument === undefined ? call.title : `${call.title} ${call.argument}`;
+                    lines.push(`- ${displayText(text)}${call.failed ? SUBCALL_FAILED_SUFFIX : ''}`);
                 }
-                lines.push('```');
+                const dropped = (entry.card.subCallsTotal ?? subCalls.length) - subCalls.length;
+                if (dropped > 0)
+                    lines.push(`- … ${dropped} more calls`);
+                lines.push('', fence);
+                lines.push(...rows);
+                if (more !== undefined)
+                    lines.push(more);
+                lines.push(fence);
                 break;
             }
         }

package/lib/export.js.map

@@ -1 +1 @@
-{"version":3,"file":"export.js","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGvC,yEAAyE;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAA;AAElD,sFAAsF;AACtF,MAAM,WAAW,GAAG,mBAAmB,CAAA;AAEvC,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,OAAO,GAAG,qBAAqB,IAAI,SAAS,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,KAAK,CAAA;AAC7E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAmC;IAClE,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,MAAM;gBACT,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAA;gBACtE,MAAK;YACP,KAAK,WAAW;gBACd,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;gBACvC,MAAK;YACP,KAAK,QAAQ;gBACX,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;gBACrD,MAAK;YACP,KAAK,QAAQ;gBACX,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;gBACpD,MAAK;YACP,KAAK,WAAW;gBACd,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;gBACxD,MAAK;YACP,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAA;gBACjD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,IAAI,KAAK,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,CAAA;gBAC1E,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM;oBAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;gBACjE,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;oBACrD,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,aAAa,CAAC,CAAA;gBAChF,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;gBACjB,MAAK;YACP,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAA;AACrD,CAAC"}
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"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"}

package/lib/fold-cursor.d.ts

@@ -0,0 +1,23 @@
+import type { ForkEvent } from './agent/fork.ts';
+/**
+ * The fold's place in a session's durable event sequence.
+ *
+ * A resumed session is folded while its agent's loop is already live, so the
+ * same event reaches the surface twice: once on the stream, once from the log
+ * the fold is reading. Every durable event carries a monotonic sequence number,
+ * which is what tells a row that has already been drawn from one that has not.
+ */
+/** Consumes durable events in sequence order, each exactly once. */
+export declare class FoldCursor {
+    private through;
+    /**
+     * Start a fresh transcript.
+     *
+     * Sequence numbers are per session, so a fold that begins a new transcript
+     * must not measure its events against the previous session's numbering.
+     */
+    reset(): void;
+    /** Whether an event still has to be folded, and record it when it does. */
+    accept(event: ForkEvent): boolean;
+}
+//# sourceMappingURL=fold-cursor.d.ts.map

package/lib/fold-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold-cursor.d.ts","sourceRoot":"","sources":["../src/fold-cursor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD;;;;;;;GAOG;AAEH,oEAAoE;AACpE,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAoB;IAEnC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAIb,2EAA2E;IAC3E,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;CAOlC"}

package/lib/fold-cursor.js

@@ -0,0 +1,31 @@
+/**
+ * The fold's place in a session's durable event sequence.
+ *
+ * A resumed session is folded while its agent's loop is already live, so the
+ * same event reaches the surface twice: once on the stream, once from the log
+ * the fold is reading. Every durable event carries a monotonic sequence number,
+ * which is what tells a row that has already been drawn from one that has not.
+ */
+/** Consumes durable events in sequence order, each exactly once. */
+export class FoldCursor {
+    through;
+    /**
+     * Start a fresh transcript.
+     *
+     * Sequence numbers are per session, so a fold that begins a new transcript
+     * must not measure its events against the previous session's numbering.
+     */
+    reset() {
+        this.through = undefined;
+    }
+    /** Whether an event still has to be folded, and record it when it does. */
+    accept(event) {
+        if (typeof event.seq === 'number') {
+            if (this.through !== undefined && event.seq <= this.through)
+                return false;
+            this.through = event.seq;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=fold-cursor.js.map

package/lib/fold-cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold-cursor.js","sourceRoot":"","sources":["../src/fold-cursor.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,oEAAoE;AACpE,MAAM,OAAO,UAAU;IACb,OAAO,CAAoB;IAEnC;;;;;OAKG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,SAAS,CAAA;IAC1B,CAAC;IAED,2EAA2E;IAC3E,MAAM,CAAC,KAAgB;QACrB,IAAI,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YAClC,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO,KAAK,CAAA;YACzE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,GAAG,CAAA;QAC1B,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;CACF"}

package/lib/gates.d.ts

@@ -1,3 +1,4 @@
+import { type Keymap } from './input/actions.ts';
 /** The outcome vocabulary the approval seam accepts from an answerer. */
 export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled';
 /** How a pending gate presents itself, independent of how it is drawn. */
@@ -5,9 +6,54 @@ export interface GateCard {
     readonly kind: 'approval' | 'question';
     readonly title: string;
     readonly detail: readonly string[];
+    /**
+     * The number the first drawn option answers for. A list longer than the
+     * screen shows a window of itself, and a window that restarts at one every
+     * scroll hides where the reader is and contradicts the digits that pick by
+     * that same number.
+     */
+    readonly optionOffset: number;
     readonly options: readonly GateOption[];
+    /**
+     * The row that answers with typed text. A question with no options is answered
+     * by typing anyway, so it has no such row to draw.
+     */
+    readonly custom: GateCustomRow | undefined;
+    /**
+     * The editor the answer is written in, drawn under the row that fills it.
+     *
+     * A question says nothing about its answer until someone writes one, so the
+     * rows come from the surface's own editor rather than from text composed
+     * here: the reader gets the cursor movement, deletion, undo, and paste the
+     * prompt bar already has.
+     */
+    readonly answerInput: GateInput | undefined;
     readonly hint: string;
 }
+/**
+ * The editor a question collects typed text with.
+ *
+ * These are the editor's own members rather than a vocabulary invented here, so
+ * the surface hands in the component the prompt bar already uses and nothing
+ * has to adapt it. Every key the gate does not claim — movement, deletion,
+ * undo, a pasted block — reaches the answer through this.
+ */
+export type GateInputMode = 'answer' | 'secret';
+export interface GateInput {
+    /** The answer as written, with a pasted block expanded back to its text. */
+    getExpandedText(): string;
+    /** Replace the answer, so the next question of a batch does not inherit one. */
+    setText(text: string): void;
+    /** Lay the answer out for this width; its rows are drawn under the free-text row. */
+    render(width: number): string[];
+    /** Take a key the gate itself did not claim. */
+    handleInput(data: string): void;
+    /**
+     * How the surface shows the answer it is collecting, absent on an editor
+     * that has no way to hide one.
+     */
+    setMode?(mode: GateInputMode): void;
+}
 /** One selectable row of a question gate. */
 export interface GateOption {
     readonly label: string;
@@ -15,6 +61,15 @@ export interface GateOption {
     readonly current: boolean;
     readonly selected: boolean;
 }
+/** The row that answers with typed text instead of a listed label. */
+export interface GateCustomRow {
+    readonly label: string;
+    readonly description: string | undefined;
+    /** Whether the cursor is on this row, which is what makes typing the answer. */
+    readonly current: boolean;
+    /** Whether a custom answer is being formed or already holds text. */
+    readonly selected: boolean;
+}
 /**
  * One pending approval.
  *
@@ -25,8 +80,12 @@ export interface GateOption {
 export declare class ApprovalGate {
     private readonly toolName;
     private readonly reason;
+    /** The keys in force, read per press so a settings edit lands on the next key. */
+    private readonly keys;
     private outcome;
-    constructor(toolName: string, reason: string | undefined);
+    constructor(toolName: string, reason: string | undefined, 
+    /** The keys in force, read per press so a settings edit lands on the next key. */
+    keys: () => Keymap);
     get resolved(): boolean;
     /** Apply one key press; returns the outcome the first time it settles. */
     handleKey(data: string): ApprovalOutcome | undefined;
@@ -37,6 +96,7 @@ export declare class ApprovalGate {
 export interface GateQuestion {
     readonly id: string;
     readonly question: string;
+    readonly header: string | undefined;
     readonly detail: string | undefined;
     readonly options: readonly {
         readonly label: string;
@@ -57,6 +117,8 @@ export interface GateAnswer {
  * option-less gate rather than a rejected request: the model asked for text.
  */
 export declare function toGateQuestions(request: unknown): GateQuestion[];
+/** The number the free-text row answers for. It sits below the window, so drawn numbering runs 1..n then 0. */
+export declare const CUSTOM_ROW_NUMBER = 0;
 /**
  * A pending batch of questions.
  *
@@ -67,18 +129,99 @@ export declare function toGateQuestions(request: unknown): GateQuestion[];
  */
 export declare class QuestionGate {
     private readonly questions;
+    /** The editor every typed answer is written in, whichever row asks for it. */
+    private readonly input;
+    /** The keys in force, read per press so a settings edit lands on the next key. */
+    private readonly keys;
     private index;
     private cursor;
     private typed;
+    /** Whether the cursor is on the free-text row. */
+    private atCustom;
+    /**
+     * The row an escape from the free-text row returns to.
+     *
+     * It is the row the reader last acted on — walked to, picked by its number, or
+     * toggled — because that is the option they were looking at when they decided
+     * to answer freely, and it is not always the row the cursor still stands on: a
+     * digit picks by number without walking anywhere.
+     */
+    private customFrom;
     private readonly chosen;
     private readonly custom;
     private finished;
-    constructor(questions: readonly GateQuestion[]);
+    constructor(questions: readonly GateQuestion[], 
+    /** The editor every typed answer is written in, whichever row asks for it. */
+    input: GateInput, 
+    /** The keys in force, read per press so a settings edit lands on the next key. */
+    keys: () => Keymap);
+    /**
+     * Empty the editor for the question now under the cursor.
+     *
+     * The editor belongs to the surface and outlives one question, so an answer
+     * must never cross from the last question into the next — or from a gate that
+     * was abandoned into the one that follows it. Its mode follows the question
+     * for the same reason: a credential must not be shown because the last
+     * question was not one.
+     */
+    private resetInput;
     get resolved(): boolean;
+    /**
+     * Stop a question whose caller is gone.
+     *
+     * WHY: an aborted call has no reader for the answer, and a live gate would
+     * otherwise keep the keyboard — and the borrowed editor — until someone
+     * typed into a call that had already ended.
+     */
+    cancel(): void;
     private get current();
+    /**
+     * Options the typed filter leaves, in the order they were listed.
+     *
+     * The order is not the score order a picker uses: a digit answers by
+     * position, and re-ranking rows would move the number the reader just read.
+     */
+    private matched;
+    /**
+     * The rows the keys and the card agree on: the filter, then a window around
+     * the cursor, because a list as long as a provider catalog would otherwise
+     * push the editor off the screen.
+     */
+    private windowed;
+    /** The row under the cursor, as the filter leaves it. */
+    private currentRow;
+    /** Take or drop one source option, by single-select replacement or multi-select toggle. */
+    private pick;
+    /**
+     * Whether a keystroke is answer text rather than a filter.
+     *
+     * A question without options has no list to filter, and the free-text row is
+     * where a question with options collects an answer the model did not list.
+     */
+    private typingAnswer;
+    /** Add text to the filter, or to the answer the current row collects. */
+    private absorb;
     /** Apply one key press; returns the batch answer the first time it completes. */
     handleKey(data: string): GateAnswer[] | undefined;
+    /**
+     * One key press while the free-text row holds the cursor.
+     *
+     * Walking back to the list keeps whatever was typed, so a reader who changes
+     * their mind about answering freely has not lost the text yet. An escape
+     * leaves the row the same way, because a question skipped by accident is a
+     * question the reader has to answer again: from the list, where every other
+     * question is skipped, an escape skips this one too.
+     */
+    private handleCustomKey;
+    /** Take the answer the reader confirmed, then leave the question. */
     private confirm;
+    /**
+     * Leave the current question for the next one.
+     *
+     * Typed text belongs to the question being left, so it never crosses into the
+     * next one — which is why a skipped question reports no typed answer at all.
+     */
+    private advance;
     private result;
     card(): GateCard;
 }

package/lib/gates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAEA,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,CAAA;AAEvE,0EAA0E;AAC1E,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAMD;;;;;;GAMG;AACH,qBAAa,YAAY;IAIrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,OAAO,CAA6B;gBAGzB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS;IAG7C,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,0EAA0E;IAC1E,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAQpD,MAAM,IAAI,IAAI;IAId,IAAI,IAAI,QAAQ;CASjB;AAED,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,EAAE,CAAA;IACjG,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC9B;AAED,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,EAAE,CAwBhE;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;IAQX,OAAO,CAAC,QAAQ,CAAC,SAAS;IAPtC,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAQ;gBAEK,SAAS,EAAE,SAAS,YAAY,EAAE;IAO/D,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,OAAO,KAAK,OAAO,GAElB;IAED,iFAAiF;IACjF,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,SAAS;IAmDjD,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,MAAM;IAYd,IAAI,IAAI,QAAQ;CAuBjB"}
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"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"}