@bitvea/feedback-toolbar 0.0.1

package/dist/tokens.d.ts

@@ -0,0 +1,709 @@
+import type { FeedbackStatus } from "./vendor/types/index.js";
+/**
+ * The BitVea brand orange, as the logo draws it.
+ *
+ * It used to be the toolbar's whole action system: every primary button, the
+ * active bar tool, the count bubble, the avatars, the status chip and the
+ * checkbox were orange. That put the accent on metadata and on chrome, which
+ * is the one thing DESIGN.md's colour section forbids - ink carries the CTA,
+ * and colour is reserved. So the accent is now IDENTITY ONLY: it survives on
+ * the pin teardrop, which has to be findable over arbitrary host content and
+ * is the one object in the product that means "BitVea Feedback is here".
+ */
+export declare const accent: {
+    readonly start: "#DF6520";
+    readonly end: "#F97316";
+    /** 135deg, the direction the mark's own gradient runs. */
+    readonly gradient: "linear-gradient(135deg, #DF6520 0%, #F97316 100%)";
+    readonly onAccent: "#ffffff";
+};
+/** A status chip's ground and the ink on it, one pair per lane. */
+export interface ToolbarStatusStyle {
+    background: string;
+    color: string;
+}
+/**
+ * The status vocabulary, mirrored from the dashboard's semantic pairs so one
+ * product fact reads the same on both surfaces. Built from DESIGN.md's
+ * soft-ground / deep-ink pairs rather than from bare dot colours, because a
+ * bare colour has to be re-chosen for the dark polarity flip and a pair does
+ * not: the ground moves with the theme and carries its ink with it.
+ */
+export type ToolbarStatusPalette = Record<FeedbackStatus, ToolbarStatusStyle>;
+/**
+ * Every colour a surface here needs, named by role rather than by value so
+ * the two palettes can be swapped wholesale. `bar*` are the floating pill's
+ * own colours: it is a single opaque chip over arbitrary content, so it does
+ * not share the popovers' canvas.
+ */
+export interface ToolbarPalette {
+    ink: string;
+    /**
+     * What goes ON an ink fill, which is the polarity flip and not a constant:
+     * `ink` is #171717 light and #ffffff dark, so a primary button that hard-
+     * coded white text would be white-on-white for every dark-mode reviewer.
+     */
+    onInk: string;
+    body: string;
+    mute: string;
+    /**
+     * Accent-coloured TEXT, which is not the accent itself.
+     *
+     * `accent.start` on a 14%-orange wash measures about 3.0:1, and accent text
+     * is never larger than 13px here - under the 18px where 3:1 would be
+     * allowed. So the ink on the wash is a separate value per palette: a
+     * darkened orange in light, a lightened one in dark, both above 4.5:1.
+     *
+     * Nothing consumes it since the accent was demoted to identity only. It
+     * stays because the pin teardrop is still orange and the first person to
+     * print a word on it will need this rather than `accent.start`.
+     */
+    accentInk: string;
+    /**
+     * DESIGN.md's link blue, and it is a PAIR rather than a constant.
+     *
+     * `#0070f3` measures 4.6:1 on the light card and about 3.2:1 on the ink one,
+     * which is under AA for the 14px body copy a link sits in. The dark half is
+     * the lighter blue the status palette already uses for the same reason, so
+     * the two agree rather than each picking a blue.
+     */
+    link: string;
+    hairline: string;
+    hairlineStrong: string;
+    canvas: string;
+    canvasSoft: string;
+    canvasSoft2: string;
+    error: string;
+    success: string;
+    status: ToolbarStatusPalette;
+    /** The floating bar. */
+    barSurface: string;
+    barBorder: string;
+    barInk: string;
+    barInkMute: string;
+    barHover: string;
+    /** The wash the picker lays over the page while an element is being chosen. */
+    pickTint: string;
+    /**
+     * An ink fill at the weight a wash wants: the tint inside the picking
+     * outline, where the accent used to be. Stated per palette because "ink at
+     * 8%" is #171717 in light and #ffffff in dark, and one literal cannot be
+     * both.
+     */
+    inkSoft: string;
+    /** Ring drawn around a pin marker so it separates from the content beneath. */
+    markerRing: string;
+}
+export declare const lightPalette: ToolbarPalette;
+/**
+ * The dark palette, taken verbatim from `packages/ui/src/styles/globals.css`'s
+ * `.dark` block.
+ *
+ * It used to run the OPPOSITE direction from the dashboard's: canvas #0f0f0f
+ * was DARKER than canvasSoft #161616, while globals.css raises canvas #1f1f1f
+ * above canvas-soft #171717. Two dark theories in one product means every rule
+ * of the form "the row is canvas on a canvasSoft sheet" inverts when a
+ * reviewer crosses from the toolbar to the dashboard looking at the same
+ * feedback. One ladder, defined once, mirrored here.
+ */
+export declare const darkPalette: ToolbarPalette;
+export declare const radii: {
+    /** 4px. Concentric inner corner inside an 8px track, and the pin's point. */
+    readonly xs: "4px";
+    readonly sm: "6px";
+    readonly md: "8px";
+    readonly lg: "12px";
+    readonly pill: "100px";
+};
+export declare const spacing: {
+    readonly xxs: "4px";
+    readonly xs: "8px";
+    readonly sm: "12px";
+    readonly md: "16px";
+    readonly lg: "24px";
+};
+/**
+ * The margin an anchored surface keeps against the viewport's edge, as a
+ * NUMBER - the shape `DRAG_THRESHOLD` below already takes, and for the same
+ * reason: every use of it is arithmetic.
+ *
+ * Here rather than beside the clamps in PinLayer.tsx, which is where it began.
+ * The gutter appears on both axes and in both spellings - a `calc()` in a
+ * `maxWidth` and a `maxHeight`, and a `Math.min`/`Math.max` pair per axis in
+ * the code that decides where a card lands - and a token file cannot import a
+ * component's constant, so a copy in PinLayer meant tokens.ts held its own. It
+ * had five spellings between them (`16`, and four `32`s inside `calc()`
+ * strings) under a comment claiming they agreed "by construction". They do
+ * now.
+ *
+ * A card whose `maxWidth` disagreed with the clamp that positions it is
+ * pushed off the very edge the clamp believes it is holding it inside, which
+ * is not a hypothetical: it is `sizes.thread`'s own story one field down.
+ */
+export declare const VIEWPORT_GUTTER = 16;
+/**
+ * Box sizes that are not spacing and not radii: the handful of fixed squares
+ * and bubbles this package draws. They live here because every one of them
+ * used to be an off-grid literal spelled at its call site (13px, 14px, 9px,
+ * 3px), and a literal at a call site is how the next one gets invented.
+ */
+export declare const sizes: {
+    /** 16px form control, so the checkbox matches the 16px icons beside it. */
+    readonly control: "16px";
+    /** 28px: the sheet's close button and the pin marker's teardrop. */
+    readonly icon: "28px";
+    /** 18px count bubble - the smallest square that holds 12px mono legibly. */
+    readonly badge: "18px";
+    /** 8px unread dot. */
+    readonly dot: "8px";
+    /**
+     * 24px: the square a per-message action in a thread is drawn in (issue #20),
+     * and the thread's own close control, which used to be an invented 20px.
+     * A 16px glyph on DESIGN.md's `spacing.xxs` all round, so a row of them
+     * matches the 24px `Avatar` opposite it.
+     */
+    readonly action: "24px";
+    /**
+     * The thread card's width, and the pin composer's - issue #20 says in as
+     * many words that "both the pin popover and the composer-only variant share
+     * the 280px constant, widen both consistently", so they share this one.
+     *
+     * 440px is the Vercel comment thread's content width the issue names. It was
+     * two `"280px"` string literals at two call sites, which is exactly the
+     * shape the header comment above warns about: a THIRD place - the composer's
+     * own right-edge clamp - carried `280 + padding + border` as a hard-coded
+     * `300`, so widening one literal would have left the clamp holding the
+     * composer 140px inside an edge it thought it was hugging.
+     *
+     * A `px` string rather than a number because everything else in this object
+     * is one; the two call sites that need arithmetic parse it, which is one
+     * `parseFloat` against three places to forget.
+     */
+    readonly thread: "440px";
+    /**
+     * The ceiling a thread's message list scrolls inside, rather than growing
+     * past the viewport - issue #20's second acceptance line.
+     *
+     * Two caps, and both are needed. The `calc()` is `VIEWPORT_GUTTER` per
+     * side - the same margin the card's own `maxWidth` and the clamp that
+     * places it are built from - and is what stops a long thread running off
+     * the screen. The 480px is what stops a merely
+     * longish one filling a tall monitor: this card floats over the element it
+     * is talking about, and a review tool that covers the thing under review is
+     * the complaint the pin layer's own dismissal comment already answers once.
+     */
+    readonly threadMaxHeight: "min(480px, calc(100vh - 32px))";
+};
+/**
+ * Motion, from DESIGN.md's `## Motion` section - which this package's need is
+ * what added. See the provenance note at the head of this file: the toolbar
+ * renders through inline style inside somebody else's page, so there is no
+ * cascade to read a `--duration-fast` out of and the values are reproduced
+ * here, exactly as the colours and the type scale are.
+ *
+ * `enterScale` and `enterShift` are tokens rather than literals on purpose.
+ * The acceptance criterion for issue #24 is "no inline durations", and a bare
+ * `0.96` spelled at four call sites is the same defect one level down - the
+ * fifth surface is where somebody writes 0.95 and the product has two enters.
+ *
+ * Nothing here is a keyframe or a loop. Every value is one leg of a state
+ * transition a reviewer caused, which is the whole of the posture DESIGN.md
+ * states: small, fast, over before it is noticed.
+ */
+export declare const motion: {
+    readonly duration: {
+        /** 80ms - hover, press, a badge whose number changed. */
+        readonly instant: "80ms";
+        /** 120ms - the default, and every surface enter. */
+        readonly fast: "120ms";
+        /**
+         * 180ms - the ceiling, and the bar's collapse (issue #22) is its one
+         * consumer: it is the only transition here whose box changes shape
+         * underneath it, so `fast` lands before the eye has followed the pill's
+         * snap. Anything else reaching for this step needs the written reason
+         * DESIGN.md's duration table asks for.
+         */
+        readonly settle: "180ms";
+    };
+    readonly easing: {
+        /** Ease-out, for anything arriving. */
+        readonly enter: "cubic-bezier(0, 0, 0.2, 1)";
+        /** Ease-in, for anything leaving. */
+        readonly exit: "cubic-bezier(0.4, 0, 1, 1)";
+        /** Symmetric, for a property changing in place on a stationary element. */
+        readonly inOut: "cubic-bezier(0.4, 0, 0.2, 1)";
+    };
+    /** The one scale step an entering surface takes. */
+    readonly enterScale: 0.96;
+    /**
+     * The one squash a control takes under the pointer. Shallower than
+     * `enterScale` because a button that moves as far as a popover reads as
+     * broken rather than as pressed.
+     */
+    readonly pressScale: 0.97;
+    /** The one travel distance, for a surface that slides rather than scales. */
+    readonly enterShift: "4px";
+};
+/**
+ * One of the three steps in the table above, and nothing else.
+ *
+ * Exists so "no inline durations" - issue #24's acceptance criterion - can be
+ * a TYPE rather than a comment wherever a duration is passed as an argument.
+ * `surfaceMotion`'s `duration` option was declared `string` while its own doc
+ * comment claimed the only reachable values were `motion.duration` members;
+ * `duration: "140ms"` compiled fine, which made the claim false and the rule
+ * enforced by nothing. A call site that wants a fourth step now has to add it
+ * here first, where a reviewer sees it - which is what the comment said all
+ * along.
+ */
+export type MotionDuration = (typeof motion.duration)[keyof typeof motion.duration];
+/**
+ * "An exit is one step faster than its matching enter", as a function.
+ *
+ * DESIGN.md's duration table states that rule and issue #24's helper claimed
+ * to enforce it centrally - while hard-coding `instant` for every exit. That
+ * was one step faster for the two surfaces on `fast` and TWO steps faster for
+ * anything on `settle`, which is exactly the step issue #22's collapse then
+ * took. A rule enforced only for the durations that existed when it was
+ * written is not enforced.
+ *
+ * Both halves of an exit read this: the `transition` a surface leaves on, and
+ * the timer that then takes it out of the DOM. DESIGN.md says the removal is
+ * deferred "by exactly the exit duration", and two literals that happen to
+ * agree today is how that stops being true.
+ *
+ * `instant` has nowhere faster to go and answers itself, which is the right
+ * degradation - a surface entering at 80ms is already at the floor.
+ */
+export declare function exitFor(enter: MotionDuration): MotionDuration;
+/**
+ * A `transition` shorthand, composed rather than spelled.
+ *
+ * This is what makes "no inline durations" mechanically true instead of a
+ * promise: the only way to write a transition in this package is to name a
+ * duration token and an easing token, and a call site that wanted `140ms`
+ * would have to add it to `motion.duration` first, where a reviewer sees it.
+ *
+ * Deliberately not `transition: all`. `all` transitions properties nobody
+ * chose, `width` and `top` among them, and DESIGN.md forbids animating those
+ * over a host page for the reflow they cause. Every property is named.
+ *
+ * `reduced` IS REQUIRED, and that is the whole design of this signature.
+ * DESIGN.md's Reduced Motion rule is a system-layer promise, and the first
+ * draft of issue #24 kept it by writing `reduced ? [a, b] : [a, b, "transform"]`
+ * at seven call sites - seven independent restatements of one rule, none of
+ * them checked, and an eighth control added later would simply have omitted it
+ * and honoured nothing. Making the preference an argument nobody can leave out
+ * moves the rule to the token layer where the rest of this file lives: a call
+ * site now states the preference it read and this function decides what that
+ * means. Pass `false` only where there is genuinely no reviewer to ask.
+ */
+export declare function transition(properties: readonly string[], duration: string, easing: string, reduced: boolean): string;
+/**
+ * The transform half of the same rule, so it cannot be honoured by one and
+ * forgotten by the other.
+ *
+ * A reduced-motion surface is already at its final position and size on its
+ * first frame - so there is no offset to animate out of, which is why this
+ * answers `none` rather than shortening anything. `transition` above drops
+ * `transform` from the property list in the same breath; a call site that used
+ * one of these and not the other would either animate a transform it promised
+ * not to, or leave a surface parked at an offset with nothing to move it.
+ */
+export declare function motionTransform(value: string, reduced: boolean): string;
+/**
+ * How long an exit lasts, in milliseconds, for the deferred-unmount timer.
+ *
+ * A number as well as a string because a `setTimeout` cannot take "80ms" and
+ * hard-coding 80 beside the token is how the two drift apart. Parsed from the
+ * token rather than declared twice.
+ */
+export declare function durationMs(duration: string): number;
+export declare const typeScale: {
+    /** body-sm. The default voice of every popover. */
+    readonly bodySm: {
+        readonly fontFamily: "\"BitVea Geist\", Geist, Inter, system-ui, -apple-system, sans-serif";
+        readonly fontSize: "14px";
+        readonly fontWeight: 400;
+        readonly lineHeight: "20px";
+        readonly letterSpacing: "-0.28px";
+    };
+    /** body-sm-strong. Names, button labels, the one emphasis this UI has. */
+    readonly bodySmStrong: {
+        readonly fontFamily: "\"BitVea Geist\", Geist, Inter, system-ui, -apple-system, sans-serif";
+        readonly fontSize: "14px";
+        readonly fontWeight: 500;
+        readonly lineHeight: "20px";
+        readonly letterSpacing: "-0.28px";
+    };
+    /** display-sm, 600 - the weight ceiling, and only at 20px. */
+    readonly displaySm: {
+        readonly fontFamily: "\"BitVea Geist\", Geist, Inter, system-ui, -apple-system, sans-serif";
+        readonly fontSize: "20px";
+        readonly fontWeight: 600;
+        readonly lineHeight: "28px";
+        readonly letterSpacing: "-0.6px";
+    };
+    /** caption. Footnotes and secondary lines that are not technical facts. */
+    readonly caption: {
+        readonly fontFamily: "\"BitVea Geist\", Geist, Inter, system-ui, -apple-system, sans-serif";
+        readonly fontSize: "12px";
+        readonly fontWeight: 400;
+        readonly lineHeight: "16px";
+        readonly letterSpacing: "0px";
+    };
+    /** caption-mono. Every identifier: branch, commit, path, timestamp, status. */
+    readonly captionMono: {
+        readonly fontFamily: "\"BitVea Geist Mono\", \"Geist Mono\", ui-monospace, SFMono-Regular, Menlo, Monaco, monospace";
+        readonly fontSize: "12px";
+        readonly fontWeight: 400;
+        readonly lineHeight: "16px";
+        readonly letterSpacing: "0px";
+    };
+    /** code, 13px/20px. The captured selector, and nothing else so far. */
+    readonly code: {
+        readonly fontFamily: "\"BitVea Geist Mono\", \"Geist Mono\", ui-monospace, SFMono-Regular, Menlo, Monaco, monospace";
+        readonly fontSize: "13px";
+        readonly fontWeight: 400;
+        readonly lineHeight: "20px";
+        readonly letterSpacing: "0px";
+    };
+};
+/**
+ * The two faces, for the places that need a family without a whole role.
+ *
+ * NOT `Geist`. No `@font-face` in this repo registers that family: `next/font`
+ * exposes a hashed name through `--font-geist` and nothing else, so naming
+ * "Geist" here has never rendered the brand face on any surface, the preview
+ * harness included - it silently fell through to Inter or to system-ui. These
+ * are DESIGN.md's own sanctioned substitutes ("Note on Font Substitutes":
+ * Inter 400/500/600 for the geometric sans, a monospace of the same voice for
+ * the technical layer). Self-hosting the real faces inside this bundle is
+ * blocked on a licence decision and on CLAUDE.md section 8's size ceiling.
+ *
+ * And NOT `var(--font-geist)` at the head of the stack either. A `var()`
+ * reference to an undefined custom property makes the whole declaration
+ * invalid at computed-value time; `font-family` is inherited, so the toolbar
+ * would then inherit the HOST page's typeface on every site that does not
+ * define that variable - while looking correct inside apps/web, which does.
+ */
+export declare const fonts: {
+    readonly sans: "\"BitVea Geist\", Geist, Inter, system-ui, -apple-system, sans-serif";
+    readonly mono: "\"BitVea Geist Mono\", \"Geist Mono\", ui-monospace, SFMono-Regular, Menlo, Monaco, monospace";
+};
+/**
+ * The properties a host page's own element rules can set on markup this
+ * package renders unstyled, spread FIRST into every `form`, `label`, `header`,
+ * `section` and `p` here.
+ *
+ * The package ships no stylesheet, so nothing leaks OUT. Nothing stopped a
+ * host's `form { margin: 0 0 1rem; padding: 1rem; border: 1px solid #ccc }`
+ * from leaking IN and repainting the composer, which is the same class of bug
+ * as the `box-sizing` note in FeedbackToolbar.tsx and was invisible on the
+ * preview route only because apps/web loads Tailwind's preflight.
+ */
+export declare const resetBox: {
+    readonly margin: 0;
+    readonly padding: 0;
+    readonly border: 0;
+    readonly background: "transparent";
+    readonly boxSizing: "border-box";
+};
+/**
+ * Visually hidden, still in the accessibility tree AND still in `textContent`.
+ *
+ * An icon-only control needs a name, and `aria-label` alone would give it one
+ * only for a screen reader: `toHaveText` and `Node.textContent` - which is how
+ * both the e2e suite and the unit tests read the resolve control's label - see
+ * nothing an `aria-label` says. So the label is real text, clipped.
+ *
+ * Clipped rather than `display: none` or `visibility: hidden`, because both of
+ * those take the text OUT of the accessibility tree and out of `textContent`,
+ * which is the whole thing being preserved. The `clip` / `clipPath` pair is
+ * belt and braces: `clip` is deprecated and `clip-path` is what actually
+ * applies in a modern engine, and this package cannot rely on a host stylesheet
+ * to have shipped either.
+ */
+export declare const srOnly: {
+    readonly position: "absolute";
+    readonly width: "1px";
+    readonly height: "1px";
+    readonly margin: "-1px";
+    readonly padding: 0;
+    readonly border: 0;
+    readonly overflow: "hidden";
+    readonly clip: "rect(0 0 0 0)";
+    readonly clipPath: "inset(50%)";
+    readonly whiteSpace: "nowrap";
+};
+/** The bar's fixed geometry, from the reference's computed CSS. */
+export declare const bar: {
+    readonly radius: "8px";
+    readonly padding: "4px";
+    readonly gap: "8px";
+    /** 36x36 icon buttons, so a 4px-padded bar lands at the reference height. */
+    readonly button: "36px";
+    /**
+     * The bar's height, in BOTH forms: a 36px button, 4px of padding either
+     * side and the 1px hairline, which is also the collapsed circle's diameter.
+     *
+     * Written down rather than left implicit because the layout now has to do
+     * arithmetic with it: a mid-edge dock centres the BAR on the viewport, and
+     * doing that without moving it when a popover opens means offsetting the
+     * dock's own padding by half this. See `dockLayout`.
+     */
+    readonly height: "46px";
+    /**
+     * Issue #21's "standard viewport inset", on all four sides.
+     *
+     * It was `bottom`, because the bottom edge was the only dock there was. The
+     * dock is now a box inset from every edge by this one value, which is what
+     * makes "the bar always ends flush to an edge with the standard viewport
+     * inset" one number rather than four pieces of per-edge arithmetic.
+     */
+    readonly inset: "8px";
+};
+/**
+ * How far a pointer has to travel before a press on the bar is a DRAG rather
+ * than a click. Issue #21.
+ *
+ * A hit-test distance, deliberately not `motion.enterShift`: that is how far
+ * an entering surface travels, and the two agreeing on 4px today is not a
+ * reason for one to be defined in terms of the other. 6px swallows the wobble
+ * a trackpad click or a thumb tap produces, and is well inside the collapsed
+ * dot's own 46px box - so a reviewer who means to drag the dot has crossed it
+ * long before the pointer leaves the control.
+ */
+export declare const DRAG_THRESHOLD = 6;
+/**
+ * Where the bar sits. Issue #21.
+ *
+ * Eight discrete positions rather than a stored pixel coordinate, and that is
+ * the whole design: "snap targets are discrete, not free-floating - the bar
+ * always ends flush to an edge with the standard viewport inset". Two of the
+ * issue's acceptance criteria - "dragging never leaves the bar off-screen" and
+ * "a resize that would strand the bar re-docks it" - are then satisfied
+ * STRUCTURALLY. There is no coordinate to fall outside a viewport, so there is
+ * no resize listener and nothing to re-clamp; every value here is flush to an
+ * edge at every viewport size.
+ *
+ * Spelled `<vertical>-<horizontal>`, which is the vocabulary the tests written
+ * against issue #22 already pinned (`bottom-right`, `top-left`). The nine
+ * combinations less `middle-center`, which is not an edge - the issue calls the
+ * two survivors "the two vertical mid-edges".
+ */
+export type ToolbarDock = "top-left" | "top-center" | "top-right" | "middle-left" | "middle-right" | "bottom-left" | "bottom-center" | "bottom-right";
+/** Which horizontal band of the viewport a dock is in. */
+export type DockVertical = "top" | "middle" | "bottom";
+/** Which vertical band. */
+export type DockHorizontal = "left" | "center" | "right";
+/**
+ * The dock a reviewer who has never dragged anything gets, and the one issue
+ * #21 calls the default.
+ */
+export declare const DEFAULT_DOCK: ToolbarDock;
+/**
+ * Every dock, in the reading order the keyboard control lays them out: three
+ * across the top, the two mid-edges, three across the bottom. Exported so the
+ * 3x3 grid in the account surface and the tests do not each spell the list.
+ */
+export declare const TOOLBAR_DOCKS: readonly ToolbarDock[];
+/**
+ * Beside `isThemeMode`, and for the same reason: this value comes back out of
+ * the HOST's `localStorage`, so it can be anything their code, an extension or
+ * a newer build of this toolbar wrote there. `hasOwnProperty` rather than
+ * `in`, which would accept `"toString"`.
+ */
+export declare function isToolbarDock(value: unknown): value is ToolbarDock;
+/** The one place a per-edge answer is decided. See `dockLayout`. */
+export interface DockLayout {
+    vertical: DockVertical;
+    horizontal: DockHorizontal;
+    /**
+     * The dock is one flex column, and the DIRECTION is what flips for a top
+     * edge. The children are laid out switcher, popover, pill; reversed, the
+     * pill is visually first and the popover falls beneath it - which is the
+     * whole of "a top-docked bar opens its popover downwards".
+     */
+    flexDirection: "column" | "column-reverse";
+    /**
+     * How far the dock's own bottom padding holds the stack off the viewport's
+     * bottom edge - `bar.inset` at seven of the eight docks, and at the two
+     * mid-edges the offset that centres the BAR rather than the stack.
+     *
+     * This is the whole of how a mid-edge dock avoids moving the bar when a
+     * popover opens, and it was a real defect rather than a hypothetical: the
+     * dock packed the stack with `justifyContent: center`, so opening the
+     * composer at `middle-right` slid the bar 130px down the viewport and out
+     * from under the pointer that had just clicked it. The column now always
+     * packs against the bar's own edge - the popover grows away from the pill
+     * and the pill does not move - and "middle" is expressed as a padding
+     * instead: half the viewport, less half the bar, puts the pill's CENTRE on
+     * the centre line whatever is stacked above it. `vh` because the dock is a
+     * `position: fixed` box inset to all four edges, so its box is the
+     * viewport's.
+     */
+    paddingBottom: string;
+    /** Which side of the viewport the stack hugs. */
+    alignItems: "flex-start" | "center" | "flex-end";
+    /**
+     * `transform-origin` for the popover: DESIGN.md's rule that "a surface
+     * anchored to a control grows from the edge it is attached to", which is the
+     * edge FACING the bar and therefore flips with the dock.
+     */
+    popoverOrigin: string;
+    /** The longhand carrying the popover's gap to the pill, on that same edge. */
+    popoverGap: "marginTop" | "marginBottom";
+    /**
+     * Where the collapsed dot's unread indicator sits: the corner facing AWAY
+     * from the docked edge, so a circle - which has no orientation of its own -
+     * still answers issue #22's "the collapsed form follows the dock edge".
+     * Nothing is ever clipped; the dock keeps `bar.inset` on every side.
+     */
+    badge: {
+        top?: 0;
+        bottom?: 0;
+        left?: 0;
+        right?: 0;
+    };
+    /** Degrees to turn the collapse chevron by, so it points at the dock edge. */
+    chevron: number;
+}
+/**
+ * Everything that changes with the dock, derived in one place.
+ *
+ * Four call sites used to be four independent decisions waiting to disagree -
+ * the dock's flex triple, the popover's origin, the popover's gap and the
+ * badge's corner. They are all the same two facts (which vertical band, which
+ * horizontal band), so they are answered together.
+ */
+export declare function dockLayout(dock: ToolbarDock): DockLayout;
+export interface ToolbarShadows {
+    /**
+     * The bar's elevation is an outward GLOW rather than a drop shadow: the bar
+     * floats over content it does not belong to, and a directional shadow makes
+     * it look pasted onto the page instead of hovering above it.
+     */
+    bar: string;
+    popover: string;
+    marker: string;
+    /**
+     * DESIGN.md's Level 1: the inset hairline ring, on its own. Exported
+     * because three surfaces drew their own `0 0 0 1px <hairline>` ring by
+     * hand and one drew a raw `rgba(255,255,255,0.08)` literal.
+     */
+    insetHairline: string;
+    /**
+     * The keyboard focus ring. There was not one `outline`, `:focus` or focus
+     * state in this entire package, so any host shipping `*:focus { outline:
+     * none }` erased keyboard focus from a review tool - WCAG 2.4.7, failed by
+     * inheritance. Ink-based rather than link-blue, mirroring `--ring`'s ROLE
+     * (the highest-contrast ring the palette has) rather than its literal, since
+     * this palette has no link blue in it.
+     */
+    focusRing: string;
+}
+/** What the reviewer chose, which is not the same as what gets rendered. */
+export type ToolbarThemeMode = "system" | "light" | "dark";
+/** What gets rendered, after `system` has been resolved against the host. */
+export type ResolvedTheme = "light" | "dark";
+export interface ToolbarTheme {
+    resolved: ResolvedTheme;
+    colors: ToolbarPalette;
+    shadows: ToolbarShadows;
+}
+export declare const lightTheme: ToolbarTheme;
+export declare const darkTheme: ToolbarTheme;
+export declare function themeFor(resolved: ResolvedTheme): ToolbarTheme;
+/**
+ * Where the reviewer's manual override is remembered. `localStorage` on the
+ * host origin, because the preference belongs to this person on this app and
+ * there is nowhere else to put it that survives a reload without a round trip
+ * the disabled-build requirement forbids.
+ */
+export declare const THEME_STORAGE_KEY = "bitvea.feedback-toolbar.theme";
+/** Media query the default follows, read from the host document. */
+export declare const DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+/**
+ * The other preference the toolbar reads from the HOST document, beside it
+ * because they are answered the same way - one `matchMedia` subscription each,
+ * through `useSyncExternalStore` so there is a server snapshot.
+ *
+ * It is the host's document rather than ours because there is only one: the
+ * reviewer's own OS setting, which the page the toolbar is injected into has
+ * no say in. See `usePrefersReducedMotion` in motion.ts.
+ */
+export declare const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+export declare function isThemeMode(value: unknown): value is ToolbarThemeMode;
+/**
+ * Above almost everything. Host apps routinely use z-indexes in the thousands
+ * for their own modals; the toolbar has to sit above those to be usable at
+ * all, and it is the reviewer's own overlay rather than part of the page.
+ */
+export declare const Z_INDEX = 2147483000;
+/**
+ * The toolbar's own internal stacking order, inside the root that `Z_INDEX`
+ * lifts above the host page.
+ *
+ * This exists because every one of these surfaces used to pick its own number
+ * and the bar picked none at all - it inherited `z-index: auto`, which loses
+ * to any positive value in the same stacking context. The consequences were
+ * not cosmetic: the picking overlay painted over the bar and swallowed the
+ * click that cancels picking, leaving a reviewer with no way out of crosshair
+ * mode, and the inbox sheet covered the account button on any viewport under
+ * about 1024px.
+ *
+ * So the order is written down once, and the rule it encodes is that THE BAR
+ * IS ALWAYS REACHABLE. It is the only persistent chrome the toolbar has; every
+ * other surface is something the bar opened and the bar has to be able to
+ * close. Everything else stacks under it, most transient first.
+ *
+ * `thread` sits above `surface` rather than tying with it, and issue #23 is
+ * why. A z-index only orders the siblings that declare one; equal values fall
+ * back to DOM order, and the inbox sheet is rendered after the pin layer in
+ * FeedbackToolbar.tsx - so a thread parked at `surface` loses to the sheet on
+ * any pin under its 340px. That is the common case rather than the exotic one:
+ * `focusPin` deliberately leaves the sheet open when a reviewer clicks a row,
+ * because they are working down a list, and the thread they just asked for is
+ * then the surface they are reading. It goes above the list they asked from.
+ *
+ * The other half of #23 was that an anchored thread never reached this ladder
+ * at all. It renders inside its marker's wrapper, and that wrapper is
+ * `position: fixed` with a z-index - a stacking context whatever its opacity -
+ * so the rung a thread paints at is the one the WRAPPER declares, not one the
+ * thread could set on itself. `PinMarker` therefore moves its wrapper between
+ * `marker` and `thread` as the thread opens, and nothing inside that wrapper
+ * declares a z-index of its own. Read this list as the order that actually
+ * renders; when it stops being that, the code is what is wrong.
+ *
+ * WHAT IS DELIBERATELY NOT IN THIS LADDER: the note and account popovers.
+ * `surface` used to be documented as "threads, composers, popovers and the
+ * inbox sheet" and only the sheet was ever really there - the popovers are
+ * children of the DOCK, so they ride its `bar` rung and have never declared
+ * one of their own. Splitting `thread` out of `surface` for issue #23 made
+ * that list true for threads and composers and left the popovers unmentioned,
+ * which is worse than the wrong entry: a reader could not place them at all.
+ * They are chrome rather than surfaces. They are anchored to the bar, opened
+ * and closed by the button beside them, and clamped to the same strip, so
+ * "above everything, with the bar" is the whole of their layering and a rung
+ * would be a second place to state it.
+ */
+export declare const layers: {
+    /** The picking wash. Under everything, including its own markers. */
+    readonly picker: number;
+    /** Pin markers: part of the page's review state, so below any open surface. */
+    readonly marker: number;
+    /** Panels the bar opened and the bar closes again: the inbox sheet. */
+    readonly surface: number;
+    /**
+     * The one thread the reviewer is reading, and the composer they are writing
+     * the next one in - a composer is a thread that does not exist yet, so it
+     * shares this rung and wins the tie by being rendered last.
+     */
+    readonly thread: number;
+    /** Alerts that must be seen over an open surface. */
+    readonly alert: number;
+    /** The floating bar. Nothing the toolbar renders may cover it. */
+    readonly bar: 2147483000;
+};
+//# sourceMappingURL=tokens.d.ts.map