Voodoo MCP Server

cliphou.se

cliphou.se is a gallery of AI-generated Remotion and HyperFrames videos. Users can find videos with faceted filters, edit text and colors inline, and keep private starred collections through Google sign-in. Each template is locked to one engine, while the editor, agent handoff, sharing, and export flows use the same contract.

The Firebase-hosted site is at https://cliphouse-app.web.app/. The production domain is https://cliphou.se/ after the Loopia DNS cutover. Pushes to main deploy through keyless GitHub Actions. The previous https://sunmer.github.io/voodoo/ address is retained.

See deployment.md for configuration and the Loopia cutover checklist. See sharing.md for saved video links, rendering, and the pending paid-service activation. See agents.md for agent specs, handoff links, source packages, and template versions.

Run

npm install
npm run dev                 # http://localhost:5180/voodoo/
npm run studio              # Remotion Studio
node scripts/previews.mjs   # rebuild gallery posters and MP4 loops in public/previews
npm run previews:hyperframes # rebuild HyperFrames posters and loops

Accounts And Analytics

Use .env.example to configure the public Firebase web settings and GA4 measurement ID. Never put a service-account key or OAuth client secret in a VITE_ variable. Missing configuration leaves browsing and editing available but does not pretend to save bookmarks.

Stars use users/{uid}/bookmarks/{variantId} in Firestore. Rules restrict all access to the account owner and validate the payload. Sign-out clears the visible collection. Existing voodoo: local-storage keys are intentionally retained so the rebrand does not discard edits on the same origin. Local edits cannot automatically transfer from the GitHub Pages origin to cliphou.se.

Analytics loads automatically when configured, without a consent banner. The site sends explicit hash-route page views and a small set of actions, without account IDs or editable text. Disable automatic enhanced measurement on the GA4 web stream to avoid duplicate page views or automatic collection. Review consent obligations before public launch; this configuration is not a compliance guarantee.

Google pop-ups can be blocked inside social apps. The error state permits retrying in a regular browser. Native iPhone sign-in still needs a real-device acceptance test before launch.

Taxonomy

The catalog uses three levels:

• Template: code in src/videos/<id>/. It sets the scenes, motion, and timing. Its technical facts, such as size, fps, duration, scenes, and motion, are in meta.ts.
• Variant: an entry in manifest.json. It is a template plus preset text and theme values, plus curated facets: purpose, style, energy, and keywords. Users browse variants.
• Remix: a user's edit of a variant. Save keeps a private account draft. Publishing saves an immutable composition and JPEG thumbnail behind a share link; the website animates the saved composition without a rendered MP4.

Facets come from different sources:

Shared Roles

All templates use the text roles in src/videos/vocab.ts: brand, headline, subhead, point1 to point3, and cta. All templates also use the same five theme roles. Because of this, the brand kit can apply one set of values to every video. Each card then shows one static Remotion frame with the user's text, but only while the card is on screen.

Content roles hold text that belongs to one video, so the brand kit never fills them. quote (140 characters) and author (40 characters) are content roles for testimonials. Countdown digits come from the timeline, not from a text role. Image logo upload is not part of the contract yet; Wordmark animates the brand name as text.

Add A Template

HyperFrames templates live in src/hyperframes/<id>/index.html. Use the shared __BASE_CSS__, __BASE_JS__, and __ASSET_BASE__ placeholders, mark editable text with data-text-role and data-var-text, and register the template ID in src/videos/engine.ts. Their source packages are native HyperFrames projects with variables.json; run npx hyperframes check on an extracted package before publishing.

1. Generate a composition that reads all text from props.texts with shared roles, and all color from props.theme.
2. Add meta.ts with its scenes. Each scene has from, duration, focus, and roles. Map the components to scenes in the same order with SceneTrack from src/videos/shared/scenes.tsx. Each role must be visible at its scene's midpoint because inline tests seek there.
3. Add the schema with textsSchema([...roles]) and themeSchema, and register the template in src/videos/registry.ts and src/videos/meta.ts.
4. Add the template and one visible variant to manifest.json. Keep retired variants with "hidden": true so existing links still open. Then run node scripts/previews.mjs.
5. Mark each editable text group with data-text-role="headline" (or the matching shared role). Use display: contents on additional wrappers to preserve the composition layout. Tag the copy itself, not decorative labels or whole scenes.
6. Add the schema to src/videos/schemas.ts. Run npm run sources to publish its source package and version. Run it again after any template or shared helper change.

Editor

• Mobile uses a screen-filling stage with overlay controls. Landscape compositions fill the phone when it rotates to landscape. The expand button requests native fullscreen and landscape orientation where supported; otherwise it uses the browser viewport. Desktop keeps a contained preview.
• Click or tap visible text to pause and edit that role in place. Confirm to save one undo step, or cancel. Scene buttons expose later text without a separate text panel.
• Theme controls sit below the video. Video details show the original creative brief with a copy action. Related videos and taxonomy are not part of the editor.
• Saved props are validated before loading. Invalid text cannot be committed. Changes remain available after reloading.
• Share replaces the JSON download. Publishing requires Google sign-in; recipients can view without it. Live publishing stays unavailable until the rendering service is configured.

Notes

• Preset gallery cards autoplay muted MP4s when at least 35% visible. Scrolling away or hiding the page unloads them. Reduced-motion settings keep the poster, as does a rejected autoplay request.
• iPhone/iPad live compositions skip costly grain, blur, and selected 3D layers. Exported videos retain the full effects. Browser emulation cannot prove stability on every physical iPhone.
• The gallery shows one preset per template. Retired color presets stay hidden but remain valid for bookmarks, saved drafts, and share links. Flex measures glyph bounds to fit variable-width text.

Verify

npm run build
npm test
npm run test:agent
npm run test:source-render -- stack
npm run test:rules          # requires Java 21 on PATH
node scripts/smoke.cjs
node scripts/smoke-ios.cjs
node scripts/smoke-media.cjs
node scripts/smoke-media.cjs --ios
node scripts/smoke-inline.cjs
node scripts/smoke-inline.cjs --ios
node scripts/smoke-editor-layout.cjs
node scripts/smoke-editor-layout.cjs --ios
node scripts/smoke-editor-layout.cjs --mobile

Additional integration checks:

# Run a separate Vite server with VITE_GA_MEASUREMENT_ID=G-TEST123.
URL=http://127.0.0.1:5181/voodoo/ node scripts/smoke-analytics.cjs

# Start local emulators with project demo-cliphouse, then start Vite with
# VITE_FIREBASE_EMULATORS=true and demo Firebase settings.
firebase emulators:start --project demo-cliphouse --only auth,firestore
URL=http://127.0.0.1:5182/voodoo/ node scripts/smoke-sync.cjs

The emulator switch is ignored in production builds. Security tests cover unauthenticated access, cross-account access, payload validation, and owner writes.

Run the browser checks against the dev server, or set URL to the deployed site. Media checks cover viewport autoplay, background cleanup, blocked autoplay, reduced motion, complete editor loops, and Flex text fitting. Screenshots are viewport-sized and written under /tmp/voodoo-*.

Inline checks edit every role in every template and verify undo, redo, and persistence. Layout checks cover mobile rotation, the fullscreen fallback, orientation requests, duplicate text values, and validation. The synthetic keyboard viewport test runs in mobile Chromium because overriding that native property crashes this Mac's WebKit test runner; physical-device keyboard behavior still needs manual confirmation.

Design reference: Adobe's 2026 design trends, including tactile collage and playful typography. Playback reference: WebKit's inline autoplay policies.

Rendering

• Remotion's downloaded headless Chrome hangs on this machine. remotion.config.ts and the preview script use Playwright's cached headless shell instead. To use another browser, set REMOTION_BROWSER.
• Remotion needs a company license above a small team size. See remotion.dev/license.