Манифест и установка на экран

Манифест — обычный JSON-файл на сервере рядом с доской. Код страницы его не читает и ничего с ним не делает: страница только сообщает браузеру адрес, одной строкой в <head> — <link rel="manifest" href="/manifest.webmanifest">. Расширение .webmanifest зарегистрировано именно для таких файлов, тип ответа у него — application/manifest+json. Сработает и .json, но так по имени сразу видно, что это за файл.

Вот манифест доски. Он лежит в той же папке board, которую мы разложили в первой статье главы, а рядом появилась папка с тремя иконками:

$ cat board/manifest.webmanifest

$ ls -1 board/icons

Откроем доску в чистом профиле и посмотрим журнал сервера. Сервер тот же, свой статический, что и в статье про стратегии кеша; порт другой, чтобы регистрации воркера не смешивались с прошлыми опытами.

$ node serve.mjs m1 3341

manifest.webmanifest браузер попросил сам, сразу за данными, и тут же скачал одну иконку, icon-192.png. Ни одной строки кода ради этого страница не выполняла. Иконка нужна для проверки установки: ниже увидим, что без подходящей иконки приложение не поставить. Манифеста нет и в оболочке воркера — и не нужно: браузер читает его при установке, а в этот момент сеть заведомо есть.

Заставку при запуске на Android Chrome собирает сам — из name, background_color и иконки; отдельной картинки для неё в манифесте нет, а theme_color красит панель над приложением. Если режим display браузеру не по силам, он спускается по цепочке fullscreen → standalone → minimal-ui → browser до первого режима, который умеет.

Иконки — самое капризное место. У каждой есть purpose. Обычная, any (так считается и без поля), рисуется как есть — с прозрачностью и без полей, как значок сайта. maskable — иконка, которую система обрежет своей маской: кругом, скруглённым квадратом, каплей. Всё важное на ней должно помещаться в круг радиусом 40% ширины с центром посередине, а внешние 10% по краю могут срезать. Отсюда правило: две разные картинки, а не одна на всё. Запись "purpose": "any maskable" web.dev прямо не советует: там, где иконка пойдёт как обычная, она выйдет с лишними полями и мельче, чем нужно.

Иконка maskable — не «иконка получше», а иконка с запасом полей под чужую маску. Обычную она не заменяет, а дополняет.

Как Chrome понял этот файл, показывает DevTools: панель Application, раздел Manifest, а в нём блок Installability — что мешает установке. Те же ответы можно получить у Chrome через протокол DevTools; мой сценарий так и делает, чтобы вывод можно было положить сюда текстом:

$ node check-manifest.mjs http://127.0.0.1:3341/

Все адреса стали полными, цвета — числами, а display записан внутренним именем Chrome, kStandalone. Главная строка — последняя: установке ничего не мешает. Service worker в этом решении не участвует. В критериях Chrome его больше нет, и манифест на странице без воркера проходит так же — это стенд тоже показал. Воркер нужен доске не для установки, а чтобы поставленное приложение открывалось без сети.

Забегая вперёд, к Next.js в четвёртой части: там манифест можно не писать руками, а вернуть объектом из файла app/manifest.ts, и Next.js сам отдаст его по адресу — тем же приёмом, каким в той части собирают карту сайта из app/sitemap.ts. Поля те же, и правила, о которых дальше пойдёт речь, от этого не меняются.

Адреса в манифесте можно писать относительными — "./", "index.html", "../". Вопрос в том, от чего их отсчитывать. Кандидатов три: адрес страницы, на которой нашли манифест, адрес самого манифеста и корень сайта. Сначала посчитаем, что даёт каждый. Прогноз тут не так прост, как кажется: у new URL с базой свои правила, мы встречали их в первой статье главы.

const page = "https://board.example/tasks/17";
const manifest = "https://board.example/static/manifest.webmanifest";

console.log("от адреса страницы:", new URL("./", page).href);
console.log("от адреса манифеста:", new URL("./", manifest).href);
console.log("от корня сайта:", new URL("./", "https://board.example/").href);
console.log("../ от адреса манифеста:", new URL("../", manifest).href);

Первая строка — ловушка сама по себе: от /tasks/17 адрес ./ ведёт в /tasks/, потому что последний сегмент без слэша считается именем файла и отбрасывается. А теперь главное: какую из этих баз возьмёт браузер? На стенде манифест с "start_url": "./" и "scope": "./" лежит в папке static, а ссылка на него стоит на странице /exp/relative.html:

$ node check-manifest.mjs http://127.0.0.1:3341/exp/relative.html

$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3341/static/

Chrome отсчитал от манифеста: и start_url, и scope стали /static/. Так записано в спецификации манифеста, и причина понятна: один манифест подключают десятки страниц сайта, и приложение не должно зависеть от того, на какой из них его нашли. Посмотрите и на строку «мешает установке: нет». Chrome готов поставить приложение, которое при запуске откроет /static/, а там у сервера 404. Проверки на это в критериях нет.

Относительные адреса в манифесте отсчитываются от адреса манифеста. Надёжнее всего писать их от корня — "/", "/app/": такой адрес не зависит ни от страницы, ни от папки, куда положили файл.

Второе, что нужно знать про эти поля: из-за одного неудачного значения браузер не отвергает манифест целиком. Он отбрасывает поле и берёт значение по умолчанию. Правила короткие, соберём их функцией. По умолчанию start_url — адрес страницы, а scope — папка start_url. start_url с чужого происхождения отбрасывается; scope, внутри которого не оказался start_url, — тоже. «Внутри» здесь — то же совпадение префикса, что и у области действия воркера. Предскажите четыре блока вывода.

function parse(value, base) {
  try {
    return new URL(value, base);
  } catch (error) {
    return null;
  }
}

function within(url, scope) {
  const target = new URL(url);
  const area = new URL(scope);
  return target.origin === area.origin && target.pathname.startsWith(area.pathname);
}

function resolveManifest(json, manifestUrl, documentUrl) {
  const notes = [];

  let startUrl = documentUrl;
  if (typeof json.start_url === "string" && json.start_url !== "") {
    const start = parse(json.start_url, manifestUrl);
    if (start && start.origin === new URL(documentUrl).origin) startUrl = start.href;
    else notes.push("start_url отброшен: чужое происхождение");
  }

  let scope = new URL(".", startUrl).href;
  if (typeof json.scope === "string" && json.scope !== "") {
    const area = parse(json.scope, manifestUrl);
    if (area) {
      area.search = "";
      area.hash = "";
      if (within(startUrl, area.href)) scope = area.href;
      else notes.push("scope отброшен: start_url вне его");
    }
  }

  return { startUrl, scope, notes };
}

const MANIFEST = "https://board.example/manifest.webmanifest";

function show(label, json, documentUrl) {
  const { startUrl, scope, notes } = resolveManifest(json, MANIFEST, documentUrl);
  console.log(label);
  console.log("  start_url:", startUrl);
  console.log("  scope:", scope);
  for (const note of notes) console.log("  !", note);
}

show("доска", { start_url: "/", scope: "/" }, "https://board.example/");
show("scope уже, чем start_url", { start_url: "/", scope: "/app/" }, "https://board.example/app/");
show("start_url на чужом сайте", { start_url: "https://other.example/" }, "https://board.example/help/faq.html");
show("scope не указан", { start_url: "/app/board.html" }, "https://board.example/app/board.html");

Во втором блоке scope /app/ не накрывает start_url / — и отброшен именно scope, а не весь манифест: область стала папкой start_url, то есть всем сайтом. В третьем отброшен start_url, и приложение будет запускаться с той страницы, где его поставили, — здесь это /help/faq.html, а область — её папка. Проверим те же два случая на живом Chrome:

$ node check-manifest.mjs http://127.0.0.1:3341/exp/outside.html http://127.0.0.1:3341/exp/foreign.html

Предупреждения Chrome — те же правила его словами, и оба говорят, что поле проигнорировано, а не что манифест сломан. Но в последней строке есть расхождение, и оно полезное. По спецификации манифест с отброшенным start_url остаётся годным, а у Chrome к установке своё требование: start_url должен быть задан и принят. Поэтому манифест, где scope не накрывает start_url, ставится, хотя область получилась не та, что задумана, а манифест с start_url на чужом сайте — нет: start-url-not-valid.

Совет «start_url вне scope ломает установку» неверен. Ломается не установка, а замысел: область молча становится шире, чем вы её написали.

Решение «можно ставить» у каждого браузера своё, и лучше всех описано решение Chrome — на web.dev. Сайт должен открываться по HTTPS (localhost, как и для воркера, считается безопасным, а HTTPS на своём сервере настроим в части VI). Приложение не должно быть уже установлено. Человек должен хотя бы раз нажать на странице и провести на ней не меньше 30 секунд — это эвристика вовлечённости, и считается она за всё время, а не за одно посещение. А в манифесте должны быть name или short_name, start_url, иконки 192 и 512 пикселей, display — одно из fullscreen, standalone, minimal-ui или window-controls-overlay, и не должно быть "prefer_related_applications": true — так манифест говорит «ставьте лучше приложение из магазина».

Соберём проверку функцией. Разбор адресов из прошлого раздела уже лежит на странице примера. Ошибки назовём так же, как их называет сам Chrome, чтобы сверка шла буква в букву, а то, что установке не мешает, но портит вид, пусть идёт советом. Одна оговорка до запуска: правила в функции взяты не из абзаца выше, а из опытов над Chrome 152, и где они с абзацем расходятся, станет видно по выводу. Предскажите, какие из пяти манифестов пройдут.

const DISPLAY = ["fullscreen", "standalone", "minimal-ui"];

function isSecure(url) {
  const { protocol, hostname } = new URL(url);
  return protocol === "https:" || hostname === "localhost" || hostname === "127.0.0.1";
}

const purposes = (icon) => (icon.purpose || "any").split(" ");
const sides = (icon) => (icon.sizes || "").split(" ").map((size) => parseInt(size, 10) || 0);

function checkInstall(json, manifestUrl, documentUrl) {
  const errors = [];
  const advice = [];
  const { notes } = resolveManifest(json, manifestUrl, documentUrl);

  if (!isSecure(documentUrl)) errors.push("not-from-secure-origin");
  if (!json.name && !json.short_name) errors.push("manifest-missing-name-or-short-name");
  const startDropped = notes.some((note) => note.startsWith("start_url"));
  if (typeof json.start_url !== "string" || json.start_url === "" || startDropped) errors.push("start-url-not-valid");

  // display_override браузер читает раньше display, поэтому годится любое из двух
  const modes = [...(json.display_override || []), json.display];
  if (!modes.some((mode) => DISPLAY.includes(mode))) errors.push("manifest-display-not-supported");

  const icons = json.icons || [];
  const ordinary = icons.filter((icon) => purposes(icon).includes("any"));
  if (!ordinary.some((icon) => Math.max(...sides(icon)) >= 144)) errors.push("manifest-missing-suitable-icon");

  // установке это не мешает, но иконка окажется там, где её растянут или обрежут
  for (const side of [192, 512]) {
    if (!ordinary.some((icon) => sides(icon).includes(side))) advice.push("нет обычной иконки " + side + "×" + side);
  }
  if (icons.some((icon) => purposes(icon).length > 1)) advice.push("purpose из двух слов: иконка any получит лишние поля");
  if (!icons.some((icon) => purposes(icon).includes("maskable"))) advice.push("нет иконки maskable: на Android прозрачная иконка встанет в белый круг");

  return { errors, advice };
}

const icon192 = { src: "/icons/icon-192.png", sizes: "192x192" };
const icon512 = { src: "/icons/icon-512.png", sizes: "512x512" };
const maskable = { src: "/icons/icon-maskable-512.png", sizes: "512x512", purpose: "maskable" };
const board = { name: "Доска задач", start_url: "/", scope: "/", display: "standalone", icons: [icon192, icon512, maskable] };

const cases = [
  ["доска", board, "https://board.example/"],
  ["доска по http", board, "http://board.example/"],
  ["только maskable", { ...board, icons: [{ ...icon192, purpose: "maskable" }, maskable] }, "https://board.example/"],
  ["без иконки 512", { ...board, icons: [icon192, maskable] }, "https://board.example/"],
  ["display: window-controls-overlay", { ...board, display: "window-controls-overlay" }, "https://board.example/"]
];

for (const [label, json, page] of cases) {
  const { errors, advice } = checkInstall(json, new URL("/manifest.webmanifest", page).href, page);
  console.log(label + ":", errors.length > 0 ? errors.join(", ") : "установке ничего не мешает");
  for (const line of advice) console.log("   совет:", line);
}

Три манифеста из пяти не ставятся, и у двух причина неожиданная. «Только maskable» не проходит, хотя иконок две и обе нужного размера: иконки под чужую маску Chrome за обычные не считает, а без обычной показать приложение ему нечем. «Без иконки 512» проходит, хотя web.dev требует 512: сам Chrome проверяет только, что есть обычная иконка от 144 пикселей. А window-controls-overlay из списка web.dev в поле display не годится вовсе. Это значение для display_override — поля, где режимы окна перечисляют по убыванию желания и откуда браузер берёт первый, который умеет.

Откуда такие правила — вот прогон Chrome по десяти страницам. У каждой свой манифест:

$ node check-manifest.mjs --short http://127.0.0.1:3341/ http://board.test:3341/ http://127.0.0.1:3341/exp/noname.html http://127.0.0.1:3341/exp/nostart.html http://127.0.0.1:3341/exp/browser.html http://127.0.0.1:3341/exp/wco.html http://127.0.0.1:3341/exp/override.html http://127.0.0.1:3341/exp/maskonly.html http://127.0.0.1:3341/exp/anymask.html http://127.0.0.1:3341/exp/no512.html

На общих случаях модель и Chrome совпадают, и видно ещё три вещи. Первая: not-from-secure-origin у board.test — страница та же, сервер тот же, отличается только имя в адресе. На такой странице нет и воркера: navigator.serviceWorker там undefined, и строка регистрации в app.js на стенде упала с TypeError. Вторая: display_override проходит даже при "display": "browser", потому что браузер читает его первым. Третья: any maskable Chrome ставит, так что совет web.dev — про внешний вид, а не про установку. Для window-controls-overlay в подробном выводе Chrome пишет ещё и предупреждение «inapplicable 'display' value ignored.»: значение в этом поле он просто выбросил.

Часть критериев стенд не проверил. Главный из них — вовлечённость: в Chrome без окна событие установки beforeinstallprompt (о нём ниже) приходило сразу после загрузки, без нажатий и тридцати секунд, поэтому по такому стенду нельзя судить, как эвристика поведёт себя у вас. "prefer_related_applications": true Chrome 152 на компьютере установке не помешал, а на Android я его не проверял. И «приложение ещё не установлено» тоже осталось без проверки: поставить приложение в Chrome без окна стенд не может.

Проверку установки пишут по поведению браузера, а документацию используют как список того, что проверить. На стенде они разошлись в трёх местах: размер иконки, window-controls-overlay и prefer_related_applications.

Критерии выше — про Chrome и браузеры на его движке. Остальные ставят приложения по-своему, и разница не в мелочах: где-то сайт предлагает установку сам, где-то человек ищет пункт в меню, а где-то манифест вообще не обязателен. Первое различие видно прямо из песочницы. Предскажите три строки — и учтите, что ответ зависит от браузера, в котором вы читаете эту страницу.

console.log("beforeinstallprompt:", "onbeforeinstallprompt" in window);
console.log("appinstalled:", "onappinstalled" in window);
console.log("SyncManager:", "SyncManager" in window);

В Chrome все три строки — true, в Firefox все три — false; по данным MDN о поддержке, Edge отвечает как Chrome, а Safari — как Firefox. События beforeinstallprompt и appinstalled нестандартные и есть только в Chromium — как и фоновая синхронизация из статьи «Без сети». Откройте эту страницу в другом браузере и запустите пример ещё раз: так быстрее всего убедиться, что кнопка «Установить» на сайте бывает не у всех.

Самая большая перемена последнего года — в iOS 26 и iPadOS 26. Раньше сайт без манифеста (и без старого мета-тега Apple) открывался с экрана Домой как закладка — в Safari. Теперь в окне добавления на экран есть переключатель «открыть как веб-приложение», и включён он по умолчанию: своим окном открывается любой сайт. Манифест при этом не теряет смысла — если он есть, iOS берёт из него иконки и остальные поля. Но узнать, что его поставили, сайт на iPhone не может: ни beforeinstallprompt, ни appinstalled там нет.

Про push в этой таблице — только где он есть. Как устроена подписка и почему на iPhone без экрана Домой её не бывает, разберём в следующей статье. А выбирать по таблице между установкой из браузера и выпуском в магазин будем в пятой части, в статье «PWA или приложение из магазина»: здесь механизмы, там решение.

Свою кнопку «Установить» сайт может показать только в Chromium. Везде остальное — подсказка словами или ничего, и это нормальный ответ, а не недоработка.

Там, где событие есть, схема такая. Браузер решил, что сайт годится к установке, и прислал beforeinstallprompt. Сайт отменяет собственное предложение браузера через preventDefault(), прячет событие в переменную и показывает свою кнопку. По нажатию он зовёт у события prompt(), и браузер открывает своё окно установки; ответ человека приходит в userChoice — "accepted" или "dismissed". Вызвать prompt() у одного события можно один раз: после отказа придётся ждать, пока браузер пришлёт новое. Когда приложение уже установлено (на компьютере или как WebAPK на Android), событие больше не приходит. Вот app.js доски целиком:

navigator.serviceWorker.register("/sw.js");

const standalone = window.matchMedia("(display-mode: standalone)");
console.log("display-mode standalone:", standalone.matches);

let deferredPrompt = null;

window.addEventListener("beforeinstallprompt", (event) => {
  event.preventDefault();
  deferredPrompt = event;
  console.log("beforeinstallprompt: платформы", JSON.stringify(event.platforms));
  document.querySelector("#install").hidden = false;
});

document.querySelector("#install").addEventListener("click", async () => {
  if (!deferredPrompt) return;
  const event = deferredPrompt;
  deferredPrompt = null;
  document.querySelector("#install").hidden = true;
  await event.prompt();
  const choice = await event.userChoice;
  console.log("выбор человека:", choice.outcome);
});

window.addEventListener("appinstalled", () => {
  console.log("appinstalled: доска установлена");
});

async function show() {
  const response = await fetch("/api/tasks.json");
  const data = await response.json();
  const board = document.querySelector("#board");
  for (const text of data.tasks) {
    const li = document.createElement("li");
    li.textContent = text;
    board.append(li);
  }
  console.log("controller:", navigator.serviceWorker.controller ? "есть" : "нет");
  console.log("задач на экране:", data.tasks.length);
}

show();

Событие пришло, поле platforms у него — ["web"]: ставится веб-приложение. Кнопка появилась. Нажмём её и посмотрим в журнал сервера:

$ node serve.mjs m1 3341

Окно установки, судя по журналу, скачало все три иконки. Самого окна в Chrome без экрана не видно, и ответить в нём некому, поэтому до userChoice этот стенд не дошёл. Зато он показал, чего делать нельзя. Соблазнительно не возиться с кнопкой и позвать prompt() прямо в обработчике события:

window.addEventListener("beforeinstallprompt", async (event) => {
  event.preventDefault();
  console.log("beforeinstallprompt пришло");
  try {
    await event.prompt();
  } catch (error) {
    console.log("prompt() не сработал:", error.name + ":", error.message);
  }
});

NotAllowedError: окно установки открывается только в ответ на действие человека — нажатие или касание. Та же защита стоит у всплывающих окон: сайт не может навязать установку, пока человек на него только смотрит.

Вторая половина кнопки — знать, когда её не показывать: если доску уже запустили с экрана, предлагать установку глупо. Открыто ли приложение своим окном, говорит медиазапрос display-mode. Это тот же matchMedia, что в статье про вычисленные стили, только спрашивает он не про ширину, а про режим окна. Песочница — обычная вкладка; предскажите четыре строки.

for (const mode of ["fullscreen", "standalone", "minimal-ui", "browser"]) {
  console.log(mode + ":", window.matchMedia("(display-mode: " + mode + ")").matches);
}

Во вкладке верно только browser. В окне установленной доски true ответит запрос с её режимом — у нас standalone. Но у этой проверки две ловушки. Первая — в самом Chrome: видео или игра на весь экран через Fullscreen API тоже включают display-mode: fullscreen. На стенде после document.documentElement.requestFullscreen() запрос fullscreen стал true, а browser — false. Вторая — в Safari на iPhone: по данным MDN о поддержке и открытому с 2023 года отчёту WebKit 264218, приложение с "display": "standalone", запущенное с экрана Домой, отвечает true на fullscreen и false на standalone. На iPhone с iOS 26 я это не проверял, поэтому проверку пишут с запасом на оба случая.

Соберём решение «что показать» функцией. Предскажите семь строк, особенно третью и пятую.

function launchedAsApp(matches, fullscreenElement) {
  if (matches("(display-mode: standalone)") || matches("(display-mode: minimal-ui)")) return true;
  // видео на весь экран тоже включает fullscreen, а запуском с экрана не является
  return matches("(display-mode: fullscreen)") && !fullscreenElement;
}

function installUi({ promptEvent, appleMobile, matches, fullscreenElement }) {
  if (launchedAsApp(matches, fullscreenElement)) return "ничего: доска уже открыта как приложение";
  if (promptEvent) return "кнопка «Установить доску»";
  if (appleMobile) return "подсказка «Поделиться → На экран Домой»";
  return "ничего: своей кнопки здесь не сделать";
}

const only = (mode) => (query) => query === "(display-mode: " + mode + ")";

const situations = [
  ["Chrome, вкладка", { promptEvent: {}, appleMobile: false, matches: only("browser"), fullscreenElement: null }],
  ["Chrome, окно установленной доски", { promptEvent: null, appleMobile: false, matches: only("standalone"), fullscreenElement: null }],
  ["Chrome, вкладка с видео на весь экран", { promptEvent: {}, appleMobile: false, matches: only("fullscreen"), fullscreenElement: {} }],
  ["Safari на iPhone, вкладка", { promptEvent: null, appleMobile: true, matches: only("browser"), fullscreenElement: null }],
  ["iPhone, запуск с экрана Домой", { promptEvent: null, appleMobile: true, matches: only("fullscreen"), fullscreenElement: null }],
  ["Firefox в Windows, вкладка", { promptEvent: null, appleMobile: false, matches: only("browser"), fullscreenElement: null }]
];

for (const [label, state] of situations) {
  console.log(label + " →", installUi(state));
}

console.log("эта песочница →", installUi({
  promptEvent: null,
  appleMobile: false,
  matches: (query) => window.matchMedia(query).matches,
  fullscreenElement: document.fullscreenElement
}));

Третья строка — Chrome с видео на весь экран: fullscreen там верен, но есть и fullscreenElement, значит, это не запуск с экрана, и кнопка остаётся. Пятая — iPhone с экрана Домой: standalone молчит, зато fullscreen без полноэкранного элемента выдаёт приложение. Как узнать, что перед вами iPhone, модель не решает, это флаг. В настоящем коде это обычно navigator.userAgent, и способ ненадёжный: iPad по умолчанию представляется компьютером Mac. Поэтому подсказку «Поделиться → На экран Домой» делают ненавязчивой и с кнопкой «закрыть».

«Открыто как приложение» — это не один медиазапрос, а standalone, minimal-ui или fullscreen без полноэкранного элемента. Проверка меньшего ломается на iPhone или на первом же видео.

Последняя ловушка стоит на стыке манифеста и воркера. Хочется знать, сколько людей открывают доску с иконки, а не из вкладки, и в start_url дописывают метку: "/?source=homescreen". Сервер увидит её в журнале, аналитика — в адресе, а id у доски задан явно, так что для браузера это то же приложение. Оболочка в воркере прежняя, из статьи «Без сети»: главная /, запасная страница, код и стили. Ветка навигации тоже прежняя и уже лежит на странице примера. Предскажите три строки.

const HOME = "https://board.example/";
const START = "https://board.example/?source=homescreen";

async function main() {
  const cache = createCache();
  const network = createNetwork();

  // install воркера: оболочка из статьи «Без сети»
  for (const url of [HOME, OFFLINE]) {
    cache.put({ method: "GET", url }, await network.fetch(url));
  }

  const tab = await navigationFirst({ method: "GET", url: HOME, mode: "navigate" }, cache, network, 200);
  console.log("вкладка, с сетью:", tab.body, "|", tab.from);

  network.setMode("offline");

  // запуск с иконки — это навигация на start_url из манифеста
  const icon = await navigationFirst({ method: "GET", url: START, mode: "navigate" }, cache, network, 200);
  console.log("иконка, без сети:", icon.body, "|", icon.from);

  const again = await navigationFirst({ method: "GET", url: HOME, mode: "navigate" }, cache, network, 200);
  console.log("адрес доски, без сети:", again.body, "|", again.from);
}

main();

Иконка без сети открыла запасную страницу, хотя доска лежит в кеше и по своему адресу без сети отдаётся как ни в чём не бывало. Ключ кеша — адрес целиком, вместе со строкой запроса: / и /?source=homescreen для него разные записи, это мы проверяли на живом Cache API в статье про стратегии кеша. Ветка навигации честно поискала ровно этот адрес, не нашла и отдала запасную.

Проверим на доске. Манифест с меткой, воркер из статьи «Без сети», два открытия с сетью, потом сервер останавливается. Запустить приложение с иконки в Chrome без окна нельзя, поэтому start_url открывается в новой вкладке: для воркера это та же навигация.

$ node start-offline.mjs v5q

Chrome понял start_url ровно так, как написано. В кеше / есть, а /?source=homescreen нет, и вместо доски открылась «Доска без сети». В жизни это выглядит так: человек поставил доску на экран, вечером закрыл, утром в метро нажал на иконку — и увидел запасную страницу. Стоит один раз открыть иконку с сетью, и всё заработает: ветка навигации положит в кеш и этот адрес. Но после выхода новой версии activate удалит старый кеш, и история повторится.

Лечится одной строкой: start_url кладут в оболочку ровно в том виде, в каком он записан в манифесте.

const VERSION = "board-v5";
const OFFLINE = "/offline.html";
// start_url из манифеста — ровно с тем адресом, что там написан, вместе с ?source
const START = "/?source=homescreen";
const SHELL = ["/", START, OFFLINE, "/assets/app.7e4d2f90.js", "/assets/board.5c7d0a11.css"];

Есть и второй путь — искать навигацию в кеше без строки запроса: cache.match(request, { ignoreSearch: true }). Он короче, но меняет правило для всех страниц сразу: будь у доски поиск, /search?q=молоко без сети открыл бы сохранённую страницу поиска по совсем другому слову. Для доски, у которой строка запроса нужна только метке, START в оболочке честнее.

Всё, что открывается с иконки, должно лежать в оболочке буква в букву — вместе со строкой запроса.

Доска стала приложением: ставится на экран там, где платформа это умеет, знает, когда запущена с иконки, и с иконки же открывается без сети. Осталась последняя способность настоящего приложения — сообщить о чём-то, когда доска закрыта. Функция «открыто как приложение» уезжает в следующую статью готовой: на iPhone push получает только приложение, запущенное с экрана Домой.