PRD 03: Visual Editor, Houston Runtime, and Embed Widget
Problem Statement
Picasso FE contains the old visual editor and Houston runtime. These are central to the old product experience: creators build flows visually, and end users consume them through an embeddable runtime. The old implementation has strong interaction patterns but also complexity in hook sprawl, snapshot-only runtime behavior, and limited inspector structure.
The new platform must preserve the editor/runtime feature set while creating a safer and clearer product architecture.
Solution
Preserve the editor and runtime as two connected products:
- Creator editor: visual canvas, creation menu, shell/top bar, node/component editing, autosave, collaboration signals, results/share/settings sections.
- Runtime: Houston-style published experience, page navigation, component rendering, media capture, form submission, AI node handling, embedding, whitelabeling, and analytics.
Legacy Source References
picasso-fe-reference/apps/picasso-editor/src/pages/flow-editor/picasso-fe-reference/apps/picasso-editor/src/widgets/react-flow-instance/picasso-fe-reference/apps/picasso-editor/src/widgets/editor-shell/picasso-fe-reference/apps/picasso-editor/src/widgets/editor-top-bar/picasso-fe-reference/apps/picasso-editor/src/widgets/creation-bar/picasso-fe-reference/apps/houston/src/widgets/houston-routine/picasso-fe-reference/packages/common/src/entities/houston/picasso-fe-reference/apps/widget/src/
User Stories
- As a creator, I want a visual canvas, so that I can build flows without writing code.
- As a creator, I want to add text, media, forms, buttons, AI nodes, router nodes, and notes, so that I can compose rich experiences.
- As a creator, I want drag, resize, duplicate, paste, align, and delete actions, so that editing feels efficient.
- As a creator, I want autosave, so that work is not lost.
- As a creator, I want visible save state, so that I know whether changes are stored.
- As a creator, I want undo and redo, so that I can recover from mistakes.
- As a creator, I want an inspector or property panel, so that complex nodes can be configured clearly.
- As a creator, I want preview mode, so that I can test the published experience.
- As a creator, I want results, share, settings, integrations, webhooks, and notifications accessible from the editor, so that all flow operations are in one place.
- As an end user, I want the runtime to load quickly, so that published companions feel polished.
- As an end user, I want forms, media capture, camera, microphone, GPS, barcode, and upload fields to work in the runtime.
- As an end user, I want runtime navigation to follow conditions and AI decisions, so that the companion adapts to my input.
- As a site owner, I want to embed a companion in a website, so that users can access it outside the app.
- As a brand owner, I want whitelabel colors, logo, and domain settings, so that the runtime matches my brand.
- As an operator, I want runtime errors reported, so that broken public flows can be diagnosed.
Functional Requirements
Editor Shell
- Fixed top bar with flow name, main sections, publish action, collaboration avatars, and validation status.
- Creation toolbar for adding supported content and logic blocks.
- Editor sections: editor, results, share, settings, integrations, webhooks, notifications.
- Responsive layout for creator workflows.
Canvas and Component Editing
- Support page/step nodes, router nodes, AI nodes, sticky notes, media nodes, and form nodes.
- Support nested components inside page/step nodes.
- Support selection, multi-select, drag/drop, alignment, resize, copy/paste, keyboard shortcuts, and context menus.
- Support an inspector panel for complex configuration.
- Support normalized local state and pending-change batches.
Save and Collaboration
- Autosave changes with debounced batch updates.
- Show save state and errors.
- Support collaboration presence and user cursors where feasible.
- Avoid disconnected undo/redo state; undo/redo must integrate with the editor state and save state.
Runtime Rendering
- Load the published flow snapshot or version.
- Render runtime pages/steps in order or based on routing.
- Support form state, AI state, navigation path, session state, and submission state.
- Support component catalog: text, image, button, form fields, video, audio, carousel, icon, shape, Typeform, YouTube, Vimeo, Mux, file upload, image recognition, barcode, GPS, live capture, record video, record audio.
- Support background and foreground components.
- Support AI node processing before navigation when configured.
Embed Widget
- Support iframe embedding.
- Support camera, microphone, geolocation, autoplay, and clipboard permissions only when needed.
- Support popup, floating, and inline embed modes.
- Support versioned embed script or package.
- Support postMessage protocol for status, resize, completion, errors, and optional streaming events.
Non-Functional Requirements
- Runtime must not depend on creator-authenticated APIs.
- Runtime must have error boundaries and fallback states.
- Editor should not be a direct copy of 100+ single-action hooks.
- Component rendering should become registry-based rather than hardcoded dispatch chains.
- Runtime must support future streaming; legacy snapshot-only behavior is not enough.
Implementation Decisions
- Reuse the editor shell pattern and visual interactions.
- Reuse normalized state and pending-change autosave pattern.
- Rebuild undo/redo as part of state management.
- Rebuild property inspector as a first-class panel.
- Convert Houston component catalog into a versioned widget registry.
- Preserve iframe embedding, but modernize host bridge and postMessage protocol.
Testing Decisions
- Browser-test create/edit/publish/share/preview flows.
- Browser-test runtime components including media permissions.
- Unit-test routing engine as a pure function.
- Unit-test autosave batching.
- E2E-test embed widget modes.
Out of Scope
- Pixel-perfect recreation of old styling where it conflicts with usability.
- Keeping the exact old hook structure.