gestalt-mobile 0.37.1 → 0.38.0

package/README.md

@@ -32,6 +32,17 @@ The command prints the loopback URL when it is ready. Open that URL in a
 browser. Press Ctrl-C, or send SIGINT or SIGTERM, to stop the HTTP server,
 active Codex subprocesses, and database cleanly.
 
+Use `--icon <path>` to replace the installed PWA application icon with a local
+SVG or PNG. Relative paths resolve from the directory where Mobile is started:
+
+```sh
+gestalt-mobile --cwd . --icon ./branding/project-icon.svg
+```
+
+Without `--icon`, Mobile keeps its packaged Gestalt icons. SVG icons are
+declared scalable; PNG dimensions are read from the file. A square PNG of at
+least 512×512 is recommended for consistent launcher presentation.
+
 ### Run this checkout
 
 `npm run start` builds and runs the current checkout with the same managed
@@ -149,6 +160,7 @@ checks with `npm run format:check`, `npm run license:check`, `npm run check`,
 | `--public-origin <origin>` | Loopback Vite origin | Exact browser origin for passkeys; required for non-loopback hosts |
 | `--disable-passkey-auth`   | Off                  | Disable passkey access control and serve every client directly     |
 | `--data-dir <path>`        | XDG state directory  | Directory containing `relay.sqlite`                                |
+| `--icon <path>`            | Gestalt icons        | SVG or PNG used when installing the PWA                            |
 | `--skills <profile>`       |                      | Apply a saved global profile to every session                      |
 | `--skills list`            |                      | List global profiles without starting the server                   |
 | `--help`                   |                      | Print usage without starting the application                       |

package/dist/server/server/app.js

@@ -19,6 +19,7 @@ import { registerOrgPlanAttentionRoutes } from './features/org-plan-attention/re
 import { registerAutopilotRoutes } from './features/autopilot/register-routes.js';
 import { registerFileRoutes } from './features/files/register-routes.js';
 import { registerMaintenanceRoutes } from './features/maintenance/register-routes.js';
+import { registerPwaRoutes } from './features/pwa/register-routes.js';
 export async function buildApp(deps) {
     // Keep the default boundary finite even when an endpoint forgot a narrower schema.
     const app = fastify({ logger: false, bodyLimit: 1024 * 1024 });
@@ -32,6 +33,8 @@ export async function buildApp(deps) {
         return payload;
     });
     await app.register(fastifyCookie);
+    if (deps.pwaIcon)
+        registerPwaRoutes(app, deps.pwaIcon);
     if (deps.staticDir)
         await app.register(fastifyStatic, { root: deps.staticDir });
     if (deps.auth)

package/dist/server/server/cli.js

@@ -14,6 +14,7 @@ import { composeRelayApp } from './composition.js';
 import { CliUsageError, parseConfig } from './config.js';
 import { LauncherProfileCatalog } from './platform/catalog/launcher-profile-catalog.js';
 import { FilesystemSkillProfileStore } from './platform/skills/filesystem-skill-profile-store.js';
+import { loadPwaIcon } from './platform/pwa/load-pwa-icon.js';
 const runFile = promisify(execFile);
 export const usage = `Usage: gestalt-mobile [options]
 
@@ -24,6 +25,7 @@ Options:
   --public-origin <origin> Exact HTTPS browser origin for passkeys (localhost may use HTTP)
   --disable-passkey-auth Disable passkey access control (unsafe on shared or network hosts)
   --data-dir <path>  Directory for persistent application data
+  --icon <path>      SVG or PNG used as the installed PWA application icon
   --skills <profile> Use a global skill profile for every session
   --skills list      List saved global skill profiles without starting the server
   --help             Show this help
@@ -205,6 +207,14 @@ export async function runCli(dependencies = {}) {
         stderr.write(`Unknown skill profile: ${config.skillsProfile}\n\n${usage}\n`);
         return 2;
     }
+    let pwaIcon;
+    try {
+        pwaIcon = config.iconPath ? await loadPwaIcon(config.iconPath) : undefined;
+    }
+    catch (error) {
+        stderr.write(`${error instanceof Error ? error.message : 'Invalid --icon file'}\n\n${usage}\n`);
+        return 2;
+    }
     const diagnosis = await (dependencies.runStartupDoctor ?? runStartupDoctor)(cwd);
     if (diagnosis.report)
         stderr.write(diagnosis.report);
@@ -219,6 +229,7 @@ export async function runCli(dependencies = {}) {
         relyingParty: config.relyingParty,
         passkeyAuthEnabled: config.passkeyAuthEnabled,
         staticDir: packagedClientDir(moduleUrl),
+        pwaIcon,
         profiles: new LauncherProfileCatalog(),
         installedCodexVersion,
         installedKimiVersion,

package/dist/server/server/composition.js

@@ -1026,6 +1026,7 @@ export async function composeRelayApp(options) {
             },
             logger: console,
             staticDir: options.staticDir,
+            pwaIcon: options.pwaIcon,
             recentThreads: recentThreadsForRelay,
             bootstrap: {
                 workspaces,

package/dist/server/server/config.js

@@ -15,6 +15,7 @@ const optionNames = new Set([
     '--data-dir',
     '--public-origin',
     '--skills',
+    '--icon',
 ]);
 const flagNames = new Set(['--disable-passkey-auth']);
 export function parseConfig(args, cwd = process.cwd()) {
@@ -57,8 +58,14 @@ export function parseConfig(args, cwd = process.cwd()) {
         root: resolve(cwd, values.get('--cwd') ?? '.'),
         dataDir: values.get('--data-dir'),
         skillsProfile: values.get('--skills'),
+        iconPath: values.has('--icon') ? resolveIconPath(cwd, values.get('--icon')) : undefined,
     };
 }
+function resolveIconPath(cwd, value) {
+    if (!/\.(?:png|svg)$/i.test(value))
+        throw new CliUsageError('--icon must reference an SVG or PNG file');
+    return resolve(cwd, value);
+}
 export function normalizePublicOrigin(value) {
     if (!/^[a-z][a-z\d+.-]*:\/\/[^/?#\s\\\\]+\/?$/i.test(value))
         throw new CliUsageError('--public-origin must be a bare origin without a path, query, or fragment');

package/dist/server/server/features/pwa/register-routes.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2026 Dyne.org foundation
+ * Designed by Denis Roio <jaromil@dyne.org>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+const manifestBase = {
+    id: '/',
+    name: 'Gestalt Mobile',
+    short_name: 'Gestalt',
+    description: 'A mobile interface for durable Codex development sessions.',
+    start_url: '/',
+    scope: '/',
+    display: 'standalone',
+    background_color: '#141414',
+    theme_color: '#141414',
+    categories: ['productivity', 'utilities'],
+};
+/** Overrides only install metadata; ordinary client assets stay package-static. */
+export function registerPwaRoutes(app, icon) {
+    const iconPath = `/install-icon.${icon.extension}`;
+    app.get('/manifest.webmanifest', async (_request, reply) => reply
+        .header('Cache-Control', 'no-cache')
+        .type('application/manifest+json')
+        .send({
+        ...manifestBase,
+        icons: [
+            {
+                src: iconPath,
+                sizes: icon.sizes,
+                type: icon.contentType,
+                purpose: 'any',
+            },
+        ],
+    }));
+    app.get(iconPath, async (_request, reply) => reply.header('Cache-Control', 'no-cache').type(icon.contentType).send(icon.bytes));
+}

package/dist/server/server/platform/pwa/load-pwa-icon.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2026 Dyne.org foundation
+ * Designed by Denis Roio <jaromil@dyne.org>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+const maxIconBytes = 5 * 1024 * 1024;
+const pngSignature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+export async function loadPwaIcon(path) {
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch {
+        throw new Error(`Unable to read --icon file: ${path}`);
+    }
+    if (bytes.length === 0 || bytes.length > maxIconBytes)
+        throw new Error('--icon must be a non-empty SVG or PNG no larger than 5 MiB');
+    const extension = extname(path).toLowerCase();
+    if (extension === '.svg') {
+        if (!/<svg(?:\s|>)/i.test(bytes.toString('utf8')))
+            throw new Error('--icon SVG does not contain an <svg> root');
+        return { bytes, contentType: 'image/svg+xml', extension: 'svg', sizes: 'any' };
+    }
+    if (extension !== '.png' ||
+        bytes.length < 24 ||
+        !bytes.subarray(0, 8).equals(pngSignature) ||
+        bytes.toString('ascii', 12, 16) !== 'IHDR')
+        throw new Error('--icon PNG has an invalid header');
+    const width = bytes.readUInt32BE(16);
+    const height = bytes.readUInt32BE(20);
+    if (width === 0 || height === 0)
+        throw new Error('--icon PNG has invalid dimensions');
+    return { bytes, contentType: 'image/png', extension: 'png', sizes: `${width}x${height}` };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gestalt-mobile",
-  "version": "0.37.1",
+  "version": "0.38.0",
   "description": "Mobile-first web relay for durable Codex development sessions",
   "keywords": [
     "codex",