@ccslabs/xtend 0.1.0-rc.1

package/catalog/surface-manager-native-rmt-surfaces.js

@@ -0,0 +1,325 @@
+const {
+  KERNEL_BOUNDARY
+} = require('./epic12-rc0-gate-matrix');
+
+const SURFACE_MANAGER_NATIVE_RMT_SCHEMA = 'xtend.rmt.surfaces-domain.v1';
+const SURFACE_MANAGER_NATIVE_RMT_REPORT_SCHEMA = 'xtend.rmt.surfaces-domain-report.v1';
+const SURFACE_ADAPTER_SCHEMA = 'xtend.surface.adapter.v1';
+const SURFACE_MANAGER_SCHEMA = 'xtend.surface.manager.v1';
+const SURFACE_RECORD_SCHEMA = 'xtend.surface.record.v1';
+const SURFACE_CONTROLLER_SCHEMA = 'xtend.surface.controller.v1';
+const SURFACE_SNAPSHOT_SCHEMA = 'xtend.surface.snapshot.v1';
+const SURFACE_QUALITY_GATES_SCHEMA = 'xtend.surface.quality-gates.v1';
+const SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE = 'WP-SM-08';
+const SURFACE_MANAGER_NATIVE_RMT_STATUS = 'accepted-native-surfaces-domain-contract';
+const SURFACE_MANAGER_NATIVE_RMT_TARGET = 'native-rmt-surfaces-domain-handoff-ready';
+const SURFACE_MANAGER_NATIVE_RMT_MODULE = 'catalog/surface-manager-native-rmt-surfaces.js';
+const SURFACE_MANAGER_NATIVE_RMT_SUITE = 'tests/rmt/surface_manager_native_rmt_surfaces_suite.js';
+const SURFACE_MANAGER_NATIVE_RMT_PLAN = 'development/XTend-SurfaceManager-und-Multi-Window-Plan.md';
+const SURFACE_MANAGER_NATIVE_RMT_CONTRACT = 'development/XTend-SurfaceManager-Native-RMT-Surfaces-Domain-Contract.md';
+const SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE_DOC = 'development/WP-SM-08-Native-RMT-surfaces-Domain-und-xtend-surface-Adapter-entwerfen.md';
+const SURFACE_MANAGER_NATIVE_RMT_DOCS = 'docs/surface-manager-native-rmt-surfaces.md';
+const SURFACE_MANAGER_NATIVE_RMT_FIXTURE = 'tests/fixtures/rmt-surface-native-domain.rmt';
+const SURFACE_MANAGER_NATIVE_RMT_LOCAL_GATE = 'node scripts/run_xtend_tests.js surface-native-rmt --json';
+const SURFACE_MANAGER_NATIVE_RMT_PACKAGE_SCRIPT = 'npm run test:surface-native-rmt';
+const SURFACE_DOMAIN = 'surfaces';
+const SURFACE_ADAPTER_ID = 'xtend.surface';
+const SURFACE_ADAPTER_KIND = 'surface_adapter';
+const NEXT_WORKPACKAGE = 'WP-SM-09';
+const NEXT_DECISION = 'surface-docs-component-lab-migration-guide';
+
+const REQUIRED_DOMAINS = Object.freeze([
+  'manifest',
+  'adapters',
+  'components',
+  'routes',
+  'schedules',
+  'surfaces',
+  'templates'
+]);
+
+const REQUIRED_ADAPTERS = Object.freeze([
+  'xtend.component',
+  'xtend.xrouter',
+  'rmt.state-scheduler-diagnostics',
+  SURFACE_ADAPTER_ID
+]);
+
+const SURFACE_TYPES = Object.freeze([
+  'window',
+  'side-panel',
+  'modal',
+  'dialog',
+  'drawer'
+]);
+
+const SURFACE_FIELDS = Object.freeze([
+  'id',
+  'schema',
+  'type',
+  'adapter',
+  'manager',
+  'component',
+  'route',
+  'schedule',
+  'stateKey',
+  'defaultOpen',
+  'active',
+  'bounds',
+  'placement',
+  'mode',
+  'layer',
+  'capabilities',
+  'a11y',
+  'persistence',
+  'metadata'
+]);
+
+const SURFACE_REFERENCE_CHECKS = Object.freeze([
+  'surfaces[*].adapter -> adapters[*].id',
+  'surfaces[*].manager -> components[*].id',
+  'surfaces[*].component -> components[*].id',
+  'surfaces[*].route -> routes[*].id',
+  'surfaces[*].schedule -> schedules[*].id|endpointName'
+]);
+
+const SURFACE_ADAPTER_OPERATIONS = Object.freeze([
+  'registerSurface',
+  'openSurface',
+  'closeSurface',
+  'focusSurface',
+  'moveSurface',
+  'resizeSurface',
+  'dockSurface',
+  'undockSurface',
+  'snapshotSurfaces',
+  'emitDiagnostic'
+]);
+
+const TOOLING_ARTIFACTS = Object.freeze([
+  'xtendrmt/rmt.schema.json',
+  'xtendrmt/rmt-core.d.ts',
+  'xtendrmt/rmt-core.esm.js',
+  'xtendrmt/rmt-runtime.esm.js',
+  'xtendrmt/rmt-runtime.browser.js',
+  'tools/rmt-language/semantic-graph.js',
+  'tools/rmt-language/completions.js',
+  'tools/rmt-language/diagnostics.js'
+]);
+
+const REQUIRED_ARTIFACTS = Object.freeze([
+  SURFACE_MANAGER_NATIVE_RMT_MODULE,
+  SURFACE_MANAGER_NATIVE_RMT_SUITE,
+  SURFACE_MANAGER_NATIVE_RMT_FIXTURE,
+  SURFACE_MANAGER_NATIVE_RMT_CONTRACT,
+  SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE_DOC,
+  SURFACE_MANAGER_NATIVE_RMT_DOCS,
+  ...TOOLING_ARTIFACTS
+]);
+
+const REQUIRED_DOCS = Object.freeze([
+  SURFACE_MANAGER_NATIVE_RMT_PLAN,
+  SURFACE_MANAGER_NATIVE_RMT_CONTRACT,
+  SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE_DOC,
+  SURFACE_MANAGER_NATIVE_RMT_DOCS,
+  'development/XTend-SurfaceManager-Quality-Gates-Contract.md',
+  'docs/surface-manager-quality-gates.md',
+  'docs/surface-manager-rmt-authoring.md',
+  'docs/xtendrmt-native-authoring.md'
+]);
+
+function includesAll(values, required) {
+  return required.every((entry) => Array.isArray(values) && values.includes(entry));
+}
+
+function createSurfaceManagerNativeRmtSurfacesPlan(options = {}) {
+  return {
+    schema: SURFACE_MANAGER_NATIVE_RMT_SCHEMA,
+    reportSchema: SURFACE_MANAGER_NATIVE_RMT_REPORT_SCHEMA,
+    adapterSchema: SURFACE_ADAPTER_SCHEMA,
+    surfaceManagerSchema: SURFACE_MANAGER_SCHEMA,
+    surfaceRecordSchema: SURFACE_RECORD_SCHEMA,
+    surfaceControllerSchema: SURFACE_CONTROLLER_SCHEMA,
+    snapshotSchema: SURFACE_SNAPSHOT_SCHEMA,
+    qualityGatesSchema: SURFACE_QUALITY_GATES_SCHEMA,
+    workpackage: SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE,
+    status: SURFACE_MANAGER_NATIVE_RMT_STATUS,
+    generatedAt: options.generatedAt || 'static-local',
+    targetReadiness: SURFACE_MANAGER_NATIVE_RMT_TARGET,
+    module: SURFACE_MANAGER_NATIVE_RMT_MODULE,
+    suite: SURFACE_MANAGER_NATIVE_RMT_SUITE,
+    planningDocument: SURFACE_MANAGER_NATIVE_RMT_PLAN,
+    contract: SURFACE_MANAGER_NATIVE_RMT_CONTRACT,
+    workpackageDocument: SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE_DOC,
+    docs: SURFACE_MANAGER_NATIVE_RMT_DOCS,
+    fixture: SURFACE_MANAGER_NATIVE_RMT_FIXTURE,
+    localGate: SURFACE_MANAGER_NATIVE_RMT_LOCAL_GATE,
+    packageScript: SURFACE_MANAGER_NATIVE_RMT_PACKAGE_SCRIPT,
+    domain: SURFACE_DOMAIN,
+    adapterId: SURFACE_ADAPTER_ID,
+    adapterKind: SURFACE_ADAPTER_KIND,
+    requiredDomains: REQUIRED_DOMAINS.slice(),
+    requiredAdapters: REQUIRED_ADAPTERS.slice(),
+    surfaceTypes: SURFACE_TYPES.slice(),
+    surfaceFields: SURFACE_FIELDS.slice(),
+    referenceChecks: SURFACE_REFERENCE_CHECKS.slice(),
+    adapterOperations: SURFACE_ADAPTER_OPERATIONS.slice(),
+    artifactPaths: REQUIRED_ARTIFACTS.slice(),
+    requiredDocs: REQUIRED_DOCS.slice(),
+    toolingArtifacts: TOOLING_ARTIFACTS.slice(),
+    migrationModel: {
+      from: 'components[*].metadata.surface',
+      to: 'surfaces[*]',
+      compatibilityMode: 'dual-records-during-handoff',
+      stableIdentity: 'surfaces[*].id',
+      componentBinding: 'surfaces[*].component',
+      managerBinding: 'surfaces[*].manager',
+      scheduleBinding: 'surfaces[*].schedule',
+      statePolicy: 'digital-twin-ssot-xstate',
+      qualityRegressionBase: 'WP-SM-07'
+    },
+    adapterContract: {
+      id: SURFACE_ADAPTER_ID,
+      kind: SURFACE_ADAPTER_KIND,
+      schema: SURFACE_ADAPTER_SCHEMA,
+      consumes: [
+        'surfaces[*]',
+        'components[*]',
+        'routes[*]',
+        'schedules[*]',
+        'xtend.surface.controller.v1',
+        'xtend.surface.snapshot.v1'
+      ],
+      operations: SURFACE_ADAPTER_OPERATIONS.slice(),
+      runtimeImplemented: false,
+      kernelVisible: false
+    },
+    featureFlags: {
+      nativeSurfacesDomainDesigned: true,
+      rmtSchemaSynchronized: true,
+      rmtTypesSynchronized: true,
+      rmtNormalizerReadsSurfaces: true,
+      semanticGraphIndexesSurfaces: true,
+      completionProviderKnowsSurfaces: true,
+      surfaceAdapterRuntimeImplemented: false,
+      componentRecordCompatibilityKept: true,
+      createsSecondRegistry: false,
+      externalNetworkAllowedInLocalGate: false,
+      browserRequiredInLocalGate: false,
+      rmtKernelImportsXtendTypes: false
+    },
+    kernelBoundary: KERNEL_BOUNDARY,
+    nextWorkpackage: NEXT_WORKPACKAGE,
+    nextDecision: NEXT_DECISION
+  };
+}
+
+function validateSurfaceManagerNativeRmtSurfacesPlan(plan = createSurfaceManagerNativeRmtSurfacesPlan()) {
+  const errors = [];
+
+  if (!plan || plan.schema !== SURFACE_MANAGER_NATIVE_RMT_SCHEMA) errors.push(`schema must be ${SURFACE_MANAGER_NATIVE_RMT_SCHEMA}`);
+  if (!plan || plan.reportSchema !== SURFACE_MANAGER_NATIVE_RMT_REPORT_SCHEMA) errors.push(`reportSchema must be ${SURFACE_MANAGER_NATIVE_RMT_REPORT_SCHEMA}`);
+  if (!plan || plan.adapterSchema !== SURFACE_ADAPTER_SCHEMA) errors.push(`adapterSchema must be ${SURFACE_ADAPTER_SCHEMA}`);
+  if (!plan || plan.workpackage !== SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE) errors.push(`workpackage must be ${SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE}`);
+  if (!plan || plan.status !== SURFACE_MANAGER_NATIVE_RMT_STATUS) errors.push(`status must be ${SURFACE_MANAGER_NATIVE_RMT_STATUS}`);
+  if (!plan || plan.targetReadiness !== SURFACE_MANAGER_NATIVE_RMT_TARGET) errors.push(`targetReadiness must be ${SURFACE_MANAGER_NATIVE_RMT_TARGET}`);
+  if (!plan || plan.domain !== SURFACE_DOMAIN) errors.push(`domain must be ${SURFACE_DOMAIN}`);
+  if (!plan || plan.adapterId !== SURFACE_ADAPTER_ID) errors.push(`adapterId must be ${SURFACE_ADAPTER_ID}`);
+  if (!plan || plan.adapterKind !== SURFACE_ADAPTER_KIND) errors.push(`adapterKind must be ${SURFACE_ADAPTER_KIND}`);
+  if (!includesAll(plan && plan.requiredDomains, REQUIRED_DOMAINS)) errors.push('required domains missing');
+  if (!includesAll(plan && plan.requiredAdapters, REQUIRED_ADAPTERS)) errors.push('required adapters missing');
+  if (!includesAll(plan && plan.surfaceTypes, SURFACE_TYPES)) errors.push('surface types missing');
+  if (!includesAll(plan && plan.surfaceFields, SURFACE_FIELDS)) errors.push('surface fields missing');
+  if (!includesAll(plan && plan.referenceChecks, SURFACE_REFERENCE_CHECKS)) errors.push('surface reference checks missing');
+  if (!includesAll(plan && plan.adapterOperations, SURFACE_ADAPTER_OPERATIONS)) errors.push('surface adapter operations missing');
+  if (!plan || !plan.adapterContract || plan.adapterContract.runtimeImplemented !== false) errors.push('surface adapter runtime must stay deferred');
+  if (!plan || plan.featureFlags.nativeSurfacesDomainDesigned !== true) errors.push('native surfaces domain must be designed');
+  if (!plan || plan.featureFlags.rmtSchemaSynchronized !== true) errors.push('RMT schema must be synchronized');
+  if (!plan || plan.featureFlags.rmtTypesSynchronized !== true) errors.push('RMT types must be synchronized');
+  if (!plan || plan.featureFlags.rmtNormalizerReadsSurfaces !== true) errors.push('RMT normalizer must preserve surfaces records');
+  if (!plan || plan.featureFlags.semanticGraphIndexesSurfaces !== true) errors.push('semantic graph must index surfaces');
+  if (!plan || plan.featureFlags.completionProviderKnowsSurfaces !== true) errors.push('completion provider must know surfaces');
+  if (!plan || plan.featureFlags.surfaceAdapterRuntimeImplemented !== false) errors.push('WP-SM-08 must not claim a productive surface adapter runtime');
+  if (!plan || plan.featureFlags.componentRecordCompatibilityKept !== true) errors.push('component record compatibility must be kept');
+  if (!plan || plan.featureFlags.createsSecondRegistry !== false) errors.push('WP-SM-08 must not create a second registry');
+  if (!plan || plan.featureFlags.rmtKernelImportsXtendTypes !== false) errors.push('RMT kernel boundary must stay clean');
+  if (!plan || plan.kernelBoundary !== KERNEL_BOUNDARY) errors.push(`kernelBoundary must be ${KERNEL_BOUNDARY}`);
+  if (!plan || plan.nextWorkpackage !== NEXT_WORKPACKAGE) errors.push(`nextWorkpackage must be ${NEXT_WORKPACKAGE}`);
+  if (!plan || plan.nextDecision !== NEXT_DECISION) errors.push(`nextDecision must be ${NEXT_DECISION}`);
+
+  return {
+    schema: SURFACE_MANAGER_NATIVE_RMT_REPORT_SCHEMA,
+    ok: errors.length === 0,
+    errors,
+    checkedAt: 'static-local',
+    workpackage: SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE,
+    targetReadiness: SURFACE_MANAGER_NATIVE_RMT_TARGET
+  };
+}
+
+function createSurfaceManagerNativeRmtSurfacesReport(options = {}) {
+  const plan = options.plan || createSurfaceManagerNativeRmtSurfacesPlan(options);
+  const validation = validateSurfaceManagerNativeRmtSurfacesPlan(plan);
+
+  return {
+    schema: SURFACE_MANAGER_NATIVE_RMT_REPORT_SCHEMA,
+    ok: validation.ok,
+    errors: validation.errors,
+    workpackage: plan.workpackage,
+    status: plan.status,
+    targetReadiness: plan.targetReadiness,
+    domain: plan.domain,
+    adapterId: plan.adapterId,
+    adapterKind: plan.adapterKind,
+    surfaceTypeCount: plan.surfaceTypes.length,
+    referenceCheckCount: plan.referenceChecks.length,
+    adapterOperationCount: plan.adapterOperations.length,
+    fixture: plan.fixture,
+    localGate: plan.localGate,
+    packageScript: plan.packageScript,
+    kernelBoundary: plan.kernelBoundary,
+    nextWorkpackage: plan.nextWorkpackage,
+    nextDecision: plan.nextDecision
+  };
+}
+
+module.exports = {
+  KERNEL_BOUNDARY,
+  NEXT_DECISION,
+  NEXT_WORKPACKAGE,
+  REQUIRED_ADAPTERS,
+  REQUIRED_ARTIFACTS,
+  REQUIRED_DOCS,
+  REQUIRED_DOMAINS,
+  SURFACE_ADAPTER_ID,
+  SURFACE_ADAPTER_KIND,
+  SURFACE_ADAPTER_OPERATIONS,
+  SURFACE_ADAPTER_SCHEMA,
+  SURFACE_CONTROLLER_SCHEMA,
+  SURFACE_DOMAIN,
+  SURFACE_FIELDS,
+  SURFACE_MANAGER_NATIVE_RMT_CONTRACT,
+  SURFACE_MANAGER_NATIVE_RMT_DOCS,
+  SURFACE_MANAGER_NATIVE_RMT_FIXTURE,
+  SURFACE_MANAGER_NATIVE_RMT_LOCAL_GATE,
+  SURFACE_MANAGER_NATIVE_RMT_MODULE,
+  SURFACE_MANAGER_NATIVE_RMT_PACKAGE_SCRIPT,
+  SURFACE_MANAGER_NATIVE_RMT_PLAN,
+  SURFACE_MANAGER_NATIVE_RMT_REPORT_SCHEMA,
+  SURFACE_MANAGER_NATIVE_RMT_SCHEMA,
+  SURFACE_MANAGER_NATIVE_RMT_STATUS,
+  SURFACE_MANAGER_NATIVE_RMT_SUITE,
+  SURFACE_MANAGER_NATIVE_RMT_TARGET,
+  SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE,
+  SURFACE_MANAGER_NATIVE_RMT_WORKPACKAGE_DOC,
+  SURFACE_MANAGER_SCHEMA,
+  SURFACE_QUALITY_GATES_SCHEMA,
+  SURFACE_RECORD_SCHEMA,
+  SURFACE_REFERENCE_CHECKS,
+  SURFACE_SNAPSHOT_SCHEMA,
+  SURFACE_TYPES,
+  TOOLING_ARTIFACTS,
+  createSurfaceManagerNativeRmtSurfacesPlan,
+  createSurfaceManagerNativeRmtSurfacesReport,
+  validateSurfaceManagerNativeRmtSurfacesPlan
+};

package/catalog/surface-manager-overlay-bridge.d.ts

@@ -0,0 +1,42 @@
+import type {
+  XtendCatalogConstant,
+  XtendCatalogGate,
+  XtendCatalogOptions,
+  XtendCatalogPlan,
+  XtendCatalogRecord,
+  XtendCatalogReport
+} from './catalog-public-types';
+
+
+export declare const BRIDGE_EVENTS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const COMPONENT_TAGS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const KERNEL_BOUNDARY: XtendCatalogConstant;
+export declare const LEGACY_EVENTS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const LEGACY_STATE_KEYS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const NEXT_DECISION: XtendCatalogConstant;
+export declare const NEXT_WORKPACKAGE: string;
+export declare const OVERLAY_SURFACE_TYPES: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const REQUIRED_ARTIFACTS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const REQUIRED_DOCS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const RUNTIME_ARTIFACTS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const SURFACE_CONTROLLER_SCHEMA: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_CONTRACT: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_DOCS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_FIXTURE: XtendCatalogConstant;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_LOCAL_GATE: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_MODULE: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_PACKAGE_SCRIPT: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_PLAN: XtendCatalogConstant;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_REPORT_SCHEMA: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_SCHEMA: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_STATUS: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_SUITE: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_TARGET: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE: string;
+export declare const SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE_DOC: XtendCatalogConstant;
+export declare const SURFACE_MANAGER_SCHEMA: string;
+export declare const SURFACE_RECORD_SCHEMA: string;
+export declare const SURFACE_SNAPSHOT_SCHEMA: string;
+export declare function createSurfaceManagerOverlayBridgePlan(options?: XtendCatalogOptions): XtendCatalogPlan;
+export declare function createSurfaceManagerOverlayBridgeReport(options?: XtendCatalogOptions): XtendCatalogReport;
+export declare function validateSurfaceManagerOverlayBridgePlan(plan?: unknown): XtendCatalogReport;

package/catalog/surface-manager-overlay-bridge.js

@@ -0,0 +1,247 @@
+const {
+  KERNEL_BOUNDARY
+} = require('./epic12-rc0-gate-matrix');
+
+const SURFACE_MANAGER_OVERLAY_BRIDGE_SCHEMA = 'xtend.surface.overlay-stack-bridge.v1';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_REPORT_SCHEMA = 'xtend.surface.overlay-stack-bridge-report.v1';
+const SURFACE_MANAGER_SCHEMA = 'xtend.surface.manager.v1';
+const SURFACE_RECORD_SCHEMA = 'xtend.surface.record.v1';
+const SURFACE_CONTROLLER_SCHEMA = 'xtend.surface.controller.v1';
+const SURFACE_SNAPSHOT_SCHEMA = 'xtend.surface.snapshot.v1';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE = 'WP-SM-06';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_STATUS = 'accepted-overlay-stack-bridge';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_TARGET = 'overlay-stack-bridge-ready';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_MODULE = 'catalog/surface-manager-overlay-bridge.js';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_SUITE = 'tests/components/surface_manager_overlay_bridge_suite.js';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_PLAN = 'development/XTend-SurfaceManager-und-Multi-Window-Plan.md';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_CONTRACT = 'development/XTend-SurfaceManager-Overlay-Stack-Bridge-Contract.md';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE_DOC = 'development/WP-SM-06-Overlay-Kompatibilitaet-und-Stack-Bridge-vorbereiten.md';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_DOCS = 'docs/surface-manager-overlay-bridge.md';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_FIXTURE = 'tests/components/fixtures/xsurfaceoverlaybridge.component.html';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_LOCAL_GATE = 'node scripts/run_xtend_tests.js surface-overlay-bridge --json';
+const SURFACE_MANAGER_OVERLAY_BRIDGE_PACKAGE_SCRIPT = 'npm run test:surface-overlay-bridge';
+const NEXT_WORKPACKAGE = 'WP-SM-07';
+const NEXT_DECISION = 'surface-browser-a11y-performance-visual-gates';
+
+const RUNTIME_ARTIFACTS = Object.freeze([
+  'components/xsurfaceoverlay-bridge.js',
+  'components/xsurfaceoverlay-bridge.d.ts',
+  'components/xsurfacemanager.js',
+  'components/xsurfacemanager-controller.js',
+  'components/xmodal.js',
+  'components/xdialog.js',
+  'components/xdrawer.js'
+]);
+
+const REQUIRED_ARTIFACTS = Object.freeze([
+  SURFACE_MANAGER_OVERLAY_BRIDGE_MODULE,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_SUITE,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_CONTRACT,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE_DOC,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_DOCS,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_FIXTURE,
+  ...RUNTIME_ARTIFACTS
+]);
+
+const REQUIRED_DOCS = Object.freeze([
+  SURFACE_MANAGER_OVERLAY_BRIDGE_PLAN,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_CONTRACT,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE_DOC,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_DOCS,
+  'docs/surface-manager-workbench-fixture.md',
+  'docs/surface-manager-side-panel-runtime.md',
+  'docs/surface-manager-window-runtime.md'
+]);
+
+const COMPONENT_TAGS = Object.freeze([
+  'x-surface-manager',
+  'x-modal',
+  'x-dialog',
+  'x-drawer'
+]);
+
+const OVERLAY_SURFACE_TYPES = Object.freeze([
+  'modal',
+  'dialog',
+  'drawer'
+]);
+
+const LEGACY_EVENTS = Object.freeze([
+  'modal-opened',
+  'modal-closed',
+  'dialog-opened',
+  'dialog-closed',
+  'drawer-opened',
+  'drawer-closed',
+  'drawer-route-selected'
+]);
+
+const BRIDGE_EVENTS = Object.freeze([
+  'surface-overlay-command',
+  ...LEGACY_EVENTS
+]);
+
+const LEGACY_STATE_KEYS = Object.freeze([
+  'modal-open-<id>',
+  'dialog-open-<id>',
+  'xdrawer-open-<id>'
+]);
+
+function includesAll(values, required) {
+  return required.every((entry) => Array.isArray(values) && values.includes(entry));
+}
+
+function createSurfaceManagerOverlayBridgePlan(options = {}) {
+  return {
+    schema: SURFACE_MANAGER_OVERLAY_BRIDGE_SCHEMA,
+    reportSchema: SURFACE_MANAGER_OVERLAY_BRIDGE_REPORT_SCHEMA,
+    surfaceManagerSchema: SURFACE_MANAGER_SCHEMA,
+    surfaceRecordSchema: SURFACE_RECORD_SCHEMA,
+    surfaceControllerSchema: SURFACE_CONTROLLER_SCHEMA,
+    snapshotSchema: SURFACE_SNAPSHOT_SCHEMA,
+    workpackage: SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE,
+    status: SURFACE_MANAGER_OVERLAY_BRIDGE_STATUS,
+    generatedAt: options.generatedAt || 'static-local',
+    targetReadiness: SURFACE_MANAGER_OVERLAY_BRIDGE_TARGET,
+    module: SURFACE_MANAGER_OVERLAY_BRIDGE_MODULE,
+    suite: SURFACE_MANAGER_OVERLAY_BRIDGE_SUITE,
+    planningDocument: SURFACE_MANAGER_OVERLAY_BRIDGE_PLAN,
+    contract: SURFACE_MANAGER_OVERLAY_BRIDGE_CONTRACT,
+    workpackageDocument: SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE_DOC,
+    docs: SURFACE_MANAGER_OVERLAY_BRIDGE_DOCS,
+    fixture: SURFACE_MANAGER_OVERLAY_BRIDGE_FIXTURE,
+    localGate: SURFACE_MANAGER_OVERLAY_BRIDGE_LOCAL_GATE,
+    packageScript: SURFACE_MANAGER_OVERLAY_BRIDGE_PACKAGE_SCRIPT,
+    runtimeArtifacts: RUNTIME_ARTIFACTS.slice(),
+    artifactPaths: REQUIRED_ARTIFACTS.slice(),
+    requiredDocs: REQUIRED_DOCS.slice(),
+    componentTags: COMPONENT_TAGS.slice(),
+    overlaySurfaceTypes: OVERLAY_SURFACE_TYPES.slice(),
+    legacyEvents: LEGACY_EVENTS.slice(),
+    bridgeEvents: BRIDGE_EVENTS.slice(),
+    legacyStateKeys: LEGACY_STATE_KEYS.slice(),
+    runtimeModel: {
+      bridge: 'xsurfaceoverlay-bridge-adapts-existing-overlays-to-surface-records',
+      managerIntegration: 'x-surface-manager-overlays-slot-auto-registers-x-modal-x-dialog-x-drawer',
+      commandBridge: 'surface-overlay-command-to-controller-operation',
+      lifecycleBridge: 'legacy-overlay-events-to-surface-controller',
+      stackPolicy: 'single-controller-stack-for-windows-panels-and-compatible-overlays',
+      legacyApiPolicy: 'preserve-existing-open-close-events-and-state-keys'
+    },
+    featureFlags: {
+      overlayBridgeImplemented: true,
+      managerRegistersOverlays: true,
+      surfaceOverlayCommandImplemented: true,
+      legacyLifecycleEventsPreserved: true,
+      legacyStateKeysPreserved: true,
+      modalDialogDrawerProfilesImplemented: true,
+      controllerReusedFromWpSm02: true,
+      createsSecondRegistry: false,
+      externalNetworkAllowedInLocalGate: false,
+      browserRequiredInLocalGate: false,
+      nativeSurfacesDomainImplemented: false,
+      rmtKernelImportsXtendTypes: false
+    },
+    kernelBoundary: KERNEL_BOUNDARY,
+    nextWorkpackage: NEXT_WORKPACKAGE,
+    nextDecision: NEXT_DECISION
+  };
+}
+
+function validateSurfaceManagerOverlayBridgePlan(plan = createSurfaceManagerOverlayBridgePlan()) {
+  const errors = [];
+
+  if (!plan || plan.schema !== SURFACE_MANAGER_OVERLAY_BRIDGE_SCHEMA) errors.push(`schema must be ${SURFACE_MANAGER_OVERLAY_BRIDGE_SCHEMA}`);
+  if (!plan || plan.reportSchema !== SURFACE_MANAGER_OVERLAY_BRIDGE_REPORT_SCHEMA) errors.push(`reportSchema must be ${SURFACE_MANAGER_OVERLAY_BRIDGE_REPORT_SCHEMA}`);
+  if (!plan || plan.surfaceManagerSchema !== SURFACE_MANAGER_SCHEMA) errors.push(`surfaceManagerSchema must be ${SURFACE_MANAGER_SCHEMA}`);
+  if (!plan || plan.surfaceRecordSchema !== SURFACE_RECORD_SCHEMA) errors.push(`surfaceRecordSchema must be ${SURFACE_RECORD_SCHEMA}`);
+  if (!plan || plan.surfaceControllerSchema !== SURFACE_CONTROLLER_SCHEMA) errors.push(`surfaceControllerSchema must be ${SURFACE_CONTROLLER_SCHEMA}`);
+  if (!plan || plan.snapshotSchema !== SURFACE_SNAPSHOT_SCHEMA) errors.push(`snapshotSchema must be ${SURFACE_SNAPSHOT_SCHEMA}`);
+  if (!plan || plan.workpackage !== SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE) errors.push(`workpackage must be ${SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE}`);
+  if (!plan || plan.status !== SURFACE_MANAGER_OVERLAY_BRIDGE_STATUS) errors.push(`status must be ${SURFACE_MANAGER_OVERLAY_BRIDGE_STATUS}`);
+  if (!plan || plan.targetReadiness !== SURFACE_MANAGER_OVERLAY_BRIDGE_TARGET) errors.push(`targetReadiness must be ${SURFACE_MANAGER_OVERLAY_BRIDGE_TARGET}`);
+  if (!includesAll(plan && plan.componentTags, COMPONENT_TAGS)) errors.push('component tags missing');
+  if (!includesAll(plan && plan.overlaySurfaceTypes, OVERLAY_SURFACE_TYPES)) errors.push('overlay surface types missing');
+  if (!includesAll(plan && plan.legacyEvents, LEGACY_EVENTS)) errors.push('legacy events missing');
+  if (!includesAll(plan && plan.bridgeEvents, BRIDGE_EVENTS)) errors.push('bridge events missing');
+  if (!includesAll(plan && plan.legacyStateKeys, LEGACY_STATE_KEYS)) errors.push('legacy state keys missing');
+  if (!plan || plan.featureFlags.overlayBridgeImplemented !== true) errors.push('overlay bridge must be implemented');
+  if (!plan || plan.featureFlags.managerRegistersOverlays !== true) errors.push('manager must register overlay elements');
+  if (!plan || plan.featureFlags.surfaceOverlayCommandImplemented !== true) errors.push('surface-overlay-command must be implemented');
+  if (!plan || plan.featureFlags.legacyLifecycleEventsPreserved !== true) errors.push('legacy overlay events must be preserved');
+  if (!plan || plan.featureFlags.legacyStateKeysPreserved !== true) errors.push('legacy overlay state keys must be preserved');
+  if (!plan || plan.featureFlags.controllerReusedFromWpSm02 !== true) errors.push('WP-SM-06 must reuse WP-SM-02 controller');
+  if (!plan || plan.featureFlags.createsSecondRegistry !== false) errors.push('WP-SM-06 must not create a second registry');
+  if (!plan || plan.featureFlags.rmtKernelImportsXtendTypes !== false) errors.push('RMT kernel boundary must stay clean');
+  if (!plan || plan.kernelBoundary !== KERNEL_BOUNDARY) errors.push(`kernelBoundary must be ${KERNEL_BOUNDARY}`);
+  if (!plan || plan.nextWorkpackage !== NEXT_WORKPACKAGE) errors.push(`nextWorkpackage must be ${NEXT_WORKPACKAGE}`);
+  if (!plan || plan.nextDecision !== NEXT_DECISION) errors.push(`nextDecision must be ${NEXT_DECISION}`);
+
+  return {
+    schema: SURFACE_MANAGER_OVERLAY_BRIDGE_REPORT_SCHEMA,
+    ok: errors.length === 0,
+    errors,
+    checkedAt: 'static-local',
+    workpackage: SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE,
+    targetReadiness: SURFACE_MANAGER_OVERLAY_BRIDGE_TARGET
+  };
+}
+
+function createSurfaceManagerOverlayBridgeReport(options = {}) {
+  const plan = options.plan || createSurfaceManagerOverlayBridgePlan(options);
+  const validation = validateSurfaceManagerOverlayBridgePlan(plan);
+
+  return {
+    schema: SURFACE_MANAGER_OVERLAY_BRIDGE_REPORT_SCHEMA,
+    ok: validation.ok,
+    errors: validation.errors,
+    workpackage: plan.workpackage,
+    status: plan.status,
+    targetReadiness: plan.targetReadiness,
+    fixture: plan.fixture,
+    runtimeArtifacts: plan.runtimeArtifacts.length,
+    componentTags: plan.componentTags.length,
+    overlaySurfaceTypes: plan.overlaySurfaceTypes.length,
+    legacyEvents: plan.legacyEvents.length,
+    localGate: plan.localGate,
+    packageScript: plan.packageScript,
+    kernelBoundary: plan.kernelBoundary,
+    nextWorkpackage: plan.nextWorkpackage,
+    nextDecision: plan.nextDecision
+  };
+}
+
+module.exports = {
+  BRIDGE_EVENTS,
+  COMPONENT_TAGS,
+  KERNEL_BOUNDARY,
+  LEGACY_EVENTS,
+  LEGACY_STATE_KEYS,
+  NEXT_DECISION,
+  NEXT_WORKPACKAGE,
+  OVERLAY_SURFACE_TYPES,
+  REQUIRED_ARTIFACTS,
+  REQUIRED_DOCS,
+  RUNTIME_ARTIFACTS,
+  SURFACE_CONTROLLER_SCHEMA,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_CONTRACT,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_DOCS,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_FIXTURE,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_LOCAL_GATE,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_MODULE,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_PACKAGE_SCRIPT,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_PLAN,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_REPORT_SCHEMA,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_SCHEMA,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_STATUS,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_SUITE,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_TARGET,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE,
+  SURFACE_MANAGER_OVERLAY_BRIDGE_WORKPACKAGE_DOC,
+  SURFACE_MANAGER_SCHEMA,
+  SURFACE_RECORD_SCHEMA,
+  SURFACE_SNAPSHOT_SCHEMA,
+  createSurfaceManagerOverlayBridgePlan,
+  createSurfaceManagerOverlayBridgeReport,
+  validateSurfaceManagerOverlayBridgePlan
+};

package/catalog/surface-manager-persistence.d.ts

@@ -0,0 +1,37 @@
+import type {
+  XtendCatalogConstant,
+  XtendCatalogGate,
+  XtendCatalogOptions,
+  XtendCatalogPlan,
+  XtendCatalogRecord,
+  XtendCatalogReport
+} from './catalog-public-types';
+
+
+export declare const KERNEL_BOUNDARY: XtendCatalogConstant;
+export declare const MANAGER_METHODS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const PERSISTENCE_EVENTS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const PERSISTENCE_MODES: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const REQUIRED_ARTIFACTS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const RESTORE_POLICIES: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const SURFACE_CONTROLLER_SCHEMA: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_BACKLOG: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_DOCS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const SURFACE_MANAGER_PERSISTENCE_FIXTURE: XtendCatalogConstant;
+export declare const SURFACE_MANAGER_PERSISTENCE_LOCAL_GATE: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_MODULE: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_PACKAGE_SCRIPT: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_REPORT_SCHEMA: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_SCHEMA: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_STATUS: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_SUITE: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_TARGET: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_WORKPACKAGE: string;
+export declare const SURFACE_MANAGER_PERSISTENCE_WORKPACKAGE_DOC: XtendCatalogConstant;
+export declare const SURFACE_MANAGER_SCHEMA: string;
+export declare const SURFACE_PERSISTED_SNAPSHOT_SCHEMA: string;
+export declare const SURFACE_RECORD_SCHEMA: string;
+export declare const SURFACE_SNAPSHOT_SCHEMA: string;
+export declare function createSurfaceManagerPersistencePlan(options?: XtendCatalogOptions): XtendCatalogPlan;
+export declare function createSurfaceManagerPersistenceReport(options?: XtendCatalogOptions): XtendCatalogReport;
+export declare function validateSurfaceManagerPersistencePlan(plan?: unknown): XtendCatalogReport;