@localpreview/protocol 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,161 @@
+# @localpreview/protocol
+
+Shared protocol contract for LocalPreview packages.
+
+This package contains the stable shapes and helpers used by the CLI,
+control-plane, and relay. Keep runtime-specific code out of this package; it
+should stay small, dependency-light, and safe to import from every LocalPreview
+runtime.
+
+## What Lives Here
+
+- Public LocalPreview origin constants.
+- Tunnel creation and relay registration response/request shapes.
+- Relay WebSocket message encoding and validation.
+- Shared error codes and error response shape.
+- Header filtering helpers for proxy boundaries.
+- Target and requested subdomain validation.
+- Protocol and relay snapshot version constants.
+
+## Relay Message Flow
+
+The relay protocol multiplexes browser HTTP requests over the CLI WebSocket.
+Messages are JSON strings and every message belongs to a `requestId`.
+
+```txt
+browser request
+  -> relay sends request-start/request-chunk/request-end to CLI
+  -> CLI forwards to local target
+  -> CLI sends response-start/response-chunk/response-end to relay
+  -> relay streams response back to browser
+```
+
+Server-to-client messages are decoded with `decodeServerRelayMessage`.
+Client-to-server messages are decoded with `decodeClientRelayMessage`.
+
+```ts
+import {
+  decodeServerRelayMessage,
+  encodeRelayMessage,
+  type ServerMessage,
+} from "@localpreview/protocol";
+
+const message: ServerMessage = {
+  type: "request-start",
+  requestId: "req_1",
+  method: "GET",
+  path: "/hello",
+  headers: [["host", "example.test"]],
+};
+
+const encoded = encodeRelayMessage(message);
+const decoded = decodeServerRelayMessage(encoded);
+```
+
+Decoders return `{ ok: true, message }` or `{ ok: false, error }`. They do not
+throw on invalid JSON or invalid message shapes.
+
+Request and response body chunks are sent as base64 strings in `chunkBase64`.
+Headers are represented as ordered `[name, value]` pairs rather than an object
+map so duplicate headers such as `set-cookie` are preserved.
+
+## Targets
+
+`parseTarget` normalizes CLI target input into a `TunnelTarget`.
+
+```ts
+import { parseTarget } from "@localpreview/protocol";
+
+parseTarget("4000");
+// { ok: true, target: { protocol: "http", hostname: "127.0.0.1", port: 4000 } }
+
+parseTarget("https://localhost:4000");
+// { ok: true, target: { protocol: "https", hostname: "localhost", port: 4000 } }
+```
+
+Rules:
+
+- A bare port means `http://127.0.0.1:<port>`.
+- URL targets default to `http` when no protocol is provided.
+- URL targets must use `http` or `https`.
+- URL targets must include an explicit port.
+- Ports must be integers from `1` to `65535`.
+
+## Requested Subdomains
+
+`validateRequestedSubdomain` trims and lowercases user input, rejects reserved
+names, and enforces the public subdomain format.
+
+```ts
+import { validateRequestedSubdomain } from "@localpreview/protocol";
+
+validateRequestedSubdomain("Proyecto-API");
+// { valid: true, subdomain: "proyecto-api" }
+```
+
+Valid requested subdomains:
+
+- Start and end with a lowercase letter or number after normalization.
+- May contain lowercase letters, numbers, and hyphens.
+- Must not use reserved names such as `api`, `app`, `auth`, `dashboard`, or
+  `www`.
+
+## Headers
+
+Proxy boundaries should remove hop-by-hop headers and internal LocalPreview
+headers before forwarding requests across trust boundaries.
+
+```ts
+import {
+  filterEndToEndHeaderPairs,
+  filterInternalLocalPreviewHeaderPairs,
+} from "@localpreview/protocol";
+
+const publicHeaders = filterInternalLocalPreviewHeaderPairs(
+  filterEndToEndHeaderPairs(headers),
+);
+```
+
+Use `flattenHeaderPairs` when an HTTP adapter expects alternating
+`name, value, name, value` entries.
+
+## Errors
+
+`LOCALPREVIEW_ERROR_CODES` is the shared code registry for CLI, control-plane,
+and relay failures. API responses should use the `LocalPreviewError` shape so
+clients can branch on `error.code` instead of parsing messages.
+
+```ts
+import { LOCALPREVIEW_ERROR_CODES, makeLocalPreviewError } from "@localpreview/protocol";
+
+const error = makeLocalPreviewError({
+  code: LOCALPREVIEW_ERROR_CODES.TUNNEL_NOT_FOUND,
+  message: "Tunnel not found.",
+  tunnelId: "tun_123",
+});
+```
+
+## Versioning
+
+`LOCALPREVIEW_PROTOCOL_VERSION` identifies the wire and HTTP contract expected
+by all LocalPreview packages.
+
+`LOCALPREVIEW_RELAY_SNAPSHOT_VERSION` identifies the relay snapshot build
+contract used by production sandboxes.
+
+Change `LOCALPREVIEW_PROTOCOL_VERSION` when a deployed CLI, control-plane, or
+relay would no longer understand the same request/response/message shapes.
+Change `LOCALPREVIEW_RELAY_SNAPSHOT_VERSION` when the relay snapshot must be
+rebuilt or promoted even if the protocol version stays compatible.
+
+See `../../docs/relay-snapshot.md` for the production snapshot runbook.
+
+## Development
+
+From the repo root:
+
+```sh
+pnpm --filter @localpreview/protocol test
+pnpm --filter @localpreview/protocol typecheck
+pnpm --filter @localpreview/protocol build
+```

package/dist/capture.d.ts

@@ -0,0 +1,37 @@
+import type { TunnelTarget } from "./target.js";
+/** Local backend endpoint registered via `--capture host:port`. */
+export type CaptureTarget = {
+    readonly hostname: string;
+    readonly port: number;
+};
+type ParseCaptureResult = {
+    readonly capture: CaptureTarget;
+    readonly ok: true;
+} | {
+    readonly message: string;
+    readonly ok: false;
+};
+/**
+ * Returns true when `hostname` is an allowed loopback host for capture.
+ *
+ * Allowed values: `localhost`, `127.0.0.1`, `[::1]` / `::1`, and `*.localhost`.
+ */
+export declare const isLoopbackHost: (hostname: string) => boolean;
+/**
+ * Parses `--capture host:port` input into a normalized capture target.
+ *
+ * The host must be loopback-only. Port must be between 1 and 65535.
+ */
+export declare const parseCaptureHostPort: (input: string) => ParseCaptureResult;
+/** Canonicalizes loopback hostnames for stable allowlist matching. */
+export declare const normalizeLoopbackHostname: (hostname: string) => string;
+/** Returns true when the capture matches the given target host and port. */
+export declare const captureMatchesTarget: (capture: CaptureTarget, hostname: string, port: number) => boolean;
+/** Finds an allowlisted capture for the given host and port. */
+export declare const findCapture: (captures: ReadonlyArray<CaptureTarget>, hostname: string, port: number) => CaptureTarget | undefined;
+/** Formats a capture target as `host:port` for CLI output. */
+export declare const formatCaptureOrigin: (capture: CaptureTarget) => string;
+/** Converts a capture target into a tunnel target using HTTP by default. */
+export declare const captureToTunnelTarget: (capture: CaptureTarget, protocol: TunnelTarget["protocol"]) => TunnelTarget;
+export {};
+//# sourceMappingURL=capture.d.ts.map

package/dist/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,KAAK,kBAAkB,GACnB;IACE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;CACnB,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;CACpB,CAAC;AAEN;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,KAAG,OAYjD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,kBAiCpD,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,GAAI,UAAU,MAAM,KAAG,MAQ5D,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,GAC/B,SAAS,aAAa,EACtB,UAAU,MAAM,EAChB,MAAM,MAAM,KACX,OAEoB,CAAC;AAExB,gEAAgE;AAChE,eAAO,MAAM,WAAW,GACtB,UAAU,aAAa,CAAC,aAAa,CAAC,EACtC,UAAU,MAAM,EAChB,MAAM,MAAM,KACX,aAAa,GAAG,SACwD,CAAC;AAE5E,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,GAAI,SAAS,aAAa,KAAG,MACtB,CAAC;AAExC,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,GAChC,SAAS,aAAa,EACtB,UAAU,YAAY,CAAC,UAAU,CAAC,KACjC,YAID,CAAC"}

package/dist/capture.js

@@ -0,0 +1,97 @@
+/**
+ * Returns true when `hostname` is an allowed loopback host for capture.
+ *
+ * Allowed values: `localhost`, `127.0.0.1`, `[::1]` / `::1`, and `*.localhost`.
+ */
+export const isLoopbackHost = (hostname) => {
+    const lower = hostname.toLowerCase();
+    if (lower === "localhost" || lower === "127.0.0.1") {
+        return true;
+    }
+    if (lower === "[::1]" || lower === "::1") {
+        return true;
+    }
+    return lower.endsWith(".localhost");
+};
+/**
+ * Parses `--capture host:port` input into a normalized capture target.
+ *
+ * The host must be loopback-only. Port must be between 1 and 65535.
+ */
+export const parseCaptureHostPort = (input) => {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, message: "Capture must be host:port, like localhost:4000." };
+    }
+    const parsed = splitHostPort(trimmed);
+    if (!parsed.ok) {
+        return parsed;
+    }
+    const { hostname, port } = parsed;
+    if (!isLoopbackHost(hostname)) {
+        return {
+            ok: false,
+            message: `Capture host "${hostname}" must be loopback (localhost, 127.0.0.1, [::1], or *.localhost).`,
+        };
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        return { ok: false, message: "Capture port must be between 1 and 65535." };
+    }
+    return {
+        ok: true,
+        capture: {
+            hostname: normalizeLoopbackHostname(hostname),
+            port,
+        },
+    };
+};
+/** Canonicalizes loopback hostnames for stable allowlist matching. */
+export const normalizeLoopbackHostname = (hostname) => {
+    const lower = hostname.toLowerCase();
+    if (lower === "::1") {
+        return "[::1]";
+    }
+    return lower;
+};
+/** Returns true when the capture matches the given target host and port. */
+export const captureMatchesTarget = (capture, hostname, port) => normalizeLoopbackHostname(hostname) === normalizeLoopbackHostname(capture.hostname) &&
+    capture.port === port;
+/** Finds an allowlisted capture for the given host and port. */
+export const findCapture = (captures, hostname, port) => captures.find((capture) => captureMatchesTarget(capture, hostname, port));
+/** Formats a capture target as `host:port` for CLI output. */
+export const formatCaptureOrigin = (capture) => `${capture.hostname}:${capture.port}`;
+/** Converts a capture target into a tunnel target using HTTP by default. */
+export const captureToTunnelTarget = (capture, protocol) => ({
+    hostname: capture.hostname,
+    port: capture.port,
+    protocol,
+});
+const splitHostPort = (input) => {
+    if (input.startsWith("[")) {
+        const closingBracket = input.indexOf("]");
+        if (closingBracket === -1 || input[closingBracket + 1] !== ":") {
+            return { ok: false, message: "Capture must be host:port, like [::1]:4000." };
+        }
+        const hostname = input.slice(0, closingBracket + 1);
+        const portText = input.slice(closingBracket + 2);
+        if (portText.length === 0) {
+            return { ok: false, message: "Capture must include a port." };
+        }
+        const port = Number(portText);
+        if (!/^\d+$/.test(portText)) {
+            return { ok: false, message: "Capture port must be a number." };
+        }
+        return { ok: true, hostname, port };
+    }
+    const separator = input.lastIndexOf(":");
+    if (separator <= 0 || separator === input.length - 1) {
+        return { ok: false, message: "Capture must be host:port, like localhost:4000." };
+    }
+    const hostname = input.slice(0, separator);
+    const portText = input.slice(separator + 1);
+    const port = Number(portText);
+    if (!/^\d+$/.test(portText)) {
+        return { ok: false, message: "Capture port must be a number." };
+    }
+    return { ok: true, hostname, port };
+};

package/dist/errors.d.ts

@@ -1,13 +1,43 @@
 import { Schema } from "effect";
-export declare const ErrorCodeSchema: Schema.Literals<readonly ["BODY_TOO_LARGE", "INVALID_SUBDOMAIN", "REQUEST_TIMEOUT", "REQUEST_FAILED", "RELAY_REGISTRATION_FAILED", "SANDBOX_CREATE_FAILED", "SUBDOMAIN_TAKEN", "TUNNEL_NOT_CONNECTED", "TUNNEL_NOT_FOUND", "UNAUTHORIZED"]>;
-export type ErrorCode = Schema.Schema.Type<typeof ErrorCodeSchema>;
-export declare const LocalPreviewErrorSchema: Schema.Struct<{
-    readonly code: Schema.Literals<readonly ["BODY_TOO_LARGE", "INVALID_SUBDOMAIN", "REQUEST_TIMEOUT", "REQUEST_FAILED", "RELAY_REGISTRATION_FAILED", "SANDBOX_CREATE_FAILED", "SUBDOMAIN_TAKEN", "TUNNEL_NOT_CONNECTED", "TUNNEL_NOT_FOUND", "UNAUTHORIZED"]>;
+/** Shared machine-readable error codes used across LocalPreview packages. */
+export declare const LOCALPREVIEW_ERROR_CODES: {
+    readonly BODY_TOO_LARGE: "BODY_TOO_LARGE";
+    readonly BULK_CLEANUP_REQUIRES_FORCE: "BULK_CLEANUP_REQUIRES_FORCE";
+    readonly CLEANUP_DISABLED: "CLEANUP_DISABLED";
+    readonly CONFIG_ERROR: "CONFIG_ERROR";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly INVALID_JSON: "INVALID_JSON";
+    readonly INVALID_SUBDOMAIN: "INVALID_SUBDOMAIN";
+    readonly RELAY_HEALTH_CHECK_FAILED: "RELAY_HEALTH_CHECK_FAILED";
+    readonly RELAY_REGISTRATION_FAILED: "RELAY_REGISTRATION_FAILED";
+    readonly REQUEST_FAILED: "REQUEST_FAILED";
+    readonly REQUEST_TIMEOUT: "REQUEST_TIMEOUT";
+    readonly SANDBOX_CREATE_FAILED: "SANDBOX_CREATE_FAILED";
+    readonly SANDBOX_STOP_FAILED: "SANDBOX_STOP_FAILED";
+    readonly STORE_FAILED: "STORE_FAILED";
+    readonly SUBDOMAIN_ACTIVE: "SUBDOMAIN_ACTIVE";
+    readonly SUBDOMAIN_TAKEN: "SUBDOMAIN_TAKEN";
+    readonly TUNNEL_HOST_NOT_FOUND: "TUNNEL_HOST_NOT_FOUND";
+    readonly TUNNEL_NOT_CONNECTED: "TUNNEL_NOT_CONNECTED";
+    readonly TUNNEL_NOT_FOUND: "TUNNEL_NOT_FOUND";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+};
+declare const LocalPreviewErrorSchema: Schema.Struct<{
+    readonly code: Schema.Literals<readonly ["BODY_TOO_LARGE", "BULK_CLEANUP_REQUIRES_FORCE", "CLEANUP_DISABLED", "CONFIG_ERROR", "INTERNAL_ERROR", "INVALID_JSON", "INVALID_SUBDOMAIN", "RELAY_HEALTH_CHECK_FAILED", "RELAY_REGISTRATION_FAILED", "REQUEST_FAILED", "REQUEST_TIMEOUT", "SANDBOX_CREATE_FAILED", "SANDBOX_STOP_FAILED", "STORE_FAILED", "SUBDOMAIN_ACTIVE", "SUBDOMAIN_TAKEN", "TUNNEL_HOST_NOT_FOUND", "TUNNEL_NOT_CONNECTED", "TUNNEL_NOT_FOUND", "UNAUTHORIZED"]>;
     readonly message: Schema.String;
     readonly requestId: Schema.optional<Schema.String>;
     readonly subdomain: Schema.optional<Schema.String>;
+    readonly tunnelId: Schema.optional<Schema.String>;
     readonly limitBytes: Schema.optional<Schema.Number>;
 }>;
+/**
+ * Shared API error shape.
+ *
+ * Callers should branch on `code` and treat `message` as human-readable context.
+ * Optional fields add request-specific identifiers or limits when available.
+ */
 export type LocalPreviewError = Schema.Schema.Type<typeof LocalPreviewErrorSchema>;
+/** Preserves literal error-code inference when constructing LocalPreview errors. */
 export declare const makeLocalPreviewError: (error: LocalPreviewError) => LocalPreviewError;
+export {};
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,eAAO,MAAM,eAAe,6OAWjB,CAAC;AAEZ,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,eAAe,CAAC,CAAC;AAEnE,eAAO,MAAM,uBAAuB;;;;;;EAMlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAEnF,eAAO,MAAM,qBAAqB,GAAI,OAAO,iBAAiB,KAAG,iBAA0B,CAAC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;CAqB3B,CAAC;AAyBX,QAAA,MAAM,uBAAuB;;;;;;;EAO3B,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAEnF,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,GAAI,OAAO,iBAAiB,KAAG,iBAA0B,CAAC"}

package/dist/errors.js

@@ -1,21 +1,56 @@
 import { Schema } from "effect";
-export const ErrorCodeSchema = Schema.Literals([
-    "BODY_TOO_LARGE",
-    "INVALID_SUBDOMAIN",
-    "REQUEST_TIMEOUT",
-    "REQUEST_FAILED",
-    "RELAY_REGISTRATION_FAILED",
-    "SANDBOX_CREATE_FAILED",
-    "SUBDOMAIN_TAKEN",
-    "TUNNEL_NOT_CONNECTED",
-    "TUNNEL_NOT_FOUND",
-    "UNAUTHORIZED",
+/** Shared machine-readable error codes used across LocalPreview packages. */
+export const LOCALPREVIEW_ERROR_CODES = {
+    BODY_TOO_LARGE: "BODY_TOO_LARGE",
+    BULK_CLEANUP_REQUIRES_FORCE: "BULK_CLEANUP_REQUIRES_FORCE",
+    CLEANUP_DISABLED: "CLEANUP_DISABLED",
+    CONFIG_ERROR: "CONFIG_ERROR",
+    INTERNAL_ERROR: "INTERNAL_ERROR",
+    INVALID_JSON: "INVALID_JSON",
+    INVALID_SUBDOMAIN: "INVALID_SUBDOMAIN",
+    RELAY_HEALTH_CHECK_FAILED: "RELAY_HEALTH_CHECK_FAILED",
+    RELAY_REGISTRATION_FAILED: "RELAY_REGISTRATION_FAILED",
+    REQUEST_FAILED: "REQUEST_FAILED",
+    REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
+    SANDBOX_CREATE_FAILED: "SANDBOX_CREATE_FAILED",
+    SANDBOX_STOP_FAILED: "SANDBOX_STOP_FAILED",
+    STORE_FAILED: "STORE_FAILED",
+    SUBDOMAIN_ACTIVE: "SUBDOMAIN_ACTIVE",
+    SUBDOMAIN_TAKEN: "SUBDOMAIN_TAKEN",
+    TUNNEL_HOST_NOT_FOUND: "TUNNEL_HOST_NOT_FOUND",
+    TUNNEL_NOT_CONNECTED: "TUNNEL_NOT_CONNECTED",
+    TUNNEL_NOT_FOUND: "TUNNEL_NOT_FOUND",
+    UNAUTHORIZED: "UNAUTHORIZED",
+};
+const ErrorCodeSchema = Schema.Literals([
+    LOCALPREVIEW_ERROR_CODES.BODY_TOO_LARGE,
+    LOCALPREVIEW_ERROR_CODES.BULK_CLEANUP_REQUIRES_FORCE,
+    LOCALPREVIEW_ERROR_CODES.CLEANUP_DISABLED,
+    LOCALPREVIEW_ERROR_CODES.CONFIG_ERROR,
+    LOCALPREVIEW_ERROR_CODES.INTERNAL_ERROR,
+    LOCALPREVIEW_ERROR_CODES.INVALID_JSON,
+    LOCALPREVIEW_ERROR_CODES.INVALID_SUBDOMAIN,
+    LOCALPREVIEW_ERROR_CODES.RELAY_HEALTH_CHECK_FAILED,
+    LOCALPREVIEW_ERROR_CODES.RELAY_REGISTRATION_FAILED,
+    LOCALPREVIEW_ERROR_CODES.REQUEST_FAILED,
+    LOCALPREVIEW_ERROR_CODES.REQUEST_TIMEOUT,
+    LOCALPREVIEW_ERROR_CODES.SANDBOX_CREATE_FAILED,
+    LOCALPREVIEW_ERROR_CODES.SANDBOX_STOP_FAILED,
+    LOCALPREVIEW_ERROR_CODES.STORE_FAILED,
+    LOCALPREVIEW_ERROR_CODES.SUBDOMAIN_ACTIVE,
+    LOCALPREVIEW_ERROR_CODES.SUBDOMAIN_TAKEN,
+    LOCALPREVIEW_ERROR_CODES.TUNNEL_HOST_NOT_FOUND,
+    LOCALPREVIEW_ERROR_CODES.TUNNEL_NOT_CONNECTED,
+    LOCALPREVIEW_ERROR_CODES.TUNNEL_NOT_FOUND,
+    LOCALPREVIEW_ERROR_CODES.UNAUTHORIZED,
 ]);
-export const LocalPreviewErrorSchema = Schema.Struct({
+const LocalPreviewErrorSchema = Schema.Struct({
     code: ErrorCodeSchema,
     message: Schema.String,
     requestId: Schema.optional(Schema.String),
     subdomain: Schema.optional(Schema.String),
+    tunnelId: Schema.optional(Schema.String),
     limitBytes: Schema.optional(Schema.Number),
 });
+/** Preserves literal error-code inference when constructing LocalPreview errors. */
 export const makeLocalPreviewError = (error) => error;

package/dist/headers.d.ts

@@ -1,19 +1,28 @@
+/** Header used to authenticate administrative control-plane operations. */
 export declare const LOCALPREVIEW_ADMIN_TOKEN_HEADER = "x-localpreview-admin-token";
+/** Header used by trusted proxies to preserve the original public host. */
 export declare const LOCALPREVIEW_FORWARDED_HOST_HEADER = "x-localpreview-forwarded-host";
+/** Header used by trusted proxies to preserve the original public protocol. */
 export declare const LOCALPREVIEW_FORWARDED_PROTO_HEADER = "x-localpreview-forwarded-proto";
+/** Header used to authenticate relay-to-control-plane proxy requests. */
 export declare const LOCALPREVIEW_PROXY_TOKEN_HEADER = "x-localpreview-proxy-token";
-export type HeaderMap = Readonly<Record<string, string>>;
+/**
+ * Ordered HTTP header pair.
+ *
+ * Headers are represented as pairs instead of object maps so duplicate headers,
+ * especially `set-cookie`, survive relay and proxy boundaries.
+ */
 export type HeaderPair = readonly [name: string, value: string];
+/** Ordered HTTP header list that may contain duplicate header names. */
 export type HeaderPairs = ReadonlyArray<HeaderPair>;
+/** Returns true when a header must not be forwarded across proxy hops. */
 export declare const isHopByHopHeader: (name: string) => boolean;
+/** Returns true when a header is internal LocalPreview control metadata. */
 export declare const isInternalLocalPreviewHeader: (name: string) => boolean;
-export declare const filterEndToEndHeaders: (headers: HeaderMap) => HeaderMap;
-export declare const filterInternalLocalPreviewHeaders: (headers: HeaderMap) => HeaderMap;
+/** Removes hop-by-hop headers while preserving original header order. */
 export declare const filterEndToEndHeaderPairs: (headers: HeaderPairs) => HeaderPairs;
+/** Removes LocalPreview internal headers before forwarding to untrusted targets. */
 export declare const filterInternalLocalPreviewHeaderPairs: (headers: HeaderPairs) => HeaderPairs;
-export declare const headerPairsToMap: (headers: HeaderPairs) => HeaderMap;
-export declare const headerMapToPairs: (headers: HeaderMap) => HeaderPairs;
+/** Converts header pairs to alternating name/value entries for HTTP adapters. */
 export declare const flattenHeaderPairs: (headers: HeaderPairs) => Array<string>;
-export declare const headersToMap: (headers: Headers) => HeaderMap;
-export declare const recordToHeaders: (headers: HeaderMap) => Headers;
 //# sourceMappingURL=headers.d.ts.map

package/dist/headers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAC5E,eAAO,MAAM,kCAAkC,kCAAkC,CAAC;AAClF,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AACpF,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAS5E,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AACzD,MAAM,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,OAAkD,CAAC;AAEnG,eAAO,MAAM,4BAA4B,GAAI,MAAM,MAAM,KAAG,OACP,CAAC;AAEtD,eAAO,MAAM,qBAAqB,GAAI,SAAS,SAAS,KAAG,SAC8B,CAAC;AAE1F,eAAO,MAAM,iCAAiC,GAAI,SAAS,SAAS,KAAG,SAGpE,CAAC;AAEJ,eAAO,MAAM,yBAAyB,GAAI,SAAS,WAAW,KAAG,WACZ,CAAC;AAEtD,eAAO,MAAM,qCAAqC,GAAI,SAAS,WAAW,KAAG,WACZ,CAAC;AAElE,eAAO,MAAM,gBAAgB,GAAI,SAAS,WAAW,KAAG,SAAwC,CAAC;AAEjG,eAAO,MAAM,gBAAgB,GAAI,SAAS,SAAS,KAAG,WAAsC,CAAC;AAE7F,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,KAAG,KAAK,CAAC,MAAM,CACnB,CAAC;AAEpD,eAAO,MAAM,YAAY,GAAI,SAAS,OAAO,KAAG,SAAkD,CAAC;AAEnG,eAAO,MAAM,eAAe,GAAI,SAAS,SAAS,KAAG,OAQpD,CAAC"}
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAWA,2EAA2E;AAC3E,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAE5E,2EAA2E;AAC3E,eAAO,MAAM,kCAAkC,kCAAkC,CAAC;AAElF,+EAA+E;AAC/E,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AAEpF,yEAAyE;AACzE,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAS5E;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAEhE,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;AAEpD,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,OAAkD,CAAC;AAEnG,4EAA4E;AAC5E,eAAO,MAAM,4BAA4B,GAAI,MAAM,MAAM,KAAG,OACP,CAAC;AAEtD,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,GAAI,SAAS,WAAW,KAAG,WACZ,CAAC;AAEtD,oFAAoF;AACpF,eAAO,MAAM,qCAAqC,GAAI,SAAS,WAAW,KAAG,WACZ,CAAC;AAElE,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,KAAG,KAAK,CAAC,MAAM,CACnB,CAAC"}

package/dist/headers.js

@@ -8,9 +8,13 @@ const hopByHopHeaders = new Set([
     "transfer-encoding",
     "upgrade",
 ]);
+/** Header used to authenticate administrative control-plane operations. */
 export const LOCALPREVIEW_ADMIN_TOKEN_HEADER = "x-localpreview-admin-token";
+/** Header used by trusted proxies to preserve the original public host. */
 export const LOCALPREVIEW_FORWARDED_HOST_HEADER = "x-localpreview-forwarded-host";
+/** Header used by trusted proxies to preserve the original public protocol. */
 export const LOCALPREVIEW_FORWARDED_PROTO_HEADER = "x-localpreview-forwarded-proto";
+/** Header used to authenticate relay-to-control-plane proxy requests. */
 export const LOCALPREVIEW_PROXY_TOKEN_HEADER = "x-localpreview-proxy-token";
 const internalLocalPreviewHeaders = new Set([
     LOCALPREVIEW_ADMIN_TOKEN_HEADER,
@@ -18,20 +22,13 @@ const internalLocalPreviewHeaders = new Set([
     LOCALPREVIEW_FORWARDED_PROTO_HEADER,
     LOCALPREVIEW_PROXY_TOKEN_HEADER,
 ]);
+/** Returns true when a header must not be forwarded across proxy hops. */
 export const isHopByHopHeader = (name) => hopByHopHeaders.has(name.toLowerCase());
+/** Returns true when a header is internal LocalPreview control metadata. */
 export const isInternalLocalPreviewHeader = (name) => internalLocalPreviewHeaders.has(name.toLowerCase());
-export const filterEndToEndHeaders = (headers) => Object.fromEntries(Object.entries(headers).filter(([name]) => !isHopByHopHeader(name)));
-export const filterInternalLocalPreviewHeaders = (headers) => Object.fromEntries(Object.entries(headers).filter(([name]) => !isInternalLocalPreviewHeader(name)));
+/** Removes hop-by-hop headers while preserving original header order. */
 export const filterEndToEndHeaderPairs = (headers) => headers.filter(([name]) => !isHopByHopHeader(name));
+/** Removes LocalPreview internal headers before forwarding to untrusted targets. */
 export const filterInternalLocalPreviewHeaderPairs = (headers) => headers.filter(([name]) => !isInternalLocalPreviewHeader(name));
-export const headerPairsToMap = (headers) => Object.fromEntries(headers);
-export const headerMapToPairs = (headers) => Object.entries(headers);
+/** Converts header pairs to alternating name/value entries for HTTP adapters. */
 export const flattenHeaderPairs = (headers) => headers.flatMap(([name, value]) => [name, value]);
-export const headersToMap = (headers) => Object.fromEntries(headers.entries());
-export const recordToHeaders = (headers) => {
-    const result = new Headers();
-    for (const [name, value] of Object.entries(headers)) {
-        result.set(name, value);
-    }
-    return result;
-};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./capture.js";
 export * from "./errors.js";
 export * from "./headers.js";
 export * from "./messages.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from "./capture.js";
 export * from "./errors.js";
 export * from "./headers.js";
 export * from "./messages.js";

package/dist/messages.d.ts

@@ -1,114 +1,14 @@
 import { Schema } from "effect";
 import type { HeaderPairs } from "./headers.js";
-export declare const RequestIdSchema: Schema.String;
-export type RequestId = Schema.Schema.Type<typeof RequestIdSchema>;
-export declare const RequestStartMessageSchema: Schema.Struct<{
-    readonly headers: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-    readonly method: Schema.String;
-    readonly path: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"request-start">;
-}>;
-export declare const RequestChunkMessageSchema: Schema.Struct<{
-    readonly chunkBase64: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"request-chunk">;
-}>;
-export declare const RequestEndMessageSchema: Schema.Struct<{
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"request-end">;
-}>;
-export declare const CancelMessageSchema: Schema.Struct<{
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"cancel">;
-}>;
-export declare const ResponseStartMessageSchema: Schema.Struct<{
-    readonly headers: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-    readonly requestId: Schema.String;
-    readonly status: Schema.Number;
-    readonly type: Schema.Literal<"response-start">;
-}>;
-export declare const ResponseChunkMessageSchema: Schema.Struct<{
-    readonly chunkBase64: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"response-chunk">;
-}>;
-export declare const ResponseEndMessageSchema: Schema.Struct<{
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"response-end">;
-}>;
-export declare const ResponseErrorMessageSchema: Schema.Struct<{
-    readonly message: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"response-error">;
-}>;
-export declare const ServerMessageSchema: Schema.Union<readonly [Schema.Struct<{
-    readonly headers: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-    readonly method: Schema.String;
-    readonly path: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"request-start">;
-}>, Schema.Struct<{
-    readonly chunkBase64: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"request-chunk">;
-}>, Schema.Struct<{
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"request-end">;
-}>, Schema.Struct<{
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"cancel">;
-}>]>;
-export declare const ClientMessageSchema: Schema.Union<readonly [Schema.Struct<{
-    readonly headers: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-    readonly requestId: Schema.String;
-    readonly status: Schema.Number;
-    readonly type: Schema.Literal<"response-start">;
-}>, Schema.Struct<{
-    readonly chunkBase64: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"response-chunk">;
-}>, Schema.Struct<{
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"response-end">;
-}>, Schema.Struct<{
-    readonly message: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"response-error">;
-}>]>;
-export declare const RelayMessageSchema: Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
-    readonly headers: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-    readonly method: Schema.String;
-    readonly path: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"request-start">;
-}>, Schema.Struct<{
-    readonly chunkBase64: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"request-chunk">;
-}>, Schema.Struct<{
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"request-end">;
-}>, Schema.Struct<{
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"cancel">;
-}>]>, Schema.Union<readonly [Schema.Struct<{
-    readonly headers: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-    readonly requestId: Schema.String;
-    readonly status: Schema.Number;
-    readonly type: Schema.Literal<"response-start">;
-}>, Schema.Struct<{
-    readonly chunkBase64: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"response-chunk">;
-}>, Schema.Struct<{
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"response-end">;
-}>, Schema.Struct<{
-    readonly message: Schema.String;
-    readonly requestId: Schema.String;
-    readonly type: Schema.Literal<"response-error">;
-}>]>]>;
+declare const RequestIdSchema: Schema.String;
+type RequestId = Schema.Schema.Type<typeof RequestIdSchema>;
+/**
+ * Relay messages sent by the relay server to the CLI client.
+ *
+ * These messages describe the inbound browser request that the CLI must forward
+ * to the local target. Body chunks are base64 strings so the wire format can
+ * stay JSON while preserving arbitrary bytes.
+ */
 export type ServerMessage = {
     readonly type: "request-start";
     readonly requestId: RequestId;
@@ -126,7 +26,13 @@ export type ServerMessage = {
     readonly type: "cancel";
     readonly requestId: RequestId;
 };
-export type ClientMessage = {
+/**
+ * Relay messages sent by the CLI client back to the relay server.
+ *
+ * These messages describe the local target response, stream response bytes, or
+ * report a request-scoped forwarding failure.
+ */
+type ClientMessage = {
     readonly type: "response-start";
     readonly requestId: RequestId;
     readonly status: number;
@@ -143,17 +49,30 @@ export type ClientMessage = {
     readonly requestId: RequestId;
     readonly message: string;
 };
-export type RelayMessage = ServerMessage | ClientMessage;
+type RelayMessage = ServerMessage | ClientMessage;
+/** Encodes a relay message as the JSON string sent over the WebSocket. */
 export declare const encodeRelayMessage: (message: RelayMessage) => string;
-export declare const decodeRelayMessage: (input: string) => RelayMessage;
-export type RelayMessageDecodeResult<A> = {
+type RelayMessageDecodeResult<A> = {
     readonly ok: true;
     readonly message: A;
 } | {
     readonly error: unknown;
     readonly ok: false;
 };
+/**
+ * Decodes a relay-to-CLI WebSocket message.
+ *
+ * Returns a result object instead of throwing for invalid JSON or invalid
+ * message shapes, which lets callers close or ignore malformed connections
+ * using their own error policy.
+ */
 export declare const decodeServerRelayMessage: (input: string) => RelayMessageDecodeResult<ServerMessage>;
+/**
+ * Decodes a CLI-to-relay WebSocket message.
+ *
+ * Response headers must be ordered pairs, not collapsed maps, so duplicate
+ * response headers remain representable.
+ */
 export declare const decodeClientRelayMessage: (input: string) => RelayMessageDecodeResult<ClientMessage>;
-export declare const decodeTypedRelayMessage: (input: string) => RelayMessageDecodeResult<RelayMessage>;
+export {};
 //# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,eAAO,MAAM,eAAe,eAAgB,CAAC;AAC7C,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,eAAe,CAAC,CAAC;AAInE,eAAO,MAAM,yBAAyB;;;;;;EAMpC,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;EAIpC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;EAGlC,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;EAG9B,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;EAKrC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;EAIrC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;EAGnC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;EAIrC,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;IAKrB,CAAC;AAEZ,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;IAKrB,CAAC;AAEZ,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAAoE,CAAC;AAEpG,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B,CAAC;AAEN,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,aAAa,CAAC;AAEzD,eAAO,MAAM,kBAAkB,GAAI,SAAS,YAAY,KAAG,MAAiC,CAAC;AAE7F,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,YAChB,CAAC;AAEpC,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAClC;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;CACrB,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;CACpB,CAAC;AAEN,eAAO,MAAM,wBAAwB,GAAI,OAAO,MAAM,KAAG,wBAAwB,CAAC,aAAa,CACjD,CAAC;AAE/C,eAAO,MAAM,wBAAwB,GAAI,OAAO,MAAM,KAAG,wBAAwB,CAAC,aAAa,CACjD,CAAC;AAE/C,eAAO,MAAM,uBAAuB,GAAI,OAAO,MAAM,KAAG,wBAAwB,CAAC,YAAY,CAChD,CAAC"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,QAAA,MAAM,eAAe,eAAgB,CAAC;AACtC,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,eAAe,CAAC,CAAC;AAkE5D;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B,CAAC;AAEN;;;;;GAKG;AACH,KAAK,aAAa,GACd;IACE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,KAAK,YAAY,GAAG,aAAa,GAAG,aAAa,CAAC;AAElD,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,GAAI,SAAS,YAAY,KAAG,MAAiC,CAAC;AAE7F,KAAK,wBAAwB,CAAC,CAAC,IAC3B;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;CACrB,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;CACpB,CAAC;AAEN;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,MAAM,KAAG,wBAAwB,CAAC,aAAa,CACjD,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,MAAM,KAAG,wBAAwB,CAAC,aAAa,CACjD,CAAC"}

package/dist/messages.js

@@ -1,64 +1,75 @@
 import { Result, Schema } from "effect";
-export const RequestIdSchema = Schema.String;
+const RequestIdSchema = Schema.String;
 const HeaderPairsSchema = Schema.Array(Schema.Tuple([Schema.String, Schema.String]));
-export const RequestStartMessageSchema = Schema.Struct({
+const RequestStartMessageSchema = Schema.Struct({
     headers: HeaderPairsSchema,
     method: Schema.String,
     path: Schema.String,
     requestId: RequestIdSchema,
     type: Schema.Literal("request-start"),
 });
-export const RequestChunkMessageSchema = Schema.Struct({
+const RequestChunkMessageSchema = Schema.Struct({
     chunkBase64: Schema.String,
     requestId: RequestIdSchema,
     type: Schema.Literal("request-chunk"),
 });
-export const RequestEndMessageSchema = Schema.Struct({
+const RequestEndMessageSchema = Schema.Struct({
     requestId: RequestIdSchema,
     type: Schema.Literal("request-end"),
 });
-export const CancelMessageSchema = Schema.Struct({
+const CancelMessageSchema = Schema.Struct({
     requestId: RequestIdSchema,
     type: Schema.Literal("cancel"),
 });
-export const ResponseStartMessageSchema = Schema.Struct({
+const ResponseStartMessageSchema = Schema.Struct({
     headers: HeaderPairsSchema,
     requestId: RequestIdSchema,
     status: Schema.Number,
     type: Schema.Literal("response-start"),
 });
-export const ResponseChunkMessageSchema = Schema.Struct({
+const ResponseChunkMessageSchema = Schema.Struct({
     chunkBase64: Schema.String,
     requestId: RequestIdSchema,
     type: Schema.Literal("response-chunk"),
 });
-export const ResponseEndMessageSchema = Schema.Struct({
+const ResponseEndMessageSchema = Schema.Struct({
     requestId: RequestIdSchema,
     type: Schema.Literal("response-end"),
 });
-export const ResponseErrorMessageSchema = Schema.Struct({
+const ResponseErrorMessageSchema = Schema.Struct({
     message: Schema.String,
     requestId: RequestIdSchema,
     type: Schema.Literal("response-error"),
 });
-export const ServerMessageSchema = Schema.Union([
+const ServerMessageSchema = Schema.Union([
     RequestStartMessageSchema,
     RequestChunkMessageSchema,
     RequestEndMessageSchema,
     CancelMessageSchema,
 ]);
-export const ClientMessageSchema = Schema.Union([
+const ClientMessageSchema = Schema.Union([
     ResponseStartMessageSchema,
     ResponseChunkMessageSchema,
     ResponseEndMessageSchema,
     ResponseErrorMessageSchema,
 ]);
-export const RelayMessageSchema = Schema.Union([ServerMessageSchema, ClientMessageSchema]);
+/** Encodes a relay message as the JSON string sent over the WebSocket. */
 export const encodeRelayMessage = (message) => JSON.stringify(message);
-export const decodeRelayMessage = (input) => JSON.parse(input);
+/**
+ * Decodes a relay-to-CLI WebSocket message.
+ *
+ * Returns a result object instead of throwing for invalid JSON or invalid
+ * message shapes, which lets callers close or ignore malformed connections
+ * using their own error policy.
+ */
 export const decodeServerRelayMessage = (input) => decodeWithSchema(input, ServerMessageSchema);
+/**
+ * Decodes a CLI-to-relay WebSocket message.
+ *
+ * Response headers must be ordered pairs, not collapsed maps, so duplicate
+ * response headers remain representable.
+ */
 export const decodeClientRelayMessage = (input) => decodeWithSchema(input, ClientMessageSchema);
-export const decodeTypedRelayMessage = (input) => decodeWithSchema(input, RelayMessageSchema);
 const decodeWithSchema = (input, schema) => {
     try {
         const result = Schema.decodeUnknownResult(schema)(JSON.parse(input));

package/dist/public-domain.d.ts

@@ -1,3 +1,5 @@
+/** Canonical public domain used for production LocalPreview URLs. */
 export declare const LOCALPREVIEW_PUBLIC_DOMAIN = "localpreview.dev";
+/** HTTPS origin for the production LocalPreview control-plane. */
 export declare const LOCALPREVIEW_PUBLIC_ORIGIN = "https://localpreview.dev";
 //# sourceMappingURL=public-domain.d.ts.map

package/dist/public-domain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public-domain.d.ts","sourceRoot":"","sources":["../src/public-domain.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAC7D,eAAO,MAAM,0BAA0B,6BAA0C,CAAC"}
+{"version":3,"file":"public-domain.d.ts","sourceRoot":"","sources":["../src/public-domain.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAE7D,kEAAkE;AAClE,eAAO,MAAM,0BAA0B,6BAA0C,CAAC"}

package/dist/public-domain.js

@@ -1,2 +1,4 @@
+/** Canonical public domain used for production LocalPreview URLs. */
 export const LOCALPREVIEW_PUBLIC_DOMAIN = "localpreview.dev";
+/** HTTPS origin for the production LocalPreview control-plane. */
 export const LOCALPREVIEW_PUBLIC_ORIGIN = `https://${LOCALPREVIEW_PUBLIC_DOMAIN}`;

package/dist/subdomain.d.ts

@@ -1,9 +1,17 @@
-export type SubdomainValidationResult = {
+type SubdomainValidationResult = {
     readonly valid: true;
     readonly subdomain: string;
 } | {
     readonly valid: false;
     readonly reason: "invalid-format" | "reserved";
 };
+/**
+ * Normalizes and validates a user-requested public subdomain.
+ *
+ * The returned `subdomain` is trimmed and lowercased. Reserved product routes
+ * and names outside the public subdomain format are rejected with separate
+ * reasons so callers can produce specific user-facing errors.
+ */
 export declare const validateRequestedSubdomain: (input: string) => SubdomainValidationResult;
+export {};
 //# sourceMappingURL=subdomain.d.ts.map

package/dist/subdomain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subdomain.d.ts","sourceRoot":"","sources":["../src/subdomain.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,yBAAyB,GACjC;IACE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CAAC;CAChD,CAAC;AAEN,eAAO,MAAM,0BAA0B,GAAI,OAAO,MAAM,KAAG,yBAY1D,CAAC"}
+{"version":3,"file":"subdomain.d.ts","sourceRoot":"","sources":["../src/subdomain.ts"],"names":[],"mappings":"AAaA,KAAK,yBAAyB,GAC1B;IACE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CAAC;CAChD,CAAC;AAEN;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,OAAO,MAAM,KAAG,yBAY1D,CAAC"}

package/dist/subdomain.js

@@ -10,6 +10,13 @@ const reservedSubdomains = new Set([
     "status",
     "www",
 ]);
+/**
+ * Normalizes and validates a user-requested public subdomain.
+ *
+ * The returned `subdomain` is trimmed and lowercased. Reserved product routes
+ * and names outside the public subdomain format are rejected with separate
+ * reasons so callers can produce specific user-facing errors.
+ */
 export const validateRequestedSubdomain = (input) => {
     const subdomain = input.trim().toLowerCase();
     if (reservedSubdomains.has(subdomain)) {

package/dist/target.d.ts

@@ -1,14 +1,23 @@
+/** Local HTTP(S) endpoint that the CLI forwards tunnel traffic to. */
 export type TunnelTarget = {
     readonly protocol: "http" | "https";
     readonly hostname: string;
     readonly port: number;
 };
-export type ParseTargetResult = {
+type ParseTargetResult = {
     readonly ok: true;
     readonly target: TunnelTarget;
 } | {
     readonly ok: false;
     readonly message: string;
 };
+/**
+ * Parses CLI target input into a normalized tunnel target.
+ *
+ * A bare port is treated as `http://127.0.0.1:<port>`. URL-like inputs default
+ * to `http` when no protocol is provided, but must include an explicit port and
+ * use either `http` or `https`.
+ */
 export declare const parseTarget: (input: string) => ParseTargetResult;
+export {};
 //# sourceMappingURL=target.d.ts.map

package/dist/target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../src/target.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,iBA4B3C,CAAC"}
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../src/target.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,KAAK,iBAAiB,GAClB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,iBA4B3C,CAAC"}

package/dist/target.js

@@ -1,3 +1,10 @@
+/**
+ * Parses CLI target input into a normalized tunnel target.
+ *
+ * A bare port is treated as `http://127.0.0.1:<port>`. URL-like inputs default
+ * to `http` when no protocol is provided, but must include an explicit port and
+ * use either `http` or `https`.
+ */
 export const parseTarget = (input) => {
     const trimmed = input.trim();
     if (/^\d+$/.test(trimmed)) {

package/dist/tunnel.d.ts

@@ -1,21 +1,4 @@
-import { Schema } from "effect";
-export declare const TunnelStatusSchema: Schema.Literals<readonly ["starting", "connected", "disconnected", "expired"]>;
-export type TunnelStatus = Schema.Schema.Type<typeof TunnelStatusSchema>;
-export type TunnelRecord = {
-    readonly tunnelId: string;
-    readonly subdomain: string;
-    readonly relayHttpUrl: string;
-    readonly relayWsUrl: string;
-    readonly proxyToken: string;
-    readonly relayProvider?: "local" | "vercel";
-    readonly status: TunnelStatus;
-    readonly sandboxId?: string;
-    readonly createdAt: string;
-    readonly expiresAt: string;
-};
-export type CreateTunnelRequest = {
-    readonly requestedSubdomain?: string;
-};
+/** Response returned by the control-plane after creating a tunnel session. */
 export type CreateTunnelResponse = {
     readonly tunnelId: string;
     readonly subdomain: string;
@@ -26,6 +9,7 @@ export type CreateTunnelResponse = {
     readonly protocolVersion: string;
     readonly relaySnapshotVersion: string;
 };
+/** Admin request used by the control-plane to register a tunnel with a relay. */
 export type RegisterRelayTunnelRequest = {
     readonly tunnelId: string;
     readonly clientToken: string;

package/dist/tunnel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../src/tunnel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,eAAO,MAAM,kBAAkB,gFAKpB,CAAC;AAEZ,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEzE,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC"}
+{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../src/tunnel.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC"}

package/dist/tunnel.js

@@ -1,7 +1 @@
-import { Schema } from "effect";
-export const TunnelStatusSchema = Schema.Literals([
-    "starting",
-    "connected",
-    "disconnected",
-    "expired",
-]);
+export {};

package/dist/version.d.ts

@@ -1,20 +1,35 @@
 import { Schema } from "effect";
+/**
+ * Wire and HTTP contract version expected by CLI, control-plane, and relay.
+ *
+ * Change this when a deployed component would no longer understand the same
+ * public request, response, or relay message shapes.
+ */
 export declare const LOCALPREVIEW_PROTOCOL_VERSION = "1";
+/**
+ * Production relay snapshot contract version.
+ *
+ * Change this when the relay snapshot must be rebuilt or promoted even if the
+ * shared protocol remains compatible.
+ */
 export declare const LOCALPREVIEW_RELAY_SNAPSHOT_VERSION = "2026-05-25.1";
-export declare const RelayHealthResponseSchema: Schema.Struct<{
+declare const RelayHealthResponseSchema: Schema.Struct<{
     readonly ok: Schema.Literal<true>;
     readonly protocolVersion: Schema.String;
     readonly relaySnapshotVersion: Schema.String;
     readonly service: Schema.String;
     readonly tunnels: Schema.Number;
 }>;
+/** Health response emitted by relay instances and checked by snapshot tooling. */
 export type RelayHealthResponse = Schema.Schema.Type<typeof RelayHealthResponseSchema>;
-export type RelayHealthDecodeResult = {
+type RelayHealthDecodeResult = {
     readonly health: RelayHealthResponse;
     readonly ok: true;
 } | {
     readonly error: unknown;
     readonly ok: false;
 };
+/** Validates an unknown relay `/health` response without throwing. */
 export declare const decodeRelayHealthResponse: (input: unknown) => RelayHealthDecodeResult;
+export {};
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,eAAO,MAAM,mCAAmC,iBAAiB,CAAC;AAElE,eAAO,MAAM,yBAAyB;;;;;;EAMpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEvF,MAAM,MAAM,uBAAuB,GAC/B;IACE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;CACnB,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;CACpB,CAAC;AAEN,eAAO,MAAM,yBAAyB,GAAI,OAAO,OAAO,KAAG,uBAQ1D,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,iBAAiB,CAAC;AAElE,QAAA,MAAM,yBAAyB;;;;;;EAM7B,CAAC;AAEH,kFAAkF;AAClF,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEvF,KAAK,uBAAuB,GACxB;IACE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;CACnB,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;CACpB,CAAC;AAEN,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,GAAI,OAAO,OAAO,KAAG,uBAQ1D,CAAC"}

package/dist/version.js

@@ -1,13 +1,26 @@
 import { Result, Schema } from "effect";
+/**
+ * Wire and HTTP contract version expected by CLI, control-plane, and relay.
+ *
+ * Change this when a deployed component would no longer understand the same
+ * public request, response, or relay message shapes.
+ */
 export const LOCALPREVIEW_PROTOCOL_VERSION = "1";
+/**
+ * Production relay snapshot contract version.
+ *
+ * Change this when the relay snapshot must be rebuilt or promoted even if the
+ * shared protocol remains compatible.
+ */
 export const LOCALPREVIEW_RELAY_SNAPSHOT_VERSION = "2026-05-25.1";
-export const RelayHealthResponseSchema = Schema.Struct({
+const RelayHealthResponseSchema = Schema.Struct({
     ok: Schema.Literal(true),
     protocolVersion: Schema.String,
     relaySnapshotVersion: Schema.String,
     service: Schema.String,
     tunnels: Schema.Number,
 });
+/** Validates an unknown relay `/health` response without throwing. */
 export const decodeRelayHealthResponse = (input) => {
     const result = Schema.decodeUnknownResult(RelayHealthResponseSchema)(input);
     if (Result.isSuccess(result)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localpreview/protocol",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "files": [
     "dist",
@@ -16,18 +16,20 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "effect": "beta"
-  },
-  "devDependencies": {
-    "typescript": "latest",
-    "vitest": "latest"
-  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch",
     "lint": "oxlint .",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm test && pnpm typecheck && pnpm build",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "effect": "catalog:"
+  },
+  "devDependencies": {
+    "typescript": "catalog:",
+    "vitest": "catalog:"
   }
-}
+}