API Reference

public struct HBSpace: Codable, Identifiable, Equatable

// From ARWorldMap
init(id: UUID = UUID(), name: String? = nil, worldMap: ARWorldMap) throws

// From serialized data
init(id: UUID, name: String?, worldMapData: Data, createdAt: Date, updatedAt: Date)

// Serialization
static func serialize(worldMap: ARWorldMap) throws -> Data
static func deserialize(worldMapData: Data) throws -> ARWorldMap
func arWorldMap() throws -> ARWorldMap

// Mutation
mutating func update(worldMap: ARWorldMap) throws
mutating func update(name: String?)

// Utilities
func validate() -> Bool
var worldMapSize: Int { get }
var worldMapSizeFormatted: String { get }

public struct HBAnchor: Codable, Identifiable, Equatable

// From simd_float4x4
init(id: UUID = UUID(), spaceId: UUID, transform: simd_float4x4, metadata: [String: AnyCodableValue] = [:])

// From flat array
init(id: UUID, spaceId: UUID, transform: [Float], metadata: [String: AnyCodableValue], createdAt: Date, updatedAt: Date, deletedAt: Date?)

// Transform
static func flatten(_ matrix: simd_float4x4) -> [Float]
static func unflatten(_ array: [Float]) throws -> simd_float4x4
func simdTransform() throws -> simd_float4x4
var validSimdTransform: simd_float4x4? { get }
var position: SIMD3<Float> { get }
mutating func update(transform: simd_float4x4)

// Metadata
func metadata(forKey key: String) -> AnyCodableValue?
func stringMetadata(forKey key: String) -> String?
func intMetadata(forKey key: String) -> Int?
func boolMetadata(forKey key: String) -> Bool?
mutating func updateMetadata(key: String, value: AnyCodableValue?)
mutating func update(metadata: [String: AnyCodableValue])

// Deletion
mutating func markDeleted()
mutating func restore()
var isDeleted: Bool { get }

// Validation
func validate() -> Bool

public enum AnyCodableValue: Codable, Equatable

case string(String)
case int(Int)
case double(Double)
case bool(Bool)
case array([AnyCodableValue])
case dictionary([String: AnyCodableValue])
case null

var stringValue: String? { get }
var intValue: Int? { get }
var doubleValue: Double? { get }
var boolValue: Bool? { get }
var arrayValue: [AnyCodableValue]? { get }
var dictionaryValue: [String: AnyCodableValue]? { get }
var isNull: Bool { get }

public class HBStorage

init()
init(config: HBStorageConfig)

func save(_ space: HBSpace) async throws
func loadSpace(id: UUID) async throws -> HBSpace?
func loadAllSpaces() async throws -> [HBSpace]
func deleteSpace(id: UUID) async throws

func save(_ anchor: HBAnchor) async throws
func loadAnchor(id: UUID) async throws -> HBAnchor?
func loadAnchors(spaceId: UUID, includeDeleted: Bool = false) async throws -> [HBAnchor]
func deleteAnchor(id: UUID) async throws
func purgeDeletedAnchors(before: Date) async throws

func sync() async throws
var isCloudEnabled: Bool { get }
var pendingOperationCount: Int { get }

func clearLocalStorage() throws
func localStorageSize() throws -> Int

func timeline(spaceId: UUID) async throws -> HBTimeline
func anchorsAt(spaceId: UUID, date: Date) async throws -> [HBAnchor]
func diff(spaceId: UUID, from: Date, to: Date) async throws -> HBDiff
func history(anchorId: UUID) async throws -> [HBAnchorEvent]
func rollback(anchorId: UUID, toVersion: Int) async throws -> HBAnchor

public struct HBStorageConfig

let backend: HBBackend
let syncStrategy: HBSyncStrategy
let compression: HBCompressionLevel

static let `default`: HBStorageConfig

public enum HBBackend {
    case localOnly
    case supabase(url: String, anonKey: String)
}

public enum HBSyncStrategy {
    case manual
    case onSave
}

public enum HBCompressionLevel {
    case none
    case balanced
}

public enum HBStorageError: LocalizedError {
    case notFound(type: String, id: UUID)
    case encodingFailed(underlying: Error)
    case decodingFailed(underlying: Error)
    case fileSystemError(underlying: Error)
    case compressionFailed(underlying: Error)
    case decompressionFailed(underlying: Error)
    case cloudNotConfigured
    case cloudSyncFailed(underlying: Error)
    case networkError(underlying: Error)
    case unauthorized
    case serverError(statusCode: Int, message: String?)

    // Versioning errors
    case versionNotFound(anchorId: UUID, version: Int)
    case reconstructionFailed(anchorId: UUID)
    case eventLogCorrupted(spaceId: UUID)
}

public enum HBSpaceError: LocalizedError {
    case serializationFailed(underlying: Error?)
    case deserializationFailed(underlying: Error?)
    case invalidWorldMapData
}

public enum HBAnchorError: LocalizedError {
    case invalidTransform(count: Int)
    case alreadyDeleted
    case metadataKeyNotFound(key: String)
}

public enum HBCompression {
    static func compress(_ data: Data, level: HBCompressionLevel) throws -> Data
    static func decompress(_ data: Data) throws -> Data
}

public struct HBAnchorEvent: Codable, Identifiable, Equatable

public enum EventType: String, Codable {
    case created
    case moved
    case updated
    case deleted
    case restored
}

public struct HBTimeline

func events(for anchorId: UUID) -> [HBAnchorEvent]
func events(from: Date, to: Date) -> [HBAnchorEvent]
func events(ofType type: EventType) -> [HBAnchorEvent]
func state(at date: Date) -> [HBAnchor]
func diff(from: Date, to: Date) -> HBDiff
func scrubberDates(from: Date?, to: Date?, steps: Int) -> [Date]
func closestEvent(to date: Date) -> HBAnchorEvent?
var significantDates: [Date]

public struct HBDiff: Equatable

var changeCount: Int
var hasChanges: Bool
var summary: String
var currentAnchors: [HBAnchor]
var previousAnchors: [HBAnchor]

struct MovedAnchor: Equatable {
    let anchor: HBAnchor
    let previousTransform: [Float]
    var previousPosition: SIMD3<Float>
    var currentPosition: SIMD3<Float>
    var distanceMoved: Float
}

struct UpdatedAnchor: Equatable {
    let anchor: HBAnchor
    let previousMetadata: [String: AnyCodableValue]
    var addedKeys: Set<String>
    var removedKeys: Set<String>
    var changedKeys: Set<String>
}