@idealyst/mcp-server 1.2.117 → 1.2.118

package/dist/index.cjs

@@ -2689,10 +2689,13 @@ Layout components are **web-only**. Native ignores \`layoutComponent\` entirely.
 layouts/
   AppLayout.web.tsx       \u2190 Real layout with Outlet from @idealyst/navigation
   AppLayout.native.tsx    \u2190 No-op mock (return null)
+  index.ts                \u2190 REQUIRED: base export for TypeScript resolution
   index.web.ts            \u2190 export { AppLayout } from './AppLayout.web'
   index.native.ts         \u2190 export { AppLayout } from './AppLayout.native'
 \`\`\`
 
+> **CRITICAL:** You MUST create a base \`index.ts\` alongside \`index.web.ts\` and \`index.native.ts\`. Without it, TypeScript cannot resolve \`import { AppLayout } from './layouts'\` and you get TS2307. The base \`index.ts\` re-exports from the web version (bundlers pick the platform-specific file at runtime).
+
 ### Example Files
 
 **\`AppLayout.web.tsx\`** \u2014 The real layout:
@@ -2730,6 +2733,11 @@ export function AppLayout() {
 }
 \`\`\`
 
+**\`index.ts\`** \u2014 Base export (REQUIRED for TypeScript module resolution):
+\`\`\`ts
+export { AppLayout } from './AppLayout.web';
+\`\`\`
+
 **\`index.web.ts\`**:
 \`\`\`ts
 export { AppLayout } from './AppLayout.web';
@@ -2760,7 +2768,8 @@ const appRouter: NavigatorParam = {
 > **Key rules:**
 > - Import \`Outlet\` from \`@idealyst/navigation\` (NOT from \`react-router-dom\`)
 > - Layout props do NOT include \`children\` \u2014 content renders via \`<Outlet />\`
-> - Always create both \`.web.tsx\` and \`.native.tsx\` files with platform index files
+> - Always create \`.web.tsx\`, \`.native.tsx\`, AND a base \`index.ts\` \u2014 without the base \`index.ts\`, TypeScript reports TS2307 (cannot find module)
+> - The base \`index.ts\` re-exports from the \`.web\` version; bundlers pick the right platform file at runtime
 
 ## GeneralLayout Component
 
@@ -20246,16 +20255,18 @@ import { View, Text, Button, TextInput, Card, Icon, ... } from '@idealyst/compon
 
 ## How to Use This MCP Server
 
-This server has tools for every aspect of the framework. **Always look up the API before writing code.**
+This server has tools for every aspect of the framework. **Look up APIs as you need them \u2014 don't research everything upfront.**
+
+### Workflow
+
+Write code iteratively. Look up each API right before you use it:
 
-### Workflow (be efficient \u2014 minimize tool calls)
+- **Before using a component** \u2014 call \`get_component_types\` for its props (supports batching: \`get_component_types("Button,Card,Text")\`)
+- **Before using a package** \u2014 call its dedicated \`get_*_guide\` tool with topic \`api\`
+- **Search icons once** \u2014 batch all terms into one call: \`search_icons("home settings check timer")\`
+- **Check recipes** \u2014 \`search_recipes\` for ready-made patterns you can adapt
 
-1. **Start here** \u2014 this intro covers conventions and gotchas
-2. **Look up components** \u2014 call \`get_component_types\` for EVERY component you plan to use. Call it for each component you need. (Card has NO compound components \u2014 no Card.Content/Card.Header)
-3. **Look up packages** \u2014 call the dedicated \`get_*_guide\` tool with topic \`api\` for each \`@idealyst/*\` package
-4. **Check recipes** \u2014 call \`search_recipes\` to find ready-made patterns for common screens
-5. **Search icons ONCE** \u2014 combine all needed icon terms into ONE \`search_icons\` call (e.g., \`"home settings check timer calendar"\`)
-6. **Then write code** \u2014 only after reading the types and guides. Do NOT make additional icon searches \u2014 pick from what you found
+Do NOT try to read all documentation before writing code. Start building, and look things up as you go.
 
 ### Component Tools
 - \`list_components\` / \`search_components\` \u2014 Discover available components
@@ -20265,7 +20276,7 @@ This server has tools for every aspect of the framework. **Always look up the AP
 - \`search_icons\` \u2014 Find Material Design icon names (7,447 available). **Batch your needs**: search once with multiple terms like \`"home settings user check"\` rather than making separate calls per icon
 
 ### Package Guide Tools
-**For any \`@idealyst/*\` package, call its dedicated guide tool with topic \`api\` BEFORE writing code.** These return complete TypeScript interfaces, return types, and correct usage. The generic \`get_package_docs\` tool only has summaries.
+Each \`@idealyst/*\` package has a dedicated guide tool that returns complete TypeScript interfaces and correct usage. The generic \`get_package_docs\` tool only has summaries.
 
 | Package | Guide Tool |
 |---------|-----------|
@@ -20339,7 +20350,7 @@ These are mistakes agents make repeatedly. Each one causes TypeScript compilatio
 
 ### Component Props
 1. **Text** does NOT have \`variant\`, \`intent\`, \`size\`, \`fontSize\`, \`numberOfLines\`, \`ellipsizeMode\`, \`selectable\`, \`textColor\`, or \`onPress\`. Use \`typography\` (\`h1\`\u2013\`h6\`, \`subtitle1\`, \`subtitle2\`, \`body1\`, \`body2\`, \`caption\`), \`weight\` (\`light\`, \`normal\`, \`medium\`, \`semibold\`, \`bold\`), and \`color\` (\`primary\`, \`secondary\`, \`tertiary\`, \`inverse\`). **\`textColor\` is an Icon-only prop** \u2014 Text uses \`color\`. For pressable text, wrap in \`Pressable\` or use \`Button type="text"\`.
-2. **TextInput** does NOT have \`label\`, \`error\`, \`editable\`, \`autoComplete\`, \`keyboardType\`, or \`onChange\`. Compose labels/errors with \`Text\` + \`View\`. Use \`onChangeText\`, \`inputMode\` (\`text\`, \`email\`, \`password\`, \`number\`), and \`textContentType\`. TextArea is different \u2014 it DOES support \`label\`, \`error\`, \`rows\`, \`onChange\`.
+2. **TextInput** does NOT have \`label\`, \`error\`, \`editable\`, \`autoComplete\`, \`keyboardType\`, or \`onChange\`. Compose labels/errors with \`Text\` + \`View\`. Use \`onChangeText\`, \`inputMode\` (\`'text' | 'email' | 'password' | 'number'\` \u2014 NOT \`'decimal'\`, \`'numeric'\`, \`'tel'\`, \`'url'\`), and \`textContentType\`. TextArea is different \u2014 it DOES support \`label\`, \`error\`, \`rows\`, \`onChange\`.
 3. **Button/IconButton** \`type\` is \`'contained' | 'outlined' | 'text'\` \u2014 NOT \`'ghost'\`, \`'solid'\`, \`'default'\`. Button has \`leftIcon\` and \`rightIcon\` \u2014 NOT \`icon\`.
 4. **View** does NOT have \`direction\`, \`align\`, or \`onPress\` props. For touch handling, wrap content in \`Pressable\` from \`@idealyst/components\` (NOT from \`react-native\`): \`<Pressable onPress={handlePress}><View>...</View></Pressable>\`. For horizontal layout use \`style={{ flexDirection: 'row' }}\`. View spacing shorthand props (all accept Size: \`xs\`|\`sm\`|\`md\`|\`lg\`|\`xl\`): \`padding\`, \`paddingVertical\`, \`paddingHorizontal\`, \`margin\`, \`marginVertical\`, \`marginHorizontal\`, \`gap\`/\`spacing\`. Do NOT use \`paddingTop\`, \`paddingBottom\`, \`paddingLeft\`, \`paddingRight\`, \`marginTop\`, \`marginBottom\`, \`marginLeft\`, \`marginRight\` as shorthand props \u2014 they do NOT exist and will cause TS2353. For single-side spacing, use \`style={{ paddingTop: 16 }}\`. Other View props: \`background\`, \`radius\`, \`border\`, \`scrollable\`. \`border\` is \`'none' | 'thin' | 'thick'\` \u2014 NOT \`'outline'\`, \`'solid'\`.
 5. **Badge** \`type\` is \`'filled' | 'outlined' | 'dot'\` \u2014 NOT \`'soft'\`, \`'subtle'\`, \`'solid'\`.
@@ -20353,7 +20364,7 @@ These are mistakes agents make repeatedly. Each one causes TypeScript compilatio
 ### Navigation
 11. Use \`NavigatorProvider\` \u2014 there is NO \`Router\` export.
 12. Use \`useNavigator()\` \u2014 NOT \`useNavigate()\`.
-13. \`navigate()\` takes an **object**: \`navigate({ path: '/settings' })\` \u2014 NOT \`navigate('/settings')\` or \`navigate('routeName', params)\`.
+13. \`navigate()\` takes an **object**: \`navigate({ path: '/settings' })\` \u2014 NOT \`navigate('/settings')\` or \`navigate('routeName', params)\`. To pass data use \`vars\`: \`navigate({ path: '/detail/:id', vars: { id: '123' } })\` \u2014 NOT \`params\`: \`navigate({ path: '/detail', params: { id: '123' } })\` (no \`params\` property exists).
 14. \`useNavigationState\` returns \`Record<string, unknown>\` by default. Always provide a type parameter: \`useNavigationState<{ title?: string }>()\`.
 15. \`useParams()\` does NOT accept generic type arguments. It returns \`Record<string, string>\`. Do NOT write \`useParams<{ id: string }>()\` \u2014 that causes TS2558.
 
@@ -20369,7 +20380,10 @@ These are mistakes agents make repeatedly. Each one causes TypeScript compilatio
    - \`theme.radii.md\` \u2014 border radius values (this DOES exist)
    - **WRONG**: \`<View paddingTop="md">\` \u2014 does NOT exist as a shorthand prop; use \`style={{ paddingTop: 16 }}\`
    - **WRONG**: \`theme.spacing.md\` \u2014 does NOT exist, causes TS2339
+   - **WRONG**: \`theme.colors.background\` \u2014 does NOT exist. \`theme.colors\` has: \`pallet\`, \`surface\`, \`text\`, \`border\`. Use \`theme.colors.surface.primary\` for background colors.
    - **WRONG**: \`theme.colors.intent.danger\` \u2014 does NOT exist; intents are at \`theme.intents.danger\`
+   - **WRONG**: \`theme.intents.primary.bg\` \u2014 IntentValue does NOT have \`bg\` or \`text\`. IntentValue has: \`primary\` (main color string), \`contrast\` (text-on-bg color), \`light\`, \`dark\`
+   - **CORRECT**: \`theme.intents.primary.primary\` for the color, \`theme.intents.primary.contrast\` for text on that color
 
 ### Cross-Platform (CRITICAL)
 20. **Never use raw HTML/SVG elements** (\`<svg>\`, \`<circle>\`, \`<canvas>\`, \`<div>\`, \`<span>\`, \`<input>\`) \u2014 they are web-only and will crash on React Native, just like react-native primitives crash on web. Also never use CSS \`transition\` or \`animation\` properties in styles \u2014 they don't exist on native. If you need custom drawing or circular progress, use \`@idealyst/animate\` hooks or \`@idealyst/charts\` \u2014 never raw SVG.
@@ -20395,7 +20409,7 @@ When working in a CLI-scaffolded workspace (created with \`idealyst init\` + \`i
 ### Package-Specific (call guide tools for full API)
 18. **Audio** (\`@idealyst/audio\`) is **PCM streaming**, NOT file-based. \`recorder.stop()\` returns \`void\`. Data is \`ArrayBufferLike\`, NOT strings. Call \`get_audio_guide\` topic \`api\`.
 19. **Camera** (\`@idealyst/camera\`): Component is \`CameraPreview\`, NOT \`Camera\`. Permission is \`requestPermission()\`, NOT \`requestCameraPermission\`. \`CameraStatus\` is an interface (\`.state\`, \`.permission\`), NOT a string. Call \`get_camera_guide\` topic \`api\`.
-20. **Files** (\`@idealyst/files\`): Method is \`pick()\`, NOT \`pickFiles()\`. \`FileType\` is \`'image' | 'video' | 'audio' | 'document' | 'archive' | 'any'\` \u2014 NOT \`'pdf'\` or \`'doc'\`. Call \`get_files_guide\` topic \`api\`.
+20. **Files** (\`@idealyst/files\`): Method is \`pick()\`, NOT \`pickFiles()\`. \`useFilePicker()\` takes \`{ config: { allowedTypes: ['image'], multiple: true } }\` \u2014 NOT \`{ type: 'image' }\` (no \`type\` prop on options). \`FileType\` is \`'image' | 'video' | 'audio' | 'document' | 'archive' | 'any'\` \u2014 NOT \`'pdf'\` or \`'doc'\`. Call \`get_files_guide\` topic \`api\`.
 21. **Storage** (\`@idealyst/storage\`): Methods are \`getItem()\`/\`setItem()\`, NOT \`get()\`/\`set()\`. Values are string-only. Call \`get_storage_guide\` topic \`api\`.
 22. **Animate** (\`@idealyst/animate\`): There is NO \`useSequence\` or \`useKeyframes\` \u2014 only \`useAnimatedStyle\`, \`useAnimatedValue\`, \`usePresence\`, \`useGradientBorder\`. Easing values are **camelCase**: \`'easeOut'\` NOT \`'ease-out'\`. \`useAnimatedValue\` REQUIRES an initial number: \`useAnimatedValue(0)\` \u2014 NOT \`useAnimatedValue()\`. Call \`get_animate_guide\` topic \`api\`.
 23. **Charts** (\`@idealyst/charts\`): \`ChartDataSeries\` requires \`id\` and \`name\` (NOT \`label\`). \`AxisConfig\` uses \`show\` (NOT \`visible\`). \`tickFormat\` type is \`(value: number | string | Date) => string\`. Call \`get_charts_guide\` topic \`api\`.
@@ -70062,8 +70076,8 @@ function getThemeTypes2(args = {}) {
     const result = getThemeTypes(format);
     if (typeof result === "object" && result !== null) {
       const r = result;
-      r.useThemeNote = 'IMPORTANT: useTheme() returns Theme directly \u2014 NOT wrapped in an object. Correct: `const theme = useTheme();` WRONG: `const { theme } = useTheme();` (causes TS2339). Theme top-level keys: intents, radii, shadows, colors, sizes, interaction, breakpoints. For spacing, use component props (padding="md", gap="md") \u2014 NOT theme.spacing (does NOT exist). For colors: `style={{ backgroundColor: theme.colors.surface.primary }}`. For radii: `style={{ borderRadius: theme.radii.md }}`. For intents: `theme.intents.primary` (NOT theme.colors.intent).';
-      r.themeAccessPatterns = "## Theme Access Patterns\n\n```typescript\nimport { useTheme } from '@idealyst/theme';\nconst theme = useTheme();\n\n// Colors (surface, text, border sub-groups)\ntheme.colors.surface.primary    // main background\ntheme.colors.surface.secondary  // card/section background\ntheme.colors.text.primary       // main text color\ntheme.colors.text.secondary     // muted text\ntheme.colors.text.tertiary      // subtle text\ntheme.colors.text.inverse       // text on dark backgrounds\ntheme.colors.border.primary     // standard border\ntheme.colors.border.secondary   // subtle border\n\n// Intents (semantic colors with bg, text, border)\ntheme.intents.primary.bg        // primary background\ntheme.intents.primary.text      // primary text color\ntheme.intents.danger.bg         // danger/error background\n// Available: primary, secondary, success, warning, danger, info, neutral\n\n// Radii\ntheme.radii.none  // 0\ntheme.radii.sm    // small radius\ntheme.radii.md    // medium radius\ntheme.radii.lg    // large radius\ntheme.radii.xl    // extra large\ntheme.radii.full  // fully rounded\n\n// Shadows\ntheme.shadows.sm   // subtle shadow\ntheme.shadows.md   // medium shadow\ntheme.shadows.lg   // prominent shadow\n\n// Breakpoints (responsive)\ntheme.breakpoints.xs  // 0\ntheme.breakpoints.sm  // small screens\ntheme.breakpoints.md  // medium screens\ntheme.breakpoints.lg  // large screens\n```";
+      r.useThemeNote = "IMPORTANT: useTheme() returns Theme directly \u2014 NOT wrapped in an object. Correct: `const theme = useTheme();` WRONG: `const { theme } = useTheme();` (causes TS2339). Theme top-level keys: intents, radii, shadows, colors, sizes, interaction, breakpoints. For spacing, use component props (padding=\"md\", gap=\"md\") \u2014 NOT theme.spacing (does NOT exist). For colors: `style={{ backgroundColor: theme.colors.surface.primary }}`. For radii: `style={{ borderRadius: theme.radii.md }}`. For intents: `theme.intents.primary.primary` (main color), `.contrast`, `.light`, `.dark`. WRONG: `theme.intents.primary.bg` \u2014 'bg' does NOT exist. WRONG: `theme.intents.primary.text` \u2014 'text' does NOT exist. WRONG: `theme.colors.intent.danger` \u2014 intents are at theme.intents, NOT theme.colors.intent.";
+      r.themeAccessPatterns = "## Theme Access Patterns\n\n```typescript\nimport { useTheme } from '@idealyst/theme';\nconst theme = useTheme();\n\n// Colors (surface, text, border sub-groups)\ntheme.colors.surface.primary    // main background\ntheme.colors.surface.secondary  // card/section background\ntheme.colors.text.primary       // main text color\ntheme.colors.text.secondary     // muted text\ntheme.colors.text.tertiary      // subtle text\ntheme.colors.text.inverse       // text on dark backgrounds\ntheme.colors.border.primary     // standard border\ntheme.colors.border.secondary   // subtle border\n\n// Intents \u2014 IntentValue has: primary, contrast, light, dark\ntheme.intents.primary.primary   // primary intent main color (string)\ntheme.intents.primary.contrast  // contrast color for text on primary bg\ntheme.intents.primary.light     // lighter variant\ntheme.intents.primary.dark      // darker variant\ntheme.intents.danger.primary    // danger intent main color\n// Available intents: primary, secondary, success, warning, danger, info, neutral\n// WRONG: theme.intents.primary.bg \u2014 'bg' does NOT exist on IntentValue\n// WRONG: theme.intents.primary.text \u2014 'text' does NOT exist on IntentValue\n\n// Radii\ntheme.radii.none  // 0\ntheme.radii.sm    // small radius\ntheme.radii.md    // medium radius\ntheme.radii.lg    // large radius\ntheme.radii.xl    // extra large\ntheme.radii.full  // fully rounded\n\n// Shadows\ntheme.shadows.sm   // subtle shadow\ntheme.shadows.md   // medium shadow\ntheme.shadows.lg   // prominent shadow\n\n// Breakpoints (responsive)\ntheme.breakpoints.xs  // 0\ntheme.breakpoints.sm  // small screens\ntheme.breakpoints.md  // medium screens\ntheme.breakpoints.lg  // large screens\n```";
       r.themeSetup = "## Theme Setup (app initialization)\n\n```typescript\nimport { configureThemes, lightTheme, darkTheme, fromTheme } from '@idealyst/theme';\n\n// Build themes from defaults\nconst light = fromTheme(lightTheme).build();\nconst dark = fromTheme(darkTheme).build();\n\n// Configure at app startup (call once, before any component renders)\nconfigureThemes({ themes: { light, dark } });\n```\n\n## Theme Switching at Runtime\n\n```typescript\nimport { ThemeSettings, getColorScheme } from '@idealyst/theme';\n\n// Switch theme\nThemeSettings.setTheme('dark', 'dark');       // (themeName, contentColor)\nThemeSettings.setTheme('light', 'light', true); // animated transition\n\n// Get current theme name\nconst current = ThemeSettings.getThemeName(); // 'light' or 'dark'\n\n// Follow system light/dark preference\nThemeSettings.setAdaptiveThemes(true);\n\n// Get device color scheme\nconst scheme = getColorScheme(); // 'light' | 'dark' | null\n```\n\nIMPORTANT: Do NOT import from 'react-native-unistyles' directly. Use configureThemes (NOT StyleSheet.configure or UnistylesRegistry). Use ThemeSettings (NOT UnistylesRuntime).";
     }
     return jsonResponse(result);