acrylblends 0.6.0 → 0.6.2

package/plugins/acryl-router/src/core/middleware/mount/index.ts

@@ -0,0 +1,108 @@
+/**
+ * @module
+ * Mount Helper for Acryl.
+ */
+
+import type { Context, ExecutionContext } from '../../context.ts'
+import { routePath } from '../../helper/route/index.ts'
+import type { MiddlewareHandler } from '../../types.ts'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ApplicationHandler = (request: Request, ...args: any) => Response | Promise<Response>
+type MountOptionHandler = (c: Context) => unknown
+type MountReplaceRequest = (originalRequest: Request) => Request
+type MountOptions =
+  | MountOptionHandler
+  | {
+      optionHandler?: MountOptionHandler
+      replaceRequest?: MountReplaceRequest | false
+    }
+
+const defaultReplaceRequest = (c: Context): Request => {
+  // e.g. `/another-app/*` (basePath is already merged) -> `/another-app`
+  const pathPrefix = routePath(c).replace(/\/\*$/, '')
+  const url = new URL(c.req.raw.url)
+  url.pathname = c.req.path.slice(pathPrefix.length) || '/'
+  return new Request(url, c.req.raw)
+}
+
+const defaultGetOptions = (c: Context): unknown[] => {
+  let executionContext: ExecutionContext | undefined = undefined
+  try {
+    executionContext = c.executionCtx
+  } catch {} // Do nothing
+  return [c.env, executionContext]
+}
+
+/**
+ * `mount()` allows you to mount applications built with other frameworks into your Acryl application.
+ *
+ *
+ * @param {Function} applicationHandler - other Request Handler
+ * @param {MountOptions} [options] - options of `mount()`
+ * @returns {MiddlewareHandler} handler to register with `app.all()`
+ *
+ * @example
+ * ```ts
+ * import { Router as IttyRouter } from 'itty-router'
+ * import { Acryl } from 'acrylblends'
+ * import { mount } from 'acrylblends/mount'
+ * // Create itty-router application
+ * const ittyRouter = IttyRouter()
+ * // GET /itty-router/hello
+ * ittyRouter.get('/hello', () => new Response('Hello from itty-router'))
+ *
+ * const app = new Acryl()
+ * app.all('/itty-router/*', mount(ittyRouter.handle))
+ * ```
+ *
+ * @example
+ * ```ts
+ * const app = new Acryl()
+ * // Send the request to another application without modification.
+ * app.all('/app/*', mount(anotherApp, {
+ *   replaceRequest: (req) => req,
+ * }))
+ * ```
+ */
+export const mount = (
+  applicationHandler: ApplicationHandler,
+  options?: MountOptions
+): MiddlewareHandler => {
+  // handle options
+  let replaceRequest: MountReplaceRequest | undefined
+  let optionHandler: MountOptionHandler | undefined
+  if (options) {
+    if (typeof options === 'function') {
+      optionHandler = options
+    } else {
+      optionHandler = options.optionHandler
+      if (options.replaceRequest === false) {
+        replaceRequest = (request) => request
+      } else {
+        replaceRequest = options.replaceRequest
+      }
+    }
+  }
+
+  // prepare handlers for request
+  const getOptions: (c: Context) => unknown[] = optionHandler
+    ? (c) => {
+        const options = optionHandler!(c)
+        return Array.isArray(options) ? options : [options]
+      }
+    : defaultGetOptions
+
+  return async (c, next) => {
+    const request = replaceRequest ? replaceRequest(c.req.raw) : defaultReplaceRequest(c)
+    const res = await applicationHandler(request, ...getOptions(c))
+
+    if (res) {
+      return res
+    }
+
+    await next()
+  }
+}
+
+export type { ApplicationHandler, MountOptionHandler, MountReplaceRequest, MountOptions }

package/plugins/acryl-router/src/core/preset/quick.test.ts

@@ -0,0 +1,42 @@
+import { getRouterName } from '../helper/dev/index.ts'
+import { Acryl } from './quick.ts'
+
+describe('acryl-router/quick preset', () => {
+  it('Should have SmartRouter + LinearRouter', async () => {
+    const app = new Acryl()
+    expect(getRouterName(app)).toBe('SmartRouter + LinearRouter')
+  })
+})
+
+describe('Generics for Bindings and Variables', () => {
+  interface CloudflareBindings {
+    MY_VARIABLE: string
+  }
+
+  it('Should not throw type errors', () => {
+    // @ts-expect-error Bindings should extend object
+    new Acryl<{
+      Bindings: number
+    }>()
+
+    const appWithInterface = new Acryl<{
+      Bindings: CloudflareBindings
+    }>()
+
+    appWithInterface.get('/', (c) => {
+      expectTypeOf(c.env.MY_VARIABLE).toMatchTypeOf<string>()
+      return c.text('/')
+    })
+
+    const appWithType = new Acryl<{
+      Bindings: {
+        foo: string
+      }
+    }>()
+
+    appWithType.get('/', (c) => {
+      expectTypeOf(c.env.foo).toMatchTypeOf<string>()
+      return c.text('Hello Acryl!')
+    })
+  })
+})

package/plugins/acryl-router/src/core/preset/quick.ts

@@ -0,0 +1,24 @@
+/**
+ * @module
+ * The preset that uses `LinearRouter`.
+ */
+
+import { AcrylBase } from '../app-base.ts'
+import type { AcrylOptions } from '../app-base.ts'
+import { LinearRouter } from '../router/linear-router/index.ts'
+import { SmartRouter } from '../router/smart-router/index.ts'
+import { TrieRouter } from '../router/trie-router/index.ts'
+import type { BlankEnv, BlankSchema, Env, Schema } from '../types.ts'
+
+export class Acryl<
+  E extends Env = BlankEnv,
+  S extends Schema = BlankSchema,
+  BasePath extends string = '/',
+> extends AcrylBase<E, S, BasePath> {
+  constructor(options: AcrylOptions<E> = {}) {
+    super(options)
+    this.router = new SmartRouter({
+      routers: [new LinearRouter(), new TrieRouter()],
+    })
+  }
+}

package/plugins/acryl-router/src/core/preset/tiny.test.ts

@@ -0,0 +1,42 @@
+import { getRouterName } from '../helper/dev/index.ts'
+import { Acryl } from './tiny.ts'
+
+describe('acryl-router/tiny preset', () => {
+  it('Should have PatternRouter', async () => {
+    const app = new Acryl()
+    expect(getRouterName(app)).toBe('PatternRouter')
+  })
+})
+
+describe('Generics for Bindings and Variables', () => {
+  interface CloudflareBindings {
+    MY_VARIABLE: string
+  }
+
+  it('Should not throw type errors', () => {
+    // @ts-expect-error Bindings should extend object
+    new Acryl<{
+      Bindings: number
+    }>()
+
+    const appWithInterface = new Acryl<{
+      Bindings: CloudflareBindings
+    }>()
+
+    appWithInterface.get('/', (c) => {
+      expectTypeOf(c.env.MY_VARIABLE).toMatchTypeOf<string>()
+      return c.text('/')
+    })
+
+    const appWithType = new Acryl<{
+      Bindings: {
+        foo: string
+      }
+    }>()
+
+    appWithType.get('/', (c) => {
+      expectTypeOf(c.env.foo).toMatchTypeOf<string>()
+      return c.text('Hello Acryl!')
+    })
+  })
+})

package/plugins/acryl-router/src/core/preset/tiny.ts

@@ -0,0 +1,20 @@
+/**
+ * @module
+ * The preset that uses `PatternRouter`.
+ */
+
+import { AcrylBase } from '../app-base.ts'
+import type { AcrylOptions } from '../app-base.ts'
+import { PatternRouter } from '../router/pattern-router/index.ts'
+import type { BlankEnv, BlankSchema, Env, Schema } from '../types.ts'
+
+export class Acryl<
+  E extends Env = BlankEnv,
+  S extends Schema = BlankSchema,
+  BasePath extends string = '/',
+> extends AcrylBase<E, S, BasePath> {
+  constructor(options: AcrylOptions<E> = {}) {
+    super(options)
+    this.router = new PatternRouter()
+  }
+}

package/plugins/acryl-router/src/core/utils/types.ts

@@ -125,6 +125,9 @@ export type BufferSource = ArrayBufferView<ArrayBuffer> | ArrayBuffer
 /** A Web Crypto key, named from the runtime's own `crypto` so the public types do not need the DOM library. */
 export type CryptoKey = Awaited<ReturnType<typeof crypto.subtle.importKey>>
 
+/** What the Web `Headers` constructor accepts, named from the runtime's own `Headers` so the public types do not need the DOM library. */
+export type HeadersInit = NonNullable<ConstructorParameters<typeof Headers>[0]>
+
 /** How a WebSocket hands binary data to `onmessage`; declared here so the public types do not need the DOM library. */
 export type BinaryType = 'arraybuffer' | 'blob'
 

package/plugins/acryl-router/src/helpers/index.ts

@@ -5,6 +5,8 @@ export { createFactory, createMiddleware, Factory } from '../core/helper/factory
 export { deleteCookie, generateCookie, generateSignedCookie, getCookie, getSignedCookie, setCookie, setSignedCookie } from '../core/helper/cookie/index.ts'
 export { getExtension, getMimeType, mimes, type BaseMime } from '../core/utils/mime.ts'
 export { html, raw } from '../core/helper/html/index.ts'
+export { proxy } from '../core/helper/proxy/index.ts'
+export { getRouterName, inspectRoutes, showRoutes } from '../core/helper/dev/index.ts'
 export { matchedRoutes, routePath, baseRoutePath, basePath } from '../core/helper/route/index.ts'
 export { testClient } from '../core/helper/testing/index.ts'
 export { stream, streamSSE, streamText, SSEStreamingApi, type SSEMessage } from '../core/helper/streaming/index.ts'

package/plugins/acryl-router/src/middleware/index.ts

@@ -1,6 +1,7 @@
 export { basicAuth } from '../core/middleware/basic-auth/index.ts'
 export { bearerAuth } from '../core/middleware/bearer-auth/index.ts'
 export { bodyLimit } from '../core/middleware/body-limit/index.ts'
+export { cache } from '../core/middleware/cache/index.ts'
 export { every, except, some } from '../core/middleware/combine/index.ts'
 export { compress } from '../core/middleware/compress/index.ts'
 export { contextStorage, getContext, tryGetContext } from '../core/middleware/context-storage/index.ts'
@@ -14,6 +15,7 @@ export { detectFromCookie, detectFromHeader, detectFromPath, detectFromQuery, la
 export { logger } from '../core/middleware/logger/index.ts'
 export { methodNotAllowed } from '../core/middleware/method-not-allowed/index.ts'
 export { methodOverride } from '../core/middleware/method-override/index.ts'
+export { mount } from '../core/middleware/mount/index.ts'
 export { poweredBy } from '../core/middleware/powered-by/index.ts'
 export { prettyJSON } from '../core/middleware/pretty-json/index.ts'
 export { requestId, type RequestIdVariables } from '../core/middleware/request-id/index.ts'

package/plugins/acryl-router/src/service.ts

@@ -54,13 +54,30 @@ declare module '@deepseek-ai/cordis' {
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 export const name = 'acryl-router'
 
-// Any `Acryl`, whatever its Env and schema; the router only reads its routes.
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type MountableApp = Acryl<any, any, any>
+/**
+ * What {@link Router.route} takes: any app with routes, read structurally. An `Acryl` from this package qualifies, and so does one built from
+ * another copy of the framework (the published `acrylblends`), whose classes TypeScript would refuse nominally for their private members:
+ * mounting copies the app's routes (and keeps its own `onError`), which is all the router reads. Their handlers are then called with this
+ * router's `Context`, which has the same shape.
+ */
+export interface MountableApp {
+  readonly routes: readonly MountableRoute[]
+}
+
+/** One route of a {@link MountableApp}, as the core lists it. A handler of any context type fits (`never` parameters accept every function). */
+export interface MountableRoute {
+  readonly basePath: string
+  readonly path: string
+  readonly method: string
+  readonly handler: (c: never, next: never) => unknown
+}
+
+/** The core's `app.route` with a structural app: at run time it reads only the routes and the app's own error handler. */
+const copyRoutes = (app: MountableApp): Acryl => new Acryl().route('/', app as unknown as Acryl)
 
 interface Mount {
   readonly path: string
-  readonly app: MountableApp
+  readonly app: Acryl
 }
 
 interface RouterState {
@@ -161,7 +178,7 @@ export class Router extends Service {
    * mount's code a request is in. The core's `app.route` runs first so a sub-app's own `onError` still applies to its routes.
    */
   private snapshot(path: string, app: MountableApp): Mount {
-    const copy = new Acryl().route('/', app)
+    const copy = copyRoutes(app)
     const tagged = new Acryl()
     const mount: Mount = { path, app: tagged }
     for (const route of copy.routes) {

package/plugins/acryl-router/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router",
-    "commit": "5743482e4199ded676a77f594bce15fd4aa0ca2f"
+    "commit": "0174cb01625bfd32d0162ad56179c582f353321e"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 4,
-  "digest": "sha256:543a5ca99518eea1fe2e319b7708d62af34a6c24ab3daeb17dde48d67d319d6a",
+  "digest": "sha256:e732a94e1cf98c4390780156359603dc5d3d33597baf21457082fb33c120cb90",
   "testsNotRun": {
     "tests/loader.spec.ts": "loads the built lib/ entry through the real Loader; the library ships source and has no build"
   },

package/plugins/acryl-router-http/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router-http",
-    "commit": "5743482e4199ded676a77f594bce15fd4aa0ca2f"
+    "commit": "0174cb01625bfd32d0162ad56179c582f353321e"
   },
   "vendored": [
     "src",

package/plugins/acryl-state/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-state",
-    "commit": "5743482e4199ded676a77f594bce15fd4aa0ca2f"
+    "commit": "0174cb01625bfd32d0162ad56179c582f353321e"
   },
   "vendored": [
     "src",

package/plugins/desktop/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "5743482e4199ded676a77f594bce15fd4aa0ca2f"
+    "commit": "0174cb01625bfd32d0162ad56179c582f353321e"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/desktop-web/main.ts

@@ -0,0 +1,92 @@
+/**
+ * The desktop shell of a plain Acryl app: `npm run desktop` serves the app (`src/app.ts`, `export default app`) on a free loopback port from this Electron main process and
+ * opens one window on it. Nothing in the app imports electron; every Electron call is in this file and `window.ts`, so a different shell is a change here only.
+ *
+ * Order matters: the user-data folder is set before anything else (and before the single-instance lock), so one app never shares window state, logs or the lock with
+ * another app or with the real user's data.
+ */
+
+import { mkdirSync, readFileSync } from 'node:fs'
+import type { AddressInfo } from 'node:net'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { serve } from 'acrylblends/node-server'
+import { app, BrowserWindow, shell } from 'electron'
+import acrylApp from '../../app.ts'
+import { createDesktopShutdown, installShutdownRequests } from './shutdown.ts'
+import { resolveDesktopUserDataOverride } from './user-data.ts'
+import { windowOptions } from './window.ts'
+
+const projectRoot = fileURLToPath(new URL('../../..', import.meta.url))
+const manifest = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8')) as {
+  name?: string
+  acrylblends?: { desktopPath?: string }
+}
+
+/** Electron's user-data folder: an explicit DSH_DESKTOP_USER_DATA, else a folder inside the app's own folder. */
+const userData =
+  resolveDesktopUserDataOverride(process.env) ?? join(projectRoot, '.acrylblends', 'electron')
+mkdirSync(userData, { recursive: true, mode: 0o700 })
+app.setPath('userData', userData)
+app.setName(manifest.name ?? 'acryl-app')
+
+if (!app.requestSingleInstanceLock()) {
+  // The same app is already open: its window takes focus (see `second-instance` below) and this process ends.
+  app.quit()
+} else {
+  let server: ReturnType<typeof serve> | undefined
+  let window: BrowserWindow | undefined
+
+  const shutdown = createDesktopShutdown(
+    () =>
+      new Promise<void>((done) => {
+        if (server === undefined) return done()
+        server.close(() => {
+          done()
+        })
+        // Open streams and keep-alive connections would hold close() open: end them.
+        ;(server as { closeAllConnections?: () => void }).closeAllConnections?.()
+      }),
+    (code) => {
+      app.exit(code)
+    },
+  )
+  installShutdownRequests(process, app, (code) => {
+    void shutdown.request(code)
+  })
+
+  app.on('second-instance', () => {
+    if (window === undefined) return
+    if (window.isMinimized()) window.restore()
+    window.focus()
+  })
+  // The window is the app: closing it ends the process on every platform, after the server has stopped.
+  app.on('window-all-closed', () => {
+    void shutdown.request(0)
+  })
+
+  void app.whenReady().then(async () => {
+    const port = await new Promise<number>((resolve) => {
+      server = serve(
+        { fetch: acrylApp.fetch, port: 0, hostname: '127.0.0.1' },
+        (info: AddressInfo) => {
+          resolve(info.port)
+        },
+      )
+    })
+    const origin = `http://127.0.0.1:${port}`
+    window = new BrowserWindow(windowOptions({ title: manifest.name ?? 'acryl-app' }))
+    window.once('ready-to-show', () => window?.show())
+    // Navigation stays on the app's own server; any other address opens in the system browser.
+    window.webContents.setWindowOpenHandler(({ url }) => {
+      void shell.openExternal(url)
+      return { action: 'deny' }
+    })
+    window.webContents.on('will-navigate', (event, url) => {
+      if (new URL(url).origin === origin) return
+      event.preventDefault()
+      void shell.openExternal(url)
+    })
+    await window.loadURL(new URL(manifest.acrylblends?.desktopPath ?? '/', origin).href)
+  })
+}

package/plugins/desktop-web/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "desktop-web",
+  "description": "Run a plain Acryl app (`export default app`) as a desktop app: an Electron window on the app's own server. `npm run desktop`; the app's code never imports electron. `acrylblends add desktop` picks this one for an app without the Blend plugins.",
+  "requires": [],
+  "inject": [],
+  "provides": [],
+  "dependencies": {},
+  "devDependencies": {
+    "electron": "44.0.0"
+  },
+  "scripts": {
+    "desktop": "electron src/plugins/desktop-web/main.ts"
+  },
+  "gitignore": [".acrylblends/"],
+  "omit": ["**/*.test.*"],
+  "mount": "nothing to mount: run `npm install`, then `npm run desktop` (the window opens on the app's own server; every electron call is in src/plugins/desktop-web)"
+}

package/plugins/desktop-web/shutdown.ts

@@ -0,0 +1,177 @@
+/** Application-level quit sources that must remain active before any window mounts. */
+
+/** Maximum grace allowed for the Cordis tree to dispose before native exit. */
+export const DESKTOP_SHUTDOWN_TIMEOUT_MS = 5_000
+
+/**
+ * Exit code a dev-mode relaunch uses instead of `app.relaunch()`.
+ *
+ * `acryl-desktop/scripts/launch-dev.mjs` stages the Electron runtime into a
+ * fresh, per-run temp directory and deletes it as soon as this process
+ * exits. `app.relaunch()` would spawn a new process pointed at that same
+ * (about to be deleted) executable path, which crashes at dyld load time
+ * ("Library not loaded: Electron Framework") instead of restarting the app.
+ * `main.ts` exits with this code under the dev launcher instead of calling
+ * `app.relaunch()`; `launch-dev.mjs` recognizes it and stages a fresh bundle
+ * before spawning again. The literal `43` is mirrored in `launch-dev.mjs` -
+ * that plain script cannot import this compiled module.
+ */
+export const DESKTOP_DEV_RESTART_EXIT_CODE = 43
+
+/** Bounded, escalating shutdown controller for the Electron application. */
+export interface DesktopShutdown {
+  /** Start graceful disposal, or force exit when a shutdown already owns it. */
+  request(code: number): Promise<void>
+}
+
+/** Native operations performed after the Host tree has disposed. */
+export interface DesktopNativeExit {
+  /** Mark the window close path as a final process exit. */
+  prepareToQuit(): void
+  /**
+   * Schedule a fresh Electron process and terminate the current one - fully
+   * owns process exit; `finish()` never calls `exit()` afterward. A packaged
+   * install's implementation must call both `app.relaunch()` (schedule) and
+   * `app.exit()` (terminate this instance) itself - `app.relaunch()` alone
+   * does not end the current process. Calling `exit()` again afterward with
+   * a different code is not a graceful no-op: two `app.exit()` calls in
+   * quick succession race, and the second one's code wins - confirmed live
+   * (`app.exit(DESKTOP_DEV_RESTART_EXIT_CODE)` from the dev-mode branch,
+   * immediately followed by `finish()`'s own unconditional `app.exit(0)`,
+   * silently replaced the dev-restart signal with a plain exit, so
+   * `launch-dev.mjs`'s loop saw code 0, concluded "not a restart," and
+   * returned instead of staging a fresh bundle and respawning - the app
+   * closed with no automatic restart, every time).
+   */
+  relaunch(): void
+  /** End the current Electron process without another quit event. */
+  exit(code: number): void
+}
+
+/** Final-exit state shared by ordinary quits and mode-change relaunches. */
+export interface DesktopExitCoordinator {
+  /** Mark the next successful exit as a relaunch. */
+  requestRelaunch(): void
+  /** Complete one native exit after Cordis teardown. */
+  finish(code: number): void
+}
+
+/**
+ * Coordinate the final Electron action without relaunching failed generations.
+ * @param native - native application and runtime exit operations.
+ * @param beforeExit - listener cleanup that must precede app.exit.
+ * @returns a final-exit controller consumed by the shutdown path.
+ */
+export function createDesktopExitCoordinator(
+  native: DesktopNativeExit,
+  beforeExit: () => void,
+): DesktopExitCoordinator {
+  let relaunchRequested = false
+  return {
+    requestRelaunch() {
+      relaunchRequested = true
+    },
+    finish(code) {
+      beforeExit()
+      native.prepareToQuit()
+      // relaunch() fully owns process termination (see its doc comment) -
+      // calling exit() afterward would race it and can silently replace
+      // whichever exit code relaunch() actually needs with this one.
+      if (relaunchRequested && code === 0) {
+        native.relaunch()
+        return
+      }
+      native.exit(code)
+    },
+  }
+}
+
+/**
+ * Create one bounded shutdown around the Host Cordis disposer.
+ * @param dispose - whole Host tree teardown.
+ * @param exit - final native process exit.
+ * @param timeoutMs - grace before forced exit.
+ * @returns a controller whose second request escalates immediately.
+ */
+export function createDesktopShutdown(
+  dispose: () => Promise<void>,
+  exit: (code: number) => void,
+  timeoutMs = DESKTOP_SHUTDOWN_TIMEOUT_MS,
+): DesktopShutdown {
+  let pending: Promise<void> | undefined
+  let timeout: ReturnType<typeof setTimeout> | undefined
+  let exited = false
+
+  const exitOnce = (code: number): void => {
+    if (exited) return
+    exited = true
+    if (timeout !== undefined) clearTimeout(timeout)
+    exit(code)
+  }
+
+  return {
+    request(code) {
+      if (pending !== undefined) {
+        exitOnce(code)
+        return pending
+      }
+      const failureCode = code === 0 ? 1 : code
+      timeout = setTimeout(() => { exitOnce(failureCode) }, timeoutMs)
+      pending = Promise.resolve().then(dispose).then(
+        () => { exitOnce(code) },
+        () => { exitOnce(failureCode) },
+      )
+      return pending
+    },
+  }
+}
+
+/** Minimal native quit event consumed by the launcher. */
+export interface DesktopQuitEvent {
+  /** Cancel Electron's immediate default exit. */
+  preventDefault(): void
+}
+
+/** Process signal surface used by the shutdown coordinator. */
+export interface DesktopSignalSource {
+  /** Register one shutdown signal listener. */
+  on(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown
+  /** Remove one shutdown signal listener. */
+  off(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown
+}
+
+/** Electron application surface used by the shutdown coordinator. */
+export interface DesktopQuitSource {
+  /** Register the native quit guard. */
+  on(event: 'before-quit', listener: (event: DesktopQuitEvent) => void): unknown
+  /** Remove the native quit guard. */
+  off(event: 'before-quit', listener: (event: DesktopQuitEvent) => void): unknown
+}
+
+/**
+ * Route every application-level quit source through Cordis teardown.
+ * @param signals - process signal owner.
+ * @param nativeApp - Electron application event owner.
+ * @param requestQuit - idempotent launcher shutdown request.
+ * @returns a disposer removing every listener.
+ */
+export function installShutdownRequests(
+  signals: DesktopSignalSource,
+  nativeApp: DesktopQuitSource,
+  requestQuit: (code: number) => void,
+): () => void {
+  const interrupt = (): void => { requestQuit(130) }
+  const terminate = (): void => { requestQuit(0) }
+  const beforeQuit = (event: DesktopQuitEvent): void => {
+    event.preventDefault()
+    requestQuit(0)
+  }
+  signals.on('SIGINT', interrupt)
+  signals.on('SIGTERM', terminate)
+  nativeApp.on('before-quit', beforeQuit)
+  return () => {
+    signals.off('SIGINT', interrupt)
+    signals.off('SIGTERM', terminate)
+    nativeApp.off('before-quit', beforeQuit)
+  }
+}

package/plugins/desktop-web/upstream.json

@@ -0,0 +1,12 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "files": {
+      "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
+      "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
+    },
+    "commit": "0174cb01625bfd32d0162ad56179c582f353321e"
+  },
+  "rewrittenSpecifiers": 0,
+  "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"
+}