@bitvea/feedback-toolbar 0.0.1

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,EACvB,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAU/D,OAAO,EACL,UAAU,EACV,cAAc,EACd,yBAAyB,EACzB,eAAe,EACf,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AA+B1D,OAAO,EACL,MAAM,EACN,SAAS,EACT,YAAY,EACZ,OAAO,EACP,KAAK,EACL,UAAU,EACV,MAAM,EACN,eAAe,EACf,KAAK,EACL,oBAAoB,EACpB,KAAK,EACL,OAAO,EACP,QAAQ,EACR,aAAa,EACb,UAAU,EACV,SAAS,EACT,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,sBAAsB,GAC5B,MAAM,UAAU,CAAC;AAQlB,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,OAAO,EACP,aAAa,EACb,KAAK,SAAS,GACf,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,68 @@
+// @bitvea/feedback-toolbar - the toolbar a BitVea app installs to collect
+// review feedback from its preview deployments.
+//
+// Install with `npx @bitvea/feedback-toolbar init`, which adds the dependency,
+// writes the env vars, and injects <FeedbackToolbar /> into the root layout.
+export { FeedbackToolbar, } from "./FeedbackToolbar.js";
+export { FeedbackPanel, AccountSurface, } from "./FeedbackPanel.js";
+// The inbox sheet is the default inbox, so a host never needs to name it -
+// but a host replacing it needs its props, and the preview route mounts it
+// directly.
+export { InboxSheet, INBOX_OPEN_STORAGE_KEY, } from "./InboxSheet.js";
+// Deep-linking. The dashboard builds these links; the toolbar consumes them.
+export { buildDeepLink, parseDeepLink, DEEP_LINK_PREFIX } from "./deepLink.js";
+export { createToolbarClient, ToolbarApiError, } from "./client.js";
+export { captureMetadata, captureScreenshot } from "./capture.js";
+// The composer's formatting helpers, and the markdown SAFETY POLICY the
+// dashboard renders by too. Shared rather than copied: the two surfaces style
+// a comment differently and must decide what a comment IS identically, or the
+// same text means two things and the copy nobody is looking at drifts.
+//
+// Rendering itself is react-markdown's job. The conditions that keep it safe
+// on a customer's page are at the head of RichText.tsx - chiefly that
+// `rehype-raw` is never added.
+export { toggleMark, MARKDOWN_MARKS, MARKDOWN_ALLOWED_ELEMENTS, safeMarkdownUrl, } from "./markdown.js";
+export { PinLayer } from "./PinLayer.js";
+// The tokens the toolbar renders with, for a surface that has to sit beside
+// it - the preview route's own chrome, for one - without re-deriving them.
+// The type scale, spacing and radii are exported alongside the palettes for
+// the same reason the palettes are: a neighbouring surface that re-derives
+// them drifts, and the alternative to exporting them is a second set of
+// literals somewhere nobody looks.
+// `motion`, `transition` and `motionTransform` are in this list for exactly
+// the reason the rest of it gives: a surface sitting beside the toolbar that
+// hand-writes `120ms ease` is a surface that animates at a different speed
+// from the thing it sits beside, and DESIGN.md's Motion section is the
+// authority both are supposed to be reading. The two functions travel together
+// because they are two halves of one rule - `transition` takes `transform` out
+// of the property list under reduced motion and `motionTransform` takes out
+// the value, and a consumer with only one of them can honour only half the
+// preference. The hooks in motion.ts stay internal - they are how this package
+// implements the vocabulary, not part of it - but `reduced` is a REQUIRED
+// argument on both functions, so `REDUCED_MOTION_QUERY` has to travel with them
+// or a consumer has no way to answer it except by retyping the media string,
+// which is exactly the drift the palettes are exported to prevent. `exitFor`
+// and `MotionDuration` come along for the same reason: the exit rule and the
+// closed set of three steps are the parts of `transition`'s contract a caller
+// outside this file would otherwise have to guess at.
+// `ToolbarDock` and its two constants are exported ADDITIVELY, and that word is
+// doing work: this is the one package here that publishes to npm, so the eight
+// dock values are now part of a shipped type. A host that renders the account
+// surface itself, or that wants to write the reviewer's dock from its own
+// settings screen, needs the vocabulary - and it needs it as a type it cannot
+// mistype rather than as eight strings copied out of a changelog. Nothing
+// existing changed shape: no prop was added to `AccountSurfaceProps`, which is
+// why the position control reads the preference store directly.
+export { accent, darkTheme, DEFAULT_DOCK, exitFor, fonts, lightTheme, motion, motionTransform, radii, REDUCED_MOTION_QUERY, sizes, spacing, themeFor, TOOLBAR_DOCKS, transition, typeScale, } from "./tokens.js";
+export { buildSelector, resolveSelector, offsetWithin, locatePin, } from "./selector.js";
+export { resolveConfig, API_URL_ENV_VAR, VERCEL_ENV_VARS, } from "./config.js";
+// The pinning chord. Exported because remapping or switching it off is a HOST
+// decision - the toolbar claims the keys inside the host's own application -
+// and a host cannot express either without the chord's type. `formatChord`
+// travels with them for the same reason the palettes do: a host that renders
+// its own hint and hand-writes "Cmd+Space+F" has written a second copy of a
+// value this package can change, which is the drift the single definition
+// exists to prevent.
+export { DEFAULT_PIN_SHORTCUT, formatChord, isApplePlatform, } from "./shortcut.js";
+export { isToolbarEnabled, isToolbarEnabledFromEnv, ENV_VAR, FORCE_ENV_VAR, } from "./gating.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,gDAAgD;AAChD,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,OAAO,EACL,eAAe,GAIhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EAEb,cAAc,GAEf,MAAM,iBAAiB,CAAC;AACzB,2EAA2E;AAC3E,2EAA2E;AAC3E,YAAY;AACZ,OAAO,EACL,UAAU,EAGV,sBAAsB,GACvB,MAAM,cAAc,CAAC;AACtB,6EAA6E;AAC7E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EACL,mBAAmB,EACnB,eAAe,GAGhB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE/D,wEAAwE;AACxE,8EAA8E;AAC9E,8EAA8E;AAC9E,uEAAuE;AACvE,EAAE;AACF,6EAA6E;AAC7E,sEAAsE;AACtE,+BAA+B;AAC/B,OAAO,EACL,UAAU,EACV,cAAc,EACd,yBAAyB,EACzB,eAAe,GAEhB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAsB,MAAM,YAAY,CAAC;AAC1D,4EAA4E;AAC5E,2EAA2E;AAC3E,4EAA4E;AAC5E,2EAA2E;AAC3E,wEAAwE;AACxE,mCAAmC;AACnC,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAC3E,uEAAuE;AACvE,+EAA+E;AAC/E,+EAA+E;AAC/E,4EAA4E;AAC5E,2EAA2E;AAC3E,+EAA+E;AAC/E,0EAA0E;AAC1E,gFAAgF;AAChF,6EAA6E;AAC7E,6EAA6E;AAC7E,6EAA6E;AAC7E,8EAA8E;AAC9E,sDAAsD;AACtD,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAC9E,0EAA0E;AAC1E,+EAA+E;AAC/E,gEAAgE;AAChE,OAAO,EACL,MAAM,EACN,SAAS,EACT,YAAY,EACZ,OAAO,EACP,KAAK,EACL,UAAU,EACV,MAAM,EACN,eAAe,EACf,KAAK,EACL,oBAAoB,EACpB,KAAK,EACL,OAAO,EACP,QAAQ,EACR,aAAa,EACb,UAAU,EACV,SAAS,GASV,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,GAGhB,MAAM,UAAU,CAAC;AAClB,8EAA8E;AAC9E,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAC7E,4EAA4E;AAC5E,0EAA0E;AAC1E,qBAAqB;AACrB,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,eAAe,GAGhB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,OAAO,EACP,aAAa,GAEd,MAAM,UAAU,CAAC"}

package/dist/markdown.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The markers, and the only ones the bar writes. CommonMark, so what a
+ * reviewer types by hand and what the buttons produce are the same thing.
+ */
+export declare const MARKDOWN_MARKS: {
+    readonly bold: "**";
+    readonly italic: "_";
+    readonly strike: "~~";
+    readonly code: "`";
+};
+export type MarkdownMark = keyof typeof MARKDOWN_MARKS;
+/**
+ * react-markdown's `urlTransform`, as an ALLOWLIST.
+ *
+ * The library ships a default that strips known-dangerous protocols; this
+ * replaces it because the set of dangerous schemes is open-ended and the set
+ * of useful ones is three.
+ *
+ * Parsed with NO BASE, and that is the load-bearing detail. Resolving against
+ * one made every relative href PASS: `//evil.example/steal` became
+ * `https://evil.example/steal`, and `/settings` became a link to whatever
+ * origin the base named - while on a customer's page a relative href points at
+ * THEIR site, not ours. Without a base those throw, which is the right answer:
+ * a comment renders on the reviewed site AND on the dashboard, so a
+ * destination meaning "here" means two different places.
+ *
+ * Returns `""` rather than throwing: a refused destination renders as inert
+ * text with its label intact, so nothing a reviewer wrote disappears and
+ * nothing they wrote executes.
+ */
+export declare function safeMarkdownUrl(url: string): string;
+/**
+ * The elements a comment may render, on either surface.
+ *
+ * Shared rather than duplicated: the toolbar and the dashboard style comments
+ * differently and must decide what a comment IS identically, or the same text
+ * means two things. Anything outside this list is dropped with its text kept
+ * (`unwrapDisallowed`), so an unsupported construct reads as what the reviewer
+ * typed rather than vanishing.
+ *
+ * No `img`: it would let a comment fetch a remote URL from inside a customer's
+ * page - a tracking pixel the reviewed site appears to have requested - and a
+ * screenshot has its own field. No headings: they are noise in a 440px card.
+ */
+export declare const MARKDOWN_ALLOWED_ELEMENTS: readonly ["p", "br", "strong", "em", "del", "code", "pre", "a", "ul", "ol", "li", "blockquote", "hr"];
+/**
+ * Wrap or unwrap a selection, for the composer's formatting bar.
+ *
+ * Toggling rather than only wrapping: a reviewer who bolds the wrong word
+ * presses the same button to undo it, which is what every editor they have
+ * used does. Returns the new text and where the selection should land, because
+ * a formatting button that loses the cursor is one a reviewer stops using.
+ */
+export declare function toggleMark(text: string, start: number, end: number, mark: MarkdownMark): {
+    text: string;
+    selectionStart: number;
+    selectionEnd: number;
+};
+//# sourceMappingURL=markdown.d.ts.map

package/dist/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;CAOjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,cAAc,CAAC;AAWvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,uGAc5B,CAAC;AAEX;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,YAAY,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAmChE"}

package/dist/markdown.js

@@ -0,0 +1,130 @@
+// The markers the composer's formatting bar writes.
+//
+// RENDERING is `react-markdown`'s job (see RichText.tsx); this is only the
+// half that edits the source text. The two have to agree on the grammar, and
+// they do because the grammar is CommonMark - these are the markers it
+// defines, not a dialect of our own.
+//
+// There is no parser here any more. There was one, and the library replaced it
+// for two reasons worth writing down: a hand-written parser covers four
+// constructs and a maintained one covers the language, and the edge cases in
+// markdown are endless enough that owning them is a standing cost. It was NOT
+// replaced for safety - both build a React tree and neither produces HTML, and
+// the conditions that keep react-markdown safe are listed at the head of
+// RichText.tsx.
+/**
+ * The markers, and the only ones the bar writes. CommonMark, so what a
+ * reviewer types by hand and what the buttons produce are the same thing.
+ */
+export const MARKDOWN_MARKS = {
+    bold: "**",
+    italic: "_",
+    // GFM, which is why `remark-gfm` is loaded: CommonMark has no strikethrough.
+    // It renders to `del`, which the allowed element set carries.
+    strike: "~~",
+    code: "`",
+};
+/**
+ * Only these schemes may appear in a link.
+ *
+ * `javascript:` is the obvious one, but `data:` is the one that gets missed: a
+ * `data:text/html` href executes in the page's origin on click, which on a
+ * customer's site is THEIR origin, not ours.
+ */
+const SAFE_SCHEMES = ["http:", "https:", "mailto:"];
+/**
+ * react-markdown's `urlTransform`, as an ALLOWLIST.
+ *
+ * The library ships a default that strips known-dangerous protocols; this
+ * replaces it because the set of dangerous schemes is open-ended and the set
+ * of useful ones is three.
+ *
+ * Parsed with NO BASE, and that is the load-bearing detail. Resolving against
+ * one made every relative href PASS: `//evil.example/steal` became
+ * `https://evil.example/steal`, and `/settings` became a link to whatever
+ * origin the base named - while on a customer's page a relative href points at
+ * THEIR site, not ours. Without a base those throw, which is the right answer:
+ * a comment renders on the reviewed site AND on the dashboard, so a
+ * destination meaning "here" means two different places.
+ *
+ * Returns `""` rather than throwing: a refused destination renders as inert
+ * text with its label intact, so nothing a reviewer wrote disappears and
+ * nothing they wrote executes.
+ */
+export function safeMarkdownUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return SAFE_SCHEMES.includes(parsed.protocol) ? url : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * The elements a comment may render, on either surface.
+ *
+ * Shared rather than duplicated: the toolbar and the dashboard style comments
+ * differently and must decide what a comment IS identically, or the same text
+ * means two things. Anything outside this list is dropped with its text kept
+ * (`unwrapDisallowed`), so an unsupported construct reads as what the reviewer
+ * typed rather than vanishing.
+ *
+ * No `img`: it would let a comment fetch a remote URL from inside a customer's
+ * page - a tracking pixel the reviewed site appears to have requested - and a
+ * screenshot has its own field. No headings: they are noise in a 440px card.
+ */
+export const MARKDOWN_ALLOWED_ELEMENTS = [
+    "p",
+    "br",
+    "strong",
+    "em",
+    "del",
+    "code",
+    "pre",
+    "a",
+    "ul",
+    "ol",
+    "li",
+    "blockquote",
+    "hr",
+];
+/**
+ * Wrap or unwrap a selection, for the composer's formatting bar.
+ *
+ * Toggling rather than only wrapping: a reviewer who bolds the wrong word
+ * presses the same button to undo it, which is what every editor they have
+ * used does. Returns the new text and where the selection should land, because
+ * a formatting button that loses the cursor is one a reviewer stops using.
+ */
+export function toggleMark(text, start, end, mark) {
+    const marker = MARKDOWN_MARKS[mark];
+    const selected = text.slice(start, end);
+    const before = text.slice(0, start);
+    const after = text.slice(end);
+    // Already wrapped, either inside the selection or just outside it.
+    if (selected.startsWith(marker) &&
+        selected.endsWith(marker) &&
+        selected.length > marker.length * 2) {
+        const stripped = selected.slice(marker.length, -marker.length);
+        return {
+            text: before + stripped + after,
+            selectionStart: start,
+            selectionEnd: start + stripped.length,
+        };
+    }
+    if (before.endsWith(marker) && after.startsWith(marker)) {
+        return {
+            text: before.slice(0, -marker.length) + selected + after.slice(marker.length),
+            selectionStart: start - marker.length,
+            selectionEnd: end - marker.length,
+        };
+    }
+    // An empty selection inserts the pair and puts the cursor between them, so
+    // the button works before the words exist as well as after.
+    return {
+        text: `${before}${marker}${selected}${marker}${after}`,
+        selectionStart: start + marker.length,
+        selectionEnd: end + marker.length,
+    };
+}
+//# sourceMappingURL=markdown.js.map

package/dist/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,uEAAuE;AACvE,qCAAqC;AACrC,EAAE;AACF,+EAA+E;AAC/E,wEAAwE;AACxE,6EAA6E;AAC7E,8EAA8E;AAC9E,+EAA+E;AAC/E,yEAAyE;AACzE,gBAAgB;AAEhB;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,GAAG;IACX,6EAA6E;IAC7E,8DAA8D;IAC9D,MAAM,EAAE,IAAI;IACZ,IAAI,EAAE,GAAG;CACD,CAAC;AAIX;;;;;;GAMG;AACH,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,GAAG;IACH,IAAI;IACJ,QAAQ;IACR,IAAI;IACJ,KAAK;IACL,MAAM;IACN,KAAK;IACL,GAAG;IACH,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,YAAY;IACZ,IAAI;CACI,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,KAAa,EACb,GAAW,EACX,IAAkB;IAElB,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAE9B,mEAAmE;IACnE,IACE,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;QAC3B,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EACnC,CAAC;QACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/D,OAAO;YACL,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK;YAC/B,cAAc,EAAE,KAAK;YACrB,YAAY,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM;SACtC,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxD,OAAO;YACL,IAAI,EACF,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;YACzE,cAAc,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM;YACrC,YAAY,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM;SAClC,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,4DAA4D;IAC5D,OAAO;QACL,IAAI,EAAE,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,EAAE;QACtD,cAAc,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM;QACrC,YAAY,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM;KAClC,CAAC;AACJ,CAAC"}

package/dist/motion.d.ts

@@ -0,0 +1,178 @@
+import { type CSSProperties } from "react";
+import { type MotionDuration } from "./tokens.js";
+/**
+ * `prefers-reduced-motion: reduce`, read from the host document and kept live.
+ *
+ * A hook per animating component rather than a field on `ToolbarTheme`. The
+ * theme is a colour and elevation object that `themeFor` returns as one of two
+ * module constants; widening it to carry a motion preference would make it
+ * per-render, which is a real cost for a subscription that is free to
+ * duplicate.
+ */
+export declare function usePrefersReducedMotion(): boolean;
+/**
+ * False on the frame a surface mounts, true on the next one.
+ *
+ * This is the whole reason an inline `transition` is not enough on its own: a
+ * transition never runs on an element's FIRST style computation, so a surface
+ * that mounts already at `opacity: 1` has nothing to transition from. The
+ * `from` state has to be committed, painted, and only then replaced - which is
+ * one `requestAnimationFrame`.
+ *
+ * `requestAnimationFrame` rather than a layout effect that reads `offsetWidth`
+ * to force the same flush. Both work; the reflow version synchronously lays
+ * out the HOST page every time a reviewer opens a thread, and this package's
+ * standing rule is that it costs the page it is injected into as little as
+ * possible. Where there is no frame loop to wait for, the surface simply
+ * starts entered - a hard cut is the correct degradation.
+ *
+ * `settledAtMount` is DESIGN.md's first-mount rule for the one shape that
+ * cannot infer it. For a surface that MOUNTS when it opens, the mount is the
+ * reviewer's own click and there is nothing to distinguish - it enters, which
+ * is the default. For a surface mounted all session and toggled by a prop, an
+ * `active` that is already true on the first render is RESTORED STATE, not an
+ * action: the inbox sheet's open flag comes out of `localStorage`, so without
+ * this the sheet replayed its whole slide-in on every page the reviewer
+ * navigated to with it left open - "the toolbar animates itself in on every
+ * page load", which is the exact thing DESIGN.md forbids.
+ */
+export declare function useEntered(active?: boolean, settledAtMount?: boolean): boolean;
+/**
+ * The two-sided sibling of `useEntered`: false for one frame after `form`
+ * changes, true otherwise, and true on the very first render.
+ *
+ * For a surface that is REPLACED rather than opened. `useEntered` takes a
+ * boolean, so it can only re-arm in one direction - `active` going false means
+ * "this surface is gone" and its effect deliberately stops there. The bar's
+ * two forms (issue #22) are not open and closed: each of them is the current
+ * one, and whichever arrives has to enter, so the trigger is a value CHANGING
+ * rather than a flag going true.
+ *
+ * Settled on the first render, and here that is not an option a call site
+ * passes but the only correct answer: which form the bar is in comes out of
+ * `localStorage`, so a reviewer who collapsed it meets it collapsed on the
+ * next page - restored state, not an action - and a toolbar that replays its
+ * own collapse on every navigation is precisely what DESIGN.md's first-mount
+ * rule forbids. That is the bug `useEntered`'s `settledAtMount` was added for,
+ * one surface earlier.
+ *
+ * THE CALLER MUST REMOUNT THE ELEMENT IT STYLES - key it on the same `form`.
+ * Everything else in this file is used by a surface that mounts when it opens,
+ * which is why a transition can run on it at all: a transition never runs on
+ * an element's FIRST style computation, so the `from` state paints and the
+ * `to` state animates. A swap has no mount, so an element reused across it
+ * receives `opacity: 0` with the transition ALREADY declared, animates 1 -> 0,
+ * and gets reversed one frame later - a hard cut wearing a transition. This
+ * hook decides WHEN the from-state is committed; only a new element makes that
+ * commit instantaneous. See `BarContents` in FeedbackToolbar.tsx.
+ */
+export declare function useSwapEntered(form: unknown): boolean;
+/**
+ * "Was this one already here when the surface opened?", as a predicate.
+ *
+ * DESIGN.md's first-mount rule applied to a list: the replies already in a
+ * thread are pre-existing state and must not animate, or every reopen of an
+ * old thread replays the whole conversation arriving. Only the reply that
+ * lands while the reviewer is looking is new.
+ *
+ * The set is captured on the first render and never updated, which is the
+ * point - an id that arrives later stays "new" for as long as this surface is
+ * mounted, and the row it belongs to plays its enter exactly once because the
+ * row itself mounts exactly once.
+ */
+export declare function useNewSinceMount(ids: readonly string[]): (id: string) => boolean;
+export interface Presence {
+    /** Whether to render the surface at all. */
+    mounted: boolean;
+    /** Whether it is on its way out. */
+    leaving: boolean;
+}
+/**
+ * Keep a surface in the DOM for one exit duration after it closes, then take
+ * it out for real.
+ *
+ * The deferral is DOM REMOVAL ONLY. Whatever state change closed the surface
+ * has already been committed by the caller - `openPinId` is null, the sheet's
+ * store says closed - so nothing a reviewer did is waiting on an animation,
+ * which is DESIGN.md's "an exit never delays the action that triggered it".
+ *
+ * And the element really does leave. A surface parked at `opacity: 0` forever
+ * is markup in a host app's DOM that their own queries and audits trip over,
+ * and four e2e specs assert these surfaces reach zero elements - Playwright
+ * retries, so a deferred unmount passes and a permanent ghost does not.
+ *
+ * The latch is set during render rather than in an effect: "a prop changed, so
+ * derive some state from it" is React's own documented shape for this, it is
+ * what `PinLayer` already does for a focus request, and doing it in an effect
+ * would paint one frame of the closed surface still fully open.
+ *
+ * `exit` is the EXIT duration, and a caller that also drives `surfaceMotion`
+ * has to spell it the same way that helper does - `exitFor(<the enter step>)`
+ * - or the timer and the transition are two independent literals for the one
+ * value DESIGN.md calls "exactly the exit duration".
+ */
+export declare function usePresence(open: boolean, exit: string): Presence;
+/**
+ * True for one `instant` after `value` changes, and false on first mount.
+ *
+ * For acknowledging a number that moved rather than a surface that arrived:
+ * the unread badge, whose colours and position are identical before and after,
+ * so without this a count going 3 → 4 is a glyph swap nobody sees.
+ *
+ * A latch rather than an enter, and the difference matters: the element has
+ * been on screen for a while, so its resting state is already painted and a
+ * transition out of it runs immediately - no frame of `from` state to arrange,
+ * and therefore no `requestAnimationFrame`.
+ */
+export declare function useJustChanged(value: unknown): boolean;
+export interface SurfaceMotionOptions {
+    /** True once the surface has had its first frame. From `useEntered`. */
+    visible: boolean;
+    /** True while it is on its way out. From `usePresence`. */
+    leaving?: boolean;
+    /** From `usePrefersReducedMotion`. */
+    reduced: boolean;
+    /**
+     * `transform-origin`, relative to the surface's own box. Omitted means the
+     * default centre, which is right only for a surface with no anchor - see
+     * DESIGN.md: a surface opened by a click originates at the clicked pixel.
+     */
+    origin?: string;
+    /**
+     * Slide on this axis instead of scaling. `x` is a sheet coming in from the
+     * viewport's edge, `y` a message arriving from below.
+     */
+    slide?: "x" | "y";
+    /**
+     * The ENTER's duration, for the surface DESIGN.md's own duration table puts
+     * on a step other than `fast`. A token, never a literal - `MotionDuration`
+     * is the union of the three steps in `motion.duration`, so the only way to
+     * reach a value not in that object is to add it there first. It was declared
+     * `string`, which said the same thing in a comment and accepted `"140ms"`
+     * without complaint.
+     *
+     * Only the enter. "An exit is one step faster than its matching enter" is a
+     * rule from the same table and not a per-call-site decision, so there is
+     * deliberately no way to override the exit - it is DERIVED from this, by
+     * `exitFor` in tokens.ts. It used to be hard-coded `instant`, which was one
+     * step faster only for the surfaces already on `fast`; the moment issue #22
+     * put the bar's collapse on `settle`, the rule this comment states stopped
+     * being the rule the code applied.
+     */
+    duration?: MotionDuration;
+}
+/**
+ * Every entering and leaving surface in this package, styled from one place.
+ *
+ * A helper rather than five hand-written style fragments because "the same
+ * enter everywhere" is the point of having tokens at all, and because the
+ * three things easy to get wrong here - which properties are transitioned,
+ * which direction the easing runs, what reduced motion drops - are exactly the
+ * three a call site would restate slightly differently each time.
+ *
+ * Only `opacity` and `transform` appear. Both are handed to the compositor and
+ * reflow nothing, which is what lets this package animate at all over a host
+ * page nobody here wrote.
+ */
+export declare function surfaceMotion({ visible, leaving, reduced, origin, slide, duration, }: SurfaceMotionOptions): CSSProperties;
+//# sourceMappingURL=motion.d.ts.map

package/dist/motion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../src/motion.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,KAAK,aAAa,EAInB,MAAM,OAAO,CAAC;AAEf,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAsClB;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,UAAU,CAAC,MAAM,UAAO,EAAE,cAAc,UAAQ,GAAG,OAAO,CA8BzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAsBrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,SAAS,MAAM,EAAE,GACrB,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAMzB;AAID,MAAM,WAAW,QAAQ;IACvB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAgBjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAkBtD;AAID,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;IAClB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,OAAe,EACf,OAAO,EACP,MAAM,EACN,KAAK,EACL,QAA+B,GAChC,EAAE,oBAAoB,GAAG,aAAa,CA6BtC"}