@pygmalionjs/pygmalion 0.19.0 → 0.20.0

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

@@ -0,0 +1,60 @@
+import type { StoryboardEnvironment } from './designImport.js';
+/**
+ * One value of a catalog condition axis.
+ *
+ * The environment is what the value means to the browser: boot storage,
+ * permissions, devices, an opaque screen preset. It is merged into the
+ * storyboard baseline, so every capture fingerprint, flow session and
+ * Application run re-resolves under it. An option without an environment is a
+ * pure catalog choice and leaves existing capture identities untouched.
+ */
+export interface CatalogConditionAxisOptionDef {
+    value: string;
+    label: string;
+    description?: string;
+    environment?: StoryboardEnvironment;
+}
+/**
+ * One independent condition the whole catalog can be seen under.
+ *
+ * A session preset is a single runtime choice; a preview environment control
+ * dresses only the live preview. Products also have flags that cut across both:
+ * a color scheme, an account level, a feature entitlement. Each is its own axis
+ * with stable value ids. Screens say in `conditions` which values they exist
+ * under; a screen that names no axis exists under every value of it.
+ *
+ * Without `defaultValue` an unselected axis constrains nothing, the same way the
+ * legacy "Default" session shows every runtime. With one, the default is the
+ * effective value from the start.
+ */
+export interface CatalogConditionAxisDef {
+    id: string;
+    label: string;
+    description?: string;
+    defaultValue?: string;
+    options: readonly CatalogConditionAxisOptionDef[];
+}
+/** Explicit selections only; defaults stay implicit. */
+export type CatalogConditionSelections = Readonly<Record<string, string>>;
+/** Values, per axis id, a screen exists under. Absent axes mean every value. */
+export type ScreenConditionDeclaration = Readonly<Record<string, readonly string[]>>;
+/**
+ * One editor's declared condition axes, the explicit selections, and the
+ * environment they contribute to the storyboard baseline.
+ */
+export declare function createConditionAxes(deps: {
+    setStoryboardBaselineEnvironment(environment?: StoryboardEnvironment): void;
+}): {
+    setConditionAxes: (next: readonly CatalogConditionAxisDef[]) => void;
+    getConditionAxes: () => readonly CatalogConditionAxisDef[];
+    getConditionAxisValue: (axisId: string) => string | null | undefined;
+    getConditionAxisSelections: () => CatalogConditionSelections;
+    selectConditionAxisValue: (axisId: string, value: string | null) => void;
+    clearConditionAxisSelections: () => void;
+    getConditionAxesEnvironment: () => StoryboardEnvironment | undefined;
+    isInSelectedConditions: (conditions: ScreenConditionDeclaration | undefined) => boolean;
+    conditionDeclarationIssues: (conditions: ScreenConditionDeclaration | undefined) => string[];
+    subscribeConditionAxes: (listener: () => void) => () => void;
+    getConditionAxesRevision: () => number;
+};
+export type ConditionAxes = ReturnType<typeof createConditionAxes>;

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

@@ -1,11 +1,13 @@
+import { type ScreenConditionDeclaration } from './conditionAxes.js';
+import type { StoryboardEnvironment } from './designImport.js';
 export declare function createEditorDeclarations(): {
     setPreviewDependencyDigests: (routes: readonly {
         path?: string;
         dependencyDigest?: string;
     }[] | null) => void;
     previewDependencyDigest: (route: string) => string | undefined;
-    routePreviewFrameRecipe: (page: import("./previewBootstrap.js").PreviewFramePage, baselineEnvironment?: import("./designImport.js").StoryboardEnvironment) => import("./previewBootstrap.js").RoutePreviewFrameRecipe;
-    createRoutePreviewFrameFingerprint: (page: import("./previewBootstrap.js").PreviewFramePage, previewRevision: string, baselineEnvironment?: import("./designImport.js").StoryboardEnvironment) => string;
+    routePreviewFrameRecipe: (page: import("./previewBootstrap.js").PreviewFramePage, baselineEnvironment?: StoryboardEnvironment) => import("./previewBootstrap.js").RoutePreviewFrameRecipe;
+    createRoutePreviewFrameFingerprint: (page: import("./previewBootstrap.js").PreviewFramePage, previewRevision: string, baselineEnvironment?: StoryboardEnvironment) => string;
     setDesignImportController: (controller: import("./designImport.js").DesignImportController | null) => void;
     getDesignImportController: () => import("./designImport.js").DesignImportController | null;
     setSurfaceClassifications: (classifications: readonly import("./surfaceDemands.js").SurfaceClassification[] | undefined) => void;
@@ -20,17 +22,32 @@ export declare function createEditorDeclarations(): {
     subscribeStoryboardGraph: (listener: () => void) => () => void;
     bumpPreviewIdentityEpoch: () => void;
     getPreviewIdentityEpoch: () => number;
-    setStoryboardBaselineEnvironment: (environment?: import("./designImport.js").StoryboardEnvironment) => void;
-    getStoryboardBaselineEnvironment: () => import("./designImport.js").StoryboardEnvironment | undefined;
+    setStoryboardBaselineEnvironment: (environment?: StoryboardEnvironment) => void;
+    getStoryboardBaselineEnvironment: () => StoryboardEnvironment | undefined;
     setPreviewEnvironmentControls: (next: readonly import("./previewEnvironmentControls.js").PreviewEnvironmentControlDef[]) => void;
     getPreviewEnvironmentControls: () => readonly import("./previewEnvironmentControls.js").PreviewEnvironmentControlDef[];
     getPreviewEnvironmentControlSelections: () => Readonly<Record<string, string>>;
     getPreviewEnvironmentControlValue: (controlId: string) => string | undefined;
     setPreviewEnvironmentControlValue: (controlId: string, value: string) => void;
     clearPreviewEnvironmentControlValues: () => void;
-    getPreviewEnvironmentOverride: () => import("./designImport.js").StoryboardEnvironment | undefined;
+    getPreviewEnvironmentOverride: () => StoryboardEnvironment | undefined;
     subscribePreviewEnvironmentControls: (listener: () => void) => () => void;
     getPreviewEnvironmentControlRevision: () => number;
+    isPageInSelectedConditions: (page: {
+        runtimes?: readonly string[];
+        conditions?: ScreenConditionDeclaration;
+    }) => boolean;
+    setConditionAxes: (next: readonly import("./conditionAxes.js").CatalogConditionAxisDef[]) => void;
+    getConditionAxes: () => readonly import("./conditionAxes.js").CatalogConditionAxisDef[];
+    getConditionAxisValue: (axisId: string) => string | null | undefined;
+    getConditionAxisSelections: () => import("./conditionAxes.js").CatalogConditionSelections;
+    selectConditionAxisValue: (axisId: string, value: string | null) => void;
+    clearConditionAxisSelections: () => void;
+    getConditionAxesEnvironment: () => StoryboardEnvironment | undefined;
+    isInSelectedConditions: (conditions: ScreenConditionDeclaration | undefined) => boolean;
+    conditionDeclarationIssues: (conditions: ScreenConditionDeclaration | undefined) => string[];
+    subscribeConditionAxes: (listener: () => void) => () => void;
+    getConditionAxesRevision: () => number;
     setSessionPresets: (next: readonly import("./sessionPresets.js").SessionPresetDef[]) => void;
     getSessionPresets: () => import("./sessionPresets.js").SessionPresetDef[];
     getSelectedSessionPreset: () => number | null;

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

@@ -258,6 +258,12 @@ export interface DesignImportPage {
      * runtime — only the screens a runtime cannot reach at all need to say so.
      */
     runtimes?: readonly string[];
+    /**
+     * Values, per condition axis id, this screen exists under. An absent axis
+     * means every value of it; unknown ids or values hide the screen and are
+     * reported as declaration issues rather than passing silently.
+     */
+    conditions?: Readonly<Record<string, readonly string[]>>;
     scenarioId?: string;
     /**
      * Every scenario this screen demonstrates. Coverage is the whole set; the
@@ -400,6 +406,12 @@ export interface DesignImportInitialPage {
      * runtime — only the screens a runtime cannot reach at all need to say so.
      */
     runtimes?: readonly string[];
+    /**
+     * Values, per condition axis id, this screen exists under. An absent axis
+     * means every value of it; unknown ids or values hide the screen and are
+     * reported as declaration issues rather than passing silently.
+     */
+    conditions?: Readonly<Record<string, readonly string[]>>;
     scenarioId?: string;
     /** Every authored scenario this initial screen demonstrates. */
     scenarioIds?: readonly string[];

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

@@ -7,6 +7,7 @@ import type { FrameBranchKindDef, FrameLabelLabels } from './frameLabels.js';
 import type { ScreenLaneDef } from './frameLanes.js';
 import { type ScreenStateAxisDef } from './interactiveStates.js';
 import type { PreviewEnvironmentControlDef } from './previewEnvironmentControls.js';
+import type { CatalogConditionAxisDef } from './conditionAxes.js';
 import type { RegistryEntry } from './registry.js';
 import type { ScenarioCoverageClaim } from './scenarioCoverage.js';
 import type { ScreenCardDef } from './screenCards.js';
@@ -55,6 +56,8 @@ export interface PygmalionRevisionCatalogV1 {
     viewportPresets?: readonly ViewportPresetDef[];
     sessionPresets?: readonly SessionPresetDef[];
     previewEnvironmentControls?: readonly PreviewEnvironmentControlDef[];
+    /** Independent catalog conditions every screen, capture and run resolves under. */
+    conditionAxes?: readonly CatalogConditionAxisDef[];
     screenFlows?: readonly ScreenFlowPath[];
     scenarioCoverage?: readonly ScenarioCoverageClaim[];
     screenDimensions?: readonly ScreenDimensionDef[];

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

@@ -4,6 +4,7 @@ import type { FrameBranchKindDef, FrameLabelLabels } from './frameLabels.js';
 import type { ScreenLaneDef } from './frameLanes.js';
 import type { ScreenStateAxisDef } from './interactiveStates.js';
 import type { PreviewEnvironmentControlDef } from './previewEnvironmentControls.js';
+import type { CatalogConditionAxisDef } from './conditionAxes.js';
 import type { ComponentRegistry, RegistryEntry } from './registry.js';
 import type { ScenarioCoverageClaim } from './scenarioCoverage.js';
 import type { ScreenCardDef } from './screenCards.js';
@@ -27,6 +28,7 @@ export interface RevisionCatalogDeclarations {
     viewportPresets?: readonly ViewportPresetDef[];
     sessionPresets?: readonly SessionPresetDef[];
     previewEnvironmentControls?: readonly PreviewEnvironmentControlDef[];
+    conditionAxes?: readonly CatalogConditionAxisDef[];
     screenFlows?: readonly ScreenFlowPath[];
     scenarioCoverage?: readonly ScenarioCoverageClaim[];
     screenDimensions?: readonly ScreenDimensionDef[];

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

@@ -205,6 +205,12 @@ export interface PageModel {
      * a runtime cannot reach at all need to say so.
      */
     runtimes?: readonly string[];
+    /**
+     * Values, per condition axis id, this screen exists under. An absent axis
+     * means every value of it; unknown ids or values hide the screen and are
+     * reported as declaration issues rather than passing silently.
+     */
+    conditions?: Readonly<Record<string, readonly string[]>>;
     scenarioId?: string;
     /** Every scenario the screen demonstrates; coverage counts this set. */
     scenarioIds?: readonly string[];

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

@@ -2,6 +2,11 @@ import type { StoryboardEnvironment } from './designImport.js';
 export declare const STORYBOARD_ENVIRONMENT_QUERY: "__pygmalion_environment";
 export declare const STORYBOARD_ENVIRONMENT_CONTROL: "/__pygmalion-storyboard/environment";
 export declare function mergeStoryboardEnvironment(base?: StoryboardEnvironment, override?: StoryboardEnvironment): StoryboardEnvironment | undefined;
+/**
+ * Drops record keys the merge left empty so a composed environment reads, and
+ * hashes, the same as one declared directly. `undefined` when nothing remains.
+ */
+export declare function compactStoryboardEnvironment(environment?: StoryboardEnvironment): StoryboardEnvironment | undefined;
 /**
  * Boot-time environment derived from a screen preset — parity with the Node
  * capture runtime's init script, which installs the preset global and seeds

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

@@ -174,6 +174,8 @@ export { SourceRefControl } from './ui/SourceRefControl.js';
 export type { SourceRefControlProps } from './ui/SourceRefControl.js';
 export type { TokenDef } from './editor/tokens.js';
 import type { SessionPresetDef } from './editor/sessionPresets.js';
+import type { CatalogConditionAxisDef } from './editor/conditionAxes.js';
+export type { CatalogConditionAxisDef, CatalogConditionAxisOptionDef, CatalogConditionSelections, ScreenConditionDeclaration, } from './editor/conditionAxes.js';
 export type { ViewportPresetDef } from './editor/viewportPresets.js';
 export type { SessionPresetDef } from './editor/sessionPresets.js';
 export { GENERIC_ASSERTION_SHARE, MIN_UNVERIFIED_REASON_LENGTH, detectStateGroupCandidates, hooksInSelector, summarizeConditionCoverage, validateHookTargeting, validateScreenConformance, } from './editor/screenConformance.js';
@@ -237,6 +239,13 @@ export interface PygmalionEditorProps {
     sessionPresets?: readonly SessionPresetDef[];
     /** Host-declared browser conditions shown in the active frame's Preview inspector. */
     previewEnvironmentControls?: readonly PreviewEnvironmentControlDef[];
+    /**
+     * Independent catalog conditions — a color scheme, an account level — that
+     * every screen, capture and run resolves under. Screens name the values they
+     * exist in through `conditions`; an option's environment joins the storyboard
+     * baseline so captures re-resolve when the value changes.
+     */
+    conditionAxes?: readonly CatalogConditionAxisDef[];
     /** A public importer that provides unified control over code inventory and importing of entire DOM layers. */
     designImport?: DesignImportController;
     /** Called with cumulative changes when editing a token in the Assets panel — the host is responsible for writing back (file saving). */

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

@@ -1,7 +1,7 @@
 import type { EditorDeclarations } from '../editor/declarations.js';
 
 export interface WorkspaceConditionsProps {
-    declarations: Pick<EditorDeclarations, 'getSessionPresets' | 'getSelectedSessionPreset' | 'selectSessionPreset' | 'subscribeSessionPresets' | 'getPreviewEnvironmentControls' | 'getPreviewEnvironmentControlValue' | 'getPreviewEnvironmentControlSelections' | 'setPreviewEnvironmentControlValue' | 'clearPreviewEnvironmentControlValues' | 'subscribePreviewEnvironmentControls' | 'getPreviewEnvironmentControlRevision'>;
+    declarations: Pick<EditorDeclarations, 'getSessionPresets' | 'getSelectedSessionPreset' | 'selectSessionPreset' | 'subscribeSessionPresets' | 'getConditionAxes' | 'getConditionAxisValue' | 'getConditionAxisSelections' | 'selectConditionAxisValue' | 'clearConditionAxisSelections' | 'subscribeConditionAxes' | 'getConditionAxesRevision' | 'getPreviewEnvironmentControls' | 'getPreviewEnvironmentControlValue' | 'getPreviewEnvironmentControlSelections' | 'setPreviewEnvironmentControlValue' | 'clearPreviewEnvironmentControlValues' | 'subscribePreviewEnvironmentControls' | 'getPreviewEnvironmentControlRevision'>;
 }
 /** Present declared catalog sessions and preview values without interpreting product policy. */
 export declare function WorkspaceConditions({ declarations }: WorkspaceConditionsProps): import("react").JSX.Element | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "Apache-2.0",
   "repository": {