feat: auto-toggle Chromium app mode for small viewports (#153)

## Summary
- Automatically enables Chromium `--app` mode when the requested display
width < 500px or height < 200px, removing the tab/toolbar chrome that
enforces a ~500px minimum window width
- Adds `RemoveFlagsByPrefix` and `HasFlagWithPrefix` helpers to the
`chromiumflags` package for dynamic flag management
- Adds manually crafted modelines for exact 390x844 (iPhone 14/15) and
768x1024 (tablet) viewports at 60/30/25 Hz, bypassing CVT's
multiple-of-8 width convention since the Xorg dummy driver doesn't
require it

## Context

Chromium enforces a minimum window size of approximately 500px wide due
to the tab bar and toolbar chrome. Launching with `--app=<url>` removes
this chrome, allowing the window to resize to mobile viewports like
390x844. The `PatchDisplay` endpoint now automatically toggles this flag
based on the requested dimensions and restarts Chromium when needed.

The modelines use exact pixel widths (e.g. 390 instead of 392) with
manually calculated timing parameters that keep the pixel clock above
the Xorg dummy driver's 11 MHz minimum. CVT's convention of rounding
widths to multiples of 8 is a standard for real monitor compatibility —
the dummy driver is more permissive.

Depends on kernel/neko#11 for correct width
handling (removes Neko's Go-level rounding that was truncating 390 →
384).

## Test plan
- [x] `PATCH /display` with `{"width": 390, "height": 844}` — enables
app mode, display is exactly 390x844
- [x] `PATCH /display` with `{"width": 768, "height": 1024}` — no app
mode, display is 768x1024
- [x] `PATCH /display` with `{"width": 1920, "height": 1080}` — disables
app mode if previously enabled
- [x] Verify `RemoveFlagsByPrefix` and `HasFlagWithPrefix` unit tests
pass

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes runtime Chromium flag management and automatically triggers
restarts based on viewport size, which can impact session stability and
resize behavior; also updates Neko/image dependencies that affect
display handling.
> 
> **Overview**
> Automatically toggles Chromium *app mode* during `PATCH /display`:
when the requested size is below `500x200`, the API adds
`--app=https://start.duckduckgo.com` to the runtime flags and forces a
Chromium restart; when returning to normal sizes it removes the flag.
> 
> Refactors Chromium runtime flag writing around a shared
`chromiumFlagsPath` constant + `writeChromiumFlags`, adds
`chromiumflags.RemoveFlagsByPrefix`/`HasFlagWithPrefix` helpers (with
new tests), and extends the headful Xorg dummy config with exact
`390x844` (iPhone) and `768x1024` modelines at 60/30/25 Hz. Also bumps
the `neko` base image/dependency version and ignores the built
`chromium-launcher` binary in `server/.gitignore`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
9e9dfdf. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: hiroTamada

images/chromium-headful/Dockerfile

@@ -146,7 +146,7 @@ RUN --mount=type=cache,target=/tmp/cache/ffmpeg,sharing=locked,id=$CACHEIDPREFIX
     rm -rf /tmp/ffmpeg*
 EOT
 
-FROM ghcr.io/kernel/neko/base:3.0.8-v1.3.0 AS neko
+FROM ghcr.io/kernel/neko/base:3.0.8-v1.4.0 AS neko
 # ^--- now has event.SYSTEM_PONG with legacy support to keepalive
 FROM node:22-bullseye-slim AS node-22
 FROM docker.io/ubuntu:22.04

images/chromium-headful/xorg.conf

@@ -66,6 +66,10 @@ Section "Monitor"
   Modeline "960x720_60.00" 55.86 960 1008 1104 1248 720 721 724 746 -HSync +Vsync
   # 800x600 @ 60.00 Hz (GTF) hsync: 37.32 kHz; pclk: 38.22 MHz
   Modeline "800x600_60.00" 38.22 800 832 912 1024 600 601 604 622 -HSync +Vsync
+  # 768x1024 @ 60.00 Hz (GTF) hsync: 63.60 kHz; pclk: 65.13 MHz
+  Modeline "768x1024_60.00" 65.13 768 816 896 1024 1024 1025 1028 1060 -HSync +Vsync
+  # 390x844 @ 60.00 Hz (manual, non-CVT) pclk: 27.26 MHz (mobile: iPhone 14/15)
+  Modeline "390x844_60.00" 27.26 390 406 446 520 844 845 848 874 -HSync +Vsync
   # 2560x1440 @ 60.00 Hz (GTF) hsync: 89.52 kHz; pclk: 312.25 MHz
   Modeline "2560x1440_60.00" 312.25 2560 2752 3024 3488 1440 1443 1448 1493 -HSync +Vsync
   # 1024x768 @ 60.00 Hz (GTF) hsync: 47.70 kHz; pclk: 63.50 MHz
@@ -89,6 +93,10 @@ Section "Monitor"
   Modeline "960x720_30.00" 25.33 960 960 1056 1152 720 721 724 733 -HSync +Vsync
   # 800x600 @ 30.00 Hz (GTF) hsync: 18.33 kHz; pclk: 17.01 MHz
   Modeline "800x600_30.00" 17.01 800 792 864 928 600 601 604 611 -HSync +Vsync
+  # 768x1024 @ 30.00 Hz (GTF) hsync: 31.26 kHz; pclk: 30.01 MHz
+  Modeline "768x1024_30.00" 30.01 768 784 864 960 1024 1025 1028 1042 -HSync +Vsync
+  # 390x844 @ 30.00 Hz (manual, non-CVT) pclk: 12.57 MHz (mobile: iPhone 14/15)
+  Modeline "390x844_30.00" 12.57 390 406 446 488 844 845 848 859 -HSync +Vsync
   # 1920x1200 @ 30.00 Hz (GTF) hsync: 36.90 kHz; pclk: 96.00 MHz
   Modeline "1920x1200_30.00" 96.00 1920 2000 2200 2528 1200 1203 1209 1235 -HSync +Vsync
   # 1440x900 @ 30.00 Hz (GTF) hsync: 27.72 kHz; pclk: 52.80 MHz
@@ -120,6 +128,10 @@ Section "Monitor"
   Modeline "1200x800_25.00" 31.48 1200 1224 1352 1540 800 801 804 818 -HSync +Vsync
   # 800x1600 @ 24.92 Hz (CVT) hsync: 40.53 kHz; pclk: 41.50 MHz
   Modeline "800x1600_25.00"   41.50  800 832 912 1024  1600 1603 1613 1626 -Hsync +Vsync
+  # 768x1024 @ 25.00 Hz (GTF) hsync: 25.97 kHz; pclk: 24.52 MHz
+  Modeline "768x1024_25.00" 24.52 768 784 856 944 1024 1025 1028 1039 -HSync +Vsync
+  # 390x844 @ 25.00 Hz (manual, non-CVT) pclk: 11.14 MHz (mobile: iPhone 14/15)
+  Modeline "390x844_25.00" 11.14 390 406 446 520 844 845 848 857 -HSync +Vsync
 
   # 2560x1440 @ 10.00 Hz (GTF) hsync: 14.65 kHz; pclk: 48.76 MHz
   Modeline "2560x1440_10.00" 48.76 2560 2568 2816 3104 1440 1441 1444 1465 -HSync +Vsync
@@ -143,7 +155,7 @@ Section "Screen"
   SubSection "Display"
     Viewport 0 0
     Depth 24
-    Modes "2560x1440_60.00" "1920x1080_60.00" "1920x1200_60.00" "1440x900_60.00" "1280x720_60.00" "1200x800_60.00" "1152x648_60.00" "1024x768_60.00" "1024x576_60.00" "960x720_60.00" "800x600_60.00" "2560x1440_30.00" "1920x1080_30.00" "1920x1200_30.00" "1440x900_30.00" "1368x768_30.00" "1280x720_30.00" "1200x800_30.00" "1152x648_30.00" "1024x768_30.00" "1024x576_30.00" "960x720_30.00" "800x600_30.00" "800x1600_30.00" "3840x2160_25.00" "2560x1440_25.00" "1920x1080_25.00" "1920x1200_25.00" "1600x900_25.00" "1440x900_25.00" "1368x768_25.00" "1200x800_25.00" "1024x768_25.00" "800x1600_25.00" "2560x1440_10.00" "1920x1080_10.00" "1920x1200_10.00" "1440x900_10.00" "1200x800_10.00" "1024x768_10.00"
+    Modes "2560x1440_60.00" "1920x1080_60.00" "1920x1200_60.00" "1440x900_60.00" "1280x720_60.00" "1200x800_60.00" "1152x648_60.00" "1024x768_60.00" "1024x576_60.00" "960x720_60.00" "800x600_60.00" "768x1024_60.00" "390x844_60.00" "2560x1440_30.00" "1920x1080_30.00" "1920x1200_30.00" "1440x900_30.00" "1368x768_30.00" "1280x720_30.00" "1200x800_30.00" "1152x648_30.00" "1024x768_30.00" "1024x576_30.00" "960x720_30.00" "800x600_30.00" "800x1600_30.00" "768x1024_30.00" "390x844_30.00" "3840x2160_25.00" "2560x1440_25.00" "1920x1080_25.00" "1920x1200_25.00" "1600x900_25.00" "1440x900_25.00" "1368x768_25.00" "1200x800_25.00" "1024x768_25.00" "800x1600_25.00" "768x1024_25.00" "390x844_25.00" "2560x1440_10.00" "1920x1080_10.00" "1920x1200_10.00" "1440x900_10.00" "1200x800_10.00" "1024x768_10.00"
   EndSubSection
 EndSection
 

server/.gitignore

@@ -28,6 +28,7 @@ go.work
 
 .tmp/
 bin/
+chromium-launcher
 recordings/
 
 # downconverted openapi spec

server/cmd/api/api/chromium.go

@@ -21,6 +21,15 @@ import (
 
 var nameRegex = regexp.MustCompile(`^[A-Za-z0-9._-]{1,255}$`)
 
+const (
+	// chromiumFlagsPath is the runtime flags file read by the chromium-launcher at startup.
+	chromiumFlagsPath = "/chromium/flags"
+
+	// appModeURL is the URL loaded in --app mode for small viewports. Keep in
+	// sync with "NewTabPageLocation" in shared/chromium-policies/managed/policy.json.
+	appModeURL = "https://start.duckduckgo.com"
+)
+
 // UploadExtensionsAndRestart handles multipart upload of one or more extension zips, extracts
 // them under /home/kernel/extensions/<name>, writes /chromium/flags to enable them, restarts
 // Chromium via supervisord, and waits (via UpstreamManager) until DevTools is ready.
@@ -291,14 +300,12 @@ func (s *ApiService) UploadExtensionsAndRestart(ctx context.Context, request oap
 }
 
 // mergeAndWriteChromiumFlags reads existing flags, merges them with new flags,
-// and writes the result back to /chromium/flags. Returns the merged tokens or an error.
+// and writes the result back to chromiumFlagsPath. Returns the merged tokens or an error.
 func (s *ApiService) mergeAndWriteChromiumFlags(ctx context.Context, newTokens []string) ([]string, error) {
 	log := logger.FromContext(ctx)
 
-	const flagsPath = "/chromium/flags"
-
-	// Read existing runtime flags from /chromium/flags (if any)
-	existingTokens, err := chromiumflags.ReadOptionalFlagFile(flagsPath)
+	// Read existing runtime flags (if any)
+	existingTokens, err := chromiumflags.ReadOptionalFlagFile(chromiumFlagsPath)
 	if err != nil {
 		log.Error("failed to read existing flags", "error", err)
 		return nil, fmt.Errorf("failed to read existing flags: %w", err)
@@ -309,22 +316,27 @@ func (s *ApiService) mergeAndWriteChromiumFlags(ctx context.Context, newTokens [
 	// Merge existing flags with new flags using token-aware API
 	mergedTokens := chromiumflags.MergeFlags(existingTokens, newTokens)
 
-	// Ensure the chromium directory exists
-	if err := os.MkdirAll("/chromium", 0o755); err != nil {
-		log.Error("failed to create chromium dir", "error", err)
-		return nil, fmt.Errorf("failed to create chromium dir: %w", err)
-	}
-
-	// Write flags file with merged flags
-	if err := chromiumflags.WriteFlagFile(flagsPath, mergedTokens); err != nil {
+	if err := writeChromiumFlags(mergedTokens); err != nil {
 		log.Error("failed to write flags", "error", err)
-		return nil, fmt.Errorf("failed to write flags: %w", err)
+		return nil, err
 	}
 
 	log.Info("flags written", "merged", mergedTokens)
 	return mergedTokens, nil
 }
 
+// writeChromiumFlags ensures the /chromium directory exists and writes tokens
+// to chromiumFlagsPath. Shared by mergeAndWriteChromiumFlags and ensureAppMode.
+func writeChromiumFlags(tokens []string) error {
+	if err := os.MkdirAll("/chromium", 0o755); err != nil {
+		return fmt.Errorf("failed to create chromium dir: %w", err)
+	}
+	if err := chromiumflags.WriteFlagFile(chromiumFlagsPath, tokens); err != nil {
+		return fmt.Errorf("failed to write flags file: %w", err)
+	}
+	return nil
+}
+
 // restartChromiumAndWait restarts Chromium via supervisorctl and waits for DevTools to be ready.
 // Returns an error if the restart fails or times out.
 func (s *ApiService) restartChromiumAndWait(ctx context.Context, operation string) error {

server/cmd/api/api/display.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 
 	nekooapi "github.com/m1k1o/neko/server/lib/oapi"
+	"github.com/onkernel/kernel-images/server/lib/chromiumflags"
 	"github.com/onkernel/kernel-images/server/lib/logger"
 	oapi "github.com/onkernel/kernel-images/server/lib/oapi"
 )
@@ -88,6 +89,21 @@ func (s *ApiService) PatchDisplay(ctx context.Context, req oapi.PatchDisplayRequ
 		restartChrome = *req.Body.RestartChromium
 	}
 
+	// App mode: Chromium's --app flag removes the tab bar and toolbar chrome,
+	// allowing the window to resize below the normal ~500px minimum width
+	// and ~200px minimum height.
+	// We automatically toggle this based on the requested viewport dimensions.
+	const appModeWidthThreshold = 500
+	const appModeHeightThreshold = 200
+	needsAppMode := width < appModeWidthThreshold || height < appModeHeightThreshold
+	if toggled, err := s.ensureAppMode(ctx, needsAppMode); err != nil {
+		log.Error("failed to toggle app mode", "error", err)
+		// Non-fatal: continue with the resize even if app mode toggle fails.
+	} else if toggled {
+		// App mode changed — force a chromium restart so it picks up the new flags.
+		restartChrome = true
+	}
+
 	// Route to appropriate resolution change handler
 	if displayMode == "xorg" {
 		if s.isNekoEnabled() {
@@ -390,3 +406,55 @@ func (s *ApiService) setResolutionViaNeko(ctx context.Context, width, height, re
 	log.Info("successfully changed resolution via Neko API", "width", width, "height", height, "refresh_rate", refreshRate)
 	return nil
 }
+
+// ensureAppMode adds or removes the --app flag from the Chromium runtime flags
+// file. When enabling, any existing --app flag is removed first so the URL is
+// always exactly appModeURL (defined in chromium.go). It returns (true, nil)
+// when the flag state was changed (meaning Chromium needs a restart), or
+// (false, nil) when no change was needed.
+func (s *ApiService) ensureAppMode(ctx context.Context, enable bool) (toggled bool, err error) {
+	log := logger.FromContext(ctx)
+	const appPrefix = "--app"
+	wantFlag := appPrefix + "=" + appModeURL
+
+	existing, err := chromiumflags.ReadOptionalFlagFile(chromiumFlagsPath)
+	if err != nil {
+		return false, fmt.Errorf("failed to read flags file: %w", err)
+	}
+
+	// Always strip any --app/--app=... flags so we can compare cleanly.
+	stripped := chromiumflags.RemoveFlagsByPrefix(existing, appPrefix)
+
+	if enable {
+		updated := append(stripped, wantFlag)
+		// If the exact flag was already present and nothing else changed, no-op.
+		if chromiumflags.HasFlagWithPrefix(existing, appPrefix) && len(updated) == len(existing) {
+			// Check the existing flag is the exact one we want.
+			for _, tok := range existing {
+				if tok == wantFlag {
+					log.Info("app mode already enabled with correct URL, no change needed")
+					return false, nil
+				}
+			}
+		}
+		log.Info("enabling app mode for small viewport", "flag", wantFlag)
+		if err := writeChromiumFlags(updated); err != nil {
+			return false, err
+		}
+		log.Info("app mode toggled", "enabled", true, "flags", updated)
+		return true, nil
+	}
+
+	// Disabling: if nothing was stripped, already disabled.
+	if len(stripped) == len(existing) {
+		log.Info("app mode already disabled, no change needed")
+		return false, nil
+	}
+
+	log.Info("disabling app mode for normal viewport")
+	if err := writeChromiumFlags(stripped); err != nil {
+		return false, err
+	}
+	log.Info("app mode toggled", "enabled", false, "flags", stripped)
+	return true, nil
+}

server/cmd/chromium-launcher/main.go

@@ -116,6 +116,7 @@ func main() {
 	}
 }
 
+
 // execLookPath helps satisfy syscall.Exec's requirement to pass an absolute path.
 func execLookPath(file string) (string, error) {
 	if strings.ContainsRune(file, os.PathSeparator) {

server/cmd/chromium-launcher/main_test.go

@@ -34,3 +34,4 @@ func TestExecLookPath(t *testing.T) {
 		t.Fatalf("execLookPath PATH search failed: p=%q err=%v", p, err)
 	}
 }
+

server/go.mod

@@ -101,4 +101,4 @@ require (
 	modernc.org/sqlite v1.23.1 // indirect
 )
 
-replace github.com/m1k1o/neko/server => github.com/onkernel/neko/server v0.0.0-20251008185748-46e2fc7d3866
+replace github.com/m1k1o/neko/server => github.com/onkernel/neko/server v0.0.0-20260213021128-abe9ac59a634

server/go.sum

@@ -133,8 +133,8 @@ github.com/oasdiff/yaml v0.0.0-20250309154309-f31be36b4037 h1:G7ERwszslrBzRxj//J
 github.com/oasdiff/yaml v0.0.0-20250309154309-f31be36b4037/go.mod h1:2bpvgLBZEtENV5scfDFEtB/5+1M4hkQhDQrccEJ/qGw=
 github.com/oasdiff/yaml3 v0.0.0-20250309153720-d2182401db90 h1:bQx3WeLcUWy+RletIKwUIt4x3t8n2SxavmoclizMb8c=
 github.com/oasdiff/yaml3 v0.0.0-20250309153720-d2182401db90/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o=
-github.com/onkernel/neko/server v0.0.0-20251008185748-46e2fc7d3866 h1:Cix/sgZLCsavpiTFxDLPbUOXob50IekCg5mgh+i4D4Q=
-github.com/onkernel/neko/server v0.0.0-20251008185748-46e2fc7d3866/go.mod h1:0+zactiySvtKwfe5JFjyNrSuQLA+EEPZl5bcfcZf1RM=
+github.com/onkernel/neko/server v0.0.0-20260213021128-abe9ac59a634 h1:Q8v6O/VRVLKcEHMSGC0ItDmLFShKLny/0bBggC/1jjk=
+github.com/onkernel/neko/server v0.0.0-20260213021128-abe9ac59a634/go.mod h1:0+zactiySvtKwfe5JFjyNrSuQLA+EEPZl5bcfcZf1RM=
 github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
 github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
 github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=

server/lib/chromiumflags/chromiumflags.go

@@ -224,6 +224,31 @@ func MergeExtensionPath(args []string, extPath string) []string {
 	return result
 }
 
+// RemoveFlagsByPrefix returns a new slice with any tokens that match the given
+// prefix removed. For example, prefix "--app" removes "--app", "--app=about:blank", etc.
+// It does NOT match longer flag names that merely share the prefix
+// (e.g. "--app" will not match "--application-name").
+func RemoveFlagsByPrefix(tokens []string, prefix string) []string {
+	out := make([]string, 0, len(tokens))
+	for _, tok := range tokens {
+		if tok == prefix || strings.HasPrefix(tok, prefix+"=") {
+			continue
+		}
+		out = append(out, tok)
+	}
+	return out
+}
+
+// HasFlagWithPrefix returns true if any token equals prefix or starts with prefix + "=".
+func HasFlagWithPrefix(tokens []string, prefix string) bool {
+	for _, tok := range tokens {
+		if tok == prefix || strings.HasPrefix(tok, prefix+"=") {
+			return true
+		}
+	}
+	return false
+}
+
 // WriteFlagFile writes the provided tokens to the given path as JSON in the
 // form: { "flags": ["--foo", "--bar=1"] } with file mode 0644.
 // The function creates or truncates the file.