@tangle-network/starter-foundry 0.5.4 → 0.7.2

package/registry/layers/framework/electron-native-os/files/App.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useState } from "react";
+
+// The renderer exercises every native-OS seam exposed via the preload.
+// Each card is a smoke-test for one capability — agents can rip them
+// out once a real UI is designed but the wiring stays identical.
+
+declare global {
+  interface Window {
+    native: {
+      openFile: () => Promise<string | null>;
+      saveFile: (name: string) => Promise<string | null>;
+      notify: (payload: { title: string; body: string }) => Promise<boolean>;
+      onDeepLink: (handler: (url: string) => void) => () => void;
+      onMenuCommand: (handler: (command: string) => void) => () => void;
+    };
+  }
+}
+
+export default function App() {
+  const [lastFile, setLastFile] = useState<string | null>(null);
+  const [lastDeepLink, setLastDeepLink] = useState<string | null>(null);
+  const [lastMenu, setLastMenu] = useState<string | null>(null);
+
+  useEffect(() => {
+    const unsubDeep = window.native?.onDeepLink((url) => setLastDeepLink(url));
+    const unsubMenu = window.native?.onMenuCommand((cmd) => setLastMenu(cmd));
+    return () => {
+      unsubDeep?.();
+      unsubMenu?.();
+    };
+  }, []);
+
+  return (
+    <main className="shell">
+      <header>
+        <h1>{{headline}}</h1>
+        <p>{{subheadline}}</p>
+      </header>
+
+      <section className="cards">
+        <article className="card">
+          <h2>Native file dialog</h2>
+          <p>Opens the OS file picker via IPC — renderer stays sandboxed.</p>
+          <button
+            onClick={async () => {
+              const file = await window.native.openFile();
+              if (file) setLastFile(file);
+            }}
+          >
+            Open file…
+          </button>
+          {lastFile && <code>{lastFile}</code>}
+        </article>
+
+        <article className="card">
+          <h2>OS notification</h2>
+          <p>Dispatches a native banner / action-center toast.</p>
+          <button
+            onClick={() =>
+              window.native.notify({
+                title: "{{projectName}}",
+                body: "Notifications are wired.",
+              })
+            }
+          >
+            Send notification
+          </button>
+        </article>
+
+        <article className="card">
+          <h2>Deep link handler</h2>
+          <p>
+            Try <code>{{packageName}}://ping</code> from a browser — the URL
+            routes into this renderer.
+          </p>
+          <code>{lastDeepLink ?? "waiting…"}</code>
+        </article>
+
+        <article className="card">
+          <h2>Menu-bar commands</h2>
+          <p>File → Open (Cmd+O) and File → Save (Cmd+S) fire IPC here.</p>
+          <code>{lastMenu ?? "waiting…"}</code>
+        </article>
+      </section>
+    </main>
+  );
+}

package/registry/layers/framework/electron-native-os/files/deeplinks.ts

@@ -0,0 +1,59 @@
+// Deep-link routing. Two OS-specific paths:
+//
+//   - macOS: app.on("open-url", ...) fires when the user clicks a
+//     `{{packageName}}://` URL. It can fire BEFORE app.whenReady() on
+//     cold launch, so we buffer until the renderer exists.
+//
+//   - Windows/Linux: no open-url event; the URL arrives as argv on a
+//     second-instance launch. We listen to app.on("second-instance")
+//     which requires the single-instance lock to be held.
+//
+// Both paths funnel into a single queue that main/index.ts drains after
+// the BrowserWindow is ready.
+
+import { app } from "electron";
+
+type UrlHandler = (url: string) => void;
+
+export interface DeepLinkState {
+  flushTo(handler: UrlHandler): void;
+  onUrl(handler: UrlHandler): void;
+}
+
+export function installDeepLinkHandlers(): DeepLinkState {
+  const buffered: string[] = [];
+  const subscribers: UrlHandler[] = [];
+
+  function emit(url: string): void {
+    if (subscribers.length === 0) {
+      buffered.push(url);
+      return;
+    }
+    for (const handler of subscribers) handler(url);
+  }
+
+  // macOS cold-launch + warm open-url.
+  app.on("open-url", (event, url) => {
+    event.preventDefault();
+    emit(url);
+  });
+
+  // Windows/Linux: the running instance is told about the new argv.
+  app.on("second-instance", (_event, argv) => {
+    const url = argv.find((arg) => arg.startsWith("{{packageName}}://"));
+    if (url) emit(url);
+  });
+
+  return {
+    flushTo(handler) {
+      const pending = buffered.splice(0, buffered.length);
+      for (const url of pending) handler(url);
+    },
+    onUrl(handler) {
+      subscribers.push(handler);
+      // Any URLs that arrived before any subscriber existed will have
+      // been captured by `buffered` and flushed via flushTo(); nothing
+      // to replay here.
+    },
+  };
+}

package/registry/layers/framework/electron-native-os/files/electron-builder.json

@@ -0,0 +1,39 @@
+{
+  "appId": "com.starterfoundry.{{packageName}}",
+  "productName": "{{projectName}}",
+  "directories": {
+    "output": "release"
+  },
+  "files": [
+    "out/**/*",
+    "node_modules/**/*",
+    "package.json"
+  ],
+  "protocols": [
+    {
+      "name": "{{projectName}}",
+      "schemes": ["{{packageName}}"]
+    }
+  ],
+  "mac": {
+    "hardenedRuntime": true,
+    "gatekeeperAssess": false,
+    "entitlements": "build/entitlements.mac.plist",
+    "entitlementsInherit": "build/entitlements.mac.plist",
+    "notarize": true
+  },
+  "win": {
+    "target": ["nsis"],
+    "publisherName": "{{projectName}}"
+  },
+  "linux": {
+    "target": ["AppImage", "deb"],
+    "category": "Utility"
+  },
+  "publish": [
+    {
+      "provider": "github",
+      "releaseType": "release"
+    }
+  ]
+}

package/registry/layers/framework/electron-native-os/files/electron.vite.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig, externalizeDepsPlugin } from 'electron-vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  main: {
+    plugins: [externalizeDepsPlugin()]
+  },
+  preload: {
+    plugins: [externalizeDepsPlugin()]
+  },
+  renderer: {
+    plugins: [react()]
+  }
+})

package/registry/layers/framework/electron-native-os/files/index.ts

@@ -0,0 +1,119 @@
+// Main-process entry. The order of operations below is load-bearing:
+//
+//   1. acquire the single-instance lock FIRST (without it, Windows deep
+//      links launch a second copy of the app instead of routing to the
+//      running one).
+//   2. register custom protocol schemes BEFORE app.whenReady().
+//   3. install deep-link listeners BEFORE whenReady so macOS cold-launch
+//      open-url events are not lost.
+//   4. whenReady: register the app:// file protocol, build the menu,
+//      open the main window, boot the updater.
+
+import { app, BrowserWindow, ipcMain, dialog, Notification } from "electron";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import log from "electron-log";
+import { registerAppProtocol, registerPrivilegedSchemes } from "./protocol.js";
+import { installDeepLinkHandlers } from "./deeplinks.js";
+import { buildApplicationMenu } from "./menu.js";
+import { bootAutoUpdater } from "./updater.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+log.initialize();
+
+// (1) single-instance lock — required for Windows/Linux deep-link routing.
+const gotLock = app.requestSingleInstanceLock();
+if (!gotLock) {
+  app.quit();
+  process.exit(0);
+}
+
+// (2) privileged scheme registration must happen before whenReady().
+registerPrivilegedSchemes();
+
+// (3) deep-link plumbing — must attach before whenReady so we catch
+// cold-launch open-url on macOS.
+const deepLinkState = installDeepLinkHandlers();
+
+let mainWindow: BrowserWindow | null = null;
+
+function createMainWindow(): BrowserWindow {
+  const win = new BrowserWindow({
+    width: 1000,
+    height: 700,
+    title: "{{projectName}}",
+    webPreferences: {
+      preload: path.join(__dirname, "../preload/index.cjs"),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+    },
+  });
+
+  if (process.env.VITE_DEV_SERVER_URL) {
+    win.loadURL(process.env.VITE_DEV_SERVER_URL);
+  } else {
+    win.loadURL("app://local/index.html");
+  }
+
+  return win;
+}
+
+// Renderer-side dialogs are proxied through IPC so the renderer stays
+// sandboxed (contextIsolation on, nodeIntegration off).
+ipcMain.handle("dialog:open-file", async () => {
+  const result = await dialog.showOpenDialog({
+    properties: ["openFile"],
+    filters: [{ name: "All Files", extensions: ["*"] }],
+  });
+  return result.canceled ? null : result.filePaths[0];
+});
+
+ipcMain.handle("dialog:save-file", async (_event, suggestedName: string) => {
+  const result = await dialog.showSaveDialog({ defaultPath: suggestedName });
+  return result.canceled ? null : result.filePath;
+});
+
+ipcMain.handle("notify", async (_event, { title, body }: { title: string; body: string }) => {
+  if (!Notification.isSupported()) return false;
+  new Notification({ title, body }).show();
+  return true;
+});
+
+app.whenReady().then(() => {
+  // (4a) Install the app:// file protocol now that we have a ready session.
+  registerAppProtocol();
+
+  // (4b) Platform menu.
+  buildApplicationMenu();
+
+  // (4c) Main window.
+  mainWindow = createMainWindow();
+
+  // (4d) Replay any deep link that arrived before the window existed.
+  deepLinkState.flushTo((url) => {
+    mainWindow?.webContents.send("deeplink", url);
+  });
+
+  // (4e) Forward future deep links into the renderer.
+  deepLinkState.onUrl((url) => {
+    if (mainWindow && !mainWindow.isDestroyed()) {
+      mainWindow.focus();
+      mainWindow.webContents.send("deeplink", url);
+    }
+  });
+
+  // (4f) Auto-update channel.
+  bootAutoUpdater(log);
+
+  app.on("activate", () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      mainWindow = createMainWindow();
+    }
+  });
+});
+
+app.on("window-all-closed", () => {
+  if (process.platform !== "darwin") app.quit();
+});

package/registry/layers/framework/electron-native-os/files/menu.ts

@@ -0,0 +1,99 @@
+// Platform menus diverge enough that a shared "roles" menu template
+// produces the wrong thing on macOS (no app-name item) or Windows (no
+// File submenu). Branch on process.platform and build each explicitly.
+
+import { app, BrowserWindow, Menu, shell, type MenuItemConstructorOptions } from "electron";
+
+export function buildApplicationMenu(): void {
+  const isMac = process.platform === "darwin";
+
+  const macAppMenu: MenuItemConstructorOptions = {
+    label: app.name,
+    submenu: [
+      { role: "about" },
+      { type: "separator" },
+      { role: "services" },
+      { type: "separator" },
+      { role: "hide" },
+      { role: "hideOthers" },
+      { role: "unhide" },
+      { type: "separator" },
+      { role: "quit" },
+    ],
+  };
+
+  const fileMenu: MenuItemConstructorOptions = {
+    label: "File",
+    submenu: [
+      {
+        label: "Open…",
+        accelerator: "CmdOrCtrl+O",
+        click: (_item, win) => {
+          (win as BrowserWindow | undefined)?.webContents.send("menu:open");
+        },
+      },
+      {
+        label: "Save",
+        accelerator: "CmdOrCtrl+S",
+        click: (_item, win) => {
+          (win as BrowserWindow | undefined)?.webContents.send("menu:save");
+        },
+      },
+      { type: "separator" },
+      isMac ? { role: "close" } : { role: "quit" },
+    ],
+  };
+
+  const editMenu: MenuItemConstructorOptions = {
+    label: "Edit",
+    submenu: [
+      { role: "undo" },
+      { role: "redo" },
+      { type: "separator" },
+      { role: "cut" },
+      { role: "copy" },
+      { role: "paste" },
+      { role: "selectAll" },
+    ],
+  };
+
+  const viewMenu: MenuItemConstructorOptions = {
+    label: "View",
+    submenu: [
+      { role: "reload" },
+      { role: "forceReload" },
+      { role: "toggleDevTools" },
+      { type: "separator" },
+      { role: "resetZoom" },
+      { role: "zoomIn" },
+      { role: "zoomOut" },
+      { type: "separator" },
+      { role: "togglefullscreen" },
+    ],
+  };
+
+  const windowMenu: MenuItemConstructorOptions = {
+    label: "Window",
+    submenu: isMac
+      ? [{ role: "minimize" }, { role: "zoom" }, { type: "separator" }, { role: "front" }]
+      : [{ role: "minimize" }, { role: "zoom" }, { role: "close" }],
+  };
+
+  const helpMenu: MenuItemConstructorOptions = {
+    label: "Help",
+    submenu: [
+      {
+        label: "Documentation",
+        click: async () => {
+          await shell.openExternal("https://www.electronjs.org/docs");
+        },
+      },
+    ],
+  };
+
+  const template: MenuItemConstructorOptions[] = isMac
+    ? [macAppMenu, fileMenu, editMenu, viewMenu, windowMenu, helpMenu]
+    : [fileMenu, editMenu, viewMenu, windowMenu, helpMenu];
+
+  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+}

package/registry/layers/framework/electron-native-os/files/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "private": true,
+  "main": "out/main/index.cjs",
+  "scripts": {
+    "dev": "electron-vite dev",
+    "build": "electron-vite build",
+    "preview": "electron-vite preview",
+    "package": "electron-builder --config electron-builder.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "electron-log": "^5.2.4",
+    "electron-updater": "^6.3.9"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.3",
+    "electron": "^33.4.0",
+    "electron-builder": "^25.1.8",
+    "electron-vite": "^2.3.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.10"
+  }
+}

package/registry/layers/framework/electron-native-os/files/preload.ts

@@ -0,0 +1,33 @@
+// The ONLY surface area the renderer sees. Keep this list small and
+// typed — every function here is a capability the renderer can exercise
+// without needing nodeIntegration. Anything not listed here is not
+// reachable from the renderer, by design.
+
+import { contextBridge, ipcRenderer } from "electron";
+
+const api = {
+  openFile: (): Promise<string | null> => ipcRenderer.invoke("dialog:open-file"),
+  saveFile: (suggestedName: string): Promise<string | null> =>
+    ipcRenderer.invoke("dialog:save-file", suggestedName),
+  notify: (payload: { title: string; body: string }): Promise<boolean> =>
+    ipcRenderer.invoke("notify", payload),
+  onDeepLink: (handler: (url: string) => void): (() => void) => {
+    const wrapper = (_event: unknown, url: string) => handler(url);
+    ipcRenderer.on("deeplink", wrapper);
+    return () => ipcRenderer.removeListener("deeplink", wrapper);
+  },
+  onMenuCommand: (handler: (command: string) => void): (() => void) => {
+    const wrapper = (_event: unknown, _payload: unknown, channel: string) =>
+      handler(channel.replace(/^menu:/, ""));
+    ipcRenderer.on("menu:open", (event, payload) => wrapper(event, payload, "menu:open"));
+    ipcRenderer.on("menu:save", (event, payload) => wrapper(event, payload, "menu:save"));
+    return () => {
+      ipcRenderer.removeAllListeners("menu:open");
+      ipcRenderer.removeAllListeners("menu:save");
+    };
+  },
+};
+
+contextBridge.exposeInMainWorld("native", api);
+
+export type NativeApi = typeof api;

package/registry/layers/framework/electron-native-os/files/protocol.ts

@@ -0,0 +1,56 @@
+// Two protocol responsibilities in one file:
+//
+//   1. `app://` — a bundled-asset protocol for loading the renderer in
+//      production without exposing the file:// surface. Must be declared
+//      as "privileged" (secure, supports fetch) BEFORE app.whenReady(),
+//      then registered as a file handler AFTER whenReady.
+//
+//   2. `{{packageName}}://` — the OS-wide deep-link scheme. Registration
+//      is handled by electron-builder's `protocols` block for installed
+//      builds and by app.setAsDefaultProtocolClient for dev.
+
+import { app, protocol, net } from "electron";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { pathToFileURL } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEEP_LINK_SCHEME = "{{packageName}}";
+
+export function registerPrivilegedSchemes(): void {
+  protocol.registerSchemesAsPrivileged([
+    {
+      scheme: "app",
+      privileges: {
+        standard: true,
+        secure: true,
+        supportFetchAPI: true,
+        corsEnabled: true,
+      },
+    },
+  ]);
+
+  // Deep-link registration. On macOS this is declarative via Info.plist
+  // (generated by electron-builder's protocols block). On Windows/Linux
+  // we still call setAsDefaultProtocolClient for dev-mode runs.
+  if (process.defaultApp) {
+    if (process.argv.length >= 2) {
+      app.setAsDefaultProtocolClient(DEEP_LINK_SCHEME, process.execPath, [
+        path.resolve(process.argv[1]!),
+      ]);
+    }
+  } else {
+    app.setAsDefaultProtocolClient(DEEP_LINK_SCHEME);
+  }
+}
+
+export function registerAppProtocol(): void {
+  // Electron 25+ prefers protocol.handle over registerFileProtocol.
+  protocol.handle("app", async (request) => {
+    const url = new URL(request.url);
+    // "app://local/index.html" -> resolve against the packaged renderer.
+    const rendererRoot = path.join(__dirname, "../renderer");
+    const filePath = path.join(rendererRoot, url.pathname);
+    return net.fetch(pathToFileURL(filePath).toString());
+  });
+}

package/registry/layers/framework/electron-native-os/files/renderer-index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self' app:; script-src 'self'; style-src 'self' 'unsafe-inline'" />
+    <title>{{headline}}</title>
+    <link rel="stylesheet" href="/src/renderer/styles.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/renderer/main.tsx"></script>
+  </body>
+</html>

package/registry/layers/framework/electron-native-os/files/renderer-main.tsx

@@ -0,0 +1,12 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+
+const container = document.getElementById("root");
+if (!container) throw new Error("missing #root");
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/registry/layers/framework/electron-native-os/files/styles.css

@@ -0,0 +1,72 @@
+body {
+  margin: 0;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  background: #f8fafc;
+  color: #0f172a;
+}
+
+.shell {
+  padding: 32px;
+  max-width: 920px;
+  margin: 0 auto;
+}
+
+.shell header h1 {
+  margin: 0 0 4px;
+  font-size: 24px;
+}
+
+.shell header p {
+  margin: 0 0 24px;
+  opacity: 0.7;
+}
+
+.cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 16px;
+}
+
+.card {
+  background: white;
+  border: 1px solid #e2e8f0;
+  border-radius: 12px;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.card h2 {
+  margin: 0;
+  font-size: 15px;
+}
+
+.card p {
+  margin: 0;
+  font-size: 13px;
+  opacity: 0.75;
+}
+
+.card button {
+  align-self: flex-start;
+  padding: 6px 12px;
+  font-size: 13px;
+  border-radius: 6px;
+  border: 1px solid #cbd5e1;
+  background: #f1f5f9;
+  cursor: pointer;
+}
+
+.card button:hover {
+  background: #e2e8f0;
+}
+
+.card code {
+  font-family: ui-monospace, SFMono-Regular, monospace;
+  font-size: 12px;
+  background: #f1f5f9;
+  padding: 4px 6px;
+  border-radius: 4px;
+  overflow-wrap: anywhere;
+}

package/registry/layers/framework/electron-native-os/files/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"]
+}

package/registry/layers/framework/electron-native-os/files/updater.ts

@@ -0,0 +1,29 @@
+// electron-updater wired to GitHub Releases. The `publish` block in
+// electron-builder.json determines the update feed; this file just
+// orchestrates the poll + install flow and forwards status to the main
+// log so silent failures (missing GH_TOKEN, unsigned binary) surface in
+// the user's log file instead of vanishing.
+
+import type electronLog from "electron-log";
+import { autoUpdater } from "electron-updater";
+
+export function bootAutoUpdater(log: typeof electronLog): void {
+  autoUpdater.logger = log;
+  autoUpdater.autoDownload = true;
+  autoUpdater.autoInstallOnAppQuit = true;
+
+  autoUpdater.on("checking-for-update", () => log.info("updater: checking"));
+  autoUpdater.on("update-available", (info) => log.info("updater: available", info.version));
+  autoUpdater.on("update-not-available", () => log.info("updater: up to date"));
+  autoUpdater.on("error", (err) => log.error("updater: error", err));
+  autoUpdater.on("download-progress", (p) => log.info(`updater: ${p.percent.toFixed(1)}%`));
+  autoUpdater.on("update-downloaded", (info) => {
+    log.info("updater: downloaded", info.version);
+  });
+
+  // Silent failure if the app is unsigned / not-notarized. Don't crash —
+  // just log and let the user keep using the running version.
+  autoUpdater.checkForUpdates().catch((err) => {
+    log.warn("updater: first check failed", err);
+  });
+}