@50arms/ui 0.0.0-stage → 35.1.0

package/dist/types/lib/calendar/segments.d.ts

@@ -0,0 +1,91 @@
+import { isoDateString, type Instant, type PlainDate, type TimeZone } from "@/lib/time";
+import type { AllDayEvent, CalendarEvent, TimedEvent } from "./types";
+/** One day's worth of a timed event, positioned within that day's column. */
+export interface TimeSegment {
+    readonly event: TimedEvent;
+    readonly day: PlainDate;
+    /** Index into the range's `days`, so a view can address a column directly. */
+    readonly dayIndex: number;
+    /** Fraction down the column, 0 at the day's first instant, 1 at the next day's. */
+    readonly top: number;
+    readonly bottom: number;
+    /** False when the event began before this day — draw the top edge as cut. */
+    readonly isStart: boolean;
+    /** False when the event continues past this day. */
+    readonly isEnd: boolean;
+}
+/** A run of whole days, for the month grid or the all-day band. */
+export interface BandSegment {
+    readonly event: CalendarEvent;
+    /** Inclusive column index within the row. */
+    readonly startColumn: number;
+    readonly endColumn: number;
+    readonly isStart: boolean;
+    readonly isEnd: boolean;
+}
+/**
+ * Cut a timed event into one segment per day it touches.
+ *
+ * `days` is a contiguous run — a week, or a single day. Days the event does not
+ * touch produce nothing.
+ */
+export declare function timeSegments(zone: TimeZone, days: readonly PlainDate[], event: TimedEvent): TimeSegment[];
+/**
+ * Where an all-day event sits within a row of days.
+ *
+ * `null` when it does not reach this row at all. Both `endColumn` and the
+ * event's own end are handled here so no caller ever does the ±1: the model is
+ * half-open (`endExclusive` is the first day NOT in the event) and a column
+ * index is inclusive, so the conversion happens once, here.
+ */
+export declare function allDayBandSegment(rowDays: readonly PlainDate[], event: AllDayEvent): BandSegment | null;
+/**
+ * Where a TIMED event sits within a row of days, as whole columns.
+ *
+ * The month grid draws timed events as chips in a day cell, so a timed event
+ * that crosses midnight occupies both cells and needs the same clipping
+ * booleans an all-day bar does.
+ */
+export declare function timedBandSegment(zone: TimeZone, rowDays: readonly PlainDate[], event: TimedEvent): BandSegment | null;
+/** One horizontal rail in the time grid, and the wall time it is labelled by. */
+export interface DaySlot {
+    readonly instant: Instant;
+    /** Position down the column, 0–1. */
+    readonly fraction: number;
+    /** 0–23. On a fall-back day one value appears TWICE — see below. */
+    readonly hour: number;
+    readonly minute: number;
+    /** True for the second of a repeated reading, so a view can mark it. */
+    readonly repeated: boolean;
+}
+/**
+ * The rails for one day, generated by WALKING WALL-CLOCK TIME through the zone.
+ *
+ * NOT by dividing the column into 24. That is the difference between a
+ * fall-back day showing **25 rails with 1 AM twice** — which is what the clock
+ * on the wall actually did — and showing 24 evenly spaced labels that are each
+ * an hour wrong after 02:00.
+ *
+ * Walking forward by real elapsed time and reading the clock at each step is
+ * also what makes the 30-minute zone fall out for free: Lord Howe's short day
+ * produces 23 hourly rails and a half-hour remainder, with no branch.
+ */
+export declare function daySlots(zone: TimeZone, day: PlainDate, slotMinutes?: number): DaySlot[];
+/**
+ * The instant a pointer at `fraction` down `day`'s column is over, snapped.
+ *
+ * SNAP IS A HIT-CHANGE, NOT COORDINATE ROUNDING, and the difference is what the
+ * gesture feels like. Resolving which slot the pointer is IN and only reacting
+ * when that slot changes makes the preview jump discretely between positions,
+ * and **that discreteness IS the feedback** — a preview that tracks the pointer
+ * continuously and rounds on drop reads as mushy and imprecise.
+ *
+ * `snapMinutes` is deliberately independent of the rail spacing. FullCalendar,
+ * react-big-calendar and Schedule-X all couple them; Google and Mobiscroll do
+ * not, and **Google is 15-minute snap on 60-minute rails**, which is the
+ * combination that feels right. Retrofitting the split is a rewrite, so the two
+ * are separate values from the first commit.
+ */
+export declare function snapFractionToInstant(zone: TimeZone, day: PlainDate, fraction: number, snapMinutes: number): Instant;
+/** Stable key for a day, for maps and React keys. */
+export declare const dayKey: typeof isoDateString;

package/dist/types/lib/calendar/types.d.ts

@@ -0,0 +1,166 @@
+import type { CalendarDuration, Instant, PlainDate, TimeZone } from "@/lib/time/types";
+export type CalendarEventId = string;
+interface EventCommon {
+    readonly id: CalendarEventId;
+    readonly title: string;
+    /**
+     * Which series this occurrence belongs to, if any.
+     *
+     * PRESENT FROM THE FIRST COMMIT ALTHOUGH RECURRENCE SHIPS LATER, because
+     * this is the half that cannot be added afterwards. The moment any real data
+     * exists, backfilling series identity onto rows that never had it is a
+     * migration nobody can write correctly — there is no way to tell, later,
+     * which of two identical Tuesday stand-ups belonged to which series.
+     */
+    readonly seriesId?: string;
+    /**
+     * A short human label for the calendar this event came from, rendered ON the
+     * chip.
+     *
+     * NOT decoration, and not satisfied by a legend. Colour-coding is only
+     * conforming when the information it carries is also available another way,
+     * and the remedy has to sit on the coded item itself — a key elsewhere on the
+     * page requires the reader to hold a colour in their head and go looking.
+     */
+    readonly calendarLabel?: string;
+    /** A key into the calendar's palette. Never a raw colour — see `EventPalette`. */
+    readonly paletteKey?: string;
+    /**
+     * Whether this event may be dragged, resized, or otherwise moved.
+     *
+     * Defaults to editable at the calendar level, not here: an undefined value
+     * means "ask the calendar", and only an explicit `false` pins one event down
+     * while its neighbours stay live.
+     */
+    readonly editable?: boolean;
+    /** Anything the consumer wants back in a render prop or an event handler. */
+    readonly data?: unknown;
+}
+/**
+ * An event with a time of day, anchored to a real instant.
+ *
+ * Both ends are `Instant`s, so the event means the same moment regardless of
+ * which zone renders it. A meeting at 09:00 in New York is at 14:00 in London
+ * and both are the same event; storing wall-clock fields instead makes it two
+ * different events that happen to be spelled alike.
+ */
+export interface TimedEvent extends EventCommon {
+    readonly allDay: false;
+    readonly start: Instant;
+    /**
+     * The first instant NOT in the event. Half-open: `start <= t < endExclusive`.
+     *
+     * THE NAME IS THE DOCUMENTATION, deliberately. Half-open intervals make
+     * `duration = end - start` correct, make adjacent events provably
+     * non-overlapping, and make every algorithm in the layout core fall out
+     * without a `+1` anywhere — overlap is `aStart < bEnd && bStart < aEnd`, with
+     * no special case for two events that merely touch.
+     *
+     * The cost is the most-reported bug in calendar interoperability: a
+     * one-day event stored as 23rd → 24th renders as two days in any consumer
+     * that reads the end as inclusive. So the ±1 conversion happens in exactly
+     * TWO places — the display formatter and the date-picker binding — and the
+     * field is named so that nobody has to remember which convention this is.
+     */
+    readonly endExclusive: Instant;
+    /**
+     * The start this occurrence had when the series first produced it.
+     *
+     * THE PERMANENT JOIN KEY FOR AN OVERRIDE, and the single most common
+     * recurrence-model mistake is keying by the CURRENT start instead. Do that
+     * and the override becomes unjoinable the moment somebody drags the event:
+     * the series still generates an occurrence at the original time, the
+     * override now claims a different one, and the calendar shows both.
+     *
+     * Set once, never updated. Absent on an event that is not part of a series.
+     */
+    readonly originalStart?: Instant;
+}
+/**
+ * An event that occupies whole days.
+ *
+ * IT CARRIES NO ZONE, AND THAT IS THE POINT. A birthday is on the 4th of March
+ * everywhere; model it as an instant and it moves to the 3rd for anyone far
+ * enough west. `PlainDate` has no offset to be wrong about.
+ */
+export interface AllDayEvent extends EventCommon {
+    readonly allDay: true;
+    readonly start: PlainDate;
+    /** The first day NOT in the event — same half-open rule as `TimedEvent`. */
+    readonly endExclusive: PlainDate;
+    /** See `TimedEvent.originalStart`. A date, because an all-day event has no time. */
+    readonly originalStart?: PlainDate;
+}
+export type CalendarEvent = TimedEvent | AllDayEvent;
+/** Narrowing helper, so consumers never test `allDay` by hand. */
+export declare function isAllDay(event: CalendarEvent): event is AllDayEvent;
+/** Which part of an event a gesture is moving. */
+export type DragKind = "move" | "resize-start" | "resize-end" | "create";
+/**
+ * A gesture in progress, as a DELTA against the committed event.
+ *
+ * NEVER A REWRITTEN COPY OF THE EVENT, and never a reference to one. Two real
+ * failures from other calendars' trackers, both of which this shape makes
+ * impossible:
+ *
+ *   A re-render replaces the event store mid-drag, and the drag is left holding
+ *   an instance from the store that no longer exists — so the drop writes stale
+ *   values over fresh ones.
+ *
+ *   A concurrent update arrives from a server during a drag and the times end
+ *   up DUPLICATED, because a snapshot taken at pointer-down was composited on
+ *   top of data that had moved underneath it.
+ *
+ * A delta keyed by id composes instead of clobbering: whatever the event says
+ * at the moment of the drop, the gesture's meaning is "two hours later than
+ * that", and a change arriving underneath is respected rather than overwritten.
+ *
+ * `delta` IS A CALENDAR DURATION, not a number of milliseconds — see
+ * `CalendarDuration`. Dragging across a spring-forward boundary must preserve
+ * the wall-clock time, and a millisecond delta cannot express that.
+ */
+export interface EventDraft {
+    readonly id: CalendarEventId;
+    readonly kind: DragKind;
+    readonly delta: CalendarDuration;
+}
+/**
+ * One swatch, with its text colour ALREADY PAIRED and verified.
+ *
+ * WHY NOT COMPUTE THE TEXT COLOUR. The familiar trick — measure the fill's
+ * luminance and flip to black or white — fails in a band in the middle where
+ * NEITHER clears AA against the fill. The threshold is also not 0.5: it is
+ * around 0.38, and implementations that use 0.5 pick white on colours that
+ * needed black. Google ships two entire palettes ("white text" and "black
+ * text") rather than compute a flip, which is the same conclusion arrived at
+ * from the other direction.
+ *
+ * So the palette is curated, each pair is measured, and a consumer supplying
+ * arbitrary hex gets a documented refusal rather than an unreadable chip.
+ */
+/** The eight swatch keys. Each one's spoken name is a built-in string (`calendar.colors`), so colour is never the only cue. */
+export type PaletteKey = "iris" | "aqua" | "mint" | "amber" | "rose" | "azure" | "orchid" | "slate";
+export interface PaletteEntry {
+    readonly key: PaletteKey;
+    readonly fill: string;
+    readonly text: string;
+    /** Border and left-edge accent; darker than `fill`, still AA against it. */
+    readonly edge: string;
+}
+export type EventPalette = readonly PaletteEntry[];
+export type CalendarView = "day" | "week" | "month";
+/**
+ * The days a view is currently showing, and the zone it is showing them in.
+ *
+ * `days` is EXPLICIT rather than a start/end pair, because a month grid's days
+ * are not a contiguous range in any useful sense — they cross two month
+ * boundaries and the layout core needs to address them positionally.
+ */
+export interface VisibleRange {
+    readonly view: CalendarView;
+    readonly zone: TimeZone;
+    readonly days: readonly PlainDate[];
+    /** 0 = Sunday. Carried on the range so the packers never have to guess. */
+    readonly weekStartsOn: number;
+}
+export {};

package/dist/types/lib/chart-palette.d.ts

@@ -0,0 +1,14 @@
+/** How many categorical hues exist. A 9th series is never a 9th hue: it folds into "Other". */
+export declare const CHART_SERIES_COUNT = 8;
+/** The eight categorical tokens, in the fixed order series are assigned. */
+export declare const CHART_SERIES_TOKENS: readonly ["--chart-1", "--chart-2", "--chart-3", "--chart-4", "--chart-5", "--chart-6", "--chart-7", "--chart-8"];
+/** The one sequential hue: a single series of magnitudes (a ranked bar list). */
+export declare const CHART_SEQUENTIAL_TOKEN: "--chart-seq";
+/**
+ * The CSS colour for the series at zero-based `index` — `var(--chart-1)` for
+ * index 0. Throws past the eighth: a ninth series is folded into "Other" by
+ * the caller, never given a generated hue.
+ */
+export declare function chartSeriesColor(index: number): string;
+/** The CSS colour of the sequential hue. */
+export declare const CHART_SEQUENTIAL_COLOR: string;

package/dist/types/lib/clipboard.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copy `text` to the OS clipboard.
+ *
+ * Tries `navigator.clipboard.writeText` first. If that API is unavailable or
+ * rejects (e.g. permission denied, as in the Claude Code desktop in-app
+ * browser — DX-3661), falls back to selecting a hidden `<textarea>` and
+ * running `document.execCommand('copy')`, restoring the document's prior
+ * selection and focused element afterward.
+ *
+ * Rejects only when both the async API and the fallback fail.
+ */
+export declare function copyText(text: string): Promise<void>;

package/dist/types/lib/cn.d.ts

@@ -0,0 +1,7 @@
+import { type ClassValue } from "clsx";
+/**
+ * Merge conditional class names, resolving Tailwind conflicts last-wins.
+ * Every component funnels its class composition through this so a consumer's
+ * `className` always beats the component's own defaults.
+ */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/types/lib/color.d.ts

@@ -0,0 +1,14 @@
+export interface Hsv {
+    /** Hue in degrees, `[0, 360)` from `hexToHsv`. `hsvToHex` also accepts 360, the same colour as 0. */
+    h: number;
+    /** Saturation, `0..1`. */
+    s: number;
+    /** Brightness (value), `0..1`. */
+    v: number;
+}
+/** True for exactly `#rrggbb` (either case); shorthand `#rgb` and alpha forms are not accepted. */
+export declare function isHexColor(value: string): boolean;
+/** `#rrggbb` to HSV. Throws on anything else: a stored colour that is not a hex is a caller bug, never defaulted. */
+export declare function hexToHsv(hex: string): Hsv;
+/** HSV to lowercase `#rrggbb`. Components outside range are clamped (hue wraps). */
+export declare function hsvToHex({ h, s, v }: Hsv): string;

package/dist/types/lib/component-guidance.d.ts

@@ -0,0 +1,15 @@
+export interface ComponentGuidanceRule {
+    /** Stable id — used only for messages/tooling, never matched against. */
+    id: string;
+    /** Tested against a whole file's source text. Deliberately case-sensitive
+     *  (see `raw-*` rules below) — a lowercase native tag is the violation; the
+     *  identically-spelled PascalCase `@50arms/ui` export is not. */
+    pattern: RegExp;
+    /** The component(s) that usually fit better than the matched shape. */
+    preferInstead: readonly string[];
+    /** Why the richer alternative usually fits — surfaced in a consumer's
+     *  violation message, and what a `UI-LIBRARY-ALLOW: <reason>` comment is
+     *  answering when the richer one genuinely does not apply here. */
+    reason: string;
+}
+export declare const COMPONENT_GUIDANCE: readonly ComponentGuidanceRule[];

package/dist/types/lib/confidence.d.ts

@@ -0,0 +1,28 @@
+/** One of the five steps of the confidence scale — see `ConfidenceBar` for how each is drawn. */
+export type ConfidenceLevel = 1 | 2 | 3 | 4 | 5;
+/**
+ * A RATING to one of the five confidence steps, or null when there is no
+ * rating on a real scale to draw.
+ *
+ * A five-point rating maps one-to-one. Any other scale is mapped by its
+ * fraction, so a colour and a length keep one meaning whatever scale a consumer
+ * rates on. A rating below one step is "not rated", never level 1: a zero is
+ * the absence of a rating, and drawing it as the lowest earned level would
+ * claim a judgement nobody made.
+ *
+ * The fraction feeds a COLOUR and a LENGTH, never a printed figure — a step is
+ * a judgement five values wide and survives the trip; a percentage is a figure
+ * and does not.
+ */
+export declare function confidenceLevel(rating: number, scale: number): ConfidenceLevel | null;
+/**
+ * Each level's own word, the operator's scale (SG-843): 4 is "Confident" and 5
+ * is "Highly confident", so the two readings of "fine" stay distinguishable in
+ * words exactly as they are in colour and length.
+ *
+ * These are the ENGLISH words for a non-React consumer that cannot read the
+ * provider (the demand letter's Vue overlay bundles them, SG-901). Components
+ * read `confidenceBar.levels` from the provider, whose English set is this very
+ * object, so there is one place the English lives.
+ */
+export declare const CONFIDENCE_LEVEL_LABELS: Readonly<Record<ConfidenceLevel, string>>;

package/dist/types/lib/date-timeline/scale.d.ts

@@ -0,0 +1,143 @@
+/** The unit one axis tick spans; it follows the scale (`tickUnitFor`), nobody picks it. */
+export type DateTimelineUnit = "days" | "weeks" | "months" | "quarters";
+/** The scale limits, in horizontal pixels per calendar day (DXUI-61): a year is 365px at the least and 43,800px at the most. */
+export declare const MIN_PX_PER_DAY = 1;
+export declare const MAX_PX_PER_DAY = 120;
+/** The scale a timeline opens at and Ctrl + 0 returns to: about 365px a month. */
+export declare const DEFAULT_PX_PER_DAY = 12;
+/** The tick unit the axis uses at this scale. */
+export declare function tickUnitFor(pxPerDay: number): DateTimelineUnit;
+/** A scale outside the limits, or not a number, is a caller's bug and throws. */
+export declare function assertPxPerDay(pxPerDay: number): void;
+/** `pxPerDay` held inside the limits. */
+export declare function clampPxPerDay(pxPerDay: number): number;
+/** `pxPerDay` times `factor`, held inside the limits. */
+export declare function scalePxPerDay(pxPerDay: number, factor: number): number;
+/** The slider runs 0..100 along the log of the scale, so each step is the same percentage of zoom. */
+export declare const ZOOM_SLIDER_MAX = 100;
+export declare function pxPerDayToSlider(pxPerDay: number): number;
+export declare function sliderToPxPerDay(value: number): number;
+/** The scale after a mouse-wheel (or pinch) movement of `deltaY` px (`deltaMode`: 0 pixels, 1 lines, 2 pages): a 100px notch is about 22%. Scrolling up zooms in. */
+export declare function wheelZoomFactor(deltaY: number, deltaMode: number): number;
+/** One press of Ctrl + plus (or minus, its inverse). */
+export declare const KEY_ZOOM_FACTOR = 1.25;
+/** The `scrollLeft` that keeps `day` at `viewportX` (px from the scroller's left edge, label column included). Never negative. */
+export declare function scrollLeftForAnchor(day: number, rangeStartDay: number, pxPerDay: number, labelWidth: number, viewportX: number): number;
+/** The day number under `viewportX` (px from the scroller's left edge) at this scroll position. */
+export declare function dayAtViewportX(viewportX: number, scrollLeft: number, rangeStartDay: number, pxPerDay: number, labelWidth: number): number;
+export interface DateTimelineSpan {
+    start: Date;
+    end: Date;
+    /** A second end instant drawn as its own marker (DXUI-60); the axis extends to hold it. */
+    plannedEnd?: Date;
+}
+export interface DayRange {
+    /** First day number of the axis: a unit start. */
+    startDay: number;
+    /** Day number the axis ends at (exclusive): a unit start. */
+    endDay: number;
+}
+export interface Tick {
+    /** Day number of the unit's first day. */
+    startDay: number;
+    /** Day number of the next unit's first day. */
+    endDay: number;
+    /** Left edge in px from the axis start. */
+    x: number;
+    width: number;
+}
+/** Local calendar day number of `date`, with the elapsed fraction of the local day. */
+export declare function toDayNumber(date: Date): number;
+/** The local midnight Date that opens the day with this number. */
+export declare function fromDayNumber(day: number): Date;
+/** The first day of the unit holding `day`. `weekStartsOn`: 0 = Sunday ... 6 = Saturday. */
+export declare function unitStart(day: number, unit: DateTimelineUnit, weekStartsOn: number): number;
+/** The first day of the unit after the one that starts at `start`. */
+export declare function nextUnitStart(start: number, unit: DateTimelineUnit): number;
+/** Calendar quarter (1-4) of the day. */
+export declare function quarterOf(day: number): number;
+export declare function yearOf(day: number): number;
+/**
+ * The axis range for these items and today: from the earliest start or today to the latest end or today, widened to
+ * whole units with `AIR_UNITS` of air around, so every bar and the today line sit inside it.
+ * A bar is drawn at its true length (DXUI-60), so only the dates decide the range; a `plannedEnd` counts like an end.
+ * An item that ends before it starts is a caller's bug and throws.
+ */
+export declare function timelineRange(spans: readonly DateTimelineSpan[], today: Date, unit: DateTimelineUnit, weekStartsOn: number, markerDates?: readonly Date[]): DayRange;
+/** Pixel x of a day number on an axis that starts at `rangeStartDay`. */
+export declare function dayToX(day: number, rangeStartDay: number, pxPerDay: number): number;
+/** The axis width in px. */
+export declare function trackWidth(range: DayRange, pxPerDay: number): number;
+/** One tick per unit across the range, each with its pixel box. */
+export declare function unitTicks(range: DayRange, unit: DateTimelineUnit, pxPerDay: number): Tick[];
+/** Pixel x of an instant on an axis that starts at `rangeStartDay`. */
+export declare function instantToX(date: Date, rangeStartDay: number, pxPerDay: number): number;
+/** Where an item's bar sits: from the x of its start to the x of its end, its true length at any scale. */
+export declare function barBox(span: DateTimelineSpan, range: DayRange, pxPerDay: number): {
+    left: number;
+    width: number;
+};
+/** `date` moved `days` whole calendar days, keeping its time of day (a daylight-saving day is still one day). */
+export declare function addDays(date: Date, days: number): Date;
+/** What a drag or key press changes: the whole bar, only its end, or only its start. */
+export type DateTimelineEdit = "move" | "end" | "start";
+/**
+ * The span after `days` whole days of `edit` (DXUI-60): "move" shifts both ends; "end" and "start" shift one and
+ * stop at the other end, so a bar never inverts. Returns the original dates unchanged for 0 days.
+ */
+export declare function editSpan(span: {
+    start: Date;
+    end: Date;
+}, edit: DateTimelineEdit, days: number): {
+    start: Date;
+    end: Date;
+};
+/**
+ * `days` limited so a marker moved by it (DXUI-67) stays on the axis: the axis is built from the markers' own dates, so a drag
+ * must not carry one past its ends. Whole days in, whole days out.
+ */
+export declare function clampMarkerDays(date: Date, days: number, range: DayRange): number;
+/** The `scrollLeft` that puts x (a px offset on the axis) in the middle of the date area: `viewportWidth` wide, less the sticky label column. Never negative. */
+export declare function scrollLeftToCenter(x: number, viewportWidth: number, labelWidth: number): number;
+/** A progress value clamped to 0..1; NaN is a caller's bug and throws. */
+export declare function clampProgress(progress: number): number;
+/** Throws on a marker with an invalid date or an id another marker already uses. */
+export declare function assertMarkers(markers: readonly {
+    id: string;
+    date: Date;
+}[]): void;
+export interface MarkerTagPlacement {
+    /** Index of the marker in the input. */
+    index: number;
+    /** Left edge of the tag in the track, px: centred on the line, then clamped inside [0, trackWidth - width]. */
+    left: number;
+    /** Row, 0 = the one nearest the dates; a tag overlapping (or within `gap` of) an earlier one on a row moves to the next. */
+    row: number;
+}
+/**
+ * Places each marker's header tag (DXUI-64). A tag is centred on its line, clamped so it never leaves the track (the line
+ * stays on its date), and stacked in rows so two tags never overlap or touch closer than `gap`.
+ */
+export declare function layoutMarkerTags(tags: readonly {
+    x: number;
+    width: number;
+}[], trackWidth: number, gap: number): MarkerTagPlacement[];
+/** The tag row's top, in px relative to the date header: row 0 sits directly above the dates and each further row one `rowPx` higher. */
+export declare function markerTagTop(row: number, rowPx: number): number;
+export interface MarkerFlagPlacement {
+    /** Index of the marker in the input. */
+    index: number;
+    /** Lane, 0 = the one nearest the top of the band. */
+    lane: number;
+    /** The flag's width, cut short when the next flag in its lane would otherwise run into it; never below `minWidth`. */
+    maxWidth: number;
+}
+/**
+ * Places each marker's flag in the Phases band above the date header (DXUI-68). Flags go left to right: each takes the first lane
+ * whose last flag has ended `gap` px before it, else the lane that frees up soonest. A flag that runs into the next one in its lane
+ * is cut short to the room before that one, so no flag is ever drawn over another.
+ */
+export declare function layoutMarkerFlags(flags: readonly {
+    x: number;
+    width: number;
+}[], lanes: number, gap: number, minWidth: number): MarkerFlagPlacement[];

package/dist/types/lib/design-frame/document.d.ts

@@ -0,0 +1,39 @@
+import { type DesignFrameAppearance } from "./protocol";
+/**
+ * Turns an untrusted single-file HTML document into the one string a
+ * `SandboxedFrame` hands the browser as `srcdoc` (DX-4075).
+ */
+/**
+ * What the framed document may do: run its own inline script and style, and show
+ * data:/blob: media. It may not fetch, submit, set a base, or load anything by URL.
+ */
+export declare const DESIGN_FRAME_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; media-src data: blob:; connect-src 'none'; form-action 'none'; base-uri 'none'";
+/**
+ * DX-4693: the framed document declares the colour-scheme of the theme it mirrors. The host
+ * `<iframe>` element takes its colour-scheme from the host page; a framed document that declares
+ * none is `normal` (light), and under that mismatch Chromium paints an opaque backdrop that can
+ * hide the design entirely (reproduced in Electron's Chromium and real Chrome). The declaration is
+ * keyed on the `data-theme` attribute, so the frame follows a live flip: the injected mini-app script
+ * writes that attribute with every appearance the host posts.
+ */
+export declare const DESIGN_FRAME_COLOR_SCHEME_CSS: string;
+/**
+ * The policy is inserted by PARSING, never by string or regex surgery: text
+ * placed after the first literal `<head>` is defeated by a decoy earlier in the
+ * document (`<!-- <head> -->`, or the word in a script string), which would leave
+ * the REAL head with no policy. The HTML parser always synthesises a head, so
+ * `prepend` has somewhere to put it; whether the author wrote an explicit
+ * `<head>` is not decidable here.
+ *
+ * THE RESULT IS SELF-VERIFIED: the serialised document is parsed once more and
+ * this throws unless the first element of its head is the policy, exactly. A
+ * document is never rendered unprotected.
+ *
+ * `docId` is the id the injected script puts on every height message, so the host can drop a report from a
+ * document it has since replaced (DXUI-6).
+ *
+ * The host's `appearance` is stamped on the framed `<html>` here, so the frame
+ * paints in the right theme from its first frame, with the matching color-scheme
+ * declared right behind the policy (DX-4693).
+ */
+export declare function prepareDesignDocument(html: unknown, appearance: DesignFrameAppearance, docId: string): string;

package/dist/types/lib/design-frame/mini-app-script.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DXUI-6: the script `prepareDesignDocument` injects into every framed page, which defines
+ * `window.danxMiniApp`. The page installs nothing, so a repo on any version of this library, or on
+ * another framework, gets the theme, ready, error reporting and height with no client code.
+ *
+ * It is a STRING, not a function serialised with `toString()`: a bundler or minifier may rewrite a
+ * function's body (renamed helpers, hoisted imports), and this code must run alone in a document
+ * that has none of the library. It is plain ES5 and dependency-free for the same reason, and the
+ * protocol names and domains are interpolated from the host's own constants so the two sides
+ * cannot drift. Nothing in it may contain a closing script tag or a comment opener, which would end
+ * the element it is serialised into (pinned by `design-frame-mini-app.test.ts`).
+ *
+ * THE APPEARANCE WRITE MIRRORS `applyPreference` (`preference-values.ts`), including the forced
+ * style read inside the `data-motion-suspend` window: without it a theme flip dissolves every
+ * transition in the page instead of cutting. A value the frame already shows writes nothing (DX-5526).
+ *
+ * EVERY HEIGHT MESSAGE ALSO CARRIES `doc`, the id the host generated for this document. Setting `srcdoc` only starts
+ * a navigation: the old document stays live, and shares its window object with the new one, until the new one
+ * commits, so the host tells their reports apart by this id.
+ *
+ * EVERY HEIGHT MESSAGE CARRIES THE FRAME'S OWN VIEWPORT HEIGHT (`window.innerHeight`), and a viewport change alone is
+ * reported (the `resize` event), so the host can tell a page whose height changed by itself from one whose height
+ * only moved because the host resized the frame.
+ *
+ * THE HEIGHT IS THE `<html>` ELEMENT'S, not `scrollHeight`: `scrollHeight` is never below the
+ * viewport, so a page could never shrink. A page whose root is `100vh` has an `<html>` as tall as the
+ * frame, reports the frame's own height, and the host leaves it there.
+ */
+export declare function danxMiniAppScript(docId: string): string;

package/dist/types/lib/design-frame/mini-app.d.ts

@@ -0,0 +1,17 @@
+import type { DesignFrameAppearance } from "./protocol";
+/**
+ * DXUI-6: the interface of `window.danxMiniApp`, which `SandboxedFrame` injects into every framed
+ * page (`mini-app-script.ts`). A mini app declares it once to call it type-safely; the docs
+ * (`content/docs/sandboxed-frame.mdx`) give a declaration to copy. React-free: the interface plus `DANX_MINI_APP_METHODS`.
+ */
+export interface DanxMiniApp {
+    /** Call in the page's first script to delay `ready` past `load` until `ready()` is called. */
+    holdReady(): void;
+    /** Tells the host the page has mounted. Posted once; later calls do nothing. */
+    ready(): void;
+    /** Shows a failure in the host as text, capped at 500 characters. */
+    reportError(message: string): void;
+    /** Calls `callback` with what the host just sent, after it is applied; returns the unsubscribe. */
+    onAppearance(callback: (appearance: DesignFrameAppearance) => void): () => void;
+}
+export declare const DANX_MINI_APP_METHODS: readonly (keyof DanxMiniApp)[];