Add visual design UX optimization plan and sync roadmaps with actual spec state

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

README.md

@@ -191,6 +191,8 @@ See **[ROADMAP.md](./ROADMAP.md)** for the next-phase optimization and improveme
 
 Studio-specific roadmap: **[apps/studio/ROADMAP.md](./apps/studio/ROADMAP.md)**
 
+Visual design UX optimization plan: **[docs/design/visual-design-ux-optimization.md](./docs/design/visual-design-ux-optimization.md)**
+
 ## 🤝 Contributing
 
 We welcome contributions! Please read our **[Contributing Guide](./CONTRIBUTING.md)** for:

ROADMAP.md

@@ -364,20 +364,24 @@ The following renames are planned for packages that implement core service contr
 - [x] Per-element data binding — `dataSource` property on `PageComponentSchema` for multi-object pages
 - [x] Element props — `ElementTextPropsSchema`, `ElementNumberPropsSchema`, `ElementImagePropsSchema`
 
-#### Phase B: Element Library & Builder (v3.3)
+#### Phase B: Element Library & Builder (v3.3) ✅
 
-- [ ] Interactive elements — `element:button`, `element:filter`, `element:form`, `element:record_picker`
-- [ ] `BlankPageLayoutSchema` — Free-form canvas composition with grid-based positioning
-- [ ] Record picker variable binding — `PageVariableSchema` integration with `element:record_picker`
-- [ ] Studio Interface Builder — Drag-and-drop element placement UI
+- [x] Interactive elements — `element:button`, `element:filter`, `element:form`, `element:record_picker`
+- [x] `BlankPageLayoutSchema` — Free-form canvas composition with grid-based positioning
+- [x] Record picker variable binding — `PageVariableSchema` integration with `element:record_picker`
+- [x] `InterfaceBuilderConfigSchema` — Canvas snap, zoom, element palette, layer panel configuration
+- [ ] Studio Interface Builder — Drag-and-drop element placement UI (runtime)
 
-#### Phase C: Sharing, Embedding & Permissions (v4.0)
+#### Phase C: Sharing, Embedding & Permissions (v4.0) 🟡
 
-- [ ] `SharingConfigSchema` — Public link, password, domain restriction, expiration (`src/ui/sharing.zod.ts`)
-- [ ] `EmbedConfigSchema` — iframe embedding with origin restrictions and display options
-- [ ] Per-interface role assignment — `assignedRoles` on `InterfaceSchema`
-- [ ] Public form sharing — `sharing` property on `FormViewSchema`
-- [ ] Design-time user impersonation — `previewAs` option for interface preview
+- [x] `SharingConfigSchema` — Public link, password, domain restriction, expiration (`src/ui/sharing.zod.ts`)
+- [x] `EmbedConfigSchema` — iframe embedding with origin restrictions and display options
+- [x] Per-interface role assignment — `assignedRoles` on `InterfaceSchema`
+- [x] Public form sharing — `sharing` property on `FormViewSchema`
+- [ ] Design-time user impersonation — `previewAs` option for interface preview (see [UX Optimization](docs/design/visual-design-ux-optimization.md))
+- [ ] Share link generation runtime service
+- [ ] Embed code generation runtime service
+- [ ] Security audit for shared/embedded access control
 
 #### Phase D: Advanced Interface Features (v4.1)
 
@@ -522,9 +526,9 @@ The following renames are planned for packages that implement core service contr
 | **v3.0** | ✅ Shipped | Protocol specification complete, core runtime stable |
 | **v3.1** | Q2 2026 | Essential services (`service-cache`, `service-queue`, `service-job`, `service-storage`), PostgreSQL driver, Turso/libSQL core driver ([design](docs/design/driver-turso.md)) |
 | **v3.2** | Q3 2026 | Communication services (`service-realtime`, `service-graphql`, `service-i18n`, `service-notification`), Turso embedded replica & edge sync, UI Protocol Enhancement Phase A (`InterfaceSchema`, `RecordReviewConfig`, content elements) — see [gap analysis](docs/design/airtable-interface-gap-analysis.md) |
-| **v3.3** | Q4 2026 | Business logic services (`service-automation`, `service-workflow`, `service-search`), Turso multi-tenancy (database-per-tenant), UI Protocol Enhancement Phase B (interactive elements, blank page layout, Interface Builder) |
-| **v4.0** | Q1 2027 | Zod v4 migration, `plugin-auth` → `service-auth` rename, JSON Schema output, OpenAPI generation, AI services, multi-tenancy, Turso vector search & FTS5 integration, UI Protocol Enhancement Phase C (sharing, embedding, per-interface permissions) |
-| **v4.1** | Q2 2027 | Studio IDE general availability, marketplace launch, UI Protocol Enhancement Phase D (templates, versioning, collaborative editing) |
+| **v3.3** | Q4 2026 | Business logic services (`service-automation`, `service-workflow`, `service-search`), Turso multi-tenancy (database-per-tenant), UI Protocol Enhancement Phase B spec ✅ complete (interactive elements, blank page layout), Studio Interface Builder runtime, Visual Design UX optimization ([plan](docs/design/visual-design-ux-optimization.md)) |
+| **v4.0** | Q1 2027 | Zod v4 migration, `plugin-auth` → `service-auth` rename, JSON Schema output, OpenAPI generation, AI services, multi-tenancy, Turso vector search & FTS5 integration, UI Protocol Enhancement Phase C spec 🟡 mostly complete (sharing, embedding), `previewAs` design-time preview, Data Studio protocol, runtime share/embed services |
+| **v4.1** | Q2 2027 | Studio IDE general availability, marketplace launch, UI Protocol Enhancement Phase D (templates, versioning, collaborative editing), Interface Builder enhancements (selection model, clipboard, alignment) |
 | **v5.0** | 2027+ | Managed cloud, app store, global ecosystem |
 
 ---
@@ -536,6 +540,7 @@ The following renames are planned for packages that implement core service contr
 | [`ARCHITECTURE.md`](ARCHITECTURE.md) | Microkernel design, package structure, three-layer protocol stack |
 | [`docs/design/driver-turso.md`](docs/design/driver-turso.md) | Turso/libSQL driver design document — architecture impact, capabilities, implementation phases |
 | [`docs/design/airtable-interface-gap-analysis.md`](docs/design/airtable-interface-gap-analysis.md) | Airtable Interface gap analysis — UI protocol comparison, schema proposals, implementation roadmap |
+| [`docs/design/visual-design-ux-optimization.md`](docs/design/visual-design-ux-optimization.md) | Visual Design UX optimization plan — Airtable benchmark, spec coverage audit, Studio builder alignment |
 | [`apps/studio/ROADMAP.md`](apps/studio/ROADMAP.md) | Studio IDE development phases (v2.1 → v3.0) |
 | [`docs/DX_ROADMAP.md`](docs/DX_ROADMAP.md) | Developer experience improvements |
 | [`RELEASE_NOTES.md`](RELEASE_NOTES.md) | Version history and changelog |

apps/studio/ROADMAP.md

@@ -1,6 +1,6 @@
 # ObjectStack Studio — Development Roadmap
 
-> **Last Updated:** 2026-02-15  
+> **Last Updated:** 2026-02-16  
 > **Version:** 2.0.0 → 3.0.0  
 > **Goal:** Transform Studio from a metadata inspector into a full-featured visual IDE for the ObjectStack platform.
 
@@ -106,7 +106,9 @@
 
 ### Phase 2: UI Protocol Designers (v2.3) — 6 weeks
 
-> **Theme:** Visual builders for every UI metadata type — the "App Builder" experience.
+> **Theme:** Visual builders for every UI metadata type — the "App Builder" experience.  
+> **Spec Status:** All UI Protocol schemas are complete (20 files, full Airtable parity). This phase is pure runtime implementation.  
+> **Reference:** [Visual Design UX Optimization Plan](../../docs/design/visual-design-ux-optimization.md)
 
 | # | Task | Plugin ID | Priority |
 |---|------|-----------|----------|
@@ -116,19 +118,21 @@
 | | Mode-specific config panels: Kanban (status field, swimlanes), Calendar (date fields, duration), Gantt (dependencies, milestones). | | |
 | 2.3 | **FormView Designer** | `objectstack.form-designer` | 🔴 P0 |
 | | Section/column layout editor. Field placement with drag-and-drop. Conditional visibility (`visibleOn`). Widget selection per field. Preview mode. | | |
-| 2.4 | **Page Builder** | `objectstack.page-builder` | 🟡 P1 |
+| 2.4 | **Interface Builder** | `objectstack.interface-builder` | 🔴 P0 |
+| | **Airtable Interface Designer parity.** Drag-and-drop element canvas using `BlankPageLayoutSchema`. Element palette (12 types: text, number, image, divider, button, filter, form, record_picker, grid, chart, details, list). Property panel per element. Snap-to-grid with alignment guides. Layer ordering. Undo/redo (50 steps). Data source binding per element (`ElementDataSourceSchema`). See `InterfaceBuilderConfigSchema` in `@objectstack/spec/studio`. | | |
+| 2.5 | **Page Builder** | `objectstack.page-builder` | 🟡 P1 |
 | | Component composition canvas. Drag regions and components (header, details, related list, AI chat, custom). Property panel for each component. Preview with live data context. | | |
-| 2.5 | **App Builder** | `objectstack.app-builder` | 🟡 P1 |
-| | Navigation tree editor (drag-and-drop reorder). Add object/dashboard/page/URL items. Branding panel (colors, logo). Home page selector. | | |
-| 2.6 | **Dashboard Designer** | `objectstack.dashboard-designer` | 🟡 P1 |
+| 2.6 | **App Builder** | `objectstack.app-builder` | 🟡 P1 |
+| | Navigation tree editor (drag-and-drop reorder). Add object/dashboard/page/URL items. Interface management (`interfaces[]`). Branding panel (colors, logo). Home page selector. | | |
+| 2.7 | **Dashboard Designer** | `objectstack.dashboard-designer` | 🟡 P1 |
 | | Grid layout editor (React-Grid-Layout). Widget palette: charts, KPIs, lists, embedded views. Data source binding per widget. Auto-refresh config. | | |
-| 2.7 | **Report Builder** | `objectstack.report-builder` | 🟢 P2 |
+| 2.8 | **Report Builder** | `objectstack.report-builder` | 🟢 P2 |
 | | Tabular/Summary/Matrix report config. Column picker, grouping, aggregation. Embedded chart toggle. Filter builder. Export options. | | |
-| 2.8 | **Chart Editor** | `objectstack.chart-editor` | 🟢 P2 |
+| 2.9 | **Chart Editor** | `objectstack.chart-editor` | 🟢 P2 |
 | | Visual chart type selector (40+ types). Axis/series configuration. Preview with sample data. Annotation support. | | |
-| 2.9 | **Action Editor** | `objectstack.action-editor` | 🟢 P2 |
+| 2.10 | **Action Editor** | `objectstack.action-editor` | 🟢 P2 |
 | | Configure action type (script/URL/modal/flow/API). Location picker. Confirm/success text. Keyboard shortcut. Visibility conditions. | | |
-| 2.10 | **Theme Editor** | `objectstack.theme-editor` | 🟢 P2 |
+| 2.11 | **Theme Editor** | `objectstack.theme-editor` | 🟢 P2 |
 | | Visual color palette picker. Typography controls. Spacing/radius scale. Live preview. Export to theme metadata. | | |
 
 **Deliverable:** Full "App Builder" experience — design complete applications visually.
@@ -256,7 +260,8 @@
 
 ### Phase 8: Studio Platform Evolution (v3.0) — Ongoing
 
-> **Theme:** Studio becomes a full IDE ecosystem.
+> **Theme:** Studio becomes a full IDE ecosystem.  
+> **Reference:** [Visual Design UX Optimization Plan](../../docs/design/visual-design-ux-optimization.md)
 
 | # | Task | Priority |
 |---|------|----------|
@@ -270,12 +275,18 @@
 | | Git diff viewer for metadata changes. Commit from Studio. Branch switching. Conflict resolution. |
 | 8.5 | **External Plugin Marketplace** | 🟡 P1 |
 | | Browse/install community Studio plugins. Plugin manifest validation. Sandboxed execution. |
-| 8.6 | **Collaborative Editing** | 🟢 P2 |
+| 8.6 | **Data Studio Mode** | 🟡 P1 |
+| | Unified interactive data workspace combining views + embedded charts + inline editing + quick filters. Cross-view global filter. Aggregation bar. View switcher tabs. See `DataStudioConfigSchema` proposal. |
+| 8.7 | **Design-Time Preview** | 🟡 P1 |
+| | Preview interfaces as different users/roles. Responsive viewport switcher (desktop/tablet/mobile). Live data preview. Show data binding indicators. |
+| 8.8 | **Template Gallery** | 🟡 P1 |
+| | Pre-built interface templates (CRM, Project, HR, etc.). One-click instantiation with variable binding. Community template marketplace. |
+| 8.9 | **Collaborative Editing** | 🟢 P2 |
 | | Real-time multi-user editing (CRDT). Presence indicators. Change attribution. |
-| 8.7 | **Responsive / Mobile Mode** | 🟢 P2 |
+| 8.10 | **Responsive / Mobile Mode** | 🟢 P2 |
 | | Mobile preview mode. Responsive layout testing. Touch-friendly interactions. |
-| 8.8 | **Embedded AI Copilot** | 🟡 P1 |
-| | In-Studio AI assistant. Generate metadata from natural language. Explain configuration. Suggest best practices. |
+| 8.11 | **Embedded AI Copilot** | 🟡 P1 |
+| | In-Studio AI assistant. Generate metadata from natural language. Explain configuration. Suggest best practices. AI-assisted layout suggestions. |
 
 ---
 
@@ -350,7 +361,9 @@ export const myPlugin: StudioPlugin = {
 | Metadata types with dedicated viewer | 1 / 30+ | 15 / 30+ | 30+ / 30+ |
 | Object Designer protocol schemas | 16 schemas | — | — |
 | Object Designer protocol tests | 46 tests | — | — |
+| Interface Builder protocol schemas | 4 schemas | 10+ | 15+ |
 | Component test coverage | 0% | 50% | 80% |
 | Deep-linkable views | 0 | All | All |
 | Plugin count (built-in) | 7 | 20 | 35+ |
+| Airtable UX parity (visual builder) | 20% | 60% | 90% |
 | Time to build a complete app (from scratch) | N/A (manual JSON) | 30 min | 10 min |

docs/design/airtable-interface-gap-analysis.md

@@ -2,7 +2,7 @@
 
 > **Author:** ObjectStack Core Team  
 > **Created:** 2026-02-16  
-> **Status:** Phase A Implemented  
+> **Status:** Phase A–C Spec Complete · Studio Runtime Pending  
 > **Target Version:** v3.2 – v4.0
 
 ---
@@ -59,12 +59,12 @@ ties them together — specifically:
 | Area | Airtable | ObjectStack |
 |:---|:---|:---|
 | **Interface as a first-class entity** | ✅ Multi-page app per base | ✅ `InterfaceSchema` + `App.interfaces[]` drives sidebar |
-| **Drag-and-drop element canvas** | ✅ Free-form element placement | 🟡 Region-based composition |
+| **Drag-and-drop element canvas** | ✅ Free-form element placement | ✅ `BlankPageLayoutSchema` + `InterfaceBuilderConfigSchema` |
 | **Record Review workflow** | ✅ Built-in record-by-record review | ✅ `RecordReviewConfigSchema` in `PageSchema` |
 | **Element-level data binding** | ✅ Each element binds to any table/view | ✅ `ElementDataSourceSchema` per component |
-| **Shareable interface URLs** | ✅ Public/private share links | ❌ Not modeled (Phase C) |
+| **Shareable interface URLs** | ✅ Public/private share links | ✅ `SharingConfigSchema` on `InterfaceSchema` |
 | **Interface-level permissions** | ✅ Per-interface user access | ✅ `assignedRoles` on `InterfaceSchema` |
-| **Embeddable interfaces** | ✅ iframe embed codes | ❌ Not modeled (Phase C) |
+| **Embeddable interfaces** | ✅ iframe embed codes | ✅ `EmbedConfigSchema` on `InterfaceSchema` |
 
 This document proposes specific schema additions and a phased roadmap to close these gaps while
 preserving ObjectStack's superior extensibility and enterprise capabilities.
@@ -630,33 +630,34 @@ export const EmbedConfigSchema = z.object({
 
 **Estimated effort:** 2–3 weeks
 
-### 7.2 Phase B: Element Library & Builder (v3.3 — Q4 2026)
+### 7.2 Phase B: Element Library & Builder (v3.3 — Q4 2026) ✅
 
 > **Goal:** Complete the element library and enable free-form page composition.
 
-- [ ] Add interactive elements: `element:button`, `element:filter`, `element:form`, `element:record_picker`
-- [ ] Add `ElementFormPropsSchema`, `ElementRecordPickerPropsSchema`, `ElementButtonPropsSchema`, `ElementFilterPropsSchema`
-- [ ] Define `BlankPageLayoutSchema` for free-form canvas composition (grid-based positioning)
-- [ ] Add `PageVariableSchema` integration with `element:record_picker` (variable binding)
-- [ ] Add `RecordReviewConfigSchema` with approval actions, navigation modes, and progress indicators
-- [ ] Implement Studio Interface Builder UI (drag-and-drop element placement)
-- [ ] Write integration tests for multi-element page composition
+- [x] Add interactive elements: `element:button`, `element:filter`, `element:form`, `element:record_picker`
+- [x] Add `ElementFormPropsSchema`, `ElementRecordPickerPropsSchema`, `ElementButtonPropsSchema`, `ElementFilterPropsSchema`
+- [x] Define `BlankPageLayoutSchema` for free-form canvas composition (grid-based positioning)
+- [x] Add `PageVariableSchema` integration with `element:record_picker` (variable binding)
+- [x] Add `RecordReviewConfigSchema` with approval actions, navigation modes, and progress indicators
+- [x] Define `InterfaceBuilderConfigSchema` with snap, zoom, palette, layer panel configuration
+- [ ] Implement Studio Interface Builder UI (drag-and-drop element placement) — **runtime task**
+- [x] Write integration tests for multi-element page composition
 
 **Estimated effort:** 4–6 weeks
 
-### 7.3 Phase C: Sharing, Embedding & Permissions (v4.0 — Q1 2027)
+### 7.3 Phase C: Sharing, Embedding & Permissions (v4.0 — Q1 2027) 🟡
 
 > **Goal:** Enable Airtable-level sharing and access control for interfaces.
 
-- [ ] Define `SharingConfigSchema` in `src/ui/sharing.zod.ts`
-- [ ] Define `EmbedConfigSchema` for iframe embedding configuration
-- [ ] Add `sharing` property to `InterfaceSchema` and `FormViewSchema` (public forms)
-- [ ] Add per-interface role assignment (`assignedRoles`)
-- [ ] Implement share link generation in runtime (service layer)
-- [ ] Implement embed code generation with origin restrictions
-- [ ] Add `previewAs` option for design-time user impersonation
-- [ ] Security audit for shared/embedded interface access control
-- [ ] Write permission and sharing tests
+- [x] Define `SharingConfigSchema` in `src/ui/sharing.zod.ts`
+- [x] Define `EmbedConfigSchema` for iframe embedding configuration
+- [x] Add `sharing` property to `InterfaceSchema` and `FormViewSchema` (public forms)
+- [x] Add per-interface role assignment (`assignedRoles`)
+- [ ] Implement share link generation in runtime (service layer) — **runtime task**
+- [ ] Implement embed code generation with origin restrictions — **runtime task**
+- [ ] Add `previewAs` option for design-time user impersonation — see [Visual Design UX Optimization](./visual-design-ux-optimization.md)
+- [ ] Security audit for shared/embedded interface access control — **runtime task**
+- [x] Write permission and sharing tests
 
 **Estimated effort:** 4–6 weeks