Add typed Web Viewer command registry

[eluce2]

Summary

• add @proofkit/webviewer/commands for typed command registration, buffering, cleanup, and namespace init
• add React helper hook and export surface for client-side command handlers
• update CLI Vite template to auto-init commands
• document the FileMaker-to-JS command flow in docs

Testing

• added runtime tests for buffering, replay, missing-command modes, cleanup, and namespace handling
• added type-level tests for registry declaration and command signature validation
• not run locally here

Summary by CodeRabbit

• New Features

  • Typed Web Viewer command registry with configurable buffering, missing-command modes, and error/warning handling
  • React hook to register/manage command handlers with automatic lifecycle
  • New package entrypoints for commands and React utilities

• Documentation

  • Expanded guide covering registration patterns, typed registries, buffering behavior, Next.js notes, and migration tips

• Tests

  • Added runtime and TypeScript tests for registry behavior and typings

• Chores

  • Release metadata updated to minor versions

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
proofkit-docs	Ready	Preview, Comment	May 19, 2026 5:36pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 6479740

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@proofkit/better-auth

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/better-auth@273

@proofkit/cli

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/cli@273

create-proofkit

pnpm add https://pkg.pr.new/proofsh/proofkit/create-proofkit@273

@proofkit/fmdapi

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/fmdapi@273

@proofkit/fmodata

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/fmodata@273

@proofkit/typegen

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/typegen@273

@proofkit/webviewer

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/webviewer@273

commit: 691ae3f

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9f6f799b-2e7f-402d-9226-9578571988a2

📥 Commits

Reviewing files that changed from the base of the PR and between 691ae3f and 6479740.

📒 Files selected for processing (1)

• .changeset/webviewer-commands.md

---

📝 Walkthrough

Walkthrough

This PR adds a typed, Proxy-backed Web Viewer command registry with buffering for early calls, configurable missing-command behaviors, a React hook, compile-time type tests, runtime tests, package exports, docs, and a changeset for release metadata.

Changes

Web Viewer Command Registry

Layer / File(s)	Summary
Command Registry Types and Public API Contract packages/webviewer/src/commands.ts	Branded type logic derives valid command names from a registry interface. Exported types define generic command handler signatures, registry options for missing-command behavior (buffer/warn/drop/throw), buffering limits, error/warn callbacks, and the public registry handle interface for namespace introspection.
Command Registry Implementation packages/webviewer/src/commands.ts	Per-namespace state tracks registered handlers, wrapped handlers, buffered calls, and options using WeakMap and Map storage. Proxy layer maps property access to wrapped registered handlers or missing-command handlers; registration replays buffered calls with error reporting during replay. initWebViewerCommands mounts proxy at window[namespace], preserving existing non-null values. Public APIs: registerWebViewerCommand, unregisterWebViewerCommand, getWebViewerCommandRegistry.
Runtime Tests for Command Registry packages/webviewer/tests/commands.test.ts	Validates initialization without window, default namespace creation, buffering and replay before/after command registration, error handling with structured context and replay continuation, missing-command modes, bounded buffering with oldest-call dropping, cleanup semantics, idempotent initialization, namespace preservation with warnings, and unregistration behavior.
Type Safety Compile-Time Tests packages/webviewer/tests/commands-types.test.ts	Subprocess tsc validation confirms valid string-parameter registries compile, rejects invalid parameter types and malformed entries via DefineWebViewerCommandRegistry, and enforces correct handler signatures for unknown commands.
React Hook for Command Registration packages/webviewer/src/react.ts	useWebViewerCommand hook initializes the command registry and registers a command handler on mount, using a ref to keep the handler in sync with the latest callback without re-registering on function identity changes.
Package Configuration and Build Setup packages/webviewer/package.json, packages/webviewer/vite.config.ts	Adds export subpaths ./commands and ./react with ESM/CJS/types targets. Marks next and react peer dependencies as optional. Updates @types/react to 19.2.7. Adds commands.ts and react.ts to vite entry config.
User Documentation and Release Metadata apps/docs/content/docs/webviewer/commands.mdx, apps/docs/content/docs/webviewer/meta.json, .changeset/webviewer-commands.md	Comprehensive MDX guide covers initialization patterns, typed registry definitions, static and React-based command registration, Next.js Client Component guidance, missing-command buffering modes, and migration from direct window.proofkit assignment. Doc navigation updated with commands entry. Changeset marks @proofkit/webviewer, @proofkit/docs, and @proofkit/cli as minor releases.

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add typed Web Viewer command registry' directly and clearly summarizes the main change: introducing a typed command registry system for the webviewer with corresponding types, exports, and documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch webviewer-commands

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}