@canmi/web 0.0.0

package/LICENSE

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

package/dist/compat/src/build.d.ts

@@ -0,0 +1,8 @@
+//#region compat/src/build.d.ts
+/**
+ * Reads an app's `browserslist` floors into esbuild's `build.target`.
+ *
+ * See spec/compat.md, "The syntax floor is set to the same line, deliberately".
+ */
+export declare function esbuildTarget(browserslist: string[]): string[];
+//#endregion

package/dist/compat/src/build.js

@@ -0,0 +1,15 @@
+//#region compat/src/build.ts
+/**
+* Reads an app's `browserslist` floors into esbuild's `build.target`.
+*
+* See spec/compat.md, "The syntax floor is set to the same line, deliberately".
+*/
+function esbuildTarget(browserslist) {
+	return browserslist.map((query) => {
+		const floor = /^([a-z]+) >= ([\d.]+)$/.exec(query);
+		if (!floor) throw new Error(`browserslist entry is not a floor, so esbuild cannot take it: ${query}`);
+		return `${floor[1]}${floor[2]}`;
+	});
+}
+//#endregion
+export { esbuildTarget };

package/dist/compat/src/index.d.ts

@@ -0,0 +1,14 @@
+//#region compat/src/index.d.ts
+/**
+ * Browser features missing from a browser that once crashed a reader; any one absent loads
+ * core-js. A new one met in production is one more line here and one in canaries.test.ts.
+ *
+ * Why a list of met cases and not a complete one, why `stable` and not `es` or `actual` -- see
+ * spec/compat.md, "The API floor".
+ */
+export declare const CANARIES: {
+  name: string;
+  present: () => boolean;
+}[];
+export declare function prepareBrowserRuntime(): Promise<void>;
+//#endregion

package/dist/compat/src/index.js

@@ -0,0 +1,21 @@
+//#region compat/src/index.ts
+/**
+* Browser features missing from a browser that once crashed a reader; any one absent loads
+* core-js. A new one met in production is one more line here and one in canaries.test.ts.
+*
+* Why a list of met cases and not a complete one, why `stable` and not `es` or `actual` -- see
+* spec/compat.md, "The API floor".
+*/
+const CANARIES = [{
+	name: "Array.prototype.toSorted",
+	present: () => typeof Array.prototype.toSorted === "function"
+}, {
+	name: "URL.canParse",
+	present: () => typeof URL.canParse === "function"
+}];
+async function prepareBrowserRuntime() {
+	if (CANARIES.every((canary) => canary.present())) return;
+	await import("core-js/stable");
+}
+//#endregion
+export { CANARIES, prepareBrowserRuntime };

package/dist/referer/src/index.d.ts

@@ -0,0 +1,20 @@
+//#region referer/src/index.d.ts
+/**
+ * Where a reader came from, taken out of the address bar. See spec/architecture/referer.md.
+ */
+/** Parameters a link may carry into any page, taken out once the page is running. */
+export declare const ARRIVAL_PARAMETERS: readonly ['ref'];
+/**
+ * `url`'s path, query and hash with every `name` pair taken out and every other pair left as it
+ * arrived, spelling and order included; undefined when there is no `name` to take.
+ */
+export declare function withoutParameter(url: URL, name: string): string | undefined;
+/**
+ * Take `name` out of the address bar, in place: no history entry, and no page view either. A
+ * tracker counts views by wrapping `history.replaceState` on the instance, so the prototype's is
+ * the browser's own. Returns the value taken, or null when there was none.
+ */
+export declare function takeParameter(name: string): string | null;
+/** Take every arrival parameter. Called once a page has hydrated; nothing reads them yet. */
+export declare function takeArrivalParameters(): void;
+//#endregion

package/dist/referer/src/index.js

@@ -0,0 +1,45 @@
+//#region referer/src/index.ts
+/**
+* Where a reader came from, taken out of the address bar. See spec/architecture/referer.md.
+*/
+/** Parameters a link may carry into any page, taken out once the page is running. */
+const ARRIVAL_PARAMETERS = ["ref"];
+/** A query pair's name, decoded; a name that does not decode is compared as written. */
+function nameOf(pair) {
+	const name = pair.split("=", 1)[0].replaceAll("+", " ");
+	try {
+		return decodeURIComponent(name);
+	} catch {
+		return name;
+	}
+}
+/**
+* `url`'s path, query and hash with every `name` pair taken out and every other pair left as it
+* arrived, spelling and order included; undefined when there is no `name` to take.
+*/
+function withoutParameter(url, name) {
+	if (!url.search) return void 0;
+	const pairs = url.search.slice(1).split("&");
+	const kept = pairs.filter((pair) => nameOf(pair) !== name);
+	if (kept.length === pairs.length) return void 0;
+	const search = kept.length > 0 ? `?${kept.join("&")}` : "";
+	return `${url.pathname}${search}${url.hash}`;
+}
+/**
+* Take `name` out of the address bar, in place: no history entry, and no page view either. A
+* tracker counts views by wrapping `history.replaceState` on the instance, so the prototype's is
+* the browser's own. Returns the value taken, or null when there was none.
+*/
+function takeParameter(name) {
+	const url = new URL(window.location.href);
+	const value = url.searchParams.get(name);
+	const replacement = withoutParameter(url, name);
+	if (replacement !== void 0) History.prototype.replaceState.call(history, history.state, "", replacement);
+	return value;
+}
+/** Take every arrival parameter. Called once a page has hydrated; nothing reads them yet. */
+function takeArrivalParameters() {
+	for (const name of ARRIVAL_PARAMETERS) takeParameter(name);
+}
+//#endregion
+export { ARRIVAL_PARAMETERS, takeArrivalParameters, takeParameter, withoutParameter };

package/dist/sentry/src/build.d.ts

@@ -0,0 +1,50 @@
+import { sentrySvelteKit } from "@sentry/sveltekit/vite";
+//#region sentry/src/build.d.ts
+/** What `sentrySvelteKit` takes. Its own name for this is not part of the published surface. */
+export type SentryPluginOptions = NonNullable<Parameters<typeof sentrySvelteKit>[0]>;
+/** The environment a build reads, passed in so a test can hand it one. */
+export type BuildEnv = Readonly<Record<string, string | undefined>>;
+/** The Sentry organization every app's project lives in. */
+export declare const SENTRY_ORG = "canmi";
+export interface UploadPolicy {
+  /**
+   * Throw when CI builds without `SENTRY_AUTH_TOKEN`, for an app whose CI build is the one
+   * deployed. The site sets it; the status page, built on Vercel, does not.
+   */
+  requireTokenInCi?: boolean;
+}
+/**
+ * Whether this build sends its source maps to Sentry: only when `SENTRY_AUTH_TOKEN` is set.
+ *
+ * `SENTRY_SKIP_UPLOAD`, set in `mise.toml`, turns it off whatever the token says -- see
+ * spec/architecture/data.md, "A CI build compiles the site, and no longer compiles the corpus".
+ * Any non-empty value skips, so `SENTRY_SKIP_UPLOAD= pnpm run build` is how one local build
+ * uploads after all; `0` and `false` skip too, since this is a switch and parses no words.
+ */
+export declare function uploadsSourceMaps(env: BuildEnv, policy?: UploadPolicy): boolean;
+export interface PluginRequest {
+  /** The project's slug in {@link SENTRY_ORG}. */
+  project: string;
+  /** The answer of {@link uploadsSourceMaps}, asked once by the caller. */
+  upload: boolean;
+  env: BuildEnv;
+  /** Globs of the maps the adapter wrote, deleted once they are uploaded. */
+  mapsToDelete: string[];
+}
+/**
+ * The options every app hands `sentrySvelteKit`.
+ *
+ * The skip drives `autoUploadSourceMaps` rather than only withholding the token, because the
+ * plugin reads `SENTRY_AUTH_TOKEN` from the environment itself. Maps are deleted after the upload,
+ * so the deployed output carries none.
+ */
+export declare function pluginOptions({ project, upload, env, mapsToDelete }: PluginRequest): SentryPluginOptions;
+/**
+ * Vite's `build.sourcemap` for a build that does or does not upload.
+ *
+ * `hidden` emits maps without the `sourceMappingURL` comment, so no browser asks for a file that
+ * was deleted. A build that skips emits none, since deletion only follows an upload and a map
+ * left behind would ship the app's source as a static asset.
+ */
+export declare function sourcemapSetting(upload: boolean): 'hidden' | false;
+//#endregion

package/dist/sentry/src/build.js

@@ -0,0 +1,46 @@
+//#region sentry/src/build.ts
+/** The Sentry organization every app's project lives in. */
+const SENTRY_ORG = "canmi";
+/**
+* Whether this build sends its source maps to Sentry: only when `SENTRY_AUTH_TOKEN` is set.
+*
+* `SENTRY_SKIP_UPLOAD`, set in `mise.toml`, turns it off whatever the token says -- see
+* spec/architecture/data.md, "A CI build compiles the site, and no longer compiles the corpus".
+* Any non-empty value skips, so `SENTRY_SKIP_UPLOAD= pnpm run build` is how one local build
+* uploads after all; `0` and `false` skip too, since this is a switch and parses no words.
+*/
+function uploadsSourceMaps(env, policy = {}) {
+	if (env.SENTRY_SKIP_UPLOAD) return false;
+	const token = env.SENTRY_AUTH_TOKEN;
+	if (!token && env.CI && policy.requireTokenInCi) throw new Error("SENTRY_AUTH_TOKEN is unset in CI. Add it as an encrypted build variable, or the deployed worker will report every error without a usable stack trace.");
+	return Boolean(token);
+}
+/**
+* The options every app hands `sentrySvelteKit`.
+*
+* The skip drives `autoUploadSourceMaps` rather than only withholding the token, because the
+* plugin reads `SENTRY_AUTH_TOKEN` from the environment itself. Maps are deleted after the upload,
+* so the deployed output carries none.
+*/
+function pluginOptions({ project, upload, env, mapsToDelete }) {
+	return {
+		org: SENTRY_ORG,
+		project,
+		autoUploadSourceMaps: upload,
+		authToken: upload ? env.SENTRY_AUTH_TOKEN : void 0,
+		telemetry: false,
+		sourcemaps: { filesToDeleteAfterUpload: mapsToDelete }
+	};
+}
+/**
+* Vite's `build.sourcemap` for a build that does or does not upload.
+*
+* `hidden` emits maps without the `sourceMappingURL` comment, so no browser asks for a file that
+* was deleted. A build that skips emits none, since deletion only follows an upload and a map
+* left behind would ship the app's source as a static asset.
+*/
+function sourcemapSetting(upload) {
+	return upload ? "hidden" : false;
+}
+//#endregion
+export { SENTRY_ORG, pluginOptions, sourcemapSetting, uploadsSourceMaps };

package/dist/sentry/src/client.d.ts

@@ -0,0 +1,6 @@
+import { SentryApp } from "./options.js";
+//#region sentry/src/client.d.ts
+/** Initialize the browser SDK, or do nothing when the app has no DSN. */
+export declare function initClient({ dsn, dev }: SentryApp): void;
+//#endregion
+export type { SentryApp };

package/dist/sentry/src/client.js

@@ -0,0 +1,10 @@
+import { initOptions } from "./options.js";
+import { init } from "@sentry/sveltekit";
+//#region sentry/src/client.ts
+/** Initialize the browser SDK, or do nothing when the app has no DSN. */
+function initClient({ dsn, dev }) {
+	if (!dsn) return;
+	init(initOptions(dsn, dev));
+}
+//#endregion
+export { initClient };

package/dist/sentry/src/options.d.ts

@@ -0,0 +1,11 @@
+//#region sentry/src/options.d.ts
+/**
+ * What an app says about itself to the SDK, on either side.
+ *
+ * `dsn` absent means the app has no Sentry project: every helper then does nothing.
+ */
+export interface SentryApp {
+  dsn: string | undefined;
+  dev: boolean;
+}
+//#endregion

package/dist/sentry/src/options.js

@@ -0,0 +1,22 @@
+//#region sentry/src/options.ts
+/** A transport that accepts every envelope and sends none of them. */
+const silent = () => ({
+	send: () => Promise.resolve({}),
+	flush: () => Promise.resolve(true)
+});
+/**
+* The init options both sides share.
+*
+* Development initializes the SDK with every integration installed, so capture is exercised, and
+* hands it a transport that sends nothing. `enabled: false` would install no integrations at all.
+* See spec/analytics.md, "Development loads the client and reports nothing".
+*/
+function initOptions(dsn, dev) {
+	return {
+		dsn,
+		environment: dev ? "development" : "production",
+		...dev ? { transport: silent } : {}
+	};
+}
+//#endregion
+export { initOptions };

package/dist/sentry/src/server.d.ts

@@ -0,0 +1,13 @@
+import { SentryApp } from "./options.js";
+import { Handle } from "@sveltejs/kit/hooks";
+//#region sentry/src/server.d.ts
+/**
+ * The handles that initialize and instrument the server SDK, first in `sequence`; none without a
+ * DSN.
+ *
+ * `initCloudflareSentryHandle` serves both adapters: the `worker` export condition wraps the
+ * request in Cloudflare's context, and the `node` one initializes on the first request.
+ */
+export declare function serverHandles({ dsn, dev }: SentryApp): Handle[];
+//#endregion
+export type { SentryApp };

package/dist/sentry/src/server.js

@@ -0,0 +1,16 @@
+import { initOptions } from "./options.js";
+import { initCloudflareSentryHandle, sentryHandle } from "@sentry/sveltekit";
+//#region sentry/src/server.ts
+/**
+* The handles that initialize and instrument the server SDK, first in `sequence`; none without a
+* DSN.
+*
+* `initCloudflareSentryHandle` serves both adapters: the `worker` export condition wraps the
+* request in Cloudflare's context, and the `node` one initializes on the first request.
+*/
+function serverHandles({ dsn, dev }) {
+	if (!dsn) return [];
+	return [initCloudflareSentryHandle(initOptions(dsn, dev)), sentryHandle()];
+}
+//#endregion
+export { serverHandles };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@canmi/web",
+  "version": "0.0.0",
+  "description": "Running a SvelteKit app in public: browser compatibility, the referrer and Sentry",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/canmi21/lib.git",
+    "directory": "pkgs/web"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./compat": {
+      "types": "./dist/compat/src/index.d.ts",
+      "default": "./dist/compat/src/index.js"
+    },
+    "./compat/build": {
+      "types": "./dist/compat/src/build.d.ts",
+      "default": "./dist/compat/src/build.js"
+    },
+    "./referer": {
+      "types": "./dist/referer/src/index.d.ts",
+      "default": "./dist/referer/src/index.js"
+    },
+    "./sentry/build": {
+      "types": "./dist/sentry/src/build.d.ts",
+      "default": "./dist/sentry/src/build.js"
+    },
+    "./sentry/client": {
+      "types": "./dist/sentry/src/client.d.ts",
+      "default": "./dist/sentry/src/client.js"
+    },
+    "./sentry/server": {
+      "types": "./dist/sentry/src/server.d.ts",
+      "default": "./dist/sentry/src/server.js"
+    }
+  },
+  "dependencies": {
+    "@sentry/sveltekit": "^11.4.0",
+    "@sveltejs/kit": "^3.0.0",
+    "core-js": "^3.50.0"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}