@wcomp/elementum 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,9 +5,25 @@
5
5
  ![Zero Dependencies](https://img.shields.io/badge/runtime%20deps-0-success)
6
6
  ![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
7
7
 
8
- > **Elementum** (*Latin*: /e.leˈmen.tum/) — Direct Latin for *element*, *first principle*, or *foundational matter*.
9
- >
10
- > Just as classical philosophy identified *elementa* as the indivisible building blocks of the physical world, **Elementum** returns web UI to its purest primitives: standard Custom Elements, fine-grained micro-signals, and Shadow DOM encapsulation. No virtual DOM diffing, no hydration mismatches, no vendor lock-in, and zero build tool prerequisites.
8
+ > **Elementum** (*Latin*: /e.leˈmen.tum/) — **An AI-native, framework-independent UI engineering platform** built on standard Custom Elements, fine-grained micro-signals, W3C DTCG tokens, Declarative Shadow DOM SSR, and MCP/AG-UI tooling.
9
+ >
10
+ > **Live Showcase:** https://elementum-sage.vercel.app/ · **Catalog (109 elements):** https://elementum-sage.vercel.app/examples/index.html · **AG-UI Demo:** https://elementum-sage.vercel.app/examples/ag-ui.html · **Live DSD SSR:** https://elementum-sage.vercel.app/ssr
11
+
12
+ ---
13
+
14
+ ## 🧪 Verification & Browser Matrix (Beta — `v0.2.0`)
15
+
16
+ Every architectural claim in Elementum is backed by automated verification in CI:
17
+
18
+ | Verification Layer | Tooling | Scope |
19
+ | :--- | :--- | :--- |
20
+ | **Core Signals & Fuzzing** | `node:test` (`test/signal-torture.test.js`) | Cycle detection, stale-dep cleanup, AbortSignal disposal, 100-graph randomized DAG fuzzer |
21
+ | **Unit & Contract Suite** | `node:test` + `happy-dom` (Node 20/22/24, Ubuntu & Windows) | **208+ tests**, **≥ 95% line coverage**, automated Source-vs-Catalog Diff (`npm run catalog:diff`) |
22
+ | **Real Browser E2E** | Playwright (`npm run test:e2e`) — Chromium, Firefox, WebKit | Native `<dialog>` focus restoration, `ElementInternals` `<form>` submit/reset, mobile `375px` overflow, AG-UI SSE |
23
+ | **Declarative Shadow DOM SSR** | Playwright (`/?hydrate=0` Zero-JS & `/?hydrate=1` Hydrated) | Native `<template shadowrootmode="open">` attachment with JS disabled + clean client hydration |
24
+ | **Accessibility** | `@axe-core/playwright` (WCAG 2.2 AA ruleset) + MCP `lint_accessibility` | Automated real-browser `axe-core` checks on Home, AG-UI, and SSR pages |
25
+ | **Security & MCP Hardening** | `test/security.test.js` | XSS escaping in `template.js` & `ssr.js`, URL sanitization, prototype-pollution guards, 128 KB MCP payload cap |
26
+ | **Performance Benchmarks** | `npm run bench` (`tools/benchmark.js`) | 10,000 signal updates in ~7 ms · 1,000 DSD SSR renders in ~15 ms · 1,000 DOM mounts in ~60 ms |
11
27
 
12
28
  ---
13
29
 
package/mcp/server.js CHANGED
@@ -15,9 +15,41 @@ const rootDir = path.resolve(__dirname, '..');
15
15
  // Load Custom Elements Manifest and Figma Tokens
16
16
  const manifestPath = path.join(rootDir, 'custom-elements.json');
17
17
  const tokensPath = path.join(rootDir, 'tokens', 'figma-tokens.json');
18
+ const pkgPath = path.join(rootDir, 'package.json');
18
19
 
19
20
  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
20
21
  const tokens = JSON.parse(fs.readFileSync(tokensPath, 'utf8'));
22
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
23
+
24
+ const MAX_PAYLOAD_BYTES = 128 * 1024;
25
+ const SAFE_TAG_RE = /^[a-z][a-z0-9]*-[a-z0-9-]+$/;
26
+ const SAFE_CLASS_RE = /^[A-Z][A-Za-z0-9_]*$/;
27
+ const SAFE_ATTR_RE = /^[a-z][a-z0-9-]*$/;
28
+ const GLOBAL_HTML_ATTRS = new Set([
29
+ 'id', 'class', 'style', 'slot', 'part', 'title', 'lang', 'dir', 'hidden',
30
+ 'tabindex', 'role', 'draggable', 'contenteditable', 'spellcheck', 'translate',
31
+ 'unstyled', 'name', 'value', 'disabled', 'required', 'readonly', 'autofocus',
32
+ ]);
33
+
34
+ function escapeAttr(val) {
35
+ return String(val ?? '')
36
+ .replace(/&/g, '&amp;')
37
+ .replace(/"/g, '&quot;')
38
+ .replace(/</g, '&lt;')
39
+ .replace(/>/g, '&gt;');
40
+ }
41
+
42
+ function escapeText(val) {
43
+ return String(val ?? '')
44
+ .replace(/&/g, '&amp;')
45
+ .replace(/</g, '&lt;')
46
+ .replace(/>/g, '&gt;');
47
+ }
48
+
49
+ const allDeclarations = manifest.modules.flatMap((m) =>
50
+ (m.declarations || []).map((d) => ({ ...d, modulePath: m.path }))
51
+ );
52
+ const declByTag = new Map(allDeclarations.map((d) => [d.tagName, d]));
21
53
 
22
54
  const TOOLS = [
23
55
  {
@@ -90,9 +122,20 @@ const TOOLS = [
90
122
  required: ['tag'],
91
123
  },
92
124
  },
125
+ {
126
+ name: 'lint_accessibility',
127
+ description: 'Static HTML accessibility linter for common WCAG 2.2 labeling and attribute issues (not a substitute for real-browser axe-core auditing).',
128
+ inputSchema: {
129
+ type: 'object',
130
+ properties: {
131
+ markup: { type: 'string', description: 'HTML markup snippet to inspect' },
132
+ },
133
+ required: ['markup'],
134
+ },
135
+ },
93
136
  {
94
137
  name: 'validate_accessibility',
95
- description: 'Audits Elementum component usage or HTML markup against WCAG 2.2 accessibility standards.',
138
+ description: 'Alias for lint_accessibility: static HTML accessibility linter for common WCAG 2.2 labeling issues.',
96
139
  inputSchema: {
97
140
  type: 'object',
98
141
  properties: {
@@ -101,33 +144,63 @@ const TOOLS = [
101
144
  required: ['markup'],
102
145
  },
103
146
  },
147
+ {
148
+ name: 'suggest_component',
149
+ description: 'Recommends Elementum Web Components that best match a UI requirement or natural-language query.',
150
+ inputSchema: {
151
+ type: 'object',
152
+ properties: {
153
+ query: { type: 'string', description: 'UI requirement, e.g. "date picker", "code diff", "command palette"' },
154
+ limit: { type: 'number', description: 'Maximum results to return (default 5)' },
155
+ },
156
+ required: ['query'],
157
+ },
158
+ },
159
+ {
160
+ name: 'validate_component_usage',
161
+ description: 'Validates <el-*> tags and attributes in an HTML snippet against the live Custom Elements Manifest to catch hallucinated tags or props.',
162
+ inputSchema: {
163
+ type: 'object',
164
+ properties: {
165
+ markup: { type: 'string', description: 'HTML snippet containing <el-*> components' },
166
+ },
167
+ required: ['markup'],
168
+ },
169
+ },
170
+ {
171
+ name: 'get_component_maturity',
172
+ description: 'Returns machine-readable package version, component count, stability tier, and browser/testing verification metadata.',
173
+ inputSchema: {
174
+ type: 'object',
175
+ properties: {},
176
+ },
177
+ },
104
178
  ];
105
179
 
106
- function handleToolCall(name, args) {
180
+ export function handleToolCall(name, rawArgs) {
181
+ const args = rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {};
182
+
107
183
  if (name === 'list_components') {
108
- const list = manifest.modules.flatMap((m) =>
109
- m.declarations.map((d) => ({
110
- tag: d.tagName,
111
- name: d.name,
112
- description: d.description,
113
- }))
114
- );
115
- return { components: list };
184
+ const list = allDeclarations.map((d) => ({
185
+ tag: d.tagName,
186
+ name: d.name,
187
+ description: d.description,
188
+ }));
189
+ return { count: list.length, components: list };
116
190
  }
117
191
 
118
192
  if (name === 'get_component_doc') {
119
- const match = manifest.modules
120
- .flatMap((m) => m.declarations)
121
- .find((d) => d.tagName === args.tag);
193
+ const tag = typeof args.tag === 'string' ? args.tag.trim().toLowerCase() : '';
194
+ const match = declByTag.get(tag);
122
195
 
123
196
  if (!match) {
124
- return { error: `Component <${args.tag}> not found in manifest.` };
197
+ return { error: `Component <${tag || 'unknown'}> not found in manifest.` };
125
198
  }
126
199
  return match;
127
200
  }
128
201
 
129
202
  if (name === 'list_tokens') {
130
- const category = args?.category || 'all';
203
+ const category = typeof args.category === 'string' ? args.category : 'all';
131
204
  if (category === 'all') {
132
205
  return tokens;
133
206
  }
@@ -135,29 +208,36 @@ function handleToolCall(name, args) {
135
208
  }
136
209
 
137
210
  if (name === 'generate_snippet') {
138
- const { tag, variant, size, label, disabled } = args;
211
+ const tag = typeof args.tag === 'string' ? args.tag.trim().toLowerCase() : '';
212
+ if (!SAFE_TAG_RE.test(tag)) {
213
+ return { error: `Invalid custom element tag name: '${tag}'. Expected lowercase kebab-case with hyphen.` };
214
+ }
215
+ const { variant, size, label, disabled } = args;
139
216
  const attrs = [];
140
- if (variant) attrs.push(`variant="${variant}"`);
141
- if (size) attrs.push(`size="${size}"`);
217
+ if (variant !== undefined && variant !== '') attrs.push(`variant="${escapeAttr(variant)}"`);
218
+ if (size !== undefined && size !== '') attrs.push(`size="${escapeAttr(size)}"`);
142
219
  if (disabled) attrs.push('disabled');
143
220
 
144
221
  const attrStr = attrs.length > 0 ? ' ' + attrs.join(' ') : '';
145
- const content = label || '';
222
+ const content = escapeText(label || '');
146
223
  return {
147
224
  snippet: `<${tag}${attrStr}>${content}</${tag}>`,
148
225
  };
149
226
  }
150
227
 
151
228
  if (name === 'scaffold_component') {
152
- const tag = args.tag.toLowerCase();
153
- const className =
154
- args.name ||
155
- tag
156
- .split('-')
157
- .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
158
- .join('');
229
+ const tag = typeof args.tag === 'string' ? args.tag.trim().toLowerCase() : '';
230
+ if (!SAFE_TAG_RE.test(tag)) {
231
+ return { error: `Invalid custom element tag name: '${tag}'. Expected lowercase kebab-case with hyphen.` };
232
+ }
233
+ const derivedName = tag
234
+ .split('-')
235
+ .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
236
+ .join('');
237
+ const className = typeof args.name === 'string' && SAFE_CLASS_RE.test(args.name) ? args.name : derivedName;
159
238
  const formAssociated = !!args.formAssociated;
160
- const attrs = args.attributes || ['disabled', 'size'];
239
+ const rawAttrs = Array.isArray(args.attributes) ? args.attributes : ['disabled', 'size'];
240
+ const attrs = rawAttrs.filter((a) => typeof a === 'string' && SAFE_ATTR_RE.test(a));
161
241
  const observed = attrs.map((a) => `'${a}'`).join(', ');
162
242
 
163
243
  const signalDefs = attrs
@@ -243,8 +323,8 @@ if (typeof customElements !== 'undefined' && !customElements.get('${tag}')) {
243
323
  };
244
324
  }
245
325
 
246
- if (name === 'validate_accessibility') {
247
- const markup = args.markup || '';
326
+ if (name === 'validate_accessibility' || name === 'lint_accessibility') {
327
+ const markup = typeof args.markup === 'string' ? args.markup : '';
248
328
  const violations = [];
249
329
  const warnings = [];
250
330
  const passed = [];
@@ -327,6 +407,9 @@ if (typeof customElements !== 'undefined' && !customElements.get('${tag}')) {
327
407
  }
328
408
 
329
409
  return {
410
+ scope: 'static-html-lint',
411
+ disclaimer:
412
+ 'Static HTML lint only — run `npm run test:e2e` (@axe-core/playwright) in real browsers for full WCAG 2.2 AA auditing.',
330
413
  valid: violations.length === 0,
331
414
  violationsCount: violations.length,
332
415
  warningsCount: warnings.length,
@@ -336,38 +419,120 @@ if (typeof customElements !== 'undefined' && !customElements.get('${tag}')) {
336
419
  };
337
420
  }
338
421
 
422
+ if (name === 'suggest_component') {
423
+ const query = typeof args.query === 'string' ? args.query.trim().toLowerCase() : '';
424
+ if (!query) return { suggestions: [] };
425
+ const limit = Math.max(1, Math.min(20, Number(args.limit) || 5));
426
+ const terms = query.split(/\s+/).filter(Boolean);
427
+
428
+ const scored = allDeclarations
429
+ .map((d) => {
430
+ const hay = `${d.tagName} ${d.name} ${d.description || ''} ${(d.attributes || []).map((a) => a.name).join(' ')}`.toLowerCase();
431
+ let score = 0;
432
+ for (const t of terms) {
433
+ if (d.tagName.includes(t)) score += 4;
434
+ if ((d.name || '').toLowerCase().includes(t)) score += 3;
435
+ if (hay.includes(t)) score += 1;
436
+ }
437
+ return { tag: d.tagName, name: d.name, description: d.description || '', score };
438
+ })
439
+ .filter((s) => s.score > 0)
440
+ .sort((a, b) => b.score - a.score)
441
+ .slice(0, limit);
442
+
443
+ return { query, suggestions: scored };
444
+ }
445
+
446
+ if (name === 'validate_component_usage') {
447
+ const markup = typeof args.markup === 'string' ? args.markup : '';
448
+ const issues = [];
449
+ const checkedTags = [];
450
+
451
+ for (const match of markup.matchAll(/<(el-[a-z0-9-]+)([^>]*)>/gi)) {
452
+ const tag = match[1].toLowerCase();
453
+ const attrChunk = match[2] || '';
454
+ checkedTags.push(tag);
455
+ const decl = declByTag.get(tag);
456
+ if (!decl) {
457
+ issues.push({ severity: 'error', tag, message: `Unknown Elementum tag <${tag}> (not in custom-elements.json).` });
458
+ continue;
459
+ }
460
+ const allowed = new Set((decl.attributes || []).map((a) => a.name));
461
+ for (const attrMatch of attrChunk.matchAll(/\s([a-zA-Z_:][a-zA-Z0-9_.:-]*)(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?/g)) {
462
+ const attr = attrMatch[1].toLowerCase();
463
+ if (
464
+ allowed.has(attr) ||
465
+ GLOBAL_HTML_ATTRS.has(attr) ||
466
+ attr.startsWith('aria-') ||
467
+ attr.startsWith('data-') ||
468
+ attr.startsWith('on')
469
+ ) {
470
+ continue;
471
+ }
472
+ issues.push({
473
+ severity: 'warning',
474
+ tag,
475
+ attribute: attr,
476
+ message: `Attribute "${attr}" is not declared on <${tag}>. Allowed: ${[...allowed].join(', ') || '(none)'}.`,
477
+ });
478
+ }
479
+ }
480
+
481
+ return {
482
+ valid: issues.filter((i) => i.severity === 'error').length === 0,
483
+ checkedCount: checkedTags.length,
484
+ issues,
485
+ };
486
+ }
487
+
488
+ if (name === 'get_component_maturity') {
489
+ return {
490
+ package: pkg.name,
491
+ version: pkg.version,
492
+ maturity: 'beta',
493
+ componentCount: allDeclarations.length,
494
+ zeroRuntimeDependencies: !pkg.dependencies || Object.keys(pkg.dependencies).length === 0,
495
+ testing: {
496
+ unitRunner: 'node:test + happy-dom',
497
+ browserE2E: 'playwright (Chromium, Firefox, WebKit) + @axe-core/playwright',
498
+ },
499
+ subpathExports: Object.keys(pkg.exports || {}),
500
+ };
501
+ }
502
+
339
503
  throw new Error(`Unknown tool: ${name}`);
340
504
  }
341
505
 
342
- // JSON-RPC stdio protocol loop
343
- const rl = readline.createInterface({
344
- input: process.stdin,
345
- output: process.stdout,
346
- terminal: false,
347
- });
348
-
349
- rl.on('line', (line) => {
350
- if (!line.trim()) return;
506
+ export function handleJsonRpcLine(line) {
507
+ if (typeof line !== 'string' || !line.trim()) return null;
508
+ if (Buffer.byteLength(line, 'utf8') > MAX_PAYLOAD_BYTES) {
509
+ return {
510
+ jsonrpc: '2.0',
511
+ id: null,
512
+ error: { code: -32600, message: `Payload exceeds maximum size of ${MAX_PAYLOAD_BYTES} bytes.` },
513
+ };
514
+ }
351
515
 
352
516
  try {
353
517
  const request = JSON.parse(line);
518
+ if (!request || typeof request !== 'object') {
519
+ return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid JSON-RPC request object.' } };
520
+ }
354
521
 
355
522
  if (request.method === 'tools/list') {
356
- const response = {
523
+ return {
357
524
  jsonrpc: '2.0',
358
- id: request.id,
525
+ id: request.id ?? null,
359
526
  result: { tools: TOOLS },
360
527
  };
361
- process.stdout.write(JSON.stringify(response) + '\n');
362
- return;
363
528
  }
364
529
 
365
530
  if (request.method === 'tools/call') {
366
- const { name, arguments: toolArgs } = request.params;
367
- const result = handleToolCall(name, toolArgs);
368
- const response = {
531
+ const params = request.params && typeof request.params === 'object' ? request.params : {};
532
+ const result = handleToolCall(params.name, params.arguments);
533
+ return {
369
534
  jsonrpc: '2.0',
370
- id: request.id,
535
+ id: request.id ?? null,
371
536
  result: {
372
537
  content: [
373
538
  {
@@ -377,32 +542,52 @@ rl.on('line', (line) => {
377
542
  ],
378
543
  },
379
544
  };
380
- process.stdout.write(JSON.stringify(response) + '\n');
381
- return;
382
545
  }
383
546
 
384
547
  if (request.method === 'initialize') {
385
- const response = {
548
+ return {
386
549
  jsonrpc: '2.0',
387
- id: request.id,
550
+ id: request.id ?? null,
388
551
  result: {
389
552
  protocolVersion: '2024-11-05',
390
553
  capabilities: { tools: {} },
391
554
  serverInfo: {
392
555
  name: 'elementum-design-system-mcp',
393
- version: '0.1.0',
556
+ version: pkg.version,
394
557
  },
395
558
  },
396
559
  };
397
- process.stdout.write(JSON.stringify(response) + '\n');
398
- return;
399
560
  }
561
+
562
+ return {
563
+ jsonrpc: '2.0',
564
+ id: request.id ?? null,
565
+ error: { code: -32601, message: `Method not found: ${request.method}` },
566
+ };
400
567
  } catch (err) {
401
- const errorResponse = {
568
+ return {
402
569
  jsonrpc: '2.0',
403
570
  id: null,
404
571
  error: { code: -32603, message: err.message },
405
572
  };
406
- process.stdout.write(JSON.stringify(errorResponse) + '\n');
407
573
  }
408
- });
574
+ }
575
+
576
+ // Start JSON-RPC stdio loop only when executed directly as CLI
577
+ const isDirectRun =
578
+ process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
579
+
580
+ if (isDirectRun) {
581
+ const rl = readline.createInterface({
582
+ input: process.stdin,
583
+ output: process.stdout,
584
+ terminal: false,
585
+ });
586
+
587
+ rl.on('line', (line) => {
588
+ const response = handleJsonRpcLine(line);
589
+ if (response) {
590
+ process.stdout.write(JSON.stringify(response) + '\n');
591
+ }
592
+ });
593
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wcomp/elementum",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Ultra-lightweight, signal-driven, frameworkless Web Components for modern design systems",
5
5
  "type": "module",
6
6
  "main": "./src/index.js",
@@ -27,6 +27,7 @@
27
27
  },
28
28
  "./ssr": "./src/ssr.js",
29
29
  "./ag-ui": "./src/ag-ui.js",
30
+ "./behaviors": "./src/behaviors/index.js",
30
31
  "./tokens.css": "./src/tokens.css",
31
32
  "./custom-elements.json": "./custom-elements.json",
32
33
  "./components/*": "./src/components/*.js"
@@ -41,6 +42,8 @@
41
42
  },
42
43
  "scripts": {
43
44
  "test": "node --test --experimental-test-coverage",
45
+ "test:e2e": "playwright test",
46
+ "bench": "node tools/benchmark.js",
44
47
  "serve": "node tools/serve.js",
45
48
  "serve:proxy": "node tools/serve.js --proxy",
46
49
  "ssr": "node examples/ssr-server.js",
@@ -69,6 +72,8 @@
69
72
  "author": "wcomp",
70
73
  "license": "MIT",
71
74
  "devDependencies": {
75
+ "@axe-core/playwright": "^4.14.0",
76
+ "@playwright/test": "^1.65.1",
72
77
  "happy-dom": "^21.0.4"
73
78
  }
74
79
  }