@ccslabs/xtend 0.1.0-rc.1

package/catalog/surface-manager-browser-lab.js

@@ -0,0 +1,225 @@
+const {
+  KERNEL_BOUNDARY
+} = require('./epic12-rc0-gate-matrix');
+
+const SURFACE_MANAGER_BROWSER_LAB_SCHEMA = 'xtend.surface.browser-lab.v1';
+const SURFACE_MANAGER_BROWSER_LAB_REPORT_SCHEMA = 'xtend.surface.browser-lab-report.v1';
+const SURFACE_MANAGER_BROWSER_LAB_VISUAL_BASELINE_SCHEMA = 'xtend.surface.browser-lab.visual-baseline.v1';
+const SURFACE_MANAGER_BROWSER_LAB_PERFORMANCE_REPORT_SCHEMA = 'xtend.surface.browser-lab.performance-report.v1';
+const SURFACE_MANAGER_BROWSER_LAB_CLS_REPORT_SCHEMA = 'xtend.surface.browser-lab.cls-report.v1';
+const SURFACE_MANAGER_BROWSER_LAB_WORKPACKAGE = 'WP-SM-18';
+const SURFACE_MANAGER_BROWSER_LAB_STATUS = 'implemented-browser-lab-visual-stability-gates';
+const SURFACE_MANAGER_BROWSER_LAB_TARGET = 'surface-browser-lab-visual-stability-ready';
+const SURFACE_MANAGER_BROWSER_LAB_MODULE = 'catalog/surface-manager-browser-lab.js';
+const SURFACE_MANAGER_BROWSER_LAB_SUITE = 'tests/browser/surface_manager_browser_lab_suite.js';
+const SURFACE_MANAGER_BROWSER_LAB_FIXTURE = 'tests/browser/fixtures/surface-manager-browser-lab.html';
+const SURFACE_MANAGER_BROWSER_LAB_VISUAL_BASELINE = 'tests/browser/visual-baselines/surface-manager-browser-lab.dom-baseline.json';
+const SURFACE_MANAGER_BROWSER_LAB_BACKLOG = 'development/BACKLOG-XTend-SurfaceManager-App-Shell-und-RMT-Surface-Runtime.md';
+const SURFACE_MANAGER_BROWSER_LAB_WORKPACKAGE_DOC = 'development/WP-SM-18-Browser-Lab-Pixel-Baselines-und-App-Shell-Projektproben-ausbauen.md';
+const SURFACE_MANAGER_BROWSER_LAB_DOCS = 'docs/surface-manager-browser-lab.md';
+const SURFACE_MANAGER_BROWSER_LAB_LOCAL_GATE = 'node scripts/run_xtend_tests.js surface-browser-lab --json';
+const SURFACE_MANAGER_BROWSER_LAB_PACKAGE_SCRIPT = 'npm run test:surface-browser-lab';
+const DOCS_APP_REFERENCE = 'docs/index.php';
+const DOCS_RMT_REFERENCE = 'docs/xtendrmt-parsedown-docs.rmt';
+const WORKBENCH_REFERENCE = 'tests/browser/fixtures/rmt-surface-workbench-smoke.html';
+
+const VISUAL_STATES = Object.freeze([
+  'cold-start',
+  'skeleton',
+  'hydrated',
+  'route-change',
+  'modal-stack'
+]);
+
+const VISUAL_SNAPSHOT_IDS = Object.freeze([
+  'surface-lab-cold-start',
+  'surface-lab-skeleton',
+  'surface-lab-hydrated',
+  'surface-lab-route-change',
+  'surface-lab-modal-stack'
+]);
+
+const PERFORMANCE_BUDGETS = Object.freeze({
+  coldStartShellMs: 1000,
+  openMs: 16,
+  focusMs: 16,
+  routeMs: 32,
+  hydrateMs: 120,
+  maxCumulativeLayoutShift: 0.01,
+  maxLayoutShiftPx: 1,
+  unstyledContentPopInCount: 0
+});
+
+const APP_SHELL_PROBES = Object.freeze([
+  'docs-app-parsedown-shell',
+  'rmt-surface-workbench'
+]);
+
+const REQUIRED_ARTIFACTS = Object.freeze([
+  SURFACE_MANAGER_BROWSER_LAB_MODULE,
+  SURFACE_MANAGER_BROWSER_LAB_SUITE,
+  SURFACE_MANAGER_BROWSER_LAB_FIXTURE,
+  SURFACE_MANAGER_BROWSER_LAB_VISUAL_BASELINE,
+  SURFACE_MANAGER_BROWSER_LAB_BACKLOG,
+  SURFACE_MANAGER_BROWSER_LAB_WORKPACKAGE_DOC,
+  SURFACE_MANAGER_BROWSER_LAB_DOCS,
+  'tests/browser/browser_smoke_suite.js',
+  DOCS_APP_REFERENCE,
+  DOCS_RMT_REFERENCE,
+  WORKBENCH_REFERENCE,
+  'components/xsurfacemanager.js',
+  'components/xsurfacewindow.js',
+  'components/xsidepanel.js',
+  'components/xmodal.js',
+  'xtend-loader.js'
+]);
+
+function includesAll(values, required) {
+  return required.every((entry) => Array.isArray(values) && values.includes(entry));
+}
+
+function createSurfaceManagerBrowserLabPlan(options = {}) {
+  return {
+    schema: SURFACE_MANAGER_BROWSER_LAB_SCHEMA,
+    reportSchema: SURFACE_MANAGER_BROWSER_LAB_REPORT_SCHEMA,
+    visualBaselineSchema: SURFACE_MANAGER_BROWSER_LAB_VISUAL_BASELINE_SCHEMA,
+    performanceReportSchema: SURFACE_MANAGER_BROWSER_LAB_PERFORMANCE_REPORT_SCHEMA,
+    clsReportSchema: SURFACE_MANAGER_BROWSER_LAB_CLS_REPORT_SCHEMA,
+    workpackage: SURFACE_MANAGER_BROWSER_LAB_WORKPACKAGE,
+    status: SURFACE_MANAGER_BROWSER_LAB_STATUS,
+    generatedAt: options.generatedAt || 'static-local',
+    targetReadiness: SURFACE_MANAGER_BROWSER_LAB_TARGET,
+    module: SURFACE_MANAGER_BROWSER_LAB_MODULE,
+    suite: SURFACE_MANAGER_BROWSER_LAB_SUITE,
+    fixture: SURFACE_MANAGER_BROWSER_LAB_FIXTURE,
+    visualBaseline: SURFACE_MANAGER_BROWSER_LAB_VISUAL_BASELINE,
+    backlog: SURFACE_MANAGER_BROWSER_LAB_BACKLOG,
+    workpackageDocument: SURFACE_MANAGER_BROWSER_LAB_WORKPACKAGE_DOC,
+    docs: SURFACE_MANAGER_BROWSER_LAB_DOCS,
+    localGate: SURFACE_MANAGER_BROWSER_LAB_LOCAL_GATE,
+    packageScript: SURFACE_MANAGER_BROWSER_LAB_PACKAGE_SCRIPT,
+    docsAppReference: DOCS_APP_REFERENCE,
+    docsRmtReference: DOCS_RMT_REFERENCE,
+    workbenchReference: WORKBENCH_REFERENCE,
+    requiredArtifacts: REQUIRED_ARTIFACTS.slice(),
+    visualStates: VISUAL_STATES.slice(),
+    visualSnapshotIds: VISUAL_SNAPSHOT_IDS.slice(),
+    performanceBudgets: { ...PERFORMANCE_BUDGETS },
+    appShellProbes: APP_SHELL_PROBES.slice(),
+    runtimeBoundary: {
+      shellFirst: true,
+      coldStartVisualGate: true,
+      skeletonHydrationReproducible: true,
+      routeChangeVisualGate: true,
+      modalStackVisualGate: true,
+      layoutShiftRegressionFails: true,
+      unstyledContentPopInRegressionFails: true,
+      usesSkeletonLoader: true,
+      usesXTendStyleRegistry: true,
+      docsAppMonkeypatch: false,
+      browserRequiredInLocalGate: false,
+      externalNetworkAllowedInLocalGate: false,
+      createsSecondRegistry: false,
+      rmtKernelImportsXtendTypes: false
+    },
+    nextWorkpackage: 'WP-SM-19',
+    nextDecision: 'surface-runtime-release-handoff',
+    kernelBoundary: KERNEL_BOUNDARY
+  };
+}
+
+function validateSurfaceManagerBrowserLabPlan(plan = createSurfaceManagerBrowserLabPlan()) {
+  const errors = [];
+
+  if (!plan || plan.schema !== SURFACE_MANAGER_BROWSER_LAB_SCHEMA) errors.push(`schema must be ${SURFACE_MANAGER_BROWSER_LAB_SCHEMA}`);
+  if (!plan || plan.reportSchema !== SURFACE_MANAGER_BROWSER_LAB_REPORT_SCHEMA) errors.push(`reportSchema must be ${SURFACE_MANAGER_BROWSER_LAB_REPORT_SCHEMA}`);
+  if (!plan || plan.visualBaselineSchema !== SURFACE_MANAGER_BROWSER_LAB_VISUAL_BASELINE_SCHEMA) errors.push(`visualBaselineSchema must be ${SURFACE_MANAGER_BROWSER_LAB_VISUAL_BASELINE_SCHEMA}`);
+  if (!plan || plan.performanceReportSchema !== SURFACE_MANAGER_BROWSER_LAB_PERFORMANCE_REPORT_SCHEMA) errors.push(`performanceReportSchema must be ${SURFACE_MANAGER_BROWSER_LAB_PERFORMANCE_REPORT_SCHEMA}`);
+  if (!plan || plan.clsReportSchema !== SURFACE_MANAGER_BROWSER_LAB_CLS_REPORT_SCHEMA) errors.push(`clsReportSchema must be ${SURFACE_MANAGER_BROWSER_LAB_CLS_REPORT_SCHEMA}`);
+  if (!plan || plan.workpackage !== SURFACE_MANAGER_BROWSER_LAB_WORKPACKAGE) errors.push(`workpackage must be ${SURFACE_MANAGER_BROWSER_LAB_WORKPACKAGE}`);
+  if (!plan || plan.status !== SURFACE_MANAGER_BROWSER_LAB_STATUS) errors.push(`status must be ${SURFACE_MANAGER_BROWSER_LAB_STATUS}`);
+  if (!plan || plan.targetReadiness !== SURFACE_MANAGER_BROWSER_LAB_TARGET) errors.push(`targetReadiness must be ${SURFACE_MANAGER_BROWSER_LAB_TARGET}`);
+  if (!includesAll(plan && plan.visualStates, VISUAL_STATES)) errors.push('visual states missing');
+  if (!includesAll(plan && plan.visualSnapshotIds, VISUAL_SNAPSHOT_IDS)) errors.push('visual snapshot ids missing');
+  if (!includesAll(plan && plan.appShellProbes, APP_SHELL_PROBES)) errors.push('app shell probes missing');
+  if (!plan || !plan.performanceBudgets || plan.performanceBudgets.openMs !== PERFORMANCE_BUDGETS.openMs) errors.push('open budget missing');
+  if (!plan || !plan.performanceBudgets || plan.performanceBudgets.maxCumulativeLayoutShift !== PERFORMANCE_BUDGETS.maxCumulativeLayoutShift) errors.push('CLS budget missing');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.shellFirst !== true) errors.push('shell-first boundary must be true');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.coldStartVisualGate !== true) errors.push('cold-start visual gate must be true');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.skeletonHydrationReproducible !== true) errors.push('skeleton hydration must be reproducible');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.layoutShiftRegressionFails !== true) errors.push('layout-shift regressions must fail');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.unstyledContentPopInRegressionFails !== true) errors.push('unstyled pop-in regressions must fail');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.usesSkeletonLoader !== true) errors.push('SkeletonLoader must be used');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.usesXTendStyleRegistry !== true) errors.push('XTendStyleRegistry must be used');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.docsAppMonkeypatch !== false) errors.push('docs app monkeypatch must stay false');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.externalNetworkAllowedInLocalGate !== false) errors.push('browser lab must stay offline');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.createsSecondRegistry !== false) errors.push('browser lab must not create a second registry');
+  if (!plan || !plan.runtimeBoundary || plan.runtimeBoundary.rmtKernelImportsXtendTypes !== false) errors.push('RMT kernel boundary must stay clean');
+  if (!plan || plan.kernelBoundary !== KERNEL_BOUNDARY) errors.push(`kernelBoundary must be ${KERNEL_BOUNDARY}`);
+
+  return {
+    schema: SURFACE_MANAGER_BROWSER_LAB_REPORT_SCHEMA,
+    ok: errors.length === 0,
+    errors,
+    checkedAt: 'static-local',
+    workpackage: SURFACE_MANAGER_BROWSER_LAB_WORKPACKAGE,
+    targetReadiness: SURFACE_MANAGER_BROWSER_LAB_TARGET
+  };
+}
+
+function createSurfaceManagerBrowserLabReport(options = {}) {
+  const plan = options.plan || createSurfaceManagerBrowserLabPlan(options);
+  const validation = validateSurfaceManagerBrowserLabPlan(plan);
+
+  return {
+    schema: SURFACE_MANAGER_BROWSER_LAB_REPORT_SCHEMA,
+    ok: validation.ok,
+    errors: validation.errors,
+    workpackage: plan.workpackage,
+    status: plan.status,
+    targetReadiness: plan.targetReadiness,
+    visualStates: plan.visualStates.length,
+    visualSnapshots: plan.visualSnapshotIds.length,
+    appShellProbes: plan.appShellProbes.slice(),
+    performanceBudgets: { ...plan.performanceBudgets },
+    fixture: plan.fixture,
+    visualBaseline: plan.visualBaseline,
+    localGate: plan.localGate,
+    packageScript: plan.packageScript,
+    kernelBoundary: plan.kernelBoundary,
+    nextWorkpackage: plan.nextWorkpackage,
+    nextDecision: plan.nextDecision
+  };
+}
+
+module.exports = {
+  APP_SHELL_PROBES,
+  DOCS_APP_REFERENCE,
+  DOCS_RMT_REFERENCE,
+  KERNEL_BOUNDARY,
+  PERFORMANCE_BUDGETS,
+  REQUIRED_ARTIFACTS,
+  SURFACE_MANAGER_BROWSER_LAB_BACKLOG,
+  SURFACE_MANAGER_BROWSER_LAB_CLS_REPORT_SCHEMA,
+  SURFACE_MANAGER_BROWSER_LAB_DOCS,
+  SURFACE_MANAGER_BROWSER_LAB_FIXTURE,
+  SURFACE_MANAGER_BROWSER_LAB_LOCAL_GATE,
+  SURFACE_MANAGER_BROWSER_LAB_MODULE,
+  SURFACE_MANAGER_BROWSER_LAB_PACKAGE_SCRIPT,
+  SURFACE_MANAGER_BROWSER_LAB_PERFORMANCE_REPORT_SCHEMA,
+  SURFACE_MANAGER_BROWSER_LAB_REPORT_SCHEMA,
+  SURFACE_MANAGER_BROWSER_LAB_SCHEMA,
+  SURFACE_MANAGER_BROWSER_LAB_STATUS,
+  SURFACE_MANAGER_BROWSER_LAB_SUITE,
+  SURFACE_MANAGER_BROWSER_LAB_TARGET,
+  SURFACE_MANAGER_BROWSER_LAB_VISUAL_BASELINE,
+  SURFACE_MANAGER_BROWSER_LAB_VISUAL_BASELINE_SCHEMA,
+  SURFACE_MANAGER_BROWSER_LAB_WORKPACKAGE,
+  SURFACE_MANAGER_BROWSER_LAB_WORKPACKAGE_DOC,
+  VISUAL_SNAPSHOT_IDS,
+  VISUAL_STATES,
+  WORKBENCH_REFERENCE,
+  createSurfaceManagerBrowserLabPlan,
+  createSurfaceManagerBrowserLabReport,
+  validateSurfaceManagerBrowserLabPlan
+};

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

@@ -0,0 +1,43 @@
+import type {
+  XtendCatalogConstant,
+  XtendCatalogGate,
+  XtendCatalogOptions,
+  XtendCatalogPlan,
+  XtendCatalogRecord,
+  XtendCatalogReport
+} from './catalog-public-types';
+
+
+export declare const KERNEL_BOUNDARY: XtendCatalogConstant;
+export declare const NEXT_DECISION: XtendCatalogConstant;
+export declare const NEXT_WORKPACKAGE: string;
+export declare const REQUIRED_ARTIFACTS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const REQUIRED_DIAGNOSTIC_CODES: XtendCatalogConstant;
+export declare const REQUIRED_DOCS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const REQUIRED_LANES: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const REQUIRED_METHODS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const REQUIRED_STATE_KEYS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const REQUIRED_SURFACE_TYPES: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const SOURCE_ARTIFACTS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const SURFACE_CONTROLLER_CONTRACT: string;
+export declare const SURFACE_CONTROLLER_DOCS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const SURFACE_CONTROLLER_LOCAL_GATE: string;
+export declare const SURFACE_CONTROLLER_MODULE: string;
+export declare const SURFACE_CONTROLLER_PACKAGE_SCRIPT: string;
+export declare const SURFACE_CONTROLLER_PLAN: XtendCatalogConstant;
+export declare const SURFACE_CONTROLLER_REPORT_SCHEMA: string;
+export declare const SURFACE_CONTROLLER_RUNTIME: XtendCatalogConstant;
+export declare const SURFACE_CONTROLLER_SCHEMA: string;
+export declare const SURFACE_DIAGNOSTIC_SCHEMA: string;
+export declare const SURFACE_CONTROLLER_STATUS: string;
+export declare const SURFACE_CONTROLLER_SUITE: string;
+export declare const SURFACE_CONTROLLER_TARGET: string;
+export declare const SURFACE_CONTROLLER_TYPES: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const SURFACE_CONTROLLER_WORKPACKAGE: string;
+export declare const SURFACE_CONTROLLER_WORKPACKAGE_DOC: XtendCatalogConstant;
+export declare const SURFACE_OPERATION_RESULT_SCHEMA: string;
+export declare const SURFACE_RECORD_SCHEMA: string;
+export declare const SURFACE_SNAPSHOT_SCHEMA: string;
+export declare function createSurfaceControllerPlan(options?: XtendCatalogOptions): XtendCatalogPlan;
+export declare function createSurfaceControllerReport(options?: XtendCatalogOptions): XtendCatalogReport;
+export declare function validateSurfaceControllerPlan(plan?: unknown): XtendCatalogReport;

package/catalog/surface-manager-controller.js

@@ -0,0 +1,290 @@
+const {
+  KERNEL_BOUNDARY
+} = require('./epic12-rc0-gate-matrix');
+
+const SURFACE_CONTROLLER_SCHEMA = 'xtend.surface.controller.v1';
+const SURFACE_CONTROLLER_REPORT_SCHEMA = 'xtend.surface.controller-report.v1';
+const SURFACE_RECORD_SCHEMA = 'xtend.surface.record.v1';
+const SURFACE_SNAPSHOT_SCHEMA = 'xtend.surface.snapshot.v1';
+const SURFACE_DIAGNOSTIC_SCHEMA = 'xtend.surface.diagnostic.v1';
+const SURFACE_OPERATION_RESULT_SCHEMA = 'xtend.surface.operation-result.v1';
+const SURFACE_CONTROLLER_WORKPACKAGE = 'WP-SM-02';
+const SURFACE_CONTROLLER_STATUS = 'accepted-controller-contract';
+const SURFACE_CONTROLLER_TARGET = 'surface-controller-state-snapshot-ready';
+const SURFACE_CONTROLLER_MODULE = 'catalog/surface-manager-controller.js';
+const SURFACE_CONTROLLER_RUNTIME = 'components/xsurfacemanager-controller.js';
+const SURFACE_CONTROLLER_TYPES = 'components/xsurfacemanager-controller.d.ts';
+const SURFACE_CONTROLLER_SUITE = 'tests/components/surface_controller_suite.js';
+const SURFACE_CONTROLLER_PLAN = 'development/XTend-SurfaceManager-und-Multi-Window-Plan.md';
+const SURFACE_CONTROLLER_CONTRACT = 'development/XTend-SurfaceManager-Controller-und-State-Snapshot-Contract.md';
+const SURFACE_CONTROLLER_WORKPACKAGE_DOC = 'development/WP-SM-02-Surface-Controller-und-State-Snapshot-bauen.md';
+const SURFACE_CONTROLLER_DOCS = 'docs/surface-manager-controller.md';
+const SURFACE_CONTROLLER_LOCAL_GATE = 'node scripts/run_xtend_tests.js surface-controller --json';
+const SURFACE_CONTROLLER_PACKAGE_SCRIPT = 'npm run test:surface-controller';
+const NEXT_WORKPACKAGE = 'WP-SM-03';
+const NEXT_DECISION = 'x-surface-manager-window-runtime';
+
+const SOURCE_ARTIFACTS = Object.freeze([
+  'src/components/x-surface-manager/surface-record.ts',
+  'src/components/x-surface-manager/surface-layout.ts',
+  'src/components/x-surface-manager/surface-controller.ts'
+]);
+
+const REQUIRED_ARTIFACTS = Object.freeze([
+  SURFACE_CONTROLLER_MODULE,
+  SURFACE_CONTROLLER_RUNTIME,
+  SURFACE_CONTROLLER_TYPES,
+  SURFACE_CONTROLLER_SUITE,
+  SURFACE_CONTROLLER_CONTRACT,
+  SURFACE_CONTROLLER_WORKPACKAGE_DOC,
+  SURFACE_CONTROLLER_DOCS,
+  ...SOURCE_ARTIFACTS
+]);
+
+const REQUIRED_DOCS = Object.freeze([
+  SURFACE_CONTROLLER_PLAN,
+  SURFACE_CONTROLLER_CONTRACT,
+  SURFACE_CONTROLLER_WORKPACKAGE_DOC,
+  SURFACE_CONTROLLER_DOCS,
+  'development/XTend-SurfaceManager-Contract-und-RMT-Authoring-Model.md',
+  'docs/surface-manager-rmt-authoring.md',
+  'docs/xtend-fabric.md'
+]);
+
+const REQUIRED_METHODS = Object.freeze([
+  'registerSurface',
+  'openSurface',
+  'closeSurface',
+  'focusSurface',
+  'updateSurface',
+  'moveSurface',
+  'resizeSurface',
+  'minimizeSurface',
+  'maximizeSurface',
+  'restoreSurface',
+  'snapshot',
+  'dispose'
+]);
+
+const REQUIRED_STATE_KEYS = Object.freeze([
+  'xtend.surface.registry',
+  'xtend.surface.active',
+  'xtend.surface.<surfaceId>.state',
+  'xtend.surface.<surfaceId>.bounds',
+  'xtend.surface.<surfaceId>.lifecycle',
+  'xtend.surface.diagnostics',
+  'xtend.surface.snapshot'
+]);
+
+const REQUIRED_SURFACE_TYPES = Object.freeze([
+  'window',
+  'side-panel',
+  'modal',
+  'dialog',
+  'drawer',
+  'popover',
+  'tooltip'
+]);
+
+const REQUIRED_DIAGNOSTIC_CODES = Object.freeze([
+  'xtend.surface.controller.created',
+  'xtend.surface.registered',
+  'xtend.surface.opened',
+  'xtend.surface.closed',
+  'xtend.surface.focused',
+  'xtend.surface.updated',
+  'xtend.surface.moved',
+  'xtend.surface.resized',
+  'xtend.surface.minimized',
+  'xtend.surface.maximized',
+  'xtend.surface.restored',
+  'xtend.surface.snapshot',
+  'xtend.surface.disposed',
+  'xtend.surface.invalid-record',
+  'xtend.surface.not-found',
+  'xtend.surface.capability-refused',
+  'xtend.surface.state-mirror.failed',
+  'xtend.surface.fabric-diagnostic.failed'
+]);
+
+const REQUIRED_LANES = Object.freeze([
+  'user-blocking',
+  'visible',
+  'transition',
+  'diagnostics'
+]);
+
+function includesAll(values, required) {
+  return required.every((entry) => Array.isArray(values) && values.includes(entry));
+}
+
+function createSurfaceControllerPlan(options = {}) {
+  return {
+    schema: SURFACE_CONTROLLER_SCHEMA,
+    reportSchema: SURFACE_CONTROLLER_REPORT_SCHEMA,
+    recordSchema: SURFACE_RECORD_SCHEMA,
+    snapshotSchema: SURFACE_SNAPSHOT_SCHEMA,
+    diagnosticSchema: SURFACE_DIAGNOSTIC_SCHEMA,
+    operationResultSchema: SURFACE_OPERATION_RESULT_SCHEMA,
+    workpackage: SURFACE_CONTROLLER_WORKPACKAGE,
+    status: SURFACE_CONTROLLER_STATUS,
+    generatedAt: options.generatedAt || 'static-local',
+    targetReadiness: SURFACE_CONTROLLER_TARGET,
+    module: SURFACE_CONTROLLER_MODULE,
+    runtime: SURFACE_CONTROLLER_RUNTIME,
+    types: SURFACE_CONTROLLER_TYPES,
+    suite: SURFACE_CONTROLLER_SUITE,
+    planningDocument: SURFACE_CONTROLLER_PLAN,
+    contract: SURFACE_CONTROLLER_CONTRACT,
+    workpackageDocument: SURFACE_CONTROLLER_WORKPACKAGE_DOC,
+    docs: SURFACE_CONTROLLER_DOCS,
+    localGate: SURFACE_CONTROLLER_LOCAL_GATE,
+    packageScript: SURFACE_CONTROLLER_PACKAGE_SCRIPT,
+    sourceArtifacts: SOURCE_ARTIFACTS.slice(),
+    artifactPaths: REQUIRED_ARTIFACTS.slice(),
+    requiredDocs: REQUIRED_DOCS.slice(),
+    requiredMethods: REQUIRED_METHODS.slice(),
+    stateKeys: REQUIRED_STATE_KEYS.slice(),
+    surfaceTypes: REQUIRED_SURFACE_TYPES.slice(),
+    diagnosticCodes: REQUIRED_DIAGNOSTIC_CODES.slice(),
+    lanes: REQUIRED_LANES.slice(),
+    controllerModel: {
+      boundary: 'component-owned-controller',
+      runtimeArtifact: 'controller-only-no-custom-element',
+      rmtInputModel: 'metadata.surface-records-from-WP-SM-01',
+      statePolicy: 'digital-twin-ssot-with-xstate-mirror',
+      fabricPolicy: 'emit-diagnostics-consume-fabric-do-not-replace-fabric',
+      persistencePolicy: 'layout-state-only-no-content-payload',
+      loaderPolicy: 'deferred-to-WP-SM-03-custom-element-runtime'
+    },
+    featureFlags: {
+      customElementsImplemented: false,
+      visibleSurfaceChromeImplemented: false,
+      sidePanelRuntimeImplemented: false,
+      nativeSurfacesDomainImplemented: false,
+      browserRequiredInLocalGate: false,
+      externalNetworkAllowedInLocalGate: false,
+      runtimeHasDomDependency: false,
+      runtimeHasRmtKernelImport: false,
+      runtimeHasFabricHardDependency: false
+    },
+    snapshotShape: {
+      schema: SURFACE_SNAPSHOT_SCHEMA,
+      fields: [
+        'managerId',
+        'stateKey',
+        'activeSurfaceId',
+        'version',
+        'surfaceCount',
+        'openSurfaceCount',
+        'surfaces',
+        'stack',
+        'diagnostics',
+        'updatedAt'
+      ]
+    },
+    kernelBoundary: KERNEL_BOUNDARY,
+    nextWorkpackage: NEXT_WORKPACKAGE,
+    nextDecision: NEXT_DECISION
+  };
+}
+
+function validateSurfaceControllerPlan(plan = createSurfaceControllerPlan()) {
+  const errors = [];
+
+  if (!plan || plan.schema !== SURFACE_CONTROLLER_SCHEMA) errors.push(`schema must be ${SURFACE_CONTROLLER_SCHEMA}`);
+  if (!plan || plan.reportSchema !== SURFACE_CONTROLLER_REPORT_SCHEMA) errors.push(`reportSchema must be ${SURFACE_CONTROLLER_REPORT_SCHEMA}`);
+  if (!plan || plan.recordSchema !== SURFACE_RECORD_SCHEMA) errors.push(`recordSchema must be ${SURFACE_RECORD_SCHEMA}`);
+  if (!plan || plan.snapshotSchema !== SURFACE_SNAPSHOT_SCHEMA) errors.push(`snapshotSchema must be ${SURFACE_SNAPSHOT_SCHEMA}`);
+  if (!plan || plan.diagnosticSchema !== SURFACE_DIAGNOSTIC_SCHEMA) errors.push(`diagnosticSchema must be ${SURFACE_DIAGNOSTIC_SCHEMA}`);
+  if (!plan || plan.workpackage !== SURFACE_CONTROLLER_WORKPACKAGE) errors.push(`workpackage must be ${SURFACE_CONTROLLER_WORKPACKAGE}`);
+  if (!plan || plan.status !== SURFACE_CONTROLLER_STATUS) errors.push(`status must be ${SURFACE_CONTROLLER_STATUS}`);
+  if (!plan || plan.targetReadiness !== SURFACE_CONTROLLER_TARGET) errors.push(`targetReadiness must be ${SURFACE_CONTROLLER_TARGET}`);
+  if (!includesAll(plan && plan.requiredMethods, REQUIRED_METHODS)) errors.push('required methods missing');
+  if (!includesAll(plan && plan.stateKeys, REQUIRED_STATE_KEYS)) errors.push('required xstate mirror keys missing');
+  if (!includesAll(plan && plan.surfaceTypes, REQUIRED_SURFACE_TYPES)) errors.push('required surface types missing');
+  if (!includesAll(plan && plan.diagnosticCodes, REQUIRED_DIAGNOSTIC_CODES)) errors.push('required diagnostics missing');
+  if (!includesAll(plan && plan.lanes, REQUIRED_LANES)) errors.push('required lanes missing');
+  if (!plan || plan.featureFlags.runtimeHasDomDependency !== false) errors.push('runtime must stay DOM-free in WP-SM-02');
+  if (!plan || plan.featureFlags.runtimeHasRmtKernelImport !== false) errors.push('runtime must not import RMT kernel types');
+  if (!plan || plan.featureFlags.runtimeHasFabricHardDependency !== false) errors.push('runtime must not hard-depend on Fabric');
+  if (!plan || plan.featureFlags.customElementsImplemented !== false) errors.push('custom elements must remain WP-SM-03 scope');
+  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_CONTROLLER_REPORT_SCHEMA,
+    ok: errors.length === 0,
+    errors,
+    checkedAt: 'static-local',
+    workpackage: SURFACE_CONTROLLER_WORKPACKAGE,
+    targetReadiness: SURFACE_CONTROLLER_TARGET
+  };
+}
+
+function createSurfaceControllerReport(options = {}) {
+  const plan = options.plan || createSurfaceControllerPlan(options);
+  const validation = validateSurfaceControllerPlan(plan);
+
+  return {
+    schema: SURFACE_CONTROLLER_REPORT_SCHEMA,
+    ok: validation.ok,
+    errors: validation.errors,
+    workpackage: plan.workpackage,
+    status: plan.status,
+    targetReadiness: plan.targetReadiness,
+    methodCount: plan.requiredMethods.length,
+    stateKeyCount: plan.stateKeys.length,
+    surfaceTypeCount: plan.surfaceTypes.length,
+    diagnosticCount: plan.diagnosticCodes.length,
+    runtime: plan.runtime,
+    types: plan.types,
+    localGate: plan.localGate,
+    packageScript: plan.packageScript,
+    runtimeHasDomDependency: plan.featureFlags.runtimeHasDomDependency,
+    runtimeHasRmtKernelImport: plan.featureFlags.runtimeHasRmtKernelImport,
+    runtimeHasFabricHardDependency: plan.featureFlags.runtimeHasFabricHardDependency,
+    kernelBoundary: plan.kernelBoundary,
+    nextWorkpackage: plan.nextWorkpackage,
+    nextDecision: plan.nextDecision
+  };
+}
+
+module.exports = {
+  KERNEL_BOUNDARY,
+  NEXT_DECISION,
+  NEXT_WORKPACKAGE,
+  REQUIRED_ARTIFACTS,
+  REQUIRED_DIAGNOSTIC_CODES,
+  REQUIRED_DOCS,
+  REQUIRED_LANES,
+  REQUIRED_METHODS,
+  REQUIRED_STATE_KEYS,
+  REQUIRED_SURFACE_TYPES,
+  SOURCE_ARTIFACTS,
+  SURFACE_CONTROLLER_CONTRACT,
+  SURFACE_CONTROLLER_DIAGNOSTIC_SCHEMA: SURFACE_DIAGNOSTIC_SCHEMA,
+  SURFACE_CONTROLLER_DOCS,
+  SURFACE_CONTROLLER_LOCAL_GATE,
+  SURFACE_CONTROLLER_MODULE,
+  SURFACE_CONTROLLER_PACKAGE_SCRIPT,
+  SURFACE_CONTROLLER_PLAN,
+  SURFACE_CONTROLLER_REPORT_SCHEMA,
+  SURFACE_CONTROLLER_RUNTIME,
+  SURFACE_CONTROLLER_SCHEMA,
+  SURFACE_DIAGNOSTIC_SCHEMA,
+  SURFACE_CONTROLLER_SNAPSHOT_SCHEMA: SURFACE_SNAPSHOT_SCHEMA,
+  SURFACE_CONTROLLER_STATUS,
+  SURFACE_CONTROLLER_SUITE,
+  SURFACE_CONTROLLER_TARGET,
+  SURFACE_CONTROLLER_TYPES,
+  SURFACE_CONTROLLER_WORKPACKAGE,
+  SURFACE_CONTROLLER_WORKPACKAGE_DOC,
+  SURFACE_OPERATION_RESULT_SCHEMA,
+  SURFACE_RECORD_SCHEMA,
+  SURFACE_SNAPSHOT_SCHEMA,
+  createSurfaceControllerPlan,
+  createSurfaceControllerReport,
+  validateSurfaceControllerPlan
+};

package/catalog/surface-manager-layout-engines.d.ts

@@ -0,0 +1,32 @@
+import type {
+  XtendCatalogConstant,
+  XtendCatalogGate,
+  XtendCatalogOptions,
+  XtendCatalogPlan,
+  XtendCatalogRecord,
+  XtendCatalogReport
+} from './catalog-public-types';
+
+
+export declare const KERNEL_BOUNDARY: XtendCatalogConstant;
+export declare const LAYOUT_ENGINES: XtendCatalogConstant;
+export declare const LAYOUT_ENGINE_EVENTS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const MANAGER_METHODS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const REQUIRED_ARTIFACTS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_BACKLOG: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_DIAGNOSTIC_SCHEMA: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_DOCS: readonly XtendCatalogConstant[] | XtendCatalogConstant;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_FIXTURE: XtendCatalogConstant;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_LOCAL_GATE: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_MODULE: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_PACKAGE_SCRIPT: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_REPORT_SCHEMA: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_SCHEMA: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_STATUS: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_SUITE: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_TARGET: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_WORKPACKAGE: string;
+export declare const SURFACE_MANAGER_LAYOUT_ENGINE_WORKPACKAGE_DOC: XtendCatalogConstant;
+export declare function createSurfaceManagerLayoutEnginesPlan(options?: XtendCatalogOptions): XtendCatalogPlan;
+export declare function createSurfaceManagerLayoutEnginesReport(options?: XtendCatalogOptions): XtendCatalogReport;
+export declare function validateSurfaceManagerLayoutEnginesPlan(plan?: unknown): XtendCatalogReport;