@despia/local 1.0.8 → 1.0.9

package/README.md

@@ -15,12 +15,33 @@ Universal build plugin to generate `despia/local.json` manifest for [Despia](htt
 - **Sorted Output** - Alphabetically sorted paths for consistent builds
 - **Standalone Script** - Can be used with any build system via CLI
 
+## Setup
+
+> **No changes to your hosting.** Add this build plugin to your existing setup, deploy your web app, then enable the feature in Despia.
+
+1. Add the plugin to your build configuration (see [Framework Support](#framework-support)).
+2. Deploy your web app — the plugin generates `despia/local.json` alongside your existing build output.
+3. In Despia: **Open your project → Settings → Local Server → Enable**.
+
+**Prerequisite:** The local server can only be enabled after the plugin is added and your web app has been fully deployed with the generated manifest. Until then, the option will not be available.
+
 ## About Despia's Local Server
 
 **Note**: Despia's local server is optional. Normally, the Despia runtime can run your web app directly from a URL. Despia's local server is for developers who need extra performance and full true native offline support.
 
 Despia's local server enables your web app to run entirely from a local HTTP server on-device, providing a native app experience with full offline functionality.
 
+### Ownership & Control
+
+The local server provides an OTA-capable system with a **secure origin** (`http://localhost`) and **full web API access**. It supports local-first apps, offline-capable apps, and apps requiring improved performance. The deployment pipeline remains under your control:
+
+- **No MAU fees** — No per-user or usage-based charges
+- **No proprietary OTA hosting** — Deploy assets to any host (CDN, Vercel, Netlify, or your own infrastructure)
+- **Fully client-side** — The update logic runs entirely on the client; no dedicated OTA backend required
+- **Pipeline control** — Integrate with your existing build and deployment workflow
+
+Updates do not depend on third-party OTA infrastructure. The system runs entirely client-side, providing high reliability with update latency comparable to cloud-based solutions. Local assets are served from the local assets stored on the native file system; network requests occur only when a new deployment is detected.
+
 ### Architecture
 
 The Despia native container consists of:
@@ -80,6 +101,21 @@ When connectivity is available, Despia checks for updates in the background and
 
 **Important**: Updates only change web content (HTML, CSS, JavaScript). Native code, permissions, and app functionality remain unchanged from the original App Store/Play Store submission.
 
+### Smart OTA Cache System
+
+> **Role of `deployed_at` in conditional update logic**
+
+On startup, the client fetches `despia/local.json` and compares `deployed_at` with the cached value to determine whether a full asset download is required:
+
+| Scenario | Behavior |
+|----------|----------|
+| **Good connection** | Fetch manifest and compare `deployed_at` to cached value |
+| **`deployed_at` changed** | New deployment detected → download all assets → set as active app source |
+| **`deployed_at` unchanged** | Serve from existing local cache; no download |
+| **Poor or no connection** | Serve from offline cache; defer manifest check until connectivity improves |
+
+This approach minimizes network requests while preserving OTA update capability. The `deployed_at` field acts as a lightweight change indicator; a full asset download is performed only when it has changed.
+
 ### Store Compliance & Security
 
 **Compliance Summary for App Reviewers:**
@@ -648,6 +684,7 @@ The generated `despia/local.json` file contains an object with the entry HTML pa
 ```json
 {
   "entry": "/index.html",
+  "deployed_at": "1737225600000",
   "assets": [
     "/index.html",
     "/assets/app.abc123.css",
@@ -658,6 +695,7 @@ The generated `despia/local.json` file contains an object with the entry HTML pa
 ```
 
 - **`entry`**: The entry HTML file path (e.g., `/index.html`). **Required** - Local apps always need an entry point for client-side rendering. The entry path is also included in the `assets` array (unless `skipEntryHtml` is enabled).
+- **`deployed_at`**: Timestamp in milliseconds (as string) when the manifest was generated. Updated on every deployment.
 - **`assets`**: A sorted array of all asset paths, **including the entry file**. When `skipEntryHtml` is enabled, the entry is still required in the manifest but won't be included in the `assets` array.
 
 ## Examples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@despia/local",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Universal build plugin to generate despia/local.json manifest for offline caching in Despia web-native apps. Supports Vite, Webpack, Rollup, Nuxt, SvelteKit, Astro, Remix, esbuild, Parcel, and more.",
   "type": "module",
   "main": "./src/core.js",

package/src/core.js

@@ -95,6 +95,7 @@ export function generateManifest({ outputDir, entryHtml = 'index.html', addition
   // Create manifest object (entry is always required for local client-side apps)
   const manifest = {
     entry: entryPath,
+    deployed_at: String(Date.now()),
     assets: assets
   };
   

package/src/webpack.js

@@ -110,6 +110,7 @@ class DespiaLocalPlugin {
         
         const manifestObj = {
           entry: entryPath,
+          deployed_at: String(Date.now()),
           assets: assetList
         };
         const manifest = JSON.stringify(manifestObj, null, 2);