Honua.Sdk.Studio 1.13.1

Honua.Sdk.Studio

Browser-safe Console Studio clients and shared contracts for Honua Console hosts (Blazor Web and optional .NET MAUI Blazor Hybrid). The package ships three typed clients registered by a single AddHonuaStudio call:

• IHonuaStudioReportsClient — retrieve/render analysis reports.
• IHonuaCapabilityManifestClient — fetch the server capability manifest (GET /api/v1/capabilities/manifest, schema honua.capability_manifest.v1) to gate authoring UI and tool exposure on what the connected server supports.
• IHonuaStudioPackageClient — the Studio package lifecycle (/api/v1/studio/*): family capabilities, draft CRUD, validate, preview-plan, content-version, publish-request, reopen, and rollback across every in-scope package family (query, map, analysis, dashboard, report, form, app, workflow, gp, etl).

The projected shapes mirror the honua-sdk-js Studio contract (src/studio/{types,validation,capability-manifest}.ts) so the .NET and JS projections do not diverge.

Studio is Preview in 2026.1. It is not a GA surface.

Install

Stable releases are on nuget.org and install anonymously. An unversioned add resolves to the newest stable release (the current SDK version is in the repo README). Prereleases stay on the authenticated GitHub Packages feed; see INSTALL.md.

dotnet add package Honua.Sdk.Studio

using Honua.Sdk.Studio.Extensions;

builder.Services.AddHonuaStudio(o =>
{
    o.BaseAddress = new Uri("https://your-honua-server");
    o.BearerTokenProvider = tokenProvider.GetAccessTokenAsync;
});

Use IHonuaStudioReportsClient to fetch the structured report envelope and to render Markdown or HTML for completed geoprocessing jobs. The report contracts themselves live in Honua.Sdk.Abstractions (namespace Honua.Sdk.Abstractions.Studio) so browser and native hosts share one DTO set.

REST surface

The client targets the analysis-reporting surface under /api/v1/analysis/reports.

GetReportAsync returns HonuaAnalysisReport deserialized from the unwrapped server JSON (analysis reports are not wrapped in the Admin ApiResponse<T> envelope). RenderReportAsync requests text/markdown for format=md and text/html for format=html, then returns HonuaRenderedReport carrying the text body and media type. If the response omits Content-Type, the SDK reports the media type implied by the requested format.

var report = await studio.GetReportAsync(jobId, cancellationToken);

foreach (var section in report.Sections)
{
    switch (section)
    {
        case HonuaHeadingSection heading:
            Console.WriteLine(new string('#', heading.Level) + " " + heading.Text);
            break;
        case HonuaKeyMetricSection metric:
            Console.WriteLine($"{metric.Label}: {metric.Value} {metric.Unit}");
            break;
        // Add cases as the report contract adds section kinds; unknown kinds
        // surface as HonuaStudioContractException so drift is visible.
    }
}

var markdown = await studio.RenderReportAsync(
    jobId,
    HonuaReportRenderFormat.Markdown,
    cancellationToken);

Report sections

HonuaAnalysisReportSection is a polymorphic hierarchy keyed by the kind discriminator and resolved through a source-generated JSON context (trimming/AOT-safe). Modeled section kinds:

heading, paragraph, key-metric, table, chart, map-embed, narrative, provenance-footer.

The eight kinds are exhaustive within report contract version honua.report.v1. Gate on HonuaAnalysisReport.ReportContractVersion for version-level compatibility. New fields on a known kind are tolerated (ignored) on read; an entirely unmodeled kind within a supported contract version is genuine drift and surfaces as HonuaStudioContractException so it is caught loudly rather than silently dropped.

Errors

Non-success HTTP statuses throw HonuaStudioApiException (preserving StatusCode, problem Title/Detail, and the raw ResponseBody). Successful responses whose body does not satisfy the report contract throw HonuaStudioContractException.

Capability manifest

IHonuaCapabilityManifestClient.GetManifestAsync fetches the frozen honua.capability_manifest.v1 document into a CapabilityManifest. Query helpers mirror the JS getCapability/hasCapability helpers:

var manifest = await capabilities.GetManifestAsync(cancellationToken: ct);

if (manifest.IsAvailable("studio.map")) { /* enable the map builder */ }
if (!manifest.IsAvailable("studio.ai.generate"))
{
    var reason = manifest.GetReasonCode("studio.ai.generate"); // e.g. "entitlement-inactive"
}
if (manifest.HasPackageFamily("dashboard")) { /* show the dashboard family */ }

GetCapability(id) returns the full CapabilityEntry (Supported, Available, Lifecycle, OptInRequired, ReasonCode, EntitlementKey, MinimumEdition, …). Lifecycle and OptInRequired are required, server-owned governance fields; unknown lifecycle strings are preserved, while a missing field is treated as contract drift rather than silently defaulting to GA or no opt-in. The manifest also carries scope, server/environment info, transports, limits, and entitlement policy.

Studio package lifecycle

IHonuaStudioPackageClient covers the family-agnostic lifecycle; the family discriminant travels on StudioPackageEnvelope. The envelope's Bindings, Dependencies, and Provenance collections always serialize as arrays (the server rejects null for any of them).

var draft = await packages.CreateDraftAsync(new CreateStudioPackageDraftRequest
{
    PackageKey = "my-map",
    Envelope = new StudioPackageEnvelope
    {
        Family = StudioPackageFamily.Map,
        SchemaVersion = "honua_map_package.v1",
    },
}, ct);

var validation = await packages.ValidateDraftAsync(draft.DraftId, ct);
var plan = await packages.PreviewPlanAsync(draft.DraftId, ct);
var version = await packages.CreateContentVersionAsync(
    draft.DraftId, new SaveStudioContentVersionRequest { ChangeNote = "v1" }, ct);
var submission = await packages.SubmitPublishRequestAsync(
    version.ItemId, version.VersionId, new CreateStudioPublicationRequest(), ct);
if (submission.RequiresApproval)
{
    // Keep the saved version and previous published pointer unchanged.
    // A separate authorized actor reviews this proposal through the governance UI/API.
    Console.WriteLine($"Awaiting approval: {submission.Operation!.ProposalId}");
}
else
{
    Console.WriteLine($"Publication request: {submission.Publication!.Status}");
}

SubmitPublishRequestAsync distinguishes a HTTP 201 publication request from a HTTP 202 operation requiring approval. A pending operation has no publication request ID and is not evidence that the version was published. The SDK does not approve proposals, retry a submission automatically, or replace authorization. Malformed or ambiguous success payloads raise HonuaStudioContractException. Call GetContentItemPointersAsync(itemId) to refresh exact current/published version IDs after an authorized reviewer acts. This reads the existing scoped content-item listing, with cancellation, cursor-cycle protection and a 100-page limit. It returns null only after a complete visible listing omits the item; malformed or incomplete scans fail instead of fabricating absence. A proposal's success status alone is not proof of the currently published pointer. The existing CreatePublishRequestAsync signature remains available for callers that expect only completed publication-request responses. The new submission API requires a release after 1.9.0; it is not included in 1.9.0.

Content-hash verification and publication URL

A version read (GetVersionAsync) and the save response (CreateContentVersionAsync) carry ContentHashInput when the server supplies it (honua-server#5449): base64 of the exact bytes whose lower-case hex SHA-256 is ContentHash. Recompute the digest with version.VerifyContentHash() (or StudioContentHash.Verify(input, hash)) instead of re-serializing the envelope. It returns null when the server sent no input (version enumerations, servers that predate the field, bridged Form/Analysis versions), true on a match, and false on a mismatch or malformed base64.

An accepted publication request carries PublicationUrl (honua-server#5788), the root-relative published-route URL serving the Active version; it is null while pending, on a rejected request, and from servers that predate the field.

var saved = await packages.GetVersionAsync(itemId, versionId, ct);
if (saved.VerifyContentHash() == false)
{
    throw new InvalidOperationException("Content hash does not match its canonical input.");
}

Scope

AI generate endpoints (/api/v1/studio/{map,app}-packages/generate) return AI-specific result shapes and are tracked separately.

Documentation

• Console client contracts
• Client behavior
• Browser / WASM support
• Studio analysis report sample

Reading a final publication

Read the governed route to inspect the publication that viewers receive:

var artifact = await packages.GetPublishedArtifactAsync("approved-map", cancellationToken);
Console.WriteLine($"{artifact.PublicationId}: {artifact.VersionId} {artifact.ContentHash}");
var envelope = artifact.Envelope;

The response includes route, visibility, publication/item/version identifiers, version number, package key/family, content hash, publication time and the sealed package envelope. Supply the route key rather than a URL. Missing/inaccessible routes and server failures raise HonuaStudioApiException; malformed publication responses raise HonuaStudioContractException.