gap-inspector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bence Redmond
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# Gap Inspector
+
+Gap Inspector is a React dev overlay for explaining visual spacing. It lets you draw a horizontal or vertical line between rendered elements, then copies a markdown report with the selected DOM elements, total gap, CSS/layout contributors, and a pixel equation.
+
+It is built for the frontend workflow where "make this gap match that gap" is too vague for an agent to execute reliably.
+
+## Install
+
+```sh
+npm install gap-inspector -D
+```
+
+## Usage
+
+```tsx
+import { GapInspector } from "gap-inspector";
+
+export function App() {
+  return (
+    <>
+      <YourApp />
+      <GapInspector />
+    </>
+  );
+}
+```
+
+The toolbar appears in the bottom-right corner. Open it and draw a line between two rendered edges; the measurement axis is inferred from the drag direction. Drag the panel header to move the inspector anywhere on screen.
+
+## What It Reports
+
+```md
+Measured horizontal gap: 48px
+
+From: `.Sidebar`
+To: `.PreviewPanel`
+Common ancestor: `.MainShell`
+
+Contributions:
+- 16px from `.MainShell` column-gap (16px) - flex parent
+- 8px from `.TableWrap` padding-right (8px)
+- 6px from `.MarketTableBody` scrollbar gutter - Native scrollbar gutter inside this scroll container.
+- 24px from `.MainShell` flex space-between - Rendered space between sibling layout branches.
+
+Equation: 16px + 8px + 6px + 24px = 54px
+```
+
+## Notes
+
+The tool measures rendered geometry first, then attributes pixels to computed CSS where it can. Some spacing is not directly caused by a single margin or padding declaration. Flex distribution, grid tracks, explicit widths, `min-width`, transforms, scrollbars, and empty wrappers may show up as layout or unattributed space.
+
+That distinction is deliberate: the report should be useful to an LLM without inventing false causes.
+
+Adjacent vertical margins that collapse are reported as the single winning margin (with a note about the collapsed sibling). Negative margins and transformed elements cannot be expressed as positive contributors, so they are surfaced as warnings instead.
+
+Hold <kbd>⌥</kbd>/<kbd>Alt</kbd> while the inspector is open to let pointer events through to the page — useful for opening click-driven menus or scrolling nested panes into the state you want to measure.
+
+## Limitations
+
+- **Closed shadow roots** cannot be inspected. Open shadow roots are pierced for hit-testing and get `host >>> inner` selectors in reports.
+- **Iframes** are measured as opaque boxes; their contents render in a separate document and cannot be attributed (the report warns when an endpoint is an iframe).
+- **CSS-only `:hover` states** collapse as soon as the pointer moves onto the inspector canvas, so they cannot be measured. The Alt passthrough covers UI that stays open after a click.
+- **`position: fixed`/`sticky` elements** move relative to the document, so their committed overlays catch up one frame behind during scroll (everything else tracks scroll with zero lag).
+
+## API
+
+```tsx
+<GapInspector
+  initiallyOpen={false}
+  onMeasure={(measurement) => {
+    console.log(measurement.markdown);
+  }}
+/>
+```
+
+You can also call the measurement engine directly:
+
+```ts
+import { measureGap } from "gap-inspector";
+
+const measurement = measureGap({
+  axis: "horizontal",
+  start: { x: 220, y: 340 },
+  end: { x: 420, y: 340 }
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { inferAxis, measureGap, type GapMeasurement } from "./measurement";
+export type GapInspectorProps = {
+    initiallyOpen?: boolean;
+    onMeasure?: (measurement: GapMeasurement) => void;
+};
+export declare function GapInspector({ initiallyOpen, onMeasure }: GapInspectorProps): import("react").JSX.Element;
+export { inferAxis, measureGap };
+export type { GapAxis, GapContribution, GapMeasurement, GapPoint, PointInspection } from "./measurement";