Praxis Forge View SDK

Pure-function asset SDK for Praxis Station team capability packages.

Package Shape

This repository publishes a single npm package: praxis-forge-view-sdk.

The SDK keeps module boundaries internally:

• Core asset types, registry validation, trigger matching, View DataGraph effects, and mapping constraints.
• Optional fetcher utilities for ConnectorGraph scope request wrapping through host-injected transport.
• Renderer utilities that convert loaded UIAsset/UINode definitions into a render tree.
• A versioned Praxis Widget Catalog whose React adapter is implemented with Ant Design, Lucide icons, and ECharts time-series charts.
• Authoring constraints that describe valid asset kinds, standard events, action types, and host-owned editing boundaries.
• Scoped asset styles and theme compilation.

View and Widget share the same UIAsset + UINode data model. kind: "view" is an entry asset, kind: "widget" is a reusable UI fragment, and both render from UIAsset.root. Widget inputs are declared by structured interfaces; ViewDataGraph.targets inject runtime data into Widget instances, while UINode.params maps a parent component interface to nested Widgets. View data wiring lives only on the entry View's UIAsset.dataGraph; Widget assets that declare their own dataGraph fail validation. ConnectorGraph definitions and their embedded response shapes live in the loaded registry.

JsonShape remains an embedded contract rather than a second asset type. A shape may declare a versioned $id such as praxis.team.task-list@1, and another loaded UIAsset or ConnectorGraph boundary may use $ref. The SDK builds this catalog from the already loaded registry; it does not add a Schema bucket or a Station endpoint. ViewDataGraph is likewise the scene wiring layer. Reusable cross-View graph fragments are an extension point for proven repetition, not a new Binding asset path.

The SDK Core does not index capability package files, read from Forge, access the filesystem, issue network requests, or edit asset JSON. Hosts load assets, generate or edit JSON definitions, persist changes, and inject runtime data, secrets, permissions, and transports.

Scripts

pnpm build
pnpm typecheck
pnpm test

Distribution

The formal integration path is npm:

pnpm build
pnpm typecheck
pnpm test
pnpm publish --access public

Forge UI and Station should depend on a semver range of praxis-forge-view-sdk. Local file: dependencies, pnpm link, or pnpm pack are only for development checks.

Runtime Host Usage

For normal hosts, create one long-lived runtime. It owns asset loading, prepared registry validation, connector result caching, connection resolution, and explicit asset/data invalidation:

import { createPraxisRuntime } from "praxis-forge-view-sdk/runtime";

const runtime = createPraxisRuntime({
  loader: async ({ packageId }) => stationApi.getPackageDetail(packageId),
  transport: stationTransport,
  cache: { ttlMs: 300_000, staleWhileRevalidate: true }
});

const result = await runtime.renderView({
  packageId,
  entry: "homepage",
  context: { teamId, deptId },
  hostData
});

await runtime.renderView(input, { refreshData: true });
await runtime.renderView(input, { reloadAssets: true });

Changing only hostData reuses both the prepared registry and Connector outputs. refreshData reruns ConnectorGraph requests without reloading assets; reloadAssets invalidates both layers. createRuntimeAssetView remains available as the compatibility one-shot API.

React Usage

React hosts can use the optional subpath:

import {
  PraxisRuntimeProvider,
  PraxisView
} from "praxis-forge-view-sdk/react";

export function App() {
  return (
    <PraxisRuntimeProvider runtime={runtime} components={components}>
      <PraxisView
        teamId={teamId}
        deptId={deptId}
        packageId={packageId}
        entry="homepage"
        context={{ teamId, deptId }}
        hostData={hostData}
        fallback={<DefaultHomeDashboard />}
      />
    </PraxisRuntimeProvider>
  );
}

For custom layouts, usePraxisView returns refreshData() and reloadAssets(). Existing RuntimeAssetView and useRuntimeAssetView remain compatible. Non-React hosts can use the explicit DOM adapter without changing the runtime model:

import { mountPraxisView } from "praxis-forge-view-sdk/react/mount";

const view = mountPraxisView(container, { runtime, packageId, entry: "homepage" });
view.update({ hostData });
view.refreshData();
view.destroy();

react remains an optional peer for Core-only consumers and is required when using the React subpath. Ant Design is installed by the SDK and is only loaded through that subpath; importing the root Core SDK does not load the React adapter.

Connector Connections and Transport Policy

The complete Connector fetcher contract, including browser scopes, runtime bindings, pre-request scripts, SDK dependencies, and integrity checks, is documented in docs/connector-runtime.md.

ConnectorGraph remains host-neutral. A runtime can resolve environment values, session secrets, and a transport per Connector without persisting credentials in the asset:

const runtime = createPraxisRuntime({
  connectionResolver: ({ connector }) => ({
    runtime: connections[connector.id].runtime,
    secrets: connections[connector.id].sessionSecrets,
    transport: connections[connector.id].transport
  })
});

createHttpTransport allows same-origin requests by default. Cross-origin requests require an explicit allowedOrigins entry and still depend on the target CORS policy. createGatewayTransport adapts the same TransportRequest for private networks or server-held credentials. redactTransportRequest and HTTP transport traces redact authorization/cookie/token fields and configured secret values. This capability boundary lets the same ConnectorGraph run in Forge, Station, or another host without granting assets unrestricted network access.

Low-Level Usage

Advanced hosts can still call the lower-level pure functions directly:

import {
  createRenderTree,
  evaluateViewDataGraph,
  executeConnector,
  resolveViewDataGraphData
} from "praxis-forge-view-sdk";

const firstPass = evaluateViewDataGraph(viewAsset, runtime);
const request = firstPass.requestEffects[0];
const connectorResult = await executeConnector({
  connector,
  scope: request.scope,
  request: request.request,
  runtime: stationRuntime,
  secrets: stationSecrets,
  transport: stationTransport
});
const data = resolveViewDataGraphData(viewAsset, {
  [request.sourceId]: connectorResult.data
});
const secondPass = evaluateViewDataGraph(viewAsset, runtime, data.dataSourceOutputs, data.viewModel);
const renderTree = createRenderTree({
  asset: viewAsset,
  registry,
  targetInputs: secondPass.targetInputs,
  viewModel: data.viewModel
});

Connector source requests may reference context, state, data, and view values. This allows a resource-defined selector to update runtime state and drive the next Connector request without adding business-specific host code.

The React catalog also includes resource-driven table row events, read-only details dialogs, relative date formatting, and schema form fields with disabled or custom-value select modes. These behaviors remain declarative in the UI asset; hosts only need to dispatch the emitted runtime actions.

praxis.form.dialog/v1 supports an open event for read-only preparation such as field suggestions. The event receives event.currentValues and normalized event.availableOptions; a request action can save its response with resultStateKey and pass that state back through the dialog's suggestions property. The dialog applies only the first candidate for an empty, enabled field and never replaces a user-entered value. Open-request failures leave the form usable and do not affect its existing submit action.

Renderer Boundary

The Core renderer is intentionally composable. It does not hard-code Station layouts, CSS, business widgets, or HTML templates. It produces a neutral RenderTree from UIAsset + UINode. The React adapter maps registered praxis.*\/vN types to Ant Design internally; resource definitions never name Ant Design components directly:

import { createRenderTree, renderTreeToHtml, renderTreeToElements } from "praxis-forge-view-sdk";

const tree = createRenderTree({ asset: viewAsset, viewModel });

// Generic HTML/SVG output for schema-defined native nodes.
const html = renderTreeToHtml(tree);

// A host can still supply component overrides for registered Praxis types.
const element = renderTreeToElements(tree, {
  createElement: React.createElement,
  components: {
    "praxis.card/v1": StationCard,
    "praxis.metric/v1": TeamMetric
  },
  text: (value) => value
});

props contains structural directives such as ref, repeat, and each. Component inputs belong in params. UI assets may compose fragment, slot, widget, registered Praxis Widget types, and explicitly registered host components. antd.* types and unregistered praxis.* types fail registry validation.

New display assets should use JSON UIAsset files and host-owned component/style mapping. The SDK should not accumulate special-case renderers for individual screens.

The React catalog includes generic visual primitives that keep assets library-neutral. praxis.icon/v1 resolves a Lucide icon by name, while praxis.chart.timeseries/v1 accepts plain points or series data and renders an ECharts line chart:

id: weekly-volume
kind: widget
interfaces:
  - name: points
    role: data
    type: array
root:
  uuid: weekly-volume-root
  type: praxis.chart.timeseries/v1
  params:
    data: points
    xField: date
    yField: value
    showAxis: false

praxis.avatar/v1 can resolve a host-provided memberId from a members directory, and praxis.avatar.group/v1 renders participant IDs with tooltips. The host remains responsible for resolving protected capability-package avatar files; the asset never fetches them itself.

Asset Ownership

The SDK does not publish View, Widget, ConnectorGraph, page layout, copy, or theme fixture assets. Forge and Store own those resources and their versions. The SDK package changes only when its protocol, validation, data runtime, or renderer behavior changes. Protocol coverage uses minimal test-local samples that are not exported from the npm package.

Authoring Constraints

The SDK does not ship a visual editor or text editor. Forge UI, Station, or another host owns any JSON editing experience, whether text-based, AI-assisted, or visual. The SDK only exports the contract those hosts should obey:

import {
  getAssetAuthoringConstraints,
  STANDARD_PRAXIS_EVENTS,
  validateLoadedAssets
} from "praxis-forge-view-sdk";

const constraints = getAssetAuthoringConstraints();
const standardEvents = STANDARD_PRAXIS_EVENTS;
const validation = validateLoadedAssets(hostLoadedRegistry);

Important boundaries:

• Hosts may use the exported TypeScript types and constraints to generate forms, visual builders, schema-aware text editors, or AI prompts.
• Hosts persist JSON/YAML files and decide how to map package files to loaded UIAsset / ViewDataGraph / ConnectorGraphDefinition definitions.
• The SDK validates loaded references and renders loaded definitions; it does not mutate or save authoring files.
• Plugin calls and sandbox scripts are declarations only. The SDK validates and propagates them as effects; hosts decide whether and how to execute them.