roxxie-proxy-u-prod 0.1.0

package/scripts/build.mjs

@@ -0,0 +1,344 @@
+/* SPDX-License-Identifier: AGPL-3.0-only */
+
+import { spawnSync } from "node:child_process";
+import {
+	access,
+	copyFile,
+	cp,
+	mkdir,
+	readFile,
+	readdir,
+	rm,
+	writeFile,
+} from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const checkoutRoot = resolve(packageRoot, "../..");
+const sourceRoot = join(packageRoot, "source");
+
+async function isWorkspaceRoot(root) {
+	try {
+		await access(join(root, "packages/chrome/package.json"));
+		await access(join(root, "rspack.config.ts"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+const buildingFromPackagedSource =
+	resolve(checkoutRoot, "packages/roxxie-proxy-u-prod") !== packageRoot ||
+	!(await isWorkspaceRoot(checkoutRoot));
+const repositoryRoot = buildingFromPackagedSource ? sourceRoot : checkoutRoot;
+if (!(await isWorkspaceRoot(repositoryRoot))) {
+	throw new Error(
+		"Could not find either the Roxxie Proxy U checkout or the packaged source/ workspace"
+	);
+}
+const chromeRoot = join(repositoryRoot, "packages/chrome");
+const outputRoot = join(packageRoot, "dist");
+const runtimeRoot = join(packageRoot, "runtime");
+const thirdPartyRoot = join(packageRoot, "third_party");
+const manifest = JSON.parse(
+	await readFile(join(packageRoot, "package.json"), "utf8")
+);
+
+const trackerUrl = process.env.ROXXIE_TRACKER_URL ?? "https://100.58.76.81/";
+const runtimeBase = process.env.ROXXIE_RUNTIME_BASE ?? "/browser/";
+const cdnBase =
+	process.env.ROXXIE_CDN_BASE ??
+	`https://cdn.jsdelivr.net/npm/${manifest.name}@${manifest.version}/dist/`;
+
+function validateConfiguration() {
+	const tracker = new URL(trackerUrl);
+	if (
+		tracker.protocol !== "https:" ||
+		tracker.hostname !== "100.58.76.81" ||
+		tracker.pathname !== "/" ||
+		tracker.search ||
+		tracker.hash ||
+		tracker.username ||
+		tracker.password
+	) {
+		throw new Error(
+			"ROXXIE_TRACKER_URL must be the production origin https://100.58.76.81/"
+		);
+	}
+	if (!runtimeBase.startsWith("/") || !runtimeBase.endsWith("/")) {
+		throw new Error("ROXXIE_RUNTIME_BASE must be an absolute path ending in /");
+	}
+	if (!cdnBase.startsWith("https://") || !cdnBase.endsWith("/")) {
+		throw new Error("ROXXIE_CDN_BASE must be an HTTPS URL ending in /");
+	}
+}
+
+validateConfiguration();
+await rm(outputRoot, { recursive: true, force: true });
+await rm(runtimeRoot, { recursive: true, force: true });
+if (!buildingFromPackagedSource) {
+	await rm(sourceRoot, { recursive: true, force: true });
+	await rm(thirdPartyRoot, { recursive: true, force: true });
+}
+await mkdir(runtimeRoot, { recursive: true });
+
+if (buildingFromPackagedSource) {
+	for (const workspace of [
+		"roxxie-transports-adrift-protocol",
+		"roxxie-transports-tracker-protocol",
+		"roxxie-transports",
+	]) {
+		const sourceBuild = spawnSync(
+			"pnpm",
+			["--dir", repositoryRoot, "--filter", workspace, "build"],
+			{
+				cwd: repositoryRoot,
+				env: { ...process.env, CI: "1" },
+				stdio: "inherit",
+			}
+		);
+		if (sourceBuild.error) throw sourceBuild.error;
+		if (sourceBuild.status !== 0) {
+			throw new Error(
+				`Packaged ${workspace} source build failed with ${sourceBuild.status}; install source/ with pnpm first`
+			);
+		}
+	}
+}
+
+const injectResult = spawnSync(
+	"pnpm",
+	["exec", "rspack", "build", "--config-name", "inject"],
+	{
+		cwd: repositoryRoot,
+		env: {
+			...process.env,
+			CI: "1",
+			ROXXIE_PRODUCTION_BUILD: "1",
+			SKIP_CORE: "1",
+		},
+		stdio: "inherit",
+	}
+);
+if (injectResult.error) throw injectResult.error;
+if (injectResult.status !== 0) {
+	throw new Error(
+		`Production injection bundle build failed with ${injectResult.status}`
+	);
+}
+
+const result = spawnSync(
+	"pnpm",
+	[
+		"--dir",
+		chromeRoot,
+		"exec",
+		"vite",
+		"build",
+		"--outDir",
+		outputRoot,
+		"--emptyOutDir",
+	],
+	{
+		cwd: repositoryRoot,
+		env: {
+			...process.env,
+			VITE_BASE: cdnBase,
+			VITE_RUNTIME_BASE: runtimeBase,
+			VITE_ISOLATION_ORIGIN: "none",
+			VITE_SOURCEMAP: "0",
+			VITE_PRODUCTION_PACKAGE: "1",
+		},
+		stdio: "inherit",
+	}
+);
+if (result.error) throw result.error;
+if (result.status !== 0) {
+	throw new Error(`Vite production package build failed with ${result.status}`);
+}
+
+const shell = await readFile(join(outputRoot, "index.html"), "utf8");
+if (!shell.includes(cdnBase)) {
+	throw new Error("Generated shell does not reference the pinned CDN release");
+}
+await writeFile(join(runtimeRoot, "index.html"), shell);
+
+for (const filename of ["controller.sw.js", "localcontrollersw.js", "sw.js"]) {
+	await copyFile(join(outputRoot, filename), join(runtimeRoot, filename));
+}
+
+await writeFile(
+	join(runtimeRoot, "roxxie-network.json"),
+	JSON.stringify(
+		{
+			schemaVersion: 1,
+			tracker: { url: trackerUrl },
+			timeouts: {
+				signalingMs: 12000,
+				iceGatheringMs: 5000,
+				webrtcMs: 18000,
+				handshakeMs: 5000,
+				probeMs: 3000,
+			},
+		},
+		null,
+		"\t"
+	) + "\n"
+);
+
+for (const filename of [
+	"index.html",
+	"controller.sw.js",
+	"localcontrollersw.js",
+	"sw.js",
+	"roxxie-network.json",
+	"ROXXIE_NETWORK.md",
+]) {
+	await rm(join(outputRoot, filename), { force: true });
+}
+
+if (!buildingFromPackagedSource) {
+	await cp(join(repositoryRoot, "LICENSE"), join(packageRoot, "LICENSE"));
+	await copyFile(
+		join(repositoryRoot, "THIRD_PARTY_NOTICES.md"),
+		join(packageRoot, "THIRD_PARTY_NOTICES.md")
+	);
+	await cp(
+		join(repositoryRoot, "third_party", "filter-lists"),
+		join(thirdPartyRoot, "filter-lists"),
+		{ recursive: true }
+	);
+
+	const sourceEntries = [
+		"package.json",
+		"pnpm-lock.yaml",
+		"pnpm-workspace.yaml",
+		"rspack.config.ts",
+		"scripts/update-adblock-assets.mjs",
+		"packages/cdp/dist",
+		"packages/cdp/LICENSE",
+		"packages/cdp/README.md",
+		"packages/cdp/package.json",
+		"packages/cdp/script",
+		"packages/cdp/src",
+		"packages/cdp/tsconfig.json",
+		"packages/cdp/webpack.config.js",
+		"packages/chrome/index.html",
+		"packages/chrome/package.json",
+		"packages/chrome/public",
+		"packages/chrome/src",
+		"packages/chrome/tsconfig.json",
+		"packages/chrome/vite.config.ts",
+		"packages/inject/package.json",
+		"packages/inject/src",
+		"packages/adrift-protocol/package.json",
+		"packages/adrift-protocol/src",
+		"packages/adrift-protocol/tsconfig.json",
+		"packages/tracker-protocol/package.json",
+		"packages/tracker-protocol/src",
+		"packages/tracker-protocol/tsconfig.json",
+		"packages/roxxie-transport/package.json",
+		"packages/roxxie-transport/src",
+		"packages/roxxie-transport/tsconfig.json",
+		"packages/scramjet/rspack.config.ts",
+		"packages/scramjet/patches/htmlparser2@12.0.0.patch",
+		"packages/scramjet/tsconfig.json",
+		"packages/scramjet/packages/controller/package.json",
+		"packages/scramjet/packages/controller/src",
+		"packages/scramjet/packages/controller/tsconfig.json",
+		"packages/scramjet/packages/core/lib",
+		"packages/scramjet/packages/core/package.json",
+		"packages/scramjet/packages/core/dist",
+		"packages/scramjet/packages/core/src",
+		"packages/scramjet/packages/core/tsconfig.json",
+		"packages/scramjet/packages/rpc/index.ts",
+		"packages/scramjet/packages/rpc/package.json",
+		"packages/scramjet/packages/utils/package.json",
+		"packages/scramjet/packages/utils/src",
+		"packages/scramjet/packages/utils/tsconfig.json",
+		"external/dreamlandjs/LICENSE",
+		"external/dreamlandjs/README.md",
+		"external/dreamlandjs/dist",
+		"external/dreamlandjs/package.json",
+		"external/dreamlandjs/rollup.config.ts",
+		"external/dreamlandjs/rollup.plugins.ts",
+		"external/dreamlandjs/src",
+		"external/dreamlandjs/tsconfig.json",
+	];
+	for (const relativePath of sourceEntries) {
+		const destination = join(sourceRoot, relativePath);
+		await mkdir(dirname(destination), { recursive: true });
+		await cp(join(repositoryRoot, relativePath), destination, {
+			recursive: true,
+		});
+	}
+
+	// Rspack writes the checkout root into context-module comments and source
+	// maps. These strings are not executable inputs and must not disclose the
+	// maintainer's filesystem in the published preferred-source snapshot.
+	const generatedCoreRoot = join(
+		sourceRoot,
+		"packages/scramjet/packages/core/dist"
+	);
+	const checkoutPrefixes = [
+		repositoryRoot.replaceAll("\\", "/") + "/",
+		repositoryRoot.replaceAll("/", "\\") + "\\",
+	];
+	for (const relativePath of await readdir(generatedCoreRoot, {
+		recursive: true,
+	})) {
+		if (!/\.(?:c?js|mjs|map|json)$/u.test(relativePath)) continue;
+		const path = join(generatedCoreRoot, relativePath);
+		let contents;
+		try {
+			contents = await readFile(path, "utf8");
+		} catch (error) {
+			if (error?.code === "EISDIR") continue;
+			throw error;
+		}
+		const sanitized = checkoutPrefixes.reduce(
+			(value, prefix) => value.replaceAll(prefix, ""),
+			contents
+		);
+		if (sanitized !== contents) await writeFile(path, sanitized);
+	}
+
+	await writeFile(
+		join(sourceRoot, "pnpm-workspace.yaml"),
+		`ignoredBuiltDependencies:\n  - bufferutil\n\nonlyBuiltDependencies:\n  - core-js\n  - esbuild\n\nlinkWorkspacePackages: true\n\noverrides:\n  htmlparser2: 12.0.0\n\npatchedDependencies:\n  htmlparser2@12.0.0: packages/scramjet/patches/htmlparser2@12.0.0.patch\n\npackages:\n  - "packages/chrome"\n  - "packages/cdp"\n  - "packages/inject"\n  - "packages/adrift-protocol"\n  - "packages/tracker-protocol"\n  - "packages/roxxie-transport"\n  - "external/dreamlandjs"\n  - "packages/scramjet/packages/core"\n  - "packages/scramjet/packages/controller"\n  - "packages/scramjet/packages/rpc"\n  - "packages/scramjet/packages/utils"\n\ncatalog:\n  "@mercuryworkshop/proxy-transports": 1.0.2\n  htmlparser2: ^12.0.0\n`,
+		"utf8"
+	);
+
+	const rewriterRoot = "packages/scramjet/packages/core/rewriter";
+	for (const relativePath of [
+		"Cargo.lock",
+		"Cargo.toml",
+		"rust-toolchain.toml",
+		"rustfmt.toml",
+		"coverage-macro/Cargo.toml",
+		"coverage-macro/src",
+		"js/Cargo.toml",
+		"js/src",
+		"native/Cargo.toml",
+		"native/src",
+		"transform/Cargo.toml",
+		"transform/src",
+		"wasm/Cargo.toml",
+		"wasm/build.sh",
+		"wasm/src",
+	]) {
+		const sourcePath = join(rewriterRoot, relativePath);
+		const destination = join(sourceRoot, sourcePath);
+		await mkdir(dirname(destination), { recursive: true });
+		await cp(join(repositoryRoot, sourcePath), destination, {
+			recursive: true,
+		});
+	}
+}
+console.log(`Built ${manifest.name}@${manifest.version}`);
+console.log(`CDN assets: ${outputRoot}`);
+console.log(`Same-origin runtime: ${runtimeRoot}`);
+console.log(
+	`Build source: ${buildingFromPackagedSource ? "packaged source/ workspace" : "repository checkout"}`
+);

package/scripts/smoke.mjs

@@ -0,0 +1,123 @@
+/* SPDX-License-Identifier: AGPL-3.0-only */
+
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+import { dirname, extname, join, normalize, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { chromium } from "playwright";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const runtimeRoot = join(packageRoot, "runtime");
+const distRoot = join(packageRoot, "dist");
+const cdnPath = "/npm/roxxie-proxy-u-prod@0.1.0/dist/";
+
+const contentTypes = {
+	".bin": "application/octet-stream",
+	".css": "text/css; charset=utf-8",
+	".html": "text/html; charset=utf-8",
+	".js": "application/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".png": "image/png",
+	".svg": "image/svg+xml",
+	".wasm": "application/wasm",
+};
+
+function safePath(root, relative) {
+	const resolved = resolve(root, normalize(relative));
+	if (resolved !== root && !resolved.startsWith(root + "/")) {
+		throw new Error("Invalid test path");
+	}
+	return resolved;
+}
+
+async function sendFile(response, path) {
+	try {
+		const body = await readFile(path);
+		response.writeHead(200, {
+			"content-type": contentTypes[extname(path)] ?? "application/octet-stream",
+		});
+		response.end(body);
+	} catch {
+		response.writeHead(404).end("Not found");
+	}
+}
+
+const server = createServer(async (request, response) => {
+	const path = new URL(request.url ?? "/", "http://localhost").pathname;
+	if (path === "/browser/" || path === "/browser/index.html") {
+		await sendFile(response, join(runtimeRoot, "index.html"));
+		return;
+	}
+	if (path.startsWith("/browser/")) {
+		await sendFile(response, safePath(runtimeRoot, path.slice(9)));
+		return;
+	}
+	if (path === "/embed.js") {
+		await sendFile(response, join(packageRoot, "embed.js"));
+		return;
+	}
+	if (path === "/embed-test/") {
+		response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+		response.end(`<!doctype html>
+			<div id="target" style="width:800px;height:600px"></div>
+			<script src="/embed.js" data-roxxie-target="#target"
+				data-roxxie-src="/browser/"></script>`);
+		return;
+	}
+	response.writeHead(404).end("Not found");
+});
+
+await new Promise((resolveListen) =>
+	server.listen(0, "127.0.0.1", resolveListen)
+);
+const address = server.address();
+assert(address && typeof address === "object");
+const origin = `http://127.0.0.1:${address.port}`;
+
+const browser = await chromium.launch({ headless: true });
+try {
+	const context = await browser.newContext();
+	await context.route(
+		"https://cdn.jsdelivr.net/npm/roxxie-proxy-u-prod@0.1.0/dist/**",
+		async (route) => {
+			const url = new URL(route.request().url());
+			assert(url.pathname.startsWith(cdnPath));
+			const path = safePath(distRoot, url.pathname.slice(cdnPath.length));
+			const body = await readFile(path);
+			await route.fulfill({
+				body,
+				contentType: contentTypes[extname(path)] ?? "application/octet-stream",
+				headers: { "access-control-allow-origin": "*" },
+			});
+		}
+	);
+
+	const page = await context.newPage();
+	const pageErrors = [];
+	page.on("pageerror", (error) => pageErrors.push(error));
+	await page.goto(`${origin}/browser/`);
+	await page.getByRole("button", { name: "Start" }).waitFor();
+	assert.equal(pageErrors.length, 0);
+	assert.equal(
+		await page.locator('script[src^="https://cdn.jsdelivr.net/"]').count(),
+		1
+	);
+
+	await page.goto(`${origin}/embed-test/`);
+	const embedded = page.locator("iframe[data-roxxie-proxy-u]");
+	await embedded.waitFor();
+	await page
+		.frameLocator("iframe[data-roxxie-proxy-u]")
+		.getByRole("button", { name: "Start" })
+		.waitFor();
+	assert.equal(await embedded.count(), 1);
+	assert.equal(pageErrors.length, 0);
+
+	console.log("Production shell and one-page embed smoke test passed");
+} finally {
+	await browser.close();
+	await new Promise((resolveClose, rejectClose) =>
+		server.close((error) => (error ? rejectClose(error) : resolveClose()))
+	);
+}

package/scripts/verify.mjs

@@ -0,0 +1,122 @@
+/* SPDX-License-Identifier: AGPL-3.0-only */
+
+import { access, readFile, readdir, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const manifest = JSON.parse(
+	await readFile(join(packageRoot, "package.json"), "utf8")
+);
+const expectedCdn = `https://cdn.jsdelivr.net/npm/${manifest.name}@${manifest.version}/dist/`;
+const required = [
+	"embed.js",
+	"LICENSE",
+	"SOURCE.md",
+	"THIRD_PARTY_NOTICES.md",
+	"dist",
+	"source/packages/chrome/src",
+	"source/packages/chrome/src/adblock/assets/filters.bin",
+	"source/packages/cdp/dist/chobitsu.js",
+	"source/packages/cdp/src",
+	"source/packages/scramjet/packages/core/dist/scramjet.wasm",
+	"source/packages/scramjet/packages/core/src",
+	"source/packages/scramjet/patches/htmlparser2@12.0.0.patch",
+	"source/external/dreamlandjs/LICENSE",
+	"source/external/dreamlandjs/dist/core.js",
+	"third_party/filter-lists/manifest.json",
+	"third_party/filter-lists/LICENSE-GPL-3.0.txt",
+	"third_party/filter-lists/LICENSE-CC-BY-SA-3.0.txt",
+	"third_party/filter-lists/LICENSE-MPL-2.0.txt",
+	"third_party/filter-lists/easylist.txt",
+	"third_party/filter-lists/easyprivacy.txt",
+	"third_party/filter-lists/ublock-filters.txt",
+	"third_party/filter-lists/ublock-privacy.txt",
+	"third_party/filter-lists/ublock-unbreak.txt",
+	"third_party/filter-lists/ublock-resources.json",
+	"runtime/index.html",
+	"runtime/roxxie-network.json",
+	"runtime/controller.sw.js",
+	"runtime/localcontrollersw.js",
+	"runtime/sw.js",
+];
+
+function assertNoLocalPath(path, source) {
+	const normalized = source.replaceAll("\\", "/").replace(/\/+/gu, "/");
+	if (/\/(?:home|Users)\/[A-Za-z0-9._-]+\//u.test(normalized)) {
+		throw new Error(`${path} contains an absolute local source path`);
+	}
+}
+
+async function* walkFiles(root, relativeRoot = "") {
+	for (const entry of await readdir(join(root, relativeRoot), {
+		withFileTypes: true,
+	})) {
+		const relativePath = join(relativeRoot, entry.name);
+		if (
+			entry.isSymbolicLink() ||
+			entry.name === "node_modules" ||
+			(relativeRoot === "" && entry.name === "third_party")
+		) {
+			continue;
+		}
+		if (entry.isDirectory()) yield* walkFiles(root, relativePath);
+		else if (entry.isFile()) yield relativePath;
+	}
+}
+
+for (const path of required) await access(join(packageRoot, path));
+
+const shell = await readFile(join(packageRoot, "runtime/index.html"), "utf8");
+if (!shell.includes(expectedCdn)) {
+	throw new Error(`runtime/index.html must reference ${expectedCdn}`);
+}
+if (/127\.0\.0\.1|localhost/.test(shell)) {
+	throw new Error("Production shell contains a loopback address");
+}
+
+const network = JSON.parse(
+	await readFile(join(packageRoot, "runtime/roxxie-network.json"), "utf8")
+);
+if (network?.tracker?.url !== "https://100.58.76.81/") {
+	throw new Error("Production tracker URL is not https://100.58.76.81/");
+}
+
+const outputFiles = await readdir(join(packageRoot, "dist"), {
+	recursive: true,
+});
+const JavaScriptFiles = outputFiles.filter((path) => path.endsWith(".js"));
+if (JavaScriptFiles.length === 0) {
+	throw new Error("Production package contains no browser JavaScript");
+}
+if (outputFiles.some((path) => path.endsWith(".map"))) {
+	throw new Error("Production package must not contain source maps");
+}
+if (outputFiles.includes("index.html")) {
+	throw new Error("CDN dist must not claim that jsDelivr can execute HTML");
+}
+for (const path of JavaScriptFiles) {
+	const source = await readFile(join(packageRoot, "dist", path), "utf8");
+	assertNoLocalPath(`dist/${path}`, source);
+}
+for await (const path of walkFiles(packageRoot)) {
+	const contents = await readFile(join(packageRoot, path));
+	if (contents.includes(0)) continue;
+	assertNoLocalPath(path, contents.toString("utf8"));
+}
+if ((await stat(join(packageRoot, "runtime/controller.sw.js"))).size === 0) {
+	throw new Error("controller.sw.js is empty");
+}
+const filterManifest = JSON.parse(
+	await readFile(
+		join(packageRoot, "third_party/filter-lists/manifest.json"),
+		"utf8"
+	)
+);
+if (filterManifest?.format !== 1 || !Array.isArray(filterManifest.sources)) {
+	throw new Error("Bundled filter source manifest is invalid");
+}
+
+console.log(
+	`Verified ${manifest.name}@${manifest.version}: ${JavaScriptFiles.length} JavaScript asset(s)`
+);

package/source/external/dreamlandjs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mercury Workshop
+
+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/source/external/dreamlandjs/README.md

@@ -0,0 +1,22 @@
+<h1 align="center">dreamland.js</h1>
+<p align="center"><img src="./assets/logo.png" alt="logo" height="100"></p>
+
+dreamland is a utilitarian JSX-based web framework with **no virtual dom** and **no build step**. It is less than 4kb minified + brotli'd (smaller than preact), gradually integrates with existing plain JS projects, and is reasonably easy to learn.
+
+<div align="center">
+ <a href="https://dreamland.js.org/docs/getting-started">Get Started</a> | <a href="https://dreamland.js.org">Documentation</a> | <a href="https://dreamland.js.org/playground">Playground</a> | <a href="https://discord.gg/GKKF3CmHPA">Discord</a>
+</div>
+<br/>
+
+<div align="center">
+  <img src="https://img.shields.io/github/issues/MercuryWorkshop/dreamlandjs?style=for-the-badge&color=purple" height="25"/>
+  <img src="https://img.shields.io/github/stars/MercuryWorkshop/dreamlandjs?style=for-the-badge&color=purple" height="25"/>
+</div>
+
+---
+
+Check out the [website](https://dreamland.js.org/docs/getting-started) to get started with dreamland. You can also try dreamland online in the [playground](https://dreamland.js.org/playground), which has dreamland and typescript set up already.
+
+## Acknowledgements
+
+dreamland uses the [parsel](https://github.com/LeaVerou/parsel) CSS selector parsing library to transform CSS in components.