Enable twoslash

Author: tarrencev

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Validate Twoslash code blocks
+        run: pnpm validate-twoslash

CLAUDE.md

@@ -47,4 +47,15 @@ The documentation covers three main products:
 - Key dependencies: React 18, Starknet libraries, Cartridge connector
 - Vocs alpha version (1.0.0-alpha.55)
 
+### TypeScript Twoslash Integration
+The documentation site supports TypeScript Twoslash for enhanced code blocks that provide:
+- Type information on hover
+- IntelliSense-like features
+- Compile-time error checking in documentation
+
+To use Twoslash in code blocks, add `twoslash` to the language identifier:
+```typescript twoslash
+// Your TypeScript code here with full type checking
+```
+
 When editing content, maintain the existing markdown structure and follow the established sidebar navigation patterns in `vocs.config.ts`.

package.json

@@ -5,10 +5,12 @@
   "scripts": {
     "dev": "vocs dev",
     "build": "vocs build",
-    "preview": "vocs preview"
+    "preview": "vocs preview",
+    "validate-twoslash": "node scripts/validate-twoslash.js"
   },
   "dependencies": {
-    "@cartridge/connector": "^0.3.46",
+    "@cartridge/controller": "^0.8.0",
+    "@cartridge/connector": "^0.8.0",
     "@starknet-react/chains": "^0.1.7",
     "@starknet-react/core": "^3.5.0",
     "@types/react": "^18.3.12",

pnpm-lock.yaml

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { glob } from 'glob';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, '..');
+const tempDir = join(rootDir, 'temp-validation');
+
+// Find all markdown and mdx files
+const files = await glob('src/pages/**/*.{md,mdx}', { cwd: rootDir });
+
+let hasErrors = false;
+let totalBlocks = 0;
+let validatedBlocks = 0;
+
+console.log('🔍 Validating Twoslash code blocks...\n');
+
+// Create temp directory
+await mkdir(tempDir, { recursive: true });
+
+for (const file of files) {
+  const filePath = join(rootDir, file);
+  const content = await readFile(filePath, 'utf-8');
+  
+  // Match code blocks with twoslash
+  const twoslashBlocks = content.match(/```(?:typescript|ts|javascript|js)\s+twoslash\n([\s\S]*?)\n```/g);
+  
+  if (!twoslashBlocks) continue;
+  
+  console.log(`📄 Checking ${file}...`);
+  
+  for (let i = 0; i < twoslashBlocks.length; i++) {
+    totalBlocks++;
+    const block = twoslashBlocks[i];
+    
+    // Extract the code content
+    const codeMatch = block.match(/```(?:typescript|ts|javascript|js)\s+twoslash\n([\s\S]*?)\n```/);
+    if (!codeMatch) continue;
+    
+    const code = codeMatch[1];
+    const blockNumber = i + 1;
+    const tempFileName = `${file.replace(/[/\\]/g, '_')}_block_${blockNumber}.ts`;
+    const tempFilePath = join(tempDir, tempFileName);
+    
+    try {
+      // Write code to temp file
+      await writeFile(tempFilePath, code);
+      
+      // Run TypeScript compiler
+      try {
+        await execAsync(`npx tsc --project tsconfig.validation.json --noEmit "${tempFilePath}"`, {
+          cwd: rootDir,
+          env: { ...process.env, NODE_PATH: join(rootDir, 'node_modules') }
+        });
+        
+        console.log(`✅ ${file} (block ${blockNumber}): Valid`);
+        validatedBlocks++;
+      } catch (error) {
+        console.error(`❌ ${file} (block ${blockNumber}): TypeScript compilation failed`);
+        console.error(`   ${error.stdout || error.stderr || error.message}`);
+        hasErrors = true;
+      }
+    } catch (error) {
+      console.error(`❌ ${file} (block ${blockNumber}): Validation error`);
+      console.error(`   ${error.message}`);
+      hasErrors = true;
+    }
+  }
+}
+
+// Cleanup temp directory
+try {
+  await execAsync(`rm -rf "${tempDir}"`);
+} catch (error) {
+  console.warn(`Warning: Could not clean up temp directory: ${error.message}`);
+}
+
+console.log(`\n📊 Validation Summary:`);
+console.log(`   Total blocks: ${totalBlocks}`);
+console.log(`   Valid blocks: ${validatedBlocks}`);
+console.log(`   Failed blocks: ${totalBlocks - validatedBlocks}`);
+
+if (hasErrors) {
+  console.error('\n❌ Twoslash validation failed. Please fix the errors above.');
+  process.exit(1);
+} else {
+  console.log('\n✅ All Twoslash code blocks are valid!');
+  process.exit(0);
+}

scripts/validate-twoslash.js

@@ -12,10 +12,10 @@ seamlessly integrated into your application like any other wallet.
 
 The fastest way to get started is to install the controller package and connect to Cartridge:
 
-```ts
+```ts twoslash
 import Controller from "@cartridge/controller";
 
-const controller = new Controller();
+const controller = new Controller({});
 const account = await controller.connect();
 
 // You're ready to execute transactions!

src/pages/controller/getting-started.mdx

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"],
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["temp-validation/**/*"]
+}

tsconfig.validation.json

@@ -190,6 +190,9 @@ export default defineConfig({
     ],
   },
 
+  // Twoslash configuration
+  twoslash: {},
+
   // Vite configuration
   vite: {
     plugins: [svgr()],