@symbo.ls/mcp 1.0.21 → 1.0.22

package/bin/symbols-mcp.js

@@ -662,7 +662,7 @@ async function handleTool(name, args) {
   // generate_page
   if (name === 'generate_page') {
     const pageName = args.page_name || 'home'
-    const context = readSkills('RULES.md', 'COMMON_MISTAKES.md', 'PROJECT_STRUCTURE.md', 'PATTERNS.md', 'SNIPPETS.md', 'DEFAULT_LIBRARY.md', 'COMPONENTS.md')
+    const context = readSkills('RULES.md', 'COMMON_MISTAKES.md', 'PROJECT_STRUCTURE.md', 'SHARED_LIBRARIES.md', 'PATTERNS.md', 'SNIPPETS.md', 'DEFAULT_LIBRARY.md', 'COMPONENTS.md')
     return `# Generate Page: ${pageName}\n\n## Description\n${args.description}\n\n## Requirements\n- Export as: \`export const ${pageName} = { ... }\`\n- Page is a plain object composing components\n- Add to pages/index.js route map: \`'/${pageName}': ${pageName}\`\n- Use components by PascalCase key (Header, Footer, Hero, etc.)\n- **MANDATORY: ALL values MUST use design system tokens** — spacing (A, B, C, D), colors (primary, surface, white, gray.5), typography (fontSize: 'B'). ZERO px values, ZERO hex colors, ZERO rgb/hsl.\n- Use Icon component for SVGs — store icons in designSystem/icons\n- NO direct DOM manipulation — all structure via DOMQL declarative syntax\n- Include responsive layout adjustments\n\n## Context — Rules, Structure, Patterns & Snippets\n\n${context}`
   }
 
@@ -692,7 +692,8 @@ async function handleTool(name, args) {
       if (files.includes('index.html') && !files.includes('package.json') && !files.includes('symbols.json')) { envType = 'cdn'; confidence = 'medium' }
     }
     const guide = readSkill('RUNNING_APPS.md')
-    return `# Environment Detection\n\n**Detected: ${envType}** (confidence: ${confidence})\n\n${guide}`
+    const sharedLibsGuide = envType === 'local_project' ? '\n\n## Shared Libraries\n\n' + readSkill('SHARED_LIBRARIES.md') : ''
+    return `# Environment Detection\n\n**Detected: ${envType}** (confidence: ${confidence})\n\n${guide}${sharedLibsGuide}`
   }
 
   // audit_component (sync)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/mcp",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "description": "Symbols.app MCP — docs, code generation, publishing, CLI/SDK reference",
   "mcpName": "io.github.symbo-ls/symbols-mcp",
   "files": [

package/symbols_mcp/skills/AUDIT.md

@@ -202,6 +202,7 @@ Generate or update two files. Keep their scopes strictly separated.
 Include only framework-level findings:
 
 - DOMQL v3 violations
+- UPPERCASE design system keys (COLOR, THEME, etc. — must be lowercase)
 - Event handler misuse
 - Atom/state mispatterns
 - Shorthand inconsistencies

package/symbols_mcp/skills/COMMON_MISTAKES.md

@@ -223,3 +223,19 @@ SpreadsheetCell: { fontSize: 'Z1', width: 'E', ... }
 RowNumberCell:   { fontSize: 'Z1', width: 'C', ... }
 CornerCell:      { fontSize: 'Z1', width: 'C', ... }
 ```
+
+---
+
+## 13. Design system keys — ALWAYS lowercase, never UPPERCASE
+
+```js
+// ❌ WRONG — UPPERCASE keys are deprecated and banned
+import { TYPOGRAPHY, SPACING } from '@symbo.ls/scratch'
+const { COLOR, THEME } = context.designSystem
+set({ COLOR: { blue: '#00f' }, TYPOGRAPHY: { base: 16 } })
+
+// ✅ CORRECT — lowercase keys only
+import { typography, spacing } from '@symbo.ls/scratch'
+const { color, theme } = context.designSystem
+set({ color: { blue: '#00f' }, typography: { base: 16 } })
+```

package/symbols_mcp/skills/COMPONENTS.md

@@ -65,7 +65,8 @@ All atoms support these additional features:
 |---------|--------|
 | Media queries | `@mobile`, `@tablet`, `@tabletSm`, `@dark`, `@light` |
 | Pseudo selectors | `:hover`, `:active`, `:focus-visible` |
-| Conditional cases | `.isActive`, `.disabled`, `.hidden`, `!isActive` |
+| Conditional cases | `.isActive`, `!isActive`, `$isSafari` (global from `context.cases`) |
+| ARIA attributes | `ariaLabel`, `aria: { expanded: true }`, `'aria-label': 'Close'` |
 | Child overrides | `childProps` — one-level child overrides |
 | Children | `children` — arrays or nested object trees |
 | Lifecycle events | `onInit`, `onRender`, `onUpdate`, `onStateUpdate` |

package/symbols_mcp/skills/DEFAULT_COMPONENTS.md

@@ -42,6 +42,7 @@ import pages from './pages/index.js'
 import * as functions from './functions/index.js'
 import * as methods from './methods/index.js'
 import designSystem from './designSystem/index.js'
+import cases from './cases.js'
 import files from './files/index.js'
 
 export default {
@@ -53,6 +54,7 @@ export default {
   functions,
   methods,
   designSystem,
+  cases,
   files
 }
 ```

package/symbols_mcp/skills/DESIGN_SYSTEM.md

@@ -17,8 +17,8 @@ Design system config lives in `designSystem/`. All tokens resolve to CSS via DOM
 | `class.js` | Utility CSS class overrides |
 | `animation.js` | Named keyframe animations |
 | `media.js` | Custom media query breakpoints |
-| `cases.js` | Conditional environment flags |
 | `reset.js` | Global CSS reset overrides |
+| `vars.js` | Custom CSS properties (custom vars) |
 
 ## How Tokens Are Used in Props
 
@@ -488,16 +488,56 @@ Box: {
 
 ---
 
-## CASES
+## Cases
 
-| Case | Condition |
-|---|---|
-| `isSafari` | `true` when browser is Safari |
+Cases are defined in `symbols/cases.js` (not in designSystem) and added to `context.cases`. They are functions that evaluate conditions globally or per-element.
+
+### Defining cases
+
+```js
+// symbols/cases.js
+export default {
+  isSafari: () => /Safari/.test(navigator.userAgent) && !/Chrome/.test(navigator.userAgent),
+  isGeorgian () { return this?.state?.root?.language === 'ka' },
+  isMobile: () => window.innerWidth < 768
+}
+
+// symbols/context.js
+import cases from './cases.js'
+export default { cases, /* ...other context */ }
+```
+
+Case functions receive `element` as `this` (and first arg), but must work without it (for global detection like `isSafari`).
+
+### Using cases in components
 
 ```js
+// $ prefix — global case from context.cases
 Element: { $isSafari: { top: 'Z2', right: 'Z2' } }
+
+// . prefix — props/state first, then context.cases
+Button: { '.isActive': { background: 'blue', aria: { expanded: true } } }
+
+// ! prefix — inverted
+Card: { '!isMobile': { maxWidth: '1200px' } }
+```
+
+Cases work in both CSS props (css-in-props) and HTML attributes (attrs-in-props).
+
+## CSS Custom Properties (vars)
+
+Define initial CSS custom properties in designSystem:
+
+```js
+vars: {
+  '--header-height': '60px',
+  'sidebar-width': '280px',   // auto-prefixed to --sidebar-width
+  gap: '1rem'                  // becomes --gap
+}
 ```
 
+Reference in props: `padding: '--gap'` → resolves to `var(--gap)`. Any `--` prefixed value is auto-wrapped in `var()`.
+
 ---
 
 ## Design System Configuration
@@ -566,7 +606,7 @@ const designSystemConfig = {
 ```
 color, gradient, theme, typography, spacing, timing,
 font, font_family, icons, semantic_icons, svg, svg_data,
-shadow, media, grid, class, reset, unit, animation, cases
+shadow, media, grid, class, reset, unit, animation, vars
 ```
 
 Do NOT wrap these under `props` or other wrappers.
@@ -599,13 +639,30 @@ font: {
 
 ```js
 font: {
-  inter: {
-    400: { url: '/fonts/Inter-Regular.woff2', fontWeight: 400 },
-    700: { url: '/fonts/Inter-Bold.woff2', fontWeight: 700 }
-  }
+  inter: [
+    { url: '/fonts/Inter-Regular.woff2', fontWeight: 400 },
+    { url: '/fonts/Inter-Bold.woff2', fontWeight: 700 }
+  ]
+}
+```
+
+### Multiple format fallbacks (array URL)
+
+```js
+font: {
+  Exo2: [
+    {
+      url: ['Exo2-Medium.woff2', 'Exo2-Medium.woff'],
+      fontWeight: '500',
+      fontStyle: 'normal',
+      fontDisplay: 'swap'
+    }
+  ]
 }
 ```
 
+Generates comma-separated `src` with auto-detected formats per URL.
+
 ---
 
 ## Icons & SVG
@@ -709,6 +766,7 @@ updateVars({ color: { primary: '#ff0000' } })  // Update CSS variables only
 
 ## Common Mistakes
 
+- **NEVER use UPPERCASE keys** (`COLOR`, `THEME`, `TYPOGRAPHY`, etc.) — always use lowercase (`color`, `theme`, `typography`). UPPERCASE is deprecated and banned.
 - Do NOT nest config under `props` or other wrappers
 - Use `font_family` not `fontFamily` in config
 - Define `typography` and `spacing` if you use tokens like `A`, `B2`, or `C+Z`

package/symbols_mcp/skills/DESIGN_TO_CODE.md

@@ -23,7 +23,7 @@ Provide one or more of: design description, wireframe, screenshot, or component
 
 - Complete, copy-paste ready Symbols component objects
 - Responsive implementation using Symbols breakpoint syntax (`@tabletS`, `@mobileL`, etc.)
-- Accessibility: semantic `tag` values, ARIA attributes where needed
+- Accessibility: semantic `tag` values, ARIA attributes via `aria: {}` shorthand / camelCase (`ariaLabel`) / kebab-case (`aria-label`)
 - Loading states via `if` conditionals and state flags
 - Animation via CSS transition properties on the component object
 

package/symbols_mcp/skills/PATTERNS.md

@@ -251,18 +251,25 @@ Box: { tag: 'div', text: 'Submit', onClick: fn }    // div is not a button
 ```js
 // Landmark roles
 Box: { role: 'alert', text: 'Error occurred' }
-Box: { role: 'status', attr: { 'aria-live': 'polite' }, text: '3 results found' }
+Box: { role: 'status', aria: { live: 'polite' }, text: '3 results found' }
 
-// Labels
-Input: { attr: { 'aria-label': 'Search networks' } }
-Button: { icon: 'x', attr: { 'aria-label': 'Close dialog' } }
-Icon: { name: 'settings', attr: { 'aria-hidden': 'true' } }
+// Labels — three equivalent forms:
+Input: { ariaLabel: 'Search networks' }                    // camelCase
+Button: { icon: 'x', aria: { label: 'Close dialog' } }    // object shorthand
+Icon: { name: 'settings', 'aria-hidden': 'true' }         // kebab-case
 
-// Dynamic state
+// Dynamic state via attr block (functions)
 Button: {
   attr: (el, s) => ({ 'aria-expanded': s.isOpen, 'aria-controls': 'dropdown-menu' }),
   onClick: (e, el, s) => s.update({ isOpen: !s.isOpen })
 }
+
+// Dynamic state via conditional cases
+Button: {
+  '.isOpen': { aria: { expanded: true } },
+  '!isOpen': { ariaHidden: true },
+  onClick: (e, el, s) => s.update({ isOpen: !s.isOpen })
+}
 ```
 
 ### Keyboard Navigation

package/symbols_mcp/skills/PROJECT_STRUCTURE.md

@@ -26,6 +26,7 @@ project-root/
 └── symbols/                      # Symbols frontend (client-side)
     ├── index.js                  # Root entry: exports components, pages, state, designSystem, functions
     ├── state.js                  # export default { key: initialValue, ... }
+    ├── cases.js                  # export default { isSafari: () => {}, ... } — conditional cases
     ├── lang.js                   # Translations — root level, NOT in designSystem
     ├── dependencies.js           # export default { 'pkg': 'exact-version' }
     ├── config.js                 # export default { useReset: true, fetch: { adapter: 'supabase', ... }, ... }
@@ -228,9 +229,9 @@ import theme from './theme.js'
 export default { color, theme }
 ```
 
-**What belongs here:** color, gradient, theme, font, typography, spacing, timing, grid, icons, shape, reset, animation, media, cases.
+**What belongs here:** color, gradient, theme, font, typography, spacing, timing, grid, icons, shape, reset, animation, media, vars.
 
-**What does NOT belong here:** translations/lang (use root-level `lang.js`), application state, API config, business logic.
+**What does NOT belong here:** translations/lang (use root-level `lang.js`), cases (use root-level `cases.js`), application state, API config, business logic.
 
 See `DESIGN_SYSTEM.md` for the full token reference.
 
@@ -249,7 +250,7 @@ export default {
 
 // symbols/context.js
 import lang from './lang.js'
-export default { lang, state, components, designSystem, ...config }
+export default { lang, cases, state, components, designSystem, ...config }
 ```
 
 For Supabase-backed translations, configure the `polyglot` key in `config.js`:

package/symbols_mcp/skills/RULES.md

@@ -18,6 +18,27 @@ These rules are absolute. Violations cause silent failures (black page, nothing
 | `children` + `childExtends`   | ~~`$collection`, `$propsCollection`~~   |
 | `children` + `childrenAs: 'state'` | ~~`$stateCollection`~~              |
 | No `extends` needed for Text/Box/Flex; replace `extends: 'Flex'` with `flow: 'x'` or `flow: 'y'` | ~~`extends: 'Text'`~~, ~~`extends: 'Box'`~~, ~~`extends: 'Flex'`~~ |
+| `color: {}`, `theme: {}`, `typography: {}` (lowercase) | ~~`COLOR: {}`, `THEME: {}`, `TYPOGRAPHY: {}`~~ (UPPERCASE) |
+| `context.designSystem.color` | ~~`context.designSystem.COLOR`~~ |
+| `import { typography } from '@symbo.ls/scratch'` | ~~`import { TYPOGRAPHY } from '@symbo.ls/scratch'`~~ |
+
+---
+
+## Rule 0 — Design system keys are ALWAYS lowercase
+
+UPPERCASE design system keys (`COLOR`, `THEME`, `TYPOGRAPHY`, `SPACING`, `TIMING`, `FONT`, `FONT_FAMILY`, `ICONS`, `SHADOW`, `MEDIA`, `GRID`, `ANIMATION`, `RESET`, `SVG`, `GRADIENT`, `SEMANTIC_ICONS`, `CASES`) are **deprecated and strictly banned**.
+
+Always use lowercase: `color`, `theme`, `typography`, `spacing`, `timing`, `font`, `font_family`, `icons`, `shadow`, `media`, `grid`, `animation`, `reset`, `svg`, `gradient`, `vars`.
+
+```js
+// ❌ BANNED
+import { TYPOGRAPHY } from '@symbo.ls/scratch'
+const { COLOR } = context.designSystem
+
+// ✅ CORRECT
+import { typography } from '@symbo.ls/scratch'
+const { color } = context.designSystem
+```
 
 ---
 

package/symbols_mcp/skills/RUNNING_APPS.md

@@ -55,6 +55,7 @@ my-app/
     ├── pages/
     │   ├── index.js          # import-based route map (only file with imports)
     │   └── main.js           # export const main = { extends: 'Page', ... }
+    ├── cases.js              # export default { isSafari: () => {}, ... }
     ├── functions/
     │   ├── index.js          # export * from './myFn.js'
     │   └── myFn.js           # export const myFn = function() {}

package/symbols_mcp/skills/SHARED_LIBRARIES.md

@@ -0,0 +1,313 @@
+# sharedLibraries
+
+sharedLibraries is a mechanism in the Symbols framework that allows projects to inherit components, functions, methods, state, designSystem, pages, files, snippets, and dependencies from external library projects. Libraries are merged into the consuming app's context at runtime — no manual re-exports needed.
+
+---
+
+## Configuration
+
+### symbols.json
+
+Three supported formats:
+
+```json
+// Array of strings (library keys)
+"sharedLibraries": ["brand", "shared"]
+
+// Object with key:version
+"sharedLibraries": { "brand": "1.0.0", "shared": "latest" }
+
+// Object with key:config (used in editor)
+"sharedLibraries": {
+  "brand": { "version": "1.0.0", "destDir": "../brand" },
+  "shared": { "destDir": "../shared" }
+}
+```
+
+All formats are normalized by the CLI (`cli/helpers/symbolsConfig.js:246-268`) to: `[{ key, version, destDir }]`
+
+### sharedLibraries.js
+
+Each package has a `sharedLibraries.js` that imports other packages' `context.js` and exports them as an array:
+
+```js
+import brand from '../brand/context.js'
+import shared from '../shared/context.js'
+
+export default [brand, shared]
+```
+
+For remote libraries fetched from the platform:
+
+```js
+import platformSymboLs from '../.symbols_local/libs/platform.symbo.ls/context.js'
+import docsSymboLs from '../.symbols_local/libs/docs.symbo.ls/context.js'
+
+export default [platformSymboLs, docsSymboLs]
+```
+
+### context.js
+
+The `sharedLibraries` array is included in the context export:
+
+```js
+import sharedLibraries from './sharedLibraries.js'
+import * as components from './components/index.js'
+import * as functions from './functions/index.js'
+// ...
+
+export default {
+  sharedLibraries,
+  components,
+  functions,
+  // ...
+}
+```
+
+---
+
+## Runtime Merge
+
+### Entry Point
+
+`smbls/src/createDomql.js:42-44`:
+
+```js
+if (context.sharedLibraries && context.sharedLibraries.length) {
+  prepareSharedLibs(context)
+}
+```
+
+This runs early in context initialization, **before** designSystem, state, components, and pages are prepared.
+
+### Merge Logic
+
+`smbls/src/prepare.js:240-251`:
+
+```js
+export const prepareSharedLibs = (context) => {
+  const sharedLibraries = context.sharedLibraries
+  for (let i = 0; i < sharedLibraries.length; i++) {
+    const sharedLib = sharedLibraries[i]
+    if (context.type === 'template') {
+      overwriteShallow(context.designSystem, sharedLib.designSystem)
+      deepMerge(context, sharedLib, ['designSystem'], 1)
+    } else {
+      deepMerge(context, sharedLib, [], 1)
+    }
+  }
+}
+```
+
+**Two strategies:**
+
+| App Type | designSystem | Everything Else |
+|----------|-------------|-----------------|
+| **template** | `overwriteShallow` — library completely replaces template's designSystem | `deepMerge` with designSystem excluded |
+| **regular** | `deepMerge` (app wins) | `deepMerge` (app wins) |
+
+### deepMerge Behavior
+
+`smbls/packages/utils/object.js:61-76`:
+
+```js
+export const deepMerge = (element, extend, excludeFrom = METHODS_EXL) => {
+  for (const e in extend) {
+    if (_startsWithDunder(e)) continue       // skip __private
+    if (excludeFrom.includes(e)) continue    // skip excluded keys
+    const elementProp = element[e]
+    const extendProp = extend[e]
+    if (isObjectLike(elementProp) && isObjectLike(extendProp)) {
+      deepMerge(elementProp, extendProp, excludeFrom)  // recursive
+    } else if (elementProp === undefined) {
+      element[e] = extendProp  // only fill undefined slots
+    }
+  }
+  return element
+}
+```
+
+Key rules:
+- **App always wins** — only merges when the app property is `undefined`
+- Skips `__` prefixed properties
+- Recursively merges nested objects
+- Skips METHODS_EXL keys: `node`, `context`, `extends`, `__element`, `__ref`, and all element/state/props methods
+
+---
+
+## Order of Precedence
+
+Libraries are processed sequentially. First library fills undefined slots, second fills remaining, etc.
+
+```
+App's own context  (highest priority — never overwritten)
+  ↑
+sharedLibraries[0]  (fills undefined slots)
+  ↑
+sharedLibraries[1]  (fills remaining undefined slots)
+  ↑
+UIKit atoms         (lowest priority, applied in prepareComponents)
+```
+
+After all merges, `prepareComponents` applies:
+
+```js
+// smbls/src/prepare.js:51-55
+export const prepareComponents = (context) => {
+  return context.components
+    ? { ...UIkitWithPrefix(), ...context.components }
+    : UIkitWithPrefix()
+}
+```
+
+So the final component resolution is: **App > Shared Libraries > UIKit**
+
+---
+
+## What Gets Merged
+
+| Merged | Not Merged (METHODS_EXL) |
+|--------|--------------------------|
+| components | node |
+| functions | context |
+| methods | extends |
+| snippets | __element, __ref |
+| pages / routes | Element methods (set, reset, update, remove, lookup...) |
+| state | State methods (parse, create, destroy, toggle...) |
+| designSystem | Props methods |
+| files | Properties starting with `__` |
+| dependencies | |
+| dependenciesOnDemand | |
+| utils, cases, plugins | |
+
+---
+
+## CLI Integration
+
+### Scaffolding (`cli/bin/fs.js:231-345`)
+
+`scaffoldSharedLibraries()`:
+1. Reads `sharedLibraries` from project JSON
+2. Creates each library as a full project folder via frank's `toFS()`
+3. Default location: `.symbols_local/libs/`
+4. Generates `sharedLibraries.js` with import statements
+
+### Fetch (`cli/bin/fetch.js`)
+
+When fetching from the platform:
+- Pulls full project data including `sharedLibraries` array
+- Each library is a complete Symbols project object
+- Extracts version info and stores in lock file
+
+### toJSON (`frank/toJSON.js:170-183`)
+
+Context modules list includes sharedLibraries:
+
+```js
+const CONTEXT_MODULES = [
+  { name: 'state', path: './state.js', style: 'default' },
+  { name: 'dependencies', path: './dependencies.js', style: 'default' },
+  { name: 'sharedLibraries', path: './sharedLibraries.js', style: 'default' },
+  { name: 'components', path: './components/index.js', style: 'namespace' },
+  { name: 'snippets', path: './snippets/index.js', style: 'namespace' },
+  { name: 'pages', path: './pages/index.js', style: 'default' },
+  { name: 'functions', path: './functions/index.js', style: 'namespace' },
+  { name: 'methods', path: './methods/index.js', style: 'namespace' },
+  { name: 'designSystem', path: './designSystem/index.js', style: 'default' },
+  { name: 'files', path: './files/index.js', style: 'default' },
+  { name: 'config', path: './config.js', style: 'default' }
+]
+```
+
+### Validation (`cli/bin/validate-domql-runner.js:323-342`)
+
+`mergeSharedLibraries()` merges all library exports for DOMQL validation:
+
+```js
+function mergeSharedLibraries(sharedLibraries) {
+  const merged = { pages: {}, components: {}, functions: {}, methods: {}, snippets: {} }
+  for (const lib of libs) {
+    if (isPlainObject(lib?.pages)) Object.assign(merged.pages, lib.pages)
+    if (isPlainObject(lib?.components)) Object.assign(merged.components, lib.components)
+    // ...
+  }
+  return merged
+}
+```
+
+---
+
+## Context Preparation Sequence
+
+```
+prepareContext() {
+  1. Set key, define, cssPropsRegistry, window
+
+  2. prepareSharedLibs(context)
+     → deepMerge each library into context
+
+  3. prepareDesignSystem(context)
+     → uses context.designSystem (now includes shared lib data)
+
+  4. prepareState(app, context)
+     → merges context.state + app.state
+
+  5. preparePages(app, context)
+     → merges app.routes + context.pages
+
+  6. prepareComponents(context)
+     → { ...UIkit, ...context.components }
+
+  7. prepareUtils(context)
+     → spreads utils, router, snippets, functions
+
+  8. prepareDependencies()
+
+  9. prepareMethods(context)
+     → spreads context.methods + require/router
+}
+```
+
+---
+
+## Editor Workspace Map
+
+| Package | sharedLibraries | Role |
+|---------|----------------|------|
+| **brand** | `[]` | Provider — colors, typography, design system |
+| **shared** | none | Provider — common components, functions |
+| **preview** | `[brand, shared]` | Consumer — standalone preview app |
+| **convert** | `[brand, shared]` | Consumer — code converter app |
+| **inspect** | `[brand, cms, shared]` | Consumer — inspector editor |
+| **cms** | `[brand, shared]` | Consumer — CMS editor |
+| **docs** | `[shared]` | Consumer — documentation |
+| **assistant** | `[platform, docs, brand, shared]` | Consumer — AI assistant (remote + local libs) |
+| **no-code** | `[brand, cms]` | Consumer — no-code editor |
+| **canvas** | `[]` | Consumer — canvas editor (no shared libs) |
+
+---
+
+## Key Takeaways
+
+1. **No re-exports needed** — components/functions from a shared library are automatically available in the consuming app's context
+2. **App always wins** — app's own definitions take precedence over shared libraries
+3. **Order matters** — first library in the array has priority over later ones for filling undefined slots
+4. **Templates are special** — designSystem is fully overwritten (shallow) rather than deep-merged
+5. **Methods are protected** — METHODS_EXL prevents shared libraries from overwriting element methods and internal references
+6. **No circular detection** — JavaScript's ESM module system prevents infinite loops naturally; circular deps resolve as undefined values
+
+---
+
+## Source Files
+
+| Purpose | File | Lines |
+|---------|------|-------|
+| Runtime merge entry | `smbls/packages/smbls/src/createDomql.js` | 42-44 |
+| prepareSharedLibs | `smbls/packages/smbls/src/prepare.js` | 240-251 |
+| deepMerge | `smbls/packages/utils/object.js` | 61-76 |
+| overwriteShallow | `smbls/packages/utils/object.js` | 431-439 |
+| METHODS_EXL | `smbls/packages/utils/keys.js` | 147-152 |
+| Config normalization | `smbls/packages/cli/helpers/symbolsConfig.js` | 246-268 |
+| FS scaffolding | `smbls/packages/cli/bin/fs.js` | 231-345 |
+| Context modules | `smbls/packages/frank/toJSON.js` | 170-183 |
+| Validation merge | `smbls/packages/cli/bin/validate-domql-runner.js` | 323-342 |

package/symbols_mcp/skills/SYNTAX.md

@@ -19,9 +19,11 @@ export const MyCard = {
   theme: 'dialog',
   round: 'C',
 
-  // HTML attributes (standard attrs are auto-detected by attrs-in-props)
+  // HTML attributes (auto-detected by attrs-in-props)
   role: 'region',
-  attr: { 'aria-label': ({ props }) => props.label },
+  ariaLabel: 'My card',                                // camelCase → aria-label
+  aria: { describedby: 'desc' },                       // object shorthand → aria-describedby
+  attr: { 'aria-label': ({ props }) => props.label },  // explicit attr block
 
   // State
   state: { open: false },
@@ -150,14 +152,25 @@ export const Hoverable = {
 }
 ```
 
-### CSS Class State Modifiers (Emotion `.className`)
+### Conditional Props (Cases)
+
+Three prefix types for conditional CSS and attributes:
+
+| Prefix | Resolution | Example |
+|---|---|---|
+| `$` | Global case from `context.cases` | `$isSafari: { padding: 'B' }` |
+| `.` | Props/state first, then `context.cases` | `.isActive: { opacity: 1 }` |
+| `!` | Inverted — applies when falsy | `!isActive: { opacity: 0 }` |
+
+Cases are defined in `symbols/cases.js` and added to `context.cases`. Both CSS props and HTML attributes inside conditional blocks are applied.
 
 ```js
 export const Item = {
   opacity: 0.6,
-  '.active':   { opacity: 1, fontWeight: '600' },
-  '.disabled': { opacity: 0.3, pointerEvents: 'none' },
-  '.hidden':   { transform: 'translate3d(0,10%,0)', opacity: 0, visibility: 'hidden' }
+  '.active':   { opacity: 1, fontWeight: '600', aria: { selected: true } },
+  '.disabled': { opacity: 0.3, pointerEvents: 'none', disabled: true },
+  '!active':   { ariaHidden: true },
+  '$isSafari': { padding: 'B' }
 }
 ```