weseek__growi/.kiro/specs/presentation/research.md

Research & Design Decisions

Summary

• Feature: optimize-presentation
• Discovery Scope: Extension
• Key Findings:
  • GrowiSlides imports growi-marpit.ts only for CSS extraction (marpit.render('')) and a string constant — no Marp rendering is performed
  • growi-marpit.ts instantiates new Marp(...) at module scope, pulling in @marp-team/marp-core (~524KB) and @marp-team/marpit (~372KB) unconditionally
  • All consumers of Slides.tsx are already behind SSR-disabled dynamic boundaries (next/dynamic, useLazyLoader), making React.lazy safe to use within the package

Research Log

GrowiSlides dependency on growi-marpit.ts

• Context: Investigating why GrowiSlides requires Marp at all
• Sources Consulted: packages/presentation/src/client/components/GrowiSlides.tsx, packages/presentation/src/client/services/growi-marpit.ts
• Findings:
  • GrowiSlides imports MARP_CONTAINER_CLASS_NAME (string 'marpit'), presentationMarpit, slideMarpit
  • Usage: const { css } = marpit.render(''); — renders empty string to extract base theme CSS
  • The CSS output is deterministic (same Marp config → same CSS every time)
  • MARP_CONTAINER_CLASS_NAME is a plain string constant co-located with heavy Marp code
• Implications: GrowiSlides can be fully decoupled by pre-extracting the CSS and moving the constant

Vite build with preserveModules and React.lazy

• Context: Verifying that React.lazy dynamic import works correctly in the package's Vite build output
• Sources Consulted: packages/presentation/vite.config.ts
• Findings:
  • Build uses preserveModules: true with preserveModulesRoot: 'src' — each source file → separate output module
  • nodeExternals({ devDeps: true }) externalizes @marp-team/marp-core and @marp-team/marpit
  • Dynamic import('./MarpSlides') in source will produce dynamic import('./MarpSlides.js') in output
  • Next.js (app bundler) handles code-splitting of the externalized Marp packages into async chunks
• Implications: React.lazy in Slides.tsx will produce the correct dynamic import boundary in the build output

SSR safety of React.lazy

• Context: React.lazy does not support SSR in React 18; need to verify all render paths are client-only
• Sources Consulted: Consumer components in apps/app
• Findings:
  • PagePresentationModal: useLazyLoader → client-only
  • Presentation wrapper: next/dynamic({ ssr: false })
  • SlideRenderer: next/dynamic({ ssr: false }) in PageView.tsx
  • No SSR path exists for Slides.tsx
• Implications: React.lazy is safe; no need for next/dynamic in the shared package

CSS extraction approach

• Context: Evaluating how to pre-extract the Marp base CSS
• Sources Consulted: growi-marpit.ts, package.json scripts, existing build:vendor-styles pattern
• Findings:
  • slideMarpit.render('') and presentationMarpit.render('') produce deterministic CSS strings
  • CSS only changes when @marp-team/marp-core is upgraded or Marp options change
  • The package already has a build:vendor-styles script pattern for pre-building CSS assets
  • tsx is not available in the workspace; extraction script must use plain Node.js (.mjs)
• Implications: An .mjs extraction script with dynamic imports from the built package or direct Marp usage is the simplest approach

Design Decisions

Decision: Pre-extracted CSS constants vs runtime generation

• Context: GrowiSlides needs Marp theme CSS but should not load Marp runtime
• Alternatives Considered:
  1. Dynamic import of growi-marpit in GrowiSlides — adds async complexity for a static value
  2. Pre-extract CSS at build time as string constants — zero runtime cost
  3. CSS file extracted to dist — requires additional CSS import handling
• Selected Approach: Pre-extract CSS as TypeScript string constants in consts/marpit-base-css.ts
• Rationale: The CSS is deterministic; generating it at build time eliminates runtime overhead entirely. TypeScript constants integrate seamlessly with existing import patterns.
• Trade-offs: Requires regeneration on Marp version upgrade (mitigated by pre:build:src script)
• Follow-up: Verify CSS output matches runtime generation; commit generated file for dev mode

Decision: React.lazy vs next/dynamic for MarpSlides

• Context: Need dynamic import boundary for MarpSlides within the shared @growi/presentation package
• Alternatives Considered:
  1. next/dynamic — Next.js-specific, couples package to framework
  2. React.lazy + Suspense — standard React, works with any bundler
• Selected Approach: React.lazy + Suspense
• Rationale: Although the package already uses next/head, React.lazy is the standard React pattern for code-splitting and avoids further Next.js coupling. All consumer paths already disable SSR, so React.lazy's SSR limitation is irrelevant.
• Trade-offs: Requires <Suspense> wrapper; fallback UI is visible during chunk load
• Follow-up: Verify chunk splitting in Next.js production build

Decision: Shared constants module for MARP_CONTAINER_CLASS_NAME

• Context: MARP_CONTAINER_CLASS_NAME is defined in growi-marpit.ts but needed by GrowiSlides without Marp dependency
• Selected Approach: Move to consts/index.ts (existing shared constants module)
• Rationale: The constant has no dependency on Marp; co-locating it with Marp code creates an unnecessary transitive import

Risks & Mitigations

• CSS drift on Marp upgrade: Pre-extracted CSS may become stale → pre:build:src script auto-regenerates before every build
• Suspense flash on Marp load: Brief loading indicator when MarpSlides loads → Masked by parent next/dynamic loading spinner in most paths
• Build script compatibility: .mjs script must work in CI and local dev → Use standard Node.js ESM with no external tooling dependencies