quicklook-kit 0.2.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,23 @@
+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/{readme.markdown → README.markdown}

@@ -14,15 +14,15 @@ Built-in support for SvelteKit, Astro, SolidStart, Nuxt and Analog. Any other fr
 
 - macOS 14 or later, with [Xcode](https://apps.apple.com/app/xcode/id497799835) installed
 - [XcodeGen](https://github.com/yonaskolb/XcodeGen)
-- [Bun](https://bun.sh), which runs the `quicklook` CLI
+- [Node.js](https://nodejs.org) 22.17 or later, which runs the `quicklook` CLI
 
 ## Installation
 
 ```sh
-bun add --dev quicklook-kit
+npm install --save-dev quicklook-kit
 ```
 
-To start from scratch, use one of the [templates](https://github.com/idleberg/quicklook-kit/tree/main/templates) instead.
+To start from scratch, run `pnpm create quicklook` instead.
 
 ## Setup
 

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cli.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+import { a as serializeCsp, i as loadConfig, t as addSources } from "./config-BQ-9qYNV.mjs";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { cp, glob, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+//#region src/cli.ts
+const config = await loadConfig();
+const { root, name, bundleId, macOS, types, framework, icon } = config;
+const target = name.replace(/[^A-Za-z0-9]/g, "");
+const work = `${root}/.quicklook`;
+const web = `${work}/web`;
+const built = `${work}/build/${name}.app`;
+const installed = `/Applications/${name}.app`;
+const native = fileURLToPath(new URL("../native", import.meta.url));
+const lsregister = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+const leadingV = /^v/;
+const inlineScript = /<script\b(?![^>]*\ssrc=)[^>]*>([\s\S]*?)<\/script>/gi;
+/** Runs a command, exiting with its status if it fails unless `nothrow` is set. */
+function exec([file = "", ...args], { quiet = false, nothrow = false, env = process.env } = {}) {
+	const { status, error } = spawnSync(file, args, {
+		cwd: root,
+		env,
+		stdio: quiet ? "ignore" : "inherit"
+	});
+	if (error) throw error;
+	if (status !== 0 && !nothrow) process.exit(status ?? 1);
+}
+/** `node_modules/.bin` of the project and every folder above it, as workspaces hoist binaries. */
+function binPath() {
+	const dirs = [];
+	for (let dir = root;; dir = dirname(dir)) {
+		dirs.push(join(dir, "node_modules/.bin"));
+		if (dir === dirname(dir)) return [...dirs, process.env.PATH].join(delimiter);
+	}
+}
+/** Runs a framework command with the project's own binaries. */
+function run(command) {
+	exec(command, { env: {
+		...process.env,
+		PATH: binPath()
+	} });
+}
+/** Frameworks bootstrap with inline scripts; the CSP allows exactly those, by hash. */
+async function inlineScriptHashes() {
+	const hashes = /* @__PURE__ */ new Set();
+	for await (const file of glob("**/*.html", { cwd: web })) {
+		const html = await readFile(`${web}/${file}`, "utf8");
+		for (const [, body = ""] of html.matchAll(inlineScript)) hashes.add(`'sha256-${createHash("sha256").update(body).digest("base64")}'`);
+	}
+	return [...hashes];
+}
+/** Builds the page with the framework and copies it to `.quicklook/web`. */
+async function buildWeb() {
+	run(framework.build.command);
+	const outDir = resolve(root, framework.build.outDir);
+	for (const integration of config.integrations) await integration.hooks?.["build:done"]?.({
+		outDir,
+		config
+	});
+	await rm(web, {
+		recursive: true,
+		force: true
+	});
+	await cp(outDir, web, { recursive: true });
+}
+async function build() {
+	await buildWeb();
+	const csp = addSources(config.csp, "script-src", ...await inlineScriptHashes());
+	const spec = {
+		name: target,
+		options: {
+			deploymentTarget: { macOS },
+			createIntermediateGroups: true
+		},
+		settings: { base: {
+			SWIFT_VERSION: "6.0",
+			MARKETING_VERSION: process.env.VERSION?.replace(leadingV, "") ?? "1.0",
+			CURRENT_PROJECT_VERSION: "1",
+			CODE_SIGN_STYLE: "Manual",
+			CODE_SIGN_IDENTITY: "-"
+		} },
+		targets: {
+			[target]: {
+				type: "application",
+				platform: "macOS",
+				sources: [`${native}/App`, ...icon ? [{
+					path: resolve(root, icon),
+					buildPhase: "resources"
+				}] : []],
+				settings: {
+					PRODUCT_NAME: name,
+					PRODUCT_BUNDLE_IDENTIFIER: bundleId
+				},
+				dependencies: [{
+					target: `${target}Extension`,
+					embed: true,
+					codeSign: true
+				}],
+				info: {
+					path: `${work}/App/Info.plist`,
+					properties: {
+						CFBundleName: name,
+						...icon && { CFBundleIconFile: basename(icon, ".icns") },
+						LSMinimumSystemVersion: macOS,
+						UTExportedTypeDeclarations: types.filter((type) => typeof type !== "string").map((type) => ({
+							UTTypeIdentifier: type.id,
+							UTTypeDescription: type.description,
+							UTTypeConformsTo: type.conformsTo,
+							UTTypeTagSpecification: { "public.filename-extension": type.extensions }
+						}))
+					}
+				}
+			},
+			[`${target}Extension`]: {
+				type: "app-extension",
+				platform: "macOS",
+				sources: [`${native}/Extension`, {
+					path: web,
+					type: "folder",
+					buildPhase: "resources"
+				}],
+				settings: { PRODUCT_BUNDLE_IDENTIFIER: `${bundleId}.Extension` },
+				dependencies: [{ sdk: "QuickLookUI.framework" }, { sdk: "WebKit.framework" }],
+				entitlements: {
+					path: `${work}/Extension/Extension.entitlements`,
+					properties: {
+						"com.apple.security.app-sandbox": true,
+						"com.apple.security.files.user-selected.read-only": true,
+						"com.apple.security.network.client": true
+					}
+				},
+				info: {
+					path: `${work}/Extension/Info.plist`,
+					properties: {
+						CFBundleDisplayName: name,
+						QLWebContentSecurityPolicy: serializeCsp(csp),
+						QLMaxFileSize: config.maxFileSize,
+						NSExtension: {
+							NSExtensionPointIdentifier: "com.apple.quicklook.preview",
+							NSExtensionPrincipalClass: "PreviewViewController",
+							NSExtensionAttributes: {
+								QLSupportedContentTypes: types.map((type) => typeof type === "string" ? type : type.id),
+								QLSupportsSearchableItems: false
+							}
+						}
+					}
+				}
+			}
+		}
+	};
+	for (const integration of config.integrations) await integration.hooks?.["xcode:spec"]?.(spec, config);
+	await writeFile(`${work}/project.yml`, JSON.stringify(spec, null, 2));
+	exec([
+		"xcodegen",
+		"generate",
+		"--quiet",
+		"--spec",
+		`${work}/project.yml`,
+		"--project",
+		work
+	]);
+	exec([
+		"xcodebuild",
+		"-quiet",
+		"-project",
+		`${work}/${target}.xcodeproj`,
+		"-scheme",
+		target,
+		"-configuration",
+		"Release",
+		"-destination",
+		"generic/platform=macOS",
+		`CONFIGURATION_BUILD_DIR=${work}/build`,
+		"build"
+	]);
+	exec(["touch", built]);
+	console.log(`Built ${built}`);
+}
+switch (process.argv[2]) {
+	case "dev":
+		run(framework.build.dev);
+		break;
+	case "build:web":
+		await buildWeb();
+		break;
+	case "build":
+		await build();
+		break;
+	case "register":
+		if (!existsSync(built)) throw new Error(`No build at ${built}, run 'quicklook build' first.`);
+		await rm(installed, {
+			recursive: true,
+			force: true
+		});
+		exec([
+			"cp",
+			"-R",
+			built,
+			installed
+		]);
+		exec([
+			lsregister,
+			"-f",
+			"-R",
+			installed
+		]);
+		exec(["qlmanage", "-r"], {
+			quiet: true,
+			nothrow: true
+		});
+		exec([
+			"qlmanage",
+			"-r",
+			"cache"
+		], {
+			quiet: true,
+			nothrow: true
+		});
+		exec([
+			"open",
+			"-g",
+			installed
+		]);
+		console.log(`Installed ${installed}\nVerify with: pluginkit -mAv | grep ${bundleId}`);
+		break;
+	case "unregister":
+		exec([
+			lsregister,
+			"-u",
+			installed
+		], {
+			quiet: true,
+			nothrow: true
+		});
+		await rm(installed, {
+			recursive: true,
+			force: true
+		});
+		exec(["qlmanage", "-r"], {
+			quiet: true,
+			nothrow: true
+		});
+		console.log(`Removed ${installed}`);
+		break;
+	default: throw new Error("Usage: quicklook dev|build:web|build|register|unregister");
+}
+//#endregion
+export {};

package/dist/config-BQ-9qYNV.mjs

@@ -0,0 +1,113 @@
+import { join } from "node:path";
+import process from "node:process";
+import { loadConfig } from "c12";
+import { createJiti } from "jiti";
+//#region src/config.ts
+/** The previewed file is untrusted input; nothing on the page needs the network. */
+const defaultCsp = {
+	"default-src": ["'none'"],
+	"script-src": ["'self'"],
+	"style-src": ["'self'", "'unsafe-inline'"],
+	"img-src": [
+		"'self'",
+		"data:",
+		"blob:"
+	],
+	"font-src": ["'self'", "data:"],
+	"media-src": [
+		"'self'",
+		"data:",
+		"blob:"
+	]
+};
+const defineConfig = (config) => config;
+const serializeCsp = (csp) => Object.entries(csp).map(([directive, sources = []]) => [directive, ...sources].join(" ")).join("; ");
+/** `csp` with `sources` appended to `directive`. */
+const addSources = (csp, directive, ...sources) => ({
+	...csp,
+	[directive]: [...csp[directive] ?? [], ...sources]
+});
+/**
+* Built-in frameworks: their dev and build commands, and the default `outDir`
+* of a static, client-side build. Each takes `{ outDir }` to override it.
+*/
+const frameworkBuilds = {
+	analog: [
+		["vite", "dev"],
+		["vite", "build"],
+		"dist"
+	],
+	astro: [
+		["astro", "dev"],
+		["astro", "build"],
+		"dist"
+	],
+	nuxt: [
+		["nuxt", "dev"],
+		["nuxt", "generate"],
+		".output/public"
+	],
+	"solid-start": [
+		["vite", "dev"],
+		["vite", "build"],
+		".output/public"
+	],
+	sveltekit: [
+		["vite", "dev"],
+		["vite", "build"],
+		"build"
+	]
+};
+function builtinFramework(name, options) {
+	const builtin = frameworkBuilds[name];
+	if (!builtin) return;
+	const [dev, command, outDir] = builtin;
+	return {
+		name,
+		build: {
+			dev,
+			command,
+			outDir: options?.outDir ?? outDir
+		}
+	};
+}
+async function resolveIntegration(ref, root) {
+	if (typeof ref === "object" && !Array.isArray(ref)) return ref;
+	const [name, options] = typeof ref === "string" ? [ref] : ref;
+	const builtin = builtinFramework(name, options);
+	if (builtin) return builtin;
+	const exported = await createJiti(join(root, "quicklook.config")).import(name, { default: true });
+	return typeof exported === "function" ? exported(options) : exported;
+}
+async function loadConfig$1(root = process.cwd()) {
+	const { config } = await loadConfig({
+		name: "quicklook",
+		cwd: root
+	});
+	if (!config?.name) throw new Error(`No quicklook.config.* with a name found in ${root}`);
+	const { framework: frameworkRef, integrations: refs = [], ...rest } = config;
+	const framework = await resolveIntegration(frameworkRef, root);
+	if (!framework.build) throw new Error(`Framework "${framework.name}" doesn't say how to build the page`);
+	const integrations = [framework];
+	for (const ref of refs) integrations.push(await resolveIntegration(ref, root));
+	const resolved = {
+		macOS: "14.0",
+		maxFileSize: 1e7,
+		public: {},
+		...rest,
+		csp: {
+			...defaultCsp,
+			...config.csp
+		},
+		root,
+		framework: {
+			...framework,
+			build: framework.build
+		},
+		integrations
+	};
+	for (const integration of integrations) await integration.hooks?.["config:resolved"]?.(resolved);
+	return resolved;
+}
+//#endregion
+export { serializeCsp as a, loadConfig$1 as i, defaultCsp as n, defineConfig as r, addSources as t };

package/dist/config.d.mts

@@ -0,0 +1,80 @@
+import { Plugin } from "vite";
+//#region src/config.d.ts
+/** An existing type id such as "public.json", or a new type the app declares. */
+export type FileType = string | DeclaredType;
+/** A file type the app declares itself, as a UTExportedTypeDeclaration. */
+export interface DeclaredType {
+  id: string;
+  description: string;
+  extensions: string[];
+  conformsTo: string[];
+}
+/** CSP directives, e.g. `{ 'img-src': ["'self'", 'https:'] }`. */
+export type Csp = Partial<Record<string, string[]>>;
+/** The xcodegen project spec, written as project.yml. */
+export type XcodeSpec = Record<string, any>;
+export interface Integration {
+  name: string;
+  /** Set by frameworks only: how to run and build the page, and where it lands. */
+  build?: {
+    dev: string[];
+    command: string[];
+    outDir: string;
+  };
+  hooks?: {
+    'config:resolved'?: (config: ResolvedConfig) => void | Promise<void>;
+    /** Runs on the framework's static output, before it's bundled into the app. */
+    'build:done'?: (context: {
+      outDir: string;
+      config: ResolvedConfig;
+    }) => void | Promise<void>;
+    /** Edit the generated Xcode project: Info.plist keys, entitlements, targets. */
+    'xcode:spec'?: (spec: XcodeSpec, config: ResolvedConfig) => void | Promise<void>;
+    /** Vite plugins to add wherever the `quicklook()` Vite plugin is used. */
+    vite?: () => Plugin[];
+  };
+}
+/**
+ * A built-in framework or package name, the same with options, or an
+ * integration object. Names are imported from the project, so JSON and YAML
+ * configs can use third-party integrations too: the module's default export is
+ * either an integration or a function that takes the options and returns one.
+ */
+export type IntegrationRef = Integration | string | [name: string, options?: unknown];
+export interface QuickLookConfig {
+  /** App name, shown in Finder and System Settings. */
+  name: string;
+  bundleId: string;
+  /** Path to the app's .icns icon, relative to the project root. */
+  icon?: string;
+  /** Minimum macOS version. Defaults to 14.0. */
+  macOS?: string;
+  types: FileType[];
+  /** `sveltekit`, `astro`, `solid-start`, `nuxt`, `analog`, or any integration that sets `build`. */
+  framework: IntegrationRef;
+  integrations?: IntegrationRef[];
+  /** Directives given here replace the defaults of the same name. */
+  csp?: Csp;
+  /** Larger files get QuickLook's generic preview. Defaults to 10 MB. */
+  maxFileSize?: number;
+  /** Exposed to the page as `config.public` from `virtual:quicklook`. */
+  public?: Record<string, unknown>;
+}
+/** What the page sees as `config` from `virtual:quicklook`. */
+export type PageConfig = Pick<ResolvedConfig, 'name' | 'bundleId' | 'types' | 'public'>;
+export interface ResolvedConfig extends Required<Omit<QuickLookConfig, 'framework' | 'integrations' | 'icon'>>, Pick<QuickLookConfig, 'icon'> {
+  root: string;
+  framework: Integration & {
+    build: NonNullable<Integration['build']>;
+  };
+  /** The framework first, then the configured integrations, in order. */
+  integrations: Integration[];
+}
+/** The previewed file is untrusted input; nothing on the page needs the network. */
+export declare const defaultCsp: Csp;
+export declare const defineConfig: (config: QuickLookConfig) => QuickLookConfig;
+export declare const serializeCsp: (csp: Csp) => string;
+/** `csp` with `sources` appended to `directive`. */
+export declare const addSources: (csp: Csp, directive: string, ...sources: string[]) => Csp;
+export declare function loadConfig(root?: string): Promise<ResolvedConfig>;
+//#endregion

package/dist/config.mjs

@@ -0,0 +1 @@
+export { t as addSources, n as defaultCsp, r as defineConfig, i as loadConfig, a as serializeCsp } from "./config-BQ-9qYNV.mjs";

package/dist/runtime.d.mts

@@ -0,0 +1,23 @@
+//#region src/runtime.d.ts
+/** The file QuickLook asked to preview. */
+export interface QuickLookFile {
+  name: string;
+  /** Lowercase, without the dot. */
+  extension: string;
+  bytes: Uint8Array;
+}
+declare global {
+  interface Window {
+    /** Injected by the extension before the page loads. See native/Extension/PreviewViewController.swift. */
+    quicklook?: {
+      name: string;
+      extension: string;
+      base64: string;
+    };
+  }
+}
+/** The previewed file inside QuickLook; `undefined` in the browser. */
+export declare function nativeFile(): QuickLookFile | undefined;
+/** The same shape from a file picked or dropped in the browser, for the dev server. */
+export declare function browserFile(file: File): Promise<QuickLookFile>;
+//#endregion

package/dist/runtime.mjs

@@ -0,0 +1,21 @@
+//#region src/runtime.ts
+/** The previewed file inside QuickLook; `undefined` in the browser. */
+function nativeFile() {
+	const injected = window.quicklook;
+	if (!injected) return;
+	return {
+		name: injected.name,
+		extension: injected.extension,
+		bytes: Uint8Array.from(atob(injected.base64), (c) => c.charCodeAt(0))
+	};
+}
+/** The same shape from a file picked or dropped in the browser, for the dev server. */
+async function browserFile(file) {
+	return {
+		name: file.name,
+		extension: file.name.includes(".") ? (file.name.split(".").pop() ?? "").toLowerCase() : "",
+		bytes: new Uint8Array(await file.arrayBuffer())
+	};
+}
+//#endregion
+export { browserFile, nativeFile };

package/dist/vite.d.mts

@@ -0,0 +1,8 @@
+import { Plugin } from "vite";
+//#region src/vite.d.ts
+/**
+ * Provides `virtual:quicklook`, adds the integrations' Vite plugins, and makes
+ * the dev server report what the extension's CSP would block.
+ */
+export declare function quicklook(): Promise<Plugin[]>;
+//#endregion

package/dist/vite.mjs

@@ -0,0 +1,33 @@
+import { a as serializeCsp, i as loadConfig, t as addSources } from "./config-BQ-9qYNV.mjs";
+//#region src/vite.ts
+const virtualId = "virtual:quicklook";
+/**
+* Provides `virtual:quicklook`, adds the integrations' Vite plugins, and makes
+* the dev server report what the extension's CSP would block.
+*/
+async function quicklook() {
+	const config = await loadConfig();
+	const { name, bundleId, types } = config;
+	const pageConfig = {
+		name,
+		bundleId,
+		types,
+		public: config.public
+	};
+	const virtualSource = `export const config = ${JSON.stringify(pageConfig)};
+export { browserFile, nativeFile } from 'quicklook-kit/runtime';`;
+	const devCsp = serializeCsp(addSources(addSources(config.csp, "script-src", "'unsafe-inline'"), "connect-src", "'self'", "ws:"));
+	return [{
+		name: "quicklook",
+		resolveId: (source) => source === virtualId ? `\0${virtualId}` : void 0,
+		load: (source) => source === `\0${virtualId}` ? virtualSource : void 0,
+		configureServer(server) {
+			server.middlewares.use((_request, response, next) => {
+				response.setHeader("Content-Security-Policy-Report-Only", devCsp);
+				next();
+			});
+		}
+	}, ...config.integrations.flatMap((integration) => integration.hooks?.vite?.() ?? [])];
+}
+//#endregion
+export { quicklook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quicklook-kit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Build macOS QuickLook previews with any Vite-based web framework",
   "license": "MIT",
   "keywords": [
@@ -18,22 +18,40 @@
   ],
   "type": "module",
   "bin": {
-    "quicklook": "./src/cli.ts"
+    "quicklook": "./dist/cli.mjs"
   },
   "exports": {
-    ".": "./src/config.ts",
-    "./vite": "./src/vite.ts",
-    "./runtime": "./src/runtime.ts",
+    ".": {
+      "types": "./dist/config.d.mts",
+      "default": "./dist/config.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "default": "./dist/vite.mjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.mts",
+      "default": "./dist/runtime.mjs"
+    },
     "./virtual": {
       "types": "./src/virtual.d.ts"
     }
   },
+  "files": [
+    "dist",
+    "native",
+    "src/virtual.d.ts"
+  ],
+  "engines": {
+    "node": ">=22.17"
+  },
   "dependencies": {
     "c12": "3.3.4",
     "jiti": "2.7.0"
   },
   "devDependencies": {
-    "@types/bun": "1.3.9",
+    "@types/node": "24.19.2",
+    "tsdown": "0.23.0",
     "typescript": "6.0.3",
     "vite": "8.3.0"
   },
@@ -41,6 +59,7 @@
     "vite": ">=7"
   },
   "scripts": {
+    "build": "tsdown",
     "check": "tsc --noEmit"
   }
 }

package/src/virtual.d.ts

@@ -2,6 +2,6 @@
 // with `/// <reference types="quicklook-kit/virtual" />`.
 declare module 'virtual:quicklook' {
 	/** Build-time values from quicklook.config.*. */
-	export const config: import('./config.ts').PageConfig;
+	export const config: import('quicklook-kit').PageConfig;
 	export { browserFile, nativeFile, type QuickLookFile } from 'quicklook-kit/runtime';
 }

package/src/cli.ts

@@ -1,204 +0,0 @@
-#!/usr/bin/env bun
-// Builds the page with the configured framework, wraps it in a QuickLook
-// extension, and installs it. Usage: quicklook dev|build:web|build|register|unregister
-import { createHash } from 'node:crypto';
-import { existsSync } from 'node:fs';
-import { cp, rm } from 'node:fs/promises';
-import { basename, resolve } from 'node:path';
-import process from 'node:process';
-import { fileURLToPath } from 'node:url';
-import { $, Glob } from 'bun';
-import {
-	addSources,
-	type DeclaredType,
-	loadConfig,
-	serializeCsp,
-	type XcodeSpec,
-} from './config.ts';
-
-const config = await loadConfig();
-const { root, name, bundleId, macOS, types, framework, icon } = config;
-const target = name.replace(/[^A-Za-z0-9]/g, '');
-// Everything generated lives here, away from the framework's own output.
-const work = `${root}/.quicklook`;
-const web = `${work}/web`;
-const built = `${work}/build/${name}.app`;
-const installed = `/Applications/${name}.app`;
-const native = fileURLToPath(new URL('../native', import.meta.url));
-const lsregister =
-	'/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister';
-
-const leadingV = /^v/;
-const inlineScript = /<script\b(?![^>]*\ssrc=)[^>]*>([\s\S]*?)<\/script>/gi;
-
-/** Runs a framework command with the project's own binaries. */
-async function run(command: string[]) {
-	const child = Bun.spawn(['bun', 'run', ...command], {
-		cwd: root,
-		stdio: ['inherit', 'inherit', 'inherit'],
-	});
-	const code = await child.exited;
-	if (code !== 0) {
-		process.exit(code);
-	}
-}
-
-/** Frameworks bootstrap with inline scripts; the CSP allows exactly those, by hash. */
-async function inlineScriptHashes() {
-	const hashes = new Set<string>();
-	for await (const file of new Glob('**/*.html').scan(web)) {
-		const html = await Bun.file(`${web}/${file}`).text();
-		for (const [, body = ''] of html.matchAll(inlineScript)) {
-			hashes.add(`'sha256-${createHash('sha256').update(body).digest('base64')}'`);
-		}
-	}
-	return [...hashes];
-}
-
-/** Builds the page with the framework and copies it to `.quicklook/web`. */
-async function buildWeb() {
-	await run(framework.build.command);
-	const outDir = resolve(root, framework.build.outDir);
-	for (const integration of config.integrations) {
-		await integration.hooks?.['build:done']?.({ outDir, config });
-	}
-	// Copied so the bundle's folder is always named `web`, whatever the framework calls it.
-	await rm(web, { recursive: true, force: true });
-	await cp(outDir, web, { recursive: true });
-}
-
-async function build() {
-	await buildWeb();
-
-	const csp = addSources(config.csp, 'script-src', ...(await inlineScriptHashes()));
-	const spec: XcodeSpec = {
-		name: target,
-		options: { deploymentTarget: { macOS }, createIntermediateGroups: true },
-		settings: {
-			base: {
-				SWIFT_VERSION: '6.0',
-				MARKETING_VERSION: process.env.VERSION?.replace(leadingV, '') ?? '1.0',
-				CURRENT_PROJECT_VERSION: '1',
-				// Ad-hoc signing: enough for QuickLook to load it, no Apple Developer account needed.
-				CODE_SIGN_STYLE: 'Manual',
-				CODE_SIGN_IDENTITY: '-',
-			},
-		},
-		targets: {
-			[target]: {
-				type: 'application',
-				platform: 'macOS',
-				sources: [
-					`${native}/App`,
-					...(icon ? [{ path: resolve(root, icon), buildPhase: 'resources' }] : []),
-				],
-				settings: { PRODUCT_NAME: name, PRODUCT_BUNDLE_IDENTIFIER: bundleId },
-				dependencies: [{ target: `${target}Extension`, embed: true, codeSign: true }],
-				info: {
-					path: `${work}/App/Info.plist`,
-					properties: {
-						CFBundleName: name,
-						...(icon && { CFBundleIconFile: basename(icon, '.icns') }),
-						LSMinimumSystemVersion: macOS,
-						UTExportedTypeDeclarations: types
-							.filter((type): type is DeclaredType => typeof type !== 'string')
-							.map((type) => ({
-								UTTypeIdentifier: type.id,
-								UTTypeDescription: type.description,
-								UTTypeConformsTo: type.conformsTo,
-								UTTypeTagSpecification: { 'public.filename-extension': type.extensions },
-							})),
-					},
-				},
-			},
-			[`${target}Extension`]: {
-				type: 'app-extension',
-				platform: 'macOS',
-				sources: [`${native}/Extension`, { path: web, type: 'folder', buildPhase: 'resources' }],
-				// macOS silently ignores an extension whose bundle id isn't prefixed by its app's.
-				settings: { PRODUCT_BUNDLE_IDENTIFIER: `${bundleId}.Extension` },
-				dependencies: [{ sdk: 'QuickLookUI.framework' }, { sdk: 'WebKit.framework' }],
-				entitlements: {
-					path: `${work}/Extension/Extension.entitlements`,
-					properties: {
-						'com.apple.security.app-sandbox': true,
-						'com.apple.security.files.user-selected.read-only': true,
-						// WKWebView's content process won't launch in a sandbox without this,
-						// even for a page that loads nothing. The page's CSP blocks all requests.
-						'com.apple.security.network.client': true,
-					},
-				},
-				info: {
-					path: `${work}/Extension/Info.plist`,
-					properties: {
-						CFBundleDisplayName: name,
-						// Read by PreviewViewController.swift.
-						QLWebContentSecurityPolicy: serializeCsp(csp),
-						QLMaxFileSize: config.maxFileSize,
-						NSExtension: {
-							NSExtensionPointIdentifier: 'com.apple.quicklook.preview',
-							NSExtensionPrincipalClass: 'PreviewViewController',
-							NSExtensionAttributes: {
-								QLSupportedContentTypes: types.map((type) =>
-									typeof type === 'string' ? type : type.id,
-								),
-								QLSupportsSearchableItems: false,
-							},
-						},
-					},
-				},
-			},
-		},
-	};
-	for (const integration of config.integrations) {
-		await integration.hooks?.['xcode:spec']?.(spec, config);
-	}
-
-	// JSON is valid YAML.
-	await Bun.write(`${work}/project.yml`, JSON.stringify(spec, null, 2));
-	await $`xcodegen generate --quiet --spec ${work}/project.yml --project ${work}`;
-	await $`xcodebuild -quiet -project ${work}/${target}.xcodeproj -scheme ${target} -configuration Release -destination generic/platform=macOS CONFIGURATION_BUILD_DIR=${work}/build build`;
-	// Finder keys its icon cache on the bundle's mtime, which xcodebuild leaves alone.
-	await $`touch ${built}`;
-	console.log(`Built ${built}`);
-}
-
-switch (process.argv[2]) {
-	case 'dev':
-		await run(framework.build.dev);
-		break;
-
-	case 'build:web':
-		await buildWeb();
-		break;
-
-	case 'build':
-		await build();
-		break;
-
-	// macOS only loads extensions from apps in a standard location, and caches
-	// registrations aggressively, including for apps since renamed or deleted.
-	case 'register':
-		if (!existsSync(built)) {
-			throw new Error(`No build at ${built}, run 'quicklook build' first.`);
-		}
-		await $`rm -rf ${installed}`;
-		await $`cp -R ${built} ${installed}`;
-		await $`${lsregister} -f -R ${installed}`;
-		await $`qlmanage -r`.quiet().nothrow();
-		await $`qlmanage -r cache`.quiet().nothrow();
-		// Launching the app is what registers its embedded extension.
-		await $`open -g ${installed}`;
-		console.log(`Installed ${installed}\nVerify with: pluginkit -mAv | grep ${bundleId}`);
-		break;
-
-	case 'unregister':
-		await $`${lsregister} -u ${installed}`.quiet().nothrow();
-		await $`rm -rf ${installed}`;
-		await $`qlmanage -r`.quiet().nothrow();
-		console.log(`Removed ${installed}`);
-		break;
-
-	default:
-		throw new Error('Usage: quicklook dev|build:web|build|register|unregister');
-}

package/src/config.ts

@@ -1,179 +0,0 @@
-// Loads quicklook.config.* (any format c12 reads: ts, js, json, yaml, toml…)
-// and resolves its framework and integrations.
-
-import { join } from 'node:path';
-import process from 'node:process';
-import { loadConfig as loadC12 } from 'c12';
-import { createJiti } from 'jiti';
-import type { Plugin } from 'vite';
-
-/** An existing type id such as "public.json", or a new type the app declares. */
-export type FileType = string | DeclaredType;
-
-/** A file type the app declares itself, as a UTExportedTypeDeclaration. */
-export interface DeclaredType {
-	id: string;
-	description: string;
-	extensions: string[];
-	conformsTo: string[];
-}
-
-/** CSP directives, e.g. `{ 'img-src': ["'self'", 'https:'] }`. */
-export type Csp = Partial<Record<string, string[]>>;
-
-/** The xcodegen project spec, written as project.yml. */
-// biome-ignore lint/suspicious/noExplicitAny: hooks edit arbitrary xcodegen keys.
-export type XcodeSpec = Record<string, any>;
-
-export interface Integration {
-	name: string;
-	/** Set by frameworks only: how to run and build the page, and where it lands. */
-	build?: { dev: string[]; command: string[]; outDir: string };
-	hooks?: {
-		'config:resolved'?: (config: ResolvedConfig) => void | Promise<void>;
-		/** Runs on the framework's static output, before it's bundled into the app. */
-		'build:done'?: (context: { outDir: string; config: ResolvedConfig }) => void | Promise<void>;
-		/** Edit the generated Xcode project: Info.plist keys, entitlements, targets. */
-		'xcode:spec'?: (spec: XcodeSpec, config: ResolvedConfig) => void | Promise<void>;
-		/** Vite plugins to add wherever the `quicklook()` Vite plugin is used. */
-		vite?: () => Plugin[];
-	};
-}
-
-/**
- * A built-in framework or package name, the same with options, or an
- * integration object. Names are imported from the project, so JSON and YAML
- * configs can use third-party integrations too: the module's default export is
- * either an integration or a function that takes the options and returns one.
- */
-export type IntegrationRef = Integration | string | [name: string, options?: unknown];
-
-export interface QuickLookConfig {
-	/** App name, shown in Finder and System Settings. */
-	name: string;
-	bundleId: string;
-	/** Path to the app's .icns icon, relative to the project root. */
-	icon?: string;
-	/** Minimum macOS version. Defaults to 14.0. */
-	macOS?: string;
-	types: FileType[];
-	/** `sveltekit`, `astro`, `solid-start`, `nuxt`, `analog`, or any integration that sets `build`. */
-	framework: IntegrationRef;
-	integrations?: IntegrationRef[];
-	/** Directives given here replace the defaults of the same name. */
-	csp?: Csp;
-	/** Larger files get QuickLook's generic preview. Defaults to 10 MB. */
-	maxFileSize?: number;
-	/** Exposed to the page as `config.public` from `virtual:quicklook`. */
-	public?: Record<string, unknown>;
-}
-
-/** What the page sees as `config` from `virtual:quicklook`. */
-export type PageConfig = Pick<ResolvedConfig, 'name' | 'bundleId' | 'types' | 'public'>;
-
-export interface ResolvedConfig
-	extends Required<Omit<QuickLookConfig, 'framework' | 'integrations' | 'icon'>>,
-		Pick<QuickLookConfig, 'icon'> {
-	root: string;
-	framework: Integration & { build: NonNullable<Integration['build']> };
-	/** The framework first, then the configured integrations, in order. */
-	integrations: Integration[];
-}
-
-/** The previewed file is untrusted input; nothing on the page needs the network. */
-export const defaultCsp: Csp = {
-	'default-src': ["'none'"],
-	'script-src': ["'self'"],
-	'style-src': ["'self'", "'unsafe-inline'"],
-	'img-src': ["'self'", 'data:', 'blob:'],
-	'font-src': ["'self'", 'data:'],
-	'media-src': ["'self'", 'data:', 'blob:'],
-};
-
-export const defineConfig = (config: QuickLookConfig) => config;
-
-export const serializeCsp = (csp: Csp) =>
-	Object.entries(csp)
-		.map(([directive, sources = []]) => [directive, ...sources].join(' '))
-		.join('; ');
-
-/** `csp` with `sources` appended to `directive`. */
-export const addSources = (csp: Csp, directive: string, ...sources: string[]): Csp => ({
-	...csp,
-	[directive]: [...(csp[directive] ?? []), ...sources],
-});
-
-/**
- * Built-in frameworks: their dev and build commands, and the default `outDir`
- * of a static, client-side build. Each takes `{ outDir }` to override it.
- */
-const frameworkBuilds: Record<string, [dev: string[], command: string[], outDir: string]> = {
-	// @analogjs/vite-plugin-angular, writing Vite's default `dist`.
-	analog: [['vite', 'dev'], ['vite', 'build'], 'dist'],
-	// Astro's default `output: 'static'`.
-	astro: [['astro', 'dev'], ['astro', 'build'], 'dist'],
-	// `ssr: false`; `nuxt generate` writes `.output/public`.
-	nuxt: [['nuxt', 'dev'], ['nuxt', 'generate'], '.output/public'],
-	// `solidStart({ ssr: false })` and Nitro's static preset prerendering `/`.
-	'solid-start': [['vite', 'dev'], ['vite', 'build'], '.output/public'],
-	// @sveltejs/adapter-static, writing `build`.
-	sveltekit: [['vite', 'dev'], ['vite', 'build'], 'build'],
-};
-
-function builtinFramework(name: string, options?: unknown): Integration | undefined {
-	const builtin = frameworkBuilds[name];
-	if (!builtin) {
-		return;
-	}
-	const [dev, command, outDir] = builtin;
-	return {
-		name,
-		build: { dev, command, outDir: (options as { outDir?: string } | undefined)?.outDir ?? outDir },
-	};
-}
-
-async function resolveIntegration(ref: IntegrationRef, root: string): Promise<Integration> {
-	if (typeof ref === 'object' && !Array.isArray(ref)) {
-		return ref;
-	}
-	const [name, options] = typeof ref === 'string' ? [ref] : ref;
-	const builtin = builtinFramework(name, options);
-	if (builtin) {
-		return builtin;
-	}
-	const exported = await createJiti(join(root, 'quicklook.config')).import<
-		Integration | ((options?: unknown) => Integration)
-	>(name, { default: true });
-	return typeof exported === 'function' ? exported(options) : exported;
-}
-
-export async function loadConfig(root = process.cwd()): Promise<ResolvedConfig> {
-	const { config } = await loadC12<QuickLookConfig>({ name: 'quicklook', cwd: root });
-	if (!config?.name) {
-		throw new Error(`No quicklook.config.* with a name found in ${root}`);
-	}
-	const { framework: frameworkRef, integrations: refs = [], ...rest } = config;
-	const framework = await resolveIntegration(frameworkRef, root);
-	if (!framework.build) {
-		throw new Error(`Framework "${framework.name}" doesn't say how to build the page`);
-	}
-	const integrations = [framework];
-	for (const ref of refs) {
-		integrations.push(await resolveIntegration(ref, root));
-	}
-
-	const resolved: ResolvedConfig = {
-		macOS: '14.0',
-		maxFileSize: 10_000_000,
-		public: {},
-		...rest,
-		csp: { ...defaultCsp, ...config.csp },
-		root,
-		framework: { ...framework, build: framework.build },
-		integrations,
-	};
-	for (const integration of integrations) {
-		await integration.hooks?.['config:resolved']?.(resolved);
-	}
-	return resolved;
-}

package/src/runtime.ts

@@ -1,36 +0,0 @@
-/** The file QuickLook asked to preview. */
-export interface QuickLookFile {
-	name: string;
-	/** Lowercase, without the dot. */
-	extension: string;
-	bytes: Uint8Array;
-}
-
-declare global {
-	interface Window {
-		/** Injected by the extension before the page loads. See native/Extension/PreviewViewController.swift. */
-		quicklook?: { name: string; extension: string; base64: string };
-	}
-}
-
-/** The previewed file inside QuickLook; `undefined` in the browser. */
-export function nativeFile(): QuickLookFile | undefined {
-	const injected = window.quicklook;
-	if (!injected) {
-		return;
-	}
-	return {
-		name: injected.name,
-		extension: injected.extension,
-		bytes: Uint8Array.from(atob(injected.base64), (c) => c.charCodeAt(0)),
-	};
-}
-
-/** The same shape from a file picked or dropped in the browser, for the dev server. */
-export async function browserFile(file: File): Promise<QuickLookFile> {
-	return {
-		name: file.name,
-		extension: file.name.includes('.') ? (file.name.split('.').pop() ?? '').toLowerCase() : '',
-		bytes: new Uint8Array(await file.arrayBuffer()),
-	};
-}

package/src/vite.ts

@@ -1,41 +0,0 @@
-import type { Plugin } from 'vite';
-import { addSources, loadConfig, type PageConfig, serializeCsp } from './config.ts';
-
-const virtualId = 'virtual:quicklook';
-
-/**
- * Provides `virtual:quicklook`, adds the integrations' Vite plugins, and makes
- * the dev server report what the extension's CSP would block.
- */
-export async function quicklook(): Promise<Plugin[]> {
-	const config = await loadConfig();
-	const { name, bundleId, types } = config;
-	const pageConfig: PageConfig = { name, bundleId, types, public: config.public };
-	const virtualSource = `export const config = ${JSON.stringify(pageConfig)};
-export { browserFile, nativeFile } from 'quicklook-kit/runtime';`;
-	// Report-only, so violations show in the console without breaking HMR. Inline
-	// scripts are only hashed at build time, and the dev server needs its socket.
-	const devCsp = serializeCsp(
-		addSources(
-			addSources(config.csp, 'script-src', "'unsafe-inline'"),
-			'connect-src',
-			"'self'",
-			'ws:',
-		),
-	);
-
-	return [
-		{
-			name: 'quicklook',
-			resolveId: (source) => (source === virtualId ? `\0${virtualId}` : undefined),
-			load: (source) => (source === `\0${virtualId}` ? virtualSource : undefined),
-			configureServer(server) {
-				server.middlewares.use((_request, response, next) => {
-					response.setHeader('Content-Security-Policy-Report-Only', devCsp);
-					next();
-				});
-			},
-		},
-		...config.integrations.flatMap((integration) => integration.hooks?.vite?.() ?? []),
-	];
-}

package/tsconfig.json

@@ -1,16 +0,0 @@
-{
-	"compilerOptions": {
-		"target": "es2023",
-		"module": "preserve",
-		"moduleResolution": "bundler",
-		"lib": ["es2023", "dom"],
-		"types": ["bun"],
-		"strict": true,
-		"noUncheckedIndexedAccess": true,
-		"noEmit": true,
-		"allowImportingTsExtensions": true,
-		"verbatimModuleSyntax": true,
-		"skipLibCheck": true
-	},
-	"include": ["src"]
-}