@wildo-ai/saas-models 1.1.2 → 1.1.3

package/dist/esm/external-providers/provider-frontend-surface.shared.schemas.js

@@ -0,0 +1,332 @@
+/**
+ * Frontend-surface atoms a provider declares: what it needs the page to be
+ * ALLOWED to reach (its CSP footprint), which vendor SDK package it loads, and
+ * which third-party `<script>` tags it asks the surface to add.
+ *
+ * ## Why these are DATA and live here
+ *
+ * A frontend provider reaches its surface through TWO channels, and only one of
+ * them can carry code:
+ *
+ *   - the **DATA** channel — `FrontendProviderEntry`, projected by the backend
+ *     into `/application-config` and materialized into the generated
+ *     frontend-services artifact. It is JSON end to end, so nothing
+ *     function-valued survives it (it used to be cast to a module type anyway,
+ *     which is the defect this split closes);
+ *   - the **CODE** channel — the provider package's own facet barrel, imported
+ *     by the bundle through the generated `frontend-providers.generated.ts`.
+ *
+ * Everything in this file is the DATA half. It is what the CLI, the CSP
+ * composer and the bundle-isolation policy need to SEE without executing any
+ * frontend module — and the CLI genuinely cannot execute one: it is a Node
+ * process and these modules are browser-bound. The executable half (`sdk.activate`,
+ * `publicConfigSchema`) lives on the facet module types in
+ * `@wildo-ai/external-connectors-public` and never crosses this boundary.
+ *
+ * Added by slice S4a of epic #337 (issue #332).
+ */
+import { z } from 'zod';
+/**
+ * The origins a provider needs the composed Content-Security-Policy to admit,
+ * grouped by WHAT THE PROVIDER IS REACHING rather than by CSP directive name.
+ *
+ * ## Why semantic buckets and not directive names
+ *
+ * `CSP_DIRECTIVE_NAMES` is a closed vocabulary that already has one named
+ * runtime source, in `@wildo-ai/platform-config-lib`. That package DEPENDS on
+ * this one, so this file cannot reference it, and re-declaring the list here
+ * would create a second source for one vocabulary — precisely what the
+ * one-named-source rule exists to prevent, and the way the two copies would
+ * drift the first time a directive is added.
+ *
+ * Keying on intent instead is also the better contract. A provider author knows
+ * "my SDK is fetched from `https://js.stripe.com` and it calls back to
+ * `https://api.stripe.com`"; which directive grades which fetch is framework
+ * knowledge, and it lives in exactly one place — the bucket-to-directive
+ * mapping in `platform-config-lib`'s `csp-emit.ts`.
+ *
+ * ## Why it is STRICT while the entry that carries it is loose
+ *
+ * The entry is a WIRE record read by a possibly-older consumer, so it tolerates
+ * unknown keys (see `frontend-provider-entry.shared.schemas.ts`). This footprint
+ * is AUTHORED, by a provider package, and validated where it is authored — so a
+ * misspelled bucket must fail loudly rather than contribute nothing. That
+ * distinction matters more here than anywhere else in the frontend surface:
+ * CSP is enforced in production and report-only in development, so a bucket that
+ * silently contributes nothing is invisible until the provider breaks in
+ * production only.
+ *
+ * Adding a bucket is not a one-sided producer change either — a new bucket is
+ * useless until `csp-emit.ts` maps it to a directive — so strictness costs no
+ * version-skew tolerance that was ever available.
+ *
+ * Every field defaults to `[]`: a provider that declares a footprint at all is
+ * making a complete statement about the buckets it did not name.
+ */
+/**
+ * Which bucket an origin lands in, as a value a provider can name.
+ *
+ * The bucket names are already the footprint's field names; this enum is what
+ * lets a provider REFER to one — a derived origin has to say where it goes, and
+ * a bare string there would be a second, unexplained spelling of a closed
+ * vocabulary. A compile-time check below pins the two together.
+ */
+export var ProviderFrontendCspOriginBucket;
+(function (ProviderFrontendCspOriginBucket) {
+    ProviderFrontendCspOriginBucket["SCRIPT"] = "scriptOrigins";
+    ProviderFrontendCspOriginBucket["CONNECT"] = "connectOrigins";
+    ProviderFrontendCspOriginBucket["FRAME"] = "frameOrigins";
+    ProviderFrontendCspOriginBucket["IMG"] = "imgOrigins";
+    ProviderFrontendCspOriginBucket["STYLE"] = "styleOrigins";
+    ProviderFrontendCspOriginBucket["FONT"] = "fontOrigins";
+})(ProviderFrontendCspOriginBucket || (ProviderFrontendCspOriginBucket = {}));
+/**
+ * An origin the framework must READ OUT OF the provider's own public config,
+ * because the provider cannot know it.
+ *
+ * The case that forced this: an error-monitoring provider sends to the host
+ * inside its DSN, and a product-analytics provider to whatever `apiHost` the
+ * application configured — including a self-hosted one. Both are per
+ * APPLICATION, and often per ENVIRONMENT, so no static list on the provider
+ * module can contain them. Without this the application would have to author
+ * the same host twice — once as the provider's config and once in its CSP — and
+ * the copy that drifts fails in production only, because development is
+ * report-only.
+ *
+ * Resolution is data, not code: the CLI takes `publicConfig[publicConfigKey]`,
+ * reads its URL origin, and adds it to `bucket`. An absent key contributes
+ * nothing (the provider simply is not configured for that service); a key that
+ * is present and is NOT a URL fails the sync loudly, because silently dropping
+ * it is the exact failure this exists to prevent.
+ */
+export const ProviderFrontendCspDerivedOriginSchema = z.strictObject({
+    /** Key in this provider's `publicConfig` whose value is a URL. */
+    publicConfigKey: z.string().min(1),
+    bucket: z.enum(ProviderFrontendCspOriginBucket),
+});
+export const ProviderFrontendCspFootprintSchema = z.strictObject({
+    /** Origins the surface loads executable script from (`script-src`). */
+    scriptOrigins: z.array(z.string().min(1)).default([]),
+    /** Origins the provider's code opens fetch / XHR / WebSocket connections to (`connect-src`). */
+    connectOrigins: z.array(z.string().min(1)).default([]),
+    /** Origins the provider embeds in an iframe — a picker, a checkout, a meeting (`frame-src`). */
+    frameOrigins: z.array(z.string().min(1)).default([]),
+    /** Origins the provider loads images or pixels from (`img-src`). */
+    imgOrigins: z.array(z.string().min(1)).default([]),
+    /** Origins the provider loads stylesheets from (`style-src`). */
+    styleOrigins: z.array(z.string().min(1)).default([]),
+    /** Origins the provider loads web fonts from (`font-src`). */
+    fontOrigins: z.array(z.string().min(1)).default([]),
+    /**
+     * Origins the framework reads out of this provider's own `publicConfig`,
+     * for the endpoints a provider cannot know in advance. See
+     * {@link ProviderFrontendCspDerivedOriginSchema}.
+     */
+    derivedOrigins: z.array(ProviderFrontendCspDerivedOriginSchema).default([]),
+});
+/**
+ * Fills in the buckets a declaration did not name.
+ *
+ * The ONE place that normalization happens, used by the projection that builds
+ * an entry and by the hydration join that compares one against a module. Two
+ * copies would eventually disagree about whether an unnamed bucket is `[]` or
+ * absent, and the join reads that difference as a stale artifact — a false
+ * alarm on the diagnostic whose whole job is to be believed.
+ */
+export function normalizeProviderFrontendCspFootprint(declaration) {
+    return ProviderFrontendCspFootprintSchema.parse(declaration);
+}
+/**
+ * The DATA half of a provider's `sdk` declaration: WHICH npm package carries the
+ * vendor SDK, and at which range.
+ *
+ * The CODE half — the dynamic import and the vendor's initialization call — is
+ * `ProviderFrontendSdk.activate` on the facet module type, and is deliberately
+ * absent here: a function cannot cross a JSON channel, and a channel that
+ * silently drops one is worse than a channel that never carried it.
+ *
+ * The descriptor is not decoration. It is what the bundle-isolation policy reads
+ * to decide whether a bare specifier a provider package imports was DECLARED,
+ * what an application's dependency alignment needs in order to install the SDK
+ * as an optional peer, and what a human reads when asking why a bundle grew.
+ *
+ * Who authors it, since the epic's bulk-integration model was reversed on
+ * 2026-09-06: a FIRST-CLASS provider package or an application's own provider
+ * module. The scraper-mapper that fills the catalogue emits identity, auth, a
+ * secrets contract and an operation catalogue on the `rest` arm — a
+ * backend-only package — so a scraped provider has no frontend facet to carry
+ * this. That is a narrowing of the population, not of the contract: the pickers
+ * and embeds this surface exists for were always the hand-authored kind.
+ */
+export const ProviderFrontendSdkDescriptorSchema = z.strictObject({
+    /** npm package name of the vendor SDK, e.g. `@sentry/browser`. */
+    packageName: z.string().min(1),
+    /**
+     * Semver range the provider was built against. Optional because a provider
+     * that pins its SDK as a direct dependency has already said so in its own
+     * manifest; stating it here as well would be a second copy of that pin.
+     */
+    versionRange: z.string().min(1).optional(),
+});
+/**
+ * `crossorigin` attribute values for a provider-declared `<script>`.
+ *
+ * A closed vocabulary with a named runtime source rather than a bare literal
+ * union, so each member can carry why it exists — and there are exactly two
+ * reasons to pick one over the other.
+ */
+export var ProviderFrontendScriptCrossOrigin;
+(function (ProviderFrontendScriptCrossOrigin) {
+    /** No credentials are sent; the response must carry `Access-Control-Allow-Origin`. The right choice for a public CDN script. */
+    ProviderFrontendScriptCrossOrigin["ANONYMOUS"] = "anonymous";
+    /** Cookies and TLS client certificates are sent. Only for a vendor that authenticates the script fetch itself. */
+    ProviderFrontendScriptCrossOrigin["USE_CREDENTIALS"] = "use-credentials";
+})(ProviderFrontendScriptCrossOrigin || (ProviderFrontendScriptCrossOrigin = {}));
+/**
+ * A third-party `<script>` a provider asks its surface to add — the case a
+ * dynamic `import()` cannot serve, because the vendor ships a global-installing
+ * tag rather than an npm module (reCAPTCHA, most tag managers, several chat
+ * widgets).
+ *
+ * `integrity` is Subresource Integrity. It is optional because a vendor that
+ * versionless-serves a mutable URL (again, reCAPTCHA) cannot publish a stable
+ * hash — but when it IS given the surface must also send `crossorigin`, or the
+ * browser refuses the integrity check outright. That coupling is enforced below
+ * rather than left to each surface to remember.
+ */
+export const ProviderFrontendScriptDeclarationSchema = z
+    .strictObject({
+    /** Absolute URL of the script. Its origin must also appear in `csp.scriptOrigins`. */
+    src: z.string().min(1),
+    /** Subresource-integrity hash, e.g. `sha384-…`. */
+    integrity: z.string().min(1).optional(),
+    crossOrigin: z.enum(ProviderFrontendScriptCrossOrigin).optional(),
+    async: z.boolean().optional(),
+    defer: z.boolean().optional(),
+})
+    .superRefine((declaration, context) => {
+    if (declaration.integrity !== undefined && declaration.crossOrigin === undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: ['crossOrigin'],
+            message: 'A script declaring `integrity` must also declare `crossOrigin`; without it the browser skips the '
+                + 'integrity check for a cross-origin script, so the hash would protect nothing.',
+        });
+    }
+});
+/**
+ * WHAT a provider's component hands back, when what it hands back is a thing
+ * rather than a value.
+ *
+ * ## The question this answers, and why it is a DECLARATION
+ *
+ * An application's objective is that it calls third-party APIs directly from
+ * custom frontend components. On the backend that is unambiguous. In a browser
+ * it is not, because a tenant credential must never get there — so a picker for
+ * a credentialed vendor and a picker for a vendor with a browser-safe public
+ * token cannot hand back the same thing, and the framework surface that
+ * receives a selection has to know which before it mounts anything.
+ *
+ * Settled 2026-09-07 (issue #383, recorded as Q5 of the provider-architecture
+ * plan): **per vendor, DECLARED.** Both shapes are real and both ship; which one
+ * a provider emits is a static fact about that provider, stated here and
+ * visible on the DATA channel without executing a line of its code.
+ *
+ * The word doing the work is *declared*. A discriminated union alone would let a
+ * provider decide at runtime, which is the shape the decision explicitly
+ * rejected — so the framework REFUSES a selection whose discriminant contradicts
+ * this field. Without that refusal the declaration is decoration, and a reviewer
+ * reading a provider's manifest would be reading a wish.
+ *
+ * ## Why a single value and not a set
+ *
+ * A provider that genuinely could emit either — Google's Picker hands back both
+ * a file id and a URL, and which is usable depends on the granted OAuth scope —
+ * was the argument for `selectionDelivery: [...]`. Rejected: an array puts the
+ * choice back at runtime, which is the half of the decision that carries all the
+ * weight. A vendor whose two modes are both wanted contributes two components,
+ * and the chooser then shows them as what they are — two different things a user
+ * can pick between — rather than one component whose behaviour a reader cannot
+ * predict.
+ *
+ * ## What it means for CSP
+ *
+ * `REMOTE_REFERENCE` does NOT imply a provider needs no `connectOrigins`: a
+ * picker still talks to its vendor to RENDER, even when the bytes it selects are
+ * fetched later by the backend. So this field does not gate the CSP buckets, and
+ * a guard inferring otherwise would break every real picker. What it does gate
+ * is where the SELECTED OBJECT travels.
+ */
+export var ProviderFrontendSelectionDelivery;
+(function (ProviderFrontendSelectionDelivery) {
+    /**
+     * An opaque handle only the application backend can resolve — a Drive file id,
+     * a DAM asset key. The browser never holds the bytes and never authenticates
+     * to the vendor for them; the framework routes the reference to the
+     * application's executor door, which holds the tenant credential.
+     */
+    ProviderFrontendSelectionDelivery["REMOTE_REFERENCE"] = "REMOTE_REFERENCE";
+    /**
+     * Bytes the browser already holds, as a `File`. Available only to a vendor
+     * whose picker runs on a browser-safe grant — a publishable key, a
+     * user-consented OAuth token, a picker's own scoped grant — so nothing
+     * tenant-secret is involved. The framework uploads it exactly as it uploads a
+     * file chosen from disk.
+     */
+    ProviderFrontendSelectionDelivery["BROWSER_READABLE_FILE"] = "BROWSER_READABLE_FILE";
+    /**
+     * A URL the browser may fetch, under the same browser-safe-grant condition as
+     * `BROWSER_READABLE_FILE`. Distinct from it because the framework must fetch
+     * before it can upload, and that fetch is a network call the composed CSP has
+     * to admit — a difference the surface cannot discover from a `File`.
+     */
+    ProviderFrontendSelectionDelivery["BROWSER_READABLE_URL"] = "BROWSER_READABLE_URL";
+})(ProviderFrontendSelectionDelivery || (ProviderFrontendSelectionDelivery = {}));
+/**
+ * The DATA half of one component a provider contributes — everything about it
+ * that a reviewer, the CLI or a build step can read without running a browser.
+ *
+ * The loader is the CODE half and stays on the facet module in
+ * `@wildo-ai/external-connectors-public`, exactly as `sdk.activate` does. What
+ * crosses the wire is the fact that a component EXISTS for this capability, plus
+ * the contract it commits to.
+ *
+ * Strict, and for the same reason the CSP footprint is: this is AUTHORED by a
+ * provider package rather than received from an older producer, so a misspelled
+ * key must fail where it is written instead of contributing nothing.
+ */
+export const ProviderFrontendComponentDescriptorSchema = z.strictObject({
+    /**
+     * What a selection from this component contains. Absent for a capability whose
+     * component returns a plain value rather than a thing — a captcha widget hands
+     * back a token, and there is no delivery question to answer about a string.
+     */
+    selectionDelivery: z.enum(ProviderFrontendSelectionDelivery).optional(),
+});
+/**
+ * A provider's component descriptors, keyed by the CAPABILITY each fills.
+ *
+ * The key is a capability token rather than a member of a closed enum because
+ * `ProviderCapability` is OPEN — an application extends it by module
+ * augmentation — so a `z.enum` here would refuse an application's own
+ * capability. The registry that consumes this makes the same choice for the same
+ * reason.
+ */
+export const ProviderFrontendComponentDescriptorsSchema = z.record(z.string().min(1), ProviderFrontendComponentDescriptorSchema);
+/**
+ * Pins every bucket member to a real field of the footprint.
+ *
+ * A member whose value is not a footprint key would be authorable, would parse,
+ * and would contribute nothing — in production only, because CSP is report-only
+ * in development. This makes it a compile error instead.
+ */
+const _everyBucketNamesAFootprintField = {
+    [ProviderFrontendCspOriginBucket.SCRIPT]: 'scriptOrigins',
+    [ProviderFrontendCspOriginBucket.CONNECT]: 'connectOrigins',
+    [ProviderFrontendCspOriginBucket.FRAME]: 'frameOrigins',
+    [ProviderFrontendCspOriginBucket.IMG]: 'imgOrigins',
+    [ProviderFrontendCspOriginBucket.STYLE]: 'styleOrigins',
+    [ProviderFrontendCspOriginBucket.FONT]: 'fontOrigins',
+};
+void _everyBucketNamesAFootprintField;
+//# sourceMappingURL=provider-frontend-surface.shared.schemas.js.map

package/dist/esm/external-providers/provider-frontend-surface.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-frontend-surface.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-frontend-surface.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Frontend-surface atoms a provider declares: what it needs the page to be\n * ALLOWED to reach (its CSP footprint), which vendor SDK package it loads, and\n * which third-party `<script>` tags it asks the surface to add.\n *\n * ## Why these are DATA and live here\n *\n * A frontend provider reaches its surface through TWO channels, and only one of\n * them can carry code:\n *\n *   - the **DATA** channel — `FrontendProviderEntry`, projected by the backend\n *     into `/application-config` and materialized into the generated\n *     frontend-services artifact. It is JSON end to end, so nothing\n *     function-valued survives it (it used to be cast to a module type anyway,\n *     which is the defect this split closes);\n *   - the **CODE** channel — the provider package's own facet barrel, imported\n *     by the bundle through the generated `frontend-providers.generated.ts`.\n *\n * Everything in this file is the DATA half. It is what the CLI, the CSP\n * composer and the bundle-isolation policy need to SEE without executing any\n * frontend module — and the CLI genuinely cannot execute one: it is a Node\n * process and these modules are browser-bound. The executable half (`sdk.activate`,\n * `publicConfigSchema`) lives on the facet module types in\n * `@wildo-ai/external-connectors-public` and never crosses this boundary.\n *\n * Added by slice S4a of epic #337 (issue #332).\n */\n\nimport { z } from 'zod';\n\n/**\n * The origins a provider needs the composed Content-Security-Policy to admit,\n * grouped by WHAT THE PROVIDER IS REACHING rather than by CSP directive name.\n *\n * ## Why semantic buckets and not directive names\n *\n * `CSP_DIRECTIVE_NAMES` is a closed vocabulary that already has one named\n * runtime source, in `@wildo-ai/platform-config-lib`. That package DEPENDS on\n * this one, so this file cannot reference it, and re-declaring the list here\n * would create a second source for one vocabulary — precisely what the\n * one-named-source rule exists to prevent, and the way the two copies would\n * drift the first time a directive is added.\n *\n * Keying on intent instead is also the better contract. A provider author knows\n * \"my SDK is fetched from `https://js.stripe.com` and it calls back to\n * `https://api.stripe.com`\"; which directive grades which fetch is framework\n * knowledge, and it lives in exactly one place — the bucket-to-directive\n * mapping in `platform-config-lib`'s `csp-emit.ts`.\n *\n * ## Why it is STRICT while the entry that carries it is loose\n *\n * The entry is a WIRE record read by a possibly-older consumer, so it tolerates\n * unknown keys (see `frontend-provider-entry.shared.schemas.ts`). This footprint\n * is AUTHORED, by a provider package, and validated where it is authored — so a\n * misspelled bucket must fail loudly rather than contribute nothing. That\n * distinction matters more here than anywhere else in the frontend surface:\n * CSP is enforced in production and report-only in development, so a bucket that\n * silently contributes nothing is invisible until the provider breaks in\n * production only.\n *\n * Adding a bucket is not a one-sided producer change either — a new bucket is\n * useless until `csp-emit.ts` maps it to a directive — so strictness costs no\n * version-skew tolerance that was ever available.\n *\n * Every field defaults to `[]`: a provider that declares a footprint at all is\n * making a complete statement about the buckets it did not name.\n */\n/**\n * Which bucket an origin lands in, as a value a provider can name.\n *\n * The bucket names are already the footprint's field names; this enum is what\n * lets a provider REFER to one — a derived origin has to say where it goes, and\n * a bare string there would be a second, unexplained spelling of a closed\n * vocabulary. A compile-time check below pins the two together.\n */\nexport enum ProviderFrontendCspOriginBucket {\n  SCRIPT = 'scriptOrigins',\n  CONNECT = 'connectOrigins',\n  FRAME = 'frameOrigins',\n  IMG = 'imgOrigins',\n  STYLE = 'styleOrigins',\n  FONT = 'fontOrigins',\n}\n\n/**\n * An origin the framework must READ OUT OF the provider's own public config,\n * because the provider cannot know it.\n *\n * The case that forced this: an error-monitoring provider sends to the host\n * inside its DSN, and a product-analytics provider to whatever `apiHost` the\n * application configured — including a self-hosted one. Both are per\n * APPLICATION, and often per ENVIRONMENT, so no static list on the provider\n * module can contain them. Without this the application would have to author\n * the same host twice — once as the provider's config and once in its CSP — and\n * the copy that drifts fails in production only, because development is\n * report-only.\n *\n * Resolution is data, not code: the CLI takes `publicConfig[publicConfigKey]`,\n * reads its URL origin, and adds it to `bucket`. An absent key contributes\n * nothing (the provider simply is not configured for that service); a key that\n * is present and is NOT a URL fails the sync loudly, because silently dropping\n * it is the exact failure this exists to prevent.\n */\nexport const ProviderFrontendCspDerivedOriginSchema = z.strictObject({\n  /** Key in this provider's `publicConfig` whose value is a URL. */\n  publicConfigKey: z.string().min(1),\n  bucket: z.enum(ProviderFrontendCspOriginBucket),\n});\nexport type ProviderFrontendCspDerivedOrigin = z.infer<typeof ProviderFrontendCspDerivedOriginSchema>;\n\nexport const ProviderFrontendCspFootprintSchema = z.strictObject({\n  /** Origins the surface loads executable script from (`script-src`). */\n  scriptOrigins: z.array(z.string().min(1)).default([]),\n  /** Origins the provider's code opens fetch / XHR / WebSocket connections to (`connect-src`). */\n  connectOrigins: z.array(z.string().min(1)).default([]),\n  /** Origins the provider embeds in an iframe — a picker, a checkout, a meeting (`frame-src`). */\n  frameOrigins: z.array(z.string().min(1)).default([]),\n  /** Origins the provider loads images or pixels from (`img-src`). */\n  imgOrigins: z.array(z.string().min(1)).default([]),\n  /** Origins the provider loads stylesheets from (`style-src`). */\n  styleOrigins: z.array(z.string().min(1)).default([]),\n  /** Origins the provider loads web fonts from (`font-src`). */\n  fontOrigins: z.array(z.string().min(1)).default([]),\n  /**\n   * Origins the framework reads out of this provider's own `publicConfig`,\n   * for the endpoints a provider cannot know in advance. See\n   * {@link ProviderFrontendCspDerivedOriginSchema}.\n   */\n  derivedOrigins: z.array(ProviderFrontendCspDerivedOriginSchema).default([]),\n});\nexport type ProviderFrontendCspFootprint = z.infer<typeof ProviderFrontendCspFootprintSchema>;\n\n/**\n * The footprint as a provider AUTHORS it: name only the buckets you reach.\n *\n * Authoring and the wire are deliberately different shapes, and the asymmetry\n * is the point.\n *\n *   - **Authoring is partial.** A provider that only loads a script should write\n *     `{ scriptOrigins: ['https://js.acme.com'] }`, not that plus four empty\n *     arrays. Four empty arrays are noise at exactly the place the declaration\n *     should be readable, and noise is what stops a reviewer noticing the one\n *     line that grants an origin.\n *   - **The wire is total.** Every bucket is present by the time the footprint\n *     reaches an entry, so the CSP composer never branches on absence and the\n *     staleness comparison between a served footprint and its module's has two\n *     comparable shapes rather than a partial and a total that differ in every\n *     bucket nobody named.\n *\n * Derived as `z.input` rather than written as a `Partial<…>`, so it cannot drift\n * from the schema: adding a bucket makes it optional here automatically.\n */\nexport type ProviderFrontendCspFootprintDeclaration = z.input<typeof ProviderFrontendCspFootprintSchema>;\n\n/**\n * Fills in the buckets a declaration did not name.\n *\n * The ONE place that normalization happens, used by the projection that builds\n * an entry and by the hydration join that compares one against a module. Two\n * copies would eventually disagree about whether an unnamed bucket is `[]` or\n * absent, and the join reads that difference as a stale artifact — a false\n * alarm on the diagnostic whose whole job is to be believed.\n */\nexport function normalizeProviderFrontendCspFootprint(\n  declaration: ProviderFrontendCspFootprintDeclaration,\n): ProviderFrontendCspFootprint {\n  return ProviderFrontendCspFootprintSchema.parse(declaration);\n}\n\n/**\n * The DATA half of a provider's `sdk` declaration: WHICH npm package carries the\n * vendor SDK, and at which range.\n *\n * The CODE half — the dynamic import and the vendor's initialization call — is\n * `ProviderFrontendSdk.activate` on the facet module type, and is deliberately\n * absent here: a function cannot cross a JSON channel, and a channel that\n * silently drops one is worse than a channel that never carried it.\n *\n * The descriptor is not decoration. It is what the bundle-isolation policy reads\n * to decide whether a bare specifier a provider package imports was DECLARED,\n * what an application's dependency alignment needs in order to install the SDK\n * as an optional peer, and what a human reads when asking why a bundle grew.\n *\n * Who authors it, since the epic's bulk-integration model was reversed on\n * 2026-09-06: a FIRST-CLASS provider package or an application's own provider\n * module. The scraper-mapper that fills the catalogue emits identity, auth, a\n * secrets contract and an operation catalogue on the `rest` arm — a\n * backend-only package — so a scraped provider has no frontend facet to carry\n * this. That is a narrowing of the population, not of the contract: the pickers\n * and embeds this surface exists for were always the hand-authored kind.\n */\nexport const ProviderFrontendSdkDescriptorSchema = z.strictObject({\n  /** npm package name of the vendor SDK, e.g. `@sentry/browser`. */\n  packageName: z.string().min(1),\n  /**\n   * Semver range the provider was built against. Optional because a provider\n   * that pins its SDK as a direct dependency has already said so in its own\n   * manifest; stating it here as well would be a second copy of that pin.\n   */\n  versionRange: z.string().min(1).optional(),\n});\nexport type ProviderFrontendSdkDescriptor = z.infer<typeof ProviderFrontendSdkDescriptorSchema>;\n\n/**\n * `crossorigin` attribute values for a provider-declared `<script>`.\n *\n * A closed vocabulary with a named runtime source rather than a bare literal\n * union, so each member can carry why it exists — and there are exactly two\n * reasons to pick one over the other.\n */\nexport enum ProviderFrontendScriptCrossOrigin {\n  /** No credentials are sent; the response must carry `Access-Control-Allow-Origin`. The right choice for a public CDN script. */\n  ANONYMOUS = 'anonymous',\n  /** Cookies and TLS client certificates are sent. Only for a vendor that authenticates the script fetch itself. */\n  USE_CREDENTIALS = 'use-credentials',\n}\n\n/**\n * A third-party `<script>` a provider asks its surface to add — the case a\n * dynamic `import()` cannot serve, because the vendor ships a global-installing\n * tag rather than an npm module (reCAPTCHA, most tag managers, several chat\n * widgets).\n *\n * `integrity` is Subresource Integrity. It is optional because a vendor that\n * versionless-serves a mutable URL (again, reCAPTCHA) cannot publish a stable\n * hash — but when it IS given the surface must also send `crossorigin`, or the\n * browser refuses the integrity check outright. That coupling is enforced below\n * rather than left to each surface to remember.\n */\nexport const ProviderFrontendScriptDeclarationSchema = z\n  .strictObject({\n    /** Absolute URL of the script. Its origin must also appear in `csp.scriptOrigins`. */\n    src: z.string().min(1),\n    /** Subresource-integrity hash, e.g. `sha384-…`. */\n    integrity: z.string().min(1).optional(),\n    crossOrigin: z.enum(ProviderFrontendScriptCrossOrigin).optional(),\n    async: z.boolean().optional(),\n    defer: z.boolean().optional(),\n  })\n  .superRefine((declaration, context) => {\n    if (declaration.integrity !== undefined && declaration.crossOrigin === undefined) {\n      context.addIssue({\n        code: 'custom',\n        path: ['crossOrigin'],\n        message:\n          'A script declaring `integrity` must also declare `crossOrigin`; without it the browser skips the '\n          + 'integrity check for a cross-origin script, so the hash would protect nothing.',\n      });\n    }\n  });\nexport type ProviderFrontendScriptDeclaration = z.infer<typeof ProviderFrontendScriptDeclarationSchema>;\n\n/**\n * WHAT a provider's component hands back, when what it hands back is a thing\n * rather than a value.\n *\n * ## The question this answers, and why it is a DECLARATION\n *\n * An application's objective is that it calls third-party APIs directly from\n * custom frontend components. On the backend that is unambiguous. In a browser\n * it is not, because a tenant credential must never get there — so a picker for\n * a credentialed vendor and a picker for a vendor with a browser-safe public\n * token cannot hand back the same thing, and the framework surface that\n * receives a selection has to know which before it mounts anything.\n *\n * Settled 2026-09-07 (issue #383, recorded as Q5 of the provider-architecture\n * plan): **per vendor, DECLARED.** Both shapes are real and both ship; which one\n * a provider emits is a static fact about that provider, stated here and\n * visible on the DATA channel without executing a line of its code.\n *\n * The word doing the work is *declared*. A discriminated union alone would let a\n * provider decide at runtime, which is the shape the decision explicitly\n * rejected — so the framework REFUSES a selection whose discriminant contradicts\n * this field. Without that refusal the declaration is decoration, and a reviewer\n * reading a provider's manifest would be reading a wish.\n *\n * ## Why a single value and not a set\n *\n * A provider that genuinely could emit either — Google's Picker hands back both\n * a file id and a URL, and which is usable depends on the granted OAuth scope —\n * was the argument for `selectionDelivery: [...]`. Rejected: an array puts the\n * choice back at runtime, which is the half of the decision that carries all the\n * weight. A vendor whose two modes are both wanted contributes two components,\n * and the chooser then shows them as what they are — two different things a user\n * can pick between — rather than one component whose behaviour a reader cannot\n * predict.\n *\n * ## What it means for CSP\n *\n * `REMOTE_REFERENCE` does NOT imply a provider needs no `connectOrigins`: a\n * picker still talks to its vendor to RENDER, even when the bytes it selects are\n * fetched later by the backend. So this field does not gate the CSP buckets, and\n * a guard inferring otherwise would break every real picker. What it does gate\n * is where the SELECTED OBJECT travels.\n */\nexport enum ProviderFrontendSelectionDelivery {\n  /**\n   * An opaque handle only the application backend can resolve — a Drive file id,\n   * a DAM asset key. The browser never holds the bytes and never authenticates\n   * to the vendor for them; the framework routes the reference to the\n   * application's executor door, which holds the tenant credential.\n   */\n  REMOTE_REFERENCE = 'REMOTE_REFERENCE',\n  /**\n   * Bytes the browser already holds, as a `File`. Available only to a vendor\n   * whose picker runs on a browser-safe grant — a publishable key, a\n   * user-consented OAuth token, a picker's own scoped grant — so nothing\n   * tenant-secret is involved. The framework uploads it exactly as it uploads a\n   * file chosen from disk.\n   */\n  BROWSER_READABLE_FILE = 'BROWSER_READABLE_FILE',\n  /**\n   * A URL the browser may fetch, under the same browser-safe-grant condition as\n   * `BROWSER_READABLE_FILE`. Distinct from it because the framework must fetch\n   * before it can upload, and that fetch is a network call the composed CSP has\n   * to admit — a difference the surface cannot discover from a `File`.\n   */\n  BROWSER_READABLE_URL = 'BROWSER_READABLE_URL',\n}\n\n/**\n * The DATA half of one component a provider contributes — everything about it\n * that a reviewer, the CLI or a build step can read without running a browser.\n *\n * The loader is the CODE half and stays on the facet module in\n * `@wildo-ai/external-connectors-public`, exactly as `sdk.activate` does. What\n * crosses the wire is the fact that a component EXISTS for this capability, plus\n * the contract it commits to.\n *\n * Strict, and for the same reason the CSP footprint is: this is AUTHORED by a\n * provider package rather than received from an older producer, so a misspelled\n * key must fail where it is written instead of contributing nothing.\n */\nexport const ProviderFrontendComponentDescriptorSchema = z.strictObject({\n  /**\n   * What a selection from this component contains. Absent for a capability whose\n   * component returns a plain value rather than a thing — a captcha widget hands\n   * back a token, and there is no delivery question to answer about a string.\n   */\n  selectionDelivery: z.enum(ProviderFrontendSelectionDelivery).optional(),\n});\nexport type ProviderFrontendComponentDescriptor = z.infer<typeof ProviderFrontendComponentDescriptorSchema>;\n\n/**\n * A provider's component descriptors, keyed by the CAPABILITY each fills.\n *\n * The key is a capability token rather than a member of a closed enum because\n * `ProviderCapability` is OPEN — an application extends it by module\n * augmentation — so a `z.enum` here would refuse an application's own\n * capability. The registry that consumes this makes the same choice for the same\n * reason.\n */\nexport const ProviderFrontendComponentDescriptorsSchema = z.record(\n  z.string().min(1),\n  ProviderFrontendComponentDescriptorSchema,\n);\nexport type ProviderFrontendComponentDescriptors = z.infer<typeof ProviderFrontendComponentDescriptorsSchema>;\n\n/**\n * Pins every bucket member to a real field of the footprint.\n *\n * A member whose value is not a footprint key would be authorable, would parse,\n * and would contribute nothing — in production only, because CSP is report-only\n * in development. This makes it a compile error instead.\n */\nconst _everyBucketNamesAFootprintField: Record<\n  ProviderFrontendCspOriginBucket,\n  keyof Omit<ProviderFrontendCspFootprint, 'derivedOrigins'>\n> = {\n  [ProviderFrontendCspOriginBucket.SCRIPT]: 'scriptOrigins',\n  [ProviderFrontendCspOriginBucket.CONNECT]: 'connectOrigins',\n  [ProviderFrontendCspOriginBucket.FRAME]: 'frameOrigins',\n  [ProviderFrontendCspOriginBucket.IMG]: 'imgOrigins',\n  [ProviderFrontendCspOriginBucket.STYLE]: 'styleOrigins',\n  [ProviderFrontendCspOriginBucket.FONT]: 'fontOrigins',\n};\nvoid _everyBucketNamesAFootprintField;\n"]}

package/dist/esm/external-providers/provider-metadata.shared.schemas.d.ts

@@ -7,16 +7,24 @@
  * contracts, no backend behavior. The fields are exactly what a UI needs
  * to render a provider entry (translation-ready display-name key, optional
  * legacy fallback label, optional icon ref) plus the stable `ref` used as
- * the join key between facet modules.
+ * the join key between facet modules — and, since #328, the provider's
+ * IDENTITY: which package ships it, which tier it belongs to, which vendor
+ * groups it, and where it came from.
  *
- * Phase 0 of the provider-registration refactor introduces this type as
- * the single source of truth for provider header information so that the
- * cross-facet seam (`FrontendBootstrapBackendService`) can project a
- * `BackendProviderModule` into a `FrontendProviderEntry` without ever
- * leaking backend-only fields.
+ * ## Why identity lives here and not on the ref
  *
- * See `.cursor/plans/provider-registration-refactor-implementation-plan.md`
- * §Phase 0.1 for the full rationale.
+ * A bare `ref` string cannot say whether a provider is one the engine
+ * REQUIRES (a MAIN provider binding an `EngineCapability` slot), one that
+ * merely MAY bind a slot as a substitute (EXTENSION), or one of the bulk
+ * loaded on demand that must never claim a slot (CATALOGUE). Nor can it say
+ * that `microsoft-graph-mail` and `microsoft-teams` are two packages of one
+ * vendor sharing an OAuth client. Encoding any of that in the ref's
+ * spelling is invisible to the compiler and to every consumer; encoding it
+ * as fields is what lets composition ENFORCE the tier rule
+ * (`assertProviderTierCoherence`) and lets tooling display and group.
+ *
+ * The identity fields are REQUIRED. A provider without a tier is a provider
+ * nobody has decided about, and "undecided" must not parse as "fine".
  */
 import { z } from 'zod';
 /**
@@ -27,11 +35,172 @@ import { z } from 'zod';
  * time instead of freezing human copy into generated/runtime artifacts.
  */
 export declare function buildProviderDisplayNameLabelKey(providerRef: string): string;
+/**
+ * The three provider tiers (decided 2026-09-05, epic #337).
+ *
+ * The tier is a DECISION recorded on the module, never inferred from its
+ * capabilities at runtime — inference is silent and wrong for a provider
+ * such as Odoo, whose empty capability list says nothing about whether the
+ * engine depends on it.
+ */
+export declare enum ProviderTier {
+    /**
+     * Mandatory, engine-shipped. Binds an `EngineCapability` slot the engine
+     * itself consumes (email, billing, SMS, the AI slots) or is an SSO login
+     * provider the auth subsystem consumes. MAIN is the engine's own set:
+     * its origin is always `ENGINE`, and it is what stays in the static
+     * engine registry when everything else loads on demand.
+     */
+    MAIN = "MAIN",
+    /**
+     * May ALSO bind an engine slot, as a substitute for a MAIN provider
+     * (a second email sink, a telemetry sink, an audit sink). Kept distinct
+     * from MAIN so the engine's floor is not confused with what happens to
+     * be installed.
+     */
+    EXTENSION = "EXTENSION",
+    /**
+     * The bulk: integrations with no engine slot, loaded on demand when an
+     * application declares them. A CATALOGUE provider may claim only OPEN
+     * `ProviderCapability` tokens — never one that maps to an engine slot —
+     * which composition enforces.
+     */
+    CATALOGUE = "CATALOGUE"
+}
+/** Where a provider module's code comes from. */
+export declare enum ProviderOriginKind {
+    /** Shipped by the framework's own connector packages. */
+    ENGINE = "ENGINE",
+    /** Authored inside an application (its own `provider-contributions`). */
+    APPLICATION = "APPLICATION",
+    /**
+     * Emitted by the framework packager from an external catalogue source;
+     * carries the catalogue provenance so the wrapped upstream artifact can
+     * be named, attributed and re-generated.
+     */
+    GENERATED = "GENERATED"
+}
+/**
+ * External catalogues a build-time MAPPER reads to emit a native Wildo provider package.
+ *
+ * Every member is a SOURCE that is read, never a runtime the application depends on: the mapper
+ * extracts each operation's method, URL template, parameters and auth shape as DATA, and Wildo's
+ * own HTTP client executes them. Nothing third-party is installed or executed by a generated
+ * application. (An earlier revision of this enum described Activepieces as a set of executable
+ * bundles Wildo would WRAP; that model was built, measured and deleted on 2026-09-06 — see
+ * `providers-are-scraped-never-wrapped`.)
+ *
+ * - `ACTIVEPIECES` — the community pieces monorepo. Each piece's actions and triggers call
+ *   `httpClient.sendRequest({ method, url, body })` in plain TypeScript an AST pass can read.
+ *   Note the PUBLISHED bundle is NOT a usable input: its metadata carries name, inputs and auth
+ *   but not the endpoint, which lives inside the compiled `run`.
+ * - `SIM` — Sim's tool modules, whose request declaration carries URL and headers the same way.
+ *   Their `transformResponse` / `postProcess` are functions and are deliberately not read; response
+ *   shaping stays Wildo's.
+ * - `OPENAPI_DOCUMENT` — a vendor-published OpenAPI document, the second mapper input feeding the
+ *   same output shape. Authoritative where it exists, since it is the vendor's own description.
+ */
+export declare enum ProviderCatalogueSource {
+    ACTIVEPIECES = "ACTIVEPIECES",
+    SIM = "SIM",
+    OPENAPI_DOCUMENT = "OPENAPI_DOCUMENT"
+}
+export declare const ProviderCatalogueProvenanceSchema: z.ZodObject<{
+    source: z.ZodEnum<typeof ProviderCatalogueSource>;
+    sourceRef: z.ZodString;
+    sourceVersion: z.ZodString;
+}, z.core.$strip>;
+export type ProviderCatalogueProvenance = z.infer<typeof ProviderCatalogueProvenanceSchema>;
+/**
+ * Origin as ONE object with a `kind` and a provenance that is REQUIRED exactly when the kind is
+ * `GENERATED` (and forbidden otherwise), enforced by the refinement below.
+ *
+ * Not a `z.discriminatedUnion`, deliberately: under `strictNullChecks: false` — how the engine
+ * packages compile — Zod 4 infers a union-typed object key as OPTIONAL (the members' `optout`
+ * collapses to `"optional"` once `undefined` is erased), so `metadata.origin` would type as
+ * omittable in every engine consumer while the runtime refused its absence. A plain object
+ * infers as required in both modes; the invariant the union expressed lives in the refinement
+ * and in the `ProviderOrigin` type below.
+ */
+export declare const ProviderOriginSchema: z.ZodObject<{
+    kind: z.ZodEnum<typeof ProviderOriginKind>;
+    catalogue: z.ZodOptional<z.ZodObject<{
+        source: z.ZodEnum<typeof ProviderCatalogueSource>;
+        sourceRef: z.ZodString;
+        sourceVersion: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ProviderOrigin = {
+    kind: ProviderOriginKind.ENGINE;
+    catalogue?: undefined;
+} | {
+    kind: ProviderOriginKind.APPLICATION;
+    catalogue?: undefined;
+} | {
+    kind: ProviderOriginKind.GENERATED;
+    catalogue: ProviderCatalogueProvenance;
+};
+/** The one engine origin value, so 22 modules do not each spell it. */
+export declare const ENGINE_PROVIDER_ORIGIN: ProviderOrigin;
 export declare const ProviderMetadataSchema: z.ZodObject<{
     ref: z.ZodString;
+    packageName: z.ZodString;
+    tier: z.ZodEnum<typeof ProviderTier>;
+    vendor: z.ZodString;
+    origin: z.ZodObject<{
+        kind: z.ZodEnum<typeof ProviderOriginKind>;
+        catalogue: z.ZodOptional<z.ZodObject<{
+            source: z.ZodEnum<typeof ProviderCatalogueSource>;
+            sourceRef: z.ZodString;
+            sourceVersion: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
     displayNameLabelKey: z.ZodOptional<z.ZodString>;
     displayName: z.ZodOptional<z.ZodString>;
     iconRef: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type ProviderMetadata = z.infer<typeof ProviderMetadataSchema>;
+export type ProviderMetadata = Omit<z.infer<typeof ProviderMetadataSchema>, 'origin'> & {
+    origin: ProviderOrigin;
+};
+/**
+ * The identity half of {@link ProviderMetadataSchema} on its own — what a
+ * companion contribution carries so tooling can display tiers and group
+ * vendors without loading a provider's runtime module.
+ */
+export declare const ProviderIdentitySchema: z.ZodObject<{
+    origin: z.ZodObject<{
+        kind: z.ZodEnum<typeof ProviderOriginKind>;
+        catalogue: z.ZodOptional<z.ZodObject<{
+            source: z.ZodEnum<typeof ProviderCatalogueSource>;
+            sourceRef: z.ZodString;
+            sourceVersion: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    packageName: z.ZodString;
+    tier: z.ZodEnum<typeof ProviderTier>;
+    vendor: z.ZodString;
+}, z.core.$strip>;
+export type ProviderIdentity = Omit<z.infer<typeof ProviderIdentitySchema>, 'origin'> & {
+    origin: ProviderOrigin;
+};
+export interface DefineProviderMetadataInput {
+    ref: string;
+    packageName: string;
+    tier: ProviderTier;
+    origin: ProviderOrigin;
+    /** Defaults to `ref` — the single-package vendor case. */
+    vendor?: string;
+    displayName?: string;
+    iconRef?: string;
+}
+/**
+ * The one way a provider module authors its metadata.
+ *
+ * Derives `displayNameLabelKey` from the ref (every module used to call
+ * `buildProviderDisplayNameLabelKey` by hand), defaults `vendor` to the ref,
+ * and parses the result so an incomplete identity fails at MODULE LOAD —
+ * in the package that owns the module — rather than at the first consumer
+ * that reads a field which is not there.
+ */
+export declare function defineProviderMetadata(input: DefineProviderMetadataInput): ProviderMetadata;
 //# sourceMappingURL=provider-metadata.shared.schemas.d.ts.map

package/dist/esm/external-providers/provider-metadata.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-metadata.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-metadata.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,eAAO,MAAM,sBAAsB;;;;;iBAyBjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}
+{"version":3,"file":"provider-metadata.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-metadata.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;;;;;GAOG;AACH,oBAAY,YAAY;IACtB;;;;;;OAMG;IACH,IAAI,SAAS;IACb;;;;;OAKG;IACH,SAAS,cAAc;IACvB;;;;;OAKG;IACH,SAAS,cAAc;CACxB;AAED,iDAAiD;AACjD,oBAAY,kBAAkB;IAC5B,yDAAyD;IACzD,MAAM,WAAW;IACjB,yEAAyE;IACzE,WAAW,gBAAgB;IAC3B;;;;OAIG;IACH,SAAS,cAAc;CACxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oBAAY,uBAAuB;IACjC,YAAY,iBAAiB;IAC7B,GAAG,QAAQ;IACX,gBAAgB,qBAAqB;CACtC;AAED,eAAO,MAAM,iCAAiC;;;;iBAa5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB;;;;;;;iBAa7B,CAAC;AACL,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,kBAAkB,CAAC,WAAW,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,kBAAkB,CAAC,SAAS,CAAC;IAAC,SAAS,EAAE,2BAA2B,CAAA;CAAE,CAAC;AAEnF,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,EAAE,cAAmE,CAAC;AAEzG,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;iBA2CjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,EAAE,QAAQ,CAAC,GAAG;IAAE,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC;AAEnH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;iBAKjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,EAAE,QAAQ,CAAC,GAAG;IAAE,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC;AAEnH,MAAM,WAAW,2BAA2B;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,gBAAgB,CAW3F"}