@legendapp/create-spark 0.0.0-stage → 0.0.1-next.5

package/dist/npm-bin/npm

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// npm 11's CLI; avoid installer-specific shell wrappers and global npm versions.
+import { createRequire } from 'node:module';
+import path from 'node:path';
+const require = createRequire(import.meta.url);
+require(path.join(path.dirname(require.resolve('npm/package.json')), 'bin/npm-cli.js'));

package/dist/npm-bin/npm.cmd

@@ -0,0 +1 @@
+@node "%~dp0npm" %*

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@legendapp/create-spark",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-next.5",
+  "description": "Create a Legend Spark app",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-spark": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "engines": {
+    "node": ">=24.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LegendApp/legend-spark.git",
+    "directory": "packages/create-spark"
+  },
+  "dependencies": {
+    "cross-spawn": "7.0.6",
+    "expo-desktop": "1.0.0",
+    "npm": "11.21.1",
+    "yaml": "2.9.1"
+  }
+}

package/templates/blank-typescript/.claude/skills/spark/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: spark
+description: Develop, build, diagnose, or upgrade a Legend Spark desktop app.
+---
+
+<!-- spark:skill:start -->
+From the app root, read [Spark's app development skill](node_modules/@legendapp/spark/skills/spark/SKILL.md) before working on this app.
+The installed Spark version owns these instructions; do not copy them here.
+<!-- spark:skill:end -->

package/templates/blank-typescript/AGENTS.md

@@ -0,0 +1,4 @@
+<!-- spark:skill:start -->
+From the app root, read [Spark's app development skill](node_modules/@legendapp/spark/skills/spark/SKILL.md) before working on this app.
+The installed Spark version owns these instructions; do not copy them here.
+<!-- spark:skill:end -->

package/templates/blank-typescript/App.tsx

@@ -0,0 +1,23 @@
+import React, { useState } from "react";
+import { Button, StyleSheet, Text, View } from "react-native";
+import { openFileDialog } from "@legendapp/spark/dialogs";
+import { useMenu, type MenuRootItem } from "@legendapp/spark/menus";
+
+const menus: MenuRootItem[] = [{ type: "submenu", id: "hello", label: "Hello", items: [{ type: "action", id: "greet", label: "Say Hello" }] }];
+export default function App({ runtime }: { runtime?: { mode: string } }) {
+  const [message, setMessage] = useState("Ready");
+  useMenu({ id: "hello-world", items: menus, onAction: action => { if (action.itemId === "greet") setMessage("Hello from the native menu"); }, onError: error => setMessage(String(error)) });
+  async function chooseFile() {
+    try {
+      const files = await openFileDialog({ title: "Choose a file", multiple: false });
+      setMessage(files.canceled ? "Dialog cancelled" : files.paths.join(", "));
+    } catch (error) { setMessage(String(error)); }
+  }
+  return <View style={styles.root}>
+    <Text style={styles.title}>Hello, Legend Spark</Text>
+    <Text style={styles.text}>Runtime: {runtime?.mode ?? "unknown"}</Text>
+    <Button title="Choose a file" onPress={chooseFile} />
+    <Text style={styles.text} accessible accessibilityLabel={message}>{message}</Text>
+  </View>;
+}
+const styles = StyleSheet.create({ root: { flex: 1, alignItems: "center", justifyContent: "center", gap: 16, backgroundColor: "#f5f5f7" }, text: { color: "#18181b" }, title: { fontSize: 32, fontWeight: "600", color: "#18181b" } });

package/templates/blank-typescript/CLAUDE.md

@@ -0,0 +1,4 @@
+<!-- spark:skill:start -->
+From the app root, read [Spark's app development skill](node_modules/@legendapp/spark/skills/spark/SKILL.md) before working on this app.
+The installed Spark version owns these instructions; do not copy them here.
+<!-- spark:skill:end -->

package/templates/blank-typescript/README.md

@@ -0,0 +1,15 @@
+# Spark app
+
+Run the app with `macos` using your chosen package manager:
+
+```sh
+npm run macos
+```
+
+macOS opens in Spark Runner. Windows requires a custom development build and is
+an unverified preview. JavaScript edits use Fast Refresh. Use `npm run build` for
+a standalone macOS app; native builds require Xcode and CocoaPods.
+
+Use the equivalent `bun run`, `pnpm run`, or `yarn` commands for those managers.
+See [Spark documentation](https://legend.so/spark) for configuration, upgrades,
+platform prerequisites, and distribution.

package/templates/blank-typescript/app.json

@@ -0,0 +1,11 @@
+{
+  "expo": {
+    "name": "HelloWorld",
+    "slug": "helloworld",
+    "version": "0.0.1",
+    "platforms": [
+      "macos"
+    ],
+    "icon": "./assets/icon.png"
+  }
+}

package/templates/blank-typescript/desktop.config.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "./node_modules/@legendapp/spark/schema.json",
+  "name": "HelloWorld",
+  "version": "0.0.1",
+  "window": {
+    "size": {
+      "width": 1000,
+      "height": 700
+    },
+    "restoreBounds": true
+  },
+  "macos": {
+    "bundleIdentifier": "so.legend.spark.prototype.helloworld"
+  },
+  "platforms": [
+    "macos"
+  ],
+  "expo": {
+    "icon": "./assets/icon.png"
+  }
+}

package/templates/blank-typescript/gitignore

@@ -0,0 +1,8 @@
+node_modules/
+.threaded-runtime/
+.spark/
+macos/
+dist/
+app.json
+windows/
+.expo/

package/templates/blank-typescript/index.ts

@@ -0,0 +1,5 @@
+require("@legendapp/spark/runtime-entry");
+if (!(globalThis as any).__THREADED_RUNTIME_ENV__) {
+  const { registerRootComponent } = require("expo");
+  registerRootComponent(require("./App").default);
+}

package/templates/blank-typescript/metro.config.js

@@ -0,0 +1,3 @@
+const { makeMetroConfig } = require("expo-desktop-metro-config");
+const { withDesktop } = require("@legendapp/spark/metro");
+module.exports = withDesktop(makeMetroConfig(__dirname));

package/templates/blank-typescript/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "spark-template-blank-typescript",
+  "version": "0.0.1",
+  "private": true,
+  "main": "index.ts",
+  "scripts": {
+    "start": "spark dev",
+    "macos": "spark dev",
+    "dev": "spark dev",
+    "build": "spark build",
+    "package": "spark package",
+    "doctor": "spark doctor",
+    "postinstall": "node node_modules/@legendapp/spark/init-template.cjs"
+  },
+  "dependencies": {
+    "@legendapp/spark": "0.0.1-next.5",
+    "expo": "54.0.37",
+    "expo-desktop": "1.0.0",
+    "expo-desktop-prebuild-config": "1.1.0",
+    "expo-desktop-config-plugins": "1.2.0",
+    "expo-desktop-metro-config": "54.81.0",
+    "expo-desktop-template-bare-minimum": "54.81.1",
+    "react": "19.1.4",
+    "react-dom": "19.1.4",
+    "react-native": "0.81.6",
+    "react-native-macos": "0.81.7",
+    "@react-native-community/cli": "20.1.3",
+    "typescript": "5.9.3",
+    "@types/react": "19.1.10",
+    "@react-native-runtimes/core": "0.1.0-alpha.2"
+  },
+  "overrides": {
+    "@expo/cli": "54.0.27",
+    "react-native-nitro-modules": "0.37.0",
+    "react-native-webview": "16.0.0",
+    "@op-engineering/op-sqlite": "18.2.1",
+    "expo-asset": "12.0.13",
+    "expo-constants": "18.0.14",
+    "expo-file-system": "19.0.24",
+    "expo-font": "14.0.12",
+    "expo-keep-awake": "15.0.8",
+    "expo-modules-core": "3.0.30",
+    "expo-desktop-modules-core": "54.0.14",
+    "expo-desktop-stubs": "54.0.14",
+    "react": "19.1.4",
+    "react-native": "0.81.6",
+    "react-native-macos": "0.81.7",
+    "react-native-windows": "0.81.35",
+    "postcss": "8.5.31",
+    "dompurify": "3.4.17",
+    "@tiptap/core": "3.32.0",
+    "@tiptap/extension-blockquote": "3.32.0",
+    "@tiptap/extension-bold": "3.32.0",
+    "@tiptap/extension-code": "3.32.0",
+    "@tiptap/extension-document": "3.32.0",
+    "@tiptap/extension-heading": "3.32.0",
+    "@tiptap/extension-history": "3.32.0",
+    "@tiptap/extension-image": "3.32.0",
+    "@tiptap/extension-italic": "3.32.0",
+    "@tiptap/extension-link": "3.32.0",
+    "@tiptap/extension-list": "3.32.0",
+    "@tiptap/extension-paragraph": "3.32.0",
+    "@tiptap/extension-strike": "3.32.0",
+    "@tiptap/extension-text": "3.32.0",
+    "@tiptap/extension-text-align": "3.32.0",
+    "@tiptap/extension-underline": "3.32.0",
+    "@tiptap/extensions": "3.32.0",
+    "@tiptap/pm": "3.32.0",
+    "@tiptap/react": "3.32.0",
+    "@tiptap/extension-bubble-menu": "3.32.0",
+    "@tiptap/extension-floating-menu": "3.32.0",
+    "fast-xml-parser": "5.11.2",
+    "react-dom": "19.1.4"
+  },
+  "expo": {
+    "install": {
+      "exclude": [
+        "react",
+        "react-dom",
+        "react-native"
+      ]
+    }
+  },
+  "allowScripts": {
+    "@legendapp/spark": true,
+    "react-native-enriched-markdown": true,
+    "fsevents": true
+  },
+  "trustedDependencies": [
+    "@legendapp/spark",
+    "react-native-enriched-markdown",
+    "fsevents"
+  ],
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@legendapp/spark",
+      "react-native-enriched-markdown",
+      "fsevents"
+    ]
+  }
+}

package/templates/blank-typescript/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx"
+  ]
+}

package/templates/diff-lite/App.tsx

@@ -0,0 +1,34 @@
+import { useMemo, useState } from "react";
+import { FlatList, SafeAreaView, StyleSheet, Text, View } from "react-native";
+import { Button } from "@legendapp/spark/ui";
+import { io } from "./shared/io";
+import { Lifecycle } from "./shared/Lifecycle";
+import { compare } from "./compare";
+import { Git } from "./Git";
+const clean = () => false, flush = async () => true;
+export default function App({ windowId = "main" }: { windowId?: string }) {
+  const [left, setLeft] = useState({ name: "Original", text: "A shared application\nNative platform behavior\n" });
+  const [right, setRight] = useState({ name: "Changed", text: "A shared application\nNative platform behavior\nOne codebase\n" });
+  const [error, setError] = useState<string | null>(null);
+  const [patch, setPatch] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const commands = useMemo(() => [{ id: "open", title: "Open original…", key: "O", run: () => open("left") }], []);
+  async function open(side: "left" | "right") {
+    setBusy(true); setError(null);
+    try { const file = await io.open(); if (file) { if (file.text.length > 200_000) throw new Error("Choose a file smaller than 200,000 characters."); (side === "left" ? setLeft : setRight)({ name: file.file.name, text: file.text }); setPatch(null); } }
+    catch (error) { setError(String(error)); } finally { setBusy(false); }
+  }
+  const comparison = useMemo(() => { try { return { rows: compare(left.text, right.text), error: null }; } catch (error) { return { rows: [], error: String(error) }; } }, [left.text, right.text]);
+  const patchLines = useMemo(() => patch?.split("\n"), [patch]);
+  return <SafeAreaView style={styles.root}>
+    <Lifecycle title="Diff" windowId={windowId} flush={flush} dirty={clean} commands={commands} onError={setError} />
+    <Text style={styles.title}>Diff</Text><Text>{left.name} → {right.name}</Text>
+    <View style={styles.toolbar}><Button disabled={busy} onPress={() => { void open("left"); }}>Open original</Button><Button disabled={busy} onPress={() => { void open("right"); }}>Open changed</Button><Button onPress={() => { setLeft(right); setRight(left); setPatch(null); }}>Swap files</Button><Git onResult={setPatch} onError={setError} /></View>
+    <Text>− Removed · + Added · unchanged lines have no marker</Text>
+    {error || comparison.error ? <Text accessibilityRole="alert" style={styles.error}>{error ?? comparison.error}</Text> : null}
+    {patchLines ? <FlatList data={patchLines} keyExtractor={(_, index) => String(index)} renderItem={({ item }) => <Text selectable style={styles.code}>{item || " "}</Text>} /> : <FlatList data={comparison.rows} keyExtractor={(_, index) => String(index)} renderItem={({ item }) => <View style={[styles.line, item.kind === "added" && styles.added, item.kind === "removed" && styles.removed]}>
+      <Text style={styles.number}>{item.left ?? ""}</Text><Text style={styles.number}>{item.right ?? ""}</Text><Text selectable style={styles.code}>{item.kind === "added" ? "+ " : item.kind === "removed" ? "− " : "  "}{item.text || " "}</Text>
+    </View>} />}
+  </SafeAreaView>;
+}
+const styles = StyleSheet.create({ root: { flex: 1, padding: 20, gap: 12, backgroundColor: "#faf9f6" }, title: { fontSize: 28, fontWeight: "600", color: "#222" }, toolbar: { flexDirection: "row", flexWrap: "wrap", gap: 8 }, line: { flexDirection: "row", paddingVertical: 3 }, number: { width: 36, color: "#555", textAlign: "right", paddingRight: 8, fontSize: 12 }, code: { flex: 1, flexShrink: 1, fontFamily: "monospace", fontSize: 13, color: "#222" }, added: { backgroundColor: "#ddf4df" }, removed: { backgroundColor: "#f9dddd" }, error: { color: "#a32020" } });

package/templates/diff-lite/Git.macos.tsx

@@ -0,0 +1,13 @@
+import { useState } from "react";
+import { Button } from "@legendapp/spark/ui";
+import { openFileDialog } from "@legendapp/spark/dialogs";
+import { runCommand } from "@legendapp/spark/processes";
+export function Git({ onResult, onError }: { onResult(text: string): void; onError(message: string): void }) {
+  const [busy, setBusy] = useState(false);
+  return <Button disabled={busy} onPress={() => { setBusy(true); void (async () => {
+    const paths = await openFileDialog({ selection: "directories" }); if (paths.canceled) return;
+    const result = await runCommand({ executable: "/usr/bin/git", args: ["--no-pager", "diff", "--no-ext-diff", "--no-textconv", "--", "."], cwd: paths.paths[0], timeoutMs: 10_000 });
+    if (result.timedOut || result.outputTruncated || result.exitCode !== 0) throw new Error(result.stderr || "Git comparison failed or exceeded its output limit");
+    onResult(result.stdout || "No unstaged changes.");
+  })().catch(error => onError(String(error))).finally(() => setBusy(false)); }}>{busy ? "Reading Git…" : "Open Git changes"}</Button>;
+}

package/templates/diff-lite/Git.tsx

@@ -0,0 +1 @@
+export function Git(_props: { onResult(text: string): void; onError(message: string): void }) { return null; }

package/templates/diff-lite/compare.ts

@@ -0,0 +1,12 @@
+import { diffLines } from "diff";
+export type DiffLine = { kind: "same" | "added" | "removed"; text: string; left: number | null; right: number | null };
+export function compare(left: string, right: string): DiffLine[] {
+  if (left.length + right.length > 400_000) throw new Error("Choose text files smaller than 200,000 characters each for this example.");
+  const changes = diffLines(left, right, { timeout: 300 });
+  if (!changes) throw new Error("These files take too long to compare. Try a smaller selection.");
+  let a = 0, b = 0;
+  return changes.flatMap(change => {
+    const lines = change.value.split("\n"); if (lines.at(-1) === "") lines.pop();
+    return lines.map(text => ({ kind: change.added ? "added" as const : change.removed ? "removed" as const : "same" as const, text, left: change.added ? null : ++a, right: change.removed ? null : ++b }));
+  });
+}

package/templates/document-editor/App.tsx

@@ -0,0 +1,34 @@
+import { useState } from "react";
+import { Platform, SafeAreaView, StyleSheet, Text, TextInput, View } from "react-native";
+import { Button } from "@legendapp/spark/ui";
+import { Integration } from "./Integration";
+import { sessionFor } from "./sessions";
+import { useDocument } from "./useDocument";
+export default function App({ windowId = "main", windowProps }: { windowId?: string; windowProps?: { documentId?: string } }) {
+  const documentId = windowProps?.documentId ?? "main";
+  const [session] = useState(() => sessionFor(documentId));
+  const state = useDocument(session);
+  const [guardsReady, setGuardsReady] = useState(Platform.OS !== "macos");
+  const copy = ["ios", "android", "web"].includes(Platform.OS);
+  return <SafeAreaView style={styles.root}>
+    <View style={styles.header}>
+      <Text style={styles.title}>{state.file.name}{session.dirty ? " •" : ""}</Text>
+      <Text>{copy ? "Open imports a copy. Save exports your text." : state.file.location ?? "Choose a location when saving."}</Text>
+      <View style={styles.toolbar}>
+        <Button disabled={state.busy || !guardsReady} onPress={() => { void session.newDocument(); }}>New</Button>
+        <Button disabled={state.busy || !guardsReady} onPress={() => { void session.open(); }}>Open</Button>
+        <Button disabled={state.busy || !guardsReady} onPress={() => { void session.save(); }}>{copy ? "Save a copy" : "Save"}</Button>
+        {!copy ? <Button disabled={state.busy || !guardsReady} onPress={() => { void session.save(true); }}>Save As</Button> : null}
+      </View>
+      <Integration session={session} windowId={windowId} documentId={documentId} onReady={setGuardsReady} />
+      {state.error ? <Text accessibilityRole="alert" style={styles.error}>{state.error}</Text> : null}
+    </View>
+    <TextInput testID="document-body" accessibilityLabel="Document text" multiline editable={guardsReady} value={state.text} onChangeText={session.edit} textAlignVertical="top" style={styles.editor} autoCapitalize="none" autoCorrect={false} />
+    <Text style={styles.status}>{state.busy ? "Working…" : session.dirty ? "Unsaved changes" : "Saved"} · {state.text.length} characters</Text>
+  </SafeAreaView>;
+}
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: "#faf9f6" }, header: { padding: 20, gap: 10 }, title: { fontSize: 24, fontWeight: "600", color: "#222" },
+  toolbar: { flexDirection: "row", flexWrap: "wrap", gap: 8 }, editor: { flex: 1, marginHorizontal: 20, padding: 16, borderWidth: 1, borderColor: "#bbb", borderRadius: 6, backgroundColor: "white", color: "#222", fontSize: 16 },
+  error: { color: "#ad2020" }, status: { padding: 16, color: "#555" },
+});

package/templates/document-editor/Integration.macos.tsx

@@ -0,0 +1,59 @@
+import { useEffect, useState } from "react";
+import { Text } from "react-native";
+import { Button } from "@legendapp/spark/ui";
+import { beforeWindowClose, openWindow, setWindowOptions, addWindowListener } from "@legendapp/spark/windows";
+import { beforeQuit } from "@legendapp/spark/app";
+import { useMenu, type MenuItem } from "@legendapp/spark/menus";
+import { registerShortcut } from "@legendapp/spark/shortcuts";
+import { subscribeToOpenRequests } from "@legendapp/spark/app/documents";
+import { readText } from "@legendapp/spark/files";
+import { sessions } from "./sessions";
+import type { DocumentSession } from "./document";
+const items: MenuItem[] = [{ type: "submenu", id: "file", target: { menu: "file" }, label: "File", items: [
+  { type: "action", id: "new", label: "New" }, { type: "action", id: "open", label: "Open…" }, { type: "action", id: "save", label: "Save" }, { type: "action", id: "saveAs", label: "Save As…" },
+] }];
+let nextWindow = 0;
+export function Integration({ session, windowId, documentId, onReady }: { session: DocumentSession; windowId: string; documentId: string; onReady: (ready: boolean) => void }) {
+  const [error, setError] = useState<string | null>(null);
+  const menu = useMenu({ id: `editor-${windowId}`, items, onAction: event => {
+    const actions: Record<string, () => unknown> = { new: () => session.newDocument(), open: () => session.open(), save: () => session.save(), saveAs: () => session.save(true) };
+    actions[event.itemId]?.();
+  }, onError: error => setError(String(error)) });
+  useEffect(() => {
+    if (menu.status !== "ready") return;
+    let disposed = false, focus: Awaited<ReturnType<typeof addWindowListener>> | undefined;
+    void addWindowListener(windowId, "focusChanged", event => { if (event.focused) void menu.menu.update({ items }).catch(error => setError(String(error))); }).then(value => { if (disposed) void value.remove(); else focus = value; }).catch(error => setError(String(error)));
+    return () => { disposed = true; void focus?.remove(); };
+  }, [menu, windowId]);
+  useEffect(() => {
+    let removed = false;
+    const cleanups: (() => void | Promise<void>)[] = [];
+    const retain = async (registration: Promise<{ remove(): void | Promise<void> }>) => {
+      const subscription = await registration;
+      if (removed) await subscription.remove(); else cleanups.push(() => subscription.remove());
+    };
+    const actions: Record<string, () => unknown> = { new: () => session.newDocument(), open: () => session.open(), save: () => session.save(), saveAs: () => session.save(true) };
+    const title = () => { const state = session.getSnapshot(); void setWindowOptions(windowId, { title: `${state.file.name}${session.dirty ? " •" : ""}` }).catch(e => setError(String(e))); };
+    title(); cleanups.push(session.subscribe(title));
+    void (async () => {
+      await retain(beforeWindowClose(windowId, session.canClose));
+      for (const [key, action] of Object.entries({ "Command+N": actions.new!, "Command+O": actions.open!, "Command+S": actions.save!, "Command+Shift+S": actions.saveAs! })) {
+        await retain(registerShortcut(key, () => { action(); }, { windowId }));
+      }
+      if (windowId === "main") {
+        await retain(beforeQuit(async () => { for (const document of sessions.values()) if (!await document.canClose()) return false; return true; }));
+        await retain(subscribeToOpenRequests(event => {
+          if (event.type !== "file") return;
+          const location = event.path;
+          void readText(location).then(text => session.load({ location, name: location.split("/").pop()! }, text)).catch(e => setError(String(e)));
+        }));
+      }
+      if (!removed) onReady(true);
+    })().catch(e => setError(String(e)));
+    return () => { removed = true; for (const cleanup of cleanups.reverse()) void Promise.resolve().then(cleanup).catch(console.error); };
+  }, [session, windowId, onReady]);
+  return <>
+    <Button onPress={() => { const id = `document-${++nextWindow}`; void openWindow({ id, title: session.getSnapshot().file.name, component: "main", size: { width: 800, height: 600 }, props: { windowId: id, windowProps: { documentId } } }).catch(e => setError(String(e))); }}>Open another view</Button>
+    {error ? <Text accessibilityRole="alert">{error}</Text> : null}
+  </>;
+}

package/templates/document-editor/Integration.tsx

@@ -0,0 +1,13 @@
+import { useEffect } from "react";
+import { BackHandler } from "react-native";
+import type { DocumentSession } from "./document";
+export function Integration({ session }: { session: DocumentSession; windowId: string; documentId: string; onReady: (ready: boolean) => void }) {
+  useEffect(() => {
+    const back = BackHandler.addEventListener("hardwareBackPress", () => {
+      if (!session.dirty) return false;
+      void session.canClose().then(allow => { if (allow) BackHandler.exitApp(); }); return true;
+    });
+    return () => back.remove();
+  }, [session]);
+  return null;
+}

package/templates/document-editor/Integration.web.tsx

@@ -0,0 +1,14 @@
+import { useEffect } from "react";
+import type { DocumentSession } from "./document";
+export function Integration({ session }: { session: DocumentSession; windowId: string; documentId: string; onReady: (ready: boolean) => void }) {
+  useEffect(() => {
+    const unload = (event: BeforeUnloadEvent) => { if (session.dirty) { event.preventDefault(); event.returnValue = ""; } };
+    const key = (event: KeyboardEvent) => {
+      if (!(event.metaKey || event.ctrlKey) || !["s", "o"].includes(event.key.toLowerCase())) return;
+      event.preventDefault(); if (event.key.toLowerCase() === "s") void session.save(event.shiftKey); else void session.open();
+    };
+    window.addEventListener("beforeunload", unload); window.addEventListener("keydown", key);
+    return () => { window.removeEventListener("beforeunload", unload); window.removeEventListener("keydown", key); };
+  }, [session]);
+  return null;
+}

package/templates/document-editor/Integration.windows.tsx

@@ -0,0 +1,59 @@
+import { useEffect, useState } from "react";
+import { Text } from "react-native";
+import { Button } from "@legendapp/spark/ui";
+import { beforeWindowClose, openWindow, setWindowOptions, addWindowListener } from "@legendapp/spark/windows";
+import { beforeQuit } from "@legendapp/spark/app";
+import { useMenu, type MenuItem } from "@legendapp/spark/menus";
+import { registerShortcut } from "@legendapp/spark/shortcuts";
+import { subscribeToOpenRequests } from "@legendapp/spark/app/documents";
+import { readText } from "@legendapp/spark/files";
+import { sessions } from "./sessions";
+import type { DocumentSession } from "./document";
+const items: MenuItem[] = [{ type: "submenu", id: "file", target: { menu: "file" }, label: "File", items: [
+  { type: "action", id: "new", label: "New" }, { type: "action", id: "open", label: "Open…" }, { type: "action", id: "save", label: "Save" }, { type: "action", id: "saveAs", label: "Save As…" },
+] }];
+let nextWindow = 0;
+export function Integration({ session, windowId, documentId, onReady }: { session: DocumentSession; windowId: string; documentId: string; onReady: (ready: boolean) => void }) {
+  const [error, setError] = useState<string | null>(null);
+  const menu = useMenu({ id: `editor-${windowId}`, items, onAction: event => {
+    const actions: Record<string, () => unknown> = { new: () => session.newDocument(), open: () => session.open(), save: () => session.save(), saveAs: () => session.save(true) };
+    actions[event.itemId]?.();
+  }, onError: error => setError(String(error)) });
+  useEffect(() => {
+    if (menu.status !== "ready") return;
+    let disposed = false, focus: Awaited<ReturnType<typeof addWindowListener>> | undefined;
+    void addWindowListener(windowId, "focusChanged", event => { if (event.focused) void menu.menu.update({ items }).catch(error => setError(String(error))); }).then(value => { if (disposed) void value.remove(); else focus = value; }).catch(error => setError(String(error)));
+    return () => { disposed = true; void focus?.remove(); };
+  }, [menu, windowId]);
+  useEffect(() => {
+    let removed = false;
+    const cleanups: (() => void | Promise<void>)[] = [];
+    const retain = async (registration: Promise<{ remove(): void | Promise<void> }>) => {
+      const subscription = await registration;
+      if (removed) await subscription.remove(); else cleanups.push(() => subscription.remove());
+    };
+    const actions: Record<string, () => unknown> = { new: () => session.newDocument(), open: () => session.open(), save: () => session.save(), saveAs: () => session.save(true) };
+    const title = () => { const state = session.getSnapshot(); void setWindowOptions(windowId, { title: `${state.file.name}${session.dirty ? " •" : ""}` }).catch(e => setError(String(e))); };
+    title(); cleanups.push(session.subscribe(title));
+    void (async () => {
+      await retain(beforeWindowClose(windowId, session.canClose));
+      for (const [key, action] of Object.entries({ "Control+N": actions.new!, "Control+O": actions.open!, "Control+S": actions.save!, "Control+Shift+S": actions.saveAs! })) {
+        await retain(registerShortcut(key, () => { action(); }, { windowId }));
+      }
+      if (windowId === "main") {
+        await retain(beforeQuit(async () => { for (const document of sessions.values()) if (!await document.canClose()) return false; return true; }));
+        await retain(subscribeToOpenRequests(event => {
+          if (event.type !== "file") return;
+          const location = event.path;
+          void readText(location).then(text => session.load({ location, name: location.split("/").pop()! }, text)).catch(e => setError(String(e)));
+        }));
+      }
+      if (!removed) onReady(true);
+    })().catch(e => setError(String(e)));
+    return () => { removed = true; for (const cleanup of cleanups.reverse()) void Promise.resolve().then(cleanup).catch(console.error); };
+  }, [session, windowId, onReady]);
+  return <>
+    <Button onPress={() => { const id = `document-${++nextWindow}`; void openWindow({ id, title: session.getSnapshot().file.name, component: "main", size: { width: 800, height: 600 }, props: { windowId: id, windowProps: { documentId } } }).catch(e => setError(String(e))); }}>Open another view</Button>
+    {error ? <Text accessibilityRole="alert">{error}</Text> : null}
+  </>;
+}

package/templates/document-editor/document.ts

@@ -0,0 +1,58 @@
+export type FileReference = { name: string; location?: string; handle?: unknown };
+export type DocumentState = { text: string; savedText: string; file: FileReference; busy: boolean; error: string | null; revision: number };
+export type DocumentIO = {
+  open(): Promise<{ file: FileReference; text: string } | null>;
+  save(file: FileReference, text: string, expected: string, saveAs: boolean): Promise<FileReference | null>;
+  confirmDiscard(name: string): Promise<"save" | "discard" | "cancel">;
+};
+/** One document model is shared by its windows; I/O always works on a snapshot. */
+export class DocumentSession {
+  private state: DocumentState = { text: "", savedText: "", file: { name: "Untitled.txt" }, busy: false, error: null, revision: 0 };
+  private listeners = new Set<() => void>();
+  private active = false;
+  constructor(readonly io: DocumentIO) {}
+  getSnapshot = () => this.state;
+  subscribe = (listener: () => void) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+  private update(patch: Partial<DocumentState>) { this.state = { ...this.state, ...patch }; for (const listener of this.listeners) listener(); }
+  edit = (text: string) => { if (text !== this.state.text) this.update({ text, revision: this.state.revision + 1 }); };
+  get dirty() { return this.state.text !== this.state.savedText; }
+  private async operation(action: () => Promise<boolean>) {
+    if (this.active) return false;
+    this.active = true; this.update({ busy: true, error: null });
+    try { return await action(); }
+    catch (error) { this.update({ error: error instanceof Error ? error.message : String(error) }); return false; }
+    finally { this.active = false; this.update({ busy: false }); }
+  }
+  private async saveSnapshot(saveAs: boolean) {
+    const snapshot = this.state;
+    const file = await this.io.save(snapshot.file, snapshot.text, snapshot.savedText, saveAs);
+    if (!file) return false;
+    // Edits typed during an asynchronous save remain dirty.
+    this.update({ file, savedText: snapshot.text }); return true;
+  }
+  save = (saveAs = false) => this.operation(() => this.saveSnapshot(saveAs));
+  private async mayReplace() {
+    if (!this.dirty) return true;
+    const revision = this.state.revision;
+    const answer = await this.io.confirmDiscard(this.state.file.name);
+    if (answer === "cancel") return false;
+    if (answer === "save") return await this.saveSnapshot(false) && !this.dirty;
+    return revision === this.state.revision;
+  }
+  canClose = () => this.operation(() => this.mayReplace());
+  newDocument = () => this.operation(async () => {
+    if (!await this.mayReplace()) return false;
+    this.update({ text: "", savedText: "", file: { name: "Untitled.txt" }, revision: this.state.revision + 1 }); return true;
+  });
+  open = () => this.operation(async () => {
+    if (!await this.mayReplace()) return false;
+    const revision = this.state.revision;
+    const loaded = await this.io.open();
+    if (!loaded || revision !== this.state.revision) return false;
+    this.update({ file: loaded.file, text: loaded.text, savedText: loaded.text, revision: revision + 1 }); return true;
+  });
+  load = (file: FileReference, text: string) => this.operation(async () => {
+    if (!await this.mayReplace()) return false;
+    this.update({ file, text, savedText: text, revision: this.state.revision + 1 }); return true;
+  });
+}

package/templates/document-editor/io.desktop.ts

@@ -0,0 +1,27 @@
+import { openFileDialog, saveFileDialog } from "@legendapp/spark/dialogs";
+import { readText, writeText, writeTextIfUnchanged } from "@legendapp/spark/files";
+import { Alert } from "react-native";
+import type { DocumentIO } from "./document";
+export const io: DocumentIO = {
+  async open() {
+    const paths = await openFileDialog({ filters: [{ extensions: ["txt", "md", "json"] }], multiple: false });
+    if (paths.canceled) return null;
+    const location = paths.paths[0];
+    return { file: { location, name: location.split(/[\\/]/).pop()! }, text: await readText(location) };
+  },
+  async save(file, text, expected, saveAs) {
+    const result = saveAs || !file.location ? await saveFileDialog({ defaultName: file.name, filters: [{ extensions: ["txt", "md", "json"] }] }) : { canceled: false as const, path: file.location };
+    if (result.canceled) return null;
+    const location = result.path;
+    if (!location) return null;
+    if (location === file.location) {
+      if (!(await writeTextIfUnchanged(location, expected, text)).written) throw new Error("The file changed outside the editor. Use Save As to keep your edits in another file.");
+    } else await writeText(location, text);
+    return { location, name: location.split(/[\\/]/).pop()! };
+  },
+  confirmDiscard: name => new Promise(resolve => Alert.alert("Unsaved changes", `Save changes to ${name}?`, [
+    { text: "Cancel", style: "cancel", onPress: () => resolve("cancel") },
+    { text: "Discard", style: "destructive", onPress: () => resolve("discard") },
+    { text: "Save", onPress: () => resolve("save") },
+  ], { cancelable: false })),
+};