WebVNWrite/tasks/prd-vn-flowchart-editor.md

PRD: Visual Novel Flowchart Editor

Introduction

A web-based visual flowchart editor for authoring visual novels. Writers create branching narratives by placing and connecting nodes on an interactive canvas. The tool supports dialogue, choices, and variables with conditional branching. Projects are saved to a database with user authentication, and flowcharts can be exported to a flexible JSON format compatible with Ren'Py.

The tool is designed for private deployment with invite-only access, allowing a small team of collaborators to each manage their own projects.

Goals

• Provide an intuitive drag-and-drop canvas for creating VN story flowcharts
• Support three node types: dialogue, choice, and variable
• Enable visual connections between nodes with optional conditionals
• Auto-save to LocalStorage for crash recovery
• Persist projects to database with user authentication
• Support invite-only multi-user deployment (admin creates accounts)
• Export flowcharts to flexible Ren'Py-compatible JSON
• Deploy easily to Vercel or Netlify

User Stories

US-001: Project scaffolding and configuration

Description: As a developer, I need the project set up with Next.js, TailwindCSS, and Supabase so that I can build the application.

Acceptance Criteria:

• Initialize Next.js project with TypeScript and App Router
• Install and configure TailwindCSS
• Install Supabase client library (@supabase/supabase-js)
• Create .env.example with required Supabase environment variables
• Basic folder structure: app/, components/, lib/, types/
• Typecheck passes

US-002: Supabase schema for users and projects

Description: As a developer, I need database tables to store users and their projects.

Acceptance Criteria:

• Create profiles table: id (references auth.users), email, display_name, is_admin, created_at
• Create projects table: id, user_id (foreign key to profiles), name, flowchart_data (JSONB), created_at, updated_at
• Set up Row Level Security (RLS): users can only access their own projects
• Admin users can access all profiles (for invite system)
• SQL migration file saved in supabase/migrations/
• Typecheck passes

US-003: Sign up page (invite-only)

Description: As an invited user, I want to create my account using an invite link so that I can access the tool.

Acceptance Criteria:

• /signup page with email and password fields
• Sign up only works with valid Supabase invite token (magic link or pre-created auth user)
• Show error message if signup fails or token invalid
• On success, create profile record and redirect to dashboard
• Typecheck passes
• Verify in browser using dev-browser skill

US-004: Login page

Description: As a user, I want to log in with my email and password so that I can access my projects.

Acceptance Criteria:

• /login page with email and password fields
• Show error message for invalid credentials
• On success, redirect to /dashboard
• Link to "Forgot password" page
• Typecheck passes
• Verify in browser using dev-browser skill

US-005: Logout functionality

Description: As a user, I want to log out so that I can secure my session.

Acceptance Criteria:

• Logout button visible in header/navbar when authenticated
• Clicking logout clears session and redirects to /login
• Typecheck passes
• Verify in browser using dev-browser skill

US-006: Password reset flow

Description: As a user, I want to reset my password if I forget it.

Acceptance Criteria:

• /forgot-password page with email field
• Sends password reset email via Supabase
• Shows confirmation message after sending
• /reset-password page to set new password (handles Supabase token)
• On success, redirect to login with success message
• Typecheck passes
• Verify in browser using dev-browser skill

US-007: Protected routes middleware

Description: As a developer, I need authentication middleware so that only logged-in users can access the app.

Acceptance Criteria:

• Middleware checks Supabase session on protected routes
• Unauthenticated users redirected to /login
• Protected routes: /dashboard, /editor/*
• Public routes: /login, /signup, /forgot-password, /reset-password
• Typecheck passes

US-008: User dashboard - list projects

Description: As a user, I want to see all my projects so that I can choose which one to edit.

Acceptance Criteria:

• /dashboard page shows list of user's projects
• Each project card shows: name, last updated date
• Click project card to open in editor (/editor/[projectId])
• Empty state with message when no projects exist
• Typecheck passes
• Verify in browser using dev-browser skill

US-009: Create new project

Description: As a user, I want to create a new project so that I can start a new flowchart.

Acceptance Criteria:

• "New Project" button on dashboard
• Opens modal to enter project name
• Creates project in database with empty flowchart_data
• Redirects to editor with new project loaded
• Typecheck passes
• Verify in browser using dev-browser skill

US-010: Delete project

Description: As a user, I want to delete a project I no longer need.

Acceptance Criteria:

• Delete button/icon on each project card
• Shows confirmation dialog before deleting
• Deletes project from database
• Removes project from dashboard list
• Typecheck passes
• Verify in browser using dev-browser skill

US-011: Rename project

Description: As a user, I want to rename a project to keep my work organized.

Acceptance Criteria:

• Edit/rename button on project card or in editor header
• Opens modal or inline edit for project name
• Saves new name to database
• Updates display immediately
• Typecheck passes
• Verify in browser using dev-browser skill

US-012: Admin - invite new user

Description: As an admin, I want to invite new users so that collaborators can access the tool.

Acceptance Criteria:

• Admin-only page or section: /admin/invite
• Form to enter email address
• Creates Supabase auth user and sends invite email
• Shows success/error message
• Only accessible by users with is_admin=true
• Typecheck passes
• Verify in browser using dev-browser skill

US-013: Define TypeScript types for flowchart data

Description: As a developer, I need TypeScript types for nodes, connections, and conditions.

Acceptance Criteria:

• DialogueNode type: id, type, position, data: { speaker, text }
• ChoiceNode type: id, type, position, data: { prompt, options: { id, label }[] }
• VariableNode type: id, type, position, data: { variableName, operation, value }
• FlowchartEdge type: id, source, sourceHandle, target, targetHandle, data: { condition? }
• Condition type: variableName, operator, value
• FlowchartData type: { nodes: Node[], edges: Edge[] }
• Types exported from types/flowchart.ts
• Typecheck passes

US-014: Editor page with canvas

Description: As a user, I want an editor page with a canvas where I can build my flowchart.

Acceptance Criteria:

• /editor/[projectId] page loads project from database
• React Flow canvas fills the editor area
• Canvas has grid background
• Header shows project name
• Shows loading state while fetching project
• Shows error if project not found or unauthorized
• Typecheck passes
• Verify in browser using dev-browser skill

US-015: Canvas pan and zoom

Description: As a user, I want to pan and zoom the canvas to navigate large flowcharts.

Acceptance Criteria:

• Click and drag on canvas background to pan
• Mouse wheel to zoom in/out
• Zoom controls (+ / - buttons) in corner
• Fit-to-view button to show all nodes
• Typecheck passes
• Verify in browser using dev-browser skill

US-016: Editor toolbar

Description: As a user, I want a toolbar with actions for adding nodes and saving/exporting.

Acceptance Criteria:

• Toolbar at top or side of editor
• Buttons: Add Dialogue, Add Choice, Add Variable
• Buttons: Save, Export, Import
• Back to Dashboard button/link
• Typecheck passes
• Verify in browser using dev-browser skill

US-017: Add dialogue node

Description: As a user, I want to add dialogue nodes to represent character speech.

Acceptance Criteria:

• Clicking "Add Dialogue" creates node at center of viewport
• Node styled with distinct color (e.g., blue)
• Node displays editable speaker name field
• Node displays editable text field (multi-line)
• Node has one input handle (top) and one output handle (bottom)
• Node can be dragged to reposition
• Typecheck passes
• Verify in browser using dev-browser skill

US-018: Add choice node

Description: As a user, I want to add choice nodes to create branching decisions.

Acceptance Criteria:

• Clicking "Add Choice" creates node at center of viewport
• Node styled with distinct color (e.g., green)
• Node displays editable prompt text field
• Node starts with 2 options, each with editable label
• Each option has its own output handle
• Node has one input handle (top)
• Node can be dragged to reposition
• Typecheck passes
• Verify in browser using dev-browser skill

US-019: Add/remove choice options

Description: As a user, I want to add or remove choice options (2-6 options supported).

Acceptance Criteria:

• "+" button on choice node to add option (max 6)
• "x" button on each option to remove (min 2)
• Adding option creates new output handle
• Removing option deletes connected edge if any
• Typecheck passes
• Verify in browser using dev-browser skill

US-020: Add variable node

Description: As a user, I want to add variable nodes to set or modify story variables.

Acceptance Criteria:

• Clicking "Add Variable" creates node at center of viewport
• Node styled with distinct color (e.g., orange)
• Node displays editable variable name field
• Node displays operation dropdown: set, add, subtract
• Node displays editable numeric value field
• Node has one input handle and one output handle
• Node can be dragged to reposition
• Typecheck passes
• Verify in browser using dev-browser skill

US-021: Connect nodes with edges

Description: As a user, I want to connect nodes with arrows to define story flow.

Acceptance Criteria:

• Drag from output handle to input handle to create edge
• Edges render as smooth bezier curves
• Edges show arrow marker indicating direction
• Edges update position when nodes are moved
• Cannot connect output-to-output or input-to-input
• Typecheck passes
• Verify in browser using dev-browser skill

US-022: Select and delete nodes

Description: As a user, I want to delete nodes to revise my flowchart.

Acceptance Criteria:

• Click node to select it (visual highlight)
• Press Delete key to remove selected node
• Deleting node removes all its connected edges
• Typecheck passes
• Verify in browser using dev-browser skill

US-023: Select and delete edges

Description: As a user, I want to delete connections between nodes.

Acceptance Criteria:

• Click edge to select it (visual highlight)
• Press Delete key to remove selected edge
• Typecheck passes
• Verify in browser using dev-browser skill

US-024: Right-click context menu

Description: As a user, I want a context menu for quick actions.

Acceptance Criteria:

• Right-click on canvas: menu with Add Dialogue, Add Choice, Add Variable
• Node appears at click position
• Right-click on node: menu with Delete option
• Right-click on edge: menu with Delete, Add Condition options
• Clicking elsewhere closes menu
• Typecheck passes
• Verify in browser using dev-browser skill

US-025: Add condition to edge

Description: As a user, I want to add conditions to edges so branches depend on variables.

Acceptance Criteria:

• Double-click edge or use context menu to open condition editor
• Editor modal/popover with: variable name input, operator dropdown (>, <, ==, >=, <=, !=), value input
• Save button applies condition to edge
• Clear/Remove button removes condition
• Typecheck passes
• Verify in browser using dev-browser skill

US-026: Display conditions on edges

Description: As a user, I want to see conditions displayed on edges.

Acceptance Criteria:

• Edges with conditions render as dashed lines
• Condition label displayed on edge (e.g., "score > 5")
• Unconditional edges remain solid lines
• Typecheck passes
• Verify in browser using dev-browser skill

US-027: Auto-save to LocalStorage

Description: As a user, I want my work auto-saved locally so I don't lose progress if the browser crashes.

Acceptance Criteria:

• Flowchart state saved to LocalStorage on every change (debounced, e.g., 1 second)
• LocalStorage key includes project ID to support multiple projects
• On editor load, check LocalStorage for newer data than database
• If local data is newer, prompt user to restore or discard
• Typecheck passes
• Verify in browser using dev-browser skill

US-028: Save project to database

Description: As a user, I want to save my project to the database manually.

Acceptance Criteria:

• "Save" button in toolbar
• Saves current flowchart_data to database
• Shows saving indicator while in progress
• Shows success toast/message on completion
• Clears LocalStorage draft after successful save
• Updates project's updated_at timestamp
• Typecheck passes
• Verify in browser using dev-browser skill

US-029: Export project as .vnflow file

Description: As a user, I want to export my project as a JSON file for backup or sharing.

Acceptance Criteria:

• "Export" button in toolbar (or dropdown)
• Downloads file as [project-name].vnflow
• File contains full flowchart data (nodes + edges)
• JSON is human-readable (pretty-printed)
• Typecheck passes
• Verify in browser using dev-browser skill

US-030: Import project from .vnflow file

Description: As a user, I want to import a .vnflow file to restore or share projects.

Acceptance Criteria:

• "Import" button opens file picker
• Accepts .vnflow or .json files
• Prompts for confirmation if current project has unsaved changes
• Loads flowchart data into current project
• Validates file structure before importing
• Shows error message if file is invalid
• Typecheck passes
• Verify in browser using dev-browser skill

US-031: Export to Ren'Py JSON format

Description: As a user, I want to export my flowchart to Ren'Py-compatible JSON for use in my game.

Acceptance Criteria:

• "Export to Ren'Py" button/option
• Downloads file as [project-name]-renpy.json
• Dialogue nodes export as: { "type": "dialogue", "speaker": "...", "text": "..." }
• Choice nodes export as: { "type": "menu", "prompt": "...", "choices": [{ "label": "...", "next": "..." }] }
• Variable nodes export as: { "type": "variable", "name": "...", "operation": "...", "value": ... }
• Edges with conditions include: "condition": { "variable": "...", "operator": "...", "value": ... }
• Nodes organized into labeled sections based on flow structure
• Output JSON is valid and parseable
• Typecheck passes

US-032: Unsaved changes warning

Description: As a user, I want a warning before losing unsaved work.

Acceptance Criteria:

• Track dirty state when flowchart is modified after last save
• Browser beforeunload shows warning if dirty
• Navigating away (e.g., back to dashboard) shows confirmation modal if dirty
• Dirty state clears after successful save
• Typecheck passes
• Verify in browser using dev-browser skill

US-033: Loading and error states

Description: As a user, I want clear feedback when things are loading or when errors occur.

Acceptance Criteria:

• Loading spinner while fetching project data
• Error message if project fails to load
• Error message if save fails (with retry option)
• Toast notifications for success/error feedback
• Typecheck passes
• Verify in browser using dev-browser skill

Functional Requirements

• FR-1: The system must authenticate users via Supabase Auth with email/password
• FR-2: The system must restrict registration to invite-only (admin creates users)
• FR-3: The system must store user profiles with admin flag for access control
• FR-4: The system must store projects with JSONB flowchart data per user
• FR-5: The system must enforce Row Level Security so users only access their own projects
• FR-6: The system must render an interactive canvas using React Flow
• FR-7: The system must support three node types: dialogue, choice, variable
• FR-8: Dialogue nodes must store: speaker name (optional), text content
• FR-9: Choice nodes must store: prompt text, 2-6 options with labels
• FR-10: Variable nodes must store: variable name, operation (set/add/subtract), numeric value
• FR-11: The system must allow creating edges by dragging between handles
• FR-12: Edges must support optional conditions: variable name, operator, numeric value
• FR-13: The system must auto-save to LocalStorage on changes (debounced)
• FR-14: The system must support manual save to database
• FR-15: The system must support export/import as .vnflow JSON files
• FR-16: The system must export to Ren'Py-compatible JSON format
• FR-17: The system must warn users before losing unsaved changes

Non-Goals (Out of Scope)

• No undo/redo functionality
• No keyboard shortcuts beyond Delete key for deletion
• No real-time collaborative editing
• No cloud auto-sync (manual save only)
• No asset management (images, sprites, audio)
• No preview/playback mode to test the VN
• No auto-layout or alignment algorithms
• No copy/paste of nodes
• No public registration (invite-only)
• No node grouping or sub-flowcharts

Technical Considerations

• Framework: Next.js 14+ with App Router and TypeScript
• Styling: TailwindCSS for utility-first styling
• Canvas: React Flow library for node-based editor
• Auth & Database: Supabase (PostgreSQL + Auth)
• State Management: React state + React Flow's built-in state; consider Zustand if complexity grows
• LocalStorage: Use project ID as key prefix to support multiple drafts
• Deployment: Vercel or Netlify (both support Next.js natively)

Supabase Setup Notes

• Enable Email Auth in Supabase dashboard
• Disable "Enable email confirmations" for simpler invite flow, OR use magic links
• Use Supabase's inviteUserByEmail function for admin invites
• RLS policies must be carefully tested

Ren'Py Export Format (Flexible)

{
  "metadata": {
    "exportedAt": "2024-01-15T10:30:00Z",
    "projectName": "My VN"
  },
  "variables": {
    "affection": 0,
    "seen_intro": false
  },
  "labels": {
    "start": [
      { "type": "dialogue", "speaker": "Alice", "text": "Hello!" },
      { "type": "menu", "prompt": "What do you say?", "choices": [
        { "label": "Hi!", "next": "friendly_path" },
        { "label": "Go away", "next": "rude_path", "condition": { "variable": "confidence", "operator": ">", "value": 5 } }
      ]}
    ],
    "friendly_path": [
      { "type": "variable", "name": "affection", "operation": "add", "value": 1 },
      { "type": "dialogue", "speaker": "Alice", "text": "Nice to meet you!" }
    ]
  }
}

Design Considerations

• Clean, minimal UI with focus on the canvas
• Node colors should clearly differentiate types:
  • Dialogue: Blue
  • Choice: Green
  • Variable: Orange
• Consistent spacing and typography via TailwindCSS
• Responsive layout, but optimized for desktop (canvas editing is difficult on mobile)
• Dark mode support is nice-to-have but not required for MVP

Success Metrics

• User can create a branching story (10+ nodes) and save it
• User can close browser and return to find project intact
• Exported Ren'Py JSON is valid and usable
• Invited collaborators can sign up and manage their own projects
• Application deploys successfully to Vercel/Netlify

Open Questions

• Should we support string variables in addition to numeric?
• Should conditions support AND/OR logic (multiple conditions per edge)?
• What should happen if a user tries to connect to an already-connected input?
• Should we add a "Start" node type to mark the entry point?
• Should project names be unique per user?