@vibesdotdev/applets 0.0.0-stage → 1.0.0-rc.3

package/dist/config/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAsB,MAAM,4BAA4B,CAAC;AAEhF,OAAO,EACN,0BAA0B,EAC1B,mBAAmB,EAEnB,MAAM,gCAAgC,CAAC;AAMxC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAqB;IAC5D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC/C,IACC,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC;QACnC,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC,WAAW,EAAE,CAAC,MAAM,KAAK,CAAC,EAC7F,CAAC;QACF,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAe,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrE,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,0BAA0B,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC;AACrF,CAAC"}

package/dist/content-path.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The addressable path for a shared thing.
+ *
+ * `content.vibes.dev/{scope}/{name}/{kind}/{slug}`. Specified in the proposal
+ * and unimplemented until now, which meant the reserved-segment protection it
+ * claimed did not exist.
+ *
+ * Pure grammar, deliberately separate from any surface: which app serves this is
+ * an open product question, and the shape of the URL is not. Building it here
+ * means the answer to that question inherits a tested parser rather than
+ * reinventing one.
+ *
+ * `{kind}` is validated as a SEGMENT only, not against a vocabulary. This module
+ * deliberately does not own the list of shareable kinds: that is
+ * `marketplaceListingKindSchema`, and the surface that routes a request should
+ * check against it. Duplicating the enum here would create exactly the second
+ * vocabulary this is meant to avoid, and importing it would drag a DOM-typed
+ * package into a package that has no DOM lib.
+ *
+ * So the grammar is permissive about kind and the router is strict. Stated
+ * because an earlier draft of the test claimed this module "uses the marketplace
+ * vocabulary", which nothing here enforces.
+ */
+import * as z from 'zod/v4';
+export declare const appletContentScopeSchema: z.ZodEnum<{
+    user: "user";
+    project: "project";
+    org: "org";
+}>;
+/**
+ * Segments a name may never take.
+ *
+ * Without this a user called `api` owns `content.vibes.dev/user/api/...` and,
+ * more importantly, a future first-party route at `/api/...` collides with a
+ * name someone already registered. Reserving them costs nothing now and is
+ * impossible later.
+ */
+export declare const RESERVED_CONTENT_SEGMENTS: readonly string[];
+export declare const appletContentNameSchema: z.ZodString;
+export declare const appletContentSlugSchema: z.ZodString;
+/**
+ * The kind segment. Shape and LENGTH, because every other segment is capped and
+ * an uncapped one is the one an attacker uses: a 5000-character kind produced a
+ * valid path and parsed back cleanly.
+ */
+export declare const appletContentKindSchema: z.ZodString;
+export interface AppletContentAddress {
+    scope: z.infer<typeof appletContentScopeSchema>;
+    name: string;
+    kind: string;
+    slug: string;
+}
+/** Build the path. Refuses rather than emitting something unroutable. */
+export declare function appletContentPath(address: AppletContentAddress): string;
+/**
+ * Parse a path back into an address, or null.
+ *
+ * Null rather than throwing: this runs on request paths, where a miss is an
+ * ordinary 404 and not an exceptional condition.
+ */
+export declare function parseAppletContentPath(pathname: string): AppletContentAddress | null;
+//# sourceMappingURL=content-path.d.ts.map

package/dist/content-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-path.d.ts","sourceRoot":"","sources":["../src/content-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,eAAO,MAAM,wBAAwB;;;;EAAqC,CAAC;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAiBrD,CAAC;AAIH,eAAO,MAAM,uBAAuB,aAOjC,CAAC;AAEJ,eAAO,MAAM,uBAAuB,aAIkB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,aAIkB,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAMvE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAuBpF"}

package/dist/content-path.js

@@ -0,0 +1,121 @@
+/**
+ * The addressable path for a shared thing.
+ *
+ * `content.vibes.dev/{scope}/{name}/{kind}/{slug}`. Specified in the proposal
+ * and unimplemented until now, which meant the reserved-segment protection it
+ * claimed did not exist.
+ *
+ * Pure grammar, deliberately separate from any surface: which app serves this is
+ * an open product question, and the shape of the URL is not. Building it here
+ * means the answer to that question inherits a tested parser rather than
+ * reinventing one.
+ *
+ * `{kind}` is validated as a SEGMENT only, not against a vocabulary. This module
+ * deliberately does not own the list of shareable kinds: that is
+ * `marketplaceListingKindSchema`, and the surface that routes a request should
+ * check against it. Duplicating the enum here would create exactly the second
+ * vocabulary this is meant to avoid, and importing it would drag a DOM-typed
+ * package into a package that has no DOM lib.
+ *
+ * So the grammar is permissive about kind and the router is strict. Stated
+ * because an earlier draft of the test claimed this module "uses the marketplace
+ * vocabulary", which nothing here enforces.
+ */
+import * as z from 'zod/v4';
+export const appletContentScopeSchema = z.enum(['user', 'org', 'project']);
+/**
+ * Segments a name may never take.
+ *
+ * Without this a user called `api` owns `content.vibes.dev/user/api/...` and,
+ * more importantly, a future first-party route at `/api/...` collides with a
+ * name someone already registered. Reserving them costs nothing now and is
+ * impossible later.
+ */
+export const RESERVED_CONTENT_SEGMENTS = Object.freeze([
+    'api',
+    '_app',
+    '_next',
+    'admin',
+    'assets',
+    'health',
+    'internal',
+    'login',
+    'logout',
+    'oauth',
+    'org',
+    'project',
+    'settings',
+    'static',
+    'user',
+    'well-known'
+]);
+const SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const appletContentNameSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(SEGMENT, 'Names must be lowercase kebab-case')
+    .refine((value) => !RESERVED_CONTENT_SEGMENTS.includes(value), {
+    message: 'This name is reserved for first-party routes'
+});
+export const appletContentSlugSchema = z
+    .string()
+    .min(1)
+    .max(80)
+    .regex(SEGMENT, 'Slugs must be lowercase kebab-case');
+/**
+ * The kind segment. Shape and LENGTH, because every other segment is capped and
+ * an uncapped one is the one an attacker uses: a 5000-character kind produced a
+ * valid path and parsed back cleanly.
+ */
+export const appletContentKindSchema = z
+    .string()
+    .min(1)
+    .max(40)
+    .regex(SEGMENT, 'Kinds must be lowercase kebab-case');
+/** Build the path. Refuses rather than emitting something unroutable. */
+export function appletContentPath(address) {
+    appletContentScopeSchema.parse(address.scope);
+    appletContentNameSchema.parse(address.name);
+    appletContentSlugSchema.parse(address.slug);
+    appletContentKindSchema.parse(address.kind);
+    return `/${address.scope}/${address.name}/${address.kind}/${address.slug}`;
+}
+/**
+ * Parse a path back into an address, or null.
+ *
+ * Null rather than throwing: this runs on request paths, where a miss is an
+ * ordinary 404 and not an exceptional condition.
+ */
+export function parseAppletContentPath(pathname) {
+    // Canonical form only. FILTERING empty segments — which an earlier version
+    // did — silently accepted `//user/x/y/z` and `/user//x/y/z` as the same
+    // address, so one resource answered at several URLs. That is how a cache and
+    // a path-prefix rule end up disagreeing about what they are protecting.
+    //
+    // Splitting without filtering is enough on its own: an extra slash produces
+    // an extra segment and fails the length check, and a blank segment in a
+    // four-part path fails its own schema, every one of which requires at least
+    // one character. An explicit empty-segment guard was here briefly and was
+    // unreachable, so it is gone rather than left looking protective.
+    const canonical = pathname.endsWith('/') ? pathname.slice(0, -1) : pathname;
+    if (!canonical.startsWith('/'))
+        return null;
+    const segments = canonical.slice(1).split('/');
+    if (segments.length !== 4)
+        return null;
+    const [scope, name, kind, slug] = segments;
+    if (!scope || !name || !kind || !slug)
+        return null;
+    const parsedScope = appletContentScopeSchema.safeParse(scope);
+    if (!parsedScope.success)
+        return null;
+    if (!appletContentNameSchema.safeParse(name).success)
+        return null;
+    if (!appletContentSlugSchema.safeParse(slug).success)
+        return null;
+    if (!appletContentKindSchema.safeParse(kind).success)
+        return null;
+    return { scope: parsedScope.data, name, kind, slug };
+}
+//# sourceMappingURL=content-path.js.map

package/dist/content-path.js.map

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

package/dist/contribution-registry.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Contribution registration and dispatch.
+ *
+ * This is where the proposal's central claim becomes enforceable code:
+ *
+ *     Descriptors are data. Implementations are code.
+ *     The host registers a shim; it never imports applet code.
+ *
+ * Nothing in this file resolves an applet path, and nothing calls `import()`.
+ * A contributed implementation is named by reference, and the only thing the
+ * host ever does with that reference is put it in a message envelope that
+ * crosses the sandbox boundary.
+ *
+ * Two rules that look like ceremony and are not:
+ *
+ * 1. Authorization is re-read on EVERY dispatch through an injected reader.
+ *    Registration is a cache, not a boundary — a long-lived runtime keeps its
+ *    shims until something restarts it, so a revoked subscription must be
+ *    refused by the call itself.
+ * 2. A contribution whose capabilities were declined is never registered at
+ *    all, rather than registered and failing at call time.
+ */
+import type { AppletCapabilityGrant, AppletLaunchLease } from './schemas/grants.ts';
+import type { AppletSubscription } from './schemas/subscription.ts';
+import type { AppletObservationRecorder } from './schemas/observation.ts';
+import type { AppletContributes, AppletImplRef } from './schemas/contributes.ts';
+import type { ComponentReleaseRef } from './schemas/component-release-ref.ts';
+import { CapabilityError, type CaughtFailure, type RuntimeRef, type CapabilityErrorCode, type VibesRuntime } from '@vibesdotdev/kernel';
+import type { ToolCallContext } from '@vibesdotdev/kernel/schemas/tool-call';
+import type { JsonValue } from '@vibesdotdev/kernel/schemas/json';
+import { type AppletDispatchRequest, type AppletDispatchResponse } from './schemas/dispatch.ts';
+/** Runtime kinds a contribution can register into. Closed, like the manifest. */
+export type AppletContributionKind = 'tools/tool' | 'cli/command' | 'applet/event-handler';
+export interface AppletContributionRegistration {
+    kind: AppletContributionKind;
+    /** Host-assigned identity. Authors never choose this. */
+    id: string;
+    requires: readonly string[];
+    impl: AppletImplRef;
+}
+export interface AppletWithheldContribution {
+    kind: AppletContributionKind;
+    id: string;
+    missing: string[];
+}
+export interface AppletContributionPlan {
+    registered: AppletContributionRegistration[];
+    withheld: AppletWithheldContribution[];
+}
+/**
+ * Host-assigned identities.
+ *
+ * Namespacing is what stops collision and squatting, so it is computed here
+ * from the slug rather than read from anything the author supplied. CLI
+ * commands are always mounted under `vibes applet <slug>` and can never reach
+ * the top level, because this function cannot express a top-level command.
+ */
+export declare function appletToolId(slug: string, name: string): string;
+export declare function appletCliCommandId(slug: string, command: string): string;
+export declare function appletCliCommandPath(slug: string, command: string): readonly string[];
+export declare function appletEventHandlerId(slug: string, name: string): string;
+/**
+ * Decide what a subscription registers, given what the subscriber actually
+ * granted. Pure: it reads no runtime and performs no I/O.
+ */
+export declare function planAppletContributionRegistrations(input: {
+    slug: string;
+    contributes: AppletContributes | undefined;
+    grantedCapabilities: readonly string[];
+}): AppletContributionPlan;
+/**
+ * Runtime key for one contributed implementation: `<entry>#<export>`.
+ *
+ * CANONICAL definition. The compiler emits this key onto the bundle's
+ * `__contributions` map and the runner reads it back, so the two must agree
+ * exactly or every dispatch resolves to nothing.
+ *
+ * `apps/applet-runner` mirrors this by value because it takes no @vibesdotdev
+ * runtime dependency; `apps/applet-runner/test/protocol-parity.test.ts` asserts
+ * the two implementations agree.
+ */
+export declare function appletContributionKey(impl: {
+    entry: string;
+    export: string;
+}): string;
+export { APPLET_DISPATCH_PROTOCOL_VERSION } from './schemas/dispatch.ts';
+export type { AppletDispatchRequest, AppletDispatchResponse } from './schemas/dispatch.ts';
+export interface AppletDispatchTransport {
+    /** MessagePort or headless RPC answer; parsed once at the host dispatch boundary. */
+    send(request: AppletDispatchRequest): Promise<JsonValue>;
+}
+/**
+ * How long the HOST waits for a dispatch reply.
+ *
+ * This is the bound that actually protects the caller. The runner's own timeout
+ * cannot interrupt synchronous applet code — a `while (true)` in a contributed
+ * function blocks that frame's only thread and no reply is ever sent — so
+ * without a host-side deadline the caller waits forever on a hostile applet.
+ */
+export declare const APPLET_DISPATCH_TIMEOUT_MS = 20000;
+/** Live authority for one dispatch. Re-read per call; never cached. */
+export interface AppletAuthorizationState {
+    subscription: AppletSubscription;
+    grant: AppletCapabilityGrant;
+    lease?: AppletLaunchLease;
+}
+export declare class AppletAuthorizationError extends CapabilityError {
+    constructor(reason: string, detail: string);
+}
+/** Longest applet-supplied error text the host will carry. */
+export declare const MAX_DISPATCH_ERROR_MESSAGE = 500;
+/**
+ * Parse the ONE wire crossing from the sandbox into the host.
+ *
+ * The response is third-party output and was previously trusted raw: a malformed
+ * `{ok:false}` threw a TypeError instead of a dispatch error, and an
+ * applet-controlled `error.message` propagated verbatim into an agent's tool
+ * result — unbounded, control-character-bearing, prompt-injection-shaped.
+ */
+export declare function parseAppletDispatchResponse(value: unknown): AppletDispatchResponse;
+export interface AppletDispatchFailure {
+    readonly code: CapabilityErrorCode;
+    readonly reason: string;
+    readonly hostOriginated: boolean;
+    readonly cause?: CaughtFailure;
+}
+export declare class AppletDispatchError extends CapabilityError {
+    /**
+     * Whether the HOST produced this, rather than relaying applet text.
+     *
+     * Without it an applet can forge a host error: returning
+     * `{ok:false, error:{message:'Applet dispatch timed out.'}}` produced a
+     * byte-identical exception, so a caller could not tell a real deadline from
+     * an applet pretending there was one.
+     */
+    readonly hostOriginated: boolean;
+    constructor(message: string, init: AppletDispatchFailure);
+}
+export interface AppletDispatchShim {
+    readonly registrationId: string;
+    /**
+     * The canonical tools shape `(input, runtime, ctx)`, mirrored structurally:
+     * the shim dispatches on `input` only and ignores `runtime` and `ctx`.
+     * Types come from the runtime package below, never from tools above.
+     */
+    execute(input?: Record<string, JsonValue>, runtime?: VibesRuntime, ctx?: ToolCallContext): Promise<JsonValue>;
+}
+/**
+ * Correlation ids must satisfy the runner protocol's rule, or the far side
+ * rejects the envelope: 32-128 chars of `[A-Za-z0-9_-]`.
+ */
+export declare function isAppletCorrelationId(value: string): value is string;
+/**
+ * Build the implementation the host registers for one contributed descriptor.
+ *
+ * The returned object closes over identity and a transport. It never receives,
+ * resolves, or executes applet code — `impl` travels as data inside the
+ * envelope and is resolved on the far side of the boundary.
+ */
+export declare function createAppletDispatchShim(input: {
+    /** The runtime whose lifecycle bounds each dispatch, and whose logging reports a failed ledger append. */
+    runtime: RuntimeRef;
+    registration: AppletContributionRegistration;
+    release: ComponentReleaseRef;
+    transport: AppletDispatchTransport;
+    /** Live authority, re-read on every call. */
+    readAuthorization: () => Promise<AppletAuthorizationState>;
+    newCorrelationId: () => string;
+    now?: () => Date;
+    /** Overridable so tests do not wait the real deadline. */
+    dispatchTimeoutMs?: number;
+    /**
+     * Appends to the observation ledger.
+     *
+     * Taken here, at the boundary, rather than left to callers: the shim is the
+     * only path across the sandbox, so recording here is what makes the ledger
+     * non-bypassable. A caller that could choose not to record would eventually
+     * be a caller that does not.
+     */
+    recordObservation?: AppletObservationRecorder;
+}): AppletDispatchShim;
+/**
+ * The loader the host registers, in the shape `runtime.registerLoader` expects.
+ *
+ * `ImplementationLoader<T> = () => Promise<{ impl: T }>`. The blessed lazy
+ * pattern normally has the loader `import()` an implementation module — here it
+ * deliberately does not. There is nothing to import: the implementation lives
+ * inside the sandbox, and the loader hands back a shim that dispatches to it.
+ *
+ * This is the strongest form of the invariant. The usual lazy loader defers an
+ * import; this one has no import to defer, at any point, ever.
+ *
+ * Register with:
+ *   runtime.registerLoader(registration.kind, registration.id, loader)
+ */
+export declare function createAppletContributionLoader(input: {
+    /** The runtime whose lifecycle bounds each dispatch, and whose logging reports a failed ledger append. */
+    runtime: RuntimeRef;
+    registration: AppletContributionRegistration;
+    release: ComponentReleaseRef;
+    transport: AppletDispatchTransport;
+    readAuthorization: () => Promise<AppletAuthorizationState>;
+    newCorrelationId: () => string;
+    now?: () => Date;
+    dispatchTimeoutMs?: number;
+    /**
+     * Threaded through deliberately. Without it the blessed registration path
+     * produced an UNLEDGERED shim while the ledger was described as
+     * non-bypassable — the recorder was optional on the shim and absent here, so
+     * the documented way to register a contribution was also the way to lose its
+     * receipts.
+     */
+    recordObservation?: AppletObservationRecorder;
+}): () => Promise<{
+    impl: AppletDispatchShim;
+}>;
+/** One named export the compiled bundle must expose, in the compiler's terms. */
+export interface AppletCompileContribution {
+    entry: string;
+    exportName: string;
+}
+/**
+ * Map a manifest's `contributes` onto the compiler's contribution input.
+ *
+ * The translation exists because the two sides own different vocabularies:
+ * Applets declares WHAT a release contributes and why; Platform owns source,
+ * compilation, bundles, and releases and only needs to know WHICH named exports
+ * to expose. Keeping the compiler Applet-agnostic is what stops applet semantics
+ * leaking into the build.
+ *
+ * Deduplicated on the same `<entry>#<export>` key the compiler refuses
+ * duplicates on: two contributions may legitimately share one implementation
+ * (a tool and a CLI command over the same function), and that must not become a
+ * publish-time failure.
+ */
+export declare function appletCompileContributions(contributes: AppletContributes | undefined): AppletCompileContribution[];
+/** One subscription plus the records it references, as a resolver reads them. */
+export interface SubscribedApplet {
+    subscription: AppletSubscription;
+    grant: AppletCapabilityGrant;
+    /** Host-assigned namespace segment. Comes from the publication, not the author. */
+    slug: string;
+    /** The manifest stored on the instance. Absent means nothing to register. */
+    definitionManifest: {
+        contributes?: AppletContributes;
+    } | null;
+}
+export interface SubscribedContributionPlan {
+    registered: AppletContributionRegistration[];
+    withheld: AppletWithheldContribution[];
+    /** Why a subscription contributed nothing, for an operator staring at a gap. */
+    skipped: Array<{
+        subscriptionId: string;
+        reason: string;
+    }>;
+}
+/**
+ * Turn live subscriptions into a registration plan.
+ *
+ * Pure. Registration decides only what EXISTS; every dispatch re-derives
+ * authority through `authorizeAppletContribution`, so nothing here is a security
+ * decision and a stale plan cannot grant anything. What it must get right is the
+ * opposite: never registering something the subscriber did not consent to, so a
+ * revoked or mismatched subscription contributes nothing at all.
+ *
+ * Reasons are recorded rather than silently dropped, because "my applet's tool
+ * isn't there" is otherwise unanswerable.
+ */
+export declare function resolveSubscribedContributions(subscribed: readonly SubscribedApplet[]): SubscribedContributionPlan;
+//# sourceMappingURL=contribution-registry.d.ts.map

package/dist/contribution-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contribution-registry.d.ts","sourceRoot":"","sources":["../src/contribution-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,EAA0C,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,KAAK,mBAAmB,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChL,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAElE,OAAO,EAKN,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAI/B,iFAAiF;AACjF,MAAM,MAAM,sBAAsB,GAAG,YAAY,GAAG,aAAa,GAAG,sBAAsB,CAAC;AAE3F,MAAM,WAAW,8BAA8B;IAC9C,IAAI,EAAE,sBAAsB,CAAC;IAC7B,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,IAAI,EAAE,aAAa,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,sBAAsB,CAAC;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACtC,UAAU,EAAE,8BAA8B,EAAE,CAAC;IAC7C,QAAQ,EAAE,0BAA0B,EAAE,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AACD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAExE;AACD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAErF;AACD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC3C,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,sBAAsB,CA2CzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAErF;AAED,OAAO,EAAE,gCAAgC,EAAE,MAAM,uBAAuB,CAAC;AACzE,YAAY,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE3F,MAAM,WAAW,uBAAuB;IACvC,qFAAqF;IACrF,IAAI,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD,uEAAuE;AACvE,MAAM,WAAW,wBAAwB;IACxC,YAAY,EAAE,kBAAkB,CAAC;IACjC,KAAK,EAAE,qBAAqB,CAAC;IAC7B,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAED,qBAAa,wBAAyB,SAAQ,eAAe;gBAChD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI1C;AAED,8DAA8D;AAC9D,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAqB9C;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,CAkBlF;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,qBAAa,mBAAoB,SAAQ,eAAe;IACvD;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;gBACrB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB;CAKxD;AA6ED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC9G;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,MAAM,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC/C,0GAA0G;IAC1G,OAAO,EAAE,UAAU,CAAC;IACpB,YAAY,EAAE,8BAA8B,CAAC;IAC7C,OAAO,EAAE,mBAAmB,CAAC;IAC7B,SAAS,EAAE,uBAAuB,CAAC;IACnC,6CAA6C;IAC7C,iBAAiB,EAAE,MAAM,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAC3D,gBAAgB,EAAE,MAAM,MAAM,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;CAC9C,GAAG,kBAAkB,CA2JrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACrD,0GAA0G;IAC1G,OAAO,EAAE,UAAU,CAAC;IACpB,YAAY,EAAE,8BAA8B,CAAC;IAC7C,OAAO,EAAE,mBAAmB,CAAC;IAC7B,SAAS,EAAE,uBAAuB,CAAC;IACnC,iBAAiB,EAAE,MAAM,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAC3D,gBAAgB,EAAE,MAAM,MAAM,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;CAC9C,GAAG,MAAM,OAAO,CAAC;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAE9C;AAED,iFAAiF;AACjF,MAAM,WAAW,yBAAyB;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACzC,WAAW,EAAE,iBAAiB,GAAG,SAAS,GACxC,yBAAyB,EAAE,CAkB7B;AAED,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAChC,YAAY,EAAE,kBAAkB,CAAC;IACjC,KAAK,EAAE,qBAAqB,CAAC;IAC7B,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,kBAAkB,EAAE;QAAE,WAAW,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,0BAA0B;IAC1C,UAAU,EAAE,8BAA8B,EAAE,CAAC;IAC7C,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,gFAAgF;IAChF,OAAO,EAAE,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC7C,UAAU,EAAE,SAAS,gBAAgB,EAAE,GACrC,0BAA0B,CAkD5B"}