JuntaiConsoleSDK

@zephytiju/console-sdk is the separately versioned UI-composition standard library shared by Juntai Console and contributor-owned Micro-UIs. It defines stable build-time registration, lazy React pages, bounded page context, identifier-only navigation, validation, compatibility, fixtures, and contributor-test contracts.

The package deliberately has no Console shell, router, session implementation, runtime catalog, discovery UI, service client, generated API source, contributor page, backend service, shared domain store, or runtime module loader. JuntaiConsole owns the composition root and implements ConsoleRegistrar with its catalog builder.

Install

npm install --save-peer @zephytiju/console-sdk react react-dom
npm install @zephytiju/juntai-typescript-sdk

@zephytiju/juntai-typescript-sdk is the one dependency for all approved Console-facing service clients. Do not install independent service-client, runtime, Configuration, Artifact, Registry, or OCI packages.

Define a module and use its owning service

import type { ConsolePageProps } from "@zephytiju/console-sdk";
import {
  defineConsoleModule,
  defineService,
} from "@zephytiju/console-sdk";
import { createClient as createAxiomClient } from "@zephytiju/juntai-typescript-sdk/services/domain.axiom";

function ApplicationDetails({ context }: ConsolePageProps) {
  const appId = context.route.params.appId;
  const axiom = createAxiomClient({
    baseUrl: "/api/axiom/v1",
    fetch: context.fetch,
  });
  // This page calls only Axiom's browser-facing API through `axiom`.
  void axiom;
  return <main>Application {appId}</main>;
}

const workflows = defineService({
  id: "axiom.workflow",
  ownerModuleId: "axiom",
  displayName: { defaultMessage: "Workflows" },
  summary: { defaultMessage: "Create, run, and inspect Axiom workflows." },
  category: "AI & Automation",
  tags: ["workflow", "execution"],
  icon: { name: "workflow" },
  discoveryPermissions: [{ resource: "axiom/workflows", action: "read" }],
  pages: [
    {
      id: "details",
      kind: "manage",
      path: "/applications/:appId",
      label: { defaultMessage: "Application" },
      load: async () => ({ default: ApplicationDetails }),
    },
  ],
});

export const axiomConsoleModule = defineConsoleModule({
  id: "axiom",
  version: "2.3.0",
  owner: { team: "axiom", repository: "zephytiju/JuntaiAxiomConsole" },
  compatibility: {
    console: "^1",
    sdk: "^2",
    react: "^19",
    typescriptSdk: "^1",
  },
  register(registrar) {
    registrar.registerService(workflows);
  },
});

Registration is synchronous, deterministic, side-effect-free, and limited to descriptors and lazy imports. It never performs service-client construction, network discovery, Registry lookup, or runtime registration. JuntaiConsole composes approved Micro-UIs explicitly at build time.

Blueprint uses Blueprint Service only

import type { ConsolePageContext } from "@zephytiju/console-sdk";
import { createClient as createBlueprintClient } from "@zephytiju/juntai-typescript-sdk/services/platform.blueprint";

type BlueprintClient = ReturnType<typeof createBlueprintClient>;
type BlueprintInput = Parameters<BlueprintClient["create"]>[0]["body"];

export async function createBlueprint(
  context: ConsolePageContext,
  blueprintInput: BlueprintInput,
): Promise<void> {
  const blueprints = createBlueprintClient({
    baseUrl: "/api/blueprints/v1",
    fetch: context.fetch,
  });
  await blueprints.create({ body: blueprintInput });
}

There is no browser fallback to Configuration, Artifact, Registry, OCI, or another service. Blueprint Service owns those backend workflows.

Contribute a Blueprint asset route

import {
  createBlueprintAssetNavigationTarget,
  defineBlueprintAssetContribution,
} from "@zephytiju/console-sdk";

export const latticeBlueprintContribution =
  defineBlueprintAssetContribution({
    domain: "lattice",
    domainDisplayName: "Lattice",
    assetKinds: [
      "ontology.bundle",
      "ontology.model",
      "ontology.relation",
    ],
    routeKey: "lattice.blueprint.asset",
    openActionLabel: "Open in Lattice",
    load: () => import("./pages/BlueprintAsset.js"),
    parameters: [
      "blueprintAssetId",
      "blueprintVersionId",
      "intent",
      "targetApplicationId",
      "targetRevision",
    ],
  });

const target = createBlueprintAssetNavigationTarget(
  latticeBlueprintContribution,
  {
    blueprintAssetId: "asset-42",
    blueprintVersionId: "version-7",
    intent: "derive_bundle",
    targetIds: { targetApplicationId: "application-9" },
  },
);

The shell resolves the build-time routeKey; all route values are flattened strings. domain + assetKind and contribution route keys are globally unique. The catalog compiler fails closed on missing, duplicate, incompatible, or undeclared contributions. Blueprint records, domain semantics, object snapshots, callbacks, and client instances never enter this SDK contract. resolveBlueprintAssetContribution returns stable missing, ambiguous, or incompatible unavailable codes so the gallery can render a disabled reason.

Contribute documentation routes

import {
  defineDocumentationProviderContribution,
  defineDocumentationViewerContribution,
} from "@zephytiju/console-sdk";

export const documentationViewer = defineDocumentationViewerContribution({
  serviceId: "platform.documentation",
  pages: ["catalog", "bundle", "application-version"],
  layoutProfile: "juntai.documentation.standard/v1",
  parameters: [
    "applicationId", "applicationVersionId",
    "ownerKey", "contributionKey", "bundleDigest", "unitId",
  ],
});

export const latticeDocumentation = defineDocumentationProviderContribution({
  ownerKey: "lattice",
  routeKey: "lattice.documentation",
  capability: "platform.documentation.provider",
  parameters: [
    "applicationId", "applicationVersionId",
    "contributionKey", "bundleDigest", "unitId",
  ],
  load: () => import("./pages/Documentation.js"),
});

Application-version navigation carries only applicationId and applicationVersionId. A selected restricted entry carries the five declared provider scalars. The provider imports the shared viewer components and calls its own authorized backend; Console SDK owns no documentation content, bundle bytes, catalog records, backend client, OCI coordinate, or authorization. resolveDocumentationProviderContribution likewise resolves only the exact build-time ownerKey + routeKey pair and returns a stable unavailable reason.

Modules attach these descriptor arrays through the additive ConsoleModule.contributions field; their existing synchronous register function remains limited to discoverable services. The testing entry point exposes compileConsoleCatalog plus contribution and direct-entry fixtures so duplicate Blueprint keys, duplicate documentation provider keys, route collisions, and module incompatibility fail CI before a Console bundle is produced.

Backend-only Python client names

Owning backend services, including Blueprint Service, install the high-level Python distributions below when their workflows require them. This is a backend deployment command, never a Micro-UI or npm dependency:

python -m pip install juntai-configuration-client juntai-artifact-client

Their stable Python imports remain:

import juntai.configuration
import juntai.artifact

The browser still calls only its owning service through @zephytiju/juntai-typescript-sdk; internal Registry gRPC and OCI access remain behind these backend Python clients.

Bounded page context

ConsolePageContext provides validated route parameters, principal and tenant display context, locale, theme, identifier-only navigation, notifications, correlation IDs, and session-aware fetch. It does not provide Registry endpoints, Registry clients, OCI credentials or transports, generated service client instances, Configuration or Artifact client instances, service tokens, mutable domain stores, or shell internals.

Navigation accepts only registered service/page IDs, scalar path parameters, and scalar or string-array query hints. Tenant overrides, secrets, credentials, object snapshots, callbacks, stores, client instances, Registry references, and OCI locators are not part of the contract. Destination pages construct only their owning service module from @zephytiju/juntai-typescript-sdk and refetch authoritative state with context.fetch.

Validate and test a contributor

import { render, screen } from "@testing-library/react";
import {
  ConsolePageTestHarness,
  assertDeterministicConsoleModule,
  createConsolePageContext,
} from "@zephytiju/console-sdk/testing";

assertDeterministicConsoleModule(axiomConsoleModule, {
  compatibilityTarget: {
    consoleVersion: "1.8.0",
    sdkVersion: "2.1.0",
    reactVersion: "19.2.7",
    typescriptSdkVersion: "1.1.0",
  },
});

const context = createConsolePageContext({
  route: {
    serviceId: "axiom.workflow",
    pageId: "details",
    params: { appId: "app-42" },
  },
});

render(
  <ConsolePageTestHarness
    loader={workflows.pages[0].load}
    context={context}
  />,
);
await screen.findByText("Application app-42");

The testing entry point contains deterministic fixtures, a recording registrar, a registration network guard, compatibility assertions, lazy-module validation, and a real React harness using the exact <Page context={context} /> handshake.

Verification and release

npm run verify enforces the repository and service-client boundaries, checks public TypeScript examples, runs validation/compatibility/registration and negative boundary tests, mounts real lazy React pages, builds declarations and ESM, packs the exact artifact, installs it into a clean offline consumer, compiles that consumer, and renders a real page component. It also installs the immutable public @zephytiju/[email protected] release into a second clean consumer and compiles a real owning-service client with Console's bounded session-aware fetch.

The initial 1.0.0 package bootstrap was authenticated by its npm owner. Later versions are published to https://registry.npmjs.org/ only by .github/workflows/publish-npm.yml from zephytiju/JuntaiConsoleSDK. Its npm Trusted Publisher identity is owner zephytiju, repository JuntaiConsoleSDK, workflow publish-npm.yml, and environment npm.

Serialized return targets and page capabilities (2.2)

serializeConsoleReturnTarget emits canonical version-1 JSON for an exact registered service/page and scalar params/query. Pass the resulting string as one query value to context.navigate; the host router performs URL encoding. parseConsoleReturnTarget accepts the exact decoded wire format and returns an available target or a typed unavailable reason. It rejects duplicate JSON members/query values, unsupported versions, nested values, prototype keys, tenant overrides, credentials, snapshots, redirects and nested return targets. Values are locators; destinations must refetch their own authority.

import { parseConsoleReturnTarget, serializeConsoleReturnTarget } from "@zephytiju/console-sdk";
const returnTarget = serializeConsoleReturnTarget({
  serviceId: "domain.service", pageId: "review",
  params: { applicationId: "app-exact", revisionId: "revision-exact" },
});
const parsed = parseConsoleReturnTarget(returnTarget);
if (parsed.status === "available") context.navigate(parsed.target);

Pages may add capabilities: readonly string[]; existing registrations remain valid. Duplicate capabilities within a page are invalid. Different pages may advertise the same capability so a domain can present explicit provider choices. The host supplies optional context.catalog version 1 with findPages(capability) and resolveTarget(target). Its immutable results contain identifiers, labels, parameter names and capabilities, never loaders or mutable host registrations. The SDK defines this contract; JuntaiConsole implements the actual projection. A missing catalog means the host cannot support the flow. It does not permit a consumer to invent a provider or bypass module compatibility.