External/open-design
1
0
Fork 0
mirror of https://github.com/nexu-io/open-design.git synced 2026-10-27 09:51:12 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
codex/discovery-scope-fix
open-design/docs/handoffs/slides-project-experience-handoff.md
T
Tom HuangGitHubfree666799Claude Opus 4.8
 bc6a246c65 feat(slides): enhance deck project experience (#5083) 
* feat(deck): enhance slide deck functionality with speaker notes and navigation improvements

- Added a switch for including speaker notes in slide decks, defaulting to true.
- Updated keyboard navigation to include 'R' for resetting to the first slide.
- Implemented click navigation for half-slide transitions.
- Enhanced the deck framework to support hidden programmatic prev/next controls.
- Improved handling of file inputs in question forms to support file submissions.

This update aims to improve user experience in creating and presenting slide decks, ensuring better accessibility and functionality.

* feat(artifacts): enforce semantic naming for user-facing deliverables

- Updated guidelines to require semantic filenames derived from user briefs for new artifacts, moving away from defaulting to `index.html`.
- Enhanced documentation to clarify naming conventions for HTML files, emphasizing the use of descriptive names like `investor-pitch-deck.html`.
- Adjusted prompts and hints across the system to reflect these changes, ensuring consistency in user-facing outputs.
- Improved test coverage to validate the new naming conventions and ensure proper implementation in various contexts.

This update aims to enhance clarity and usability in project file management, promoting better organization and user experience.

* feat(file-viewer): enhance speaker notes display and improve file workspace functionality

- Updated the speaker notes section to include a styled placeholder for empty notes, improving user experience.
- Changed the icon in the file workspace from "slides" to "panel-left" for better clarity.
- Introduced new sub-category filtering options in the file workspace, enhancing organization and navigation.
- Improved styling for the page creator search input and added visual feedback for loading states.

These changes aim to enhance usability and visual consistency across the file viewer and workspace components.

* test(web): align workspace tests with pages switcher

* test(e2e): open design files through pages menu

* fix(deck): keep source mode reachable

* fix(workspace): restore uploaded file tabs

* feat(deck-thumbnail): implement virtualized thumbnail rail for improved performance

- Introduced a new `DeckThumbnailRail` component to optimize the rendering of deck thumbnails, reducing memory usage and improving load times.
- Enhanced the `FileViewer` to integrate the new thumbnail rail, allowing for lazy loading of thumbnails based on viewport visibility.
- Added tests for the `DeckThumbnailRail` to ensure correct functionality and caching behavior.
- Updated styles for better visual consistency and performance during thumbnail rendering.

These changes aim to enhance user experience by providing a smoother and more efficient way to navigate through deck slides.

* feat(deck): enhance deck rendering with thumbnail support and keyboard shortcuts

- Integrated `DeckSlideThumbnail` for rendering individual slides in a shadow root, improving performance and reducing main-thread load.
- Updated `DeckThumbnailRail` to utilize the new thumbnail component, allowing for efficient slide navigation.
- Implemented keyboard shortcuts for deck navigation, enhancing user experience during presentations.
- Added tests for `buildDeckRenderInput` to ensure proper functionality of the deck stage fallback.
- Improved styling for loading states in the viewer, providing a smoother visual experience.

These changes aim to optimize the deck viewing experience by reducing resource consumption and enhancing interactivity.

* feat(deck): improve thumbnail loading and speaker notes editing experience

- Refactored `DeckSlideThumbnail` to enhance loading states with a new shimmer effect, improving visual feedback during thumbnail rendering.
- Updated `DeckThumbnailRail` to manage loading states for thumbnails, ensuring a smoother user experience.
- Simplified the speaker notes editing interface by removing the toggle switch, allowing direct editing from the notes body.
- Enhanced accessibility by adding roles and focus states to speaker notes elements.
- Added tests to verify the new loading states and speaker notes functionality.

These changes aim to optimize the user experience in deck navigation and speaker notes management, providing a more intuitive and responsive interface.

* feat(file-viewer): enhance version export functionality and speaker notes interaction

- Introduced new export options for file versions, including PDF and image formats, improving the ability to download and share content.
- Implemented a streamlined process for exporting version content, with progress indicators and error handling for a better user experience.
- Enhanced speaker notes editing by refining event handling to prevent unintended focus shifts, ensuring a smoother editing experience.
- Updated styles for improved visual consistency in the file version download interface.
- Added tests to verify the functionality of version exports and speaker notes interactions.

These changes aim to optimize the file viewer's usability and enhance the overall experience when managing and exporting project files.

* fix(web): polish export menus and creator filters

* fix(file-viewer): fall back to preview exports

* test(file-viewer): cover version export fallbacks

* test(file-viewer): assert loading skeleton by role

* fix(file-viewer): restore html source mode affordance

* fix(file-viewer): capture full version fallback snapshots

* docs: trim slides handoff eof

* test(exports): cover full preview snapshot requests

* test(file-viewer): account for snapshot options arg

* refactor(file-viewer, file-workspace): streamline export functions and enhance page creator dialog visibility

* test(file-workspace): enhance slide template creation and mock plugin responses

* feat(export): add support for versioned exports and enhance HTML export functionality

* feat(export): implement versioned export support across multiple formats and enhance related tests

* feat(file-viewer): enhance manual edit functionality with commit sequence tracking and add test for inline text session saving

* style(speaker-notes): update filmstrip and thumb-frame styles for improved responsiveness and add corresponding tests

* feat(file-viewer): enhance comment composer functionality with portal metrics and improve draw toolbar layout for mobile views

* feat(analytics): track slide deck viewing experience

Add analytics for the new deck/slides experience introduced in this PR:
the deck viewer surface, in-deck slide navigation, thumbnail rail, and
speaker-notes authoring. Presentation entry stays on the existing
present_popover click to avoid double-counting.

- contracts: DeckViewerSurfaceViewProps (surface_view),
  DeckViewerClickProps (ui_click), SpeakerNotesSaveResultProps
  (new speaker_notes_save_result event), wired into the event unions.
- web: track* wrappers + fire helpers in FileViewer — deck_viewer
  surface_view on deck mount, slide_prev/next/reset, thumbnail_select,
  thumbnail_rail_toggle (expand/collapse), speaker_notes_edit, and
  speaker_notes_save_result (preview + presenter surfaces).
- tests: deck analytics suite asserting the emitted (event, props) pairs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(file-viewer, file-workspace): enhance export toast functionality and improve localization for page creation

* feat(home-view, plugins-home-section, agent-skill): update default facet preference, enhance category selection handling, and improve localization support

- Set `preferDefaultFacet` to true in HomeView component for better user experience.
- Introduced `handlePickCategory` function in PluginsHomeSection to manage category selection based on card layout visibility.
- Updated PRIMARY_CATEGORIES to reflect the new order and added localization for titles and descriptions in adaptAgentSkill.
- Enhanced tests to verify the correct handling of display copy and tags from SKILL frontmatter.

* feat(plugins-home, file-workspace): introduce commercial category labels and enhance deck handling

- Added a new module for resolving and localizing commercial category labels for plugins.
- Updated the FileWorkspace and PluginCard components to display the commercial category label on deck cards.
- Enhanced the PageCreatorPresetFrame to adjust frame classes based on deck presets.
- Refactored subcategory handling in facets to align with the new commercial category taxonomy.
- Improved localization support for new category labels across multiple languages.

* feat(deck-preview): implement deck preview scaling and enhance home hero layout

- Introduced `useDeckPreviewScale` hook to manage scaling of deck previews within a fixed 1280×720 logical viewport, ensuring proportional rendering across various templates.
- Updated `FileWorkspace`, `HomeHero`, and `PluginCard` components to utilize the new scaling functionality for improved visual consistency.
- Enhanced the layout of the home hero section to accommodate new subtype chips and descriptions, including a "More" dropdown for overflow handling.
- Improved localization support for new UI elements across multiple languages.

* fix(PreviewModal): clarify sidebar prop documentation and update test description

- Updated the documentation for the `PreviewSidebar` interface to specify that the sidebar's stage-edge handles are not shown when the sidebar prop is absent.
- Modified the test suite description for `PreviewModal` to be more concise and relevant.

* test(e2e): select prototype visual card

---------

Co-authored-by: free666799 <293857035+free666799@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-10 09:41:47 +00:00

14 KiB
Raw Permalink Blame History

Slides project experience handoff

Date: 2026-07-02 Repo: /Users/pftom/.superset/worktrees/d3aab1a3-c696-403f-9692-7e5bc2dfa1f3/jumpy-centipede

This handoff summarizes the full user feedback thread for the Slides / PPT HTML project experience. The goal is to give the next agent enough context to continue product polish without re-deriving the requirements from screenshots.

Product Goal

Slides are a distinct project type, not just generic HTML preview. A slide-deck HTML file should get a slide-specific viewing, presenting, speaker-notes, thumbnail, and generation flow.

Core principle:

  • Deck controls should be programmatic host/template chrome, not bespoke per generated deck.
  • Fullscreen and new-tab presentation should feel like a real presentation surface, not an editable preview with visible app controls.
  • Speaker notes are first-class per slide: generated when requested, shown in preview/presenter mode, editable in place, and saved per page.
  • Thumbnail navigation, current page, presenter notes, and prev/next preview state should all stay synchronized.

User Feedback Timeline

1. Define slides as a unique project type

User asked to focus first on the slides scene and described the expected boundary:

  • Slides HTML has slide preview with programmatic open/focus controls.
  • Left thumbnails can highlight the current slide and switch slides.
  • Speaker notes and page count are explicit, editable, and previewable.
  • Present mode supports normal fullscreen and speaker mode.
  • Presenter view has timer, pause/reset, current page, notes edit, previous/next preview.
  • Generation confirmation form should ask whether speaker notes are needed.
  • If requested, every generated slide should get speaker notes.

Images:

  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-dZhJSs.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-k6B77f.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-gIwCnU.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-6o0RlS.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-25Uioa.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-XGBFU5.png

2. Deck navigation chrome should be host/template-owned

User clarified that page-turn controls should not be generated dynamically by each deck body. They should come from the PPT skills HTML template or host layer. The same deck should work consistently across project preview, fullscreen, new tab, and presenter mode.

Specific asks:

  • Hide unnecessary page-turn button overlays in presentation surfaces.
  • Reset should return to slide 1.
  • In project preview, do not show duplicate navigation if top toolbar/thumbnails already provide navigation.
  • Add thumbnail expand/collapse and thumbnail navigation.
  • Navigation control should be small, polished, hover-revealed, and fade away after focus/mouse inactivity.

Images:

  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-NhYkDS.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-HzSIVF.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-F7yJEs.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-jJL97r.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-Va33Fu.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-2NWQ9t.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-zBAucz.png

3. Speaker notes panel requirements

User specified the desired speaker-notes behavior:

  • Edit control is a switch button.
  • Title row and notes body are separated by a line.
  • Notes region should be taller and visually cleaner.
  • Editing happens in place.
  • On blur, editing should close and auto-save.
  • Notes are saved per slide.
  • Presenter mode notes text was too large and needed to be reduced.
  • Avoid having two different note-edit states.

Images:

  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-y6XSR3.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-M8xXd0.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-4KJkAx.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-5Abte2.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-RTxHk4.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-Osr8jX.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-4arGmf.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-t2BUC1.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-JN82jm.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-umiUzq.png

4. Presentation and fullscreen behavior

User clarified the presentation modes:

  • Presenter view should not show extra page-turn overlays on the slide preview itself.
  • On first slide in presenter view, show only Next preview; do not show Previous.
  • From second slide onward, show both Previous and Next previews.
  • Timer, pause, and reset must work; reset returns to slide 1.
  • Main presentation/fullscreen should fill the full window and cover the app chrome.
  • Esc exits fullscreen.
  • In fullscreen and new-tab presentation, do not show exit button or page-turn controls.
  • Navigation should happen through keyboard and click zones:
    • Left arrow / click left half goes previous.
    • Right arrow / click right half goes next.
  • Fullscreen can show a toast such as "Press Esc to exit".

Images:

  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-OWTXoU.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-DOiMc1.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-Tra8Xt.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-UBdFqC.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-InBoHO.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-eZXB1z.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-Ep6DDk.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-IOW1Me.png

5. Generation and template integration

User asked for generation/template changes:

  • The PPT generation question form needs a field asking whether speaker notes are needed.
  • The blank Slide deck template in the create-page modal should use the same unified base HTML capability, including:
    • programmatic navigation,
    • slide recognition,
    • thumbnails,
    • speaker notes,
    • presenter/fullscreen support.
  • The preview/code toggle should be removed for this experience so users perceive the result as a real design, not code.

Images:

  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-ckmKXI.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-hM5kJF.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-nuY6sn.png

6. Late bug reports after implementation

User reported remaining gaps:

  • Thumbnail expand/collapse control was in the wrong place. It should be in the top toolbar row; once collapsed, the internal rail button disappears and cannot reopen the rail.
  • Presenter view previous/next preview did not update as slides changed. On initialization, first slide should not show Previous.
  • Speaker notes edit switch double-triggered and could not toggle.
  • Preview fullscreen could not exit via Esc.

Images:

  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-L7mOyP.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-vkdvDp.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-81E3Am.png
  • /var/folders/5j/fb63hyxj11nblszkmd3vfcjm0000gn/T/codex-clipboard-Ethkx4.png

Current Implementation State

The latest patch in this workspace addressed the late bugs above.

Changed areas:

  • apps/web/src/components/FileViewer.tsx

    • Moved deck thumbnail expand/collapse button into the top viewer toolbar.
    • Kept thumbnail toggle available after the rail is collapsed.
    • Replaced host speaker-note edit label/input with a single switch button.
    • Added in-tab presentation handling for od:present-escape messages from the active iframe.
    • Built per-slide presenter preview HTML so Previous/Next can stay synchronized.

  • apps/web/src/runtime/speaker-notes.ts

    • Added optional previewHtmlBySlide.
    • Presenter view uses the correct per-slide frame for current, previous, and next previews.
    • Presenter edit control is a single button role="switch".
    • Edit blur saves and closes.
    • Slide changes clear active editing.

  • apps/web/src/runtime/srcdoc.ts

    • Injected Escape forwarding from deck iframes to the host via od:present-escape.
    • Covers both framework decks and legacy/non-framework deck HTML.

  • apps/web/src/styles/viewer/theater.css

    • Styled top-toolbar thumbnail toggle.
    • Updated speaker-notes switch styling for button-based switch.
    • Reduced unnecessary rail top padding after moving the toggle.

  • apps/web/src/styles/viewer/composio.css

    • Kept .present-exit hidden so fullscreen/in-tab presentation does not show an exit button.

  • Tests updated:

    • apps/web/tests/runtime/speaker-notes.test.ts
    • apps/web/tests/runtime/srcdoc-deck-bridge-framework-deck.test.ts
    • apps/web/tests/components/FileViewer.test.tsx

Validation Already Run

Run with Node 24:

PATH=/Users/pftom/.nvm/versions/node/v24.15.0/bin:$PATH pnpm --filter @open-design/web typecheck
PATH=/Users/pftom/.nvm/versions/node/v24.15.0/bin:$PATH pnpm --filter @open-design/web exec vitest run -c vitest.config.ts tests/runtime/speaker-notes.test.ts tests/runtime/srcdoc-deck-bridge-framework-deck.test.ts tests/components/FileViewer.test.tsx
PATH=/Users/pftom/.nvm/versions/node/v24.15.0/bin:$PATH pnpm guard
PATH=/Users/pftom/.nvm/versions/node/v24.15.0/bin:$PATH pnpm typecheck
git diff --check

All passed. The full typecheck emitted existing Astro landing-page hints/warnings but exited successfully.

Manual UI verification was not completed after the last fixes because the machine showed a macOS out-of-application-memory warning, with Electron/Superset processes using unusually high memory. Before heavy browser QA, free memory or restart the relevant app runtime.

Acceptance Checklist for Next Agent

Use this checklist before considering the slides work complete.

Deck detection and preview

  • Opening a slide-deck HTML shows slide-specific chrome.
  • The current slide index is read from URL/hash and persists across reloads where applicable.
  • Top toolbar page count/navigation works.
  • Left thumbnail rail shows slide thumbnails and highlights the current slide.
  • Thumbnail clicks switch the slide.
  • Thumbnail rail can be collapsed and reopened from the top toolbar.
  • Collapsed rail does not leave an orphan internal toggle button.

Host navigation chrome

  • In normal preview, deck navigation chrome is small and polished.
  • Navigation appears on hover/focus and fades after inactivity.
  • It does not overlap critical slide content more than necessary.
  • Reset returns to slide 1.
  • Duplicate deck-body controls are not shown in preview/presentation surfaces.

Speaker notes in preview

  • Speaker notes panel shows SPEAKER NOTES plus Slide X / N.
  • Header and notes body have a clear separator line.
  • Notes area is tall enough to be useful.
  • Edit is a switch button, not a label-wrapped checkbox that can double-toggle.
  • Clicking Edit changes the same region into editable state.
  • Blurring the text area auto-saves and exits editing.
  • Switching slides saves notes per slide and loads the correct notes for the new slide.

Presenter view

  • Presenter window opens with timer, pause, reset, current page, current slide preview, notes, and adjacent previews.
  • Timer counts up and pause freezes/resumes it.
  • Reset returns to slide 1.
  • First slide shows only Next preview, no Previous preview.
  • Middle slides show both Previous and Next previews.
  • Last slide shows only Previous preview, no Next preview.
  • Previous/Next preview thumbnails update every time the slide changes.
  • Speaker notes text size is readable but not oversized.
  • Presenter notes edit switch does not double-trigger.
  • Presenter note edits save by slide.

Fullscreen and new tab

  • Fullscreen presentation covers the app chrome and browser tab area when native fullscreen is granted.
  • No exit button is shown in fullscreen.
  • No visible page-turn button overlay is shown in fullscreen.
  • Esc exits fullscreen/presentation.
  • Fullscreen shows only a minimal toast such as Press Esc to exit when appropriate.
  • Click left half navigates previous; click right half navigates next.
  • Left/right keyboard navigation works.
  • New tab presentation follows the same no-visible-controls navigation model.

Generation and templates

  • The question form for slide generation asks whether speaker notes are needed.
  • If notes are requested, generated deck pages include per-slide speaker notes.
  • The blank Slide deck template in create-page uses the same slide base capability.
  • Preview/Code segmented control is not exposed in the user-facing design preview path if the intent is to present it as a real design artifact.

High-Risk Areas to Recheck

  • Iframe source filtering: od:present-escape should only close the active deck presentation iframe, not unrelated iframes.
  • Notes save semantics: preserve existing persistence pipeline and avoid writing only to local component state.
  • Presenter window sync: if host and popup both navigate, ensure they do not race or drift.
  • Memory usage: thumbnails and presenter preview frames can be expensive for large decks. Avoid keeping many live iframes mounted if not necessary.
  • Cross-mode consistency: preview, presenter, fullscreen, and new-tab modes should use one shared slide-state model.
  • Template integration: generated decks and blank slide templates must use the same base script contract, otherwise behavior will regress for newly created files.

Suggested Next Optimization Pass

  1. Start the app with a clean memory state and manually walk the acceptance checklist.
  2. Record short screenshots/GIFs for:
    • thumbnail rail expand/collapse,
    • speaker note edit/blur/save,
    • presenter first/middle/last slide previews,
    • fullscreen Esc exit,
    • new-tab click-zone navigation.
  3. Add or extend an e2e test if the repository already has a stable deck-preview Playwright harness.
  4. Profile memory if Electron/Superset/Chrome still grow unexpectedly when opening presenter/fullscreen views.
  5. Confirm generation prompts and the blank slide-deck template both produce/use the unified slide base capability.
Reference in New Issue View Git Blame Copy Permalink