HyperPBI is one declarative analytics system with multiple hosts. HyperPBI 2.0 is the only dashboard schema; neither the unified website nor its embedded Playground introduces a second format.
AI / Visual Editor / JSON / Templates
↓
HyperPBI 2.0 Specification
↓
Shared HyperPBI Runtime
↓
Power BI Host | Web Host
Shared TypeScript under src owns schema preparation, canonical field resolution, calculated fields, logical datasets, reference validation, sanitization, Studio, rendering, component state, interactions, maps, tables, charts, and SVG. apps/playground supplies reusable Preact project, authoring, play-mode, file-import, and browser-host surfaces. apps/web owns the Next.js application shell, shared navigation, content routes, server-side manifest loading, and the runtime-island boundary that mounts those Playground surfaces without duplicating the renderer.
Runtime settings moved to src/runtime/runtimeSettings.ts, so Studio and rendering do not need Power BI formatting APIs. Host behavior is expressed by HyperPbiHostBridge:
PowerBiHostBridge delegates identity selection, JSON filters, and safe URL launching to Power BI while preserving existing interaction diagnostics.BrowserHostBridge allows the shared internal interaction engine to keep working but returns an explicit unsupported result for Power BI-only selection and external filtering.No bridge evaluates specification strings, runs arbitrary JavaScript, or bypasses the existing URL, HTML, CSS, SVG, JSON, map-provider, or chart-option policies.
The public site is one Next.js application:
| Route | Purpose |
|---|---|
/ |
Product introduction and primary workflows |
/components |
Searchable Component Explorer generated from canonical component metadata |
/playground |
Local project creation/import and links to project authoring and Play Mode |
/examples |
Manifest-driven complete dashboards plus the analytical map gallery |
/docs |
Repository Markdown documentation with shared site navigation |
The Next.js pages own navigation and content composition. Interactive HyperPBI surfaces are compiled into a browser runtime island and mounted only where a page needs the shared Preact renderer or Playground workflow. IndexedDB remains browser-local; server-rendered pages do not receive uploaded project data.
DataWorkspace contains a stable default source ID and named DataSource records. powerbi resolves to the default source in every host. Power BI creates one source. The Playground creates one source for each CSV and one for each XLSX sheet. Logical dataset definitions may use an uploaded source ID as their input and may chain normal declarative operations from that source.
Uploaded data processing is deterministic:
null;null;Joins, relationships, DAX, Power Query, and SQL remain out of scope. Read-only remote sources are resolved through the shared source layer: MiniUp table/Function sources plus approved HTTPS rest.get restricted by the build-time trusted-host list. Components never fetch directly.
IndexedDbProjectStorage is the repository-owned implementation of the host-neutral ProjectStorage interface. Each project stores metadata, a canonical 2.0 specification, Runtime Configuration, Studio layout/drafts, source manifests, normalized field metadata, rows, and row keys. A cloud implementation can satisfy the same interface later without changing Studio or the renderer.
The .hyperpbi format is a complete local project bundle. Import validates the bundle marker/version, workspace invariants, Runtime Configuration, schema 2.0, datasets, and field bindings, then assigns a new project ID. It is not the same thing as portable dashboard JSON: it includes local data and editor state that Power BI does not consume.
Every Power BI-oriented export runs analyzePowerBiPortability. Results are:
compatible: the specification already uses the portable powerbi source;compatible-after-default-source-rewrite: explicit references to only the selected default browser source can be safely rewritten to powerbi;not-fully-portable: the project needs independent uploaded sources, browser-only behavior, invalid/missing bindings or aliases, or another dependency that one Power BI data view cannot satisfy.The rewrite changes only dataset inputs equal to the selected default source ID. It never rewrites or merges a genuinely separate source. Warnings also call out external filter actions whose fields must resolve to real Power BI model columns.
The Playground is an authoring and reference runtime for analytics specifications. Standard presentation uses sanitized HTML/CSS, governed SVG, implemented components, declarative actions, safe expressions, and deterministic logical datasets. Explicit trusted author mode preserves HTML/SVG in opaque-origin sandboxed documents and unrestricted CSS inside an isolated visual. Those documents have no report-service bridge; host CSP, network and frame restrictions still apply. The standard expression and workbook pipelines never execute scripts or callbacks.
Published map imports use versioned generic definitions in src/maps/imports, explicit source adapters and three-way refresh merging. GeoJSON relationships reuse the existing map join engine and carry only real source-row lineage into host interactions. The compact Map Studio sends scoped commands to the same native map preview; it does not create a second renderer or an independent saved-state model. Remote GeoJSON lifecycle, popup content, color controls, effects and layer-origin presentation live in separate modules.
From the repository root:
npm ci
npm run dev
npm run build
npm run web:sites:build
npm run dev builds the browser runtime island and starts Next.js on http://localhost:4178. npm run build performs the root and web type checks, rebuilds the island, and creates the production Next.js output.
The production Vercel project builds main using the GitHub integration and vercel.json. Release verification also builds the OpenNext Worker and stages the repository’s website distribution archive.
SpecificationAuthoringService is the future AI integration seam. A provider adapter will receive an AuthoringContext and return a candidate HyperPbiSchema; it must never save or render before the shared validator accepts it. A future publishing service should sit beside ProjectStorage, persist projects/specifications to an authenticated backend, and deploy the same web host. Neither service should fork the schema, editor, renderer, or security pipeline.
HyperPbiRoot tracks the latest event for configured source IDs and events. Interaction payloads carry table rows, chart selections, and filter values. Leaflet supplies feature attributes. RemoteFragmentHost resolves the URL, checks network permission, cancels stale requests, and prepares the returned tree with the shared schema and registry. Fragment roots own their data and state. Dashboard roots own overlay definitions, focus, and stack state. Dynamic Content guide.