quicklook-kit 0.0.0-stage → 0.1.1

package/native/App/HostApp.swift

@@ -0,0 +1,21 @@
+import SwiftUI
+
+/// QuickLook extensions have to ship inside an app, and macOS registers them
+/// when that app is first launched. This is all the app does.
+@main
+struct HostApp: App {
+  private let name = Bundle.main.object(forInfoDictionaryKey: "CFBundleName") as? String ?? ""
+
+  var body: some Scene {
+    Window(name, id: "main") {
+      VStack(spacing: 8) {
+        Text(name).font(.headline)
+        Text("The QuickLook preview is installed. You can close this window.")
+          .foregroundStyle(.secondary)
+      }
+      .padding(32)
+      .fixedSize()
+    }
+    .windowResizability(.contentSize)
+  }
+}

package/native/Extension/PreviewViewController.swift

@@ -0,0 +1,124 @@
+import QuickLookUI
+import UniformTypeIdentifiers
+import WebKit
+
+/// Loads the bundled page over `quicklook://app/` and hands it the previewed
+/// file as `window.quicklook`. See packages/quicklook-kit/src/runtime.ts.
+@objc(PreviewViewController)
+final class PreviewViewController: NSViewController, QLPreviewingController {
+  /// Larger files throw, which makes QuickLook fall back to its generic preview
+  /// instead of stalling while megabytes of base64 cross into the page.
+  private static let maxFileSize =
+    Bundle.main.object(forInfoDictionaryKey: "QLMaxFileSize") as? Int ?? 10_000_000
+
+  private let loadWaiter = LoadWaiter()
+
+  private lazy var webView: WKWebView = {
+    let configuration = WKWebViewConfiguration()
+    configuration.setURLSchemeHandler(BundleSchemeHandler(), forURLScheme: "quicklook")
+    let webView = WKWebView(frame: .zero, configuration: configuration)
+    webView.navigationDelegate = loadWaiter
+    return webView
+  }()
+
+  override func loadView() {
+    view = webView
+  }
+
+  func preparePreviewOfFile(at url: URL) async throws {
+    let size = try url.resourceValues(forKeys: [.fileSizeKey]).fileSize ?? 0
+    guard size <= Self.maxFileSize else { throw CocoaError(.fileReadTooLarge) }
+
+    let file = [
+      "name": url.lastPathComponent,
+      "extension": url.pathExtension.lowercased(),
+      "base64": try Data(contentsOf: url).base64EncodedString(),
+    ]
+    // JSON is a valid JavaScript expression, so this needs no escaping of its own.
+    let json = String(decoding: try JSONSerialization.data(withJSONObject: file), as: UTF8.self)
+    let scripts = webView.configuration.userContentController
+    scripts.removeAllUserScripts()
+    scripts.addUserScript(
+      WKUserScript(
+        source: "window.quicklook = \(json);", injectionTime: .atDocumentStart,
+        forMainFrameOnly: true))
+
+    // QuickLook displays the view as soon as this returns, so wait for the
+    // page to actually finish loading — otherwise larger files show blank.
+    let page = URLRequest(url: URL(string: "quicklook://app/")!)
+    try await loadWaiter.load { webView.load(page) }
+  }
+}
+
+/// Serves the bundled `web` folder. A real origin, unlike file://, lets any
+/// framework's build load its ES modules and chunks as `'self'`, and every
+/// response carries the CSP the build wrote into Info.plist.
+private final class BundleSchemeHandler: NSObject, WKURLSchemeHandler {
+  private let root = Bundle.main.resourceURL!.appendingPathComponent("web").standardizedFileURL
+  private let csp =
+    Bundle.main.object(forInfoDictionaryKey: "QLWebContentSecurityPolicy") as? String
+    ?? "default-src 'none'"
+
+  func webView(_ webView: WKWebView, start task: any WKURLSchemeTask) {
+    guard let url = task.request.url else {
+      task.didFailWithError(URLError(.badURL))
+      return
+    }
+    var path = url.path(percentEncoded: false)
+    if path.isEmpty || path.hasSuffix("/") { path += "index.html" }
+    let file = root.appendingPathComponent(path).standardizedFileURL
+    // `..%2f` arrives decoded as a real `..`; never serve anything outside web/.
+    let data = file.path.hasPrefix(root.path + "/") ? try? Data(contentsOf: file) : nil
+    let type =
+      UTType(filenameExtension: file.pathExtension)?.preferredMIMEType ?? "application/octet-stream"
+    let response = HTTPURLResponse(
+      url: url, statusCode: data == nil ? 404 : 200, httpVersion: "HTTP/1.1",
+      headerFields: ["Content-Type": type, "Content-Security-Policy": csp])!
+    task.didReceive(response)
+    task.didReceive(data ?? Data())
+    task.didFinish()
+  }
+
+  func webView(_ webView: WKWebView, stop task: any WKURLSchemeTask) {}
+}
+
+/// Bridges `WKNavigationDelegate` callbacks back to `async`.
+@MainActor
+private final class LoadWaiter: NSObject, WKNavigationDelegate {
+  private var continuation: CheckedContinuation<Void, Error>?
+
+  func load(_ start: () -> Void) async throws {
+    try await withCheckedThrowingContinuation { continuation in
+      self.continuation = continuation
+      start()
+    }
+  }
+
+  private func finish(_ result: Result<Void, Error>) {
+    continuation?.resume(with: result)
+    continuation = nil
+  }
+
+  func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+    finish(.success(()))
+  }
+
+  func webView(
+    _ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error
+  ) {
+    finish(.failure(error))
+  }
+
+  func webView(
+    _ webView: WKWebView, didFailProvisionalNavigation navigation: WKNavigation!,
+    withError error: Error
+  ) {
+    finish(.failure(error))
+  }
+
+  /// A crashed content process fires no navigation callback at all — without
+  /// this the await never returns and QuickLook spins forever.
+  func webViewWebContentProcessDidTerminate(_ webView: WKWebView) {
+    finish(.failure(CocoaError(.featureUnsupported)))
+  }
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "quicklook-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Build macOS QuickLook previews with any Vite-based web framework",
+  "license": "MIT",
+  "keywords": [
+    "quicklook",
+    "quicklook-plugin",
+    "sveltekit",
+    "svelte",
+    "astro",
+    "solid",
+    "solid-start",
+    "vue",
+    "nuxt",
+    "angular",
+    "analog"
+  ],
+  "type": "module",
+  "bin": {
+    "quicklook": "./src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/config.ts",
+    "./vite": "./src/vite.ts",
+    "./runtime": "./src/runtime.ts",
+    "./virtual": {
+      "types": "./src/virtual.d.ts"
+    }
+  },
+  "dependencies": {
+    "c12": "3.3.4",
+    "jiti": "2.7.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.9",
+    "typescript": "6.0.3",
+    "vite": "8.3.0"
+  },
+  "peerDependencies": {
+    "vite": ">=7"
+  },
+  "scripts": {
+    "check": "tsc --noEmit"
+  }
 }

package/readme.markdown

@@ -0,0 +1,200 @@
+# quicklook-kit
+
+![License](https://img.shields.io/npm/l/quicklook-kit?style=for-the-badge)
+[![Version](https://img.shields.io/npm/v/quicklook-kit?style=for-the-badge)](https://www.npmjs.org/package/quicklook-kit)
+[![Build](https://img.shields.io/github/actions/workflow/status/idleberg/quicklook-kit/ci.yml?style=for-the-badge)](https://github.com/idleberg/quicklook-kit/actions)
+
+> Build macOS QuickLook previews with any Vite-based web framework, no Swift required
+
+Your preview is a web page. quicklook-kit builds it with your framework, wraps it in a small native QuickLook extension and installs the resulting app. You never touch Swift or Xcode.
+
+Built-in support for SvelteKit, Astro, SolidStart, Nuxt and Analog. Any other framework that builds with Vite and writes a static `index.html` works through an integration.
+
+## Requirements
+
+- 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
+
+## Installation
+
+```sh
+bun add --dev quicklook-kit
+```
+
+To start from scratch, use one of the [templates](https://github.com/idleberg/quicklook-kit/tree/main/templates) instead.
+
+## Setup
+
+### 1. Configure
+
+Create `quicklook.config.ts` in your project root:
+
+```ts
+import { defineConfig } from "quicklook-kit";
+
+export default defineConfig({
+  name: "Example Preview",
+  bundleId: "com.example.ExamplePreview",
+  types: [
+    {
+      id: "com.example.ExamplePreview.example",
+      description: "Example File",
+      extensions: ["example"],
+      conformsTo: ["public.plain-text"],
+    },
+  ],
+  framework: "sveltekit",
+});
+```
+
+A new type conforms to `public.plain-text` for text formats, or `public.data` for binary ones. To preview a type macOS already knows about, use a plain string like `'public.json'` in place of an object.
+
+The config can also be `quicklook.config.js`, `.json`, `.yaml` or `.toml`, or a `.quicklookrc`. The keys are the same in every format.
+
+| Key            | Default      |                                                                                    |
+| -------------- | ------------ | ---------------------------------------------------------------------------------- |
+| `name`         | required     | App name, shown in Finder and System Settings                                      |
+| `bundleId`     | required     | The extension gets `<bundleId>.Extension`                                          |
+| `types`        | required     | File types to preview                                                              |
+| `framework`    | required     | `'sveltekit'`, `'astro'`, `'solid-start'`, `'nuxt'`, `'analog'`, or an integration |
+| `macOS`        | `'14.0'`     | Minimum macOS version                                                              |
+| `integrations` | `[]`         | See [Integrations](#integrations)                                                  |
+| `csp`          | locked down  | Directives here replace the defaults of the same name                              |
+| `maxFileSize`  | `10_000_000` | Larger files get QuickLook's generic preview                                       |
+| `public`       | `{}`         | Values the page can read at build time                                             |
+
+A framework can take options as a `[name, options]` pair, e.g. `['sveltekit', { outDir: 'dist' }]` when your adapter writes somewhere other than the default.
+
+Each framework needs a static, client-side build:
+
+| Framework  | Requirement                                            |
+| ---------- | ------------------------------------------------------ |
+| Analog     | `@analogjs/vite-plugin-angular`                        |
+| Astro      | the default `output: 'static'`                         |
+| Nuxt       | `ssr: false`                                           |
+| SolidStart | `ssr: false`, Nitro's `static` preset prerendering `/` |
+| SvelteKit  | `@sveltejs/adapter-static`                             |
+
+### 2. Add the Vite plugin
+
+```ts
+import { quicklook } from "quicklook-kit/vite";
+
+// in the framework's Vite config
+plugins: [quicklook()];
+```
+
+For TypeScript, add the types of the virtual module, either in a `.d.ts` file:
+
+```ts
+/// <reference types="quicklook-kit/virtual" />
+```
+
+or in `tsconfig.json` under `compilerOptions.types` as `"quicklook-kit/virtual"`.
+
+### 3. Read the file
+
+```ts
+import { browserFile, config, nativeFile } from "virtual:quicklook";
+
+const file = nativeFile(); // the previewed file inside QuickLook, undefined in the browser
+config.public; // values from quicklook.config.*
+```
+
+| Field       | Type         |                                |
+| ----------- | ------------ | ------------------------------ |
+| `name`      | `string`     | `"notes.example"`              |
+| `extension` | `string`     | `"example"`, lowercase, no dot |
+| `bytes`     | `Uint8Array` | the raw file contents          |
+
+Decode `bytes` however your format needs: `new TextDecoder().decode(file.bytes)` for text, or a parser for binary formats.
+
+In the dev server, `nativeFile()` returns `undefined`. Pass a dropped or picked `File` to `browserFile()` to get the same shape.
+
+### 4. Add scripts
+
+```json
+{
+  "scripts": {
+    "dev": "quicklook dev",
+    "build": "quicklook build",
+    "register": "quicklook build && quicklook register",
+    "unregister": "quicklook unregister"
+  }
+}
+```
+
+## CLI
+
+| Command                | Description                                                         |
+| ---------------------- | ------------------------------------------------------------------- |
+| `quicklook dev`        | Starts the framework's dev server                                   |
+| `quicklook build:web`  | Builds the page only, into `.quicklook/web`                         |
+| `quicklook build`      | Builds the app with its extension into `.quicklook/build`           |
+| `quicklook register`   | Copies the built app to `/Applications` and registers the extension |
+| `quicklook unregister` | Removes the app from `/Applications`                                |
+
+After `register`, select a file in Finder and press Space. Run `build` and `register` again after every change.
+
+If the preview doesn't show up, check `pluginkit -mAv | grep <your bundleId>`, and make sure no other app claims the same file type.
+
+Add `.quicklook` to your `.gitignore`.
+
+## Things to know
+
+- **Nothing can be loaded from the network.** The extension serves your build from inside the app with a strict Content Security Policy. Import images, fonts and CSS normally and they get bundled. The dev server only reports violations in the console, without blocking them.
+- **Inline scripts are allowed by hash.** Frameworks that bootstrap with inline `<script>` tags keep working; the hashes are added to the CSP at build time.
+- **Test in Safari.** It uses the same WebKit engine as QuickLook's WKWebView.
+- **The light/dark theme follows the system.** Use `prefers-color-scheme` in CSS.
+- **The app is signed ad hoc.** Other people have to allow it in System Settings → Privacy & Security on first launch. Distributing it without that step requires an Apple Developer account and notarization.
+
+## Integrations
+
+An integration is an object with a `name` and any of these hooks. They run in order: the framework first, then each entry in `integrations`.
+
+```ts
+import type { Integration } from "quicklook-kit";
+
+export default (options: { key: string }): Integration => ({
+  name: "my-integration",
+  hooks: {
+    // Adjust the resolved config.
+    "config:resolved"(config) {},
+
+    // Post-process the framework's static output before it's bundled.
+    async "build:done"({ outDir, config }) {},
+
+    // Edit the generated XcodeGen spec: Info.plist keys, entitlements, targets.
+    "xcode:spec"(spec, config) {
+      spec.targets.ExamplePreviewExtension.info.properties.MyKey = options.key;
+    },
+
+    // Add Vite plugins wherever quicklook() is used.
+    vite: () => [],
+  },
+});
+```
+
+Add it as an object, or by name so JSON and YAML configs can use it too. A name is imported from the project: a package or a relative path, whose default export is the integration or a function returning it.
+
+```jsonc
+{
+  "integrations": ["quicklook-some-package", ["./my-integration.ts", { "key": "value" }]],
+}
+```
+
+A framework is an integration with a `build` field:
+
+```ts
+framework: {
+	name: 'my-framework',
+	build: { dev: ['vite', 'dev'], command: ['vite', 'build'], outDir: 'dist' }
+}
+```
+
+The commands run with the project's own binaries.
+
+## License
+
+This work is licensed under [The MIT License](https://opensource.org/licenses/MIT).

package/src/cli.ts

@@ -0,0 +1,200 @@
+#!/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 { 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 } = 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`],
+				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,
+						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

@@ -0,0 +1,176 @@
+// 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;
+	/** 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'>> {
+	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

@@ -0,0 +1,36 @@
+/** 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/virtual.d.ts

@@ -0,0 +1,7 @@
+// Types for the module the `quicklook()` Vite plugin provides. Reference it
+// with `/// <reference types="quicklook-kit/virtual" />`.
+declare module 'virtual:quicklook' {
+	/** Build-time values from quicklook.config.*. */
+	export const config: import('./config.ts').PageConfig;
+	export { browserFile, nativeFile, type QuickLookFile } from 'quicklook-kit/runtime';
+}

package/src/vite.ts

@@ -0,0 +1,41 @@
+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

@@ -0,0 +1,16 @@
+{
+	"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"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.