gad-visual-context
v0.1.2
Published
Visual Context System (VCS) — deterministic component IDs, dev-mode inspector modal, and source-searchable visual identities for any React app. Ships from the GAD framework.
Maintainers
bgarrardReadme
gad-visual-context
Visual Context System (VCS) for React — deterministic component IDs, a dev-mode inspector modal, and source-searchable visual identities for any React application. Ships from the GAD framework.
VCS assigns every rendered UI region a stable cid (component ID) that survives reloads. In dev mode, hovering any wrapped region and pressing Alt+I opens an inspector panel showing the component tree, cids, and one-click AI-agent prompt templates for that surface.
Installation
npm install gad-visual-context@portfolio/ui is a required peer dependency (shadcn-based component library). If you are consuming this inside the GAD monorepo it is already workspace-linked.
Peer dependencies
{
"react": ">=19.0.0",
"react-dom": ">=19.0.0",
"@portfolio/ui": "workspace:*"
}Usage — Next.js app/layout.tsx
// app/layout.tsx
import { VisualContextProvider, DevIdProvider } from "gad-visual-context";
import { useMemo } from "react";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<VisualContextProvider>
<DevIdProvider enabled={process.env.NODE_ENV === "development"}>
{children}
</DevIdProvider>
</VisualContextProvider>
</body>
</html>
);
}For Next.js with router adapter (recommended — enables pathname-aware cid labels):
// components/AppVisualContextProvider.tsx
"use client";
import { useMemo } from "react";
import { usePathname, useRouter } from "next/navigation";
import {
VisualContextProvider,
type VCSRouterAdapterValue,
} from "gad-visual-context";
export function AppVisualContextProvider({ children }: { children: React.ReactNode }) {
const pathname = usePathname() ?? "/";
const nextRouter = useRouter();
const adapter = useMemo<VCSRouterAdapterValue>(
() => ({
pathname,
router: {
push: (href) => nextRouter.push(href),
replace: (href) => nextRouter.replace(href),
back: () => nextRouter.back(),
forward: () => nextRouter.forward(),
refresh: () => nextRouter.refresh(),
prefetch: (href) => nextRouter.prefetch(href),
},
}),
[pathname, nextRouter],
);
return <VisualContextProvider router={adapter}>{children}</VisualContextProvider>;
}Wrap UI regions with SiteSection:
import { SiteSection } from "gad-visual-context";
export function HeroSection() {
return (
<SiteSection cid="hero.main">
<h1>Hello</h1>
</SiteSection>
);
}Exports
| Export | Description |
|---|---|
| VisualContextProvider | Root provider — mounts the VCS context and optional router adapter |
| DevIdProvider | Dev-mode overlay provider — enables cid inspector (pass enabled={false} in production) |
| DevPanel | Floating inspector panel (auto-mounted inside DevIdProvider) |
| BandDevPanel | Band-scoped variant of DevPanel for section-level inspection |
| SiteSection | Wraps any region with a cid — renders as a transparent div |
| Identified | Wraps any element and registers a cid without layout impact |
| IdentifiedPrimitive | Lower-level primitive for non-div elements |
| CrudModalFooter | Standard CRUD modal footer with VCS-aware action buttons |
| SiteProse | Prose content wrapper with cid support |
| SiteSectionHeading | Heading component wired to SiteSection |
| DevIdSearchDialog | Fuzzy-search dialog across all registered cids |
| DevIdAgentPromptDialog | AI-agent prompt builder for a selected cid |
| DevIdModalContextFooter | Footer component for DevId modal surfaces |
| KeyboardShortcutsProvider | Mounts the ? keyboard shortcut cheatsheet overlay |
| useVisualContext | Hook — access current VCS context value |
| useDevId | Hook — access DevId state (selected cid, enabled flag) |
| useDevIdEnabled | Hook — boolean, true when DevId overlay is active |
Dev modal keybinding
| Key | Action |
|---|---|
| Alt+I | Toggle DevId inspector panel |
| Alt+K | Open cid search dialog |
| Alt+click | Select a cid by clicking its region |
| ? | Open keyboard shortcut reference |
| Escape | Close active panel |