--- type: plan status: reference date: 2026-08-28 --- # Inputs — what we're building on Captured 2026-08-28 from three sources rian pointed at, before any easel product code existed. This is a **record of the inputs**, not a decision. It exists so Adi (and any later session) can pick the project up without re-watching the video or reverse-engineering the walkthrough. Sources: - `notes/adi-invision-app-idea.mp4` + `notes/adi-invision-app-idea.transcript.md` - `/srv/apps/hartlingowners/main/static/tour.js` and `/srv/apps/hartlingowners/main/templates/_tour.html` - rian's framing (see `brief.md`) --- ## 1. Adi's prototype — `Proto Preview` A working WordPress plugin on a local install (`protopreviewer.local`), built on an underscores-based theme. Adi's own summary: *"it's like InVision app."* This is the closest thing to a spec that exists, so it's worth reading in detail. ### The data model ``` Project ("Test") — has a client, a share link, assigned stakeholders └── Screen ("Homepage", "About Us") — has a title + a URL slug (/home, /screen-2) └── Option ("Homepage 1 (Modern SaaS)", "Homepage 2 (Dark Cyber AI)") ├── variation title ├── prototype source — an .html file (media library) or a URL └── a design-concept tag/badge ("Clean & High Conversion", "Dark Mode & High Tech", "Initial Exploration") ``` A screen can have one option or several. In the demo, Homepage has 2 options and About Us has 1. Adi in the video: *"one can mean home, for example, and it can have option 1, option 2 … and then another screen, maybe we have only one, so only one option there."* Supporting taxonomies in the admin: **Clients**, **Review Statuses**, **Project Categories**. ### The admin side (us) A "Screen Flows & Design Variations Builder" metabox on the project edit screen — add screen flows, add variation options within each, pick the prototype file, tag it. Sidebar boxes for: the share link ("Direct Client Link", with a copy button and a live/active indicator), publish state, clients, review statuses, categories, and **Team & Email Notifications**. The notification box has an "Enable Email Notifications" toggle (*"sends instant, branded email alerts when someone leaves a review pin or replies"*), a list of **assigned stakeholders** with checkboxes, and a free-text **additional client emails** field. So notification recipients are per-project and mix internal people with plain email addresses. ### The client side **The overview** — the landing view when a client opens the share link. A header (project name, client name, screen count), a stats strip (`SCREEN FLOWS 2 / TOTAL VARIATIONS 3 / REVIEW MODE: Active Project`), the stakeholder notification banner, then a **card per screen**. Each card shows a live thumbnail of the design, the option count, a radio-style list of that screen's options (the selected one highlighted with a checkmark), and an **Open Screen →** button. Hovering a card offers "Zoom In & Review". There's a screen search box. The option list on the card is doing double duty: it's both the option *switcher* and, apparently, the **option-selection / approval** control — which maps directly to rian's "lock in a final direction" goal. **The viewer** — the design rendered full-width and full-height in an iframe, real and scrollable, not a scaled-down image. Adi is explicit that it renders at full height rather than being fit to the window. A slim toolbar across the top carries: - a breadcrumb: project → `Overview` · screen (`Homepage`) · option (`Option 2 — Homepage 2 (Dark C…)`), each a dropdown - prev/next arrows for moving between options - **Comment Mode / Play Mode** toggle, centred - a device/viewport toggle, a comments-panel toggle, and the account avatar - big left/right chevrons overlaid on the design itself for navigation **Play Mode** hides every pin — *"play mode will just hide all the comments"* — with a toast: `Play Mode Active: Pins hidden for clean demo (Press C for Comment Mode)`. **Comment Mode** shows the pins and lets you place new ones. The mode is in the URL (`?page=2&mode=comment`), so a link can open straight into either. **Pins.** Click anywhere on the design to drop a numbered pin. A toast confirms `Comment pin anchored! (Hold pin to drag & reposition)`. The pin opens a thread popover: author, avatar, timestamp, an Open/Resolved state, the comment body, replies, a reply box, and `Drag` / `Resolve` / `Delete Pin` controls. Pins are colour-coded — red/pink for open, green for resolved. The comment count shows on the Comment Mode button. **Feedback Discussion panel** — a right-hand sidebar listing every pin for the current option, filterable **All / Open / Resolved**, each row with the author, timestamp, body, a Resolve button and a **View on Canvas →** link that jumps to the pin. Header reads *"Pins for current layout"* — so pins belong to a specific screen+option, not to the project as a whole. In the demo, threads come from both `adi` (badged **DESIGNER**) and a client persona `Sarah Jenkins` — so the model already anticipates two kinds of participant. ### What Adi flagged as unfinished or undecided Straight from the video, worth carrying forward verbatim: - *"This is still buggy, still not perfect."* - **Auth:** *"this is only me login, but I'm thinking it should be super non-login user."* → clients should be able to comment without an account. This is the single most consequential open question; see `brief.md`. - **Hosting + email:** *"we should put this somewhere in real host thing, maybe without gateway, and then with SMTP email working, for example like in DreamHost — so if someone leaves a comment, we can actually get notification and act right away."* The driver is working outbound mail, not a problem with this server per se. Worth checking what mail we can already send from here before letting it decide the hosting question. --- ## 2. The hartlingowners welcome walkthrough rian's second idea: *"that's another idea for how we might present concepts to clients."* **What it is.** A guided coach-mark tour. On first visit a **welcome panel** greets the user by first name and offers `Next` / `Not now`. Then each step dims the page, **spotlights one element**, and floats a bubble beside it with a title, a short body, `Step N of M`, progress dots, and `Back` / `Next` / `Finish` plus a close button. **Why the implementation is worth reading** (`main/static/tour.js`, 264 lines — it's small and it solves the real problems): - **Steps are pure data**, defined in `_tour.html` as a JSON array on a `data-steps` attribute. Rewriting the tour is editing content, not code. That's exactly the property a per-concept walkthrough would need — each mockup gets its own script. - **Steps can span pages.** A step names a `page`; the tour navigates there and resumes, holding position in `sessionStorage`. A walkthrough could therefore run across several screens of a concept. - **A step can offer several `targets`; the first one actually laid out wins** — so a step still lands when the nav collapses into a hamburger on mobile, instead of spotlighting a zero-size box. - **A step whose target has vanished is skipped, not shown pointing at nothing.** The design changed; the tour degrades quietly. - **Versioned.** `TOUR_VERSION` in `accounts/tour.py`; bumping it re-offers the tour to everyone below that version. A revised concept could re-walk a client through what changed. - **Re-runnable on demand** from the profile menu, and completion is stored server-side per user. - Honours `prefers-reduced-motion`; the bubble is a real `role="dialog"`. **Why it matters here.** The walkthrough is the answer to the "cost the client no time" problem. Rather than opening a client on a design and hoping they know what to look at, we can walk them through it — *"notice the booking bar sits above the fold"*, *"this section replaces the old testimonials block"* — three or four beats, then hand them the comment tool. It's the difference between sending a design and **presenting** one, without anyone having to be on a call. It also composes with Adi's Play/Comment modes rather than competing: the walkthrough is arguably a third mode, or the scripted opening of Play Mode. --- ## 3. Where easel actually is Bare BW-app shell. `main/app/routers/` is still the sample scaffold; no product routes, no models, no client-facing anything. The account system (sign-in, levels, invites, View As, access matrix) is in place and passing its conformance pack. So nothing here has to be worked around — the product is entirely unwritten, and the questions in `brief.md` are all still open.