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

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 })),
+};

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

@@ -0,0 +1,7 @@
+import { io as desktop } from "./io.desktop";
+import { showMessage } from "@legendapp/spark/dialogs";
+import type { DocumentIO } from "./document";
+export const io: DocumentIO = { ...desktop, async confirmDiscard(name) {
+  const { buttonId } = await showMessage({ title: "Unsaved changes", message: `Save changes to ${name}?`, buttons: [{ id: "cancel", label: "Cancel" }, { id: "discard", label: "Discard" }, { id: "save", label: "Save" }], cancelButtonId: "cancel", defaultButtonId: "save" });
+  return buttonId === "save" ? "save" : buttonId === "discard" ? "discard" : "cancel";
+} };

package/templates/document-editor/io.ts

@@ -0,0 +1,31 @@
+import * as DocumentPicker from "expo-document-picker";
+import * as FileSystem from "expo-file-system/legacy";
+import * as Sharing from "expo-sharing";
+import { Alert } from "react-native";
+import type { DocumentIO } from "./document";
+export const io: DocumentIO = {
+  async open() {
+    const result = await DocumentPicker.getDocumentAsync({ type: ["text/*", "application/json"], copyToCacheDirectory: true });
+    if (result.canceled) return null;
+    const asset = result.assets[0]!;
+    if ((asset.size ?? 0) > 8 * 1024 * 1024) throw new Error("Choose a text file smaller than 8 MB");
+    // The picker returns an imported copy, not permission to overwrite the source.
+    return { file: { name: asset.name }, text: await FileSystem.readAsStringAsync(asset.uri) };
+  },
+  async save(file, text) {
+    if (!await Sharing.isAvailableAsync()) throw new Error("File sharing is unavailable on this device");
+    const directory = FileSystem.documentDirectory;
+    if (!directory) throw new Error("Document storage is unavailable");
+    const name = file.name.replace(/[^a-zA-Z0-9._-]/g, "_") || "Untitled.txt";
+    const location = `${directory}spark-${name}`;
+    await FileSystem.writeAsStringAsync(location, text);
+    await Sharing.shareAsync(location, { mimeType: "text/plain", UTI: "public.plain-text" });
+    // Save commits the app's durable copy, regardless of share-sheet dismissal.
+    return { name: file.name, location };
+  },
+  confirmDiscard: name => new Promise(resolve => Alert.alert("Unsaved changes", `Save a copy of ${name}?`, [
+    { text: "Cancel", style: "cancel", onPress: () => resolve("cancel") },
+    { text: "Discard", style: "destructive", onPress: () => resolve("discard") },
+    { text: "Save", onPress: () => resolve("save") },
+  ], { cancelable: false })),
+};

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

@@ -0,0 +1,21 @@
+import type { DocumentIO } from "./document";
+export const io: DocumentIO = {
+  open: () => new Promise((resolve, reject) => {
+    const input = document.createElement("input"); input.type = "file"; input.accept = ".txt,.md,.json,text/plain";
+    input.oncancel = () => resolve(null);
+    input.onchange = () => {
+      const file = input.files?.[0];
+      if (!file) { resolve(null); return; }
+      if (file.size > 8 * 1024 * 1024) { reject(new Error("Choose a text file smaller than 8 MB")); return; }
+      void file.text().then(text => resolve({ file: { name: file.name }, text }), reject);
+    };
+    input.click();
+  }),
+  async save(file, text) {
+    const url = URL.createObjectURL(new Blob([text], { type: "text/plain;charset=utf-8" }));
+    const anchor = document.createElement("a"); anchor.href = url; anchor.download = file.name; anchor.click();
+    setTimeout(() => URL.revokeObjectURL(url), 30_000);
+    return { name: file.name };
+  },
+  async confirmDiscard(name) { return window.confirm(`Discard unsaved changes to ${name}? Choose Cancel to return and save.`) ? "discard" : "cancel"; },
+};

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

@@ -0,0 +1 @@
+export { io } from "./io.desktop";

package/templates/document-editor/sessions.ts

@@ -0,0 +1,8 @@
+import { DocumentSession } from "./document";
+import { io } from "./io";
+// Secondary macOS roots share this JS heap and therefore the same document data.
+export const sessions = new Map<string, DocumentSession>();
+export function sessionFor(id: string) {
+  if (!sessions.has(id)) sessions.set(id, new DocumentSession(io));
+  return sessions.get(id)!;
+}

package/templates/document-editor/useDocument.ts

@@ -0,0 +1,6 @@
+import { useSyncExternalStore } from "react";
+import type { DocumentSession } from "./document";
+/** React adapter for the document model shared by native window roots. */
+export function useDocument(session: DocumentSession) {
+  return useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+}

package/templates/example-shared/Lifecycle.desktop.tsx

@@ -0,0 +1,25 @@
+import { useEffect } from "react";
+import { Platform } from "react-native";
+import { beforeWindowClose, setWindowOptions, addWindowListener } from "@legendapp/spark/windows";
+import { beforeQuit } from "@legendapp/spark/app";
+import { createMenu, type MenuItem } from "@legendapp/spark/menus";
+import { registerShortcut } from "@legendapp/spark/shortcuts";
+import { mountSerial } from "./lifetime";
+import type { LifecycleProps } from "./lifecycle-types";
+export function Lifecycle({ title, windowId = "main", flush, quit, commands, onError }: LifecycleProps) {
+  useEffect(() => { void setWindowOptions(windowId, { title: title }).catch(error => onError(String(error))); }, [title, windowId, onError]);
+  useEffect(() => mountSerial(`window-${windowId}`, async retain => {
+    const owner = `example-${windowId}`;
+    const items: MenuItem[] = [{ type: "submenu", id: "file", target: { menu: "file" }, label: "File", items: commands.map(({ id, title, key }) => ({ type: "action", id, label: title, shortcut: `CmdOrCtrl+${key}` })) }];
+    const menu = await createMenu({ id: owner, items, onAction: event => { commands.find(command => command.id === event.itemId)?.run(); } });
+    await retain(Promise.resolve(menu));
+    await retain(addWindowListener(windowId, "focusChanged", event => { if (event.focused) void menu.update({ items }).catch(error => onError(String(error))); }));
+    const guarded = (save: () => Promise<boolean>) => async () => {
+      try { return await save(); } catch (error) { onError(String(error)); return false; }
+    };
+    await retain(beforeWindowClose(windowId, guarded(flush)));
+    if (windowId === "main") await retain(beforeQuit(guarded(quit ?? flush)));
+    for (const command of commands) await retain(registerShortcut(`${Platform.OS === "windows" ? "Control" : "Command"}+${command.key}`, command.run, { windowId }));
+  }, onError), [windowId, flush, quit, commands, onError]);
+  return null;
+}

package/templates/example-shared/Lifecycle.macos.tsx

@@ -0,0 +1 @@
+export { Lifecycle } from "./Lifecycle.desktop";

package/templates/example-shared/Lifecycle.tsx

@@ -0,0 +1,14 @@
+import { useEffect } from "react";
+import { AppState, BackHandler } from "react-native";
+import type { LifecycleProps } from "./lifecycle-types";
+export function Lifecycle({ flush, dirty }: LifecycleProps) {
+  useEffect(() => {
+    const state = AppState.addEventListener("change", state => { if (state !== "active") void flush(); });
+    const back = BackHandler.addEventListener("hardwareBackPress", () => {
+      if (!dirty()) return false;
+      void flush().then(ok => { if (ok && !dirty()) BackHandler.exitApp(); }); return true;
+    });
+    return () => { state.remove(); back.remove(); };
+  }, [flush, dirty]);
+  return null;
+}

package/templates/example-shared/Lifecycle.web.tsx

@@ -0,0 +1,20 @@
+import { useEffect } from "react";
+import type { LifecycleProps } from "./lifecycle-types";
+export function Lifecycle({ title, dirty, flush, commands }: LifecycleProps) {
+  useEffect(() => { document.title = title; }, [title]);
+  useEffect(() => {
+    const close = (event: BeforeUnloadEvent) => { if (dirty()) { event.preventDefault(); event.returnValue = ""; } };
+    const background = () => { if (document.visibilityState === "hidden") void flush(); };
+    const key = (event: KeyboardEvent) => {
+      if (event.isComposing || event.altKey || !(event.metaKey || event.ctrlKey)) return;
+      const command = commands.find(command => {
+        const parts = command.key.toLowerCase().split("+");
+        return parts.includes("shift") === event.shiftKey && parts.at(-1) === event.key.toLowerCase();
+      });
+      if (command) { event.preventDefault(); command.run(); }
+    };
+    window.addEventListener("beforeunload", close); window.addEventListener("keydown", key); document.addEventListener("visibilitychange", background);
+    return () => { window.removeEventListener("beforeunload", close); window.removeEventListener("keydown", key); document.removeEventListener("visibilitychange", background); };
+  }, [dirty, flush, commands]);
+  return null;
+}

package/templates/example-shared/Lifecycle.windows.tsx

@@ -0,0 +1 @@
+export { Lifecycle } from "./Lifecycle.desktop";

package/templates/example-shared/OpenFiles.desktop.tsx

@@ -0,0 +1,23 @@
+import { useEffect } from "react";
+import { subscribeToOpenRequests } from "@legendapp/spark/app/documents";
+import { mountSerial } from "./lifetime";
+import type { OpenFilesProps } from "./OpenFiles";
+// Each subscription replays queued launches to each subscription. Remounts must not import twice.
+const imported = new Set<string>();
+const importing = new Set<string>();
+export function OpenFiles({ windowId = "main", onFile, onError }: OpenFilesProps) {
+  useEffect(() => {
+    if (windowId !== "main") return;
+    return mountSerial("file-activation", async retain => { await retain(subscribeToOpenRequests(event => {
+      if (event.type !== "file") return;
+      if (imported.has(event.id) || importing.has(event.id)) return;
+      importing.add(event.id);
+      void (async () => {
+        await onFile(event.path);
+        imported.add(event.id);
+        if (imported.size > 200) imported.delete(imported.values().next().value!);
+      })().catch(error => onError(String(error))).finally(() => importing.delete(event.id));
+    })); }, onError);
+  }, [windowId, onFile, onError]);
+  return null;
+}

package/templates/example-shared/OpenFiles.macos.tsx

@@ -0,0 +1 @@
+export { OpenFiles } from "./OpenFiles.desktop";

package/templates/example-shared/OpenFiles.tsx

@@ -0,0 +1,2 @@
+export type OpenFilesProps = { windowId?: string; onFile(path: string): Promise<void>; onError(message: string): void };
+export function OpenFiles(_props: OpenFilesProps) { return null; }

package/templates/example-shared/OpenFiles.windows.tsx

@@ -0,0 +1 @@
+export { OpenFiles } from "./OpenFiles.desktop";

package/templates/example-shared/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/example-shared/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 })),
+};

package/templates/example-shared/io.macos.ts

@@ -0,0 +1,7 @@
+import { io as desktop } from "./io.desktop";
+import { showMessage } from "@legendapp/spark/dialogs";
+import type { DocumentIO } from "./document";
+export const io: DocumentIO = { ...desktop, async confirmDiscard(name) {
+  const { buttonId } = await showMessage({ title: "Unsaved changes", message: `Save changes to ${name}?`, buttons: [{ id: "cancel", label: "Cancel" }, { id: "discard", label: "Discard" }, { id: "save", label: "Save" }], cancelButtonId: "cancel", defaultButtonId: "save" });
+  return buttonId === "save" ? "save" : buttonId === "discard" ? "discard" : "cancel";
+} };

package/templates/example-shared/io.ts

@@ -0,0 +1,31 @@
+import * as DocumentPicker from "expo-document-picker";
+import * as FileSystem from "expo-file-system/legacy";
+import * as Sharing from "expo-sharing";
+import { Alert } from "react-native";
+import type { DocumentIO } from "./document";
+export const io: DocumentIO = {
+  async open() {
+    const result = await DocumentPicker.getDocumentAsync({ type: ["text/*", "application/json"], copyToCacheDirectory: true });
+    if (result.canceled) return null;
+    const asset = result.assets[0]!;
+    if ((asset.size ?? 0) > 8 * 1024 * 1024) throw new Error("Choose a text file smaller than 8 MB");
+    // The picker returns an imported copy, not permission to overwrite the source.
+    return { file: { name: asset.name }, text: await FileSystem.readAsStringAsync(asset.uri) };
+  },
+  async save(file, text) {
+    if (!await Sharing.isAvailableAsync()) throw new Error("File sharing is unavailable on this device");
+    const directory = FileSystem.documentDirectory;
+    if (!directory) throw new Error("Document storage is unavailable");
+    const name = file.name.replace(/[^a-zA-Z0-9._-]/g, "_") || "Untitled.txt";
+    const location = `${directory}spark-${name}`;
+    await FileSystem.writeAsStringAsync(location, text);
+    await Sharing.shareAsync(location, { mimeType: "text/plain", UTI: "public.plain-text" });
+    // Save commits the app's durable copy, regardless of share-sheet dismissal.
+    return { name: file.name, location };
+  },
+  confirmDiscard: name => new Promise(resolve => Alert.alert("Unsaved changes", `Save a copy of ${name}?`, [
+    { text: "Cancel", style: "cancel", onPress: () => resolve("cancel") },
+    { text: "Discard", style: "destructive", onPress: () => resolve("discard") },
+    { text: "Save", onPress: () => resolve("save") },
+  ], { cancelable: false })),
+};

package/templates/example-shared/io.web.ts

@@ -0,0 +1,21 @@
+import type { DocumentIO } from "./document";
+export const io: DocumentIO = {
+  open: () => new Promise((resolve, reject) => {
+    const input = document.createElement("input"); input.type = "file"; input.accept = ".txt,.md,.json,text/plain";
+    input.oncancel = () => resolve(null);
+    input.onchange = () => {
+      const file = input.files?.[0];
+      if (!file) { resolve(null); return; }
+      if (file.size > 8 * 1024 * 1024) { reject(new Error("Choose a text file smaller than 8 MB")); return; }
+      void file.text().then(text => resolve({ file: { name: file.name }, text }), reject);
+    };
+    input.click();
+  }),
+  async save(file, text) {
+    const url = URL.createObjectURL(new Blob([text], { type: "text/plain;charset=utf-8" }));
+    const anchor = document.createElement("a"); anchor.href = url; anchor.download = file.name; anchor.click();
+    setTimeout(() => URL.revokeObjectURL(url), 30_000);
+    return { name: file.name };
+  },
+  async confirmDiscard(name) { return window.confirm(`Discard unsaved changes to ${name}? Choose Cancel to return and save.`) ? "discard" : "cancel"; },
+};

package/templates/example-shared/io.windows.ts

@@ -0,0 +1 @@
+export { io } from "./io.desktop";

package/templates/example-shared/lifecycle-types.ts

@@ -0,0 +1,10 @@
+export type Command = { id: string; title: string; key: string; run(): void };
+export type LifecycleProps = {
+  windowId?: string;
+  title: string;
+  dirty(): boolean;
+  flush(): Promise<boolean>;
+  quit?(): Promise<boolean>;
+  commands: readonly Command[];
+  onError(message: string): void;
+};

package/templates/example-shared/lifetime.ts

@@ -0,0 +1,23 @@
+type Subscription = { remove(): void | Promise<void> };
+const lifetimes = new Map<string, Promise<void>>();
+/** Serialize teardown/re-registration across Strict Mode and Fast Refresh. */
+export function mountSerial(key: string, setup: (retain: (item: Promise<Subscription>) => Promise<void>) => Promise<void>, onError: (message: string) => void) {
+  const previous = lifetimes.get(key) ?? Promise.resolve();
+  let finished!: () => void;
+  const closed = new Promise<void>(resolve => { finished = resolve; });
+  lifetimes.set(key, closed);
+  let removed = false;
+  const subscriptions: Subscription[] = [];
+  const ready = previous.then(async () => {
+    if (removed) return;
+    await setup(async item => { const subscription = await item; if (removed) await subscription.remove(); else subscriptions.push(subscription); });
+  }).catch(error => onError(String(error)));
+  return () => {
+    if (removed) return;
+    removed = true;
+    void ready.then(async () => {
+      try { for (const subscription of subscriptions.reverse()) { try { await subscription.remove(); } catch (error) { onError(String(error)); } } }
+      finally { finished(); if (lifetimes.get(key) === closed) lifetimes.delete(key); }
+    });
+  };
+}

package/templates/example-shared/records.ts

@@ -0,0 +1,51 @@
+export interface RecordStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+type Envelope = { format: 1; revision: number; data: string; checksum: string };
+function checksum(text: string) {
+  let hash = 2166136261;
+  for (let i = 0; i < text.length; i++) hash = Math.imul(hash ^ text.charCodeAt(i), 16777619);
+  return (hash >>> 0).toString(16);
+}
+/** Alternating complete snapshots retain the previous version if a write is interrupted.
+ * One writer per key in this JS runtime; not a cross-process database or encryption.
+ */
+export class Records<T> {
+  private revision = 0;
+  private loaded = false;
+  private tail: Promise<void> = Promise.resolve();
+  constructor(private storage: RecordStorage, private key: string, private decode: (value: unknown) => T) {}
+  async load(): Promise<{ value: T | null; recovered: boolean }> {
+    const raw = await Promise.all([0, 1].map(slot => this.storage.getItem(`${this.key}:${slot}`)));
+    const valid: { revision: number; value: T }[] = [];
+    let invalid = false;
+    for (const text of raw) {
+      if (text === null) continue;
+      let item: Envelope;
+      try {
+        item = JSON.parse(text) as Envelope;
+        if (item.format !== 1 || !Number.isSafeInteger(item.revision) || item.revision < 1 || typeof item.data !== "string" || item.checksum !== checksum(item.data)) throw new Error("Invalid record");
+      } catch { invalid = true; continue; }
+      // A valid envelope with an unknown application schema needs migration, not rollback.
+      valid.push({ revision: item.revision, value: this.decode(JSON.parse(item.data)) });
+    }
+    valid.sort((a, b) => b.revision - a.revision);
+    if (!valid.length && invalid) throw new Error("Stored data could not be read. It has been preserved; restore a backup before editing.");
+    this.revision = valid[0]?.revision ?? 0;
+    this.loaded = true;
+    return { value: valid[0]?.value ?? null, recovered: invalid };
+  }
+  save(value: T): Promise<void> {
+    // Serialize now so later edits cannot change an in-flight snapshot.
+    const data = JSON.stringify(value);
+    const write = this.tail.then(async () => {
+      if (!this.loaded) throw new Error("Load records before saving");
+      const revision = this.revision + 1;
+      await this.storage.setItem(`${this.key}:${revision % 2}`, JSON.stringify({ format: 1, revision, data, checksum: checksum(data) }));
+      this.revision = revision;
+    });
+    this.tail = write.catch(() => {});
+    return write;
+  }
+}

package/templates/example-shared/storage.ts

@@ -0,0 +1,6 @@
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { Records } from "./records";
+import { projectId } from "./identity";
+export function records<T>(name: string, decode: (value: unknown) => T) {
+  return new Records(AsyncStorage, `spark:${projectId.length}:${projectId}:${name}`, decode);
+}

package/templates/example-shared/useModel.ts

@@ -0,0 +1,6 @@
+import { useSyncExternalStore } from "react";
+export interface Model<T> { subscribe(listener: () => void): () => void; getSnapshot(): T }
+/** React adapter for these examples' external application models. */
+export function useModel<T>(model: Model<T>): T {
+  return useSyncExternalStore(model.subscribe, model.getSnapshot, model.getSnapshot);
+}

package/templates/music-lite/Activation.desktop.tsx

@@ -0,0 +1,4 @@
+import { OpenFiles } from "./shared/OpenFiles";
+import { music } from "./store";
+const open = async (uri: string) => { await music.load(); await music.add([{ id: uri, uri, name: uri.split(/[\\/]/).pop()! }]); };
+export function Activation({ windowId, onError }: { windowId: string; onError(message: string): void }) { return <OpenFiles windowId={windowId} onFile={open} onError={onError} />; }

package/templates/music-lite/Activation.macos.tsx

@@ -0,0 +1 @@
+export { Activation } from "./Activation.desktop";

package/templates/music-lite/Activation.tsx

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

package/templates/music-lite/Activation.windows.tsx

@@ -0,0 +1 @@
+export { Activation } from "./Activation.desktop";

package/templates/music-lite/App.tsx

@@ -0,0 +1,38 @@
+import { Activation } from "./Activation";
+import { useEffect, useMemo, useState } from "react";
+import { FlatList, Platform, SafeAreaView, StyleSheet, Text, View } from "react-native";
+import { Button } from "@legendapp/spark/ui";
+import { Lifecycle } from "./shared/Lifecycle";
+import { useModel } from "./shared/useModel";
+import { mountSerial } from "./shared/lifetime";
+import { music, dirty } from "./store";
+import { importTracks } from "./assets";
+const time = (seconds: number) => `${Math.floor(seconds / 60)}:${String(Math.floor(seconds % 60)).padStart(2, "0")}`;
+export default function App({ windowId = "main" }: { windowId?: string }) {
+  const state = useModel(music);
+  const [error, setError] = useState<string | null>(null);
+  const [importing, setImporting] = useState(false);
+  const commands = useMemo(() => [{ id: "import", title: "Import tracks…", key: "O", run: () => {
+    setImporting(true); void importTracks().then(music.add).catch(error => setError(String(error))).finally(() => setImporting(false));
+  } }], []);
+  useEffect(() => mountSerial("music-player", async retain => {
+    await music.load();
+    const timer = setInterval(() => { void music.tick(); }, 500);
+    await retain(Promise.resolve({ remove: async () => { clearInterval(timer); await music.dispose(); } }));
+  }, setError), []);
+  const current = state.tracks.find(track => track.id === state.currentId);
+  return <SafeAreaView style={styles.root}>
+    <Activation windowId={windowId} onError={setError} />
+    <Lifecycle title="Music" windowId={windowId} flush={music.flush} dirty={dirty} commands={commands} onError={setError} />
+    <Text style={styles.title}>Music</Text>
+    <Text>{["macos", "windows"].includes(Platform.OS) ? "Tracks stay in their original location. Keep those files available." : "Imported audio is stored on this device."}</Text>
+    <View style={styles.toolbar}><Button disabled={!state.ready || importing} onPress={commands[0]!.run}>{importing ? "Importing…" : "Import tracks"}</Button></View>
+    {error || state.error ? <Text accessibilityRole="alert" style={styles.error}>{error ?? state.error}</Text> : null}
+    <FlatList data={state.tracks} keyExtractor={track => track.id} extraData={[state.currentId, state.busy]} renderItem={({ item }) => <View style={[styles.track, item.id === state.currentId && styles.current]}><Text style={styles.name} numberOfLines={2}>{item.name}</Text><Button disabled={state.busy} onPress={() => { void music.play(item.id); }}>Play track</Button></View>} ListEmptyComponent={<Text style={styles.empty}>Import a few audio files to start your queue.</Text>} />
+    <View style={styles.player}><Text style={styles.now}>{current?.name ?? "Nothing playing"}</Text><Text accessibilityLiveRegion="none">{time(state.position)} / {time(state.status.duration)}</Text>
+      <View style={styles.toolbar}><Button disabled={state.busy || !state.tracks.length} onPress={() => { void (state.status.playing ? music.pause() : music.play()); }}>{state.status.playing ? "Pause" : "Play"}</Button><Button disabled={state.busy || !current || state.status.duration <= 0} onPress={() => { void music.seek(state.status.currentTime - 10); }}>Back 10 seconds</Button><Button disabled={state.busy || !current || state.status.duration <= 0} onPress={() => { void music.seek(Math.min(state.status.duration, state.status.currentTime + 10)); }}>Forward 10 seconds</Button><Button disabled={state.busy || !current || state.status.duration <= 0} onPress={() => { void music.next(); }}>Next track</Button></View>
+      <Text>{state.dirty ? "Saving playback position…" : "Queue and position saved"}</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 }, track: { flexDirection: "row", alignItems: "center", padding: 12, gap: 12, borderBottomWidth: 1, borderColor: "#ddd" }, name: { flex: 1, fontSize: 16, color: "#222" }, current: { backgroundColor: "#dce9ef" }, player: { padding: 16, gap: 12, backgroundColor: "white", borderRadius: 8 }, now: { fontSize: 18, fontWeight: "600", color: "#222" }, empty: { padding: 24, color: "#555" }, error: { color: "#a32020" } });

package/templates/music-lite/assets.desktop.ts

@@ -0,0 +1,7 @@
+import { openFileDialog } from "@legendapp/spark/dialogs";
+import type { Track } from "./model";
+export async function importTracks(): Promise<Track[]> {
+  const paths = await openFileDialog({ filters: [{ extensions: ["mp3", "m4a", "wav", "aac", "flac", "ogg"] }], multiple: true });
+  return (paths.canceled ? [] : paths.paths).map(uri => ({ id: uri, uri, name: uri.split(/[\\/]/).pop()! }));
+}
+export const resolveTrack = async (track: Track) => ({ uri: track.uri, release() {} });

package/templates/music-lite/assets.macos.ts

@@ -0,0 +1 @@
+export * from "./assets.desktop";