The isWithinHome() check used path.relative() which is purely string-based
and does not follow symlinks. A symlink inside the home directory pointing
to an external path would bypass the containment check, allowing directory
listing of arbitrary filesystem locations.
Now uses fs.realpathSync() to resolve symlinks before the containment
comparison, ensuring the real filesystem path is validated.
Co-authored-by: ThankNIXlater <ThankNIXlater@users.noreply.github.com>
* feat(ui): improve visual polish, responsiveness, and UX consistency
- GatewayConnectScreen: replace hardcoded text-white* with semantic
foreground/muted-foreground tokens so the connect form is readable
in both light and dark modes
- HeaderBar: show gateway status chip for "connected" state in addition
to "connecting", giving users clear visual feedback once connected
- FleetSidebar: add aria-label and aria-pressed to agent row buttons
for screen-reader accessibility
- HQSidebar: add role=tablist/tab/tabpanel, aria-selected, aria-controls,
and aria-labelledby to the headquarters panel tabs
- OfficePage: replace Suspense fallback={null} with a themed spinner
so users see feedback instead of a blank screen during initial load
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(office): widen agent nameplate to prevent name truncation
- Expand background plane from 0.68 to 1.1 width
- Increase maxWidth from 0.56 to 1.0
- Slightly reduce fontSize 0.1 to 0.09 for better fit
- Add whiteSpace nowrap to prevent wrapping
- Truncate names >14 chars with ellipsis for very long agent names
---------
Co-authored-by: Claw3D UI Bot <ui-improvements@claw3d.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(issue-17): add onboarding wizard for new users
Adds a step-based onboarding wizard that guides new users through their
first Claw3D setup: welcome, prerequisites, gateway connection, agent
discovery, and a completion screen.
Architecture:
src/features/onboarding/ (new feature module):
- types.ts: Step definitions, navigation helpers (getNextStep/getPrevStep)
- useOnboardingState.ts: localStorage-backed persistence hook
- index.ts: Barrel exports for clean imports
- components/OnboardingWizard.tsx: Main wizard container with step
navigation, progress bar, and modal overlay
- components/WelcomeStep.tsx: Feature highlights grid
- components/PrerequisitesStep.tsx: Checklist with links/commands
- components/ConnectStep.tsx: Compact gateway connection form
- components/AgentsStep.tsx: Agent discovery feedback
- components/CompleteStep.tsx: Final screen with CTA
Design decisions:
- Modular step system: new steps can be added by extending
OnboardingStepId and registering a component in the switch
- localStorage persistence: wizard shows once per browser, resettable
from settings (future: wire into Studio settings API)
- Connect step gates forward navigation: users cannot skip connection
- Follows Claw3D conventions: feature-first module, no shared state
pollution, Tailwind utility classes, lucide-react icons
- Does NOT modify existing routes or components — zero-risk integration
(parent wiring left to maintainer preference)
Integration guide (for maintainer):
1. Import { OnboardingWizard, useOnboardingState } from the module
2. Add useOnboardingState() to the root layout or agents page
3. Render <OnboardingWizard /> when showOnboarding is true
4. Pass gateway connection props from existing store
tests/unit/onboardingTypes.test.ts (13 tests):
- Step structure validation, navigation helpers, ordering
tests/unit/onboardingState.test.ts (5 tests):
- localStorage persistence, show/hide/reset lifecycle
Addresses #17
* fix(onboarding): wire wizard launch into office UI
Mount the onboarding wizard in OfficeScreen and add a settings action that can re-open it so the new-user flow is reachable and testable.
Made-with: Cursor
---------
Co-authored-by: Neo <neo@openclaw.ai>
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
* fix(issue-5): add collision-aware pathfinding to Phaser office viewer
Agents in the Phaser office viewer previously moved in straight lines toward
zone anchors, ignoring walls, furniture, and collision geometry. This made
agents walk through rendered map obstacles.
Changes:
src/lib/office/pathfinding.ts (new):
- Shared 2D A* pathfinding module for OfficeMap surfaces
- Builds a nav grid from map objects (walls/furniture layers) and
collision polygons with configurable cell size and padding
- Diagonal corner-cutting prevention (checks both orthogonal neighbors)
- Returns empty path on failure instead of raw destination fallback
- Point-in-polygon rasterisation for collision polygon support
- Intentionally placed in src/lib/office/ for reuse across office stacks
src/features/office/phaser/systems/AgentEffectsSystem.ts:
- Computes A* waypoint paths when agent targets change
- Follows waypoints sequentially instead of linear interpolation
- Caches nav grid and invalidates on map identity change
- Agents stay put when no valid path exists (no wall clipping)
tests/unit/officePathfinding.test.ts (new):
- 12 unit tests covering grid construction, A* routing, corner-cutting
prevention, collision polygon support, blocked-start recovery, and
starter map integration
Fixes#5
* fix(test): remove unused NavGrid2D type import
---------
Co-authored-by: Neo <neo@openclaw.ai>
* fix(issue-4): add missing solid floor props to BLOCKING_TYPES
Audited all furniture types defined in furnitureDefaults.ts and
geometry.ts (ITEM_FOOTPRINT) against BLOCKING_TYPES in navigation.ts.
Added five previously missing solid floor props:
- water_cooler: freestanding floor appliance, agents pathfound through it
- server_terminal: floor-standing terminal in the server room
- dishwasher: floor appliance in the kitchen area
- easel: floor-standing art-room prop
- beanbag: floor seat large enough to obstruct walking paths
Also adds a unit test asserting every newly-added type is correctly
blocked in the nav grid, and that non-solid desk decorations (keyboard)
remain free.
* refactor(nav): replace hardcoded BLOCKING_TYPES with metadata-driven ITEM_METADATA
Previously, buildNavGrid() maintained a hardcoded BLOCKING_TYPES set in
navigation.ts. The issue #4 fix added the five missing solid props directly
to that set, but this approach is brittle — every new furniture type requires
a separate PR touching navigation.ts to stay correct.
This rework introduces ITEM_METADATA in geometry.ts (alongside the existing
ITEM_FOOTPRINT record) as the single source of truth for per-type navigation
properties:
export const ITEM_METADATA: Record<string, { blocksNavigation: boolean }>
Each item type explicitly declares blocksNavigation: true/false. The five
props fixed in issue #4 (water_cooler, server_terminal, dishwasher, easel,
beanbag) retain their blocking status. Unknown types default to false, so
future decorative items never accidentally block navigation.
Changes:
- geometry.ts: add ITEM_METADATA export (64 type entries)
- navigation.ts: remove BLOCKING_TYPES set; add itemBlocksNavigation() helper
that reads ITEM_METADATA[type]?.blocksNavigation ?? false; update buildNavGrid()
to call it
- tests/unit/navigation.navBlockers.test.ts: retain original 5 solid-prop tests;
add metadata-driven test suite covering: all blocking types from metadata,
all non-blocking types from metadata, runtime-added type with blocksNavigation:true,
and unknown-type safe fallback
All 10 tests pass; lint clean; only pre-existing TS2367 (issue #13) remains.
* test(navigation): add extended nav blocker tests (issue #4)
Additional tests for buildNavGrid and astar pathfinding:
- Adjacent blocking items create a continuous impassable wall
- Blocking item near grid edge/boundary causes no out-of-bounds errors
- Full pathfinding integration: astar routes AROUND a cabinet placed between
start and end (not just that cells are blocked)
- desk_cubicle explicitly does NOT block — confirmed via ITEM_METADATA
- door explicitly does NOT block — agents must walk through doors
---------
Co-authored-by: Neo (subagent) <neo@openclaw.local>
* fix(issue-6): prevent A* diagonal corner-cutting through blocked cells
The A* neighbor loop previously checked only whether the destination cell
was free. For diagonal moves this allows agents to clip through the corner
of a blocked cell — the two orthogonal neighbours (e.g. N and E for a NE
move) were never validated.
Fix: after confirming the diagonal destination is free, additionally check
both orthogonal intermediary cells. If either is blocked, the diagonal
expansion is skipped and the agent must route around the obstacle.
Adds three unit tests covering:
- a path that would clip a single corner (rejected after fix)
- a path through open space (diagonals still used freely)
- a path around a multi-cell wall segment (no cells in the wall visited)
* chore: remove unused imports from diagonal corner test (lint cleanup)
* test(navigation): add expanded diagonal corner-cutting tests (issue #6)
Additional tests for astar diagonal corner-cutting prevention:
- All 4 diagonal directions (NE, NW, SE, SW): block orthogonal neighbour,
verify path avoids the blocked cell in each direction
- Both orthogonal sides blocked: verify no diagonal move is taken from start
- L-shaped wall: verify agent navigates around entire L without clipping any segment
- Dense grid stress test: maze-like layout verifying valid path found and no
waypoint lands on a blocked cell
---------
Co-authored-by: Neo (subagent) <neo@openclaw.local>
* Fix WS auth: wire accessGate.allowUpgrade via verifyClient
The allowWs callback was never actually calling accessGate.allowUpgrade
during the WS handshake - the ws library passes (info) not (req), and
verifyClient must be set on the WebSocketServer constructor options.
Fix: pass verifyClient to WebSocketServer constructor and wrap
allowUpgrade to extract info.req.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Fix TypeScript error and add gym release directive support
Add "release" value to OfficeGymDirective type for symmetry with
OfficeQaDirective ("qa_lab" | "release"). Previously OfficeGymDirective
was only "gym" with no release state, making the "!== 'release'"
check in eventTriggers.ts dead code that TypeScript flagged as an
unintentional comparison.
Changes:
- deskDirectives.ts: add "release" to OfficeGymDirective type
- deskDirectives.ts: add gym release patterns to skill and command
directive resolvers (e.g. "leave the gym", "done with skills")
- eventTriggers.ts: change !== "release" to === "gym" for clarity
and consistency with reduceOfficeGymHoldState pattern
This fixes: https://github.com/iamlukethedev/Claw3D/issues/15
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Nix