QR Microapps Lab

Локальный инструмент для проверки и упаковки небольших автономных HTML-приложений в QR-код. Готовая лаборатория работает одним HTML-файлом: без сервера, установки, CDN и подключения к Интернету.

Лабораторию можно использовать на занятиях по разработке с ИИ: задавать требования к приложению, проверять результат генерации и исправлять найденные нарушения.

Автор: Илья Барило (Ilya Barilo).

Открыть онлайн · Скачать автономный HTML · Последний релиз · Практический кейс · Спецификация игр

Статус: рабочий экспериментальный инструмент. Публичное демо соответствует последнему опубликованному релизу.

HTML → оптимизация → автоматические проверки → QR → обратное декодирование → предпросмотр

Попробовать за 2 минуты

1. Откройте онлайн-демо.
2. Выберите готовый пример — он загрузится автоматически.
3. Измените код или оставьте без изменений.
4. Нажмите «Проверить и создать QR».
5. Посмотрите автоотчёт и результат обратного декодирования.
6. Проверьте работу приложения во встроенном предпросмотре. Затем можно скачать HTML или QR.

Автономный запуск

1. Скачайте qr-microapps-lab.html.
2. Откройте файл в современном браузере.
3. Загрузите собственный HTML или выберите автоматически загружаемый готовый пример, затем нажмите «Проверить и создать QR».

Стили, исходный код, QRCode.js, jsQR, анализаторы Acorn и CSS Tree и обязательные лицензионные уведомления уже встроены в этот файл. Для обычного запуска остальные файлы репозитория не нужны.

QR с data: URL может распознаться камерой как текст, а не как обычная веб-ссылка. Возможность открыть его зависит от сканера, браузера и операционной системы телефона.

Для кого

• для авторов компактных автономных HTML-игр и микроприложений;
• для преподавателей и разработчиков интерактивных учебных материалов;
• для проектов, которым нужен запуск без сервера и подключения к Интернету;
• для разработчиков, проверяющих вместимость, корректность и практическую читаемость QR-кодов.

Что умеет лаборатория

• принимает готовый HTML или собирает тест в визуальном конструкторе;
• загружает QR-изображение, декодирует коды из других генераторов и показывает версию, матрицу, уровень коррекции, маску, режим данных и геометрию изображения;
• позволяет перенести измеренные уровень коррекции, масштаб модулей и рамку в генератор для сравнительного испытания, не выдавая расчёт за гарантию распознавания телефоном;
• сокращает CSS и JavaScript с помощью локальных синтаксических анализаторов и показывает экономию; HTML-комментарии и межтеговые пробелы сохраняются;
• проверяет doctype, UTF-8, мобильный viewport, внешние ресурсы, сетевые API и навигацию;
• проверяет сенсорное управление по исходнику и доступным элементам в предпросмотре, включая кнопки, созданные JavaScript;
• включает в автоотчёт ошибки выполнения, заблокированные операции и переполнение предпросмотра;
• всегда использует Base64 и автоматически выбирает коррекцию M, а при нехватке вместимости — L с предупреждением;
• позволяет настраивать рамку QR и масштаб полноэкранного отображения;
• рисует модули целым числом пикселей и показывает QR на белом полноэкранном поле;
• создаёт быстрый лист Q и полный набор листов A–H с расчётом физического размера модулей для проверки печатного порога, коррекции, способов представления HTML, вариантов ручного перехода и плотности QR;
• позволяет открывать каждый тестовый QR отдельно на экране, калибровать физический масштаб банковской картой и видеть CSS-пиксели, размер буфера и пиксели на модуль;
• декодирует пиксели через независимую библиотеку jsQR и сравнивает нагрузку с исходной;
• запускает приложение в sandbox-предпросмотре с запретом сетевых запросов;
• изменяет сложность любого совместимого HTML через стандартную переменную $d;
• содержит встроенную Markdown-спецификацию для создания игр с помощью ИИ, которую можно скачать или скопировать без интернета;
• сохраняет HTML, PNG, дополнительный векторный SVG, профиль, отчёт и переносимый файл проекта;
• печатает текущий QR на одном листе A4 с названием, редактируемой инструкцией и размером от 20 до 180 мм;
• содержит одиннадцать встроенных примеров: тест, «Как думает компьютер?», «Турнирная сетка», «Пакет в сети», «Разбей блоки», «Брандмауэр», «Успей в релиз», «Киберрефлекс», «Кибертрасса 2.5D», «Киберлабиринт 2.5D» и «Карьерный компас».

«Кибертрасса 2.5D» и «Киберлабиринт 2.5D» создают видимость объёма двумерными методами. Для примеров с документацией доступна кнопка «Описание примера».

Как контролируется результат ИИ

Лаборатория не считает сгенерированный HTML готовым только потому, что он открылся в браузере. Работа строится как последовательность контрольных точек:

замысел преподавателя → спецификация → HTML от ИИ → автоматические проверки
→ независимое декодирование QR → испытание на телефоне → применение

Автоматически проверяются измеримые технические свойства: автономность, вместимость, структура HTML, мобильный интерфейс, запрещённые операции и точность цифрового восстановления. Содержание, удобство и работа на конкретном телефоне требуют отдельной оценки человеком.

Проверка на реальных устройствах

Приложение из QR удалось запустить на Redmi Note 13 Pro, Redmi Note 8 Pro, Redmi Note 6 Pro и Huawei Mate X6. На трёх Redmi дополнительно проверена работа без Интернета. На Huawei Интернет не отключали.

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

Ранняя версия проекта использовалась на учебном занятии, но результаты проверки телефонов тогда не протоколировались. Опубликованные результаты получены в отдельных испытаниях.

Структура публичного репозитория

Каталоги

Каталог	Зачем нужен
.github/workflows/	Автоматическая проверка, публикация GitHub Pages и подготовка файлов релиза.
docs/	Краткие материалы о проверке проекта и изображения для публичной документации.
docs/images/	Изображения, используемые в README и других публичных материалах проекта.
editor/	Редактируемые исходники лаборатории: HTML-шаблон, CSS, JavaScript-модули и локальные QR-библиотеки.
editor/vendor/	QR-библиотеки, анализаторы HTML/CSS/JavaScript и лицензии. Библиотеки включаются в итоговый HTML и не загружаются из CDN.
pages/	Стартовая страница и служебный файл для публикации GitHub Pages.
tests/	Проверки, npm-конфигурация, зафиксированные тестовые зависимости и настройки Playwright.
tools/	Сборщик, объединяющий исходники и лицензии в один qr-microapps-lab.html.

Файлы в корне

Файл	Зачем нужен
qr-microapps-lab.html	Готовая версия программы одним автономным файлом. Это основной результат проекта.
spec_game_creation_ru.md	Спецификация создания совместимых автономных игр с помощью ИИ и готовый шаблон промпта.
README.md	Краткое описание, запуск и карта репозитория.
LICENSE	MIT-лицензия собственного кода проекта.
THIRD_PARTY_NOTICES.md	Происхождение и лицензии встроенных библиотек.

Разработка

Для сборки требуется Node.js 22 или новее. Редактировать нужно файлы в editor/; корневой автономный HTML является результатом сборки.

npm --prefix tests run build:standalone
npm --prefix tests run check

Полная браузерная проверка после установки зависимостей:

npm --prefix tests ci
npm --prefix tests exec -- playwright install chromium firefox webkit
npm --prefix tests run check:all

• npm --prefix tests run build:standalone обновляет корневой автономный HTML.
• npm --prefix tests run build:html-parser воспроизводит локальную браузерную сборку parse5 из зависимостей, зафиксированных в tests/package-lock.json. Для обычной сборки лаборатории эта команда не нужна.
• npm --prefix tests run check запускает модульные тесты, проверяет актуальность сборки и структуру репозитория.
• npm --prefix tests run test:standalone-browser открывает HTML напрямую через file:// в Chromium, проверяет отсутствие сетевых запросов и печать листов в PDF.
• npm --prefix tests run test:e2e проверяет основные пользовательские сценарии в Chromium, Firefox и WebKit: черновики, импорт и экспорт, автономный запуск, предпросмотр и адаптивный интерфейс. Для одного браузера добавьте -- --project=firefox (или chromium, webkit).

CI и публикация релиза запускают проверки во всех трёх браузерах. Используются тестовые сборки Playwright; WebKit в этих проверках не подтверждает работу камеры или Safari на настоящем iPhone. Тестовые браузеры нужны только для разработки и не включаются в автономный HTML.

GitHub Pages

Единый workflow Publish release автоматически запускается при публикации GitHub Release и извлекает проект из соответствующего тега. Он один раз проверяет выбранную версию, подставляет тег в интерфейс, прикрепляет автономный HTML к релизу и публикует тот же файл на GitHub Pages. Содержимое демо, отображаемая версия и скачиваемый релиз поэтому соответствуют друг другу. Для повторной публикации существующего релиза workflow можно запустить вручную, указав его тег. Обычный push в main обновляет исходники и запускает CI, но не меняет стабильное демо. Исходный каталог pages/ не нужен для локального запуска лаборатории.

Релизы

При публикации GitHub Release workflow Publish release подставляет тег релиза в интерфейс и автоматически добавляет готовый qr-microapps-lab.html. Создаваемые GitHub архивы Source code остаются доступны отдельно.

В отображаемых версиях и тегах конечный нулевой номер исправления опускается: v0.1 вместо v0.1.0, v1.2 вместо v1.2.0. Ненулевой номер сохраняется полностью, например v0.1.2.

Порядок подготовки релиза и разбор ошибок CI описаны в руководстве разработчика.

Ограничения и безопасность

Корректно созданный QR не гарантирует запуск штатной камерой любого телефона. Результат зависит от физического размера модулей, экрана, освещения, сканера, ОС и того, разрешает ли браузер открывать data: URL.

Обратное декодирование jsQR доказывает цифровую корректность сформированных пикселей, но не заменяет проверку камерой реального устройства.

Предпросмотр использует sandbox, CSP внутри запускаемого документа и ограничение навигации iframe на странице лаборатории. Это уменьшает риск, но не защищает полностью от пользовательского кода, способного зависанием перегрузить вкладку. Не запускайте неизвестный HTML без необходимости.

Лицензии

Компонент	Лицензия	Где используется
Собственный код QR Microapps Lab, © 2026 Ilya Barilo	MIT	Редактор, сборщик, тесты и встроенные примеры.
QRCode.js 1.0.0	MIT	Встроенная генерация QR-кода.
Acorn 8.18.0	MIT	Разбор JavaScript для оптимизации.
CSS Tree 3.2.1	MIT	Разбор и сериализация CSS; включает mdn-data.
parse5 8.0.1	MIT	Разбор HTML без выполнения кода и сетевых запросов.
entities 8.0.0	BSD-2-Clause	Декодирование HTML-сущностей внутри parse5.
jsQR 1.4.0	Apache-2.0	Встроенное обратное декодирование QR.

MIT допускает личное и коммерческое использование, изменение и распространение проекта при сохранении уведомления об авторских правах и текста лицензии. Сторонние компоненты сохраняют собственные лицензии и не перелицензируются как MIT.

Подробные сведения и ссылки на исходные проекты находятся в THIRD_PARTY_NOTICES.md. Полные тексты лицензий встроенных библиотек сохранены в editor/vendor/ и внутри qr-microapps-lab.html, поэтому автономный файл можно распространять отдельно, не удаляя встроенные уведомления.