ZNVerse

A registry-first catalog for UI effects—browse and search on the web app, run live demos in an isolated preview runtime, copy source from disk.

Industry: Developer tools · UI motion
Category: Effect catalog · Monorepo
Role: Full Stack Product Engineer — registry contracts, web catalog, preview isolation
Timeline: 2026
Status: MVP shipped (catalog, preview, search, real effects)
Stack: Next.js · React · pnpm · Turborepo · Playwright smoke · registry schema

Executive Overview

ZNVerse solves a maintainer problem: dozens of small effects lived as one-off demos. The MVP gives developers one place to find an effect, see it live, and copy source—without importing a whole motion stack blindly.

Architecture is deliberately loose-coupled: `registry/effects/<slug>` is the single source of truth; `apps/web` reads manifests; `apps/preview` mounts preview entries so effect code never runs inside the marketing app bundle.

MVP scope is disciplined—no accounts, billing, or npm publish in v1—so the shipped surface is browse, detail, sandboxed preview, source API, and search.

Business Problem

Existing workflow

UI experiments accumulate in separate repos and Storybook folders; previewing one effect means cloning, installing, and hoping dependencies match.

Pain points

No canonical index of what exists and how it is categorized.
Running arbitrary effect code inside the main site risks one bad WebGL loop taking down browse.
Copy-paste source drifts from the demo users actually saw.
Adding an effect manually duplicates metadata in multiple places.

Why it matters

A catalog only helps if preview truth and source truth are the same file on disk.

Solution

ZNVerse ships three cooperating apps/packages:

Registry SSOT
Each effect is a folder with effect.json, src/, preview/, and README—validated by `pnpm effect:validate`.
Catalog site
apps/web lists and details effects, serves search/filter, SEO, and read-only source via API routes.
Isolated preview
apps/preview (separate port) mounts live demos; the web app embeds them through a sandboxed iframe with slow-load UX.

Developers preview real motion safely, copy the exact registry source, and maintainers add effects with a scaffold command—not hand-wired routes.

Core Features

Catalog

Browse & detail

Category navigation, effect detail pages, and metadata from validated manifests.

NeedDiscovery is the product—tags alone are not enough.

ValueFind the right interaction pattern quickly.

Search & filter

Toolbar search across manifests with browse tags and letter-grouped navigation.

NeedThe library grows; scrolling does not scale.

ValueReach the right effect without knowing the slug.

Preview & source

Live preview frame

Embeds the preview app in a sandboxed iframe with loading and slow-timeout overlays.

NeedWebGL and R3F demos must not share the catalog app’s React tree.

ValueSafe live demos with graceful degradation.

Source API

GET /api/source returns inline files or repository metadata for copy-out.

NeedThe copied code must match the previewed effect.

ValueDrop-in snippets for production apps.

User Journey

Developer copies an effect

01
Search or browse to an effect detail page.
02
Watch the isolated preview load in the iframe.
03
Copy source from the API-backed panel into a project.

Technical Highlights

Disk loader with schema validation

apps/web/src/lib/registry/index.ts walks registry/effects, parses manifests with @znvserce/registry-schema, and exposes GET /api/effects.

Business valueOne validation pipeline keeps catalog and preview in sync.

Preview origin separation

getPreviewEffectUrl builds URLs against a dedicated preview base; PreviewIframe applies an explicit sandbox string.

Business valueA broken effect cannot crash the main catalog session.

Scaffold + validate toolchain

pnpm effect:create scaffolds folders; effect:validate regenerates preview maps used by the preview app.

Business valueAdding content stays mechanical as the library grows.

Challenges & Solutions

Challenge	Solution
Inlining effect runtime inside apps/web would couple WebGL/R3F crashes to every catalog page.	Dedicated apps/preview service and iframe embedding with sandbox attributes and slow-load UX.
Metadata drifted when manifests lived separately from source folders.	Registry-only SSOT with Zod/schema validation and a single loader path—no parallel JSON databases in MVP.

Tech Stack

Monorepo: pnpm workspaces — apps/web, apps/preview, packages/registry-schema
Catalog: Next.js App Router, server registry loader, SEO routes
Preview: Separate Next app on port 3001, iframe embed from web
Content: registry/effects/* — magnetic-button, spotlight-card, tilt-card, WebGL samples
Quality: Playwright smoke tests, effect:validate script

Project Gallery

Recommended capture order for the case-study gallery.

01Landing — how browse works
02Effect grid / categories
03Detail page with live iframe preview
04Source copy panel

Key Learnings

Architecture

Treat the registry as the product; the marketing site is just a reader—otherwise every new effect becomes a deploy risk.

Scope

MVP wins by saying no to auth and billing until browse → preview → copy is flawless.

Future Improvements

Priority	Improvement	Business value
Medium	More effects migrated from zn-effects demos	One catalog replaces scattered experiments.
Low	Richer media previews for non-live effects	Fallback when sandboxed live preview is not appropriate.

Need a catalog for reusable UI or motion assets?

ZNVerse is a case study in registry SSOT and isolated previews—not a bloated design-system platform. If you want the same pattern for your component library, start a conversation.

Start a conversation

Role

Full Stack Product Engineer

Client

Personal product / developer catalog

Date

2026

Collaborators

Solo build

Next Project

verify-pak-nic

View next