@tagna/udiot/browser safety contract

This contract describes the browser entry point's import boundary. Check the public export inventory for exact names and value/type status.

What counts as "browser-safe"

A module is browser-safe when it can be statically resolved by Vite, webpack, or rollup without requiring any of:

• Node built-ins: fs, fs/promises, path, os, crypto, child_process, http, https, net, tls, stream, cluster, worker_threads, node:*.
• Node-only npm packages: fs-extra, express, body-parser, pg, bullmq, firebase, @mikro-orm/*, multer, ws, openai, commander, chalk, ora, boxen, inquirer, chokidar, ts-node, tsx, esbuild, vite.

The static import graph from src/browser/index.ts is walked by test/browser-safety.test.ts on every commit. A PR that brings any of the above into browser reach fails CI.

What IS exported from @tagna/udiot/browser

• Core primitives: Framework, createComponent, Component type.
• Components: BaseComponent, AIAdaptiveComponent, VirtualComponent, lifecycle hooks, props validator, reactive state, slots, composition, registry, factory, VDOM, template compiler, ComponentEventEmitter.
• Event bus (in-memory): InMemoryEventBus, decorators, registry, providers.
• Enterprise features (browser-only subset): Context, createContext, routing, HttpClient, forms, error boundary.
• State: Store, createStore, IStore, ReadonlyStore, StoreLike, observables, subjects, selectors, persistence (LocalStorage / SessionStorage / IndexedDB / in-memory), Persist / ReactiveStore / Mutation / Action / Selector decorators, thunk + logger middleware.
• DevTools: DevToolsConnector, StateInspector, Redux DevTools integration.
• Micro-frontend runtime (@tagna/udiot/mfe re-exports): ShellRegistry, SharedPlatformContext, defineRemote.

What is NOT exported (even though it exists in the package)

• ../hooks.js and ../styling.js — both pull in AIClient → openai.
• ../plugins.js — paired with server-side plugin manager.
• ../testing/index.js — test utilities; use @tagna/udiot directly in Node test runners.
• ../ai/state-analyzer.js, ../ai/optimizer.js, ../ai/predictor.js, ../decorators/ai-powered.js — transitive Node deps.

These remain in @tagna/udiot so Node code (SSR, build, scripts) can use them.

Adding new exports

If you want to expose something from the browser entry, add it to src/browser/index.ts explicitly (named re-export). Do not add another export * from '../something.js' umbrella — that is what caused §1 of the limitations doc.

Before pushing, run:

npx jest test/browser-safety.test.ts