@neomorph/sdk 0.0.1

package/README.md

@@ -0,0 +1,189 @@
+# @neomorph/sdk
+
+Advanced theme transformation SDK for web applications. Enables dynamic theme customization through CSS custom properties with cross-origin communication support.
+
+[![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)
+
+## 🎯 Overview
+
+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.
+
+## 🏗️ Architecture
+
+```
+┌─────────────────┐                           ┌─────────────────┐
+│ Your Application│←──── Neomorph Bridge ────→│ Theme Designer  │
+├─────────────────┤                           ├─────────────────┤
+│ CSS Variables   │                           │ Custom UI       │
+│ • --primary     │                           │ • Color Pickers │
+│ • --font-size   │                           │ • Sliders       │
+│ • --border      │                           │ • Input Fields  │
+└─────────────────┘                           └─────────────────┘
+```
+
+## 📦 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);
+}
+```
+
+## 📖 Use Cases
+
+### Loomer Integration (Theme Designer Side)
+
+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.
+
+#### Basic Data Retrieval
+
+```typescript
+import { Loomer, type SDKResponse } 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);
+  }
+});
+
+// Request CSS variables from the loaded application
+function startListening() {
+  loomer.listenCssVariables(); // Sends PostMessage to iframe
+}
+
+// Example: Build your own theme designer UI
+function buildYourThemeDesigner(response: SDKResponse) {
+  // Extract data from the response payload
+  const cssData = response.payload;
+
+  // Create your own UI based on the received data
+  // YOU implement the color pickers, sliders, inputs, etc.
+  createCustomThemeControls(cssData);
+}
+```
+
+#### Advanced Data Retrieval with Configuration
+
+```typescript
+import { Loomer, type SDKResponse } from '@neomorph/sdk';
+
+const loomer = new Loomer({
+  // Custom iframe container
+  container: document.getElementById('preview-container'),
+
+  // Communication timeout
+  timeout: 5000,
+
+  // Enable debugging
+  debug: true
+});
+
+// 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);
+  });
+}
+```
+
+## 🔒 Security Considerations
+
+- **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
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**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
+
+**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
+
+**Cross-origin errors**
+- Verify CORS headers are properly configured on target application
+- Use appropriate iframe sandbox attributes
+- Consider using a proxy for local development
+
+## 🤝 Contributing
+
+See the main [repository README](../../README.md) for contribution guidelines.
+
+## 📄 License
+
+ISC - See [LICENSE](../../LICENSE) for details.
+
+---
+
+**Made with ❤️ by the Neomorph team**
+
+For more information, visit the [main repository](https://github.com/sinha-sahil/neomorph).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./loomer";
+export * from "./weaver";

package/dist/index.js

@@ -0,0 +1 @@
+function e(e){return"string"==typeof e?e:null}function n(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}const t=function(t){if(n(t)){const i=e(t.requestId),r=e(t.service),a=function(e){if(n(e))return{...e};return null}(t.payload);if(null!==i&&null!==r&&null!==a)return{requestId:i,service:r,payload:a}}return null};class i{applicationFrame;constructor(){this.applicationFrame=null}loadApplication(e,n){if("undefined"!=typeof document&&"undefined"!=typeof window)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",document.body.appendChild(this.applicationFrame),window.addEventListener("message",e=>{const i=t(e.data);n(i)})}catch(e){console.error("🕸️ Weaver: Failed to load application:",e)}else console.warn("🕸️ Weaver: loadApplication() called in non-browser environment")}listenCssVariables(){if("undefined"!=typeof window)try{const e=this.applicationFrame;if(!e?.contentWindow)return void console.error("🕸️ Weaver: No iframe loaded or iframe not ready");e.contentWindow.postMessage(JSON.stringify({source:"skinweaver",payload:JSON.stringify({requestId:"randomId",service:"skinweaver",payload:{action:"listenCssVariables"}})}),"*")}catch(e){console.error("🕸️ Weaver: Failed to send message to iframe:",e)}else console.warn("🕸️ Weaver: listenCssVariables() called in non-browser environment")}}class r{static inject(e="1.0.0"){if("undefined"!=typeof document)try{const n=document.createElement("script");n.src=`https://cdn.jsdelivr.net/gh/sinha-sahil/neomorph/build/weaver/${e}/index.js`,n.type="text/javascript",document.head.appendChild(n)}catch(e){console.error("🕸️ Weaver: Failed to inject weaver script:",e)}else console.warn("🕸️ Weaver: inject() called in non-browser environment")}}export{i as Loomer,r as Weaver};

package/dist/loomer.d.ts

@@ -0,0 +1,7 @@
+import { SDKResponse } from "./types";
+export declare class Loomer {
+    private applicationFrame;
+    constructor();
+    loadApplication(url: string, callback: (response: SDKResponse | null) => void): void;
+    listenCssVariables(): void;
+}

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export type DocumentHost = {
+    name: string;
+    target: DocumentLike;
+};
+export type DocumentLike = Document | ShadowRoot;
+export type CSSProperty = {
+    property: string;
+    value: string;
+};
+export type HostStyles = Map<string, Array<CSSProperty>>;
+export type SDKPayload = {
+    requestId: string;
+    service: string;
+    payload: SDKPayloadPayload;
+};
+export type SDKPayloadPayload = Record<string, unknown>;
+export type SDKResponse = SDKPayload;
+export declare function decodeCssProperty(rawInput: unknown): CSSProperty | null;
+export declare function decodeSDKPayload(rawInput: unknown): SDKPayload | null;
+export declare function decodeSDKPayloadPayload(rawInput: unknown): SDKPayloadPayload | null;
+export declare const decodeSDKResponse: (rawInput: unknown) => SDKResponse | null;

package/dist/weaver.d.ts

@@ -0,0 +1,3 @@
+export declare class Weaver {
+    static inject(version?: string): void;
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@neomorph/sdk",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Core SDK for Neomorph - Advanced theme generator toolkit for web applications",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "rollup -c rollup.config.js --watch",
+    "build": "rollup --config rollup.config.js",
+    "format": "npx prettier --write .",
+    "lint": "prettier --plugin-search-dir . --check . && eslint .",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "neomorph",
+    "theme",
+    "css-variables",
+    "transformation",
+    "ui",
+    "design-system",
+    "theming",
+    "sdk"
+  ],
+  "author": "Sahil Sinha",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sinha-sahil/neomorph.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/sinha-sahil/neomorph#readme",
+  "bugs": {
+    "url": "https://github.com/sinha-sahil/neomorph/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.18.0",
+  "dependencies": {
+    "type-decoder": "^2.1.0"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.36.0",
+    "@rollup/plugin-alias": "^5.1.1",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@typescript-eslint/eslint-plugin": "^8.44.0",
+    "@typescript-eslint/parser": "^8.44.0",
+    "eslint": "^9.36.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.6.2",
+    "rollup": "^4.52.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.2"
+  }
+}