@despia/local 1.0.7 → 1.0.9

package/README.md

@@ -4,7 +4,7 @@ Universal build plugin to generate `despia/local.json` manifest for [Despia](htt
 
 **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.
 
-**Store Compliant**: Despia's local server is fully compliant with Apple App Store and Google Play Store guidelines. It downloads and caches web content (HTML, CSS, JavaScript) for offline display in a WebView—identical to how web browsers work. No native code or executables are downloaded. See [Store Compliance & Security](#store-compliance--security) section for detailed compliance information.
+**Store Compliant**: Despia's local server is fully compliant with Apple App Store and Google Play Store guidelines. It downloads and caches web content (HTML, CSS, JavaScript) for offline display in a WebView - identical to how web browsers work. No native code or executables are downloaded. See [Store Compliance & Security](#store-compliance--security) section for detailed compliance information.
 
 ## Features
 
@@ -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:**
@@ -155,7 +191,7 @@ Despia's local server complies with this guideline because:
    - Binary behavior
    - System integration
 
-   **However**, the web UI can be updated to use existing native APIs in new ways. For example, if Face ID is already implemented in the native code and exposed through the WebView bridge, the web UI can be updated to call Face ID from new parts of the app. This is compliant because the native capability already exists in the submitted binary—only the web UI's usage of it changes.
+   **However**, the web UI can be updated to use existing native APIs in new ways. For example, if Face ID is already implemented in the native code and exposed through the WebView bridge, the web UI can be updated to call Face ID from new parts of the app. This is compliant because the native capability already exists in the submitted binary - only the web UI's usage of it changes.
 
    **Note**: This follows the same pattern as [Expo](https://expo.dev), which has been generally accepted by app stores. However, Apple's interpretation of "feature changes" under Guideline 3.3.2 is subjective, and your app could still face review challenges. It's recommended to be conservative with updates that significantly change app behavior, even when using existing native APIs.
 
@@ -183,7 +219,7 @@ Despia's local server complies with this policy because:
 
 4. **Sandboxed Execution**: All web content executes within the WebView's security sandbox, with permissions and capabilities fixed at APK submission time.
 
-   **However**, the web UI can be updated to use existing native APIs in new ways. For example, if biometric authentication is already implemented in the native code and exposed through the WebView bridge, the web UI can be updated to call it from new parts of the app. This is compliant because the native capability already exists in the submitted APK—only the web UI's usage of it changes.
+   **However**, the web UI can be updated to use existing native APIs in new ways. For example, if biometric authentication is already implemented in the native code and exposed through the WebView bridge, the web UI can be updated to call it from new parts of the app. This is compliant because the native capability already exists in the submitted APK - only the web UI's usage of it changes.
 
 **This approach is explicitly permitted** under Play Store policies, as evidenced by:
 - Chrome and other browsers rendering web content
@@ -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.7",
+  "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);