@astralkit/mcp 1.5.0 → 1.7.1

package/dist/review.js

@@ -0,0 +1,182 @@
+// review_app — a STRUCTURAL audit (the architectural sibling of validate_code's
+// visual audit). It flags high-signal "messy app" smells: a missing four-state
+// contract, swallowed errors, atomic-design/separation-of-concerns violations,
+// missing mobile navigation, and Radix a11y gaps. Heuristic, not a compiler —
+// deliberately conservative (only flags what it is confident about) so agents
+// trust it. Rules mirror the named anti-patterns in docs/empty-states-guide.md,
+// docs/error-handing.md, and docs/CODE_ARCHITECTURE_GUIDE.md.
+const FILE_SIZE_LIMIT = 300;
+// Strip line/block comments so we don't flag commented-out code.
+function decomment(code) {
+    return code.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+function countLines(s) {
+    return s.split('\n').length;
+}
+// ── Checks that work on any code snippet ──────────────────────────────────────
+function snippetChecks(raw, where) {
+    const issues = [];
+    const code = decomment(raw);
+    const at = where ? ` (${where})` : '';
+    // --- State contract: the "Ghost" (render nothing when empty) ---
+    // `{items.length > 0 && <JSX>}` or `{items.length && <JSX>}` with no empty branch.
+    const ghost = /\{\s*[\w.]+\.length\s*(?:>\s*0\s*)?&&\s*[(<]/.test(code);
+    const hasEmptyHandling = /length\s*===\s*0|length\s*<\s*1|!\w+\??\.length|\bEmptyState\b|isEmpty|no[\s-]?results/i.test(code);
+    if (ghost && !hasEmptyHandling) {
+        issues.push({
+            rule: 'ghost-render',
+            severity: 'high',
+            detail: `Renders a list only when it has items, with no empty branch${at} — users see blank space and assume it's broken (the "Ghost" anti-pattern).`,
+            fix: 'Add an explicit empty branch: `if (!data?.length) return <EmptyState .../>` before rendering the list. See get_build_standards topic "state-lifecycle".',
+        });
+    }
+    // --- State contract: the "Naked Empty" ---
+    if (/return\s*\(?\s*<\w+[^>]*>\s*(No data|Nothing here|No results|Empty|None)\b/i.test(code)) {
+        issues.push({
+            rule: 'naked-empty-state',
+            severity: 'medium',
+            detail: `A bare "No data"-style empty state${at} with no icon, explanation, or action.`,
+            fix: 'Use a real empty state (icon + title + description + CTA) — reuse atoms/empty-state.tsx. See get_build_standards topic "empty-states".',
+        });
+    }
+    // --- State contract: a data view with no loading/empty handling ---
+    const isDataView = /\buseQuery\s*\(|\buseSWR\s*\(/.test(code);
+    const handlesLoadingOrEmpty = /isLoading|isPending|isFetching|Skeleton|EmptyState|length\s*===\s*0|!\w+\??\.length/.test(code);
+    if (isDataView && !handlesLoadingOrEmpty) {
+        issues.push({
+            rule: 'incomplete-states',
+            severity: 'medium',
+            detail: `Fetches data${at} but appears to render no loading skeleton or empty state.`,
+            fix: 'Handle all four states: loading (skeleton) -> empty -> error -> data. See get_build_standards topic "state-lifecycle".',
+        });
+    }
+    // --- Error handling: empty catch ---
+    if (/catch\s*\([^)]*\)\s*\{\s*\}/.test(code)) {
+        issues.push({
+            rule: 'empty-catch',
+            severity: 'high',
+            detail: `An empty catch block${at} silently swallows errors.`,
+            fix: 'Every catch must log AND update the UI (set an error state / show a recovery toast). See get_build_standards topic "error-handling".',
+        });
+    }
+    // --- Error handling: alert() ---
+    if (/(?:^|[^.\w])alert\s*\(/.test(code)) {
+        issues.push({
+            rule: 'alert-used',
+            severity: 'high',
+            detail: `Uses alert()${at} for user feedback.`,
+            fix: 'Replace alert() with a toast (react-hot-toast / Sonner / Radix Toast). Error toasts should not auto-dismiss.',
+        });
+    }
+    // --- Error handling: raw error rendered to the UI (the "Confuser") ---
+    if (/\{\s*\w*[eE]rr\w*\.message\s*\}/.test(code) || /Error\s*\d{3}\b/.test(code) || /ECONNREFUSED|ETIMEDOUT/.test(code)) {
+        issues.push({
+            rule: 'raw-error-shown',
+            severity: 'medium',
+            detail: `A raw error message or error code is shown to the user${at}.`,
+            fix: 'Show a plain-language title + recovery action; log the technical detail. Never surface stack traces / status codes / errno to users. See get_build_standards topic "error-handling".',
+        });
+    }
+    // --- Responsive: a nav with no mobile menu ---
+    const looksLikeNav = /<nav[\s>]|role=["']navigation["']|<header[\s>]/.test(code);
+    const hasDesktopLinks = /hidden\s+md:|md:flex|md:items-center/.test(code);
+    const hasMobileMenu = /md:hidden|Sheet|Drawer|Dialog|hamburger|mobile[-\s]?menu|MobileMenu|\bList\b.*weight|aria-label=["'][^"']*menu/i.test(code);
+    if (looksLikeNav && hasDesktopLinks && !hasMobileMenu) {
+        issues.push({
+            rule: 'missing-mobile-menu',
+            severity: 'high',
+            detail: `Navigation${at} has desktop links but appears to have no mobile menu (no hamburger / Dialog sheet / md:hidden toggle).`,
+            fix: 'Add a hamburger (md:hidden) that opens a Radix Dialog used as a side sheet (w-[85vw] max-w-sm). See get_build_standards topic "responsive" and get_screen_blueprint("nav").',
+        });
+    }
+    // --- Radix: Dialog/AlertDialog content without a Title (a11y) ---
+    const hasDialogContent = /DialogContent|Dialog\.Content|AlertDialogContent|AlertDialog\.Content/.test(code);
+    const hasDialogTitle = /DialogTitle|Dialog\.Title|AlertDialogTitle|AlertDialog\.Title/.test(code);
+    if (hasDialogContent && !hasDialogTitle) {
+        issues.push({
+            rule: 'dialog-without-title',
+            severity: 'medium',
+            detail: `A Radix Dialog/AlertDialog${at} has content but no Title — screen readers announce nothing and Radix warns.`,
+            fix: 'Add a Title (wrap in a visually-hidden span if there is no visible heading) and a description / aria-describedby. See get_build_standards topic "radix".',
+        });
+    }
+    return issues;
+}
+// ── Path-aware checks (only available when `files` is provided) ───────────────
+function fileChecks(path, content) {
+    const issues = [];
+    const lines = countLines(content);
+    const lower = path.toLowerCase();
+    if (lines > FILE_SIZE_LIMIT) {
+        issues.push({
+            rule: 'file-too-large',
+            severity: 'medium',
+            detail: `${path} is ${lines} lines (limit ${FILE_SIZE_LIMIT}).`,
+            fix: 'Split it: extract sub-components, a custom hook, or utilities. See get_build_standards topic "architecture" (file-size limits) and "refactoring".',
+        });
+    }
+    const code = decomment(content);
+    const isAtomOrMolecule = /[\\/](atoms|molecules)[\\/]/.test(lower);
+    const hasSideEffects = /\bfetch\s*\(|\buseQuery\s*\(|\buseSWR\s*\(|await\s+prisma|['"]use server['"]/.test(code);
+    if (isAtomOrMolecule && hasSideEffects) {
+        issues.push({
+            rule: 'atom-with-side-effects',
+            severity: 'high',
+            detail: `${path} is an atom/molecule but fetches data or runs a server action — it should be presentational (data via props).`,
+            fix: 'Move data fetching to a hook/container; keep this component dumb. See get_build_standards topic "architecture" (atomic design + presentational vs container).',
+        });
+    }
+    const isRouteFile = /[\\/]page\.tsx$/.test(lower);
+    const hasBusinessLogic = /\buseState\s*\(|\buseEffect\s*\(|\buseReducer\s*\(/.test(code);
+    if (isRouteFile && hasBusinessLogic && lines > 60) {
+        issues.push({
+            rule: 'fat-page',
+            severity: 'medium',
+            detail: `${path} (a route file) holds component state/logic and is ${lines} lines.`,
+            fix: 'Keep page.tsx thin (wire data + compose). Move state/logic into a hook and the UI into an organism. See get_build_standards topic "architecture".',
+        });
+    }
+    return issues;
+}
+export function reviewApp(input) {
+    const issues = [];
+    if (input.files && Object.keys(input.files).length > 0) {
+        const routePaths = new Set();
+        for (const [path, content] of Object.entries(input.files)) {
+            issues.push(...fileChecks(path, content));
+            issues.push(...snippetChecks(content, path));
+            const lower = path.toLowerCase();
+            const m = lower.match(/(.*[\\/])(page|layout)\.tsx$/);
+            if (m)
+                routePaths.add(m[1]);
+        }
+        // Route hygiene: a route folder with page.tsx should ship error.tsx + loading.tsx.
+        for (const dir of routePaths) {
+            const has = (name) => Object.keys(input.files).some(p => p.toLowerCase() === `${dir}${name}`);
+            const missing = ['error.tsx', 'loading.tsx'].filter(n => !has(n));
+            if (missing.length) {
+                issues.push({
+                    rule: 'route-missing-boundaries',
+                    severity: 'medium',
+                    detail: `Route ${dir} is missing ${missing.join(' + ')}.`,
+                    fix: 'Every route should ship error.tsx (recovery UI) and loading.tsx (skeleton). See get_build_standards topic "error-handling". (Note: only the files you passed were checked.)',
+                });
+            }
+        }
+    }
+    else if (input.code) {
+        issues.push(...snippetChecks(input.code, ''));
+    }
+    const screenNote = input.screenType
+        ? ` For screen-specific must-haves, also see get_screen_blueprint("${input.screenType}").`
+        : '';
+    return {
+        valid: issues.length === 0,
+        issueCount: issues.length,
+        issues,
+        summary: issues.length === 0
+            ? `No structural issues detected. NOTE: review_app is a heuristic structural audit, not a compiler or a substitute for review — it checks for common "messy app" smells (missing states, swallowed errors, layering, mobile nav, Radix a11y), not correctness or compilation.${screenNote}`
+            : `Found ${issues.length} structural issue${issues.length === 1 ? '' : 's'}. Apply each fix; pair with validate_code for visual/token issues. review_app is heuristic — confirm each finding in context.${screenNote}`,
+    };
+}
+//# sourceMappingURL=review.js.map

package/dist/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../src/review.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AA05BA,wBAAsB,WAAW,kBA2BhC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AA4kCA,wBAAsB,WAAW,kBA2BhC"}

package/dist/server.js

@@ -9,7 +9,10 @@ import { PHOSPHOR_ICONS, PHOSPHOR_ICON_NAMES } from './data/icons.js';
 import { SETUP } from './data/setup.js';
 import { CROSSWALK, nearestToken } from './data/crosswalk.js';
 import { buildPolishGuide, ARCHETYPE_KEYS } from './data/polish.js';
-const VERSION = '1.4.0';
+import { buildStandardsGuide, BUILD_STANDARD_TOPICS } from './data/build-standards.js';
+import { buildScreenBlueprint, SCREEN_TYPES } from './data/screens.js';
+import { reviewApp } from './review.js';
+const VERSION = '1.7.1';
 /** Build "raw → ak" suggestions for a list of flagged raw classes (for validate_code). */
 function tokenSuggestions(classes) {
     const seen = new Set();
@@ -26,24 +29,29 @@ function tokenSuggestions(classes) {
 }
 // The golden path — surfaced as server `instructions` so even a naive agent
 // (one that just gets "build X") self-guides to design-system-quality output.
-const SERVER_INSTRUCTIONS = `AstralKit builds polished, accessible, on-brand UI with a design-token system.
+const SERVER_INSTRUCTIONS = `AstralKit builds polished, accessible, on-brand UI. The AstralKit COMPONENT LIBRARY is the source of truth — build FROM real library components; do NOT freestyle UI. Hand-writing a component the library already provides is a failure, even if it is token-compliant.
 
-GOLDEN PATH — follow this for ANY UI request ("build a …", "make a …", a page/section/component):
+GOLDEN PATH — for ANY UI request (build, redesign, or improve a page/section/component):
 1. get_coding_standards — the mandatory rules. Read first.
 2. get_design_tokens — use ONLY ak-* tokens. NEVER raw Tailwind colors (bg-gray-*), NEVER arbitrary values (p-[1rem]).
-3. search_components — find candidate AstralKit components to use as a quality REFERENCE. The library ranges from minimal to bold showcase designs — favor the striking ones that fit.
-4. get_preview — SEE a candidate's rendered design (returns an image) and pick the best-looking fit before committing.
-5. get_component (mode:"recipe") — study the chosen reference and ADAPT it into a new screen; do not paste verbatim. PRESERVE its distinctive design (watermarks, display type, complex layout). The recipe lists the exact tokens, icons, font, dependencies, and setup it uses.
-6. get_icons — before using any Phosphor icon, confirm the name exists here. Never guess icon names.
-7. get_setup — the exact CSS imports + font-load step so the screen actually renders (declaring a font is not loading it).
-8. validate_code — run on your final code and fix every diff it returns.
-9. BUILD IT — validate_code checks conventions, NOT that the code compiles. Always run a real build/typecheck (tsc / next build) before declaring done; it will not catch syntax errors (e.g. a stray */ inside a block comment, unbalanced braces).
+3. search_components — ALWAYS do this before writing any UI. Find the closest real component(s) for what you are building; never skip straight to JSX.
+4. get_preview — SEE candidates (returns an image) and pick the best-looking fit.
+5. get_component (mode:"recipe") — get the real component and REUSE it: keep its structure, layout, and polish. "Adapt" = RE-CONTENT, not rebuild — swap its placeholder copy, nav items, logo, and sample data for the app's real content, and match the app's theme. Do NOT regenerate the layout into something generic, and do NOT freestyle a replacement.
+6. install_component — install the chosen component(s) into the project (e.g. components/ui) and import them. The library piece is what ships; your job is to wire it in + re-content it.
+7. get_icons — confirm Phosphor names exist (never guess). get_setup — the CSS imports + font-load step.
+8. validate_code + review_app — fix every issue, then BUILD (run tsc / next build — validate_code is NOT a compiler; it won't catch syntax errors).
 
-TOKENIZE EXISTING UI (the source is already well-designed; you only need ak-* tokens): SKIP steps 3–5. (a) get_coding_standards, (b) get_design_tokens — it includes a raw-Tailwind→ak CROSSWALK; map every raw class (bg-gray-*, text-sm, p-6, indigo gradients, etc.) to its ak-* token, (c) get_icons — swap any icon library / inline <svg> UI icons to Phosphor, (d) validate_code — it returns the exact "raw → ak" suggestion per flagged class; apply each and re-run until clean, (e) BUILD IT — validate_code is not a compiler; run a real build/typecheck before declaring done. Also: raise sub-16px body to text-ak-base, add focus rings + 48px targets.
+IF NOTHING FITS EXACTLY: still start from the CLOSEST component's recipe and modify it (adjust layout/content as needed) — NEVER from a blank file. The reference sets the quality bar; match it.
 
-POLISH / REVAMP EXISTING UI (the source also has weak hierarchy, cramped/uneven spacing, flat weights, or off-brand surfaces — it needs design-quality elevation, not just tokens): call polish_ui FIRST. It returns a 6-phase revamp procedure (tokenize is Phase 1 inside it), a design-smell rubric, the allowed/forbidden structural changes, a self-check, and per-region reference targets. Pass the UI regions you see (e.g. ["kanban-card","sidebar","form"]). Polish keeps the original layout, content, and behavior — it is a revamp, not a redesign.
+REDESIGN / IMPROVE AN EXISTING APP: for each bespoke piece (sidebar, top bar, cards, forms, hero…) search the AstralKit equivalent, install it, and REPLACE the bespoke one — then RE-CONTENT it with the app's real nav, logo, copy, and data. PRESERVE the app's existing theme: if the app is dark, keep it dark (set the matching data-ak-theme — never flip dark↔light). Never invent colors. ("*-light" showcase components are LIGHT demos — match them to the app's theme, don't drag the app to light.)
 
-Hard rules: 16px body floor (text-ak-base), 48px touch targets (min-h-ak-control-lg), Phosphor icons only, semantic color tokens, focus-visible states. Prefer the resources astralkit://tokens, ://rules, ://icons, ://setup if your client supports them (load once).`;
+TOKENIZE (source already well-designed, only needs ak-* tokens): get_coding_standards → get_design_tokens (raw-Tailwind→ak CROSSWALK) → map every raw class → swap icons to Phosphor → validate_code → build. PRESERVE the source theme — the crosswalk assumes a LIGHT source, so for a dark app map to dark surfaces / inverse roles, not the light defaults (mapping a dark app naively flips it to a broken light theme).
+
+POLISH / REVAMP (weak hierarchy, cramped spacing, off-brand surfaces): call polish_ui FIRST. It keeps the original layout, content, and behavior.
+
+BUILD IT RIGHT (architecture & screen UX): get_build_standards (atomic design, separation of concerns, the loading/empty/error/populated state contract, error handling, responsive/mobile-menu, radix; pass a topic). For a specific screen call get_screen_blueprint(screen_type) — it tells you WHICH AstralKit components to install for that screen + the must-haves. Audit existing/AI-generated code with review_app.
+
+Hard rules: build from library components, never freestyle; 16px body floor (text-ak-base); 48px touch targets; Phosphor icons only; semantic color tokens; PRESERVE the app's theme. Prefer the resources astralkit://tokens, ://rules, ://icons, ://setup, ://standards if your client supports them.`;
 // ─── Security: Input validation ───────────────────────────────────────────────
 const MAX_QUERY_LENGTH = 200;
 const MAX_SLUG_LENGTH = 100;
@@ -59,6 +67,10 @@ function validateSlug(slug) {
 }
 // ─── Security: Periodic auth revalidation ─────────────────────────────────────
 const REVALIDATION_INTERVAL_MS = 10 * 60 * 1000; // 10 minutes
+// During a transient network outage, keep serving on the last good validation
+// for up to this long rather than bricking a valid subscriber. A genuinely
+// invalid/expired key is still caught immediately (that's an AuthError, not transient).
+const AUTH_GRACE_MS = 24 * 60 * 60 * 1000; // 24 hours
 class AuthGuard {
     lastCheck;
     apiKey;
@@ -80,11 +92,17 @@ class AuthGuard {
         }
         catch (err) {
             if (err instanceof AuthError) {
+                // Genuine auth failure (invalid key / plan downgrade) — revoke immediately.
                 this.revoked = true;
                 console.error('[astralkit-mcp] Subscription revalidation failed — access revoked.');
+                throw err;
+            }
+            // Transient (network/timeout, ApiError). Do NOT revoke: keep serving on the
+            // last good validation within the grace window, and let the next call retry.
+            if (Date.now() - this.lastCheck < AUTH_GRACE_MS) {
+                console.error('[astralkit-mcp] Revalidation network error; serving on cached auth (will retry).');
+                return;
             }
-            // Network errors (ApiError with TIMEOUT/NETWORK_ERROR) are transient —
-            // don't permanently revoke; the next check will retry.
             throw err;
         }
     }
@@ -110,14 +128,61 @@ function imageResult(base64, mimeType) {
 }
 // ─── Recipe extraction (makes get_component build-ready / self-describing) ─────
 const VALID_ICONS = new Set(PHOSPHOR_ICON_NAMES);
-/** Strip block, line, and JSX comments to shrink the recipe payload. */
+/**
+ * Strip block, line, and JSX comments to shrink the recipe payload — string-aware,
+ * so it never eats comment-like text INSIDE a string/template literal (e.g. a glob
+ * "src/**\/*.tsx" or a protocol-relative URL "//cdn.example.com"). A naive regex
+ * pass corrupts such source; this walks the code tracking literal context.
+ */
 function stripComments(code) {
-    return code
-        .replace(/\{\/\*[\s\S]*?\*\/\}/g, '') // {/* jsx */}
-        .replace(/\/\*[\s\S]*?\*\//g, '') // /* block */
-        .replace(/(^|[^:])\/\/.*$/gm, '$1') // // line (avoid http://)
-        .replace(/\n{3,}/g, '\n\n')
-        .trim();
+    let out = '';
+    const n = code.length;
+    for (let i = 0; i < n;) {
+        const c = code[i];
+        const c2 = code[i + 1];
+        // string / template literal — copy verbatim (incl. escapes), never scan for comments inside
+        if (c === '"' || c === "'" || c === '`') {
+            const q = c;
+            out += c;
+            i++;
+            while (i < n) {
+                if (code[i] === '\\') {
+                    out += code[i] + (code[i + 1] ?? '');
+                    i += 2;
+                    continue;
+                }
+                out += code[i];
+                const done = code[i] === q;
+                i++;
+                if (done)
+                    break;
+            }
+            continue;
+        }
+        // JSX comment {/* ... */}
+        if (c === '{' && c2 === '/' && code[i + 2] === '*') {
+            const end = code.indexOf('*/}', i + 3);
+            if (end !== -1) {
+                i = end + 3;
+                continue;
+            }
+        }
+        // block comment /* ... */
+        if (c === '/' && c2 === '*') {
+            const end = code.indexOf('*/', i + 2);
+            i = end === -1 ? n : end + 2;
+            continue;
+        }
+        // line comment // ...
+        if (c === '/' && c2 === '/') {
+            while (i < n && code[i] !== '\n')
+                i++;
+            continue;
+        }
+        out += c;
+        i++;
+    }
+    return out.replace(/[ \t]+$/gm, '').replace(/\n{3,}/g, '\n\n').trim();
 }
 /** Every ak-* token/utility referenced in the code (for tokensUsed). */
 function extractAkTokens(code) {
@@ -144,10 +209,10 @@ function createServer(auth, guard, apiKey) {
     server.registerTool('search_components', {
         title: 'Search Components',
         description: 'START HERE when building any UI with AstralKit. Search components by name, description, or category ' +
-            'to find a quality REFERENCE, then call get_component (recipe) to adapt it. ' +
+            'to find the real component to INSTALL & REUSE (never freestyle one the library already has). ' +
             'Read the descriptions: the library ranges from minimal to BOLD showcase designs (watermarks, oversized display type, complex/asymmetric layouts) — prefer the most striking option that fits the brand, not just the most literal keyword match. ' +
-            'Each result includes a previewImage URL; call get_preview(slug) to SEE a candidate and pick the best-looking fit before adapting. ' +
-            'Returns matching components with metadata. (Golden path: get_coding_standards → get_design_tokens → search_components → get_preview → get_component → get_icons → get_setup → validate_code.)',
+            'Each result includes a previewImage URL; call get_preview(slug) to SEE a candidate and pick the best fit, then get_component (recipe) + install_component to reuse it. ' +
+            'Returns matching components with metadata. (Golden path: get_coding_standards → get_design_tokens → search_components → get_preview → get_component → install_component (reuse + re-content) → validate_code.)',
         inputSchema: {
             query: z.string().max(MAX_QUERY_LENGTH).describe('Search query (component name, description, or keyword)'),
             category: z.string().max(MAX_SLUG_LENGTH).optional().describe('Filter by category slug'),
@@ -261,7 +326,7 @@ function createServer(auth, guard, apiKey) {
     });
     server.registerTool('get_component', {
         title: 'Get Component',
-        description: 'Get a build-ready AstralKit component to ADAPT into a new screen (do not paste verbatim). ' +
+        description: 'Get a real, build-ready AstralKit component to INSTALL and REUSE — keep its structure/layout/polish and re-content it (swap copy, nav, logo, data) to fit the app; do not freestyle a replacement. ' +
             'Call search_components/list_components first to find the slug. ' +
             'Default mode "recipe" returns a lean, self-describing payload: source (comments stripped) plus ' +
             'the exact ak-* tokens, Phosphor icons, intended font, setup, and dependencies it uses — so you never guess. ' +
@@ -301,7 +366,7 @@ function createServer(auth, guard, apiKey) {
                 slug: result.slug,
                 framework: fw,
                 previewImage: result.previewImage,
-                howToAdapt: 'Use this as a quality reference and PRESERVE its distinctive design — watermarks, oversized/display type, asymmetric or complex layout, and effects ARE the premium character you want. Rewrite the COPY/content to fit the request, but do NOT flatten it into a generic layout. The library ranges from minimal to bold showcase designs; lean into the striking ones. Build a NEW screen at the same level of polish — do not paste verbatim.',
+                howToAdapt: 'REUSE this component — install it into the project and keep its structure, layout, spacing, and polish (watermarks, display type, complex layout, effects ARE the premium character). ADAPT = RE-CONTENT only: replace placeholder copy, nav items, logo, and sample data with the real app content, and match the app theme (preserve dark/light — never flip it). Do NOT regenerate the layout into something generic, and do NOT freestyle a replacement. If it is not an exact fit, modify THIS recipe rather than building from a blank file.',
                 intendedFont: 'Inter via font-ak-sans (load with next/font and wire to --font-ak-sans — see get_setup)',
                 tokensUsed,
                 iconsUsed: icons.used,
@@ -384,6 +449,51 @@ function createServer(auth, guard, apiKey) {
         }
         return textResult(CODING_STANDARDS);
     });
+    server.registerTool('get_build_standards', {
+        title: 'Get Build Standards',
+        description: 'Get AstralKit STRUCTURAL standards — how to build an app well, not just how to style it. ' +
+            'Covers architecture (atomic design, separation of concerns, layers, file-size limits), the ' +
+            'safe incremental refactoring process for cleaning up a messy app, the loading/empty/error/' +
+            'populated state contract, error handling, responsive/mobile-menu patterns, and Radix correctness. ' +
+            'This complements get_coding_standards (visual rules). Pass a topic to get one section; omit for the index. ' +
+            'Use it before building app structure, or when asked to clean up / refactor vibe-coded code.',
+        inputSchema: {
+            topic: z.enum(BUILD_STANDARD_TOPICS).optional()
+                .describe(`Which section to return. One of: ${BUILD_STANDARD_TOPICS.join(', ')}. Omit to get the index of all topics.`),
+        },
+    }, async ({ topic }) => {
+        try {
+            await guard.check();
+        }
+        catch (err) {
+            if (err instanceof AuthError)
+                return errorResult(err.message);
+            throw err;
+        }
+        return textResult(buildStandardsGuide(topic));
+    });
+    server.registerTool('get_screen_blueprint', {
+        title: 'Get Screen Blueprint',
+        description: 'Get a UX blueprint for a specific screen type — structure, must-haves, anti-patterns, the ' +
+            'four-state (loading/empty/error/populated) requirement, responsive/mobile notes, and exactly ' +
+            'which AstralKit components to INSTALL for this screen (categories + ready search_components queries + polish_ui archetypes) — reuse and re-content them, do not freestyle. ' +
+            'Call this FIRST when building a dashboard, navigation, pricing page, marketing/landing page, ' +
+            'auth screen, onboarding flow, or settings page, so the screen is built right and on-library.',
+        inputSchema: {
+            screen_type: z.enum(SCREEN_TYPES)
+                .describe(`The kind of screen to build. One of: ${SCREEN_TYPES.join(', ')}.`),
+        },
+    }, async ({ screen_type }) => {
+        try {
+            await guard.check();
+        }
+        catch (err) {
+            if (err instanceof AuthError)
+                return errorResult(err.message);
+            throw err;
+        }
+        return textResult(buildScreenBlueprint(screen_type));
+    });
     server.registerTool('get_setup', {
         title: 'Get Setup',
         description: 'Get the exact project setup AstralKit needs to RENDER correctly: the CSS imports (theme + utilities), ' +
@@ -484,8 +594,8 @@ function createServer(auth, guard, apiKey) {
     server.registerTool('get_preview', {
         title: 'Get Preview Image',
         description: 'Get a rendered PREVIEW IMAGE of a component so you can SEE its design before building. ' +
-            'Use it to compare candidates from search_components and pick the most striking one that fits the brand — ' +
-            'then call get_component (recipe) to adapt the chosen one. Returns the image.',
+            'Use it to compare candidates from search_components and pick the best fit — ' +
+            'then call get_component (recipe) to install and reuse the chosen one. Returns the image.',
         inputSchema: {
             slug: z.string().max(MAX_SLUG_LENGTH).describe('Component slug to preview'),
         },
@@ -570,9 +680,12 @@ function createServer(auth, guard, apiKey) {
                 fix: `Replace with the nearest AstralKit token — ${tokenSuggestions([...new Set(rawTailwindColors)])}. (Full crosswalk via get_design_tokens.)`,
             });
         }
-        const arbitraryValues = code.match(/\b(p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap|space-[xy]|w|h|text|rounded|leading)-\[[^\]]+\]/g);
+        // Negative lookbehind for a word-char/hyphen so `h-[…]` inside `min-h-[…]`
+        // (and `w-[…]` inside `max-w-[…]`) is NOT falsely captured — those min-/max-
+        // prefixed values are legitimate (min-h touch targets, max-w width clamps).
+        const arbitraryValues = code.match(/(?<![\w-])(p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap|space-[xy]|w|h|text|rounded|leading)-\[[^\]]+\]/g);
         if (arbitraryValues) {
-            const nonExempt = arbitraryValues.filter(v => !v.startsWith('min-h-[3rem]') && !v.startsWith('h-14'));
+            const nonExempt = arbitraryValues.filter(v => !v.startsWith('h-14'));
             if (nonExempt.length > 0) {
                 issues.push({
                     rule: 'arbitrary-value',
@@ -665,6 +778,36 @@ function createServer(auth, guard, apiKey) {
                 fix: 'GSAP is not licensed for sold products/templates. Use Framer Motion (the MIT `motion` package) or CSS animations / the astralkit motion presets instead.',
             });
         }
+        // Cheap structural smells (the deep structural audit lives in review_app).
+        if (/catch\s*\([^)]*\)\s*\{\s*\}/.test(code)) {
+            issues.push({
+                rule: 'empty-catch',
+                detail: 'Empty catch block silently swallows errors.',
+                fix: 'Every catch must log AND update the UI (error state / recovery toast). See get_build_standards("error-handling").',
+            });
+        }
+        if (/(?:^|[^.\w])alert\s*\(/.test(code)) {
+            issues.push({
+                rule: 'alert-used',
+                detail: 'alert() used for user feedback.',
+                fix: 'Use a toast (react-hot-toast / Sonner / Radix Toast) — error toasts should not auto-dismiss. See get_build_standards("error-handling").',
+            });
+        }
+        if (/\{\s*[\w.]+\.length\s*(?:>\s*0\s*)?&&\s*[(<]/.test(code) &&
+            !/length\s*===\s*0|length\s*<\s*1|!\w+\??\.length|\bEmptyState\b|isEmpty/i.test(code)) {
+            issues.push({
+                rule: 'ghost-render',
+                detail: 'A list is rendered only when non-empty, with no empty branch (the "Ghost" — users see blank space).',
+                fix: 'Add an explicit empty branch before the list: if (!data?.length) return <EmptyState .../>. See get_build_standards("state-lifecycle").',
+            });
+        }
+        if (/return\s*\(?\s*<\w+[^>]*>\s*(No data|Nothing here|No results|Empty)\b/i.test(code)) {
+            issues.push({
+                rule: 'naked-empty-state',
+                detail: 'A bare "No data"-style empty state with no icon, explanation, or action.',
+                fix: 'Use a real empty state (icon + title + description + CTA) — reuse atoms/empty-state.tsx. See get_build_standards("empty-states").',
+            });
+        }
         return jsonResult({
             valid: issues.length === 0,
             issueCount: issues.length,
@@ -674,6 +817,36 @@ function createServer(auth, guard, apiKey) {
                 : `Found ${issues.length} issue${issues.length === 1 ? '' : 's'}. Apply each fix and re-run validate_code until clean. (validate_code checks conventions, not compilation — also run a real build/typecheck.)`,
         });
     });
+    server.registerTool('review_app', {
+        title: 'Review App (structural audit)',
+        description: 'Audit code for STRUCTURAL "messy app" smells — the architectural counterpart to validate_code ' +
+            '(which checks visual/token issues). Flags a missing loading/empty/error state contract, the ' +
+            '"Ghost" and "Naked Empty" anti-patterns, swallowed errors (empty catch, alert(), raw errors ' +
+            'shown to users), atomic-design / separation-of-concerns violations, navigation with no mobile ' +
+            'menu, and Radix a11y gaps. Pass a single `code` snippet, or a `files` map (path -> contents) ' +
+            'for cross-file checks (file-size limits, atoms that fetch, fat page.tsx, routes missing ' +
+            'error.tsx/loading.tsx). Heuristic, not a compiler — pair it with validate_code.',
+        inputSchema: {
+            code: z.string().max(MAX_CODE_LENGTH).optional().describe('A single TSX/JSX file or snippet to audit.'),
+            files: z.record(z.string(), z.string().max(MAX_CODE_LENGTH)).optional()
+                .describe('A map of { "path/to/file.tsx": "contents" } for multi-file checks (file size, layering, route boundaries).'),
+            screen_type: z.enum(SCREEN_TYPES).optional()
+                .describe(`Optional screen type for screen-specific guidance. One of: ${SCREEN_TYPES.join(', ')}.`),
+        },
+    }, async ({ code, files, screen_type }) => {
+        try {
+            await guard.check();
+        }
+        catch (err) {
+            if (err instanceof AuthError)
+                return errorResult(err.message);
+            throw err;
+        }
+        if (!code && (!files || Object.keys(files).length === 0)) {
+            return errorResult('Provide either `code` (a snippet) or `files` (a path -> contents map) to review.');
+        }
+        return jsonResult(reviewApp({ code, files, screenType: screen_type }));
+    });
     // Boosters (Plus/Lifetime only)
     if (canAccessBoosters(auth.tier)) {
         server.registerTool('list_boosters', {
@@ -783,6 +956,12 @@ function createServer(auth, guard, apiKey) {
             contents: [{ uri: 'astralkit://polish', text: buildPolishGuide(), mimeType: 'text/markdown' }],
         };
     });
+    server.registerResource('AstralKit Build Standards', 'astralkit://standards', { description: 'Structural standards — atomic design, separation of concerns, the loading/empty/error/populated state contract, error handling, responsive/mobile-menu, Radix correctness, and the safe refactoring process (the architectural sibling of the visual coding rules)', mimeType: 'text/markdown' }, async () => {
+        await guard.check();
+        return {
+            contents: [{ uri: 'astralkit://standards', text: buildStandardsGuide(), mimeType: 'text/markdown' }],
+        };
+    });
     // ─── Prompts ─────────────────────────────────────────────────────────
     server.registerPrompt('build-with-astralkit', {
         title: 'Build with AstralKit',