@honua/react 0.0.20-alpha.0

package/studio/capability-manifest.js

@@ -0,0 +1,59 @@
+/**
+ * Client projection of the server capability manifest — the server-advertised
+ * set of package families, feature capabilities, transports, limits, and policy
+ * state a Console/MCP/QGIS client may rely on. Lets a client gate UI and tool
+ * exposure on what the connected server actually supports for the current
+ * tenant, workspace, environment, and caller policy scope rather than
+ * hard-coding assumptions.
+ *
+ * These shapes mirror the frozen server wire contract
+ * `honua.capability_manifest.v1` (honua-server `CapabilityManifestService` /
+ * `CapabilityManifestDocument`, PR #2356) and are the TypeScript analogue of the
+ * honua-sdk-dotnet `CapabilityManifest` / `CapabilityEntry` projection
+ * (honua-sdk-dotnet PR #253). The wire is frozen; field names, the
+ * `supported`/`available` split, and the reason-code surface are stable, so
+ * these shapes are no longer marked `@experimental`. Fetch a manifest with the
+ * control-plane client's `getCapabilityManifest()`.
+ *
+ * @module
+ */
+/**
+ * Return the capability entry with the given id, or `undefined` if the
+ * manifest does not advertise it (regardless of supported/available state).
+ * Mirrors the .NET `CapabilityManifest.GetCapability`.
+ */
+export function getCapability(manifest, id) {
+    return manifest.capabilities.find((entry) => entry.id === id);
+}
+/**
+ * Return `true` when the manifest advertises the capability as available in the
+ * current scope. Mirrors the .NET `CapabilityManifest.IsAvailable`.
+ */
+export function hasCapability(manifest, id) {
+    return getCapability(manifest, id)?.available === true;
+}
+/**
+ * Return `true` when the server implements the capability at all, even if it is
+ * not currently available (for example gated by edition or entitlement).
+ * Inspect {@link getCapabilityReasonCode} to explain an unavailable but
+ * supported capability. Mirrors the .NET `CapabilityManifest.IsSupported`.
+ */
+export function isCapabilitySupported(manifest, id) {
+    return getCapability(manifest, id)?.supported === true;
+}
+/**
+ * Return the machine-friendly reason code explaining a capability's
+ * availability state, or `undefined` when unknown or the capability is
+ * unrecognized. Mirrors the .NET `CapabilityManifest.GetReasonCode`.
+ */
+export function getCapabilityReasonCode(manifest, id) {
+    return getCapability(manifest, id)?.reasonCode;
+}
+/**
+ * Return `true` when the server advertises a supported package family with the
+ * given identifier (for example `map`). Mirrors the .NET
+ * `CapabilityManifest.HasPackageFamily`.
+ */
+export function hasPackageFamily(manifest, familyId) {
+    return manifest.packages?.families?.some((family) => family.id === familyId && family.supported) === true;
+}

package/studio/chart-spec.d.ts

@@ -0,0 +1,85 @@
+/**
+ * A documented, compatible subset of the Vega-Lite v5 spec used by Studio
+ * dashboard and report charts. The acceptance criterion for cross-surface
+ * parity is that "dashboard/report charts use Vega-Lite specs or an explicitly
+ * documented compatible subset" — this module is that documented subset, plus
+ * a pure helper that derives a spec from a generated-app chart widget so MCP,
+ * QGIS, Console, and the SDK preview runtime all render the same chart.
+ *
+ * The subset is intentionally narrow: bar / arc / line / point marks over a
+ * single positional encoding pair plus an optional color channel. It is a
+ * structural subset of a real Vega-Lite `TopLevelSpec`, so a host may hand the
+ * object directly to `vega-embed` / `vega-lite` without translation, while the
+ * SDK stays free of a Vega dependency (these are plain data types).
+ *
+ * @experimental Not yet covered by the SDK's semver contract — these shapes
+ *   may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+import type { HonuaGeneratedAppChartWidget } from "../generated-app/manifest.js";
+/** Vega-Lite schema URL this subset targets. */
+export declare const HONUA_VEGA_LITE_SCHEMA_V5: "https://vega.github.io/schema/vega-lite/v5.json";
+/** Mark types in the supported subset. */
+export type HonuaChartMark = "bar" | "line" | "point" | "arc";
+/** Encoding field type in the supported subset. */
+export type HonuaChartFieldType = "quantitative" | "nominal" | "ordinal" | "temporal";
+/**
+ * One positional / visual encoding channel. A structural subset of a
+ * Vega-Lite `FieldDef`.
+ *
+ * @experimental
+ */
+export interface HonuaChartEncodingChannel {
+    readonly field: string;
+    readonly type: HonuaChartFieldType;
+    readonly title?: string;
+    readonly aggregate?: "count" | "sum" | "mean" | "min" | "max" | "median";
+    readonly timeUnit?: string;
+    readonly bin?: boolean | {
+        readonly maxbins?: number;
+    };
+}
+/**
+ * The encoding block. `x`/`y` are the positional pair; `color` is optional.
+ *
+ * @experimental
+ */
+export interface HonuaChartEncoding {
+    readonly x?: HonuaChartEncodingChannel;
+    readonly y?: HonuaChartEncodingChannel;
+    readonly color?: HonuaChartEncodingChannel;
+}
+/**
+ * The documented Vega-Lite-compatible chart spec. Inline `data.values` carry
+ * the rows; a host may instead point `data.name` at a named dataset. The
+ * `$schema` and structural layout make this directly consumable by Vega-Lite.
+ *
+ * @experimental
+ */
+export interface HonuaVegaLiteChartSpec {
+    readonly $schema: typeof HONUA_VEGA_LITE_SCHEMA_V5;
+    readonly title?: string;
+    readonly description?: string;
+    readonly mark: HonuaChartMark | {
+        readonly type: HonuaChartMark;
+        readonly tooltip?: boolean;
+    };
+    readonly encoding: HonuaChartEncoding;
+    readonly data?: {
+        readonly values?: ReadonlyArray<Record<string, unknown>>;
+        readonly name?: string;
+    };
+    readonly width?: number | "container";
+    readonly height?: number | "container";
+}
+/**
+ * Derive a {@link HonuaVegaLiteChartSpec} from a generated-app chart widget so
+ * dashboard and report charts render identically across surfaces. `rows`, when
+ * supplied, become inline `data.values`; otherwise the host binds a named
+ * dataset. Returns `undefined` when the widget lacks the field needed for its
+ * chart kind (so a caller can degrade cleanly rather than emit a broken spec).
+ *
+ * @experimental
+ */
+export declare function chartWidgetToVegaLiteSpec(widget: HonuaGeneratedAppChartWidget, rows?: ReadonlyArray<Record<string, unknown>>): HonuaVegaLiteChartSpec | undefined;
+//# sourceMappingURL=chart-spec.d.ts.map

package/studio/chart-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-spec.d.ts","sourceRoot":"","sources":["../../../src/studio/chart-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAEjF,gDAAgD;AAChD,eAAO,MAAM,yBAAyB,EAAG,iDAA0D,CAAC;AAEpG,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAE9D,mDAAmD;AACnD,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAEtF;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,CAAC,CAAC,EAAE,yBAAyB,CAAC;IACvC,QAAQ,CAAC,CAAC,CAAC,EAAE,yBAAyB,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,yBAAyB,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,yBAAyB,CAAC;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC9F,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE;QACd,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;CACxC;AAYD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,4BAA4B,EACpC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC5C,sBAAsB,GAAG,SAAS,CAiDpC"}

package/studio/chart-spec.js

@@ -0,0 +1,106 @@
+/**
+ * A documented, compatible subset of the Vega-Lite v5 spec used by Studio
+ * dashboard and report charts. The acceptance criterion for cross-surface
+ * parity is that "dashboard/report charts use Vega-Lite specs or an explicitly
+ * documented compatible subset" — this module is that documented subset, plus
+ * a pure helper that derives a spec from a generated-app chart widget so MCP,
+ * QGIS, Console, and the SDK preview runtime all render the same chart.
+ *
+ * The subset is intentionally narrow: bar / arc / line / point marks over a
+ * single positional encoding pair plus an optional color channel. It is a
+ * structural subset of a real Vega-Lite `TopLevelSpec`, so a host may hand the
+ * object directly to `vega-embed` / `vega-lite` without translation, while the
+ * SDK stays free of a Vega dependency (these are plain data types).
+ *
+ * @experimental Not yet covered by the SDK's semver contract — these shapes
+ *   may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+/** Vega-Lite schema URL this subset targets. */
+export const HONUA_VEGA_LITE_SCHEMA_V5 = "https://vega.github.io/schema/vega-lite/v5.json";
+/**
+ * Map a generated-app chart widget kind to a Vega-Lite mark and the encoding
+ * shape the subset expects.
+ */
+const CHART_KIND_MARK = {
+    categories: "bar",
+    histogram: "bar",
+    "time-series": "line",
+};
+/**
+ * Derive a {@link HonuaVegaLiteChartSpec} from a generated-app chart widget so
+ * dashboard and report charts render identically across surfaces. `rows`, when
+ * supplied, become inline `data.values`; otherwise the host binds a named
+ * dataset. Returns `undefined` when the widget lacks the field needed for its
+ * chart kind (so a caller can degrade cleanly rather than emit a broken spec).
+ *
+ * @experimental
+ */
+export function chartWidgetToVegaLiteSpec(widget, rows) {
+    const chartKind = widget.chartKind ?? "categories";
+    const mark = CHART_KIND_MARK[chartKind];
+    let encoding;
+    if (chartKind === "categories") {
+        const category = widget.groupBy ?? widget.field;
+        if (!category)
+            return undefined;
+        encoding = {
+            x: { field: category, type: "nominal", title: widget.title },
+            y: { field: "count", type: "quantitative", aggregate: "count", title: "Count" },
+        };
+    }
+    else if (chartKind === "histogram") {
+        if (!widget.field)
+            return undefined;
+        encoding = {
+            x: {
+                field: widget.field,
+                type: "quantitative",
+                bin: widget.bins ? { maxbins: widget.bins } : true,
+                title: widget.title ?? widget.field,
+            },
+            y: { field: "count", type: "quantitative", aggregate: "count", title: "Count" },
+        };
+    }
+    else {
+        // time-series
+        const timeField = widget.field ?? widget.groupBy;
+        if (!timeField)
+            return undefined;
+        const valueChannel = widget.metric
+            ? {
+                field: widget.metric.field === "*" ? "count" : widget.metric.field,
+                type: "quantitative",
+                aggregate: metricToAggregate(widget.metric.fn),
+                title: widget.metric.alias ?? widget.metric.field,
+            }
+            : { field: "count", type: "quantitative", aggregate: "count", title: "Count" };
+        encoding = {
+            x: { field: timeField, type: "temporal", title: widget.title ?? timeField },
+            y: valueChannel,
+        };
+    }
+    return {
+        $schema: HONUA_VEGA_LITE_SCHEMA_V5,
+        ...(widget.title ? { title: widget.title } : {}),
+        mark: { type: mark, tooltip: true },
+        encoding,
+        width: "container",
+        ...(rows ? { data: { values: rows } } : {}),
+    };
+}
+function metricToAggregate(metric) {
+    switch (metric) {
+        case "sum":
+            return "sum";
+        case "avg":
+        case "mean":
+            return "mean";
+        case "min":
+            return "min";
+        case "max":
+            return "max";
+        default:
+            return "count";
+    }
+}

package/studio/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `@honua/sdk-js/studio` — browser-safe TypeScript projections, validation and
+ * preview envelopes, capability-manifest types, and publish/share/embed
+ * contracts for the Studio package families.
+ *
+ * This barrel is intentionally MCP/QGIS-safe: it exports only types and pure
+ * functions and never imports from `operator`, `esri-compat`, `web-components`,
+ * `interactions`, or `realtime` (which pull in MapLibre / DOM code). The
+ * established `map` and `dashboard`/`app` shapes are re-exported from their
+ * leaf modules so consumers reach every family from one import path.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`, and the
+ *   stub families may change again when their server contracts ship.
+ * @module
+ */
+export { HONUA_ANALYSIS_PACKAGE_FORMAT_V1, HONUA_ETL_PACKAGE_FORMAT_V1, HONUA_FORM_PACKAGE_FORMAT_V1, HONUA_GP_PACKAGE_FORMAT_V1, HONUA_QUERY_PACKAGE_FORMAT_V1, HONUA_REPORT_PACKAGE_FORMAT_V1, HONUA_WORKFLOW_PACKAGE_FORMAT_V1, STUDIO_PACKAGE_FAMILIES, isStudioPackageFamily, tagStudioPackage, } from "./types.js";
+export type { HonuaAnalysisPackage, HonuaAnalysisPackageFormat, HonuaETLPackage, HonuaETLPackageFormat, HonuaFormFieldSpec, HonuaFormPackage, HonuaFormPackageFormat, HonuaGPPackage, HonuaGPPackageFormat, HonuaGPParameterSpec, HonuaQueryPackage, HonuaQueryPackageFormat, HonuaReportPackage, HonuaReportPackageFormat, HonuaReportSectionSpec, HonuaStudioBindingRef, HonuaStudioPackage, HonuaStudioPackageBase, HonuaStudioPackageFamily, HonuaStudioPackageStatus, HonuaStudioQuerySpec, HonuaWorkflowPackage, HonuaWorkflowPackageFormat, HonuaWorkflowStepSpec, StudioPackageFamilyShapes, } from "./types.js";
+export { fromMapPackageValidation, toStudioValidationResponse } from "./validation.js";
+export type { StudioPackageDiagnostic, StudioPackageDiagnosticSeverity, StudioPackagePreviewResponse, StudioPackageValidationResponse, StudioPreviewArtifactRef, } from "./validation.js";
+export { validatePackageProvenance, validateStudioPackage } from "./validate.js";
+export type { ValidateStudioPackageOptions } from "./validate.js";
+export { HONUA_PACKAGE_PROVENANCE_FORMAT_V1, getPackageProvenance } from "./provenance.js";
+export type { HonuaPackageOrigin, HonuaPackagePermission, HonuaPackageProvenance, HonuaPackageProvenanceFormat, HonuaPlanProvenance, HonuaPlanStep, HonuaPromptProvenance, HonuaProvenanceDataBinding, } from "./provenance.js";
+export { HONUA_VEGA_LITE_SCHEMA_V5, chartWidgetToVegaLiteSpec } from "./chart-spec.js";
+export type { HonuaChartEncoding, HonuaChartEncodingChannel, HonuaChartFieldType, HonuaChartMark, HonuaVegaLiteChartSpec, } from "./chart-spec.js";
+export { getCapability, getCapabilityReasonCode, hasCapability, hasPackageFamily, isCapabilitySupported, } from "./capability-manifest.js";
+export type { StudioCapabilityAnalysisLimits, StudioCapabilityAttachmentLimits, StudioCapabilityEditLimits, StudioCapabilityEntitlementDecision, StudioCapabilityEntry, StudioCapabilityEnvironment, StudioCapabilityGeometryLimits, StudioCapabilityJobLimits, StudioCapabilityLimits, StudioCapabilityLink, StudioCapabilityManifest, StudioCapabilityPackageFamily, StudioCapabilityPackages, StudioCapabilityPolicies, StudioCapabilityPreviewLimits, StudioCapabilityPublicationLimits, StudioCapabilityQueryLimits, StudioCapabilityScope, StudioCapabilityServerInfo, StudioCapabilityStreamingLimits, StudioCapabilityTransports, StudioCapabilityTransportState, StudioCapabilityUploadLimits, } from "./capability-manifest.js";
+export type { HonuaShareRequest, HonuaShareResponse, StudioEmbedConfig, StudioPublishRequest, StudioPublishResponse, } from "./publish.js";
+export { HONUA_MAP_PACKAGE_FORMAT_V1 } from "../runtime/map-package.js";
+export type { HonuaMapPackage, HonuaMapPackageFormat } from "../runtime/map-package.js";
+export { HONUA_GENERATED_APP_MANIFEST_FORMAT_V1 } from "../generated-app/manifest.js";
+export type { HonuaGeneratedAppManifest, HonuaGeneratedAppPackage } from "../generated-app/manifest.js";
+//# sourceMappingURL=index.d.ts.map

package/studio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/studio/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,gCAAgC,EAChC,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,6BAA6B,EAC7B,8BAA8B,EAC9B,gCAAgC,EAChC,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AACvF,YAAY,EACV,uBAAuB,EACvB,+BAA+B,EAC/B,4BAA4B,EAC5B,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACjF,YAAY,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,EAAE,kCAAkC,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3F,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,4BAA4B,EAC5B,mBAAmB,EACnB,aAAa,EACb,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACvF,YAAY,EACV,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,EACd,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,aAAa,EACb,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,8BAA8B,EAC9B,gCAAgC,EAChC,0BAA0B,EAC1B,mCAAmC,EACnC,qBAAqB,EACrB,2BAA2B,EAC3B,8BAA8B,EAC9B,yBAAyB,EACzB,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,EACxB,wBAAwB,EACxB,6BAA6B,EAC7B,iCAAiC,EACjC,2BAA2B,EAC3B,qBAAqB,EACrB,0BAA0B,EAC1B,+BAA+B,EAC/B,0BAA0B,EAC1B,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAElC,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAKtB,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACxF,OAAO,EAAE,sCAAsC,EAAE,MAAM,8BAA8B,CAAC;AACtF,YAAY,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC"}

package/studio/index.js

@@ -0,0 +1,27 @@
+/**
+ * `@honua/sdk-js/studio` — browser-safe TypeScript projections, validation and
+ * preview envelopes, capability-manifest types, and publish/share/embed
+ * contracts for the Studio package families.
+ *
+ * This barrel is intentionally MCP/QGIS-safe: it exports only types and pure
+ * functions and never imports from `operator`, `esri-compat`, `web-components`,
+ * `interactions`, or `realtime` (which pull in MapLibre / DOM code). The
+ * established `map` and `dashboard`/`app` shapes are re-exported from their
+ * leaf modules so consumers reach every family from one import path.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`, and the
+ *   stub families may change again when their server contracts ship.
+ * @module
+ */
+export { HONUA_ANALYSIS_PACKAGE_FORMAT_V1, HONUA_ETL_PACKAGE_FORMAT_V1, HONUA_FORM_PACKAGE_FORMAT_V1, HONUA_GP_PACKAGE_FORMAT_V1, HONUA_QUERY_PACKAGE_FORMAT_V1, HONUA_REPORT_PACKAGE_FORMAT_V1, HONUA_WORKFLOW_PACKAGE_FORMAT_V1, STUDIO_PACKAGE_FAMILIES, isStudioPackageFamily, tagStudioPackage, } from "./types.js";
+export { fromMapPackageValidation, toStudioValidationResponse } from "./validation.js";
+export { validatePackageProvenance, validateStudioPackage } from "./validate.js";
+export { HONUA_PACKAGE_PROVENANCE_FORMAT_V1, getPackageProvenance } from "./provenance.js";
+export { HONUA_VEGA_LITE_SCHEMA_V5, chartWidgetToVegaLiteSpec } from "./chart-spec.js";
+export { getCapability, getCapabilityReasonCode, hasCapability, hasPackageFamily, isCapabilitySupported, } from "./capability-manifest.js";
+// Re-exported established families so `@honua/sdk-js/studio` is the single
+// import path for every Studio package projection. These leaf modules carry
+// no MapLibre/DOM runtime imports (their cross-module imports are type-only).
+export { HONUA_MAP_PACKAGE_FORMAT_V1 } from "../runtime/map-package.js";
+export { HONUA_GENERATED_APP_MANIFEST_FORMAT_V1 } from "../generated-app/manifest.js";

package/studio/provenance.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Shared provenance contract carried by AI-generated Studio packages
+ * (map, dashboard, report, app, and the stub families) regardless of which
+ * surface produced them — Honua Studio/Console, an MCP client, or the QGIS
+ * plugin.
+ *
+ * Parity goal: a package generated through MCP or QGIS records the same
+ * prompt / plan / data-binding / permission / origin provenance as one
+ * generated in Console, so the SDK can validate, attribute, and preview it
+ * with one contract. The shape is intentionally additive and open-ended —
+ * unknown fields are preserved through `[extra: string]: unknown` so a newer
+ * generator never breaks an older client.
+ *
+ * @experimental Not yet covered by the SDK's semver contract — these shapes
+ *   may change in any minor release prior to `1.0.0` and before the matching
+ *   server contracts ship.
+ * @module
+ */
+/** Canonical format string for the v1 package-provenance shape. */
+export declare const HONUA_PACKAGE_PROVENANCE_FORMAT_V1: "honua_package_provenance.v1";
+export type HonuaPackageProvenanceFormat = typeof HONUA_PACKAGE_PROVENANCE_FORMAT_V1;
+/**
+ * The surface that produced a package. Used to attribute generation and to
+ * gate which capabilities a host may assume (e.g. QGIS-origin packages cannot
+ * assume Console-only server execution).
+ *
+ * @experimental
+ */
+export type HonuaPackageOrigin = "console" | "studio" | "mcp" | "qgis" | "sdk" | (string & {});
+/**
+ * The natural-language prompt and any structured instructions that drove an
+ * AI generation. `surface` records which client captured the prompt so MCP
+ * and QGIS flows carry the same shape as Console.
+ *
+ * @experimental
+ */
+export interface HonuaPromptProvenance {
+    readonly text?: string;
+    readonly system?: string;
+    readonly surface?: HonuaPackageOrigin;
+    readonly model?: string;
+    readonly capturedAt?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * One step in the generation plan the agent followed to produce the package.
+ *
+ * @experimental
+ */
+export interface HonuaPlanStep {
+    readonly id?: string;
+    readonly kind?: string;
+    readonly summary?: string;
+    readonly toolName?: string;
+    readonly status?: "planned" | "succeeded" | "failed" | "skipped" | (string & {});
+    readonly [extra: string]: unknown;
+}
+/**
+ * The plan an agent executed — an ordered list of steps plus an optional
+ * free-text rationale. Mirrors what Console records so MCP/QGIS-generated
+ * packages can be inspected identically.
+ *
+ * @experimental
+ */
+export interface HonuaPlanProvenance {
+    readonly steps?: readonly HonuaPlanStep[];
+    readonly rationale?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * One data binding referenced by a package's provenance: which source (and
+ * optionally which query/layer) the generated output reads. This duplicates
+ * just enough of the per-family binding to let a validator confirm the
+ * package's declared inputs without loading every family-specific spec.
+ *
+ * @experimental
+ */
+export interface HonuaProvenanceDataBinding {
+    readonly sourceId: string;
+    readonly title?: string;
+    readonly protocol?: string;
+    readonly queryId?: string;
+    readonly layerId?: string;
+    readonly role?: "primary" | "secondary" | "lookup" | (string & {});
+    readonly [extra: string]: unknown;
+}
+/**
+ * A single permission the package requires to render or execute. `scope`
+ * names the capability (e.g. `"source:read"`, `"server:execute"`) and
+ * `clientSide` records whether the SDK can satisfy it in a browser preview
+ * (`true`) or whether it requires server execution (`false`).
+ *
+ * @experimental
+ */
+export interface HonuaPackagePermission {
+    readonly scope: string;
+    readonly resource?: string;
+    readonly clientSide?: boolean;
+    readonly description?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * Provenance envelope attached to a generated package, consistently shaped
+ * across Console, MCP, and QGIS. Attach it under a package's `provenance`
+ * field (every family carries an open `[extra]` index signature) so the SDK
+ * validator and preview helpers can read one contract.
+ *
+ * @experimental
+ */
+export interface HonuaPackageProvenance {
+    readonly format: HonuaPackageProvenanceFormat;
+    readonly origin: HonuaPackageOrigin;
+    /** Stable id of the package this provenance describes, when known. */
+    readonly packageId?: string;
+    readonly generatedAt?: string;
+    /** Generator/tool identifier, e.g. `"honua-mcp@1.4.0"` or `"qgis-plugin@0.3"`. */
+    readonly generator?: string;
+    readonly prompt?: HonuaPromptProvenance;
+    readonly plan?: HonuaPlanProvenance;
+    readonly dataBindings?: readonly HonuaProvenanceDataBinding[];
+    readonly permissions?: readonly HonuaPackagePermission[];
+    readonly [extra: string]: unknown;
+}
+/**
+ * Read the provenance envelope off any package value, or `undefined` when it
+ * is absent or malformed. Does not throw on untrusted input.
+ *
+ * @experimental
+ */
+export declare function getPackageProvenance(pkg: unknown): HonuaPackageProvenance | undefined;
+//# sourceMappingURL=provenance.d.ts.map

package/studio/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../../src/studio/provenance.ts"],"names":[],"mappings":"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"}

package/studio/provenance.js

@@ -0,0 +1,39 @@
+/**
+ * Shared provenance contract carried by AI-generated Studio packages
+ * (map, dashboard, report, app, and the stub families) regardless of which
+ * surface produced them — Honua Studio/Console, an MCP client, or the QGIS
+ * plugin.
+ *
+ * Parity goal: a package generated through MCP or QGIS records the same
+ * prompt / plan / data-binding / permission / origin provenance as one
+ * generated in Console, so the SDK can validate, attribute, and preview it
+ * with one contract. The shape is intentionally additive and open-ended —
+ * unknown fields are preserved through `[extra: string]: unknown` so a newer
+ * generator never breaks an older client.
+ *
+ * @experimental Not yet covered by the SDK's semver contract — these shapes
+ *   may change in any minor release prior to `1.0.0` and before the matching
+ *   server contracts ship.
+ * @module
+ */
+/** Canonical format string for the v1 package-provenance shape. */
+export const HONUA_PACKAGE_PROVENANCE_FORMAT_V1 = "honua_package_provenance.v1";
+/**
+ * Read the provenance envelope off any package value, or `undefined` when it
+ * is absent or malformed. Does not throw on untrusted input.
+ *
+ * @experimental
+ */
+export function getPackageProvenance(pkg) {
+    if (!isRecord(pkg))
+        return undefined;
+    const provenance = pkg.provenance;
+    if (!isRecord(provenance))
+        return undefined;
+    if (provenance.format !== HONUA_PACKAGE_PROVENANCE_FORMAT_V1)
+        return undefined;
+    return provenance;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/studio/publish.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Versioned publication, share, and embed request/response contracts for
+ * generated Studio artifacts. These extend the established control-plane
+ * patterns: {@link HonuaShareRequest} / {@link HonuaShareResponse} are
+ * re-exported from `control-plane/types` (single source of truth — not
+ * re-declared) so Console and MCP can reach the share contract from the one
+ * `@honua/sdk-js/studio` path without taking on the full control-plane client.
+ *
+ * @experimental Not yet covered by the SDK's semver contract — these shapes
+ *   may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+import type { HonuaStudioPackage, HonuaStudioPackageFamily } from "./types.js";
+export type { HonuaShareRequest, HonuaShareResponse } from "../control-plane/types.js";
+/**
+ * Request to publish a Studio package of any family.
+ *
+ * @experimental
+ */
+export interface StudioPublishRequest<T = HonuaStudioPackage> {
+    readonly packageFamily: HonuaStudioPackageFamily | (string & {});
+    readonly package: T;
+    readonly title?: string;
+    readonly description?: string;
+    readonly workspaceId?: string;
+    readonly visibility?: "private" | "workspace" | "public" | (string & {});
+    readonly message?: string;
+    readonly ifMatch?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * Response from publishing a Studio package.
+ *
+ * @experimental
+ */
+export interface StudioPublishResponse {
+    readonly packageId: string;
+    readonly packageFamily: HonuaStudioPackageFamily | (string & {});
+    readonly status?: string;
+    readonly job?: {
+        readonly id: string;
+        readonly status: string;
+        readonly [k: string]: unknown;
+    };
+    readonly links?: Record<string, string | undefined>;
+    readonly [extra: string]: unknown;
+}
+/**
+ * Client-side descriptor for embedding a published package. `token` and
+ * `embedUrl` are server-issued; this type only carries an already-issued
+ * descriptor — it does not imply a token-minting call within the SDK.
+ *
+ * @experimental
+ */
+export interface StudioEmbedConfig {
+    readonly packageId: string;
+    readonly packageFamily: HonuaStudioPackageFamily | (string & {});
+    readonly embedUrl?: string;
+    readonly token?: string;
+    readonly expiresAt?: string;
+    readonly options?: Record<string, unknown>;
+    readonly [extra: string]: unknown;
+}
+//# sourceMappingURL=publish.d.ts.map

package/studio/publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../../src/studio/publish.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAG/E,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEvF;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,kBAAkB;IAC1D,QAAQ,CAAC,aAAa,EAAE,wBAAwB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,wBAAwB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACpD,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,wBAAwB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC"}

package/studio/publish.js

@@ -0,0 +1,13 @@
+/**
+ * Versioned publication, share, and embed request/response contracts for
+ * generated Studio artifacts. These extend the established control-plane
+ * patterns: {@link HonuaShareRequest} / {@link HonuaShareResponse} are
+ * re-exported from `control-plane/types` (single source of truth — not
+ * re-declared) so Console and MCP can reach the share contract from the one
+ * `@honua/sdk-js/studio` path without taking on the full control-plane client.
+ *
+ * @experimental Not yet covered by the SDK's semver contract — these shapes
+ *   may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export {};