@01.works/visual-review 0.1.0

package/dist/vite.d.ts

@@ -0,0 +1,29 @@
+import type { Plugin } from 'vite';
+
+export interface VisualReviewBuildIdentityOptions {
+  /** Browser-visible deployment-unique build identifier. Never reuse it for different output. */
+  buildId?: string;
+  /** Browser-visible full Git SHA. `null` explicitly disables automatic discovery. */
+  gitCommit?: string | null;
+}
+
+export interface VisualReviewViteSourceMapOptions {
+  /** Enables upload explicitly. A source-map upload token is still required. */
+  enabled?: boolean;
+  /** Node-only build secret. Prefer VISUAL_REVIEW_SOURCE_MAP_TOKEN in CI. */
+  token?: string;
+  /** Hosted service origin. Primarily useful for local/self-hosted build services. */
+  serviceUrl?: string;
+}
+
+export interface VisualReviewViteOptions extends VisualReviewBuildIdentityOptions {
+  /** Uploads private hidden source maps and removes them from the deployment output. */
+  sourceMaps?: boolean | VisualReviewViteSourceMapOptions;
+  /** Adds opaque production JSX markers by default. Set `false` for identity-only output. */
+  sourceMetadata?: boolean;
+}
+
+/** Injects public build provenance and optionally uploads private hidden source maps. */
+export declare function visualReview(
+  options?: VisualReviewViteOptions,
+): Plugin;

package/dist/vite.js

@@ -0,0 +1,141 @@
+import { t as resolveVisualReviewBuildIdentity } from "./build-identity-CgoY3-jy.js";
+import { a as visualReviewSourceIndexFilename, f as cleanupViteSourceMapOutput, l as writeViteVisualReviewSourceIndex, p as uploadViteSourceMaps, s as viteSourceIndexUrl } from "./source-index-BdWeiNHZ.js";
+import { t as instrumentVisualReviewSource } from "./source-instrumentation-transform-BwKYKlp0.js";
+import { randomBytes } from "node:crypto";
+import { resolve } from "node:path";
+//#region src/vite.ts
+const BUILD_ID_LITERAL = "process.env.VISUAL_REVIEW_PUBLIC_BUILD_ID";
+const GIT_COMMIT_LITERAL = "process.env.VISUAL_REVIEW_PUBLIC_GIT_COMMIT";
+const BUILD_MODE_LITERAL = "process.env.VISUAL_REVIEW_PUBLIC_BUILD_MODE";
+/** Injects public build provenance and optionally uploads private hidden source maps. */
+function visualReview(options = {}) {
+	let identity;
+	let resolvedConfig;
+	let sourceMapUpload;
+	let sourceMetadataEnabled = false;
+	let sourceIndexFilename;
+	let sourceIndexUrl;
+	let sourceMarkerSalt;
+	let releaseMode;
+	return {
+		name: "01works:visual-review-build-identity",
+		enforce: "pre",
+		config(config, environment) {
+			identity = resolveVisualReviewBuildIdentity(options, {
+				cwd: resolve(process.cwd(), config.root ?? "."),
+				env: process.env
+			});
+			releaseMode = typeof environment?.mode === "string" && environment.mode.length > 0 ? normalizeReleaseMode(environment.mode) : void 0;
+			const define = publicLiteralDefinitions(identity, releaseMode);
+			assertReservedLiterals(config.define, define, "Vite define");
+			if (environment?.command === "serve") {
+				sourceMapUpload = void 0;
+				sourceMetadataEnabled = false;
+				sourceMarkerSalt = void 0;
+				return { define };
+			}
+			sourceMapUpload = resolveSourceMapUpload(options.sourceMaps, process.env);
+			sourceMetadataEnabled = options.sourceMetadata ?? true;
+			sourceMarkerSalt = sourceMetadataEnabled ? randomBytes(32).toString("hex") : void 0;
+			if (!sourceMapUpload) return { define };
+			if (config.build?.sourcemap === "inline") throw new Error("Visual Review source-map upload refuses inline Vite source maps");
+			return {
+				define,
+				build: { sourcemap: "hidden" }
+			};
+		},
+		configResolved(config) {
+			resolvedConfig = config;
+			if (releaseMode !== void 0 && normalizeReleaseMode(config.mode) !== releaseMode) throw new Error("Visual Review build mode changed after the public literals were injected");
+			if (sourceMetadataEnabled) {
+				if (!identity || !sourceMarkerSalt) throw new Error("Visual Review source metadata identity is unavailable");
+				sourceIndexFilename = visualReviewSourceIndexFilename(identity.buildId, sourceMarkerSalt);
+				sourceIndexUrl = viteSourceIndexUrl(config.base, sourceIndexFilename);
+			}
+			if (!sourceMapUpload) return;
+			if (config.build.sourcemap !== "hidden") throw new Error("Visual Review source-map upload requires build.sourcemap=\"hidden\"");
+			if (config.build.ssr) throw new Error("Visual Review Vite source-map upload currently supports browser builds only");
+		},
+		transform(source, id) {
+			if (!sourceMetadataEnabled) return null;
+			if (!resolvedConfig || !sourceIndexUrl || !sourceMarkerSalt) throw new Error("Visual Review source metadata was not initialized by Vite");
+			const transformed = instrumentVisualReviewSource(source, {
+				id,
+				indexUrl: sourceIndexUrl,
+				markerSalt: sourceMarkerSalt,
+				projectRoot: resolvedConfig.root
+			});
+			return transformed ? {
+				code: transformed.code,
+				map: transformed.map
+			} : null;
+		},
+		async closeBundle() {
+			if (!identity || !resolvedConfig) throw new Error("Visual Review build adapter was not initialized by Vite");
+			const outDir = resolve(resolvedConfig.root, resolvedConfig.build.outDir);
+			if (sourceMetadataEnabled) {
+				if (!sourceIndexFilename) throw new Error("Visual Review source metadata was not initialized by Vite");
+				try {
+					await writeViteVisualReviewSourceIndex({
+						projectRoot: resolvedConfig.root,
+						outDir,
+						base: resolvedConfig.base,
+						filename: sourceIndexFilename
+					});
+				} catch (sourceIndexError) {
+					if (!sourceMapUpload) throw sourceIndexError;
+					try {
+						await cleanupViteSourceMapOutput(resolvedConfig.root, outDir);
+					} catch (cleanupError) {
+						throw new AggregateError([sourceIndexError, cleanupError], "Visual Review source index failed and Vite source maps could not be cleaned");
+					}
+					throw sourceIndexError;
+				}
+			}
+			if (!sourceMapUpload) return;
+			await uploadViteSourceMaps({
+				projectRoot: resolvedConfig.root,
+				outDir,
+				base: resolvedConfig.base,
+				token: sourceMapUpload.token,
+				...sourceMapUpload.serviceUrl ? { serviceUrl: sourceMapUpload.serviceUrl } : {},
+				buildId: identity.buildId,
+				gitCommit: identity.gitCommit,
+				mode: normalizeReleaseMode(resolvedConfig.mode)
+			});
+		}
+	};
+}
+function resolveSourceMapUpload(option, env) {
+	if (option === false || typeof option === "object" && option.enabled === false) return;
+	const configured = typeof option === "object" ? option : void 0;
+	const token = configured?.token ?? env.VISUAL_REVIEW_SOURCE_MAP_TOKEN;
+	if (!(option === true || configured !== void 0 || token !== void 0)) return void 0;
+	if (typeof token !== "string" || token.length === 0 || /\s/.test(token)) throw new Error("Visual Review source-map upload requires VISUAL_REVIEW_SOURCE_MAP_TOKEN in the Node build environment");
+	return {
+		token,
+		...configured?.serviceUrl ? { serviceUrl: configured.serviceUrl } : {}
+	};
+}
+function normalizeReleaseMode(mode) {
+	if (mode === "production") return "production";
+	if (mode === "development") return "development";
+	return "preview";
+}
+function publicLiteralDefinitions(identity, releaseMode) {
+	return {
+		[BUILD_ID_LITERAL]: JSON.stringify(identity.buildId),
+		[GIT_COMMIT_LITERAL]: JSON.stringify(identity.gitCommit ?? ""),
+		...releaseMode ? { [BUILD_MODE_LITERAL]: JSON.stringify(releaseMode) } : {}
+	};
+}
+function assertReservedLiterals(current, expected, location) {
+	if (!current) return;
+	for (const key of [
+		BUILD_ID_LITERAL,
+		GIT_COMMIT_LITERAL,
+		BUILD_MODE_LITERAL
+	]) if (Object.prototype.hasOwnProperty.call(current, key) && current[key] !== expected[key]) throw new Error(`${location} already defines reserved ${key}; configure it through visualReview() options`);
+}
+//#endregion
+export { visualReview };

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@01.works/visual-review",
+  "version": "0.1.0",
+  "description": "Invitation-only visual feedback for staging websites, hosted by 01.works.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/01works/visual-review.git",
+    "directory": "packages/review-client"
+  },
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSES"
+  ],
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js",
+      "default": "./dist/next.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js",
+      "default": "./dist/vite.js"
+    },
+    "./next-config": {
+      "types": "./dist/next-config.d.ts",
+      "import": "./dist/next-config.js",
+      "default": "./dist/next-config.js"
+    }
+  },
+  "scripts": {
+    "build": "tsdown --config tsdown.config.ts && tsdown --config tsdown.node.config.ts && node scripts/emit-public-types.mjs",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.18"
+  },
+  "peerDependencies": {
+    "next": ">=15.5.0",
+    "react": ">=18.2.0",
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@babel/core": "^7.28.5",
+    "@babel/parser": "^7.28.5",
+    "@babel/plugin-transform-react-jsx": "^7.27.1",
+    "@babel/plugin-transform-typescript": "^7.28.5",
+    "@instantdb/core": "^1.0.52",
+    "magic-string": "^0.30.21"
+  }
+}