@bookklik/senangstart-css 0.2.5 → 0.2.7

package/.agent/skills/add-utility/scripts/scaffold-utility.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+/**
+ * Scaffold New Utility
+ * 
+ * Helper script to generate boilerplate for a new SenangStart utility.
+ * Creates definition, adds stub to JIT engine, and generates test file.
+ * 
+ * Usage: node .agent/skills/add-utility/scripts/scaffold-utility.js <name> <category>
+ * 
+ * Example: node .agent/skills/add-utility/scripts/scaffold-utility.js glow visual
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, '../../../../');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const utilityName = args[0];
+const category = args[1] || 'visual';
+
+if (!utilityName) {
+  console.log(`
+📦 SenangStart Utility Scaffold
+
+Usage: node scaffold-utility.js <name> [category]
+
+Arguments:
+  name      Utility name (e.g., 'glow', 'outline-offset')
+  category  Category: layout | space | visual (default: visual)
+
+Example:
+  node scaffold-utility.js glow visual
+  node scaffold-utility.js gap-x space
+  node scaffold-utility.js grid-flow layout
+`);
+  process.exit(0);
+}
+
+console.log(`\n🔧 Scaffolding utility: ${utilityName} (${category})\n`);
+
+// ============================================
+// 1. Generate Definition Template
+// ============================================
+
+const definitionTemplate = `/**
+ * ${utilityName} - SenangStart CSS Utility Definition
+ * Category: ${category}
+ * 
+ * TODO: Update values, descriptions, and examples
+ */
+
+export const ${toCamelCase(utilityName)}Definition = {
+  name: '${utilityName}',
+  property: 'TODO-css-property',
+  category: '${category}',
+  attribute: '${category}',
+  description: 'TODO: English description',
+  descriptionMs: 'TODO: Malay description',
+  syntax: '${utilityName}:<value>',
+  values: [
+    { name: 'small', value: 'TODO', description: 'Small value' },
+    { name: 'medium', value: 'TODO', description: 'Medium value' },
+    { name: 'big', value: 'TODO', description: 'Big value' },
+    { name: 'none', value: 'none', description: 'Disable' }
+  ],
+  examples: [
+    { code: '${category}="${utilityName}:small"', description: 'Basic usage' },
+    { code: '${category}="hover:${utilityName}:medium"', description: 'On hover' }
+  ],
+  notes: 'TODO: Additional notes for documentation'
+};
+
+export default { ${toCamelCase(utilityName)}Definition };
+`;
+
+// ============================================
+// 2. Generate Test Template
+// ============================================
+
+const testTemplate = `/**
+ * ${utilityName} Utility Tests
+ */
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+// import { generateVisualRule } from '../../../../src/compiler/generators/css.js';
+
+const mockConfig = {
+  theme: {
+    // TODO: Add required theme scales
+  }
+};
+
+describe('${utilityName} utility', () => {
+  test('generates correct CSS for small value', () => {
+    const token = { 
+      property: '${utilityName}', 
+      value: 'small', 
+      attrType: '${category}' 
+    };
+    // TODO: Uncomment and update when generator is implemented
+    // const result = generate${capitalize(category)}Rule(token, mockConfig);
+    // assert.strictEqual(result, 'TODO-expected-css');
+    assert.ok(true, 'TODO: Implement test');
+  });
+
+  test('generates correct CSS for none value', () => {
+    const token = { 
+      property: '${utilityName}', 
+      value: 'none', 
+      attrType: '${category}' 
+    };
+    // TODO: Implement
+    assert.ok(true, 'TODO: Implement test');
+  });
+
+  test('handles arbitrary values', () => {
+    const token = { 
+      property: '${utilityName}', 
+      value: '10px', 
+      attrType: '${category}',
+      isArbitrary: true
+    };
+    // TODO: Implement
+    assert.ok(true, 'TODO: Implement test');
+  });
+});
+`;
+
+// ============================================
+// 3. Generate JIT Engine Stub
+// ============================================
+
+const jitStubTemplate = `
+// ============================================
+// ${utilityName.toUpperCase()} UTILITY
+// Add this to generate${capitalize(category)}Rule() in src/cdn/senangstart-engine.js
+// ============================================
+
+/*
+if (prop === '${utilityName}') {
+  if (value === 'none') {
+    return 'TODO-css-property: none';
+  }
+  // TODO: Add scale lookup
+  // const scaled = config.theme.TODO_SCALE?.[value];
+  // if (scaled) return \`TODO-css-property: \${scaled}\`;
+  
+  // Arbitrary value support
+  if (value.startsWith('[') && value.endsWith(']')) {
+    return \`TODO-css-property: \${value.slice(1, -1)}\`;
+  }
+}
+*/
+`;
+
+// ============================================
+// Write Files
+// ============================================
+
+// Create output directory
+const outputDir = path.join(rootDir, '.agent', 'skills', 'add-utility', 'generated');
+fs.mkdirSync(outputDir, { recursive: true });
+
+// Write definition
+const defPath = path.join(outputDir, `${utilityName}-definition.js`);
+fs.writeFileSync(defPath, definitionTemplate);
+console.log(`✓ Created definition template: ${path.relative(rootDir, defPath)}`);
+
+// Write test
+const testPath = path.join(outputDir, `${utilityName}.test.js`);
+fs.writeFileSync(testPath, testTemplate);
+console.log(`✓ Created test template: ${path.relative(rootDir, testPath)}`);
+
+// Write JIT stub
+const jitPath = path.join(outputDir, `${utilityName}-jit-stub.js`);
+fs.writeFileSync(jitPath, jitStubTemplate);
+console.log(`✓ Created JIT stub: ${path.relative(rootDir, jitPath)}`);
+
+console.log(`
+📋 Next Steps:
+
+1. Move definition to src/definitions/${category}.js or create new file
+2. Export from src/definitions/index.js
+3. Add handler to src/cdn/senangstart-engine.js (use stub as reference)
+4. Add handler to src/compiler/generators/css.js (same logic)
+5. Move test to tests/unit/compiler/generators/
+6. Run: npm run docs:generate
+7. Run: npm test
+
+Generated files are in: .agent/skills/add-utility/generated/
+`);
+
+// ============================================
+// Helper Functions
+// ============================================
+
+function toCamelCase(str) {
+  return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/.agent/skills/compiler-development/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: Compiler Development
+description: Understanding and extending the CLI compiler with parser, tokenizer, and CSS generators
+---
+
+# Compiler Development
+
+This skill covers the build-time compiler used by the CLI commands (`senangstart build` and `senangstart dev`).
+
+## Compiler Architecture
+
+```
+src/compiler/
+├── index.js          # Main compiler entry point
+├── parser.js         # HTML/JSX attribute extraction
+├── tokenizer.js      # Re-exports from core tokenizer
+└── generators/
+    ├── css.js        # Main CSS generator (~2200 lines)
+    ├── preflight.js  # Base reset styles
+    ├── typescript.js # TypeScript definitions
+    └── ai-context.js # AI context generation
+```
+
+## Compilation Pipeline
+
+```mermaid
+flowchart LR
+    A[Source Files] --> B[Parser]
+    B --> C[Tokenizer]
+    C --> D[Generator]
+    D --> E[CSS Output]
+```
+
+1. **Parser** extracts `layout`, `space`, `visual` attribute values from HTML/JSX
+2. **Tokenizer** parses raw strings into structured token objects
+3. **Generator** transforms tokens into CSS rules
+
+---
+
+## Parser (`src/compiler/parser.js`)
+
+Extracts SenangStart attributes from source files using regex.
+
+### Key Functions
+
+```javascript
+// Parse single file content
+parseSource(content) → { layout: Set, space: Set, visual: Set }
+
+// Parse multiple files
+parseMultipleSources([{path, content}]) → combined results
+```
+
+### Regex Patterns
+
+```javascript
+const ATTRIBUTE_PATTERNS = {
+  layout: /layout\s*=\s*["']([^"']*)\["']/g,
+  space:  /space\s*=\s*["']([^"']*)\["']/g,
+  visual: /visual\s*=\s*["']([^"']*)\["']/g
+};
+```
+
+### Security Features
+- Value length limits (10,000 chars max)
+- Token length limits (500 chars max)
+- Fresh regex per parse to prevent state issues
+
+---
+
+## Tokenizer (`src/core/tokenizer-core.js`)
+
+Transforms raw attribute strings into structured token objects.
+
+### Token Structure
+
+```javascript
+{
+  raw: 'tab:hover:bg:blue-500',  // Original string
+  breakpoint: 'tab',             // null | mob | tab | lap | desk
+  state: 'hover',                // null | hover | focus | active | ...
+  property: 'bg',                // Utility name
+  value: 'blue-500',             // Utility value
+  isArbitrary: false,            // true if [bracketed]
+  attrType: 'visual'             // layout | space | visual
+}
+```
+
+### Key Functions
+
+```javascript
+// Tokenize single attribute string
+tokenize(raw, attrType) → token object
+
+// Tokenize all parsed attributes
+tokenizeAll(parsed) → token array
+
+// Parse token without validation (internal)
+parseToken(raw) → token object
+
+// Validate token structure
+isValidToken(token) → boolean
+
+// Sanitize value (remove semicolons)
+sanitizeValue(value) → string
+```
+
+### Parsing Logic
+
+1. Split by `:` separator
+2. Check first part for breakpoint prefix
+3. Check next part for state prefix
+4. Remaining parts are property and value
+5. Detect arbitrary values with `[brackets]`
+
+---
+
+## CSS Generator (`src/compiler/generators/css.js`)
+
+The core generator transforms tokens into CSS rules.
+
+### Main Functions
+
+```javascript
+// Generate complete CSS from tokens
+generateCSS(tokens, config) → string
+
+// Generate CSS variables from config
+generateCSSVariables(config) → string
+
+// Generate single rule from token
+generateRule(token, config) → string
+
+// Minify CSS output
+minifyCSS(css) → string
+```
+
+### Generator Functions by Category
+
+```javascript
+// Layout utilities (display, flex, grid, position)
+generateLayoutRule(token, config) → string
+
+// Space utilities (padding, margin, gap, width, height)
+generateSpaceRule(token, config) → string
+
+// Visual utilities (colors, borders, shadows, transforms, etc.)
+generateVisualRule(token, config) → string
+```
+
+### Adding a New Generator Pattern
+
+In the appropriate function (e.g., `generateVisualRule`):
+
+```javascript
+// 1. Simple keyword mapping
+if (prop === 'my-utility') {
+  if (value === 'on') return 'my-property: value-on';
+  if (value === 'off') return 'my-property: value-off';
+}
+
+// 2. Scale-based value
+if (prop === 'my-scale-utility') {
+  const v = config.theme.myScale?.[value];
+  if (v) return `my-property: ${v}`;
+}
+
+// 3. Arbitrary value support
+if (prop === 'my-arbitrary-utility') {
+  if (token.isArbitrary) {
+    return `my-property: ${sanitizeArbitraryValue(value)}`;
+  }
+  return `my-property: ${config.theme.myScale?.[value] || value}`;
+}
+
+// 4. Multi-property output
+if (prop === 'inset') {
+  const v = config.theme.spacing[value] || value;
+  return `top: ${v}; right: ${v}; bottom: ${v}; left: ${v}`;
+}
+```
+
+### CSS Selector Generation
+
+Selectors use attribute selectors with proper escaping:
+
+```javascript
+// Simple: [visual~="bg:blue-500"]
+// With state: [visual~="hover:bg:blue-500"]:hover
+// With breakpoint: @media (min-width: 768px) { [layout~="tab:flex"] }
+```
+
+---
+
+## Preflight Generator (`src/compiler/generators/preflight.js`)
+
+Generates base reset styles similar to Tailwind's preflight.
+
+```javascript
+generatePreflight() → string  // Returns CSS reset
+```
+
+---
+
+## Other Generators
+
+### TypeScript (`typescript.js`)
+Generates TypeScript declarations for IntelliSense.
+
+### AI Context (`ai-context.js`)
+Generates context files for AI assistants.
+
+---
+
+## Testing Generators
+
+Unit tests in `tests/unit/compiler/generators/`:
+
+```javascript
+import { test, describe } from 'node:test';
+import { generateVisualRule } from '../../../src/compiler/generators/css.js';
+
+describe('my-utility', () => {
+  test('generates correct CSS', () => {
+    const token = { property: 'my-utility', value: 'on', attrType: 'visual' };
+    const result = generateVisualRule(token, config);
+    assert.strictEqual(result, 'my-property: value-on');
+  });
+});
+```
+
+Run tests:
+```bash
+npm run test:unit
+```
+
+---
+
+## Common Patterns
+
+### State-Aware Generation
+
+```javascript
+function generateRule(token, config) {
+  const css = generateVisualRule(token, config);
+  
+  if (token.state) {
+    // Wrap with pseudo-selector
+    return `${selector}:${token.state} { ${css} }`;
+  }
+  
+  return `${selector} { ${css} }`;
+}
+```
+
+### Responsive Wrapping
+
+```javascript
+if (token.breakpoint) {
+  const minWidth = config.theme.screens[token.breakpoint];
+  return `@media (min-width: ${minWidth}) { ${rule} }`;
+}
+```
+
+### Dark Mode Handling
+
+```javascript
+if (token.state === 'dark') {
+  const darkSelector = getDarkModeSelector(config);
+  return `${darkSelector} ${selector} { ${css} }`;
+}
+```

package/.agent/skills/jit-engine/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: JIT Engine Development
+description: Developing and extending the browser-based JIT CSS engine
+---
+
+# JIT Engine Development
+
+This skill covers development of `src/cdn/senangstart-engine.js` - the browser-based Just-In-Time CSS compilation engine.
+
+## Engine Overview
+
+The JIT engine is an IIFE (~83KB unminified) that runs in the browser with zero configuration. It:
+
+1. Observes DOM for elements with `layout`, `space`, or `visual` attributes
+2. Parses attribute values into utility tokens
+3. Generates CSS rules on-demand
+4. Injects styles via a `<style>` element
+5. Watches for DOM mutations to handle dynamic content
+
+## File Structure
+
+```javascript
+// src/cdn/senangstart-engine.js
+
+// Imports from core modules
+import { BREAKPOINTS, STATES, LAYOUT_KEYWORDS } from '../core/constants.js';
+import { tokenize, parseToken } from '../core/tokenizer-core.js';
+
+(function() {
+  'use strict';
+
+  // 1. Default Configuration
+  const defaultConfig = { theme: {...}, darkMode: 'media', preflight: true };
+
+  // 2. Config Loader
+  function validateConfig(config) {...}
+  function loadInlineConfig() {...}
+  function mergeConfig(user) {...}
+
+  // 3. CSS Variable Generator
+  function generateCSSVariables(config) {...}
+
+  // 4. Utility Generators
+  function generateLayoutRule(prop, value, config) {...}
+  function generateSpaceRule(prop, value, config) {...}
+  function generateVisualRule(prop, value, config) {...}
+
+  // 5. DOM Observer & Style Injection
+  function processElement(element) {...}
+  function observeDOM() {...}
+
+  // 6. Initialize
+  document.addEventListener('DOMContentLoaded', init);
+})();
+```
+
+## Default Configuration
+
+Located at the top of the engine, `defaultConfig` defines all theme scales:
+
+```javascript
+const defaultConfig = {
+  theme: {
+    spacing: {
+      'none': '0px',
+      'thin': '1px',
+      // ... full scale
+      'vast-10x': '384px'
+    },
+    radius: { 'none': '0px', 'small': '4px', ... },
+    shadow: { 'none': 'none', 'small': '...', ... },
+    fontSize: { 'tiny': '0.75rem', ... },
+    fontWeight: { 'normal': '400', 'medium': '500', 'bold': '700' },
+    screens: { 'mob': '480px', 'tab': '768px', ... },
+    colors: { 'white': '#FFFFFF', 'primary': '#3B82F6', ... },
+    zIndex: { 'base': '0', 'low': '10', ... },
+    ring: { 'none': '0px', 'thin': '1px', ... }
+  },
+  darkMode: 'media',
+  preflight: true
+};
+```
+
+## Adding a New Utility Handler
+
+### Step 1: Identify the Category
+
+- `generateLayoutRule()` - For layout utilities
+- `generateSpaceRule()` - For spacing utilities  
+- `generateVisualRule()` - For visual utilities
+
+### Step 2: Add Pattern Matching
+
+In the appropriate generator function:
+
+```javascript
+function generateVisualRule(prop, value, config) {
+  // Existing handlers...
+
+  // ADD: New utility
+  if (prop === 'my-utility') {
+    // Option 1: Simple keyword mapping
+    if (value === 'on') return 'my-css-property: value-on';
+    if (value === 'off') return 'my-css-property: value-off';
+    
+    // Option 2: Scale-based
+    const scaleValue = config.theme.myScale?.[value];
+    if (scaleValue) return `my-css-property: ${scaleValue}`;
+    
+    // Option 3: Arbitrary value with [brackets]
+    if (value.startsWith('[') && value.endsWith(']')) {
+      return `my-css-property: ${value.slice(1, -1)}`;
+    }
+  }
+
+  // ... rest of handlers
+}
+```
+
+### Step 3: Add Scale (if needed)
+
+Add to `defaultConfig.theme`:
+
+```javascript
+myScale: {
+  'small': '4px',
+  'medium': '8px',
+  'big': '16px'
+}
+```
+
+And update `generateCSSVariables()` if CSS variables are needed:
+
+```javascript
+// In generateCSSVariables():
+Object.entries(config.theme.myScale).forEach(([name, value]) => {
+  vars += `  --ss-my-scale-${name}: ${value};\n`;
+});
+```
+
+## State Handling
+
+States (hover, focus, etc.) are handled automatically. The engine:
+
+1. Detects state prefix: `hover:bg:blue-500`
+2. Generates CSS with pseudo-selector: `.hover\:bg\:blue-500:hover { ... }`
+
+State parsing occurs in the main processing loop before calling generators.
+
+## Responsive Handling
+
+Breakpoints wrap rules in media queries:
+
+1. Detects breakpoint prefix: `mob:flex`
+2. Generates: `@media (min-width: 480px) { .mob\:flex { display: flex } }`
+
+## CSS Variable System
+
+The engine generates CSS variables for all theme values:
+
+```css
+:root {
+  --ss-spacing-none: 0px;
+  --ss-spacing-thin: 1px;
+  --ss-radius-small: 4px;
+  --ss-color-primary: #3B82F6;
+  /* ... */
+}
+```
+
+Utilities can reference variables:
+```javascript
+return `border-radius: var(--ss-radius-${value})`;
+```
+
+## Testing Engine Changes
+
+After modifying the engine:
+
+1. **Rebuild distribution:**
+```bash
+npm run build:dist
+```
+
+2. **Test in playground:**
+   Open `playground/index.html` in browser
+
+3. **Run unit tests:**
+```bash
+npm run test:unit
+```
+
+4. **Check sync tests:**
+```bash
+npm run test:sync
+```
+
+## Common Patterns
+
+### Color Handler
+```javascript
+if (prop === 'text') {
+  const color = config.theme.colors[value];
+  if (color) return `color: ${color}`;
+  // Support arbitrary colors
+  if (value.startsWith('[')) return `color: ${value.slice(1, -1)}`;
+}
+```
+
+### Spacing Handler
+```javascript
+if (prop === 'p') { // padding shorthand
+  const space = config.theme.spacing[value];
+  if (space) return `padding: ${space}`;
+}
+```
+
+### Multi-Property Handler
+```javascript
+if (prop === 'inset') {
+  const v = config.theme.spacing[value] || value;
+  return `top: ${v}; right: ${v}; bottom: ${v}; left: ${v}`;
+}
+```
+
+### Transform Handler
+```javascript
+if (prop === 'rotate') {
+  return `--ss-rotate: ${value}deg; transform: var(--ss-transform)`;
+}
+```
+
+## Debugging
+
+Enable debug logging by adding early in the IIFE:
+```javascript
+const DEBUG = true;
+function log(...args) { if (DEBUG) console.log('[SS]', ...args); }
+```
+
+Then sprinkle `log()` calls in key functions.