Blueprint UI

vyuh_blueprint_ui is the Blueprint application adapter. It interprets a Blueprint and maps its declared app shell, workspaces, collections, commands, relationships, actions, and regulated runtime state into Studio UI contracts.

The design system and generic application widgets live in vyuh_studio_ui. Blueprint UI maps BlueprintApp, routes, effective entity UI plans, action surfaces, dashboards, reports, and shell values onto that shared UI layer. It must not introduce a second design system or expose a separate Workspace UI vocabulary.

The package name carries the Blue context. Public UI classes use plain product language:

Concept	Class
App composition root	AppBuilder
Application-wide Blueprint service	BlueprintPlugin, exposed as vyuh.blueprint
Route/view adapter registry	ViewRegistry, ViewContext
App frame	AppShell
Runtime scope values	ShellValues
Account and appearance chrome	UserMenuUI, AppearanceUI from vyuh_blueprint
Workspace frame	Workspace from vyuh_studio_ui
List-like projection	CollectionView from vyuh_studio_ui
Collection state owner	CollectionController from vyuh_studio_ui
Query tokens	CollectionQuery, FilterToken, SortToken
Saved view	SavedView, SavedViews
Action affordances	ActionPanel, UiAction
Command surface	CommandPalette, Command
Icon vocabulary	UiIcons
Details and editors	DetailView, EditorView, FieldValue
Dashboards and reports	DashboardView, ReportView, Metric
History and integrity	TimelineView, AuditTrail, VersionHistory
Regulated panels	PolicyPanel, EvidencePanel, AuthorizationGate, ErrorPanel
Operations surfaces	ImportExportPanel, RelationshipPanel, HierarchyView
Runtime posture	OfflineBanner, RealtimeStatus, SimulationPanel, HelpPanel

Application Construction And Client Ownership

runBlueprintApp assembles the application in a fixed order. Product code supplies the Blueprint server URL and domain features; the runner supplies the shared platform infrastructure:

runBlueprintApp
  -> Vyuh PluginDescriptor
       -> NetworkPlugin (Dio by default)
       -> BlueprintPlugin
       -> auth, storage, telemetry, command palette
  -> Blueprint Host feature
       -> domain feature descriptors
       -> accumulated BlueprintApp
  -> AppBuilder and workspaces

BlueprintPlugin is a platform plugin, not a route-local object and not a feature-owned client. Its public entry point is:

final client = vyuh.blueprint.client;

The word protocol is deliberately absent from the public lookup. The wire protocol is an implementation concern behind the Blueprint client.

The default request path is singular:

feature, shell, search, editor, action, or inspector consumer
  -> vyuh.blueprint.client
  -> CachedBlueprintProtocolClient
  -> HttpBlueprintProtocolClient
  -> vyuh.network (DioNetworkPlugin)
  -> Blueprint server

This gives the app one cache, one in-flight request deduplication boundary, one relationship-derived invalidation graph, and one inspector stream. Feature and UI code must not construct http.Client, Dio, or another Blueprint client. Hosts that require custom authentication or transport behavior replace the network plugin or pass the advanced client factory to runBlueprintApp; the result is still exposed through vyuh.blueprint.client.

The default Dio network plugin owns transport retries and interceptors. The Blueprint layer owns semantic concerns: request models, cache keys, mutation announcements, relationship invalidation, connection state, heartbeat, and inspection. Safe-read attempts are kept at one in the HTTP adapter so retries are not multiplied across both layers.

Shell bootstrap is actor-first. After authentication, the actor projection is loaded before actor-dependent shell data. The actor projection can carry its denormalized tenant, site, and department scope. The shell therefore does not enumerate the department collection merely to resolve the selected actor's department; it loads site options only because the site selector needs them.

The Blueprint Inspector observes the same shared client. Its Overview values use the application's field formatter for date-time, number, duration, status, and sequence display. Request and Response payload tabs preserve the exact JSON wire data so the debugger remains valid evidence of what was sent and received.

Naming Rule

Do not prefix renderer classes with Blueprint or Entity unless the class is specifically modeling the blueprint declaration graph. UI components are named for the interaction they provide: shell, workspace, collection, detail, form, panel, command, report, dashboard, and so on.

This keeps the renderer useful for entity-backed screens and non-entity runtime surfaces such as reports, dashboards, protocol records, policy consoles, simulator timelines, and generated documents.

Icon Vocabulary

Workspace UI uses fluentui_system_icons as the default enterprise icon set. The public API exposes a semantic UiIcons catalog, so the renderer asks for concepts such as policy, kanban, report, command, audit, resize, or simulation instead of scattering raw icon-library names through apps.

This gives us one icon language for shell chrome, command palettes, collection modes, regulated panels, workflow surfaces, dashboards, reports, and simulator tools while still keeping the icon library replaceable behind one adapter.

UI Vocabulary

UIVocabulary.complete() is the code-level catalog for the Blueprint app UI language. It describes what a generated or hand-authored app can put on the screen without tying every term to an entity implementation detail.

Group	UI capabilities
Shell	app_shell, workspace, environment_selector, tenant_selector, site_selector, role_selector, language_selector
Navigation	menu, navigation, route, command_palette, command
Exploration	collection, list, table, cards, kanban, calendar, map, tree, graph, timeline, visualization
Work	inbox, alert, notification, approval, task, exception, escalation, workflow, action
Data	search, filter, saved_view, detail, summary, editor, form, wizard
Regulated	audit, evidence, policy, permission, version_history, comparison
Outputs	dashboard, report, document, attachment
Operations	import_export, relationship, hierarchy, activity_feed
Runtime	settings, profile, help, offline, realtime, simulation

The distinction is intentional:

• a capability describes a renderer/controller the package can provide;
• a surface describes an application concept that can appear in an app blueprint, runtime manifest, route map, permission map, or generated UI.

Entity System UI Inventory

EntitySystemUIInventory.current() is the harvested capability checklist from the existing Entity System UI package. Blueprint UI uses this as the extraction map while keeping the implementation independent from EntityBase, MobX, CDX routing, and the old app runtime.

Capability group	What exists today in Entity System UI
Authorization	Route, menu, tab, field read/write, action, and section gates with fallback rendering.
Routing	Standard routes, custom routes, dialogs, adaptive sheets, route lifecycle hooks, and navigation extensions.
Workspace	Entity workspaces, grouped/singleton workspaces, detail docking, draft isolation, mutation events, and pane modes.
Collections	Collection controller, selection, pagination, batch actions, headers, side panels, and collection actions.
Collection modes	table, grid, inbox, kanban, calendar, tree, and miller.
Query, filters, saved views	Search, filters, sort, filter presets, saved views, layout state, and URL sync.
Dashboards and metrics	Analytics dashboards, entity statistics, metric cards, compact cards, and hero cards.
Reports and documents	Report surfaces that assemble metrics, tables, charts, generated documents, and PDF outputs.
Forms and editors	Entity editors, create dialogs, dirty-state tracking, validation, field extensions, permission matrix fields, and password fields.
Details and relationships	Detail tabs, section cards, relationship panels, related entity cards, entity links, and status banners.
Hierarchy and trees	Tree views, breadcrumbs, Miller columns, split views, and hierarchy nodes.
Versioning and audit	Version history, audit history, comparison views, version badges, and versioned actions.
Import/export	Import/export dialogs, column mapping, validation preview, progress display, and capability actions.
Workflow timeline	Milestones, tasks, warnings, actor rows, and activity lists.
Contextual help	Help dialog with search, overview, fields, actions, and FAQ tabs.
Errors	Error service plus banner, dialog, inline, page, panel, and snackbar renderers.
Command palette	Searchable command palette, search providers, highlighted results, tabs, and keyboard intents.
Pickers and links	Entity pickers, multi-select fields, actor-chain pickers, entity links, and name cells.
Offline and drafts	Draft isolation, read-only draft scope, draft toggles, and draft detail cards.

The extraction is intentionally adapter-first. Instead of copying the old internals wholesale, Blueprint UI creates plain Flutter renderers and state objects that can later be driven by the Blueprint protocol, CDX query adapters, runtime action records, simulator streams, or domain-specific apps.

App Builder And View Registry

AppBuilder is the composition root for a Blueprint-rendered Flutter app. It consumes an BlueprintApp, the current ShellValues, collection row providers, dashboard metric providers, and an action handler. It then owns the selected route and renders the configured AppShell, Workspace, CommandPalette, and route body.

ViewRegistry is the route-to-view adapter layer. The default registry maps app route kinds to Blueprint UI surfaces:

Route kind	Default renderer
entityList, entityDetail	CollectionView with action affordances
dashboard	DashboardView using dashboard metrics
inbox	InboxPanel surfaces
settings	Declared settings modules and policy packs
search	SearchPanel surfaces
report	ReportView surfaces
editor	EditorView placeholder until form/runtime adapters land
custom	Overridable host renderer

This is the missing bridge between the app blueprint and the renderer. The ELog preview now uses AppBuilder; the app supplies rows, dashboard metrics, and action behavior, while navigation, shell chrome, collection rendering, dashboards, command surfaces, and docked panels come from vyuh_blueprint_ui. The active app scope is surfaced in the workspace header: current actor, tenant, site, configured selectors, profile, settings, and logout come from the app blueprint shell rather than from ELog-specific widgets.

Extracted Collection Runtime

The first concrete extraction from Entity System UI now lives in vyuh_studio_ui:

Pattern	Blueprint UI Type
Collection state owner	CollectionController
Layout mode	CollectionLayoutMode
Layout state	CollectionPresentation
Visible field	CollectionColumn
Saved view	SavedView
Query state	CollectionQuery, FilterToken, SortToken
Renderer	CollectionView

CollectionController carries rows, loading/failure state, selection, paging, query, saved views, and presentation state. A saved view can restore both the query and the collection presentation, matching the Entity System UI pattern where view state is user-facing and durable.

CollectionView currently switches these modes from the same controller:

Mode	Use
table	Dense operational lists and regulated master data.
cards	Compact record summaries.
grid	Card/grid exploration for visual record scanning.
inbox	Actor or role-oriented work queues.
kanban	Work queues grouped by status, stage, or owner.
calendar	Date-oriented activity, due-date, and schedule views.
map	Location-oriented collections; currently rendered through card fallback.
tree	Hierarchical structures such as sites, areas, assets, or org units.
miller	Multi-column hierarchy exploration.
timeline	Chronological records, activity, audit, and workflow movement.

App declarations now use ordered typed ListUI.layouts. Runtime artifacts preserve every layout and its projection/configuration, so the UI can offer a layout switcher without hard-coding per-entity behavior.

Blueprint UI builds a CollectionDescriptor from each app-blueprint EffectiveEntityUI; the shared renderer owns mode controls and updates CollectionPresentation in the same place Entity System UI used to keep collection layout state.

AppBuilder can source a collection through CollectionData.fromQueryRows. That path carries the BlueprintQueryRequest, emitted QueryRecord, and rows together, so local previews and production clients can render the same protocol shape used by /blueprint/query. The ELog preview app uses this path now: the collection still renders through CollectionView, but the rows are wrapped in a query record and the workspace shows the protocol record id.

Registry And Navigation

The app blueprint remains the place where descriptors are collected into one application surface:

• entity descriptors assemble the effective entities, facets, and Entity.ui;
• app assembly derives route, collection, navigation, and command-palette surfaces from Entity.ui and facet-owned actions;
• app descriptors contribute shell, settings, dashboard, report, help, inbox, menu, scope, realtime, offline, and custom surfaces;
• effective entity UI plans advertise projections, supported modes, filters, sort, derived action surfaces, and related navigation;
• menus, navigation groups, command palette entries, dashboards, reports, saved views, and settings surfaces form the registry the UI can render;
• shell chrome exposes actor, tenant, site, domain selectors, profile, settings, logout, theme mode, and text-scale controls from configuration;
• permission and policy refs stay attached to routes, menus, actions, related links, dashboards, and reports so the runtime can trim or annotate the surface for the current actor.

Related navigation is explicit through RelatedUI. An entity UI plan can point to related entities such as area, equipment logs, workflow tasks, documents, batches, samples, deviations, or approvals while preserving route, projection, permission, and policy metadata.

Reports And Metrics

Use metric in the public vocabulary for dashboard and report values. A dashboard widget can be a metric, and a report can contain ReportBlockKind.metric, table, chart, text, image, section, or custom blocks. ReportUI.outputs advertises outputs such as pdf, html, csv, xlsx, and json.

That gives us one language for dashboards, reports, generated PDFs, and factual exports.

Workspaces And Docks

WorkspaceLayout, DockConfig, DockPlacement, and DockMode model the workspace layer. The renderer supports right-docked detail panels and a bottom dock for protocol streams, logs, inboxes, inspectors, approvals, or simulation traces. Both panes expose draggable splitters, so the default AppBuilder layout behaves like a real workspace instead of a static page.

The result is IDE-like but still app-blueprint driven: a workspace can have left/right docks, a bottom stream, collapsible or undocked panels, and role-specific layouts without each app hand-building the frame.

Contextual Help

Contextual help is now captured as a separate vocabulary item. HelpFragment and HelpContext model hierarchical, JSON-backed help fragments that can be composed from the current app, workspace, route, menu, collection, detail tab, field, action, dashboard, or report.

Hosts resolve each jsonRef, merge the fragments for the current visible UI stack, and present the result through their configured help surface.

The ELog preview app now dogfoods these primitives through AppBuilder: routes render through ViewRegistry, Workspace, CommandPalette, DashboardView, CollectionView, ActionPanel, InboxPanel, ApprovalPanel, NotificationPanel, PolicyPanel, EvidencePanel, AuditTrail, ReportView, OfflineBanner, RealtimeStatus, and SimulationPanel.

The Studio path includes protocol-backed plan, preflight, and execute action forms, typed query translation, explain/failure traces, and the supported table, grid, Kanban, calendar, tree, and timeline layouts.