[jordanhudgens]

What

Prepare @encapsa-dev/brain 0.1.1 for its first dashboard integration, with corrected npm packaging, a one-action sidebar preview, a fill-parent explorer, React 18/19 compatibility proof, and complete release documentation.

No npm publication, merge, production deployment, Forge modification, or Toastability/app change is included.

Why

The published 0.1.0 artifact was the root Next.js demo workspace, including a self-dependency, rather than the nested library. The initial library also declared React 19 only, while the intended first host uses React 18.

The requested UI needs two distinct surfaces: a small read-only overview with just Expand, and a full explorer in a host-owned Brain tab. The existing compact explorer still exposed controls and managed its own expansion.

How

• Rename and mark the workspace root private; add a root publish guard.
• Make packages/brain the sole public package, version 0.1.1.
• Preserve the existing BSD-3-Clause license and README animation; synchronize README/LICENSE/CHANGELOG into the tarball at prepack.
• Add BrainPreview with a host-owned onExpand callback, no graph interaction, and inexpensive SVG defaults.
• Add variant="embedded" and composition UI visibility controls.
• Add a synthetic /embed example matching the sidebar → host Brain tab → center content pattern.
• Test React 18.3.1/Fiber 8.18.0 and React 19.2.4/Fiber 9.8.1 with the actual packed library.
• Fix stale detail/subscription state, malformed receipt matching, unsafe object-property IDs in layout dictionaries, incoming-edge navigation, offscreen rendering, and a light-theme contrast failure.
• Complete README, CONTRIBUTING, CHANGELOG, DEVELOPMENT, AGENTS, package metadata, demo metadata, verification evidence, and CI.

The two commits separate library/runtime changes from release/demo/documentation work. Generated distribution files remain tracked and have been rebuilt.

Testing

• Frozen-lockfile install
• Typecheck and lint
• 107 unit/integration tests in 13 files
• 20 Playwright browser tests
• Library ESM/declaration build
• Normal Next.js production build
• Static review build
• Actual tarball inspection and installation
• Four clean consumer lanes: React 18 SVG, React 19 SVG, React 18 WebGL, React 19 WebGL
• SVG consumers omit Three, Fiber, and graphics types
• SSR imports, strict peer resolution, strict declaration checks
• Desktop/mobile and light/dark visual inspection
• Private review preview checked for hydration, Expand → tab, and WebGL readiness
• Original README animation preserved byte-for-byte
• git diff --check

See docs/verification.md for the audit findings, executed checks, limitations, and integration boundary. docs/consumer-proof.json contains the portable package-matrix evidence.

Release instructions for Jordan

After review/merge and the documented checks:

pnpm --filter @encapsa-dev/brain publish --access public

Do not publish from the root workspace. npm remains on 0.1.0 until you publish this corrected release. Update the CHANGELOG's Unreleased heading to the actual publication date as part of your release process.

GitHub About description/topics are prepared in DEVELOPMENT for review; repository settings were not changed outside this PR. Package description, keywords, repository/homepage/bugs fields, author, license, and demo metadata are included in the diff.

Scope and limitations

• All demo data is fictional; no live API credentials or production records.
• No host application, Forge, database, or production environment-variable changes.
• Renderer fallback never weakens data authorization.
• Hardware FPS, Safari/iOS, Firefox, and exhaustive screen-reader testing are not claimed.
• Optional Three/Fiber chunks still trigger Vite's large-chunk warning; SVG-only consumers remain independent.
• CI is newly added; local results above are complete, but remote CI status should be reviewed separately.

The first Toastability/app implementation should be a follow-up PR after 0.1.1 is published.

[vercel]

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

Project	Deployment	Actions	Updated
brain	Ready	Preview, v0	Oct 3, 2026 6:02am UTC