quicklook-kit 0.3.1 → 0.5.0

package/LICENSE

@@ -1,3 +1,7 @@
+MIT License
+
+Copyright (c) 2026 Jan T. Sott
+
 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

package/README.markdown

@@ -4,9 +4,9 @@
 [![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
+> Build macOS Quick Look 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.
+Your preview is a web page. quicklook-kit builds it with your framework, wraps it in a small native Quick Look 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.
 
@@ -34,11 +34,11 @@ Create `quicklook.config.ts` in your project root:
 import { defineConfig } from "quicklook-kit";
 
 export default defineConfig({
-  name: "Example Preview",
-  bundleId: "com.example.ExamplePreview",
+  name: "Quick Look Example",
+  bundleId: "com.example.QuickLookExample",
   types: [
     {
-      id: "com.example.ExamplePreview.example",
+      id: "com.example.QuickLookExample.example",
       description: "Example File",
       extensions: ["example"],
       conformsTo: ["public.plain-text"],
@@ -62,7 +62,7 @@ The config can also be `quicklook.config.js`, `.json`, `.yaml` or `.toml`, or a
 | `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                                       |
+| `maxFileSize`  | `10_000_000` | Larger files get Quick Look'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.
@@ -99,7 +99,7 @@ or in `tsconfig.json` under `compilerOptions.types` as `"quicklook-kit/virtual"`
 ```ts
 import { browserFile, config, nativeFile } from "virtual:quicklook";
 
-const file = nativeFile(); // the previewed file inside QuickLook, undefined in the browser
+const file = nativeFile(); // the previewed file inside Quick Look, undefined in the browser
 config.public; // values from quicklook.config.*
 ```
 
@@ -146,7 +146,7 @@ Add `.quicklook` to your `.gitignore`.
 
 - **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.
+- **Test in Safari.** It uses the same WebKit engine as Quick Look'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.
 
@@ -168,7 +168,7 @@ export default (options: { key: string }): Integration => ({
 
     // Edit the generated XcodeGen spec: Info.plist keys, entitlements, targets.
     "xcode:spec"(spec, config) {
-      spec.targets.ExamplePreviewExtension.info.properties.MyKey = options.key;
+      spec.targets.QuickLookExampleExtension.info.properties.MyKey = options.key;
     },
 
     // Add Vite plugins wherever quicklook() is used.
@@ -190,7 +190,11 @@ A framework is an integration with a `build` field:
 ```ts
 framework: {
 	name: 'my-framework',
-	build: { dev: ['vite', 'dev'], command: ['vite', 'build'], outDir: 'dist' }
+	build: {
+		dev: ['vite', 'dev'],
+		command: ['vite', 'build'],
+		outDir: 'dist'
+	}
 }
 ```
 

package/dist/config.d.mts

@@ -55,7 +55,7 @@ export interface QuickLookConfig {
   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. */
+  /** Larger files get Quick Look's generic preview. Defaults to 10 MB. */
   maxFileSize?: number;
   /** Exposed to the page as `config.public` from `virtual:quicklook`. */
   public?: Record<string, unknown>;

package/dist/runtime.d.mts

@@ -1,5 +1,5 @@
 //#region src/runtime.d.ts
-/** The file QuickLook asked to preview. */
+/** The file Quick Look asked to preview. */
 export interface QuickLookFile {
   name: string;
   /** Lowercase, without the dot. */
@@ -16,7 +16,7 @@ declare global {
     };
   }
 }
-/** The previewed file inside QuickLook; `undefined` in the browser. */
+/** The previewed file inside Quick Look; `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>;

package/dist/runtime.mjs

@@ -1,5 +1,5 @@
 //#region src/runtime.ts
-/** The previewed file inside QuickLook; `undefined` in the browser. */
+/** The previewed file inside Quick Look; `undefined` in the browser. */
 function nativeFile() {
 	const injected = window.quicklook;
 	if (!injected) return;

package/native/App/HostApp.swift

@@ -1,21 +1,170 @@
 import SwiftUI
+import UniformTypeIdentifiers
 
-/// QuickLook extensions have to ship inside an app, and macOS registers them
-/// when that app is first launched. This is all the app does.
+/// Quick Look extensions have to ship inside an app, and macOS registers them
+/// when that app is first launched. Beyond that, the app only lets the user
+/// enable or disable the extension.
 @main
 struct HostApp: App {
   private let name = Bundle.main.object(forInfoDictionaryKey: "CFBundleName") as? String ?? ""
 
   var body: some Scene {
     Window(name, id: "main") {
+      ContentView(name: name)
+        .padding(32)
+        .fixedSize()
+    }
+    .windowResizability(.contentSize)
+  }
+}
+
+private struct ContentView: View {
+  let name: String
+
+  // Matches the extension's PRODUCT_BUNDLE_IDENTIFIER in cli.ts.
+  private let extensionId = "\(Bundle.main.bundleIdentifier ?? "").Extension"
+
+  @State private var isEnabled = true
+  @State private var status: String?
+  @State private var conflicts: [String] = []
+
+  var body: some View {
+    VStack(spacing: 16) {
       VStack(spacing: 8) {
         Text(name).font(.headline)
-        Text("The QuickLook preview is installed. You can close this window.")
+        Text("Previews supported files when you press Space in Finder.")
           .foregroundStyle(.secondary)
+          .multilineTextAlignment(.center)
       }
-      .padding(32)
-      .fixedSize()
+
+      Button(isEnabled ? "Disable Preview" : "Enable Preview", action: toggle)
+
+      if let status {
+        Text(status).font(.caption).foregroundStyle(.secondary)
+      }
+
+      if isEnabled && !conflicts.isEmpty {
+        VStack(alignment: .leading, spacing: 8) {
+          Text("⚠️ \(conflicts.count == 1 ? "There is a conflict:" : "There are conflicts:")")
+            .bold()
+          ForEach(conflicts, id: \.self) { conflict in
+            Label {
+              Text(conflict)
+            } icon: {
+              Text("•")
+            }
+            .fixedSize(horizontal: false, vertical: true)
+          }
+        }
+        .font(.callout)
+        .frame(maxWidth: .infinity, alignment: .leading)
+      }
+
+      Divider()
+
+      Text("Made with [quicklook-kit](https://github.com/idleberg/quicklook-kit)")
+        .font(.caption)
+        .foregroundStyle(.tertiary)
+        .tint(.secondary)
     }
-    .windowResizability(.contentSize)
+    // Fixed so the window only grows in height as text comes and goes.
+    .frame(width: 360)
+    .onAppear(perform: refresh)
+  }
+
+  private func refresh() {
+    isEnabled = currentlyEnabled()
+    // The same app installed twice yields the same line twice; ForEach needs unique ids.
+    var seen = Set<String>()
+    conflicts = findConflicts().filter { seen.insert($0).inserted }
+  }
+
+  /// Other apps that would win over this preview for some of its file types.
+  /// ponytail: how Quick Look picks between conflicting extensions isn't documented, so
+  /// this is a best guess. Any overlap is reported, even if we'd happen to win.
+  private func findConflicts() -> [String] {
+    var conflicts: [String] = []
+
+    // Same file extension, two types: LaunchServices resolves the extension to only one.
+    // UTIs are case-insensitive, and LaunchServices returns them lowercased.
+    let declarations = Bundle.main.object(forInfoDictionaryKey: "UTExportedTypeDeclarations")
+    for declaration in declarations as? [[String: Any]] ?? [] {
+      guard let id = declaration["UTTypeIdentifier"] as? String,
+        let tags = declaration["UTTypeTagSpecification"] as? [String: Any],
+        let extensions = tags["public.filename-extension"] as? [String]
+      else { continue }
+      for ext in extensions {
+        guard let other = UTType(filenameExtension: ext)?.identifier,
+          other.lowercased() != id.lowercased()
+        else { continue }
+        conflicts.append("“.\(ext)” files are claimed by another app’s type “\(other)”.")
+      }
+    }
+
+    // Same type, two extensions.
+    let ourTypes = supportedTypes(Bundle.main.builtInPlugInsURL?.appendingPathComponent(appexName))
+    guard let output = pluginkit("-m", "-v", "-p", "com.apple.quicklook.preview") else {
+      return conflicts
+    }
+    for line in output.split(separator: "\n") {
+      guard let path = line.split(separator: "\t").last.map(String.init),
+        !line.trimmingCharacters(in: .whitespaces).hasPrefix("-"),
+        !line.contains(" \(extensionId)("),
+        !path.hasPrefix("/System/")
+      else { continue }
+      let theirTypes = supportedTypes(URL(fileURLWithPath: path))
+      let overlaps = ourTypes.contains { ours in theirTypes.contains { ours.conforms(to: $0) } }
+      guard overlaps else { continue }
+      let app = path.split(separator: "/").first { $0.hasSuffix(".app") }?.dropLast(4)
+      conflicts.append(
+        "“\(app ?? Substring(path))” also previews these files. Turn it off in System Settings → "
+          + "Login Items & Extensions → Quick Look.")
+    }
+    return conflicts
+  }
+
+  private var appexName: String {
+    let plugins = Bundle.main.builtInPlugInsPath ?? ""
+    let items = (try? FileManager.default.contentsOfDirectory(atPath: plugins)) ?? []
+    return items.first { $0.hasSuffix(".appex") } ?? ""
+  }
+
+  private func supportedTypes(_ appex: URL?) -> [UTType] {
+    guard let appex, let info = Bundle(url: appex)?.infoDictionary,
+      let attributes = (info["NSExtension"] as? [String: Any])?["NSExtensionAttributes"]
+        as? [String: Any],
+      let ids = attributes["QLSupportedContentTypes"] as? [String]
+    else { return [] }
+    return ids.compactMap(UTType.init)
+  }
+
+  /// `pluginkit -mv` prefixes a line with `-` when the extension is ignored,
+  /// `+` when explicitly enabled, and nothing when enabled by default.
+  private func currentlyEnabled() -> Bool {
+    guard let output = pluginkit("-m", "-v", "-i", extensionId) else { return true }
+    return !output.trimmingCharacters(in: .whitespaces).hasPrefix("-")
+  }
+
+  private func toggle() {
+    guard pluginkit("-e", isEnabled ? "ignore" : "use", "-i", extensionId) != nil else {
+      status = "Couldn't change the preview. Try again from System Settings."
+      return
+    }
+    refresh()
+    status = isEnabled ? "Preview enabled." : "Preview disabled."
+  }
+
+  /// Returns stdout, or nil if pluginkit failed to run or exited non-zero.
+  private func pluginkit(_ args: String...) -> String? {
+    let process = Process()
+    process.executableURL = URL(fileURLWithPath: "/usr/bin/pluginkit")
+    process.arguments = args
+    let pipe = Pipe()
+    process.standardOutput = pipe
+    guard (try? process.run()) != nil else { return nil }
+    let data = pipe.fileHandleForReading.readDataToEndOfFile()
+    process.waitUntilExit()
+    guard process.terminationStatus == 0 else { return nil }
+    return String(data: data, encoding: .utf8)
   }
 }

package/native/Extension/PreviewViewController.swift

@@ -6,7 +6,7 @@ import WebKit
 /// 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
+  /// Larger files throw, which makes Quick Look 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
@@ -43,7 +43,7 @@ final class PreviewViewController: NSViewController, QLPreviewingController {
         source: "window.quicklook = \(json);", injectionTime: .atDocumentStart,
         forMainFrameOnly: true))
 
-    // QuickLook displays the view as soon as this returns, so wait for the
+    // Quick Look 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) }
@@ -117,7 +117,7 @@ private final class LoadWaiter: NSObject, WKNavigationDelegate {
   }
 
   /// A crashed content process fires no navigation callback at all — without
-  /// this the await never returns and QuickLook spins forever.
+  /// this the await never returns and Quick Look spins forever.
   func webViewWebContentProcessDidTerminate(_ webView: WKWebView) {
     finish(.failure(CocoaError(.featureUnsupported)))
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "quicklook-kit",
-  "version": "0.3.1",
-  "description": "Build macOS QuickLook previews with any Vite-based web framework",
+  "version": "0.5.0",
+  "description": "Build macOS Quick Look previews with any Vite-based web framework",
   "license": "MIT",
   "keywords": [
     "quicklook",
@@ -51,9 +51,9 @@
   },
   "devDependencies": {
     "@types/node": "24.19.2",
-    "tsdown": "0.23.0",
+    "tsdown": "0.23.1",
     "typescript": "6.0.3",
-    "vite": "8.3.0"
+    "vite": "8.3.4"
   },
   "peerDependencies": {
     "vite": ">=7"