@lssm/lib.contracts-spec 17.3.2

package/dist/versioning/release-utils.js

@@ -0,0 +1 @@
+import{compareVersions as o}from"./utils.js";function i(n){if(n.version)return n.version;const r=n.packages.map((e)=>e.version).filter((e)=>typeof e==="string");if(r.length===0)return null;return r.reduce((e,t)=>o(t,e)===1?t:e)}export function sortReleaseManifest(n){return[...n.releases].sort((r,e)=>{const t=new Date(e.date).getTime()-new Date(r.date).getTime();if(t!==0)return t;const a=i(r),s=i(e);if(a&&s)return o(s,a);if(a)return-1;if(s)return 1;return r.slug.localeCompare(e.slug)})}export function countUpgradePlanStepLevels(n){return n.reduce((r,e)=>{r[e.level]+=1;return r},{auto:0,assisted:0,manual:0})}export function dedupeUpgradePlanSteps(n){const r=new Map;for(const e of n){const t=r.get(e.id);if(!t){r.set(e.id,{...e,instructions:[...e.instructions],packages:e.packages?[...e.packages]:void 0,autofixes:e.autofixes?[...e.autofixes]:void 0});continue}t.instructions=Array.from(new Set([...t.instructions,...e.instructions]));t.packages=Array.from(new Set([...t.packages??[],...e.packages??[]]));t.autofixes=Array.from(new Map([...t.autofixes??[],...e.autofixes??[]].map((a)=>[a.id,a])).values())}return Array.from(r.values())}export function createAgentPromptBundles(n,r,e){return r.map((t)=>({agent:t,title:`Upgrade guide for ${t}`,prompt:e(t,n)}))}

package/dist/versioning/schema.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { AgentPromptBundle, AgentTarget, GeneratedReleaseManifest, GeneratedReleaseManifestEntry, MigrationInstruction, ReleaseAudienceKind, ReleaseCapsule, ReleaseCapsulePackage, ReleaseCapsuleValidation, ReleaseDetail, ReleaseEnforceOn, ReleaseImpactAudience, ReleaseIndex, ReleaseIndexEntry, UpgradeAutofix, UpgradeAutofixKind, UpgradePackageTarget, UpgradePlan, UpgradePlanStep, UpgradeStepLevel } from './release-types.js';
+import type { VersionBumpType } from './types.js';
+export declare const VersionBumpTypeSchema: z.ZodType<VersionBumpType>;
+export declare const AgentTargetSchema: z.ZodType<AgentTarget>;
+export declare const ReleaseEnforceOnSchema: z.ZodType<ReleaseEnforceOn>;
+export declare const ReleaseAudienceKindSchema: z.ZodType<ReleaseAudienceKind>;
+export declare const UpgradeStepLevelSchema: z.ZodType<UpgradeStepLevel>;
+export declare const UpgradeAutofixKindSchema: z.ZodType<UpgradeAutofixKind>;
+export declare const ReleaseImpactAudienceSchema: z.ZodType<ReleaseImpactAudience>;
+export declare const ReleaseCapsulePackageSchema: z.ZodType<ReleaseCapsulePackage>;
+export declare const MigrationInstructionSchema: z.ZodType<MigrationInstruction>;
+export declare const UpgradeAutofixSchema: z.ZodType<UpgradeAutofix>;
+export declare const UpgradePlanStepSchema: z.ZodType<UpgradePlanStep>;
+export declare const AgentPromptBundleSchema: z.ZodType<AgentPromptBundle>;
+export declare const ReleaseCapsuleValidationSchema: z.ZodType<ReleaseCapsuleValidation>;
+export declare const ReleaseCapsuleSchema: z.ZodType<ReleaseCapsule>;
+export declare const UpgradePackageTargetSchema: z.ZodType<UpgradePackageTarget>;
+export declare const GeneratedReleaseManifestEntrySchema: z.ZodType<GeneratedReleaseManifestEntry>;
+export declare const GeneratedReleaseManifestSchema: z.ZodType<GeneratedReleaseManifest>;
+export declare const ReleaseIndexEntrySchema: z.ZodType<ReleaseIndexEntry>;
+export declare const ReleaseIndexSchema: z.ZodType<ReleaseIndex>;
+export declare const ReleaseDetailSchema: z.ZodType<ReleaseDetail>;
+export declare const UpgradePlanSchema: z.ZodType<UpgradePlan>;

package/dist/versioning/schema.js

@@ -0,0 +1 @@
+import{z as e}from"zod";export const VersionBumpTypeSchema=e.enum(["patch","minor","major"]);export const AgentTargetSchema=e.enum(["codex","opencode","claude-code"]);export const ReleaseEnforceOnSchema=e.enum(["release-branch","always","never"]);export const ReleaseAudienceKindSchema=e.enum(["maintainer","customer","integrator","agent"]);export const UpgradeStepLevelSchema=e.enum(["auto","assisted","manual"]);export const UpgradeAutofixKindSchema=e.enum(["package-json","contractsrc","import-rewrite","codemod"]);export const ReleaseImpactAudienceSchema=e.object({kind:ReleaseAudienceKindSchema,summary:e.string(),affectedPackages:e.array(e.string()).optional(),affectedRuntimes:e.array(e.string()).optional(),affectedFrameworks:e.array(e.string()).optional()}).strict();export const ReleaseCapsulePackageSchema=e.object({name:e.string(),releaseType:VersionBumpTypeSchema,version:e.string().optional(),previousVersion:e.string().optional()}).strict();export const MigrationInstructionSchema=e.object({id:e.string(),title:e.string(),summary:e.string(),required:e.boolean().default(!0),when:e.string().optional(),steps:e.array(e.string()).default([])}).strict();export const UpgradeAutofixSchema=e.object({id:e.string(),kind:UpgradeAutofixKindSchema,title:e.string(),summary:e.string(),path:e.string().optional(),packageName:e.string().optional(),dependencyType:e.enum(["dependencies","devDependencies","peerDependencies"]).optional(),from:e.string().optional(),to:e.string().optional(),configPath:e.string().optional(),value:e.unknown().optional(),codemodId:e.string().optional()});export const UpgradePlanStepSchema=e.object({id:e.string(),title:e.string(),summary:e.string(),level:UpgradeStepLevelSchema,instructions:e.array(e.string()).default([]),packages:e.array(e.string()).optional(),autofixes:e.array(UpgradeAutofixSchema).optional()});export const AgentPromptBundleSchema=e.object({agent:AgentTargetSchema,title:e.string(),prompt:e.string()});export const ReleaseCapsuleValidationSchema=e.object({commands:e.array(e.string()).default([]),evidence:e.array(e.string()).default([])}).strict();export const ReleaseCapsuleSchema=e.object({schemaVersion:e.literal("1").default("1"),slug:e.string(),summary:e.string(),isBreaking:e.boolean().default(!1),packages:e.array(ReleaseCapsulePackageSchema).default([]),affectedRuntimes:e.array(e.string()).default([]),affectedFrameworks:e.array(e.string()).default([]),audiences:e.array(ReleaseImpactAudienceSchema).default([]),deprecations:e.array(e.string()).default([]),migrationInstructions:e.array(MigrationInstructionSchema).default([]),upgradeSteps:e.array(UpgradePlanStepSchema).default([]),validation:ReleaseCapsuleValidationSchema.default({commands:[],evidence:[]}),prompts:e.record(AgentTargetSchema,e.string()).optional()}).strict();export const UpgradePackageTargetSchema=e.object({name:e.string(),currentVersion:e.string().optional(),targetVersion:e.string().optional()});export const GeneratedReleaseManifestEntrySchema=e.object({slug:e.string(),version:e.string(),summary:e.string(),date:e.string(),isBreaking:e.boolean(),packages:e.array(ReleaseCapsulePackageSchema).default([]),affectedRuntimes:e.array(e.string()).default([]),affectedFrameworks:e.array(e.string()).default([]),audiences:e.array(ReleaseImpactAudienceSchema).default([]),deprecations:e.array(e.string()).default([]),migrationInstructions:e.array(MigrationInstructionSchema).default([]),upgradeSteps:e.array(UpgradePlanStepSchema).default([]),validation:ReleaseCapsuleValidationSchema.default({commands:[],evidence:[]})});export const GeneratedReleaseManifestSchema=e.object({generatedAt:e.string(),releases:e.array(GeneratedReleaseManifestEntrySchema).default([])});export const ReleaseIndexEntrySchema=e.object({slug:e.string(),version:e.string(),summary:e.string(),date:e.string(),isBreaking:e.boolean(),packageCount:e.number(),changeCount:e.number()});export const ReleaseIndexSchema=e.object({generatedAt:e.string(),releases:e.array(ReleaseIndexEntrySchema).default([])});export const ReleaseDetailSchema=GeneratedReleaseManifestEntrySchema;export const UpgradePlanSchema=e.object({generatedAt:e.string(),targetPackages:e.array(UpgradePackageTargetSchema).default([]),releases:e.array(GeneratedReleaseManifestEntrySchema).default([]),steps:e.array(UpgradePlanStepSchema).default([]),autofixCount:e.number().default(0),manualCount:e.number().default(0),assistedCount:e.number().default(0),agentPrompts:e.array(AgentPromptBundleSchema).default([])});

package/dist/versioning/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Versioning types for ContractSpec changelog and version management.
+ *
+ * Supports three-tier changelogs:
+ * - Per-spec: ChangelogDocBlock entries
+ * - Per-library: Package CHANGELOG.md files
+ * - Per-monorepo: Root CHANGELOG.md
+ */
+import type { DocBlock } from '../docs/types.js';
+/** Version bump type based on semantic versioning */
+export type VersionBumpType = 'patch' | 'minor' | 'major';
+/** Semantic version components */
+export interface SemanticVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+    build?: string;
+}
+/** Type of change for changelog entries */
+export type ChangeType = 'added' | 'changed' | 'fixed' | 'removed' | 'deprecated' | 'breaking' | 'security';
+/** Individual change entry */
+export interface ChangeEntry {
+    /** Type of change */
+    type: ChangeType;
+    /** Human-readable description of the change */
+    description: string;
+    /** Schema/code path changed (e.g., "io.input.email", "meta.stability") */
+    path?: string;
+    /** Related issue/ticket reference (e.g., "GH-123", "JIRA-456") */
+    issueRef?: string;
+    /** Git commit SHA for traceability */
+    commitSha?: string;
+    /** Author of the change */
+    author?: string;
+}
+/** Changelog entry for a specific version */
+export interface ChangelogEntry {
+    /** Version number (semver format) */
+    version: string;
+    /** Release date (ISO 8601 format) */
+    date: string;
+    /** Type of version bump that led to this version */
+    bumpType: VersionBumpType;
+    /** List of changes in this version */
+    changes: ChangeEntry[];
+    /** Breaking changes (subset for emphasis) */
+    breakingChanges?: ChangeEntry[];
+    /** Deprecation notices */
+    deprecations?: ChangeEntry[];
+    /** Contributors to this version */
+    contributors?: string[];
+    /** Release notes summary */
+    summary?: string;
+}
+/** DocBlock extension for per-spec changelogs */
+export interface ChangelogDocBlock extends DocBlock {
+    /** Changelog-specific kind */
+    kind: 'changelog';
+    /** Related spec key (e.g., "auth.beginSignup") */
+    specKey: string;
+    /** Current spec version */
+    specVersion: string;
+    /** Changelog entries for this spec */
+    entries: ChangelogEntry[];
+}
+/** Result of version analysis for a single spec */
+export interface VersionAnalysis {
+    /** Path to the spec file */
+    specPath: string;
+    /** Spec key (e.g., "auth.login") */
+    specKey: string;
+    /** Current version in the spec */
+    currentVersion: string;
+    /** Suggested new version based on changes */
+    suggestedVersion: string;
+    /** Suggested bump type */
+    bumpType: VersionBumpType;
+    /** Detected changes requiring version bump */
+    changes: ChangeEntry[];
+    /** Whether breaking changes were detected */
+    hasBreaking: boolean;
+}
+/** Aggregated version analysis result */
+export interface VersionAnalysisResult {
+    /** Individual spec analyses */
+    analyses: VersionAnalysis[];
+    /** Total specs analyzed */
+    totalSpecs: number;
+    /** Specs needing version bump */
+    specsNeedingBump: number;
+    /** Total breaking changes across all specs */
+    totalBreaking: number;
+    /** Git baseline used for comparison */
+    baseline?: string;
+}
+/** Result of changelog generation */
+export interface ChangelogResult {
+    /** Per-spec DocBlock entries */
+    specChangelogs: ChangelogDocBlock[];
+    /** Library-level markdown by package path */
+    libraryMarkdown: Map<string, string>;
+    /** Monorepo-level markdown */
+    monorepoMarkdown: string;
+    /** JSON format for programmatic use */
+    json: ChangelogJsonExport;
+}
+/** JSON export format for changelogs */
+export interface ChangelogJsonExport {
+    generatedAt: string;
+    baseline?: string;
+    specs: {
+        key: string;
+        version: string;
+        path: string;
+        entries: ChangelogEntry[];
+    }[];
+    libraries: {
+        name: string;
+        path: string;
+        version: string;
+        entries: ChangelogEntry[];
+    }[];
+}
+/** Check if a DocBlock is a ChangelogDocBlock */
+export declare function isChangelogDocBlock(doc: DocBlock): doc is ChangelogDocBlock;
+/** Check if a string is a valid VersionBumpType */
+export declare function isVersionBumpType(value: unknown): value is VersionBumpType;
+/** Check if a string is a valid ChangeType */
+export declare function isChangeType(value: unknown): value is ChangeType;

package/dist/versioning/types.js

@@ -0,0 +1 @@
+export function isChangelogDocBlock(e){return e.kind==="changelog"&&"specKey"in e&&"entries"in e}export function isVersionBumpType(e){return e==="patch"||e==="minor"||e==="major"}export function isChangeType(e){return typeof e==="string"&&["added","changed","fixed","removed","deprecated","breaking","security"].includes(e)}

package/dist/versioning/utils.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Semantic version parsing, comparison, and manipulation utilities.
+ */
+import type { SemanticVersion, VersionBumpType } from './types.js';
+/**
+ * Parse a semantic version string into components.
+ *
+ * @param version - Version string (e.g., "1.2.3", "1.0.0-alpha.1")
+ * @returns Parsed SemanticVersion or null if invalid
+ *
+ * @example
+ * parseVersion("1.2.3") // { major: 1, minor: 2, patch: 3 }
+ * parseVersion("2.0.0-beta.1") // { major: 2, minor: 0, patch: 0, prerelease: "beta.1" }
+ */
+export declare function parseVersion(version: string): SemanticVersion | null;
+/**
+ * Strictly parse a version, throwing on invalid input.
+ *
+ * @throws Error if version is not valid semver
+ */
+export declare function parseVersionStrict(version: string): SemanticVersion;
+/**
+ * Format a SemanticVersion back to string.
+ *
+ * @example
+ * formatVersion({ major: 1, minor: 2, patch: 3 }) // "1.2.3"
+ * formatVersion({ major: 2, minor: 0, patch: 0, prerelease: "beta.1" }) // "2.0.0-beta.1"
+ */
+export declare function formatVersion(version: SemanticVersion): string;
+/**
+ * Compare two version strings.
+ *
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ *
+ * @example
+ * compareVersions("1.0.0", "2.0.0") // -1
+ * compareVersions("1.2.3", "1.2.3") // 0
+ * compareVersions("2.0.0", "1.9.9") // 1
+ */
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+/**
+ * Check if version a is greater than version b.
+ */
+export declare function isVersionGreater(a: string, b: string): boolean;
+/**
+ * Check if version a is less than version b.
+ */
+export declare function isVersionLess(a: string, b: string): boolean;
+/**
+ * Check if two versions are equal.
+ */
+export declare function isVersionEqual(a: string, b: string): boolean;
+/**
+ * Bump a version by the specified type.
+ *
+ * @param current - Current version string
+ * @param bumpType - Type of bump: 'patch', 'minor', or 'major'
+ * @returns New version string
+ *
+ * @example
+ * bumpVersion("1.2.3", "patch") // "1.2.4"
+ * bumpVersion("1.2.3", "minor") // "1.3.0"
+ * bumpVersion("1.2.3", "major") // "2.0.0"
+ */
+export declare function bumpVersion(current: string, bumpType: VersionBumpType): string;
+/**
+ * Determine the appropriate version bump type based on change impact.
+ *
+ * - Breaking changes → major
+ * - Non-breaking additions/changes → minor
+ * - Fixes only → patch
+ *
+ * @param hasBreaking - Whether breaking changes were detected
+ * @param hasNonBreaking - Whether non-breaking changes (additions, changes) were detected
+ * @returns Appropriate bump type
+ */
+export declare function determineBumpType(hasBreaking: boolean, hasNonBreaking: boolean): VersionBumpType;
+/**
+ * Get sort priority for bump types (higher = more significant).
+ */
+export declare function getBumpTypePriority(bumpType: VersionBumpType): number;
+/**
+ * Get the most significant bump type from a list.
+ */
+export declare function getMaxBumpType(bumpTypes: VersionBumpType[]): VersionBumpType | null;
+/**
+ * Check if a string is a valid semantic version.
+ */
+export declare function isValidVersion(version: string): boolean;
+/**
+ * Validate a version string, returning validation errors.
+ */
+export declare function validateVersion(version: string): string[];

package/dist/versioning/utils.js

@@ -0,0 +1 @@
+const a=/^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*))?(?:\+([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*))?$/;export function parseVersion(r){const e=r.trim().match(a);if(!e)return null;const n=e[1],t=e[2],o=e[3],i=e[4],s=e[5];if(!n||!t||!o)return null;return{major:parseInt(n,10),minor:parseInt(t,10),patch:parseInt(o,10),...i&&{prerelease:i},...s&&{build:s}}}export function parseVersionStrict(r){const e=parseVersion(r);if(!e)throw Error(`Invalid semantic version: "${r}"`);return e}export function formatVersion(r){let e=`${r.major}.${r.minor}.${r.patch}`;if(r.prerelease)e+=`-${r.prerelease}`;if(r.build)e+=`+${r.build}`;return e}export function compareVersions(r,e){const n=parseVersionStrict(r),t=parseVersionStrict(e);if(n.major!==t.major)return n.major>t.major?1:-1;if(n.minor!==t.minor)return n.minor>t.minor?1:-1;if(n.patch!==t.patch)return n.patch>t.patch?1:-1;if(n.prerelease&&!t.prerelease)return-1;if(!n.prerelease&&t.prerelease)return 1;if(n.prerelease&&t.prerelease)return n.prerelease<t.prerelease?-1:n.prerelease>t.prerelease?1:0;return 0}export function isVersionGreater(r,e){return compareVersions(r,e)===1}export function isVersionLess(r,e){return compareVersions(r,e)===-1}export function isVersionEqual(r,e){return compareVersions(r,e)===0}export function bumpVersion(r,e){const n=parseVersionStrict(r);switch(e){case"major":return formatVersion({major:n.major+1,minor:0,patch:0});case"minor":return formatVersion({major:n.major,minor:n.minor+1,patch:0});case"patch":return formatVersion({major:n.major,minor:n.minor,patch:n.patch+1})}}export function determineBumpType(r,e){if(r)return"major";if(e)return"minor";return"patch"}export function getBumpTypePriority(r){switch(r){case"major":return 3;case"minor":return 2;case"patch":return 1}}export function getMaxBumpType(r){if(r.length===0)return null;return r.reduce((e,n)=>getBumpTypePriority(n)>getBumpTypePriority(e)?n:e)}export function isValidVersion(r){return parseVersion(r)!==null}export function validateVersion(r){const e=[];if(!r||typeof r!=="string"){e.push("Version must be a non-empty string");return e}const n=r.trim();if(n!==r)e.push("Version should not have leading or trailing whitespace");if(!parseVersion(n))e.push(`Invalid semantic version format: "${r}". Expected format: MAJOR.MINOR.PATCH[-prerelease][+build]`);return e}

package/dist/visual-scenarios/index.d.ts

@@ -0,0 +1,4 @@
+export { PlatformStorybookFeature, VisualTestingCapability } from './platform.js';
+export { VisualScenarioRegistry } from './registry.js';
+export { defineVisualScenario, type VisualA11yPolicy, type VisualArgs, type VisualArgValue, type VisualBindingRef, type VisualCaptureClassification, type VisualCapturePolicy, type VisualDocumentationPolicy, type VisualModeSpec, type VisualScenarioPresentationRef, type VisualScenarioRef, type VisualScenarioSpec, VisualScenarioSpecDocBlock, type VisualSnapshotPolicy, type VisualStoryCase, type VisualStoryLayout, type VisualSubcomponentSpec, } from './spec.js';
+export { type VisualScenarioValidationContext, type VisualScenarioValidationError, type VisualScenarioValidationResult, validateVisualScenario, } from './validation.js';

package/dist/visual-scenarios/index.js

@@ -0,0 +1 @@
+export{PlatformStorybookFeature,VisualTestingCapability}from"./platform.js";export{VisualScenarioRegistry}from"./registry.js";export{defineVisualScenario,VisualScenarioSpecDocBlock}from"./spec.js";export{validateVisualScenario}from"./validation.js";

package/dist/visual-scenarios/platform.d.ts

@@ -0,0 +1,2 @@
+export declare const VisualTestingCapability: import("..").CapabilitySpec;
+export declare const PlatformStorybookFeature: import("..").FeatureModuleSpec;

package/dist/visual-scenarios/platform.js

@@ -0,0 +1 @@
+import{defineCapability as i}from"../capabilities/index.js";import{defineFeature as t}from"../features/index.js";import{VisualScenarioSpecDocBlock as o}from"./spec.js";export const VisualTestingCapability=i({meta:{key:"ui.visual-testing",version:"1.0.0",kind:"ui",title:"Visual testing",description:"Provider-neutral visual scenarios, component documentation, deterministic lifecycle and interaction bindings, accessibility policy, and snapshot intent.",domain:"ui-platform",owners:["platform.core"],tags:["ui","visual-testing","storybook"],stability:"experimental"}});export const PlatformStorybookFeature=t({meta:{key:"platform.storybook",version:"1.0.0",title:"Storybook visual development platform",description:"Installs the provider-neutral capability consumed by Storybook integrations.",domain:"ui-platform",owners:["platform.core"],tags:["ui","visual-testing","storybook"],stability:"experimental"},capabilities:{provides:[{key:"ui.visual-testing",version:"1.0.0"}]},docs:[o.id]});

package/dist/visual-scenarios/registry.d.ts

@@ -0,0 +1,6 @@
+import { SpecContractRegistry } from '../registry.js';
+import type { VisualScenarioSpec } from './spec.js';
+/** In-memory registry for provider-neutral visual scenarios. */
+export declare class VisualScenarioRegistry extends SpecContractRegistry<'visual-scenario', VisualScenarioSpec> {
+    constructor(items?: VisualScenarioSpec[]);
+}

package/dist/visual-scenarios/registry.js

@@ -0,0 +1 @@
+import{SpecContractRegistry as i}from"../registry.js";export class VisualScenarioRegistry extends i{constructor(e){super("visual-scenario",e)}}

package/dist/visual-scenarios/spec.d.ts

@@ -0,0 +1,94 @@
+import type { CapabilityRef } from '../capabilities/index.js';
+import type { OwnerShipMeta } from '../ownership.js';
+import type { VersionedSpecRef } from '../versioning/index.js';
+export type VisualScenarioRef = VersionedSpecRef;
+export type VisualScenarioPresentationRef = VersionedSpecRef;
+export type VisualCaptureClassification = 'synthetic' | 'sanitized';
+export interface VisualBindingRef {
+    readonly $binding: string;
+}
+export type VisualArgValue = string | number | boolean | null | VisualBindingRef | readonly VisualArgValue[] | {
+    readonly [key: string]: VisualArgValue;
+};
+export interface VisualArgs {
+    readonly [key: string]: VisualArgValue;
+}
+export interface VisualModeSpec {
+    key: string;
+    title?: string;
+    parameters?: VisualArgs;
+}
+export type VisualStoryLayout = 'centered' | 'fullscreen' | 'padded';
+export interface VisualSubcomponentSpec {
+    /** Label exposed by the documentation renderer. */
+    readonly name: string;
+    /** Package-owned binding that resolves to the public React component. */
+    readonly binding: string;
+}
+export interface VisualDocumentationPolicy {
+    readonly description?: string;
+    readonly subcomponents?: readonly VisualSubcomponentSpec[];
+}
+export interface VisualA11yPolicy {
+    test: 'off' | 'todo' | 'error';
+}
+export interface VisualSnapshotPolicy {
+    enabled: boolean;
+    /** Publishing permits an external visual-diff provider to receive the capture. */
+    publish?: boolean;
+    disableAnimations?: boolean;
+    delayMs?: number;
+}
+export interface VisualStoryCase {
+    key: string;
+    title?: string;
+    args?: VisualArgs;
+    renderBinding?: string;
+    setupBinding?: string;
+    interactionBinding?: string;
+    decoratorBindings?: readonly string[];
+    globals?: VisualArgs;
+    parameters?: VisualArgs;
+    tags?: readonly string[];
+    layout?: VisualStoryLayout;
+    modes?: string[];
+    a11y?: VisualA11yPolicy;
+    snapshot?: VisualSnapshotPolicy;
+}
+export interface VisualCapturePolicy {
+    classification: VisualCaptureClassification;
+    /** Explicit permission to send captures to an external service. */
+    external?: boolean;
+}
+export interface VisualScenarioSpec {
+    meta: OwnerShipMeta;
+    presentation: VisualScenarioPresentationRef;
+    /** Stable product-surface key, independent of the source file path. */
+    surface: string;
+    capability?: CapabilityRef;
+    componentBinding?: string;
+    setupBinding?: string;
+    decoratorBindings?: readonly string[];
+    docs?: VisualDocumentationPolicy;
+    globals?: VisualArgs;
+    parameters?: VisualArgs;
+    tags?: readonly string[];
+    layout?: VisualStoryLayout;
+    modes?: VisualModeSpec[];
+    cases: VisualStoryCase[];
+    capture: VisualCapturePolicy;
+    renderBinding?: string;
+    a11y?: VisualA11yPolicy;
+    snapshot?: VisualSnapshotPolicy;
+}
+export declare function defineVisualScenario(spec: VisualScenarioSpec): VisualScenarioSpec;
+export declare const VisualScenarioSpecDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};

package/dist/visual-scenarios/spec.js

@@ -0,0 +1 @@
+export function defineVisualScenario(e){return e}export const VisualScenarioSpecDocBlock={id:"docs.tech.contracts.visual-scenarios",title:"Visual scenario contracts",summary:"Provider-neutral, deterministic UI cases linked to React presentations.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/visual-scenarios",tags:["contracts","presentations","visual-testing"],body:"# Visual scenario contracts\n\nVisual scenarios describe named, deterministic UI cases independently of Storybook or any visual-diff provider. Each scenario references a React presentation and a stable product surface. Args, globals, and parameters remain JSON-compatible and may contain nested `{ $binding: string }` references resolved by a host-owned binding registry. Non-serializable components, decorators, setup hooks, and interactions are referenced by package-owned binding names.\n\nEvery scenario classifies captured data as `synthetic` or `sanitized`. A snapshot policy with `publish: true` is valid only when `capture.external` is explicitly `true`; omission always fails closed. Modes and render bindings are references and must resolve when their registries are supplied to validation.\n"};

package/dist/visual-scenarios/validation-authoring.d.ts

@@ -0,0 +1,5 @@
+import type { VisualScenarioSpec } from './spec.js';
+import type { VisualScenarioValidationContext } from './validation.js';
+type AddError = (message: string, path?: string) => void;
+export declare function validateVisualAuthoring(spec: VisualScenarioSpec, context: VisualScenarioValidationContext, add: AddError): void;
+export {};

package/dist/visual-scenarios/validation-authoring.js

@@ -0,0 +1 @@
+const c=new Set(["centered","fullscreen","padded"]);export function validateVisualAuthoring(i,e,n){s(i.componentBinding,e,"componentBinding",n);s(i.setupBinding,e,"setupBinding",n);f(i.decoratorBindings,e,"decoratorBindings",n);a(i.globals,e,"globals",n);a(i.parameters,e,"parameters",n);l(i.tags,"tags",n);g(i.layout,"layout",n);m(i,e,n);for(const[t,r]of i.cases.entries()){const o=`cases[${t}]`;s(r.setupBinding,e,`${o}.setupBinding`,n);s(r.interactionBinding,e,`${o}.interactionBinding`,n);f(r.decoratorBindings,e,`${o}.decoratorBindings`,n);a(r.globals,e,`${o}.globals`,n);a(r.parameters,e,`${o}.parameters`,n);l(r.tags,`${o}.tags`,n);g(r.layout,`${o}.layout`,n)}}function m(i,e,n){if(i.docs?.description!==void 0&&!i.docs.description.trim())n("Visual documentation description must not be empty","docs.description");const t=new Set;for(const[r,o]of(i.docs?.subcomponents??[]).entries()){const u=`docs.subcomponents[${r}]`;if(!o.name.trim())n("Subcomponent name must not be empty",`${u}.name`);else if(t.has(o.name))n(`Duplicate subcomponent ${o.name}`,u);t.add(o.name);s(o.binding,e,`${u}.binding`,n)}}function l(i,e,n){if(!i)return;if(new Set(i).size!==i.length)n("Visual tags must be unique",e);for(const[t,r]of i.entries()){if(!r.trim())n("Visual tag must not be empty",`${e}[${t}]`);if(r==="ai-generated")n("The ai-generated Storybook tag is forbidden",`${e}[${t}]`)}}function g(i,e,n){if(i!==void 0&&!c.has(i))n(`Unsupported visual layout ${i}`,e)}function f(i,e,n,t){if(!i)return;if(new Set(i).size!==i.length)t("Visual binding references must be unique",n);i.forEach((r,o)=>s(r,e,`${n}[${o}]`,t))}function a(i,e,n,t){if(!i)return;d(i,n,(r,o)=>s(r,e,o,t))}function d(i,e,n){if(i===null||typeof i!=="object")return;if("$binding"in i&&typeof i.$binding==="string"){n(i.$binding,`${e}.$binding`);return}if(Array.isArray(i)){i.forEach((t,r)=>d(t,`${e}[${r}]`,n));return}for(const[t,r]of Object.entries(i))d(r,`${e}.${t}`,n)}function s(i,e,n,t){if(i===void 0)return;if(!i.trim()){t("Visual binding must not be empty",n);return}if(!e.bindings)return;const r=e.bindings;if(!(typeof r.has==="function"?r.has(i):e.bindings.includes(i)))t(`Unresolved visual binding ${i}`,n)}

package/dist/visual-scenarios/validation.d.ts

@@ -0,0 +1,17 @@
+import type { PresentationSpec } from '../presentations/index.js';
+import type { VisualScenarioSpec } from './spec.js';
+export interface VisualScenarioValidationError {
+    message: string;
+    path?: string;
+}
+export interface VisualScenarioValidationResult {
+    valid: boolean;
+    errors: VisualScenarioValidationError[];
+}
+export interface VisualScenarioValidationContext {
+    presentations?: {
+        get(key: string, version?: string): PresentationSpec | undefined;
+    };
+    bindings?: ReadonlySet<string> | readonly string[];
+}
+export declare function validateVisualScenario(spec: VisualScenarioSpec, context?: VisualScenarioValidationContext): VisualScenarioValidationResult;

package/dist/visual-scenarios/validation.js

@@ -0,0 +1 @@
+import{validateVisualAuthoring as m}from"./validation-authoring.js";export function validateVisualScenario(e,t={}){const n=[],i=(a,r)=>n.push({message:a,path:r});if(!e.meta.key.trim())i("Visual scenario key must not be empty","meta.key");if(!e.meta.version.trim())i("Visual scenario version must not be empty","meta.version");if(!e.meta.description.trim())i("Visual scenario description must not be empty","meta.description");if(!e.meta.owners.length)i("Visual scenario must declare at least one owner","meta.owners");if(!e.meta.tags.length)i("Visual scenario must declare at least one tag","meta.tags");if(!e.surface.trim())i("Visual scenario surface must not be empty","surface");if(!e.presentation.key.trim()||!e.presentation.version.trim())i("Visual scenario must reference a versioned presentation","presentation");if(!e.cases.length)i("Visual scenario must declare at least one case","cases");if(e.capture.classification!=="synthetic"&&e.capture.classification!=="sanitized")i("Capture classification must be synthetic or sanitized","capture.classification");g(e,t,i);V(e,t,i);m(e,t,i);f(e.snapshot,e.capture.external,"snapshot",i);return{valid:n.length===0,errors:n}}function g(e,t,n){if(!t.presentations)return;const i=t.presentations.get(e.presentation.key,e.presentation.version);if(!i){n(`Presentation ${e.presentation.key}.v${e.presentation.version} was not found`,"presentation");return}if(i.source.type!=="component"||i.source.framework!=="react"||!i.targets.includes("react"))n("Visual scenarios require a React presentation","presentation")}function V(e,t,n){const i=new Set;for(const[r,s]of(e.modes??[]).entries()){if(!s.key.trim())n("Visual mode key must not be empty",`modes[${r}].key`);else if(i.has(s.key))n(`Duplicate visual mode ${s.key}`,`modes[${r}]`);i.add(s.key);c(s.parameters,t,`modes[${r}].parameters`,n)}const a=new Set;for(const[r,s]of e.cases.entries()){const o=`cases[${r}]`;if(!s.key.trim())n("Visual case key must not be empty",`${o}.key`);else if(a.has(s.key))n(`Duplicate visual case ${s.key}`,o);a.add(s.key);for(const d of s.modes??[])if(!i.has(d))n(`Unknown visual mode ${d}`,`${o}.modes`);if(s.modes&&new Set(s.modes).size!==s.modes.length)n("Visual case mode references must be unique",`${o}.modes`);l(s.renderBinding,t,`${o}.renderBinding`,n);c(s.args,t,`${o}.args`,n);f(s.snapshot,e.capture.external,`${o}.snapshot`,n)}l(e.renderBinding,t,"renderBinding",n)}function f(e,t,n,i){if(e?.publish&&t!==!0)i("Published snapshots require capture.external to be true",`${n}.publish`);if(e?.publish&&!e.enabled)i("Published snapshots must be enabled",`${n}.enabled`);if(e?.delayMs!==void 0&&e.delayMs<0)i("Snapshot delayMs must be non-negative",`${n}.delayMs`)}function c(e,t,n,i){if(!e)return;u(e,n,(a,r)=>l(a,t,r,i))}function u(e,t,n){if(e===null||typeof e!=="object")return;if("$binding"in e&&typeof e.$binding==="string"){n(e.$binding,`${t}.$binding`);return}if(Array.isArray(e)){e.forEach((i,a)=>u(i,`${t}[${a}]`,n));return}for(const[i,a]of Object.entries(e))u(a,`${t}.${i}`,n)}function l(e,t,n,i){if(e===void 0)return;if(!e.trim()){i("Visual binding must not be empty",n);return}if(!t.bindings)return;const a=t.bindings;if(!(typeof a.has==="function"?a.has(e):t.bindings.includes(e)))i(`Unresolved visual binding ${e}`,n)}

package/dist/visualizations/index.d.ts

@@ -0,0 +1,4 @@
+export { VisualizationRegistry, visualizationKey } from './registry.js';
+export type { VisualizationRef, VisualizationSpec } from './spec.js';
+export { defineVisualization } from './spec.js';
+export type { CartesianVisualizationConfig, FunnelVisualizationConfig, GeoVisualizationConfig, HeatmapVisualizationConfig, MetricVisualizationConfig, PieVisualizationConfig, VisualizationAnnotation, VisualizationBaseConfig, VisualizationCartesianVariant, VisualizationConfig, VisualizationDimension, VisualizationDrilldown, VisualizationDrilldownMapping, VisualizationGeoJsonSource, VisualizationGeoMode, VisualizationGeoVariant, VisualizationKind, VisualizationMeasure, VisualizationMeta, VisualizationSeries, VisualizationSource, VisualizationStates, VisualizationThreshold, VisualizationValueFormat, } from './types.js';

package/dist/visualizations/index.js

@@ -0,0 +1 @@
+export{VisualizationRegistry,visualizationKey}from"./registry.js";export{defineVisualization}from"./spec.js";

package/dist/visualizations/registry.d.ts

@@ -0,0 +1,6 @@
+import { SpecContractRegistry } from '../registry.js';
+import type { VisualizationSpec } from './spec.js';
+export declare function visualizationKey(spec: VisualizationSpec): string;
+export declare class VisualizationRegistry extends SpecContractRegistry<'visualization', VisualizationSpec> {
+    constructor(items?: VisualizationSpec[]);
+}

package/dist/visualizations/registry.js

@@ -0,0 +1 @@
+import{SpecContractRegistry as t}from"../registry.js";export function visualizationKey(i){return`${i.meta.key}.v${i.meta.version}`}export class VisualizationRegistry extends t{constructor(i){super("visualization",i)}}

package/dist/visualizations/spec.d.ts

@@ -0,0 +1,16 @@
+import type { ExperimentRef } from '../experiments/spec.js';
+import type { VisualizationRef } from '../features/types.js';
+import type { VisualizationConfig, VisualizationMeta, VisualizationSource, VisualizationStates } from './types.js';
+export type { VisualizationRef };
+export interface VisualizationSpec {
+    meta: VisualizationMeta;
+    source: VisualizationSource;
+    visualization: VisualizationConfig;
+    states?: VisualizationStates;
+    policy?: {
+        flags?: string[];
+        pii?: string[];
+    };
+    experiments?: ExperimentRef[];
+}
+export declare function defineVisualization(spec: VisualizationSpec): VisualizationSpec;

package/dist/visualizations/spec.js

@@ -0,0 +1 @@
+export function defineVisualization(i){return i}