@aws-blocks/core 0.2.0 → 0.4.0

package/dist/cdk/config-registry.test.js

@@ -0,0 +1,115 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CDK tests for the config registry — specifically the getConfigLocation ↔ finalizeConfigRegistry
+ * interaction. `getConfigLocation()` creates the config bucket eagerly (so co-located compute can
+ * inject BLOCKS_CONFIG_BUCKET/KEY at construction); finalize must therefore still upload the config
+ * object + wire the computes whenever a bucket exists, even if zero entries were registered —
+ * otherwise that compute's loadConfigToProcessEnv() would 404 forever against a created-but-empty
+ * bucket.
+ */
+import assert from 'node:assert';
+import { afterEach, test } from 'node:test';
+import * as cdk from 'aws-cdk-lib';
+import { Match, Template } from 'aws-cdk-lib/assertions';
+import { Construct } from 'constructs';
+import { Compute } from './compute/compute.js';
+import { finalizeConfigRegistry, getConfigLocation, registerConfig } from './config-registry.js';
+import { DEFAULT_NODE_RUNTIME } from './node-version.js';
+// getConfigLocation reads globalThis.CURRENT_BLOCKS_STACK to place the bucket under the owning
+// stack/backend; clear it between tests so one test's owner never leaks into another.
+afterEach(() => {
+    delete globalThis.CURRENT_BLOCKS_STACK;
+});
+// A real app's compute comes from @aws-blocks/bb-lambda-compute, which core's own tests can't
+// depend on. This is the same shape: a Compute that owns a real Lambda function and injects config
+// via addEnvironment — enough for finalizeConfigRegistry to stamp BLOCKS_CONFIG_BUCKET/KEY on it.
+class TestCompute extends Compute {
+    fn;
+    constructor(scope, id) {
+        super(id, { parent: scope });
+        this.fn = new cdk.aws_lambda.Function(this, 'Handler', {
+            runtime: DEFAULT_NODE_RUNTIME,
+            handler: 'index.handler',
+            code: cdk.aws_lambda.Code.fromInline('exports.handler = async () => {};'),
+        });
+    }
+    setEnv(key, value) {
+        this.fn.addEnvironment(key, value);
+    }
+}
+function stackWithCompute(id) {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, id);
+    const role = new cdk.aws_iam.Role(stack, 'BlocksRole', {
+        assumedBy: new cdk.aws_iam.ServicePrincipal('lambda.amazonaws.com'),
+    });
+    const compute = new TestCompute(stack, 'Compute');
+    return { stack, role, computes: [compute] };
+}
+test('finalize uploads + wires the computes even with zero entries when a bucket was created', () => {
+    const { stack, role, computes } = stackWithCompute('EmptyWithBucket');
+    // Simulate a co-located BB that creates the bucket but registers no config of its own.
+    getConfigLocation(stack);
+    finalizeConfigRegistry(stack, role, computes);
+    const t = Template.fromStack(stack);
+    assert.strictEqual(Object.keys(t.findResources('AWS::S3::Bucket')).length, 1, 'one config bucket');
+    t.resourceCountIs('Custom::CDKBucketDeployment', 1); // the (empty) blocks-config.json is uploaded
+    t.hasResourceProperties('AWS::Lambda::Function', {
+        Environment: { Variables: Match.objectLike({ BLOCKS_CONFIG_KEY: 'blocks-config.json' }) },
+    });
+    // Read is granted once to the shared role (not per-function), so every compute that assumes it
+    // — including co-located compute that never went through finalize — can read the object.
+    t.hasResourceProperties('AWS::IAM::Policy', {
+        PolicyDocument: {
+            Statement: Match.arrayWith([
+                Match.objectLike({ Action: Match.arrayWith([Match.stringLikeRegexp('^s3:GetObject')]) }),
+            ]),
+        },
+        Roles: Match.arrayWith([Match.objectLike({ Ref: Match.stringLikeRegexp('BlocksRole') })]),
+    });
+});
+test('finalize is a no-op with zero entries and no bucket', () => {
+    const { stack, role, computes } = stackWithCompute('EmptyNoBucket');
+    finalizeConfigRegistry(stack, role, computes);
+    const t = Template.fromStack(stack);
+    assert.strictEqual(Object.keys(t.findResources('AWS::S3::Bucket')).length, 0, 'no config bucket created');
+    t.resourceCountIs('Custom::CDKBucketDeployment', 0);
+});
+test('finalize uploads + wires the computes when config was registered (bucket auto-created)', () => {
+    const { stack, role, computes } = stackWithCompute('WithEntries');
+    registerConfig(stack, 'BLOCKS_SOMETHING', 'value');
+    finalizeConfigRegistry(stack, role, computes);
+    const t = Template.fromStack(stack);
+    assert.strictEqual(Object.keys(t.findResources('AWS::S3::Bucket')).length, 1, 'one config bucket');
+    t.resourceCountIs('Custom::CDKBucketDeployment', 1);
+    t.hasResourceProperties('AWS::Lambda::Function', {
+        Environment: { Variables: Match.objectLike({ BLOCKS_CONFIG_KEY: 'blocks-config.json' }) },
+    });
+});
+test('the config bucket is created under the owning stack/backend, not the (deep) caller scope', () => {
+    // Mimic a BlocksBackend embedded in a customer stack: the owner is a nested construct, and the
+    // first caller of getConfigLocation is a *deep* construct (like the AgentCore Runtime).
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'CustomerStack');
+    const owner = new Construct(stack, 'Embedded'); // stands in for the BlocksBackend construct
+    globalThis.CURRENT_BLOCKS_STACK = owner;
+    const deepScope = new Construct(new Construct(owner, 'agent'), 'runtime');
+    getConfigLocation(deepScope);
+    const t = Template.fromStack(stack);
+    const bucketIds = Object.keys(t.findResources('AWS::S3::Bucket'));
+    assert.strictEqual(bucketIds.length, 1, 'exactly one config bucket');
+    // Logical IDs encode the construct path — under the owner it's `EmbeddedBlocksConfigBucket…`,
+    // at the stack root it would be `BlocksConfigBucket…`. Pin that it follows the owner.
+    assert.ok(bucketIds[0].startsWith('Embedded'), `bucket should be nested under the owner, got ${bucketIds[0]}`);
+});
+test('getConfigLocation creates exactly one bucket across repeated calls (idempotent)', () => {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'Idempotent');
+    const a = getConfigLocation(stack);
+    const b = getConfigLocation(stack);
+    assert.strictEqual(a.key, b.key, 'same config key');
+    assert.strictEqual(a.bucketName, b.bucketName, 'same bucket');
+    const t = Template.fromStack(stack);
+    assert.strictEqual(Object.keys(t.findResources('AWS::S3::Bucket')).length, 1, 'exactly one bucket');
+});

package/dist/cdk/index.d.ts

@@ -2,27 +2,59 @@ import * as cdk from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { type BlocksStackProps, type BlocksStack as BaseBlocksStack, type ScopeParent, type ScopeOptions } from '../common/index.js';
 import { type BlocksDefaults } from './blocks-defaults.js';
-export { BlocksBackend, type BlocksBackendProps } from './blocks-backend.js';
+import type { Compute } from './compute/compute.js';
+import type { DefaultComputeFactory } from './compute/default-compute-factory.js';
+export { BlocksBackend, type BlocksBackendProps, type CoreBlocksBackendProps, SHARED_HANDLER_TIMEOUT_SECONDS, } from './blocks-backend.js';
 export { DEFAULT_NODE_RUNTIME } from './node-version.js';
 export { blocksNodejsBundling } from './bundling.js';
 export { SandboxDisableDeletionProtection } from './mixins.js';
-export { registerConfig, finalizeConfigRegistry } from './config-registry.js';
-export { type BlocksDefaults, BlocksPresets, } from './blocks-defaults.js';
+export { registerConfig, finalizeConfigRegistry, getConfigLocation } from './config-registry.js';
+export { ensureApiGatewayAccount } from './apigateway-account.js';
+export { type BlocksDefaults, type BlocksThrottling, BlocksPresets, } from './blocks-defaults.js';
 export { synthGuard } from './synth-guard.js';
 export type { ScopeOptions } from '../index.js';
 export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
+/**
+ * Core's `create()` props: the public {@link BlocksStackProps} plus the required
+ * `defaultComputeFactory`. The umbrella (`@aws-blocks/blocks`) supplies the
+ * factory (which builds a `LambdaCompute`) by spreading it onto the customer's
+ * props; customers use {@link BlocksStackProps} and never set the factory.
+ *
+ * Kept separate (rather than a `create()` argument) so the factory travels with
+ * the props object and core stays free of any concrete compute class.
+ *
+ * @internal
+ */
+export interface CoreBlocksStackProps extends BlocksStackProps {
+    /** Builds the stack's default compute. Injected by `@aws-blocks/blocks`. */
+    defaultComputeFactory: DefaultComputeFactory;
+}
 export declare class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     readonly id: string;
-    readonly apiUrl: string;
-    readonly gateway: cdk.aws_apigateway.RestApi;
-    readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
     readonly backendHandlerPath: string;
+    /**
+     * Path to the app's backend module (`props.backendCDKPath`). Exposed so Building Blocks that
+     * co-bundle the backend at synth (e.g. the Agent BB's AgentCore Runtime) can discover it via
+     * `globalThis.CURRENT_BLOCKS_STACK.backendModulePath`.
+     */
+    readonly backendModulePath: string;
     /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
     readonly executionRole: cdk.aws_iam.IRole;
     /** Infrastructure defaults for Building Blocks created under this stack. */
     readonly defaults: BlocksDefaults;
+    /** The default compute (owns the Lambda function + API Gateway); set in `create()`. @internal */
+    _defaultCompute?: Compute;
+    /** The default compute's Lambda function. To be removed once consumers move to the multi-compute model. */
+    get handler(): cdk.aws_lambda_nodejs.NodejsFunction;
+    /** The default compute's API Gateway REST API. To be removed once consumers move to the multi-compute model. */
+    get gateway(): cdk.aws_apigateway.RestApi;
+    /** The default compute's RPC endpoint URL. To be removed once consumers move to the multi-compute model. */
+    get apiUrl(): string;
+    /** The default compute's handler CloudWatch log group. `bb-logger` reconfigures its retention. */
+    get handlerLogGroup(): cdk.aws_logs.ILogGroup;
+    private requireDefaultCompute;
     private constructor();
-    static create(scope: Construct, id: string, props: BlocksStackProps): Promise<BlocksStack>;
+    static create(scope: Construct, id: string, props: CoreBlocksStackProps): Promise<BlocksStack>;
 }
 export declare class Scope extends Construct {
     readonly id: string;
@@ -37,6 +69,14 @@ export declare class Scope extends Construct {
      * tree walk.
      */
     private readonly root;
+    /**
+     * Compute assigned at this node. Applies to this block and is inherited by
+     * descendants (a nearer assignment wins). Covers both a handler assigned to a
+     * specific compute and a scope-level default for its subtree. Internal until
+     * the customer-facing surface exists.
+     * @internal
+     */
+    _compute?: Compute;
     constructor(id: string, options?: ScopeOptions);
     /**
      * Walk up the construct tree to the nearest owning BlocksStack/BlocksBackend;
@@ -51,6 +91,27 @@ export declare class Scope extends Construct {
      * route those grants to the role's default (inline) policy.
      */
     get executionRole(): cdk.aws_iam.IRole;
+    /**
+     * The compute this block runs on: the nearest `_compute` assigned on this
+     * block or an ancestor scope, else the owning stack/backend's default compute.
+     *
+     * For any app that doesn't assign a compute, this always resolves to the
+     * default — so reads are a no-op refactor. `_compute` is internal
+     * (test/framework) until the customer-facing surface exists; there is no
+     * public option to set it yet.
+     */
+    get compute(): Compute;
+    /**
+     * The stack's default compute, **ignoring** any per-scope `_compute`
+     * assignment (unlike {@link compute}, which resolves the nearest assigned
+     * one). Use when a resource is a stack-level singleton that must bind to one
+     * deterministic compute regardless of the block's resolved compute — e.g.
+     * Realtime's shared WebSocket route integration, where one WebSocket API
+     * integrates to a single target and connection bookkeeping is compute-agnostic.
+     *
+     * @internal Not a customer surface; for framework/BB singleton infra only.
+     */
+    get defaultCompute(): Compute;
     /**
      * The backend entry file the owning BlocksStack/BlocksBackend runs — the
      * single handler entry shared across the whole app.
@@ -65,6 +126,14 @@ export declare class Scope extends Construct {
      * as `fullId` ({@link BlocksBackend.fullId}); `BlocksStack` as `id`.
      */
     get backendStackName(): string;
+    /**
+     * The shared handler Lambda's CloudWatch log group (the default compute's).
+     * Resolves the same way as {@link handler} — via the owning
+     * BlocksStack/BlocksBackend. `bb-logger` uses this to reconfigure retention on
+     * the single, framework-owned group rather than creating a second one that
+     * would collide on the log-group name.
+     */
+    get handlerLogGroup(): cdk.aws_logs.ILogGroup;
     get fullId(): string;
     /**
      * The stack-wide infrastructure {@link BlocksDefaults} registered by

package/dist/cdk/index.d.ts.map

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

package/dist/cdk/index.js

@@ -9,35 +9,62 @@ import { setupBlocksInfra, BlocksBackend, assertCdkConditionActive } from './blo
 import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry } from './config-registry.js';
 import { BlocksPresets } from './blocks-defaults.js';
-export { BlocksBackend } from './blocks-backend.js';
+import { getComputes } from './compute/compute-registry.js';
+export { BlocksBackend, SHARED_HANDLER_TIMEOUT_SECONDS, } from './blocks-backend.js';
 export { DEFAULT_NODE_RUNTIME } from './node-version.js';
 export { blocksNodejsBundling } from './bundling.js';
 export { SandboxDisableDeletionProtection } from './mixins.js';
-export { registerConfig, finalizeConfigRegistry } from './config-registry.js';
+export { registerConfig, finalizeConfigRegistry, getConfigLocation } from './config-registry.js';
+export { ensureApiGatewayAccount } from './apigateway-account.js';
 export { BlocksPresets, } from './blocks-defaults.js';
 export { synthGuard } from './synth-guard.js';
 export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 export class BlocksStack extends cdk.Stack {
     id;
-    apiUrl;
-    gateway;
-    handler;
     backendHandlerPath;
+    /**
+     * Path to the app's backend module (`props.backendCDKPath`). Exposed so Building Blocks that
+     * co-bundle the backend at synth (e.g. the Agent BB's AgentCore Runtime) can discover it via
+     * `globalThis.CURRENT_BLOCKS_STACK.backendModulePath`.
+     */
+    backendModulePath;
     /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
     executionRole;
     /** Infrastructure defaults for Building Blocks created under this stack. */
     defaults;
+    /** The default compute (owns the Lambda function + API Gateway); set in `create()`. @internal */
+    _defaultCompute;
+    /** The default compute's Lambda function. To be removed once consumers move to the multi-compute model. */
+    get handler() {
+        return this.requireDefaultCompute().fn;
+    }
+    /** The default compute's API Gateway REST API. To be removed once consumers move to the multi-compute model. */
+    get gateway() {
+        return this.requireDefaultCompute().apiGateway;
+    }
+    /** The default compute's RPC endpoint URL. To be removed once consumers move to the multi-compute model. */
+    get apiUrl() {
+        return this.requireDefaultCompute().apiUrl;
+    }
+    /** The default compute's handler CloudWatch log group. `bb-logger` reconfigures its retention. */
+    get handlerLogGroup() {
+        return this.requireDefaultCompute().logGroup;
+    }
+    requireDefaultCompute() {
+        if (!this._defaultCompute) {
+            throw new Error('Blocks stack not fully initialized — access .handler/.gateway/.apiUrl after BlocksStack.create() resolves.');
+        }
+        return this._defaultCompute;
+    }
     constructor(scope, id, props) {
         super(scope, id, props);
         this.id = id;
         this.backendHandlerPath = props.backendHandlerPath;
         this.defaults = props.defaults;
+        this.backendModulePath = props.backendCDKPath;
         // Set globalThis so Building Blocks attach directly to this stack
         globalThis.CURRENT_BLOCKS_STACK = this;
         const infra = setupBlocksInfra(this, props, id);
-        this.handler = infra.handler;
-        this.gateway = infra.gateway;
-        this.apiUrl = infra.apiUrl;
         this.executionRole = infra.executionRole;
     }
     static async create(scope, id, props) {
@@ -46,6 +73,13 @@ export class BlocksStack extends cdk.Stack {
         const pipelineScope = globalThis[__PIPELINE_STAGE_SCOPE__];
         const actualScope = pipelineScope || scope;
         const stack = new BlocksStack(actualScope, id, props);
+        // Create the default compute before importing the backend: it OWNS the
+        // Lambda function + API Gateway (which back .handler/.gateway/.apiUrl), and
+        // a block reading `this.compute` in its constructor (during that import)
+        // must resolve to it. The factory is supplied by the umbrella
+        // @aws-blocks/blocks (which injects LambdaCompute) via props, so core never
+        // imports the concrete compute class.
+        stack._defaultCompute = props.defaultComputeFactory(stack);
         // file:// URL (not a raw path) so the cache-busting query works on Windows,
         // where an absolute path like `D:\...` is rejected as URL scheme `d:`.
         const backendUrl = pathToFileURL(props.backendCDKPath);
@@ -60,7 +94,7 @@ export class BlocksStack extends cdk.Stack {
             }
         }
         // Finalize BB config → S3 (after all BBs have registered their config)
-        finalizeConfigRegistry(stack, stack.handler);
+        finalizeConfigRegistry(stack, stack.executionRole, getComputes(stack));
         new cdk.CfnOutput(stack, 'ApiUrl', { value: stack.apiUrl });
         addBlocksStackMetadata(stack);
         return stack;
@@ -79,6 +113,14 @@ export class Scope extends Construct {
      * tree walk.
      */
     root;
+    /**
+     * Compute assigned at this node. Applies to this block and is inherited by
+     * descendants (a nearer assignment wins). Covers both a handler assigned to a
+     * specific compute and a scope-level default for its subtree. Internal until
+     * the customer-facing surface exists.
+     * @internal
+     */
+    _compute;
     constructor(id, options) {
         const parent = options?.parent || globalThis.CURRENT_BLOCKS_STACK;
         super(parent, id);
@@ -115,6 +157,44 @@ export class Scope extends Construct {
     get executionRole() {
         return this.root.executionRole;
     }
+    /**
+     * The compute this block runs on: the nearest `_compute` assigned on this
+     * block or an ancestor scope, else the owning stack/backend's default compute.
+     *
+     * For any app that doesn't assign a compute, this always resolves to the
+     * default — so reads are a no-op refactor. `_compute` is internal
+     * (test/framework) until the customer-facing surface exists; there is no
+     * public option to set it yet.
+     */
+    get compute() {
+        for (let current = this; current; current = current.parent) {
+            const assigned = current._compute;
+            if (assigned)
+                return assigned;
+        }
+        const defaultCompute = this.root._defaultCompute;
+        if (!defaultCompute) {
+            throw new Error('Default compute not initialized — BlocksStack/BlocksBackend.create() must run before resolving `compute`.');
+        }
+        return defaultCompute;
+    }
+    /**
+     * The stack's default compute, **ignoring** any per-scope `_compute`
+     * assignment (unlike {@link compute}, which resolves the nearest assigned
+     * one). Use when a resource is a stack-level singleton that must bind to one
+     * deterministic compute regardless of the block's resolved compute — e.g.
+     * Realtime's shared WebSocket route integration, where one WebSocket API
+     * integrates to a single target and connection bookkeeping is compute-agnostic.
+     *
+     * @internal Not a customer surface; for framework/BB singleton infra only.
+     */
+    get defaultCompute() {
+        const defaultCompute = this.root._defaultCompute;
+        if (!defaultCompute) {
+            throw new Error('Default compute not initialized — BlocksStack/BlocksBackend.create() must run before resolving `defaultCompute`.');
+        }
+        return defaultCompute;
+    }
     /**
      * The backend entry file the owning BlocksStack/BlocksBackend runs — the
      * single handler entry shared across the whole app.
@@ -137,6 +217,16 @@ export class Scope extends Construct {
         }
         return name;
     }
+    /**
+     * The shared handler Lambda's CloudWatch log group (the default compute's).
+     * Resolves the same way as {@link handler} — via the owning
+     * BlocksStack/BlocksBackend. `bb-logger` uses this to reconfigure retention on
+     * the single, framework-owned group rather than creating a second one that
+     * would collide on the log-group name.
+     */
+    get handlerLogGroup() {
+        return this.root.handlerLogGroup;
+    }
     get fullId() {
         return computeScopeFullId(this);
     }

package/dist/cdk/internal.d.ts

@@ -20,5 +20,6 @@
  * @internal
  */
 export { Compute } from './compute/compute.js';
+export type { DefaultComputeFactory } from './compute/default-compute-factory.js';
 export { BLOCKS_NAMESPACE } from '../constants.js';
 //# sourceMappingURL=internal.d.ts.map

package/dist/cdk/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/cdk/internal.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/cdk/internal.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAGlF,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/client/index.d.ts

@@ -92,6 +92,6 @@ export interface ApiNamespaceClientOptions {
  * ```
  */
 export declare function ApiNamespaceClient<T extends Record<string, (...args: any[]) => any>>(name: string, options?: ApiNamespaceClientOptions): AsyncAPI<T>;
-export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
+export { ApiError, blocksError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 export { Scope, type ScopeOptions } from '../common/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAChC,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC;AAiBhF,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAoHF;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,iKAAiK;IACjK,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,wHAAwH;IACxH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC7F,6FAA6F;IAC7F,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAErE;AAqBD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAClF,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,yBAAyB,GAClC,QAAQ,CAAC,CAAC,CAAC,CAyDb;AAED,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAChC,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC;AAiBhF,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAoHF;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,iKAAiK;IACjK,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,wHAAwH;IACxH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC7F,6FAA6F;IAC7F,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAErE;AAqBD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAClF,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,yBAAyB,GAClC,QAAQ,CAAC,CAAC,CAAC,CAyDb;AAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC1G,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/client/index.js

@@ -234,5 +234,5 @@ export function ApiNamespaceClient(name, options) {
         }
     });
 }
-export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
+export { ApiError, blocksError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 export { Scope } from '../common/index.js';

package/dist/common/config.d.ts

@@ -34,6 +34,40 @@ export declare function preloadConfig(): Promise<void>;
  * Only sets env vars that aren't already set (won't override explicit env vars).
  */
 export declare function loadConfigToProcessEnv(): Promise<void>;
+/**
+ * Whether a config load has resolved and cached a result.
+ *
+ * Returns `true` once `loadConfigFromS3()` has cached a config object — either a
+ * successful S3 load, a genuinely-empty `{}` config, or the no-bucket local-dev
+ * path (both of which cache `{}`). Returns `false` in the initial state AND
+ * after a transient not-found miss: the 404 path deliberately does NOT cache its
+ * empty result (see `loadConfigFromS3`), so a `false` return immediately after
+ * awaiting a load uniquely identifies the post-deploy S3 window where
+ * blocks-config.json isn't readable yet.
+ *
+ * Callers use this to tell a transient-empty load (retry on the next request)
+ * apart from a legitimately-config-less app (do nothing) without reaching into
+ * the module's private cache.
+ */
+export declare function isConfigResolved(): boolean;
+/**
+ * Sanitize a Blocks identifier into a valid config/env-var key segment:
+ * uppercase, with every non-alphanumeric character replaced by `_`.
+ *
+ * Config entries are loaded into `process.env` at runtime (see
+ * {@link loadConfigToProcessEnv}), so a key must be a valid env-var name. This
+ * is the single rule both sides of a key share: whoever *writes* a config key
+ * (`registerConfig(\`PREFIX_${sanitizeConfigKey(id)}\`, …)`) and whoever *reads*
+ * it (`getConfigSync(\`PREFIX_${sanitizeConfigKey(id)}\`)`) MUST go through this
+ * function so they reconstruct a byte-identical key — a hand-inlined variant
+ * that drifts silently misses the lookup at runtime.
+ *
+ * @example
+ * ```typescript
+ * registerConfig(this, `BLOCKS_QUEUE_URL_${sanitizeConfigKey(this.fullId)}`, url);
+ * ```
+ */
+export declare function sanitizeConfigKey(id: string): string;
 /**
  * Reset the config cache. **For testing only.**
  */

package/dist/common/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/common/config.ts"],"names":[],"mappings":"AA4FA;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAEtG"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/common/config.ts"],"names":[],"mappings":"AAgGA;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAEtG"}

package/dist/common/config.js

@@ -53,9 +53,13 @@ async function loadConfigFromS3() {
             || error?.Code === 'NoSuchKey'
             || error?.$metadata?.httpStatusCode === 404;
         if (isNotFound) {
-            console.warn(`[Blocks] Config file not found in S3 (${bucket}/${key}), proceeding with empty config`);
-            configCache = {};
-            return configCache;
+            // Do NOT cache the empty result: a 404 right after deploy is usually the config file
+            // not being readable yet (the transient window before the BucketDeployment settles), not
+            // a genuinely config-less app. Caching {} here would poison the container for its whole
+            // lifetime. Returning without caching lets the next invocation re-fetch and pick up the
+            // real config once it's present. (Apps that truly have no config just re-check cheaply.)
+            console.warn(`[Blocks] Config file not found in S3 (${bucket}/${key}), proceeding with empty config (will retry on next request)`);
+            return {};
         }
         const msg = error instanceof Error ? error.message : String(error);
         throw new Error(`[Blocks] Failed to load config from S3 (${bucket}/${key}): ${msg}`);
@@ -138,6 +142,44 @@ export async function loadConfigToProcessEnv() {
         }
     }
 }
+/**
+ * Whether a config load has resolved and cached a result.
+ *
+ * Returns `true` once `loadConfigFromS3()` has cached a config object — either a
+ * successful S3 load, a genuinely-empty `{}` config, or the no-bucket local-dev
+ * path (both of which cache `{}`). Returns `false` in the initial state AND
+ * after a transient not-found miss: the 404 path deliberately does NOT cache its
+ * empty result (see `loadConfigFromS3`), so a `false` return immediately after
+ * awaiting a load uniquely identifies the post-deploy S3 window where
+ * blocks-config.json isn't readable yet.
+ *
+ * Callers use this to tell a transient-empty load (retry on the next request)
+ * apart from a legitimately-config-less app (do nothing) without reaching into
+ * the module's private cache.
+ */
+export function isConfigResolved() {
+    return configCache !== null;
+}
+/**
+ * Sanitize a Blocks identifier into a valid config/env-var key segment:
+ * uppercase, with every non-alphanumeric character replaced by `_`.
+ *
+ * Config entries are loaded into `process.env` at runtime (see
+ * {@link loadConfigToProcessEnv}), so a key must be a valid env-var name. This
+ * is the single rule both sides of a key share: whoever *writes* a config key
+ * (`registerConfig(\`PREFIX_${sanitizeConfigKey(id)}\`, …)`) and whoever *reads*
+ * it (`getConfigSync(\`PREFIX_${sanitizeConfigKey(id)}\`)`) MUST go through this
+ * function so they reconstruct a byte-identical key — a hand-inlined variant
+ * that drifts silently misses the lookup at runtime.
+ *
+ * @example
+ * ```typescript
+ * registerConfig(this, `BLOCKS_QUEUE_URL_${sanitizeConfigKey(this.fullId)}`, url);
+ * ```
+ */
+export function sanitizeConfigKey(id) {
+    return id.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
 /**
  * Reset the config cache. **For testing only.**
  */

package/dist/common/config.test.js

@@ -101,6 +101,25 @@ describe('config — S3 errors', () => {
         const result = await getConfig('ANY_KEY');
         assert.strictEqual(result, '', 'Should return empty string (empty config) on 404');
     });
+    it('does not cache a not-found result — a later call re-fetches once the config exists', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        // Simulate the transient post-deploy window: the object isn't written yet on the first
+        // fetch, then becomes available. A not-found result must NOT be cached, or the container
+        // would be poisoned with empty config for its lifetime.
+        let call = 0;
+        const notFound = new Error('The specified key does not exist.');
+        notFound.name = 'NoSuchKey';
+        _setS3Fetcher(async () => {
+            call++;
+            if (call === 1)
+                throw notFound;
+            return JSON.stringify({ READY_KEY: 'ready-value' });
+        });
+        assert.strictEqual(await getConfig('READY_KEY'), '', 'first call sees the not-yet-written config as empty');
+        assert.strictEqual(await getConfig('READY_KEY'), 'ready-value', 'later call re-fetches once the config exists');
+        assert.strictEqual(call, 2, 'a not-found result must not be cached — S3 is retried');
+    });
     it('throws with clear message on S3 network error', async () => {
         process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
         process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';

package/dist/common/index.d.ts

@@ -224,6 +224,14 @@ export interface BlocksStackProps extends StackProps {
 }
 export declare class BlocksStack {
     readonly id: string;
+    /**
+     * Path to the app's backend module (`props.backendCDKPath`). A typed contract for Building
+     * Blocks that co-bundle the backend at synth time and read it off
+     * `globalThis.CURRENT_BLOCKS_STACK` (the CDK `BlocksStack` / `BlocksBackend` set it). Declared
+     * here so those consumers can type against this shared `BlocksStack` contract — which the CDK
+     * `BlocksStack` / `BlocksBackend` implements — instead of `any`.
+     */
+    readonly backendModulePath: string;
     constructor(scope: Construct, id: string, props: BlocksStackProps);
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAEH;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,KAAK;IAChB,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,WAAW,CAA8D;gBAE5E,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAiB9C;;;;;;;;OAQG;IACH,MAAM,CAAC,mBAAmB,IAAI;QAAE,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE;IAejI,2CAA2C;IAC3C,MAAM,CAAC,cAAc,IAAI,IAAI;IAI7B,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;;;;;OAUG;IACH,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAOlH;;;;OAIG;IACH,wBAAwB,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAIxD;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAIrD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,mBAAmB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;CAapD;AA0CD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,GAAG,CAAA;CAAE,UAUrE;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,qBAAa,WAAW;IACvB,SAAgB,EAAE,EAAE,MAAM,CAAC;gBACf,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB;CAGjE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAEH;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,KAAK;IAChB,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,WAAW,CAA8D;gBAE5E,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAiB9C;;;;;;;;OAQG;IACH,MAAM,CAAC,mBAAmB,IAAI;QAAE,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE;IAejI,2CAA2C;IAC3C,MAAM,CAAC,cAAc,IAAI,IAAI;IAI7B,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;;;;;OAUG;IACH,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAOlH;;;;OAIG;IACH,wBAAwB,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAIxD;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAIrD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,mBAAmB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;CAapD;AA0CD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,GAAG,CAAA;CAAE,UAUrE;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,qBAAa,WAAW;IACvB,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,SAAiB,iBAAiB,EAAE,MAAM,CAAC;gBAC/B,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB;CAGjE"}