From bed92c28e73898356e4bedbb7aa2ca1945cb3a7a Mon Sep 17 00:00:00 2001 From: Luke The Dev <252071647+iamlukethedev@users.noreply.github.com> Date: Sat, 4 Apr 2026 22:24:29 -0500 Subject: [PATCH 1/3] fix(docker): omit dev dependencies from runtime image (#84) Co-authored-by: Cursor Agent Co-authored-by: Luke The Dev --- Dockerfile | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 Dockerfile diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..41f2df8 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,34 @@ +# Claw3D - 3D agent visualization for OpenClaw. +# Multi-stage build: install prod deps -> build Next.js -> run with custom server. + +FROM node:20-slim AS deps +WORKDIR /app +COPY package.json package-lock.json ./ +RUN npm ci --ignore-scripts --omit=dev + +FROM node:20-slim AS builder +WORKDIR /app +COPY package.json package-lock.json ./ +RUN npm ci --ignore-scripts +COPY . . +ENV NEXT_TELEMETRY_DISABLED=1 +# Build-time gateway URL (overridden at runtime by CLAW3D_GATEWAY_URL). +ENV NEXT_PUBLIC_GATEWAY_URL=ws://127.0.0.1:18789 +RUN npm run build + +FROM node:20-slim AS runner +WORKDIR /app +ENV NODE_ENV=production +ENV NEXT_TELEMETRY_DISABLED=1 + +# Copy built app + custom server + production node_modules only. +COPY --from=builder /app/.next ./.next +COPY --from=builder /app/public ./public +COPY --from=builder /app/server ./server +COPY --from=deps /app/node_modules ./node_modules +COPY --from=builder /app/package.json ./package.json +COPY --from=builder /app/next.config.ts ./next.config.ts + +EXPOSE 3000 + +CMD ["node", "server/index.js"] From dc9db7c732cef448eb70875c6b2ada61b4897294 Mon Sep 17 00:00:00 2001 From: Luke The Dev <252071647+iamlukethedev@users.noreply.github.com> Date: Sat, 4 Apr 2026 22:25:06 -0500 Subject: [PATCH 2/3] fix(kanban): hide HUD elements when immersive board is open (#87) * fix: include kanbanImmersive in immersiveOverlayActive calculation When Kanban board is open, HUD elements (camera preset buttons, edit toolbar, overlays) should be suppressed. The kanbanImmersive flag was defined but not included in the immersiveOverlayActive condition, causing HUD elements to remain visible. This fix adds kanbanImmersive to the immersiveOverlayActive calculation so HUD elements are properly hidden when the Kanban board is open. Co-authored-by: Luke The Dev * Fix: Hide mini status bar when Kanban immersive overlay is open Wraps the bottom-left mini status bar (showing agent stats, vibe score, and control hints) with !immersiveOverlayActive check to match the behavior of other HUD elements like camera controls and toolbar. This ensures the status bar is properly hidden when the Kanban board or any other immersive overlay is active, maintaining a clean immersive experience. Co-authored-by: Luke The Dev * chore: drop unrelated package-lock line from branch Co-authored-by: Luke The Dev --------- Co-authored-by: Cursor Agent Co-authored-by: Luke The Dev From 04efa31c4014566e4d16ec811f1793d71870c6f5 Mon Sep 17 00:00:00 2001 From: Luke The Dev <252071647+iamlukethedev@users.noreply.github.com> Date: Sat, 4 Apr 2026 22:26:20 -0500 Subject: [PATCH 3/3] Add Cursor Cloud specific instructions to AGENTS.md (#85) Co-authored-by: Cursor Agent Co-authored-by: Luke The Dev --- AGENTS.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ebb9fe3..f3ba532 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,3 +9,33 @@ Do not modify the OpenClaw source code. When the user asks for changes, they are If you use local private overlay instructions, keep them outside the repository and do not commit them here. Do not commit personal, environment-specific, or secret instructions to this repository. + +## Cursor Cloud specific instructions + +### Service overview + +Claw3D is a Next.js 16 frontend (TypeScript, React 19, Three.js, Phaser) for OpenClaw. It runs a custom Node.js server (`server/index.js`) that bundles a same-origin WebSocket proxy to the upstream OpenClaw Gateway. No database or Docker is required. The only hard system dependency is Node.js 20+ with npm 10+. + +### Running the app + +- `npm run dev` starts the dev server on port 3000 via the custom server (`node server/index.js --dev`). +- The app requires a running OpenClaw Gateway to show agent data. Without one, the UI loads but shows the gateway connection form. This is expected and not an error. +- `.env` is copied from `.env.example`; see `README.md` "Configuration" for variable descriptions. + +### Lint, typecheck, and tests + +- `npm run lint` — ESLint. The codebase has a small number of pre-existing warnings and one pre-existing error (in `RetroOffice3D.tsx`). +- `npm run typecheck` — `tsc --noEmit`. Pre-existing type errors exist in some test files (`agentChatPanel-*.test.ts`) due to a stale `onOpenSettings` prop. +- `npm run test -- --run` — Vitest unit tests (use `--run` for single-run mode). A few pre-existing failures exist. +- `npm run e2e` — Playwright E2E tests; requires `npx playwright install` first. +- `npm run smoke:dev-server` — starts the dev server on a random port and verifies HTTP response. + +### Build + +- `npm run build` — Next.js production build. Expect a non-blocking warning about `Can't resolve 'openclaw'`; the `openclaw` npm package is resolved optionally at runtime and is not bundled. + +### Gotchas + +- The `openclaw` npm package is not a dependency of this repo. The build warning about it is harmless. +- `npm run studio:setup` is interactive (TTY prompts) — avoid running it in non-interactive cloud environments. +- Vitest runs in watch mode by default; always pass `--run` for CI/cloud agent use.