camox 0.59.0 → 0.61.0

package/dist/features/sdkBundle/sdkBundleName.js

@@ -0,0 +1,164 @@
+import { LUCIDE_ICON_HELPER, SDK_BUNDLE_TARGETS, loadsAtFirstPaint, packageOfSpecifier, sdkBundleEntryFile, sdkBundleSpecifiers } from "./specifiers.js";
+import { parse } from "yaml";
+
+//#region src/features/sdkBundle/sdkBundleName.ts
+/**
+* An SDK Bundle's name, computed from a pnpm lockfile alone, before anything is built: the
+* bundle and the website's build both bake it in. Runs anywhere Web Crypto does, in Node or a
+* Worker, so the platform can name a bundle without installing the website.
+*/
+/**
+* The version of the code that builds SDK Bundles. Bump it whenever a change to the builder
+* changes what a bundle holds for the same packages and settings.
+*/
+const SDK_BUNDLE_BUILDER_VERSION = "2";
+/** Where a website's pages and Worker find an SDK Bundle's files: `/_camox/sdk/<name>/`. */
+function sdkBundlePath(name) {
+	return `/_camox/sdk/${name}/`;
+}
+/**
+* The file a website's build names its SDK Bundle in, as `SdkBundleNames` JSON, in the server
+* build's folder beside its `wrangler.json`. A build without it is whole-app.
+*/
+const SDK_BUNDLE_BUILD_MANIFEST = "camox-sdk-bundle.json";
+/** What a hosted build whose SDK Bundle is missing fails with, followed by the names as JSON. */
+const SDK_BUNDLE_MISSING = "CAMOX_SDK_BUNDLE_MISSING";
+/** The line a build that's missing its SDK Bundle prints its error with. */
+function sdkBundleMissingLine(names) {
+	return `${SDK_BUNDLE_MISSING} ${JSON.stringify({
+		browser: names.browser,
+		workerd: names.workerd
+	})}`;
+}
+/**
+* The SDK Bundle a build's log says is missing, or null when the build failed for another reason:
+* the caller ensures the bundle, then builds again.
+*/
+function sdkBundleMissingIn(log) {
+	const json = new RegExp(`${SDK_BUNDLE_MISSING} (\\{[^\n]*?\\})`).exec(log)?.[1];
+	if (!json) return null;
+	try {
+		const { browser, workerd } = JSON.parse(json);
+		return typeof browser === "string" && typeof workerd === "string" ? {
+			browser,
+			workerd
+		} : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Packages camox depends on that no specifier on the list reaches: its CLI runs in Node, beside
+* the website's build.
+*/
+const NEVER_BUNDLED = /* @__PURE__ */ new Set(["@camox/cli"]);
+/**
+* A digest of the builder's version, the target, the settings and the lockfile's resolution
+* (name, version, integrity) of every package the target's specifiers reach.
+*/
+async function sdkBundleName({ lockfile, importer = ".", target, settings, builderVersion = "2" }) {
+	const parsed = parse(lockfile);
+	const specifiers = heldSpecifiers(parsed, importer, target);
+	const resolutions = bundledResolutions(parsed, importer, [...new Set(specifiers.map(packageOfSpecifier))]);
+	const digested = JSON.stringify({
+		builderVersion,
+		target,
+		specifiers,
+		settings: {
+			iconIds: settings.iconIds,
+			telemetryDisabled: settings.telemetryDisabled,
+			experimentalFeatures: settings.experimentalFeatures,
+			apiUrl: settings.apiUrl
+		},
+		packages: resolutions
+	});
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(digested));
+	return [...new Uint8Array(digest).slice(0, 16)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+* The specifiers the SDK Bundle of the website at `importer` holds for `target`: the packages it
+* shares with camox are in only when it installs them.
+*/
+function sdkBundleSpecifiersFor({ lockfile, importer = ".", target }) {
+	return heldSpecifiers(parse(lockfile), importer, target);
+}
+function heldSpecifiers(lockfile, importer, target) {
+	const locked = lockfile.importers?.[importer];
+	if (!locked) throw new Error(`Camox: the lockfile has no importer at ${JSON.stringify(importer)}.`);
+	const installed = new Set([
+		locked.dependencies,
+		locked.optionalDependencies,
+		locked.devDependencies
+	].flatMap((deps) => Object.keys(deps ?? {})));
+	return sdkBundleSpecifiers(target, installed);
+}
+/** Each package the roots reach, as `name@version` with its resolution, sorted. */
+function bundledResolutions(lockfile, importer, roots) {
+	const resolutions = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const importerOf = (path) => {
+		const locked = lockfile.importers?.[path];
+		if (!locked) throw new Error(`Camox: the lockfile has no importer at ${JSON.stringify(path)}.`);
+		return locked;
+	};
+	const importerVersions = (locked, withDev) => Object.fromEntries([
+		...Object.entries(locked.dependencies ?? {}),
+		...Object.entries(locked.optionalDependencies ?? {}),
+		...withDev ? Object.entries(locked.devDependencies ?? {}) : []
+	].map(([name, { version }]) => [name, version]));
+	const visit = (name, version, from) => {
+		if (NEVER_BUNDLED.has(name)) return;
+		if (version.startsWith("link:")) {
+			const path = joinPath(from, version.slice(5));
+			if (visited.has(`link:${path}`)) return;
+			visited.add(`link:${path}`);
+			resolutions.add(`${name}@link:${path}`);
+			for (const [dependency, dependencyVersion] of Object.entries(importerVersions(importerOf(path), false))) visit(dependency, dependencyVersion, path);
+			return;
+		}
+		const { snapshotKey, packageKey } = lockedKeys(name, version);
+		if (visited.has(snapshotKey)) return;
+		visited.add(snapshotKey);
+		const locked = lockfile.packages?.[packageKey];
+		if (!locked) throw new Error(`Camox: the lockfile has no package ${packageKey}.`);
+		resolutions.add(`${packageKey} ${JSON.stringify(locked.resolution ?? {})}`);
+		const peers = new Set(Object.keys(locked.peerDependencies ?? {}));
+		const snapshot = lockfile.snapshots?.[snapshotKey] ?? {};
+		for (const [dependency, dependencyVersion] of Object.entries({
+			...snapshot.dependencies,
+			...snapshot.optionalDependencies
+		})) if (!peers.has(dependency)) visit(dependency, dependencyVersion, from);
+	};
+	const website = importerVersions(importerOf(importer), true);
+	for (const root of roots) {
+		const version = website[root];
+		if (!version) throw new Error(`Camox: the website doesn't install ${root}.`);
+		visit(root, version, importer);
+	}
+	return [...resolutions].sort();
+}
+/**
+* Where a dependency's version finds it in the lockfile. pnpm writes `1.0.0(react@19.3.1)` for a
+* package resolved with peers, and the target's own `name@version` for an aliased one.
+*/
+function lockedKeys(name, version) {
+	const withoutPeers = version.split("(")[0];
+	if (/^(@?[^@]+)@(.+)$/.exec(withoutPeers)) return {
+		snapshotKey: version,
+		packageKey: withoutPeers
+	};
+	return {
+		snapshotKey: `${name}@${version}`,
+		packageKey: `${name}@${withoutPeers}`
+	};
+}
+/** A workspace folder, from the lockfile's, as pnpm names importers: `packages/sdk`, or `.`. */
+function joinPath(from, relative) {
+	const parts = [];
+	for (const part of `${from}/${relative}`.split("/")) if (part === "..") parts.pop();
+	else if (part && part !== ".") parts.push(part);
+	return parts.join("/") || ".";
+}
+
+//#endregion
+export { LUCIDE_ICON_HELPER, SDK_BUNDLE_BUILDER_VERSION, SDK_BUNDLE_BUILD_MANIFEST, SDK_BUNDLE_MISSING, SDK_BUNDLE_TARGETS, loadsAtFirstPaint, packageOfSpecifier, sdkBundleEntryFile, sdkBundleMissingIn, sdkBundleMissingLine, sdkBundleName, sdkBundlePath, sdkBundleSpecifiers, sdkBundleSpecifiersFor };

package/dist/features/sdkBundle/specifiers.d.ts

@@ -0,0 +1,34 @@
+//#region src/features/sdkBundle/specifiers.d.ts
+/**
+ * What an SDK Bundle holds: the bare specifiers a website's build leaves to it. The SDK owns this
+ * list, so an SDK release can change it. Each specifier gets one entry in each target it's for.
+ */
+/** Who loads an SDK Bundle's version: visitors' browsers, or the Worker in workerd. */
+export type SdkBundleTarget = "browser" | "workerd";
+export declare const SDK_BUNDLE_TARGETS: readonly SdkBundleTarget[];
+/**
+ * lucide's icon helper, which draws every icon. The website keeps its own icons, and they draw
+ * with the bundle's helper: a website's icon module imports it by relative path, from inside the
+ * package.
+ */
+export declare const LUCIDE_ICON_HELPER = "lucide-react/dist/esm/createLucideIcon.mjs";
+/**
+ * The bare specifiers an SDK Bundle's `target` version holds, each with an entry of its own, for
+ * a website that installs `websitePackages`.
+ */
+export declare function sdkBundleSpecifiers(target: SdkBundleTarget, websitePackages: ReadonlySet<string>): string[];
+/**
+ * Whether a page loads `specifier` at first paint: the camox entry points a page's code imports,
+ * the page's own client, React, and the packages websites share with camox. A page that imports
+ * another of camox's entry points loads one more chunk.
+ */
+export declare function loadsAtFirstPaint(specifier: string): boolean;
+/** The npm package a bare specifier imports from: `@tanstack/react-query` for itself. */
+export declare function packageOfSpecifier(specifier: string): string;
+/**
+ * The file a specifier's entry is, in its target's folder: `react/jsx-runtime` is
+ * `react~jsx-runtime.mjs`. Every entry sits at the folder's root, so the website's build can point
+ * at it from the bundle's name alone.
+ */
+export declare function sdkBundleEntryFile(specifier: string): string;
+//#endregion

package/dist/features/sdkBundle/specifiers.js

@@ -0,0 +1,146 @@
+//#region src/features/sdkBundle/specifiers.ts
+const SDK_BUNDLE_TARGETS = ["browser", "workerd"];
+/**
+* lucide's icon helper, which draws every icon. The website keeps its own icons, and they draw
+* with the bundle's helper: a website's icon module imports it by relative path, from inside the
+* package.
+*/
+const LUCIDE_ICON_HELPER = "lucide-react/dist/esm/createLucideIcon.mjs";
+const SPECIFIERS = [
+	{ specifier: "camox/createCollection" },
+	{ specifier: "camox/dom" },
+	{
+		specifier: "camox/createApp",
+		page: true
+	},
+	{
+		specifier: "camox/createBlock",
+		page: true
+	},
+	{
+		specifier: "camox/createLayout",
+		page: true
+	},
+	{
+		specifier: "camox/document",
+		page: true
+	},
+	{ specifier: "camox/CamoxPreview" },
+	{ specifier: "camox/CamoxContent" },
+	{ specifier: "camox/CamoxProvider" },
+	{ specifier: "camox/CamoxStudio" },
+	{
+		specifier: "camox/navigation",
+		page: true
+	},
+	{
+		specifier: "camox/_internal/pageClient",
+		only: "browser",
+		page: true
+	},
+	{
+		specifier: "camox/_internal/studioClient",
+		only: "browser"
+	},
+	{
+		specifier: "camox/_internal/rendererClient",
+		only: "browser"
+	},
+	{
+		specifier: "camox/_internal/pageServer",
+		only: "workerd"
+	},
+	{
+		specifier: "camox/_internal/studioServer",
+		only: "workerd"
+	},
+	{
+		specifier: "camox/_internal/runtime",
+		only: "workerd"
+	},
+	{
+		specifier: "camox/_internal/imageResponse",
+		only: "workerd"
+	},
+	{
+		specifier: "camox/_internal/workerRuntime",
+		only: "workerd"
+	},
+	{
+		specifier: "react",
+		page: true
+	},
+	{
+		specifier: "react/jsx-runtime",
+		page: true
+	},
+	{
+		specifier: "react/compiler-runtime",
+		page: true
+	},
+	{
+		specifier: "react-dom",
+		page: true
+	},
+	{
+		specifier: "react-dom/client",
+		only: "browser",
+		page: true
+	},
+	{
+		specifier: "react-dom/server",
+		only: "workerd"
+	},
+	{ specifier: "@tanstack/react-query" },
+	{
+		specifier: "tailwind-merge",
+		shared: true,
+		page: true
+	},
+	{
+		specifier: "clsx",
+		shared: true,
+		page: true
+	},
+	{
+		specifier: "class-variance-authority",
+		shared: true,
+		page: true
+	},
+	{
+		specifier: LUCIDE_ICON_HELPER,
+		shared: true,
+		page: true
+	}
+];
+/**
+* The bare specifiers an SDK Bundle's `target` version holds, each with an entry of its own, for
+* a website that installs `websitePackages`.
+*/
+function sdkBundleSpecifiers(target, websitePackages) {
+	return SPECIFIERS.filter(({ specifier, only, shared }) => (!only || only === target) && (!shared || websitePackages.has(packageOfSpecifier(specifier)))).map(({ specifier }) => specifier);
+}
+/**
+* Whether a page loads `specifier` at first paint: the camox entry points a page's code imports,
+* the page's own client, React, and the packages websites share with camox. A page that imports
+* another of camox's entry points loads one more chunk.
+*/
+function loadsAtFirstPaint(specifier) {
+	return SPECIFIERS.some((entry) => entry.specifier === specifier && entry.page);
+}
+/** The npm package a bare specifier imports from: `@tanstack/react-query` for itself. */
+function packageOfSpecifier(specifier) {
+	const parts = specifier.split("/");
+	return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+/**
+* The file a specifier's entry is, in its target's folder: `react/jsx-runtime` is
+* `react~jsx-runtime.mjs`. Every entry sits at the folder's root, so the website's build can point
+* at it from the bundle's name alone.
+*/
+function sdkBundleEntryFile(specifier) {
+	return `${specifier.replace(/\.[cm]?js$/, "").replaceAll("/", "~")}.mjs`;
+}
+
+//#endregion
+export { LUCIDE_ICON_HELPER, SDK_BUNDLE_TARGETS, loadsAtFirstPaint, packageOfSpecifier, sdkBundleEntryFile, sdkBundleSpecifiers };