@hyperfrontend/features 0.1.0 → 0.2.0

package/_dependencies/@hyperfrontend/nexus/index.cjs.js

@@ -11,6 +11,7 @@ const index_cjs_js$7 = require('../immutable-api-utils/built-in-copy/date/index.
 const index_cjs_js$8 = require('../immutable-api-utils/built-in-copy/console/index.cjs.js');
 const index_cjs_js$9 = require('../immutable-api-utils/built-in-copy/weak-set/index.cjs.js');
 const index_cjs_js$a = require('../json-utils/index.cjs.js');
+const index_cjs_js$b = require('../immutable-api-utils/built-in-copy/reflect/index.cjs.js');
 
 function uuidV4() {
     return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (char) => {
@@ -82,10 +83,10 @@ const invalidRequest = (deps) => (processId, error) => index_cjs_js$1.freeze({
     error,
 });
 
-const newMessage = (deps) => (data) => index_cjs_js$1.freeze({
+const newMessage = (deps) => (message) => index_cjs_js$1.freeze({
     type: ACTION_TYPES.NEW_MESSAGE,
     senderId: deps.getBrokerId(),
-    data,
+    data: message,
 });
 
 const openConnection = (deps) => (processId, security) => {
@@ -695,7 +696,7 @@ function send(channel, message) {
     if (!emittedTypes.includes(message.type)) {
         throw index_cjs_js$6.createError(`Cannot send message to ${state.name} channel. Message type '${message.type}' is not in the emitted actions of channel contract.`);
     }
-    const action = channel.actions.newMessage(message.data);
+    const action = channel.actions.newMessage(message);
     sendAction(channel, action);
     channel.notifyMessage(message);
 }
@@ -930,6 +931,7 @@ function createChannel(config, deps) {
         getName: () => state.name,
         getTarget: () => state.target,
         isActive: () => state.active,
+        getAcceptedTypes: () => state.acceptedActions,
         toJSON: () => ({
             id: state.id,
             name: state.name,
@@ -1158,12 +1160,22 @@ function handleAccept(context, message) {
     channel.notifyEvent('open', { origin: message.origin, contract });
 }
 
+function resolveChannel(registry, message) {
+    const source = message.source;
+    if (source) {
+        const channel = registry.getByWindow(source);
+        if (channel) {
+            return channel;
+        }
+    }
+    return registry.getById(message.data.senderId);
+}
+
 function handleCancel(context, message) {
     const { state, registry, processManager } = context;
     const action = message.data;
-    const senderId = action['senderId'];
     const processId = action['processId'];
-    const channel = (getById(registry, senderId) || processManager.get(processId));
+    const channel = (resolveChannel(registry, message) || processManager.get(processId));
     if (!channel) {
         return;
     }
@@ -1192,12 +1204,11 @@ function handleCancelAcknowledged(context, message) {
 function handleClose(context, message) {
     const { state, registry, processManager } = context;
     const action = message.data;
-    const senderId = action.senderId;
     if (!('processId' in action)) {
         return;
     }
     const processId = action.processId;
-    const channel = getById(registry, senderId);
+    const channel = resolveChannel(registry, message);
     if (!channel || !channel.isActive()) {
         return;
     }
@@ -1238,9 +1249,7 @@ function handleDeny(context, message) {
 
 function handleDestroy(context, message) {
     const { registry } = context;
-    const action = message.data;
-    const senderId = action.senderId;
-    const channel = getById(registry, senderId);
+    const channel = resolveChannel(registry, message);
     if (!channel) {
         return;
     }
@@ -1313,12 +1322,11 @@ function validateMessage(message) {
 function handleMessage(context, message) {
     const { state, registry, logger } = context;
     const action = message.data;
-    const senderId = action.senderId;
     if (!isActionWithData(action)) {
         return;
     }
     const messageData = action.data;
-    const channel = getById(registry, senderId);
+    const channel = resolveChannel(registry, message);
     if (!channel || !channel.isActive()) {
         return;
     }
@@ -1327,6 +1335,10 @@ function handleMessage(context, message) {
         logger.info(`${state.name} ignored message from ${channel.getName()}`);
         return;
     }
+    if (!channel.getAcceptedTypes().includes(messageData.type)) {
+        logger.info(`${state.name} dropped message type '${messageData.type}' not accepted by the ${channel.getName()} channel contract`);
+        return;
+    }
     channel.notifyMessage(messageData);
 }
 
@@ -1620,6 +1632,10 @@ function createBroker(config) {
     assertNoCircularRef(config.settings, 'config.settings');
     validateName(config.name);
     validateContract(config.contract);
+    const brokerWindow = config.window ?? (typeof window !== 'undefined' ? window : undefined);
+    if (!brokerWindow) {
+        throw index_cjs_js$6.createError('Cannot create broker: no window is available. Pass an explicit `window` in the broker config when running outside a browser environment.');
+    }
     const mergedSettings = {
         ...defaultBrokerSettings,
         ...config.settings,
@@ -1633,7 +1649,7 @@ function createBroker(config) {
     const state = {
         id: uuidV4(),
         name: config.name,
-        window: window,
+        window: brokerWindow,
         contract: config.contract,
         settings: mergedSettings,
         logger,
@@ -1686,9 +1702,7 @@ function createBroker(config) {
         }
         routeMessage(router, routingContext, event);
     };
-    if (typeof window !== 'undefined') {
-        window.addEventListener('message', onMessage);
-    }
+    brokerWindow.addEventListener('message', onMessage);
     const broker = {
         id: state.id,
         name: state.name,
@@ -1770,9 +1784,25 @@ const DEFAULT_CONTRACT = index_cjs_js$1.freeze({
         { type: 'ACK', description: 'Acknowledgment' },
     ]),
 });
-const broker = createBroker({
-    name: 'default-broker',
-    contract: DEFAULT_CONTRACT,
+
+let instance = null;
+function resolveBroker() {
+    if (!instance) {
+        instance = createBroker({
+            name: 'default-broker',
+            contract: DEFAULT_CONTRACT,
+        });
+    }
+    return instance;
+}
+const broker = new Proxy({}, {
+    get: (_target, property) => index_cjs_js$b.get(resolveBroker(), property),
+    has: (_target, property) => index_cjs_js$b.has(resolveBroker(), property),
+    ownKeys: () => index_cjs_js$b.ownKeys(resolveBroker()),
+    getOwnPropertyDescriptor: (_target, property) => {
+        const descriptor = index_cjs_js$b.getOwnPropertyDescriptor(resolveBroker(), property);
+        return descriptor ? { ...descriptor, configurable: true } : undefined;
+    },
 });
 
 exports.DEFAULT_CONTRACT = DEFAULT_CONTRACT;

package/_dependencies/@hyperfrontend/nexus/index.esm.js

@@ -9,6 +9,7 @@ import { dateNow } from '../immutable-api-utils/built-in-copy/date/index.esm.js'
 import { debug, info, log, warn, error } from '../immutable-api-utils/built-in-copy/console/index.esm.js';
 import { createWeakSet } from '../immutable-api-utils/built-in-copy/weak-set/index.esm.js';
 import { createValidator as createValidator$1 } from '../json-utils/index.esm.js';
+import { getOwnPropertyDescriptor, ownKeys, has, get } from '../immutable-api-utils/built-in-copy/reflect/index.esm.js';
 
 function uuidV4() {
     return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (char) => {
@@ -80,10 +81,10 @@ const invalidRequest = (deps) => (processId, error) => freeze({
     error,
 });
 
-const newMessage = (deps) => (data) => freeze({
+const newMessage = (deps) => (message) => freeze({
     type: ACTION_TYPES.NEW_MESSAGE,
     senderId: deps.getBrokerId(),
-    data,
+    data: message,
 });
 
 const openConnection = (deps) => (processId, security) => {
@@ -693,7 +694,7 @@ function send(channel, message) {
     if (!emittedTypes.includes(message.type)) {
         throw createError(`Cannot send message to ${state.name} channel. Message type '${message.type}' is not in the emitted actions of channel contract.`);
     }
-    const action = channel.actions.newMessage(message.data);
+    const action = channel.actions.newMessage(message);
     sendAction(channel, action);
     channel.notifyMessage(message);
 }
@@ -928,6 +929,7 @@ function createChannel(config, deps) {
         getName: () => state.name,
         getTarget: () => state.target,
         isActive: () => state.active,
+        getAcceptedTypes: () => state.acceptedActions,
         toJSON: () => ({
             id: state.id,
             name: state.name,
@@ -1156,12 +1158,22 @@ function handleAccept(context, message) {
     channel.notifyEvent('open', { origin: message.origin, contract });
 }
 
+function resolveChannel(registry, message) {
+    const source = message.source;
+    if (source) {
+        const channel = registry.getByWindow(source);
+        if (channel) {
+            return channel;
+        }
+    }
+    return registry.getById(message.data.senderId);
+}
+
 function handleCancel(context, message) {
     const { state, registry, processManager } = context;
     const action = message.data;
-    const senderId = action['senderId'];
     const processId = action['processId'];
-    const channel = (getById(registry, senderId) || processManager.get(processId));
+    const channel = (resolveChannel(registry, message) || processManager.get(processId));
     if (!channel) {
         return;
     }
@@ -1190,12 +1202,11 @@ function handleCancelAcknowledged(context, message) {
 function handleClose(context, message) {
     const { state, registry, processManager } = context;
     const action = message.data;
-    const senderId = action.senderId;
     if (!('processId' in action)) {
         return;
     }
     const processId = action.processId;
-    const channel = getById(registry, senderId);
+    const channel = resolveChannel(registry, message);
     if (!channel || !channel.isActive()) {
         return;
     }
@@ -1236,9 +1247,7 @@ function handleDeny(context, message) {
 
 function handleDestroy(context, message) {
     const { registry } = context;
-    const action = message.data;
-    const senderId = action.senderId;
-    const channel = getById(registry, senderId);
+    const channel = resolveChannel(registry, message);
     if (!channel) {
         return;
     }
@@ -1311,12 +1320,11 @@ function validateMessage(message) {
 function handleMessage(context, message) {
     const { state, registry, logger } = context;
     const action = message.data;
-    const senderId = action.senderId;
     if (!isActionWithData(action)) {
         return;
     }
     const messageData = action.data;
-    const channel = getById(registry, senderId);
+    const channel = resolveChannel(registry, message);
     if (!channel || !channel.isActive()) {
         return;
     }
@@ -1325,6 +1333,10 @@ function handleMessage(context, message) {
         logger.info(`${state.name} ignored message from ${channel.getName()}`);
         return;
     }
+    if (!channel.getAcceptedTypes().includes(messageData.type)) {
+        logger.info(`${state.name} dropped message type '${messageData.type}' not accepted by the ${channel.getName()} channel contract`);
+        return;
+    }
     channel.notifyMessage(messageData);
 }
 
@@ -1618,6 +1630,10 @@ function createBroker(config) {
     assertNoCircularRef(config.settings, 'config.settings');
     validateName(config.name);
     validateContract(config.contract);
+    const brokerWindow = config.window ?? (typeof window !== 'undefined' ? window : undefined);
+    if (!brokerWindow) {
+        throw createError('Cannot create broker: no window is available. Pass an explicit `window` in the broker config when running outside a browser environment.');
+    }
     const mergedSettings = {
         ...defaultBrokerSettings,
         ...config.settings,
@@ -1631,7 +1647,7 @@ function createBroker(config) {
     const state = {
         id: uuidV4(),
         name: config.name,
-        window: window,
+        window: brokerWindow,
         contract: config.contract,
         settings: mergedSettings,
         logger,
@@ -1684,9 +1700,7 @@ function createBroker(config) {
         }
         routeMessage(router, routingContext, event);
     };
-    if (typeof window !== 'undefined') {
-        window.addEventListener('message', onMessage);
-    }
+    brokerWindow.addEventListener('message', onMessage);
     const broker = {
         id: state.id,
         name: state.name,
@@ -1768,9 +1782,25 @@ const DEFAULT_CONTRACT = freeze({
         { type: 'ACK', description: 'Acknowledgment' },
     ]),
 });
-const broker = createBroker({
-    name: 'default-broker',
-    contract: DEFAULT_CONTRACT,
+
+let instance = null;
+function resolveBroker() {
+    if (!instance) {
+        instance = createBroker({
+            name: 'default-broker',
+            contract: DEFAULT_CONTRACT,
+        });
+    }
+    return instance;
+}
+const broker = new Proxy({}, {
+    get: (_target, property) => get(resolveBroker(), property),
+    has: (_target, property) => has(resolveBroker(), property),
+    ownKeys: () => ownKeys(resolveBroker()),
+    getOwnPropertyDescriptor: (_target, property) => {
+        const descriptor = getOwnPropertyDescriptor(resolveBroker(), property);
+        return descriptor ? { ...descriptor, configurable: true } : undefined;
+    },
 });
 
 export { DEFAULT_CONTRACT, createBroker, createChannel, createLogger, broker as defaultBroker, logAction, logEvent, mergeContracts };

package/_dependencies/@hyperfrontend/project-scope/core/fs/index.cjs.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const node_fs = require('node:fs');
+const node_path = require('node:path');
 const index_cjs_js$2 = require('../../../immutable-api-utils/built-in-copy/array/index.cjs.js');
 const index_cjs_js$4 = require('../../../immutable-api-utils/built-in-copy/console/index.cjs.js');
 const index_cjs_js$6 = require('../../../immutable-api-utils/built-in-copy/json/index.cjs.js');
@@ -271,6 +272,22 @@ function createFileSystemError(message, code, context) {
     });
     return error;
 }
+function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
+    if (!node_fs.existsSync(filePath)) {
+        fsLogger.debug('File not found', { path: filePath });
+        throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
+    }
+    try {
+        return node_fs.readFileSync(filePath, { encoding });
+    }
+    catch (error) {
+        fsLogger.warn('Failed to read file', { path: filePath });
+        throw createFileSystemError(`Failed to read file: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read', cause: error });
+    }
+}
 function readFileBuffer(filePath) {
     if (!isSafePath(filePath)) {
         throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
@@ -384,14 +401,59 @@ function removeDirectory(dirPath, options) {
 const fsTraversalLogger = createScopedLogger('project-scope:fs:traversal');
 
 const fsWriteLogger = createScopedLogger('project-scope:fs:write');
+function ensureDir(dirPath) {
+    if (!node_fs.existsSync(dirPath)) {
+        fsWriteLogger.debug('Creating directory recursively', { path: dirPath });
+        node_fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+function writeFileContent(filePath, content, options) {
+    try {
+        fsWriteLogger.debug('Writing file content', { path: filePath, size: content.length, encoding: options?.encoding ?? 'utf-8' });
+        ensureDir(node_path.dirname(filePath));
+        node_fs.writeFileSync(filePath, content, {
+            encoding: options?.encoding ?? 'utf-8',
+            mode: options?.mode,
+        });
+        fsWriteLogger.debug('File written successfully', { path: filePath });
+    }
+    catch (error) {
+        fsWriteLogger.warn('Failed to write file', { path: filePath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to write file: ${filePath}`, 'FS_WRITE_ERROR', { path: filePath, operation: 'write', cause: error });
+    }
+}
+function writeJsonFile(filePath, data, options) {
+    try {
+        fsWriteLogger.debug('Writing JSON file', { path: filePath, indent: options?.indent ?? 2 });
+        const indent = options?.indent ?? 2;
+        const content = index_cjs_js$6.stringify(data, null, indent) + '\n';
+        writeFileContent(filePath, content, options);
+        fsWriteLogger.debug('JSON file written successfully', { path: filePath });
+    }
+    catch (error) {
+        if (error?.code === 'FS_WRITE_ERROR') {
+            throw error;
+        }
+        fsWriteLogger.warn('Failed to write JSON file', { path: filePath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to write JSON file: ${filePath}`, 'FS_WRITE_ERROR', {
+            path: filePath,
+            operation: 'write',
+            cause: error,
+        });
+    }
+}
 
 exports.createDirectory = createDirectory;
 exports.createFileSystemError = createFileSystemError;
+exports.ensureDir = ensureDir;
 exports.exists = exists;
 exports.getFileStat = getFileStat;
 exports.isFile = isFile;
 exports.readFileBuffer = readFileBuffer;
+exports.readFileContent = readFileContent;
 exports.readFileIfExists = readFileIfExists;
 exports.readJsonFile = readJsonFile;
 exports.readJsonFileIfExists = readJsonFileIfExists;
 exports.removeDirectory = removeDirectory;
+exports.writeFileContent = writeFileContent;
+exports.writeJsonFile = writeJsonFile;

package/_dependencies/@hyperfrontend/project-scope/core/fs/index.esm.js

@@ -1,4 +1,5 @@
-import { existsSync, readFileSync, statSync, lstatSync, mkdirSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, statSync, lstatSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { isArray } from '../../../immutable-api-utils/built-in-copy/array/index.esm.js';
 import { debug, info, log, warn, error } from '../../../immutable-api-utils/built-in-copy/console/index.esm.js';
 import { stringify, parse } from '../../../immutable-api-utils/built-in-copy/json/index.esm.js';
@@ -269,6 +270,22 @@ function createFileSystemError(message, code, context) {
     });
     return error;
 }
+function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
+    if (!existsSync(filePath)) {
+        fsLogger.debug('File not found', { path: filePath });
+        throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
+    }
+    try {
+        return readFileSync(filePath, { encoding });
+    }
+    catch (error) {
+        fsLogger.warn('Failed to read file', { path: filePath });
+        throw createFileSystemError(`Failed to read file: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read', cause: error });
+    }
+}
 function readFileBuffer(filePath) {
     if (!isSafePath(filePath)) {
         throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
@@ -382,5 +399,46 @@ function removeDirectory(dirPath, options) {
 const fsTraversalLogger = createScopedLogger('project-scope:fs:traversal');
 
 const fsWriteLogger = createScopedLogger('project-scope:fs:write');
+function ensureDir(dirPath) {
+    if (!existsSync(dirPath)) {
+        fsWriteLogger.debug('Creating directory recursively', { path: dirPath });
+        mkdirSync(dirPath, { recursive: true });
+    }
+}
+function writeFileContent(filePath, content, options) {
+    try {
+        fsWriteLogger.debug('Writing file content', { path: filePath, size: content.length, encoding: options?.encoding ?? 'utf-8' });
+        ensureDir(dirname(filePath));
+        writeFileSync(filePath, content, {
+            encoding: options?.encoding ?? 'utf-8',
+            mode: options?.mode,
+        });
+        fsWriteLogger.debug('File written successfully', { path: filePath });
+    }
+    catch (error) {
+        fsWriteLogger.warn('Failed to write file', { path: filePath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to write file: ${filePath}`, 'FS_WRITE_ERROR', { path: filePath, operation: 'write', cause: error });
+    }
+}
+function writeJsonFile(filePath, data, options) {
+    try {
+        fsWriteLogger.debug('Writing JSON file', { path: filePath, indent: options?.indent ?? 2 });
+        const indent = options?.indent ?? 2;
+        const content = stringify(data, null, indent) + '\n';
+        writeFileContent(filePath, content, options);
+        fsWriteLogger.debug('JSON file written successfully', { path: filePath });
+    }
+    catch (error) {
+        if (error?.code === 'FS_WRITE_ERROR') {
+            throw error;
+        }
+        fsWriteLogger.warn('Failed to write JSON file', { path: filePath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to write JSON file: ${filePath}`, 'FS_WRITE_ERROR', {
+            path: filePath,
+            operation: 'write',
+            cause: error,
+        });
+    }
+}
 
-export { createDirectory, createFileSystemError, exists, getFileStat, isFile, readFileBuffer, readFileIfExists, readJsonFile, readJsonFileIfExists, removeDirectory };
+export { createDirectory, createFileSystemError, ensureDir, exists, getFileStat, isFile, readFileBuffer, readFileContent, readFileIfExists, readJsonFile, readJsonFileIfExists, removeDirectory, writeFileContent, writeJsonFile };

package/_shared/generators/feature/generate-feature-module/index.esm.js

@@ -1,13 +1,18 @@
 import { Mode } from '../../../../_dependencies/@hyperfrontend/project-scope/vfs/index.esm.js';
+import { isAbsolute, join, relative, dirname } from 'node:path';
 
 const MODULE_PATH = 'src/hyperfrontend.feature.ts';
-function toContractImportPath(contractPath) {
+function toContractImportPath(contractPath, treeRoot) {
     const withoutExtension = contractPath.replace(/\.(json|ts|js)$/, '');
-    return /^[./]/.test(withoutExtension) ? withoutExtension : `./${withoutExtension}`;
+    const target = isAbsolute(withoutExtension) ? withoutExtension : join(treeRoot, withoutExtension);
+    const specifier = relative(join(treeRoot, dirname(MODULE_PATH)), target)
+        .split('\\')
+        .join('/');
+    return specifier.startsWith('.') ? specifier : `./${specifier}`;
 }
-function buildFeatureModule(config, contract) {
+function buildFeatureModule(config, contract, treeRoot) {
     const handlers = contract.accepted
-        .map((action) => `feature.on('${action.type}', (data) => {\n  // todo: handle ${action.type}\n})`)
+        .map((action) => `feature.on('${action.type}', (_data: unknown) => {\n  // todo: handle ${action.type}\n})`)
         .join('\n\n');
     const emits = contract.emitted.map((action) => `// feature.send('${action.type}', undefined)`).join('\n');
     return `/**
@@ -20,7 +25,7 @@ function buildFeatureModule(config, contract) {
  * @module ${config.name}.feature
  */
 import { createFeature } from '@hyperfrontend/features/hostee'
-import contract from '${toContractImportPath(config.contract)}'
+import contract from '${toContractImportPath(config.contract, treeRoot)}'
 
 /** The ${config.name} feature handle; use it to send and receive contract actions. */
 export const feature = createFeature({ name: '${config.name}', contract })
@@ -32,7 +37,7 @@ ${emits}
 `;
 }
 function generateFeatureModule(config, contract, tree) {
-    tree.write(MODULE_PATH, buildFeatureModule(config, contract), { mode: Mode.SkipIfExists });
+    tree.write(MODULE_PATH, buildFeatureModule(config, contract, tree.root), { mode: Mode.SkipIfExists });
 }
 
 export { MODULE_PATH, toContractImportPath, buildFeatureModule, generateFeatureModule };

package/_shared/generators/metadata/generate-metadata/index.esm.js

@@ -9,6 +9,7 @@ function generateMetadata(config, contract, tree) {
         version: format(parseVersionStrict(config.version)),
         url: config.url,
         contract,
+        ...(config.protocol !== undefined && { protocol: config.protocol }),
         generatedBy: '@hyperfrontend/features',
     };
     tree.write(METADATA_PATH, `${stringify(metadata, null, 2)}\n`);

package/_shared/shared/control/index.cjs.js

@@ -8,15 +8,25 @@ const ControlType = index_cjs_js.freeze({
     Beat: '__hf:beat',
     /** Hostee-to-host content-size announcement. */
     Size: '__hf:size',
+    /** Correlated request envelope carrying a consumer request in either direction. */
+    Request: '__hf:request',
+    /** Correlated response envelope answering a request. */
+    Response: '__hf:response',
 });
 function isControlType(type) {
     return type.startsWith(CONTROL_PREFIX);
 }
 function withControlContract(contract) {
     // note: Fresh action literals per direction — sharing references across emitted/accepted trips nexus's circular-reference guard, which flags any repeated object.
+    const controlActions = () => [
+        { type: ControlType.Beat },
+        { type: ControlType.Size },
+        { type: ControlType.Request },
+        { type: ControlType.Response },
+    ];
     return {
-        emitted: [...contract.emitted, { type: ControlType.Beat }, { type: ControlType.Size }],
-        accepted: [...contract.accepted, { type: ControlType.Beat }, { type: ControlType.Size }],
+        emitted: [...contract.emitted, ...controlActions()],
+        accepted: [...contract.accepted, ...controlActions()],
     };
 }
 

package/_shared/shared/control/index.esm.js

@@ -6,15 +6,25 @@ const ControlType = freeze({
     Beat: '__hf:beat',
     /** Hostee-to-host content-size announcement. */
     Size: '__hf:size',
+    /** Correlated request envelope carrying a consumer request in either direction. */
+    Request: '__hf:request',
+    /** Correlated response envelope answering a request. */
+    Response: '__hf:response',
 });
 function isControlType(type) {
     return type.startsWith(CONTROL_PREFIX);
 }
 function withControlContract(contract) {
     // note: Fresh action literals per direction — sharing references across emitted/accepted trips nexus's circular-reference guard, which flags any repeated object.
+    const controlActions = () => [
+        { type: ControlType.Beat },
+        { type: ControlType.Size },
+        { type: ControlType.Request },
+        { type: ControlType.Response },
+    ];
     return {
-        emitted: [...contract.emitted, { type: ControlType.Beat }, { type: ControlType.Size }],
-        accepted: [...contract.accepted, { type: ControlType.Beat }, { type: ControlType.Size }],
+        emitted: [...contract.emitted, ...controlActions()],
+        accepted: [...contract.accepted, ...controlActions()],
     };
 }