@veil-runtime/ui 0.0.0-stage → 0.3.0

package/dist/capability-view-derivation.js

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { assertBoundedData, copyData } from "./validation-safety.js";
+import { deriveUIFields } from "./derive-input-fields.js";
+import { deriveOutputView } from "./derive-output-view.js";
+import { interpretRelationship, isExplicitAction } from "./relationship-interpretation.js";
+function humanise(value) {
+    return value
+        .replace(/[._-]+/g, " ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+export function deriveDeterministicCapabilityView(options) {
+    const { capability, outputSchema, transition } = options;
+    assertBoundedData(capability.inputSchema ?? {});
+    assertBoundedData(outputSchema);
+    assertBoundedData(options.relationships ?? []);
+    assertBoundedData(transition);
+    const relationships = options.relationships ?? [];
+    const fields = deriveUIFields((capability.inputSchema ?? {}));
+    const confirmation = capability.risk === "destructive"
+        ? {
+            required: true,
+            title: "Confirm destructive action",
+            message: "This action is destructive and may not be reversible.",
+        }
+        : undefined;
+    const outputView = deriveOutputView(outputSchema);
+    if (outputView.surface === "table" && outputView.table) {
+        outputView.table.actions = relationships
+            .filter((relationship) => isExplicitAction(interpretRelationship(relationship, "table-row")))
+            .map((relationship) => ({
+            label: relationship.label,
+            capability: relationship.targetCapability,
+            bindings: copyData(relationship.bindings),
+            interaction: interpretRelationship(relationship, "table-row"),
+            ...(relationship.conditions
+                ? { conditions: copyData(relationship.conditions) }
+                : {}),
+        }));
+        if (outputView.table.actions.length === 0)
+            delete outputView.table.actions;
+    }
+    if (outputView.surface === "detail" && outputView.detail) {
+        outputView.detail.actions = relationships
+            .filter((relationship) => isExplicitAction(interpretRelationship(relationship, "detail")))
+            .map((relationship) => ({
+            label: relationship.label,
+            capability: relationship.targetCapability,
+            bindings: copyData(relationship.bindings),
+            interaction: interpretRelationship(relationship, "detail"),
+            ...(relationship.conditions
+                ? { conditions: copyData(relationship.conditions) }
+                : {}),
+        }));
+        if (outputView.detail.actions.length === 0)
+            delete outputView.detail.actions;
+    }
+    return {
+        capability: capability.name,
+        title: humanise(capability.name),
+        description: capability.description,
+        risk: capability.risk,
+        surface: outputView.surface,
+        fields,
+        derivation: {
+            surface: outputView.derivation,
+            fields: "input-schema",
+            actions: "relationship-metadata",
+            ...(confirmation ? { confirmation: "authoritative-risk" } : {}),
+            ...(transition?.onSuccess
+                ? { successTransition: "transition-metadata" }
+                : {}),
+        },
+        ...(confirmation ? { confirmation } : {}),
+        ...(outputView.table ? { table: outputView.table } : {}),
+        ...(outputView.detail ? { detail: outputView.detail } : {}),
+        ...(outputView.aggregate ? { aggregate: outputView.aggregate } : {}),
+        ...(outputView.timeSeries ? { timeSeries: outputView.timeSeries } : {}),
+        ...(outputView.categorySeries ? { categorySeries: outputView.categorySeries } : {}),
+        ...(transition?.onSuccess ? { onSuccess: copyData(transition.onSuccess) } : {}),
+        submitLabel: humanise(capability.name),
+    };
+}
+function applySuggestion(view, suggestion) {
+    if (suggestion.title !== undefined && suggestion.title.trim() === "") {
+        throw new Error("Presentation title cannot be empty");
+    }
+    if (suggestion.submitLabel !== undefined && suggestion.submitLabel.trim() === "") {
+        throw new Error("Presentation submit label cannot be empty");
+    }
+    let fields = view.fields;
+    if (suggestion.fields) {
+        const expected = view.fields.map((field) => field.name).sort();
+        const received = suggestion.fields.map((field) => field.name).sort();
+        if (expected.length !== received.length
+            || expected.some((name, index) => name !== received[index])
+            || new Set(received).size !== received.length) {
+            throw new Error("Presentation suggestion changed authoritative field membership");
+        }
+        const suggestions = new Map(suggestion.fields.map((field) => [field.name, field.label]));
+        if ([...suggestions.values()].some((label) => label.trim() === "")) {
+            throw new Error("Presentation field labels cannot be empty");
+        }
+        fields = view.fields.map((field) => ({
+            ...field,
+            label: suggestions.get(field.name),
+        }));
+    }
+    return {
+        ...view,
+        fields,
+        ...(suggestion.title ? { title: suggestion.title } : {}),
+        ...(suggestion.submitLabel ? { submitLabel: suggestion.submitLabel } : {}),
+    };
+}
+export async function deriveCapabilityView(options) {
+    const deterministic = deriveDeterministicCapabilityView(options);
+    const capabilityVersion = options.capability.version;
+    const generatedAt = new Date().toISOString();
+    if (options.strategy !== "generative") {
+        return {
+            ...deterministic,
+            provenance: {
+                strategy: "deterministic",
+                requestedStrategy: "deterministic",
+                fallback: false,
+                capabilityVersion,
+                generatedAt,
+                source: "generated",
+            },
+        };
+    }
+    try {
+        if (!options.provider)
+            throw new Error("No presentation provider configured");
+        const suggestion = await options.provider.suggestCapabilityPresentation({
+            capability: {
+                name: options.capability.name, version: capabilityVersion,
+                description: options.capability.description, risk: options.capability.risk,
+                ...(options.capability.inputSchema ? { inputSchema: copyData(options.capability.inputSchema) } : {}),
+                async execute() { throw new Error("Presentation metadata cannot execute capabilities"); },
+            },
+            deterministicView: copyData(deterministic),
+            ...(options.context ? { context: copyData(options.context) } : {}),
+        });
+        assertBoundedData(suggestion);
+        const safeSuggestion = z.object({
+            title: z.string().trim().min(1).max(100).optional(),
+            submitLabel: z.string().trim().min(1).max(80).optional(),
+            fields: z.array(z.object({ name: z.string().min(1).max(120), label: z.string().trim().min(1).max(160) }).strict()).max(256).optional(),
+        }).strict().parse(suggestion);
+        const view = applySuggestion(deterministic, {
+            ...(safeSuggestion.title !== undefined ? { title: safeSuggestion.title } : {}),
+            ...(safeSuggestion.submitLabel !== undefined ? { submitLabel: safeSuggestion.submitLabel } : {}),
+            ...(safeSuggestion.fields !== undefined ? { fields: safeSuggestion.fields } : {}),
+        });
+        return {
+            ...view,
+            provenance: {
+                strategy: "generative",
+                requestedStrategy: "generative",
+                provider: options.provider.name,
+                ...(options.provider.model ? { model: options.provider.model } : {}),
+                fallback: false,
+                capabilityVersion,
+                generatedAt,
+                source: "generated",
+            },
+        };
+    }
+    catch (error) {
+        return {
+            ...deterministic,
+            provenance: {
+                strategy: "deterministic",
+                requestedStrategy: "generative",
+                fallback: true,
+                reason: error instanceof Error ? error.message : "presentation-provider-failed",
+                capabilityVersion,
+                generatedAt,
+                source: "generated",
+            },
+        };
+    }
+}

package/dist/capability-view.d.ts

@@ -0,0 +1,170 @@
+export type UIFieldType = "text" | "textarea" | "number" | "checkbox" | "date" | "datetime" | "currency" | "object" | "array" | "email" | "select" | "unknown";
+export interface UIField {
+    name: string;
+    label: string;
+    type: UIFieldType;
+    required: boolean;
+    description: string;
+    authoritativeType: string;
+    options?: Array<string | number | boolean>;
+    format?: "date" | "date-time" | "multiline";
+    semantic?: "currency";
+    currency?: string;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    fields?: UIField[];
+    item?: UIField;
+    derivation: {
+        source: "authoritative-input-schema";
+        reason: string;
+    };
+}
+export interface UISection {
+    id: string;
+    title: string;
+    fields: string[];
+}
+export interface UIConfirmation {
+    required: boolean;
+    title: string;
+    message: string;
+}
+export interface UIAction {
+    label: string;
+    capability: string;
+    bindings: Record<string, string>;
+    interaction: import("./relationship-interpretation.js").RelationshipInteraction;
+    conditions?: Array<{
+        field: string;
+        operator: "equals";
+        value: string | number | boolean;
+    } | {
+        field: string;
+        operator: "exists";
+    }>;
+}
+export interface UITableColumn {
+    key: string;
+    label: string;
+}
+export interface UITable {
+    dataPath: string;
+    columns: UITableColumn[];
+    actions?: UIAction[];
+}
+export interface UIDetailField {
+    key: string;
+    label: string;
+    semantic?: "currency" | "count" | "ratio";
+    currency?: string;
+}
+export interface UIAggregateMetric {
+    key: string;
+    label: string;
+    authoritativeType: "number" | "integer";
+    semantic: "currency" | "count" | "ratio";
+    currency?: string;
+    derivation: {
+        source: "authoritative-output-schema";
+        reason: "metric-semantics";
+    };
+}
+export interface UIViewProvenance {
+    strategy: "deterministic" | "generative";
+    provider?: string;
+    model?: string;
+    capabilityVersion: string;
+    generatedAt: string;
+    requestedStrategy?: "deterministic" | "generative";
+    fallback?: boolean;
+    reason?: string;
+    source?: "generated" | "memory-cache" | "persistent-cache";
+}
+export interface UISuccessTransition {
+    capability: string;
+    refresh?: boolean;
+    resultBindings?: Record<string, string>;
+}
+export interface UIViewDerivation {
+    surface: {
+        source: "input-schema" | "output-schema";
+        reason: "no-output-schema" | "single-top-level-array-of-objects" | "flat-output-object" | "structured-output-object" | "authoritative-aggregate-object" | "authoritative-time-series" | "authoritative-category-series";
+    };
+    fields: "input-schema";
+    actions: "relationship-metadata";
+    confirmation?: "authoritative-risk";
+    successTransition?: "transition-metadata";
+}
+export interface CapabilityView {
+    capability: string;
+    title: string;
+    description: string;
+    risk: "read" | "write" | "destructive";
+    surface: "form" | "table" | "detail" | "aggregate" | "time-series" | "category-series";
+    fields: UIField[];
+    derivation: UIViewDerivation;
+    sections?: UISection[];
+    confirmation?: UIConfirmation;
+    table?: UITable;
+    detail?: {
+        fields: UIDetailField[];
+        actions?: UIAction[];
+    };
+    aggregate?: {
+        metrics: UIAggregateMetric[];
+    };
+    categorySeries?: {
+        dataPath: string;
+        visualization: "bar";
+        ordering: "source-order";
+        dimension: {
+            key: string;
+            label: string;
+            type: "string";
+            enum?: string[];
+            role: "dimension";
+        };
+        measure: {
+            key: string;
+            label: string;
+            type: "number" | "integer";
+            semantic: "count" | "currency" | "ratio";
+            currency?: string;
+            role: "measure";
+        };
+        derivation: {
+            source: "authoritative-output-schema";
+            reason: "categorical-dimension-with-numeric-measure";
+        };
+    };
+    timeSeries?: {
+        dataPath: string;
+        visualization: "line";
+        dimension: {
+            key: string;
+            label: string;
+            type: "string";
+            format: "date" | "date-time";
+            role: "dimension";
+        };
+        measure: {
+            key: string;
+            label: string;
+            type: "number" | "integer";
+            semantic: "count" | "currency" | "ratio";
+            currency?: string;
+            role: "measure";
+        };
+        derivation: {
+            source: "authoritative-output-schema";
+            reason: "temporal-dimension-with-numeric-measure";
+        };
+    };
+    provenance?: UIViewProvenance;
+    submitLabel: string;
+    onSuccess?: UISuccessTransition;
+}

package/dist/capability-view.js

@@ -0,0 +1 @@
+export {};

package/dist/composed-surface.d.ts

@@ -0,0 +1,67 @@
+import type { CapabilityView } from "./capability-view.js";
+export interface SurfaceExecution {
+    capability: string;
+    view: CapabilityView;
+    result: Record<string, unknown>;
+    contextToken: string;
+}
+export interface RelatedSurfaceExecution {
+    capability: string;
+    label: string;
+    bindings: Record<string, string>;
+    resolvedInputs: Record<string, unknown>;
+    role: "related";
+    execution: "automatic-read";
+    reason: "authoritative-related-relationship-and-read-only-target";
+    status: "success" | "empty" | "failed";
+    view?: CapabilityView;
+    result?: Record<string, unknown>;
+    error?: string;
+}
+export type PresentationSurface = CapabilityView["surface"] | "error";
+export interface PresentationEnvelopeSection {
+    id: string;
+    capability: string;
+    surface: PresentationSurface;
+    label: string;
+    required: true;
+    movable: boolean;
+    groupable: boolean;
+    defaultOrder: number;
+}
+export interface PresentationEnvelope {
+    applicationSurface: string;
+    sections: PresentationEnvelopeSection[];
+    immutable: string[];
+}
+export interface PresentationGroup {
+    id: string;
+    title?: string;
+    description?: string;
+    emphasis: "normal" | "prominent" | "subtle";
+    density: "comfortable" | "compact";
+    sections: string[];
+}
+export interface PresentationPlan {
+    title?: string;
+    description?: string;
+    groups: PresentationGroup[];
+}
+export interface PresentationProvenance {
+    strategy: "deterministic" | "generative";
+    requestedStrategy: "deterministic" | "generative";
+    provider?: string;
+    model?: string;
+    fallback: boolean;
+    validated: boolean;
+    reason?: string;
+}
+export interface ComposedSurface {
+    primary: SurfaceExecution;
+    related: RelatedSurfaceExecution[];
+    presentation: {
+        envelope: PresentationEnvelope;
+        plan: PresentationPlan;
+        provenance: PresentationProvenance;
+    };
+}

package/dist/composed-surface.js

@@ -0,0 +1 @@
+export {};

package/dist/composition-inspection.d.ts

@@ -0,0 +1,51 @@
+import type { CapabilityView } from "./capability-view.js";
+import type { DerivedApplication, DerivedApplicationCapability } from "./application.js";
+import type { CapabilityInteractionResolution } from "./interaction-resolution.js";
+export interface InspectionEdge {
+    kind: "relationship" | "success";
+    source: string;
+    target: string;
+    label: string;
+    bindings: Record<string, string>;
+    conditions: string[];
+}
+export interface CompositionInspection {
+    application: {
+        id: string;
+        title: string;
+        entryCapability: string;
+        members: string[];
+    };
+    capabilities: Array<{
+        name: string;
+        entry: boolean;
+        risk: DerivedApplicationCapability["risk"];
+        roles: import("./experience-orchestration.js").ApplicationExperienceRole[];
+    }>;
+    edges: InspectionEdge[];
+    surface?: {
+        primary: string;
+        related: Array<{
+            capability: string;
+            label: string;
+            bindings: Record<string, string>;
+            execution: "automatic-read";
+            reason: string;
+        }>;
+        actions: Array<{
+            capability: string;
+            label: string;
+            bindings: Record<string, string>;
+        }>;
+    };
+    active?: {
+        capability: DerivedApplicationCapability;
+        view: CapabilityView;
+        interaction: CapabilityInteractionResolution;
+    };
+    recipe: Array<{
+        label: string;
+        metadata: unknown;
+    }>;
+}
+export declare function buildCompositionInspection(application: DerivedApplication, activeCapabilityName: string | null, view: CapabilityView | null, interaction: CapabilityInteractionResolution | null): CompositionInspection;

package/dist/composition-inspection.js

@@ -0,0 +1,102 @@
+import { deriveApplicationExperience } from "./experience-orchestration.js";
+import { interpretRelationship } from "./relationship-interpretation.js";
+function conditionText(condition) {
+    return condition.operator === "exists"
+        ? `${condition.field} exists`
+        : `${condition.field} equals ${String(condition.value)}`;
+}
+export function buildCompositionInspection(application, activeCapabilityName, view, interaction) {
+    const edges = [];
+    const experience = deriveApplicationExperience(application);
+    for (const capability of application.capabilities) {
+        for (const relationship of capability.relationships) {
+            edges.push({
+                kind: "relationship",
+                source: capability.name,
+                target: relationship.targetCapability,
+                label: relationship.label,
+                bindings: relationship.bindings,
+                conditions: (relationship.conditions ?? []).map(conditionText),
+            });
+        }
+        if (capability.transition?.onSuccess) {
+            edges.push({
+                kind: "success",
+                source: capability.name,
+                target: capability.transition.onSuccess.capability,
+                label: "success",
+                bindings: capability.transition.onSuccess.resultBindings ?? {},
+                conditions: [],
+            });
+        }
+    }
+    const activeCapability = application.capabilities.find((capability) => capability.name === activeCapabilityName);
+    const recipe = [{
+            label: "Register capabilities and authoritative input schemas",
+            metadata: Object.fromEntries(application.capabilities.map((capability) => [
+                capability.name,
+                capability.inputSchema,
+            ])),
+        }];
+    if (application.capabilities.some((capability) => capability.outputSchema)) {
+        recipe.push({
+            label: "Define authoritative output schemas",
+            metadata: Object.fromEntries(application.capabilities
+                .filter((capability) => capability.outputSchema)
+                .map((capability) => [capability.name, capability.outputSchema])),
+        });
+    }
+    if (edges.some((edge) => edge.kind === "relationship")) {
+        recipe.push({
+            label: "Add relationships, bindings, and conditions",
+            metadata: edges.filter((edge) => edge.kind === "relationship"),
+        });
+    }
+    if (edges.some((edge) => edge.kind === "success")) {
+        recipe.push({
+            label: "Add success transitions and result bindings",
+            metadata: edges.filter((edge) => edge.kind === "success"),
+        });
+    }
+    recipe.push({
+        label: "Add an application manifest",
+        metadata: {
+            id: application.id,
+            entryCapability: application.entryCapability,
+            capabilities: application.capabilities.map((capability) => capability.name),
+        },
+    }, {
+        label: "Validate the derived application graph",
+        metadata: { applicationId: application.id },
+    }, {
+        label: "Render the derived view through the generic shell",
+        metadata: view
+            ? {
+                capability: view.capability,
+                surface: view.surface,
+                derivation: view.derivation,
+            }
+            : {},
+    });
+    const activeRelationships = activeCapability?.relationships ?? [];
+    return {
+        application: {
+            id: application.id,
+            title: application.title,
+            entryCapability: application.entryCapability,
+            members: application.capabilities.map((capability) => capability.name),
+        },
+        capabilities: application.capabilities.map((capability) => ({
+            name: capability.name,
+            entry: capability.name === application.entryCapability,
+            risk: capability.risk,
+            roles: experience.find((item) => item.capability.name === capability.name)?.roles ?? [],
+        })),
+        edges,
+        ...(activeCapability ? { surface: { primary: activeCapability.name, related: activeRelationships.filter((r) => interpretRelationship(r, "detail") === "related-read").map((r) => ({ capability: r.targetCapability, label: r.label, bindings: r.bindings, execution: "automatic-read", reason: "authoritative related relationship and read-only target" })), actions: activeRelationships.filter((r) => interpretRelationship(r, "detail") !== "related-read").map((r) => ({ capability: r.targetCapability, label: r.label, bindings: r.bindings })) } } : {}),
+        ...(activeCapability && view && interaction && view.capability === activeCapability.name
+            ? { active: { capability: activeCapability, view, interaction } }
+            : {}),
+        recipe,
+    };
+}

package/dist/composition.d.ts

@@ -0,0 +1,43 @@
+import type { UIField } from "./capability-view.js";
+import { type RichCapabilityInputSchema } from "./input-schema.js";
+export interface ComponentNode {
+    component: string;
+    field?: string;
+    action?: string;
+    text?: string;
+    children?: ComponentNode[];
+}
+export interface ComposedApplication {
+    id: string;
+    title: string;
+    fields: RichCapabilityInputSchema;
+    initialState?: Record<string, unknown>;
+    screen: ComponentNode;
+    actions: readonly string[];
+}
+export type SubmissionStatus = "idle" | "submitting" | "success" | "error";
+export interface CompositionSnapshot {
+    values: Record<string, unknown>;
+    errors: Record<string, string>;
+    status: SubmissionStatus;
+    message: string;
+}
+export type ActionResult = {
+    ok: true;
+} | {
+    ok: false;
+};
+export type ActionHandler = (input: Readonly<Record<string, unknown>>) => Promise<ActionResult> | ActionResult;
+export type ActionHandlers = Readonly<Record<string, ActionHandler>>;
+export declare function defineComposedApplication<const T extends ComposedApplication>(definition: T): T;
+export declare function validateComposedApplication(definition: ComposedApplication, customComponents?: readonly string[]): void;
+export interface CompositionController<Action extends string = string, Field extends string = string> {
+    readonly definition: ComposedApplication;
+    snapshot(): CompositionSnapshot;
+    field(name: Field): UIField;
+    setField(name: Field, value: unknown): void;
+    submit(action: Action): Promise<boolean>;
+    subscribe(listener: (snapshot: CompositionSnapshot) => void): () => void;
+    dispose(): void;
+}
+export declare function createCompositionController<const T extends ComposedApplication>(definition: T, handlers: Readonly<Record<T["actions"][number], ActionHandler>>, customComponents?: readonly string[]): CompositionController<T["actions"][number], keyof T["fields"] & string>;