@ng-prism/core 22.3.0 → 22.4.1

package/README.md

@@ -1,24 +1,24 @@
 # ng-prism
 
-**ng-prism** is the Angular-native Storybook alternative. A lightweight component showcase tool that scans your library at build time and renders interactive demos — annotate components with `@Showcase`, no separate story files needed.
+**ng-prism** is the Angular-native Storybook alternative. A lightweight component showcase tool that scans your library at build time and renders interactive demos. Annotate components with `@Showcase`; no separate story files needed.
 
 [![Angular](https://img.shields.io/badge/Angular-20%20%7C%2021%20%7C%2022-dd0031)](https://angular.dev)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.5+-3178c6)](https://www.typescriptlang.org)
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 
-**[Live Demo](https://dyingangel666.github.io/ng-prism/demo/?component=ButtonComponent)** · **[Documentation](https://dyingangel666.github.io/ng-prism/)**
+**[Live Demo](https://ng-prism.github.io/ng-prism/demo/?component=ButtonComponent)** · **[Documentation](https://ng-prism.github.io/ng-prism/)**
 
 ## Features
 
-- **Zero-config discovery** — TypeScript Compiler API scans your library at build time
-- **Signal-native** — works with `input()` / `output()` signals
-- **Directive support** — showcase directives with configurable host elements
-- **Plugin architecture** — JSDoc, A11y, Figma, Performance, Box Model, Coverage
-- **Live Controls** — auto-generated input controls with type-aware editors
-- **Code Snippets** — live-updating Angular template snippets per variant
-- **Component Pages** — free-form demo pages for complex components
-- **Deep-linking** — URL state sync for sharing specific component/variant/view
-- **Themeable** — full CSS custom property system, replaceable UI sections
+- **Zero-config discovery**: TypeScript Compiler API scans your library at build time
+- **Signal-native**: works with `input()` / `output()` signals
+- **Directive support**: showcase directives with configurable host elements
+- **Plugin architecture**: JSDoc, A11y, Figma, Performance, Box Model, Coverage
+- **Live Controls**: auto-generated input controls with type-aware editors
+- **Code Snippets**: live-updating Angular template snippets per variant
+- **Component Pages**: free-form demo pages for complex components
+- **Deep-linking**: URL state sync for sharing specific component/variant/view
+- **Themeable**: full CSS custom property system, replaceable UI sections
 
 ## Quick Start
 
@@ -70,7 +70,7 @@ This creates the prism app project, configures Angular builders, and generates `
 ng run my-lib:prism
 ```
 
-Open `http://localhost:4400` — your component appears in the sidebar with live controls, code snippets, and variant tabs.
+Open `http://localhost:4400`. Your component appears in the sidebar with live controls, code snippets, and variant tabs.
 
 ## Configuration
 
@@ -142,7 +142,7 @@ Link to a `@Showcase`-decorated component for combined API docs + custom renderi
 | Coverage  | `@ng-prism/plugin-coverage`          | Per-component test coverage from Istanbul/v8                  |
 | VRT       | `@ng-prism/plugin-visual-regression` | Per-variant visual regression report from a screenshot runner |
 
-> **Note:** Accessibility auditing (axe-core) is built into ng-prism core — no plugin needed.
+> **Note:** Accessibility auditing (axe-core) is built into ng-prism core, so no plugin is needed.
 
 ## Requirements
 

package/dist/app/canvas/canvas-bg.styles.d.ts

@@ -2,18 +2,13 @@
  * What each `CanvasBg` value paints, shared by the Playground stage
  * (`prism-renderer`) and the Overview cells (`prism-overview-cell`).
  *
- * Append this as the **last** entry of a component's `styles` array. The
- * selectors are bare attribute selectors, so after Angular's encapsulation
- * rewrite they carry the same specificity as the `.some-stage` class rule they
- * have to override — source order is what decides, and only last place gets it
- * right.
+ * Must be the last entry of a component's `styles` array. After encapsulation
+ * these attribute selectors have the same specificity as the `.some-stage`
+ * class rule they override, so source order decides.
  *
- * The consuming element supplies its own `background-color`; `light` and `dark`
- * override it, the rest leave it alone.
- *
- * Capture mode is unaffected by where these rules live: `CAPTURE_STYLES` in
- * `prism-capture.service.ts` is a global stylesheet using `!important`, which
- * beats any component-scoped rule regardless.
+ * The consuming element supplies its own `background-color`; only `light` and
+ * `dark` override it. Capture mode is unaffected: `CAPTURE_STYLES` is a global
+ * stylesheet using `!important`.
  */
-export declare const CANVAS_BG_STYLES = "\n  [data-bg=\"dots\"] {\n    background-image: radial-gradient(circle, var(--prism-dot) 1px, transparent 1px);\n    background-size: 20px 20px;\n  }\n\n  [data-bg=\"plain\"] {\n    background-image: none;\n  }\n\n  /* Flat, not dotted. \"light\" and \"dark\" name a surface a component was\n     designed against \u2014 and they are the two backgrounds whose colour is\n     absolute rather than a theme token, which is what makes them the values\n     to declare for a screenshot baseline. \"dots\" already exists for anyone\n     who wants the grid. */\n  /* These two also re-point --prism-measure, and that is not decoration.\n     Every other canvas overlay is drawn in a theme colour over a theme\n     surface, so the two move together. These two backgrounds are absolute:\n     \"light\" stays near-white while the app runs the dark theme, and \"dark\"\n     stays near-black while it runs the light one. The measurement colour\n     picked for one theme is then sitting on the other theme's ground \u2014\n     measured, the dark theme's blue reaches 1.8:1 on the light background,\n     which is a viewport overlay you cannot see. Pinning the colour to the\n     ground rather than to the theme is what makes \"always visible\" true\n     instead of true-in-the-common-case.\n\n     Literal values because this file is theme-independent by construction \u2014\n     it is the one place that already hard-codes the two absolute grounds\n     below, for the same reason. Keep them in step with --prism-measure in\n     prism-default-theme.ts; semantic-colours.spec.ts fails if they drift. */\n  [data-bg=\"light\"] {\n    background-color: var(--prism-void-light, #f7f5fc);\n    background-image: none;\n    --prism-measure: #004d8a;\n  }\n  [data-bg=\"dark\"] {\n    background-color: var(--prism-void-dark, #07050f);\n    background-image: none;\n    --prism-measure: #41bcff;\n  }\n\n  /* \"transparent\" shares the checkerboard on purpose. The two say the same\n     thing in the two media the canvas has: while browsing, the checkerboard\n     is already the UI's word for \"no surface here\"; in a capture it becomes\n     literal transparency. A stage that were really see-through in the app\n     would just show the shell through the canvas, which means nothing. The\n     split between the two lives entirely in CAPTURE_STYLES. */\n  [data-bg=\"checker\"],\n  [data-bg=\"transparent\"] {\n    background-image:\n      linear-gradient(45deg, var(--prism-border) 25%, transparent 25%),\n      linear-gradient(-45deg, var(--prism-border) 25%, transparent 25%),\n      linear-gradient(45deg, transparent 75%, var(--prism-border) 75%),\n      linear-gradient(-45deg, transparent 75%, var(--prism-border) 75%);\n    background-size: 16px 16px;\n    background-position: 0 0, 0 8px, 8px -8px, -8px 0;\n  }\n";
+export declare const CANVAS_BG_STYLES = "\n  [data-bg=\"dots\"] {\n    background-image: radial-gradient(circle, var(--prism-dot) 1px, transparent 1px);\n    background-size: 20px 20px;\n  }\n\n  [data-bg=\"plain\"] {\n    background-image: none;\n  }\n\n  /* Flat, not dotted. \"light\" and \"dark\" name the surface a component was\n     designed against, and their colour is absolute rather than a theme token,\n     which makes them the values to declare for a screenshot baseline. Use\n     \"dots\" for the grid. */\n  /* These two also re-point --prism-measure. Other overlays use theme colours\n     on theme surfaces, but these grounds ignore the theme: \"light\" stays\n     near-white in the dark theme and \"dark\" stays near-black in the light one.\n     The dark theme's magenta reaches only 2.85:1 on the light ground, under the\n     4.5:1 its 9px readout needs, so the measurement colour has to follow the\n     ground, not the theme.\n\n     --prism-measure-plate follows it for the same reason. It is the surface\n     the measuring tool's value label paints itself on, so the label reads as a\n     gap in the measurement line rather than a badge on top of it. At its\n     --prism-stage fallback it would be the theme's stage under a re-pointed\n     foreground: the light theme's magenta on the dark theme's stage reads\n     3.71:1, the dark theme's on white 3.08:1. Pinned to the ground the same way,\n     the pairs reach 4.54:1 and 6.57:1. A color-mix against the ground would\n     work too, but this file already states both grounds literally, and one\n     mechanism per decision is enough.\n\n     Literal values because this file is theme-independent, like the two\n     grounds below. Keep them in step with --prism-measure in\n     prism-default-theme.ts; semantic-colours.spec.ts fails if they drift. */\n  [data-bg=\"light\"] {\n    background-color: var(--prism-void-light, #f7f5fc);\n    background-image: none;\n    --prism-measure: #ca00c1;\n    --prism-measure-plate: var(--prism-void-light, #f7f5fc);\n  }\n  [data-bg=\"dark\"] {\n    background-color: var(--prism-void-dark, #07050f);\n    background-image: none;\n    --prism-measure: #f632ff;\n    --prism-measure-plate: var(--prism-void-dark, #07050f);\n  }\n\n  /* \"transparent\" shares the checkerboard. In the app the checkerboard is\n     already the UI's sign for \"no surface\", and a see-through stage would only\n     show the shell behind it. Only CAPTURE_STYLES tells the two apart. */\n  [data-bg=\"checker\"],\n  [data-bg=\"transparent\"] {\n    background-image:\n      linear-gradient(45deg, var(--prism-border) 25%, transparent 25%),\n      linear-gradient(-45deg, var(--prism-border) 25%, transparent 25%),\n      linear-gradient(45deg, transparent 75%, var(--prism-border) 75%),\n      linear-gradient(-45deg, transparent 75%, var(--prism-border) 75%);\n    background-size: 16px 16px;\n    background-position: 0 0, 0 8px, 8px -8px, -8px 0;\n  }\n";
 //# sourceMappingURL=canvas-bg.styles.d.ts.map

package/dist/app/canvas/canvas-bg.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas-bg.styles.d.ts","sourceRoot":"","sources":["../../../src/app/canvas/canvas-bg.styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,wwFAyD5B,CAAC"}
+{"version":3,"file":"canvas-bg.styles.d.ts","sourceRoot":"","sources":["../../../src/app/canvas/canvas-bg.styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,62FA4D5B,CAAC"}

package/dist/app/canvas/canvas-bg.styles.js

@@ -2,18 +2,13 @@
  * What each `CanvasBg` value paints, shared by the Playground stage
  * (`prism-renderer`) and the Overview cells (`prism-overview-cell`).
  *
- * Append this as the **last** entry of a component's `styles` array. The
- * selectors are bare attribute selectors, so after Angular's encapsulation
- * rewrite they carry the same specificity as the `.some-stage` class rule they
- * have to override — source order is what decides, and only last place gets it
- * right.
+ * Must be the last entry of a component's `styles` array. After encapsulation
+ * these attribute selectors have the same specificity as the `.some-stage`
+ * class rule they override, so source order decides.
  *
- * The consuming element supplies its own `background-color`; `light` and `dark`
- * override it, the rest leave it alone.
- *
- * Capture mode is unaffected by where these rules live: `CAPTURE_STYLES` in
- * `prism-capture.service.ts` is a global stylesheet using `!important`, which
- * beats any component-scoped rule regardless.
+ * The consuming element supplies its own `background-color`; only `light` and
+ * `dark` override it. Capture mode is unaffected: `CAPTURE_STYLES` is a global
+ * stylesheet using `!important`.
  */
 export const CANVAS_BG_STYLES = `
   [data-bg="dots"] {
@@ -25,43 +20,46 @@ export const CANVAS_BG_STYLES = `
     background-image: none;
   }
 
-  /* Flat, not dotted. "light" and "dark" name a surface a component was
-     designed against — and they are the two backgrounds whose colour is
-     absolute rather than a theme token, which is what makes them the values
-     to declare for a screenshot baseline. "dots" already exists for anyone
-     who wants the grid. */
-  /* These two also re-point --prism-measure, and that is not decoration.
-     Every other canvas overlay is drawn in a theme colour over a theme
-     surface, so the two move together. These two backgrounds are absolute:
-     "light" stays near-white while the app runs the dark theme, and "dark"
-     stays near-black while it runs the light one. The measurement colour
-     picked for one theme is then sitting on the other theme's ground —
-     measured, the dark theme's blue reaches 1.8:1 on the light background,
-     which is a viewport overlay you cannot see. Pinning the colour to the
-     ground rather than to the theme is what makes "always visible" true
-     instead of true-in-the-common-case.
+  /* Flat, not dotted. "light" and "dark" name the surface a component was
+     designed against, and their colour is absolute rather than a theme token,
+     which makes them the values to declare for a screenshot baseline. Use
+     "dots" for the grid. */
+  /* These two also re-point --prism-measure. Other overlays use theme colours
+     on theme surfaces, but these grounds ignore the theme: "light" stays
+     near-white in the dark theme and "dark" stays near-black in the light one.
+     The dark theme's magenta reaches only 2.85:1 on the light ground, under the
+     4.5:1 its 9px readout needs, so the measurement colour has to follow the
+     ground, not the theme.
+
+     --prism-measure-plate follows it for the same reason. It is the surface
+     the measuring tool's value label paints itself on, so the label reads as a
+     gap in the measurement line rather than a badge on top of it. At its
+     --prism-stage fallback it would be the theme's stage under a re-pointed
+     foreground: the light theme's magenta on the dark theme's stage reads
+     3.71:1, the dark theme's on white 3.08:1. Pinned to the ground the same way,
+     the pairs reach 4.54:1 and 6.57:1. A color-mix against the ground would
+     work too, but this file already states both grounds literally, and one
+     mechanism per decision is enough.
 
-     Literal values because this file is theme-independent by construction —
-     it is the one place that already hard-codes the two absolute grounds
-     below, for the same reason. Keep them in step with --prism-measure in
+     Literal values because this file is theme-independent, like the two
+     grounds below. Keep them in step with --prism-measure in
      prism-default-theme.ts; semantic-colours.spec.ts fails if they drift. */
   [data-bg="light"] {
     background-color: var(--prism-void-light, #f7f5fc);
     background-image: none;
-    --prism-measure: #004d8a;
+    --prism-measure: #ca00c1;
+    --prism-measure-plate: var(--prism-void-light, #f7f5fc);
   }
   [data-bg="dark"] {
     background-color: var(--prism-void-dark, #07050f);
     background-image: none;
-    --prism-measure: #41bcff;
+    --prism-measure: #f632ff;
+    --prism-measure-plate: var(--prism-void-dark, #07050f);
   }
 
-  /* "transparent" shares the checkerboard on purpose. The two say the same
-     thing in the two media the canvas has: while browsing, the checkerboard
-     is already the UI's word for "no surface here"; in a capture it becomes
-     literal transparency. A stage that were really see-through in the app
-     would just show the shell through the canvas, which means nothing. The
-     split between the two lives entirely in CAPTURE_STYLES. */
+  /* "transparent" shares the checkerboard. In the app the checkerboard is
+     already the UI's sign for "no surface", and a see-through stage would only
+     show the shell behind it. Only CAPTURE_STYLES tells the two apart. */
   [data-bg="checker"],
   [data-bg="transparent"] {
     background-image:

package/dist/app/canvas/measure-geometry.d.ts

@@ -0,0 +1,140 @@
+import { type MeasurePoint } from '../../shared/measure.type.js';
+/**
+ * A measured value as text, without a unit.
+ *
+ * The caller appends the unit: the primary measurement carries `px` like the
+ * viewport dimension line does, the four-sided readout does not, because
+ * four `px` in a small space is noise.
+ */
+export declare function formatMeasure(cssPx: number): string;
+export interface Vec {
+    x: number;
+    y: number;
+}
+/** A measurement, reduced to exactly what the template draws. */
+export interface RenderedLine {
+    a: Vec;
+    b: Vec;
+    tickA: [Vec, Vec];
+    tickB: [Vec, Vec];
+    label: Vec;
+    text: string;
+    pinned: boolean;
+    /**
+     * The snapped-to edges, retraced as a dotted line (Spec §4.4).
+     *
+     * Without them you can see *that* the tool latched, but not *onto what*
+     * — and with a 2px border, the border, padding and content edges sit
+     * exactly 2 pixels apart. Which one was meant is otherwise impossible to
+     * tell. Always empty for the alt-hover quad readout: a span between two
+     * elements has no single snapped-to edge to retrace.
+     */
+    echoes: Array<[Vec, Vec]>;
+}
+/**
+ * A zoom that is never 0.
+ *
+ * The same guard the renderer template gives the viewport grips with
+ * `canvasService.zoom() || 1`. A division by zero here produces no visible
+ * problem but an invisible one: `NaN` in an SVG attribute is silently
+ * discarded, and the measurement simply vanishes.
+ *
+ * Exported rather than private because `measure-quad.ts` divides by zoom
+ * too. It used to carry its own `|| 1`, which let a negative zoom straight
+ * through and mirrored the measurement instead of dropping it — two guards
+ * that disagree are worse than one, so there is only one.
+ */
+export declare function safeZoom(zoom: number): number;
+/** Screen point -> `.demo-wrap`-local CSS pixels. */
+export declare function toLocal(screen: Vec, origin: Vec, zoom: number): Vec;
+/** The reverse of {@link toLocal}. */
+export declare function toScreen(local: Vec, origin: Vec, zoom: number): Vec;
+/**
+ * Viewport coordinates -> the overlay host's own box.
+ *
+ * Every rect the measuring tool reads — `.demo-wrap`'s for the projection
+ * origin, the specimen's for the label reference point, an element's for the
+ * four-sided readout — comes out of `getBoundingClientRect()` and is
+ * therefore measured from the top-left corner of the *window*. Nothing the
+ * overlay draws lives in that space: the SVG is `inset: 0` on the host, so
+ * its user coordinates start at the host's top-left corner, and `.m-label`
+ * is placed with `left`/`top` against the same corner. The shell puts a
+ * header above the stage and a sidebar beside it, so handing a viewport
+ * coordinate straight to the template pushes every line, tick, echo and
+ * label down and to the right by the stage's screen offset — largely off
+ * the visible area, while the stored numbers stay perfectly correct.
+ *
+ * Pure, and taking the host rect rather than reading one, because jsdom has
+ * no layout engine: every rect it reports is zero, so a test routed through
+ * the DOM could not tell this subtraction from its absence. The same seam
+ * `watchGeometry` opens for `ResizeObserver` in the component.
+ */
+export declare function toHostSpace(point: Vec, hostRect: {
+    left: number;
+    top: number;
+}): Vec;
+export declare function measureDistance(a: Vec, b: Vec): number;
+/** The two ends of the tick at point `at`, perpendicular to the line. */
+export declare function tickEndpoints(a: Vec, b: Vec, at: 'a' | 'b'): [Vec, Vec];
+/**
+ * Where the value sits.
+ *
+ * At the midpoint, as long as the line is long enough. Below that,
+ * perpendicular to the line, on the side that points away from `awayFrom` —
+ * otherwise the number lands directly on what it describes for short spans
+ * inside a single component.
+ */
+export declare function labelPlacement(a: Vec, b: Vec, awayFrom: Vec): Vec;
+/**
+ * `point`, pulled onto whichever of the eight 45-degree directions from `a` it
+ * lies nearest.
+ *
+ * Held while dragging, this is what makes an exactly horizontal, vertical or
+ * diagonal measurement reachable by hand — the same service Shift performs in
+ * Photoshop, Illustrator and Figma, which is where the reach for that key
+ * comes from.
+ *
+ * The projection is orthogonal rather than length-preserving: the component
+ * across the chosen direction is dropped, not folded into the result. A drag
+ * 240 across and 7 down therefore reports 240, which is the distance along the
+ * line actually drawn. Preserving the raw length instead would print the
+ * hypotenuse beside a line that is not the hypotenuse.
+ *
+ * Order matters at the call site. Edge snapping runs first and this runs on
+ * its result, so the snap's contribution on the preserved axis survives: a
+ * point latched to a left edge at x=338 and then forced horizontal stays at
+ * x=338. Constraining first and snapping afterwards would bend the line back
+ * off the axis the constraint was asked for.
+ */
+export declare function constrainDirection(a: Vec, point: MeasurePoint): MeasurePoint;
+/**
+ * `point` with every axis the document did not pin rounded to a whole CSS
+ * pixel.
+ *
+ * The decimals a free measurement shows are not sub-pixel geometry — they are
+ * the specimen's own offset leaking into the reading. `.demo-wrap` is centred
+ * in the stage, so its left edge sits at something like 824.3594, and a point
+ * that latched onto nothing is the cursor minus exactly that. The fraction
+ * therefore describes where the specimen happens to sit, which is of no
+ * interest, and it appears on practically every free drag.
+ *
+ * Rounding per axis rather than per point is what keeps this from throwing
+ * away the fractions that *are* real. `pointAt` only ever pins one axis: a
+ * point latched to a left edge takes that edge's exact x while its y is still
+ * the raw cursor carrying the same offset. Measured against the shipped
+ * fixtures, a fifth of the distances between a parent and its child are
+ * genuinely fractional — a toggle knob centred at 2.5px in its track, an
+ * avatar's glyph sitting 6.8281 from one side and 6.8438 from the other.
+ * Rounding those away would hide the asymmetry a ruler exists to reveal.
+ *
+ * In CSS pixels, not screen pixels: at 200% zoom one whole CSS pixel is two
+ * screen pixels, and a whole pixel should mean what the readout prints.
+ *
+ * Deliberately not applied after {@link constrainDirection}. Projecting onto a
+ * diagonal multiplies by √2/2, so a constrained endpoint is fractional by
+ * construction and the length between two whole points on a 45-degree line is
+ * irrational anyway. Rounding there would trade the exact angle Shift just
+ * promised for a tidier number.
+ */
+export declare function quantizeFree(point: MeasurePoint): MeasurePoint;
+//# sourceMappingURL=measure-geometry.d.ts.map

package/dist/app/canvas/measure-geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-geometry.d.ts","sourceRoot":"","sources":["../../../src/app/canvas/measure-geometry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqE,KAAK,YAAY,EAAgB,MAAM,8BAA8B,CAAC;AAElJ;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAInD;AAED,MAAM,WAAW,GAAG;IAChB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IACzB,CAAC,EAAE,GAAG,CAAC;IACP,CAAC,EAAE,GAAG,CAAC;IACP,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAClB,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAClB,KAAK,EAAE,GAAG,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;;;OAQG;IACH,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAInE;AAED,sCAAsC;AACtC,wBAAgB,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAInE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,GAAG,CAEpF;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAEtD;AAiBD,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CASvE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,GAAG,GAAG,CASjE;AA2CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,CAa5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAU9D"}

package/dist/app/canvas/measure-geometry.js

@@ -0,0 +1,217 @@
+import { MEASURE_LABEL_MIN_SPAN, MEASURE_LABEL_OFFSET, MEASURE_TICK_LENGTH } from '../../shared/measure.type.js';
+/**
+ * A measured value as text, without a unit.
+ *
+ * The caller appends the unit: the primary measurement carries `px` like the
+ * viewport dimension line does, the four-sided readout does not, because
+ * four `px` in a small space is noise.
+ */
+export function formatMeasure(cssPx) {
+    const rounded = Math.round(cssPx * 10) / 10;
+    return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+}
+/**
+ * A zoom that is never 0.
+ *
+ * The same guard the renderer template gives the viewport grips with
+ * `canvasService.zoom() || 1`. A division by zero here produces no visible
+ * problem but an invisible one: `NaN` in an SVG attribute is silently
+ * discarded, and the measurement simply vanishes.
+ *
+ * Exported rather than private because `measure-quad.ts` divides by zoom
+ * too. It used to carry its own `|| 1`, which let a negative zoom straight
+ * through and mirrored the measurement instead of dropping it — two guards
+ * that disagree are worse than one, so there is only one.
+ */
+export function safeZoom(zoom) {
+    return zoom > 0 && Number.isFinite(zoom) ? zoom : 1;
+}
+/** Screen point -> `.demo-wrap`-local CSS pixels. */
+export function toLocal(screen, origin, zoom) {
+    const z = safeZoom(zoom);
+    return { x: (screen.x - origin.x) / z, y: (screen.y - origin.y) / z };
+}
+/** The reverse of {@link toLocal}. */
+export function toScreen(local, origin, zoom) {
+    const z = safeZoom(zoom);
+    return { x: origin.x + local.x * z, y: origin.y + local.y * z };
+}
+/**
+ * Viewport coordinates -> the overlay host's own box.
+ *
+ * Every rect the measuring tool reads — `.demo-wrap`'s for the projection
+ * origin, the specimen's for the label reference point, an element's for the
+ * four-sided readout — comes out of `getBoundingClientRect()` and is
+ * therefore measured from the top-left corner of the *window*. Nothing the
+ * overlay draws lives in that space: the SVG is `inset: 0` on the host, so
+ * its user coordinates start at the host's top-left corner, and `.m-label`
+ * is placed with `left`/`top` against the same corner. The shell puts a
+ * header above the stage and a sidebar beside it, so handing a viewport
+ * coordinate straight to the template pushes every line, tick, echo and
+ * label down and to the right by the stage's screen offset — largely off
+ * the visible area, while the stored numbers stay perfectly correct.
+ *
+ * Pure, and taking the host rect rather than reading one, because jsdom has
+ * no layout engine: every rect it reports is zero, so a test routed through
+ * the DOM could not tell this subtraction from its absence. The same seam
+ * `watchGeometry` opens for `ResizeObserver` in the component.
+ */
+export function toHostSpace(point, hostRect) {
+    return { x: point.x - hostRect.left, y: point.y - hostRect.top };
+}
+export function measureDistance(a, b) {
+    return Math.hypot(b.x - a.x, b.y - a.y);
+}
+/**
+ * Direction and normal of the line.
+ *
+ * The length falls to 0 for two identical points; the normal is then set to
+ * horizontal so the ticks have a defined direction instead of `NaN`.
+ */
+function basis(a, b) {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const len = Math.hypot(dx, dy);
+    if (len === 0)
+        return { nx: 0, ny: 1, len: 0 };
+    return { nx: -dy / len, ny: dx / len, len };
+}
+/** The two ends of the tick at point `at`, perpendicular to the line. */
+export function tickEndpoints(a, b, at) {
+    const { nx, ny } = basis(a, b);
+    const p = at === 'a' ? a : b;
+    const h = MEASURE_TICK_LENGTH / 2;
+    return [
+        { x: p.x - nx * h, y: p.y - ny * h },
+        { x: p.x + nx * h, y: p.y + ny * h }
+    ];
+}
+/**
+ * Where the value sits.
+ *
+ * At the midpoint, as long as the line is long enough. Below that,
+ * perpendicular to the line, on the side that points away from `awayFrom` —
+ * otherwise the number lands directly on what it describes for short spans
+ * inside a single component.
+ */
+export function labelPlacement(a, b, awayFrom) {
+    const { nx, ny, len } = basis(a, b);
+    const mid = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+    if (len >= MEASURE_LABEL_MIN_SPAN)
+        return mid;
+    const sign = (awayFrom.x - mid.x) * nx + (awayFrom.y - mid.y) * ny > 0 ? -1 : 1;
+    return { x: mid.x + nx * MEASURE_LABEL_OFFSET * sign, y: mid.y + ny * MEASURE_LABEL_OFFSET * sign };
+}
+/**
+ * The eight directions a constrained measurement may take, as exact unit
+ * vectors.
+ *
+ * Written out rather than computed from `Math.cos`/`Math.sin`, because
+ * `Math.cos(Math.PI / 2)` is 6.1e-17 and not zero. That residue would leave a
+ * "vertical" measurement a hair off vertical — invisible on screen, but it
+ * would make the guarantee this function exists to provide quietly false, and
+ * every test of it would have to be written in tolerances instead of equality.
+ */
+const DIRECTIONS = [
+    { x: 1, y: 0 },
+    { x: Math.SQRT1_2, y: Math.SQRT1_2 },
+    { x: 0, y: 1 },
+    { x: -Math.SQRT1_2, y: Math.SQRT1_2 },
+    { x: -1, y: 0 },
+    { x: -Math.SQRT1_2, y: -Math.SQRT1_2 },
+    { x: 0, y: -1 },
+    { x: Math.SQRT1_2, y: -Math.SQRT1_2 }
+];
+/**
+ * The snap reference `point` may keep once it has been projected along `u`.
+ *
+ * A constraint forces one coordinate and preserves the other, so a latched
+ * edge survives only when it lies on the preserved axis: forcing `y` keeps a
+ * `left`/`right` edge, forcing `x` keeps a `top`/`bottom` one. A diagonal
+ * moves the point on both axes at once and leaves it on no edge at all.
+ *
+ * Dropping it matters because the reference is what draws the dotted snap
+ * echo. Carried over unchecked, the echo would mark an edge the point has
+ * just been moved off — the tool would claim a precision it no longer has.
+ */
+function keptSnap(snap, u) {
+    if (!snap)
+        return null;
+    if (u.y === 0)
+        return snap.side === 'left' || snap.side === 'right' ? snap : null;
+    if (u.x === 0)
+        return snap.side === 'top' || snap.side === 'bottom' ? snap : null;
+    return null;
+}
+/**
+ * `point`, pulled onto whichever of the eight 45-degree directions from `a` it
+ * lies nearest.
+ *
+ * Held while dragging, this is what makes an exactly horizontal, vertical or
+ * diagonal measurement reachable by hand — the same service Shift performs in
+ * Photoshop, Illustrator and Figma, which is where the reach for that key
+ * comes from.
+ *
+ * The projection is orthogonal rather than length-preserving: the component
+ * across the chosen direction is dropped, not folded into the result. A drag
+ * 240 across and 7 down therefore reports 240, which is the distance along the
+ * line actually drawn. Preserving the raw length instead would print the
+ * hypotenuse beside a line that is not the hypotenuse.
+ *
+ * Order matters at the call site. Edge snapping runs first and this runs on
+ * its result, so the snap's contribution on the preserved axis survives: a
+ * point latched to a left edge at x=338 and then forced horizontal stays at
+ * x=338. Constraining first and snapping afterwards would bend the line back
+ * off the axis the constraint was asked for.
+ */
+export function constrainDirection(a, point) {
+    const dx = point.x - a.x;
+    const dy = point.y - a.y;
+    // `atan2(0, 0)` is 0, which would silently pin a not-yet-moved drag to the
+    // horizontal. There is no direction to snap to yet.
+    if (dx === 0 && dy === 0)
+        return point;
+    const octant = (Math.round(Math.atan2(dy, dx) / (Math.PI / 4)) + 8) % 8;
+    const u = DIRECTIONS[octant];
+    const along = dx * u.x + dy * u.y;
+    return { x: a.x + along * u.x, y: a.y + along * u.y, snap: keptSnap(point.snap, u) };
+}
+/**
+ * `point` with every axis the document did not pin rounded to a whole CSS
+ * pixel.
+ *
+ * The decimals a free measurement shows are not sub-pixel geometry — they are
+ * the specimen's own offset leaking into the reading. `.demo-wrap` is centred
+ * in the stage, so its left edge sits at something like 824.3594, and a point
+ * that latched onto nothing is the cursor minus exactly that. The fraction
+ * therefore describes where the specimen happens to sit, which is of no
+ * interest, and it appears on practically every free drag.
+ *
+ * Rounding per axis rather than per point is what keeps this from throwing
+ * away the fractions that *are* real. `pointAt` only ever pins one axis: a
+ * point latched to a left edge takes that edge's exact x while its y is still
+ * the raw cursor carrying the same offset. Measured against the shipped
+ * fixtures, a fifth of the distances between a parent and its child are
+ * genuinely fractional — a toggle knob centred at 2.5px in its track, an
+ * avatar's glyph sitting 6.8281 from one side and 6.8438 from the other.
+ * Rounding those away would hide the asymmetry a ruler exists to reveal.
+ *
+ * In CSS pixels, not screen pixels: at 200% zoom one whole CSS pixel is two
+ * screen pixels, and a whole pixel should mean what the readout prints.
+ *
+ * Deliberately not applied after {@link constrainDirection}. Projecting onto a
+ * diagonal multiplies by √2/2, so a constrained endpoint is fractional by
+ * construction and the length between two whole points on a 45-degree line is
+ * irrational anyway. Rounding there would trade the exact angle Shift just
+ * promised for a tidier number.
+ */
+export function quantizeFree(point) {
+    const side = point.snap?.side;
+    const xPinned = side === 'left' || side === 'right';
+    const yPinned = side === 'top' || side === 'bottom';
+    return {
+        x: xPinned ? point.x : Math.round(point.x),
+        y: yPinned ? point.y : Math.round(point.y),
+        snap: point.snap
+    };
+}

package/dist/app/canvas/measure-keyboard.d.ts

@@ -0,0 +1,20 @@
+import type { Vec } from './measure-geometry.js';
+/**
+ * The moved point — or `null` when the key does not belong here.
+ *
+ * Tab is deliberately not one of `nudge`'s keys. Spec §10 reserves it for
+ * stepping through the specimen's snap targets — the accessible substitute
+ * for the pointer, and arguably the more precise input, not a consolation
+ * prize for lacking one: edges are exactly what one wants to measure in the
+ * first place. Arrow keys only come in afterwards, to nudge off an edge once
+ * a free point is what's wanted; `nudge` only ever moves a point that
+ * already exists, it does not place one. Someone will eventually be tempted
+ * to fold Tab in here as "simpler" free-pixel movement — resist it, and see
+ * `onKey` in the component for why returning `null` here (rather than the
+ * unchanged point) is what makes that possible to resist safely.
+ *
+ * The step sizes are the pair Spec §10 fixes for this tool: 1px plain, 10px
+ * with Shift.
+ */
+export declare function nudge(point: Vec, key: string, shift: boolean): Vec | null;
+//# sourceMappingURL=measure-keyboard.d.ts.map

package/dist/app/canvas/measure-keyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-keyboard.d.ts","sourceRoot":"","sources":["../../../src/app/canvas/measure-keyboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAKjD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,GAAG,GAAG,IAAI,CAezE"}

package/dist/app/canvas/measure-keyboard.js

@@ -0,0 +1,34 @@
+const STEP = 1;
+const STEP_COARSE = 10;
+/**
+ * The moved point — or `null` when the key does not belong here.
+ *
+ * Tab is deliberately not one of `nudge`'s keys. Spec §10 reserves it for
+ * stepping through the specimen's snap targets — the accessible substitute
+ * for the pointer, and arguably the more precise input, not a consolation
+ * prize for lacking one: edges are exactly what one wants to measure in the
+ * first place. Arrow keys only come in afterwards, to nudge off an edge once
+ * a free point is what's wanted; `nudge` only ever moves a point that
+ * already exists, it does not place one. Someone will eventually be tempted
+ * to fold Tab in here as "simpler" free-pixel movement — resist it, and see
+ * `onKey` in the component for why returning `null` here (rather than the
+ * unchanged point) is what makes that possible to resist safely.
+ *
+ * The step sizes are the pair Spec §10 fixes for this tool: 1px plain, 10px
+ * with Shift.
+ */
+export function nudge(point, key, shift) {
+    const d = shift ? STEP_COARSE : STEP;
+    switch (key) {
+        case 'ArrowRight':
+            return { x: point.x + d, y: point.y };
+        case 'ArrowLeft':
+            return { x: point.x - d, y: point.y };
+        case 'ArrowDown':
+            return { x: point.x, y: point.y + d };
+        case 'ArrowUp':
+            return { x: point.x, y: point.y - d };
+        default:
+            return null;
+    }
+}