@bicharts/chart-host 0.6.83 → 0.6.85

package/dist/page.mjs

@@ -14,7 +14,10 @@ import {
   readControls,
   viewFromToken,
   viewToken
-} from "./chunk-XIAL6EEC.mjs";
+} from "./chunk-DTOGTKAJ.mjs";
+import "./chunk-QIRLWJBI.mjs";
+import "./chunk-IURROJT7.mjs";
+import "./chunk-MR6TL7QZ.mjs";
 import "./chunk-GHODWOAL.mjs";
 export {
   LINKED_HOVER_CLASS,

package/dist/react.mjs

@@ -13,7 +13,7 @@ import {
   payloadRowReader,
   viewFromToken,
   viewToken
-} from "./chunk-XIAL6EEC.mjs";
+} from "./chunk-DTOGTKAJ.mjs";
 import {
   assembleD3,
   createChartGroup,
@@ -22,11 +22,14 @@ import {
   loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-CJNONH6V.mjs";
-import "./chunk-2XWE6YFO.mjs";
-import "./chunk-MGAO2DR7.mjs";
+} from "./chunk-CDWNZHIN.mjs";
+import "./chunk-QIRLWJBI.mjs";
+import "./chunk-2ZUUIZWL.mjs";
+import "./chunk-7HKVV5T5.mjs";
+import "./chunk-IURROJT7.mjs";
+import "./chunk-BQFG5HWZ.mjs";
 import "./chunk-A2GMXZP7.mjs";
-import "./chunk-7JWL6LYE.mjs";
+import "./chunk-MR6TL7QZ.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/react.tsx

package/dist/testing.mjs

@@ -4,7 +4,7 @@ import {
   MARK_CLASS,
   MARK_SELECTED_CLASS,
   ROW_IDX_ATTR
-} from "./chunk-7JWL6LYE.mjs";
+} from "./chunk-MR6TL7QZ.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/testing/interact.ts

package/dist/types/contract.d.ts

@@ -1,4 +1,4 @@
-export declare const HOST_CONTRACT_VERSION = "1.14.0";
+export declare const HOST_CONTRACT_VERSION = "1.16.0";
 export type GeoPointPrecision = "latlon" | "city" | "zip3" | "state" | "country";
 /** Every valid tier, ordered most precise → coarsest. Runtime form of GeoPointPrecision. */
 export declare const GEO_POINT_PRECISIONS: readonly GeoPointPrecision[];
@@ -19,6 +19,18 @@ export declare const MARK_KEY_ATTR = "data-mark-key";
 export declare const NO_ROW_MARKS_ATTR = "data-lch-no-row-marks";
 export declare const SNAPSHOT_SVG_ATTR = "data-lch-snapshot";
 export declare const XFILTER_REFRESH_EVENT = "llm-xfilter-refresh";
+/** What the event carries. `source` names who selected ("user" when a reader's gesture did); the host
+ *  passes it on to its subscribers, and "chart" stands in when it is absent. */
+export type XfilterRefreshDetail = {
+    clear: true;
+    source?: string;
+} | {
+    mark: Element;
+    source?: string;
+} | {
+    rows: readonly number[];
+    source?: string;
+};
 export declare const CONTAINER_SLOT_ANIM_STOP = "__llmAnimStop";
 export declare const CONTAINER_SLOT_XF_CLEAR = "__llmXfClear";
 export declare const CONTAINER_SLOT_INITIAL_XF_MARK = "__llmInitialXfMark";
@@ -109,6 +121,9 @@ export interface RenderOptions {
         rolesRefused?: string[];
     } | null;
     dateCellsAreUtcDays?: boolean;
+    dataComplete?: boolean;
+    rowsWithheld?: number;
+    rowsFilteredOut?: number;
     geoPointDest?: {
         precision: GeoPointPrecision | null;
         precisionCounts: Record<GeoPointPrecision, number>;
@@ -178,6 +193,25 @@ export interface RenderOptions {
      * take the reader's gesture with it: the helper swallows anything this raises.
      */
     onControlChange?: (e: ChartControlChange) => void;
+    /**
+     * THE HOST LASSO (contract 1.16.0): whether this chart gets the gesture that draws around marks and selects the
+     * ones inside, and what the host does when it ends. A chart never draws the gesture; it hears it as an
+     * `llm-lasso` event on its container.
+     *   capable  - the capability the SERVER sent with this chart (the chart's type declares that it has no drag
+     *              gesture of its own and that a lasso means something for it). ABSENT MEANS NOT CAPABLE: no host
+     *              holds a list of chart types, so a chart saved before the capability existed has none.
+     *   enabled  - the reader's setting; on unless it is exactly false. Both must hold for a surface to be drawn.
+     *   rowCap   - the most rows in view that still get a lasso; above it the whole lasso is off and a caption says
+     *              so. Absent is LASSO_ROW_CAP (provisional).
+     *   actions  - what the host runs on release, in order, by name. Absent is ["select"]; a name the host does
+     *              not know is skipped, so a list can be sent ahead of the build that understands it.
+     */
+    lasso?: {
+        enabled?: boolean;
+        rowCap?: number;
+        actions?: string[];
+        capable?: boolean;
+    };
 }
 /** One reader gesture on a chart's own control. */
 export interface ChartControlChange {

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, NO_ROW_MARKS_ATTR, SELECTION_RULE_ATTR, SELECTION_RULE_CLICKED_MARKS, MARK_KEY_ATTR, CONTAINER_SLOT_CLICKED_MARKS, SNAPSHOT_SVG_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, FLIP_INTERVAL_MIN_MS, FLIP_INTERVAL_MAX_MS, FLIP_DIRECTION_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type FlipDirection, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, } from "./contract";
+export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, NO_ROW_MARKS_ATTR, SELECTION_RULE_ATTR, SELECTION_RULE_CLICKED_MARKS, MARK_KEY_ATTR, CONTAINER_SLOT_CLICKED_MARKS, SNAPSHOT_SVG_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, FLIP_INTERVAL_MIN_MS, FLIP_INTERVAL_MAX_MS, FLIP_DIRECTION_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type FlipDirection, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, type XfilterRefreshDetail, } from "./contract";
 export { resolveOptions, type ResolveOptionsInput } from "./defaults";
 export { OPTIONS_VOCABULARY, LIVE_OPTION_KEYS, MAX_MAP_POINTS_MIN, MAX_MAP_POINTS_MAX, LIMIT_COUNT_MAX, wireLimitCount, codeReadsOption, type OptionVocabularyEntry, type OptionTiming, type OptionWire, type OptionKey, } from "./optionsVocabulary";
 export { loadGeo, geoFromCache, registerGeo, registerGeoAsset, geoAssetFor, clearGeoCache, type GeoAssetName, } from "./geoLazy";
@@ -13,14 +13,15 @@ export type { MarkNoteLike, NoteBadgeOptions } from "./markNotes";
 export type { Controls, ControlInfo, ControlsAttachment } from "./controls";
 export { createChartGroup, toSourceRows, syncMemberSelection, type ChartGroup, type ChartGroupMember, type ChartGroupSelection, type ChartGroupChange, type ChartGroupMemberOptions, type ChartGroupSourceOptions, type ChartGroupPayload } from "./group";
 export type { Filter, FilterScope, FilterOptions, FilterKey, FilterChangeReason, FilterBinding, BindFilterOptions, VegaInteractionEvent, PageView } from "./filterScope";
-export { createMarkResolver, isInsideControl, rowIdxsFromMark, nextSelection, selectionRuleOf, markKeyOf, planSelectionPaint, nextClickedMarks, sameRowSet, type SelectionRule, type ClickedMarks, type SelectionPaintMark, type SelectionPaintMode, type SelectionPaintPlan, collectD3GlyphCenters, clearSelectionGlyphs, paintSelectionGlyphs, SELECTION_GLYPH_CLASS, type MarkResolver, type MarkResolverEnv, type GlyphCenter, type SelectionGlyphStyle, type SelectionModifiers, } from "./selection";
+export { createMarkResolver, isInsideControl, rowIdxsFromMark, nextSelection, DRAG_NOT_CLICK_PX, gestureWasDrag, trackPress, pressOf, clearPress, clickWasDrag, CONTAINER_SLOT_PRESS_AT, type PressPoint, dispatchRowSet, validRowSet, ROW_SET_MAX, selectionRuleOf, markKeyOf, planSelectionPaint, nextClickedMarks, sameRowSet, type SelectionRule, type ClickedMarks, type SelectionPaintMark, type SelectionPaintMode, type SelectionPaintPlan, collectD3GlyphCenters, clearSelectionGlyphs, paintSelectionGlyphs, SELECTION_GLYPH_CLASS, type MarkResolver, type MarkResolverEnv, type GlyphCenter, type SelectionGlyphStyle, type SelectionModifiers, } from "./selection";
+export { installLasso, clearLasso, lassoVerdict, lassoRowCap, lassoActions, registerLassoAction, pointInShape, LASSO_ROW_CAP, LASSO_DRAG_PX, LASSO_SAMPLE_PX, LASSO_MAX_VERTICES, LASSO_RESTORE_MAX_VERTICES, LASSO_RESTORE_MAX_SHAPES, LASSO_EVENT, LASSO_SURFACE_CLASS, LASSO_OUTLINE_CLASS, LASSO_COUNT_CLASS, LASSO_NOTE_CLASS, LASSO_PLOT_CLASS, LASSO_MODE_ATTR, LASSO_KNOB_KEY, LASSO_AXES_SLOT, LASSO_DEFAULT_ACTIONS, type LassoSetting, type LassoVerdict, type LassoMode, type LassoSpace, type LassoShape, type LassoStored, type LassoEventDetail, type LassoAxes, type LassoAction, type LassoActionContext, type LassoEnv, type LassoHandle, } from "./lasso";
 export type { AdapterEvent, AdapterHit, AdapterId, AdapterScene, MarkHandle, MarkInfo, MarkRole, PaintRequest, RendererAdapter, RowTable, } from "./adapters/types";
 export { planTrivialChart, compileTrivialSource, type TrivialPlan, type TrivialShapeKind } from "./trivial";
 export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngDataUrl, tableHostOf, chartSvgOf, htmlToSvgDataUrl, htmlNaturalSize, type SnapshotOptions } from "./snapshot";
 export { shouldReview, buildReviewWire, bareBase64, actionFor, type ReviewGate, type ReviewWire, type ReviewVerdict, type ReviewAction } from "./review";
 export { askApplyImprovements, type ReviewDialogOptions, type ReviewDialogText } from "./reviewDialog";
 export { mountProductFeedbackBox, normaliseProductFeedbackText, productFeedbackSendable, buildProductFeedbackPayload, PRODUCT_FEEDBACK_MAX_CHARS, PRODUCT_FEEDBACK_MIN_CHARS, type ProductFeedbackBox, type ProductFeedbackBoxOptions, type ProductFeedbackText, type ProductFeedbackSendResult, type ProductFeedbackPayload, type ProductFeedbackIdentity, type ProductFeedbackHost, } from "./productFeedback";
-export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, type QualifyGroupState, type QualifyGroupHeading, orderRefusalsForDisplay, refusalIsSelectable, hasRefusalsToShow, qualifyRefusalHeadingFor, newQualifyRefusalGroupState, qualifyRefusalReason, QUALIFY_REFUSAL_UNSPECIFIED, type QualifyRefusalRow, type QualifyRefusalGroupState, type QualifyRefusalHeading, } from "./qualifyGroups";
+export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, type QualifyGroupState, type QualifyGroupHeading, orderRefusalsForDisplay, refusalIsSelectable, hasRefusalsToShow, qualifyRefusalHeadingFor, newQualifyRefusalGroupState, qualifyRefusalReason, QUALIFY_REFUSAL_UNSPECIFIED, refusalIsTileBound, QUALIFY_TILE_REFUSAL_CODES, QUALIFY_TOO_SMALL_HEADING, type QualifyRefusalRow, type QualifyRefusalGroupState, type QualifyRefusalHeading, } from "./qualifyGroups";
 export { qualifyPick, qualifyAuto, qualifyCancel, launchGenerates, launchFavorStyle, chooserFitsViewport, shouldOpenChooserOnGenerate, shouldOpenInlineChooserOnGenerate, canConfirmLaunch, confirmLaunch, qualifyFailureFallsOpen, CHOOSER_MIN_WIDTH_PX, CHOOSER_MIN_HEIGHT_PX, type QualifyLaunchOutcome, type ChooserGateInput, } from "./qualifyLaunch";
 export { normalizeFilterTerm, filterQualifyRows, readQualifyChartRow, readQualifyRefusalRow, DEFAULT_FILTER_MATCH_STYLE, filterMatchStyleOf, type FilterMatchStyle, filterFitsChooser, listNeedsFilter, qualifyFilterGate, inlineFilterGate, FILTER_MIN_TERM_CHARS, FILTER_ROW_PX, FILTER_MIN_WIDTH_PX, FILTER_MIN_HEIGHT_PX, INLINE_FILTER_MIN_ROWS, computeQualifyFilterView, qualifyFilterCountText, type QualifyFilterTier, type QualifyFilterResult, type QualifyFilterRead, type QualifyFilterGateReason, type QualifyFilterGateInput, type QualifyFilterRow, type QualifyFilterGroup, type QualifyFilterView, type QualifyFilterNoteKind, } from "./qualifyFilter";
 export { qualifyTableRows, type QualifyTableRow, type QualifyTableSource } from "./qualifyTable";

package/dist/types/lasso.d.ts

@@ -0,0 +1,143 @@
+import { type RenderOptions } from "./contract";
+/**
+ * THE MOST ROWS A CHART MAY HAVE IN VIEW AND STILL OFFER A LASSO.
+ *
+ * PROVISIONAL. Unmeasured: 5,000 is a stand-in until the time Power BI Desktop takes to apply a selection
+ * of that many ids is measured on a release-test page (1,000, 5,000 and 13,000 ids), and that number
+ * replaces this one. Do not read it as a finding. It is the worst case that is allowed for, not the
+ * typical one: a reader can lasso everything.
+ *
+ * Above it the WHOLE lasso is off: no surface is installed, and a one-line caption says why. It is one
+ * number for every host; a host may pass its own through RenderOptions.lasso.rowCap.
+ */
+export declare const LASSO_ROW_CAP = 5000;
+/** Travel, in px on either axis, at which a press stops being a click and becomes a lasso. */
+export declare const LASSO_DRAG_PX = 5;
+/** A freeform point is kept only when it is this far from the last one kept. */
+export declare const LASSO_SAMPLE_PX = 3;
+/** A freeform shape longer than this is thinned before it is used, so what is published, stored and
+ *  restored is one and the same shape. */
+export declare const LASSO_MAX_VERTICES = 400;
+/** What a restore will read, per shape and in all: a bag is untrusted, and a poisoned one must not be able
+ *  to ask for unbounded work. */
+export declare const LASSO_RESTORE_MAX_VERTICES = 2000;
+export declare const LASSO_RESTORE_MAX_SHAPES = 32;
+/** The DOM event a chart listens for on its container. detail is a LassoEventDetail. */
+export declare const LASSO_EVENT = "llm-lasso";
+export declare const LASSO_SURFACE_CLASS = "lch-lasso-surface";
+export declare const LASSO_OUTLINE_CLASS = "lch-lasso-outline";
+export declare const LASSO_COUNT_CLASS = "lch-lasso-count";
+export declare const LASSO_NOTE_CLASS = "lch-lasso-note";
+/** The group a chart draws its plot in; the surface goes over it. Without one the chart's svg is the plot. */
+export declare const LASSO_PLOT_CLASS = "lch-plot";
+/** Set on the container to switch to a rectangle ("rect"); anything else is freeform. */
+export declare const LASSO_MODE_ATTR = "data-lch-lasso-mode";
+/** The key in the shared knob bag. */
+export declare const LASSO_KNOB_KEY = "lasso";
+/** A chart registers { toData([x, y]), toScreen([dx, dy]) } here so the shape is stored in data coordinates.
+ *  x and y are in the user space of the element the surface sits in (the plot group). */
+export declare const LASSO_AXES_SLOT = "__lchLassoAxes";
+/** The action list a host runs when none is configured. */
+export declare const LASSO_DEFAULT_ACTIONS: readonly string[];
+/** RenderOptions.lasso. `capable` is the capability the server sent with this chart (absent means not
+ *  capable); `enabled` is the reader's setting (default on); both must hold. */
+export type LassoSetting = NonNullable<RenderOptions["lasso"]>;
+/** "on" installs a surface. The others say why not; only "over-cap" shows a caption. */
+export type LassoVerdict = "on" | "not-capable" | "disabled" | "over-cap";
+/** The row cap in force: the setting's when it is a positive number, else LASSO_ROW_CAP. */
+export declare function lassoRowCap(setting: LassoSetting | null | undefined): number;
+/** The action names to run on release, in order. Anything that is not a list of names is the default. */
+export declare function lassoActions(setting: LassoSetting | null | undefined): string[];
+/** Whether a chart with `rows` rows in view gets a lasso under `setting`. */
+export declare function lassoVerdict(setting: LassoSetting | null | undefined, rows: number): LassoVerdict;
+type Pt = [number, number];
+export type LassoMode = "free" | "rect";
+export type LassoSpace = "data" | "unit";
+/** One drawn shape as stored: a freeform polygon, or the four corners of a rectangle. */
+export interface LassoShape {
+    mode: LassoMode;
+    pts: Pt[];
+}
+/** What the knob bag holds under LASSO_KNOB_KEY. */
+export interface LassoStored {
+    v: 1;
+    space: LassoSpace;
+    shapes: LassoShape[];
+}
+/** detail of the `llm-lasso` DOM event. `polygon` is the last shape drawn, `polygons` every shape in the
+ *  lasso, both in `space` (data coordinates, or fractions of the plot box); `rows` is empty when the lasso
+ *  was cleared. source: "user" a gesture or a clear, "restore" a lasso re-applied on draw, "host" a clear the
+ *  host made because the selection was replaced from outside. */
+export interface LassoEventDetail {
+    rows: number[];
+    polygon: Pt[];
+    polygons: Pt[][];
+    mode: LassoMode;
+    space: LassoSpace;
+    source: "user" | "restore" | "host";
+}
+export interface LassoAxes {
+    toData(p: [number, number]): ArrayLike<unknown>;
+    toScreen(p: [number, number]): ArrayLike<unknown>;
+}
+/** Point in a shape: the bounding box rejects first; a rectangle is then done, and a freeform polygon is
+ *  an even-odd ray cast. Implemented here so the host takes no dependency on a geometry library. */
+export declare function pointInShape(shape: {
+    mode: LassoMode;
+    pts: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+}, x: number, y: number): boolean;
+/** What an action is given on release. */
+export interface LassoActionContext {
+    /** The rows inside the lasso (every shape of it), ascending. */
+    rows: number[];
+    mode: LassoMode;
+    source: "user";
+    env: LassoEnv;
+}
+export type LassoAction = (ctx: LassoActionContext) => void;
+/**
+ * Make `name` available to the action list (RenderOptions.lasso.actions). A name in the list that nothing
+ * registered is skipped, so a host can carry a list ahead of the build that understands it.
+ */
+export declare function registerLassoAction(name: string, action: LassoAction): void;
+/** What the host gives the lasso. The lasso never reaches into the host's selection itself. */
+export interface LassoEnv {
+    container: HTMLElement;
+    /** The options of the render now on screen (a function, because setOptions replaces them). */
+    options: () => RenderOptions;
+    /** How many rows the chart was handed: the number the cap is measured against. */
+    rows: number;
+    /** Publish this row set as the selection (what the "select" action does). */
+    select(rows: number[]): void;
+    /** Clear the host's selection the way an empty click does: the chart's own clear slot first when the
+     *  chart owns the selection, then a published clear. A no-op when nothing is selected. */
+    clearSelection(): void;
+}
+export interface LassoHandle {
+    /** The surface the gesture is read on; null when the lasso is off at this row count. */
+    readonly surface: Element | null;
+    /** The rows inside the lasso now drawn, ascending; empty when none. */
+    rows(): number[];
+    /** Erase the lasso. By default it also clears the host's selection and says so with `llm-lasso`. */
+    clear(opts?: {
+        publish?: boolean;
+        source?: "user" | "host";
+    }): void;
+    /** Remove the listeners and everything the lasso drew. Nothing is persisted. */
+    destroy(): void;
+}
+/**
+ * Put the lasso on the chart in `env.container`, which has just drawn. Returns null when the chart gets none
+ * (not capable, switched off, nothing to draw on); a handle for the caption when the rows exceed the cap;
+ * otherwise the live handle. A lasso already installed on the container is destroyed first.
+ */
+export declare function installLasso(env: LassoEnv): LassoHandle | null;
+/** Erase the lasso on `container`, if it has one, and clear the selection with it. */
+export declare function clearLasso(container: Element | null | undefined, opts?: {
+    publish?: boolean;
+    source?: "user" | "host";
+}): void;
+export {};

package/dist/types/legendFit/frameFit.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Frame fit — pure geometry.
+ *
+ * The third measured sibling of the label-contrast and legend-reconcile passes.
+ * Generated code routinely parks a footer/source caption against the
+ * RAW svg edge — `svg.append('text').attr('y', height - 2)` — instead of reserving
+ * a band for it inside `margin.bottom`. That looks right in the code and is wrong
+ * on screen: a baseline is not an ink box. A glyph descends roughly 0.27 * fontSize
+ * BELOW its baseline, so a 2px gap at font-size 7.5 puts the tails of "g", "p", "y"
+ * exactly on (or past) the frame, and `.lch-d3ctr` is `overflow:hidden` — the host
+ * silently slices them. Measured live on a Marimekko (690x340): the
+ * caption's ink box ran 331->340 in a 340-tall frame, i.e. flush, tails gone.
+ *
+ * Corpus: 41 D3 generations across ~20 chart types park text within 5 user units of
+ * the frame, so this is a RENDERER-level habit, not one chart's bug.
+ *
+ * WHY EXTEND THE VIEWBOX RATHER THAN MOVE THE TEXT: nudging a glyph back inside
+ * can shove it into whatever sits above it — in that Marimekko the axis title's ink
+ * ends 12 units above the caption, so a blind 6-unit lift would collide the two
+ * and trade a clipped line for an overlapping one. Growing the viewBox instead
+ * makes the SVG scale to fit its container: nothing moves relative to anything
+ * else, nothing is clipped, and a 2-unit grow on a 340-unit frame is a 0.6%
+ * rescale nobody can see. This is exactly the remedy the legend-reconcile pass already
+ * uses for a legend that runs off the right edge.
+ *
+ * Coordinates: EVERYTHING here is in the SVG's USER space (== viewBox units). The
+ * caller maps measured client-px boxes through `svg.getScreenCTM().inverse()`
+ * first, which captures viewBox, preserveAspectRatio, container scaling AND host
+ * page zoom in one matrix — so this module needs no px<->unit factor. Same
+ * contract as legendReconcile; the box and viewBox types are shared with it.
+ *
+ * DOM-free so it can be unit-tested on plain numbers; the DOM I/O lives in
+ * frameFitDom.fitTextToFrame.
+ */
+import type { Rect, ViewBox } from "./legendReconcile";
+export type { Rect, ViewBox };
+export interface FrameFitPlan {
+    action: "none" | "extend" | "defer";
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    newViewBox: ViewBox;
+    considered: number;
+    rescued: number;
+    deferred: number;
+    deferredIdx: number[];
+    reason: string;
+}
+export declare const FRAME_PAD = 1;
+export declare const MAX_EXTEND_FRACTION = 0.08;
+/**
+ * Work out how much the viewBox must grow so every measured ink box sits inside
+ * the frame with FRAME_PAD to spare.
+ *
+ * @param boxes  ink boxes in USER space (see module note on the CTM mapping)
+ * @param vb     the SVG's current viewBox in user units
+ * @param maxFraction  per-axis extension ceiling, as a fraction of the frame
+ */
+export declare function planFrameFit(boxes: Rect[], vb: ViewBox, maxFraction?: number): FrameFitPlan;
+/** Serialize a viewBox the way the SVG attribute wants it. */
+export declare function viewBoxAttr(vb: ViewBox): string;
+export type TextAnchor = "start" | "middle" | "end";
+/** The minimum readable type, px. */
+export declare const FIT_TYPE_FLOOR = 10;
+/** A shrink never goes below this fraction of the chart's own size: past it, cut instead. */
+export declare const FIT_SHRINK_FLOOR = 0.8;
+/**
+ * The width, in user units, a label may keep so that its box sits inside `frame` (with
+ * FRAME_PAD), given the edge its anchor holds - or null when no shortening can fit it
+ * (it overflows vertically, or its held edge is itself outside the frame).
+ */
+export declare function labelRoom(box: Rect, frame: ViewBox, anchor: TextAnchor): number | null;
+export interface LabelFitDecision {
+    action: "none" | "shrink" | "cut";
+    fontSize: number;
+}
+/**
+ * Shrink or cut: a label `width` units wide at `fontSize` px that must fit `room` units.
+ * Width scales with the font size, so the first guess is exact to within hinting; the caller
+ * re-measures after a shrink and falls through to the cut if hinting disagreed.
+ */
+export declare function labelFitDecision(width: number, room: number, fontSize: number): LabelFitDecision;
+/**
+ * The widest prefix of `full` (plus the ellipsis) that `fits`, never cut inside a number:
+ * a cut between two digits moves back to before the number ("largest 12..." of
+ * "largest 128 of 400" states a different count). Empty when nothing fits.
+ */
+export declare function cutToFit(full: string, fits: (s: string) => boolean, ell?: string): string;

package/dist/types/legendFit/frameFitDom.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Frame fit - the labels the viewBox could not rescue.
+ *
+ * fitTextToFrame grows the viewBox for text that pokes a few units past the frame and
+ * DEFERS text that is further out, because swallowing it would shrink the whole chart. A
+ * deferred label used to stay exactly where the chart put it, sliced by the frame, and
+ * a log line only counted it: a Bullet of 21 KPIs at 1230x626 reported
+ * `{"rescued":8,"deferred":6,"grew":"left+68.06"}` while six KPI names still read
+ * "...f Service Effort - Reduce effort".
+ *
+ * A label that overflows on the side its anchor does NOT hold is fitted in place: the type
+ * shrinks first (see labelFitDecision - never below the 10px floor or 80% of the chart's size),
+ * then the string is cut to the widest prefix that fits, never inside a number, and the full
+ * text rides a <title>. A label that overflows vertically, or on the side its anchor holds, is
+ * counted as unfixable and left alone. The geometry is in frameFit.ts; this is the DOM I/O,
+ * with the measurement handed in so the caller's CTM mapping (viewBox, zoom) is the only one.
+ */
+import { Rect, ViewBox, FrameFitPlan } from "./frameFit";
+export interface DeferredLabelFitReport {
+    /** Deferred text elements looked at. */
+    deferred: number;
+    /** Fitted by a smaller font size alone. */
+    shrunk: number;
+    /** Fitted by cutting the string (after any shrink). */
+    cut: number;
+    /** Could not be fitted by shortening: vertical overflow, the held edge outside, rotated, tspans. */
+    unfixable: number;
+    /** The first few full labels that were fitted, for the log line. */
+    labels: string[];
+}
+/**
+ * Fit ONE label, `width` wide, into `room` (both in whatever units `widthNow` measures): shrink the
+ * type first (labelFitDecision - never below the 10px floor or 80% of the label's size), then cut
+ * the string to the widest prefix that fits, never inside a number, with the full text riding a
+ * <title>. `minChars` keeps at least that many characters before the ellipsis even when they do not
+ * fit - a caller that must never REMOVE a label (the nominal axis) passes 1. Shared by the
+ * frame fit and the nominal-axis cut.
+ */
+export declare function fitLabelToRoom(el: Element, width: number, room: number, widthNow: () => number, minChars?: number): "none" | "shrunk" | "cut";
+/**
+ * Fit each deferred label to `frame`. `measure` returns the element's box in the SAME user
+ * space as `frame` (null when it cannot). Never throws; a label it cannot judge is unfixable.
+ */
+export declare function fitDeferredLabels(els: Element[], frame: ViewBox, measure: (el: Element) => Rect | null): DeferredLabelFitReport;
+/** Perf ceiling: every text costs a getBoundingClientRect, and a Tabular can paint thousands of
+ *  cells; above this the sweep costs more than the defect it fixes (and such charts scroll their
+ *  own body anyway, so their overflow is intentional). */
+export declare const FRAME_FIT_TEXT_CAP = 600;
+export interface FrameFitOutcome {
+    /** Set when the pass declined: too many texts to measure. */
+    skipped?: {
+        texts: number;
+        cap: number;
+    };
+    /** The viewBox plan (planFrameFit). */
+    plan?: FrameFitPlan;
+    /** What happened to the labels the plan deferred, when there were any. */
+    labels?: DeferredLabelFitReport;
+}
+/**
+ * THE WHOLE PASS, host-free: grow the viewBox for text a few units past the frame (planFrameFit),
+ * then fit the labels it deferred (fitDeferredLabels). Null when there is nothing to measure (no
+ * svg, no text, no CTM, an unreadable viewBox). A host adds its own logging around this call; it
+ * is kept DOM-only so a headless replay can run exactly what a host runs.
+ */
+export declare function fitTextToFrame(host: HTMLElement): FrameFitOutcome | null;
+/** True when the element sits under a clip-path/mask, inside <defs>, or inside a scrollable
+ *  subtree - all cases where being outside the frame is the chart's intent rather than a
+ *  text-metric miss. */
+export declare function isClippedOrScrolled(el: Element, stopAt: Element): boolean;

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

@@ -0,0 +1,4 @@
+export { MIN_OVERLAP, MAX_GUTTER_FRACTION, COLORBAR_ON_PLOT_COVER, MAX_FIT_FRACTION, FIT_PAD, LEGIBILITY_GRACE_PX, MIN_LEGIBLE_PX, BOTTOM_TEXT_MIN_TICK_HITS, SWATCH_MAX_PX, SWATCH_LABEL_GAP_PX, SIGNATURE_MIN_PAIRS, AXIS_THIN_MIN_TICKS, AXIS_THIN_GAP, LABEL_ROW_MIN_TEXTS, LABEL_ROW_Y_TOLERANCE, LABEL_ROW_TRACK_COVER, LABEL_ROW_TRACK_REACH, rightmostOverlappingPlotEdge, bottommostOverlappingPlotEdge, planLegendReconcile, colorbarProbePoints, colorbarOnPlot, colorbarSitsOnMarks, colorbarReconcileSide, planContentFit, planBottomTextPush, swatchPairs, isLegendSignature, planAxisTickThin, isNumericLabelText, isDateLikeLabelText, isOrderedAxisLabelText, axisLabelsAreNominal, nominalLabelRooms, groupLabelRows, labelRowHasTrack, type Rect, type ViewBox, type ReconcileSide, type ReconcilePlan, type ReconcileOptions, type ContentFitPlan, type ContentFitOptions, type SwatchPairs, type AxisThinPlan, } from "./legendReconcile";
+export { FRAME_PAD, MAX_EXTEND_FRACTION, FIT_TYPE_FLOOR, FIT_SHRINK_FLOOR, planFrameFit, viewBoxAttr, labelRoom, labelFitDecision, cutToFit, type FrameFitPlan, type TextAnchor, type LabelFitDecision, } from "./frameFit";
+export { reconcileLegendInSvg, findSignatureLegendGroups, findColorbarFurniture, smallestRenderedTextPx, styleDeclaresScroll, type LegendReconcileResult, type AxisThinReport, } from "./legendReconcileDom";
+export { FRAME_FIT_TEXT_CAP, fitTextToFrame, fitDeferredLabels, fitLabelToRoom, isClippedOrScrolled, type FrameFitOutcome, type DeferredLabelFitReport, } from "./frameFitDom";