@strata-ds/core 2.1.18 → 2.1.19

package/README.md

@@ -98,7 +98,7 @@ Your React Application
 
 ## Quick Start (< 5 Minutes)
 
-> 🚀 **New to Strata?** Get your first component rendering in 4 steps.
+Get your first component rendering in 4 steps.
 
 ### Step 1: Install
 
@@ -117,7 +117,7 @@ Go to [strata.charisol.io](https://strata.charisol.io) → **Your Project** →
 
 ### Step 3: Wrap Your App
 
-**✅ Recommended: CDN Snapshot Sync** (1 request per poll, edge-cached)
+**Recommended: CDN Snapshot Sync** (1 request per poll, edge-cached)
 
 ```tsx
 "use client"; // Next.js App Router only
@@ -142,12 +142,12 @@ export default function RootLayout({
 }
 ```
 
-> 💡 Replace `YOUR_PROJECT_ID` and `pt_live_your_token_here` with values from **Step 2**.
+> Replace `YOUR_PROJECT_ID` and `pt_live_your_token_here` with values from **Step 2**.
 
 ---
 
 <details>
-<summary><strong>⚠️ Legacy Sync</strong> (3 requests per poll — for migration only)</summary>
+<summary><strong>Legacy Sync</strong> (3 requests per poll — for migration only)</summary>
 
 ```tsx
 "use client";
@@ -173,9 +173,9 @@ export default function RootLayout({
 
 **Why CDN is better:**
 
-- ✅ 1 request instead of 3 (faster, cheaper)
-- ✅ Edge-cached for global performance
-- ✅ Atomic updates (no partial states)
+- 1 request instead of 3 (faster, cheaper)
+- Edge-cached for global performance
+- Atomic updates (no partial states)
 
 </details>
 
@@ -224,10 +224,10 @@ Use this checklist to verify your setup after following [Quick Start](#quick-sta
 
 **Verification:**
 
-- [ ] Opened DevTools → Console and saw `🔄 Starting design system sync...`
-- [ ] Console shows `📊 Components available: ...`
+- [ ] Opened DevTools → Console and saw `Starting design system sync...`
+- [ ] Console shows `Components available: ...`
 - [ ] Component renders on screen with correct styles
-- [ ] Added `<StrataDebug />` and verified connection status is **✅ Connected**
+- [ ] Added `<StrataDebug />` and verified connection status is **Connected**
 
 **Stuck?** → Jump to [Debugging and Troubleshooting](#debugging-and-troubleshooting).
 
@@ -287,7 +287,7 @@ export default function RootLayout({
 }
 ```
 
-> 💡 Replace `YOUR_PROJECT_ID` with the ID from your Strata project dashboard. For private projects, add `syncToken="pt_live_your_token_here"` (get it from the **Publish & Sync** tab).
+> Replace `YOUR_PROJECT_ID` with the ID from your Strata project dashboard. For private projects, add `syncToken="pt_live_your_token_here"` (get it from the **Publish & Sync** tab).
 
 ### Sync token authentication
 
@@ -359,10 +359,10 @@ function StatusBar() {
 
 Add `<StrataDebug />` anywhere inside `<StrataProvider>` to inspect:
 
-- ✅ Active sync mode (CDN vs Legacy)
-- ✅ Connection status
-- ✅ Loaded components
-- ✅ Sync token presence (never shows the actual token)
+- Active sync mode (CDN vs Legacy)
+- Connection status
+- Loaded components
+- Sync token presence (never shows the actual token)
 
 ```tsx
 "use client";
@@ -380,11 +380,11 @@ function App() {
 
 The panel automatically displays the relevant fields for the active sync mode:
 
-- **CDN mode** (`snapshotCdnBase` + `projectId` set): shows `✅ CDN Snapshot`, Project ID, resolved Snapshot URL, token presence, and sync interval.
-- **Legacy mode** (`syncUrl` set): shows `⚠️ Legacy (3 requests/poll)`, Sync URL, token presence, and sync interval.
-- **Disabled**: shows `❌ Disabled`.
+- **CDN mode** (`snapshotCdnBase` + `projectId` set): shows `CDN Snapshot`, Project ID, resolved Snapshot URL, token presence, and sync interval.
+- **Legacy mode** (`syncUrl` set): shows `Legacy (3 requests/poll)`, Sync URL, token presence, and sync interval.
+- **Disabled**: shows `Disabled`.
 
-> 🔒 The `syncToken` value is **never** rendered — the panel only shows `✅ Present` or `❌ None`.
+> The `syncToken` value is **never** rendered — the panel only shows `Present` or `None`.
 
 ---
 
@@ -424,11 +424,11 @@ Open **DevTools → Network tab** and filter by:
 
 Check for these messages:
 
-- ✅ `🔄 Starting design system sync...` → Sync is working
-- ✅ `📊 Components available: Button, Navbar, Card` → Components loaded
-- ✅ `🎨 Variables available: colors, spacing, typography` → Tokens loaded
-- ❌ `❌ Sync failed: 401` → Token issue (see table above)
-- ❌ `❌ Sync failed: 403` → CORS issue (see table above)
+- `Starting design system sync...` → Sync is working
+- `Components available: Button, Navbar, Card` → Components loaded
+- `Variables available: colors, spacing, typography` → Tokens loaded
+- `Sync failed: 401` → Token issue (see table above)
+- `Sync failed: 403` → CORS issue (see table above)
 
 ---
 
@@ -543,26 +543,26 @@ const MyComponent = StrataComponentFactory.createComponent(
 
 Any project using the Strata Design System can enable full offline resilience in three quick steps:
 
-#### Step 1: Configure Auto-Generation in `package.json`
-Simply add a `"strata"` configuration block to your application's `package.json`. The SDK's built-in postinstall hook will automatically fetch the latest snapshot and generate the fallback assets every time you run `npm install`:
-
+#### Step 1: Initialize Configuration with strata.json
+Run the initialization CLI tool to prompt for configuration fields and generate a `strata.json` file in your application's root directory:
+```bash
+npx strata init
+```
+This will create a `strata.json` file at your project's root:
 ```json
 {
-  "name": "your-app",
-  "strata": {
-    "projectId": "YOUR_PROJECT_ID",
-    "snapshotCdnBase": "https://your-cdn-base-url.cloudfront.net",
-    "output": "./src/data/strata-snapshot.json",
-    "outputCss": "./src/styles/strata-fallbacks.css",
-    "variablesOnly": true
-  }
+  "projectId": "YOUR_PROJECT_ID",
+  "snapshotCdnBase": "https://your-cdn-base-url.cloudfront.net",
+  "output": "./src/data/strata-snapshot.json",
+  "outputCss": "./src/styles/strata-fallbacks.css",
+  "variablesOnly": true
 }
 ```
 
 *(Commit the generated JSON and CSS files to your Git repository as your baseline fallback).*
 
-> 💡 **Manual Generation**: You can also run the CLI snapshot tool manually if needed:
-> `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`
+> **Manual Generation**: You can run the CLI snapshot tool manually if you need to fetch updates:
+> `npx strata run`
 
 #### Step 2: Import Fallback Styles
 Reference the CSS file in your main style entry point (e.g., `src/index.css` or `src/App.css`):
@@ -594,13 +594,13 @@ export default function App() {
 
 ## Key Features
 
-- 🔁 Live sync with Strata backend
-- 🧠 Token-driven styling
-- 🧩 Dynamic component registry
-- 🛠 Inline style overrides supported
-- 📦 Installable via npm
-- 📴 Offline-first fallback
-- 🧪 Debug tools included (`StrataDebug`)
+- Live sync with Strata backend
+- Token-driven styling
+- Dynamic component registry
+- Inline style overrides supported
+- Installable via npm
+- Offline-first fallback
+- Debug tools included (`StrataDebug`)
 
 ## License
 

package/dist/cli/postinstall.js

@@ -22,6 +22,44 @@ async function retrieveSnapshot(options) {
         if (!data || typeof data !== 'object' || typeof data.variables !== 'object') {
             throw new Error('Invalid snapshot response shape: missing variables');
         }
+        // Sanitize variables to prevent malformed values from breaking outputs
+        const variables = data.variables || {};
+        for (const [key, val] of Object.entries(variables)) {
+            if (val && typeof val === 'object') {
+                let value = val.value;
+                let resolvedValue = val.resolvedValue;
+                // Sanitize value
+                if (typeof value === 'string') {
+                    if (value.endsWith('\\')) {
+                        value += '\\';
+                    }
+                    if (value.startsWith('url(') && !value.endsWith(')')) {
+                        if (value === 'url(\\' || value === 'url(\\\\' || value === 'url(\\;') {
+                            value = 'none';
+                        }
+                        else {
+                            value += ')';
+                        }
+                    }
+                    val.value = value;
+                }
+                // Sanitize resolvedValue
+                if (typeof resolvedValue === 'string') {
+                    if (resolvedValue.endsWith('\\')) {
+                        resolvedValue += '\\';
+                    }
+                    if (resolvedValue.startsWith('url(') && !resolvedValue.endsWith(')')) {
+                        if (resolvedValue === 'url(\\' || resolvedValue === 'url(\\\\' || resolvedValue === 'url(\\;') {
+                            resolvedValue = 'none';
+                        }
+                        else {
+                            resolvedValue += ')';
+                        }
+                    }
+                    val.resolvedValue = resolvedValue;
+                }
+            }
+        }
         let snapshotJson = data;
         if (variablesOnly) {
             snapshotJson = {
@@ -86,17 +124,15 @@ async function retrieveSnapshot(options) {
     }
 }
 
-function findHostPackage() {
+function findHostStrataJson() {
     let currentDir = process.cwd();
-    // Traverse up to find the host application's package.json
+    // Traverse up to find the host application's strata.json
     while (true) {
-        const packagePath = path.join(currentDir, 'package.json');
-        if (fs.existsSync(packagePath)) {
+        const jsonPath = path.join(currentDir, 'strata.json');
+        if (fs.existsSync(jsonPath)) {
             try {
-                const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
-                if (pkg.name !== '@strata-ds/core' && pkg.strata) {
-                    return { packagePath, rootDir: currentDir, config: pkg.strata };
-                }
+                const config = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+                return { jsonPath, rootDir: currentDir, config };
             }
             catch (e) { }
         }
@@ -108,15 +144,15 @@ function findHostPackage() {
     return null;
 }
 async function run() {
-    const hostInfo = findHostPackage();
+    const hostInfo = findHostStrataJson();
     if (!hostInfo) {
-        console.log('[Strata] No "strata" configuration block found in host package.json. Skipping auto-snapshot retrieval.');
+        console.log('[Strata] No strata.json configuration file found. Run "npx strata init" to initialize design token fallback configuration.');
         return;
     }
     const { rootDir, config } = hostInfo;
     const { projectId, snapshotCdnBase, output, outputCss, syncToken, variablesOnly } = config;
     if (!projectId || !snapshotCdnBase) {
-        console.warn('[Strata] Warning: "projectId" and "snapshotCdnBase" are required in package.json "strata" config.');
+        console.warn('[Strata] Warning: "projectId" and "snapshotCdnBase" are required in strata.json config.');
         return;
     }
     const outputPath = output ? path.resolve(rootDir, output) : undefined;
@@ -129,13 +165,13 @@ async function run() {
             outputPath,
             outputCssPath,
             syncToken,
-            variablesOnly: variablesOnly !== false, // default to true for post-install variable trimming
+            variablesOnly: variablesOnly !== false,
         });
-        console.log('✅ [Strata] Postinstall snapshot retrieval complete.');
+        console.log('[Strata] Postinstall snapshot retrieval complete.');
     }
     catch (error) {
         // Graceful degradation: log warning but do not throw error so install succeeds
-        console.warn(`⚠️ [Strata] Postinstall snapshot failed: ${error.message || error}`);
+        console.warn(`[Strata] Postinstall snapshot failed: ${error.message || error}`);
     }
 }
 run();

package/dist/cli/snapshot.js

@@ -2,6 +2,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import * as readline from 'readline';
 
 async function retrieveSnapshot(options) {
     const { projectId, cdnBase, outputPath, outputCssPath, syncToken, variablesOnly } = options;
@@ -24,6 +25,44 @@ async function retrieveSnapshot(options) {
         if (!data || typeof data !== 'object' || typeof data.variables !== 'object') {
             throw new Error('Invalid snapshot response shape: missing variables');
         }
+        // Sanitize variables to prevent malformed values from breaking outputs
+        const variables = data.variables || {};
+        for (const [key, val] of Object.entries(variables)) {
+            if (val && typeof val === 'object') {
+                let value = val.value;
+                let resolvedValue = val.resolvedValue;
+                // Sanitize value
+                if (typeof value === 'string') {
+                    if (value.endsWith('\\')) {
+                        value += '\\';
+                    }
+                    if (value.startsWith('url(') && !value.endsWith(')')) {
+                        if (value === 'url(\\' || value === 'url(\\\\' || value === 'url(\\;') {
+                            value = 'none';
+                        }
+                        else {
+                            value += ')';
+                        }
+                    }
+                    val.value = value;
+                }
+                // Sanitize resolvedValue
+                if (typeof resolvedValue === 'string') {
+                    if (resolvedValue.endsWith('\\')) {
+                        resolvedValue += '\\';
+                    }
+                    if (resolvedValue.startsWith('url(') && !resolvedValue.endsWith(')')) {
+                        if (resolvedValue === 'url(\\' || resolvedValue === 'url(\\\\' || resolvedValue === 'url(\\;') {
+                            resolvedValue = 'none';
+                        }
+                        else {
+                            resolvedValue += ')';
+                        }
+                    }
+                    val.resolvedValue = resolvedValue;
+                }
+            }
+        }
         let snapshotJson = data;
         if (variablesOnly) {
             snapshotJson = {
@@ -93,24 +132,61 @@ function printHelp() {
 Strata Design System Snapshot CLI
 
 Usage:
-  npx strata-ds snapshot [options]
+  npx strata [command] [options]
+
+Commands:
+  init               Interactively initialize strata.json configuration file
+  run                Fetch snapshot and generate fallbacks using strata.json
+  snapshot           Legacy command to fetch snapshot using 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)
+  --project-id       Strata Project ID (overrides strata.json)
+  --cdn-base         CDN base URL (overrides strata.json)
+  --output           Path to write the snapshot JSON file (overrides strata.json)
+  --output-css       Path to write the CSS fallback file (overrides strata.json)
+  --sync-token       Authorization Sync Token (overrides strata.json)
+  --variables-only   Only output variables in the snapshot JSON (overrides strata.json)
   --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);
+function askQuestion(query) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => rl.question(query, (ans) => {
+        rl.close();
+        resolve(ans.trim());
+    }));
+}
+async function runInit() {
+    console.log('Strata Design System Initialization\n');
+    let projectId = '';
+    while (!projectId) {
+        projectId = await askQuestion('Enter your Strata Project ID (required): ');
+        if (!projectId) {
+            console.log('Error: Project ID is required.');
+        }
     }
+    const cdnBase = (await askQuestion('Enter CDN Base URL (default: https://dx2nhw7wqn4nn.cloudfront.net): ')) || 'https://dx2nhw7wqn4nn.cloudfront.net';
+    const output = (await askQuestion('Enter path to write snapshot JSON file (default: ./src/data/strata-snapshot.json): ')) || './src/data/strata-snapshot.json';
+    const outputCss = (await askQuestion('Enter path to write CSS fallback file (default: ./src/styles/strata-fallbacks.css): ')) || './src/styles/strata-fallbacks.css';
+    const varsOnlyInput = await askQuestion('Only output variables in snapshot JSON? (Y/n): ');
+    const variablesOnly = varsOnlyInput.toLowerCase() !== 'n';
+    const config = {
+        projectId,
+        snapshotCdnBase: cdnBase,
+        output,
+        outputCss,
+        variablesOnly,
+    };
+    const strataJsonPath = path.join(process.cwd(), 'strata.json');
+    fs.writeFileSync(strataJsonPath, JSON.stringify(config, null, 2), 'utf8');
+    console.log(`\nConfig file written successfully to: ${strataJsonPath}`);
+    console.log('To fetch your design tokens, run: npx strata run');
+}
+async function runRetrieve(command) {
+    const args = process.argv.slice(2);
     const getArgValue = (flag) => {
         const idx = args.indexOf(flag);
         if (idx !== -1 && idx + 1 < args.length) {
@@ -121,14 +197,37 @@ async function run() {
     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');
+    // Load config from strata.json if it exists
+    const strataJsonPath = path.join(process.cwd(), 'strata.json');
+    let config = {};
+    if (fs.existsSync(strataJsonPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(strataJsonPath, 'utf8'));
+        }
+        catch (e) {
+            console.error(`Error reading strata.json: ${e.message}`);
+            process.exit(1);
+        }
+    }
+    else if (command === 'run') {
+        console.error('Error: strata.json not found. Run "npx strata init" to initialize configuration.');
+        process.exit(1);
+    }
+    const projectId = getArgValue('--project-id') || config.projectId;
+    const cdnBase = getArgValue('--cdn-base') || config.snapshotCdnBase;
+    const outputPath = getArgValue('--output') || config.output;
+    const outputCssPath = getArgValue('--output-css') || config.outputCss;
+    const syncToken = getArgValue('--sync-token') || config.syncToken;
+    // variables-only is true by default if not set to false
+    let variablesOnly = true;
+    if (hasFlag('--variables-only')) {
+        variablesOnly = true;
+    }
+    else if (config.variablesOnly !== undefined) {
+        variablesOnly = config.variablesOnly;
+    }
     if (!projectId || !cdnBase) {
-        console.error('❌ Error: --project-id and --cdn-base are required.');
+        console.error('Error: --project-id and --cdn-base are required (or must be configured in strata.json).');
         printHelp();
         process.exit(1);
     }
@@ -136,15 +235,33 @@ async function run() {
         await retrieveSnapshot({
             projectId,
             cdnBase,
-            outputPath,
-            outputCssPath,
+            outputPath: outputPath ? path.resolve(outputPath) : undefined,
+            outputCssPath: outputCssPath ? path.resolve(outputCssPath) : undefined,
             syncToken,
             variablesOnly,
         });
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message || error}`);
+        console.error(`Error: ${error.message || error}`);
         process.exit(1);
     }
 }
-run();
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (args.includes('--help') || args.includes('-h') || !command) {
+        printHelp();
+        process.exit(0);
+    }
+    if (command === 'init') {
+        await runInit();
+    }
+    else if (command === 'run' || command === 'snapshot') {
+        await runRetrieve(command);
+    }
+    else {
+        // If it's not a recognized command, default to legacy options-based fetch
+        await runRetrieve('legacy');
+    }
+}
+main();

package/package.json

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