quicklook-kit 0.5.0 → 0.6.0

package/README.markdown

@@ -64,6 +64,7 @@ The config can also be `quicklook.config.js`, `.json`, `.yaml` or `.toml`, or a
 | `csp`          | locked down  | Directives here replace the defaults of the same name                              |
 | `maxFileSize`  | `10_000_000` | Larger files get Quick Look's generic preview                                      |
 | `public`       | `{}`         | Values the page can read at build time                                             |
+| `settings`     | `{}`         | Settings the user edits in the app, see [Settings](#settings)                      |
 
 A framework can take options as a `[name, options]` pair, e.g. `['sveltekit', { outDir: 'dist' }]` when your adapter writes somewhere other than the default.
 
@@ -150,6 +151,47 @@ Add `.quicklook` to your `.gitignore`.
 - **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.
 
+## Settings
+
+`settings` declares options the user can change in the app. Each entry's `type` picks the control the app shows:
+
+```ts
+settings: {
+  theme: {
+    type: "string",
+    default: "light",
+    enum: [{ value: "light", description: "Light" }, "dark"],
+    radio: true,
+  },
+  wrap: { type: "boolean", default: true, description: "Wrap **long** lines" },
+  fontSize: { type: "integer", default: 13, minimum: 9, maximum: 32 },
+  editor: {
+    type: "object",
+    properties: { tabSize: { type: "integer", default: 2, enum: [2, 4, 8] } },
+  },
+},
+```
+
+| Type                                        | Control                                                                   |
+| ------------------------------------------- | ------------------------------------------------------------------------- |
+| `boolean`                                   | Checkbox                                                                  |
+| `enum` (on `string`, `integer` or `number`) | Picker, or radio buttons with `radio: true`                               |
+| `string`                                    | Text field                                                                |
+| `integer`, `number`                         | Number field, clamped to `minimum`/`maximum`; `integer` rejects fractions |
+| `object`                                    | A group with a heading, for nested `properties`                           |
+
+Every entry except `object` needs a `default`. `title` defaults to the key in words (`fontSize` becomes "Font Size"), `description` is inline Markdown, and `order` sorts entries. `enum` entries are plain values or `{ value, description }`. A schema with an unknown type or field, a field on the wrong type, a key containing `.`, or a default that doesn't fit its type, `enum` or bounds fails the build with the key path, e.g. `settings.editor.tabSize: default 0 is below minimum 1`.
+
+The page reads the values, nested like the schema, with `settings()`:
+
+```ts
+import { settings } from "virtual:quicklook";
+
+const { wrap, editor } = settings();
+```
+
+In the dev server, `settings()` returns the defaults.
+
 ## 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`.

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as serializeCsp, i as loadConfig, t as addSources } from "./config-BQ-9qYNV.mjs";
+import { a as serializeCsp, i as loadConfig, t as addSources } from "./config-BVPHnCWr.mjs";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
@@ -19,6 +19,20 @@ 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;
+/**
+* The settings schema as nested arrays, each entry with its own `key`: Swift's
+* JSONSerialization decodes objects into unordered dictionaries.
+*/
+function settingsSchema(settings) {
+	return Object.entries(settings).map(([key, setting]) => setting.type === "object" ? {
+		...setting,
+		key,
+		properties: settingsSchema(setting.properties)
+	} : {
+		...setting,
+		key
+	});
+}
 /** 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, {
@@ -70,12 +84,11 @@ async function buildWeb() {
 async function build() {
 	await buildWeb();
 	const csp = addSources(config.csp, "script-src", ...await inlineScriptHashes());
+	const hasSettings = Object.keys(config.settings).length > 0;
+	const qlSettings = hasSettings && { QLSettings: JSON.stringify(settingsSchema(config.settings)) };
 	const spec = {
 		name: target,
-		options: {
-			deploymentTarget: { macOS },
-			createIntermediateGroups: true
-		},
+		options: { deploymentTarget: { macOS } },
 		settings: { base: {
 			SWIFT_VERSION: "6.0",
 			MARKETING_VERSION: process.env.VERSION?.replace(leadingV, "") ?? "1.0",
@@ -87,10 +100,14 @@ async function build() {
 			[target]: {
 				type: "application",
 				platform: "macOS",
-				sources: [`${native}/App`, ...icon ? [{
-					path: resolve(root, icon),
-					buildPhase: "resources"
-				}] : []],
+				sources: [
+					`${native}/App`,
+					`${native}/Shared`,
+					...icon ? [{
+						path: resolve(root, icon),
+						buildPhase: "resources"
+					}] : []
+				],
 				settings: {
 					PRODUCT_NAME: name,
 					PRODUCT_BUNDLE_IDENTIFIER: bundleId
@@ -106,6 +123,7 @@ async function build() {
 						CFBundleName: name,
 						...icon && { CFBundleIconFile: basename(icon, ".icns") },
 						LSMinimumSystemVersion: macOS,
+						...qlSettings,
 						UTExportedTypeDeclarations: types.filter((type) => typeof type !== "string").map((type) => ({
 							UTTypeIdentifier: type.id,
 							UTTypeDescription: type.description,
@@ -118,11 +136,15 @@ async function build() {
 			[`${target}Extension`]: {
 				type: "app-extension",
 				platform: "macOS",
-				sources: [`${native}/Extension`, {
-					path: web,
-					type: "folder",
-					buildPhase: "resources"
-				}],
+				sources: [
+					`${native}/Extension`,
+					`${native}/Shared`,
+					{
+						path: web,
+						type: "folder",
+						buildPhase: "resources"
+					}
+				],
 				settings: { PRODUCT_BUNDLE_IDENTIFIER: `${bundleId}.Extension` },
 				dependencies: [{ sdk: "QuickLookUI.framework" }, { sdk: "WebKit.framework" }],
 				entitlements: {
@@ -130,7 +152,8 @@ async function build() {
 					properties: {
 						"com.apple.security.app-sandbox": true,
 						"com.apple.security.files.user-selected.read-only": true,
-						"com.apple.security.network.client": true
+						"com.apple.security.network.client": true,
+						...hasSettings && { "com.apple.security.temporary-exception.shared-preference.read-only": [bundleId] }
 					}
 				},
 				info: {
@@ -139,6 +162,7 @@ async function build() {
 						CFBundleDisplayName: name,
 						QLWebContentSecurityPolicy: serializeCsp(csp),
 						QLMaxFileSize: config.maxFileSize,
+						...qlSettings,
 						NSExtension: {
 							NSExtensionPointIdentifier: "com.apple.quicklook.preview",
 							NSExtensionPrincipalClass: "PreviewViewController",

package/dist/config-BVPHnCWr.mjs

@@ -0,0 +1,249 @@
+import { join } from "node:path";
+import process from "node:process";
+import { loadConfig } from "c12";
+import { createJiti } from "jiti";
+//#region src/settings.ts
+/** The fields each setting type allows, besides `type`, `title`, `description` and `order`. */
+const settingFields = {
+	boolean: ["default"],
+	string: [
+		"default",
+		"enum",
+		"radio"
+	],
+	integer: [
+		"default",
+		"enum",
+		"radio",
+		"minimum",
+		"maximum"
+	],
+	number: [
+		"default",
+		"enum",
+		"radio",
+		"minimum",
+		"maximum"
+	],
+	object: ["properties"]
+};
+const commonFields = [
+	"type",
+	"title",
+	"description",
+	"order"
+];
+const knownFields = /* @__PURE__ */ new Set([...commonFields, ...Object.values(settingFields).flat()]);
+function isString(value) {
+	return typeof value === "string";
+}
+/** Whether `value` is a valid value of setting type `type`. */
+const valueChecks = {
+	boolean: (value) => typeof value === "boolean",
+	string: isString,
+	integer: Number.isInteger,
+	number: Number.isFinite
+};
+/** Optional fields with a fixed type, and the problem when it's wrong. */
+const fieldChecks = [
+	[
+		"title",
+		isString,
+		"title must be a string"
+	],
+	[
+		"description",
+		isString,
+		"description must be a string"
+	],
+	[
+		"order",
+		Number.isFinite,
+		"order must be a number"
+	],
+	[
+		"minimum",
+		Number.isFinite,
+		"minimum must be a number"
+	],
+	[
+		"maximum",
+		Number.isFinite,
+		"maximum must be a number"
+	],
+	[
+		"radio",
+		(value) => typeof value === "boolean",
+		"radio must be true or false"
+	]
+];
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Throws on anything in a `settings` schema the app can't show, naming the key
+* path, e.g. `settings.editor.tabSize: default 0 is below minimum 1`.
+*/
+function validateSettings(settings, path = "settings") {
+	if (!isRecord(settings)) throw new Error(`${path}: expected an object of settings`);
+	for (const [key, entry] of Object.entries(settings)) {
+		const at = `${path}.${key}`;
+		if (key.includes(".")) throw new Error(`${at}: keys can't contain "."`);
+		if (!isRecord(entry)) throw new Error(`${at}: expected an object with a type`);
+		const problem = settingProblem(entry);
+		if (problem) throw new Error(`${at}: ${problem}`);
+		if (entry.type === "object") validateSettings(entry.properties, at);
+	}
+}
+/** What's wrong with one entry, without looking into `properties`. */
+function settingProblem(entry) {
+	const type = String(entry.type);
+	if (!(typeof entry.type === "string" && Object.hasOwn(settingFields, type))) return `unknown type ${JSON.stringify(entry.type)}`;
+	for (const field of Object.keys(entry)) {
+		if (!knownFields.has(field)) return `unknown field "${field}"`;
+		if (!(commonFields.includes(field) || settingFields[type]?.includes(field))) return `"${field}" isn't allowed on type "${type}"`;
+	}
+	const wrong = fieldChecks.find(([field, check]) => !(entry[field] === void 0 || check(entry[field])));
+	if (wrong) return wrong[2];
+	if (type === "object") return isRecord(entry.properties) && Object.keys(entry.properties).length > 0 ? void 0 : "an object needs non-empty properties";
+	return valueProblem(entry, type);
+}
+/** What's wrong with the default, the range and the enum of a non-object entry. */
+function valueProblem(entry, type) {
+	if (!("default" in entry)) return "default is required";
+	const { default: value, minimum, maximum, radio, enum: options } = entry;
+	const shown = JSON.stringify(value);
+	if (!valueChecks[type]?.(value)) return `default ${shown} isn't of type "${type}"`;
+	if (typeof minimum === "number" && typeof maximum === "number" && minimum > maximum) return `minimum ${minimum} is above maximum ${maximum}`;
+	if (typeof minimum === "number" && value < minimum) return `default ${shown} is below minimum ${minimum}`;
+	if (typeof maximum === "number" && value > maximum) return `default ${shown} is above maximum ${maximum}`;
+	if (radio && options === void 0) return "radio needs an enum";
+	return options === void 0 ? void 0 : enumProblem(options, value, type);
+}
+/** An object entry other than `{ value, description? }`. */
+function malformedOption(option) {
+	return !("value" in option && Object.keys(option).every((field) => field === "value" || field === "description") && (option.description === void 0 || isString(option.description)));
+}
+function enumProblem(options, value, type) {
+	if (!Array.isArray(options) || options.length === 0) return "enum must be a non-empty array";
+	const values = [];
+	for (const [index, option] of options.entries()) {
+		if (isRecord(option) && malformedOption(option)) return `enum[${index}] must be a value or { value, description }`;
+		const optionValue = isRecord(option) ? option.value : option;
+		if (!valueChecks[type]?.(optionValue)) return `enum[${index}] ${JSON.stringify(optionValue)} isn't of type "${type}"`;
+		values.push(optionValue);
+	}
+	return values.includes(value) ? void 0 : `default ${JSON.stringify(value)} isn't in the enum`;
+}
+//#endregion
+//#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}`);
+	validateSettings(config.settings ?? {});
+	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: {},
+		settings: {},
+		...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

@@ -13,6 +13,41 @@ export interface DeclaredType {
 export type Csp = Partial<Record<string, string[]>>;
 /** The xcodegen project spec, written as project.yml. */
 export type XcodeSpec = Record<string, any>;
+/** An `enum` entry: a plain value, or one with a label for the picker. */
+export type EnumEntry<T> = T | {
+  value: T;
+  description?: string;
+};
+interface BaseSetting {
+  /** Defaults to the key, turned into words (`fontSize` → "Font Size"). */
+  title?: string;
+  /** Inline Markdown. */
+  description?: string;
+  order?: number;
+}
+/**
+ * A user-editable setting. The type decides the control the app shows; the
+ * page gets the resolved values from `settings()`.
+ */
+export type Setting = (BaseSetting & {
+  type: 'boolean';
+  default: boolean;
+}) | (BaseSetting & {
+  type: 'string';
+  default: string;
+  enum?: EnumEntry<string>[];
+  radio?: boolean;
+}) | (BaseSetting & {
+  type: 'integer' | 'number';
+  default: number;
+  enum?: EnumEntry<number>[];
+  radio?: boolean;
+  minimum?: number;
+  maximum?: number;
+}) | (BaseSetting & {
+  type: 'object';
+  properties: Record<string, Setting>;
+});
 export interface Integration {
   name: string;
   /** Set by frameworks only: how to run and build the page, and where it lands. */
@@ -59,6 +94,8 @@ export interface QuickLookConfig {
   maxFileSize?: number;
   /** Exposed to the page as `config.public` from `virtual:quicklook`. */
   public?: Record<string, unknown>;
+  /** Settings the user edits in the app, read on the page with `settings()`. */
+  settings?: Record<string, Setting>;
 }
 /** What the page sees as `config` from `virtual:quicklook`. */
 export type PageConfig = Pick<ResolvedConfig, 'name' | 'bundleId' | 'types' | 'public'>;
@@ -77,4 +114,5 @@ 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
+//#endregion
+export {};

package/dist/config.mjs

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

package/dist/runtime.d.mts

@@ -13,6 +13,8 @@ declare global {
       name: string;
       extension: string;
       base64: string;
+      /** Present when the config declares `settings`. */
+      settings?: Record<string, unknown>;
     };
   }
 }

package/dist/vite.mjs

@@ -1,6 +1,10 @@
-import { a as serializeCsp, i as loadConfig, t as addSources } from "./config-BQ-9qYNV.mjs";
+import { a as serializeCsp, i as loadConfig, t as addSources } from "./config-BVPHnCWr.mjs";
 //#region src/vite.ts
 const virtualId = "virtual:quicklook";
+/** The schema's defaults as nested objects, the shape the extension injects. */
+function settingDefaults(settings) {
+	return Object.fromEntries(Object.entries(settings).map(([key, setting]) => [key, setting.type === "object" ? settingDefaults(setting.properties) : setting.default]));
+}
 /**
 * Provides `virtual:quicklook`, adds the integrations' Vite plugins, and makes
 * the dev server report what the extension's CSP would block.
@@ -15,7 +19,9 @@ async function quicklook() {
 		public: config.public
 	};
 	const virtualSource = `export const config = ${JSON.stringify(pageConfig)};
-export { browserFile, nativeFile } from 'quicklook-kit/runtime';`;
+export { browserFile, nativeFile } from 'quicklook-kit/runtime';
+// The injected values in Quick Look, the defaults in the dev server and when prerendering.
+export const settings = () => globalThis.window?.quicklook?.settings ?? ${JSON.stringify(settingDefaults(config.settings))};`;
 	const devCsp = serializeCsp(addSources(addSources(config.csp, "script-src", "'unsafe-inline'"), "connect-src", "'self'", "ws:"));
 	return [{
 		name: "quicklook",

package/native/App/HostApp.swift

@@ -8,16 +8,237 @@ import UniformTypeIdentifiers
 struct HostApp: App {
   private let name = Bundle.main.object(forInfoDictionaryKey: "CFBundleName") as? String ?? ""
 
+  private let specs = SettingSpec.load()
+
   var body: some Scene {
     Window(name, id: "main") {
-      ContentView(name: name)
-        .padding(32)
+      if specs.isEmpty {
+        ContentView(name: name)
+          .padding([.horizontal, .top], 32)
+          // Matches the gap above the footer.
+          .padding(.bottom, 16)
+          .fixedSize()
+      } else {
+        TabView {
+          ContentView(name: name)
+            .padding([.horizontal, .top], 32)
+            // Matches the gap above the footer.
+            .padding(.bottom, 16)
+            .tabItem { Text("General") }
+          VStack(spacing: 16) {
+            ScrollView {
+              VStack(alignment: .leading, spacing: 20) {
+                ForEach(specs, id: \.key) { SettingRow(spec: $0) }
+              }
+              .frame(width: 360, alignment: .leading)
+            }
+            // Caps the window height; longer forms scroll.
+            .frame(maxHeight: 420)
+            Footer()
+          }
+          .frame(width: 360)
+          .padding([.horizontal, .top], 32)
+          // Matches the gap above the footer.
+          .padding(.bottom, 16)
+          .tabItem { Text("Settings") }
+        }
+        .padding([.horizontal, .top], 20)
         .fixedSize()
+      }
     }
     .windowResizability(.contentSize)
   }
 }
 
+/// Shown at the bottom of every tab.
+private struct Footer: View {
+  var body: some View {
+    Divider()
+    HStack(spacing: 3) {
+      Text("Made with").foregroundStyle(.tertiary)
+      Link("quicklook-kit", destination: URL(string: "https://github.com/idleberg/quicklook-kit")!)
+        .foregroundStyle(.secondary)
+        // A separate view, so only the link gets the pointer.
+        .onHover { $0 ? NSCursor.pointingHand.push() : NSCursor.pop() }
+    }
+    .font(.caption)
+  }
+}
+
+/// One entry of the settings form, in a single column: title, description, control.
+/// Values live in `UserDefaults.standard` under the dotted key, where the extension reads them.
+private struct SettingRow: View {
+  let spec: SettingSpec
+
+  var body: some View {
+    VStack(alignment: .leading, spacing: 6) {
+      if spec.type == "boolean" {
+        CheckboxSetting(spec: spec)
+        SettingDescription(spec: spec)
+      } else {
+        Text(spec.title).font(spec.type == "object" ? .headline : .body).bold()
+        SettingDescription(spec: spec)
+        if spec.type == "object" {
+          VStack(alignment: .leading, spacing: 16) {
+            ForEach(spec.children, id: \.key) { SettingRow(spec: $0) }
+          }
+          .padding(.leading, 16)
+          .padding(.top, 6)
+        } else if !spec.options.isEmpty {
+          PickerSetting(spec: spec)
+        } else {
+          FieldSetting(spec: spec)
+        }
+      }
+    }
+  }
+}
+
+private struct SettingDescription: View {
+  let spec: SettingSpec
+
+  var body: some View {
+    if let description = spec.description {
+      let options = AttributedString.MarkdownParsingOptions(
+        interpretedSyntax: .inlineOnlyPreservingWhitespace)
+      Text(
+        (try? AttributedString(markdown: description, options: options))
+          ?? AttributedString(description)
+      )
+      .foregroundStyle(.secondary)
+      .fixedSize(horizontal: false, vertical: true)
+    }
+  }
+}
+
+private struct CheckboxSetting: View {
+  let spec: SettingSpec
+  @State private var isOn: Bool
+
+  init(spec: SettingSpec) {
+    self.spec = spec
+    _isOn = State(initialValue: (storedValue(spec) ?? spec.defaultValue) as? Bool ?? false)
+  }
+
+  var body: some View {
+    Toggle(isOn: $isOn) { Text(spec.title).bold() }
+      .toggleStyle(.checkbox)
+      .onChange(of: isOn) { save(isOn, for: spec) }
+  }
+}
+
+private struct PickerSetting: View {
+  let spec: SettingSpec
+  @State private var selection: Int
+
+  init(spec: SettingSpec) {
+    self.spec = spec
+    let current = storedValue(spec) ?? spec.defaultValue
+    _selection = State(
+      initialValue: spec.options.firstIndex { option in
+        current.map { same(option.value, $0) } ?? false
+      } ?? 0)
+  }
+
+  var body: some View {
+    let picker = Picker(spec.title, selection: $selection) {
+      ForEach(spec.options.indices, id: \.self) { Text(spec.options[$0].label).tag($0) }
+    }
+    .labelsHidden()
+    .fixedSize()
+    .onChange(of: selection) { save(spec.options[selection].value, for: spec) }
+
+    if spec.radio {
+      picker.pickerStyle(.radioGroup)
+    } else {
+      picker.pickerStyle(.menu)
+    }
+  }
+}
+
+/// Saves on Return or focus loss. Empty removes the stored value, so the default
+/// (shown as placeholder) applies again.
+private struct FieldSetting: View {
+  let spec: SettingSpec
+  @State private var text: String
+  @FocusState private var isFocused: Bool
+
+  init(spec: SettingSpec) {
+    self.spec = spec
+    _text = State(initialValue: storedValue(spec).map { "\($0)" } ?? "")
+  }
+
+  var body: some View {
+    TextField(spec.defaultValue.map { String(describing: $0) } ?? "", text: $text)
+      .focused($isFocused)
+      .onSubmit(commit)
+      .onChange(of: isFocused) { if !isFocused { commit() } }
+  }
+
+  private func commit() {
+    let input = spec.type == "string" ? text : text.trimmingCharacters(in: .whitespaces)
+    if input.isEmpty {
+      text = ""
+      save(nil, for: spec)
+      return
+    }
+
+    let clamp = { (raw: Double) in
+      min(max(raw, spec.minimum ?? -.infinity), spec.maximum ?? .infinity)
+    }
+    var value: Any?
+    switch spec.type {
+    // Int() rejects fractions, so "2.5" never saves for an integer.
+    case "integer":
+      value = Int(input).map { clamp(Double($0)) == Double($0) ? $0 : Int(clamp(Double($0))) }
+    case "number": value = Double(input).map(clamp)
+    default: value = input
+    }
+
+    // Invalid input isn't saved; the field goes back to what's stored.
+    guard let value, spec.isValid(value) else {
+      text = storedValue(spec).map { "\($0)" } ?? ""
+      return
+    }
+    text = "\(value)"
+    save(value, for: spec)
+  }
+}
+
+/// The stored value, or nil when there is none or it no longer fits the schema.
+private func storedValue(_ spec: SettingSpec) -> Any? {
+  guard let value = UserDefaults.standard.object(forKey: spec.key), spec.isValid(value) else {
+    return nil
+  }
+  return value
+}
+
+/// Compares through NSObject, so an Int option matches the NSNumber UserDefaults returns,
+/// and 2 matches 2.0.
+private func same(_ lhs: Any, _ rhs: Any) -> Bool {
+  (lhs as AnyObject).isEqual(rhs as AnyObject)
+}
+
+/// Writes or removes (nil) the value, then resets Quick Look's cache so the next
+/// preview picks it up. Open previews don't update.
+private func save(_ value: Any?, for spec: SettingSpec) {
+  let defaults = UserDefaults.standard
+  let old = defaults.object(forKey: spec.key)
+  if let value {
+    if let old, same(old, value) { return }
+    defaults.set(value, forKey: spec.key)
+  } else {
+    if old == nil { return }
+    defaults.removeObject(forKey: spec.key)
+  }
+
+  let process = Process()
+  process.executableURL = URL(fileURLWithPath: "/usr/bin/qlmanage")
+  process.arguments = ["-r", "cache"]
+  process.standardOutput = FileHandle.nullDevice
+  try? process.run()
+}
+
 private struct ContentView: View {
   let name: String
 
@@ -60,12 +281,7 @@ private struct ContentView: View {
         .frame(maxWidth: .infinity, alignment: .leading)
       }
 
-      Divider()
-
-      Text("Made with [quicklook-kit](https://github.com/idleberg/quicklook-kit)")
-        .font(.caption)
-        .foregroundStyle(.tertiary)
-        .tint(.secondary)
+      Footer()
     }
     // Fixed so the window only grows in height as text comes and goes.
     .frame(width: 360)

package/native/Extension/PreviewViewController.swift

@@ -29,11 +29,18 @@ final class PreviewViewController: NSViewController, QLPreviewingController {
     let size = try url.resourceValues(forKeys: [.fileSizeKey]).fileSize ?? 0
     guard size <= Self.maxFileSize else { throw CocoaError(.fileReadTooLarge) }
 
-    let file = [
+    var file: [String: Any] = [
       "name": url.lastPathComponent,
       "extension": url.pathExtension.lowercased(),
       "base64": try Data(contentsOf: url).base64EncodedString(),
     ]
+    // The host app saves settings to its own defaults; the extension's bundle id
+    // is the app's plus `.Extension`, and its entitlements allow reading them.
+    let specs = SettingSpec.load()
+    let suite = Bundle.main.bundleIdentifier.map { String($0.dropLast(".Extension".count)) }
+    if !specs.isEmpty, let suite, let defaults = UserDefaults(suiteName: suite) {
+      file["settings"] = resolveSettings(specs, from: defaults)
+    }
     // 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

package/native/Shared/Settings.swift

@@ -0,0 +1,129 @@
+import Foundation
+
+/// One entry of the `QLSettings` schema the build writes into Info.plist.
+/// Compiled into both the app, which edits the values, and the extension,
+/// which hands them to the page. See packages/quicklook-kit/src/config.ts.
+struct SettingSpec {
+  let key: String
+  let type: String
+  let title: String
+  let description: String?
+  let defaultValue: Any?
+  let options: [(value: Any, label: String)]
+  let radio: Bool
+  let minimum: Double?
+  let maximum: Double?
+  let children: [SettingSpec]
+
+  private init(_ entry: [String: Any], prefix: String) {
+    let name = entry["key"] as? String ?? ""
+    let type = entry["type"] as? String ?? ""
+    key = prefix + name
+    self.type = type
+    title = entry["title"] as? String ?? words(name)
+    description = entry["description"] as? String
+    radio = bool(entry["radio"] as Any) ?? false
+    minimum = number(entry["minimum"] as Any)?.doubleValue
+    maximum = number(entry["maximum"] as Any)?.doubleValue
+    children = Self.sorted(entry["properties"] as? [[String: Any]] ?? [], prefix: key + ".")
+    defaultValue = entry["default"].flatMap { Self.cast($0, as: type) }
+    options = (entry["enum"] as? [Any] ?? []).compactMap { option in
+      let object = option as? [String: Any]
+      guard let value = Self.cast(object?["value"] ?? option, as: type) else { return nil }
+      return (value, object?["description"] as? String ?? "\(value)")
+    }
+  }
+
+  /// Whether a stored value fits this entry: right type, in `options` if any, within bounds, integers whole.
+  func isValid(_ value: Any) -> Bool { validated(value) != nil }
+
+  /// `value` as this entry's Swift type if it fits, so a stored 3.0 comes back as integer 3.
+  func validated(_ value: Any) -> Any? {
+    guard let cast = Self.cast(value, as: type) else { return nil }
+    if !options.isEmpty, !options.contains(where: { ($0.value as AnyObject).isEqual(cast) }) {
+      return nil
+    }
+    if let num = number(cast)?.doubleValue {
+      if let minimum, num < minimum { return nil }
+      if let maximum, num > maximum { return nil }
+    }
+    return cast
+  }
+
+  /// `value` as Bool, String, Int or Double per `type`, or nil if it's the wrong type.
+  private static func cast(_ value: Any, as type: String) -> Any? {
+    switch type {
+    case "boolean": bool(value)
+    case "string": value as? String
+    case "integer": number(value).flatMap { Int(exactly: $0.doubleValue) }
+    case "number": number(value)?.doubleValue
+    default: nil
+    }
+  }
+
+  /// Top-level entries from the bundle's `QLSettings`, sorted; empty if absent.
+  static func load(from bundle: Bundle = .main) -> [SettingSpec] {
+    decode(bundle.object(forInfoDictionaryKey: "QLSettings") as? String ?? "[]")
+  }
+
+  /// Entries from a `QLSettings` JSON string, sorted; empty if it doesn't parse.
+  static func decode(_ json: String) -> [SettingSpec] {
+    let entries = (try? JSONSerialization.jsonObject(with: Data(json.utf8))) as? [[String: Any]]
+    return sorted(entries ?? [], prefix: "")
+  }
+
+  /// By `order`, unordered entries last, then in declaration order.
+  private static func sorted(_ entries: [[String: Any]], prefix: String) -> [SettingSpec] {
+    entries.enumerated()
+      .sorted {
+        let lhs = number($0.element["order"] as Any)?.doubleValue ?? .infinity
+        let rhs = number($1.element["order"] as Any)?.doubleValue ?? .infinity
+        return (lhs, $0.offset) < (rhs, $1.offset)
+      }
+      .map { SettingSpec($0.element, prefix: prefix) }
+  }
+}
+
+/// Defaults overridden by valid values from `defaults` (read by dotted key), as nested dictionaries.
+func resolveSettings(_ specs: [SettingSpec], from defaults: UserDefaults) -> [String: Any] {
+  var values: [String: Any] = [:]
+  for spec in specs {
+    let name = spec.key.split(separator: ".").last.map(String.init) ?? spec.key
+    values[name] =
+      spec.type == "object"
+      ? resolveSettings(spec.children, from: defaults)
+      : defaults.object(forKey: spec.key).flatMap(spec.validated) ?? spec.defaultValue
+  }
+  return values
+}
+
+// UserDefaults and JSONSerialization hand back NSNumber for booleans and numbers
+// alike; only the CFBoolean ones are booleans.
+private func bool(_ value: Any) -> Bool? {
+  guard let num = value as? NSNumber, CFGetTypeID(num) == CFBooleanGetTypeID() else { return nil }
+  return num.boolValue
+}
+
+private func number(_ value: Any) -> NSNumber? {
+  guard let num = value as? NSNumber, CFGetTypeID(num) != CFBooleanGetTypeID() else { return nil }
+  return num
+}
+
+/// "fontSize" → "Font Size"; dashes and underscores become spaces too.
+private func words(_ key: String) -> String {
+  var spaced = ""
+  var previous: Character?
+  for char in key {
+    if char == "_" || char == "-" {
+      spaced.append(" ")
+    } else {
+      if char.isUppercase, previous?.isLowercase == true || previous?.isNumber == true {
+        spaced.append(" ")
+      }
+      spaced.append(char)
+    }
+    previous = char
+  }
+  return spaced.split(separator: " ").map { $0.prefix(1).uppercased() + $0.dropFirst() }
+    .joined(separator: " ")
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quicklook-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Build macOS Quick Look previews with any Vite-based web framework",
   "license": "MIT",
   "keywords": [
@@ -53,13 +53,15 @@
     "@types/node": "24.19.2",
     "tsdown": "0.23.1",
     "typescript": "6.0.3",
-    "vite": "8.3.4"
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
   },
   "peerDependencies": {
     "vite": ">=7"
   },
   "scripts": {
     "build": "tsdown",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "vitest run"
   }
 }

package/src/virtual.d.ts

@@ -3,5 +3,7 @@
 declare module 'virtual:quicklook' {
 	/** Build-time values from quicklook.config.*. */
 	export const config: import('quicklook-kit').PageConfig;
+	/** The user's settings: stored values over the config's defaults, as nested objects. */
+	export const settings: () => Record<string, unknown>;
 	export { browserFile, nativeFile, type QuickLookFile } from 'quicklook-kit/runtime';
 }

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

@@ -1,113 +0,0 @@
-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 };