@altertable/data-app 0.65.0 → 0.67.0

package/dist/types/client/iframe.d.ts

@@ -12,10 +12,11 @@ export declare function createIframeTransport({ parentOrigin, window: frame, tim
     request: (message: RoutedMessage, signal?: AbortSignal) => Promise<unknown>;
     transport: (operation: string, input: unknown, signal?: AbortSignal) => Promise<TransportResponse>;
     lakehouse: {
-        queryAll(statement: string, { limit, signal }: {
+        queryAll(statement: string, { limit, signal, params }: {
             limit: number;
             signal: AbortSignal;
             name?: string;
+            params?: import("../core/contract.js").QueryParameters;
         }): Promise<import("../core/contract.js").QueryResult>;
     };
     dispose: () => void;
@@ -39,10 +40,11 @@ export declare function getDataAppTransport(frame?: Window): {
     request: (message: RoutedMessage, signal?: AbortSignal) => Promise<unknown>;
     transport: (operation: string, input: unknown, signal?: AbortSignal) => Promise<TransportResponse>;
     lakehouse: {
-        queryAll(statement: string, { limit, signal }: {
+        queryAll(statement: string, { limit, signal, params }: {
             limit: number;
             signal: AbortSignal;
             name?: string;
+            params?: import("../core/contract.js").QueryParameters;
         }): Promise<import("../core/contract.js").QueryResult>;
     };
     dispose: () => void;

package/dist/types/client/index.d.ts

@@ -11,3 +11,4 @@ export { createHttpTransport, DataAppError, type DataTransport, } from './transp
 export { createIframeTransport, installDataAppTransport, getDataAppTransport, type IframeTransport, } from './iframe.js';
 export { createMessageClient } from './messages.js';
 export type { DataAppLogger } from '../core/logger.js';
+export { createAnnotationClient } from './annotations.js';

package/dist/types/core/annotations.d.ts

@@ -0,0 +1,94 @@
+export type DataAppAnnotationDraft = {
+    id: string;
+    target: {
+        id: string;
+        label: string;
+        kind: 'widget' | 'element' | 'app';
+        text: string;
+        queryNames: string[];
+        glossaryIds: string[];
+    };
+    context: {
+        search: string;
+        hash: string;
+        displayedInput?: unknown;
+        /** Normalized position within the selected target, stable across scrolling/resizing. */
+        anchor?: {
+            x: number;
+            y: number;
+        };
+        cursor?: {
+            x: number;
+            y: number;
+        };
+        /** Normalized custom selection rectangle within the iframe document. */
+        region?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        screenshot?: {
+            mimeType: 'image/png';
+            dataUrl: string;
+            width: number;
+            height: number;
+        };
+        view?: string;
+        viewport: {
+            width: number;
+            height: number;
+        };
+        rect: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    comment: string;
+};
+export type DataAppAnnotationPresentation = {
+    enabled: boolean;
+    /** When provided, the host owns the mode and renders the annotation trigger. */
+    active?: boolean;
+    pinsVisible?: boolean;
+    showHint?: boolean;
+    readOnly?: boolean;
+    targets?: {
+        id: string;
+        targetId: string;
+        number: number;
+        comment?: string;
+        anchor?: {
+            x: number;
+            y: number;
+        };
+        region?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }[];
+    selectedAnnotationId?: string;
+    selectedTargetId?: string;
+    selectionId?: string;
+};
+/** Reconstruct at the boundary; discard extra fields and bound the entire JSON payload. */
+export declare function parseDataAppAnnotationDraft(value: unknown): DataAppAnnotationDraft;
+export declare const annotationDraftRoute: import("./messages.js").MessageRoute<DataAppAnnotationDraft, null>;
+export declare const annotationEditorStateRoute: import("./messages.js").MessageRoute<{
+    hasUnsavedChanges: boolean;
+}, null>;
+/** Request host-owned batch submission without transferring ownership of drafts. */
+export declare const annotationSendRoute: import("./messages.js").MessageRoute<null, null>;
+export declare const annotationUpdateRoute: import("./messages.js").MessageRoute<{
+    id: string;
+    comment: string;
+}, null>;
+/** A controlled shell acknowledges local exits (for example Escape). */
+export declare const annotationModeRoute: import("./messages.js").MessageRoute<{
+    active: boolean;
+}, null>;
+export declare function isAnnotationPresentation(value: unknown): value is DataAppAnnotationPresentation;

package/dist/types/core/appearance.d.ts

@@ -32,8 +32,8 @@ export declare function parseAppearance(value: unknown): AppearanceSettings;
 /** Resolve typed app settings without repeating authoring checks at runtime. */
 export declare function normalizeAppearance(value?: AppearanceOptions): AppearanceSettings;
 /**
- * Install semantic tokens on the document root, including portaled UI. Returns a cleanup for
- * system-theme listening.
+ * Select document-owned appearance presets and brand inputs. Public CSS tokens remain
+ * overridable in stylesheets. Cleanup restores the previous document appearance.
  */
 export declare function applyAppearance(value?: AppearanceOptions): () => void;
 /** Persist a viewer theme preference. Applying appearance belongs to the UI owner. */

package/dist/types/core/config.d.ts

@@ -1,15 +1,59 @@
 /**
- * App identity and display scope shared by browser and server.
- * @module @altertable/data-app/config
+ * App configuration shared by browser and server.
+ * @module @altertable/data-app
  */
+import { defineOperation } from './contract.js';
 import type { AppearanceOptions } from './appearance.js';
-export type DataAppConfig = {
+import { type QueryDefinitions } from './queries.js';
+export type { QueryDefinitions, QueryParameterValue } from './queries.js';
+export type DataAppConfig<Queries extends QueryDefinitions = QueryDefinitions> = {
     title: string;
     /** Display labels; scope does not grant data access. */
     scope: {
         organization: string;
         environment: string;
     };
-    appearance: AppearanceOptions;
+    /** Explain what the app helps readers explore. */
+    description: string;
+    /** Omit to use the standard appearance. */
+    appearance?: AppearanceOptions;
+    /** Named SQL statements and parameter defaults used by app operations. */
+    queries: Queries;
 };
+type ImmutableQueries<Queries extends QueryDefinitions> = {
+    readonly [Name in keyof Queries]: {
+        readonly statement: Queries[Name]['statement'];
+        readonly params: {
+            readonly [Param in keyof Queries[Name]['params']]: Readonly<Queries[Name]['params'][Param]>;
+        };
+    };
+};
+/** An app declaration with operations bound to its query registry. */
+export type DataAppDefinition<Queries extends QueryDefinitions = QueryDefinitions> = Readonly<Omit<DataAppConfig<Queries>, 'queries'>> & {
+    readonly queries: ImmutableQueries<Queries>;
+    defineOperation<Input, Output>(operation: Omit<Parameters<typeof defineOperation<Input, Output, Queries>>[0], 'queries'>): ReturnType<typeof defineOperation<Input, Output, Queries>>;
+};
+/**
+ * Define the app's query source of truth while preserving exact query and parameter names.
+ * Use `app.defineOperation()` to bind operations to these queries. Pass the app once
+ * to `mountDataApp({ app, component })` or `<DataAppProvider app={app}>`.
+ * The app owns an immutable snapshot of its registry; later input mutations do not change it.
+ * This declaration does not execute queries or mount UI. Static apps use `queries: {}`.
+ *
+ * Declare exactly one module-level const initialized with `defineDataApp({ ... })` in the app's
+ * declaration source. For the future backend extractor, the argument is read before bundling
+ * by resolving the named `defineDataApp` import from `@altertable/data-app`, including aliases.
+ * Variable name is arbitrary;
+ * export only for imports by other modules. The argument must be a direct object literal
+ * containing schema-valid objects, arrays, strings (including templates without interpolation),
+ * finite signed numbers, booleans, and null. No spreads, computed keys, references, calls,
+ * or callbacks inside it. Extraction must validate data without evaluating app code.
+ * TypeScript checks the shape, not AST syntax. Keep executable composition outside the call.
+ *
+ * SQL passes unchanged to the backend, which interprets placeholders such as `$orgId`.
+ * Declare every parameter with `{ defaultValue: value }` or `{}` for a required value.
+ * Values are finite numbers, strings, booleans, or null, never SQL fragments or identifiers.
+ * Caller values override defaults; trusted server `queryParams` cannot be overridden.
+ */
+export declare function defineDataApp<const Queries extends QueryDefinitions>(config: DataAppConfig<Queries>): DataAppDefinition<Queries>;
 export declare function dataAppTitle(config: Pick<DataAppConfig, 'title' | 'scope'>): string;

package/dist/types/core/contract.d.ts

@@ -1,3 +1,5 @@
+import { type QueryDefinitions, type QueryParameterValue } from './queries.js';
+export type { QueryDefinitions, QueryParameters, QueryParameterValue, } from './queries.js';
 import type { DateRange as DateRangeInput } from './date-range.js';
 import type { QueryResult, DataOperation, OperationContext } from './operation-types.js';
 export type { QueryResult, DisclosedQuery, Lakehouse, OperationContext, DataOperation, DataOperations, } from './operation-types.js';
@@ -69,24 +71,32 @@ export declare class DataSourceError extends Error {
     static [Symbol.hasInstance](value: unknown): boolean;
     constructor(reason: 'unauthorized' | 'forbidden' | 'rate_limited' | 'query_rejected' | 'unavailable', status?: number | undefined);
 }
-export type OperationQuery<Names extends Readonly<Record<string, string>>> = (name: Names[keyof Names], statement: string, options?: {
+type RegisteredQueryParameters<Queries extends QueryDefinitions, Name extends keyof Queries> = keyof Queries[Name]['params'] extends never ? Record<string, never> : Partial<Record<keyof Queries[Name]['params'], QueryParameterValue>>;
+export type RegisteredQuery<Queries extends QueryDefinitions> = <Name extends keyof Queries & string, const Params extends object = {}>(name: Name, params?: Params & NoInfer<RegisteredQueryParameters<Queries, Name>> & NoInfer<Record<Exclude<keyof Params, keyof Queries[Name]['params']>, never>> & NoInfer<Params extends (...args: never[]) => unknown ? never : object>, options?: {
     limit?: number;
 }) => Promise<QueryResult>;
-export declare function defineOperation<Input, Output, const Names extends Readonly<Record<string, string>> = Record<string, never>>(operation: Omit<DataOperation<Input, Output>, 'run' | 'queryNames'> & {
-    queryNames?: Names;
-    run: (context: OperationContext & {
-        query: OperationQuery<NoInfer<Names>>;
+export declare function defineOperation<Input, Output, const Queries extends QueryDefinitions>(operation: Omit<DataOperation<Input, Output>, 'run' | 'queryNames'> & {
+    queries: Queries;
+    run: (context: Pick<OperationContext, 'signal'> & {
+        query: RegisteredQuery<NoInfer<Queries>>;
     }, input: Input) => Promise<Output>;
-}): DataOperation<Input, Output> & {
-    queryNames?: Names;
+}): Omit<DataOperation<Input, Output>, 'queryNames'> & {
+    queryNames: {
+        readonly [Name in keyof Queries & string]: Name;
+    };
 };
-export declare const connectionQueryNames: {
-    readonly connection: "connection-check";
+/** A connectivity probe uses the app's registered connection query. */
+export declare function connectionCheck<const Queries extends QueryDefinitions & {
+    connection: QueryDefinitions[string];
+}>(queries: Queries): Omit<DataOperation<Record<string, never>, true>, "queryNames"> & {
+    queryNames: { readonly [Name in keyof Queries & string]: Name; };
 };
-/** Success requires a bounded SQL query; it does not establish access to a particular dataset. */
-export declare function connectionCheck(): DataOperation<Record<string, never>, true>;
 export { dimensionFilter, parseDimensionSelection, parseFacetOptions, dimensionPredicate, } from './dimension.js';
 export type { DimensionSelection, DimensionMember, DimensionOption, DimensionVariable, DimensionFilterOptions, } from './dimension.js';
 export { createMessageRouter, defineMessageRoute, defineDataQueryRoute, MessageRoutingError, dataAppRoutes, navigationUpdateRoute, sqlQueryRoute, } from './messages.js';
 export type { MessageContext, RoutedMessage, MessageDispatcher, MessageTransport, MessageRoute, MessageRoutes, MessageInput, MessageHandlers, MessageOutput, OperationContracts, DataQueryInput, DataQueryBody, DataQueryRoute, NavigationUpdate, SqlQueryInput, } from './messages.js';
 export type { TransportResponse } from './bridge.js';
+export { annotationDraftRoute, annotationModeRoute, annotationEditorStateRoute, annotationSendRoute, annotationUpdateRoute, parseDataAppAnnotationDraft, } from './annotations.js';
+export type { DataAppAnnotationDraft, DataAppAnnotationPresentation, } from './annotations.js';
+export { numberFilter, booleanFilter, parseNumberSelection, parseBooleanSelection, } from './filters.js';
+export type { NumberSelection, NumberOperator, NumberFilter, BooleanSelection, BooleanFilter, } from './filters.js';

package/dist/types/core/dimension.d.ts

@@ -9,7 +9,7 @@ export type DimensionMember<T extends DimensionValue = DimensionValue> = {
 export type DimensionSelection<T extends DimensionValue = DimensionValue> = {
     kind: 'all';
 } | {
-    kind: 'include';
+    kind: 'include' | 'exclude';
     members: readonly DimensionMember<T>[];
 };
 export type DimensionOption<T extends DimensionValue = DimensionValue> = {
@@ -17,11 +17,12 @@ export type DimensionOption<T extends DimensionValue = DimensionValue> = {
     label: string;
     count?: number;
 };
-export type DimensionVariable<T extends DimensionValue = DimensionValue> = Omit<AppVariable<DimensionSelection<T>, 'dimension'>, 'options'> & {
+export type DimensionVariable<T extends DimensionValue = DimensionValue> = AppVariable<DimensionSelection<T>, 'dimension'> & {
     label: string;
-    selection: 'single' | 'multiple';
+    selectionMode: 'single' | 'multiple';
     valueType: 'string' | 'number';
     allowMissing: boolean;
+    allowExclusion: boolean;
     maxSelected: number;
     options: readonly DimensionOption<T>[];
     facet?: {
@@ -35,8 +36,9 @@ export type DimensionFilterOptions<T extends DimensionValue> = {
     key: string;
     label: string;
     valueType: T extends number ? 'number' : 'string';
-    selection: 'single' | 'multiple';
+    selectionMode: 'single' | 'multiple';
     allowMissing?: boolean;
+    allowExclusion?: boolean;
     maxSelected?: number;
     history?: HistoryMode;
 } & ({

package/dist/types/core/filters.d.ts

@@ -0,0 +1,44 @@
+import type { AppVariable, HistoryMode } from './variables.js';
+export type NumberOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
+export type NumberSelection = {
+    kind: 'all';
+} | {
+    kind: 'comparison';
+    operator: NumberOperator;
+    value: number;
+} | {
+    kind: 'range';
+    min?: number;
+    max?: number;
+};
+export type BooleanSelection = {
+    kind: 'all';
+} | {
+    kind: 'is';
+    value: boolean;
+};
+export type NumberFilter = AppVariable<NumberSelection, 'numberFilter'> & {
+    label: string;
+    min?: number;
+    max?: number;
+};
+export type BooleanFilter = AppVariable<BooleanSelection, 'booleanFilter'> & {
+    label: string;
+};
+type FilterOptions<Value> = {
+    key: string;
+    label: string;
+    defaultValue?: Value;
+    history?: HistoryMode;
+};
+export declare const numberOperatorLabels: Record<NumberOperator, string>;
+/** Exact numeric predicates; range bounds are inclusive and may be open-ended. */
+export declare function numberFilter({ key, label, min, max, defaultValue, history, }: FilterOptions<NumberSelection> & {
+    min?: number;
+    max?: number;
+}): NumberFilter;
+/** Boolean predicate with a distinct unrestricted state. */
+export declare function booleanFilter({ key, label, defaultValue, history, }: FilterOptions<BooleanSelection>): BooleanFilter;
+export declare function parseNumberSelection(value: unknown, filter: NumberFilter): NumberSelection;
+export declare function parseBooleanSelection(value: unknown, filter: BooleanFilter): BooleanSelection;
+export {};

package/dist/types/core/messages.d.ts

@@ -1,3 +1,4 @@
+import { type QueryParameters } from './queries.js';
 import type { TransportResponse, QueryResult, OperationContracts, DataQueryInput, DataQueryBody, OutputOf } from './operation-types.js';
 export type { OperationContracts, DataQueryInput, DataQueryBody, } from './operation-types.js';
 import { type NavigationUpdate } from './navigation.js';
@@ -49,6 +50,7 @@ export declare const navigationUpdateRoute: MessageRoute<NavigationUpdate, null>
 export type SqlQueryInput = {
     statement: string;
     limit: number;
+    params?: QueryParameters;
 };
 /** SQL delivery for browser-owned operations. Hosts must enforce backend access and resource limits. */
 export declare const sqlQueryRoute: MessageRoute<SqlQueryInput, QueryResult>;

package/dist/types/core/operation-types.d.ts

@@ -1,4 +1,5 @@
 /** Shared operation, query, and response contracts; independent of delivery adapters. */
+import type { QueryParameters } from './queries.js';
 export type OperationContracts = Record<string, {
     input: (value: unknown) => unknown;
     output: (value: unknown) => unknown;
@@ -17,10 +18,11 @@ export type QueryResult = {
     rows: unknown[][];
     queryId?: string;
 };
-/** One named statement an operation ran. Returned only when SQL disclosure is allowed. */
+/** One registered statement an operation ran, with its parameter values. */
 export type DisclosedQuery = {
     name: string;
     statement: string;
+    params?: QueryParameters;
     queryId?: string;
 };
 /** Query interface supplied by a server adapter or an authorized iframe bridge. */
@@ -29,11 +31,13 @@ export type Lakehouse = {
         limit: number;
         signal: AbortSignal;
         name?: string;
+        params?: QueryParameters;
     }): Promise<QueryResult>;
 };
 export type OperationContext = {
     lakehouse: Lakehouse;
     signal: AbortSignal;
+    queryParams?: QueryParameters;
 };
 /**
  * Parsers run in the operation executor's runtime: server for HTTP apps, browser for bundle apps.
@@ -49,7 +53,6 @@ export type DataOperation<Input, Output> = {
         maxQueryRows: number;
         maxDurationMs: number;
         maxResponseBytes?: number;
-        exposeSql?: boolean;
     };
 };
 /** Heterogeneous registry: inputs vary per operation, so checks retain unknown values. */

package/dist/types/core/operation.d.ts

@@ -1,15 +1,14 @@
-import type { DataOperations, Lakehouse, DataQueryBody } from './operation-types.js';
+import type { DataOperations, Lakehouse, OperationContext, DataQueryBody } from './operation-types.js';
 type Operation = DataOperations[string];
 type OperationExecutionOptions = {
     operationName: string;
     lakehouse: Lakehouse;
     signal: AbortSignal;
-    /** Include query evidence in the response; this does not keep browser-owned SQL private. */
-    includeSql: boolean;
     requestId: string;
+    queryParams?: OperationContext['queryParams'];
 };
 /** Shared operation execution. Adapters own authorization, delivery, and public errors. */
-export declare function executeDataOperation(operation: Operation, value: unknown, { operationName, lakehouse, signal: requestSignal, includeSql, requestId, }: OperationExecutionOptions): Promise<{
+export declare function executeDataOperation(operation: Operation, value: unknown, { operationName, lakehouse, signal: requestSignal, requestId, queryParams, }: OperationExecutionOptions): Promise<{
     body: DataQueryBody<unknown>;
     serializedBody: string;
 }>;

package/dist/types/core/presentation.d.ts

@@ -1,7 +1,9 @@
+import { type DataAppAnnotationPresentation } from './annotations.js';
 import type { Theme } from './appearance.js';
 /** Presentation owned by the parent shell, delivered only over a trusted bridge. */
 export type DataAppPresentation = {
     surface: 'embedded' | 'standalone';
     theme: Theme;
+    annotations?: DataAppAnnotationPresentation;
 };
 export declare function isDataAppPresentation(value: unknown): value is DataAppPresentation;

package/dist/types/core/queries.d.ts

@@ -0,0 +1,16 @@
+export type QueryParameterValue = string | number | boolean | null;
+type QueryDefinition = {
+    statement: string;
+    params: Readonly<Record<string, {
+        defaultValue?: QueryParameterValue;
+    }>>;
+};
+export type QueryDefinitions = Readonly<Record<string, QueryDefinition>>;
+/** Parameters are scalar SQL values, never identifiers or SQL fragments. */
+export type QueryParameters = Readonly<Record<string, QueryParameterValue>>;
+export declare function isQueryParameters(value: unknown): value is QueryParameters;
+/** Retain authored statements and defaults, rejecting empty SQL and invalid scalar defaults. */
+export declare function snapshotQueries(definitions: QueryDefinitions): QueryDefinitions;
+/** Context owns protected values; callers supply filters; defaults fill remaining declarations. */
+export declare function resolveQueryParameters(declarations: QueryDefinition['params'], values: Partial<QueryParameters>, context: QueryParameters): QueryParameters;
+export {};

package/dist/types/core/uuid.d.ts

@@ -0,0 +1,2 @@
+/** Opaque documents can lack randomUUID even when cryptographic randomness is available. */
+export declare function randomUuid(): string;

package/dist/types/core/variables.d.ts

@@ -1,25 +1,25 @@
 import { type DatePresetId, type DateRange } from './date-range.js';
 import type { DateRangeContract, DateRangeRequest } from './contract.js';
 import type { DimensionSelection, DimensionVariable } from './dimension.js';
+import type { NumberFilter, BooleanFilter } from './filters.js';
 import type { HistoryMode } from './navigation.js';
 export type { HistoryMode } from './navigation.js';
 /** An app-owned value with one URL representation. Controls never parse or write routes. */
-export type AppVariable<Value, Kind extends string = Value extends string ? 'text' | 'select' : 'dateRange'> = {
+export type AppVariable<Value, Kind extends string = string> = {
     kind: Kind;
     label?: string;
-    options?: readonly {
-        id: string;
-        label: string;
-    }[];
     urlKeys: readonly string[];
     defaultValue: Value;
+    /** Unrestricted value, when this variable represents a filter. */
+    clearValue?: Value;
+    describe?: (value: Value) => string;
     history: HistoryMode;
     read: (params: URLSearchParams) => Value;
     write: (value: Value) => Record<string, string | null>;
     valid: (value: Value) => boolean;
     same: (left: Value, right: Value) => boolean;
 };
-export type VariableCollection = Record<string, AppVariable<string> | DateRangeVariable | DimensionVariable<any>>;
+export type VariableCollection = Record<string, SearchVariable | ChoiceVariable | MultiChoiceVariable | DateRangeVariable | DimensionVariable<any> | NumberFilter | BooleanFilter>;
 export type AppVariableValues<Variables> = {
     [Key in keyof Variables]: Variables[Key] extends DimensionVariable<infer Value> ? DimensionSelection<Value> : Variables[Key] extends AppVariable<infer Value, string> ? Value : never;
 };
@@ -31,13 +31,32 @@ type ScalarVariableOptions = {
     defaultValue?: string;
     history?: HistoryMode;
 };
-/** A local text filter. Typing replaces the current history entry by default. */
-export declare function textVariable({ key, label, defaultValue, history, }: ScalarVariableOptions): AppVariable<string>;
-/** A single choice. Supply values when the option set is known before data loads. */
-export declare function selectVariable({ key, label, defaultValue, values, history, }: ScalarVariableOptions & {
+export type SearchVariable = AppVariable<string, 'search'>;
+export type ChoiceOption = {
+    id: string;
+    label: string;
+    description?: string;
+};
+export type ChoiceVariable = AppVariable<string, 'choice'> & {
+    options: readonly ChoiceOption[];
+};
+export type MultiChoiceVariable = AppVariable<readonly string[], 'multiChoice'> & {
+    options: readonly ChoiceOption[];
+    maxSelected: number;
+};
+/** Search query state; typing replaces history by default. */
+export declare function searchVariable({ key, label, defaultValue, history, }: ScalarVariableOptions): SearchVariable;
+/** Validate labeled choices before controls or URL state consume them. */
+export declare function validateChoiceOptions(options: readonly ChoiceOption[]): void;
+export declare function choiceVariable({ key, label, defaultValue, options, history, }: ScalarVariableOptions & {
     defaultValue: string;
-    values?: readonly string[];
-}): AppVariable<string>;
+    options: readonly ChoiceOption[];
+}): ChoiceVariable;
+export declare function multiChoiceVariable({ key, label, defaultValue, options, maxSelected, history, }: Omit<ScalarVariableOptions, 'defaultValue'> & {
+    defaultValue?: readonly string[];
+    options: readonly ChoiceOption[];
+    maxSelected?: number;
+}): MultiChoiceVariable;
 export type DateRangeSelection = {
     kind: 'preset';
     id: DatePresetId;
@@ -50,10 +69,8 @@ export type DateRangeSelection = {
 };
 export type DateRangeVariableOptions = {
     label?: string;
-    /** URL key for a relative preset; explicit dates use startKey and endKey. */
+    /** URL key for a relative preset; explicit dates use start/end for period, otherwise key-prefixed fields. */
     key: string;
-    startKey?: string;
-    endKey?: string;
     defaultValue: DateRangeSelection & {
         comparison?: never;
     };
@@ -61,9 +78,8 @@ export type DateRangeVariableOptions = {
     history?: HistoryMode;
     /** Opt into a URL-backed comparison with the preceding equal-length range. */
     comparison?: boolean;
-    comparisonKey?: string;
 };
-export type DateRangeVariable = AppVariable<DateRangeSelection> & {
+export type DateRangeVariable = AppVariable<DateRangeSelection, 'dateRange'> & {
     kind: 'dateRange';
     supportsComparison: boolean;
     input: (selection: DateRangeSelection) => DateRangeRequest;
@@ -79,4 +95,4 @@ export type DateRangeVariable = AppVariable<DateRangeSelection> & {
     comparisonRange: (selection: DateRangeSelection) => DateRange | null;
 };
 /** A date variable keeps relative presets relative and validates exact dates against source coverage. */
-export declare function dateRangeVariable({ key, label, startKey, endKey, defaultValue, contract, history, comparison, comparisonKey, }: DateRangeVariableOptions): DateRangeVariable;
+export declare function dateRangeVariable({ key, label, defaultValue, contract, history, comparison, }: DateRangeVariableOptions): DateRangeVariable;

package/dist/types/embed/runtime-html.d.ts

@@ -0,0 +1,2 @@
+export declare const PAGE_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; connect-src 'none'; form-action 'none'; base-uri 'none'";
+export declare function runtimeHtml(parentOrigin: string): string;

package/dist/types/embed/source.d.ts

@@ -4,7 +4,8 @@ export type DataAppSource = {
     url: string;
 } | {
     type: 'bundle';
-    bootstrapUrl: string;
+    /** Omit to use the packaged, network-isolated data document. */
+    bootstrapUrl?: string;
     javascript: string;
 };
 export type DataAppSourceOptions = DataAppHostOptions & {

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+/** Portable data app declarations; safe in browser and server modules. */
+export { defineDataApp, dataAppTitle } from './core/config.js';
+export type { DataAppConfig, DataAppDefinition, QueryDefinitions, QueryParameterValue, } from './core/config.js';

package/dist/types/react/annotations/AnnotationBar.d.ts

@@ -0,0 +1,30 @@
+import { type Ref } from 'react';
+import type { Theme } from '../../core/appearance.js';
+import { type DataAppAnnotationDraft } from '../../core/annotations.js';
+export type AnnotationBarHandle = {
+    /** Submit through the same guards, pending state, and retry feedback as the Send button. */
+    send: () => Promise<void>;
+};
+export type AnnotationBarProps = {
+    ref?: Ref<AnnotationBarHandle>;
+    annotations: readonly DataAppAnnotationDraft[];
+    active?: boolean;
+    theme?: Theme;
+    disabled?: boolean;
+    deletedAnnotationId?: string;
+    onUndoDelete?: (id: string) => void;
+    onDismissUndo?: () => void;
+    hasUnsavedChanges?: boolean;
+    pinsVisible: boolean;
+    onPinsVisibleChange: (visible: boolean) => void;
+    onSelect: (id: string) => void;
+    onDelete: (id: string) => void;
+    onClear: () => void;
+    /** Let host apps use their existing confirmation dialog. */
+    requestDiscard?: (discard: () => void) => void;
+    /** Resolve only after the outer application's agent API accepts this snapshot. */
+    onSend: (annotations: readonly DataAppAnnotationDraft[]) => Promise<void>;
+    onClose: () => void;
+};
+/** Host-owned batch controls. Collection changes and agent submission stay with the outer app. */
+export declare function AnnotationBar({ ref, annotations, active, theme, disabled, deletedAnnotationId, onUndoDelete, onDismissUndo, hasUnsavedChanges, pinsVisible, onPinsVisibleChange, onSelect, onDelete, onClear, requestDiscard, onSend, onClose, }: AnnotationBarProps): import("react").JSX.Element | null;

package/dist/types/react/annotations/AnnotationControls.d.ts

@@ -0,0 +1,10 @@
+import { type ComponentRef, type RefObject } from 'react';
+import type { DataAppAnnotationPresentation } from '../../core/annotations.js';
+type AnnotationControlsProps = {
+    rootRef: RefObject<ComponentRef<'div'> | null>;
+    presentation: DataAppAnnotationPresentation;
+    displayedInput?: unknown;
+    view?: string;
+};
+export declare function AnnotationControls({ rootRef, presentation, displayedInput, view, }: AnnotationControlsProps): import("react").JSX.Element;
+export {};

package/dist/types/react/annotations/AnnotationEditor.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentRef, CSSProperties, Ref } from 'react';
+import type { AnnotationEditorState } from './annotation-editor-state.js';
+type AnnotationEditorProps = {
+    editor: AnnotationEditorState;
+    editorRef: Ref<ComponentRef<'section'>>;
+    textareaRef: Ref<ComponentRef<'textarea'>>;
+    style: CSSProperties;
+    disabled: boolean;
+    onCommentChange: (comment: string) => void;
+    onSubmit: () => void;
+    onSend: () => void;
+    onRetryScreenshot: () => void;
+    onShakeEnd: () => void;
+};
+export declare function AnnotationEditor({ editor, editorRef, textareaRef, style, disabled, onCommentChange, onSubmit, onSend, onRetryScreenshot, onShakeEnd, }: AnnotationEditorProps): import("react").JSX.Element;
+export {};

package/dist/types/react/annotations/AnnotationMarkers.d.ts

@@ -0,0 +1,19 @@
+import type { AnnotationPoint, AnnotationRect } from './annotation-targets.js';
+export type AnnotationPin = {
+    id: string;
+    number: number;
+    anchor: AnnotationPoint;
+    rect: AnnotationRect;
+};
+type AnnotationMarkersProps = {
+    outline?: AnnotationRect;
+    rounded: boolean;
+    pins: AnnotationPin[];
+    pinsVisible: boolean;
+    disabled: boolean;
+    showHint: boolean;
+    hasDuplicateIds: boolean;
+    onOpenAnnotation: (id: string) => void;
+};
+export declare function AnnotationMarkers({ outline, rounded, pins, pinsVisible, disabled, showHint, hasDuplicateIds, onOpenAnnotation, }: AnnotationMarkersProps): import("react").JSX.Element;
+export {};