@deskwork/studio 0.9.5

package/dist/build-client-assets.d.ts

@@ -0,0 +1,51 @@
+/**
+ * On-startup esbuild for studio client modules.
+ *
+ * Phase 23e — the studio's HTTP listener calls
+ * `buildClientAssets({ pluginRoot })` once during boot, BEFORE accepting
+ * requests. The result of the build lands in
+ * `<pluginRoot>/.runtime-cache/dist/<name>.js`, mirroring what `build.ts`
+ * used to commit into `<pluginRoot>/public/dist/`. The `/static/dist/*`
+ * route serves from the runtime cache; URL surface is unchanged.
+ *
+ * Cache strategy: per-entry mtime check. For each `<name>.ts` under
+ * `<pluginRoot>/public/src/`, compare the source's mtime (and every
+ * file imported transitively, via esbuild's `metafile`) against the
+ * cached `<name>.js`. If the cache is newer than every input, skip the
+ * rebuild. Otherwise rebuild that single entry. Warm boots therefore
+ * avoid esbuild work entirely once `.runtime-cache/dist/` is populated.
+ *
+ * Concurrency safety (Issue #77):
+ *   1. Per-entry directory lock (`<outFile>.lock/`) serializes
+ *      concurrent rebuilds across processes. mkdir is atomic on POSIX;
+ *      the loser polls until the holder finishes (or the lock is
+ *      deemed stale) and then re-checks the cache so it can skip the
+ *      rebuild entirely if the holder produced a valid output.
+ *   2. Atomic writes: esbuild writes to `<outFile>.tmp.<pid>.<rand>`
+ *      and we `rename()` to `<outFile>` once the build succeeds. The
+ *      sidecar metafile follows the same `tmp + rename` pattern. A
+ *      kill mid-build leaves either the prior valid output OR no
+ *      output — never a half-written file.
+ *   3. Self-healing metafile reads: a missing/malformed sidecar is
+ *      treated the same as "no metafile" — rebuild the entry. This
+ *      prevents a corrupt sidecar from wedging boot.
+ *
+ * Failures throw with descriptive messages (per project rules — no
+ * silent fallbacks). The caller logs a status line.
+ */
+export interface BuildClientAssetsOptions {
+    /** Absolute path to plugins/deskwork-studio/. */
+    readonly pluginRoot: string;
+}
+export interface BuildSummary {
+    /** Number of entries that were re-bundled this run. */
+    readonly entriesBuilt: number;
+    /** Number of entries served from the existing cache. */
+    readonly entriesCached: number;
+    /** Total bytes across all output files (built + cached). */
+    readonly totalBytes: number;
+    /** Absolute output directory (`<pluginRoot>/.runtime-cache/dist/`). */
+    readonly outDir: string;
+}
+export declare function buildClientAssets(opts: BuildClientAssetsOptions): Promise<BuildSummary>;
+//# sourceMappingURL=build-client-assets.d.ts.map

package/dist/build-client-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-client-assets.d.ts","sourceRoot":"","sources":["../src/build-client-assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAOH,MAAM,WAAW,wBAAwB;IACvC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAiBD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAgCvB"}

package/dist/build-client-assets.js

@@ -0,0 +1,341 @@
+/**
+ * On-startup esbuild for studio client modules.
+ *
+ * Phase 23e — the studio's HTTP listener calls
+ * `buildClientAssets({ pluginRoot })` once during boot, BEFORE accepting
+ * requests. The result of the build lands in
+ * `<pluginRoot>/.runtime-cache/dist/<name>.js`, mirroring what `build.ts`
+ * used to commit into `<pluginRoot>/public/dist/`. The `/static/dist/*`
+ * route serves from the runtime cache; URL surface is unchanged.
+ *
+ * Cache strategy: per-entry mtime check. For each `<name>.ts` under
+ * `<pluginRoot>/public/src/`, compare the source's mtime (and every
+ * file imported transitively, via esbuild's `metafile`) against the
+ * cached `<name>.js`. If the cache is newer than every input, skip the
+ * rebuild. Otherwise rebuild that single entry. Warm boots therefore
+ * avoid esbuild work entirely once `.runtime-cache/dist/` is populated.
+ *
+ * Concurrency safety (Issue #77):
+ *   1. Per-entry directory lock (`<outFile>.lock/`) serializes
+ *      concurrent rebuilds across processes. mkdir is atomic on POSIX;
+ *      the loser polls until the holder finishes (or the lock is
+ *      deemed stale) and then re-checks the cache so it can skip the
+ *      rebuild entirely if the holder produced a valid output.
+ *   2. Atomic writes: esbuild writes to `<outFile>.tmp.<pid>.<rand>`
+ *      and we `rename()` to `<outFile>` once the build succeeds. The
+ *      sidecar metafile follows the same `tmp + rename` pattern. A
+ *      kill mid-build leaves either the prior valid output OR no
+ *      output — never a half-written file.
+ *   3. Self-healing metafile reads: a missing/malformed sidecar is
+ *      treated the same as "no metafile" — rebuild the entry. This
+ *      prevents a corrupt sidecar from wedging boot.
+ *
+ * Failures throw with descriptive messages (per project rules — no
+ * silent fallbacks). The caller logs a status line.
+ */
+import { build } from 'esbuild';
+import { mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { join, resolve } from 'node:path';
+const CACHE_DIR_NAME = '.runtime-cache';
+const CACHE_OUT_SUBDIR = 'dist';
+const LOCK_WAIT_MS = 30_000;
+const LOCK_POLL_INITIAL_MS = 50;
+const LOCK_POLL_MAX_MS = 500;
+const LOCK_STALE_MS = 60_000;
+export async function buildClientAssets(opts) {
+    const srcDir = resolve(opts.pluginRoot, 'public', 'src');
+    const outDir = resolve(opts.pluginRoot, CACHE_DIR_NAME, CACHE_OUT_SUBDIR);
+    const entries = await findEntries(srcDir);
+    if (entries.length === 0) {
+        throw new Error(`deskwork-studio: no .ts entries found in ${srcDir}; cannot build client assets`);
+    }
+    await mkdir(outDir, { recursive: true });
+    let entriesBuilt = 0;
+    let entriesCached = 0;
+    let totalBytes = 0;
+    for (const entryPath of entries) {
+        const decision = await decideEntry(entryPath, srcDir, outDir);
+        if (decision.rebuild) {
+            const result = await rebuildEntryWithLock(decision, srcDir, outDir);
+            totalBytes += result.bytes;
+            if (result.didBuild)
+                entriesBuilt += 1;
+            else
+                entriesCached += 1;
+        }
+        else {
+            const cachedStat = await stat(decision.outFile);
+            totalBytes += cachedStat.size;
+            entriesCached += 1;
+        }
+    }
+    return { entriesBuilt, entriesCached, totalBytes, outDir };
+}
+async function findEntries(dir) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`deskwork-studio: cannot read client source dir ${dir}: ${reason}`);
+    }
+    const entries = [];
+    for (const name of names) {
+        if (!name.endsWith('.ts'))
+            continue;
+        const full = join(dir, name);
+        const info = await stat(full);
+        if (info.isFile())
+            entries.push(full);
+    }
+    entries.sort();
+    return entries;
+}
+async function decideEntry(entryPath, srcDir, outDir) {
+    const baseName = entryPath.slice(srcDir.length + 1).replace(/\.ts$/, '.js');
+    const outFile = join(outDir, baseName);
+    const cachedMtime = await safeMtime(outFile);
+    if (cachedMtime === null) {
+        return { entryPath, outFile, baseName, rebuild: true };
+    }
+    // First-pass cheap check: compare against just the entry's own mtime.
+    // If the entry source itself is newer than the cache, rebuild without
+    // bothering to walk imports. If not, fall through to the metafile-based
+    // transitive check (also handles imported-file edits).
+    const entryMtime = await safeMtime(entryPath);
+    if (entryMtime === null) {
+        throw new Error(`deskwork-studio: client entry vanished between readdir and stat: ${entryPath}`);
+    }
+    if (entryMtime > cachedMtime) {
+        return { entryPath, outFile, baseName, rebuild: true };
+    }
+    // Cache is at least as new as the entry. Check transitive imports via
+    // a sidecar metafile written on the previous build.
+    const metaPath = `${outFile}.meta.json`;
+    const metaMtime = await safeMtime(metaPath);
+    if (metaMtime === null) {
+        // No metafile — built by an older code path. Rebuild to populate it.
+        return { entryPath, outFile, baseName, rebuild: true };
+    }
+    const importPaths = await readMetafileInputs(metaPath, entryPath);
+    if (importPaths === null) {
+        // Stale or corrupt sidecar — rebuild this entry to self-heal.
+        // eslint-disable-next-line no-console
+        console.warn(`deskwork-studio: stale or corrupt metafile at ${metaPath} — rebuild`);
+        return { entryPath, outFile, baseName, rebuild: true };
+    }
+    for (const imp of importPaths) {
+        const impMtime = await safeMtime(imp);
+        if (impMtime === null)
+            continue; // file removed; rebuild will fail loudly if relevant
+        if (impMtime > cachedMtime) {
+            return { entryPath, outFile, baseName, rebuild: true };
+        }
+    }
+    return { entryPath, outFile, baseName, rebuild: false };
+}
+async function rebuildEntryWithLock(decision, srcDir, outDir) {
+    const lockPath = `${decision.outFile}.lock`;
+    const acquired = await acquireLock(lockPath);
+    if (!acquired.acquired) {
+        // Lock-wait timed out without us getting it. Re-check the cache:
+        // even if we never held the lock, the holder's output may now be
+        // valid (and our caller's `decideEntry` was a stale snapshot).
+        const recheck = await decideEntry(decision.entryPath, srcDir, outDir);
+        if (!recheck.rebuild) {
+            const cachedStat = await stat(decision.outFile);
+            return { bytes: cachedStat.size, didBuild: false };
+        }
+        throw new Error(`deskwork-studio: timed out waiting for build lock at ${lockPath}; remove it manually if stale`);
+    }
+    try {
+        // We hold the lock. Re-decide under the lock — another process may
+        // have finished its build while we waited. If the cache is now
+        // valid, skip the rebuild and report bytes from the cached file.
+        const recheck = await decideEntry(decision.entryPath, srcDir, outDir);
+        if (!recheck.rebuild) {
+            const cachedStat = await stat(decision.outFile);
+            return { bytes: cachedStat.size, didBuild: false };
+        }
+        const bytes = await rebuildEntry(decision);
+        return { bytes, didBuild: true };
+    }
+    finally {
+        await releaseLock(lockPath);
+    }
+}
+async function acquireLock(lockPath) {
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    let pollMs = LOCK_POLL_INITIAL_MS;
+    while (true) {
+        try {
+            await mkdir(lockPath, { recursive: false });
+            return { acquired: true };
+        }
+        catch (err) {
+            if (!isEexist(err))
+                throw err;
+            // Stale-lock recovery: if the lock dir is older than LOCK_STALE_MS,
+            // the holder probably crashed. Reap it and retry.
+            const lockMtime = await safeMtime(lockPath);
+            if (lockMtime !== null && Date.now() - lockMtime > LOCK_STALE_MS) {
+                // eslint-disable-next-line no-console
+                console.warn(`deskwork-studio: removing stale build lock at ${lockPath} (age=${Math.round((Date.now() - lockMtime) / 1000)}s)`);
+                try {
+                    await rm(lockPath, { recursive: true, force: true });
+                }
+                catch {
+                    // Another process may have just released it; loop back and try mkdir again.
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                return { acquired: false };
+            }
+            await sleep(pollMs);
+            pollMs = Math.min(pollMs * 2, LOCK_POLL_MAX_MS);
+        }
+    }
+}
+async function releaseLock(lockPath) {
+    try {
+        await rm(lockPath, { recursive: true, force: true });
+    }
+    catch {
+        // best-effort; nothing actionable here.
+    }
+}
+function isEexist(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    if (!('code' in err))
+        return false;
+    const code = err.code;
+    return code === 'EEXIST';
+}
+function sleep(ms) {
+    return new Promise((r) => {
+        setTimeout(r, ms);
+    });
+}
+function makeTmpPath(finalPath) {
+    const rand = randomBytes(6).toString('hex');
+    return `${finalPath}.tmp.${process.pid}.${rand}`;
+}
+async function rebuildEntry(decision) {
+    const tmpOutFile = makeTmpPath(decision.outFile);
+    const opts = {
+        entryPoints: [decision.entryPath],
+        outfile: tmpOutFile,
+        bundle: true,
+        format: 'esm',
+        target: 'es2022',
+        minify: false,
+        sourcemap: 'linked',
+        logLevel: 'warning',
+        metafile: true,
+    };
+    let result;
+    try {
+        result = await build(opts);
+    }
+    catch (err) {
+        // Best-effort cleanup of any partial tmp output.
+        await unlink(tmpOutFile).catch(() => undefined);
+        await unlink(`${tmpOutFile}.map`).catch(() => undefined);
+        throw err;
+    }
+    if (result.errors.length > 0) {
+        await unlink(tmpOutFile).catch(() => undefined);
+        await unlink(`${tmpOutFile}.map`).catch(() => undefined);
+        throw new Error(`deskwork-studio: esbuild reported ${result.errors.length} errors building ${decision.entryPath}`);
+    }
+    if (!result.metafile) {
+        await unlink(tmpOutFile).catch(() => undefined);
+        await unlink(`${tmpOutFile}.map`).catch(() => undefined);
+        throw new Error(`deskwork-studio: esbuild did not return a metafile for ${decision.entryPath}; cache check would be unsound`);
+    }
+    // Atomically promote the JS (and sourcemap, if present) to the final path.
+    await rename(tmpOutFile, decision.outFile);
+    // sourcemap path mirrors esbuild's `linked` behavior: <outfile>.map
+    const tmpMap = `${tmpOutFile}.map`;
+    const finalMap = `${decision.outFile}.map`;
+    if (await exists(tmpMap)) {
+        await rename(tmpMap, finalMap);
+    }
+    await writeMetafileAtomic(`${decision.outFile}.meta.json`, result.metafile);
+    const stats = await stat(decision.outFile);
+    return stats.size;
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function safeMtime(path) {
+    try {
+        const info = await stat(path);
+        return info.mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeMetafileAtomic(path, meta) {
+    const tmp = makeTmpPath(path);
+    const json = JSON.stringify({ inputs: Object.keys(meta.inputs) });
+    await writeFile(tmp, json, 'utf8');
+    await rename(tmp, path);
+}
+/**
+ * Returns the resolved import paths from the sidecar metafile.
+ * Returns `null` if the sidecar is missing, unreadable, malformed, or
+ * fails JSON.parse — the caller treats `null` as "rebuild this entry."
+ * This makes the cache self-healing: a corrupt sidecar (e.g. truncated
+ * by a kill mid-write) cannot wedge boot.
+ */
+async function readMetafileInputs(metaPath, entryPath) {
+    let raw;
+    try {
+        raw = await readFile(metaPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isMetafileSidecar(parsed)) {
+        return null;
+    }
+    // esbuild metafile inputs are project-relative paths from cwd at build
+    // time. Resolve them relative to the entry's directory so the mtime
+    // checks work whether or not cwd has changed since the build.
+    const entryDir = entryPath.slice(0, entryPath.lastIndexOf('/'));
+    return parsed.inputs.map((rel) => resolve(entryDir, rel));
+}
+function isMetafileSidecar(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('inputs' in value))
+        return false;
+    const inputs = value.inputs;
+    if (!Array.isArray(inputs))
+        return false;
+    for (const item of inputs) {
+        if (typeof item !== 'string')
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=build-client-assets.js.map

package/dist/build-client-assets.js.map

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

package/dist/components/scrapbook-item.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared scrapbook-item renderer.
+ *
+ * Three studio surfaces consume this module:
+ *
+ *   1. Standalone scrapbook viewer  — `pages/scrapbook.ts`
+ *   2. Review-page drawer (Phase 16c) — `pages/review.ts`
+ *   3. Bird's-eye content view detail panel (Phase 16d) — `pages/content.ts`
+ *
+ * Goal: the operator sees consistent in-browser preview behavior wherever
+ * a scrapbook item appears. The standalone viewer keeps its richer
+ * disclosure / edit / rename / delete affordances; the read-only views
+ * (review drawer, content-view detail panel) reuse the same kind chip,
+ * filename, size, mtime, and the same in-browser preview rules:
+ *
+ *   - Image kinds (`png`, `jpg`, `jpeg`, `webp`, `gif`, `svg`)
+ *     render an inline thumbnail with a small overlay action to view
+ *     full-size; clicking opens the served file in a new tab. Both
+ *     image and PDF surfaces use a read-only binary endpoint
+ *     (`GET /api/dev/scrapbook-file`) that the studio adds for these
+ *     read-only views — distinct from the (not-yet-ported) full
+ *     scrapbook CRUD API.
+ *   - PDF — embedded via `<iframe>` using the same binary endpoint. The
+ *     browser renders it natively.
+ *   - Plain text / JSON — inline-truncated `<pre>` preview. Operators
+ *     can read the first ~10 lines without leaving the page; a "view
+ *     full" link opens the standalone viewer where the full file
+ *     is mounted.
+ *   - Markdown — kept as a kind-only row. Markdown is the editable
+ *     surface — operators jump to the standalone viewer to edit. Showing
+ *     a raw markdown preview here would either duplicate the editor or
+ *     misrepresent what double-click does on this surface.
+ *   - Anything else — kind chip + a download link. The browser can't
+ *     render it, so make that explicit.
+ *
+ * Inline previews for text + JSON come from the server side: the
+ * standalone viewer only loads body content on disclosure (lazy), but
+ * the read-only renderers want the preview embedded at server-render
+ * time so operators don't see a flash. Callers pass an
+ * `inlinePreviewLoader` that knows how to read the first N bytes of
+ * the file and return a string; this module composes the result into
+ * the row HTML.
+ */
+import { type ScrapbookItem } from '@deskwork/core/scrapbook';
+import { type RawHtml } from '../pages/html.ts';
+/** Scrapbook items addressed by site + path. */
+export interface ScrapbookAddress {
+    site: string;
+    /**
+     * Hierarchical path of the scrapbook (e.g.
+     * `the-outbound/characters/strivers`). Same string the standalone
+     * viewer uses in its URL.
+     */
+    path: string;
+}
+/**
+ * Read the first slice of a text/JSON scrapbook file for inline
+ * preview. Implementations must read at most `maxBytes` to keep the
+ * server render cheap. Returns `null` when the file isn't readable
+ * as text (the renderer falls back to a download link in that case).
+ */
+export type InlineTextLoader = (filename: string, maxBytes: number) => string | null;
+export interface ScrapbookItemRendererOptions {
+    /**
+     * Maximum bytes to read for inline text/JSON preview. Defaults to
+     * 800 — small enough to keep the row tight, large enough for the
+     * operator to recognize the file's shape.
+     */
+    inlinePreviewMaxBytes?: number;
+    /**
+     * Optional loader used by text/JSON kinds. Required if the caller
+     * wants those kinds to actually preview inline; without a loader
+     * they fall back to a kind-chip-only row.
+     */
+    inlinePreviewLoader?: InlineTextLoader;
+}
+/**
+ * Build the URL to fetch a scrapbook file's raw bytes from the
+ * read-only binary endpoint. The endpoint is read-only by design —
+ * Phase 16's image / PDF previews need a stable URL, but full
+ * scrapbook CRUD remains in the standalone viewer's surface.
+ */
+export declare function scrapbookFileUrl(address: ScrapbookAddress, filename: string, opts?: {
+    secret?: boolean;
+}): string;
+/**
+ * Build the URL to the standalone scrapbook viewer for an address —
+ * the operator's "open scrapbook" jumping-off point.
+ */
+export declare function scrapbookViewerUrl(address: ScrapbookAddress): string;
+/**
+ * Render a single scrapbook item as a read-only row for the review
+ * drawer or the content-view detail panel. Returns the row HTML wrapped
+ * in `unsafe(...)`.
+ *
+ * Visual posture: kind chip + filename + size + mtime, with an inline
+ * preview block beneath the row for kinds the browser can render in
+ * place (image thumbnail, text/JSON truncated, PDF embed). Markdown +
+ * unrenderable kinds keep a single-line row.
+ */
+export declare function renderReadOnlyScrapbookRow(address: ScrapbookAddress, item: ScrapbookItem, opts?: ScrapbookItemRendererOptions): RawHtml;
+/**
+ * Render an empty-state row for a scrapbook drawer / panel that has
+ * no items. Shown faded so the operator still sees the section exists
+ * for this node.
+ */
+export declare function renderEmptyScrapbookRow(): RawHtml;
+//# sourceMappingURL=scrapbook-item.d.ts.map

package/dist/components/scrapbook-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrapbook-item.d.ts","sourceRoot":"","sources":["../../src/components/scrapbook-item.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAgB,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAM9D,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,KACb,MAAM,GAAG,IAAI,CAAC;AAEnB,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;CACxC;AASD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9B,MAAM,CAQR;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAIpE;AA+DD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,aAAa,EACnB,IAAI,GAAE,4BAAiC,GACtC,OAAO,CA8DT;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAKjD"}