@neomorph/sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,189 +1,149 @@
 # @neomorph/sdk
 
-Advanced theme transformation SDK for web applications. Enables dynamic theme customization through CSS custom properties with cross-origin communication support.
+The **headless, framework-agnostic** core of Neomorph. Use it to add live CSS-variable theming to your own product — load a target app, read its theme, write a new one.
 
-[![npm version](https://badge.fury.io/js/@neomorph%2Fsdk.svg)](https://www.npmjs.com/package/@neomorph/sdk)
-[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+The SDK has no UI of its own. [Neomorph Studio](../studio) is a visual designer built on top of this SDK; this package is what you reach for when you want to build that experience into your own app instead.
 
-## 🎯 Overview
+## What's in the box
 
-The Neomorph SDK provides communication tools for building theme designer interfaces. It enables theme designers to retrieve CSS variable data from target applications and build custom theme customization UIs.
+The SDK exports two classes:
 
-## 🏗️ Architecture
+| Class | Side | Responsibility |
+|---|---|---|
+| `Loomer` | Designer side (parent window) | Loads a target app in an iframe and drives it: scrape variables, apply a theme, reset, configure, tear down. |
+| `Weaver` | Designer side | One helper — injects the Weaver script into a page from the CDN. |
 
-```
-┌─────────────────┐                           ┌─────────────────┐
-│ Your Application│←──── Neomorph Bridge ────→│ Theme Designer  │
-├─────────────────┤                           ├─────────────────┤
-│ CSS Variables   │                           │ Custom UI       │
-│ • --primary     │                           │ • Color Pickers │
-│ • --font-size   │                           │ • Sliders       │
-│ • --border      │                           │ • Input Fields  │
-└─────────────────┘                           └─────────────────┘
-```
+> **Naming note:** `Loomer` is the *controller class*. "Studio" is the separate ready-made *app*. You use `Loomer`; Studio uses it too.
 
-## 📦 Installation
+The target app itself runs the [`@neomorph/weaver`](../weaver) script — that's a separate package, loaded inside the app being themed, not imported here.
+
+## Installation
 
 ```bash
 npm install @neomorph/sdk
 ```
 
-## 🚀 Quick Start
-
-### Prerequisites
-
-Your application must use CSS custom properties for theming:
-
-```css
-:root {
-  --primary-color: #3498db;
-  --secondary-color: #2ecc71;
-  --background-color: #ffffff;
-  --text-color: #333333;
-  --border-radius: 4px;
-  --font-size-base: 16px;
-}
-
-.button {
-  background-color: var(--primary-color);
-  color: var(--text-color);
-  border-radius: var(--border-radius);
-  font-size: var(--font-size-base);
-}
-```
+Or load the CDN build, which exposes `window.Neomorph.Loomer` and `window.Neomorph.Weaver`.
 
-## 📖 Use Cases
+## Prerequisites
 
-### Loomer Integration (Theme Designer Side)
+The target app must theme itself with CSS custom properties (`--color-primary`, etc.) and must have the Weaver script loaded. See the [root README](../../README.md) for the full picture.
 
-Use the Loomer class to communicate with applications and retrieve CSS variable data. The SDK provides the data and communication layer - you build the actual theme designer UI based on the returned JSON data.
+## Usage
 
-#### Basic Data Retrieval
+### Load a target app and read its theme
 
-```typescript
-import { Loomer, type SDKResponse } from '@neomorph/sdk';
+```ts
+import { Loomer } from '@neomorph/sdk';
 
-// Initialize Loomer for theme designer communication
 const loomer = new Loomer();
 
-// Load target application in iframe with callback
-loomer.loadApplication('https://your-app.com', (response: SDKResponse | null) => {
-  if (response) {
-    console.log('Received data:', response);
-
-    // Actual response structure:
-    // {
-    //   requestId: "randomId",
-    //   service: "skinweaver",
-    //   payload: { action: "listenCssVariables", ...cssData }
-    // }
-
-    // YOU process this data and build UI
-    buildYourThemeDesigner(response);
-  }
+// Creates an iframe for the target app inside the given container
+loomer.loadApplication('https://your-app.com', document.getElementById('preview'));
+
+// Ask the app for its CSS variables. The callback fires with the scraped
+// data, and again every time the app's stylesheets change.
+loomer.listenCssVariables((variables) => {
+  console.log('current theme:', variables);
+  // variables is keyed by host ("document", shadow-root tag names),
+  // then by CSS selector, then a list of { property, value } pairs.
 });
+```
+
+Messages are queued until the iframe finishes loading, so you can call these
+immediately after `loadApplication` without waiting.
+
+### Apply a theme
+
+```ts
+loomer.applyCssVariables(
+  {
+    document: {
+      '--color-primary': '#e11d48',
+      '--color-bg': '#0f172a'
+    }
+  },
+  /* persist */ true
+);
+```
 
-// Request CSS variables from the loaded application
-function startListening() {
-  loomer.listenCssVariables(); // Sends PostMessage to iframe
-}
+The outer key is the host (`'document'` or a shadow-root host's tag name). Pass
+`persist: true` to save the theme to the target app's `localStorage` so it
+survives reloads.
 
-// Example: Build your own theme designer UI
-function buildYourThemeDesigner(response: SDKResponse) {
-  // Extract data from the response payload
-  const cssData = response.payload;
+### Reset, configure, tear down
 
-  // Create your own UI based on the received data
-  // YOU implement the color pickers, sliders, inputs, etc.
-  createCustomThemeControls(cssData);
-}
+```ts
+loomer.clearTheme();                       // remove overrides + clear persisted theme
+loomer.configure({ debounceMs: 500 });     // tune Weaver's runtime behavior
+loomer.teardown();                         // disconnect observers + listeners
 ```
 
-#### Advanced Data Retrieval with Configuration
+### Inject the Weaver script programmatically
 
-```typescript
-import { Loomer, type SDKResponse } from '@neomorph/sdk';
+If you control the target page, you can inject Weaver instead of adding a `<script>` tag by hand:
 
-const loomer = new Loomer({
-  // Custom iframe container
-  container: document.getElementById('preview-container'),
+```ts
+import { Weaver } from '@neomorph/sdk';
 
-  // Communication timeout
-  timeout: 5000,
+Weaver.inject(); // appends the Weaver CDN script to document.head
+```
 
-  // Enable debugging
-  debug: true
-});
+## API reference
 
-// Load application with error handling
-try {
-  await loomer.loadApplication('https://your-app.com', {
-    onLoad: () => console.log('Application loaded'),
-    onError: (error) => console.error('Load failed:', error),
-    onThemeChange: (variables) => console.log('Theme applied:', variables)
-  });
-
-  // Request available CSS variables
-  const response = await loomer.getCssVariables();
-
-  if (response.success) {
-    const { cssVariables, metadata } = response.data;
-
-    // Process and group the JSON data
-    const groupedVars = groupVariablesByCategory(cssVariables);
-
-    // Build your custom theme designer UI with the data
-    buildYourThemeDesignerUI(groupedVars);
-  }
-
-} catch (error) {
-  console.error('Integration failed:', error);
-}
-
-// Batch update multiple variables
-function applyTheme(theme: Record<string, string>) {
-  Object.entries(theme).forEach(([variable, value]) => {
-    loomer.updateCssVariable(variable, value);
-  });
-}
-```
+### `class Loomer`
 
-## 🔒 Security Considerations
+| Method | Description |
+|---|---|
+| `loadApplication(url, container?)` | Create an iframe for `url` inside `container` (defaults to `document.body`). |
+| `listenCssVariables(callback)` | Scrape the target's CSS variables; `callback` fires now and on every later change. |
+| `applyCssVariables(variables, persist?)` | Apply CSS variable overrides. `persist` saves them to the target's `localStorage`. |
+| `clearTheme()` | Remove all applied overrides and clear the persisted theme. |
+| `configure(config)` | Update Weaver's runtime config (e.g. `debounceMs`, `hostFilter`). |
+| `teardown()` | Disconnect Weaver's observers and listeners in the target app. |
 
-- **Cross-Origin Communication**: All PostMessage communication includes origin validation
-- **CSS Variable Exposure**: Only explicitly exposed variables are accessible via Weaver
-- **Iframe Sandboxing**: Consider appropriate iframe sandbox attributes for security
-- **Input Validation**: Always validate CSS variable values before applying
+### `class Weaver`
 
-## 🐛 Troubleshooting
+| Method | Description |
+|---|---|
+| `Weaver.inject(version?)` | Append the Weaver script (from jsDelivr) to `document.head`. Defaults to the latest pinned version. |
 
-### Common Issues
+## How communication works
 
-**PostMessage not working**
-- Ensure both applications are served over HTTPS (or both over HTTP in development)
-- Check that iframe src and parent window origins are correctly configured
-- Verify that Weaver script is loaded before Loomer attempts communication
+`Loomer` and the in-app Weaver script talk over the `postMessage` API. Every
+message is JSON with a `skinweaver` service identifier and a `requestId`.
+`Loomer` queues outgoing messages until the iframe's `load` event fires, then
+flushes them — so ordering and timing are handled for you:
 
-**CSS Variables not detected**
-- Confirm variables are defined in `:root` or explicitly exposed via Weaver options
-- Check browser DevTools for CSS custom property support
-- Ensure variables use the `--` prefix
+```mermaid
+sequenceDiagram
+    participant App as Your code
+    participant L as Loomer (SDK)
+    participant I as Target iframe
+    participant W as Weaver
 
-**Cross-origin errors**
-- Verify CORS headers are properly configured on target application
-- Use appropriate iframe sandbox attributes
-- Consider using a proxy for local development
+    App->>L: loadApplication(url, container)
+    L->>I: create iframe
+    App->>L: listenCssVariables(cb)
+    Note over L: iframe not ready —<br/>message is queued
 
-## 🤝 Contributing
+    I-->>L: iframe "load" event
+    L->>W: flush queued messages
 
-See the main [repository README](../../README.md) for contribution guidelines.
+    W-->>L: scraped CSS variables
+    L->>App: cb(variables)
 
-## 📄 License
+    App->>L: applyCssVariables(overrides)
+    L->>W: applyCssVariables
+    W-->>L: applied ✓
+```
 
-ISC - See [LICENSE](../../LICENSE) for details.
+## Security notes
 
----
+- **Origins** — messages are validated by service identifier. When embedding untrusted apps, also apply iframe `sandbox` attributes.
+- **Exposure** — only CSS variables actually present in the target's stylesheets are visible; Weaver does not expose anything else.
+- **Validation** — validate CSS values before calling `applyCssVariables` if they come from user input.
 
-**Made with ❤️ by the Neomorph team**
+## License
 
-For more information, visit the [main repository](https://github.com/sinha-sahil/neomorph).
+ISC — see [LICENSE](../../LICENSE).

package/dist/index.js

@@ -1 +1 @@
-function e(e){return"string"==typeof e?e:null}function t(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}const a=function(a){if(t(a)){const n=e(a.requestId),i=e(a.service),r=function(e){if(t(e))return{...e};return null}(a.payload);if(null!==n&&null!==i&&null!==r)return{requestId:n,service:i,payload:r}}return null};class n{applicationFrame;callbacks;constructor(){this.applicationFrame=null,this.callbacks=[]}loadApplication(e,t=document.body){try{this.applicationFrame=document.createElement("iframe"),this.applicationFrame.src=e,this.applicationFrame.style.width="100%",this.applicationFrame.style.height="100%",this.applicationFrame.style.border="none",t.appendChild(this.applicationFrame),window.addEventListener("message",e=>{const t=a(e.data);null!==t&&console.log("DecodedResponse: ",t)})}catch(e){console.error("🕸️ Weaver: Failed to load application:",e)}}listenCssVariables(e){try{this.applicationFrame?.contentWindow?.postMessage(JSON.stringify({source:"skinweaver",payload:JSON.stringify({requestId:"randomId",service:"skinweaver",payload:{action:"listenCssVariables"}})}),"*"),this.callbacks.push(e)}catch(e){console.error("🕸️ Weaver: Failed to send message to iframe:",e)}}}class i{static inject(e="1.0.0"){if("undefined"!=typeof document)try{const t=document.createElement("script");t.src=`https://cdn.jsdelivr.net/gh/sinha-sahil/neomorph/build/weaver/${e}/index.js`,t.type="text/javascript",document.head.appendChild(t)}catch(e){console.error("🕸️ Weaver: Failed to inject weaver script:",e)}else console.warn("🕸️ Weaver: inject() called in non-browser environment")}}export{n as Loomer,i as Weaver};
+function e(e){return"string"==typeof e?e:null}function s(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}const a=function(a){if(s(a)){const t=e(a.requestId),n=e(a.service),i=function(e){if(s(e))return{...e};return null}(a.payload);if(null!==t&&null!==n&&null!==i)return{requestId:t,service:n,payload:i}}return null};class t{applicationFrame;callbacks;ready;pendingMessages;constructor(){this.applicationFrame=null,this.callbacks=[],this.ready=!1,this.pendingMessages=[]}loadApplication(e,s=document.body){try{this.applicationFrame=document.createElement("iframe"),this.applicationFrame.src=e,this.applicationFrame.style.width="100%",this.applicationFrame.style.height="100%",this.applicationFrame.style.border="none",s.appendChild(this.applicationFrame),this.applicationFrame.addEventListener("load",()=>{this.ready=!0,this.flushPendingMessages()}),window.addEventListener("message",e=>{const s="string"==typeof e.data?function(e){try{return JSON.parse(e)}catch{return null}}(e.data):e.data,t=a(s);null!==t&&("action"in t.payload||this.callbacks.forEach(e=>e(t.payload)))})}catch(e){console.error("Loomer: Failed to load application:",e)}}flushPendingMessages(){for(const e of this.pendingMessages)this.postMessage(e);this.pendingMessages=[]}postMessage(e){try{if(null===this.applicationFrame||null===this.applicationFrame.contentWindow)return;this.applicationFrame.contentWindow.postMessage(JSON.stringify({source:"skinweaver",payload:JSON.stringify({requestId:crypto.randomUUID(),service:"skinweaver",payload:e})}),"*")}catch(e){console.error("Loomer: Failed to send message to iframe:",e)}}sendMessage(e){this.ready?this.postMessage(e):this.pendingMessages.push(e)}listenCssVariables(e){this.sendMessage({action:"listenCssVariables"}),this.callbacks.push(e)}applyCssVariables(e,s){this.sendMessage({action:"applyCssVariables",variables:e,persist:s})}clearTheme(){this.sendMessage({action:"clearTheme"})}configure(e){this.sendMessage({action:"configure",config:e})}teardown(){this.sendMessage({action:"teardown"})}}class n{static inject(e="1.0.0"){if("undefined"!=typeof document)try{const s=document.createElement("script");s.src=`https://cdn.jsdelivr.net/gh/sinha-sahil/neomorph/build/weaver/${e}/index.js`,s.type="text/javascript",document.head.appendChild(s)}catch(e){console.error("🕸️ Weaver: Failed to inject weaver script:",e)}else console.warn("🕸️ Weaver: inject() called in non-browser environment")}}export{t as Loomer,n as Weaver};

package/dist/loomer.d.ts

@@ -2,7 +2,16 @@ import { StylesCallback } from "./types";
 export declare class Loomer {
     private applicationFrame;
     private callbacks;
+    private ready;
+    private pendingMessages;
     constructor();
     loadApplication(url: string, container?: HTMLElement): void;
+    private flushPendingMessages;
+    private postMessage;
+    private sendMessage;
     listenCssVariables(callback: StylesCallback): void;
+    applyCssVariables(variables: Record<string, Record<string, string>>, persist?: boolean): void;
+    clearTheme(): void;
+    configure(config: Record<string, unknown>): void;
+    teardown(): void;
 }

package/dist/types.d.ts

@@ -15,7 +15,7 @@ export type SDKPayload = {
 };
 export type SDKPayloadPayload = Record<string, unknown>;
 export type SDKResponse = SDKPayload;
-export type StylesCallback = (val: HostStyles) => void;
+export type StylesCallback = (val: SDKPayloadPayload) => void;
 export declare function decodeCssProperty(rawInput: unknown): CSSProperty | null;
 export declare function decodeSDKPayload(rawInput: unknown): SDKPayload | null;
 export declare function decodeSDKPayloadPayload(rawInput: unknown): SDKPayloadPayload | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@neomorph/sdk",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Core SDK for Neomorph - Advanced theme generator toolkit for web applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,14 +15,6 @@
     "dist/",
     "README.md"
   ],
-  "scripts": {
-    "dev": "rollup -c rollup.config.js --watch",
-    "build": "rollup --config rollup.config.js",
-    "build:cdn": "rollup --config rollup.config.js --environment buildType=cdn",
-    "format": "npx prettier --write .",
-    "lint": "prettier --plugin-search-dir . --check . && eslint .",
-    "clean": "rm -rf dist"
-  },
   "keywords": [
     "neomorph",
     "theme",
@@ -47,9 +39,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.18.0",
   "dependencies": {
-    "type-decoder": "^2.1.0"
+    "type-decoder": "^2.3.1"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
@@ -65,7 +56,17 @@
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.6.2",
     "rollup": "^4.52.0",
+    "rollup-plugin-serve": "^3.0.0",
     "tslib": "^2.8.1",
     "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "dev": "rollup -c rollup.config.js --watch",
+    "dev:cdn": "rollup -c rollup.config.js --watch --environment buildType=cdn",
+    "build": "rollup --config rollup.config.js",
+    "build:cdn": "rollup --config rollup.config.js --environment buildType=cdn",
+    "format": "npx prettier --write .",
+    "lint": "prettier --plugin-search-dir . --check . && eslint .",
+    "clean": "rm -rf dist"
   }
-}
+}