Передавання даних - пакет lolly-backup

Усе, що накопичує користувач Lolly, зберігається на його пристрої - без облікового запису, без хмари. Пакет передавання даних - це спосіб перенести це: експортуйте його на одній інсталяції, перенесіть файл будь-яким способом (USB, AirDrop, лист собі на пошту, мережевий спільний ресурс) і імпортуйте на іншій. Файл і є транспорт. Цільовий пристрій може бути офлайн або онлайн. Це не має значення, оскільки нічого й ніколи не звертається до сервера.

signed by Lolly2026-10-21vector SVG9 paths~4.9k nodes11 groups56 KBПеревірте саміОтримати підписаний файл signed by Lolly2026-10-21vector SVG9 paths~4.9k nodes11 groups56 KBПеревірте саміОтримати підписаний файл

Ця сторінка - специфікація формату. Покроковий опис для кінцевого користувача - у Знайдіть і відновіть свою роботу → Перенесіть свою роботу на інший пристрій. Реалізація - shells/web/src/data-transfer.ts, а tests/data-transfer.test.ts фіксує контракт двостороннього обміну.

Обсяг. Пакет переносить дані користувача, а не інструменти каталогу. Інструменти та ресурси каталогу синхронізуються окремо, і передбачається, що вони вже присутні на цільовому пристрої (у гіршому випадку - вищої версії); інструменти, які користувач створив самостійно, подорожують усередині profile.json. Імпорт ніколи не встановлює й не оновлює інструмент каталогу.

Цілі

• Один формат, кожна оболонка. Веб-PWA, застосунки Tauri для настільних і мобільних пристроїв та майбутні оболонки поділяють той самий конверт і підтримувані схеми частин. Необов'язкові частини залежать від можливостей кожної оболонки; непідтримувані частини повідомляються. Кожен міст можливостей надає свій адаптер сховища.
• Переживає перенесення. Пакет, пошкоджений або обрізаний під час передавання, помітно завершується невдачею при імпорті, ніколи не відновлюється наполовину.
• Переживає цю версію. Старіший застосунок усе одно може імпортувати розпізнані частини новішого пакета. Дійсно несумісний формат відхиляється чисто.
• Безпечний для злиття. Імпорт в інсталяцію, яка вже використовується, ніколи не стирає нічого, чого не було в пакеті.

Конверт

Пакунок - це звичайний .zip. Завантажений файл названо на честь особи, якій він належить, - LollyTools-<First>-<Last>-<YYYY-MM-DD>-<n>.zip (наприклад, LollyTools-Ada-Lovelace-2026-06-26-1.zip) - тож папка Downloads із резервними копіями лишається зрозумілою. Частини First і Last беруться з профілю і опускаються, якщо не задані. Без профілю виходить LollyTools-2026-06-26-1.zip, а лише з іменем - LollyTools-Ada-2026-06-26-1.zip. Кожна частина очищається до безпечного для імені файлу токена (літери й цифри Unicode зберігаються, пробіли й розділові знаки прибираються, обмеження - 32 символи). <n> - це послідовність на день і на пристрій, тож повторні експорти того самого дня не конфліктують і зберігають порядок. Ім'я формує backupFilename() у файлі shells/web/src/data-transfer.ts. Вміст zip-архіву однаковий незалежно від імені. Всередині:

Пакет навмисно є звичайним zip-архівом: він неушкоджено переживає будь-який транспорт, і будь-який засіб розпакування може його оглянути.

profile.json - найменша частина і та, яку читач бачить першою в застосунку: дані, які виробник заповнює один раз, разом зі згодою, що дозволяє інструментам їх використовувати.

signed by Lolly2026-10-21vector SVG15 paths~1.2k nodes30 groups1 image40 KBПеревірте саміОтримати підписаний файл

manifest.json

{
  "format": "lolly-backup",
  "formatVersion": 3,
  "minReader": 1,
  "app": "lolly",
  "exportedAt": "2026-06-22T09:30:00.000Z",
  "counts": { "profile": true, "sessions": 2, "userAssets": 4, "prefs": 3, "assetVersions": 1, "fileOperations": 1 },
  "integrity": {
    "profile.json": "sha256-…",
    "sessions.json": "sha256-…",
    "assets.json": "sha256-…",
    "assets/blobs/0.bin": "sha256-…",
    "file-history.json": "sha256-…",
    "file-history/versions/0.bin": "sha256-…",
    "file-history/results/0.bin": "sha256-…",
    "prefs.json": "sha256-…"
  }
}

Політика версій (пряма сумісність)

Розділення між formatVersion і minReader дозволяє формату зростати, не залишаючи старіші інсталяції осторонь:

• Читач імпортує пакет, коли manifest.minReader ≤ за його власну версію читача. Він відмовляє (з повідомленням «потрібна новіша версія застосунку») лише тоді, коли пакет явно вимагає новішого читача.
• Адитивна зміна - нова необов'язкова частина або нове необов'язкове поле маніфесту - збільшує formatVersion, але залишає minReader незмінним. Старіші застосунки все одно імпортують кожну розпізнану частину. Нерозпізнані частини пропускаються (див. нижче), а не відкидаються мовчки.
• Критична зміна - коли неправильний імпорт частини псує дані або коли раніше необов'язкова частина стає обов'язковою - підвищує minReader. Тоді старіші застосунки чисто відмовляють замість того, щоб імпортувати те, з чим не можуть впоратись.
• Якщо майбутній пакет задає formatVersion, але пропускає minReader, читачі обережно орієнтуються на formatVersion (розглядають зміну як критичну).

Правило для авторів: якщо кожен наявний читач усе одно поводитиметься правильно, просто ігноруючи ваше доповнення, - це адитивна зміна: збільшуйте formatVersion, залишайте minReader. Інакше підвищуйте minReader.

Цілісність

Коли присутнє manifest.integrity, читач перевіряє SHA-256 кожної переліченої частини перед тим, як щось записати. Невідповідність («не пройшла перевірку цілісності») або відсутня частина («неповний») перериває весь імпорт - часткового відновлення немає. Це вловлює пошкодження, яке може внести транспорт файлу (обрізаний AirDrop, поштовий шлюз, що перекодував вкладення, поганий сектор USB).

Цілісність за задумом реалізована як найкраще можливе: вона записується лише там, де доступний Web Crypto (кожен захищений контекст браузера й сучасний Node), і перевіряється лише коли присутні і карта, і Web Crypto. Пакет без карти - наприклад, створений до появи цілісності - імпортується без змін. «Неможливо перевірити» ніколи не трактується як «пошкоджено».

Маніфест не перелічує ні себе, ні перегенерований README lolly.txt. Дайджести охоплюють ті частини, за які маніфест ручається.

Семантика імпорту

Імпорт - це злиття, ніколи не повна заміна:

• Наявні дані на цільовому пристрої лишаються на місці.
• Коли слот сеансу або ідентифікатор завантаженого зображення є в обох місцях, зберігається копія, збережена пізніше, тож старіша резервна копія ніколи не перезаписує новішу роботу на цільовому пристрої. Однакові чи невідомі часові мітки зберігають копію цільового пристрою. На веб-інсталяції з історією творів те саме правило вирішує, яка копія твору лишається поточною, а інша копія зберігається як захищена чернетка (див. нижче).
• Запис профілю зливається, а не замінюється. Кожна папка на цільовому пристрої лишається зі своїм вмістом; папка з пакета, якої немає на цільовому пристрої, додається, а папка, наявна в обох місцях, зберігає назву й батьківську папку цільового пристрою та отримує відсутніх їй членів з пакета. Сеанс, поданий у папці на цільовому пристрої, лишається поданим там.
• Обране (інструменти, ресурси каталогу та елементи Проєктів) об'єднується. Шаблони, шаблони Проєктів і користувацькі інструменти з пакета додаються, коли на цільовому пристрої немає запису з таким ідентифікатором. Записи Кошика з обох джерел зберігаються, тож елемент, який можна було відновити на будь-якій інсталяції, і далі можна.
• Кожне інше поле профілю (ім'я, контактні дані, мова, прапорці функцій, приховані інструменти та інші налаштування) зберігає значення цільового пристрою. Поле, порожнє на цільовому пристрої, отримує значення з пакета. Те саме стосується prefs.json: налаштування записується лише там, де на цільовому пристрої його немає.
• Звичайне застосування синхронізації пристроїв - виняток: підтримуючи пристрої в узгодженому стані, воно бере запис профілю, налаштування, сеанси й зображення із синхронізованої копії. Відновлення попередньої копії робить те саме, оскільки воно навмисно повертається в часі. Перше приєднання, Перенести це на цей пристрій, зливає так само, як імпорт.
• Історичні версії ресурсів та ідентифікатори операцій - незмінні винятки: повторний імпорт ідемпотентний, а ідентифікатор, що вже називає інші байти чи історію, відхиляється, а не перезаписується. Повторний імпорт того самого поточного ресурсу зберігає його версію. Змінений поточний ресурс повинен мати іншу версію.
• Історія творів теж зливається. Твір, наявний з обох боків, зберігає як поточну копію, збережену пізніше, а іншу копію - як захищену чернетку; твір, чий слот на цільовому пристрої зайнятий іншим твором, додається поруч із ним; твір у Кошику цільового пристрою лишається там. Ідентифікатор контрольної точки, що на цільовому пристрої називає інший вміст, зберігає версію цільового пристрою. Архів, що не проходить власні перевірки, зупиняє імпорт до будь-якої зміни профілю, сеансу, ресурсу чи налаштувань. Ідентичний повторний імпорт не додає обсягу сховища.
• Ніщо, чого не було в пакеті, не зачіпається. Сеанс, який був на цільовому пристрої, але якого не було в пакеті, переживає імпорт.

Збережені сеанси автоматично пере-прив'язуються до своїх зображень: посилання на ресурси зберігаються за ідентифікатором, і міст повторно розв'язує їх після відновлення завантажених зображень (це необхідно в будь-якому разі, оскільки URL-адреси blob: не переживають перезавантаження).

Підсумок імпорту повідомляє { profile, sessions, userAssets, prefs, skipped, failedAssets }. failedAssets рахує завантажені ресурси, які не вдалося відновити (наприклад, сховище пристрою заповнене). Це відрізняється від skipped, яке рахує частини від сумісного з майбутнім новішого записувача, які ця збірка не розпізнала. Інтерфейс показує skipped («… · N новіших елементів пропущено»), тож відновлення чесно повідомляє, що воно залишило поза увагою.

Коли присутня історія файлів, підсумок також несе assetVersions, fileOperations і failedHistory. Вичерпання сховища чи конфлікти незмінних ідентифікаторів можуть спричинити часткове відновлення; інтерфейс каже користувачу зберегти вихідну резервну копію. Хмарна синхронізація не просуває свою застосовану ревізію після часткового чи непідтримуваного відновлення, тож знімок лишається доступним для повторної спроби. Відновлення - не єдина транзакція для всіх сховищ профілю, сеансів, ресурсів та історії.

Історія творів (v3)

Ручні резервні копії з веб-хоста, здатного на історію, включають revision-history.json із власною схемою { version: 1, documents, revisions, recoveries }. Вона несе збережені ідентифікатори, канонічні знімки вхідних даних, мітки версій, растрові попередні перегляди й окремі чернетки авторів. Адаптер історії захоплює поточні сесії та їхні голови в одній транзакції читання; sessions.json використовує ті самі поточні знімки для старіших читачів.

Відновлення перевіряє SHA-256 і кількість байтів корисного навантаження, унікальні ідентичності, зв'язки документ/голова, походження, часові мітки, типи попередніх переглядів і ліміти, перш ніж застосувати архів однією транзакцією. Ущільнені посилання на батьків можуть бути відсутні. Наявна поточна робота ніколи не замінюється мовчки: коли твір наявний з обох боків, сторона, не збережена як поточна, стає захищеною чернеткою. Ліміт передавання архіву в 384 МіБ перевіряється явно, а ліміти сховища застосовуються без обрізання збережених контрольних точок. Резервна копія загалом усе ще використовує реалізацію ZIP у пам'яті і не є потоковим архівом.

Підсумок додає revisions і recoveryDrafts, рахуючи лише те, що додав цей імпорт, а також added, kept, replaced, copies і hidden - як саме злився кожен твір. Оболонка без цієї можливості відновлює звичайні сесії й повідомляє частину історії як пропущену. Історія нативної файлової системи лишається непідтримуваною, доки її адаптер не надасть стійкі транзакції історії. Стан гостя P2P не має стійкої історії чи архіву відновлення.

Особиста синхронізація знімків явно виключає історію творів. Застосування знімка до локального документа з історією зберігає його попередній робочий стан як окрему чернетку відновлення й анулює токен запису будь-якого відкритого редактора. Його незмінні контрольні точки лишаються на пристрої. Це захищає локальну історію під час заміни знімком; це не зливає паралельні історії пристроїв.

Історичні посилання на ресурси зберігаються, тоді як рендеринг усе ще розв'язує ресурси через наявну бібліотеку призначення. Цей архів поки не гарантує точні старі байти ресурсу чи старі рендери інструмента. Байти версій ресурсів і результатів файлів і далі подорожують через свою наявну окрему частину резервної копії.

Збережені версії та результати файлів (v2)

Необов'язкова частина історії містить { version: 2, assetVersions: [...], operations: [...], batches: [...] }; читачі також приймають ранішу форму history-v1 без пакетів. Кожен знімок визначає стабільний ідентифікатор ресурсу й точну версію, час збереження, довжину в байтах і hex SHA-256, а також запис ресурсу, чиї _file та необов'язковий _credentialFile вказують на бінарні частини. Операції несуть вихідні факти файлу, запит, звіт, часові мітки й необов'язковий результат _file; назви бекендів сховища, дескриптори OPFS та оренди виконання не подорожують. Старіші читачі, що розуміють лише history-v1, відхиляють нову версію історії перед імпортом, замість того щоб мовчки відкидати належність до пакета.

Маніфести пакетів записують кожне обране джерело перед обробкою, зокрема файли, які так і не прочитано, скасованих учасників, невдачі резервування місця під результат і перервану роботу. Кожен учасник має стабільний ідентифікатор операції, посилання/факти джерела, запитану назву виводу й кінцевий звіт. Непрочитане джерело має заявлені факти, а не вигаданий дайджест. Імпорт перевіряє ідентичність учасника та узгодженість з будь-яким перенесеним звітом операції. Звіти пакета лишаються доступними, коли окремі результати явно видалено, але розписка не означає, що байти її виводу все ще зберігаються.

• Кожен відомий запис історії, звіт і файл, на який є посилання, перевіряється до будь-яких записів імпорту профілю чи ресурсів. Відсутні байти й невідповідний SHA-256 провалюють імпорт, навіть якщо конверт не має карти цілісності. Видобуті облікові дані лишаються масивами байтів, зокрема при імпорті від старіших записувачів, які серіалізували їх у JSON як об'єкти з числовими ключами.
• Операції, що виконуються, стають перерваними записами в резервній копії, з пояснювальним звітом про збій і без результату. Відновлення ніколи не перезапускає фонову роботу і не імпортує активну оренду. Повторна спроба вимагає вибору вихідного файлу, звіреного з його записаним SHA-256, коли він доступний.
• Відновлені результати фіксують свої байти й метадані разом в IndexedDB. Звичайні нові результати використовують OPFS, де це доступно, з резервним варіантом IndexedDB. Наявна активна операція ніколи не замінюється імпортом.
• Складання ZIP історії все ще відбувається в пам'яті: поточний ліміт - 256 МіБ корисного навантаження історії, 4 МіБ метаданих історії, щонайбільше 100 операцій, 100 пакетів і 2000 знімків. Експорт явно відхиляє завелику чи неповну історію; він ніколи не пропускає її мовчки. Завантажуйте важливі версії й результати окремо, перш ніж видаляти старіші локальні копії. Ці ліміти не є виміряною гарантією пікової пам'яті для телефонів.
• Локальна історія результатів має бюджет 512 МіБ і межу в 100 записів. Знімки ресурсів мають окремий бюджет 512 МіБ і щонайбільше 20 історичних версій на ресурс; видобуті байти облікових даних зараховуються до цього бюджету знімків. Відновлення дотримується цих лімітів і ніколи мовчки не витісняє наявні дані користувача.
• Локальні метадані пакетів мають окремий бюджет 4 МіБ, щонайбільше 100 маніфестів і 20 учасників на пакет. Учасники, що очікують, резервують місткість метаданих, зі стелею звіту 32 КіБ на учасника. Це логічний бюджет, а не гарантія дискового простору браузера; справжня відмова через квоту виводиться на поверхню, а звіт у пам'яті лишається доступним для завантаження. Повторна спроба з учасником пакета створює новий пакет, не перезаписуючи старий звіт. Видалення запису пакета не видаляє байти окремих результатів чи ресурси бібліотеки.
• Конвертовані результати можна явно додати в бібліотеку без нормалізації чи перекодування. Хеші джерела й виводу та зв'язок з операцією супроводжують ресурс. Повторні додавання повторно використовують незмінену копію; редаговану копію ніколи не перезаписують. Растрові зображення можуть започаткувати новий документ Design. Цей документ використовує поточний ідентифікатор ресурсу бібліотеки: забезпечення точних прив'язок версій у всій системі виконання й URL-шляху Design - усе ще окрема робота. Результати SVG/HTML/PDF/ZIP ця передача зберігає як непрозорі файлові ресурси, не підвищуючи їх до довіреного інтерактивного чи векторного вмісту.
• Convert → Recent file operations показує використання історії, звіти, завантаження й менеджер версій. Менеджер також знаходить попередні версії видалених ресурсів бібліотеки. Відновлення знімка створює нову поточну версію, зберігаючи обраний знімок незмінним. Налаштування → Сховище обліковує результати й версії окремо від видаткових кешів.
• Явне очищення тимчасових файлів видаляє лише байти, що належать операції й на які немає посилань. Поточні записи захищають свої файли; нещодавні файли OPFS мають годинний пільговий період. Збережені результати й знімки ресурсів не очищаються автоматично.

Старіші читачі й далі приймають конверт v2 (minReader: 1) і відновлюють знайомі частини, рахуючи непідтримувані частини історії як пропущені. Повне відновлення історії вимагає оболонки з адаптером fileHistory; це внутрішній шов оболонки, а не нова можливість HostV1, звернена до інструментів. Справжнє відновлення між двома пристроями покриває локальний шлюз Chromium; приймання відновлення у встановлених Tauri/iOS/Android лишається окремим.

Що не переноситься

• Кеші каталогу (завантажені метадані ресурсів і бінарні дані, індекс інструментів) - безкоштовно повторно синхронізуються на цільовому пристрої.
• Інструменти та ресурси бренду - поза межами охоплення, і передбачається, що вже присутні на цільовому пристрої. Токени бренду, шрифти й логотипи, додані користувачем, - це ресурси користувача, тож вони подорожують.
• URL-адреси blob: / об'єктні URL - перегенеровуються мостом при завантаженні.
• Оригінали конвертації, активні оренди виконання та машинно-локальні секрети доступу чи підписування - не портативне корисне навантаження історії. Збережений результат - це копія, а не обіцянка, що вихідне джерело було збережено в резервній копії.
• Лічильник послідовності експорту - лічильник іменування завантажень за день (ключ localStorage lolly-export-seq) - це локальна зручність іменування. Він виведений за межі PREF_KEYS, тому ніколи не потрапляє в пакет.

Індикатор сховища деталізує той самий розподіл. Збережені сеанси, My images та File results & versions потрапляють у пакет. Кеш ресурсів, попередні перегляди інструментів та офлайн-закріплення нижче них усі відновлювані заново, тому лишаються осторонь.

signed by Lolly2026-10-21vector SVG37 paths~4.9k nodes85 groups65 KBПеревірте саміОтримати підписаний файл signed by Lolly2026-10-21vector SVG37 paths~4.9k nodes85 groups65 KBПеревірте саміОтримати підписаний файл

Гарантія міжоболонкової сумісності

data-transfer.ts читає та записує виключно через міст можливостей (host.profile, host.state, host.assets) і спільні налаштування localStorage. Той самий модуль читає та записує спільний конверт у вебі та Tauri, через сховище IndexedDB чи файлової системи. Необов'язкові частини історії з'являються лише там, де доступний відповідний адаптер; непідтримувана частина повідомляється як пропущена при імпорті. Безголовий набір тестів перевіряє спільні частини проти моста в пам'яті, тоді як транзакції історії також мають тести в реальному браузері.

Дві оболонки виходять за межі цієї гарантії, з різних причин:

• Одноразовий CLI не має що переносити - його стан перебуває в пам'яті і зникає після кожного виклику.
• TUI справді зберігає стан (~/.lolly: сесії, теки, профіль), і його представлення Profile може створювати резервну копію, але записує простіший власний архів: saved-state/<slot>.json для кожної сесії плюс profile.json і folders.json, без маніфесту, без formatVersion/minReader і без карти цілісності. Він не імпортується в цьому форматі - зчитувач відхиляє його як "не резервна копія Lolly" - і, заплутуючи, використовує схожу назву (lolly-backup-<stamp>.zip). Об'єднання цих двох - відома прогалина.

Зарезервовані точки розширення

Конверт за задумом - це маніфест плюс набір іменованих частин, щоб нові види портованих даних могли долучитися пізніше без критичних змін. Вони вбудовуються як додаткові частини (нова formatVersion, той самий minReader), і сьогоднішній зчитувач пропускає те, чого не розпізнає. Це ще не реалізовано. Назви зарезервовано тут, щоб формат лишався узгодженим, коли вони з'являться.

• tokens.json - токени дизайну. Документ токенів дизайну W3C DTCG (формат, який імпортує й експортує Penpot - токени з $value/$type/$description, організовані в групи, набори та теми). Набір токенів у пакеті дозволяє користувачу переносити примітиви свого бренду між інсталяціями разом із сесіями. (Власні токени бренду користувача вже подорожують сьогодні як ресурс user/tokens/brand у assets.json; ця частина нестиме цілий документ DTCG з його наборами та темами.) У перспективі імпортований набір токенів стане повноцінним джерелом, проти якого інструменти й активи палітри виконуватимуть звірку.
• penpot/ - імпортовані файли Penpot. Зарезервований каталог для файлу Penpot (або його вилученої, релевантної для Lolly підмножини), імпортованого й представленого як інструмент. Пакет нестиме імпортоване визначення, тож воно подорожуватиме разом з рештою даних користувача.

Усе поза цими зарезервованими назвами та частинами вище є для зчитувача невідомою частиною: залишається незміненим і враховується в skipped.

Довідка

• Модуль: shells/web/src/data-transfer.ts (exportBackup, importBackup, BACKUP_FORMAT, BACKUP_FORMAT_VERSION, BACKUP_READER_VERSION - іменувач backupFilename() внутрішній).
• Контрактний тест: tests/data-transfer.test.ts - випадки циклу туди-й-назад, злиття, цілісності, зворотної сумісності та шлюзу зчитувача.
• Контрактні тести історії: tests/file-history-backup.test.ts, tests/file-batch-history.test.ts і tests/file-result-library.test.ts. Приймання в браузері: tests/file-history.browser.test.ts, tests/file-batch-history.browser.test.ts і tests/file-result-reuse.browser.test.ts.
• Використана поверхня моста: host.profile, host.state, host.assets - див. Host API.