@kumwe/studio-protocol 0.1.0-alpha.6 → 0.1.0-beta.2

package/dist/types.d.ts

@@ -2,6 +2,11 @@ export declare const STUDIO_CONTRACT_VERSION: "0.1-draft";
 export type StudioContractVersion = typeof STUDIO_CONTRACT_VERSION;
 export declare const STUDIO_WIRE_PROTOCOL_VERSION: "0.1.0-draft.2";
 export type StudioWireProtocolVersion = typeof STUDIO_WIRE_PROTOCOL_VERSION;
+/**
+ * Stable diagnostic carried with the canonical `invalid-request` category
+ * when a host refuses an operation from an obsolete session generation.
+ */
+export declare const STUDIO_STALE_SESSION_GENERATION_DIAGNOSTIC_CODE: "studio.host/stale-session-generation";
 export type JsonPrimitive = boolean | null | number | string;
 export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
 export interface JsonObject {
@@ -163,12 +168,23 @@ export interface BlockSlotDefinition {
     ordered: boolean;
 }
 export interface BlockPortDefinition {
+    /**
+     * Portable authoring hints. They select a Studio control/profile without
+     * exposing an editor implementation. A read-only port may still be bound by
+     * the host, but Studio never offers a value mutation for it.
+     */
+    authoring?: BlockPortAuthoringMetadata;
     id: LocalName;
     label: MessageReference;
     multiple: boolean;
     required: boolean;
     valueType: string;
 }
+export interface BlockPortAuthoringMetadata {
+    control?: QualifiedName;
+    profile?: QualifiedName;
+    readOnly?: boolean;
+}
 export interface RendererRequirement {
     capability: QualifiedName;
     surface: 'document' | 'email' | 'native' | 'preview' | 'web';
@@ -222,6 +238,63 @@ export interface BlockDefinition {
     type: BlockType;
     version: SemanticVersion;
 }
+/** Canonical, renderer-neutral chart data. It carries no Chart.js configuration. */
+export interface StudioChartDataset {
+    label: string;
+    values: number[];
+}
+export interface StudioChartSpec {
+    datasets: StudioChartDataset[];
+    labels: string[];
+    title?: string;
+    type: 'bar' | 'doughnut' | 'line' | 'pie';
+}
+export interface StudioDrawingPoint {
+    x: number;
+    y: number;
+}
+export interface StudioDrawingStroke {
+    color: string;
+    points: StudioDrawingPoint[];
+    width: number;
+}
+/** Bounded vector drawing data; never an SVG or canvas command stream. */
+export interface StudioDrawingDocument {
+    alt: string;
+    height: number;
+    strokes: StudioDrawingStroke[];
+    width: number;
+}
+/** Decimal money uses a string so persistence never rounds through a binary float. */
+export interface StudioMoneyValue {
+    amount: string;
+    currency: string;
+}
+/** Portable visual intent resolved by Studio renderers; it contains no CSS values or selectors. */
+export interface StudioPresentationIntent {
+    align?: 'center' | 'end' | 'start' | 'stretch';
+    animation?: 'fade' | 'none' | 'parallax' | 'scale' | 'slide';
+    height?: 'auto' | 'content' | 'full' | 'viewport';
+    inverse?: boolean;
+    margin?: 'comfortable' | 'compact' | 'none' | 'spacious';
+    marker?: 'check' | 'decimal' | 'disc' | 'none';
+    padding?: 'comfortable' | 'compact' | 'none' | 'spacious';
+    position?: 'flow' | 'relative' | 'sticky';
+    print?: 'hide' | 'only' | 'show';
+    scrolling?: 'auto' | 'clip' | 'snap' | 'visible';
+    visibility?: {
+        compact?: 'hidden' | 'visible';
+        expanded?: 'hidden' | 'visible';
+        medium?: 'hidden' | 'visible';
+    };
+    width?: 'auto' | 'content' | 'full';
+}
+/** Canonical bounded table data used by static authoring and host query projections. */
+export interface StudioTableDocument {
+    caption?: string;
+    columns: string[];
+    rows: string[][];
+}
 export interface HostPortCapability {
     id: QualifiedName;
     operations: QualifiedName[];
@@ -327,7 +400,7 @@ export interface PluginEntryModule {
     path: PackageRelativePath;
     realm: PluginEntryRealm;
 }
-export type PluginContributionKind = 'block' | 'command' | 'design-vocabulary' | 'field-adapter' | 'inspector' | 'locale' | 'migration' | 'panel' | 'pattern' | 'renderer-capability' | 'test-fixture' | 'transform';
+export type PluginContributionKind = 'authoring-target' | 'block' | 'command' | 'design-vocabulary' | 'field-adapter' | 'inspector' | 'locale' | 'migration' | 'panel' | 'pattern' | 'renderer-capability' | 'test-fixture' | 'transform';
 export interface PluginContributionDeclaration {
     executable?: boolean;
     id: QualifiedName;
@@ -441,6 +514,42 @@ export interface DesignVocabulary {
     recipes: ThemeRecipe[];
     version: SemanticVersion;
 }
+/**
+ * The declarative payload behind a `field-adapter` contribution. Executable
+ * control code remains host-bound; this document is safe to validate and
+ * activate into an immutable contribution generation.
+ */
+export interface FieldAdapterContribution {
+    contractVersion: StudioContractVersion;
+    control: QualifiedName;
+    description?: MessageReference;
+    extensions?: Record<QualifiedName, JsonValue>;
+    fieldKinds: QualifiedName[];
+    id: QualifiedName;
+    kind: 'field-adapter';
+    label: MessageReference;
+    optionSchema?: JsonSchema;
+    owner: OwnerReference;
+    requiredCapability?: QualifiedName;
+    version: SemanticVersion;
+}
+/**
+ * The declarative payload behind an `inspector` contribution. Its executable
+ * surface is resolved separately through host capability policy.
+ */
+export interface InspectorContribution {
+    blockTypes: BlockType[];
+    contractVersion: StudioContractVersion;
+    description?: MessageReference;
+    extensions?: Record<QualifiedName, JsonValue>;
+    id: QualifiedName;
+    kind: 'inspector';
+    label: MessageReference;
+    owner: OwnerReference;
+    placement: 'augment' | 'replace';
+    requiredCapability?: QualifiedName;
+    version: SemanticVersion;
+}
 export type MigrationArtifactKind = 'block-definition' | 'blueprint' | 'content-model' | 'entry' | 'theme';
 /**
  * The declarative payload behind a `migration` plugin contribution: the
@@ -498,6 +607,20 @@ export interface ArtifactPort {
     save(artifact: StudioArtifact, context: HostRequestContext): Promise<HostPortResult<null>>;
     unpublish(reference: ArtifactReference, context: HostRequestContext): Promise<HostPortResult<null>>;
 }
+/**
+ * Host-authoritative contextual authoring operations. The port is additive to
+ * the legacy single-artifact port: no method may be implemented as an
+ * undocumented sequence of `artifact.save` calls.
+ */
+export interface AuthoringPort {
+    listTypes(query: AuthoringTypeListQuery, context: HostRequestContext): Promise<HostPortResult<AuthoringTypeListPage>>;
+    planSave(intent: AuthoringSaveIntent, context: HostRequestContext): Promise<HostPortResult<AuthoringSavePlan>>;
+    resolveTarget(request: AuthoringTargetResolveRequest, context: HostRequestContext): Promise<HostPortResult<AuthoringTargetResolution>>;
+    saveAsNewType(request: AuthoringSaveAsNewTypeRequest, context: HostRequestContext): Promise<HostPortResult<AuthoringSaveResult>>;
+    saveItem(request: AuthoringSaveItemRequest, context: HostRequestContext): Promise<HostPortResult<AuthoringSaveResult>>;
+    saveNewTypeVersion(request: AuthoringSaveNewTypeVersionRequest, context: HostRequestContext): Promise<HostPortResult<AuthoringSaveResult>>;
+    start(request: AuthoringStartRequest, context: HostRequestContext): Promise<HostPortResult<AuthoringSessionSnapshot>>;
+}
 export interface ModelPort {
     get(reference: ArtifactReference, context: HostRequestContext): Promise<HostPortResult<ContentModelDocument>>;
     list(context: HostRequestContext): Promise<HostPortResult<ContentModelDocument[]>>;
@@ -578,6 +701,7 @@ export interface TelemetryPort {
 }
 export interface HostAdapter {
     artifact: ArtifactPort;
+    authoring?: AuthoringPort;
     localization?: LocalizationPort;
     media?: MediaHostPort;
     model?: ModelPort;
@@ -602,6 +726,215 @@ export interface EntryDocument {
     values: Record<LocalName, JsonValue>;
     workflowState?: QualifiedName;
 }
+export type AuthoringTargetEligibility = 'create' | 'edit';
+export type AuthoringStartKind = 'blank' | 'existing' | 'from-type';
+export type AuthoringPresentationState = 'fullscreen' | 'inline' | 'maximized' | 'minimized';
+export type AuthoringSaveOutcome = 'save-as-new-type' | 'save-item' | 'save-new-type-version';
+export type AuthoringContributionKind = 'block-definition' | 'design-vocabulary' | 'field-adapter' | 'inspector' | 'migration' | 'pattern';
+export interface AuthoringCapabilityRequirement {
+    id: QualifiedName;
+    versions: string;
+}
+export interface AuthoringContributionDependency {
+    id: QualifiedName;
+    kind: AuthoringContributionKind;
+    required: boolean;
+    versions: string;
+}
+/**
+ * Bounded discovery metadata shared by host-core and extension-owned targets.
+ * A declaration is never authorization and cannot mint a resource context.
+ */
+export interface AuthoringTargetDeclaration {
+    contractVersion: StudioContractVersion;
+    contributionDependencies: readonly AuthoringContributionDependency[];
+    eligibility: readonly AuthoringTargetEligibility[];
+    extensions?: Record<QualifiedName, JsonValue>;
+    id: QualifiedName;
+    kind: 'authoring-target';
+    label: MessageReference;
+    modes: readonly StudioAuthoringMode[];
+    owner: OwnerReference;
+    presentationStates: readonly AuthoringPresentationState[];
+    requiredCapabilities: readonly AuthoringCapabilityRequirement[];
+    resourceTypes: readonly QualifiedName[];
+    saveOutcomes: readonly AuthoringSaveOutcome[];
+    startKinds: readonly AuthoringStartKind[];
+    surface: QualifiedName;
+}
+export interface AuthoringReturnContext {
+    key: StableId;
+    label?: MessageReference;
+}
+export interface AuthoringTargetResolveRequest {
+    intent: AuthoringTargetEligibility;
+    requestedPresentation?: AuthoringPresentationState;
+    resourceContext: StudioResourceContext;
+    targetId: QualifiedName;
+}
+export interface AuthoringTargetResolution {
+    availableStarts: readonly AuthoringStartKind[];
+    initialPresentation: AuthoringPresentationState;
+    resourceContext: StudioResourceContext;
+    returnContext?: AuthoringReturnContext;
+    target: AuthoringTargetDeclaration;
+}
+export interface ReusableContentTypeReference {
+    id: StableId;
+    revision: Revision;
+    version: SemanticVersion;
+}
+export interface ReusableContentTypeAuthoringPolicy {
+    itemComposition: 'denied' | 'overrides';
+    modes: readonly StudioAuthoringMode[];
+}
+/** Host-owned projection; deliberately not a member of `StudioArtifact`. */
+export interface ReusableContentTypeDefinition extends ReusableContentTypeReference {
+    authoringPolicy: ReusableContentTypeAuthoringPolicy;
+    blueprint: LockedArtifactReference;
+    contractVersion: StudioContractVersion;
+    extensions?: Record<QualifiedName, JsonValue>;
+    kind: 'reusable-content-type';
+    label: MessageReference;
+    model: LockedArtifactReference;
+    status: 'draft' | 'published' | 'retired';
+}
+export interface AuthoringTypeSummary {
+    blueprint: LockedArtifactReference;
+    label: MessageReference;
+    model: LockedArtifactReference;
+    reference: ReusableContentTypeReference;
+}
+export interface AuthoringTypeListQuery {
+    cursor?: string;
+    limit: number;
+    resourceContext: StudioResourceContext;
+    search?: string;
+    targetId: QualifiedName;
+}
+export interface AuthoringTypeListPage {
+    items: AuthoringTypeSummary[];
+    nextCursor?: string;
+}
+export type AuthoringStartSource = {
+    kind: 'blank';
+} | {
+    kind: 'existing';
+} | {
+    kind: 'from-type';
+    type: ReusableContentTypeReference;
+};
+export interface AuthoringStartRequest {
+    presentation?: AuthoringPresentationState;
+    resourceContext: StudioResourceContext;
+    source: AuthoringStartSource;
+    targetId: QualifiedName;
+}
+export interface AuthoringArtifactCoordinates {
+    blueprint: LockedArtifactReference;
+    entry: ResolvedEntryReference;
+    model: LockedArtifactReference;
+    type?: ReusableContentTypeReference;
+}
+export type AuthoringDirtyArtifact = 'blueprint' | 'entry' | 'model';
+export interface AuthoringArtifactState {
+    blueprint: BlueprintDocument;
+    coordinates: AuthoringArtifactCoordinates;
+    diagnostics: StudioDiagnostic[];
+    dirty: AuthoringDirtyArtifact[];
+    entry: EntryDocument;
+    model: ContentModelDocument;
+}
+export interface AuthoringSessionCapabilities {
+    modes: readonly StudioAuthoringMode[];
+    presentationStates: readonly AuthoringPresentationState[];
+    saveOutcomes: readonly AuthoringSaveOutcome[];
+}
+export interface AuthoringSessionPresentation {
+    current: AuthoringPresentationState;
+    returnContext?: AuthoringReturnContext;
+}
+export interface AuthoringSessionSnapshot {
+    capabilities: AuthoringSessionCapabilities;
+    contractVersion: StudioContractVersion;
+    contributionGeneration: Revision;
+    extensions?: Record<QualifiedName, JsonValue>;
+    kind: 'authoring-session';
+    presentation: AuthoringSessionPresentation;
+    resourceContext: StudioResourceContext;
+    sessionGeneration: Revision;
+    sessionId: StableId;
+    start: AuthoringStartSource;
+    state: AuthoringArtifactState;
+    target: AuthoringTargetDeclaration;
+    type?: ReusableContentTypeDefinition;
+}
+export interface AuthoringSaveItemDraft {
+    entry: EntryDocument;
+    itemBlueprint?: BlueprintDocument;
+    outcome: 'save-item';
+}
+export interface AuthoringSaveNewTypeVersionDraft {
+    blueprint: BlueprintDocument;
+    model: ContentModelDocument;
+    outcome: 'save-new-type-version';
+}
+export interface AuthoringSaveAsNewTypeDraft {
+    authoringPolicy: ReusableContentTypeAuthoringPolicy;
+    blueprint: BlueprintDocument;
+    label: MessageReference;
+    model: ContentModelDocument;
+    outcome: 'save-as-new-type';
+}
+export type AuthoringSaveDraft = AuthoringSaveAsNewTypeDraft | AuthoringSaveItemDraft | AuthoringSaveNewTypeVersionDraft;
+export interface AuthoringSaveIntent {
+    contractVersion: StudioContractVersion;
+    draft: AuthoringSaveDraft;
+    expected: AuthoringArtifactCoordinates;
+    kind: 'authoring-save-intent';
+    sessionId: StableId;
+}
+export type AuthoringAffectedArtifact = 'blueprint' | 'entry' | 'model' | 'reusable-content-type';
+export interface AuthoringSavePlanReference {
+    id: StableId;
+    revision: Revision;
+    /** Exact host-minted return context adopted only after this planned save is accepted. */
+    successorContext: AuthoringReturnContext;
+}
+export interface AuthoringSavePlan extends AuthoringSavePlanReference {
+    affectedArtifacts: AuthoringAffectedArtifact[];
+    confirmationRequired: boolean;
+    consequences: StudioDiagnostic[];
+    contractVersion: StudioContractVersion;
+    expected: AuthoringArtifactCoordinates;
+    kind: 'authoring-save-plan';
+    outcome: AuthoringSaveOutcome;
+    sessionId: StableId;
+}
+interface AuthoringSaveRequestBase {
+    acceptedConsequences: QualifiedName[];
+    contractVersion: StudioContractVersion;
+    plan: AuthoringSavePlanReference;
+}
+export interface AuthoringSaveItemRequest extends AuthoringSaveRequestBase {
+    draft: AuthoringSaveItemDraft;
+    kind: 'authoring-save-item-request';
+}
+export interface AuthoringSaveNewTypeVersionRequest extends AuthoringSaveRequestBase {
+    draft: AuthoringSaveNewTypeVersionDraft;
+    kind: 'authoring-save-new-type-version-request';
+}
+export interface AuthoringSaveAsNewTypeRequest extends AuthoringSaveRequestBase {
+    draft: AuthoringSaveAsNewTypeDraft;
+    kind: 'authoring-save-as-new-type-request';
+}
+export interface AuthoringSaveResult {
+    contractVersion: StudioContractVersion;
+    kind: 'authoring-save-result';
+    outcome: AuthoringSaveOutcome;
+    plan: AuthoringSavePlanReference;
+    session: AuthoringSessionSnapshot;
+}
 export type StudioAuthoringMode = 'blueprint' | 'content' | 'model';
 /**
  * The single permission determinant of a headless editing session, fixed at
@@ -653,6 +986,104 @@ export interface StudioLimits {
     maxRichTextDepth: number;
     maxSlotsPerNode: number;
 }
+export interface StudioDeploymentLaunch {
+    initialPresentation: AuthoringPresentationState;
+    intent: AuthoringTargetEligibility;
+    resourceContext: StudioResourceContext;
+    start: AuthoringStartSource;
+    targetId: QualifiedName;
+}
+export type StudioDeploymentOperationRoute = 'artifact/dependencies' | 'artifact/load' | 'artifact/publish' | 'artifact/save' | 'artifact/unpublish' | 'authoring/list-types' | 'authoring/plan-save' | 'authoring/resolve-target' | 'authoring/save-as-new-type' | 'authoring/save-item' | 'authoring/save-new-type-version' | 'authoring/start' | 'localization/messages' | 'media/abort-upload' | 'media/authorize-upload' | 'media/complete-upload' | 'media/get' | 'media/import-external' | 'media/list' | 'media/upload-status' | 'model/get' | 'model/list' | 'permission/explain' | 'permission/refresh' | 'preview/cancel' | 'preview/render' | 'recovery/discard' | 'recovery/load' | 'recovery/store' | 'resource/search' | 'telemetry/emit';
+export type StudioDeploymentOperationEndpoints = Readonly<Partial<Record<StudioDeploymentOperationRoute, string>>> & {
+    readonly 'authoring/resolve-target': string;
+    readonly 'authoring/start': string;
+};
+export interface StudioDeploymentSingleEndpointRouting {
+    endpoint: string;
+    kind: 'single-endpoint';
+}
+export interface StudioDeploymentOperationMapRouting {
+    endpoints: StudioDeploymentOperationEndpoints;
+    kind: 'operation-map';
+}
+export type StudioDeploymentRouting = StudioDeploymentOperationMapRouting | StudioDeploymentSingleEndpointRouting;
+export interface StudioDeploymentSameOriginSessionAuthentication {
+    credentials: 'same-origin';
+    csrf: {
+        headerName: string;
+        token: string;
+    };
+    kind: 'same-origin-session';
+}
+export interface StudioDeploymentBearerTokenAuthentication {
+    credentials: 'omit';
+    expiresAt: string;
+    issuedAt: string;
+    kind: 'bearer-token';
+    token: string;
+}
+export interface StudioDeploymentHeaderTokenAuthentication {
+    credentials: 'omit';
+    expiresAt: string;
+    headerName: string;
+    issuedAt: string;
+    kind: 'header-token';
+    token: string;
+}
+export type StudioDeploymentAuthentication = StudioDeploymentBearerTokenAuthentication | StudioDeploymentHeaderTokenAuthentication | StudioDeploymentSameOriginSessionAuthentication;
+export interface StudioDeploymentStandaloneTransport {
+    kind: 'standalone';
+}
+export interface StudioDeploymentHttpTransport {
+    authentication: StudioDeploymentAuthentication;
+    kind: 'http';
+    maximumResponseBytes?: number;
+    requestTimeoutMilliseconds?: number;
+    routing: StudioDeploymentRouting;
+}
+export type StudioDeploymentTransport = StudioDeploymentHttpTransport | StudioDeploymentStandaloneTransport;
+/** Safe declarative contributions; executable controls remain precompiled registry entries. */
+export type StudioDeploymentContributionPayload = BlockDefinition | DesignVocabulary | FieldAdapterContribution | InspectorContribution | MigrationDeclaration | PatternDocument;
+export interface StudioDeploymentContributionBundle {
+    generation: Revision;
+    payloads: readonly StudioDeploymentContributionPayload[];
+}
+/** Exact release identity copied from the prebuilt browser asset manifest. */
+export interface StudioDeploymentRelease {
+    corpusManifestDigest: string;
+    version: string;
+}
+export interface StudioDeploymentConfigurationBase {
+    contractVersion?: StudioContractVersion;
+    instanceId?: StableId;
+    kind: 'studio-deployment';
+    mount: string;
+    release: StudioDeploymentRelease;
+}
+export interface StudioStandaloneDeploymentConfiguration extends StudioDeploymentConfigurationBase {
+    contributions?: never;
+    launch?: never;
+    /** Requested local UI locale. English remains the built-in message fallback. */
+    locale?: string;
+    session?: never;
+    transport?: StudioDeploymentStandaloneTransport;
+}
+export interface StudioHostedDeploymentConfiguration extends StudioDeploymentConfigurationBase {
+    contributions?: StudioDeploymentContributionBundle;
+    launch: StudioDeploymentLaunch;
+    locale?: never;
+    session: StudioConfiguration;
+    transport: StudioDeploymentHttpTransport;
+}
+/**
+ * Bounded JSON emitted by any host into an `application/json` DOM script for
+ * one Studio mount. Every emitted document is bound to its exact browser asset
+ * release. Omitting the document entirely for an explicit or associated DOM
+ * target selects local defaults; omitting `transport` from a complete document
+ * selects the deterministic standalone blank-page profile. HTTP deployments
+ * provide an exact launch plus the PHP/host-resolved Studio session configuration.
+ */
+export type StudioDeploymentConfiguration = StudioHostedDeploymentConfiguration | StudioStandaloneDeploymentConfiguration;
 export interface StudioConfiguration {
     actor: {
         displayName: string;
@@ -702,7 +1133,8 @@ export interface StudioConfiguration {
     resourceContext: StudioResourceContext;
 }
 export interface ExperimentalShellConfiguration {
-    blockDefinitions: BlockDefinition[];
+    /** Omit to use Studio's complete first-party catalog; an explicit array overrides it. */
+    blockDefinitions?: BlockDefinition[];
     session: StudioConfiguration;
 }
 export interface CommandDestination {
@@ -1143,4 +1575,5 @@ export interface MediaPage {
     assets: MediaAsset[];
     nextCursor?: string;
 }
+export {};
 //# sourceMappingURL=types.d.ts.map