@ccslabs/xtend 0.1.0-rc.1

package/xtend-builder/typing/rmt-shell-authoring-contract.js

@@ -0,0 +1,315 @@
+const RMT_SHELL_AUTHORING_SCHEMA = 'xtend.rmt.shell-authoring.v1';
+const RMT_SHELL_AUTHORING_REPORT_SCHEMA = 'xtend.rmt.shell-authoring-report.v1';
+const RMT_SHELL_AUTHORING_WORKPACKAGE = 'WP-E11-07';
+const RMT_SHELL_AUTHORING_CONTRACT_DOC = 'development/XTend-RMT-Shell-Authoring-fuer-Component-UX.md';
+const RMT_SHELL_AUTHORING_FIXTURE = 'tests/fixtures/rmt-shell-authoring-component-ux.rmt';
+const COMPONENT_CONTRACT_V2_SCHEMA = 'xtend.component.contract.v2';
+const COMPONENT_SHELL_CONTRACT_SCHEMA = 'xtend.component.shell.v1';
+const COMPONENT_STYLING_CONTRACT_SCHEMA = 'xtend.component.styling.v1';
+const RUNTIME_A11Y_CONTRACT_SCHEMA = 'xtend.component.runtime-a11y.v1';
+const COMPONENT_UX_PERFORMANCE_CONTRACT_SCHEMA = 'xtend.component.ux-performance.v1';
+const COMPONENT_NETWORK_CONTRACT_SCHEMA = 'xtend.component.network.v1';
+const RMT_STYLE_AUTHORING_SCHEMA = 'xtend.rmt.style-authoring.v1';
+const RMT_A11Y_AUTHORING_SCHEMA = 'xtend.rmt.a11y-authoring.v1';
+const RMT_PERFORMANCE_AUTHORING_SCHEMA = 'xtend.rmt.performance-authoring.v1';
+const RMT_NETWORK_AUTHORING_SCHEMA = 'xtend.rmt.component-network-authoring.v1';
+const FABRIC_BOUNDARY_SCHEMA = 'xtend.component.fabric-boundary.v2';
+const KERNEL_BOUNDARY = 'no-rmt-kernel-import-of-xtend-types';
+
+const RMT_SHELL_AUTHORING_REQUIRED_DOMAINS = [
+  'manifest',
+  'adapters',
+  'components',
+  'templates',
+  'shell',
+  'style',
+  'a11y',
+  'variants',
+  'density',
+  'events',
+  'commands',
+  'hydration',
+  'schedules',
+  'fabric',
+  'compatibility',
+  'docs',
+  'tests'
+];
+
+const RMT_SHELL_AUTHORING_FIELDS = [
+  'shell',
+  'style',
+  'a11y',
+  'commands',
+  'events',
+  'variants',
+  'density',
+  'hydration',
+  'schedule',
+  'fabric'
+];
+
+const RMT_SHELL_AUTHORING_REQUIRED_ADAPTERS = [
+  'xtend.component',
+  'xtend.xrouter',
+  'rmt.state-scheduler-diagnostics'
+];
+
+const RMT_SHELL_AUTHORING_REQUIRED_SCHEDULES = [
+  'component.shell.render',
+  'component.visible.mount',
+  'ui.user-blocking.input',
+  'route.transition.render',
+  'a11y.announce',
+  'diagnostics.snapshot'
+];
+
+const RMT_SHELL_AUTHORING_ASSERTIONS = [
+  'shell-first-authoring',
+  'style-token-authoring',
+  'runtime-a11y-authoring',
+  'command-event-network-binding',
+  'schedule-fabric-lane-binding',
+  'kernel-boundary-preserved',
+  'host-neutral-adapters',
+  'no-inline-runtime-code',
+  'density-theme-propagation',
+  'validation-fixture-resolves'
+];
+
+function normalizeArray(value) {
+  return Array.isArray(value) ? value.slice() : [];
+}
+
+function unique(values) {
+  return Array.from(new Set(normalizeArray(values).filter(Boolean)));
+}
+
+function createAdapterRecord(id, capabilities) {
+  return {
+    id,
+    kernelVisible: false,
+    capabilities: unique(capabilities)
+  };
+}
+
+function createScheduleRecord(id, lane, endpointName) {
+  return {
+    id,
+    lane,
+    endpointName,
+    kernelVisible: true,
+    fabricCorrelationRequired: true
+  };
+}
+
+function createRmtShellAuthoringContract(input = {}) {
+  const documentId = input.documentId || 'fixture.xtend.component-ux-shell-authoring';
+  const authoringFields = unique(RMT_SHELL_AUTHORING_FIELDS.concat(normalizeArray(input.authoringFields)));
+  const requiredSchedules = unique(RMT_SHELL_AUTHORING_REQUIRED_SCHEDULES.concat(normalizeArray(input.requiredSchedules)));
+
+  return {
+    schema: RMT_SHELL_AUTHORING_SCHEMA,
+    status: 'contract-draft',
+    workpackage: RMT_SHELL_AUTHORING_WORKPACKAGE,
+    componentContract: COMPONENT_CONTRACT_V2_SCHEMA,
+    shellContract: COMPONENT_SHELL_CONTRACT_SCHEMA,
+    stylingContract: COMPONENT_STYLING_CONTRACT_SCHEMA,
+    runtimeA11yContract: RUNTIME_A11Y_CONTRACT_SCHEMA,
+    uxPerformanceContract: COMPONENT_UX_PERFORMANCE_CONTRACT_SCHEMA,
+    componentNetworkContract: COMPONENT_NETWORK_CONTRACT_SCHEMA,
+    rmtStyleAuthoring: RMT_STYLE_AUTHORING_SCHEMA,
+    rmtA11yAuthoring: RMT_A11Y_AUTHORING_SCHEMA,
+    rmtPerformanceAuthoring: RMT_PERFORMANCE_AUTHORING_SCHEMA,
+    rmtNetworkAuthoring: RMT_NETWORK_AUTHORING_SCHEMA,
+    fabricBoundary: FABRIC_BOUNDARY_SCHEMA,
+    manifest: {
+      documentId,
+      renderMode: 'shell-first',
+      componentAdapter: 'xtend.component',
+      routerAdapter: 'xtend.xrouter',
+      kernelBoundary: KERNEL_BOUNDARY
+    },
+    adapters: [
+      createAdapterRecord('xtend.component', ['shell', 'style', 'a11y', 'commands', 'events', 'variants', 'density', 'hydration', 'scheduleRefs', 'fabric']),
+      createAdapterRecord('xtend.xrouter', ['routes', 'navigation', 'activeState', 'focusRestore', 'announcements']),
+      createAdapterRecord('rmt.state-scheduler-diagnostics', ['schedules', 'lanes', 'diagnostics', 'performanceBudgets', 'telemetry'])
+    ],
+    components: {
+      requiredFields: ['id', 'adapter', 'tag', 'template', 'schedule', 'shell', 'style', 'a11y', 'events', 'commands', 'hydration', 'fabric'],
+      adapter: 'xtend.component',
+      templateMode: 'dom_descriptor',
+      noInlineRuntimeCode: true
+    },
+    templates: {
+      mode: 'dom_descriptor',
+      shellFirst: true,
+      allowedNodeKinds: ['element', 'text', 'component', 'slot'],
+      noScriptNodes: true
+    },
+    shell: {
+      fields: ['domMode', 'state', 'slots', 'parts', 'focus', 'attributes'],
+      requiredStates: ['empty', 'loading', 'ready', 'error', 'disabled', 'busy', 'invalid'],
+      slotRefsMustResolve: true
+    },
+    style: {
+      schema: RMT_STYLE_AUTHORING_SCHEMA,
+      fields: ['tokens', 'parts', 'variant', 'size', 'density', 'theme', 'motion', 'contrast'],
+      tokensOnlyInlinePolicy: true
+    },
+    a11y: {
+      schema: RMT_A11Y_AUTHORING_SCHEMA,
+      fields: ['role', 'label', 'description', 'live', 'keyboard', 'focus', 'announcements'],
+      runtimeBehaviorRequired: true
+    },
+    variants: {
+      allowed: ['default', 'primary', 'secondary', 'success', 'warning', 'danger', 'neutral'],
+      unknownPolicy: 'ignore-and-diagnose'
+    },
+    density: {
+      allowed: ['comfortable', 'compact', 'dense'],
+      propagation: 'theme-context-and-component-record'
+    },
+    events: {
+      bindingMode: 'dom-event-to-rmt-command',
+      requiredPropagation: 'bubbles-composed',
+      networkSchema: RMT_NETWORK_AUTHORING_SCHEMA
+    },
+    commands: {
+      invocation: 'rmt-command-to-host-adapter',
+      diagnosticsFirst: true,
+      noThrowAcrossBoundary: true
+    },
+    hydration: {
+      policies: ['visible', 'idle', 'lazy', 'visible-or-idle'],
+      scheduleFieldRequired: true,
+      ownershipModes: ['managed_subtree', 'adapter_owned_dom']
+    },
+    schedules: {
+      required: requiredSchedules.map((id) => {
+        if (id === 'ui.user-blocking.input') return createScheduleRecord(id, 'user-blocking', 'xtendrmt.ui.user-blocking');
+        if (id === 'route.transition.render') return createScheduleRecord(id, 'transition', 'xtendrmt.route.render');
+        if (id === 'a11y.announce') return createScheduleRecord(id, 'a11y', 'xtendrmt.a11y.announce');
+        if (id === 'diagnostics.snapshot') return createScheduleRecord(id, 'diagnostics', 'xtendrmt.diagnostics.snapshot');
+        if (id === 'component.visible.mount') return createScheduleRecord(id, 'visible', 'xtendrmt.component.mount');
+        return createScheduleRecord(id, 'visible', 'xtendrmt.shell.render');
+      }),
+      performanceSchema: RMT_PERFORMANCE_AUTHORING_SCHEMA
+    },
+    fabric: {
+      schema: FABRIC_BOUNDARY_SCHEMA,
+      laneFieldsRequired: true,
+      telemetryCorrelationRequired: true,
+      diagnostics: ['rmt.shell.field.missing', 'rmt.shell.event.unbound', 'rmt.shell.schedule.unresolved', 'rmt.shell.kernel-boundary.refused']
+    },
+    compatibility: {
+      hostModes: ['xtend-only', 'rmt-first', 'vanilla', 'react', 'vue', 'custom-shell'],
+      kernelImportsXtendTypes: false,
+      noRuntimeEval: true,
+      noCdnDependency: true
+    },
+    docs: {
+      contract: RMT_SHELL_AUTHORING_CONTRACT_DOC,
+      fixture: RMT_SHELL_AUTHORING_FIXTURE,
+      requiredSections: ['Shell', 'Style', 'A11y', 'Events', 'Commands', 'Hydration', 'Schedules', 'Fabric', 'Kernel Boundary']
+    },
+    tests: {
+      requiredSuites: ['rmt-shell-authoring-ux', 'component-shell-contract', 'component-styling-contract', 'runtime-a11y-contract', 'component-ux-performance', 'component-network-contract', 'references'],
+      assertions: RMT_SHELL_AUTHORING_ASSERTIONS.slice(),
+      fixtureRequired: true
+    },
+    authoringFields,
+    requiredDomains: RMT_SHELL_AUTHORING_REQUIRED_DOMAINS.slice()
+  };
+}
+
+function validateRmtShellAuthoringContract(contract = {}) {
+  const errors = [];
+
+  if (contract.schema !== RMT_SHELL_AUTHORING_SCHEMA) {
+    errors.push(`schema must be ${RMT_SHELL_AUTHORING_SCHEMA}`);
+  }
+  RMT_SHELL_AUTHORING_REQUIRED_DOMAINS.forEach((domain) => {
+    if (!contract[domain]) {
+      errors.push(`missing domain: ${domain}`);
+    }
+  });
+  if (!contract.manifest || contract.manifest.renderMode !== 'shell-first') {
+    errors.push('manifest.renderMode must be shell-first');
+  }
+  if (!contract.manifest || contract.manifest.kernelBoundary !== KERNEL_BOUNDARY) {
+    errors.push('manifest.kernelBoundary must preserve the RMT/XTend boundary');
+  }
+  if (!Array.isArray(contract.adapters) || !RMT_SHELL_AUTHORING_REQUIRED_ADAPTERS.every((id) => contract.adapters.some((adapter) => adapter.id === id && adapter.kernelVisible === false))) {
+    errors.push(`adapters must include host-neutral adapters: ${RMT_SHELL_AUTHORING_REQUIRED_ADAPTERS.join(', ')}`);
+  }
+  if (!Array.isArray(contract.authoringFields) || !RMT_SHELL_AUTHORING_FIELDS.every((field) => contract.authoringFields.includes(field))) {
+    errors.push(`authoringFields must include: ${RMT_SHELL_AUTHORING_FIELDS.join(', ')}`);
+  }
+  if (!contract.components || contract.components.noInlineRuntimeCode !== true) {
+    errors.push('components.noInlineRuntimeCode must be true');
+  }
+  if (!contract.templates || contract.templates.shellFirst !== true || contract.templates.noScriptNodes !== true) {
+    errors.push('templates must be shell-first and refuse script nodes');
+  }
+  if (!contract.style || contract.style.tokensOnlyInlinePolicy !== true) {
+    errors.push('style.tokensOnlyInlinePolicy must be true');
+  }
+  if (!contract.a11y || contract.a11y.runtimeBehaviorRequired !== true) {
+    errors.push('a11y.runtimeBehaviorRequired must be true');
+  }
+  if (!contract.events || contract.events.bindingMode !== 'dom-event-to-rmt-command') {
+    errors.push('events.bindingMode must be dom-event-to-rmt-command');
+  }
+  if (!contract.commands || contract.commands.diagnosticsFirst !== true) {
+    errors.push('commands.diagnosticsFirst must be true');
+  }
+  if (!contract.hydration || contract.hydration.scheduleFieldRequired !== true) {
+    errors.push('hydration.scheduleFieldRequired must be true');
+  }
+  if (!contract.schedules || !Array.isArray(contract.schedules.required) || !RMT_SHELL_AUTHORING_REQUIRED_SCHEDULES.every((id) => contract.schedules.required.some((schedule) => schedule.id === id))) {
+    errors.push(`schedules.required must include: ${RMT_SHELL_AUTHORING_REQUIRED_SCHEDULES.join(', ')}`);
+  }
+  if (!contract.fabric || contract.fabric.telemetryCorrelationRequired !== true) {
+    errors.push('fabric.telemetryCorrelationRequired must be true');
+  }
+  if (!contract.compatibility || contract.compatibility.kernelImportsXtendTypes !== false) {
+    errors.push('compatibility.kernelImportsXtendTypes must be false');
+  }
+  if (!contract.tests || !normalizeArray(contract.tests.requiredSuites).includes('rmt-shell-authoring-ux')) {
+    errors.push('tests.requiredSuites must include rmt-shell-authoring-ux');
+  }
+
+  return {
+    schema: RMT_SHELL_AUTHORING_REPORT_SCHEMA,
+    ok: errors.length === 0,
+    errors
+  };
+}
+
+module.exports = {
+  COMPONENT_CONTRACT_V2_SCHEMA,
+  COMPONENT_NETWORK_CONTRACT_SCHEMA,
+  COMPONENT_SHELL_CONTRACT_SCHEMA,
+  COMPONENT_STYLING_CONTRACT_SCHEMA,
+  COMPONENT_UX_PERFORMANCE_CONTRACT_SCHEMA,
+  FABRIC_BOUNDARY_SCHEMA,
+  KERNEL_BOUNDARY,
+  RMT_A11Y_AUTHORING_SCHEMA,
+  RMT_NETWORK_AUTHORING_SCHEMA,
+  RMT_PERFORMANCE_AUTHORING_SCHEMA,
+  RMT_SHELL_AUTHORING_ASSERTIONS,
+  RMT_SHELL_AUTHORING_CONTRACT_DOC,
+  RMT_SHELL_AUTHORING_FIELDS,
+  RMT_SHELL_AUTHORING_FIXTURE,
+  RMT_SHELL_AUTHORING_REPORT_SCHEMA,
+  RMT_SHELL_AUTHORING_REQUIRED_ADAPTERS,
+  RMT_SHELL_AUTHORING_REQUIRED_DOMAINS,
+  RMT_SHELL_AUTHORING_REQUIRED_SCHEDULES,
+  RMT_SHELL_AUTHORING_SCHEMA,
+  RMT_SHELL_AUTHORING_WORKPACKAGE,
+  RMT_STYLE_AUTHORING_SCHEMA,
+  RUNTIME_A11Y_CONTRACT_SCHEMA,
+  createRmtShellAuthoringContract,
+  validateRmtShellAuthoringContract
+};

package/xtend-builder/utils/README.md

@@ -0,0 +1,8 @@
+# XTend-Scaffold Utils
+
+Dieser Bereich enthaelt pure Helfer fuer `XTend-Scaffold`.
+
+- `naming.js`: Tag-Normalisierung, Komponentenname, Klassenname und Tokenersetzung
+- `validation.js`: deterministische Eingabevalidierung fuer Component-Plans
+
+Grenze in `WP-E03-04`: Helfer duerfen Pfade, Validierung, Plan-Ausgabe und spaeter Konfliktpruefung kapseln, aber keine versteckten Schreibzugriffe einfuehren.

package/xtend-builder/utils/naming.d.ts

@@ -0,0 +1,7 @@
+import type { XtendBuilderRecord } from '../builder-public-types';
+
+export declare function getClassNameFromTag(tag: string): string;
+export declare function getComponentNameFromTag(tag: string): string;
+export declare function normalizeTag(tag: string): string;
+export declare function replaceArtifactTokens(template: string, values?: XtendBuilderRecord): string;
+export declare function toPascalCase(value: string): string;

package/xtend-builder/utils/naming.js

@@ -0,0 +1,36 @@
+function normalizeTag(tag) {
+  return String(tag || '').trim().toLowerCase();
+}
+
+function getComponentNameFromTag(tag) {
+  const normalized = normalizeTag(tag);
+  return normalized.startsWith('x-') ? normalized.slice(2) : normalized;
+}
+
+function toPascalCase(value) {
+  return String(value || '')
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join('');
+}
+
+function getClassNameFromTag(tag) {
+  const name = getComponentNameFromTag(tag);
+  return `X${toPascalCase(name)}`;
+}
+
+function replaceArtifactTokens(template, values) {
+  return String(template || '')
+    .replace(/<tag>/g, values.tag)
+    .replace(/<name>/g, values.name)
+    .replace(/<className>/g, values.className);
+}
+
+module.exports = {
+  getClassNameFromTag,
+  getComponentNameFromTag,
+  normalizeTag,
+  replaceArtifactTokens,
+  toPascalCase
+};

package/xtend-builder/utils/validation.d.ts

@@ -0,0 +1,5 @@
+import type { XtendBuilderComponentInput, XtendBuilderOptions, XtendBuilderRecord } from '../builder-public-types';
+
+export declare const ALLOWED_FEATURES: string[];
+export declare function normalizeList(value?: string | string[]): string[];
+export declare function validateComponentPlanInput(input?: XtendBuilderComponentInput, options?: XtendBuilderOptions): { ok: boolean; value?: XtendBuilderRecord; errors: string[] };

package/xtend-builder/utils/validation.js

@@ -0,0 +1,95 @@
+const config = require('../scaffold.config');
+const {
+  getComponentBlueprintContract
+} = require('../blueprints/component-blueprint.contract');
+const {
+  getComponentNameFromTag,
+  normalizeTag
+} = require('./naming');
+
+const ALLOWED_FEATURES = [
+  'accessibility',
+  'css',
+  'demo',
+  'docs',
+  'events',
+  'fixtures',
+  'manifest',
+  'slots',
+  'state',
+  'types'
+];
+
+function normalizeList(value) {
+  if (Array.isArray(value)) {
+    return value.flatMap(normalizeList);
+  }
+
+  if (typeof value !== 'string') {
+    return [];
+  }
+
+  return value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function unique(values) {
+  return Array.from(new Set(values));
+}
+
+function validateComponentPlanInput(input = {}, options = {}) {
+  const scaffoldConfig = options.config || config;
+  const blueprint = options.blueprint || getComponentBlueprintContract();
+  const errors = [];
+  const tag = normalizeTag(input.tag || input.name || '');
+  const profiles = unique(normalizeList(input.profile || input.profiles));
+  const features = unique(normalizeList(input.feature || input.features));
+  const profileNames = Array.isArray(blueprint.profiles) ? blueprint.profiles.map((profile) => profile.profile) : [];
+  const tagPattern = new RegExp(scaffoldConfig.namingConventions.componentTagPattern);
+
+  if (!tag) {
+    errors.push('Missing required --tag <x-name> input.');
+  } else if (!tagPattern.test(tag)) {
+    errors.push(`Invalid component tag "${tag}". Expected pattern ${scaffoldConfig.namingConventions.componentTagPattern}.`);
+  }
+
+  if (profiles.length === 0) {
+    errors.push('Missing required --profile <profile> input.');
+  }
+
+  profiles.forEach((profile) => {
+    if (!profileNames.includes(profile)) {
+      errors.push(`Invalid component profile "${profile}". Allowed profiles: ${profileNames.join(', ')}.`);
+    }
+  });
+
+  features.forEach((feature) => {
+    if (!ALLOWED_FEATURES.includes(feature)) {
+      errors.push(`Invalid feature "${feature}". Allowed features: ${ALLOWED_FEATURES.join(', ')}.`);
+    }
+  });
+
+  const name = input.componentName ? String(input.componentName).trim() : getComponentNameFromTag(tag);
+  if (!name && tag) {
+    errors.push(`Unable to derive component name from tag "${tag}".`);
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    value: {
+      tag,
+      name,
+      profiles,
+      features
+    }
+  };
+}
+
+module.exports = {
+  ALLOWED_FEATURES,
+  normalizeList,
+  validateComponentPlanInput
+};

package/xtend-builder/wiring/README.md

@@ -0,0 +1,46 @@
+# XTend-Scaffold Wiring
+
+Dieser Bereich enthaelt ab `WP-E03-06` die repo-lokalen Wiring-Contracts fuer Manifest und Hydration.
+
+## Manifest-Wiring
+
+`xtend-builder/wiring/manifest.js` erzeugt einen deterministischen Patch-Plan mit Schema `xtend.scaffold.manifest-wiring.v1`.
+
+Der Patch-Plan bleibt in Epic 03 dry-run-first:
+
+- Ziel ist `components/manifest.json`
+- Quellen werden als repo-relative Pfade wie `components/x-example.js` ausgegeben
+- `localImportOnly` ist `true`
+- `cdnAllowed` ist `false`
+- produktive Manifest-Schreiblogik bleibt einem spaeteren Workpackage vorbehalten
+
+## Hydration-Wiring
+
+`xtend-builder/wiring/hydration.js` erzeugt den Mindestcontract mit Schema `xtend.scaffold.hydration-wiring.v1`.
+
+Der Contract verlangt:
+
+- `connectedCallback`
+- `attributeChangedCallback`
+- `disconnectedCallback`
+- einen expliziten `hydrate()`-Pfad
+- ein Fixture-Ergebnisobjekt mit `defined`, `hasElement`, `hasShadowRoot` und `hydrated`
+
+## Feature-Wiring
+
+`xtend-builder/wiring/features.js` erzeugt profilbasierte State-, Event- und API-Patterns mit Schema `xtend.scaffold.feature-wiring.v1`.
+
+Der Contract verlangt:
+
+- kanonische State-Keys unter `xtend.component.<tag>.<id>.` oder bestehenden Core-Namespaces wie `xtend.router.*`
+- `xstate.subscribe(fn, keyFilter?)` als kanonischen Subscription-Pfad
+- `xstate.set(key, value)` als Schreibpfad
+- Custom Events mit lesbaren `<domain>-<action>` Namen
+- bevorzugte API-Hinweise unter `window.XTend.*`
+- keine direkten `xstate.on/off` Aufrufe in generierten Patterns
+- keine neuen unnamespaced `window.show*` Helper
+- lokale UI-Felder nur als abgeleitete Render-Caches
+
+## Grenze
+
+Die Wiring-Module sind reine Builder-Contracts. Sie duerfen keine Runtime registrieren, keine Produktivdateien schreiben und keine externen Quellen laden.

package/xtend-builder/wiring/features.d.ts

@@ -0,0 +1,5 @@
+import type { XtendBuilderComponentInput, XtendBuilderRecord } from '../builder-public-types';
+
+export declare const FEATURE_PROFILE_RULES: XtendBuilderRecord;
+export declare const FEATURE_WIRING_SCHEMA: string;
+export declare function createFeatureWiring(input?: XtendBuilderComponentInput): XtendBuilderRecord;

package/xtend-builder/wiring/features.js

@@ -0,0 +1,165 @@
+const FEATURE_WIRING_SCHEMA = 'xtend.scaffold.feature-wiring.v1';
+
+const FEATURE_PROFILE_RULES = {
+  display: {
+    stateKeys: ['ready'],
+    events: ['ready'],
+    apiNamespaces: [],
+    reviewChecks: ['visible-dom', 'hydration-baseline']
+  },
+  interactive: {
+    stateKeys: ['active'],
+    events: ['activated', 'changed'],
+    apiNamespaces: [],
+    reviewChecks: ['keyboard', 'focus', 'event-contract']
+  },
+  stateful: {
+    stateKeys: ['value', 'ready'],
+    events: ['changed'],
+    apiNamespaces: [],
+    reviewChecks: ['canonical-xstate-key', 'xstate.subscribe', 'ssot-boundary']
+  },
+  feedback: {
+    stateKeys: ['visible', 'dismissed'],
+    events: ['shown', 'dismissed'],
+    apiNamespaces: ['window.XTend.alert', 'window.XTend.toast'],
+    reviewChecks: ['live-region', 'dismissal', 'timer-cleanup']
+  },
+  overlay: {
+    stateKeys: ['open'],
+    events: ['opened', 'closed'],
+    apiNamespaces: ['window.XTend.dialog', 'window.XTend.modal'],
+    reviewChecks: ['open-state', 'focus-return', 'state-writeback']
+  },
+  routing: {
+    stateKeys: ['xtend.router.lastNavigated', 'xtend.router.current', 'xtend.router.lastRendered'],
+    events: ['route-changed'],
+    apiNamespaces: ['window.XTend.router'],
+    reviewChecks: ['router-navigate', 'xstate-bridge', 'route-events']
+  },
+  theme: {
+    stateKeys: ['xtend.theme.current', 'xtend.theme.available'],
+    events: ['theme-changed'],
+    apiNamespaces: ['window.XTend.theme'],
+    reviewChecks: ['theme-state', 'css-custom-properties', 'legacy-facade-boundary']
+  },
+  form: {
+    stateKeys: ['value', 'validity', 'error'],
+    events: ['changed', 'submitted', 'invalid'],
+    apiNamespaces: [],
+    reviewChecks: ['value-contract', 'validation', 'labels']
+  },
+  media: {
+    stateKeys: ['loading', 'ready', 'error'],
+    events: ['loaded', 'error'],
+    apiNamespaces: [],
+    reviewChecks: ['loading-state', 'fallbacks', 'reduced-motion']
+  }
+};
+
+function unique(values) {
+  return Array.from(new Set(values.filter(Boolean)));
+}
+
+function getDomainFromTag(tag) {
+  return String(tag || '').replace(/^x-/, '');
+}
+
+function toStateKey(prefix, key) {
+  return key.startsWith('xtend.') ? key : `${prefix}${key}`;
+}
+
+function toEventName(domain, action) {
+  return action.includes('-') ? action : `${domain}-${action}`;
+}
+
+function collectProfileRules(profiles) {
+  return profiles
+    .map((profile) => ({
+      profile,
+      rule: FEATURE_PROFILE_RULES[profile] || FEATURE_PROFILE_RULES.display
+    }));
+}
+
+function createFeatureWiring(input = {}) {
+  const tag = String(input.tag || '').trim();
+  const profiles = Array.isArray(input.profiles) && input.profiles.length > 0 ? input.profiles.slice() : ['display'];
+  const features = Array.isArray(input.features) ? input.features.slice() : [];
+  const domain = getDomainFromTag(tag);
+  const statePrefix = `xtend.component.${tag}.<id>.`;
+  const profileRules = collectProfileRules(profiles);
+  const stateRequested = features.includes('state') || profileRules.some((entry) => entry.rule.stateKeys.length > 0);
+  const eventsRequested = features.includes('events') || profileRules.some((entry) => entry.rule.events.length > 0);
+  const stateKeys = stateRequested
+    ? unique(profileRules.flatMap((entry) => entry.rule.stateKeys).map((key) => toStateKey(statePrefix, key)))
+    : [];
+  const eventNames = eventsRequested
+    ? unique(profileRules.flatMap((entry) => entry.rule.events).map((event) => toEventName(domain, event)))
+    : [];
+  const apiNamespaces = unique([
+    `window.XTend.components['${tag}']`,
+    ...profileRules.flatMap((entry) => entry.rule.apiNamespaces)
+  ]);
+
+  return {
+    schema: FEATURE_WIRING_SCHEMA,
+    ok: Boolean(tag),
+    mode: 'dry-run',
+    selected: {
+      profiles,
+      features
+    },
+    state: {
+      enabled: stateRequested,
+      source: 'xstate',
+      prefix: statePrefix,
+      keys: stateKeys,
+      read: 'xstate.get(key)',
+      write: 'xstate.set(key, value)',
+      subscribe: 'xstate.subscribe(fn, keyFilter?)',
+      forbidden: ['xstate.on', 'xstate.off'],
+      localUiPolicy: 'derived-render-cache-only'
+    },
+    events: {
+      enabled: eventsRequested,
+      names: eventNames,
+      detailShape: {
+        id: 'string',
+        stateKey: 'string | undefined',
+        value: 'unknown',
+        source: tag
+      },
+      dispatchOptions: {
+        bubbles: true,
+        composed: true
+      }
+    },
+    api: {
+      enabled: apiNamespaces.length > 0,
+      namespaceRoot: 'window.XTend',
+      namespaces: apiNamespaces,
+      forbiddenGlobals: [`window.show${input.className || ''}`],
+      registration: 'optional-review-only'
+    },
+    profiles: profileRules.map((entry) => ({
+      profile: entry.profile,
+      stateKeys: entry.rule.stateKeys.map((key) => toStateKey(statePrefix, key)),
+      events: entry.rule.events.map((event) => toEventName(domain, event)),
+      apiNamespaces: entry.rule.apiNamespaces.slice(),
+      reviewChecks: entry.rule.reviewChecks.slice()
+    })),
+    reviewRules: [
+      'Generated state patterns must use canonical xtend.* keys.',
+      'Stateful patterns must use xstate.subscribe(fn, keyFilter?) and must not call xstate.on/off directly.',
+      'Generated UI fields may only be derived render caches, never a second source of truth.',
+      'Generated API hints must prefer window.XTend.* and must not create new unnamespaced window.show* helpers.',
+      'Feature wiring remains profile-driven and optional until productive generator writes are introduced.'
+    ]
+  };
+}
+
+module.exports = {
+  FEATURE_PROFILE_RULES,
+  FEATURE_WIRING_SCHEMA,
+  createFeatureWiring
+};