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

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 VIBES DEV LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @vibesdotdev/applets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Applet definitions, instances, capability grants, launch leases, subscriptions,
+and the unified `applet` tool. An Applet is an installable web application
+pinned to one exact Platform Component release; this package owns instances,
+state, grants, and provenance, never source or compilation.
+
+The contract is [SPEC.md](./SPEC.md), including the full public entrypoint
+list. The Svelte canvas, consent UI, and lifecycle projection are described in
+[SPEC.svelte.md](./SPEC.svelte.md).
+
+This package is part of the public Vibes framework.
+
+The Assembly Field template saves its controls through the supplied applet
+surface and its declared settings store. Reset restores schema defaults;
+loading and saving failures appear in the template.
+
+## Install
+
+```sh
+bun add @vibesdotdev/applets
+# or
+npm install @vibesdotdev/applets
+```
+
+## Runtime and verification
+
+Compose `@vibesdotdev/applets/plugin` and resolve
+`getVibesAppletsClient(runtime)`; bind owner scope with `forRequest(scope)`.
+The root exports the semantic contract. The compatible `./client` subpath
+also exports `RuntimeAppletsClient` for explicit implementation consumers.
+Compose CLI and Svelte plugins through their explicit subpaths.
+
+Run `bun run check`, `bun test`, and `bun run build`.
+The build emits production TypeScript and retains the packaged Svelte surface.
+
+## Documentation
+
+- Package guide: https://docs.vibes.dev/applets
+- Vibes docs: https://docs.vibes.dev
+
+## License
+
+BUSL-1.1 (see LICENSE)

package/dist/applet-gate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The applet gate — grant enforcement as an `authz` interceptor.
+ *
+ * This replaces a bespoke decision function. `runtime-rpc` already routes every
+ * arriving invoke through L1's `authz -> friction` pipeline with `origin:
+ * 'remote'` and the peer's identity attached, so an applet's calls gate through
+ * the same chain as every other call in the system. A second gate chain for the
+ * least trusted peer in the product was the wrong shape.
+ *
+ * What this adds is the applet-specific RULE, not a parallel mechanism:
+ *
+ *   storage.*  needs a DECLARATION. The applets SPEC is explicit that
+ *              "Applet-owned storage is not a browsing-user capability" — the
+ *              host derives instance, viewer partition, descriptor, and adapter
+ *              itself, so what it checks is that the consented release actually
+ *              declared the store.
+ *   assets     the same: a declared reference, bound to the pinned revision.
+ *   everything else needs the capability on the LIVE grant.
+ *
+ * A veto is a THROW, which is the pipeline's contract. `dispatchRequest` turns
+ * it into an `RPC_INVOKE_FAILED` response, so applet code sees a rejected call
+ * rather than a silent null.
+ */
+import { CapabilityError, type InvokeInterceptor } from '@vibesdotdev/kernel';
+import type { AppletCapabilityGrant, AppletLaunchLease } from './schemas/grants.ts';
+import type { AppletDefinitionManifest } from './schemas/definition.ts';
+import type { ComponentReleaseRef } from './schemas/component-release-ref.ts';
+/** What the host knows about one live applet connection. */
+export interface AppletGateBinding {
+    readonly instanceId: string;
+    /** The exact release running. A grant for any other release is refused. */
+    readonly release: ComponentReleaseRef;
+    readonly manifest: AppletDefinitionManifest;
+    readonly grant: AppletCapabilityGrant;
+    readonly lease: AppletLaunchLease;
+}
+export declare class AppletGateDenied extends CapabilityError {
+    constructor(reason: string, detail: string);
+}
+export declare function createAppletInvokeGate(input: {
+    /** Resolve the live binding for the connection an invoke arrived on. */
+    bindingFor: (connectionId: string) => AppletGateBinding | undefined;
+    /** Consult current trusted host implementations on each call. Missing fails closed. */
+    supportsCapability?: (capability: string) => boolean;
+    now?: () => Date;
+}): InvokeInterceptor;
+//# sourceMappingURL=applet-gate.d.ts.map

package/dist/applet-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applet-gate.d.ts","sourceRoot":"","sources":["../src/applet-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,eAAe,EAAsB,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAElG,OAAO,KAAK,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAE9E,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CAClC;AAED,qBAAa,gBAAiB,SAAQ,eAAe;gBACxC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI1C;AAuCD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC7C,wEAAwE;IACxE,UAAU,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAC;IACpE,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IACrD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CACjB,GAAG,iBAAiB,CAmIpB"}

package/dist/applet-gate.js

@@ -0,0 +1,167 @@
+/**
+ * The applet gate — grant enforcement as an `authz` interceptor.
+ *
+ * This replaces a bespoke decision function. `runtime-rpc` already routes every
+ * arriving invoke through L1's `authz -> friction` pipeline with `origin:
+ * 'remote'` and the peer's identity attached, so an applet's calls gate through
+ * the same chain as every other call in the system. A second gate chain for the
+ * least trusted peer in the product was the wrong shape.
+ *
+ * What this adds is the applet-specific RULE, not a parallel mechanism:
+ *
+ *   storage.*  needs a DECLARATION. The applets SPEC is explicit that
+ *              "Applet-owned storage is not a browsing-user capability" — the
+ *              host derives instance, viewer partition, descriptor, and adapter
+ *              itself, so what it checks is that the consented release actually
+ *              declared the store.
+ *   assets     the same: a declared reference, bound to the pinned revision.
+ *   everything else needs the capability on the LIVE grant.
+ *
+ * A veto is a THROW, which is the pipeline's contract. `dispatchRequest` turns
+ * it into an `RPC_INVOKE_FAILED` response, so applet code sees a rejected call
+ * rather than a silent null.
+ */
+import { CapabilityError } from '@vibesdotdev/kernel';
+import * as z from 'zod/v4';
+export class AppletGateDenied extends CapabilityError {
+    constructor(reason, detail) {
+        super(detail, 'PERMISSION_DENIED', { reason, retryable: false });
+        this.name = 'AppletGateDenied';
+    }
+}
+/*
+ * There is deliberately NO target-ref check here.
+ *
+ * A previous version required a `rootRefId` on the binding and compared it to
+ * `ctx.implId`, documented as "the ONE ref this connection may invoke". Nothing
+ * read it, and wiring it would have added ceremony rather than safety: the ref
+ * is not a secret. `DefaultReferenceTable` mints `${prefix}:${kind}:${seq}`, so
+ * every connection's root is the same string, and it is broadcast to the frame
+ * anyway.
+ *
+ * The real containment is the PER-CONNECTION reference table: a ref the table
+ * never minted derefs to nothing, whatever it says. Claiming a second control
+ * that the id cannot provide was worse than having one control that works.
+ */
+/**
+ * Methods on the applet root that read or write a DECLARED store rather than
+ * exercising a capability. Kept as data so the rule is legible, and so adding a
+ * method cannot silently inherit "no capability required".
+ */
+const STORAGE_METHODS = new Set(['storageGet', 'storageList', 'storagePut', 'storageDelete']);
+const ASSET_METHODS = new Set(['assetUrl']);
+/**
+ * A2 runtime parity: the principal-bound runtime handle. No manifest
+ * declaration and no capability tag gate it — Drew's rule is no brittle
+ * per-source exposure. The handle acts AS the principal the host bound, so the
+ * runtime's own authz decides each call; the gate still proves the connection
+ * is live (grant, lease, instance, release) before anything reaches it.
+ */
+const RUNTIME_METHODS = new Set(['runtimeQuery', 'runtimeCall', 'runtimeToolCall']);
+/**
+ * `call` on a FUNCTION ref the host handed the applet (an unsubscribe a runtime call answered,
+ * runtime-rpc SPEC rule 11). The transport admits `call` only on a ref it advertised as a function,
+ * never on the root, so this grants nothing beyond the function the host itself returned.
+ */
+const CALLBACK_METHODS = new Set(['call']);
+export function createAppletInvokeGate(input) {
+    const now = input.now ?? (() => new Date());
+    return {
+        id: 'applets.grant',
+        phase: 'authz',
+        async intercept(ctx, next) {
+            // Local calls are not applet calls. This gate only speaks for invokes
+            // that arrived over an applet connection.
+            if (ctx.origin !== 'remote') {
+                return next();
+            }
+            const binding = ctx.remotePeer ? input.bindingFor(ctx.remotePeer.connectionId) : undefined;
+            if (!binding) {
+                throw new AppletGateDenied('no-binding', 'No live applet binding for this connection; the lease may have been revoked.');
+            }
+            // Liveness first, for EVERY method including storage. Consent to run
+            // this release is what makes its declared stores addressable at all, so
+            // a revoked grant stops a read as surely as it stops a capability.
+            const at = now();
+            if (binding.grant.revokedAt !== null) {
+                throw new AppletGateDenied('grant-revoked', 'Capability grant was revoked.');
+            }
+            if (binding.lease.revokedAt !== null) {
+                throw new AppletGateDenied('lease-revoked', 'Launch lease was revoked.');
+            }
+            if (binding.lease.expiresAt.getTime() <= at.getTime()) {
+                throw new AppletGateDenied('lease-expired', 'Launch lease has expired.');
+            }
+            if (binding.lease.instanceId !== binding.instanceId ||
+                binding.grant.instanceId !== binding.instanceId) {
+                throw new AppletGateDenied('instance-mismatched', 'Grant or lease belongs to a different applet instance.');
+            }
+            // THE GRANT MUST BE FOR THE RELEASE BEING GATED.
+            //
+            // Instance identity alone stopped being sufficient once a composed CHILD
+            // could hold its own grant: a child grant carries the SAME instance id
+            // and a different release, so `instance-mismatched` waves it through.
+            // Nothing selects one today — the page picks the parent grant by release
+            // — but "nothing currently does" is not a control, and this is the one
+            // place that can say so for every caller.
+            if (binding.grant.release.componentId !== binding.release.componentId ||
+                binding.grant.release.version !== binding.release.version ||
+                binding.grant.release.bundleHash !== binding.release.bundleHash ||
+                // FOUR fields, like every other release comparator in this codebase.
+                //
+                // VACUOUS TODAY, and worth saying so in the house style: nothing in
+                // this repository computes a `manifestHash`, so both sides are null on
+                // every product path and this term never decides anything. It is here
+                // because two releases with identical bytes and different manifests
+                // ARE different consent, and because a comparator that omits it would
+                // be the one place in the codebase that does.
+                //
+                // Distinct from dead code deleted elsewhere on this branch: a
+                // duplicated runner gate could never fire in ANY future, while this
+                // fires the moment a producer exists.
+                (binding.grant.release.manifestHash ?? null) !== (binding.release.manifestHash ?? null)) {
+                throw new AppletGateDenied('release-mismatched', 'Capability grant was consented for a different release.');
+            }
+            if (STORAGE_METHODS.has(ctx.method)) {
+                const parsed = z.string().safeParse(ctx.args[0]);
+                const descriptorId = parsed.success ? parsed.data : '';
+                const declared = binding.manifest.storage.some((store) => store.id === descriptorId);
+                if (!declared) {
+                    throw new AppletGateDenied('storage-undeclared', `Store "${descriptorId}" is not declared by this release.`);
+                }
+                return next();
+            }
+            if (ASSET_METHODS.has(ctx.method)) {
+                const parsed = z.string().safeParse(ctx.args[0]);
+                const assetId = parsed.success ? parsed.data : '';
+                const referenced = binding.manifest.assets.some((asset) => asset.assetId === assetId);
+                if (!referenced) {
+                    throw new AppletGateDenied('asset-undeclared', `Asset "${assetId}" is not referenced by this release.`);
+                }
+                return next();
+            }
+            if (RUNTIME_METHODS.has(ctx.method) || CALLBACK_METHODS.has(ctx.method)) {
+                return next();
+            }
+            // Anything else is authority. An unknown method reaching here is denied
+            // rather than allowed: a method added to the root without a rule should
+            // fail closed, not inherit one.
+            const parsedCap = z.string().safeParse(ctx.args[0]);
+            const capability = parsedCap.success ? parsedCap.data : '';
+            if (ctx.method !== 'capabilityInvoke') {
+                throw new AppletGateDenied('method-ungoverned', `Method "${ctx.method}" has no applet authority rule; refusing rather than assuming one.`);
+            }
+            if (!binding.grant.capabilities.includes(capability)) {
+                throw new AppletGateDenied('capability-not-granted', `Capability "${capability}" is not on the live grant.`);
+            }
+            if (!binding.manifest.capabilities.some(({ tag }) => tag === capability)) {
+                throw new AppletGateDenied('capability-not-declared', 'Capability was not declared by this release.');
+            }
+            if (!input.supportsCapability?.(capability)) {
+                throw new AppletGateDenied('capability-not-supported', 'Capability has no current host implementation.');
+            }
+            return next();
+        }
+    };
+}
+//# sourceMappingURL=applet-gate.js.map

package/dist/applet-gate.js.map

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

package/dist/applet-root-surface.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The one object an applet connection can reach.
+ *
+ * The host puts exactly this in its reference table for a connection, and
+ * `dispatchRequest` derefs `targetRef` through that table — so a frame cannot
+ * fabricate a ref and reach anything else. The surface here IS the attack
+ * surface, which is why it is small and why every method is named in the gate.
+ *
+ * Authorization is NOT re-done here; `createAppletInvokeGate` runs first on the
+ * `authz` phase. What this does is BIND: it reads scope and authority from the
+ * manifest and hands the backend a binding the caller could not have chosen.
+ * The gate proves a store was declared; this decides what that declaration
+ * MEANS. A caller that could name its own scope could read another viewer's
+ * rows.
+ *
+ * A2 runtime parity: the surface also carries a PRINCIPAL-BOUND runtime handle
+ * (`runtimeQuery`, `runtimeCall`, `runtimeToolCall`). The host binds the
+ * principal (local: the user; cloud: the viewer); the applet can never name it,
+ * and every call runs through the host's invoke pipeline so the same authz
+ * chain gates it as any other remote peer.
+ */
+import * as z from 'zod/v4';
+import type { JsonValue } from '@vibesdotdev/shared/types';
+import type { AppletDefinitionManifest, AppletOwnStorageDescriptor } from './schemas/definition.ts';
+export interface AppletStorageBinding {
+    readonly descriptorId: string;
+    readonly scope: AppletOwnStorageDescriptor['scope'];
+    readonly authority: AppletOwnStorageDescriptor['authority'];
+    readonly instanceId: string;
+}
+/** One enabled descriptor, projected for an applet: identity and description only. */
+export interface AppletRuntimeDescriptorView {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly enabled: boolean;
+}
+/**
+ * A callback an applet hands to a runtime call (`subscribe(listener)`): over runtime-rpc it crosses
+ * as a callback ref, so the host can call it back across the boundary. The host never sees the
+ * applet's function, only a ref it can invoke until the ref is released.
+ */
+export type AppletRuntimeCallback = AppletRuntimeFunction;
+/** A function that crosses the applet boundary as a `call`-only ref: JSON in, JSON (or nothing) out. */
+export type AppletRuntimeFunction = (...values: JsonValue[]) => JsonValue | void | Promise<JsonValue | void>;
+/** One positional argument of a runtime call: bounded JSON, or a callback. */
+export type AppletRuntimeArg = JsonValue | AppletRuntimeCallback;
+/** What a runtime call answers: bounded JSON, or a function (an unsubscribe) that crosses back as a ref. */
+export type AppletRuntimeAnswer = JsonValue | AppletRuntimeFunction;
+/** What a host hands the surface before the surface checks it crosses: an answer, or nothing. */
+export type AppletRuntimeHostValue = AppletRuntimeAnswer | undefined;
+/** What one `runtimeQuery` answers: a bounded page of enabled descriptors. */
+export interface AppletRuntimeQueryView {
+    readonly kind: string;
+    readonly total: number;
+    readonly truncated: boolean;
+    readonly descriptors: readonly AppletRuntimeDescriptorView[];
+}
+/** What the host must implement to make an applet's declarations real. */
+export interface AppletSurfaceBackend {
+    storageGet: (binding: AppletStorageBinding, key: string) => Promise<JsonValue>;
+    storageList: (binding: AppletStorageBinding, query: {
+        limit?: number;
+        cursor?: string;
+    }) => Promise<{
+        results: JsonValue[];
+        nextCursor: string | null;
+    }>;
+    storagePut: (binding: AppletStorageBinding, key: string, value: JsonValue) => Promise<void>;
+    storageDelete: (binding: AppletStorageBinding, key: string) => Promise<void>;
+    assetUrl: (assetId: string, revision: string, digest: string) => Promise<string | null>;
+    capabilityInvoke: (capability: string, input: JsonValue) => Promise<JsonValue>;
+    /** Enabled descriptors of one kind, already projected; the surface bounds the answer. Absent: this host binds no runtime handle. */
+    runtimeQuery?: (kind: string) => Promise<AppletRuntimeQueryView>;
+    /** One method call on a resolved runtime asset, through the host's invoke pipeline. Absent: no runtime handle. */
+    runtimeCall?: (kind: string, id: string, method: string, args: readonly AppletRuntimeArg[]) => Promise<AppletRuntimeHostValue>;
+    /** One tool call, on the runtime the host bound to the principal. Absent: no runtime handle. */
+    runtimeToolCall?: (toolId: string, input: JsonValue) => Promise<AppletRuntimeHostValue>;
+}
+export interface AppletRootSurface {
+    storageGet: (descriptorId: string, key: string) => Promise<JsonValue>;
+    storageList: (descriptorId: string, query?: {
+        limit?: number;
+        cursor?: string;
+    }) => Promise<{
+        results: JsonValue[];
+        nextCursor: string | null;
+    }>;
+    storagePut: (descriptorId: string, key: string, value: JsonValue) => Promise<void>;
+    storageDelete: (descriptorId: string, key: string) => Promise<void>;
+    assetUrl: (assetId: string) => Promise<string | null>;
+    capabilityInvoke: (capability: string, input?: JsonValue) => Promise<JsonValue>;
+    /** Enabled descriptors of `kind` on the principal-bound runtime, bounded. */
+    runtimeQuery: (kind: string) => Promise<AppletRuntimeQueryView>;
+    /**
+     * One method call on a runtime asset of `kind`/`id`, as the bound principal. Arguments may be
+     * callbacks and the answer may be a function: `runtimeCall(kind, id, 'subscribe', listener)`
+     * subscribes to an existing store or hook and answers its unsubscribe. No subscribe method exists.
+     */
+    runtimeCall: (kind: string, id: string, method: string, ...args: AppletRuntimeArg[]) => Promise<AppletRuntimeAnswer>;
+    /** One tool call on the principal-bound runtime, bounded. */
+    runtimeToolCall: (toolId: string, input?: JsonValue) => Promise<JsonValue>;
+}
+/**
+ * Every method an applet connection may call on its root surface. A host that
+ * serves the surface over runtime-rpc advertises exactly these as the listen
+ * target's `rootMethods`; an unadvertised method is refused before dispatch.
+ */
+export declare const APPLET_ROOT_SURFACE_METHODS: readonly ["storageGet", "storageList", "storagePut", "storageDelete", "assetUrl", "capabilityInvoke", "runtimeQuery", "runtimeCall", "runtimeToolCall"];
+/** A function value: a callback argument or an unsubscribe answer, carried by the wire as a ref. */
+export declare const appletRuntimeCallbackSchema: z.ZodCustom<AppletRuntimeFunction, AppletRuntimeFunction>;
+/** A host's raw runtime answer, parsed where it enters the surface: a function, bounded JSON, or nothing. */
+export declare const appletRuntimeHostValueSchema: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<AppletRuntimeFunction, AppletRuntimeFunction>, z.ZodPipe<z.ZodCustom<import("@vibesdotdev/kernel/bootstrap").JsonValue, import("@vibesdotdev/kernel/bootstrap").JsonValue>, z.ZodTransform<string | number | boolean | import("@vibesdotdev/kernel/schemas/json").JsonObject | import("@vibesdotdev/kernel/schemas/json").JsonArray | null, import("@vibesdotdev/kernel/bootstrap").JsonValue>>]>>;
+/** Most descriptors one runtime query answers. */
+export declare const MAX_RUNTIME_DESCRIPTORS = 100;
+/** Longest description the descriptor projection carries. */
+export declare const MAX_RUNTIME_DESCRIPTION = 280;
+/** What one `runtimeQuery` answers, checked at the surface before it crosses. */
+export declare const appletRuntimeQueryViewSchema: z.ZodObject<{
+    kind: z.ZodString;
+    total: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    descriptors: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function createAppletRootSurface(input: {
+    instanceId: string;
+    manifest: AppletDefinitionManifest;
+    backend: AppletSurfaceBackend;
+}): AppletRootSurface;
+//# sourceMappingURL=applet-root-surface.d.ts.map

package/dist/applet-root-surface.d.ts.map

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