refactor: clean CopilotKit setup for CI/CD

Author: wenluowang

components/CopilotKitWrapper.jsx

@@ -1,190 +1,61 @@
-// CopilotKitWrapper.jsx
+"use client";
+
 import { CopilotKit } from "@copilotkit/react-core";
-import {
-  CopilotSidebar,
-  useCopilotChatSuggestions,
-} from "@copilotkit/react-ui";
-import "@copilotkit/react-ui/styles.css";
+import { CopilotSidebar, useCopilotChatSuggestions } from "@copilotkit/react-ui";
+
+// System instructions for the assistant
+const SYSTEM_INSTRUCTIONS = `You are the Dspread Documentation Assistant, helping developers with Dspread payment terminals and SDKs.
+
+**KEY GUIDELINES:**
+- Use 80% direct documentation quotes, 20% explanation
+- Only reference official Dspread GitHub repositories for code examples
+- Include links to docs: https://dspreadorg.github.io/docs
+
+**DOCUMENTATION PAGES:**
+- Android: /android-terminals/overview, /android-terminals/set-up-integration, /android-terminals/accept-card-payment
+- Linux: /linux-terminals/getting-started, /linux-terminals/transaction-flow
+- Payment: /payment-gateway-aws, /key-management-aws, /emv-l3-testing
+- Management: /tms-larktms, /cloud-speaker
 
-// Component with CopilotKit suggestions
-function AppWithSuggestions({ children }) {
-  // Use the official CopilotKit hook for suggestions
+**OFFICIAL REPOS:**
+- Android SDK: https://github.com/DspreadOrg/android
+- Linux Tools: https://github.com/DspreadOrg/qpos-linux-tools
+- D30 Linux: https://github.com/DspreadOrg/D30-linux
+
+Only use code from these repos. If no official example exists, state that clearly.`;
+
+// Suggestions component
+function ChatSuggestions({ children }) {
   useCopilotChatSuggestions({
-    instructions: `You are a Dspread documentation assistant. Suggest contextual questions that users might want to ask about:
-    
-    🚀 Getting Started: "How do I set up the development environment for Android terminals?" or "What are the first steps to integrate with Dspread?"
-    📱 Android SDK: "How do I accept EMV card payments?" or "How do I implement PIN entry for smartpos terminals?"  
-    🐧 Linux Terminals: "How do I compile and run my first Linux terminal application?" or "What is the transaction flow for Linux terminals?"
-    💳 Payment Processing: "How does EMV online authorization work?" or "How do I handle reversal data in failed transactions?"
-    🖨️ Print & Scanner: "How do I implement receipt printing?" or "How do I use the QR code scanner service?"
-    🔐 Security & P2PE: "How does AWS Payment Cryptography work with Dspread?" or "How do I handle encrypted payment data?"
-    🧪 Testing & Certification: "How do I prepare for EMV L3 testing?" or "What are the common issues in Linux terminal development?"
-    ⚙️ Terminal Management: "How does LarkTMS work?" or "How do I manage terminals remotely?"
-    
-    Generate specific, actionable questions that would help developers implement features or solve problems using the actual Dspread documentation content.`,
+    instructions: `Suggest questions about: Android SDK setup, EMV payments, Linux terminals, receipt printing, QR scanning, AWS payment cryptography, EMV L3 testing, LarkTMS.`,
     minSuggestions: 3,
-    maxSuggestions: 6,
+    maxSuggestions: 5,
   });
 
   return (
     <>
       <CopilotSidebar
-        instructions={`You are the Dspread Documentation Assistant, a specialized AI helper for developers working with Dspread payment terminals, SDKs, and integration guides.
-
-**CRITICAL INSTRUCTION - CONTENT RATIO**:
-- **80% DIRECT DOCUMENTATION QUOTES**: Your answers should be 80% direct quotes and code examples from the original documentation
-- **20% EXPLANATION**: Limit your own explanations to 20% of the response, primarily to connect documentation sections
-
-**DOCUMENTATION BASE**:
-- All documentation is available at: https://dspreadorg.github.io/docs
-
-**CODE EXAMPLES SOURCE - MANDATORY**:
-- **ONLY use code examples from official Dspread GitHub repositories**
-- **Android SDK examples**: Reference only from official Dspread Android SDK repositories
-- **Linux Terminal examples**: Reference only from official Dspread Linux terminal repositories  
-- **Demo applications**: Reference only from Dspread's official demo repositories
-- **NEVER use generic public code examples or third-party code that is not from Dspread**
-- **ALWAYS verify code examples come from official Dspread GitHub organization repositories**
-
-**IMPORTANT GUIDELINES:**
-1. **Direct quotation**: Use exact language from documentation for technical explanations
-2. **Official code only**: Only reference code examples from official Dspread GitHub repositories mentioned in the documentation
-3. **Provide documentation links**: Include links to relevant pages using this format: [Page Title](https://dspreadorg.github.io/docs/page-path)
-4. **Repository references**: When providing code examples, clearly indicate the source repository from Dspread's GitHub organization
-5. **Minimal interpretation**: Only add your own explanations to connect concepts or highlight key points
-6. **Accuracy verification**: Ensure all code examples are from legitimate Dspread sources, not generic or third-party implementations
-7. **Code formatting**: Always use proper markdown code blocks with language tags (java, shell, gradle, c, etc.)
-
-**AVAILABLE DOCUMENTATION PAGES:**
-- **Overview**: [Overview](https://dspreadorg.github.io/docs/) - Main documentation entry point
-- **Planning**: [Plan Your Integration](https://dspreadorg.github.io/docs/plan-your-integration) - Integration planning guide
-- **How Terminal Works**: [How Terminal Works](https://dspreadorg.github.io/docs/how-terminal-works) - Terminal architecture overview
-
-**Android Terminals**:
-- [Android Terminals Overview](https://dspreadorg.github.io/docs/android-terminals/overview) - SDK compatibility for Smart and mPOS terminals
-- [Set Up Integration](https://dspreadorg.github.io/docs/android-terminals/set-up-integration) - Development environment and SDK setup
-- [Accept Card Payment](https://dspreadorg.github.io/docs/android-terminals/accept-card-payment) - Complete payment processing workflow
-- [Print Receipt](https://dspreadorg.github.io/docs/android-terminals/print-receipt) - Receipt printing implementation
-- [Scanner QR/Bar Code](https://dspreadorg.github.io/docs/android-terminals/scanner-qr-bar-code) - QR code scanning service
-- [Customize OS](https://dspreadorg.github.io/docs/android-terminals/customize-os) - OS customization guide
-
-**Linux Terminals**:
-- [Getting Started](https://dspreadorg.github.io/docs/linux-terminals/getting-started) - Development environment setup and compilation
-- [Transaction Flow](https://dspreadorg.github.io/docs/linux-terminals/transaction-flow) - Payment transaction flow and code examples
-- [Additional Resources](https://dspreadorg.github.io/docs/linux-terminals/additional-resources) - External repositories and tools
-- [Best Practices](https://dspreadorg.github.io/docs/linux-terminals/best-practices) - Linux terminal development best practices
-- [Common Issues](https://dspreadorg.github.io/docs/linux-terminals/common-issues) - Troubleshooting and common problems
-
-**Payment & Security**:
-- [Payment Gateway (AWS)](https://dspreadorg.github.io/docs/payment-gateway-aws) - AWS Payment Cryptography integration and DUKPT decryption
-- [Key Management (AWS)](https://dspreadorg.github.io/docs/key-management-aws) - AWS key management and encryption
-- [EMV L3 Testing](https://dspreadorg.github.io/docs/emv-l3-testing) - EMV Level 3 certification testing
-
-**Device Management**:
-- [TMS LarkTMS](https://dspreadorg.github.io/docs/tms-larktms) - Terminal Management System
-- [Cloud Speaker](https://dspreadorg.github.io/docs/cloud-speaker) - Cloud speaker functionality
-
-**OFFICIAL REPOSITORY SOURCES** (Reference code examples ONLY from these):
-
-**Android SDK and Demo Repositories:**
-- **Primary Android SDK**: https://github.com/DspreadOrg/android - Main Android SDK repository with demo source code and releases
-- **Android SDK Releases**: https://github.com/DspreadOrg/android/releases - Download SDKs and demo APKs
-- **Keystore Example**: https://github.com/DspreadOrg/android/blob/master/pos_android_studio_demo/pos_android_studio_app/app.keystore
-
-**Linux Terminal Repositories:**
-- **QPOS Linux Tools**: https://github.com/DspreadOrg/qpos-linux-tools - Development environment and tools
-- **D30 Linux SDK**: https://github.com/DspreadOrg/D30-linux - D30 terminal Linux SDK and examples
-- **QPOS Linux SDK**: https://github.com/dspreadOrg/qpos-linux - QPOS Plus terminal Linux SDK and examples
-- **QPOS Linux (GitLab)**: https://gitlab.com/dspread/qpos-linux - Alternative Linux SDK repository
-- **QPOS Linux Tools (GitLab)**: https://gitlab.com/dspread/qpos-linux-tools - Alternative tools repository
-
-**Documentation Repository:**
-- **Documentation Source**: https://github.com/DspreadOrg/docs - This documentation website source code
-
-**STRICT CODE REFERENCING POLICY:**
-- Only use code examples from the repositories listed above
-- Always specify the exact repository URL and file path when referencing code
-- Never use generic, third-party, or non-Dspread code examples
-- If no official Dspread code exists for a specific example, explicitly state this limitation
-
-**COVERAGE AREAS:**
-📱 **Android Terminals**: Smart POS and mPOS integration, SDK setup, payment processing, EMV workflows
-🐧 **Linux Terminals**: Development environment, project structure, transaction flows, compilation and deployment  
-💳 **Payment Processing**: EMV card reading, PIN entry, online authorization, reversal handling
-🖨️ **Hardware Features**: Receipt printing, QR/barcode scanning, device communication
-🔐 **Security**: P2PE encryption, AWS Payment Cryptography, DUKPT key management
-⚙️ **Integration**: Setup guides, demo applications, SDK configuration, terminal management
-
-**RESPONSE FORMAT - 80% DOCUMENTATION, 20% EXPLANATION:**
-- Begin with a brief introduction (5%)
-- Include extensive direct quotations from documentation (50%)
-- Include complete code examples from official Dspread repositories only (30%)
-- Add minimal clarification or connection between concepts (15%)
-- End with document reference links (5%)
-
-**CODE FORMATTING GUIDELINES:**
-- Always wrap code in proper markdown code blocks with language specification
-- Use \`\`\`java for Java code examples
-- Use \`\`\`shell for terminal commands
-- Use \`\`\`gradle for build configuration
-- Use \`\`\`c for C/C++ code examples
-- Use \`\`\`xml for XML configuration files
-- Use \`\`\`json for JSON configuration
-- Include proper indentation and formatting
-- Add comments to explain key parts of the code
-- Break long code examples into logical sections with explanations
-- Always specify the source file path when showing code examples
-- Use descriptive variable names and maintain consistent formatting
-- Ensure all code blocks are properly closed with \`\`\`
-- **Only use code blocks (\`\`\`) for complete code, configuration, or multi-line examples.**
-- **Do NOT use inline code formatting (\`...\`) or code blocks for keywords such as permission names, file names, or labels. Use plain text, bold, or italics instead.**
-- （仅对完整代码、配置或多行示例使用代码块，不要对权限名、文件名、标签等普通关键词使用行内代码格式或代码块。权限名、文件名、标签等请用普通文本或加粗/斜体，不要用 code 标签。）
-- If you need to highlight a file name, permission name, or label, use **bold** or *italic* text, never code formatting.
-
-**CODE PRESENTATION RULES:**
-- Start each code block with the appropriate language tag
-- Include the source repository and file path as a comment at the top
-- Use consistent indentation (4 spaces for Java, 2 spaces for XML/JSON)
-- Add inline comments for complex logic
-- Break long lines appropriately to maintain readability
-- Group related code sections together with explanatory text between them
-
-**STRICT CODE EXAMPLE POLICY:**
-- All code examples MUST be directly copied from the official Dspread documentation or the official GitHub repositories listed below.
-- DO NOT invent, guess, or generate code that is not present in the official documentation or repositories.
-- If there is no official code example, explicitly state: "No official code example is available for this case."
-- For every code block, indicate the source documentation page and the exact repository file path.
-- File names, permission names, and configuration keys should be presented as plain text, **bold**, or *italic* only, NEVER as code blocks or inline code.
-- If unsure, do NOT use code formatting for such keywords.
-
-**严格代码示例政策：**
-- 所有代码示例必须严格引用官方文档或下方列出的官方GitHub仓库，禁止AI自创、猜测或拼接代码。
-- 如无官方代码示例，必须明确说明：“本场景暂无官方代码示例”。
-- 每个代码块前必须注明来源（文档页面和repo文件路径）。
-- 文件名、权限名、配置项等仅用普通文本、加粗或斜体，绝不能用代码块或行内code。如无法判断，宁可不用代码格式。`}
+        instructions={SYSTEM_INSTRUCTIONS}
         labels={{
           title: "Dspread Assistant",
-          initial: "How can I help you with Dspread documentation today?",
+          initial: "How can I help you with Dspread documentation?",
         }}
-        defaultOpen={true}
-        clickOutsideToClose={false}
-        className="copilot-sidebar"
+        defaultOpen={false}
+        clickOutsideToClose={true}
       />
       {children}
     </>
   );
 }
 
-// Main CopilotKit wrapper component
+// Main wrapper - no CSS imports here to avoid build issues
 export default function CopilotKitWrapper({ children }) {
   return (
-    <CopilotKit 
+    <CopilotKit
       publicApiKey="ck_pub_79b8a4d1d6892f3997f82b857495ed8b"
       showDevConsole={false}
     >
-      <AppWithSuggestions>
-        {children}
-      </AppWithSuggestions>
+      <ChatSuggestions>{children}</ChatSuggestions>
     </CopilotKit>
   );
 }

components/CopilotKitWrapperClient.jsx

@@ -0,0 +1,11 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+// Dynamic import with SSR disabled to avoid hydration issues and CSS import errors
+const CopilotKitWrapper = dynamic(() => import("./CopilotKitWrapper"), {
+  ssr: false,
+  loading: () => null,
+});
+
+export default CopilotKitWrapper;

next.config.js

@@ -1,3 +1,4 @@
+const webpack = require('webpack')
 const withNextra = require('nextra')({
   theme: 'nextra-theme-docs',
   themeConfig: './theme.config.jsx'
@@ -8,13 +9,31 @@ const isDev = process.env.NODE_ENV !== 'production'
 const basePath = isDev ? '' : '/docs'
 
 module.exports = withNextra({
+  transpilePackages: [
+    '@copilotkit/react-core',
+    '@copilotkit/react-ui',
+  ],
   output: 'export',
   images: {
     unoptimized: true,
   },
   basePath,
   assetPrefix: basePath,
   trailingSlash: true,
+  webpack: (config) => {
+    // Ignore CSS imports from node_modules to avoid Next.js global CSS restriction
+    config.plugins.push(
+      new webpack.IgnorePlugin({
+        resourceRegExp: /katex\.min\.css$/,
+        contextRegExp: /node_modules/,
+      }),
+      new webpack.IgnorePlugin({
+        resourceRegExp: /styles\.css$/,
+        contextRegExp: /@copilotkit/,
+      })
+    )
+    return config
+  },
 })
 
 // If you have other Next.js configurations, you can pass them as the parameter above

package.json

@@ -9,8 +9,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@copilotkit/react-core": "^1.8.13",
-    "@copilotkit/react-ui": "^1.8.13",
+    "@copilotkit/react-core": "1.51.3",
+    "@copilotkit/react-ui": "1.51.3",
     "@vercel/analytics": "^1.1.1",
     "next": "^14.2.26",
     "nextra": "^2.13.2",

pages/_app.mdx

@@ -1,7 +1,27 @@
 import "../styles/custom.css";
+import CopilotKitWrapper from "../components/CopilotKitWrapperClient";
+import Head from "next/head";
 
 export default function MyApp({ Component, pageProps }) {
-  return <Component {...pageProps} />;
+  return (
+    <>
+      <Head>
+        <link
+          rel="stylesheet"
+          href="https://cdn.jsdelivr.net/npm/katex@0.16.28/dist/katex.min.css"
+          crossOrigin="anonymous"
+        />
+        <link
+          rel="stylesheet"
+          href="https://cdn.jsdelivr.net/npm/@copilotkit/react-ui@1.51.3/dist/styles.css"
+          crossOrigin="anonymous"
+        />
+      </Head>
+      <CopilotKitWrapper>
+        <Component {...pageProps} />
+      </CopilotKitWrapper>
+    </>
+  );
 }