@strata-ds/core 2.1.6 → 2.1.17

package/README.md

@@ -526,6 +526,63 @@ const MyComponent = StrataComponentFactory.createComponent(
 );
 ```
 
+## Offline Resilience & Build-Time Fallbacks
+
+`@strata-ds/core` is built to be completely resilient to network outages, CDN downtime, or slow connections using a multi-layered fallback strategy.
+
+### How It Works (The 4 Layers of Defense)
+
+1. **Static CSS Fallbacks (No-JS / Instant Load)**: Design tokens are pre-rendered into a plain CSS file (`strata-fallbacks.css`) containing direct `:root` custom property assignments. This stylesheet loads statically before React boots, ensuring the page never flickers or appears unstyled.
+2. **Instant React Hydration (`initialData`)**: When the React application mounts, `StrataProvider` initializes with the local snapshot JSON file, allowing it to render immediately with real values without waiting for a CDN fetch.
+3. **Automatic `localStorage` Cache (Fallback)**: If the app is online, the SDK automatically caches successful live sync updates to `localStorage`. If a user reloads the page while offline, the SDK retrieves the last-known-good cache.
+4. **ETag Delta Sync (Bandwidth Optimization)**: Live sync requests include an `If-None-Match` conditional header. If nothing changed, the CDN returns a `304 Not Modified` with no body payload—minimizing data usage to ~0 bytes per poll.
+
+---
+
+### Step-by-Step Setup Guide
+
+Any project using the Strata Design System can enable full offline resilience in three quick steps:
+
+#### Step 1: Generate the Local Snapshot and Fallback CSS
+Run the CLI snapshot tool locally or add it to your project's build process:
+```bash
+npx strata-ds snapshot \
+  --project-id "YOUR_PROJECT_ID" \
+  --cdn-base "https://your-cdn-base-url.cloudfront.net" \
+  --output "./src/data/strata-snapshot.json" \
+  --output-css "./src/styles/strata-fallbacks.css" \
+  --variables-only
+```
+*(Commit the generated JSON and CSS files to your Git repository as your baseline fallback).*
+
+#### Step 2: Import Fallback Styles
+Reference the CSS file in your main style entry point (e.g., `src/index.css` or `src/App.css`):
+```css
+@import './styles/strata-fallbacks.css';
+```
+
+#### Step 3: Configure StrataProvider
+Import the snapshot and configure your `StrataProvider`:
+```tsx
+import React from 'react';
+import { StrataProvider } from '@strata-ds/core';
+import strataSnapshot from './data/strata-snapshot.json';
+
+export default function App() {
+  return (
+    <StrataProvider
+      initialData={strataSnapshot}
+      syncEnabled={true}
+      projectId="YOUR_PROJECT_ID"
+      snapshotCdnBase="https://your-cdn-base-url.cloudfront.net"
+      syncInterval={5000}
+    >
+      <MainLayout />
+    </StrataProvider>
+  );
+}
+```
+
 ## Key Features
 
 - 🔁 Live sync with Strata backend

package/dist/cli/snapshot.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/snapshot.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+function printHelp() {
+    console.log(`
+Strata Design System Snapshot CLI
+
+Usage:
+  npx strata-ds [options]
+
+Options:
+  --project-id       Strata Project ID (required)
+  --cdn-base         CDN base URL (e.g. https://dx2nhw7wqn4nn.cloudfront.net) (required)
+  --output           Path to write the snapshot JSON file (optional)
+  --output-css       Path to write the CSS fallback file (optional)
+  --sync-token       Authorization Sync Token (optional)
+  --variables-only   Only output variables in the snapshot JSON (optional)
+  --help, -h         Show help
+`);
+}
+async function run() {
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+        printHelp();
+        process.exit(0);
+    }
+    const getArgValue = (flag) => {
+        const idx = args.indexOf(flag);
+        if (idx !== -1 && idx + 1 < args.length) {
+            return args[idx + 1];
+        }
+        return undefined;
+    };
+    const hasFlag = (flag) => {
+        return args.includes(flag);
+    };
+    const projectId = getArgValue('--project-id');
+    const cdnBase = getArgValue('--cdn-base');
+    const outputPath = getArgValue('--output');
+    const outputCssPath = getArgValue('--output-css');
+    const syncToken = getArgValue('--sync-token');
+    const variablesOnly = hasFlag('--variables-only');
+    if (!projectId || !cdnBase) {
+        console.error('❌ Error: --project-id and --cdn-base are required.');
+        printHelp();
+        process.exit(1);
+    }
+    const base = cdnBase.replace(/\/+$/, '');
+    const snapshotUrl = base.endsWith('/snapshots')
+        ? `${base}/${projectId}/strata.json`
+        : `${base}/snapshots/${projectId}/strata.json`;
+    console.log(`📡 Fetching snapshot from: ${snapshotUrl}`);
+    try {
+        const headers = {};
+        if (syncToken) {
+            headers['Authorization'] = `Bearer ${syncToken}`;
+        }
+        const res = await fetch(snapshotUrl, { headers });
+        if (!res.ok) {
+            throw new Error(`Server returned ${res.status} ${res.statusText}`);
+        }
+        const data = await res.json();
+        // Validate shape
+        if (!data || typeof data !== 'object' || typeof data.variables !== 'object') {
+            throw new Error('Invalid snapshot response shape: missing variables');
+        }
+        let snapshotJson = data;
+        if (variablesOnly) {
+            snapshotJson = {
+                variables: data.variables,
+            };
+        }
+        // Write JSON output if requested
+        if (outputPath) {
+            const resolvedOutput = path.resolve(outputPath);
+            fs.mkdirSync(path.dirname(resolvedOutput), { recursive: true });
+            fs.writeFileSync(resolvedOutput, JSON.stringify(snapshotJson, null, 2), 'utf-8');
+            console.log(`✅ Snapshot JSON written to: ${resolvedOutput}`);
+        }
+        // Write CSS output if requested
+        if (outputCssPath) {
+            const resolvedCssOutput = path.resolve(outputCssPath);
+            fs.mkdirSync(path.dirname(resolvedCssOutput), { recursive: true });
+            let cssContent = `/* @strata-ds/core — Auto-generated CSS fallback variables\n`;
+            cssContent += ` * Project: ${projectId}\n`;
+            cssContent += ` * Generated: ${new Date().toISOString()}\n`;
+            cssContent += ` * DO NOT EDIT MANUALLY — regenerate with CLI snapshot tool\n`;
+            cssContent += ` */\n\n`;
+            cssContent += `:root {\n`;
+            const variables = data.variables || {};
+            for (const [key, val] of Object.entries(variables)) {
+                const resolvedVal = val.resolvedValue ?? val.value;
+                cssContent += `  ${key}: ${resolvedVal};\n`;
+            }
+            cssContent += `}\n`;
+            fs.writeFileSync(resolvedCssOutput, cssContent, 'utf-8');
+            console.log(`✅ CSS fallback written to: ${resolvedCssOutput}`);
+        }
+    }
+    catch (error) {
+        console.warn(`⚠️ Warning: Fetch failed: ${error.message || error}`);
+        // If fetch failed, check if output files already exist to degrade gracefully (exit 0)
+        let jsonExists = false;
+        let cssExists = false;
+        if (outputPath && fs.existsSync(path.resolve(outputPath))) {
+            jsonExists = true;
+        }
+        if (outputCssPath && fs.existsSync(path.resolve(outputCssPath))) {
+            cssExists = true;
+        }
+        const requestedOutputs = [];
+        if (outputPath)
+            requestedOutputs.push('JSON');
+        if (outputCssPath)
+            requestedOutputs.push('CSS');
+        const existingOutputs = [];
+        if (jsonExists)
+            existingOutputs.push('JSON');
+        if (cssExists)
+            existingOutputs.push('CSS');
+        if (requestedOutputs.length > 0 && requestedOutputs.length === existingOutputs.length) {
+            console.warn(`ℹ️ Existing output file(s) found. Graceful degradation: exiting 0.`);
+            process.exit(0);
+        }
+        else {
+            console.error('❌ Error: Fetch failed and no existing local outputs found to fall back on.');
+            process.exit(1);
+        }
+    }
+}
+run();

package/dist/data/mock.types.d.ts

@@ -7,6 +7,7 @@ export type DesignToken = {
     comment: string;
     category?: string;
     deprecated?: boolean;
+    resolvedValue?: string;
 };
 export type ComponentProperty = {
     value: string;

package/dist/index.d.ts

@@ -11,6 +11,7 @@ type DesignToken = {
     comment: string;
     category?: string;
     deprecated?: boolean;
+    resolvedValue?: string;
 };
 type ComponentProperty = {
     value: string;
@@ -87,6 +88,8 @@ interface StrataContextType {
     syncToken: string | undefined;
     snapshotCdnBase: string | undefined;
     projectId: string | undefined;
+    dataSource: "live" | "cache" | "initial" | "empty";
+    cacheAge: number | null;
 }
 declare const useStrata: () => StrataContextType;
 interface StrataProviderProps {
@@ -133,6 +136,16 @@ interface StrataProviderProps {
      * Use this to show a loading indicator or log sync lifecycle events.
      */
     onSyncStart?: () => void;
+    /**
+     * Whether to persist and restore cached snapshot to/from localStorage.
+     * Defaults to true.
+     */
+    persistCache?: boolean;
+    /**
+     * Whether to automatically inject design system variables into document.documentElement.
+     * Defaults to true.
+     */
+    injectCssVars?: boolean;
 }
 declare const StrataProvider: React__default.FC<StrataProviderProps>;
 

package/dist/index.esm.js

@@ -1113,35 +1113,103 @@ var StrataProvider = function StrataProvider(_ref) {
     projectId = _ref.projectId,
     onSyncError = _ref.onSyncError,
     onSyncSuccess = _ref.onSyncSuccess,
-    onSyncStart = _ref.onSyncStart;
-  var _useState = useState(userDesignSystem || initialData || {
-      variables: {},
-      components: {},
-      custom: {
-        variables: {},
-        components: {}
+    onSyncStart = _ref.onSyncStart,
+    _ref$persistCache = _ref.persistCache,
+    persistCache = _ref$persistCache === void 0 ? true : _ref$persistCache,
+    _ref$injectCssVars = _ref.injectCssVars,
+    injectCssVars = _ref$injectCssVars === void 0 ? true : _ref$injectCssVars;
+  var _useState = useState(function () {
+      if (userDesignSystem) return "initial";
+      if (initialData) return "initial";
+      if (persistCache && projectId) {
+        if (typeof window !== "undefined") {
+          try {
+            var cached = localStorage.getItem("strata-cache-".concat(projectId));
+            if (cached) return "cache";
+          } catch (e) {}
+        }
       }
+      return "empty";
     }),
     _useState2 = _slicedToArray(_useState, 2),
-    designSystem = _useState2[0],
-    setDesignSystem = _useState2[1];
-  var _useState3 = useState("idle"),
+    dataSource = _useState2[0],
+    setDataSource = _useState2[1];
+  var _useState3 = useState(function () {
+      if (userDesignSystem || initialData) return Date.now();
+      if (persistCache && projectId) {
+        if (typeof window !== "undefined") {
+          try {
+            var ts = localStorage.getItem("strata-cache-ts-".concat(projectId));
+            if (ts) {
+              var parsed = Number.parseInt(ts, 10);
+              if (Number.isFinite(parsed)) return parsed;
+            }
+          } catch (e) {}
+        }
+      }
+      return null;
+    }),
     _useState4 = _slicedToArray(_useState3, 2),
-    syncStatus = _useState4[0],
-    setSyncStatus = _useState4[1];
-  var _useState5 = useState(null),
+    dataTimestamp = _useState4[0],
+    setDataTimestamp = _useState4[1];
+  var _useState5 = useState(function () {
+      if (userDesignSystem) return userDesignSystem;
+      if (initialData) return initialData;
+      if (persistCache && projectId) {
+        if (typeof window !== "undefined") {
+          try {
+            var cached = localStorage.getItem("strata-cache-".concat(projectId));
+            if (cached) {
+              var parsed = JSON.parse(cached);
+              if (parsed && parsed.variables && parsed.components) {
+                return parsed;
+              }
+            }
+          } catch (e) {}
+        }
+      }
+      return {
+        variables: {},
+        components: {},
+        custom: {
+          variables: {},
+          components: {}
+        }
+      };
+    }),
     _useState6 = _slicedToArray(_useState5, 2),
-    lastSynced = _useState6[0],
-    setLastSynced = _useState6[1];
-  var _useState7 = useState(0),
+    designSystem = _useState6[0],
+    setDesignSystem = _useState6[1];
+  var _useState7 = useState("idle"),
     _useState8 = _slicedToArray(_useState7, 2),
-    syncVersion = _useState8[0],
-    setSyncVersion = _useState8[1];
+    syncStatus = _useState8[0],
+    setSyncStatus = _useState8[1];
+  var _useState9 = useState(function () {
+      if (typeof window !== "undefined" && persistCache && projectId) {
+        try {
+          var ts = localStorage.getItem("strata-cache-ts-".concat(projectId));
+          if (ts) {
+            var parsed = Number.parseInt(ts, 10);
+            if (Number.isFinite(parsed)) return new Date(parsed);
+          }
+        } catch (e) {}
+      }
+      return null;
+    }),
+    _useState0 = _slicedToArray(_useState9, 2),
+    lastSynced = _useState0[0],
+    setLastSynced = _useState0[1];
+  var _useState1 = useState(0),
+    _useState10 = _slicedToArray(_useState1, 2),
+    syncVersion = _useState10[0],
+    setSyncVersion = _useState10[1];
   // Ref that tracks the JSON string of the last successfully synced payload so
   // that syncDesignSystem does not need to close over the designSystem state
   // value. This keeps the callback stable and prevents the polling interval
   // from being continuously reset after each successful sync.
   var lastSyncedStringRef = useRef(null);
+  // Ref to track the ETag of the last fetched snapshot
+  var lastETagRef = useRef(null);
   // Refs for lifecycle callbacks so that syncDesignSystem does not need to
   // close over them. Inline functions passed by the consumer (e.g. anonymous
   // arrow functions) would otherwise change identity on every render, forcing
@@ -1178,7 +1246,7 @@ var StrataProvider = function StrataProvider(_ref) {
   }, []);
   var syncDesignSystem = useCallback(/*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
     var _onSyncStartRef$curre;
-    var headers, remoteData, res, _onSyncErrorRef$curre, data, _onSyncErrorRef$curre2, _yield$Promise$all, _yield$Promise$all2, variablesRes, componentsRes, customRes, _yield$Promise$all3, _yield$Promise$all4, variables, components, custom, newDataString, _onSyncSuccessRef$cur, _onSyncErrorRef$curre3, _t;
+    var headers, remoteData, res, _onSyncErrorRef$curre, etag, data, _onSyncErrorRef$curre2, _yield$Promise$all, _yield$Promise$all2, variablesRes, componentsRes, customRes, _yield$Promise$all3, _yield$Promise$all4, variables, components, custom, newDataString, _onSyncSuccessRef$cur, _onSyncErrorRef$curre3, _t;
     return _regenerator().w(function (_context) {
       while (1) switch (_context.p = _context.n) {
         case 0:
@@ -1195,19 +1263,30 @@ var StrataProvider = function StrataProvider(_ref) {
             Authorization: "Bearer ".concat(syncToken)
           } : {};
           if (!snapshotUrl) {
-            _context.n = 8;
+            _context.n = 9;
             break;
           }
+          if (lastETagRef.current) {
+            headers["If-None-Match"] = lastETagRef.current;
+          }
+          // Single CDN snapshot fetch — edge-cached, 1 request per poll
           _context.n = 3;
           return fetch(snapshotUrl, {
             headers: headers
           });
         case 3:
           res = _context.v;
-          if (!(!res.ok && res.status >= 400 && res.status < 500)) {
+          if (!(res.status === 304)) {
             _context.n = 4;
             break;
           }
+          setSyncStatus("idle");
+          return _context.a(2);
+        case 4:
+          if (!(!res.ok && res.status >= 400 && res.status < 500)) {
+            _context.n = 5;
+            break;
+          }
           setSyncStatus("error");
           (_onSyncErrorRef$curre = onSyncErrorRef.current) === null || _onSyncErrorRef$curre === void 0 || _onSyncErrorRef$curre.call(onSyncErrorRef, {
             code: res.status,
@@ -1215,19 +1294,23 @@ var StrataProvider = function StrataProvider(_ref) {
             source: "cdn"
           });
           return _context.a(2);
-        case 4:
+        case 5:
           if (res.ok) {
-            _context.n = 5;
+            _context.n = 6;
             break;
           }
           throw new Error("Snapshot fetch failed: ".concat(res.status));
-        case 5:
-          _context.n = 6;
-          return res.json();
         case 6:
+          etag = res.headers.get("ETag");
+          if (etag) {
+            lastETagRef.current = etag;
+          }
+          _context.n = 7;
+          return res.json();
+        case 7:
           data = _context.v;
           if (!(!data || _typeof(data) !== "object" || Array.isArray(data) || _typeof(data.variables) !== "object" || data.variables === null || Array.isArray(data.variables) || _typeof(data.components) !== "object" || data.components === null || Array.isArray(data.components))) {
-            _context.n = 7;
+            _context.n = 8;
             break;
           }
           console.warn("[strata] Invalid snapshot shape received from CDN — skipping update.");
@@ -1238,7 +1321,7 @@ var StrataProvider = function StrataProvider(_ref) {
             source: "cdn"
           });
           return _context.a(2);
-        case 7:
+        case 8:
           remoteData = {
             variables: data.variables,
             components: data.components,
@@ -1251,10 +1334,10 @@ var StrataProvider = function StrataProvider(_ref) {
           // ComponentNode shape so that useDynamicComponents and the registry
           // always receive consistently-shaped data.
           remoteData = normalizeComponents(remoteData);
-          _context.n = 14;
+          _context.n = 15;
           break;
-        case 8:
-          _context.n = 9;
+        case 9:
+          _context.n = 10;
           return Promise.all([fetch("".concat(syncUrl, "/variables"), {
             headers: headers
           }), fetch("".concat(syncUrl, "/components"), {
@@ -1262,33 +1345,33 @@ var StrataProvider = function StrataProvider(_ref) {
           }), fetch("".concat(syncUrl, "/custom"), {
             headers: headers
           })]);
-        case 9:
+        case 10:
           _yield$Promise$all = _context.v;
           _yield$Promise$all2 = _slicedToArray(_yield$Promise$all, 3);
           variablesRes = _yield$Promise$all2[0];
           componentsRes = _yield$Promise$all2[1];
           customRes = _yield$Promise$all2[2];
           if (variablesRes.ok) {
-            _context.n = 10;
+            _context.n = 11;
             break;
           }
           throw new Error("Variables fetch failed: ".concat(variablesRes.status));
-        case 10:
+        case 11:
           if (componentsRes.ok) {
-            _context.n = 11;
+            _context.n = 12;
             break;
           }
           throw new Error("Components fetch failed: ".concat(componentsRes.status));
-        case 11:
+        case 12:
           if (customRes.ok) {
-            _context.n = 12;
+            _context.n = 13;
             break;
           }
           throw new Error("Custom fetch failed: ".concat(customRes.status));
-        case 12:
-          _context.n = 13;
-          return Promise.all([variablesRes.json(), componentsRes.json(), customRes.json()]);
         case 13:
+          _context.n = 14;
+          return Promise.all([variablesRes.json(), componentsRes.json(), customRes.json()]);
+        case 14:
           _yield$Promise$all3 = _context.v;
           _yield$Promise$all4 = _slicedToArray(_yield$Promise$all3, 3);
           variables = _yield$Promise$all4[0];
@@ -1306,7 +1389,7 @@ var StrataProvider = function StrataProvider(_ref) {
           // ComponentNode shape so that useDynamicComponents and the registry
           // always receive consistently-shaped data.
           remoteData = normalizeComponents(remoteData);
-        case 14:
+        case 15:
           // Only update if data actually changed (compared against the last synced
           // snapshot via ref, so this callback stays stable across renders).
           newDataString = JSON.stringify(remoteData);
@@ -1319,14 +1402,22 @@ var StrataProvider = function StrataProvider(_ref) {
             });
             setSyncStatus("success");
             setLastSynced(new Date());
+            setDataSource("live");
+            setDataTimestamp(Date.now());
+            if (persistCache && projectId) {
+              try {
+                localStorage.setItem("strata-cache-".concat(projectId), newDataString);
+                localStorage.setItem("strata-cache-ts-".concat(projectId), Date.now().toString());
+              } catch (e) {}
+            }
             (_onSyncSuccessRef$cur = onSyncSuccessRef.current) === null || _onSyncSuccessRef$cur === void 0 || _onSyncSuccessRef$cur.call(onSyncSuccessRef, remoteData);
           } else {
             setSyncStatus("idle");
           }
-          _context.n = 16;
+          _context.n = 17;
           break;
-        case 15:
-          _context.p = 15;
+        case 16:
+          _context.p = 16;
           _t = _context.v;
           console.error("❌ Sync failed:", _t);
           setSyncStatus("error");
@@ -1335,11 +1426,11 @@ var StrataProvider = function StrataProvider(_ref) {
             message: _t instanceof Error ? _t.message : String(_t),
             source: snapshotUrl ? "cdn" : "sync"
           });
-        case 16:
+        case 17:
           return _context.a(2);
       }
-    }, _callee, null, [[2, 15]]);
-  })), [syncEnabled, syncUrl, syncToken, snapshotUrl, normalizeComponents]);
+    }, _callee, null, [[2, 16]]);
+  })), [syncEnabled, syncUrl, syncToken, snapshotUrl, normalizeComponents, persistCache, projectId]);
   // Force sync function for manual triggering
   var forceSync = useCallback(/*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
     return _regenerator().w(function (_context2) {
@@ -1428,13 +1519,37 @@ var StrataProvider = function StrataProvider(_ref) {
       xl: ((_designSystem$variabl24 = designSystem.variables["--shadow-xl"]) === null || _designSystem$variabl24 === void 0 ? void 0 : _designSystem$variabl24.value) || "0 20px 25px -5px rgba(0, 0, 0, 0.1)"
     }
   });
+  // CSS Variable Auto-Injection
+  useEffect(function () {
+    if (injectCssVars === false) return;
+    if (typeof document === 'undefined') return;
+    var vars = designSystem.variables;
+    if (!vars || Object.keys(vars).length === 0) return;
+    var root = document.documentElement;
+    for (var _i = 0, _Object$entries = Object.entries(vars); _i < _Object$entries.length; _i++) {
+      var _token$resolvedValue;
+      var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+        key = _Object$entries$_i[0],
+        token = _Object$entries$_i[1];
+      root.style.setProperty(key, (_token$resolvedValue = token.resolvedValue) !== null && _token$resolvedValue !== void 0 ? _token$resolvedValue : token.value);
+    }
+  }, [designSystem.variables, injectCssVars]);
   var updateDesignSystem = function updateDesignSystem(newData) {
     setDesignSystem(newData);
     setSyncVersion(function (prev) {
       return prev + 1;
     });
-    if (!syncEnabled) {
-      localStorage.setItem("designSystemData", JSON.stringify(newData));
+    setDataSource("initial");
+    setDataTimestamp(Date.now());
+    if (persistCache && projectId) {
+      try {
+        localStorage.setItem("strata-cache-".concat(projectId), JSON.stringify(newData));
+        localStorage.setItem("strata-cache-ts-".concat(projectId), Date.now().toString());
+      } catch (e) {}
+    } else if (!syncEnabled && typeof window !== "undefined") {
+      try {
+        localStorage.setItem("designSystemData", JSON.stringify(newData));
+      } catch (e) {}
     }
   };
   var contextValue = {
@@ -1449,7 +1564,9 @@ var StrataProvider = function StrataProvider(_ref) {
     syncInterval: syncInterval,
     syncToken: syncToken,
     snapshotCdnBase: snapshotCdnBase,
-    projectId: projectId
+    projectId: projectId,
+    dataSource: dataSource,
+    cacheAge: dataTimestamp ? Date.now() - dataTimestamp : null
   };
   return jsx(StrataContext.Provider, {
     value: contextValue,

package/dist/index.js

@@ -1115,35 +1115,103 @@ var StrataProvider = function StrataProvider(_ref) {
     projectId = _ref.projectId,
     onSyncError = _ref.onSyncError,
     onSyncSuccess = _ref.onSyncSuccess,
-    onSyncStart = _ref.onSyncStart;
-  var _useState = React.useState(userDesignSystem || initialData || {
-      variables: {},
-      components: {},
-      custom: {
-        variables: {},
-        components: {}
+    onSyncStart = _ref.onSyncStart,
+    _ref$persistCache = _ref.persistCache,
+    persistCache = _ref$persistCache === void 0 ? true : _ref$persistCache,
+    _ref$injectCssVars = _ref.injectCssVars,
+    injectCssVars = _ref$injectCssVars === void 0 ? true : _ref$injectCssVars;
+  var _useState = React.useState(function () {
+      if (userDesignSystem) return "initial";
+      if (initialData) return "initial";
+      if (persistCache && projectId) {
+        if (typeof window !== "undefined") {
+          try {
+            var cached = localStorage.getItem("strata-cache-".concat(projectId));
+            if (cached) return "cache";
+          } catch (e) {}
+        }
       }
+      return "empty";
     }),
     _useState2 = _slicedToArray(_useState, 2),
-    designSystem = _useState2[0],
-    setDesignSystem = _useState2[1];
-  var _useState3 = React.useState("idle"),
+    dataSource = _useState2[0],
+    setDataSource = _useState2[1];
+  var _useState3 = React.useState(function () {
+      if (userDesignSystem || initialData) return Date.now();
+      if (persistCache && projectId) {
+        if (typeof window !== "undefined") {
+          try {
+            var ts = localStorage.getItem("strata-cache-ts-".concat(projectId));
+            if (ts) {
+              var parsed = Number.parseInt(ts, 10);
+              if (Number.isFinite(parsed)) return parsed;
+            }
+          } catch (e) {}
+        }
+      }
+      return null;
+    }),
     _useState4 = _slicedToArray(_useState3, 2),
-    syncStatus = _useState4[0],
-    setSyncStatus = _useState4[1];
-  var _useState5 = React.useState(null),
+    dataTimestamp = _useState4[0],
+    setDataTimestamp = _useState4[1];
+  var _useState5 = React.useState(function () {
+      if (userDesignSystem) return userDesignSystem;
+      if (initialData) return initialData;
+      if (persistCache && projectId) {
+        if (typeof window !== "undefined") {
+          try {
+            var cached = localStorage.getItem("strata-cache-".concat(projectId));
+            if (cached) {
+              var parsed = JSON.parse(cached);
+              if (parsed && parsed.variables && parsed.components) {
+                return parsed;
+              }
+            }
+          } catch (e) {}
+        }
+      }
+      return {
+        variables: {},
+        components: {},
+        custom: {
+          variables: {},
+          components: {}
+        }
+      };
+    }),
     _useState6 = _slicedToArray(_useState5, 2),
-    lastSynced = _useState6[0],
-    setLastSynced = _useState6[1];
-  var _useState7 = React.useState(0),
+    designSystem = _useState6[0],
+    setDesignSystem = _useState6[1];
+  var _useState7 = React.useState("idle"),
     _useState8 = _slicedToArray(_useState7, 2),
-    syncVersion = _useState8[0],
-    setSyncVersion = _useState8[1];
+    syncStatus = _useState8[0],
+    setSyncStatus = _useState8[1];
+  var _useState9 = React.useState(function () {
+      if (typeof window !== "undefined" && persistCache && projectId) {
+        try {
+          var ts = localStorage.getItem("strata-cache-ts-".concat(projectId));
+          if (ts) {
+            var parsed = Number.parseInt(ts, 10);
+            if (Number.isFinite(parsed)) return new Date(parsed);
+          }
+        } catch (e) {}
+      }
+      return null;
+    }),
+    _useState0 = _slicedToArray(_useState9, 2),
+    lastSynced = _useState0[0],
+    setLastSynced = _useState0[1];
+  var _useState1 = React.useState(0),
+    _useState10 = _slicedToArray(_useState1, 2),
+    syncVersion = _useState10[0],
+    setSyncVersion = _useState10[1];
   // Ref that tracks the JSON string of the last successfully synced payload so
   // that syncDesignSystem does not need to close over the designSystem state
   // value. This keeps the callback stable and prevents the polling interval
   // from being continuously reset after each successful sync.
   var lastSyncedStringRef = React.useRef(null);
+  // Ref to track the ETag of the last fetched snapshot
+  var lastETagRef = React.useRef(null);
   // Refs for lifecycle callbacks so that syncDesignSystem does not need to
   // close over them. Inline functions passed by the consumer (e.g. anonymous
   // arrow functions) would otherwise change identity on every render, forcing
@@ -1180,7 +1248,7 @@ var StrataProvider = function StrataProvider(_ref) {
   }, []);
   var syncDesignSystem = React.useCallback(/*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
     var _onSyncStartRef$curre;
-    var headers, remoteData, res, _onSyncErrorRef$curre, data, _onSyncErrorRef$curre2, _yield$Promise$all, _yield$Promise$all2, variablesRes, componentsRes, customRes, _yield$Promise$all3, _yield$Promise$all4, variables, components, custom, newDataString, _onSyncSuccessRef$cur, _onSyncErrorRef$curre3, _t;
+    var headers, remoteData, res, _onSyncErrorRef$curre, etag, data, _onSyncErrorRef$curre2, _yield$Promise$all, _yield$Promise$all2, variablesRes, componentsRes, customRes, _yield$Promise$all3, _yield$Promise$all4, variables, components, custom, newDataString, _onSyncSuccessRef$cur, _onSyncErrorRef$curre3, _t;
     return _regenerator().w(function (_context) {
       while (1) switch (_context.p = _context.n) {
         case 0:
@@ -1197,19 +1265,30 @@ var StrataProvider = function StrataProvider(_ref) {
             Authorization: "Bearer ".concat(syncToken)
           } : {};
           if (!snapshotUrl) {
-            _context.n = 8;
+            _context.n = 9;
             break;
           }
+          if (lastETagRef.current) {
+            headers["If-None-Match"] = lastETagRef.current;
+          }
+          // Single CDN snapshot fetch — edge-cached, 1 request per poll
           _context.n = 3;
           return fetch(snapshotUrl, {
             headers: headers
           });
         case 3:
           res = _context.v;
-          if (!(!res.ok && res.status >= 400 && res.status < 500)) {
+          if (!(res.status === 304)) {
             _context.n = 4;
             break;
           }
+          setSyncStatus("idle");
+          return _context.a(2);
+        case 4:
+          if (!(!res.ok && res.status >= 400 && res.status < 500)) {
+            _context.n = 5;
+            break;
+          }
           setSyncStatus("error");
           (_onSyncErrorRef$curre = onSyncErrorRef.current) === null || _onSyncErrorRef$curre === void 0 || _onSyncErrorRef$curre.call(onSyncErrorRef, {
             code: res.status,
@@ -1217,19 +1296,23 @@ var StrataProvider = function StrataProvider(_ref) {
             source: "cdn"
           });
           return _context.a(2);
-        case 4:
+        case 5:
           if (res.ok) {
-            _context.n = 5;
+            _context.n = 6;
             break;
           }
           throw new Error("Snapshot fetch failed: ".concat(res.status));
-        case 5:
-          _context.n = 6;
-          return res.json();
         case 6:
+          etag = res.headers.get("ETag");
+          if (etag) {
+            lastETagRef.current = etag;
+          }
+          _context.n = 7;
+          return res.json();
+        case 7:
           data = _context.v;
           if (!(!data || _typeof(data) !== "object" || Array.isArray(data) || _typeof(data.variables) !== "object" || data.variables === null || Array.isArray(data.variables) || _typeof(data.components) !== "object" || data.components === null || Array.isArray(data.components))) {
-            _context.n = 7;
+            _context.n = 8;
             break;
           }
           console.warn("[strata] Invalid snapshot shape received from CDN — skipping update.");
@@ -1240,7 +1323,7 @@ var StrataProvider = function StrataProvider(_ref) {
             source: "cdn"
           });
           return _context.a(2);
-        case 7:
+        case 8:
           remoteData = {
             variables: data.variables,
             components: data.components,
@@ -1253,10 +1336,10 @@ var StrataProvider = function StrataProvider(_ref) {
           // ComponentNode shape so that useDynamicComponents and the registry
           // always receive consistently-shaped data.
           remoteData = normalizeComponents(remoteData);
-          _context.n = 14;
+          _context.n = 15;
           break;
-        case 8:
-          _context.n = 9;
+        case 9:
+          _context.n = 10;
           return Promise.all([fetch("".concat(syncUrl, "/variables"), {
             headers: headers
           }), fetch("".concat(syncUrl, "/components"), {
@@ -1264,33 +1347,33 @@ var StrataProvider = function StrataProvider(_ref) {
           }), fetch("".concat(syncUrl, "/custom"), {
             headers: headers
           })]);
-        case 9:
+        case 10:
           _yield$Promise$all = _context.v;
           _yield$Promise$all2 = _slicedToArray(_yield$Promise$all, 3);
           variablesRes = _yield$Promise$all2[0];
           componentsRes = _yield$Promise$all2[1];
           customRes = _yield$Promise$all2[2];
           if (variablesRes.ok) {
-            _context.n = 10;
+            _context.n = 11;
             break;
           }
           throw new Error("Variables fetch failed: ".concat(variablesRes.status));
-        case 10:
+        case 11:
           if (componentsRes.ok) {
-            _context.n = 11;
+            _context.n = 12;
             break;
           }
           throw new Error("Components fetch failed: ".concat(componentsRes.status));
-        case 11:
+        case 12:
           if (customRes.ok) {
-            _context.n = 12;
+            _context.n = 13;
             break;
           }
           throw new Error("Custom fetch failed: ".concat(customRes.status));
-        case 12:
-          _context.n = 13;
-          return Promise.all([variablesRes.json(), componentsRes.json(), customRes.json()]);
         case 13:
+          _context.n = 14;
+          return Promise.all([variablesRes.json(), componentsRes.json(), customRes.json()]);
+        case 14:
           _yield$Promise$all3 = _context.v;
           _yield$Promise$all4 = _slicedToArray(_yield$Promise$all3, 3);
           variables = _yield$Promise$all4[0];
@@ -1308,7 +1391,7 @@ var StrataProvider = function StrataProvider(_ref) {
           // ComponentNode shape so that useDynamicComponents and the registry
           // always receive consistently-shaped data.
           remoteData = normalizeComponents(remoteData);
-        case 14:
+        case 15:
           // Only update if data actually changed (compared against the last synced
           // snapshot via ref, so this callback stays stable across renders).
           newDataString = JSON.stringify(remoteData);
@@ -1321,14 +1404,22 @@ var StrataProvider = function StrataProvider(_ref) {
             });
             setSyncStatus("success");
             setLastSynced(new Date());
+            setDataSource("live");
+            setDataTimestamp(Date.now());
+            if (persistCache && projectId) {
+              try {
+                localStorage.setItem("strata-cache-".concat(projectId), newDataString);
+                localStorage.setItem("strata-cache-ts-".concat(projectId), Date.now().toString());
+              } catch (e) {}
+            }
             (_onSyncSuccessRef$cur = onSyncSuccessRef.current) === null || _onSyncSuccessRef$cur === void 0 || _onSyncSuccessRef$cur.call(onSyncSuccessRef, remoteData);
           } else {
             setSyncStatus("idle");
           }
-          _context.n = 16;
+          _context.n = 17;
           break;
-        case 15:
-          _context.p = 15;
+        case 16:
+          _context.p = 16;
           _t = _context.v;
           console.error("❌ Sync failed:", _t);
           setSyncStatus("error");
@@ -1337,11 +1428,11 @@ var StrataProvider = function StrataProvider(_ref) {
             message: _t instanceof Error ? _t.message : String(_t),
             source: snapshotUrl ? "cdn" : "sync"
           });
-        case 16:
+        case 17:
           return _context.a(2);
       }
-    }, _callee, null, [[2, 15]]);
-  })), [syncEnabled, syncUrl, syncToken, snapshotUrl, normalizeComponents]);
+    }, _callee, null, [[2, 16]]);
+  })), [syncEnabled, syncUrl, syncToken, snapshotUrl, normalizeComponents, persistCache, projectId]);
   // Force sync function for manual triggering
   var forceSync = React.useCallback(/*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
     return _regenerator().w(function (_context2) {
@@ -1430,13 +1521,37 @@ var StrataProvider = function StrataProvider(_ref) {
       xl: ((_designSystem$variabl24 = designSystem.variables["--shadow-xl"]) === null || _designSystem$variabl24 === void 0 ? void 0 : _designSystem$variabl24.value) || "0 20px 25px -5px rgba(0, 0, 0, 0.1)"
     }
   });
+  // CSS Variable Auto-Injection
+  React.useEffect(function () {
+    if (injectCssVars === false) return;
+    if (typeof document === 'undefined') return;
+    var vars = designSystem.variables;
+    if (!vars || Object.keys(vars).length === 0) return;
+    var root = document.documentElement;
+    for (var _i = 0, _Object$entries = Object.entries(vars); _i < _Object$entries.length; _i++) {
+      var _token$resolvedValue;
+      var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+        key = _Object$entries$_i[0],
+        token = _Object$entries$_i[1];
+      root.style.setProperty(key, (_token$resolvedValue = token.resolvedValue) !== null && _token$resolvedValue !== void 0 ? _token$resolvedValue : token.value);
+    }
+  }, [designSystem.variables, injectCssVars]);
   var updateDesignSystem = function updateDesignSystem(newData) {
     setDesignSystem(newData);
     setSyncVersion(function (prev) {
       return prev + 1;
     });
-    if (!syncEnabled) {
-      localStorage.setItem("designSystemData", JSON.stringify(newData));
+    setDataSource("initial");
+    setDataTimestamp(Date.now());
+    if (persistCache && projectId) {
+      try {
+        localStorage.setItem("strata-cache-".concat(projectId), JSON.stringify(newData));
+        localStorage.setItem("strata-cache-ts-".concat(projectId), Date.now().toString());
+      } catch (e) {}
+    } else if (!syncEnabled && typeof window !== "undefined") {
+      try {
+        localStorage.setItem("designSystemData", JSON.stringify(newData));
+      } catch (e) {}
     }
   };
   var contextValue = {
@@ -1451,7 +1566,9 @@ var StrataProvider = function StrataProvider(_ref) {
     syncInterval: syncInterval,
     syncToken: syncToken,
     snapshotCdnBase: snapshotCdnBase,
-    projectId: projectId
+    projectId: projectId,
+    dataSource: dataSource,
+    cacheAge: dataTimestamp ? Date.now() - dataTimestamp : null
   };
   return jsxRuntime.jsx(StrataContext.Provider, {
     value: contextValue,

package/dist/providers/StrataProvider.d.ts

@@ -13,6 +13,8 @@ interface StrataContextType {
     syncToken: string | undefined;
     snapshotCdnBase: string | undefined;
     projectId: string | undefined;
+    dataSource: "live" | "cache" | "initial" | "empty";
+    cacheAge: number | null;
 }
 export declare const useStrata: () => StrataContextType;
 interface StrataProviderProps {
@@ -59,6 +61,16 @@ interface StrataProviderProps {
      * Use this to show a loading indicator or log sync lifecycle events.
      */
     onSyncStart?: () => void;
+    /**
+     * Whether to persist and restore cached snapshot to/from localStorage.
+     * Defaults to true.
+     */
+    persistCache?: boolean;
+    /**
+     * Whether to automatically inject design system variables into document.documentElement.
+     * Defaults to true.
+     */
+    injectCssVars?: boolean;
 }
 export declare const StrataProvider: React.FC<StrataProviderProps>;
 export {};

package/package.json

@@ -1,12 +1,15 @@
 {
 	"name": "@strata-ds/core",
-	"version": "2.1.6",
+	"version": "2.1.17",
 	"type": "module",
 	"description": "The runtime component library for Strata — design once, sync everywhere.",
 	"homepage": "https://strata.charisol.io",
 	"main": "dist/index.js",
 	"module": "dist/index.esm.js",
 	"types": "dist/index.d.ts",
+	"bin": {
+		"strata-ds": "./dist/cli/snapshot.js"
+	},
 	"exports": {
 		".": {
 			"import": "./dist/index.esm.js",