mbt-puzzle-preview-lb

puzzle-view is the source package for mbt-puzzle-preview-lb. It exports the core puzzle runtime and web-ready wrappers used by MOBA Trainer web surfaces.

Main Exports

PuzzlePreview

Default export. This is the raw puzzle runtime.

Use it when the host application fully owns the surrounding viewport, fullscreen behavior, orientation handling, and layout chrome.

import PuzzlePreview from 'mbt-puzzle-preview-lb';

<PuzzlePreview
  puzzle={puzzle}
  onQuitPuzzle={handleQuitPuzzle}
  onFinishPuzzle={handleFinishPuzzle}
  isNextPuzzleAvailable={false}
  isWebVersion
  openExternalLink={handleOpenExternalLink}
/>;

PuzzlePreviewWebEmbed

Named export. This is the recommended component for web and Electron consumers. It renders the same puzzle runtime, but adds reusable browser/mobile embedding behavior around it.

Desktop and Electron behavior is pass-through by default: no body lock, no fixed layout, no orientation screen, and no mobile resizing unless a real mobile browser is detected.

import { PuzzlePreviewWebEmbed } from 'mbt-puzzle-preview-lb';

<PuzzlePreviewWebEmbed
  puzzle={puzzle}
  onQuitPuzzle={handleQuitPuzzle}
  onFinishPuzzle={handleFinishPuzzle}
  isNextPuzzleAvailable={false}
  isWebVersion
  openExternalLink={handleOpenExternalLink}
/>;

On mobile browsers, PuzzlePreviewWebEmbed handles:

• portrait orientation warning
• landscape immersive layout
• visible viewport height via visualViewport
• safe-area padding
• 16:9 stage fitting
• body scroll locking while immersive
• inline video behavior through the underlying puzzle runtime

PuzzlePreviewWebEmbed Props

PuzzlePreviewWebEmbed accepts all PuzzlePreview props plus:

type TPuzzlePreviewWebEmbedProps = TProps & {
  mobileImmersive?: 'auto' | 'off' | 'force';
  onImmersiveChange?: (isImmersive: boolean) => void;
  renderPortraitWarning?: () => React.ReactNode;
  renderLoading?: () => React.ReactNode;
  className?: string;
  stageClassName?: string;
};

Defaults:

• mobileImmersive = 'auto'
• renderPortraitWarning uses the built-in rotate-device screen
• renderLoading uses the built-in loading state

Use mobileImmersive="off" if the host wants to fully control mobile layout. Use mobileImmersive="force" only for testing or a custom kiosk-style flow.

Host Chrome Integration

The library does not know how a host app implements navbars, footers, cookie banners, or route shells. Use onImmersiveChange to bridge that part:

<PuzzlePreviewWebEmbed
  puzzle={puzzle}
  onQuitPuzzle={handleQuitPuzzle}
  onFinishPuzzle={handleFinishPuzzle}
  isNextPuzzleAvailable={false}
  isWebVersion
  onImmersiveChange={setHostChromeHidden}
/>;

When isImmersive is true, the host should hide UI that would cover the puzzle. When it becomes false, the host should restore its normal shell.

Electron Usage

For Electron, use PuzzlePreviewWebEmbed with default props. Electron is treated as desktop by default, even when the window is small, so existing desktop puzzle behavior stays unchanged.

<PuzzlePreviewWebEmbed
  puzzle={puzzle}
  onQuitPuzzle={handleQuitPuzzle}
  onFinishPuzzle={handleFinishPuzzle}
  isNextPuzzleAvailable={false}
/>;

Local Development With web

Run the library build watcher in one terminal:

cd /Users/levpotapov/Documents/projects/puzzle-view-fixing/puzzle-view
npm run watch

Run the web app against the linked local library in another terminal:

cd /Users/levpotapov/Documents/projects/puzzle-view-fixing/web
npm run dev:local-lib

In dev:local-lib, the web dev server watches the linked library output and restarts Next automatically when puzzle-view/dist/index.js changes.

If local linking has not been set up yet, run this once:

cd /Users/levpotapov/Documents/projects/puzzle-view-fixing/puzzle-view
npm run link:local-lib

cd /Users/levpotapov/Documents/projects/puzzle-view-fixing/web
npm run link:local-lib

Then open the /puzzle-of-the-day URL printed by the web dev server.

Verification

Before publishing or handing off changes that affect web, run:

cd /Users/levpotapov/Documents/projects/puzzle-view-fixing/puzzle-view
npm run build

cd /Users/levpotapov/Documents/projects/puzzle-view-fixing/web
npm run lint
npm run type-check
npm run build