@oddkin/ai 0.0.0-stage → 1.0.0-beta.1

package/dist/contracts/types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Types for AI interaction surfaces: records inferred from the models, controller state, and the
+ * normalized event stream adapters produce. Contract: docs/architecture/ai-interaction.md §3–§5.
+ */
+import type { Infer, JsonValue } from '@oddkin/core/model';
+import type { ApprovalModel, ArtifactModel, CheckpointModel, ContextItemModel, ConversationSnapshotModel, FeedbackModel, MessageModel, ModelOptionModel, PlanModel, QuestionModel, SuggestionModel, ToolCallModel, TranscriptSegmentModel, UsageModel, capabilitiesSchema, partSchema, provenanceSchema, publicErrorSchema, usageEntrySchema } from './models.js';
+export type { JsonValue };
+export type PublicError = Infer<typeof publicErrorSchema>;
+export type Capabilities = Infer<typeof capabilitiesSchema>;
+export type CapabilityName = keyof Capabilities;
+export type MessagePart = Infer<typeof partSchema>;
+export type PartType = MessagePart['type'];
+export type PartOf<T extends PartType> = Extract<MessagePart, {
+    type: T;
+}>;
+export type Provenance = Infer<typeof provenanceSchema>;
+export type MessageRecord = Infer<typeof MessageModel>;
+export type MessageRole = MessageRecord['role'];
+export type ToolCallRecord = Infer<typeof ToolCallModel>;
+export type ToolStatus = ToolCallRecord['status'];
+export type ApprovalRecord = Infer<typeof ApprovalModel>;
+export type ApprovalStatus = ApprovalRecord['status'];
+export type ArtifactRecord = Infer<typeof ArtifactModel>;
+export type ArtifactRevision = ArtifactRecord['revisions'][number];
+export type UsageEntry = Infer<typeof usageEntrySchema>;
+export type Usage = Infer<typeof UsageModel>;
+export type CheckpointRecord = Infer<typeof CheckpointModel>;
+export type PlanRecord = Infer<typeof PlanModel>;
+export type PlanStep = PlanRecord['steps'][number];
+export type StepStatus = PlanStep['status'];
+export type QuestionRecord = Infer<typeof QuestionModel>;
+export type ContextItem = Infer<typeof ContextItemModel>;
+export type ModelOption = Infer<typeof ModelOptionModel>;
+export type FeedbackRecord = Infer<typeof FeedbackModel>;
+export type Suggestion = Infer<typeof SuggestionModel>;
+export type TranscriptSegment = Infer<typeof TranscriptSegmentModel>;
+export type ConversationSnapshot = Infer<typeof ConversationSnapshotModel>;
+/** How an attempt relates to earlier work. `resume` never creates an attempt. */
+export type AttemptRelation = 'new' | 'retry' | 'regenerate' | 'edit';
+/** Status of the underlying work, independent of the client connection. */
+export type AttemptStatus = 'submitted' | 'accepted' | 'streaming' | 'awaiting-input' | 'completed' | 'cancelled' | 'failed' | 'interrupted';
+/** The client's connection to an attempt's stream. */
+export type ConnectionState = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'disconnected' | 'closed';
+/** An explicit stop request and its outcome. */
+export type StopState = 'none' | 'requested' | 'confirmed' | 'too-late' | 'failed' | 'unknown';
+export interface AttemptRecord {
+    readonly attemptId: string;
+    readonly runId: string;
+    readonly conversationId: string;
+    /** The assistant message this attempt writes. */
+    readonly messageId: string;
+    /** The user message this attempt answers. */
+    readonly promptId: string;
+    readonly relation: AttemptRelation;
+    readonly parentAttemptId?: string | undefined;
+    readonly status: AttemptStatus;
+    readonly connection: ConnectionState;
+    readonly stop: StopState;
+    readonly error?: PublicError | undefined;
+    readonly usage?: Usage | undefined;
+}
+export type HistoryState = 'idle' | 'loading' | 'complete' | 'error';
+/** Immutable snapshot of a conversation surface. Replaced, never mutated. */
+export interface ConversationState {
+    readonly conversationId: string;
+    /** Increments on every change; consumers compare to skip work. */
+    readonly revision: number;
+    /** Messages on the active branch, oldest first. */
+    readonly messages: readonly MessageRecord[];
+    readonly tools: Readonly<Record<string, ToolCallRecord>>;
+    readonly approvals: Readonly<Record<string, ApprovalRecord>>;
+    readonly artifacts: Readonly<Record<string, ArtifactRecord>>;
+    readonly attempts: Readonly<Record<string, AttemptRecord>>;
+    /** Alternatives for messages that have siblings, keyed by message id. */
+    readonly branches: Readonly<Record<string, BranchPosition>>;
+    readonly activeAttemptId?: string | undefined;
+    readonly capabilities: Capabilities;
+    readonly history: HistoryState;
+    readonly hasMoreHistory: boolean;
+    readonly feedback: Readonly<Record<string, FeedbackRecord>>;
+}
+export interface BranchPosition {
+    /** 1-based position among siblings. */
+    readonly index: number;
+    readonly count: number;
+    readonly previousId?: string | undefined;
+    readonly nextId?: string | undefined;
+}
+/** Interoperable subscription contract (same shape as React's `useSyncExternalStore`), from core. */
+export type { ExternalSource } from '@oddkin/core/reactive';
+/** Identifies which attempt an event, stop, or decision belongs to. */
+export interface AttemptTarget {
+    readonly conversationId: string;
+    readonly runId: string;
+    readonly attemptId: string;
+}
+/**
+ * Optional replay identity. Supply only what the protocol guarantees: `eventId` when ids are
+ * unique per attempt, `seq` when offsets strictly increase per attempt. Content is never used to
+ * detect duplicates.
+ */
+export interface EventIdentity {
+    readonly eventId?: string | undefined;
+    readonly seq?: number | undefined;
+}
+export type AiEvent = EventIdentity & ({
+    readonly type: 'attempt-accepted';
+} | {
+    readonly type: 'message-start';
+    readonly messageId?: string | undefined;
+}
+/** Discard partial output for the message and rebuild it (protocol replay). */
+ | {
+    readonly type: 'message-reset';
+} | {
+    readonly type: 'step-start';
+}
+/** Remove parts added since the last `step-start`. */
+ | {
+    readonly type: 'step-reset';
+} | {
+    readonly type: 'text-start';
+    readonly partId: string;
+    readonly kind?: 'text' | 'reasoning';
+} | {
+    readonly type: 'text-delta';
+    readonly partId: string;
+    readonly delta: string;
+} | {
+    readonly type: 'text-end';
+    readonly partId: string;
+} | {
+    readonly type: 'part';
+    readonly part: MessagePart;
+} | {
+    readonly type: 'tool-input-start';
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly title?: string | undefined;
+} | {
+    readonly type: 'tool-input-delta';
+    readonly toolCallId: string;
+    readonly delta: string;
+} | {
+    readonly type: 'tool-input-available';
+    readonly toolCallId: string;
+    readonly input: JsonValue;
+} | {
+    readonly type: 'tool-executing';
+    readonly toolCallId: string;
+} | {
+    readonly type: 'tool-output';
+    readonly toolCallId: string;
+    readonly output: JsonValue;
+} | {
+    readonly type: 'tool-error';
+    readonly toolCallId: string;
+    readonly error: PublicError;
+} | {
+    readonly type: 'tool-denied';
+    readonly toolCallId: string;
+} | {
+    readonly type: 'approval-request';
+    readonly approval: ApprovalRecord;
+} | {
+    readonly type: 'approval-resolved';
+    readonly approvalId: string;
+    readonly revision: number;
+    readonly status: 'approved' | 'rejected' | 'expired' | 'superseded';
+} | {
+    readonly type: 'artifact';
+    readonly artifact: ArtifactRecord;
+} | {
+    readonly type: 'usage';
+    readonly usage: Usage;
+}
+/** Replace the attempt's message wholesale (reconciliation against a known scope). */
+ | {
+    readonly type: 'snapshot';
+    readonly message: MessageRecord;
+} | {
+    readonly type: 'finish';
+    readonly status?: 'completed' | 'awaiting-input';
+} | {
+    readonly type: 'abort';
+    readonly reason?: string | undefined;
+} | {
+    readonly type: 'error';
+    readonly error: PublicError;
+}
+/** Diagnostic or provider data; kept out of rendered content. */
+ | {
+    readonly type: 'metadata';
+    readonly data: JsonValue;
+});
+export type AiEventType = AiEvent['type'];
+/** Where an adapter delivers an attempt's events. Bound to one attempt; stale sinks drop events. */
+export interface EventSink {
+    readonly target: AttemptTarget;
+    push(event: AiEvent): void;
+    /** The stream ended. Without a terminal event the attempt becomes `interrupted`. */
+    close(): void;
+    /** False after the controller moved on (another conversation, a reset, or disposal). */
+    readonly active: boolean;
+}
+export interface SendRequest extends AttemptTarget {
+    readonly relation: AttemptRelation;
+    readonly parentAttemptId?: string | undefined;
+    /** The user message being answered (new or edited). */
+    readonly prompt: MessageRecord;
+    /** The assistant message id the attempt must write. */
+    readonly messageId: string;
+    /** Messages before the prompt on the active branch. */
+    readonly history: readonly MessageRecord[];
+}
+export type StopOutcome = 'cancelled' | 'already-finished' | 'not-found' | 'unknown';
+export type DecisionOutcome = 'accepted' | 'stale' | 'expired';
+export type RestoreOutcome = {
+    readonly status: 'restored';
+    readonly checkpointId: string;
+    readonly description: string;
+} | {
+    readonly status: 'failed';
+    readonly checkpointId: string;
+    readonly error: PublicError;
+};
+export interface ApprovalDecision extends AttemptTarget {
+    readonly approvalId: string;
+    readonly toolCallId?: string | undefined;
+    readonly revision: number;
+    readonly decision: 'approve' | 'reject';
+    readonly reason?: string | undefined;
+}
+/**
+ * What an adapter provides. Optional methods are capabilities; their absence makes the matching
+ * action unavailable. Promises resolve with the authoritative outcome or reject with a
+ * `PublicError`-shaped value.
+ */
+export interface ConversationTransport {
+    readonly capabilities: Capabilities;
+    /** Resolve when the backend accepted the request; stream events into `sink`. */
+    send(request: SendRequest, sink: EventSink): Promise<void>;
+    /** Cancel the underlying work for exactly this attempt. */
+    stop?(target: AttemptTarget): Promise<StopOutcome>;
+    /** Close the client stream only; the work continues according to the backend's policy. */
+    disconnect?(target: AttemptTarget): void;
+    /** Reattach to the same attempt; never starts new work. */
+    resume?(target: AttemptTarget, sink: EventSink): Promise<void>;
+    decide?(decision: ApprovalDecision): Promise<DecisionOutcome>;
+    loadHistory?(conversationId: string, before: string | undefined): Promise<ConversationSnapshot>;
+    submitFeedback?(feedback: FeedbackRecord): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/contracts/types.d.ts.map

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

package/dist/contracts/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/contracts/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/contracts/types.ts"],"names":[],"mappings":""}

package/dist/controllers/announcer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Announcement policy: which state changes deserve a screen-reader status message. Meaningful
+ * transitions only (submission, generation start and end, stop, failure, approval, history);
+ * never streamed text. Pure and DOM-free; `createAnnouncer` delivers the result through one
+ * live region per surface. Contract: docs/architecture/ai-interaction.md §10.2.
+ */
+import { format } from '@oddkin/core/i18n';
+import type { AnnounceDetail } from '../events.js';
+import type { ConversationState } from '../contracts/types.js';
+/** `important`: outcomes and requests for action. `all` adds progress. `none` is silent. */
+export type AnnouncementLevel = 'all' | 'important' | 'none';
+export interface AnnouncementStrings {
+    readonly sent: string;
+    readonly responding: string;
+    readonly completed: string;
+    readonly stopped: string;
+    readonly stopping: string;
+    readonly stopTooLate: string;
+    readonly stopUnknown: string;
+    readonly failed: string;
+    readonly interrupted: string;
+    readonly disconnected: string;
+    readonly awaitingInput: string;
+    readonly approvalRequested: string;
+    readonly approvalApproved: string;
+    readonly approvalRejected: string;
+    readonly approvalExpired: string;
+    readonly approvalSuperseded: string;
+    readonly toolFailed: string;
+    readonly historyLoaded: string;
+}
+export declare const DEFAULT_ANNOUNCEMENTS: AnnouncementStrings;
+/** Replace `{name}` placeholders. Values are plain text. */
+export { format };
+/** Announcements for the change from `previous` to `next`. Nothing for the first snapshot. */
+export declare function describeConversationChange(previous: ConversationState | undefined, next: ConversationState, level: AnnouncementLevel, strings?: AnnouncementStrings): AnnounceDetail[];
+//# sourceMappingURL=announcer.d.ts.map

package/dist/controllers/announcer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"announcer.d.ts","sourceRoot":"","sources":["../../src/controllers/announcer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,4FAA4F;AAC5F,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,WAAW,GAAG,MAAM,CAAC;AAE7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,eAAO,MAAM,qBAAqB,EAAE,mBAmBnC,CAAC;AAEF,4DAA4D;AAC5D,OAAO,EAAE,MAAM,EAAE,CAAC;AAIlB,8FAA8F;AAC9F,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,iBAAiB,EACxB,OAAO,GAAE,mBAA2C,GACnD,cAAc,EAAE,CA2IlB"}

package/dist/controllers/announcer.js

@@ -0,0 +1,169 @@
+/**
+ * Announcement policy: which state changes deserve a screen-reader status message. Meaningful
+ * transitions only (submission, generation start and end, stop, failure, approval, history);
+ * never streamed text. Pure and DOM-free; `createAnnouncer` delivers the result through one
+ * live region per surface. Contract: docs/architecture/ai-interaction.md §10.2.
+ */
+import { format } from '@oddkin/core/i18n';
+export const DEFAULT_ANNOUNCEMENTS = {
+    sent: 'Message sent.',
+    responding: 'Assistant is responding.',
+    completed: 'Response complete.',
+    stopped: 'Response stopped.',
+    stopping: 'Stopping…',
+    stopTooLate: 'The response finished before it could be stopped.',
+    stopUnknown: 'Stop could not be confirmed. The response may still be running.',
+    failed: 'Response failed: {message}',
+    interrupted: 'Connection lost. The response may be incomplete.',
+    disconnected: 'Disconnected from the response.',
+    awaitingInput: 'The assistant is waiting for your input.',
+    approvalRequested: 'Approval needed: {title}',
+    approvalApproved: 'Approved: {title}',
+    approvalRejected: 'Rejected: {title}',
+    approvalExpired: 'Approval expired: {title}',
+    approvalSuperseded: 'The proposal changed: {title}. Review it again.',
+    toolFailed: '{tool} failed.',
+    historyLoaded: 'Earlier messages loaded.',
+};
+/** Replace `{name}` placeholders. Values are plain text. */
+export { format };
+/** Announcements for the change from `previous` to `next`. Nothing for the first snapshot. */
+export function describeConversationChange(previous, next, level, strings = DEFAULT_ANNOUNCEMENTS) {
+    if (!previous || level === 'none' || previous.conversationId !== next.conversationId)
+        return [];
+    const out = [];
+    for (const attempt of Object.values(next.attempts)) {
+        const before = previous.attempts[attempt.attemptId];
+        const key = (what) => `attempt:${attempt.attemptId}:${what}`;
+        if (!before) {
+            if (attempt.relation === 'new')
+                out.push({ text: strings.sent, priority: 'polite', key: key('sent'), level: 'important' });
+            continue;
+        }
+        if (before.status !== attempt.status) {
+            switch (attempt.status) {
+                case 'streaming':
+                    if (before.status !== 'awaiting-input' && before.status !== 'interrupted')
+                        out.push({
+                            text: strings.responding,
+                            priority: 'polite',
+                            key: key('streaming'),
+                            level: 'all',
+                        });
+                    break;
+                case 'completed':
+                    out.push({
+                        text: strings.completed,
+                        priority: 'polite',
+                        key: key('completed'),
+                        level: 'important',
+                    });
+                    break;
+                case 'cancelled':
+                    out.push({
+                        text: strings.stopped,
+                        priority: 'polite',
+                        key: key('cancelled'),
+                        level: 'important',
+                    });
+                    break;
+                case 'failed':
+                    out.push({
+                        text: format(strings.failed, { message: attempt.error?.message ?? '' }),
+                        priority: 'assertive',
+                        key: key('failed'),
+                        level: 'important',
+                    });
+                    break;
+                case 'interrupted':
+                    out.push({
+                        text: strings.interrupted,
+                        priority: 'polite',
+                        key: key('interrupted'),
+                        level: 'important',
+                    });
+                    break;
+                case 'awaiting-input':
+                    out.push({
+                        text: strings.awaitingInput,
+                        priority: 'polite',
+                        key: key('awaiting'),
+                        level: 'important',
+                    });
+                    break;
+            }
+        }
+        if (before.stop !== attempt.stop) {
+            const stop = attempt.stop;
+            if (stop === 'requested')
+                out.push({
+                    text: strings.stopping,
+                    priority: 'polite',
+                    key: key('stopping'),
+                    level: 'all',
+                });
+            if (stop === 'too-late')
+                out.push({
+                    text: strings.stopTooLate,
+                    priority: 'polite',
+                    key: key('too-late'),
+                    level: 'important',
+                });
+            if (stop === 'unknown' || stop === 'failed')
+                out.push({
+                    text: strings.stopUnknown,
+                    priority: 'polite',
+                    key: key('stop-unknown'),
+                    level: 'important',
+                });
+        }
+        if (before.connection !== attempt.connection && attempt.connection === 'disconnected')
+            out.push({
+                text: strings.disconnected,
+                priority: 'polite',
+                key: key('disconnected'),
+                level: 'important',
+            });
+    }
+    for (const approval of Object.values(next.approvals)) {
+        const before = previous.approvals[approval.approvalId];
+        if (before && before.revision === approval.revision && before.status === approval.status)
+            continue;
+        const key = `approval:${approval.approvalId}:${approval.revision}:${approval.status}`;
+        const title = approval.title;
+        const text = approval.status === 'requested'
+            ? format(before && before.revision !== approval.revision
+                ? strings.approvalSuperseded
+                : strings.approvalRequested, { title })
+            : approval.status === 'approved'
+                ? format(strings.approvalApproved, { title })
+                : approval.status === 'rejected'
+                    ? format(strings.approvalRejected, { title })
+                    : approval.status === 'expired'
+                        ? format(strings.approvalExpired, { title })
+                        : undefined;
+        if (text)
+            out.push({ text, priority: 'polite', key, level: 'important' });
+    }
+    for (const tool of Object.values(next.tools)) {
+        const before = previous.tools[tool.toolCallId];
+        if (before && before.status !== tool.status && tool.status === 'output-error')
+            out.push({
+                text: format(strings.toolFailed, { tool: tool.title ?? tool.toolName }),
+                priority: 'polite',
+                key: `tool:${tool.toolCallId}:error`,
+                level: 'all',
+            });
+    }
+    if (previous.history === 'loading' && next.history !== 'loading' && next.history !== 'error')
+        out.push({
+            text: strings.historyLoaded,
+            priority: 'polite',
+            key: `history:${next.revision}`,
+            level: 'all',
+        });
+    return out
+        .filter((entry) => level === 'all' || entry.level === 'important')
+        .map(({ text, priority, key }) => ({ text, priority, key }));
+}
+//# sourceMappingURL=announcer.js.map

package/dist/controllers/announcer.js.map

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

package/dist/controllers/composer.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `ComposerController` — draft, attachments, and submission state for a prompt composer.
+ * Tracks draft revisions so acknowledging an older submission never clears newer input, keeps
+ * the draft through failures, and owns only the object URLs it created. DOM-free (File and
+ * URL APIs are used only when called). Contract: docs/architecture/ai-interaction.md §8.1.
+ */
+import { type Readable } from '@oddkin/core/reactive';
+import type { PublicError } from '../contracts/types.js';
+export type AttachmentStatus = 'selected' | 'uploading' | 'uploaded' | 'processing' | 'ready' | 'failed' | 'removed';
+/** Serializable attachment state; the File itself is held separately (`file(id)`). */
+export interface AttachmentState {
+    readonly id: string;
+    readonly name: string;
+    readonly size: number;
+    readonly mediaType: string;
+    readonly status: AttachmentStatus;
+    /** 0–1 when the host reports upload progress. */
+    readonly progress?: number | undefined;
+    /** Where the host stored it (after upload). */
+    readonly url?: string | undefined;
+    /** A preview URL this controller created and will revoke. */
+    readonly previewUrl?: string | undefined;
+    readonly error?: PublicError | undefined;
+}
+export type ComposerIssueCode = 'ai.attachment.type' | 'ai.attachment.size' | 'ai.attachment.count' | 'ai.attachment.unavailable';
+export interface ComposerIssue {
+    readonly code: ComposerIssueCode;
+    readonly name: string;
+    readonly limit?: number | string | undefined;
+}
+export interface Submission {
+    readonly submissionId: string;
+    /** Draft revision captured at submission. */
+    readonly revision: number;
+    readonly text: string;
+    readonly attachments: readonly AttachmentState[];
+}
+export interface ComposerState {
+    readonly text: string;
+    readonly revision: number;
+    readonly attachments: readonly AttachmentState[];
+    /** The in-flight or last failed submission. */
+    readonly submission?: {
+        readonly submissionId: string;
+        readonly revision: number;
+        readonly status: 'submitting';
+    } | {
+        readonly submissionId: string;
+        readonly revision: number;
+        readonly status: 'failed';
+        readonly error: PublicError;
+    } | undefined;
+    /** Validation feedback from the last attachment change. */
+    readonly issues: readonly ComposerIssue[];
+}
+export interface ComposerOptions {
+    /** MIME types, `type/*`, or `.ext` patterns, as in `<input accept>`. Empty accepts all. */
+    readonly accept?: readonly string[];
+    readonly maxFileSize?: number;
+    readonly maxFiles?: number;
+    /** Whether attachments are supported at all (capability). */
+    readonly attachments?: boolean;
+    readonly createId?: (prefix: string) => string;
+    /** Create preview URLs for images (default true when `URL.createObjectURL` exists). */
+    readonly previews?: boolean;
+}
+export declare function matchesAccept(file: {
+    name: string;
+    type: string;
+}, accept: readonly string[]): boolean;
+export declare class ComposerController {
+    #private;
+    readonly state: Readable<ComposerState>;
+    constructor(options?: ComposerOptions);
+    getSnapshot(): ComposerState;
+    configure(options: ComposerOptions): void;
+    /** Replace the draft text (user edit or host restore). Increments the draft revision. */
+    setText(text: string): void;
+    /** Validate and add files. Rejected files are reported in `issues` and never added. */
+    addFiles(files: Iterable<File>): readonly AttachmentState[];
+    /** The runtime File for an attachment (never part of serializable state). */
+    file(id: string): File | undefined;
+    /** Host-reported upload or processing progress. Ignored for removed attachments. */
+    updateAttachment(id: string, update: Partial<Pick<AttachmentState, 'status' | 'progress' | 'url' | 'error'>>): void;
+    removeAttachment(id: string): void;
+    clearIssues(): void;
+    /** Why the draft cannot be submitted now, or undefined when it can. */
+    blocker(): 'empty' | 'submitting' | 'attachments-busy' | 'attachments-failed' | undefined;
+    /**
+     * Capture the draft as a submission. The draft stays in place (and editable) until the host
+     * acknowledges acceptance; a failure leaves it untouched.
+     */
+    beginSubmit(): Submission | undefined;
+    /**
+     * The host accepted `submissionId`. Clears the submitted text only if the draft was not
+     * edited since; attachments added after submission stay. Stale ids are ignored.
+     */
+    acknowledge(submissionId: string): boolean;
+    /** The host rejected `submissionId`. The draft and attachments are preserved. */
+    fail(submissionId: string, error: PublicError): boolean;
+    /** Abandon the pending submission locally (e.g. the host cancelled it before acceptance). */
+    cancel(submissionId: string): boolean;
+    /** Revoke owned preview URLs and drop File references. */
+    dispose(): void;
+    /** Number of object URLs this controller currently owns (for leak tests). */
+    get ownedUrlCount(): number;
+    /** Revoke owned preview URLs (e.g. while a view is disconnected); the files are kept. */
+    releasePreviews(): void;
+    /** Recreate previews released by `releasePreviews`. */
+    restorePreviews(): void;
+}
+//# sourceMappingURL=composer.d.ts.map

package/dist/controllers/composer.d.ts.map

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