@nice2dev/spatial-core 1.0.10

package/dist/serialization/index.js

@@ -0,0 +1,412 @@
+/**
+ * Serialization — .nsp.json (NiceToDev Spatial Plan) format.
+ *
+ * Unified serialization format for all spatial documents:
+ * - Floor plans
+ * - Network topologies
+ * - CAD drawings
+ * - Interior designs
+ * - Game scenes
+ *
+ * @module @nice2dev/spatial-core/serialization
+ */
+/* ================================================================
+   JSON SCHEMA
+   ================================================================ */
+/** JSON Schema for .nsp.json validation. */
+export const NSP_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $id: 'https://nice2dev.com/schemas/nsp-v1.json',
+    title: 'NiceToDev Spatial Plan',
+    description: 'Unified format for floor plans, network topologies, CAD drawings, and spatial documents',
+    type: 'object',
+    required: ['version', 'type', 'metadata', 'floors', 'settings'],
+    properties: {
+        $schema: { type: 'string' },
+        version: {
+            type: 'string',
+            pattern: '^\\d+\\.\\d+\\.\\d+$',
+        },
+        type: {
+            type: 'string',
+            enum: ['floor-plan', 'network-topology', 'infrastructure', 'cad', 'interior', 'game-scene'],
+        },
+        metadata: {
+            type: 'object',
+            required: ['id', 'name', 'created', 'modified'],
+            properties: {
+                id: { type: 'string' },
+                name: { type: 'string' },
+                description: { type: 'string' },
+                author: { type: 'string' },
+                created: { type: 'string', format: 'date-time' },
+                modified: { type: 'string', format: 'date-time' },
+                tags: { type: 'array', items: { type: 'string' } },
+                thumbnail: { type: 'string' },
+            },
+        },
+        building: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                address: { type: 'string' },
+                type: { type: 'string' },
+                totalArea: { type: 'number' },
+                floors: { type: 'integer' },
+                yearBuilt: { type: 'integer' },
+                coordinates: {
+                    type: 'object',
+                    properties: {
+                        lat: { type: 'number' },
+                        lng: { type: 'number' },
+                    },
+                },
+            },
+        },
+        floors: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['id', 'name', 'level', 'bounds', 'layers'],
+                properties: {
+                    id: { type: 'string' },
+                    name: { type: 'string' },
+                    level: { type: 'integer' },
+                    elevation: { type: 'number' },
+                    ceilingHeight: { type: 'number' },
+                    bounds: {
+                        type: 'object',
+                        properties: {
+                            x: { type: 'number' },
+                            y: { type: 'number' },
+                            width: { type: 'number' },
+                            height: { type: 'number' },
+                        },
+                    },
+                    layers: { type: 'array' },
+                },
+            },
+        },
+        settings: {
+            type: 'object',
+            properties: {
+                units: { type: 'string', enum: ['metric', 'imperial'] },
+                scale: { type: 'number' },
+                grid: { type: 'object' },
+                defaultWallHeight: { type: 'number' },
+                defaultWallThickness: { type: 'number' },
+                precision: { type: 'integer' },
+            },
+        },
+    },
+};
+/* ================================================================
+   SERIALIZATION
+   ================================================================ */
+/**
+ * Serialize floor plan document to JSON string.
+ */
+export function serialize(document, options = {}) {
+    const { pretty = false, includeSchema = true, excludeEmptyLayers = false, includeMetadata = true, } = options;
+    // Deep clone to avoid mutation
+    const output = JSON.parse(JSON.stringify(document));
+    // Add schema reference
+    if (includeSchema && !output.$schema) {
+        output.$schema = 'https://nice2dev.com/schemas/nsp-v1.json';
+    }
+    // Update modified timestamp
+    if (includeMetadata) {
+        output.metadata = output.metadata ?? {
+            id: '',
+            name: '',
+            created: new Date().toISOString(),
+            modified: new Date().toISOString(),
+        };
+        output.metadata.modified = new Date().toISOString();
+    }
+    // Filter empty layers if requested
+    if (excludeEmptyLayers) {
+        for (const floor of output.floors) {
+            floor.layers = floor.layers.filter((layer) => layer.objects.length > 0);
+        }
+    }
+    return pretty ? JSON.stringify(output, null, 2) : JSON.stringify(output);
+}
+/**
+ * Deserialize JSON string to floor plan document.
+ */
+export function deserialize(json) {
+    try {
+        const data = JSON.parse(json);
+        const validation = validate(data);
+        if (!validation.valid) {
+            return {
+                success: false,
+                errors: validation.errors.map((e) => `${e.path}: ${e.message}`),
+            };
+        }
+        return {
+            success: true,
+            data,
+            warnings: validation.warnings.map((w) => w.message),
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            errors: [`Invalid JSON: ${error.message}`],
+        };
+    }
+}
+/**
+ * Validate floor plan document against schema.
+ */
+export function validate(document) {
+    const errors = [];
+    const warnings = [];
+    // Required fields
+    if (!document.version) {
+        errors.push({ path: 'version', message: 'Version is required', code: 'MISSING_VERSION' });
+    }
+    if (!document.type) {
+        errors.push({ path: 'type', message: 'Type is required', code: 'MISSING_TYPE' });
+    }
+    if (!document.metadata?.id) {
+        errors.push({ path: 'metadata.id', message: 'Metadata ID is required', code: 'MISSING_ID' });
+    }
+    if (!document.metadata?.name) {
+        errors.push({
+            path: 'metadata.name',
+            message: 'Metadata name is required',
+            code: 'MISSING_NAME',
+        });
+    }
+    if (!document.floors) {
+        errors.push({ path: 'floors', message: 'Floors array is required', code: 'MISSING_FLOORS' });
+    }
+    if (!document.settings) {
+        errors.push({
+            path: 'settings',
+            message: 'Settings object is required',
+            code: 'MISSING_SETTINGS',
+        });
+    }
+    // Version format
+    if (document.version && !/^\d+\.\d+\.\d+$/.test(document.version)) {
+        warnings.push({
+            path: 'version',
+            message: 'Version should be in semver format (x.y.z)',
+            code: 'INVALID_VERSION_FORMAT',
+        });
+    }
+    // Valid type
+    const validTypes = [
+        'floor-plan',
+        'network-topology',
+        'infrastructure',
+        'cad',
+        'interior',
+        'game-scene',
+    ];
+    if (document.type && !validTypes.includes(document.type)) {
+        errors.push({
+            path: 'type',
+            message: `Invalid type. Must be one of: ${validTypes.join(', ')}`,
+            code: 'INVALID_TYPE',
+        });
+    }
+    // Validate floors
+    if (document.floors) {
+        for (let i = 0; i < document.floors.length; i++) {
+            const floor = document.floors[i];
+            if (!floor.id) {
+                errors.push({
+                    path: `floors[${i}].id`,
+                    message: 'Floor ID is required',
+                    code: 'MISSING_FLOOR_ID',
+                });
+            }
+            if (!floor.name) {
+                warnings.push({
+                    path: `floors[${i}].name`,
+                    message: 'Floor name is recommended',
+                    code: 'MISSING_FLOOR_NAME',
+                });
+            }
+            // Check for duplicate IDs
+            const ids = new Set();
+            for (const layer of floor.layers || []) {
+                for (const obj of layer.objects || []) {
+                    if (ids.has(obj.id)) {
+                        errors.push({
+                            path: `floors[${i}].objects`,
+                            message: `Duplicate object ID: ${obj.id}`,
+                            code: 'DUPLICATE_ID',
+                        });
+                    }
+                    ids.add(obj.id);
+                }
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/* ================================================================
+   IMPORT / EXPORT
+   ================================================================ */
+/**
+ * Parse .nsp.json file.
+ */
+export async function importNSP(file) {
+    try {
+        const text = await file.text();
+        return deserialize(text);
+    }
+    catch (error) {
+        return {
+            success: false,
+            errors: [`Failed to read file: ${error.message}`],
+        };
+    }
+}
+/**
+ * Create .nsp.json file blob.
+ */
+export function exportNSP(document, options) {
+    const json = serialize(document, { pretty: true, ...options });
+    return new Blob([json], { type: 'application/json' });
+}
+/**
+ * Download .nsp.json file.
+ */
+export function downloadNSP(document, filename = 'floor-plan.nsp.json', options) {
+    const blob = exportNSP(document, options);
+    const url = URL.createObjectURL(blob);
+    const a = globalThis.document.createElement('a');
+    a.href = url;
+    a.download = filename.endsWith('.nsp.json') ? filename : `${filename}.nsp.json`;
+    globalThis.document.body.appendChild(a);
+    a.click();
+    globalThis.document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+}
+/* ================================================================
+   SVG EXPORT
+   ================================================================ */
+/**
+ * Export floor to SVG.
+ */
+export function exportFloorToSVG(floor, options = {}) {
+    const { width = floor.bounds.width, height = floor.bounds.height, scale = 1, background = '#ffffff', showGrid = true, showLabels = true, } = options;
+    const svgWidth = width * scale;
+    const svgHeight = height * scale;
+    let svg = `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" 
+     width="${svgWidth}" 
+     height="${svgHeight}" 
+     viewBox="${floor.bounds.x} ${floor.bounds.y} ${width} ${height}">
+  <rect x="${floor.bounds.x}" y="${floor.bounds.y}" width="${width}" height="${height}" fill="${background}"/>
+`;
+    // Grid
+    if (showGrid) {
+        svg += `  <defs>
+    <pattern id="grid" width="1" height="1" patternUnits="userSpaceOnUse">
+      <path d="M 1 0 L 0 0 0 1" fill="none" stroke="#e0e0e0" stroke-width="0.02"/>
+    </pattern>
+  </defs>
+  <rect x="${floor.bounds.x}" y="${floor.bounds.y}" width="${width}" height="${height}" fill="url(#grid)"/>
+`;
+    }
+    // Render layers in order
+    for (const layer of floor.layers) {
+        if (!layer.visible) {
+            continue;
+        }
+        svg += `  <g id="layer-${layer.id}" opacity="${layer.opacity}">
+`;
+        for (const obj of layer.objects) {
+            svg += renderObjectToSVG(obj, showLabels);
+        }
+        svg += `  </g>
+`;
+    }
+    svg += '</svg>';
+    return svg;
+}
+/**
+ * Render a single object to SVG.
+ */
+function renderObjectToSVG(obj, showLabels) {
+    const { bounds, name, type } = obj;
+    if (!bounds) {
+        return '';
+    }
+    let svg = '';
+    // Basic rectangle representation
+    svg += `    <rect x="${bounds.x}" y="${bounds.y}" width="${bounds.width}" height="${bounds.height}" 
+          fill="#cccccc" stroke="#333333" stroke-width="0.05" 
+          data-id="${obj.id}" data-type="${type}"/>
+`;
+    // Label
+    if (showLabels && name) {
+        const cx = bounds.x + bounds.width / 2;
+        const cy = bounds.y + bounds.height / 2;
+        svg += `    <text x="${cx}" y="${cy}" text-anchor="middle" dominant-baseline="middle" 
+          font-family="sans-serif" font-size="0.3" fill="#333333">${escapeXml(name)}</text>
+`;
+    }
+    return svg;
+}
+/**
+ * Escape XML special characters.
+ */
+function escapeXml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/** Version migrations. */
+const MIGRATIONS = {
+    // Example: migrate from 0.9.x to 1.0.0
+    '0.9': (doc) => {
+        return {
+            ...doc,
+            version: '1.0.0',
+        };
+    },
+};
+/**
+ * Migrate document to latest version.
+ */
+export function migrate(document) {
+    let current = document;
+    const currentVersion = document.version || '1.0.0';
+    const [major, minor] = currentVersion.split('.').map(Number);
+    // Apply migrations in order
+    for (const [version, migration] of Object.entries(MIGRATIONS)) {
+        const [migMajor, migMinor] = version.split('.').map(Number);
+        if (major < migMajor || (major === migMajor && minor < migMinor)) {
+            current = migration(current);
+        }
+    }
+    return current;
+}
+export default {
+    serialize,
+    deserialize,
+    validate,
+    importNSP,
+    exportNSP,
+    downloadNSP,
+    exportFloorToSVG,
+    migrate,
+    NSP_SCHEMA,
+};
+//# sourceMappingURL=index.js.map

package/dist/serialization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/serialization/index.ts"],"names":[],"mappings":"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"}

package/dist/topology/index.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Topology Layer — Network topology overlay for floor plans.
+ *
+ * Provides:
+ * - Device connections (cables, wireless links)
+ * - Network paths and routing
+ * - Cable routing with pathfinding
+ * - VLAN visualization
+ * - Signal strength / coverage areas
+ *
+ * @module @nice2dev/spatial-core/topology
+ */
+import type { Point2D, BoundingBox } from '../grid';
+/** Connection medium type. */
+export type ConnectionMedium = 'ethernet-cat5' | 'ethernet-cat6' | 'ethernet-cat6a' | 'ethernet-cat7' | 'fiber-single' | 'fiber-multi' | 'coax' | 'power-line' | 'wifi-2.4ghz' | 'wifi-5ghz' | 'wifi-6ghz' | 'bluetooth' | 'zigbee' | 'z-wave' | 'thread' | 'matter' | 'lora' | 'cellular-4g' | 'cellular-5g' | 'serial' | 'usb' | 'hdmi' | 'displayport' | 'custom';
+/** Connection status. */
+export type ConnectionStatus = 'active' | 'inactive' | 'error' | 'degraded' | 'unknown';
+/** Network connection between two devices. */
+export interface TopologyConnection {
+    id: string;
+    /** Source device ID. */
+    sourceId: string;
+    /** Source port/interface name. */
+    sourcePort?: string;
+    /** Target device ID. */
+    targetId: string;
+    /** Target port/interface name. */
+    targetPort?: string;
+    /** Connection medium. */
+    medium: ConnectionMedium;
+    /** Cable/path waypoints (for non-straight routes). */
+    waypoints: Point2D[];
+    /** Connection status. */
+    status: ConnectionStatus;
+    /** Bandwidth in Mbps (null for wireless). */
+    bandwidth?: number;
+    /** Latency in ms. */
+    latency?: number;
+    /** Signal strength in dBm (for wireless). */
+    signalStrength?: number;
+    /** VLAN ID. */
+    vlanId?: number;
+    /** Cable label/ID. */
+    cableLabel?: string;
+    /** Cable length in meters. */
+    cableLength?: number;
+    /** Color for visualization. */
+    color?: string;
+    /** Line style. */
+    lineStyle?: 'solid' | 'dashed' | 'dotted';
+    /** Line width in pixels. */
+    lineWidth?: number;
+    /** Custom metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** Network path (route between two endpoints). */
+export interface NetworkPath {
+    id: string;
+    /** Start device ID. */
+    startDeviceId: string;
+    /** End device ID. */
+    endDeviceId: string;
+    /** Ordered list of connection IDs forming the path. */
+    connectionIds: string[];
+    /** Total latency (sum of all connections). */
+    totalLatency: number;
+    /** Bottleneck bandwidth (minimum of all connections). */
+    bottleneckBandwidth: number;
+    /** Path status (worst of all connections). */
+    status: ConnectionStatus;
+    /** Is this the primary path? */
+    isPrimary: boolean;
+    /** Path color for visualization. */
+    color?: string;
+}
+/** Cable route segment (for conduit/tray visualization). */
+export interface CableRoute {
+    id: string;
+    /** Route type. */
+    type: 'conduit' | 'tray' | 'raceway' | 'underground' | 'aerial' | 'wall' | 'ceiling' | 'floor';
+    /** Route path points. */
+    path: Point2D[];
+    /** Route width in cm. */
+    width: number;
+    /** Capacity (number of cables). */
+    capacity: number;
+    /** Current fill (number of cables). */
+    currentFill: number;
+    /** Cables in this route. */
+    connectionIds: string[];
+    /** Color for visualization. */
+    color?: string;
+}
+/** VLAN definition. */
+export interface VLAN {
+    id: number;
+    name: string;
+    description?: string;
+    /** Color for visualization. */
+    color: string;
+    /** Devices in this VLAN. */
+    deviceIds: string[];
+    /** IP subnet (CIDR notation). */
+    subnet?: string;
+    /** Gateway IP. */
+    gateway?: string;
+    /** DHCP enabled. */
+    dhcpEnabled?: boolean;
+}
+/** Network zone (security/functional grouping). */
+export interface NetworkZone {
+    id: string;
+    name: string;
+    type: 'dmz' | 'lan' | 'wan' | 'guest' | 'iot' | 'management' | 'voip' | 'storage' | 'custom';
+    /** Zone boundary polygon. */
+    boundary: Point2D[];
+    /** Floor ID. */
+    floorId: string;
+    /** VLANs in this zone. */
+    vlanIds: number[];
+    /** Security level (0-10). */
+    securityLevel: number;
+    /** Color for visualization. */
+    color: string;
+    /** Firewall rules applied. */
+    firewallRules?: string[];
+}
+/** Wireless coverage area. */
+export interface WirelessCoverage {
+    id: string;
+    /** Access point device ID. */
+    accessPointId: string;
+    /** Frequency band. */
+    band: '2.4ghz' | '5ghz' | '6ghz';
+    /** Coverage polygon (signal strength boundary). */
+    coveragePolygon: Point2D[];
+    /** Signal strength at boundary (dBm). */
+    boundarySignalStrength: number;
+    /** Estimated max range in meters. */
+    maxRange: number;
+    /** Channel number. */
+    channel?: number;
+    /** Transmit power in dBm. */
+    txPower?: number;
+    /** Color gradient for heatmap. */
+    colorGradient?: string[];
+}
+/** Signal measurement point. */
+export interface SignalMeasurement {
+    id: string;
+    /** Position. */
+    position: Point2D;
+    /** Access point ID. */
+    accessPointId: string;
+    /** Signal strength in dBm. */
+    signalStrength: number;
+    /** Noise level in dBm. */
+    noiseLevel?: number;
+    /** SNR in dB. */
+    snr?: number;
+    /** Timestamp. */
+    timestamp: string;
+}
+/** Complete network topology layer. */
+export interface TopologyLayer {
+    id: string;
+    /** Floor ID this topology belongs to. */
+    floorId: string;
+    /** Network devices (references to spatial objects). */
+    deviceIds: string[];
+    /** Connections between devices. */
+    connections: TopologyConnection[];
+    /** Cable routes. */
+    cableRoutes: CableRoute[];
+    /** VLANs. */
+    vlans: VLAN[];
+    /** Network zones. */
+    zones: NetworkZone[];
+    /** Wireless coverage areas. */
+    wirelessCoverage: WirelessCoverage[];
+    /** Signal measurements (for heatmaps). */
+    measurements: SignalMeasurement[];
+    /** Computed network paths. */
+    paths: NetworkPath[];
+}
+/**
+ * Create a new network connection.
+ */
+export declare function createConnection(sourceId: string, targetId: string, medium: ConnectionMedium, options?: Partial<TopologyConnection>): TopologyConnection;
+/**
+ * Create empty topology layer.
+ */
+export declare function createTopologyLayer(floorId: string): TopologyLayer;
+/**
+ * Check if medium is wireless.
+ */
+export declare function isWireless(medium: ConnectionMedium): boolean;
+/**
+ * Get default color for connection medium.
+ */
+export declare function getDefaultConnectionColor(medium: ConnectionMedium): string;
+/**
+ * Get bandwidth for connection medium (typical max).
+ */
+export declare function getTypicalBandwidth(medium: ConnectionMedium): number | null;
+/**
+ * Build adjacency graph from connections.
+ */
+export declare function buildAdjacencyGraph(connections: TopologyConnection[]): Map<string, Array<{
+    deviceId: string;
+    connection: TopologyConnection;
+}>>;
+/**
+ * Find shortest path between two devices (Dijkstra).
+ */
+export declare function findShortestPath(connections: TopologyConnection[], startDeviceId: string, endDeviceId: string, metric?: 'latency' | 'hops' | 'bandwidth'): NetworkPath | null;
+/**
+ * Find all paths between two devices (for redundancy analysis).
+ */
+export declare function findAllPaths(connections: TopologyConnection[], startDeviceId: string, endDeviceId: string, maxPaths?: number): NetworkPath[];
+/**
+ * Calculate optimal cable route avoiding obstacles.
+ * Uses A* pathfinding on a grid.
+ */
+export declare function calculateCableRoute(start: Point2D, end: Point2D, obstacles: BoundingBox[], gridSize?: number): Point2D[];
+/**
+ * Estimate wireless coverage area.
+ * Simple model based on distance and obstacles.
+ */
+export declare function estimateWirelessCoverage(accessPointPosition: Point2D, txPower: number, band: '2.4ghz' | '5ghz' | '6ghz', _walls: Array<{
+    start: Point2D;
+    end: Point2D;
+    thickness: number;
+}>, boundaryThreshold?: number): WirelessCoverage;
+/**
+ * Generate SVG path for a connection with waypoints.
+ */
+export declare function connectionToSVGPath(startPos: Point2D, endPos: Point2D, waypoints: Point2D[], curved?: boolean): string;
+/**
+ * Generate gradient ID for signal strength visualization.
+ */
+export declare function getSignalGradientId(signalStrength: number): string;
+/**
+ * Calculate connection statistics for a device.
+ */
+export declare function getDeviceConnectionStats(deviceId: string, connections: TopologyConnection[]): {
+    totalConnections: number;
+    activeConnections: number;
+    totalBandwidth: number;
+    averageLatency: number;
+};
+//# sourceMappingURL=index.d.ts.map