@procedures/client 0.0.0-stage → 0.1.0

package/dist/procedures/storage/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Procedure Storage Types
+ *
+ * Types for serializing and persisting procedure definitions.
+ * Enables procedure registry to be backed by CollectionStorage.
+ */
+import type { ProcedurePath, ProcedureMetadata } from "../types.js";
+/**
+ * Reference to a handler that can be loaded at runtime.
+ * Handlers cannot be serialized directly, so we store a reference.
+ */
+export interface HandlerReference {
+    /** Module name or path (e.g., "@mark1russell7/client-cli") */
+    module: string;
+    /** Named export from the module (e.g., "libScanHandler") */
+    export: string;
+}
+/**
+ * Serialized procedure definition for storage.
+ * Contains only JSON-serializable data.
+ */
+export interface SerializedProcedure {
+    /** Procedure path (e.g., ['lib', 'scan']) */
+    path: ProcedurePath;
+    /** Procedure metadata */
+    metadata: ProcedureMetadata;
+    /** Whether this procedure supports streaming */
+    streaming?: boolean | undefined;
+    /** Reference to handler for runtime loading (optional) */
+    handlerRef?: HandlerReference | undefined;
+    /** Timestamp when stored */
+    storedAt?: number | undefined;
+    /** Version for conflict detection */
+    version?: number | undefined;
+}
+/**
+ * Function to load a handler from a reference.
+ * Used to restore handlers when loading procedures from storage.
+ */
+export interface HandlerLoader {
+    /**
+     * Load a handler from a reference.
+     *
+     * @param ref - Handler reference with module and export name
+     * @returns The handler function, or undefined if not found
+     */
+    load(ref: HandlerReference): Promise<unknown | undefined>;
+}
+/**
+ * Sync direction for registry operations.
+ */
+export type SyncDirection = "push" | "pull" | "both";
+/**
+ * Conflict resolution strategy.
+ */
+export type ConflictResolution = "local" | "remote" | "merge" | "error";
+/**
+ * Write strategy for persistence.
+ */
+export type WriteStrategy = "write-through" | "write-back";
+/**
+ * Status of a sync conflict.
+ */
+export interface SyncConflict {
+    /** Procedure path that had conflict */
+    path: ProcedurePath;
+    /** How the conflict was resolved */
+    resolution: ConflictResolution;
+    /** Local version (if any) */
+    local?: SerializedProcedure;
+    /** Remote version (if any) */
+    remote?: SerializedProcedure;
+}
+/**
+ * Result of a sync operation.
+ */
+export interface SyncResult {
+    /** Number of procedures pushed to storage */
+    pushed: number;
+    /** Number of procedures pulled from storage */
+    pulled: number;
+    /** Conflicts encountered during sync */
+    conflicts: SyncConflict[];
+    /** Timestamp of sync completion */
+    timestamp: number;
+}
+/**
+ * Current sync status of the registry.
+ */
+export interface SyncStatus {
+    /** Whether connected to remote storage */
+    connected: boolean;
+    /** Remote endpoint URL (if connected) */
+    endpoint?: string | undefined;
+    /** Last successful sync timestamp */
+    lastSync?: number | undefined;
+    /** Number of pending local changes */
+    pendingChanges: number;
+    /** Whether currently syncing */
+    syncing: boolean;
+}
+/**
+ * Options for SyncedProcedureRegistry.
+ */
+export interface SyncedRegistryOptions {
+    /** Write strategy: write-through (immediate) or write-back (queued) */
+    writeStrategy: WriteStrategy;
+    /** How to resolve conflicts when loading from storage */
+    conflictResolution: ConflictResolution;
+    /** Auto-sync interval in milliseconds (0 to disable) */
+    syncInterval?: number | undefined;
+    /** Handler loader for restoring handlers from references */
+    handlerLoader?: HandlerLoader | undefined;
+    /** Whether to sync on initialization */
+    syncOnInit?: boolean | undefined;
+}
+/**
+ * Configuration for creating a storage-backed registry.
+ */
+export interface ProcedureStorageConfig {
+    /** Storage type to use */
+    type: "memory" | "api" | "hybrid";
+    /** The collection of the core collection procedures for API storage (default: "procedures") */
+    collection?: string | undefined;
+    /** The service of the calls, for a server with other paths (default: `collections.<collection>`) */
+    service?: string | undefined;
+    /** Options for the synced registry */
+    options?: Partial<SyncedRegistryOptions> | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/procedures/storage/types.d.ts.map

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

package/dist/procedures/storage/types.js

@@ -0,0 +1,8 @@
+/**
+ * Procedure Storage Types
+ *
+ * Types for serializing and persisting procedure definitions.
+ * Enables procedure registry to be backed by CollectionStorage.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/procedures/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/procedures/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/procedures/types.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Procedure Type System
+ *
+ * Core types for procedure definitions, handlers, and registration.
+ * Procedures are the foundation for typed RPC calls with schema validation.
+ */
+import type { ZodErrorLike } from "../client/validation/types.js";
+import type { ProcedureSchema } from "./schema.js";
+import type { CollectionStorage } from "./collection/storage.js";
+import type { EventBus } from "../events/types.js";
+import type { HydrationEvent } from "./ref.js";
+/**
+ * Procedure path as array of segments.
+ * Forms a tree structure for nested routing.
+ *
+ * @example
+ * ```typescript
+ * ['collections', 'users', 'get']  // collections.users.get
+ * ['weather', 'forecast']           // weather.forecast
+ * ```
+ */
+export type ProcedurePath = string[];
+/**
+ * Convert path array to dot-separated key.
+ */
+export declare function pathToKey(path: ProcedurePath): string;
+/**
+ * Parse dot-separated key to path array.
+ */
+export declare function keyToPath(key: string): ProcedurePath;
+/**
+ * Metadata for procedure documentation and categorization.
+ */
+export interface ProcedureMetadata {
+    /** Human-readable description */
+    description?: string;
+    /** Tags for categorization and filtering */
+    tags?: string[];
+    /** Whether this procedure is deprecated */
+    deprecated?: boolean;
+    /** Deprecation message with migration guidance */
+    deprecationMessage?: string;
+    /**
+     * The procedures that this procedure calls through `ctx.client`: keys (`"shell.run"`) or
+     * namespaces (`"fs.*"`). A host with a call policy lets the procedure call only these and the
+     * exposed procedures (see `policy.ts`, deep dive MCP-3). `"*"` alone is not allowed: a
+     * procedure whose callees come from its input has the `runs-refs` tag.
+     */
+    calls?: readonly string[];
+    /** Custom metadata fields */
+    [key: string]: unknown;
+}
+/**
+ * Repository provider for storage access.
+ * Injected into procedure handlers for data access.
+ */
+export interface RepositoryProvider {
+    /**
+     * Get storage for a collection.
+     *
+     * @param collection - Collection name
+     * @returns Storage instance for the collection
+     */
+    getStorage<T>(collection: string): CollectionStorage<T>;
+    /**
+     * Check if a collection exists.
+     *
+     * @param collection - Collection name
+     */
+    hasCollection(collection: string): boolean;
+}
+/**
+ * Context passed to procedure handlers.
+ * Contains request metadata and service access.
+ */
+export interface ProcedureContext {
+    /** Request metadata (auth, tracing, etc.) */
+    metadata: Record<string, unknown>;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Repository provider for storage access */
+    repository?: RepositoryProvider;
+    /** The full path that was called */
+    path: ProcedurePath;
+    /**
+     * Event bus for pub/sub messaging.
+     * Use for streaming coordination and inter-procedure communication.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to updates in a streaming handler
+     * handler: async function* (input, ctx) {
+     *   yield await getInitial(input.id);
+     *
+     *   for await (const update of ctx.bus.stream(`entity:${input.id}`)) {
+     *     yield update;
+     *   }
+     * }
+     *
+     * // Emit events from another procedure
+     * handler: async (input, ctx) => {
+     *   const result = await saveEntity(input);
+     *   ctx.bus.emit(`entity:${input.id}`, result);
+     *   return result;
+     * }
+     * ```
+     */
+    bus?: EventBus;
+    /**
+     * Client for calling other procedures.
+     * Enables inter-procedure communication via the RPC mechanism.
+     *
+     * @example
+     * ```typescript
+     * handler: async (input, ctx) => {
+     *   // Call fs.mkdir procedure
+     *   await ctx.client.call(["fs", "mkdir"], { path: input.dir });
+     *
+     *   // Call git.init procedure
+     *   await ctx.client.call(["git", "init"], { cwd: input.dir });
+     *
+     *   return { created: true };
+     * }
+     * ```
+     */
+    client: ProcedureClient;
+    /**
+     * The registry of the caller: `ctx.client` finds the nested procedures here. A procedure that
+     * reads or changes the registry (`procedure.define`, `client.lookup`) uses this one. When it is
+     * not set, such a procedure uses `PROCEDURE_REGISTRY`.
+     */
+    registry?: ProcedureRegistryLike;
+    /**
+     * The hydration observer of the program that runs this procedure (`client.exec(ref, input,
+     * { onRef })`). A procedure that hydrates refs itself (control flow, a runner) gives it to
+     * `hydrateInput`, so a trace sees the events of its own program only.
+     */
+    onRef?: ((event: HydrationEvent) => void) | undefined;
+}
+/**
+ * The part of `ProcedureRegistry` that a procedure can use through `ctx.registry`.
+ */
+export interface ProcedureRegistryLike {
+    get(path: ProcedurePath): AnyProcedure | undefined;
+    has(path: ProcedurePath): boolean;
+    getAll(): AnyProcedure[];
+    register(procedure: AnyProcedure, options?: RegistrationOptions): void;
+    unregister(path: ProcedurePath): boolean;
+}
+/**
+ * Interface for procedure-to-procedure calls.
+ * Implemented by both Client and ProcedureServer's internal caller.
+ */
+export interface ProcedureClient {
+    /**
+     * Call a procedure by path. For a streaming procedure, the result is the last item.
+     */
+    call<TInput = unknown, TOutput = unknown>(path: ProcedurePath, input: TInput): Promise<TOutput>;
+    /**
+     * Call a procedure by path and read each output: each item of a streaming procedure, or the
+     * one value of another procedure. The procedure starts when the caller reads the first item.
+     * An older client has no `stream`.
+     */
+    stream?<TInput = unknown, TOutput = unknown>(path: ProcedurePath, input: TInput): AsyncIterable<TOutput>;
+}
+/**
+ * Standard procedure handler function (single return).
+ * Receives validated input and context, returns output.
+ *
+ * @example
+ * ```typescript
+ * const handler: StandardHandler<{ id: string }, User> = async (input, ctx) => {
+ *   const storage = ctx.repository?.getStorage<User>('users');
+ *   const user = await storage?.get(input.id);
+ *   if (!user) throw new Error('User not found');
+ *   return user;
+ * };
+ * ```
+ */
+export type StandardHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: ProcedureContext) => Promise<TOutput> | TOutput;
+/**
+ * Generator procedure handler (streaming/multi-yield).
+ * Yields output values one or more times.
+ *
+ * @example
+ * ```typescript
+ * // Single yield (same as standard, but generator syntax)
+ * const handler: GeneratorHandler<{ id: string }, User> = async function* (input, ctx) {
+ *   const user = await fetchUser(input.id);
+ *   yield user;  // yields once
+ * };
+ *
+ * // Multi-yield streaming
+ * const handler: GeneratorHandler<{ roomId: string }, Message> = async function* (input, ctx) {
+ *   // Initial data
+ *   yield await getInitialMessages(input.roomId);
+ *
+ *   // Stream updates
+ *   for await (const msg of ctx.bus.stream(`room:${input.roomId}`)) {
+ *     yield msg;  // yields many times
+ *   }
+ * };
+ * ```
+ */
+export type GeneratorHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: ProcedureContext) => AsyncGenerator<TOutput, void, unknown>;
+/**
+ * Procedure handler function - supports both standard and generator forms.
+ *
+ * - **Standard handlers**: Return a single value (sync or async)
+ * - **Generator handlers**: Yield one or more values
+ *
+ * The caller's consumption mode (sponge/stream/handlers) determines
+ * how the output is delivered, regardless of handler type.
+ *
+ * @example
+ * ```typescript
+ * // Standard handler (single return)
+ * const handler: ProcedureHandler<{ id: string }, User> = async (input, ctx) => {
+ *   return await fetchUser(input.id);
+ * };
+ *
+ * // Generator handler (streaming)
+ * const handler: ProcedureHandler<{ query: string }, SearchResult> = async function* (input, ctx) {
+ *   for await (const result of search(input.query)) {
+ *     yield result;
+ *   }
+ * };
+ * ```
+ */
+export type ProcedureHandler<TInput = unknown, TOutput = unknown> = StandardHandler<TInput, TOutput> | GeneratorHandler<TInput, TOutput>;
+/**
+ * Full procedure definition with schemas and optional handler.
+ *
+ * @example
+ * ```typescript
+ * const getUserProcedure: Procedure<GetUserInput, User> = {
+ *   path: ['users', 'get'],
+ *   input: z.object({ id: z.string() }),
+ *   output: z.object({ id: z.string(), name: z.string() }),
+ *   metadata: { description: 'Get user by ID', tags: ['users', 'read'] },
+ *   handler: async ({ id }, ctx) => { ... },
+ * };
+ * ```
+ */
+export interface Procedure<TInput = unknown, TOutput = unknown, TMeta extends ProcedureMetadata = ProcedureMetadata> {
+    /** Path in the route tree */
+    path: ProcedurePath;
+    /** Input validation schema: a Standard Schema (zod 4, valibot, arktype) or a `ZodLike` */
+    input: ProcedureSchema<TInput>;
+    /** Output validation schema: a Standard Schema or a `ZodLike` */
+    output: ProcedureSchema<TOutput>;
+    /** Procedure metadata for documentation */
+    metadata: TMeta;
+    /**
+     * Whether this procedure supports streaming (multi-yield).
+     * When true, the handler is expected to be a generator that may yield multiple times.
+     * When false or undefined, the procedure yields exactly once.
+     *
+     * This is a capability declaration - callers can still consume
+     * streaming procedures in sponge mode (getting only the final value).
+     */
+    streaming?: boolean | undefined;
+    /**
+     * Output mode declaration - how the procedure produces its output.
+     *
+     * - `single`: Returns a single value (default) - most procedures
+     * - `stream`: Returns multiple values over time (generator that yields many times)
+     * - `batch`: Returns an array of values all at once
+     *
+     * The consumer can choose their consumption mode (sponge/stream/handlers)
+     * independently. The system translates automatically:
+     *
+     * | Producer Mode | Consumer Mode | Result Type              |
+     * |---------------|---------------|--------------------------|
+     * | single        | sponge        | Promise<T>               |
+     * | single        | stream        | AsyncIterable<T> (1 item)|
+     * | stream        | sponge        | Promise<T> (last value)  |
+     * | stream        | stream        | AsyncIterable<T>         |
+     * | batch         | sponge        | Promise<T[]>             |
+     * | batch         | stream        | AsyncIterable<T>         |
+     */
+    outputMode?: 'single' | 'stream' | 'batch' | undefined;
+    /** Server-side handler implementation (optional for stubs and aggregations) */
+    handler?: ProcedureHandler<TInput, TOutput> | undefined;
+}
+/**
+ * Procedure without type parameters for generic storage.
+ * Uses `any` for handler to allow covariant/contravariant type compatibility.
+ */
+export type AnyProcedure = Procedure<any, any, ProcedureMetadata>;
+/**
+ * How a procedure produces its output.
+ */
+export type OutputMode = 'single' | 'stream' | 'batch';
+/**
+ * Default output mode when not specified.
+ */
+export declare const DEFAULT_OUTPUT_MODE: OutputMode;
+/**
+ * Result of a procedure call.
+ */
+export type ProcedureResult<TOutput> = {
+    success: true;
+    data: TOutput;
+} | {
+    success: false;
+    error: ProcedureError;
+};
+/**
+ * Error from procedure execution.
+ */
+export interface ProcedureError {
+    /** Error code */
+    code: string;
+    /** Error message */
+    message: string;
+    /** Whether the error is retryable */
+    retryable: boolean;
+    /** Validation errors if applicable */
+    validationErrors?: ZodErrorLike;
+    /** The procedure path that failed */
+    path: ProcedurePath;
+}
+/**
+ * Infer input type from a procedure.
+ */
+export type InferProcedureInput<T> = T extends Procedure<infer TInput, any, any> ? TInput : unknown;
+/**
+ * Infer output type from a procedure.
+ */
+export type InferProcedureOutput<T> = T extends Procedure<any, infer TOutput, any> ? TOutput : unknown;
+/**
+ * Infer metadata type from a procedure.
+ */
+export type InferProcedureMetadata<T> = T extends Procedure<any, any, infer TMeta> ? TMeta : ProcedureMetadata;
+/**
+ * Event types emitted by ProcedureRegistry.
+ */
+export type RegistryEventType = "register" | "unregister";
+/**
+ * Listener for registry events.
+ */
+export interface RegistryListener {
+    event: RegistryEventType;
+    listener: (procedure: AnyProcedure) => void;
+}
+/**
+ * Module that exports procedures for registration.
+ */
+export interface ProcedureModule {
+    /** Array of procedures exported by this module */
+    procedures: AnyProcedure[];
+    /** Optional module name for debugging */
+    name?: string;
+    /**
+     * The modules whose procedures this module calls (for example `client-lib` calls `fs.*` and
+     * `git.*`). `createRegistry()` registers them too.
+     */
+    requires?: readonly ProcedureModule[] | undefined;
+}
+/**
+ * Registration options for bulk procedure registration.
+ */
+export interface RegistrationOptions {
+    /** Override existing procedures with same path */
+    override?: boolean;
+    /** Prefix to prepend to all paths */
+    pathPrefix?: ProcedurePath;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/procedures/types.d.ts.map

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

package/dist/procedures/types.js

@@ -0,0 +1,23 @@
+/**
+ * Procedure Type System
+ *
+ * Core types for procedure definitions, handlers, and registration.
+ * Procedures are the foundation for typed RPC calls with schema validation.
+ */
+/**
+ * Convert path array to dot-separated key.
+ */
+export function pathToKey(path) {
+    return path.join(".");
+}
+/**
+ * Parse dot-separated key to path array.
+ */
+export function keyToPath(key) {
+    return key.split(".");
+}
+/**
+ * Default output mode when not specified.
+ */
+export const DEFAULT_OUTPUT_MODE = 'single';
+//# sourceMappingURL=types.js.map

package/dist/procedures/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/procedures/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,IAAmB;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AA+UD;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAe,QAAQ,CAAC"}

package/dist/server/browser-guard.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Checks of requests that a web browser can send to a procedure server.
+ *
+ * A server serves its whole registry, often with `shell.*` in it, and a web page that the user
+ * opens can send requests to `127.0.0.1`. Before, the HTTP server transport read any request
+ * body as JSON, so a "simple" cross-site POST (`Content-Type: text/plain`, no CORS preflight)
+ * ran any procedure, and the WebSocket server accepted a connection from any page
+ * (cross-site WebSocket hijacking). The checks here are on by default in both transports:
+ *
+ * - A connection that arrives on a loopback address must name a loopback host in its `Host`
+ *   header. A DNS rebinding attack sends the name of the attacker's site.
+ * - A browser request (an `Origin` header) must come from the server's own origin, or from an
+ *   origin in `allowedOrigins`.
+ * - A request that the browser marks `Sec-Fetch-Site: cross-site` or `same-site` and that has
+ *   no allowed origin is refused (an image tag or a form sends no `Origin` for a GET).
+ * - HTTP only: a procedure call by GET or HEAD is refused unless `allowGet` is true, and a
+ *   request body must be JSON.
+ */
+import type { IncomingHttpHeaders } from "node:http";
+/** The options of the browser checks of a server transport. */
+export interface BrowserGuardOptions {
+    /**
+     * The web origins that can call the server, besides its own origin. `"*"` allows every
+     * origin. A function decides for each origin.
+     * @default [] (only the server's own origin)
+     */
+    allowedOrigins?: readonly string[] | "*" | ((origin: string) => boolean) | undefined;
+    /**
+     * The host names that a request on a loopback address can name in its `Host` header,
+     * besides the loopback names. `"*"` turns the check off.
+     * @default [] (only `localhost`, `127.0.0.1` and `[::1]`)
+     */
+    allowedHosts?: readonly string[] | "*" | undefined;
+    /**
+     * HTTP only: accept procedure calls by GET or HEAD. A RESTful URL strategy needs this. A GET
+     * is a request that any page can send (an image tag), so it is off by default.
+     * @default false
+     */
+    allowGet?: boolean | undefined;
+}
+/** The parts of an incoming request that the checks read. */
+export interface GuardedRequest {
+    method?: string | undefined;
+    headers: IncomingHttpHeaders;
+    socket?: {
+        localAddress?: string | undefined;
+    } | undefined;
+}
+/** The result of the checks: the request passes, or the HTTP status and the error to send. */
+export type GuardResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly status: 403 | 405 | 415;
+    readonly code: string;
+    readonly message: string;
+};
+/** True for a host name or a bind address that only this computer can reach. */
+export declare function isLoopbackHost(host: string): boolean;
+/** True for a local socket address on the loopback interface (IPv4, IPv6, or IPv4 in IPv6). */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/** The name of a Host header without its port: "localhost:3000" gives "localhost", "[::1]:80" gives "[::1]". */
+export declare function hostNameOf(header: string | undefined): string;
+/**
+ * The checks of the host, the origin and the fetch site, for HTTP and WebSocket requests.
+ * `http` adds the checks of the method and the body.
+ */
+export declare function checkBrowserRequest(req: GuardedRequest, options?: BrowserGuardOptions, http?: boolean): GuardResult;
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/server/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../../src/server/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAIrD,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IACrF;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,GAAG,SAAS,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,MAAM,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,SAAS,CAAC;CAC5D;AAED,8FAA8F;AAC9F,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9G,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAItE;AAED,gHAAgH;AAChH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI7D;AA8BD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,cAAc,EACnB,OAAO,GAAE,mBAAwB,EACjC,IAAI,UAAQ,GACX,WAAW,CAkCb"}