castle-web-cli 0.1.0 → 0.3.0

package/AGENTS.md

@@ -2,10 +2,13 @@
 
 ## Commands
 
-- `castle-web init <dir>` — scaffold a new project (index.html, game.js, castle.js SDK)
-- `castle-web serve [dir] [--port PORT] [--open]` — local dev server with hot reload (default port 3737)
-- `castle-web push [dir]` — bundle with esbuild and publish to Castle. Creates a new deck if no castle.json exists.
-- `castle-web login` — authenticate with Castle (saves token to ~/.castle/config.json)
+- `npx castle-web-cli init <dir>` — scaffold a new project (index.html, game.js, package.json with castle-web-sdk)
+- `npx castle-web-cli serve [dir] [--port PORT] [--open]` — local dev server with Vite (default port 3737, WS on 3738). No auto-reload — use `restart` to reload.
+- `npx castle-web-cli restart [--port PORT]` — reload the game in the browser (default WS port 3738)
+- `npx castle-web-cli screenshot [--out FILE] [--port PORT]` — capture a screenshot from the running game (default: screenshot.png)
+- `npx castle-web-cli push [dir]` — bundle with Vite and publish to Castle. Creates a new deck if no castle.json exists. Automatically saves a preview image on first push if `serve` is running.
+- `npx castle-web-cli save-preview-image [dir] [--port PORT]` — restarts the deck, takes a screenshot, uploads it as the deck's preview image. Requires `serve` running and `castle.json` to exist (push first).
+- `npx castle-web-cli login` — authenticate with Castle (saves token to ~/.castle/config.json)
 
 ## Project Structure
 
@@ -13,10 +16,9 @@
 my-game/
   index.html      # entry point
   game.js         # game code
-  castle.js       # SDK (copied by init)
+  package.json    # dependencies (castle-web-sdk)
   castle.json     # deck/card IDs (created by first push)
+  .castle/        # runtime state (logs, screenshots)
+    logs.txt      # forwarded console.log/warn/error
+    screenshots/  # captured screenshots
 ```
-
-## Bundling
-
-`push` uses esbuild to inline all `<script src="...">` tags into a single self-contained HTML string stored in the deck's scene data as `experimentalWeb.bundle`.

package/dist/api.d.ts

@@ -18,3 +18,8 @@ export declare function uploadSceneData(cards: Array<{
     cardId: string;
     uploadId: string;
 }>): Promise<any[]>;
+export declare function uploadBase64(base64: string, filename: string): Promise<{
+    fileId: string;
+    url: string;
+}>;
+export declare function updateCardCustomBackgroundImage(cardId: string, backgroundImageFileId: string): Promise<void>;

package/dist/api.js

@@ -41,7 +41,7 @@ export async function pollForCLILogin(pollToken) {
 }
 export async function me() {
     try {
-        const data = await graphql(`query { me { userId username isAnonymous } }`);
+        const data = await graphql(`query { me { userId username isAnonymous photo { url } photoFrame { frameUrl } } }`);
         return data.data?.me ?? null;
     }
     catch {
@@ -103,3 +103,18 @@ export async function uploadSceneData(cards) {
     handleAPIError(data);
     return data.data.uploadSceneData;
 }
+export async function uploadBase64(base64, filename) {
+    const data = await graphql(`mutation($data: String!, $filename: String, $mimetype: String) {
+       uploadBase64(data: $data, filename: $filename, mimetype: $mimetype) {
+         fileId url
+       }
+     }`, { data: base64, filename, mimetype: 'image/png' });
+    handleAPIError(data);
+    return data.data.uploadBase64;
+}
+export async function updateCardCustomBackgroundImage(cardId, backgroundImageFileId) {
+    const data = await graphql(`mutation($cardId: ID!, $backgroundImageFileId: ID) {
+       updateCardCustomBackgroundImage(cardId: $cardId, backgroundImageFileId: $backgroundImageFileId)
+     }`, { cardId, backgroundImageFileId });
+    handleAPIError(data);
+}

package/dist/bundle.d.ts

@@ -1 +1 @@
-export declare function bundleProject(dir: string): string;
+export declare function bundleProject(dir: string): Promise<string>;

package/dist/bundle.js

@@ -1,27 +1,25 @@
-import * as fs from 'fs';
 import * as path from 'path';
-import * as esbuild from 'esbuild';
-export function bundleProject(dir) {
-    const indexPath = path.join(dir, 'index.html');
-    if (!fs.existsSync(indexPath)) {
-        throw new Error(`No index.html found in ${dir}`);
-    }
-    let html = fs.readFileSync(indexPath, 'utf-8');
-    // Find <script src="..."> tags, bundle each with esbuild, inline the result
-    html = html.replace(/<script\s+([^>]*?)src=["']([^"']+)["']([^>]*?)>\s*<\/script>/gi, (fullMatch, before, src, after) => {
-        const srcPath = path.resolve(dir, src);
-        if (!fs.existsSync(srcPath))
-            return fullMatch;
-        const result = esbuild.buildSync({
-            entryPoints: [srcPath],
-            bundle: true,
-            format: 'esm',
+import { build } from 'vite';
+import { viteSingleFile } from 'vite-plugin-singlefile';
+export async function bundleProject(dir) {
+    const result = await build({
+        root: dir,
+        plugins: [viteSingleFile()],
+        build: {
             write: false,
-            minify: false,
-        });
-        const code = result.outputFiles[0].text;
-        const attrs = `${before}${after}`.trim();
-        return `<script type="module"${attrs ? ' ' + attrs : ''}>\n${code}</script>`;
+            rollupOptions: {
+                input: path.join(dir, 'index.html'),
+            },
+        },
+        logLevel: 'silent',
     });
-    return html;
+    const output = Array.isArray(result) ? result[0] : result;
+    if (!('output' in output))
+        throw new Error('Unexpected build result');
+    for (const chunk of output.output) {
+        if (chunk.type === 'asset' && chunk.fileName.endsWith('.html')) {
+            return chunk.source;
+        }
+    }
+    throw new Error('No HTML output found from build');
 }

package/dist/index.js

@@ -1,18 +1,21 @@
 #!/usr/bin/env node
+import * as fs from 'fs';
 import { login } from './login.js';
 import { serve } from './serve.js';
 import { push } from './push.js';
 import { init } from './init.js';
+import { savePreviewImage, savePreviewIfNeeded } from './preview.js';
 const args = process.argv.slice(2);
 const command = args[0];
 function usage() {
     console.log(`Usage:
   castle-web init <dir>
   castle-web serve [dir] [--port PORT] [--open]
+  castle-web restart [--port PORT]
+  castle-web screenshot [--out FILE] [--port PORT]
+  castle-web save-preview-image [dir] [--port PORT]
   castle-web push [dir]
-  castle-web login
-
-Install: cd castle-experimental-web/cli && npm install && npm run build && npm link`);
+  castle-web login`);
     process.exit(1);
 }
 async function main() {
@@ -36,9 +39,63 @@ async function main() {
         }
         case 'push': {
             const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
+            const portIdx = args.indexOf('--port');
+            const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
             await push(dir);
+            await savePreviewIfNeeded(dir, wsPort);
+            break;
+        }
+        case 'restart': {
+            const portIdx = args.indexOf('--port');
+            const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+            const { default: WS } = await import('ws');
+            const ws = new WS(`ws://localhost:${wsPort}`);
+            ws.on('open', () => {
+                ws.send(JSON.stringify({ type: 'restart' }));
+                setTimeout(() => { ws.close(); process.exit(0); }, 100);
+            });
+            ws.on('error', () => { console.error('Could not connect. Is castle-web serve running?'); process.exit(1); });
             break;
         }
+        case 'screenshot': {
+            const outIdx = args.indexOf('--out');
+            const outFile = outIdx >= 0 ? args[outIdx + 1] : 'screenshot.png';
+            const portIdx = args.indexOf('--port');
+            const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+            const requestId = Math.random().toString(36).slice(2);
+            const { default: WS } = await import('ws');
+            const ws = new WS(`ws://localhost:${wsPort}`);
+            ws.on('open', () => {
+                ws.send(JSON.stringify({ type: 'screenshot_request', requestId }));
+            });
+            const timeout = setTimeout(() => {
+                console.error('Screenshot timed out. Is castle-web serve running?');
+                ws.close();
+                process.exit(1);
+            }, 3000);
+            ws.on('message', (raw) => {
+                try {
+                    const msg = JSON.parse(raw.toString());
+                    if (msg.type === 'screenshot_response' && msg.requestId === requestId) {
+                        clearTimeout(timeout);
+                        const base64 = msg.data.replace(/^data:image\/png;base64,/, '');
+                        fs.writeFileSync(outFile, Buffer.from(base64, 'base64'));
+                        console.log(`Saved ${outFile}`);
+                        ws.close();
+                        process.exit(0);
+                    }
+                }
+                catch { }
+            });
+            break;
+        }
+        case 'save-preview-image': {
+            const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
+            const portIdx = args.indexOf('--port');
+            const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+            await savePreviewImage(dir, wsPort);
+            process.exit(0);
+        }
         case 'login':
             await login();
             break;

package/dist/init.js

@@ -11,19 +11,22 @@ const INDEX_HTML = `<!DOCTYPE html>
 </body>
 </html>
 `;
-const GAME_JS = `import * as castle from 'castle-web-sdk';
+const GAME_JS = `import { setup, initCard } from 'castle-web-sdk';
 
-castle.enableHotReload();
-const card = castle.initCard();
+setup();
+const card = initCard();
 
-const div = document.createElement('div');
-div.style.cssText = \`
+const el = document.createElement('div');
+el.style.cssText = \`
   width: 100%; height: 100%;
   display: flex; align-items: center; justify-content: center;
   font-family: system-ui; color: #fff; font-size: 24px;
 \`;
-div.textContent = 'Hello Castle!';
-card.appendChild(div);
+el.textContent = 'Hello Castle!';
+card.appendChild(el);
+`;
+const CLAUDE_MD = `@node_modules/castle-web-cli/AGENTS.md
+@node_modules/castle-web-sdk/AGENTS.md
 `;
 export async function init(dir) {
     const projectDir = path.resolve(dir);
@@ -34,7 +37,7 @@ export async function init(dir) {
     fs.mkdirSync(projectDir, { recursive: true });
     fs.writeFileSync(path.join(projectDir, 'index.html'), INDEX_HTML);
     fs.writeFileSync(path.join(projectDir, 'game.js'), GAME_JS);
-    // Create package.json with SDK dependency
+    fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), CLAUDE_MD);
     const packageJson = {
         name: path.basename(projectDir),
         private: true,
@@ -42,16 +45,18 @@ export async function init(dir) {
         dependencies: {
             'castle-web-sdk': '*',
         },
+        devDependencies: {
+            'castle-web-cli': '*',
+        },
     };
     fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(packageJson, null, 2) + '\n');
-    // Install dependencies (picks up npm-linked SDK)
     const { execSync } = await import('child_process');
     execSync('npm install', { cwd: projectDir, stdio: 'inherit' });
     console.log(`Created project in ${projectDir}/`);
     console.log('');
     console.log('Next steps:');
     console.log(`  cd ${dir}`);
-    console.log('  castle-web serve --open');
-    console.log('  castle-web login');
-    console.log('  castle-web push');
+    console.log('  npx castle-web-cli serve --open');
+    console.log('  npx castle-web-cli login');
+    console.log('  npx castle-web-cli push');
 }

package/dist/preview.d.ts

@@ -0,0 +1,2 @@
+export declare function savePreviewImage(dir: string, wsPort: number): Promise<void>;
+export declare function savePreviewIfNeeded(dir: string, wsPort: number): Promise<void>;

package/dist/preview.js

@@ -0,0 +1,84 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as api from './api.js';
+import * as config from './config.js';
+function connectWS(wsPort) {
+    return new Promise(async (resolve, reject) => {
+        const { default: WS } = await import('ws');
+        const ws = new WS(`ws://localhost:${wsPort}`);
+        ws.on('error', () => reject(new Error('Could not connect. Is castle-web serve running?')));
+        ws.on('open', () => resolve(ws));
+    });
+}
+function takeScreenshot(ws) {
+    return new Promise((resolve, reject) => {
+        const requestId = Math.random().toString(36).slice(2);
+        const timeout = setTimeout(() => {
+            reject(new Error('Screenshot timed out.'));
+        }, 5000);
+        ws.on('message', (raw) => {
+            try {
+                const msg = JSON.parse(raw.toString());
+                if (msg.type === 'screenshot_response' && msg.requestId === requestId) {
+                    clearTimeout(timeout);
+                    resolve(msg.data.replace(/^data:image\/png;base64,/, ''));
+                }
+            }
+            catch { }
+        });
+        ws.send(JSON.stringify({ type: 'screenshot_request', requestId }));
+    });
+}
+function waitForRestart(ws) {
+    return new Promise((resolve) => {
+        // restart, wait a moment for the deck to render its first frame
+        ws.send(JSON.stringify({ type: 'restart' }));
+        setTimeout(resolve, 500);
+    });
+}
+export async function savePreviewImage(dir, wsPort) {
+    const projectDir = path.resolve(dir);
+    const castleJsonPath = path.join(projectDir, 'castle.json');
+    if (!fs.existsSync(castleJsonPath)) {
+        console.error('No castle.json found. Push the deck first.');
+        process.exit(1);
+    }
+    const castleJson = JSON.parse(fs.readFileSync(castleJsonPath, 'utf-8'));
+    if (!config.getToken()) {
+        console.error('Not logged in. Run `castle-web login` first.');
+        process.exit(1);
+    }
+    const ws = await connectWS(wsPort);
+    await waitForRestart(ws);
+    const base64 = await takeScreenshot(ws);
+    ws.close();
+    fs.writeFileSync(path.join(projectDir, 'preview.png'), Buffer.from(base64, 'base64'));
+    console.log('Saved preview.png');
+    const file = await api.uploadBase64(base64, 'preview.png');
+    await api.updateCardCustomBackgroundImage(castleJson.cardId, file.fileId);
+    console.log('Set deck preview image.');
+}
+export async function savePreviewIfNeeded(dir, wsPort) {
+    const projectDir = path.resolve(dir);
+    if (fs.existsSync(path.join(projectDir, 'preview.png'))) {
+        return;
+    }
+    try {
+        const ws = await connectWS(wsPort);
+        await waitForRestart(ws);
+        const base64 = await takeScreenshot(ws);
+        ws.close();
+        const castleJsonPath = path.join(projectDir, 'castle.json');
+        if (!fs.existsSync(castleJsonPath))
+            return;
+        const castleJson = JSON.parse(fs.readFileSync(castleJsonPath, 'utf-8'));
+        fs.writeFileSync(path.join(projectDir, 'preview.png'), Buffer.from(base64, 'base64'));
+        console.log('Saved preview.png');
+        const file = await api.uploadBase64(base64, 'preview.png');
+        await api.updateCardCustomBackgroundImage(castleJson.cardId, file.fileId);
+        console.log('Set deck preview image.');
+    }
+    catch {
+        // serve not running, skip preview
+    }
+}

package/dist/push.js

@@ -39,8 +39,12 @@ export async function push(dir) {
     }
     let castleJson = readCastleJson(projectDir);
     console.log('Bundling...');
-    const bundle = bundleProject(projectDir);
-    console.log(`Bundle size: ${(bundle.length / 1024).toFixed(1)}KB`);
+    const bundle = await bundleProject(projectDir);
+    const sizeKB = bundle.length / 1024;
+    console.log(`Bundle size: ${sizeKB.toFixed(1)}KB`);
+    if (sizeKB > 1024) {
+        console.warn(`Warning: Bundle is ${(sizeKB / 1024).toFixed(1)}MB. Large bundles may load slowly.`);
+    }
     const sceneData = buildSceneData(bundle);
     const isNew = !castleJson;
     const cardId = castleJson?.cardId ?? nanoid(12);
@@ -69,7 +73,7 @@ export async function push(dir) {
     // Create or update via updateCardAndDeckV2
     const title = path.basename(path.resolve(projectDir));
     try {
-        const result = await api.updateCardAndDeckV2({ deckId, title }, { cardId, blocks: [], uploadId: uploadConfig.uploadId, makeInitialCard: true });
+        const result = await api.updateCardAndDeckV2({ deckId, title, visibility: 'unlisted' }, { cardId, blocks: [], uploadId: uploadConfig.uploadId, makeInitialCard: true });
         if (isNew) {
             const newCastleJson = { deckId: result.deckId, cardId: result.cardId };
             fs.writeFileSync(path.join(projectDir, 'castle.json'), JSON.stringify(newCastleJson, null, 2) + '\n', 'utf-8');

package/dist/serve.js

@@ -1,120 +1,97 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import * as http from 'http';
-const MIME_TYPES = {
-    '.html': 'text/html',
-    '.js': 'application/javascript',
-    '.mjs': 'application/javascript',
-    '.css': 'text/css',
-    '.json': 'application/json',
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.gif': 'image/gif',
-    '.svg': 'image/svg+xml',
-    '.wasm': 'application/wasm',
-    '.ico': 'image/x-icon',
-    '.mp3': 'audio/mpeg',
-    '.ogg': 'audio/ogg',
-    '.wav': 'audio/wav',
-    '.mp4': 'video/mp4',
-    '.webm': 'video/webm',
-    '.ttf': 'font/ttf',
-    '.woff': 'font/woff',
-    '.woff2': 'font/woff2',
-};
+import { createServer } from 'vite';
+import { WebSocketServer, WebSocket } from 'ws';
+function castlePlugin(wsPort) {
+    return {
+        name: 'castle-dev',
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                if (req.url === '/__castle/ws-port') {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ port: wsPort }));
+                    return;
+                }
+                next();
+            });
+        },
+    };
+}
 export async function serve(dir, options = {}) {
     const projectDir = path.resolve(dir);
     if (!fs.existsSync(projectDir)) {
         console.error(`Directory not found: ${projectDir}`);
         process.exit(1);
     }
-    const indexPath = path.join(projectDir, 'index.html');
-    if (!fs.existsSync(indexPath)) {
+    if (!fs.existsSync(path.join(projectDir, 'index.html'))) {
         console.error(`No index.html found in ${projectDir}`);
         process.exit(1);
     }
     const port = parseInt(options.port ?? '3737', 10);
-    let version = 0;
-    const pendingVersionPolls = [];
-    function flushVersionPolls() {
-        while (pendingVersionPolls.length > 0) {
-            const poll = pendingVersionPolls.shift();
-            poll.res.writeHead(200, { 'Content-Type': 'application/json' });
-            poll.res.end(JSON.stringify({ version }));
-        }
-    }
-    // Watch project dir for changes
-    fs.watch(projectDir, { recursive: true }, (event, filename) => {
-        if (filename && !filename.startsWith('.')) {
-            version++;
-            flushVersionPolls();
-        }
+    const wsPort = port + 1;
+    // Local WebSocket server for SDK communication
+    const castleDir = path.join(projectDir, '.castle');
+    if (!fs.existsSync(castleDir))
+        fs.mkdirSync(castleDir, { recursive: true });
+    const logFile = path.join(castleDir, 'logs.txt');
+    const screenshotsDir = path.join(castleDir, 'screenshots');
+    startWSServer(wsPort, logFile, screenshotsDir);
+    const vite = await createServer({
+        root: projectDir,
+        plugins: [castlePlugin(wsPort)],
+        server: {
+            port,
+            strictPort: true,
+            open: options.open ? true : undefined,
+            hmr: false,
+            fs: { strict: false },
+        },
+        logLevel: 'info',
     });
-    const server = http.createServer((req, res) => {
-        const url = new URL(req.url ?? '/', `http://localhost:${port}`);
-        const pathname = url.pathname;
-        // Version polling for hot reload
-        if (pathname === '/__version') {
-            const clientVersion = parseInt(url.searchParams.get('v') ?? '0', 10);
-            if (clientVersion < version) {
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ version }));
-            }
-            else {
-                // Long poll — wait for next change
-                pendingVersionPolls.push({ clientVersion, res });
-                const timeout = setTimeout(() => {
-                    const idx = pendingVersionPolls.findIndex((p) => p.res === res);
-                    if (idx >= 0)
-                        pendingVersionPolls.splice(idx, 1);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ version }));
-                }, 30000);
-                res.on('close', () => {
-                    clearTimeout(timeout);
-                    const idx = pendingVersionPolls.findIndex((p) => p.res === res);
-                    if (idx >= 0)
-                        pendingVersionPolls.splice(idx, 1);
-                });
-            }
-            return;
-        }
-        // Serve static files
-        let filePath = path.join(projectDir, pathname === '/' ? 'index.html' : pathname);
-        filePath = path.normalize(filePath);
-        // Security: don't serve files outside project dir
-        if (!filePath.startsWith(projectDir)) {
-            res.writeHead(403);
-            res.end('Forbidden');
-            return;
-        }
-        if (!fs.existsSync(filePath)) {
-            res.writeHead(404);
-            res.end('Not found');
-            return;
-        }
-        const stat = fs.statSync(filePath);
-        if (stat.isDirectory()) {
-            filePath = path.join(filePath, 'index.html');
-            if (!fs.existsSync(filePath)) {
-                res.writeHead(404);
-                res.end('Not found');
-                return;
+    await vite.listen();
+    vite.printUrls();
+}
+function startWSServer(port, logFile, screenshotsDir) {
+    const wss = new WebSocketServer({ port });
+    const clients = new Set();
+    wss.on('connection', (ws) => {
+        clients.add(ws);
+        ws.on('message', (raw) => {
+            try {
+                const msg = JSON.parse(raw.toString());
+                if (msg.type === 'restart' || msg.type === 'screenshot_request') {
+                    const fwd = JSON.stringify(msg);
+                    for (const c of clients) {
+                        if (c !== ws && c.readyState === WebSocket.OPEN)
+                            c.send(fwd);
+                    }
+                }
+                if (msg.type === 'log') {
+                    const line = `[${msg.level}] ${msg.msg}\n`;
+                    fs.appendFileSync(logFile, line);
+                    if (msg.level === 'error')
+                        process.stderr.write(line);
+                    else
+                        process.stdout.write(line);
+                }
+                if (msg.type === 'screenshot_response') {
+                    if (!fs.existsSync(screenshotsDir))
+                        fs.mkdirSync(screenshotsDir, { recursive: true });
+                    const filename = `screenshot-${Date.now()}.png`;
+                    const filepath = path.join(screenshotsDir, filename);
+                    const base64 = msg.data.replace(/^data:image\/png;base64,/, '');
+                    fs.writeFileSync(filepath, Buffer.from(base64, 'base64'));
+                    console.log(`Screenshot saved: ${filepath}`);
+                    const fwd = JSON.stringify(msg);
+                    for (const c of clients) {
+                        if (c !== ws && c.readyState === WebSocket.OPEN)
+                            c.send(fwd);
+                    }
+                }
             }
-        }
-        const ext = path.extname(filePath).toLowerCase();
-        const contentType = MIME_TYPES[ext] ?? 'application/octet-stream';
-        const data = fs.readFileSync(filePath);
-        res.writeHead(200, { 'Content-Type': contentType });
-        res.end(data);
-    });
-    server.listen(port, () => {
-        const url = `http://localhost:${port}`;
-        console.log(`Serving ${projectDir}`);
-        console.log(`  ${url}`);
-        console.log('Press Ctrl+C to stop.');
-        if (options.open) {
-            import('open').then(({ default: open }) => open(url));
-        }
+            catch { }
+        });
+        ws.on('close', () => { clients.delete(ws); });
     });
+    return wss;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"
@@ -10,12 +10,15 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "esbuild": "^0.28.0",
     "nanoid": "^5.1.7",
-    "open": "^10.0.0"
+    "open": "^10.0.0",
+    "vite": "^8.0.3",
+    "vite-plugin-singlefile": "^2.3.2",
+    "ws": "^8.20.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/ws": "^8.18.1",
     "typescript": "^5.0.0"
   }
 }

package/src/api.ts

@@ -49,7 +49,7 @@ export async function pollForCLILogin(pollToken: string): Promise<any> {
 
 export async function me(): Promise<any> {
   try {
-    const data = await graphql(`query { me { userId username isAnonymous } }`);
+    const data = await graphql(`query { me { userId username isAnonymous photo { url } photoFrame { frameUrl } } }`);
     return data.data?.me ?? null;
   } catch {
     return null;
@@ -135,3 +135,26 @@ export async function uploadSceneData(
   handleAPIError(data);
   return data.data.uploadSceneData;
 }
+
+export async function uploadBase64(base64: string, filename: string): Promise<{ fileId: string; url: string }> {
+  const data = await graphql(
+    `mutation($data: String!, $filename: String, $mimetype: String) {
+       uploadBase64(data: $data, filename: $filename, mimetype: $mimetype) {
+         fileId url
+       }
+     }`,
+    { data: base64, filename, mimetype: 'image/png' }
+  );
+  handleAPIError(data);
+  return data.data.uploadBase64;
+}
+
+export async function updateCardCustomBackgroundImage(cardId: string, backgroundImageFileId: string): Promise<void> {
+  const data = await graphql(
+    `mutation($cardId: ID!, $backgroundImageFileId: ID) {
+       updateCardCustomBackgroundImage(cardId: $cardId, backgroundImageFileId: $backgroundImageFileId)
+     }`,
+    { cardId, backgroundImageFileId }
+  );
+  handleAPIError(data);
+}

package/src/bundle.ts

@@ -1,35 +1,28 @@
-import * as fs from 'fs';
 import * as path from 'path';
-import * as esbuild from 'esbuild';
+import { build } from 'vite';
+import { viteSingleFile } from 'vite-plugin-singlefile';
 
-export function bundleProject(dir: string): string {
-  const indexPath = path.join(dir, 'index.html');
-  if (!fs.existsSync(indexPath)) {
-    throw new Error(`No index.html found in ${dir}`);
-  }
-
-  let html = fs.readFileSync(indexPath, 'utf-8');
+export async function bundleProject(dir: string): Promise<string> {
+  const result = await build({
+    root: dir,
+    plugins: [viteSingleFile()],
+    build: {
+      write: false,
+      rollupOptions: {
+        input: path.join(dir, 'index.html'),
+      },
+    },
+    logLevel: 'silent',
+  });
 
-  // Find <script src="..."> tags, bundle each with esbuild, inline the result
-  html = html.replace(
-    /<script\s+([^>]*?)src=["']([^"']+)["']([^>]*?)>\s*<\/script>/gi,
-    (fullMatch, before, src, after) => {
-      const srcPath = path.resolve(dir, src);
-      if (!fs.existsSync(srcPath)) return fullMatch;
+  const output = Array.isArray(result) ? result[0] : result;
+  if (!('output' in output)) throw new Error('Unexpected build result');
 
-      const result = esbuild.buildSync({
-        entryPoints: [srcPath],
-        bundle: true,
-        format: 'esm',
-        write: false,
-        minify: false,
-      });
-
-      const code = result.outputFiles[0].text;
-      const attrs = `${before}${after}`.trim();
-      return `<script type="module"${attrs ? ' ' + attrs : ''}>\n${code}</script>`;
+  for (const chunk of output.output) {
+    if (chunk.type === 'asset' && chunk.fileName.endsWith('.html')) {
+      return chunk.source as string;
     }
-  );
+  }
 
-  return html;
+  throw new Error('No HTML output found from build');
 }

package/src/index.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 
+import * as fs from 'fs';
 import { login } from './login.js';
 import { serve } from './serve.js';
 import { push } from './push.js';
 import { init } from './init.js';
+import { savePreviewImage, savePreviewIfNeeded } from './preview.js';
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -12,10 +14,11 @@ function usage() {
   console.log(`Usage:
   castle-web init <dir>
   castle-web serve [dir] [--port PORT] [--open]
+  castle-web restart [--port PORT]
+  castle-web screenshot [--out FILE] [--port PORT]
+  castle-web save-preview-image [dir] [--port PORT]
   castle-web push [dir]
-  castle-web login
-
-Install: cd castle-experimental-web/cli && npm install && npm run build && npm link`);
+  castle-web login`);
   process.exit(1);
 }
 
@@ -37,9 +40,62 @@ async function main() {
     }
     case 'push': {
       const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
+      const portIdx = args.indexOf('--port');
+      const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
       await push(dir);
+      await savePreviewIfNeeded(dir, wsPort);
+      break;
+    }
+    case 'restart': {
+      const portIdx = args.indexOf('--port');
+      const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+      const { default: WS } = await import('ws');
+      const ws = new WS(`ws://localhost:${wsPort}`);
+      ws.on('open', () => {
+        ws.send(JSON.stringify({ type: 'restart' }));
+        setTimeout(() => { ws.close(); process.exit(0); }, 100);
+      });
+      ws.on('error', () => { console.error('Could not connect. Is castle-web serve running?'); process.exit(1); });
       break;
     }
+    case 'screenshot': {
+      const outIdx = args.indexOf('--out');
+      const outFile = outIdx >= 0 ? args[outIdx + 1] : 'screenshot.png';
+      const portIdx = args.indexOf('--port');
+      const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+      const requestId = Math.random().toString(36).slice(2);
+      const { default: WS } = await import('ws');
+      const ws = new WS(`ws://localhost:${wsPort}`);
+      ws.on('open', () => {
+        ws.send(JSON.stringify({ type: 'screenshot_request', requestId }));
+      });
+      const timeout = setTimeout(() => {
+        console.error('Screenshot timed out. Is castle-web serve running?');
+        ws.close();
+        process.exit(1);
+      }, 3000);
+      ws.on('message', (raw: Buffer) => {
+        try {
+          const msg = JSON.parse(raw.toString());
+          if (msg.type === 'screenshot_response' && msg.requestId === requestId) {
+            clearTimeout(timeout);
+            const base64 = msg.data.replace(/^data:image\/png;base64,/, '');
+            fs.writeFileSync(outFile, Buffer.from(base64, 'base64'));
+            console.log(`Saved ${outFile}`);
+            ws.close();
+            process.exit(0);
+          }
+        } catch {}
+      });
+      break;
+    }
+    case 'save-preview-image': {
+      const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
+      const portIdx = args.indexOf('--port');
+      const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+      await savePreviewImage(dir, wsPort);
+      process.exit(0);
+    }
     case 'login':
       await login();
       break;

package/src/init.ts

@@ -13,19 +13,23 @@ const INDEX_HTML = `<!DOCTYPE html>
 </html>
 `;
 
-const GAME_JS = `import * as castle from 'castle-web-sdk';
+const GAME_JS = `import { setup, initCard } from 'castle-web-sdk';
 
-castle.enableHotReload();
-const card = castle.initCard();
+setup();
+const card = initCard();
 
-const div = document.createElement('div');
-div.style.cssText = \`
+const el = document.createElement('div');
+el.style.cssText = \`
   width: 100%; height: 100%;
   display: flex; align-items: center; justify-content: center;
   font-family: system-ui; color: #fff; font-size: 24px;
 \`;
-div.textContent = 'Hello Castle!';
-card.appendChild(div);
+el.textContent = 'Hello Castle!';
+card.appendChild(el);
+`;
+
+const CLAUDE_MD = `@node_modules/castle-web-cli/AGENTS.md
+@node_modules/castle-web-sdk/AGENTS.md
 `;
 
 export async function init(dir: string) {
@@ -39,8 +43,8 @@ export async function init(dir: string) {
   fs.mkdirSync(projectDir, { recursive: true });
   fs.writeFileSync(path.join(projectDir, 'index.html'), INDEX_HTML);
   fs.writeFileSync(path.join(projectDir, 'game.js'), GAME_JS);
+  fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), CLAUDE_MD);
 
-  // Create package.json with SDK dependency
   const packageJson = {
     name: path.basename(projectDir),
     private: true,
@@ -48,10 +52,12 @@ export async function init(dir: string) {
     dependencies: {
       'castle-web-sdk': '*',
     },
+    devDependencies: {
+      'castle-web-cli': '*',
+    },
   };
   fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(packageJson, null, 2) + '\n');
 
-  // Install dependencies (picks up npm-linked SDK)
   const { execSync } = await import('child_process');
   execSync('npm install', { cwd: projectDir, stdio: 'inherit' });
 
@@ -59,7 +65,7 @@ export async function init(dir: string) {
   console.log('');
   console.log('Next steps:');
   console.log(`  cd ${dir}`);
-  console.log('  castle-web serve --open');
-  console.log('  castle-web login');
-  console.log('  castle-web push');
+  console.log('  npx castle-web-cli serve --open');
+  console.log('  npx castle-web-cli login');
+  console.log('  npx castle-web-cli push');
 }

package/src/preview.ts

@@ -0,0 +1,93 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as api from './api.js';
+import * as config from './config.js';
+
+function connectWS(wsPort: number): Promise<any> {
+  return new Promise(async (resolve, reject) => {
+    const { default: WS } = await import('ws');
+    const ws = new WS(`ws://localhost:${wsPort}`);
+    ws.on('error', () => reject(new Error('Could not connect. Is castle-web serve running?')));
+    ws.on('open', () => resolve(ws));
+  });
+}
+
+function takeScreenshot(ws: any): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const requestId = Math.random().toString(36).slice(2);
+    const timeout = setTimeout(() => {
+      reject(new Error('Screenshot timed out.'));
+    }, 5000);
+    ws.on('message', (raw: Buffer) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === 'screenshot_response' && msg.requestId === requestId) {
+          clearTimeout(timeout);
+          resolve(msg.data.replace(/^data:image\/png;base64,/, ''));
+        }
+      } catch {}
+    });
+    ws.send(JSON.stringify({ type: 'screenshot_request', requestId }));
+  });
+}
+
+function waitForRestart(ws: any): Promise<void> {
+  return new Promise((resolve) => {
+    // restart, wait a moment for the deck to render its first frame
+    ws.send(JSON.stringify({ type: 'restart' }));
+    setTimeout(resolve, 500);
+  });
+}
+
+export async function savePreviewImage(dir: string, wsPort: number): Promise<void> {
+  const projectDir = path.resolve(dir);
+  const castleJsonPath = path.join(projectDir, 'castle.json');
+  if (!fs.existsSync(castleJsonPath)) {
+    console.error('No castle.json found. Push the deck first.');
+    process.exit(1);
+  }
+  const castleJson = JSON.parse(fs.readFileSync(castleJsonPath, 'utf-8'));
+
+  if (!config.getToken()) {
+    console.error('Not logged in. Run `castle-web login` first.');
+    process.exit(1);
+  }
+
+  const ws = await connectWS(wsPort);
+  await waitForRestart(ws);
+  const base64 = await takeScreenshot(ws);
+  ws.close();
+
+  fs.writeFileSync(path.join(projectDir, 'preview.png'), Buffer.from(base64, 'base64'));
+  console.log('Saved preview.png');
+
+  const file = await api.uploadBase64(base64, 'preview.png');
+  await api.updateCardCustomBackgroundImage(castleJson.cardId, file.fileId);
+  console.log('Set deck preview image.');
+}
+
+export async function savePreviewIfNeeded(dir: string, wsPort: number): Promise<void> {
+  const projectDir = path.resolve(dir);
+  if (fs.existsSync(path.join(projectDir, 'preview.png'))) {
+    return;
+  }
+  try {
+    const ws = await connectWS(wsPort);
+    await waitForRestart(ws);
+    const base64 = await takeScreenshot(ws);
+    ws.close();
+
+    const castleJsonPath = path.join(projectDir, 'castle.json');
+    if (!fs.existsSync(castleJsonPath)) return;
+    const castleJson = JSON.parse(fs.readFileSync(castleJsonPath, 'utf-8'));
+
+    fs.writeFileSync(path.join(projectDir, 'preview.png'), Buffer.from(base64, 'base64'));
+    console.log('Saved preview.png');
+
+    const file = await api.uploadBase64(base64, 'preview.png');
+    await api.updateCardCustomBackgroundImage(castleJson.cardId, file.fileId);
+    console.log('Set deck preview image.');
+  } catch {
+    // serve not running, skip preview
+  }
+}

package/src/push.ts

@@ -49,8 +49,12 @@ export async function push(dir: string) {
   let castleJson = readCastleJson(projectDir);
 
   console.log('Bundling...');
-  const bundle = bundleProject(projectDir);
-  console.log(`Bundle size: ${(bundle.length / 1024).toFixed(1)}KB`);
+  const bundle = await bundleProject(projectDir);
+  const sizeKB = bundle.length / 1024;
+  console.log(`Bundle size: ${sizeKB.toFixed(1)}KB`);
+  if (sizeKB > 1024) {
+    console.warn(`Warning: Bundle is ${(sizeKB / 1024).toFixed(1)}MB. Large bundles may load slowly.`);
+  }
 
   const sceneData = buildSceneData(bundle);
   const isNew = !castleJson;
@@ -85,7 +89,7 @@ export async function push(dir: string) {
   const title = path.basename(path.resolve(projectDir));
   try {
     const result = await api.updateCardAndDeckV2(
-      { deckId, title },
+      { deckId, title, visibility: 'unlisted' },
       { cardId, blocks: [], uploadId: uploadConfig.uploadId, makeInitialCard: true }
     );
 

package/src/serve.ts

@@ -1,28 +1,23 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import * as http from 'http';
+import { createServer, type Plugin } from 'vite';
+import { WebSocketServer, WebSocket } from 'ws';
 
-const MIME_TYPES: Record<string, string> = {
-  '.html': 'text/html',
-  '.js': 'application/javascript',
-  '.mjs': 'application/javascript',
-  '.css': 'text/css',
-  '.json': 'application/json',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.wasm': 'application/wasm',
-  '.ico': 'image/x-icon',
-  '.mp3': 'audio/mpeg',
-  '.ogg': 'audio/ogg',
-  '.wav': 'audio/wav',
-  '.mp4': 'video/mp4',
-  '.webm': 'video/webm',
-  '.ttf': 'font/ttf',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-};
+function castlePlugin(wsPort: number): Plugin {
+  return {
+    name: 'castle-dev',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        if (req.url === '/__castle/ws-port') {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ port: wsPort }));
+          return;
+        }
+        next();
+      });
+    },
+  };
+}
 
 export async function serve(
   dir: string,
@@ -33,103 +28,81 @@ export async function serve(
     console.error(`Directory not found: ${projectDir}`);
     process.exit(1);
   }
-
-  const indexPath = path.join(projectDir, 'index.html');
-  if (!fs.existsSync(indexPath)) {
+  if (!fs.existsSync(path.join(projectDir, 'index.html'))) {
     console.error(`No index.html found in ${projectDir}`);
     process.exit(1);
   }
 
   const port = parseInt(options.port ?? '3737', 10);
-  let version = 0;
-  const pendingVersionPolls: Array<{ clientVersion: number; res: http.ServerResponse }> = [];
+  const wsPort = port + 1;
 
-  function flushVersionPolls() {
-    while (pendingVersionPolls.length > 0) {
-      const poll = pendingVersionPolls.shift()!;
-      poll.res.writeHead(200, { 'Content-Type': 'application/json' });
-      poll.res.end(JSON.stringify({ version }));
-    }
-  }
+  // Local WebSocket server for SDK communication
+  const castleDir = path.join(projectDir, '.castle');
+  if (!fs.existsSync(castleDir)) fs.mkdirSync(castleDir, { recursive: true });
+  const logFile = path.join(castleDir, 'logs.txt');
+  const screenshotsDir = path.join(castleDir, 'screenshots');
 
-  // Watch project dir for changes
-  fs.watch(projectDir, { recursive: true }, (event, filename) => {
-    if (filename && !filename.startsWith('.')) {
-      version++;
-      flushVersionPolls();
-    }
-  });
+  startWSServer(wsPort, logFile, screenshotsDir);
 
-  const server = http.createServer((req, res) => {
-    const url = new URL(req.url ?? '/', `http://localhost:${port}`);
-    const pathname = url.pathname;
+  const vite = await createServer({
+    root: projectDir,
+    plugins: [castlePlugin(wsPort)],
+    server: {
+      port,
+      strictPort: true,
+      open: options.open ? true : undefined,
+      hmr: false,
+      fs: { strict: false },
+    },
+    logLevel: 'info',
+  });
 
-    // Version polling for hot reload
-    if (pathname === '/__version') {
-      const clientVersion = parseInt(url.searchParams.get('v') ?? '0', 10);
-      if (clientVersion < version) {
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ version }));
-      } else {
-        // Long poll — wait for next change
-        pendingVersionPolls.push({ clientVersion, res });
-        const timeout = setTimeout(() => {
-          const idx = pendingVersionPolls.findIndex((p) => p.res === res);
-          if (idx >= 0) pendingVersionPolls.splice(idx, 1);
-          res.writeHead(200, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({ version }));
-        }, 30000);
-        res.on('close', () => {
-          clearTimeout(timeout);
-          const idx = pendingVersionPolls.findIndex((p) => p.res === res);
-          if (idx >= 0) pendingVersionPolls.splice(idx, 1);
-        });
-      }
-      return;
-    }
+  await vite.listen();
+  vite.printUrls();
+}
 
-    // Serve static files
-    let filePath = path.join(projectDir, pathname === '/' ? 'index.html' : pathname);
-    filePath = path.normalize(filePath);
+function startWSServer(port: number, logFile: string, screenshotsDir: string): WebSocketServer {
+  const wss = new WebSocketServer({ port });
+  const clients = new Set<WebSocket>();
 
-    // Security: don't serve files outside project dir
-    if (!filePath.startsWith(projectDir)) {
-      res.writeHead(403);
-      res.end('Forbidden');
-      return;
-    }
+  wss.on('connection', (ws) => {
+    clients.add(ws);
 
-    if (!fs.existsSync(filePath)) {
-      res.writeHead(404);
-      res.end('Not found');
-      return;
-    }
+    ws.on('message', (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
 
-    const stat = fs.statSync(filePath);
-    if (stat.isDirectory()) {
-      filePath = path.join(filePath, 'index.html');
-      if (!fs.existsSync(filePath)) {
-        res.writeHead(404);
-        res.end('Not found');
-        return;
-      }
-    }
+        if (msg.type === 'restart' || msg.type === 'screenshot_request') {
+          const fwd = JSON.stringify(msg);
+          for (const c of clients) {
+            if (c !== ws && c.readyState === WebSocket.OPEN) c.send(fwd);
+          }
+        }
 
-    const ext = path.extname(filePath).toLowerCase();
-    const contentType = MIME_TYPES[ext] ?? 'application/octet-stream';
-    const data = fs.readFileSync(filePath);
-    res.writeHead(200, { 'Content-Type': contentType });
-    res.end(data);
-  });
+        if (msg.type === 'log') {
+          const line = `[${msg.level}] ${msg.msg}\n`;
+          fs.appendFileSync(logFile, line);
+          if (msg.level === 'error') process.stderr.write(line);
+          else process.stdout.write(line);
+        }
 
-  server.listen(port, () => {
-    const url = `http://localhost:${port}`;
-    console.log(`Serving ${projectDir}`);
-    console.log(`  ${url}`);
-    console.log('Press Ctrl+C to stop.');
+        if (msg.type === 'screenshot_response') {
+          if (!fs.existsSync(screenshotsDir)) fs.mkdirSync(screenshotsDir, { recursive: true });
+          const filename = `screenshot-${Date.now()}.png`;
+          const filepath = path.join(screenshotsDir, filename);
+          const base64 = msg.data.replace(/^data:image\/png;base64,/, '');
+          fs.writeFileSync(filepath, Buffer.from(base64, 'base64'));
+          console.log(`Screenshot saved: ${filepath}`);
+          const fwd = JSON.stringify(msg);
+          for (const c of clients) {
+            if (c !== ws && c.readyState === WebSocket.OPEN) c.send(fwd);
+          }
+        }
+      } catch {}
+    });
 
-    if (options.open) {
-      import('open').then(({ default: open }) => open(url));
-    }
+    ws.on('close', () => { clients.delete(ws); });
   });
+
+  return wss;
 }