Add Taco Design to an Electron app

import { createTacoDesignView, registerTacoDesignScheme } from "@taco-design/electron";

// Before the app is ready. An app with custom schemes of its own adds the
// exported `tacoDesignScheme` to its own registerSchemesAsPrivileged call
// instead, because Electron accepts that call only once.
registerTacoDesignScheme();

const window = new BaseWindow({
  width: 1400,
  height: 900,
  title: "Taco Design sample",
  show: !process.argv.includes("--hidden"),
});
// The editor stores no document itself: this app hands one over and saves it.
// While it starts, the editor shows a slim progress bar of its own. With
// `--host-progress` it shows none: the app then draws the progress itself
// (this sample only writes it in the window title, see below).
const editor = createTacoDesignView({
  document: startDocument,
  startupProgress: process.argv.includes("--host-progress") ? "host" : "editor",
  menuShortcutConflict: startConflict,
  shortcuts: startRemapped ? DUPLICATE_REMAP : {},
});
window.contentView.addChildView(editor.view);

const fillWindow = () => {
  const { width, height } = window.getContentBounds();
  editor.view.setBounds({ x: 0, y: 0, width, height });
};
fillWindow();
window.on("resize", fillWindow);

try {
  // The editor has opened the start document, so its file is now the one to save to.
  await saverWhenReady;
  const ready = await editor.ready;
  windowTitle.startEnded();
  windowTitle.setDocumentTitle(ready.document.title);
  showTitle();
  console.log(
    `Taco Design is ready: "${ready.document.title}", document schema ${ready.documentSchemaVersion}.`,
    startFile === null ? "No file was named, so nothing is saved." : `Saving to ${startFile}.`,
  );
  editor.focus();
  for (const request of startsBeforeTheWindow.splice(0)) openInRunningApp(request.file);
} catch (error) {
  // A TacoDesignError: error.code says what went wrong ("invalid-document"
  // with error.path, "schema-too-new", ...). The view shows the same message.
  // No last progress report came, so this is where the title stops saying
  // that the editor is loading.
  windowTitle.startEnded();
  showTitle();
  console.error("Taco Design could not start:", error);
  if (startFile !== null) console.error(`${startFile} is left as it is: nothing is saved to it.`);
}

/**
 * Reads the document file. A missing file means a new document; a file that
 * is not JSON stops the app, so that it is never saved over.
 * @param {string | null} file
 * @returns {Promise<unknown>}
 */
async function readDocument(file) {
  if (file === null) return null;
  let text;
  try {
    text = await readFile(file, "utf8");
  } catch (error) {
    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") return null;
    throw error;
  }
  return JSON.parse(text);
}

const startFile = documentFileFromArguments();
let startDocument;
try {
  startDocument = await readDocument(startFile);
} catch (error) {
  console.error(`${String(startFile)} could not be read as a document, so the app stops instead of saving over it:`, error);
  app.exit(1);
  return;
}

// Saving. saveModel.mjs decides when to save, what counts as edited, what
// happens after a failed save, when the window may close and how it goes
// over to another file; its first lines list the rules. This file only
// gives it what it cannot do itself. The model is made once the editor has
// opened the start document: before that, and when the editor refused that
// document, there is nothing to save, and a close saves nothing over the
// file. Without a file the model saves nothing until another file is opened.
/** @type {import("./saveModel.mjs").SaveModel<string> | null} */
let saver = null;
const saverWhenReady = editor.ready.then(() => {
  /** @type {import("./saveModel.mjs").SaveModel<string>} */
  const model = createSaveModel({
    file: startFile,
    saveDelayMs: SAVE_DELAY_MS,
    getDocument: () => editor.getDocument(),
    // With `ifRevision` the editor replaces only the document the model has just saved.
    // `readDocument` gives null for a file that does not exist yet: the window
    // then starts a new blank document that is saved there, as at the first start.
    setDocument: (document, options) =>
      (document === null ? editor.newDocument(options) : editor.setDocument(document, options)),
    load: readDocument,
    write: async (document, file) => {
      // Written next to the file first, so a crash half-way leaves the old file whole.
      await writeFile(`${file}.saving`, JSON.stringify(document));
      await rename(`${file}.saving`, file);
    },
    close: () => window.close(),
    askAfterFailedClose: async (error) => {
      const { response } = await dialog.showMessageBox(window, {
        type: "warning",
        message: `"${windowTitle.documentTitle()}" could not be saved.`,
        detail: `${String(model.file())}\n${error instanceof Error ? error.message : String(error)}\n\nClosing now loses the changes made since the last save.`,
        buttons: ["Try Again", "Close Without Saving", "Cancel"],
        defaultId: 0,
        cancelId: 2,
      });
      return response === 0 ? "try-again" : response === 1 ? "close-without-saving" : "cancel";
    },
    askAfterFailedSwitch: async (error, next) => {
      const { response } = await dialog.showMessageBox(window, {
        type: "warning",
        message: `"${windowTitle.documentTitle()}" could not be saved, so ${path.basename(next)} is not open yet.`,
        detail: `${String(model.file())}\n${error instanceof Error ? error.message : String(error)}\n\nOpening ${next} now loses the changes made since the last save.`,
        buttons: ["Try Again", "Open Without Saving", "Cancel"],
        defaultId: 0,
        cancelId: 2,
      });
      return response === 0 ? "try-again" : response === 1 ? "open-without-saving" : "cancel";
    },
    onState: showTitle,
    // Told once, not for every retry. The title says the rest.
    onSaveFailed: (error) => console.error(`Could not save ${String(model.file())}. The app keeps trying:`, error),
  });
  saver = model;
  return model;
});

for (let refusals = 0; ; ) {
  readRevision = from !== null && saveFirst ? await saveUntilNothingIsNewer(from) : null;
  // No `await` between that answer and this call (see `saveUntilNothingIsNewer`).
  // The page is another process and can still take an edit before the
  // call reaches it, so the editor is told which revision is on disk
  // and replaces only that one.
  replacing = replacement;
  try {
    opened = await setDocument(document, readRevision === null ? {} : { ifRevision: readRevision });
    break;
  } catch (error) {
    const code = /** @type {{ code?: string } | null} */ (error)?.code ?? "";
    if (code === "revision-changed" && readRevision !== null) {
      // An edit came in between. The old document is still open, with
      // that edit: bring it to disk and ask again.
      refusals += 1;
      if (refusals < MOST_REPLACEMENTS_FOR_ONE_SWITCH) continue;
      // The edit of the last refusal is saved like any other, a little later.
      if (saveTimer !== null) clearTimer(saveTimer);
      saveTimer = setTimer(() => {
        saveTimer = null;
        saveInTheBackground();
      }, saveDelayMs);
      throw new Error(
        `The document was changed each of the last ${MOST_REPLACEMENTS_FOR_ONE_SWITCH} times the other file was about to be opened, so it is still open.`,
      );
    }
    if (DOCUMENT_KEPT_CODES.has(code)) return { outcome: "refused", error };
    // It is not known which document the editor has: stop saving.
    file = null;
    failures = 0;
    stopTimers();
    tell();
    return { outcome: "stopped-saving", error, file: from };
  } finally {
    replacing = null;
  }
}

// A change event is small and carries no document.
editor.on("change", (change) => {
  windowTitle.setDocumentTitle(change.title);
  showTitle();
  saver?.changed(change.revision, { origin: change.origin });
});

// Which layers are selected, for the window title. The event is small:
// the page ID and each layer's ID, name and kind.
editor.on("selection", (next) => {
  selection = next;
  showTitle();
});

/**
 * The selection in a few words, for a window title or a status line.
 * @param {import("@taco-design/electron").SelectionSummary | null} selection
 * @returns {string}
 */
export function describeSelection(selection) {
  const only = selection?.nodes[0];
  if (selection === null || only === undefined) return "nothing selected";
  if (selection.nodes.length === 1) return `${only.name} (${only.shape ?? only.type}) selected`;
  return `${selection.nodes.length} layers selected`;
}

// The editor stopped working after it had started. Its crash screen has a
// Reload button of its own; a canvas that stopped drawing and a page whose
// process ended are loaded again here. reload() reads the document from
// the page first where it can, so no edit is lost.
let lastReloadAfterFailure = Number.NEGATIVE_INFINITY;
editor.on("failure", (error) => {
  console.error(`Taco Design stopped working (${error.code}): ${error.message}`);
  if (error.code === "editor-crashed") return;
  if (Date.now() - lastReloadAfterFailure < RELOAD_AFTER_FAILURE_INTERVAL_MS) {
    console.error("It failed again shortly after it was loaded again, so it is left as it is.");
    return;
  }
  lastReloadAfterFailure = Date.now();
  editor.reload().catch((reloadError) => console.error("Taco Design could not be loaded again:", reloadError));
});

// The page was loaded again (its crash screen's Reload, or reload() below)
// and counts its revisions from 0 again. With `handedOver` it shows the
// latest work, which the save model has not read and so saves again;
// without, the last document this app read.
editor.on("reloaded", (document) => {
  windowTitle.setDocumentTitle(document.title);
  selection = null;
  showTitle();
  if (!document.handedOver) {
    console.warn("The editor was loaded again and could not hand over its document first: it shows the last saved state.");
  }
  saver?.reloaded(document.revision, { handedOver: document.handedOver });
});

const { nodes } = await editor.getSelection();
const [only] = nodes;
if (only === undefined) return { status: "nothing-selected" };

if (nodes.length === 1) {
  // Exported first, because the editor knows the file name that suits the layer.
  const [file] = await editor.exportLayers({ nodeId: only.id, format: "png", scale });
  if (file === undefined) throw new Error("The editor answered the export without a file.");
  const target = await chooseFile(file.fileName);
  if (target === null) return { status: "cancelled" };
  await writeFile(target, file.bytes);
  return { status: "saved", files: [target] };
}

// How far the editor's start-up is, in the window title. The last report
// (fraction 1) arrives before `ready` resolves. A start that fails sends no
// last report and rejects `ready` instead, so the title stops showing
// progress when `ready` settles, either way (see the end of this function).
editor.on("startupProgress", (progress) => {
  windowTitle.startupProgress(progress);
  showTitle();
});

/** The override the sample's "Duplicate on Cmd/Ctrl+Shift+D" item switches on. */
export const DUPLICATE_REMAP = /** @type {const} */ ({ "edit.duplicate": "CmdOrCtrl+Shift+D" });

const startConflict = conflictFromArguments();
// `--remap-duplicate` starts with the editor's Duplicate on Shift+Cmd/Ctrl+D.
const startRemapped = process.argv.includes("--remap-duplicate");

const editor = createTacoDesignView({
  document: startDocument,
  startupProgress: process.argv.includes("--host-progress") ? "host" : "editor",
  menuShortcutConflict: startConflict,
  shortcuts: startRemapped ? DUPLICATE_REMAP : {},
});

/** Cmd/Ctrl+S and the menu's Save. A failure is reported by the model (`onSaveFailed`) and shown in the title. */
const saveNow = () => void saver?.save().catch(() => undefined);

// Cmd/Ctrl+S in the editor. The editor saves nothing itself.
editor.on("saveRequested", saveNow);

{
  label: "File",
  submenu: [
    { id: SAVE_MENU_ID, label: "Save", accelerator: "CmdOrCtrl+S", click: () => options.save() },
    { type: "separator" },
    mac ? { role: "close" } : { role: "quit" },
  ],
},
{
  label: "Edit",
  submenu: [
    { id: UNDO_MENU_ID, label: "Undo", accelerator: "CmdOrCtrl+Z", click: history("undo") },
    { id: REDO_MENU_ID, label: "Redo", accelerator: "Shift+CmdOrCtrl+Z", click: history("redo") },
    { type: "separator" },
    { role: "cut" },
    { role: "copy" },
    { role: "paste" },
    { role: "selectAll" },
  ],
},
// No zoom roles here: they would scale the whole view.
{ label: "View", submenu: [{ role: "togglefullscreen" }] },

/** @type {"canvas" | "text" | "other" | null} */
let editorFocus = null;
editor.on("focus", (focus) => {
  editorFocus = focus.target;
});

/**
 * Whether Undo and Redo belong to the editor right now: its canvas or one of
 * its panels has the keyboard. With a text field ("text"), or with the
 * keyboard outside the editor (null), they belong to whatever has it.
 *
 * @param {"canvas" | "text" | "other" | null} focusTarget What the editor's last `focus` event said.
 */
export function editorOwnsUndo(focusTarget) {
  return focusTarget === "canvas" || focusTarget === "other";
}

/** @param {"undo" | "redo"} command */
const history = (command) => () => {
  if (!editorOwnsUndo(options.editorFocus())) options.runTextCommand(command);
  else if (command === "undo") options.undoInEditor();
  else options.redoInEditor();
};

let appCommandRuns = 0;
Menu.setApplicationMenu(Menu.buildFromTemplate(buildAppMenuTemplate({
  platform: process.platform,
  editorFocus: () => editorFocus,
  undoInEditor: () => void editor.undo().catch((error) => console.error("Undo failed:", error)),
  redoInEditor: () => void editor.redo().catch((error) => console.error("Redo failed:", error)),
  // What the `undo` and `redo` roles do: the focused page's text command,
  // or on macOS the focused native text field's.
  runTextCommand: (command) => {
    const focused = webContents.getFocusedWebContents();
    if (focused !== null) focused[command]();
    else if (process.platform === "darwin") Menu.sendActionToFirstResponder(`${command}:`);
  },
  save: saveNow,
  conflict: startConflict,
  setConflict: (conflict) => {
    editor.setMenuShortcutConflict(conflict);
    console.log(`Keys that are an editor shortcut and a menu shortcut: ${conflict}.`);
  },
  duplicateRemapped: startRemapped,
  setDuplicateRemapped: (remapped) => {
    editor.setShortcuts(remapped ? DUPLICATE_REMAP : {}).then(
      (commands) => console.log(`Duplicate is on ${commands.find((command) => command.id === "edit.duplicate")?.keys.join(", ")}.`),
      (error) => console.error("The shortcut could not be changed:", error),
    );
  },
  runAppCommand: () => {
    appCommandRuns += 1;
    console.log(`The app's own command ran (${appCommandRuns}).`);
    void dialog.showMessageBox(window, {
      type: "info",
      message: "The app's own command ran.",
      detail: `It is on the same keys as the editor's Duplicate. Times it ran: ${appCommandRuns}.`,
    });
  },
})));

// The page has no "unsaved changes" guard of its own, so a window with a
// file closes only through its save model: once the document is on disk,
// or once the person chose to lose the changes. Quitting asks every window
// to close and so takes the same way; an app with several windows gives
// each its own model.
window.on("close", (event) => {
  if (saver === null || saver.closed()) return;
  event.preventDefault();
  void saver.requestClose();
});

/**
 * Reads, and writes what it read, until a read finds the document that is
 * on disk. Then it closes with no `await` in between, so no edit can
 * arrive between that answer and the close.
 */
const saveUntilNothingIsNewerThenClose = async () => {
  if (hasClosed) return;
  const to = file;
  if (to === null) {
    closeNow();
    return;
  }
  await saveUntilNothingIsNewer(to);
  closeNow();
};
/**
 * Resolves, with the revision read, in the same turn as the answer of a
 * read that found the document that is on disk. Whoever awaits this is
 * resumed before any other event of this process is handled, so what it
 * does next without an `await` of its own follows that answer directly.
 * @param {File} to
 */
const saveUntilNothingIsNewer = async (to) => {
  stopTimers();
  try {
    for (let writes = 0; ; writes += 1) {
      const documentRead = await read();
      if (documentRead.name === onDisk) {
        worked();
        return documentRead.revision;
      }
      if (writes === MOST_WRITES_FOR_ONE_CLOSE) {
        throw new Error(
          `The document was changed during each of the last ${MOST_WRITES_FOR_ONE_CLOSE} saves, so the newest changes are not saved yet.`,
        );
      }
      await writeToDisk(documentRead, to);
    }
  } catch (error) {
    failed(error);
    throw error;
  }
};

const capability = (await editor.getState()).design;
if (!capability?.versions.includes(DESIGN_PROTOCOL_VERSION)) throw new Error("This editor does not advertise the supported design protocol.");
const call = createDesignClient(request => editor.designRequest(request, { timeoutMs: 10_000 }), capability.binding, randomUUID);
console.log(await call("protocol.describe", {}));
const snapshot = await call("document.inspect", {});
console.log(snapshot);