@pygmalionjs/pygmalion 0.5.25 → 0.5.28

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-Df_DH4UK.js";
+import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-fEKTwThA.js";
 export {
   s as FrozenRoutePreviewView,
   a as NodeModel,

package/dist-lib/types/editor/designImport.d.ts

@@ -183,6 +183,11 @@ export interface DesignImportPage {
     stateKind?: string;
     /** Host-declared situation group the canvas arranges the frame into. */
     lane?: string;
+    /**
+     * Runtimes this screen exists in, by session preset id. Absent means every
+     * runtime — only the screens a runtime cannot reach at all need to say so.
+     */
+    runtimes?: readonly string[];
     scenarioId?: string;
     /**
      * Every scenario this screen demonstrates. Coverage is the whole set; the
@@ -301,6 +306,11 @@ export interface DesignImportInitialPage {
     state?: string;
     stateKind?: string;
     lane?: string;
+    /**
+     * Runtimes this screen exists in, by session preset id. Absent means every
+     * runtime — only the screens a runtime cannot reach at all need to say so.
+     */
+    runtimes?: readonly string[];
     scenarioId?: string;
     interactions?: DesignScreenInteraction[];
     environment?: StoryboardEnvironment;

package/dist-lib/types/editor/screenConformance.d.ts

@@ -0,0 +1,166 @@
+/**
+ * What a screen declaration has to carry to be worth trusting.
+ *
+ * A declared screen is a claim: replay these steps and you arrive at this
+ * screen. Nothing checked the claim. A step whose selector had moved failed
+ * quietly, the capture went ahead from wherever it stood, and the frame shipped
+ * under the declared name — a screen nobody had ever seen, filed as the one they
+ * meant. Ten of seventy screens in the first host were in that state, including
+ * two the designer had been looking at for weeks.
+ *
+ * The floor here is that a declaration must be able to fail. Reviewing the
+ * declarations by eye does not scale and does not survive a refactor; a screen
+ * that cannot fail will eventually be wrong without saying so.
+ *
+ * The second rule is subtler and matters more over time. A screen may declare
+ * an assertion that proves only that the application booted — every screen in
+ * the catalog satisfies it — which reads as evidence in review and is none. That
+ * shape is recognizable without knowing what a host named its shared constant:
+ * an assertion that nearly every other screen also declares distinguishes
+ * nothing. So the check compares the declarations against each other rather
+ * than against a list of names, and stays useful in a codebase it has never
+ * seen.
+ */
+/** Reasons must say something; the surface ledger uses the same floor. */
+export declare const MIN_UNVERIFIED_REASON_LENGTH = 10;
+/**
+ * How many screens may share an assertion before it stops counting as evidence
+ * that you reached one of them.
+ *
+ * Expressed as a share of the catalog rather than a count, so it means the same
+ * thing for a catalog of twelve screens and one of three hundred.
+ */
+export declare const GENERIC_ASSERTION_SHARE = 0.5;
+export type ScreenConformanceKind = 
+/** Steps replay with nothing that could fail if they went elsewhere. */
+'no-arrival-evidence'
+/** Everything it asserts is asserted by most of the catalog. */
+ | 'generic-arrival-only'
+/** The host admitted the gap and said why. Informational. */
+ | 'unverified-declared';
+export interface ScreenConformanceFinding {
+    severity: 'error' | 'warning' | 'info';
+    kind: ScreenConformanceKind;
+    screenId: string;
+    message: string;
+    /** Where to declare the fix, named so the reader does not have to guess. */
+    fix: string;
+}
+interface ConformanceAssertion {
+    selector?: string;
+    text?: string;
+    attribute?: {
+        name?: string;
+        value?: string;
+    };
+}
+export interface ConformanceScreen {
+    id: string;
+    name?: string;
+    /** Steps replayed before the capture. */
+    interactions?: readonly unknown[];
+    assertions?: readonly ConformanceAssertion[];
+    /**
+     * An admission that this screen's arrival is not checked, and why. Held to
+     * the same floor as a surface verdict's reason: "later" is not a reason.
+     */
+    arrivalUnverified?: string;
+}
+/**
+ * Reads the catalog against itself.
+ *
+ * The host owns which screens exist and what proves each one; this only refuses
+ * to let a screen claim something nothing could contradict.
+ */
+export declare function validateScreenConformance(screens: readonly ConformanceScreen[], options?: {
+    genericShare?: number;
+}): ScreenConformanceFinding[];
+/**
+ * A test hook exists so something can aim at it. One that nothing aims at is
+ * not a hook, it is a comment that looks like contract — and the failure is
+ * silent in both directions. A hook nobody targets can be deleted by a refactor
+ * with no test going red; a target naming a hook that no longer exists fails
+ * only when that screen is next captured, which may be never.
+ *
+ * The host owns the source and hands over the hooks it found; this side owns the
+ * declarations and knows what they aim at. Neither could answer alone.
+ */
+export interface HookTargetingInput {
+    /** Hooks the product declares, as the host's own scan found them. */
+    hooks: readonly string[];
+    /** Selectors the declarations aim at — assertions, steps, axis requirements. */
+    targets: readonly string[];
+    /**
+     * Hooks answered some other way: named in a scenario test, or recorded as
+     * out of scope. Absent means nothing is excused.
+     */
+    answered?: readonly string[];
+}
+export type HookTargetingKind = 'hook-untargeted' | 'target-missing';
+export interface HookTargetingFinding {
+    severity: 'error';
+    kind: HookTargetingKind;
+    hook: string;
+    message: string;
+    fix: string;
+}
+/** Pulls hook names out of a selector, so `[data-testid="x"][y]` reads as `x`. */
+export declare function hooksInSelector(selector: string): string[];
+export declare function validateHookTargeting(input: HookTargetingInput): HookTargetingFinding[];
+/**
+ * Frames that should have been an axis.
+ *
+ * A frame is for a different screen in a flow; an axis is for the same screen
+ * held a different way. Hosts reach for a frame either way, because a frame is
+ * the thing they already know how to declare — and then the storyboard grows
+ * nodes that are not places, and the reader cannot tell a step from a variation.
+ *
+ * The signal is a group of screens that agree on route, flow, and scenario and
+ * differ only in the state they name, none of which says it is a branch of the
+ * others. That is one screen wearing several states, which is what the axis and
+ * the screen-states control exist for.
+ */
+export interface StateGroupScreen {
+    id: string;
+    name?: string;
+    route?: string;
+    flow?: string;
+    scenario?: string;
+    state?: string;
+    /** Set when the host already declares this as a branch of its group. */
+    stateKind?: string;
+}
+export interface StateGroupFinding {
+    severity: 'warning';
+    kind: 'axis-candidate';
+    screenIds: readonly string[];
+    message: string;
+    fix: string;
+}
+export declare function detectStateGroupCandidates(screens: readonly StateGroupScreen[]): StateGroupFinding[];
+/**
+ * Routes the catalog only ever shows working.
+ *
+ * Empty, slow, and failed are states a product spends real time in and a
+ * catalog almost never holds, because reaching one is not something a designer
+ * can click — so they go undrawn until a customer finds them. A route whose
+ * every screen boots on the default path is not proof that nothing else exists
+ * there; it is the absence of the question.
+ *
+ * This counts rather than judges: the host decides which routes deserve the
+ * other states, and only the host knows which requests a route even makes.
+ */
+export interface ConditionCoverageScreen {
+    id: string;
+    route?: string;
+    /** Boot conditions this screen declares (network outcomes, seeded storage). */
+    conditions?: number;
+}
+export interface ConditionCoverageRoute {
+    route: string;
+    screens: number;
+    /** Screens declaring at least one boot condition. */
+    conditioned: number;
+}
+export declare function summarizeConditionCoverage(screens: readonly ConditionCoverageScreen[]): ConditionCoverageRoute[];
+export {};

package/dist-lib/types/editor/sessionPresets.d.ts

@@ -16,6 +16,11 @@ import type { StoryboardEnvironment } from './designImport';
  * frames captured under the old one.
  */
 export interface SessionPresetDef {
+    /**
+     * Stable key a screen names to say it exists in this runtime. Labels are for
+     * reading and change; this does not.
+     */
+    id: string;
     /** Button text. The panel column is narrow, so keep it short. */
     label: string;
     /**
@@ -44,3 +49,16 @@ export declare function getSelectedSessionPreset(): number | null;
  */
 export declare function selectSessionPreset(index: number | null): void;
 export declare function subscribeSessionPresets(listener: () => void): () => void;
+/**
+ * Whether a screen belongs in the runtime currently selected.
+ *
+ * A screen that names no runtime exists in all of them — most do, and a product
+ * that ships one build should not have to say so 75 times. Naming runtimes is
+ * for the screens that only exist in some: an EMR-linked build has surfaces the
+ * standalone one cannot reach at all, and showing them side by side reads as a
+ * catalog of screens that do not exist.
+ *
+ * With no preset selected everything shows, because "the product's own default"
+ * is not a claim about which runtime is running.
+ */
+export declare function isInSelectedSessionPreset(runtimes: readonly string[] | undefined): boolean;

package/dist-lib/types/editor/store.d.ts

@@ -187,6 +187,12 @@ export interface PageModel {
     stateKind?: string;
     /** Host-declared situation group the frame is arranged into (see frameLanes). */
     lane?: string;
+    /**
+     * Runtimes this screen exists in, by session preset id. Absent means every
+     * runtime — most screens are the same product either way, and only the ones
+     * a runtime cannot reach at all need to say so.
+     */
+    runtimes?: readonly string[];
     scenarioId?: string;
     /** Every scenario the screen demonstrates; coverage counts this set. */
     scenarioIds?: readonly string[];
@@ -341,6 +347,14 @@ export declare class EditorStore {
     /** The group member holding the group's canvas slot, or null for non-groups. */
     shownScreenStateId(scenario: string, canvas: string): string | null;
     /** False only for state variants folded into the Screen states control. */
+    /**
+     * Whether the frame belongs in the runtime the panel is set to.
+     *
+     * An EMR-linked build has surfaces the standalone one cannot reach at all, so
+     * showing every frame under both runtimes reads as a catalog of screens that
+     * do not exist. A frame that names no runtime exists in all of them.
+     */
+    isInSelectedRuntime(page: PageModel): boolean;
     isScreenStateShown(page: PageModel): boolean;
     /** Swaps a folded variant into its group's canvas slot; the camera stays. */
     private revealScreenState;
@@ -476,6 +490,7 @@ export declare class EditorStore {
         state?: string;
         stateKind?: string;
         lane?: string;
+        runtimes?: readonly string[];
         scenarioId?: string;
         scenarioIds?: readonly string[];
         interactions?: DesignScreenInteraction[];

package/dist-lib/types/lib.d.ts

@@ -82,6 +82,8 @@ import { type SessionPresetDef } from './editor/sessionPresets';
 export type { ViewportPresetDef } from './editor/viewportPresets';
 export { getSelectedSessionPreset, getSessionPresets, selectSessionPreset, setSessionPresets, subscribeSessionPresets, } from './editor/sessionPresets';
 export type { SessionPresetDef } from './editor/sessionPresets';
+export { GENERIC_ASSERTION_SHARE, MIN_UNVERIFIED_REASON_LENGTH, detectStateGroupCandidates, hooksInSelector, summarizeConditionCoverage, validateHookTargeting, validateScreenConformance, } from './editor/screenConformance';
+export type { ConditionCoverageRoute, ConditionCoverageScreen, ConformanceScreen, HookTargetingFinding, HookTargetingInput, HookTargetingKind, ScreenConformanceFinding, ScreenConformanceKind, StateGroupFinding, StateGroupScreen, } from './editor/screenConformance';
 export { clearPreviewEnvironmentControlValues, getPreviewEnvironmentControlValue, getPreviewEnvironmentControls, getPreviewEnvironmentOverride, setPreviewEnvironmentControlValue, setPreviewEnvironmentControls, subscribePreviewEnvironmentControls, } from './editor/previewEnvironmentControls';
 export type { PreviewEnvironmentControlDef, PreviewEnvironmentControlOptionDef, } from './editor/previewEnvironmentControls';
 export { createDesignImportController, createDesignScreenCollection, DESIGN_IMPORT_KINDS, expandDesignScreenCasesViewports, expandDesignScreenCollectionViewports, mergeScreenPresets, } from './editor/designImport';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.5.25",
+  "version": "0.5.28",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {