ds-galo/openspec/changes/pano360-viewer/design.md

Design

Context

См. proposal.md — Why. См. сценарии в specs/ui-workspace/spec.md. Опорные факты по коду:

• Viewer.svelte — единая область просмотра: scroller c <img> (плоский зум/панорамирование, Space, колесо), топбар, лента миниатюр, контекстное меню, f/fullscreen. Используется и в маршруте фото, и на публичной share-странице.
• Теги персональные (tags.user_id); photo.tags приходят и в списке, и в /photos/:id. На share-страницах GetPublic читает фото с пустым пользователем → тегов нет.
• Варианты: thumb 200 и preview 1200 (webp); плюс original_url (подписанный, 1 час).
• В проекте нет runtime-зависимостей; статика вшивается в Go-бинарник.

Goals / Non-Goals

Goals:

• 360-обзор для фото с личным тегом pano360, без сторонних библиотек.
• Сохранить плоский просмотр и все прочие функции Viewer без регрессий.
• Деградация до плоского изображения, когда 360 невозможен.

Non-Goals:

• Бэкенд, новый pano-вариант, автоопределение GPano/XMP.
• 360 на share-страницах и у других участников (теги персональные).
• Редактор панорам, горячие точки, стерео/VR.

Decisions

1. Детект: личный тег pano360

isPanoTag(photo) — photo.tags?.some(t => t.name.trim().toLowerCase() === 'pano360'). Источник — уже отдаваемые теги; бэкенд не трогаем. Следствие: на share и у других участников режим не включается (осознанное ограничение, покрыто сценарием спеки).

2. Рендер: мини-WebGL equirect без зависимостей

Отдельный PanoViewer.svelte, владеющий <canvas>:

экран (uv) --inv(fov,yaw,pitch)--> луч dir --atan2/asin--> lon/lat --> equirect uv --> sample

• Вершинный шейдер: полноэкранный quad.
• Фрагментный: направление луча из uv + uFov/uYaw/uPitch/uRes; выборка текстуры equirect.
• WebGL1: NPOT-текстура → CLAMP_TO_EDGE/LINEAR, без мипмапов.
• ResizeObserver + devicePixelRatio для ресайза канвы.

Альтернативы: three.js (быстрее писать, но +~150 КБ gz и первая runtime-зависимость) и готовая панорамная библиотека (чужая тема/UI). Отклонены в пользу 0 зависимостей.

3. Текстура: оригинал с даунскейлом, фолбэк preview

original_url загружается через fetch того же origin (подписанный URL может быть абсолютным на хост API) → blob → createImageBitmap, чтобы пиксели были origin-clean (иначе texImage2D бросает «cross-origin data»). Далее даунскейл до min(4096, gl.MAX_TEXTURE_SIZE) и texImage2D. Если оригинал недоступен — preview_url. Новый pano-вариант не заводим (иначе бэкенд).

3a. Жизненный цикл WebGL

GL инициализируется один раз на элемент канвы; повторные запуски эффекта (в т.ч. из-за bind:this) — no-op. Освобождение ресурсов (текстура/программа, WEBGL_lose_context) — только при уничтожении компонента. Раньше teardown() вызывался на перезапуске эффекта, терял контекст, и повторная инициализация компилировала шейдеры на «потерянном» контексте → ложный фолбэк.

4. Фолбэк на плоский <img>

PanoViewer вызывает onFallback() при отсутствии WebGL-контекста или сбое загрузки/декодирования; Viewer тогда рендерит обычный <img> и плоские жесты.

5. Разделение ответственности и интеракции

• Viewer владеет топбаром, лентой, клавишами и контекстным меню.
• PanoViewer владеет канвой, указателем и колесом: drag/свайп — yaw/pitch, колесо — fov (клэмп, напр. 30°..100°).
• Space в Viewer в 360-режиме вызывает panoRef.reset() (вместо плоского toggleActual).
• В 360-режиме плоский зум/панорамирование и wheel/pointer-обработчики scroller не активны; свайп не листает фото (смена — стрелками и лентой); f/fullscreen и стрелки — как прежде.
• Компонент создаётся с key={current.id}, ресурсы освобождаются при смене фото/размонтировании.

6. Индикация

Признак «360» в топбаре при активном режиме; бейдж «360» на плитке сетки для фото с тегом (теги есть в списочном ответе).

Risks / Trade-offs

• [Оригинал больше лимита текстуры/много VRAM] → даунскейл до min(4096, MAX_TEXTURE_SIZE).
• [WebGL недоступен] → onFallback() и плоский <img>.
• [Конфликт жестов с плоским режимом] → режим-специфичные обработчики; свайп в 360 только осмотр.
• [Утечки WebGL-контекста] → deleteTexture/deleteProgram/loseContext при размонтировании/смене фото.
• [Личный тег: 360 не виден другим/на share] → покрыто сценарием спеки как ожидаемое поведение.
• [Производительность на слабых GPU] → простая сцена (один quad), опционально ограничение DPR.

Migration Plan

Только фронтенд; данных и API не трогаем. Откат — удаление нового режима. Проверка: cd frontend && npm run check и npm run build, плюс панo-сценарии в CDP‑QA.