@astralkit/mcp 1.7.1 → 1.9.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.
Files changed (49) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +8 -2
  3. package/dist/api.js +2 -2
  4. package/dist/audit.d.ts +22 -0
  5. package/dist/audit.d.ts.map +1 -0
  6. package/dist/audit.js +402 -0
  7. package/dist/audit.js.map +1 -0
  8. package/dist/auth.d.ts +18 -2
  9. package/dist/auth.d.ts.map +1 -1
  10. package/dist/auth.js +21 -13
  11. package/dist/auth.js.map +1 -1
  12. package/dist/browser.d.ts +1686 -0
  13. package/dist/browser.d.ts.map +1 -0
  14. package/dist/browser.js +51 -0
  15. package/dist/browser.js.map +1 -0
  16. package/dist/capture.d.ts +38 -0
  17. package/dist/capture.d.ts.map +1 -0
  18. package/dist/capture.js +84 -0
  19. package/dist/capture.js.map +1 -0
  20. package/dist/data/art-direction.d.ts +2 -0
  21. package/dist/data/art-direction.d.ts.map +1 -0
  22. package/dist/data/art-direction.js +316 -0
  23. package/dist/data/art-direction.js.map +1 -0
  24. package/dist/data/crosswalk.d.ts +1 -1
  25. package/dist/data/crosswalk.d.ts.map +1 -1
  26. package/dist/data/crosswalk.js +135 -2
  27. package/dist/data/crosswalk.js.map +1 -1
  28. package/dist/data/polish.d.ts.map +1 -1
  29. package/dist/data/polish.js +28 -8
  30. package/dist/data/polish.js.map +1 -1
  31. package/dist/data/rules.d.ts +1 -1
  32. package/dist/data/rules.d.ts.map +1 -1
  33. package/dist/data/rules.js +55 -3
  34. package/dist/data/rules.js.map +1 -1
  35. package/dist/data/screens.d.ts.map +1 -1
  36. package/dist/data/screens.js +36 -4
  37. package/dist/data/screens.js.map +1 -1
  38. package/dist/data/theming.d.ts +2 -0
  39. package/dist/data/theming.d.ts.map +1 -0
  40. package/dist/data/theming.js +71 -0
  41. package/dist/data/theming.js.map +1 -0
  42. package/dist/data/visual.d.ts +7 -0
  43. package/dist/data/visual.d.ts.map +1 -0
  44. package/dist/data/visual.js +130 -0
  45. package/dist/data/visual.js.map +1 -0
  46. package/dist/server.d.ts.map +1 -1
  47. package/dist/server.js +590 -44
  48. package/dist/server.js.map +1 -1
  49. package/package.json +6 -4
package/dist/data/theming.js ADDED
@@ -0,0 +1,71 @@
1
+ // Theming guidance served by the get_theming tool. The #1 cold-agent failure
2
+ // this addresses: shipping default black-and-white UI when the library has 16
3
+ // designed palettes. A themed screen reads "designed"; an unthemed one reads
4
+ // "template". Palette catalog mirrors astralkit/presets (SDK >= 0.7.0).
5
+ export const THEMING = `# AstralKit Theming — never ship default monochrome
6
+
7
+ The library ships **16 designed palettes**. A screen left on the bare default
8
+ theme reads as an unfinished template. UNLESS the brand is deliberately
9
+ monochrome, picking a palette is part of building the screen — not an optional
10
+ polish step.
11
+
12
+ ## How to apply a palette (2 steps)
13
+
14
+ 1. Import the palette stylesheet once (globals.css or root layout):
15
+ \`@import 'astralkit/palettes';\` (CSS) or \`import 'astralkit/palettes'\` (JS entry)
16
+ 2. Set the palette id on the root (or any container to scope it):
17
+ \`<html data-ak-theme="indigo-craft">\` — every ak-* token re-resolves automatically.
18
+
19
+ That's it. No class changes: bg-ak-primary, text-ak-text, borders, gradients all
20
+ re-theme because the palette re-declares the CSS variables.
21
+
22
+ For runtime/theme-builder scenarios, \`astralkit/presets\` exports the same
23
+ palettes as data (\`THEME_PALETTES\`, \`paletteToAkVariables()\` → 129 vars).
24
+
25
+ ## The catalog — pick by brand mood
26
+
27
+ ### Light palettes
28
+ | id | mood — when to pick |
29
+ |---|---|
30
+ | astral-default | Violet on warm paper. The house default — good for dev tools, builders. |
31
+ | warm-earth | Teal primary, coral highlights. Friendly, human, wellness/community products. |
32
+ | slate-pro | Professional gray + blue accent. Fintech, B2B ops, "serious software". |
33
+ | indigo-craft | Warm neutral + indigo. Productivity, project management, calm focus. |
34
+ | medtrackr | Clean white + emerald + mint washes. Healthcare, success-coded domains. |
35
+ | periwinkle | Lavender-white + vivid periwinkle. Fitness, lifestyle, consumer SaaS. |
36
+ | scout-cyan | Crisp white + deep sky-cyan. Analytics, referral/growth dashboards. |
37
+ | pulse | Bone neutrals, ink CTAs, volt-lime selection. High-energy, sporty, bold. |
38
+ | logozap | Warm paper + Zap Blue. Creative tools, brand-forward products. |
39
+
40
+ ### Dark palettes
41
+ | id | mood — when to pick |
42
+ |---|---|
43
+ | volt-noir | True black + volt-lime CTAs. Dark sibling of pulse — gyms, gaming, energy. |
44
+ | neon-noir | Deep violet-black + periwinkle glow. Nightlife, entertainment, web3. |
45
+ | astral-ultraviolet | Deep violet-black, rich purple gradients, coral pulse. Premium dark SaaS. |
46
+ | plasma-orbit | Black-blue + electric indigo/cyan/violet. Data-heavy dark dashboards. |
47
+ | lunar-citron | Obsidian + lavender depth + citron energy. Editorial dark, portfolios. |
48
+ | magenta-circuit | Charcoal + hot magenta + data-green hits. Dev tools, monitoring, cyber. |
49
+ | deep-teal | Dark ocean teal + golden accent. Calm dark, finance, maritime. |
50
+
51
+ ## How to choose (30 seconds, not a project)
52
+
53
+ 1. Read the brief for mood words: "premium" → astral-ultraviolet/slate-pro;
54
+ "friendly" → warm-earth/periwinkle; "energetic" → pulse/volt-noir;
55
+ "professional PM/productivity" → indigo-craft/slate-pro.
56
+ 2. PRESERVE an existing app's mode — dark app gets a dark palette, never flipped.
57
+ 3. Say which palette you chose and why in one line. If the user named brand
58
+ colors that match no palette, use the closest palette and override the
59
+ primary tokens in globals.css — never invent a full ad-hoc color system.
60
+
61
+ ## Anti-patterns
62
+
63
+ - Shipping the bare default theme for a branded product ("black and white
64
+ template syndrome") — the single most common cold-build failure.
65
+ - Hardcoding hexes on elements instead of applying a palette.
66
+ - Mixing palettes across sections of one app (one palette per app; scoped
67
+ data-ak-theme only for deliberate contrast panels).
68
+ - Flipping a dark app to a light palette (or vice versa).
69
+ - Forgetting the 60-30-10 rule still applies WITHIN a palette: neutral canvas
70
+ dominates; the palette's accent belongs on CTAs and active states only.`;
71
+ //# sourceMappingURL=theming.js.map
package/dist/data/theming.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"theming.js","sourceRoot":"","sources":["../../src/data/theming.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,8EAA8E;AAC9E,6EAA6E;AAC7E,wEAAwE;AAExE,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0EAiEmD,CAAC"}
package/dist/data/visual.d.ts ADDED
@@ -0,0 +1,7 @@
1
+ /** verify_visual with a reference image: reference + render + forced compare. */
2
+ export declare function buildVisualVerdictGuide(slug: string, scope: string, viewport: string): string;
3
+ /** screenshot_ui / verify_visual without a slug: self-review against the same failure classes. */
4
+ export declare function buildVisualSelfReviewGuide(scope: string, viewport: string): string;
5
+ /** Graceful degradation when no local browser can be launched. */
6
+ export declare function buildBrowserFallbackGuide(reason: string, hasReference: boolean): string;
7
+ //# sourceMappingURL=visual.d.ts.map
package/dist/data/visual.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"visual.d.ts","sourceRoot":"","sources":["../../src/data/visual.ts"],"names":[],"mappings":"AAwGA,iFAAiF;AACjF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW7F;AAED,kGAAkG;AAClG,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUlF;AAED,kEAAkE;AAClE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,MAAM,CAavF"}
package/dist/data/visual.js ADDED
@@ -0,0 +1,130 @@
1
+ // The visual verification contract for verify_visual / screenshot_ui.
2
+ //
3
+ // validate_code / review_app are static text checks — they cannot see a banner
4
+ // with no image, an undersized logo, an unintended dark band, or a font that
5
+ // silently fell back to system-ui. This rubric is what the model runs its EYES
6
+ // over. It is deliberately a FORCED per-item audit: models shown their own
7
+ // render tend to self-grade "looks good" and move on, so the protocol demands
8
+ // an explicit PASS/FAIL + evidence line for every item before any conclusion.
9
+ /** Failure classes that are invisible to static analysis and obvious in a screenshot. */
10
+ const RUBRIC_ITEMS = [
11
+ {
12
+ id: 'completeness',
13
+ check: 'Every region of the reference exists in the render — banner/hero, nav, media panel, form, footer, badges. ' +
14
+ 'Nothing was dropped or collapsed during re-contenting.',
15
+ },
16
+ {
17
+ id: 'imagery',
18
+ check: 'Every image/illustration ACTUALLY renders: no empty gray/dark boxes, no broken-image icons, no missing hero ' +
19
+ 'photo, no blank <img>. A region the reference fills with a photo must show a real photo (or a deliberate, styled replacement — never a void).',
20
+ },
21
+ {
22
+ id: 'brand',
23
+ check: 'The logo is present and proportionate — same relative size/prominence as the reference (a logo that shrank to a ' +
24
+ 'favicon-sized mark is a FAIL). Brand marks are crisp, not stretched.',
25
+ },
26
+ {
27
+ id: 'surfaces',
28
+ check: 'No unintended background bands, halos, or dark/mismatched blocks around regions. Surface roles read correctly: ' +
29
+ 'page canvas vs card vs inverse panel. Nothing looks like a misapplied wrapper.',
30
+ },
31
+ {
32
+ id: 'typography',
33
+ check: 'Fonts visibly LOADED (Inter — not a system-ui fallback; compare letterforms against the reference), and the ' +
34
+ 'hierarchy shows real size jumps: display/heading vs body vs meta, matching the reference\'s rhythm.',
35
+ },
36
+ {
37
+ id: 'spacing',
38
+ check: 'Spacing rhythm matches the reference: consistent card padding, even gaps, breathing room around sections. ' +
39
+ 'No cramped clusters, no accidental double-gaps (a collapsed ak-* token renders as MISSING space — look for it).',
40
+ },
41
+ {
42
+ id: 'theme',
43
+ check: 'The app\'s theme is preserved (a dark app stayed dark, a light app stayed light) and colors follow 60-30-10: ' +
44
+ 'neutral canvas dominates, accent only on CTAs/active states. Nothing rendered transparent or washed out.',
45
+ },
46
+ {
47
+ id: 'integrity',
48
+ check: 'Nothing is clipped, overlapping, or overflowing: no cut-off text, no elements escaping their container, ' +
49
+ 'no horizontal scrollbar, controls aligned on their rows.',
50
+ },
51
+ {
52
+ id: 'interactive-states',
53
+ check: 'If the component has dropdowns, popovers, modals, or menus: OPEN each one (use screenshot_ui with clickSelector, ' +
54
+ 'or trigger manually) and verify every overlay has complete surface treatment — bg-ak-elevated (background), ' +
55
+ 'border border-ak-border (border), and shadow-lg (shadow). Overlays are the ONE place shadows are required. ' +
56
+ 'A dropdown that floats with no visible container, no border, or no shadow is a FAIL. ' +
57
+ 'Also verify hover/active/focus states on interactive elements show visible feedback.',
58
+ },
59
+ {
60
+ id: 'responsive',
61
+ check: 'Check THREE widths, not two: re-run at viewport:"tablet" (768) and viewport:"mobile" (390). Tablet is where ' +
62
+ 'late-breakpoint bugs hide — content crushed into narrow columns but not yet collapsed; if anything is cramped ' +
63
+ 'at 768, the breakpoint fires too late (collapse where content crushes, not at an arbitrary md/lg). ' +
64
+ 'On mobile, navigation must transform into a REAL mobile pattern: hamburger + Radix Dialog side-sheet, or a ' +
65
+ 'bottom tab bar (2-3 primary destinations + "More" opening a Radix Sheet). A shrunken desktop nav, or one that ' +
66
+ 'simply disappears, is a FAIL.',
67
+ },
68
+ {
69
+ id: 'theme-personality',
70
+ check: 'The screen wears a designed palette, not the bare default: is there a deliberate brand color on CTAs/active ' +
71
+ 'states, themed washes on selection/hover, and a palette that matches the product mood (get_theming has 16)? ' +
72
+ 'A black-and-white screen for a branded product is a FAIL unless the brand is deliberately monochrome. ' +
73
+ 'Also check icon sizes read comfortably: meaningful icons (nav items, list/row leading icons, section markers) ' +
74
+ 'at 20-24px minimum — 16px icons next to 16px text read as clutter, not iconography.',
75
+ },
76
+ ];
77
+ function rubricBlock() {
78
+ return RUBRIC_ITEMS.map((r, i) => `${i + 1}. [${r.id}] ${r.check}`).join('\n');
79
+ }
80
+ const PROTOCOL = `## Verdict protocol (mandatory — do not skip)
81
+
82
+ For EACH rubric item output one line: \`<id>: PASS|FAIL — <one sentence of visual evidence>\`.
83
+ You must cite what you SEE (e.g. "banner region renders a gray void where the reference has a photo"), not what the code says.
84
+
85
+ - ANY FAIL → fix the code, then call verify_visual again. Do NOT declare the work done with an open FAIL.
86
+ - Stop after 3 iterations if something still fails and report the remaining gap honestly.
87
+ - Content is SUPPOSED to differ from the reference (your copy, your logo, your data) — judge structure, completeness,
88
+ and treatment, never literal pixels or literal text.
89
+ - Also glance beyond the rubric: if something looks broken that no item names, treat it as a FAIL too.`;
90
+ /** verify_visual with a reference image: reference + render + forced compare. */
91
+ export function buildVisualVerdictGuide(slug, scope, viewport) {
92
+ return `# Visual verification — compare your render against the reference
93
+
94
+ Image 1 is the AstralKit reference preview ("${slug}" — the quality bar).
95
+ Image 2 is YOUR render (${scope}, ${viewport} viewport), captured just now.
96
+
97
+ Compare them REGION BY REGION against this rubric:
98
+
99
+ ${rubricBlock()}
100
+
101
+ ${PROTOCOL}`;
102
+ }
103
+ /** screenshot_ui / verify_visual without a slug: self-review against the same failure classes. */
104
+ export function buildVisualSelfReviewGuide(scope, viewport) {
105
+ return `# Visual self-review — audit your render
106
+
107
+ This is YOUR render (${scope}, ${viewport} viewport), captured just now. There is no single reference component;
108
+ audit it against the AstralKit bar using this rubric (interpret "reference" as the design you were asked to match,
109
+ or the library's quality standard):
110
+
111
+ ${rubricBlock()}
112
+
113
+ ${PROTOCOL}`;
114
+ }
115
+ /** Graceful degradation when no local browser can be launched. */
116
+ export function buildBrowserFallbackGuide(reason, hasReference) {
117
+ return `# Screenshot capture unavailable — verify visually anyway
118
+
119
+ Could not drive a local browser: ${reason}
120
+
121
+ The visual check is still REQUIRED. Do it with your own tooling:
122
+ 1. Capture the page yourself (your client's browser/screenshot tool, or ask the user for a screenshot of the route).
123
+ ${hasReference ? '2. The reference preview image is included above — compare your capture against it region by region.' : '2. Compare your capture against the design you were asked to match.'}
124
+ 3. Run the full rubric below and output the per-item verdict lines. Fix every FAIL and re-check.
125
+
126
+ ${rubricBlock()}
127
+
128
+ ${PROTOCOL}`;
129
+ }
130
+ //# sourceMappingURL=visual.js.map
package/dist/data/visual.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"visual.js","sourceRoot":"","sources":["../../src/data/visual.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,+EAA+E;AAC/E,2EAA2E;AAC3E,8EAA8E;AAC9E,8EAA8E;AAE9E,yFAAyF;AACzF,MAAM,YAAY,GAAyC;IACzD;QACE,EAAE,EAAE,cAAc;QAClB,KAAK,EACH,4GAA4G;YAC5G,wDAAwD;KAC3D;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EACH,8GAA8G;YAC9G,+IAA+I;KAClJ;IACD;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EACH,kHAAkH;YAClH,sEAAsE;KACzE;IACD;QACE,EAAE,EAAE,UAAU;QACd,KAAK,EACH,iHAAiH;YACjH,gFAAgF;KACnF;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EACH,8GAA8G;YAC9G,qGAAqG;KACxG;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EACH,4GAA4G;YAC5G,iHAAiH;KACpH;IACD;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EACH,+GAA+G;YAC/G,0GAA0G;KAC7G;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EACH,0GAA0G;YAC1G,0DAA0D;KAC7D;IACD;QACE,EAAE,EAAE,oBAAoB;QACxB,KAAK,EACH,mHAAmH;YACnH,8GAA8G;YAC9G,6GAA6G;YAC7G,uFAAuF;YACvF,sFAAsF;KACzF;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EACH,8GAA8G;YAC9G,gHAAgH;YAChH,qGAAqG;YACrG,6GAA6G;YAC7G,gHAAgH;YAChH,+BAA+B;KAClC;IACD;QACE,EAAE,EAAE,mBAAmB;QACvB,KAAK,EACH,8GAA8G;YAC9G,8GAA8G;YAC9G,wGAAwG;YACxG,gHAAgH;YAChH,qFAAqF;KACxF;CACF,CAAC;AAEF,SAAS,WAAW;IAClB,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjF,CAAC;AAED,MAAM,QAAQ,GAAG;;;;;;;;;uGASsF,CAAC;AAExG,iFAAiF;AACjF,MAAM,UAAU,uBAAuB,CAAC,IAAY,EAAE,KAAa,EAAE,QAAgB;IACnF,OAAO;;+CAEsC,IAAI;0BACzB,KAAK,KAAK,QAAQ;;;;EAI1C,WAAW,EAAE;;EAEb,QAAQ,EAAE,CAAC;AACb,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,0BAA0B,CAAC,KAAa,EAAE,QAAgB;IACxE,OAAO;;uBAEc,KAAK,KAAK,QAAQ;;;;EAIvC,WAAW,EAAE;;EAEb,QAAQ,EAAE,CAAC;AACb,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,yBAAyB,CAAC,MAAc,EAAE,YAAqB;IAC7E,OAAO;;mCAE0B,MAAM;;;;EAIvC,YAAY,CAAC,CAAC,CAAC,sGAAsG,CAAC,CAAC,CAAC,qEAAqE;;;EAG7L,WAAW,EAAE;;EAEb,QAAQ,EAAE,CAAC;AACb,CAAC"}
package/dist/server.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AA4kCA,wBAAsB,WAAW,kBA2BhC"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AA4nDA,wBAAsB,WAAW,kBAyChC"}