clayspace 0.1.1__py3-none-any.whl

clayspace/__init__.py

@@ -0,0 +1,14 @@
+from .cell import inspect_cell, load_cell, new_box_cell, save_cell, validate_cell
+from .model import add_box, add_cylinder, add_plane, add_prism, add_sphere, move_geometry, recompute_bounds, remove_geometry
+from .placement import make_placement, validate_placement
+from .preview import preview_cell, preview_world
+from .resources import manifest, schema
+from .world import inspect_world_snapshot, load_world_snapshot, new_world, place_cell, save_world_snapshot, validate_world_snapshot
+
+__version__ = "0.1.1"
+__all__ = [
+    "inspect_cell","load_cell","new_box_cell","save_cell","validate_cell",
+    "add_box","add_cylinder","add_plane","add_prism","add_sphere","move_geometry","recompute_bounds","remove_geometry",
+    "make_placement","validate_placement","preview_cell","preview_world","manifest","schema",
+    "inspect_world_snapshot","load_world_snapshot","new_world","place_cell","save_world_snapshot","validate_world_snapshot",
+]

clayspace/cell.py

@@ -0,0 +1,232 @@
+"""Standalone local Cell ownership: creation, validation, inspection and safe I/O.
+
+ClaySpace Cells are host-agnostic local geometry. Host projects may attach their
+own workflow metadata, but ClaySpace itself does not define canon, acceptance,
+publication, identity or ledger policy.
+"""
+from __future__ import annotations
+import json
+from copy import deepcopy
+from math import isfinite
+from pathlib import Path, PurePosixPath
+from typing import Any
+from zipfile import ZipFile, is_zipfile
+
+MAX_CELL_BYTES = 16 * 1024 * 1024
+
+
+def _finite(v: Any) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool) and isfinite(v)
+
+
+def _vector(v: Any, n: int = 3) -> bool:
+    return isinstance(v, (list, tuple)) and len(v) == n and all(_finite(x) for x in v)
+
+
+def _text(v: Any) -> bool:
+    return isinstance(v, str) and bool(v.strip())
+
+
+def _object(v: Any) -> dict:
+    return v if isinstance(v, dict) else {}
+
+
+def _absent(v: Any) -> bool:
+    return v is None or v == 'none'
+
+
+def load_cell(path: str | Path) -> dict:
+    """Load JSON or the sole cell.json in a ZIP, without extracting/running files."""
+    path = Path(path)
+    if is_zipfile(path):
+        with ZipFile(path) as archive:
+            candidates = []
+            for item in archive.infolist():
+                parts = PurePosixPath(item.filename)
+                if parts.name != 'cell.json' or item.is_dir():
+                    continue
+                if parts.is_absolute() or '..' in parts.parts or '\\' in item.filename:
+                    raise ValueError('unsafe cell.json archive path')
+                if item.file_size > MAX_CELL_BYTES:
+                    raise ValueError('cell.json exceeds size limit')
+                candidates.append(item)
+            if len(candidates) != 1:
+                raise ValueError('archive must contain exactly one cell.json')
+            raw = archive.read(candidates[0])
+    else:
+        if path.stat().st_size > MAX_CELL_BYTES:
+            raise ValueError('cell.json exceeds size limit')
+        raw = path.read_bytes()
+    value = json.loads(raw.decode('utf-8'))
+    if not isinstance(value, dict):
+        raise ValueError('cell.json must contain an object')
+    return value
+
+
+def save_cell(cell: dict, path: str | Path, *, overwrite: bool = False) -> Path:
+    check = validate_cell(cell)
+    if not check['valid']:
+        raise ValueError('invalid Cell: ' + '; '.join(check['errors']))
+    path = Path(path)
+    mode = 'w' if overwrite else 'x'
+    with path.open(mode, encoding='utf-8') as stream:
+        json.dump(cell, stream, indent=2, ensure_ascii=False, allow_nan=False)
+        stream.write('\n')
+    return path
+
+
+def validate_cell(cell: Any) -> dict:
+    """Validate either supported local Cell family; malformed data fails closed."""
+    base = dict(valid=False, errors=[], schemaFamily=None, schemaVersion=None,
+                cellId=None, objectCount=0, bounds=None, stage=None, notCanon=None)
+    if not isinstance(cell, dict):
+        base['errors'] = ['Cell must be an object']
+        return base
+    errors: list[str] = []
+    v1 = cell.get('schema') == 'clayspace.cell.local-fragment' and cell.get('schemaVersion') == '1.0.0'
+    legacy = cell.get('schemaVersion') == '0.1'
+    if not (v1 or legacy):
+        base.update(schemaFamily=cell.get('schema'), schemaVersion=cell.get('schemaVersion'),
+                    errors=['unsupported Cell format'])
+        return base
+    identity = _object(cell.get('identity'))
+    cell_id = identity.get('cellId') if v1 else cell.get('id')
+    if not _text(cell_id):
+        errors.append('Cell ID must be a non-empty string')
+
+    # A Cell is local. Workflow metadata may exist for a host project, but a
+    # baked master-world transform is never part of the portable source Cell.
+    if not _absent(cell.get('placement')):
+        errors.append('source Cell must remain locally unplaced')
+    for field in ('worldTransform', 'masterWorldCoordinates'):
+        if cell.get(field) is not None:
+            errors.append(f'source Cell must not contain {field}')
+    for container in ('portability', 'handoff'):
+        value = cell.get(container)
+        if value is not None and not isinstance(value, dict):
+            errors.append(f'{container} must be an object')
+        flags = _object(value)
+        if not _absent(flags.get('placement')):
+            errors.append(f'{container}.placement must remain none')
+        if flags.get('containsWorldTransform') is True:
+            errors.append(f'{container} declares a world transform')
+        if flags.get('masterWorldCoordinates') not in (None, False):
+            errors.append(f'{container} declares master-world coordinates')
+
+    if v1:
+        cs = _object(cell.get('coordinateSystem'))
+        axes = cs.get('axes')
+        if not isinstance(axes, str) or not all(t in axes.lower() for t in ('x-right', 'y-up', 'z-forward')):
+            errors.append('axes must describe x-right / y-up / z-forward')
+        origin, units = cs.get('localOrigin'), cs.get('units')
+    else:
+        cs = cell.get('coordinateSystem')
+        if cs != 'x-right-y-up-z-forward-meters':
+            errors.append('unsupported coordinateSystem')
+        origin, units = cell.get('origin'), cell.get('units')
+    if not _vector(origin) or any(x != 0 for x in origin):
+        errors.append('local origin must be [0,0,0]')
+    if units != 'meters':
+        errors.append('units must be meters')
+
+    geometry = cell.get('geometry' if v1 else 'objects')
+    if not isinstance(geometry, list) or not geometry:
+        errors.append('Cell geometry must be a non-empty array')
+        geometry = []
+    ids = set()
+    for index, item in enumerate(geometry):
+        label = f'geometry[{index}]'
+        if not isinstance(item, dict):
+            errors.append(f'{label} must be an object')
+            continue
+        item_id = item.get('id')
+        if not _text(item_id):
+            errors.append(f'{label} requires a string ID')
+        elif item_id in ids:
+            errors.append(f'duplicate geometry ID {item_id}')
+        else:
+            ids.add(item_id)
+        if v1:
+            primitive = item.get('primitive')
+            if primitive not in ('box', 'prism', 'cylinder', 'sphere', 'plane'):
+                errors.append(f'{label} unsupported primitive')
+            if not _vector(item.get('position')):
+                errors.append(f'{label} invalid position')
+            if not _vector(item.get('rotationDeg', [0, 0, 0])):
+                errors.append(f'{label} invalid rotationDeg')
+            scale = item.get('scale', [1, 1, 1])
+            if not _vector(scale) or any(v <= 0 for v in scale):
+                errors.append(f'{label} invalid scale')
+            if primitive == 'box':
+                size = item.get('size')
+                if not _vector(size) or any(v <= 0 for v in size):
+                    errors.append(f'{label} invalid size')
+            elif primitive == 'prism':
+                footprint = item.get('footprintXZ')
+                if not isinstance(footprint, list) or len(footprint) < 3 or not all(_vector(p, 2) for p in footprint):
+                    errors.append(f'{label} invalid footprintXZ')
+                y0, y1 = item.get('y0'), item.get('y1')
+                if not _finite(y0) or not _finite(y1) or y1 <= y0:
+                    errors.append(f'{label} invalid prism height')
+            elif primitive == 'cylinder':
+                if not _finite(item.get('radius')) or item.get('radius', 0) <= 0:
+                    errors.append(f'{label} invalid radius')
+                if not _finite(item.get('height')) or item.get('height', 0) <= 0:
+                    errors.append(f'{label} invalid height')
+                if 'segments' in item and (not isinstance(item['segments'], int) or item['segments'] < 3 or item['segments'] > 256):
+                    errors.append(f'{label} segments must be an integer from 3 to 256')
+            elif primitive == 'sphere':
+                if not _finite(item.get('radius')) or item.get('radius', 0) <= 0:
+                    errors.append(f'{label} invalid radius')
+            elif primitive == 'plane':
+                size = item.get('size')
+                if not _vector(size, 2) or any(v <= 0 for v in size):
+                    errors.append(f'{label} invalid plane size')
+        else:
+            if item.get('kind') not in ('box', 'card', 'road-strip'):
+                errors.append(f'{label} unsupported kind')
+            g = _object(item.get('geometry'))
+            if not all(_finite(g.get(k)) for k in ('x','y','z')):
+                errors.append(f'{label} invalid xyz')
+            if not all(_finite(g.get(k)) and g[k] > 0 for k in ('w','h','d')):
+                errors.append(f'{label} invalid dimensions')
+            for field in ('yaw','pitch','roll'):
+                if field in g and not _finite(g[field]):
+                    errors.append(f'{label} invalid {field}')
+
+    if v1 and 'bounds' in cell and cell.get('bounds') is not None and not isinstance(cell.get('bounds'), dict):
+        errors.append('bounds must be an object')
+    aabb = _object(cell.get('bounds')).get('aabb') if v1 else None
+    if v1 and aabb is not None:
+        b = _object(aabb)
+        if not _vector(b.get('min')) or not _vector(b.get('max')):
+            errors.append('bounds.aabb requires finite min/max vectors')
+        elif any(hi <= lo for lo, hi in zip(b['min'], b['max'])):
+            errors.append('bounds.aabb must have positive dimensions')
+
+    base.update(valid=not errors, errors=errors,
+                schemaFamily='clayspace.cell.local-fragment' if v1 else 'clayspace-cell',
+                schemaVersion=cell.get('schemaVersion'), cellId=cell_id,
+                objectCount=len(geometry), bounds=deepcopy(aabb),
+                stage=cell.get('stage'), notCanon=cell.get('notCanon'))
+    return base
+
+
+def inspect_cell(cell: dict) -> dict:
+    result = validate_cell(cell)
+    return {**result, 'placementStatus': 'local' if result['valid'] else None}
+
+
+def new_box_cell(*, cell_id: str, name: str, size=(2.0, 2.0, 2.0)) -> dict:
+    """Create a generic ground-centred editable local Cell scaffold."""
+    if not _text(cell_id) or not _text(name) or not _vector(size) or any(v <= 0 for v in size):
+        raise ValueError('Cell needs a non-empty ID/name and three positive dimensions')
+    w, h, d = size
+    return {
+        'schema': 'clayspace.cell.local-fragment', 'schemaVersion': '1.0.0',
+        'identity': {'cellId': cell_id, 'title': name},
+        'coordinateSystem': {'axes': 'x-right / y-up / z-forward', 'units': 'meters', 'localOrigin': [0,0,0]},
+        'bounds': {'aabb': {'min': [-w/2,0,-d/2], 'max': [w/2,h,d/2]}},
+        'geometry': [{'id': 'MASS-001', 'primitive': 'box', 'position': [0,h/2,0], 'size': [w,h,d], 'rotationDeg': [0,0,0], 'scale': [1,1,1]}],
+        'portability': {'containsWorldTransform': False, 'placement': 'none'}
+    }

clayspace/cli.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+import argparse, json
+from pathlib import Path
+from .cell import inspect_cell, load_cell, new_box_cell, save_cell, validate_cell
+from .model import add_box, add_cylinder, add_sphere, move_geometry, remove_geometry
+from .placement import make_placement
+from .preview import preview_cell, preview_world
+from .resources import manifest, schema
+from .world import inspect_world_snapshot, load_world_snapshot, new_world, place_cell, save_world_snapshot, validate_world_snapshot
+
+
+def _print(obj): print(json.dumps(obj,indent=2,ensure_ascii=False))
+def _vec(text,n=3):
+    parts=[p.strip() for p in text.split(',')]
+    if len(parts)!=n: raise argparse.ArgumentTypeError(f'expected {n} comma-separated numbers')
+    try:return [float(p) for p in parts]
+    except ValueError as exc: raise argparse.ArgumentTypeError('values must be numbers') from exc
+
+def _vec3(text): return _vec(text,3)
+def _write_cell(cell,path,force): save_cell(cell,path,overwrite=force)
+def _write_world(world,path,force): save_world_snapshot(world,path,overwrite=force)
+
+
+def main(argv=None):
+    parser=argparse.ArgumentParser(prog='clayspace',description='Standalone local spatial modeling toolkit')
+    sub=parser.add_subparsers(dest='cmd',required=True)
+    sub.add_parser('about')
+    ps=sub.add_parser('schema');ps.add_argument('name',choices=['cell','placement','world'])
+
+    pc=sub.add_parser('cell');cs=pc.add_subparsers(dest='cell_cmd',required=True)
+    p=cs.add_parser('init');p.add_argument('--id',required=True);p.add_argument('--name',required=True);p.add_argument('--size',type=_vec3,default=[2,2,2]);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    for name in ('validate','inspect'):
+        p=cs.add_parser(name);p.add_argument('path')
+    p=cs.add_parser('add-box');p.add_argument('path');p.add_argument('--id',required=True);p.add_argument('--position',type=_vec3,default=[0,0,0]);p.add_argument('--size',type=_vec3,required=True);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=cs.add_parser('add-cylinder');p.add_argument('path');p.add_argument('--id',required=True);p.add_argument('--position',type=_vec3,default=[0,0,0]);p.add_argument('--radius',type=float,required=True);p.add_argument('--height',type=float,required=True);p.add_argument('--segments',type=int,default=24);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=cs.add_parser('add-sphere');p.add_argument('path');p.add_argument('--id',required=True);p.add_argument('--position',type=_vec3,default=[0,0,0]);p.add_argument('--radius',type=float,required=True);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=cs.add_parser('move');p.add_argument('path');p.add_argument('--id',required=True);p.add_argument('--position',type=_vec3,required=True);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=cs.add_parser('remove');p.add_argument('path');p.add_argument('--id',required=True);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=cs.add_parser('preview');p.add_argument('path');p.add_argument('--out',required=True)
+
+    pp=sub.add_parser('placement');pps=pp.add_subparsers(dest='placement_cmd',required=True)
+    p=pps.add_parser('make');p.add_argument('cell_path');p.add_argument('--position',required=True,type=_vec3);p.add_argument('--yaw-radians',type=float,default=0);p.add_argument('--scale',type=float,default=1);p.add_argument('--id');p.add_argument('--out')
+
+    pw=sub.add_parser('world');ws=pw.add_subparsers(dest='world_cmd',required=True)
+    p=ws.add_parser('init');p.add_argument('--id',required=True);p.add_argument('--name');p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=ws.add_parser('place');p.add_argument('world_path');p.add_argument('--cell',required=True);p.add_argument('--entity-id',required=True);p.add_argument('--position',type=_vec3,required=True);p.add_argument('--yaw-radians',type=float,default=0);p.add_argument('--scale',type=float,default=1);p.add_argument('--name');p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    for name in ('validate','inspect'):
+        p=ws.add_parser(name);p.add_argument('path')
+    p=ws.add_parser('preview');p.add_argument('path');p.add_argument('--out',required=True)
+
+    args=parser.parse_args(argv)
+    if args.cmd=='about':_print(manifest());return 0
+    if args.cmd=='schema':_print(schema(args.name));return 0
+    if args.cmd=='cell':
+        if args.cell_cmd=='init':
+            _write_cell(new_box_cell(cell_id=args.id,name=args.name,size=args.size),args.out,args.force);return 0
+        cell=load_cell(args.path)
+        if args.cell_cmd=='validate':
+            r=validate_cell(cell);_print(r);return 0 if r['valid'] else 1
+        if args.cell_cmd=='inspect':
+            r=inspect_cell(cell);_print(r);return 0 if r['valid'] else 1
+        if args.cell_cmd=='add-box':out=add_box(cell,object_id=args.id,position=args.position,size=args.size)
+        elif args.cell_cmd=='add-cylinder':out=add_cylinder(cell,object_id=args.id,position=args.position,radius=args.radius,height=args.height,segments=args.segments)
+        elif args.cell_cmd=='add-sphere':out=add_sphere(cell,object_id=args.id,position=args.position,radius=args.radius)
+        elif args.cell_cmd=='move':out=move_geometry(cell,object_id=args.id,position=args.position)
+        elif args.cell_cmd=='remove':out=remove_geometry(cell,object_id=args.id)
+        elif args.cell_cmd=='preview':preview_cell(cell,args.out);return 0
+        else:return 2
+        _write_cell(out,args.out,args.force);return 0
+    if args.cmd=='placement' and args.placement_cmd=='make':
+        obj=make_placement(load_cell(args.cell_path),position=args.position,yaw_radians=args.yaw_radians,scale=args.scale,placement_id=args.id)
+        text=json.dumps(obj,indent=2,ensure_ascii=False)+'\n'
+        Path(args.out).write_text(text,encoding='utf-8') if args.out else print(text,end='')
+        return 0
+    if args.cmd=='world':
+        if args.world_cmd=='init':_write_world(new_world(world_id=args.id,label=args.name),args.out,args.force);return 0
+        world=load_world_snapshot(args.world_path if hasattr(args,'world_path') else args.path)
+        if args.world_cmd=='place':
+            out=place_cell(world,load_cell(args.cell),entity_id=args.entity_id,position=args.position,yaw_radians=args.yaw_radians,scale=args.scale,display_name=args.name)
+            _write_world(out,args.out,args.force);return 0
+        if args.world_cmd=='validate':r=validate_world_snapshot(world);_print(r);return 0 if r['valid'] else 1
+        if args.world_cmd=='inspect':r=inspect_world_snapshot(world);_print(r);return 0 if r['valid'] else 1
+        if args.world_cmd=='preview':preview_world(world,args.out);return 0
+    return 2
+
+if __name__=='__main__':raise SystemExit(main())

clayspace/data/cell-local-fragment-1.0.0.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clayspace.invalid/schema/cell-local-fragment-1.0.0.json",
+  "title": "ClaySpace Local Fragment Cell 1.0.0",
+  "type": "object",
+  "required": ["schema", "schemaVersion", "identity", "coordinateSystem", "geometry"],
+  "properties": {
+    "schema": {"const": "clayspace.cell.local-fragment"},
+    "schemaVersion": {"const": "1.0.0"},
+    "identity": {"type": "object", "required": ["cellId"]},
+    "coordinateSystem": {"type": "object"},
+    "placement": {"enum": ["none", null]},
+    "masterWorldCoordinates": {"type": "null"},
+    "worldTransform": {"type": "null"},
+    "geometry": {"type": "array", "minItems": 1}
+  },
+  "additionalProperties": true
+}

clayspace/data/manifest.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": "0.1.0",
+  "id": "clayspace",
+  "name": "ClaySpace",
+  "role": "standalone local spatial modeling toolkit for portable Cells and worlds",
+  "status": "preview",
+  "coordinateConvention": "x-right / y-up / z-forward / meters",
+  "principles": {
+    "worksWithoutAccountsOrServices": true,
+    "localCellsArePortable": true,
+    "sourceCellsStayLocal": true,
+    "placementIsSeparate": true,
+    "hostProtocolsStayExternal": true,
+    "hostPolicyIsNotClaySpacePolicy": true
+  },
+  "mandatoryDependencies": [],
+  "packageVersion": "0.1.1",
+  "capabilities": {
+    "cellCreation": true,
+    "primitiveModeling": ["box", "prism", "cylinder", "sphere", "plane"],
+    "cellValidation": true,
+    "safeCellZipLoading": true,
+    "worldComposition": true,
+    "placementTransforms": true,
+    "selfContainedHtmlPreview": true,
+    "interactive3dEditor": false,
+    "hostSpecificPolicy": false
+  },
+  "provenance": {
+    "flyWithMe": {
+      "project": "Fly With Me",
+      "author": "Kun Chen",
+      "url": "https://github.com/kunchenguid/fly-with-me",
+      "license": "MIT",
+      "noticeFile": "licenses/FLY_WITH_ME_MIT.txt"
+    }
+  }
+}

clayspace/data/placement-0.1.0.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clayspace.invalid/schema/placement-0.1.0.json",
+  "title": "ClaySpace Placement 0.1.0",
+  "type": "object",
+  "required": ["schema", "schemaVersion", "placementId", "cellId", "position", "yawRadians", "scale"],
+  "properties": {
+    "schema": {"const": "clayspace.placement"},
+    "schemaVersion": {"const": "0.1.0"},
+    "placementId": {"type": "string"},
+    "cellId": {"type": "string"},
+    "position": {"type": "array", "minItems": 3, "maxItems": 3, "items": {"type": "number"}},
+    "yawRadians": {"type": "number"},
+    "scale": {"type": "number", "exclusiveMinimum": 0}
+  },
+  "additionalProperties": true
+}

clayspace/data/world-snapshot-0.1.0.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clayspace.invalid/schema/world-snapshot-0.1.0.json",
+  "title": "ClaySpace World Snapshot 0.1.0",
+  "type": "object",
+  "required": ["schema", "schemaVersion", "worldId", "entities"],
+  "properties": {
+    "schema": {"const": "clayspace.world.snapshot"},
+    "schemaVersion": {"const": "0.1.0"},
+    "worldId": {"type": "string"},
+    "label": {"type": "string"},
+    "entities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["entityId"],
+        "properties": {
+          "entityId": {"type": "string"},
+          "kind": {"type": "string"},
+          "displayName": {"type": "string"},
+          "placement": {
+            "type": ["object", "null"],
+            "properties": {
+              "position": {"type": "array", "minItems": 3, "maxItems": 3, "items": {"type": "number"}},
+              "yawRadians": {"type": "number"},
+              "scale": {"type": "number", "exclusiveMinimum": 0}
+            },
+            "required": ["position", "yawRadians", "scale"],
+            "additionalProperties": true
+          },
+          "payload": {"type": "object"}
+        },
+        "additionalProperties": true
+      }
+    },
+    "metadata": {"type": "object"}
+  },
+  "additionalProperties": true
+}

clayspace/model.py

@@ -0,0 +1,141 @@
+"""Pure-data modeling operations for ClaySpace Cells."""
+from __future__ import annotations
+from copy import deepcopy
+from math import cos, radians, sin
+from .cell import validate_cell
+
+
+def _require_v1(cell: dict) -> dict:
+    check = validate_cell(cell)
+    if not check['valid']:
+        raise ValueError('invalid Cell: ' + '; '.join(check['errors']))
+    if check['schemaFamily'] != 'clayspace.cell.local-fragment':
+        raise ValueError('editing requires clayspace.cell.local-fragment 1.0.0')
+    return deepcopy(cell)
+
+
+def _ensure_unique(cell: dict, object_id: str) -> None:
+    if not isinstance(object_id, str) or not object_id.strip():
+        raise ValueError('object_id must be a non-empty string')
+    if any(g.get('id') == object_id for g in cell['geometry'] if isinstance(g, dict)):
+        raise ValueError(f'duplicate geometry ID {object_id}')
+
+
+def _vec3(value, name: str, positive: bool = False):
+    if not isinstance(value, (list, tuple)) or len(value) != 3:
+        raise ValueError(f'{name} must contain three numbers')
+    result = [float(x) for x in value]
+    if positive and any(x <= 0 for x in result):
+        raise ValueError(f'{name} values must be > 0')
+    return result
+
+
+def _vec2(value, name: str, positive: bool = False):
+    if not isinstance(value, (list, tuple)) or len(value) != 2:
+        raise ValueError(f'{name} must contain two numbers')
+    result = [float(x) for x in value]
+    if positive and any(x <= 0 for x in result):
+        raise ValueError(f'{name} values must be > 0')
+    return result
+
+
+def add_box(cell: dict, *, object_id: str, position=(0,0,0), size=(1,1,1), rotation_deg=(0,0,0), scale=(1,1,1)) -> dict:
+    out = _require_v1(cell); _ensure_unique(out, object_id)
+    out['geometry'].append({'id': object_id, 'primitive': 'box', 'position': _vec3(position,'position'), 'size': _vec3(size,'size',True), 'rotationDeg': _vec3(rotation_deg,'rotation_deg'), 'scale': _vec3(scale,'scale',True)})
+    return recompute_bounds(out)
+
+
+def add_cylinder(cell: dict, *, object_id: str, position=(0,0,0), radius=1.0, height=2.0, rotation_deg=(0,0,0), scale=(1,1,1), segments=24) -> dict:
+    out = _require_v1(cell); _ensure_unique(out, object_id)
+    radius=float(radius);height=float(height);segments=int(segments)
+    if radius<=0 or height<=0 or not 3<=segments<=256: raise ValueError('radius/height must be >0 and segments 3..256')
+    out['geometry'].append({'id':object_id,'primitive':'cylinder','position':_vec3(position,'position'),'radius':radius,'height':height,'segments':segments,'rotationDeg':_vec3(rotation_deg,'rotation_deg'),'scale':_vec3(scale,'scale',True)})
+    return recompute_bounds(out)
+
+
+def add_sphere(cell: dict, *, object_id: str, position=(0,0,0), radius=1.0, scale=(1,1,1)) -> dict:
+    out = _require_v1(cell); _ensure_unique(out, object_id)
+    radius=float(radius)
+    if radius<=0: raise ValueError('radius must be > 0')
+    out['geometry'].append({'id':object_id,'primitive':'sphere','position':_vec3(position,'position'),'radius':radius,'rotationDeg':[0,0,0],'scale':_vec3(scale,'scale',True)})
+    return recompute_bounds(out)
+
+
+def add_plane(cell: dict, *, object_id: str, position=(0,0,0), size=(1,1), rotation_deg=(0,0,0), scale=(1,1,1)) -> dict:
+    out = _require_v1(cell); _ensure_unique(out, object_id)
+    out['geometry'].append({'id':object_id,'primitive':'plane','position':_vec3(position,'position'),'size':_vec2(size,'size',True),'rotationDeg':_vec3(rotation_deg,'rotation_deg'),'scale':_vec3(scale,'scale',True)})
+    return recompute_bounds(out)
+
+
+def add_prism(cell: dict, *, object_id: str, footprint_xz, y0=0.0, y1=1.0, position=(0,0,0), rotation_deg=(0,0,0), scale=(1,1,1)) -> dict:
+    out = _require_v1(cell); _ensure_unique(out, object_id)
+    points=[_vec2(p,'footprint point') for p in footprint_xz]
+    if len(points)<3: raise ValueError('footprint needs at least three points')
+    y0=float(y0);y1=float(y1)
+    if y1<=y0: raise ValueError('y1 must be greater than y0')
+    out['geometry'].append({'id':object_id,'primitive':'prism','position':_vec3(position,'position'),'footprintXZ':points,'y0':y0,'y1':y1,'rotationDeg':_vec3(rotation_deg,'rotation_deg'),'scale':_vec3(scale,'scale',True)})
+    return recompute_bounds(out)
+
+
+def move_geometry(cell: dict, *, object_id: str, position) -> dict:
+    out=_require_v1(cell)
+    for item in out['geometry']:
+        if item.get('id')==object_id:
+            item['position']=_vec3(position,'position')
+            return recompute_bounds(out)
+    raise KeyError(object_id)
+
+
+def remove_geometry(cell: dict, *, object_id: str) -> dict:
+    out=_require_v1(cell)
+    kept=[g for g in out['geometry'] if g.get('id')!=object_id]
+    if len(kept)==len(out['geometry']): raise KeyError(object_id)
+    if not kept: raise ValueError('a Cell must retain at least one geometry item')
+    out['geometry']=kept
+    return recompute_bounds(out)
+
+
+def _rotate_y(x,z,yaw_deg):
+    a=radians(yaw_deg);c=cos(a);s=sin(a)
+    return x*c-z*s, x*s+z*c
+
+
+def _item_bounds(item: dict):
+    px,py,pz=item.get('position',[0,0,0]); sx,sy,sz=item.get('scale',[1,1,1]); yaw=item.get('rotationDeg',[0,0,0])[1]
+    primitive=item.get('primitive')
+    points=[]
+    if primitive=='box':
+        w,h,d=item['size']; w*=sx;h*=sy;d*=sz
+        for x in (-w/2,w/2):
+            for y in (-h/2,h/2):
+                for z in (-d/2,d/2):
+                    rx,rz=_rotate_y(x,z,yaw);points.append((px+rx,py+y,pz+rz))
+    elif primitive=='sphere':
+        r=item['radius']; rx=r*sx;ry=r*sy;rz=r*sz
+        points=[(px-rx,py-ry,pz-rz),(px+rx,py+ry,pz+rz)]
+    elif primitive=='cylinder':
+        r=item['radius']; h=item['height']; rr=r*max(sx,sz)
+        points=[(px-rr,py-h*sy/2,pz-rr),(px+rr,py+h*sy/2,pz+rr)]
+    elif primitive=='plane':
+        w,h=item['size'];w*=sx;h*=sy
+        for x in (-w/2,w/2):
+            for y in (-h/2,h/2):
+                rx,rz=_rotate_y(x,0,yaw);points.append((px+rx,py+y,pz+rz))
+    elif primitive=='prism':
+        for x,z in item['footprintXZ']:
+            x*=sx;z*=sz;rx,rz=_rotate_y(x,z,yaw)
+            points.extend([(px+rx,py+item['y0']*sy,pz+rz),(px+rx,py+item['y1']*sy,pz+rz)])
+    return points
+
+
+def recompute_bounds(cell: dict) -> dict:
+    out=deepcopy(cell)
+    points=[]
+    for item in out.get('geometry',[]): points.extend(_item_bounds(item))
+    if not points: raise ValueError('Cell has no bounded geometry')
+    mins=[min(p[i] for p in points) for i in range(3)]; maxs=[max(p[i] for p in points) for i in range(3)]
+    # ensure nonzero bounds for planar-only Cells
+    for i in range(3):
+        if maxs[i] <= mins[i]: mins[i]-=0.0005;maxs[i]+=0.0005
+    out['bounds']={'aabb':{'min':mins,'max':maxs}}
+    return out

clayspace/placement.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+from math import isfinite
+from uuid import uuid4
+from .cell import inspect_cell
+
+
+def _finite3(value) -> bool:
+    return isinstance(value, (list, tuple)) and len(value) == 3 and all(isinstance(v, (int, float)) and not isinstance(v, bool) and isfinite(v) for v in value)
+
+
+def validate_placement(placement: dict) -> dict:
+    errors: list[str] = []
+    if not isinstance(placement, dict):
+        return {"valid": False, "errors": ["placement must be an object"]}
+    if placement.get("schema") != "clayspace.placement" or placement.get("schemaVersion") != "0.1.0":
+        errors.append("unsupported placement schema")
+    for key in ("placementId", "cellId"):
+        if not placement.get(key): errors.append(f"missing {key}")
+    if not _finite3(placement.get("position")): errors.append("position must be a finite xyz vector")
+    yaw = placement.get("yawRadians")
+    if not isinstance(yaw, (int, float)) or isinstance(yaw, bool) or not isfinite(yaw): errors.append("yawRadians must be finite")
+    scale = placement.get("scale")
+    if not isinstance(scale, (int, float)) or isinstance(scale, bool) or not isfinite(scale) or scale <= 0: errors.append("scale must be > 0")
+    return {"valid": not errors, "errors": errors}
+
+
+def make_placement(cell: dict, *, position, yaw_radians: float = 0.0, scale: float = 1.0, placement_id: str | None = None) -> dict:
+    info = inspect_cell(cell)
+    if not info["valid"]: raise ValueError("invalid Cell: " + "; ".join(info["errors"]))
+    placement = {
+        "schema": "clayspace.placement", "schemaVersion": "0.1.0",
+        "placementId": placement_id or f"clayspace:placement:{uuid4().hex}",
+        "cellId": info["cellId"], "position": list(position),
+        "yawRadians": yaw_radians, "scale": scale,
+    }
+    check = validate_placement(placement)
+    if not check["valid"]: raise ValueError("invalid placement: " + "; ".join(check["errors"]))
+    return placement

clayspace/preview.py

@@ -0,0 +1,78 @@
+"""Dependency-free self-contained HTML previews for Cells and worlds."""
+from __future__ import annotations
+import html
+import json
+from pathlib import Path
+from .cell import validate_cell
+from .world import validate_world_snapshot
+
+
+def _write(title: str, model: dict, out: str | Path) -> Path:
+    out=Path(out)
+    data=json.dumps(model,ensure_ascii=False,separators=(',',':')).replace('</','<\\/')
+    safe_title=html.escape(title)
+    page=f'''<!doctype html>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>{safe_title} — ClaySpace</title>
+<style>
+html,body{{margin:0;height:100%;background:#111;color:#eee;font:14px system-ui,sans-serif;overflow:hidden}}
+canvas{{display:block;width:100%;height:100%;cursor:grab}}canvas:active{{cursor:grabbing}}
+#hud{{position:fixed;left:14px;top:12px;background:#111c;padding:10px 12px;border:1px solid #ffffff22;border-radius:8px;backdrop-filter:blur(6px);max-width:min(520px,calc(100vw - 40px))}}
+#hud b{{font-size:15px}}#hud small{{display:block;color:#aaa;margin-top:4px;line-height:1.35}}
+button{{margin-top:8px;background:#222;color:#eee;border:1px solid #555;border-radius:5px;padding:5px 8px}}
+</style>
+<canvas id="c"></canvas><div id="hud"><b>{safe_title}</b><small>Drag to orbit · wheel to zoom · double-click to reset<br>Self-contained ClaySpace preview — no network required.</small><button id="reset">Reset view</button></div>
+<script>
+const MODEL={data};
+const canvas=document.getElementById('c'),ctx=canvas.getContext('2d');
+let yaw=.7,pitch=-.45,zoom=1,drag=false,lx=0,ly=0;
+function resize(){{const d=devicePixelRatio||1;canvas.width=innerWidth*d;canvas.height=innerHeight*d;ctx.setTransform(d,0,0,d,0,0);draw();}}
+addEventListener('resize',resize);
+canvas.onpointerdown=e=>{{drag=true;lx=e.clientX;ly=e.clientY;canvas.setPointerCapture(e.pointerId)}};
+canvas.onpointerup=()=>drag=false;canvas.onpointermove=e=>{{if(!drag)return;yaw+=(e.clientX-lx)*.008;pitch=Math.max(-1.45,Math.min(1.45,pitch+(e.clientY-ly)*.008));lx=e.clientX;ly=e.clientY;draw()}};
+canvas.onwheel=e=>{{e.preventDefault();zoom*=Math.exp(-e.deltaY*.001);zoom=Math.max(.1,Math.min(10,zoom));draw()}};canvas.ondblclick=reset;document.getElementById('reset').onclick=reset;
+function reset(){{yaw=.7;pitch=-.45;zoom=1;draw()}}
+function rotY(p,a){{let c=Math.cos(a),s=Math.sin(a);return [p[0]*c-p[2]*s,p[1],p[0]*s+p[2]*c]}}
+function rotX(p,a){{let c=Math.cos(a),s=Math.sin(a);return [p[0],p[1]*c-p[2]*s,p[1]*s+p[2]*c]}}
+function rotZ(p,a){{let c=Math.cos(a),s=Math.sin(a);return [p[0]*c-p[1]*s,p[0]*s+p[1]*c,p[2]]}}
+function applyLocal(p,shape){{let s=shape.scale||[1,1,1],r=shape.rotationDeg||[0,0,0],q=[p[0]*s[0],p[1]*s[1],p[2]*s[2]];q=rotX(q,r[0]*Math.PI/180);q=rotY(q,r[1]*Math.PI/180);q=rotZ(q,r[2]*Math.PI/180);let pos=shape.position||[0,0,0];return [q[0]+pos[0],q[1]+pos[1],q[2]+pos[2]]}}
+function worldPoint(p,shape){{let q=applyLocal(p,shape),w=shape.world||null;if(w){{q=[q[0]*(w.scale||1),q[1]*(w.scale||1),q[2]*(w.scale||1)];q=rotY(q,w.yawRadians||0);let t=w.position||[0,0,0];q=[q[0]+t[0],q[1]+t[1],q[2]+t[2]]}}return q}}
+function geom(shape){{let v=[],e=[];const edge=(a,b)=>e.push([a,b]);if(shape.primitive==='box'){{let [w,h,d]=shape.size;for(let y of [-h/2,h/2])for(let z of [-d/2,d/2])for(let x of [-w/2,w/2])v.push([x,y,z]);[[0,1],[2,3],[4,5],[6,7],[0,2],[1,3],[4,6],[5,7],[0,4],[1,5],[2,6],[3,7]].forEach(x=>edge(...x));}}
+else if(shape.primitive==='sphere'){{let r=shape.radius,n=20;for(let ring=0;ring<3;ring++){{let base=v.length;for(let i=0;i<n;i++){{let a=i*2*Math.PI/n;if(ring===0)v.push([Math.cos(a)*r,Math.sin(a)*r,0]);if(ring===1)v.push([Math.cos(a)*r,0,Math.sin(a)*r]);if(ring===2)v.push([0,Math.cos(a)*r,Math.sin(a)*r]);}}for(let i=0;i<n;i++)edge(base+i,base+(i+1)%n);}}}}
+else if(shape.primitive==='cylinder'){{let r=shape.radius,h=shape.height,n=Math.max(6,Math.min(48,shape.segments||24));for(let y of [-h/2,h/2])for(let i=0;i<n;i++){{let a=i*2*Math.PI/n;v.push([Math.cos(a)*r,y,Math.sin(a)*r]);}}for(let i=0;i<n;i++){{edge(i,(i+1)%n);edge(n+i,n+(i+1)%n);if(i%(Math.ceil(n/8))===0)edge(i,n+i);}}}}
+else if(shape.primitive==='plane'){{let [w,h]=shape.size;v=[[-w/2,-h/2,0],[w/2,-h/2,0],[w/2,h/2,0],[-w/2,h/2,0]];[[0,1],[1,2],[2,3],[3,0]].forEach(x=>edge(...x));}}
+else if(shape.primitive==='prism'){{let f=shape.footprintXZ,n=f.length,y0=shape.y0,y1=shape.y1;for(let y of [y0,y1])for(let p of f)v.push([p[0],y,p[1]]);for(let i=0;i<n;i++){{edge(i,(i+1)%n);edge(n+i,n+(i+1)%n);edge(i,n+i);}}}}
+return {{v,e}};}}
+function collect(){{let pts=[];for(const s of MODEL.shapes){{let g=geom(s);for(const p of g.v)pts.push(worldPoint(p,s));}}return pts}}
+function bounds(pts){{if(!pts.length)return {{c:[0,0,0],r:10}};let mi=[Infinity,Infinity,Infinity],ma=[-Infinity,-Infinity,-Infinity];for(const p of pts)for(let i=0;i<3;i++){{mi[i]=Math.min(mi[i],p[i]);ma[i]=Math.max(ma[i],p[i]);}}let c=mi.map((x,i)=>(x+ma[i])/2),r=Math.max(...ma.map((x,i)=>x-mi[i]))||1;return {{c,r}}}}
+function project(p,b){{let q=[p[0]-b.c[0],p[1]-b.c[1],p[2]-b.c[2]];q=rotY(q,-yaw);q=rotX(q,-pitch);let dist=b.r*2.5/zoom,z=q[2]+dist,f=Math.max(10,Math.min(innerWidth,innerHeight))*.9;let k=f/Math.max(.2,z+b.r*1.2);return [innerWidth/2+q[0]*k,innerHeight/2-q[1]*k,q[2]]}}
+function grid(b){{ctx.strokeStyle='#ffffff10';ctx.lineWidth=1;let step=Math.max(1,Math.pow(10,Math.floor(Math.log10(b.r||1)))/2),n=12;for(let i=-n;i<=n;i++){{for(const pair of [[[i*step,0,-n*step],[i*step,0,n*step]],[[-n*step,0,i*step],[n*step,0,i*step]]]){{let a=project(pair[0],b),c=project(pair[1],b);ctx.beginPath();ctx.moveTo(a[0],a[1]);ctx.lineTo(c[0],c[1]);ctx.stroke();}}}}}}
+function draw(){{ctx.clearRect(0,0,innerWidth,innerHeight);let all=collect(),b=bounds(all);grid(b);let lines=[];for(const s of MODEL.shapes){{let g=geom(s),pv=g.v.map(p=>project(worldPoint(p,s),b));for(const [a,c] of g.e)lines.push([pv[a],pv[c],s]);}}lines.sort((a,c)=>(a[0][2]+a[1][2])-(c[0][2]+c[1][2]));for(const [a,c,s] of lines){{ctx.strokeStyle=s.stroke||'#a7d7ff';ctx.lineWidth=1.6;ctx.beginPath();ctx.moveTo(a[0],a[1]);ctx.lineTo(c[0],c[1]);ctx.stroke();}}}}
+resize();
+</script>'''
+    out.write_text(page,encoding='utf-8')
+    return out
+
+
+def preview_cell(cell: dict, out: str | Path) -> Path:
+    check=validate_cell(cell)
+    if not check['valid']: raise ValueError('invalid Cell: '+'; '.join(check['errors']))
+    if check['schemaFamily']!='clayspace.cell.local-fragment': raise ValueError('preview requires local-fragment Cell format')
+    title=(cell.get('identity') or {}).get('title') or check['cellId'] or 'ClaySpace Cell'
+    return _write(title,{'shapes':cell['geometry']},out)
+
+
+def preview_world(world: dict, out: str | Path) -> Path:
+    check=validate_world_snapshot(world)
+    if not check['valid']: raise ValueError('invalid world: '+'; '.join(check['errors']))
+    shapes=[]
+    for entity in world.get('entities',[]):
+        payload=entity.get('payload') or {};cell=payload.get('cell');placement=entity.get('placement')
+        if not isinstance(cell,dict) or not isinstance(placement,dict): continue
+        ci=validate_cell(cell)
+        if not ci['valid'] or ci['schemaFamily']!='clayspace.cell.local-fragment': continue
+        world_transform={'position':placement['position'],'yawRadians':placement['yawRadians'],'scale':placement['scale']}
+        for item in cell['geometry']:
+            shape=dict(item);shape['world']=world_transform;shapes.append(shape)
+    title=world.get('label') or world.get('worldId') or 'ClaySpace World'
+    return _write(title,{'shapes':shapes},out)

clayspace/resources.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+import json
+from importlib.resources import files
+
+
+def _load(name: str) -> dict:
+    return json.loads(files("clayspace.data").joinpath(name).read_text(encoding="utf-8"))
+
+
+def manifest() -> dict:
+    return _load("manifest.json")
+
+
+def schema(name: str) -> dict:
+    names = {
+        "cell": "cell-local-fragment-1.0.0.json",
+        "placement": "placement-0.1.0.json",
+        "world": "world-snapshot-0.1.0.json",
+    }
+    if name not in names:
+        raise KeyError(f"unknown schema {name!r}")
+    return _load(names[name])

clayspace/world.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+import json
+from copy import deepcopy
+from math import isfinite
+from pathlib import Path
+from typing import Any
+from .cell import inspect_cell, validate_cell
+
+
+def _finite(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value)
+
+
+def _finite3(value: Any) -> bool:
+    return isinstance(value, (list, tuple)) and len(value) == 3 and all(_finite(v) for v in value)
+
+
+def load_world_snapshot(path: str | Path) -> dict:
+    value=json.loads(Path(path).read_text(encoding='utf-8'))
+    if not isinstance(value,dict): raise ValueError('world snapshot must be an object')
+    return value
+
+
+def save_world_snapshot(world: dict, path: str | Path, *, overwrite: bool=False) -> Path:
+    check=validate_world_snapshot(world)
+    if not check['valid']: raise ValueError('invalid world: '+'; '.join(check['errors']))
+    path=Path(path);mode='w' if overwrite else 'x'
+    with path.open(mode,encoding='utf-8') as f: json.dump(world,f,indent=2,ensure_ascii=False,allow_nan=False);f.write('\n')
+    return path
+
+
+def new_world(*, world_id: str, label: str | None=None) -> dict:
+    if not isinstance(world_id,str) or not world_id.strip(): raise ValueError('world_id required')
+    return {'schema':'clayspace.world.snapshot','schemaVersion':'0.1.0','worldId':world_id,'label':label or world_id,'entities':[],'metadata':{}}
+
+
+def place_cell(world: dict, cell: dict, *, entity_id: str, position=(0,0,0), yaw_radians=0.0, scale=1.0, display_name: str | None=None, embed=True) -> dict:
+    if not validate_world_snapshot(world)['valid']: raise ValueError('invalid world')
+    info=inspect_cell(cell)
+    if not info['valid']: raise ValueError('invalid Cell: '+'; '.join(info['errors']))
+    if any(e.get('entityId')==entity_id for e in world['entities'] if isinstance(e,dict)): raise ValueError(f'duplicate entityId {entity_id}')
+    if not _finite3(position): raise ValueError('position must be xyz')
+    if not _finite(yaw_radians): raise ValueError('yaw_radians must be finite')
+    if not _finite(scale) or scale<=0: raise ValueError('scale must be > 0')
+    out=deepcopy(world)
+    payload={'cellId':info['cellId']}
+    if embed: payload['cell']=deepcopy(cell)
+    out['entities'].append({'entityId':entity_id,'kind':'clayspace-cell','displayName':display_name or info['cellId'],'placement':{'position':list(position),'yawRadians':float(yaw_radians),'scale':float(scale)},'payload':payload})
+    return out
+
+
+def validate_world_snapshot(snapshot: dict) -> dict:
+    errors: list[str] = []
+    if not isinstance(snapshot, dict): return {"valid": False, "errors": ["world snapshot must be an object"], "entityCount": 0}
+    if snapshot.get("schema") != "clayspace.world.snapshot" or snapshot.get("schemaVersion") != "0.1.0": errors.append("unsupported world snapshot schema")
+    if not snapshot.get("worldId"): errors.append("missing worldId")
+    entities = snapshot.get("entities")
+    if not isinstance(entities, list): errors.append("entities must be an array"); entities=[]
+    ids: set[str] = set()
+    for index, entity in enumerate(entities):
+        if not isinstance(entity, dict): errors.append(f"entity {index} must be an object"); continue
+        entity_id = entity.get("entityId")
+        if not entity_id: errors.append(f"entity {index} missing entityId")
+        elif entity_id in ids: errors.append(f"duplicate entityId {entity_id}")
+        else: ids.add(entity_id)
+        placement = entity.get("placement")
+        if placement is not None:
+            if not isinstance(placement, dict): errors.append(f"{entity_id or index} placement must be an object")
+            else:
+                if not _finite3(placement.get("position")): errors.append(f"{entity_id or index} placement.position must be a finite xyz vector")
+                if not _finite(placement.get("yawRadians")): errors.append(f"{entity_id or index} placement.yawRadians must be finite")
+                if not _finite(placement.get("scale")) or placement.get('scale',0)<=0: errors.append(f"{entity_id or index} placement.scale must be > 0")
+        payload=entity.get('payload')
+        if isinstance(payload,dict) and isinstance(payload.get('cell'),dict):
+            c=validate_cell(payload['cell'])
+            errors.extend(f"{entity_id or index} cell: {e}" for e in c['errors'])
+    return {"valid": not errors, "errors": errors, "entityCount": len(entities), "worldId": snapshot.get("worldId")}
+
+
+def inspect_world_snapshot(snapshot: dict) -> dict:
+    check=validate_world_snapshot(snapshot)
+    entities=snapshot.get('entities') if isinstance(snapshot,dict) and isinstance(snapshot.get('entities'),list) else []
+    placed=sum(1 for item in entities if isinstance(item,dict) and isinstance(item.get('placement'),dict))
+    embedded=sum(1 for item in entities if isinstance(item,dict) and isinstance(item.get('payload'),dict) and isinstance(item['payload'].get('cell'),dict))
+    return {**check,'placedEntityCount':placed,'unplacedEntityCount':max(0,len(entities)-placed),'embeddedCellCount':embedded}

clayspace-0.1.1.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: clayspace
+Version: 0.1.1
+Summary: Standalone local spatial modeling toolkit for building portable Cells and worlds on your own computer.
+Author: ClaySpace contributors
+License-Expression: MIT
+Project-URL: Upstream lineage: Fly With Me, https://github.com/kunchenguid/fly-with-me
+Keywords: clayspace,modeling,spatial,3d,blockout,worldbuilding,geometry,offline
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+License-File: licenses/FLY_WITH_ME_MIT.txt
+Dynamic: license-file
+
+# ClaySpace
+
+**ClaySpace is a standalone spatial modeling toolkit you can install on your
+own computer and use without an account, hosted service, or host-world SDK.**
+Build a room, a building, a street, a stage, a landscape
+blockout, an abstract structure, or a whole world from portable local pieces
+called **Cells**.
+
+ClaySpace is intentionally lightweight. Its job is to give geometry stable
+identity, coordinates, placement, and a viewable spatial structure without
+forcing a particular art pipeline or story system on top of it.
+
+> **Upstream license notice:** ClaySpace's development lineage includes
+> [Fly With Me](https://github.com/kunchenguid/fly-with-me) by Kun Chen, used
+> under the MIT License. The original `Copyright (c) 2026 Kun Chen` notice and
+> MIT terms are included with this distribution in
+> `licenses/FLY_WITH_ME_MIT.txt`. ClaySpace is an independent project and is
+> not maintained or endorsed by the Fly With Me project.
+
+```bash
+python -m pip install clayspace==0.1.1
+```
+
+There are no required runtime dependencies and no network calls in the core
+package.
+
+## Make something
+
+Start a local Cell:
+
+```bash
+clayspace cell init --id MY-HOUSE --name "My house" --size 12,8,18 --out house.json
+```
+
+Add and edit primitive geometry:
+
+```bash
+clayspace cell add-box house.json --id GARAGE --position 8,1.5,3 --size 6,3,7 --out house-2.json
+clayspace cell add-cylinder house-2.json --id TOWER --position -4,6,0 --radius 2 --height 12 --out house-3.json
+clayspace cell add-sphere house-3.json --id DOME --position -4,12,0 --radius 2.4 --out house-4.json
+clayspace cell move house-4.json --id GARAGE --position 8,1.5,-2 --out house-5.json
+clayspace cell preview house-5.json --out house-preview.html
+```
+
+`preview` writes a **self-contained HTML file** with a dependency-free orbit,
+zoom, grid, and wireframe/shaded primitive viewer. Open it in any modern
+browser. Nothing is uploaded anywhere.
+
+You can also work directly in Python:
+
+```python
+from clayspace import new_box_cell, add_box, add_cylinder, save_cell
+
+cell = new_box_cell(cell_id="MY-SET", name="My set", size=(20, 1, 20))
+cell = add_box(cell, object_id="WALL-A", position=(0, 2, -8), size=(20, 4, 0.4))
+cell = add_cylinder(cell, object_id="COLUMN", position=(3, 2, 0), radius=0.5, height=4)
+save_cell(cell, "my-set.json")
+```
+
+## Compose a world
+
+Cells stay local and portable. A **world** places them with transforms without
+rewriting the Cell itself.
+
+```bash
+clayspace world init --id MY-WORLD --name "My world" --out world.json
+clayspace world place world.json --cell house-5.json --entity-id HOUSE-01 --position 30,0,-12 --yaw-radians 0.6 --out world-2.json
+clayspace world preview world-2.json --out world-preview.html
+```
+
+That separation means the same building can be placed many times, moved, or
+shared without baking any one world's coordinates into the source object.
+
+## Cells and geometry
+
+The public `clayspace.cell.local-fragment` format uses meters with
+`x-right / y-up / z-forward` coordinates. 0.1.1 supports these procedural
+primitives:
+
+- boxes;
+- prisms with arbitrary X/Z footprints;
+- cylinders;
+- spheres;
+- planes/cards.
+
+Cells may also carry additional metadata and asset references. The validator
+checks structural portability; it is not a structural-engineering, collision,
+or mesh-quality certification system.
+
+For compatibility, ClaySpace also reads the earlier compact `0.1` Cell form and
+richer production Cells that carry extra host metadata. Host-specific fields do
+not become part of ClaySpace policy.
+
+## What ClaySpace does *not* require
+
+You do **not** need:
+
+- another project's SDK;
+- a cloud account;
+- a ledger or database service;
+- a server;
+- a particular renderer;
+- permission from a host system to make your own Cells and worlds.
+
+Other projects can choose to depend on ClaySpace. ClaySpace itself does not
+depend on their identity, workflow, publication, or governance systems.
+
+## Fly With Me provenance and license
+
+ClaySpace's development lineage includes
+[**Fly With Me**](https://github.com/kunchenguid/fly-with-me), the open-source
+browser world/flight project by **Kun Chen**. Fly With Me is licensed under the
+MIT License, copyright (c) 2026 Kun Chen. Its original MIT notice is included
+verbatim in `licenses/FLY_WITH_ME_MIT.txt` and described in
+`THIRD_PARTY_NOTICES.md`.
+
+We are deliberately explicit about that origin. ClaySpace is an independent
+project and is not maintained or endorsed by Kun Chen or the Fly With Me
+project.
+
+The ClaySpace package itself is also released under the MIT License; see
+`LICENSE`.
+
+## Current scope
+
+ClaySpace 0.1.1 is an early modeling/blockout release, not a replacement for a
+full DCC such as Blender. It provides portable spatial primitives, Cell/world
+composition, transforms, validation, and local browser previews. Mesh import,
+advanced materials, rigging, sculpting, and a full desktop GUI are not part of
+this release.

clayspace-0.1.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+clayspace/__init__.py,sha256=FpSx4Klx-0cnESpRrGAIIUEqscbt8vqvT8RiKaEWR8w,937
+clayspace/cell.py,sha256=o6PfuVnalhQsNfojvv8Qx_XdaueBS8v4hV1kEcCuR4A,10941
+clayspace/cli.py,sha256=oN8z8w9LpxGa69EIlWJ7C6jT0p68vNbl7ok-rG7mfw0,7001
+clayspace/model.py,sha256=c8k_WQk9CllYb2ykJigRv8mu7w4Y7ttcYIlXHHjXADQ,6698
+clayspace/placement.py,sha256=XM6hGjBcuYjzoI-WUTHJ6pu-7eeMBSILzcmktqpTgHI,1957
+clayspace/preview.py,sha256=dVgRrmFQgtU-xhdbsDs3IRySVdOewy2X2ScC6G6vK_I,7550
+clayspace/resources.py,sha256=Tn783CzxXnKNc5T3oD2a42Kk4T0j1w1SXiyvrAlz87M,568
+clayspace/world.py,sha256=uWHs8I53JlJ1rsTg8Wns2f2rGO1eiRqPiP-1jO3_O2I,5082
+clayspace/data/cell-local-fragment-1.0.0.json,sha256=-uZw4ym0uPTELJ9j-m73bZJzwxy1d5AvBIBF5xBRYh4,735
+clayspace/data/manifest.json,sha256=H1UeaaNUVURyq3khWU2pE8XQeRA62oJ6X9JIKtQeTUg,1153
+clayspace/data/placement-0.1.0.json,sha256=R4rAK6akhcty60ATatMJgMMj8JMM13yrRT3Q_HxMlIY,697
+clayspace/data/world-snapshot-0.1.0.json,sha256=hkblJvqhpzkHcjDTs6DJ78IpltrctZElWN-iyQKHwt0,1328
+clayspace-0.1.1.dist-info/licenses/LICENSE,sha256=8LYNcu_EegxXLVje2xnQJ10SEm9rGTCeySpQIYS-vIc,1079
+clayspace-0.1.1.dist-info/licenses/THIRD_PARTY_NOTICES.md,sha256=SEj71C3RIIFTnOaENzbIc3vM5BTCQ8ETg_MEKsdLgHo,692
+clayspace-0.1.1.dist-info/licenses/licenses/FLY_WITH_ME_MIT.txt,sha256=lFAWvTfhunIRYi72DuHSOrcniWuncQ7dIej76YOGOWk,1065
+clayspace-0.1.1.dist-info/METADATA,sha256=6s6beG89j8wwJDCUNCa-Wo6bdsVbqDCax8aMtpexZfA,5833
+clayspace-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+clayspace-0.1.1.dist-info/entry_points.txt,sha256=cSJvOVWIPUPgaKHD5BxgDZVUAzuze5twFePPtJ3zWjU,49
+clayspace-0.1.1.dist-info/top_level.txt,sha256=EJDy0B2jbeuY2dJsmKrNozeO1573sSAc1wGwXTksM4E,10
+clayspace-0.1.1.dist-info/RECORD,,

clayspace-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clayspace-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clayspace = clayspace.cli:main

clayspace-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClaySpace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clayspace-0.1.1.dist-info/licenses/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices
+
+## Fly With Me
+
+ClaySpace's development lineage includes **Fly With Me**, an open-source browser
+world/flight project by **Kun Chen**:
+
+https://github.com/kunchenguid/fly-with-me
+
+Fly With Me is distributed under the MIT License, copyright (c) 2026 Kun Chen.
+The original license text is preserved verbatim in
+`licenses/FLY_WITH_ME_MIT.txt`.
+
+ClaySpace is an independent project. Kun Chen and the Fly With Me project do
+not maintain, sponsor, or endorse ClaySpace.
+
+The public ClaySpace Python package is licensed separately under its own MIT
+License. The Fly With Me notice remains included to preserve the upstream
+license and make the project's provenance explicit.

clayspace-0.1.1.dist-info/licenses/licenses/FLY_WITH_ME_MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kun Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clayspace-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+clayspace