void-offline-first-mutation

Implements offline-tolerant UI mutations using an IndexedDB capture-queue with idempotency keys and retry.

Updated May 29, 2026
One-click install
npx skills add https://github.com/voidcorp-core/void-harness --skill void-offline-first-mutation-voidcorp-core
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: void-offline-first-mutation
Source: https://github.com/voidcorp-core/void-harness/tree/main/packages/cli/core-assets/packs/pack-pwa/skills/void-offline-first-mutation
Command: npx skills add https://github.com/voidcorp-core/void-harness --skill void-offline-first-mutation-voidcorp-core

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires idb.

What problem does it solve? User-triggered writes in a PWA fail or silently lose data when the device is offline, on flaky wifi, or when the browser crashes mid-submission. This Skill provides a capture-queue + sync pattern so mutations are persisted locally, applied optimistically, and reconciled with the server when connectivity returns. ## Core Features & Use Cases - Durable capture-queue: Persists each mutation intent to IndexedDB before the UI confirms, so a browser crash never loses user input. - Idempotent sync engine: Each intent carries a client-generated UUID idempotency key, with status transitions (pending, syncing, committed, failed), exponential backoff from 2s to 4h, and a dead-letter UI for failed intents. - Server-side idempotency: Shows the inbox pattern for Server Actions that honor idempotency keys, plus server-wins conflict resolution. - Use Case: A field technician on mobile submits a form in a subway tunnel; the note appears instantly in the list via optimistic update, the intent is queued in IndexedDB, and it syncs automatically when the device comes back online. ## Quick Start Ask the agent to implement an offline-first mutation for a user-triggered write such as creating a note, using the capture-queue and sync pattern with an idempotency key.

Frequently Asked Questions about void-offline-first-mutation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make a form submission work offline in a PWA?

Persist the mutation as an intent in an IndexedDB capture-queue before updating the UI optimistically, then run a background sync that replays pending intents when connectivity returns. Each intent carries a client-generated idempotency key so retries are safe.

How do I implement idempotency keys for offline mutations?

Generate a UUID on the client when the intent is created and send it as the idempotencyKey with every sync attempt. On the server, check for an existing record with that key before inserting, returning the existing row on redelivery, and enforce a unique index on the column.

Should I use React Query or a capture-queue for offline writes?

Pick one per concern: use React Query for reads and the capture-queue for offline-tolerant writes. Mixing both for mutations creates conflicting retry and cache semantics, so the pattern explicitly separates them.

How are conflicts resolved when offline edits clash with server state?

The server wins. For field-level conflicts the server response overwrites the optimistic local state; for validation rejections the intent is marked failed and surfaced to the user. Richer reconciliation with CRDTs like Yjs or Automerge is explicitly out of scope.

What happens to mutations that keep failing to sync?

Retries follow a backoff schedule from 2 seconds up to 4 hours, after which the intent is marked failed. Failed intents appear in a dead-letter UI where the user can retry, edit and resubmit, or delete them; they are never silently dropped.