@coldtea/pr-lens-cli 0.1.3 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ npx @coldtea/pr-lens-cli analyze --base origin/main
 
 ## Bring your own key
 
-Only `analyze` talks to a model; `render`, `comment`, `validate` and `export` never do. Its key is read from the environment, never from a flag: a flag lands in shell history and in the log of whatever CI runs it. The diff goes to the provider you name and nowhere else: there is no PR Lens service in this path.
+Only `analyze` talks to a model; `render`, `comment`, `validate`, `export` and `canvas` never do. Its key is read from the environment, never from a flag: a flag lands in shell history and in the log of whatever CI runs it. The diff goes to the provider you name and nowhere else: there is no PR Lens service in this path.
 
 ```bash
 export GEMINI_API_KEY=…      # Gemini is the default, not a requirement
@@ -19,10 +19,10 @@ pr-lens analyze --base origin/main --head HEAD
 
 Three request shapes are implemented rather than a list of vendors:
 
-| `--provider` | Endpoint | Key |
-| --- | --- | --- |
-| `gemini` (default) | Google's own API | `GEMINI_API_KEY` |
-| `openai` | OpenAI's own API | `OPENAI_API_KEY` |
+| `--provider`        | Endpoint                                                          | Key              |
+| ------------------- | ----------------------------------------------------------------- | ---------------- |
+| `gemini` (default)  | Google's own API                                                  | `GEMINI_API_KEY` |
+| `openai`            | OpenAI's own API                                                  | `OPENAI_API_KEY` |
 | `openai-compatible` | anything else speaking `/chat/completions`, named by `--base-url` | `OPENAI_API_KEY` |
 
 DeepSeek, Anthropic's compatibility endpoint, OpenRouter, Ollama and llama.cpp are all reached by pointing `--base-url` at them, and a new vendor needs no release here. OpenAI is listed separately from the servers that copied it because the two have drifted: it renamed the output limit to `max_completion_tokens` and its newer models reject `max_tokens`, which is the only spelling the others know. There is no field both accept, so you say which endpoint you are talking to rather than the CLI guessing from a hostname.
@@ -43,6 +43,8 @@ None of it is meant to be committed. The SVGs, the document and the manifest are
 
 `--out` overrides the location on every command that writes. Point it somewhere else and PR Lens leaves your `.gitignore` alone: that directory is yours to decide about.
 
+`canvas` keeps one more file there, `.pr-lens/canvas.json`, which holds the write token for every canvas this checkout has pushed. It is the one file in the directory that cannot be rebuilt, and a bigger reason the directory is ignored.
+
 ## The commands
 
 ### `analyze`
@@ -69,7 +71,7 @@ pr-lens render .pr-lens/graph.json
 
 Draws the document as self-contained light and dark SVGs (one pair per drill-down section per lens, or one pair per lens when the document has no sections), and writes two files beside them: `manifest.json`, which says what was drawn and under which file name, and `drawn.graph.json`, the document those pictures actually show.
 
-Both matter to what comes next. The manifest is where `comment` gets its file names, so neither command re-derives the other's. And `drawn.graph.json` exists because this is where corrections are applied: excluding a node can empty out a whole drill-down section, and the renderer then draws no picture for it. A comment composed from the document that went *in* would announce a section that came out of nothing.
+Both matter to what comes next. The manifest is where `comment` gets its file names, so neither command re-derives the other's. And `drawn.graph.json` exists because this is where corrections are applied: excluding a node can empty out a whole drill-down section, and the renderer then draws no picture for it. A comment composed from the document that went _in_ would announce a section that came out of nothing.
 
 The SVGs carry no script and no external reference, and the same document renders to the same bytes every time. `--theme light` or `--theme dark` draws one half of the pair.
 
@@ -100,6 +102,34 @@ Turns a pull-request document into the map of the system once that pull request
 
 The map is a snapshot, not a source of truth. Nothing reads it back into the pipeline: a committed map that overrode inference would be hand-maintained rot with merge conflicts attached. Commit it so a repository has something to read, to diff, and to hand an agent.
 
+### `canvas`
+
+```bash
+pr-lens canvas push
+```
+
+Puts the document on prlens.dev as a canvas: a page anyone with the link can read, and an SVG a README can embed.
+
+`push` sends the JSON document, never an SVG; the app draws it. The default is `.pr-lens/drawn.graph.json`, the document `render` drew, so what the page shows is what the diagrams show. The first push of a file mints a canvas and every push after that updates the same one, matched by the path it came from. `--canvas <id|name>` picks a different one and `--name` says what to call a new one; the document's title is the default. It prints three links:
+
+```
+✓ https://prlens.dev/c/{id} — rev 1 · 4 diagrams
+  edit link, keep it to yourself: https://prlens.dev/c/{id}#w=…
+  README embed: https://prlens.dev/c/{id}.svg
+```
+
+The view link is the one to share. The edit link is the same page with the write token in the fragment, and anyone holding it can push over your canvas, so it stays with you. The embed is the hero diagram as an SVG, for a README or a wiki.
+
+`pull` fetches the document back, by the view link or the bare id, into `.pr-lens/graph.json` unless `-o` says otherwise, and records the revision. Pull the edit link, the one ending in `#w=…`, and its token is recorded too: that is how a fresh checkout, or one that lost `.pr-lens/canvas.json`, gets the canvas back. A push carries the revision it last saw, and one that has been overtaken is refused rather than applied: pull, then push again.
+
+`rotate` mints a new write token and retires the old one. Use it when an edit link has leaked. The CLI saves the new token before it sends the request, so if the connection drops, the next command finishes the rotation instead of losing the token. The token lives in `.pr-lens/canvas.json`, keyed by canvas id, and git ignores it. Lose that file and the canvas is still readable by everyone; pushing to it again needs the token, which the edit link still carries.
+
+Registry writes take a lock at `.pr-lens/canvas.json.lock`. The CLI never removes another command's lock. If a command dies and leaves one behind, the error names its process id and you remove the file yourself.
+
+The CLI refuses to write the registry where git could commit it. If a checkout tracks `.pr-lens/canvas.json` or un-ignores `.pr-lens/`, the command fails with `CANVAS_REGISTRY_EXPOSED` and writes nothing.
+
+`--api` points at another PR Lens app, or set `PR_LENS_API_URL`.
+
 ## Corrections
 
 A repository's `.github/pr-lens.yml` is picked up automatically by `render` and applied at draw time: renames, exclusions, lane pins, groupings. It is an overlay: inference never writes back into it, so a correction keeps holding as the code moves and the model renames things between runs, and the document on disk stays the record of what was inferred.
@@ -120,7 +150,7 @@ A lane pin may name a lane the document never declared; the band is created and
 
 ## Failures
 
-Every failure carries a code, so a script can branch on it: `USAGE`, `UNREADABLE_FILE`, `UNKNOWN_DOCUMENT`, `INVALID_DOCUMENT`, `GIT_FAILED`, `EMPTY_DIFF`, `REPOSITORY_UNKNOWN`, `MISSING_API_KEY`, `PROVIDER_FAILED`, `MODEL_OUTPUT_INVALID`, `RENDER_FAILED`. Misuse exits 2, everything else exits 1.
+Every failure carries a code, so a script can branch on it: `USAGE`, `UNREADABLE_FILE`, `UNKNOWN_DOCUMENT`, `INVALID_DOCUMENT`, `GIT_FAILED`, `EMPTY_DIFF`, `REPOSITORY_UNKNOWN`, `MISSING_API_KEY`, `PROVIDER_FAILED`, `MODEL_OUTPUT_INVALID`, `RENDER_FAILED`, and for `canvas`: `CANVAS_UNREGISTERED`, `CANVAS_UNKNOWN`, `CANVAS_CONFLICT`, `CANVAS_REJECTED`, `CANVAS_RATE_LIMITED`, `CANVAS_UNAVAILABLE`, `CANVAS_REGISTRY_EXPOSED`. Misuse exits 2, everything else exits 1.
 
 ---
 

package/dist/canvas/api.d.ts

@@ -0,0 +1,65 @@
+import { type GraphDoc } from "@coldtea/pr-lens-schema";
+import { z } from "zod";
+declare const Minted: z.ZodObject<{
+    id: z.ZodString;
+    writeToken: z.ZodString;
+    rev: z.ZodNumber;
+    viewUrl: z.ZodString;
+    editUrl: z.ZodString;
+    embedUrl: z.ZodString;
+}, z.core.$strip>;
+declare const Fetched: z.ZodObject<{
+    id: z.ZodString;
+    rev: z.ZodNumber;
+    viewUrl: z.ZodString;
+    embedUrl: z.ZodString;
+    document: z.ZodUnknown;
+    tiles: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        lens: z.ZodString;
+        crumbs: z.ZodArray<z.ZodString>;
+        hero: z.ZodBoolean;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        renders: z.ZodRecord<z.ZodString, z.ZodString>;
+        images: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const Pushed: z.ZodObject<{
+    id: z.ZodString;
+    rev: z.ZodNumber;
+    viewUrl: z.ZodString;
+    editUrl: z.ZodString;
+    embedUrl: z.ZodString;
+    tiles: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        lens: z.ZodString;
+        crumbs: z.ZodArray<z.ZodString>;
+        hero: z.ZodBoolean;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        renders: z.ZodRecord<z.ZodString, z.ZodString>;
+        images: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const Rotated: z.ZodObject<{
+    id: z.ZodString;
+    editUrl: z.ZodString;
+}, z.core.$strip>;
+export type Minted = z.infer<typeof Minted>;
+export type Pushed = z.infer<typeof Pushed>;
+export type Rotated = z.infer<typeof Rotated>;
+export type Fetched = Omit<z.infer<typeof Fetched>, "document"> & {
+    document: GraphDoc;
+};
+export declare const mintCanvas: (api: string) => Promise<Minted>;
+export declare const fetchCanvas: (api: string, id: string) => Promise<Fetched>;
+export declare const pushCanvas: (api: string, id: string, token: string, rev: number, document: GraphDoc) => Promise<Pushed>;
+/** A rotation onto itself changes nothing and is answered "rotated" only for the current token. */
+export declare const verifyWriteToken: (api: string, id: string, token: string) => Promise<boolean>;
+/** The caller mints the next token, so a lost answer can be asked for again. */
+export declare const rotateCanvas: (api: string, id: string, token: string, nextToken: string) => Promise<Rotated>;
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dist/canvas/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/canvas/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,QAAA,MAAM,MAAM;;;;;;;iBAOV,CAAC;AAEH,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;;iBAOX,CAAC;AAEH,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;iBAOV,CAAC;AAEH,QAAA,MAAM,OAAO;;;iBAAoD,CAAC;AAElE,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAC5C,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAC5C,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,CAAC;AAC9C,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,EAAE,UAAU,CAAC,GAAG;IAChE,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC;AAkLF,eAAO,MAAM,UAAU,QAAS,MAAM,KAAG,OAAO,CAAC,MAAM,CACwB,CAAC;AAEhF,eAAO,MAAM,WAAW,QACjB,MAAM,MACP,MAAM,KACT,OAAO,CAAC,OAAO,CAgBjB,CAAC;AAEF,eAAO,MAAM,UAAU,QAChB,MAAM,MACP,MAAM,SACH,MAAM,OACR,MAAM,YACD,QAAQ,KACjB,OAAO,CAAC,MAAM,CAYd,CAAC;AAEJ,mGAAmG;AACnG,eAAO,MAAM,gBAAgB,QACtB,MAAM,MACP,MAAM,SACH,MAAM,KACZ,OAAO,CAAC,OAAO,CAQf,CAAC;AAEJ,gFAAgF;AAChF,eAAO,MAAM,YAAY,QAClB,MAAM,MACP,MAAM,SACH,MAAM,aACF,MAAM,KAChB,OAAO,CAAC,OAAO,CAWf,CAAC"}

package/dist/canvas/api.js

@@ -0,0 +1,175 @@
+import { assertNever, safeParseGraphDoc, } from "@coldtea/pr-lens-schema";
+import { z } from "zod";
+import { PrLensCliError } from "../errors.js";
+import { CLI_VERSION } from "../version.js";
+const REQUEST_TIMEOUT_MS = 60_000;
+const Tile = z.object({
+    id: z.string(),
+    title: z.string(),
+    lens: z.string(),
+    crumbs: z.array(z.string()),
+    hero: z.boolean(),
+    width: z.number(),
+    height: z.number(),
+    renders: z.record(z.string(), z.string()),
+    images: z.record(z.string(), z.string()),
+});
+const Minted = z.object({
+    id: z.string(),
+    writeToken: z.string(),
+    rev: z.number().int(),
+    viewUrl: z.string(),
+    editUrl: z.string(),
+    embedUrl: z.string(),
+});
+const Fetched = z.object({
+    id: z.string(),
+    rev: z.number().int(),
+    viewUrl: z.string(),
+    embedUrl: z.string(),
+    document: z.unknown(),
+    tiles: z.array(Tile),
+});
+const Pushed = z.object({
+    id: z.string(),
+    rev: z.number().int(),
+    viewUrl: z.string(),
+    editUrl: z.string(),
+    embedUrl: z.string(),
+    tiles: z.array(Tile),
+});
+const Rotated = z.object({ id: z.string(), editUrl: z.string() });
+/** Loose inner object: an unknown code must still reach the refusal below. */
+const Envelope = z.object({
+    error: z.looseObject({ code: z.string(), message: z.string() }),
+});
+const Refusal = z.discriminatedUnion("code", [
+    z.object({ code: z.literal("NOT_FOUND"), message: z.string() }),
+    z.object({ code: z.literal("INVALID_REQUEST"), message: z.string() }),
+    z.object({
+        code: z.literal("INVALID_DOCUMENT"),
+        message: z.string(),
+        issues: z.array(z.object({ code: z.string(), path: z.string(), message: z.string() })),
+    }),
+    z.object({ code: z.literal("CANNOT_DRAW"), message: z.string() }),
+    z.object({
+        code: z.literal("REVISION_MOVED"),
+        message: z.string(),
+        rev: z.number().int(),
+    }),
+    z.object({
+        code: z.literal("RATE_LIMITED"),
+        message: z.string(),
+        retryAt: z.string(),
+    }),
+    z.object({ code: z.literal("TOO_LARGE"), message: z.string() }),
+]);
+const hostOf = (api) => new URL(api).host;
+const unavailable = (api, status, details) => new PrLensCliError("CANVAS_UNAVAILABLE", status === undefined
+    ? `${hostOf(api)} did not answer`
+    : `${hostOf(api)} answered ${status}`, details);
+const parseJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const refusal = (api, request, status, body) => {
+    const envelope = Envelope.safeParse(body);
+    if (!envelope.success)
+        return unavailable(api, status);
+    const known = Refusal.safeParse(envelope.data.error);
+    if (!known.success)
+        return unavailable(api, status, envelope.data.error.message);
+    const error = known.data;
+    switch (error.code) {
+        case "NOT_FOUND":
+            return request.canvas === undefined
+                ? unavailable(api, status, error.message)
+                : new PrLensCliError("CANVAS_UNKNOWN", `no canvas ${request.canvas} at ${hostOf(api)}, or the token is wrong`, "if the token was rotated elsewhere, pull the current edit link to record it");
+        case "REVISION_MOVED":
+            return new PrLensCliError("CANVAS_CONFLICT", `${request.canvas ?? "the canvas"} is at rev ${error.rev} on ${hostOf(api)}, not rev ${request.ifMatch ?? "?"}`, "pr-lens canvas pull, then push again");
+        case "INVALID_DOCUMENT":
+            return new PrLensCliError("CANVAS_REJECTED", error.message, error.issues
+                .map((issue) => issue.path === ""
+                ? issue.message
+                : `${issue.path}: ${issue.message}`)
+                .join("\n"));
+        case "CANNOT_DRAW":
+            // Passed the contract but nothing to draw; the app's message says why.
+            return new PrLensCliError("CANVAS_REJECTED", error.message);
+        case "RATE_LIMITED":
+            return new PrLensCliError("CANVAS_RATE_LIMITED", `${hostOf(api)} is rate limiting this client until ${error.retryAt}`, error.message);
+        case "INVALID_REQUEST":
+        case "TOO_LARGE":
+            return unavailable(api, status, error.message);
+        default:
+            return assertNever(error, "Unhandled canvas refusal");
+    }
+};
+const call = async (api, request, schema) => {
+    const headers = {
+        accept: "application/json",
+        "user-agent": `pr-lens-cli/${CLI_VERSION}`,
+    };
+    if (request.token !== undefined)
+        headers.authorization = `Bearer ${request.token}`;
+    if (request.ifMatch !== undefined)
+        headers["if-match"] = String(request.ifMatch);
+    if (request.body !== undefined)
+        headers["content-type"] = "application/json";
+    const response = await fetch(`${api}${request.path}`, {
+        method: request.method,
+        headers,
+        body: request.body === undefined ? undefined : JSON.stringify(request.body),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }).catch(() => {
+        // The runtime's message names addresses and internals; keep it out.
+        throw unavailable(api, undefined, "check the address and the connection, then try again");
+    });
+    // A body can fail after the headers arrived.
+    const text = await response.text().catch(() => {
+        throw unavailable(api, response.status, "the answer was cut off; check the connection, then try again");
+    });
+    const body = parseJson(text);
+    if (!response.ok)
+        throw refusal(api, request, response.status, body);
+    const parsed = schema.safeParse(body);
+    if (!parsed.success)
+        throw unavailable(api, response.status, "the answer was not in the shape the canvas API documents");
+    return parsed.data;
+};
+const canvasPath = (id) => `/api/canvas/${id}`;
+export const mintCanvas = (api) => call(api, { method: "POST", path: "/api/canvas", canvas: undefined }, Minted);
+export const fetchCanvas = async (api, id) => {
+    const fetched = await call(api, { method: "GET", path: canvasPath(id), canvas: id }, Fetched);
+    const document = safeParseGraphDoc(fetched.document);
+    if (!document.ok)
+        throw new PrLensCliError("CANVAS_UNAVAILABLE", `${hostOf(api)} serves a document for ${id} that this CLI cannot read [${document.error.code}]`, "a newer CLI may know the shape: npx @coldtea/pr-lens-cli@latest");
+    return { ...fetched, document: document.value };
+};
+export const pushCanvas = (api, id, token, rev, document) => call(api, {
+    method: "PUT",
+    path: canvasPath(id),
+    canvas: id,
+    token,
+    ifMatch: rev,
+    body: document,
+}, Pushed);
+/** A rotation onto itself changes nothing and is answered "rotated" only for the current token. */
+export const verifyWriteToken = (api, id, token) => rotateCanvas(api, id, token, token).then(() => true, (error) => {
+    if (error instanceof PrLensCliError && error.code === "CANVAS_UNKNOWN")
+        return false;
+    throw error;
+});
+/** The caller mints the next token, so a lost answer can be asked for again. */
+export const rotateCanvas = (api, id, token, nextToken) => call(api, {
+    method: "POST",
+    path: `${canvasPath(id)}/rotate`,
+    canvas: id,
+    token,
+    body: { writeToken: nextToken },
+}, Rotated);
+//# sourceMappingURL=api.js.map

package/dist/canvas/api.js.map

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

package/dist/canvas/registry.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { Terminal } from "../terminal.js";
+/** Holds write tokens, the one thing here nothing can rebuild. */
+export declare const REGISTRY_PATH: string;
+export declare const isCanvasId: (value: string) => boolean;
+export declare const mintWriteToken: () => string;
+declare const Entry: z.ZodObject<{
+    name: z.ZodString;
+    source: z.ZodString;
+    api: z.ZodString;
+    writeToken: z.ZodOptional<z.ZodString>;
+    pending: z.ZodOptional<z.ZodString>;
+    rev: z.ZodNumber;
+}, z.core.$strip>;
+declare const Registry: z.ZodObject<{
+    canvases: z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        source: z.ZodString;
+        api: z.ZodString;
+        writeToken: z.ZodOptional<z.ZodString>;
+        pending: z.ZodOptional<z.ZodString>;
+        rev: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CanvasEntry = z.infer<typeof Entry>;
+export type CanvasRegistry = z.infer<typeof Registry>;
+export type Registered = {
+    id: string;
+    entry: CanvasEntry;
+};
+export declare const readRegistry: () => Promise<CanvasRegistry>;
+/** Asked before a canvas is minted, so a refusal costs nothing on the app. */
+export declare const ensureRegistryHome: (terminal: Terminal) => Promise<void>;
+/** Compared case-blind and by inode: macOS ignores case, and a link is the same file. */
+export declare const isReservedRegistryTarget: (path: string) => Promise<boolean>;
+export declare const writeRegistry: (registry: CanvasRegistry, terminal: Terminal) => Promise<void>;
+/** Two commands writing the whole file at once would each keep only their own change. */
+export declare const withRegistryLock: <T>(work: () => Promise<T>) => Promise<T>;
+export declare const updateRegistry: (change: (registry: CanvasRegistry) => void, terminal: Terminal) => Promise<CanvasRegistry>;
+export declare const sourceKey: (path: string) => string;
+export declare const findCanvas: (registry: CanvasRegistry, ref: string) => Registered;
+export declare const findBySource: (registry: CanvasRegistry, path: string) => Registered | undefined;
+export declare const onlyCanvas: (registry: CanvasRegistry) => Registered;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/canvas/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/canvas/registry.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAK/C,kEAAkE;AAClE,eAAO,MAAM,aAAa,QAAqC,CAAC;AAMhE,eAAO,MAAM,UAAU,UAAW,MAAM,KAAG,OAAgC,CAAC;AAE5E,eAAO,MAAM,cAAc,QAAO,MACK,CAAC;AAExC,QAAA,MAAM,KAAK;;;;;;;iBAUT,CAAC;AAEH,QAAA,MAAM,QAAQ;;;;;;;;;iBAEZ,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AACtD,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAQ5D,eAAO,MAAM,YAAY,QAAa,OAAO,CAAC,cAAc,CAc3D,CAAC;AAkGF,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,aAAoB,QAAQ,KAAG,OAAO,CAAC,IAAI,CAGzE,CAAC;AAWF,yFAAyF;AACzF,eAAO,MAAM,wBAAwB,SAC7B,MAAM,KACX,OAAO,CAAC,OAAO,CA6BjB,CAAC;AAEF,eAAO,MAAM,aAAa,aACd,cAAc,YACd,QAAQ,KACjB,OAAO,CAAC,IAAI,CAGd,CAAC;AAyHF,yFAAyF;AACzF,eAAO,MAAM,gBAAgB,GAAU,CAAC,QAChC,MAAM,OAAO,CAAC,CAAC,CAAC,KACrB,OAAO,CAAC,CAAC,CAwCX,CAAC;AAEF,eAAO,MAAM,cAAc,WACjB,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,YAChC,QAAQ,KACjB,OAAO,CAAC,cAAc,CAMrB,CAAC;AAEL,eAAO,MAAM,SAAS,SAAU,MAAM,KAAG,MACD,CAAC;AAUzC,eAAO,MAAM,UAAU,aACX,cAAc,OACnB,MAAM,KACV,UAoBF,CAAC;AAEF,eAAO,MAAM,YAAY,aACb,cAAc,QAClB,MAAM,KACX,UAAU,GAAG,SAaf,CAAC;AAEF,eAAO,MAAM,UAAU,aAAc,cAAc,KAAG,UAiBrD,CAAC"}