@dbx-tools/shared-appkit 0.0.0-stage → 0.9.188

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @dbx-tools/shared-appkit
 
-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.
+Browser-safe schemas, route constants, and client configuration contracts for
+dbx-tools AppKit extensions.
+
+## Build a browser debug capture request
+
+`@dbx-tools/appkit` publishes the optional debug-capture plugin configuration,
+and `@dbx-tools/ui/react` consumes these contracts to record browser events.
+Applications normally enable the route through `createApp({ debug: "auto" })`,
+which is active only when `NODE_ENV=development`.
+
+```ts
+import {
+  DebugCaptureClientConfigSchema,
+  DebugCaptureRequestSchema,
+  debugCaptureRoute,
+} from "@dbx-tools/shared-appkit/debug";
+```
+
+Capture requests are bounded and contain scalar diagnostics only. The browser
+recorder does not send form values or printable key content.
+
+## Resolve the browser capture endpoint
+
+Use the published client configuration instead of hard-coding an AppKit route.
+The route helper normalizes a configured base path and appends the capture
+resource path.
+
+```ts
+import {
+  DebugCaptureClientConfigSchema,
+  debugCaptureRoute,
+} from "@dbx-tools/shared-appkit/debug";
+
+const config = DebugCaptureClientConfigSchema.parse({
+  basePath: "/api/debug-capture",
+});
+const endpoint = debugCaptureRoute(config.basePath);
+```
+
+The resulting endpoint is `/api/debug-capture/captures` for the default AppKit
+plugin configuration.
+
+## Validate debug requests
+
+Use `DebugCaptureRequestSchema` on route handlers or tests that accept browser
+debug payloads. The schema keeps the wire contract browser-safe while the node
+package owns persistence and any server-side processing.

package/index.debug.ts

@@ -0,0 +1,7 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as contracts from "./src/debug/contracts.ts";
+export { DEBUG_CAPTURE_PLUGIN_NAME, DEBUG_CAPTURE_ROUTE, DEBUG_CAPTURE_DEFAULT_BASE_PATH, debugCaptureRoute, DebugCaptureScalarSchema, DebugCaptureEventSchema, DebugCaptureEventsSchema, DebugCaptureIdSchema, DebugCaptureRequestSchema, DebugCaptureStartResponseSchema, DebugCaptureAppendResponseSchema, DebugCaptureStopResponseSchema, DebugCaptureClientConfigSchema } from "./src/debug/contracts.ts";
+export type { DebugCaptureScalar, DebugCaptureEvent, DebugCaptureRequest, DebugCaptureClientConfig } from "./src/debug/contracts.ts";

package/index.ts

@@ -0,0 +1,6 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export const PACKAGE_IDENTIFIER = "@dbx-tools/shared-appkit";
+export const PACKAGE_VERSION = "0.9.188";

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export declare const PACKAGE_IDENTIFIER = "@dbx-tools/shared-appkit";
+export declare const PACKAGE_VERSION = "0.9.188";

package/lib/index.debug.d.ts

@@ -0,0 +1,3 @@
+export * as contracts from "./src/debug/contracts.ts";
+export { DEBUG_CAPTURE_PLUGIN_NAME, DEBUG_CAPTURE_ROUTE, DEBUG_CAPTURE_DEFAULT_BASE_PATH, debugCaptureRoute, DebugCaptureScalarSchema, DebugCaptureEventSchema, DebugCaptureEventsSchema, DebugCaptureIdSchema, DebugCaptureRequestSchema, DebugCaptureStartResponseSchema, DebugCaptureAppendResponseSchema, DebugCaptureStopResponseSchema, DebugCaptureClientConfigSchema } from "./src/debug/contracts.ts";
+export type { DebugCaptureScalar, DebugCaptureEvent, DebugCaptureRequest, DebugCaptureClientConfig } from "./src/debug/contracts.ts";

package/lib/index.debug.js

@@ -0,0 +1,6 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+export * as contracts from "./src/debug/contracts.js";
+export { DEBUG_CAPTURE_PLUGIN_NAME, DEBUG_CAPTURE_ROUTE, DEBUG_CAPTURE_DEFAULT_BASE_PATH, debugCaptureRoute, DebugCaptureScalarSchema, DebugCaptureEventSchema, DebugCaptureEventsSchema, DebugCaptureIdSchema, DebugCaptureRequestSchema, DebugCaptureStartResponseSchema, DebugCaptureAppendResponseSchema, DebugCaptureStopResponseSchema, DebugCaptureClientConfigSchema } from "./src/debug/contracts.js";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZGVidWcuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC5kZWJ1Zy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssU0FBUyxNQUFNLDBCQUEwQixDQUFDO0FBQ3RELE9BQU8sRUFBRSx5QkFBeUIsRUFBRSxtQkFBbUIsRUFBRSwrQkFBK0IsRUFBRSxpQkFBaUIsRUFBRSx3QkFBd0IsRUFBRSx1QkFBdUIsRUFBRSx3QkFBd0IsRUFBRSxvQkFBb0IsRUFBRSx5QkFBeUIsRUFBRSwrQkFBK0IsRUFBRSxnQ0FBZ0MsRUFBRSw4QkFBOEIsRUFBRSw4QkFBOEIsRUFBRSxNQUFNLDBCQUEwQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0ICogYXMgY29udHJhY3RzIGZyb20gXCIuL3NyYy9kZWJ1Zy9jb250cmFjdHMudHNcIjtcbmV4cG9ydCB7IERFQlVHX0NBUFRVUkVfUExVR0lOX05BTUUsIERFQlVHX0NBUFRVUkVfUk9VVEUsIERFQlVHX0NBUFRVUkVfREVGQVVMVF9CQVNFX1BBVEgsIGRlYnVnQ2FwdHVyZVJvdXRlLCBEZWJ1Z0NhcHR1cmVTY2FsYXJTY2hlbWEsIERlYnVnQ2FwdHVyZUV2ZW50U2NoZW1hLCBEZWJ1Z0NhcHR1cmVFdmVudHNTY2hlbWEsIERlYnVnQ2FwdHVyZUlkU2NoZW1hLCBEZWJ1Z0NhcHR1cmVSZXF1ZXN0U2NoZW1hLCBEZWJ1Z0NhcHR1cmVTdGFydFJlc3BvbnNlU2NoZW1hLCBEZWJ1Z0NhcHR1cmVBcHBlbmRSZXNwb25zZVNjaGVtYSwgRGVidWdDYXB0dXJlU3RvcFJlc3BvbnNlU2NoZW1hLCBEZWJ1Z0NhcHR1cmVDbGllbnRDb25maWdTY2hlbWEgfSBmcm9tIFwiLi9zcmMvZGVidWcvY29udHJhY3RzLnRzXCI7XG5leHBvcnQgdHlwZSB7IERlYnVnQ2FwdHVyZVNjYWxhciwgRGVidWdDYXB0dXJlRXZlbnQsIERlYnVnQ2FwdHVyZVJlcXVlc3QsIERlYnVnQ2FwdHVyZUNsaWVudENvbmZpZyB9IGZyb20gXCIuL3NyYy9kZWJ1Zy9jb250cmFjdHMudHNcIjtcbiJdfQ==

package/lib/index.js

@@ -0,0 +1,6 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+export const PACKAGE_IDENTIFIER = "@dbx-tools/shared-appkit";
+export const PACKAGE_VERSION = "0.9.188";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRywwQkFBMEIsQ0FBQztBQUM3RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsU0FBUyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0IGNvbnN0IFBBQ0tBR0VfSURFTlRJRklFUiA9IFwiQGRieC10b29scy9zaGFyZWQtYXBwa2l0XCI7XG5leHBvcnQgY29uc3QgUEFDS0FHRV9WRVJTSU9OID0gXCIwLjkuMTg4XCI7XG4iXX0=

package/lib/src/debug/contracts.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/** Registered AppKit plugin name for browser debug capture. */
+export declare const DEBUG_CAPTURE_PLUGIN_NAME = "debugCapture";
+/** Route segment registered beneath the debug-capture plugin base path. */
+export declare const DEBUG_CAPTURE_ROUTE = "/captures";
+/** Default AppKit mount for the debug-capture plugin. */
+export declare const DEBUG_CAPTURE_DEFAULT_BASE_PATH = "/api/debug-capture";
+/** Build the browser debug-capture endpoint from a published plugin base path. */
+export declare function debugCaptureRoute(basePath?: string): string;
+/** Scalar value allowed in debug capture metadata and event snapshots. */
+export declare const DebugCaptureScalarSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+/** Scalar value allowed in debug capture metadata and event snapshots. */
+export type DebugCaptureScalar = z.infer<typeof DebugCaptureScalarSchema>;
+/** One timestamped browser diagnostic event. */
+export declare const DebugCaptureEventSchema: z.ZodObject<{
+    at: z.ZodNumber;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    sequence: z.ZodNumber;
+    type: z.ZodString;
+}, z.core.$strict>;
+/** One timestamped browser diagnostic event. */
+export type DebugCaptureEvent = z.infer<typeof DebugCaptureEventSchema>;
+/** Bounded event batch accepted by append and stop requests. */
+export declare const DebugCaptureEventsSchema: z.ZodArray<z.ZodObject<{
+    at: z.ZodNumber;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    sequence: z.ZodNumber;
+    type: z.ZodString;
+}, z.core.$strict>>;
+/** Capture identifier generated by the AppKit debug plugin. */
+export declare const DebugCaptureIdSchema: z.ZodString;
+/** Request body accepted by the debug-capture route. */
+export declare const DebugCaptureRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"start">;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"append">;
+    captureId: z.ZodString;
+    events: z.ZodArray<z.ZodObject<{
+        at: z.ZodNumber;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        sequence: z.ZodNumber;
+        type: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"stop">;
+    captureId: z.ZodString;
+    events: z.ZodArray<z.ZodObject<{
+        at: z.ZodNumber;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        sequence: z.ZodNumber;
+        type: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "action">;
+/** Request body accepted by the debug-capture route. */
+export type DebugCaptureRequest = z.infer<typeof DebugCaptureRequestSchema>;
+/** Response returned after starting a browser debug capture. */
+export declare const DebugCaptureStartResponseSchema: z.ZodObject<{
+    captureId: z.ZodString;
+}, z.core.$strict>;
+/** Response returned after appending browser debug events. */
+export declare const DebugCaptureAppendResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strict>;
+/** Response returned after stopping a browser debug capture. */
+export declare const DebugCaptureStopResponseSchema: z.ZodObject<{
+    captureId: z.ZodString;
+    ok: z.ZodLiteral<true>;
+}, z.core.$strict>;
+/** Browser-safe configuration published by the AppKit debug-capture plugin. */
+export declare const DebugCaptureClientConfigSchema: z.ZodObject<{
+    basePath: z.ZodString;
+}, z.core.$strict>;
+/** Browser-safe configuration published by the AppKit debug-capture plugin. */
+export type DebugCaptureClientConfig = z.infer<typeof DebugCaptureClientConfigSchema>;

package/lib/src/debug/contracts.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+/** Registered AppKit plugin name for browser debug capture. */
+export const DEBUG_CAPTURE_PLUGIN_NAME = "debugCapture";
+/** Route segment registered beneath the debug-capture plugin base path. */
+export const DEBUG_CAPTURE_ROUTE = "/captures";
+/** Default AppKit mount for the debug-capture plugin. */
+export const DEBUG_CAPTURE_DEFAULT_BASE_PATH = "/api/debug-capture";
+/** Build the browser debug-capture endpoint from a published plugin base path. */
+export function debugCaptureRoute(basePath = DEBUG_CAPTURE_DEFAULT_BASE_PATH) {
+    return `${basePath.replace(/\/+$/, "")}${DEBUG_CAPTURE_ROUTE}`;
+}
+/** Scalar value allowed in debug capture metadata and event snapshots. */
+export const DebugCaptureScalarSchema = z
+    .union([z.string().max(500), z.number().finite(), z.boolean(), z.null()])
+    .describe("Bounded scalar diagnostic value safe to serialize as JSON.");
+/** One timestamped browser diagnostic event. */
+export const DebugCaptureEventSchema = z
+    .object({
+    at: z
+        .number()
+        .finite()
+        .nonnegative()
+        .describe("Milliseconds elapsed since this capture started."),
+    data: z
+        .record(z.string().max(80), DebugCaptureScalarSchema)
+        .optional()
+        .describe("Browser, viewport, target, and selected element measurements."),
+    sequence: z.number().int().nonnegative().describe("Monotonic event sequence number."),
+    type: z.string().min(1).max(80).describe("Normalized browser or recorder event name."),
+})
+    .strict()
+    .describe("One browser debug-capture event.");
+/** Bounded event batch accepted by append and stop requests. */
+export const DebugCaptureEventsSchema = z
+    .array(DebugCaptureEventSchema)
+    .max(200)
+    .describe("Ordered browser diagnostic events uploaded in one request.");
+/** Capture identifier generated by the AppKit debug plugin. */
+export const DebugCaptureIdSchema = z
+    .string()
+    .regex(/^vp-[a-z0-9]+-[a-f0-9]{8}$/)
+    .describe("Opaque browser debug-capture identifier.");
+/** Request body accepted by the debug-capture route. */
+export const DebugCaptureRequestSchema = z
+    .discriminatedUnion("action", [
+    z
+        .object({
+        action: z.literal("start").describe("Start a new capture."),
+        metadata: z
+            .record(z.string().max(80), DebugCaptureScalarSchema)
+            .describe("Initial application, route, device, and browser metadata."),
+    })
+        .strict(),
+    z
+        .object({
+        action: z.literal("append").describe("Append buffered events."),
+        captureId: DebugCaptureIdSchema,
+        events: DebugCaptureEventsSchema,
+    })
+        .strict(),
+    z
+        .object({
+        action: z.literal("stop").describe("Append final events and close the capture."),
+        captureId: DebugCaptureIdSchema,
+        events: DebugCaptureEventsSchema,
+    })
+        .strict(),
+])
+    .describe("Start, append, or stop request for a browser debug capture.");
+/** Response returned after starting a browser debug capture. */
+export const DebugCaptureStartResponseSchema = z
+    .object({
+    captureId: DebugCaptureIdSchema,
+})
+    .strict()
+    .describe("New browser debug-capture identifier.");
+/** Response returned after appending browser debug events. */
+export const DebugCaptureAppendResponseSchema = z
+    .object({
+    ok: z.literal(true).describe("Whether the event batch was persisted."),
+})
+    .strict()
+    .describe("Browser debug-capture append result.");
+/** Response returned after stopping a browser debug capture. */
+export const DebugCaptureStopResponseSchema = z
+    .object({
+    captureId: DebugCaptureIdSchema,
+    ok: z.literal(true).describe("Whether the capture was closed."),
+})
+    .strict()
+    .describe("Completed browser debug-capture result.");
+/** Browser-safe configuration published by the AppKit debug-capture plugin. */
+export const DebugCaptureClientConfigSchema = z
+    .object({
+    basePath: z.string().min(1).describe("AppKit mount containing the capture route."),
+})
+    .strict()
+    .describe("Browser-safe AppKit debug-capture configuration.");
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udHJhY3RzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2RlYnVnL2NvbnRyYWN0cy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsQ0FBQyxFQUFFLE1BQU0sS0FBSyxDQUFDO0FBRXhCLCtEQUErRDtBQUMvRCxNQUFNLENBQUMsTUFBTSx5QkFBeUIsR0FBRyxjQUFjLENBQUM7QUFFeEQsMkVBQTJFO0FBQzNFLE1BQU0sQ0FBQyxNQUFNLG1CQUFtQixHQUFHLFdBQVcsQ0FBQztBQUUvQyx5REFBeUQ7QUFDekQsTUFBTSxDQUFDLE1BQU0sK0JBQStCLEdBQUcsb0JBQW9CLENBQUM7QUFFcEUsa0ZBQWtGO0FBQ2xGLE1BQU0sVUFBVSxpQkFBaUIsQ0FBQyxRQUFRLEdBQUcsK0JBQStCO0lBQzFFLE9BQU8sR0FBRyxRQUFRLENBQUMsT0FBTyxDQUFDLE1BQU0sRUFBRSxFQUFFLENBQUMsR0FBRyxtQkFBbUIsRUFBRSxDQUFDO0FBQ2pFLENBQUM7QUFFRCwwRUFBMEU7QUFDMUUsTUFBTSxDQUFDLE1BQU0sd0JBQXdCLEdBQUcsQ0FBQztLQUN0QyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUMsTUFBTSxFQUFFLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxFQUFFLENBQUMsQ0FBQyxNQUFNLEVBQUUsQ0FBQyxNQUFNLEVBQUUsRUFBRSxDQUFDLENBQUMsT0FBTyxFQUFFLEVBQUUsQ0FBQyxDQUFDLElBQUksRUFBRSxDQUFDLENBQUM7S0FDeEUsUUFBUSxDQUFDLDREQUE0RCxDQUFDLENBQUM7QUFLMUUsZ0RBQWdEO0FBQ2hELE1BQU0sQ0FBQyxNQUFNLHVCQUF1QixHQUFHLENBQUM7S0FDckMsTUFBTSxDQUFDO0lBQ04sRUFBRSxFQUFFLENBQUM7U0FDRixNQUFNLEVBQUU7U0FDUixNQUFNLEVBQUU7U0FDUixXQUFXLEVBQUU7U0FDYixRQUFRLENBQUMsa0RBQWtELENBQUM7SUFDL0QsSUFBSSxFQUFFLENBQUM7U0FDSixNQUFNLENBQUMsQ0FBQyxDQUFDLE1BQU0sRUFBRSxDQUFDLEdBQUcsQ0FBQyxFQUFFLENBQUMsRUFBRSx3QkFBd0IsQ0FBQztTQUNwRCxRQUFRLEVBQUU7U0FDVixRQUFRLENBQUMsK0RBQStELENBQUM7SUFDNUUsUUFBUSxFQUFFLENBQUMsQ0FBQyxNQUFNLEVBQUUsQ0FBQyxHQUFHLEVBQUUsQ0FBQyxXQUFXLEVBQUUsQ0FBQyxRQUFRLENBQUMsa0NBQWtDLENBQUM7SUFDckYsSUFBSSxFQUFFLENBQUMsQ0FBQyxNQUFNLEVBQUUsQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQyxDQUFDLFFBQVEsQ0FBQyw0Q0FBNEMsQ0FBQztDQUN2RixDQUFDO0tBQ0QsTUFBTSxFQUFFO0tBQ1IsUUFBUSxDQUFDLGtDQUFrQyxDQUFDLENBQUM7QUFLaEQsZ0VBQWdFO0FBQ2hFLE1BQU0sQ0FBQyxNQUFNLHdCQUF3QixHQUFHLENBQUM7S0FDdEMsS0FBSyxDQUFDLHVCQUF1QixDQUFDO0tBQzlCLEdBQUcsQ0FBQyxHQUFHLENBQUM7S0FDUixRQUFRLENBQUMsNERBQTRELENBQUMsQ0FBQztBQUUxRSwrREFBK0Q7QUFDL0QsTUFBTSxDQUFDLE1BQU0sb0JBQW9CLEdBQUcsQ0FBQztLQUNsQyxNQUFNLEVBQUU7S0FDUixLQUFLLENBQUMsNEJBQTRCLENBQUM7S0FDbkMsUUFBUSxDQUFDLDBDQUEwQyxDQUFDLENBQUM7QUFFeEQsd0RBQXdEO0FBQ3hELE1BQU0sQ0FBQyxNQUFNLHlCQUF5QixHQUFHLENBQUM7S0FDdkMsa0JBQWtCLENBQUMsUUFBUSxFQUFFO0lBQzVCLENBQUM7U0FDRSxNQUFNLENBQUM7UUFDTixNQUFNLEVBQUUsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FBQyxRQUFRLENBQUMsc0JBQXNCLENBQUM7UUFDM0QsUUFBUSxFQUFFLENBQUM7YUFDUixNQUFNLENBQUMsQ0FBQyxDQUFDLE1BQU0sRUFBRSxDQUFDLEdBQUcsQ0FBQyxFQUFFLENBQUMsRUFBRSx3QkFBd0IsQ0FBQzthQUNwRCxRQUFRLENBQUMsMkRBQTJELENBQUM7S0FDekUsQ0FBQztTQUNELE1BQU0sRUFBRTtJQUNYLENBQUM7U0FDRSxNQUFNLENBQUM7UUFDTixNQUFNLEVBQUUsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsQ0FBQyxRQUFRLENBQUMseUJBQXlCLENBQUM7UUFDL0QsU0FBUyxFQUFFLG9CQUFvQjtRQUMvQixNQUFNLEVBQUUsd0JBQXdCO0tBQ2pDLENBQUM7U0FDRCxNQUFNLEVBQUU7SUFDWCxDQUFDO1NBQ0UsTUFBTSxDQUFDO1FBQ04sTUFBTSxFQUFFLENBQUMsQ0FBQyxPQUFPLENBQUMsTUFBTSxDQUFDLENBQUMsUUFBUSxDQUFDLDRDQUE0QyxDQUFDO1FBQ2hGLFNBQVMsRUFBRSxvQkFBb0I7UUFDL0IsTUFBTSxFQUFFLHdCQUF3QjtLQUNqQyxDQUFDO1NBQ0QsTUFBTSxFQUFFO0NBQ1osQ0FBQztLQUNELFFBQVEsQ0FBQyw2REFBNkQsQ0FBQyxDQUFDO0FBSzNFLGdFQUFnRTtBQUNoRSxNQUFNLENBQUMsTUFBTSwrQkFBK0IsR0FBRyxDQUFDO0tBQzdDLE1BQU0sQ0FBQztJQUNOLFNBQVMsRUFBRSxvQkFBb0I7Q0FDaEMsQ0FBQztLQUNELE1BQU0sRUFBRTtLQUNSLFFBQVEsQ0FBQyx1Q0FBdUMsQ0FBQyxDQUFDO0FBRXJELDhEQUE4RDtBQUM5RCxNQUFNLENBQUMsTUFBTSxnQ0FBZ0MsR0FBRyxDQUFDO0tBQzlDLE1BQU0sQ0FBQztJQUNOLEVBQUUsRUFBRSxDQUFDLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDLFFBQVEsQ0FBQyx3Q0FBd0MsQ0FBQztDQUN2RSxDQUFDO0tBQ0QsTUFBTSxFQUFFO0tBQ1IsUUFBUSxDQUFDLHNDQUFzQyxDQUFDLENBQUM7QUFFcEQsZ0VBQWdFO0FBQ2hFLE1BQU0sQ0FBQyxNQUFNLDhCQUE4QixHQUFHLENBQUM7S0FDNUMsTUFBTSxDQUFDO0lBQ04sU0FBUyxFQUFFLG9CQUFvQjtJQUMvQixFQUFFLEVBQUUsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQyxRQUFRLENBQUMsaUNBQWlDLENBQUM7Q0FDaEUsQ0FBQztLQUNELE1BQU0sRUFBRTtLQUNSLFFBQVEsQ0FBQyx5Q0FBeUMsQ0FBQyxDQUFDO0FBRXZELCtFQUErRTtBQUMvRSxNQUFNLENBQUMsTUFBTSw4QkFBOEIsR0FBRyxDQUFDO0tBQzVDLE1BQU0sQ0FBQztJQUNOLFFBQVEsRUFBRSxDQUFDLENBQUMsTUFBTSxFQUFFLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyw0Q0FBNEMsQ0FBQztDQUNuRixDQUFDO0tBQ0QsTUFBTSxFQUFFO0tBQ1IsUUFBUSxDQUFDLGtEQUFrRCxDQUFDLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyB6IH0gZnJvbSBcInpvZFwiO1xuXG4vKiogUmVnaXN0ZXJlZCBBcHBLaXQgcGx1Z2luIG5hbWUgZm9yIGJyb3dzZXIgZGVidWcgY2FwdHVyZS4gKi9cbmV4cG9ydCBjb25zdCBERUJVR19DQVBUVVJFX1BMVUdJTl9OQU1FID0gXCJkZWJ1Z0NhcHR1cmVcIjtcblxuLyoqIFJvdXRlIHNlZ21lbnQgcmVnaXN0ZXJlZCBiZW5lYXRoIHRoZSBkZWJ1Zy1jYXB0dXJlIHBsdWdpbiBiYXNlIHBhdGguICovXG5leHBvcnQgY29uc3QgREVCVUdfQ0FQVFVSRV9ST1VURSA9IFwiL2NhcHR1cmVzXCI7XG5cbi8qKiBEZWZhdWx0IEFwcEtpdCBtb3VudCBmb3IgdGhlIGRlYnVnLWNhcHR1cmUgcGx1Z2luLiAqL1xuZXhwb3J0IGNvbnN0IERFQlVHX0NBUFRVUkVfREVGQVVMVF9CQVNFX1BBVEggPSBcIi9hcGkvZGVidWctY2FwdHVyZVwiO1xuXG4vKiogQnVpbGQgdGhlIGJyb3dzZXIgZGVidWctY2FwdHVyZSBlbmRwb2ludCBmcm9tIGEgcHVibGlzaGVkIHBsdWdpbiBiYXNlIHBhdGguICovXG5leHBvcnQgZnVuY3Rpb24gZGVidWdDYXB0dXJlUm91dGUoYmFzZVBhdGggPSBERUJVR19DQVBUVVJFX0RFRkFVTFRfQkFTRV9QQVRIKTogc3RyaW5nIHtcbiAgcmV0dXJuIGAke2Jhc2VQYXRoLnJlcGxhY2UoL1xcLyskLywgXCJcIil9JHtERUJVR19DQVBUVVJFX1JPVVRFfWA7XG59XG5cbi8qKiBTY2FsYXIgdmFsdWUgYWxsb3dlZCBpbiBkZWJ1ZyBjYXB0dXJlIG1ldGFkYXRhIGFuZCBldmVudCBzbmFwc2hvdHMuICovXG5leHBvcnQgY29uc3QgRGVidWdDYXB0dXJlU2NhbGFyU2NoZW1hID0gelxuICAudW5pb24oW3ouc3RyaW5nKCkubWF4KDUwMCksIHoubnVtYmVyKCkuZmluaXRlKCksIHouYm9vbGVhbigpLCB6Lm51bGwoKV0pXG4gIC5kZXNjcmliZShcIkJvdW5kZWQgc2NhbGFyIGRpYWdub3N0aWMgdmFsdWUgc2FmZSB0byBzZXJpYWxpemUgYXMgSlNPTi5cIik7XG5cbi8qKiBTY2FsYXIgdmFsdWUgYWxsb3dlZCBpbiBkZWJ1ZyBjYXB0dXJlIG1ldGFkYXRhIGFuZCBldmVudCBzbmFwc2hvdHMuICovXG5leHBvcnQgdHlwZSBEZWJ1Z0NhcHR1cmVTY2FsYXIgPSB6LmluZmVyPHR5cGVvZiBEZWJ1Z0NhcHR1cmVTY2FsYXJTY2hlbWE+O1xuXG4vKiogT25lIHRpbWVzdGFtcGVkIGJyb3dzZXIgZGlhZ25vc3RpYyBldmVudC4gKi9cbmV4cG9ydCBjb25zdCBEZWJ1Z0NhcHR1cmVFdmVudFNjaGVtYSA9IHpcbiAgLm9iamVjdCh7XG4gICAgYXQ6IHpcbiAgICAgIC5udW1iZXIoKVxuICAgICAgLmZpbml0ZSgpXG4gICAgICAubm9ubmVnYXRpdmUoKVxuICAgICAgLmRlc2NyaWJlKFwiTWlsbGlzZWNvbmRzIGVsYXBzZWQgc2luY2UgdGhpcyBjYXB0dXJlIHN0YXJ0ZWQuXCIpLFxuICAgIGRhdGE6IHpcbiAgICAgIC5yZWNvcmQoei5zdHJpbmcoKS5tYXgoODApLCBEZWJ1Z0NhcHR1cmVTY2FsYXJTY2hlbWEpXG4gICAgICAub3B0aW9uYWwoKVxuICAgICAgLmRlc2NyaWJlKFwiQnJvd3Nlciwgdmlld3BvcnQsIHRhcmdldCwgYW5kIHNlbGVjdGVkIGVsZW1lbnQgbWVhc3VyZW1lbnRzLlwiKSxcbiAgICBzZXF1ZW5jZTogei5udW1iZXIoKS5pbnQoKS5ub25uZWdhdGl2ZSgpLmRlc2NyaWJlKFwiTW9ub3RvbmljIGV2ZW50IHNlcXVlbmNlIG51bWJlci5cIiksXG4gICAgdHlwZTogei5zdHJpbmcoKS5taW4oMSkubWF4KDgwKS5kZXNjcmliZShcIk5vcm1hbGl6ZWQgYnJvd3NlciBvciByZWNvcmRlciBldmVudCBuYW1lLlwiKSxcbiAgfSlcbiAgLnN0cmljdCgpXG4gIC5kZXNjcmliZShcIk9uZSBicm93c2VyIGRlYnVnLWNhcHR1cmUgZXZlbnQuXCIpO1xuXG4vKiogT25lIHRpbWVzdGFtcGVkIGJyb3dzZXIgZGlhZ25vc3RpYyBldmVudC4gKi9cbmV4cG9ydCB0eXBlIERlYnVnQ2FwdHVyZUV2ZW50ID0gei5pbmZlcjx0eXBlb2YgRGVidWdDYXB0dXJlRXZlbnRTY2hlbWE+O1xuXG4vKiogQm91bmRlZCBldmVudCBiYXRjaCBhY2NlcHRlZCBieSBhcHBlbmQgYW5kIHN0b3AgcmVxdWVzdHMuICovXG5leHBvcnQgY29uc3QgRGVidWdDYXB0dXJlRXZlbnRzU2NoZW1hID0gelxuICAuYXJyYXkoRGVidWdDYXB0dXJlRXZlbnRTY2hlbWEpXG4gIC5tYXgoMjAwKVxuICAuZGVzY3JpYmUoXCJPcmRlcmVkIGJyb3dzZXIgZGlhZ25vc3RpYyBldmVudHMgdXBsb2FkZWQgaW4gb25lIHJlcXVlc3QuXCIpO1xuXG4vKiogQ2FwdHVyZSBpZGVudGlmaWVyIGdlbmVyYXRlZCBieSB0aGUgQXBwS2l0IGRlYnVnIHBsdWdpbi4gKi9cbmV4cG9ydCBjb25zdCBEZWJ1Z0NhcHR1cmVJZFNjaGVtYSA9IHpcbiAgLnN0cmluZygpXG4gIC5yZWdleCgvXnZwLVthLXowLTldKy1bYS1mMC05XXs4fSQvKVxuICAuZGVzY3JpYmUoXCJPcGFxdWUgYnJvd3NlciBkZWJ1Zy1jYXB0dXJlIGlkZW50aWZpZXIuXCIpO1xuXG4vKiogUmVxdWVzdCBib2R5IGFjY2VwdGVkIGJ5IHRoZSBkZWJ1Zy1jYXB0dXJlIHJvdXRlLiAqL1xuZXhwb3J0IGNvbnN0IERlYnVnQ2FwdHVyZVJlcXVlc3RTY2hlbWEgPSB6XG4gIC5kaXNjcmltaW5hdGVkVW5pb24oXCJhY3Rpb25cIiwgW1xuICAgIHpcbiAgICAgIC5vYmplY3Qoe1xuICAgICAgICBhY3Rpb246IHoubGl0ZXJhbChcInN0YXJ0XCIpLmRlc2NyaWJlKFwiU3RhcnQgYSBuZXcgY2FwdHVyZS5cIiksXG4gICAgICAgIG1ldGFkYXRhOiB6XG4gICAgICAgICAgLnJlY29yZCh6LnN0cmluZygpLm1heCg4MCksIERlYnVnQ2FwdHVyZVNjYWxhclNjaGVtYSlcbiAgICAgICAgICAuZGVzY3JpYmUoXCJJbml0aWFsIGFwcGxpY2F0aW9uLCByb3V0ZSwgZGV2aWNlLCBhbmQgYnJvd3NlciBtZXRhZGF0YS5cIiksXG4gICAgICB9KVxuICAgICAgLnN0cmljdCgpLFxuICAgIHpcbiAgICAgIC5vYmplY3Qoe1xuICAgICAgICBhY3Rpb246IHoubGl0ZXJhbChcImFwcGVuZFwiKS5kZXNjcmliZShcIkFwcGVuZCBidWZmZXJlZCBldmVudHMuXCIpLFxuICAgICAgICBjYXB0dXJlSWQ6IERlYnVnQ2FwdHVyZUlkU2NoZW1hLFxuICAgICAgICBldmVudHM6IERlYnVnQ2FwdHVyZUV2ZW50c1NjaGVtYSxcbiAgICAgIH0pXG4gICAgICAuc3RyaWN0KCksXG4gICAgelxuICAgICAgLm9iamVjdCh7XG4gICAgICAgIGFjdGlvbjogei5saXRlcmFsKFwic3RvcFwiKS5kZXNjcmliZShcIkFwcGVuZCBmaW5hbCBldmVudHMgYW5kIGNsb3NlIHRoZSBjYXB0dXJlLlwiKSxcbiAgICAgICAgY2FwdHVyZUlkOiBEZWJ1Z0NhcHR1cmVJZFNjaGVtYSxcbiAgICAgICAgZXZlbnRzOiBEZWJ1Z0NhcHR1cmVFdmVudHNTY2hlbWEsXG4gICAgICB9KVxuICAgICAgLnN0cmljdCgpLFxuICBdKVxuICAuZGVzY3JpYmUoXCJTdGFydCwgYXBwZW5kLCBvciBzdG9wIHJlcXVlc3QgZm9yIGEgYnJvd3NlciBkZWJ1ZyBjYXB0dXJlLlwiKTtcblxuLyoqIFJlcXVlc3QgYm9keSBhY2NlcHRlZCBieSB0aGUgZGVidWctY2FwdHVyZSByb3V0ZS4gKi9cbmV4cG9ydCB0eXBlIERlYnVnQ2FwdHVyZVJlcXVlc3QgPSB6LmluZmVyPHR5cGVvZiBEZWJ1Z0NhcHR1cmVSZXF1ZXN0U2NoZW1hPjtcblxuLyoqIFJlc3BvbnNlIHJldHVybmVkIGFmdGVyIHN0YXJ0aW5nIGEgYnJvd3NlciBkZWJ1ZyBjYXB0dXJlLiAqL1xuZXhwb3J0IGNvbnN0IERlYnVnQ2FwdHVyZVN0YXJ0UmVzcG9uc2VTY2hlbWEgPSB6XG4gIC5vYmplY3Qoe1xuICAgIGNhcHR1cmVJZDogRGVidWdDYXB0dXJlSWRTY2hlbWEsXG4gIH0pXG4gIC5zdHJpY3QoKVxuICAuZGVzY3JpYmUoXCJOZXcgYnJvd3NlciBkZWJ1Zy1jYXB0dXJlIGlkZW50aWZpZXIuXCIpO1xuXG4vKiogUmVzcG9uc2UgcmV0dXJuZWQgYWZ0ZXIgYXBwZW5kaW5nIGJyb3dzZXIgZGVidWcgZXZlbnRzLiAqL1xuZXhwb3J0IGNvbnN0IERlYnVnQ2FwdHVyZUFwcGVuZFJlc3BvbnNlU2NoZW1hID0gelxuICAub2JqZWN0KHtcbiAgICBvazogei5saXRlcmFsKHRydWUpLmRlc2NyaWJlKFwiV2hldGhlciB0aGUgZXZlbnQgYmF0Y2ggd2FzIHBlcnNpc3RlZC5cIiksXG4gIH0pXG4gIC5zdHJpY3QoKVxuICAuZGVzY3JpYmUoXCJCcm93c2VyIGRlYnVnLWNhcHR1cmUgYXBwZW5kIHJlc3VsdC5cIik7XG5cbi8qKiBSZXNwb25zZSByZXR1cm5lZCBhZnRlciBzdG9wcGluZyBhIGJyb3dzZXIgZGVidWcgY2FwdHVyZS4gKi9cbmV4cG9ydCBjb25zdCBEZWJ1Z0NhcHR1cmVTdG9wUmVzcG9uc2VTY2hlbWEgPSB6XG4gIC5vYmplY3Qoe1xuICAgIGNhcHR1cmVJZDogRGVidWdDYXB0dXJlSWRTY2hlbWEsXG4gICAgb2s6IHoubGl0ZXJhbCh0cnVlKS5kZXNjcmliZShcIldoZXRoZXIgdGhlIGNhcHR1cmUgd2FzIGNsb3NlZC5cIiksXG4gIH0pXG4gIC5zdHJpY3QoKVxuICAuZGVzY3JpYmUoXCJDb21wbGV0ZWQgYnJvd3NlciBkZWJ1Zy1jYXB0dXJlIHJlc3VsdC5cIik7XG5cbi8qKiBCcm93c2VyLXNhZmUgY29uZmlndXJhdGlvbiBwdWJsaXNoZWQgYnkgdGhlIEFwcEtpdCBkZWJ1Zy1jYXB0dXJlIHBsdWdpbi4gKi9cbmV4cG9ydCBjb25zdCBEZWJ1Z0NhcHR1cmVDbGllbnRDb25maWdTY2hlbWEgPSB6XG4gIC5vYmplY3Qoe1xuICAgIGJhc2VQYXRoOiB6LnN0cmluZygpLm1pbigxKS5kZXNjcmliZShcIkFwcEtpdCBtb3VudCBjb250YWluaW5nIHRoZSBjYXB0dXJlIHJvdXRlLlwiKSxcbiAgfSlcbiAgLnN0cmljdCgpXG4gIC5kZXNjcmliZShcIkJyb3dzZXItc2FmZSBBcHBLaXQgZGVidWctY2FwdHVyZSBjb25maWd1cmF0aW9uLlwiKTtcblxuLyoqIEJyb3dzZXItc2FmZSBjb25maWd1cmF0aW9uIHB1Ymxpc2hlZCBieSB0aGUgQXBwS2l0IGRlYnVnLWNhcHR1cmUgcGx1Z2luLiAqL1xuZXhwb3J0IHR5cGUgRGVidWdDYXB0dXJlQ2xpZW50Q29uZmlnID0gei5pbmZlcjx0eXBlb2YgRGVidWdDYXB0dXJlQ2xpZW50Q29uZmlnU2NoZW1hPjtcbiJdfQ==

package/lib/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/debug/contracts.ts","../index.debug.ts","../index.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@dbx-tools/shared-appkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Browser-safe contracts for dbx-tools AppKit plugins and development diagnostics",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "packages/js/shared/appkit"
+  },
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "prepack": "projen prepack",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "zod": "4.3.6"
+  },
+  "main": "./lib/index.js",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "./lib/index.js",
+    "types": "./lib/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "./debug": {
+        "types": "./lib/index.debug.d.ts",
+        "default": "./lib/index.debug.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "version": "0.9.188",
+  "types": "./lib/index.d.ts",
+  "dbxToolsConfig": {
+    "tags": [
+      "shared"
+    ]
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./debug": {
+      "types": "./lib/index.debug.d.ts",
+      "default": "./lib/index.debug.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index*.ts",
+    "src",
+    "lib"
+  ],
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"bunx projen\"."
+}

package/src/debug/contracts.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+
+/** Registered AppKit plugin name for browser debug capture. */
+export const DEBUG_CAPTURE_PLUGIN_NAME = "debugCapture";
+
+/** Route segment registered beneath the debug-capture plugin base path. */
+export const DEBUG_CAPTURE_ROUTE = "/captures";
+
+/** Default AppKit mount for the debug-capture plugin. */
+export const DEBUG_CAPTURE_DEFAULT_BASE_PATH = "/api/debug-capture";
+
+/** Build the browser debug-capture endpoint from a published plugin base path. */
+export function debugCaptureRoute(basePath = DEBUG_CAPTURE_DEFAULT_BASE_PATH): string {
+  return `${basePath.replace(/\/+$/, "")}${DEBUG_CAPTURE_ROUTE}`;
+}
+
+/** Scalar value allowed in debug capture metadata and event snapshots. */
+export const DebugCaptureScalarSchema = z
+  .union([z.string().max(500), z.number().finite(), z.boolean(), z.null()])
+  .describe("Bounded scalar diagnostic value safe to serialize as JSON.");
+
+/** Scalar value allowed in debug capture metadata and event snapshots. */
+export type DebugCaptureScalar = z.infer<typeof DebugCaptureScalarSchema>;
+
+/** One timestamped browser diagnostic event. */
+export const DebugCaptureEventSchema = z
+  .object({
+    at: z
+      .number()
+      .finite()
+      .nonnegative()
+      .describe("Milliseconds elapsed since this capture started."),
+    data: z
+      .record(z.string().max(80), DebugCaptureScalarSchema)
+      .optional()
+      .describe("Browser, viewport, target, and selected element measurements."),
+    sequence: z.number().int().nonnegative().describe("Monotonic event sequence number."),
+    type: z.string().min(1).max(80).describe("Normalized browser or recorder event name."),
+  })
+  .strict()
+  .describe("One browser debug-capture event.");
+
+/** One timestamped browser diagnostic event. */
+export type DebugCaptureEvent = z.infer<typeof DebugCaptureEventSchema>;
+
+/** Bounded event batch accepted by append and stop requests. */
+export const DebugCaptureEventsSchema = z
+  .array(DebugCaptureEventSchema)
+  .max(200)
+  .describe("Ordered browser diagnostic events uploaded in one request.");
+
+/** Capture identifier generated by the AppKit debug plugin. */
+export const DebugCaptureIdSchema = z
+  .string()
+  .regex(/^vp-[a-z0-9]+-[a-f0-9]{8}$/)
+  .describe("Opaque browser debug-capture identifier.");
+
+/** Request body accepted by the debug-capture route. */
+export const DebugCaptureRequestSchema = z
+  .discriminatedUnion("action", [
+    z
+      .object({
+        action: z.literal("start").describe("Start a new capture."),
+        metadata: z
+          .record(z.string().max(80), DebugCaptureScalarSchema)
+          .describe("Initial application, route, device, and browser metadata."),
+      })
+      .strict(),
+    z
+      .object({
+        action: z.literal("append").describe("Append buffered events."),
+        captureId: DebugCaptureIdSchema,
+        events: DebugCaptureEventsSchema,
+      })
+      .strict(),
+    z
+      .object({
+        action: z.literal("stop").describe("Append final events and close the capture."),
+        captureId: DebugCaptureIdSchema,
+        events: DebugCaptureEventsSchema,
+      })
+      .strict(),
+  ])
+  .describe("Start, append, or stop request for a browser debug capture.");
+
+/** Request body accepted by the debug-capture route. */
+export type DebugCaptureRequest = z.infer<typeof DebugCaptureRequestSchema>;
+
+/** Response returned after starting a browser debug capture. */
+export const DebugCaptureStartResponseSchema = z
+  .object({
+    captureId: DebugCaptureIdSchema,
+  })
+  .strict()
+  .describe("New browser debug-capture identifier.");
+
+/** Response returned after appending browser debug events. */
+export const DebugCaptureAppendResponseSchema = z
+  .object({
+    ok: z.literal(true).describe("Whether the event batch was persisted."),
+  })
+  .strict()
+  .describe("Browser debug-capture append result.");
+
+/** Response returned after stopping a browser debug capture. */
+export const DebugCaptureStopResponseSchema = z
+  .object({
+    captureId: DebugCaptureIdSchema,
+    ok: z.literal(true).describe("Whether the capture was closed."),
+  })
+  .strict()
+  .describe("Completed browser debug-capture result.");
+
+/** Browser-safe configuration published by the AppKit debug-capture plugin. */
+export const DebugCaptureClientConfigSchema = z
+  .object({
+    basePath: z.string().min(1).describe("AppKit mount containing the capture route."),
+  })
+  .strict()
+  .describe("Browser-safe AppKit debug-capture configuration.");
+
+/** Browser-safe configuration published by the AppKit debug-capture plugin. */
+export type DebugCaptureClientConfig = z.infer<typeof DebugCaptureClientConfigSchema>;