Site Spaces

Site Spaces organize your physical environment into a navigable hierarchy of buildings, floors, wings, and rooms. Spaces can be assigned zones, modes, and floor plan blueprints for spatial visualization and AI-assisted room extraction.

Overview

The Spaces page provides:

• Hierarchical Organization: Nest spaces (building > floor > wing > room) to mirror your physical layout
• Zone Assignment: Associate control zones with specific spaces
• Mode Assignment: Set operational modes per space with inheritance from parent spaces
• Blueprint Upload: Upload floor plans and annotate them with space overlays
• AI-Powered Extraction: Analyze blueprints with AI to automatically identify and create child spaces
• UI Generation: Create user interfaces directly from spaces

Layout

The Spaces page is a single-screen tree + detail editor — no tabs, no drill-in navigation.

• Tree Rail (left) - The full space hierarchy, expandable in place. Filter box at the top.
• Center Pane - The selected space's editor, organized as scrollable sections (Overview, Mode, Blueprint, Zones, UIs, Child Spaces). When nothing is selected, a welcome panel shows summary stats (total spaces, with blueprint, linked UIs).
• Right Rail - Mode History for the selected space. Collapsible via the chevron in its header.

:::info Single root The site has exactly one root site_space, auto-managed from the Site record with This Server enabled. The server refuses any attempt to create a second root or to promote an existing space to root — every other space must live under the root. Pick the root in the tree and use Add Child to grow the hierarchy. :::

Tree Rail

Each tree row shows, left to right:

• Chevron - Click to expand/collapse children (only present when the space has children)
• Color swatch - The space's configured color
• Label - Display name (system name shown on hover); disabled spaces are dimmed and struck through
• Mode pill - Active mode (gray = inherited from a parent, blue = set directly on this space). Tooltip names the source parent for inherited modes.
• Counts/badges - Nz zone count, a map icon when a floor plan is uploaded, an eye icon when a UI is linked

Click any row to load that space into the center pane. The tree auto-expands to reveal the selected node.

Filter box - Type to filter the tree by label, name, or space type. Matching nodes and their ancestors stay visible (ancestors are dimmed if they don't match), and the tree is force-expanded so all matches are reachable. Clear the filter to restore manual expansion state.

Multi-select / bulk re-parent - Hold Shift and click to range-select rows, or Ctrl/Cmd-click to toggle individual rows. Selection is constrained to siblings — rows under the same parent. Multi-selected rows are highlighted amber. When more than one row is selected, a yellow action bar appears above the tree showing the count and current parent, with a Move to… button and a clear (×) button. Move to… opens a modal listing every valid destination parent (the current parent, the selected rows, and any of their descendants are excluded to prevent cycles); picking a destination and confirming re-parents every selected space in a single batch — children, zones, and attributes are preserved. A plain click anywhere collapses the multi-selection back to a single focused row.

Center Pane Header

Above the sections, a breadcrumb chain shows the selected space's ancestor path; click any ancestor to jump to it. A dirty dot (orange) appears when there are unsaved changes. Action buttons:

• Add Child - Start a new child space under the selected one
• Delete - Opens a dependent-aware confirmation modal (see Deleting a Space)
• Discard / Close - Discard unsaved changes (label switches to Close when clean)
• Save - Persist changes (disabled while clean)

If you click a different tree row while there are unsaved changes, you're prompted to discard them first.

Welcome Panel

When no space is selected, the center pane shows four summary tiles (Total Spaces, With Blueprint, Linked UIs, Zones Assigned) and instructions to pick a space from the tree.

Space Types

Spaces are categorized by type, which affects hierarchy behavior:

Container Types

These types can contain child spaces and support floor plan visualization:

• Building - Top-level structure
• Floor - Level within a building
• Wing - Section of a floor

Room Types

• Room - Generic room
• Bathroom, Kitchen, Living Room, Bedroom, Office - Specific room types
• Hallway, Closet, Garage, Utility, Outdoor, Other - Additional types

Creating a Space

The root space is auto-managed — you cannot create another root. To add anywhere else in the tree, select the parent and click Add Child in the center header. A fresh editor opens in the center pane with the parent pre-filled.

Overview Section

Name

• Internal identifier (lowercase_with_underscores)
• Auto-formatted on blur
• Required

Label

• Human-readable display name
• Required

Description

• Optional text describing the space

Space Type

• Select from the list of space types (Building, Floor, Room, etc.)

Parent

• The parent space in the hierarchy
• Pre-filled based on current navigation level
• Can be changed via dropdown
• Required — cannot be cleared (only the auto-managed site root is allowed to be parentless)

Color

• Color code for UI and floor plan visualization
• New overlays drawn on a floor plan cycle through a built-in palette (blue, green, orange, purple, teal, pink, amber, red, cyan, slate), skipping colors already used by siblings under the same parent, so adjacent rooms get visually distinct colors out of the box

Tags

• Comma-separated tags for categorization and filtering

Sort Index

• Numeric value controlling display order

Enabled

• Toggle to enable/disable the space

Create UI? (only shown when creating a new space)

• When checked, an accompanying UI is auto-created and bound to the new space via site_space_id with include_child_spaces enabled. The UI's group defaults to the parent space's label (or "Spaces" at the root) and the prodigy theme is applied.

Deleting a Space

Clicking Delete opens a confirmation modal that first inspects every row referencing the space:

• Child spaces — listed as a blocker; reparent or delete them first.
• Zones — listed as a blocker; reassign each zone's site_space_id first.
• UIs — listed as an unlink warning, not a blocker. Deleting clears each UI's site_space_id; those UIs surface at the top of the launcher as orphans until re-linked or deleted.

The Delete button stays disabled while any blocker rows exist. When the modal is unblocked and you confirm, the success toast reports how many UIs were unlinked (if any).

Mode Section

Visible once the space is saved. Shows the active mode as a large pill (gray = inherited, blue = direct), the inheritance chain back to the ancestor that supplied the mode (annotated with source), and inline controls to:

• Set a mode — pick from the dropdown; changes apply immediately via SiteModeManager (no need to click Save).
• Clear & inherit — only shown when this space has a direct mode; reverts to parent inheritance.

Mode changes captured here are recorded in the Mode History right rail. The effective-mode display for the tree auto-refreshes every 30 seconds.

See Site Modes for defining the modes available here.

Blueprint Section

Container spaces (Building, Floor, Wing) can have a floor plan image uploaded for spatial visualization.

• Upload Floor Plan / Replace Floor Plan - PNG, JPG, or WebP
• Extract Spaces with AI - Visible once a blueprint exists AND an Anthropic API key is configured (System Attributes > anthropic_api_key)
• Edit Layout (header) - Toggle the floor plan viewer between view and edit modes when overlays exist
• Crop Image (Edit Layout modal) - Trim the blueprint to a tighter rectangle. The drag handles let you frame the area to keep; a shaded inner rectangle marks the bounding box of all existing immediate child overlays — the crop can't shrink past it so cropping never slices into a placed room. Applying the crop re-renders the blueprint, re-uploads it, and rewrites each immediate child's bounds against the new image. Deeper descendants are stored relative to their immediate parent and don't need to move.

Once uploaded, the floor plan renders every bounded descendant as an overlay — not just direct children. Nested bounds are composed automatically (a room inside a wing inside a floor lands in the right pixel position on the floor's blueprint). Each overlay shows the space label, its active mode pill (if any), and a subsystem rollup chip row summarizing the zones that live in the space (e.g. 4 lights, 2 shades). When a zone in the space is currently active (e.g. lights on, door unlocked), the overlay pulses softly in the leading subsystem's color — alert subsystems (security/doors/locks/gates/garages/power/fire) win the color pick over comfort subsystems when both are active. In edit mode (toggle via Edit Layout in the section header) the overlays become drag/resizable for placement; drags are decomposed back into the immediate parent's coordinate system on save, so you can rearrange a deeply nested room from any ancestor's plan. In view mode, clicking an overlay opens that space's zones — if there's only one zone, the live control modal opens directly (same control component the zone uses in UIs); otherwise a chip picker lists the zones so you can pick one.

If a space does not have its own blueprint but lives inside an ancestor that does, the section displays an inherited view: a zoomed crop of the nearest ancestor's blueprint, framed to this space's bounds. It renders the same label / mode pill / subsystem chips / activity pulse as the overlay does on the parent plan, and clicking it opens the same zone chooser. Edit Layout is available on inherited views too — drag to draw or move child overlays directly on the cropped image without uploading a separate blueprint for the leaf.

AI Blueprint Extraction

1. Click Extract Spaces with AI - the model examines the floor plan and identifies rooms/spaces
2. Review the Extracted Spaces list - each entry shows a checkbox, color swatch, name, and type
3. Optionally toggle Also create UIs to generate a UI per extracted space (each bound via site_space_id, include_child_spaces enabled, prodigy theme applied)
4. Click Create N Spaces - the selected spaces are inserted as children of the current space

Zones Section

Visible once the space is saved.

• Assigned zones render as clickable chips (label + subsystem badge). Clicking a chip opens the zone's control inline in a modal — the same control component the zone uses in user UIs (dimmer, climate, gate, lock, etc.), based on the zone's control setting. If control matches a user-defined Svelte widget instead of a built-in control, that widget is rendered. The active UI theme is applied so themed components render with their normal appearance.
• Assign / Unassign Zones uses a MultiSelector tied to all enabled zones. Optionally filter by subsystem first. Adding a zone updates its site_space_id immediately; removing one clears it.

UIs Section

If a UI is linked to this space (site_space_id on the UI record) it's displayed with Open UI — launches in a new tab. Sub-info shows whether the UI is set to include_child_spaces and any group value.

If no UI is linked, Create UI generates one:

• UI name matches the space name; label matches the space label
• include_child_spaces is enabled automatically for container types
• The UI is linked to the space via site_space_id and gets the prodigy theme

Child Spaces Section

Compact table of direct children (label, type, zones, mode, badges). Click any row to navigate to that child. Add Child in the section header creates a new child under the current space.

Mode History (right rail)

The right rail records every mode change for the selected space — direct or inherited-from-parent — with timestamp, action (activated / cleared / etc.), and the resolved mode. Up to 20 most recent rows are shown. Collapse the rail with the chevron in its header; reopen with the small toggle that takes its place. Hidden on narrower viewports (< 1100px).

Database Schema

Column	Type	Description
id	INTEGER	Primary key
name	STRING	Internal name (required)
label	STRING	Display name
description	STRING	Optional description
tags	JSON	Array of string tags
sort_index	INTEGER	Display order
enabled	BOOLEAN	Active state (default: true)
site_mode_id	INTEGER	FK to site_mode (direct mode assignment)
parent_site_space_id	INTEGER	FK to parent site_space (hierarchy)
space_type	STRING	Type classification
blueprint	TEXT	Floor plan image data
bounds	JSON	Position/size on parent's floor plan
color	STRING	Color code for visualization

Common Use Cases

Residential Home

Home (Building)
  First Floor (Floor)
    Living Room (Living Room) - zones: living_lights, living_shades
    Kitchen (Kitchen) - zones: kitchen_lights, kitchen_fan
    Master Bedroom (Bedroom) - zones: master_lights, master_shades
  Second Floor (Floor)
    Kids Room (Bedroom)
    Office (Office)
  Garage (Garage)

Commercial Building

Office Tower (Building)
  Floor 1 (Floor) - mode: business_hours
    Lobby (Hallway)
    Conference Room A (Room)
    Conference Room B (Room)
  Floor 2 (Floor) - mode: business_hours
    East Wing (Wing)
      Office 201 (Office)
      Office 202 (Office)
    West Wing (Wing)
      Open Plan (Room)

Best Practices

1. Start with Structure: Create the building/floor/wing hierarchy first, then add rooms
2. Use Labels: Always set labels for user-friendly display in UIs
3. Assign Zones: Link zones to the most specific space possible
4. Use Modes Sparingly: Set modes at the highest level that makes sense; let child spaces inherit
5. Upload Blueprints: Floor plans on container spaces enable visual navigation for users
6. Use AI Analysis: For complex floor plans, AI extraction saves significant manual effort
7. Create UIs: Generate UIs directly from spaces to maintain a consistent mapping

Related Documentation

• Site Modes - Defining operational modes for spaces
• Sites - Multi-site management
• Zones - Zone configuration
• UIs - User interface management