synorch 0.2.0 → 0.4.0-beta.0

package/dist/harness/contracts/renderer.d.ts

@@ -0,0 +1,291 @@
+import type { AuthInteraction } from "./auth.ts";
+import type { ChoiceAnswer, ChoiceQuestion } from "./choice.ts";
+import type { SessionEvent } from "./events.ts";
+import type { ModelStreamEvent } from "./model.ts";
+import type { PanelPage } from "./panel.ts";
+import type { ApprovalBroker, PermissionMode } from "./policy.ts";
+/**
+ * The terminal port (ADR-04). Renderers only consume events; they never own task state. The
+ * interactive renderer is the only module allowed to import `@earendil-works/pi-tui`; the plain
+ * and JSONL renderers have no dependencies and are selected whenever there is no TTY.
+ */
+export declare const RENDERER_KINDS: readonly ["tui", "plain", "jsonl"];
+export type RendererKind = (typeof RENDERER_KINDS)[number];
+export interface StatusLine {
+    readonly runId: string | undefined;
+    readonly task: string | undefined;
+    readonly model: string | undefined;
+    readonly step: string | undefined;
+    readonly budgetUsed: string | undefined;
+    readonly budgetLimit: string | undefined;
+    readonly workersRunning: number;
+    readonly pendingApproval: string | undefined;
+    readonly lastVerification: string | undefined;
+}
+export interface SessionHeaderView {
+    readonly workspaceRoot: string;
+    readonly gitBranch: string | undefined;
+    readonly policyMode: "autonomous" | "ask";
+    readonly routes: readonly {
+        readonly tier: string;
+        readonly model: string;
+        readonly source: string;
+    }[];
+    readonly sandboxEnforcement: "full" | "partial" | "unavailable";
+    /** The partial-sandbox warning was already shown once on this machine: the header leaves it out (/permissions keeps it). */
+    readonly sandboxNoticeSeen?: boolean;
+    readonly notices: readonly string[];
+    /** Conversation view (ADR-21): harness version, the conversation model's short name and its context window. */
+    readonly version?: string;
+    readonly model?: string;
+    readonly contextWindowTokens?: number;
+    /** The conversation's interactive permission mode (ADR-08 revision 2026-09-24); absent outside one. */
+    readonly permissionMode?: PermissionMode;
+    /** K8 welcome header facts beyond the ones above (interactive renderer only). */
+    readonly welcome?: SessionWelcomeView;
+}
+/** K8: what the welcome header shows besides version, model, folder and mode. */
+export interface SessionWelcomeView {
+    /** Short commit of the build (`syn --version`). */
+    readonly commit?: string;
+    readonly effort?: string;
+    /** Provider / plan label: `ChatGPT Plus`, `Claude Code`, `OpenAI API`. */
+    readonly plan?: string;
+    /** Worker models that differ from the conversation model. */
+    readonly workers?: readonly string[];
+    /** `~`-shortened workspace path. */
+    readonly path?: string;
+    /** The one contextual hint line. */
+    readonly hint?: string;
+}
+/** K8 welcome header preferences (`ui.welcome.*`). */
+export interface WelcomePreferences {
+    readonly style: "full" | "compact" | "minimal" | "off";
+    readonly logo: "on" | "art" | "glyph" | "off" | "custom";
+    readonly fields: readonly ("version" | "model" | "plan" | "workers" | "folder" | "mode")[];
+    readonly tips: boolean;
+}
+/**
+ * K8 appearance: the theme and welcome pickers with live preview. The renderer owns painting and
+ * previews; the session saves what was chosen to the user configuration.
+ */
+export interface AppearanceControls {
+    /** Every theme the renderer can apply (built-ins, then the user's). */
+    readonly themes: readonly {
+        readonly name: string;
+        readonly description: string;
+        readonly custom: boolean;
+    }[];
+    /** The active theme's name. */
+    readonly theme: string;
+    readonly welcome: WelcomePreferences;
+    /**
+     * Theme picker with a live preview of the highlighted theme; Enter applies it (and resolves its
+     * name), Esc keeps the current one (undefined). `step` labels a wizard step (`1/3`).
+     */
+    pickTheme(signal?: AbortSignal, step?: string): Promise<string | undefined>;
+    /** The whole welcome customization (style, logo, fields, tips) with live preview; applied on the last step. */
+    pickWelcome(signal?: AbortSignal): Promise<WelcomePreferences | undefined>;
+    /** Only the welcome style (the setup wizard's step), applied when chosen. */
+    pickWelcomeStyle(signal?: AbortSignal, step?: string): Promise<WelcomePreferences["style"] | undefined>;
+    /** Glyph set with a sample row per choice; applies from the next session. */
+    pickGlyphs(signal?: AbortSignal, step?: string): Promise<"rich" | "safe" | "ascii" | undefined>;
+    /** Applies a theme by name; false when it is unknown. */
+    setTheme(name: string): boolean;
+    setWelcome(preferences: WelcomePreferences): void;
+    /** Late welcome facts (the plan label resolves after start); redrawn while the header is on screen. */
+    updateWelcome(patch: SessionWelcomeView): void;
+}
+/** What the footer shows about the conversation's model (K3 status line). */
+export interface SessionStatusView {
+    readonly model: string;
+    /** The effective reasoning effort; undefined = provider default / not applicable. */
+    readonly effort: string | undefined;
+    readonly contextWindowTokens?: number;
+}
+export type RenderEvent = {
+    readonly kind: "session-event";
+    readonly event: SessionEvent;
+} | {
+    readonly kind: "stream";
+    readonly requestId: string;
+    readonly event: ModelStreamEvent;
+} | {
+    readonly kind: "status";
+    readonly status: StatusLine;
+} | {
+    readonly kind: "notice";
+    readonly level: "info" | "warning" | "error";
+    readonly message: string;
+};
+/**
+ * One row of the `/` command palette (K1-U1). The session owns the command list and pushes it with
+ * `InteractiveInputControls.setCommands`; the renderer only filters, shows and completes it.
+ *
+ * @example { name: "plan", description: "plan a large goal with parallel workers", argsHint: "<goal>" }
+ */
+export interface CommandPaletteEntry {
+    /** Without the leading slash: `plan`, `model`. */
+    readonly name: string;
+    /** One line, shown dim next to the name. */
+    readonly description: string;
+    /**
+     * Argument hint shown after the name. `<required>` hints make Enter complete the command (so the
+     * argument can be typed) instead of submitting it; `[optional]` hints submit on Enter.
+     */
+    readonly argsHint?: string;
+    readonly aliases?: readonly string[];
+}
+export declare const ATTACHMENT_KINDS: readonly ["file", "directory", "image"];
+export type AttachmentKind = (typeof ATTACHMENT_KINDS)[number];
+/**
+ * Context the user attached to a message (K1-U1 → U2): `@path` mentions and pasted images. The text
+ * keeps its visible placeholder (`@src/app.ts`, `[image 1]`); `label` is that placeholder so the
+ * session can map it back. Paths are absolute. Images live in a temporary PNG (clipboard) or are the
+ * user's own file (pasted/dragged path); the session decides how to send them to the model: only
+ * routes with the `image_input` capability receive image bytes, others get a text note.
+ *
+ * @example { id: "image-1", kind: "image", label: "[image 1]", path: "/tmp/synorch-images/4242-1.png",
+ *            displayPath: "clipboard image", mediaType: "image/png", bytes: 48213, source: "clipboard", temporary: true }
+ * @example { id: "file-1", kind: "file", label: "@src/app.ts", path: "/repo/src/app.ts", displayPath: "src/app.ts", source: "mention" }
+ */
+export interface Attachment {
+    readonly id: string;
+    readonly kind: AttachmentKind;
+    readonly label: string;
+    readonly path: string;
+    /** Workspace-relative for mentions; a short description for clipboard images. */
+    readonly displayPath: string;
+    readonly source: "mention" | "clipboard" | "paste-path";
+    /** Images only: `image/png`, `image/jpeg`, `image/gif`, `image/webp`. */
+    readonly mediaType?: string;
+    readonly bytes?: number;
+    /** True when the harness created the file (clipboard image) and may delete it after the session. */
+    readonly temporary?: boolean;
+}
+/**
+ * One row of the `/model` picker (K1-U1 builds the picker, U2 supplies rows and applies the choice).
+ *
+ * @example { id: "session", tier: "session", provider: "openai", model: "gpt-6-sol", auth: "oauth", current: true }
+ */
+export interface ModelPickerEntry {
+    /** Opaque to the renderer; returned unchanged with the choice. */
+    readonly id: string;
+    readonly tier: string;
+    readonly provider: string;
+    readonly model: string;
+    /** How the route authenticates: `oauth`, `api-key`, `env`, `none`… */
+    readonly auth: string;
+    readonly current: boolean;
+    readonly description?: string;
+    /** When set, the row is shown but cannot be chosen; the text says why. */
+    readonly disabled?: string;
+    /** Replaces the `provider/model` column (the `/config` screen reuses the picker for settings). */
+    readonly label?: string;
+}
+/** Title and hint line of a picker opened for something other than models (`/config`). */
+export interface PickerHeading {
+    readonly title: string;
+    readonly hint: string;
+}
+/**
+ * Interactive-only controls of the pi-tui renderer (`TerminalRenderer.controls`). Plain and JSONL
+ * renderers leave `controls` undefined; every caller must treat it as optional.
+ */
+export interface InteractiveInputControls {
+    /** Replaces the `/` palette rows (renderer-local `/mouse`, `/select` and `/exit` stay). */
+    setCommands(entries: readonly CommandPaletteEntry[]): void;
+    /** Called when the user attaches something (before submit); submit also carries the attachments. */
+    onAttachment(listener: (attachment: Attachment) => void): () => void;
+    /** Resolves with the chosen row, or undefined on Esc / abort. */
+    openModelPicker(entries: readonly ModelPickerEntry[], signal?: AbortSignal, heading?: PickerHeading): Promise<ModelPickerEntry | undefined>;
+    /**
+     * A question that owns the input until answered (K5): with options the choice modal as a closed
+     * confirmation (arrows + Enter, number shortcuts, Esc cancels, no "Other…"), without a one-line
+     * answer field. What is typed never reaches the conversation. Resolves with the chosen option
+     * text or the answer, undefined on Esc / abort.
+     */
+    ask(question: string, options: readonly string[] | undefined, signal?: AbortSignal): Promise<string | undefined>;
+    /**
+     * The K5 choice modal: one structured question (single or multi-select, recommended tag,
+     * descriptions, "Other…" free text). Resolves undefined on Esc / abort.
+     */
+    choose(question: ChoiceQuestion, signal?: AbortSignal): Promise<ChoiceAnswer | undefined>;
+    /**
+     * Permission mode (Shift+Tab / Alt+M cycles ask -> auto -> full -> plan): the renderer shows it in
+     * the footer; the session applies the policy and announces the change.
+     */
+    readonly permissionMode: PermissionMode;
+    setPermissionMode(mode: PermissionMode): void;
+    onPermissionModeChange(listener: (mode: PermissionMode) => void): () => void;
+    /**
+     * K3/K6: live session facts for the footer, pushed whenever they change (`/model`, `/effort`,
+     * resume). `effort` undefined shows none. Optional: renderers without a footer ignore it.
+     */
+    setSessionStatus?(status: SessionStatusView): void;
+    /** K3 `/rewind`: puts text back into the editor (replacing what is there) for the user to edit and send. */
+    setEditorText?(text: string): void;
+    /**
+     * K3: when the user last pressed a key in the editor and whether it holds a draft. A prompt from a
+     * background worker waits for a typing pause so it never swallows keystrokes meant for the editor.
+     */
+    inputActivity?(): {
+        readonly lastKeyAtMs: number;
+        readonly draft: boolean;
+    };
+    /** SGR mouse reporting (wheel scroll, click to expand). Off by default: it disables native selection. */
+    readonly mouseMode: boolean;
+    setMouseMode(on: boolean): void;
+    /** K8 theme and welcome customization (interactive renderer with the conversation view). */
+    readonly appearance?: AppearanceControls;
+    /**
+     * Layered panels: opens `page` as a navigable overlay in place of the transcript (restored on
+     * close). Resolves when the user closes it (Esc at the root, `q`, Ctrl+C) or on abort. Optional:
+     * without it the command prints its text report.
+     */
+    openPanel?(page: PanelPage, signal?: AbortSignal): Promise<void>;
+}
+export type UserInputResult = {
+    readonly kind: "message" | "command";
+    readonly text: string;
+    readonly attachments?: readonly Attachment[];
+}
+/** `command`: the user typed /exit or /quit (K3: a background worker run is then stopped without asking). */
+ | {
+    readonly kind: "interrupt" | "exit";
+    readonly command?: boolean;
+};
+export interface UserInputSource {
+    /** Resolves with the next submitted message; Ctrl+C first cancels the active request (ADR-04). */
+    next(signal: AbortSignal): Promise<UserInputResult>;
+}
+export interface TerminalRenderer {
+    readonly kind: RendererKind;
+    start(header: SessionHeaderView): Promise<void>;
+    /** Must not block the agent: implementations queue and coalesce, bounded, and drop only deltas. */
+    render(event: RenderEvent): void;
+    readonly input: UserInputSource | undefined;
+    /** Interactive renderer only (K1-U1): palette, attachments, model picker, plan and mouse modes. */
+    readonly controls?: InteractiveInputControls;
+    readonly approvals: ApprovalBroker;
+    readonly auth: AuthInteraction;
+    stop(reason: "completed" | "error" | "signal"): Promise<void>;
+}
+export interface RendererSelectionInput {
+    readonly jsonl: boolean;
+    readonly plain: boolean;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly stdinIsTTY: boolean;
+    readonly stdoutIsTTY: boolean;
+}
+/** Mode rule from the cross-platform checklist: jsonl > plain triggers > interactive TUI. */
+export declare function selectRendererKind(input: RendererSelectionInput): RendererKind;
+export interface ColorSelectionInput {
+    readonly flag: "always" | "never" | "auto";
+    readonly config: boolean | undefined;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly streamHasColors: boolean;
+}
+/** `--color` > config > NO_COLOR (non-empty) > FORCE_COLOR > the stream's own capability. */
+export declare function selectColor(input: ColorSelectionInput): boolean;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/harness/contracts/renderer.d.ts.map

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

package/dist/harness/contracts/renderer.js

@@ -0,0 +1,36 @@
+/**
+ * The terminal port (ADR-04). Renderers only consume events; they never own task state. The
+ * interactive renderer is the only module allowed to import `@earendil-works/pi-tui`; the plain
+ * and JSONL renderers have no dependencies and are selected whenever there is no TTY.
+ */
+export const RENDERER_KINDS = ["tui", "plain", "jsonl"];
+export const ATTACHMENT_KINDS = ["file", "directory", "image"];
+/** Mode rule from the cross-platform checklist: jsonl > plain triggers > interactive TUI. */
+export function selectRendererKind(input) {
+    if (input.jsonl)
+        return "jsonl";
+    const plainEnv = input.env.SYN_PLAIN;
+    if (input.plain ||
+        (plainEnv !== undefined && plainEnv !== "" && plainEnv !== "0") ||
+        input.env.TERM === "dumb" ||
+        !input.stdinIsTTY ||
+        !input.stdoutIsTTY) {
+        return "plain";
+    }
+    return "tui";
+}
+/** `--color` > config > NO_COLOR (non-empty) > FORCE_COLOR > the stream's own capability. */
+export function selectColor(input) {
+    if (input.flag !== "auto")
+        return input.flag === "always";
+    if (input.config !== undefined)
+        return input.config;
+    const noColor = input.env.NO_COLOR;
+    if (noColor !== undefined && noColor !== "")
+        return false;
+    const force = input.env.FORCE_COLOR;
+    if (force !== undefined)
+        return force !== "0" && force !== "false";
+    return input.streamHasColors;
+}
+//# sourceMappingURL=renderer.js.map

package/dist/harness/contracts/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../../src/harness/contracts/renderer.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAsHjE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,CAAU,CAAC;AA8IxE,6FAA6F;AAC7F,MAAM,UAAU,kBAAkB,CAAC,KAA6B;IAC9D,IAAI,KAAK,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;IACrC,IACE,KAAK,CAAC,KAAK;QACX,CAAC,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,IAAI,QAAQ,KAAK,GAAG,CAAC;QAC/D,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM;QACzB,CAAC,KAAK,CAAC,UAAU;QACjB,CAAC,KAAK,CAAC,WAAW,EAClB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AASD,6FAA6F;AAC7F,MAAM,UAAU,WAAW,CAAC,KAA0B;IACpD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;IAC1D,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IACpD,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;IACnC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC;IACpC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,OAAO,CAAC;IACnE,OAAO,KAAK,CAAC,eAAe,CAAC;AAC/B,CAAC"}

package/dist/harness/contracts/roles.d.ts

@@ -0,0 +1,28 @@
+import { type WorkerRole } from "./common.ts";
+/**
+ * What each worker role can actually do in the harness, stated once so the planner, plan
+ * validation and the orchestrator's instructions agree with the policy engine
+ * (`ROLE_EFFECT_CEILINGS`, the exec allowlist and tool visibility; a test keeps them in sync).
+ * This table describes authority; it never grants any: the policy engine decides every call.
+ */
+/**
+ * - `none`: no command execution at all (the `exec` tool is not even offered).
+ * - `verification-and-read-only`: the task's exact verification commands plus the read-only list
+ *   (non-mutating git, listing, viewing, `rg`/`grep`).
+ * - `verification-and-build`: the above plus the vetted build/test list (or anything a full OS
+ *   sandbox confines).
+ */
+export type CommandCapability = "none" | "verification-and-read-only" | "verification-and-build";
+export interface RoleCapability {
+    readonly writes: "never" | "owned-paths" | "only-with-owned-paths";
+    /** Command capability of the role (for a debugger: without owned paths, i.e. rca-only). */
+    readonly commands: CommandCapability;
+    readonly summary: string;
+}
+export declare const ROLE_CAPABILITIES: {
+    readonly [R in WorkerRole]: RoleCapability;
+};
+export declare function canRunCommands(role: WorkerRole): boolean;
+/** The concise table the orchestrator plans with. */
+export declare function renderRoleCapabilityTable(): string;
+//# sourceMappingURL=roles.d.ts.map

package/dist/harness/contracts/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../../src/harness/contracts/roles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,4BAA4B,GAAG,wBAAwB,CAAC;AAEjG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,GAAG,uBAAuB,CAAC;IACnE,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,iBAAiB,EAAE;IAAE,QAAQ,EAAE,CAAC,IAAI,UAAU,GAAG,cAAc;CAwB3E,CAAC;AAEF,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAExD;AAED,qDAAqD;AACrD,wBAAgB,yBAAyB,IAAI,MAAM,CAOlD"}

package/dist/harness/contracts/roles.js

@@ -0,0 +1,36 @@
+import { WORKER_ROLES } from "./common.js";
+export const ROLE_CAPABILITIES = {
+    explorer: {
+        writes: "never",
+        commands: "none",
+        summary: "reads and searches inside its read_paths; runs NO commands (no exec tool): its verification must be empty and every acceptance criterion must be satisfiable by reading files",
+    },
+    implementer: {
+        writes: "owned-paths",
+        commands: "verification-and-build",
+        summary: "changes only its owned_paths in an isolated workspace; runs its exact verification commands and vetted build/test commands",
+    },
+    debugger: {
+        writes: "only-with-owned-paths",
+        commands: "verification-and-read-only",
+        summary: "root-cause analysis; without owned_paths it changes nothing and runs only its exact verification commands and read-only commands; with owned_paths it may fix like an implementer",
+    },
+    reviewer: {
+        writes: "never",
+        commands: "verification-and-read-only",
+        summary: "configures the mandatory independent review of the standard/high-risk tasks it depends on (reviewer tier, extra criteria, extra verification); it never changes files and runs no attempt of its own",
+    },
+};
+export function canRunCommands(role) {
+    return ROLE_CAPABILITIES[role].commands !== "none";
+}
+/** The concise table the orchestrator plans with. */
+export function renderRoleCapabilityTable() {
+    return [
+        "Worker role capabilities (enforced by the harness policy; plans that ignore them are rejected):",
+        ...WORKER_ROLES.map((role) => `- ${role}: ${ROLE_CAPABILITIES[role].summary}.`),
+        "Put every command that must run (tests, `node check.mjs`, builds) in the verification of a task whose role can run it, usually the implementer that owns the change.",
+        "The harness runs each verification command itself as a plain argv under the task's policy, and plan_propose dry-runs them: no shell syntax (quoted code, pipes, redirects, &&, VAR=value) and no inline interpreter code (`node -e`, `python -c`, `sh -c`); to check behaviour, let the implementer own a small check script and verify with `node check-x.mjs`, or use the project's test runner.",
+    ].join("\n");
+}
+//# sourceMappingURL=roles.js.map

package/dist/harness/contracts/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../../src/harness/contracts/roles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AAyB5D,MAAM,CAAC,MAAM,iBAAiB,GAAmD;IAC/E,QAAQ,EAAE;QACR,MAAM,EAAE,OAAO;QACf,QAAQ,EAAE,MAAM;QAChB,OAAO,EACL,+KAA+K;KAClL;IACD,WAAW,EAAE;QACX,MAAM,EAAE,aAAa;QACrB,QAAQ,EAAE,wBAAwB;QAClC,OAAO,EAAE,4HAA4H;KACtI;IACD,QAAQ,EAAE;QACR,MAAM,EAAE,uBAAuB;QAC/B,QAAQ,EAAE,4BAA4B;QACtC,OAAO,EACL,mLAAmL;KACtL;IACD,QAAQ,EAAE;QACR,MAAM,EAAE,OAAO;QACf,QAAQ,EAAE,4BAA4B;QACtC,OAAO,EACL,sMAAsM;KACzM;CACF,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,IAAgB;IAC7C,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,QAAQ,KAAK,MAAM,CAAC;AACrD,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,iGAAiG;QACjG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,KAAK,iBAAiB,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,CAAC;QAC/E,sKAAsK;QACtK,oYAAoY;KACrY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}