osmgl 0.18.0 → 0.19.0

package/dist/osmgl.d.cts

@@ -903,7 +903,13 @@ declare class Shader {
     readonly program: WebGLProgram;
     private uniforms;
     private attribs;
-    constructor(ctx: Context, name: string, vertexSource: string, fragmentSource: string, defines?: Record<string, string | number | boolean>);
+    constructor(ctx: Context, name: string, vertexSource: string, fragmentSource: string, defines?: Record<string, string | number | boolean>, 
+    /**
+     * Места атрибутов, которые надо повторить, — у ВАРИАНТА программы (см. surfaceShader): VAO
+     * собран по местам базовой программы и обязан подойти каждому варианту. Общий список мест
+     * (ATTRIB_SLOTS) тут не годится: атрибутов больше, чем гарантированных шестнадцати мест.
+     */
+    bind?: ReadonlyMap<string, number>);
     private cacheLocations;
     use(): void;
     attribLocation(name: string): number;
@@ -1351,6 +1357,41 @@ interface FillExtrusionLayerSpec extends LayerBase {
          * Цвет при этом остаётся за темой: ручка только добавляет блик и градиент поверх него.
          */
         ice?: Interpolated<number>;
+        /**
+         * ОТРАЖЕНИЕ ДОМОВ В СТЕКЛЯННОЙ ЗЕМЛЕ, 0..1 — сила зеркала. Ноль — отражения нет.
+         *
+         * Работает только с z18 (`REFLECTION_MIN_ZOOM` в `layers/renderer`) и без рельефа: это второй
+         * проход по всем домам кадра, и на общем плане он удвоил бы самую дорогую геометрию.
+         */
+        reflection?: Interpolated<number>;
+        /**
+         * БЛЕСК СТЕКЛЯННОЙ ЗЕМЛИ, 0..1: отражение неба по Френелю — чем дальше и чем более скользящий
+         * взгляд, тем сильнее земля берёт цвет горизонта. Работает на любом зуме (это один квад), в
+         * отличие от отражения домов.
+         */
+        reflectionGloss?: Interpolated<number>;
+        /**
+         * ДОМ КАК СТЕКЛО (по образцу Baidu) — только вместе с `ice`.
+         *
+         * `glassTint` — цвет стекла у земли (у Baidu бирюзовый), `glassTintAmount` — насколько (0..1),
+         * `glassTintHeight` — на какой высоте, метры, цвет растворяется: низ цветной, верх светлый, как
+         * у Baidu. Кровля светлее всего — оттенка на ней одна десятая. `glassRim` — светлая
+         * кромка по Френелю: грань, повёрнутая к взгляду ребром, светится, как край стекла.
+         */
+        glassTint?: Interpolated<string>;
+        glassTintAmount?: Interpolated<number>;
+        glassTintHeight?: Interpolated<number>;
+        glassRim?: Interpolated<number>;
+        /**
+         * Насколько верх дома ярче низа, 0..1 — в СВОЁМ цвете, без подмеса белого (0.1 — на 10 %).
+         * Кровля — наравне с верхом стены. Только с `glassTintAmount`.
+         */
+        glassTopLight?: Interpolated<number>;
+        /**
+         * Градиент по плоской крыше, 0..1: ближний к камере край — в тон стекла, дальний — светлый.
+         * Чтобы крыши стеклянного квартала не сливались в одно поле. Только с `glassTintAmount`.
+         */
+        glassRoofGradient?: Interpolated<number>;
         /**
          * Доля светящихся окон, 0..1 — для ночных тем. Какие именно окна горят,
          * решает хеш ячейки, поэтому при движении камеры свет не «бегает».
@@ -1851,6 +1892,13 @@ interface LightSpec {
     fillAltitude: number;
     fillColor: string;
     fillIntensity: number;
+    /**
+     * Сила теней, 0..1 (по умолчанию 1). Ноль — теней нет ВОВСЕ: проход карты теней не запускается.
+     *
+     * Заведено ради стеклянных тем по образцу Baidu: там город светится, и серое пятно у основания
+     * каждого дома читается грязью. Дробное значение ослабляет тень на земле.
+     */
+    shadowStrength?: number;
 }
 /**
  * Небо и дымка.
@@ -3212,6 +3260,16 @@ declare class SeamAssembler {
      * камеры от того набора кусков, что есть прямо сейчас, — и здание «дышало» бы: то целое, то
      * половина. Пока хоть один кусок на месте, дом остаётся тем же самым.
      */
+    /**
+     * Дома, которые НЕ СШИЛИСЬ, с подписью набора кусков, на котором это случилось (01.10.2026).
+     *
+     * Не сшивается дом, у которого часть кусков не загружена: остатки не смыкаются. Без этой памяти
+     * такой дом считался «устаревшим» на каждом заходе и снова отдавался объединению; когда таких
+     * домов больше бюджета, заход не заканчивался НИКОГДА (`pending`), и карта в покое рисовала кадр
+     * за кадром, проигрывая одни и те же объединения (замер на эмуляторе: ~28 кадров в секунду,
+     * поток GL занят наполовину). Повторяем только при смене набора кусков.
+     */
+    private failed;
     private cache;
     /**
      * Пересобрать то, что изменилось.
@@ -3491,6 +3549,8 @@ interface Candidate {
         x: number;
         y: number;
     }[];
+    /** Те же вершины линии в меркаторе (x, y парами) — по ним сетка мест отмеряется ПО ЗЕМЛЕ. */
+    lineWorld?: number[];
 }
 /**
  * Размещённая подпись: то, что реально видно на экране в этом кадре.
@@ -3700,8 +3760,42 @@ declare class SymbolRenderer {
     private shownAt;
     /** Есть ли в кадре подпись, которая ещё проявляется — по ней решается, нужен ли следующий кадр. */
     private fading;
+    /**
+     * ГОТОВЫЙ КАДР ПОДПИСЕЙ — ПОВТОРЯЕМ, ЕСЛИ НИЧЕГО НЕ МЕНЯЛОСЬ (30.09.2026).
+     *
+     * Карта рисует кадры и в покое — ради бегущей воды. Раскладывать подписи заново на каждом таком
+     * кадре незачем: камера та же, тайлы те же, значит и ответ тот же, — а раскладка самая дорогая
+     * часть кадра после геометрии. Хуже того, раскладка зависит от прошлого кадра (липкость, сторона,
+     * место на линии), и любая её неустойчивость в покое превращается в подпись, которая без
+     * остановки прыгает туда-сюда. MapLibre и Mapbox поступают так же: раскладка — по изменению, а
+     * между ними рисуется уже готовое.
+     *
+     * Подпись кадра (`frameSignature`) собирает ВСЁ, от чего раскладка зависит: камеру, размер,
+     * поля, версии данных источников, видимость слоёв подписей, наведение, скрытие, выбранный дом и
+     * поколение картинок. Не хватило глифов или значков — кадр не запоминается: следующий обязан
+     * разложиться с ними. При рельефе повтор выключен: высоты доезжают плитками, а их версии здесь нет.
+     */
+    private lastSignature;
+    private lastRanges;
+    private styleIds;
+    private nextStyleId;
+    private idOf;
+    private frameSignature;
     /** Прозрачность подписи: только что появилась — проявляется, стоит давно — единица. */
     private fadeOf;
+    /**
+     * ★ ПРОЯВЛЕНИЕ ОТМЕЧАЕТ ТОЛЬКО ТО, ЧТО ВСТАЛО (30.09.2026).
+     *
+     * Прозрачность считается в начале `place`, ещё ДО проверки на столкновение, и флаг «кто-то
+     * проявляется» ставился и для кандидата, которому места не нашлось. Его запись о возрасте тут же
+     * стиралась (`rememberPlaced` держит только вставшие), на следующем кадре всё повторялось — флаг
+     * не гас никогда. Кандидатов в кадре сотни, встают десятки, поэтому карта В ПОКОЕ рисовала
+     * 60 кадров в секунду и раскладывала подписи заново каждый кадр (замер на проде: 2538 кадров
+     * подряд). Подпись вдоль дороги, чьё место зависит от прошлого кадра, на части ракурсов при этом
+     * бесконечно перескакивала между двумя местами. Теперь флаг ставит цикл раскладки — по вставшей
+     * подписи, которой ещё не исполнилось `FADE_MS`.
+     */
+    private stillFading;
     /**
      * Порядок разбора кандидатов: важнее — раньше, у прошедших первыми есть шанс занять место.
      *
@@ -3750,6 +3844,8 @@ declare class SymbolRenderer {
     private colorOf;
     private inStyleOrder;
     private draw;
+    /** Нарисовать диапазоны уже залитого буфера — и после раскладки, и при повторе кадра. */
+    private drawRanges;
     /** Запись подложки этого слоя в атласе — по ней градиент знает высоту фигуры. */
     private frameEntryOf;
     private ensureBuffers;
@@ -5364,6 +5460,19 @@ declare const DEFAULT_SHADOWS: ShadowSettings;
 declare class LayerRenderer {
     private fill;
     private surface;
+    /**
+     * ВАРИАНТЫ ПРОГРАММЫ ПОВЕРХНОСТИ: без кода теней и под один материал (см. NO_SHADOWS и MATERIAL в
+     * шейдере). Собираются по первой надобности и живут до конца — их не больше десятка.
+     */
+    private surfaceVariants;
+    /** Варианты программы зданий: без теней, без фасада, без стекла (см. buildingShader). */
+    private buildingVariants;
+    /** Варианты программы линий: без теней, под один материал и один рисунок (см. lineShader). */
+    private lineVariants;
+    /** Для чего варианты уже собраны (см. warmVariants): стиль, тени, детализация. */
+    private warmedStyle;
+    private warmedShadows;
+    private warmedDetail;
     private surfaceLocs;
     private line;
     private building;
@@ -5407,6 +5516,17 @@ declare class LayerRenderer {
     /** Настройки теней; правит карта через `setShadows`. */
     readonly shadows: ShadowSettings;
     private shadowTarget;
+    /** Отражение домов в стеклянной земле (см. `renderReflection`). */
+    private reflectionTarget;
+    private reflectionShader;
+    private reflectionQuad;
+    private reflectionBuffers;
+    /** Сила отражения в ЭТОМ кадре; ноль — прохода нет. */
+    private reflectionStrength;
+    /** Блеск стеклянной земли в этом кадре (см. `reflectionGloss`). */
+    private reflectionGloss;
+    /** Идёт проход отражения: шейдер домов переворачивает их по высоте. */
+    private mirror;
     /** Пустышка под sampler2DShadow, когда теней нет, — см. createShadowPlaceholder. */
     private shadowPlaceholder;
     /** Тени посчитаны в этом кадре и их можно накладывать. */
@@ -5417,6 +5537,17 @@ declare class LayerRenderer {
     private materialTime;
     /** Хоть один материал в кадре анимируется — значит нужен следующий кадр. */
     private materialAnimating;
+    /**
+     * Материал ТЕКУЩЕГО слоя анимирован (бегущая вода) — но кадр просим, только если слой что-то
+     * нарисовал.
+     *
+     * Раньше `applyMaterial` сразу ставил `materialAnimating`: слой воды включён на зуме — значит,
+     * следующий кадр, даже когда воды на экране нет вовсе. Слой воды есть почти во всех темах, и карта
+     * в покое рисовала 60 кадров в секунду на любом зуме (замер на проде 30.09.2026: 180 кадров за
+     * 3 с на районе без единого водоёма). Теперь флаг ставит цикл отрисовки — по тайлу, где нашлась
+     * геометрия.
+     */
+    private materialPending;
     /**
      * Номер тайла в трафарете — по нему поверхности обрезаются по своему тайлу.
      * Пусто, если трафарет в этом кадре не размечен (см. `drawTileStencil`).
@@ -5594,7 +5725,10 @@ declare class LayerRenderer {
     hiddenVenueLayer: string | null;
     /** Урезанные индексы по тайлам; ключ — тайл, отпечаток — состав набора. */
     private hiddenCut;
+    /** Отпечаток общего набора скрытого (заменённые + оболочки). `null` — ещё не считали. */
     private hiddenStamp;
+    /** Отпечаток раскладки швов по тайлам. */
+    private hiddenTileStamps;
     /**
      * Отпечаток наборов скрытого — ОДИН раз за кадр, а не на каждый тайк.
      *
@@ -5930,6 +6064,34 @@ declare class LayerRenderer {
      * рисует землю. Программе без соответствующих юниформов установка молча проходит мимо.
      */
     private applyTileScale;
+    /** Номер материала слоя; ноль — без материала (в том числе при нулевой детализации). */
+    private materialIdOf;
+    /**
+     * Программа поверхности под этот слой и кадр. Тени выключены — берётся вариант без их кода,
+     * материал — только свой. Так программа меньше, и мобильный GPU держит больше пикселей в работе:
+     * на Adreno 610 полотно подешевело с 32 до 6 мс за кадр (01.10.2026).
+     */
+    private surfaceShader;
+    /**
+     * Программа зданий под этот слой и кадр — тот же приём, что у поверхности: выключенное (тени,
+     * фасад при нулевой детализации, стекло вне ледяной темы) в программу не попадает. Цена здания
+     * на мобильном GPU определяется размером программы, а не тем, какие ветки выполнились.
+     */
+    private buildingShader;
+    /**
+     * СОБРАТЬ ВАРИАНТЫ ПРОГРАММ ЗАРАНЕЕ — при смене стиля, а не при первой встрече в кадре.
+     *
+     * Сборка программы на мобильном GPU стоит десятки миллисекунд (замер на Adreno 610: кадр 187 мс
+     * без единой заливки — это сборка). Встреча «по пути» приходится ровно на проезд по городу, когда
+     * в кадр въезжает слой нового вида, — и выглядит рывком. Поэтому все варианты стиля собираются
+     * разом: один долгий кадр при загрузке вместо рывков на ходу. Тени — по ожидаемому состоянию;
+     * переключение теней соберёт свой набор один раз. Фасад зависит от зума — перебираем зумы слоя.
+     */
+    private warmVariants;
+    /** Рисунок вдоль линии: 0 сплошная, 1 штрих, 2 шевроны, 3 стрелки, 4 только стрелки, 5 стрелки-штрих. */
+    private linePatternOf;
+    /** Программа линий под этот слой и кадр — тот же приём, что у поверхности (см. surfaceShader). */
+    private lineShader;
     private applyMaterial;
     private drawFill;
     private drawLine;
@@ -5992,6 +6154,28 @@ declare class LayerRenderer {
      * тот проход считает всё лежащим на нуле.
      */
     private drawSurface;
+    /**
+     * Сила отражения в кадре: наибольшая из `reflection` видимых слоёв домов, с плавным входом на
+     * `REFLECTION_MIN_ZOOM`. На рельефе и глобусе отражения нет: земля там не плоскость, и зеркало в
+     * плоскости z = 0 показало бы дома не там, где они отражаются.
+     */
+    private reflectionStrengthOf;
+    /** Блеск стеклянной земли: наибольший `reflectionGloss` видимых слоёв домов, на любом зуме. */
+    private reflectionGlossOf;
+    /**
+     * ОТРАЖЕНИЕ ДОМОВ — В СВОЙ БУФЕР, ДО ОСНОВНОГО КАДРА.
+     *
+     * Приём зеркала в плоскости (`Reflector` three.js): для плоскости земли отражённая камера
+     * равносильна тем же домам, перевёрнутым по высоте, — их и рисует обычный проход зданий с
+     * `u_mirror = −1`. Намотка треугольников при этом зеркальная, поэтому отсекаются ПЕРЕДНИЕ грани.
+     * Тени в отражении не нужны: его и так едва видно. Буфер — в полразмера кадра.
+     */
+    private renderReflection;
+    /**
+     * СТЕКЛЯННАЯ ЗЕМЛЯ — один квад во весь экран: размытое отражение домов (с z18) и блеск неба по
+     * Френелю (на любом зуме). Выше горизонта не рисуется: там небо, а не стекло.
+     */
+    private drawReflection;
     private drawBuildings;
     /** Подсветить один сшитый дом: геометрия берётся из его же меша. */
     private drawSeamHighlight;

package/dist/osmgl.d.ts

@@ -903,7 +903,13 @@ declare class Shader {
     readonly program: WebGLProgram;
     private uniforms;
     private attribs;
-    constructor(ctx: Context, name: string, vertexSource: string, fragmentSource: string, defines?: Record<string, string | number | boolean>);
+    constructor(ctx: Context, name: string, vertexSource: string, fragmentSource: string, defines?: Record<string, string | number | boolean>, 
+    /**
+     * Места атрибутов, которые надо повторить, — у ВАРИАНТА программы (см. surfaceShader): VAO
+     * собран по местам базовой программы и обязан подойти каждому варианту. Общий список мест
+     * (ATTRIB_SLOTS) тут не годится: атрибутов больше, чем гарантированных шестнадцати мест.
+     */
+    bind?: ReadonlyMap<string, number>);
     private cacheLocations;
     use(): void;
     attribLocation(name: string): number;
@@ -1351,6 +1357,41 @@ interface FillExtrusionLayerSpec extends LayerBase {
          * Цвет при этом остаётся за темой: ручка только добавляет блик и градиент поверх него.
          */
         ice?: Interpolated<number>;
+        /**
+         * ОТРАЖЕНИЕ ДОМОВ В СТЕКЛЯННОЙ ЗЕМЛЕ, 0..1 — сила зеркала. Ноль — отражения нет.
+         *
+         * Работает только с z18 (`REFLECTION_MIN_ZOOM` в `layers/renderer`) и без рельефа: это второй
+         * проход по всем домам кадра, и на общем плане он удвоил бы самую дорогую геометрию.
+         */
+        reflection?: Interpolated<number>;
+        /**
+         * БЛЕСК СТЕКЛЯННОЙ ЗЕМЛИ, 0..1: отражение неба по Френелю — чем дальше и чем более скользящий
+         * взгляд, тем сильнее земля берёт цвет горизонта. Работает на любом зуме (это один квад), в
+         * отличие от отражения домов.
+         */
+        reflectionGloss?: Interpolated<number>;
+        /**
+         * ДОМ КАК СТЕКЛО (по образцу Baidu) — только вместе с `ice`.
+         *
+         * `glassTint` — цвет стекла у земли (у Baidu бирюзовый), `glassTintAmount` — насколько (0..1),
+         * `glassTintHeight` — на какой высоте, метры, цвет растворяется: низ цветной, верх светлый, как
+         * у Baidu. Кровля светлее всего — оттенка на ней одна десятая. `glassRim` — светлая
+         * кромка по Френелю: грань, повёрнутая к взгляду ребром, светится, как край стекла.
+         */
+        glassTint?: Interpolated<string>;
+        glassTintAmount?: Interpolated<number>;
+        glassTintHeight?: Interpolated<number>;
+        glassRim?: Interpolated<number>;
+        /**
+         * Насколько верх дома ярче низа, 0..1 — в СВОЁМ цвете, без подмеса белого (0.1 — на 10 %).
+         * Кровля — наравне с верхом стены. Только с `glassTintAmount`.
+         */
+        glassTopLight?: Interpolated<number>;
+        /**
+         * Градиент по плоской крыше, 0..1: ближний к камере край — в тон стекла, дальний — светлый.
+         * Чтобы крыши стеклянного квартала не сливались в одно поле. Только с `glassTintAmount`.
+         */
+        glassRoofGradient?: Interpolated<number>;
         /**
          * Доля светящихся окон, 0..1 — для ночных тем. Какие именно окна горят,
          * решает хеш ячейки, поэтому при движении камеры свет не «бегает».
@@ -1851,6 +1892,13 @@ interface LightSpec {
     fillAltitude: number;
     fillColor: string;
     fillIntensity: number;
+    /**
+     * Сила теней, 0..1 (по умолчанию 1). Ноль — теней нет ВОВСЕ: проход карты теней не запускается.
+     *
+     * Заведено ради стеклянных тем по образцу Baidu: там город светится, и серое пятно у основания
+     * каждого дома читается грязью. Дробное значение ослабляет тень на земле.
+     */
+    shadowStrength?: number;
 }
 /**
  * Небо и дымка.
@@ -3212,6 +3260,16 @@ declare class SeamAssembler {
      * камеры от того набора кусков, что есть прямо сейчас, — и здание «дышало» бы: то целое, то
      * половина. Пока хоть один кусок на месте, дом остаётся тем же самым.
      */
+    /**
+     * Дома, которые НЕ СШИЛИСЬ, с подписью набора кусков, на котором это случилось (01.10.2026).
+     *
+     * Не сшивается дом, у которого часть кусков не загружена: остатки не смыкаются. Без этой памяти
+     * такой дом считался «устаревшим» на каждом заходе и снова отдавался объединению; когда таких
+     * домов больше бюджета, заход не заканчивался НИКОГДА (`pending`), и карта в покое рисовала кадр
+     * за кадром, проигрывая одни и те же объединения (замер на эмуляторе: ~28 кадров в секунду,
+     * поток GL занят наполовину). Повторяем только при смене набора кусков.
+     */
+    private failed;
     private cache;
     /**
      * Пересобрать то, что изменилось.
@@ -3491,6 +3549,8 @@ interface Candidate {
         x: number;
         y: number;
     }[];
+    /** Те же вершины линии в меркаторе (x, y парами) — по ним сетка мест отмеряется ПО ЗЕМЛЕ. */
+    lineWorld?: number[];
 }
 /**
  * Размещённая подпись: то, что реально видно на экране в этом кадре.
@@ -3700,8 +3760,42 @@ declare class SymbolRenderer {
     private shownAt;
     /** Есть ли в кадре подпись, которая ещё проявляется — по ней решается, нужен ли следующий кадр. */
     private fading;
+    /**
+     * ГОТОВЫЙ КАДР ПОДПИСЕЙ — ПОВТОРЯЕМ, ЕСЛИ НИЧЕГО НЕ МЕНЯЛОСЬ (30.09.2026).
+     *
+     * Карта рисует кадры и в покое — ради бегущей воды. Раскладывать подписи заново на каждом таком
+     * кадре незачем: камера та же, тайлы те же, значит и ответ тот же, — а раскладка самая дорогая
+     * часть кадра после геометрии. Хуже того, раскладка зависит от прошлого кадра (липкость, сторона,
+     * место на линии), и любая её неустойчивость в покое превращается в подпись, которая без
+     * остановки прыгает туда-сюда. MapLibre и Mapbox поступают так же: раскладка — по изменению, а
+     * между ними рисуется уже готовое.
+     *
+     * Подпись кадра (`frameSignature`) собирает ВСЁ, от чего раскладка зависит: камеру, размер,
+     * поля, версии данных источников, видимость слоёв подписей, наведение, скрытие, выбранный дом и
+     * поколение картинок. Не хватило глифов или значков — кадр не запоминается: следующий обязан
+     * разложиться с ними. При рельефе повтор выключен: высоты доезжают плитками, а их версии здесь нет.
+     */
+    private lastSignature;
+    private lastRanges;
+    private styleIds;
+    private nextStyleId;
+    private idOf;
+    private frameSignature;
     /** Прозрачность подписи: только что появилась — проявляется, стоит давно — единица. */
     private fadeOf;
+    /**
+     * ★ ПРОЯВЛЕНИЕ ОТМЕЧАЕТ ТОЛЬКО ТО, ЧТО ВСТАЛО (30.09.2026).
+     *
+     * Прозрачность считается в начале `place`, ещё ДО проверки на столкновение, и флаг «кто-то
+     * проявляется» ставился и для кандидата, которому места не нашлось. Его запись о возрасте тут же
+     * стиралась (`rememberPlaced` держит только вставшие), на следующем кадре всё повторялось — флаг
+     * не гас никогда. Кандидатов в кадре сотни, встают десятки, поэтому карта В ПОКОЕ рисовала
+     * 60 кадров в секунду и раскладывала подписи заново каждый кадр (замер на проде: 2538 кадров
+     * подряд). Подпись вдоль дороги, чьё место зависит от прошлого кадра, на части ракурсов при этом
+     * бесконечно перескакивала между двумя местами. Теперь флаг ставит цикл раскладки — по вставшей
+     * подписи, которой ещё не исполнилось `FADE_MS`.
+     */
+    private stillFading;
     /**
      * Порядок разбора кандидатов: важнее — раньше, у прошедших первыми есть шанс занять место.
      *
@@ -3750,6 +3844,8 @@ declare class SymbolRenderer {
     private colorOf;
     private inStyleOrder;
     private draw;
+    /** Нарисовать диапазоны уже залитого буфера — и после раскладки, и при повторе кадра. */
+    private drawRanges;
     /** Запись подложки этого слоя в атласе — по ней градиент знает высоту фигуры. */
     private frameEntryOf;
     private ensureBuffers;
@@ -5364,6 +5460,19 @@ declare const DEFAULT_SHADOWS: ShadowSettings;
 declare class LayerRenderer {
     private fill;
     private surface;
+    /**
+     * ВАРИАНТЫ ПРОГРАММЫ ПОВЕРХНОСТИ: без кода теней и под один материал (см. NO_SHADOWS и MATERIAL в
+     * шейдере). Собираются по первой надобности и живут до конца — их не больше десятка.
+     */
+    private surfaceVariants;
+    /** Варианты программы зданий: без теней, без фасада, без стекла (см. buildingShader). */
+    private buildingVariants;
+    /** Варианты программы линий: без теней, под один материал и один рисунок (см. lineShader). */
+    private lineVariants;
+    /** Для чего варианты уже собраны (см. warmVariants): стиль, тени, детализация. */
+    private warmedStyle;
+    private warmedShadows;
+    private warmedDetail;
     private surfaceLocs;
     private line;
     private building;
@@ -5407,6 +5516,17 @@ declare class LayerRenderer {
     /** Настройки теней; правит карта через `setShadows`. */
     readonly shadows: ShadowSettings;
     private shadowTarget;
+    /** Отражение домов в стеклянной земле (см. `renderReflection`). */
+    private reflectionTarget;
+    private reflectionShader;
+    private reflectionQuad;
+    private reflectionBuffers;
+    /** Сила отражения в ЭТОМ кадре; ноль — прохода нет. */
+    private reflectionStrength;
+    /** Блеск стеклянной земли в этом кадре (см. `reflectionGloss`). */
+    private reflectionGloss;
+    /** Идёт проход отражения: шейдер домов переворачивает их по высоте. */
+    private mirror;
     /** Пустышка под sampler2DShadow, когда теней нет, — см. createShadowPlaceholder. */
     private shadowPlaceholder;
     /** Тени посчитаны в этом кадре и их можно накладывать. */
@@ -5417,6 +5537,17 @@ declare class LayerRenderer {
     private materialTime;
     /** Хоть один материал в кадре анимируется — значит нужен следующий кадр. */
     private materialAnimating;
+    /**
+     * Материал ТЕКУЩЕГО слоя анимирован (бегущая вода) — но кадр просим, только если слой что-то
+     * нарисовал.
+     *
+     * Раньше `applyMaterial` сразу ставил `materialAnimating`: слой воды включён на зуме — значит,
+     * следующий кадр, даже когда воды на экране нет вовсе. Слой воды есть почти во всех темах, и карта
+     * в покое рисовала 60 кадров в секунду на любом зуме (замер на проде 30.09.2026: 180 кадров за
+     * 3 с на районе без единого водоёма). Теперь флаг ставит цикл отрисовки — по тайлу, где нашлась
+     * геометрия.
+     */
+    private materialPending;
     /**
      * Номер тайла в трафарете — по нему поверхности обрезаются по своему тайлу.
      * Пусто, если трафарет в этом кадре не размечен (см. `drawTileStencil`).
@@ -5594,7 +5725,10 @@ declare class LayerRenderer {
     hiddenVenueLayer: string | null;
     /** Урезанные индексы по тайлам; ключ — тайл, отпечаток — состав набора. */
     private hiddenCut;
+    /** Отпечаток общего набора скрытого (заменённые + оболочки). `null` — ещё не считали. */
     private hiddenStamp;
+    /** Отпечаток раскладки швов по тайлам. */
+    private hiddenTileStamps;
     /**
      * Отпечаток наборов скрытого — ОДИН раз за кадр, а не на каждый тайк.
      *
@@ -5930,6 +6064,34 @@ declare class LayerRenderer {
      * рисует землю. Программе без соответствующих юниформов установка молча проходит мимо.
      */
     private applyTileScale;
+    /** Номер материала слоя; ноль — без материала (в том числе при нулевой детализации). */
+    private materialIdOf;
+    /**
+     * Программа поверхности под этот слой и кадр. Тени выключены — берётся вариант без их кода,
+     * материал — только свой. Так программа меньше, и мобильный GPU держит больше пикселей в работе:
+     * на Adreno 610 полотно подешевело с 32 до 6 мс за кадр (01.10.2026).
+     */
+    private surfaceShader;
+    /**
+     * Программа зданий под этот слой и кадр — тот же приём, что у поверхности: выключенное (тени,
+     * фасад при нулевой детализации, стекло вне ледяной темы) в программу не попадает. Цена здания
+     * на мобильном GPU определяется размером программы, а не тем, какие ветки выполнились.
+     */
+    private buildingShader;
+    /**
+     * СОБРАТЬ ВАРИАНТЫ ПРОГРАММ ЗАРАНЕЕ — при смене стиля, а не при первой встрече в кадре.
+     *
+     * Сборка программы на мобильном GPU стоит десятки миллисекунд (замер на Adreno 610: кадр 187 мс
+     * без единой заливки — это сборка). Встреча «по пути» приходится ровно на проезд по городу, когда
+     * в кадр въезжает слой нового вида, — и выглядит рывком. Поэтому все варианты стиля собираются
+     * разом: один долгий кадр при загрузке вместо рывков на ходу. Тени — по ожидаемому состоянию;
+     * переключение теней соберёт свой набор один раз. Фасад зависит от зума — перебираем зумы слоя.
+     */
+    private warmVariants;
+    /** Рисунок вдоль линии: 0 сплошная, 1 штрих, 2 шевроны, 3 стрелки, 4 только стрелки, 5 стрелки-штрих. */
+    private linePatternOf;
+    /** Программа линий под этот слой и кадр — тот же приём, что у поверхности (см. surfaceShader). */
+    private lineShader;
     private applyMaterial;
     private drawFill;
     private drawLine;
@@ -5992,6 +6154,28 @@ declare class LayerRenderer {
      * тот проход считает всё лежащим на нуле.
      */
     private drawSurface;
+    /**
+     * Сила отражения в кадре: наибольшая из `reflection` видимых слоёв домов, с плавным входом на
+     * `REFLECTION_MIN_ZOOM`. На рельефе и глобусе отражения нет: земля там не плоскость, и зеркало в
+     * плоскости z = 0 показало бы дома не там, где они отражаются.
+     */
+    private reflectionStrengthOf;
+    /** Блеск стеклянной земли: наибольший `reflectionGloss` видимых слоёв домов, на любом зуме. */
+    private reflectionGlossOf;
+    /**
+     * ОТРАЖЕНИЕ ДОМОВ — В СВОЙ БУФЕР, ДО ОСНОВНОГО КАДРА.
+     *
+     * Приём зеркала в плоскости (`Reflector` three.js): для плоскости земли отражённая камера
+     * равносильна тем же домам, перевёрнутым по высоте, — их и рисует обычный проход зданий с
+     * `u_mirror = −1`. Намотка треугольников при этом зеркальная, поэтому отсекаются ПЕРЕДНИЕ грани.
+     * Тени в отражении не нужны: его и так едва видно. Буфер — в полразмера кадра.
+     */
+    private renderReflection;
+    /**
+     * СТЕКЛЯННАЯ ЗЕМЛЯ — один квад во весь экран: размытое отражение домов (с z18) и блеск неба по
+     * Френелю (на любом зуме). Выше горизонта не рисуется: там небо, а не стекло.
+     */
+    private drawReflection;
     private drawBuildings;
     /** Подсветить один сшитый дом: геометрия берётся из его же меша. */
     private drawSeamHighlight;