@timber-js/app 0.2.0-alpha.96 → 0.2.0-alpha.98

package/dist/server/html-injector-core.d.ts

@@ -0,0 +1,212 @@
+/**
+ * HTML injector core — pure stateful helpers for streaming HTML post-processing.
+ *
+ * These helpers contain the actual byte/string logic for the held-flush
+ * streaming pipeline (buffered transforms, suffix moving, head injection,
+ * RSC flight interleaving). They are stream-shape agnostic: they know
+ * nothing about Web `TransformStream` or Node.js `Transform` and contain
+ * no `setImmediate` scheduling or controller plumbing.
+ *
+ * The Web Stream wrapper (`html-injectors.ts`) and the Node Stream wrapper
+ * (`node-stream-transforms.ts`) compose these helpers behind whichever
+ * stream shape their target runtime needs:
+ *
+ *   - On Cloudflare/edge: Web `TransformStream` wraps the helpers.
+ *   - On Node.js/Bun: Node `Transform` wraps the helpers (faster — C++ streams).
+ *
+ * Keeping this module split per-shape (rather than one file exporting both)
+ * preserves the build-time tree-shake: Cloudflare bundles never import
+ * `node:stream` even transitively. Only the helpers below are shared.
+ *
+ * **Pure functions only.** Anything that touches a stream API, schedules
+ * a tick, or owns a controller belongs in the wrapper, not here.
+ *
+ * Design docs: 02-rendering-pipeline.md §"Streaming Constraints", 18-build-system.md §"Entry Files"
+ */
+import { type Machine } from '../utils/state-machine.js';
+import { type FlightInjectionState, type FlightInjectionEvent } from './flight-injection-state.js';
+/** Closing tags React Fizz emits inside the shell chunk. */
+export declare const SUFFIX = "</body></html>";
+/** UTF-8 bytes of {@link SUFFIX}. Cached so wrappers don't re-encode per request. */
+export declare const SUFFIX_BYTES: Uint8Array;
+/** Encode a UTF-8 string. Convenience for wrappers that need a single source of truth. */
+export declare function encodeUtf8(text: string): Uint8Array;
+/**
+ * Pure buffer state for the buffered transform.
+ *
+ * Both Web and Node wrappers want the same behaviour: collect chunks that
+ * arrive in the same event-loop tick, decide whether the buffer has grown
+ * beyond `maxBufferByteLength` and must flush synchronously, then emit a
+ * single concatenated chunk on the next tick.
+ *
+ * The only thing the two wrappers disagree on is *who schedules the tick*
+ * (`setImmediate` callback vs Promise-based) and *how to push the merged
+ * chunk* (`controller.enqueue` vs `transform.push`). This class owns
+ * everything else.
+ */
+export declare class BufferAggregator {
+    private readonly maxBufferByteLength;
+    private chunks;
+    private byteLength;
+    constructor(maxBufferByteLength?: number);
+    /**
+     * Append a chunk. Returns `true` if the caller should flush synchronously
+     * right now (the buffer has reached the byte cap), `false` if a deferred
+     * tick-end flush is sufficient.
+     */
+    append(chunk: Uint8Array): boolean;
+    /** Drain the buffer into a single concatenated chunk, or `null` if empty. */
+    drain(): Uint8Array | null;
+    get bufferedByteLength(): number;
+    get isEmpty(): boolean;
+}
+/**
+ * Result of feeding one chunk through the suffix-mover state.
+ *
+ * - `passthrough` — already found and removed the suffix on a previous chunk.
+ *   Caller emits the chunk unchanged.
+ * - `noSuffix` — current chunk does not contain the suffix. Caller emits unchanged.
+ * - `suffixFound` — caller emits `before` and `after` (skipping the suffix
+ *   itself). The suffix will be re-emitted later by {@link suffixFlush}.
+ */
+export type SuffixChunkResult = {
+    kind: 'passthrough';
+} | {
+    kind: 'noSuffix';
+} | {
+    kind: 'suffixFound';
+    before: Uint8Array | null;
+    after: Uint8Array | null;
+};
+export interface SuffixState {
+    found: boolean;
+}
+export declare function createSuffixState(): SuffixState;
+/**
+ * Search a chunk for {@link SUFFIX}. If found, mark state and return the
+ * surrounding bytes (the caller emits them; the suffix is held for the
+ * end of the stream). The bytes-vs-text dance matches what both Web and
+ * Node implementations did before extraction — search via decoded UTF-8
+ * to avoid splitting multi-byte characters at the suffix boundary.
+ */
+export declare function processSuffixChunk(state: SuffixState, chunk: Uint8Array): SuffixChunkResult;
+/**
+ * Final emit for the suffix mover. Always returns the suffix bytes — even
+ * if no suffix was ever observed in the input — so output is well-formed.
+ */
+export declare function suffixFlush(_state: SuffixState): Uint8Array;
+/**
+ * Pure state for `injectHead`-style transforms: scan for a target tag,
+ * inject `content` once at the matching position, then pass everything
+ * else through. We keep a small trailing string buffer (just under the
+ * length of the target tag) so the tag can be detected even when split
+ * across chunk boundaries.
+ *
+ * The `decoder` is a long-lived `TextDecoder` reused across every chunk
+ * with `{ stream: true }`. This is required so a UTF-8 codepoint that
+ * spans two chunks (e.g. the bytes of `é` arriving in two halves) is
+ * reassembled correctly. A fresh decoder per chunk would drop or
+ * replace the partial codepoint and corrupt streamed HTML.
+ */
+export interface InjectorState {
+    injected: boolean;
+    tail: string;
+    readonly content: string;
+    readonly targetTag: string;
+    readonly position: 'before' | 'after';
+    readonly tailLen: number;
+    readonly decoder: TextDecoder;
+}
+export interface InjectorOptions {
+    content: string;
+    targetTag: string;
+    position?: 'before' | 'after';
+}
+export declare function createInjectorState(options: InjectorOptions): InjectorState;
+/**
+ * Result of feeding one chunk through {@link processInjectorChunk}.
+ *
+ * - `passthrough` — already injected. Emit `chunk` unchanged.
+ * - `emit` — emit the returned bytes (or nothing if `null`).
+ *
+ * Note: when not yet injected and the target tag is not present, the
+ * helper still emits the *safe head* of the buffer — everything except
+ * the trailing `tailLen` characters that might be the start of the
+ * target tag spilled into the next chunk. The unsafe tail is held in
+ * `state.tail` for the next call.
+ */
+export type InjectorChunkResult = {
+    kind: 'passthrough';
+} | {
+    kind: 'emit';
+    bytes: Uint8Array | null;
+};
+export declare function processInjectorChunk(state: InjectorState, chunk: Uint8Array): InjectorChunkResult;
+/**
+ * Final emit for the injector. If the target tag never appeared, the
+ * leftover tail bytes are returned so they aren't lost. (The injection
+ * itself is silently skipped — same behaviour as before extraction.)
+ */
+export declare function injectorFlush(state: InjectorState): Uint8Array | null;
+/**
+ * Pure async core of the RSC flight-injection transform.
+ *
+ * Both wrappers (Web `TransformStream` and Node `Transform`) implement the
+ * exact same protocol around an RSC reader:
+ *
+ *   1. On the first HTML chunk, send `FIRST_CHUNK` and start the pull loop.
+ *   2. The pull loop reads from `rscReader` (timeout-guarded), wraps each
+ *      chunk in a `<script>` via `flightChunkScript`, and pushes it onto a
+ *      pending queue. Between reads, it yields with a single-shot
+ *      `setImmediate` so HTML chunks get event-loop priority — and after
+ *      yielding, it drains the queue (via the wrapper's `onYieldDrain`)
+ *      so flight data reaches the client at shell-flush time.
+ *   3. After every emitted HTML chunk, the wrapper drains the queue.
+ *   4. On `flush()` the wrapper sends `HTML_DONE` and awaits `pullPromise`.
+ *      No polling — just `.then()`.
+ *
+ * The wrappers only differ in:
+ *   - How they push bytes (controller.enqueue vs transform.push).
+ *   - How they signal a terminal error (controller.error vs transform.destroy).
+ *
+ * This class owns the state machine, the pending queue, and the pull
+ * loop itself. The wrapper supplies the drain callback and consumes the
+ * pending queue + machine state to decide what to push.
+ *
+ * **No polling.** See design/02-rendering-pipeline.md §"No Polling".
+ * **Always timeout-guarded reads.** Per design/02 §"Streaming Constraints".
+ */
+export declare class FlightInjectorCore {
+    readonly machine: Machine<FlightInjectionState, FlightInjectionEvent>;
+    /** Script chunks waiting to be drained between HTML chunks. */
+    readonly pending: Uint8Array[];
+    private readonly rscReader;
+    private readonly timeoutMs;
+    private readonly decoder;
+    private pullPromise;
+    constructor(rscStream: ReadableStream<Uint8Array>, renderTimeoutMs?: number);
+    /** Tell the machine the first HTML chunk has arrived. Idempotent-ish: caller checks. */
+    notifyFirstChunk(): void;
+    /** Tell the machine HTML output is finished — pull loop will stop yielding. */
+    notifyHtmlDone(): void;
+    get isInit(): boolean;
+    get isPullDone(): boolean;
+    get hasPullPromise(): boolean;
+    /**
+     * Get (or start) the pull-loop promise. The wrapper calls this from
+     * `flush()` and chains `.then()` onto it — never `await` without an
+     * existing finish callback (we don't want to block transform()).
+     *
+     * `onYieldDrain` is invoked between RSC reads while HTML is still
+     * streaming. It must drain the pending queue into the output stream.
+     */
+    ensurePullLoop(onYieldDrain: () => void): Promise<void>;
+    /**
+     * Get the current terminal error if the machine is in the error phase,
+     * else `null`. Wrappers use this after a drain to decide whether to
+     * `controller.error()` / `transform.destroy()`.
+     */
+    get terminalError(): unknown;
+    private runPullLoop;
+}
+//# sourceMappingURL=html-injector-core.d.ts.map

package/dist/server/html-injector-core.d.ts.map

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

package/dist/server/html-injectors.d.ts

@@ -1,14 +1,22 @@
 /**
- * HTML stream injectors — TransformStreams that modify streamed HTML.
- *
- * These are extracted into a separate module so they can be tested
- * independently of rsc-entry.ts (which imports virtual modules).
+ * HTML stream injectors — Web `TransformStream` wrappers around the
+ * pure helpers in `html-injector-core.ts`.
+ *
+ * Used on edge runtimes (Cloudflare Workers, Deno, browser SSR) where
+ * Web Streams are the native shape. The Node.js / Bun adapters live in
+ * `node-stream-transforms.ts` and wrap the same core in Node `Transform`s.
+ * Both wrappers must stay byte-for-byte equivalent — the core enforces
+ * that. If you fix a streaming bug here, you almost certainly need to
+ * fix it (or its cause) in the core, not in the Node wrapper.
+ *
+ * Also exports the `buildClientScripts` helper used by RSC entry to
+ * resolve bootstrap script URLs from the build manifest. That helper
+ * is unrelated to streaming but lives here for historical reasons (it
+ * shares no code with the core and was previously co-located with the
+ * Web stream transforms).
  *
  * Design docs: 02-rendering-pipeline.md, 18-build-system.md §"Entry Files"
  */
-/**
- * Options for the buffered transform stream.
- */
 export interface BufferedTransformOptions {
     /**
      * Flush synchronously once the buffer reaches this many bytes.
@@ -20,49 +28,38 @@ export interface BufferedTransformOptions {
 /**
  * Buffer incoming chunks and coalesce them within a single event loop tick.
  *
- * React Fizz may emit multiple micro-chunks within a single flush (e.g.,
- * opening tags, attributes, closing tags as separate writes). Without
- * buffering, downstream transforms (especially flight injection) could
- * see chunk boundaries in the middle of HTML tags or attribute values.
- *
- * This transform collects all chunks that arrive in the same tick and
- * emits them as a single concatenated chunk on the next `setImmediate`.
- * This ensures each output chunk represents a coherent HTML fragment
- * from a single Fizz flush — safe for downstream script injection at
- * chunk boundaries.
- *
- * **Not a polling loop.** Uses a single-shot `setImmediate` per flush
- * cycle — no recursive scheduling, no busy-wait. See design/02 §"No Polling".
+ * React Fizz may emit multiple micro-chunks within a single flush. Without
+ * coalescing, downstream transforms (especially flight injection) could
+ * see chunk boundaries in the middle of HTML tags. This transform collects
+ * everything that arrives in the same tick and emits it as one concatenated
+ * chunk on the next `setImmediate` — a single-shot schedule, not a poll.
  *
- * Inspired by Next.js `createBufferedTransformStream`.
+ * See design/02 §"No Polling" and §"Scripts at Chunk Boundaries Only".
  */
 export declare function createBufferedTransformStream(options?: BufferedTransformOptions): TransformStream<Uint8Array, Uint8Array>;
 /**
  * Move `</body></html>` to the end of the stream.
  *
- * React's renderToReadableStream emits `</body></html>` as part of the
- * shell chunk. Content that arrives after the shell (Suspense resolutions,
- * RSC script tags) would appear after the closing tags, producing invalid
- * HTML like `</body></html><script>...</script>`.
- *
- * This transform strips the suffix when first encountered and re-emits
- * it in `flush()` — after all content has passed through. If no suffix
- * is found, it's appended anyway to ensure well-formed HTML.
+ * React's renderToReadableStream emits the closing tags as part of the
+ * shell chunk. Content arriving after the shell (Suspense resolutions,
+ * RSC scripts) would otherwise appear after `</html>` and produce invalid
+ * HTML. This transform strips the suffix on first sight and re-emits it
+ * from `flush()` — after every other byte has passed through. If the
+ * suffix never appeared in the input, it is appended anyway so output
+ * is well-formed.
  *
  * Equivalent to Next.js's `createMoveSuffixStream`.
  */
 export declare function createMoveSuffixStream(): TransformStream<Uint8Array, Uint8Array>;
 /**
- * Inject metadata elements before </head> in the HTML stream.
- *
- * If no </head> is found, the buffer is emitted as-is.
+ * Inject metadata elements before `</head>` in the HTML stream.
+ * If no `</head>` is found, the buffer is emitted as-is.
  */
 export declare function injectHead(stream: ReadableStream<Uint8Array>, headHtml: string): ReadableStream<Uint8Array>;
 /**
- * Inject client bootstrap scripts before </body> in the HTML stream.
- *
- * Returns the stream unchanged if scriptsHtml is empty (client JS disabled mode).
- * If no </body> is found, the buffer is emitted as-is.
+ * Inject client bootstrap scripts before `</body>` in the HTML stream.
+ * Returns the stream unchanged if `scriptsHtml` is empty (client JS
+ * disabled mode). If no `</body>` is found, the buffer is emitted as-is.
  */
 export declare function injectScripts(stream: ReadableStream<Uint8Array>, scriptsHtml: string): ReadableStream<Uint8Array>;
 /**
@@ -70,29 +67,32 @@ export declare function injectScripts(stream: ReadableStream<Uint8Array>, script
  *
  * Uses a **pull-based** ReadableStream — the consumer (the injection
  * transform) drives reads from the RSC stream on demand. No background
- * reader, no shared mutable arrays, no race conditions.
- *
- * Each RSC chunk becomes a `<script>self.__timber_f.push([1,"data"])</script>`.
- * The init script (which creates __timber_f) is in `<head>` via
- * flightInitScript() — see flight-scripts.ts.
+ * reader, no shared mutable arrays, no race conditions. Each RSC chunk
+ * becomes `<script>self.__timber_f.push([1,"data"])</script>`. The
+ * init script (which creates `__timber_f`) is in `<head>` via
+ * `flightInitScript()` — see flight-scripts.ts.
  */
 export declare function createInlinedRscStream(rscStream: ReadableStream<Uint8Array>, renderTimeoutMs?: number): ReadableStream<Uint8Array>;
 /**
  * Progressively inline RSC Flight payload chunks into the HTML stream.
  *
- * Architecture (3 TransformStream pipeline):
- * 1. HTML stream → moveSuffix (captures </body></html>, re-emits at end)
- * 2. → flightInjection (merges RSC <script> tags between HTML chunks)
- * 3. → output (well-formed HTML with interleaved RSC data)
+ * Architecture (2 TransformStream pipeline):
+ *   HTML stream → flightInjection → moveSuffix → output
+ *
+ * 1. flightInjection wraps each RSC chunk in a `<script>` and interleaves
+ *    them between HTML chunks.
+ * 2. moveSuffix strips `</body></html>` and re-emits at end so injected
+ *    scripts appear before the closing tags.
  *
- * The RSC stream is transformed into <script> tags via createInlinedRscStream
- * (pull-based, no shared mutable state) and merged into the HTML pipeline
- * via createFlightInjectionTransform.
+ * Wrapping happens inside `FlightInjectorCore` (via `flightChunkScript`).
+ * The raw RSC stream is passed straight to `createFlightInjectionTransform`
+ * — do not pre-wrap with `createInlinedRscStream` (that helper still
+ * exists for callers that want a standalone scripted stream).
  *
  * The client reads these script tags via `self.__timber_f` and feeds
- * them to `createFromReadableStream` for progressive hydration.
- * Stream completion is signaled by the DOMContentLoaded event on the
- * client side — no custom done flag needed.
+ * them to `createFromReadableStream` for progressive hydration. Stream
+ * completion is signaled by the `DOMContentLoaded` event on the client
+ * side — no custom done flag needed.
  */
 export declare function injectRscPayload(htmlStream: ReadableStream<Uint8Array>, rscStream: ReadableStream<Uint8Array> | undefined, renderTimeoutMs?: number): ReadableStream<Uint8Array>;
 /**
@@ -115,19 +115,19 @@ export interface ClientBootstrapConfig {
 /**
  * Build client bootstrap configuration based on runtime config.
  *
- * Returns empty strings when client JavaScript is disabled,
- * which produces zero-JS output. When `enableHMRInDev` is true and
- * running in dev mode, injects only the Vite HMR client (no app
- * bootstrap) so hot reloading works during development.
+ * Returns empty strings when client JavaScript is disabled, which produces
+ * zero-JS output. When `enableHMRInDev` is true and running in dev mode,
+ * injects only the Vite HMR client (no app bootstrap) so hot reloading
+ * works during development.
  *
  * In production, uses hashed chunk URLs from the build manifest.
  *
  * The bootstrap uses dynamic `import()` inside a regular (non-module)
  * inline script so it executes immediately during HTML parsing. This
- * is critical for streaming: `<script type="module">` is deferred
- * until the document finishes parsing, which blocks hydration behind
- * Suspense boundaries. Dynamic `import()` starts module loading and
- * execution as soon as the shell HTML is parsed.
+ * is critical for streaming: `<script type="module">` is deferred until
+ * the document finishes parsing, which blocks hydration behind Suspense
+ * boundaries. Dynamic `import()` starts module loading and execution as
+ * soon as the shell HTML is parsed.
  */
 export declare function buildClientScripts(runtimeConfig: {
     output: string;

package/dist/server/html-injectors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html-injectors.d.ts","sourceRoot":"","sources":["../../src/server/html-injectors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,wBAA6B,GACrC,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAgEzC;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAuChF;AA8ED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,EAAE,MAAM,GAClB,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAiC5B;AAmID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAiB5B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;CACtB;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,OAAO,CAAA;KAAE,CAAC;IACjE,GAAG,EAAE,OAAO,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;CAC7D,GAAG,qBAAqB,CA8DxB"}
+{"version":3,"file":"html-injectors.d.ts","sourceRoot":"","sources":["../../src/server/html-injectors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkBH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,wBAA6B,GACrC,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CA0CzC;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAiBhF;AAuCD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,EAAE,MAAM,GAClB,cAAc,CAAC,UAAU,CAAC,CAE5B;AAID;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CA6B5B;AAuED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAS5B;AAID;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;CACtB;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,OAAO,CAAA;KAAE,CAAC;IACjE,GAAG,EAAE,OAAO,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;CAC7D,GAAG,qBAAqB,CA8DxB"}