@ng-prism/core 22.3.0 → 22.4.1

package/dist/app/services/prism-capture.service.js

@@ -8,133 +8,66 @@ const STYLE_ELEMENT_ID = 'ng-prism-capture-styles';
 /**
  * Everything capture mode makes see-through for `bg: 'transparent'`.
  *
- * A screenshot tool clips the *composited* page, so a transparent stage alone
- * buys nothing: the wrappers behind it keep painting and the PNG comes back
- * opaque. The stage and every ancestor that paints have to go at once, which
- * is why this is one selector rather than a rule per layer.
- *
- * `html` and `body` are insurance rather than observation — ng-prism paints
- * neither, but a consuming app's global stylesheet can, and the guarantee this
- * makes is "nothing opaque between the component and the document root".
- * Above `html` the backdrop is the browser's own and no stylesheet reaches it;
- * a runner has to clear that with `omitBackground: true`.
- *
- * `prism-shell` is the *host element* the app bootstraps into, not the
- * `div.prism-shell` inside its template — both are in the chain and either can
- * be given a background, a `:host` rule being the easy way to do it by
- * accident. `.prism-body` is the grid between the shell and `.prism-main` and
- * is listed on the same insurance grounds.
- *
- * Scoped by `:has()` to a *transparent* stage, so the other five backgrounds
- * behave exactly as before. Exported so a test can assert the invariant
- * against the real DOM rather than against this list — the list is the
- * fragile part of the feature. A renamed wrapper or a newly introduced
- * painting layer turns the capture opaque again, and an opaque capture still
- * looks correct; it just silently stops testing transparency.
+ * A screenshot tool clips the composited page, so the stage and every painting
+ * ancestor must clear together or the PNG comes back opaque. `html`, `body`,
+ * the `prism-shell` host element and `.prism-body` are insurance: ng-prism
+ * paints none of them, but an app stylesheet or a `:host` rule can. The
+ * browser's own backdrop above `html` needs `omitBackground: true` in the runner.
+ *
+ * Scoped by `:has()` to a transparent stage so the other backgrounds are
+ * untouched. Exported so a test can check it against the real DOM: a renamed
+ * wrapper or a new painting layer makes captures opaque again, and an opaque
+ * capture still looks correct.
  */
 export const CAPTURE_TRANSPARENT_SELECTOR = `[${CAPTURE_ATTRIBUTE}] .prism-canvas-stage[data-bg='transparent'],\n` +
     `[${CAPTURE_ATTRIBUTE}] :is(html, body, prism-shell, .prism-shell, .prism-body, .prism-main, .prism-canvas-wrap):has(.prism-canvas-stage[data-bg='transparent'])`;
 /**
  * Everything capture mode removes from layout so the canvas owns the viewport.
  *
- * The canvas is not an overlay host: `.prism-canvas-wrap` is one flex sibling
- * among several inside `.prism-main`, which is itself one grid cell of
- * `.prism-body` inside `.prism-shell`. A screenshot tool captures the *screen
- * coordinates* of `.demo-wrap`, and `.demo-wrap` is centred in a stage that
- * scrolls — so whenever the component is larger than the canvas viewport, its
- * box extends past the canvas and the compositor fills those coordinates with
- * whichever sibling lives there. Measured in Chromium against the real
- * stylesheets, a 200x400 component at a 1280x720 viewport leaks 57px upwards
- * into the variant ribbon and 121px downwards into the panel. That is neither
- * a z-order nor a clipping bug: the capture target legitimately extends beyond
- * its scroll container and the page paints something there.
- *
- * `display: none` rather than `visibility: hidden`, and this is the one thing
- * not to "simplify" later. Keeping the layout box is the tempting minimal-churn
- * fix — nothing re-centres, no unaffected baseline moves — and it does not
- * work: the box still occupies its space, so what paints at those coordinates
- * becomes `.prism-main`'s own background instead of the panel. Measured at the
- * bottom row of a `bg: 'transparent'` capture: `#11284e` with the panel left
- * alone, `#11284e` with `visibility: hidden`, transparent only once the panel
- * leaves layout. The canvas is `flex: 1`; it has to reclaim the space for the
- * stage to paint there, and only removal from layout gives it back.
+ * Runners screenshot the screen coordinates of `.demo-wrap`, which is centred
+ * in a scrolling stage. A component larger than the canvas extends past it,
+ * and whichever sibling region paints there (ribbon, panel) leaks into the image.
  *
- * Written as a structural rule rather than a list of chrome selectors, because
- * enumeration is what makes this class of bug recur: the list has to be revised
- * every time the shell grows a region, nothing fails when it is not, and the
- * baselines recorded in the meantime look perfectly fine while guarding the
- * wrong image. At every level from the shell to the canvas wrap, the one child
- * that leads to the stage survives and every sibling is removed, so a region
- * added tomorrow is suppressed without anyone remembering this file exists.
+ * Use `display: none`, not `visibility: hidden`: a hidden box keeps its space
+ * and `.prism-main`'s background paints there instead. The canvas is `flex: 1`
+ * and only gets the space back once its siblings leave layout.
  *
- * The track collapses are not cosmetic. `.prism-shell` and `.prism-body` are
- * grids with sized tracks (`52px 1fr`, `var(--sw) 4px 1fr`); hiding the header
- * and the sidebar without collapsing them would auto-place the survivor into
- * the *first* track and render the canvas 52px tall or 264px wide.
+ * Structural rather than a list of chrome selectors: at each level from the
+ * shell to the canvas wrap, the child leading to the stage survives and every
+ * sibling goes, so a new shell region is covered without touching this file.
+ * The grid track overrides in `CAPTURE_STYLES` are required too: without them
+ * the survivor lands in the first sized track and the canvas renders 52px tall
+ * or 264px wide.
  *
- * Scoped by `:has(.prism-canvas-stage)` throughout: a component page or a view
- * panel has no canvas, and blanking the shell around it would leave a runner
- * with an empty screenshot rather than an honest one.
+ * Scoped by `:has(.prism-canvas-stage)`: a component page or view panel has no
+ * canvas, and blanking the shell there would give an empty screenshot.
  */
 const CAPTURE_CANVAS_ONLY_SELECTOR = `[${CAPTURE_ATTRIBUTE}] ` + `:is(.prism-shell, .prism-body, .prism-main, .prism-canvas-wrap)` + `:has(.prism-canvas-stage) > :not(:has(.prism-canvas-stage))`;
 /**
  * Global stylesheet applied in capture mode.
  *
- * This has to be a document-level stylesheet rather than a component `styles`
- * block: Angular's emulated view encapsulation scopes component styles to that
- * component's own content attribute, so a rule written inside the renderer
- * could never reach into the dynamically created showcase component to stop
- * *its* transitions and animations.
- *
- * Stripping `background-image` is what makes the canvas capture-safe without
- * flattening it to one colour. Every `data-bg` value is a background *colour*
- * plus, for all but `plain`, a repeating *pattern* — dots or a checkerboard.
- * The colour is what `@Showcase({ bg })` declares and is deterministic; the
- * pattern is not, because the component is centred, so the pattern's phase
- * beneath it shifts whenever the component changes size and every pixel behind
- * it differs after an unrelated resize. `!important` is required: the stage's
- * own rules are component-scoped and therefore more specific than this one.
- *
- * `transparent` is the one value that drops the colour too, and it cannot do
- * that on the stage alone — see {@link CAPTURE_TRANSPARENT_SELECTOR} for the
- * layers involved. Alpha is not what the paragraph above rules out: a pattern
- * has a phase that moves when the component resizes, an alpha channel is a
- * per-pixel value that does not.
- *
- * Colour is only half of it. The rules from
- * {@link CAPTURE_CANVAS_ONLY_SELECTOR} down hand the whole viewport to the
- * canvas, which is what makes the declared background reach the *whole* of the
- * capture target's box rather than only the part that happens to fit inside
- * the canvas viewport.
- *
- * The stage's padding goes with them, and it buys more than the 32px it looks
- * like. The stage is `height: 100%` under `content-box`, so its padding lands
- * *outside* that height: the stage is 64px taller than the row it sits in,
- * overflows it, and centres the component 32px below the true centre of what
- * is actually painted. Dropping the padding makes the stage exactly the canvas
- * and the component's centre the viewport's centre, which turns the guarantee
- * crisp — a component is contained iff it fits the viewport. Measured: a
- * 200x700 component at 1280x720 still leaks 22px past the canvas with the
- * regions gone but the padding kept. None of that padding is ever inside a
- * `.demo-wrap` screenshot, so nothing is lost by removing it.
- *
- * The stage's edge goes with them, and it is stripped rather than reshaped for
- * the same reason it exists in that shape at all. The edge is deliberately
- * built from `outline` plus `box-shadow` and never from a border or padding,
- * because neither participates in layout: `plugin-visual-regression`
- * screenshots `.demo-wrap`, which is centred in the stage, and a border would
- * shrink the stage's content box by 2px and move that centre, shifting every
- * recorded baseline without a component having changed. Not participating in
- * layout is not the same as not painting. `outline-offset: -1px` draws the
- * line *inside* the border box, and with the padding above gone the stage edge
- * sits flush against the component, so for anything whose `.demo-wrap` reaches
- * it that 1px line and the shadow under it composite straight into the
- * screenshot. So capture mode removes the paint and leaves the geometry
- * untouched — the same division of labour the edge was chosen for, and the
- * only one that keeps both halves of the guarantee.
- *
- * {@link CAPTURE_TRANSPARENT_SELECTOR} cannot cover this: it clears background
- * colour, and an outline is not a background.
+ * Document-level because emulated encapsulation would stop a renderer rule from
+ * reaching the dynamically created showcase component's transitions and
+ * animations.
+ *
+ * `background-image` is stripped because the dot/checker pattern's phase shifts
+ * whenever the centred component resizes; the declared colour is deterministic
+ * and stays. `!important` is required to beat the component-scoped stage rules.
+ * `transparent` also drops the colour, across the layers in
+ * {@link CAPTURE_TRANSPARENT_SELECTOR}; alpha is per-pixel and does not shift.
+ * The rules from {@link CAPTURE_CANVAS_ONLY_SELECTOR} down give the canvas the
+ * whole viewport, so the background covers the capture target's whole box.
+ *
+ * The stage padding goes too. The stage is `height: 100%` under `content-box`,
+ * so the padding makes it 64px taller than its row and centres the component
+ * 32px too low. Without it the stage is the canvas, and a component is
+ * contained iff it fits the viewport.
+ *
+ * The stage edge is `outline` plus `box-shadow`, never a border, so it does not
+ * move `.demo-wrap`'s centre and shift baselines. It still paints, and with the
+ * padding gone it sits flush against the component, so capture mode removes the
+ * paint and keeps the geometry. {@link CAPTURE_TRANSPARENT_SELECTOR} does not
+ * cover this: an outline is not a background.
  */
 const CAPTURE_STYLES = `
 [${CAPTURE_ATTRIBUTE}] *,
@@ -175,33 +108,20 @@ ${CAPTURE_CANVAS_ONLY_SELECTOR} {
 }
 `;
 /**
- * Capture-isolation mode.
- *
- * Screenshot tools clip the composited page to the capture target's box, so
- * anything painted behind or inside `.demo-wrap` ends up in the image. Capture
- * mode strips the canvas background down to its patternless colour — keeping
- * whatever `@Showcase({ bg })` declared, or clearing the whole paint chain to
- * real transparency for `bg: 'transparent'` — suppresses every piece of
- * canvas chrome, removes every other shell region from layout so the canvas
- * owns the viewport, locks zoom to 1 and freezes animation, so a variant
- * renders identically on every run.
- *
- * What that buys a runner is the right to screenshot `.demo-wrap` directly:
- * the target is composited against the declared background over its whole box,
- * not merely over the part that fits inside the canvas viewport. The one thing
- * the mode cannot do is make room that the viewport does not have — a
- * component larger than the viewport still overflows, and sizing the viewport
- * to fit is the runner's job.
- *
- * The flag is read once from the URL at construction time and never written
- * back — {@link PrismUrlStateService} rebuilds the query string from scratch,
- * so navigating inside the app drops `?capture=1` from the address bar while
- * the mode itself stays on for the lifetime of the document.
- *
- * Reading in the constructor (rather than during `PrismUrlStateService.init()`)
- * is deliberate: `PrismCanvasService` restores persisted zoom in *its* own
- * constructor, which can run first, so anything init-order dependent would
- * make zoom-locking racy.
+ * Capture-isolation mode, for external screenshot runners.
+ *
+ * Keeps the declared canvas colour but strips its pattern (or clears the whole
+ * paint chain for `bg: 'transparent'`), hides canvas chrome and every other
+ * shell region, locks zoom to 1 and freezes animation, so a variant renders the
+ * same on every run and a runner can screenshot `.demo-wrap` directly. It
+ * cannot make room the viewport lacks: sizing the viewport is the runner's job.
+ *
+ * The flag is read once from the URL in the constructor and never written back.
+ * {@link PrismUrlStateService} rebuilds the query string, so `?capture=1` leaves
+ * the address bar on navigation while the mode stays on. Reading it during
+ * `PrismUrlStateService.init()` instead would make zoom-locking racy:
+ * `PrismCanvasService` restores persisted zoom in its own constructor, which
+ * can run first.
  */
 export class PrismCaptureService {
     _active = signal(typeof window !== 'undefined' ? parseCaptureParam(window.location.search) : false, /* @ts-ignore */

package/dist/app/services/prism-measure.service.d.ts

@@ -0,0 +1,44 @@
+import type { Measurement, MeasurePoint } from '../../shared/measure.type.js';
+import * as i0 from "@angular/core";
+/**
+ * The transient state of the measuring tool.
+ *
+ * Deliberately separate from `PrismCanvasService`, which holds durable
+ * preferences: the toggle lives there, the measurements live here. None of
+ * this is persisted — rescuing a half-finished measurement across a reload
+ * would be a burden, not a convenience.
+ */
+export declare class PrismMeasureService {
+    private readonly navigation;
+    private readonly renderer;
+    private readonly canvas;
+    private readonly _draft;
+    private readonly _pins;
+    private readonly _hoverAnchor;
+    /** The measurement in progress, for as long as the pointer is down. */
+    readonly draft: import("@angular/core").Signal<Measurement | null>;
+    /** Pinned measurements, in the order they were set. */
+    readonly pins: import("@angular/core").Signal<readonly Measurement[]>;
+    /** The element fixed by click for alt-hover mode. */
+    readonly hoverAnchor: import("@angular/core").Signal<Element | null>;
+    constructor();
+    beginDraft(a: MeasurePoint): void;
+    updateDraft(b: MeasurePoint): void;
+    commitDraft(): void;
+    cancelDraft(): void;
+    removePin(index: number): void;
+    setHoverAnchor(element: Element | null): void;
+    /**
+     * What happens when the tool is switched off.
+     *
+     * Deliberately not `clearAll()`: the toggle is a mode, not a reset. Anyone
+     * who hits the rail by accident must not lose the pinned measurements —
+     * the running one, on the other hand, no longer makes sense without a
+     * pointer, and an anchor with no visible overlay even less so.
+     */
+    suspend(): void;
+    clearAll(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PrismMeasureService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+//# sourceMappingURL=prism-measure.service.d.ts.map

package/dist/app/services/prism-measure.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prism-measure.service.d.ts","sourceRoot":"","sources":["../../../src/app/services/prism-measure.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;;AAK9E;;;;;;;GAOG;AACH,qBACa,mBAAmB;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IAErD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgC;IAE7D,uEAAuE;IACvE,QAAQ,CAAC,KAAK,qDAA4B;IAE1C,uDAAuD;IACvD,QAAQ,CAAC,IAAI,yDAA2B;IAExC,qDAAqD;IACrD,QAAQ,CAAC,WAAW,iDAAkC;;IAmBtD,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI;IAIjC,WAAW,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI;IAIlC,WAAW,IAAI,IAAI;IAQnB,WAAW,IAAI,IAAI;IAInB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI9B,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI;IAI7C;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;IAKf,QAAQ,IAAI,IAAI;yCA5EP,mBAAmB;;CAiF/B"}

package/dist/app/services/prism-measure.service.js

@@ -0,0 +1,91 @@
+import { effect, inject, Injectable, signal } from '@angular/core';
+import { PrismCanvasService } from './prism-canvas.service.js';
+import { PrismNavigationService } from './prism-navigation.service.js';
+import { PrismRendererService } from './prism-renderer.service.js';
+import * as i0 from "@angular/core";
+/**
+ * The transient state of the measuring tool.
+ *
+ * Deliberately separate from `PrismCanvasService`, which holds durable
+ * preferences: the toggle lives there, the measurements live here. None of
+ * this is persisted — rescuing a half-finished measurement across a reload
+ * would be a burden, not a convenience.
+ */
+export class PrismMeasureService {
+    navigation = inject(PrismNavigationService);
+    renderer = inject(PrismRendererService);
+    canvas = inject(PrismCanvasService);
+    _draft = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_draft" }] : /* istanbul ignore next */ []));
+    _pins = signal([], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_pins" }] : /* istanbul ignore next */ []));
+    _hoverAnchor = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_hoverAnchor" }] : /* istanbul ignore next */ []));
+    /** The measurement in progress, for as long as the pointer is down. */
+    draft = this._draft.asReadonly();
+    /** Pinned measurements, in the order they were set. */
+    pins = this._pins.asReadonly();
+    /** The element fixed by click for alt-hover mode. */
+    hoverAnchor = this._hoverAnchor.asReadonly();
+    constructor() {
+        // The same mechanism by which PrismVariantBgService lets its override
+        // lapse. Both are statements about *this* variant.
+        effect(() => {
+            this.navigation.activeComponent();
+            this.renderer.activeVariantIndex();
+            this.clearAll();
+        });
+        // Hangs off the toggle, not the variant, which is why it calls
+        // `suspend()` instead of `clearAll()`.
+        effect(() => {
+            if (this.canvas.measure())
+                return;
+            this.suspend();
+        });
+    }
+    beginDraft(a) {
+        this._draft.set({ a, b: a });
+    }
+    updateDraft(b) {
+        this._draft.update((d) => (d ? { a: d.a, b } : null));
+    }
+    commitDraft() {
+        const draft = this._draft();
+        if (!draft)
+            return;
+        this._pins.update((pins) => [...pins, draft]);
+        this._draft.set(null);
+    }
+    cancelDraft() {
+        this._draft.set(null);
+    }
+    removePin(index) {
+        this._pins.update((pins) => pins.filter((_, i) => i !== index));
+    }
+    setHoverAnchor(element) {
+        this._hoverAnchor.set(element);
+    }
+    /**
+     * What happens when the tool is switched off.
+     *
+     * Deliberately not `clearAll()`: the toggle is a mode, not a reset. Anyone
+     * who hits the rail by accident must not lose the pinned measurements —
+     * the running one, on the other hand, no longer makes sense without a
+     * pointer, and an anchor with no visible overlay even less so.
+     */
+    suspend() {
+        this._draft.set(null);
+        this._hoverAnchor.set(null);
+    }
+    clearAll() {
+        this._draft.set(null);
+        this._pins.set([]);
+        this._hoverAnchor.set(null);
+    }
+    static ɵfac = function PrismMeasureService_Factory(__ngFactoryType__) { return new (__ngFactoryType__ || PrismMeasureService)(); };
+    static ɵprov = /*@__PURE__*/ i0.ɵɵdefineInjectable({ token: PrismMeasureService, factory: PrismMeasureService.ɵfac, providedIn: 'root' });
+}
+(() => { (typeof ngDevMode === "undefined" || ngDevMode) && i0.ɵsetClassMetadata(PrismMeasureService, [{
+        type: Injectable,
+        args: [{ providedIn: 'root' }]
+    }], () => [], null); })();

package/dist/app/services/prism-panel.service.d.ts

@@ -13,9 +13,9 @@ export declare class PrismPanelService {
     /**
      * Every panel that renders as a view tab, builtin before plugin.
      *
-     * Unfiltered on purpose: `prism-view-panel-host` resolves the active view
+     * Unfiltered because `prism-view-panel-host` resolves the active view
      * through this list. Filtering here would let the host come up empty for a
-     * frame whenever a component switch invalidates the active view — the
+     * frame whenever a component switch invalidates the active view, because the
      * fallback in `prism-shell` runs in the same change-detection round.
      */
     readonly viewPanels: import("@angular/core").Signal<PanelDefinition[]>;

package/dist/app/services/prism-panel.service.js

@@ -18,9 +18,9 @@ export class PrismPanelService {
     /**
      * Every panel that renders as a view tab, builtin before plugin.
      *
-     * Unfiltered on purpose: `prism-view-panel-host` resolves the active view
+     * Unfiltered because `prism-view-panel-host` resolves the active view
      * through this list. Filtering here would let the host come up empty for a
-     * frame whenever a component switch invalidates the active view — the
+     * frame whenever a component switch invalidates the active view, because the
      * fallback in `prism-shell` runs in the same change-detection round.
      */
     viewPanels = computed(() => [...this.builtinPanels.filter((p) => p.placement === 'view'), ...this.pluginService.viewPanels()], /* @ts-ignore */

package/dist/app/services/prism-persistence.service.js

@@ -23,7 +23,7 @@ export class PrismPersistenceService {
     init() {
         if (this.config.persistState === false)
             return;
-        // Capture mode must render a variant exactly as the manifest declares it;
+        // Capture mode must render a variant as the manifest declares it;
         // restoring a previous session's control values would silently change what
         // an external screenshot tool captures.
         if (this.capture.active())

package/dist/app/services/prism-renderer.service.js

@@ -136,7 +136,7 @@ export class PrismRendererService {
     }
     applyVariant(index, comp) {
         const { values, activeContent } = computeVariantState(comp, index, {
-            onUnknownInput: (variantName, key) => console.warn(`[ng-prism] Variant "${variantName}" references unknown input "${key}" on ${comp.meta.className} — ignoring.`)
+            onUnknownInput: (variantName, key) => console.warn(`[ng-prism] Variant "${variantName}" references unknown input "${key}" on ${comp.meta.className}, ignoring.`)
         });
         this.inputValues.set(values);
         this.activeContent.set(activeContent);

package/dist/app/services/prism-url-state.service.js

@@ -77,7 +77,7 @@ export class PrismUrlStateService {
     writeToUrl(item, variantIndex, viewId, panelId) {
         // Built from scratch, never from the current search string: parameters the
         // app does not own must not survive a navigation. `?capture=1` relies on
-        // this — see the "capture flag" specs, which pin the guarantee.
+        // this; the "capture flag" specs pin the guarantee.
         const params = new URLSearchParams();
         if (item?.kind === 'component') {
             params.set(PARAM_COMPONENT, item.data.meta.className);

package/dist/app/services/prism-variant-bg.service.d.ts

@@ -11,32 +11,18 @@ export declare class PrismVariantBgService {
     /**
      * The background the stage actually paints.
      *
-     * Capture mode keeps the *declared* background. `@Showcase({ bg })` and a
-     * per-variant `bg` exist precisely so a component is judged against the
-     * surface it was designed for — an outlined button on `dark` proves nothing
-     * when it is screenshotted on the light default — so a capture that dropped
-     * them would pin the wrong image.
+     * Capture mode uses the declared background, since a component must be
+     * judged on the surface it was designed for, and ignores the user override,
+     * which is session UI state and must not shape a baseline. Patterns are
+     * stripped separately in `CAPTURE_STYLES`.
      *
-     * What capture mode does drop is the manual user override: session UI state
-     * that must never decide what a baseline looks like. The other half of the
-     * determinism problem — the dot grid and the checkerboard, whose phase shifts
-     * under a centred component whenever that component changes size — is solved
-     * in `CAPTURE_STYLES`, which strips the pattern and leaves the colour. Colour
-     * is deterministic; the pattern is not.
+     * With nothing declared, capture uses {@link DEFAULT_VARIANT_BG}, not the
+     * canvas default: `dots` paints a theme token, so the baseline would depend
+     * on the runner's theme. It is also what the discovery manifest reports, so
+     * the reported and the captured background cannot drift apart.
      *
-     * With no declared bg capture mode lands on {@link DEFAULT_VARIANT_BG} rather
-     * than on the canvas default. `dots` would paint `--prism-bg-surface`, a
-     * *theme* token, so the surface behind an undeclared component would depend
-     * on whichever theme the runner's browser started in — a baseline that
-     * flips with a persisted UI preference. The fixed default is also exactly
-     * what the discovery manifest reports for the variant, so what a tool is
-     * told and what it screenshots cannot drift apart. That default is
-     * `transparent`, which removes the theme dependency outright instead of
-     * pinning one theme's colour: an undeclared variant has no opinion about its
-     * surface, and no surface is the honest capture of that.
-     *
-     * Interactive mode keeps `canvas.bg()`: there the dot grid on the themed
-     * surface is the point, and forcing `light` would break dark-theme browsing.
+     * Interactive mode keeps `canvas.bg()`: browsing wants the themed dot grid,
+     * and forcing `light` would break dark-theme browsing.
      */
     readonly effective: import("@angular/core").Signal<CanvasBg>;
     /** True when the user's override differs from the (non-null) recommended bg. */

package/dist/app/services/prism-variant-bg.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prism-variant-bg.service.d.ts","sourceRoot":"","sources":["../../../src/app/services/prism-variant-bg.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;;AAO/D,qBACa,qBAAqB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IAEvD,QAAQ,CAAC,WAAW,kDAKjB;IAEH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAC3D,QAAQ,CAAC,QAAQ,kDAA+B;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,SAAS,2CAEhB;IAEF,gFAAgF;IAChF,QAAQ,CAAC,WAAW,0CAKjB;;IAUH,WAAW,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI;IAI/B,aAAa,IAAI,IAAI;yCAtEZ,qBAAqB;;CAyEjC"}
+{"version":3,"file":"prism-variant-bg.service.d.ts","sourceRoot":"","sources":["../../../src/app/services/prism-variant-bg.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;;AAO/D,qBACa,qBAAqB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IAEvD,QAAQ,CAAC,WAAW,kDAKjB;IAEH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAC3D,QAAQ,CAAC,QAAQ,kDAA+B;IAEhD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,SAAS,2CAEhB;IAEF,gFAAgF;IAChF,QAAQ,CAAC,WAAW,0CAKjB;;IAUH,WAAW,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI;IAI/B,aAAa,IAAI,IAAI;yCAxDZ,qBAAqB;;CA2DjC"}

package/dist/app/services/prism-variant-bg.service.js

@@ -23,32 +23,18 @@ export class PrismVariantBgService {
     /**
      * The background the stage actually paints.
      *
-     * Capture mode keeps the *declared* background. `@Showcase({ bg })` and a
-     * per-variant `bg` exist precisely so a component is judged against the
-     * surface it was designed for — an outlined button on `dark` proves nothing
-     * when it is screenshotted on the light default — so a capture that dropped
-     * them would pin the wrong image.
+     * Capture mode uses the declared background, since a component must be
+     * judged on the surface it was designed for, and ignores the user override,
+     * which is session UI state and must not shape a baseline. Patterns are
+     * stripped separately in `CAPTURE_STYLES`.
      *
-     * What capture mode does drop is the manual user override: session UI state
-     * that must never decide what a baseline looks like. The other half of the
-     * determinism problem — the dot grid and the checkerboard, whose phase shifts
-     * under a centred component whenever that component changes size — is solved
-     * in `CAPTURE_STYLES`, which strips the pattern and leaves the colour. Colour
-     * is deterministic; the pattern is not.
+     * With nothing declared, capture uses {@link DEFAULT_VARIANT_BG}, not the
+     * canvas default: `dots` paints a theme token, so the baseline would depend
+     * on the runner's theme. It is also what the discovery manifest reports, so
+     * the reported and the captured background cannot drift apart.
      *
-     * With no declared bg capture mode lands on {@link DEFAULT_VARIANT_BG} rather
-     * than on the canvas default. `dots` would paint `--prism-bg-surface`, a
-     * *theme* token, so the surface behind an undeclared component would depend
-     * on whichever theme the runner's browser started in — a baseline that
-     * flips with a persisted UI preference. The fixed default is also exactly
-     * what the discovery manifest reports for the variant, so what a tool is
-     * told and what it screenshots cannot drift apart. That default is
-     * `transparent`, which removes the theme dependency outright instead of
-     * pinning one theme's colour: an undeclared variant has no opinion about its
-     * surface, and no surface is the honest capture of that.
-     *
-     * Interactive mode keeps `canvas.bg()`: there the dot grid on the themed
-     * surface is the point, and forcing `light` would break dark-theme browsing.
+     * Interactive mode keeps `canvas.bg()`: browsing wants the themed dot grid,
+     * and forcing `light` would break dark-theme browsing.
      */
     effective = computed(() => this.capture.active() ? (this.recommended() ?? DEFAULT_VARIANT_BG) : (this._override() ?? this.recommended() ?? this.canvas.bg()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "effective" }] : /* istanbul ignore next */ []));

package/dist/app/shared/prism-metric-badge.component.d.ts

@@ -2,21 +2,15 @@ import * as i0 from "@angular/core";
 /**
  * Library-wide metric badge for the header.
  *
- * Presentational only — it takes an already-formatted value and a variant and
- * knows nothing about thresholds, manifests or where the number came from.
- * That keeps the three badges that use it (a11y in core, coverage and visual
- * regression in their plugins) owning their own data logic while sharing one
- * appearance.
+ * Presentational only: it takes a formatted value and a variant, so each badge
+ * (a11y in core, coverage and visual regression in their plugins) keeps its own
+ * data logic while sharing one appearance.
  *
- * It carries an icon rather than a text label on purpose. The glyph is the
- * same one the source contributes to the navigation marks and its panel tab,
- * so one symbol means one source wherever it appears — and the badge gets
- * narrow enough that three of them fit a 40px header without crowding it.
- * The icon is `aria-hidden` — it is decoration, not content. The accessible
- * name is composed here as "label: value" (e.g. "Library coverage: 23%"), so
- * the figure that is the whole point of the badge cannot be dropped by a
- * consumer that only passes `label`. `title` stays the full text the
- * consumer passes, for the hover tooltip.
+ * It shows an icon instead of a text label: the same glyph the source uses for
+ * its navigation marks and panel tab, and narrow enough to fit three badges in
+ * the 40px header. The icon is `aria-hidden`; the accessible name is built here
+ * as "label: value" (e.g. "Library coverage: 23%") so a consumer cannot drop
+ * the figure. `title` is the consumer's full text for the hover tooltip.
  */
 export declare class PrismMetricBadgeComponent {
     readonly icon: import("@angular/core").InputSignal<string>;
@@ -24,7 +18,7 @@ export declare class PrismMetricBadgeComponent {
     readonly label: import("@angular/core").InputSignal<string>;
     readonly title: import("@angular/core").InputSignal<string>;
     readonly variant: import("@angular/core").InputSignal<"ok" | "warn" | "danger">;
-    /** "label: value" — the accessible name, so the figure is never dropped. */
+    /** "label: value" is the accessible name, so the figure is never dropped. */
     readonly accessibleName: import("@angular/core").Signal<string>;
     static ɵfac: i0.ɵɵFactoryDeclaration<PrismMetricBadgeComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<PrismMetricBadgeComponent, "prism-metric-badge", never, { "icon": { "alias": "icon"; "required": true; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": true; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;

package/dist/app/shared/prism-metric-badge.component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prism-metric-badge.component.d.ts","sourceRoot":"","sources":["../../../src/app/shared/prism-metric-badge.component.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAQa,yBAAyB;IAClC,QAAQ,CAAC,IAAI,8CAA4B;IACzC,QAAQ,CAAC,KAAK,8CAA4B;IAC1C,QAAQ,CAAC,KAAK,8CAA4B;IAC1C,QAAQ,CAAC,KAAK,8CAAqB;IACnC,QAAQ,CAAC,OAAO,gEAAyC;IAEzD,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,yCAAsD;yCARpE,yBAAyB;2CAAzB,yBAAyB;CASrC"}
+{"version":3,"file":"prism-metric-badge.component.d.ts","sourceRoot":"","sources":["../../../src/app/shared/prism-metric-badge.component.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;;GAYG;AACH,qBAQa,yBAAyB;IAClC,QAAQ,CAAC,IAAI,8CAA4B;IACzC,QAAQ,CAAC,KAAK,8CAA4B;IAC1C,QAAQ,CAAC,KAAK,8CAA4B;IAC1C,QAAQ,CAAC,KAAK,8CAAqB;IACnC,QAAQ,CAAC,OAAO,gEAAyC;IAEzD,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,yCAAsD;yCARpE,yBAAyB;2CAAzB,yBAAyB;CASrC"}