boxframe 0.1.0__py3-none-any.whl

boxframe/__init__.py

@@ -0,0 +1,8 @@
+"""boxframe — Pseudo-graphic UI mockup editor for AI agents."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("boxframe")
+except PackageNotFoundError:  # installed without metadata (e.g. run from source)
+    __version__ = "0.0.0"

boxframe/api/__init__.py

@@ -0,0 +1,4 @@
+from boxframe.api.projects import router as projects_router
+from boxframe.api.layouts import router as layouts_router
+
+__all__ = ["projects_router", "layouts_router"]

boxframe/api/layouts.py

@@ -0,0 +1,349 @@
+"""
+Layout API routes.
+"""
+
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from boxframe.database import get_db
+from boxframe.services.layout_service import LayoutService
+from boxframe.services.renderer import PseudoGraphicRenderer
+
+router = APIRouter(prefix="/api/layouts", tags=["layouts"])
+
+
+# ── Pydantic schemas ──────────────────────────────────────
+
+class BlockOut(BaseModel):
+    id: str
+    block_type: str
+    x: int
+    y: int
+    width: int
+    height: int
+    content: str
+    border_style: str
+    parent_id: str | None
+    meta: dict
+    order: int
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class LayoutCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=255)
+    # Optional: a layout may have a width, a height, both, or neither.
+    # No upper limit: a set dimension is a visual bounds line in the
+    # editor — blocks may be placed outside it, it is not a constraint.
+    width: int | None = Field(default=None, ge=1)
+    height: int | None = Field(default=None, ge=1)
+
+
+class LayoutUpdate(BaseModel):
+    name: str | None = None
+    width: int | None = None
+    height: int | None = None
+
+
+class LayoutOut(BaseModel):
+    id: str
+    project_id: str
+    name: str
+    width: int | None = None
+    height: int | None = None
+    blocks: list[BlockOut] = []
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class BlockCreate(BaseModel):
+    block_type: str = Field(..., description="Type of block (box, button, input, etc.)")
+    x: int = 0
+    y: int = 0
+    width: int = 20
+    height: int = 3
+    content: str = ""
+    border_style: str = "solid"
+    parent_id: str | None = None
+    meta: dict = {}
+    order: int = 0
+
+
+class BlockUpdate(BaseModel):
+    block_type: str | None = None
+    x: int | None = None
+    y: int | None = None
+    width: int | None = None
+    height: int | None = None
+    content: str | None = None
+    border_style: str | None = None
+    parent_id: str | None = None
+    meta: dict | None = None
+    order: int | None = None
+
+
+class BlockIn(BaseModel):
+    """A block in a full-state replace payload.
+
+    id is optional: given ids are preserved (undo/redo restores the same
+    block identity), missing ids are generated server-side.
+    """
+
+    id: str | None = None
+    block_type: str = "box"
+    x: int = 0
+    y: int = 0
+    width: int = 20
+    height: int = 3
+    content: str = ""
+    border_style: str = "solid"
+    parent_id: str | None = None
+    meta: dict = {}
+    order: int = 0
+
+
+class BlocksReplace(BaseModel):
+    blocks: list[BlockIn]
+
+
+class RenderOut(BaseModel):
+    ascii: str
+    html: str | None = None
+
+
+class ExportOut(BaseModel):
+    layout_json: dict | None = None
+    markdown: str | None = None
+    ascii: str | None = None
+
+
+# ── Layout CRUD ───────────────────────────────────────────
+
+@router.post("/{project_id}/layouts", response_model=LayoutOut)
+async def create_layout(project_id: str, data: LayoutCreate, db: AsyncSession = Depends(get_db)):
+    service = LayoutService(db)
+    layout = await service.create_layout(project_id, data.name, data.width, data.height)
+    return layout
+
+
+@router.get("/{layout_id}", response_model=LayoutOut)
+async def get_layout(layout_id: str, db: AsyncSession = Depends(get_db)):
+    service = LayoutService(db)
+    layout = await service.get_layout(layout_id)
+    if not layout:
+        raise HTTPException(status_code=404, detail="Layout not found")
+    return layout
+
+
+@router.delete("/{layout_id}")
+async def delete_layout(layout_id: str, db: AsyncSession = Depends(get_db)):
+    service = LayoutService(db)
+    layout = await service.get_layout(layout_id)
+    if not layout:
+        raise HTTPException(status_code=404, detail="Layout not found")
+    await service.delete_layout(layout_id)
+    return {"ok": True}
+
+
+# ── Block CRUD ────────────────────────────────────────────
+
+@router.post("/{layout_id}/blocks", response_model=BlockOut)
+async def create_block(layout_id: str, data: BlockCreate, db: AsyncSession = Depends(get_db)):
+    service = LayoutService(db)
+    block = await service.create_block(
+        layout_id=layout_id,
+        block_type=data.block_type,
+        x=data.x,
+        y=data.y,
+        width=data.width,
+        height=data.height,
+        content=data.content,
+        border_style=data.border_style,
+        parent_id=data.parent_id,
+        meta=data.meta,
+        order=data.order,
+    )
+    return block
+
+
+@router.put("/{layout_id}/blocks/{block_id}", response_model=BlockOut)
+async def update_block(layout_id: str, block_id: str, data: BlockUpdate, db: AsyncSession = Depends(get_db)):
+    service = LayoutService(db)
+    block = await service.get_block(block_id)
+    if not block or block.layout_id != layout_id:
+        raise HTTPException(status_code=404, detail="Block not found")
+
+    update_data = data.model_dump(exclude_none=True)
+    if not update_data:
+        return block
+
+    updated = await service.update_block(block_id, **update_data)
+    return updated
+
+
+@router.delete("/{layout_id}/blocks/{block_id}")
+async def delete_block(layout_id: str, block_id: str, db: AsyncSession = Depends(get_db)):
+    service = LayoutService(db)
+    block = await service.get_block(block_id)
+    if not block or block.layout_id != layout_id:
+        raise HTTPException(status_code=404, detail="Block not found")
+    await service.delete_block(block_id)
+    return {"ok": True}
+
+
+@router.delete("/{layout_id}/blocks")
+async def clear_layout_blocks(layout_id: str, db: AsyncSession = Depends(get_db)):
+    """Remove all blocks from a layout (the layout itself is kept)."""
+    service = LayoutService(db)
+    layout = await service.get_layout(layout_id)
+    if not layout:
+        raise HTTPException(status_code=404, detail="Layout not found")
+    deleted = await service.delete_all_blocks(layout_id)
+    return {"ok": True, "deleted": deleted}
+
+
+@router.put("/{layout_id}/blocks", response_model=LayoutOut)
+async def replace_layout_blocks(layout_id: str, data: BlocksReplace, db: AsyncSession = Depends(get_db)):
+    """Replace all blocks of a layout with the given set (full state restore).
+
+    Backs the editor's undo/redo: the client sends a state snapshot and the
+    layout is atomically restored to it. Block ids from the payload are kept.
+    """
+    service = LayoutService(db)
+    layout = await service.get_layout(layout_id)
+    if not layout:
+        raise HTTPException(status_code=404, detail="Layout not found")
+    updated = await service.replace_blocks(layout_id, [b.model_dump() for b in data.blocks])
+    return updated
+
+
+# ── Rendering ─────────────────────────────────────────────
+
+@router.get("/{layout_id}/render", response_model=RenderOut)
+async def render_layout(
+    layout_id: str,
+    char_width_px: float = Query(default=12.0, ge=1, le=50),
+    char_height_px: float = Query(default=14.4, ge=1, le=50),
+    db: AsyncSession = Depends(get_db),
+):
+    """Render layout to pseudo-graphic ASCII art.
+
+    char_width_px / char_height_px — measured pixel dimensions of a single
+    character.  JS measures the real .ascii-art character size and passes
+    them back so overlays match exactly.
+    """
+    service = LayoutService(db)
+    ascii_art = await service.render_layout(layout_id)
+    if ascii_art is None:
+        raise HTTPException(status_code=404, detail="Layout not found")
+
+    # Generate HTML preview with block overlays and resize handles
+    layout = await service.get_layout(layout_id)
+    html = ""
+    if layout:
+        # Canvas = layout size expanded to fit blocks outside the bounds
+        # (the ASCII grid is rendered the same way).
+        canvas_w, canvas_h = service.canvas_size(layout)
+        # Compute exact pixel dimensions so the art layer and overlays share
+        # the same size.
+        pre_width = canvas_w * char_width_px
+        pre_height = round(canvas_h * char_height_px, 1)
+        pad = 16.0
+        # Padding lives on .render-wrapper; the art layer has no margin so
+        # overlay coordinates (padding_offset + grid * char_size) align
+        # exactly.  It is a <div>, not a <pre>: the HTML parser strips the
+        # first newline right after a <pre> start tag, which would drop the
+        # first row when the art starts with an empty row (topmost block
+        # not at y=0) and shift the art up one row relative to the overlays.
+        ascii_html = (
+            f'<div class="ascii-art" style="font-family: monospace; font-size: 12px; '
+            f'line-height: 1.2; display: block; white-space: pre; '
+            f'width:{pre_width}px; height:{pre_height}px; '
+            f'background: #1a1a2e; color: #e0e0e0;">'
+            f"{ascii_art.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')}</div>"
+        )
+        blocks_data = _serialize_blocks_for_html(layout.blocks)
+        block_previews_html = PseudoGraphicRenderer.render_html_preview(
+            blocks_data,
+            char_width_px=char_width_px,
+            char_height_px=char_height_px,
+            padding_offset=pad,
+        )
+        # Layout bounds overlay: a set width/height draws a visual line on
+        # the editor canvas. It does not affect block placement or the
+        # canvas size, and it is not part of the ASCII art.
+        bounds_html = PseudoGraphicRenderer.render_bounds_html(
+            layout.width,
+            layout.height,
+            char_width_px=char_width_px,
+            char_height_px=char_height_px,
+            padding_offset=pad,
+        )
+        html = (
+            f'<div class="render-wrapper" '
+            f'style="width:{pre_width}px; height:{pre_height}px;">'
+            f"{ascii_html}"
+            f"{bounds_html}"
+            f"{block_previews_html}"
+            f"</div>"
+        )
+
+    return RenderOut(ascii=ascii_art, html=html)
+
+
+def _serialize_blocks_for_html(blocks: list) -> list[dict]:
+    """Serialize ORM blocks to dicts for HTML preview generation."""
+    by_id = {b.id: b for b in blocks}
+    result = []
+    for block in blocks:
+        if block.parent_id and block.parent_id in by_id:
+            continue
+        bd = {
+            "id": block.id,
+            "x": block.x,
+            "y": block.y,
+            "width": block.width,
+            "height": block.height,
+            "block_type": block.block_type,
+            "content": block.content,
+            "border_style": block.border_style,
+            "order": block.order,
+            "children": [
+                {
+                    "id": c.id,
+                    "x": c.x,
+                    "y": c.y,
+                    "width": c.width,
+                    "height": c.height,
+                    "block_type": c.block_type,
+                    "content": c.content,
+                    "border_style": c.border_style,
+                    "order": c.order,
+                }
+                for c in blocks
+                if c.parent_id == block.id
+            ],
+        }
+        result.append(bd)
+    return result
+
+
+@router.get("/{layout_id}/export", response_model=ExportOut)
+async def export_layout(layout_id: str, db: AsyncSession = Depends(get_db)):
+    """Export layout in multiple formats."""
+    service = LayoutService(db)
+
+    json_data = await service.export_json(layout_id)
+    markdown = await service.export_markdown(layout_id)
+    ascii_art = await service.render_layout(layout_id)
+
+    return ExportOut(layout_json=json_data, markdown=markdown, ascii=ascii_art)

boxframe/api/projects.py

@@ -0,0 +1,143 @@
+"""
+Project API routes.
+"""
+
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from boxframe.database import get_db
+from boxframe.models.block import BLOCK_TYPES, BORDER_STYLES
+from boxframe.services.layout_service import LayoutService
+
+router = APIRouter(prefix="/api/projects", tags=["projects"])
+
+
+# ── Pydantic schemas ──────────────────────────────────────
+
+class ProjectCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=255)
+
+
+class ProjectOut(BaseModel):
+    id: str
+    name: str
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class LayoutOut(BaseModel):
+    id: str
+    name: str
+    width: int | None = None
+    height: int | None = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class BlockSchema(BaseModel):
+    id: str | None = None
+    block_type: str
+    x: int = 0
+    y: int = 0
+    width: int = 20
+    height: int = 3
+    content: str = ""
+    border_style: str = "solid"
+    parent_id: str | None = None
+    meta: dict = {}
+    order: int = 0
+
+
+class BlockOut(BaseModel):
+    id: str
+    block_type: str
+    x: int
+    y: int
+    width: int
+    height: int
+    content: str
+    border_style: str
+    parent_id: str | None
+    meta: dict
+    order: int
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+# ── Routes ────────────────────────────────────────────────
+
+@router.get("/", response_model=list[ProjectOut])
+async def list_projects(db: AsyncSession = Depends(get_db)):
+    service = LayoutService(db)
+    projects = await service.list_projects()
+    return projects
+
+
+@router.post("/", response_model=ProjectOut)
+async def create_project(data: ProjectCreate, db: AsyncSession = Depends(get_db)):
+    service = LayoutService(db)
+    project = await service.create_project(data.name)
+    return project
+
+
+@router.get("/{project_id}", response_model=ProjectOut)
+async def get_project(project_id: str, db: AsyncSession = Depends(get_db)):
+    service = LayoutService(db)
+    project = await service.get_project(project_id)
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    return project
+
+
+@router.delete("/{project_id}")
+async def delete_project(project_id: str, db: AsyncSession = Depends(get_db)):
+    service = LayoutService(db)
+    project = await service.get_project(project_id)
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    await service.delete_project(project_id)
+    return {"ok": True}
+
+
+@router.get("/{project_id}/info", response_model=dict)
+async def project_info(project_id: str, db: AsyncSession = Depends(get_db)):
+    """Return project metadata including available block types and border styles."""
+    service = LayoutService(db)
+    project = await service.get_project(project_id)
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+
+    return {
+        "project": {"id": project.id, "name": project.name},
+        "layouts": [{"id": l.id, "name": l.name} for l in project.layouts],
+        "block_types": BLOCK_TYPES,
+        "border_styles": BORDER_STYLES,
+    }
+
+
+class LayoutCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=255)
+    # Optional: a layout may have a width, a height, both, or neither.
+    # A set dimension is a visual bounds line in the editor, not a constraint.
+    width: int | None = Field(default=None, ge=1)
+    height: int | None = Field(default=None, ge=1)
+
+
+@router.post("/{project_id}/layouts", response_model=LayoutOut)
+async def create_layout(project_id: str, data: LayoutCreate, db: AsyncSession = Depends(get_db)):
+    """Create a new layout for a project."""
+    service = LayoutService(db)
+    layout = await service.create_layout(project_id, data.name, data.width, data.height)
+    return layout

boxframe/api/test_cleanup.py

@@ -0,0 +1,62 @@
+"""
+Test cleanup API route.
+
+Deletes all projects, layouts, and blocks whose names start with
+the ``E2E: `` prefix.  This keeps the production database clean
+when running E2E tests against a shared server.
+"""
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from boxframe.database import get_db
+from boxframe.models.block import Block
+from boxframe.models.layout import Layout
+from boxframe.models.project import Project
+
+router = APIRouter(prefix="/api/test", tags=["test"])
+
+E2E_PREFIX = "E2E: "
+
+
+@router.delete("/cleanup")
+async def cleanup_e2e_data(db: AsyncSession = Depends(get_db)):
+    """Delete all E2E test data (projects, layouts, blocks with E2E prefix)."""
+    # 1. Collect layout IDs belonging to E2E projects
+    e2e_projects = await db.execute(
+        select(Project.id).where(Project.name.like(f"{E2E_PREFIX}%"))
+    )
+    e2e_project_ids = set(e2e_projects.scalars().all())
+
+    # 2. Collect layout IDs for those projects
+    e2e_layouts = await db.execute(
+        select(Layout.id).where(Layout.project_id.in_(e2e_project_ids))
+    )
+    e2e_layout_ids = set(e2e_layouts.scalars().all())
+
+    # 3. Delete blocks belonging to those layouts
+    deleted_blocks = 0
+    if e2e_layout_ids:
+        result = await db.execute(delete(Block).where(Block.layout_id.in_(e2e_layout_ids)))
+        deleted_blocks = result.rowcount
+
+    # 4. Delete layouts
+    deleted_layouts = 0
+    if e2e_layout_ids:
+        result = await db.execute(delete(Layout).where(Layout.id.in_(e2e_layout_ids)))
+        deleted_layouts = result.rowcount
+
+    # 5. Delete projects
+    deleted_projects = 0
+    if e2e_project_ids:
+        result = await db.execute(delete(Project).where(Project.id.in_(e2e_project_ids)))
+        deleted_projects = result.rowcount
+
+    await db.commit()
+
+    return {
+        "deleted_projects": deleted_projects,
+        "deleted_layouts": deleted_layouts,
+        "deleted_blocks": deleted_blocks,
+    }

boxframe/config.py

@@ -0,0 +1,14 @@
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    app_name: str = "boxframe"
+    database_url: str = "sqlite+aiosqlite:///./boxframe.db"
+    debug: bool = False
+    log_dir: str = "log"
+
+    class Config:
+        env_prefix = "BOXFRAME_"
+
+
+settings = Settings()

boxframe/database.py

@@ -0,0 +1,62 @@
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+
+from boxframe.config import settings
+
+engine = create_async_engine(settings.database_url, echo=settings.debug)
+async_session = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        try:
+            yield session
+        finally:
+            await session.close()
+
+
+async def init_db():
+    async with engine.begin() as conn:
+        await conn.run_sync(_migrate_layouts_size_nullable)
+        await conn.run_sync(Base.metadata.create_all)
+
+
+def _migrate_layouts_size_nullable(conn) -> None:
+    """One-off migration: layouts.width/height became nullable.
+
+    SQLite cannot drop NOT NULL in place, so the table is rebuilt when the
+    old (non-nullable) schema is detected. Existing data is preserved.
+    """
+    result = conn.exec_driver_sql("PRAGMA table_info(layouts)")
+    cols = {row[1]: row for row in result.fetchall()}
+    if not cols:
+        return  # table does not exist yet — create_all will make it
+    # PRAGMA table_info row: (cid, name, type, notnull, dflt_value, pk)
+    if not cols["width"][3] and not cols["height"][3]:
+        return  # already nullable
+    conn.exec_driver_sql(
+        """
+        CREATE TABLE layouts_migrated (
+            id VARCHAR(36) PRIMARY KEY,
+            project_id VARCHAR(36) NOT NULL REFERENCES projects(id),
+            name VARCHAR(255) NOT NULL,
+            width INTEGER,
+            height INTEGER,
+            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+            updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+        )
+        """
+    )
+    conn.exec_driver_sql(
+        "INSERT INTO layouts_migrated "
+        "(id, project_id, name, width, height, created_at, updated_at) "
+        "SELECT id, project_id, name, width, height, created_at, updated_at FROM layouts"
+    )
+    conn.exec_driver_sql("DROP TABLE layouts")
+    conn.exec_driver_sql("ALTER TABLE layouts_migrated RENAME TO layouts")