chore: import upstream snapshot with attribution

tools/ui/scripts/dev.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+# Development script for llama-ui
+#
+# This script starts the llama-ui development servers (Storybook and Vite).
+# Note: You need to start llama-server separately.
+#
+# Usage:
+#   bash scripts/dev.sh
+#   npm run dev
+
+cd ../../
+
+# Ensure node_modules are installed
+if [ ! -d "tools/ui/node_modules" ]; then
+    echo "📦 Installing npm dependencies..."
+    cd tools/ui && npm install && cd ../../
+fi
+
+# Check and install git hooks if missing
+check_and_install_hooks() {
+    local hooks_missing=false
+
+    # Check for required hooks
+    if [ ! -f ".git/hooks/pre-commit" ] || [ ! -f ".git/hooks/pre-push" ]; then
+        hooks_missing=true
+    fi
+
+    if [ "$hooks_missing" = true ]; then
+        echo "🔧 Git hooks missing, installing them..."
+        if bash "$(dirname "$0")/git-hooks/install.sh"; then
+            echo "✅ Git hooks installed successfully"
+        else
+            echo "⚠️  Failed to install git hooks, continuing anyway..."
+        fi
+    else
+        echo "✅ Git hooks already installed"
+    fi
+}
+
+# Install git hooks if needed
+check_and_install_hooks
+
+# Cleanup function
+cleanup() {
+    echo "🧹 Cleaning up..."
+    exit
+}
+
+# Set up signal handlers
+trap cleanup SIGINT SIGTERM
+
+echo "🚀 Starting development servers..."
+echo "📝 Note: Make sure to start llama-server separately if needed"
+cd tools/ui
+# Use --insecure-http-parser to handle malformed HTTP responses from llama-server
+# (some responses have both Content-Length and Transfer-Encoding headers)
+storybook dev -p 6006 --ci & NODE_OPTIONS="--insecure-http-parser" vite dev --host 0.0.0.0 &
+
+# Wait for all background processes
+wait

tools/ui/scripts/favicon-colorize.ts

@@ -0,0 +1,107 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(HERE, '..');
+
+const DEFAULT_LOGO = resolve(PROJECT_ROOT, 'src/lib/assets/logo.svg');
+const DEFAULT_OUT_DIR = resolve(PROJECT_ROOT, 'static');
+const DEFAULT_OUT_LIGHT = resolve(DEFAULT_OUT_DIR, 'favicon.svg');
+const DEFAULT_OUT_DARK = resolve(DEFAULT_OUT_DIR, 'favicon-dark.svg');
+
+const CURRENT_COLOR = 'currentColor';
+
+export interface ColorizedFavicon {
+	light: string;
+	dark: string;
+}
+
+export interface WriteThemeFaviconsOptions {
+	sourcePath?: string;
+	lightOutPath?: string;
+	darkOutPath?: string;
+	/**
+	 * Fraction of the icon (0..1) to leave as an even margin on each side.
+	 * Applied by wrapping the inner content in a `<g transform="...">` so the
+	 * source `src/lib/assets/logo.svg` is not modified. Pass 0 to disable.
+	 */
+	padding?: number;
+}
+
+/**
+ * Replace every `currentColor` occurrence in the SVG with the given color.
+ * Pure: no filesystem access, so it is straightforward to unit-test.
+ */
+export function colorizeFaviconSvg(
+	svg: string,
+	lightColor: string,
+	darkColor: string
+): ColorizedFavicon {
+	return {
+		light: svg.replaceAll(CURRENT_COLOR, lightColor),
+		dark: svg.replaceAll(CURRENT_COLOR, darkColor)
+	};
+}
+
+/**
+ * Shrink the inner SVG content uniformly and re-center it so `padding` (a
+ * 0..1 fraction) is reserved as equal margin on each side. Returns the input
+ * unchanged for non-positive padding, missing/invalid `viewBox`, or unexpected
+ * markup so the caller always gets a renderable SVG.
+ */
+export function padFaviconSvg(svg: string, padding: number): string {
+	if (!(padding > 0) || padding >= 1) return svg;
+
+	const viewBoxMatch = svg.match(/viewBox\s*=\s*["']([^"']+)["']/i);
+	if (!viewBoxMatch) return svg;
+
+	const parts = viewBoxMatch[1]
+		.trim()
+		.split(/[\s,]+/)
+		.map(Number);
+	if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) return svg;
+
+	const [, , width, height] = parts;
+	if (width <= 0 || height <= 0) return svg;
+
+	const scale = 1 - padding;
+	const translateX = (padding * width) / 2;
+	const translateY = (padding * height) / 2;
+
+	const openTagStart = svg.search(/<svg\b/i);
+	if (openTagStart === -1) return svg;
+	const openTagEnd = svg.indexOf('>', openTagStart);
+	if (openTagEnd === -1) return svg;
+	const closeStart = svg.lastIndexOf('</svg');
+	if (closeStart === -1 || closeStart <= openTagEnd) return svg;
+
+	const openTag = svg.slice(0, openTagEnd + 1);
+	const inner = svg.slice(openTagEnd + 1, closeStart);
+	const closeTag = svg.slice(closeStart);
+
+	const group = `<g transform="translate(${translateX} ${translateY}) scale(${scale})">`;
+	return `${openTag}${group}${inner}</g>${closeTag}`;
+}
+
+/**
+ * Read `src/lib/assets/logo.svg`, colorize it for both themes, and write
+ * the results to the static directory so the PWA asset generator can consume
+ * them. Paths can be overridden for tests.
+ */
+export function writeThemeFavicons(
+	lightColor: string,
+	darkColor: string,
+	{
+		sourcePath = DEFAULT_LOGO,
+		lightOutPath = DEFAULT_OUT_LIGHT,
+		darkOutPath = DEFAULT_OUT_DARK,
+		padding = 0
+	}: WriteThemeFaviconsOptions = {}
+): void {
+	const source = readFileSync(sourcePath, 'utf-8');
+	const { light, dark } = colorizeFaviconSvg(source, lightColor, darkColor);
+	mkdirSync(dirname(lightOutPath), { recursive: true });
+	writeFileSync(lightOutPath, padFaviconSvg(light, padding));
+	writeFileSync(darkOutPath, padFaviconSvg(dark, padding));
+}

tools/ui/scripts/git-hooks/install.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# Install git hooks for llama-ui
+# Copies pre-commit and pre-push hooks into the repo's .git/hooks directory.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+HOOKS_DIR="$REPO_ROOT/$(cd "$REPO_ROOT" && git rev-parse --git-path hooks)"
+
+# Verify package.json exists
+if [ ! -f "$REPO_ROOT/tools/ui/package.json" ]; then
+    echo "❌ package.json not found in tools/ui"
+    exit 1
+fi
+
+echo "Installing git hooks for llama-ui..."
+
+for hook in pre-commit pre-push; do
+    src="$SCRIPT_DIR/${hook}.sh"
+    dst="$HOOKS_DIR/$hook"
+
+    if cp "$src" "$dst" && chmod +x "$dst"; then
+        echo "  ✅ $hook"
+    else
+        echo "  ❌ Failed to install $hook"
+        exit 1
+    fi
+done
+
+echo ""
+echo "Pre-commit:  format (staged) + type-check"
+echo "Pre-push:    lint + test"
+echo ""
+echo "Hooks stash unstaged changes temporarily and restore them after."
+echo "Skip with:  git commit --no-verify / git push --no-verify"

tools/ui/scripts/git-hooks/pre-commit.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+#
+# Pre-commit hook for llama-ui
+# Runs: format (staged files only) + type-check
+# Stashes unstaged changes temporarily and restores them after.
+
+# Only run when there are staged changes in tools/ui/
+if ! git diff --cached --name-only | grep -q "^tools/ui/"; then
+    exit 0
+fi
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+cd "$REPO_ROOT/tools/ui"
+
+# Check that node_modules exists
+if [ ! -d "node_modules" ]; then
+    echo "❌ node_modules not found. Run 'npm install' first."
+    exit 1
+fi
+
+# Stash unstaged changes in tools/ui/ so they don't interfere
+stash_name="pi-ui-precommit"
+git stash push --keep-index -u -m "$stash_name" -- tools/ui/ 2>/dev/null || true
+
+echo "Running pre-commit checks for llama-ui..."
+
+# Format only staged files
+staged_ui=$(git diff --cached --name-only -- tools/ui/)
+if [ -n "$staged_ui" ]; then
+    echo "$staged_ui" | xargs npm run format
+    format_ok=$?
+    # Re-stage formatted files
+    git add tools/ui/
+else
+    format_ok=0
+fi
+
+# Type-check the clean tree
+npm run check
+check_ok=$?
+
+# Restore stashed changes
+if git stash list | grep -q "$stash_name"; then
+    git stash pop 2>/dev/null || true
+fi
+
+if [ $format_ok -ne 0 ]; then
+    echo "❌ Format failed"
+    exit 1
+fi
+if [ $check_ok -ne 0 ]; then
+    echo "❌ Type check failed"
+    exit 1
+fi
+
+echo "✅ Pre-commit checks passed"
+exit 0

tools/ui/scripts/git-hooks/pre-push.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Pre-push hook for llama-ui
+# Runs: lint + test
+# Ignores unstaged changes (stashes them temporarily and restores after).
+
+needs_check=false
+
+# Read refs from stdin: local_ref local_sha remote_ref remote_sha
+while read local_ref local_sha remote_ref remote_sha; do
+    # New branch or force-push — always check
+    if [ "$local_sha" = "0000000000000000000000000000000000000000" ] || \
+       [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
+        needs_check=true
+        continue
+    fi
+
+    # Check for changes in tools/ui/ between remote and local
+    if git diff --name-only "$remote_sha...$local_sha" -- tools/ui/ | grep -q .; then
+        needs_check=true
+    fi
+done
+
+if [ "$needs_check" = false ]; then
+    exit 0
+fi
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+cd "$REPO_ROOT/tools/ui"
+
+# Check that node_modules exists
+if [ ! -d "node_modules" ]; then
+    echo "❌ node_modules not found. Run 'npm install' first."
+    exit 1
+fi
+
+# Stash unstaged changes so they don't interfere with checks
+stash_name="pi-ui-prepush"
+git stash push -u -m "$stash_name" -- tools/ui/ 2>/dev/null || true
+
+echo "Running pre-push checks for llama-ui..."
+
+# Lint
+npm run lint
+lint_ok=$?
+
+# Test
+npm test
+test_ok=$?
+
+# Restore stashed changes
+if git stash list | grep -q "$stash_name"; then
+    git stash pop 2>/dev/null || true
+fi
+
+if [ $lint_ok -ne 0 ]; then
+    echo "❌ Lint failed"
+    exit 1
+fi
+
+if [ $test_ok -ne 0 ]; then
+    echo "❌ Tests failed"
+    exit 1
+fi
+
+echo "✅ Pre-push checks passed"
+exit 0

tools/ui/scripts/make-icons-circular.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+/**
+ * Apply circular mask to pwa-*.png icons.
+ * Uses the maskable icon as source (white bg, full logo) to avoid
+ * the small-colormap pwa icons looking bad when cropped to a circle.
+ *
+ * Usage: node scripts/make-icons-circular.js [--padding-pct <0-50>] [--scale-pct <50-100>]
+ *
+ * - padding-pct: percentage of icon size kept as padding around the circle (default: 25)
+ * - scale-pct: scale down the source image before cropping (default: 85)
+ *
+ * maskable-icon and apple-touch-icon are left untouched.
+ */
+
+import sharp from 'sharp';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const STATIC_DIR = path.resolve(__dirname, '..', 'static');
+
+const paddingPct = process.argv.reduce((acc, arg, i, args) => {
+	if (arg === '--padding-pct' && args[i + 1]) return parseFloat(args[i + 1]);
+	return acc;
+}, 0);
+
+// Scale down the source image before cropping to circle
+const scalePct = process.argv.reduce((acc, arg, i, args) => {
+	if (arg === '--scale-pct' && args[i + 1]) return parseFloat(args[i + 1]);
+	return acc;
+}, 85); // default 85% - icon fills 85% of the circular area
+
+// Source for circular icons: the maskable icon (white bg, full logo)
+const sourceIcon = 'maskable-icon-512x512.png';
+const targetIcons = ['pwa-64x64.png', 'pwa-192x192.png', 'pwa-512x512.png'];
+
+// maskable-icon and apple-touch-icon stay square
+const untouchedIcons = ['maskable-icon-512x512.png', 'apple-touch-icon-180x180.png'];
+
+async function makeCircle(targetFilename) {
+	const targetPath = path.join(STATIC_DIR, targetFilename);
+	const sourcePath = path.join(STATIC_DIR, sourceIcon);
+
+	if (!fs.existsSync(sourcePath)) {
+		console.log(`⏭️  ${sourceIcon} not found, skipping`);
+		return;
+	}
+	if (!fs.existsSync(targetPath)) {
+		console.log(`⏭️  ${targetFilename} not found, skipping`);
+		return;
+	}
+
+	const metadata = await sharp(targetPath).metadata();
+	const size = Math.max(metadata.width, metadata.height);
+	const radius = Math.floor((size * (1 - paddingPct / 100)) / 2);
+	const center = Math.floor(size / 2);
+
+	// Build circular mask as RGBA buffer: white opaque circle on transparent bg
+	const maskBuf = Buffer.alloc(size * size * 4, 0);
+	for (let y = 0; y < size; y++) {
+		for (let x = 0; x < size; x++) {
+			const dx = x - center;
+			const dy = y - center;
+			const dist = Math.sqrt(dx * dx + dy * dy);
+			if (dist < radius) {
+				const i = (y * size + x) * 4;
+				maskBuf[i] = 255;
+				maskBuf[i + 1] = 255;
+				maskBuf[i + 2] = 255;
+				maskBuf[i + 3] = 255;
+			}
+		}
+	}
+
+	const tmpMask = path.join(STATIC_DIR, '.mask-tmp.png');
+	await sharp(maskBuf, {
+		raw: { width: size, height: size, channels: 4 }
+	})
+		.png()
+		.toFile(tmpMask);
+
+	// Step 1: Scale source relative to circle diameter (not full icon), composite centered onto white canvas of full size
+	const circleDiameter = Math.floor(size * (1 - paddingPct / 100));
+	const scaledSize = Math.floor((circleDiameter * scalePct) / 100);
+	const offset = Math.floor((size - scaledSize) / 2);
+
+	const scaledBuf = await sharp(sourcePath)
+		.resize(scaledSize, scaledSize, {
+			fit: 'cover',
+			background: { r: 255, g: 255, b: 255, alpha: 1 }
+		})
+		.ensureAlpha()
+		.png()
+		.toBuffer();
+
+	// Step 2: Composite scaled image onto white background, then apply circular mask
+	const output = await sharp({
+		create: {
+			width: size,
+			height: size,
+			channels: 4,
+			background: { r: 255, g: 255, b: 255, alpha: 1 }
+		}
+	})
+		.composite([
+			{ input: scaledBuf, top: offset, left: offset },
+			{ input: tmpMask, top: 0, left: 0, blend: 'dest-in' }
+		])
+		.png()
+		.toBuffer();
+
+	fs.writeFileSync(targetPath, output);
+	fs.unlinkSync(tmpMask);
+
+	console.log(
+		`✓ ${targetFilename} → circle from ${sourceIcon}, ${paddingPct}% padding (size=${size}, r=${radius}, scale=${scalePct}%, circleDiameter=${circleDiameter})`
+	);
+}
+
+async function main() {
+	console.log(`Circular mask: ${paddingPct}% padding, ${scalePct}% scale, source=${sourceIcon}\n`);
+	for (const icon of targetIcons) {
+		await makeCircle(icon);
+	}
+
+	console.log('\nUnchanged:');
+	for (const icon of untouchedIcons) {
+		const fp = path.join(STATIC_DIR, icon);
+		console.log(`  ${icon} (${fs.existsSync(fp) ? fs.statSync(fp).size + ' bytes' : 'missing'})`);
+	}
+}
+
+main();

tools/ui/scripts/vite-plugin-build-info.ts

@@ -0,0 +1,41 @@
+import { writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'path';
+import type { Plugin } from 'vite';
+import { BUILD_CONFIG } from '../src/lib/constants/pwa';
+
+let processed = false;
+
+const OUTPUT_DIR = process.env.LLAMA_UI_OUT_DIR ?? BUILD_CONFIG.OUTPUT_DIR;
+
+/**
+ * Write build.json with the llama.cpp release build number.
+ *
+ * LLAMA_BUILD_NUMBER is passed from CMake -> npm -> vite via env var.
+ * Used for display of the current llama-server release (e.g. "b1234").
+ */
+export function buildInfoPlugin(): Plugin {
+	return {
+		name: 'llamacpp:build-info',
+		apply: 'build',
+		closeBundle() {
+			setTimeout(() => {
+				try {
+					if (processed) return;
+					processed = true;
+
+					const buildNumber = process.env.LLAMA_BUILD_NUMBER || 'b0000';
+
+					const outDir = resolve(OUTPUT_DIR);
+					const indexPath = resolve(outDir, 'index.html');
+					if (!existsSync(indexPath)) return;
+
+					const buildJsonPath = resolve(outDir, 'build.json');
+					writeFileSync(buildJsonPath, JSON.stringify({ version: buildNumber }), 'utf-8');
+					console.log(`Created build.json (version: ${buildNumber})`);
+				} catch (error) {
+					console.error('Failed to write build.json:', error);
+				}
+			}, 100);
+		}
+	};
+}

tools/ui/scripts/vite-plugin-relativize-base.ts

@@ -0,0 +1,61 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'path';
+import type { Plugin } from 'vite';
+import { BUILD_CONFIG } from '../src/lib/constants/pwa';
+
+let processed = false;
+
+const OUTPUT_DIR = process.env.LLAMA_UI_OUT_DIR ?? BUILD_CONFIG.OUTPUT_DIR;
+
+function rewrite(path: string, pairs: [string, string][]): void {
+	if (!existsSync(path)) {
+		return;
+	}
+	const text = readFileSync(path, 'utf-8');
+	let out = text;
+	for (const [from, to] of pairs) {
+		out = out.split(from).join(to);
+	}
+	if (out !== text) {
+		writeFileSync(path, out, 'utf-8');
+	}
+}
+
+/**
+ * Relativize SvelteKit absolute base refs so the build is relocatable under any subpath.
+ *
+ * SvelteKit bakes root absolute /_app/ paths into the SPA fallback because paths.relative
+ * does not apply to a depth agnostic fallback page. Rewriting to ./_app/ lets a plain
+ * recursive copy of the output into /any/subdir/ resolve assets against the document URL.
+ * Runs after adapter-static writes index.html and the PWA plugin writes sw.js, deferred the
+ * same way as buildInfoPlugin so the emitted files exist.
+ */
+export function relativizeBasePlugin(): Plugin {
+	return {
+		name: 'llamacpp:relativize-base',
+		apply: 'build',
+		closeBundle() {
+			setTimeout(() => {
+				try {
+					if (processed) return;
+					processed = true;
+
+					const outDir = resolve(OUTPUT_DIR);
+
+					// index.html: modulepreload, stylesheet and bootstrap import reference "/_app/
+					rewrite(resolve(outDir, 'index.html'), [['"/_app/', '"./_app/']]);
+
+					// sw.js: the only absolute entries are the navigate fallback precache key and handler
+					rewrite(resolve(outDir, 'sw.js'), [
+						['{url:"/"', '{url:"./"'],
+						['createHandlerBoundToURL("/"', 'createHandlerBoundToURL("./"']
+					]);
+
+					console.log('Relativized base refs in index.html and sw.js');
+				} catch (error) {
+					console.error('Failed to relativize base refs:', error);
+				}
+			}, 100);
+		}
+	};
+}

tools/ui/scripts/vite-plugin-splash-screen.ts

@@ -0,0 +1,115 @@
+import { readdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'path';
+import type { Plugin } from 'vite';
+import { TAB, NEWLINE } from '../src/lib/constants/code';
+import { APPLE_DEVICES, BUILD_CONFIG, REGEX_PATTERNS, SPLASH_LINK } from '../src/lib/constants/pwa';
+import type { SplashDimensions } from '../src/lib/types';
+import { SplashOrientation } from '../src/lib/enums/splash.enums';
+
+let processed = false;
+
+const OUTPUT_DIR = process.env.LLAMA_UI_OUT_DIR ?? BUILD_CONFIG.OUTPUT_DIR;
+
+/**
+ * Generate iOS splash screen <link> tags from generated apple-splash-*.png files.
+ * Returns an array of HTML link strings to be injected into the page head.
+ */
+export function generateSplashScreenLinks(outDir: string): string[] {
+	const files = readdirSync(outDir).filter((f) => f.match(REGEX_PATTERNS.SPLASH_FILE));
+	if (files.length === 0) return [];
+
+	const dimMap = new Map<string, SplashDimensions>();
+	for (const [dims, spec] of Object.entries(APPLE_DEVICES)) {
+		const [w, h] = dims.split('x').map(Number);
+		// logical-point dimensions
+		dimMap.set(`${w}x${h}`, { deviceW: spec.width, deviceH: spec.height, dpr: spec.dpr });
+		dimMap.set(`${h}x${w}`, { deviceW: spec.width, deviceH: spec.height, dpr: spec.dpr });
+		// pixel dimensions (used by actual generated splash files)
+		dimMap.set(`${w * spec.dpr}x${h * spec.dpr}`, {
+			deviceW: spec.width,
+			deviceH: spec.height,
+			dpr: spec.dpr
+		});
+		dimMap.set(`${h * spec.dpr}x${w * spec.dpr}`, {
+			deviceW: spec.width,
+			deviceH: spec.height,
+			dpr: spec.dpr
+		});
+	}
+
+	const lightLinks: string[] = [];
+	const darkLinks: string[] = [];
+
+	for (const file of files) {
+		const match = file.match(REGEX_PATTERNS.SPLASH_FILE);
+		if (!match) continue;
+		const orientation = match[1] as SplashOrientation;
+		const isDark = !!match[2];
+		const pixelW = parseInt(match[3]);
+		const pixelH = parseInt(match[4]);
+
+		const key = `${pixelW}x${pixelH}`;
+		const spec = dimMap.get(key);
+		if (!spec) {
+			console.warn(`Unknown splash screen dimensions: ${key} (${file})`);
+			continue;
+		}
+
+		const { deviceW, deviceH, dpr } = spec;
+		const media = `screen and (device-width: ${deviceW}px) and (device-height: ${deviceH}px) and (-webkit-device-pixel-ratio: ${dpr}) and (orientation: ${orientation})`;
+		const href = `./${file}`;
+
+		if (isDark) {
+			darkLinks.push(
+				`${SPLASH_LINK.HTML} media="${media}${SPLASH_LINK.DARK_MEDIA_SUFFIX}" href="${href}">`
+			);
+		} else {
+			lightLinks.push(`${SPLASH_LINK.HTML} media="${media}" href="${href}">`);
+		}
+	}
+
+	return [...lightLinks, ...darkLinks];
+}
+
+export function splashScreenPlugin(): Plugin {
+	return {
+		name: 'llamacpp:splash-screen',
+		apply: 'build',
+		closeBundle() {
+			setTimeout(() => {
+				try {
+					if (processed) return;
+					processed = true;
+
+					const outDir = resolve(OUTPUT_DIR);
+					const indexPath = resolve(outDir, 'index.html');
+					if (!existsSync(indexPath)) return;
+
+					let content = readFileSync(indexPath, 'utf-8');
+
+					// Inject iOS splash screen <link> tags into <head>.
+					// The @vite-pwa/assets-generator generates apple-splash-*.png files;
+					// this scans them and creates the <link> tags SvelteKit needs.
+					const splashLinks = generateSplashScreenLinks(outDir);
+					if (splashLinks.length > 0) {
+						console.log(`Generated ${splashLinks.length} apple-splash link tags`);
+						const splashHtml = splashLinks.map((l) => TAB + TAB + l).join(NEWLINE);
+						content = content.replace(
+							REGEX_PATTERNS.HEAD_CLOSE,
+							splashHtml + NEWLINE + TAB + TAB + '</head>'
+						);
+					}
+
+					// Remove trailing \r from Windows line endings
+					content = content.replace(/\r/g, '');
+					content = BUILD_CONFIG.GUIDE_COMMENT + NEWLINE + content;
+
+					writeFileSync(indexPath, content, 'utf-8');
+					console.log('Updated index.html');
+				} catch (error) {
+					console.error('Failed to process build output:', error);
+				}
+			}, 100);
+		}
+	};
+}